octane 0.1.16 → 0.1.17

package/dist/compiler/compile.js

@@ -2174,6 +2174,96 @@ function rewriteAutoCallback(stmt, stable, componentLocals, ctx) {
 	return modified ? { ...stmt, declarations: newDecls } : stmt;
 }
 
+// Auto-calculation: lower a derived `const X = <expr containing a render-time
+// call>` to `useMemo(() => <expr>, [deps])` so its identity is stable while its
+// inputs are. Without this, an idiomatic `const visible = todos.filter(...)`
+// allocates a fresh array every render, and every downstream consumer keyed on
+// its identity — an autoMemo region's dependency tuple, a memo() child's prop —
+// misses unconditionally. The region cache is only as good as the stability of
+// what it keys on.
+//
+// A calculation is admitted on exactly the callee rule that governs regions
+// (plainCalleeIsMemoizable): the receiver of a member call can return a new
+// answer while its own identity holds, and that hazard does not become safe
+// because the author named the result. `virtualizer.getVirtualItems()` in
+// examples/pulseboard is the same shape as `header.column.getIsSorted()` — its
+// window moves with scroll while the virtualizer instance stays put — so
+// caching it froze a virtualized list mid-scroll. One rule, both paths.
+//
+// The cost of that is real and accepted: `const visible = todos.filter(...)`
+// stays uncached, because `todos.filter` is a member call and this analysis
+// cannot yet prove the receiver is an immutable snapshot rather than a live
+// object. Recovering it needs receiver provenance (does the root trace to a
+// state binding?), which is a separate change with its own evidence.
+//
+// Scope: single-declarator `const` with an Identifier id whose init reaches a
+// render-time call (isPropCreationExpr — no JSX, no hook-shaped calls), whose
+// every call is an admitted projection, whose value the render tree actually
+// reads (memoizing a value nothing renders only adds cells), and whose
+// dependencies are all component locals. Bodies that already went through Pass
+// A′ arrive with hook-shaped inits and are skipped.
+function rewriteAutoCalculation(stmt, componentLocals, renderReadNames, ctx) {
+	if (stmt.type !== 'VariableDeclaration' || stmt.kind !== 'const') return stmt;
+	if (stmt.declarations?.length !== 1) return stmt;
+	const decl = stmt.declarations[0];
+	if (!decl || decl.id?.type !== 'Identifier' || !decl.init) return stmt;
+	if (!renderReadNames.has(decl.id.name)) return stmt;
+	const init = unwrapTsExpr(decl.init);
+	// An arrow/function init is auto-callback's job, not ours.
+	if (FN_TYPES.has(init?.type)) return stmt;
+	if (!isPropCreationExpr(init, ctx)) return stmt;
+	// Every call reached during render must be a proven value projection — the
+	// same admission the region cache uses. A member call fails closed.
+	if (containsRenderCall([init], ctx)) return stmt;
+	const deps = [];
+	const seen = new Set();
+	for (const name of collectFreeIdentifiers(init, [])) {
+		if (name === decl.id.name) return stmt; // self-referential; leave alone
+		if (!componentLocals.has(name)) continue;
+		if (seen.has(name)) continue;
+		seen.add(name);
+		deps.push(name);
+	}
+	// Every free name must be a witnessed component local. An unwitnessed
+	// module/global read would make the cache freeze on something no dependency
+	// can observe, which is a different bargain from the one above.
+	for (const name of collectFreeIdentifiers(init, [])) {
+		if (
+			!componentLocals.has(name) &&
+			!ctx.moduleFunctionDeclarations?.has(name) &&
+			!ctx.importedNames?.has(name)
+		) {
+			return stmt;
+		}
+	}
+	return {
+		...stmt,
+		declarations: [
+			{
+				...decl,
+				init: inheritOriginLoc(
+					b.call(
+						{ ...b.id('useMemo'), _octaneGenerated: true },
+						b.arrow([], init),
+						b.array(deps.map((n) => b.id(n))),
+					),
+					init,
+				),
+			},
+		],
+	};
+}
+
+// Names the render tree actually reads, resolved against the scopes the
+// statement walker cannot see (nested functions, loops, `@for` item bindings,
+// directive-arm blocks) so a shadowing inner binding never nominates an
+// unrelated body const.
+function collectRenderReadNames(jsxNodes, ctx) {
+	const into = new Set();
+	collectUseArgumentRoots(jsxNodes, ctx, into, true, true);
+	return into;
+}
+
 function allocAutoMemoCell(ctx, dependencyCount) {
 	const base = ctx.currentAutoMemoOffset || 0;
 	const init = base + dependencyCount;
@@ -2858,10 +2948,19 @@ function containsRenderCall(stmts, memoCtx = null) {
 	return found;
 }
 
-const HOOK_CALLEE_NAME_RE = /^use[A-Z]/;
+// A hook call is identified by naming convention — the same signal React and
+// React Compiler key on — plus React's own `unstable_` staging prefix, which
+// bindings mirror (`unstable_useRouterState` in @octanejs/remix-router). The
+// prefix is enumerated rather than matched as "any `_use`" so an ordinary
+// helper cannot be mistaken for a hook by spelling alone.
+//
+// Getting this wrong in the permissive direction is not a staleness bug: a
+// cache wrapped around a hook call freezes its subscription and its state cell
+// for the life of the component.
+const HOOK_NAME_CONVENTION_RE = /^(?:unstable_)?use(?:$|[A-Z])/;
 
 function isHookCalleeName(name) {
-	return name === 'use' || HOOK_CALLEE_NAME_RE.test(name);
+	return HOOK_NAME_CONVENTION_RE.test(name);
 }
 
 /**
@@ -9386,6 +9485,19 @@ function compileFunctionBody(node, ctx, name, parentNs = 'html', cssHash = null,
 			creations,
 			puParamNames,
 		);
+		// Auto-calculation runs AFTER Pass A′ so use()-fed chains keep their
+		// Symbol-slot treatment (their rewritten inits are hook-shaped and are
+		// skipped here), and BEFORE Pass A/B so the numeric-slot useMemo it mints is
+		// lowered by the authored inline tier rather than re-wrapped. Client only:
+		// a server render evaluates each body once, so a cache is pure overhead.
+		if (ctx.currentComponentLocals && ctx.mode !== 'server') {
+			const renderReadNames = collectRenderReadNames(jsxNodes, ctx);
+			if (renderReadNames.size > 0) {
+				workingStatements = workingStatements.map((statement) =>
+					rewriteAutoCalculation(statement, ctx.currentComponentLocals, renderReadNames, ctx),
+				);
+			}
+		}
 		workingStatements = parallelUseMemoizePass(workingStatements, ctx, name, creations, [], null);
 		jsxNodes = parallelUseWalkJsx(jsxNodes, ctx, name, creations, warmChildren, [], new Set());
 		const warm = buildWarmArtifacts(node, ctx, name, creations, warmChildren);
@@ -10210,14 +10322,17 @@ function isPropCreationExpr(expr, ctx) {
 	function isHookishCallee(callee) {
 		if (callee.type === 'Identifier') {
 			return (
-				/^use($|[A-Z])/.test(callee.name) || ctx?._parallelUseAliases?.has(callee.name) === true
+				HOOK_NAME_CONVENTION_RE.test(callee.name) ||
+				ctx?._parallelUseAliases?.has(callee.name) === true
 			);
 		}
 		if (
 			(callee.type === 'MemberExpression' || callee.type === 'OptionalMemberExpression') &&
 			!callee.computed
 		) {
-			return callee.property.type === 'Identifier' && /^use($|[A-Z])/.test(callee.property.name);
+			return (
+				callee.property.type === 'Identifier' && HOOK_NAME_CONVENTION_RE.test(callee.property.name)
+			);
 		}
 		return false;
 	}
@@ -10632,8 +10747,14 @@ function memoizeUseFedCreations(stmts, jsxNodes, ctx, componentName, creations,
 // Deep scan (nested functions and render-tree nodes included — a consumer
 // anywhere makes stability load-bearing) for `use(<arg>)` arguments' free
 // identifier roots.
-function collectUseArgumentRoots(root, ctx, into, startInRenderTree = false) {
-	walk(root, EMPTY_BOUND_SET, startInRenderTree);
+function collectUseArgumentRoots(
+	root,
+	ctx,
+	into,
+	startInRenderTree = false,
+	seedRenderReads = false,
+) {
+	walk(root, EMPTY_BOUND_SET, startInRenderTree, false);
 
 	// `bound` carries every name introduced by a scope the candidate collector
 	// cannot reach: nested-function params + internal declarations, loop
@@ -10645,10 +10766,10 @@ function collectUseArgumentRoots(root, ctx, into, startInRenderTree = false) {
 	// into memoization (which would wrongly stop it recreating per render).
 	// Over-binding is the safe direction: a dropped seed just leaves that
 	// chain unmemoized — today's behavior.
-	function walk(n, bound, inRenderTree) {
+	function walk(n, bound, inRenderTree, deferred) {
 		if (n == null || typeof n !== 'object') return;
 		if (Array.isArray(n)) {
-			for (const child of n) walk(child, bound, inRenderTree);
+			for (const child of n) walk(child, bound, inRenderTree, deferred);
 			return;
 		}
 		if (
@@ -10665,7 +10786,10 @@ function collectUseArgumentRoots(root, ctx, into, startInRenderTree = false) {
 			const inner = new Set(bound);
 			for (const param of n.params || []) collectPatternNames(param, inner);
 			collectScopeDeclaredNames(n.body, inner);
-			walk(n.body, inner, inRenderTree);
+			// A function VALUE runs at invoke time, not while the template renders,
+			// so names it reads are not render reads. use()-argument seeding still
+			// descends (a use() inside a render prop is a real suspension point).
+			walk(n.body, inner, inRenderTree, true);
 			return;
 		}
 		if (LOOP_TYPES.has(n.type)) {
@@ -10674,7 +10798,7 @@ function collectUseArgumentRoots(root, ctx, into, startInRenderTree = false) {
 			for (const key in n) {
 				if (key === 'loc' || key === 'start' || key === 'end' || key.startsWith('_octane'))
 					continue;
-				walk(n[key], inner, inRenderTree);
+				walk(n[key], inner, inRenderTree, deferred);
 			}
 			return;
 		}
@@ -10682,7 +10806,7 @@ function collectUseArgumentRoots(root, ctx, into, startInRenderTree = false) {
 			const inner = new Set(bound);
 			if (n.param) collectPatternNames(n.param, inner);
 			collectScopeDeclaredNames(n.body, inner);
-			walk(n.body, inner, inRenderTree);
+			walk(n.body, inner, inRenderTree, deferred);
 			return;
 		}
 		if (n.type === 'JSXForExpression') {
@@ -10696,16 +10820,32 @@ function collectUseArgumentRoots(root, ctx, into, startInRenderTree = false) {
 				collectPatternNames(n.left, inner);
 			}
 			if (n.index) collectPatternNames(n.index, inner);
-			walk(n.right, bound, true);
-			walk(n.key, inner, true);
-			walk(n.body, inner, true);
-			walk(n.empty, bound, true);
+			walk(n.right, bound, true, deferred);
+			walk(n.key, inner, true, deferred);
+			walk(n.body, inner, true, deferred);
+			walk(n.empty, bound, true, deferred);
+			return;
+		}
+		if (
+			seedRenderReads &&
+			inRenderTree &&
+			!deferred &&
+			n.type === 'Identifier' &&
+			!bound.has(n.name)
+		) {
+			into.add(n.name);
+		}
+		if ((n.type === 'MemberExpression' || n.type === 'OptionalMemberExpression') && !n.computed) {
+			// `row.length` reads `row`, not a binding called `length`. Skipping the
+			// property also cannot hide a use() call: a non-computed property is an
+			// Identifier by construction.
+			walk(n.object, bound, inRenderTree, deferred);
 			return;
 		}
 		if (inRenderTree && n.type === 'BlockStatement') {
 			const inner = new Set(bound);
 			collectScopeDeclaredNames(n, inner);
-			for (const child of n.body || []) walk(child, inner, true);
+			for (const child of n.body || []) walk(child, inner, true, deferred);
 			return;
 		}
 		// JSX reached at a setup VALUE position (`const el = <div>{use(x)}</div>`)
@@ -10716,7 +10856,7 @@ function collectUseArgumentRoots(root, ctx, into, startInRenderTree = false) {
 				(n.type.startsWith('JSX') || n.type === 'Element' || n.type === 'Tsrx'));
 		for (const key in n) {
 			if (key === 'loc' || key === 'start' || key === 'end' || key.startsWith('_octane')) continue;
-			walk(n[key], bound, nextInRenderTree);
+			walk(n[key], bound, nextInRenderTree, deferred);
 		}
 	}
 }
@@ -16057,9 +16197,11 @@ function propertyIsEnumerableCall(objNode, name) {
 	);
 }
 
-// `__s.cleanups.push(<fn>)`.
+// `(__s.cleanups ??= []).push(<fn>)` — the scope's cleanup array is lazily allocated (most
+// scopes never register one), so the registration site owns creating it.
 function cleanupsPush(fnNode) {
-	return b.stmt(b.call(b.member(b.member(b.id('__s'), 'cleanups'), 'push'), fnNode));
+	const lazyArray = b.assignment('??=', b.member(b.id('__s'), 'cleanups'), b.array([]));
+	return b.stmt(b.call(b.member(lazyArray, 'push'), fnNode));
 }
 
 // Mount for a DEFERRED property-write binding: store the element ref + seed the

package/dist/devtools-hook.d.ts

@@ -8,7 +8,7 @@ export interface DevtoolsScopeLike {
     children: Array<{
         key: symbol | string | number;
         scope: DevtoolsScopeLike;
-    }>;
+    }> | null;
     $$ctxValues?: Map<any, any> | null;
 }
 export interface DevtoolsTreeNode {

package/dist/devtools-hook.js

@@ -63,7 +63,7 @@ function buildNode(scope, key) {
     id,
     name: nameOf(scope, key),
     kind: scope.kind ?? "component",
-    children: scope.children.map((c) => buildNode(c.scope, c.key))
+    children: scope.children === null ? [] : scope.children.map((c) => buildNode(c.scope, c.key))
   };
 }
 const hook = {

package/dist/runtime.d.ts

@@ -52,7 +52,12 @@ export interface Scope {
      * `undefined` when null, identical to a Map.get miss.
      */
     hooks: Map<HookSlot, any> | null;
-    cleanups: Cleanup[];
+    /**
+     * Teardown callbacks (ref detaches, listener removal, slot cleanup). Lazily allocated by
+     * `pushCleanup` — most scopes never register one, so the array is only paid for on demand,
+     * matching `hooks` / `effectSlots` / `_slots`.
+     */
+    cleanups: Cleanup[] | null;
     /**
      * This scope's effect slots in hook DECLARATION order (first-enqueue order —
      * the order the hooks ran in the scope's first render). unmountScope walks it
@@ -69,8 +74,10 @@ export interface Scope {
      * (NOT a Map): iteration is a plain indexed for-loop, and lookups are linear
      * scans — faster than `Map.get` for the typical N ≤ 8 case (most components
      * have a handful of static sub-component calls at most).
+     *
+     * Lazily allocated when the first child scope registers: a leaf component has none.
      */
-    children: ChildScope[];
+    children: ChildScope[] | null;
     mounted: boolean;
     /**
      * Slot objects owned by this scope (ifBlockSlot, forBlockSlot, etc.).

package/dist/runtime.js

@@ -664,7 +664,7 @@ function scheduleRender(block) {
     );
   }
   const renderPhaseSelf = CURRENT_BLOCK === block;
-  const renderPhaseOther = CURRENT_BLOCK !== null && !renderPhaseSelf && TRANSITION_LISTENER_PUBLISH_DEPTH === 0;
+  const renderPhaseOther = CURRENT_BLOCK !== null && !renderPhaseSelf && TRANSITION_LISTENER_PUBLISH_DEPTH === 0 && EFFECT_EVENT_LIFECYCLE_DEPTH === 0;
   if (renderPhaseOther) {
     block.crossRenderUpdate = true;
     warnCrossComponentRenderUpdate(block, CURRENT_BLOCK);
@@ -1523,9 +1523,9 @@ class BlockImpl {
     this.currentRenderDeferred = false;
     this.inactive = false;
     this.hooks = null;
-    this.cleanups = [];
+    this.cleanups = null;
     this.effectSlots = null;
-    this.children = [];
+    this.children = null;
     this._slots = null;
     this.refFields = null;
     this.$$ctxValues = null;
@@ -1574,9 +1574,9 @@ class ScopeImpl {
     this.block = block;
     this.parent = parent;
     this.hooks = null;
-    this.cleanups = [];
+    this.cleanups = null;
     this.effectSlots = null;
-    this.children = [];
+    this.children = null;
     this._slots = null;
     this.refFields = null;
     this.slots = [];
@@ -1868,7 +1868,7 @@ function componentSlotLite(parentScope, slotKey, host, comp, props, anchor) {
       });
     }
     parentScope.slots[slotKey] = scope;
-    parentScope.children.push({ key: slotKey, scope });
+    (parentScope.children ??= []).push({ key: slotKey, scope });
   } else {
   }
   const prevScope = CURRENT_SCOPE;
@@ -1984,15 +1984,17 @@ function unmountScope(scope, detachDom = true) {
 }
 function unmountScopeChildrenAndSlots(scope, detachDom) {
   const c = scope.cleanups;
-  for (let i = c.length - 1; i >= 0; i--) {
-    try {
-      runEffectLifecycleCallback(c[i]);
-    } catch (err) {
-      reportTeardownError(err);
+  if (c !== null)
+    for (let i = c.length - 1; i >= 0; i--) {
+      try {
+        runEffectLifecycleCallback(c[i]);
+      } catch (err) {
+        reportTeardownError(err);
+      }
     }
-  }
   const children = scope.children;
-  for (let i = 0, n = children.length; i < n; i++) unmountScope(children[i].scope, detachDom);
+  if (children !== null)
+    for (let i = 0, n = children.length; i < n; i++) unmountScope(children[i].scope, detachDom);
   const slots = scope._slots;
   if (slots !== null) {
     for (let i = 0, n = slots.length; i < n; i++) {
@@ -2428,7 +2430,7 @@ function useEffectEvent(fn, slot) {
     s = { impl: fn, active: true };
     ensureHooks(scope).set(slot, s);
     const cell2 = s;
-    scope.cleanups.push(() => {
+    (scope.cleanups ??= []).push(() => {
       cell2.active = false;
     });
   } else {
@@ -2459,6 +2461,15 @@ function createContext(defaultValue) {
     }
     scope.$$ctxValues.set(ctx, props.value);
     if (props.children != null) {
+      const dialect = typeof props.children === "function" ? 1 : 2;
+      const previous = scope.hooks?.get(CHILDREN_DIALECT_SLOT);
+      if (previous !== dialect) {
+        if (previous !== void 0) {
+          resetScopeChildren(scope);
+          if (scope.block.disposed) return;
+        }
+        ensureHooks(scope).set(CHILDREN_DIALECT_SLOT, dialect);
+      }
       childrenAsBody(props.children)(void 0, scope, void 0);
     }
   };
@@ -2496,6 +2507,28 @@ function childrenAsBody(children) {
     childSlot(s, 0, s.block.parentNode, children, s.block.endMarker);
   };
 }
+const CHILDREN_DIALECT_SLOT = /* @__PURE__ */ Symbol("octane.childrenDialect");
+function resetScopeChildren(scope) {
+  const block = scope.block;
+  if (TEARDOWN_DEPTH === 0) {
+    TEARDOWN_HANDLER = findTryHandler(block.parentBlock) ?? rendererRegionTryHandler(block);
+  }
+  TEARDOWN_DEPTH++;
+  try {
+    unmountScopeChildrenAndSlots(scope, true);
+    const start = block.startMarker;
+    removeRange(start !== null ? start.nextSibling : block.parentNode.firstChild, block.endMarker);
+    scope.children = null;
+    scope.cleanups = null;
+    scope._slots = null;
+    scope.effectSlots = null;
+    scope.hooks = null;
+    scope.slots = [];
+    scope.refFields = null;
+  } finally {
+    if (--TEARDOWN_DEPTH === 0) dispatchTeardownErrors();
+  }
+}
 const HYDRATE_ID_SLOT = /* @__PURE__ */ Symbol("octane.hydrate.id");
 const HYDRATE_SETUP_SLOT = /* @__PURE__ */ Symbol("octane.hydrate.setup");
 const HYDRATE_NOTIFY_SLOT = /* @__PURE__ */ Symbol("octane.hydrate.notify");
@@ -3372,7 +3405,7 @@ function bindRendererRegionOwner(props) {
   RENDERER_REGION_DOM_OWNERS.set(root, bridge);
   root.$$ctxCache?.clear();
   if (previous === void 0) {
-    root.cleanups.push(() => {
+    (root.cleanups ??= []).push(() => {
       const current = RENDERER_REGION_DOM_BINDINGS.get(root);
       if (current === void 0) return;
       current.release();
@@ -5270,7 +5303,7 @@ function mountFragmentRef(scope, startMarker, endMarker, ref) {
   const fi = new FragmentInstance(scope.block, startMarker, endMarker);
   fi._currentRef = ref;
   queueRefAttach(scope, () => attachRef(fi._currentRef, fi));
-  scope.cleanups.push(() => {
+  (scope.cleanups ??= []).push(() => {
     queueRefDetach(fi._currentRef, fi);
     fi._destroy();
   });
@@ -5889,7 +5922,7 @@ function headBlock(scope, slot, key, tag, attrs, text) {
     }
     state = { el: el2 };
     scope.slots[slot] = state;
-    scope.cleanups.push(() => {
+    (scope.cleanups ??= []).push(() => {
       state.el.remove();
       scope.slots[slot] = void 0;
     });
@@ -8063,9 +8096,9 @@ function hostComponent(scope, slot, tag, props, childrenBody, anchor) {
     scope.slots[slot] = state;
     const childScope = new ScopeImpl(scope, block);
     state.childScope = childScope;
-    scope.children.push({ key: slot, scope: childScope });
+    (scope.children ??= []).push({ key: slot, scope: childScope });
     block.parentNode.insertBefore(el2, anchor ?? block.endMarker);
-    scope.cleanups.push(() => queueRefDetach(state.ref, state.el));
+    (scope.cleanups ??= []).push(() => queueRefDetach(state.ref, state.el));
   }
   const el = state.el;
   applyHostProps(el, props, scope, state);
@@ -8133,6 +8166,19 @@ function applyHostProps(el, props, scope, state) {
   if (process.env.NODE_ENV !== "production") queueDevFormDiagnostic(el, scope);
 }
 const DEOPT_DESC = /* @__PURE__ */ Symbol("octane.deoptDesc");
+function hasDeoptOwnedChild(el) {
+  let n = getFirstChild(el);
+  while (n !== null) {
+    const rangeEnd = n.$$portalEnd;
+    if (rangeEnd != null) {
+      n = nodeAfterPortalRange(n, rangeEnd);
+      continue;
+    }
+    if (n.$$deoptKey !== void 0 || getDeoptDesc(n) !== void 0) return true;
+    n = getNextSibling(n);
+  }
+  return false;
+}
 function getDeoptDesc(n) {
   return n[DEOPT_DESC];
 }
@@ -8297,8 +8343,14 @@ function reconcileDeoptChildren(el, children, ownerBlock) {
     }
     return;
   }
+  if (next.length === 0 && activeHydration() === null && !hasDeoptOwnedChild(el)) {
+    return;
+  }
   const owned = [];
   let hasForeign = false;
+  let hydrationOwnsUnstamped;
+  let byKey = null;
+  const unstamped = [];
   let scan = getFirstChild(el);
   while (scan !== null) {
     const rangeEnd = scan.$$portalEnd;
@@ -8307,22 +8359,25 @@ function reconcileDeoptChildren(el, children, ownerBlock) {
       scan = nodeAfterPortalRange(scan, rangeEnd);
       continue;
     }
+    const stampedKey = scan.$$deoptKey;
+    const descriptor = stampedKey === void 0 ? getDeoptDesc(scan) : void 0;
+    if (stampedKey === void 0 && descriptor === void 0 && !(hydrationOwnsUnstamped ??= activeHydration() !== null)) {
+      hasForeign = true;
+      scan = getNextSibling(scan);
+      continue;
+    }
     owned.push(scan);
-    scan = getNextSibling(scan);
-  }
-  let byKey = null;
-  const unstamped = [];
-  for (let i = 0; i < owned.length; i++) {
-    const n = owned[i];
-    const k = n.$$deoptKey ?? getDeoptDesc(n)?.key;
-    if (k != null) {
+    const key = stampedKey ?? descriptor?.key;
+    if (key != null) {
       if (byKey === null) byKey = /* @__PURE__ */ new Map();
-      if (!byKey.has(k)) {
-        byKey.set(k, n);
+      if (!byKey.has(key)) {
+        byKey.set(key, scan);
+        scan = getNextSibling(scan);
         continue;
       }
     }
-    unstamped.push(n);
+    unstamped.push(scan);
+    scan = getNextSibling(scan);
   }
   let up = 0;
   const result = [];
@@ -8351,7 +8406,7 @@ function reconcileDeoptChildren(el, children, ownerBlock) {
   }
   for (let i = 0; i < result.length; i++) {
     const want = result[i];
-    const at = hasForeign ? liveOwnedChildAt(el, i) : existing[i] ?? null;
+    const at = hasForeign ? liveOwnedChildAt(el, i, hydrationOwnsUnstamped === true) : existing[i] ?? null;
     if (at !== want) el.insertBefore(want, at);
   }
 }
@@ -8360,7 +8415,7 @@ function nodeAfterPortalRange(start, end) {
   while (m !== null && m !== end) m = getNextSibling(m);
   return getNextSibling(m ?? start);
 }
-function liveOwnedChildAt(el, index) {
+function liveOwnedChildAt(el, index, adoptHydrationChildren = false) {
   let i = 0;
   let scan = getFirstChild(el);
   while (scan !== null) {
@@ -8369,6 +8424,10 @@ function liveOwnedChildAt(el, index) {
       scan = nodeAfterPortalRange(scan, rangeEnd);
       continue;
     }
+    if (!adoptHydrationChildren && scan.$$deoptKey === void 0 && getDeoptDesc(scan) === void 0) {
+      scan = getNextSibling(scan);
+      continue;
+    }
     if (i === index) return scan;
     i++;
     scan = getNextSibling(scan);
@@ -10417,7 +10476,7 @@ function useTransition(slot) {
       }
     };
     TRANSITION_LISTENERS.add(listener);
-    scope.cleanups.push(() => TRANSITION_LISTENERS.delete(listener));
+    (scope.cleanups ??= []).push(() => TRANSITION_LISTENERS.delete(listener));
   }
   return [s.isPending, s.start];
 }
@@ -10519,7 +10578,7 @@ function useFormStatus(slot) {
     s = { form: null, listener: null };
     const slotRef = s;
     ensureHooks(scope).set(slot, slotRef);
-    scope.cleanups.push(() => {
+    (scope.cleanups ??= []).push(() => {
       if (slotRef.form && slotRef.listener)
         FORM_STATUS_LISTENERS.get(slotRef.form)?.delete(slotRef.listener);
     });
@@ -10594,7 +10653,7 @@ function useOptimistic(passthrough, updateFnOrSlot, slot) {
       if (TRANSITION_PENDING_COUNT === 0 && slotRef.armed) clear();
     };
     TRANSITION_LISTENERS.add(listener);
-    scope.cleanups.push(() => TRANSITION_LISTENERS.delete(listener));
+    (scope.cleanups ??= []).push(() => TRANSITION_LISTENERS.delete(listener));
   }
   s.updateFn = updateFn;
   let optimistic = passthrough;
@@ -11214,7 +11273,7 @@ function activityBlock(parentScope, slotKey, domParent, mode, body, anchor, env)
 }
 function forEachSubtreeChild(scope, visit, includeHiddenTry = true) {
   const children = scope.children;
-  for (let i = 0, n = children.length; i < n; i++) visit(children[i].scope);
+  if (children !== null) for (let i = 0, n = children.length; i < n; i++) visit(children[i].scope);
   const slots = scope._slots;
   if (slots !== null) {
     for (let i = 0, n = slots.length; i < n; i++) {
@@ -11938,7 +11997,7 @@ function batchClearItems(state, oldItems) {
     range.deleteContents();
   }
   for (let b = state.head; b !== null; b = b.nextSibling) {
-    if (b.cleanups.length > 0 || b.children.length > 0 || b._slots !== null) {
+    if (b.cleanups !== null || b.children !== null || b._slots !== null) {
       unmountBlock(b, false);
     } else {
       if (b.deoptNode !== null) detachDeoptTreeRefs(b.deoptNode, null);
@@ -12286,7 +12345,7 @@ function coalesceHydratedRanges(rootBlock, liteRanges) {
       if (group !== void 0) return group;
     }
     const registered = scope._slots;
-    if (registered !== null && registered.length === 1 && scope.children.length === 0 && registered[0].__kind === "childSlot" && registered[0].compactable && mayBorrowCandidate(registered[0])) {
+    if (registered !== null && registered.length === 1 && scope.children === null && registered[0].__kind === "childSlot" && registered[0].compactable && mayBorrowCandidate(registered[0])) {
       return ownerGroups.get(registered[0]) ?? null;
     }
     return null;
@@ -12363,7 +12422,8 @@ function coalesceHydratedRanges(rootBlock, liteRanges) {
   }
   function visitScopeContents(scope) {
     const children = scope.children;
-    for (let i = 0; i < children.length; i++) visitNestedScope(children[i].scope);
+    if (children !== null)
+      for (let i = 0; i < children.length; i++) visitNestedScope(children[i].scope);
     const registered = scope._slots;
     if (registered === null) return;
     for (let i = 0; i < registered.length; i++) visitSlot(registered[i]);

package/dist/runtime.server.d.ts

@@ -137,6 +137,13 @@ export declare function ssrActivity(mode: string, render: () => string): string;
  * hydration recover server/client list-shape mismatches without extra nodes.
  */
 export declare function ssrForBlock(content: string, hasItems: boolean): string;
+/**
+ * @internal Exported for direct testing: a conflating or wrong-width encoding is
+ * invisible through `prerender`, because occurrence tracking assigns list items
+ * distinct scopes independently of the key bytes. Not re-exported from
+ * `octane/server`.
+ */
+export declare function encodeAsyncIdentityString(value: string): string;
 /** Compiler-emitted identity membrane for one @if/@switch/@for instance. */
 export declare function ssrControl<T>(siteKey: string, fn: () => T): T;
 /** Compiler-emitted identity membrane for one arm/item inside ssrControl. */
@@ -466,7 +473,12 @@ export declare function namespaceHeadElement(headKey: string, tag: string, attrs
  * - `html` — the rendered markup. Hoisted document metadata (`<title>`/`<meta>`/
  *   `<link>`, collected via `ssrHeadEl`) is folded IN: spliced before `</head>`
  *   when the render produced a document, otherwise prepended. (React folds head
- *   resources into the document too, so there is no separate `head` channel.)
+ *   resources into the document too, which is why folding is the default.)
+ * - `head`, the hoisted metadata on its own, present ONLY under
+ *   `headChannel: 'separate'`; `html` then excludes it. For hosts that render
+ *   into a `<head>`-bearing template they own rather than rendering the
+ *   document, where the fold has no `</head>` to target and would otherwise
+ *   prepend metadata into the body. See `RenderOptions.headChannel`.
  * - `css` — the scoped stylesheets of the components that rendered, as
  *   ready-to-place `<style data-octane="hash">…</style>` tags (one per hash,
  *   deduped). Kept as its own field because octane has scoped CSS that React core
@@ -478,6 +490,7 @@ export declare function namespaceHeadElement(headKey: string, tag: string, attrs
 export interface RenderResult {
     html: string;
     css: string;
+    head?: string;
 }
 /** Options accepted by the buffered render entry points (React-shaped subset). */
 export interface RenderOptions {
@@ -502,6 +515,22 @@ export interface RenderOptions {
      * renders only (`prerender`).
      */
     timeoutMs?: number;
+    /**
+     * Where hoisted `<title>`/`<meta>`/`<link>` go.
+     *
+     * `'fold'` (default) keeps React's resource-hoisting shape: the metadata is
+     * spliced into `html` before `</head>`, or prepended when the render is not a
+     * document. `'separate'` withholds it from `html`/the streamed shell and hands
+     * it over on its own, `RenderResult.head` for the buffered renderers,
+     * `StreamOptions.onHeadReady` for the streaming ones.
+     *
+     * A host that renders into a `<head>`-bearing template it owns (rather than
+     * rendering the document itself) needs `'separate'`: the fold has no
+     * `</head>` to find in a body-only render, so it would prepend the metadata
+     * into the body, where a `<title>` loses to the template's and a canonical or
+     * description is ignored outright.
+     */
+    headChannel?: 'fold' | 'separate';
 }
 export declare function setSsrSuspenseTimeout(ms: number): void;
 export declare function getSsrSuspenseTimeout(): number;
@@ -668,6 +697,19 @@ export interface StreamOptions extends RenderOptions {
     onShellReady?: () => void;
     onShellError?: (err: unknown) => void;
     onAllReady?: () => void;
+    /**
+     * Receives the shell's hoisted `<title>`/`<meta>`/`<link>` under
+     * `headChannel: 'separate'`, called once BEFORE the shell is written and
+     * therefore before `onShellReady` and before `renderToReadableStream`'s
+     * promise resolves, so a host still has time to place the metadata in the
+     * template prefix it writes ahead of the render stream. Never called under
+     * the default `'fold'`, where the metadata rides the shell.
+     *
+     * Only the shell's metadata: head elements hoisted from inside a Suspense
+     * boundary that streams later are re-created client-side on hydration (see
+     * docs/ssr.md).
+     */
+    onHeadReady?: (head: string) => void;
     /** Merge externally-produced HTML into the stream (see StreamInjectionSource). */
     injection?: StreamInjectionSource;
 }

package/dist/runtime.server.js

@@ -756,10 +756,15 @@ function ssrActivity(mode, render) {
 function ssrForBlock(content, hasItems) {
   return MARKERS ? (hasItems ? FOR_BLOCK_OPEN_ITEMS : FOR_BLOCK_OPEN_EMPTY) + content + BLOCK_CLOSE : content;
 }
+const ASCII_ASYNC_IDENTITY_UNITS = [];
+for (let code = 0; code < 128; code++) {
+  ASCII_ASYNC_IDENTITY_UNITS.push(code.toString(16).padStart(4, "0"));
+}
 function encodeAsyncIdentityString(value) {
   let encoded = "";
   for (let i = 0; i < value.length; i++) {
-    encoded += value.charCodeAt(i).toString(16).padStart(4, "0");
+    const code = value.charCodeAt(i);
+    encoded += code < 128 ? ASCII_ASYNC_IDENTITY_UNITS[code] : code.toString(16).padStart(4, "0");
   }
   return encoded;
 }
@@ -3035,16 +3040,27 @@ async function runBuffered(component, props, options, nonceAttr) {
     if (resolved.pu.touched !== void 0) resolved.pu.touched = /* @__PURE__ */ new Set();
   }
 }
-function passToResult(pass, nonceAttr) {
+function passToResult(pass, nonceAttr, separateHead = false) {
   let body = pass.body;
   if (pass.serial.length > 0) body += serializeSuspenseSeeds(pass.serial, nonceAttr);
+  if (separateHead) {
+    return {
+      html: pass.vtCandidates ? vtSsrStrip(body) : body,
+      css: pass.css,
+      head: pass.vtCandidates ? vtSsrStrip(pass.head) : pass.head
+    };
+  }
   const html = spliceHead(body, pass.head);
   return { html: pass.vtCandidates ? vtSsrStrip(html) : html, css: pass.css };
 }
 async function prerender(entryComponent, props, options) {
   const component = entryComponent;
   const nonceAttr = nonceAttrOf(options);
-  return passToResult(await runBuffered(component, props, options, nonceAttr), nonceAttr);
+  return passToResult(
+    await runBuffered(component, props, options, nonceAttr),
+    nonceAttr,
+    options?.headChannel === "separate"
+  );
 }
 let HOSTED_FOREIGN_CONTEXT_READER = null;
 function readHostedForeignContext(usable, api) {
@@ -3122,7 +3138,7 @@ function renderToString(entryComponent, props, options) {
     options?.onError?.(err);
     throw err;
   }
-  return passToResult(pass, nonceAttr);
+  return passToResult(pass, nonceAttr, options?.headChannel === "separate");
 }
 function renderToStaticMarkup(entryComponent, props, options) {
   const component = entryComponent;
@@ -3146,6 +3162,13 @@ function renderToStaticMarkup(entryComponent, props, options) {
     options?.onError?.(err);
     throw err;
   }
+  if (options?.headChannel === "separate") {
+    return {
+      html: pass.vtCandidates ? vtSsrStrip(pass.body) : pass.body,
+      css: pass.css,
+      head: pass.vtCandidates ? vtSsrStrip(pass.head) : pass.head
+    };
+  }
   const html = spliceHead(pass.body, pass.head);
   return { html: pass.vtCandidates ? vtSsrStrip(html) : html, css: pass.css };
 }
@@ -3685,6 +3708,9 @@ async function runStream(component, props, options, sink) {
     emittedCss.add(hash);
     leadingStyles += '<style data-octane="' + hash + '"' + nonceAttr + ">" + escapeEntireInlineStyleContent(sheet) + "</style>";
   }
+  const separateHead = options?.headChannel === "separate";
+  if (separateHead) options?.onHeadReady?.(pass.vtCandidates ? vtSsrStrip(pass.head) : pass.head);
+  const shellHead = separateHead ? "" : pass.head;
   const documentRoot = isDocumentRoot(pass.body);
   let shell = documentRoot ? "<!DOCTYPE html>" : "";
   let heldDocumentTail = "";
@@ -3694,12 +3720,12 @@ async function runStream(component, props, options, sink) {
       heldDocumentTail = pass.body.slice(tailStart);
       const bodyHtml = pass.body.slice(0, tailStart);
       const headInsert = documentHeadInsertionPoint(bodyHtml);
-      shell += headInsert !== -1 ? bodyHtml.slice(0, headInsert) + leadingStyles + pass.head + bodyHtml.slice(headInsert) : leadingStyles + pass.head + bodyHtml;
+      shell += headInsert !== -1 ? bodyHtml.slice(0, headInsert) + leadingStyles + shellHead + bodyHtml.slice(headInsert) : leadingStyles + shellHead + bodyHtml;
     } else {
-      shell += leadingStyles + pass.head + pass.body;
+      shell += leadingStyles + shellHead + pass.body;
     }
   } else {
-    shell += leadingStyles + pass.head + pass.body;
+    shell += leadingStyles + shellHead + pass.body;
   }
   if (pass.serial.length > 0) shell += serializeSuspenseSeeds(pass.serial, nonceAttr);
   const anyPending = stream.boundaries.size > 0;
@@ -4272,6 +4298,7 @@ export {
   createElement,
   createHostedServerSession,
   createPortal,
+  encodeAsyncIdentityString,
   escapeAttr,
   escapeHtml,
   flushSync,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octane",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,