@ultimat3/core 18.0.0 → 19.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "18.0.0",
+  "version": "19.1.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.1.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 {
@@ -538,6 +550,7 @@ export { safeUrl, URL_ATTRIBUTES } from './safe-url';
 export { defineService, resetServices, type ServiceFactory } from './service';
 export type { FlightJoin, Scheduler, SingleFlight, SingleFlightOptions } from './single-flight';
 export { createSingleFlight } from './single-flight';
+export { endOfLiteral, maskLiterals, QUOTES, stripComments } from './source-mask';
 export { timingSafeEqual } from './timing-safe-equal';
 export {
   frameworkVersion,

package/src/source-mask.ts

@@ -0,0 +1,118 @@
+// Reading TypeScript source without a parser: comments — and optionally string contents — replaced
+// by spaces, newlines kept so line numbers survive. Moved here from `@ultimat3/cli`'s `ts-scan.ts`
+// on 2026-09-05 because `@ultimat3/i18n`'s key extractor (tier 1) needed exactly this and could not
+// import a tier-5 package: a `// … t('…')` in a comment was a phantom key `x i18n sync` would have
+// written as `"…": "⟦…⟧"`. One masking implementation, at the tier every scanner can reach.
+
+// `ReadonlySet`, so a consumer cannot mutate what every scan reads.
+export const QUOTES: ReadonlySet<string> = new Set(["'", '"', '`']);
+const WORD = /[\w$]/;
+
+/** After one of these words a `/` opens a regex; after any other identifier it divides. */
+const REGEX_AFTER_WORDS = new Set(
+  'await case delete do else in instanceof new of return throw typeof void yield'.split(' '),
+);
+
+/**
+ * Index just past the closing quote of the literal opening at `from`, or `from + 1` when a `'`/`"`
+ * does not close on its own line — which makes it text, not a literal. Only a template literal may
+ * span a newline, so the apostrophe in `<p>Don't panic</p>` is JSX text; read as an opener it ran
+ * forward to the next `'` in the FILE (the next `fix:` line) and blanked every declaration between,
+ * silently emptying the `errors` gate for the whole file. Same rule `endOfRegex` applies to a `/`.
+ * An escaped newline is still a continuation: the escape is consumed before the line test.
+ */
+export function endOfLiteral(text: string, from: number): number {
+  const quote = text[from] as string;
+  const spansLines = quote === '`';
+  for (let i = from + 1; i < text.length; i += 1) {
+    if (text[i] === '\\') i += 1;
+    else if (text[i] === quote) return i + 1;
+    else if (!spansLines && text[i] === '\n') return from + 1;
+  }
+  return spansLines ? text.length : from + 1;
+}
+
+/**
+ * Whether the `/` at `at` opens a regex rather than divides — the call no scanner without a parser
+ * avoids. A regex cannot follow what ends an expression: an identifier that is not one of the words
+ * above, a number, `)`, `]`, a string's closing quote. Every other position is an operator's and
+ * opens one; `</` and `/>` are JSX delimiters. Read from the masked prefix, so a comment is space.
+ */
+function opensRegex(out: readonly string[], at: number): boolean {
+  if (out[at + 1] === '>') return false;
+  let i = at - 1;
+  while (i >= 0 && /\s/.test(out[i] as string)) i -= 1;
+  if (i < 0) return true;
+  const ch = out[i] as string;
+  if (ch === '<' || ch === ')' || ch === ']' || QUOTES.has(ch)) return false;
+  if (!WORD.test(ch)) return true;
+  let start = i;
+  while (start >= 0 && WORD.test(out[start] as string)) start -= 1;
+  return REGEX_AFTER_WORDS.has(out.slice(start + 1, i + 1).join(''));
+}
+
+/**
+ * Index just past the closing `/` of the regex opening at `from`, or `from + 1` when it does not
+ * close on its own line — a literal may not span one, so an unterminated candidate was a division
+ * or a JSX delimiter after all. A `/` inside a `[…]` class does not close the literal.
+ */
+function endOfRegex(text: string, from: number): number {
+  let inClass = false;
+  let escaped = false;
+  for (let i = from + 1; i < text.length; i += 1) {
+    const ch = text[i];
+    if (ch === '\n') break;
+    if (escaped) escaped = false;
+    else if (ch === '\\') escaped = true;
+    else if (inClass) inClass = ch !== ']';
+    else if (ch === '[') inClass = true;
+    else if (ch === '/') return i + 1;
+  }
+  return from + 1;
+}
+
+/**
+ * Comments — and optionally string contents — replaced by spaces, newlines kept so line numbers
+ * survive and quote delimiters kept so the caller can still find where a literal starts and ends.
+ * A regex body is masked the same way: `/(['"`])/` holds three quotes that delimit nothing, and
+ * reading one as an opening quote desyncs every literal after it.
+ */
+function blankRegions(text: string, strings: boolean): string {
+  // `split('')` and NOT `[...text]`: the spread yields one element per CODE POINT while every
+  // index below runs over UTF-16 units (`text.length`, `text[i]`). One astral character — an emoji
+  // in a fixture, `piñata 🎉` — and `out` is shorter than `text`, so every write past it lands a
+  // slot early and the returned mask no longer aligns with the input. Measured: 22 files in this
+  // tree desynced, shipped source included, and eight rules read this mask.
+  const out = text.split('');
+  const blank = (from: number, to: number): void => {
+    for (let n = from; n < to; n += 1) if (out[n] !== '\n') out[n] = ' ';
+  };
+  let i = 0;
+  while (i < text.length) {
+    const ch = text[i] as string;
+    if (ch === '/' && (text[i + 1] === '/' || text[i + 1] === '*')) {
+      const line = text[i + 1] === '/';
+      const end = line ? text.indexOf('\n', i) : text.indexOf('*/', i + 2);
+      const stop = end === -1 ? text.length : line ? end : end + 2;
+      blank(i, stop);
+      i = stop;
+      continue;
+    }
+    // Not code: a regex body or a literal. `end === i + 1` blanks nothing and steps one char.
+    const end =
+      ch === '/' && opensRegex(out, i)
+        ? endOfRegex(text, i)
+        : QUOTES.has(ch)
+          ? endOfLiteral(text, i)
+          : i + 1;
+    if (strings) blank(i + 1, end - 1);
+    i = end;
+  }
+  return out.join('');
+}
+
+/** Comments gone, string literals intact — what a scan for declared codes or `t()` keys reads. */
+export const stripComments = (text: string): string => blankRegions(text, false);
+
+/** Comments and string contents gone, delimiters kept — what a scan for code structure reads. */
+export const maskLiterals = (text: string): string => blankRegions(text, true);