@ultimat3/render 23.0.0 → 25.0.0

package/src/html.ts

@@ -1,11 +1,11 @@
 /**
- * HTML text and attribute serialization for the server renderer. Escaping lives here and only
- * here: a second escaper is how one of them ends up missing a character, and a missing character
- * in an attribute is an injection.
+ * HTML text and attribute serialization for the server renderer. The character table is
+ * `@ultimat3/core`'s `escapeHtml`, imported from core by every render-* file: a second escaper is
+ * how one of them ends up missing a character, and a missing character in an attribute is an
+ * injection (`X_HELPER_COPY` refuses both a copy and a re-export).
  */
 
-import { safeUrl, URL_ATTRIBUTES } from '@ultimat3/core';
-import { escapeAttribute } from '@ultimat3/seo';
+import { escapeHtml, safeUrl, URL_ATTRIBUTES } from '@ultimat3/core';
 import type { JsxProps } from './jsx';
 
 /** Elements that never carry children, so the writer must not emit a closing tag. */
@@ -26,21 +26,9 @@ export const VOID_ELEMENTS: ReadonlySet<string> = new Set([
   'wbr',
 ]);
 
-export function escapeText(value: string): string {
-  return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
-}
-
-/**
- * Re-exported, never re-implemented: `@ultimat3/seo` (tier 1) owns the one attribute escaper, and
- * the copy that lived here was a second place for a character to go missing. It stays reachable
- * from `./html` so this module remains the single import site every render-* file already uses —
- * one implementation, one place to look.
- */
-export { escapeAttribute };
-
 /**
  * `<script>` and `<style>` hold RAW TEXT: a character reference is not decoded inside them, so
- * `escapeText` there would ship `&lt;` to a JS or CSS parser and corrupt the code without closing
+ * `escapeHtml` there would ship `&lt;` to a JS or CSS parser and corrupt the code without closing
  * the hole. What actually ends the element is `</` followed by its tag name, and — inside a script
  * only — `<!--` switches the tokenizer into the escaped state where the element's own `</script>`
  * no longer closes it and the rest of the document becomes script text.
@@ -113,7 +101,7 @@ const URL_BEARING_ATTRIBUTES: ReadonlySet<string> = new Set([
 
 /**
  * Attributes that carry MARKUP, not text or a URL, and are therefore never emitted. `srcdoc` is
- * entity-DECODED and then parsed as HTML, so `escapeAttribute`'s `&lt;script&gt;` becomes a live
+ * entity-DECODED and then parsed as HTML, so an escaped `&lt;script&gt;` becomes a live
  * `<script>` inside the iframe — on this origin, with this session's cookie. Escaping cannot make
  * it inert, so the attribute is refused instead, the same way `innerHTML` above stays the one
  * explicit escape hatch rather than a prop anyone can spread in from a row.
@@ -167,7 +155,7 @@ export function attributePair(name: string, value: unknown): string | null {
   if (value === true) return attribute;
   if (attribute === 'style') {
     const style = styleValue(value);
-    return style === null ? null : `style="${escapeAttribute(style)}"`;
+    return style === null ? null : `style="${escapeHtml(style)}"`;
   }
   const text = String(value);
   // Escaping makes a value inert inside the quotes; it cannot make a SCHEME inert, because
@@ -178,9 +166,9 @@ export function attributePair(name: string, value: unknown): string | null {
   if (URL_BEARING_ATTRIBUTES.has(attribute.toLowerCase())) {
     const url = safeUrl(text, attribute.toLowerCase());
     if (url === null) return null;
-    return `${attribute}="${escapeAttribute(url)}"`;
+    return `${attribute}="${escapeHtml(url)}"`;
   }
-  return `${attribute}="${escapeAttribute(text)}"`;
+  return `${attribute}="${escapeHtml(text)}"`;
 }
 
 export function renderAttributes(props: JsxProps): string {

package/src/hydrate.ts

@@ -6,8 +6,9 @@
  */
 
 import type { HydrateStrategy } from '@ultimat3/core';
-import { HYDRATE_STRATEGIES } from '@ultimat3/core';
-import { escapeAttribute, escapeJsonContent } from './html';
+import { escapeHtml, HYDRATE_STRATEGIES } from '@ultimat3/core';
+import { escapeJsonContent } from './html';
+import { ISLAND_HOLD_ATTRIBUTES, RUNTIME_HOLD } from './island-hold';
 
 export interface IslandDirective {
   /** Unique per INSTANCE: two of the same island on a page need two prop bags to find. */
@@ -26,6 +27,11 @@ export interface IslandDirective {
   readonly events?: readonly string[];
   /** `rootMargin` for `visible`. */
   readonly rootMargin?: string;
+  /**
+   * The server markup must not paint before the island mounts (`island-hold.ts`, #506): hidden
+   * from its first byte, booted at once, revealed by the mount or the cap. Never on `never`.
+   */
+  readonly hold?: boolean;
 }
 
 export const DEFAULT_REPLAY_EVENTS = ['click', 'input', 'change', 'submit', 'keydown'] as const;
@@ -61,7 +67,7 @@ export function emitIslandAttributes(directive: IslandDirective): string {
   // and the rest of the string is markup. Author-controlled today — which is why it costs nothing
   // to route through the ONE escaper now, rather than after a build id or a prop-derived margin
   // starts carrying something the author did not type.
-  const attr = (name: string, value: string): string => `${name}="${escapeAttribute(value)}"`;
+  const attr = (name: string, value: string): string => `${name}="${escapeHtml(value)}"`;
   const attrs = [
     attr('data-x-island', directive.islandId),
     attr('data-x-hydrate', directive.strategy),
@@ -74,6 +80,8 @@ export function emitIslandAttributes(directive: IslandDirective): string {
     if (directive.events !== undefined && directive.events.length > 0) {
       attrs.push(attr('data-x-events', directive.events.join(' ')));
     }
+    // A constant, so it needs no escaper — and nothing a caller supplies reaches it.
+    if (directive.hold === true) attrs.push(ISLAND_HOLD_ATTRIBUTES);
   }
   return attrs.join(' ');
 }
@@ -89,7 +97,7 @@ export function emitIslandProps(directive: IslandDirective): string {
     // The id goes through the SAME escaper every other attribute in this file does. Safe today —
     // `islandModuleId` reduces to `[a-z0-9-]` — which is exactly why it costs nothing to route it
     // now, rather than after an id starts being derived from something an author did not type.
-    `<script type="application/json" data-x-props="${escapeAttribute(directive.islandId)}">` +
+    `<script type="application/json" data-x-props="${escapeHtml(directive.islandId)}">` +
     `${escapeJsonContent(JSON.stringify(directive.props))}</script>`
   );
 }
@@ -205,6 +213,9 @@ io.observe(el)})
 // `go` chains on the same `el.__x`, and the first flush empties `q` and sets `done`, so however many
 // ran, each caught event is replayed exactly once and an untouched island still lets go of its
 // listeners at mount — a listener left behind would replay every later click a second time.
+// An island something ELSE booted (a held island: `island-hold.ts` boots it at once) had no flush
+// to let go in, so `on` checks the mount marker — set in the same `.then` that settles `el.__x` —
+// and detaches instead of queueing: the press reaches its target natively, once.
 const RUNTIME_CATCH_UP = `
 function path(el,t){var p=[t&&t.tagName];
 for(;t&&t!==el&&t.parentNode;t=t.parentNode)p.unshift(Array.prototype.indexOf.call(t.parentNode.children,t));
@@ -219,7 +230,8 @@ var q=[],done=false;
 var off=function(){done=true;evs.forEach(function(n){el.removeEventListener(n,on,true)});q=[]};
 var go=function(){boot(el).then(function(){var r=q;off();
 r.forEach(function(e){var ev=e[0],c=new ev.constructor(ev.type,ev);aim(el,ev,e[1]).dispatchEvent(c)})},off)};
-var on=function(ev){if(done)return;q.push([ev,path(el,ev.target)]);go()};
+var on=function(ev){if(done)return;if(el.getAttribute('${ISLAND_MOUNTED_ATTRIBUTE}')!==null){off();return}
+q.push([ev,path(el,ev.target)]);go()};
 evs.forEach(function(n){el.addEventListener(n,on,true)});return go}
 `.trim();
 
@@ -249,9 +261,14 @@ const RUNTIME_ORDER: readonly Exclude<HydrateStrategy, 'never'>[] = HYDRATE_STRA
  * moment the runtime changes, and the failure it produces is an island that never boots on a page
  * that otherwise looks correct.
  */
-const runtimeBody = (needed: ReadonlySet<Exclude<HydrateStrategy, 'never'>>): string =>
+const runtimeBody = (
+  needed: ReadonlySet<Exclude<HydrateStrategy, 'never'>>,
+  held: boolean,
+): string =>
   [
     RUNTIME_PRELUDE,
+    // Right after the prelude: no strategy part below that throws can strand a held island.
+    ...(held ? [RUNTIME_HOLD] : []),
     // Emitted once for whichever of the two catch-up strategies the page uses; a `visible`-only
     // page never pays for it.
     ...(needed.has('idle') || needed.has('interaction') ? [RUNTIME_CATCH_UP] : []),
@@ -260,18 +277,22 @@ const runtimeBody = (needed: ReadonlySet<Exclude<HydrateStrategy, 'never'>>): st
     ),
   ].join('\n');
 
+/** Whether any island the runtime boots is held — a `never` island boots nothing to reveal it. */
+const holds = (directives: readonly IslandDirective[]): boolean =>
+  directives.some((directive) => directive.hold === true && directive.strategy !== 'never');
+
 /**
- * Every body `hydrateRuntime` can emit: one per non-empty subset of the three strategies, seven in
- * all, deterministic. A policy that admits inline script by HASH has to enumerate them before the
+ * Every body `hydrateRuntime` can emit: one per non-empty subset of the three strategies, with and
+ * without a held island — fourteen in all, deterministic. A policy that admits inline script by HASH has to enumerate them before the
  * socket opens — the alternative is a per-response nonce, which a `render: 'static'` page (a file
  * on disk) can never receive. Enumerated rather than derived from the route table because the
  * runtime is a function of the SET a document needs, and a table read at boot cannot answer for
  * a document assembled later.
  */
-export const HYDRATE_RUNTIME_BODIES: readonly string[] = Array.from(
-  { length: 2 ** RUNTIME_ORDER.length - 1 },
-  (_unused, index) =>
-    runtimeBody(new Set(RUNTIME_ORDER.filter((_s, bit) => (((index + 1) >> bit) & 1) === 1))),
+export const HYDRATE_RUNTIME_BODIES: readonly string[] = [false, true].flatMap((held) =>
+  Array.from({ length: 2 ** RUNTIME_ORDER.length - 1 }, (_unused, index) =>
+    runtimeBody(new Set(RUNTIME_ORDER.filter((_s, bit) => (((index + 1) >> bit) & 1) === 1)), held),
+  ),
 );
 
 /**
@@ -281,7 +302,7 @@ export const HYDRATE_RUNTIME_BODIES: readonly string[] = Array.from(
 export function hydrateRuntime(directives: readonly IslandDirective[]): string {
   const needed = requiredStrategies(directives);
   if (needed.size === 0) return '';
-  return `<script type="module">${runtimeBody(needed)}</script>`;
+  return `<script type="module">${runtimeBody(needed, holds(directives))}</script>`;
 }
 
 /** Rough emitted size of the hydration runtime for a page, for the budget check. */

package/src/index.ts

@@ -5,26 +5,21 @@
  */
 
 /**
- * The route vocabulary is declared once, at tier 0 (`@ultimat3/core`), and re-exported here
- * because `defineRoute`, `MODE_SPECS`, `surfaceAllows` and `RouteDescriptor` all take these types
- * in their signatures: a consumer calling this package's API should not need a second import to
- * name its arguments. A re-export is not a declaration — `scripts/render-modes.test.ts` refuses a
- * second declaration, which is what makes re-exporting safe where copying was not.
+ * The route vocabulary is declared once, at tier 0 (`@ultimat3/core`). Its TYPES are re-exported
+ * here because `defineRoute`, `MODE_SPECS`, `surfaceAllows` and `RouteDescriptor` take them in
+ * their signatures; its VALUES (`RENDER_MODES`, `HYDRATE_STRATEGIES`, `OFFLINE_STRATEGIES`) and
+ * `formatBytes` are imported from core by every caller — a value re-export is a second import path
+ * (`X_HELPER_COPY`, `bun run flight-copies`). Nor are core's page-meta names (`CLIENT_*_META`)
+ * re-published beside the tag writers below.
  */
 export type { HydrateStrategy, OfflineStrategy, RenderMode } from '@ultimat3/core';
-// `formatBytes` moved to `@ultimat3/core` (one formatter, with the `mb` branch this package's copy
-// never had); still named here because `@ultimat3/cli`'s budget reporter reads it beside the route
-// table it prints against.
-export { formatBytes, HYDRATE_STRATEGIES, OFFLINE_STRATEGIES, RENDER_MODES } from '@ultimat3/core';
 /** `asset('assets/x.avif')` → the content-hashed URL the site asset surface serves it at. */
 export type { AssetExtension, AssetPath, AssetResolver } from './asset';
 export { ASSET_DIR, ASSET_EXTENSIONS, asset, assetPathProblem, setAssetResolver } from './asset';
 /** The `<meta name="ultimate-path-style">` core's `actionPath` reads — a non-default style only. */
-export { CLIENT_PATH_STYLE_META, clientPathStyleTags } from './client-path-style-tag';
+export { clientPathStyleTags } from './client-path-style-tag';
 /** The `<meta name="ultimate-scope">` core's `pageClient()` reads, on private documents only. */
 export {
-  CLIENT_PERSIST_META,
-  CLIENT_SCOPE_META,
   clientPersistTags,
   clientScopeTag,
   documentCarriesScope,
@@ -32,9 +27,6 @@ export {
 /** Where the page's one socket dials, and the worker that hosts it (plan 101, slice 11). */
 export type { ClientSyncHead } from './client-sync-tags';
 export {
-  CLIENT_BUILD_META,
-  CLIENT_SYNC_META,
-  CLIENT_SYNC_WORKER_META,
   clientBootTags,
   clientSyncTags,
 } from './client-sync-tags';
@@ -75,7 +67,6 @@ export {
   headFromMeta,
   mergeHead,
   renderHead,
-  THEME_STORAGE_KEY,
   themeScript,
   themeScriptBody,
 } from './head';
@@ -99,7 +90,8 @@ export {
   islandModuleId,
 } from './island';
 export type { IslandCollector, IslandCollectorInput } from './island-collector';
-export { createIslandCollector, islandModuleIds } from './island-collector';
+export { islandCollector, islandModuleIds } from './island-collector';
+export { ISLAND_HOLD_ATTRIBUTE, ISLAND_HOLD_MS, ISLAND_HOLD_REVEAL } from './island-hold';
 export type { IslandProps, JsonValue } from './island-props';
 export { ISLAND_PROPS_MAX_BYTES } from './island-props';
 export { parseByteBudget } from './islands';
@@ -137,8 +129,6 @@ export {
   NAVIGATING_ATTRIBUTE,
   NAVIGATION_CACHE_TTL_MS,
   NAVIGATION_ERROR_EVENT,
-  NAVIGATION_HEADER,
-  NAVIGATION_LOCATION_HEADER,
   NAVIGATION_MAX_HOPS,
   NAVIGATION_META,
   NAVIGATION_NO_PREFETCH_ATTRIBUTE,
@@ -147,15 +137,12 @@ export {
   NAVIGATION_PREFETCH_DELAY_MS,
   NAVIGATION_PROGRESS_DELAY_MS,
   NAVIGATION_RELOAD_ATTRIBUTE,
-  NAVIGATION_SCOPE_HEADER,
-  NAVIGATION_SURFACE_HEADER,
   responseVerdict,
   reusable,
 } from './navigation-rules';
 export type { ClientNavigationHead } from './navigation-tags';
 export { clientNavigationTags } from './navigation-tags';
 export type {
-  CompiledPattern,
   MountedRouteInput,
   RegisterRouteInput,
   RouteDescriptor,
@@ -165,8 +152,7 @@ export type {
 } from './registry';
 export {
   clearRoutes,
-  compilePattern,
-  describeRoutes,
+  describePages,
   ROUTE_FILENAME,
   registerMountedRoutes,
   registerRoute,
@@ -200,11 +186,12 @@ export {
   defineRoute,
   isRouteConfig,
   ROUTE_NAVIGATION_MODES,
-  tagKeys,
 } from './route';
 export type { RouteComponent } from './route-component';
 export { pageComponentOf } from './route-component';
 export { metaContextFor, routeDataFor } from './route-data';
+export type { CompiledPattern } from './route-pattern';
+export { compilePattern } from './route-pattern';
 export { routeStatusOf, withStatus } from './route-status';
 export type { SpeculationRules } from './speculation-rules';
 export {

package/src/island-collector.ts

@@ -5,6 +5,7 @@
  */
 
 import type { HydrateStrategy } from '@ultimat3/core';
+import { renderCauseValue } from '@ultimat3/core';
 import { IslandInvalidError, IslandNotHydratedError } from './errors';
 import type { IslandDirective } from './hydrate';
 import { DEFAULT_REPLAY_EVENTS } from './hydrate';
@@ -28,6 +29,12 @@ export interface IslandCollectorInput {
   readonly hydrate: HydrateStrategy;
   /** Specifier → built chunk URL. Identity in dev and in tests; the build supplies the real one. */
   readonly resolve?: (src: string) => string;
+  /**
+   * Which islands (by `src`, as the page wrote it) must not paint their server markup before they
+   * mount (`island-hold.ts`). The caller's to answer — the renderer cannot see what an island's
+   * graph imports. Absent, nothing is held.
+   */
+  readonly hold?: (src: string) => boolean;
 }
 
 /**
@@ -42,7 +49,7 @@ export interface IslandCollector {
   record(spec: IslandSpec, props: JsxProps): IslandDirective;
 }
 
-export function createIslandCollector(input: IslandCollectorInput): IslandCollector {
+export function islandCollector(input: IslandCollectorInput): IslandCollector {
   const directives: IslandDirective[] = [];
   const entries = new Map<string, string>();
   const resolve = input.resolve ?? ((src: string) => src);
@@ -71,7 +78,8 @@ export function createIslandCollector(input: IslandCollectorInput): IslandCollec
 
       const bag = checkIslandProps(props, spec.propKeys, input.file, spec.moduleId);
       const instance = directives.filter((d) => d.moduleId === spec.moduleId).length + 1;
-      const directive = buildDirective(spec, strategy, entry, `${spec.moduleId}-${instance}`, bag);
+      const built = buildDirective(spec, strategy, entry, `${spec.moduleId}-${instance}`, bag);
+      const directive = input.hold?.(spec.src) === true ? { ...built, hold: true } : built;
       directives.push(directive);
       return directive;
     },
@@ -131,9 +139,9 @@ function assertHydrates(strategy: HydrateStrategy, spec: IslandSpec, file: strin
 function assertEntry(entry: string, spec: IslandSpec, file: string): void {
   if (isEmittableSpecifier(entry)) return;
   throw new IslandInvalidError(
-    `the resolver returned ${JSON.stringify(entry)} for the ${spec.moduleId} island in ${file}, ` +
+    `the resolver returned ${renderCauseValue(entry)} for the ${spec.moduleId} island in ${file}, ` +
       'which cannot be emitted as a module URL',
-    'fix the resolve() passed to createIslandCollector — it must return a plain URL path',
+    'fix the resolve() passed to islandCollector — it must return a plain URL path',
   );
 }
 
@@ -142,7 +150,7 @@ export function islandWithoutCollector(spec: IslandSpec): IslandNotHydratedError
   return new IslandNotHydratedError(
     `the ${spec.moduleId} island was rendered outside a render that collects islands, so no ` +
       'hydration runtime is emitted and its chunk is never requested',
-    'render the page through renderToHtml(tree, { islands: createIslandCollector({ file, ' +
+    'render the page through renderToHtml(tree, { islands: islandCollector({ file, ' +
       'hydrate }) }) so the island is counted, booted and budgeted',
   );
 }

package/src/island-hold.ts

@@ -0,0 +1,56 @@
+// A HELD island (#506): server markup that must not paint before the island mounts, because what
+// it shows can be older than what the page will show — an offline reload's cached count, under a
+// queued write the mount rebuilds. Hidden from its first byte, booted at once, revealed when the
+// mount settles or at the cap. Who is held is the renderer's caller's call (`hold` on the collector).
+
+/** On a held island's wrapper until the runtime reveals it; what the runtime finds it by. */
+export const ISLAND_HOLD_ATTRIBUTE = 'data-x-hold';
+
+/**
+ * The longest a held island stays hidden, whatever its chunk does — a download on a slow network,
+ * a mount that never settles. Above `@ultimat3/realtime`'s `FIRST_PAINT_HOLD_MS` (1 s), the cap on
+ * the disk restore a realtime island waits for, so a slow disk meets that cap and still mounts
+ * before this one shows the server's markup. Interpolated into the runtime: one number, one copy.
+ */
+export const ISLAND_HOLD_MS = 3_000;
+
+/**
+ * The keyframes that reveal a held island with no script at all — JS off, the runtime blocked, a
+ * strategy part that threw before the hold could run. Defined in `@ultimat3/ui`'s `global.scss`
+ * (this package may not import `ui`; `island-hold-replay.test.ts` holds the two spellings equal).
+ */
+export const ISLAND_HOLD_REVEAL = 'ultimate-hold-reveal';
+
+/**
+ * The wrapper's attributes. An inline `style` and not a stylesheet rule: it applies from the byte
+ * the parser reads (no sheet can have loaded yet), and `@ultimat3/http`'s policy admits a style
+ * ATTRIBUTE (`style-src-attr`) where an inline `<style>` would need a hash. `visibility`, never
+ * `display`: the island keeps its box, so the reveal shifts no layout. The animation is the reveal
+ * that needs no script: a zero-length step to `visible` after the cap, held by `forwards` (reduced
+ * motion shortens durations, never delays). The runtime takes both properties off when it reveals.
+ */
+export const ISLAND_HOLD_ATTRIBUTES =
+  `${ISLAND_HOLD_ATTRIBUTE} ` +
+  `style="visibility:hidden;animation:${ISLAND_HOLD_REVEAL} 0s ${ISLAND_HOLD_MS}ms forwards"`;
+
+// Booted at once, whatever the route's strategy: a hidden island receives no press and sits in no
+// idle slot worth waiting for, so `interaction` would hold it until the cap and show the stale
+// markup anyway. `boot` is the prelude's, so the strategy below chains on the SAME `el.__x` and
+// mounts nothing twice. `el.__h`, not `each`'s `el.__v`: `each` would mark the root visited and
+// the strategy's own pass would then skip it. Emitted FIRST after the prelude (`hydrate.ts`), so
+// a strategy part that throws — an old WebView with no IntersectionObserver — cannot strand it.
+// The strategy's capture listeners let go on the first event after the mount (`catchUp`'s `on`),
+// since the hold, not a caught event, is what booted the island.
+//
+// Revealed TOGETHER, once every held island of this pass has settled (or at the cap): one record
+// shown in two islands is rebuilt by whichever island holds its writer — a queued write's overlay
+// is restored inside THAT island's mount — so a reader revealed at its own mount painted the
+// record without it (#506, measured in `offline-like.e2e.test.ts`). A failed mount counts as
+// settled (`hush`): its server markup is shown rather than hidden forever.
+export const RUNTIME_HOLD = `
+var hs=[];Array.prototype.forEach.call(document.querySelectorAll('[${ISLAND_HOLD_ATTRIBUTE}]'),function(el){
+if(!el.__h){el.__h=1;hs.push(el)}});
+if(hs.length){var t,r=function(){clearTimeout(t);hs.forEach(function(el){el.removeAttribute('${ISLAND_HOLD_ATTRIBUTE}');
+el.style.removeProperty('visibility');el.style.removeProperty('animation')})};
+t=setTimeout(r,${ISLAND_HOLD_MS});Promise.all(hs.map(function(el){return boot(el).then(null,hush)})).then(r)}
+`.trim();

package/src/island-props.ts

@@ -173,7 +173,7 @@ export function checkIslandProps(
         'and every one of them ships inside the HTML on every request — ' +
         heaviest.map(([key, size]) => `props.${key} is ${size} B of the ${bytes}`).join(', '),
       `in ${file}, pass ${heaviest.map(([key]) => `\`${key}: []\``).join(' and ')} beside ` +
-        `\`${first}Endpoint: derivePath('<queryName>')\` (@ultimat3/query) and fetch the rows inside ` +
+        `\`${first}Endpoint: queryPath('<queryName>')\` (@ultimat3/core) and fetch the rows inside ` +
         'the island after mount — a list that is the same on every request is a dataset, not a ' +
         'prop; an id, a count and a URL are',
     );

package/src/island.ts

@@ -6,6 +6,7 @@
  * graph (axiom 6). WHEN it wakes is the route's `hydrate`, never a second declaration here.
  */
 
+import { renderFixShellArg } from '@ultimat3/core';
 import { IslandInvalidError } from './errors';
 import type { JsonValue } from './island-props';
 import type { JsxProps } from './jsx';
@@ -25,7 +26,7 @@ const UNSAFE_SPECIFIER = /["'`<>\s\\]/;
 
 /** The same test the resolver's output has to pass: one rule, applied at both ends of the seam. */
 export function isEmittableSpecifier(value: string): boolean {
-  return value.length > 0 && !UNSAFE_SPECIFIER.test(value);
+  return typeof value === 'string' && value.length > 0 && !UNSAFE_SPECIFIER.test(value);
 }
 
 export interface IslandDeclaration<TKeys extends readonly string[] = readonly string[]> {
@@ -195,7 +196,10 @@ function normalizeIsland(declaration: IslandDeclaration): IslandSpec {
     throw new IslandInvalidError(
       `island src ${JSON.stringify(src)} is not an island file: a module ships to the browser ` +
         `only if its name says so, and ${ISLAND_EXTENSION} is the one spelling that says it`,
-      `git mv -- ${src} ${stem}${ISLAND_EXTENSION}, then pass src: '${stem}${ISLAND_EXTENSION}'`,
+      // Screened (security audit of plan 101 sweep 1c, M1): `UNSAFE_SPECIFIER` lets `$(…)`, `;`,
+      // `|` and `&` through. A leading `./` is dropped first — the same path to a shell, and
+      // `renderFixShellArg` refuses a leading `.` — so the common specifier stays pasteable.
+      `git mv -- ${renderFixShellArg(src.replace(/^\.\//, ''), "'<module>'")} ${renderFixShellArg(`${stem.replace(/^\.\//, '')}${ISLAND_EXTENSION}`, `'<name>${ISLAND_EXTENSION}'`)}, then pass src: '${stem}${ISLAND_EXTENSION}'`,
     );
   }
 

package/src/modes.ts

@@ -6,7 +6,7 @@
  */
 
 import type { HydrateStrategy, RenderMode } from '@ultimat3/core';
-import { HYDRATE_STRATEGIES, RENDER_MODES } from '@ultimat3/core';
+import { HYDRATE_STRATEGIES, RENDER_MODES, renderCauseValue } from '@ultimat3/core';
 import { parseTtlMs } from './duration';
 import { RouteModeInvalidError } from './errors';
 import type { RouteConfig } from './route';
@@ -84,14 +84,14 @@ export function assertModeShape(config: RouteShape): void {
     : undefined;
   if (spec === undefined) {
     throw new RouteModeInvalidError(
-      `render: ${JSON.stringify(config.render)} is not a render mode`,
+      `render: ${renderCauseValue(config.render)} is not a render mode`,
       `use one of ${RENDER_MODES.join(' | ')}`,
     );
   }
 
   if (!HYDRATE_STRATEGIES.includes(config.hydrate)) {
     throw new RouteModeInvalidError(
-      `hydrate: ${JSON.stringify(config.hydrate)} is not a hydration strategy`,
+      `hydrate: ${renderCauseValue(config.hydrate)} is not a hydration strategy`,
       `use one of ${HYDRATE_STRATEGIES.join(' | ')}`,
     );
   }
@@ -200,6 +200,17 @@ export function assertModeInvariants(config: RouteShape, ctx: ModeCheckContext):
     );
   }
 
+  // `js` is the one budget anything measures. `lcp`, `css`, `cls` and `tbt` were each accepted,
+  // stored and compared by nothing that had a measurement — a false green — so a key the type no
+  // longer declares, arriving by a cast or from plain JS, is refused rather than carried.
+  for (const key of Object.keys(config.budget)) {
+    if (key === 'js') continue;
+    throw new RouteModeInvalidError(
+      `${ctx.file} declares budget.${key}, which nothing in the framework measures — only budget.js is weighed (x verify's budgets step). In ${ctx.file}, delete ${key}: the whole budget is the js key`,
+      "budget: { js: '10kb' }",
+    );
+  }
+
   // `budget` is always on the descriptor; `budget.js` is the field that stays optional,
   // and its absence is the failure — site/ is 0kb until a route says otherwise, in bytes.
   if (ctx.surface === 'site' && config.hydrate !== 'never' && config.budget.js === undefined) {

package/src/module-loader.ts

@@ -4,12 +4,10 @@
  * `bun test` all load a component the same way and there is no separate "bundled" behaviour.
  */
 
-// why: Bun ships no path API, and a relative app root has to be resolved against the working
-// directory before it can be compared with the absolute paths the Bun plugin hands this loader.
-import { resolve } from 'node:path';
 import { renderThrowable } from '@ultimat3/core';
 import { compileStylesheet, isGlobalStylesheet, stripCharset } from './css-modules';
 import { PrerenderFailedError } from './errors';
+import { comparablePath, isPathBelow, pathBelow } from './stylesheet-path';
 import type { Surface } from './surfaces';
 import { surfaceUnder } from './surfaces';
 
@@ -42,7 +40,8 @@ const RENDER_PACKAGE = '@ultimat3/render';
  * `Bun.plugin` ignores `onResolve` outright — the callback never fires, from module scope or from
  * a `--preload`, and a virtual namespace never resolves — and ignores `resolveDir` on an `onLoad`
  * result. Neither seam can carry the resolution, so the specifier must. Revisit if Bun wires
- * either: an `onResolve` hook would leave every compiled module byte-identical.
+ * either: an `onResolve` hook would leave every compiled module byte-identical. Upstream:
+ * https://github.com/oven-sh/bun/issues/40579.
  *
  * The fallback is the status quo, for the one frame that cannot answer: inside a
  * `bun build --compile` binary `import.meta.url` is `file:///$bunfs/root/<name>` and
@@ -120,9 +119,12 @@ export function registeredStylesheets(): readonly Stylesheet[] {
 /**
  * The directory a sheet's surface is read below. Absent, the process's working directory — which
  * is the app root in the container (`WORKDIR /app`) and under every `x` command run from one.
+ * Held as a `comparablePath`, like every claim: on Windows each arrives as `D:\app\…`.
  */
 let stylesheetRoot: string | undefined;
 
+const rootOfSheets = (): string => stylesheetRoot ?? comparablePath(process.cwd());
+
 /**
  * Directories a package claimed for ONE surface, longest first. A package's sheet has no surface
  * of its own and rides both graphs — right for a design system, and the reason an app's static
@@ -130,11 +132,13 @@ let stylesheetRoot: string | undefined;
  */
 const claims: { readonly dir: string; readonly surface: Surface }[] = [];
 
-const claimedSurface = (path: string): Surface | undefined =>
-  claims.find((claim) => path.startsWith(`${claim.dir}/`))?.surface;
+const claimedSurface = (path: string): Surface | undefined => {
+  const comparable = comparablePath(path);
+  return claims.find((claim) => isPathBelow(comparable, claim.dir))?.surface;
+};
 
 const surfaceOfSheet = (path: string): Surface | null =>
-  claimedSurface(path) ?? surfaceUnder(stylesheetRoot ?? process.cwd(), path);
+  claimedSurface(path) ?? surfaceUnder(rootOfSheets(), comparablePath(path));
 
 /** Every registered sheet, classified again; the revision moves only when an answer does. */
 const reclassify = (): void => {
@@ -157,7 +161,7 @@ const reclassify = (): void => {
  * it standing, because the module that made it is cached and will not make it again.
  */
 export function claimStylesheets(dir: string, surface: Surface): void {
-  const claimed = resolve(dir);
+  const claimed = comparablePath(dir);
   if (claims.some((claim) => claim.dir === claimed && claim.surface === surface)) return;
   claims.push({ dir: claimed, surface });
   claims.sort((a, b) => b.dir.length - a.dir.length);
@@ -174,7 +178,7 @@ export function claimStylesheets(dir: string, surface: Surface): void {
  */
 export function setStylesheetRoot(root: string | undefined): void {
   // Resolved: `loadApp('.')` is a legal call, and `.` is a prefix of no absolute path.
-  stylesheetRoot = root === undefined ? undefined : resolve(root);
+  stylesheetRoot = root === undefined ? undefined : comparablePath(root);
   reclassify();
 }
 
@@ -221,11 +225,12 @@ const OWNER_RANK = (sheet: Stylesheet): number =>
   // A claimed sheet is a package's whichever surface carries it: library first.
   sheet.surface === null || sheet.claimed ? 0 : sheet.surface === 'shared' ? 1 : 2;
 
-/** Relative to the app root, so a container at `/app` and a laptop order one app alike. */
-const orderPath = (sheet: Stylesheet): string => {
-  const root = stylesheetRoot ?? process.cwd();
-  return sheet.file.startsWith(`${root}/`) ? sheet.file.slice(root.length + 1) : sheet.file;
-};
+/**
+ * Relative to the app root and `/`-separated, so a container at `/app`, a laptop and a Windows
+ * checkout at `D:\app` order one app alike — and so mint one stylesheet hash.
+ */
+const orderPath = (sheet: Stylesheet): string =>
+  pathBelow(comparablePath(sheet.file), rootOfSheets());
 
 /** See `stylesFor`: global layer, then owner, then path. Exported for the tests that pin it. */
 export function stylesheetOrder(a: Stylesheet, b: Stylesheet): number {

package/src/navigation-dom.ts

@@ -39,6 +39,28 @@ export function anchorOf(target: EventTarget | null): HTMLAnchorElement | HTMLAr
 export const fieldText = (value: unknown): string =>
   value instanceof File ? value.name : String(value);
 
+/** Every lone CR, lone LF and CRLF in `text`, as CRLF. */
+const crlf = (text: string): string => text.replace(/\r\n|\r|\n/g, '\r\n');
+
+/**
+ * The fields as a GET query or a urlencoded body carries them — names and values with their line
+ * breaks normalised to CRLF, as the browser's own submit does (HTML's "convert to a list of
+ * name-value pairs"). A `<textarea>`'s value holds bare LFs; sent as they were, the router's
+ * submit and a native one delivered two different bodies for one form. A multipart body needs
+ * none of this: `fetch` encodes a `FormData` with the same normalisation.
+ */
+export const formPairs = (fields: FormData): readonly (readonly [string, string])[] =>
+  [...fields].map(([name, value]: [string, unknown]) => [crlf(name), crlf(fieldText(value))]);
+
+/**
+ * A form's action, resolved against the document — or the raw text when it does not resolve, which
+ * `formVerdict` leaves to the browser (`'unparsable'`) rather than throwing from a submit handler.
+ */
+export function formAction(raw: string, fallback: string, base: string): string {
+  const action = raw || fallback;
+  return URL.canParse(action, base) ? new URL(action, base).href : action;
+}
+
 /** The submitted fields, the submitter's own name/value included, as the browser would send. */
 export function formFields(form: HTMLFormElement, submitter: HTMLElement | null): FormData {
   try {
@@ -59,7 +81,7 @@ const hush = (): void => undefined;
 export async function transition(
   win: Window,
   apply: () => void,
-  track?: (running: RunningTransition | undefined) => void,
+  track?: (running: RunningTransition, finished: boolean) => void,
 ): Promise<void> {
   const doc = win.document as Document & {
     startViewTransition?: (update: () => void) => RunningTransition;
@@ -70,12 +92,12 @@ export async function transition(
     return;
   }
   const running = doc.startViewTransition(apply);
-  track?.(running);
+  track?.(running, false);
   running.ready.catch(hush);
-  running.finished.then(
-    () => track?.(undefined),
-    () => track?.(undefined),
-  );
+  // The transition itself, never "whichever is running": an older one finishing after a newer one
+  // started must not clear the newer one (the caller compares by identity).
+  const done = (): void => track?.(running, true);
+  running.finished.then(done, done);
   await running.updateCallbackDone;
 }