npm - @ultimat3/render - Versions diffs - 7.0.0 → 9.0.0 - Mend

@ultimat3/render 7.0.0 → 9.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/CLAUDE.md CHANGED Viewed

@@ -4,13 +4,30 @@ Owns: the `route` primitive, the four render modes, the route table, the surface
 islands + budgets, hydration directives, `<head>` merge, **the server JSX runtime and the two Bun
 loaders that make an app's `.tsx` and `.scss` runnable**.
+**Two entry points, disjoint, split 2026-08-22** — the same `"."` / `"./server"` shape
+`@ultimat3/realtime` took, for the same reason. `"."` (`index.ts`) is the CLIENT half and BUNDLES
+for the browser; `"./server"` (`server.ts`) is the build-time half — `css-modules`,
+`module-loader`, `render-html`, `render-isr`, `render-ssr`, `render-static`, `render-stream` — and
+does not. `css-modules.ts` imports `fileURLToPath`/`pathToFileURL` from `node:url`, which Bun's
+browser polyfill exports NEITHER of, so the single barrel was not a fat bundle, it was a
+`bun build --target=browser` that FAILED at link time on any app entry that reached this package.
+Measured: no `sideEffects` value repairs it (`false`, `[]`, an array naming only `errors.ts` — all
+fail identically), which is where this split differs from realtime's, where the array alone was
+enough. Only not importing the module does. Never re-export a name from both barrels: disjointness
+is what makes "which half does this live in" a mechanical fact, and `index.test.ts` asserts both
+the empty name intersection AND that `index.ts`'s transitive runtime import graph reaches none of
+the seven modules above. `scripts/browser-barrel.test.ts` holds the end property, both directions.
 `island()` is a **factory over the route's own `hydrate`**, not a ninth primitive and not a
 second render mode — the same rule `llm()` and `backfill()` follow. It adds no key to
 `defineRoute`.
 Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cache`, `seo`,
-`entity`, `policy`, `http`, `action`, `query`. **Never** `pwa`, `mcp`, `ai`, `manifest`
-(sideways), never `ui`/`cli` (upward).
+`entity`, `policy`, `http`, `action`, `query`. **Never** `pwa`, `mcp`, `ai`, `manifest`, `ui`
+— all tier 4, so **sideways**, and an undeclared sideways edge is a build error. `ui` moved 5 → 4
+in 2026-08 and is held level with this package deliberately (`FLOOR_ABOVE` in
+`scripts/lib/tiers.ts`), so `render → ui` stays refused; this package sits above its own floor of 2
+for the mirror-image reason, keeping `render → pwa` refused. Never `cli` (upward).
 | Rule | Detail |
 |---|---|
@@ -35,14 +52,16 @@ Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cach
 | Island props | declared, JSON-safe, under `ISLAND_PROPS_MAX_BYTES` — `island-props.ts` is the one gate. A structural walk, never a `JSON.stringify` round trip: stringify drops a function and an `undefined` silently, which is the footgun rather than the check. |
 | A prop lands via `Object.defineProperty` | never `out[key] = v`. For exactly one name — `__proto__`, which `JSON.parse` mints as a real OWN key off any request body — the assignment runs `Object.prototype`'s setter: the prop was DROPPED from the browser payload (the footgun the walk exists to prevent), the record handed back as `IslandProps` carried a prototype built from request data, so a later `bag.row.isAdmin` on the SERVER read attacker-chosen values, and `ISLAND_PROPS_MAX_BYTES` under-counted because `JSON.stringify` could not see it. Same shape `@ultimat3/mcp`'s `validate-args.ts` uses for the same class. |
 | An attribute alias is a `Map` | never a record — an object lookup walks the prototype chain, so `<div {...row} />` with a column named `toString` resolved the alias to a FUNCTION and `attribute.toLowerCase()` threw a bare `TypeError`: no code, no fix, the whole page 500s off a `load()` result. Same reason `MODE_SPECS[config.render]` in `modes.ts` is guarded by `Object.hasOwn`, where `render: 'constructor'` returned a frozen descriptor for a mode nothing implements. |
+| An attribute NAME is validated too | `ATTRIBUTE_NAME` in `html.ts` — `/^[A-Za-z_:][-A-Za-z0-9_:.]*$/`, refused as `null`. A name is emitted VERBATIM before the `=` and is escaped nowhere, so `{ 'q onmouseover=alert(1) r': 'ok' }` shipped a live event handler out of an object KEY. The handler check on the line under it folds case for the same reason: it was `name.startsWith('on')` while the two checks below it lowercased, so `ONERROR="alert(1)"` went out on the wire. Both are reachable by `<div {...row} />` over a JSON body or a JSONB column. `head.ts`'s `renderTag` is the package's OTHER attribute sink and shares the predicate (`isAttributeName`) — it emitted `<meta name="q" r onmouseover=alert(1) s="ok">` from an `attrs` key. One predicate, never two. |
 | Which attributes take a URL | `URL_BEARING_ATTRIBUTES` in `html.ts` — core's four (`href`, `src`, `action`, `formaction`) plus `data`, `poster`, `ping` and `xlink:href`, each of which a browser FOLLOWS. `srcdoc` is refused outright: its value is entity-decoded and THEN parsed as HTML, so `escapeAttribute`'s `&lt;script&gt;` becomes a live `<script>` on this origin — escaping cannot make markup inert, so the attribute is never emitted, the same way `innerHTML` stays the one explicit escape hatch. |
 | Island collection | per render, passed as `renderToHtml(tree, { islands })`. Never module-global and never on an ambient context — two concurrent requests would bill one page for the other's JS, and `assertNoPerRequestState` refuses a live context under `static` anyway. |
+| A byte count in a message | `formatBytes` from `@ultimat3/core`, never a local one. This package's copy stopped at `kb`, so a 5 MB route read `5120kb` in `X_BUDGET_EXCEEDED` while `@ultimat3/pwa`'s own copy said `5mb` for the same bytes — two halves of one build disagreeing about the size of one artifact. Still on this barrel, because `@ultimat3/cli`'s budget reporter reads it beside the route table. |
 | Island bytes | `routeJsBytes` unions `entry.islands` with the rendered directives' `moduleId`s. Reading either alone is a budget that counts the runtime and not the chunk. |
 | 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` 744, `visible` 816, `interaction` 1,010 (`As of 2026-08-21`, the numbers `DEFAULT_ISLAND_JS_BYTES` is derived from). |
 | `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. |
+| 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. |
 | Registry input | descriptors only. `registerRoute` refuses a raw declaration with `X_ROUTE_UNNORMALIZED` — `defineRoute` is the one normalizer of everything the declaration alone decides, and every reader downstream assumes it ran. The registry fills in exactly one value on top: the island budget, which needs the surface, which is a fact of the file path only the route table reads. |
 | Descriptors | `describeRoutes()` must stay JSON-safe, sorted by path, deterministic. |
@@ -63,14 +82,14 @@ Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cach
 | Responses | return `RenderResult`. `@ultimat3/http` builds the `Response`. |
 | Solid | no `solid-js` import anywhere in this package — `type-pins.tsx` satisfies its `JSX.Element` structurally, through `jsxImportSource`, and never names it. The JSX factory in `jsx.ts` builds inert nodes — it is not a Solid renderer and must never become one. The client half runs in an island chunk, which `@ultimat3/cli`'s `solid-loader.ts` compiles with `babel-preset-solid`: Solid's reactivity is a COMPILE-time contract, so nothing this package could inject would substitute for it. `router-client.ts` was the one file built on that premise ("inject primitives") and it never had a caller. |
 | Root element | `ROOT_ELEMENT_ID` (`render-html.ts`), the id every document's body wraps its component in. It was `SPA_ROOT_ID` in `render-spa.ts`, naming a mode that never used it and that no longer exists. |
-| The loaders | `module-loader.ts` installs them at `index.ts` module scope, once. A plugin only affects modules loaded after it, so a second install point is a page that renders in one entry point and not another. |
+| The loaders | `module-loader.ts` installs them at **`server.ts`** module scope, once — `index.ts` until the barrel split, and it cannot be there again: the client barrel would carry `sass` and `node:url`. A plugin only affects modules loaded after it, so a second install point is a page that renders in one entry point and not another. Anything that loads an app's `.tsx` reaches `@ultimat3/render/server` first, which is why `packages/cli/src/app-load.ts` imports it for the side effect and nothing else. |
 | `<head>` baseline | `documentBaseline()` in `head.ts` — charset, viewport, `color-scheme` — merged FIRST so a route can still override any of them. Absent until `As of 2026-08`, and the missing `viewport` is why every deployed app rendered zoomed-out on a phone whatever its CSS said. |
-| Escaping | `html.ts` only, and that now includes `render-stream.ts` (`holeMarker`'s attribute, and `revealChunk`'s `$X(...)` argument via `JSON.stringify` — an id containing `")` closed the call and ran the rest) and `head.ts`'s `themeScript` (`storageKey`/`attribute` as JS string LITERALS). All author-controlled today — the identical status `emitIslandAttributes` had before the last sweep. `render-spa.ts` was the third entry here and went with the mode. A second escaper is how one of them ends up missing a character, and a missing character in an attribute is an injection. `head.ts` and `hydrate.ts` each had a private copy; both now import — `escapeAttribute` for every attribute value (`emitIslandAttributes` interpolated all five of its own raw until 2026-08, while this row already claimed otherwise) and `escapeJsonContent` for a JSON script body. |
+| Escaping | `html.ts` only, and that now includes `render-stream.ts` (`holeMarker`'s attribute, and `revealChunk`'s `$X(...)` argument via `JSON.stringify` — an id containing `")` closed the call and ran the rest) and `head.ts`'s `themeScript` (`storageKey`/`attribute` as JS string LITERALS). All author-controlled today — the identical status `emitIslandAttributes` had before the last sweep. `render-spa.ts` was the third entry here and went with the mode. A second escaper is how one of them ends up missing a character, and a missing character in an attribute is an injection. `escapeAttribute` itself is `@ultimat3/seo`'s (tier 1), re-exported by `html.ts` rather than reimplemented — the copy that lived here was the second escaper this row forbids, and `pwa/CLAUDE.md` already named seo's as the one. `head.ts` and `hydrate.ts` each had a private copy; both now import — `escapeAttribute` for every attribute value (`emitIslandAttributes` interpolated all five of its own raw until 2026-08, while this row already claimed otherwise) and `escapeJsonContent` for a JSON script body. |
 | Script and style CONTENT | never emitted raw. Three rules, one choice: HTML text (`escapeText`), raw text for code (`escapeRawTextContent`: `</` → `<\/`, `<!--` → `<\!--`), and the total JSON rule for a `type` ending in `json` (`escapeJsonContent`: `<`, `>`, `&`, U+2028/9 → `\uXXXX`, still valid JSON). `meta.ld` is built from route data, and it was emitted VERBATIM until `As of 2026-08` — a title could close the element. Never HTML-escape a script body: a character reference is not decoded there, so `&lt;` corrupts the code AND leaves the hole. |
 | Which export is the page | `route-component.ts`, one precedence: `Page` → a single `…Page` → a single capitalised function. Never a per-generator name table. |
 | Stylesheets | compiled by `css-modules.ts` and served **inlined** per surface. `sass` is this package's only third-party dependency and its only reason to exist here. |
 | CSS order | `stylesFor` sorts **globals before modules** (`isGlobalStylesheet`), never plain insertion order — the reset styles bare elements at the lowest specificity there is, so whichever page loaded first must not decide who wins a tie. `shared/` is carried by both graphs, like a package sheet: it is where an app's own global layer lives, and filtering it out is what made every deployed app render token-less. |
-| The global layer | this package may not import `@ultimat3/ui` (tier 5, upward), so the app's source graph carries it: one `shared/global.scss` that `@use`s `@ultimat3/ui/global.scss`, side-effect-imported by `shared/global.ts`. One file, because each stylesheet is its own Sass compilation — a token file `@use`d per module duplicates its `:root` block per module. `x verify` fails with `X_STYLES_GLOBAL_MISSING` when a surface's document defines none. |
+| The global layer | this package may not import `@ultimat3/ui` (tier 4, the same tier — sideways, not upward: `ui` moved 5 → 4 in 2026-08 and `render → ui` stays forbidden because a same-tier edge has to be declared in `scripts/lib/tiers.ts`, and this one deliberately is not — the static bundle graph may not reach the design system, axiom 6), so the app's source graph carries it: one `shared/global.scss` that `@use`s `@ultimat3/ui/global.scss`, side-effect-imported by `shared/global.ts`. One file, because each stylesheet is its own Sass compilation — a token file `@use`d per module duplicates its `:root` block per module. `x verify` fails with `X_STYLES_GLOBAL_MISSING` when a surface's document defines none. |
 | Colours | tokens and `data-theme` only. No hex in `head.ts` or any emitted script. |
 | `<head>` binding | `head.ts` stays injection-only (testable with no catalog); `head-seo.ts` is the ONE binding of `HeadRenderers` to `@ultimat3/seo`. A caller writing its own converter is the drift this file prevents. |

package/README.md CHANGED Viewed

@@ -19,7 +19,7 @@ export const config = defineRoute({
   budget:     { js: '40kb', lcp: 2000 },
   load:       ({ params }) => db.posts.bySlug(params.slug),   // once per render
   meta:       ({ data, url }) => ({ title: data.title, description: data.excerpt,
-                                    og: { image: data.cover }, alternates: { canonical: url },
+                                    og: { image: data.cover }, canonical: url,
                                     ld: ld.Article(data) }),
 });
@@ -321,18 +321,44 @@ never flushed into an island that did not mount. `ISLAND_MOUNTED_ATTRIBUTE` and
 from, exported for the same reason: anything waiting for hydration has to wait at least this long,
 and a second copy of the number is a settle that shoots early and calls a healthy page broken.
+## Two entry points
+**Split 2026-08-22, and every claim in this section holds `As of 2026-08`.**
+`@ultimat3/render` is the **client** half — the `route` primitive, the JSX factory, islands,
+hydration, `<head>`, the route table. It bundles for the browser, and
+`scripts/browser-barrel.test.ts` builds it that way and asserts it.
+`@ultimat3/render/server` is the **build-time** half — the `.tsx`/`.scss` Bun loaders and the
+render pipeline. It imports `sass` and `node:url`, so it never reaches a browser bundle.
+The two are **disjoint**: no name is on both, and a file needing both imports both. That is the
+price of the split and it is the point of it — a single barrel could not be bundled for the
+browser at all, because `node:url`'s browser polyfill exports neither `fileURLToPath` nor
+`pathToFileURL` and the build fails at link time. No `sideEffects` value fixes that (measured:
+`false`, `[]` and an array naming only `errors.ts` all fail identically) — only not importing it
+does.
+**Importing `@ultimat3/render/server` installs the `.tsx`/`.scss` loaders**, once, as a module
+side effect. Anything that loads an app's source — `x dev`, `x build`, `server.ts`, a test that
+`await import()`s a `page.tsx` — reaches it before the module it loads.
 ## Public API
+`†` marks a name on `@ultimat3/render/server`.
 | Export | Owns |
 |---|---|
 | `defineRoute` | the `route` primitive |
 | `island`, `createIslandCollector` | one interactive component on a static page |
 | `MODE_SPECS`, `assertModeShape`, `assertModeInvariants` | the mode invariant table |
-| `registerRoute`, `describeRoutes`, `matchRoute`, `routePathFromFile` | the route table |
+| `registerRoute`, `describeRoutes`, `routeFor`, `routePathFromFile` | the route table |
 | `checkSurfaceBoundary`, `assertSurfaceBoundary`, `surfaceOf` | the hard boundary |
-| `renderStatic`, `enumeratePrerender` | build-time render, content hashing |
-| `createIsrController`, `invalidateAndRevalidate` | SWR + single-flight + tag triggers |
-| `renderSsr`, `streamResult` | the per-request modes |
+| `renderStatic`†, `enumeratePrerender`† | build-time render, content hashing |
+| `createIsrController`†, `invalidateAndRevalidate`† | SWR + single-flight + tag triggers |
+| `renderSsr`†, `streamResult`† | the per-request modes |
+| `renderToHtml`†, `renderComponent`†, `stylesFor`† | the server JSX writer and the surface's css |
+| `installRenderLoader`†, `compileStylesheet`† | the `.tsx`/`.scss` loaders, installed on import |
 | `emitIslandAttributes`, `hydrateRuntime` | the four hydration strategies |
 | `ISLAND_MOUNTED_ATTRIBUTE`, `ISLAND_FAILED_ATTRIBUTE`, `IDLE_HYDRATE_TIMEOUT_MS` | what hydration looks like from outside the page |
 | `graphFor`, `checkBudget`, `assertBudget` | two bundle graphs, per-route budgets |

package/package.json CHANGED Viewed

@@ -1,12 +1,12 @@
 {
   "name": "@ultimat3/render",
-  "version": "7.0.0",
+  "version": "9.0.0",
   "description": "The route primitive and the five render modes: static, isr, ssr, stream, spa.",
   "license": "MIT",
   "type": "module",
   "sideEffects": [
     "./src/errors.ts",
-    "./src/index.ts"
+    "./src/server.ts"
   ],
   "repository": {
     "type": "git",
@@ -18,7 +18,8 @@
     "provenance": true
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./server": "./src/server.ts"
   },
   "files": [
     "src",
@@ -35,10 +36,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "7.0.0",
-    "@ultimat3/core": "7.0.0",
-    "@ultimat3/i18n": "7.0.0",
-    "@ultimat3/seo": "7.0.0",
+    "@ultimat3/cache": "9.0.0",
+    "@ultimat3/core": "9.0.0",
+    "@ultimat3/i18n": "9.0.0",
+    "@ultimat3/seo": "9.0.0",
     "sass": "1.102.0"
   }
 }

package/src/head.ts CHANGED Viewed

@@ -10,7 +10,13 @@
 import type { RouteMeta } from '@ultimat3/seo';
 import { BudgetExceededError } from './errors';
 // `html.ts` is this package's one escaper — a second one is how a character ends up missing.
-import { escapeAttribute, escapeJsonContent, escapeRawTextContent, escapeText } from './html';
+import {
+  escapeAttribute,
+  escapeJsonContent,
+  escapeRawTextContent,
+  escapeText,
+  isAttributeName,
+} from './html';
 export type HeadTagKind = 'title' | 'base' | 'meta' | 'link' | 'script' | 'style';
@@ -112,7 +118,11 @@ export function renderHead(tags: readonly HeadTag[]): string {
 }
 function renderTag(tag: HeadTag): string {
+  // The NAME is emitted verbatim before the `=` and is escaped nowhere, so a key carrying a space
+  // carries a whole second attribute with it — an app spreading a row into `attrs` put a live
+  // event handler in `<head>`. Same predicate `attributePair` uses, never a second copy.
   const attrs = Object.entries(tag.attrs ?? {})
+    .filter(([name]) => isAttributeName(name))
     .map(([name, value]) =>
       value === true ? ` ${name}` : ` ${name}="${escapeAttribute(String(value))}"`,
     )

package/src/html.ts CHANGED Viewed

@@ -5,6 +5,7 @@
  */
 import { safeUrl, URL_ATTRIBUTES } from '@ultimat3/core';
+import { escapeAttribute } from '@ultimat3/seo';
 import type { JsxProps } from './jsx';
 /** Elements that never carry children, so the writer must not emit a closing tag. */
@@ -29,9 +30,13 @@ export function escapeText(value: string): string {
   return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
 }
-export function escapeAttribute(value: string): string {
-  return escapeText(value).replaceAll('"', '&quot;');
-}
+/**
+ * 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
@@ -115,6 +120,20 @@ const URL_BEARING_ATTRIBUTES: ReadonlySet<string> = new Set([
  */
 const REFUSED_ATTRIBUTES: ReadonlySet<string> = new Set(['srcdoc']);
+/**
+ * The only shape that can be written between `<div` and `>` without ending the attribute. A name
+ * is not escaped anywhere — it is emitted verbatim before the `=` — so a key carrying a space
+ * carries a whole second attribute with it: `{ 'x onmouseover=alert(1) y': 'ok' }` emitted a live
+ * event handler out of an object KEY, which is `<div {...row} />` over a JSON body or a JSONB
+ * column. Narrower than the HTML spec's name production on purpose: everything an app actually
+ * writes (`data-*`, `aria-*`, `xlink:href`, a `__proto__`-named column) matches, and the refusal
+ * is `null` — the same "emit nothing" this function already answers for a refused URL.
+ */
+const ATTRIBUTE_NAME = /^[A-Za-z_:][-A-Za-z0-9_:.]*$/;
+/** Exported for `head.ts`, the package's other attribute sink. One predicate, never two. */
+export const isAttributeName = (name: string): boolean => ATTRIBUTE_NAME.test(name);
 const cssProperty = (name: string): string =>
   name.startsWith('--') ? name : name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
@@ -137,7 +156,11 @@ export function attributePair(name: string, value: unknown): string | null {
   if (NON_ATTRIBUTES.has(name)) return null;
   if (value === undefined || value === null || value === false) return null;
   if (typeof value === 'function') return null;
-  if (name.startsWith('on') && name.length > 2) return null;
+  if (!isAttributeName(name)) return null;
+  // Folded, because HTML attribute names are case-insensitive and the two checks below already
+  // fold: `ONERROR="alert(1)"` went out on the wire off a spread row for as long as this line was
+  // `name.startsWith('on')`.
+  if (name.toLowerCase().startsWith('on') && name.length > 2) return null;
   const attribute = ATTRIBUTE_ALIASES.get(name) ?? name;
   if (REFUSED_ATTRIBUTES.has(attribute.toLowerCase())) return null;

package/src/index.ts CHANGED Viewed

@@ -1,13 +1,8 @@
-/** Public API of `@ultimat3/render`: the `route` primitive, the five modes, the table. */
-import { installRenderLoader } from './module-loader';
-// A side effect on import, deliberately: a Bun plugin only transforms modules loaded AFTER it, and
-// every consumer that will ever load a `.tsx` route or a `.scss` module imports this package first
-// (an app's route file imports `defineRoute` from here before it imports anything else it owns).
-// Any later hook — `x dev`, `x build`, `server.ts` — would each have to remember, which is four
-// places one fact can be wrong instead of none.
-installRenderLoader();
+/**
+ * The CLIENT half of `@ultimat3/render` — the `route` primitive, the JSX factory, islands, and the
+ * tables describing them — kept disjoint from `@ultimat3/render/server` because everything here
+ * must bundle for a browser, which the loaders cannot (axiom 6).
+ */
 /**
  * The route vocabulary is declared once, at tier 0 (`@ultimat3/core`), and re-exported here
@@ -17,9 +12,10 @@ installRenderLoader();
  * second declaration, which is what makes re-exporting safe where copying was not.
  */
 export type { HydrateStrategy, OfflineStrategy, RenderMode } from '@ultimat3/core';
-export { HYDRATE_STRATEGIES, OFFLINE_STRATEGIES, RENDER_MODES } from '@ultimat3/core';
-export type { CompiledStylesheet } from './css-modules';
-export { compileStylesheet, isCssModule, isGlobalStylesheet, scopeClasses } from './css-modules';
+// `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';
 export { parseTtlMs } from './duration';
 export type { RenderErrorCode } from './errors';
 export {
@@ -86,7 +82,6 @@ export {
   assertBudget,
   checkBudget,
   checkBudgets,
-  formatBytes,
   graphFor,
   parseByteBudget,
   routeJsBytes,
@@ -102,27 +97,16 @@ export {
   defaultIslandBudget,
   MODE_SPECS,
 } from './modes';
-export type { Stylesheet } from './module-loader';
-export {
-  clearStylesheets,
-  installRenderLoader,
-  loadStylesheet,
-  registeredStylesheets,
-  stylesFor,
-  transformTsx,
-} from './module-loader';
 export type {
   CompiledPattern,
   RegisterRouteInput,
   RouteDescriptor,
   RouteEntry,
-  RouteMatch,
 } from './registry';
 export {
   clearRoutes,
   compilePattern,
   describeRoutes,
-  matchRoute,
   ROUTE_FILENAME,
   registerRoute,
   routeCount,
@@ -130,48 +114,6 @@ export {
   routeFor,
   routePathFromFile,
 } from './registry';
-export type { RenderHtmlOptions } from './render-html';
-export { ROOT_ELEMENT_ID, renderComponent, renderToHtml } from './render-html';
-export type {
-  IsrController,
-  IsrControllerOptions,
-  IsrEntry,
-  IsrRenderFn,
-  IsrServeResult,
-  IsrState,
-  IsrStore,
-  MemoryIsrStoreOptions,
-} from './render-isr';
-export {
-  createIsrController,
-  DEFAULT_ISR_MAX_ENTRIES,
-  invalidateAndRevalidate,
-  isrKey,
-  memoryIsrStore,
-} from './render-isr';
-export type { SsrOptions, SsrRenderFn, SsrRenderInput } from './render-ssr';
-export { renderSsr, ssrHeaders } from './render-ssr';
-export type { StaticArtifact, StaticBuildOptions, StaticRenderFn } from './render-static';
-export {
-  assertNoPerRequestState,
-  contentHash,
-  enumeratePrerender,
-  fillPath,
-  renderStatic,
-  staticHeaders,
-  staticResult,
-} from './render-static';
-export type { StreamHole, StreamOptions, StreamPlan } from './render-stream';
-export {
-  collectStream,
-  DEFAULT_HOLE_TIMEOUT_MS,
-  holeId,
-  holeMarker,
-  REVEAL_SCRIPT,
-  renderStreamHtml,
-  revealChunk,
-  streamResult,
-} from './render-stream';
 export type {
   LoadRequirement,
   PrerenderFn,

package/src/islands.ts CHANGED Viewed

@@ -6,6 +6,9 @@
  */
 import type { HydrateStrategy } from '@ultimat3/core';
+// One formatter, in `@ultimat3/core`: the copy that lived here had no `mb` branch, so a 5 MB route
+// read `5120kb` in `X_BUDGET_EXCEEDED` while `@ultimat3/pwa` said `5mb` for the same bytes.
+import { formatBytes } from '@ultimat3/core';
 import { BudgetExceededError } from './errors';
 import type { IslandDirective } from './hydrate';
 import { hydrateRuntimeBytes } from './hydrate';
@@ -55,11 +58,6 @@ export function parseByteBudget(budget: string | undefined): number | null {
   return factor === undefined ? null : Math.round(Number(amount) * factor);
 }
-export function formatBytes(bytes: number): string {
-  if (bytes < 1024) return `${bytes}b`;
-  return `${Math.round((bytes / 1024) * 10) / 10}kb`;
-}
 export interface RouteBytes {
   readonly total: number;
   readonly baseline: number;

package/src/registry.ts CHANGED Viewed

@@ -13,7 +13,7 @@ import {
   SurfaceBoundaryError,
 } from './errors';
 import { assertModeInvariants, defaultIslandBudget } from './modes';
-import type { RouteConfig, RouteData, RouteParams } from './route';
+import type { RouteConfig, RouteData } from './route';
 import { isRouteConfig, tagKeys } from './route';
 import type { RouteComponent } from './route-component';
 import type { Surface } from './surfaces';
@@ -155,12 +155,20 @@ function assertRouteFilename(file: string, surface: Surface, basename: string |
   const dir = stem.slice(0, stem.lastIndexOf('/'));
   const inPlace = DIRECTORY_STEMS.has(stem.slice(dir.length + 1));
   const target = inPlace ? `${dir}/${expected}` : `${stem}/${expected}`;
+  // Plain `mv`, never `git mv`. `x new --no-git` scaffolds a tree with no repository, and there the
+  // shipped `git mv` answered `fatal: not a git repository` — a fix line that fails is worse than
+  // no fix line, because the reader debugs git instead of moving the file. `mv` works in both
+  // cases: git detects the rename at `git add` time, so the only thing given up is a nicety, and
+  // the instruction is the same one either way. `-n` keeps the one guarantee `git mv` did carry:
+  // an author who adds the correct `site/pricing/page.tsx` and leaves `site/pricing.tsx` behind is
+  // reported against the stale file, and `target` is then the GOOD file — a clobber deletes a
+  // working route, and this fix line is pasted unread.
   throw new RouteFileInvalidError(
     `${file} is a route on the ${surface} surface, so it must be named ${expected}: the URL is the ` +
       'directory path and the filename names the kind of file',
     inPlace
-      ? `git mv -- ${shellQuote(file)} ${shellQuote(target)}`
-      : `mkdir -p -- ${shellQuote(stem)} && git mv -- ${shellQuote(file)} ${shellQuote(target)}`,
+      ? `mv -n -- ${shellQuote(file)} ${shellQuote(target)}`
+      : `mkdir -p -- ${shellQuote(stem)} && mv -n -- ${shellQuote(file)} ${shellQuote(target)}`,
   );
 }
@@ -334,46 +342,14 @@ export function describeRoutes(): readonly RouteDescriptor[] {
   }));
 }
-export interface RouteMatch {
-  readonly entry: RouteEntry;
-  readonly params: RouteParams;
-}
-/** Most specific pattern wins: static segments > dynamic > catch-all. */
-export function matchRoute(pathname: string): RouteMatch | null {
-  const candidates = routeEntries()
-    .slice()
-    .sort((a, b) => b.pattern.specificity - a.pattern.specificity);
-  for (const entry of candidates) {
-    const match = entry.pattern.regex.exec(pathname);
-    if (match === null) continue;
-    const params: Record<string, string> = {};
-    let undecodable = false;
-    entry.pattern.keys.forEach((key, index) => {
-      const value = match[index + 1];
-      if (value === undefined) return;
-      const decoded = decodeSegment(value);
-      if (decoded === undefined) undecodable = true;
-      else params[key] = decoded;
-    });
-    // A segment that will not decode fails only the branch that would have decoded it, exactly as
-    // `@ultimat3/http`'s router already answers: a literal route matching the same text still wins,
-    // and a pathname nothing else claims is the 404 it always was.
-    if (undecodable) continue;
-    return { entry, params };
-  }
-  return null;
-}
 /**
  * `undefined` for a malformed percent-escape. A pathname is whatever the client typed, and
- * `decodeURIComponent('%zz')` throws a bare `URIError` — no code, no fix line — which escaped
- * `matchRoute` as a 500 and an error-monitor page for somebody's typo.
+ * `decodeURIComponent('%zz')` throws a bare `URIError` — no code, no fix line — where a router
+ * already has an answer for "this branch does not match".
  *
- * Still exported after `router-client.ts` went with `createRouter`: it is the one answer to "is
- * this segment decodable?" on this side of the wire, and a second copy of it is how one of the two
- * ends up throwing where the other 404s.
+ * Still exported after this package's own `matchRoute` was deleted for `@ultimat3/http`'s trie
+ * (`stages.ts`): it is the one answer to "is this segment decodable?" on this side of the wire,
+ * and a second copy of it is how one of the two ends up throwing where the other 404s.
  */
 export function decodeSegment(value: string): string | undefined {
   try {

package/src/server.ts ADDED Viewed

@@ -0,0 +1,72 @@
+/**
+ * The BUILD-TIME half of `@ultimat3/render` — the loaders and the route → bytes pipeline — split
+ * off because `css-modules.ts` imports `node:url`, whose browser polyfill exports neither name it
+ * asks for: one barrel carrying both halves could not be bundled for a browser at all (axiom 6).
+ * Disjoint from `@ultimat3/render` by construction, which `server.test.ts` checks.
+ */
+import { installRenderLoader } from './module-loader';
+// A side effect on import, deliberately, and the reason this barrel is named in `sideEffects`: a
+// Bun plugin only transforms modules loaded AFTER it, so the install has to happen before any
+// `.tsx` route or `.scss` module is imported. It lives on THIS barrel rather than on
+// `@ultimat3/render` because the loader is build-time code — a browser bundle that reached it
+// would carry `sass` and `node:fs`, which is the defect this split closes.
+installRenderLoader();
+// ---- scss → css, and the scoped class map every `import styles from` receives -------------------
+export type { CompiledStylesheet } from './css-modules';
+export { compileStylesheet, isCssModule, isGlobalStylesheet, scopeClasses } from './css-modules';
+// ---- the two Bun loaders: `.tsx` → the server JSX factory, `.scss` → css + a class map ----------
+export type { Stylesheet } from './module-loader';
+export {
+  clearStylesheets,
+  installRenderLoader,
+  loadStylesheet,
+  registeredStylesheets,
+  stylesFor,
+  transformTsx,
+} from './module-loader';
+// ---- the render pipeline: one entry point per mode ----------------------------------------------
+export type { RenderHtmlOptions } from './render-html';
+export { ROOT_ELEMENT_ID, renderComponent, renderToHtml } from './render-html';
+export type {
+  IsrController,
+  IsrControllerOptions,
+  IsrEntry,
+  IsrRenderFn,
+  IsrServeResult,
+  IsrState,
+  IsrStore,
+  MemoryIsrStoreOptions,
+} from './render-isr';
+export {
+  createIsrController,
+  DEFAULT_ISR_MAX_ENTRIES,
+  invalidateAndRevalidate,
+  isrKey,
+  memoryIsrStore,
+} from './render-isr';
+export type { SsrOptions, SsrRenderFn, SsrRenderInput } from './render-ssr';
+export { renderSsr, ssrHeaders } from './render-ssr';
+export type { StaticArtifact, StaticBuildOptions, StaticRenderFn } from './render-static';
+export {
+  assertNoPerRequestState,
+  contentHash,
+  enumeratePrerender,
+  fillPath,
+  renderStatic,
+  staticHeaders,
+  staticResult,
+} from './render-static';
+export type { StreamHole, StreamOptions, StreamPlan } from './render-stream';
+export {
+  collectStream,
+  DEFAULT_HOLE_TIMEOUT_MS,
+  holeId,
+  holeMarker,
+  REVEAL_SCRIPT,
+  renderStreamHtml,
+  revealChunk,
+  streamResult,
+} from './render-stream';