docs: add troubleshooting, cookbook, visual architecture and performance guide

unadlib · unadlib · commit 7a0639bac2e3 · 2026-02-16T03:16:14.000+08:00
diff --git a/README.md b/README.md
@@ -367,12 +367,16 @@ Use `manifest-only` in production (`autoPinLatestModuleManifest: false`) when yo
 ## Integration Docs
 
 - Architecture overview: [`docs/architecture.md`](docs/architecture.md)
+- Visual architecture diagrams (Mermaid): [`docs/architecture-visual.md`](docs/architecture-visual.md)
 - RuntimePlan IR reference: [`docs/runtime-plan-ir.md`](docs/runtime-plan-ir.md)
 - Runtime execution engine: [`docs/runtime-execution.md`](docs/runtime-execution.md)
 - Dependency verification model: [`docs/runtime-execution.md#verification-model`](docs/runtime-execution.md#verification-model)
 - Browser embedding: [`docs/browser-integration.md`](docs/browser-integration.md)
 - Security guide: [`docs/security.md`](docs/security.md)
 - Plugin system: [`docs/plugin-system.md`](docs/plugin-system.md)
+- Troubleshooting & FAQ: [`docs/troubleshooting-faq.md`](docs/troubleshooting-faq.md)
+- Cookbook / common integration patterns: [`docs/cookbook.md`](docs/cookbook.md)
+- Performance tuning guide: [`docs/performance-tuning.md`](docs/performance-tuning.md)
 
 ## Browser Examples
 
diff --git a/docs/architecture-visual.md b/docs/architecture-visual.md
@@ -0,0 +1,102 @@
+# Visual Architecture (Mermaid)
+
+This document provides visual diagrams for the main Renderify architecture paths.
+
+## End-to-End Pipeline
+
+```mermaid
+flowchart LR
+  A[Prompt or RuntimePlan] --> B[CodeGen]
+  B --> C[RuntimePlan IR]
+  C --> D[Security Checker]
+  D --> E[Runtime Manager]
+  E --> F[UI Renderer]
+  F --> G[DOM Output]
+
+  E --> H[JSPM Module Loader]
+  H --> I[Primary CDN]
+  H --> J[Fallback CDNs]
+```
+
+## Package Dependency Map
+
+```mermaid
+graph TD
+  R[renderify] --> C[@renderify/core]
+  R --> IR[@renderify/ir]
+  R --> RT[@renderify/runtime]
+  R --> S[@renderify/security]
+  R --> L[@renderify/llm]
+
+  C --> IR
+  C --> RT
+  C --> S
+
+  RT --> IR
+  RT --> S
+
+  S --> IR
+
+  CLI[@renderify/cli] --> R
+  CLI --> C
+  CLI --> L
+  CLI --> RT
+```
+
+## Runtime Source Execution Path
+
+```mermaid
+flowchart TD
+  A[plan.source code] --> B[Transpile TSX or JSX]
+  B --> C[Extract imports]
+  C --> D[Resolve specifiers]
+  D --> E[Fetch remote modules]
+  E --> F[Rewrite nested imports]
+  F --> G[Create blob URLs]
+  G --> H[dynamic import]
+  H --> I[Export function or node]
+  I --> J[Render artifact or RuntimeNode]
+```
+
+## Sandbox Decision Flow
+
+```mermaid
+flowchart TD
+  A[Source execution requested] --> B{Sandbox mode}
+
+  B -->|none| C[Main thread execution]
+  B -->|worker| D[Worker sandbox]
+  B -->|iframe| E[Iframe sandbox]
+  B -->|shadowrealm| F[ShadowRealm sandbox]
+
+  F --> G{ShadowRealm available?}
+  G -->|yes| H[Execute in ShadowRealm]
+  G -->|no| I[Fallback chain]
+  I --> D
+  I --> E
+
+  D --> J{Timeout or abort?}
+  E --> J
+  H --> J
+
+  J -->|no| K[Return result]
+  J -->|yes| L[AbortError or timeout error]
+```
+
+## Defense-in-Depth Security Layers
+
+```mermaid
+flowchart TB
+  A[Layer 1: Policy pre-check]
+  B[Layer 2: Module host and manifest constraints]
+  C[Layer 3: Runtime sandbox isolation]
+  D[Layer 4: UI sanitization]
+
+  A --> B --> C --> D
+```
+
+## Notes
+
+- The diagrams intentionally show control flow, not every internal helper.
+- For type-level details, see [`docs/api-reference.md`](./api-reference.md).
+- For execution semantics, see [`docs/runtime-execution.md`](./runtime-execution.md).
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -2,6 +2,8 @@
 
 This document describes the end-to-end architecture of Renderify, covering the pipeline stages, package responsibilities, data flow, and key design decisions.
 
+For Mermaid diagrams of the same architecture, see [`docs/architecture-visual.md`](./architecture-visual.md).
+
 ## High-Level Pipeline
 
 ```
diff --git a/docs/cookbook.md b/docs/cookbook.md
@@ -0,0 +1,163 @@
+# Cookbook: Common Integration Patterns
+
+This cookbook focuses on production-friendly patterns that appear repeatedly in Renderify integrations.
+
+## Pattern 1: Renderer-Only Embed (No Built-In LLM)
+
+Use when plan generation happens on your backend or another model pipeline.
+
+```ts
+import { renderPlanInBrowser } from "renderify";
+import type { RuntimePlan } from "@renderify/ir";
+
+const plan: RuntimePlan = {
+  specVersion: "runtime-plan/v1",
+  id: "renderer_only_card",
+  version: 1,
+  root: {
+    type: "element",
+    tag: "section",
+    children: [{ type: "text", value: "Hello from external plan" }],
+  },
+  capabilities: { domWrite: true },
+};
+
+await renderPlanInBrowser(plan, { target: "#mount" });
+```
+
+## Pattern 2: Manifest-Pinned Production Execution
+
+Use when reproducibility matters and dependency drift is not acceptable.
+
+```ts
+import { renderPlanInBrowser } from "renderify";
+
+await renderPlanInBrowser(planWithPinnedManifest, {
+  target: "#mount",
+  autoPinLatestModuleManifest: false,
+  runtimeOptions: {
+    enforceModuleManifest: true,
+    enableDependencyPreflight: true,
+    failOnDependencyPreflightError: true,
+  },
+});
+```
+
+Checklist:
+
+- Pin every bare specifier in `moduleManifest`.
+- In strict mode, include `integrity` for remote modules.
+- Run `probe-plan` in CI before release.
+
+## Pattern 3: Untrusted Source in Browser Sandbox
+
+Use when `plan.source` originates from untrusted prompts.
+
+```ts
+import { renderPlanInBrowser } from "renderify";
+
+await renderPlanInBrowser(untrustedPlan, {
+  target: "#mount",
+  runtimeOptions: {
+    browserSourceSandboxMode: "worker",
+    browserSourceSandboxTimeoutMs: 4000,
+    browserSourceSandboxFailClosed: true,
+  },
+});
+```
+
+Recommended policy posture:
+
+- `RENDERIFY_SECURITY_PROFILE=strict`
+- `RENDERIFY_RUNTIME_BROWSER_SANDBOX_FAIL_CLOSED=true`
+- `RENDERIFY_RUNTIME_JSPM_ONLY_STRICT_MODE=true` (when you want no fallback CDN path)
+
+## Pattern 4: Streaming Prompt to Progressive UI
+
+Use when chat UX needs preview updates before final render.
+
+```ts
+for await (const chunk of app.renderPromptStream(prompt, { previewEveryChunks: 2 })) {
+  if (chunk.type === "llm-delta") {
+    appendToken(chunk.delta);
+  }
+
+  if (chunk.type === "preview") {
+    renderPreviewHtml(chunk.html);
+  }
+
+  if (chunk.type === "final") {
+    commitFinalHtml(chunk.final.html);
+  }
+
+  if (chunk.type === "error") {
+    showError(chunk.error.message);
+  }
+}
+```
+
+## Pattern 5: Probe Before Execute (CI Gate)
+
+Use when you need deterministic "will this render?" signals without executing source/component code.
+
+```bash
+pnpm cli -- probe-plan examples/runtime/recharts-dashboard-plan.json
+```
+
+A practical CI flow:
+
+1. Run `probe-plan` for generated plans.
+2. Fail pipeline if `securityIssueCount > 0`.
+3. Fail pipeline if `preflightIssueCount > 0` in strict production lanes.
+
+## Pattern 6: Controlled Network Scope for Remote Modules
+
+Use when outbound network egress must be restricted.
+
+```ts
+await renderPlanInBrowser(plan, {
+  runtimeOptions: {
+    allowArbitraryNetwork: false,
+    allowedNetworkHosts: ["ga.jspm.io", "cdn.jspm.io", "esm.sh"],
+    remoteFallbackCdnBases: ["https://esm.sh"],
+  },
+});
+```
+
+Keep `allowedNetworkHosts` and `remoteFallbackCdnBases` aligned so fallback URLs do not violate runtime host policy.
+
+## Pattern 7: Explicit JSX Helper Behavior
+
+Use when you want stable transpilation behavior across environments.
+
+```ts
+await renderPlanInBrowser(planWithSource, {
+  runtimeOptions: {
+    runtimeSourceJsxHelperMode: "always", // "auto" | "always" | "never"
+  },
+});
+```
+
+- `auto`: runtime decides helper injection based on source/runtime mode.
+- `always`: always inject helper path (predictable for heterogeneous input).
+- `never`: only for advanced setups where helper wiring is external.
+
+## Pattern 8: Serialized Target Renders (Avoid UI Race Conditions)
+
+Use when multiple concurrent renders target the same mount element.
+
+```ts
+await Promise.all([
+  renderPlanInBrowser(planA, { target: "#mount", serializeTargetRenders: true }),
+  renderPlanInBrowser(planB, { target: "#mount", serializeTargetRenders: true }),
+]);
+```
+
+`renderPlanInBrowser` serializes operations per target element by default (`serializeTargetRenders !== false`). Keep it enabled unless you have a custom scheduler.
+
+## Related Docs
+
+- [`docs/getting-started.md`](./getting-started.md)
+- [`docs/runtime-execution.md`](./runtime-execution.md)
+- [`docs/security.md`](./security.md)
+- [`docs/troubleshooting-faq.md`](./troubleshooting-faq.md)
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -208,6 +208,7 @@ pnpm format           # Auto-format code
 ## Next Steps
 
 - [Architecture Overview](./architecture.md) — understand the full pipeline
+- [Visual Architecture (Mermaid)](./architecture-visual.md) — system diagrams for data flow and package boundaries
 - [RuntimePlan IR Reference](./runtime-plan-ir.md) — learn the intermediate representation
 - [Security Guide](./security.md) — security policies and profiles
 - [LLM Integration](./llm-integration.md) — provider configuration and structured output
@@ -216,4 +217,7 @@ pnpm format           # Auto-format code
 - [CLI & Playground](./cli-playground.md) — CLI commands and playground features
 - [Browser Integration](./browser-integration.md) — embedding in web applications
 - [API Reference](./api-reference.md) — complete type and function reference
+- [Troubleshooting & FAQ](./troubleshooting-faq.md) — failure diagnostics and recovery checklist
+- [Cookbook](./cookbook.md) — copy-paste integration patterns
+- [Performance Tuning](./performance-tuning.md) — runtime knobs, CI guardrails, and optimization workflow
 - [Contributing Guide](./contributing.md) — development workflow and conventions
diff --git a/docs/performance-tuning.md b/docs/performance-tuning.md
diff --git a/docs/troubleshooting-faq.md b/docs/troubleshooting-faq.md
