@agimon-ai/doompi-web-contracts 0.0.1-alpha.2

package/dist/services/testing/slotProps.d.mts

@@ -0,0 +1,57 @@
+import { SlotDataFill, ToolMessageRenderProps, ToolResultView, WebPluginSlotProps } from "../../types/webPlugin.mjs";
+import { ReactNode } from "react";
+//#region src/services/testing/slotProps.d.ts
+/**
+ * The props the cockpit hands a plugin's components, built for a test.
+ *
+ * A plugin component takes fifteen props and reads three of them. Written out
+ * by hand in each test, the other twelve are noise that goes stale the moment
+ * the contract grows a member; written as a cast, the component compiles
+ * against props the host never sends. This builds all of them, records what the
+ * component did with the actions, and lets a test override the two or three it
+ * cares about.
+ */
+interface RecordedSlotAction {
+  action: 'openTab' | 'openTransientTab' | 'closeTransientTab' | 'sendSessionFrame';
+  /** The tab id, the transient tab's id, or the target session of a frame. */
+  target: string | null;
+  /** The frame a component sent, for `sendSessionFrame`. */
+  frame?: Record<string, unknown>;
+}
+interface SlotPropsFixture {
+  props: WebPluginSlotProps;
+  /** Everything the component did through its props, in order. */
+  readonly actions: readonly RecordedSlotAction[];
+  /** Frames the component sent, which is what most assertions want. */
+  frames(): readonly Record<string, unknown>[];
+}
+interface SlotPropsOptions {
+  sessionId?: string | null;
+  statuses?: Readonly<Record<string, string>>;
+  /** Component fills this slot owner should see; keyed by slot name. */
+  slotContent?: Readonly<Record<string, ReactNode>>;
+  /** Data fills this slot owner should read back, keyed by slot name. */
+  slotData?: Readonly<Record<string, readonly SlotDataFill[]>>;
+  /** What `renderThread` returns for a plugin that renders one. */
+  thread?: (threadId: string) => ReactNode;
+}
+declare function slotPropsFixture(options?: SlotPropsOptions): SlotPropsFixture;
+interface ToolMessagePropsOptions extends SlotPropsOptions {
+  toolCallId?: string;
+  toolName: string;
+  args?: Record<string, unknown>;
+  /** The newest result; null is what the host sends before any output. */
+  result?: ToolResultView | null;
+  /** The result's text blocks joined, as the host's own fallback item shows them. */
+  output?: string;
+  running?: boolean;
+  isError?: boolean;
+}
+interface ToolMessagePropsFixture extends Omit<SlotPropsFixture, 'props'> {
+  props: ToolMessageRenderProps;
+}
+/** The props a tool's timeline item receives, in any of its four states. */
+declare function toolMessagePropsFixture(options: ToolMessagePropsOptions): ToolMessagePropsFixture;
+//#endregion
+export { RecordedSlotAction, SlotPropsFixture, SlotPropsOptions, ToolMessagePropsFixture, ToolMessagePropsOptions, slotPropsFixture, toolMessagePropsFixture };
+//# sourceMappingURL=slotProps.d.mts.map

package/dist/services/testing/slotProps.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slotProps.d.mts","names":[],"sources":["../../../src/services/testing/slotProps.ts"],"mappings":";;;;;;;;;;;;;UAqBiB;EACf;;EAEA;;EAEA,QAAQ;;UAGO;EACf,OAAO;;WAEE,kBAAkB;;EAE3B,mBAAmB;;UAGJ;EACf;EACA,WAAW,SAAS;;EAEpB,cAAc,SAAS,eAAe;;EAEtC,WAAW,SAAS,wBAAwB;;EAE5C,UAAU,qBAAqB;;iBAKjB,iBAAiB,UAAS,mBAAwB;UAgCjD,gCAAgC;EAC/C;EACA;EACA,OAAO;;EAEP,SAAS;;EAET;EACA;EACA;;UAGe,gCAAgC,KAAK;EACpD,OAAO;;;iBAMO,wBAAwB,SAAS,0BAA0B"}

package/dist/services/testing/slotProps.mjs

@@ -0,0 +1,2 @@
+function e(e={}){let t=[];return{props:{sessionId:e.sessionId===void 0?`s1`:e.sessionId,statuses:e.statuses??{},openTab:e=>{t.push({action:`openTab`,target:e})},openTransientTab:e=>{t.push({action:`openTransientTab`,target:e.id})},closeTransientTab:e=>{t.push({action:`closeTransientTab`,target:e})},sendSessionFrame:(e,n)=>{t.push({action:`sendSessionFrame`,target:e,frame:n})},renderThread:t=>e.thread?.(t)??null,renderSlot:t=>e.slotContent?.[t]??null,slotData:t=>e.slotData?.[t.slot]??[]},actions:t,frames:()=>t.flatMap(e=>e.frame?[e.frame]:[])}}function t(t){let n=e(t),r=t.result===void 0?null:t.result;return{...n,props:{...n.props,toolCallId:t.toolCallId??`call-1`,toolName:t.toolName,args:t.args??{},result:r,output:t.output??``,running:t.running??!1,isError:t.isError??!1}}}export{e as slotPropsFixture,t as toolMessagePropsFixture};
+//# sourceMappingURL=slotProps.mjs.map

package/dist/services/testing/slotProps.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"slotProps.mjs","names":[],"sources":["../../../src/services/testing/slotProps.ts"],"sourcesContent":["import type { ReactNode } from 'react';\nimport type {\n  SlotDataFill,\n  SlotDeclaration,\n  ToolMessageRenderProps,\n  ToolResultView,\n  TransientTab,\n  WebPluginSlotProps,\n} from '../../types/webPlugin.ts';\n\n/**\n * The props the cockpit hands a plugin's components, built for a test.\n *\n * A plugin component takes fifteen props and reads three of them. Written out\n * by hand in each test, the other twelve are noise that goes stale the moment\n * the contract grows a member; written as a cast, the component compiles\n * against props the host never sends. This builds all of them, records what the\n * component did with the actions, and lets a test override the two or three it\n * cares about.\n */\n\nexport interface RecordedSlotAction {\n  action: 'openTab' | 'openTransientTab' | 'closeTransientTab' | 'sendSessionFrame';\n  /** The tab id, the transient tab's id, or the target session of a frame. */\n  target: string | null;\n  /** The frame a component sent, for `sendSessionFrame`. */\n  frame?: Record<string, unknown>;\n}\n\nexport interface SlotPropsFixture {\n  props: WebPluginSlotProps;\n  /** Everything the component did through its props, in order. */\n  readonly actions: readonly RecordedSlotAction[];\n  /** Frames the component sent, which is what most assertions want. */\n  frames(): readonly Record<string, unknown>[];\n}\n\nexport interface SlotPropsOptions {\n  sessionId?: string | null;\n  statuses?: Readonly<Record<string, string>>;\n  /** Component fills this slot owner should see; keyed by slot name. */\n  slotContent?: Readonly<Record<string, ReactNode>>;\n  /** Data fills this slot owner should read back, keyed by slot name. */\n  slotData?: Readonly<Record<string, readonly SlotDataFill[]>>;\n  /** What `renderThread` returns for a plugin that renders one. */\n  thread?: (threadId: string) => ReactNode;\n}\n\nconst DEFAULT_SESSION_ID = 's1';\n\nexport function slotPropsFixture(options: SlotPropsOptions = {}): SlotPropsFixture {\n  const actions: RecordedSlotAction[] = [];\n  const props: WebPluginSlotProps = {\n    sessionId: options.sessionId === undefined ? DEFAULT_SESSION_ID : options.sessionId,\n    statuses: options.statuses ?? {},\n    openTab: (tabId) => {\n      actions.push({ action: 'openTab', target: tabId });\n    },\n    openTransientTab: (tab: TransientTab) => {\n      actions.push({ action: 'openTransientTab', target: tab.id });\n    },\n    closeTransientTab: (tabId: string) => {\n      actions.push({ action: 'closeTransientTab', target: tabId });\n    },\n    sendSessionFrame: (sessionId, frame) => {\n      actions.push({ action: 'sendSessionFrame', target: sessionId, frame });\n    },\n    renderThread: (threadId) => options.thread?.(threadId) ?? null,\n    renderSlot: (slot) => options.slotContent?.[slot] ?? null,\n    // The host resolves fills by slot name and hands the owner its own typed\n    // view, so a test declares them by name too.\n    slotData: <Data>(slot: SlotDeclaration<Data>) =>\n      (options.slotData?.[slot.slot] ?? []) as readonly SlotDataFill<Data>[],\n  };\n\n  return {\n    props,\n    actions,\n    frames: () => actions.flatMap((entry) => (entry.frame ? [entry.frame] : [])),\n  };\n}\n\nexport interface ToolMessagePropsOptions extends SlotPropsOptions {\n  toolCallId?: string;\n  toolName: string;\n  args?: Record<string, unknown>;\n  /** The newest result; null is what the host sends before any output. */\n  result?: ToolResultView | null;\n  /** The result's text blocks joined, as the host's own fallback item shows them. */\n  output?: string;\n  running?: boolean;\n  isError?: boolean;\n}\n\nexport interface ToolMessagePropsFixture extends Omit<SlotPropsFixture, 'props'> {\n  props: ToolMessageRenderProps;\n}\n\nconst DEFAULT_TOOL_CALL_ID = 'call-1';\n\n/** The props a tool's timeline item receives, in any of its four states. */\nexport function toolMessagePropsFixture(options: ToolMessagePropsOptions): ToolMessagePropsFixture {\n  const base = slotPropsFixture(options);\n  const result = options.result === undefined ? null : options.result;\n  return {\n    ...base,\n    props: {\n      ...base.props,\n      toolCallId: options.toolCallId ?? DEFAULT_TOOL_CALL_ID,\n      toolName: options.toolName,\n      args: options.args ?? {},\n      result,\n      output: options.output ?? '',\n      running: options.running ?? false,\n      isError: options.isError ?? false,\n    },\n  };\n}\n"],"mappings":"AAkDA,SAAgB,EAAiB,EAA4B,CAAC,EAAqB,CACjF,IAAM,EAAgC,CAAC,EAwBvC,MAAO,CACL,MAAA,CAvBA,UAAW,EAAQ,YAAc,IAAA,GAAY,KAAqB,EAAQ,UAC1E,SAAU,EAAQ,UAAY,CAAC,EAC/B,QAAU,GAAU,CAClB,EAAQ,KAAK,CAAE,OAAQ,UAAW,OAAQ,CAAM,CAAC,CACnD,EACA,iBAAmB,GAAsB,CACvC,EAAQ,KAAK,CAAE,OAAQ,mBAAoB,OAAQ,EAAI,EAAG,CAAC,CAC7D,EACA,kBAAoB,GAAkB,CACpC,EAAQ,KAAK,CAAE,OAAQ,oBAAqB,OAAQ,CAAM,CAAC,CAC7D,EACA,kBAAmB,EAAW,IAAU,CACtC,EAAQ,KAAK,CAAE,OAAQ,mBAAoB,OAAQ,EAAW,OAAM,CAAC,CACvE,EACA,aAAe,GAAa,EAAQ,SAAS,CAAQ,GAAK,KAC1D,WAAa,GAAS,EAAQ,cAAc,IAAS,KAGrD,SAAiB,GACd,EAAQ,WAAW,EAAK,OAAS,CAAC,CAIjC,EACJ,UACA,WAAc,EAAQ,QAAS,GAAW,EAAM,MAAQ,CAAC,EAAM,KAAK,EAAI,CAAC,CAAE,CAC7E,CACF,CAqBA,SAAgB,EAAwB,EAA2D,CACjG,IAAM,EAAO,EAAiB,CAAO,EAC/B,EAAS,EAAQ,SAAW,IAAA,GAAY,KAAO,EAAQ,OAC7D,MAAO,CACL,GAAG,EACH,MAAO,CACL,GAAG,EAAK,MACR,WAAY,EAAQ,YAAc,SAClC,SAAU,EAAQ,SAClB,KAAM,EAAQ,MAAQ,CAAC,EACvB,SACA,OAAQ,EAAQ,QAAU,GAC1B,QAAS,EAAQ,SAAW,GAC5B,QAAS,EAAQ,SAAW,EAC9B,CACF,CACF"}

package/dist/services/toolResult.cjs

@@ -0,0 +1,7 @@
+function e(e){return typeof e==`object`&&!!e&&e.type===`text`&&typeof e.text==`string`}function t(t){return t.filter(e).map(e=>e.text).join(`
+`)}function n(e){let n=t(e);if(n.length===0)return[];let r=n.replaceAll(`\r
+`,`
+`).replaceAll(`\r`,`
+`).replaceAll(`	`,`  `).split(`
+`);for(;r.length>0&&r.at(-1)?.trim()===``;)r.pop();return r}exports.toolResultText=t,exports.toolResultTextLines=n;
+//# sourceMappingURL=toolResult.cjs.map

package/dist/services/toolResult.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolResult.cjs","names":[],"sources":["../../src/services/toolResult.ts"],"sourcesContent":["/**\n * The text of a tool result, the way every tool card reads it: the `text`\n * content blocks joined with newlines, non-text blocks (images) dropped.\n */\n\nconst TAB = '\\t';\nconst TAB_WIDTH = '  ';\n\nfunction isTextBlock(block: unknown): block is { type: 'text'; text: string } {\n  return (\n    typeof block === 'object' &&\n    block !== null &&\n    (block as { type?: unknown }).type === 'text' &&\n    typeof (block as { text?: unknown }).text === 'string'\n  );\n}\n\n/** The text blocks of a result's content, joined with newlines. */\nexport function toolResultText(content: readonly unknown[]): string {\n  return content\n    .filter(isTextBlock)\n    .map((block) => block.text)\n    .join('\\n');\n}\n\n/**\n * toolResultText as lines a card can count and clip: tabs widened, CRLF\n * folded, trailing blank lines dropped, and no lines at all for no text.\n */\nexport function toolResultTextLines(content: readonly unknown[]): string[] {\n  const text = toolResultText(content);\n  if (text.length === 0) return [];\n  const lines = text.replaceAll('\\r\\n', '\\n').replaceAll('\\r', '\\n').replaceAll(TAB, TAB_WIDTH).split('\\n');\n  while (lines.length > 0 && lines.at(-1)?.trim() === '') lines.pop();\n  return lines;\n}\n"],"mappings":"AAQA,SAAS,EAAY,EAAyD,CAC5E,OACE,OAAO,GAAU,YACjB,GACC,EAA6B,OAAS,QACvC,OAAQ,EAA6B,MAAS,QAElD,CAGA,SAAgB,EAAe,EAAqC,CAClE,OAAO,EACJ,OAAO,CAAW,CAAC,CACnB,IAAK,GAAU,EAAM,IAAI,CAAC,CAC1B,KAAK;CAAI,CACd,CAMA,SAAgB,EAAoB,EAAuC,CACzE,IAAM,EAAO,EAAe,CAAO,EACnC,GAAI,EAAK,SAAW,EAAG,MAAO,CAAC,EAC/B,IAAM,EAAQ,EAAK,WAAW;EAAQ;CAAI,CAAC,CAAC,WAAW,KAAM;CAAI,CAAC,CAAC,WAAW,IAAK,IAAS,CAAC,CAAC,MAAM;CAAI,EACxG,KAAO,EAAM,OAAS,GAAK,EAAM,GAAG,EAAE,CAAC,EAAE,KAAK,IAAM,IAAI,EAAM,IAAI,EAClE,OAAO,CACT"}

package/dist/services/toolResult.d.cts

@@ -0,0 +1,15 @@
+//#region src/services/toolResult.d.ts
+/**
+ * The text of a tool result, the way every tool card reads it: the `text`
+ * content blocks joined with newlines, non-text blocks (images) dropped.
+ */
+/** The text blocks of a result's content, joined with newlines. */
+declare function toolResultText(content: readonly unknown[]): string;
+/**
+ * toolResultText as lines a card can count and clip: tabs widened, CRLF
+ * folded, trailing blank lines dropped, and no lines at all for no text.
+ */
+declare function toolResultTextLines(content: readonly unknown[]): string[];
+//#endregion
+export { toolResultText, toolResultTextLines };
+//# sourceMappingURL=toolResult.d.cts.map

package/dist/services/toolResult.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolResult.d.cts","names":[],"sources":["../../src/services/toolResult.ts"],"mappings":";;;;;;iBAkBgB,eAAe;;;;;iBAWf,oBAAoB"}

package/dist/services/toolResult.d.mts

@@ -0,0 +1,15 @@
+//#region src/services/toolResult.d.ts
+/**
+ * The text of a tool result, the way every tool card reads it: the `text`
+ * content blocks joined with newlines, non-text blocks (images) dropped.
+ */
+/** The text blocks of a result's content, joined with newlines. */
+declare function toolResultText(content: readonly unknown[]): string;
+/**
+ * toolResultText as lines a card can count and clip: tabs widened, CRLF
+ * folded, trailing blank lines dropped, and no lines at all for no text.
+ */
+declare function toolResultTextLines(content: readonly unknown[]): string[];
+//#endregion
+export { toolResultText, toolResultTextLines };
+//# sourceMappingURL=toolResult.d.mts.map

package/dist/services/toolResult.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolResult.d.mts","names":[],"sources":["../../src/services/toolResult.ts"],"mappings":";;;;;;iBAkBgB,eAAe;;;;;iBAWf,oBAAoB"}

package/dist/services/toolResult.mjs

@@ -0,0 +1,7 @@
+function e(e){return typeof e==`object`&&!!e&&e.type===`text`&&typeof e.text==`string`}function t(t){return t.filter(e).map(e=>e.text).join(`
+`)}function n(e){let n=t(e);if(n.length===0)return[];let r=n.replaceAll(`\r
+`,`
+`).replaceAll(`\r`,`
+`).replaceAll(`	`,`  `).split(`
+`);for(;r.length>0&&r.at(-1)?.trim()===``;)r.pop();return r}export{t as toolResultText,n as toolResultTextLines};
+//# sourceMappingURL=toolResult.mjs.map

package/dist/services/toolResult.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolResult.mjs","names":[],"sources":["../../src/services/toolResult.ts"],"sourcesContent":["/**\n * The text of a tool result, the way every tool card reads it: the `text`\n * content blocks joined with newlines, non-text blocks (images) dropped.\n */\n\nconst TAB = '\\t';\nconst TAB_WIDTH = '  ';\n\nfunction isTextBlock(block: unknown): block is { type: 'text'; text: string } {\n  return (\n    typeof block === 'object' &&\n    block !== null &&\n    (block as { type?: unknown }).type === 'text' &&\n    typeof (block as { text?: unknown }).text === 'string'\n  );\n}\n\n/** The text blocks of a result's content, joined with newlines. */\nexport function toolResultText(content: readonly unknown[]): string {\n  return content\n    .filter(isTextBlock)\n    .map((block) => block.text)\n    .join('\\n');\n}\n\n/**\n * toolResultText as lines a card can count and clip: tabs widened, CRLF\n * folded, trailing blank lines dropped, and no lines at all for no text.\n */\nexport function toolResultTextLines(content: readonly unknown[]): string[] {\n  const text = toolResultText(content);\n  if (text.length === 0) return [];\n  const lines = text.replaceAll('\\r\\n', '\\n').replaceAll('\\r', '\\n').replaceAll(TAB, TAB_WIDTH).split('\\n');\n  while (lines.length > 0 && lines.at(-1)?.trim() === '') lines.pop();\n  return lines;\n}\n"],"mappings":"AAQA,SAAS,EAAY,EAAyD,CAC5E,OACE,OAAO,GAAU,YACjB,GACC,EAA6B,OAAS,QACvC,OAAQ,EAA6B,MAAS,QAElD,CAGA,SAAgB,EAAe,EAAqC,CAClE,OAAO,EACJ,OAAO,CAAW,CAAC,CACnB,IAAK,GAAU,EAAM,IAAI,CAAC,CAC1B,KAAK;CAAI,CACd,CAMA,SAAgB,EAAoB,EAAuC,CACzE,IAAM,EAAO,EAAe,CAAO,EACnC,GAAI,EAAK,SAAW,EAAG,MAAO,CAAC,EAC/B,IAAM,EAAQ,EAAK,WAAW;EAAQ;CAAI,CAAC,CAAC,WAAW,KAAM;CAAI,CAAC,CAAC,WAAW,IAAK,IAAS,CAAC,CAAC,MAAM;CAAI,EACxG,KAAO,EAAM,OAAS,GAAK,EAAM,GAAG,EAAE,CAAC,EAAE,KAAK,IAAM,IAAI,EAAM,IAAI,EAClE,OAAO,CACT"}

package/dist/testing.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./services/testing/channels.cjs"),t=require("./services/testing/render.cjs"),n=require("./services/testing/slotProps.cjs");exports.driveChannel=e.driveChannel,exports.hubChannelHarness=e.hubChannelHarness,exports.renderPlugin=t.renderPlugin,exports.slotPropsFixture=n.slotPropsFixture,exports.toolMessagePropsFixture=n.toolMessagePropsFixture;

package/dist/testing.d.cts

@@ -0,0 +1,4 @@
+import { ChannelDelivery, HubChannelHarness, HubChannelHarnessOptions, driveChannel, hubChannelHarness } from "./services/testing/channels.cjs";
+import { RenderedPlugin, renderPlugin } from "./services/testing/render.cjs";
+import { RecordedSlotAction, SlotPropsFixture, SlotPropsOptions, ToolMessagePropsFixture, ToolMessagePropsOptions, slotPropsFixture, toolMessagePropsFixture } from "./services/testing/slotProps.cjs";
+export { type ChannelDelivery, type HubChannelHarness, type HubChannelHarnessOptions, type RecordedSlotAction, type RenderedPlugin, type SlotPropsFixture, type SlotPropsOptions, type ToolMessagePropsFixture, type ToolMessagePropsOptions, driveChannel, hubChannelHarness, renderPlugin, slotPropsFixture, toolMessagePropsFixture };

package/dist/testing.d.mts

@@ -0,0 +1,4 @@
+import { ChannelDelivery, HubChannelHarness, HubChannelHarnessOptions, driveChannel, hubChannelHarness } from "./services/testing/channels.mjs";
+import { RenderedPlugin, renderPlugin } from "./services/testing/render.mjs";
+import { RecordedSlotAction, SlotPropsFixture, SlotPropsOptions, ToolMessagePropsFixture, ToolMessagePropsOptions, slotPropsFixture, toolMessagePropsFixture } from "./services/testing/slotProps.mjs";
+export { type ChannelDelivery, type HubChannelHarness, type HubChannelHarnessOptions, type RecordedSlotAction, type RenderedPlugin, type SlotPropsFixture, type SlotPropsOptions, type ToolMessagePropsFixture, type ToolMessagePropsOptions, driveChannel, hubChannelHarness, renderPlugin, slotPropsFixture, toolMessagePropsFixture };

package/dist/testing.mjs

@@ -0,0 +1 @@
+import{driveChannel as e,hubChannelHarness as t}from"./services/testing/channels.mjs";import{renderPlugin as n}from"./services/testing/render.mjs";import{slotPropsFixture as r,toolMessagePropsFixture as i}from"./services/testing/slotProps.mjs";export{e as driveChannel,t as hubChannelHarness,n as renderPlugin,r as slotPropsFixture,i as toolMessagePropsFixture};

package/dist/types/webHub.d.cts

@@ -0,0 +1,56 @@
+//#region src/types/webHub.d.ts
+/**
+ * The wire shape and the hub-server half of the DoomPi web plugin contract.
+ *
+ * A plugin package's hub entry exports `webHubChannels: readonly
+ * WebHubChannel[]`. The cockpit hub imports server contracts type-only, so
+ * this module must stay free of runtime values beyond plain types.
+ */
+/**
+ * Per-plugin session data on the page socket. The channel name IS the frame
+ * type; the page routes by registry lookup and drops unknown types.
+ */
+interface ChannelFrame {
+  type: string;
+  sessionId: string;
+  payload: unknown;
+}
+interface HubSessionScope {
+  sessionId: string;
+  /** The session's working directory, for repo-scoped data sources. */
+  cwd: string;
+}
+/** What the hub hands a channel when it starts. */
+interface HubChannelHost {
+  /** Every session the hub currently manages. */
+  sessions(): readonly HubSessionScope[];
+  /** Live fan-out to the session's page subscribers. */
+  publish(sessionId: string, payload: unknown): void;
+  onNotice(message: string): void;
+}
+/**
+ * One running data source. `payloadFor` answers the subscribe-time snapshot;
+ * undefined means no frame. The optional session hooks cover per-session
+ * sources; a hub-wide source may ignore them and filter inside itself.
+ */
+interface HubChannelSource {
+  /** unknown already admits undefined; a literal undefined result means no frame. */
+  payloadFor(scope: HubSessionScope): unknown;
+  sessionAdded?(scope: HubSessionScope): void;
+  sessionRemoved?(sessionId: string): void;
+  /**
+   * The Pi session journal (an absolute .jsonl path) behind one thread of a
+   * session, such as a subagent run; the hub tails it for the page. Undefined
+   * means not this source's thread, or not known yet: the hub keeps asking.
+   */
+  threadJournal?(scope: HubSessionScope, threadId: string): string | undefined;
+  close(): void;
+}
+interface WebHubChannel {
+  /** Wire frame type; globally unique across every loaded plugin. */
+  frameType: string;
+  start(host: HubChannelHost): HubChannelSource;
+}
+//#endregion
+export { ChannelFrame, HubChannelHost, HubChannelSource, HubSessionScope, WebHubChannel };
+//# sourceMappingURL=webHub.d.cts.map

package/dist/types/webHub.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webHub.d.cts","names":[],"sources":["../../src/types/webHub.ts"],"mappings":";;;;;;;;;;;;UAYiB;EACf;EACA;EACA;;UAGe;EACf;;EAEA;;;UAIe;;EAEf,qBAAqB;;EAErB,QAAQ,mBAAmB;EAC3B,SAAS;;;;;;;UAQM;;EAEf,WAAW,OAAO;EAClB,cAAc,OAAO;EACrB,gBAAgB;;;;;;EAMhB,eAAe,OAAO,iBAAiB;EACvC;;UAGe;;EAEf;EACA,MAAM,MAAM,iBAAiB"}

package/dist/types/webHub.d.mts

@@ -0,0 +1,56 @@
+//#region src/types/webHub.d.ts
+/**
+ * The wire shape and the hub-server half of the DoomPi web plugin contract.
+ *
+ * A plugin package's hub entry exports `webHubChannels: readonly
+ * WebHubChannel[]`. The cockpit hub imports server contracts type-only, so
+ * this module must stay free of runtime values beyond plain types.
+ */
+/**
+ * Per-plugin session data on the page socket. The channel name IS the frame
+ * type; the page routes by registry lookup and drops unknown types.
+ */
+interface ChannelFrame {
+  type: string;
+  sessionId: string;
+  payload: unknown;
+}
+interface HubSessionScope {
+  sessionId: string;
+  /** The session's working directory, for repo-scoped data sources. */
+  cwd: string;
+}
+/** What the hub hands a channel when it starts. */
+interface HubChannelHost {
+  /** Every session the hub currently manages. */
+  sessions(): readonly HubSessionScope[];
+  /** Live fan-out to the session's page subscribers. */
+  publish(sessionId: string, payload: unknown): void;
+  onNotice(message: string): void;
+}
+/**
+ * One running data source. `payloadFor` answers the subscribe-time snapshot;
+ * undefined means no frame. The optional session hooks cover per-session
+ * sources; a hub-wide source may ignore them and filter inside itself.
+ */
+interface HubChannelSource {
+  /** unknown already admits undefined; a literal undefined result means no frame. */
+  payloadFor(scope: HubSessionScope): unknown;
+  sessionAdded?(scope: HubSessionScope): void;
+  sessionRemoved?(sessionId: string): void;
+  /**
+   * The Pi session journal (an absolute .jsonl path) behind one thread of a
+   * session, such as a subagent run; the hub tails it for the page. Undefined
+   * means not this source's thread, or not known yet: the hub keeps asking.
+   */
+  threadJournal?(scope: HubSessionScope, threadId: string): string | undefined;
+  close(): void;
+}
+interface WebHubChannel {
+  /** Wire frame type; globally unique across every loaded plugin. */
+  frameType: string;
+  start(host: HubChannelHost): HubChannelSource;
+}
+//#endregion
+export { ChannelFrame, HubChannelHost, HubChannelSource, HubSessionScope, WebHubChannel };
+//# sourceMappingURL=webHub.d.mts.map

package/dist/types/webHub.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webHub.d.mts","names":[],"sources":["../../src/types/webHub.ts"],"mappings":";;;;;;;;;;;;UAYiB;EACf;EACA;EACA;;UAGe;EACf;;EAEA;;;UAIe;;EAEf,qBAAqB;;EAErB,QAAQ,mBAAmB;EAC3B,SAAS;;;;;;;UAQM;;EAEf,WAAW,OAAO;EAClB,cAAc,OAAO;EACrB,gBAAgB;;;;;;EAMhB,eAAe,OAAO,iBAAiB;EACvC;;UAGe;;EAEf;EACA,MAAM,MAAM,iBAAiB"}

package/dist/types/webPlugin.d.cts

@@ -0,0 +1,343 @@
+import { Store } from "@tanstack/store";
+import { ComponentType, ReactNode } from "react";
+//#region src/types/webPlugin.d.ts
+/**
+ * The client half of the DoomPi web plugin contract.
+ *
+ * A plugin package exports one `webPlugin: WebPluginDefinition` from its
+ * declared client entry. The cockpit's bundler compiles that entry into the
+ * host bundle, so a plugin's client code may import only react,
+ * @tanstack/store, @tanstack/react-store, this contract,
+ * @agimon-ai/doompi-web-components, and the package's own web/ and src/types
+ * modules; never another plugin, a node builtin, or a server framework, which
+ * the host bundle would swallow. Per-session state takes the shape
+ * defineSessionStore gives it. Tailwind utility classes must appear as
+ * complete literal strings so the host's class scanner can see them.
+ *
+ * Plugins are independent: none depends on another, any of them may be added
+ * or removed at the next sync, and every relation between two plugins (a fill
+ * into a slot, a section inside an activity group) resolves by name once every
+ * plugin is installed. The manifest's registrationOrder is only a tiebreak,
+ * and a collision between two plugins is an install diagnostic, never a
+ * failure.
+ */
+/** Sends one command frame to a session's agent on the page's hub socket. */
+type SessionFrameSender = (sessionId: string, frame: Record<string, unknown>) => void;
+/**
+ * A slot a plugin opens inside its own UI for independent plugins to fill.
+ * The name is namespaced by its owner, '<pluginId>.<name>', so no two plugins
+ * open the same slot. A slot with a parse gate takes data fills, declared as
+ * data the owner renders; one without takes component fills the owner places
+ * with renderSlot. Either side may be absent: the owner renders with zero
+ * fills, and a fill into a slot no installed plugin declares is an install
+ * diagnostic, never a failure.
+ */
+interface SlotDeclaration<Data = unknown> {
+  slot: string;
+  /** The gate for data fills, run once at install; null rejects the fill with a diagnostic. */
+  parse?(input: unknown): Data | null;
+}
+/** A data fill as its owner reads it back, already through the parse gate. */
+interface SlotDataFill<Data = unknown> {
+  pluginId: string;
+  id: string;
+  order: number;
+  data: Data;
+}
+/**
+ * A tab a plugin opens at runtime for one session, beside the declared ones:
+ * the reader closes it, and it goes with the session or the page. The host
+ * keeps the panel it was opened with, so opening the same id again only
+ * focuses the tab.
+ */
+interface TransientTab {
+  /** Unique across plugins and URL-safe: '<pluginId>-<name>-<key>'. */
+  id: string;
+  label: string;
+  panel: ComponentType<WebPluginSlotProps>;
+}
+/** Every slot component receives the focused session; null while nothing is focused. */
+interface WebPluginSlotProps {
+  sessionId: string | null;
+  /** Host navigation for the focused session; null returns to the conversation tab. */
+  openTab: (tabId: string | null) => void;
+  /** Opens the tab for the focused session, or focuses it when one with the same id is already open. */
+  openTransientTab: (tab: TransientTab) => void;
+  closeTransientTab: (tabId: string) => void;
+  /**
+   * The host's live conversation view of one thread of the focused session,
+   * rendered like the session's own timeline and subscribed while mounted. A
+   * plugin's hub source names the thread's journal (HubChannelSource.threadJournal).
+   */
+  renderThread: (threadId: string) => ReactNode;
+  /** The same sender palette commands and `start` receive; components act through it. */
+  sendSessionFrame: SessionFrameSender;
+  /** The component fills of one slot, in slot order; the host resolves them, so this contract holds no state. */
+  renderSlot: (slot: string) => ReactNode;
+  /** The data fills of one slot, typed by the declaration handle only its owner holds. */
+  slotData: <Data>(slot: SlotDeclaration<Data>) => readonly SlotDataFill<Data>[];
+  /**
+   * The footer statuses the focused session has published, raw, keyed as the
+   * publishing extension named them. A package reads its own key: the status
+   * line is the only thing some modes report, and a plugin that renders its
+   * own surface needs the same facts the host folds into the selection bar.
+   */
+  statuses: Readonly<Record<string, string>>;
+}
+/**
+ * One contribution into a slot, keyed by (pluginId, id): independent plugins
+ * never collide on an id. A component fill renders where the owner places the
+ * slot; a data fill is what the owner's parse gate reads.
+ */
+interface SlotFillContribution {
+  slot: string;
+  id: string;
+  /** Sort position within the slot; lower first, then pluginId, then id. */
+  order?: number;
+  data?: unknown;
+  component?: ComponentType<WebPluginSlotProps>;
+}
+interface TabContribution {
+  /** URL segment (/session/:id/:tabId) and testid suffix (tab-<id>, tab-<id>-count). */
+  id: string;
+  label: string;
+  panel: ComponentType<WebPluginSlotProps>;
+  /** A React hook, fully typed inside the plugin; 0 hides the badge. */
+  useBadge?: (sessionId: string | null) => number;
+}
+interface SurfaceContribution {
+  id: string;
+  component: ComponentType<WebPluginSlotProps>;
+}
+interface PaletteCommandContext {
+  sessionId: string | null;
+  /** Host navigation; null returns to the conversation tab. */
+  openTab(tabId: string | null): void;
+  sendSessionFrame: SessionFrameSender;
+}
+interface PaletteCommandContribution {
+  id: string;
+  title: string;
+  description?: string;
+  run(context: PaletteCommandContext): void;
+}
+/**
+ * One step of a Leader Space key path: the key pressed and the label the
+ * menu shows beside it. Keys are one lowercase letter or digit, the same
+ * alphabet the TUI's leader registry accepts.
+ */
+interface LeaderKeyContribution {
+  key: string;
+  label: string;
+  detail?: string;
+}
+interface LeaderBindingBase {
+  id: string;
+  /** The SPC path, group segments first; the last segment is the key that fires. */
+  path: LeaderKeyContribution[];
+}
+/**
+ * A Leader Space binding, the cockpit's half of the TUI's leader contract.
+ *
+ * The session's own leader tree never reaches an RPC client, so each package
+ * declares here the paths its TUI documents that a browser can honor: a slash
+ * command line the host sends through the prompt channel (without the leading
+ * slash), or a client action such as opening the plugin's tab. Plugins that
+ * share a group prefix (SPC w) word it the same way; the first to register a
+ * segment names it, and a later binding on an already-bound leaf takes it
+ * over. Either disagreement between two plugins is an install diagnostic.
+ */
+type LeaderBindingContribution = (LeaderBindingBase & {
+  command: string;
+}) | (LeaderBindingBase & {
+  run(context: PaletteCommandContext): void;
+});
+/**
+ * A minor mode's presence in the cockpit, declared as data rather than a
+ * component: the host's selection bar renders the list, folding in what the
+ * session reports. A mode with neither signal key shows as unavailable until
+ * its package publishes one.
+ */
+interface MinorModeContribution {
+  name: string;
+  /**
+   * The catalog mode this row drives, when the runtime registers it under a
+   * different id than the row shows. A package whose leader key drives one of
+   * several modes it owns needs this: the row must reach the same mode the
+   * key does, not the one that happens to share the row's label.
+   */
+  modeId?: string;
+  /** Leader Space key path, as the TUI documents it. */
+  keys: string;
+  /** Footer status key whose presence and content report availability and detail. */
+  statusKey?: string;
+  /** Widget key whose presence reports the mode as installed but off. */
+  widgetKey?: string;
+  /** Sort position in the selection bar list; lower first, name breaks ties. */
+  order?: number;
+}
+/**
+ * A selection-bar axis, declared as data: the host renders the chip and
+ * routes its click through the axis's slash command. The axis shows only
+ * while the session publishes the status key; the content is the current
+ * selection, and emptyLabel shows while it is published empty.
+ */
+interface SelectionAxisContribution {
+  /** Chip identity: testid axis-<name> and the popover menu it claims. */
+  name: string;
+  /** Slash command the host runs when the chip is clicked. */
+  command: string;
+  /** Footer status key: absent hides the axis, content is the selection. */
+  statusKey: string;
+  /** Shown while the status is published with nothing selected. */
+  emptyLabel: string;
+  /** The status content is a comma-separated list: several selections can be active at once. */
+  multi?: boolean;
+  /** Sort position in the bar; lower first, name breaks ties. */
+  order?: number;
+}
+/**
+ * An activity-dock group, declared as data: the host renders the group's
+ * frame when the session publishes its signal (the footer status key, or any
+ * of the widget keys). The body is the status content as a one-line summary
+ * unless some plugin fills the group's slot, `activity.<name>`, with an
+ * activity section of the same name, in which case those sections render the
+ * body themselves.
+ */
+interface ActivityGroupContribution {
+  name: string;
+  /** Leader Space key path, as the TUI documents it. */
+  keys: string;
+  /** Footer status key whose presence shows the group and content fills its summary. */
+  statusKey?: string;
+  /** Widget keys any of which shows the group without a summary. */
+  widgetKeys?: string[];
+  /** The plugin tab the group's key chip opens; without one the chip is a plain label. */
+  tab?: string;
+  /** Sort position in the dock; lower first, name breaks ties. */
+  order?: number;
+}
+/**
+ * One session-scoped data channel: the hub pushes ChannelFrame payloads whose
+ * frame type equals `channel`; parse is the validation gate at the boundary
+ * (null rejects); drop clears the plugin's per-session state.
+ */
+interface SessionChannelContribution<Payload = unknown> {
+  channel: string;
+  parse(input: unknown): Payload | null;
+  apply(sessionId: string, payload: Payload): void;
+  drop(sessionId: string): void;
+}
+/** One record per session id; a missing key means the session has reported nothing. */
+type SessionRecords<T> = Partial<Record<string, T>>;
+/** A channel folded straight into a session store: parse gates the wire, reduce folds one payload into the record. */
+interface SessionStoreChannel<T, Payload> {
+  channel: string;
+  parse(input: unknown): Payload | null;
+  /** Folds one payload into the session's record; ephemeral fields (stop requests, dismissals) reconcile here. */
+  reduce(current: T, payload: Payload): T;
+}
+/**
+ * Per-session plugin state, the shape every plugin's store takes: one record
+ * per session, shared by the plugin's tab, badge, sections, and channels.
+ * Records are immutable values; updaters and reducers return new ones.
+ */
+interface SessionStore<T> {
+  readonly store: Store<SessionRecords<T>>;
+  /**
+   * The session's record, or the one shared empty record for null and unknown
+   * sessions: a stable reference, so a useStore selector over it never
+   * re-renders on an unchanged session.
+   */
+  select(state: SessionRecords<T>, sessionId: string | null): T;
+  /** Replaces the session's record; an updater returning the current record publishes nothing. */
+  update(sessionId: string, updater: (current: T) => T): void;
+  drop(sessionId: string): void;
+  reset(): void;
+  /** A session channel whose apply and drop are already wired to this store. */
+  channel<Payload>(options: SessionStoreChannel<T, Payload>): SessionChannelContribution;
+}
+/**
+ * A tool result as Pi's tool_execution frames carry it: the content blocks
+ * the model sees and the structured `details` the tool attached for its own
+ * renderer. Both are wire JSON; the plugin that owns the tool narrows them.
+ */
+interface ToolResultView {
+  content: unknown[];
+  details: unknown;
+}
+/**
+ * Everything a tool's timeline item receives: the actions every plugin
+ * component gets, plus the call and its newest result. The component owns
+ * the whole item, its frame, header, body, and expand state included; the
+ * host only wraps it in the timeline row and catches a throw. Compose it
+ * from the shared components package's MessageItem so it looks like every
+ * other item, the host's own fallback included.
+ */
+interface ToolMessageRenderProps extends WebPluginSlotProps {
+  toolCallId: string;
+  /** The wire name, as registered with Pi (registerTool's `name`). */
+  toolName: string;
+  args: Record<string, unknown>;
+  /** The session's footer statuses at render time, the same picture `matches` saw. */
+  statuses: Readonly<Record<string, string>>;
+  /** The newest result: partial while the tool runs, final once it ends; null before any output. */
+  result: ToolResultView | null;
+  /** The result's text blocks joined, which is what the host's fallback item shows. */
+  output: string;
+  /** True while the tool still runs, so `result` is a partial one. */
+  running: boolean;
+  isError: boolean;
+}
+/**
+ * The timeline item for the tools a package registers, the web half of the
+ * TUI's renderCall/renderResult with Pi's renderShell 'self': one `message`
+ * component per claimed tool owns the whole item. One tool name belongs to
+ * one renderer.
+ */
+interface ToolRendererContribution {
+  /** Tool names as registered with Pi (registerTool's `name`). */
+  tools: string[];
+  /**
+   * Claims a tool named only at runtime (an MCP server's tools) when no
+   * plugin lists the name. The session's footer statuses come along so the
+   * plugin can read whatever its session half published, such as the server
+   * names; the first renderer to match, in install order, wins.
+   */
+  matches?(toolName: string, statuses: Readonly<Record<string, string>>): boolean;
+  message: ComponentType<ToolMessageRenderProps>;
+}
+/** What a plugin's optional runtime may do; both send on the page's hub socket. */
+interface WebPluginRuntime {
+  sendSessionFrame: SessionFrameSender;
+  sendHubFrame(frame: Record<string, unknown>): void;
+}
+interface WebPluginDefinition {
+  id: string;
+  tabs?: TabContribution[];
+  channels?: SessionChannelContribution[];
+  selectionAxes?: SelectionAxisContribution[];
+  minorModes?: MinorModeContribution[];
+  activityGroups?: ActivityGroupContribution[];
+  overlays?: SurfaceContribution[];
+  paletteCommands?: PaletteCommandContribution[];
+  leaderBindings?: LeaderBindingContribution[];
+  railSections?: SurfaceContribution[];
+  selectionBarItems?: SurfaceContribution[];
+  toolRenderers?: ToolRendererContribution[];
+  /**
+   * A section whose id names an activity group any plugin declares renders
+   * inside that group's slot, `activity.<id>`, replacing the session's
+   * one-line summary; any other section renders after the groups.
+   */
+  activitySections?: SurfaceContribution[];
+  /** The slots this plugin opens for others, each named '<this plugin id>.<name>'. */
+  slots?: SlotDeclaration[];
+  /** This plugin's contributions into slots other plugins (or the host) declare. */
+  fills?: SlotFillContribution[];
+  /** Started after the host runtime, for page-lifetime needs such as hub frames; the return value disposes. */
+  start?(runtime: WebPluginRuntime): (() => void) | void;
+}
+//#endregion
+export { ActivityGroupContribution, LeaderBindingBase, LeaderBindingContribution, LeaderKeyContribution, MinorModeContribution, PaletteCommandContext, PaletteCommandContribution, SelectionAxisContribution, SessionChannelContribution, SessionFrameSender, SessionRecords, SessionStore, SessionStoreChannel, SlotDataFill, SlotDeclaration, SlotFillContribution, SurfaceContribution, TabContribution, ToolMessageRenderProps, ToolRendererContribution, ToolResultView, TransientTab, WebPluginDefinition, WebPluginRuntime, WebPluginSlotProps };
+//# sourceMappingURL=webPlugin.d.cts.map

package/dist/types/webPlugin.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webPlugin.d.cts","names":[],"sources":["../../src/types/webPlugin.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;KAwBY,sBAAsB,mBAAmB,OAAO;;;;;;;;;;UAU3C,gBAAgB;EAC/B;;EAEA,OAAO,iBAAiB;;;UAGT,aAAa;EAC5B;EACA;EACA;EACA,MAAM;;;;;;;;UAQS;;EAEf;EACA;EACA,OAAO,cAAc;;;UAGN;EACf;;EAEA,UAAU;;EAEV,mBAAmB,KAAK;EACxB,oBAAoB;;;;;;EAMpB,eAAe,qBAAqB;;EAEpC,kBAAkB;;EAElB,aAAa,iBAAiB;;EAE9B,WAAW,MAAM,MAAM,gBAAgB,mBAAmB,aAAa;;;;;;;EAOvE,UAAU,SAAS;;;;;;;UAOJ;EACf;EACA;;EAEA;EACA;EACA,YAAY,cAAc;;UAEX;;EAEf;EACA;EACA,OAAO,cAAc;;EAErB,YAAY;;UAEG;EACf;EACA,WAAW,cAAc;;UAEV;EACf;;EAEA,QAAQ;EACR,kBAAkB;;UAEH;EACf;EACA;EACA;EACA,IAAI,SAAS;;;;;;;UAOE;EACf;EACA;EACA;;UAEe;EACf;;EAEA,MAAM;;;;;;;;;;;;;KAaI,6BACP;EACC;MAED;EACC,IAAI,SAAS;;;;;;;;UAQF;EACf;;;;;;;EAOA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;UAQe;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;;;UAUe;EACf;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;UAOe,2BAA2B;EAC1C;EACA,MAAM,iBAAiB;EACvB,MAAM,mBAAmB,SAAS;EAClC,KAAK;;;KAGK,eAAe,KAAK,QAAQ,eAAe;;UAEtC,oBAAoB,GAAG;EACtC;EACA,MAAM,iBAAiB;;EAEvB,OAAO,SAAS,GAAG,SAAS,UAAU;;;;;;;UAOvB,aAAa;WACnB,OAAO,MAAM,eAAe;;;;;;EAMrC,OAAO,OAAO,eAAe,IAAI,2BAA2B;;EAE5D,OAAO,mBAAmB,UAAU,SAAS,MAAM;EACnD,KAAK;EACL;;EAEA,QAAQ,SAAS,SAAS,oBAAoB,GAAG,WAAW;;;;;;;UAO7C;EACf;EACA;;;;;;;;;;UAUe,+BAA+B;EAC9C;;EAEA;EACA,MAAM;;EAEN,UAAU,SAAS;;EAEnB,QAAQ;;EAER;;EAEA;EACA;;;;;;;;UAQe;;EAEf;;;;;;;EAOA,SAAS,kBAAkB,UAAU,SAAS;EAC9C,SAAS,cAAc;;;UAGR;EACf,kBAAkB;EAClB,aAAa,OAAO;;UAEL;EACf;EACA,OAAO;EACP,WAAW;EACX,gBAAgB;EAChB,aAAa;EACb,iBAAiB;EACjB,WAAW;EACX,kBAAkB;EAClB,iBAAiB;EACjB,eAAe;EACf,oBAAoB;EACpB,gBAAgB;;;;;;EAMhB,mBAAmB;;EAEnB,QAAQ;;EAER,QAAQ;;EAER,OAAO,SAAS"}