tempestweb 0.1.0__tar.gz

tempestweb-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+dist/
+build/
+
+# Pyodide / WASM build artifacts
+/site/
+/public/pyodide/
+
+# Node (only if a test runner needs it; the client itself ships no node_modules)
+node_modules/
+
+# Editor / OS
+.vscode/
+.idea/
+.DS_Store
+
+# Worktrees live outside the tree; ignore any stray local ones
+/worktrees/
+
+# Local session permissions (not shared)
+.claude/settings.local.json
+.playwright-mcp/

tempestweb-0.1.0/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to **tempestweb** are documented here. Format follows
+[Keep a Changelog](https://keepachangelog.com/); this project adheres to semantic
+versioning.
+
+## [0.1.0] — 2026-06-11
+
+First public release. Build web apps in typed Python — one declarative tree, a
+pure-JS DOM renderer, two execution modes (WASM in the browser via Pyodide, or a
+FastAPI server over WebSocket/SSE).
+
+### Added
+
+- **Two execution modes, one `view()`.** Mode A (WASM/Pyodide) runs Python in the
+  browser; Mode B (server) runs it on FastAPI over WebSocket + SSE. The app never
+  names a transport.
+- **`tempestweb` CLI** — `new` (scaffold), `dev` (watch + reload), `build`
+  (`--mode wasm|server`), `run`. The wasm build emits a static bundle (Pyodide +
+  the `tempest_core`/`tempestweb` payload + `app.py`); the server build emits a
+  FastAPI host.
+- **Pure-JS client** (no TypeScript, no framework, no build step): DOM patcher,
+  `Style`→CSS, delegated events, the three transports (wasm/ws/sse).
+- **Trilho E parity** (live in Mode A): URL routing (deep links + back/forward +
+  pushState), virtualized lists with a proportional scrollbar, overlays
+  (dialogs/sheets), CSS transitions, pointer gestures (tap/swipe/long-press),
+  real form controls (Input/Checkbox/Image), and a11y (semantics→ARIA) / i18n /
+  theme.
+- **Native capabilities** wired in both modes (geolocation, clipboard, http,
+  share, camera, audio, storage, notifications) — in-process FFI in Mode A,
+  proxied over the transport in Mode B.
+- **PWA layer**: installable manifest + icons + a service worker with an injected
+  app-shell precache (offline second load).
+- **Observability**: telemetry, logger, error boundary, feature flags, auth —
+  adapter pattern.
+- **`tempestweb.components`**: ready-to-use validated fields (EmailField,
+  PasswordField, PhoneField, CPFField, CNPJField, AddressField, TextField) and
+  forms (LoginForm, SignupForm).
+- **Bilingual docs** (PT-BR + EN) built with MkDocs Material.
+
+### Depends on
+
+- [`tempest-core`](https://pypi.org/project/tempest-core/) `>=0.1.0` — the
+  renderer-agnostic UI engine (IR/reconciler/state/style/widgets).
+
+### Known follow-ups
+
+- Mode B `view→URL` (pushState) needs a server→client nav envelope (Mode A is
+  bidirectional today).
+- WebPush tab-closed delivery and real camera/geo need on-device verification.

tempestweb-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: tempestweb
+Version: 0.1.0
+Summary: Build web apps in typed Python — one tree, a DOM renderer, two execution modes (WASM + server).
+Author-email: Mauricio Benjamin <mauricio.benjamin@reloverelations.com>
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: tempest-core>=0.1.0
+Provides-Extra: cli
+Requires-Dist: watchfiles>=0.21; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs-static-i18n>=1.2; extra == 'docs'
+Provides-Extra: server
+Requires-Dist: fastapi>=0.110; extra == 'server'
+Requires-Dist: uvicorn[standard]>=0.29; extra == 'server'
+Requires-Dist: websockets>=12; extra == 'server'
+Provides-Extra: webpush
+Requires-Dist: pywebpush>=1.14; extra == 'webpush'
+Description-Content-Type: text/markdown
+
+# tempestweb
+
+📚 **Documentation:** [Português (Brasil)](https://mauriciobenjamin700.github.io/tempestweb/)
+· [English (US)](https://mauriciobenjamin700.github.io/tempestweb/en/) — bilingual
+docs site (PT-BR default + EN-US), deployed to GitHub Pages.
+
+> Build web apps in **typed Python**. One declarative widget tree, a **DOM**
+> renderer, and **two execution modes** that share 100% of the application code:
+> **Mode A (WASM)** runs your Python in the browser via Pyodide; **Mode B
+> (server)** runs it on the server (FastAPI) and talks to a thin JS client over
+> **WebSocket or SSE**. Installable **PWA**, **offline-first** (service worker +
+> IndexedDB), and **WebPush** are first-class — parity with `tempest-react-sdk`.
+
+Sister project to [tempestroid](../tempestroid) — same "one tree, multiple
+renderers" architecture. The renderer-agnostic engine (IR, reconciler, state,
+style, widgets) is shared; tempestweb adds a **DOM** leaf renderer (pure
+JavaScript, no framework, no build step, no TypeScript) and two patch transports.
+
+## Status
+
+🚧 Early construction. See the design docs:
+
+- [`docs/plan.md`](docs/plan.md) — full design and phase plan.
+- [`docs/roadmap.md`](docs/roadmap.md) — phase checklist.
+- [`docs/arquitetura.md`](docs/arquitetura.md) — architecture.
+- [`docs/contract.md`](docs/contract.md) — the Python↔client wire format.
+- [`docs/agents/MANIFEST.md`](docs/agents/MANIFEST.md) — parallel agent task plan.
+
+Want runnable apps? Browse the **[Example Gallery](https://mauriciobenjamin700.github.io/tempestweb/en/examples/)**
+([PT-BR](https://mauriciobenjamin700.github.io/tempestweb/examples/)) — 35 single-concept
+demos (stopwatch, forms, data table, kanban, chat, theming, i18n, canvas, native
+capabilities, observability, PWA/WebPush, and a server-mode walkthrough), each
+running unchanged in both modes.
+
+## How it works
+
+```text
+   view(app) ──build──▶ Node tree (IR)        ← shared core (vendored from tempestroid)
+                            │
+                          diff
+                            ▼
+                        [ Patch ]              insert / remove / update / reorder / replace
+                       ╱          ╲
+              Mode A transport   Mode B transport
+              (pyodide.ffi)       (WebSocket | SSE)
+                       ╲          ╱
+                  client/ (pure JS): apply patches to the DOM
+                  + Style→CSS + event capture                  ← same code in both modes
+```
+
+The application's `view()` never names a transport — the same `examples/counter/app.py`
+runs under `--mode wasm` and `--mode server` unchanged. Capabilities (`native/`:
+http, audio, share, geolocation, clipboard, storage, camera) are typed awaitables
+with the same Python API in both modes — Mode A calls the Web API in-process, Mode
+B proxies it over a round-trip (see [`docs/contract.md`](docs/contract.md)).
+
+## Develop
+
+```bash
+uv venv && uv pip install -e ".[dev,server,cli]"
+make check          # ruff + mypy + pytest + JS (jsdom) tests
+```
+
+## Layout
+
+| Path | What |
+|---|---|
+| `tempest-core` (dependency) | Renderer-agnostic engine — IR/reconciler/state/style/widgets (`import tempest_core`), extracted from tempestroid. |
+| `tempestweb/components/` | Ready-to-use fields + forms (EmailField, PasswordField, PhoneField, LoginForm, …). |
+| `tempestweb/transports/` | The one seam between modes (`base.py` Protocol, `wasm.py`, `websocket.py`, `sse.py`). |
+| `tempestweb/server/` | FastAPI + WebSocket/SSE host (Mode B). |
+| `tempestweb/native/` | Web API capability adapters — http, audio, share, geo, clipboard, storage, camera (Track N). |
+| `tempestweb/observability/` | Telemetry, logger, error boundary, feature flags, auth — adapter pattern (Track O). |
+| `tempestweb/pwa/` | Web App Manifest + icon emitter (Track P). |
+| `tempestweb/cli/` | `tempestweb new/dev/build/run`. |
+| `client/` | Pure-JS DOM renderer, Style→CSS, event capture; `pwa/` `sw/` `offline/` `push/` `native/` subdirs. |
+| `tests/fixtures/` | Golden wire-format fixtures derived from the core. |
+
+## Conventions
+
+Python: double quotes, full typing (mypy `--strict`), Google docstrings in English,
+async-first. Client: **plain JavaScript only** — no TypeScript, no framework, no
+build step. See [`CLAUDE.md`](CLAUDE.md).

tempestweb-0.1.0/README.md

@@ -0,0 +1,83 @@
+# tempestweb
+
+📚 **Documentation:** [Português (Brasil)](https://mauriciobenjamin700.github.io/tempestweb/)
+· [English (US)](https://mauriciobenjamin700.github.io/tempestweb/en/) — bilingual
+docs site (PT-BR default + EN-US), deployed to GitHub Pages.
+
+> Build web apps in **typed Python**. One declarative widget tree, a **DOM**
+> renderer, and **two execution modes** that share 100% of the application code:
+> **Mode A (WASM)** runs your Python in the browser via Pyodide; **Mode B
+> (server)** runs it on the server (FastAPI) and talks to a thin JS client over
+> **WebSocket or SSE**. Installable **PWA**, **offline-first** (service worker +
+> IndexedDB), and **WebPush** are first-class — parity with `tempest-react-sdk`.
+
+Sister project to [tempestroid](../tempestroid) — same "one tree, multiple
+renderers" architecture. The renderer-agnostic engine (IR, reconciler, state,
+style, widgets) is shared; tempestweb adds a **DOM** leaf renderer (pure
+JavaScript, no framework, no build step, no TypeScript) and two patch transports.
+
+## Status
+
+🚧 Early construction. See the design docs:
+
+- [`docs/plan.md`](docs/plan.md) — full design and phase plan.
+- [`docs/roadmap.md`](docs/roadmap.md) — phase checklist.
+- [`docs/arquitetura.md`](docs/arquitetura.md) — architecture.
+- [`docs/contract.md`](docs/contract.md) — the Python↔client wire format.
+- [`docs/agents/MANIFEST.md`](docs/agents/MANIFEST.md) — parallel agent task plan.
+
+Want runnable apps? Browse the **[Example Gallery](https://mauriciobenjamin700.github.io/tempestweb/en/examples/)**
+([PT-BR](https://mauriciobenjamin700.github.io/tempestweb/examples/)) — 35 single-concept
+demos (stopwatch, forms, data table, kanban, chat, theming, i18n, canvas, native
+capabilities, observability, PWA/WebPush, and a server-mode walkthrough), each
+running unchanged in both modes.
+
+## How it works
+
+```text
+   view(app) ──build──▶ Node tree (IR)        ← shared core (vendored from tempestroid)
+                            │
+                          diff
+                            ▼
+                        [ Patch ]              insert / remove / update / reorder / replace
+                       ╱          ╲
+              Mode A transport   Mode B transport
+              (pyodide.ffi)       (WebSocket | SSE)
+                       ╲          ╱
+                  client/ (pure JS): apply patches to the DOM
+                  + Style→CSS + event capture                  ← same code in both modes
+```
+
+The application's `view()` never names a transport — the same `examples/counter/app.py`
+runs under `--mode wasm` and `--mode server` unchanged. Capabilities (`native/`:
+http, audio, share, geolocation, clipboard, storage, camera) are typed awaitables
+with the same Python API in both modes — Mode A calls the Web API in-process, Mode
+B proxies it over a round-trip (see [`docs/contract.md`](docs/contract.md)).
+
+## Develop
+
+```bash
+uv venv && uv pip install -e ".[dev,server,cli]"
+make check          # ruff + mypy + pytest + JS (jsdom) tests
+```
+
+## Layout
+
+| Path | What |
+|---|---|
+| `tempest-core` (dependency) | Renderer-agnostic engine — IR/reconciler/state/style/widgets (`import tempest_core`), extracted from tempestroid. |
+| `tempestweb/components/` | Ready-to-use fields + forms (EmailField, PasswordField, PhoneField, LoginForm, …). |
+| `tempestweb/transports/` | The one seam between modes (`base.py` Protocol, `wasm.py`, `websocket.py`, `sse.py`). |
+| `tempestweb/server/` | FastAPI + WebSocket/SSE host (Mode B). |
+| `tempestweb/native/` | Web API capability adapters — http, audio, share, geo, clipboard, storage, camera (Track N). |
+| `tempestweb/observability/` | Telemetry, logger, error boundary, feature flags, auth — adapter pattern (Track O). |
+| `tempestweb/pwa/` | Web App Manifest + icon emitter (Track P). |
+| `tempestweb/cli/` | `tempestweb new/dev/build/run`. |
+| `client/` | Pure-JS DOM renderer, Style→CSS, event capture; `pwa/` `sw/` `offline/` `push/` `native/` subdirs. |
+| `tests/fixtures/` | Golden wire-format fixtures derived from the core. |
+
+## Conventions
+
+Python: double quotes, full typing (mypy `--strict`), Google docstrings in English,
+async-first. Client: **plain JavaScript only** — no TypeScript, no framework, no
+build step. See [`CLAUDE.md`](CLAUDE.md).

tempestweb-0.1.0/client/constants.js

@@ -0,0 +1,17 @@
+// constants.js — shared client-side constants (tunables used across modules).
+//
+// Module-private values stay in their module; this file holds the few constants
+// that are shared or are worth naming/tuning in one place: gesture-recognition
+// thresholds and the virtualization stylesheet id.
+
+/** Minimum pointer travel (px) for a drag to count as a swipe. */
+export const SWIPE_MIN_PX = 30;
+
+/** Hold time (ms, with little travel) for a press to count as a long press. */
+export const LONG_PRESS_MS = 500;
+
+/** Widget type tag that opts into gesture events (tap/swipe/long_press). */
+export const GESTURE_TYPE = "GestureDetector";
+
+/** Id of the injected stylesheet that carries virtualized-list spacer heights. */
+export const VIRT_STYLE_ID = "tw-virt-styles";

tempestweb-0.1.0/client/dom.js

@@ -0,0 +1,373 @@
+// dom.js — build a DOM tree from the Node IR and apply patch batches to it. W1.
+//
+// buildElement(node) turns one serialized Node into a live DOM element (recursing
+// into children); applyPatches(root, patches) mutates a tree in place. Given the
+// DOM built from node_initial.json, applying patches_all_kinds.json yields the
+// expected DOM. Patch kinds are distinguished by key presence (see transport.js):
+//   - set_props present       -> Update
+//   - node + index present     -> Insert
+//   - index only               -> Remove
+//   - order present            -> Reorder
+//   - node without index       -> Replace
+//
+// Every element carries `data-tw-key` when its Node has a key, so events.js can
+// read the originating widget key via event delegation. Verify against
+// ../tests/fixtures/ in tests/client/ (jsdom). No framework.
+
+import { styleToCss } from "./style.js";
+
+/** Attribute holding a widget's stable reconciliation key. */
+export const KEY_ATTR = "data-tw-key";
+/** Attribute holding a widget's IR type (so patches can re-key/inspect it). */
+export const TYPE_ATTR = "data-tw-type";
+
+// Each widget type maps to one HTML tag. Container-like widgets are <div>; Text is
+// an inline <span>; Button is a real <button>. Unknown types fall back to <div> so
+// a new core widget renders (as a generic box) rather than throwing.
+const TAG_BY_TYPE = Object.freeze({
+  Column: "div",
+  Row: "div",
+  Container: "div",
+  Stack: "div",
+  Text: "span",
+  Button: "button",
+  Input: "input",
+  Checkbox: "input",
+  Image: "img",
+});
+
+/**
+ * Resolve the HTML tag name for an IR widget type.
+ * @param {string} type  The widget type ("Column", "Text", "Button", ...).
+ * @returns {string}     The HTML tag name (defaults to "div").
+ */
+function tagForType(type) {
+  return TAG_BY_TYPE[type] ?? "div";
+}
+
+/**
+ * Apply a node's props to an element: style, key/type attributes and text.
+ *
+ * `content` (Text) and `label` (Button) become the element's text. The `style`
+ * prop is translated by {@link styleToCss} into the inline `style` attribute. The
+ * widget `key` and `type` are mirrored onto data attributes for event delegation.
+ *
+ * @param {HTMLElement} el      The target element.
+ * @param {string} type         The widget type.
+ * @param {?string} key         The widget key, or null.
+ * @param {Object} props        The widget props (may include `style`).
+ * @returns {void}
+ */
+function applyNodeShape(el, type, key, props) {
+  el.setAttribute(TYPE_ATTR, type);
+  if (key != null) {
+    el.setAttribute(KEY_ATTR, key);
+  } else {
+    el.removeAttribute(KEY_ATTR);
+  }
+  applyProps(el, props ?? {});
+}
+
+/**
+ * Apply a bag of props onto an element (style + text-bearing props).
+ *
+ * Used both when first building an element and by Update patches. `style` is
+ * (re)translated to CSS; `content`/`label` set the text. Other keys are widget
+ * metadata the DOM does not render and are ignored.
+ *
+ * @param {HTMLElement} el     The target element.
+ * @param {Object} props       The props to apply.
+ * @returns {void}
+ */
+function applyProps(el, props) {
+  if ("style" in props) {
+    const css = styleToCss(props.style);
+    if (css) {
+      el.style.cssText = css;
+    } else {
+      el.removeAttribute("style");
+    }
+  }
+  const type = el.getAttribute(TYPE_ATTR);
+  // Text-bearing props. A Checkbox is an <input> and cannot hold text, so its
+  // label rides as an accessible name instead of textContent.
+  if ("content" in props) {
+    el.textContent = props.content == null ? "" : String(props.content);
+  }
+  if ("label" in props) {
+    if (type === "Checkbox") {
+      el.setAttribute("aria-label", props.label == null ? "" : String(props.label));
+    } else {
+      el.textContent = props.label == null ? "" : String(props.label);
+    }
+  }
+  applyControlProps(el, type, props);
+  applyA11yProps(el, props);
+  applyLazyProps(el, type, props);
+}
+
+/**
+ * Apply accessibility props (semantics + focus) onto an element.
+ *
+ * Maps the core's renderer-agnostic a11y model to ARIA/DOM: ``semantics.label``
+ * → ``aria-label``, ``semantics.role`` → ``role``, ``semantics.hint`` →
+ * ``aria-description``; ``focus_order`` sets an explicit ``tabindex`` and
+ * ``focusable`` toggles a default one (``0`` to include, ``-1`` to exclude).
+ *
+ * @param {HTMLElement} el     The target element.
+ * @param {Object} props       The props to apply.
+ * @returns {void}
+ */
+function applyA11yProps(el, props) {
+  const sem = props.semantics;
+  if (sem != null && typeof sem === "object") {
+    if (sem.label != null) {
+      el.setAttribute("aria-label", String(sem.label));
+    }
+    if (sem.role != null) {
+      el.setAttribute("role", String(sem.role));
+    }
+    if (sem.hint != null) {
+      el.setAttribute("aria-description", String(sem.hint));
+    }
+  }
+  if (props.focus_order != null) {
+    el.setAttribute("tabindex", String(props.focus_order));
+  } else if (props.focusable === true) {
+    el.setAttribute("tabindex", "0");
+  } else if (props.focusable === false) {
+    el.setAttribute("tabindex", "-1");
+  }
+}
+
+/**
+ * Apply form-control / media props (Input, Checkbox, Image) onto an element.
+ *
+ * Maps the widget's typed props onto the right DOM property/attribute so the
+ * control is actually interactive (a real <input> holding `value`, a checkbox
+ * reflecting `checked`, an <img> pointing at `src`). No-ops for other types.
+ *
+ * @param {HTMLElement} el     The target element.
+ * @param {?string} type       The widget type (from the data-tw-type attribute).
+ * @param {Object} props       The props to apply.
+ * @returns {void}
+ */
+// Virtualized list widgets: rendered as scroll viewports whose visible window
+// the runtime slides in response to scroll events (see client/virtualize.js).
+const LAZY_TYPES = Object.freeze(["LazyColumn", "LazyRow", "LazyGrid"]);
+
+/**
+ * Mark a virtualized list element and mirror its windowing metadata to data
+ * attributes so the scroll controller can compute the visible window.
+ *
+ * @param {HTMLElement} el     The target element.
+ * @param {?string} type       The widget type.
+ * @param {Object} props       The props to apply.
+ * @returns {void}
+ */
+function applyLazyProps(el, type, props) {
+  if (type == null || !LAZY_TYPES.includes(type)) {
+    return;
+  }
+  const horizontal = type === "LazyRow";
+  // A bounded, scrollable viewport: the app's Style sets the extent (e.g.
+  // height); overflow scrolls the materialized window, and scrolling past the
+  // edge slides the window (see client/virtualize.js). min-height:0 stops a flex
+  // parent from growing the viewport to fit its content instead of scrolling.
+  el.style.overflowY = horizontal ? "hidden" : "auto";
+  el.style.overflowX = horizontal ? "auto" : "hidden";
+  el.style.minHeight = "0";
+  if ("item_count" in props && props.item_count != null) {
+    el.setAttribute("data-tw-item-count", String(props.item_count));
+  }
+  if ("window_size" in props && props.window_size != null) {
+    el.setAttribute("data-tw-window-size", String(props.window_size));
+  }
+  // window is [start, end) when slid, or null (start at 0).
+  const start = Array.isArray(props.window) ? props.window[0] : 0;
+  el.setAttribute("data-tw-window-start", String(start ?? 0));
+}
+
+function applyControlProps(el, type, props) {
+  if (type === "Input") {
+    el.setAttribute("type", props.secure ? "password" : "text");
+    if ("value" in props) {
+      el.value = props.value == null ? "" : String(props.value);
+    }
+    if ("placeholder" in props && props.placeholder != null) {
+      el.setAttribute("placeholder", String(props.placeholder));
+    }
+    if (props.max_length != null) {
+      el.setAttribute("maxlength", String(props.max_length));
+    }
+  } else if (type === "Checkbox") {
+    el.setAttribute("type", "checkbox");
+    if ("checked" in props) {
+      el.checked = Boolean(props.checked);
+    }
+  } else if (type === "Image") {
+    if ("src" in props && props.src != null) {
+      el.setAttribute("src", String(props.src));
+    }
+    if ("alt" in props && props.alt != null) {
+      el.setAttribute("alt", String(props.alt));
+    }
+  }
+}
+
+/**
+ * Build a DOM element from an IR node (recursing into its children).
+ * @param {import("./transport.js").Node} node  The serialized node.
+ * @returns {HTMLElement}                        The constructed element subtree.
+ */
+export function buildElement(node) {
+  const el = document.createElement(tagForType(node.type));
+  applyNodeShape(el, node.type, node.key ?? null, node.props ?? {});
+  for (const child of node.children ?? []) {
+    el.appendChild(buildElement(child));
+  }
+  return el;
+}
+
+/**
+ * Walk a path of child indices from `root` down to the target element.
+ * @param {HTMLElement} root      The root element.
+ * @param {number[]} path         Child indices from the root ([] = root).
+ * @returns {HTMLElement}         The element at `path`.
+ * @throws {RangeError}           If an index does not resolve to an element.
+ */
+function resolvePath(root, path) {
+  /** @type {HTMLElement} */
+  let el = root;
+  for (const index of path) {
+    const next = el.children[index];
+    if (next == null) {
+      throw new RangeError(`tempestweb: patch path out of range at index ${index}`);
+    }
+    el = /** @type {HTMLElement} */ (next);
+  }
+  return el;
+}
+
+/**
+ * Apply a single Update patch: set/unset props on the node at `path`.
+ * @param {HTMLElement} root  The root element.
+ * @param {{path:number[], set_props?:Object, unset_props?:string[]}} patch  The patch.
+ * @returns {void}
+ */
+function applyUpdate(root, patch) {
+  const el = resolvePath(root, patch.path);
+  if (patch.set_props) {
+    applyProps(el, patch.set_props);
+  }
+  for (const key of patch.unset_props ?? []) {
+    if (key === "style") {
+      el.removeAttribute("style");
+    } else if (key === "content" || key === "label") {
+      el.textContent = "";
+    }
+  }
+}
+
+/**
+ * Apply a single Insert patch: insert a new child at `index` under `path`.
+ * @param {HTMLElement} root  The root element.
+ * @param {{path:number[], index:number, node:import("./transport.js").Node}} patch
+ * @returns {void}
+ */
+function applyInsert(root, patch) {
+  const parent = resolvePath(root, patch.path);
+  const child = buildElement(patch.node);
+  const ref = parent.children[patch.index] ?? null;
+  parent.insertBefore(child, ref);
+}
+
+/**
+ * Apply a single Remove patch: remove the child at `index` under `path`.
+ * @param {HTMLElement} root  The root element.
+ * @param {{path:number[], index:number}} patch  The patch.
+ * @returns {void}
+ */
+function applyRemove(root, patch) {
+  const parent = resolvePath(root, patch.path);
+  const child = parent.children[patch.index];
+  if (child != null) {
+    parent.removeChild(child);
+  }
+}
+
+/**
+ * Apply a single Reorder patch: new child `i` = old child `order[i]`.
+ *
+ * Snapshots the current children first so indices in `order` refer to the
+ * pre-reorder positions, then re-appends them in the requested order.
+ *
+ * @param {HTMLElement} root  The root element.
+ * @param {{path:number[], order:number[]}} patch  The patch.
+ * @returns {void}
+ */
+function applyReorder(root, patch) {
+  const parent = resolvePath(root, patch.path);
+  const before = Array.from(parent.children);
+  for (const index of patch.order) {
+    const child = before[index];
+    if (child != null) {
+      parent.appendChild(child);
+    }
+  }
+}
+
+/**
+ * Apply a single Replace patch: swap the element at `path` for a fresh subtree.
+ * @param {HTMLElement} root  The root element.
+ * @param {{path:number[], node:import("./transport.js").Node}} patch  The patch.
+ * @returns {void}
+ */
+function applyReplace(root, patch) {
+  const old = resolvePath(root, patch.path);
+  const fresh = buildElement(patch.node);
+  if (old.parentNode) {
+    old.parentNode.replaceChild(fresh, old);
+  }
+}
+
+/**
+ * Classify a patch by key presence and dispatch it to the right applier.
+ * @param {HTMLElement} root                   The root element.
+ * @param {import("./transport.js").Patch} patch  The patch to apply.
+ * @returns {void}
+ * @throws {TypeError}                          If the patch shape is unrecognized.
+ */
+function applyPatch(root, patch) {
+  if ("set_props" in patch || "unset_props" in patch) {
+    applyUpdate(root, /** @type {any} */ (patch));
+  } else if ("order" in patch) {
+    applyReorder(root, /** @type {any} */ (patch));
+  } else if ("node" in patch && "index" in patch) {
+    applyInsert(root, /** @type {any} */ (patch));
+  } else if ("node" in patch) {
+    applyReplace(root, /** @type {any} */ (patch));
+  } else if ("index" in patch) {
+    applyRemove(root, /** @type {any} */ (patch));
+  } else {
+    throw new TypeError(`tempestweb: unrecognized patch shape ${JSON.stringify(patch)}`);
+  }
+}
+
+/**
+ * Apply a coalesced batch of patches to the DOM tree rooted at `root`.
+ *
+ * The reconciler coalesces a tick's mutations into one ordered list; the whole
+ * list is applied before the next frame. Patches are applied in array order — the
+ * order the core emitted them — so index-relative ops (insert/remove/reorder)
+ * stay consistent.
+ *
+ * @param {HTMLElement} root                       The mounted root element.
+ * @param {import("./transport.js").Patch[]} patches  The tick's patch batch.
+ * @returns {void}
+ */
+export function applyPatches(root, patches) {
+  for (const patch of patches) {
+    applyPatch(root, patch);
+  }
+}