@almadar/shell-web 0.0.0-stage → 1.0.0

package/dist/katexPlugin-NCDKOOQY.js

@@ -0,0 +1,2 @@
+import './chunk-G7DCAZ22.js';
+export { default as rehypeKatex } from 'rehype-katex';

package/dist/kernel-client-TZKGHJRY.js

@@ -0,0 +1,516 @@
+import { createTickDriver, runTickFrame } from './chunk-AU7O65OX.js';
+import { presenceGroup, getTraitPresence } from './chunk-4YXBKHHM.js';
+import './chunk-G7DCAZ22.js';
+import { isJsonObject } from '@almadar/core';
+import { createLocalFold, traceResponse, paintResponse } from '@almadar/shell-runtime';
+import { TraitMountError } from '@almadar/shell-runtime/client/trait-mount-error';
+import { SessionEndedError } from '@almadar/shell-runtime/client/EventTransport';
+import { createLogger } from '@almadar/logger';
+
+var log = createLogger("almadar:ui:kernel-client");
+var nextClientSerial = 0;
+var defaultFrameScheduler = (callback) => {
+  if (typeof requestAnimationFrame === "function") {
+    const handle = requestAnimationFrame(callback);
+    return () => cancelAnimationFrame(handle);
+  }
+  const timer = setTimeout(() => callback(performance.now()), 16);
+  return () => clearTimeout(timer);
+};
+function parse(text) {
+  return JSON.parse(text);
+}
+function payloadJson(payload) {
+  return payload === void 0 ? void 0 : JSON.stringify(payload);
+}
+function createKernelClient(opts) {
+  const { store, traitIndex, transport } = opts;
+  let loaded;
+  const configs = /* @__PURE__ */ new Map();
+  const ready = opts.instance.then((k) => {
+    loaded = k;
+    return k;
+  });
+  ready.catch(() => void 0);
+  const visibleGroups = [...traitIndex.byName].filter(([, entry]) => entry.ticks.some((tick) => tick.whileVisible)).map(([name]) => [name, presenceGroup(traitIndex, name)]);
+  const foldTurns = /* @__PURE__ */ new Map();
+  const runQueuedFolds = (k) => {
+    for (let json = k.nextFold(); json !== void 0; json = k.nextFold()) {
+      const next = parse(json);
+      const turn = foldTurns.get(next.ticket);
+      if (turn === void 0) throw new Error(`kernel wire: the kernel folded ticket ${next.ticket}, which nothing waits on`);
+      foldTurns.delete(next.ticket);
+      if (next.outcome === "failed") turn.failed(new Error(next.error));
+      else turn.ran(next.fold);
+    }
+  };
+  const foldInOrder = (k, flight, answer, alreadyDeliveredJson, baseJson) => settleProgress(k, parse(k.foldInOrder(flight, JSON.stringify(answer), alreadyDeliveredJson, baseJson)));
+  const deliverInOrder = (k, flight, emitted) => settleProgress(k, parse(k.deliverEmitToListeners(flight, JSON.stringify(emitted))));
+  const deliverOriginInOrder = (k, flight, emitted) => settleProgress(k, parse(k.deliverOriginEmit(flight, JSON.stringify(emitted))));
+  const settleProgress = (k, progress) => {
+    if (progress.status === "applied") return Promise.resolve(progress.fold);
+    const turn = new Promise((ran, failed) => {
+      foldTurns.set(progress.ticket, { ran, failed });
+    });
+    queueMicrotask(() => runQueuedFolds(k));
+    return turn;
+  };
+  const endFlight = (k, flight) => {
+    if (flight === null || flight === void 0) return;
+    k.endFlight(flight);
+    runQueuedFolds(k);
+  };
+  const flightOf = (wire) => {
+    if (wire.flight === null || wire.flight === void 0) throw new Error(`kernel wire: ${wire.seed.trait}.${wire.seed.event} owes a leg and carries no flight`);
+    return wire.flight;
+  };
+  let scopeTail = Promise.resolve();
+  const framesSince = (since) => {
+    if (loaded === void 0) throw new Error("the kernel is not loaded");
+    return parse(loaded.framesSince(since));
+  };
+  const mirror = (response) => paintResponse(store, framesSince, response);
+  const traceStreams = /* @__PURE__ */ new Set();
+  const movedTraits = (item) => {
+    const dispatch = item["dispatch"];
+    const outcomes = dispatch !== void 0 && dispatch !== null && isJsonObject(dispatch) ? dispatch["outcomes"] ?? null : null;
+    if (!Array.isArray(outcomes)) return [];
+    return outcomes.flatMap((o) => o !== null && isJsonObject(o) && typeof o["trait"] === "string" ? [o["trait"]] : []);
+  };
+  const publishTrace = (k) => {
+    if (traceStreams.size === 0) return;
+    const items = parse(k.takeTrace());
+    if (!Array.isArray(items)) return;
+    for (const item of items) {
+      if (item === null || !isJsonObject(item)) continue;
+      const moved = movedTraits(item);
+      for (const stream of traceStreams) {
+        if (moved.some((t) => stream.traits.has(t))) queueMicrotask(() => stream.onItem(item));
+      }
+    }
+  };
+  const trace = (k, response) => {
+    traceResponse(opts.observer, response);
+    publishTrace(k);
+  };
+  const localFold = createLocalFold({ store, framesSince, ...opts.observer !== void 0 ? { observer: opts.observer } : {} });
+  const syncStates = (k, traits) => {
+    for (const trait of traits) {
+      const state = k.getState(trait);
+      if (state !== "" && store.states.getState(trait)?.currentState !== state) store.states.seedState(trait, state);
+    }
+  };
+  const restore = (k, wire, entityId) => {
+    const snapshot = wire.snapshot;
+    if (snapshot === null) return { clientEffectsByTrait: [] };
+    const trait = wire.seed.trait;
+    const repaint = parse(k.restore(trait, entityId, JSON.stringify(snapshot)));
+    if (snapshot.state !== "") store.states.rollbackState(trait, snapshot.state, entityId, "server-rejected");
+    mirror(repaint);
+    store.notify();
+    return { clientEffectsByTrait: repaint.clientEffectsByTrait ?? [] };
+  };
+  const planDispatch = (wire, carriesCircuitState) => {
+    if (wire.serverLegs.length > 0) {
+      return {
+        awaiting: wire.awaiting,
+        legs: wire.serverLegs.map(({ orbital, leg }) => ({
+          orbital,
+          leg,
+          keepsState: carriesCircuitState || wire.mode === "hybridClientOnly",
+          alreadyDelivered: wire.alreadyDelivered,
+          foldSeeded: wire.foldSeeded,
+          wires: [wire],
+          flight: flightOf(wire)
+        }))
+      };
+    }
+    if (!carriesCircuitState && wire.statefulLeg !== null) {
+      return {
+        awaiting: wire.statefulLeg.awaiting,
+        legs: [{ orbital: wire.statefulLeg.orbital, leg: wire.statefulLeg.leg, keepsState: true, alreadyDelivered: wire.alreadyDelivered, foldSeeded: [], wires: [wire], flight: flightOf(wire) }]
+      };
+    }
+    return { legs: [], awaiting: [] };
+  };
+  const mountedSeeds = /* @__PURE__ */ new Map();
+  const foldAnswer = async (k, flight, answer) => {
+    const applied = await foldInOrder(k, flight, answer, "[]", void 0);
+    mirror(applied.response);
+    syncStates(k, Object.keys(answer.states));
+    return applied;
+  };
+  const resyncFrames = async (k, flight, orbital, leg, since, request) => {
+    if (leg.clientId === void 0) throw new Error("a frame resync needs the client id the leg was posted under");
+    const answer = await sendReseeding(k, flight, orbital, { event: "$FRAMES", clientId: leg.clientId, framesSince: since }, request);
+    if (answer.success) await foldAnswer(k, flight, answer);
+  };
+  const sendReseeding = async (k, flight, orbital, sent, request) => {
+    if (transport === void 0) throw new Error("no transport");
+    try {
+      return await transport.send(orbital, sent);
+    } catch (err) {
+      const seeds = mountedSeeds.get(orbital);
+      if (!(err instanceof SessionEndedError) || seeds === void 0 || seeds.length === 0) throw err;
+      const reseed = JSON.parse(k.reseedLeg(JSON.stringify(seeds), request.entityId));
+      const mounted = await transport.send(orbital, request.locale !== void 0 ? { ...reseed, locale: request.locale } : reseed);
+      await foldAnswer(k, flight, mounted);
+      store.notify();
+      return transport.send(orbital, sent);
+    }
+  };
+  const sendLegs = async (k, legs, request, flags, initial) => {
+    const out = {
+      response: initial,
+      serverEffects: { clientEffectsByTrait: [] },
+      success: true,
+      rejections: [],
+      foldedEmits: []
+    };
+    if (transport === void 0) return out;
+    const queue = [...legs];
+    for (let planned = queue.shift(); planned !== void 0; planned = queue.shift()) {
+      const shaped = planned.keepsState ? planned.leg : JSON.parse(k.statefulLeg(JSON.stringify(planned.leg)));
+      const sent = request.locale !== void 0 ? { ...shaped, locale: request.locale } : shaped;
+      const base = k.foldBase(sent.entityByTrait !== void 0 ? JSON.stringify(sent.entityByTrait) : void 0, JSON.stringify(planned.foldSeeded), sent.entityId);
+      let posted;
+      try {
+        posted = await sendReseeding(k, planned.flight, planned.orbital, sent, request);
+      } catch (err) {
+        if (flags.rollback || flags.mount) for (const wire of planned.wires) restore(k, wire, request.entityId);
+        throw err instanceof Error ? err : new Error(String(err));
+      }
+      if (!posted.success) {
+        const optimistic = planned.wires.filter((wire) => wire.mode === "runtimeOptimistic");
+        if (flags.rollback && optimistic.length > 0) {
+          return { ...out, response: posted, success: false, rolledBack: restore(k, optimistic[0], request.entityId) };
+        }
+        if (flags.mount) for (const wire of optimistic) restore(k, wire, request.entityId);
+      }
+      const applied = await foldInOrder(k, planned.flight, posted, JSON.stringify(planned.alreadyDelivered), base);
+      log.debug("fold", { orbital: planned.orbital, event: sent.event, posted: { success: posted.success, states: posted.states, emitted: posted.emittedEvents.map((e) => e.event) }, applied: applied.applied, cascadeEmitted: applied.response.emittedEvents.map((e) => e.event) });
+      trace(k, applied.response);
+      for (const routed of applied.serverLegs) {
+        queue.push({ orbital: routed.orbital, leg: routed.leg, keepsState: true, alreadyDelivered: [], foldSeeded: [], wires: [], flight: planned.flight });
+      }
+      mirror(applied.response);
+      if (applied.resync != null) await resyncFrames(k, planned.flight, planned.orbital, sent, applied.resync.since, request);
+      syncStates(k, [...Object.keys(posted.states), ...applied.applied.map(([trait]) => trait)]);
+      store.notify();
+      const fold = applied.response;
+      const delivered = new Set(planned.alreadyDelivered.map(([trait, event]) => `${trait}\0${event}`));
+      const serverEmits = posted.emittedEvents.filter((e) => !delivered.has(`${e.source?.trait ?? ""}\0${e.event}`));
+      const byTrait = [...posted.clientEffectsByTrait ?? [], ...fold.clientEffectsByTrait ?? []];
+      out.serverEffects.clientEffectsByTrait?.push(...byTrait);
+      out.foldedEmits.push(...serverEmits, ...fold.emittedEvents);
+      out.response = {
+        ...out.response,
+        emittedEvents: [...out.response.emittedEvents, ...serverEmits, ...fold.emittedEvents],
+        clientEffectsByTrait: [...out.response.clientEffectsByTrait ?? [], ...byTrait],
+        effectResults: [...out.response.effectResults ?? [], ...fold.effectResults ?? []]
+      };
+      out.success = out.success && posted.success;
+      if (posted.error !== void 0) out.error = posted.error;
+      out.rejections.push(...(fold.rejections ?? []).filter((r) => r.code === "effect-failed" || r.code === "repaint-failed"));
+    }
+    return out;
+  };
+  const post = async (k, wire, request, flags) => {
+    const topology = await opts.topology;
+    const plan = planDispatch(wire, topology.carriesCircuitState);
+    const awaiting = flags.awaiting ? plan.awaiting : [];
+    store.awaiting.begin(awaiting);
+    try {
+      return await sendLegs(k, plan.legs, request, { rollback: flags.rollback, mount: false }, wire.response);
+    } finally {
+      store.awaiting.end(awaiting.map((a) => a.trait));
+    }
+  };
+  const framePost = (k) => {
+    if (transport === void 0) return void 0;
+    return {
+      postDispatch: async (wire) => {
+        try {
+          return (await post(k, wire, {}, { rollback: false, awaiting: false })).serverEffects;
+        } finally {
+          endFlight(k, wire.flight);
+        }
+      },
+      sendBrowserLeg: async (routed, frameResponse) => {
+        const flight = k.openFlight();
+        try {
+          const planned = { orbital: routed.orbital, leg: routed.leg, keepsState: true, alreadyDelivered: [], foldSeeded: [], wires: [], flight };
+          return (await sendLegs(k, [planned], {}, { rollback: false, mount: false }, frameResponse)).serverEffects;
+        } finally {
+          endFlight(k, flight);
+        }
+      }
+    };
+  };
+  const tickPorts = (k) => ({
+    kernel: {
+      frame: (nowMs) => {
+        const presence = getTraitPresence();
+        for (const [traitName, group] of visibleGroups) k.setTraitOnScreen(traitName, presence.state(group) !== "off-screen");
+        return k.frame(nowMs);
+      },
+      framePause: () => k.framePause(),
+      frameResume: () => k.frameResume(),
+      tickCount: () => k.tickCount()
+    },
+    client: localFold,
+    post: framePost(k)
+  });
+  const dispatchOne = async (request, hooks, progress) => {
+    const traitName = request.targetTrait;
+    if (traitName === void 0) throw new Error("dispatch requires request.targetTrait (the seed trait)");
+    const k = await ready;
+    await scopeTail;
+    if (request.runTick !== void 0) {
+      const response = parse(k.tick(request.runTick.trait, request.runTick.tick, request.entityId));
+      publishTrace(k);
+      mirror(response);
+      store.notify();
+      return { response, mode: parse(k.dispatchMode(request.runTick.trait)) };
+    }
+    const wire = parse(k.dispatch(traitName, request.entityId, request.event, payloadJson(request.payload)));
+    try {
+      return await settleDispatch(k, wire, request, hooks, progress);
+    } finally {
+      endFlight(k, wire.flight);
+    }
+  };
+  const settleDispatch = async (k, wire, request, hooks, progress) => {
+    log.debug("dispatch", { trait: wire.seed.trait, event: request.event, mode: wire.mode, legs: wire.serverLegs.length, success: wire.response.success, states: wire.response.states, effects: (wire.response.clientEffectsByTrait ?? []).map((e) => `${e.traitName}:${e.effect[0]}:${e.effect[1] ?? ""}`), emitted: wire.response.emittedEvents.map((e) => e.event) });
+    trace(k, wire.response);
+    mirror(wire.response);
+    store.notify();
+    if (transport === void 0 || wire.serverLegs.length === 0 && wire.statefulLeg === null) return { response: wire.response, mode: wire.mode };
+    const painters = hooks.filter((h) => h.onLocal !== void 0);
+    for (const h of painters) h.onLocal?.(wire.response);
+    const posted = await post(k, wire, request, { rollback: true, awaiting: !progress });
+    const localPainted = painters.length > 0;
+    if (posted.rolledBack !== void 0) {
+      return { response: posted.response, mode: wire.mode, ...localPainted ? { localPainted, serverEffects: posted.rolledBack } : {} };
+    }
+    return localPainted ? { response: posted.response, mode: wire.mode, localPainted, serverEffects: posted.serverEffects } : { response: posted.response, mode: wire.mode };
+  };
+  const settleMount = async (k, mount, seeds, hooks, baseRequest) => {
+    if (mount.failed !== null) {
+      const failed = mount.failed;
+      throw new TraitMountError(failed.trait, failed.event, new Error(failed.message));
+    }
+    const wires = mount.seeds;
+    for (const wire of wires) {
+      const kept = mountedSeeds.get(wire.orbital) ?? [];
+      if (!kept.some((s) => s.trait === wire.seed.trait)) mountedSeeds.set(wire.orbital, [...kept, { trait: wire.seed.trait, event: seeds.find((s) => s.trait === wire.seed.trait)?.event ?? "INIT" }]);
+    }
+    for (const wire of wires) {
+      log.debug("mount", { trait: wire.seed.trait, event: wire.seed.event, mode: wire.mode, legs: wire.serverLegs.length, success: wire.response.success });
+      trace(k, wire.response);
+      mirror(wire.response);
+    }
+    store.notify();
+    for (const wire of wires) hooks?.onLocal?.(wire.seed.trait, wire.response);
+    const outcome = {
+      seeds: wires.map((w) => ({ trait: w.seed.trait, event: w.seed.event, mode: w.mode, local: w.response })),
+      posted: false,
+      success: true,
+      rejections: [],
+      serverEffects: { clientEffectsByTrait: [] },
+      emittedEvents: []
+    };
+    if (transport === void 0) return outcome;
+    const topology = await opts.topology;
+    const groups = (topology.carriesCircuitState ? mount.legs : mount.statefulLegs).map((group) => {
+      const answered = wires.filter((w) => group.seeds.some((s) => s.trait === w.seed.trait && s.event === w.seed.event));
+      const flown = answered.filter((w) => w.flight !== null && w.flight !== void 0);
+      return { group, answered, flight: Math.min(...(flown.length > 0 ? flown : answered).map(flightOf)) };
+    }).sort((a, b) => a.flight - b.flight);
+    for (const wire of wires) if (!groups.some(({ answered }) => answered.includes(wire))) endFlight(k, wire.flight);
+    for (const { group, answered, flight } of groups) {
+      const planned = { orbital: group.orbital, leg: group.leg, keepsState: true, alreadyDelivered: group.alreadyDelivered, foldSeeded: group.foldSeeded, wires: answered, flight };
+      store.awaiting.begin(group.awaiting);
+      let posted;
+      try {
+        posted = await sendLegs(k, [planned], baseRequest, { rollback: false, mount: true }, answered[0]?.response ?? outcome.seeds[0].local);
+      } finally {
+        store.awaiting.end(group.awaiting.map((a) => a.trait));
+        for (const wire of answered) endFlight(k, wire.flight);
+      }
+      outcome.posted = true;
+      outcome.success = outcome.success && posted.success;
+      if (posted.error !== void 0) outcome.error = posted.error;
+      outcome.rejections.push(...posted.rejections);
+      outcome.serverEffects.clientEffectsByTrait?.push(...posted.serverEffects.clientEffectsByTrait ?? []);
+      outcome.emittedEvents.push(...posted.foldedEmits);
+    }
+    return outcome;
+  };
+  const deliver = async (emitted, fold) => {
+    const k = await ready;
+    await scopeTail;
+    const flight = k.openFlight();
+    try {
+      const applied = await fold(k, flight);
+      trace(k, applied.response);
+      mirror(applied.response);
+      syncStates(k, applied.applied.map(([trait]) => trait));
+      store.notify();
+      const owed = applied.serverLegs.map((routed) => ({ orbital: routed.orbital, leg: routed.leg, keepsState: true, alreadyDelivered: [], foldSeeded: [], wires: [], flight }));
+      const posted = await sendLegs(k, owed, {}, { rollback: false, mount: false }, applied.response);
+      return { response: posted.response };
+    } finally {
+      endFlight(k, flight);
+    }
+  };
+  const clientSerial = nextClientSerial++;
+  const release = async (left) => {
+    if (transport === void 0 || left.length === 0) return;
+    await opts.topology;
+    for (const { trait, orbital, leg } of left) {
+      transport.send(orbital, leg).catch((err) => log.warn("unmount-post-failed", { trait, orbital, error: String(err) }));
+    }
+  };
+  const client = {
+    store,
+    dispatch: (request, hooks) => dispatchOne(request, hooks !== void 0 ? [hooks] : [], false),
+    dispatchProgress: (request) => dispatchOne(request, [], true),
+    foldHostDispatch: async (request, response) => {
+      const k = await ready;
+      if (request.targetTrait === void 0) throw new Error("foldHostDispatch requires request.targetTrait (the seed trait)");
+      const mode = parse(k.dispatchMode(request.targetTrait));
+      if (!response.success) return { response: { ...response, clientEffectsByTrait: [] }, mode };
+      const flight = k.openFlight();
+      try {
+        const applied = await foldInOrder(k, flight, response, "[]", void 0);
+        trace(k, applied.response);
+        mirror(applied.response);
+        syncStates(k, [...Object.keys(response.states), ...applied.applied.map(([trait]) => trait)]);
+        store.notify();
+        const owed = applied.serverLegs.map((routed) => ({ orbital: routed.orbital, leg: routed.leg, keepsState: true, alreadyDelivered: [], foldSeeded: [], wires: [], flight }));
+        const posted = await sendLegs(k, owed, request, { rollback: false, mount: false }, applied.response);
+        return {
+          response: {
+            ...response,
+            clientEffectsByTrait: [...response.clientEffectsByTrait ?? [], ...posted.response.clientEffectsByTrait ?? []]
+          },
+          mode
+        };
+      } finally {
+        endFlight(k, flight);
+      }
+    },
+    deliverEmit: (emitted) => deliver(emitted, (k, flight) => foldInOrder(k, flight, { success: true, transitioned: false, states: {}, emittedEvents: [emitted] }, "[]", void 0)),
+    deliverToListeners: (emitted) => deliver(emitted, (k, flight) => deliverInOrder(k, flight, emitted)),
+    deliverOriginEmit: (emitted) => deliver(emitted, (k, flight) => deliverOriginInOrder(k, flight, emitted)),
+    dispatchMount: async (seeds, hooks, base) => {
+      const k = await ready;
+      await scopeTail;
+      const baseRequest = base ?? {};
+      k.mount(JSON.stringify(seeds.map((s) => s.trait)));
+      const mount = parse(k.dispatchMount(JSON.stringify(seeds), baseRequest.entityId, payloadJson(baseRequest.payload), baseRequest.route));
+      try {
+        return await settleMount(k, mount, seeds, hooks, baseRequest);
+      } finally {
+        for (const wire of mount.seeds) endFlight(k, wire.flight);
+      }
+    },
+    routeMounts: async (routePath) => parse((await ready).routeMounts(routePath)),
+    pageCircuit: async (page, route) => parse((await ready).pageCircuit(page, route)),
+    enter: (routePath, mountKey, traits) => {
+      const entered = scopeTail.then(() => ready).then((k) => parse(k.enter(routePath, `${clientSerial}\0${mountKey}`, JSON.stringify(traits))));
+      scopeTail = entered.then(() => void 0, () => void 0);
+      return entered.then((answer) => {
+        void release(answer.left);
+        return { seeds: answer.seeds, left: answer.left.map((l) => l.trait) };
+      });
+    },
+    leave: async () => {
+      const left = scopeTail.then(() => ready).then((k) => parse(k.leave()));
+      scopeTail = left.then(() => void 0, () => void 0);
+      await release(await left);
+    },
+    frame: async (nowMs) => {
+      const k = await ready;
+      await scopeTail;
+      const ran = await runTickFrame(tickPorts(k), () => nowMs);
+      publishTrace(k);
+      return ran.outcomes;
+    },
+    framePause: () => loaded?.framePause(),
+    frameResume: () => loaded?.frameResume(),
+    startFrames: (onFrame, schedule = defaultFrameScheduler) => {
+      const presence = getTraitPresence();
+      const releases = visibleGroups.map(([, group]) => presence.watch(group));
+      let stopped = false;
+      let latestMs = 0;
+      let nextHandle = 0;
+      const cancels = /* @__PURE__ */ new Map();
+      const visibility = {
+        hidden: () => document.visibilityState === "hidden",
+        onChange: (listener) => {
+          document.addEventListener("visibilitychange", listener);
+          return () => document.removeEventListener("visibilitychange", listener);
+        }
+      };
+      let driver;
+      ready.then(async (k) => {
+        await scopeTail;
+        if (stopped) return;
+        driver = createTickDriver({
+          ...tickPorts(k),
+          now: () => latestMs,
+          requestFrame: (callback) => {
+            nextHandle += 1;
+            const handle = nextHandle;
+            cancels.set(handle, schedule((nowMs) => {
+              cancels.delete(handle);
+              latestMs = nowMs;
+              callback(nowMs);
+            }));
+            return handle;
+          },
+          cancelFrame: (handle) => {
+            cancels.get(handle)?.();
+            cancels.delete(handle);
+          },
+          visibility,
+          onApplied: (applied) => {
+            publishTrace(k);
+            if (!stopped && applied.outcomes.length > 0) onFrame(applied.outcomes);
+          },
+          onError: (error) => log.error("kernel-frame-failed", { error: error.message })
+        });
+        driver.start();
+      }).catch((error) => log.error("kernel-frame-failed", { error: error.message }));
+      return () => {
+        stopped = true;
+        driver?.stop();
+        releases.forEach((release2) => release2());
+      };
+    },
+    traceStream: (traits, onItem) => {
+      const stream = { traits: new Set(traits), onItem };
+      traceStreams.add(stream);
+      void ready.then((k) => k.setTraceOn(true)).catch((error) => log.error("trace-stream-failed", { error: error.message }));
+      return () => {
+        traceStreams.delete(stream);
+        if (traceStreams.size === 0) loaded?.setTraceOn(false);
+      };
+    },
+    traitState: (traitName) => loaded?.getState(traitName),
+    sessionTheme: () => loaded?.sessionTheme(),
+    traitConfig: (traitName) => {
+      if (loaded === void 0) return void 0;
+      const held = configs.get(traitName);
+      if (held !== void 0) return held;
+      const config = parse(loaded.traitConfig(traitName));
+      configs.set(traitName, config);
+      return config;
+    }
+  };
+  return client;
+}
+
+export { createKernelClient };

package/dist/kernel-wire-wNdAPfhJ.d.ts

@@ -0,0 +1,88 @@
+import { KernelModule as KernelModule$1 } from '@almadar/shell-browser/kv';
+import './verification-C5pTeMJv.js';
+
+/**
+ * The `Kernel` class surface of `@almadar/kernel` (JSON strings in, JSON strings out). The wire data it
+ * speaks (`DispatchWire`, `AppliedWire`, `FrameWire`, ...) is imported from `@almadar/core/kernel-wire`.
+ *
+ * @packageDocumentation
+ */
+
+/** The `Kernel` class `@almadar/kernel` exports: JSON strings in, JSON strings out. */
+interface KernelInstance {
+    dispatch(traitName: string, entityId: string | undefined, event: string, payloadJson?: string): string;
+    /** A flight for work the kernel did not wire (a dispatch the host ran on its own, a frame's browser leg). */
+    openFlight(): number;
+    /** `applyServerResponse` in flight order (EXEC-CONC-8): a `FoldProgressWire` as JSON, folded now or queued behind an older flight. */
+    foldInOrder(flight: number, responseJson: string, alreadyDeliveredJson?: string, baseJson?: string): string;
+    /** `foldInOrder` for an emit that entered from outside the kernel (another client's push): delivered to its declared listeners only, a `FoldProgressWire` as JSON. */
+    deliverEmitToListeners(flight: number, emittedJson: string): string;
+    /** `deliverEmitToListeners` for a live message of this client's own running call, whose emitter ran its own arm as that call's progress dispatch: the emitter is not delivered its own emit a second time. */
+    deliverOriginEmit(flight: number, emittedJson: string): string;
+    /** The oldest queued answer that can fold now, folded: a `FoldedNextWire` as JSON, or `undefined` when none waits. */
+    nextFold(): string | undefined;
+    /** The flight is done: its answers are folded, or the host gave up on them. */
+    endFlight(flight: number): boolean;
+    /** The rows a posted leg's answer is folded against; `undefined` when the leg carried none. */
+    /** The leg as a host that holds the circuit state takes it: only the `[shared]` frame rows its traits read. */
+    statefulLeg(legJson: string): string;
+    /** The mount a reconnecting client posts to rebuild its session: the seeds with the state and frame this client holds for each. */
+    reseedLeg(seedsJson: string, entityId?: string): string;
+    foldBase(carriedJson: string | undefined, seededJson: string, entityId?: string): string | undefined;
+    dispatchMount(seedsJson: string, entityId?: string, payloadJson?: string, route?: string): string;
+    /** The frame delta a painter at version `since` of this kernel's frames needs (`FrameDelta` JSON): empty when current, else a snapshot. */
+    framesSince(since: number): string;
+    restore(traitName: string, entityId: string | undefined, snapshotJson: string): string;
+    tick(traitName: string, tickName: string, entityId?: string): string;
+    frame(nowMs: number): string | undefined;
+    framePause(): void;
+    frameResume(): void;
+    tickCount(): number;
+    /** The theme key the server bound to this client's session with `theme/set` (mirrored from its frames); `undefined` when none is. */
+    sessionTheme(): string | undefined;
+    /** The kernel's dispatch mode for a registered trait (`DispatchMode` as JSON text); throws for an unregistered one. */
+    dispatchMode(traitName: string): string;
+    /** The config the kernel binds as `@config` for a registered trait (JSON text); throws for an unregistered one. */
+    traitConfig(traitName: string): string;
+    getState(traitName: string, entityId?: string): string;
+    /** The page's locale `i18n/t` paints in when a dispatch names none; the program carries its own messages. */
+    setViewerLocale(locale: string | undefined): void;
+    /** The host runs the listeners of every emit it marks `dispatched` (the JS runtime, `orbital-server`). */
+    setHostFansOut(fansOut: boolean): void;
+    /** Carry each hop's `@entity` before and after it on the dispatch's transitions, for a verifier (EXEC-STEP-10). */
+    setRecordEntityAfter(record: boolean): void;
+    /** Record each dispatch as a trace item while on, for the host's `program/live { kind: "trace" }` streams (EXEC-DIST-14). */
+    setTraceOn(on: boolean): void;
+    /** The trace items recorded since the last take, in dispatch order: a JSON array. */
+    takeTrace(): string;
+    /** Carry each frame response's `effectResults` (omitted otherwise), for a verifier. */
+    setFrameEffectResults(carry: boolean): void;
+    /** The kernel's mounts for a host start on `side` (`client|server|process|start`): `MountSeed[]` as JSON. */
+    bootMounts(side: string): string;
+    /** The kernel's mounts for a client opening `routePath`: `MountSeed[]` as JSON. */
+    routeMounts(routePath: string): string;
+    /** The circuit a client mounts for `page` or `route` (neither: the initial page): a `PageCircuit` as JSON. */
+    pageCircuit(page?: string, route?: string): string;
+    /** One question about the registered program (a `ContractQuery` as JSON): its answer as JSON. */
+    contractQuery(queryJson: string): string;
+    mount(traitsJson: string): void;
+    /** The page `mountKey` holds `traitsJson`, opened at `routePath` when it has one: an `Entered` as JSON (the seeds to mount, the traits that left with the legs that release them). */
+    enter(routePath: string | undefined, mountKey: string, traitsJson: string): string;
+    /** Every trait the page entered leaves: `Left[]` as JSON. */
+    leave(): string;
+    /** The host's report of whether a trait's rendered output is on screen; gates its `[visible]` ticks. */
+    setTraitOnScreen(traitName: string, onScreen: boolean): void;
+    seed(entityType: string, rowsJson: string): void;
+    free(): void;
+}
+/**
+ * What a host's loader resolves: the `@almadar/kernel` module with its WebAssembly already
+ * initialised and its language installed (`loadBrowserKernel` in a browser, `initSync` in Node). `@almadar/ui` never imports the
+ * package itself, so the default bundle carries none of it.
+ */
+interface KernelModule extends KernelModule$1 {
+    Kernel: new (resolvedSchemaJson: string, clientId: string) => KernelInstance;
+}
+type KernelLoader = () => Promise<KernelModule>;
+
+export type { KernelModule as K, KernelLoader as a, KernelInstance as b };