streetui 1.8.0 → 2.0.0

package/dist/renderer-interface-BUhHV7ja.d.cts

@@ -0,0 +1,26 @@
+import { C as CompiledApplication } from './hydration-diagnostics-CFYDXBlm.cjs';
+
+/**
+ * The interface the runtime uses to communicate with the renderer.
+ *
+ * The runtime never knows how DOM nodes are created — it delegates to this
+ * interface. This keeps the runtime/renderer boundary clean.
+ */
+
+interface RenderHandle {
+    /** Force a synchronous flush of pending updates. */
+    flush(): void;
+    /** Unmount and dispose all resources. */
+    unmount(): void;
+}
+interface StreetRenderer {
+    mount(application: CompiledApplication, container: Element): RenderHandle;
+    /**
+     * Optional: attach behavior to server-rendered HTML already present in
+     * `container` instead of recreating it. Renderers that cannot hydrate may
+     * omit this; callers fall back to `mount`.
+     */
+    hydrate?(application: CompiledApplication, container: Element): RenderHandle;
+}
+
+export type { RenderHandle as R, StreetRenderer as S };

package/dist/renderer-interface-B_-hWnKk.d.ts

@@ -0,0 +1,26 @@
+import { C as CompiledApplication } from './hydration-diagnostics-CFYDXBlm.js';
+
+/**
+ * The interface the runtime uses to communicate with the renderer.
+ *
+ * The runtime never knows how DOM nodes are created — it delegates to this
+ * interface. This keeps the runtime/renderer boundary clean.
+ */
+
+interface RenderHandle {
+    /** Force a synchronous flush of pending updates. */
+    flush(): void;
+    /** Unmount and dispose all resources. */
+    unmount(): void;
+}
+interface StreetRenderer {
+    mount(application: CompiledApplication, container: Element): RenderHandle;
+    /**
+     * Optional: attach behavior to server-rendered HTML already present in
+     * `container` instead of recreating it. Renderers that cannot hydrate may
+     * omit this; callers fall back to `mount`.
+     */
+    hydrate?(application: CompiledApplication, container: Element): RenderHandle;
+}
+
+export type { RenderHandle as R, StreetRenderer as S };

package/dist/{server-CnLEnlYU.d.cts → server-C0PvFBzD.d.ts}

@@ -1,4 +1,31 @@
-import { C as CompiledApplication } from './compile-CJJQYi71.cjs';
+import { G as GraphNode, R as ReadonlySignal, C as CompiledApplication, i as ApplicationGraph, j as HydrationDiagnosticSink } from './hydration-diagnostics-CFYDXBlm.js';
+
+/**
+ * Application and component lifecycle primitives.
+ *
+ * Lifecycle phases:
+ *   created → mounted → active ⇄ updating → unmounting → destroyed
+ */
+type LifecyclePhase = 'created' | 'mounted' | 'active' | 'updating' | 'unmounting' | 'destroyed';
+type LifecycleHook = () => void | Promise<void>;
+declare class Lifecycle {
+    private _phase;
+    private readonly _hooks;
+    get phase(): LifecyclePhase;
+    get isMounted(): boolean;
+    get isDestroyed(): boolean;
+    on(phase: LifecyclePhase, hook: LifecycleHook): () => void;
+    transition(to: LifecyclePhase): Promise<void>;
+    onMount(hook: LifecycleHook): () => void;
+    onUnmount(hook: LifecycleHook): () => void;
+    onDestroy(hook: LifecycleHook): () => void;
+}
+/** A simple cleanup registry — collect teardown functions and run them all at once. */
+declare class CleanupRegistry {
+    private readonly _fns;
+    add(fn: () => void): void;
+    run(): void;
+}
 
 /**
  * DOMAdapter — framework-owned abstraction over DOM operations.
@@ -44,6 +71,13 @@ interface DOMAdapter {
      * inline rendering and focus management degrade to a no-op.
      */
     body(): Element | null;
+    /**
+     * The document head — the mount target for `head()` metadata (title/meta/
+     * link/etc.). Returns null on the server (no document), which is what makes
+     * the head platform degrade to server-side string emission (`renderHead`) and
+     * the browser `wireHeadBehavior` a no-op on the server render pass.
+     */
+    head(): Element | null;
     /** The currently focused element, or null on the server / when none is focused. */
     activeElement(): Element | null;
     /** True if `ancestor` contains `node` (inclusive). Always false on the server. */
@@ -106,6 +140,7 @@ declare class ServerDOMAdapter implements DOMAdapter {
     getElementById(): Element | null;
     focus(): void;
     body(): Element | null;
+    head(): Element | null;
     activeElement(): Element | null;
     contains(_ancestor: Element, _node: Node): boolean;
     matches(_element: Element, _selector: string): boolean;
@@ -123,6 +158,150 @@ declare class ServerDOMAdapter implements DOMAdapter {
 }
 declare const serverDOMAdapter: ServerDOMAdapter;
 
+/**
+ * NodeInstance — the renderer's live counterpart to a GraphNode.
+ *
+ * Tracks the actual DOM node(s), all signal subscriptions that drive
+ * targeted DOM updates, and DOM event listener teardowns.
+ */
+
+declare class NodeInstance {
+    readonly graphNode: GraphNode;
+    /** The primary DOM node for this instance (element or text node). */
+    domNode: Node;
+    readonly children: NodeInstance[];
+    readonly cleanup: CleanupRegistry;
+    constructor(graphNode: GraphNode, domNode: Node);
+    addChild(child: NodeInstance): void;
+    /** Subscribe to a signal; auto-cleanup on unmount. */
+    trackSignal<T>(sig: ReadonlySignal<T>, handler: (v: T) => void): void;
+    /** Register a raw cleanup fn (DOM event removal, etc.). */
+    trackCleanup(fn: () => void): void;
+    dispose(): void;
+}
+
+/**
+ * Document head / metadata runtime (2.0 §1–§3).
+ *
+ * Two entry points, sharing the normalized {@link HeadEntry} model the DSL's
+ * `head()` produces (mirrored here as a local structural type so the renderer
+ * takes no compile-time dependency on the DSL package — the same convention as
+ * the overlay/component descriptors):
+ *
+ *   • `wireHeadBehavior(ctx, node, instance)` — BROWSER. Reads the
+ *     `__head__<id>` descriptor, registers this node's contribution with a
+ *     per-render {@link HeadManager} (created lazily on `ctx`), subscribes to any
+ *     reactive attr/text signals, and tracks cleanup on the NodeInstance so the
+ *     contribution is withdrawn (and the manager re-applies the merged result)
+ *     when the node unmounts or the route changes. Server-safe: when
+ *     `dom.head()` is null (SSR) it is a no-op.
+ *
+ *   • `renderHead(compiled)` — SERVER. Walks the compiled graph in document
+ *     order, merges every live `head()` contribution (last-in-document-order
+ *     wins per dedup key — §3), and serializes the effective tags to an HTML
+ *     string for the caller to place inside `<head>`. Only the active graph is
+ *     walked, so only active-route metadata is emitted (§2). Each tag carries
+ *     `data-streetui-head` + `data-streetui-head-key="…"` so the browser adopts
+ *     it on hydration instead of creating a duplicate.
+ */
+
+interface HeadEntryLike {
+    readonly tag: 'title' | 'meta' | 'link' | 'base';
+    readonly dedupKey: string;
+    readonly attrs: Readonly<Record<string, unknown>>;
+    readonly text?: unknown;
+}
+/**
+ * Coordinates every live `head()` node's contribution into a single
+ * `document.head`. One instance per render (lazily created on `ctx`). Merges by
+ * dedup key with last-in-document-order winning, and applies the minimal diff to
+ * the DOM on every register/unregister/signal change. Adopts server-emitted tags
+ * on the first apply so hydration produces no duplicates.
+ */
+declare class HeadManager {
+    private readonly _dom;
+    private readonly _head;
+    private readonly _contributions;
+    private readonly _applied;
+    private _order;
+    private _adopted;
+    constructor(dom: DOMAdapter, head: Element);
+    /** Register (or replace) a node's contribution and re-apply the merged result. */
+    register(nodeId: string, entries: readonly HeadEntryLike[]): void;
+    /** Withdraw a node's contribution (unmount / route change) and re-apply. */
+    unregister(nodeId: string): void;
+    /** Recompute the merged head and patch `document.head` to match. */
+    apply(): void;
+    private _createTag;
+    private _reconcileAttrs;
+    /**
+     * Seed `_applied` from server-emitted `[data-streetui-head-key]` tags already
+     * in `document.head`. The subsequent diff reuses these elements when the
+     * client desires the same key (no duplicate), rewrites them if the value
+     * changed, or removes them if the client graph no longer wants them.
+     */
+    private _adoptServerTags;
+    /** The framework-managed attribute names currently on a server tag. */
+    private _attrNames;
+}
+/**
+ * Wire a mounted/hydrated `head` node's contribution into `document.head`.
+ * Server-safe (no-op when there is no document). Shared by the mount and hydrate
+ * paths so both establish identical ownership + cleanup.
+ */
+declare function wireHeadBehavior(ctx: RenderContext, graphNode: GraphNode, instance: NodeInstance): void;
+/**
+ * Render the active graph's merged document metadata to an HTML string suitable
+ * for placing inside `<head>`. Walks the graph in document order, merges every
+ * `head()` contribution (last-in-document-order wins per dedup key), and
+ * serializes each effective tag with the `data-streetui-head` marker so the
+ * browser adopts it on hydration. Returns `''` when the app declares no metadata
+ * — so apps that never call `head()` emit nothing extra and existing SSR output
+ * is unchanged.
+ */
+declare function renderHead(compiled: CompiledApplication): string;
+
+/**
+ * RenderContext — shared state for a single mount operation.
+ *
+ * Passed through the render pipeline so every sub-function has access
+ * to the DOM adapter, graph, and instance map without prop-drilling.
+ */
+
+interface RenderContext {
+    readonly dom: DOMAdapter;
+    readonly graph: ApplicationGraph;
+    /** Maps GraphNode.id → its live NodeInstance */
+    readonly instances: Map<string, NodeInstance>;
+    /** The root container element. */
+    readonly container: Element;
+    /**
+     * Optional dev-only sink that observes hydration mismatch repairs. When
+     * absent (the default) the hydration path does no extra work — this is how
+     * 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>;
+    /**
+     * Lazily-created coordinator for `head()` metadata nodes (2.0 §1). Created on
+     * first `wireHeadBehavior` call on the browser (never on the server, where
+     * `dom.head()` is null and `renderHead` emits the metadata instead). Mutable
+     * because it is attached on demand; a render with no `head()` nodes never
+     * allocates one.
+     */
+    head?: HeadManager;
+}
+declare function createRenderContext(dom: DOMAdapter, graph: ApplicationGraph, container: Element, hydrationDiagnostics?: HydrationDiagnosticSink, staticHTML?: ReadonlyMap<string, string>): RenderContext;
+
 /**
  * SSR state transfer (dehydration) — move server-resolved data to the client.
  *
@@ -204,4 +383,4 @@ interface RenderToStringOptions {
  */
 declare function renderToString(compiled: CompiledApplication, options?: RenderToStringOptions): string;
 
-export { type DOMAdapter as D, type RenderToStringOptions as R, STATE_MARKER_ATTR as S, ServerDOMAdapter as a, renderToString as b, serverDOMAdapter as c, readState as r, serializeState as s };
+export { CleanupRegistry as C, type DOMAdapter as D, HeadManager as H, Lifecycle as L, NodeInstance as N, type RenderContext as R, STATE_MARKER_ATTR as S, type LifecycleHook as a, type LifecyclePhase as b, type RenderToStringOptions as c, ServerDOMAdapter as d, createRenderContext as e, renderHead as f, renderToString as g, serverDOMAdapter as h, readState as r, serializeState as s, wireHeadBehavior as w };

package/dist/{server-DNlg7ou2.d.ts → server-DnAOFpMP.d.cts}

@@ -1,4 +1,31 @@
-import { C as CompiledApplication } from './compile-CJJQYi71.js';
+import { G as GraphNode, R as ReadonlySignal, C as CompiledApplication, i as ApplicationGraph, j as HydrationDiagnosticSink } from './hydration-diagnostics-CFYDXBlm.cjs';
+
+/**
+ * Application and component lifecycle primitives.
+ *
+ * Lifecycle phases:
+ *   created → mounted → active ⇄ updating → unmounting → destroyed
+ */
+type LifecyclePhase = 'created' | 'mounted' | 'active' | 'updating' | 'unmounting' | 'destroyed';
+type LifecycleHook = () => void | Promise<void>;
+declare class Lifecycle {
+    private _phase;
+    private readonly _hooks;
+    get phase(): LifecyclePhase;
+    get isMounted(): boolean;
+    get isDestroyed(): boolean;
+    on(phase: LifecyclePhase, hook: LifecycleHook): () => void;
+    transition(to: LifecyclePhase): Promise<void>;
+    onMount(hook: LifecycleHook): () => void;
+    onUnmount(hook: LifecycleHook): () => void;
+    onDestroy(hook: LifecycleHook): () => void;
+}
+/** A simple cleanup registry — collect teardown functions and run them all at once. */
+declare class CleanupRegistry {
+    private readonly _fns;
+    add(fn: () => void): void;
+    run(): void;
+}
 
 /**
  * DOMAdapter — framework-owned abstraction over DOM operations.
@@ -44,6 +71,13 @@ interface DOMAdapter {
      * inline rendering and focus management degrade to a no-op.
      */
     body(): Element | null;
+    /**
+     * The document head — the mount target for `head()` metadata (title/meta/
+     * link/etc.). Returns null on the server (no document), which is what makes
+     * the head platform degrade to server-side string emission (`renderHead`) and
+     * the browser `wireHeadBehavior` a no-op on the server render pass.
+     */
+    head(): Element | null;
     /** The currently focused element, or null on the server / when none is focused. */
     activeElement(): Element | null;
     /** True if `ancestor` contains `node` (inclusive). Always false on the server. */
@@ -106,6 +140,7 @@ declare class ServerDOMAdapter implements DOMAdapter {
     getElementById(): Element | null;
     focus(): void;
     body(): Element | null;
+    head(): Element | null;
     activeElement(): Element | null;
     contains(_ancestor: Element, _node: Node): boolean;
     matches(_element: Element, _selector: string): boolean;
@@ -123,6 +158,150 @@ declare class ServerDOMAdapter implements DOMAdapter {
 }
 declare const serverDOMAdapter: ServerDOMAdapter;
 
+/**
+ * NodeInstance — the renderer's live counterpart to a GraphNode.
+ *
+ * Tracks the actual DOM node(s), all signal subscriptions that drive
+ * targeted DOM updates, and DOM event listener teardowns.
+ */
+
+declare class NodeInstance {
+    readonly graphNode: GraphNode;
+    /** The primary DOM node for this instance (element or text node). */
+    domNode: Node;
+    readonly children: NodeInstance[];
+    readonly cleanup: CleanupRegistry;
+    constructor(graphNode: GraphNode, domNode: Node);
+    addChild(child: NodeInstance): void;
+    /** Subscribe to a signal; auto-cleanup on unmount. */
+    trackSignal<T>(sig: ReadonlySignal<T>, handler: (v: T) => void): void;
+    /** Register a raw cleanup fn (DOM event removal, etc.). */
+    trackCleanup(fn: () => void): void;
+    dispose(): void;
+}
+
+/**
+ * Document head / metadata runtime (2.0 §1–§3).
+ *
+ * Two entry points, sharing the normalized {@link HeadEntry} model the DSL's
+ * `head()` produces (mirrored here as a local structural type so the renderer
+ * takes no compile-time dependency on the DSL package — the same convention as
+ * the overlay/component descriptors):
+ *
+ *   • `wireHeadBehavior(ctx, node, instance)` — BROWSER. Reads the
+ *     `__head__<id>` descriptor, registers this node's contribution with a
+ *     per-render {@link HeadManager} (created lazily on `ctx`), subscribes to any
+ *     reactive attr/text signals, and tracks cleanup on the NodeInstance so the
+ *     contribution is withdrawn (and the manager re-applies the merged result)
+ *     when the node unmounts or the route changes. Server-safe: when
+ *     `dom.head()` is null (SSR) it is a no-op.
+ *
+ *   • `renderHead(compiled)` — SERVER. Walks the compiled graph in document
+ *     order, merges every live `head()` contribution (last-in-document-order
+ *     wins per dedup key — §3), and serializes the effective tags to an HTML
+ *     string for the caller to place inside `<head>`. Only the active graph is
+ *     walked, so only active-route metadata is emitted (§2). Each tag carries
+ *     `data-streetui-head` + `data-streetui-head-key="…"` so the browser adopts
+ *     it on hydration instead of creating a duplicate.
+ */
+
+interface HeadEntryLike {
+    readonly tag: 'title' | 'meta' | 'link' | 'base';
+    readonly dedupKey: string;
+    readonly attrs: Readonly<Record<string, unknown>>;
+    readonly text?: unknown;
+}
+/**
+ * Coordinates every live `head()` node's contribution into a single
+ * `document.head`. One instance per render (lazily created on `ctx`). Merges by
+ * dedup key with last-in-document-order winning, and applies the minimal diff to
+ * the DOM on every register/unregister/signal change. Adopts server-emitted tags
+ * on the first apply so hydration produces no duplicates.
+ */
+declare class HeadManager {
+    private readonly _dom;
+    private readonly _head;
+    private readonly _contributions;
+    private readonly _applied;
+    private _order;
+    private _adopted;
+    constructor(dom: DOMAdapter, head: Element);
+    /** Register (or replace) a node's contribution and re-apply the merged result. */
+    register(nodeId: string, entries: readonly HeadEntryLike[]): void;
+    /** Withdraw a node's contribution (unmount / route change) and re-apply. */
+    unregister(nodeId: string): void;
+    /** Recompute the merged head and patch `document.head` to match. */
+    apply(): void;
+    private _createTag;
+    private _reconcileAttrs;
+    /**
+     * Seed `_applied` from server-emitted `[data-streetui-head-key]` tags already
+     * in `document.head`. The subsequent diff reuses these elements when the
+     * client desires the same key (no duplicate), rewrites them if the value
+     * changed, or removes them if the client graph no longer wants them.
+     */
+    private _adoptServerTags;
+    /** The framework-managed attribute names currently on a server tag. */
+    private _attrNames;
+}
+/**
+ * Wire a mounted/hydrated `head` node's contribution into `document.head`.
+ * Server-safe (no-op when there is no document). Shared by the mount and hydrate
+ * paths so both establish identical ownership + cleanup.
+ */
+declare function wireHeadBehavior(ctx: RenderContext, graphNode: GraphNode, instance: NodeInstance): void;
+/**
+ * Render the active graph's merged document metadata to an HTML string suitable
+ * for placing inside `<head>`. Walks the graph in document order, merges every
+ * `head()` contribution (last-in-document-order wins per dedup key), and
+ * serializes each effective tag with the `data-streetui-head` marker so the
+ * browser adopts it on hydration. Returns `''` when the app declares no metadata
+ * — so apps that never call `head()` emit nothing extra and existing SSR output
+ * is unchanged.
+ */
+declare function renderHead(compiled: CompiledApplication): string;
+
+/**
+ * RenderContext — shared state for a single mount operation.
+ *
+ * Passed through the render pipeline so every sub-function has access
+ * to the DOM adapter, graph, and instance map without prop-drilling.
+ */
+
+interface RenderContext {
+    readonly dom: DOMAdapter;
+    readonly graph: ApplicationGraph;
+    /** Maps GraphNode.id → its live NodeInstance */
+    readonly instances: Map<string, NodeInstance>;
+    /** The root container element. */
+    readonly container: Element;
+    /**
+     * Optional dev-only sink that observes hydration mismatch repairs. When
+     * absent (the default) the hydration path does no extra work — this is how
+     * 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>;
+    /**
+     * Lazily-created coordinator for `head()` metadata nodes (2.0 §1). Created on
+     * first `wireHeadBehavior` call on the browser (never on the server, where
+     * `dom.head()` is null and `renderHead` emits the metadata instead). Mutable
+     * because it is attached on demand; a render with no `head()` nodes never
+     * allocates one.
+     */
+    head?: HeadManager;
+}
+declare function createRenderContext(dom: DOMAdapter, graph: ApplicationGraph, container: Element, hydrationDiagnostics?: HydrationDiagnosticSink, staticHTML?: ReadonlyMap<string, string>): RenderContext;
+
 /**
  * SSR state transfer (dehydration) — move server-resolved data to the client.
  *
@@ -204,4 +383,4 @@ interface RenderToStringOptions {
  */
 declare function renderToString(compiled: CompiledApplication, options?: RenderToStringOptions): string;
 
-export { type DOMAdapter as D, type RenderToStringOptions as R, STATE_MARKER_ATTR as S, ServerDOMAdapter as a, renderToString as b, serverDOMAdapter as c, readState as r, serializeState as s };
+export { CleanupRegistry as C, type DOMAdapter as D, HeadManager as H, Lifecycle as L, NodeInstance as N, type RenderContext as R, STATE_MARKER_ATTR as S, type LifecycleHook as a, type LifecyclePhase as b, type RenderToStringOptions as c, ServerDOMAdapter as d, createRenderContext as e, renderHead as f, renderToString as g, serverDOMAdapter as h, readState as r, serializeState as s, wireHeadBehavior as w };