@madojs/mado 0.8.0 → 0.10.0

package/AGENTS.md

@@ -9,9 +9,11 @@
 
 ## Project at a glance
 
-- **Mado** — SPA framework built on Web Components + signals + tagged-template `html`.
-- No build system (only `tsc`), no runtime dependencies.
-- Small TypeScript core in `src/`; bundled/minified full API is roughly 11 KB gzip.
+- **Mado** — a calm browser-native SPA framework for internal tools, admin panels and business apps.
+- Built on Web Components + signals + tagged-template `html`.
+- Zero runtime dependencies. Generated apps use dev tooling (`typescript`,
+  `esbuild`, `linkedom`) for build/bundle/bake/release.
+- Small TypeScript core in `src/`; production size budgets are enforced in CI.
 
 ## HARD RULES — violation = bug
 
@@ -119,7 +121,9 @@ component("x-badge", ({ attr }) => {
 ```
 
 `ctx.attr(name, defaultValue?)` returns a `Signal<string>` that auto-updates.
-The attribute is automatically added to `observedAttributes`.
+Internally Mado uses a per-instance `MutationObserver` for attributes registered
+during `setup()`. The observer auto-disconnects on component removal via
+lifecycle cleanup.
 
 ### 5. Reactive value in template child position = function
 
@@ -180,6 +184,29 @@ html`<ul>
 </ul>`;
 ```
 
+### 7b. Parser hard errors
+
+Mado fails loudly for template shapes that cannot be represented safely.
+
+```ts
+// ❌ NO — slots inside RAW_TEXT elements are a parser error
+html`<textarea>${draft}</textarea>`;
+html`<title>${title}</title>`;
+
+// ✅ YES — use properties or page/head APIs
+html`<textarea .value=${draft}></textarea>`;
+page({ title: ({ id }) => `User ${id}`, view: () => html`<main></main>` });
+
+// ❌ NO — nested SVG-only templates lose namespace context
+html`<svg>${html`<path d=${d}></path>`}</svg>`;
+
+// ✅ YES — keep the SVG in one template or in its own component
+html`<svg viewBox="0 0 10 10"><path d=${d}></path></svg>`;
+```
+
+No dynamic `${...}` child slots inside `<script>`, `<style>`, `<textarea>`,
+or `<title>`. Keep SVG internals in one `<svg>...</svg>` template.
+
 ### 8. Routing — `routes()` + `page()`
 
 ```ts
@@ -202,6 +229,31 @@ export default page<{ id: string }>({
 - Each page is a **separate file** in `pages/` with `export default page({...})`.
 - Import via `() => import("./pages/foo.js")` — this enables code-splitting via ESM.
 - Programmatic navigation: `import { navigate } from "@madojs/mado"; navigate("/users/42")`.
+- Layouts are declared in the route manifest via `layout()`. Treat
+  `layout.view({ child })` as a stateless wrapper around `${child}` and shared
+  chrome. Put per-page state in pages/components/resources, not in layout view
+  locals that depend on route identity.
+- **`onDispose`** — cleanup hook for page views. Use for `setInterval`, `WebSocket`, `EventSource`. `resource()` and `effect()` are auto-cleaned.
+- **`untracked()`** — required when reading signals inside async functions called synchronously from `view()`. Without it, the signal subscribes the router's render effect → infinite loop.
+
+```ts
+// page with polling and cleanup
+import { page, html, signal, untracked } from "@madojs/mado";
+export default page({
+  view: ({ onDispose }) => {
+    const data = signal(null);
+    const poll = async () => {
+      // untracked: don't subscribe the router's render effect
+      const res = await fetch("/api/status");
+      data.set(await res.json());
+    };
+    const id = setInterval(poll, 5000);
+    onDispose(() => clearInterval(id)); // ← cleaned up on navigation
+    poll(); // initial call
+    return html`<div>${() => JSON.stringify(data())}</div>`;
+  },
+});
+```
 
 ### 9. Data fetching — `resource()` / `mutation()`
 
@@ -226,6 +278,14 @@ const save = mutation<User, User>(
 await save.run(newUser);
 ```
 
+- A resource key is the cache identity. Same key means shared cache and deduped
+  in-flight request; use distinct keys for distinct data or auth scope.
+- `mutation().run()` is concurrent by default. `loading()` stays true while any
+  run is in flight. Use `{ abortPrevious: true }` only for search-as-you-type or
+  "latest request wins" flows.
+- Invalidation is best-effort after a successful mutation; invalidation errors
+  are logged but do not turn the mutation itself into a failure.
+
 ### 10. Forms — `useForm()`
 
 ```ts
@@ -325,10 +385,24 @@ Rules:
 - Tiny leaf components used everywhere → importing in `main.ts` is acceptable.
 - Do **not** bulk-import every component "just in case".
 
+### 14. Bake — meta shell, not SSR/SSG runtime
+
+`mado bake` is a static meta-shell/prerender pass for SEO and first paint. It is
+not SSR with hydration and not a Next-style SSG runtime.
+
+- Baked HTML must be deterministic from `params`, `bake.data`, and plain values.
+- Do not rely on browser-only effects, timers, relative `fetch`, or keyed
+  runtime directives such as `each()` during bake.
+- Use `page({ head, bake })` for meta/JSON-LD/sitemap data; render dynamic,
+  personalized, real-time, or auth-dependent content in the client SPA.
+
 ## SOFT GUIDELINES — recommended, but not critical
 
 - **TypeScript strict.** Use `noUncheckedIndexedAccess`-aware code (with `!` or a type guard).
 - **Import using `.js`** (not `.ts`) — this is required by ES modules in the browser: `import { foo } from "./bar.js"`.
+- **Public imports only.** App code imports from `@madojs/mado` and, when
+  needed, side-effect `@madojs/mado/devtools.js`. Other package subpaths and
+  `dist/src/*` are internal.
 - **One file = one responsibility.** Don't put 5 components in one file "because they're all small".
 - **Do not add runtime dependencies** (`npm install` in `dependencies`). This violates the framework's principle.
 - **JSDoc on public functions** is required. Comments explain "why", not "what".
@@ -376,6 +450,9 @@ When generating an app, prefer the blessed production shape from
 | How should an app be structured? | `docs/en/10-app-architecture.md` |
 | How should errors be handled?    | `docs/en/15-error-handling.md`   |
 | How should bake be used?         | `docs/en/16-bake-cookbook.md`    |
+| What API is stable?              | `docs/en/18-api-freeze-map.md`   |
+| What ordering is guaranteed?     | `docs/en/19-reactivity-ordering.md` |
+| What does v1 stability mean?     | `docs/en/20-v1-stability.md`     |
 | When something goes wrong        | `docs/en/07-llm-pitfalls.md`     |
 
 ## Before committing

package/CHANGELOG.md

@@ -2,7 +2,208 @@
 
 ## Unreleased
 
-Nothing yet.
+## 0.10.0 - 2026-06-12
+
+Surface-cleanup and API-lock release from the v1 tracker Phase B: legacy public
+surface is removed, package exports are closed, docs/LLM guidance match the real
+API, and CI now protects package, size, release and LLM-smoke contracts.
+
+### Fixed
+
+- **Component attribute changes no longer clobber host properties (B1).**
+  Legacy `observedAttributes` reflection used to write `this[name] = value`
+  from `attributeChangedCallback`, overwriting `.prop=` bindings and custom
+  host state such as `.value`. Attribute changes now update only `ctx.attr()`
+  signals; `ctx.attr()` is the canonical reactive attribute API.
+
+- **Removed `component(..., { observedAttributes })` (B2).** `ctx.attr()` is now
+  the single reactive-attribute API. It installs a per-instance observer for the
+  attributes used during setup, so component options no longer carry a second
+  attribute mechanism.
+
+- **Package exports are explicit (B3).** The npm package no longer exports
+  `./*`. Public imports are limited to `@madojs/mado` and
+  `@madojs/mado/devtools.js`; internal files such as `lifecycle.js` are no
+  longer package subpaths.
+
+- **Internal `_testHooks` are stripped from declarations (B4).** Runtime hooks
+  remain available to the repository's own tests, but emitted `.d.ts` files no
+  longer advertise them as public API; the router barrel also no longer
+  re-exports manifest test hooks.
+
+- **README now states the explicit No list (B5).** The project boundary is
+  documented: no SSR hydration, template compiler, separate store library,
+  Suspense, router plugin system, built-in i18n/animation/virtual-scroll
+  primitives, or non-evergreen browser support. Browser baseline is pinned to
+  Baseline 2023.
+
+- **`resource()` dedupes in-flight requests by key (B6).** Concurrent resources
+  with the same key now share one fetch. If the same in-flight key is used with
+  different fetcher functions, Mado warns once because the cache key is likely
+  too broad. README/docs now spell out resource key discipline.
+
+- **`each()` warns on duplicate keys (B7).** The positional-suffix fallback is
+  preserved so every item still renders, but duplicate keys now produce a
+  `warnOnce` diagnostic because they are almost always a data bug.
+
+- **API freeze map published (B8).** `docs/en/18-api-freeze-map.md` now defines
+  the stable root API, the public devtools subpath, and the internal modules
+  that are not protected by SemVer.
+
+- **Reactivity ordering contract published (B9).** `docs/en/19-reactivity-ordering.md`
+  documents signal/effect/batch ordering, nested-template update reuse and
+  component teardown timing. A new invariant test pins nested-batch effect
+  scheduling.
+
+- **v1 stability contract published (B10).** `docs/en/20-v1-stability.md`
+  defines what SemVer protects after v1 and what remains internal or
+  implementation-specific, including bundle byte output and internal module
+  layout.
+
+- **Agent and LLM guidance synced to the real API (B11).** `AGENTS.md`,
+  `.clinerules`, `.cursorrules` and `llms.txt` now document C7 parser hard
+  errors, C6 mutation concurrency, stateless `layout.view` wrappers, public
+  package imports and `bake` as a static meta-shell rather than SSR/SSG runtime.
+
+- **`mado init` writes required dev dependencies (B12).** Generated apps now
+  include `typescript`, `esbuild` and `linkedom` as dev dependencies, sourced
+  from the package's own tool versions. README/agent wording now says zero
+  **runtime** dependencies instead of implying no build tooling exists.
+
+- **Size budgets are enforced in CI (B13).** `npm run size` bundles the full
+  public API and the showcase app, then fails on gzip regressions above the
+  current budgets: public API < 16 KiB, showcase app < 42 KiB.
+
+- **Published tarball smoke test added (B14).** `npm run package:smoke` packs
+  the package, installs the tarball in a temp project, checks that public
+  imports work and `@madojs/mado/lifecycle.js` is blocked with
+  `ERR_PACKAGE_PATH_NOT_EXPORTED`, then scaffolds a clean app and runs
+  `mado release`.
+
+- **Release output is deterministic (B15).** `bake-stamp` was removed from baked
+  HTML, and the release pipeline test now runs `mado release` twice on the same
+  input and compares the entire `out/` tree byte-for-byte.
+
+- **LLM zero-history test is a CI smoke (B16).** `npm run llm:smoke` validates
+  that `llms.txt` retains the key Mado guidance, checks the committed
+  `examples/tickets` artifact for required APIs and forbidden React-shaped
+  patterns, then builds and runs the tickets smoke test.
+
+- **Localized docs synced for Phase B (B17).** RU/FR/UK docs now include the
+  API freeze map, reactivity ordering and v1 stability pages, plus the Phase B
+  updates for resource key discipline, deterministic bake metadata and the
+  LLM-smoke CI proxy.
+
+## 0.9.0 - 2026-06-12
+
+Correctness release from the v1 tracker Phase A: C1-C8 are closed with focused
+regression tests.
+
+### Changed
+
+- **`mutation().run()` is concurrent by default (C6).** Previously a `run()`
+  aborted any previous in-flight run, so two quick submits of different entities
+  through one mutation cancelled the first POST client-side — its `invalidates`
+  never fired even though the server had likely applied it. Mutations are now
+  concurrent: each `run()` has its own `AbortController`, `loading` is an
+  in-flight counter (true until the last run settles), and aborting the previous
+  run is opt-in via `mutation(fetcher, { abortPrevious: true })` for
+  search-as-you-type. `reset()` aborts all in-flight runs. **Behavioural change**
+  (done before the v1 API freeze). Regression test:
+  `test/mutation-concurrent.test.mjs`.
+
+### Fixed
+
+- **Lifecycle/router defect pack is closed (C8).** `onDispose()` registered
+  after a lifecycle was already disposed now runs immediately instead of being
+  dropped. SPA link interception now respects `target="_blank"` and `download`.
+  Same-path `#hash` navigation scrolls to its anchor instead of being swallowed
+  by signal deduplication. Guard redirects now have a per-tick loop detector
+  that reports and halts mutually-redirecting routes. Regression test:
+  `test/lifecycle-router-pack.test.mjs`.
+
+- **Parser fails loudly instead of silently dropping bindings (C7).** A `${}`
+  slot inside a RAW_TEXT element (`<textarea>`/`<title>`/`<style>`/`<script>`)
+  was silently ignored — an LLM writing `<textarea>${draft}</textarea>` got
+  neither an error nor a render. And a nested `html\`<path …>\`` for `<svg>` was
+  parsed in the HTML namespace, producing an invisible element. The parser now
+  throws a clear, fixable error in both cases (the RAW_TEXT message points at
+  `.value=`; the SVG message says to keep SVG content in one `<svg>…</svg>`
+  template). A self-contained `<svg>` still works. Regression test:
+  `test/html-rawtext-svg.test.mjs`.
+
+- **Forms: stale async validation no longer lands on a shifted field-array row
+
+
+  (C5).** `useForm().array()` mutations (`remove`/`move`/`replace`/…) shift
+  indices, but an in-flight `validateAsync` for e.g. `items.2.title` still
+  matched its per-path generation guard and wrote its result onto a row that had
+  moved — a red error "jumping" onto a neighbouring valid row after a delete.
+  Array writes now bump the validation generation for every in-flight path under
+  the array prefix, so stale results are discarded. Row identity remains
+  positional. Regression test: `test/forms-array-stale-async.test.mjs`.
+
+- **`computed({ equals })` no longer breaks `batch()` atomicity (C4).** An
+
+  observed `equals`-computed recomputed eagerly inside `set()`, so during
+  `batch(() => { x.set(2); y.set(2) })` a computed reading both `x` and `y` ran
+  on half-applied state `(new x, old y)` — observing an inconsistent snapshot,
+  potentially notifying with it, and running once per `set()`. An observed
+  `equals`-computed invalidated inside a batch now defers its recompute+compare
+  to a queue drained at the end of the outermost `batch()`, so it runs once on
+  fully-applied state. Behaviour outside a batch is unchanged. Regression test:
+  `test/signal-batch-equals.test.mjs`.
+
+- **`update()` reuses nested templates instead of recreating them (C3).** A
+
+  renderer returning a nested `html\`\`` (e.g. a conditional form block) rebuilt
+  its entire subtree on every change of any signal it read, because `renderChild`
+  always did clear + re-instantiate for a single `TemplateResult` — unlike
+  `each()` and `render()`, which compare `_strings` and patch in place. Focus and
+  `<input>` values inside such blocks were lost and listeners re-attached.
+  `renderChild` now reuses the existing instance via `update()` when the new
+  value is a single `TemplateResult` with matching `_strings`, preserving DOM
+  identity; a structurally different template still rebuilds. Regression test:
+  `test/update-nested-reuse.test.mjs`.
+
+- **`persisted()` cross-tab sync no longer ping-pongs, and `destroy()` is
+
+  complete (C2).** For object/array values, every cross-tab message produced a
+  new structured-clone identity, so the publisher effect re-broadcast each
+  received value forever (a single change generated 80+ messages in the
+  regression test). Cross-tab values are now echo-suppressed by their serialized
+  form, so an arriving value is never re-published. `destroy()` previously only
+  closed the channel and cleared storage while leaving the write/publish effects
+  alive — so the next `set()` re-created the key; it now disposes both effects,
+  clears the debounce timer, and marks the signal inert. `persisted()` also
+  registers `destroy()` with the active component/page lifecycle, so a persisted
+  signal created inside `setup()` no longer leaks. Regression test:
+  `test/persisted-crosstab.test.mjs`.
+
+- **`each()` reorder no longer destroys custom-element state (C1).** Moving a
+  connected node (which keyed `each()` does via `insertBefore`) fires
+  `disconnectedCallback` → `connectedCallback` synchronously, and the old
+
+  `disconnectedCallback` tore the component down immediately — re-running
+  `setup()` and wiping every signal/resource/timer plus focus and `<input>`
+  values on a shuffle. Teardown is now deferred to a microtask and cancelled if
+  the element is re-inserted in the same tick, so a keyed move preserves state;
+  a genuine removal still disposes. `each()` also uses `Node.prototype.moveBefore`
+  (Chrome 133+) when available, which relocates connected nodes without firing
+  lifecycle callbacks at all. Regression test: `test/each-component-state.test.mjs`.
+
+### Docs / planning
+
+
+- **Road to v1 re-sequenced around correctness.** Added
+  [`MADO_V1_TRACKER.md`](./MADO_V1_TRACKER.md), the active task-by-task tracker
+  derived from the `FABLE_REPORT.md` audit: phase A `v0.9` (correctness fixes
+  C1–C8, TDD: reproducing test → fix), phase B `v0.10` (surface cleanup, explicit
+  exports map, API freeze map), phase C `v1.0-rc` (live demo + external
+  dogfooding), phase D `v1.0` (freeze). `ROADMAP.md` now gates its
+  product-surface milestones behind a new "Milestone 0"; `TODO.md` points at the
+  tracker and drops items it now owns (exports policy, size reporting).
+
 
 ## 0.8.0