feat(reliability): error boundaries + cancellation + retry + iframe error reporting (#11)

Adds the seven reliability gaps tracked in
docs/research/09-polish-parity-backlog.md:

C1  App-shell React error boundary with Reload + Copy stack actions
C2  Per-pane boundaries (Sidebar / Preview / TopBar) so a single crash
    never blanks the window
C5  AbortController threaded through core.generate -> providers.complete
    -> pi-ai signal; renderer races IPC against abort and shows Cancel
    button while generating
C6  completeWithRetry wrapper in packages/providers: max 3 attempts,
    base 500ms with +/-20% jitter, retries only 5xx / network /
    429-with-Retry-After. Every attempt is surfaced via onRetry — no
    silent retries (PRINCIPLES §10)
C7  429 rate-limit handling: parse Retry-After, store rateLimitedUntil,
    show "Rate limited until HH:MM:SS" toast with countdown
C10 Sandbox iframe error reporting: overlay.ts catches window.error +
    unhandledrejection and postMessages IFRAME_ERROR; surfaced as a
    slim red CanvasErrorBar above the iframe
C11 Overlay defense: setInterval(reattach, 200) re-installs listeners
    in case generated HTML strips them; capture-phase listeners

New files:
  packages/providers/src/retry.ts (+12 vitest cases in retry.test.ts)
  packages/runtime/src/iframe-errors.ts
  apps/desktop/src/renderer/src/components/ErrorBoundary.tsx
  apps/desktop/src/renderer/src/components/CanvasErrorBar.tsx

No new prod dependencies. Tier 1 — no animations, no new libraries.
All UI uses var(--color-*) tokens.

Signed-off-by: hqhq1025 <1506751656@qq.com>

Author: hqhq1025

apps/desktop/src/renderer/src/components/CanvasErrorBar.tsx

@@ -0,0 +1,43 @@
+/**
+ * CanvasErrorBar — slim red strip shown above the preview iframe when the
+ * sandbox runtime postMessages an IFRAME_ERROR.
+ *
+ * Loud surface (PRINCIPLES §10): every JS exception thrown inside the
+ * generated HTML lands here with file + line. Users can dismiss the bar
+ * (it clears the store slice) but errors are never auto-hidden.
+ */
+
+import { X } from 'lucide-react';
+import { useCodesignStore } from '../store';
+
+export function CanvasErrorBar() {
+  const errors = useCodesignStore((s) => s.iframeErrors);
+  const clear = useCodesignStore((s) => s.clearIframeErrors);
+  if (errors.length === 0) return null;
+  const latest = errors[errors.length - 1];
+  if (!latest) return null;
+  return (
+    <div
+      role="alert"
+      className="flex items-start gap-3 px-4 py-2 border-b border-[var(--color-border)] bg-[color-mix(in_srgb,var(--color-error)_10%,var(--color-background))] text-[var(--color-text-primary)]"
+    >
+      <span className="mt-0.5 inline-block w-2 h-2 rounded-full bg-[var(--color-error)] shrink-0" />
+      <div className="flex-1 min-w-0">
+        <div className="text-xs font-semibold uppercase tracking-wide text-[var(--color-error)]">
+          Preview runtime error{errors.length > 1 ? ` (${errors.length})` : ''}
+        </div>
+        <div className="text-sm text-[var(--color-text-primary)] truncate" title={latest}>
+          {latest}
+        </div>
+      </div>
+      <button
+        type="button"
+        onClick={clear}
+        aria-label="Dismiss preview errors"
+        className="shrink-0 p-1 rounded-[var(--radius-md)] text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] hover:bg-[var(--color-surface-hover)] transition-colors"
+      >
+        <X className="w-4 h-4" />
+      </button>
+    </div>
+  );
+}

apps/desktop/src/renderer/src/components/ErrorBoundary.tsx

@@ -0,0 +1,119 @@
+/**
+ * Generic React error boundary.
+ *
+ * Strategy (PRINCIPLES §10): never silently swallow render exceptions.
+ * If a child throws we render an actionable card with:
+ *   - the error message (loud, not hidden in console)
+ *   - "Reload" — re-mounts the children by bumping a key
+ *   - "Copy stack" — puts message+stack into the clipboard for bug reports
+ *
+ * Used both at the app shell (whole renderer) and per-pane (sidebar /
+ * preview / topbar) so a single crash never blanks the entire window.
+ */
+
+import { Button } from '@open-codesign/ui';
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+
+export interface ErrorBoundaryProps {
+  children: ReactNode;
+  /** Human-readable label used in the fallback heading: "Sidebar crashed". */
+  scope?: string;
+  /**
+   * Optional custom fallback. Receives the error and a `reset` callback
+   * that re-mounts the boundary's children.
+   */
+  fallback?: (args: { error: Error; reset: () => void }) => ReactNode;
+}
+
+interface ErrorBoundaryState {
+  error: Error | null;
+  resetKey: number;
+}
+
+export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  override state: ErrorBoundaryState = { error: null, resetKey: 0 };
+
+  static getDerivedStateFromError(error: Error): Partial<ErrorBoundaryState> {
+    return { error };
+  }
+
+  override componentDidCatch(error: Error, info: ErrorInfo): void {
+    // Loud surface: also log so devtools shows the boundary that caught it.
+    // Tier-1 — no remote reporting, BYOK / local-first.
+    console.error(`[ErrorBoundary:${this.props.scope ?? 'root'}]`, error, info.componentStack);
+  }
+
+  reset = (): void => {
+    this.setState((s) => ({ error: null, resetKey: s.resetKey + 1 }));
+  };
+
+  copyStack = async (): Promise<void> => {
+    const err = this.state.error;
+    if (!err) return;
+    const text = `${err.name}: ${err.message}\n\n${err.stack ?? '(no stack)'}`;
+    try {
+      await navigator.clipboard.writeText(text);
+    } catch {
+      // Clipboard may be blocked in the sandbox; surface a textarea fallback
+      // so the user can still grab the text instead of failing silently.
+      const ta = document.createElement('textarea');
+      ta.value = text;
+      ta.style.position = 'fixed';
+      ta.style.opacity = '0';
+      document.body.appendChild(ta);
+      ta.select();
+      try {
+        document.execCommand('copy');
+      } finally {
+        ta.remove();
+      }
+    }
+  };
+
+  override render(): ReactNode {
+    const { error, resetKey } = this.state;
+    if (!error) {
+      // Use resetKey to force remount of children after reset.
+      return <ErrorBoundaryChildren key={resetKey}>{this.props.children}</ErrorBoundaryChildren>;
+    }
+    if (this.props.fallback) {
+      return this.props.fallback({ error, reset: this.reset });
+    }
+    const scope = this.props.scope ?? 'this view';
+    return (
+      <div className="h-full w-full flex items-center justify-center p-6 bg-[var(--color-background)]">
+        <div className="max-w-md w-full rounded-[var(--radius-2xl)] border border-[var(--color-border)] bg-[var(--color-surface)] shadow-[var(--shadow-card)] p-6">
+          <div className="text-xs uppercase tracking-wide text-[var(--color-error)] font-semibold mb-2">
+            {scope} crashed
+          </div>
+          <h2 className="text-lg font-semibold text-[var(--color-text-primary)] mb-1">
+            {error.name}: {error.message}
+          </h2>
+          <p className="text-sm text-[var(--color-text-secondary)] mb-4">
+            The rest of the app is still running. Reload this view, or copy the stack to file a bug.
+          </p>
+          <pre className="text-[11px] leading-snug font-mono text-[var(--color-text-muted)] bg-[var(--color-surface-active)] border border-[var(--color-border-muted)] rounded-[var(--radius-md)] p-3 max-h-40 overflow-auto whitespace-pre-wrap">
+            {error.stack ?? '(no stack)'}
+          </pre>
+          <div className="mt-4 flex gap-2 justify-end">
+            <Button
+              type="button"
+              variant="secondary"
+              size="md"
+              onClick={() => void this.copyStack()}
+            >
+              Copy stack
+            </Button>
+            <Button type="button" size="md" onClick={this.reset}>
+              Reload
+            </Button>
+          </div>
+        </div>
+      </div>
+    );
+  }
+}
+
+function ErrorBoundaryChildren({ children }: { children: ReactNode }): ReactNode {
+  return children;
+}

packages/core/src/generate.test.ts

@@ -6,6 +6,13 @@ const completeMock = vi.fn();
 
 vi.mock('@open-codesign/providers', () => ({
   complete: (...args: unknown[]) => completeMock(...args),
+  completeWithRetry: (
+    _model: unknown,
+    _messages: unknown,
+    _opts: unknown,
+    _retryOpts: unknown,
+    impl: (...args: unknown[]) => unknown,
+  ) => impl(_model, _messages, _opts),
 }));
 
 import { generate } from './index';

packages/core/src/index.ts

@@ -1,5 +1,5 @@
 import { type ArtifactEvent, createArtifactParser } from '@open-codesign/artifacts';
-import { complete } from '@open-codesign/providers';
+import { type RetryReason, complete, completeWithRetry } from '@open-codesign/providers';
 import type { Artifact, ChatMessage, ModelRef } from '@open-codesign/shared';
 import { CodesignError } from '@open-codesign/shared';
 import { SYSTEM_PROMPTS } from '@open-codesign/templates';
@@ -11,6 +11,10 @@ export interface GenerateInput {
   apiKey: string;
   baseUrl?: string;
   systemPrompt?: string;
+  /** Optional cancellation. Threaded through to pi-ai. */
+  signal?: AbortSignal;
+  /** Surfaced for every retry attempt — never silent (PRINCIPLES §10). */
+  onRetry?: (info: RetryReason) => void;
 }
 
 export interface GenerateOutput {
@@ -46,7 +50,9 @@ function collect(events: Iterable<ArtifactEvent>, into: Collected): void {
 /**
  * Generate one design artifact in response to a user prompt.
  * Tier 1: blocking call, returns the parsed artifact list at the end.
- * Tier 2 will switch to streaming with intermediate events.
+ * Wraps the provider call in `completeWithRetry` so transient 5xx/429/network
+ * failures retry with backoff. Caller passes `signal` to cancel and `onRetry`
+ * to surface retry attempts in the UI.
  */
 export async function generate(input: GenerateInput): Promise<GenerateOutput> {
   if (!input.prompt.trim()) {
@@ -59,10 +65,19 @@ export async function generate(input: GenerateInput): Promise<GenerateOutput> {
     { role: 'user', content: input.prompt },
   ];
 
-  const result = await complete(input.model, messages, {
-    apiKey: input.apiKey,
-    ...(input.baseUrl !== undefined ? { baseUrl: input.baseUrl } : {}),
-  });
+  const result = await completeWithRetry(
+    input.model,
+    messages,
+    {
+      apiKey: input.apiKey,
+      ...(input.baseUrl !== undefined ? { baseUrl: input.baseUrl } : {}),
+      ...(input.signal !== undefined ? { signal: input.signal } : {}),
+    },
+    {
+      ...(input.onRetry !== undefined ? { onRetry: input.onRetry } : {}),
+    },
+    complete,
+  );
 
   const parser = createArtifactParser();
   const collected: Collected = { text: '', artifacts: [] };

packages/providers/src/index.ts

@@ -101,6 +101,9 @@ export function detectProviderFromKey(key: string): ModelRef['provider'] | null
 export { pingProvider } from './validate';
 export type { ValidateResult } from './validate';
 
+export { completeWithRetry, classifyError, sleepWithAbort } from './retry';
+export type { CompleteWithRetryOptions, RetryReason } from './retry';
+
 // Tier 2 surface (not yet implemented):
 //   structuredComplete<T>(model, schema, messages, opts): Promise<T>
 //   streamArtifacts(model, messages, opts): AsyncIterable<ArtifactEvent>

packages/providers/src/retry.test.ts

@@ -0,0 +1,118 @@
+import { type ChatMessage, CodesignError, type ModelRef } from '@open-codesign/shared';
+import { describe, expect, it, vi } from 'vitest';
+import type { GenerateOptions, GenerateResult } from './index';
+import { type RetryReason, classifyError, completeWithRetry } from './retry';
+
+const MODEL: ModelRef = { provider: 'anthropic', modelId: 'claude-sonnet-4-6' };
+const MESSAGES: ChatMessage[] = [{ role: 'user', content: 'hi' }];
+const OPTS: GenerateOptions = { apiKey: 'test-key' };
+
+const ok: GenerateResult = { content: 'hello', inputTokens: 1, outputTokens: 1, costUsd: 0 };
+
+class HttpError extends Error {
+  constructor(
+    message: string,
+    public readonly status: number,
+    public readonly headers?: Record<string, string>,
+  ) {
+    super(message);
+    this.name = 'HttpError';
+  }
+}
+
+describe('classifyError', () => {
+  it('marks 5xx as retryable', () => {
+    expect(classifyError(new HttpError('boom', 503))).toMatchObject({ retry: true });
+  });
+  it('marks 4xx (non-429) as non-retryable', () => {
+    expect(classifyError(new HttpError('bad', 400))).toMatchObject({ retry: false });
+  });
+  it('marks 429 as retryable and parses retry-after seconds', () => {
+    const d = classifyError(new HttpError('slow', 429, { 'retry-after': '7' }));
+    expect(d.retry).toBe(true);
+    expect(d.retryAfterMs).toBe(7000);
+  });
+  it('marks AbortError as not retryable', () => {
+    const err = new DOMException('Aborted', 'AbortError');
+    expect(classifyError(err)).toMatchObject({ retry: false, reason: 'aborted' });
+  });
+  it('marks TypeError (fetch failure) as retryable', () => {
+    expect(classifyError(new TypeError('fetch failed'))).toMatchObject({ retry: true });
+  });
+});
+
+describe('completeWithRetry', () => {
+  it('returns the result on first-try success', async () => {
+    const impl = vi.fn().mockResolvedValueOnce(ok);
+    const out = await completeWithRetry(MODEL, MESSAGES, OPTS, {}, impl);
+    expect(out).toEqual(ok);
+    expect(impl).toHaveBeenCalledTimes(1);
+  });
+
+  it('retries on 503 then succeeds, surfacing each attempt via onRetry', async () => {
+    const impl = vi
+      .fn()
+      .mockRejectedValueOnce(new HttpError('boom', 503))
+      .mockResolvedValueOnce(ok);
+    const onRetry = vi.fn<(info: RetryReason) => void>();
+    const out = await completeWithRetry(MODEL, MESSAGES, OPTS, { baseDelayMs: 1, onRetry }, impl);
+    expect(out).toEqual(ok);
+    expect(impl).toHaveBeenCalledTimes(2);
+    expect(onRetry).toHaveBeenCalledTimes(1);
+    expect(onRetry.mock.calls[0]?.[0].reason).toMatch(/server error/);
+  });
+
+  it('throws after exhausting retries', async () => {
+    const impl = vi.fn().mockRejectedValue(new HttpError('still down', 500));
+    await expect(
+      completeWithRetry(MODEL, MESSAGES, OPTS, { baseDelayMs: 1, maxRetries: 3 }, impl),
+    ).rejects.toThrow(/still down/);
+    expect(impl).toHaveBeenCalledTimes(3);
+  });
+
+  it('does not retry on a 401 client error', async () => {
+    const impl = vi.fn().mockRejectedValue(new HttpError('unauthorized', 401));
+    await expect(
+      completeWithRetry(MODEL, MESSAGES, OPTS, { baseDelayMs: 1 }, impl),
+    ).rejects.toThrow(/unauthorized/);
+    expect(impl).toHaveBeenCalledTimes(1);
+  });
+
+  it('honours Retry-After on 429 (delay is at least retryAfterMs)', async () => {
+    const impl = vi
+      .fn()
+      .mockRejectedValueOnce(new HttpError('slow', 429, { 'retry-after': '0.05' }))
+      .mockResolvedValueOnce(ok);
+    const onRetry = vi.fn<(info: RetryReason) => void>();
+    const out = await completeWithRetry(MODEL, MESSAGES, OPTS, { baseDelayMs: 1, onRetry }, impl);
+    expect(out).toEqual(ok);
+    const info = onRetry.mock.calls[0]?.[0];
+    expect(info?.retryAfterMs).toBe(50);
+    expect(info?.delayMs).toBeGreaterThanOrEqual(50);
+  });
+
+  it('aborts immediately when signal is already aborted', async () => {
+    const impl = vi.fn().mockResolvedValue(ok);
+    const ctrl = new AbortController();
+    ctrl.abort();
+    await expect(
+      completeWithRetry(MODEL, MESSAGES, { ...OPTS, signal: ctrl.signal }, {}, impl),
+    ).rejects.toBeInstanceOf(CodesignError);
+    expect(impl).not.toHaveBeenCalled();
+  });
+
+  it('aborts mid-backoff when signal fires during retry sleep', async () => {
+    const impl = vi.fn().mockRejectedValue(new HttpError('boom', 503));
+    const ctrl = new AbortController();
+    const promise = completeWithRetry(
+      MODEL,
+      MESSAGES,
+      { ...OPTS, signal: ctrl.signal },
+      { baseDelayMs: 5_000, maxRetries: 5 },
+      impl,
+    );
+    setTimeout(() => ctrl.abort(), 10);
+    await expect(promise).rejects.toThrow();
+    expect(impl).toHaveBeenCalledTimes(1);
+  });
+});