@ultimat3/core 18.0.0 → 19.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "18.0.0",
+  "version": "19.0.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",
@@ -37,6 +37,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/schema": "18.0.0"
+    "@ultimat3/schema": "19.0.0"
   }
 }

package/src/config-pwa.ts

@@ -11,18 +11,37 @@
 // subjects (a config file, and a function argument a library caller supplies directly).
 
 import { describeValue } from './error-render';
-// `app.config.ts` CONSUMES the route vocabulary; it does not own it — `config.ts`'s rule, and the
-// reason `OfflineStrategy` is imported rather than restated.
-import type { OfflineStrategy } from './route-vocabulary';
 
 /**
  * `installPrompt` was removed 2026-08, same rule: `@ultimat3/pwa`'s `createInstallController` is
  * real and complete, nothing ever threaded the flag into it, and both tracked apps plus every
  * scaffolded app set a switch with no wire. Call the controller from your own affordance instead.
  */
+/**
+ * What the service worker needs that no route can say for itself.
+ *
+ * `fallback` is the document a navigation gets when the network is gone and the cache has no
+ * answer — the one thing an offline app cannot do without, and the reason this block replaced a
+ * bare `offline: OfflineStrategy`. That key was an app-wide DEFAULT for a field `defineRoute`
+ * makes **required** on every route (`route.ts` refuses a route without one), so it defaulted
+ * nothing, was read by nobody, and could not be given a reader without inventing a meaning for it
+ * (#390).
+ *
+ * The other three are `@ultimat3/pwa`'s `OfflineConfig` verbatim, and each is read by the emitter
+ * that builds `sw.js`: a placeholder image, a placeholder font, and the request patterns that must
+ * never be answered from a cache — auth and payments, where a stale 200 is worse than a failure.
+ */
+export interface PwaOfflineConfig {
+  /** Absolute route path of the offline document, e.g. `/offline`. Required once `enabled`. */
+  readonly fallback: string | null;
+  readonly image: string | null;
+  readonly font: string | null;
+  readonly neverCache: readonly string[];
+}
+
 export interface PwaConfig {
   readonly enabled: boolean;
-  readonly offline: OfflineStrategy;
+  readonly offline: PwaOfflineConfig;
   readonly backgroundSync: boolean;
   readonly push: boolean;
   /**
@@ -79,7 +98,7 @@ export const PWA_COLOR_KEYS = ['themeColor', 'backgroundColor'] as const;
  * boolean needs to see the complete shape and the opt-out in the same line.
  */
 export const PWA_FIX =
-  "in app.config.ts, complete the pwa block: pwa: { enabled: true, offline: 'runtime', name: 'My App', colors: { light: { themeColor: '#1b1f3b', backgroundColor: '#ffffff' }, dark: { themeColor: '#1b1f3b', backgroundColor: '#0b0d1a' } } } — a browser paints the install splash and the address bar from those four values before any stylesheet loads, so there is nothing for the framework to derive them from; or set pwa.enabled: false";
+  "in app.config.ts, complete the pwa block: pwa: { enabled: true, offline: { fallback: '/offline' }, name: 'My App', colors: { light: { themeColor: '#1b1f3b', backgroundColor: '#ffffff' }, dark: { themeColor: '#1b1f3b', backgroundColor: '#0b0d1a' } } } — a browser paints the install splash and the address bar from those four values before any stylesheet loads, so there is nothing for the framework to derive them from, and offline.fallback is the document the emitted sw.js serves when the network is gone, so add a route at that path too; or set pwa.enabled: false";
 
 /**
  * Every rule `validate` applies to the block, appended to the caller's own issue list. Answers
@@ -96,6 +115,18 @@ export function pwaIssues(pwa: PwaConfig, issues: string[]): boolean {
   if (typeof name !== 'string' || name.trim() === '') {
     issues.push(`pwa.name is required when pwa.enabled is true, and is ${describeValue(name)}`);
   }
+  // An ABSOLUTE path, screened here rather than at emit for this file's own stated reason: a
+  // relative one resolves against whatever document registered the worker, so `offline` served
+  // under `/posts/1` is `/posts/offline` — a 404 cached as the answer to every offline navigation.
+  // `pwa.enabled` means an installable app, and an installable app that shows the browser's error
+  // page offline is the failure the whole block exists to prevent, so this is required rather
+  // than optional: the alternative is two meanings for one switch (axiom 1).
+  const fallback: unknown = pwa.offline?.fallback;
+  if (typeof fallback !== 'string' || !fallback.startsWith('/')) {
+    issues.push(
+      `pwa.offline.fallback is required when pwa.enabled is true and must be an absolute route path like "/offline", and is ${describeValue(fallback)}`,
+    );
+  }
   // `typeof !== 'object' || null`, never `=== undefined`: an untyped `app.config.ts` writing
   // `pwa.colors: null` reached `null[scheme]` one line down and took the boot out with a native
   // `TypeError`, from the validator whose whole job is producing an instruction instead of one.

package/src/config.ts

@@ -7,7 +7,7 @@ import { CURRENCY_CODE_PATTERN } from '@ultimat3/schema';
 // them. Declaring them here is what let `cache.tiers` and the ladder `@ultimat3/cache` orders by
 // drift into two vocabularies with no map between them (issue #293).
 import { CACHE_TIERS, type CacheTierName } from './cache-vocabulary';
-import type { PwaConfig } from './config-pwa';
+import type { PwaConfig, PwaOfflineConfig } from './config-pwa';
 import { PWA_FIX, pwaIssues } from './config-pwa';
 import { describeValue } from './error-render';
 import { ConfigInvalidError } from './errors';
@@ -197,6 +197,17 @@ export interface AiConfigInput {
   readonly mcp?: Input<McpConfig> | undefined;
 }
 
+/**
+ * `offline` is NESTED for `AiConfigInput`'s reason, and here it is load-bearing rather than
+ * ergonomic: `section` applies a patch ONE level deep, so an app writing
+ * `offline: { fallback: '/offline' }` under a flat `Input<PwaConfig>` would replace the whole
+ * default block — leaving `image`, `font` and `neverCache` absent at run time while the type says
+ * they are there, which is the exact shape of defect this repo keeps re-shipping.
+ */
+export interface PwaConfigInput extends Omit<Input<PwaConfig>, 'offline'> {
+  readonly offline?: Input<PwaOfflineConfig> | undefined;
+}
+
 export interface AppConfigInput {
   readonly name: string;
   readonly locales?: readonly string[] | undefined;
@@ -205,7 +216,7 @@ export interface AppConfigInput {
   readonly defaultCurrency?: string | undefined;
   readonly theme?: Input<ThemeConfig> | undefined;
   readonly auth?: Input<AuthConfig> | undefined;
-  readonly pwa?: Input<PwaConfig> | undefined;
+  readonly pwa?: PwaConfigInput | undefined;
   readonly roles?: readonly Role[] | undefined;
   readonly database?: Input<DatabaseConfig> | undefined;
   readonly cache?: Input<CacheConfig> | undefined;
@@ -260,7 +271,7 @@ function defaults(name: string): Omit<AppConfig, 'name'> {
     auth: { signInPath: null },
     pwa: {
       enabled: false,
-      offline: 'network-only',
+      offline: { fallback: null, image: null, font: null, neverCache: [] },
       backgroundSync: false,
       push: false,
       name: '',
@@ -405,7 +416,13 @@ export function defineConfig(
     defaultCurrency: merged.defaultCurrency ?? base.defaultCurrency,
     theme: section(base.theme, merged.theme),
     auth: section(base.auth, merged.auth),
-    pwa: section(base.pwa, merged.pwa),
+    // Two `section` calls, one per level: the outer one may not see `offline` at all, or it would
+    // drop the nested defaults `PwaConfigInput` exists to keep. Hence the cast — the outer patch is
+    // this block minus the key the inner call owns.
+    pwa: {
+      ...section(base.pwa, { ...merged.pwa, offline: undefined } as Input<PwaConfig>),
+      offline: section(base.pwa.offline, merged.pwa?.offline),
+    },
     roles: merged.roles ?? base.roles,
     database: section(base.database, merged.database),
     cache: section(base.cache, merged.cache),

package/src/index.ts

@@ -5,6 +5,17 @@
 // secrets — because each is one subject spread over a dozen modules. Every name they carry is
 // still written out below: `export *` would make the contract something a reader has to resolve.
 
+// Anchored on purpose, and NOT by the `sideEffects` array: Bun reads any array as `false` and drops
+// the module regardless (oven-sh/bun#40650). This module registers @ultimat3/schema's error TITLES,
+// because schema is tier 0 and cannot register its own — and what reads them is `UltimateError`'s
+// constructor, which never imports this file. Shaken out, every X_VALIDATION_FAILED renders
+// untitled in the browser with nothing to say why. `SIDE_EFFECTS_ANCHORS` carries the argument and
+// `bun run side-effects` enforces it. `context.ts`, `lifecycle-errors.ts` and `secrets-errors.ts`
+// are declared side-effecting too and are deliberately NOT anchored: each is reached by whatever
+// uses it, and anchoring `context.ts` alone measured +3,485 B on a browser chunk for a provider a
+// browser can never fire.
+import './schema-error-codes';
+
 export type {
   Actor,
   ActorFactKey,
@@ -66,13 +77,14 @@ export type {
   JobsConfig,
   McpConfig,
   NotifyConfig,
+  PwaConfigInput,
   RealtimeConfig,
   RealtimeTransport,
   ThemeConfig,
   ThemeMode,
 } from './config';
 export { defineConfig, INBOX_RETENTION_KEYS } from './config';
-export type { PwaColors, PwaConfig, PwaSchemeColors } from './config-pwa';
+export type { PwaColors, PwaConfig, PwaOfflineConfig, PwaSchemeColors } from './config-pwa';
 export { PWA_COLOR_KEYS, PWA_SCHEMES } from './config-pwa';
 export type { Ctx, CtxFacts, CtxInit, CtxPatch, CtxServices, ServiceBag } from './context';
 export {