cursedbelt-core 1.0.0

package/dist/core/tokens/registry.js

@@ -0,0 +1,447 @@
+/**
+ * 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 { MARSHALLER_WORKER_OFFLOAD_BYTES, requiresWorkerOffload, } from '../wire/marshalling';
+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) => id.startsWith('x-');
+/** `x-habits:mark` ⇒ `habits`; `media:videos` ⇒ `media`. */
+export const namespaceOf = (id) => id.slice(0, id.indexOf(':'));
+/** `x-habits:mark` ⇒ `plugin-habits`. */
+export const stagingPluginOf = (id) => `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) {
+    const described = z.toJSONSchema(schema, { io: 'output', unrepresentable: 'any' });
+    const { $schema: _ignored, ...rest } = described;
+    return rest;
+}
+const stableStringify = (value) => {
+    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).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, consumer) {
+    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, consumer) {
+    if (stableStringify(producer) === stableStringify(consumer))
+        return 'identical';
+    if (typeof producer !== 'object' || producer === null || typeof consumer !== 'object' || consumer === null)
+        return 'divergent';
+    const producerNode = producer;
+    const consumerNode = consumer;
+    if (producerNode.type === 'array' && consumerNode.type === 'array')
+        return compareNodes(producerNode.items, consumerNode.items);
+    const producerProps = (producerNode.properties ?? null);
+    const consumerProps = (consumerNode.properties ?? null);
+    if (producerNode.type !== 'object' || consumerNode.type !== 'object' || !producerProps || !consumerProps)
+        return 'divergent';
+    const producerRequired = new Set(producerNode.required ?? []);
+    const consumerRequired = new Set(consumerNode.required ?? []);
+    const widen = (current, next) => {
+        if (current === 'divergent' || next === 'divergent')
+            return 'divergent';
+        if (current === 'backward-compatible-extension' || next === 'backward-compatible-extension')
+            return 'backward-compatible-extension';
+        return 'identical';
+    };
+    let verdict = '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 class TokenRegistry {
+    tokens = new Map();
+    marshallers = new Map();
+    shapes = new Map();
+    constructor(base = []) {
+        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, opts = { origin: 'staging' }) {
+        const issues = [];
+        const accepted = [];
+        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) {
+        this.marshallers.set(marshaller.tokenId, marshaller);
+    }
+    get(id) {
+        return this.tokens.get(id);
+    }
+    has(id) {
+        return this.tokens.has(id);
+    }
+    ids() {
+        return [...this.tokens.keys()].sort();
+    }
+    marshallerFor(tokenId) {
+        return this.marshallers.get(tokenId);
+    }
+    shapeOf(tokenId) {
+        return this.shapes.get(tokenId);
+    }
+    /** The reflexive-transitive closure of `subtypeOf`: is `childId ⊑ parentId`? */
+    isSubtype(childId, parentId) {
+        let cursor = childId;
+        const seen = new Set();
+        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) {
+        const chain = [];
+        const seen = new Set();
+        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, consumedId) {
+        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 };
+    }
+    hasSubtypeCycle(startId) {
+        const seen = new Set();
+        let cursor = 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 = [
+    {
+        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' }] },
+    },
+    {
+        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', 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' }] },
+    },
+    {
+        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' },
+    },
+    {
+        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 = () => new TokenRegistry(BASE_TOKENS);

package/dist/core/uiScale/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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/dist/core/uiScale/index.js

@@ -0,0 +1,8 @@
+/**
+ * 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, uiScaleToFontSize, } from './scale';
+export { applyUiScaleToDocument, createUiScaleStore, getUiScale, initUiScale, setUiScale, subscribeUiScale, UI_SCALE_STORAGE_KEY, uiScaleStore, } from './uiScaleStore';

package/dist/core/uiScale/scale.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 declare const UI_SCALE_LEVELS: readonly UiScaleLevel[];
+export declare const MIN_UI_SCALE = 0.8;
+export declare const MAX_UI_SCALE = 2;
+export declare const DEFAULT_UI_SCALE = 1;
+/** One press of the +/- stepper. */
+export declare const UI_SCALE_STEP = 0.1;
+/** Clamp to the supported range, rounded to 3 decimals; non-finite → default. */
+export declare function clampUiScale(n: number): number;
+/** Nudge a scale up (+1) or down (-1) by one step, clamped. */
+export declare function stepUiScale(scale: number, dir: 1 | -1): number;
+/** The preset closest to a (continuous) scale — drives a picker's active state. */
+export declare function nearestUiScaleLevel(scale: number): UiScaleLevel;
+/** 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 declare function uiScaleToFontSize(scale: number): string;

package/dist/core/uiScale/scale.js

@@ -0,0 +1,47 @@
+/**
+ * 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.
+ */
+/** Named presets for a simple picker. Continuous values in between are valid too. */
+export const UI_SCALE_LEVELS = [
+    { 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) {
+    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, dir) {
+    return clampUiScale(scale + dir * UI_SCALE_STEP);
+}
+/** The preset closest to a (continuous) scale — drives a picker's active state. */
+export function nearestUiScaleLevel(scale) {
+    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) {
+    const pct = Math.round(clampUiScale(scale) * 1000) / 10; // 1.15 → 115, 0.9 → 90
+    return `${pct}%`;
+}

package/dist/core/uiScale/uiScaleStore.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The UI-scale store: holds the current scale, persists it, applies it to the
+ * document root, and notifies subscribers. Split from the React hook so it works
+ * before React mounts (call {@link initUiScale} early — like a theme init — to
+ * apply the saved size with no flash) and so its logic is testable without a DOM.
+ *
+ * Side-effects (storage + applying to the page) are injected, so a test drives a
+ * real store with fakes; the exported default singleton binds them to
+ * `localStorage` + the `<html>` element.
+ */
+/** The slice of the Web Storage API the store needs (so a test can fake it). */
+export interface UiScaleStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+export interface UiScaleStore {
+    /** Current scale (lazily hydrated from storage on first read). */
+    get(): number;
+    /** Set, clamp, persist, apply, and notify. */
+    set(scale: number): void;
+    /** Nudge up (+1) / down (-1) one step. */
+    step(dir: 1 | -1): void;
+    /** Back to the default size. */
+    reset(): void;
+    /** Re-apply the persisted scale to the page (call once on app boot). */
+    init(): void;
+    subscribe(listener: () => void): () => void;
+}
+export interface UiScaleStoreOptions {
+    storage?: UiScaleStorage | null;
+    /** Apply a scale to the page. Default writes the root font-size + a CSS var. */
+    apply?: (scale: number) => void;
+    /** localStorage key. */
+    key?: string;
+}
+export declare const UI_SCALE_STORAGE_KEY = "cwip.uiScale";
+export declare function createUiScaleStore(options?: UiScaleStoreOptions): UiScaleStore;
+/** Apply a scale to the document root: scale the rem base + expose a `--cwip-ui-scale`
+ *  var (for the rare px that wants `calc(... * var(--cwip-ui-scale))`). SSR-safe. */
+export declare function applyUiScaleToDocument(scale: number): void;
+/** The app-wide singleton bound to localStorage + the page. */
+export declare const uiScaleStore: UiScaleStore;
+export declare const getUiScale: () => number;
+export declare const setUiScale: (scale: number) => void;
+export declare const subscribeUiScale: (listener: () => void) => (() => void);
+/** Apply the saved UI size on app boot, before React mounts (no flash). */
+export declare const initUiScale: () => void;

package/dist/core/uiScale/uiScaleStore.js

@@ -0,0 +1,63 @@
+/**
+ * The UI-scale store: holds the current scale, persists it, applies it to the
+ * document root, and notifies subscribers. Split from the React hook so it works
+ * before React mounts (call {@link initUiScale} early — like a theme init — to
+ * apply the saved size with no flash) and so its logic is testable without a DOM.
+ *
+ * Side-effects (storage + applying to the page) are injected, so a test drives a
+ * real store with fakes; the exported default singleton binds them to
+ * `localStorage` + the `<html>` element.
+ */
+import { clampUiScale, DEFAULT_UI_SCALE, stepUiScale, uiScaleToFontSize } from './scale';
+export const UI_SCALE_STORAGE_KEY = 'cwip.uiScale';
+export function createUiScaleStore(options = {}) {
+    const { storage = null, apply, key = UI_SCALE_STORAGE_KEY } = options;
+    const listeners = new Set();
+    let current; // undefined until first hydrate
+    const hydrate = () => {
+        if (current !== undefined)
+            return current;
+        const raw = storage?.getItem(key);
+        current = raw != null ? clampUiScale(Number.parseFloat(raw)) : DEFAULT_UI_SCALE;
+        return current;
+    };
+    const commit = (next) => {
+        const clamped = clampUiScale(next);
+        current = clamped;
+        storage?.setItem(key, String(clamped));
+        apply?.(clamped);
+        for (const l of listeners)
+            l();
+    };
+    return {
+        get: hydrate,
+        set: commit,
+        step: (dir) => commit(stepUiScale(hydrate(), dir)),
+        reset: () => commit(DEFAULT_UI_SCALE),
+        init: () => apply?.(hydrate()),
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+    };
+}
+/** Apply a scale to the document root: scale the rem base + expose a `--cwip-ui-scale`
+ *  var (for the rare px that wants `calc(... * var(--cwip-ui-scale))`). SSR-safe. */
+export function applyUiScaleToDocument(scale) {
+    if (typeof document === 'undefined')
+        return;
+    const root = document.documentElement;
+    root.style.fontSize = uiScaleToFontSize(scale);
+    root.style.setProperty('--cwip-ui-scale', String(clampUiScale(scale)));
+}
+const defaultStorage = typeof localStorage !== 'undefined' ? localStorage : null;
+/** The app-wide singleton bound to localStorage + the page. */
+export const uiScaleStore = createUiScaleStore({
+    storage: defaultStorage,
+    apply: applyUiScaleToDocument,
+});
+export const getUiScale = () => uiScaleStore.get();
+export const setUiScale = (scale) => uiScaleStore.set(scale);
+export const subscribeUiScale = (listener) => uiScaleStore.subscribe(listener);
+/** Apply the saved UI size on app boot, before React mounts (no flash). */
+export const initUiScale = () => uiScaleStore.init();

package/dist/core/wire/__fixtures__/rowsMarshalWorker.d.ts

@@ -0,0 +1 @@
+export {};