@g9tm/app-pilot 0.0.0-stage → 0.1.0

package/src/config.ts

@@ -0,0 +1,182 @@
+// The app's G9AppPilot configuration at run time (plan §10.1): every capability optional.
+//
+// The build carries the configuration (the app's `pilot` block, per environment); `installPilotConfig(initial)` takes it
+// and a QA controller may change what is SAFE to change on a running app — `pilot.config.get {path?}` (observe),
+// `pilot.config.set {path, value}` (admin) — until the app restarts. Keys, the servers a write may reach and whether
+// DevTool is linked change only in a build: `set` refuses them by name.
+//
+// A capability switched off is refused at the door (one dispatch gate, not a check in every feature):
+//   network.shaping  → net.shape            clock.control → clock.set, clock.reset
+//   stage.seed       → state.seed           studio.tokens → design.set, design.reset
+//   oracles.enabled  → oracle.*  (and the oracles report nothing: setOraclesEnabled)
+// `events.channels.<kind>` switches a heavy event channel (net.body, perf.frame, store.change) on or off.
+import { addGate } from './dispatch.ts';
+import { PilotError } from './errors.ts';
+import { setEventChannel } from './events.ts';
+import { setOraclesEnabled } from './oracles.ts';
+import { registerCommand } from './registry.ts';
+
+export interface PilotConfig {
+  readonly network?: { readonly shaping?: boolean };
+  readonly clock?: { readonly control?: boolean };
+  readonly stage?: { readonly seed?: boolean; readonly reduceMotion?: boolean };
+  readonly studio?: { readonly tokens?: boolean; readonly inspectorGesture?: boolean };
+  readonly oracles?: { readonly enabled?: boolean };
+  readonly events?: { readonly channels?: Readonly<Record<string, boolean>> };
+  readonly badge?: { readonly mode?: string };
+  /** true: a run-time change (pilot.config.set) survives a restart, kept in the app's store (plan v2 P1-23). */
+  readonly persist?: boolean;
+  readonly [key: string]: unknown;
+}
+
+/** Where the app keeps the run-time changes when `persist` is on: any small string store (a secure store, a file). */
+export interface PilotConfigStore {
+  load(): Promise<string | null> | string | null;
+  save(text: string): Promise<void> | void;
+}
+
+/** The paths a running app may change; anything else is the build's. */
+const RUNTIME_PATHS = ['network.shaping', 'clock.control', 'stage.seed', 'stage.reduceMotion', 'studio.tokens', 'studio.inspectorGesture', 'oracles.enabled', 'badge.mode'];
+const RUNTIME_PREFIXES = ['events.channels.'];
+
+/** Which capability a command belongs to (a command of a capability that is off is refused). */
+function capabilityOf(command: string): string | null {
+  if (command === 'net.shape') return 'network.shaping';
+  if (command === 'clock.set' || command === 'clock.reset') return 'clock.control';
+  if (command === 'state.seed') return 'stage.seed';
+  if (command === 'design.set' || command === 'design.reset') return 'studio.tokens';
+  if (command.startsWith('oracle.') && command !== 'oracle.rules') return 'oracles.enabled';
+  return null;
+}
+
+let config: Record<string, unknown> = {};
+
+const read = (path: string): unknown => path.split('.').reduce<unknown>((o, k) => (o && typeof o === 'object' ? (o as Record<string, unknown>)[k] : undefined), config);
+
+/** A capability is on unless the configuration says `false` (everything optional, nothing required). */
+export const pilotConfigOn = (path: string): boolean => read(path) !== false;
+
+export const pilotConfigValue = (path: string): unknown => read(path);
+
+function write(path: string, value: unknown): void {
+  const keys = path.split('.');
+  const next = structuredCloneish(config);
+  let o = next;
+  for (const k of keys.slice(0, -1)) {
+    if (!o[k] || typeof o[k] !== 'object') o[k] = {};
+    o = o[k] as Record<string, unknown>;
+  }
+  o[keys[keys.length - 1]!] = value;
+  config = next;
+}
+
+function structuredCloneish(v: Record<string, unknown>): Record<string, unknown> {
+  return JSON.parse(JSON.stringify(v)) as Record<string, unknown>;
+}
+
+/** Applies what a value means beyond the table (the oracles' switch, a heavy event channel). */
+function apply(path: string): void {
+  if (path === 'oracles.enabled') setOraclesEnabled(pilotConfigOn('oracles.enabled'));
+  if (path.startsWith('events.channels.')) setEventChannel(path.slice('events.channels.'.length), read(path) === true);
+}
+
+/** The run-time changes of this session (path → value): what `persist` keeps. */
+let runtimeChanges: Record<string, unknown> = {};
+let persistStore: PilotConfigStore | null = null;
+const runtimeAllowed = (path: string) => RUNTIME_PATHS.includes(path) || RUNTIME_PREFIXES.some((p) => path.startsWith(p) && path.length > p.length);
+const savePersisted = () => {
+  try {
+    void Promise.resolve(persistStore?.save(JSON.stringify(runtimeChanges))).catch(() => undefined);
+  } catch {
+    // a store that fails keeps nothing; the change still holds until the app restarts
+  }
+};
+
+/**
+ * Installs the build's configuration, its gate and `pilot.config.get | set | reset`. With `persist: true` in the build and a
+ * `store`, the run-time changes saved before are put back (only the paths a running app may change; a build value of a
+ * later build is NOT overridden by an older key that is no longer run-time) and every change is saved. Returns the remover.
+ */
+export function installPilotConfig(initial: PilotConfig = {}, { store = null }: { readonly store?: PilotConfigStore | null } = {}): () => void {
+  config = structuredCloneish(initial as Record<string, unknown>);
+  runtimeChanges = {};
+  persistStore = initial.persist === true ? store : null;
+  setOraclesEnabled(pilotConfigOn('oracles.enabled'));
+  for (const [kind, on] of Object.entries(initial.events?.channels ?? {})) setEventChannel(kind, on === true);
+  if (persistStore) {
+    const restore = (text: string | null) => {
+      let saved: Record<string, unknown> = {};
+      try {
+        saved = text ? (JSON.parse(text) as Record<string, unknown>) : {};
+      } catch {
+        saved = {};
+      }
+      for (const [path, value] of Object.entries(saved)) {
+        if (!runtimeAllowed(path)) continue;
+        write(path, value);
+        runtimeChanges[path] = value;
+        apply(path);
+      }
+    };
+    try {
+      const loaded = persistStore.load();
+      if (loaded && typeof (loaded as Promise<string | null>).then === 'function') void (loaded as Promise<string | null>).then(restore, () => undefined);
+      else restore(loaded as string | null);
+    } catch {
+      // nothing kept
+    }
+  }
+  const offs = [
+    addGate((request) => {
+      const cap = capabilityOf(request.command);
+      if (!cap || pilotConfigOn(cap)) return null;
+      return { ok: false, error: `"${request.command}" is off in this app's G9AppPilot configuration (${cap} = false).`, code: 'DISABLED', category: 'automation', hint: `pilot.config.set {path: '${cap}', value: true} turns it on until the app restarts.` };
+    }),
+    registerCommand(
+      'pilot.config.get',
+      (args) => {
+        const path = typeof args.path === 'string' && args.path ? args.path : null;
+        return path ? { path, value: read(path) ?? null, on: pilotConfigOn(path) } : { config, runtime: [...RUNTIME_PATHS, ...RUNTIME_PREFIXES.map((p) => `${p}<kind>`)] };
+      },
+      { scope: 'observe', description: 'The G9AppPilot configuration in force (or one path of it), and what may change at run time.' },
+    ),
+    registerCommand(
+      'pilot.config.set',
+      (args) => {
+        const path = typeof args.path === 'string' ? args.path : '';
+        if (!RUNTIME_PATHS.includes(path) && !RUNTIME_PREFIXES.some((p) => path.startsWith(p) && path.length > p.length)) {
+          throw new PilotError(`"${path}" changes only in a build (the app's pilot configuration); at run time: ${RUNTIME_PATHS.join(', ')}, events.channels.<kind>.`, { code: 'BAD_ARGS', fixExample: { command: 'pilot.config.set', args: { path: 'network.shaping', value: false } } });
+        }
+        const value = args.value;
+        const wantsBool = path !== 'badge.mode';
+        if (wantsBool ? typeof value !== 'boolean' : typeof value !== 'string') {
+          throw new PilotError(`${path} needs a ${wantsBool ? 'boolean' : 'string'} (got ${JSON.stringify(value)}).`, { code: 'BAD_ARGS' });
+        }
+        const before = read(path) ?? null;
+        write(path, value);
+        apply(path);
+        runtimeChanges[path] = value;
+        if (persistStore) savePersisted();
+        return { path, from: before, to: value, until: persistStore ? 'pilot.config.reset (kept across restarts: persist)' : 'the app restarts' };
+      },
+      { scope: 'admin', description: 'Switches a safe capability on the running app (until it restarts, or — persist — until pilot.config.reset): network shaping, clock, seed, studio, oracles, heavy event channels.' },
+    ),
+    registerCommand(
+      'pilot.config.reset',
+      () => {
+        const paths = Object.keys(runtimeChanges);
+        config = structuredCloneish(initial as Record<string, unknown>);
+        runtimeChanges = {};
+        for (const p of paths) apply(p);
+        if (persistStore) savePersisted();
+        return { reset: paths, persist: persistStore !== null };
+      },
+      { scope: 'admin', description: 'Every run-time change back to the build’s values (and, with persist, forgotten by the store).' },
+    ),
+  ];
+  return () => {
+    for (const off of offs) off();
+    config = {};
+    setOraclesEnabled(true);
+  };
+}

package/src/design.ts

@@ -0,0 +1,120 @@
+// Live design tokens (plan §7): a controller — the studio, an agent — reads the app's tokens and changes one on the
+// running app; the screen follows at once, nothing is saved, a restart forgets it. «Approve» is the controller's: it
+// takes `design.snapshot` and writes the values into the token files (`g9pilot tokens approve`), never the app.
+//
+//   installDesign(registry)     the app's tokens behind a small interface (the app owns them; production has no pilot)
+//
+//   design.tokens {prefix?, changedOnly?}    every token: id, value, default, type, where it is written
+//   design.set {id, value} | {values}        one or many, checked against the type (design scope)
+//   design.reset {id?}                       one, or every change
+//   design.snapshot                          what changed: {id, from, to, source} — what an approval writes
+import { optionalString } from './args.ts';
+import { emit } from './events.ts';
+import { PilotError } from './errors.ts';
+import { registerCommand } from './registry.ts';
+
+export interface DesignToken {
+  /** Dotted id (`map.chrome.toolSpacing`). */
+  readonly id: string;
+  /** The value in force (an override, else the default). */
+  readonly value: number | string;
+  /** The value the build shipped (from the token files). */
+  readonly defaultValue: number | string;
+  /** DTCG $type: `dimension`, `number`, `color`, … (null: untyped). */
+  readonly type: string | null;
+  readonly description?: string | null;
+  /** Where the default is written: the token file and the token's path in it. */
+  readonly source?: { readonly file: string; readonly path: string } | null;
+}
+
+/** The app's side: its tokens and their overrides. */
+export interface DesignRegistry {
+  tokens(): readonly DesignToken[];
+  set(id: string, value: number | string): void;
+  /** One token back to its default, or (no id) every one. */
+  reset(id?: string): void;
+}
+
+const NUMERIC = new Set(['dimension', 'number', 'duration', 'fontWeight']);
+
+/** A value checked against its token's type: a number for a dimension (dp) or a number, a CSS color string for a color. */
+export function checkTokenValue(token: DesignToken, value: unknown): number | string {
+  if (NUMERIC.has(token.type ?? '') || (token.type === null && typeof token.defaultValue === 'number')) {
+    const n = typeof value === 'number' ? value : typeof value === 'string' && value.trim() !== '' ? Number(value) : Number.NaN;
+    if (!Number.isFinite(n)) throw new PilotError(`${token.id} is a ${token.type ?? 'number'}: it needs a number (got ${JSON.stringify(value)}).`, { code: 'BAD_ARGS', fixExample: { command: 'design.set', args: { id: token.id, value: token.defaultValue } } });
+    if (token.type === 'dimension' && n < 0) throw new PilotError(`${token.id} is a dimension: it cannot be negative.`, { code: 'BAD_ARGS' });
+    return n;
+  }
+  if (token.type === 'color') {
+    if (typeof value !== 'string' || !/^(#[0-9a-fA-F]{3,8}|rgba?\(.+\)|hsla?\(.+\))$/.test(value.trim())) {
+      throw new PilotError(`${token.id} is a color: #RRGGBB, #RRGGBBAA, rgb(…) or hsl(…) (got ${JSON.stringify(value)}).`, { code: 'BAD_ARGS' });
+    }
+    return value.trim();
+  }
+  if (typeof value !== 'string' && typeof value !== 'number') throw new PilotError(`${token.id} needs a string or a number.`, { code: 'BAD_ARGS' });
+  return value;
+}
+
+/** The design commands over the app's registry. Returns the uninstaller. */
+export function installDesign(registry: DesignRegistry): () => void {
+  const find = (id: string): DesignToken => {
+    const t = registry.tokens().find((x) => x.id === id);
+    if (!t) {
+      const near = registry
+        .tokens()
+        .map((x) => x.id)
+        .filter((x) => x.split('.').pop() === id.split('.').pop())
+        .slice(0, 3);
+      throw new PilotError(`No token ${id}${near.length ? ` — did you mean ${near.join(', ')}?` : ''}`, { code: 'NOT_FOUND', fixExample: { command: 'design.tokens', args: { prefix: id.split('.').slice(0, -1).join('.') } } });
+    }
+    return t;
+  };
+  const changes = () =>
+    registry
+      .tokens()
+      .filter((t) => t.value !== t.defaultValue)
+      .map((t) => ({ id: t.id, from: t.defaultValue, to: t.value, type: t.type, source: t.source ?? null }));
+  const offs = [
+    registerCommand(
+      'design.tokens',
+      (args) => {
+        const prefix = optionalString(args, 'prefix');
+        const changedOnly = args.changedOnly === true;
+        const list = registry.tokens().filter((t) => (!prefix || t.id.startsWith(prefix)) && (!changedOnly || t.value !== t.defaultValue));
+        return { tokens: list.map((t) => ({ ...t, changed: t.value !== t.defaultValue })), count: list.length };
+      },
+      { scope: 'observe', description: 'The app’s design tokens: id, value in force, default, type and the file they are written in.', example: { prefix: 'map.chrome' } },
+    ),
+    registerCommand(
+      'design.set',
+      (args) => {
+        const values: Record<string, unknown> =
+          args.values && typeof args.values === 'object' ? (args.values as Record<string, unknown>) : { [String(args.id ?? '')]: args.value };
+        if (Object.keys(values).length === 0 || (Object.keys(values).length === 1 && !Object.keys(values)[0])) {
+          throw new PilotError('design.set needs {id, value} or {values: {id: value}}.', { code: 'BAD_ARGS', fixExample: { command: 'design.set', args: { id: 'map.chrome.toolSpacing', value: 16 } } });
+        }
+        // Every value checked before any is applied: one bad value changes nothing.
+        const checked = Object.entries(values).map(([id, v]) => [id, checkTokenValue(find(id), v)] as const);
+        for (const [id, v] of checked) registry.set(id, v);
+        emit('design.changed', { ids: checked.map(([id]) => id) });
+        return { set: Object.fromEntries(checked), changes: changes().length };
+      },
+      { scope: 'design', description: 'Changes tokens on the running app (until it restarts): the screen follows at once. Checked against the type first.', example: { id: 'map.chrome.toolSpacing', value: 16 } },
+    ),
+    registerCommand(
+      'design.reset',
+      (args) => {
+        const id = optionalString(args, 'id');
+        if (id) find(id);
+        registry.reset(id ?? undefined);
+        emit('design.changed', { ids: id ? [id] : 'all' });
+        return { reset: id ?? 'all', changes: changes().length };
+      },
+      { scope: 'design', description: 'One token back to its default, or every change.' },
+    ),
+    registerCommand('design.snapshot', () => ({ changes: changes() }), { scope: 'observe', description: 'What changed against the build: {id, from, to, source} — what an approval writes into the token files.' }),
+  ];
+  return () => {
+    for (const off of offs) off();
+  };
+}

package/src/dispatch.ts

@@ -0,0 +1,111 @@
+// One request from the native listener → one answer. The order is fixed (pilot/AiGuides/03 «Dispatch»):
+//   1. the app's gates      → whatever they refuse with (automation switched off, a lease, a derailed app…), in order —
+//                              first, because "automation is off on this device" is the answer whatever was asked;
+//   2. unknown command      → NOT_FOUND (with the count of known ones and the way to list them);
+//   3. scope                → SCOPE (the key may not run this command; the native gate already proved the key);
+//   4. the handler          → {ok:true, result} | the failure it threw;
+//   5. the app's after-gates→ may turn a success into a refusal (the action itself derailed the app);
+//   6. the observers        → see the answer as it leaves (the black box's trail and its failure traces), never change it.
+import { failureOf, PilotError, type PilotFailure } from './errors.ts';
+import { commandHandler, commandNames, commandScope, type PilotContext } from './registry.ts';
+import { scopeAllows } from './scopes.ts';
+
+export interface PilotRequest {
+  readonly id: string;
+  readonly command: string;
+  readonly args?: Record<string, unknown>;
+  readonly timeoutMs?: number;
+  readonly leaseId?: string | null;
+  readonly kid?: string | null;
+  /** The signing key's scopes, as the native gate admitted them ('*' for an unsigned request a migration allowed). */
+  readonly scopes?: readonly string[];
+}
+
+export type PilotAnswer = { readonly ok: true; readonly result: unknown } | PilotFailure;
+
+/** A gate: null lets the request through; anything else is the refusal (a message, or a full failure). */
+export type PilotGateHook = (request: PilotRequest, ctx: PilotContext) => string | PilotFailure | null;
+
+const before: PilotGateHook[] = [];
+const after: PilotGateHook[] = [];
+
+/** An app's own check before every command (leases, a switched-off bridge, a derailed app). Returns the remover. */
+export function addGate(hook: PilotGateHook, when: 'before' | 'after' = 'before'): () => void {
+  const list = when === 'before' ? before : after;
+  list.push(hook);
+  return () => {
+    const i = list.indexOf(hook);
+    if (i >= 0) list.splice(i, 1);
+  };
+}
+
+/** Sees every answer as it leaves (request, answer, how long it took). An observer that throws is ignored. */
+export type PilotAnswerObserver = (request: PilotRequest, answer: PilotAnswer, ms: number) => void;
+const observers: PilotAnswerObserver[] = [];
+
+export function onAnswer(observer: PilotAnswerObserver): () => void {
+  observers.push(observer);
+  return () => {
+    const i = observers.indexOf(observer);
+    if (i >= 0) observers.splice(i, 1);
+  };
+}
+
+const refusal = (r: string | PilotFailure): PilotFailure =>
+  typeof r === 'string' ? { ok: false, error: r, code: 'REFUSED', category: r.startsWith('DERAILED:') ? 'derailed' : 'automation' } : r;
+
+export async function dispatch(request: PilotRequest): Promise<PilotAnswer> {
+  const started = Date.now();
+  const answer = await answerOf(request);
+  for (const o of observers.slice()) {
+    try {
+      o(request, answer, Date.now() - started);
+    } catch {
+      // an observer never changes the answer
+    }
+  }
+  return answer;
+}
+
+async function answerOf(request: PilotRequest): Promise<PilotAnswer> {
+  const scopes = request.scopes ?? ['*'];
+  const timeoutMs = Math.min(Math.max(request.timeoutMs && request.timeoutMs > 0 ? request.timeoutMs : 30_000, 1_000), 120_000);
+  // The host waits exactly timeoutMs for the answer. A handler that used all of it (a wait that ends in «not found»,
+  // which then lists what IS on screen) answered after the host had given up, and the controller saw TIMEOUT instead of
+  // the answer it can act on. So a handler's own budget keeps a margin for answering: 15 %, between 250 ms and 1.5 s.
+  const margin = Math.min(1_500, Math.max(250, Math.round(timeoutMs * 0.15)));
+  const ctx: PilotContext = { timeoutMs: timeoutMs - margin, leaseId: request.leaseId ?? null, kid: request.kid ?? null, scopes };
+  for (const gate of before) {
+    const r = gate(request, ctx);
+    if (r) return refusal(r);
+  }
+  const handler = commandHandler(request.command);
+  if (!handler) {
+    return failureOf(
+      new PilotError(`Unknown command "${request.command}". Call qa.capabilities (or pilot.capabilities) for the list — this build serves ${commandNames().length} page commands.`, {
+        code: 'NOT_FOUND',
+        hint: 'Call pilot.capabilities and use a name it lists.',
+        fixExample: { command: 'pilot.capabilities' },
+      }),
+      request.command,
+    );
+  }
+  const scope = commandScope(request.command);
+  if (!scopeAllows(scopes, scope)) {
+    return { ok: false, error: `The key "${request.kid ?? '(unsigned)'}" may not run "${request.command}" (scope ${scope}).`, code: 'SCOPE', category: 'scope' };
+  }
+  try {
+    const result = await handler(request.args ?? {}, ctx);
+    for (const gate of after) {
+      const r = gate(request, ctx);
+      if (r) return refusal(r);
+    }
+    return { ok: true, result: result ?? null };
+  } catch (error) {
+    for (const gate of after) {
+      const r = gate(request, ctx);
+      if (r) return refusal(r);
+    }
+    return failureOf(error, request.command);
+  }
+}

package/src/errors.ts

@@ -0,0 +1,59 @@
+// Errors a command throws. The wire shape (pilot/protocol/PROTOCOL.md «Errors"): {ok:false, error, code, category, hint?,
+// fixExample?}. `hint` is one sentence an agent can act on; `fixExample` a correct call. A plain Error from a command
+// becomes code COMMAND_FAILED, category product (the app misbehaved) — throw a PilotError when the cause is known.
+
+export type PilotErrorCategory = 'product' | 'automation' | 'auth' | 'scope' | 'lease' | 'derailed';
+
+export interface PilotErrorOptions {
+  readonly code?: string;
+  readonly category?: PilotErrorCategory;
+  readonly hint?: string;
+  readonly fixExample?: { readonly command: string; readonly args?: Record<string, unknown> };
+  readonly retryable?: boolean;
+}
+
+export class PilotError extends Error {
+  readonly code: string;
+  readonly category: PilotErrorCategory;
+  readonly hint: string | undefined;
+  readonly fixExample: PilotErrorOptions['fixExample'] | undefined;
+  readonly retryable: boolean;
+
+  constructor(message: string, options: PilotErrorOptions = {}) {
+    super(message);
+    this.name = 'PilotError';
+    this.code = options.code ?? 'REFUSED';
+    this.category = options.category ?? 'automation';
+    this.hint = options.hint;
+    this.fixExample = options.fixExample;
+    this.retryable = options.retryable ?? false;
+  }
+}
+
+export interface PilotFailure {
+  readonly ok: false;
+  readonly error: string;
+  readonly code: string;
+  readonly category: PilotErrorCategory;
+  readonly hint?: string;
+  readonly fixExample?: PilotErrorOptions['fixExample'];
+  readonly retryable?: boolean;
+}
+
+export function failureOf(error: unknown, command: string): PilotFailure {
+  if (error instanceof PilotError) {
+    return {
+      ok: false,
+      error: error.message,
+      code: error.code,
+      category: error.category,
+      ...(error.hint ? { hint: error.hint } : {}),
+      ...(error.fixExample ? { fixExample: error.fixExample } : {}),
+      ...(error.retryable ? { retryable: true } : {}),
+    };
+  }
+  // A thrown error of an older registry (an Error named QaError, say) keeps its message as-is: runners match on it.
+  if (error instanceof Error && error.name !== 'Error') return { ok: false, error: error.message, code: 'REFUSED', category: 'automation' };
+  const message = error instanceof Error ? error.message : String(error);
+  return { ok: false, error: `Command "${command}" failed: ${message}`, code: 'COMMAND_FAILED', category: 'product' };
+}

package/src/events.ts

@@ -0,0 +1,86 @@
+// Page events into the bridge's stream (pilot/protocol/PROTOCOL.md, `GET /pilot/events`). The native side numbers them
+// (`seq`), keeps the flight recorder and serves Server-Sent Events; this side only batches: events emitted in one turn
+// leave together on the next tick, so a burst (a list of layer changes) is one bridge call, and nothing waits on it.
+//
+//   emit('toast', { text: 'ذخیره شد', kind: 'success' });
+//
+// A kind is a short dotted name (pilot/protocol/PROTOCOL.md, «Events» in AiGuides/03). Heavy kinds (`net.body`,
+// `perf.frame`, `store.change`) are emitted only when the app switched them on (`setEventChannels`).
+
+export interface PilotEvent {
+  readonly kind: string;
+  readonly data: unknown;
+  readonly t: number;
+}
+
+export type EventSink = (batch: readonly PilotEvent[]) => void;
+
+let sink: EventSink | null = null;
+let queue: PilotEvent[] = [];
+let scheduled = false;
+const heavy = new Set(['net.body', 'perf.frame', 'store.change', 'log.line']);
+let enabledHeavy = new Set<string>();
+
+/** The transport connects the native side (null disconnects: events are then dropped, never queued forever). */
+export function setEventSink(next: EventSink | null): void {
+  sink = next;
+  if (!next) queue = [];
+}
+
+export function setEventChannels(channels: Readonly<Record<string, boolean>>): void {
+  enabledHeavy = new Set(Object.entries(channels).filter(([, on]) => on).map(([k]) => k));
+}
+
+/** One heavy channel on or off, the others as they were (log.stream, store.watch). */
+export function setEventChannel(kind: string, on: boolean): void {
+  if (on) enabledHeavy.add(kind);
+  else enabledHeavy.delete(kind);
+}
+
+export const eventChannelOn = (kind: string): boolean => enabledHeavy.has(kind);
+
+export const eventsConnected = (): boolean => sink !== null;
+
+/** (recorder v2) In-page listeners: every emitted event, whether or not a stream is connected. A throw is ignored. */
+type EventListener = (kind: string, data: unknown, t: number) => void;
+const listeners: EventListener[] = [];
+
+export function onEmit(listener: EventListener): () => void {
+  listeners.push(listener);
+  return () => {
+    const i = listeners.indexOf(listener);
+    if (i >= 0) listeners.splice(i, 1);
+  };
+}
+
+export function emit(kind: string, data: unknown = null): void {
+  if (listeners.length) {
+    const t = Date.now();
+    for (const l of listeners.slice()) {
+      try {
+        l(kind, data, t);
+      } catch {
+        // a listener never stops an event
+      }
+    }
+  }
+  if (!sink) return;
+  if (heavy.has(kind) && !enabledHeavy.has(kind)) return;
+  queue.push({ kind, data, t: Date.now() });
+  if (queue.length > 200) queue.splice(0, queue.length - 200);
+  if (scheduled) return;
+  scheduled = true;
+  setTimeout(flush, 0);
+}
+
+export function flush(): void {
+  scheduled = false;
+  if (!sink || queue.length === 0) return;
+  const batch = queue;
+  queue = [];
+  try {
+    sink(batch);
+  } catch {
+    // the stream is best-effort: a failed hand-off never reaches the app
+  }
+}