@streetui/renderer 1.6.0 → 1.7.0

package/dist/index.d.ts

@@ -110,8 +110,18 @@ interface RenderContext {
      * DevTools/diagnostics stay off the production runtime path.
      */
     readonly hydrationDiagnostics?: HydrationDiagnosticSink;
+    /**
+     * Optional SSR-only static-subtree plan (v1.7). Maps a maximal
+     * static-subtree root GraphNode.id → its precomputed, verbatim HTML string.
+     * Present only on the server render path when a plan has been built; on the
+     * browser mount path it is always `undefined`, so the client hot path is
+     * unaffected (a single `=== undefined` check short-circuits). When a mounted
+     * node's id is in this map, the renderer emits the precomputed HTML via
+     * `dom.createRawHTML` instead of recursively constructing the subtree.
+     */
+    readonly staticHTML?: ReadonlyMap<string, string>;
 }
-declare function createRenderContext(dom: DOMAdapter, graph: ApplicationGraph, container: Element, hydrationDiagnostics?: HydrationDiagnosticSink): RenderContext;
+declare function createRenderContext(dom: DOMAdapter, graph: ApplicationGraph, container: Element, hydrationDiagnostics?: HydrationDiagnosticSink, staticHTML?: ReadonlyMap<string, string>): RenderContext;
 
 /**
  * Attribute and property application helpers.
@@ -168,6 +178,20 @@ declare function wireSignalBindings(ctx: RenderContext, graphNode: GraphNode, in
  * eager build factory (it only ever renders 0..1 branch, so eager is fine).
  */
 declare function wireReactiveList(ctx: RenderContext, graphNode: GraphNode, instance: NodeInstance, el: Element): void;
+/**
+ * Attach overlay focus/keyboard behavior to a mounted portal. Server-safe: on
+ * the server `dom.body()` is null so this returns immediately (SSR emits inert
+ * markup, no focus concept). A plain portal has no `__overlay__` descriptor, so
+ * this also returns immediately — the behavior is purely additive.
+ *
+ * The panel is mounted/unmounted by the portal's inner `when(open, …)`, whose
+ * signal subscription is registered *before* this one (the conditional child is
+ * mounted earlier in the portal branch). Signal subscribers fire synchronously
+ * in subscription order, so on open→true the panel DOM exists before we move
+ * focus into it, and on open→false the panel is torn down before we restore
+ * focus. All listeners are tracked on the instance and torn down on unmount.
+ */
+declare function wireOverlayBehavior(ctx: RenderContext, graphNode: GraphNode, instance: NodeInstance, target: Element): void;
 
 /**
  * Patch — targeted DOM updates driven by signal changes.
@@ -393,6 +417,18 @@ interface RenderToStringOptions {
      * `ServerDOMAdapter` per call so concurrent renders never share state.
      */
     readonly domAdapter?: ServerDOMAdapter;
+    /**
+     * @internal — testing/benchmark knob for the v1.7 static SSR plan.
+     *
+     * `undefined` (default): use the per-app cached plan (build once, reuse).
+     * `null`: disable the plan entirely — the exact v1.6 runtime mount path, used
+     *   by the byte-identity gate and A/B benchmark as the "legacy" baseline.
+     * a map: use this explicit plan.
+     *
+     * Not part of the supported public API; output is byte-identical regardless
+     * of this value (§8).
+     */
+    readonly staticPlan?: ReadonlyMap<string, string> | null;
 }
 /**
  * Render a compiled StreetUI application to an HTML string.
@@ -409,4 +445,4 @@ declare function renderToString(compiled: CompiledApplication, options?: RenderT
 
 declare function resolveTag(type: SemanticNodeType): string;
 
-export { type HydrationDiagnostic, type HydrationDiagnosticSink, type HydrationMismatchType, type MountFn, NodeInstance, type PlanEntry, type ReconcileResult, type RenderContext, type RenderToStringOptions, STATE_MARKER_ATTR, StreetRenderHandle, StreetRendererImpl, type StreetRendererOptions, applyNodeProps, applyProp, buttonUpdate, consoleHydrationDiagnosticSink, createHydrationDiagnosticCollector, createRenderContext, createRenderer, formatHydrationDiagnostic, headingUpdate, hydrateGraph, inputUpdate, mountGraph, mountNode, patchNode, patchProp, readState, reconcileChildren, reconcileChildrenByPlan, renderToString, resolveTag, serializeState, textUpdate, wireEvents, wireReactiveList, wireSignalBindings };
+export { type HydrationDiagnostic, type HydrationDiagnosticSink, type HydrationMismatchType, type MountFn, NodeInstance, type PlanEntry, type ReconcileResult, type RenderContext, type RenderToStringOptions, STATE_MARKER_ATTR, StreetRenderHandle, StreetRendererImpl, type StreetRendererOptions, applyNodeProps, applyProp, buttonUpdate, consoleHydrationDiagnosticSink, createHydrationDiagnosticCollector, createRenderContext, createRenderer, formatHydrationDiagnostic, headingUpdate, hydrateGraph, inputUpdate, mountGraph, mountNode, patchNode, patchProp, readState, reconcileChildren, reconcileChildrenByPlan, renderToString, resolveTag, serializeState, textUpdate, wireEvents, wireOverlayBehavior, wireReactiveList, wireSignalBindings };

package/dist/index.js

@@ -1,11 +1,12 @@
 // src/render-context.ts
-function createRenderContext(dom, graph, container, hydrationDiagnostics) {
+function createRenderContext(dom, graph, container, hydrationDiagnostics, staticHTML) {
   return {
     dom,
     graph,
     instances: /* @__PURE__ */ new Map(),
     container,
-    ...hydrationDiagnostics !== void 0 ? { hydrationDiagnostics } : {}
+    ...hydrationDiagnostics !== void 0 ? { hydrationDiagnostics } : {},
+    ...staticHTML !== void 0 ? { staticHTML } : {}
   };
 }
 
@@ -137,6 +138,16 @@ function wireEvents(dom, graph, node, element, instance) {
   }
 }
 
+// src/mount.ts
+import {
+  focusInitial,
+  trapFocus,
+  containFocus,
+  onEscape,
+  saveFocus,
+  restoreFocus
+} from "@streetui/dom";
+
 // src/tag-map.ts
 var TAG_MAP = {
   application: "div",
@@ -155,7 +166,12 @@ var TAG_MAP = {
   component: "div",
   slot: "div",
   fragment: "div",
-  "reactive-list": "ul"
+  "reactive-list": "ul",
+  // A portal renders as a neutral inline anchor <div> at its declaration site;
+  // its children are relocated to a document.body container on the browser
+  // (see the portal branch in mount.ts). On the server (no body) it renders
+  // inline, so the anchor tag is what SSR/hydration positionally match on.
+  portal: "div"
 };
 function resolveTag(type) {
   return TAG_MAP[type] ?? "div";
@@ -434,6 +450,17 @@ function mountGraph(ctx) {
 }
 function mountNode(ctx, graphNode, parentDom) {
   const { dom, graph } = ctx;
+  const staticHTML = ctx.staticHTML;
+  if (staticHTML !== void 0 && dom.createRawHTML !== void 0) {
+    const precomputed = staticHTML.get(graphNode.id);
+    if (precomputed !== void 0) {
+      const raw = dom.createRawHTML(precomputed);
+      dom.appendChild(parentDom, raw);
+      const instance2 = new NodeInstance(graphNode, raw);
+      ctx.instances.set(graphNode.id, instance2);
+      return instance2;
+    }
+  }
   if (graphNode.type === "application") {
     const instance2 = new NodeInstance(graphNode, parentDom);
     ctx.instances.set(graphNode.id, instance2);
@@ -556,6 +583,28 @@ function mountNode(ctx, graphNode, parentDom) {
     wireReactiveList(ctx, graphNode, instance2, el2);
     return instance2;
   }
+  if (graphNode.type === "portal") {
+    const anchor = dom.createElement(resolveTag("portal"));
+    dom.setAttribute(anchor, "data-streetui-portal", "");
+    applyNodeProps(ctx, graphNode, anchor);
+    const instance2 = new NodeInstance(graphNode, anchor);
+    ctx.instances.set(graphNode.id, instance2);
+    const body = dom.body();
+    let target = anchor;
+    if (body !== null) {
+      const portalContainer = dom.createElement("div");
+      dom.setAttribute(portalContainer, "data-streetui-portal-container", "");
+      dom.appendChild(body, portalContainer);
+      instance2.trackCleanup(() => dom.removeChild(body, portalContainer));
+      target = portalContainer;
+    }
+    for (const child of graphNode.children) {
+      instance2.addChild(mountNode(ctx, child, target));
+    }
+    dom.appendChild(parentDom, anchor);
+    wireOverlayBehavior(ctx, graphNode, instance2, target);
+    return instance2;
+  }
   const tag = resolveTag(graphNode.type);
   const el = dom.createElement(tag);
   applyNodeProps(ctx, graphNode, el);
@@ -705,6 +754,44 @@ function forgetInstance(ctx, instance) {
   ctx.instances.delete(instance.graphNode.id);
   for (const child of instance.children) forgetInstance(ctx, child);
 }
+function wireOverlayBehavior(ctx, graphNode, instance, target) {
+  const { dom, graph } = ctx;
+  if (dom.body() === null) return;
+  const descFn = graph.getHandler(`__overlay__${graphNode.id}`);
+  if (descFn === void 0) return;
+  const desc = descFn();
+  const openSig = desc.open;
+  if (openSig === void 0 || typeof openSig.subscribe !== "function") return;
+  let active = [];
+  let saved = null;
+  const teardown = () => {
+    for (const fn of active) fn();
+    active = [];
+  };
+  const onOpenChange = (isOpen) => {
+    if (isOpen) {
+      if (desc.restoreFocus) saved = saveFocus(dom);
+      if (desc.takesFocus) focusInitial(dom, target, desc.initialFocusId);
+      if (desc.modal) {
+        active.push(trapFocus(dom, target));
+        active.push(containFocus(dom, target));
+      }
+      if (desc.closeOnEscape && desc.onClose !== void 0) {
+        active.push(onEscape(dom, target, desc.onClose));
+      }
+    } else {
+      teardown();
+      if (desc.restoreFocus && saved !== null) {
+        restoreFocus(dom, saved);
+        saved = null;
+      }
+    }
+  };
+  const unsub = openSig.subscribe(onOpenChange);
+  instance.trackCleanup(unsub);
+  instance.trackCleanup(teardown);
+  if (openSig.peek() === true) onOpenChange(true);
+}
 
 // src/renderer.ts
 import { BrowserDOMAdapter } from "@streetui/dom";
@@ -810,6 +897,25 @@ function hydrateNode(ctx, graphNode, domNode, path) {
       wireReactiveList(ctx, graphNode, instance, domNode);
       return instance;
     }
+    case "portal": {
+      const instance = new NodeInstance(graphNode, domNode);
+      ctx.instances.set(graphNode.id, instance);
+      const body = dom.body();
+      let target = domNode;
+      if (body !== null) {
+        const portalContainer = dom.createElement("div");
+        dom.setAttribute(portalContainer, "data-streetui-portal-container", "");
+        for (const child of dom.childNodes(domNode)) {
+          dom.appendChild(portalContainer, child);
+        }
+        dom.appendChild(body, portalContainer);
+        instance.trackCleanup(() => dom.removeChild(body, portalContainer));
+        target = portalContainer;
+      }
+      hydrateChildren(ctx, graphNode, instance, target, path);
+      wireOverlayBehavior(ctx, graphNode, instance, target);
+      return instance;
+    }
     default: {
       const instance = new NodeInstance(graphNode, domNode);
       ctx.instances.set(graphNode.id, instance);
@@ -1025,11 +1131,64 @@ function readState(dom, root) {
 }
 
 // src/ssr.ts
+import { ServerDOMAdapter as ServerDOMAdapter2 } from "@streetui/dom";
+
+// src/static-ssr-plan.ts
+import { analyzeGraph } from "@streetui/compiler/diagnostics";
 import { ServerDOMAdapter } from "@streetui/dom";
+function collectMaximalStaticRoots(graph) {
+  const analysis = analyzeGraph(graph);
+  const roots = [];
+  const walk = (node) => {
+    if (node.type !== "application") {
+      const a = analysis.nodes.get(node.id);
+      if (a !== void 0 && a.isStaticSubtree) {
+        roots.push(node);
+        return;
+      }
+    }
+    for (const child of node.children) walk(child);
+  };
+  walk(graph.root);
+  return roots;
+}
+function serializeStaticSubtree(dom, graph, root) {
+  const container = dom.createElement("div");
+  const ctx = createRenderContext(dom, graph, container);
+  const instance = mountNode(ctx, root, container);
+  const html = dom.serializeInner(container);
+  instance.dispose();
+  ctx.instances.clear();
+  return html;
+}
+function buildStaticSSRPlan(compiled) {
+  const graph = compiled.graph;
+  const roots = collectMaximalStaticRoots(graph);
+  const plan = /* @__PURE__ */ new Map();
+  if (roots.length === 0) return plan;
+  const dom = new ServerDOMAdapter();
+  for (const root of roots) {
+    plan.set(root.id, serializeStaticSubtree(dom, graph, root));
+  }
+  return plan;
+}
+var PLAN_CACHE = /* @__PURE__ */ new WeakMap();
+function getStaticSSRPlan(compiled) {
+  let plan = PLAN_CACHE.get(compiled);
+  if (plan === void 0) {
+    plan = buildStaticSSRPlan(compiled);
+    PLAN_CACHE.set(compiled, plan);
+  }
+  return plan;
+}
+
+// src/ssr.ts
 function renderToString(compiled, options = {}) {
-  const dom = options.domAdapter ?? new ServerDOMAdapter();
+  const dom = options.domAdapter ?? new ServerDOMAdapter2();
+  const plan = options.staticPlan === null ? void 0 : options.staticPlan ?? getStaticSSRPlan(compiled);
+  const staticHTML = plan !== void 0 && plan.size > 0 ? plan : void 0;
   const container = dom.createElement("div");
-  const ctx = createRenderContext(dom, compiled.graph, container);
+  const ctx = createRenderContext(dom, compiled.graph, container, void 0, staticHTML);
   const rootInstance = mountGraph(ctx);
   const html = dom.serializeInner(container);
   rootInstance.dispose();
@@ -1064,6 +1223,7 @@ export {
   serializeState,
   textUpdate,
   wireEvents,
+  wireOverlayBehavior,
   wireReactiveList,
   wireSignalBindings
 };