@almadar/shell-runtime 0.0.0-stage → 0.1.0

package/dist/chunk-ZAQSS47X.js

@@ -0,0 +1,157 @@
+import { base64Standard, isOAuthReason, isOAuthCode } from './chunk-YO4LWS3I.js';
+import { isJsonObject } from '@almadar/core';
+
+var PENDING_GRANT_TTL_MS = 10 * 60 * 1e3;
+var MOCK_PENDING_TTL_MS = Number.MAX_SAFE_INTEGER;
+var PROVIDERS = ["google", "github", "auth0"];
+var OAuthEffectFailure = class extends Error {
+  constructor(payload) {
+    super(payload.error);
+    this.payload = payload;
+  }
+  payload;
+};
+function parsed(text) {
+  return JSON.parse(text);
+}
+function objectOf(value, what) {
+  if (value === void 0 || !isJsonObject(value)) throw new Error(`${what} is malformed`);
+  return value;
+}
+function failureOf(kernel, reason) {
+  if (kernel.oauthFailure === void 0) throw new Error("this kernel build has no OAuth failure messages");
+  const payload = objectOf(parsed(kernel.oauthFailure(reason)), "the oauth failure");
+  const { error, code } = payload;
+  if (typeof error !== "string" || !isOAuthCode(code)) throw new Error("the oauth failure is malformed");
+  return new OAuthEffectFailure({ error, code, reason });
+}
+async function ask(ports, kernel, request, principal) {
+  if (ports.oauth === void 0) throw failureOf(kernel, "store-unavailable");
+  try {
+    const reply = await ports.oauth.answer(request, principal);
+    if (!isReplyOf(request, reply)) throw new Error("wrong reply");
+    return reply;
+  } catch {
+    throw failureOf(kernel, "store-unavailable");
+  }
+}
+function isReplyOf(request, reply) {
+  switch (request.ask) {
+    case "pendingPut":
+    case "subjectRemember":
+    case "subjectForget":
+    case "metadataPut":
+      return reply.reply === "done";
+    case "pendingTake":
+      return reply.reply === "taken";
+    case "connectionAvailable":
+      return reply.reply === "flag";
+    case "connectionSave":
+    case "connectionStatus":
+    case "connectionRemove":
+      return reply.reply === "row";
+    case "subjectLookup":
+      return reply.reply === "subject";
+    case "metadataGet":
+      return reply.reply === "metadata";
+    case "clock":
+      return reply.reply === "millis";
+    case "mockTokenPut":
+      return reply.reply === "done";
+    case "mockTokenRefresh":
+    case "mockTokenRevoke":
+      return reply.reply === "flag";
+    case "mockTokenCheck":
+      return reply.reply === "mockToken";
+    case "consent":
+      return reply.reply === "code";
+  }
+}
+async function oauthAuthorizePayload(ports, client, options, principal, key) {
+  if (key !== void 0 && (typeof key !== "string" || key === "")) {
+    throw new Error(`call key must evaluate to a non-empty string, got ${String(key)}`);
+  }
+  const echoed = typeof key === "string" ? key : null;
+  const kernel = await ports.kernel();
+  if (kernel.oauthAuthorizePlan === void 0 || kernel.oauthAuthorizeBuild === void 0) {
+    throw new Error("oauth-authorize: this kernel build cannot run it");
+  }
+  const planned = objectOf(parsed(kernel.oauthAuthorizePlan(JSON.stringify(client ?? null), JSON.stringify(options ?? null))), "the authorize plan");
+  if (planned.mode === "mock") {
+    if (kernel.oauthAuthorizeMockBuild === void 0) throw new Error("oauth-authorize: this kernel build cannot run it");
+    const mock = objectOf(parsed(kernel.oauthAuthorizeMockBuild(JSON.stringify(planned.plan ?? null), base64Standard(ports.random(16)))), "the authorization");
+    return keepGrant(ports, kernel, mock, MOCK_PENDING_TTL_MS, principal, echoed, false);
+  }
+  const slot = objectOf(planned.clientId, "the client id slot");
+  if (typeof slot.name !== "string") throw new Error("the client id slot is malformed");
+  let owner;
+  if (slot.scope === "user") {
+    if (principal === void 0) throw failureOf(kernel, "not-signed-in");
+    owner = principal;
+  }
+  const clientId = await ports.secrets.get(slot.name, owner);
+  if (clientId === void 0) throw failureOf(kernel, "unconfigured-client");
+  let metadata = planned.metadata ?? null;
+  if (typeof planned.issuer === "string") {
+    const reply = await ask(ports, kernel, { ask: "metadataGet", issuer: planned.issuer }, principal);
+    metadata = reply.reply === "metadata" ? reply.metadata : null;
+  }
+  if (metadata === null) throw failureOf(kernel, "metadata-invalid");
+  const state = ports.random(32);
+  const verifier = ports.random(32);
+  const built = objectOf(
+    parsed(kernel.oauthAuthorizeBuild(JSON.stringify(planned.plan ?? null), clientId, JSON.stringify(metadata), base64Standard(state), base64Standard(verifier))),
+    "the authorization"
+  );
+  if (typeof built.refused === "string") throw new Error(built.refused);
+  if (built.failure !== void 0) {
+    const failure = objectOf(built.failure, "the failure");
+    const reason = failure.reason;
+    if (!isOAuthReason(reason)) throw new Error("the oauth failure is malformed");
+    throw failureOf(kernel, reason);
+  }
+  return keepGrant(ports, kernel, objectOf(built.ok, "the authorization"), PENDING_GRANT_TTL_MS, principal, echoed, true);
+}
+async function keepGrant(ports, kernel, ok, ttlMs, principal, key, consent) {
+  const grant = objectOf(ok.grant, "the pending grant");
+  if (typeof ok.authUrl !== "string" || typeof ok.state !== "string") throw new Error("the authorization is malformed");
+  const scopes = Array.isArray(grant.scopes) ? grant.scopes.flatMap((scope) => typeof scope === "string" ? [scope] : []) : [];
+  await ask(
+    ports,
+    kernel,
+    {
+      ask: "pendingPut",
+      state: ok.state,
+      ttlMs,
+      grant: {
+        provider: String(grant.provider),
+        redirectUri: String(grant.redirectUri),
+        verifier: String(grant.verifier),
+        subject: typeof grant.subject === "string" ? grant.subject : null,
+        scopes
+      }
+    },
+    principal
+  );
+  let code = "";
+  if (consent) {
+    const reply = await ask(ports, kernel, { ask: "consent", authUrl: ok.authUrl, state: ok.state, redirectUri: String(grant.redirectUri) }, principal);
+    code = reply.reply === "code" ? reply.code ?? "" : "";
+  }
+  return { authUrl: ok.authUrl, state: ok.state, code, key };
+}
+async function oauthConnectionPayload(ports, head, provider, principal) {
+  const word = PROVIDERS.find((known) => known === provider);
+  if (word === void 0) {
+    throw new Error(typeof provider === "string" ? `${head}: provider must be google, github or auth0, not \`${provider}\`` : `${head}: provider must be a provider word`);
+  }
+  const kernel = await ports.kernel();
+  const available = await ask(ports, kernel, { ask: "connectionAvailable" }, principal);
+  if (available.reply !== "flag" || !available.value) throw failureOf(kernel, "store-unavailable");
+  if (principal === void 0 || principal === "") throw failureOf(kernel, "not-signed-in");
+  const reply = await ask(ports, kernel, head === "oauth-connection-status" ? { ask: "connectionStatus", provider: word } : { ask: "connectionRemove", provider: word }, principal);
+  if (reply.reply !== "row") throw failureOf(kernel, "store-unavailable");
+  return reply.row;
+}
+
+export { OAuthEffectFailure, oauthAuthorizePayload, oauthConnectionPayload };

package/dist/chunk-ZCQUUJIF.js

@@ -0,0 +1,129 @@
+import { detectLayoutStrategy } from './chunk-EV56K4GB.js';
+import { applyEventWiring } from './chunk-MHYSHSRG.js';
+
+// src/runtime/effects/composition/compose-behaviors.ts
+function isSchema(input) {
+  return "orbitals" in input && Array.isArray(input.orbitals);
+}
+function asDefinitions(inputs) {
+  return inputs.flatMap(
+    (input) => isSchema(input) ? input.orbitals : [input]
+  );
+}
+function mergeLedgers(inputs) {
+  const merged = /* @__PURE__ */ new Map();
+  let sawLedger = false;
+  for (const input of inputs) {
+    if (!isSchema(input) || input.ledger === void 0) continue;
+    sawLedger = true;
+    for (const [id, entry] of Object.entries(input.ledger.entries)) {
+      if (!merged.has(id)) merged.set(id, entry);
+    }
+  }
+  if (!sawLedger) return void 0;
+  const entries = {};
+  for (const [id, entry] of [...merged.entries()].sort(
+    ([a], [b]) => a < b ? -1 : a > b ? 1 : 0
+  )) {
+    entries[id] = entry;
+  }
+  return { schemaVersion: 1, entries };
+}
+function mergeSchemaVersions(inputs) {
+  let max;
+  for (const input of inputs) {
+    if (!isSchema(input) || input.schemaVersion === void 0) continue;
+    max = max === void 0 ? input.schemaVersion : Math.max(max, input.schemaVersion);
+  }
+  return max;
+}
+function toKebabCase(name) {
+  return name.replace(/([a-z])([A-Z])/g, "$1-$2").replace(/[\s_]+/g, "-").toLowerCase();
+}
+function generatePages(orbitals, strategy) {
+  switch (strategy) {
+    case "single": {
+      const orbital = orbitals[0];
+      const name = orbital?.name ?? "Main";
+      return [
+        {
+          name: `${name}Page`,
+          path: "/",
+          isInitial: true,
+          primaryEntity: getEntityName(orbital)
+        }
+      ];
+    }
+    case "dashboard": {
+      return [
+        {
+          name: "DashboardPage",
+          path: "/",
+          viewType: "dashboard",
+          isInitial: true
+        }
+      ];
+    }
+    case "sidebar":
+    case "tabs":
+    case "wizard-flow": {
+      return orbitals.map((orbital, index) => ({
+        name: `${orbital.name}Page`,
+        path: index === 0 ? "/" : `/${toKebabCase(orbital.name)}`,
+        isInitial: index === 0,
+        primaryEntity: getEntityName(orbital)
+      }));
+    }
+  }
+}
+function getEntityName(orbital) {
+  if (!orbital) return void 0;
+  const entity = orbital.entity;
+  if (typeof entity === "string") {
+    return entity.replace(".entity", "");
+  }
+  return entity.name;
+}
+function composeBehaviors(input) {
+  const {
+    appName,
+    orbitals: rawInputs,
+    layoutStrategy: strategyInput,
+    eventWiring
+  } = input;
+  const rawOrbitals = asDefinitions(rawInputs);
+  const wiredOrbitals = eventWiring && eventWiring.length > 0 ? applyEventWiring(rawOrbitals, eventWiring) : rawOrbitals;
+  const strategy = !strategyInput || strategyInput === "auto" ? detectLayoutStrategy(wiredOrbitals, eventWiring) : strategyInput;
+  const pages = generatePages(wiredOrbitals, strategy);
+  const orbitalsWithPages = wiredOrbitals.map((orbital, index) => {
+    if (orbital.pages && orbital.pages.length > 0) {
+      return orbital;
+    }
+    const page = strategy === "dashboard" || strategy === "single" ? pages[0] : pages[index];
+    return {
+      ...orbital,
+      pages: page ? [page] : []
+    };
+  });
+  const ledger = mergeLedgers(rawInputs);
+  const schemaVersion = mergeSchemaVersions(rawInputs);
+  const schema = {
+    name: appName,
+    version: "1.0.0",
+    orbitals: orbitalsWithPages,
+    ...schemaVersion !== void 0 ? { schemaVersion } : {},
+    ...ledger !== void 0 ? { ledger } : {}
+  };
+  return {
+    schema,
+    layout: {
+      strategy,
+      pageCount: pages.length
+    },
+    wiring: {
+      connections: eventWiring?.length ?? 0
+    }
+  };
+}
+
+export { composeBehaviors };

package/dist/client/EventTransport.d.ts

@@ -0,0 +1,131 @@
+import { OrbitalSchema, OrbitalEventRequest, OrbitalEventResponse, RowSetRef, RowQueryPage, EmittedEvent, ServerTopology } from '@almadar/core';
+
+/**
+ * EventTransport — the client → orbital event transport port (plan P5,
+ * `docs/Almadar_Runtime_Stateless_Stateful_PLAN.md` §4.2).
+ *
+ * Promotes `@almadar/ui`'s `ServerBridgeTransport` interface +
+ * `createHttpTransport` into `@almadar/runtime` so there is ONE owner of
+ * the HTTP request/response leg instead of two (this package's own
+ * `ServerBridge` class and the ui provider). `@almadar/ui`'s provider will
+ * be switched onto this port at the W5b build checkpoint (see the plan);
+ * until then this file has no consumers outside this package.
+ *
+ * The wire shapes are `@almadar/core`'s existing `OrbitalEventRequest` /
+ * `OrbitalEventResponse` — no shadow types.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * `true` = stateless topology: the server holds no circuit state between
+ * requests, so every `send()` request must carry `traits`/`entityByTrait`.
+ * `false` = the server (or an in-process evaluator) holds the state itself.
+ *
+ * Derivation mirrors `@almadar/ui`'s `ServerBridgeProvider` EXACTLY
+ * (`providers/ServerBridge.tsx`, both the initial-state fallback and the
+ * post-register `.then` callback — the same mapping was duplicated at two
+ * call sites there, which is the `stateSource` string-branching this port
+ * retires): `'stateful'` → false, `'stateless'` OR an absent/undeclared
+ * topology (older servers) → true. An absent topology defaulting to
+ * "stateless" is the ui's existing assumption, carried over unchanged, not
+ * a new judgment call made here.
+ */
+declare function deriveCarriesCircuitState(topology: ServerTopology | undefined): boolean;
+interface EventTransportRegisterResult {
+    success: boolean;
+    /** See `deriveCarriesCircuitState`. Computed once here, not re-derived by callers. */
+    carriesCircuitState: boolean;
+}
+/**
+ * Who a server push was addressed to: `peers` — another client's change
+ * (live push); `origin` — this client's own running request, live (a
+ * call-service's `emit.onMessage`).
+ */
+type PushTarget = 'peers' | 'origin';
+interface EventTransport {
+    /** Register a schema with the transport's target (server, or an in-process evaluator). */
+    register(schema: OrbitalSchema): Promise<EventTransportRegisterResult>;
+    unregister(): Promise<void>;
+    /** Play one event through the orbital named `orbitalName`. */
+    send(orbitalName: string, request: OrbitalEventRequest): Promise<OrbitalEventResponse>;
+    /**
+     * A row-set reference resolved by the host that holds the rows, for the viewer the transport is signed in as (the
+     * host applies `@read`): the rows that still match, in the reference's order. Absent when the transport has no
+     * such route (an in-process evaluator resolves against its own store).
+     */
+    resolveRows?(reference: RowSetRef): Promise<RowQueryPage>;
+    /**
+     * Subscribe to server-pushed cascade events (e.g. another client's
+     * persist-envelope emits, Almadar_Live_Push.md). Absent when the
+     * transport has no server to push from (in-process). `params` augments
+     * the push channel's query string (e.g. a caller-supplied per-tab
+     * `clientId` for the server's origin-exclusion) — the transport itself
+     * carries no notion of "tab identity", that is a client-role concern
+     * (plan P4).
+     */
+    subscribe?(onPush: (emitted: EmittedEvent, target: PushTarget) => void, params?: Record<string, string>): () => void;
+    /**
+     * The host runs the whole program, browser-stored entities included (an extension's worker): a
+     * view of it keeps no browser store of its own and sends every leg to the host.
+     */
+    readonly hostsBrowserStore?: boolean;
+    /**
+     * Hear the results of dispatches the host ran without any view asking (a declared input, a
+     * follow-on call's outcome), so an open view shows them. The view applies the result; it never
+     * runs the dispatch again. `params` addresses this view on a push channel, as for `subscribe`.
+     */
+    subscribeHostDispatches?(onDispatch: HostDispatchListener, params?: Record<string, string>): () => void;
+}
+/** A dispatch the host ran on its own, with its result. */
+type HostDispatchListener = (orbitalName: string, request: OrbitalEventRequest, response: OrbitalEventResponse) => void;
+/**
+ * Supplies the bearer token the hosting server authenticates with. Resolved
+ * per request (tokens expire); `undefined` sends the request unauthenticated
+ * (dev servers with an auth bypass, standalone playground). Moved verbatim
+ * from `@almadar/ui`'s `providers/ServerBridge.tsx`.
+ */
+type AccessTokenProvider = () => Promise<string | undefined>;
+interface HttpTransportOptions {
+    serverUrl: string;
+    getAccessToken?: AccessTokenProvider;
+    /** Custom fetch function (for testing or custom auth). */
+    fetch?: typeof fetch;
+    /**
+     * Gzip JSON request bodies of at least `COMPRESSED_BODY_MIN_BYTES` (`Content-Encoding: gzip`).
+     * Browsers never compress request bodies, so a registered schema otherwise goes up raw. Only
+     * for servers that inflate request bodies (Express's JSON parser does).
+     */
+    compressRequests?: boolean;
+}
+/** Bodies below this stay plain: compressing them costs more than it saves. */
+declare const COMPRESSED_BODY_MIN_BYTES: number;
+/** A JSON request body, gzipped (`encoding: 'gzip'`) when `compress` is set and it is large enough to be worth it. */
+declare function encodeJsonBody(value: object, compress: boolean): Promise<{
+    body: string | Uint8Array<ArrayBuffer>;
+    encoding?: 'gzip';
+}>;
+/** HTTP transport — POSTs to a server speaking the canonical playground-runtime contract. */
+declare function createHttpTransport(options: HttpTransportOptions): EventTransport;
+/** Evaluates one event against an orbital with no wire in between — the unified `evaluateOrbitalEvent` (a separate, in-progress unit) is a valid `OrbitalEvaluator`. */
+type OrbitalEvaluator = (orbitalName: string, request: OrbitalEventRequest) => Promise<OrbitalEventResponse>;
+interface InProcessTransportOptions {
+    onRegister?: (schema: OrbitalSchema) => Promise<void> | void;
+    onUnregister?: () => Promise<void> | void;
+    /**
+     * In-process evaluation never crosses a wire, so nothing about circuit
+     * state is "carried" in the stateless-topology sense — `false` by
+     * default, mirroring `@almadar/ui`'s `BrowserPlayground` today: its
+     * in-process `register` never declares a `topology`, and the provider's
+     * fallback for a custom transport is `'in-process'` (not
+     * `'stateless-http'`).
+     */
+    carriesCircuitState?: boolean;
+    /** Resolves a row-set reference on the in-process kernel (`KernelEngine.resolveRows`), `@read` applied there. */
+    resolveRows?: (reference: RowSetRef) => Promise<RowQueryPage>;
+}
+/** In-process transport — the evaluator is INJECTED (e.g. the unified `evaluateOrbitalEvent`, owned elsewhere). */
+declare function createInProcessTransport(evaluate: OrbitalEvaluator, options?: InProcessTransportOptions): EventTransport;
+
+export { COMPRESSED_BODY_MIN_BYTES, createHttpTransport, createInProcessTransport, deriveCarriesCircuitState, encodeJsonBody };
+export type { AccessTokenProvider, EventTransport, EventTransportRegisterResult, HostDispatchListener, HttpTransportOptions, InProcessTransportOptions, OrbitalEvaluator, PushTarget };

package/dist/client/EventTransport.js

@@ -0,0 +1,2 @@
+export { COMPRESSED_BODY_MIN_BYTES, createHttpTransport, createInProcessTransport, deriveCarriesCircuitState, encodeJsonBody } from '../chunk-QELZ6TEJ.js';
+import '../chunk-MLKGABMK.js';

package/dist/client/ServerBridge.d.ts

@@ -0,0 +1,126 @@
+import { IEventBus } from '../runtime/types.js';
+import { EventPayload, EmittedEvent } from '@almadar/core';
+import '../service/default-call-service.js';
+import '../service/service-provider.js';
+import '../kernel/program-effects.js';
+import '../runtime/effects/composition/compose-behaviors.js';
+import '../runtime/effects/composition/event-wiring.js';
+import '../runtime/effects/composition/layout-strategy.js';
+import '../runtime/effects/composition/pipe.js';
+
+/**
+ * ServerBridge - Client-Server Trait Communication
+ *
+ * Bridges the client EventBus with the server OrbitalRuntime:
+ * 1. Forwards specified events from client to server
+ * 2. Receives events from server (via polling or WebSocket)
+ * 3. Puts server events onto client EventBus
+ *
+ * This enables cross-orbital communication between client and server traits.
+ *
+ * @example
+ * ```typescript
+ * import { ServerBridge } from '@kflow-builder/shared/runtime';
+ * import { useEventBus } from './hooks/useEventBus';
+ *
+ * // In your app initialization
+ * const eventBus = useEventBus();
+ * const bridge = new ServerBridge({
+ *   eventBus,
+ *   serverUrl: '/api/orbitals',
+ *   // Events to forward from client to server
+ *   forwardEvents: ['ORDER_PLACED', 'PAYMENT_COMPLETED'],
+ * });
+ *
+ * bridge.connect();
+ *
+ * // Now when client emits ORDER_PLACED, server traits receive it
+ * eventBus.emit('ORDER_PLACED', { orderId: '123' });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+interface ServerBridgeConfig {
+    /** Client EventBus to bridge */
+    eventBus: IEventBus;
+    /** Base URL for orbital server API */
+    serverUrl: string;
+    /** Events to forward from client to server */
+    forwardEvents?: string[];
+    /** Forward all events matching pattern (e.g., 'Order*', '*') */
+    forwardPattern?: string;
+    /** Target orbital for forwarded events (or 'broadcast' for all) */
+    targetOrbital?: string;
+    /** Enable WebSocket for real-time server events */
+    useWebSocket?: boolean;
+    /** Polling interval in ms (if not using WebSocket) */
+    pollInterval?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Custom fetch function (for testing or custom auth) */
+    fetch?: typeof fetch;
+}
+interface ServerBridgeState {
+    connected: boolean;
+    lastError?: string;
+    eventsForwarded: number;
+    eventsReceived: number;
+}
+/**
+ * Bridges client EventBus with server OrbitalRuntime
+ */
+declare class ServerBridge {
+    private config;
+    private state;
+    private unsubscribes;
+    private pollTimer?;
+    private ws?;
+    private fetchFn;
+    /** The one HTTP request/response leg — shared with `@almadar/ui`'s transport (P5, EventTransport.ts). */
+    private transport;
+    constructor(config: ServerBridgeConfig);
+    /**
+     * Connect the bridge - start forwarding events
+     */
+    connect(): void;
+    /**
+     * Disconnect the bridge
+     */
+    disconnect(): void;
+    /**
+     * Get current bridge state
+     */
+    getState(): ServerBridgeState;
+    private setupEventForwarding;
+    private forwardToServer;
+    private sendEventToOrbital;
+    private fetchOrbitals;
+    private setupPolling;
+    private setupWebSocket;
+    /**
+     * Send an event directly to a specific orbital (bypassing EventBus)
+     */
+    sendEvent(orbitalName: string, event: string, payload?: EventPayload): Promise<{
+        success: boolean;
+        states?: Record<string, string>;
+        emittedEvents?: EmittedEvent[];
+        error?: string;
+    }>;
+    /**
+     * Get current state of an orbital's traits
+     */
+    getOrbitalState(orbitalName: string): Promise<{
+        success: boolean;
+        states?: Record<string, string>;
+        error?: string;
+    }>;
+    private log;
+}
+/**
+ * Create a ServerBridge instance
+ */
+declare function createServerBridge(config: ServerBridgeConfig): ServerBridge;
+
+export { ServerBridge, createServerBridge };
+export type { ServerBridgeConfig, ServerBridgeState };

package/dist/client/ServerBridge.js

@@ -0,0 +1,3 @@
+export { ServerBridge, createServerBridge } from '../chunk-D5USD2EX.js';
+import '../chunk-QELZ6TEJ.js';
+import '../chunk-MLKGABMK.js';

package/dist/client/awaiting.d.ts

@@ -0,0 +1,28 @@
+import { AwaitingTrait } from '@almadar/core';
+
+/**
+ * Which traits are awaiting a server round trip right now — the kernel contract
+ * behind awaiting-server skeletons (`AwaitingTrait`, `@almadar/core`). The
+ * client kernel begins an entry right before a server leg's send and ends it
+ * when the leg folds or fails; local/hybrid traits and tick legs never enter.
+ * Subscriptions are per trait, so only the slots that trait owns re-render.
+ */
+
+declare class AwaitingRegistry {
+    private readonly entries;
+    private readonly listeners;
+    private readonly anyListeners;
+    private version;
+    begin(list: readonly AwaitingTrait[]): void;
+    end(traits: readonly string[]): void;
+    get(trait: string): AwaitingTrait | undefined;
+    list(): AwaitingTrait[];
+    subscribe(trait: string, listener: () => void): () => void;
+    /** Any trait's awaiting change (an empty slot does not know which trait will fill it). */
+    subscribeAll(listener: () => void): () => void;
+    /** Bumped on every change — a stable snapshot key for `useSyncExternalStore`. */
+    getVersion(): number;
+    private emit;
+}
+
+export { AwaitingRegistry };

package/dist/client/awaiting.js

@@ -0,0 +1,2 @@
+export { AwaitingRegistry } from '../chunk-HC6ERSAH.js';
+import '../chunk-MLKGABMK.js';

package/dist/client/channel-transport.d.ts

@@ -0,0 +1,69 @@
+import { OrbitalEventRequest, OrbitalEventResponse, EmittedEvent } from '@almadar/core';
+import { PushTarget, EventTransport } from './EventTransport.js';
+
+/**
+ * An EventTransport over a message channel, for a program hosted in another browser context (an
+ * extension's service worker, a web worker, an iframe). The view half plays events and receives
+ * pushes; the host half serves any EventTransport on the channel and pushes to its views. The
+ * channel is two functions, so any postMessage-style port fits behind it.
+ */
+
+type ChannelMessage = {
+    almadarChannel: 'register';
+    id: number;
+    schemaName: string;
+} | {
+    almadarChannel: 'registered';
+    id: number;
+    held: boolean;
+} | {
+    almadarChannel: 'send';
+    id: number;
+    orbitalName: string;
+    request: OrbitalEventRequest;
+} | {
+    almadarChannel: 'reply';
+    id: number;
+    response: OrbitalEventResponse;
+} | {
+    almadarChannel: 'push';
+    emitted: EmittedEvent;
+    target: PushTarget;
+} | {
+    almadarChannel: 'dispatched';
+    orbitalName: string;
+    request: OrbitalEventRequest;
+    response: OrbitalEventResponse;
+};
+interface TransportChannel {
+    post(message: ChannelMessage): void;
+    onMessage(listener: (message: ChannelMessage) => void): () => void;
+    /** The other end went away for good (a stopped extension worker's port); absent for channels that cannot close. */
+    onClose?(listener: () => void): () => void;
+}
+interface ChannelTransportOptions {
+    /** The host on the other end keeps the program's browser-stored entities (see `EventTransport.hostsBrowserStore`). */
+    hostsBrowserStore?: boolean;
+}
+/** The view half: an EventTransport whose program lives on the other end of the channel. */
+declare function createChannelTransport(channel: TransportChannel, options?: ChannelTransportOptions): EventTransport;
+interface ServedChannel {
+    /** Push a host-side event to the view (e.g. one a declared input caused while no view was asking). */
+    push(emitted: EmittedEvent, target: PushTarget): void;
+    /** Send the view the result of a dispatch the host ran on its own. */
+    pushDispatch(orbitalName: string, request: OrbitalEventRequest, response: OrbitalEventResponse): void;
+    stop(): void;
+}
+/** The host half: serve `transport` on `channel` for the program named `schemaName`. */
+declare function serveChannel(channel: TransportChannel, transport: EventTransport, options: {
+    schemaName: string;
+}): ServedChannel;
+/**
+ * A channel that listens from the moment it is wrapped and keeps what arrives until something
+ * subscribes, then hands it over in order: a host that is still starting (an extension worker
+ * waking up) serves the channel late without losing the view's first messages.
+ */
+declare function holdUntilServed(channel: TransportChannel): TransportChannel;
+
+export { createChannelTransport, holdUntilServed, serveChannel };
+export type { ChannelMessage, ChannelTransportOptions, ServedChannel, TransportChannel };

package/dist/client/channel-transport.js

@@ -0,0 +1,2 @@
+export { createChannelTransport, holdUntilServed, serveChannel } from '../chunk-SKLMWHQD.js';
+import '../chunk-MLKGABMK.js';