cursedbelt-core 1.0.0

package/src/core/wire/marshalling.ts

@@ -0,0 +1,238 @@
+/**
+ * Port marshalling + the 512KB worker gate (02 §7.1).
+ *
+ * External payloads — webhooks, third-party feeds, spreadsheet imports — never
+ * touch component code. A marshaller registered on the token is the only entry,
+ * and its `transform` output is checked against the token's canonical Zod schema
+ * (V3 asserts this statically; here it is enforced at runtime too, because a
+ * provider can change its shape without anyone recompiling).
+ *
+ * **The size boundary is the interesting part.** Inbound payloads over 512KB are
+ * never validated or transformed on the main thread: a 4MB webhook body running
+ * a synchronous Zod parse blocks the request loop on the server and the render
+ * thread in the browser, and the symptom — "the app freezes sometimes" —
+ * is nearly impossible to trace back to one large payload. Above the threshold
+ * the work is offloaded to a Worker (structured-clone in, validated result out).
+ */
+import type { z } from 'zod';
+import { AppError } from '../../shared/errors';
+
+/** Above this, `validate` + `transform` are offloaded to a Worker (02 §7.1). */
+export const MARSHALLER_WORKER_OFFLOAD_BYTES = 512 * 1024;
+
+/**
+ * The ONE marshaller contract (05 §B1, unified 2026-07-26).
+ *
+ * There were TWO interfaces of this name in this package: this one, and a
+ * divergent copy in `core/tokens/registry.ts` that additionally required
+ * `tokenId` and `workerOffload` — with `MARSHALLER_WORKER_OFFLOAD_BYTES`
+ * declared twice alongside them. The verify pipeline (V3, `verify/types.ts`, the
+ * fixtures) read the registry's shape; `marshalInbound` below read this one. So a
+ * value that satisfied the runtime could be rejected by the type the pipeline
+ * checks, and the two thresholds could drift apart silently. The registry's
+ * shape won — it is the one the pipeline enforces — and `registry.ts` now
+ * re-exports both symbols from here.
+ */
+export interface CCWireMarshaller<Inbound = unknown, Out = unknown> {
+  id: string;
+  /** The wire token this marshaller feeds — V3 resolves it against the registry. */
+  tokenId: string;
+  /** REQUIRED — V3 `marshaller-payload-unbounded` when absent or non-positive. */
+  maxPayloadBytes: number;
+  /**
+   * The module that runs this marshaller's `validate`+`transform` off the main
+   * thread — an entry calling `serveMarshalWorker` (`core/wire/marshalWorker.ts`).
+   *
+   * **This replaced a `workerOffload: boolean` in the Worker commit (05 §B1).**
+   * That flag was authored by hand and asserted a capability the codebase did
+   * not have: every marshaller in the repo set it `true` while no worker
+   * existed anywhere, so the V3 gate it fed was checking that someone had
+   * remembered to type `true`. Whether a marshaller can offload is now a
+   * question about an ARTIFACT — this entry either exists or it does not — and
+   * whether it NEEDS to is {@link requiresWorkerOffload}, derived from
+   * `maxPayloadBytes`. Neither is a promise anyone can make by hand.
+   *
+   * Optional because a marshaller whose `maxPayloadBytes` sits under the
+   * main-thread limit can never reach the offload path; V3 requires it of
+   * exactly those that can.
+   */
+  workerEntry?: string;
+  validate(inbound: Inbound): boolean;
+  transform(inbound: Inbound): Out;
+  /** V3 checks `transform` output against the token's canonical schema. */
+  targetZodSchema: z.ZodType<Out>;
+}
+
+/**
+ * Can this marshaller ever reach the offload path? A DERIVED fact (05 §B1).
+ *
+ * A marshaller that refuses anything over 256KB can never produce a payload
+ * above the 512KB main-thread limit, so it needs no worker and demanding one
+ * would be noise. One whose ceiling is 2MB certainly can, and without a
+ * `workerEntry` its large payloads are a guaranteed 503 — which is why V3
+ * refuses to verify that combination rather than letting it surface in
+ * production as an intermittent failure on the biggest imports.
+ */
+export function requiresWorkerOffload(
+  marshaller: Pick<CCWireMarshaller, 'maxPayloadBytes'>,
+  thresholdBytes: number = MARSHALLER_WORKER_OFFLOAD_BYTES,
+): boolean {
+  return marshaller.maxPayloadBytes > thresholdBytes;
+}
+
+export const MARSHALLER_PAYLOAD_TOO_LARGE = 'MARSHALLER_PAYLOAD_TOO_LARGE';
+export const MARSHALLER_VALIDATION_FAILED = 'MARSHALLER_VALIDATION_FAILED';
+export const MARSHALLER_SCHEMA_VIOLATION = 'MARSHALLER_SCHEMA_VIOLATION';
+
+/**
+ * Measure a payload's wire size.
+ *
+ * Uses the UTF-8 byte length, not `string.length`: a 400k-character document of
+ * CJK text is ~1.2MB on the wire, and sizing it by character count would sail
+ * past the offload threshold on the main thread.
+ */
+export function payloadBytes(payload: unknown): number {
+  if (typeof payload === 'string') return new TextEncoder().encode(payload).length;
+  if (payload instanceof ArrayBuffer) return payload.byteLength;
+  if (ArrayBuffer.isView(payload)) return payload.byteLength;
+  try {
+    return new TextEncoder().encode(JSON.stringify(payload) ?? '').length;
+  } catch {
+    // A cyclic or non-serializable payload cannot be structured-cloned into a
+    // worker either, so treat it as over-threshold and let the caller refuse.
+    return Number.POSITIVE_INFINITY;
+  }
+}
+
+/** The worker seam — injected so tests and SSR can run without a real Worker. */
+export interface MarshalWorker {
+  run<Inbound, Out>(marshallerId: string, payload: Inbound): Promise<Out>;
+}
+
+export interface MarshalOptions {
+  /**
+   * Use THIS worker instead of the one the marshaller's `workerEntry` names.
+   * Left unset in production: offload is the default path, resolved from the
+   * marshaller itself, so an ingress route needs no worker wiring of its own.
+   */
+  worker?: MarshalWorker;
+  /**
+   * Resolves a worker for a marshaller that declares a `workerEntry`. The host
+   * supplies this once (`createMarshalWorkerClient`, cached per entry) — it is a
+   * parameter rather than a module-level singleton because a worker is a live
+   * OS thread, and something has to own disposing of it.
+   */
+  resolveWorker?: (marshaller: CCWireMarshaller<never, never>) => MarshalWorker | undefined;
+  /** Override the offload threshold (tests drive it down to exercise the path). */
+  offloadThresholdBytes?: number;
+}
+
+/**
+ * Run a payload through its marshaller, offloading past the size gate.
+ *
+ * Order matters: the marshaller's OWN `maxPayloadBytes` is checked first, so an
+ * oversized payload is refused with a typed diagnostic before any work — worker
+ * or otherwise — is scheduled for it.
+ */
+export async function marshalInbound<Inbound, Out>(
+  marshaller: CCWireMarshaller<Inbound, Out>,
+  payload: Inbound,
+  options: MarshalOptions = {},
+): Promise<Out> {
+  const bytes = payloadBytes(payload);
+
+  if (bytes > marshaller.maxPayloadBytes)
+    throw new AppError(
+      `Payload of ${bytes} bytes exceeds marshaller '${marshaller.id}' limit of ${marshaller.maxPayloadBytes}.`,
+      {
+        code: MARSHALLER_PAYLOAD_TOO_LARGE,
+        status: 413,
+        context: { marshaller: marshaller.id, bytes, maxPayloadBytes: marshaller.maxPayloadBytes },
+      },
+    );
+
+  const threshold = options.offloadThresholdBytes ?? MARSHALLER_WORKER_OFFLOAD_BYTES;
+
+  if (bytes > threshold) {
+    // Offload is the DEFAULT path (05 §B1): an explicitly injected worker wins,
+    // otherwise the marshaller's own `workerEntry` is resolved through the host's
+    // resolver. Neither present means this marshaller has no offload path at all
+    // — which V3 refuses to verify, so a verified app never reaches this throw.
+    const worker =
+      options.worker ??
+      (marshaller.workerEntry ? options.resolveWorker?.(marshaller as CCWireMarshaller<never, never>) : undefined);
+    if (!worker)
+      throw new AppError(
+        `Payload of ${bytes} bytes exceeds the ${threshold}-byte main-thread limit and marshaller '${marshaller.id}' has no marshalling worker.`,
+        {
+          code: MARSHALLER_PAYLOAD_TOO_LARGE,
+          status: 503,
+          context: {
+            marshaller: marshaller.id,
+            bytes,
+            threshold,
+            workerEntry: marshaller.workerEntry ?? null,
+            hint: marshaller.workerEntry
+              ? 'The marshaller declares a workerEntry but no resolveWorker was supplied — pass createMarshalWorkerClient through MarshalOptions.resolveWorker.'
+              : 'Give the marshaller a workerEntry (a module calling serveMarshalWorker), or lower maxPayloadBytes below the main-thread limit.',
+          },
+        },
+      );
+    // The worker validates AND transforms; the result still gets schema-checked
+    // below, because a worker is a thread boundary, not a trust boundary.
+    const result = await worker.run<Inbound, Out>(marshaller.id, payload);
+    return assertSchema(marshaller, result);
+  }
+
+  if (!marshaller.validate(payload))
+    throw new AppError(`Inbound payload rejected by marshaller '${marshaller.id}'.`, {
+      code: MARSHALLER_VALIDATION_FAILED,
+      status: 400,
+      context: { marshaller: marshaller.id },
+    });
+
+  return assertSchema(marshaller, marshaller.transform(payload));
+}
+
+/**
+ * The canonical-schema check every path funnels through. Running it on the
+ * worker result too is what stops a drifting provider shape from entering the
+ * hub as a well-typed lie.
+ */
+function assertSchema<Inbound, Out>(marshaller: CCWireMarshaller<Inbound, Out>, value: Out): Out {
+  const parsed = marshaller.targetZodSchema.safeParse(value);
+  if (!parsed.success)
+    throw new AppError(`Marshaller '${marshaller.id}' produced output that violates its token's schema.`, {
+      code: MARSHALLER_SCHEMA_VIOLATION,
+      status: 502,
+      context: {
+        marshaller: marshaller.id,
+        issues: parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`),
+      },
+    });
+  return parsed.data;
+}
+
+/** The registry of marshallers, keyed by token id (02 §7.1: registered ON the token). */
+export interface MarshallerRegistry {
+  register(tokenId: string, marshaller: CCWireMarshaller): void;
+  forToken(tokenId: string): CCWireMarshaller | undefined;
+  all(): readonly { tokenId: string; marshaller: CCWireMarshaller }[];
+}
+
+export function createMarshallerRegistry(): MarshallerRegistry {
+  const byToken = new Map<string, CCWireMarshaller>();
+  return {
+    register(tokenId, marshaller) {
+      if (marshaller.maxPayloadBytes === undefined || marshaller.maxPayloadBytes <= 0)
+        throw new AppError(`Marshaller '${marshaller.id}' must declare a positive maxPayloadBytes.`, {
+          code: 'marshaller-payload-unbounded',
+          status: 500,
+          context: { marshaller: marshaller.id, tokenId },
+        });
+      byToken.set(tokenId, marshaller);
+    },
+    forToken: (tokenId) => byToken.get(tokenId),
+    all: () => [...byToken.entries()].map(([tokenId, marshaller]) => ({ tokenId, marshaller })),
+  };
+}

package/src/core/wire/wireHub.spec.ts

@@ -0,0 +1,137 @@
+import { describe, expect, it } from 'bun:test';
+import { createInstanceRuntime, createWireHub, type WireEnvelope } from './wireHub';
+
+const envelope = <T>(rev: number, payload: T, scope?: string): WireEnvelope<T> => ({ rev, at: rev, payload, scope });
+
+describe('wire hub — settle by revision (R-5)', () => {
+  it('delivers a new rev and drops a repeat of the same rev', () => {
+    const hub = createWireHub();
+    const seen: number[] = [];
+    hub.subscribe<number>('gallery:videos-out', (e) => seen.push(e.payload));
+
+    expect(hub.emit('gallery:videos-out', envelope(1, 10))).toBe('delivered');
+    expect(hub.emit('gallery:videos-out', envelope(1, 10))).toBe('settled');
+    expect(hub.emit('gallery:videos-out', envelope(2, 20))).toBe('delivered');
+    expect(seen).toEqual([10, 20]);
+  });
+
+  it('is inert against a producer that re-allocates an equal payload every tick', () => {
+    const hub = createWireHub();
+    let deliveries = 0;
+    hub.subscribe('gallery:videos-out', () => {
+      deliveries += 1;
+    });
+    for (let i = 0; i < 50; i++) hub.emit('gallery:videos-out', envelope(7, { items: [{ id: 'a' }] }));
+    expect(deliveries).toBe(1); // object identity is irrelevant; rev decides
+  });
+
+  it('retains the last value for late subscribers', () => {
+    const hub = createWireHub();
+    hub.emit('gallery:videos-out', envelope(3, 'payload'));
+    expect(hub.retained<string>('gallery:videos-out')?.payload).toBe('payload');
+  });
+
+  it('trips the storm breaker past the channel budget', () => {
+    const hub = createWireHub({ stormBudget: 5, windowMs: 10_000, now: () => 0 });
+    const outcomes: string[] = [];
+    for (let rev = 1; rev <= 8; rev++) outcomes.push(hub.emit('noisy:port', envelope(rev, rev)));
+    expect(outcomes.filter((o) => o === 'breaker-tripped').length).toBe(3);
+    expect(hub.breakerTrips()[0]?.channel).toBe('noisy:port');
+  });
+
+  it('removes a listener on teardown', () => {
+    const hub = createWireHub();
+    const off = hub.subscribe('a:b', () => {});
+    expect(hub.listenerCount('a:b')).toBe(1);
+    off();
+    expect(hub.listenerCount('a:b')).toBe(0);
+  });
+});
+
+describe('instance runtime — two-tier subscriptions (R-4 ∧ J3-3)', () => {
+  it('records only {dirty,lastRev} in the ledger, never a payload copy', async () => {
+    const hub = createWireHub();
+    const runtime = createInstanceRuntime({ id: 'notes', hub, intakeChannels: ['notes:refresh-in'] });
+    await runtime.onLoad();
+    await runtime.onReady();
+
+    hub.emit('notes:refresh-in', envelope(4, { huge: 'payload' }));
+    const entry = runtime.ledger().get('notes:refresh-in');
+    expect(entry).toEqual({ dirty: true, lastRev: 4 });
+    expect(JSON.stringify(entry)).not.toContain('huge');
+  });
+
+  it('pulls the retained envelope on mount only when the ledger is ahead', async () => {
+    const hub = createWireHub();
+    const runtime = createInstanceRuntime({ id: 'notes', hub, intakeChannels: ['notes:refresh-in'] });
+    await runtime.onLoad();
+    await runtime.onReady();
+
+    hub.emit('notes:refresh-in', envelope(9, 'fresh'));
+    expect(runtime.pullIfDirty<string>('notes:refresh-in', 8)?.payload).toBe('fresh');
+    expect(runtime.ledger().get('notes:refresh-in')?.dirty).toBe(false);
+    expect(runtime.pullIfDirty('notes:refresh-in', 9)).toBeUndefined();
+  });
+
+  it('tears intake down at unmount so navigation cannot accumulate listeners', async () => {
+    const hub = createWireHub();
+    const runtime = createInstanceRuntime({ id: 'notes', hub, intakeChannels: ['notes:refresh-in'] });
+    await runtime.onLoad();
+    await runtime.onReady();
+    expect(hub.listenerCount('notes:refresh-in')).toBe(1);
+    runtime.onUnmount();
+    expect(hub.listenerCount('notes:refresh-in')).toBe(0);
+  });
+});
+
+describe('instance runtime — lifecycle and abort interception', () => {
+  it('enforces onLoad → onReady ordering', async () => {
+    const hub = createWireHub();
+    const runtime = createInstanceRuntime({ id: 'x', hub, intakeChannels: [] });
+    await runtime.onReady();
+    expect(runtime.lifecycleErrors()[0]).toContain('onReady called in phase');
+  });
+
+  it('reports a double unmount', async () => {
+    const hub = createWireHub();
+    const runtime = createInstanceRuntime({ id: 'x', hub, intakeChannels: [] });
+    await runtime.onLoad();
+    await runtime.onReady();
+    runtime.onUnmount();
+    runtime.onUnmount();
+    expect(runtime.lifecycleErrors()).toContain('onUnmount called twice');
+  });
+
+  it('no-ops a state write that arrives after unmount', async () => {
+    const hub = createWireHub();
+    const runtime = createInstanceRuntime({ id: 'x', hub, intakeChannels: [] });
+    await runtime.onLoad();
+    await runtime.onReady();
+
+    let value = 0;
+    const apply = runtime.guarded<number>((next) => {
+      value = next;
+    });
+    expect(apply(1)).toBe(true);
+    runtime.onUnmount();
+    expect(apply(2)).toBe(false);
+    expect(value).toBe(1);
+  });
+
+  it('aborts the view scope on suspend and the instance scope on unmount', async () => {
+    const hub = createWireHub();
+    const runtime = createInstanceRuntime({ id: 'x', hub, intakeChannels: [] });
+    await runtime.onLoad();
+    await runtime.onReady();
+
+    const viewSignal = runtime.viewSignal();
+    runtime.onSuspend();
+    expect(viewSignal.aborted).toBe(true);
+    expect(runtime.signal.aborted).toBe(false); // the instance survives navigation away
+
+    await runtime.onReady();
+    runtime.onUnmount();
+    expect(runtime.signal.aborted).toBe(true);
+    expect(runtime.phase()).toBe('unmounted');
+  });
+});

package/src/core/wire/wireHub.ts

@@ -0,0 +1,213 @@
+/**
+ * The port hub and instance lifecycle (03 §6.1–§6.2) — the two primitives V7's
+ * wire-smoke and lifecycle probes assert against.
+ *
+ * **Settle by revision, not identity (R-5).** Every value emission is a
+ * `WireEnvelope { rev, at, payload }` and a delivery whose `rev` equals the last
+ * delivered one for that channel is dropped. Object identity is irrelevant,
+ * which is what makes a server that re-allocates an equal payload on every tick
+ * inert instead of a delivery storm.
+ *
+ * **Two subscription tiers (R-4 ∧ J3-3).** Instance-level intake lives from
+ * `onReady` to `onUnmount` and writes only `{dirty, lastRev}` into a ledger —
+ * never a payload copy, so an unrendered feature costs O(1) regardless of
+ * traffic. Pane-level listeners live only while a pane is mounted and are torn
+ * down on unmount, so navigation cannot accumulate dangling listeners. On mount
+ * a pane compares the ledger's `lastRev` against what it rendered and pulls the
+ * retained envelope if it is behind — no signal is lost, no payload is buffered.
+ *
+ * **Abort interception.** `InstanceRuntime.signal` fans into everything the
+ * instance starts; `onSuspend` aborts the view scope and `onUnmount` the instance
+ * scope. State setters routed through `guarded()` no-op after abort, so a late
+ * async result is structurally unable to write into an unmounted instance.
+ */
+export interface WireEnvelope<T = unknown> {
+  /** Monotonic per (instance, port); bump ONLY on content change. */
+  rev: number;
+  scope?: string;
+  at: number;
+  payload: T;
+}
+
+export interface LedgerEntry {
+  dirty: boolean;
+  lastRev: number;
+}
+
+export interface StormBreakerTrip {
+  channel: string;
+  count: number;
+}
+
+export interface WireHubOptions {
+  /** Deliveries per channel per window before the breaker trips (04 §2 V4). */
+  stormBudget?: number;
+  windowMs?: number;
+  now?: () => number;
+}
+
+export interface WireHub {
+  emit<T>(channel: string, envelope: WireEnvelope<T>): 'delivered' | 'settled' | 'breaker-tripped';
+  /** Pane-level listener: live re-render while mounted; returns its teardown. */
+  subscribe<T>(channel: string, listener: (envelope: WireEnvelope<T>) => void): () => void;
+  retained<T>(channel: string): WireEnvelope<T> | undefined;
+  listenerCount(channel: string): number;
+  breakerTrips(): readonly StormBreakerTrip[];
+}
+
+export function createWireHub(options: WireHubOptions = {}): WireHub {
+  const budget = options.stormBudget ?? 200;
+  const windowMs = options.windowMs ?? 1_000;
+  const now = options.now ?? (() => Date.now());
+
+  const listeners = new Map<string, ((envelope: WireEnvelope<unknown>) => void)[]>();
+  const retainedValues = new Map<string, WireEnvelope<unknown>>();
+  const lastRevs = new Map<string, number>();
+  const windows = new Map<string, { start: number; count: number }>();
+  const trips: StormBreakerTrip[] = [];
+
+  return {
+    emit(channel, envelope) {
+      const window = windows.get(channel);
+      const stamp = now();
+      if (!window || stamp - window.start > windowMs) windows.set(channel, { start: stamp, count: 1 });
+      else {
+        window.count += 1;
+        if (window.count > budget) {
+          trips.push({ channel, count: window.count });
+          return 'breaker-tripped';
+        }
+      }
+
+      if (lastRevs.get(channel) === envelope.rev) return 'settled'; // identity is irrelevant; rev decides
+      lastRevs.set(channel, envelope.rev);
+      retainedValues.set(channel, envelope as WireEnvelope<unknown>);
+      for (const listener of [...(listeners.get(channel) ?? [])]) listener(envelope as WireEnvelope<unknown>);
+      return 'delivered';
+    },
+
+    subscribe(channel, listener) {
+      const list = listeners.get(channel) ?? [];
+      const typed = listener as (envelope: WireEnvelope<unknown>) => void;
+      list.push(typed);
+      listeners.set(channel, list);
+      return () => {
+        const current = listeners.get(channel) ?? [];
+        const index = current.indexOf(typed);
+        if (index >= 0) current.splice(index, 1);
+      };
+    },
+
+    retained: <T>(channel: string) => retainedValues.get(channel) as WireEnvelope<T> | undefined,
+    listenerCount: (channel) => (listeners.get(channel) ?? []).length,
+    breakerTrips: () => trips,
+  };
+}
+
+export type LifecyclePhase = 'created' | 'loaded' | 'ready' | 'suspended' | 'unmounted';
+
+export interface InstanceRuntime {
+  id: string;
+  phase(): LifecyclePhase;
+  /** Order is strict and verified: onLoad → onReady before the first view render. */
+  onLoad(): Promise<void>;
+  onReady(): Promise<void>;
+  onSuspend(): void;
+  onUnmount(): void;
+  /** Instance-scoped abort signal — fans into every fetch and background loop. */
+  signal: AbortSignal;
+  /** View-scoped signal; aborted by onSuspend and re-created on the next render. */
+  viewSignal(): AbortSignal;
+  /** Wraps a state setter so a late async result cannot write after abort. */
+  guarded<T>(apply: (value: T) => void): (value: T) => boolean;
+  ledger(): ReadonlyMap<string, LedgerEntry>;
+  /** Pane mount: pull the retained envelope iff the ledger is ahead of what was rendered. */
+  pullIfDirty<T>(channel: string, renderedRev: number): WireEnvelope<T> | undefined;
+  lifecycleErrors(): readonly string[];
+}
+
+export interface InstanceRuntimeOptions {
+  id: string;
+  hub: WireHub;
+  /** Channels the instance takes intake on at onReady (`subscribesAtMount` ports). */
+  intakeChannels: readonly string[];
+}
+
+export function createInstanceRuntime(options: InstanceRuntimeOptions): InstanceRuntime {
+  const instanceController = new AbortController();
+  let viewController = new AbortController();
+  let phase: LifecyclePhase = 'created';
+  const ledger = new Map<string, LedgerEntry>();
+  const teardowns: (() => void)[] = [];
+  const errors: string[] = [];
+
+  const requirePhase = (expected: LifecyclePhase[], transition: string): void => {
+    if (!expected.includes(phase)) errors.push(`${transition} called in phase '${phase}' (expected ${expected.join('|')})`);
+  };
+
+  return {
+    id: options.id,
+    phase: () => phase,
+
+    async onLoad() {
+      requirePhase(['created'], 'onLoad');
+      phase = 'loaded';
+    },
+
+    async onReady() {
+      requirePhase(['loaded', 'suspended'], 'onReady');
+      if (teardowns.length === 0) {
+        for (const channel of options.intakeChannels) {
+          ledger.set(channel, { dirty: false, lastRev: -1 });
+          // Intake writes a flag and a rev — never a payload copy (R-4).
+          teardowns.push(
+            options.hub.subscribe(channel, (envelope) => {
+              ledger.set(channel, { dirty: true, lastRev: envelope.rev });
+            }),
+          );
+        }
+      }
+      phase = 'ready';
+    },
+
+    onSuspend() {
+      requirePhase(['ready', 'suspended'], 'onSuspend'); // idempotent by contract
+      viewController.abort();
+      viewController = new AbortController();
+      phase = 'suspended';
+    },
+
+    onUnmount() {
+      if (phase === 'unmounted') {
+        errors.push('onUnmount called twice');
+        return;
+      }
+      viewController.abort();
+      instanceController.abort();
+      for (const teardown of teardowns.splice(0)) teardown();
+      phase = 'unmounted';
+    },
+
+    signal: instanceController.signal,
+    viewSignal: () => viewController.signal,
+
+    guarded<T>(apply: (value: T) => void) {
+      return (value: T) => {
+        if (instanceController.signal.aborted || viewController.signal.aborted) return false;
+        apply(value);
+        return true;
+      };
+    },
+
+    ledger: () => ledger,
+
+    pullIfDirty<T>(channel: string, renderedRev: number) {
+      const entry = ledger.get(channel);
+      if (!entry || entry.lastRev === renderedRev) return undefined;
+      ledger.set(channel, { dirty: false, lastRev: entry.lastRev });
+      return options.hub.retained<T>(channel);
+    },
+
+    lifecycleErrors: () => errors,
+  };
+}

package/src/ctgr/base64url.ts

@@ -0,0 +1,44 @@
+/*
+ * Base64 over raw bytes, isomorphic via `btoa`/`atob` (present on Bun and in the
+ * browser). The binary string is built in 32 KB blocks so a large payload never
+ * overflows the call stack via `String.fromCharCode(...all)`.
+ *
+ * Two flavors:
+ *  - base64URL (`-`/`_`, no padding) for the per-chunk `_d` payload (URL-safe).
+ *  - standard base64 for the `__files` data carried inside the JSON body.
+ */
+const STEP = 0x8000;
+
+function toBinary(bytes: Uint8Array): string {
+  let binary = '';
+  for (let i = 0; i < bytes.length; i += STEP) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + STEP));
+  }
+  return binary;
+}
+
+function fromBinary(binary: string): Uint8Array {
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+/** URL-safe base64 of `bytes` (RFC 4648 §5: `+`→`-`, `/`→`_`, no `=` padding). */
+export function toBase64url(bytes: Uint8Array): string {
+  return btoa(toBinary(bytes)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+/** Inverse of {@link toBase64url}. */
+export function fromBase64url(value: string): Uint8Array {
+  return fromBinary(atob(value.replace(/-/g, '+').replace(/_/g, '/')));
+}
+
+/** Standard base64 (with `+`/`/` and `=` padding). */
+export function toBase64(bytes: Uint8Array): string {
+  return btoa(toBinary(bytes));
+}
+
+/** Inverse of {@link toBase64}. */
+export function fromBase64(value: string): Uint8Array {
+  return fromBinary(atob(value));
+}