@ultimat3/render 13.0.0 → 14.0.0

package/CLAUDE.md

@@ -61,8 +61,9 @@ for the mirror-image reason, keeping `render → pwa` refused. Never `cli` (upwa
 | The hydration runtime's CSP | `HYDRATE_RUNTIME_BODIES` — every body `hydrateRuntime` can emit, one per non-empty subset of the three strategies, seven in all. It is emitted INLINE in every document carrying an island, and `@ultimat3/http`'s `script-src` is `'self' 'wasm-unsafe-eval'`, so under the enforced policy a container serves (`dev: false`) **no island ever booted** — invisible in `x dev`, where the policy is report-only. `@ultimat3/cli`'s `script-csp.ts` hashes this list at boot, the mirror of `style-csp.ts`. Hashes and not a nonce, for `cspHashSource`'s own reason: a `render: 'static'` page is a file on disk. Never restate the concatenation — `runtimeBody` is the one place the served text and the hashed text are the same string. **Still uncovered**: `render-stream.ts`'s per-hole `<script>$X("id")</script>`, whose body is per-response and cannot be hashed. Unreachable today (`dev-render.ts` passes `holes: []`), and the first real hole needs a nonce, not a hash. |
 | Island markup | the props `<script>` is emitted INSIDE the wrapper by `render-html.ts`, so a document assembler has exactly one thing left to remember: `hydrateRuntime(directives)`. |
 | Island boot | `el.__x` holds the boot PROMISE, never a boolean. As a flag, a second interaction while the chunk was still loading got a resolved promise back and the replay queue flushed into an island that had not mounted — the events went nowhere and the listeners were already removed. |
-| Island mount markers | `data-x-mounted=""` when `mount()` RESOLVED, `data-x-failed="<message>"` when it rejected — set by the runtime, never by `emitIslandAttributes`, because the server does not know the answer. `el.__x` alone cannot carry this: it is assigned when `import()` is CALLED, so a chunk still downloading and one whose `mount()` threw were the same observable, and telling those apart is what `x shot` gates on. Two attributes rather than two values of one, so `[data-x-mounted]` never counts a failure as a success. The rejection handler RETHROWS — swallowing it resolves `el.__x` and the interaction runtime flushes its replay queue into an island that never mounted, which is the row above reintroduced one layer out. Costs 129 B of shared prelude: `idle` 774, `visible` 846, `interaction` 1,067 (`As of 2026-08-23`, the numbers `DEFAULT_ISLAND_JS_BYTES` is derived from). |
+| Island mount markers | `data-x-mounted=""` when `mount()` RESOLVED, `data-x-failed="<message>"` when it rejected — set by the runtime, never by `emitIslandAttributes`, because the server does not know the answer. `el.__x` alone cannot carry this: it is assigned when `import()` is CALLED, so a chunk still downloading and one whose `mount()` threw were the same observable, and telling those apart is what `x shot` gates on. Two attributes rather than two values of one, so `[data-x-mounted]` never counts a failure as a success. The rejection handler RETHROWS — swallowing it resolves `el.__x` and the interaction runtime flushes its replay queue into an island that never mounted, which is the row above reintroduced one layer out. Costs 129 B of shared prelude: `idle` 774, `visible` 846, `interaction` 1,251 (`As of 2026-08-25`, the numbers `DEFAULT_ISLAND_JS_BYTES` is derived from — `interaction` moved 1,067 -> 1,251 for the replay-target row below, and neither of the other two changed). |
 | A runtime that calls `boot` | TERMINATES the chain, because `boot` rethrows. `idle` and `visible` end in `.catch(hush)`; `interaction` passes `off` as the rejection arm of its `then`. A bare `boot(el)` produced a fresh rejected promise per call — one unhandled rejection per user event on an island whose `mount()` threw — and, on `interaction`, left `done` false, the listeners attached and the queue growing by one retained `Event` (each with a live `target`) per click, for an island that will never mount. Nothing is lost by swallowing here: the DOM already carries the failure as `data-x-failed`, which is the row above and the documented observable. `hydrate-runtime.test.ts` runs all three against a real module; Bun's runner fails a test on an unhandled rejection, so the omission reds the suite by itself. |
+| Where `interaction` replays | `aim(el, ev)` in `hydrate.ts`, never `ev.target`. Every island's `mount` opens with `el.textContent = ''` — the documented idiom, and what `settings`, `feed` and `like` all do — so the node the visitor pressed is DETACHED by the time the replay runs and `ev.target.dispatchEvent(c)` reached nothing: the first press did nothing and the second worked, which reads as a slow network and is never filed as a bug. `examples/dummy/apps/web/app/posts/[id]/page.tsx` declares `hydrate: 'idle'` in writing to avoid it. The runtime CAN tell the two mounts apart — `el.contains(ev.target)` AFTER the mount is the exact question — so this is a repair and not a refusal: refusing the pairing would delete a strategy that works today for a takeover-style island (`contact-sales.island.tsx` attaches to the server's own form and replaces nothing). Kept → the original target. Replaced → `document.elementFromPoint(ev.clientX, ev.clientY)`, which is where the event would land had the visitor pressed a moment later. The island ROOT is the last resort and never the repair: Solid's delegated listener sits on `document` and walks UP from the target (`solid-js/web`'s `eventHandler`), so a handler on a CHILD of the root is never visited and dispatching at the root fixes nothing for the canonical island. A hit landing outside this island falls back to the root too — synthesizing a click on an element the visitor never pressed is worse than losing the replay. `typeof ev.clientX === 'number'`, never `ev.clientX || ev.clientY`: (0, 0) is a coordinate. `hydrate-replay.test.ts` holds it, and it is a separate file because `hydrate-runtime.test.ts`'s element is BOTH the island root and every event's target — the two answers are the same node there, which is how this survived. |
 | `idle`'s deadline | `IDLE_HYDRATE_TIMEOUT_MS`, interpolated INTO the runtime string. Exported because a second reader has to agree — `x shot` waits before it photographs, and a settle shorter than this deadline reports an unhydrated page for one that hydrates perfectly. A constant the emitted string restates instead of reading is worse than no constant. |
 | Route truth | `registry.ts`. Never keep a second route list anywhere, and never a second *matcher*: this package's `matchRoute` was deleted in 2026-08 with zero consumers, because `@ultimat3/http`'s trie (`stages.ts`) is the one that serves requests and two matchers with different precedence rules is two answers to "which route is this?". `routeFor` is an exact-path `Map` lookup, not a pattern matcher. |
 | Route filename | `page.tsx` under `site/`/`app/`, `route.ts` under `api/` — `ROUTE_FILENAME`, one per surface. The URL is the directory path. Anything else is `X_ROUTE_FILE_INVALID`; never widen the table to accept a second spelling. |

package/README.md

@@ -198,27 +198,29 @@ production Solid, `As of 2026-08`:
 | `render(() => <p>hello</p>, el)` — the floor, before an author writes a line | 12,588 |
 | a signal, a button and reactive text | 13,663 |
 | `settings.island.tsx`, the heaviest island this repo ships | 17,797 |
-| one directive's hydration runtime at `hydrate: 'idle'` | 615 |
-| the same at `'interaction'`, which is what an island route declaring no `hydrate` gets | 881 |
+| one directive's hydration runtime at `hydrate: 'idle'` | 774 |
+| the same at `'interaction'`, which is what an island route declaring no `hydrate` gets | 1,251 |
 
-17,797 + 881 = **18,678** — the heaviest island this repo ships, plus the runtime an app pays
+17,797 + 1,251 = **19,048** — the heaviest island this repo ships, plus the runtime an app pays
 without writing a number down. `DEFAULT_ISLAND_HYDRATE` is `'interaction'`
 ([`route.ts:33`](src/route.ts)), applied at `:253` to any island route that states no `hydrate`, so
-`idle`'s 615 is the cheaper case and not the one a budget has to clear.
+`idle`'s 774 is the cheaper case and not the one a budget has to clear.
 
 The default is **20,480** (20kb), which is not that number rounded: the next whole kilobyte above
-it is 19,456, and clearing today's worst island by 778 bytes is a ceiling the next line anyone
-writes breaks. 20kb leaves 1,802 B, and stays under 2× 18,678 — so a route that bundles the same
+it is 19,456, and clearing today's worst island by 408 bytes is a ceiling the next line anyone
+writes breaks. 20kb leaves 1,432 B, and stays under 2× 19,048 — so a route that bundles the same
 island twice is still refused. All three clauses are assertions in
-[`modes.test.ts`](src/modes.test.ts)'s `DEFAULT_ISLAND_JS_BYTES` block, against the measured
-table above; a default that stopped clearing the floor, or stopped being a ceiling, is red.
+[`island-budget.test.ts`](src/island-budget.test.ts)'s `DEFAULT_ISLAND_JS_BYTES` block, against the
+measured table above; a default that stopped clearing the floor, or stopped being a ceiling, is red.
 
 It was **4kb** until `As of 2026-08`, sized from `contact-sales.island.tsx` — 875 B of chunk, and
 no `solid-js` import anywhere in it. Calibrating a JSX budget on the one island shape that does not
 pay the JSX runtime put the default a factor of three below the floor of every island that does:
 no `budget.js` under 4096 was reachable on any surface, because the allowance is measured ABOVE the
 baseline and not against it. (Its second number was wrong too — one directive's hydration runtime
-is 615 B at `idle` and 881 B at `interaction`, never 1,019.)
+was 615 B at `idle` and 881 B at `interaction` when that default was set, never 1,019. The table
+above is what it measures today: the runtime has grown three times since, for the mount markers,
+for terminating the chain `boot` starts, and for aiming the replay.)
 
 Still a ceiling and not a pass: exceeding it is `X_BUDGET_EXCEEDED`, naming the island. An island
 that pulls a design system in — `@ultimat3/ui`'s `<Switch>` measures 36,335 B — writes its own
@@ -385,7 +387,12 @@ side effect. Anything that loads an app's source — `x dev`, `x build`, `server
   is handed an `AbortSignal` so the work stops, and nothing more is enqueued. Solid's compiled templates and signals mean the shell costs zero
   hydration work, so streaming buys TTFB *and* TBT here, not just TTFB.
 - **`hydrate: 'interaction'`** replays the event that woke the island; without replay the
-  first click on a cold island is silently lost.
+  first click on a cold island is silently lost. It replays onto a node the mount left standing —
+  the original target when the mount kept it, otherwise whatever `elementFromPoint` now answers for
+  a pointer event, otherwise the island root. An island's `mount` opens with `el.textContent = ''`,
+  so the pressed node is usually gone by the time the replay runs, and dispatching at it reached
+  nothing: `hydrate: 'interaction'` is usable with a replacing island, and was not until
+  `As of 2026-08-25`.
 - **`hydrate: 'never'`** emits no attributes beyond the marker and no runtime — the `site/`
   0kb default is mechanical, not aspirational. A page that renders an island anyway is
   `X_ISLAND_NOT_HYDRATED`, not a silently dead button.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/render",
-  "version": "13.0.0",
+  "version": "14.0.0",
   "description": "The route primitive and the five render modes: static, isr, ssr, stream, spa.",
   "license": "MIT",
   "type": "module",
@@ -36,10 +36,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "13.0.0",
-    "@ultimat3/core": "13.0.0",
-    "@ultimat3/i18n": "13.0.0",
-    "@ultimat3/seo": "13.0.0",
+    "@ultimat3/cache": "14.0.0",
+    "@ultimat3/core": "14.0.0",
+    "@ultimat3/i18n": "14.0.0",
+    "@ultimat3/seo": "14.0.0",
     "sass": "1.102.0"
   }
 }

package/src/hydrate.ts

@@ -148,6 +148,27 @@ io.observe(el)})
 // woke the island, and re-dispatches it once mounted. Without this, the first click on a
 // cold island is silently lost — the failure users read as "the button does nothing".
 //
+// `aim` is WHERE it is re-dispatched, and it is not `ev.target`. An island's `mount` opens with
+// `el.textContent = ''` — the documented idiom, and what `settings`, `feed` and `like` all do — so
+// by the time the replay runs, the node the visitor actually pressed has been detached and a
+// `dispatchEvent` on it reaches nothing: "the button does nothing on the first press, and works on
+// the second", which is indistinguishable from a slow network and is never reported as a bug.
+//
+// The runtime CAN tell the two mounts apart, per event, and that is what makes a repair possible
+// instead of a refusal: `el.contains(ev.target)` after the mount answers "did this mount keep the
+// node I caught the event on". Kept → replay there, which is what a takeover-style island
+// (`contact-sales.island.tsx` attaches to the server's own form) needs.
+//
+// Replaced → the honest target is where the event would land NOW, so a pointer event is
+// hit-tested again with `elementFromPoint`. That is the same answer the browser would have given
+// had the visitor pressed a moment later, and it reaches a fresh descendant's own handler —
+// dispatching at the island ROOT does not, because Solid's delegated listener sits on `document`
+// and walks UP from the target (`solid-js/web`'s `eventHandler`), so a handler on a child of the
+// root is never visited. The root is the last resort, not the repair: it is where an event with no
+// coordinates goes (a `keydown` has no `clientX`), and where a hit landing outside this island goes
+// — synthesizing a click on an element the visitor never pressed is worse than losing the replay.
+// `typeof` and not `ev.clientX||ev.clientY`, because (0, 0) is a coordinate.
+//
 // `off` is BOTH arms of the `then`, and the rejection arm is the reason it is a named function.
 // `boot` rethrows on purpose (see the prelude), so `el.__x` holds a rejected promise from the
 // first failed mount onward — and a `.then` with no rejection handler makes a fresh rejected
@@ -157,13 +178,16 @@ io.observe(el)})
 // will never mount. Swallowing here loses no signal: the DOM already carries the failure as
 // `data-x-failed`, which is the documented observable.
 const RUNTIME_INTERACTION = `
+function aim(el,ev){var t=ev.target;if(t&&el.contains(t))return t;
+var x=ev.clientX,h=typeof x==='number'?document.elementFromPoint(x,ev.clientY):null;
+return h&&el.contains(h)?h:el}
 each('[data-x-hydrate="interaction"]',function(el){
 var evs=(el.getAttribute('data-x-events')||'click').split(' ');
 var q=[],done=false;
 var off=function(){done=true;evs.forEach(function(n){el.removeEventListener(n,on,true)});q=[]};
 var on=function(ev){if(done)return;q.push(ev);
 boot(el).then(function(){var r=q;off();
-r.forEach(function(ev){var c=new ev.constructor(ev.type,ev);ev.target.dispatchEvent(c)})},off)};
+r.forEach(function(ev){var c=new ev.constructor(ev.type,ev);aim(el,ev).dispatchEvent(c)})},off)};
 evs.forEach(function(n){el.addEventListener(n,on,true)})})
 `.trim();
 

package/src/modes.ts

@@ -225,12 +225,12 @@ export function defaultHydrate(surface: Surface): HydrateStrategy {
  * (`settings.island.tsx`) is 17,797 B. No `budget.js` under 4096 was reachable by any of them, on
  * any surface, because the allowance is measured above the baseline and not against it.
  *
- * The number: 17,797 (the heaviest island this repo actually ships) + 1,067 (`hydrateRuntimeBytes`
+ * The number: 17,797 (the heaviest island this repo actually ships) + 1,251 (`hydrateRuntimeBytes`
  * for one directive at `DEFAULT_ISLAND_HYDRATE`, which is `'interaction'` — `route.ts:33`, applied
- * at `:253` to any island route declaring no `hydrate`) = **18,864**. That is the worst case an
+ * at `:253` to any island route declaring no `hydrate`) = **19,048**. That is the worst case an
  * app reaches without writing a number down. 20,480 is NOT that rounded up — the next whole
- * kilobyte above it is 19,456 — it is one whole kB further, leaving 1,616 B of headroom and still
- * under 2x 18,864, so a route bundling the same island twice is refused. `island-budget.test.ts`
+ * kilobyte above it is 19,456 — it is one whole kB further, leaving 1,432 B of headroom and still
+ * under 2x 19,048, so a route bundling the same island twice is refused. `island-budget.test.ts`
  * asserts all three. `idle` costs 774 and `visible` 846, so an island route that declares its
  * strategy pays less; the default is what the budget has to clear.
  *
@@ -238,8 +238,10 @@ export function defaultHydrate(surface: Surface): HydrateStrategy {
  * mount's OUTCOME so `x shot` can tell an island that RAN from one that only started loading, and
  * again on 2026-08-23 — +18 B in the shared prelude (`hush`) for all three, +39 B more on
  * `interaction` — when each runtime learned to TERMINATE the promise chain `boot` starts rather
- * than emit one unhandled rejection per user event. The headroom absorbed both and the conclusion
- * is unchanged, which is the point of stating the
+ * than emit one unhandled rejection per user event. `interaction` alone grew a third time on
+ * 2026-08-25 (+184 B, `aim`), when the replay learned that the node it was dispatching at had been
+ * detached by the mount it was waiting for. The headroom absorbed all three and the conclusion is
+ * unchanged, which is the point of stating the
  * arithmetic here rather than the answer alone. It is not
  * derived from Solid's own size on purpose — this package may not import or name `solid-js`
  * (`CLAUDE.md`), so a constant tracking the runtime's version would be a dependency in a comment.