@mintjamsinc/ichigojs 0.1.76 → 0.1.78

package/dist/ichigo.esm.js

@@ -7505,6 +7505,14 @@ class VBindDirective {
      * @inheritdoc
      */
     get onMount() {
+        // A constant expression (e.g. :label="'Apple'") has no reactive
+        // identifiers, so the identifier-driven update cycle never applies it.
+        // Render it once at mount instead.
+        if (this.#evaluator && this.#evaluator.dependentIdentifiers.length === 0) {
+            return () => {
+                this.#render();
+            };
+        }
         return undefined;
     }
     /**
@@ -8920,6 +8928,344 @@ class VBindings {
     }
 }
 
+// Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
+/**
+ * Registry of custom element tag names defined via defineComponent().
+ *
+ * VNode consults this registry during compilation to recognize component
+ * boundaries: the children of an already-expanded ichigo component belong to
+ * the component's own VApplication and must not be compiled by the parent
+ * application (doing so would strip the component's directives and evaluate
+ * its template expressions in the wrong scope).
+ */
+class IchigoElementRegistry {
+    /**
+     * Registered tag names, stored uppercased to match Node.nodeName.
+     */
+    static #tags = new Set();
+    /**
+     * Registers a component tag name. Called by defineComponent().
+     * @param tagName The custom element tag name (case-insensitive).
+     */
+    static add(tagName) {
+        this.#tags.add(tagName.toUpperCase());
+    }
+    /**
+     * Checks whether a tag name belongs to a component defined via defineComponent().
+     * @param tagName The tag name to check (case-insensitive; nodeName is accepted as-is).
+     */
+    static has(tagName) {
+        return this.#tags.has(tagName.toUpperCase());
+    }
+}
+
+// Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
+/**
+ * Renders a scoped slot outlet: a `<slot>` element inside a component template
+ * whose host element received a matching `<template v-slot:name="scope">` from
+ * the parent.
+ *
+ * The slot content is compiled in the PARENT application's scope (the scope in
+ * which the template was authored), extended with the slot props — the values
+ * bound on the `<slot>` outlet with `v-bind` / `:` — exposed under the single
+ * scope variable declared in `v-slot` (e.g. `v-slot:item="row"` makes
+ * `row.node`, `row.index`, ... available):
+ *
+ * ```html
+ * <!-- component template -->
+ * <li v-for="(node, i) of items">
+ *   <slot name="item" :node="node" :index="i">fallback</slot>
+ * </li>
+ *
+ * <!-- usage -->
+ * <my-tree :items="nodes">
+ *   <template v-slot:item="row">{{ row.node.label }} ({{ appTitle }})</template>
+ * </my-tree>
+ * ```
+ *
+ * This directive is created only when a scoped template for the slot's name
+ * exists (see {@link VSlotOutletDirective.tryCreate}); otherwise `<slot>`
+ * elements keep their existing behavior (static distribution at expansion,
+ * or fallback content compiled in the component scope).
+ *
+ * Rendering happens synchronously in onMount — before the component
+ * application would compile the slot's fallback children — by replacing the
+ * `<slot>` element with a clone of the scoped template's content. The content
+ * VNode is attached under the host element's VNode in the parent application,
+ * so parent-side data changes flow through the normal update cycle; slot-prop
+ * changes on the component side are pushed by this directive's domUpdater.
+ */
+class VSlotOutletDirective {
+    /**
+     * The virtual node of the `<slot>` element (in the component application).
+     */
+    #vNode;
+    /**
+     * The captured scoped template and its scope variable name.
+     */
+    #entry;
+    /**
+     * The host element's VNode in the parent application. Slot content is
+     * compiled against this node's application and bindings.
+     */
+    #hostVNode;
+    /**
+     * The slot props: camelized names and evaluators for the `v-bind` / `:`
+     * attributes found on the `<slot>` outlet (evaluated in component scope).
+     */
+    #props = [];
+    /**
+     * The bindings for the slot content: a child scope of the parent
+     * application's bindings holding the scope variable.
+     */
+    #scopeBindings;
+    /**
+     * The VNode tree of the rendered slot content (owned by the parent application).
+     */
+    #contentVNode;
+    /**
+     * Guards against double destruction (the content VNode is reachable from
+     * both the parent application's tree and this directive).
+     */
+    #destroyed = false;
+    /**
+     * Tracks host elements that already logged the "no host context" warning.
+     */
+    static #warnedNoHost = new WeakSet();
+    /**
+     * Creates a slot outlet directive for the given `<slot>` VNode when a
+     * scoped template for its slot name was captured on the host element.
+     * Returns undefined when there is nothing to do (no component host, no
+     * scoped template for this name) so the `<slot>` element keeps its
+     * existing behavior.
+     */
+    static tryCreate(vNode) {
+        const host = vNode.vApplication.hostElement;
+        if (!host) {
+            return undefined;
+        }
+        const scopedSlots = host._ichigoScopedSlots;
+        if (!scopedSlots || scopedSlots.size === 0) {
+            return undefined;
+        }
+        const element = vNode.node;
+        const slotName = element.getAttribute('name') || 'default';
+        const entry = scopedSlots.get(slotName);
+        if (!entry) {
+            return undefined;
+        }
+        const hostVNode = host._ichigoHost?.vNode;
+        if (!hostVNode) {
+            // The scoped template cannot be rendered without the parent scope.
+            // Leave the <slot> alone (fallback content renders in component scope).
+            if (!VSlotOutletDirective.#warnedNoHost.has(host)) {
+                VSlotOutletDirective.#warnedNoHost.add(host);
+                console.warn(`[ichigo] <${host.tagName.toLowerCase()}>: a scoped slot template for '${slotName}' was provided, but the component has no parent application scope to render it in. The fallback content is used instead.`);
+            }
+            return undefined;
+        }
+        return new VSlotOutletDirective(vNode, entry, hostVNode);
+    }
+    constructor(vNode, entry, hostVNode) {
+        this.#vNode = vNode;
+        this.#entry = entry;
+        this.#hostVNode = hostVNode;
+        // Collect and consume the slot-prop bindings (v-bind / :) so the
+        // generic attribute parsing does not also process them.
+        const element = vNode.node;
+        for (const attr of Array.from(element.attributes)) {
+            let propName;
+            if (attr.name.startsWith('v-bind:')) {
+                propName = attr.name.substring(7);
+            }
+            else if (attr.name.startsWith(':')) {
+                propName = attr.name.substring(1);
+            }
+            if (!propName) {
+                continue;
+            }
+            const evaluator = attr.value && vNode.bindings
+                ? ExpressionEvaluator.create(attr.value, vNode.bindings, vNode.vApplication.functionDependencies)
+                : undefined;
+            this.#props.push({ name: this.#kebabToCamel(propName), evaluator });
+            element.removeAttribute(attr.name);
+        }
+    }
+    /**
+     * @inheritdoc
+     */
+    get name() {
+        return 'slot-outlet';
+    }
+    /**
+     * @inheritdoc
+     */
+    get vNode() {
+        return this.#vNode;
+    }
+    /**
+     * @inheritdoc
+     */
+    get needsAnchor() {
+        return false;
+    }
+    /**
+     * @inheritdoc
+     */
+    get bindingsPreparer() {
+        return undefined;
+    }
+    /**
+     * @inheritdoc
+     */
+    get domUpdater() {
+        const identifiers = this.dependentIdentifiers;
+        const updater = {
+            get dependentIdentifiers() {
+                return identifiers;
+            },
+            applyToDOM: () => {
+                this.#refresh();
+            }
+        };
+        return updater;
+    }
+    /**
+     * @inheritdoc
+     */
+    get templatize() {
+        return false;
+    }
+    /**
+     * @inheritdoc
+     */
+    get dependentIdentifiers() {
+        const ids = new Set();
+        for (const prop of this.#props) {
+            prop.evaluator?.dependentIdentifiers.forEach(id => ids.add(id));
+        }
+        return Array.from(ids);
+    }
+    /**
+     * @inheritdoc
+     *
+     * The initial render happens here — synchronously during VNode
+     * construction, after the directives are created and BEFORE the component
+     * application compiles the slot element's children. This guarantees the
+     * outlet renders exactly once regardless of whether its slot props have
+     * reactive identifiers, and removes the fallback children before they
+     * could be compiled in the component scope.
+     */
+    get onMount() {
+        return () => {
+            this.#render();
+        };
+    }
+    /**
+     * @inheritdoc
+     */
+    get onMounted() {
+        return undefined;
+    }
+    /**
+     * @inheritdoc
+     */
+    get onUpdate() {
+        return undefined;
+    }
+    /**
+     * @inheritdoc
+     */
+    get onUpdated() {
+        return undefined;
+    }
+    /**
+     * @inheritdoc
+     */
+    get onUnmount() {
+        return undefined;
+    }
+    /**
+     * @inheritdoc
+     */
+    get onUnmounted() {
+        return undefined;
+    }
+    /**
+     * @inheritdoc
+     */
+    destroy() {
+        if (this.#destroyed) {
+            return;
+        }
+        this.#destroyed = true;
+        // Destroy the content VNode so its dependency registrations on the
+        // host VNode are released (critical for v-for rows that come and go).
+        // The content DOM nodes live inside the component's subtree and are
+        // removed together with it.
+        this.#contentVNode?.destroy();
+        this.#contentVNode = undefined;
+        this.#scopeBindings = undefined;
+    }
+    /**
+     * Renders the scoped slot content in place of the `<slot>` element.
+     */
+    #render() {
+        const slot = this.#vNode.node;
+        // Scope: parent application's bindings + the scope variable
+        this.#scopeBindings = new VBindings({ parent: this.#hostVNode.bindings });
+        if (this.#entry.scopeVar) {
+            this.#scopeBindings.setLocal(this.#entry.scopeVar, this.#buildSlotProps());
+        }
+        // Clone the scoped template's content and create its VNode tree BEFORE
+        // inserting into the DOM, so components inside the slot content are
+        // compiled before their connectedCallback can expand them.
+        // (Created through the parent application to keep the VNode import
+        // type-only; a direct `new VNode` here would close a module cycle
+        // VNode -> VDirectiveManager -> VSlotOutletDirective -> VNode.)
+        const fragment = this.#entry.template.content.cloneNode(true);
+        this.#contentVNode = this.#hostVNode.vApplication.createVNode({
+            node: fragment,
+            vApplication: this.#hostVNode.vApplication,
+            parentVNode: this.#hostVNode,
+            bindings: this.#scopeBindings
+        });
+        // Drop the fallback children (a scoped template supersedes them), then
+        // swap the <slot> element for the content.
+        while (slot.firstChild) {
+            slot.removeChild(slot.firstChild);
+        }
+        slot.replaceWith(fragment);
+        // Initial rendering
+        this.#contentVNode.forceUpdate();
+    }
+    /**
+     * Re-evaluates the slot props (component-side change) and pushes them into
+     * the content scope.
+     */
+    #refresh() {
+        if (!this.#contentVNode || !this.#scopeBindings || !this.#entry.scopeVar) {
+            return;
+        }
+        this.#scopeBindings.setLocal(this.#entry.scopeVar, this.#buildSlotProps());
+        this.#contentVNode.forceUpdate();
+    }
+    /**
+     * Builds the slot props object from the outlet's `v-bind` attributes,
+     * evaluated in the component scope.
+     */
+    #buildSlotProps() {
+        const props = {};
+        for (const prop of this.#props) {
+            props[prop.name] = prop.evaluator?.evaluate();
+        }
+        return props;
+    }
+    #kebabToCamel(str) {
+        return str.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+    }
+}
+
 // Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
 /**
  * Manages directives associated with a virtual node (VNode).
@@ -9086,6 +9432,24 @@ class VDirectiveManager {
     }
     #parseDirectives() {
         const element = this.#vNode.node;
+        // Parse directives from attributes
+        const directives = [];
+        // Scoped slot outlet: a <slot> element (without structural directives)
+        // inside a component whose host received a matching <template v-slot:...>.
+        // This is an element-based directive, created before the generic
+        // attribute parsing so it can consume the slot-prop bindings (:x).
+        // A <slot> carrying v-if / v-for is handled structurally first; the
+        // outlet is then created when the clone is compiled.
+        if (element.tagName === 'SLOT' &&
+            !element.hasAttribute(StandardDirectiveName.V_FOR) &&
+            !element.hasAttribute(StandardDirectiveName.V_IF) &&
+            !element.hasAttribute(StandardDirectiveName.V_ELSE_IF) &&
+            !element.hasAttribute(StandardDirectiveName.V_ELSE)) {
+            const outlet = VSlotOutletDirective.tryCreate(this.#vNode);
+            if (outlet) {
+                directives.push(outlet);
+            }
+        }
         // Collect relevant attributes
         // For v-for, v-if, v-else-if, v-else: process only the structural directive on the template element.
         // Other directives (@click, :class, etc.) will be processed on the cloned/rendered elements.
@@ -9121,8 +9485,6 @@ class VDirectiveManager {
         else {
             attributes.push(...Array.from(element.attributes));
         }
-        // Parse directives from attributes
-        const directives = [];
         for (const attribute of attributes) {
             // Create a context for parsing the directive
             const context = {
@@ -9515,7 +9877,14 @@ class VNode {
         }
         else if (this.#nodeType === Node.ELEMENT_NODE) {
             // If the node is an element, initialize directives and child nodes
-            this.#node;
+            const element = this.#node;
+            // If the element is a component defined via defineComponent(), install
+            // the host context so component-boundary features (e.g. scoped slot
+            // outlets) can reach back into this application's scope.
+            const isComponent = IchigoElementRegistry.has(this.#nodeName);
+            if (isComponent) {
+                element._ichigoHost = { vNode: this };
+            }
             // Initialize child virtual nodes
             this.#childVNodes = [];
             // Initialize directive manager
@@ -9528,8 +9897,19 @@ class VNode {
                     d.onMount?.();
                 });
             }
+            // A component whose template is already expanded compiles its own
+            // internals with its own VApplication — this (parent) application must
+            // not adopt them (that would strip the component's directives and
+            // evaluate its expressions in the wrong scope). An unexpanded component
+            // element only contains authored slot content, which does belong to
+            // this application's scope and is compiled normally.
+            const isExpandedComponent = isComponent && element._ichigoExpanded === true;
+            if (isExpandedComponent) {
+                this.#vApplication.logManager.getLogger(this.constructor.name)
+                    .debug(`Skipped compiling internals of expanded component <${this.#nodeName.toLowerCase()}>`);
+            }
             // Create child virtual nodes if template preservation is not required
-            if (!this.#templatized) {
+            if (!this.#templatized && !isExpandedComponent) {
                 for (const childNode of Array.from(this.#node.childNodes)) {
                     new VNode({
                         node: childNode,
@@ -11567,17 +11947,45 @@ class VModelDirective {
      * The modifiers for this v-model directive (e.g., "lazy", "number", "trim")
      */
     #modifiers = new Set();
+    /**
+     * The argument of the directive (e.g. "size" for `v-model:size`), camelized.
+     * Only meaningful on components; selects the target prop and update event
+     * (prop `size` + event `update:size`). Undefined = the default `modelValue`.
+     */
+    #arg;
+    /**
+     * Ensures the "v-model targets an undeclared prop" warning fires only once.
+     */
+    #warnedUndeclaredProp = false;
     /**
      * @param context The context for parsing the directive.
      */
     constructor(context) {
         this.#vNode = context.vNode;
-        // Extract modifiers from the directive name
-        // e.g., "v-model.lazy.trim" -> modifiers = ["lazy", "trim"]
+        // Extract the optional argument and modifiers from the directive name
+        // e.g. "v-model" / "v-model.lazy.trim" / "v-model:size" / "v-model:size.number"
         const attrName = context.attribute.name;
-        if (attrName.startsWith('v-model.')) {
-            const parts = attrName.split('.');
-            parts.slice(1).forEach(mod => this.#modifiers.add(mod));
+        let rest = attrName.substring(StandardDirectiveName.V_MODEL.length);
+        if (rest.startsWith(':')) {
+            const dotIndex = rest.indexOf('.');
+            const rawArg = dotIndex === -1 ? rest.substring(1) : rest.substring(1, dotIndex);
+            if (rawArg) {
+                // HTML attribute names are lowercased by the browser, so a
+                // camelCase prop is addressed with kebab-case (v-model:inner-title).
+                this.#arg = rawArg.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+            }
+            rest = dotIndex === -1 ? '' : rest.substring(dotIndex);
+        }
+        if (rest.startsWith('.')) {
+            rest.split('.').slice(1).forEach(mod => this.#modifiers.add(mod));
+        }
+        const element = context.vNode.node;
+        if (this.#arg && !this.#isComponentElement(element)) {
+            console.warn(`[ichigo] v-model:${this.#arg} is only supported on components; the argument is ignored on <${element.tagName.toLowerCase()}>`);
+            this.#arg = undefined;
+        }
+        if (this.#isComponentElement(element) && this.#modifiers.has('lazy')) {
+            console.warn(`[ichigo] <${element.tagName.toLowerCase()}>: the .lazy modifier has no effect on components (the component decides when to emit 'update:${this.#propName}')`);
         }
         // Parse the expression and create the evaluator
         const expression = context.attribute.value;
@@ -11749,6 +12157,14 @@ class VModelDirective {
         }
         // Evaluate the expression to get the value
         const value = this.#evaluator.evaluate();
+        // Components: deliver the value as a property (prop `modelValue`, or the
+        // directive argument). For ichigo components this reaches the reactive
+        // bindings through the generated prop setter.
+        if (this.#isComponentElement(element)) {
+            const propName = this.#resolveComponentPropName(element);
+            element[propName] = value;
+            return;
+        }
         // Update the element based on its type
         if (element instanceof HTMLInputElement) {
             if (element.type === 'checkbox') {
@@ -11782,6 +12198,19 @@ class VModelDirective {
         const element = this.#vNode.node;
         const eventName = this.#getEventName();
         this.#listener = (event) => {
+            // Components: the payload of the `update:<prop>` CustomEvent is the
+            // new value. Only events emitted by this component itself are
+            // accepted — the default $emit fires on the component's root element
+            // (a direct child of the host), so an event whose target lies deeper
+            // was emitted by a nested component and bubbled through.
+            if (this.#isComponentElement(element)) {
+                const src = event.target;
+                if (src !== element && src?.parentElement !== element) {
+                    return;
+                }
+                this.#updateBinding(this.#applyModifiers(event.detail));
+                return;
+            }
             const target = event.target;
             let newValue;
             // Get the new value based on element type
@@ -11936,11 +12365,52 @@ class VModelDirective {
         }
         return result;
     }
+    /**
+     * The target prop name on a component: the camelized directive argument,
+     * or the `modelValue` convention when no argument is given.
+     */
+    get #propName() {
+        return this.#arg ?? 'modelValue';
+    }
+    /**
+     * Returns true when the bound element is a component (custom element).
+     * The `modelValue` / `update:modelValue` contract works for any custom
+     * element that follows it, not only ichigo components.
+     */
+    #isComponentElement(element) {
+        return element.tagName.includes('-');
+    }
+    /**
+     * Resolves the property name to assign on a component. For ichigo
+     * components the declared prop list fixes up case-insensitive mismatches
+     * (HTML-lowercased arguments vs. camelCase props) and an undeclared target
+     * prop logs a one-time development warning.
+     */
+    #resolveComponentPropName(element) {
+        const name = this.#propName;
+        const props = element.constructor._props;
+        if (Array.isArray(props)) {
+            const lower = name.toLowerCase();
+            const canonical = props.find(p => p.toLowerCase() === lower);
+            if (canonical) {
+                return canonical;
+            }
+            if (!this.#warnedUndeclaredProp) {
+                this.#warnedUndeclaredProp = true;
+                console.warn(`[ichigo] <${element.tagName.toLowerCase()}>: v-model targets prop '${name}', which is not declared in the component's props`);
+            }
+        }
+        return name;
+    }
     /**
      * Gets the appropriate event name for the element type.
      */
     #getEventName() {
         const element = this.#vNode.node;
+        // Components: listen for the `update:<prop>` convention event.
+        if (this.#isComponentElement(element)) {
+            return 'update:' + this.#propName;
+        }
         // .lazy modifier: use 'change' event instead of 'input'
         if (this.#modifiers.has('lazy')) {
             return 'change';
@@ -13680,9 +14150,10 @@ class VStandardDirectiveParser {
             // v-bind:<attribute>, :<attribute>
             context.attribute.name.startsWith(StandardDirectiveName.V_BIND + ":") ||
             context.attribute.name.startsWith(":") ||
-            // v-model, v-model.<modifier>
+            // v-model, v-model.<modifier>, v-model:<arg>, v-model:<arg>.<modifier>
             context.attribute.name === StandardDirectiveName.V_MODEL ||
             context.attribute.name.startsWith(StandardDirectiveName.V_MODEL + ".") ||
+            context.attribute.name.startsWith(StandardDirectiveName.V_MODEL + ":") ||
             // v-resize
             context.attribute.name === StandardDirectiveName.V_RESIZE ||
             // v-intersection
@@ -13750,9 +14221,10 @@ class VStandardDirectiveParser {
             context.attribute.name.startsWith(":")) {
             return new VBindDirective(context);
         }
-        // v-model, v-model.<modifier>
+        // v-model, v-model.<modifier>, v-model:<arg>, v-model:<arg>.<modifier>
         if (context.attribute.name === StandardDirectiveName.V_MODEL ||
-            context.attribute.name.startsWith(StandardDirectiveName.V_MODEL + ".")) {
+            context.attribute.name.startsWith(StandardDirectiveName.V_MODEL + ".") ||
+            context.attribute.name.startsWith(StandardDirectiveName.V_MODEL + ":")) {
             return new VModelDirective(context);
         }
         // v-resize
@@ -14176,6 +14648,14 @@ class VApplication {
      * Flag to indicate if an update is already scheduled.
      */
     #updateScheduled = false;
+    /**
+     * The custom element hosting this application when it powers a component
+     * defined via defineComponent(). Set by IchigoElement before mounting.
+     * Used by component-boundary features (e.g. scoped slot outlets) to reach
+     * the host's captured slot templates and parent application scope.
+     * Undefined for regular (non-component) applications.
+     */
+    #hostElement;
     /**
      * Creates an instance of the virtual application.
      * @param args The initialization arguments for the application.
@@ -14279,9 +14759,32 @@ class VApplication {
     get refs() {
         return this.#refs;
     }
+    /**
+     * The custom element hosting this application when it powers a component
+     * (see the #hostElement field). Undefined for regular applications.
+     */
+    get hostElement() {
+        return this.#hostElement;
+    }
+    set hostElement(element) {
+        this.#hostElement = element;
+    }
+    /**
+     * Creates a VNode. Directives that need to build VNode trees at runtime
+     * (e.g. the scoped slot outlet) call this instead of constructing VNode
+     * directly, so they can keep their VNode import type-only and avoid a
+     * VNode -> VDirectiveManager -> directive -> VNode module cycle.
+     * @param init The initialization arguments for the virtual node.
+     * @returns The created VNode.
+     */
+    createVNode(init) {
+        return new VNode(init);
+    }
     /**
      * Mounts the application.
      * @param target The CSS selector string or HTMLElement to mount the application to.
+     * @returns This application instance, so `VDOM.createApp(...).mount('#app')`
+     * can be assigned for later access (e.g. `app.bindings`, `app.unmount()`).
      */
     mount(target) {
         let element;
@@ -14312,6 +14815,7 @@ class VApplication {
         });
         element.removeAttribute('v-cloak');
         this.#logger.info('Application mounted.');
+        return this;
     }
     /**
      * Unmounts the application and cleans up resources.
@@ -14362,7 +14866,15 @@ class VApplication {
             else {
                 buffer = null;
                 if (node.nodeType === Node.ELEMENT_NODE) {
-                    this.#cleanElement(node);
+                    const child = node;
+                    // Do not clean inside an expanded component: its DOM belongs
+                    // to the component's own application, and removing rendered
+                    // (possibly empty) text nodes would detach them from that
+                    // application's virtual nodes, freezing its output.
+                    if (IchigoElementRegistry.has(child.tagName) && child._ichigoExpanded === true) {
+                        continue;
+                    }
+                    this.#cleanElement(child);
                 }
             }
         }
@@ -14758,7 +15270,8 @@ class VApplication {
      */
     #emit(name, detail, options) {
         // Documentation/validation only: warn when emitting an event not declared in `emits`.
-        if (this.#options.emits && !this.#options.emits.includes(name)) {
+        // `update:*` events are the component v-model convention and are always allowed.
+        if (this.#options.emits && !name.startsWith('update:') && !this.#options.emits.includes(name)) {
             this.#logger.warn(`Event '${name}' is emitted but not declared in the 'emits' option.`);
         }
         const target = options?.target ?? this.#vNode?.node;
@@ -14861,13 +15374,19 @@ class VDOM {
  * Mount timing:
  *  - If the component declares no props, the VApplication is mounted synchronously
  *    at the end of connectedCallback (the template is known, no props to wait for).
- *  - If the component declares props, the VApplication is mounted the first time
- *    _setProp() is called after connectedCallback has prepared the DOM. This
- *    guarantees that the parent framework (e.g. ichigo.js VBindDirective) has
- *    already delivered at least one prop value before data() is evaluated.
+ *  - If the component declares props, a mount microtask is scheduled at the end of
+ *    connectedCallback. Prop values delivered synchronously by the parent framework
+ *    (VBindDirective runs within the parent's mount task) are stored before the
+ *    microtask fires, so data() can read them. A component used without any prop
+ *    binding still mounts — with its declared defaults — instead of waiting forever.
  *
- * Subclasses must set the static fields _template, _props and _buildOptions before
- * calling customElements.define(). defineComponent() handles this automatically.
+ * Slot content is captured on the first connection and cached, so a component
+ * that is moved in the DOM (e.g. reordered by v-for) re-expands its template
+ * and redistributes the same slot nodes on reconnection.
+ *
+ * Subclasses must set the static fields _template, _props, _propOptions and
+ * _buildOptions before calling customElements.define(). defineComponent()
+ * handles this automatically.
  */
 class IchigoElement extends HTMLElement {
     /**
@@ -14887,43 +15406,118 @@ class IchigoElement extends HTMLElement {
      * Whether a mount microtask is already queued to avoid double-mounting.
      */
     #mountScheduled = false;
+    /**
+     * Slot content captured on the first connection. Reused on reconnection
+     * (v-for reorder moves the host element, which re-runs connectedCallback
+     * with the previously expanded template as children — not authored slot
+     * content — so the original capture must be redistributed instead).
+     * `scopedSlots` holds `<template v-slot:...>` children by slot name; they
+     * are rendered per outlet by VSlotOutletDirective, not distributed here.
+     */
+    #slotCache;
+    /**
+     * True once this element's children are the expanded component template.
+     * Read by VNode during compilation: a parent application must not compile
+     * an expanded component's internals as its own template (the internals
+     * belong to this component's VApplication and scope).
+     */
+    _ichigoExpanded = false;
+    /**
+     * Host context installed by the parent application's VNode when it
+     * compiles this element. Gives component-boundary features (e.g. scoped
+     * slot outlets) access to the parent scope. Undefined when the element is
+     * placed outside any ichigo application.
+     */
+    _ichigoHost;
+    /**
+     * The scoped slot templates captured from this element's children, keyed
+     * by slot name ('default' for `v-slot` without a name). Read by
+     * VSlotOutletDirective when the component template renders a `<slot>`.
+     */
+    get _ichigoScopedSlots() {
+        return this.#slotCache?.scopedSlots;
+    }
     connectedCallback() {
-        // --- 0. Guard: skip if template not yet loaded ---
+        // --- 0a. Guard: do not expand a template-source element ---
+        // An element still carrying a templatizing directive attribute (v-if
+        // family / v-for) is a template source: the owning application clones it
+        // and inserts the clones (whose directive attributes are stripped during
+        // clone compilation, so the clones expand normally). Expanding the source
+        // here would bake the expansion into every clone, and the clone's
+        // internals would then be compiled in the parent scope.
+        if (this.hasAttribute(StandardDirectiveName.V_IF) ||
+            this.hasAttribute(StandardDirectiveName.V_ELSE_IF) ||
+            this.hasAttribute(StandardDirectiveName.V_ELSE) ||
+            this.hasAttribute(StandardDirectiveName.V_FOR)) {
+            return;
+        }
+        // --- 0b. Reclaim prop values assigned before upgrade ---
+        // A plain property set on the instance (e.g. by a binding delivered
+        // while the element was detached or not yet upgraded) is an own data
+        // property that shadows the prototype accessor generated by
+        // defineComponent — later assignments would keep writing to it and
+        // never reach _setProp. Delete the own property and replay the value
+        // through the accessor.
+        const ctor = this.constructor;
+        for (const prop of ctor._props) {
+            if (Object.prototype.hasOwnProperty.call(this, prop)) {
+                const value = this[prop];
+                delete this[prop];
+                this[prop] = value;
+            }
+        }
+        // --- 0c. Guard: skip if template not yet loaded ---
         // customElements.define() may run before loadComponent() completes (e.g. when
         // dynamic imports are inlined by the bundler). The static placeholder element
         // in the HTML will be removed and replaced by v-for once the template is ready,
         // so it is safe to do nothing here.
-        const ctor = this.constructor;
         const templateEl = document.querySelector(ctor._template);
         if (!templateEl || !(templateEl instanceof HTMLTemplateElement)) {
             return;
         }
-        // --- 1. Capture slot content before clearing children ---
-        const defaultSlotNodes = [];
-        const namedSlotNodes = new Map();
-        for (const child of Array.from(this.childNodes)) {
-            if (child.nodeType === Node.ELEMENT_NODE) {
-                const el = child;
-                const slotName = el.getAttribute('slot');
-                if (slotName) {
-                    if (!namedSlotNodes.has(slotName)) {
-                        namedSlotNodes.set(slotName, []);
+        // --- 1. Capture slot content (first connection only) ---
+        if (!this.#slotCache) {
+            const defaultNodes = [];
+            const namedNodes = new Map();
+            const scopedSlots = new Map();
+            for (const child of Array.from(this.childNodes)) {
+                if (child.nodeType === Node.ELEMENT_NODE) {
+                    const el = child;
+                    // <template v-slot:name="scopeVar"> — a scoped slot template.
+                    // Captured for per-outlet rendering (VSlotOutletDirective),
+                    // not distributed statically.
+                    if (el instanceof HTMLTemplateElement) {
+                        const scoped = this.#parseVSlotAttribute(el);
+                        if (scoped) {
+                            scopedSlots.set(scoped.name, { template: el, scopeVar: scoped.scopeVar });
+                            continue;
+                        }
+                    }
+                    const slotName = el.getAttribute('slot');
+                    if (slotName) {
+                        if (!namedNodes.has(slotName)) {
+                            namedNodes.set(slotName, []);
+                        }
+                        namedNodes.get(slotName).push(el);
+                        // Remove slot attribute so ichigo.js doesn't try to bind it
+                        el.removeAttribute('slot');
+                    }
+                    else {
+                        defaultNodes.push(el);
                     }
-                    namedSlotNodes.get(slotName).push(el);
-                    // Remove slot attribute so ichigo.js doesn't try to bind it
-                    el.removeAttribute('slot');
-                }
-                else {
-                    defaultSlotNodes.push(el);
                 }
-            }
-            else if (child.nodeType === Node.TEXT_NODE) {
-                if ((child.textContent ?? '').trim()) {
-                    defaultSlotNodes.push(child);
+                else if (child.nodeType === Node.TEXT_NODE) {
+                    if ((child.textContent ?? '').trim()) {
+                        defaultNodes.push(child);
+                    }
                 }
             }
+            this.#slotCache = { defaultNodes, namedNodes, scopedSlots };
         }
-        // Clear host element so we can append the cloned template
+        const { defaultNodes, namedNodes } = this.#slotCache;
+        // Clear host element so we can append the cloned template.
+        // (On reconnection this discards the previous expansion; the cached slot
+        // nodes are still referenced and are moved into the fresh clone below.)
         while (this.firstChild) {
             this.removeChild(this.firstChild);
         }
@@ -14931,7 +15525,7 @@ class IchigoElement extends HTMLElement {
         const fragment = templateEl.content.cloneNode(true);
         const root = this.#findRootElement(fragment);
         // --- 3. Distribute named slot content ---
-        for (const [name, nodes] of namedSlotNodes) {
+        for (const [name, nodes] of namedNodes) {
             const slot = root.querySelector(`slot[name="${name}"]`);
             if (slot) {
                 slot.replaceWith(...nodes);
@@ -14939,22 +15533,25 @@ class IchigoElement extends HTMLElement {
         }
         // --- 4. Distribute default slot content ---
         const defaultSlot = root.querySelector('slot:not([name])');
-        if (defaultSlot && defaultSlotNodes.length > 0) {
-            defaultSlot.replaceWith(...defaultSlotNodes);
+        if (defaultSlot && defaultNodes.length > 0) {
+            defaultSlot.replaceWith(...defaultNodes);
         }
         // Attach the populated template to the host element
         this.appendChild(root);
         this.#mountRoot = root;
-        // If props were set before connectedCallback, ensure mount is scheduled
-        this.#scheduleMountIfNeeded();
+        this._ichigoExpanded = true;
         // --- 5. Mount strategy ---
-        // If this component has no declared props, mount immediately.
-        // If it has props, mount will be triggered from _setProp() once the parent
-        // delivers the first prop value (via VBindDirective / forceUpdate).
+        // No declared props: mount immediately (nothing to wait for).
+        // Declared props: schedule a mount microtask unconditionally. Prop values
+        // pushed synchronously by the parent (VBindDirective) land before the
+        // microtask runs; a component used without any binding still mounts,
+        // with its declared defaults.
         if (ctor._props.length === 0) {
             this.#doMount();
         }
-        // else: wait for _setProp() to trigger #scheduleMountIfNeeded()
+        else {
+            this.#scheduleMountIfNeeded();
+        }
     }
     disconnectedCallback() {
         this.#mountRoot = undefined;
@@ -14968,8 +15565,17 @@ class IchigoElement extends HTMLElement {
      * Called by the property setters generated by defineComponent().
      * Before mount: stores the value and schedules a mount microtask.
      * After mount: pushes the value directly into the reactive bindings.
+     * An undefined value is replaced by the prop's declared default, if any.
      */
     _setProp(name, value) {
+        const ctor = this.constructor;
+        const opts = ctor._propOptions[name];
+        if (opts) {
+            if (value === undefined) {
+                value = IchigoElement.#resolveDefault(opts);
+            }
+            this.#validateProp(name, value, opts);
+        }
         this.#propValues[name] = value;
         if (this.#app) {
             this.#app.bindings?.set(name, value);
@@ -14990,9 +15596,16 @@ class IchigoElement extends HTMLElement {
      */
     static _template;
     /**
-     * List of declared prop names. Used to decide whether to defer mounting.
+     * List of declared prop names. Used to decide whether to defer mounting,
+     * and by VBindDirective to resolve kebab-case attributes to prop names.
      */
     static _props = [];
+    /**
+     * Per-prop declaration options (type / default / required / validator),
+     * keyed by prop name. Normalized by defineComponent(): a prop declared
+     * without options gets an empty object.
+     */
+    static _propOptions = {};
     /**
      * Factory that builds VApplicationOptions from the current prop values.
      * Implemented by defineComponent() as a closure that captures the user's options.
@@ -15001,7 +15614,8 @@ class IchigoElement extends HTMLElement {
     // --- Private helpers ---
     /**
      * Schedules a mount microtask if the DOM root is ready and no mount is pending.
-     * Called from _setProp() so the mount happens after the prop value is stored.
+     * Called from connectedCallback and _setProp() so the mount happens after
+     * synchronously delivered prop values are stored.
      */
     #scheduleMountIfNeeded() {
         if (this.#mountScheduled || this.#app || !this.#mountRoot) {
@@ -15018,10 +15632,85 @@ class IchigoElement extends HTMLElement {
             return;
         }
         const ctor = this.constructor;
+        // Attribute fallback: a prop that never received a property value may
+        // have been provided as a plain HTML attribute — static usage like
+        // <my-badge label="x">, or a binding delivered by setAttribute before
+        // the element was upgraded. Attribute values are strings; a declared
+        // Boolean type turns presence ("") into true, and a declared Number
+        // type parses numeric strings.
+        for (const name of ctor._props) {
+            if (this.#propValues[name] !== undefined) {
+                continue;
+            }
+            const attr = this.getAttribute(IchigoElement.#camelToKebab(name)) ?? this.getAttribute(name.toLowerCase());
+            if (attr === null) {
+                continue;
+            }
+            const opts = ctor._propOptions[name];
+            let value = attr;
+            if (opts && IchigoElement.#typeIncludes(opts.type, Boolean) && attr === '') {
+                value = true;
+            }
+            else if (opts && IchigoElement.#typeIncludes(opts.type, Number) && attr !== '' && !Number.isNaN(Number(attr))) {
+                value = Number(attr);
+            }
+            if (opts) {
+                this.#validateProp(name, value, opts);
+            }
+            this.#propValues[name] = value;
+        }
+        // Resolve defaults for props that never received a value, and report
+        // missing required props (warning only; the mount proceeds either way).
+        for (const [name, opts] of Object.entries(ctor._propOptions)) {
+            if (this.#propValues[name] === undefined) {
+                const resolved = IchigoElement.#resolveDefault(opts);
+                if (resolved !== undefined) {
+                    this.#propValues[name] = resolved;
+                }
+                else if (opts.required) {
+                    this.#warn(`required prop '${name}' is missing`);
+                }
+            }
+        }
         const options = ctor._buildOptions(this.#propValues);
         this.#app = VDOM.createApp(options);
+        // Give the application a handle back to this host element so
+        // component-boundary features (e.g. scoped slot outlets) can reach the
+        // captured slot templates and the parent application scope.
+        this.#app.hostElement = this;
         this.#app.mount(this.#mountRoot);
     }
+    /**
+     * Parses a `v-slot` declaration on a `<template>` child, accepting
+     * `v-slot` / `v-slot:name` and the `#name` shorthand. Returns the slot
+     * name ('default' when omitted) and the scope variable name, or undefined
+     * when the template carries no v-slot attribute. The scope variable must
+     * be a single identifier; an invalid one is ignored with a warning.
+     */
+    #parseVSlotAttribute(template) {
+        for (const attr of Array.from(template.attributes)) {
+            let name;
+            if (attr.name === 'v-slot') {
+                name = 'default';
+            }
+            else if (attr.name.startsWith('v-slot:')) {
+                name = attr.name.substring(7);
+            }
+            else if (attr.name.startsWith('#')) {
+                name = attr.name.substring(1);
+            }
+            if (name === undefined || name === '') {
+                continue;
+            }
+            let scopeVar = attr.value.trim();
+            if (scopeVar && !/^[A-Za-z_$][\w$]*$/.test(scopeVar)) {
+                this.#warn(`v-slot scope must be a single identifier; '${scopeVar}' is ignored (destructuring is not supported)`);
+                scopeVar = '';
+            }
+            return { name, scopeVar };
+        }
+        return undefined;
+    }
     #findRootElement(fragment) {
         for (const node of Array.from(fragment.childNodes)) {
             if (node.nodeType === Node.ELEMENT_NODE) {
@@ -15030,6 +15719,74 @@ class IchigoElement extends HTMLElement {
         }
         throw new Error(`IchigoElement: no root element found in template '${this.constructor._template}'`);
     }
+    /**
+     * Resolves a prop's default value. A function default is called as a
+     * factory unless the declared type includes Function, in which case the
+     * function itself is the value.
+     */
+    static #resolveDefault(opts) {
+        const def = opts.default;
+        if (def === undefined) {
+            return undefined;
+        }
+        if (typeof def === 'function' && !IchigoElement.#typeIncludes(opts.type, Function)) {
+            return def();
+        }
+        return def;
+    }
+    static #typeIncludes(type, ctor) {
+        if (!type) {
+            return false;
+        }
+        return Array.isArray(type) ? type.includes(ctor) : type === ctor;
+    }
+    static #camelToKebab(str) {
+        return str.replace(/([A-Z])/g, '-$1').toLowerCase();
+    }
+    /**
+     * Validates a delivered prop value against its declaration.
+     * Warnings only — the value is stored and delivered regardless.
+     * null/undefined values skip both checks (undefined is handled by
+     * default/required; null is an explicit "no value").
+     */
+    #validateProp(name, value, opts) {
+        if (value === null || value === undefined) {
+            return;
+        }
+        if (opts.type) {
+            const types = Array.isArray(opts.type) ? opts.type : [opts.type];
+            if (!types.some(t => IchigoElement.#matchesType(value, t))) {
+                const expected = types.map(t => t.name ?? String(t)).join(' | ');
+                const actual = typeof value === 'object'
+                    ? (value?.constructor?.name ?? 'object')
+                    : typeof value;
+                this.#warn(`prop '${name}' expects ${expected}, got ${actual}`);
+            }
+        }
+        if (opts.validator && !opts.validator(value)) {
+            this.#warn(`prop '${name}' failed its validator`);
+        }
+    }
+    static #matchesType(value, type) {
+        switch (type) {
+            case String: return typeof value === 'string';
+            case Number: return typeof value === 'number';
+            case Boolean: return typeof value === 'boolean';
+            case Function: return typeof value === 'function';
+            case Array: return Array.isArray(value);
+            case Object: return typeof value === 'object' && value !== null && !Array.isArray(value);
+            default:
+                try {
+                    return value instanceof type;
+                }
+                catch {
+                    return false;
+                }
+        }
+    }
+    #warn(message) {
+        console.warn(`[ichigo] <${this.tagName.toLowerCase()}>: ${message}`);
+    }
 }
 
 // Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
@@ -15050,9 +15807,8 @@ class IchigoElement extends HTMLElement {
  * ```typescript
  * defineComponent('my-list', {
  *   template: '#my-list',
- *   props: ['items'],
- *   data() {
- *     return { items: this.items ?? [] };
+ *   props: {
+ *     items: { type: Array, default: () => [] },
  *   },
  * });
  * ```
@@ -15062,15 +15818,34 @@ class IchigoElement extends HTMLElement {
  * </my-list>
  * ```
  *
+ * Props may be declared as a simple name list (`props: ['items']`) or as a
+ * record with per-prop options (type / default / required / validator).
+ * See {@link PropOptions} for the declaration semantics.
+ *
  * @param tagName  Custom element tag name (must contain a hyphen, e.g. 'my-card').
  * @param options  Component options including template selector and optional props.
  */
 function defineComponent(tagName, options) {
     const { props = [], template, data, computed, methods, watch, emits, logLevel } = options;
+    // Normalize the props declaration: a plain name list becomes a record of
+    // empty option objects so the rest of the code handles a single shape.
+    const propOptions = {};
+    if (Array.isArray(props)) {
+        for (const name of props) {
+            propOptions[name] = {};
+        }
+    }
+    else {
+        for (const [name, opts] of Object.entries(props)) {
+            propOptions[name] = opts ?? {};
+        }
+    }
+    const propNames = Object.keys(propOptions);
     // Build a subclass of IchigoElement specific to this component
     class ComponentElement extends IchigoElement {
         static _template = template;
-        static _props = props;
+        static _props = propNames;
+        static _propOptions = propOptions;
         static _buildOptions(propValues) {
             return {
                 data() {
@@ -15095,7 +15870,7 @@ function defineComponent(tagName, options) {
     }
     // Generate a property getter/setter for each declared prop.
     // This enables the parent VApplication to push updates via `element.propName = value`.
-    for (const prop of props) {
+    for (const prop of propNames) {
         Object.defineProperty(ComponentElement.prototype, prop, {
             get() {
                 return this._getProp(prop);
@@ -15108,6 +15883,8 @@ function defineComponent(tagName, options) {
         });
     }
     customElements.define(tagName, ComponentElement);
+    // Record the tag so VNode can recognize component boundaries during compilation.
+    IchigoElementRegistry.add(tagName);
 }
 
 export { ExpressionUtils, IchigoElement, ReactiveProxy, VComponent, VComponentRegistry, VDOM, defineComponent, toDisplayString };