Component

A Component is a reusable element tree you define once and place many times — an attachable subtree. Identity + fields (the prop schema) + testData for the canvas. The tree is loaded with the component when you outline or edit it.

It is not an element. An element on a page can be a component instance: kind: { _tag: "Component", value: "<componentId>" }. That node's props are the instance values (title, events, …). The definition lives here; the instance is a page (or parent component) node.

Fields

create_component starts with no elements. A page scaffolds a body root; a component does not — the root kind is yours. Seed it with add_root_element, then add_element for children. The root kind must be a registered Primitive (header, div, section, …), not a Component reference.

Optional fields on create are the prop schema — the same array set_props_schema would write. Do not follow create with set_props_schema just to re-declare them.

Inside the tree, {{props.title}} is this component's props. Entering the component replaces the outer frame — an inner {{props.X}} never reaches the page's props. Pass page or store data in at the instance (update_props on the Component-kind element), then bind_prop (or a {{props.*}} expression) onto inner nodes.

bind_prop writes {{props.<key>}} onto a target prop:

A store can attach to the component so state travels with it and the name state stays free.

How it relates

• App — components are listed and created in the active app (contextId).
• Page — place the component as an element. Set instance values with update_props (or instanceProps on add_elements).
• Element — the definition is an element tree (container: { _tag: "Component", id }). Same Primitive vs Component kind, props, styles, repeat.
• Page vs component as containers — both own an element tree. You usually declare fields on the component; pages also have author fields, plus {{page.id}} / {{page.appId}} / {{page.params.*}} / {{page.search.*}}.

MCP tools

Tree mutations use the element tools with container: { _tag: "Component", id: componentId }.

Build sequence:

1. list_components with search for the name — skip create if it exists.
2. create_component with name, layer, category, and optional fields.
3. add_root_element with a Primitive kind (article, div, …).
4. add_element for children.
5. bind_prop each field onto an inner prop.
6. set_test_data with sample values.

On a page: add_element with kind { _tag: "Component", value: componentId }, then update_props to set instance values (title, …).

Gotchas

• Empty until you seed a root. add_element needs an existing parent and errors on an empty tree. add_root_element is the first call; pages never need it.
• set_props_schema is wholesale. list_components / load_component_outline first, then send the full fields array. Same pattern as update_store.
• Search, then create. list_components search is a substring on name and description. A listing from earlier in the session is how duplicates get made.
• Props do not leak inward. Bind signedIn: "{{session.signedIn}}" (or a store field) on the instance, then renderIf: "{{props.signedIn}}" inside.
• instanceProps only on Component kinds in add_elements. Primitive nodes use props. Both fold into the same record the renderer reads.
• Same tree rules as pages. Purpose aria-label, omit targetPosition to append, inspect_element_type before composite primitives. See Element.