@opentf/web 0.4.0 → 0.6.0

package/README.md

@@ -1,40 +1,42 @@
 # @opentf/web
 
-The core engine of the **Web App Framework**, a lightweight, high-performance SPA framework designed for the modern web.
+The native-first **OTF Web** runtime — signal-based reactivity and zero-VDOM DOM
+operations, paired with the IR-based compiler ([`@opentf/web-compiler`](https://github.com/Open-Tech-Foundation/Web-App-Framework/tree/main/packages/web-compiler)).
 
-## Features
-
-- 🚀 **Zero-VDOM**: Compiles JSX directly to imperative DOM operations for maximum speed.
-- ⚡ **Signal-Based Reactivity**: Powered by `@preact/signals-core` for fine-grained, surgical updates.
-- 📦 **Web Component Native**: Every component is a standard Custom Element, ensuring perfect encapsulation and interoperability.
-- 🛠️ **Convention-over-Configuration**: File-based routing and automatic component registration.
-- 📏 **Ultra-Lightweight**: Minimal runtime footprint.
+You normally don't call this API by hand. You write `.jsx` components; the compiler
+lowers them to plain DOM code that imports its helpers (`signal`, `computed`,
+`bindText`, `bindList`, …) from this package. Components compile to self-registering
+`web-*` Custom Elements.
 
 ## Installation
 
 ```bash
-npm install @opentf/web
-```
-
-## Basic Usage
-
-```jsx
-export default function Counter() {
-  let count = $state(0);
-
-  return (
-    <div className="counter">
-      <button onclick={() => count--}>-</button>
-      <span>{count}</span>
-      <button onclick={() => count++}>+</button>
-    </div>
-  );
-}
+bun add @opentf/web
 ```
 
-## Documentation
-
-Visit [web.opentf.workers.dev](https://web.opentf.workers.dev) for full documentation and guides.
+Scaffold a ready-to-run app with [`@opentf/create-web`](https://github.com/Open-Tech-Foundation/Web-App-Framework/tree/main/packages/create-web)
+and drive it with [`@opentf/web-cli`](https://github.com/Open-Tech-Foundation/Web-App-Framework/tree/main/packages/web-cli).
+
+## What's inside
+
+- **Reactivity** — a from-scratch `signal` / `computed` / `effect` core.
+- **DOM runtime** — fine-grained bindings (`bindText`, `bindAttr`, `bindList`,
+  `bindChild`, `setProp`, `spread`, `clsx`) the compiler targets, plus `Context`,
+  `Portal`, `ErrorBoundary`, and event dispatch (`emit`).
+- **Compiler macros** — authored in your components, resolved at compile time:
+  `$state`, `$derived`, `$ref`, `$context`, `$effect`, `$expose`, and the
+  `onMount` / `onCleanup` lifecycle hooks.
+- **`<Link>`** — client-side navigation, shipped as JSX source and compiled by your
+  app's pipeline.
+
+## Entry points
+
+| Import | Contents |
+| --- | --- |
+| `@opentf/web` | runtime + reactivity + `Link` (what compiled components import) |
+| `@opentf/web/signals` | the reactivity core on its own |
+| `@opentf/web/runtime` | DOM helpers, Context, Portal, ErrorBoundary |
+| `@opentf/web/server` | string-composed render helpers for SSG |
 
 ## License
 

package/components/Link.jsx

@@ -0,0 +1,43 @@
+// <Link href> — client-side (SPA) navigation.
+//
+// A *pure JSX component*, shipped as source and compiled by the consuming app's
+// pipeline (like a UI library ships components for the user's bundler). The
+// framework dogfoods its own JSX → Custom Element model here instead of a
+// hand-written HTMLElement class — so it gets reactive props, the children slot,
+// and a matching SSG renderer for free, with no separate runtime build step.
+//
+// `class` is a declared prop, so it lands on the rendered <a> (the link), not on
+// the <web-link> host — no duplicated styling.
+
+import { localizePath, navigate, shouldInterceptNav } from "../runtime/router.js";
+
+export default function Link({ href, class: className, reload, children }) {
+  // Keep the link in the active locale (no-op when i18n is off). Locale is a
+  // per-load constant under URL-prefix routing, so resolving it once here is
+  // correct — a navigation that changes the locale rebuilds this component.
+  const target = localizePath(href);
+  // `reload` (a bare attribute → "") forces a full-page navigation for this link.
+  // Absent resolves to null (getAttribute), so use loose `!= null` to treat only a
+  // present, non-false value as opting out.
+  const forceReload = reload != null && reload !== false;
+
+  const onclick = (e) => {
+    // Let the browser handle modified clicks (new tab, etc.) and non-primary buttons.
+    if (e.defaultPrevented || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || e.button !== 0) {
+      return;
+    }
+    // Full-page navigation when this link opts out (`reload`) or the app runs in MPA
+    // mode (docs/HYDRATION.md §7) — leave the click to the browser.
+    if (forceReload || !shouldInterceptNav()) {
+      return;
+    }
+    e.preventDefault();
+    navigate(target);
+  };
+
+  return (
+    <a href={target} class={className} onclick={onclick}>
+      {children}
+    </a>
+  );
+}

package/core/errors.js

@@ -0,0 +1,48 @@
+//! Central error reporting for the OTF Web runtime.
+//
+// Render, effect, lifecycle, and event errors are funneled here instead of being
+// thrown into the void. Userland (and the dev overlay) subscribe via `onError`;
+// in the browser every report is also dispatched as an `otfw:error` window event
+// so a fully decoupled listener (e.g. the dev server's injected overlay) can show
+// it without importing the bundle.
+
+const handlers = new Set();
+const isBrowser = typeof window !== "undefined";
+
+/**
+ * Subscribe to runtime errors. `handler(error, context)` is called for every
+ * `reportError`. Returns a disposer that unsubscribes.
+ */
+export function onError(handler) {
+  handlers.add(handler);
+  return () => handlers.delete(handler);
+}
+
+/**
+ * Report a caught error. `context` carries where it happened
+ * (`{ phase: "render" | "effect" | "mount" | "event" | "route", … }`).
+ * Notifies subscribers, emits the `otfw:error` window event, and — if nobody is
+ * listening — logs to the console so errors are never silently swallowed.
+ */
+export function reportError(error, context = {}) {
+  for (const handler of handlers) {
+    try {
+      handler(error, context);
+    } catch {
+      // A failing handler must not mask the original error.
+    }
+  }
+  if (isBrowser) {
+    window.dispatchEvent(new CustomEvent("otfw:error", { detail: { error, context } }));
+  }
+  if (handlers.size === 0) {
+    console.error(`[otfw${context.phase ? `:${context.phase}` : ""}]`, error);
+  }
+}
+
+/** Signal that the error condition has cleared (e.g. a successful navigation). */
+export function clearError(context = {}) {
+  if (isBrowser) {
+    window.dispatchEvent(new CustomEvent("otfw:error-clear", { detail: context }));
+  }
+}

package/core/reactive.js

@@ -0,0 +1,190 @@
+//! Deep reactive store — a fine-grained, signal-backed reactive object.
+//
+// `reactive(obj)` returns a deep proxy over plain data. Reading a property
+// inside an effect/computed subscribes to *just that path*; writing a property
+// notifies *only* the effects that read it. Object/array nodes are wrapped
+// lazily on access, so a 100-field store costs nothing until a field is touched.
+//
+// This is the public primitive SPEC §1.1 requires to live in `@opentf/web`:
+// apps `import { reactive }` and read values directly (no provider object), and
+// `@opentf/web-form` builds its values/errors trees on top of it instead of a
+// private proxy. It is forward-compatible with the `$signal()` compiler bridge
+// (SPEC §3.5): each node is itself reactive, so a future First-Access unwrap can
+// read `store.user.value` without changing this runtime.
+//
+// Model (mirrors the signals core, one level up):
+//   - per *key* signal  → fine-grained leaf subscription (read `a.b.c`)
+//   - per *node* "struct" signal → bumped on key add/remove so `in`, `ownKeys`,
+//     iteration and array `length` stay reactive.
+// State is mutated in place (the store owns it); reads always go through the
+// proxy, so callers never observe the raw object directly. No per-write tree
+// clone, no broadcast — the two costs the old form proxy paid on every keystroke.
+
+import { signal, untracked, batch } from "./signals.js";
+
+/** Unwrap a reactive proxy back to its underlying plain object. */
+const RAW = Symbol.for("otfw.reactive.raw");
+/** Brand a proxy so `isReactive` is a cheap, collision-free check. */
+const IS_REACTIVE = Symbol.for("otfw.reactive.is");
+
+// Per raw-object bookkeeping, kept off the data itself so the data stays clean.
+const proxyCache = new WeakMap(); // raw object  → its proxy (stable identity)
+const keySignals = new WeakMap(); // raw object  → Map<key, signal(value)>
+const structSignals = new WeakMap(); // raw object → signal(int) bumped on shape change
+
+// Array methods that mutate in place; routed through a `batch` so the many
+// internal index/length writes collapse into a single notification.
+const ARRAY_MUTATORS = new Set([
+  "push", "pop", "shift", "unshift", "splice", "reverse", "sort", "fill", "copyWithin",
+]);
+
+/** Only plain objects and arrays are wrapped; class instances, Dates, etc. pass through. */
+function isWrappable(v) {
+  if (v === null || typeof v !== "object") return false;
+  if (Array.isArray(v)) return true;
+  const proto = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+}
+
+function getKeySig(target, key) {
+  let map = keySignals.get(target);
+  if (!map) keySignals.set(target, (map = new Map()));
+  let sig = map.get(key);
+  if (!sig) map.set(key, (sig = signal(target[key])));
+  return sig;
+}
+
+function getStructSig(target) {
+  let sig = structSignals.get(target);
+  if (!sig) structSignals.set(target, (sig = signal(0)));
+  return sig;
+}
+
+/** Strip a reactive wrapper from a value before it is stored. */
+function toRaw(v) {
+  return v && typeof v === "object" && v[RAW] !== undefined ? v[RAW] : v;
+}
+
+const handler = {
+  get(target, key, receiver) {
+    if (key === RAW) return target;
+    if (key === IS_REACTIVE) return true;
+
+    if (typeof key === "symbol") {
+      // Spreading/iterating walks length+indices through the proxy, but the
+      // iterator lookup itself should subscribe to shape so a re-spread re-runs.
+      if (key === Symbol.iterator) getStructSig(target).value;
+      return Reflect.get(target, key, receiver);
+    }
+
+    // `length` is structural for arrays — push/splice change it.
+    if (key === "length" && Array.isArray(target)) {
+      getStructSig(target).value;
+      return target.length;
+    }
+
+    const value = target[key];
+
+    if (typeof value === "function") {
+      if (Array.isArray(target)) {
+        // Mutators re-enter the `set` trap via `receiver`; batch their internal
+        // writes so an effect re-runs once.
+        if (ARRAY_MUTATORS.has(key)) {
+          return (...args) => batch(() => value.apply(receiver, args));
+        }
+        // Read methods (map/filter/forEach/…) subscribe to *structure* only and
+        // run over the raw array, so they re-run when the list grows/shrinks but
+        // not when an individual element's value changes. This is what keeps a
+        // `list.map(i => <input/>)` from re-rendering (and dropping focus) on
+        // every keystroke — the element's own binding handles its value.
+        getStructSig(target).value;
+        return value.bind(target);
+      }
+      return value.bind(receiver);
+    }
+
+    getKeySig(target, key).value; // subscribe to this leaf/branch
+    return isWrappable(value) ? wrap(value) : value;
+  },
+
+  set(target, key, value) {
+    const raw = toRaw(value);
+
+    if (key === "length" && Array.isArray(target)) {
+      if (target.length !== raw) {
+        target.length = raw;
+        getStructSig(target).value++;
+      }
+      return true;
+    }
+
+    const had = Object.prototype.hasOwnProperty.call(target, key);
+    if (had && Object.is(target[key], raw)) return true;
+
+    target[key] = raw;
+    const map = keySignals.get(target);
+    const sig = map && map.get(key);
+    if (sig) sig.value = raw; // notify only if someone is listening
+    if (!had) getStructSig(target).value++; // new key → shape changed
+    return true;
+  },
+
+  deleteProperty(target, key) {
+    if (!Object.prototype.hasOwnProperty.call(target, key)) return true;
+    delete target[key];
+    const map = keySignals.get(target);
+    const sig = map && map.get(key);
+    if (sig) sig.value = undefined;
+    getStructSig(target).value++;
+    return true;
+  },
+
+  has(target, key) {
+    getStructSig(target).value;
+    return Reflect.has(target, key);
+  },
+
+  ownKeys(target) {
+    getStructSig(target).value;
+    return Reflect.ownKeys(target);
+  },
+};
+
+function wrap(target) {
+  const cached = proxyCache.get(target);
+  if (cached) return cached;
+  const proxy = new Proxy(target, handler);
+  proxyCache.set(target, proxy);
+  return proxy;
+}
+
+/**
+ * Create a deep reactive store over a plain object/array. Property reads inside
+ * an effect subscribe fine-grained; writes (`s.a.b = x`, `s.items.push(y)`)
+ * notify only dependents of the touched paths.
+ */
+export function reactive(init = {}) {
+  if (!isWrappable(init)) {
+    throw new TypeError("reactive() expects a plain object or array");
+  }
+  return wrap(init);
+}
+
+/** Whether `v` is a store created by `reactive()`. */
+export function isReactive(v) {
+  return !!(v && typeof v === "object" && v[IS_REACTIVE]);
+}
+
+/** The underlying plain object of a store (live, not a copy); identity for non-stores. */
+export function toRawValue(v) {
+  return isReactive(v) ? v[RAW] : v;
+}
+
+/**
+ * A plain, non-reactive deep copy of a store's current value — for submit
+ * payloads, validation input, or persistence. Reads are untracked, so taking a
+ * snapshot never subscribes the caller.
+ */
+export function snapshot(v) {
+  return untracked(() => structuredClone(toRawValue(v)));
+}

package/core/signals.js

@@ -0,0 +1,207 @@
+//! Fine-grained reactivity — our own signals core.
+//
+// This replaces the previous `@preact/signals-core` dependency to remove a
+// third-party supply-chain risk (SPEC §1.1). The public surface is the
+// industry-standard `signal` / `computed` / `effect` with a `.value` accessor;
+// more APIs (peek/untracked/subscribe) are added only when a consumer needs them.
+//
+// Model: producers (signals, computeds) hold a set of subscribers; consumers
+// (effects, computeds) track the producers they read. Reads register a
+// dependency on the active consumer; writes mark dependent computeds stale and
+// queue dependent effects, which run once per change/batch (glitch-free: an
+// effect that depends on a signal both directly and via a computed runs once).
+
+import { reportError } from "./errors.js";
+
+/** The consumer (effect or computed) currently executing, if any. */
+let activeConsumer = null;
+/** Depth of nested `batch()` calls; effects flush when this returns to 0. */
+let batchDepth = 0;
+/** Re-entrancy guard for the flush loop. */
+let flushing = false;
+/** Effects queued to run on the next flush. A Set so each runs at most once. */
+const pendingEffects = new Set();
+
+/** Register `producer` as a dependency of the consumer currently running. */
+function track(producer) {
+  if (activeConsumer) {
+    activeConsumer.sources.add(producer);
+    producer.subscribers.add(activeConsumer);
+  }
+}
+
+/** Detach a consumer from all producers it previously read. */
+function clearSources(consumer) {
+  for (const source of consumer.sources) {
+    source.subscribers.delete(consumer);
+  }
+  consumer.sources.clear();
+}
+
+/** Mark dependents stale: computeds recursively, effects into the run queue. */
+function propagate(producer) {
+  for (const sub of producer.subscribers) {
+    if (sub.kind === "computed") {
+      if (!sub.stale) {
+        sub.stale = true;
+        propagate(sub);
+      }
+    } else {
+      pendingEffects.add(sub);
+    }
+  }
+}
+
+/** Run all queued effects, including any they queue in turn. */
+function flush() {
+  if (flushing) return;
+  flushing = true;
+  try {
+    while (pendingEffects.size > 0) {
+      const batch = [...pendingEffects];
+      pendingEffects.clear();
+      for (const effectNode of batch) {
+        if (effectNode.disposed) continue;
+        // A throwing reactive update is reported but must not break the scheduler
+        // (other queued effects still run). Build-time (initial) runs propagate so
+        // the surrounding component/page catch can handle them.
+        try {
+          effectNode.run();
+        } catch (e) {
+          reportError(e, { phase: "effect" });
+        }
+      }
+    }
+  } finally {
+    flushing = false;
+  }
+}
+
+/**
+ * A writable reactive value. Reading `.value` inside an effect/computed
+ * subscribes to it; writing a changed `.value` notifies dependents.
+ */
+export function signal(initial) {
+  const node = { kind: "signal", value: initial, subscribers: new Set() };
+  return {
+    get value() {
+      track(node);
+      return node.value;
+    },
+    set value(next) {
+      if (Object.is(next, node.value)) return;
+      node.value = next;
+      propagate(node);
+      if (batchDepth === 0) flush();
+    },
+    /** Read the current value without subscribing the active consumer. */
+    peek() {
+      return node.value;
+    },
+  };
+}
+
+/**
+ * Run `fn` without subscribing the active consumer to any signals it reads.
+ * Use inside an effect/computed to read reactive state without depending on it
+ * (e.g. validation that reads many fields but should not re-run on each).
+ */
+export function untracked(fn) {
+  const prev = activeConsumer;
+  activeConsumer = null;
+  try {
+    return fn();
+  } finally {
+    activeConsumer = prev;
+  }
+}
+
+/**
+ * A derived, read-only reactive value. Lazy and cached: the compute function
+ * runs only when `.value` is read while stale, and recomputes only after a
+ * dependency changes.
+ */
+export function computed(fn) {
+  const node = {
+    kind: "computed",
+    fn,
+    value: undefined,
+    stale: true,
+    sources: new Set(),
+    subscribers: new Set(),
+  };
+  return {
+    get value() {
+      if (node.stale) {
+        const prev = activeConsumer;
+        clearSources(node);
+        activeConsumer = node;
+        try {
+          node.value = node.fn();
+          node.stale = false;
+        } finally {
+          activeConsumer = prev;
+        }
+      }
+      track(node);
+      return node.value;
+    },
+  };
+}
+
+/**
+ * Run `fn` immediately, tracking the signals it reads, and re-run it whenever
+ * any of them change. `fn` may return a cleanup function, which runs before the
+ * next re-run and on dispose. Returns a disposer that stops the effect.
+ */
+export function effect(fn) {
+  const node = {
+    kind: "effect",
+    fn,
+    cleanup: undefined,
+    sources: new Set(),
+    disposed: false,
+    run() {
+      if (node.disposed) return;
+      runCleanup(node);
+      clearSources(node);
+      const prev = activeConsumer;
+      activeConsumer = node;
+      try {
+        const result = node.fn();
+        if (typeof result === "function") node.cleanup = result;
+      } finally {
+        activeConsumer = prev;
+      }
+    },
+  };
+  node.run();
+  return function dispose() {
+    if (node.disposed) return;
+    node.disposed = true;
+    runCleanup(node);
+    clearSources(node);
+  };
+}
+
+function runCleanup(node) {
+  if (node.cleanup) {
+    const fn = node.cleanup;
+    node.cleanup = undefined;
+    fn();
+  }
+}
+
+/**
+ * Group multiple writes so dependent effects run once after the outermost batch
+ * completes, instead of after each write.
+ */
+export function batch(fn) {
+  batchDepth++;
+  try {
+    return fn();
+  } finally {
+    batchDepth--;
+    if (batchDepth === 0) flush();
+  }
+}

package/index.js

@@ -0,0 +1,13 @@
+// Public entry for the OTF Web runtime: reactivity + DOM operations.
+// CSR-generated modules import their helpers (signal/computed/bindText/…) from here.
+export * from "./core/signals.js";
+export * from "./core/reactive.js";
+export * from "./core/errors.js";
+export * from "./runtime/index.js";
+// `Link` is shipped as JSX source and compiled by the consuming app's pipeline
+// (the `.jsx` lands in the module graph and otfwc transforms it). Its compiled
+// module self-registers `web-link` (CSR `customElements.define` / SSG `defineSSG`).
+// The bare import forces that registration to be retained — `<Link>` is used as a
+// tag, so the `Link` binding alone would be tree-shaken.
+import "./components/Link.jsx";
+export { default as Link } from "./components/Link.jsx";

package/package.json

@@ -1,29 +1,38 @@
 {
   "name": "@opentf/web",
-  "version": "0.4.0",
-  "description": "The core engine of the Web App Framework, including the zero-VDOM compiler and signal-based runtime.",
-  "main": "dist/index.js",
-  "module": "dist/index.js",
+  "version": "0.6.0",
+  "description": "The native-first OTF Web runtime — signal-based reactivity and zero-VDOM DOM operations, paired with the IR-based compiler.",
   "type": "module",
-  "scripts": {
-    "build": "babel . --out-dir dist --extensions .js,.jsx --copy-files --config-file ./babel.config.cjs --ignore \"node_modules,dist,package.json,bun.lock,*.md\"",
-    "prepublishOnly": "npm run build"
-  },
   "exports": {
-    ".": "./dist/index.js",
-    "./compiler": "./dist/compiler/babel-plugin.cjs",
-    "./runtime": "./dist/runtime/index.js",
-    "./router": "./dist/router/index.js"
+    ".": "./index.js",
+    "./signals": "./core/signals.js",
+    "./runtime": "./runtime/index.js",
+    "./server": "./server/index.js"
   },
   "files": [
-    "dist"
+    "index.js",
+    "core",
+    "runtime",
+    "components",
+    "server",
+    "!**/*.test.js"
+  ],
+  "keywords": [
+    "opentf",
+    "web-components",
+    "signals",
+    "reactivity",
+    "runtime",
+    "ssg"
   ],
-  "dependencies": {
-    "@preact/signals-core": "^1.14.1",
-    "@babel/core": "^7.29.0",
-    "@babel/helper-module-imports": "^7.28.6",
-    "@babel/plugin-syntax-jsx": "^7.28.6"
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Open-Tech-Foundation/Web-App-Framework.git",
+    "directory": "packages/web"
   },
+  "homepage": "https://github.com/Open-Tech-Foundation/Web-App-Framework#readme",
+  "bugs": "https://github.com/Open-Tech-Foundation/Web-App-Framework/issues",
+  "license": "MIT",
   "publishConfig": {
     "access": "public"
   }

package/runtime/clipboard.js

@@ -0,0 +1,47 @@
+//! Clipboard helpers for "copy" affordances (code blocks, etc.).
+//
+// Behavior travels with the component that needs it — these are imported by the
+// `web-internal-code-block` built-in and by `@opentf/web-docs`'s `CodeBlock`, so a
+// copy button works wherever it's rendered, with no cooperation from an ancestor
+// layout. `copyText` prefers the async Clipboard API and falls back to a hidden
+// `<textarea>` + `execCommand` for non-secure contexts / older browsers.
+
+export function copyText(text) {
+  if (typeof navigator !== "undefined" && navigator.clipboard?.writeText) {
+    navigator.clipboard.writeText(text).catch(() => fallbackCopy(text));
+  } else {
+    fallbackCopy(text);
+  }
+}
+
+function fallbackCopy(text) {
+  try {
+    const ta = document.createElement("textarea");
+    ta.value = text;
+    ta.style.position = "fixed";
+    ta.style.opacity = "0";
+    document.body.appendChild(ta);
+    ta.select();
+    document.execCommand("copy");
+    document.body.removeChild(ta);
+  } catch {
+    /* clipboard unavailable */
+  }
+}
+
+/**
+ * Copy `text`, then give `button` the standard "Copied" feedback: add `is-copied`,
+ * swap its `.otfw-copy-label` to "Copied", and revert after 2s. Idempotent across
+ * rapid clicks (the pending revert is reset each time).
+ */
+export function copyWithFeedback(button, text) {
+  copyText(text);
+  const label = button.querySelector(".otfw-copy-label");
+  button.classList.add("is-copied");
+  if (label) label.textContent = "Copied";
+  clearTimeout(button._otfwCopyT);
+  button._otfwCopyT = setTimeout(() => {
+    button.classList.remove("is-copied");
+    if (label) label.textContent = "Copy";
+  }, 2000);
+}