@ultimat3/render 26.1.0 → 26.1.1

package/CLAUDE.md

@@ -10,7 +10,12 @@ loaders that make an app's `.tsx` and `.scss` runnable**.
 `node:url`, which a browser build cannot link; no `sideEffects` value repairs that). Never re-export
 a name from both barrels: `index.test.ts` asserts the empty name intersection and that `index.ts`'s
 runtime import graph reaches none of those seven modules; `scripts/browser-barrel.test.ts` holds
-the end property.
+the end property. **`"./client"` (`client.ts`) is THE browser entry** for what an island calls
+(`navigate`, `refresh`, `openModal`, `closeModal`, the modal refusal, the three event names): its
+graph never reaches `errors.ts` (the barrel's `sideEffects` keeps that table in every chunk), held
+by `client-bundle.test.ts`. A name there stays on `.` too (additive); a refusal it can construct
+lives in its own module over `@ultimat3/core/page`'s `UltimateError` (`navigation-errors.ts`) and
+`errors.ts` re-exports it — one class, never two.
 
 `island()` is a **factory over the route's own `hydrate`**, not a ninth primitive and not a second
 render mode. It adds no key to `defineRoute`.

package/README.md

@@ -143,8 +143,9 @@ reaching a page — a link, a redirect after a POST, a pasted hash.
 
 From code — an island, an app script — `navigate(url, { replace? })`, `refresh()`,
 `openModal(path)` and `closeModal()` go through the router when the page has one and fall back to
-`location.assign`/`replace`/`reload` when it does not; they import the router's type only.
-[Navigating from code](../../wiki/Client-Navigation.md#navigating-from-code).
+`location.assign`/`replace`/`reload` when it does not; they import the router's type only. An
+island imports them from **`@ultimat3/render/client`**, never the barrel — see
+[Two entry points](#two-entry-points). [Navigating from code](../../wiki/Client-Navigation.md#navigating-from-code).
 
 ## Mode invariants, checked at registration
 
@@ -483,6 +484,19 @@ does.
 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.
 
+`@ultimat3/render/client` is the **browser** entry — what an island or a page script calls:
+`navigate`, `refresh`, `openModal`, `closeModal`, `NavigateToOptions`,
+`NavigationModalPathInvalidError`, `NAVIGATE_EVENT`, `NAVIGATED_EVENT`, `NAVIGATION_ERROR_EVENT`.
+The barrel bundles for the browser but its `sideEffects` keeps `errors.ts` — render's code table,
+and core's and schema's titles tables behind it — in every chunk that reaches it; this entry's
+graph is the navigation helpers plus `@ultimat3/core/page` (`client-bundle.test.ts`). `As of
+2026-10-08`, an island whose body is `refresh()`: 9,323 B minified from the barrel, 216 B from
+`/client`. The barrel keeps the same names, for compatibility.
+
+```ts
+import { navigate, refresh } from '@ultimat3/render/client';
+```
+
 ## Error classes
 
 Every error class `src/index.ts` exports, for `instanceof` inside one process. Across a wire or
@@ -495,7 +509,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `IslandInvalidError` | `X_ISLAND_INVALID` | `src/errors.ts` |
 | `IslandNotHydratedError` | `X_ISLAND_NOT_HYDRATED` | `src/errors.ts` |
 | `IslandPropsInvalidError` | `X_ISLAND_PROPS_INVALID` | `src/errors.ts` |
-| `NavigationModalPathInvalidError` | `X_NAVIGATION_MODAL_PATH_INVALID` | `src/errors.ts` |
+| `NavigationModalPathInvalidError` | `X_NAVIGATION_MODAL_PATH_INVALID` | `src/navigation-errors.ts` (re-exported by `src/errors.ts`; also on `/client`) |
 | `PrerenderFailedError` | `X_PRERENDER_FAILED` | `src/errors.ts` |
 | `RouteDuplicateError` | `X_ROUTE_DUPLICATE` | `src/errors.ts` |
 | `RouteFileInvalidError` | `X_ROUTE_FILE_INVALID` | `src/errors.ts` |
@@ -509,7 +523,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 
 ## Public API
 
-`†` marks a name on `@ultimat3/render/server`.
+`†` marks a name on `@ultimat3/render/server`; `‡` a name also on `@ultimat3/render/client`.
 
 | Export | Owns |
 |---|---|
@@ -533,8 +547,8 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `ISLAND_HOLD_ATTRIBUTE`, `ISLAND_HOLD_MS`, `ISLAND_HOLD_REVEAL` | a held island's marker, and the cap after which it shows its server markup regardless |
 | `parseByteBudget`, `defaultIslandBudget` | the `'40kb'` budget grammar, and the ceiling a declared island earns |
 | `mergeHead`, `renderHead`, `themeScript` | `<head>` merge + the one inlined script; it stamps `data-theme` and, beside it, the fallback itself as `data-theme-default` for `@ultimat3/ui`'s `clearTheme`/`watchOsTheme` |
-| `clientNavigationTags`, `linkVerdict`, `formVerdict`, `responseVerdict`, `reusable`, `mayPrefetch`, `NAVIGATION_*`, `NAVIGATE_EVENT`, `NAVIGATED_EVENT` | the client router's document tags and its pure rules; the router itself is `@ultimat3/render/navigation`, built and served by the CLI |
-| `navigate`, `refresh`, `openModal`, `closeModal`, `NavigateToOptions` | navigating from code: the router when the page has one, the browser's own load when not |
+| `clientNavigationTags`, `linkVerdict`, `formVerdict`, `responseVerdict`, `reusable`, `mayPrefetch`, `NAVIGATION_*` (`NAVIGATION_ERROR_EVENT`‡), `NAVIGATE_EVENT`‡, `NAVIGATED_EVENT`‡ | the client router's document tags and its pure rules; the router itself is `@ultimat3/render/navigation`, built and served by the CLI |
+| `navigate`‡, `refresh`‡, `openModal`‡, `closeModal`‡, `NavigateToOptions`‡, `NavigationModalPathInvalidError`‡ | navigating from code: the router when the page has one, the browser's own load when not. Import from `/client` in an island |
 | `modalAddress`, `modalLocation`, `addressOf`, `presentation`, `modalHistory`, `leaveModal`, `NAVIGATION_PRESENTATION_META`, `NAVIGATION_MODAL_ATTRIBUTE` | route-presented modals (`navigation: 'modal'`): the hash grammar, when an answer is a modal, and what leaving one does to history |
 | `clientPathStyleTags`, `CLIENT_PATH_STYLE_META` | `<meta name="ultimate-path-style">` — the action path style the server serves, for the browser's typed client. No tag for `'resource'`, the default |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/render",
-  "version": "26.1.0",
+  "version": "26.1.1",
   "description": "The route primitive and the five render modes: static, isr, ssr, stream, spa.",
   "license": "MIT",
   "type": "module",
@@ -20,6 +20,7 @@
   },
   "exports": {
     ".": "./src/index.ts",
+    "./client": "./src/client.ts",
     "./server": "./src/server.ts",
     "./navigation": "./src/navigation-entry.ts"
   },
@@ -39,11 +40,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "26.1.0",
-    "@ultimat3/core": "26.1.0",
-    "@ultimat3/http": "26.1.0",
-    "@ultimat3/i18n": "26.1.0",
-    "@ultimat3/seo": "26.1.0",
+    "@ultimat3/cache": "26.1.1",
+    "@ultimat3/core": "26.1.1",
+    "@ultimat3/http": "26.1.1",
+    "@ultimat3/i18n": "26.1.1",
+    "@ultimat3/seo": "26.1.1",
     "sass": "1.105.1"
   }
 }

package/src/client.ts

@@ -0,0 +1,14 @@
+// `@ultimat3/render/client` — THE browser entry of this package: what an island or a page script
+// may call, and nothing that drags the rest along. The `.` barrel bare-retains `errors.ts` (render's
+// whole code table, registered at import, plus core's titles tables); this entry's graph is
+// `navigation-api.ts`, `navigation-errors.ts`, the pure rules and `@ultimat3/core/page`, held there
+// by `client-bundle.test.ts`.
+//
+//   import { navigate, openModal, refresh } from '@ultimat3/render/client';
+//
+// The same names stay exported from `.` for compatibility; an island imports them from here.
+
+export type { NavigateToOptions } from './navigation-api';
+export { closeModal, navigate, openModal, refresh } from './navigation-api';
+export { NavigationModalPathInvalidError } from './navigation-errors';
+export { NAVIGATE_EVENT, NAVIGATED_EVENT, NAVIGATION_ERROR_EVENT } from './navigation-rules';

package/src/errors.ts

@@ -222,17 +222,10 @@ export class RouteNavigationInvalidError extends UltimateError {
   }
 }
 
-/** `openModal(path)` with a path no hash can address on this origin. Thrown in the browser. */
-export class NavigationModalPathInvalidError extends UltimateError {
-  static readonly code = 'X_NAVIGATION_MODAL_PATH_INVALID' as const;
-  constructor(path: string) {
-    super({
-      code: NavigationModalPathInvalidError.code,
-      cause: `openModal(${JSON.stringify(path)}): a modal is addressed by '#<path>', and this is not an absolute path on this origin`,
-      fix: "openModal('/runs/new') — the modal route's own path, as its link carries it; never a full URL or a relative one",
-    });
-  }
-}
+// `openModal(path)` with a path no hash can address on this origin. Re-exported, never re-declared:
+// the class lives in `navigation-errors.ts` so `@ultimat3/render/client` constructs it without this
+// module's table. One class, so `instanceof` holds from either entry.
+export { NavigationModalPathInvalidError } from './navigation-errors';
 
 export class RouteLoadInvalidError extends UltimateError {
   static readonly code = 'X_ROUTE_LOAD_INVALID' as const;

package/src/index.ts

@@ -107,7 +107,11 @@ export {
   defaultIslandBudget,
   MODE_SPECS,
 } from './modes';
-/** Navigating from code — through the router when the page has one, the browser's load when not. */
+/**
+ * Navigating from code — through the router when the page has one, the browser's load when not.
+ * Kept here for compatibility; an island imports them from `@ultimat3/render/client` (`client.ts`),
+ * whose graph does not retain this barrel's `errors.ts` and the code tables behind it.
+ */
 export type { NavigateToOptions } from './navigation-api';
 export { closeModal, navigate, openModal, refresh } from './navigation-api';
 /** Client-side navigation over server-rendered documents — `navigation: { client }` surfaces. */

package/src/navigation-api.ts

@@ -7,8 +7,8 @@
  * only: an island that navigates never ships the router.
  */
 
-import { NavigationModalPathInvalidError } from './errors';
 import type { NavigationRouter } from './navigation';
+import { NavigationModalPathInvalidError } from './navigation-errors';
 import { modalAddress } from './navigation-modal-rules';
 
 export interface NavigateToOptions {

package/src/navigation-errors.ts

@@ -0,0 +1,21 @@
+/**
+ * The one refusal a BROWSER can reach in this package — `openModal`'s — apart from `errors.ts` for
+ * bytes: that module registers render's whole code table at import, and an island that calls
+ * `openModal` must not carry it. `errors.ts` re-exports this class, so it is ONE class wherever it is
+ * imported from and `instanceof` agrees across both entries. Without the table loaded, core titles
+ * the code from its name; the code, cause and fix are the same either way. Runs nothing at import.
+ */
+
+import { UltimateError } from '@ultimat3/core/page';
+
+/** `openModal` was handed something no `#<path>` hash can address. Rejected, never thrown. */
+export class NavigationModalPathInvalidError extends UltimateError {
+  static readonly code = 'X_NAVIGATION_MODAL_PATH_INVALID' as const;
+  constructor(path: string) {
+    super({
+      code: NavigationModalPathInvalidError.code,
+      cause: `openModal(${JSON.stringify(path)}): a modal is addressed by '#<path>', and this is not an absolute path on this origin`,
+      fix: "openModal('/runs/new') — the modal route's own path, as its link carries it; never a full URL or a relative one",
+    });
+  }
+}