mikuru 1.0.21 → 1.0.22

package/CHANGELOG.md

@@ -1,6 +1,22 @@
 # Changelog
 
-## Unreleased
+## 1.0.22 - 2026-05-13
+
+- Generalized component slot hydration to pass default, named, dynamic, and scoped slots through `props.children` and `props.slots`.
+- Improved SSR component slots so dynamic slot names support scoped props and explicit default slot templates are exposed through `props.children`.
+- Added async component hydration delegation so SSR-rendered async children inside `<AsyncBoundary>` can be reused after streaming SSR.
+- Improved async component hydration fallback handling for loader errors, timeouts, and retry recovery.
+- Added Teleport + AsyncBoundary hydration coverage for SSR target reuse, async child hydration, and sibling stability.
+- Added route SSR Teleport collection and RouterView + Teleport hydration coverage.
+- Added Teleport + ErrorBoundary hydration coverage for target-side DOM reuse and cleanup.
+- Added Transition and TransitionGroup async-child hydration coverage for DOM reuse, keyed order, and cleanup.
+- Added nested AsyncBoundary streaming SSR hydration coverage for parent/child async DOM reuse and cleanup.
+- Added nested lazy RouterView SSR hydration coverage with route-level Teleport reuse.
+- Expanded SSR/hydration examples and E2E coverage for lazy route Teleport and nested AsyncBoundary Teleport patterns.
+- Added nested AsyncBoundary error and timeout hydration coverage for inner fallback retry, sibling stability, and cleanup.
+- Added SSR `v-model` form-control state rendering for input, textarea, checkbox, radio, select, and multiple select hydration parity.
+- Improved hydration diagnostics with phase/component/file context and `hydration:warning` devtools events.
+- Updated README and docs to reflect current SSR/hydration, router, diagnostics, examples, and release checklist coverage.
 
 ## 1.0.21 - 2026-05-13
 

package/README.md

@@ -148,6 +148,7 @@ declare const Greeting: MikuruComponent<GreetingProps>;
 - Hydration through `compileHydration()` and `hydrateRoute()`, reusing existing SSR DOM while attaching events, syncing text/attributes, recovering structural mismatches with an opt-out remount fallback, hydrating component context/lifecycle hooks, `v-show`, DOM and component `v-model`, `v-pre`, `v-cloak`, initial `v-if` / `v-for` DOM, Teleport target and disabled inline content, delegating child and route components to `hydrate()` when available, and optionally starting router history listening after route hydration
 - Style injection and basic `<style scoped>` selector rewriting
 - Compile errors with filenames, line/column information, code frames, and typo suggestions for built-in attributes, directives, and modifiers
+- Debug diagnostics with optional generated `sourceURL`, unstable devtools metadata/events, and hydration warnings that include phase, component, and filename context
 
 ## Package Exports
 
@@ -268,4 +269,5 @@ npm run dev:mikuru-vue-like
 - `docs/npm-usage.md` shows a manual Vite setup for package consumers.
 - `docs/app-architecture.md` describes how to keep larger Mikuru apps split across components, API modules, stores, forms, auth, and tests.
 - `docs/router.md` documents the runtime router.
+- `docs/production-readiness.md` summarizes debugging, parser, package, SSR, and hydration caveats.
 - `docs/v1-api-contract.md` describes the v1 compatibility boundary used by this repository.

package/dist/compiler/generateHydration.js

@@ -1,3 +1,4 @@
+import { createCompileError } from "./errors.js";
 import { compileTemplateExpression, parseForExpression, validateAssignableExpression } from "./parseExpression.js";
 export function generateHydration(descriptor, root, options = {}) {
     const context = {
@@ -36,7 +37,9 @@ export function generateHydration(descriptor, root, options = {}) {
     emit(context, 2, "},");
     emit(context, 2, "registerEffect: (fn) => Promise.resolve().then(fn)");
     emit(context, 1, "};");
-    emit(context, 1, "const __mikuru_warn = (message) => { if (typeof console !== \"undefined\" && console.warn) console.warn(`[Mikuru hydration] ${message}`); };");
+    emit(context, 1, "const __mikuru_emitDebug = (type, payload) => { const hook = globalThis.__MIKURU_DEVTOOLS__; if (!hook) return; const event = { type, timestamp: Date.now(), payload }; hook.events ??= []; hook.events.push(event); if (typeof hook.emit === \"function\") hook.emit(event); for (const listener of hook.listeners ?? []) { try { listener(event); } catch (error) { setTimeout(() => { throw error; }); } } };");
+    emit(context, 1, "const __mikuru_hydrationDiagnostic = (message, details = {}) => ({ ...__mikuru_componentInfo, phase: \"hydration\", message, ...details });");
+    emit(context, 1, "const __mikuru_warn = (message, details = {}) => { const diagnostic = __mikuru_hydrationDiagnostic(message, details); __mikuru_emitDebug(\"hydration:warning\", diagnostic); if (typeof console !== \"undefined\" && console.warn) console.warn(`[Mikuru hydration] ${message} (phase: ${diagnostic.phase}, component: ${diagnostic.component}, file: ${diagnostic.filename})`); };");
     emit(context, 1, "const __mikuru_describeNode = (node) => { if (!node) return \"missing\"; if (node.nodeType === 1) return `<${node.tagName?.toLowerCase?.() ?? \"element\"}>`; if (node.nodeType === 3) return `text(${JSON.stringify(node.nodeValue ?? \"\")})`; if (node.nodeType === 8) return `comment(${JSON.stringify(node.nodeValue ?? \"\")})`; return `nodeType(${node.nodeType})`; };");
     emit(context, 1, "const __mikuru_restoreRegistrar = () => { if (__mikuru_previousRegistrar === undefined) { delete globalThis.__mikuru_currentRegistrar; } else { globalThis.__mikuru_currentRegistrar = __mikuru_previousRegistrar; } };");
     emit(context, 1, "const __mikuru_recovery = {};");
@@ -134,6 +137,7 @@ function hydrateElement(context, node, elementVar, indent) {
     hydrateAttrs(context, node, elementVar, indent);
     hydrateEvents(context, node, elementVar, indent);
     const contentDirective = getContentDirectiveAttr(node);
+    const textareaModel = node.tag === "textarea" && hasElementModel(node);
     const hydrateChildrenBeforeModel = node.tag === "select" && !contentDirective;
     if (hydrateChildrenBeforeModel) {
         hydrateChildren(context, node.children, elementVar, indent);
@@ -141,7 +145,10 @@ function hydrateElement(context, node, elementVar, indent) {
     hydrateModelAndShow(context, node, elementVar, indent);
     hydrateContentDirective(context, node, elementVar, indent);
     hydrateTemplateRef(context, node, elementVar, indent);
-    if (!contentDirective && !hydrateChildrenBeforeModel) {
+    if (textareaModel) {
+        emit(context, indent, `if (${elementVar}.childNodes.length > 0) { const __mikuru_textarea_value = ${elementVar}.value; ${elementVar}.textContent = ""; ${elementVar}.value = __mikuru_textarea_value; }`);
+    }
+    if (!contentDirective && !hydrateChildrenBeforeModel && !textareaModel) {
         hydrateChildren(context, node.children, elementVar, indent);
     }
 }
@@ -446,35 +453,134 @@ function emitRouterViewRouteSlot(context, node, propsVar, indent) {
     emit(context, indent, `if (typeof props.children === "function") { ${propsVar}.children = props.children; ${propsVar}.slots = { ...(${propsVar}.slots ?? {}), default: props.children }; }`);
 }
 function emitHydrationComponentSlots(context, node, propsVar, indent) {
-    const children = getDefaultHydrationSlotChildren(node);
-    if (!children || !hasMeaningfulHydrationChildren(children)) {
+    const slots = collectHydrationComponentSlots(context, node);
+    if (slots.length === 0) {
         return;
     }
+    const defaultSlot = slots.find((slot) => !slot.nameExpression && slot.name === "default");
+    if (defaultSlot) {
+        emitHydrationSlotFunction(context, `${propsVar}.children`, defaultSlot, indent);
+    }
+    emit(context, indent, `${propsVar}.slots = { ...(${propsVar}.slots ?? {}) };`);
+    for (const slot of slots) {
+        const property = slot.nameExpression ? `[${slot.nameExpression}]` : `[${quote(slot.name)}]`;
+        emitHydrationSlotFunction(context, `${propsVar}.slots${property}`, slot, indent);
+    }
+}
+function emitHydrationSlotFunction(context, target, slot, indent) {
     const slotTargetVar = nextName(context, "slotTarget");
     const slotPropsVar = nextName(context, "slotProps");
-    emit(context, indent, `${propsVar}.children = (${slotTargetVar}, ${slotPropsVar} = {}) => {`);
-    hydrateChildren(context, children, slotTargetVar, indent + 1);
+    emit(context, indent, `${target} = (${slotTargetVar}, ${slotPropsVar} = {}) => {`);
+    emitHydrationSlotScopeBindings(context, slot, slotPropsVar, indent + 1);
+    hydrateChildren(context, slot.children, slotTargetVar, indent + 1);
     emit(context, indent, "};");
-    emit(context, indent, `${propsVar}.slots = { ...(${propsVar}.slots ?? {}), default: ${propsVar}.children };`);
 }
-function getDefaultHydrationSlotChildren(node) {
+function emitHydrationSlotScopeBindings(context, slot, slotPropsVar, indent) {
+    for (const binding of parseHydrationSlotScopeBindings(slot.scope, context, slot.scopeLoc ?? slot.loc)) {
+        if (binding.kind === "props") {
+            emit(context, indent, `const ${binding.alias} = ${slotPropsVar};`);
+            continue;
+        }
+        if (binding.kind === "rest") {
+            emit(context, indent, `const ${binding.alias} = { get value() { const rest = { ...${slotPropsVar} }; ${binding.exclude.map((key) => `delete rest[${quote(key)}];`).join(" ")} return rest; } };`);
+            continue;
+        }
+        const valueExpression = slotScopePathExpression(slotPropsVar, binding.path);
+        if (binding.defaultValue) {
+            emit(context, indent, `const ${binding.alias} = { get value() { const value = ${valueExpression}; return value === undefined ? (${binding.defaultValue}) : value; } };`);
+            continue;
+        }
+        emit(context, indent, `const ${binding.alias} = { get value() { return ${valueExpression}; } };`);
+    }
+}
+function slotScopePathExpression(rootVar, path) {
+    return path.reduce((expression, key, index) => {
+        const property = /^[A-Za-z_$][\w$]*$/.test(key) ? `.${key}` : `[${quote(key)}]`;
+        return `${expression}${index === 0 ? property : `?.${property.slice(1)}`}`;
+    }, rootVar);
+}
+function collectHydrationComponentSlots(context, node) {
+    const slots = [];
+    const usedNames = new Set();
     const defaultChildren = [];
     for (const child of node.children) {
         if (child.type === "element" && child.tag === "template") {
-            const defaultSlotAttr = child.attrs.find(isDefaultSlotTemplateAttr);
-            if (defaultSlotAttr) {
-                return child.children;
-            }
-            if (child.attrs.some(isSlotTemplateAttr)) {
+            const slotDirective = getHydrationSlotTemplateDirective(child, context);
+            if (slotDirective) {
+                if (usedNames.has(slotDirective.name)) {
+                    throwTemplateError(`Duplicate slot template: ${slotDirective.name}`, context, slotDirective.loc);
+                }
+                usedNames.add(slotDirective.name);
+                slots.push({
+                    name: slotDirective.name,
+                    nameExpression: slotDirective.nameExpression,
+                    children: child.children,
+                    scope: slotDirective.scope,
+                    loc: child.loc,
+                    scopeLoc: slotDirective.scopeLoc
+                });
                 continue;
             }
         }
         defaultChildren.push(child);
     }
-    return defaultChildren;
+    if (hasMeaningfulHydrationChildren(defaultChildren)) {
+        if (usedNames.has("default")) {
+            throwTemplateError("Duplicate slot template: default", context, node.loc);
+        }
+        slots.unshift({
+            name: "default",
+            children: defaultChildren,
+            scope: true,
+            loc: node.loc
+        });
+    }
+    return slots;
+}
+function getHydrationSlotTemplateDirective(node, context) {
+    const slotAttrs = node.attrs.filter((attr) => isSlotTemplateAttr(attr));
+    if (slotAttrs.length === 0) {
+        return undefined;
+    }
+    if (slotAttrs.length > 1) {
+        throwTemplateError("A slot template can only declare one slot target", context, slotAttrs[1]?.loc);
+    }
+    const attr = slotAttrs[0];
+    const name = getHydrationSlotTemplateName(attr, context);
+    return {
+        ...name,
+        scope: attr.value,
+        loc: attr.loc,
+        scopeLoc: attr.valueLoc
+    };
+}
+function getHydrationSlotTemplateName(attr, context) {
+    if (attr.name === "v-slot") {
+        return { name: "default" };
+    }
+    if (attr.name.startsWith("v-slot:")) {
+        return parseHydrationSlotTemplateName(attr.name.slice("v-slot:".length) || "default", attr, context);
+    }
+    if (attr.name.startsWith("#")) {
+        return parseHydrationSlotTemplateName(attr.name.slice(1) || "default", attr, context);
+    }
+    return { name: "default" };
 }
-function isDefaultSlotTemplateAttr(attr) {
-    return attr.name === "v-slot" || attr.name === "v-slot:default" || attr.name === "#default";
+function parseHydrationSlotTemplateName(rawName, attr, context) {
+    const name = rawName.trim();
+    const dynamicStart = name.indexOf("[");
+    const dynamicEnd = name.lastIndexOf("]");
+    if (dynamicStart >= 0 && dynamicEnd > dynamicStart) {
+        const expression = name.slice(dynamicStart + 1, dynamicEnd).trim();
+        if (!expression) {
+            throwTemplateError("Dynamic slot name requires an expression", context, attr.loc);
+        }
+        return {
+            name: `[${expression}]`,
+            nameExpression: compileTemplateExpression(expression, attr.name, toExpressionContext(context, attr.loc))
+        };
+    }
+    return { name };
 }
 function isSlotTemplateAttr(attr) {
     return attr.name === "v-slot" || attr.name.startsWith("v-slot:") || attr.name.startsWith("#");
@@ -482,6 +588,102 @@ function isSlotTemplateAttr(attr) {
 function hasMeaningfulHydrationChildren(children) {
     return children.some((child) => child.type === "element" || child.parts.some((part) => part.value.trim()));
 }
+function parseHydrationSlotScopeBindings(scope, context, location) {
+    if (scope === true || !scope.trim()) {
+        return [];
+    }
+    const source = scope.trim();
+    if (isIdentifier(source)) {
+        return [{ kind: "props", alias: source }];
+    }
+    if (!source.startsWith("{") || !source.endsWith("}")) {
+        throwTemplateError("Slot scope must be an identifier or object destructuring pattern", context, location);
+    }
+    const body = source.slice(1, -1).trim();
+    if (!body) {
+        return [];
+    }
+    return parseHydrationSlotScopeObjectPattern(body, context, location, []);
+}
+function parseHydrationSlotScopeObjectPattern(body, context, location, pathPrefix) {
+    const bindings = [];
+    const excludedTopLevelKeys = [];
+    for (const part of splitTopLevel(body, ",")) {
+        const sourcePart = part.trim();
+        if (!sourcePart) {
+            continue;
+        }
+        if (sourcePart.startsWith("...")) {
+            const alias = sourcePart.slice(3).trim();
+            if (pathPrefix.length > 0) {
+                throwTemplateError("Slot scope rest destructuring is only supported at the top level", context, location);
+            }
+            if (!isIdentifier(alias)) {
+                throwTemplateError("Slot scope rest destructuring must use a simple identifier like ...rest", context, location);
+            }
+            bindings.push({ kind: "rest", alias, exclude: excludedTopLevelKeys });
+            continue;
+        }
+        const { left, right } = splitHydrationSlotScopeEntry(sourcePart, context, location);
+        if (!isIdentifier(left)) {
+            throwTemplateError(`Unsupported slot scope key "${left}". Use identifier keys in slot scope destructuring`, context, location);
+        }
+        if (pathPrefix.length === 0) {
+            excludedTopLevelKeys.push(left);
+        }
+        const path = [...pathPrefix, left];
+        if (right === undefined) {
+            bindings.push(...hydrationSlotScopeLeafBindings(left, path, context, location));
+            continue;
+        }
+        const value = right.trim();
+        if (value.startsWith("{") && value.endsWith("}")) {
+            bindings.push(...parseHydrationSlotScopeObjectPattern(value.slice(1, -1), context, location, path));
+            continue;
+        }
+        if (value.startsWith("[") || value.includes("{")) {
+            throwTemplateError("Slot scope destructuring supports nested object patterns only; array and mixed patterns are not supported", context, location);
+        }
+        bindings.push(...hydrationSlotScopeLeafBindings(value, path, context, location));
+    }
+    return bindings;
+}
+function splitHydrationSlotScopeEntry(source, context, location) {
+    const colonIndex = findTopLevelToken(source, ":");
+    if (colonIndex >= 0) {
+        return {
+            left: source.slice(0, colonIndex).trim(),
+            right: source.slice(colonIndex + 1).trim()
+        };
+    }
+    const equalsIndex = findTopLevelToken(source, "=");
+    if (equalsIndex >= 0) {
+        const left = source.slice(0, equalsIndex).trim();
+        if (!isIdentifier(left)) {
+            throwTemplateError("Slot scope default values can only be assigned to simple identifiers", context, location);
+        }
+        return { left, right: source };
+    }
+    return { left: source.trim() };
+}
+function hydrationSlotScopeLeafBindings(source, path, context, location) {
+    const equalsIndex = findTopLevelToken(source, "=");
+    const localSource = equalsIndex >= 0 ? source.slice(0, equalsIndex).trim() : source.trim();
+    const defaultSource = equalsIndex >= 0 ? source.slice(equalsIndex + 1).trim() : undefined;
+    if (!isIdentifier(localSource)) {
+        throwTemplateError(`Unsupported slot scope binding "${source}". Use identifiers, aliases, defaults, nested objects, or top-level ...rest`, context, location);
+    }
+    return [
+        {
+            kind: "property",
+            path,
+            alias: localSource,
+            defaultValue: defaultSource
+                ? compileTemplateExpression(defaultSource, "slot scope default", toExpressionContext(context, location))
+                : undefined
+        }
+    ];
+}
 function hydrateDynamicComponentAtIndex(context, node, parentVar, domIndex, indent) {
     const isAttr = getDynamicComponentIsAttr(node);
     if (!isAttr) {
@@ -1438,6 +1640,9 @@ function parseModelDirective(name) {
     const [argument = "", ...modifiers] = name.slice("v-model:".length).split(".");
     return { argument, modifiers: modifiers.filter(Boolean) };
 }
+function hasElementModel(node) {
+    return node.attrs.some((attr) => Boolean(parseModelDirective(attr.name)));
+}
 function toComponentEventProp(eventName) {
     return `on${eventName.split(":").map((part) => part ? part[0].toUpperCase() + part.slice(1) : "").join("")}`;
 }
@@ -1510,9 +1715,90 @@ function compileHydrationExpression(context, expression, usage) {
         filename: context.filename
     });
 }
+function toExpressionContext(context, location) {
+    if (!context.source || !location) {
+        return undefined;
+    }
+    return {
+        source: context.source,
+        offset: location.offset,
+        filename: context.filename
+    };
+}
+function throwTemplateError(message, context, location) {
+    if (context.source && location) {
+        throw createCompileError(message, context.source, location.offset, context.filename);
+    }
+    throw new Error(message);
+}
 function isIdentifier(value) {
     return /^[A-Za-z_$][\w$]*$/.test(value);
 }
+function splitTopLevel(source, delimiter) {
+    const parts = [];
+    let depth = 0;
+    let quoteChar = "";
+    let start = 0;
+    for (let index = 0; index < source.length; index += 1) {
+        const char = source[index];
+        const previous = source[index - 1];
+        if (quoteChar) {
+            if (char === quoteChar && previous !== "\\") {
+                quoteChar = "";
+            }
+            continue;
+        }
+        if (char === "\"" || char === "'" || char === "`") {
+            quoteChar = char;
+            continue;
+        }
+        if (char === "{" || char === "[" || char === "(") {
+            depth += 1;
+            continue;
+        }
+        if (char === "}" || char === "]" || char === ")") {
+            depth -= 1;
+            continue;
+        }
+        if (depth === 0 && source.startsWith(delimiter, index)) {
+            parts.push(source.slice(start, index));
+            start = index + delimiter.length;
+            index += delimiter.length - 1;
+        }
+    }
+    parts.push(source.slice(start));
+    return parts;
+}
+function findTopLevelToken(source, token) {
+    let depth = 0;
+    let quoteChar = "";
+    for (let index = 0; index < source.length; index += 1) {
+        const char = source[index];
+        const previous = source[index - 1];
+        if (quoteChar) {
+            if (char === quoteChar && previous !== "\\") {
+                quoteChar = "";
+            }
+            continue;
+        }
+        if (char === "\"" || char === "'" || char === "`") {
+            quoteChar = char;
+            continue;
+        }
+        if (char === "{" || char === "[" || char === "(") {
+            depth += 1;
+            continue;
+        }
+        if (char === "}" || char === "]" || char === ")") {
+            depth -= 1;
+            continue;
+        }
+        if (depth === 0 && source.startsWith(token, index)) {
+            return index;
+        }
+    }
+    return -1;
+}
 function withTemplateRefMode(context, mode, callback) {
     const previousMode = context.templateRefMode;
     context.templateRefMode = mode;