@matthesketh/utopia-runtime 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Hesketh
+
+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,74 @@
+# @matthesketh/utopia-runtime
+
+DOM renderer, directives, component lifecycle, scheduler, and hydration for UtopiaJS. This is the client-side runtime that compiled `.utopia` components import from.
+
+## Install
+
+```bash
+pnpm add @matthesketh/utopia-runtime
+```
+
+## Usage
+
+```ts
+import { mount } from '@matthesketh/utopia-runtime';
+import App from './App.utopia';
+
+mount(App, '#app');
+```
+
+For hydrating server-rendered HTML:
+
+```ts
+import { hydrate } from '@matthesketh/utopia-runtime';
+import App from './App.utopia';
+
+hydrate(App, '#app');
+```
+
+## API
+
+**DOM helpers** (used by compiled template output):
+
+| Export | Description |
+|--------|-------------|
+| `createElement(tag)` | Create a DOM element |
+| `createTextNode(text)` | Create a text node |
+| `createComment(text)` | Create a comment node |
+| `setText(node, text)` | Set text content |
+| `setAttr(el, name, value)` | Set an attribute |
+| `addEventListener(el, event, handler)` | Attach an event listener |
+| `appendChild(parent, child)` | Append a child node |
+| `insertBefore(parent, node, ref)` | Insert before a reference node |
+| `removeNode(node)` | Remove a node from the DOM |
+
+**Directives** (used by compiled control-flow):
+
+| Export | Description |
+|--------|-------------|
+| `createIf(anchor, cond, trueBranch, falseBranch?)` | Conditional rendering |
+| `createFor(anchor, list, renderFn)` | List rendering |
+| `createComponent(def, props?)` | Component instantiation |
+
+**Lifecycle:**
+
+| Export | Description |
+|--------|-------------|
+| `mount(component, target)` | Mount a component to the DOM |
+| `createComponentInstance(def, props?)` | Create a component instance |
+| `hydrate(component, target)` | Hydrate server-rendered HTML |
+
+**Scheduler:**
+
+| Export | Description |
+|--------|-------------|
+| `queueJob(fn)` | Queue a microtask job |
+| `nextTick()` | Wait for the next flush |
+
+**Re-exports from `@matthesketh/utopia-core`:** `signal`, `computed`, `effect`, `batch`, `untrack`, `createEffect`.
+
+See [docs/architecture.md](../../docs/architecture.md) and [docs/ssr.md](../../docs/ssr.md) for full details.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,425 @@
+"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, {
+  addEventListener: () => addEventListener,
+  appendChild: () => appendChild,
+  batch: () => import_utopia_core2.batch,
+  computed: () => import_utopia_core2.computed,
+  createComment: () => createComment,
+  createComponent: () => createComponent,
+  createComponentInstance: () => createComponentInstance,
+  createEffect: () => import_utopia_core3.effect,
+  createElement: () => createElement,
+  createFor: () => createFor,
+  createIf: () => createIf,
+  createTextNode: () => createTextNode,
+  effect: () => import_utopia_core2.effect,
+  hydrate: () => hydrate,
+  insertBefore: () => insertBefore,
+  mount: () => mount,
+  nextTick: () => nextTick,
+  queueJob: () => queueJob,
+  removeNode: () => removeNode,
+  setAttr: () => setAttr,
+  setText: () => setText,
+  signal: () => import_utopia_core2.signal,
+  untrack: () => import_utopia_core2.untrack
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/component.ts
+function createComponentInstance(definition, props) {
+  let styleElement = null;
+  const instance = {
+    el: null,
+    props: props ?? {},
+    slots: {},
+    mount(target, anchor) {
+      if (instance.el) {
+        target.insertBefore(instance.el, anchor ?? null);
+        return;
+      }
+      const ctx = definition.setup ? definition.setup(instance.props) : {};
+      const renderCtx = {
+        ...ctx,
+        $slots: instance.slots
+      };
+      instance.el = definition.render(renderCtx);
+      target.insertBefore(instance.el, anchor ?? null);
+      if (definition.styles && !styleElement) {
+        styleElement = document.createElement("style");
+        styleElement.textContent = definition.styles;
+        document.head.appendChild(styleElement);
+      }
+    },
+    unmount() {
+      if (instance.el && instance.el.parentNode) {
+        instance.el.parentNode.removeChild(instance.el);
+      }
+      instance.el = null;
+      if (styleElement && styleElement.parentNode) {
+        styleElement.parentNode.removeChild(styleElement);
+        styleElement = null;
+      }
+    }
+  };
+  return instance;
+}
+function mount(component, target) {
+  const el = typeof target === "string" ? document.querySelector(target) : target;
+  if (!el) {
+    throw new Error(
+      `[utopia] Mount target not found: ${typeof target === "string" ? target : "Element"}`
+    );
+  }
+  const instance = createComponentInstance(component);
+  instance.mount(el);
+  return instance;
+}
+
+// src/hydration.ts
+var isHydrating = false;
+var hydrateNode = null;
+var cursorStack = [];
+function claimNode() {
+  const node = hydrateNode;
+  if (node) {
+    hydrateNode = node.nextSibling;
+  }
+  return node;
+}
+function enterNode(el) {
+  cursorStack.push(hydrateNode);
+  hydrateNode = el.firstChild;
+}
+function exitNode() {
+  hydrateNode = cursorStack.pop() ?? null;
+}
+function hydrate(component, target) {
+  const el = typeof target === "string" ? document.querySelector(target) : target;
+  if (!el) {
+    throw new Error(
+      `[utopia] Hydration target not found: ${typeof target === "string" ? target : "Element"}`
+    );
+  }
+  isHydrating = true;
+  hydrateNode = el.firstChild;
+  try {
+    const instance = createComponentInstance(component);
+    const ctx = component.setup ? component.setup(instance.props) : {};
+    const renderCtx = {
+      ...ctx,
+      $slots: instance.slots
+    };
+    instance.el = component.render(renderCtx);
+    if (component.styles) {
+      const style = document.createElement("style");
+      style.textContent = component.styles;
+      document.head.appendChild(style);
+    }
+  } finally {
+    isHydrating = false;
+    hydrateNode = null;
+    cursorStack.length = 0;
+  }
+}
+
+// src/dom.ts
+function createElement(tag) {
+  if (isHydrating) {
+    const node = claimNode();
+    if (node && node.nodeType === 1) {
+      enterNode(node);
+      return node;
+    }
+    if (typeof process !== "undefined" && process.env?.["NODE_ENV"] !== "production") {
+      console.warn(`[utopia] Hydration mismatch: expected <${tag}>, got`, node);
+    }
+  }
+  return document.createElement(tag);
+}
+function createTextNode(text) {
+  if (isHydrating) {
+    const node = claimNode();
+    if (node && node.nodeType === 3) {
+      return node;
+    }
+    if (typeof process !== "undefined" && process.env?.["NODE_ENV"] !== "production") {
+      console.warn(`[utopia] Hydration mismatch: expected text node, got`, node);
+    }
+  }
+  return document.createTextNode(String(text));
+}
+function setText(node, value) {
+  const text = value == null ? "" : String(value);
+  if (node.data !== text) {
+    node.data = text;
+  }
+}
+function setAttr(el, name, value) {
+  if (name === "class") {
+    if (value == null || value === false) {
+      el.removeAttribute("class");
+    } else if (typeof value === "string") {
+      el.className = value;
+    } else if (typeof value === "object") {
+      const classes = [];
+      for (const key of Object.keys(value)) {
+        if (value[key]) {
+          classes.push(key);
+        }
+      }
+      el.className = classes.join(" ");
+    }
+    return;
+  }
+  if (name === "style") {
+    const htmlEl = el;
+    if (value == null || value === false) {
+      htmlEl.removeAttribute("style");
+    } else if (typeof value === "string") {
+      htmlEl.style.cssText = value;
+    } else if (typeof value === "object") {
+      htmlEl.style.cssText = "";
+      for (const prop of Object.keys(value)) {
+        const val = value[prop];
+        if (val != null) {
+          htmlEl.style.setProperty(
+            prop.replace(/([A-Z])/g, "-$1").toLowerCase(),
+            String(val)
+          );
+        }
+      }
+    }
+    return;
+  }
+  const BOOLEAN_ATTRS = /* @__PURE__ */ new Set([
+    "disabled",
+    "checked",
+    "readonly",
+    "hidden",
+    "selected",
+    "required",
+    "multiple",
+    "autofocus",
+    "autoplay",
+    "controls",
+    "loop",
+    "muted",
+    "open",
+    "novalidate"
+  ]);
+  if (BOOLEAN_ATTRS.has(name)) {
+    if (value) {
+      el.setAttribute(name, "");
+      if (name in el) {
+        el[name] = true;
+      }
+    } else {
+      el.removeAttribute(name);
+      if (name in el) {
+        el[name] = false;
+      }
+    }
+    return;
+  }
+  if (name.startsWith("data-")) {
+    const key = name.slice(5).replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    el.dataset[key] = value == null ? "" : String(value);
+    return;
+  }
+  if (value == null || value === false) {
+    el.removeAttribute(name);
+  } else {
+    el.setAttribute(name, value === true ? "" : String(value));
+  }
+}
+function addEventListener(el, event, handler) {
+  el.addEventListener(event, handler);
+  return () => {
+    el.removeEventListener(event, handler);
+  };
+}
+function insertBefore(parent, node, anchor) {
+  parent.insertBefore(node, anchor);
+}
+function removeNode(node) {
+  if (node.parentNode) {
+    node.parentNode.removeChild(node);
+  }
+}
+function appendChild(parent, child) {
+  if (isHydrating) {
+    if (child.nodeType === 1) {
+      exitNode();
+    }
+    return;
+  }
+  parent.appendChild(child);
+}
+function createComment(text) {
+  if (isHydrating) {
+    const node = claimNode();
+    if (node && node.nodeType === 8) {
+      return node;
+    }
+    if (typeof process !== "undefined" && process.env?.["NODE_ENV"] !== "production") {
+      console.warn(`[utopia] Hydration mismatch: expected comment node, got`, node);
+    }
+  }
+  return document.createComment(text);
+}
+
+// src/directives.ts
+var import_utopia_core = require("@matthesketh/utopia-core");
+function clearNodes(nodes) {
+  for (const node of nodes) {
+    removeNode(node);
+  }
+  nodes.length = 0;
+}
+function createIf(anchor, condition, renderTrue, renderFalse) {
+  let currentNodes = [];
+  let lastConditionTruthy;
+  const parent = anchor.parentNode;
+  const dispose = (0, import_utopia_core.effect)(() => {
+    const truthy = !!condition();
+    if (truthy === lastConditionTruthy) {
+      return;
+    }
+    lastConditionTruthy = truthy;
+    clearNodes(currentNodes);
+    if (truthy) {
+      const node = renderTrue();
+      currentNodes.push(node);
+      insertBefore(parent, node, anchor);
+    } else if (renderFalse) {
+      const node = renderFalse();
+      currentNodes.push(node);
+      insertBefore(parent, node, anchor);
+    }
+  });
+  return () => {
+    dispose();
+    clearNodes(currentNodes);
+  };
+}
+function createFor(anchor, list, renderItem, key) {
+  let currentNodes = [];
+  const parent = anchor.parentNode;
+  void key;
+  const dispose = (0, import_utopia_core.effect)(() => {
+    const items = list();
+    clearNodes(currentNodes);
+    for (let i = 0; i < items.length; i++) {
+      const node = renderItem(items[i], i);
+      currentNodes.push(node);
+      insertBefore(parent, node, anchor);
+    }
+  });
+  return () => {
+    dispose();
+    clearNodes(currentNodes);
+  };
+}
+function createComponent(Component, props, children) {
+  const instance = createComponentInstance(Component, props);
+  if (children) {
+    for (const slotName of Object.keys(children)) {
+      instance.slots[slotName] = children[slotName];
+    }
+  }
+  const ctx = Component.setup ? Component.setup(instance.props) : {};
+  const renderCtx = {
+    ...ctx,
+    $slots: instance.slots
+  };
+  instance.el = Component.render(renderCtx);
+  if (Component.styles) {
+    const style = document.createElement("style");
+    style.textContent = Component.styles;
+    document.head.appendChild(style);
+  }
+  return instance.el;
+}
+
+// src/scheduler.ts
+var queue = /* @__PURE__ */ new Set();
+var isFlushing = false;
+var isFlushPending = false;
+var resolvedPromise = Promise.resolve();
+function queueJob(job) {
+  queue.add(job);
+  if (!isFlushPending && !isFlushing) {
+    isFlushPending = true;
+    resolvedPromise.then(flushJobs);
+  }
+}
+function nextTick() {
+  return resolvedPromise.then();
+}
+function flushJobs() {
+  isFlushPending = false;
+  isFlushing = true;
+  try {
+    for (const job of queue) {
+      queue.delete(job);
+      job();
+    }
+  } finally {
+    isFlushing = false;
+    if (queue.size > 0) {
+      isFlushPending = true;
+      resolvedPromise.then(flushJobs);
+    }
+  }
+}
+
+// src/index.ts
+var import_utopia_core2 = require("@matthesketh/utopia-core");
+var import_utopia_core3 = require("@matthesketh/utopia-core");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  addEventListener,
+  appendChild,
+  batch,
+  computed,
+  createComment,
+  createComponent,
+  createComponentInstance,
+  createEffect,
+  createElement,
+  createFor,
+  createIf,
+  createTextNode,
+  effect,
+  hydrate,
+  insertBefore,
+  mount,
+  nextTick,
+  queueJob,
+  removeNode,
+  setAttr,
+  setText,
+  signal,
+  untrack
+});

package/dist/index.d.cts

@@ -0,0 +1,172 @@
+export { batch, computed, effect as createEffect, effect, signal, untrack } from '@matthesketh/utopia-core';
+
+/**
+ * @matthesketh/utopia-runtime — Low-level DOM helpers
+ *
+ * These thin wrappers are the only layer between compiled .utopia template
+ * output and the real DOM. Keeping them minimal makes tree-shaking effective
+ * and keeps the runtime footprint small.
+ */
+/** Create a real DOM element for the given tag name. */
+declare function createElement(tag: string): HTMLElement;
+/** Create a DOM text node. */
+declare function createTextNode(text: string): Text;
+/**
+ * Set the text content of a Text node. The compiler wraps calls to this
+ * function inside an `effect()` so the DOM stays in sync with signals.
+ */
+declare function setText(node: Text, value: any): void;
+/**
+ * Set an attribute on an element, handling the many special cases that arise
+ * in real-world templates:
+ *
+ * - **class**: accepts a string or an object `{ active: true, hidden: false }`
+ * - **style**: accepts a string or an object `{ color: 'red', fontSize: '14px' }`
+ * - **Boolean attributes** (`disabled`, `checked`, `readonly`, `hidden`,
+ *   `selected`, `required`, `multiple`, `autofocus`, `autoplay`, `controls`,
+ *   `loop`, `muted`, `open`, `novalidate`): set/remove the attribute based on
+ *   truthiness, and also set the IDL property where applicable.
+ * - **data-* attributes**: set via `el.dataset`
+ * - Everything else: plain `setAttribute` / `removeAttribute`.
+ */
+declare function setAttr(el: Element, name: string, value: any): void;
+/**
+ * Add an event listener to an element and return a cleanup function that
+ * removes it.
+ */
+declare function addEventListener(el: Element, event: string, handler: EventListener): () => void;
+/** Insert `node` into `parent` before the given `anchor` (or append if null). */
+declare function insertBefore(parent: Node, node: Node, anchor: Node | null): void;
+/** Remove a node from its parent. No-op if the node has no parent. */
+declare function removeNode(node: Node): void;
+/** Append a child node to a parent. */
+declare function appendChild(parent: Node, child: Node): void;
+/** Create a DOM comment node. */
+declare function createComment(text: string): Comment;
+
+/**
+ * @matthesketh/utopia-runtime — Component lifecycle
+ *
+ * Provides the primitives for instantiating and mounting compiled .utopia
+ * component definitions.
+ */
+/**
+ * A ComponentDefinition is the object the compiler produces for each .utopia
+ * single-file component.
+ */
+interface ComponentDefinition {
+    /** The `<script>` block compiled into a setup function. */
+    setup?: (props: Record<string, any>) => Record<string, any>;
+    /** The `<template>` block compiled into a render function. */
+    render: (ctx: Record<string, any>) => Node;
+    /** Scoped CSS extracted from the `<style>` block, if any. */
+    styles?: string;
+}
+/**
+ * A live instance of a mounted component.
+ */
+interface ComponentInstance {
+    /** The root DOM node produced by `render()`. */
+    el: Node | null;
+    /** The reactive props passed into this component. */
+    props: Record<string, any>;
+    /** Named slots (each value is a factory that returns a DOM subtree). */
+    slots: Record<string, () => Node>;
+    /** Mount the component's root node into the given target element. */
+    mount(target: Element, anchor?: Node): void;
+    /** Remove the component's root node from the DOM and clean up styles. */
+    unmount(): void;
+}
+/**
+ * Create a `ComponentInstance` from a compiled component definition.
+ *
+ * The instance is **not** automatically mounted — call `instance.mount()`
+ * to attach it to the DOM.
+ */
+declare function createComponentInstance(definition: ComponentDefinition, props?: Record<string, any>): ComponentInstance;
+/**
+ * Mount a root component to the page.
+ *
+ * ```ts
+ * import App from './App.utopia'
+ * import { mount } from '@matthesketh/utopia-runtime'
+ *
+ * mount(App, '#app')
+ * ```
+ *
+ * @param component  The compiled root component definition.
+ * @param target     A CSS selector string or a DOM Element to mount into.
+ * @returns The `ComponentInstance`, allowing later `unmount()`.
+ */
+declare function mount(component: ComponentDefinition, target: string | Element): ComponentInstance;
+
+/**
+ * @matthesketh/utopia-runtime — Runtime directive implementations
+ *
+ * These functions are called by the code the compiler emits for control-flow
+ * constructs (`@if`, `@for`) and child components in .utopia templates.
+ */
+
+/**
+ * Conditional rendering directive.
+ *
+ * @param anchor    A Comment node already in the DOM that marks the insertion
+ *                  point. All branch nodes are inserted immediately before it.
+ * @param condition A function that returns a truthy/falsy value (typically
+ *                  reading a signal so the effect tracks it).
+ * @param renderTrue  Factory that produces the DOM subtree for the "true" branch.
+ * @param renderFalse Optional factory for the "false" / else branch.
+ * @returns A dispose function that tears down the effect and removes nodes.
+ */
+declare function createIf(anchor: Comment, condition: () => any, renderTrue: () => Node, renderFalse?: () => Node): () => void;
+/**
+ * List rendering directive.
+ *
+ * @param anchor     Comment node marking the insertion point.
+ * @param list       Function returning the current array (reads signals).
+ * @param renderItem Factory `(item, index) => Node` for each element.
+ * @param key        Optional key extractor for future keyed-diffing optimisation.
+ * @returns A dispose function.
+ */
+declare function createFor<T>(anchor: Comment, list: () => T[], renderItem: (item: T, index: number) => Node, key?: (item: T, index: number) => any): () => void;
+/**
+ * Mount a child component at the given anchor position.
+ *
+ * @param Component  The compiled component definition (has `setup`, `render`,
+ *                   and optional `styles`).
+ * @param props      Props object to pass to the component's setup function.
+ * @param children   Optional slot/children map. Each key maps to a function
+ *                   that returns a DOM node for that slot.
+ * @returns The root DOM node of the mounted component.
+ */
+declare function createComponent(Component: ComponentDefinition, props?: Record<string, any>, children?: Record<string, () => Node>): Node;
+
+/**
+ * @matthesketh/utopia-runtime — Microtask-based update scheduler
+ *
+ * Batches DOM update jobs so that multiple signal changes within the same
+ * synchronous tick only trigger a single DOM update pass.
+ */
+/**
+ * Queue a job for the next microtask flush. Duplicate references to the same
+ * function are automatically de-duplicated because we store them in a Set.
+ */
+declare function queueJob(job: () => void): void;
+/**
+ * Returns a promise that resolves after the current pending flush completes.
+ * Useful for tests and any code that needs to wait for DOM updates.
+ */
+declare function nextTick(): Promise<void>;
+
+/**
+ * Hydrate a server-rendered component. Instead of creating new DOM nodes,
+ * the runtime claims the existing nodes in the target element and attaches
+ * event listeners and reactive effects.
+ *
+ * @param component - The compiled component definition
+ * @param target    - A CSS selector string or DOM Element containing the
+ *                    server-rendered HTML
+ */
+declare function hydrate(component: ComponentDefinition, target: string | Element): void;
+
+export { type ComponentDefinition, type ComponentInstance, addEventListener, appendChild, createComment, createComponent, createComponentInstance, createElement, createFor, createIf, createTextNode, hydrate, insertBefore, mount, nextTick, queueJob, removeNode, setAttr, setText };

package/dist/index.d.ts

@@ -0,0 +1,172 @@
+export { batch, computed, effect as createEffect, effect, signal, untrack } from '@matthesketh/utopia-core';
+
+/**
+ * @matthesketh/utopia-runtime — Low-level DOM helpers
+ *
+ * These thin wrappers are the only layer between compiled .utopia template
+ * output and the real DOM. Keeping them minimal makes tree-shaking effective
+ * and keeps the runtime footprint small.
+ */
+/** Create a real DOM element for the given tag name. */
+declare function createElement(tag: string): HTMLElement;
+/** Create a DOM text node. */
+declare function createTextNode(text: string): Text;
+/**
+ * Set the text content of a Text node. The compiler wraps calls to this
+ * function inside an `effect()` so the DOM stays in sync with signals.
+ */
+declare function setText(node: Text, value: any): void;
+/**
+ * Set an attribute on an element, handling the many special cases that arise
+ * in real-world templates:
+ *
+ * - **class**: accepts a string or an object `{ active: true, hidden: false }`
+ * - **style**: accepts a string or an object `{ color: 'red', fontSize: '14px' }`
+ * - **Boolean attributes** (`disabled`, `checked`, `readonly`, `hidden`,
+ *   `selected`, `required`, `multiple`, `autofocus`, `autoplay`, `controls`,
+ *   `loop`, `muted`, `open`, `novalidate`): set/remove the attribute based on
+ *   truthiness, and also set the IDL property where applicable.
+ * - **data-* attributes**: set via `el.dataset`
+ * - Everything else: plain `setAttribute` / `removeAttribute`.
+ */
+declare function setAttr(el: Element, name: string, value: any): void;
+/**
+ * Add an event listener to an element and return a cleanup function that
+ * removes it.
+ */
+declare function addEventListener(el: Element, event: string, handler: EventListener): () => void;
+/** Insert `node` into `parent` before the given `anchor` (or append if null). */
+declare function insertBefore(parent: Node, node: Node, anchor: Node | null): void;
+/** Remove a node from its parent. No-op if the node has no parent. */
+declare function removeNode(node: Node): void;
+/** Append a child node to a parent. */
+declare function appendChild(parent: Node, child: Node): void;
+/** Create a DOM comment node. */
+declare function createComment(text: string): Comment;
+
+/**
+ * @matthesketh/utopia-runtime — Component lifecycle
+ *
+ * Provides the primitives for instantiating and mounting compiled .utopia
+ * component definitions.
+ */
+/**
+ * A ComponentDefinition is the object the compiler produces for each .utopia
+ * single-file component.
+ */
+interface ComponentDefinition {
+    /** The `<script>` block compiled into a setup function. */
+    setup?: (props: Record<string, any>) => Record<string, any>;
+    /** The `<template>` block compiled into a render function. */
+    render: (ctx: Record<string, any>) => Node;
+    /** Scoped CSS extracted from the `<style>` block, if any. */
+    styles?: string;
+}
+/**
+ * A live instance of a mounted component.
+ */
+interface ComponentInstance {
+    /** The root DOM node produced by `render()`. */
+    el: Node | null;
+    /** The reactive props passed into this component. */
+    props: Record<string, any>;
+    /** Named slots (each value is a factory that returns a DOM subtree). */
+    slots: Record<string, () => Node>;
+    /** Mount the component's root node into the given target element. */
+    mount(target: Element, anchor?: Node): void;
+    /** Remove the component's root node from the DOM and clean up styles. */
+    unmount(): void;
+}
+/**
+ * Create a `ComponentInstance` from a compiled component definition.
+ *
+ * The instance is **not** automatically mounted — call `instance.mount()`
+ * to attach it to the DOM.
+ */
+declare function createComponentInstance(definition: ComponentDefinition, props?: Record<string, any>): ComponentInstance;
+/**
+ * Mount a root component to the page.
+ *
+ * ```ts
+ * import App from './App.utopia'
+ * import { mount } from '@matthesketh/utopia-runtime'
+ *
+ * mount(App, '#app')
+ * ```
+ *
+ * @param component  The compiled root component definition.
+ * @param target     A CSS selector string or a DOM Element to mount into.
+ * @returns The `ComponentInstance`, allowing later `unmount()`.
+ */
+declare function mount(component: ComponentDefinition, target: string | Element): ComponentInstance;
+
+/**
+ * @matthesketh/utopia-runtime — Runtime directive implementations
+ *
+ * These functions are called by the code the compiler emits for control-flow
+ * constructs (`@if`, `@for`) and child components in .utopia templates.
+ */
+
+/**
+ * Conditional rendering directive.
+ *
+ * @param anchor    A Comment node already in the DOM that marks the insertion
+ *                  point. All branch nodes are inserted immediately before it.
+ * @param condition A function that returns a truthy/falsy value (typically
+ *                  reading a signal so the effect tracks it).
+ * @param renderTrue  Factory that produces the DOM subtree for the "true" branch.
+ * @param renderFalse Optional factory for the "false" / else branch.
+ * @returns A dispose function that tears down the effect and removes nodes.
+ */
+declare function createIf(anchor: Comment, condition: () => any, renderTrue: () => Node, renderFalse?: () => Node): () => void;
+/**
+ * List rendering directive.
+ *
+ * @param anchor     Comment node marking the insertion point.
+ * @param list       Function returning the current array (reads signals).
+ * @param renderItem Factory `(item, index) => Node` for each element.
+ * @param key        Optional key extractor for future keyed-diffing optimisation.
+ * @returns A dispose function.
+ */
+declare function createFor<T>(anchor: Comment, list: () => T[], renderItem: (item: T, index: number) => Node, key?: (item: T, index: number) => any): () => void;
+/**
+ * Mount a child component at the given anchor position.
+ *
+ * @param Component  The compiled component definition (has `setup`, `render`,
+ *                   and optional `styles`).
+ * @param props      Props object to pass to the component's setup function.
+ * @param children   Optional slot/children map. Each key maps to a function
+ *                   that returns a DOM node for that slot.
+ * @returns The root DOM node of the mounted component.
+ */
+declare function createComponent(Component: ComponentDefinition, props?: Record<string, any>, children?: Record<string, () => Node>): Node;
+
+/**
+ * @matthesketh/utopia-runtime — Microtask-based update scheduler
+ *
+ * Batches DOM update jobs so that multiple signal changes within the same
+ * synchronous tick only trigger a single DOM update pass.
+ */
+/**
+ * Queue a job for the next microtask flush. Duplicate references to the same
+ * function are automatically de-duplicated because we store them in a Set.
+ */
+declare function queueJob(job: () => void): void;
+/**
+ * Returns a promise that resolves after the current pending flush completes.
+ * Useful for tests and any code that needs to wait for DOM updates.
+ */
+declare function nextTick(): Promise<void>;
+
+/**
+ * Hydrate a server-rendered component. Instead of creating new DOM nodes,
+ * the runtime claims the existing nodes in the target element and attaches
+ * event listeners and reactive effects.
+ *
+ * @param component - The compiled component definition
+ * @param target    - A CSS selector string or DOM Element containing the
+ *                    server-rendered HTML
+ */
+declare function hydrate(component: ComponentDefinition, target: string | Element): void;
+
+export { type ComponentDefinition, type ComponentInstance, addEventListener, appendChild, createComment, createComponent, createComponentInstance, createElement, createFor, createIf, createTextNode, hydrate, insertBefore, mount, nextTick, queueJob, removeNode, setAttr, setText };

package/dist/index.js

@@ -0,0 +1,376 @@
+// src/component.ts
+function createComponentInstance(definition, props) {
+  let styleElement = null;
+  const instance = {
+    el: null,
+    props: props ?? {},
+    slots: {},
+    mount(target, anchor) {
+      if (instance.el) {
+        target.insertBefore(instance.el, anchor ?? null);
+        return;
+      }
+      const ctx = definition.setup ? definition.setup(instance.props) : {};
+      const renderCtx = {
+        ...ctx,
+        $slots: instance.slots
+      };
+      instance.el = definition.render(renderCtx);
+      target.insertBefore(instance.el, anchor ?? null);
+      if (definition.styles && !styleElement) {
+        styleElement = document.createElement("style");
+        styleElement.textContent = definition.styles;
+        document.head.appendChild(styleElement);
+      }
+    },
+    unmount() {
+      if (instance.el && instance.el.parentNode) {
+        instance.el.parentNode.removeChild(instance.el);
+      }
+      instance.el = null;
+      if (styleElement && styleElement.parentNode) {
+        styleElement.parentNode.removeChild(styleElement);
+        styleElement = null;
+      }
+    }
+  };
+  return instance;
+}
+function mount(component, target) {
+  const el = typeof target === "string" ? document.querySelector(target) : target;
+  if (!el) {
+    throw new Error(
+      `[utopia] Mount target not found: ${typeof target === "string" ? target : "Element"}`
+    );
+  }
+  const instance = createComponentInstance(component);
+  instance.mount(el);
+  return instance;
+}
+
+// src/hydration.ts
+var isHydrating = false;
+var hydrateNode = null;
+var cursorStack = [];
+function claimNode() {
+  const node = hydrateNode;
+  if (node) {
+    hydrateNode = node.nextSibling;
+  }
+  return node;
+}
+function enterNode(el) {
+  cursorStack.push(hydrateNode);
+  hydrateNode = el.firstChild;
+}
+function exitNode() {
+  hydrateNode = cursorStack.pop() ?? null;
+}
+function hydrate(component, target) {
+  const el = typeof target === "string" ? document.querySelector(target) : target;
+  if (!el) {
+    throw new Error(
+      `[utopia] Hydration target not found: ${typeof target === "string" ? target : "Element"}`
+    );
+  }
+  isHydrating = true;
+  hydrateNode = el.firstChild;
+  try {
+    const instance = createComponentInstance(component);
+    const ctx = component.setup ? component.setup(instance.props) : {};
+    const renderCtx = {
+      ...ctx,
+      $slots: instance.slots
+    };
+    instance.el = component.render(renderCtx);
+    if (component.styles) {
+      const style = document.createElement("style");
+      style.textContent = component.styles;
+      document.head.appendChild(style);
+    }
+  } finally {
+    isHydrating = false;
+    hydrateNode = null;
+    cursorStack.length = 0;
+  }
+}
+
+// src/dom.ts
+function createElement(tag) {
+  if (isHydrating) {
+    const node = claimNode();
+    if (node && node.nodeType === 1) {
+      enterNode(node);
+      return node;
+    }
+    if (typeof process !== "undefined" && process.env?.["NODE_ENV"] !== "production") {
+      console.warn(`[utopia] Hydration mismatch: expected <${tag}>, got`, node);
+    }
+  }
+  return document.createElement(tag);
+}
+function createTextNode(text) {
+  if (isHydrating) {
+    const node = claimNode();
+    if (node && node.nodeType === 3) {
+      return node;
+    }
+    if (typeof process !== "undefined" && process.env?.["NODE_ENV"] !== "production") {
+      console.warn(`[utopia] Hydration mismatch: expected text node, got`, node);
+    }
+  }
+  return document.createTextNode(String(text));
+}
+function setText(node, value) {
+  const text = value == null ? "" : String(value);
+  if (node.data !== text) {
+    node.data = text;
+  }
+}
+function setAttr(el, name, value) {
+  if (name === "class") {
+    if (value == null || value === false) {
+      el.removeAttribute("class");
+    } else if (typeof value === "string") {
+      el.className = value;
+    } else if (typeof value === "object") {
+      const classes = [];
+      for (const key of Object.keys(value)) {
+        if (value[key]) {
+          classes.push(key);
+        }
+      }
+      el.className = classes.join(" ");
+    }
+    return;
+  }
+  if (name === "style") {
+    const htmlEl = el;
+    if (value == null || value === false) {
+      htmlEl.removeAttribute("style");
+    } else if (typeof value === "string") {
+      htmlEl.style.cssText = value;
+    } else if (typeof value === "object") {
+      htmlEl.style.cssText = "";
+      for (const prop of Object.keys(value)) {
+        const val = value[prop];
+        if (val != null) {
+          htmlEl.style.setProperty(
+            prop.replace(/([A-Z])/g, "-$1").toLowerCase(),
+            String(val)
+          );
+        }
+      }
+    }
+    return;
+  }
+  const BOOLEAN_ATTRS = /* @__PURE__ */ new Set([
+    "disabled",
+    "checked",
+    "readonly",
+    "hidden",
+    "selected",
+    "required",
+    "multiple",
+    "autofocus",
+    "autoplay",
+    "controls",
+    "loop",
+    "muted",
+    "open",
+    "novalidate"
+  ]);
+  if (BOOLEAN_ATTRS.has(name)) {
+    if (value) {
+      el.setAttribute(name, "");
+      if (name in el) {
+        el[name] = true;
+      }
+    } else {
+      el.removeAttribute(name);
+      if (name in el) {
+        el[name] = false;
+      }
+    }
+    return;
+  }
+  if (name.startsWith("data-")) {
+    const key = name.slice(5).replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    el.dataset[key] = value == null ? "" : String(value);
+    return;
+  }
+  if (value == null || value === false) {
+    el.removeAttribute(name);
+  } else {
+    el.setAttribute(name, value === true ? "" : String(value));
+  }
+}
+function addEventListener(el, event, handler) {
+  el.addEventListener(event, handler);
+  return () => {
+    el.removeEventListener(event, handler);
+  };
+}
+function insertBefore(parent, node, anchor) {
+  parent.insertBefore(node, anchor);
+}
+function removeNode(node) {
+  if (node.parentNode) {
+    node.parentNode.removeChild(node);
+  }
+}
+function appendChild(parent, child) {
+  if (isHydrating) {
+    if (child.nodeType === 1) {
+      exitNode();
+    }
+    return;
+  }
+  parent.appendChild(child);
+}
+function createComment(text) {
+  if (isHydrating) {
+    const node = claimNode();
+    if (node && node.nodeType === 8) {
+      return node;
+    }
+    if (typeof process !== "undefined" && process.env?.["NODE_ENV"] !== "production") {
+      console.warn(`[utopia] Hydration mismatch: expected comment node, got`, node);
+    }
+  }
+  return document.createComment(text);
+}
+
+// src/directives.ts
+import { effect } from "@matthesketh/utopia-core";
+function clearNodes(nodes) {
+  for (const node of nodes) {
+    removeNode(node);
+  }
+  nodes.length = 0;
+}
+function createIf(anchor, condition, renderTrue, renderFalse) {
+  let currentNodes = [];
+  let lastConditionTruthy;
+  const parent = anchor.parentNode;
+  const dispose = effect(() => {
+    const truthy = !!condition();
+    if (truthy === lastConditionTruthy) {
+      return;
+    }
+    lastConditionTruthy = truthy;
+    clearNodes(currentNodes);
+    if (truthy) {
+      const node = renderTrue();
+      currentNodes.push(node);
+      insertBefore(parent, node, anchor);
+    } else if (renderFalse) {
+      const node = renderFalse();
+      currentNodes.push(node);
+      insertBefore(parent, node, anchor);
+    }
+  });
+  return () => {
+    dispose();
+    clearNodes(currentNodes);
+  };
+}
+function createFor(anchor, list, renderItem, key) {
+  let currentNodes = [];
+  const parent = anchor.parentNode;
+  void key;
+  const dispose = effect(() => {
+    const items = list();
+    clearNodes(currentNodes);
+    for (let i = 0; i < items.length; i++) {
+      const node = renderItem(items[i], i);
+      currentNodes.push(node);
+      insertBefore(parent, node, anchor);
+    }
+  });
+  return () => {
+    dispose();
+    clearNodes(currentNodes);
+  };
+}
+function createComponent(Component, props, children) {
+  const instance = createComponentInstance(Component, props);
+  if (children) {
+    for (const slotName of Object.keys(children)) {
+      instance.slots[slotName] = children[slotName];
+    }
+  }
+  const ctx = Component.setup ? Component.setup(instance.props) : {};
+  const renderCtx = {
+    ...ctx,
+    $slots: instance.slots
+  };
+  instance.el = Component.render(renderCtx);
+  if (Component.styles) {
+    const style = document.createElement("style");
+    style.textContent = Component.styles;
+    document.head.appendChild(style);
+  }
+  return instance.el;
+}
+
+// src/scheduler.ts
+var queue = /* @__PURE__ */ new Set();
+var isFlushing = false;
+var isFlushPending = false;
+var resolvedPromise = Promise.resolve();
+function queueJob(job) {
+  queue.add(job);
+  if (!isFlushPending && !isFlushing) {
+    isFlushPending = true;
+    resolvedPromise.then(flushJobs);
+  }
+}
+function nextTick() {
+  return resolvedPromise.then();
+}
+function flushJobs() {
+  isFlushPending = false;
+  isFlushing = true;
+  try {
+    for (const job of queue) {
+      queue.delete(job);
+      job();
+    }
+  } finally {
+    isFlushing = false;
+    if (queue.size > 0) {
+      isFlushPending = true;
+      resolvedPromise.then(flushJobs);
+    }
+  }
+}
+
+// src/index.ts
+import { signal, computed, effect as effect2, batch, untrack } from "@matthesketh/utopia-core";
+import { effect as effect3 } from "@matthesketh/utopia-core";
+export {
+  addEventListener,
+  appendChild,
+  batch,
+  computed,
+  createComment,
+  createComponent,
+  createComponentInstance,
+  effect3 as createEffect,
+  createElement,
+  createFor,
+  createIf,
+  createTextNode,
+  effect2 as effect,
+  hydrate,
+  insertBefore,
+  mount,
+  nextTick,
+  queueJob,
+  removeNode,
+  setAttr,
+  setText,
+  signal,
+  untrack
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@matthesketh/utopia-runtime",
+  "version": "0.0.1",
+  "description": "DOM renderer and component lifecycle for UtopiaJS",
+  "type": "module",
+  "license": "MIT",
+  "author": "Matt <matt@matthesketh.pro>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wrxck/utopiajs.git",
+    "directory": "packages/runtime"
+  },
+  "homepage": "https://github.com/wrxck/utopiajs/tree/main/packages/runtime",
+  "keywords": [
+    "runtime",
+    "dom",
+    "renderer",
+    "lifecycle",
+    "directives",
+    "utopiajs"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@matthesketh/utopia-core": "0.0.1"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch"
+  }
+}