foundry-design-web-adapter 0.2.0-beta.11 → 0.2.0-beta.14

package/README.md

@@ -6,11 +6,19 @@ Foundry is a local-first precision design workbench for Codex, Cursor, and Claud
 
 Foundry is distributed through npm, so testers do not need GitHub access.
 
-> **Current public beta:** `0.2.0-beta.11`. Both npm `latest` and `beta` point to the same tested release. Use the unqualified command below for normal installation.
+> **Release candidate:** `0.2.0-beta.14`. The commands below are prepared for this release and must not be promoted to npm `latest` until the full installation matrix passes.
 
 Full documentation is available at [withfoundry.ai](https://withfoundry.ai).
 
-### Recommended: one command
+### Recommended: install once, use in every project
+
+Install Foundry's shared connection for Codex, Cursor, and Claude once:
+
+```bash
+npx foundry-design install
+```
+
+Restart the selected coding agents once. Then open any project and run:
 
 Open a terminal in the project, or ask Codex, Cursor, or Claude Code to run:
 
@@ -18,7 +26,7 @@ Open a terminal in the project, or ask Codex, Cursor, or Claude Code to run:
 npx foundry-design
 ```
 
-That command detects the project and active coding agent, installs or safely updates Foundry, repairs the shared agent connection, validates its integration, starts the project when needed, and opens the visual session. Before changing local configuration, Foundry prints the exact CLI and MCP bridge versions it will use. On the first installation only, restart the coding agent once so it can load the shared MCP connection. A reviewed batch can be queued before the restart and will be claimed when the agent reconnects.
+That command finds the nearest real project, detects its framework, installs or safely updates only the development adapter and lightweight project connection, validates it, starts the project when needed, and opens the visual session. The agent bridge and skill remain installed once at machine level. Foundry refuses to treat a home folder as a project and prints the exact CLI and MCP bridge versions before changing configuration.
 
 After the restart, reopen the same project folder and ask:
 
@@ -30,16 +38,16 @@ That is the normal workflow. Foundry resumes the most recent session for the cur
 
 ### Manual installation
 
-From the first project you want to inspect, run:
+Install the shared connection for selected agents:
 
 ```bash
-npx foundry-design setup --global
+npx foundry-design install --agent codex,cursor,claude
 ```
 
-For later projects, keep the shared agent connection and install only the development adapter:
+Connect any project with only its development adapter and local project metadata:
 
 ```bash
-npx foundry-design setup --agent none
+npx foundry-design connect
 ```
 
 Then restart the coding agent, reopen the same project folder, and ask:
@@ -48,7 +56,23 @@ Then restart the coding agent, reopen the same project folder, and ask:
 Start Foundry for this project and keep listening for Apply with agent requests.
 ```
 
-You do not need to run a second terminal command when the agent starts Foundry for you. Apply requests remain queued safely when the agent is offline. After an active agent claims a batch, the MCP bridge keeps that handoff alive while the agent inspects source and begins the edit. If the agent process exits, Foundry releases the abandoned claim back to the queue instead of losing it. Run `npx foundry-design doctor --repair` if the connection or generated integration needs repair.
+You do not need to run a second terminal command when the agent starts Foundry for you. Apply requests remain queued safely when the agent is offline. After an active agent claims a batch, the MCP bridge keeps that handoff alive through source edits, rebuilding, and verification. A claim abandoned before source work begins returns to the queue. If the agent disappears during source work, Foundry preserves the same run in **Needs attention** and waits for you to choose **Resume with agent**. It never guesses whether a half-finished edit is safe to repeat.
+
+Check the complete connection at any time with:
+
+```bash
+npx foundry-design status
+```
+
+Foundry reports project integration, the exact MCP package version, runtime health, and the live agent listener separately. Run `npx foundry-design doctor --repair` if configuration or generated integration needs repair.
+
+If an older project has stale or conflicting project-scoped agent configuration, run:
+
+```bash
+npx foundry-design reset
+```
+
+Reset migrates Foundry-owned project MCP files and skills to the shared connection, preserves customized files, and reports anything it could not replace safely.
 
 Update an existing installation with:
 
@@ -56,7 +80,13 @@ Update an existing installation with:
 npx foundry-design update
 ```
 
-The updater refreshes checksum-matched Foundry files, agent connections, and skill bundles. It preserves and reports files changed since setup, validates the project, and rolls back the update if Foundry introduces a TypeScript or lint failure. Restart the coding agent after updating.
+The updater refreshes checksum-matched project files and the shared machine connection. It removes only Foundry-owned legacy project agent files, preserves customized files, validates the project, and rolls back if Foundry introduces a TypeScript or lint failure. Restart the coding agent only when its shared bridge version changes.
+
+Remove a project from Foundry's recent-project list without removing its adapter:
+
+```bash
+npx foundry-design disconnect
+```
 
 Remove only Foundry-managed integration with:
 
@@ -64,15 +94,31 @@ Remove only Foundry-managed integration with:
 npx foundry-design uninstall
 ```
 
+Remove the shared machine connection separately:
+
+```bash
+npx foundry-design uninstall --global
+```
+
+Project-scoped MCP configuration remains available only as an explicit compatibility mode:
+
+```bash
+npx foundry-design setup --project-agent --agent codex
+```
+
 Supported automatic web integration currently includes Next.js App Router, Vite, and plain HTML. Generic web, SwiftUI, and React Native projects receive explicit setup guidance when a safe automatic edit is not available.
 
 The npm setup above is the public beta installation path and includes the same portable skill and MCP connection used by the agent plugin bundle.
 
+### Claude Desktop extension
+
+The repository also produces a validated `.mcpb` extension for Claude Desktop. It bundles the local Foundry MCP bridge and can be installed through **Settings → Extensions → Advanced → Install Extension**. This provides a host-native alternative when a Claude Desktop surface does not merge the normal user-level Claude Code MCP configuration. Project instrumentation is still installed with `npx foundry-design`.
+
 If an npm mirror or existing `npx` cache reports an old tag, bypass it with a temporary cache and the exact current release:
 
 ```bash
 FOUNDRY_NPX_CACHE="$(mktemp -d)"
-npx --yes --prefer-online --registry=https://registry.npmjs.org --cache "$FOUNDRY_NPX_CACHE" --package=foundry-design@0.2.0-beta.11 foundry-design
+npx --yes --prefer-online --registry=https://registry.npmjs.org --cache "$FOUNDRY_NPX_CACHE" --package=foundry-design@0.2.0-beta.14 foundry-design
 ```
 
 The beta supports Node.js 20 or newer. Read the [local-first safety model](https://withfoundry.ai/#safety) before using it with sensitive work.
@@ -87,6 +133,10 @@ Start Foundry for this project.
 
 Foundry remains local-first. Installing the plugin does not create an account, enable telemetry, or send project data to a Foundry service.
 
+### Cursor one-click connection
+
+[Add the Foundry MCP bridge to Cursor](https://cursor.com/link/mcp/install?name=foundry-design-control&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIi0tcHJlZmVyLW9ubGluZSIsImZvdW5kcnktZGVzaWduLW1jcC1zZXJ2ZXJAMC4yLjAtYmV0YS4xNCJdfQ%3D%3D), then run `npx foundry-design` inside the project. The repository's Cursor plugin additionally bundles the Foundry skill and session-start hook for marketplace distribution.
+
 ## Current capabilities
 
 - A dedicated local design workspace with a live product canvas, equal Layers and Inspector docks, and a direct-overlay fallback when a product blocks framing
@@ -105,6 +155,7 @@ Foundry remains local-first. Installing the plugin does not create an account, e
 - Center-workspace review with editable approved batches, grouped targets, and unresolved-target blocking
 - Persistent Apply with agent runs across Codex, Cursor, and Claude Code through MCP
 - Automatically renewed agent handoffs that remain claimed during source inspection and safely return abandoned work to the queue
+- Explicit same-run recovery when an agent disappears during source editing, rebuilding, or verification
 - Live source, rebuild, validation, retry, and rendered-verification progress
 - Rendered verification that resumes after refresh and does not depend on Review remaining open
 - Local MCP bridge for agent access
@@ -123,6 +174,8 @@ pnpm check
 pnpm release:check
 pnpm release:pack
 pnpm release:test-install
+pnpm test:e2e
+pnpm mcpb:build
 pnpm build
 pnpm foundry setup --project /path/to/project --agent codex --local-mcp
 pnpm foundry index --project /path/to/project --output /tmp/foundry-design-graph.json

package/dist/adapter.js

@@ -948,6 +948,43 @@ function createSafeDiagnostics(input) {
   };
 }
 
+// src/apply-run.ts
+var ACTIVE_APPLY_STATES = [
+  "queued",
+  "claimed",
+  "applying",
+  "rebuilding",
+  "verifying"
+];
+function isActiveApplyRun(run) {
+  return ACTIVE_APPLY_STATES.includes(run.state);
+}
+function applyRunAction(run, agentConnected, labels) {
+  if (run.state === "needs_attention" && run.interruptedState) {
+    return { action: "resume", label: "Resume with agent", disabled: false };
+  }
+  if (run.state === "needs_attention" || run.state === "failed") {
+    return { action: "retry", label: "Retry with agent", disabled: false };
+  }
+  if ((run.state === "queued" || run.state === "claimed") && !agentConnected) {
+    return { action: "reconnect", label: "Reconnect agent", disabled: false };
+  }
+  return {
+    action: "status",
+    label: run.state === "passed" ? "Verified" : isActiveApplyRun(run) ? labels[run.state] ?? run.state : "Run complete",
+    disabled: true
+  };
+}
+function applyRunMessage(run, agentConnected) {
+  if (run.state === "queued") {
+    return (run.requeueCount ?? 0) > 0 ? "The previous agent did not begin source work, so Foundry safely returned this batch to the queue." : "The reviewed changes are queued and ready for an active coding agent.";
+  }
+  if (run.state === "claimed") {
+    return agentConnected ? "The agent received this batch. Foundry is keeping the handoff active while source work begins." : "The agent disconnected before source work began. Foundry will return this batch to the queue shortly.";
+  }
+  return run.messages?.at(-1)?.message ?? run.error ?? "Apply run created.";
+}
+
 // src/workspace.ts
 function resolveInterfaceTheme(preference, systemPrefersDark) {
   return preference === "system" ? systemPrefersDark ? "dark" : "light" : preference;
@@ -5388,8 +5425,8 @@ function installFoundryInspector(options = {}) {
   function renderApplyRun(run) {
     const attention = ["needs_attention", "failed"].includes(run.state);
     const passed = run.state === "passed";
-    const active = ["queued", "claimed", "applying", "rebuilding", "verifying"].includes(run.state);
-    const latestMessage = run.state === "queued" ? run.requeueCount > 0 ? "The previous agent did not begin source work, so Foundry safely returned this batch to the queue." : "The reviewed changes are queued and ready for an active coding agent." : run.state === "claimed" ? activeAgentPresence.connected ? "The agent received this batch. Foundry is keeping the handoff active while source work begins." : "The agent disconnected before source work began. Foundry will return this batch to the queue shortly." : run.messages.at(-1)?.message ?? run.error ?? "Apply run created.";
+    const active = isActiveApplyRun(run);
+    const latestMessage = applyRunMessage(run, activeAgentPresence.connected);
     latestApplyState = run.state;
     if (run.state === "passed") completeOnboardingStep("apply");
     captureVerifiedRun(run);
@@ -5399,19 +5436,10 @@ function installFoundryInspector(options = {}) {
     ).join(
       ""
     )}</div>${run.changedFiles.length ? `<div class="run-files"><strong>Changed files</strong>${run.changedFiles.map((file) => `<code>${escapeHtml(file)}</code>`).join("")}</div>` : ""}${run.validationResults.length ? `<div class="result-list">${run.validationResults.map((result) => `<div class="result-row ${result.passed ? "pass" : "fail"}"><span>${result.passed ? "Passed" : "Failed"} \xB7 ${escapeHtml(result.name)}</span><span>${escapeHtml(result.summary ?? "")}</span></div>`).join("")}</div>` : ""}${run.verificationResults.length ? `<div class="result-list">${run.verificationResults.map((result) => `<div class="result-row ${result.passed ? "pass" : "fail"}"><span>${result.passed ? "Matched" : "Mismatch"} \xB7 ${escapeHtml(result.property)}</span><span>${escapeHtml(verificationResultValue(result))}${result.reason ? `<br/>${escapeHtml(result.reason)}` : ""}</span></div>`).join("")}</div>` : ""}`;
-    if (attention) {
-      applyButton.dataset.action = "retry";
-      applyButton.textContent = "Retry with agent";
-      applyButton.disabled = false;
-    } else if (["queued", "claimed"].includes(run.state) && !activeAgentPresence.connected) {
-      applyButton.dataset.action = "reconnect";
-      applyButton.textContent = "Reconnect agent";
-      applyButton.disabled = false;
-    } else {
-      applyButton.dataset.action = "status";
-      applyButton.textContent = passed ? "Verified" : active ? runStateLabels[run.state] ?? run.state : "Run complete";
-      applyButton.disabled = true;
-    }
+    const primaryAction = applyRunAction(run, activeAgentPresence.connected, runStateLabels);
+    applyButton.dataset.action = primaryAction.action;
+    applyButton.textContent = primaryAction.label;
+    applyButton.disabled = primaryAction.disabled;
     const confirmingCancel = active && cancelConfirmationRunId === run.id && Date.now() < cancelConfirmationUntil;
     reviewCancel.dataset.action = active ? "cancel" : "back";
     reviewCancel.textContent = active ? confirmingCancel ? "Confirm stop" : "Stop apply" : "Back";
@@ -5570,6 +5598,21 @@ function installFoundryInspector(options = {}) {
       showToast(error instanceof Error ? error.message : "Could not retry apply run");
     }
   }
+  async function resumeRun() {
+    const run = activeReviewPayload?.applyRuns?.at(-1);
+    if (!run) return;
+    try {
+      renderReviewPayload(
+        await sessionRequest(`/apply-runs/${encodeURIComponent(run.id)}/resume`, {
+          method: "POST",
+          body: "{}"
+        })
+      );
+      showToast("Resume authorized. Waiting for an agent to reinspect this run.");
+    } catch (error) {
+      showToast(error instanceof Error ? error.message : "Could not resume apply run");
+    }
+  }
   async function cancelRun() {
     const run = activeReviewPayload?.applyRuns?.at(-1);
     if (!run) return;
@@ -9206,6 +9249,7 @@ function installFoundryInspector(options = {}) {
   applyButton.addEventListener("click", () => {
     if (applyButton.dataset.action === "apply") void submitReviewedRun();
     if (applyButton.dataset.action === "retry") void retryRun();
+    if (applyButton.dataset.action === "resume") void resumeRun();
     if (applyButton.dataset.action === "reconnect") copyAgentListenerInstruction();
   });
   function handleGlobalShortcuts(event) {

package/dist/apply-run.d.ts

@@ -0,0 +1,19 @@
+export interface ApplyRunView {
+    state: string;
+    interruptedState?: 'applying' | 'rebuilding' | 'verifying';
+    requeueCount?: number;
+    error?: string;
+    messages?: Array<{
+        message: string;
+    }>;
+}
+export interface ApplyRunAction {
+    action: 'resume' | 'retry' | 'reconnect' | 'status';
+    label: string;
+    disabled: boolean;
+}
+export declare const ACTIVE_APPLY_STATES: readonly ["queued", "claimed", "applying", "rebuilding", "verifying"];
+export declare function isActiveApplyRun(run: ApplyRunView): boolean;
+export declare function applyRunAction(run: ApplyRunView, agentConnected: boolean, labels: Record<string, string>): ApplyRunAction;
+export declare function applyRunMessage(run: ApplyRunView, agentConnected: boolean): string;
+//# sourceMappingURL=apply-run.d.ts.map

package/dist/apply-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-run.d.ts","sourceRoot":"","sources":["../src/apply-run.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,CAAC,EAAE,UAAU,GAAG,YAAY,GAAG,WAAW,CAAC;IAC3D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,QAAQ,GAAG,OAAO,GAAG,WAAW,GAAG,QAAQ,CAAC;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,eAAO,MAAM,mBAAmB,uEAMtB,CAAC;AAEX,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAE3D;AAED,wBAAgB,cAAc,CAC5B,GAAG,EAAE,YAAY,EACjB,cAAc,EAAE,OAAO,EACvB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,cAAc,CAoBhB;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,YAAY,EAAE,cAAc,EAAE,OAAO,GAAG,MAAM,CAYlF"}

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAgHA,MAAM,WAAW,uBAAuB;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,0BAA0B;IACzC,OAAO,IAAI,IAAI,CAAC;IAChB,cAAc,IAAI,IAAI,CAAC;IACvB,MAAM,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IACnC,OAAO,IAAI,IAAI,CAAC;CACjB;AA4lCD,wBAAgB,uBAAuB,CACrC,OAAO,GAAE,uBAA4B,GACpC,0BAA0B,CA2jP5B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAiHA,MAAM,WAAW,uBAAuB;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,0BAA0B;IACzC,OAAO,IAAI,IAAI,CAAC;IAChB,cAAc,IAAI,IAAI,CAAC;IACvB,MAAM,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IACnC,OAAO,IAAI,IAAI,CAAC;CACjB;AA4lCD,wBAAgB,uBAAuB,CACrC,OAAO,GAAE,uBAA4B,GACpC,0BAA0B,CAsjP5B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foundry-design-web-adapter",
-  "version": "0.2.0-beta.11",
+  "version": "0.2.0-beta.14",
   "description": "Development-only browser inspector for Foundry",
   "type": "module",
   "main": "dist/adapter.js",