diff --git a/packages/webui/docs/adr/0020-webui-miniapp-view-and-runtime-seams.md b/packages/webui/docs/adr/0020-webui-miniapp-view-and-runtime-seams.md
index 326e9dddb..b8b10897f 100644
--- a/packages/webui/docs/adr/0020-webui-miniapp-view-and-runtime-seams.md
+++ b/packages/webui/docs/adr/0020-webui-miniapp-view-and-runtime-seams.md
@@ -326,6 +326,13 @@ An absent session is reported as `none`; no session lookup or ended-session noti
A runtime that stops while the tab is open clears the view and reports the stop reason; it does not
restart the Mini App, because the tab may be unattended and a retry would start work the user did not
ask for. A retry is a user action.
+A failed start leaves an actionable “not opened” state in the mounted view, alongside the
+attempt's error toast. Dismissing the toast does not remove the state or its explicit retry
+control. Only an `OWNED_ELSEWHERE` refusal tells the user to close the other client's app;
+a generic preparation failure does not establish ownership. Retry uses the normal open
+operation, never a takeover, and polling does not restart a failed presentation. Stop or
+lease failures do not create this failed-start state.
+
### The standalone presentation is a lease
diff --git a/packages/webui/src/client/features/miniapp/application/miniapp-workflows.ts b/packages/webui/src/client/features/miniapp/application/miniapp-workflows.ts
index 07831a6da..c70740dbe 100644
--- a/packages/webui/src/client/features/miniapp/application/miniapp-workflows.ts
+++ b/packages/webui/src/client/features/miniapp/application/miniapp-workflows.ts
@@ -81,10 +81,12 @@ const MINIAPP_PRESENTATION_RECONNECT_GRACE_MS = 300;
* `open` carries the proxy's view URL and nothing else — not the Mini App's
* origin, not its surface path, not the credential its guard demands. `stopped`
* is a cleared view that remembers why, which is what the panel renders instead
- * of a dead frame.
+ * of a dead frame. `failed` retains an unsuccessful start until the person
+ * retries; a stop or lease failure cannot create that state.
*/
export type WebuiMiniAppPresentation =
| { readonly kind: "opening" }
+ | { readonly kind: "failed"; readonly refusal: WebuiMiniAppRefusal }
| {
readonly kind: "open";
readonly viewUrl: string;
@@ -663,7 +665,7 @@ export function createWebuiMiniAppWorkflows(deps: {
} catch (error) {
if (!isCurrent()) return false;
const refusal = refusalOf(error);
- setPresentation(pluginId, undefined);
+ setPresentation(pluginId, { kind: "failed", refusal });
setRefusal(pluginId, refusal);
// The runtime refused to start, so the row it refused about is stale: a
// capacity refusal names the running apps, and those names come from here.
@@ -873,7 +875,7 @@ export function createWebuiMiniAppWorkflows(deps: {
const existing = current.presentations[pluginId];
if (existing?.kind === "opening") return "presented";
// A cleared presentation or a refusal is the person's to retry, never a timer's.
- if (existing?.kind === "stopped" || current.refusals[pluginId] !== undefined) return "blocked";
+ if (existing?.kind === "stopped" || existing?.kind === "failed" || current.refusals[pluginId] !== undefined) return "blocked";
let catalogue: WebuiMiniAppCatalogue | undefined;
try {
catalogue = observed ? observed.catalogue : await readCatalogue();
diff --git a/packages/webui/src/client/features/miniapp/ui/MiniAppView.public.tsx b/packages/webui/src/client/features/miniapp/ui/MiniAppView.public.tsx
index 27f0621be..6a8e7b3c2 100644
--- a/packages/webui/src/client/features/miniapp/ui/MiniAppView.public.tsx
+++ b/packages/webui/src/client/features/miniapp/ui/MiniAppView.public.tsx
@@ -80,7 +80,7 @@ import {
import { sessionHash } from "../../../projection/common/router.js";
import { FeedbackLiveRegion } from "../../../ui/feedback.js";
import { useWebuiToastError } from "../../../ui/toast.js";
-import { WebuiIconButton } from "../../../ui/button.js";
+import { WebuiButton, WebuiIconButton } from "../../../ui/button.js";
import { WebuiSkeletonProjection } from "../../../ui/page.js";
import { FeedbackEmpty } from "../../../ui/feedback.js";
import {
@@ -739,6 +739,23 @@ export function MiniAppView({
) : null}
+ {presentation?.kind === "failed" && !detached ? (
+ // The toast reports the attempt; this state remains until another
+ // explicit open succeeds. Polling must never restart a failed app.
+
+ workflows?.open(pluginId)}
+ >重试打开应用}
+ />
+
+ ) : null}
{detached ? (
{
+ ${refusal ? `window.__fixture.refuseOperation("openMiniApp", ${JSON.stringify(refusal.code)}, ${JSON.stringify(refusal.message)});` : ""}
window.__fixture.setResponse("listMiniApps", {
miniApps: [${JSON.stringify(catalogueRow(false, 0))}],
});
@@ -191,3 +192,49 @@ test("a deep link naming a session that has ended still shows the Mini App", asy
// Still no way back inline.
await expect(page.getByTestId("miniapp-switch-standalone")).toHaveCount(0);
});
+
+for (const [code, message] of [
+ ["MINIAPP_PREPARATION_FAILED", "Mini App publication preparation failed"],
+ ["OWNED_ELSEWHERE", "Mini App is running in another client"],
+]) {
+ test(`a standalone start refusal stays actionable and an explicit retry recovers (${code})`, async ({ page }) => {
+ await configureDocuments(page, { code, message });
+ await page.goto(`/miniapp?token=synthetic-token&plugin=${PLUGIN}`);
+ const failed = page.getByTestId("miniapp-view-start-failed");
+ await expect(failed).toBeVisible();
+ await expect(failed).toContainText("应用尚未打开");
+ if (code === "OWNED_ELSEWHERE") {
+ await expect(failed).toContainText("请先在其他客户端关闭该应用,再重试。");
+ } else {
+ await expect(failed).toContainText(message);
+ await expect(failed).not.toContainText("请先在其他客户端关闭");
+ }
+ await expect(page.getByTestId("miniapp-view-frame")).toHaveCount(0);
+ await page.getByTestId("miniapp-view-refusal").getByRole("button", { name: "关闭", exact: true }).click();
+ await expect(failed).toBeVisible();
+ // A repeated refusal keeps the recovery control instead of erasing the page.
+ const retry = page.getByRole("button", { name: "重试打开应用" });
+ await retry.click();
+ await expect(failed).toBeVisible();
+ await expect.poll(() => page.evaluate(() => window.__fixture.requests.filter(
+ (request) => request.operation === "openMiniApp",
+ ).length)).toBe(2);
+ await page.evaluate(() => {
+ window.__fixture.allowOperation("openMiniApp");
+ window.__fixture.delayNext("openMiniApp", {});
+ });
+ await retry.click();
+ await expect(page.getByTestId("miniapp-view-opening")).toBeVisible();
+ await expect(retry).toHaveCount(0);
+ await expect(failed).toHaveCount(0);
+ await page.evaluate(({ pluginId, path }) => window.__fixture.resolve("openMiniApp", {}, {
+ pluginId, viewUrl: window.location.origin + path,
+ }), { pluginId: PLUGIN, path: STANDALONE_STUB });
+ await expect(page.getByTestId("miniapp-view-frame")).toBeVisible();
+ await expect(failed).toHaveCount(0);
+ await expect(retry).toHaveCount(0);
+ expect(await page.evaluate(() => window.__fixture.requests.filter(
+ (request) => request.operation === "openMiniApp",
+ ).length)).toBe(3);
+ });
+}
diff --git a/packages/webui/test/unit/miniapp-client-state.test.ts b/packages/webui/test/unit/miniapp-client-state.test.ts
index 7c2aedd7a..02f18c081 100644
--- a/packages/webui/test/unit/miniapp-client-state.test.ts
+++ b/packages/webui/test/unit/miniapp-client-state.test.ts
@@ -385,7 +385,7 @@ describe("the Mini App business", () => {
// Keep diagnostics while presenting a neutral client name.
expect(text).not.toContain("electron");
expect(text).toContain("4242");
- expect(snapshot.presentations["shared-app"]).toBeUndefined();
+ expect(snapshot.presentations["shared-app"]).toEqual({ kind: "failed", refusal });
});
it("offers to stop a Mini App another client is running", () => {
diff --git a/packages/webui/test/unit/miniapp-surfaces.test.tsx b/packages/webui/test/unit/miniapp-surfaces.test.tsx
index 8d758317f..2201f899a 100644
--- a/packages/webui/test/unit/miniapp-surfaces.test.tsx
+++ b/packages/webui/test/unit/miniapp-surfaces.test.tsx
@@ -11,8 +11,9 @@
// The failures and the confirmations are said through the shared toast (ADR
// 0030), which is raised in an effect and drawn over the page: a server render
// never sees it. So what a case pins about a failure here is that the layout
-// does not carry it — and, from the surfaces' own sources, that it is still
-// reported at all.
+// does not carry transient errors — and, from the surfaces' own sources, that
+// they are still reported at all. A failed start additionally leaves a persistent
+// not-opened state with an explicit recovery control.
//
// The registry half is real: an actual upstream `http.Server`, an actual listener,
// and a close that has to free its port — because the whole reason it exists is
@@ -439,7 +440,7 @@ describe("the Mini App view the panel frames", () => {
expect(opens).toBe(1);
});
- it("reports the refusal through the toast, and shows no frame", async () => {
+ it("keeps an actionable state after another client refuses the start", async () => {
const workflows = createWebuiMiniAppWorkflows({
port: port({
miniApps: [summary("shared", "stopped")],
@@ -456,14 +457,59 @@ describe("the Mini App view the panel frames", () => {
createElement(MiniAppView, { pluginId: "shared", sessionId: "session-1" }),
workflows,
);
- // The refusal is an event, not a state: it is said once, through the shared
- // toast (ADR 0030). A server render never sees it.
+ // The toast reports the attempt; the retained state gives a safe next step
+ // without repeating the other process's details.
expect(markup).not.toContain("pid 99");
expect(markup).not.toContain("electron");
expect(markup).not.toContain("miniapp-view-frame");
// The view itself still renders, so there is a surface to look at.
expect(markup).toContain('data-testid="miniapp-view"');
- expect(markup).toContain('data-state="idle"');
+ expect(markup).toContain("应用尚未打开");
+ expect(markup).toContain("请先在其他客户端关闭该应用,再重试。");
+ expect(markup).toContain("重试打开应用");
+ });
+
+ it("does not offer a start retry for a refused stop without a presentation", async () => {
+ const workflows = createWebuiMiniAppWorkflows({
+ port: port({
+ miniApps: [summary("shared", "running")],
+ stop: async () => { throw new Error("Stop was refused"); },
+ }),
+ });
+ await workflows.stop("shared");
+ const markup = render(createElement(MiniAppView, { pluginId: "shared" }), workflows);
+ expect(workflows.getSnapshot().refusals.shared?.message).toBe("Stop was refused");
+ expect(markup).not.toContain("应用尚未打开");
+ expect(markup).not.toContain("重试打开应用");
+ });
+
+ it("retains a preparation failure until an explicit retry succeeds", async () => {
+ let succeeds = false;
+ const workflows = createWebuiMiniAppWorkflows({
+ port: port({
+ miniApps: [summary("shared", "stopped")],
+ open: async () => {
+ if (!succeeds) throw Object.assign(new Error("Mini App publication preparation failed"), {
+ code: "MINIAPP_PREPARATION_FAILED",
+ });
+ return { pluginId: "shared", viewUrl: "http://127.0.0.1:49152" };
+ },
+ }),
+ });
+ await workflows.open("shared");
+ const view = createElement(MiniAppView, { pluginId: "shared", surface: "standalone" });
+ const failed = render(view, workflows);
+ expect(failed).toContain("应用尚未打开");
+ expect(failed).toContain("Mini App publication preparation failed");
+ expect(failed).toContain("重试打开应用");
+ expect(failed).not.toContain("请先在其他客户端关闭");
+ expect(failed).not.toContain("miniapp-view-frame");
+ succeeds = true;
+ await workflows.open("shared");
+ const recovered = render(view, workflows);
+ expect(recovered).toContain("miniapp-view-frame");
+ expect(recovered).not.toContain("应用尚未打开");
+ expect(recovered).not.toContain("重试打开应用");
});
});
diff --git a/scripts/lib/webui-presentation-inventory.json b/scripts/lib/webui-presentation-inventory.json
index 0277d7b29..637f33383 100644
--- a/scripts/lib/webui-presentation-inventory.json
+++ b/scripts/lib/webui-presentation-inventory.json
@@ -213,7 +213,7 @@
"features/miniapp/ui/MiniAppPicker.public.tsx": "7b631ebd095435d5",
"features/miniapp/ui/MiniAppStandalone.public.tsx": "cb4684d8ffa3f32f",
"features/miniapp/ui/MiniAppToolApprovals.public.tsx": "a123d341198a1b26",
- "features/miniapp/ui/MiniAppView.public.tsx": "7245af70ea92ed94",
+ "features/miniapp/ui/MiniAppView.public.tsx": "92707a60570eba49",
"features/models/ui/ModelEffortSlider.tsx": "4b36ea2127bcc1c3",
"features/models/ui/ModelListPanel.tsx": "9be8a8e124de5e7e",
"features/models/ui/ModelPanel.tsx": "8f68051cc0c54706",