@streetui/runtime 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StreetUI contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,26 @@
+# @streetui/runtime
+
+StreetUI runtime — application mounting, lifecycle, node instances, state/event integration
+
+Part of [StreetUI](https://github.com/streetui/streetui) — a semantic,
+signal-based UI framework with its own reactivity and keyed DOM reconciler
+(no virtual DOM).
+
+## Install
+
+```sh
+npm install @streetui/runtime
+```
+
+## Usage
+
+```ts
+import * as pkg from '@streetui/runtime';
+```
+
+Both ESM (`import`) and CommonJS (`require`) entry points are shipped, with
+matching TypeScript declarations.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,173 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Runtime: () => Runtime,
+  RuntimeNodeInstance: () => RuntimeNodeInstance,
+  createRuntime: () => createRuntime
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/node-instance.ts
+var import_core = require("@streetui/core");
+var RuntimeNodeInstance = class {
+  graphNode;
+  domNode;
+  children = [];
+  cleanup = new import_core.CleanupRegistry();
+  _mounted = false;
+  constructor(options) {
+    this.graphNode = options.graphNode;
+    this.domNode = options.domNode;
+  }
+  get isMounted() {
+    return this._mounted;
+  }
+  mount() {
+    this._mounted = true;
+  }
+  unmount() {
+    if (!this._mounted) return;
+    this._mounted = false;
+    for (const child of this.children) {
+      child.unmount();
+    }
+    this.cleanup.run();
+  }
+  addChild(instance) {
+    this.children.push(instance);
+  }
+  /** Subscribe to a signal and register the unsubscribe for cleanup. */
+  trackSignal(signal, handler) {
+    const unsub = signal.subscribe(handler);
+    this.cleanup.add(unsub);
+  }
+  /** Register an arbitrary cleanup function (e.g. DOM event removal). */
+  trackCleanup(fn) {
+    this.cleanup.add(fn);
+  }
+};
+
+// src/runtime.ts
+var import_core2 = require("@streetui/core");
+var import_scheduler = require("@streetui/scheduler");
+var Runtime = class {
+  _renderer;
+  _scheduler;
+  _cleanup = new import_core2.CleanupRegistry();
+  _renderHandle = null;
+  _mounted = false;
+  constructor(options) {
+    this._renderer = options.renderer;
+    this._scheduler = options.scheduler ?? new import_scheduler.Scheduler();
+  }
+  get isMounted() {
+    return this._mounted;
+  }
+  /**
+   * Mount the compiled application into the given DOM container.
+   */
+  mount(compiled, container) {
+    if (this._mounted) {
+      throw new Error("[Runtime] Already mounted. Call unmount() first.");
+    }
+    this._renderHandle = this._renderer.mount(compiled, container);
+    this._mounted = true;
+    this._bindSignals(compiled.graph);
+    const self = this;
+    return {
+      renderHandle: this._renderHandle,
+      runtime: this,
+      unmount() {
+        self.unmount();
+      },
+      flush() {
+        self._scheduler.flush();
+      }
+    };
+  }
+  unmount() {
+    if (!this._mounted) return;
+    this._mounted = false;
+    this._renderHandle?.unmount();
+    this._renderHandle = null;
+    this._cleanup.run();
+  }
+  /**
+   * Hydrate a container that already holds server-rendered HTML for this
+   * application. Delegates to the renderer's `hydrate` (adopting the existing
+   * DOM instead of recreating it) and falls back to `mount` for renderers that
+   * cannot hydrate. Signal binding is identical to `mount`, so the live client
+   * lifecycle is established the same way.
+   */
+  hydrate(compiled, container) {
+    if (this._mounted) {
+      throw new Error("[Runtime] Already mounted. Call unmount() first.");
+    }
+    this._renderHandle = this._renderer.hydrate !== void 0 ? this._renderer.hydrate(compiled, container) : this._renderer.mount(compiled, container);
+    this._mounted = true;
+    this._bindSignals(compiled.graph);
+    const self = this;
+    return {
+      renderHandle: this._renderHandle,
+      runtime: this,
+      unmount() {
+        self.unmount();
+      },
+      flush() {
+        self._scheduler.flush();
+      }
+    };
+  }
+  /**
+   * Walk the graph and subscribe to all signal-bound nodes.
+   * When a signal changes, schedule a renderer update for that node.
+   */
+  _bindSignals(graph) {
+    graph.walk((node) => {
+      for (const stateRef of node.stateRefs) {
+        const signalKey = `__signal__${stateRef.signalId}`;
+        const maybeSignal = graph.getHandler(signalKey);
+        if (maybeSignal === void 0 || typeof maybeSignal.subscribe !== "function") continue;
+        const unsub = maybeSignal.subscribe(() => {
+          this._scheduler.schedule({
+            key: `update:${node.id}:${stateRef.propKey}`,
+            priority: "normal",
+            fn: () => {
+              this._renderHandle?.flush();
+            }
+          });
+        });
+        this._cleanup.add(unsub);
+      }
+    });
+  }
+};
+function createRuntime(options) {
+  return new Runtime(options);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Runtime,
+  RuntimeNodeInstance,
+  createRuntime
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/node-instance.ts","../src/runtime.ts"],"sourcesContent":["export * from './node-instance.js';\nexport * from './renderer-interface.js';\nexport * from './runtime.js';\n","/**\n * RuntimeNodeInstance — the runtime's live representation of a GraphNode.\n *\n * Each GraphNode in the compiled application gets a corresponding\n * RuntimeNodeInstance during mounting. The instance owns:\n *  - the DOM node(s) produced for this graph node\n *  - all signal subscriptions that drive updates\n *  - all DOM event listeners\n *  - child instances\n */\n\nimport { CleanupRegistry } from '@streetui/core';\nimport type { GraphNode } from '@streetui/graph';\nimport type { Signal, ReadonlySignal } from '@streetui/state';\n\nexport interface NodeInstanceOptions {\n  readonly graphNode: GraphNode;\n  readonly domNode: Node;\n}\n\nexport class RuntimeNodeInstance {\n  readonly graphNode: GraphNode;\n  domNode: Node;\n  readonly children: RuntimeNodeInstance[] = [];\n  readonly cleanup: CleanupRegistry = new CleanupRegistry();\n  private _mounted = false;\n\n  constructor(options: NodeInstanceOptions) {\n    this.graphNode = options.graphNode;\n    this.domNode = options.domNode;\n  }\n\n  get isMounted(): boolean {\n    return this._mounted;\n  }\n\n  mount(): void {\n    this._mounted = true;\n  }\n\n  unmount(): void {\n    if (!this._mounted) return;\n    this._mounted = false;\n    for (const child of this.children) {\n      child.unmount();\n    }\n    this.cleanup.run();\n  }\n\n  addChild(instance: RuntimeNodeInstance): void {\n    this.children.push(instance);\n  }\n\n  /** Subscribe to a signal and register the unsubscribe for cleanup. */\n  trackSignal<T>(\n    signal: Signal<T> | ReadonlySignal<T>,\n    handler: (value: T) => void,\n  ): void {\n    const unsub = signal.subscribe(handler);\n    this.cleanup.add(unsub);\n  }\n\n  /** Register an arbitrary cleanup function (e.g. DOM event removal). */\n  trackCleanup(fn: () => void): void {\n    this.cleanup.add(fn);\n  }\n}\n","/**\n * StreetUI Runtime.\n *\n * Owns:\n *  - Signal binding — wires signal subscriptions to renderer update calls\n *  - Event dispatch — calls registered handlers from graph events\n *  - Lifecycle — orchestrates mount, update cycles, unmount\n *\n * The runtime does NOT create DOM nodes. It calls into StreetRenderer\n * for all DOM operations.\n */\n\nimport { CleanupRegistry } from '@streetui/core';\nimport type { GraphNode, ApplicationGraph } from '@streetui/graph';\nimport type { Signal, ReadonlySignal } from '@streetui/state';\nimport { Scheduler } from '@streetui/scheduler';\nimport type { CompiledApplication } from '@streetui/compiler';\nimport type { StreetRenderer, RenderHandle } from './renderer-interface.js';\n\nexport interface RuntimeOptions {\n  readonly renderer: StreetRenderer;\n  readonly scheduler?: Scheduler;\n}\n\nexport interface MountedApplication {\n  readonly renderHandle: RenderHandle;\n  readonly runtime: Runtime;\n  unmount(): void;\n  flush(): void;\n}\n\nexport class Runtime {\n  private readonly _renderer: StreetRenderer;\n  private readonly _scheduler: Scheduler;\n  private readonly _cleanup: CleanupRegistry = new CleanupRegistry();\n  private _renderHandle: RenderHandle | null = null;\n  private _mounted = false;\n\n  constructor(options: RuntimeOptions) {\n    this._renderer = options.renderer;\n    this._scheduler = options.scheduler ?? new Scheduler();\n  }\n\n  get isMounted(): boolean {\n    return this._mounted;\n  }\n\n  /**\n   * Mount the compiled application into the given DOM container.\n   */\n  mount(compiled: CompiledApplication, container: Element): MountedApplication {\n    if (this._mounted) {\n      throw new Error('[Runtime] Already mounted. Call unmount() first.');\n    }\n\n    // Hand off to renderer — it creates all DOM nodes\n    this._renderHandle = this._renderer.mount(compiled, container);\n    this._mounted = true;\n\n    // Wire signal subscriptions from the graph\n    this._bindSignals(compiled.graph);\n\n    const self = this;\n    return {\n      renderHandle: this._renderHandle,\n      runtime: this,\n      unmount() { self.unmount(); },\n      flush() { self._scheduler.flush(); },\n    };\n  }\n\n  unmount(): void {\n    if (!this._mounted) return;\n    this._mounted = false;\n    this._renderHandle?.unmount();\n    this._renderHandle = null;\n    this._cleanup.run();\n  }\n\n  /**\n   * Hydrate a container that already holds server-rendered HTML for this\n   * application. Delegates to the renderer's `hydrate` (adopting the existing\n   * DOM instead of recreating it) and falls back to `mount` for renderers that\n   * cannot hydrate. Signal binding is identical to `mount`, so the live client\n   * lifecycle is established the same way.\n   */\n  hydrate(compiled: CompiledApplication, container: Element): MountedApplication {\n    if (this._mounted) {\n      throw new Error('[Runtime] Already mounted. Call unmount() first.');\n    }\n\n    this._renderHandle = this._renderer.hydrate !== undefined\n      ? this._renderer.hydrate(compiled, container)\n      : this._renderer.mount(compiled, container);\n    this._mounted = true;\n\n    this._bindSignals(compiled.graph);\n\n    const self = this;\n    return {\n      renderHandle: this._renderHandle,\n      runtime: this,\n      unmount() { self.unmount(); },\n      flush() { self._scheduler.flush(); },\n    };\n  }\n\n  /**\n   * Walk the graph and subscribe to all signal-bound nodes.\n   * When a signal changes, schedule a renderer update for that node.\n   */\n  private _bindSignals(graph: ApplicationGraph): void {\n    graph.walk((node) => {\n      for (const stateRef of node.stateRefs) {\n        const signalKey = `__signal__${stateRef.signalId}`;\n        const maybeSignal = graph.getHandler(signalKey) as\n          | (Signal<unknown> & ReadonlySignal<unknown>)\n          | undefined;\n\n        if (maybeSignal === undefined || typeof maybeSignal.subscribe !== 'function') continue;\n\n        const unsub = maybeSignal.subscribe(() => {\n          // Schedule a re-render update keyed to this node+prop\n          this._scheduler.schedule({\n            key: `update:${node.id}:${stateRef.propKey}`,\n            priority: 'normal',\n            fn: () => {\n              // The renderer handles the actual DOM update\n              this._renderHandle?.flush();\n            },\n          });\n        });\n        this._cleanup.add(unsub);\n      }\n    });\n  }\n}\n\n/**\n * Convenience factory — create a runtime, mount, and return the handle.\n */\nexport function createRuntime(options: RuntimeOptions): Runtime {\n  return new Runtime(options);\n}\n"],"mappings":"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","names":["import_core"]}

package/dist/index.d.cts

@@ -0,0 +1,116 @@
+import { CleanupRegistry } from '@streetui/core';
+import { GraphNode } from '@streetui/graph';
+import { Signal, ReadonlySignal } from '@streetui/state';
+import { CompiledApplication } from '@streetui/compiler';
+import { Scheduler } from '@streetui/scheduler';
+
+/**
+ * RuntimeNodeInstance — the runtime's live representation of a GraphNode.
+ *
+ * Each GraphNode in the compiled application gets a corresponding
+ * RuntimeNodeInstance during mounting. The instance owns:
+ *  - the DOM node(s) produced for this graph node
+ *  - all signal subscriptions that drive updates
+ *  - all DOM event listeners
+ *  - child instances
+ */
+
+interface NodeInstanceOptions {
+    readonly graphNode: GraphNode;
+    readonly domNode: Node;
+}
+declare class RuntimeNodeInstance {
+    readonly graphNode: GraphNode;
+    domNode: Node;
+    readonly children: RuntimeNodeInstance[];
+    readonly cleanup: CleanupRegistry;
+    private _mounted;
+    constructor(options: NodeInstanceOptions);
+    get isMounted(): boolean;
+    mount(): void;
+    unmount(): void;
+    addChild(instance: RuntimeNodeInstance): void;
+    /** Subscribe to a signal and register the unsubscribe for cleanup. */
+    trackSignal<T>(signal: Signal<T> | ReadonlySignal<T>, handler: (value: T) => void): void;
+    /** Register an arbitrary cleanup function (e.g. DOM event removal). */
+    trackCleanup(fn: () => void): void;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * StreetUI Runtime.
+ *
+ * Owns:
+ *  - Signal binding — wires signal subscriptions to renderer update calls
+ *  - Event dispatch — calls registered handlers from graph events
+ *  - Lifecycle — orchestrates mount, update cycles, unmount
+ *
+ * The runtime does NOT create DOM nodes. It calls into StreetRenderer
+ * for all DOM operations.
+ */
+
+interface RuntimeOptions {
+    readonly renderer: StreetRenderer;
+    readonly scheduler?: Scheduler;
+}
+interface MountedApplication {
+    readonly renderHandle: RenderHandle;
+    readonly runtime: Runtime;
+    unmount(): void;
+    flush(): void;
+}
+declare class Runtime {
+    private readonly _renderer;
+    private readonly _scheduler;
+    private readonly _cleanup;
+    private _renderHandle;
+    private _mounted;
+    constructor(options: RuntimeOptions);
+    get isMounted(): boolean;
+    /**
+     * Mount the compiled application into the given DOM container.
+     */
+    mount(compiled: CompiledApplication, container: Element): MountedApplication;
+    unmount(): void;
+    /**
+     * Hydrate a container that already holds server-rendered HTML for this
+     * application. Delegates to the renderer's `hydrate` (adopting the existing
+     * DOM instead of recreating it) and falls back to `mount` for renderers that
+     * cannot hydrate. Signal binding is identical to `mount`, so the live client
+     * lifecycle is established the same way.
+     */
+    hydrate(compiled: CompiledApplication, container: Element): MountedApplication;
+    /**
+     * Walk the graph and subscribe to all signal-bound nodes.
+     * When a signal changes, schedule a renderer update for that node.
+     */
+    private _bindSignals;
+}
+/**
+ * Convenience factory — create a runtime, mount, and return the handle.
+ */
+declare function createRuntime(options: RuntimeOptions): Runtime;
+
+export { type MountedApplication, type NodeInstanceOptions, type RenderHandle, Runtime, RuntimeNodeInstance, type RuntimeOptions, type StreetRenderer, createRuntime };

package/dist/index.d.ts

@@ -0,0 +1,116 @@
+import { CleanupRegistry } from '@streetui/core';
+import { GraphNode } from '@streetui/graph';
+import { Signal, ReadonlySignal } from '@streetui/state';
+import { CompiledApplication } from '@streetui/compiler';
+import { Scheduler } from '@streetui/scheduler';
+
+/**
+ * RuntimeNodeInstance — the runtime's live representation of a GraphNode.
+ *
+ * Each GraphNode in the compiled application gets a corresponding
+ * RuntimeNodeInstance during mounting. The instance owns:
+ *  - the DOM node(s) produced for this graph node
+ *  - all signal subscriptions that drive updates
+ *  - all DOM event listeners
+ *  - child instances
+ */
+
+interface NodeInstanceOptions {
+    readonly graphNode: GraphNode;
+    readonly domNode: Node;
+}
+declare class RuntimeNodeInstance {
+    readonly graphNode: GraphNode;
+    domNode: Node;
+    readonly children: RuntimeNodeInstance[];
+    readonly cleanup: CleanupRegistry;
+    private _mounted;
+    constructor(options: NodeInstanceOptions);
+    get isMounted(): boolean;
+    mount(): void;
+    unmount(): void;
+    addChild(instance: RuntimeNodeInstance): void;
+    /** Subscribe to a signal and register the unsubscribe for cleanup. */
+    trackSignal<T>(signal: Signal<T> | ReadonlySignal<T>, handler: (value: T) => void): void;
+    /** Register an arbitrary cleanup function (e.g. DOM event removal). */
+    trackCleanup(fn: () => void): void;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * StreetUI Runtime.
+ *
+ * Owns:
+ *  - Signal binding — wires signal subscriptions to renderer update calls
+ *  - Event dispatch — calls registered handlers from graph events
+ *  - Lifecycle — orchestrates mount, update cycles, unmount
+ *
+ * The runtime does NOT create DOM nodes. It calls into StreetRenderer
+ * for all DOM operations.
+ */
+
+interface RuntimeOptions {
+    readonly renderer: StreetRenderer;
+    readonly scheduler?: Scheduler;
+}
+interface MountedApplication {
+    readonly renderHandle: RenderHandle;
+    readonly runtime: Runtime;
+    unmount(): void;
+    flush(): void;
+}
+declare class Runtime {
+    private readonly _renderer;
+    private readonly _scheduler;
+    private readonly _cleanup;
+    private _renderHandle;
+    private _mounted;
+    constructor(options: RuntimeOptions);
+    get isMounted(): boolean;
+    /**
+     * Mount the compiled application into the given DOM container.
+     */
+    mount(compiled: CompiledApplication, container: Element): MountedApplication;
+    unmount(): void;
+    /**
+     * Hydrate a container that already holds server-rendered HTML for this
+     * application. Delegates to the renderer's `hydrate` (adopting the existing
+     * DOM instead of recreating it) and falls back to `mount` for renderers that
+     * cannot hydrate. Signal binding is identical to `mount`, so the live client
+     * lifecycle is established the same way.
+     */
+    hydrate(compiled: CompiledApplication, container: Element): MountedApplication;
+    /**
+     * Walk the graph and subscribe to all signal-bound nodes.
+     * When a signal changes, schedule a renderer update for that node.
+     */
+    private _bindSignals;
+}
+/**
+ * Convenience factory — create a runtime, mount, and return the handle.
+ */
+declare function createRuntime(options: RuntimeOptions): Runtime;
+
+export { type MountedApplication, type NodeInstanceOptions, type RenderHandle, Runtime, RuntimeNodeInstance, type RuntimeOptions, type StreetRenderer, createRuntime };

package/dist/index.js

@@ -0,0 +1,144 @@
+// src/node-instance.ts
+import { CleanupRegistry } from "@streetui/core";
+var RuntimeNodeInstance = class {
+  graphNode;
+  domNode;
+  children = [];
+  cleanup = new CleanupRegistry();
+  _mounted = false;
+  constructor(options) {
+    this.graphNode = options.graphNode;
+    this.domNode = options.domNode;
+  }
+  get isMounted() {
+    return this._mounted;
+  }
+  mount() {
+    this._mounted = true;
+  }
+  unmount() {
+    if (!this._mounted) return;
+    this._mounted = false;
+    for (const child of this.children) {
+      child.unmount();
+    }
+    this.cleanup.run();
+  }
+  addChild(instance) {
+    this.children.push(instance);
+  }
+  /** Subscribe to a signal and register the unsubscribe for cleanup. */
+  trackSignal(signal, handler) {
+    const unsub = signal.subscribe(handler);
+    this.cleanup.add(unsub);
+  }
+  /** Register an arbitrary cleanup function (e.g. DOM event removal). */
+  trackCleanup(fn) {
+    this.cleanup.add(fn);
+  }
+};
+
+// src/runtime.ts
+import { CleanupRegistry as CleanupRegistry2 } from "@streetui/core";
+import { Scheduler } from "@streetui/scheduler";
+var Runtime = class {
+  _renderer;
+  _scheduler;
+  _cleanup = new CleanupRegistry2();
+  _renderHandle = null;
+  _mounted = false;
+  constructor(options) {
+    this._renderer = options.renderer;
+    this._scheduler = options.scheduler ?? new Scheduler();
+  }
+  get isMounted() {
+    return this._mounted;
+  }
+  /**
+   * Mount the compiled application into the given DOM container.
+   */
+  mount(compiled, container) {
+    if (this._mounted) {
+      throw new Error("[Runtime] Already mounted. Call unmount() first.");
+    }
+    this._renderHandle = this._renderer.mount(compiled, container);
+    this._mounted = true;
+    this._bindSignals(compiled.graph);
+    const self = this;
+    return {
+      renderHandle: this._renderHandle,
+      runtime: this,
+      unmount() {
+        self.unmount();
+      },
+      flush() {
+        self._scheduler.flush();
+      }
+    };
+  }
+  unmount() {
+    if (!this._mounted) return;
+    this._mounted = false;
+    this._renderHandle?.unmount();
+    this._renderHandle = null;
+    this._cleanup.run();
+  }
+  /**
+   * Hydrate a container that already holds server-rendered HTML for this
+   * application. Delegates to the renderer's `hydrate` (adopting the existing
+   * DOM instead of recreating it) and falls back to `mount` for renderers that
+   * cannot hydrate. Signal binding is identical to `mount`, so the live client
+   * lifecycle is established the same way.
+   */
+  hydrate(compiled, container) {
+    if (this._mounted) {
+      throw new Error("[Runtime] Already mounted. Call unmount() first.");
+    }
+    this._renderHandle = this._renderer.hydrate !== void 0 ? this._renderer.hydrate(compiled, container) : this._renderer.mount(compiled, container);
+    this._mounted = true;
+    this._bindSignals(compiled.graph);
+    const self = this;
+    return {
+      renderHandle: this._renderHandle,
+      runtime: this,
+      unmount() {
+        self.unmount();
+      },
+      flush() {
+        self._scheduler.flush();
+      }
+    };
+  }
+  /**
+   * Walk the graph and subscribe to all signal-bound nodes.
+   * When a signal changes, schedule a renderer update for that node.
+   */
+  _bindSignals(graph) {
+    graph.walk((node) => {
+      for (const stateRef of node.stateRefs) {
+        const signalKey = `__signal__${stateRef.signalId}`;
+        const maybeSignal = graph.getHandler(signalKey);
+        if (maybeSignal === void 0 || typeof maybeSignal.subscribe !== "function") continue;
+        const unsub = maybeSignal.subscribe(() => {
+          this._scheduler.schedule({
+            key: `update:${node.id}:${stateRef.propKey}`,
+            priority: "normal",
+            fn: () => {
+              this._renderHandle?.flush();
+            }
+          });
+        });
+        this._cleanup.add(unsub);
+      }
+    });
+  }
+};
+function createRuntime(options) {
+  return new Runtime(options);
+}
+export {
+  Runtime,
+  RuntimeNodeInstance,
+  createRuntime
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/node-instance.ts","../src/runtime.ts"],"sourcesContent":["/**\n * RuntimeNodeInstance — the runtime's live representation of a GraphNode.\n *\n * Each GraphNode in the compiled application gets a corresponding\n * RuntimeNodeInstance during mounting. The instance owns:\n *  - the DOM node(s) produced for this graph node\n *  - all signal subscriptions that drive updates\n *  - all DOM event listeners\n *  - child instances\n */\n\nimport { CleanupRegistry } from '@streetui/core';\nimport type { GraphNode } from '@streetui/graph';\nimport type { Signal, ReadonlySignal } from '@streetui/state';\n\nexport interface NodeInstanceOptions {\n  readonly graphNode: GraphNode;\n  readonly domNode: Node;\n}\n\nexport class RuntimeNodeInstance {\n  readonly graphNode: GraphNode;\n  domNode: Node;\n  readonly children: RuntimeNodeInstance[] = [];\n  readonly cleanup: CleanupRegistry = new CleanupRegistry();\n  private _mounted = false;\n\n  constructor(options: NodeInstanceOptions) {\n    this.graphNode = options.graphNode;\n    this.domNode = options.domNode;\n  }\n\n  get isMounted(): boolean {\n    return this._mounted;\n  }\n\n  mount(): void {\n    this._mounted = true;\n  }\n\n  unmount(): void {\n    if (!this._mounted) return;\n    this._mounted = false;\n    for (const child of this.children) {\n      child.unmount();\n    }\n    this.cleanup.run();\n  }\n\n  addChild(instance: RuntimeNodeInstance): void {\n    this.children.push(instance);\n  }\n\n  /** Subscribe to a signal and register the unsubscribe for cleanup. */\n  trackSignal<T>(\n    signal: Signal<T> | ReadonlySignal<T>,\n    handler: (value: T) => void,\n  ): void {\n    const unsub = signal.subscribe(handler);\n    this.cleanup.add(unsub);\n  }\n\n  /** Register an arbitrary cleanup function (e.g. DOM event removal). */\n  trackCleanup(fn: () => void): void {\n    this.cleanup.add(fn);\n  }\n}\n","/**\n * StreetUI Runtime.\n *\n * Owns:\n *  - Signal binding — wires signal subscriptions to renderer update calls\n *  - Event dispatch — calls registered handlers from graph events\n *  - Lifecycle — orchestrates mount, update cycles, unmount\n *\n * The runtime does NOT create DOM nodes. It calls into StreetRenderer\n * for all DOM operations.\n */\n\nimport { CleanupRegistry } from '@streetui/core';\nimport type { GraphNode, ApplicationGraph } from '@streetui/graph';\nimport type { Signal, ReadonlySignal } from '@streetui/state';\nimport { Scheduler } from '@streetui/scheduler';\nimport type { CompiledApplication } from '@streetui/compiler';\nimport type { StreetRenderer, RenderHandle } from './renderer-interface.js';\n\nexport interface RuntimeOptions {\n  readonly renderer: StreetRenderer;\n  readonly scheduler?: Scheduler;\n}\n\nexport interface MountedApplication {\n  readonly renderHandle: RenderHandle;\n  readonly runtime: Runtime;\n  unmount(): void;\n  flush(): void;\n}\n\nexport class Runtime {\n  private readonly _renderer: StreetRenderer;\n  private readonly _scheduler: Scheduler;\n  private readonly _cleanup: CleanupRegistry = new CleanupRegistry();\n  private _renderHandle: RenderHandle | null = null;\n  private _mounted = false;\n\n  constructor(options: RuntimeOptions) {\n    this._renderer = options.renderer;\n    this._scheduler = options.scheduler ?? new Scheduler();\n  }\n\n  get isMounted(): boolean {\n    return this._mounted;\n  }\n\n  /**\n   * Mount the compiled application into the given DOM container.\n   */\n  mount(compiled: CompiledApplication, container: Element): MountedApplication {\n    if (this._mounted) {\n      throw new Error('[Runtime] Already mounted. Call unmount() first.');\n    }\n\n    // Hand off to renderer — it creates all DOM nodes\n    this._renderHandle = this._renderer.mount(compiled, container);\n    this._mounted = true;\n\n    // Wire signal subscriptions from the graph\n    this._bindSignals(compiled.graph);\n\n    const self = this;\n    return {\n      renderHandle: this._renderHandle,\n      runtime: this,\n      unmount() { self.unmount(); },\n      flush() { self._scheduler.flush(); },\n    };\n  }\n\n  unmount(): void {\n    if (!this._mounted) return;\n    this._mounted = false;\n    this._renderHandle?.unmount();\n    this._renderHandle = null;\n    this._cleanup.run();\n  }\n\n  /**\n   * Hydrate a container that already holds server-rendered HTML for this\n   * application. Delegates to the renderer's `hydrate` (adopting the existing\n   * DOM instead of recreating it) and falls back to `mount` for renderers that\n   * cannot hydrate. Signal binding is identical to `mount`, so the live client\n   * lifecycle is established the same way.\n   */\n  hydrate(compiled: CompiledApplication, container: Element): MountedApplication {\n    if (this._mounted) {\n      throw new Error('[Runtime] Already mounted. Call unmount() first.');\n    }\n\n    this._renderHandle = this._renderer.hydrate !== undefined\n      ? this._renderer.hydrate(compiled, container)\n      : this._renderer.mount(compiled, container);\n    this._mounted = true;\n\n    this._bindSignals(compiled.graph);\n\n    const self = this;\n    return {\n      renderHandle: this._renderHandle,\n      runtime: this,\n      unmount() { self.unmount(); },\n      flush() { self._scheduler.flush(); },\n    };\n  }\n\n  /**\n   * Walk the graph and subscribe to all signal-bound nodes.\n   * When a signal changes, schedule a renderer update for that node.\n   */\n  private _bindSignals(graph: ApplicationGraph): void {\n    graph.walk((node) => {\n      for (const stateRef of node.stateRefs) {\n        const signalKey = `__signal__${stateRef.signalId}`;\n        const maybeSignal = graph.getHandler(signalKey) as\n          | (Signal<unknown> & ReadonlySignal<unknown>)\n          | undefined;\n\n        if (maybeSignal === undefined || typeof maybeSignal.subscribe !== 'function') continue;\n\n        const unsub = maybeSignal.subscribe(() => {\n          // Schedule a re-render update keyed to this node+prop\n          this._scheduler.schedule({\n            key: `update:${node.id}:${stateRef.propKey}`,\n            priority: 'normal',\n            fn: () => {\n              // The renderer handles the actual DOM update\n              this._renderHandle?.flush();\n            },\n          });\n        });\n        this._cleanup.add(unsub);\n      }\n    });\n  }\n}\n\n/**\n * Convenience factory — create a runtime, mount, and return the handle.\n */\nexport function createRuntime(options: RuntimeOptions): Runtime {\n  return new Runtime(options);\n}\n"],"mappings":"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","names":["CleanupRegistry"]}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@streetui/runtime",
+  "version": "1.0.0",
+  "description": "StreetUI runtime — application mounting, lifecycle, node instances, state/event integration",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@streetui/core": "1.0.0",
+    "@streetui/graph": "1.0.0",
+    "@streetui/state": "1.0.0",
+    "@streetui/events": "1.0.0",
+    "@streetui/scheduler": "1.0.0",
+    "@streetui/compiler": "1.0.0",
+    "@streetui/dsl": "1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "*",
+    "tsup": "*",
+    "vitest": "*"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ]
+}