@withpotter/lib 0.13.0-next.101

package/dist/editor-agent/contracts.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Editor-agent (E5d "Ask AI") shared wire contracts.
+ *
+ * Frozen mirror of `withpotter/roadmap/handoffs/editor-agent-e5d.md` §3.2. These
+ * types MUST match:
+ *   - agency-runtime `modules/proposals/models/page_diff.py` (op wire shapes)
+ *   - the dashboard proxy `POST /api/editor-agent/propose`
+ *   - api `POST /editor-agent/propose` (the public gateway)
+ *   - the runtime `POST {AGENCY_RUNTIME_URL}/editor/propose`
+ *
+ * The merchant never talks to agency-runtime directly. The dashboard forwards
+ * the authenticated merchant's session to api, and api (the single public
+ * ingress) holds the runtime service credential and forwards to the private
+ * runtime (handoff §3.1/§3.4).
+ */
+/** Selection scope for an Ask-AI request. */
+export interface EditSelection {
+    /** `section` = a single section row; `page` = the whole page. */
+    scope: 'section' | 'page';
+    /** Required when `scope === 'section'`. */
+    sectionId?: string;
+}
+/**
+ * merchant-dashboard → agency-runtime editor toolset (request body).
+ *
+ * `templateDocument` is the already-shipped `GET /api/templates/:id` document,
+ * forwarded so the runtime can ground tool arguments in real field names,
+ * current values, and valid variant/token vocabulary.
+ */
+export interface ProposeEditRequest {
+    /** The page/template draft being edited. */
+    pageId: string;
+    /** The merchant's natural-language instruction. */
+    prompt: string;
+    selection: EditSelection;
+    /** Forwarded template document; opaque to the dashboard. */
+    templateDocument: unknown;
+}
+/**
+ * Typed page-diff op wire shape. MUST match agency-runtime
+ * `modules/proposals/models/page_diff.py` and api's page-diff contract. The
+ * runtime's tools compile ONLY into these ops — an agent composes typed ops,
+ * never raw dicts.
+ */
+export type PageDiffOp = {
+    op: 'set-field';
+    sectionId: string;
+    field: string;
+    value: unknown;
+} | {
+    op: 'set-extension';
+    sectionId: string;
+    field: string;
+    value: unknown;
+} | {
+    op: 'set-variant';
+    sectionId: string;
+    variant: string;
+} | {
+    op: 'add-block';
+    block: {
+        type: string;
+        data: Record<string, unknown>;
+        afterSectionId?: string;
+    };
+} | {
+    op: 'remove-block';
+    sectionId: string;
+} | {
+    op: 'reorder';
+    order: string[];
+};
+/** The proposal the runtime composed from the prompt. */
+export interface EditProposal {
+    pageId: string;
+    /** Typed page-diff ops. */
+    ops: PageDiffOp[];
+    /** Partial `settings.design` patch (E5a-gated). */
+    designDiff?: Record<string, unknown>;
+}
+/**
+ * agency-runtime → merchant-dashboard (response body).
+ *
+ * The proposal is applied optimistically to the preview iframe; `receiptId` is
+ * present once the runtime has submitted the draft to api (origin
+ * `editor-agent` → lands `draft`, awaiting the Accept gate).
+ */
+export interface ProposeEditResponse {
+    proposal: EditProposal;
+    /** Host proposal id — present once submitted; the Accept target. */
+    receiptId?: string;
+    /** One-line human summary of what changed. */
+    narration: string;
+    /** Tools the prompt wanted but that are guarded/unavailable. */
+    unavailableTools?: string[];
+}
+export interface ConversationContext {
+    pageId: string;
+    templateDocument: unknown;
+}
+export type CompanionDomain = 'ui' | 'business';
+export interface CompanionSurface {
+    kind: 'editor' | 'dashboard';
+    route: string;
+}
+export interface BusinessEvidence {
+    generatedAt: string;
+    window: {
+        key: `${number}d` | 'ytd' | 'mtd' | 'last-month' | 'last-year';
+        start: string;
+        end: string;
+    };
+    comparison?: {
+        window: BusinessEvidence['window'];
+    };
+    currency: string;
+    items: Array<{
+        key: string;
+        label: string;
+        value: number | string;
+        unit: 'currency' | 'count' | 'percent' | 'text';
+    }>;
+}
+export interface ConverseRequest {
+    sessionId?: string;
+    prompt: string;
+    previousPrompt?: string;
+    previousPrompts?: string[];
+    selection?: EditSelection;
+    context?: ConversationContext;
+    surface?: CompanionSurface;
+}
+export type ConverseEvent = {
+    event: 'session';
+    data: {
+        sessionId: string;
+    };
+} | {
+    event: 'domain';
+    data: {
+        domain: CompanionDomain;
+        label: string;
+    };
+} | {
+    event: 'narration';
+    data: {
+        delta: string;
+    };
+} | {
+    event: 'evidence';
+    data: BusinessEvidence;
+} | {
+    event: 'clarify';
+    data: {
+        question: string;
+        options?: string[];
+    };
+} | {
+    event: 'proposal';
+    data: {
+        proposal: EditProposal;
+        receiptId?: string;
+        unavailableTools?: string[];
+    };
+} | {
+    event: 'done';
+    data: Record<string, never>;
+} | {
+    event: 'error';
+    data: {
+        code: string;
+        message: string;
+    };
+};

package/dist/editor-agent/contracts.js

@@ -0,0 +1 @@
+//# sourceMappingURL=contracts.js.map

package/dist/editor-agent/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/editor-agent/converse.d.ts

@@ -0,0 +1,34 @@
+import type { BusinessEvidence, CompanionDomain, ConverseEvent, ConverseRequest, EditProposal } from './contracts';
+export interface ConverseTurnResult {
+    sessionId: string;
+    narration: string;
+    domain?: {
+        domain: CompanionDomain;
+        label: string;
+    };
+    evidence?: BusinessEvidence;
+    clarify?: {
+        question: string;
+        options?: string[];
+    };
+    proposal?: EditProposal;
+    receiptId?: string;
+    unavailableTools?: string[];
+}
+export declare class ConverseRequestError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(message: string, status: number, code?: string | undefined);
+}
+export declare function isMissingConversationSession(error: unknown): boolean;
+export declare function buildConverseRequest({ sessionId, prompt, previousPrompt, previousPrompts, selection, context, businessEnabled, pathname, }: Omit<ConverseRequest, 'surface'> & {
+    businessEnabled: boolean;
+    pathname: string;
+}): ConverseRequest;
+export declare function parseSseFrame(frame: string): ConverseEvent | null;
+export declare function streamConversation({ tenantSlug, request, signal, onEvent, }: {
+    tenantSlug: string;
+    request: ConverseRequest;
+    signal: AbortSignal;
+    onEvent?: (event: ConverseEvent) => void;
+}): Promise<ConverseTurnResult>;

package/dist/editor-agent/converse.js

@@ -0,0 +1,141 @@
+import { expireBrowserSession } from "../auth-session";
+class ConverseRequestError extends Error {
+  constructor(message, status, code) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.name = "ConverseRequestError";
+  }
+  status;
+  code;
+}
+function isMissingConversationSession(error) {
+  return error instanceof ConverseRequestError && error.status === 400 && error.code === "bad-request" && error.message === "conversation session was not found for this tenant";
+}
+function buildConverseRequest({
+  sessionId,
+  prompt,
+  previousPrompt,
+  previousPrompts,
+  selection,
+  context,
+  businessEnabled,
+  pathname
+}) {
+  return {
+    sessionId,
+    prompt,
+    ...previousPrompt ? { previousPrompt } : {},
+    ...previousPrompts?.length ? { previousPrompts } : {},
+    selection,
+    context,
+    ...businessEnabled ? {
+      surface: {
+        kind: pathname.startsWith("/dashboard/editor") ? "editor" : "dashboard",
+        route: pathname
+      }
+    } : {}
+  };
+}
+function parseSseFrame(frame) {
+  let event = "";
+  const dataLines = [];
+  for (const line of frame.split("\n")) {
+    if (line.startsWith("event:")) event = line.slice(6).trim();
+    if (line.startsWith("data:")) dataLines.push(line.slice(5).trimStart());
+  }
+  if (!event || dataLines.length === 0) return null;
+  const data = JSON.parse(dataLines.join("\n"));
+  return { event, data };
+}
+async function streamConversation({
+  tenantSlug,
+  request,
+  signal,
+  onEvent
+}) {
+  const response = await fetch("/api/editor-agent/converse", {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "x-tenant-slug": tenantSlug
+    },
+    body: JSON.stringify(request),
+    signal
+  });
+  if (!response.ok || !response.body) {
+    if (response.status === 401) {
+      expireBrowserSession();
+    }
+    const detail = await response.json().catch(() => null);
+    throw new ConverseRequestError(
+      detail?.message ?? detail?.error ?? `Request failed (${response.status}).`,
+      response.status,
+      detail?.error
+    );
+  }
+  const result = {
+    sessionId: request.sessionId ?? "",
+    narration: ""
+  };
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  const consume = (frame) => {
+    const parsed = parseSseFrame(frame);
+    if (!parsed) return;
+    onEvent?.(parsed);
+    switch (parsed.event) {
+      case "session":
+        result.sessionId = parsed.data.sessionId;
+        break;
+      case "narration":
+        result.narration += parsed.data.delta;
+        break;
+      case "domain":
+        result.domain = parsed.data;
+        break;
+      case "evidence":
+        result.evidence = parsed.data;
+        break;
+      case "clarify":
+        result.clarify = parsed.data;
+        break;
+      case "proposal":
+        result.proposal = parsed.data.proposal;
+        result.receiptId = parsed.data.receiptId;
+        result.unavailableTools = parsed.data.unavailableTools;
+        break;
+      case "error":
+        throw new Error(parsed.data.message);
+    }
+  };
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      buffer += decoder.decode(value, { stream: !done }).replaceAll("\r\n", "\n");
+      let boundary = buffer.indexOf("\n\n");
+      while (boundary !== -1) {
+        consume(buffer.slice(0, boundary));
+        buffer = buffer.slice(boundary + 2);
+        boundary = buffer.indexOf("\n\n");
+      }
+      if (done) break;
+    }
+    if (buffer.trim()) consume(buffer);
+  } catch (error) {
+    await reader.cancel().catch(() => void 0);
+    throw error;
+  }
+  if (!result.sessionId)
+    throw new Error("Conversation session was not established.");
+  return result;
+}
+export {
+  ConverseRequestError,
+  buildConverseRequest,
+  isMissingConversationSession,
+  parseSseFrame,
+  streamConversation
+};
+//# sourceMappingURL=converse.js.map

package/dist/editor-agent/converse.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/editor-agent/converse.ts"],"sourcesContent":["import type {\n  BusinessEvidence,\n  CompanionDomain,\n  ConverseEvent,\n  ConverseRequest,\n  EditProposal,\n} from './contracts';\nimport { expireBrowserSession } from '../auth-session';\n\nexport interface ConverseTurnResult {\n  sessionId: string;\n  narration: string;\n  domain?: { domain: CompanionDomain; label: string };\n  evidence?: BusinessEvidence;\n  clarify?: { question: string; options?: string[] };\n  proposal?: EditProposal;\n  receiptId?: string;\n  unavailableTools?: string[];\n}\n\nexport class ConverseRequestError extends Error {\n  constructor(\n    message: string,\n    readonly status: number,\n    readonly code?: string,\n  ) {\n    super(message);\n    this.name = 'ConverseRequestError';\n  }\n}\n\nexport function isMissingConversationSession(error: unknown): boolean {\n  return (\n    error instanceof ConverseRequestError &&\n    error.status === 400 &&\n    error.code === 'bad-request' &&\n    error.message === 'conversation session was not found for this tenant'\n  );\n}\n\nexport function buildConverseRequest({\n  sessionId,\n  prompt,\n  previousPrompt,\n  previousPrompts,\n  selection,\n  context,\n  businessEnabled,\n  pathname,\n}: Omit<ConverseRequest, 'surface'> & {\n  businessEnabled: boolean;\n  pathname: string;\n}): ConverseRequest {\n  return {\n    sessionId,\n    prompt,\n    ...(previousPrompt ? { previousPrompt } : {}),\n    ...(previousPrompts?.length ? { previousPrompts } : {}),\n    selection,\n    context,\n    ...(businessEnabled\n      ? {\n          surface: {\n            kind: pathname.startsWith('/dashboard/editor')\n              ? ('editor' as const)\n              : ('dashboard' as const),\n            route: pathname,\n          },\n        }\n      : {}),\n  };\n}\n\nexport function parseSseFrame(frame: string): ConverseEvent | null {\n  let event = '';\n  const dataLines: string[] = [];\n  for (const line of frame.split('\\n')) {\n    if (line.startsWith('event:')) event = line.slice(6).trim();\n    if (line.startsWith('data:')) dataLines.push(line.slice(5).trimStart());\n  }\n  if (!event || dataLines.length === 0) return null;\n  const data = JSON.parse(dataLines.join('\\n')) as ConverseEvent['data'];\n  return { event, data } as ConverseEvent;\n}\n\nexport async function streamConversation({\n  tenantSlug,\n  request,\n  signal,\n  onEvent,\n}: {\n  tenantSlug: string;\n  request: ConverseRequest;\n  signal: AbortSignal;\n  onEvent?: (event: ConverseEvent) => void;\n}): Promise<ConverseTurnResult> {\n  const response = await fetch('/api/editor-agent/converse', {\n    method: 'POST',\n    headers: {\n      'content-type': 'application/json',\n      'x-tenant-slug': tenantSlug,\n    },\n    body: JSON.stringify(request),\n    signal,\n  });\n  if (!response.ok || !response.body) {\n    if (response.status === 401) {\n      expireBrowserSession();\n    }\n    const detail = (await response.json().catch(() => null)) as {\n      error?: string;\n      message?: string;\n    } | null;\n    throw new ConverseRequestError(\n      detail?.message ??\n        detail?.error ??\n        `Request failed (${response.status}).`,\n      response.status,\n      detail?.error,\n    );\n  }\n\n  const result: ConverseTurnResult = {\n    sessionId: request.sessionId ?? '',\n    narration: '',\n  };\n  const reader = response.body.getReader();\n  const decoder = new TextDecoder();\n  let buffer = '';\n\n  const consume = (frame: string) => {\n    const parsed = parseSseFrame(frame);\n    if (!parsed) return;\n    onEvent?.(parsed);\n    switch (parsed.event) {\n      case 'session':\n        result.sessionId = parsed.data.sessionId;\n        break;\n      case 'narration':\n        result.narration += parsed.data.delta;\n        break;\n      case 'domain':\n        result.domain = parsed.data;\n        break;\n      case 'evidence':\n        result.evidence = parsed.data;\n        break;\n      case 'clarify':\n        result.clarify = parsed.data;\n        break;\n      case 'proposal':\n        result.proposal = parsed.data.proposal;\n        result.receiptId = parsed.data.receiptId;\n        result.unavailableTools = parsed.data.unavailableTools;\n        break;\n      case 'error':\n        throw new Error(parsed.data.message);\n    }\n  };\n\n  try {\n    while (true) {\n      const { done, value } = await reader.read();\n      buffer += decoder\n        .decode(value, { stream: !done })\n        .replaceAll('\\r\\n', '\\n');\n      let boundary = buffer.indexOf('\\n\\n');\n      while (boundary !== -1) {\n        consume(buffer.slice(0, boundary));\n        buffer = buffer.slice(boundary + 2);\n        boundary = buffer.indexOf('\\n\\n');\n      }\n      if (done) break;\n    }\n    if (buffer.trim()) consume(buffer);\n  } catch (error) {\n    await reader.cancel().catch(() => undefined);\n    throw error;\n  }\n  if (!result.sessionId)\n    throw new Error('Conversation session was not established.');\n  return result;\n}\n"],"mappings":"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","names":[]}

package/dist/editor-agent/flag.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `flag:editor-agent` — the E5d "Ask AI" popover is default-off until the
+ * agency-runtime serving surface (roadmap#114, E4b) is live and the runtime
+ * `POST /editor/propose` endpoint answers. Enable client-side with
+ * `NEXT_PUBLIC_EDITOR_AGENT_ENABLED=1`.
+ *
+ * Mirrors the `isBrandDesignPanelEnabled()` pattern (design-panel.tsx).
+ */
+export declare function isEditorAgentEnabled(): boolean;
+export declare function isInteractiveCompanionEnabled(): boolean;
+export declare function isCompanionBusinessEnabled(): boolean;
+export declare function isCommerceBuildEnabled(): boolean;

package/dist/editor-agent/flag.js

@@ -0,0 +1,19 @@
+function isEditorAgentEnabled() {
+  return process.env.NEXT_PUBLIC_EDITOR_AGENT_ENABLED === "1";
+}
+function isInteractiveCompanionEnabled() {
+  return process.env.NEXT_PUBLIC_EDITOR_AGENT_CONVERSE_ENABLED === "1";
+}
+function isCompanionBusinessEnabled() {
+  return process.env.NEXT_PUBLIC_COMPANION_BUSINESS_ENABLED === "1";
+}
+function isCommerceBuildEnabled() {
+  return process.env.NEXT_PUBLIC_COMMERCE_BUILD_ENABLED === "1";
+}
+export {
+  isCommerceBuildEnabled,
+  isCompanionBusinessEnabled,
+  isEditorAgentEnabled,
+  isInteractiveCompanionEnabled
+};
+//# sourceMappingURL=flag.js.map

package/dist/editor-agent/flag.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/editor-agent/flag.ts"],"sourcesContent":["/**\n * `flag:editor-agent` — the E5d \"Ask AI\" popover is default-off until the\n * agency-runtime serving surface (roadmap#114, E4b) is live and the runtime\n * `POST /editor/propose` endpoint answers. Enable client-side with\n * `NEXT_PUBLIC_EDITOR_AGENT_ENABLED=1`.\n *\n * Mirrors the `isBrandDesignPanelEnabled()` pattern (design-panel.tsx).\n */\nexport function isEditorAgentEnabled(): boolean {\n  return process.env.NEXT_PUBLIC_EDITOR_AGENT_ENABLED === '1';\n}\n\nexport function isInteractiveCompanionEnabled(): boolean {\n  return process.env.NEXT_PUBLIC_EDITOR_AGENT_CONVERSE_ENABLED === '1';\n}\n\nexport function isCompanionBusinessEnabled(): boolean {\n  return process.env.NEXT_PUBLIC_COMPANION_BUSINESS_ENABLED === '1';\n}\n\nexport function isCommerceBuildEnabled(): boolean {\n  return process.env.NEXT_PUBLIC_COMMERCE_BUILD_ENABLED === '1';\n}\n"],"mappings":"AAQO,SAAS,uBAAgC;AAC9C,SAAO,QAAQ,IAAI,qCAAqC;AAC1D;AAEO,SAAS,gCAAyC;AACvD,SAAO,QAAQ,IAAI,8CAA8C;AACnE;AAEO,SAAS,6BAAsC;AACpD,SAAO,QAAQ,IAAI,2CAA2C;AAChE;AAEO,SAAS,yBAAkC;AAChD,SAAO,QAAQ,IAAI,uCAAuC;AAC5D;","names":[]}

package/dist/editor-agent/template-document.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Editor-agent template capabilities → runtime-shaped propose document.
+ *
+ * The agency-runtime editor toolset gates `set_block_variant` (E5b) and
+ * `set_design_tokens` (E5a) on what the forwarded document declares:
+ * `TemplateContext.from_document` reads `document.sections[].variants` and the
+ * keys of `document.design`. Those declarations live in web-render's template
+ * `block-renderers.ts` registry and the shared `settings.design` schema — never
+ * in the persisted template document — so without this projection both tools
+ * stay permanently guarded (roadmap#112 M3).
+ *
+ * This module fetches the web-render capability descriptor
+ * (`GET /api/templates/:id/capabilities`) and projects the current page's
+ * sections into the exact shape the runtime consumes. In this system a
+ * section's id is its canonical block type, so declared variants resolve by
+ * section id directly.
+ */
+/** Response shape of web-render `GET /api/templates/:id/capabilities`. */
+export interface TemplateCapabilities {
+    templateId: string;
+    /** Declared layout variants keyed by block type (== section id). */
+    blockVariants: Record<string, string[]>;
+    /** Universal top-level `settings.design` token groups. */
+    designTokenKeys: string[];
+}
+/** One grounded section in the forwarded document. */
+export interface ProposeDocumentSection {
+    id: string;
+    variants: string[];
+}
+/**
+ * The runtime-shaped document forwarded with a propose request. Only
+ * `sections` (ids + declared variants) and `design` (token-group keys) are read
+ * by the runtime; `page_id` is carried separately on the request.
+ */
+export interface ProposeTemplateDocument {
+    sections: ProposeDocumentSection[];
+    design: Record<string, unknown>;
+}
+/**
+ * Project the current page's section ids into the runtime document shape,
+ * annotating each with its template-declared variants and surfacing the design
+ * token groups. Missing capabilities yield empty variants / design, which
+ * correctly keeps the E5a/E5b tools guarded.
+ */
+export declare function buildProposeDocument(sectionIds: readonly string[], capabilities: TemplateCapabilities | null): ProposeTemplateDocument;
+/**
+ * Fetch the capability descriptor for a template from web-render. Best-effort:
+ * any network/parse failure resolves to `null` so the editor degrades to
+ * content-only editing rather than breaking the Ask-AI flow.
+ */
+export declare function fetchTemplateCapabilities(webUrl: string, templateId: string, signal?: AbortSignal): Promise<TemplateCapabilities | null>;

package/dist/editor-agent/template-document.js

@@ -0,0 +1,50 @@
+function buildProposeDocument(sectionIds, capabilities) {
+  const blockVariants = capabilities?.blockVariants ?? {};
+  const designTokenKeys = capabilities?.designTokenKeys ?? [];
+  const sections = sectionIds.map((id) => ({
+    id,
+    variants: Array.isArray(blockVariants[id]) ? blockVariants[id] : []
+  }));
+  const design = {};
+  for (const key of designTokenKeys) design[key] = {};
+  return { sections, design };
+}
+function parseCapabilities(data) {
+  if (!data || typeof data !== "object") return null;
+  const d = data;
+  if (typeof d.templateId !== "string") return null;
+  if (!d.blockVariants || typeof d.blockVariants !== "object") return null;
+  if (!Array.isArray(d.designTokenKeys)) return null;
+  const blockVariants = {};
+  for (const [type, values] of Object.entries(
+    d.blockVariants
+  )) {
+    if (Array.isArray(values)) {
+      blockVariants[type] = values.filter(
+        (v) => typeof v === "string"
+      );
+    }
+  }
+  const designTokenKeys = d.designTokenKeys.filter(
+    (k) => typeof k === "string"
+  );
+  return { templateId: d.templateId, blockVariants, designTokenKeys };
+}
+async function fetchTemplateCapabilities(webUrl, templateId, signal) {
+  try {
+    const base = webUrl.replace(/\/+$/, "");
+    const res = await fetch(
+      `${base}/api/templates/${encodeURIComponent(templateId)}/capabilities`,
+      { cache: "no-store", signal }
+    );
+    if (!res.ok) return null;
+    return parseCapabilities(await res.json());
+  } catch {
+    return null;
+  }
+}
+export {
+  buildProposeDocument,
+  fetchTemplateCapabilities
+};
+//# sourceMappingURL=template-document.js.map

package/dist/editor-agent/template-document.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/editor-agent/template-document.ts"],"sourcesContent":["/**\n * Editor-agent template capabilities → runtime-shaped propose document.\n *\n * The agency-runtime editor toolset gates `set_block_variant` (E5b) and\n * `set_design_tokens` (E5a) on what the forwarded document declares:\n * `TemplateContext.from_document` reads `document.sections[].variants` and the\n * keys of `document.design`. Those declarations live in web-render's template\n * `block-renderers.ts` registry and the shared `settings.design` schema — never\n * in the persisted template document — so without this projection both tools\n * stay permanently guarded (roadmap#112 M3).\n *\n * This module fetches the web-render capability descriptor\n * (`GET /api/templates/:id/capabilities`) and projects the current page's\n * sections into the exact shape the runtime consumes. In this system a\n * section's id is its canonical block type, so declared variants resolve by\n * section id directly.\n */\n\n/** Response shape of web-render `GET /api/templates/:id/capabilities`. */\nexport interface TemplateCapabilities {\n  templateId: string;\n  /** Declared layout variants keyed by block type (== section id). */\n  blockVariants: Record<string, string[]>;\n  /** Universal top-level `settings.design` token groups. */\n  designTokenKeys: string[];\n}\n\n/** One grounded section in the forwarded document. */\nexport interface ProposeDocumentSection {\n  id: string;\n  variants: string[];\n}\n\n/**\n * The runtime-shaped document forwarded with a propose request. Only\n * `sections` (ids + declared variants) and `design` (token-group keys) are read\n * by the runtime; `page_id` is carried separately on the request.\n */\nexport interface ProposeTemplateDocument {\n  sections: ProposeDocumentSection[];\n  design: Record<string, unknown>;\n}\n\n/**\n * Project the current page's section ids into the runtime document shape,\n * annotating each with its template-declared variants and surfacing the design\n * token groups. Missing capabilities yield empty variants / design, which\n * correctly keeps the E5a/E5b tools guarded.\n */\nexport function buildProposeDocument(\n  sectionIds: readonly string[],\n  capabilities: TemplateCapabilities | null,\n): ProposeTemplateDocument {\n  const blockVariants = capabilities?.blockVariants ?? {};\n  const designTokenKeys = capabilities?.designTokenKeys ?? [];\n\n  const sections = sectionIds.map((id) => ({\n    id,\n    variants: Array.isArray(blockVariants[id]) ? blockVariants[id] : [],\n  }));\n\n  // The runtime only reads the KEYS of `design` (any non-empty set unlocks\n  // `set_design_tokens`); values are irrelevant to gating.\n  const design: Record<string, unknown> = {};\n  for (const key of designTokenKeys) design[key] = {};\n\n  return { sections, design };\n}\n\n/** Narrow an unknown payload to `TemplateCapabilities`, or return null. */\nfunction parseCapabilities(data: unknown): TemplateCapabilities | null {\n  if (!data || typeof data !== 'object') return null;\n  const d = data as Record<string, unknown>;\n  if (typeof d.templateId !== 'string') return null;\n  if (!d.blockVariants || typeof d.blockVariants !== 'object') return null;\n  if (!Array.isArray(d.designTokenKeys)) return null;\n\n  const blockVariants: Record<string, string[]> = {};\n  for (const [type, values] of Object.entries(\n    d.blockVariants as Record<string, unknown>,\n  )) {\n    if (Array.isArray(values)) {\n      blockVariants[type] = values.filter(\n        (v): v is string => typeof v === 'string',\n      );\n    }\n  }\n  const designTokenKeys = d.designTokenKeys.filter(\n    (k): k is string => typeof k === 'string',\n  );\n\n  return { templateId: d.templateId, blockVariants, designTokenKeys };\n}\n\n/**\n * Fetch the capability descriptor for a template from web-render. Best-effort:\n * any network/parse failure resolves to `null` so the editor degrades to\n * content-only editing rather than breaking the Ask-AI flow.\n */\nexport async function fetchTemplateCapabilities(\n  webUrl: string,\n  templateId: string,\n  signal?: AbortSignal,\n): Promise<TemplateCapabilities | null> {\n  try {\n    const base = webUrl.replace(/\\/+$/, '');\n    const res = await fetch(\n      `${base}/api/templates/${encodeURIComponent(templateId)}/capabilities`,\n      { cache: 'no-store', signal },\n    );\n    if (!res.ok) return null;\n    return parseCapabilities(await res.json());\n  } catch {\n    return null;\n  }\n}\n"],"mappings":"AAiDO,SAAS,qBACd,YACA,cACyB;AACzB,QAAM,gBAAgB,cAAc,iBAAiB,CAAC;AACtD,QAAM,kBAAkB,cAAc,mBAAmB,CAAC;AAE1D,QAAM,WAAW,WAAW,IAAI,CAAC,QAAQ;AAAA,IACvC;AAAA,IACA,UAAU,MAAM,QAAQ,cAAc,EAAE,CAAC,IAAI,cAAc,EAAE,IAAI,CAAC;AAAA,EACpE,EAAE;AAIF,QAAM,SAAkC,CAAC;AACzC,aAAW,OAAO,gBAAiB,QAAO,GAAG,IAAI,CAAC;AAElD,SAAO,EAAE,UAAU,OAAO;AAC5B;AAGA,SAAS,kBAAkB,MAA4C;AACrE,MAAI,CAAC,QAAQ,OAAO,SAAS,SAAU,QAAO;AAC9C,QAAM,IAAI;AACV,MAAI,OAAO,EAAE,eAAe,SAAU,QAAO;AAC7C,MAAI,CAAC,EAAE,iBAAiB,OAAO,EAAE,kBAAkB,SAAU,QAAO;AACpE,MAAI,CAAC,MAAM,QAAQ,EAAE,eAAe,EAAG,QAAO;AAE9C,QAAM,gBAA0C,CAAC;AACjD,aAAW,CAAC,MAAM,MAAM,KAAK,OAAO;AAAA,IAClC,EAAE;AAAA,EACJ,GAAG;AACD,QAAI,MAAM,QAAQ,MAAM,GAAG;AACzB,oBAAc,IAAI,IAAI,OAAO;AAAA,QAC3B,CAAC,MAAmB,OAAO,MAAM;AAAA,MACnC;AAAA,IACF;AAAA,EACF;AACA,QAAM,kBAAkB,EAAE,gBAAgB;AAAA,IACxC,CAAC,MAAmB,OAAO,MAAM;AAAA,EACnC;AAEA,SAAO,EAAE,YAAY,EAAE,YAAY,eAAe,gBAAgB;AACpE;AAOA,eAAsB,0BACpB,QACA,YACA,QACsC;AACtC,MAAI;AACF,UAAM,OAAO,OAAO,QAAQ,QAAQ,EAAE;AACtC,UAAM,MAAM,MAAM;AAAA,MAChB,GAAG,IAAI,kBAAkB,mBAAmB,UAAU,CAAC;AAAA,MACvD,EAAE,OAAO,YAAY,OAAO;AAAA,IAC9B;AACA,QAAI,CAAC,IAAI,GAAI,QAAO;AACpB,WAAO,kBAAkB,MAAM,IAAI,KAAK,CAAC;AAAA,EAC3C,QAAQ;AACN,WAAO;AAAA,EACT;AACF;","names":[]}

package/dist/editor-agent/use-converse.d.ts

@@ -0,0 +1,30 @@
+import type { BusinessEvidence, CompanionDomain, ConversationContext, EditSelection } from './contracts';
+import { type ConverseTurnResult } from './converse';
+export interface ConversationMessage {
+    id: string;
+    role: 'user' | 'assistant';
+    content: string;
+    domain?: {
+        domain: CompanionDomain;
+        label: string;
+    };
+    evidence?: BusinessEvidence;
+    clarify?: {
+        question: string;
+        options?: string[];
+    };
+}
+export declare function useConverse({ tenantSlug }: {
+    tenantSlug: string;
+}): {
+    messages: ConversationMessage[];
+    sessionId: string | undefined;
+    streaming: boolean;
+    error: string | undefined;
+    send: ({ prompt, selection, context, }: {
+        prompt: string;
+        selection?: EditSelection;
+        context?: ConversationContext;
+    }) => Promise<ConverseTurnResult>;
+    reset: () => void;
+};