import{CodeBlock as o}from"@contractspec/lib.design-system";import r from"@contractspec/lib.ui-link";import{ChevronRight as n}from"lucide-react";import{jsx as e,jsxs as t}from"react/jsx-runtime";var i=["builder.workspace.bootstrap","builder.channel.receiveInbound","builder.blueprint.generate","builder.plan.compile","builder.preview.create","builder.preview.runHarness","builder.export.prepare","builder.export.approve","builder.export.execute"],s=["local runtime trust and lease details","channel-action posture for mobile/operator follow-up","comparison posture and export readiness from the shared snapshot"];function c(){return t("div",{className:"space-y-8",children:[t("div",{className:"space-y-3",children:[e("h1",{className:"font-bold text-4xl",children:"Host the Builder workbench"}),e("p",{className:"text-lg text-muted-foreground",children:"Use the reusable Builder workbench as the desktop control surface for snapshot loading, guided authoring, preview, readiness, export, and mobile review handoff."})]}),t("div",{className:"card-subtle space-y-4 p-6",children:[e("h2",{className:"font-bold text-2xl",children:"What you'll build"}),t("ul",{className:"space-y-2 text-muted-foreground text-sm",children:[e("li",{children:"A workspace snapshot fetch path."}),e("li",{children:"A `BuilderWorkbench` host with action callbacks."}),e("li",{children:"Runtime-mode aware preview/export controls plus mobile review links."})]})]}),t("div",{className:"space-y-6",children:[t("div",{className:"space-y-3",children:[e("h2",{className:"font-bold text-2xl",children:"1) Fetch the workspace snapshot"}),e("p",{className:"text-muted-foreground text-sm",children:"The web shell already exposes a query path for the current Builder workspace snapshot. Your host should load it first, then refresh it after each successful command."}),e(o,{language:"typescript",filename:"builder-workbench-controller.ts",code:`export async function fetchBuilderSnapshot(workspaceId: string) {
  const response = await fetch(
    \`/api/operate/builder/queries/builder.workspace.snapshot?workspaceId=\${encodeURIComponent(workspaceId)}\`,
    { cache: "no-store" }
  );
  if (!response.ok) {
    throw new Error("Failed to fetch Builder workspace snapshot.");
  }
  const payload = await response.json() as {
    ok: boolean;
    result: BuilderWorkspaceSnapshot;
  };
  if (!payload.ok) {
    throw new Error("Builder workspace snapshot query returned an error.");
  }
  return payload.result;
}`}),e("p",{className:"text-muted-foreground text-sm",children:"Expected output: one `BuilderWorkspaceSnapshot` containing workspace, plan, providers, runtime targets, preview, export, mobile review state, and the operator posture needed for local trust, lease, and comparison status."})]}),t("div",{className:"space-y-3",children:[e("h2",{className:"font-bold text-2xl",children:"2) Host the workbench and refresh on action"}),e("p",{className:"text-muted-foreground text-sm",children:"The simplest host pattern is local state plus a small action wrapper that executes one Builder command and then refreshes the snapshot."}),e(o,{language:"tsx",filename:"BuilderWorkbenchHost.tsx",code:`import {
  BuilderWorkbench,
  useBuilderWorkbenchState,
} from "@contractspec/module.builder-workbench/presentation";

const { snapshot, setSnapshot, promptDraft, setPromptDraft } =
  useBuilderWorkbenchState({
    workspace: initialSnapshot.workspace,
    initialSnapshot,
  });

async function runAction(commandKey: string, payload?: Record<string, unknown>) {
  await executeBuilderCommand({ commandKey, workspaceId, payload });
  setSnapshot(await fetchBuilderSnapshot(workspaceId));
}

<BuilderWorkbench
  snapshot={snapshot}
  promptDraft={promptDraft}
  onPromptDraftChange={setPromptDraft}
  onCapturePrompt={() =>
    runAction("builder.channel.receiveInbound", createPromptEnvelope(workspaceId, promptDraft))
  }
  onGenerateBlueprint={() => runAction("builder.blueprint.generate")}
  onCompilePlan={() => runAction("builder.plan.compile")}
  onCreatePreview={() => runAction("builder.preview.create", { runtimeMode: "hybrid" })}
  onRunReadiness={() => runAction("builder.preview.runHarness")}
  onPrepareExport={() => runAction("builder.export.prepare", { runtimeMode: "hybrid" })}
  onApproveExport={() => runAction("builder.export.approve")}
  onExecuteExport={() => runAction("builder.export.execute")}
  selectedExportRuntimeMode="hybrid"
/>;`}),e("p",{className:"text-muted-foreground text-sm",children:"Expected output: each successful action leaves the host with a fresh snapshot and keeps the workbench tabs aligned with current runtime state."})]}),t("div",{className:"space-y-3",children:[e("h2",{className:"font-bold text-2xl",children:"3) Persist Builder defaults in workspace config"}),e("p",{className:"text-muted-foreground text-sm",children:"The host should agree with the CLI and setup flows on the same control-plane defaults. For local or hybrid setups, keep the Builder API base URL, token env var, and local runtime metadata in `.contractsrc.json`."}),e(o,{language:"json",filename:".contractsrc.json",code:`{
  "builder": {
    "enabled": true,
    "runtimeMode": "local",
    "bootstrapPreset": "local_daemon_mvp",
    "api": {
      "baseUrl": "https://api.contractspec.io",
      "controlPlaneTokenEnvVar": "CONTROL_PLANE_API_TOKEN"
    },
    "localRuntime": {
      "runtimeId": "rt_local_daemon",
      "grantedTo": "local:operator",
      "providerIds": ["provider.codex", "provider.local.model"]
    }
  }
}`})]}),t("div",{className:"space-y-3",children:[e("h2",{className:"font-bold text-2xl",children:"4) Bootstrap providers and routing policy explicitly"}),e("p",{className:"text-muted-foreground text-sm",children:"Builder v3 treats provider routing as policy, not heuristic. Use the workspace bootstrap command as the single managed-first setup path instead of orchestrating provider registration in the app shell."}),e(o,{language:"typescript",filename:"builder-bootstrap.ts",code:`await executeBuilderCommand({
  commandKey: "builder.workspace.bootstrap",
  workspaceId,
  payload: {
    preset: "managed_mvp",
    includeLocalHelperProvider: true,
  },
});`})]}),t("div",{className:"card-subtle space-y-3 p-6",children:[e("h3",{className:"font-semibold text-lg",children:"Common command keys"}),e("ul",{className:"space-y-2 text-muted-foreground text-sm",children:i.map((a)=>e("li",{children:e("code",{children:a})},a))})]}),t("div",{className:"card-subtle space-y-3 p-6",children:[e("h3",{className:"font-semibold text-lg",children:"Snapshot-backed operator details"}),e("ul",{className:"space-y-2 text-muted-foreground text-sm",children:s.map((a)=>e("li",{children:a},a))})]}),t("div",{className:"space-y-3",children:[e("h2",{className:"font-bold text-2xl",children:"5) Keep runtime mode explicit"}),e("p",{className:"text-muted-foreground text-sm",children:"Preview and export flows are runtime-mode aware. The host chooses between `managed`, `local`, and `hybrid` and passes that choice into preview or export commands instead of hiding it behind provider selection heuristics."}),e(o,{language:"typescript",filename:"runtime-mode",code:`const [selectedExportRuntimeMode, setSelectedExportRuntimeMode] =
  React.useState(resolveBuilderExportRuntimeMode(initialSnapshot));

await executeBuilderCommand({
  commandKey: "builder.preview.create",
  workspaceId,
  payload: {
    runtimeMode: selectedExportRuntimeMode,
  },
	});`})]}),t("div",{className:"space-y-3",children:[e("h2",{className:"font-bold text-2xl",children:"6) Link mobile review flows"}),e("p",{className:"text-muted-foreground text-sm",children:"When a patch proposal, approval ticket, or incident needs operator follow-up away from the desktop workbench, deep-link into the mobile review route instead of inventing a separate data model."}),e(o,{language:"typescript",filename:"mobile-review-path.ts",code:`export function buildBuilderMobileReviewPath(
  workspaceId: string,
  cardId: string
) {
  return \`/operate/builder/workspaces/\${encodeURIComponent(workspaceId)}/mobile-review/\${encodeURIComponent(cardId)}\`;
}`}),e("p",{className:"text-muted-foreground text-sm",children:"Expected output: the same Builder workspace state stays visible from desktop workbench and mobile review surfaces."})]}),t("div",{className:"space-y-3",children:[e("h2",{className:"font-bold text-2xl",children:"7) Keep Connect adjacent, not embedded"}),e("p",{className:"text-muted-foreground text-sm",children:"Builder owns the authoring control plane. When Builder delegates into coding repositories, enable Connect in those target workspaces for context packs, mutation verification, replay, and review packets, but do not replace Builder contracts with Connect artifacts."}),e(o,{language:"bash",filename:"connect-init.sh",code:"contractspec connect init --scope workspace"})]})]}),t("div",{className:"flex items-center gap-4 pt-4",children:[t(r,{href:"/docs/specs/builder-control-plane",className:"btn-primary",children:["Back to Builder control plane ",e(n,{size:16})]}),e(r,{href:"/docs/studio",className:"btn-ghost",children:"Studio overview"})]})]})}export{c as GuideHostBuilderWorkbenchPage};
