@madojs/mado 0.8.0 → 0.9.0

package/AGENTS.md

@@ -9,8 +9,9 @@
 
 ## Project at a glance
 
-- **Mado** — SPA framework built on Web Components + signals + tagged-template `html`.
-- No build system (only `tsc`), no runtime dependencies.
+- **Mado** — a calm browser-native SPA framework for internal tools, admin panels and business apps.
+- Built on Web Components + signals + tagged-template `html`.
+- No build system beyond `tsc`, no runtime dependencies.
 - Small TypeScript core in `src/`; bundled/minified full API is roughly 11 KB gzip.
 
 ## HARD RULES — violation = bug
@@ -119,7 +120,11 @@ 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 `observedAttributes` when available and a per-instance
+`MutationObserver` fallback for attributes registered during `setup()`. This is
+necessary because the browser reads `observedAttributes` once at
+`customElements.define()` time — before any instance calls `setup()`. The
+observer auto-disconnects on component removal via lifecycle cleanup.
 
 ### 5. Reactive value in template child position = function
 
@@ -202,6 +207,27 @@ 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")`.
+- **`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()`
 

package/CHANGELOG.md

@@ -2,7 +2,118 @@
 
 ## Unreleased
 
-Nothing yet.
+_No unreleased changes._
+
+## 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