cursedbelt-core 1.0.0

package/src/core/tokens/registry.ts

@@ -0,0 +1,536 @@
+/**
+ * The closed token set — the compile-time vocabulary every wire is drawn from
+ * (04 §2 V3). A `PortSpec` may only reference a `TokenDef` obtained from this
+ * registry; anything hand-declared fails V3 `token-not-registered`, which is
+ * what makes "compatible" a decidable property instead of a naming convention.
+ *
+ * Compatibility is **lattice membership**, not string equality: a wire connects
+ * iff `produced ⊑ consumed` under the reflexive-transitive closure of
+ * `subtypeOf`. String equality is retired — it forced every producer of a
+ * narrower thing (a photo feed) to lie about its type to reach a consumer of
+ * the wider thing (a media grid).
+ *
+ * Staging plugins extend the set at design time through `x-<pluginId>:*` ids
+ * (01 §5.2). Three laws keep the extension mechanism from corrupting the core
+ * vocabulary, all enforced here and reported by V3:
+ *   - namespace: an extension id must be `x-<pluginId>:<name>`;
+ *   - collision: an extension may never redeclare a base id;
+ *   - inversion: a core token may never declare an extension as its supertype
+ *     (the core would stop compiling the moment the plugin is deleted).
+ */
+import { z } from 'zod';
+
+export type TokenMode = 'value' | 'signal';
+
+/** JSON-Schema description of a token payload — the unit of structural comparison (J4-D). */
+export type SchemaShape = Record<string, unknown>;
+
+export interface TokenDeprecation {
+  replacedBy: string;
+  /** Free-form marker of when the deprecation started; surfaced in the V3 warning. */
+  since: string;
+}
+
+export interface TokenDef<S extends z.ZodType = z.ZodType> {
+  /** `<namespace>:<name>` — namespace is an engine id or `x-<pluginId>` for staging. */
+  id: string;
+  mode: TokenMode;
+  schema: S;
+  /** Parent token id; the single lattice edge. Absent ⇒ a lattice root. */
+  subtypeOf?: string;
+  /** Canonical payload injected by the V7.4 wire smoke probe. Must satisfy `schema`. */
+  sample: z.infer<S>;
+  /** True when this token receives third-party traffic — triggers the V3 marshaller gates. */
+  external?: boolean;
+  deprecated?: TokenDeprecation;
+  description: string;
+}
+
+/**
+ * 02 §7.1 — the only entry point for external payloads.
+ *
+ * Both symbols are DEFINED in `core/wire/marshalling.ts` beside the runtime that
+ * enforces them, and re-exported here because every existing importer (V3,
+ * `verify/types.ts`, the fixtures) reaches for them through the token registry.
+ * They used to be a second, divergent declaration of the same names — see the
+ * unification note on `CCWireMarshaller` (05 §B1).
+ */
+import type { CCWireMarshaller } from '../wire/marshalling';
+
+export {
+  type CCWireMarshaller,
+  MARSHALLER_WORKER_OFFLOAD_BYTES,
+  requiresWorkerOffload,
+} from '../wire/marshalling';
+
+export type TokenRegistryIssueCode =
+  | 'token-collision'
+  | 'token-namespace-violation'
+  | 'subtype-inversion'
+  | 'token-supertype-missing'
+  | 'token-subtype-cycle'
+  | 'token-sample-invalid';
+
+export interface TokenRegistryIssue {
+  code: TokenRegistryIssueCode;
+  tokenId: string;
+  message: string;
+  /** Set for harvested extensions so V3 can point the diagnostic at the source file. */
+  path?: string;
+}
+
+const TOKEN_ID_RE = /^[a-z][a-z0-9-]*:[a-z0-9-]+$/;
+const EXTENSION_ID_RE = /^x-[a-z0-9-]+:[a-z0-9-]+$/;
+
+export const isExtensionTokenId = (id: string): boolean => id.startsWith('x-');
+
+/** `x-habits:mark` ⇒ `habits`; `media:videos` ⇒ `media`. */
+export const namespaceOf = (id: string): string => id.slice(0, id.indexOf(':'));
+
+/** `x-habits:mark` ⇒ `plugin-habits`. */
+export const stagingPluginOf = (id: string): string => `plugin-${namespaceOf(id).slice('x-'.length)}`;
+
+/**
+ * Normalized structural description of a token payload. Two schemas that were
+ * authored independently in two repos still compare, which is the whole point of
+ * the J4-D fallback: identity is the fast path, structure is the truth.
+ */
+export function describeSchema(schema: z.ZodType): SchemaShape {
+  const described = z.toJSONSchema(schema, { io: 'output', unrepresentable: 'any' }) as SchemaShape;
+  const { $schema: _ignored, ...rest } = described;
+  return rest;
+}
+
+export type SchemaComparison = 'identical' | 'backward-compatible-extension' | 'divergent';
+
+const stableStringify = (value: unknown): string => {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null';
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
+  const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(',')}}`;
+};
+
+/**
+ * Compare a producer's payload shape against the consumer's canonical shape.
+ *
+ * `backward-compatible-extension` means the producer satisfies every requirement
+ * the consumer states AND everything it adds is optional — a consumer written
+ * against the older shape still validates every payload the newer producer
+ * emits. Anything else is drift: same token id, different contract, silent
+ * runtime breakage (the `media:video-ref` `{id}` vs `{id,name}` class).
+ */
+export function compareSchemaShapes(producer: SchemaShape, consumer: SchemaShape): SchemaComparison {
+  return compareNodes(producer, consumer);
+}
+
+/**
+ * The comparison recurses, because the interesting skew is never at the top
+ * level: a producer that added an optional `caption` to each item of
+ * `{ items: [...] }` differs only three levels down, and a shallow compare would
+ * call that drift and block a build for no reason.
+ */
+function compareNodes(producer: unknown, consumer: unknown): SchemaComparison {
+  if (stableStringify(producer) === stableStringify(consumer)) return 'identical';
+  if (typeof producer !== 'object' || producer === null || typeof consumer !== 'object' || consumer === null)
+    return 'divergent';
+
+  const producerNode = producer as Record<string, unknown>;
+  const consumerNode = consumer as Record<string, unknown>;
+
+  if (producerNode.type === 'array' && consumerNode.type === 'array') return compareNodes(producerNode.items, consumerNode.items);
+
+  const producerProps = (producerNode.properties ?? null) as Record<string, unknown> | null;
+  const consumerProps = (consumerNode.properties ?? null) as Record<string, unknown> | null;
+  if (producerNode.type !== 'object' || consumerNode.type !== 'object' || !producerProps || !consumerProps) return 'divergent';
+
+  const producerRequired = new Set((producerNode.required as string[] | undefined) ?? []);
+  const consumerRequired = new Set((consumerNode.required as string[] | undefined) ?? []);
+
+  const widen = (current: SchemaComparison, next: SchemaComparison): SchemaComparison => {
+    if (current === 'divergent' || next === 'divergent') return 'divergent';
+    if (current === 'backward-compatible-extension' || next === 'backward-compatible-extension')
+      return 'backward-compatible-extension';
+    return 'identical';
+  };
+
+  let verdict: SchemaComparison = 'identical';
+
+  for (const [key, consumerProp] of Object.entries(consumerProps)) {
+    const producerProp = producerProps[key];
+    if (producerProp === undefined) return 'divergent'; // a field the consumer needs and the producer never emits
+    if (consumerRequired.has(key) && !producerRequired.has(key)) return 'divergent'; // may arrive absent
+    verdict = widen(verdict, compareNodes(producerProp, consumerProp));
+    if (verdict === 'divergent') return 'divergent';
+  }
+
+  for (const key of Object.keys(producerProps)) {
+    if (key in consumerProps) continue;
+    // A required extra field is NOT backward compatible: a consumer that echoes
+    // the payload back through the same token would fail the producer's schema.
+    if (producerRequired.has(key)) return 'divergent';
+    verdict = widen(verdict, 'backward-compatible-extension');
+  }
+
+  return verdict;
+}
+
+export interface ConnectResult {
+  ok: boolean;
+  reason?: 'unknown-produced' | 'unknown-consumed' | 'mode-mismatch' | 'not-a-subtype';
+  message?: string;
+}
+
+export class TokenRegistry {
+  private readonly tokens = new Map<string, TokenDef>();
+  private readonly marshallers = new Map<string, CCWireMarshaller>();
+  private readonly shapes = new Map<string, SchemaShape>();
+
+  constructor(base: readonly TokenDef[] = []) {
+    const issues = this.registerAll(base, { origin: 'base' });
+    if (issues.length > 0) {
+      // Base tokens are authored code, not user data — a broken base registry is a
+      // programming error that must never reach a diagnostic list.
+      throw new Error(`Invalid base token registry: ${issues.map((i) => `${i.code} (${i.tokenId})`).join(', ')}`);
+    }
+  }
+
+  /**
+   * Register harvested staging extensions. Returns issues rather than throwing:
+   * these ids come from files on disk, so they are data and belong in the
+   * diagnostic list (V3), not in a crash.
+   */
+  registerAll(defs: readonly TokenDef[], opts: { origin: 'base' | 'staging'; path?: string } = { origin: 'staging' }): TokenRegistryIssue[] {
+    const issues: TokenRegistryIssue[] = [];
+    const accepted: TokenDef[] = [];
+
+    for (const def of defs) {
+      const path = opts.path;
+      // Collision is checked BEFORE the namespace laws: an extension that
+      // redeclares `media:videos` is a collision, and saying "bad namespace"
+      // would send the author to fix the wrong thing.
+      if (this.tokens.has(def.id)) {
+        issues.push({
+          code: 'token-collision',
+          tokenId: def.id,
+          path,
+          message: `Token '${def.id}' is already declared by the base registry — a staging extension may extend the vocabulary, never redefine it.`,
+        });
+        continue;
+      }
+      if (!TOKEN_ID_RE.test(def.id)) {
+        issues.push({
+          code: 'token-namespace-violation',
+          tokenId: def.id,
+          path,
+          message: `Token id '${def.id}' is not '<namespace>:<name>' in kebab-case.`,
+        });
+        continue;
+      }
+      if (opts.origin === 'staging' && !EXTENSION_ID_RE.test(def.id)) {
+        issues.push({
+          code: 'token-namespace-violation',
+          tokenId: def.id,
+          path,
+          message: `Staging token '${def.id}' must be namespaced 'x-<pluginId>:<name>'.`,
+        });
+        continue;
+      }
+      if (opts.origin === 'base' && isExtensionTokenId(def.id)) {
+        issues.push({
+          code: 'token-namespace-violation',
+          tokenId: def.id,
+          path,
+          message: `Base token '${def.id}' may not use the reserved staging 'x-' namespace.`,
+        });
+        continue;
+      }
+      const sampleCheck = def.schema.safeParse(def.sample);
+      if (!sampleCheck.success) {
+        issues.push({
+          code: 'token-sample-invalid',
+          tokenId: def.id,
+          path,
+          message: `Token '${def.id}' sample payload does not satisfy its own schema: ${sampleCheck.error.issues[0]?.message ?? 'invalid'}.`,
+        });
+        continue;
+      }
+      this.tokens.set(def.id, def);
+      this.shapes.set(def.id, describeSchema(def.schema));
+      accepted.push(def);
+    }
+
+    // Lattice edges are validated after the batch lands: a staging catalog may
+    // declare a child before its parent within the same file.
+    for (const def of accepted) {
+      const parentId = def.subtypeOf;
+      if (parentId === undefined) continue;
+      const parent = this.tokens.get(parentId);
+      if (!parent) {
+        issues.push({
+          code: 'token-supertype-missing',
+          tokenId: def.id,
+          path: opts.path,
+          message: `Token '${def.id}' declares supertype '${parentId}', which is not registered.`,
+        });
+        this.tokens.delete(def.id);
+        this.shapes.delete(def.id);
+        continue;
+      }
+      if (!isExtensionTokenId(def.id) && isExtensionTokenId(parentId)) {
+        issues.push({
+          code: 'subtype-inversion',
+          tokenId: def.id,
+          path: opts.path,
+          message: `Core token '${def.id}' declares staging extension '${parentId}' as its supertype — the core would stop compiling when the plugin is removed.`,
+        });
+        this.tokens.delete(def.id);
+        this.shapes.delete(def.id);
+        continue;
+      }
+      if (this.hasSubtypeCycle(def.id)) {
+        issues.push({
+          code: 'token-subtype-cycle',
+          tokenId: def.id,
+          path: opts.path,
+          message: `Token '${def.id}' participates in a subtypeOf cycle.`,
+        });
+        this.tokens.delete(def.id);
+        this.shapes.delete(def.id);
+      }
+    }
+
+    return issues;
+  }
+
+  registerMarshaller(marshaller: CCWireMarshaller): void {
+    this.marshallers.set(marshaller.tokenId, marshaller);
+  }
+
+  get(id: string): TokenDef | undefined {
+    return this.tokens.get(id);
+  }
+
+  has(id: string): boolean {
+    return this.tokens.has(id);
+  }
+
+  ids(): string[] {
+    return [...this.tokens.keys()].sort();
+  }
+
+  marshallerFor(tokenId: string): CCWireMarshaller | undefined {
+    return this.marshallers.get(tokenId);
+  }
+
+  shapeOf(tokenId: string): SchemaShape | undefined {
+    return this.shapes.get(tokenId);
+  }
+
+  /** The reflexive-transitive closure of `subtypeOf`: is `childId ⊑ parentId`? */
+  isSubtype(childId: string, parentId: string): boolean {
+    let cursor: string | undefined = childId;
+    const seen = new Set<string>();
+    while (cursor !== undefined) {
+      if (cursor === parentId) return true;
+      if (seen.has(cursor)) return false;
+      seen.add(cursor);
+      cursor = this.tokens.get(cursor)?.subtypeOf;
+    }
+    return false;
+  }
+
+  /** Every ancestor of a token, nearest first — used by V3 diagnostics. */
+  ancestorsOf(tokenId: string): string[] {
+    const chain: string[] = [];
+    const seen = new Set<string>();
+    let cursor = this.tokens.get(tokenId)?.subtypeOf;
+    while (cursor !== undefined && !seen.has(cursor)) {
+      chain.push(cursor);
+      seen.add(cursor);
+      cursor = this.tokens.get(cursor)?.subtypeOf;
+    }
+    return chain;
+  }
+
+  canConnect(producedId: string, consumedId: string): ConnectResult {
+    const produced = this.tokens.get(producedId);
+    const consumed = this.tokens.get(consumedId);
+    if (!produced) return { ok: false, reason: 'unknown-produced', message: `Token '${producedId}' is not registered.` };
+    if (!consumed) return { ok: false, reason: 'unknown-consumed', message: `Token '${consumedId}' is not registered.` };
+    if (produced.mode !== consumed.mode)
+      return {
+        ok: false,
+        reason: 'mode-mismatch',
+        message: `'${producedId}' is a ${produced.mode} port and '${consumedId}' is a ${consumed.mode} port.`,
+      };
+    if (!this.isSubtype(producedId, consumedId))
+      return {
+        ok: false,
+        reason: 'not-a-subtype',
+        message: `'${producedId}' is not '${consumedId}' or a subtype of it (lattice: ${
+          [producedId, ...this.ancestorsOf(producedId)].join(' ⊑ ')
+        }).`,
+      };
+    return { ok: true };
+  }
+
+  private hasSubtypeCycle(startId: string): boolean {
+    const seen = new Set<string>();
+    let cursor: string | undefined = startId;
+    while (cursor !== undefined) {
+      if (seen.has(cursor)) return true;
+      seen.add(cursor);
+      cursor = this.tokens.get(cursor)?.subtypeOf;
+    }
+    return false;
+  }
+}
+
+/* ---------------------------------------------------------------------------
+ * The base registry. Every id here is part of the app's public wire vocabulary;
+ * removing one is a breaking change that goes through the deprecation flow
+ * (02 §3.3 step 3), never a delete.
+ * ------------------------------------------------------------------------ */
+
+const MediaItemSchema = z.object({
+  id: z.string(),
+  kind: z.enum(['video', 'photo', 'file', 'audio']),
+});
+
+const VideoItemSchema = z.object({
+  id: z.string(),
+  kind: z.enum(['video', 'photo', 'file', 'audio']),
+  streamUrl: z.string().optional(),
+  hlsUrl: z.string().optional(),
+  hasHls: z.boolean().optional(),
+});
+
+export const BASE_TOKENS: readonly TokenDef[] = [
+  {
+    id: 'media:items',
+    mode: 'value',
+    description: 'Any addressable media collection — the lattice root every media feed narrows.',
+    schema: z.object({ items: z.array(MediaItemSchema) }),
+    sample: { items: [{ id: 'itm_1', kind: 'file' as const }] },
+  },
+  {
+    id: 'media:videos',
+    mode: 'value',
+    subtypeOf: 'media:items',
+    description: 'Video collection with per-item playback URLs; degrades to progressive when hls is off.',
+    schema: z.object({ items: z.array(VideoItemSchema) }),
+    sample: { items: [{ id: 'vid_1', kind: 'video' as const, streamUrl: '/api/asset/stream/vid_1' }] },
+  },
+  {
+    id: 'media:photos',
+    mode: 'value',
+    subtypeOf: 'media:items',
+    description: 'Photo collection.',
+    schema: z.object({ items: z.array(MediaItemSchema) }),
+    sample: { items: [{ id: 'pho_1', kind: 'photo' as const }] },
+  },
+  {
+    id: 'media:video-ref',
+    mode: 'value',
+    description: 'A single video selection handed between a gallery and an editor.',
+    schema: z.object({ id: z.string(), name: z.string().optional() }),
+    sample: { id: 'vid_1' },
+  },
+  {
+    id: 'asset:file-ref',
+    mode: 'value',
+    description: 'A single stored file reference.',
+    schema: z.object({ id: z.string(), mime: z.string().optional() }),
+    sample: { id: 'file_1' },
+  },
+  {
+    id: 'text:content',
+    mode: 'value',
+    description: 'Plain text body — diff panes, note editors, transcript views.',
+    schema: z.object({ text: z.string() }),
+    sample: { text: 'hello' },
+  },
+  {
+    id: 'signal:refresh',
+    mode: 'signal',
+    description: 'Scoped invalidation pulse. Fan-in target: every emission must carry a scope (03 §6.1).',
+    schema: z.object({ scope: z.string().optional() }),
+    sample: { scope: 'videos' },
+  },
+  {
+    id: 'session:private-mode',
+    mode: 'value',
+    description: 'GuardEngine session assertion. Advisory on the client; every route re-verifies (02 §4.2).',
+    schema: z.object({
+      unlocked: z.boolean(),
+      token: z.string().nullable(),
+      claims: z.unknown().nullable(),
+    }),
+    sample: { unlocked: false, token: null, claims: null },
+  },
+  {
+    id: 'nav:path',
+    mode: 'value',
+    description: 'Current client route path — replaces the deleted Breadcrumbs plugin.',
+    schema: z.object({ path: z.string() }),
+    sample: { path: '/' },
+  },
+  {
+    id: 'knowledge:conversation-ref',
+    mode: 'value',
+    description: 'A RAG conversation reference; deep-link entity for /chat/:conversationId.',
+    schema: z.object({ id: z.string() }),
+    sample: { id: 'conv_1' },
+  },
+  {
+    id: 'knowledge:note-ref',
+    mode: 'value',
+    description: 'A note reference; deep-link entity for note routes.',
+    schema: z.object({ id: z.string() }),
+    sample: { id: 'note_1' },
+  },
+  {
+    id: 'knowledge:records',
+    mode: 'value',
+    external: true,
+    description: 'Imported record rows (CSV/sheet/webhook) — external traffic, marshaller-gated (02 §7.1).',
+    schema: z.object({ rows: z.array(z.record(z.string(), z.unknown())) }),
+    sample: { rows: [{ id: '1' }] },
+  },
+  {
+    id: 'calendar:reminder',
+    mode: 'signal',
+    description: 'A due reminder pulse consumed by the notifications inbox.',
+    schema: z.object({ scope: z.string().optional(), at: z.number() }),
+    sample: { at: 0 },
+  },
+  {
+    id: 'stopwatch:toggled',
+    mode: 'signal',
+    description: 'Stopwatch widget start/stop pulse.',
+    schema: z.object({ running: z.boolean() }),
+    sample: { running: false },
+  },
+  {
+    id: 'dev:job-status',
+    mode: 'value',
+    description: 'JobBroker progress for a deploy/pipeline/promotion job.',
+    schema: z.object({
+      jobId: z.string(),
+      state: z.enum(['queued', 'running', 'done', 'failed']),
+      rev: z.number().optional(),
+    }),
+    sample: { jobId: 'job_1', state: 'queued' as const },
+  },
+  {
+    id: 'nes:rom-url',
+    mode: 'value',
+    deprecated: { replacedBy: 'asset:file-ref', since: 'core-refactor' },
+    description: 'DEPRECATED — the NES toy was pruned from the core catalog (02 §1.6).',
+    schema: z.object({ url: z.string() }),
+    sample: { url: 'about:blank' },
+  },
+];
+
+/** Fresh registry per compilation — the compiler never shares mutable state between runs. */
+export const createTokenRegistry = (): TokenRegistry => new TokenRegistry(BASE_TOKENS);

package/src/core/uiScale/index.ts

@@ -0,0 +1,32 @@
+/**
+ * UI-scale core (framework-free) — the pure model + the document/localStorage store
+ * behind the app-wide "text/UI size" accessibility control. `initUiScale()` applies
+ * the saved size on app boot (before React mounts → no flash); the React control +
+ * hook live in `cursedbelt/react`.
+ */
+export {
+  clampUiScale,
+  DEFAULT_UI_SCALE,
+  MAX_UI_SCALE,
+  MIN_UI_SCALE,
+  nearestUiScaleLevel,
+  stepUiScale,
+  UI_SCALE_LEVELS,
+  UI_SCALE_STEP,
+  type UiScaleLevel,
+  type UiScaleLevelId,
+  uiScaleToFontSize,
+} from './scale';
+export {
+  applyUiScaleToDocument,
+  createUiScaleStore,
+  getUiScale,
+  initUiScale,
+  setUiScale,
+  subscribeUiScale,
+  UI_SCALE_STORAGE_KEY,
+  type UiScaleStorage,
+  type UiScaleStore,
+  type UiScaleStoreOptions,
+  uiScaleStore,
+} from './uiScaleStore';

package/src/core/uiScale/scale.ts

@@ -0,0 +1,63 @@
+/**
+ * UI scale — the pure model behind an app-wide "text/UI size" accessibility
+ * control. A single number multiplies the document's root font-size, so every
+ * **rem-based** Tailwind utility (text, spacing, gaps, rem-sized icons) grows or
+ * shrinks together. Because the whole UI scales proportionally — like browser
+ * zoom — relative spacing, alignment, and source order are preserved by
+ * construction: there's no per-element override that could reflow things into an
+ * overlap or reorder a label below its section. (Anything sized in raw px won't
+ * scale; cwip's components are rem-first so they do.)
+ *
+ * This file is framework- and DOM-free so it's trivially testable; the React hook
+ * + the store that actually touches `document`/`localStorage` build on it.
+ */
+
+export type UiScaleLevelId = 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
+
+export interface UiScaleLevel {
+  readonly id: UiScaleLevelId;
+  readonly label: string;
+  /** Root-font-size multiplier (1 = the browser/app default). */
+  readonly scale: number;
+}
+
+/** Named presets for a simple picker. Continuous values in between are valid too. */
+export const UI_SCALE_LEVELS: readonly UiScaleLevel[] = [
+  { id: 'sm', label: 'Small', scale: 0.9 },
+  { id: 'md', label: 'Default', scale: 1 },
+  { id: 'lg', label: 'Large', scale: 1.15 },
+  { id: 'xl', label: 'Larger', scale: 1.3 },
+  { id: 'xxl', label: 'Largest', scale: 1.5 },
+];
+
+export const MIN_UI_SCALE = 0.8;
+export const MAX_UI_SCALE = 2;
+export const DEFAULT_UI_SCALE = 1;
+/** One press of the +/- stepper. */
+export const UI_SCALE_STEP = 0.1;
+
+/** Clamp to the supported range, rounded to 3 decimals; non-finite → default. */
+export function clampUiScale(n: number): number {
+  if (!Number.isFinite(n)) return DEFAULT_UI_SCALE;
+  return Math.min(MAX_UI_SCALE, Math.max(MIN_UI_SCALE, Math.round(n * 1000) / 1000));
+}
+
+/** Nudge a scale up (+1) or down (-1) by one step, clamped. */
+export function stepUiScale(scale: number, dir: 1 | -1): number {
+  return clampUiScale(scale + dir * UI_SCALE_STEP);
+}
+
+/** The preset closest to a (continuous) scale — drives a picker's active state. */
+export function nearestUiScaleLevel(scale: number): UiScaleLevel {
+  const s = clampUiScale(scale);
+  return UI_SCALE_LEVELS.reduce((best, level) =>
+    Math.abs(level.scale - s) < Math.abs(best.scale - s) ? level : best,
+  );
+}
+
+/** The CSS `font-size` value to set on the root, e.g. 1.15 → "115%". Percent (not
+ *  px) so it composes with the user's own browser base-font preference. */
+export function uiScaleToFontSize(scale: number): string {
+  const pct = Math.round(clampUiScale(scale) * 1000) / 10; // 1.15 → 115, 0.9 → 90
+  return `${pct}%`;
+}