@mulmobridge/protocol 0.1.2 → 0.1.4

package/dist/events.d.ts

@@ -10,5 +10,56 @@ export declare const EVENT_TYPES: {
     readonly sessionFinished: "session_finished";
     readonly sessionMeta: "session_meta";
     readonly rolesUpdated: "roles_updated";
+    readonly generationStarted: "generation_started";
+    readonly generationFinished: "generation_finished";
 };
 export type EventType = (typeof EVENT_TYPES)[keyof typeof EVENT_TYPES];
+/**
+ * Long-running async work originated by a plugin (MulmoScript etc.)
+ * that continues past the initial HTTP response. The server publishes
+ * a `generationStarted` event when the work begins and a
+ * `generationFinished` event when it completes (or fails). Clients
+ * track the in-flight set in `Session.pendingGenerations` so the UI
+ * can keep a "busy" indicator lit across view navigation.
+ */
+export declare const GENERATION_KINDS: {
+    readonly beatImage: "beatImage";
+    readonly characterImage: "characterImage";
+    readonly beatAudio: "beatAudio";
+    readonly movie: "movie";
+};
+export type GenerationKind = (typeof GENERATION_KINDS)[keyof typeof GENERATION_KINDS];
+export interface GenerationEvent {
+    type: "generation_started" | "generation_finished";
+    kind: GenerationKind;
+    /** MulmoScript file path — identifies the script the generation belongs to. */
+    filePath: string;
+    /** beatIndex (as string) for beat*, character key for characterImage, "" for movie. */
+    key: string;
+    /** Only set on generation_finished when the work failed. */
+    error?: string;
+}
+/**
+ * Decomposed view of a pending generation, stored as the *value* of
+ * `pendingGenerations[mapKey]`. Consumers read these fields directly
+ * rather than splitting the composite map key — filePath and user-
+ * defined character keys can contain arbitrary characters, so
+ * positional string parsing is unsafe.
+ */
+export interface PendingGeneration {
+    kind: GenerationKind;
+    filePath: string;
+    key: string;
+}
+/**
+ * Stable map-key for a generation: the triple (kind, filePath, key).
+ * Separator is U+001F (UNIT SEPARATOR), a non-printable ASCII control
+ * character that cannot appear in filePaths or user-entered keys —
+ * this guarantees `generationKey(a) === generationKey(b)` iff a≡b,
+ * unlike a human-visible delimiter that could collide.
+ *
+ * The returned string is used only as a map identity. Do NOT split it
+ * to recover the fields — store the decomposed `PendingGeneration`
+ * object as the map value instead.
+ */
+export declare function generationKey(kind: GenerationKind, filePath: string, key: string): string;

package/dist/events.js

@@ -15,4 +15,34 @@ export const EVENT_TYPES = {
     sessionFinished: "session_finished",
     sessionMeta: "session_meta",
     rolesUpdated: "roles_updated",
+    generationStarted: "generation_started",
+    generationFinished: "generation_finished",
 };
+/**
+ * Long-running async work originated by a plugin (MulmoScript etc.)
+ * that continues past the initial HTTP response. The server publishes
+ * a `generationStarted` event when the work begins and a
+ * `generationFinished` event when it completes (or fails). Clients
+ * track the in-flight set in `Session.pendingGenerations` so the UI
+ * can keep a "busy" indicator lit across view navigation.
+ */
+export const GENERATION_KINDS = {
+    beatImage: "beatImage",
+    characterImage: "characterImage",
+    beatAudio: "beatAudio",
+    movie: "movie",
+};
+/**
+ * Stable map-key for a generation: the triple (kind, filePath, key).
+ * Separator is U+001F (UNIT SEPARATOR), a non-printable ASCII control
+ * character that cannot appear in filePaths or user-entered keys —
+ * this guarantees `generationKey(a) === generationKey(b)` iff a≡b,
+ * unlike a human-visible delimiter that could collide.
+ *
+ * The returned string is used only as a map identity. Do NOT split it
+ * to recover the fields — store the decomposed `PendingGeneration`
+ * object as the map value instead.
+ */
+export function generationKey(kind, filePath, key) {
+    return `${kind}\u001f${filePath}\u001f${key}`;
+}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { EVENT_TYPES, type EventType } from "./events.js";
-export { CHAT_SOCKET_PATH, CHAT_SOCKET_EVENTS, type ChatSocketEvent, } from "./socket.js";
+export { EVENT_TYPES, type EventType, GENERATION_KINDS, type GenerationKind, type GenerationEvent, type PendingGeneration, generationKey } from "./events.js";
+export { CHAT_SOCKET_PATH, CHAT_SOCKET_EVENTS, type ChatSocketEvent, type BridgeHandshakeAuth, type BridgeOptions } from "./socket.js";
 export { type Attachment } from "./attachment.js";
 export { CHAT_SERVICE_ROUTES } from "./routes.js";

package/dist/index.js

@@ -6,6 +6,6 @@
 //   - External bridges (CLI, Telegram, future platforms)
 //
 // No runtime dependencies. Types + const-only.
-export { EVENT_TYPES } from "./events.js";
-export { CHAT_SOCKET_PATH, CHAT_SOCKET_EVENTS, } from "./socket.js";
+export { EVENT_TYPES, GENERATION_KINDS, generationKey } from "./events.js";
+export { CHAT_SOCKET_PATH, CHAT_SOCKET_EVENTS } from "./socket.js";
 export { CHAT_SERVICE_ROUTES } from "./routes.js";

package/dist/socket.d.ts

@@ -9,3 +9,30 @@ export declare const CHAT_SOCKET_EVENTS: {
     readonly textChunk: "textChunk";
 };
 export type ChatSocketEvent = (typeof CHAT_SOCKET_EVENTS)[keyof typeof CHAT_SOCKET_EVENTS];
+/**
+ * Bridge → host-app option bag carried on the handshake.
+ *
+ * Values are restricted to flat primitives (string / number /
+ * boolean). The restriction serves two purposes:
+ *
+ *   1. The wire contract is explicit — no surprise nested objects
+ *      slip through to the host app's callback where a downstream
+ *      merge might reintroduce prototype-pollution risk.
+ *   2. The scrape-from-env path produces strings anyway, so the
+ *      ceiling is already flat primitives in practice.
+ *
+ * Protocol does not interpret any keys — bridges and host apps agree
+ * on names (`defaultRole`, …) out of band.
+ */
+export type BridgeOptions = Readonly<Record<string, string | number | boolean>>;
+/**
+ * Shape of `socket.handshake.auth` on the bridge chat socket. The
+ * server validates `transportId` + `token`; `options` is the opaque-
+ * but-primitive bag forwarded to the host application's startChat
+ * callback. See `plans/feat-bridge-options-passthrough.md`.
+ */
+export interface BridgeHandshakeAuth {
+    transportId: string;
+    token?: string;
+    options?: BridgeOptions;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmobridge/protocol",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Shared types and constants for the MulmoBridge protocol",
   "type": "module",
   "main": "./dist/index.js",