@almadar/shell-web 0.0.0-stage → 0.1.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-ZH4PSMCN.js

@@ -0,0 +1,367 @@
+import { createLocalFold, src_exports, createTickDriver, runTickFrame, mirrorResponse, traceResponse } from './chunk-6P3MWXYE.js';
+import './chunk-DYEKAA4L.js';
+import { presenceGroup, getTraitPresence } from './chunk-MBQAMMSE.js';
+import './chunk-G7DCAZ22.js';
+import { TraitMountError } from '@almadar/shell-runtime/client/trait-mount-error';
+import { createLogger } from '@almadar/logger';
+
+var log = createLogger("almadar:ui:kernel-client");
+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.irTrait.ticks ?? []).some((tick) => tick.whileVisible === true)).map(([name]) => [name, presenceGroup(traitIndex, name)]);
+  let queueTail = Promise.resolve();
+  const enqueue = (run) => {
+    const result = queueTail.then(run);
+    queueTail = result.then(() => void 0, () => void 0);
+    return result;
+  };
+  let progressTail = Promise.resolve();
+  let scopeTail = Promise.resolve();
+  const declareScope = (apply) => {
+    const applied = scopeTail.then(() => ready).then(apply);
+    scopeTail = applied.then(() => void 0, () => void 0);
+    return applied;
+  };
+  const frameKeyOf = (trait) => traitIndex.byName.get(trait)?.frameKey;
+  const mirror = (response) => mirrorResponse(store, frameKeyOf, response);
+  const trace = (response) => traceResponse(opts.observer, response);
+  const localFold = createLocalFold({ store, frameKeyOf, ...opts.observer !== void 0 ? { observer: opts.observer } : {} });
+  const lane = new src_exports.DispatchLane();
+  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 { clientEffects: [], clientEffectsByTrait: [] };
+    const trait = wire.seed.trait;
+    const repaint = parse(k.restore(trait, entityId, JSON.stringify(snapshot)));
+    const frameKey = traitIndex.byName.get(trait)?.frameKey ?? trait;
+    if (snapshot.state !== "") store.states.rollbackState(trait, snapshot.state, entityId, "server-rejected");
+    const entity = snapshot.entity;
+    if (entity !== null && typeof entity === "object" && !Array.isArray(entity)) store.frames.set(frameKey, { ...entity });
+    else store.frames.delete(frameKey);
+    mirror(repaint);
+    store.notify();
+    return { clientEffects: repaint.clientEffects ?? [], 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]
+        }))
+      };
+    }
+    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] }]
+      };
+    }
+    return { legs: [], awaiting: [] };
+  };
+  const sendLegs = async (k, legs, request, flags, initial) => {
+    const out = {
+      response: initial,
+      serverEffects: { clientEffects: [], 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 transport.send(planned.orbital, sent);
+      } 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 = parse(k.applyServerResponse(JSON.stringify(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(applied.response);
+      for (const routed of applied.serverLegs) {
+        queue.push({ orbital: routed.orbital, leg: routed.leg, keepsState: true, alreadyDelivered: [], foldSeeded: [], wires: [] });
+      }
+      mirror(posted);
+      mirror(applied.response);
+      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 effects = [...posted.clientEffects ?? [], ...fold.clientEffects ?? []];
+      const byTrait = [...posted.clientEffectsByTrait ?? [], ...fold.clientEffectsByTrait ?? []];
+      out.serverEffects.clientEffects?.push(...effects);
+      out.serverEffects.clientEffectsByTrait?.push(...byTrait);
+      out.foldedEmits.push(...serverEmits, ...fold.emittedEvents);
+      out.response = {
+        ...out.response,
+        emittedEvents: [...out.response.emittedEvents, ...serverEmits, ...fold.emittedEvents],
+        clientEffects: [...out.response.clientEffects ?? [], ...effects],
+        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"));
+    }
+    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) => (await post(k, wire, {}, { rollback: false, awaiting: false })).serverEffects,
+      sendBrowserLeg: async (routed, frameResponse) => {
+        const planned = { orbital: routed.orbital, leg: routed.leg, keepsState: true, alreadyDelivered: [], foldSeeded: [], wires: [] };
+        return (await sendLegs(k, [planned], {}, { rollback: false, mount: false }, frameResponse)).serverEffects;
+      }
+    };
+  };
+  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()
+    },
+    lane,
+    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;
+    if (request.runTick !== void 0) {
+      const response = parse(k.tick(request.runTick.trait, request.runTick.tick, request.entityId));
+      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)));
+    log.debug("dispatch", { trait: traitName, 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(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 client = {
+    store,
+    dispatch: (request, hooks) => enqueue(() => dispatchOne(request, hooks !== void 0 ? [hooks] : [], false)),
+    dispatchProgress: (request) => {
+      const outcome = progressTail.then(() => dispatchOne(request, [], true));
+      progressTail = outcome.then(() => void 0, () => void 0);
+      return outcome;
+    },
+    foldHostDispatch: (request, response) => enqueue(async () => {
+      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, clientEffects: [], clientEffectsByTrait: [] }, mode };
+      const applied = parse(k.applyServerResponse(JSON.stringify(response), "[]"));
+      trace(applied.response);
+      mirror(response);
+      mirror(applied.response);
+      syncStates(k, [...Object.keys(response.states), ...applied.applied.map(([trait]) => trait)]);
+      store.notify();
+      return {
+        response: {
+          ...response,
+          clientEffects: [...response.clientEffects ?? [], ...applied.response.clientEffects ?? []],
+          clientEffectsByTrait: [...response.clientEffectsByTrait ?? [], ...applied.response.clientEffectsByTrait ?? []]
+        },
+        mode
+      };
+    }),
+    dispatchMount: (seeds, hooks, base) => enqueue(async () => {
+      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)));
+      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) {
+        log.debug("mount", { trait: wire.seed.trait, event: wire.seed.event, mode: wire.mode, legs: wire.serverLegs.length, success: wire.response.success });
+        trace(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: { clientEffects: [], clientEffectsByTrait: [] },
+        emittedEvents: []
+      };
+      if (transport === void 0) return outcome;
+      const topology = await opts.topology;
+      for (const group of topology.carriesCircuitState ? mount.legs : mount.statefulLegs) {
+        const answered = wires.filter((w) => group.seeds.some((s) => s.trait === w.seed.trait && s.event === w.seed.event));
+        const planned = { orbital: group.orbital, leg: group.leg, keepsState: true, alreadyDelivered: group.alreadyDelivered, foldSeeded: group.foldSeeded, wires: answered };
+        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));
+        }
+        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.clientEffects?.push(...posted.serverEffects.clientEffects ?? []);
+        outcome.serverEffects.clientEffectsByTrait?.push(...posted.serverEffects.clientEffectsByTrait ?? []);
+        outcome.emittedEvents.push(...posted.foldedEmits);
+      }
+      return outcome;
+    }),
+    routeMounts: async (routePath) => parse((await ready).routeMounts(routePath)),
+    remount: (traits) => declareScope((k) => k.remount(JSON.stringify(traits))),
+    mount: (traits) => declareScope((k) => k.mount(JSON.stringify(traits))),
+    unmount: (traits) => declareScope((k) => k.unmount(JSON.stringify(traits))),
+    frame: async (nowMs) => {
+      const k = await ready;
+      await scopeTail;
+      return (await runTickFrame(tickPorts(k), () => nowMs)).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) => {
+            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((release) => release());
+      };
+    },
+    traitState: (traitName) => loaded?.getState(traitName),
+    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;
+    },
+    setViewer: async (user) => {
+      const k = await ready;
+      k.setCurrentUser(JSON.stringify(user));
+      configs.clear();
+    }
+  };
+  return client;
+}
+
+export { createKernelClient };

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

@@ -0,0 +1,65 @@
+import { OrbitalSchema } from '@almadar/core';
+import { KernelModule as KernelModule$1 } from '@almadar/shell-runtime/kernel/wire';
+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;
+    applyServerResponse(responseJson: string, alreadyDeliveredJson?: string, baseJson?: string): string;
+    /** 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;
+    foldBase(carriedJson: string | undefined, seededJson: string, entityId?: string): string | undefined;
+    dispatchMount(seedsJson: string, entityId?: string, payloadJson?: string): 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 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;
+    setCurrentUser(userJson: string): void;
+    /** The viewer's locales (`string[]`, the first is painted) and their catalogs (`{ [locale]: { [key]: text } }`) for `i18n/t`. */
+    setMessages(localesJson: string, catalogsJson: string): 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;
+    /** 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;
+    mount(traitsJson: string): void;
+    remount(traitsJson: string): void;
+    unmount(traitsJson: string): void;
+    /** 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 (`await init()` 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>;
+/** Resolves the language bundle (`@almadar/core/language-data` `LanguageBundle`) as JSON text, for a kernel a browser opens over a local store. */
+type LanguageLoader = () => Promise<string>;
+/** Resolves the std `std-mock-seed` program (an already-resolved schema) that seeds a mock or browser store. */
+type SeedProgramLoader = () => Promise<OrbitalSchema>;
+
+export type { KernelModule as K, LanguageLoader as L, SeedProgramLoader as S, KernelLoader as a, KernelInstance as b };