Repository navigation
Components Variants and Slots
PixlPrfct components are ordinary frames tagged as a main (Component::Master) whose linked instances are full copies of the main's subtree, rebuilt by the Rust engine on every commit. Each instance layer records which main layer it mirrors (source) and a list of string override paths; everything not listed is re-copied from the main. Variant sets, component properties and slots are document-level definitions (component_sets, component_properties) layered on top of that one link model. The single most important thing to know: components::sync in src/components.rs regenerates every instance subtree inside commit_validated_document, so any engine change that touches shapes must keep source links, override paths and stable instance IDs coherent, or the next commit will silently discard data.
| Key files | Entry points | Depends on | Used by | Related docs |
|---|---|---|---|---|
| src/components.rs, src/variants.rs, src/component_properties.rs, src/slots.rs; web/variants.js, web/component-properties.js, web/slots.js, web/instance-context.js, web/assets.js, web/asset-drag.js, web/component-sort.js | WASM methods create_component, create_component_selection, create_instance, place_instance, swap_instance, detach_instance, reset_override, reset_instance, push_style_overrides, combine_variants, add_variant, save_component_set, set_variant_property, save_component_property, set_component_property, wrap_in_slot, clear_slot, reset_slot, sort_components
|
Editor::commit pipeline in src/lib.rs, layout constrain_axis, style/variable resolvers |
Inspector component panel in web/app.js, Assets browser, libraries (web/library-model.js), MCP/agent API (web/editor-api.js), design-file import | README "Create components from a selection", "Nested linked components"; Interface reference log "Components and variants", "Component slots"; TEAM_LIBRARIES.md |
- Create component (Ctrl/Cmd+Alt+K, inspector, context menu, Tools search). A selected ordinary frame converts in place; any other selection is wrapped in a transparent frame that becomes the main.
- Instances are inserted from the Assets rail (click, or drag a preview onto the canvas). Instances render the main's artwork; their children cannot be restyled, moved, reordered, added or deleted unless the instance is detached. Content and state (text, name, visibility, lock, control state) can be overridden.
- Instance panel: override list with per-row Reset, Reset all overrides, Detach instance, Go to main component, Swap component (dropdown), Push text and styles to main. Selecting a nested child adds Go to nested main component and Select outer instance; swap/variant pickers are disabled on non-root children with the help text "Independent nested-instance swapping is not available yet."
- Variants: Combine as variants (sibling mains) or Add variant creates a visible component-set frame. The set shows a Properties list; a main inside a set shows Current variant; an instance shows one dropdown per property.
- Component properties: Text and Visibility (boolean) properties bind one or more layers in a main; instances expose them as fields with Reset.
- Slots: a nested frame in a main becomes a slot (Properties → + → Slot, or Wrap in slot). In instances, slot frames accept arbitrary content, show Default/Modified status, Add instances, Reset slot and Delete contents. Empty slots show a "+" canvas overlay.
- Component order in the Assets/Components list is drag-sortable (or Alt+↑/↓) and saved in the document.
All component state lives on Shape and Document in src/lib.rs and is serialized into .pixl files.
| Where | Field | Meaning |
|---|---|---|
Shape.component |
Option<components::Component> |
None, {"type":"master"}, or {"type":"instance","master":u32,"source":u32,"overrides":[String]}
|
Shape.slot |
Option<slots::SlotState> |
{property, modified}; derived from slot property bindings, never trusted from the client (slots::bind) |
Shape.slot_origin |
u32 |
For default slot content in an instance, the main-side layer it was copied from (stable ID reuse) |
Document.component_sets |
Vec<variants::ComponentSet> |
{id, frame_id, name, properties[≤16], variants[{component_id, values[]}]} |
Document.component_properties |
Vec<component_properties::ComponentProperty> |
`{id, component_id, name, kind: "text" |
Document.component_order |
Vec<String> |
Keys "set:<id>" / "component:<id>" for the Assets ordering (validated in validate and Editor::sort_components) |
Instance roots vs descendants. An instance root has master == source (both equal the main's ID). A descendant has master = the same main and source = the ID of the corresponding layer inside the main's subtree. A nested instance inside a main is itself a root of a different master; when it is copied into an outer instance, its copies become descendants of the outer master whose source points at the nested instance layers inside the outer main. web/instance-context.js instanceContext(doc, shape) walks this: it returns {root, main, nestedMain, isRoot} where root is the outermost instance root and nestedMain is found by following source → source.component.master chains.
Every mutating WASM method builds a cloned Document and calls Editor::commit (or commit_document, which skips the pre-checks). The relevant stages:
flowchart TD
A["WASM call e.g. update_many(json)"] --> B["components::record_overrides(old, new)\n(per edited shape; may reject)"]
B --> C["component_properties::propagate_edits"]
C --> D["Editor::commit"]
D --> D1["slots::prepare (bind slots, mark modified)"]
D1 --> D2["variants::prune / component_properties::prune"]
D2 --> D3["validate(document)"]
D3 --> D4["components::protect_structure(old, new)\n(rejects instance-child remove/reparent/reorder)"]
D4 --> E["commit_validated_document"]
E --> E1["starter_defaults::sync, variables::resolve"]
E1 --> E2["components::validate_links"]
E2 --> E3["document_order::parents_first, reflow_text"]
E3 --> F["components::sync\n(topologically ordered instance roots)"]
F --> F1["for each main layer: reuse instance ID by source,\nconstrain_axis geometry, apply_overrides"]
F1 --> F2["slots::build_content for slot frames"]
F2 --> G["guide/effect/text/color style resolve,\nvariables::resolve, sync_paint_stacks"]
G --> H["push undo entry, replace self.document"]
sync(doc, next) (called from commit_validated_document, and also when loading documents) does:
-
Native button labels. For main components whose
control.kind == "button"(non-starter), the first visible text descendant is copied intocontrol.labelandtypographyso it propagates as the native label. -
Dependency ordering. Collects every instance root, computes which other roots live inside its main's subtree, and resolves them in dependency order. A cycle returns
"Component reference cycle: an instance cannot contain itself". This is why nested instances update correctly regardless of document paint order (tested innested-components.test.mjs). -
Orphan handling. If the master no longer exists or is no longer a
Master, the instance's links are cleared (the layers become ordinary artwork). Deleting a main therefore "detaches" all its instances at the next commit rather than deleting them. -
Rebuild. For each layer in the main's subtree (excluding slot contents):
- The existing instance layer is found by
component.source == src.id; its ID is reused, otherwise a fresh ID is allocated fromnext. Stable IDs are what let overrides, selection and prototype targets survive main edits. - The shape is cloned from the main, then the instance-owned fields are restored:
flow_name,layout_class,layout_class_generated,breakpoint_original, and every path inoverridesviaapply_overrides. - Root position comes from the instance root; descendants are positioned with
constrain_axisrelative to the main parent vs the instance parent, honoring the child's (possibly overridden) constraints. Groups pass through withConstraint::Scaleunless the group itself has a geometry override.x/yoverrides on descendants preserve the old offset from the parent. - Slot frames get
slot.modifiedcarried over and their children built byslots::build_content.
- The existing instance layer is found by
- The old subtree is spliced out and the rebuilt one spliced in at the same index. The document cap is 10,000 layers.
components::record_overrides(old, new) runs inside update_many (and path join/split, property propagation, swap transfer). It:
-
Detaches styles when values diverge: edited typography clears
text_style, edited fill/stroke paints clearfill_style/stroke_style, editedlayout_gridsclearsguide_style, edited effects cleareffect_style;variables::detach_editedremoves variable bindings for directly edited properties. This applies to all layers, not only instances. - Rejects slot or link edits made through plain updates ("Use the slot actions…", "Use the component actions…").
-
Enforces instance protection. For instance layers, each changed top-level field (compared via
effective_value, which normalizes absentappearance/typographyto defaults so legacy documents compare correctly) is checked:- Always allowed:
name,text,hidden,locked,control_state. - Root only:
x,y,width;layout_itemchanges limited tofill_width/min_width/max_width/grid_cell;auto_layoutchanges limited tohug_width. -
control: only content keys (label,value,placeholder,helper_message,validation_message,invalid,selected_values,width_sizing,hide_helper; plusnamefor radios). - Slot frames inside instances may additionally change
fill,appearance,stroke_width,effect_style,fill_style,stroke_style,variable_bindings. - Anything else errors with
"Instance appearance is protected. Edit the main component instead."Kind changes, or reparenting a descendant, error with "Detach the instance before changing its structure".
- Always allowed:
-
Computes the override list. For fields with a sub-field table (
subfields():control,typography,appearance,constraints,layout_item,auto_layout) it records per-property paths such astypography.font_size; other fields are recorded whole (text,hidden…). Paired fields are always recorded together:layout_grids+guide_style, andprototype+additional_interactions.
validate_links caps overrides at 64 per layer, requires uniqueness, and only accepts paths listed in FIELDS/subfields() (valid_override).
Note: The README ("Nested linked components") describes "independent inner and outer appearance/text overrides" and says Push to main includes "paints/effects". The current code rejects appearance edits on instance layers (only slot frames are exempt), so in practice new overrides are content/state/geometry. Appearance override paths are still accepted when loading and pushing, which covers legacy documents (
component-swapping.test.mjs: "legacy whole-style overrides survive").
-
protect_structure(old, new)(incommit) rejects removing, reparenting or reordering instance descendants ("Detach the instance before removing/changing/reordering…"). It skips the check when the main's own subtree structure changed in the same transaction (staged operations), when the outer root was detached, or for roots (whole instances can move, duplicate, delete and reorder freely). -
validate_linksenforces: mains and instance roots must be frames; a descendant's parent must be an instance of the same master; no duplicatesourcewithin one root; ordinary (unlinked) layers may only sit under an instance if their parent is a slot; main components cannot be nested inside other mains or inside instances ("Nested main components are not supported; nest linked instances inside main components instead").
| Operation | Function | Behavior |
|---|---|---|
| Per-property reset | Editor::reset_override(id, path) |
Removes path and any path.* children (plus its pair partner). If the path is bound to a component property on that layer's source, delegates to reset_component_property. The next sync re-copies the main value. |
| Reset all | Editor::reset_instance(id) |
Walks to instance_root, clears overrides on every layer in the subtree and sets slot.modified = false. Uses commit_document. |
| Detach | Editor::detach_instance(id) |
Clears component and slot on subtree layers linked to the root's master (nested instances of other masters stay linked), then restore_detached_button_labels materializes a real text layer for native button labels. |
| Push to main | Editor::push_style_overrides(id) |
For every layer under the root, takes override paths whose top-level field is in the eligible list (name, text, fill, appearance, typography, hidden, locked, image, stroke_width, layout_grids, guide_style, effect_style, text_style, fill_style, stroke_style), applies them to the source layer in the main via apply_overrides, runs record_overrides on that source (so if the source is itself a nested instance the value becomes an override there and the inner main is untouched), and removes the pushed paths from the instance. Geometry, constraints, auto layout and prototype overrides stay local. |
The inspector's override list (web/app.js renderComponentProperties) merges additional_interactions into prototype, hides x/y on roots, and maps paths to labels (e.g. stroke_alignment → "Stroke position").
Editor::swap_instance(id, master) (only from the instance root; the UI disables it for nested children):
- Builds a source-ID mapping old main → new main with
match_children: children are matched by layer name and kind, recursively by hierarchy; repeated sibling names match by occurrence in paint order. Instance-side renames do not affect matching because matching uses main-side names. - Slot properties with the same name on both mains map their target frames pairwise, so customized slot content survives swaps (and variant switches) even when the slot frames have different names.
- Matched instance layers keep their IDs and override lists with
sourceremapped; unmatched layers are dropped. Children ofmodifiedslots are carried over. - Runs
syncto fill in the new main's remaining layers, thencomponent_properties::transfer_on_swap: a text/boolean property that was overridden on the old instance is re-applied to the new main's property with the same name and kind, regardless of layer names. - Commits once with
commit_document(one undo step).
Linked instances may live inside a main (README "Nested linked components"). The engine handles them as ordinary instance roots that sync resolves before any outer root that depends on them. In outer instances, nested copies are descendants of the outer master. Consequences:
- Inner-main edits flow inner main → nested instance in outer main → outer instances, in one commit.
- An override on a nested copy is an outer-instance override; push to main writes it onto the nested source as an override, not into the inner main (
push-overrides.test.mjs). - Swapping the nested source inside the main propagates; deleting the inner main leaves the outer artwork as unlinked layers.
- Exposed instance-swap properties and independent swapping of nested instances in outer copies are not implemented.
Rust (src/variants.rs):
-
ComponentSetgroups mains.frame_id(optional, 0 for legacy sets) is the visible container: an ordinary frame whose direct children are the variant mains.validate_setsenforces ≤1000 sets, 1–16 unique property names, ≤1000 variants, each variant a main in exactly one set, unique value combinations, and membership inside the container. -
prune(incommit) drops variants whose main was deleted or moved out of the frame, clears a deleted container, deletes empty sets, and keepsset.nameequal to the container frame's name. -
combine_variants(json)requires ≥2 sibling mains not already in a set. Naming is inferred:Property=Value, Other=Valuenames become multiple properties (named_properties);Button / Primarystyle names with a shared prefix produce set nameButtonand valuesPrimary; identical names produceDefault,Variant 2… The mains are wrapped (frame_selection, padded 20px). -
add_variant(id)accepts a main, a set member, or a set frame; creates a set (Property 1 = Default) for a standalone main, upgrades legacy sibling sets to a visible container, thenduplicate_variant. -
duplicate_variant(id)duplicates the main subtree, places it below the existing members (inside a frame) or to the right, picks the next freeVariant Nvalue for the last property, and grows the container. -
save_component_set(json)is the general authoring call (rename set/properties/values, add/remove properties). It trims values, validates before pruning, auto-creates a container for sibling sets (including sets authored directly through MCP), and renames every main toProp=Value, …viavariant_name. -
set_variant_property(id, property, value): on a main, edits its value in the set; on an instance, picks the variant with that value that keeps the most other property values (ties by set order) and callsswap_instance. Sparse sets are therefore supported. -
duplicate_definitions(doc, mapping)clones a whole set when its container (or every legacy member) is duplicated; a single copied main stays standalone.
JS (web/variants.js): componentSet, componentSetFrame, canCombineVariants (selection predicate), renderVariantProperties (instance dropdowns calling set_variant_property) and renderVariantAuthoring (set "Properties" rows with inline rename and remove; main "Current variant" rows with value field + chooser; the Create property → Variant 304px popover). All edits clone the set and call save_component_set. Plain <select> elements are upgraded to the shared custom dropdown by installInspectorDropdowns (web/inspector-dropdown.js).
Rust (src/component_properties.rs):
- Kinds:
text(bindsShape.texton text layers),boolean(binds visibility;truemeans visible, stored as!hidden),slot(see below).field(p)returns the override path the property owns:"text"or"hidden". -
validate_properties: ≤10,000 properties; unique(component_id, name); targets inside the main; text properties only on text layers; one property of a given kind per layer; non-slot properties need ≥1 target; properties cannot bind layers inside slot contents. -
save_component_property(json)creates/updates a definition and immediately assigns the first target's current value to every target (bound layers share one value). Slot properties callslots::bindinstead. -
set_component_property(id, property, json)resolves bound layers for the main or the instance root (targets()maps main targets to instance layers viasource) and routes the change throughupdate_many, so it records normal overrides. -
propagate_edits(insideupdate_many): editing one bound layer directly (e.g. typing in a text layer) copies the value to every other bound layer under the same root; conflicting values in one edit error with "Bound component layers must share the same property value". -
reset_component_propertyremoves the property's override path (and slotmodified) on the bound instance layers. -
pruneremoves targets that left the main and preferred instances that are no longer mains;duplicate_definitionsremaps definitions when mains are duplicated.
JS (web/component-properties.js): renderComponentProperties renders a textarea/checkbox per property (mixed values show "Mixed values"/indeterminate), with Reset on instances and Edit binding/Remove on mains; editComponentProperty opens the modal binding dialog (Text/Visibility, layer checklist excluding layers already bound to that kind). Slot properties are delegated to slots.js.
Rust (src/slots.rs):
- A slot is a
ComponentPropertywithkind: "slot"whosetargetsare nested frames in the main (not the main itself, not instances, not inside another slot: "Nest a separate component instance to use a slot inside another slot"). Slot properties may be unbound (zero targets). -
SlotSettings:description,min_children,max_children,preferred_instances,only_preferred_instances,display_empty,fill_counter_axis. -
bind(doc)setsShape.sloton mains/ordinary layers from the property bindings.prepare(old, doc)(start ofcommit) marks an instance slotmodifiedwhen its content differs from the previous commit, and setsfill_width/fill_heighton newly added children of auto-layout slots withfill_counter_axis. -
build_content(fromsync): amodifiedslot keeps the instance's own children (translated if the slot moved); an unmodified slot clones the main's default children, reusing IDs viaslot_origin, and preserves their CSS identity. -
clear_slot(id)deletes content and marks the instance slot modified;reset_slot(id)clearsmodifiedso defaults return;wrap_in_slot(json, name)frames sibling layers inside a main (or reuses a single selected frame) and creates the slot property in one undo step. -
validate_linksallows unlinked layers under an instance only when their parent is a slot;record_overrideslets slot frames change paint/effects.
JS (web/slots.js): slotProperty, slotOwner, slotWarnings, renderSlotProperty (Default/Modified chip, add, reset/delete menu, "Limits" warning), editSlotProperty (settings dialog), slotInstancePicker (Add instances picker with library source dropdown, page folders, list/grid, live thumbnails via assetAppearance), renderSlotOverlay (empty-slot "+" targets positioned from pan/zoom).
Note: Slot limits and "only preferred instances" are advisory.
slotWarningsreports them in the UI; the engine does not enforce them (slots.test.mjs: "slot limits warn without blocking content").
| File | Role |
|---|---|
| web/assets.js |
componentAssets(doc, query, page) builds one asset per variant set plus each ungrouped main, searchable by name, page names and Prop: value labels. assetAppearance renders a live preview through compileCssScene (CSS renderer) with inherited variable modes. renderAssets renders cards in batches of 40 with a variant selector, Insert/Go to main menu and a "Protected" note for library mains. |
| web/asset-drag.js |
ASSET_MIME = 'application/x-pixlprfct-component'; drag payload {token, master}. The per-session assetDragToken (crypto.randomUUID() in app.js) means drags from another tab/editor are ignored. centeredPlacement centers the main on the pointer. |
| web/component-sort.js |
componentEntries (sets + ungrouped mains ordered by component_order), moveComponent, renderSortableComponents (drag/drop with before/after indicator, Alt+↑/↓, live-region announcements). Persists via Editor::sort_components, which requires every key exactly once. |
| web/instance-context.js |
instanceContext (see Data model). |
Drop handling in app.js calls editor.place_instance(master, x, y, parent), which stages create_instance + move_into so auto-layout parents insert in flow order and grids pin the pointed cell, in one undo step. create_instance only clones the root; sync populates children during commit.
Library-sourced mains are protected by JS policy in web/library-model.js (instancePermissions, protectedInstanceError, driven by editor_meta.library_overrides); see Teams-Libraries-and-Collaboration.
Allow a new instance override field. Add the field to FIELDS (or a sub-key to subfields()) in components.rs; decide in record_overrides whether instances may change it (the allowed match); if it should be pushable, add it to the push_style_overrides list and the UI pushFields in app.js; add a label in the override list in app.js; add a test to components.test.mjs/component-swapping.test.mjs. If the field is an object with optional serialization, extend effective_value so legacy None compares equal to defaults.
Add a component property kind. Extend validate_properties (allowed kinds), field, value, assign; render it in renderComponentProperties/editComponentProperty; consider transfer_on_swap and reset_override delegation.
Add a new structural operation on mains. Build a staged Editor (pattern used by place_instance, combine_variants, wrap_in_slot) and commit once so undo is one step; if the operation edits instance structure on purpose, use commit_document (skips protect_structure) as swap_instance/reset_instance do.
After changing any WASM signature, rebuild with npm run build:editor so web/editor-api.js is regenerated (see Build-System).
- Instance subtrees are derived data. Writing to an instance child outside the allowed fields fails; writing allowed fields without the recorded override path would be undone by the next
sync. Always go throughupdate/update_manysorecord_overridesruns. -
sourceuniqueness per root and ID reuse bysourceare what keep selection, prototype targets and overrides stable across main edits. Do not regenerate instance IDs. - Deleting a main does not delete instances;
syncunlinks them. -
protect_structureruns only incommit, notcommit_document. -
reset_component_propertyfor a slot property also strips any"hidden"override on the slot frame, becausefield()returns"hidden"for every non-text kind. - The UI's
pushFieldslist omitstext_style,fill_styleandstroke_style, which Rust does push; the button can be disabled when only those overrides exist. -
set.nameis overwritten by the container frame name on everyprune; rename sets via the frame orsave_component_set.
From code and README: no nested main definitions; no independent nested-instance swap in outer copies; no exposed instance-swap properties; no variable-driven component properties; slot limits are advisory; slot descriptions are plain text; native design-archive slot metadata is not preserved on .fig import (interface reference log "Component slots"); real-time multiplayer is out of scope here.
| Test file | Covers |
|---|---|
tests/components.test.mjs |
Propagation across pages, text overrides, protected paint, stable IDs, constraints, auto layout, malformed links, drag of roots |
tests/component-selection.test.mjs |
Create component from shapes/multi-selection/frames |
tests/component-swapping.test.mjs |
Swap matching rules, repeated names, groups, legacy overrides, protected constraints |
tests/nested-components.test.mjs |
Three-level propagation, independent overrides, cycles, inner-main deletion |
tests/push-overrides.test.mjs |
Push to main, nested source overrides, no-op cases |
tests/component-properties.test.mjs |
Text/visibility bindings, reset, swap transfer, duplication, pruning |
tests/variants.test.mjs |
Combine, add, duplicate, sparse selection, naming, legacy upgrade |
tests/slots.test.mjs |
Defaults vs customization, clear/reset, libraries, copy/paste, swaps, limits |
tests/component-sort.test.mjs, tests/assets.test.mjs, tests/asset-placement.test.mjs, tests/instance-context.test.mjs
|
Ordering, asset grouping/search/previews, drag placement, nested context |
tests/library-overrides.test.mjs, tests/browser/library-overrides.spec.mjs
|
Library-protected instances |
Run with npm test (requires a built web/pkg).
Rust-Document-Engine · Document-Model-and-File-Format · Styles-Variables-and-Paints · Prototyping-Behaviors-and-Controls · Layout-Auto-Layout-and-Grid · Teams-Libraries-and-Collaboration · Import-Design-Files · Testing-and-Verification · Glossary
-
src/components.rs —
Component,FIELDS,subfields,record_overrides,protect_structure,validate_links,sync, instance WASM methods - src/variants.rs, src/component_properties.rs, src/slots.rs
-
src/lib.rs —
Editor::commit,commit_validated_document,update_many,sort_components -
web/app.js
renderComponentProperties, asset drop handling; the JS modules listed above - README sections "Create components from a selection" and "Nested linked components"; Interface reference log "Components and variants — live reference 2026-10-29" and "Component slots — live reference 2026-10-30"
Start
Core
- Rust Document Engine
- Document Model & File Format
- Web Editor Architecture
- Rendering & Export
- Build System
Editor features
- Canvas Tools & Editing
- Layout, Auto Layout & Grid
- Components, Variants & Slots
- Styles, Variables & Paints
- Prototyping, Behaviors & Controls
- Import: Design Files & SVG
- SVG Animator
- Panel Workspace — tear-outs, icons, side flyouts and saved layouts
- Icon Library
Platforms
- Hosting Modes
- Self-Hosted Server
- Cloud API & Database
- Teams, Libraries & Collaboration
- Desktop App
- MCP Server
Practice