@zoijs/core 1.3.2 → 1.5.0

package/CHANGELOG.md

@@ -1,103 +1,132 @@
-# Changelog
-
-All notable changes to Zoijs are documented here. The format is based on
-[Keep a Changelog](https://keepachangelog.com/), and Zoijs follows
-[Semantic Versioning](https://semver.org/) (see `VERSIONING.md`).
-
-## [1.3.2] — 2026-06-26
-
-### Fixed
-- **Focus is preserved across a keyed reorder.** The 1.3.1 minimal-move change can
-  move the subtree that holds the focused element, which blurs it in browsers.
-  `each` now captures focus + caret position before reordering and restores them
-  after, so reordering a list never steals focus or selection — whichever nodes
-  happen to move. Verified in Chromium, Firefox, and WebKit
-  (`browser-tests/regression.spec.js`).
-
-## [1.3.1] — 2026-06-26
-
-### Performance
-- **Minimal DOM moves in `each`.** Keyed-list reconciliation now uses a
-  longest-increasing-subsequence pass, so a reorder moves the **fewest nodes
-  possible** — moving one item across a list is a single DOM move (it could be up
-  to N before). No API or behavior change; the final order is identical and reused
-  nodes keep their identity (focus, input values, and scroll survive reorders).
-  Proven by move-count tests (`tests/lis.test.js`); numbers in `bench/`.
-
-## [1.3.0] — 2026-06-26
-
-### Added
-- **`boundary(child, fallback)`.** A render-time error boundary: it renders
-  `child`, and if `child` throws **synchronously while building its markup** (a
-  setup/render error that would otherwise break the whole `mount`), it disposes the
-  partial work — so an `effect` created before the throw can't leak — and renders
-  `fallback` (a value, or `(error) => value`) instead. Catches synchronous
-  setup/render throws only; errors in reactive *updates* are already contained per
-  binding, and *async* errors belong to `@zoijs/resource` / `@zoijs/action`'s
-  `error()` state. Logs in dev, silent in production. The public surface is now
-  **nine** functions (additive MINOR). See [RFC 0004](docs/rfcs/0004-error-boundary.md).
-
-## [1.2.0] — 2026-06-26
-
-### Added
-- **`effect(fn)`.** A public reactive effect — runs a side effect immediately and
-  re-runs whenever a reactive value it reads changes (automatic dependency
-  tracking, microtask-batched). The function may return a cleanup that runs before
-  the next run and on dispose (same convention as a `ref`); `effect` auto-disposes
-  with its owner (component / list item) and returns `{ dispose }` for early
-  teardown. This is the public completion of the reactive trio (`createState` /
-  `computed` / `effect`) — the engine already used it internally for bindings. Use
-  it for side effects *outside* the view (persist on change, sync `document.title`,
-  drive a non-Zoijs widget); for on-screen content, keep using a binding
-  (`${() => …}`). The public surface is now **eight** functions (additive MINOR per
-  `VERSIONING.md`). See [RFC 0003](docs/rfcs/0003-effect-and-svg.md).
-
-### Notes
-- The **`svg`** helper considered alongside `effect` was **deferred**: templates
-  rooted at `<svg>` already render correctly, and only dynamic-SVG *composition* is
-  affected — a minority need. See [RFC 0003](docs/rfcs/0003-effect-and-svg.md) §6.
-
-## [1.1.0] — 2026-06-25
-
-### Added
-- **Element refs.** A new `ref` binding gives you the rendered DOM element:
-  `html\`<input ref=${(el) => el.focus()} />\``. The callback runs once, just after
-  the element is inserted (so `focus`/`scroll`/`measure`/`canvas` work), is not
-  reactive, and may return a cleanup function that runs on unmount or list-item
-  removal. Works inside keyed `each` lists. Non-function values are ignored with a
-  dev-mode warning and never become a DOM attribute. No new export — `ref` is a
-  binding semantic, so the seven-function public surface is unchanged (additive
-  MINOR per `VERSIONING.md`). See [Element refs](docs/concepts/refs.md) and
-  [RFC 0001](docs/rfcs/0001-element-refs.md).
-
-## [1.0.0] — 2026-06-24
-
-First stable release. The public API is frozen at seven functions.
-
-### Public API
-- `html` — tagged-template renderer (no JSX, no build step).
-- `mount(component, target)` → `unmount()`.
-- `createState(value)` → `{ get, set, peek }`.
-- `computed(fn)` → `{ get, peek }` — lazy, cached, value-gated.
-- `each(items, keyFn, renderFn)` — keyed list reconciliation.
-- `configure({ dev })` — development/production mode.
-- `onCleanup(fn)` — teardown for components and list items.
-
-### Features
-- Fine-grained, direct DOM updates (no Virtual DOM); setup runs once.
-- Push-pull reactive core with automatic dependency tracking and microtask batching.
-- Owner-scoped cleanup; deterministic teardown on unmount and list-item removal.
-- Context-aware template parser (quoted/unquoted/partial/multi-hole attributes,
-  boolean/URL/aria/data attributes, SVG, nested templates and lists).
-- Secure by default: inert text, URL-scheme allowlist (control-char resistant),
-  `data:` raster-image rules, `on*`/`srcdoc` blocked, function-only handlers,
-  no `eval`, CSP- and Trusted-Types-friendly.
-- TypeScript definitions with generics for state/computed/lists.
-
-### Tooling
-- 100+ unit/DOM tests (jsdom), real-browser tests on Chromium/Firefox/WebKit
-  (Playwright), and TypeScript type tests.
-- No build step required at any point.
-
-[1.1.0]: https://github.com/Zoijs/zoijs/releases/tag/core-v1.1.0
-[1.0.0]: https://github.com/Zoijs/zoijs/releases/tag/core-v1.0.0
+# Changelog
+
+All notable changes to Zoijs are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/), and Zoijs follows
+[Semantic Versioning](https://semver.org/) (see `VERSIONING.md`).
+
+## [1.5.0] — 2026-06-26
+
+### Added
+- **DOM-free template compiler + a `@zoijs/core/server` subpath.** `html\`…\`` now
+  compiles to a static HTML string + part descriptors **without touching the DOM**;
+  the `<template>` element is built lazily on first client render. This means a
+  component can be evaluated on a server (no DOM) so [`@zoijs/ssr`](https://www.npmjs.com/package/@zoijs/ssr)
+  can render it to a string. The new subpath exposes the building blocks a server
+  renderer needs — the static HTML/parts of a result, template/list markers, and the
+  **same** security predicates the client uses (`escapeText`, `escapeAttr`,
+  `isSafeUrl`, `isSafeAttributeName`, `URL_ATTRS`) so server and client make
+  identical safety decisions. Client rendering is byte-for-byte unchanged; the
+  learnable nine-function main surface is unchanged. See
+  [RFC 0008](docs/rfcs/0008-ssr.md).
+
+## [1.4.0] — 2026-06-26
+
+### Added
+- **Devtools inspection hook** (`@zoijs/core/devtools`). A new, dev-only, read-only
+  seam that lets an inspector — [`@zoijs/devtools`](https://www.npmjs.com/package/@zoijs/devtools)
+  or a browser extension — observe the reactive graph: states, computeds, effects,
+  the edges between them, and **which DOM node each binding updates**. It's reached
+  through a dedicated subpath (`import { attachInspector } from "@zoijs/core/devtools"`),
+  so the learnable **nine-function** main surface is unchanged. The hook is off by
+  default (a single null check until something attaches), never instruments the hot
+  read path (`.get()`), and is a no-op under `configure({ dev: false })` — so a
+  production app pays no measurable cost and exposes nothing. See
+  [RFC 0005](docs/rfcs/0005-devtools-hook.md).
+
+## [1.3.2] — 2026-06-26
+
+### Fixed
+- **Focus is preserved across a keyed reorder.** The 1.3.1 minimal-move change can
+  move the subtree that holds the focused element, which blurs it in browsers.
+  `each` now captures focus + caret position before reordering and restores them
+  after, so reordering a list never steals focus or selection — whichever nodes
+  happen to move. Verified in Chromium, Firefox, and WebKit
+  (`browser-tests/regression.spec.js`).
+
+## [1.3.1] — 2026-06-26
+
+### Performance
+- **Minimal DOM moves in `each`.** Keyed-list reconciliation now uses a
+  longest-increasing-subsequence pass, so a reorder moves the **fewest nodes
+  possible** — moving one item across a list is a single DOM move (it could be up
+  to N before). No API or behavior change; the final order is identical and reused
+  nodes keep their identity (focus, input values, and scroll survive reorders).
+  Proven by move-count tests (`tests/lis.test.js`); numbers in `bench/`.
+
+## [1.3.0] — 2026-06-26
+
+### Added
+- **`boundary(child, fallback)`.** A render-time error boundary: it renders
+  `child`, and if `child` throws **synchronously while building its markup** (a
+  setup/render error that would otherwise break the whole `mount`), it disposes the
+  partial work — so an `effect` created before the throw can't leak — and renders
+  `fallback` (a value, or `(error) => value`) instead. Catches synchronous
+  setup/render throws only; errors in reactive *updates* are already contained per
+  binding, and *async* errors belong to `@zoijs/resource` / `@zoijs/action`'s
+  `error()` state. Logs in dev, silent in production. The public surface is now
+  **nine** functions (additive MINOR). See [RFC 0004](docs/rfcs/0004-error-boundary.md).
+
+## [1.2.0] — 2026-06-26
+
+### Added
+- **`effect(fn)`.** A public reactive effect — runs a side effect immediately and
+  re-runs whenever a reactive value it reads changes (automatic dependency
+  tracking, microtask-batched). The function may return a cleanup that runs before
+  the next run and on dispose (same convention as a `ref`); `effect` auto-disposes
+  with its owner (component / list item) and returns `{ dispose }` for early
+  teardown. This is the public completion of the reactive trio (`createState` /
+  `computed` / `effect`) — the engine already used it internally for bindings. Use
+  it for side effects *outside* the view (persist on change, sync `document.title`,
+  drive a non-Zoijs widget); for on-screen content, keep using a binding
+  (`${() => …}`). The public surface is now **eight** functions (additive MINOR per
+  `VERSIONING.md`). See [RFC 0003](docs/rfcs/0003-effect-and-svg.md).
+
+### Notes
+- The **`svg`** helper considered alongside `effect` was **deferred**: templates
+  rooted at `<svg>` already render correctly, and only dynamic-SVG *composition* is
+  affected — a minority need. See [RFC 0003](docs/rfcs/0003-effect-and-svg.md) §6.
+
+## [1.1.0] — 2026-06-25
+
+### Added
+- **Element refs.** A new `ref` binding gives you the rendered DOM element:
+  `html\`<input ref=${(el) => el.focus()} />\``. The callback runs once, just after
+  the element is inserted (so `focus`/`scroll`/`measure`/`canvas` work), is not
+  reactive, and may return a cleanup function that runs on unmount or list-item
+  removal. Works inside keyed `each` lists. Non-function values are ignored with a
+  dev-mode warning and never become a DOM attribute. No new export — `ref` is a
+  binding semantic, so the seven-function public surface is unchanged (additive
+  MINOR per `VERSIONING.md`). See [Element refs](docs/concepts/refs.md) and
+  [RFC 0001](docs/rfcs/0001-element-refs.md).
+
+## [1.0.0] — 2026-06-24
+
+First stable release. The public API is frozen at seven functions.
+
+### Public API
+- `html` — tagged-template renderer (no JSX, no build step).
+- `mount(component, target)` → `unmount()`.
+- `createState(value)` → `{ get, set, peek }`.
+- `computed(fn)` → `{ get, peek }` — lazy, cached, value-gated.
+- `each(items, keyFn, renderFn)` — keyed list reconciliation.
+- `configure({ dev })` — development/production mode.
+- `onCleanup(fn)` — teardown for components and list items.
+
+### Features
+- Fine-grained, direct DOM updates (no Virtual DOM); setup runs once.
+- Push-pull reactive core with automatic dependency tracking and microtask batching.
+- Owner-scoped cleanup; deterministic teardown on unmount and list-item removal.
+- Context-aware template parser (quoted/unquoted/partial/multi-hole attributes,
+  boolean/URL/aria/data attributes, SVG, nested templates and lists).
+- Secure by default: inert text, URL-scheme allowlist (control-char resistant),
+  `data:` raster-image rules, `on*`/`srcdoc` blocked, function-only handlers,
+  no `eval`, CSP- and Trusted-Types-friendly.
+- TypeScript definitions with generics for state/computed/lists.
+
+### Tooling
+- 100+ unit/DOM tests (jsdom), real-browser tests on Chromium/Firefox/WebKit
+  (Playwright), and TypeScript type tests.
+- No build step required at any point.
+
+[1.1.0]: https://github.com/Zoijs/zoijs/releases/tag/core-v1.1.0
+[1.0.0]: https://github.com/Zoijs/zoijs/releases/tag/core-v1.0.0

package/README.md

@@ -1,154 +1,173 @@
-# Zoijs
-
-A lightweight frontend framework you don't have to learn before you use it — **plain HTML, CSS, and JavaScript**, no JSX, no build step, no Virtual DOM.
-
-**[Documentation](https://zoijs.dev)** · **[GitHub](https://github.com/Zoijs)** · **[npm](https://www.npmjs.com/package/@zoijs/core)**
-
-```bash
-npm install @zoijs/core
-```
-
-```js
-import { html, mount, createState } from "@zoijs/core";
-
-function Counter() {
-  const count = createState(0);
-  return html`<button onclick=${() => count.set(count.get() + 1)}>${() => count.get()}</button>`;
-}
-mount(Counter, "#app");
-```
-
-## 📚 Documentation
-
-**New here? Start at [zoijs.dev](https://zoijs.dev) (or the [docs folder](docs/README.md)) — designed to get you productive in under 30 minutes.**
-
-- [Installation](docs/installation.md) · [Your First App](docs/first-app.md) · [Core Concepts](docs/concepts/core-concepts.md)
-- [Tutorials](docs/README.md#tutorials-build-something) · [API Reference](docs/api-reference.md) · [Examples](docs/examples.md)
-- [Troubleshooting](docs/troubleshooting.md) · [FAQ](docs/faq.md) · [Migrating from React/Vue/Solid/Lit/vanilla](docs/README.md#coming-from-another-framework)
-
----
-
-## Mission
-
-Make building modern web applications feel as approachable as writing plain HTML, CSS, and JavaScript — so that any developer, on day one, can ship real software without first learning a framework.
-
-The framework should disappear into the skills developers already have. The whole mental model is three verbs: **write a function that returns `html`, put `createState` values in it, `mount` it.**
-
-## Goals
-
-- **Beginner-friendly** — concepts you already know from vanilla JS/HTML/CSS.
-- **No build step** — runs from a single `<script type="module">`.
-- **No Virtual DOM** — fine-grained, direct DOM updates; only what changed is touched.
-- **Minimal runtime** — the browser does the heavy lifting (native `<template>`, `cloneNode`, events).
-- **Secure by default** — inert text rendering, URL-scheme guards, handler references (never strings), no `eval`.
-- **Small & readable** — a junior developer can read the source.
-
-See [`docs/Phase-1-MVP-Spec.md`](docs/Phase-1-MVP-Spec.md) for the full specification.
-
-## Setup
-
-No build step is required — the framework is plain ES modules.
-
-```bash
-# from the framework/ directory
-
-# run the counter example (serves the project root over http so ES modules resolve)
-npm run dev
-# then open: http://localhost:7310/examples/counter/   (keep the trailing slash)
-
-# run the tests (DOM tests run automatically via jsdom)
-npm test
-```
-
-> Tips:
-> - ES module imports need to be served over `http://`, not opened as a `file://` path. `npm run dev` handles that.
-> - Use the **trailing slash** on the example URL (`/examples/counter/`). Without it, some static servers resolve `./app.js` against the wrong directory and the app won't load.
-
-## Testing
-
-| Command | What it runs |
-|---|---|
-| `npm test` | Unit + DOM tests via jsdom (fast, no browser) |
-| `npm run test:unit` | Pure-logic tests only (no DOM) |
-| `npm run test:types` | TypeScript type-checks (`tsc --noEmit`) |
-| `npm run test:browser` | Real-browser tests in Chromium, Firefox, WebKit (Playwright) |
-
-Browser tests live in `browser-tests/` and run the example apps plus framework regressions against real engines. First-time setup downloads the browsers:
-
-```bash
-npm install
-npx playwright install chromium firefox webkit
-npm run test:browser
-```
-
-Playwright starts a static server automatically (`npx serve` on port 7310) — still no build step.
-
-## Browser support
-
-Modern evergreen browsers. Verified automatically (Playwright) in:
-
-| Browser | Engine | Status |
-|---|---|---|
-| Chrome / Edge | Chromium | ✅ tested |
-| Firefox | Gecko | ✅ tested |
-| Safari | WebKit | ✅ tested |
-
-Relies on baseline-modern platform APIs: ES modules, `<template>`, `TreeWalker`, `Proxy`, `queueMicrotask`, `replaceChildren`, `addEventListener`, `setAttributeNS`. No IE support, no transpilation, no polyfills.
-
-## Public API
-
-```js
-import { html, mount, createState, computed, each, configure, onCleanup } from "@zoijs/core";
-```
-
-- `html` — tagged template; parsed once, cached.
-- `mount(component, target)` — render a component; returns `unmount()`.
-- `createState(value)` — a reactive value (`get` / `set` / `peek`).
-- `computed(fn)` — a lazy, cached, **value-gated** derived value (`get` / `peek`).
-- `each(itemsFn, keyFn, renderFn)` — keyed list rendering (reuse / move / remove nodes).
-- `configure({ dev })` — toggle development warnings (default `dev: true`).
-- `onCleanup(fn)` — register teardown for a component or list item (timers, subscriptions).
-
-See the [Documentation site](docs/README.md) for the full guide, tutorials, and API reference.
-
-**TypeScript:** ships type definitions ([`src/index.d.ts`](src/index.d.ts)) for autocomplete and optional type-checking — JS-first, no build step required. `createState<T>`, `computed<T>`, and `each<T>` are generic. Type-check with `npm run test:types`.
-
-## What's built
-
-- Fine-grained text/attribute bindings — `${() => state.get()}` updates one node in place; setup runs once (no re-render).
-- Native events, secure-by-default rendering (inert text, URL-scheme guards, no `eval`).
-- `computed()` derived values — lazy, cached, nestable, and **value-gated** (unchanged results don't wake downstream).
-- `each()` keyed list reconciliation — preserves focus / input / scroll on reorder.
-- Microtask batching, push-pull dependency tracking, **owner-scoped cleanup** (unmount and removed items dispose their subscriptions).
-- Production mode via `configure({ dev: false })` — no build step.
-- Safety: self-triggering effects are warned + stopped; a throwing binding doesn't break others.
-
-**Out of scope (by design):** router, CLI, plugins, SSR, global store, TypeScript-first setup, Virtual DOM.
-
-## Project Structure
-
-```
-framework/
-  package.json
-  README.md
-  src/
-    core/
-      html.js        # html() — parse template into a cached blueprint
-      mount.js       # mount() — entry point; instantiate + attach + cleanup
-      renderer.js    # internal: bind dynamic slots, apply fine-grained updates
-    reactivity/
-      state.js       # createState() + internal dependency tracking
-    utils/
-      dom.js         # small native-DOM helpers
-      security.js    # escaping, URL-scheme allowlist, attribute-name guards
-    index.js         # public entry — re-exports html, mount, createState
-  examples/
-    counter/         # the first working app
-  tests/             # basic unit tests (node --test)
-  docs/
-    Phase-1-MVP-Spec.md
-```
-
-## License
-
-MIT
+# Zoijs
+
+A lightweight frontend framework you don't have to learn before you use it — **plain HTML, CSS, and JavaScript**, no JSX, no build step, no Virtual DOM.
+
+**[Documentation](https://zoijs.dev)** · **[GitHub](https://github.com/Zoijs)** · **[npm](https://www.npmjs.com/package/@zoijs/core)**
+
+```bash
+npm install @zoijs/core
+```
+
+```js
+import { html, mount, createState } from "@zoijs/core";
+
+function Counter() {
+  const count = createState(0);
+  return html`<button onclick=${() => count.set(count.get() + 1)}>${() => count.get()}</button>`;
+}
+mount(Counter, "#app");
+```
+
+## 📚 Documentation
+
+**New here? Start at [zoijs.dev](https://zoijs.dev) (or the [docs folder](docs/README.md)) — designed to get you productive in under 30 minutes.**
+
+- [Installation](docs/installation.md) · [Your First App](docs/first-app.md) · [Core Concepts](docs/concepts/core-concepts.md)
+- [Tutorials](docs/README.md#tutorials-build-something) · [API Reference](docs/api-reference.md) · [Examples](docs/examples.md)
+- [Troubleshooting](docs/troubleshooting.md) · [FAQ](docs/faq.md) · [Migrating from React/Vue/Solid/Lit/vanilla](docs/README.md#coming-from-another-framework)
+
+---
+
+## Mission
+
+Make building modern web applications feel as approachable as writing plain HTML, CSS, and JavaScript — so that any developer, on day one, can ship real software without first learning a framework.
+
+The framework should disappear into the skills developers already have. The whole mental model is three verbs: **write a function that returns `html`, put `createState` values in it, `mount` it.**
+
+## Goals
+
+- **Beginner-friendly** — concepts you already know from vanilla JS/HTML/CSS.
+- **No build step** — runs from a single `<script type="module">`.
+- **No Virtual DOM** — fine-grained, direct DOM updates; only what changed is touched.
+- **Minimal runtime** — the browser does the heavy lifting (native `<template>`, `cloneNode`, events).
+- **Secure by default** — inert text rendering, URL-scheme guards, handler references (never strings), no `eval`.
+- **Small & readable** — a junior developer can read the source.
+
+See [`docs/Phase-1-MVP-Spec.md`](docs/Phase-1-MVP-Spec.md) for the full specification.
+
+## Setup
+
+No build step is required — the framework is plain ES modules.
+
+```bash
+# from the framework/ directory
+
+# run the counter example (serves the project root over http so ES modules resolve)
+npm run dev
+# then open: http://localhost:7310/examples/counter/   (keep the trailing slash)
+
+# run the tests (DOM tests run automatically via jsdom)
+npm test
+```
+
+> Tips:
+> - ES module imports need to be served over `http://`, not opened as a `file://` path. `npm run dev` handles that.
+> - Use the **trailing slash** on the example URL (`/examples/counter/`). Without it, some static servers resolve `./app.js` against the wrong directory and the app won't load.
+
+## Testing
+
+| Command | What it runs |
+|---|---|
+| `npm test` | Unit + DOM tests via jsdom (fast, no browser) |
+| `npm run test:unit` | Pure-logic tests only (no DOM) |
+| `npm run test:types` | TypeScript type-checks (`tsc --noEmit`) |
+| `npm run test:browser` | Real-browser tests in Chromium, Firefox, WebKit (Playwright) |
+
+Browser tests live in `browser-tests/` and run the example apps plus framework regressions against real engines. First-time setup downloads the browsers:
+
+```bash
+npm install
+npx playwright install chromium firefox webkit
+npm run test:browser
+```
+
+Playwright starts a static server automatically (`npx serve` on port 7310) — still no build step.
+
+## Browser support
+
+Modern evergreen browsers. Verified automatically (Playwright) in:
+
+| Browser | Engine | Status |
+|---|---|---|
+| Chrome / Edge | Chromium | ✅ tested |
+| Firefox | Gecko | ✅ tested |
+| Safari | WebKit | ✅ tested |
+
+Relies on baseline-modern platform APIs: ES modules, `<template>`, `TreeWalker`, `Proxy`, `queueMicrotask`, `replaceChildren`, `addEventListener`, `setAttributeNS`. No IE support, no transpilation, no polyfills.
+
+## Public API
+
+The whole framework is **nine functions** — learnable in one sitting and frozen for 1.x:
+
+```js
+import {
+  html, mount, each, boundary,
+  createState, computed, effect,
+  configure, onCleanup,
+} from "@zoijs/core";
+```
+
+- `html` — tagged template; parsed once, cached.
+- `mount(component, target)` — render a component; returns `unmount()`.
+- `each(itemsFn, keyFn, renderFn)` — keyed list rendering (reuse / move / remove nodes).
+- `boundary(child, fallback)` — render-time error boundary: if `child` throws while building its markup, dispose the partial work and render `fallback`.
+- `createState(value)` — a reactive value (`get` / `set` / `peek`).
+- `computed(fn)` — a lazy, cached, **value-gated** derived value (`get` / `peek`).
+- `effect(fn)` — a side effect that re-runs when a value it reads changes; returns `{ dispose }` and may return a per-run cleanup.
+- `configure({ dev })` — toggle development warnings (default `dev: true`).
+- `onCleanup(fn)` — register teardown for a component or list item (timers, subscriptions).
+
+Plus the **`ref`** binding (`html\`<input ref=${(el) => el.focus()} />\``) — no export; it's a template
+attribute that hands you the rendered element.
+
+**Devtools (dev-only).** A separate subpath, `@zoijs/core/devtools`, exposes a read-only inspection
+hook — `attachInspector(inspector)` and `inspecting()` — that [`@zoijs/devtools`](https://www.npmjs.com/package/@zoijs/devtools)
+(or a browser extension) uses to observe the reactive graph. It's off by default, never instruments
+the hot read path, and is a no-op under `configure({ dev: false })`, so it costs production nothing and
+leaves the nine-function main surface unchanged.
+
+See the [Documentation site](https://zoijs.dev) for the full guide, tutorials, and API reference.
+
+**TypeScript:** ships type definitions ([`src/index.d.ts`](src/index.d.ts)) for autocomplete and optional type-checking — JS-first, no build step required. `createState<T>`, `computed<T>`, and `each<T>` are generic. Type-check with `npm run test:types`.
+
+## What's built
+
+- Fine-grained text/attribute bindings — `${() => state.get()}` updates one node in place; setup runs once (no re-render).
+- Native events, secure-by-default rendering (inert text, URL-scheme guards, no `eval`).
+- `computed()` derived values — lazy, cached, nestable, and **value-gated** (unchanged results don't wake downstream).
+- `effect()` side effects — re-run on change, with owner-scoped auto-disposal and a per-run cleanup.
+- `boundary()` render-time error boundary — a failing subtree shows a fallback instead of breaking `mount`.
+- `each()` keyed list reconciliation — minimal DOM moves; preserves focus / input / scroll on reorder.
+- Microtask batching, push-pull dependency tracking, **owner-scoped cleanup** (unmount and removed items dispose their subscriptions).
+- Production mode via `configure({ dev: false })` — no build step.
+- Safety: self-triggering effects are warned + stopped; a throwing binding doesn't break others.
+
+**Out of scope (by design):** router, CLI, plugins, SSR, global store, TypeScript-first setup, Virtual DOM.
+
+## Project Structure
+
+```
+framework/
+  package.json
+  README.md
+  src/
+    core/
+      html.js        # html() — parse template into a cached blueprint
+      mount.js       # mount() — entry point; instantiate + attach + cleanup
+      renderer.js    # internal: bind dynamic slots, apply fine-grained updates
+    reactivity/
+      state.js       # createState() + internal dependency tracking
+    utils/
+      dom.js         # small native-DOM helpers
+      security.js    # escaping, URL-scheme allowlist, attribute-name guards
+    index.js         # public entry — re-exports html, mount, createState
+  examples/
+    counter/         # the first working app
+  tests/             # basic unit tests (node --test)
+  docs/
+    Phase-1-MVP-Spec.md
+```
+
+## License
+
+MIT