@mintjamsinc/ichigojs 0.1.76 → 0.1.78

package/dist/ichigo.cjs

@@ -7511,6 +7511,14 @@
          * @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;
         }
         /**
@@ -8926,6 +8934,344 @@
         }
     }
 
+    // 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).
@@ -9092,6 +9438,24 @@
         }
         #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.
@@ -9127,8 +9491,6 @@
             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 = {
@@ -9521,7 +9883,14 @@
             }
             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
@@ -9534,8 +9903,19 @@
                         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,
@@ -11573,17 +11953,45 @@
          * 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;
@@ -11755,6 +12163,14 @@
             }
             // 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') {
@@ -11788,6 +12204,19 @@
             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
@@ -11942,11 +12371,52 @@
             }
             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';
@@ -13686,9 +14156,10 @@
                 // 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
@@ -13756,9 +14227,10 @@
                 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
@@ -14182,6 +14654,14 @@
          * 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.
@@ -14285,9 +14765,32 @@
         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;
@@ -14318,6 +14821,7 @@
             });
             element.removeAttribute('v-cloak');
             this.#logger.info('Application mounted.');
+            return this;
         }
         /**
          * Unmounts the application and cleans up resources.
@@ -14368,7 +14872,15 @@
                 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);
                     }
                 }
             }
@@ -14764,7 +15276,8 @@
          */
         #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;
@@ -14867,13 +15380,19 @@
      * 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 {
         /**
@@ -14893,43 +15412,118 @@
          * 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);
             }
@@ -14937,7 +15531,7 @@
             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);
@@ -14945,22 +15539,25 @@
             }
             // --- 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;
@@ -14974,8 +15571,17 @@
          * 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);
@@ -14996,9 +15602,16 @@
          */
         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.
@@ -15007,7 +15620,8 @@
         // --- 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) {
@@ -15024,10 +15638,85 @@
                 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) {
@@ -15036,6 +15725,74 @@
             }
             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.
@@ -15056,9 +15813,8 @@
      * ```typescript
      * defineComponent('my-list', {
      *   template: '#my-list',
-     *   props: ['items'],
-     *   data() {
-     *     return { items: this.items ?? [] };
+     *   props: {
+     *     items: { type: Array, default: () => [] },
      *   },
      * });
      * ```
@@ -15068,15 +15824,34 @@
      * </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() {
@@ -15101,7 +15876,7 @@
         }
         // 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);
@@ -15114,6 +15889,8 @@
             });
         }
         customElements.define(tagName, ComponentElement);
+        // Record the tag so VNode can recognize component boundaries during compilation.
+        IchigoElementRegistry.add(tagName);
     }
 
     exports.ExpressionUtils = ExpressionUtils;