tutuca 0.15.0 → 1.0.0-beta.2

package/CHANGELOG.md

@@ -0,0 +1,132 @@
+# Changelog
+
+## 1.0.0-beta.2
+
+Messages are delivered by identity as well as by path, following the tree model in
+`spec/tree`: a reply, a `sendAt` or a notification's next hop no longer reaches whatever
+component took the path in the meantime. See [`docs/paths.md`](docs/paths.md).
+
+### Breaking
+
+- **Asks are answered in an `answers` section.** `answers: { load: { ok, error, unhandled } }`
+  replaces the `xReplyOk` / `xReplyError` / `xHandlerNotFound` messages, and a send can't forge
+  one. `ctx.ask` returns a request id, which the answer's handler reads as `ctx.request`.
+  Stories answer asks with `step.answer`, tests with `driver.answer`. The lint checks the
+  section and warns about an ask a message emits with no answers for it.
+- **An ask handler only answers.** It's called with the ask's arguments and `ctx.readOnly()`,
+  a frozen view of the asker's scope, path, source key and `now` / `random` / `uuid`, with
+  nothing to send with. The ask starts once the task that asked commits, so a failed task
+  never starts one, and its answer runs as a task of its own; an answer that throws fails only
+  itself.
+- **A task made outside a handler is addressed with `task.prepare(root)`.**
+  `Host.prepareTask` is gone.
+- **A message's context stages what its handler sends** in its own list, which the host
+  queues once the task commits.
+
+### Changes
+
+- **Messages carry a sender and a receiver `Address`**, each a path and the identity it
+  reached. Every component instance has an identity, fresh when it's made or when a handler
+  returns a new one, and kept by updates. `ctx.reply(name, args)` sends to the sender of the
+  message being handled; `HOST` is the sender of DOM events and ask answers. A task whose
+  receiver was replaced is dropped and reported `stale`; one whose path reaches no component is
+  reported `orphaned`.
+- **Notifications bubble in one turn.** Their hops are the sender's ancestors when the
+  bubble starts and run back to back, ahead of the queue. An ancestor without a handler passes
+  one on silently; one that no hop handled is reported `unhandled` once, at the root.
+- **A message with no handler is a no-op that's reported** (`Host.notify("unhandled", { task,
+  message })`), whatever sent it, a DOM event included: components compose dynamically, so a
+  view can send a message its component lacks.
+- **The host reports instead of throwing**: a render that throws is `renderFailed`, an event
+  the DOM can't route is `eventFailed`, and a stopped host drops late tasks.
+- A handler's `emits` contract counts only what that handler emitted.
+- `sourceKey` is `null` for a sender in another branch.
+- Records and `oneOf` defaults meet the constraints of what they are made of: a record key
+  whose default breaks its constraints throws `NoDefaultError` naming the key, and a `oneOf`
+  makes its first alternative.
+
+### Fixes
+
+- Morphing matches vnodes only to the nodes render made, so nodes other code puts in a
+  rendered element (an extension, a third-party widget, a foreign comment) stay in place.
+- Routing and drags read `data-eid`, `data-dragtype` and the drag marks as attributes instead of
+  through `dataset`, which MathML elements lack, so a click on a formula reaches its handler.
+- The vdom prebuilds constant children and elements once per view, and decides by itself
+  which attributes must stay dynamic.
+
+## 1.0.0-beta.1
+
+Tutuca 1.0 is a rewrite. It keeps the core ideas of 0.x, but the API, the view language and the
+tooling change a lot, so 0.x apps don't run on it without being ported. The 0.x line ends at
+0.15.0.
+
+### What stays the same
+
+- **One immutable state tree.** The app state is a tree of component instances, and every
+  update replaces the root with a new value. Views are functions of that state.
+- **Handlers mutate a draft.** A handler gets an immer draft and changes it in place.
+  Returning a value replaces the component. immer is still vendored, so the core has no npm
+  dependencies.
+- **Typed fields and named views.** Components declare typed `fields`, a `main` view plus other
+  named views, and `methods` that views and handlers can read.
+- **Rendering through paths.** The DOM holds no references to instances. Events are routed
+  through the dispatch path recorded at render time, and the update goes back in through the
+  path to the value that owns it.
+- **Messages up, down and across.** A component handles its own events, can send messages to
+  components found by a selector, and can raise a message that bubbles up to its parents. A
+  request with `Ok` / `Error` replies becomes `ask` with `ReplyOk` / `ReplyError`.
+- **Values passed down without threading them through props.** 0.x's `provide` / `lookup` is
+  now `provides` / `lookupBind`.
+- **Iteration with filters and loop state** (`each` and loops, which were `@each`, `@when` and
+  `@loop-with`), **pushed views** for nested components, and **drag and drop**.
+- **The checks are part of the library**: a linter, tests that run without a browser, and a
+  storybook built from the same component definitions.
+
+### What changes
+
+- **Views are built in JavaScript, not parsed from HTML.** `h(tag, attrs, ...children)`, the
+  `tag` / `button` builders and AST helpers (`field`, `send`, `each`, `render`, `$if`,
+  `pushView`, `scope`, ...) replace the `html\`...\`` templates, the `@`/`:` directives and the
+  value grammar (`.x`, `$x`, `@x`, `^x`, `*x`). Macros are gone; use JavaScript functions that
+  return view nodes.
+- **Explicit schemas.** Field types come from `t.*` (`t.number()`, `t.string()`, `t.array()`,
+  `t.option()`, `t.enum()`, `t.record()`, `t.oneOf()`, `t.map()`, `t.component()`, ...) rather than being inferred
+  from default values. They feed validation, the lint, property-based tests and sync.
+- **Handlers.** `receive` and `intent` merge into one `on` table. A handler is called as
+  `handler(next, args, ctx)`, with `next` being the draft, and can declare a contract (`args`,
+  `sourceKey`, `pre`, `post`, `emits`). Components can declare `invariants`. Contracts and
+  invariants are checked in development and in tests.
+- **The host.** `tutuca("#app")`, `registerComponents` and `app.state.set` are replaced by
+  `new Host({ document, rootNode })`, `host.scope.register({...})` and `host.start(instance)`.
+  Scopes nest, and they also hold the handlers that answer `ask`.
+- **A controlled world.** Handlers read time and randomness through `ctx.now()`,
+  `ctx.random()` and `ctx.uuid()`, so test runs and sync replays repeat.
+- **Styling.** The scoped `style` / `commonStyle` / `globalStyle` CSS is gone. `tutuca/classes`
+  lists the class names a view uses, for CSS tools that need them.
+- **Packaging.** The package ships its ES module sources (`src/`) with one export per area
+  (`tutuca`, `/vdom`, `/dev`, `/lint`, `/classes`, `/pbt`, `/storybook`, `/element`,
+  `/playground`, `/history`, `/sync`, `/sync/remote`, `/automerge`). The CDN bundles are
+  `dist/tutuca.js` and `dist/tutuca.min.js`. jsdom, prettier and chai are no longer
+  dependencies. `fast-check` and `@automerge/automerge` are optional peers.
+- **Removed:** the `tutuca` CLI (`get`, `list`, `show`, `lint`, `render`, `test`,
+  `storybook`, `install-skill`, `agent-context`, ...), the bundled agent skill, the
+  `tutuca/components` inspector components, the `getTests()` / `getExamples()` module
+  conventions and the `.dev.js` auto-discovery. The linter, tests and storybook are now used
+  as libraries.
+
+### New
+
+- **Property-based testing** (`tutuca/pbt`): arbitraries generated from field schemas and a
+  headless `Driver` that runs message sequences and shrinks failures.
+- **Sync** (`tutuca/sync`, `tutuca/sync/remote`, `tutuca/automerge`): a schema-guided diff,
+  per-field sync levels and pluggable engines that persist state or share it across tabs and
+  devices. State saved by another version of the components is adapted and reported. See
+  [`docs/sync.md`](docs/sync.md).
+- **History** (`tutuca/history`, `tutuca/history/bar`): step through states one user action
+  at a time. Going back is applied as a change, so storage and peers follow.
+- **Storybook stress tests**, with a log of each run and its shrink attempts.
+- **`<tutuca-app>`** (`tutuca/element`) and **`<tutuca-playground>`**
+  (`tutuca/playground`), which edits a book of stories in CodeMirror and runs it live, keeping
+  state across edits.
+- **DevTools formatters and an inspector panel** (`tutuca/dev`).
+- **A formal model** of the semantics in PLT Redex (`spec/`), kept in sync with `src/`.

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Mariano Guerra
+Copyright (c) 2025-2026 Mariano Guerra
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,193 +1,87 @@
 # Tutuca
 
-Batteries included SPA framework with a dependency-free browser bundle.
-
-- **Single file, no build, no dependencies, no setup** — a script tag is all you need
-- **Batteries included** — state management, side effects, automatic memoization, drag and drop, testing, CLI tooling, LLM skills and more
-- **Fits in your head** (and the context window)
-- **View source friendly** — step through the whole stack
-- **As much HTML as possible, as little JS as needed**
-- ~110KB minified, ~29KB brotli compressed (the core browser bundle; the dev build adds linting and test helpers)
-
-## Quick Start
-
-For an interactive walk-through with editable examples, see the
-[tutorial](https://marianoguerra.github.io/tutuca/tutorial.html).
-Upgrading an Immutable.js-based app? See the
-[Immer migration guide](./docs/immer-migration.md).
-
-### CDN (no install)
-
-```html
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Tutuca: Getting Started</title>
-  </head>
-  <body>
-    <div id="app"></div>
-    <script type="module">
-      import { component, html, tutuca } from "https://cdn.jsdelivr.net/npm/tutuca/+esm";
-
-      const Counter = component({
-        name: "Counter",
-        fields: {
-          count: 0,
-        },
-        receive: {
-          inc(draft) {
-            draft.count++;
-          },
-          dec(draft) {
-            draft.count--;
-          },
-        },
-        view: html`<div>
-          <button @on.click="dec">-</button>
-          <div @text=".count"></div>
-          <button @on.click="inc">+</button>
-        </div>`,
-      });
-
-      function main() {
-        const app = tutuca("#app");
-        app.state.set(Counter.make({}));
-        app.registerComponents([Counter]);
-        app.start();
-      }
-
-      main();
-    </script>
-  </body>
-</html>
-```
-
-## Concepts at a Glance
-
-Each concept has a tutorial section with editable live examples:
-
-- **[Components & state](https://marianoguerra.github.io/tutuca/tutorial.html#basics)** —
-  typed `fields`, Immer draft-first handlers, and views as pure functions of a
-  single immutable state tree
-  ([state & updates](https://marianoguerra.github.io/tutuca/tutorial.html#state-and-updates))
-- **[Collections](https://marianoguerra.github.io/tutuca/tutorial.html#collections)** —
-  iterate with `@each`, filter with `@when`, paginate with `@loop-with`
-- **[Rendering components](https://marianoguerra.github.io/tutuca/tutorial.html#rendering-components)** —
-  compose with `<x render>`, multiple views per component, scoped styles
-- **[Component communication](https://marianoguerra.github.io/tutuca/tutorial.html#component-communication)** —
-  send messages to a target, or raise an intent and let a route find whoever
-  answers it
-- **[Macros](https://marianoguerra.github.io/tutuca/tutorial.html#macros)** —
-  reusable markup fragments with parameters and slots
-- **[Escape hatches](https://marianoguerra.github.io/tutuca/tutorial.html#escape-hatches)** —
-  drag and drop, web components, raw HTML
-- **[Testing](https://marianoguerra.github.io/tutuca/tutorial.html#testing)** —
-  `getTests()` suites run by the CLI or in the browser, plus a
-  [linter](https://marianoguerra.github.io/tutuca/tutorial.html#linter-reference)
-  that catches template mistakes before they render blank
-
-## CLI
-
-Tutuca ships a single-file CLI (`dist/tutuca-cli.js`) for inspecting, linting,
-documenting, and rendering components defined in an ES module. The module just
-needs to export `getComponents()` and, for render-time commands, `getExamples()`
-in the storybook shape `{ title, description?, items: [{ title, description?, value, view? }] }` (a single section, or an array of sections).
-Expose **all** of your app's components through `getComponents()` — components
-left out are invisible to `lint`/`render`/`test` and silently lose coverage.
-
-### Setup
-
-```sh
-npm install --save-dev tutuca
-```
+A small framework for web apps in the browser, small enough to read in full, for people and for
+coding agents.
 
-The package exposes `tutuca` via `bin`, so `npx tutuca` (or a global `npm i -g tutuca`) just works. `jsdom` (needed by `render` and `lint`) and `prettier` (used by `--pretty`) ship as regular dependencies and are installed automatically.
+Tutuca covers components, typed state, rendering and event handling, and the tools to check them:
+tests that run without a browser, property-based tests generated from your field types, a
+storybook with stress tests, and a linter. State changes can be saved or shared with other tabs
+and devices through sync engines you plug in ([`docs/sync.md`](docs/sync.md)). A formal model of
+the semantics is being written in PLT Redex (`spec/`). The core is about 2,000 lines of
+JavaScript with no npm dependencies (it includes a copy of immer).
 
-### Commands
+- Site: https://marianoguerra.github.io/tutuca/
+- Storybook: https://marianoguerra.github.io/tutuca/storybook.html
 
-```
-tutuca <command> <module-path> [args] [flags]
-tutuca help [command]
-```
-
-| Command | What it does |
-|---|---|
-| `get <module>` | Export inventory and counts for the module |
-| `list <module> [name] [--limit n]` | List components and their fields/views (`--limit n` caps, `0` = all) |
-| `examples <module> [--limit n]` | List the examples defined in the module's section (`--limit n` caps, `0` = all) |
-| `show <module> [name]` | Component API docs — all, or one by name |
-| `lint <module> [name]` | Run lint checks — all, or one by name (exit `2` on errors) |
-| `render <module> [name] [--title t] [--view v]` | Render examples to HTML (exit `3` on render crash) |
-| `test <module> [name] [--grep p] [--bail]` | Run `getTests()` (exit `4` on failures) |
-| `storybook [dir]` | Serve a live storybook, auto-discovering co-located `*.dev.js` modules (`--port`, `--out`, `--dry-run`, `--no-margaui`, `--no-check`, `--no-tests`; no module path needed) |
-| `feedback [message]` | Append a feedback note (positional or stdin) to `~/.tutuca/feedback.jsonl` (no module path needed) |
-| `install-skill [--user\|--project] [--margaui-skill\|--all] [--dot-agents] [--dry-run] [--force]` | Install bundled Claude Code skills (no module path needed) |
-| `agent-context` | Print a versioned JSON schema of the entire CLI surface (no module path needed) |
-
-Global flags: `--json`, `-f, --format <cli\|md\|json\|html>`, `-o, --output <file>`, `--pretty`, `--module <path>`, `-h, --help`.
-
-`storybook` wires [MargaUI](https://github.com/marianoguerra/margaui) — a
-Tailwind v4 / daisyUI-compatible class library — by default; `--no-margaui`
-skips it. For the full flag reference, error codes, and "did you mean"
-behavior, run `tutuca help <command>`, or `tutuca agent-context` for a
-machine-readable schema of the whole surface.
-
-### Usage examples
+## Install
 
 ```sh
-# Summary of what the module exports
-npx tutuca get ./src/components.js
+npm install tutuca
+```
 
-# API docs for one component, as markdown
-npx tutuca show ./src/components.js Button --format md -o docs/button.md
+Or from a CDN, without a build step:
 
-# Render every example to HTML, pretty-printed
-npx tutuca render ./src/components.js --format html --pretty -o dist/examples.html
+```js
+import { component, h, Host } from "https://cdn.jsdelivr.net/npm/tutuca/dist/tutuca.min.js";
+```
 
-# Post-edit verification: lint, then render the example covering the
-# feature you just changed.
-npx tutuca lint ./src/components.js
-npx tutuca render ./src/components.js --title "Disabled state"
+## Example
+
+```js
+import { component, field, h, Host, send, t } from "tutuca";
+
+const Counter = component({
+	name: "Counter",
+	fields: { count: t.number() },
+	view: h("button", { "on:click": send("inc") }, "Clicked ", field("count")),
+	on: {
+		inc(next) {
+			next.count += 1;
+		},
+	},
+});
+
+const host = new Host({ document, rootNode: document.getElementById("app") });
+host.scope.register({ Counter });
+host.start(host.scope.components.Counter());
 ```
 
-## Use with Claude Code
+## Modules
 
-Tutuca ships an LLM-facing reference (`SKILL.md` plus topic files such as
-`core.md`, `cli.md`, `advanced.md`, `testing.md`, `storybook.md`, and more)
-packaged as a [Claude Code skill](https://docs.claude.com/en/docs/claude-code/skills).
-Once installed, Claude auto-loads it whenever a session touches tutuca
-components, views, macros, or the CLI.
+| Import | What |
+|---|---|
+| `tutuca` | components, views, schemas, the host, the `tag` and `button` element builders |
+| `tutuca/dev` | DevTools formatters |
+| `tutuca/lint` | the linter |
+| `tutuca/classes` | `collectClasses`, `classNamesOf` and `ClassCompiler`, for CSS compilers that need class names listed |
+| `tutuca/pbt` | property-based testing and the headless driver (bring your own `fast-check`) |
+| `tutuca/storybook` | the storybook |
+| `tutuca/playground` | the `<tutuca-playground>` element: edit a book of stories and run it live (bring your own CodeMirror) |
+| `tutuca/element` | the `<tutuca-app>` custom element |
+| `tutuca/vdom` | the virtual DOM |
+| `tutuca/sync` | sync engines: projection, schema-guided diff, ops, `startSynced`, `storageEngine` |
+| `tutuca/sync/remote` | an engine that sends diffs to a remote and applies the ones it sends |
+| `tutuca/automerge` | an engine over an Automerge document (bring your own `@automerge/automerge`) |
 
-```sh
-# project-scoped: writes ./.claude/skills/tutuca/ (commit it for the team)
-npx tutuca install-skill
+## Docs
 
-# or user-scoped: writes ~/.claude/skills/tutuca/
-npx tutuca install-skill --user
+- [`docs/paths.md`](docs/paths.md): how update paths, dispatch paths and selectors route messages.
+- [`docs/sync.md`](docs/sync.md): persisting and syncing state with sync engines.
+- [`spec/README.md`](spec/README.md): the formal semantics in PLT Redex and how it maps to `src/`.
 
-# companion MargaUI skill, or install both bundled skills
-npx tutuca install-skill --margaui-skill
-npx tutuca install-skill --all
+## Development
 
-# install into ./.agents/skills/ instead of ./.claude/skills/
-npx tutuca install-skill --dot-agents
+Tasks are in the `justfile`; `just` lists them.
 
-# overwrite an existing install
-npx tutuca install-skill --force
+```sh
+just install    # npm install
+just check      # lint, then test
+just storybook  # serve the storybook from the repo
+just site       # build the landing page and storybook into _site/ and serve it
+just smoke      # build dist/ and check what would be published
+just publish    # publish to npm as latest
 ```
 
-The skill content is generated from `docs/skill/`, so the same reference
-runs locally (`tutuca lint <module>` + `tutuca render <module> --title …`)
-and inside Claude.
-
-## Links
-
-- [Documentation & Playground](https://marianoguerra.github.io/tutuca/)
-- [Tutorial](https://marianoguerra.github.io/tutuca/tutorial.html)
-- [GitHub](https://github.com/marianoguerra/tutuca)
-
 ## License
 
 MIT