[ { "path": ".changeset/config.json", "content": "{\n \"$schema\": \"https://unpkg.com/@changesets/config@3.0.1/schema.json\",\n \"access\": \"public\",\n \"privatePackages\": {\n \"version\": false\n }\n}\n" }, { "path": ".git-blame-ignore-revs", "content": "# oxfmt bulk reformat (Prettier → Oxfmt migration)\ne052c5666f770d1521b8e5e574d2fa69152f89dc\n" }, { "path": ".githooks/pre-commit", "content": "#!/usr/bin/env sh\nset -eu\n\npnpm hooks:pre-commit\n\npnpm lint-staged\n" }, { "path": ".githooks/pre-push", "content": "#!/usr/bin/env sh\nset -eu\n\npnpm hooks:pre-push\n" }, { "path": ".github/pull_request_template.md", "content": "## Summary\n\n## Verification\n\n- [ ] Ran `pnpm verify:ci`\n- [ ] Committed updated `public/r` artifacts when Tool UI or registry sources changed\n" }, { "path": ".github/workflows/changeset.yaml", "content": "name: Changesets\n\non:\n push:\n branches:\n - main\n\npermissions:\n contents: write\n pull-requests: write\n\nconcurrency:\n group: ${{ github.workflow }}-${{ github.ref }}\n cancel-in-progress: true\n\nenv:\n CI: true\n\njobs:\n version:\n name: Create Version PR\n runs-on: ubuntu-latest\n steps:\n - name: Checkout code repository\n uses: actions/checkout@v6\n with:\n fetch-depth: 1\n\n - name: Install pnpm\n uses: pnpm/action-setup@v4\n\n - name: Setup node.js\n uses: actions/setup-node@v6\n with:\n node-version: 24\n cache: \"pnpm\"\n\n - name: Install dependencies\n run: pnpm install --frozen-lockfile\n\n - name: Create version PR\n id: changesets\n uses: changesets/action@v1\n with:\n commit: \"chore: update versions\"\n title: \"chore: update versions\"\n version: pnpm ci:version\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n\n - name: Check if any packages need publishing\n id: check-publish\n if: steps.changesets.outputs.hasChangesets == 'false'\n run: |\n needs_publish=\"false\"\n for pkg in packages/*/package.json; do\n [ -f \"$pkg\" ] || continue\n\n name=$(jq -r '.name' \"$pkg\")\n version=$(jq -r '.version' \"$pkg\")\n private=$(jq -r '.private // false' \"$pkg\")\n\n if [ \"$private\" = \"true\" ]; then\n echo \"Skipping private package: $name\"\n continue\n fi\n\n if npm view \"${name}@${version}\" version 2>/dev/null | grep -q \"${version}\"; then\n echo \"✓ ${name}@${version} already published\"\n else\n echo \"✗ ${name}@${version} needs publishing\"\n needs_publish=\"true\"\n fi\n done\n\n echo \"needsPublish=${needs_publish}\" >> $GITHUB_OUTPUT\n\n - name: Trigger npm publish\n if: steps.changesets.outputs.hasChangesets == 'false' && steps.check-publish.outputs.needsPublish == 'true'\n uses: actions/github-script@v7\n with:\n script: |\n await github.rest.repos.createDispatchEvent({\n owner: context.repo.owner,\n repo: context.repo.repo,\n event_type: 'npm-publish'\n });\n" }, { "path": ".github/workflows/ci.yml", "content": "name: CI\n\non:\n pull_request:\n branches: [main]\n push:\n branches: [main]\n\njobs:\n verify:\n runs-on: ubuntu-latest\n\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Setup pnpm\n uses: pnpm/action-setup@v4\n\n - name: Setup Node.js\n uses: actions/setup-node@v4\n with:\n node-version: 20\n cache: pnpm\n\n - name: Install dependencies\n run: pnpm install --frozen-lockfile\n\n - name: Format check\n run: pnpm lint:format\n\n - name: Lint - Oxlint\n run: pnpm lint:oxlint\n\n - name: Lint - ESLint custom rules\n run: pnpm lint:eslint\n\n - name: Typecheck\n run: pnpm typecheck\n\n - name: Test\n run: pnpm test\n\n - name: Check changelog structure\n run: pnpm changelog:check\n\n - name: Verify registry artifacts are up to date\n run: pnpm registry:check\n" }, { "path": ".github/workflows/npm-publish.yaml", "content": "name: npm Publish\n\non:\n repository_dispatch:\n types: [npm-publish]\n\npermissions:\n id-token: write\n contents: write\n\nenv:\n CI: true\n\njobs:\n publish:\n name: Publish to npm\n if: github.ref == 'refs/heads/main'\n environment: npm Publish\n runs-on: ubuntu-latest\n steps:\n - name: Checkout code repository\n uses: actions/checkout@v6\n with:\n fetch-depth: 1\n\n - name: Install pnpm\n uses: pnpm/action-setup@v4\n\n - name: Setup node.js\n uses: actions/setup-node@v6\n with:\n node-version: 24\n registry-url: \"https://registry.npmjs.org\"\n\n - name: Install dependencies\n run: pnpm install --frozen-lockfile\n\n - name: Publish to npm\n run: pnpm ci:publish\n env:\n NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}\n\n - name: Create GitHub Releases\n env:\n GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n run: |\n git fetch --tags\n\n for pkg in packages/*/package.json; do\n name=$(jq -r '.name' \"$pkg\")\n version=$(jq -r '.version' \"$pkg\")\n private=$(jq -r '.private // false' \"$pkg\")\n\n [[ \"$private\" == \"true\" ]] && continue\n\n tag=\"${name}@${version}\"\n\n git rev-parse \"$tag\" >/dev/null 2>&1 || continue\n gh release view \"$tag\" >/dev/null 2>&1 && continue\n\n changelog_dir=$(dirname \"$pkg\")\n changelog=\"$changelog_dir/CHANGELOG.md\"\n\n notes=\"\"\n if [[ -f \"$changelog\" ]]; then\n notes=$(awk \"/^## ${version//./\\\\.}\\$/,/^## [0-9]/\" \"$changelog\" | head -n -1 | tail -n +2)\n fi\n [[ -z \"$notes\" ]] && notes=\"Release ${tag}\"\n\n echo \"Creating release: $tag\"\n gh release create \"$tag\" \\\n --title \"$tag\" \\\n --notes \"$notes\" \\\n --verify-tag || echo \"Warning: Failed to create release for $tag\"\n done\n" }, { "path": ".gitignore", "content": "# Dependencies\nnode_modules\n/.pnp\n.pnp.*\n\n# Testing\ncoverage\n\n# Next.js\n.next/\nout/\n\n# Production\nbuild\ndist\n\n# Misc\n.DS_Store\n*.pem\nprivate\n\n# Debug\nnpm-debug.log*\nyarn-debug.log*\nyarn-error.log*\n.pnpm-debug.log*\n\n# Local env files\n.env*.local\n.env\n\n# Vercel\n.vercel\n\n# TypeScript\n*.tsbuildinfo\nnext-env.d.ts\n\n# Turbo\n.turbo\n\n# Cursor\n.cursor\n\n# Claude\n.claude/\n\n# VSCode\n.vscode/\n.vscode.playwright-mcp/\n.vscode/terminals.json\n.playwright-mcp\n" }, { "path": ".prettierignore", "content": "# Generated artifacts (managed by build scripts)\napps/www/public/r/\napps/www/components/tool-ui/weather-widget/generated/\napps/www/lib/weather-authoring/weather-widget/effects/generated/\napps/www/lib/weather-authoring/weather-widget/weather-data-overlay.generated.ts\n" }, { "path": "AGENTS.md", "content": "# AGENTS.md\n\n## Cursor Cloud specific instructions\n\n### Project overview\n\nTool UI is a Next.js 16 documentation/demo site and copy-paste component library for AI assistant interfaces. The app lives in `apps/www/` within a pnpm monorepo. There is no database, no Docker, and no required background services beyond the Node.js dev server.\n\n### Running services\n\n- **Dev server**: `pnpm dev` (Turbopack, port 3000). The static docs, gallery, and component previews work without any API keys.\n- **Chat/Playground features** require `OPENAI_API_KEY` in `.env` (see `.env.example`). Without it the chat API routes return errors, but the rest of the site functions normally.\n\n### Commands reference\n\nAll standard commands are documented in `CLAUDE.md`. Key ones:\n\n| Task | Command |\n| ------------------------- | ---------------- |\n| Dev server | `pnpm dev` |\n| Lint + typecheck + format | `pnpm check` |\n| Tests (Vitest) | `pnpm test` |\n| Fix lint issues | `pnpm lint:fix` |\n| Typecheck only | `pnpm typecheck` |\n\n### Non-obvious caveats\n\n- **Typecheck uses `tsgo`** (`@typescript/native-preview`), not standard `tsc`. The `pnpm typecheck` command runs `tsgo --noEmit`.\n- **Formatter is `oxfmt`**, not Prettier. Run `pnpm format` to format or `pnpm format:check` to verify. It handles Tailwind class sorting and import sorting.\n- **Linting is split**: `oxlint` handles standard rules; `eslint` is retained only for `no-restricted-syntax`, `no-restricted-imports`, custom `tool-ui/*` rules, and React Compiler hooks. `pnpm check` runs both in parallel.\n- **`pnpm install` triggers `prepare`** which sets up git hooks via `tsx apps/www/scripts/install-git-hooks.ts`. The hooks directory is `.githooks/`.\n- **Pre-existing lint warnings** (60 warnings, 0 errors): these are known oxlint a11y warnings in the codebase and are not regressions.\n- **Build uses `--experimental-build-mode=compile`**: `pnpm build` runs `next build --experimental-build-mode=compile`.\n" }, { "path": "AGENT_CHANGELOG.md", "content": "# Agent Changelog\n\n> This file helps coding agents understand project evolution, key decisions, and deprecated patterns.\n> Updated: 2026-02-11\n\n## Current State Summary\n\nTool UI is a maintainer-owned copy/paste component library (shadcn/ui model) for AI assistant interfaces with a registry-first install path (`https://tool-ui.com/r/.json`). Component APIs are flat, receipt semantics are unified on `choice`, and component directories remain the product surface (`schema`, `component`, `README`, exports). Registry adapters now use `@/lib/utils` for `cn` (no registry-shipped `lib/ui/cn.ts`), Tool UI component motion is constrained to Tailwind/tw-animate-compatible classes, and docs place Source/Install + GitHub source links ahead of feature marketing sections.\n\n## Stale Information Detected\n\n| Location | States | Reality | Since |\n| -------------------------------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ------- |\n| `README.md` (Shadcn Registry section) | Registry artifacts include `lib/ui/cn.ts` | Registry adapters use `@/lib/utils`; `lib/ui/cn.ts` is no longer part of generated install artifacts | 2026-02 |\n| `.claude/plans/plan-sequential-munching-canyon.md` | References `hooks/use-code-gen.ts` TypeScript generation | Tuning flow is apply/recover via repo routes; `use-code-gen.ts` removed | 2026-02 |\n| `.claude/plans/plan-sequential-munching-canyon.md` | Targets deletion of `app/sandbox/weather-compositor/` | `weather-tuning` still imports compositor presets/interpolation modules; compositor remains active | 2026-02 |\n| `.claude/docs/component-workflow.md` | New component contract requires `error-boundary.tsx` | Error-boundary layer was removed from component contracts; index exports no longer include local error boundaries | 2026-02 |\n| `.claude/agents/tool-ui-implementer.md` | Instructs creating `error-boundary.tsx` and using `createToolUiErrorBoundary` | Error-boundary wrappers were removed; component contract now centers on `_adapter`, schema, component, index, README | 2026-02 |\n| `.claude/agents/tool-ui-reviewer.md` | Blocks review if `error-boundary.tsx` is missing | `error-boundary.tsx` is no longer required in component directories | 2026-02 |\n| `.claude/compiled/component-creation.md` | Uses `../shared` barrel and error-boundary scaffolding in canonical template | Current standards forbid `../shared` barrel imports for core logic and remove per-component error boundary scaffolds | 2026-02 |\n| `docs/plans/2026-01-22-feat-wizard-step-component-plan.md` | Active implementation target is `WizardStep` at `components/tool-ui/wizard-step/*` | Implemented component is `QuestionFlow` at `components/tool-ui/question-flow/*` | 2026-01 |\n| `docs/plans/2026-01-23-feat-wizard-step-visual-polish-plan.md` | Polish targets `WizardStep` paths and naming | Final shipped component naming/path is `QuestionFlow` | 2026-01 |\n\n## Timeline\n\n### 2026-02-11 — Component Docs Prioritize Install + Source Visibility\n\n**What changed:** All component docs were normalized so `## Source and Install` appears above `## Key Features`, with a GitHub source link for each component (`components/tool-ui/`).\n\nHighlights:\n\n- Reordered sections across all component docs to surface install instructions first\n- Normalized mixed `## Features`/`## Key Features` headings to `## Key Features`\n- Added docs contract enforcement to prevent regressions in section order and source-link presence\n\n**Why:** Make integration steps and source discovery immediately visible for maintainers/copy-paste users.\n\n**Agent impact:** In component docs, place install/source sections before feature callouts. Include both:\n\n- `npx shadcn@latest add https://tool-ui.com/r/.json`\n- GitHub source link to `components/tool-ui/`\n\n**Files:** `app/docs/*/content.mdx`, `lib/tests/tool-ui/docs/registry-installation-contract.test.ts`\n\n---\n\n### 2026-02-11 — Tool UI Animation Portability Standardized for Registry Consumers\n\n**What changed:** Tool UI components were migrated off repo-private animation keyframes and now rely on Tailwind/tw-animate-compatible classes only.\n\nHighlights:\n\n- Replaced private animation names (e.g. `spring-bounce`, `check-draw`, `fade-blur-in`, `progress-pulse`) in shipped component code\n- Removed inline `@keyframes` from `stats-display/sparkline`\n- Added portability contract tests that fail on private keyframe tokens or inline keyframes in source and generated registry artifacts\n- Added registry dependency assertions for motion primitives (`accordion`/`collapsible`)\n\n**Why:** Prevent no-op/broken transitions in downstream shadcn apps that do not include this repo’s private CSS.\n\n**Agent impact:** For `components/tool-ui/**`, use Tailwind/tw-animate classes (`animate-in/out`, fade/zoom/slide, `animate-spin`, `animate-pulse`) and avoid custom keyframe names unless they are provided by stock shadcn/tw-animate setup.\n\n**Files:** `components/tool-ui/plan/plan.tsx`, `components/tool-ui/progress-tracker/progress-tracker.tsx`, `components/tool-ui/question-flow/question-flow.tsx`, `components/tool-ui/approval-card/approval-card.tsx`, `components/tool-ui/option-list/option-list.tsx`, `components/tool-ui/stats-display/sparkline.tsx`, `lib/tests/tool-ui/docs/animation-portability-contract.test.ts`, `lib/tests/registry/tool-ui-registry.test.ts`\n\n---\n\n### 2026-02-11 — Registry Adapter `cn` Dependency Migrated to shadcn `@/lib/utils`\n\n**What changed:** Registry component adapters were updated to import `cn` from `@/lib/utils`; generated artifacts no longer rely on/emit `lib/ui/cn.ts`.\n\nHighlights:\n\n- Adapter imports switched from `@/lib/ui/cn` to `@/lib/utils`\n- Registry artifact checks updated accordingly\n- Fresh install path validated against root-level shadcn command and hosted component JSON URLs\n\n**Why:** Align Tool UI install output with stock shadcn app structure and eliminate repo-specific `cn` scaffolding.\n\n**Agent impact:** For registry-consumed component adapters, expect:\n\n- `import { cn } from \"@/lib/utils\"`\n- no generated `lib/ui/cn.ts` dependency\n\n**Files:** `components/tool-ui/*/_adapter.tsx`, `lib/tests/registry/tool-ui-registry.test.ts`, `app/docs/quick-start/content.mdx`, `public/r/*.json`\n\n---\n\n### 2026-02-11 — Registry-First Install Path Finalized; ZIP/Manual Guidance Removed\n\n**What changed:** Docs were converted to a single registry-first install flow using full component URLs, and legacy ZIP/manual copy instructions were removed.\n\n**Why:** Reduce install ambiguity and support a single canonical setup path for consumers.\n\n**Agent impact:** Use only:\n\n- `npx shadcn@latest add https://tool-ui.com/r/.json`\n\nDo not propose ZIP/manual copy workflows.\n\n**Files:** `app/docs/*/content.mdx`, `app/docs/quick-start/content.mdx`, `lib/tests/tool-ui/docs/registry-installation-contract.test.ts`\n\n---\n\n### 2026-02-11 — Import Boundary Enforcement + Error Boundary Layer Removal\n\n**What changed:** Tool UI component contracts were tightened around portability boundaries and local adapter ownership.\n\nHighlights:\n\n- Removed per-component `error-boundary.tsx` files and related exports across component directories\n- Normalized component `_adapter.tsx` files to alias-based UI imports\n- Enforced adapter-only UI primitive imports via ESLint (`@/components/ui/*` and `@/lib/ui/cn` are restricted outside `_adapter.tsx`)\n- Hardened registry/ID contracts and tests (`data-table` row keys, `question-flow` ids, registry generation edge cases like OS metadata files)\n\n**Why:** Reduce copy/paste friction, prevent component-internal import drift, and keep portability constraints enforceable by lint/tests instead of convention.\n\n**Agent impact:** Do not add local `error-boundary.tsx` files for new components. In non-adapter component modules, import UI primitives and `cn` only from `./_adapter`; keep shared imports as direct leaf modules (`../shared/*`), not barrels.\n\n**Files:** `eslint.config.ts`, `components/tool-ui/*/_adapter.tsx`, `components/tool-ui/*/index.ts*`, `lib/registry/tool-ui-registry.ts`, `lib/tests/tool-ui/data-table/row-keys-contract.test.ts`, `lib/tests/tool-ui/question-flow/ids-contract.test.ts`, `lib/tests/registry/tool-ui-registry.test.ts`\n\n---\n\n### 2026-02-11 — Maintainer Workflow + State Contract Hardening\n\n**What changed:** Shifted docs and tooling to a maintainer-first workflow and added targeted regression contracts for high-risk UI state paths.\n\nHighlights:\n\n- Reframed onboarding/docs around maintainers (`README.md`, `CONTRIBUTING.md`, `app/docs/contributing/content.mdx`, `docs/playground.md`, `docs/tests.md`)\n- Added component-local README coverage and scaffold automation via `pnpm component:new` (`scripts/new-tool-ui-component.ts`)\n- Added `components/tool-ui/index.ts` aggregate export surface\n- Added contract tests for deterministic row keys, outcome sync transitions, step ids, and tab search param resolution\n- Closed component contract gaps and improved scaffold consistency\n\n**Why:** Reduce time-to-first-working-component, make component directory contracts explicit, and keep state/ID behavior stable as internals evolve.\n\n**Agent impact:** Use scaffold + maintainer docs as the default path for new components. When changing stateful behavior, expose deterministic helpers and add contract tests under `lib/tests/**`.\n\n**Files:** `README.md`, `CONTRIBUTING.md`, `app/docs/contributing/content.mdx`, `scripts/new-tool-ui-component.ts`, `components/tool-ui/index.ts`, `lib/tests/tool-ui/**/*`\n\n---\n\n### 2026-02-10 — Registry Pipeline Hardened for Per-Component Install\n\n**What changed:** Registry generation moved to component-directory discovery with per-item artifacts and minimal dependency closure (instead of relying on prefixed/manual lists and shared monolith assumptions).\n\nHighlights:\n\n- Component discovery from `components/tool-ui/*` (excluding `shared`)\n- Registry items unprefixed (`tool-ui-foo` → `foo`)\n- Shared artifact dependencies inlined per item where needed\n- Registry tests assert discovered items match component directories\n\n**Why:** Keep shadcn registry output aligned with the actual product surface and reduce drift from manually curated registry definitions.\n\n**Agent impact:** Treat `components/tool-ui` directories as source of truth for registry coverage. After adding/refactoring components, run `pnpm registry:build` and `pnpm registry:check`.\n\n**Files:** `lib/registry/tool-ui-registry.ts`, `lib/tests/registry/tool-ui-registry.test.ts`, `scripts/build-tool-ui-registry.ts`, `public/r/*.json`\n\n---\n\n### 2026-02-10 — CI 1.0 Quality Gates\n\n**What changed:** CI now enforces lint/typecheck/test/registry artifact consistency on push/PR to `main`.\n\n**Why:** Prevent state contract regressions and stale registry artifacts from landing.\n\n**Agent impact:** A local \"done\" state for maintainer work is: `pnpm lint:ci`, `pnpm typecheck`, `pnpm test`, `pnpm registry:check`.\n\n**Files:** `.github/workflows/ci.yml`, `package.json`\n\n---\n\n### 2026-02-10 — Weather Widget V3.1 Clean Break\n\n**What changed:** Weather widget migrated to a strict V3.1 payload contract and removed legacy compatibility layers.\n\nKey contract shifts:\n\n- Canonical parser: `safeParseWeatherWidgetPayload`\n- Payload shape is widget prop contract (+ UI-only props)\n- Deterministic time input is now `time` (`timeBucket` or `localTimeOfDay`)\n- Field names normalized (`current.conditionCode`, `units.temperature`, `forecast[].label`, etc.)\n\n**Why:** Keep provider normalization in the tool layer, simplify widget rendering inputs, and make day/night/effects deterministic.\n\n**Agent impact:** Emit only V3.1 payloads when rendering WeatherWidget. Do not use legacy serializable weather parser/types or provider-specific fields in widget render payloads.\n\n**Files:** `components/tool-ui/weather-widget/schema.ts`, `components/tool-ui/weather-widget/time.ts`, `components/tool-ui/weather-widget/weather-widget.tsx`, `lib/presets/weather-widget.ts`\n\n---\n\n### 2026-02-10 — Weather Tuning Workflow Simplified (Apply-Only)\n\n**What changed:** Removed client-side weather tuning codegen hook (`app/sandbox/weather-tuning/hooks/use-code-gen.ts`) and standardized on repo-backed apply/recover endpoints.\n\n**Why:** Reduce duplicate export logic and keep one source of truth (`components/tool-ui/weather-widget/effects/tuned-presets.ts`).\n\n**Agent impact:** In tuning flows, treat `Apply to repo` as the path to production. Use:\n\n- `POST /api/weather-tuning/apply`\n- `GET /api/weather-tuning/recover`\n\nDo not add/restore parallel clipboard/download codegen paths for production tuning updates.\n\n---\n\n### 2026-02-10 — Test Location Policy Enforced\n\n**What changed:** Weather + shared tests were moved under `lib/tests/**` to ensure they run under current Vitest include globs and are not copied with component folders.\n\n**Why:** Components are copy-paste product surface; test fixtures/infra should stay internal to this repo.\n\n**Agent impact:** Place new executable tests in:\n\n- `lib/tests/**` (preferred)\n- `lib/playground/**` (playground-specific)\n\nTests under `components/tool-ui/**` are out-of-policy and may not run by default.\n\n**Files:** `vitest.config.ts`, `lib/tests/tool-ui/shared/*`, `lib/tests/tool-ui/weather-widget/*`\n\n---\n\n### 2026-01-30 — PostHog Analytics Added\n\n**What changed:** Added PostHog instrumentation with Vercel Analytics dual-tracking.\n\n**Why:** Track component usage, preset selection, and code copying to understand what components and presets are most valuable.\n\n**Files added:**\n\n- `instrumentation-client.ts` — Client-side PostHog initialization\n- `lib/posthog-server.ts` — Server-side PostHog SDK\n- `lib/analytics.ts` — Typed event tracking SDK\n\n**Files modified:**\n\n- `next.config.ts` — Added `/ph/*` proxy rewrites for PostHog\n- `preset-selector.tsx` — Tracks `component_preset_selected`\n- `component-preview-shell.tsx` — Tracks `component_code_copied`, now requires `componentId` prop\n\n**Agent impact:** When adding new trackable interactions, use `analytics.*` methods from `lib/analytics.ts`. The `ComponentPreviewShell` now requires a `componentId` prop.\n\n**Events tracked:**\n\n- `component_preset_selected` — User selects a preset\n- `component_code_copied` — User copies component code\n- `component_viewed` — User views a component (ready to instrument)\n- `search_no_results` — Search with no matches (ready to instrument)\n\n---\n\n### 2026-01-29 — Sandbox Middleware Added\n\n**What changed:** Added middleware to gate `/sandbox/*` routes behind a `?sandbox=true` query param in production. Development mode always allows access.\n\n**Why:** Keep experimental sandboxes (weather effects testing, etc.) accessible for development without exposing them in production.\n\n**Agent impact:** Sandbox pages work normally in dev. In production, add `?sandbox=true` to URL to access.\n\n---\n\n### 2026-01-29 — SVG Glass Panel Effect Added\n\n**What changed:** Added `GlassPanel` component and `useGlassStyles` hook for frosted glass refraction effects using SVG displacement maps via CSS `backdrop-filter`.\n\n**Why:** Provide realistic glass distortion effects for weather widget overlays without WebGL complexity. SVG approach composes naturally with DOM, handles transparency correctly, and doesn't require canvas management.\n\n**Technical approach:**\n\n- SVG `feDisplacementMap` filter encodes X/Y displacement via R/G color channels\n- Chromatic aberration displaces RGB channels by different amounts (R most, G middle, B least)\n- Filter embedded as data URI in `backdrop-filter` CSS property\n- Graceful degradation on unsupported browsers (no effect, content still visible)\n\n**Agent impact:** Use `useGlassStyles` hook or `GlassPanel` component for glass effects. Don't implement WebGL-based glass effects—the SVG approach is simpler and sufficient.\n\n```tsx\n// Hook for applying to existing elements\nconst glassStyles = useGlassStyles({\n width: 300,\n height: 200,\n depth: 12,\n strength: 40,\n chromaticAberration: 8,\n});\n\n// Component wrapper\n\n content\n;\n```\n\n**Files:** `components/tool-ui/weather-widget/effects/glass-panel-svg.tsx`\n\n---\n\n### 2026-01-26 — AI SDK v5 → v6 Upgrade\n\n**What changed:** Upgraded AI SDK from v5 to v6, assistant-ui to v0.12 with new hook APIs.\n\n**Why:** Keep dependencies current with latest AI SDK patterns.\n\n**Agent impact:** When referencing AI SDK or assistant-ui patterns, use v6/v0.12 APIs. Don't reference deprecated v5 patterns.\n\n---\n\n### 2026-01-23 — Question Flow Component Added\n\n**What changed:** Added Question Flow component (renamed from \"Wizard Step\" during development). Includes variants: `inline` (default) and `upfront`.\n\n**Why:** Provide structured multi-step question UI for AI assistants.\n\n**Agent impact:** Use `QuestionFlow` for multi-step user input. Component was briefly in showcase, then removed—current best practice is to use `defaultValue` prop for pre-selected state.\n\n**Files:** `components/tool-ui/question-flow/`\n\n---\n\n### 2026-01-22 — Copy Humanization Pass\n\n**What changed:** Systematic rewrite of component docs and non-component docs to remove promotional language and improve voice.\n\n**Why:** Copy should feel like real, believable interactions (see `.claude/docs/copy-guide.md`).\n\n**Agent impact:** Follow copy-guide.md when writing example content. Avoid promotional language, generic placeholders, and tech demo patterns.\n\n---\n\n### 2026-01-19 — Unified Receipt Prop (`choice`)\n\n**What changed:** All receipt state props unified to `choice` across components.\n\n**Before:** `confirmed`, `decision` (inconsistent per component)\n**After:** `choice` (universal)\n\n**Why:** Consistent API for LLM serialization and code readability.\n\n**Agent impact:** Always use `choice` prop for receipt state. Never use `confirmed` or `decision`.\n\n```tsx\n// Correct\n\n\n\n// Deprecated (don't use)\n\n\n```\n\n**Files:** Plan at `.claude/plans/2025-01-19-unified-receipt-prop.md`\n\n---\n\n### 2026-01-16 — MessageDraft Component Added\n\n**What changed:** Added MessageDraft component for email and Slack message previews.\n\n**Agent impact:** Use `MessageDraft` for email/Slack preview UIs, not custom implementations.\n\n**Files:** `components/tool-ui/message-draft/`\n\n---\n\n### 2026-01-14 — Gallery Removals (X Post, ParameterSlider)\n\n**What changed:** X Post and ParameterSlider removed from gallery (components still exist in codebase).\n\n**Why:** X Post scenario didn't pass believability test. ParameterSlider was experimental.\n\n**Agent impact:** Components exist but aren't prominently featured. ParameterSlider is still usable; X Post exists but has copy issues.\n\n---\n\n### 2026-01-06 — ImageGallery Migration to View Transitions API\n\n**What changed:** ImageGallery migrated from Framer Motion to native View Transitions API.\n\n**Why:** Reduce bundle size, use platform features.\n\n**Agent impact:** Don't add Framer Motion for ImageGallery animations. Use View Transitions API patterns.\n\n---\n\n## Deprecated Patterns\n\n| Don't | Do Instead | Since |\n| --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ----------------- |\n| Use `confirmed` prop | Use `choice` prop | 2026-01-19 |\n| Use `decision` prop | Use `choice` prop | 2026-01-19 |\n| Add `maxWidth`/`padding` props | Let users customize via `className` | Project inception |\n| Use nested config objects | Use flat props | Project inception |\n| Add Framer Motion to ImageGallery | Use View Transitions API | 2026-01-06 |\n| Use AI SDK v5 patterns | Use AI SDK v6 patterns | 2026-01-26 |\n| Implement WebGL glass effects | Use `useGlassStyles` or `GlassPanel` from glass-panel-svg | 2026-01-29 |\n| Use `ComponentPreviewShell` without `componentId` | Always pass `componentId` prop for analytics | 2026-01-30 |\n| Use weather payload prop `visual` | Use weather payload prop `time` | 2026-02-10 |\n| Use legacy serializable weather parser/types | Use `WeatherWidgetPayloadSchema` + `safeParseWeatherWidgetPayload` | 2026-02-10 |\n| Put executable tests in `components/tool-ui/**` | Put tests in `lib/tests/**` (or `lib/playground/**`) | 2026-02-10 |\n| Use `app/sandbox/weather-tuning/hooks/use-code-gen.ts` export flow | Use apply/recover API routes and `tuned-presets.ts` | 2026-02-10 |\n| Curate registry component lists by hand | Discover from `components/tool-ui/*` and validate with registry tests | 2026-02-10 |\n| Import from `../shared` barrel in core interactive components | Import direct leaf modules from `../shared/*` | 2026-02-10 |\n| Import shadcn primitives (`@/components/ui/*`, `@/lib/ui/cn`) directly in non-adapter component files | Import those primitives from local `./_adapter` files | 2026-02-11 |\n| Require/export per-component `error-boundary.tsx` wrappers | Export component + schema contracts directly; rely on caller/app-level boundaries | 2026-02-11 |\n| Add new components without local READMEs and contract scaffold files | Use `pnpm component:new` and keep the full component directory contract | 2026-02-11 |\n| Depend on registry-shipped `lib/ui/cn.ts` in generated component installs | Use shadcn `@/lib/utils` (`cn`) in adapter output | 2026-02-11 |\n| Use private animation keyframes in `components/tool-ui/**` (e.g. `spring-bounce`, `check-draw`, `fade-blur-in`) | Use Tailwind/tw-animate-compatible classes only | 2026-02-11 |\n| Put `## Source and Install` below features in component docs | Put `## Source and Install` above `## Key Features` and include GitHub source link | 2026-02-11 |\n\n## Trajectory\n\nBased on recent changes, the project is:\n\n- **Standardizing APIs** — Receipt props unified, flat prop patterns enforced\n- **Maintainer-first DX** — onboarding and docs tuned for direct maintenance in this repo\n- **Polishing copy** — Moving from capability demos to believable scenarios\n- **Keeping dependencies current** — AI SDK v6, assistant-ui v0.12\n- **Reducing bundle** — View Transitions over Framer Motion where possible\n- **Adding specialized components** — MessageDraft, QuestionFlow, StatsDisplay for specific use cases\n- **Adding visual effects** — SVG-based glass refraction for weather widget, preferring CSS/SVG over WebGL\n- **Adding analytics** — PostHog + Vercel Analytics for usage tracking\n- **Hardening weather contracts** — V3.1 clean-break payloads with deterministic `time` input and apply-only tuning workflow\n- **Hardening delivery rails** — registry auto-discovery + CI gates to catch drift early\n- **Tightening portability boundaries** — adapter-only UI imports and removal of per-component error-boundary wrappers\n- **Registry-first distribution UX** — docs and tests now prioritize install/source visibility and hosted registry URLs\n- **Runtime portability over private styling** — shipped Tool UI components avoid repo-private keyframes and rely on tw-animate-compatible motion\n" }, { "path": "CLAUDE.md", "content": "# Tool UI\n\nCopy/paste component library (shadcn/ui model) for AI assistant interfaces. Users copy component directories into projects and modify them. Source code is the product—readability over cleverness.\n\n## Commands\n\n```bash\npnpm dev # Dev server (Turbopack)\npnpm build # Production build\npnpm check # Parallel: typecheck + oxlint + eslint + format check\npnpm lint:fix # Fix lint errors (run before committing)\npnpm typecheck # TypeScript checking (tsgo)\npnpm test # Run tests (Vitest)\n```\n\n## Tooling\n\n- **Formatter**: Oxfmt (config: `apps/www/.oxfmtrc.jsonc`) — Tailwind class sorting + import sorting\n- **Linter**: Oxlint (`apps/www/.oxlintrc.json`) handles standard rules; ESLint (`apps/www/eslint.config.ts`) retained only for `no-restricted-syntax`, `no-restricted-imports`, custom `tool-ui/*` rules, and React Compiler hooks\n- **Typecheck**: tsgo (`@typescript/native-preview`) — native TypeScript compiler\n- **Parallel checks**: `pnpm check` runs typecheck + all linters + format in parallel via `npm-run-all2`\n\n## Stack\n\n- **Package manager**: pnpm (required)\n- **Dependencies**: Only shadcn/ui prerequisites (Tailwind, Radix, Lucide)—users shouldn't need new deps\n\n## Architecture\n\n### Component Structure\n\nEach component lives in `apps/www/components/tool-ui/{name}/`. Reference: `apps/www/components/tool-ui/approval-card/`\n\nKey files:\n\n- `index.tsx` — Barrel exports\n- `{name}.tsx` — Main component\n- `schema.ts` — Zod schema + SerializableX types\n- `_adapter.tsx` — shadcn re-exports\n\nThe `shared/` directory contains utilities all components need.\n\n### Documentation Site\n\nInterconnected registries:\n\n- Component metadata: `apps/www/lib/docs/component-registry.ts`\n- Presets (example data): `apps/www/lib/presets/{component}.ts`\n- Preview rendering: `apps/www/lib/docs/preview-config.tsx`\n- Doc pages: `apps/www/app/docs/{component}/content.mdx`\n- Gallery: `apps/www/app/docs/gallery/page.tsx`\n\n## Key Patterns\n\n### Component API\n\n- **Tailwind for layout**: No `maxWidth`/`padding` props—users customize via `className`\n- **Standard widths**: Cards use `min-w-80 max-w-md`, compact components use `max-w-sm`\n- **Flat props**: Avoid nested config objects\n- **Semantic action IDs**: Use `id: \"confirm\"` / `id: \"cancel\"` for local and decision actions\n- **Receipt state**: Use `choice` prop to render confirmed state (e.g., ``)\n\n### Main Component Structure\n\nReference: `apps/www/components/tool-ui/approval-card/approval-card.tsx:183`\n\n- Outer `
` with `data-slot`, `data-tool-ui-id`, `lang=\"en\"`, `aria-busy`\n- Loading skeleton via `isLoading` prop\n- Optional sibling `ToolUI.LocalActions` / `ToolUI.DecisionActions` surfaces\n\n## Discovery\n\n| What | Where |\n| ----------------------- | ------------------------------------------------ |\n| Tool UI components | `apps/www/components/tool-ui/` (scan barrels) |\n| Component docs metadata | `apps/www/lib/docs/component-registry.ts` |\n| Preset configurations | `apps/www/lib/presets/*.ts` |\n| Types & validation | Colocated `schema.ts` files |\n| assistant-ui reference | `private/reference-docs/assistant-ui/` |\n| Design system specs | `private/design-system/` |\n\n## Task Guides\n\n- Adding/modifying components: `.claude/docs/component-workflow.md`\n- Writing doc pages: `.claude/docs/mdx-authoring.md`\n- Copy style for examples: `.claude/docs/copy-guide.md`\n- Writing changelog entries: `apps/www/docs/changelog.md`\n" }, { "path": "LICENSE.md", "content": "MIT License\n\nCopyright (c) 2025 AgentbaseAI Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n" }, { "path": "README.md", "content": "\n \"Tool\n\n\nCopy/paste React components for rendering tool calls in AI chat interfaces. Built by [assistant-ui](https://github.com/assistant-ui).\n\n**[Docs](https://tool-ui.com/docs/overview)** · **[Gallery](https://tool-ui.com/docs/gallery)** · **[Quick Start](https://tool-ui.com/docs/quick-start)**\n\nWhen a model calls a tool, most apps dump raw JSON into the conversation. These components turn tool payloads into interactive UI like approvals, forms, tables, charts, and media cards so users can understand and act without leaving the chat.\n\n## Featured Components\n\n\n \n \n \n \n
\n Option List
\n Let users select from multiple choices

\n \n \"Option\n \n 		\n Question Flow
\n Multi-step guided questions with branching

\n \n \"Question\n \n
\n\n\n## Why Tool UI?\n\n- **Copy/paste, not install** — shadcn/ui model. Components live in your codebase. No dependency lock-in.\n- **Schema-validated** — Every component has a Zod schema. Parse tool output, render when valid, fail safely when not.\n- **Interactive with receipts** — Components aren't just displays. Users make choices that flow back to the assistant. Choices persist as receipts.\n- **Built on shadcn/ui** — Radix primitives, Tailwind styling, your theme. No new design system to learn.\n\n## Components\n\n- **Progress**: Plan, Progress Tracker\n- **Input**: Option List, Parameter Slider, Preferences Panel, Question Flow\n- **Display**: Citation, Geo Map, Item Carousel, Link Preview, Stats Display, Terminal, Weather Widget\n- **Artifacts**: Chart, Code Block, Code Diff, Data Table, Instagram Post, LinkedIn Post, Message Draft, X Post\n- **Confirmation**: Approval Card, Order Summary\n- **Media**: Audio, Image, Image Gallery, Video\n\nEach component includes a Zod schema for payload validation and presets for realistic example data. Browse them all in the [Gallery](https://tool-ui.com/docs/gallery).\n\n\n \"Tool\n\n\n## License\n\nMIT License. See [LICENSE](LICENSE.md) for details.\n" }, { "path": "apps/www/.oxfmtrc.jsonc", "content": "{\n \"$schema\": \"https://raw.githubusercontent.com/nicolo-ribaudo/oxfmt/main/npm/oxfmt/schema.json\",\n\n // Match existing Prettier settings\n \"semi\": true,\n \"singleQuote\": false,\n \"trailingComma\": \"all\",\n \"tabWidth\": 2,\n \"printWidth\": 80,\n\n // Tailwind class sorting (v4 entry point)\n \"tailwindcss\": {\n \"stylesheet\": \"./app/styles/globals.css\",\n \"functions\": [\"clsx\", \"cn\"],\n },\n\n // Import sorting (bonus — Prettier didn't do this)\n \"importSort\": {},\n}\n" }, { "path": "apps/www/.oxlintrc.json", "content": "{\n \"$schema\": \"./node_modules/oxlint/configuration_schema.json\",\n \"plugins\": [\n \"typescript\",\n \"react\",\n \"unicorn\",\n \"oxc\",\n \"import\",\n \"jsx-a11y\",\n \"nextjs\",\n \"vitest\"\n ],\n \"categories\": {\n \"correctness\": \"error\"\n },\n \"rules\": {\n \"@typescript-eslint/no-explicit-any\": \"error\",\n \"no-unused-vars\": [\n \"error\",\n {\n \"ignoreRestSiblings\": true,\n \"argsIgnorePattern\": \"^_\",\n \"varsIgnorePattern\": \"^_\"\n }\n ],\n\n // jsx-a11y: match Next.js defaults (warn, not error) for rules\n // that fire on component library patterns\n \"jsx-a11y/heading-has-content\": \"warn\",\n \"jsx-a11y/anchor-has-content\": \"warn\",\n \"jsx-a11y/media-has-caption\": \"warn\",\n \"jsx-a11y/no-autofocus\": \"warn\",\n \"jsx-a11y/no-static-element-interactions\": \"warn\",\n \"jsx-a11y/click-events-have-key-events\": \"warn\",\n \"jsx-a11y/prefer-tag-over-role\": \"warn\",\n \"jsx-a11y/iframe-has-title\": \"warn\",\n \"jsx-a11y/aria-role\": \"warn\",\n\n // tool-ui components use for portability (not Next.js specific)\n \"nextjs/no-img-element\": \"off\",\n\n // jest rules leak through vitest plugin — disable\n \"jest/valid-expect\": \"off\",\n\n // false positives: \\$ before { in template literals, control chars in sanitizer\n \"no-useless-escape\": \"warn\",\n \"no-control-regex\": \"warn\"\n },\n \"env\": {\n \"browser\": true,\n \"builtin\": true,\n \"es2024\": true,\n \"node\": true\n },\n \"ignorePatterns\": [\n \"**/dist/**\",\n \"**/node_modules/**\",\n \"**/.next/**\",\n \"**/out/**\",\n \"**/next-env.d.ts\",\n \"components/tool-ui/weather-widget/generated/**\"\n ],\n \"settings\": {\n \"next\": {\n \"rootDir\": [\".\"]\n },\n \"react\": {\n \"version\": \"19\"\n }\n }\n}\n" }, { "path": "apps/www/.prettierignore", "content": "# Generated artifacts (managed by build scripts)\n.next/\npublic/r/\ncomponents/tool-ui/weather-widget/generated/\nlib/weather-authoring/weather-widget/effects/generated/\nlib/weather-authoring/weather-widget/weather-data-overlay.generated.ts\n" }, { "path": "apps/www/app/api/builder/chat/route.ts", "content": "import { openai } from \"@ai-sdk/openai\";\nimport { anthropic } from \"@ai-sdk/anthropic\";\nimport { streamText, convertToModelMessages, stepCountIs } from \"ai\";\nimport { experimental_createMCPClient as createMCPClient } from \"@ai-sdk/mcp\";\nimport { StreamableHTTPClientTransport } from \"@modelcontextprotocol/sdk/client/streamableHttp.js\";\nimport { checkRateLimit } from \"@/lib/integrations/rate-limit/upstash\";\nimport { requestDevServer } from \"@/lib/integrations/freestyle/create-chat\";\nimport { SYSTEM_MESSAGE } from \"@/lib/system/tool-builder-message\";\n\nexport const maxDuration = 300;\n\nexport async function POST(req: Request) {\n try {\n if (!process.env.OPENAI_API_KEY && !process.env.ANTHROPIC_API_KEY) {\n return new Response(\n JSON.stringify({\n error:\n \"API key is not configured. Please set OPENAI_API_KEY or ANTHROPIC_API_KEY in your environment variables.\",\n }),\n {\n status: 500,\n headers: { \"Content-Type\": \"application/json\" },\n },\n );\n }\n\n const ip =\n req.headers.get(\"x-forwarded-for\")?.split(\",\")[0] ||\n req.headers.get(\"x-real-ip\") ||\n \"anonymous\";\n\n const rateLimitResult = await checkRateLimit(ip);\n\n if (!rateLimitResult.success) {\n return new Response(\n JSON.stringify({\n error: \"Rate limit exceeded. Please try again later.\",\n reset: rateLimitResult.reset,\n }),\n {\n status: 429,\n headers: {\n \"Content-Type\": \"application/json\",\n \"X-RateLimit-Limit\": rateLimitResult.limit.toString(),\n \"X-RateLimit-Remaining\": rateLimitResult.remaining.toString(),\n \"X-RateLimit-Reset\": rateLimitResult.reset.toString(),\n },\n },\n );\n }\n\n const { messages } = await req.json();\n const repoId = req.headers.get(\"Repo-Id\");\n\n if (!messages || !Array.isArray(messages)) {\n return new Response(\n JSON.stringify({ error: \"Invalid request: messages array required\" }),\n {\n status: 400,\n headers: { \"Content-Type\": \"application/json\" },\n },\n );\n }\n\n const modelMessages = await convertToModelMessages(messages);\n\n // Choose model based on what's available\n const model = process.env.ANTHROPIC_API_KEY\n ? anthropic(\"claude-sonnet-4-5-20250929\")\n : openai(\"gpt-5-nano\");\n\n // If we have a repoId and Freestyle is configured, use Freestyle tools\n let tools = {};\n if (repoId && process.env.FREESTYLE_API_KEY) {\n try {\n const { mcpEphemeralUrl } = await requestDevServer({ repoId });\n\n if (mcpEphemeralUrl) {\n const devServerMcp = await createMCPClient({\n transport: new StreamableHTTPClientTransport(\n new URL(mcpEphemeralUrl),\n ),\n });\n\n tools = await devServerMcp.tools();\n }\n } catch (error) {\n console.error(\"Error setting up Freestyle MCP:\", error);\n // Continue without Freestyle tools if there's an error\n }\n }\n\n const result = streamText({\n model,\n messages: modelMessages,\n system: SYSTEM_MESSAGE,\n tools,\n stopWhen: stepCountIs(100),\n temperature: 0.7,\n });\n\n result.consumeStream();\n\n return result.toUIMessageStreamResponse();\n } catch (error) {\n console.error(\"Error in builder chat API route:\", error);\n return new Response(\n JSON.stringify({\n error: \"An error occurred while processing your request.\",\n }),\n {\n status: 500,\n headers: { \"Content-Type\": \"application/json\" },\n },\n );\n }\n}\n" }, { "path": "apps/www/app/api/builder/create-freestyle/route.ts", "content": "import { createChat } from \"@/lib/integrations/freestyle/create-chat\";\n\nexport async function POST() {\n try {\n if (!process.env.FREESTYLE_API_KEY) {\n return new Response(\n JSON.stringify({\n error:\n \"Freestyle API key is not configured. Please set FREESTYLE_API_KEY in your environment variables.\",\n }),\n {\n status: 500,\n headers: { \"Content-Type\": \"application/json\" },\n },\n );\n }\n\n const { repoId, ephemeralUrl, mcpEphemeralUrl } = await createChat();\n\n return new Response(\n JSON.stringify({\n repoId,\n ephemeralUrl,\n mcpEphemeralUrl,\n }),\n {\n status: 200,\n headers: { \"Content-Type\": \"application/json\" },\n },\n );\n } catch (error) {\n console.error(\"Error creating Freestyle project:\", error);\n return new Response(\n JSON.stringify({\n error: \"Failed to create Freestyle project.\",\n }),\n {\n status: 500,\n headers: { \"Content-Type\": \"application/json\" },\n },\n );\n }\n}\n" }, { "path": "apps/www/app/api/chat/route.ts", "content": "import { openai } from \"@ai-sdk/openai\";\nimport { streamText, convertToModelMessages, tool } from \"ai\";\nimport { z } from \"zod\";\nimport { checkRateLimit } from \"@/lib/integrations/rate-limit/upstash\";\nimport { getMockTasks } from \"@/lib/mocks/tasks\";\nimport { STATS_DISPLAY_DATA } from \"@/lib/mocks/chat-showcase-data\";\n\nexport const runtime = \"edge\";\n\nconst DEMO_SYSTEM_PROMPT = `You are a helpful assistant that showcases the power of Tool UI—a copy-paste component library for AI assistant interfaces.\n\nYour role is to demonstrate how AI assistants can render rich, interactive UIs in chat. Use the available tools proactively and enthusiastically when they fit the user's request.\n\n## Tools and when to use them\n\n- **show_plan**: Present a step-by-step plan for multi-step tasks. Use when the user asks for a plan, workflow, checklist, deployment steps, research approach, or \"how do I\" questions that break down into phases.\n- **get_tasks**: Retrieve and display support tickets or task lists. Use when the user asks about tickets, tasks, support queue, what's open, or wants to see a table of work items.\n- **show_stats**: Display key metrics and KPIs. Use when the user asks about performance, revenue, dashboards, quarterly numbers, or business metrics.\n- **show_terminal**: Show command-line output (test results, logs, build output). Use when the user asks to run tests, show terminal output, execute a command, or see build/log output.\n\n## Guidelines\n\n- Be concise and friendly. Add a short preamble before or after tool output—don't repeat what the UI already shows.\n- NEVER describe or assume data without calling the tool. Always invoke the tool first—the tool returns real data.\n- When the user asks to see support tickets, tasks, or a queue → ALWAYS call get_tasks.\n- When the user asks for a plan, deployment steps, or a checklist → ALWAYS call show_plan.\n- When the user asks about Q4, metrics, revenue, or dashboards → ALWAYS call show_stats.\n- When the user asks to run tests, execute a command, or show terminal output → ALWAYS call show_terminal.\n- When using show_plan, create relevant plans (e.g. \"Deploy to production\", \"Research competitors\").\n- When using get_tasks, the tool returns a support ticket queue. Present it with a brief intro.\n- When get_tasks returns an empty list (no tickets), you MUST add a friendly message such as: \"It looks like there are currently no support tickets in the system. If you need assistance with anything else, feel free to ask!\"\n- When using show_stats, the tool returns Q4 metrics. Present it with a brief intro.\n- When using show_terminal, create realistic output for commands like \"pnpm test auth\", \"npm run build\".\n- Keep responses brief—let the Tool UI components do the visual heavy lifting.`;\n\nexport async function POST(req: Request) {\n try {\n if (!process.env.OPENAI_API_KEY) {\n return new Response(\n JSON.stringify({\n error:\n \"OpenAI API key is not configured. Please set OPENAI_API_KEY in your environment variables.\",\n }),\n {\n status: 500,\n headers: { \"Content-Type\": \"application/json\" },\n },\n );\n }\n\n const ip =\n req.headers.get(\"x-forwarded-for\")?.split(\",\")[0] ||\n req.headers.get(\"x-real-ip\") ||\n \"anonymous\";\n\n const rateLimitResult = await checkRateLimit(ip);\n\n if (!rateLimitResult.success) {\n return new Response(\n JSON.stringify({\n error: \"Rate limit exceeded. Please try again later.\",\n reset: rateLimitResult.reset,\n }),\n {\n status: 429,\n headers: {\n \"Content-Type\": \"application/json\",\n \"X-RateLimit-Limit\": rateLimitResult.limit.toString(),\n \"X-RateLimit-Remaining\": rateLimitResult.remaining.toString(),\n \"X-RateLimit-Reset\": rateLimitResult.reset.toString(),\n },\n },\n );\n }\n\n const { messages } = await req.json();\n\n if (!messages || !Array.isArray(messages)) {\n return new Response(\n JSON.stringify({ error: \"Invalid request: messages array required\" }),\n {\n status: 400,\n headers: { \"Content-Type\": \"application/json\" },\n },\n );\n }\n\n const modelMessages = await convertToModelMessages(messages);\n\n const result = streamText({\n model: openai(\"gpt-4o-mini\"),\n messages: modelMessages,\n system: DEMO_SYSTEM_PROMPT,\n tools: {\n show_plan: tool({\n description:\n \"Present a step-by-step plan for the user to follow. Use for workflows, checklists, deployment steps, research plans, or any multi-phase task.\",\n inputSchema: z.object({\n title: z.string().describe(\"Short title for the plan\"),\n description: z.string().optional().describe(\"Context or goal\"),\n todos: z\n .array(\n z.object({\n id: z.string(),\n label: z.string(),\n status: z\n .enum([\"pending\", \"in_progress\", \"completed\", \"cancelled\"])\n .default(\"pending\"),\n description: z.string().optional(),\n }),\n )\n .min(1)\n .describe(\"Steps in order\"),\n }),\n execute: async ({ title, description, todos }) => {\n return {\n id: `plan-${Date.now()}`,\n title,\n description: description ?? title,\n todos: todos.map((t) => ({\n ...t,\n status: t.status ?? \"pending\",\n })),\n };\n },\n }),\n get_tasks: tool({\n description:\n \"Retrieve the support ticket queue and display it in a sortable table. Use when the user asks about tickets, tasks, support queue, or open work.\",\n inputSchema: z.object({\n assignee: z\n .string()\n .optional()\n .describe('Filter by assignee name (e.g. \"Chen\", \"Patel\")'),\n }),\n execute: async ({ assignee }) => {\n const tasks = await getMockTasks({ assignee });\n const rank = { high: 1, medium: 2, low: 3 } as const;\n const sorted = [...tasks].sort((a, b) => {\n const byUrgency = rank[a.priority] - rank[b.priority];\n if (byUrgency !== 0) return byUrgency;\n return (\n new Date(b.created).getTime() - new Date(a.created).getTime()\n );\n });\n\n const columns = [\n {\n key: \"priority\",\n label: \"Urgency\",\n format: {\n kind: \"status\" as const,\n statusMap: {\n high: { tone: \"danger\" as const, label: \"High\" },\n medium: { tone: \"warning\" as const, label: \"Medium\" },\n low: { tone: \"neutral\" as const, label: \"Low\" },\n },\n },\n },\n {\n key: \"issue\",\n label: \"Issue\",\n truncate: true,\n priority: \"primary\" as const,\n },\n {\n key: \"customer\",\n label: \"Customer\",\n priority: \"primary\" as const,\n },\n {\n key: \"status\",\n label: \"Status\",\n format: {\n kind: \"badge\" as const,\n colorMap: {\n open: \"info\",\n \"in-progress\": \"warning\",\n waiting: \"neutral\",\n done: \"success\",\n },\n },\n },\n { key: \"assignee\", label: \"Owner\" },\n {\n key: \"created\",\n label: \"Created\",\n format: {\n kind: \"date\" as const,\n dateFormat: \"relative\" as const,\n },\n hideOnMobile: true,\n },\n ];\n\n const data = sorted.map((t) => ({\n id: t.id,\n issue: t.issue,\n customer: t.customer,\n priority: t.priority,\n status: t.status,\n assignee: t.assignee,\n created: t.created,\n urgencyOrder:\n t.priority === \"high\" ? 1 : t.priority === \"medium\" ? 2 : 3,\n }));\n\n return {\n id: `tasks-${Date.now()}`,\n columns,\n data,\n rowIdKey: \"id\",\n defaultSort: { by: \"urgencyOrder\", direction: \"asc\" as const },\n };\n },\n }),\n show_stats: tool({\n description:\n \"Display key metrics and KPIs in a visual stats grid. Use when the user asks about performance, revenue, dashboards, quarterly numbers, or business metrics.\",\n inputSchema: z.object({}),\n execute: async () => {\n return {\n id: `stats-${Date.now()}`,\n ...STATS_DISPLAY_DATA,\n };\n },\n }),\n show_terminal: tool({\n description:\n \"Show command-line output (test results, logs, build output). Use when the user asks to run tests, execute a command, show terminal output, or see build/log results.\",\n inputSchema: z.object({\n command: z.string().describe(\"The command that was run\"),\n stdout: z.string().describe(\"The terminal output\"),\n exitCode: z.number().describe(\"Exit code (0 = success)\"),\n durationMs: z.number().optional().describe(\"Execution time in ms\"),\n }),\n execute: async ({ command, stdout, exitCode, durationMs }) => {\n return {\n id: `terminal-${Date.now()}`,\n command,\n stdout,\n exitCode,\n durationMs,\n };\n },\n }),\n },\n temperature: 0.7,\n });\n\n return result.toUIMessageStreamResponse();\n } catch (error) {\n console.error(\"Error in chat API route:\", error);\n return new Response(\n JSON.stringify({\n error: \"An error occurred while processing your request.\",\n }),\n {\n status: 500,\n headers: { \"Content-Type\": \"application/json\" },\n },\n );\n }\n}\n" }, { "path": "apps/www/app/api/mcp-tools/route.ts", "content": "import { experimental_createMCPClient as createMCPClient } from \"@ai-sdk/mcp\";\n\nexport const runtime = \"edge\";\n\ninterface MCPTool {\n name: string;\n description?: string;\n inputSchema: {\n type: string;\n properties?: Record;\n required?: string[];\n };\n}\n\nexport async function POST(req: Request) {\n try {\n const { serverUrl, transportType = \"http\" } = await req.json();\n\n if (!serverUrl || typeof serverUrl !== \"string\") {\n return new Response(\n JSON.stringify({ error: \"Invalid request: serverUrl is required\" }),\n {\n status: 400,\n headers: { \"Content-Type\": \"application/json\" },\n },\n );\n }\n\n // Validate URL format\n try {\n new URL(serverUrl);\n } catch {\n return new Response(\n JSON.stringify({\n error: \"Invalid URL format\",\n }),\n {\n status: 400,\n headers: { \"Content-Type\": \"application/json\" },\n },\n );\n }\n\n // Use Vercel AI SDK's MCP client\n console.log(\n `[MCP] Creating MCP client for ${serverUrl} with transport: ${transportType}`,\n );\n\n try {\n const mcpClient = await createMCPClient({\n transport: {\n type: transportType as \"http\" | \"sse\",\n url: serverUrl,\n },\n });\n\n console.log(`[MCP] Client created, fetching tools...`);\n const tools = await mcpClient.tools();\n console.log(`[MCP] Received ${Object.keys(tools).length} tools`);\n\n // Convert AI SDK tool format to our format\n const mcpTools: MCPTool[] = Object.entries(tools).map(([name, tool]) => ({\n name,\n description: tool.description,\n inputSchema: tool.inputSchema as unknown as {\n type: string;\n properties?: Record;\n required?: string[];\n },\n }));\n\n // Close the client\n await mcpClient.close();\n\n return new Response(\n JSON.stringify({\n tools: mcpTools,\n serverUrl,\n count: mcpTools.length,\n }),\n {\n status: 200,\n headers: { \"Content-Type\": \"application/json\" },\n },\n );\n } catch (error) {\n console.error(`[MCP] Error with AI SDK client:`, error);\n\n return new Response(\n JSON.stringify({\n error: `Could not connect to MCP server: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n }),\n {\n status: 500,\n headers: { \"Content-Type\": \"application/json\" },\n },\n );\n }\n } catch (error) {\n console.error(\"Error fetching MCP tools:\", error);\n return new Response(\n JSON.stringify({\n error: \"An error occurred while fetching MCP tools\",\n details: error instanceof Error ? error.message : \"Unknown error\",\n }),\n {\n status: 500,\n headers: { \"Content-Type\": \"application/json\" },\n },\n );\n }\n}\n" }, { "path": "apps/www/app/api/playground/chat/route.ts", "content": "import type { NextRequest } from \"next/server\";\n\nimport type { UIMessage } from \"ai\";\n\nimport { findPrototype, streamPrototypeResponse } from \"@/lib/playground\";\nimport { PROTOTYPE_SLUG_HEADER } from \"@/lib/playground/constants\";\n\nconst isUiMessageArray = (value: unknown): value is UIMessage[] =>\n Array.isArray(value);\n\nconst extractSlug = (request: NextRequest): string | null => {\n const headerSlug = request.headers.get(PROTOTYPE_SLUG_HEADER)?.trim();\n if (headerSlug) {\n return headerSlug;\n }\n const url = new URL(request.url);\n const querySlug = url.searchParams.get(\"slug\")?.trim();\n if (querySlug) {\n return querySlug;\n }\n return null;\n};\n\nexport async function POST(request: NextRequest) {\n const slug = extractSlug(request);\n if (!slug) {\n return new Response(JSON.stringify({ error: \"Missing prototype slug.\" }), {\n status: 400,\n headers: { \"Content-Type\": \"application/json\" },\n });\n }\n\n const prototype = findPrototype(slug);\n if (!prototype) {\n return new Response(\n JSON.stringify({ error: `Prototype \"${slug}\" not found.` }),\n {\n status: 404,\n headers: { \"Content-Type\": \"application/json\" },\n },\n );\n }\n\n let body: unknown;\n try {\n body = await request.json();\n } catch {\n return new Response(JSON.stringify({ error: \"Invalid JSON body.\" }), {\n status: 400,\n headers: { \"Content-Type\": \"application/json\" },\n });\n }\n\n const messages =\n typeof body === \"object\" && body !== null && \"messages\" in body\n ? (body as Record).messages\n : undefined;\n\n if (!isUiMessageArray(messages)) {\n return new Response(\n JSON.stringify({ error: \"Request body must include a messages array.\" }),\n {\n status: 400,\n headers: { \"Content-Type\": \"application/json\" },\n },\n );\n }\n\n if (process.env.NODE_ENV !== \"production\") {\n try {\n const lastAssistantWithTools = [...messages]\n .reverse()\n .find(\n (message) =>\n message.role === \"assistant\" &&\n Array.isArray(message.parts) &&\n message.parts.some(\n (part) =>\n typeof part?.type === \"string\" && part.type.startsWith(\"tool-\"),\n ),\n );\n if (lastAssistantWithTools) {\n const toolParts = lastAssistantWithTools.parts?.filter(\n (part) =>\n typeof part?.type === \"string\" && part.type.startsWith(\"tool-\"),\n );\n console.debug(\n \"[playground] forwarding tool parts:\",\n JSON.stringify(toolParts, null, 2),\n );\n }\n } catch (error) {\n console.warn(\"[playground] failed to log tool parts\", error);\n }\n }\n\n // Extract frontend tools from request body\n const clientTools: unknown =\n typeof body === \"object\" && body !== null && \"tools\" in body\n ? (body as Record).tools\n : undefined;\n\n const result = await streamPrototypeResponse(\n prototype,\n messages,\n clientTools,\n );\n return result.toUIMessageStreamResponse();\n}\n" }, { "path": "apps/www/app/api/weather-tuning/_lib/tuned-presets-io.ts", "content": "import { readFile } from \"fs/promises\";\nimport path from \"path\";\n\nimport type { WeatherEffectsTunedPresets } from \"../../../../lib/weather-authoring/weather-widget/effects/tuning\";\n\nexport const TOOL_UI_TUNED_PRESETS_PATH = path.join(\n process.cwd(),\n \"lib/weather-authoring/presets/tuned-presets.json\",\n);\n\nexport async function readToolUiTunedPresetsFromDisk(): Promise {\n const source = await readFile(TOOL_UI_TUNED_PRESETS_PATH, \"utf8\");\n return JSON.parse(source) as WeatherEffectsTunedPresets;\n}\n" }, { "path": "apps/www/app/api/weather-tuning/apply/route.ts", "content": "import { writeFile } from \"fs/promises\";\n\nimport type { WeatherConditionCode } from \"../../../../lib/weather-authoring/weather-widget/schema\";\nimport type { CheckpointOverrides } from \"../../../sandbox/weather-compositor/presets\";\nimport {\n buildCanonicalToolUiPresetsForEditedConditions,\n replaceEditedConditions,\n} from \"../../../sandbox/weather-tuning/lib/tool-ui-export\";\nimport type { WeatherEffectsTunedPresets } from \"../../../../lib/weather-authoring/weather-widget/effects/tuning\";\nimport {\n canonicalizeWeatherPresetData,\n writeWeatherRuntimeArtifacts,\n} from \"../../../../lib/weather-codegen/compile-weather-runtime\";\nimport {\n readToolUiTunedPresetsFromDisk,\n TOOL_UI_TUNED_PRESETS_PATH,\n} from \"../_lib/tuned-presets-io\";\nimport { mapToolUiPresetsToCompositor } from \"../../../sandbox/weather-tuning/lib/tool-ui-import\";\n\nexport const runtime = \"nodejs\";\n\nexport async function POST(request: Request) {\n if (process.env.NODE_ENV === \"production\") {\n return new Response(\"Disabled in production.\", { status: 403 });\n }\n\n type ApplyPayload = {\n checkpointOverrides?: Partial<\n Record\n >;\n signedOff?: WeatherConditionCode[];\n };\n\n let payload: ApplyPayload | null = null;\n try {\n payload = (await request.json()) as ApplyPayload;\n } catch {\n return new Response(\"Invalid JSON payload.\", { status: 400 });\n }\n\n if (\n !payload?.checkpointOverrides ||\n typeof payload.checkpointOverrides !== \"object\"\n ) {\n return new Response(\"Missing 'checkpointOverrides' field.\", {\n status: 400,\n });\n }\n\n if (Object.keys(payload.checkpointOverrides).length === 0) {\n return new Response(\"No tuning changes to apply.\", { status: 400 });\n }\n\n let base: WeatherEffectsTunedPresets;\n try {\n base = await readToolUiTunedPresetsFromDisk();\n } catch (error) {\n console.warn(\n \"Failed to read current tuned presets; falling back to empty.\",\n error,\n );\n base = {};\n }\n\n const repoCheckpointOverrides = mapToolUiPresetsToCompositor(base);\n const canonicalEditedConditions =\n buildCanonicalToolUiPresetsForEditedConditions(\n payload.checkpointOverrides,\n repoCheckpointOverrides,\n );\n\n if (Object.keys(canonicalEditedConditions).length === 0) {\n return new Response(\"No tuning changes to apply.\", { status: 400 });\n }\n\n const merged = replaceEditedConditions(base, canonicalEditedConditions);\n const canonicalMerged = canonicalizeWeatherPresetData(\n merged,\n ) as WeatherEffectsTunedPresets;\n const content = `${JSON.stringify(canonicalMerged, null, 2)}\\n`;\n await writeFile(TOOL_UI_TUNED_PRESETS_PATH, content, \"utf8\");\n const generated = await writeWeatherRuntimeArtifacts(process.cwd());\n\n const updatedArtifacts = [\n \"lib/weather-authoring/presets/tuned-presets.json\",\n ...generated.written,\n ];\n\n return Response.json({\n ok: true,\n path: \"lib/weather-authoring/presets/tuned-presets.json\",\n updatedArtifacts,\n checkpointOverrides: mapToolUiPresetsToCompositor(canonicalMerged),\n });\n}\n" }, { "path": "apps/www/app/api/weather-tuning/recover/route.ts", "content": "import { mapToolUiPresetsToCompositor } from \"../../../sandbox/weather-tuning/lib/tool-ui-import\";\nimport { readToolUiTunedPresetsFromDisk } from \"../_lib/tuned-presets-io\";\n\nexport const runtime = \"nodejs\";\n\nexport async function GET() {\n if (process.env.NODE_ENV === \"production\") {\n return new Response(\"Disabled in production.\", { status: 403 });\n }\n\n try {\n const presets = await readToolUiTunedPresetsFromDisk();\n const checkpointOverrides = mapToolUiPresetsToCompositor(presets);\n return Response.json({ ok: true, checkpointOverrides });\n } catch (error) {\n console.error(\"Failed to recover tuning from repo presets.\", error);\n return new Response(\"Failed to recover tuning from repo presets.\", {\n status: 500,\n });\n }\n}\n" }, { "path": "apps/www/app/builder/layout.tsx", "content": "import type { ReactNode } from \"react\";\nimport ContentLayout from \"@/app/components/layout/page-shell\";\nimport { HeaderFrame } from \"@/app/components/layout/app-shell\";\nimport { ThemeToggle } from \"@/app/components/builder/theme-toggle\";\n\nexport default function BuilderLayout({ children }: { children: ReactNode }) {\n return (\n }>\n {children}\n \n );\n}\n" }, { "path": "apps/www/app/builder/opengraph-image.tsx", "content": "import {\n generateOgImage,\n size as ogSize,\n contentType as ogContentType,\n} from \"@/lib/og/og-image\";\n\nexport const runtime = \"nodejs\";\nexport const alt = \"Tool UI - Builder\";\nexport const size = ogSize;\nexport const contentType = ogContentType;\n\nexport default async function Image() {\n return generateOgImage(\"Builder\", \"Construct components visually\");\n}\n" }, { "path": "apps/www/app/builder/page.tsx", "content": "\"use client\";\n\nimport {\n AssistantRuntimeProvider,\n ThreadPrimitive,\n ComposerPrimitive,\n MessagePrimitive,\n useAui,\n useAuiState,\n makeAssistantToolUI,\n ActionBarPrimitive,\n BranchPickerPrimitive,\n ErrorPrimitive,\n makeAssistantTool,\n} from \"@assistant-ui/react\";\nimport {\n useChatRuntime,\n AssistantChatTransport,\n} from \"@assistant-ui/react-ai-sdk\";\nimport { ThreadList } from \"@/app/components/assistant-ui/thread-list\";\nimport { MarkdownText } from \"@/app/components/assistant-ui/markdown-text\";\nimport WebView from \"@/app/components/builder/webview\";\nimport {\n ArrowUpIcon,\n Square,\n Loader2,\n Eye,\n Code,\n Copy,\n Check,\n PencilIcon,\n RefreshCw,\n FileEdit,\n FileText,\n CopyIcon,\n CheckIcon,\n RefreshCwIcon,\n ChevronLeftIcon,\n ChevronRightIcon,\n ConstructionIcon,\n} from \"lucide-react\";\nimport { MCPIcon } from \"@/app/components/builder/mcp-icon\";\nimport { Button } from \"@/components/ui/button\";\nimport { CodeBlock, CodeBlockCode } from \"@/components/ui/code-block\";\nimport { getComponentCode } from \"@/lib/integrations/freestyle/get-code\";\nimport {\n Card,\n CardHeader,\n CardTitle,\n CardDescription,\n CardContent,\n} from \"@/components/ui/card\";\nimport {\n Dialog,\n DialogContent,\n DialogHeader,\n DialogTitle,\n} from \"@/components/ui/dialog\";\nimport {\n InputGroup,\n InputGroupInput,\n InputGroupAddon,\n} from \"@/components/ui/input-group\";\nimport {\n Select,\n SelectContent,\n SelectItem,\n SelectTrigger,\n SelectValue,\n} from \"@/components/ui/select\";\nimport { useState, useEffect, type FC, createContext, useContext } from \"react\";\nimport { ToolFallback } from \"@/app/components/assistant-ui/tool-fallback\";\nimport { TooltipIconButton } from \"@/app/components/assistant-ui/tooltip-icon-button\";\nimport React from \"react\";\nimport { cn } from \"@/lib/ui/cn\";\n\n// Context for refreshing the preview pane\nconst PreviewRefreshContext = createContext<(() => void) | null>(null);\n\nconst usePreviewRefresh = () => {\n const refresh = useContext(PreviewRefreshContext);\n return refresh;\n};\n\n// Module-level holder for the refresh function (accessible from streamCall)\nlet globalRefreshPreview: (() => void) | null = null;\n\nconst PreviewRefreshSetter: FC = () => {\n const refresh = usePreviewRefresh();\n useEffect(() => {\n globalRefreshPreview = refresh;\n return () => {\n globalRefreshPreview = null;\n };\n }, [refresh]);\n return null;\n};\n\nconst UserMessage: FC = () => {\n return (\n *)]:col-start-2\">\n
\n
\n \n
\n
\n \n
\n
\n \n \n );\n};\n\nconst AssistantMessage: FC = () => {\n return (\n \n
\n \n \n
\n
\n \n \n
\n \n );\n};\n\nconst MessageError: FC = () => {\n return (\n \n \n \n \n \n );\n};\n\nconst UserActionBar: FC = () => {\n return (\n \n \n \n \n \n \n \n );\n};\n\nconst AssistantActionBar: FC = () => {\n return (\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n );\n};\n\nconst BranchPicker: FC = ({\n className,\n ...rest\n}) => {\n return (\n \n \n \n \n \n \n \n / \n \n \n \n \n \n \n \n );\n};\n\nconst EditComposer: FC = () => {\n return (\n
\n \n \n\n
\n \n \n \n \n \n \n
\n \n
\n );\n};\n\ninterface MCPTool {\n name: string;\n description?: string;\n inputSchema: {\n type: string;\n properties?: Record;\n required?: string[];\n };\n}\n\nconst MCPModal: FC<{\n open: boolean;\n onOpenChange: (open: boolean) => void;\n}> = ({ open, onOpenChange }) => {\n const aui = useAui();\n const [mcpUrl, setMcpUrl] = useState(\"\");\n const [transportType, setTransportType] = useState<\"http\" | \"sse\">(\"http\");\n const [tools, setTools] = useState([]);\n const [loading, setLoading] = useState(false);\n const [error, setError] = useState(null);\n\n // Auto-detect transport type based on URL\n useEffect(() => {\n if (mcpUrl.toLowerCase().endsWith(\"/sse\")) {\n setTransportType(\"sse\");\n } else {\n setTransportType(\"http\");\n }\n }, [mcpUrl]);\n\n const loadTools = async () => {\n if (!mcpUrl.trim()) return;\n\n setLoading(true);\n setError(null);\n\n try {\n const response = await fetch(\"/api/mcp-tools\", {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\" },\n body: JSON.stringify({\n serverUrl: mcpUrl,\n transportType,\n }),\n });\n\n const data = await response.json();\n\n if (!response.ok) {\n throw new Error(data.error || \"Failed to fetch tools\");\n }\n\n setTools(data.tools || []);\n } catch (err) {\n setError(err instanceof Error ? err.message : \"Failed to fetch tools\");\n setTools([]);\n } finally {\n setLoading(false);\n }\n };\n\n const handleGenerateUI = (tool: MCPTool) => {\n // Create a formatted prompt with tool information\n const prompt = `Please create a Tool UI component for the following MCP tool:\n\n**Tool Name:** ${tool.name}\n\n**Description:** ${tool.description || \"No description provided\"}\n\n**Full Schema:**\n\\`\\`\\`json\n${JSON.stringify(tool.inputSchema, null, 2)}\n\\`\\`\\``;\n\n // Send the message to the current thread\n aui.thread().append({\n role: \"user\",\n content: [{ type: \"text\", text: prompt }],\n });\n\n // Close the modal\n onOpenChange(false);\n };\n\n return (\n \n \n \n Import MCP Tool\n \n\n
\n \n setMcpUrl(e.target.value)}\n onKeyDown={(e) => {\n if (e.key === \"Enter\") {\n loadTools();\n }\n }}\n />\n \n \n setTransportType(value)\n }\n >\n \n \n \n \n HTTP\n SSE\n \n \n \n \n \n
\n\n {error && (\n
\n {error}\n
\n )}\n\n
\n {tools.length === 0 ? (\n
\n {loading ? \"Loading tools...\" : \"No tools loaded\"}\n
\n ) : (\n
\n {tools.map((tool) => (\n \n
\n
{tool.name}
\n {tool.description && (\n
\n {tool.description}\n
\n )}\n
\n handleGenerateUI(tool)}\n className=\"shrink-0\"\n >\n Generate UI\n \n
\n ))}\n
\n )}\n \n \n \n );\n};\n\nconst Composer: FC = () => {\n const [mcpModalOpen, setMcpModalOpen] = useState(false);\n const isNewThread = useAuiState(\n ({ threadListItem }) => threadListItem.status === \"new\",\n );\n\n return (\n <>\n \n
\n \n \n
\n
\n {isNewThread && (\n setMcpModalOpen(true)}\n >\n \n MCP\n \n )}\n
\n
\n \n \n \n \n \n \n \n\n \n \n \n \n \n \n \n
\n
\n \n
\n \n \n This builder is under heavy construction and may not always work as\n expected.\n \n
\n
\n \n );\n};\n\nconst Thread: FC = () => {\n return (\n \n \n \n
\n \n
\n \n \n \n
\n \n \n \n \n );\n};\n\ntype ViewMode = \"rendered\" | \"code\";\n\nexport default function BuilderPage() {\n const [repoId, setRepoId] = useState(null);\n const repoIdRef = useState({ current: repoId })[0];\n const [_appId, setAppId] = useState(null);\n const [webviewWidth, setWebviewWidth] = useState(50); // percentage\n const [viewMode, setViewMode] = useState(\"rendered\");\n const [codeContent, setCodeContent] = useState(null);\n const [isCodeLoading, setIsCodeLoading] = useState(false);\n const [copied, setCopied] = useState(false);\n const [refreshKey, setRefreshKey] = useState(0);\n const timestampRef = useState(() => Date.now())[0];\n\n // Keep ref in sync with state\n repoIdRef.current = repoId;\n\n // Load code when switching to code view\n useEffect(() => {\n if (viewMode === \"code\" && repoId && !codeContent) {\n setIsCodeLoading(true);\n getComponentCode(repoId, \"components/demo-tool-ui.tsx\")\n .then((content) => {\n setCodeContent(content);\n setIsCodeLoading(false);\n })\n .catch((err) => {\n console.error(\"Failed to load code:\", err);\n setIsCodeLoading(false);\n });\n }\n }, [viewMode, repoId, codeContent]);\n\n const runtime = useChatRuntime({\n transport: new AssistantChatTransport({\n api: \"/api/builder/chat\",\n headers: async () => {\n // Auto-create Freestyle project on first message if not already created\n if (\n !repoIdRef.current &&\n process.env.NEXT_PUBLIC_FREESTYLE_ENABLED !== \"false\"\n ) {\n try {\n const response = await fetch(\"/api/builder/create-freestyle\", {\n method: \"POST\",\n });\n\n if (response.ok) {\n const data = await response.json();\n setRepoId(data.repoId);\n repoIdRef.current = data.repoId;\n // Use a unique ID for this app instance\n setAppId(data.repoId + \"-\" + timestampRef);\n }\n } catch (error) {\n console.error(\"Failed to create Freestyle project:\", error);\n }\n }\n\n return {\n \"Repo-Id\": repoIdRef.current || \"\",\n };\n },\n }),\n });\n\n const handleCopy = async () => {\n if (!codeContent) return;\n\n try {\n await navigator.clipboard.writeText(codeContent);\n setCopied(true);\n setTimeout(() => setCopied(false), 2000);\n } catch (err) {\n console.error(\"Failed to copy:\", err);\n }\n };\n\n const handleMouseDown = (e: React.MouseEvent) => {\n e.preventDefault();\n const startX = e.clientX;\n const startWidth = webviewWidth;\n const containerWidth = window.innerWidth - 240; // Subtract sidebar width\n\n const handleMouseMove = (e: MouseEvent) => {\n const diff = startX - e.clientX;\n const percentageChange = (diff / containerWidth) * 100;\n const newWidth = Math.min(\n Math.max(startWidth + percentageChange, 20),\n 80,\n );\n setWebviewWidth(newWidth);\n };\n\n const handleMouseUp = () => {\n document.removeEventListener(\"mousemove\", handleMouseMove);\n document.removeEventListener(\"mouseup\", handleMouseUp);\n };\n\n document.addEventListener(\"mousemove\", handleMouseMove);\n document.addEventListener(\"mouseup\", handleMouseUp);\n };\n\n const handleRefreshPreview = () => {\n setRefreshKey((prev) => prev + 1);\n };\n\n return (\n \n \n \n
\n {/* Thread List Sidebar - hidden on mobile */}\n \n\n {/* Main Thread Area */}\n \n \n
\n\n {/* Preview/Code Panel */}\n {repoId && (\n <>\n {/* Resize Handle - hidden on mobile */}\n
\n \n )}\n \n \n \n \n \n \n );\n}\n\nconst EditFileToolUI = makeAssistantTool<\n {\n path?: string;\n edits?: Array<{\n oldText?: string;\n newText?: string;\n }>;\n },\n {}\n>({\n type: \"backend\",\n toolName: \"edit_file\",\n streamCall: async (reader) => {\n await reader.response.get();\n\n // Refresh the preview pane after edit completes\n if (globalRefreshPreview) {\n globalRefreshPreview();\n }\n },\n render: ({ args }) => {\n console.log(\"EditFileToolUI\", args);\n const path = args?.path;\n const edits = args?.edits;\n\n if (!path && (!edits || edits.length === 0)) {\n return null;\n }\n\n return (\n \n \n
\n \n Editing File\n
\n {path && (\n \n {path}\n \n )}\n \n {edits && edits.length > 0 && (\n \n
\n {edits.map(\n (edit, index) =>\n (edit.oldText || edit.newText) && (\n \n {edit.oldText && (\n <>\n pre]:py-0\"\n />\n {edit.oldText.split(\"\\n\").length > 5 && (\n
\n +{edit.oldText.split(\"\\n\").length - 5} more\n
\n )}\n \n )}\n {edit.newText && (\n <>\n pre]:py-0\"\n />\n {edit.newText.split(\"\\n\").length > 5 && (\n
\n +{edit.newText.split(\"\\n\").length - 5} more\n
\n )}\n \n )}\n \n ),\n )}\n
\n \n )}\n \n );\n },\n});\n\nconst WriteFileToolUI = makeAssistantTool<\n {\n path?: string;\n content?: string;\n },\n {}\n>({\n type: \"backend\",\n toolName: \"write_file\",\n streamCall: async (reader) => {\n await reader.response.get();\n\n // Refresh the preview pane after write completes\n if (globalRefreshPreview) {\n globalRefreshPreview();\n }\n },\n render: ({ args }) => {\n const path = args?.path;\n\n if (!path) {\n return null;\n }\n\n return (\n \n \n
\n \n Writing File\n
\n \n {path}\n \n \n \n );\n },\n});\n\nconst ReadFileToolUI = makeAssistantToolUI<\n {\n path?: string;\n },\n {}\n>({\n toolName: \"read_file\",\n render: ({ args }) => {\n const path = args?.path;\n\n if (!path) {\n return null;\n }\n\n return (\n \n \n
\n \n Reading File\n
\n \n {path}\n \n \n \n );\n },\n});\n" }, { "path": "apps/www/app/components/analytics/posthog-init.client.tsx", "content": "\"use client\";\n\nimport { useEffect } from \"react\";\n\nconst apiKey = process.env[\"NEXT_PUBLIC_POSTHOG_API_KEY\"];\nconst isDev = process.env.NODE_ENV === \"development\";\nlet didInit = false;\nlet initPromise: Promise | null = null;\n\nexport function PostHogInit() {\n useEffect(() => {\n if (didInit || initPromise || !apiKey) {\n return;\n }\n\n initPromise = (async () => {\n const { default: posthog } = await import(\"posthog-js\");\n if (didInit) {\n return;\n }\n\n posthog.init(apiKey, {\n api_host: \"/ph\",\n ui_host: \"https://us.posthog.com\",\n defaults: \"2025-11-30\",\n capture_exceptions: true,\n advanced_disable_flags: true, // Skip feature flags API call\n loaded: (instance) => {\n // Tag all events with environment for filtering.\n instance.register({\n environment: isDev ? \"development\" : \"production\",\n app: \"tool-ui\",\n });\n },\n });\n\n didInit = true;\n })()\n .catch((error) => {\n if (isDev) {\n console.error(\"[PostHog] failed to initialize\", error);\n }\n })\n .finally(() => {\n initPromise = null;\n });\n }, []);\n\n return null;\n}\n" }, { "path": "apps/www/app/components/assistant-ui/markdown-text.tsx", "content": "\"use client\";\n\nimport \"@assistant-ui/react-markdown/styles/dot.css\";\n\nimport {\n type CodeHeaderProps,\n MarkdownTextPrimitive,\n unstable_memoizeMarkdownComponents as memoizeMarkdownComponents,\n useIsMarkdownCodeBlock,\n} from \"@assistant-ui/react-markdown\";\nimport remarkGfm from \"remark-gfm\";\nimport { type FC, memo, useState } from \"react\";\nimport { CheckIcon, CopyIcon } from \"lucide-react\";\n\nimport { TooltipIconButton } from \"@/app/components/assistant-ui/tooltip-icon-button\";\nimport { cn } from \"@/lib/ui/cn\";\n\nconst MarkdownTextImpl = () => {\n return (\n \n );\n};\n\nexport const MarkdownText = memo(MarkdownTextImpl);\n\nconst CodeHeader: FC = ({ language, code }) => {\n const { isCopied, copyToClipboard } = useCopyToClipboard();\n const onCopy = () => {\n if (!code || isCopied) return;\n copyToClipboard(code);\n };\n\n return (\n
\n span]:text-xs\">\n {language}\n \n \n {!isCopied && }\n {isCopied && }\n \n
\n );\n};\n\nconst useCopyToClipboard = ({\n copiedDuration = 3000,\n}: {\n copiedDuration?: number;\n} = {}) => {\n const [isCopied, setIsCopied] = useState(false);\n\n const copyToClipboard = (value: string) => {\n if (!value) return;\n\n navigator.clipboard.writeText(value).then(() => {\n setIsCopied(true);\n setTimeout(() => setIsCopied(false), copiedDuration);\n });\n };\n\n return { isCopied, copyToClipboard };\n};\n\nconst defaultComponents = memoizeMarkdownComponents({\n h1: ({ className, ...props }) => (\n \n ),\n h2: ({ className, ...props }) => (\n \n ),\n h3: ({ className, ...props }) => (\n \n ),\n h4: ({ className, ...props }) => (\n \n ),\n h5: ({ className, ...props }) => (\n \n ),\n h6: ({ className, ...props }) => (\n \n ),\n p: ({ className, ...props }) => (\n \n ),\n a: ({ className, ...props }) => (\n \n ),\n blockquote: ({ className, ...props }) => (\n \n ),\n ul: ({ className, ...props }) => (\n li]:mt-2\",\n className,\n )}\n {...props}\n />\n ),\n ol: ({ className, ...props }) => (\n li]:mt-2\", className)}\n {...props}\n />\n ),\n hr: ({ className, ...props }) => (\n
\n ),\n table: ({ className, ...props }) => (\n \n ),\n th: ({ className, ...props }) => (\n \n ),\n td: ({ className, ...props }) => (\n \n ),\n tr: ({ className, ...props }) => (\n td:first-child]:rounded-bl-lg [&:last-child>td:last-child]:rounded-br-lg\",\n className,\n )}\n {...props}\n />\n ),\n sup: ({ className, ...props }) => (\n a]:text-xs [&>a]:no-underline\", className)}\n {...props}\n />\n ),\n pre: ({ className, ...props }) => (\n \n ),\n code: function Code({ className, ...props }) {\n const isCodeBlock = useIsMarkdownCodeBlock();\n return (\n \n );\n },\n CodeHeader,\n});\n" }, { "path": "apps/www/app/components/assistant-ui/thread-list.tsx", "content": "import { useCallback, type FC } from \"react\";\nimport {\n ThreadListItemPrimitive,\n ThreadListPrimitive,\n useAuiState,\n} from \"@assistant-ui/react\";\nimport { ArchiveIcon, HistoryIcon, PlusIcon } from \"lucide-react\";\n\nimport { Button } from \"@/components/ui/button\";\nimport { TooltipIconButton } from \"@/app/components/assistant-ui/tooltip-icon-button\";\nimport { Skeleton } from \"@/components/ui/skeleton\";\n\nexport type ThreadListProps = {\n allowedThreadIds?: Set;\n newLabel?: string;\n emptyState?: React.ReactNode;\n onReplay?: (threadId: string) => void;\n};\n\nexport const ThreadList: FC = ({\n allowedThreadIds,\n newLabel = \"New Tool UI\",\n emptyState,\n onReplay,\n}) => {\n return (\n \n \n \n \n );\n};\n\nconst ThreadListNew: FC<{ label: string }> = ({ label }) => {\n return (\n \n \n \n {label}\n \n \n );\n};\n\ntype ThreadListItemsProps = {\n allowedThreadIds?: Set;\n emptyState?: React.ReactNode;\n onReplay?: (threadId: string) => void;\n};\n\nconst ThreadListItems: FC = ({\n allowedThreadIds,\n emptyState,\n onReplay,\n}) => {\n const threadsState = useAuiState(useCallback((state) => state.threads, []));\n const isLoading = threadsState.isLoading;\n const threadIds = threadsState.threadIds;\n\n if (isLoading) {\n return ;\n }\n\n const indexMap = threadIds\n .map((id, index) => ({ id, index }))\n .filter(({ id }) => !allowedThreadIds || allowedThreadIds.has(id));\n\n if (indexMap.length === 0) {\n return emptyState ? <>{emptyState} : null;\n }\n\n return indexMap.map(({ id, index }) => (\n ,\n }}\n />\n ));\n};\n\nconst ThreadListSkeleton: FC = () => {\n return (\n <>\n {Array.from({ length: 5 }, (_, i) => (\n \n \n \n ))}\n \n );\n};\n\nconst ThreadListItem: FC<{ onReplay?: (threadId: string) => void }> = ({\n onReplay,\n}) => {\n return (\n \n \n \n \n \n \n );\n};\n\nconst ThreadListItemTitle: FC = () => {\n return (\n \n \n \n );\n};\n\nconst ThreadListItemActions: FC<{ onReplay?: (threadId: string) => void }> = ({\n onReplay,\n}) => {\n const threadId = useAuiState(({ threadListItem }) => threadListItem.id);\n\n return (\n
\n {onReplay && (\n {\n event.stopPropagation();\n onReplay(threadId);\n }}\n >\n \n \n )}\n \n \n \n \n \n
\n );\n};\n" }, { "path": "apps/www/app/components/assistant-ui/tool-fallback.tsx", "content": "\"use client\";\n\nimport type { ToolCallMessagePartComponent } from \"@assistant-ui/react\";\nimport { CheckIcon, ChevronDownIcon, ChevronUpIcon } from \"lucide-react\";\nimport { useState } from \"react\";\nimport { Button } from \"@/components/ui/button\";\n\nexport const ToolFallback: ToolCallMessagePartComponent = ({\n toolName,\n argsText,\n result,\n}) => {\n const [isCollapsed, setIsCollapsed] = useState(true);\n return (\n
\n
\n \n

\n Used tool: {toolName}\n

\n \n
\n {!isCollapsed && (\n
\n
\n 
\n              {argsText}\n
\n
\n {result !== undefined && (\n
\n

\n Result:\n

\n 
\n                {typeof result === \"string\"\n                  ? result\n                  : JSON.stringify(result, null, 2)}\n
\n
\n )}\n
\n )}\n
\n );\n};\n" }, { "path": "apps/www/app/components/assistant-ui/tooltip-icon-button.tsx", "content": "\"use client\";\n\nimport { ComponentPropsWithRef, forwardRef } from \"react\";\nimport { Slottable } from \"@radix-ui/react-slot\";\n\nimport {\n Tooltip,\n TooltipContent,\n TooltipTrigger,\n} from \"@/components/ui/tooltip\";\nimport { Button } from \"@/components/ui/button\";\nimport { cn } from \"@/lib/ui/cn\";\n\nexport type TooltipIconButtonProps = ComponentPropsWithRef & {\n tooltip: string;\n side?: \"top\" | \"bottom\" | \"left\" | \"right\";\n};\n\nexport const TooltipIconButton = forwardRef<\n HTMLButtonElement,\n TooltipIconButtonProps\n>(({ children, tooltip, side = \"bottom\", className, ...rest }, ref) => {\n return (\n \n \n \n {children}\n {tooltip}\n \n \n {tooltip}\n \n );\n});\n\nTooltipIconButton.displayName = \"TooltipIconButton\";\n" }, { "path": "apps/www/app/components/builder/mcp-icon.tsx", "content": "import * as React from \"react\";\n\nexport function MCPIcon({\n className,\n ...props\n}: React.SVGProps) {\n return (\n \n \n \n \n \n );\n}\n" }, { "path": "apps/www/app/components/builder/theme-toggle.tsx", "content": "\"use client\";\n\nimport * as React from \"react\";\nimport { Moon, Sun } from \"lucide-react\";\nimport { useTheme } from \"next-themes\";\nimport { Button } from \"@/components/ui/button\";\nimport { cn } from \"@/lib/ui/cn\";\n\nexport function ThemeToggle() {\n const { setTheme, resolvedTheme } = useTheme();\n const [mounted, setMounted] = React.useState(false);\n\n function changeTheme(newTheme: string) {\n if (!document.startViewTransition) {\n setTheme(newTheme);\n return;\n }\n\n document.documentElement.dataset.themeTransition = \"\";\n const transition = document.startViewTransition(() => {\n setTheme(newTheme);\n });\n transition.finished.then(() => {\n delete document.documentElement.dataset.themeTransition;\n });\n }\n\n React.useEffect(() => {\n setMounted(true);\n }, []);\n\n const isDark = mounted && resolvedTheme === \"dark\";\n\n const toggleTheme = () => {\n changeTheme(isDark ? \"light\" : \"dark\");\n };\n\n return (\n \n \n \n Toggle theme\n \n );\n}\n" }, { "path": "apps/www/app/components/builder/webview-actions.ts", "content": "\"use server\";\n\nimport { requestDevServer as requestDevServerInner } from \"@/lib/integrations/freestyle/create-chat\";\n\nexport async function requestDevServer({ repoId }: { repoId: string }) {\n return await requestDevServerInner({ repoId });\n}\n" }, { "path": "apps/www/app/components/builder/webview.tsx", "content": "\"use client\";\n\nimport { requestDevServer as requestDevServerInner } from \"./webview-actions\";\nimport \"@/app/styles/builder-loader.css\";\nimport {\n forwardRef,\n useCallback,\n useEffect,\n useImperativeHandle,\n useMemo,\n useState,\n} from \"react\";\n\nexport interface WebViewHandle {\n refresh: () => void;\n}\n\ntype DevServerResponse = Awaited>;\n\nexport default forwardRef<\n WebViewHandle,\n {\n repo: string;\n }\n>(function WebView(props, ref) {\n const [devServer, setDevServer] = useState(null);\n const [requesting, setRequesting] = useState(false);\n const [iframeLoading, setIframeLoading] = useState(true);\n const [error, setError] = useState(null);\n\n const devServerUrl = useMemo(\n () => devServer?.ephemeralUrl ?? null,\n [devServer],\n );\n\n const requestDevServer = useCallback(async () => {\n setRequesting(true);\n setIframeLoading(true);\n setError(null);\n try {\n const response = await requestDevServerInner({ repoId: props.repo });\n setDevServer(response);\n } catch (err) {\n const message = err instanceof Error ? err.message : String(err);\n setError(message);\n setDevServer(null);\n setIframeLoading(false);\n } finally {\n setRequesting(false);\n }\n }, [props.repo]);\n\n useImperativeHandle(ref, () => ({\n refresh: () => {\n void requestDevServer();\n },\n }));\n\n useEffect(() => {\n if (!props.repo) {\n setDevServer(null);\n setError(\"Repo ID is missing.\");\n return;\n }\n void requestDevServer();\n }, [props.repo, requestDevServer]);\n\n return (\n
\n {(requesting || iframeLoading) && !devServer?.devCommandRunning && (\n
\n
\n
\n {iframeLoading ? \"JavaScript Loading\" : \"Starting VM\"}\n
\n
\n
\n
\n
\n
\n )}\n {error ? (\n
\n {error}\n
\n ) : devServerUrl ? (\n setIframeLoading(false)}\n />\n ) : null}\n
\n );\n});\n" }, { "path": "apps/www/app/components/home/chat-showcase.tsx", "content": "\"use client\";\n\nimport { useCallback, useEffect, useMemo, useRef, useState } from \"react\";\nimport { AnimatePresence, motion, type Transition } from \"motion/react\";\nimport { cn } from \"@/lib/ui/cn\";\nimport { CitationList } from \"@/components/tool-ui/citation\";\nimport { DataTable } from \"@/components/tool-ui/data-table\";\nimport { LinkPreview } from \"@/components/tool-ui/link-preview\";\nimport { Plan } from \"@/components/tool-ui/plan\";\nimport { Terminal } from \"@/components/tool-ui/terminal\";\nimport { CodeBlock } from \"@/components/tool-ui/code-block\";\nimport { ItemCarousel } from \"@/components/tool-ui/item-carousel\";\nimport { ParameterSlider } from \"@/components/tool-ui/parameter-slider\";\nimport { StatsDisplay } from \"@/components/tool-ui/stats-display\";\nimport { ProgressTracker } from \"@/components/tool-ui/progress-tracker\";\nimport { MessageDraft } from \"@/components/tool-ui/message-draft\";\nimport { WeatherWidget } from \"@/components/tool-ui/weather-widget/runtime\";\nimport {\n type Flight,\n TABLE_COLUMNS,\n TABLE_DATA,\n LINK_PREVIEW,\n PLAN_TODO_LABELS,\n ITEM_CAROUSEL_DATA,\n LLM_CITATIONS,\n PARAMETER_SLIDER_DATA,\n STATS_DISPLAY_DATA,\n PROGRESS_TRACKER_DATA,\n} from \"@/lib/mocks/chat-showcase-data\";\n\nconst TIMING = {\n durations: {\n userIn: 500,\n preambleIn: 280,\n toolIn: 600,\n },\n beats: {\n afterUser: 700,\n beforeContent: 500,\n afterPreamble: 200,\n },\n sceneHold: 4500,\n exitStagger: {\n user: 0,\n preamble: 80,\n tool: 160,\n },\n reducedMotion: {\n duration: 250,\n sceneHold: 1500,\n },\n} as const;\n\nconst SPRINGS = {\n gentle: {\n type: \"spring\",\n damping: 28,\n stiffness: 180,\n mass: 0.8,\n },\n smooth: {\n type: \"spring\",\n damping: 24,\n stiffness: 260,\n mass: 0.8,\n },\n standard: {\n type: \"spring\",\n damping: 26,\n stiffness: 220,\n mass: 0.7,\n },\n} as const satisfies Record;\n\ntype SceneConfig = {\n userMessage?: string;\n preamble?: string;\n toolUI: React.ReactNode;\n toolFallbackHeight?: number;\n holdDuration?: number;\n};\n\ntype SceneTimelineState = {\n preambleReady: boolean;\n showTool: boolean;\n setShowTool: (value: boolean) => void;\n};\n\nfunction useReducedMotion(): boolean {\n const [reducedMotion, setReducedMotion] = useState(false);\n\n useEffect(() => {\n if (typeof window === \"undefined\") return;\n\n const mediaQuery = window.matchMedia(\"(prefers-reduced-motion: reduce)\");\n setReducedMotion(mediaQuery.matches);\n\n const handleChange = () => setReducedMotion(mediaQuery.matches);\n mediaQuery.addEventListener?.(\"change\", handleChange);\n return () => mediaQuery.removeEventListener?.(\"change\", handleChange);\n }, []);\n\n return reducedMotion;\n}\n\nfunction useSceneTimeline({\n reducedMotion,\n onComplete,\n hasUserMessage = true,\n initialDelay = 0,\n holdDuration,\n}: {\n reducedMotion: boolean;\n onComplete: () => void;\n hasUserMessage?: boolean;\n initialDelay?: number;\n holdDuration?: number;\n}): SceneTimelineState {\n const [preambleReady, setPreambleReady] = useState(reducedMotion);\n const [showTool, setShowTool] = useState(reducedMotion);\n const hasScheduledCompletion = useRef(false);\n\n useEffect(() => {\n if (!reducedMotion) return;\n\n const timeoutId = window.setTimeout(\n onComplete,\n TIMING.reducedMotion.sceneHold,\n );\n return () => window.clearTimeout(timeoutId);\n }, [reducedMotion, onComplete]);\n\n useEffect(() => {\n if (reducedMotion || preambleReady) return;\n\n const delay =\n initialDelay +\n (hasUserMessage ? TIMING.durations.userIn + TIMING.beats.afterUser : 0);\n\n const timeoutId = window.setTimeout(() => setPreambleReady(true), delay);\n return () => window.clearTimeout(timeoutId);\n }, [preambleReady, reducedMotion, hasUserMessage, initialDelay]);\n\n useEffect(() => {\n const shouldScheduleCompletion =\n !hasScheduledCompletion.current &&\n preambleReady &&\n showTool &&\n !reducedMotion;\n\n if (!shouldScheduleCompletion) return;\n\n hasScheduledCompletion.current = true;\n const timeoutId = window.setTimeout(\n onComplete,\n holdDuration ?? TIMING.sceneHold,\n );\n return () => window.clearTimeout(timeoutId);\n }, [preambleReady, showTool, onComplete, reducedMotion, holdDuration]);\n\n return useMemo(\n () => ({ preambleReady, showTool, setShowTool }),\n [preambleReady, showTool],\n );\n}\n\nfunction ToolReveal({ children }: { children: React.ReactNode }) {\n return (\n \n {children}\n \n );\n}\n\nfunction TypingIndicator() {\n return (\n \n );\n}\n\nconst TEST_LINES = [\n \"\\x1b[32m✓\\x1b[0m login flow handles invalid credentials \\x1b[90m(3 tests)\\x1b[0m \\x1b[33m42ms\\x1b[0m\",\n \"\\x1b[32m✓\\x1b[0m session tokens refresh correctly \\x1b[90m(5 tests)\\x1b[0m \\x1b[33m128ms\\x1b[0m\",\n \"\\x1b[32m✓\\x1b[0m logout clears all cookies \\x1b[90m(2 tests)\\x1b[0m \\x1b[33m18ms\\x1b[0m\",\n \"\",\n \"\\x1b[32mTests:\\x1b[0m 10 passed, 10 total\",\n];\n\nfunction AnimatedTerminal({ className }: { className?: string }) {\n const [lineCount, setLineCount] = useState(0);\n\n useEffect(() => {\n if (lineCount >= TEST_LINES.length) return;\n\n const delay = lineCount === 0 ? 300 : 700;\n const timeoutId = window.setTimeout(() => {\n setLineCount((c) => c + 1);\n }, delay);\n\n return () => window.clearTimeout(timeoutId);\n }, [lineCount]);\n\n const visibleOutput = TEST_LINES.slice(0, lineCount).join(\"\\n\") || \" \";\n const isComplete = lineCount >= TEST_LINES.length;\n\n return (\n \n );\n}\n\nfunction AnimatedPlan({ className }: { className?: string }) {\n const [completedCount, setCompletedCount] = useState(0);\n\n useEffect(() => {\n if (completedCount >= PLAN_TODO_LABELS.length) return;\n\n const delay = completedCount === 0 ? 400 : 1100;\n const timeoutId = window.setTimeout(() => {\n setCompletedCount((c) => c + 1);\n }, delay);\n\n return () => window.clearTimeout(timeoutId);\n }, [completedCount]);\n\n const todoDescriptions = [\n \"Analyzing social media activity and recent conversations\",\n \"Browsing gift guides and personalized recommendations\",\n \"Evaluating quality, reviews, and price ranges\",\n \"Selecting the top 3 options with purchase links\",\n ];\n\n const todos = PLAN_TODO_LABELS.map((label: string, index: number) => ({\n id: String(index + 1),\n label,\n description: todoDescriptions[index],\n status:\n index < completedCount\n ? (\"completed\" as const)\n : index === completedCount\n ? (\"in_progress\" as const)\n : (\"pending\" as const),\n }));\n\n return (\n \n );\n}\n\nfunction AnimatedProgressTracker({ className }: { className?: string }) {\n const [currentStep, setCurrentStep] = useState(1);\n\n useEffect(() => {\n if (currentStep >= 3) return;\n\n const delay = currentStep === 1 ? 1300 : 1500;\n const timeoutId = window.setTimeout(() => {\n setCurrentStep((s) => s + 1);\n }, delay);\n\n return () => window.clearTimeout(timeoutId);\n }, [currentStep]);\n\n const steps = PROGRESS_TRACKER_DATA.steps.map((step, index) => ({\n ...step,\n status:\n index < currentStep\n ? (\"completed\" as const)\n : index === currentStep\n ? (\"in-progress\" as const)\n : (\"pending\" as const),\n }));\n\n const elapsedTime = PROGRESS_TRACKER_DATA.elapsedTime! + currentStep * 12000;\n\n return (\n \n );\n}\n\ntype ChatBubbleProps = {\n role: \"user\" | \"assistant\";\n children: React.ReactNode;\n className?: string;\n};\n\nfunction ChatBubble({ role, children, className }: ChatBubbleProps) {\n const isUser = role === \"user\";\n\n return (\n \n \n {children}\n \n \n );\n}\n\ntype PreambleBubbleProps = {\n text: string;\n msPerChar?: number;\n reducedMotion?: boolean;\n onComplete?: () => void;\n};\n\nfunction StreamingChar({ char, delay }: { char: string; delay: number }) {\n return (\n \n {char}\n \n );\n}\n\nfunction PreambleBubble({\n text,\n msPerChar = 18,\n reducedMotion,\n onComplete,\n}: PreambleBubbleProps) {\n const [isVisible, setIsVisible] = useState(reducedMotion);\n const hasCalledComplete = useRef(false);\n\n useEffect(() => {\n if (reducedMotion) return;\n\n const timeoutId = window.setTimeout(() => setIsVisible(true), 100);\n return () => window.clearTimeout(timeoutId);\n }, [reducedMotion]);\n\n useEffect(() => {\n if (hasCalledComplete.current) return;\n\n if (reducedMotion) {\n hasCalledComplete.current = true;\n onComplete?.();\n return;\n }\n\n if (!isVisible) return;\n\n const totalDuration = text.length * msPerChar + 400;\n const timeoutId = window.setTimeout(() => {\n if (!hasCalledComplete.current) {\n hasCalledComplete.current = true;\n onComplete?.();\n }\n }, totalDuration);\n\n return () => window.clearTimeout(timeoutId);\n }, [reducedMotion, msPerChar, text.length, onComplete, isVisible]);\n\n const characters = useMemo(() => {\n return text.split(\"\").map((char, index) => ({\n char,\n delay: index * (msPerChar / 1000),\n }));\n }, [text, msPerChar]);\n\n if (reducedMotion) {\n return (\n \n {text}\n \n );\n }\n\n return (\n \n \n \n {isVisible &&\n characters.map(({ char, delay }, index) => (\n \n ))}\n \n \n \n );\n}\n\nfunction createSceneConfigs(reducedMotion: boolean): SceneConfig[] {\n const { title: _title, ...statsDataWithoutTitle } = STATS_DISPLAY_DATA;\n\n return [\n {\n userMessage: \"How's the business doing this quarter?\",\n preamble: \"Q4 numbers are in. Looking solid.\",\n toolUI: (\n \n ),\n toolFallbackHeight: 280,\n },\n {\n userMessage: \"What's the weather like this week?\",\n preamble: \"Stormy night ahead. Clears up by Thursday.\",\n toolUI: (\n \n ),\n toolFallbackHeight: 280,\n holdDuration: 6000,\n },\n {\n userMessage: \"Boost the bass a bit on this track\",\n preamble: \"Bass is up. Here's the full EQ.\",\n toolUI: (\n \n ),\n toolFallbackHeight: 240,\n },\n {\n userMessage: \"Find me a birthday gift for Sarah\",\n preamble: \"On it. Checking her interests now.\",\n toolUI: ,\n toolFallbackHeight: 280,\n },\n {\n userMessage: \"What should I listen to right now?\",\n preamble: \"Found a few albums for you.\",\n toolUI: (\n \n ),\n toolFallbackHeight: 320,\n },\n {\n userMessage: \"Run the tests for the auth module\",\n preamble: \"Running auth tests now.\",\n toolUI: ,\n toolFallbackHeight: 200,\n },\n {\n userMessage: \"Deploy the updates to production\",\n preamble: \"Deployment started. Tracking progress.\",\n toolUI: ,\n toolFallbackHeight: 260,\n },\n {\n userMessage: \"Find me flights to Tokyo in March\",\n preamble: \"Found 4 nonstop flights. Sorted by price.\",\n toolUI: (\n \n id=\"chat-showcase-data-table\"\n rowIdKey=\"id\"\n columns={TABLE_COLUMNS}\n data={TABLE_DATA}\n defaultSort={{ by: \"price\", direction: \"asc\" }}\n />\n ),\n toolFallbackHeight: 320,\n },\n {\n userMessage: \"Create a skill that learns from mistakes\",\n preamble: \"Here's a self-improving metaskill.\",\n toolUI: (\n \n ),\n toolFallbackHeight: 260,\n },\n {\n userMessage: \"Find that physics article from Quanta\",\n preamble: \"Was it this one?\",\n toolUI: ,\n toolFallbackHeight: 260,\n },\n {\n userMessage: \"Send Marcus the updated proposal\",\n preamble: \"Drafted this for you. Review before sending.\",\n toolUI: (\n \n ),\n toolFallbackHeight: 340,\n },\n {\n userMessage: \"What was the first LLM?\",\n preamble: \"GPT-1 from OpenAI in 2018. Here are the key sources.\",\n toolUI: (\n \n ),\n toolFallbackHeight: 56,\n },\n ];\n}\n\nconst SCENE_COUNT = 11;\n\ntype AnimatedSceneProps = {\n config: SceneConfig;\n reducedMotion: boolean;\n onComplete: () => void;\n sceneId: string;\n isExiting?: boolean;\n composerPadding?: boolean;\n initialDelay?: number;\n};\n\nfunction AnimatedScene({\n config,\n reducedMotion,\n onComplete,\n sceneId,\n isExiting = false,\n initialDelay = 0,\n}: AnimatedSceneProps) {\n const timeline = useSceneTimeline({\n reducedMotion,\n onComplete,\n hasUserMessage: !!config.userMessage,\n initialDelay,\n holdDuration: config.holdDuration,\n });\n\n const handlePreambleComplete = useCallback(() => {\n timeline.setShowTool(true);\n }, [timeline]);\n\n useEffect(() => {\n const shouldShowTool = timeline.preambleReady && !timeline.showTool;\n\n if (shouldShowTool) {\n timeline.setShowTool(true);\n }\n }, [timeline]);\n\n const shouldRenderItems = !isExiting;\n const shouldShowToolContent = config.preamble ? timeline.showTool : true;\n\n const createEntryTransition = (delayMs: number) => ({\n ...SPRINGS.standard,\n delay: delayMs / 1000,\n });\n\n const createExitTransition = (delayMs: number) => ({\n ...SPRINGS.standard,\n delay: delayMs / 1000,\n });\n\n return (\n
\n \n {shouldRenderItems && config.userMessage && (\n \n \n {config.userMessage}\n \n \n )}\n\n {shouldRenderItems && config.preamble && (\n \n \n {config.userMessage &&\n !timeline.preambleReady &&\n !reducedMotion && (\n \n \n \n )}\n \n\n {timeline.preambleReady && (\n \n \n \n )}\n \n )}\n\n {shouldRenderItems &&\n timeline.preambleReady &&\n shouldShowToolContent && (\n \n
\n
\n {config.toolUI}\n
\n
\n \n )}\n \n
\n );\n}\n\nexport function ChatShowcase() {\n const reducedMotion = useReducedMotion();\n const sceneConfigs = useMemo(\n () => createSceneConfigs(reducedMotion),\n [reducedMotion],\n );\n\n const [sceneIndex, setSceneIndex] = useState(0);\n const [sceneRunId, setSceneRunId] = useState(0);\n const [isExiting, setIsExiting] = useState(false);\n\n const exitDuration = reducedMotion\n ? TIMING.reducedMotion.duration\n : TIMING.exitStagger.tool + 500;\n\n const transitionToScene = useCallback(\n (getNextIndex: (current: number) => number) => {\n setIsExiting(true);\n setTimeout(() => {\n setIsExiting(false);\n setSceneIndex(getNextIndex);\n setSceneRunId((id) => id + 1);\n }, exitDuration);\n },\n [exitDuration],\n );\n\n const advanceToNextScene = useCallback(() => {\n transitionToScene((current) => (current + 1) % SCENE_COUNT);\n }, [transitionToScene]);\n\n const goToPreviousScene = useCallback(() => {\n transitionToScene((current) => (current - 1 + SCENE_COUNT) % SCENE_COUNT);\n }, [transitionToScene]);\n\n useEffect(() => {\n const handleKeyDown = (e: KeyboardEvent) => {\n if (e.key === \"ArrowRight\") {\n advanceToNextScene();\n } else if (e.key === \"ArrowLeft\") {\n goToPreviousScene();\n }\n };\n\n window.addEventListener(\"keydown\", handleKeyDown);\n return () => window.removeEventListener(\"keydown\", handleKeyDown);\n }, [advanceToNextScene, goToPreviousScene]);\n\n return (\n
\n \n
\n \n \n \n
\n
\n );\n}\n" }, { "path": "apps/www/app/components/home/demo-chat.tsx", "content": "\"use client\";\n\nimport { useMemo } from \"react\";\nimport {\n AssistantRuntimeProvider,\n ThreadPrimitive,\n Tools,\n useAui,\n} from \"@assistant-ui/react\";\nimport {\n AssistantChatTransport,\n useChatRuntime,\n} from \"@assistant-ui/react-ai-sdk\";\nimport { lastAssistantMessageIsCompleteWithToolCalls } from \"ai\";\nimport { DEMO_CHAT_TOOLKIT } from \"@/lib/demo-chat/toolkit\";\nimport {\n AssistantMessage,\n Composer,\n UserMessage,\n} from \"@/app/playground/chat-ui\";\n\n// Prompts designed to trigger specific tools: get_tasks, show_plan, show_stats, show_terminal\nconst SUGGESTIONS = [\n { text: \"Show me the support tickets\", tool: \"get_tasks\" },\n { text: \"Create a deployment plan\", tool: \"show_plan\" },\n { text: \"How's Q4 looking?\", tool: \"show_stats\" },\n { text: \"Run the auth tests\", tool: \"show_terminal\" },\n] as const;\n\nconst PASTEL_COLORS = [\n \"bg-pink-100 text-pink-800 border-pink-200 hover:bg-pink-200/80 dark:bg-pink-950/40 dark:text-pink-200 dark:border-pink-800/50 dark:hover:bg-pink-900/30\",\n \"bg-violet-100 text-violet-800 border-violet-200 hover:bg-violet-200/80 dark:bg-violet-950/40 dark:text-violet-200 dark:border-violet-800/50 dark:hover:bg-violet-900/30\",\n \"bg-sky-100 text-sky-800 border-sky-200 hover:bg-sky-200/80 dark:bg-sky-950/40 dark:text-sky-200 dark:border-sky-800/50 dark:hover:bg-sky-900/30\",\n \"bg-emerald-100 text-emerald-800 border-emerald-200 hover:bg-emerald-200/80 dark:bg-emerald-950/40 dark:text-emerald-200 dark:border-emerald-800/50 dark:hover:bg-emerald-900/30\",\n] as const;\n\nfunction SuggestionChip({\n children,\n onClick,\n colorClass,\n}: {\n children: string;\n onClick: () => void;\n colorClass: string;\n}) {\n return (\n \n {children}\n \n );\n}\n\nfunction SuggestionChips() {\n const aui = useAui();\n return (\n
\n {SUGGESTIONS.map(({ text, tool }, i) => (\n {\n const composer = aui.composer();\n composer.setText(text);\n composer.send();\n }}\n >\n {text}\n \n ))}\n
\n );\n}\n\nexport function DemoChat() {\n const transport = useMemo(\n () =>\n new AssistantChatTransport({\n api: \"/api/chat\",\n }),\n [],\n );\n\n const runtime = useChatRuntime({\n transport,\n sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,\n });\n\n const aui = useAui({\n tools: Tools({ toolkit: DEMO_CHAT_TOOLKIT }),\n });\n\n return (\n \n \n \n \n
\n

Try Tool UI

\n

\n Ask to see a plan, support tickets, metrics, or run a command.\n Each response uses a different Tool UI component.\n

\n \n
\n \n \n \n
\n \n
\n \n \n );\n}\n" }, { "path": "apps/www/app/components/home/faux-chat-shell-animated.tsx", "content": "\"use client\";\n\nimport { motion } from \"motion/react\";\nimport { FauxChatShellNoLightOverlay } from \"./faux-chat-shell\";\nimport { generateNoiseDataUri } from \"./noise-texture\";\n\nfunction generateSineEasedGradient(\n angle: number,\n centerPosition: number,\n peakOpacity: number,\n spreadWidth: number,\n steps: number = 128,\n): string {\n const stops: string[] = [];\n\n for (let i = 0; i <= steps; i++) {\n const t = i / steps;\n const position = centerPosition - spreadWidth / 2 + spreadWidth * t;\n\n const sineValue = Math.sin(t * Math.PI);\n const eased = sineValue * sineValue;\n const opacity = peakOpacity * eased;\n\n stops.push(\n `rgba(255, 255, 255, ${opacity.toFixed(4)}) ${position.toFixed(1)}%`,\n );\n }\n\n return `linear-gradient(${angle}deg, ${stops.join(\", \")})`;\n}\n\nexport function FauxChatShellAnimated() {\n // Hardcoded animation values\n const initial = {\n opacity: 0,\n rotateX: 20,\n rotateY: 37,\n rotateZ: -13,\n x: 429,\n y: -298,\n scale: 2,\n };\n\n const resting = {\n opacity: 1,\n rotateX: 37,\n rotateY: 26,\n rotateZ: -18,\n x: -35,\n y: -60,\n scale: 1.05,\n };\n\n // Perspective and transform origin\n const perspective = 3700;\n const perspectiveOriginX = 100;\n const perspectiveOriginY = 29;\n const originX = 70;\n const originY = 64;\n const translateZInitial = 96;\n const translateZResting = 96;\n\n // Lighting parameters\n const lightAngle = 140;\n const lightPosition = 82;\n const lightSpread = 29;\n const lightOpacity = 0.07;\n\n // Calculate light position based on surface normal (simulates static directional light)\n function calculateLightPosition(rotateX: number, rotateY: number) {\n const baseY = lightPosition;\n const highlightY = baseY - rotateX * 0.8 - rotateY * 0.3;\n return highlightY;\n }\n\n // Calculate highlight position for resting state\n const restingLightPos = calculateLightPosition(\n resting.rotateX,\n resting.rotateY,\n );\n\n // Generate gradient centered at calculated position\n const restingLightGradient = generateSineEasedGradient(\n lightAngle,\n restingLightPos,\n lightOpacity,\n lightSpread,\n 32,\n );\n\n // Animation config\n const transition = {\n type: \"spring\" as const,\n duration: 5,\n bounce: 0.2,\n };\n\n return (\n \n \n \n\n {/* Lighting overlay - fades in from 0 to full opacity */}\n \n \n \n );\n}\n" }, { "path": "apps/www/app/components/home/faux-chat-shell-mobile-animated.tsx", "content": "\"use client\";\n\nimport { motion } from \"motion/react\";\nimport { FauxChatShellMobile } from \"./faux-chat-shell-mobile\";\nimport { generateNoiseDataUri } from \"./noise-texture\";\n\nfunction generateSineEasedGradient(\n angle: number,\n centerPosition: number,\n peakOpacity: number,\n spreadWidth: number,\n steps: number = 128,\n): string {\n const stops: string[] = [];\n\n for (let i = 0; i <= steps; i++) {\n const t = i / steps;\n const position = centerPosition - spreadWidth / 2 + spreadWidth * t;\n\n const sineValue = Math.sin(t * Math.PI);\n const eased = sineValue * sineValue;\n const opacity = peakOpacity * eased;\n\n stops.push(\n `rgba(255, 255, 255, ${opacity.toFixed(4)}) ${position.toFixed(1)}%`,\n );\n }\n\n return `linear-gradient(${angle}deg, ${stops.join(\", \")})`;\n}\n\nexport function FauxChatShellMobileAnimated() {\n // Hardcoded animation values - adjusted for portrait phone\n const initial = {\n opacity: 0,\n rotateX: 20,\n rotateY: 37,\n rotateZ: -13,\n x: 429,\n y: -298,\n scale: 2,\n };\n\n const resting = {\n opacity: 1,\n rotateX: 37,\n rotateY: 26,\n rotateZ: -18,\n x: -35,\n y: -60,\n scale: 1.05,\n };\n\n // Perspective and transform origin\n const perspective = 3700;\n const perspectiveOriginX = 100;\n const perspectiveOriginY = 29;\n const originX = 70;\n const originY = 64;\n const translateZInitial = 96;\n const translateZResting = 96;\n\n // Lighting parameters\n const lightAngle = 140;\n const lightPosition = 82;\n const lightSpread = 29;\n const lightOpacity = 0.07;\n\n // Calculate light position based on surface normal (simulates static directional light)\n function calculateLightPosition(rotateX: number, rotateY: number) {\n const baseY = lightPosition;\n const highlightY = baseY - rotateX * 0.8 - rotateY * 0.3;\n return highlightY;\n }\n\n // Calculate highlight position for resting state\n const restingLightPos = calculateLightPosition(\n resting.rotateX,\n resting.rotateY,\n );\n\n // Generate gradient centered at calculated position\n const restingLightGradient = generateSineEasedGradient(\n lightAngle,\n restingLightPos,\n lightOpacity,\n lightSpread,\n 32,\n );\n\n // Animation config\n const transition = {\n type: \"spring\" as const,\n duration: 5,\n bounce: 0.2,\n };\n\n return (\n \n \n \n\n {/* Lighting overlay - fades in from 0 to full opacity */}\n \n \n \n );\n}\n" }, { "path": "apps/www/app/components/home/faux-chat-shell-mobile.tsx", "content": "\"use client\";\n\nimport { useEffect, useState } from \"react\";\nimport { cn } from \"@/lib/ui/cn\";\nimport { ChatShowcase } from \"./chat-showcase\";\n\ntype FauxChatShellMobileProps = {\n className?: string;\n};\n\nfunction DynamicIsland() {\n return (\n \n
\n
\n );\n}\n\nfunction StatusBar() {\n const [time, setTime] = useState(\"\");\n\n useEffect(() => {\n const updateTime = () => {\n const now = new Date();\n let hours = now.getHours();\n const minutes = now.getMinutes().toString().padStart(2, \"0\");\n hours = hours % 12 || 12;\n setTime(`${hours}:${minutes}`);\n };\n\n updateTime();\n\n const scheduleNextUpdate = () => {\n const now = new Date();\n const msUntilNextMinute =\n (60 - now.getSeconds()) * 1000 - now.getMilliseconds();\n return setTimeout(() => {\n updateTime();\n intervalRef = setInterval(updateTime, 60000);\n }, msUntilNextMinute);\n };\n\n let intervalRef: ReturnType | null = null;\n const timeoutRef = scheduleNextUpdate();\n\n return () => {\n clearTimeout(timeoutRef);\n if (intervalRef) clearInterval(intervalRef);\n };\n }, []);\n\n return (\n
\n
{time}
\n
\n {/* Signal/WiFi/Battery icons would go here - keeping minimal */}\n
\n
\n );\n}\n\nexport function FauxChatShellMobile({ className }: FauxChatShellMobileProps) {\n return (\n \n \n \n\n
\n \n
\n\n \n \n );\n}\n" }, { "path": "apps/www/app/components/home/faux-chat-shell.tsx", "content": "\"use client\";\n\nimport { useEffect, useRef, useState } from \"react\";\nimport { cn } from \"@/lib/ui/cn\";\nimport { ChatShowcase } from \"./chat-showcase\";\nimport { DemoChat } from \"./demo-chat\";\n\ntype FauxChatShellProps = {\n className?: string;\n /** When true, renders live DemoChat instead of static ChatShowcase */\n live?: boolean;\n};\n\nexport function generateSineEasedGradient(\n angle: number,\n centerPosition: number,\n peakOpacity: number,\n spreadWidth: number,\n steps: number = 128,\n): string {\n const stops: string[] = [];\n\n for (let i = 0; i <= steps; i++) {\n const t = i / steps;\n const position = centerPosition - spreadWidth / 2 + spreadWidth * t;\n\n // Sine curve: peaks at center (t=0.5), zero at edges (t=0, t=1)\n // Square the sine for even smoother falloff at edges\n const sineValue = Math.sin(t * Math.PI);\n const eased = sineValue * sineValue;\n const opacity = peakOpacity * eased;\n\n stops.push(\n `rgba(255, 255, 255, ${opacity.toFixed(4)}) ${position.toFixed(1)}%`,\n );\n }\n\n // No hard transparent stops — sine² already smoothly reaches zero at edges\n return `linear-gradient(${angle}deg, ${stops.join(\", \")})`;\n}\n\nfunction useDirectionalLight(\n containerRef: React.RefObject,\n) {\n const [gradientStyle, setGradientStyle] = useState({});\n\n useEffect(() => {\n const container = containerRef.current;\n if (!container) return;\n\n const updateGradient = () => {\n const parent = container.parentElement;\n if (!parent) return;\n\n const style = getComputedStyle(parent);\n const rotateX =\n parseFloat(style.getPropertyValue(\"--shell-rotate-x\")) || 0;\n const rotateY =\n parseFloat(style.getPropertyValue(\"--shell-rotate-y\")) || 0;\n\n // Light params from CSS custom properties (with defaults)\n const baseAngle =\n parseFloat(style.getPropertyValue(\"--light-angle\")) || 135;\n const basePosition =\n parseFloat(style.getPropertyValue(\"--light-position\")) || 35;\n const spread = parseFloat(style.getPropertyValue(\"--light-spread\")) || 40;\n const opacity =\n parseFloat(style.getPropertyValue(\"--light-opacity\")) || 0.12;\n const rotateXFactor =\n parseFloat(style.getPropertyValue(\"--light-rotate-x-factor\")) || 1.2;\n const rotateYFactor =\n parseFloat(style.getPropertyValue(\"--light-rotate-y-factor\")) || 0.8;\n\n // Highlight position shifts based on rotation (light \"slides\" across surface)\n const centerPosition =\n basePosition - rotateX * rotateXFactor - rotateY * rotateYFactor;\n\n const gradient = generateSineEasedGradient(\n baseAngle,\n centerPosition,\n opacity,\n spread,\n 32,\n );\n\n setGradientStyle({ background: gradient });\n };\n\n updateGradient();\n\n // Watch for changes via MutationObserver on parent's style attribute\n const parent = container.parentElement;\n if (!parent) return;\n\n const observer = new MutationObserver(updateGradient);\n observer.observe(parent, { attributes: true, attributeFilter: [\"style\"] });\n\n return () => observer.disconnect();\n }, [containerRef]);\n\n return gradientStyle;\n}\n\nfunction WindowDots() {\n return (\n
\n \n \n \n
\n );\n}\n\nfunction ComposerBar() {\n return (\n
\n
\n
\n );\n}\n\nfunction FauxChatShellBase({\n className,\n showLightOverlay,\n live = false,\n}: FauxChatShellProps & { showLightOverlay: boolean }) {\n const containerRef = useRef(null);\n const gradientStyle = useDirectionalLight(containerRef);\n\n return (\n \n {/* Directional light reflection overlay */}\n {showLightOverlay && (\n \n )}\n\n
\n
\n \n
\n
\n
\n \n {live ? : }\n
\n {!live && (\n <>\n \n \n \n )}\n
\n );\n}\n\nexport function FauxChatShell(props: FauxChatShellProps) {\n return ;\n}\n\nexport function FauxChatShellNoLightOverlay(props: FauxChatShellProps) {\n return ;\n}\n" }, { "path": "apps/www/app/components/home/home-background.tsx", "content": "\"use client\";\n\nexport function HomeBackground() {\n return (\n <>\n \n \n \n );\n}\n" }, { "path": "apps/www/app/components/home/home-hero.tsx", "content": "\"use client\";\n\nimport Link from \"next/link\";\nimport { useRouter } from \"next/navigation\";\nimport { ArrowRight } from \"lucide-react\";\nimport { motion } from \"motion/react\";\nimport { HomeHexnutScene } from \"./home-hexnut-scene\";\nimport { Button } from \"@/components/ui/button\";\nimport { analytics } from \"@/lib/analytics\";\n\nconst smoothSpring = {\n type: \"spring\" as const,\n stiffness: 200,\n damping: 40,\n duration: 0.8,\n restDelta: 0.0001,\n};\n\nexport function HomeHero() {\n const router = useRouter();\n const preloadGallery = () => {\n void router.prefetch(\"/docs/gallery\");\n };\n\n return (\n
\n \n \n \n
\n
\n \n Tool UI\n \n
\n \n UI components for AI interfaces\n \n
\n \n JSON-native, typed, accessible, copy-pasteable.{\" \"}\n
\n Built on Tailwind, Radix, and shadcn/ui. Open Source.\n \n \n \n analytics.cta.clicked(\"see_components\", \"home_hero\")}\n >\n See the Components\n \n \n \n \n
\n );\n}\n" }, { "path": "apps/www/app/components/home/home-hexnut-scene.tsx", "content": "\"use client\";\n\nimport dynamic from \"next/dynamic\";\n\n// Dynamic import with SSR disabled for Three.js components\nconst HexnutSceneCanvas = dynamic(\n () =>\n import(\"@/app/components/visuals/spinning-hexnut/hexnut-scene\").then(\n (mod) => mod.HexnutScene,\n ),\n {\n ssr: false,\n loading: () =>
,\n },\n);\n\nexport function HomeHexnutScene() {\n return (\n
\n \n
\n );\n}\n" }, { "path": "apps/www/app/components/home/noise-texture.ts", "content": "/**\n * Generates a data URI for a subtle noise texture to reduce gradient banding\n * @param size - Size of the noise tile (default: 64px)\n * @param opacity - Opacity of the noise (0-1, default: 0.02)\n */\nexport function generateNoiseDataUri(\n size: number = 64,\n opacity: number = 0.02,\n): string {\n // Create a minimal noise pattern using SVG\n // This is more efficient than canvas and works in SSR\n const svg = `\n \n \n \n \n \n \n \n \n \n `.trim();\n\n // Use URL encoding consistently for both SSR and client to avoid hydration mismatch\n return `data:image/svg+xml,${encodeURIComponent(svg)}`;\n}\n\n/**\n * CSS style object for applying noise texture over gradients\n */\nexport function getNoiseOverlayStyle(opacity: number = 0.02) {\n return {\n backgroundImage: `url(\"${generateNoiseDataUri(64, opacity)}\")`,\n backgroundBlendMode: \"overlay\" as const,\n };\n}\n" }, { "path": "apps/www/app/components/layout/app-header.server.tsx", "content": "import { ReactNode } from \"react\";\nimport Link from \"next/link\";\nimport { Button } from \"@/components/ui/button\";\n\nimport { FaGithub } from \"react-icons/fa\";\nimport { FaXTwitter } from \"react-icons/fa6\";\nimport { ArrowUpRight } from \"lucide-react\";\nimport { LogoMark } from \"@/components/ui/logo\";\nimport { ActiveNavLink } from \"./header-active-link.client\";\nimport { TrackedExternalAnchor } from \"./tracked-external-anchor.client\";\n\ninterface ResponsiveHeaderProps {\n rightContent?: ReactNode;\n}\n\nexport function ResponsiveHeader({ rightContent }: ResponsiveHeaderProps) {\n const navLinks = [\n { href: \"/docs/overview\", label: \"Docs\" },\n { href: \"/docs/gallery\", label: \"Gallery\" },\n ];\n\n return (\n
\n
\n \n \n

Tool UI

\n \n
\n\n {/* Desktop Navigation */}\n
\n \n
\n {rightContent}\n
\n \n \n
\n
\n
\n\n {/* Mobile Right Content */}\n
\n {rightContent}\n
\n
\n );\n}\n" }, { "path": "apps/www/app/components/layout/app-shell-animated.client.tsx", "content": "\"use client\";\n\nimport type { ReactNode } from \"react\";\nimport { useEffect, useState } from \"react\";\nimport { ResponsiveHeader } from \"@/app/components/layout/app-header.server\";\nimport { cn } from \"@/lib/ui/cn\";\n\ntype HeaderFrameProps = {\n children: ReactNode;\n rightContent?: ReactNode;\n background?: ReactNode;\n};\n\n// Persists for the life of the client bundle so the intro animation runs once.\nlet hasPlayedIntroAnimation = false;\n\nfunction HeaderFrameBase({\n children,\n rightContent,\n background,\n shouldAnimate,\n}: HeaderFrameProps & { shouldAnimate: boolean }) {\n return (\n
\n {background ? (\n
\n {background}\n
\n ) : null}\n \n \n
\n
\n {children}\n
\n
\n );\n}\n\nexport function AnimatedHeaderFrame(props: HeaderFrameProps) {\n const [shouldAnimate] = useState(() => !hasPlayedIntroAnimation);\n\n useEffect(() => {\n if (shouldAnimate) {\n hasPlayedIntroAnimation = true;\n }\n }, [shouldAnimate]);\n\n return ;\n}\n" }, { "path": "apps/www/app/components/layout/app-shell.tsx", "content": "import type { ReactNode } from \"react\";\nimport { ResponsiveHeader } from \"@/app/components/layout/app-header.server\";\nimport { cn } from \"@/lib/ui/cn\";\n\nexport type HeaderFrameProps = {\n children: ReactNode;\n rightContent?: ReactNode;\n background?: ReactNode;\n};\n\nfunction HeaderFrameBase({\n children,\n rightContent,\n background,\n shouldAnimate,\n}: HeaderFrameProps & { shouldAnimate: boolean }) {\n return (\n
\n {background ? (\n
\n {background}\n
\n ) : null}\n \n \n
\n
\n {children}\n
\n \n );\n}\n\nexport function HeaderFrame(props: HeaderFrameProps) {\n return ;\n}\n" }, { "path": "apps/www/app/components/layout/header-active-link.client.tsx", "content": "\"use client\";\n\nimport Link from \"next/link\";\nimport { usePathname } from \"next/navigation\";\nimport { cn } from \"@/lib/ui/cn\";\n\ninterface ActiveNavLinkProps {\n href: string;\n children: React.ReactNode;\n}\n\nexport function ActiveNavLink({ href, children }: ActiveNavLinkProps) {\n const pathname = usePathname();\n const isActive = href === \"/\" ? pathname === \"/\" : pathname.startsWith(href);\n\n return (\n \n {children}\n \n );\n}\n" }, { "path": "apps/www/app/components/layout/mobile-nav-sheet-gate.client.tsx", "content": "\"use client\";\n\nimport dynamic from \"next/dynamic\";\nimport { usePathname } from \"next/navigation\";\nimport { useEffect, useState } from \"react\";\n\nconst MobileNavSheet = dynamic(\n () =>\n import(\"@/app/components/layout/mobile-nav-sheet.client\").then(\n (mod) => mod.MobileNavSheet,\n ),\n {\n ssr: false,\n },\n);\n\nconst MOBILE_QUERY = \"(max-width: 767px)\";\n\nfunction shouldRenderForPath(pathname: string) {\n return (\n pathname === \"/\" ||\n pathname.startsWith(\"/docs\") ||\n pathname.startsWith(\"/builder\")\n );\n}\n\nexport function MobileNavSheetGate() {\n const pathname = usePathname();\n const [isMobileViewport, setIsMobileViewport] = useState(false);\n\n useEffect(() => {\n const mediaQuery = window.matchMedia(MOBILE_QUERY);\n const updateViewportMatch = () => setIsMobileViewport(mediaQuery.matches);\n\n updateViewportMatch();\n mediaQuery.addEventListener(\"change\", updateViewportMatch);\n\n return () => {\n mediaQuery.removeEventListener(\"change\", updateViewportMatch);\n };\n }, []);\n\n if (!isMobileViewport || !shouldRenderForPath(pathname)) {\n return null;\n }\n\n return ;\n}\n" }, { "path": "apps/www/app/components/layout/mobile-nav-sheet.client.tsx", "content": "\"use client\";\n\nimport React from \"react\";\nimport Link from \"next/link\";\nimport { usePathname } from \"next/navigation\";\nimport { Sheet, Scroll } from \"@silk-hq/components\";\nimport { FaGithub } from \"react-icons/fa\";\nimport { FaXTwitter } from \"react-icons/fa6\";\nimport { componentsRegistry } from \"@/lib/docs/component-registry\";\nimport { BASE_DOCS_PAGES } from \"@/app/docs/_components/docs-pages\";\nimport { cn } from \"@/lib/ui/cn\";\nimport { Button } from \"@/components/ui/button\";\nimport { Separator } from \"@/components/ui/separator\";\nimport { TrackedExternalAnchor } from \"./tracked-external-anchor.client\";\n\nimport \"@/app/styles/nav-sheet.css\";\n\nexport function MobileNavSheet() {\n const pathname = usePathname();\n const [presented, setPresented] = React.useState(false);\n const [showScrollIndicator, setShowScrollIndicator] = React.useState(true);\n const [isMobileViewport, setIsMobileViewport] = React.useState(false);\n\n React.useEffect(() => {\n const mediaQuery = window.matchMedia(\"(max-width: 767px)\");\n const updateViewportMatch = () => setIsMobileViewport(mediaQuery.matches);\n\n updateViewportMatch();\n mediaQuery.addEventListener(\"change\", updateViewportMatch);\n\n return () => {\n mediaQuery.removeEventListener(\"change\", updateViewportMatch);\n };\n }, []);\n\n const isDocs = pathname.startsWith(\"/docs\") && pathname !== \"/docs/gallery\";\n const isGallery = pathname === \"/docs/gallery\";\n\n const mainNavLinks = [\n { href: \"/docs/overview\", label: \"Docs\", isActive: isDocs },\n { href: \"/docs/gallery\", label: \"Gallery\", isActive: isGallery },\n ];\n\n if (!isMobileViewport) {\n return null;\n }\n\n return (\n \n {/* Floating Action Button */}\n \n \n \n \n \n \n \n \n\n {/* Bottom Sheet Portal */}\n \n \n \n \n \n\n {/* handle */}\n
\n
\n
\n\n {/* Top Scroll Indicator Gradient */}\n
\n\n \n {\n // Hide bottom indicator when scrolled near the bottom (within 5%)\n setShowScrollIndicator(progress < 0.95);\n }}\n >\n \n \n
\n \n
\n\n {/* Docs Section */}\n
\n
\n Get Started\n
\n\n {BASE_DOCS_PAGES.map((page) => {\n const isActive = pathname === page.path;\n\n return (\n setPresented(false)}\n className={cn(\n \"text-primary rounded-lg px-4 py-3.5\",\n isActive\n ? \"bg-muted text-foreground font-medium\"\n : \"text-primary hover:bg-muted/50 hover:text-foreground\",\n )}\n >\n {page.label}\n \n );\n })}\n
\n\n {/* Components Section */}\n
\n
\n Components\n
\n\n {componentsRegistry.map((component) => {\n const isActive = pathname === component.path;\n\n return (\n setPresented(false)}\n className={cn(\n \"text-primary rounded-lg px-4 py-3.5\",\n isActive\n ? \"bg-muted text-foreground font-medium\"\n : \"text-primary hover:bg-muted/50 hover:text-foreground\",\n )}\n >\n {component.label}\n \n );\n })}\n
\n \n \n\n {/* Bottom Scroll Indicator Gradient */}\n {showScrollIndicator && (\n
\n )}\n \n\n {/* Social Links Footer */}\n
\n
\n \n \n
\n
\n \n \n \n \n );\n}\n" }, { "path": "apps/www/app/components/layout/page-shell.tsx", "content": "import type { ReactNode } from \"react\";\n\ntype ContentLayoutProps = {\n children: ReactNode;\n sidebar?: ReactNode;\n};\n\nexport default function ContentLayout({\n children,\n sidebar,\n}: ContentLayoutProps) {\n return (\n
\n {sidebar ? (\n \n ) : null}\n
{children}
\n
\n );\n}\n" }, { "path": "apps/www/app/components/layout/tracked-external-anchor.client.tsx", "content": "\"use client\";\n\nimport * as React from \"react\";\nimport { analytics } from \"@/lib/analytics\";\n\ntype ExternalDestination = \"github\" | \"npm\" | \"docs\" | \"other\";\n\ntype TrackedExternalAnchorProps = React.ComponentPropsWithoutRef<\"a\"> & {\n destination: ExternalDestination;\n};\n\nexport const TrackedExternalAnchor = React.forwardRef<\n HTMLAnchorElement,\n TrackedExternalAnchorProps\n>(function TrackedExternalAnchor(\n { destination, href, onClick, ...props },\n ref,\n) {\n const hrefValue = typeof href === \"string\" ? href : \"\";\n\n const handleClick = (event: React.MouseEvent) => {\n analytics.external.linkClicked(destination, hrefValue);\n onClick?.(event);\n };\n\n return ;\n});\n" }, { "path": "apps/www/app/components/mdx/features.tsx", "content": "import { cn } from \"@/lib/ui/cn\";\nimport type { LucideIcon } from \"lucide-react\";\nimport {\n Palette,\n Copy,\n Hash,\n Highlighter,\n FoldVertical,\n FileCode,\n FileText,\n Moon,\n BarChart3,\n LineChart,\n MousePointerClick,\n CircleCheck,\n CheckCircle2,\n ListChecks,\n Settings2,\n SquareCheck,\n Paintbrush,\n Terminal,\n Timer,\n AlertCircle,\n AlertTriangle,\n Code,\n FileOutput,\n Smartphone,\n ArrowUpDown,\n Table2,\n Accessibility,\n Link,\n Image,\n Video,\n Headphones,\n Download,\n Expand,\n PartyPopper,\n HelpCircle,\n Layers,\n Play,\n Eye,\n Maximize2,\n ListTodo,\n List,\n GalleryHorizontalEnd,\n Keyboard,\n Globe,\n ExternalLink,\n Ratio,\n Quote,\n ShieldCheck,\n Target,\n MessageSquare,\n BadgeCheck,\n Images,\n Network,\n Route,\n ScanSearch,\n Rocket,\n DollarSign,\n Package,\n Grid2x2,\n Move,\n PlusCircle,\n SlidersHorizontal,\n CloudSun,\n MapPin,\n Thermometer,\n Calendar,\n} from \"lucide-react\";\n\nconst ICON_MAP: Record = {\n Palette,\n Copy,\n Hash,\n Highlighter,\n FoldVertical,\n FileCode,\n FileText,\n Moon,\n BarChart3,\n LineChart,\n MousePointerClick,\n CircleCheck,\n CheckCircle2,\n ListChecks,\n Settings2,\n SquareCheck,\n Paintbrush,\n Terminal,\n Timer,\n AlertCircle,\n AlertTriangle,\n Code,\n FileOutput,\n Smartphone,\n ArrowUpDown,\n Table2,\n Accessibility,\n Link,\n Image,\n Video,\n Headphones,\n Download,\n Expand,\n PartyPopper,\n HelpCircle,\n Layers,\n Play,\n Eye,\n Maximize2,\n ListTodo,\n List,\n GalleryHorizontalEnd,\n Keyboard,\n Globe,\n ExternalLink,\n AspectRatio: Ratio,\n Quote,\n ShieldCheck,\n Target,\n MessageSquare,\n BadgeCheck,\n Images,\n Network,\n Route,\n ScanSearch,\n Rocket,\n DollarSign,\n Package,\n Grid2x2,\n Move,\n PlusCircle,\n SlidersHorizontal,\n CloudSun,\n MapPin,\n Thermometer,\n Calendar,\n};\n\ninterface FeatureGridProps {\n children: React.ReactNode;\n className?: string;\n}\n\nexport function FeatureGrid({ children, className }: FeatureGridProps) {\n return (\n \n {children}\n
\n );\n}\n\ninterface FeatureProps {\n icon: string;\n title: string;\n children: React.ReactNode;\n className?: string;\n}\n\nexport function Feature({ icon, title, children, className }: FeatureProps) {\n const IconComponent = ICON_MAP[icon] ?? HelpCircle;\n\n return (\n \n \n
\n
{title}
\n
\n {children}\n
\n
\n
\n );\n}\n" }, { "path": "apps/www/app/components/mdx/mermaid.tsx", "content": "\"use client\";\n\nimport { useEffect, useId, useRef, useState } from \"react\";\nimport { useTheme } from \"next-themes\";\n\ninterface MermaidProps {\n chart: string;\n}\n\nlet mermaidPromise: Promise | null = null;\n\nfunction getMermaid() {\n if (!mermaidPromise) {\n mermaidPromise = import(\"mermaid\");\n }\n return mermaidPromise;\n}\n\nexport function Mermaid({ chart }: MermaidProps) {\n const id = useId();\n const { resolvedTheme } = useTheme();\n const [svg, setSvg] = useState(\"\");\n const [mounted, setMounted] = useState(false);\n const renderHostRef = useRef(null);\n\n useEffect(() => {\n setMounted(true);\n }, []);\n\n useEffect(() => {\n if (!mounted) return;\n const renderHost = renderHostRef.current;\n if (!renderHost) return;\n\n const render = async () => {\n const mermaid = await getMermaid();\n const isDark = resolvedTheme === \"dark\";\n\n mermaid.default.initialize({\n startOnLoad: false,\n theme: \"base\",\n securityLevel: \"loose\",\n themeVariables: {\n // Background\n background: isDark ? \"#0a0a0a\" : \"#ffffff\",\n primaryColor: isDark ? \"#1e293b\" : \"#f1f5f9\",\n\n // Text\n primaryTextColor: isDark ? \"#e2e8f0\" : \"#1e293b\",\n secondaryTextColor: isDark ? \"#94a3b8\" : \"#64748b\",\n\n // Lines and borders\n lineColor: isDark ? \"#475569\" : \"#cbd5e1\",\n primaryBorderColor: isDark ? \"#475569\" : \"#cbd5e1\",\n\n // Edge labels\n edgeLabelBackground: isDark ? \"#1e293b\" : \"#f8fafc\",\n tertiaryTextColor: isDark ? \"#cbd5e1\" : \"#475569\",\n\n // Font\n fontFamily: \"ui-sans-serif, system-ui, sans-serif\",\n fontSize: \"14px\",\n },\n });\n\n const { svg: renderedSvg } = await mermaid.default.render(\n `mermaid-${id.replace(/:/g, \"\")}`,\n chart,\n renderHost,\n );\n\n // Post-process SVG to add padding to edge labels\n const parser = new DOMParser();\n const doc = parser.parseFromString(renderedSvg, \"image/svg+xml\");\n\n // Add padding to edge label backgrounds\n doc.querySelectorAll(\".edgeLabel rect\").forEach((rect) => {\n const currentX = parseFloat(rect.getAttribute(\"x\") || \"0\");\n const currentY = parseFloat(rect.getAttribute(\"y\") || \"0\");\n const currentWidth = parseFloat(rect.getAttribute(\"width\") || \"0\");\n const currentHeight = parseFloat(rect.getAttribute(\"height\") || \"0\");\n const padding = 6;\n\n rect.setAttribute(\"x\", String(currentX - padding));\n rect.setAttribute(\"y\", String(currentY - padding / 2));\n rect.setAttribute(\"width\", String(currentWidth + padding * 2));\n rect.setAttribute(\"height\", String(currentHeight + padding));\n rect.setAttribute(\"rx\", \"4\");\n });\n\n const serializer = new XMLSerializer();\n setSvg(serializer.serializeToString(doc));\n };\n\n render();\n }, [chart, id, mounted, resolvedTheme]);\n\n return (\n
\n \n {!mounted ? (\n
\n \n Loading diagram...\n \n
\n ) : (\n \n )}\n
\n );\n}\n" }, { "path": "apps/www/app/components/theme/theme-provider.tsx", "content": "\"use client\";\n\nimport * as React from \"react\";\nimport { ThemeProvider as NextThemesProvider } from \"next-themes\";\n\ntype ThemeProviderProps = React.ComponentProps;\n\nexport function ThemeProvider({ children, ...props }: ThemeProviderProps) {\n return {children};\n}\n" }, { "path": "apps/www/app/components/visuals/spinning-hexnut/hexnut-scene.tsx", "content": "\"use client\";\n\nimport { useEffect, useRef, useMemo, useState } from \"react\";\nimport { createPortal } from \"react-dom\";\nimport { Canvas, useFrame } from \"@react-three/fiber\";\nimport { OrbitControls } from \"@react-three/drei\";\nimport * as THREE from \"three\";\nimport { Mesh, Shape, Path, ExtrudeGeometry } from \"three\";\nimport { useTheme } from \"next-themes\";\n\nfunction createHexnutGeometry(\n outerRadius = 1,\n innerRadius = 0.5,\n height = 0.4,\n) {\n const shape = new Shape();\n\n // Create hexagon outer shape\n for (let i = 0; i < 6; i++) {\n const angle = (i / 6) * Math.PI * 2;\n const x = Math.cos(angle) * outerRadius;\n const y = Math.sin(angle) * outerRadius;\n if (i === 0) {\n shape.moveTo(x, y);\n } else {\n shape.lineTo(x, y);\n }\n }\n shape.closePath();\n\n // Create circular hole\n const hole = new Path();\n const segments = 32;\n for (let i = 0; i < segments; i++) {\n const angle = (i / segments) * Math.PI * 2;\n const x = Math.cos(angle) * innerRadius;\n const y = Math.sin(angle) * innerRadius;\n if (i === 0) {\n hole.moveTo(x, y);\n } else {\n hole.lineTo(x, y);\n }\n }\n hole.closePath();\n shape.holes.push(hole);\n\n const geometry = new ExtrudeGeometry(shape, {\n depth: height,\n bevelEnabled: false,\n });\n\n // Center the geometry so it rotates around its true center\n geometry.center();\n\n return geometry;\n}\n\ninterface HexnutProps {\n color?: string;\n scale?: number;\n initialRotation?: [number, number, number];\n rotationSpeed?: number;\n dragState: React.RefObject<{\n isDragging: boolean;\n deltaX: number;\n velocity: number;\n }>;\n}\n\nconst DRAG_SENSITIVITY = 0.01;\nconst MOMENTUM_FRICTION = 0.96;\nconst MAX_VELOCITY = 10;\n\ntype ThemeConfig = {\n lightX: number;\n lightY: number;\n lightZ: number;\n intensity: number;\n rotX: number;\n rotY: number;\n scale: number;\n speed: number;\n cameraZ: number;\n};\n\nconst THEME_CONFIGS: Record<\"dark\" | \"light\", ThemeConfig> = {\n dark: {\n lightX: -50,\n lightY: -50,\n lightZ: -31,\n intensity: 4,\n rotX: -0.7,\n rotY: 0.72,\n scale: 2.1,\n speed: 0.15,\n cameraZ: 6.8,\n },\n light: {\n lightX: 50,\n lightY: 50,\n lightZ: 50,\n intensity: 50,\n rotX: -0.7,\n rotY: 0.72,\n scale: 2.1,\n speed: 0.15,\n cameraZ: 6.8,\n },\n};\n\nfunction RotatingHexnut({\n color = \"#ffffff\",\n scale = 2.1,\n initialRotation = [0.75, -0.75, 0],\n rotationSpeed = 0.1,\n dragState,\n}: HexnutProps) {\n const meshRef = useRef(null);\n const geometry = useMemo(() => createHexnutGeometry(1.2, 0.6, 0.5), []);\n const velocity = useRef(rotationSpeed);\n const wasDragging = useRef(false);\n\n useFrame((_, delta) => {\n if (!meshRef.current) return;\n\n if (dragState.current.isDragging) {\n const dragDelta = dragState.current.deltaX * DRAG_SENSITIVITY;\n meshRef.current.rotation.z += dragDelta;\n dragState.current.deltaX = 0;\n wasDragging.current = true;\n } else {\n if (wasDragging.current) {\n const rawVelocity = dragState.current.velocity;\n const sign = rawVelocity >= 0 ? 1 : -1;\n velocity.current = sign * Math.min(Math.abs(rawVelocity), MAX_VELOCITY);\n wasDragging.current = false;\n }\n\n const absVelocity = Math.abs(velocity.current);\n const absTarget = Math.abs(rotationSpeed);\n\n if (absVelocity > absTarget) {\n velocity.current *= MOMENTUM_FRICTION;\n\n if (absVelocity <= absTarget) {\n velocity.current = rotationSpeed;\n }\n } else {\n velocity.current = rotationSpeed;\n }\n\n meshRef.current.rotation.z += delta * velocity.current;\n }\n });\n\n return (\n \n \n \n );\n}\n\ninterface PostFXOptions {\n scanlines?: boolean;\n scanlineOpacity?: number;\n vignette?: boolean;\n vignetteIntensity?: number;\n noise?: boolean;\n noiseOpacity?: number;\n}\n\ninterface HexnutSceneProps {\n width?: string | number;\n height?: string | number;\n className?: string;\n postfx?: PostFXOptions;\n debug?: boolean;\n}\n\nexport function HexnutScene({\n width = \"100%\",\n height = \"100%\",\n className,\n postfx = {},\n debug = false,\n}: HexnutSceneProps) {\n const containerRef = useRef(null);\n const [mounted, setMounted] = useState(false);\n const { resolvedTheme } = useTheme();\n\n const dragState = useRef({ isDragging: false, deltaX: 0, velocity: 0 });\n const previousX = useRef(0);\n const lastMoveTime = useRef(0);\n\n const handlePointerDown = (e: React.PointerEvent) => {\n dragState.current.isDragging = true;\n dragState.current.velocity = 0;\n previousX.current = e.clientX;\n lastMoveTime.current = performance.now();\n containerRef.current?.setPointerCapture(e.pointerId);\n };\n\n const handlePointerUp = (e: React.PointerEvent) => {\n dragState.current.isDragging = false;\n containerRef.current?.releasePointerCapture(e.pointerId);\n };\n\n const handlePointerMove = (e: React.PointerEvent) => {\n if (!dragState.current.isDragging) return;\n const now = performance.now();\n const dt = (now - lastMoveTime.current) / 1000;\n const dx = e.clientX - previousX.current;\n\n dragState.current.deltaX = dx;\n if (dt > 0) {\n dragState.current.velocity = (dx * DRAG_SENSITIVITY) / dt;\n }\n\n previousX.current = e.clientX;\n lastMoveTime.current = now;\n };\n\n const isDark = resolvedTheme === \"dark\";\n const currentConfig = isDark ? THEME_CONFIGS.dark : THEME_CONFIGS.light;\n\n // Debug state - initialized from theme config\n const [panelOpen, setPanelOpen] = useState(true);\n const [lightX, setLightX] = useState(currentConfig.lightX);\n const [lightY, setLightY] = useState(currentConfig.lightY);\n const [lightZ, setLightZ] = useState(currentConfig.lightZ);\n const [intensity, setIntensity] = useState(currentConfig.intensity);\n const [rotX, setRotX] = useState(currentConfig.rotX);\n const [rotY, setRotY] = useState(currentConfig.rotY);\n const [hexScale, setHexScale] = useState(currentConfig.scale);\n const [speed, setSpeed] = useState(currentConfig.speed);\n const [cameraZ, setCameraZ] = useState(currentConfig.cameraZ);\n\n // Sync state with theme when theme changes\n useEffect(() => {\n const config = isDark ? THEME_CONFIGS.dark : THEME_CONFIGS.light;\n setLightX(config.lightX);\n setLightY(config.lightY);\n setLightZ(config.lightZ);\n setIntensity(config.intensity);\n setRotX(config.rotX);\n setRotY(config.rotY);\n setHexScale(config.scale);\n setSpeed(config.speed);\n setCameraZ(config.cameraZ);\n }, [isDark]);\n\n // Always use state values (synced with theme or manually adjusted)\n const lightPosition: [number, number, number] = [lightX, lightY, lightZ];\n const lightIntensity = intensity;\n const initialRotation: [number, number, number] = [rotX, rotY, 0];\n\n const {\n scanlines = false,\n scanlineOpacity = 0.1,\n vignette = false,\n vignetteIntensity = 0,\n noise = false,\n noiseOpacity = 0.05,\n } = postfx;\n\n const [visible, setVisible] = useState(false);\n\n useEffect(() => {\n setMounted(true);\n }, []);\n\n // Called when WebGL context is fully initialized\n const handleCreated = ({ gl }: { gl: THREE.WebGLRenderer }) => {\n // Ensure transparent clear color from the start\n gl.setClearColor(0x000000, 0);\n // Now safe to fade in\n setVisible(true);\n };\n\n if (!mounted) {\n return (\n
\n );\n }\n\n return (\n \n \n \n\n \n \n \n\n {/* Debug Panel - portaled to body to escape stacking contexts */}\n {debug &&\n createPortal(\n \n setPanelOpen(!panelOpen)}\n style={{\n background: \"none\",\n border: \"none\",\n color: \"#fff\",\n cursor: \"pointer\",\n fontFamily: \"monospace\",\n fontSize: 10,\n padding: 0,\n marginBottom: panelOpen ? 6 : 0,\n }}\n >\n {panelOpen ? \"▼ Debug\" : \"▶ Debug\"}\n \n\n {panelOpen && (\n <>\n \n \n \n \n \n \n \n \n \n \n light: [{lightX}, {lightY}, {lightZ}]
\n int: {intensity} | rot: [{rotX.toFixed(2)}, {rotY.toFixed(2)}]\n
\n scale: {hexScale.toFixed(1)} | spd: {speed.toFixed(2)} | cam:{\" \"}\n {cameraZ.toFixed(1)}\n
\n \n )}\n
,\n document.body,\n )}\n\n {/* Scanlines overlay */}\n {scanlines && (\n \n )}\n\n {/* Vignette overlay */}\n {vignette && (\n \n )}\n\n {/* Noise overlay */}\n {noise && (\n \n )}\n \n );\n}\n" }, { "path": "apps/www/app/docs/_components/chat-context-preview.tsx", "content": "import type { ReactNode } from \"react\";\nimport { cn } from \"@/lib/ui/cn\";\n\ninterface ChatBubbleProps {\n role: \"user\" | \"assistant\";\n children: ReactNode;\n}\n\nfunction ChatBubble({ role, children }: ChatBubbleProps) {\n const isUser = role === \"user\";\n\n return (\n \n \n {children}\n \n \n );\n}\n\ninterface ChatContextPreviewProps {\n userMessage: string;\n preamble?: string;\n children: ReactNode;\n}\n\nexport function ChatContextPreview({\n userMessage,\n preamble,\n children,\n}: ChatContextPreviewProps) {\n return (\n
\n {userMessage}\n
\n {preamble && (\n \n {preamble}\n \n )}\n
{children}
\n
\n
\n );\n}\n" }, { "path": "apps/www/app/docs/_components/collaboration-diagram.tsx", "content": "\"use client\";\n\nexport function CollaborationDiagram() {\n return (\n \n \n \n \n \n \n \n \n \n \n \n \n\n {/* User circle */}\n \n \n User\n \n\n {/* Tool UI rounded rectangle */}\n \n \n Tool UI\n \n\n {/* Assistant circle */}\n \n \n Assistant\n \n\n {/* User → Surface: \"controls\" (solid) */}\n \n \n controls\n \n\n {/* Surface ↔ Assistant: \"mediates\" (solid, bidirectional) */}\n \n \n \n mediates\n \n\n {/* Assistant → User: \"narrates\" (dashed, curved) */}\n \n \n narrates\n \n \n );\n}\n" }, { "path": "apps/www/app/docs/_components/component-docs-tabs.tsx", "content": "\"use client\";\n\nimport dynamic from \"next/dynamic\";\nimport { memo, useCallback, useMemo, useRef, type ReactNode } from \"react\";\nimport { usePathname } from \"next/navigation\";\nimport { cn } from \"@/lib/ui/cn\";\nimport { Tabs, TabsContent, TabsList, TabsTrigger } from \"@/components/ui/tabs\";\nimport { DocsBorderedShell } from \"./docs-bordered-shell\";\nimport { DocsContent } from \"./docs-content\";\nimport type { ComponentId } from \"@/lib/docs/component-ids\";\nimport { useTabSearchParam } from \"@/hooks/use-tab-search-param\";\nimport { analytics } from \"@/lib/analytics\";\nimport { componentsRegistry } from \"@/lib/docs/component-registry\";\n\ntype DocsTab = \"docs\" | \"examples\";\n\nconst VALID_TABS = [\"docs\", \"examples\"] as const;\n\ninterface ComponentDocsTabsProps {\n docs: ReactNode;\n componentId?: ComponentId;\n examples?: ReactNode;\n}\n\nconst LazyComponentPreview = dynamic(\n () => import(\"./component-preview\").then((m) => m.ComponentPreview),\n {\n loading: () => (\n
\n Loading examples...\n
\n ),\n },\n);\n\nexport const ComponentDocsTabs = memo(function ComponentDocsTabs({\n docs,\n componentId,\n examples,\n}: ComponentDocsTabsProps) {\n const contentRef = useRef(null);\n const pathname = usePathname();\n const componentMeta = useMemo(\n () => componentsRegistry.find((component) => component.path === pathname),\n [pathname],\n );\n const tabsIdBase = useMemo(\n () =>\n componentId\n ? `docs-tabs-${componentId}`\n : `docs-tabs-${pathname.replaceAll(\"/\", \"-\") || \"root\"}`,\n [componentId, pathname],\n );\n\n const { activeTab, setActiveTab } = useTabSearchParam({\n defaultTab: \"docs\",\n validTabs: VALID_TABS,\n scrollTargetRef: contentRef,\n hashTrigger: \"#examples\",\n });\n\n const handleTabChange = useCallback(\n (value: string) => {\n if (value === \"docs\" || value === \"examples\") {\n if (componentMeta && value !== activeTab) {\n analytics.component.tabSwitched(componentMeta.id, value);\n }\n setActiveTab(value);\n }\n },\n [activeTab, componentMeta, setActiveTab],\n );\n\n return (\n \n \n \n \n \n \n Docs\n \n \n Examples\n \n \n \n\n \n \n
\n {docs}\n
\n \n \n {activeTab === \"examples\"\n ? (examples ??\n (componentId ? (\n \n ) : null))\n : null}\n \n \n \n \n );\n});\n" }, { "path": "apps/www/app/docs/_components/component-preview-shell.tsx", "content": "\"use client\";\n\nimport { memo, useCallback, type ReactNode } from \"react\";\nimport { Panel, PanelGroup, PanelResizeHandle } from \"react-resizable-panels\";\nimport type { ImperativePanelGroupHandle } from \"react-resizable-panels\";\nimport { Check, Code, Copy, Eye, MessageCircle } from \"lucide-react\";\nimport { Button } from \"@/components/ui/button\";\nimport { ToggleGroup, ToggleGroupItem } from \"@/components/ui/toggle-group\";\nimport { cn } from \"@/lib/ui/cn\";\nimport { useResponsivePreview } from \"@/hooks/use-responsive-preview\";\nimport { useTabSearchParam } from \"@/hooks/use-tab-search-param\";\nimport { useCopyToClipboard } from \"@/components/tool-ui/shared\";\nimport { InstallCommandBlock } from \"./install-command-block\";\nimport { analytics } from \"@/lib/analytics\";\n\nconst PREVIEW_MIN_WIDTH = 40;\nconst PREVIEW_MAX_WIDTH = 100;\n\nconst VALID_VIEW_MODES = [\"canvas\", \"chat\", \"code\"] as const;\ntype ViewMode = (typeof VALID_VIEW_MODES)[number];\n\nfunction toStablePanelIdSegment(value: string): string {\n const normalized = value\n .toLowerCase()\n .replace(/[^a-z0-9-]+/g, \"-\")\n .replace(/^-+|-+$/g, \"\");\n return normalized || \"component\";\n}\n\nfunction ViewModeToggle({\n value,\n onValueChange,\n}: {\n value: ViewMode;\n onValueChange: (value: ViewMode) => void;\n}) {\n return (\n v && onValueChange(v as ViewMode)}\n size=\"sm\"\n className=\"bg-primary/5 rounded-lg p-[3px]\"\n >\n \n \n \n \n \n \n \n \n \n \n );\n}\n\nconst RESIZE_HANDLE_STYLES = cn(\n \"absolute top-1/2 left-1/2 h-12 w-1\",\n \"-translate-x-1/2 -translate-y-1/2 rounded-full\",\n \"transition-all duration-200\",\n \"bg-gray-300 opacity-0\",\n \"group-hover/canvas:opacity-60\",\n \"group-data-resize-handle-active/handle:bg-gray-500 group-data-resize-handle-active/handle:opacity-100\",\n \"dark:bg-gray-500 dark:group-data-resize-handle-active/handle:bg-gray-400\",\n);\n\nconst ResizablePreviewArea = memo(function ResizablePreviewArea({\n panelGroupRef,\n handleLayout,\n panelIdBase,\n children,\n}: {\n panelGroupRef: React.RefObject;\n handleLayout: (sizes: number[]) => void;\n panelIdBase: string;\n children: ReactNode;\n}) {\n return (\n \n \n \n
\n \n \n \n {children}\n
\n \n \n
\n \n \n \n );\n});\n\ninterface ComponentPreviewShellProps {\n componentId: string;\n sidebar: ReactNode;\n preview: ReactNode;\n chatPanel: ReactNode;\n codePanel: ReactNode;\n code: string;\n}\n\nconst COPY_ID = \"code-panel\";\n\nexport function ComponentPreviewShell({\n componentId,\n sidebar,\n preview,\n chatPanel,\n codePanel,\n code,\n}: ComponentPreviewShellProps) {\n const { activeTab: viewMode, setActiveTab: setViewMode } =\n useTabSearchParam({\n paramName: \"view\",\n defaultTab: \"canvas\",\n validTabs: VALID_VIEW_MODES,\n });\n const { copiedId, copy } = useCopyToClipboard();\n const copied = copiedId === COPY_ID;\n const panelIdBase = `component-preview-${toStablePanelIdSegment(componentId)}`;\n const { panelGroupRef, handleLayout } = useResponsivePreview({\n minWidth: PREVIEW_MIN_WIDTH,\n maxWidth: PREVIEW_MAX_WIDTH,\n });\n\n const handleCopy = useCallback(() => {\n analytics.component.codeCopied(componentId, \"full\");\n analytics.code.blockCopied(\"tsx\", \"component_preview\");\n copy(code, COPY_ID);\n }, [componentId, code, copy]);\n\n const handleViewModeChange = useCallback(\n (nextViewMode: ViewMode) => {\n if (nextViewMode === viewMode) return;\n\n analytics.component.tabSwitched(componentId, nextViewMode);\n analytics.component.previewInteracted(\n componentId,\n `view_mode_${nextViewMode}`,\n );\n setViewMode(nextViewMode);\n },\n [componentId, setViewMode, viewMode],\n );\n\n return (\n
\n {/* Desktop sidebar */}\n \n
\n {sidebar}\n
\n \n\n {/* Main content area */}\n
\n {/* Install commands - above the gray preview, in main column only */}\n
\n \n
\n\n {/* Mobile toolbar */}\n
\n
{sidebar}
\n
\n \n
\n
\n\n \n {viewMode === \"canvas\" && (\n \n )}\n\n {viewMode === \"code\" && (\n \n )}\n\n {/* View mode toggle - top left corner */}\n \n\n {/* Copy button - top right corner (code view only) */}\n {viewMode === \"code\" && (\n \n )}\n\n \n {viewMode === \"canvas\" && (\n
\n \n {preview}\n \n
\n )}\n {viewMode === \"chat\" && (\n
\n
{chatPanel}
\n
\n )}\n {viewMode === \"code\" && codePanel}\n
\n
\n
\n \n );\n}\n" }, { "path": "apps/www/app/docs/_components/component-preview.tsx", "content": "\"use client\";\n\nimport { useCallback, useState } from \"react\";\nimport { ComponentPreviewShell } from \"./component-preview-shell\";\nimport { ChatContextPreview } from \"./chat-context-preview\";\nimport { PresetSelector } from \"./preset-selector\";\nimport { getImportLine } from \"@/lib/docs/gallery-usage-code\";\nimport {\n type ComponentId,\n getPreviewConfig,\n type PreviewState,\n} from \"@/lib/docs/preview-config\";\nimport { usePresetParam } from \"@/hooks/use-preset-param\";\nimport { TrackedDynamicCodeBlock } from \"./tracked-dynamic-codeblock\";\n\ninterface ComponentPreviewProps {\n componentId: ComponentId;\n}\n\nconst EMPTY_STATE: PreviewState = {};\n\nexport function ComponentPreview({ componentId }: ComponentPreviewProps) {\n const config = getPreviewConfig(componentId);\n\n const { currentPreset, setPreset } = usePresetParam({\n presets: config.presets,\n defaultPreset: config.defaultPreset,\n });\n\n const [state, setState] = useState(EMPTY_STATE);\n const [prevPreset, setPrevPreset] = useState(currentPreset);\n\n if (currentPreset !== prevPreset) {\n setPrevPreset(currentPreset);\n setState(EMPTY_STATE);\n }\n\n const handleSelectPreset = useCallback(\n (preset: unknown) => {\n setPreset(preset as string);\n setState(EMPTY_STATE);\n },\n [setPreset],\n );\n\n const handleSetState = useCallback((newState: Partial) => {\n setState((prev) => ({ ...prev, ...newState }));\n }, []);\n\n const preset =\n config.presets[currentPreset] ?? config.presets[config.defaultPreset];\n const selectedPreset = config.presets[currentPreset] ?? preset;\n const body = selectedPreset.generateExampleCode(selectedPreset.data);\n const code = `${getImportLine(componentId)}\\n\\n${body}`;\n\n const previewContent = config.renderComponent({\n data: preset.data,\n presetName: currentPreset,\n state,\n setState: handleSetState,\n });\n\n const wrappedPreview = config.wrapper ? (\n {previewContent}\n ) : (\n previewContent\n );\n\n const displayPreview = wrappedPreview;\n\n const chatPanel = (\n \n {displayPreview}\n \n );\n\n return (\n \n }\n preview={displayPreview}\n chatPanel={chatPanel}\n codePanel={\n
\n \n
\n }\n code={code}\n />\n );\n}\n" }, { "path": "apps/www/app/docs/_components/component-previews/social-post-preview.tsx", "content": "\"use client\";\n\nimport { useCallback, useMemo, useState, type ReactNode } from \"react\";\nimport { useSearchParams, usePathname, useRouter } from \"next/navigation\";\nimport { ComponentPreviewShell } from \"../component-preview-shell\";\nimport { ChatContextPreview } from \"../chat-context-preview\";\nimport { XPost } from \"@/components/tool-ui/x-post\";\nimport { InstagramPost } from \"@/components/tool-ui/instagram-post\";\nimport { LinkedInPost } from \"@/components/tool-ui/linkedin-post\";\nimport { ToolUI, type Action } from \"@/components/tool-ui/shared\";\nimport { xPostPresets, type XPostPresetName } from \"@/lib/presets/x-post\";\nimport {\n instagramPostPresets,\n type InstagramPostPresetName,\n} from \"@/lib/presets/instagram-post\";\nimport {\n linkedInPostPresets,\n type LinkedInPostPresetName,\n} from \"@/lib/presets/linkedin-post\";\nimport {\n Item,\n ItemContent,\n ItemDescription,\n ItemGroup,\n ItemTitle,\n} from \"@/components/ui/item\";\nimport { Tabs, TabsList, TabsTrigger } from \"@/components/ui/tabs\";\nimport { cn } from \"@/lib/ui/cn\";\n\ntype Platform = \"x\" | \"instagram\" | \"linkedin\";\ntype PresetName =\n | XPostPresetName\n | InstagramPostPresetName\n | LinkedInPostPresetName;\n\nconst VALID_PLATFORMS: readonly Platform[] = [\"x\", \"instagram\", \"linkedin\"];\n\nfunction resolveActions(actions: unknown): Action[] | null {\n if (Array.isArray(actions)) return actions as Action[];\n\n if (typeof actions === \"object\" && actions !== null) {\n const items = (actions as { items?: unknown }).items;\n if (Array.isArray(items)) return items as Action[];\n }\n\n return null;\n}\n\nconst platformConfig = {\n x: {\n label: \"X (Twitter)\",\n presets: xPostPresets,\n presetNames: Object.keys(xPostPresets) as XPostPresetName[],\n },\n instagram: {\n label: \"Instagram\",\n presets: instagramPostPresets,\n presetNames: Object.keys(instagramPostPresets) as InstagramPostPresetName[],\n },\n linkedin: {\n label: \"LinkedIn\",\n presets: linkedInPostPresets,\n presetNames: Object.keys(linkedInPostPresets) as LinkedInPostPresetName[],\n },\n} as const;\n\nfunction getPresetNames(platform: Platform): PresetName[] {\n return [...platformConfig[platform].presetNames] as PresetName[];\n}\n\nfunction getValidPreset(platform: Platform, preset: string | null): PresetName {\n const presetNames = getPresetNames(platform);\n if (preset && (presetNames as readonly string[]).includes(preset)) {\n return preset as PresetName;\n }\n return presetNames[0];\n}\n\nfunction PlatformSelector({\n currentPlatform,\n onSelectPlatform,\n}: {\n currentPlatform: Platform;\n onSelectPlatform: (platform: Platform) => void;\n}) {\n return (\n
\n
\n Platform\n
\n onSelectPlatform(value as Platform)}\n >\n \n \n X\n \n \n Instagram\n \n \n LinkedIn\n \n \n \n
\n );\n}\n\nfunction PresetSelector({\n platform,\n currentPreset,\n onSelectPreset,\n}: {\n platform: Platform;\n currentPreset: PresetName;\n onSelectPreset: (preset: PresetName) => void;\n}) {\n const config = platformConfig[platform];\n const presets = config.presets as Record<\n string,\n { description: string; data: unknown }\n >;\n const presetNames = getPresetNames(platform);\n\n return (\n \n {presetNames.map((preset) => (\n onSelectPreset(preset as PresetName)}\n >\n \n
\n
\n \n \n {preset.replace(\"-\", \" \").replace(\"_\", \" \")}\n \n \n \n {presets[preset].description}\n \n
\n
\n \n \n \n ))}\n \n );\n}\n\nexport function SocialPostPreview({\n platformLock,\n}: {\n platformLock?: Platform;\n}) {\n const router = useRouter();\n const pathname = usePathname();\n const searchParams = useSearchParams();\n const lockedPlatform = platformLock;\n const isPlatformLocked = Boolean(lockedPlatform);\n\n const platformParam = searchParams.get(\"platform\");\n const presetParam = searchParams.get(\"preset\");\n\n const initialPlatform = useMemo((): Platform => {\n if (lockedPlatform) return lockedPlatform;\n if (platformParam && VALID_PLATFORMS.includes(platformParam as Platform)) {\n return platformParam as Platform;\n }\n return \"x\";\n }, [lockedPlatform, platformParam]);\n\n const initialPreset = useMemo(\n () => getValidPreset(initialPlatform, presetParam),\n [initialPlatform, presetParam],\n );\n\n const [currentPlatform, setCurrentPlatform] =\n useState(initialPlatform);\n const [currentPreset, setCurrentPreset] = useState(initialPreset);\n\n const [prevPlatformParam, setPrevPlatformParam] = useState(platformParam);\n const [prevPresetParam, setPrevPresetParam] = useState(presetParam);\n const [prevLockedPlatform, setPrevLockedPlatform] = useState(lockedPlatform);\n\n if (\n platformParam !== prevPlatformParam ||\n presetParam !== prevPresetParam ||\n lockedPlatform !== prevLockedPlatform\n ) {\n setPrevPlatformParam(platformParam);\n setPrevPresetParam(presetParam);\n setPrevLockedPlatform(lockedPlatform);\n\n const nextPlatform = lockedPlatform\n ? lockedPlatform\n : platformParam && VALID_PLATFORMS.includes(platformParam as Platform)\n ? (platformParam as Platform)\n : currentPlatform;\n\n setCurrentPlatform(nextPlatform);\n setCurrentPreset(getValidPreset(nextPlatform, presetParam));\n }\n\n const updateUrl = useCallback(\n (platform: Platform, preset: PresetName) => {\n const params = new URLSearchParams(searchParams.toString());\n\n if (isPlatformLocked) {\n params.delete(\"platform\");\n } else {\n params.set(\"platform\", platform);\n }\n params.set(\"preset\", preset);\n router.push(`${pathname}?${params.toString()}`, { scroll: false });\n },\n [isPlatformLocked, pathname, router, searchParams],\n );\n\n const handleSelectPlatform = useCallback(\n (platform: Platform) => {\n if (isPlatformLocked) return;\n const defaultPreset = platformConfig[platform].presetNames[0];\n setCurrentPlatform(platform);\n setCurrentPreset(defaultPreset);\n updateUrl(platform, defaultPreset);\n },\n [isPlatformLocked, updateUrl],\n );\n\n const handleSelectPreset = useCallback(\n (preset: PresetName) => {\n setCurrentPreset(preset);\n updateUrl(currentPlatform, preset);\n },\n [currentPlatform, updateUrl],\n );\n\n const effectivePreset = currentPreset as\n | XPostPresetName\n | InstagramPostPresetName\n | LinkedInPostPresetName;\n\n const renderWithLocalActions = (\n id: string,\n surface: ReactNode,\n actions: Action[] | null,\n ) => {\n if (!actions || actions.length === 0) {\n return
{surface}
;\n }\n\n return (\n \n
\n {surface}\n \n alert(`Local action: ${actionId}`)}\n />\n \n
\n \n );\n };\n\n const renderedPost =\n currentPlatform === \"x\"\n ? renderWithLocalActions(\n xPostPresets[effectivePreset as XPostPresetName].data.post.id,\n \n console.log(\"X action:\", action, post.id)\n }\n />,\n resolveActions(\n xPostPresets[effectivePreset as XPostPresetName].data.localActions,\n ),\n )\n : currentPlatform === \"instagram\"\n ? renderWithLocalActions(\n instagramPostPresets[effectivePreset as InstagramPostPresetName]\n .data.post.id,\n \n console.log(\"Instagram action:\", action, post.id)\n }\n />,\n resolveActions(\n instagramPostPresets[effectivePreset as InstagramPostPresetName]\n .data.localActions,\n ),\n )\n : renderWithLocalActions(\n linkedInPostPresets[effectivePreset as LinkedInPostPresetName].data\n .post.id,\n \n console.log(\"LinkedIn action:\", action, post.id)\n }\n />,\n resolveActions(\n linkedInPostPresets[effectivePreset as LinkedInPostPresetName]\n .data.localActions,\n ),\n );\n\n const previewContent = (\n
{renderedPost}
\n );\n\n const chatPanel = (\n \n {previewContent}\n \n );\n\n return (\n \n {!isPlatformLocked && (\n \n )}\n \n \n }\n preview={previewContent}\n chatPanel={chatPanel}\n codePanel={\n
\n Code panel coming soon\n
\n }\n code=\"\"\n />\n );\n}\n" }, { "path": "apps/www/app/docs/_components/copy-markdown-button.tsx", "content": "\"use client\";\n\nimport type { MouseEventHandler } from \"react\";\nimport { useCopyButton } from \"fumadocs-ui/utils/use-copy-button\";\nimport { Button } from \"@/components/ui/button\";\nimport { Check, Copy as CopyIcon } from \"lucide-react\";\nimport { analytics } from \"@/lib/analytics\";\n\ntype CopyMarkdownButtonProps = {\n markdown: string;\n};\n\nexport function CopyMarkdownButton({ markdown }: CopyMarkdownButtonProps) {\n const [checked, copyMarkdown] = useCopyButton(async () => {\n await navigator.clipboard.writeText(markdown);\n });\n\n const onClick: MouseEventHandler = (event) => {\n analytics.code.blockCopied(\"markdown\", \"docs_header\");\n copyMarkdown(event);\n };\n\n return (\n \n {checked ? : }\n {checked ? \"Copied\" : \"Copy Page\"}\n \n );\n}\n" }, { "path": "apps/www/app/docs/_components/docs-article.tsx", "content": "\"use client\";\n\nimport type { ReactNode } from \"react\";\nimport { DocsBorderedShell } from \"./docs-bordered-shell\";\nimport { DocsContent } from \"./docs-content\";\nimport { useDocsToc } from \"./docs-toc-context\";\nimport { DocsTocWrapper } from \"./docs-toc-wrapper\";\n\nexport function DocsArticle({\n children,\n className,\n}: {\n children: ReactNode;\n className?: string;\n}) {\n const { scrollContainerRef } = useDocsToc();\n\n return (\n \n \n
\n {children}\n \n
\n \n \n );\n}\n" }, { "path": "apps/www/app/docs/_components/docs-bordered-shell.tsx", "content": "import type { ReactNode } from \"react\";\nimport { cn } from \"@/lib/ui/cn\";\n\nexport function DocsBorderedShell({\n children,\n className,\n}: {\n children: ReactNode;\n className?: string;\n}) {\n return (\n \n
\n {children}\n
\n \n );\n}\n" }, { "path": "apps/www/app/docs/_components/docs-content.tsx", "content": "import type { ReactNode } from \"react\";\nimport { cn } from \"@/lib/ui/cn\";\nimport { DocsPager } from \"./docs-pager\";\n\ninterface DocsContentProps {\n children: ReactNode;\n className?: string;\n includePager?: boolean;\n}\n\nexport function DocsContent({\n children,\n className,\n includePager = true,\n}: DocsContentProps) {\n return (\n \n {children}\n {includePager && }\n \n );\n}\n" }, { "path": "apps/www/app/docs/_components/docs-header.tsx", "content": "import { CopyMarkdownButton } from \"./copy-markdown-button\";\nimport { HeaderPreviewTabs } from \"./header-preview-tabs\";\nimport { InstallCommandLine } from \"./install-command-line\";\nimport { getMdxAsMarkdown } from \"./mdx-to-markdown\";\nimport { isComponentId } from \"@/lib/docs/component-ids\";\n\ntype DocsHeaderProps = {\n title: string;\n description?: string;\n mdxPath?: string;\n};\n\nexport function DocsHeader({ title, description, mdxPath }: DocsHeaderProps) {\n const markdown = mdxPath ? getMdxAsMarkdown(mdxPath) : undefined;\n const componentIdMatch = mdxPath?.match(/^app\\/docs\\/([^/]+)\\/content\\.mdx$/);\n const parsedComponentId = componentIdMatch?.[1];\n const componentId =\n parsedComponentId && isComponentId(parsedComponentId)\n ? parsedComponentId\n : null;\n\n return (\n
\n
\n

{title}

\n {markdown && }\n
\n {description && (\n
{description}
\n )}\n {componentId && (\n \n )}\n {componentId && }\n
\n );\n}\n" }, { "path": "apps/www/app/docs/_components/docs-nav.tsx", "content": "\"use client\";\n\nimport React, { useState } from \"react\";\nimport Link from \"next/link\";\nimport { usePathname } from \"next/navigation\";\nimport { useQueryState } from \"nuqs\";\nimport { LayoutDashboardIcon } from \"lucide-react\";\nimport { analytics } from \"@/lib/analytics\";\nimport {\n componentsRegistry,\n componentsByCategory,\n CATEGORY_META,\n type ComponentCategory,\n} from \"@/lib/docs/component-registry\";\nimport { cn } from \"@/lib/ui/cn\";\nimport { CONCEPTS_DOCS_PAGES, GET_STARTED_DOCS_PAGES } from \"./docs-pages\";\n\nconst STORAGE_KEY = \"tool-ui-components-nav-collapsed:v1\";\n\nexport function DocsNav() {\n const pathname = usePathname();\n const [currentTab] = useQueryState(\"tab\");\n const [currentView] = useQueryState(\"view\");\n const [collapsed, setCollapsed] = useState(false);\n const [isPressing, setIsPressing] = useState(false);\n const [prevPathname, setPrevPathname] = useState(pathname);\n const previousPathRef = React.useRef(null);\n\n if (pathname !== prevPathname) {\n setPrevPathname(pathname);\n setIsPressing(false);\n }\n\n React.useEffect(() => {\n try {\n if (typeof window !== \"undefined\") {\n const stored = window.localStorage.getItem(STORAGE_KEY);\n if (stored != null) setCollapsed(stored === \"true\");\n }\n } catch {}\n }, []);\n\n React.useEffect(() => {\n const handleMouseUp = (e: MouseEvent) => {\n const target = e.target as HTMLElement;\n const isNavLink = target.closest('a[href^=\"/docs\"]');\n if (!isNavLink) {\n setIsPressing(false);\n }\n };\n document.addEventListener(\"mouseup\", handleMouseUp);\n return () => document.removeEventListener(\"mouseup\", handleMouseUp);\n }, []);\n\n React.useEffect(() => {\n const component = componentsRegistry.find(\n (entry) => entry.path === pathname,\n );\n if (component) {\n const source =\n previousPathRef.current === \"/docs/gallery\" ? \"gallery\" : \"direct\";\n analytics.component.viewed(component.id, source);\n }\n\n previousPathRef.current = pathname;\n }, [pathname]);\n\n const buildLinkClasses = (isActive: boolean) =>\n cn(\n \"flex items-center gap-2 rounded-lg px-4 bg-background text-primary py-2 text-sm transition-[colors,background] duration-75\",\n {\n \"justify-center px-0\": collapsed,\n\n \"bg-primary/5\": isActive && !isPressing,\n \"hover:bg-primary/2\": !isActive,\n \"hover:bg-primary/5\": isPressing && !isActive,\n },\n );\n\n const handleLinkMouseDown = () => setIsPressing(true);\n\n const galleryPath = \"/docs/gallery\";\n const isGalleryActive = pathname === galleryPath;\n\n const categorizedComponents = (\n Object.entries(CATEGORY_META) as [\n ComponentCategory,\n (typeof CATEGORY_META)[ComponentCategory],\n ][]\n )\n .sort(([, a], [, b]) => a.order - b.order)\n .map(([category, meta]) => ({\n category,\n label: meta.label,\n components: componentsByCategory.get(category) || [],\n }));\n\n return (\n \n \n \n );\n}\n" }, { "path": "apps/www/app/docs/_components/docs-pager.tsx", "content": "\"use client\";\n\nimport * as React from \"react\";\nimport Link from \"next/link\";\nimport { usePathname } from \"next/navigation\";\nimport { ArrowLeft, ArrowRight } from \"lucide-react\";\nimport { getAllDocsPageLinks } from \"./docs-pages\";\nimport { cn } from \"@/lib/ui/cn\";\nimport { Button } from \"@/components/ui/button\";\nimport { analytics } from \"@/lib/analytics\";\n\nfunction useDocsPagination() {\n const pathname = usePathname();\n\n return React.useMemo(() => {\n const links = getAllDocsPageLinks();\n const currentIndex = links.findIndex((link) => link.path === pathname);\n if (currentIndex === -1) return { prev: null, next: null };\n const prev = currentIndex > 0 ? links[currentIndex - 1] : null;\n const next =\n currentIndex < links.length - 1 ? links[currentIndex + 1] : null;\n return { prev, next };\n }, [pathname]);\n}\n\ntype PagerLinkProps = {\n href: string;\n label: string;\n direction: \"prev\" | \"next\";\n};\n\nfunction PagerLink({ href, label, direction }: PagerLinkProps) {\n const isPrev = direction === \"prev\";\n return (\n \n analytics.docs.navigationClicked(label, href)}\n className={cn(\n \"inline-flex items-center gap-3\",\n isPrev ? \"text-left\" : \"text-right\",\n )}\n >\n {isPrev ? (\n <>\n \n {label}\n \n ) : (\n <>\n \n {label}\n \n \n \n )}\n \n \n );\n}\n\nexport function DocsPager() {\n const { prev, next } = useDocsPagination();\n\n if (!prev && !next) return null;\n\n return (\n
\n
\n {prev ? (\n \n ) : (\n \n )}\n {next ? (\n \n ) : (\n \n )}\n
\n
\n );\n}\n" }, { "path": "apps/www/app/docs/_components/docs-pages.ts", "content": "import { componentsRegistry } from \"@/lib/docs/component-registry\";\n\nexport type DocsPageLink = {\n path: string;\n label: string;\n};\n\nexport const GET_STARTED_DOCS_PAGES: DocsPageLink[] = [\n { path: \"/docs/overview\", label: \"Overview\" },\n { path: \"/docs/quick-start\", label: \"Quick Start\" },\n { path: \"/docs/agent-skills\", label: \"Agent Skills\" },\n { path: \"/docs/advanced\", label: \"Advanced\" },\n { path: \"/docs/design-guidelines\", label: \"UI Guidelines\" },\n { path: \"/docs/changelog\", label: \"Changelog\" },\n];\n\nexport const CONCEPTS_DOCS_PAGES: DocsPageLink[] = [\n { path: \"/docs/actions\", label: \"Actions\" },\n { path: \"/docs/receipts\", label: \"Receipts\" },\n];\n\nexport const BASE_DOCS_PAGES: DocsPageLink[] = [\n ...GET_STARTED_DOCS_PAGES,\n ...CONCEPTS_DOCS_PAGES,\n];\n\nexport function getAllDocsPageLinks(): DocsPageLink[] {\n return [\n ...BASE_DOCS_PAGES,\n ...componentsRegistry.map((component) => ({\n path: component.path,\n label: component.label,\n })),\n ];\n}\n" }, { "path": "apps/www/app/docs/_components/docs-search-shortcut.ts", "content": "export type SearchShortcutEvent = Pick<\n KeyboardEvent,\n \"metaKey\" | \"ctrlKey\" | \"key\" | \"preventDefault\" | \"defaultPrevented\"\n>;\n\nconst handledShortcutEvents = new WeakSet();\n\nexport const triggerSearchFromShortcut = (\n event: SearchShortcutEvent,\n onOpen: () => void,\n) => {\n if (handledShortcutEvents.has(event) || event.defaultPrevented) return false;\n\n const isModifierPressed = event.metaKey || event.ctrlKey;\n const isShortcutKey = event.key.toLowerCase() === \"k\";\n\n if (!isModifierPressed || !isShortcutKey) return false;\n\n handledShortcutEvents.add(event);\n event.preventDefault();\n onOpen();\n return true;\n};\n" }, { "path": "apps/www/app/docs/_components/docs-search.client.tsx", "content": "\"use client\";\n\nimport * as React from \"react\";\nimport Link from \"next/link\";\nimport { SearchIcon } from \"lucide-react\";\nimport { analytics } from \"@/lib/analytics\";\nimport { Button } from \"@/components/ui/button\";\nimport { Dialog, DialogContent, DialogTitle } from \"@/components/ui/dialog\";\nimport { Input } from \"@/components/ui/input\";\nimport { componentsRegistry } from \"@/lib/docs/component-registry\";\nimport { cn } from \"@/lib/ui/cn\";\nimport { BASE_DOCS_PAGES } from \"./docs-pages\";\nimport { triggerSearchFromShortcut } from \"./docs-search-shortcut\";\n\ntype SearchResult = {\n kind: \"page\" | \"component\";\n label: string;\n href: string;\n};\n\nconst SEARCH_RESULTS: SearchResult[] = [\n { kind: \"page\", label: \"Gallery\", href: \"/docs/gallery\" },\n ...BASE_DOCS_PAGES.map((page) => ({\n kind: \"page\" as const,\n label: page.label,\n href: page.path,\n })),\n ...componentsRegistry.map((component) => ({\n kind: \"component\" as const,\n label: component.label,\n href: component.path,\n })),\n];\n\nconst MAX_RESULTS = 10;\n\nexport function DocsSearch() {\n const [open, setOpen] = React.useState(false);\n const [query, setQuery] = React.useState(\"\");\n const lastTrackedSubmissionRef = React.useRef(null);\n\n const trimmedQuery = query.trim();\n\n const filteredResults = React.useMemo(() => {\n if (trimmedQuery.length === 0) return SEARCH_RESULTS.slice(0, MAX_RESULTS);\n\n const normalized = trimmedQuery.toLowerCase();\n return SEARCH_RESULTS.filter((result) =>\n result.label.toLowerCase().includes(normalized),\n ).slice(0, MAX_RESULTS);\n }, [trimmedQuery]);\n\n const trackSubmittedQuery = React.useCallback(() => {\n if (trimmedQuery.length === 0) return;\n\n const resultsCount = filteredResults.length;\n const signature = `${trimmedQuery.toLowerCase()}::${resultsCount}`;\n\n if (lastTrackedSubmissionRef.current === signature) return;\n\n analytics.search.querySubmitted(trimmedQuery, resultsCount);\n if (resultsCount === 0) {\n analytics.search.noResults(trimmedQuery);\n }\n lastTrackedSubmissionRef.current = signature;\n }, [filteredResults.length, trimmedQuery]);\n\n const openSearch = React.useCallback((source: \"header\" | \"keyboard\") => {\n analytics.search.opened(source);\n setOpen(true);\n }, []);\n\n const closeSearch = React.useCallback(() => {\n setOpen(false);\n setQuery(\"\");\n lastTrackedSubmissionRef.current = null;\n }, []);\n\n React.useEffect(() => {\n const onKeyDown = (event: KeyboardEvent) => {\n triggerSearchFromShortcut(event, () => openSearch(\"keyboard\"));\n };\n\n window.addEventListener(\"keydown\", onKeyDown);\n return () => window.removeEventListener(\"keydown\", onKeyDown);\n }, [openSearch]);\n\n return (\n <>\n openSearch(\"header\")}\n >\n \n Search\n \n \n\n {\n if (!nextOpen) {\n closeSearch();\n return;\n }\n setOpen(true);\n }}\n >\n \n Search Tool UI Docs\n {\n event.preventDefault();\n trackSubmittedQuery();\n }}\n >\n setQuery(event.target.value)}\n placeholder=\"Search pages and components...\"\n aria-label=\"Search pages and components\"\n className=\"h-10\"\n />\n \n\n
\n {filteredResults.length === 0 ? (\n
\n No results found\n
\n ) : (\n
    \n {filteredResults.map((result, index) => (\n
  • \n {\n trackSubmittedQuery();\n analytics.search.resultClicked(\n trimmedQuery,\n result.href,\n index + 1,\n );\n closeSearch();\n }}\n className={cn(\n \"hover:bg-muted flex items-center justify-between rounded-md px-3 py-2 transition-colors\",\n )}\n >\n {result.label}\n \n {result.kind}\n \n \n
    • \n ))}\n
\n )}\n
\n \n \n \n );\n}\n" }, { "path": "apps/www/app/docs/_components/docs-toc-context.tsx", "content": "\"use client\";\n\nimport {\n createContext,\n useCallback,\n useContext,\n useState,\n type ReactNode,\n} from \"react\";\nimport { useExtractHeadings, type Heading } from \"@/hooks/use-extract-headings\";\nimport { useHeadingsObserver } from \"@/hooks/use-headings-observer\";\n\ntype DocsTocContextValue = {\n scrollContainerRef: (node: HTMLElement | null) => void;\n scrollContainer: HTMLElement | null;\n headings: Heading[];\n activeId: string | null;\n};\n\nconst DocsTocContext = createContext(null);\n\nexport function useDocsToc() {\n const context = useContext(DocsTocContext);\n if (!context) {\n throw new Error(\"useDocsToc must be used within DocsTocProvider\");\n }\n return context;\n}\n\nexport function DocsTocProvider({ children }: { children: ReactNode }) {\n const [scrollContainer, setScrollContainer] = useState(\n null,\n );\n\n const scrollContainerRef = useCallback((node: HTMLElement | null) => {\n if (node) {\n setScrollContainer(node);\n }\n }, []);\n\n const headings = useExtractHeadings(scrollContainer);\n const activeId = useHeadingsObserver(headings, scrollContainer);\n\n return (\n \n {children}\n \n );\n}\n" }, { "path": "apps/www/app/docs/_components/docs-toc-wrapper.tsx", "content": "import { DocsToc } from \"./docs-toc\";\n\nexport function DocsTocWrapper() {\n return (\n
\n
\n \n
\n
\n );\n}\n" }, { "path": "apps/www/app/docs/_components/docs-toc.tsx", "content": "\"use client\";\n\nimport { useCallback, useEffect, useRef, useState } from \"react\";\nimport { cn } from \"@/lib/ui/cn\";\nimport { useDocsToc } from \"./docs-toc-context\";\nimport { useReducedMotion } from \"@/hooks/use-reduced-motion\";\nimport { useTocKeyboardNav } from \"@/hooks/use-toc-keyboard-nav\";\nimport { analytics } from \"@/lib/analytics\";\n\nexport function DocsToc() {\n const { scrollContainer, headings, activeId } = useDocsToc();\n const reducedMotion = useReducedMotion();\n const linkRefs = useRef<(HTMLAnchorElement | null)[]>([]);\n const previousIndicatorTopRef = useRef(null);\n const [indicatorTop, setIndicatorTop] = useState(null);\n\n const scrollToHeading = useCallback(\n (id: string) => {\n const element = document.getElementById(id);\n const container = scrollContainer;\n if (!element || !container) return;\n\n const stickyHeader = container.querySelector('[role=\"tablist\"]');\n const offset = stickyHeader\n ? stickyHeader.getBoundingClientRect().height + 20\n : 80;\n\n const targetScroll = element.offsetTop - offset;\n\n if (reducedMotion) {\n container.scrollTop = targetScroll;\n } else {\n container.scrollTo({ top: targetScroll, behavior: \"smooth\" });\n }\n },\n [scrollContainer, reducedMotion],\n );\n\n const { handleKeyDown, setLinkRef: setKeyboardLinkRef } = useTocKeyboardNav(\n headings,\n scrollToHeading,\n );\n\n const handleClick = (\n e: React.MouseEvent,\n id: string,\n title: string,\n ) => {\n e.preventDefault();\n analytics.docs.tocLinkClicked(title, 2);\n scrollToHeading(id);\n };\n\n useEffect(() => {\n if (typeof window === \"undefined\" || headings.length === 0) return;\n\n const hash = window.location.hash.slice(1);\n if (hash && headings.some((h) => h.id === hash)) {\n setTimeout(() => scrollToHeading(hash), 200);\n }\n }, [headings, scrollToHeading]);\n\n useEffect(() => {\n linkRefs.current = linkRefs.current.slice(0, headings.length);\n }, [headings]);\n\n // Update indicator position when activeId changes\n useEffect(() => {\n const activeIndex = headings.findIndex((h) => h.id === activeId);\n if (activeIndex >= 0 && linkRefs.current[activeIndex]) {\n const activeLink = linkRefs.current[activeIndex];\n if (activeLink) {\n const linkRect = activeLink.getBoundingClientRect();\n const navRect = activeLink.parentElement?.getBoundingClientRect();\n if (navRect) {\n const relativeTop = linkRect.top - navRect.top + 8;\n setIndicatorTop(relativeTop);\n return;\n }\n }\n }\n\n setIndicatorTop(null);\n }, [activeId, headings]);\n\n useEffect(() => {\n previousIndicatorTopRef.current = indicatorTop;\n }, [indicatorTop]);\n\n if (headings.length === 0) {\n return null;\n }\n\n const activeIndex = headings.findIndex((h) => h.id === activeId);\n const shouldAnimateIndicator =\n !reducedMotion &&\n previousIndicatorTopRef.current !== null &&\n indicatorTop !== null;\n\n const setLinkRef = (index: number) => (el: HTMLAnchorElement | null) => {\n linkRefs.current[index] = el;\n setKeyboardLinkRef(index)(el);\n };\n\n return (\n \n

\n On This Page\n

\n {activeIndex >= 0 && indicatorTop !== null && (\n \n )}\n {headings.map((heading, index) => {\n const isActive = heading.id === activeId;\n return (\n handleClick(e, heading.id, heading.text)}\n className={cn(\n \"relative block py-1 text-sm transition-colors\",\n \"hover:text-foreground focus-visible:outline-none focus-visible:text-foreground\",\n isActive && \"text-foreground font-medium\",\n !isActive && \"text-muted-foreground\",\n )}\n aria-current={isActive ? \"true\" : undefined}\n title={heading.text}\n >\n {heading.text}\n \n );\n })}\n \n );\n}\n" }, { "path": "apps/www/app/docs/_components/gallery-analytics.client.tsx", "content": "\"use client\";\n\nimport { useEffect, useRef } from \"react\";\nimport { analytics } from \"@/lib/analytics\";\n\nexport function GalleryPageAnalytics() {\n useEffect(() => {\n analytics.gallery.pageViewed();\n }, []);\n\n return null;\n}\n\ninterface GalleryPreviewImpressionProps {\n componentId: string;\n}\n\nexport function GalleryPreviewImpression({\n componentId,\n}: GalleryPreviewImpressionProps) {\n const trackedRef = useRef(false);\n const markerRef = useRef(null);\n\n useEffect(() => {\n if (trackedRef.current) {\n return;\n }\n\n const marker = markerRef.current;\n if (!marker) {\n return;\n }\n\n if (typeof IntersectionObserver !== \"function\") {\n trackedRef.current = true;\n analytics.gallery.componentPreviewed(componentId);\n return;\n }\n\n const observer = new IntersectionObserver(\n (entries) => {\n for (const entry of entries) {\n if (!entry.isIntersecting || trackedRef.current) continue;\n\n trackedRef.current = true;\n analytics.gallery.componentPreviewed(componentId);\n observer.disconnect();\n break;\n }\n },\n { threshold: 0.2 },\n );\n\n observer.observe(marker);\n\n return () => observer.disconnect();\n }, [componentId]);\n\n return ;\n}\n" }, { "path": "apps/www/app/docs/_components/gallery-card-header.tsx", "content": "\"use client\";\n\nimport Link from \"next/link\";\nimport { Button } from \"@/components/ui/button\";\nimport {\n Sheet,\n SheetContent,\n SheetDescription,\n SheetHeader,\n SheetTitle,\n SheetTrigger,\n} from \"@/components/ui/sheet\";\nimport { componentsRegistry } from \"@/lib/docs/component-registry\";\nimport { getGalleryUsageCode } from \"@/lib/docs/gallery-usage-code\";\nimport type { GalleryComponentDocId } from \"@/lib/docs/gallery-component-docs\";\nimport { analytics } from \"@/lib/analytics\";\nimport { cn } from \"@/lib/ui/cn\";\nimport { TrackedDynamicCodeBlock } from \"./tracked-dynamic-codeblock\";\nimport { InstallCommandBlock } from \"./install-command-block\";\n\nconst registryById = new Map(componentsRegistry.map((c) => [c.id, c]));\n\ninterface GalleryCardHeaderProps {\n componentId: GalleryComponentDocId;\n className?: string;\n hideDescription?: boolean;\n}\n\nexport function GalleryCardHeader({\n componentId,\n className,\n hideDescription = false,\n}: GalleryCardHeaderProps) {\n const meta = registryById.get(componentId);\n const name = meta?.label ?? componentId;\n const description = meta?.description;\n const docsHref = (meta?.path ?? `/docs/${componentId}`) as `/docs/${string}`;\n const usageCode = getGalleryUsageCode(componentId);\n\n return (\n \n
\n {\n analytics.gallery.componentClicked(componentId);\n analytics.docs.navigationClicked(name, docsHref);\n }}\n >\n

{name}

\n \n
\n \n \n \n Install & use\n \n \n \n \n Code\n \n Copy the command to install, then use the example in your app.\n \n \n
\n
\n

\n Install\n

\n \n
\n {usageCode && (\n
\n

\n Example\n

\n
\n \n
\n
\n )}\n
\n \n \n
\n
\n\n {!hideDescription && description && (\n

{description}

\n )}\n \n );\n}\n" }, { "path": "apps/www/app/docs/_components/gallery-docs-link.tsx", "content": "\"use client\";\n\nimport Link from \"next/link\";\nimport { ArrowRight } from \"lucide-react\";\nimport { analytics } from \"@/lib/analytics\";\nimport type { GalleryComponentDocId } from \"@/lib/docs/gallery-component-docs\";\nimport { cn } from \"@/lib/ui/cn\";\n\ninterface GalleryDocsLinkProps {\n componentId: GalleryComponentDocId;\n label: string;\n href: `/docs/${string}`;\n className?: string;\n}\n\nexport function GalleryDocsLink({\n componentId,\n label,\n href,\n className,\n}: GalleryDocsLinkProps) {\n const handleClick = () => {\n analytics.gallery.componentClicked(componentId);\n analytics.docs.navigationClicked(label, href);\n };\n\n return (\n \n {label}\n \n •\n \n \n \n View Docs\n \n \n \n \n );\n}\n" }, { "path": "apps/www/app/docs/_components/header-preview-tabs.tsx", "content": "\"use client\";\n\nimport { useCallback, useEffect, useState } from \"react\";\nimport { Tab, Tabs } from \"fumadocs-ui/components/tabs\";\nimport { analytics } from \"@/lib/analytics\";\nimport { getImportLine } from \"@/lib/docs/gallery-usage-code\";\nimport { TrackedDynamicCodeBlock } from \"./tracked-dynamic-codeblock\";\nimport {\n type ComponentId,\n getPreviewConfig,\n type PreviewState,\n} from \"@/lib/docs/preview-config\";\n\ninterface HeaderPreviewTabsProps {\n componentId: ComponentId;\n}\n\nconst EMPTY_STATE: PreviewState = {};\n\nexport function HeaderPreviewTabs({ componentId }: HeaderPreviewTabsProps) {\n const config = getPreviewConfig(componentId);\n const [state, setState] = useState(EMPTY_STATE);\n const [isMounted, setIsMounted] = useState(false);\n\n useEffect(() => {\n setIsMounted(true);\n }, []);\n\n const handleSetState = useCallback((partialState: Partial) => {\n setState((prev) => ({ ...prev, ...partialState }));\n }, []);\n\n const handleTabClickCapture = useCallback(\n (event: React.MouseEvent) => {\n const target = event.target as HTMLElement;\n const trigger = target.closest('[role=\"tab\"]');\n if (!trigger) return;\n if (trigger.getAttribute(\"aria-selected\") === \"true\") return;\n\n const rawLabel = trigger.textContent?.trim().toLowerCase();\n if (rawLabel === \"preview\" || rawLabel === \"code\") {\n analytics.component.tabSwitched(componentId, `header_${rawLabel}`);\n }\n },\n [componentId],\n );\n\n if (!config || !isMounted) {\n return null;\n }\n\n const preset = config.presets[config.defaultPreset];\n const preview = config.renderComponent({\n data: preset.data,\n presetName: config.defaultPreset,\n state,\n setState: handleSetState,\n });\n const wrappedPreview = config.wrapper ? (\n {preview}\n ) : (\n preview\n );\n const body = preset.generateExampleCode(preset.data);\n const code = `${getImportLine(componentId)}\\n\\n${body}`;\n\n return (\n
\n \n \n
\n {wrappedPreview}\n
\n \n \n \n \n \n
\n );\n}\n" }, { "path": "apps/www/app/docs/_components/install-command-block.tsx", "content": "\"use client\";\n\nimport type { MouseEventHandler } from \"react\";\nimport { Check, Copy as CopyIcon } from \"lucide-react\";\nimport { useCopyButton } from \"fumadocs-ui/utils/use-copy-button\";\nimport { Tabs, Tab } from \"fumadocs-ui/components/tabs\";\nimport { Button } from \"@/components/ui/button\";\nimport { analytics } from \"@/lib/analytics\";\nimport {\n detectInstallSnippetType,\n getDocsCodeCopySource,\n} from \"@/lib/docs/install-snippet-analytics\";\nimport { componentsRegistry } from \"@/lib/docs/component-registry\";\nimport { cn } from \"@/lib/ui/cn\";\n\nconst registryById = new Map(componentsRegistry.map((c) => [c.id, c]));\n\ninterface InstallCommandBlockProps {\n componentId: string;\n className?: string;\n /** Compact single-line style (e.g. docs header) vs full block (e.g. gallery sheet) */\n variant?: \"compact\" | \"block\";\n /** Override tool-agent prompt when component not in registry (e.g. quick-start) */\n toolAgentPrompt?: string;\n}\n\nfunction CopyableCommand({\n command,\n location,\n variant,\n}: {\n command: string;\n location: \"docs_code_block\" | \"docs_header\";\n variant: \"compact\" | \"block\";\n}) {\n const installSnippetType = detectInstallSnippetType(command);\n const copySource = getDocsCodeCopySource(installSnippetType);\n\n const [checked, copyCommand] = useCopyButton(async () => {\n await navigator.clipboard.writeText(command);\n });\n\n const onCopy: MouseEventHandler = (event) => {\n analytics.code.blockCopied(\"bash\", copySource);\n if (installSnippetType) {\n analytics.docs.installSnippetCopied(installSnippetType, location);\n }\n copyCommand(event);\n };\n\n const isCompact = variant === \"compact\";\n\n return (\n \n \n {command}\n \n \n {checked ? (\n \n ) : (\n \n )}\n \n \n );\n}\n\nexport function InstallCommandBlock({\n componentId,\n className,\n variant = \"compact\",\n toolAgentPrompt: promptOverride,\n}: InstallCommandBlockProps) {\n const meta = registryById.get(componentId);\n const toolAgentPrompt =\n promptOverride ??\n meta?.toolAgentPrompt ??\n `integrate the ${componentId} component`;\n const toolAgentCommand = `npx tool-agent \"${toolAgentPrompt}\"`;\n const shadcnCommand = `npx shadcn@latest add @tool-ui/${componentId}`;\n\n return (\n
\n \n \n \n \n \n \n \n \n
\n );\n}\n" }, { "path": "apps/www/app/docs/_components/install-command-line.tsx", "content": "\"use client\";\n\nimport { InstallCommandBlock } from \"./install-command-block\";\n\ninterface InstallCommandLineProps {\n componentId: string;\n className?: string;\n}\n\nexport function InstallCommandLine({\n componentId,\n className,\n}: InstallCommandLineProps) {\n return (\n \n );\n}\n" }, { "path": "apps/www/app/docs/_components/interactive-option-demo.tsx", "content": "\"use client\";\n\nimport { useCallback, useState } from \"react\";\nimport { RotateCcw } from \"lucide-react\";\nimport { MockThread, MockMessage } from \"./mock-thread\";\nimport { OptionList } from \"@/components/tool-ui/option-list\";\nimport { cn, Button } from \"@/components/tool-ui/option-list/_adapter\";\n\nconst OPTIONS = [\n {\n id: \"postgres\",\n label: \"PostgreSQL\",\n description: \"Best for relational data with complex queries\",\n },\n {\n id: \"sqlite\",\n label: \"SQLite\",\n description: \"Simple, embedded, great for single-server apps\",\n },\n {\n id: \"dynamo\",\n label: \"DynamoDB\",\n description: \"Fully managed NoSQL, scales automatically\",\n },\n];\n\nconst FOLLOW_UP: Record = {\n postgres:\n \"Good choice. PostgreSQL gives you strong typing, JSON support, and a mature ecosystem. Want me to set up the schema?\",\n sqlite:\n \"Nice pick. SQLite keeps things simple — no server to manage, and it's fast for read-heavy workloads. Want me to set up the database file?\",\n dynamo:\n \"Solid choice. DynamoDB handles scale automatically with single-digit-millisecond reads. Want me to set up the table definitions?\",\n};\n\nexport function InteractiveOptionDemo() {\n const [choice, setChoice] = useState(null);\n\n const handleAction = useCallback(\n (actionId: string, selection: string | string[] | null) => {\n if (actionId === \"confirm\" && typeof selection === \"string\") {\n setChoice(selection);\n }\n },\n [],\n );\n\n const handleReset = useCallback(() => {\n setChoice(null);\n }, []);\n\n return (\n
\n \n \n Help me pick a database for the new project\n \n \n \n {\"Based on your requirements, here are some options:\"}\n \n
\n \n
\n \n {choice && (\n \n \n {FOLLOW_UP[choice] ?? FOLLOW_UP.postgres}\n \n \n )}\n \n {choice && (\n \n \n \n Try again\n \n
\n )}\n \n );\n}\n" }, { "path": "apps/www/app/docs/_components/mdx-to-markdown.ts", "content": "import { readFileSync } from \"fs\";\nimport { join } from \"path\";\n\n/**\n * Reads an MDX file and returns it with minimal cleanup.\n * Removes the DocsHeader component and its import since that's just UI chrome.\n */\nexport function getMdxAsMarkdown(mdxPath: string): string {\n const fullPath = join(process.cwd(), mdxPath);\n const rawContent = readFileSync(fullPath, \"utf-8\");\n\n let result = rawContent;\n\n // Remove DocsHeader import\n result = result.replace(\n /^import\\s*\\{\\s*DocsHeader\\s*\\}\\s*from\\s*[\"'][^\"']+[\"'];?\\n?/gm,\n \"\",\n );\n\n // Remove DocsHeader component usage\n result = result.replace(/]*\\/>\\n?/g, \"\");\n\n // Trim leading/trailing whitespace\n result = result.trim();\n\n return result;\n}\n" }, { "path": "apps/www/app/docs/_components/mock-thread.tsx", "content": "\"use client\";\n\nimport * as React from \"react\";\nimport { cn } from \"@/lib/ui/cn\";\n\ninterface MockMessageProps {\n role: \"user\" | \"assistant\";\n children: React.ReactNode;\n}\n\nexport function MockMessage({ role, children }: MockMessageProps) {\n if (role === \"user\") {\n return (\n
\n
\n {children}\n
\n
\n );\n }\n\n return (\n
\n {children}\n
\n );\n}\n\ninterface MockThreadProps {\n children: React.ReactNode;\n className?: string;\n caption?: string;\n}\n\nexport function MockThread({ children, className, caption }: MockThreadProps) {\n return (\n \n
\n {/* Title bar */}\n
\n \n Chat\n \n
\n {/* Messages */}\n
[data-role=user]+[data-role=assistant]]:mt-2 [&>[data-role=assistant]+[data-role=user]]:mt-2\">\n {children}\n
\n
\n {caption && (\n
\n {caption}\n
\n )}\n \n );\n}\n" }, { "path": "apps/www/app/docs/_components/preset-example.tsx", "content": "\"use client\";\n\nimport { TrackedDynamicCodeBlock } from \"./tracked-dynamic-codeblock\";\nimport { Tabs, Tab } from \"fumadocs-ui/components/tabs\";\nimport { Chart } from \"@/components/tool-ui/chart\";\nimport { chartPresets, ChartPresetName } from \"@/lib/presets/chart\";\nimport { OptionList } from \"@/components/tool-ui/option-list\";\nimport { CodeBlock } from \"@/components/tool-ui/code-block\";\nimport { Terminal } from \"@/components/tool-ui/terminal\";\nimport {\n optionListPresets,\n OptionListPresetName,\n} from \"@/lib/presets/option-list\";\nimport {\n codeBlockPresets,\n CodeBlockPresetName,\n} from \"@/lib/presets/code-block\";\nimport { terminalPresets, TerminalPresetName } from \"@/lib/presets/terminal\";\nimport { Plan } from \"@/components/tool-ui/plan\";\nimport { planPresets, PlanPresetName } from \"@/lib/presets/plan\";\nimport { ItemCarousel } from \"@/components/tool-ui/item-carousel\";\nimport {\n itemCarouselPresets,\n ItemCarouselPresetName,\n} from \"@/lib/presets/item-carousel\";\nimport { ApprovalCard } from \"@/components/tool-ui/approval-card\";\nimport {\n approvalCardPresets,\n ApprovalCardPresetName,\n} from \"@/lib/presets/approval-card\";\nimport { QuestionFlow } from \"@/components/tool-ui/question-flow\";\nimport {\n questionFlowPresets,\n QuestionFlowPresetName,\n} from \"@/lib/presets/question-flow\";\n\nfunction generateOptionListCode(preset: OptionListPresetName): string {\n const list = optionListPresets[preset].data;\n const props: string[] = [];\n\n props.push(\n ` options={${JSON.stringify(list.options, null, 4).replace(/\\n/g, \"\\n \")}}`,\n );\n\n if (list.selectionMode) {\n props.push(` selectionMode=\"${list.selectionMode}\"`);\n }\n\n if (list.minSelections && list.minSelections !== 1) {\n props.push(` minSelections={${list.minSelections}}`);\n }\n\n if (list.maxSelections) {\n props.push(` maxSelections={${list.maxSelections}}`);\n }\n\n if (list.choice) {\n const choiceValue =\n typeof list.choice === \"string\"\n ? `\"${list.choice}\"`\n : JSON.stringify(list.choice);\n props.push(` choice={${choiceValue}}`);\n }\n\n if (list.actions) {\n const hasActions = Array.isArray(list.actions)\n ? list.actions.length > 0\n : list.actions.items.length > 0;\n\n if (hasActions) {\n props.push(\n ` actions={${JSON.stringify(list.actions, null, 4).replace(/\\n/g, \"\\n \")}}`,\n );\n }\n }\n\n if (!list.choice) {\n props.push(\n ` onAction={(actionId, selection) => {\\n if (actionId === \"confirm\") {\\n console.log(selection);\\n }\\n }}`,\n );\n }\n\n return ``;\n}\n\nfunction generateCodeBlockCode(preset: CodeBlockPresetName): string {\n const block = codeBlockPresets[preset].data;\n const props: string[] = [];\n\n props.push(` id=\"${block.id}\"`);\n props.push(` code={\\`${block.code.replace(/`/g, \"\\\\`\")}\\`}`);\n props.push(` language=\"${block.language}\"`);\n props.push(` lineNumbers=\"${block.lineNumbers}\"`);\n\n if (block.filename) {\n props.push(` filename=\"${block.filename}\"`);\n }\n\n if (block.highlightLines && block.highlightLines.length > 0) {\n props.push(` highlightLines={[${block.highlightLines.join(\", \")}]}`);\n }\n\n if (block.maxCollapsedLines) {\n props.push(` maxCollapsedLines={${block.maxCollapsedLines}}`);\n }\n\n return ``;\n}\n\nfunction generateTerminalCode(preset: TerminalPresetName): string {\n const term = terminalPresets[preset].data;\n const props: string[] = [];\n\n props.push(` command=\"${term.command.replace(/\"/g, '\\\\\"')}\"`);\n\n if (term.stdout) {\n props.push(` stdout={\\`${term.stdout.replace(/`/g, \"\\\\`\")}\\`}`);\n }\n\n if (term.stderr) {\n props.push(` stderr={\\`${term.stderr.replace(/`/g, \"\\\\`\")}\\`}`);\n }\n\n props.push(` exitCode={${term.exitCode}}`);\n\n if (term.durationMs !== undefined) {\n props.push(` durationMs={${term.durationMs}}`);\n }\n\n if (term.cwd) {\n props.push(` cwd=\"${term.cwd}\"`);\n }\n\n if (term.truncated) {\n props.push(` truncated={${term.truncated}}`);\n }\n\n if (term.maxCollapsedLines) {\n props.push(` maxCollapsedLines={${term.maxCollapsedLines}}`);\n }\n\n return ``;\n}\n\ninterface OptionListPresetExampleProps {\n preset: OptionListPresetName;\n}\n\nexport function OptionListPresetExample({\n preset,\n}: OptionListPresetExampleProps) {\n const data = optionListPresets[preset].data;\n const code = generateOptionListCode(preset);\n\n return (\n \n \n
\n \n
\n \n \n \n \n \n );\n}\n\nfunction generateChartCode(preset: ChartPresetName): string {\n const config = chartPresets[preset].data;\n const props: string[] = [];\n\n props.push(` id=\"chart-example\"`);\n props.push(` type=\"${config.type}\"`);\n\n if (config.title) {\n props.push(` title=\"${config.title}\"`);\n }\n\n if (config.description) {\n props.push(` description=\"${config.description}\"`);\n }\n\n props.push(\n ` data={${JSON.stringify(config.data, null, 4).replace(/\\n/g, \"\\n \")}}`,\n );\n props.push(` xKey=\"${config.xKey}\"`);\n props.push(\n ` series={${JSON.stringify(config.series, null, 4).replace(/\\n/g, \"\\n \")}}`,\n );\n\n if (config.showLegend) {\n props.push(` showLegend`);\n }\n\n if (config.showGrid) {\n props.push(` showGrid`);\n }\n\n return ``;\n}\n\ninterface ChartPresetExampleProps {\n preset: ChartPresetName;\n}\n\nexport function ChartPresetExample({ preset }: ChartPresetExampleProps) {\n const config = chartPresets[preset].data;\n const code = generateChartCode(preset);\n\n return (\n \n \n
\n \n
\n \n \n \n \n \n );\n}\n\ninterface CodeBlockPresetExampleProps {\n preset: CodeBlockPresetName;\n}\n\nexport function CodeBlockPresetExample({\n preset,\n}: CodeBlockPresetExampleProps) {\n const data = codeBlockPresets[preset].data;\n const code = generateCodeBlockCode(preset);\n\n return (\n \n \n
\n \n
\n \n \n \n \n \n );\n}\n\ninterface TerminalPresetExampleProps {\n preset: TerminalPresetName;\n}\n\nexport function TerminalPresetExample({ preset }: TerminalPresetExampleProps) {\n const data = terminalPresets[preset].data;\n const code = generateTerminalCode(preset);\n\n return (\n \n \n
\n \n
\n \n \n \n \n \n );\n}\n\nfunction generatePlanCode(preset: PlanPresetName): string {\n const plan = planPresets[preset].data;\n const props: string[] = [];\n\n props.push(` id=\"${plan.id}\"`);\n props.push(` title=\"${plan.title}\"`);\n\n if (plan.description) {\n props.push(` description=\"${plan.description}\"`);\n }\n\n props.push(\n ` todos={${JSON.stringify(plan.todos, null, 4).replace(/\\n/g, \"\\n \")}}`,\n );\n\n if (plan.maxVisibleTodos) {\n props.push(` maxVisibleTodos={${plan.maxVisibleTodos}}`);\n }\n\n return ``;\n}\n\ninterface PlanPresetExampleProps {\n preset: PlanPresetName;\n}\n\nexport function PlanPresetExample({ preset }: PlanPresetExampleProps) {\n const data = planPresets[preset].data;\n const code = generatePlanCode(preset);\n\n return (\n \n \n
\n \n
\n \n \n \n \n \n );\n}\n\nfunction generateItemCarouselCode(preset: ItemCarouselPresetName): string {\n const list = itemCarouselPresets[preset].data;\n const props: string[] = [];\n\n props.push(` id=\"${list.id}\"`);\n props.push(\n ` items={${JSON.stringify(list.items, null, 4).replace(/\\n/g, \"\\n \")}}`,\n );\n props.push(` onItemClick={(itemId) => console.log(\"Clicked:\", itemId)}`);\n props.push(\n ` onItemAction={(itemId, actionId) => console.log(\"Action:\", itemId, actionId)}`,\n );\n\n return ``;\n}\n\ninterface ItemCarouselPresetExampleProps {\n preset: ItemCarouselPresetName;\n}\n\nexport function ItemCarouselPresetExample({\n preset,\n}: ItemCarouselPresetExampleProps) {\n const data = itemCarouselPresets[preset].data;\n const code = generateItemCarouselCode(preset);\n\n return (\n \n \n
\n \n
\n \n \n \n \n \n );\n}\n\nfunction generateApprovalCardCode(preset: ApprovalCardPresetName): string {\n const data = approvalCardPresets[preset].data;\n const props: string[] = [];\n\n props.push(` id=\"${data.id}\"`);\n props.push(` title=\"${data.title}\"`);\n\n if (data.description) {\n props.push(` description=\"${data.description}\"`);\n }\n\n if (data.icon) {\n props.push(` icon=\"${data.icon}\"`);\n }\n\n if (data.metadata && data.metadata.length > 0) {\n props.push(\n ` metadata={${JSON.stringify(data.metadata, null, 4).replace(/\\n/g, \"\\n \")}}`,\n );\n }\n\n if (data.variant) {\n props.push(` variant=\"${data.variant}\"`);\n }\n\n if (data.confirmLabel) {\n props.push(` confirmLabel=\"${data.confirmLabel}\"`);\n }\n\n if (data.cancelLabel) {\n props.push(` cancelLabel=\"${data.cancelLabel}\"`);\n }\n\n if (data.choice) {\n props.push(` choice=\"${data.choice}\"`);\n }\n\n return ``;\n}\n\ninterface ApprovalCardPresetExampleProps {\n preset: ApprovalCardPresetName;\n}\n\nexport function ApprovalCardPresetExample({\n preset,\n}: ApprovalCardPresetExampleProps) {\n const data = approvalCardPresets[preset].data;\n const code = generateApprovalCardCode(preset);\n\n return (\n \n \n
\n \n
\n \n \n \n \n \n );\n}\n\ninterface QuestionFlowPresetExampleProps {\n preset: QuestionFlowPresetName;\n}\n\nexport function QuestionFlowPresetExample({\n preset,\n}: QuestionFlowPresetExampleProps) {\n const presetData = questionFlowPresets[preset];\n const code = presetData.generateExampleCode(presetData.data);\n\n return (\n \n \n
\n \n
\n \n \n \n \n \n );\n}\n" }, { "path": "apps/www/app/docs/_components/preset-selector.tsx", "content": "\"use client\";\n\nimport {\n Item,\n ItemContent,\n ItemDescription,\n ItemGroup,\n ItemTitle,\n} from \"@/components/ui/item\";\nimport { analytics } from \"@/lib/analytics\";\nimport { approvalCardPresets } from \"@/lib/presets/approval-card\";\nimport { chartPresets } from \"@/lib/presets/chart\";\nimport { citationPresets } from \"@/lib/presets/citation\";\nimport { codeBlockPresets } from \"@/lib/presets/code-block\";\nimport { codeDiffPresets } from \"@/lib/presets/code-diff\";\nimport { dataTablePresets } from \"@/lib/presets/data-table\";\nimport { geoMapPresets } from \"@/lib/presets/geo-map\";\nimport { imagePresets } from \"@/lib/presets/image\";\nimport { imageGalleryPresets } from \"@/lib/presets/image-gallery\";\nimport { videoPresets } from \"@/lib/presets/video\";\nimport { audioPresets } from \"@/lib/presets/audio\";\nimport { linkPreviewPresets } from \"@/lib/presets/link-preview\";\nimport { messageDraftPresets } from \"@/lib/presets/message-draft\";\nimport { itemCarouselPresets } from \"@/lib/presets/item-carousel\";\nimport { optionListPresets } from \"@/lib/presets/option-list\";\nimport { orderSummaryPresets } from \"@/lib/presets/order-summary\";\nimport { parameterSliderPresets } from \"@/lib/presets/parameter-slider\";\nimport { planPresets } from \"@/lib/presets/plan\";\nimport { preferencesPanelPresets } from \"@/lib/presets/preferences-panel\";\nimport { progressTrackerPresets } from \"@/lib/presets/progress-tracker\";\nimport { questionFlowPresets } from \"@/lib/presets/question-flow\";\nimport { statsDisplayPresets } from \"@/lib/presets/stats-display\";\nimport { terminalPresets } from \"@/lib/presets/terminal\";\nimport { weatherWidgetPresets } from \"@/lib/presets/weather-widget\";\nimport type { Preset } from \"@/lib/presets/types\";\nimport { cn } from \"@/lib/ui/cn\";\n\ntype PresetMap = Record>;\n\nconst PRESET_REGISTRY: Record = {\n \"approval-card\": approvalCardPresets,\n chart: chartPresets,\n citation: citationPresets,\n \"code-block\": codeBlockPresets,\n \"code-diff\": codeDiffPresets,\n \"data-table\": dataTablePresets,\n \"geo-map\": geoMapPresets,\n image: imagePresets,\n \"image-gallery\": imageGalleryPresets,\n video: videoPresets,\n audio: audioPresets,\n \"link-preview\": linkPreviewPresets,\n \"message-draft\": messageDraftPresets,\n \"item-carousel\": itemCarouselPresets,\n \"option-list\": optionListPresets,\n \"order-summary\": orderSummaryPresets,\n \"parameter-slider\": parameterSliderPresets,\n plan: planPresets,\n \"preferences-panel\": preferencesPanelPresets,\n \"progress-tracker\": progressTrackerPresets,\n \"question-flow\": questionFlowPresets,\n \"stats-display\": statsDisplayPresets,\n terminal: terminalPresets,\n \"weather-widget\": weatherWidgetPresets,\n};\n\nconst DEFAULT_COMPONENT = \"chart\";\n\nfunction getPresets(componentId: string): PresetMap {\n return PRESET_REGISTRY[componentId] ?? PRESET_REGISTRY[DEFAULT_COMPONENT];\n}\n\nfunction formatPresetName(preset: string): string {\n return preset.replaceAll(\"-\", \" \").replaceAll(\"_\", \" \");\n}\n\ninterface PresetSelectorProps {\n componentId: string;\n currentPreset: string;\n onSelectPreset: (preset: string) => void;\n}\n\nexport function PresetSelector({\n componentId,\n currentPreset,\n onSelectPreset,\n}: PresetSelectorProps) {\n const presets = getPresets(componentId);\n const presetNames = Object.keys(presets);\n\n const handleSelect = (preset: string) => {\n analytics.component.presetSelected(componentId, preset);\n onSelectPreset(preset);\n };\n\n return (\n \n {presetNames.map((name) => (\n \n ))}\n \n );\n}\n\ninterface PresetItemProps {\n preset: string;\n description: string;\n isSelected: boolean;\n onSelect: (preset: string) => void;\n}\n\nfunction PresetItem({\n preset,\n description,\n isSelected,\n onSelect,\n}: PresetItemProps) {\n return (\n onSelect(preset)}\n >\n \n
\n
\n \n \n {formatPresetName(preset)}\n \n \n \n {description}\n \n
\n
\n \n \n \n );\n}\n\ninterface SelectionIndicatorProps {\n isSelected: boolean;\n}\n\nfunction SelectionIndicator({ isSelected }: SelectionIndicatorProps) {\n return (\n \n );\n}\n" }, { "path": "apps/www/app/docs/_components/tracked-dynamic-codeblock.tsx", "content": "\"use client\";\n\nimport {\n Children,\n cloneElement,\n isValidElement,\n useCallback,\n type ReactElement,\n type ReactNode,\n} from \"react\";\nimport {\n DynamicCodeBlock,\n type DynamicCodeblockProps,\n} from \"fumadocs-ui/components/dynamic-codeblock\";\nimport { analytics } from \"@/lib/analytics\";\nimport {\n detectInstallSnippetType,\n getDocsCodeCopySource,\n} from \"@/lib/docs/install-snippet-analytics\";\n\ntype InstallSnippetType = ReturnType;\n\ntype TrackedDynamicCodeBlockProps = DynamicCodeblockProps & {\n copyButtonLabel?: string;\n};\n\ntype CopyButtonElementProps = {\n \"aria-label\"?: string;\n children?: ReactNode;\n containerRef?: unknown;\n \"data-checked\"?: unknown;\n title?: string;\n};\n\nfunction resolveSnippetPreview(code: string): string {\n const firstLine = code\n .split(/\\r?\\n/)\n .map((line) => line.trim())\n .find((line) => line.length > 0);\n if (!firstLine) {\n return \"code snippet\";\n }\n\n const normalized = firstLine.replace(/\\s+/g, \" \");\n return normalized.length > 60 ? `${normalized.slice(0, 57)}...` : normalized;\n}\n\nfunction resolveInstallCopyLabel(type: InstallSnippetType): string | null {\n if (type === \"registry\") {\n return \"registry install command\";\n }\n\n if (type === \"skills\") {\n return \"skills install command\";\n }\n\n if (type === \"package_manager\") {\n return \"package manager install command\";\n }\n\n return null;\n}\n\nfunction resolveCopyContextLabel({\n code,\n lang,\n installSnippetType,\n copyButtonLabel,\n}: {\n code: string;\n lang: string;\n installSnippetType: InstallSnippetType;\n copyButtonLabel?: string;\n}): string {\n if (copyButtonLabel && copyButtonLabel.trim()) {\n return copyButtonLabel.trim();\n }\n\n const installLabel = resolveInstallCopyLabel(installSnippetType);\n if (installLabel) {\n return installLabel;\n }\n\n const language = lang.trim().length > 0 ? lang.toUpperCase() : \"CODE\";\n return `${language} snippet: ${resolveSnippetPreview(code)}`;\n}\n\nfunction relabelCopyButtons(\n children: ReactNode,\n contextLabel: string,\n): ReactNode {\n return Children.map(children, (child) => {\n if (!isValidElement(child)) {\n return child;\n }\n\n const element = child as ReactElement;\n const currentAriaLabel = element.props[\"aria-label\"];\n const nestedChildren = element.props.children;\n const relabeledChildren = nestedChildren\n ? relabelCopyButtons(nestedChildren, contextLabel)\n : nestedChildren;\n const isFumadocsCopyButton =\n typeof element.type === \"string\" &&\n element.type === \"button\" &&\n (currentAriaLabel === \"Copy Text\" || currentAriaLabel === \"Copied Text\");\n const isFumadocsCopyButtonComponent =\n typeof element.type !== \"string\" && \"containerRef\" in element.props;\n\n if (isFumadocsCopyButton) {\n const isCopied = Boolean(element.props[\"data-checked\"]);\n const action = isCopied ? \"Copied\" : \"Copy\";\n const ariaLabel = `${action} ${contextLabel}`;\n\n return cloneElement(\n element,\n {\n \"aria-label\": ariaLabel,\n title: ariaLabel,\n },\n relabeledChildren,\n );\n }\n\n if (isFumadocsCopyButtonComponent) {\n const ariaLabel = `Copy ${contextLabel}`;\n return cloneElement(element, {\n \"aria-label\": ariaLabel,\n title: ariaLabel,\n });\n }\n\n if (relabeledChildren !== nestedChildren) {\n return cloneElement(element, undefined, relabeledChildren);\n }\n\n return child;\n });\n}\n\nexport function TrackedDynamicCodeBlock({\n lang,\n code,\n codeblock,\n copyButtonLabel,\n ...props\n}: TrackedDynamicCodeBlockProps) {\n const installSnippetType = detectInstallSnippetType(code);\n const source = getDocsCodeCopySource(installSnippetType);\n const copyContextLabel = resolveCopyContextLabel({\n code,\n lang,\n installSnippetType,\n copyButtonLabel,\n });\n\n const Actions = useCallback(\n ({ className, children }: { className?: string; children?: ReactNode }) => (\n {\n const target = event.target as HTMLElement | null;\n const clickedCopyButton = target?.closest(\"button\");\n if (!clickedCopyButton) return;\n\n analytics.code.blockCopied(lang, source);\n if (installSnippetType) {\n analytics.docs.installSnippetCopied(\n installSnippetType,\n \"docs_code_block\",\n );\n }\n }}\n >\n {relabelCopyButtons(children, copyContextLabel)}\n \n ),\n [copyContextLabel, installSnippetType, lang, source],\n );\n\n return (\n \n );\n}\n" }, { "path": "apps/www/app/docs/actions/actions-examples.tsx", "content": "\"use client\";\n\nimport { useState } from \"react\";\nimport { DataTable } from \"@/components/tool-ui/data-table\";\nimport {\n OptionList,\n type OptionListSelection,\n} from \"@/components/tool-ui/option-list\";\nimport { OrderSummary } from \"@/components/tool-ui/order-summary\";\nimport {\n ParameterSlider,\n type SliderValue,\n} from \"@/components/tool-ui/parameter-slider\";\nimport {\n PreferencesPanel,\n type PreferencesValue,\n} from \"@/components/tool-ui/preferences-panel\";\nimport { ToolUI, createDecisionResult } from \"@/components/tool-ui/shared\";\nimport { Button } from \"@/components/ui/button\";\nimport { MockMessage, MockThread } from \"../_components/mock-thread\";\n\nconst tableRows = [\n { id: \"1\", merchant: \"Delta Airlines\", amount: 847 },\n { id: \"2\", merchant: \"Acme Hotel\", amount: 312 },\n];\n\nconst orderItems = [\n { id: \"sku-1\", name: \"Wireless Keyboard\", unitPrice: 89, quantity: 1 },\n { id: \"sku-2\", name: \"Mouse\", unitPrice: 49, quantity: 1 },\n];\n\nconst orderPricing = {\n subtotal: 138,\n shipping: 0,\n tax: 12.42,\n total: 150.42,\n currency: \"USD\",\n};\n\nconst initialSliderValues: SliderValue[] = [\n { id: \"exposure\", value: 0.2 },\n { id: \"contrast\", value: 12 },\n];\n\nconst preferencesSections = [\n {\n heading: \"Notifications\",\n items: [\n {\n id: \"marketing-email\",\n type: \"switch\" as const,\n label: \"Marketing email\",\n description: \"Receive product announcements and feature updates.\",\n defaultChecked: true,\n },\n {\n id: \"digest-frequency\",\n type: \"toggle\" as const,\n label: \"Digest frequency\",\n description: \"How often we send summary emails.\",\n options: [\n { value: \"daily\", label: \"Daily\" },\n { value: \"weekly\", label: \"Weekly\" },\n ],\n defaultValue: \"weekly\",\n },\n ],\n },\n];\n\nexport function ActionFlowToolCallVisual() {\n return (\n \n \n Show last month's travel expenses.\n \n \n
\n Calling getExpenses with args:\n 
\n            {`{\n  \"month\": \"2026-01\",\n  \"category\": \"travel\"\n}`}\n
\n
\n \n \n );\n}\n\nexport function ActionFlowRenderVisual() {\n return (\n
\n \n
\n );\n}\n\nexport function ActionFlowUserActionVisual() {\n const [event, setEvent] = useState(\"No action clicked yet.\");\n\n return (\n
\n \n \n \n \n \n {\n setEvent(`Clicked: ${actionId}`);\n }}\n />\n \n \n

{event}

\n
\n );\n}\n\nexport function ActionFlowRuntimeHandleVisual() {\n const [state, setState] = useState<\"idle\" | \"handling\" | \"done\">(\"idle\");\n\n return (\n
\n
\n

Runtime status

\n

\n {state === \"idle\" && \"Waiting for a user action.\"}\n {state === \"handling\" && \"Handling action and running side effect...\"}\n {state === \"done\" && \"Action handled successfully.\"}\n

\n
\n
\n {\n setState(\"handling\");\n setTimeout(() => setState(\"done\"), 600);\n }}\n >\n Simulate handler\n \n \n
\n
\n );\n}\n\nexport function ActionFlowCommitVisual() {\n const [orderChoice, setOrderChoice] = useState<\n { action: \"confirm\"; orderId?: string; confirmedAt?: string } | undefined\n >();\n const [event, setEvent] = useState(\"No decision committed yet.\");\n\n return (\n
\n \n \n {orderChoice ? (\n \n ) : (\n \n )}\n \n {!orderChoice && (\n \n \n createDecisionResult({\n decisionId: \"flow-order-decision\",\n action,\n payload:\n action.id === \"confirm\"\n ? {\n orderId: `ORD-${Date.now()}`,\n confirmedAt: new Date().toISOString(),\n }\n : undefined,\n })\n }\n onCommit={(result) => {\n if (result.actionId !== \"confirm\") {\n setEvent(\"Decision cancelled.\");\n return;\n }\n\n const orderId =\n typeof result.payload?.orderId === \"string\"\n ? result.payload.orderId\n : `ORD-${Date.now()}`;\n const confirmedAt =\n typeof result.payload?.confirmedAt === \"string\"\n ? result.payload.confirmedAt\n : new Date().toISOString();\n\n setOrderChoice({\n action: \"confirm\",\n orderId,\n confirmedAt,\n });\n setEvent(`Committed decision: ${orderId}`);\n }}\n />\n \n )}\n \n
\n

{event}

\n {orderChoice && (\n {\n setOrderChoice(undefined);\n setEvent(\"Decision reset for demo.\");\n }}\n >\n Reset\n \n )}\n
\n
\n );\n}\n\nexport function DisplaySurfaceLocalActionsExample() {\n const [event, setEvent] = useState(\"Try a local action below.\");\n\n return (\n
\n \n \n \n \n \n {\n setEvent(`Local action executed: ${actionId}`);\n }}\n />\n \n \n

{event}

\n
\n );\n}\n\nexport function DecisionSurfaceExample() {\n const [orderChoice, setOrderChoice] = useState<\n { action: \"confirm\"; orderId?: string; confirmedAt?: string } | undefined\n >();\n const [event, setEvent] = useState(\"No decision committed yet.\");\n\n return (\n
\n \n \n {orderChoice ? (\n \n ) : (\n \n )}\n \n {!orderChoice && (\n \n \n createDecisionResult({\n decisionId: \"decision-actions-order-decision\",\n action,\n payload:\n action.id === \"confirm\"\n ? {\n orderId: `ORD-${Date.now()}`,\n confirmedAt: new Date().toISOString(),\n }\n : undefined,\n })\n }\n onCommit={(result) => {\n if (result.actionId !== \"confirm\") {\n setEvent(\"Decision cancelled.\");\n return;\n }\n\n const orderId =\n typeof result.payload?.orderId === \"string\"\n ? result.payload.orderId\n : `ORD-${Date.now()}`;\n const confirmedAt =\n typeof result.payload?.confirmedAt === \"string\"\n ? result.payload.confirmedAt\n : new Date().toISOString();\n\n setOrderChoice({\n action: \"confirm\",\n orderId,\n confirmedAt,\n });\n setEvent(`Committed decision envelope: ${orderId}`);\n }}\n />\n \n )}\n \n
\n

{event}

\n {orderChoice && (\n {\n setOrderChoice(undefined);\n setEvent(\"Decision reset for demo.\");\n }}\n >\n Reset\n \n )}\n
\n
\n );\n}\n\nexport function ActionCentricExceptionsExample() {\n const [optionChoice, setOptionChoice] = useState();\n const [optionOutput, setOptionOutput] = useState<{\n actionId: string;\n state: OptionListSelection;\n } | null>(null);\n const [sliderValues, setSliderValues] =\n useState(initialSliderValues);\n const [sliderOutput, setSliderOutput] = useState<{\n actionId: string;\n state: SliderValue[];\n } | null>(null);\n const [savedPreferences, setSavedPreferences] =\n useState(null);\n const [preferencesOutput, setPreferencesOutput] = useState<{\n actionId: string;\n state: PreferencesValue;\n } | null>(null);\n\n return (\n
\n
\n
\n

OptionList

\n {\n setOptionOutput({ actionId, state: selection });\n\n if (actionId === \"confirm\") {\n setOptionChoice(selection);\n return;\n }\n\n if (actionId === \"cancel\") {\n setOptionChoice(undefined);\n }\n }}\n />\n
\n {optionChoice !== undefined && (\n {\n setOptionChoice(undefined);\n setOptionOutput(null);\n }}\n >\n Reset\n \n )}\n
\n
\n
\n

Mock output

\n

\n onAction(actionId, state)\n

\n 
\n            {optionOutput\n              ? JSON.stringify(optionOutput, null, 2)\n              : `{\n  \"actionId\": \"confirm\",\n  \"state\": \"merge\"\n}`}\n
\n
\n
\n\n
\n
\n

ParameterSlider

\n {\n setSliderOutput({ actionId, state: values });\n }}\n />\n
\n
\n

Mock output

\n

\n onAction(actionId, state)\n

\n 
\n            {sliderOutput\n              ? JSON.stringify(sliderOutput, null, 2)\n              : `{\n  \"actionId\": \"apply\",\n  \"state\": [\n    { \"id\": \"exposure\", \"value\": 0.2 },\n    { \"id\": \"contrast\", \"value\": 12 }\n  ]\n}`}\n
\n
\n
\n\n
\n
\n

PreferencesPanel

\n {\n setPreferencesOutput({ actionId, state: value });\n\n if (actionId === \"save\") {\n setSavedPreferences(value);\n return;\n }\n if (actionId === \"cancel\") {\n setSavedPreferences(null);\n }\n }}\n />\n
\n
\n

Mock output

\n

\n onAction(actionId, state)\n

\n 
\n            {preferencesOutput\n              ? JSON.stringify(preferencesOutput, null, 2)\n              : `{\n  \"actionId\": \"save\",\n  \"state\": {\n    \"marketing-email\": true,\n    \"digest-frequency\": \"weekly\"\n  }\n}`}\n
\n {savedPreferences && (\n

\n Last saved values are shown in the callback payload.\n

\n )}\n
\n
\n
\n );\n}\n" }, { "path": "apps/www/app/docs/actions/content.mdx", "content": "import { DocsHeader } from \"../_components/docs-header\";\nimport {\n ActionFlowCommitVisual,\n ActionFlowRenderVisual,\n ActionFlowRuntimeHandleVisual,\n ActionFlowToolCallVisual,\n ActionFlowUserActionVisual,\n ActionCentricExceptionsExample,\n DecisionSurfaceExample,\n DisplaySurfaceLocalActionsExample,\n} from \"./actions-examples\";\n\n\n\nBy default, tool results are read-only. The assistant calls a tool, a component renders the data, and that's it. Actions change that: they let users **respond** to what the assistant shows them.\n\nAn action might be a small utility (exporting a table as CSV, copying a code snippet) or a consequential decision like approving a deploy or confirming a purchase. Tool UI splits these into two categories: **local actions** for in-context side effects, and **decision actions** for choices that return to the assistant and produce a permanent [receipt](/docs/receipts).\n\nFor background on how components relate to the assistant and the user, see [Design Guidelines](/docs/design-guidelines).\n\n## Mental Model\n\n\n\n\n\nThe model chooses a tool and sends structured arguments.\n\n\n\n```ts\ntools: {\n getExpenses: tool({\n description: \"Return travel expenses for a month\",\n execute: async ({ month }) => ({ id: \"expenses-jan\", month }),\n }),\n}\n```\n\n\n\n\n\nThe returned args are parsed and rendered as a display surface.\n\n\n\n```tsx\nrender: ({ result }) => {\n const parsed = safeParseSerializableDataTable(result);\n if (!parsed) {\n return null;\n }\n return ;\n},\n```\n\n\n\n\n\nThe user clicks an action control associated with the surface.\n\n\n\n```tsx\nconst localActions = [{ id: \"export-csv\", label: \"Export CSV\" }];\n\nasync function handleLocalAction(actionId: string) {\n // side effects only\n}\n```\n\n\n\n\n\nYour action handler runs side effects (navigation, export, API call, etc.).\n\n\n\n```ts\nasync function handleLocalAction(actionId: string) {\n if (actionId === \"export-csv\") await exportCsv();\n if (actionId === \"open-report\") router.push(\"/reports/monthly\");\n}\n```\n\n\n\n\n\nIf the action is consequential, commit a durable outcome (typically via `addResult(...)` in your renderer runtime).\n\n\n\n```tsx\nconst decision = createDecisionResult({\n decisionId: \"order-123\",\n action: { id: \"confirm\", label: \"Purchase\" },\n});\n\nawait addResult?.(decision);\n```\n\n\n\n\n\n## Action Surfaces\n\nTool UI has two action surfaces:\n\n- **`ToolUI.LocalActions`**: Non-consequential side effects. Exporting, copying, opening a link. The assistant doesn't need to know it happened.\n- **`ToolUI.DecisionActions`**: Consequential choices that produce a durable decision envelope. Approving, confirming, selecting. The result returns to the assistant and the component shows a [receipt](/docs/receipts).\n\n**When to use which:** If the user's action changes the conversation, if the assistant should know about it and respond, use `DecisionActions`. If it's a utility that stays local to the UI, use `LocalActions`.\n\n### Display Components + LocalActions\n\nFor display-first components, keep rendering and actions separate: the display component goes inside `ToolUI.Surface`, and local actions go inside sibling `ToolUI.Actions`.\n\n\n\n`LocalActions` handlers should not commit durable result state.\n\n### Decision Components + DecisionActions\n\nWhen user intent is consequential (approve, confirm, purchase, publish, delete), use `DecisionActions`. This makes decision payload shape explicit and commit behavior auditable.\n\n\n\n`DecisionActions` handlers should return a typed envelope, then commit in the commit phase.\n\n## Action-Centric Components (Intentional Exception)\n\nSome components are action-centric by design. Their action handling is part of component semantics, so actions stay embedded on the component rather than using sibling `ToolUI.Actions` surfaces.\n\n### Shared Embedded Contract\n\nAll three action-centric components use the same embedded action interface:\n\n- `actions`: action buttons rendered by the component.\n- `onAction(actionId, state)`: runs after the action behavior and receives post-action state.\n- `onBeforeAction(actionId, state)`: guard evaluated before an action runs.\n\nOnly the `state` type changes by component:\n\n- `OptionList`: `OptionListSelection`\n- `ParameterSlider`: `SliderValue[]`\n- `PreferencesPanel`: `PreferencesValue`\n\n### Component Examples + Mock Outputs\n\nEach example below shows the live component on the left and the corresponding mock runtime output on the right.\n\n\n" }, { "path": "apps/www/app/docs/actions/opengraph-image.tsx", "content": "import {\n generateOgImage,\n size as ogSize,\n contentType as ogContentType,\n} from \"@/lib/og/og-image\";\n\nexport const runtime = \"nodejs\";\nexport const alt = \"Tool UI - Actions\";\nexport const size = ogSize;\nexport const contentType = ogContentType;\n\nexport default async function Image() {\n return generateOgImage(\n \"Actions\",\n \"External local and decision action surfaces for Tool UI\",\n );\n}\n" }, { "path": "apps/www/app/docs/actions/page.tsx", "content": "import type { Metadata } from \"next\";\nimport Content from \"./content.mdx\";\nimport { DocsArticle } from \"../_components/docs-article\";\n\nexport const metadata: Metadata = {\n title: \"Actions\",\n description: \"Action model basics.\",\n};\n\nexport const revalidate = 3600;\n\nexport default function ActionsPage() {\n return (\n \n \n \n );\n}\n" }, { "path": "apps/www/app/docs/advanced/content.mdx", "content": "import { DocsHeader } from \"../_components/docs-header\";\n\n\n\nThe [Quick Start](/docs/quick-start) covers the basics — installing a component, registering it, and seeing it render. This page adds three patterns: type-safe tool results with `InferUITools`, frontend tools that run entirely in the browser, and auto-continue for multi-step flows.\n\n## Tool Type Inference\n\n`InferUITools` (AI SDK 6) infers tool input/output types from your tool set and gives you fully typed `message.parts` in the UI.\n\n- [**InferUITools reference**](https://ai-sdk.dev/docs/reference/ai-sdk-ui/infer-ui-tools)\n\n\n\n\n\n### Define Tools with Output Schemas\n\n```ts title=\"lib/tools.ts\"\nimport { tool } from \"ai\";\nimport { z } from \"zod\";\nimport { SerializableLinkPreviewSchema } from \"@/components/tool-ui/link-preview/schema\";\n\nexport const tools = {\n previewLink: tool({\n description: \"Return a simple link preview\",\n inputSchema: z.object({ url: z.url() }),\n outputSchema: SerializableLinkPreviewSchema,\n async execute({ url }) {\n return {\n id: \"link-preview-1\",\n href: url,\n title: \"React Server Components\",\n image:\n \"https://images.unsplash.com/photo-1633356122544-f134324a6cee?auto=format&fit=crop&q=80&w=1200\",\n domain: new URL(url).hostname,\n };\n },\n }),\n} as const;\n\n// Export a type only; the client should import types, not server code.\nexport type Tools = typeof tools;\n```\n\n\n\n\n\n### Use Tools on the Server\n\n```ts\nimport { streamText, convertToModelMessages } from \"ai\";\nimport { openai } from \"@ai-sdk/openai\";\nimport { tools } from \"@/lib/tools\";\n\nexport async function POST(req: Request) {\n const { messages } = await req.json();\n\n const result = streamText({\n model: openai(\"gpt-5-nano\"),\n messages: await convertToModelMessages(messages),\n tools,\n });\n\n return result.toUIMessageStreamResponse();\n}\n```\n\n\n\n\n\n### Infer UI-Level Types in the Client\n\n```tsx\n\"use client\";\n\nimport { useChat } from \"@ai-sdk/react\";\nimport { InferUITools } from \"ai\";\nimport type { Tools } from \"@/lib/tools\";\nimport { LinkPreview } from \"@/components/tool-ui/link-preview\";\nimport { safeParseSerializableLinkPreview } from \"@/components/tool-ui/link-preview/schema\";\n\ntype MyUITools = InferUITools;\n\nexport default function Chat() {\n const { messages } = useChat({ api: \"/api/chat\" });\n\n return (\n
\n {messages.map((m) => (\n
\n {m.parts.map((part, i) => {\n // Fully typed: 'tool-previewLink' with correct output shape\n if (\n part.type === \"tool-previewLink\" &&\n part.state === \"output-available\"\n ) {\n const preview = safeParseSerializableLinkPreview(part.output);\n if (!preview) return null;\n return ;\n }\n return null;\n })}\n
\n ))}\n
\n );\n}\n```\n\n\n\n\n\n## Tips\n\n### Keep runtime boundaries clean\n\nExport only types from `lib/tools.ts` to the client. **Never import server code into the browser.**\n\n### Single-tool helpers\n\n`InferUITool` (singular) does the same thing for a single tool definition.\n\n### End-to-end validation\n\nUse the component's `outputSchema` on the server and `safeParseSerializable{componentName}` on the client to validate at both ends.\n\n### Routing by lifecycle state (outside Tool UI renderers)\n\nIf you consume raw `message.parts`, keep lifecycle handling outside Tool UI components:\n\n- `state === 'invocation'` / `state === 'output-pending'` / `state === 'errored'`:\n route to app-level UI (message shell, transport error, telemetry), not the Tool UI component.\n- `state === 'output-available'`:\n parse `part.output` with `safeParseSerializable{componentName}` and render only when parsing succeeds.\n\nInside Tool UI toolkit renderers, use a strict gate:\n\n```tsx\nconst parsed = safeParseSerializableX(resultOrArgs);\nif (!parsed) return null;\nreturn ;\n```\n\n## Frontend tools (interactive Tool UIs)\n\nDecision surfaces like OptionList work best as **frontend tools**. The model calls a tool with component props as arguments, then your UI calls `addResult(...)` after the user confirms. That result feeds back into the conversation.\n\nIf you're using `AssistantChatTransport`, it forwards **system instructions** and **registered tools** in the request body. Your `/api/chat` route needs to read and forward them, otherwise the model won't see your frontend tools.\n\n```ts title=\"app/api/chat/route.ts\"\nimport { openai } from \"@ai-sdk/openai\";\nimport {\n streamText,\n convertToModelMessages,\n jsonSchema,\n type UIMessage,\n type JSONSchema7,\n} from \"ai\";\n\ntype ForwardedTools = Record<\n string,\n { description?: string; parameters: JSONSchema7 }\n>;\n\nfunction toStreamTextTools(tools?: ForwardedTools) {\n if (!tools) return undefined;\n return Object.fromEntries(\n Object.entries(tools).map(([name, tool]) => [\n name,\n {\n ...(tool.description ? { description: tool.description } : {}),\n inputSchema: jsonSchema(tool.parameters),\n },\n ]),\n );\n}\n\nexport async function POST(req: Request) {\n const body = (await req.json()) as {\n messages: UIMessage[];\n system?: string;\n tools?: ForwardedTools;\n };\n\n const result = streamText({\n model: openai(\"gpt-4o\"),\n messages: await convertToModelMessages(body.messages),\n system: body.system,\n tools: toStreamTextTools(body.tools),\n });\n\n return result.toUIMessageStreamResponse();\n}\n```\n\n### Register a frontend tool\n\nRegister the tool on the client so `AssistantChatTransport` forwards it to the model.\n\n```tsx\n\"use client\";\n\nimport { type Toolkit } from \"@assistant-ui/react\";\nimport { OptionList } from \"@/components/tool-ui/option-list\";\nimport {\n safeParseSerializableOptionList,\n SerializableOptionListSchema,\n} from \"@/components/tool-ui/option-list/schema\";\n\nexport const toolkit: Toolkit = {\n selectFormat: {\n // description and parameters are forwarded to the model.\n description: \"Ask the user to choose an output format.\",\n parameters: SerializableOptionListSchema,\n // For frontend tools, parse args and render; handle result for receipt state.\n render: ({ args, toolCallId, result, addResult }) => {\n const parsedArgs = safeParseSerializableOptionList({\n ...args,\n id: args?.id ?? `format-selection-${toolCallId}`,\n });\n if (!parsedArgs) {\n return null;\n }\n if (result) {\n // After the user confirms, render the receipt state.\n return ;\n }\n return (\n {\n if (actionId === \"confirm\") addResult?.(selection);\n }}\n />\n );\n },\n },\n};\n```\n\nPass this toolkit to `Tools({ toolkit })` under `` so the definition and renderer are forwarded by `AssistantChatTransport`.\n\n### Auto-continue after `addResult(...)`\n\nWhen a tool produces results that need follow-up — a search that needs a summary, a calculation that needs interpretation — auto-continue tells the assistant to proceed without waiting for user input. Enable it with `sendAutomaticallyWhen`:\n\n```tsx\nimport {\n useChatRuntime,\n AssistantChatTransport,\n} from \"@assistant-ui/react-ai-sdk\";\nimport { lastAssistantMessageIsCompleteWithToolCalls } from \"ai\";\n\nconst runtime = useChatRuntime({\n transport: new AssistantChatTransport({ api: \"/api/chat\" }),\n // Automatically send when the assistant finishes with tool calls\n sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,\n});\n```\n" }, { "path": "apps/www/app/docs/advanced/opengraph-image.tsx", "content": "import {\n generateOgImage,\n size as ogSize,\n contentType as ogContentType,\n} from \"@/lib/og/og-image\";\n\nexport const runtime = \"nodejs\";\nexport const alt = \"Tool UI - Advanced\";\nexport const size = ogSize;\nexport const contentType = ogContentType;\n\nexport default async function Image() {\n return generateOgImage(\"Advanced\", \"Deep dive into customization\");\n}\n" }, { "path": "apps/www/app/docs/advanced/page.tsx", "content": "import type { Metadata } from \"next\";\nimport Content from \"./content.mdx\";\nimport { DocsArticle } from \"../_components/docs-article\";\n\nexport const metadata: Metadata = {\n title: \"Advanced\",\n description: \"Advanced configuration and usage patterns\",\n};\n\nexport const revalidate = 3600;\n\nexport default function AdvancedDocsPage() {\n return (\n \n \n \n );\n}\n" }, { "path": "apps/www/app/docs/agent-skills/content.mdx", "content": "import { DocsHeader } from \"../_components/docs-header\";\n\n\n\n## Skill installation\n\n```bash\nnpx skills add https://github.com/assistant-ui/tool-ui --skill tool-ui\n```\n\n## What's included\n\nThis package gives coding agents everything they need to integrate Tool UI components:\n\n- **SKILL.md** — the five-step workflow (see below)\n- **Reference docs** — component catalog, recipes, integration patterns, troubleshooting\n- **CLI scripts** — compatibility checks, search, scaffolding\n- **Test suites** — regression coverage for the scripts\n\n## SKILL.md — the workflow\n\n`.agents/skills/tool-ui/SKILL.md` is the entry point. Follow these five steps:\n\n1. **Compatibility check** — verify prerequisites (shadcn/ui, Tailwind, Radix)\n2. **Discover** — search and browse available components\n3. **Install** — pull components from the registry\n4. **Scaffold** — generate adapter files and runtime wiring code\n5. **Validate** — confirm the integration works\n\nEach step links to the relevant script or reference doc.\n\n## Reference docs\n\nAll reference material lives in `.agents/skills/tool-ui/references/`.\n\n### Discover\n\n**`components-catalog.md`** — Browse components by category. Each entry includes a description and guidelines for picking the right one for your use case.\n\n**`components-data.json`** — Machine-readable metadata that the CLI scripts use for search and install operations.\n\n### Install\n\n**`recipes.md`** — Pre-built bundles for common patterns (planning flow, research output, commerce flow). Each recipe has a one-line install command that pulls the entire bundle.\n\n### Scaffold\n\n**`integration-patterns.md`** — Five wiring patterns with full code examples:\n\n- **Backend display** — render tool results as read-only UI\n- **Backend + local actions** — add inline actions alongside backend data\n- **Frontend decision** — collect user input before proceeding\n- **Action-centric** — surface standalone actions without surrounding content\n- **Manual** — wire components directly without the runtime framework\n\n### Validate\n\n**`troubleshooting.md`** — Symptom → cause → fix matrix for common install and runtime issues.\n\n## CLI scripts\n\nAll scripts live in `.agents/skills/tool-ui/scripts/`.\n\n### `tool_ui_compat.py`\n\nChecks `components.json` compatibility, auto-fixes the `@tool-ui` registry entry, and runs deeper doctor checks — shared folder presence, import resolution, and package dependencies.\n\n### `tool_ui_components.py`\n\nLists, searches, and generates install commands for components. Also handles bundle recipes from `recipes.md`. Reads from `components-data.json` for fast lookups.\n\n### `tool_ui_scaffold.py`\n\nGenerates ready-to-paste runtime wiring code in three modes: `assistant-backend`, `assistant-frontend`, and `manual`. Output adapts to the project's framework and integration pattern.\n\n## Test suites\n\nScript tests in `.agents/skills/tool-ui/tests/` provide regression coverage for the CLI scripts. They validate SKILL.md references, script syntax, and data integrity.\n" }, { "path": "apps/www/app/docs/agent-skills/opengraph-image.tsx", "content": "import {\n generateOgImage,\n size as ogSize,\n contentType as ogContentType,\n} from \"@/lib/og/og-image\";\n\nexport const runtime = \"nodejs\";\nexport const alt = \"Tool UI - Agent Skills\";\nexport const size = ogSize;\nexport const contentType = ogContentType;\n\nexport default async function Image() {\n return generateOgImage(\n \"Agent Skills\",\n \"Let your coding agent to the heavy lifting.\",\n );\n}\n" }, { "path": "apps/www/app/docs/agent-skills/page.tsx", "content": "import type { Metadata } from \"next\";\nimport Content from \"./content.mdx\";\nimport { DocsArticle } from \"../_components/docs-article\";\n\nexport const metadata: Metadata = {\n title: \"Agent Skills\",\n description: \"Let your coding agent to the heavy lifting.\",\n};\n\nexport const revalidate = 3600;\n\nexport default function AgentSkillsPage() {\n return (\n \n \n \n );\n}\n" }, { "path": "apps/www/app/docs/approval-card/content.mdx", "content": "import { DocsHeader } from \"../_components/docs-header\";\nimport { ApprovalCard } from \"@/components/tool-ui/approval-card\";\n\n\n\nBefore the assistant deploys to production, deletes a project, or sends an email on your behalf, it should ask first. ApprovalCard renders a confirmation prompt with context about the action (metadata, consequences, a clear approve/deny choice) and records the decision as a receipt once the user responds.\n\n**Role:** Decision. For choices that return to the assistant. See [Design Guidelines](/docs/design-guidelines) for how component roles work.\n\n## Getting Started\n\n\n\n\n\nRun this once from your project root.\n\n\n\n\n\n\n\nRender `ApprovalCard` in your UI with tool-compatible props.\n\n
\n\n```tsx\nimport { ApprovalCard } from \"@/components/tool-ui/approval-card\";\n\nexport function Example() {\n return (\n console.log(\"Approved\")}\n onCancel={() => console.log(\"Denied\")}\n />\n );\n}\n```\n\n
\n\n\n\n\n\nRegister this renderer so tool results display as `ApprovalCard`.\n\n```tsx\n\"use client\";\n\nimport { type Toolkit } from \"@assistant-ui/react\";\nimport { ApprovalCard } from \"@/components/tool-ui/approval-card\";\nimport {\n safeParseSerializableApprovalCard,\n SerializableApprovalCardSchema,\n} from \"@/components/tool-ui/approval-card/schema\";\n\nexport const toolkit: Toolkit = {\n requestApproval: {\n description: \"Request user approval before performing an action.\",\n parameters: SerializableApprovalCardSchema,\n render: ({ args, toolCallId, result, addResult }) => {\n const parsedArgs = safeParseSerializableApprovalCard({\n ...args,\n id: args?.id ?? `approval-${toolCallId}`,\n });\n if (!parsedArgs) {\n return null;\n }\n return result ? (\n \n ) : (\n addResult?.(\"approved\")}\n onCancel={() => addResult?.(\"denied\")}\n />\n );\n },\n },\n};\n```\n\n\n\n\n\n## Key Features\n\n\n \n Blocks agent actions until the user approves or denies\n \n \n Red styling for irreversible or dangerous operations\n \n \n Key-value pairs giving context about the action\n \n \n Compact read-only view of the decision in conversation history\n \n\n\n## Receipt State\n\nPass a `choice` prop to render this component in its receipt state. See [Receipts](/docs/receipts) for the pattern.\n\nThe receipt shows the outcome (approved or denied) with the custom button label you specified, fades in with a subtle animation, and is read-only.\n\n## Destructive Variant\n\nSet `variant=\"destructive\"` for dangerous or irreversible actions. The icon background and confirm button turn red.\n\n## Props\n\n void | Promise\",\n },\n onCancel: {\n description: \"Handler when user denies\",\n type: \"() => void | Promise\",\n },\n }}\n/>\n\n## Metadata Schema\n\n\n\nLong metadata values are automatically truncated with an ellipsis. Keep values concise for best results.\n\n## Accessibility\n\n- Uses `role=\"dialog\"` with `aria-labelledby` and `aria-describedby`\n- **Keyboard navigation:**\n - `Tab` to move between buttons\n - `Enter` or `Space` to activate focused button\n - `Escape` triggers the cancel action\n- Receipt state uses `role=\"status\"` for screen reader announcements\n- Fade-in animation respects `prefers-reduced-motion`\n\n## Related\n\n- [Order Summary](/docs/order-summary): itemized confirmation for purchases\n- [Option List](/docs/option-list): multiple choices when the decision isn't binary\n- [Message Draft](/docs/message-draft): review and approve outgoing messages\n- [Preferences Panel](/docs/preferences-panel): structured settings capture\n" }, { "path": "apps/www/app/docs/approval-card/opengraph-image.tsx", "content": "import {\n generateOgImage,\n size as ogSize,\n contentType as ogContentType,\n} from \"@/lib/og/og-image\";\n\nexport const runtime = \"nodejs\";\nexport const alt = \"Tool UI - Approval Card\";\nexport const size = ogSize;\nexport const contentType = ogContentType;\n\nexport default async function Image() {\n return generateOgImage(\n \"Approval Card\",\n \"Binary confirmation for agent actions\",\n );\n}\n" }, { "path": "apps/www/app/docs/approval-card/page.tsx", "content": "import type { Metadata } from \"next\";\nimport Content from \"./content.mdx\";\nimport { ComponentDocsTabs } from \"../_components/component-docs-tabs\";\n\nexport const metadata: Metadata = {\n title: \"Approval Card\",\n description: \"Binary confirmation for agent actions\",\n};\n\nexport const revalidate = 3600;\n\nexport default function ApprovalCardDocsPage() {\n return } componentId=\"approval-card\" />;\n}\n" }, { "path": "apps/www/app/docs/audio/content.mdx", "content": "import { DocsHeader } from \"../_components/docs-header\";\nimport { Audio } from \"@/components/tool-ui/audio\";\n\n\n\nAn audio URL by itself is invisible. No artwork, no title, no way to know what you are about to hear. Audio wraps the browser's native player with album art, title, duration, and source attribution so the track looks intentional rather than dumped into the conversation.\n\n**Role:** Information. For displaying data without user input. See [Design Guidelines](/docs/design-guidelines) for how component roles work.\n\n## Getting Started\n\n\n\n\n\nRun this once from your project root.\n\n\n\n\n\n\n\nRender `Audio` in your UI with tool-compatible props.\n\n
\n\n```tsx\nimport { Audio } from \"@/components/tool-ui/audio\";\n\nexport function Example() {\n return (\n \n );\n}\n```\n\n
\n\n\n\n\n\nRegistration tells assistant-ui which component to render when a tool returns audio data. Without it, tool results appear as raw JSON.\n\n```tsx\nimport { type Toolkit } from \"@assistant-ui/react\";\nimport { Audio } from \"@/components/tool-ui/audio\";\nimport { safeParseSerializableAudio } from \"@/components/tool-ui/audio/schema\";\n\nexport const toolkit: Toolkit = {\n showAudio: {\n type: \"backend\",\n render: ({ result }) => {\n const parsed = safeParseSerializableAudio(result);\n if (!parsed) {\n return null;\n }\n return \n\n\n\n## Key Features\n\n\n \n Browser-native play, pause, seek, and volume\n \n \n Album art or thumbnail displayed beside the player\n \n \n Title, description, duration, and file size at a glance\n \n \n Artist, album, or source with an optional link\n \n\n\n## Props\n\n void\",\n },\n }}\n/>\n\nUse [`ToolUI.LocalActions`](/docs/actions) to compose external actions next to `Audio`.\n\n## Related\n\n- [Video](/docs/video): the same inline media pattern for video content\n- [Image](/docs/image): for static visual content with metadata and attribution\n- [Item Carousel](/docs/item-carousel): for browsable collections of media items like albums or playlists\n" }, { "path": "apps/www/app/docs/audio/opengraph-image.tsx", "content": "import {\n generateOgImage,\n size as ogSize,\n contentType as ogContentType,\n} from \"@/lib/og/og-image\";\n\nexport const runtime = \"nodejs\";\nexport const alt = \"Tool UI - Audio\";\nexport const size = ogSize;\nexport const contentType = ogContentType;\n\nexport default async function Image() {\n return generateOgImage(\"Audio\", \"Audio playback with artwork and metadata\");\n}\n" }, { "path": "apps/www/app/docs/audio/page.tsx", "content": "import type { Metadata } from \"next\";\nimport Content from \"./content.mdx\";\nimport { ComponentDocsTabs } from \"../_components/component-docs-tabs\";\n\nexport const metadata: Metadata = {\n title: \"Audio\",\n description: \"Audio playback with artwork and metadata\",\n};\n\nexport const revalidate = 3600;\n\nexport default function AudioDocsPage() {\n return } componentId=\"audio\" />;\n}\n" }, { "path": "apps/www/app/docs/changelog/content.mdx", "content": "import { DocsHeader } from \"../_components/docs-header\";\n\n\n\n{/* changelog-generated-to: c84896f */}\n\n## 2026-02-26\n\n### Changes\n\n- New component: [Geo Map](/docs/geo-map) — themed Leaflet shell with automatic dark tile inheritance from the document theme.\n- [Gallery](/docs/gallery): deterministic ranking, centered layout, and masonry column breakpoint refinements.\n\n## 2026-02-17\n\n### Changes\n\n- New component: [CodeDiff](/docs/code-diff) — unified and split diff views for code.\n- Compound composition API shipped across [Code Block](/docs/code-block), [Terminal](/docs/terminal), [Order Summary](/docs/order-summary), [Video](/docs/video), [Progress Tracker](/docs/progress-tracker), and [Item Carousel](/docs/item-carousel).\n- [Weather Widget](/docs/weather-widget): runtime artifacts now generate as TypeScript; generated payload shrunk with size guardrails.\n- Shared theme tokens introduced across code components; `Code Block` mirrors shared tokens locally with tightened content line-height.\n- Normalized action button styling and layout across components; default spacing added between `ToolUI` surface and actions.\n- [Data Table](/docs/data-table): added links-tags preset; removed escalate from actions preset; removed resources preset from docs.\n\n### Migration prompt\n\n```text\nUpdate Tool UI components to the compound composition API.\n\nGoals:\n1) Re-install only the affected components that already exist in this project.\n2) Migrate usage from monolithic component props to compound subcomponents (e.g., CodeBlock.Root, Terminal.Output).\n3) Validate UI rendering with updated component APIs.\n\nSteps:\n- Check which of these components exist in this project by looking for their directories under components/tool-ui/:\n code-block, terminal, order-summary, video, progress-tracker, item-carousel\n- For each component that exists, re-install it to pull in the new compound exports:\n npx shadcn@latest add @tool-ui/code-block\n npx shadcn@latest add @tool-ui/terminal\n npx shadcn@latest add @tool-ui/order-summary\n npx shadcn@latest add @tool-ui/video\n npx shadcn@latest add @tool-ui/progress-tracker\n npx shadcn@latest add @tool-ui/item-carousel\n- Skip any component not already installed — do not add new components.\n- Update imports and usage to reference compound subcomponents instead of monolithic component props.\n- Run lint, typecheck, and tests; fix any breakages.\n- Validate UI rendering with updated component APIs.\n```\n\n## 2026-02-12\n\n### Breaking changes\n\n- Tool UI component entrypoints now enforce /schema boundaries; imports from non-schema entrypoints may break.\n- Removed the error boundary layer across Tool UI components; existing error handling may no longer apply.\n- Tool UI action model migrated to bound compound action surfaces. Legacy inline response-action patterns were removed in favor of `LocalActions` / `DecisionActions`, and outlier components now use dedicated action configs. See [Actions](/docs/actions).\n\n### Changes\n\n- Tool UI: repo-wide enforcement of /schema entrypoints.\n- Tool UI action model refactor: migrated components to bound compound action surfaces via `LocalActions` and `DecisionActions`. See [Actions](/docs/actions).\n- Action-model cutover shipped across core components (including [Audio](/docs/audio), [Citation](/docs/citation), [Code Block](/docs/code-block), [Data Table](/docs/data-table), [Image](/docs/image), [Link Preview](/docs/link-preview), [Order Summary](/docs/order-summary), [Plan](/docs/plan), [Terminal](/docs/terminal), [Video](/docs/video), and social post renderers: [X Post](/docs/x-post), [Instagram Post](/docs/instagram-post), [LinkedIn Post](/docs/linkedin-post)).\n- Outlier workflows were split to component-specific action configs ([Option List](/docs/option-list), [Parameter Slider](/docs/parameter-slider), [Preferences Panel](/docs/preferences-panel)) with contracts tightened around supported action props. See [Actions](/docs/actions).\n- [Option List](/docs/option-list): receipt presets codegen updated to omit onConfirm; multi-receipt preset added; receipt spacing refined; related tests updated.\n- [Progress Tracker](/docs/progress-tracker): shipped v2 display with result-driven UI; tests updated.\n- [Plan](/docs/plan): compact variant steps-only mode implemented.\n- [Image Gallery](/docs/image-gallery) and [Item Carousel](/docs/item-carousel): aligned tool-ui contracts.\n\n### Migration prompt\n\n```text\nMigrate codebase to adopt explicit /schema entrypoints for Tool UI schemas.\n\nGoals:\n1) Move all schema helper imports to dedicated /schema entrypoints per component.\n2) Keep public UI imports under their component paths; import schema only from /schema modules.\n3) Migrate action handling to the bound compound model using LocalActions / DecisionActions.\n4) Replace legacy response-action usage on outlier components with their dedicated action configs.\n5) Update tests and docs to reflect new entrypoints and action model semantics.\n6) Regenerate artifacts (registry/public assets) and update docs accordingly.\n7) Validate UI rendering with updated imports and schema/action contracts.\n\nSteps:\n- Replace imports of Serializable*Schema, parseSerializable*, and safeParseSerializable* from non-schema tool-ui entrypoints with imports from the component's /schema module (e.g., @/components/tool-ui//schema).\n- For all affected components, update imports to reference /schema entrypoints; preserve existing UI imports.\n- Migrate shared action composition to ToolUI-bound LocalActions / DecisionActions surfaces.\n- Remove legacy inline response-action usage and adopt dedicated outlier action configs (for example selection/adjustment/form action props) where applicable.\n- Update relevant tests and docs to reflect new entrypoints and action model semantics.\n- Run lint, typecheck, and tests; fix breakages.\n- Regenerate artifacts (registry/public assets) and update docs accordingly.\n- Validate UI rendering with updated schema and action contracts.\n```\n" }, { "path": "apps/www/app/docs/changelog/opengraph-image.tsx", "content": "import {\n contentType as ogContentType,\n generateOgImage,\n size as ogSize,\n} from \"@/lib/og/og-image\";\n\nexport const runtime = \"nodejs\";\nexport const alt = \"Tool UI - Changelog\";\nexport const size = ogSize;\nexport const contentType = ogContentType;\n\nexport default async function Image() {\n return generateOgImage(\"Changelog\", \"Release notes and migration guidance\");\n}\n" }, { "path": "apps/www/app/docs/changelog/page.tsx", "content": "import type { Metadata } from \"next\";\nimport Content from \"./content.mdx\";\nimport { DocsArticle } from \"../_components/docs-article\";\n\nexport const metadata: Metadata = {\n title: \"Changelog\",\n description: \"Release notes and migration guidance\",\n};\n\nexport const revalidate = 3600;\n\nexport default function ChangelogDocsPage() {\n return (\n \n \n \n );\n}\n" }, { "path": "apps/www/app/docs/chart/content.mdx", "content": "import { DocsHeader } from \"../_components/docs-header\";\n\n\n\n\"How did I spend money this week?\" is a question best answered visually. Chart renders bar or line visualizations inline in the conversation. You pass data, an x-axis key, and one or more series. The assistant can show spending breakdowns, revenue trends, or performance over time without describing the numbers in prose.\n\n**Role:** Information. For displaying data the user reads. See [Design Guidelines](/docs/design-guidelines) for how component roles work.\n\n## Getting Started\n\n\n\n\n\nRun this once from your project root.\n\n\n\n\n\n\n\nRender `Chart` in your UI with tool-compatible props.\n\n
\n\n```tsx\nimport { Chart } from \"@/components/tool-ui/chart\";\n\n;\n```\n\n
\n\n\n\n\n\nRegister this renderer so tool results display as `Chart`.\n\n```tsx\nimport { type Toolkit } from \"@assistant-ui/react\";\nimport { Chart } from \"@/components/tool-ui/chart\";\nimport { safeParseSerializableChart } from \"@/components/tool-ui/chart/schema\";\n\nexport const toolkit: Toolkit = {\n showChart: {\n type: \"backend\",\n render: ({ result }) => {\n const parsed = safeParseSerializableChart(result);\n if (!parsed) {\n return null;\n }\n return ;\n },\n },\n};\n```\n\n\n\n\n\n## Key Features\n\n\n \n Bar for categorical data, line for time-series\n \n \n Plot multiple datasets with automatic color assignment\n \n \n Hover tooltips and click handlers on data points\n \n \n Optional legends, grid lines, and custom color palettes\n \n\n\n## Variants\n\n### Line Charts\n\nUse `type=\"line\"` for time-series or continuous data.\n\n### Minimal Configuration\n\nOnly `data`, `xKey`, and `series` are required. Title, description, legend, and grid are all optional.\n\n## Props\n\n[]\",\n required: true,\n },\n xKey: {\n description: \"Key for x-axis values\",\n type: \"string\",\n required: true,\n },\n series: {\n description: \"Data series to plot\",\n type: \"ChartSeries[]\",\n required: true,\n },\n title: {\n description: \"Chart title (renders in Card header)\",\n type: \"string\",\n },\n description: {\n description: \"Chart description (renders below title)\",\n type: \"string\",\n },\n colors: {\n description: \"Custom color palette for series\",\n type: \"string[]\",\n },\n showLegend: {\n description: \"Show legend below chart\",\n type: \"boolean\",\n default: \"false\",\n },\n showGrid: {\n description: \"Show background grid lines\",\n type: \"boolean\",\n default: \"true\",\n },\n onDataPointClick: {\n description: \"Click handler for data points\",\n type: \"(point: ChartDataPoint) => void\",\n },\n }}\n/>\n\n## Series Schema\n\n\n\n## ChartDataPoint (click handler payload)\n\n\",\n },\n }}\n/>\n\n## Accessibility\n\n- Built on Recharts with semantic SVG structure\n- Tooltips and legends provide text alternatives for visual data\n- Inherits focus management from shadcn/ui Card primitives\n\n## Related\n\n- [Stats Display](/docs/stats-display): key metrics as a grid of numbers with sparklines\n" }, { "path": "apps/www/app/docs/chart/opengraph-image.tsx", "content": "import {\n generateOgImage,\n size as ogSize,\n contentType as ogContentType,\n} from \"@/lib/og/og-image\";\n\nexport const runtime = \"nodejs\";\nexport const alt = \"Tool UI - Chart\";\nexport const size = ogSize;\nexport const contentType = ogContentType;\n\nexport default async function Image() {\n return generateOgImage(\"Chart\", \"Visualize data with interactive charts\");\n}\n" }, { "path": "apps/www/app/docs/chart/page.tsx", "content": "import type { Metadata } from \"next\";\nimport Content from \"./content.mdx\";\nimport { ComponentDocsTabs } from \"../_components/component-docs-tabs\";\n\nexport const metadata: Metadata = {\n title: \"Chart\",\n description: \"Visualize data with interactive charts\",\n};\n\nexport const revalidate = 3600;\n\nexport default function ChartDocsPage() {\n return } componentId=\"chart\" />;\n}\n" }, { "path": "apps/www/app/docs/citation/content.mdx", "content": "import { DocsHeader } from \"../_components/docs-header\";\nimport { Citation } from \"@/components/tool-ui/citation\";\n\n\n\nUsers trust answers they can verify. Citation renders a clickable reference card with title, domain, favicon, and an optional text snippet so the reader can trace any claim back to its source. Three variants cover different density needs: a full card for prominent references, an inline chip for tight spaces, and stacked favicons for citation lists.\n\n**Role:** Information. For displaying data without user input. See [Design Guidelines](/docs/design-guidelines) for how component roles work.\n\n## Getting Started\n\n\n\n\n\nRun this once from your project root.\n\n\n\n\n\n\n\nRender `Citation` in your UI with tool-compatible props.\n\n
\n\n```tsx\nimport { Citation } from \"@/components/tool-ui/citation\";\n\nexport function Example() {\n return (\n \n );\n}\n```\n\n
\n\n\n\n\n\nRegistration tells assistant-ui which component to render when a tool returns citation data. Without it, tool results appear as raw JSON.\n\n```tsx\nimport { type Toolkit } from \"@assistant-ui/react\";\nimport { Citation } from \"@/components/tool-ui/citation\";\nimport { safeParseSerializableCitation } from \"@/components/tool-ui/citation/schema\";\n\nexport const toolkit: Toolkit = {\n showCitation: {\n type: \"backend\",\n render: ({ result }) => {\n const parsed = safeParseSerializableCitation(result);\n if (!parsed) {\n return null;\n }\n return ;\n },\n },\n};\n```\n\n\n\n\n\n## Key Features\n\n\n \n Title, domain, author, and publication date in one card\n \n \n Shows a relevant excerpt so users can judge relevance before clicking\n \n \n Full card for detail, inline chip for tight spaces, stacked favicons for\n lists\n \n \n Arrow keys and Enter navigate the stacked variant popover\n \n\n\n## Props\n\n void\",\n },\n }}\n/>\n\nUse [`ToolUI.LocalActions`](/docs/actions) to compose external actions next to citations.\n\n## Accessibility\n\nThe stacked variant popover supports full keyboard navigation:\n\n- **Enter / Space:** Open the popover\n- **Tab:** Navigate between citations\n- **Escape:** Close popover and return focus to trigger\n\nMouse users can hover to reveal the popover. All variants open links in new tabs with `noopener,noreferrer` for security.\n\n## Related\n\n- [Link Preview](/docs/link-preview): both surface external references, but LinkPreview shows Open Graph cards while Citation focuses on source attribution\n- [Data Table](/docs/data-table): for displaying multiple references in a structured, sortable format\n" }, { "path": "apps/www/app/docs/citation/opengraph-image.tsx", "content": "import {\n generateOgImage,\n size as ogSize,\n contentType as ogContentType,\n} from \"@/lib/og/og-image\";\n\nexport const runtime = \"nodejs\";\nexport const alt = \"Tool UI - Citation\";\nexport const size = ogSize;\nexport const contentType = ogContentType;\n\nexport default async function Image() {\n return generateOgImage(\n \"Citation\",\n \"Display source references with attribution\",\n );\n}\n" }, { "path": "apps/www/app/docs/citation/page.tsx", "content": "import type { Metadata } from \"next\";\nimport Content from \"./content.mdx\";\nimport { ComponentDocsTabs } from \"../_components/component-docs-tabs\";\n\nexport const metadata: Metadata = {\n title: \"Citation\",\n description: \"Display source references with attribution\",\n};\n\nexport const revalidate = 3600;\n\nexport default function CitationDocsPage() {\n return } componentId=\"citation\" />;\n}\n" }, { "path": "apps/www/app/docs/code-block/content.mdx", "content": "import { DocsHeader } from \"../_components/docs-header\";\n\n\n\nWhen the assistant generates or references code, unstyled monospace text sells it short. CodeBlock renders syntax-highlighted snippets with line numbers and a copy button. You can highlight specific lines to draw attention to changes or bugs, and collapse long snippets with `maxCollapsedLines` to keep conversations scannable.\n\n**Role:** Information. For displaying data the user reads. See [Design Guidelines](/docs/design-guidelines) for how component roles work.\n\n## Getting Started\n\n\n\n\n\nRun this once from your project root.\n\n\n\n\n\n\n\nRender `CodeBlock` in your UI with tool-compatible props.\n\n
\n\n```tsx\nimport { CodeBlock } from \"@/components/tool-ui/code-block\";\n\nexport function MyComponent() {\n return (\n \n );\n}\n```\n\n
\n\n\n\n\n\nRegister this renderer so tool results display as `CodeBlock`.\n\n```tsx\n// Backend tool\nimport { tool, jsonSchema } from \"ai\";\n\nconst showCodeBlock = tool({\n description: \"Show a code snippet\",\n inputSchema: jsonSchema<{}>({\n type: \"object\",\n properties: {},\n additionalProperties: false,\n }),\n async execute() {\n return {\n id: \"code-block-1\",\n code: \"console.log('hello');\",\n language: \"javascript\",\n filename: \"hello.js\",\n highlightLines: [1],\n };\n },\n});\n\n// Frontend with assistant-ui\nimport { type Toolkit } from \"@assistant-ui/react\";\nimport { CodeBlock } from \"@/components/tool-ui/code-block\";\nimport { safeParseSerializableCodeBlock } from \"@/components/tool-ui/code-block/schema\";\n\nexport const toolkit: Toolkit = {\n showCodeBlock: {\n type: \"backend\",\n render: ({ result }) => {\n const parsed = safeParseSerializableCodeBlock(result);\n if (!parsed) {\n return null;\n }\n return ;\n },\n },\n};\n```\n\n\n\n\n\n## Key Features\n\n\n \n Shiki-powered with 100+ languages\n \n \n Draw attention to specific lines for explanations or diffs\n \n \n Opt-in collapse for long snippets via `maxCollapsedLines`\n \n \n Filename and language badge in the header\n \n\n\n## Props\n\n### Core\n\n\n\n### Display Options\n\n void\",\n },\n }}\n/>\n\n### Standard Props\n\n\n\nUse [`ToolUI.LocalActions`](/docs/actions) to compose external actions next to `CodeBlock`.\n\n## Supported Languages\n\nCodeBlock supports all languages included with Shiki, including:\n\n- TypeScript/JavaScript\n- Python\n- JSON\n- Bash/Shell\n- CSS/HTML\n- Markdown\n- SQL\n- YAML\n- Go\n- Rust\n- And many more...\n\nSee [Shiki documentation](https://shiki.style/languages) for the complete list.\n\n## Accessibility\n\n- Collapsible sections use Radix Collapsible with proper ARIA attributes\n- Copy button is keyboard-accessible with focus indication\n- Code content is selectable and works with screen readers\n\n## Related\n\n- [Terminal](/docs/terminal): command-line output and logs\n" }, { "path": "apps/www/app/docs/code-block/opengraph-image.tsx", "content": "import {\n generateOgImage,\n size as ogSize,\n contentType as ogContentType,\n} from \"@/lib/og/og-image\";\n\nexport const runtime = \"nodejs\";\nexport const alt = \"Tool UI - Code Block\";\nexport const size = ogSize;\nexport const contentType = ogContentType;\n\nexport default async function Image() {\n return generateOgImage(\n \"Code Block\",\n \"Display syntax-highlighted code snippets\",\n );\n}\n" }, { "path": "apps/www/app/docs/code-block/page.tsx", "content": "import type { Metadata } from \"next\";\nimport Content from \"./content.mdx\";\nimport { ComponentDocsTabs } from \"../_components/component-docs-tabs\";\n\nexport const metadata: Metadata = {\n title: \"Code Block\",\n description: \"Display syntax-highlighted code snippets\",\n};\n\nexport const revalidate = 3600;\n\nexport default function CodeBlockDocsPage() {\n return } componentId=\"code-block\" />;\n}\n" }, { "path": "apps/www/app/docs/code-diff/content.mdx", "content": "import { DocsHeader } from \"../_components/docs-header\";\n\n\n\nCodeDiff renders syntax-highlighted diffs with additions and deletions marked in color. Pass `oldCode` / `newCode` for file comparisons or a `patch` string for unified diffs from version control.\n\n**Role:** Information. For displaying data the user reads. See [Design Guidelines](/docs/design-guidelines) for how component roles work.\n\n## Getting Started\n\n\n\n\n\nRun this once from your project root.\n\n\n\n\n\n\n\nCodeDiff uses [`@pierre/diffs`](https://www.npmjs.com/package/@pierre/diffs) for diff computation and rendering.\n\n```bash\npnpm add @pierre/diffs\n```\n\n\n\n\n\nRender `CodeDiff` in your UI with tool-compatible props.\n\n
\n\n```tsx\nimport { CodeDiff } from \"@/components/tool-ui/code-diff\";\n\nexport function MyComponent() {\n return (\n \n );\n}\n```\n\n
\n\n\n\n\n\nRegister this renderer so tool results display as `CodeDiff`.\n\n```tsx\nimport { type Toolkit } from \"@assistant-ui/react\";\nimport { CodeDiff } from \"@/components/tool-ui/code-diff\";\nimport { safeParseSerializableCodeDiff } from \"@/components/tool-ui/code-diff/schema\";\n\nexport const toolkit: Toolkit = {\n showCodeDiff: {\n type: \"backend\",\n render: ({ result }) => {\n const parsed = safeParseSerializableCodeDiff(result);\n if (!parsed) {\n return null;\n }\n return ;\n },\n },\n};\n```\n\n\n\n\n\n## Key Features\n\n\n \n Pass `oldCode`/`newCode` for file diffs, or `patch` for unified diffs\n \n \n Language-aware highlighting powered by @pierre/diffs\n \n \n Side-by-side comparison with `diffStyle=\"split\"`\n \n \n Collapse long diffs with `maxCollapsedLines`\n \n\n\n## Props\n\n### Core\n\n\n\n### Display Options\n\n\n\n### Standard Props\n\n\n\nUse [`ToolUI.LocalActions`](/docs/actions) to compose external actions next to `CodeDiff`.\n\n## Accessibility\n\n- Collapsible sections use Radix Collapsible with proper ARIA attributes\n- Copy button is keyboard-accessible with focus indication\n- Diff content is selectable and works with screen readers\n\n## Related\n\n- [Code Block](/docs/code-block): single-file syntax-highlighted code display\n- [Terminal](/docs/terminal): command-line output and logs\n" }, { "path": "apps/www/app/docs/code-diff/opengraph-image.tsx", "content": "import {\n generateOgImage,\n size as ogSize,\n contentType as ogContentType,\n} from \"@/lib/og/og-image\";\n\nexport const runtime = \"nodejs\";\nexport const alt = \"Tool UI - Code Diff\";\nexport const size = ogSize;\nexport const contentType = ogContentType;\n\nexport default async function Image() {\n return generateOgImage(\n \"Code Diff\",\n \"Compare code changes with syntax-highlighted diffs\",\n );\n}\n" }, { "path": "apps/www/app/docs/code-diff/page.tsx", "content": "import type { Metadata } from \"next\";\nimport Content from \"./content.mdx\";\nimport { ComponentDocsTabs } from \"../_components/component-docs-tabs\";\n\nexport const metadata: Metadata = {\n title: \"Code Diff\",\n description: \"Compare code changes with syntax-highlighted diffs\",\n};\n\nexport const revalidate = 3600;\n\nexport default function CodeDiffDocsPage() {\n return } componentId=\"code-diff\" />;\n}\n" }, { "path": "apps/www/app/docs/data-table/content.mdx", "content": "import { DocsHeader } from \"../_components/docs-header\";\nimport { DataTable } from \"@/components/tool-ui/data-table\";\nimport { FormatInlineExample } from \"./formatting-gallery\";\nimport {\n NumberValue,\n CurrencyValue,\n PercentValue,\n DeltaValue,\n DateValue,\n BooleanValue,\n LinkValue,\n BadgeValue,\n StatusBadge,\n ArrayValue,\n} from \"@/components/tool-ui/data-table\";\n\n\n\nSearch results, issue lists, transaction logs: the assistant surfaces tabular data constantly. DataTable renders those rows as a sortable table on desktop and stacked cards on mobile. You define columns with declarative formatting configs for currency, dates, status badges, and links. No raw JSON, no custom table from scratch.\n\n**Role:** Information. For displaying data the user reads. See [Design Guidelines](/docs/design-guidelines) for how component roles work.\n\n## Getting Started\n\n\n\n\n\nRun this once from your project root.\n\n\n\n\n\n\n\nRender `DataTable` in your UI with tool-compatible props.\n\n
\n\n```tsx\nimport { DataTable, type Column } from \"@/components/tool-ui/data-table\";\n\ntype Row = {\n id: string;\n issue: string;\n priority: \"high\" | \"medium\" | \"low\";\n createdAt: string;\n amount: number;\n};\n\nconst columns: Column[] = [\n { key: \"issue\", label: \"Issue\", priority: \"primary\", truncate: true },\n {\n key: \"priority\",\n label: \"Urgency\",\n format: {\n kind: \"status\",\n statusMap: {\n high: { tone: \"danger\", label: \"High\" },\n medium: { tone: \"warning\", label: \"Medium\" },\n low: { tone: \"neutral\", label: \"Low\" },\n },\n },\n },\n {\n key: \"createdAt\",\n label: \"Created\",\n format: { kind: \"date\", dateFormat: \"relative\" },\n },\n {\n key: \"amount\",\n label: \"Amount\",\n align: \"right\",\n format: { kind: \"currency\", currency: \"USD\", decimals: 2 },\n },\n];\n\nconst data: Row[] = [\n {\n id: \"1\",\n issue: \"Payment failing on checkout\",\n priority: \"high\",\n createdAt: \"2025-11-11T09:24:00Z\",\n amount: 129.99,\n },\n {\n id: \"2\",\n issue: \"Billing UI alignment bug\",\n priority: \"medium\",\n createdAt: \"2025-11-10T17:03:00Z\",\n amount: 42,\n },\n {\n id: \"3\",\n issue: \"Export CSV missing headers\",\n priority: \"low\",\n createdAt: \"2025-11-08T08:00:00Z\",\n amount: 0,\n },\n {\n id: \"4\",\n issue: \"Webhook retries inconsistent\",\n priority: \"high\",\n createdAt: \"2025-11-13T22:15:00Z\",\n amount: 527.5,\n },\n];\n\nexport default function Example() {\n return (\n \n );\n}\n```\n\n
\n\n\n\n\n\nRegister this renderer so tool results display as `DataTable`.\n\n```tsx\n// Backend tool\nimport { tool, jsonSchema } from \"ai\";\n\nconst searchProducts = tool({\n description: \"Search products and return results in a table\",\n inputSchema: jsonSchema<{ query: string }>({\n type: \"object\",\n properties: { query: { type: \"string\" } },\n required: [\"query\"],\n additionalProperties: false,\n }),\n async execute({ query }) {\n const results = await db.products.search(query);\n return {\n id: \"data-table-search-products\",\n columns: [\n { key: \"name\", label: \"Product\", priority: \"primary\" },\n {\n key: \"price\",\n label: \"Price\",\n format: { kind: \"currency\", currency: \"USD\" },\n },\n { key: \"stock\", label: \"Stock\", align: \"right\" },\n ],\n data: results.map((p) => ({\n id: p.id,\n name: p.name,\n price: p.price,\n stock: p.stock,\n })),\n };\n },\n});\n\n// Frontend with assistant-ui\nimport { type Toolkit } from \"@assistant-ui/react\";\nimport { DataTable } from \"@/components/tool-ui/data-table\";\nimport { safeParseSerializableDataTable } from \"@/components/tool-ui/data-table/schema\";\n\nexport const toolkit: Toolkit = {\n searchProducts: {\n type: \"backend\",\n render: ({ result }) => {\n const parsed = safeParseSerializableDataTable(result);\n if (!parsed) {\n return null;\n }\n return ;\n },\n },\n};\n```\n\n\n\n\n\n## Key Features\n\n\n \n Table on desktop, stacked cards on mobile\n \n \n Tri-state column headers: none, ascending, descending\n \n \n Currency, dates, links, badges, and status pills via column config\n \n \n Compose action buttons below the table\n \n\n\n## Layout Variants\n\nUse explicit components when you want to force a layout:\n\n- `` (default): responsive auto layout\n- ``: always render the table view\n- ``: always render the card view\n\n```tsx\nimport { DataTable } from \"@/components/tool-ui/data-table\";\n```\n\n## Props\n\n### Core\n\n\n\n### Column Options\n\n\n\n### Sorting\n\n void\" },\n }}\n/>\n\n### External Actions\n\nUse [`ToolUI.LocalActions`](/docs/actions) to compose surface-level actions below `DataTable`.\n\n## Formatting\n\nAll visual formatting for data stays declarative via `columns[i].format`. Keep row values as primitives and describe presentation through format configs.\n\n\n }\n />\n ),\n type: \"{ kind: 'number', decimals?: number, unit?: string, compact?: boolean, showSign?: boolean }\",\n },\n currency: {\n description: (\n \n }\n />\n ),\n type: \"{ kind: 'currency', currency: string, decimals?: number }\",\n },\n percent: {\n description: (\n <>\n \n }\n />\n \n }\n />\n \n ),\n type: \"{ kind: 'percent', basis: 'fraction' | 'unit', decimals?: number, showSign?: boolean }\",\n },\n delta: {\n description: (\n <>\n \n }\n />\n \n }\n />\n \n ),\n type: \"{ kind: 'delta', decimals?: number, upIsPositive?: boolean, showSign?: boolean }\",\n },\n date: {\n description: (\n <>\n \n }\n />\n \n }\n note=\"Long date with locale\"\n />\n \n ),\n type: \"{ kind: 'date', dateFormat?: 'short' | 'long' | 'relative' }\",\n },\n boolean: {\n description: (\n \n }\n />\n ),\n type: \"{ kind: 'boolean', labels?: { true: string; false: string } }\",\n },\n link: {\n description: (\n <>\n \n }\n />\n \n }\n />\n \n ),\n type: \"{ kind: 'link', hrefKey?: string, external?: boolean }\",\n },\n badge: {\n description: (\n \n }\n />\n ),\n type: \"{ kind: 'badge', colorMap?: Record }\",\n },\n status: {\n description: (\n \n }\n />\n ),\n type: \"{ kind: 'status', statusMap: Record }\",\n },\n array: {\n description: (\n \n }\n />\n ),\n type: \"{ kind: 'array', maxVisible?: number }\",\n },\n }}\n/>\n\n## Accessibility\n\n- Uses semantic `` markup with proper header associations\n- Sortable columns are keyboard-accessible via shadcn/ui Button\n- Sort changes are announced via `aria-live` for assistive technologies\n\n## Related\n\n- [Item Carousel](/docs/item-carousel): horizontal browsing for collection display\n" }, { "path": "apps/www/app/docs/data-table/formatting-gallery.tsx", "content": "\"use client\";\n\nimport * as React from \"react\";\nimport {\n renderFormattedValue,\n type FormatConfig,\n} from \"@/components/tool-ui/data-table\";\n\ntype Row = Record<\n string,\n string | number | boolean | null | (string | number | boolean | null)[]\n>;\n\ninterface FormatSampleProps {\n title: string;\n value:\n | string\n | number\n | boolean\n | null\n | (string | number | boolean | null)[];\n format: FormatConfig;\n row?: Row;\n locale?: string;\n code?: string;\n note?: string;\n}\n\nfunction FormatSample({\n title,\n value,\n format,\n row,\n locale,\n code,\n note,\n}: FormatSampleProps) {\n const output = React.useMemo(() => {\n return renderFormattedValue({ value, column: { format }, row, locale });\n }, [value, format, row, locale]);\n\n const codeSnippet = code ?? `format: ${JSON.stringify(format, null, 2)}`;\n const inputSnippet = JSON.stringify(value);\n\n return (\n
\n
{title}
\n
\n
\n
Format
\n 
\n            {codeSnippet}\n
\n {note ? (\n
{note}
\n ) : null}\n
\n
\n
\n
Input value
\n
{inputSnippet}
\n
\n
\n
Rendered
\n
\n {output}\n
\n
\n
\n
\n
\n );\n}\n\nexport function FormattingGallery() {\n const nowIso = \"2025-01-05T12:00:00Z\";\n\n return (\n
\n {/* number */}\n \n \n\n {/* currency */}\n \n\n {/* percent */}\n \n \n\n {/* delta */}\n \n \n\n {/* date */}\n \n \n\n {/* boolean */}\n \n\n {/* link */}\n \n \n\n {/* badge */}\n \n\n {/* status */}\n \n\n {/* array */}\n \n
\n );\n}\n\nexport function FormatInlineExample({\n value,\n format,\n row,\n locale,\n note,\n output,\n}: {\n value:\n | string\n | number\n | boolean\n | null\n | (string | number | boolean | null)[];\n format?: FormatConfig;\n row?: Row;\n locale?: string;\n note?: string;\n output?: React.ReactNode;\n}) {\n const rendered = React.useMemo(() => {\n if (output) return output;\n if (format)\n return renderFormattedValue({ value, column: { format }, row, locale });\n return String(value ?? \"\");\n }, [value, format, row, locale, output]);\n\n return (\n
\n
\n
\n Input{\" \"}\n {JSON.stringify(value)}\n
\n
\n Output{\" \"}\n \n {rendered}\n \n
\n
\n {note ? (\n
{note}
\n ) : null}\n
\n );\n}\n" }, { "path": "apps/www/app/docs/data-table/opengraph-image.tsx", "content": "import {\n generateOgImage,\n size as ogSize,\n contentType as ogContentType,\n} from \"@/lib/og/og-image\";\n\nexport const runtime = \"nodejs\";\nexport const alt = \"Tool UI - Data Table\";\nexport const size = ogSize;\nexport const contentType = ogContentType;\n\nexport default async function Image() {\n return generateOgImage(\n \"Data Table\",\n \"Present structured data in sortable tables\",\n );\n}\n" }, { "path": "apps/www/app/docs/data-table/page.tsx", "content": "import type { Metadata } from \"next\";\nimport Content from \"./content.mdx\";\nimport { ComponentDocsTabs } from \"../_components/component-docs-tabs\";\n\nexport const metadata: Metadata = {\n title: \"Data Table\",\n description: \"Present structured data in sortable tables\",\n};\n\nexport const revalidate = 3600;\n\nexport default function DataTableDocsPage() {\n return } componentId=\"data-table\" />;\n}\n" }, { "path": "apps/www/app/docs/data-table/tasks-demo.tsx", "content": "\"use client\";\n\nimport {\n Column,\n DataTable,\n DataTableRowData,\n} from \"@/components/tool-ui/data-table\";\nimport { getMockTasks } from \"@/lib/mocks/tasks\";\nimport { useEffect, useState } from \"react\";\n\nexport function TasksDemo() {\n const [rows, setRows] = useState(null);\n\n useEffect(() => {\n getMockTasks().then((tasks) => {\n setRows(\n tasks.map((t) => ({\n id: t.id,\n issue: t.issue,\n customer: t.customer,\n priority: t.priority,\n status: t.status,\n assignee: t.assignee,\n created: t.created,\n urgencyOrder:\n t.priority === \"high\" ? 1 : t.priority === \"medium\" ? 2 : 3,\n })),\n );\n });\n }, []);\n\n const columns = [\n {\n key: \"priority\",\n label: \"Urgency\",\n format: {\n kind: \"status\" as const,\n statusMap: {\n high: { tone: \"danger\", label: \"High\" },\n medium: { tone: \"warning\", label: \"Medium\" },\n low: { tone: \"neutral\", label: \"Low\" },\n },\n },\n },\n {\n key: \"issue\",\n label: \"Issue\",\n truncate: true,\n priority: \"primary\" as const,\n },\n { key: \"customer\", label: \"Customer\", priority: \"primary\" as const },\n {\n key: \"status\",\n label: \"Status\",\n format: {\n kind: \"badge\" as const,\n colorMap: {\n open: \"info\",\n \"in-progress\": \"warning\",\n waiting: \"neutral\",\n done: \"success\",\n },\n },\n },\n { key: \"assignee\", label: \"Owner\" },\n {\n key: \"created\",\n label: \"Created\",\n format: { kind: \"date\" as const, dateFormat: \"relative\" as const },\n hideOnMobile: true,\n },\n { key: \"urgencyOrder\", label: \"Order\", hideOnMobile: true },\n ] satisfies Column[];\n\n return (\n
\n \n
\n );\n}\n" }, { "path": "apps/www/app/docs/design-guidelines/content.mdx", "content": "import { DocsHeader } from \"../_components/docs-header\";\nimport { MockThread, MockMessage } from \"../_components/mock-thread\";\nimport { CollaborationDiagram } from \"../_components/collaboration-diagram\";\nimport { DataTable } from \"@/components/tool-ui/data-table\";\n\n\n\n## The Collaboration Model\n\nIn AI chat, users interact with both the assistant and any tool UIs it renders. Most tool UIs treat this as incidental — a tool UI appears, the user clicks, done. That undersells what's happening. The assistant, the tool UI, and the user form a collaborative triad.\n\n\n\nThe assistant gives context and narration. The tool UI gives structure that prose cannot — sortable tables, controls, media. They work together.\n\n
\n \n \n find a good auth library for React\n \n \n \n Found 8 React auth libraries on GitHub. Here are the top results by\n recent activity:\n \n
\n \n
\n \n \n \n Which one would you recommend for a Next.js app?\n \n \n \n \n I recommend next-auth. It's purpose-built for Next.js,\n has by far the most stars, and was updated most recently. Want me to\n show you setup instructions?\n \n \n \n
\n\nThe assistant introduces the tool UI, the user scans it and asks a follow-up, the assistant answers by referencing specific rows. This is the triadic loop.\n\n## Roles\n\nEvery Tool UI has a job:\n\n- **Information** — Display data. Users read more than they click. Examples: [Data Table](/docs/data-table), [Chart](/docs/chart), [Link Preview](/docs/link-preview).\n\n- **Decision** — For choices that matter (approve/reject, send/cancel). Show clear options and [receipts](/docs/receipts) that confirm what happened. Examples: [Approval Card](/docs/approval-card), [Option List](/docs/option-list).\n\n- **Control** — Adjust parameters without commitment (filters, sort orders, date ranges). Changes are reversible. Examples: [Parameter Slider](/docs/parameter-slider), [Preferences Panel](/docs/preferences-panel).\n\n- **State** — Show internal activity (progress indicators, status logs, loading states). Examples: [Progress Tracker](/docs/progress-tracker), [Terminal](/docs/terminal).\n\nSome tool UIs combine roles. A data table with row actions is \"information with control.\" When combining, pick one role to lead.\n\n## Constraints\n\nTool UIs live in chat: narrow widths, variable heights, mixed with prose.\n\n- **Vertical:** Communicate purpose within the first 300px or so.\n- **Horizontal:** Expect 400–600px. Prefer single-column layouts.\n- **Touch:** Interactive elements need at least 44×44px tap area.\n- **Choices:** Limit visible options to 5–7. The assistant can offer to show more.\n\n## Addressability\n\nIf the assistant can't point at something later, you lose half the value of rendering it.\n\n- **`id`**: Identifies this specific tool UI in the conversation (\"the preview above\", \"that table\").\n- **`assetId` / row IDs / option IDs**: Identify real objects (\"that link\", \"row 4\", \"the merge option\").\n\nUse stable IDs from your backend — database IDs, canonical URLs — not array indexes or render-time UUIDs. Anything the user can act on should have an ID the assistant can cite.\n\n## Anti-Patterns\n\n- **Input fields:** Input fields compete with the main chat composer. Ask whether the assistant could gather that information through conversation, or link to a form outside the chat.\n- **Hidden mutations:** Actions that change state should show what happened. Terminal decisions need a receipt showing what the user chose.\n- **Kitchen sinks:** If it needs tabs or navigation, consider breaking it into separate Tool UIs.\n- **Uncontextualized tool UIs:** Always have the assistant introduce a tool UI and explain what it shows.\n- **Redundant narration:** The assistant shouldn't describe what the tool UI already shows. The tool UI shouldn't echo what the assistant just said. If the assistant asks \"Where to?\", the tool UI doesn't need a header saying \"Where to?\" — just show the options. Divide the work between them: the assistant gives context, the tool UI gives structure.\n\n## Further reading\n\n- [**Overview**](/docs/overview): What Tool UI is and how schema-first rendering works\n- [**Actions**](/docs/actions): The local vs. decision action model in detail\n- [**Receipts**](/docs/receipts): How to show durable records of user decisions\n- [**Gallery**](/docs/gallery): Browse all available components\n" }, { "path": "apps/www/app/docs/design-guidelines/opengraph-image.tsx", "content": "import {\n generateOgImage,\n size as ogSize,\n contentType as ogContentType,\n} from \"@/lib/og/og-image\";\n\nexport const runtime = \"nodejs\";\nexport const alt = \"Tool UI - Design Guidelines\";\nexport const size = ogSize;\nexport const contentType = ogContentType;\n\nexport default async function Image() {\n return generateOgImage(\n \"Design Guidelines\",\n \"Principles for AI tool interfaces\",\n );\n}\n" }, { "path": "apps/www/app/docs/design-guidelines/page.tsx", "content": "import type { Metadata } from \"next\";\nimport Content from \"./content.mdx\";\nimport { DocsArticle } from \"../_components/docs-article\";\n\nexport const metadata: Metadata = {\n title: \"Design Guidelines\",\n description: \"Design principles and patterns for Tool UI components\",\n};\n\nexport const revalidate = 3600;\n\nexport default function DesignGuidelinesPage() {\n return (\n \n \n \n );\n}\n" }, { "path": "apps/www/app/docs/gallery/opengraph-image.tsx", "content": "import {\n generateOgImage,\n size as ogSize,\n contentType as ogContentType,\n} from \"@/lib/og/og-image\";\n\nexport const runtime = \"nodejs\";\nexport const alt = \"Tool UI - Gallery\";\nexport const size = ogSize;\nexport const contentType = ogContentType;\n\nexport default async function Image() {\n return generateOgImage(\"Gallery\", \"Browse all component examples\");\n}\n" }, { "path": "apps/www/app/docs/gallery/page.tsx", "content": "import type { Metadata } from \"next\";\nimport dynamic from \"next/dynamic\";\nimport type { ReactNode } from \"react\";\n\nimport {\n GalleryPageAnalytics,\n GalleryPreviewImpression,\n} from \"@/app/docs/_components/gallery-analytics.client\";\nimport { DocsBorderedShell } from \"@/app/docs/_components/docs-bordered-shell\";\nimport { GalleryCardHeader } from \"@/app/docs/_components/gallery-card-header\";\nimport { DataTable } from \"@/components/tool-ui/data-table\";\nimport { ItemCarousel } from \"@/components/tool-ui/item-carousel\";\nimport { OrderSummary } from \"@/components/tool-ui/order-summary\";\nimport { StatsDisplay } from \"@/components/tool-ui/stats-display\";\nimport { type GalleryComponentDocId } from \"@/lib/docs/gallery-component-docs\";\nimport {\n GALLERY_COLUMN_STACK_CLASS,\n GALLERY_DESKTOP_GRID_CLASS,\n GALLERY_LAYOUT_CLASS,\n GALLERY_MOBILE_STACK_CLASS,\n GALLERY_STANDARD_PREVIEW_WRAPPER_CLASS,\n} from \"@/lib/docs/gallery-layout\";\nimport { approvalCardPresets } from \"@/lib/presets/approval-card\";\nimport { audioPresets } from \"@/lib/presets/audio\";\nimport { chartPresets } from \"@/lib/presets/chart\";\nimport { citationPresets } from \"@/lib/presets/citation\";\nimport { codeBlockPresets } from \"@/lib/presets/code-block\";\nimport { codeDiffPresets } from \"@/lib/presets/code-diff\";\nimport { dataTablePresets } from \"@/lib/presets/data-table\";\nimport { geoMapPresets } from \"@/lib/presets/geo-map\";\nimport { instagramPostPresets } from \"@/lib/presets/instagram-post\";\nimport { imageGalleryPresets } from \"@/lib/presets/image-gallery\";\nimport { itemCarouselPresets } from \"@/lib/presets/item-carousel\";\nimport { linkPreviewPresets } from \"@/lib/presets/link-preview\";\nimport { linkedInPostPresets } from \"@/lib/presets/linkedin-post\";\nimport { messageDraftPresets } from \"@/lib/presets/message-draft\";\nimport { optionListPresets } from \"@/lib/presets/option-list\";\nimport { orderSummaryPresets } from \"@/lib/presets/order-summary\";\nimport { parameterSliderPresets } from \"@/lib/presets/parameter-slider\";\nimport { planPresets } from \"@/lib/presets/plan\";\nimport { preferencesPanelPresets } from \"@/lib/presets/preferences-panel\";\nimport { progressTrackerPresets } from \"@/lib/presets/progress-tracker\";\nimport { questionFlowPresets } from \"@/lib/presets/question-flow\";\nimport { statsDisplayPresets } from \"@/lib/presets/stats-display\";\nimport { terminalPresets } from \"@/lib/presets/terminal\";\nimport { weatherWidgetPresets } from \"@/lib/presets/weather-widget\";\nimport { xPostPresets } from \"@/lib/presets/x-post\";\nimport { cn } from \"@/lib/ui/cn\";\n\nconst ApprovalCard = dynamic(() =>\n import(\"@/components/tool-ui/approval-card\").then((m) => m.ApprovalCard),\n);\nconst CitationList = dynamic(() =>\n import(\"@/components/tool-ui/citation\").then((m) => m.CitationList),\n);\nconst ImageGallery = dynamic(() =>\n import(\"@/components/tool-ui/image-gallery\").then((m) => m.ImageGallery),\n);\nconst Audio = dynamic(() =>\n import(\"@/components/tool-ui/audio\").then((m) => m.Audio),\n);\nconst LinkPreview = dynamic(() =>\n import(\"@/components/tool-ui/link-preview\").then((m) => m.LinkPreview),\n);\nconst LinkedInPost = dynamic(() =>\n import(\"@/components/tool-ui/linkedin-post\").then((m) => m.LinkedInPost),\n);\nconst InstagramPost = dynamic(() =>\n import(\"@/components/tool-ui/instagram-post\").then((m) => m.InstagramPost),\n);\nconst OptionList = dynamic(() =>\n import(\"@/components/tool-ui/option-list\").then((m) => m.OptionList),\n);\nconst ParameterSlider = dynamic(() =>\n import(\"@/components/tool-ui/parameter-slider\").then(\n (m) => m.ParameterSlider,\n ),\n);\nconst Plan = dynamic(() =>\n import(\"@/components/tool-ui/plan\").then((m) => m.Plan),\n);\nconst Terminal = dynamic(() =>\n import(\"@/components/tool-ui/terminal\").then((m) => m.Terminal),\n);\nconst CodeBlock = dynamic(() =>\n import(\"@/components/tool-ui/code-block\").then((m) => m.CodeBlock),\n);\nconst CodeDiff = dynamic(() =>\n import(\"@/components/tool-ui/code-diff\").then((m) => m.CodeDiff),\n);\nconst Chart = dynamic(() =>\n import(\"@/components/tool-ui/chart\").then((m) => m.Chart),\n);\nconst GeoMap = dynamic(() =>\n import(\"@/components/tool-ui/geo-map\").then((m) => m.GeoMap),\n);\nconst PreferencesPanel = dynamic(() =>\n import(\"@/components/tool-ui/preferences-panel\").then(\n (m) => m.PreferencesPanel,\n ),\n);\nconst ProgressTracker = dynamic(() =>\n import(\"@/components/tool-ui/progress-tracker\").then(\n (m) => m.ProgressTracker,\n ),\n);\nconst QuestionFlow = dynamic(() =>\n import(\"@/components/tool-ui/question-flow\").then((m) => m.QuestionFlow),\n);\nconst MessageDraft = dynamic(() =>\n import(\"@/components/tool-ui/message-draft\").then((m) => m.MessageDraft),\n);\nconst XPost = dynamic(() =>\n import(\"@/components/tool-ui/x-post\").then((m) => m.XPost),\n);\nconst WeatherWidget = dynamic(() =>\n import(\"@/components/tool-ui/weather-widget/runtime\").then(\n (m) => m.WeatherWidget,\n ),\n);\n\nexport const metadata: Metadata = {\n title: \"Gallery\",\n description: \"Browse all Tool UI components in a visual gallery\",\n};\n\nexport const revalidate = 3600;\n\ninterface GalleryPreviewCardProps {\n componentId: GalleryComponentDocId;\n className?: string;\n children: ReactNode;\n}\n\ninterface GalleryCardConfig {\n componentId: GalleryComponentDocId;\n className: string;\n render: () => ReactNode;\n}\n\nfunction GalleryPreviewCard({\n componentId,\n className,\n children,\n}: GalleryPreviewCardProps) {\n return (\n \n \n \n {children}\n \n );\n}\n\nexport default function ComponentsGalleryPage() {\n const standardPreviewWidthClass = \"w-full max-w-[680px]\";\n const withStandardPreviewWidth = (node: ReactNode) => (\n
{node}
\n );\n\n const galleryCards: GalleryCardConfig[] = [\n {\n componentId: \"option-list\",\n className: \"mb-5 flex break-inside-avoid justify-center 2xl:mb-5\",\n render: () => (\n \n ),\n },\n {\n componentId: \"question-flow\",\n className: \"mb-5 flex break-inside-avoid justify-center 2xl:mb-5\",\n render: () =>\n withStandardPreviewWidth(\n ,\n ),\n },\n {\n componentId: \"plan\",\n className: \"mb-5 flex break-inside-avoid justify-center 2xl:mb-5\",\n render: () =>\n withStandardPreviewWidth(),\n },\n {\n componentId: \"order-summary\",\n className: \"mb-5 break-inside-avoid 2xl:mb-5\",\n render: () => (\n \n ),\n },\n {\n componentId: \"item-carousel\",\n className: \"mb-5 flex justify-center 2xl:col-span-full 2xl:mb-5\",\n render: () => (\n
\n \n
\n ),\n },\n {\n componentId: \"data-table\",\n className: \"mb-5 flex justify-center 2xl:col-span-full 2xl:mb-5\",\n render: () => (\n
\n \n
\n ),\n },\n {\n componentId: \"code-diff\",\n className: \"mb-5 flex break-inside-avoid justify-center 2xl:mb-5\",\n render: () => ,\n },\n {\n componentId: \"stats-display\",\n className: \"mb-5 flex break-inside-avoid justify-center 2xl:mb-5\",\n render: () => (\n \n ),\n },\n {\n componentId: \"weather-widget\",\n className: \"mb-5 flex break-inside-avoid justify-center 2xl:mb-5\",\n render: () => (\n \n ),\n },\n {\n componentId: \"image-gallery\",\n className: \"mb-5 flex break-inside-avoid justify-center 2xl:mb-5\",\n render: () => (\n \n ),\n },\n {\n componentId: \"geo-map\",\n className: \"mb-5 flex break-inside-avoid justify-center 2xl:mb-5\",\n render: () => (\n \n ),\n },\n {\n componentId: \"link-preview\",\n className: \"mb-5 flex break-inside-avoid justify-center 2xl:mb-5\",\n render: () => (\n \n ),\n },\n {\n componentId: \"citation\",\n className: \"mb-5 flex break-inside-avoid justify-center 2xl:mb-5\",\n render: () => (\n \n ),\n },\n {\n componentId: \"audio\",\n className: \"mb-5 flex break-inside-avoid justify-center 2xl:mb-5\",\n render: () =>
\n \n \n \n \n \n \n \n \n \n {metrics.map((metric) => (\n \n \n \n \n \n \n ))}\n \n
MetricUntunedTunedDelta
\n {metric.label}\n \n {formatValue(metric.untuned)}\n \n {formatValue(metric.tuned)}\n \n {formatDelta(metric.tuned, metric.untuned)}\n
\n \n \n \n );\n}\n" }, { "path": "apps/www/app/sandbox/weather-widget-production/runtime-input.ts", "content": "import type {\n PrecipitationLevel,\n WeatherConditionCode,\n} from \"@/components/tool-ui/weather-widget/runtime\";\nimport { snapTimeOfDayToNearestCheckpoint } from \"@/components/tool-ui/weather-widget/generated/weather-runtime-core.generated\";\n\nexport interface ProductionHarnessRuntimeInput {\n conditionCode: WeatherConditionCode;\n windSpeed: number;\n precipitationLevel: PrecipitationLevel;\n visibility: number;\n timestamp: string;\n timeOfDay: number;\n}\n\nexport function createProductionHarnessRuntimeInput(\n input: ProductionHarnessRuntimeInput,\n): ProductionHarnessRuntimeInput {\n return {\n ...input,\n timeOfDay: snapTimeOfDayToNearestCheckpoint(input.timeOfDay),\n };\n}\n" }, { "path": "apps/www/app/sandbox/weather-widget-stress/page.tsx", "content": "\"use client\";\n\nimport { useEffect, useMemo, useRef, useState, type ReactNode } from \"react\";\nimport { Leva, useControls, button } from \"leva\";\nimport {\n WeatherWidget,\n ForecastDay,\n PrecipitationLevel,\n TemperatureUnit,\n WeatherConditionCode,\n} from \"@/components/tool-ui/weather-widget/runtime\";\nimport { cn } from \"@/lib/ui/cn\";\n\nconst CONDITIONS: WeatherConditionCode[] = [\n \"clear\",\n \"partly-cloudy\",\n \"cloudy\",\n \"overcast\",\n \"fog\",\n \"drizzle\",\n \"rain\",\n \"heavy-rain\",\n \"thunderstorm\",\n \"snow\",\n \"sleet\",\n \"hail\",\n \"windy\",\n];\n\nconst WEBGL_SAFE_WIDGET_COUNT = 8;\n\n// A representative subset that exercises the major effect pathways:\n// - clouds, fog, rain, heavy rain, lightning, snow\nconst CONDITION_SPECTRUM: WeatherConditionCode[] = [\n \"clear\",\n \"partly-cloudy\",\n \"overcast\",\n \"fog\",\n \"rain\",\n \"heavy-rain\",\n \"thunderstorm\",\n \"snow\",\n];\n\nconst CITIES = [\n { location: \"San Diego, CA\", conditionCode: \"clear\" as const },\n { location: \"Seattle, WA\", conditionCode: \"rain\" as const },\n { location: \"London, UK\", conditionCode: \"fog\" as const },\n { location: \"Minneapolis, MN\", conditionCode: \"snow\" as const },\n { location: \"Kansas City, MO\", conditionCode: \"thunderstorm\" as const },\n { location: \"Chicago, IL\", conditionCode: \"windy\" as const },\n { location: \"Bangkok, Thailand\", conditionCode: \"heavy-rain\" as const },\n { location: \"Reykjavik, Iceland\", conditionCode: \"sleet\" as const },\n { location: \"Denver, CO\", conditionCode: \"partly-cloudy\" as const },\n { location: \"San Francisco, CA\", conditionCode: \"cloudy\" as const },\n];\n\nconst WEEKDAYS = [\"Mon\", \"Tue\", \"Wed\", \"Thu\", \"Fri\", \"Sat\", \"Sun\"] as const;\n\nfunction clamp(value: number, min: number, max: number): number {\n return Math.max(min, Math.min(max, value));\n}\n\nfunction mulberry32(seed: number): () => number {\n let a = seed >>> 0;\n return () => {\n a += 0x6d2b79f5;\n let t = a;\n t = Math.imul(t ^ (t >>> 15), t | 1);\n t ^= t + Math.imul(t ^ (t >>> 7), t | 61);\n return ((t ^ (t >>> 14)) >>> 0) / 4294967296;\n };\n}\n\nfunction pick(rand: () => number, items: readonly T[]): T {\n return items[Math.floor(rand() * items.length)]!;\n}\n\nfunction timeToISOString(timeOfDay: number): string {\n const totalMinutes = timeOfDay * 24 * 60;\n const hours = Math.floor(totalMinutes / 60);\n const minutes = Math.round(totalMinutes % 60);\n const now = new Date();\n // Keep this aligned with `getTimeOfDay`, which interprets timestamps in UTC.\n now.setUTCHours(hours, minutes, 0, 0);\n return now.toISOString();\n}\n\nfunction baseTempForCondition(\n conditionCode: WeatherConditionCode,\n unit: TemperatureUnit,\n): number {\n const f: Record = {\n clear: 78,\n \"partly-cloudy\": 70,\n cloudy: 62,\n overcast: 58,\n fog: 54,\n drizzle: 52,\n rain: 50,\n \"heavy-rain\": 47,\n thunderstorm: 72,\n snow: 18,\n sleet: 34,\n hail: 38,\n windy: 45,\n };\n const tempF = f[conditionCode] ?? 65;\n if (unit === \"fahrenheit\") return tempF;\n return Math.round(((tempF - 32) * 5) / 9);\n}\n\nfunction precipitationForCondition(\n conditionCode: WeatherConditionCode,\n): PrecipitationLevel | undefined {\n switch (conditionCode) {\n case \"drizzle\":\n return \"light\";\n case \"rain\":\n return \"moderate\";\n case \"heavy-rain\":\n case \"thunderstorm\":\n return \"heavy\";\n case \"snow\":\n case \"sleet\":\n case \"hail\":\n return \"moderate\";\n default:\n return \"none\";\n }\n}\n\nfunction buildForecast(\n rand: () => number,\n conditionCode: WeatherConditionCode,\n unit: TemperatureUnit,\n): ForecastDay[] {\n const base = baseTempForCondition(conditionCode, unit);\n const start = Math.floor(rand() * WEEKDAYS.length);\n\n return Array.from({ length: 7 })\n .slice(0, 7)\n .map((_, i) => {\n const day = WEEKDAYS[(start + i) % WEEKDAYS.length]!;\n const hi = base + Math.round((rand() - 0.4) * 10);\n const lo = hi - (3 + Math.round(rand() * 8));\n const maybeCondition = i === 0 ? conditionCode : pick(rand, CONDITIONS);\n return {\n label: day,\n tempMin: lo,\n tempMax: hi,\n conditionCode: maybeCondition,\n };\n });\n}\n\nexport default function WeatherWidgetStressPage() {\n const [remountSeed, setRemountSeed] = useState(0);\n\n const [stress] = useControls(\"Stress\", () => ({\n count: {\n value: WEBGL_SAFE_WIDGET_COUNT,\n min: 1,\n max: WEBGL_SAFE_WIDGET_COUNT,\n step: 1,\n label: \"WebGL widgets\",\n },\n columns: { value: 4, min: 1, max: 6, step: 1 },\n fillCells: { value: true, label: \"Fill grid cells\" },\n remountAll: button(() => setRemountSeed((s) => s + 1)),\n autoRemount: { value: false, label: \"Auto-remount\" },\n autoRemountSeconds: {\n value: 5,\n min: 1,\n max: 30,\n step: 1,\n label: \"Auto-remount (s)\",\n },\n }));\n\n const [timeControls, setTimeControls] = useControls(\"Time\", () => ({\n timeOfDay: { value: 0.5, min: 0, max: 1, step: 0.001 },\n animate: { value: false, label: \"Animate time\" },\n speed: {\n value: 0.03,\n min: 0.001,\n max: 0.2,\n step: 0.001,\n label: \"Speed (Δ/second)\",\n },\n }));\n\n const [effectsControls] = useControls(\"Effects\", () => ({\n enabled: { value: true },\n reducedMotion: { value: false, label: \"Reduced motion\" },\n quality: {\n value: \"auto\" as const,\n options: [\"low\", \"medium\", \"high\", \"auto\"] as const,\n },\n }));\n\n const [dataControls] = useControls(\"Data\", () => ({\n includeUpdatedAt: { value: true },\n includeExtras: { value: true },\n unit: {\n value: \"fahrenheit\" as const,\n options: [\"fahrenheit\", \"celsius\"] as const,\n },\n }));\n\n const timeOfDayRef = useRef(timeControls.timeOfDay);\n useEffect(() => {\n timeOfDayRef.current = timeControls.timeOfDay;\n }, [timeControls.timeOfDay]);\n\n useEffect(() => {\n if (!timeControls.animate) return;\n\n const intervalMs = 120;\n const id = window.setInterval(() => {\n const next =\n (timeOfDayRef.current + timeControls.speed * (intervalMs / 1000)) % 1;\n timeOfDayRef.current = next;\n setTimeControls({ timeOfDay: next });\n }, intervalMs);\n\n return () => window.clearInterval(id);\n }, [setTimeControls, timeControls.animate, timeControls.speed]);\n\n useEffect(() => {\n if (!stress.autoRemount) return;\n const id = window.setInterval(\n () => setRemountSeed((s) => s + 1),\n stress.autoRemountSeconds * 1000,\n );\n return () => window.clearInterval(id);\n }, [stress.autoRemount, stress.autoRemountSeconds]);\n\n const timestamp = useMemo(\n () => timeToISOString(timeControls.timeOfDay),\n [timeControls.timeOfDay],\n );\n\n const globalEffects = useMemo(() => {\n return {\n enabled: effectsControls.enabled,\n reducedMotion: effectsControls.reducedMotion,\n quality: effectsControls.quality,\n } as const;\n }, [\n effectsControls.enabled,\n effectsControls.quality,\n effectsControls.reducedMotion,\n ]);\n\n const gridItems = useMemo(() => {\n const items: Array<{\n key: string;\n widget: ReactNode;\n label: string;\n }> = [];\n\n for (let i = 0; i < stress.count; i++) {\n const rand = mulberry32(remountSeed * 100_000 + i * 9973 + 42);\n\n const city = CITIES[i % CITIES.length]!;\n const unit = dataControls.unit;\n\n const condition = CONDITION_SPECTRUM[i % CONDITION_SPECTRUM.length]!;\n const baseTemp = baseTempForCondition(condition, unit);\n const includeUpdatedAt = dataControls.includeUpdatedAt;\n const includeExtras = dataControls.includeExtras;\n const location = city.location;\n\n const currentTemp = baseTemp + Math.round((rand() - 0.5) * 8);\n const tempMax = currentTemp + (2 + Math.round(rand() * 6));\n const tempMin = currentTemp - (2 + Math.round(rand() * 8));\n\n const precipitation = precipitationForCondition(condition);\n\n const current = {\n temperature: currentTemp,\n tempMin,\n tempMax,\n conditionCode: condition,\n ...(includeExtras\n ? {\n windSpeed:\n condition === \"windy\"\n ? Math.round(15 + rand() * 25)\n : Math.round(rand() * 20),\n precipitationLevel: precipitation,\n visibility:\n condition === \"fog\"\n ? clamp(0.5 + rand() * 2.5, 0.1, 10)\n : clamp(3 + rand() * 10, 0.1, 15),\n }\n : {}),\n };\n\n const forecast = buildForecast(rand, condition, unit).slice(0, 7);\n\n const widget = (\n \n );\n\n items.push({\n key: `${remountSeed}-${i}`,\n widget,\n label: condition,\n });\n }\n\n return items;\n }, [\n dataControls.includeExtras,\n dataControls.includeUpdatedAt,\n dataControls.unit,\n globalEffects,\n remountSeed,\n stress.count,\n stress.fillCells,\n timeControls.timeOfDay,\n timestamp,\n ]);\n\n return (\n
\n \n\n
\n
\n

\n Weather Widget Stress Lab\n

\n

\n WebGL-safe sampler for the shipping weather effects. It renders a\n small set of representative conditions so you can scrub time of day\n globally and spot visual/correctness issues quickly.\n

\n
\n Note: Effects use{\" \"}\n WebGL2, and\n browsers cap how many WebGL contexts can be active. This page\n intentionally caps the sampler grid to{\" \"}\n \n {WEBGL_SAFE_WIDGET_COUNT}\n {\" \"}\n widgets so every card can render effects without falling back.\n
\n
\n \n Widgets:{\" \"}\n {stress.count}\n \n \n Columns:{\" \"}\n {stress.columns}\n \n \n Time:{\" \"}\n \n {timeControls.timeOfDay.toFixed(3)}\n \n \n \n Effects:{\" \"}\n \n {effectsControls.enabled ? \"on\" : \"off\"}\n \n \n \n Reduced motion:{\" \"}\n \n {effectsControls.reducedMotion ? \"on\" : \"off\"}\n \n \n \n Quality:{\" \"}\n \n {effectsControls.quality}\n \n \n
\n
\n\n
\n
\n

\n WebGL-safe condition sampler\n

\n
\n Tip:\n \n Adjust time of day to preview all conditions at the same moment.\n \n
\n
\n\n \n {gridItems.map((item) => (\n
\n
\n {item.label}\n
\n {item.widget}\n
\n ))}\n
\n \n
\n \n );\n}\n" }, { "path": "apps/www/app/staging/_components/rounded-rect-overlay.tsx", "content": "\"use client\";\n\nimport { cn } from \"@/lib/ui/cn\";\n\ninterface RoundedRectOverlayProps {\n rect: DOMRect;\n containerRect: DOMRect;\n padding?: number;\n paddingOuter?: number; // Padding on outer-facing side (overrides padding on that side)\n color: \"blue\" | \"green\" | \"orange\";\n showMargin?: boolean;\n marginSize?: number;\n marginSizeOuter?: number; // Margin on outer-facing side (overrides marginSize on that side)\n label?: string;\n outerEdgeRadiusFactor?: number; // Factor to reduce radius on outer-facing edge (0-1)\n isLeftAligned?: boolean; // If true, left side is outer-facing; if false, right side is outer-facing\n}\n\nconst COLOR_STYLES = {\n blue: {\n border: \"border-blue-500\",\n bg: \"bg-blue-500/10\",\n marginBorder: \"border-blue-400/50\",\n marginBg: \"bg-blue-400/5\",\n text: \"text-blue-600 dark:text-blue-400\",\n },\n green: {\n border: \"border-emerald-500\",\n bg: \"bg-emerald-500/10\",\n marginBorder: \"border-emerald-400/50\",\n marginBg: \"bg-emerald-400/5\",\n text: \"text-emerald-600 dark:text-emerald-400\",\n },\n orange: {\n border: \"border-orange-500\",\n bg: \"bg-orange-500/10\",\n marginBorder: \"border-orange-400/50\",\n marginBg: \"bg-orange-400/5\",\n text: \"text-orange-600 dark:text-orange-400\",\n },\n};\n\nexport function RoundedRectOverlay({\n rect,\n containerRect,\n padding = 6,\n paddingOuter,\n color,\n showMargin = false,\n marginSize = 16,\n marginSizeOuter,\n label,\n outerEdgeRadiusFactor = 1,\n isLeftAligned = true,\n}: RoundedRectOverlayProps) {\n const styles = COLOR_STYLES[color];\n\n // Asymmetric padding: outer-facing side uses paddingOuter if provided\n const paddingLeft = isLeftAligned ? (paddingOuter ?? padding) : padding;\n const paddingRight = isLeftAligned ? padding : (paddingOuter ?? padding);\n\n // Calculate position relative to container\n const left = rect.left - containerRect.left - paddingLeft;\n const top = rect.top - containerRect.top - padding;\n const width = rect.width + paddingLeft + paddingRight;\n const height = rect.height + padding * 2;\n const fullRadius = height / 2;\n const reducedRadius = fullRadius * outerEdgeRadiusFactor;\n\n // Asymmetric radii: smaller on outer-facing side\n const radiusLeft = isLeftAligned ? reducedRadius : fullRadius;\n const radiusRight = isLeftAligned ? fullRadius : reducedRadius;\n const borderRadius = `${radiusLeft}px ${radiusRight}px ${radiusRight}px ${radiusLeft}px`;\n\n // Asymmetric margin: outer-facing side uses marginSizeOuter if provided\n const marginLeft_ = isLeftAligned\n ? (marginSizeOuter ?? marginSize)\n : marginSize;\n const marginRight_ = isLeftAligned\n ? marginSize\n : (marginSizeOuter ?? marginSize);\n\n // Margin overlay dimensions\n const marginLeftPos = left - marginLeft_;\n const marginTop = top - marginSize;\n const marginWidth = width + marginLeft_ + marginRight_;\n const marginHeight = height + marginSize * 2;\n const marginFullRadius = marginHeight / 2;\n const marginReducedRadius = marginFullRadius * outerEdgeRadiusFactor;\n const marginRadiusLeft = isLeftAligned\n ? marginReducedRadius\n : marginFullRadius;\n const marginRadiusRight = isLeftAligned\n ? marginFullRadius\n : marginReducedRadius;\n const marginBorderRadius = `${marginRadiusLeft}px ${marginRadiusRight}px ${marginRadiusRight}px ${marginRadiusLeft}px`;\n\n return (\n <>\n {showMargin && (\n \n )}\n \n {label && (\n \n {label}\n \n )}\n \n \n );\n}\n\ninterface ThumbIndicatorProps {\n rect: DOMRect;\n containerRect: DOMRect;\n}\n\nexport function ThumbIndicator({ rect, containerRect }: ThumbIndicatorProps) {\n const left = rect.left - containerRect.left;\n const top = rect.top - containerRect.top;\n\n return (\n \n );\n}\n" }, { "path": "apps/www/app/staging/_components/staging-canvas.tsx", "content": "\"use client\";\n\nimport { useRef, useState, useEffect, useCallback } from \"react\";\nimport { previewConfigs, type ComponentId } from \"@/lib/docs/preview-config\";\nimport { getStagingConfig } from \"@/lib/staging/staging-config\";\nimport type { DebugLevel } from \"@/lib/staging/types\";\nimport { ChatContextPreview } from \"@/app/docs/_components/chat-context-preview\";\n\ninterface StagingCanvasProps {\n componentId: ComponentId;\n presetName: string;\n debugLevel: DebugLevel;\n}\n\nexport function StagingCanvas({\n componentId,\n presetName,\n debugLevel,\n}: StagingCanvasProps) {\n const componentRef = useRef(null);\n const [, forceUpdate] = useState(0);\n const previewConfig = previewConfigs[componentId];\n const stagingConfig = getStagingConfig(componentId);\n\n const preset = previewConfig?.presets?.[presetName];\n const Wrapper = previewConfig?.wrapper;\n\n // Force re-render overlay on pointer events and animation frames during interaction\n const scheduleUpdate = useCallback(() => {\n forceUpdate((n) => n + 1);\n }, []);\n\n useEffect(() => {\n if (debugLevel === \"off\") return;\n\n const container = componentRef.current;\n if (!container) return;\n\n let rafId: number | null = null;\n let isInteracting = false;\n\n const updateLoop = () => {\n if (isInteracting) {\n scheduleUpdate();\n rafId = requestAnimationFrame(updateLoop);\n }\n };\n\n const handlePointerDown = () => {\n isInteracting = true;\n rafId = requestAnimationFrame(updateLoop);\n };\n\n const handlePointerUp = () => {\n isInteracting = false;\n if (rafId) {\n cancelAnimationFrame(rafId);\n rafId = null;\n }\n // One final update after release\n scheduleUpdate();\n };\n\n container.addEventListener(\"pointerdown\", handlePointerDown);\n window.addEventListener(\"pointerup\", handlePointerUp);\n\n return () => {\n container.removeEventListener(\"pointerdown\", handlePointerDown);\n window.removeEventListener(\"pointerup\", handlePointerUp);\n if (rafId) cancelAnimationFrame(rafId);\n };\n }, [debugLevel, scheduleUpdate]);\n\n if (!previewConfig || !preset) {\n return (\n
\n Component or preset not found\n
\n );\n }\n\n // If staging config has a tuning panel, render it instead of the normal component\n if (stagingConfig?.renderTuningPanel) {\n return (\n
\n {stagingConfig.renderTuningPanel({\n data: preset.data as Record,\n })}\n
\n );\n }\n\n const component = previewConfig.renderComponent({\n data: preset.data,\n presetName,\n state: {},\n setState: () => {},\n });\n\n const wrappedComponent = Wrapper ? {component} : component;\n\n const hasDebugOverlay = stagingConfig?.renderDebugOverlay != null;\n const shouldShowOverlay = hasDebugOverlay && debugLevel !== \"off\";\n\n return (\n
\n \n \n {wrappedComponent}\n\n {debugLevel !== \"off\" && (\n
\n {!hasDebugOverlay && (\n
\n No debug overlay for {componentId}\n
\n )}\n {shouldShowOverlay &&\n stagingConfig?.renderDebugOverlay?.({\n level: debugLevel,\n componentRef,\n })}\n
\n )}\n
\n \n \n );\n}\n" }, { "path": "apps/www/app/staging/_components/staging-showcase.tsx", "content": "\"use client\";\n\nimport {\n useCallback,\n useEffect,\n useMemo,\n useRef,\n useState,\n type ReactNode,\n} from \"react\";\nimport { AnimatePresence, motion, type Transition } from \"motion/react\";\nimport { cn } from \"@/lib/ui/cn\";\nimport { previewConfigs, type ComponentId } from \"@/lib/docs/preview-config\";\nimport { getStagingConfig } from \"@/lib/staging/staging-config\";\nimport type { DebugLevel } from \"@/lib/staging/types\";\n\nconst TIMING = {\n durations: {\n userIn: 500,\n preambleIn: 280,\n toolIn: 600,\n },\n beats: {\n afterUser: 700,\n beforeContent: 500,\n afterPreamble: 200,\n },\n} as const;\n\nconst SPRINGS = {\n gentle: {\n type: \"spring\",\n damping: 28,\n stiffness: 180,\n mass: 0.8,\n },\n smooth: {\n type: \"spring\",\n damping: 24,\n stiffness: 260,\n mass: 0.8,\n },\n standard: {\n type: \"spring\",\n damping: 26,\n stiffness: 220,\n mass: 0.7,\n },\n} as const satisfies Record;\n\ninterface ChatBubbleProps {\n role: \"user\" | \"assistant\";\n children: ReactNode;\n className?: string;\n}\n\nfunction ChatBubble({ role, children, className }: ChatBubbleProps) {\n const isUser = role === \"user\";\n\n return (\n \n \n {children}\n \n \n );\n}\n\nfunction TypingIndicator() {\n return (\n \n );\n}\n\nfunction StreamingChar({ char, delay }: { char: string; delay: number }) {\n return (\n \n {char}\n \n );\n}\n\ninterface PreambleBubbleProps {\n text: string;\n msPerChar?: number;\n onComplete?: () => void;\n}\n\nfunction PreambleBubble({\n text,\n msPerChar = 28,\n onComplete,\n}: PreambleBubbleProps) {\n const [isVisible, setIsVisible] = useState(false);\n const hasCalledComplete = useRef(false);\n\n useEffect(() => {\n const timeoutId = window.setTimeout(() => setIsVisible(true), 100);\n return () => window.clearTimeout(timeoutId);\n }, []);\n\n useEffect(() => {\n if (hasCalledComplete.current || !isVisible) return;\n\n const totalDuration = text.length * msPerChar + 400;\n const timeoutId = window.setTimeout(() => {\n if (!hasCalledComplete.current) {\n hasCalledComplete.current = true;\n onComplete?.();\n }\n }, totalDuration);\n\n return () => window.clearTimeout(timeoutId);\n }, [msPerChar, text.length, onComplete, isVisible]);\n\n const characters = useMemo(() => {\n return text.split(\"\").map((char, index) => ({\n char,\n delay: index * (msPerChar / 1000),\n }));\n }, [text, msPerChar]);\n\n return (\n \n \n \n {isVisible &&\n characters.map(({ char, delay }, index) => (\n \n ))}\n \n \n \n );\n}\n\nfunction ToolReveal({ children }: { children: ReactNode }) {\n return (\n \n {children}\n \n );\n}\n\ntype ShowcasePhase = \"user\" | \"typing\" | \"preamble\" | \"tool\" | \"complete\";\n\ninterface StagingShowcaseProps {\n componentId: ComponentId;\n presetName: string;\n debugLevel: DebugLevel;\n}\n\nexport function StagingShowcase({\n componentId,\n presetName,\n debugLevel,\n}: StagingShowcaseProps) {\n const [phase, setPhase] = useState(\"user\");\n const [key, setKey] = useState(0);\n const componentRef = useRef(null);\n\n const previewConfig = previewConfigs[componentId];\n const stagingConfig = getStagingConfig(componentId);\n const preset = previewConfig?.presets?.[presetName];\n const Wrapper = previewConfig?.wrapper;\n\n const userMessage = previewConfig?.chatContext?.userMessage ?? \"\";\n const preamble = previewConfig?.chatContext?.preamble ?? \"\";\n\n const startSequence = useCallback(() => {\n setKey((k) => k + 1);\n setPhase(\"user\");\n\n // User message appears, then show typing\n setTimeout(() => {\n setPhase(\"typing\");\n }, TIMING.durations.userIn);\n\n // Typing indicator, then show preamble\n setTimeout(() => {\n setPhase(\"preamble\");\n }, TIMING.durations.userIn + TIMING.beats.afterUser);\n }, []);\n\n const handlePreambleComplete = useCallback(() => {\n setPhase(\"tool\");\n setTimeout(() => {\n setPhase(\"complete\");\n }, TIMING.durations.toolIn);\n }, []);\n\n // Auto-start sequence on mount and when component/preset changes\n useEffect(() => {\n startSequence();\n }, [componentId, presetName, startSequence]);\n\n if (!previewConfig || !preset) {\n return (\n
\n Component or preset not found\n
\n );\n }\n\n const component = previewConfig.renderComponent({\n data: preset.data,\n presetName,\n state: {},\n setState: () => {},\n });\n\n const wrappedComponent = Wrapper ? {component} : component;\n\n const showTyping = phase === \"typing\";\n const showPreamble =\n phase === \"preamble\" || phase === \"tool\" || phase === \"complete\";\n const showTool = phase === \"tool\" || phase === \"complete\";\n\n return (\n
\n
\n \n \n {userMessage}\n \n \n\n
\n \n {showTyping && (\n \n \n \n )}\n \n\n \n {showPreamble && (\n \n \n \n )}\n \n
\n\n \n {showTool && (\n \n \n {wrappedComponent}\n\n {debugLevel !== \"off\" && stagingConfig?.renderDebugOverlay && (\n
\n {stagingConfig.renderDebugOverlay({\n level: debugLevel,\n componentRef,\n })}\n
\n )}\n
\n \n )}\n \n
\n \n );\n}\n" }, { "path": "apps/www/app/staging/_components/staging-toolbar.tsx", "content": "\"use client\";\n\nimport { Settings, Sun, Moon, Monitor, Play, Eye } from \"lucide-react\";\nimport { useTheme } from \"next-themes\";\nimport { cn } from \"@/lib/ui/cn\";\nimport { previewConfigs, type ComponentId } from \"@/lib/docs/preview-config\";\nimport { getStagingConfig } from \"@/lib/staging/staging-config\";\nimport { useStagingStore, usePresetNames } from \"./use-staging-state\";\nimport type { DebugLevel } from \"@/lib/staging/types\";\nimport {\n Select,\n SelectContent,\n SelectItem,\n SelectTrigger,\n SelectValue,\n} from \"@/components/ui/select\";\nimport {\n Popover,\n PopoverContent,\n PopoverTrigger,\n} from \"@/components/ui/popover\";\nimport { Button } from \"@/components/ui/button\";\nimport { Label } from \"@/components/ui/label\";\nimport { RadioGroup, RadioGroupItem } from \"@/components/ui/radio-group\";\n\nconst COMPONENT_IDS = Object.keys(previewConfigs) as ComponentId[];\n\nconst DEBUG_LEVEL_LABELS: Record = {\n off: \"Off\",\n boundaries: \"Boundaries\",\n margins: \"Margins\",\n full: \"Full\",\n};\n\nfunction ComponentSelector() {\n const { componentId, setComponent } = useStagingStore();\n\n return (\n setComponent(v as ComponentId)}\n >\n \n \n \n \n {COMPONENT_IDS.map((id) => (\n \n {formatComponentName(id)}\n \n ))}\n \n \n );\n}\n\nfunction formatComponentName(id: string): string {\n return id\n .split(\"-\")\n .map((word) => word.charAt(0).toUpperCase() + word.slice(1))\n .join(\" \");\n}\n\nfunction PresetPills() {\n const { presetName, setPreset } = useStagingStore();\n const presetNames = usePresetNames();\n\n return (\n
\n {presetNames.map((name, index) => (\n setPreset(name)}\n className={cn(\n \"rounded-full px-3 py-1 text-xs font-medium transition-colors\",\n presetName === name\n ? \"bg-foreground text-background\"\n : \"text-muted-foreground hover:text-foreground hover:bg-muted\",\n )}\n >\n \n {index + 1}\n \n {formatPresetName(name)}\n \n ))}\n
\n );\n}\n\nfunction formatPresetName(name: string): string {\n return name\n .split(\"-\")\n .map((word) => word.charAt(0).toUpperCase() + word.slice(1))\n .join(\" \");\n}\n\nfunction SettingsPopover() {\n const { componentId, debugLevel, setDebugLevel } = useStagingStore();\n const { theme, setTheme } = useTheme();\n\n const stagingConfig = getStagingConfig(componentId);\n const hasDebugOverlays =\n (stagingConfig?.supportedDebugLevels?.length ?? 0) > 0;\n\n return (\n \n \n \n \n \n \n \n
\n {hasDebugOverlays && (\n
\n
\n \n \n D\n \n
\n setDebugLevel(v as DebugLevel)}\n className=\"grid grid-cols-2 gap-2\"\n >\n {(stagingConfig?.supportedDebugLevels ?? []).map((level) => (\n
\n \n \n {DEBUG_LEVEL_LABELS[level]}\n \n
\n ))}\n \n
\n )}\n\n
\n \n
\n setTheme(\"light\")}\n >\n \n Light\n \n setTheme(\"dark\")}\n >\n \n Dark\n \n setTheme(\"system\")}\n >\n \n \n
\n
\n\n
\n

\n Press{\" \"}\n 1-\n 9 to\n switch presets\n

\n
\n
\n \n \n );\n}\n\nfunction ViewModeToggle() {\n const { viewMode, setViewMode } = useStagingStore();\n\n return (\n
\n setViewMode(\"static\")}\n className={cn(\n \"flex items-center gap-1.5 rounded-md px-2 py-1 text-xs font-medium transition-colors\",\n viewMode === \"static\"\n ? \"bg-foreground text-background\"\n : \"text-muted-foreground hover:text-foreground\",\n )}\n title=\"Static view\"\n >\n \n Static\n \n setViewMode(\"showcase\")}\n className={cn(\n \"flex items-center gap-1.5 rounded-md px-2 py-1 text-xs font-medium transition-colors\",\n viewMode === \"showcase\"\n ? \"bg-foreground text-background\"\n : \"text-muted-foreground hover:text-foreground\",\n )}\n title=\"Showcase animation\"\n >\n \n Showcase\n \n
\n );\n}\n\nfunction DebugLevelIndicator() {\n const { debugLevel, cycleDebugLevel } = useStagingStore();\n\n if (debugLevel === \"off\") return null;\n\n const colors: Record = {\n off: \"\",\n boundaries: \"bg-blue-500\",\n margins: \"bg-emerald-500\",\n full: \"bg-orange-500\",\n };\n\n return (\n \n \n {DEBUG_LEVEL_LABELS[debugLevel]}\n \n );\n}\n\nexport function StagingToolbar() {\n return (\n
\n
\n
\n \n
\n \n
\n\n
\n \n
\n \n \n
\n
\n
\n );\n}\n" }, { "path": "apps/www/app/staging/_components/use-keyboard-shortcuts.ts", "content": "\"use client\";\n\nimport { useEffect } from \"react\";\nimport { useStagingStore, usePresetNames } from \"./use-staging-state\";\n\nexport function useKeyboardShortcuts() {\n const { setPreset, cycleDebugLevel } = useStagingStore();\n const presetNames = usePresetNames();\n\n useEffect(() => {\n function handleKeyDown(event: KeyboardEvent) {\n // Ignore if typing in an input\n if (\n event.target instanceof HTMLInputElement ||\n event.target instanceof HTMLTextAreaElement\n ) {\n return;\n }\n\n // Number keys 1-9 for preset selection\n if (event.key >= \"1\" && event.key <= \"9\") {\n const index = parseInt(event.key, 10) - 1;\n if (index < presetNames.length) {\n setPreset(presetNames[index]);\n }\n return;\n }\n\n // D to cycle debug levels\n if (event.key.toLowerCase() === \"d\") {\n cycleDebugLevel();\n return;\n }\n }\n\n window.addEventListener(\"keydown\", handleKeyDown);\n return () => window.removeEventListener(\"keydown\", handleKeyDown);\n }, [presetNames, setPreset, cycleDebugLevel]);\n}\n" }, { "path": "apps/www/app/staging/_components/use-staging-state.ts", "content": "\"use client\";\n\nimport { create } from \"zustand\";\nimport { useSearchParams, useRouter, usePathname } from \"next/navigation\";\nimport { useEffect, useCallback } from \"react\";\nimport { previewConfigs, type ComponentId } from \"@/lib/docs/preview-config\";\nimport type { DebugLevel } from \"@/lib/staging/types\";\n\ntype ViewMode = \"static\" | \"showcase\";\n\ninterface StagingState {\n componentId: ComponentId;\n presetName: string;\n debugLevel: DebugLevel;\n viewMode: ViewMode;\n setComponent: (id: ComponentId) => void;\n setPreset: (name: string) => void;\n setDebugLevel: (level: DebugLevel) => void;\n cycleDebugLevel: () => void;\n setViewMode: (mode: ViewMode) => void;\n}\n\nconst DEBUG_LEVELS: DebugLevel[] = [\"off\", \"boundaries\", \"margins\", \"full\"];\n\nexport const useStagingStore = create((set, get) => ({\n componentId: \"parameter-slider\",\n presetName: \"photo-adjustments\",\n debugLevel: \"off\",\n viewMode: \"static\",\n\n setComponent: (id) => {\n const config = previewConfigs[id];\n set({\n componentId: id,\n presetName:\n config?.defaultPreset ?? Object.keys(config?.presets ?? {})[0] ?? \"\",\n debugLevel: \"off\",\n });\n },\n\n setPreset: (name) => set({ presetName: name }),\n\n setDebugLevel: (level) => set({ debugLevel: level }),\n\n cycleDebugLevel: () => {\n const current = get().debugLevel;\n const currentIndex = DEBUG_LEVELS.indexOf(current);\n const nextIndex = (currentIndex + 1) % DEBUG_LEVELS.length;\n set({ debugLevel: DEBUG_LEVELS[nextIndex] });\n },\n\n setViewMode: (mode) => set({ viewMode: mode }),\n}));\n\nexport function useStagingState() {\n const store = useStagingStore();\n const searchParams = useSearchParams();\n const router = useRouter();\n const pathname = usePathname();\n\n // Sync URL params to store on mount\n useEffect(() => {\n const componentParam = searchParams.get(\"component\") as ComponentId | null;\n const presetParam = searchParams.get(\"preset\");\n const debugParam = searchParams.get(\"debug\") as DebugLevel | null;\n\n if (componentParam && componentParam in previewConfigs) {\n const config = previewConfigs[componentParam];\n const presetName =\n presetParam && presetParam in (config?.presets ?? {})\n ? presetParam\n : (config?.defaultPreset ?? \"\");\n\n const debugLevel =\n debugParam && DEBUG_LEVELS.includes(debugParam) ? debugParam : \"off\";\n\n // Only update store if values have changed to prevent infinite loop\n const currentState = useStagingStore.getState();\n if (\n currentState.componentId !== componentParam ||\n currentState.presetName !== presetName ||\n currentState.debugLevel !== debugLevel\n ) {\n useStagingStore.setState({\n componentId: componentParam,\n presetName,\n debugLevel,\n });\n }\n }\n }, [searchParams]);\n\n // Sync store to URL params\n const syncToUrl = useCallback(() => {\n const state = useStagingStore.getState();\n const params = new URLSearchParams();\n params.set(\"component\", state.componentId);\n params.set(\"preset\", state.presetName);\n if (state.debugLevel !== \"off\") {\n params.set(\"debug\", state.debugLevel);\n }\n router.replace(`${pathname}?${params.toString()}`, { scroll: false });\n }, [router, pathname]);\n\n // Subscribe to store changes\n useEffect(() => {\n const unsubscribe = useStagingStore.subscribe(() => {\n syncToUrl();\n });\n return unsubscribe;\n }, [syncToUrl]);\n\n return store;\n}\n\nexport function usePresetNames(): string[] {\n const { componentId } = useStagingStore();\n const config = previewConfigs[componentId];\n return Object.keys(config?.presets ?? {});\n}\n" }, { "path": "apps/www/app/staging/layout.tsx", "content": "import type { ReactNode } from \"react\";\nimport { ThemeProvider } from \"next-themes\";\n\nexport default function StagingLayout({ children }: { children: ReactNode }) {\n return (\n \n
\n {children}\n
\n \n );\n}\n" }, { "path": "apps/www/app/staging/page.tsx", "content": "\"use client\";\n\nimport { Suspense } from \"react\";\nimport { StagingToolbar } from \"./_components/staging-toolbar\";\nimport { StagingCanvas } from \"./_components/staging-canvas\";\nimport { StagingShowcase } from \"./_components/staging-showcase\";\nimport { useStagingState } from \"./_components/use-staging-state\";\nimport { useKeyboardShortcuts } from \"./_components/use-keyboard-shortcuts\";\n\nfunction StagingContent() {\n const { componentId, presetName, debugLevel, viewMode } = useStagingState();\n useKeyboardShortcuts();\n\n return (\n
\n \n
\n {viewMode === \"static\" ? (\n \n ) : (\n \n )}\n
\n
\n );\n}\n\nexport default function StagingPage() {\n return (\n \n
Loading...
\n \n }\n >\n \n \n );\n}\n" }, { "path": "apps/www/app/styles/builder-loader.css", "content": ".loader {\n width: 48px;\n height: 48px;\n border: 5px solid;\n border-color: #000 transparent;\n border-radius: 50%;\n display: inline-block;\n box-sizing: border-box;\n animation: rotation 1s linear infinite;\n margin: 20px auto;\n}\n\n@keyframes rotation {\n 0% {\n transform: rotate(0deg);\n }\n 100% {\n transform: rotate(360deg);\n }\n}\n\n@media (prefers-color-scheme: dark) {\n .loader {\n border-color: #fff transparent;\n }\n}\n" }, { "path": "apps/www/app/styles/custom-utilities.css", "content": ":root {\n --cubic-ease-in-out: cubic-bezier(0.62, -0.05, 0.71, 1.15);\n}\n\n@keyframes accordion-down {\n from {\n height: 0;\n }\n to {\n height: var(--radix-accordion-content-height);\n }\n}\n\n@keyframes accordion-up {\n from {\n height: var(--radix-accordion-content-height);\n }\n to {\n height: 0;\n }\n}\n\n@keyframes collapsible-down {\n from {\n height: 0;\n }\n to {\n height: var(--radix-collapsible-content-height);\n }\n}\n\n@keyframes collapsible-up {\n from {\n height: var(--radix-collapsible-content-height);\n }\n to {\n height: 0;\n }\n}\n\n@keyframes scale-in {\n from {\n transform: scale(0.8);\n opacity: 0;\n }\n to {\n transform: scale(1);\n opacity: 1;\n }\n}\n\n@keyframes spring-bounce {\n 0% {\n transform: scale(0.8);\n opacity: 0;\n }\n 50% {\n transform: scale(1.1);\n }\n 100% {\n transform: scale(1);\n opacity: 1;\n }\n}\n\n@keyframes check-draw {\n 0% {\n stroke-dasharray: var(--check-path-length, 24);\n stroke-dashoffset: var(--check-path-length, 24);\n opacity: 0;\n }\n 50% {\n opacity: 1;\n }\n 100% {\n stroke-dasharray: var(--check-path-length, 24);\n stroke-dashoffset: 0;\n opacity: 1;\n }\n}\n\n@keyframes fade-up {\n from {\n opacity: 0;\n transform: translateY(8px);\n }\n to {\n opacity: 1;\n transform: translateY(0);\n }\n}\n\n@keyframes fade-blur-in {\n from {\n opacity: 0;\n transform: translateY(4px);\n filter: blur(4px);\n }\n to {\n opacity: 1;\n transform: translateY(0);\n filter: blur(0);\n }\n}\n\n@keyframes progress-pulse {\n 0%,\n 100% {\n filter: brightness(1);\n }\n 50% {\n filter: brightness(1.3);\n }\n}\n\n@keyframes shimmer-sweep {\n 0% {\n transform: translateX(-100%);\n }\n 100% {\n transform: translateX(200%);\n }\n}\n\n@keyframes glow-pulse {\n 0%,\n 100% {\n opacity: 0;\n }\n 50% {\n opacity: 1;\n }\n}\n\n@keyframes fade-in-stagger {\n from {\n opacity: 0;\n transform: translateY(-4px);\n }\n to {\n opacity: 1;\n transform: translateY(0);\n }\n}\n\n@keyframes fade-out-stagger {\n from {\n opacity: 1;\n transform: translateY(0);\n }\n to {\n opacity: 0;\n transform: translateY(-4px);\n }\n}\n\n@keyframes navbar-fade-in {\n from {\n opacity: 0;\n transform: translateY(-12px);\n }\n to {\n opacity: 1;\n transform: translateY(0);\n }\n}\n\n@layer utilities {\n .animate-accordion-down {\n animation: accordion-down 200ms ease-out;\n }\n\n .animate-accordion-up {\n animation: accordion-up 200ms ease-out;\n }\n\n .animate-collapsible-down {\n animation: collapsible-down 150ms ease-out;\n }\n\n .animate-collapsible-up {\n animation: collapsible-up 150ms ease-out;\n }\n\n .animate-fade-blur-in {\n animation: fade-blur-in 300ms cubic-bezier(0.16, 1, 0.3, 1) both;\n }\n\n .animate-navbar-fade-in {\n opacity: 0;\n animation: navbar-fade-in 1.2s cubic-bezier(0.22, 1, 0.36, 1) 0.3s both;\n }\n\n .bg-wash {\n background-color: hsl(var(--wash));\n }\n .bg-dot-grid {\n --dot-grid-color: var(--border);\n background-image: radial-gradient(\n circle,\n var(--dot-grid-color) 1px,\n transparent 1px\n );\n background-position: 6px 6px;\n background-size: 16px 16px;\n }\n\n .dark .bg-dot-grid {\n --dot-grid-color: color-mix(in oklch, var(--border) 80%, transparent);\n }\n\n .shadow-crisp-edge {\n position: relative;\n box-sizing: padding-box;\n box-shadow:\n 0px 1px 0px -1px oklch(0 0 0 / 0.1),\n 0px 1px 1px -1px oklch(0 0 0 / 0.1),\n 0px 1px 2px -1px oklch(0 0 0 / 0.1),\n 0px 2px 4px -2px oklch(0 0 0 / 0.1),\n 0px 3px 6px -3px oklch(0 0 0 / 0.1);\n\n &::after {\n content: \"\";\n pointer-events: none;\n position: absolute;\n inset: 0;\n border-radius: inherit;\n box-shadow:\n inset 0px 0px 0px 1px oklch(1 0 0 / 0.5),\n inset 0px 1px 0px oklch(1 0 0 / 0.5);\n }\n }\n\n .dark .shadow-crisp-edge {\n box-shadow:\n 0px 1px 0px -1px oklch(0 0 0 / 0.1),\n 0px 1px 1px -1px oklch(0 0 0 / 0.1),\n 0px 1px 2px -1px oklch(0 0 0 / 0.1),\n 0px 2px 4px -2px oklch(0 0 0 / 0.1),\n 0px 3px 6px -3px oklch(0 0 0 / 0.1);\n\n &::after {\n box-shadow:\n inset 0px 0px 0px 1px oklch(1 0 0 / 0.05),\n inset 0px 1px 0px oklch(1 0 0 / 0.05);\n }\n }\n\n .scrollbar-subtle {\n scrollbar-width: thin;\n scrollbar-color: oklch(0 0 0 / 0.2) transparent;\n }\n\n .scrollbar-subtle::-webkit-scrollbar {\n width: 20px;\n height: 20px;\n }\n\n .scrollbar-subtle::-webkit-scrollbar-track {\n background: transparent;\n /* Add padding to prevent thumb from being clipped by rounded corners */\n margin: 0.25rem;\n }\n\n .scrollbar-subtle::-webkit-scrollbar-thumb {\n background-color: oklch(58.88% 0.23563 28.674 / 0.2);\n border-radius: 9999px;\n /* Ensure thumb doesn't extend to edges */\n border: 0 solid transparent;\n }\n\n .scrollbar-subtle:hover::-webkit-scrollbar-thumb {\n background-color: oklch(0 0 0 / 0.3);\n }\n\n .dark .scrollbar-subtle {\n scrollbar-color: var(--color-neutral-500) transparent;\n }\n\n .dark .scrollbar-subtle::-webkit-scrollbar-thumb {\n background-color: oklch(52.771% 0.21252 28.808 / 0.25);\n }\n\n .dark .scrollbar-subtle:hover::-webkit-scrollbar-thumb {\n background-color: oklch(58.661% 0.23514 28.709 / 0.55);\n }\n\n .border-gradient-glow {\n --glow-gradient: rgba(0, 0, 0, 0.12);\n --glow-surface-from: var(--background);\n --glow-surface-to: #f7f7f7;\n background:\n linear-gradient(\n to bottom,\n var(--glow-surface-from),\n var(--glow-surface-to)\n )\n padding-box,\n var(--glow-gradient) border-box;\n border: 1px solid transparent;\n }\n\n .dark .border-gradient-glow {\n --glow-surface-from: var(--background);\n --glow-surface-to: var(--background);\n --glow-gradient: radial-gradient(\n ellipse 300% 214% at 0% 72%,\n rgba(255, 255, 255, 0.41) 0%,\n rgba(255, 255, 255, 0.12) 19%,\n rgba(255, 255, 255, 0.02) 49%,\n rgba(255, 255, 255, 0) 100%\n );\n }\n\n .border-gradient-glow-composer {\n --glow-gradient: rgba(0, 0, 0, 0.12);\n --composer-bg: rgba(247, 247, 247, 0.8);\n background:\n linear-gradient(var(--composer-bg), var(--composer-bg)) padding-box,\n var(--glow-gradient) border-box;\n border: 1px solid transparent;\n backdrop-filter: blur(24px);\n -webkit-backdrop-filter: blur(24px);\n }\n\n .dark .border-gradient-glow-composer {\n --glow-gradient: radial-gradient(\n ellipse 167% 263% at 0% 41%,\n rgba(255, 255, 255, 0.41) 0%,\n rgba(255, 255, 255, 0.12) 19%,\n rgba(255, 255, 255, 0.02) 49%,\n rgba(255, 255, 255, 0) 100%\n );\n --composer-bg: color-mix(in srgb, var(--background) 85%, transparent);\n }\n\n .border-gradient-glow-dot {\n --glow-gradient: rgba(0, 0, 0, 0.12);\n }\n\n .dark .border-gradient-glow-dot {\n --glow-gradient: radial-gradient(\n ellipse 140% 200% at 25% 100%,\n rgba(255, 255, 255, 0.4) 0%,\n rgba(255, 255, 255, 0) 50%,\n rgba(255, 255, 255, 0.01) 46%\n );\n }\n\n .border-gradient-glow-notch {\n --glow-gradient: rgba(0, 0, 0, 0.12);\n background: var(--glow-gradient);\n border: 1px solid transparent;\n mask:\n linear-gradient(#fff 0 0) padding-box,\n linear-gradient(#fff 0 0);\n mask-composite: exclude;\n -webkit-mask-composite: xor;\n }\n\n .dark .border-gradient-glow-notch {\n --glow-gradient: radial-gradient(\n ellipse 120% 180% at 20% 80%,\n rgba(255, 255, 255, 0.12) 0%,\n rgba(255, 255, 255, 0.04) 30%,\n rgba(255, 255, 255, 0.01) 60%,\n rgba(255, 255, 255, 0) 100%\n );\n }\n\n .gradient-line-header {\n background: linear-gradient(\n to right,\n rgba(0, 0, 0, 0.07) 0%,\n rgba(0, 0, 0, 0) 140%\n );\n }\n\n .dark .gradient-line-header {\n background: linear-gradient(\n to right,\n rgba(255, 255, 255, 0.1) 0%,\n rgba(255, 255, 255, 0) 100%\n );\n }\n}\n" }, { "path": "apps/www/app/styles/fumadocs-overrides.css", "content": "/* =============================================================================\n Fumadocs UI Overrides\n Scoped to docs/MDX surfaces for consistent styling with shadcn theme\n ============================================================================= */\n\n/* -----------------------------------------------------------------------------\n Debug / Development Variables\n TODO: Remove or replace these placeholder values before production\n ----------------------------------------------------------------------------- */\n\n:root {\n --shiki-light-bg: var(--color-neutral-100);\n --shiki-dark-bg: var(--color-neutral-900);\n\n .dark {\n --color-fd-foreground: hsl(0 0% 98%);\n }\n}\n\n/* -----------------------------------------------------------------------------\n Prose Content Overrides\n Styling adjustments for MDX content within .prose containers\n ----------------------------------------------------------------------------- */\n\n@layer utilities {\n /* Step component badges (/) */\n .prose :where(.fd-step)::before {\n @apply bg-muted text-primary size-8 text-lg;\n }\n\n /* Remove decorative quote marks from blockquotes */\n .prose blockquote::before,\n .prose blockquote::after,\n .prose blockquote p::before,\n .prose blockquote p::after {\n content: none !important;\n }\n}\n\n/* -----------------------------------------------------------------------------\n Tab Panel Layout\n Component preview and code block positioning within tab panels\n ----------------------------------------------------------------------------- */\n\n/* Center component previews */\n[data-state][role=\"tabpanel\"] > .not-prose {\n margin-inline: auto;\n}\n\n/* Full-width code blocks (negative margin compensates for panel padding) */\n[data-state][role=\"tabpanel\"] > figure:only-child {\n margin: -1rem !important;\n}\n\n/* -----------------------------------------------------------------------------\n Shiki Code Block Constraints\n Prevents overflow from long unbreakable strings (URLs, tokens, etc.)\n Fumadocs Pre uses w-max which causes horizontal overflow\n ----------------------------------------------------------------------------- */\n\nfigure.shiki {\n position: relative;\n background-color: var(--color-neutral-100);\n corner-shape: squircle;\n border: none;\n border-radius: calc(var(--radius) * var(--border-radius-multiplier));\n}\n\n.dark figure.shiki {\n background-color: var(--color-neutral-900);\n}\n\nfigure.shiki pre {\n width: 100% !important;\n min-width: 0 !important;\n max-width: 100% !important;\n}\n\nfigure.shiki pre code {\n white-space: pre-wrap;\n word-break: break-all;\n overflow-wrap: anywhere;\n}\n\n/* -----------------------------------------------------------------------------\n Full-Bleed Code Panel\n Expanded code view with internal padding for view mode toggle\n ----------------------------------------------------------------------------- */\n\n.code-panel-fullbleed {\n overflow-y: scroll;\n height: 100%;\n\n & figure.shiki {\n display: flex;\n flex: 1;\n flex-direction: column;\n min-height: 0;\n margin: 0;\n border: none;\n border-radius: 0;\n height: 100%;\n background: transparent;\n }\n\n & figure.shiki pre {\n flex: 1;\n margin: 0;\n padding-top: 4rem; /* Space for toggle button */\n border-radius: 0;\n }\n\n /* Fill available height instead of fumadocs default max-height */\n & .fd-scroll-container {\n height: 100%;\n max-height: none !important;\n padding-bottom: 6rem; /* Extra scroll room at bottom */\n }\n\n /* Hide fumadocs copy button (we provide our own) */\n & figure.shiki > div.absolute {\n display: none;\n }\n\n /* Restore squircle corners on larger screens */\n @media (min-width: 1024px) {\n & figure.shiki {\n corner-shape: squircle;\n border-radius: calc(var(--radius) * var(--border-radius-multiplier));\n }\n }\n}\n\n/* -----------------------------------------------------------------------------\n Fumadocs Theme Tokens\n NOTE: fumadocs-ui/css/shadcn.css automatically maps --color-fd-* to shadcn\n variables (--background, --foreground, etc). No manual mapping needed here.\n To customize fumadocs colors, edit shadcn-theme.css instead.\n ----------------------------------------------------------------------------- */\n" }, { "path": "apps/www/app/styles/globals.css", "content": "@import \"tailwindcss\";\n@import \"tw-animate-css\";\n@import \"tw-shimmer\";\n\n/* Fumadocs UI styles */\n@import \"fumadocs-ui/css/preset.css\";\n@import \"fumadocs-ui/css/shadcn.css\";\n\n/* Silk Sheet UI styles */\n@import \"@silk-hq/components/layered-styles\";\n\n/* Shadcn theme */\n@import \"./shadcn-theme.css\";\n\n/* Lib overrides */\n@import \"./leaflet-overrides.css\";\n@import \"./fumadocs-overrides.css\";\n\n/* Custom styles */\n@import \"./prose.css\";\n@import \"./squircle.css\";\n@import \"./custom-utilities.css\";\n\n/* View Transitions */\n@import \"./theme-transition.css\";\n\n@layer base {\n * {\n @apply border-border outline-ring/50;\n }\n html {\n overflow: hidden;\n overscroll-behavior: none;\n }\n body {\n @apply bg-background text-foreground;\n overflow: hidden;\n }\n}\n" }, { "path": "apps/www/app/styles/leaflet-overrides.css", "content": "/* Leaflet overrides for theme integration */\n\n.leaflet-container {\n background: var(--muted);\n /* Isolate Leaflet's high z-indices to prevent them from escaping the container */\n isolation: isolate;\n}\n\n[data-theme=\"dark\"] .leaflet-container {\n background: hsl(240 0 10%);\n}\n\n.leaflet-control-attribution {\n background: oklch(from var(--background) l c h / 0.8) !important;\n color: var(--muted-foreground);\n}\n\n[data-theme=\"dark\"] .leaflet-control-attribution {\n background: hsl(240 10% 3.9% / 0.8) !important;\n color: hsl(240 5% 64.9%);\n}\n\n.leaflet-control-attribution a {\n color: var(--muted-foreground);\n}\n\n[data-theme=\"dark\"] .leaflet-control-attribution a {\n color: hsl(240 5% 64.9%);\n}\n\n.leaflet-control-attribution a:hover {\n color: var(--foreground);\n}\n\n[data-theme=\"dark\"] .leaflet-control-attribution a:hover {\n color: hsl(0 0% 98%);\n}\n" }, { "path": "apps/www/app/styles/nav-sheet.css", "content": ".MobileNavSheet-trigger {\n position: fixed;\n right: calc(1rem + env(safe-area-inset-right, 0px));\n bottom: calc(2.75rem + env(safe-area-inset-bottom, 0px));\n}\n\n.MobileNavSheet-view {\n height: var(--silk-100-lvh-dvh-pct);\n z-index: 50;\n position: fixed;\n inset: 0;\n}\n\n:root {\n --overlay-offset: 0px;\n}\n/* Broad fallback: difference between legacy vh and dynamic dvh */\n@supports (height: 100dvh) {\n :root {\n --overlay-offset: max(0px, calc(100vh - 100dvh));\n }\n}\n/* Preferred: largest vs dynamic viewport (captures iOS Safari toolbar) */\n@supports (height: 100lvh) and (height: 100dvh) {\n :root {\n --overlay-offset: max(0px, calc(100lvh - 100dvh));\n }\n}\n\n.MobileNavSheet-content {\n box-sizing: border-box;\n max-width: 700px;\n max-height: 100vh;\n /* Extend height to include safe area; prefer dynamic viewport units */\n height: calc(92vh + env(safe-area-inset-bottom, 0px)); /* fallback */\n height: calc(92svh + env(safe-area-inset-bottom, 0px)); /* small viewport */\n height: calc(92dvh + env(safe-area-inset-bottom, 0px)); /* dynamic viewport */\n display: flex;\n flex-direction: column;\n position: relative;\n z-index: 52;\n overflow: hidden;\n}\n\n.MobileNavSheet-content > div {\n -webkit-overflow-scrolling: touch;\n scroll-behavior: smooth;\n}\n\n.MobileNavSheet-backdrop {\n background-color: rgb(0 0 0);\n position: fixed;\n inset: 0;\n z-index: 51;\n}\n\n.MobileNavSheet-bleedingBackground {\n overflow: hidden;\n border-radius: 16px 16px 0 0;\n background-color: var(--background);\n box-shadow:\n 0 -4px 6px -1px rgb(0 0 0 / 0.1),\n 0 -2px 4px -2px rgb(0 0 0 / 0.1);\n}\n\n/* Bottom gradient that sits above the footer and hints scrolling */\n.MobileNavSheet-bottomGradient {\n pointer-events: none;\n position: absolute;\n left: 0;\n right: 0;\n bottom: 0;\n height: 5rem; /* match visual density */\n z-index: 15; /* stays below the footer */\n background: linear-gradient(to top, var(--background), transparent);\n}\n\n/* Footer with safe-area padding, outside the scroll area */\n.MobileNavSheet-footer {\n flex-shrink: 0;\n background-color: var(--background);\n position: relative;\n z-index: 20; /* above gradient */\n /* Older iOS fallback */\n padding: 0.75rem 1rem calc(0.75rem + constant(safe-area-inset-bottom));\n /* Modern: use the larger of safe-area or toolbar overlay (not both) */\n padding: 0.75rem 1rem\n calc(0.75rem + max(env(safe-area-inset-bottom, 0px), var(--overlay-offset)));\n}\n\n.MobileNavSheet-footerInner {\n max-width: 700px;\n margin: 0 auto;\n display: flex;\n gap: 0.5rem;\n}\n" }, { "path": "apps/www/app/styles/prose.css", "content": "@layer utilities {\n .prose {\n @apply text-foreground;\n }\n\n .prose :where(h1):not(:where([class~=\"not-prose\"], [class~=\"not-prose\"] *)) {\n @apply mt-0 mb-2 flex flex-wrap items-center gap-3 text-4xl font-medium tracking-normal;\n }\n\n .prose :where(h2):not(:where([class~=\"not-prose\"], [class~=\"not-prose\"] *)) {\n @apply mb-4 text-2xl font-medium;\n }\n\n .prose\n :where(h2:not(:first-child)):not(\n :where([class~=\"not-prose\"], [class~=\"not-prose\"] *)\n ) {\n @apply mt-16;\n }\n\n .prose :where(h3):not(:where([class~=\"not-prose\"], [class~=\"not-prose\"] *)) {\n @apply mt-8 mb-3 text-xl font-medium;\n }\n\n .prose :where(h4):not(:where([class~=\"not-prose\"], [class~=\"not-prose\"] *)) {\n @apply mt-6 mb-2 text-lg;\n }\n\n .prose :where(p):not(:where([class~=\"not-prose\"], [class~=\"not-prose\"] *)) {\n @apply mb-4;\n }\n\n .prose\n :where(.lead):not(:where([class~=\"not-prose\"], [class~=\"not-prose\"] *)) {\n @apply text-muted-foreground mb-6 text-xl leading-relaxed;\n }\n\n .prose :where(a):not(:where([class~=\"not-prose\"], [class~=\"not-prose\"] *)) {\n @apply text-primary hover:text-primary/80 font-medium decoration-1 transition-colors;\n }\n\n .prose\n :where(strong):not(:where([class~=\"not-prose\"], [class~=\"not-prose\"] *)) {\n @apply text-foreground font-semibold;\n }\n\n .prose\n :where(ul, ol):not(:where([class~=\"not-prose\"], [class~=\"not-prose\"] *)) {\n /* Reduce default left indent for lists */\n @apply my-4 ml-4 space-y-2;\n }\n\n /* Reduce indent for nested lists as well */\n .prose\n :where(li > ul, li > ol):not(\n :where([class~=\"not-prose\"], [class~=\"not-prose\"] *)\n ) {\n @apply ml-4;\n }\n\n .prose :where(ul):not(:where([class~=\"not-prose\"], [class~=\"not-prose\"] *)) {\n @apply list-disc;\n }\n\n .prose :where(ol):not(:where([class~=\"not-prose\"], [class~=\"not-prose\"] *)) {\n @apply list-decimal;\n }\n\n .prose :where(li):not(:where([class~=\"not-prose\"], [class~=\"not-prose\"] *)) {\n @apply leading-7;\n }\n\n .prose\n :where(li > p):not(:where([class~=\"not-prose\"], [class~=\"not-prose\"] *)) {\n @apply my-2;\n }\n\n .prose\n :where(code):not(:where([class~=\"not-prose\"], [class~=\"not-prose\"] *)) {\n @apply bg-primary/10 dark:bg-primary/15 rounded-md border-none px-1.5 py-1 font-mono;\n }\n\n /* Remove Tailwind Typography's visible backtick quotes around inline code */\n .prose :where(:not(pre) > code)::before,\n .prose :where(:not(pre) > code)::after {\n content: none !important;\n }\n\n .prose :where(pre):not(:where([class~=\"not-prose\"], [class~=\"not-prose\"] *)) {\n @apply my-6 overflow-x-auto rounded-lg bg-muted p-4;\n }\n\n .prose\n :where(pre code):not(:where([class~=\"not-prose\"], [class~=\"not-prose\"] *)) {\n @apply bg-transparent p-0;\n }\n\n .prose\n :where(blockquote):not(\n :where([class~=\"not-prose\"], [class~=\"not-prose\"] *)\n ) {\n @apply border-primary text-muted-foreground my-6 border-l-4 pl-4 font-normal italic;\n }\n\n /* Remove quote marks around blockquoted text */\n .prose :where(blockquote)::before,\n .prose :where(blockquote)::after {\n content: none !important;\n }\n\n .prose :where(hr):not(:where([class~=\"not-prose\"], [class~=\"not-prose\"] *)) {\n @apply border-border my-8;\n }\n\n .prose\n :where(table):not(:where([class~=\"not-prose\"], [class~=\"not-prose\"] *)) {\n @apply my-6 w-full border-collapse;\n }\n\n .prose\n :where(thead):not(:where([class~=\"not-prose\"], [class~=\"not-prose\"] *)) {\n @apply border-border border-b;\n }\n\n .prose :where(th):not(:where([class~=\"not-prose\"], [class~=\"not-prose\"] *)) {\n @apply p-2 text-left font-semibold;\n }\n\n .prose :where(td):not(:where([class~=\"not-prose\"], [class~=\"not-prose\"] *)) {\n @apply border-border border-t p-2;\n }\n}\n" }, { "path": "apps/www/app/styles/shadcn-theme.css", "content": "/* Tailwind v4 theme configuration */\n@custom-variant dark (&:is(.dark *, [data-theme=\"dark\"], [data-theme=\"dark\"] *));\n\n@import \"tailwindcss\";\n@import \"tw-animate-css\";\n\n@custom-variant dark (&:is(.dark *));\n\n@theme inline {\n --radius-sm: calc(var(--radius) - 4px);\n --radius-md: calc(var(--radius) - 2px);\n --radius-lg: var(--radius);\n --radius-xl: calc(var(--radius) + 4px);\n --radius-2xl: calc(var(--radius) + 8px);\n --radius-3xl: calc(var(--radius) + 12px);\n --radius-4xl: calc(var(--radius) + 16px);\n --color-background: var(--background);\n --color-foreground: var(--foreground);\n --color-card: var(--card);\n --color-card-foreground: var(--card-foreground);\n --color-popover: var(--popover);\n --color-popover-foreground: var(--popover-foreground);\n --color-primary: var(--primary);\n --color-primary-foreground: var(--primary-foreground);\n --color-secondary: var(--secondary);\n --color-secondary-foreground: var(--secondary-foreground);\n --color-muted: var(--muted);\n --color-muted-foreground: var(--muted-foreground);\n --color-accent: var(--accent);\n --color-accent-foreground: var(--accent-foreground);\n --color-destructive: var(--destructive);\n --color-border: var(--border);\n --color-input: var(--input);\n --color-ring: var(--ring);\n --color-chart-1: var(--chart-1);\n --color-chart-2: var(--chart-2);\n --color-chart-3: var(--chart-3);\n --color-chart-4: var(--chart-4);\n --color-chart-5: var(--chart-5);\n --color-sidebar: var(--sidebar);\n --color-sidebar-foreground: var(--sidebar-foreground);\n --color-sidebar-primary: var(--sidebar-primary);\n --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);\n --color-sidebar-accent: var(--sidebar-accent);\n --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);\n --color-sidebar-border: var(--sidebar-border);\n --color-sidebar-ring: var(--sidebar-ring);\n}\n\n:root {\n color-scheme: light;\n --radius: 0.625rem;\n --background: oklch(1 0 0);\n --foreground: oklch(0.145 0 0);\n --card: oklch(1 0 0);\n --card-foreground: oklch(0.145 0 0);\n --popover: oklch(1 0 0);\n --popover-foreground: oklch(0.145 0 0);\n --primary: oklch(0.205 0 0);\n --primary-foreground: oklch(0.985 0 0);\n --secondary: oklch(0.97 0 0);\n --secondary-foreground: oklch(0.205 0 0);\n --muted: oklch(0.97 0 0);\n --muted-foreground: oklch(0.556 0 0);\n --accent: oklch(0.97 0 0);\n --accent-foreground: oklch(0.205 0 0);\n --destructive: oklch(0.577 0.245 27.325);\n --border: oklch(0.922 0 0);\n --input: oklch(0.922 0 0);\n --ring: oklch(0.708 0 0);\n --chart-1: var(--color-green-500);\n --chart-2: var(--color-red-500);\n --chart-3: var(--color-blue-500);\n --chart-4: var(--color-purple-500);\n --chart-5: var(--color-yellow-500);\n --sidebar: oklch(0.985 0 0);\n --sidebar-foreground: oklch(0.145 0 0);\n --sidebar-primary: oklch(0.205 0 0);\n --sidebar-primary-foreground: oklch(0.985 0 0);\n --sidebar-accent: oklch(0.97 0 0);\n --sidebar-accent-foreground: oklch(0.205 0 0);\n --sidebar-border: oklch(0.922 0 0);\n --sidebar-ring: oklch(0.708 0 0);\n}\n\n.dark {\n color-scheme: dark;\n --background: oklch(0.145 0 0);\n --foreground: oklch(0.985 0 0);\n --card: oklch(0.205 0 0);\n --card-foreground: oklch(0.985 0 0);\n --popover: oklch(0.205 0 0);\n --popover-foreground: oklch(0.985 0 0);\n --primary: oklch(0.922 0 0);\n --primary-foreground: oklch(0.205 0 0);\n --secondary: oklch(0.269 0 0);\n --secondary-foreground: oklch(0.985 0 0);\n --muted: oklch(0.269 0 0);\n --muted-foreground: oklch(0.708 0 0);\n --accent: oklch(0.269 0 0);\n --accent-foreground: oklch(0.985 0 0);\n --destructive: oklch(0.704 0.191 22.216);\n --border: oklch(1 0 0 / 10%);\n --input: oklch(1 0 0 / 15%);\n --ring: oklch(0.556 0 0);\n --chart-1: var(--color-green-400);\n --chart-2: var(--color-red-400);\n --chart-3: var(--color-blue-400);\n --chart-4: var(--color-purple-400);\n --chart-5: var(--color-yellow-400);\n --sidebar: oklch(0.205 0 0);\n --sidebar-foreground: oklch(0.985 0 0);\n --sidebar-primary: oklch(0.488 0.243 264.376);\n --sidebar-primary-foreground: oklch(0.985 0 0);\n --sidebar-accent: oklch(0.269 0 0);\n --sidebar-accent-foreground: oklch(0.985 0 0);\n --sidebar-border: oklch(1 0 0 / 10%);\n --sidebar-ring: oklch(0.556 0 0);\n}\n\n/* Isolated theme scopes for docs preview */\n/* Double attribute selector increases specificity to override .dark from ancestors */\n[data-theme=\"light\"][data-theme] {\n color-scheme: light;\n --wash: oklch(0.95 0 0);\n --background: oklch(1 0 0);\n --foreground: oklch(0.145 0 0);\n --card: oklch(1 0 0);\n --card-foreground: oklch(0.145 0 0);\n --popover: oklch(1 0 0);\n --popover-foreground: oklch(0.145 0 0);\n --primary: oklch(0.205 0 0);\n --primary-foreground: oklch(0.985 0 0);\n --secondary: oklch(0.97 0 0);\n --secondary-foreground: oklch(0.205 0 0);\n --muted: oklch(0.97 0 0);\n --muted-foreground: oklch(0.556 0 0);\n --accent: oklch(0.97 0 0);\n --accent-foreground: oklch(0.205 0 0);\n --destructive: oklch(0.577 0.245 27.325);\n --destructive-foreground: oklch(0.985 0 0);\n --border: oklch(0.922 0 0);\n --input: oklch(0.922 0 0);\n --ring: oklch(0.708 0 0);\n --chart-1: var(--color-green-500);\n --chart-2: var(--color-red-500);\n --chart-3: var(--color-blue-500);\n --chart-4: var(--color-purple-500);\n --chart-5: var(--color-yellow-500);\n}\n\n[data-theme=\"dark\"][data-theme] {\n color-scheme: dark;\n --wash: oklch(0.15 0 0);\n --background: oklch(0.145 0 0);\n --foreground: oklch(0.985 0 0);\n --card: oklch(0.205 0 0);\n --card-foreground: oklch(0.985 0 0);\n --popover: oklch(0.205 0 0);\n --popover-foreground: oklch(0.985 0 0);\n --primary: oklch(0.922 0 0);\n --primary-foreground: oklch(0.205 0 0);\n --secondary: oklch(0.269 0 0);\n --secondary-foreground: oklch(0.985 0 0);\n --muted: oklch(0.269 0 0);\n --muted-foreground: oklch(0.708 0 0);\n --accent: oklch(0.269 0 0);\n --accent-foreground: oklch(0.985 0 0);\n --destructive: oklch(0.704 0.191 22.216);\n --destructive-foreground: oklch(0.985 0 0);\n --border: oklch(1 0 0 / 10%);\n --input: oklch(1 0 0 / 15%);\n --ring: oklch(0.556 0 0);\n --chart-1: var(--color-green-400);\n --chart-2: var(--color-red-400);\n --chart-3: var(--color-blue-400);\n --chart-4: var(--color-purple-400);\n --chart-5: var(--color-yellow-400);\n}\n" }, { "path": "apps/www/app/styles/squircle.css", "content": "/* Squircle corners - progressively enhanced / only visible if supported */\n:root {\n --border-radius-multiplier: 1;\n}\n\n@supports (corner-shape: squircle) {\n :root {\n --border-radius-multiplier: 2;\n }\n}\n\n.squircle {\n corner-shape: squircle;\n border-radius: 30px !important;\n border-radius: calc(var(--radius) * var(--border-radius-multiplier));\n}\n" }, { "path": "apps/www/app/styles/theme-transition.css", "content": "/*\n Theme transition styles adapted from https://github.com/rudrodip/theme-toggle-effect\n Scoped to [data-theme-transition] to avoid conflicts with other view transitions.\n*/\n\n@layer base {\n @keyframes theme-scale {\n to {\n mask-size: 350vmax;\n }\n }\n\n [data-theme-transition]::view-transition-old(root),\n [data-theme-transition]::view-transition-new(root) {\n animation: none;\n mix-blend-mode: normal;\n }\n\n [data-theme-transition]::view-transition-new(root) {\n mask: url(\"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'%3E%3Cdefs%3E%3Cfilter id='blur' x='-100%25' y='-100%25' width='400%25' height='400%25'%3E%3CfeGaussianBlur stdDeviation='4'/%3E%3C/filter%3E%3C/defs%3E%3Ccircle cx='100' cy='0' r='40' fill='white' filter='url(%23blur)'/%3E%3C/svg%3E\")\n calc(100% + 10px) top / 0% no-repeat;\n mask-origin: content-box;\n animation: theme-scale 0.6s ease-in-out;\n animation-fill-mode: forwards;\n }\n\n [data-theme-transition]::view-transition-old(root) {\n z-index: -1;\n }\n\n [data-theme-transition].dark::view-transition-new(root) {\n z-index: 1;\n }\n}\n" }, { "path": "apps/www/components/assistant-ui/assistant-modal.tsx", "content": "\"use client\";\n\nimport { BotIcon, ChevronDownIcon } from \"lucide-react\";\n\nimport { type FC, forwardRef } from \"react\";\nimport { AssistantModalPrimitive } from \"@assistant-ui/react\";\n\nimport { Thread } from \"@/components/assistant-ui/thread\";\nimport { TooltipIconButton } from \"@/components/assistant-ui/tooltip-icon-button\";\n\nexport const AssistantModal: FC = () => {\n return (\n \n \n \n \n \n \n .aui-thread-root]:bg-inherit\"\n >\n \n \n \n );\n};\n\ntype AssistantModalButtonProps = { \"data-state\"?: \"open\" | \"closed\" };\n\nconst AssistantModalButton = forwardRef<\n HTMLButtonElement,\n AssistantModalButtonProps\n>(({ \"data-state\": state, ...rest }, ref) => {\n const tooltip = state === \"open\" ? \"Close Assistant\" : \"Open Assistant\";\n\n return (\n \n \n\n \n {tooltip}\n \n );\n});\n\nAssistantModalButton.displayName = \"AssistantModalButton\";\n" }, { "path": "apps/www/components/assistant-ui/attachment.tsx", "content": "\"use client\";\n\nimport { PropsWithChildren, useEffect, useState, type FC } from \"react\";\nimport Image from \"next/image\";\nimport { XIcon, PlusIcon, FileText } from \"lucide-react\";\nimport {\n AttachmentPrimitive,\n ComposerPrimitive,\n MessagePrimitive,\n useAuiState,\n useAui,\n} from \"@assistant-ui/react\";\nimport { useShallow } from \"zustand/shallow\";\nimport {\n Tooltip,\n TooltipContent,\n TooltipTrigger,\n} from \"@/components/ui/tooltip\";\nimport {\n Dialog,\n DialogTitle,\n DialogContent,\n DialogTrigger,\n} from \"@/components/ui/dialog\";\nimport { Avatar, AvatarImage, AvatarFallback } from \"@/components/ui/avatar\";\nimport { TooltipIconButton } from \"@/components/assistant-ui/tooltip-icon-button\";\nimport { cn } from \"@/lib/ui/cn\";\n\nconst useFileSrc = (file: File | undefined) => {\n const [src, setSrc] = useState(undefined);\n\n useEffect(() => {\n if (!file) {\n setSrc(undefined);\n return;\n }\n\n const objectUrl = URL.createObjectURL(file);\n setSrc(objectUrl);\n\n return () => {\n URL.revokeObjectURL(objectUrl);\n };\n }, [file]);\n\n return src;\n};\n\nconst useAttachmentSrc = () => {\n const { file, src } = useAuiState(\n useShallow(({ attachment }): { file?: File; src?: string } => {\n if (attachment.type !== \"image\") return {};\n if (attachment.file) return { file: attachment.file };\n const src = attachment.content?.filter((c) => c.type === \"image\")[0]\n ?.image;\n if (!src) return {};\n return { src };\n }),\n );\n\n return useFileSrc(file) ?? src;\n};\n\ntype AttachmentPreviewProps = {\n src: string;\n};\n\nconst AttachmentPreview: FC = ({ src }) => {\n const [isLoaded, setIsLoaded] = useState(false);\n return (\n setIsLoaded(true)}\n priority={false}\n />\n );\n};\n\nconst AttachmentPreviewDialog: FC = ({ children }) => {\n const src = useAttachmentSrc();\n\n if (!src) return children;\n\n return (\n \n \n {children}\n \n button]:rounded-full [&>button]:bg-foreground/60 [&>button]:p-1 [&>button]:opacity-100 [&>button]:ring-0! [&_svg]:text-background [&>button]:hover:[&_svg]:text-destructive\">\n \n Image Attachment Preview\n \n
\n \n
\n \n \n );\n};\n\nconst AttachmentThumb: FC = () => {\n const isImage = useAuiState(({ attachment }) => attachment.type === \"image\");\n const src = useAttachmentSrc();\n\n return (\n \n \n \n \n \n \n );\n};\n\nconst AttachmentUI: FC = () => {\n const aui = useAui();\n const isComposer = aui.attachment.source === \"composer\";\n\n const isImage = useAuiState(({ attachment }) => attachment.type === \"image\");\n const typeLabel = useAuiState(({ attachment }) => {\n const type = attachment.type;\n switch (type) {\n case \"image\":\n return \"Image\";\n case \"document\":\n return \"Document\";\n case \"file\":\n return \"File\";\n default:\n const _exhaustiveCheck: never = type;\n throw new Error(`Unknown attachment type: ${_exhaustiveCheck}`);\n }\n });\n\n return (\n \n #attachment-tile]:size-24\",\n )}\n >\n \n \n \n \n \n \n \n {isComposer && }\n \n \n \n \n \n );\n};\n\nconst AttachmentRemove: FC = () => {\n return (\n \n \n \n \n \n );\n};\n\nexport const UserMessageAttachments: FC = () => {\n return (\n
\n \n
\n );\n};\n\nexport const ComposerAttachments: FC = () => {\n return (\n
\n \n
\n );\n};\n\nexport const ComposerAddAttachment: FC = () => {\n return (\n \n \n \n \n \n );\n};\n" }, { "path": "apps/www/components/assistant-ui/markdown-text.tsx", "content": "\"use client\";\n\nimport \"@assistant-ui/react-markdown/styles/dot.css\";\n\nimport {\n type CodeHeaderProps,\n MarkdownTextPrimitive,\n unstable_memoizeMarkdownComponents as memoizeMarkdownComponents,\n useIsMarkdownCodeBlock,\n} from \"@assistant-ui/react-markdown\";\nimport remarkGfm from \"remark-gfm\";\nimport { type FC, memo, useState } from \"react\";\nimport { CheckIcon, CopyIcon } from \"lucide-react\";\n\nimport { TooltipIconButton } from \"@/components/assistant-ui/tooltip-icon-button\";\nimport { cn } from \"@/lib/ui/cn\";\n\nconst MarkdownTextImpl = () => {\n return (\n \n );\n};\n\nexport const MarkdownText = memo(MarkdownTextImpl);\n\nconst CodeHeader: FC = ({ language, code }) => {\n const { isCopied, copyToClipboard } = useCopyToClipboard();\n const onCopy = () => {\n if (!code || isCopied) return;\n copyToClipboard(code);\n };\n\n return (\n
\n span]:text-xs\">\n {language}\n \n \n {!isCopied && }\n {isCopied && }\n \n
\n );\n};\n\nconst useCopyToClipboard = ({\n copiedDuration = 3000,\n}: {\n copiedDuration?: number;\n} = {}) => {\n const [isCopied, setIsCopied] = useState(false);\n\n const copyToClipboard = (value: string) => {\n if (!value) return;\n\n navigator.clipboard.writeText(value).then(() => {\n setIsCopied(true);\n setTimeout(() => setIsCopied(false), copiedDuration);\n });\n };\n\n return { isCopied, copyToClipboard };\n};\n\nconst defaultComponents = memoizeMarkdownComponents({\n h1: ({ className, ...props }) => (\n \n ),\n h2: ({ className, ...props }) => (\n \n ),\n h3: ({ className, ...props }) => (\n \n ),\n h4: ({ className, ...props }) => (\n \n ),\n h5: ({ className, ...props }) => (\n \n ),\n h6: ({ className, ...props }) => (\n \n ),\n p: ({ className, ...props }) => (\n \n ),\n a: ({ className, ...props }) => (\n \n ),\n blockquote: ({ className, ...props }) => (\n \n ),\n ul: ({ className, ...props }) => (\n li]:mt-2\", className)}\n {...props}\n />\n ),\n ol: ({ className, ...props }) => (\n li]:mt-2\", className)}\n {...props}\n />\n ),\n hr: ({ className, ...props }) => (\n
\n ),\n table: ({ className, ...props }) => (\n \n ),\n th: ({ className, ...props }) => (\n \n ),\n td: ({ className, ...props }) => (\n \n ),\n tr: ({ className, ...props }) => (\n td:first-child]:rounded-bl-lg [&:last-child>td:last-child]:rounded-br-lg\",\n className,\n )}\n {...props}\n />\n ),\n sup: ({ className, ...props }) => (\n a]:text-xs [&>a]:no-underline\", className)}\n {...props}\n />\n ),\n pre: ({ className, ...props }) => (\n \n ),\n code: function Code({ className, ...props }) {\n const isCodeBlock = useIsMarkdownCodeBlock();\n return (\n \n );\n },\n CodeHeader,\n});\n" }, { "path": "apps/www/components/assistant-ui/reasoning.tsx", "content": "\"use client\";\n\nimport { BrainIcon, ChevronDownIcon } from \"lucide-react\";\nimport {\n memo,\n useCallback,\n useRef,\n useState,\n type FC,\n type PropsWithChildren,\n} from \"react\";\n\nimport {\n useScrollLock,\n useAuiState,\n type ReasoningMessagePartComponent,\n type ReasoningGroupComponent,\n} from \"@assistant-ui/react\";\n\nimport { MarkdownText } from \"@/components/assistant-ui/markdown-text\";\nimport {\n Collapsible,\n CollapsibleContent,\n CollapsibleTrigger,\n} from \"@/components/ui/collapsible\";\nimport { cn } from \"@/lib/ui/cn\";\n\nconst ANIMATION_DURATION = 200;\nconst SHIMMER_DURATION = 1000;\n\n/**\n * Root collapsible container that manages open/closed state and scroll lock.\n * Provides animation timing via CSS variable and prevents scroll jumps on collapse.\n */\nconst ReasoningRoot: FC<\n PropsWithChildren<{\n className?: string;\n }>\n> = ({ className, children }) => {\n const collapsibleRef = useRef(null);\n const [isOpen, setIsOpen] = useState(false);\n const lockScroll = useScrollLock(collapsibleRef, ANIMATION_DURATION);\n\n const handleOpenChange = useCallback(\n (open: boolean) => {\n if (!open) {\n lockScroll();\n }\n setIsOpen(open);\n },\n [lockScroll],\n );\n\n return (\n \n {children}\n \n );\n};\n\nReasoningRoot.displayName = \"ReasoningRoot\";\n\n/**\n * Gradient overlay that softens the bottom edge during expand/collapse animations.\n * Animation: Fades out with delay when opening and fades back in when closing.\n */\nconst GradientFade: FC<{ className?: string }> = ({ className }) => (\n \n);\n\n/**\n * Trigger button for the Reasoning collapsible.\n * Composed of icons, label, and text shimmer animation when reasoning is being streamed.\n */\nconst ReasoningTrigger: FC<{ active: boolean; className?: string }> = ({\n active,\n className,\n}) => (\n \n \n \n Reasoning\n {active ? (\n \n Reasoning\n \n ) : null}\n \n \n \n);\n\n/**\n * Collapsible content wrapper that handles height expand/collapse animation.\n * Animation: Height animates up (collapse) and down (expand).\n * Also provides group context for child animations via data-state attributes.\n */\nconst ReasoningContent: FC<\n PropsWithChildren<{\n className?: string;\n \"aria-busy\"?: boolean;\n }>\n> = ({ className, children, \"aria-busy\": ariaBusy }) => (\n \n {children}\n \n \n);\n\nReasoningContent.displayName = \"ReasoningContent\";\n\n/**\n * Text content wrapper that animates the reasoning text visibility.\n * Animation: Slides in from top + fades in when opening, reverses when closing.\n * Reacts to parent ReasoningContent's data-state via Radix group selectors.\n */\nconst ReasoningText: FC<\n PropsWithChildren<{\n className?: string;\n }>\n> = ({ className, children }) => (\n \n {children}\n \n);\n\nReasoningText.displayName = \"ReasoningText\";\n\n/**\n * Renders a single reasoning part's text with markdown support.\n * Consecutive reasoning parts are automatically grouped by ReasoningGroup.\n *\n * Pass Reasoning to MessagePrimitive.Parts in thread.tsx\n *\n * @example:\n * ```tsx\n * \n * ```\n */\nconst ReasoningImpl: ReasoningMessagePartComponent = () => ;\n\n/**\n * Collapsible wrapper that groups consecutive reasoning parts together.\n * Includes scroll lock to prevent page jumps during collapse animation.\n *\n * Pass ReasoningGroup to MessagePrimitive.Parts in thread.tsx\n *\n * @example:\n * ```tsx\n * \n * ```\n */\nconst ReasoningGroupImpl: ReasoningGroupComponent = ({\n children,\n startIndex,\n endIndex,\n}) => {\n /**\n * Detects if reasoning is currently streaming within this group's range.\n */\n const isReasoningStreaming = useAuiState(({ message }) => {\n if (message.status?.type !== \"running\") return false;\n const lastIndex = message.parts.length - 1;\n if (lastIndex < 0) return false;\n const lastType = message.parts[lastIndex]?.type;\n if (lastType !== \"reasoning\") return false;\n return lastIndex >= startIndex && lastIndex <= endIndex;\n });\n\n return (\n \n \n\n \n {children}\n \n \n );\n};\n\nexport const Reasoning = memo(ReasoningImpl);\nReasoning.displayName = \"Reasoning\";\n\nexport const ReasoningGroup = memo(ReasoningGroupImpl);\nReasoningGroup.displayName = \"ReasoningGroup\";\n" }, { "path": "apps/www/components/assistant-ui/shiki-highlighter.tsx", "content": "\"use client\";\n\nimport { FC } from \"react\";\nimport ShikiHighlighter, { type ShikiHighlighterProps } from \"react-shiki\";\nimport type { SyntaxHighlighterProps as AUIProps } from \"@assistant-ui/react-markdown\";\nimport { cn } from \"@/lib/ui/cn\";\n\n/**\n * Props for the SyntaxHighlighter component\n */\nexport type HighlighterProps = Omit<\n ShikiHighlighterProps,\n \"children\" | \"theme\"\n> & {\n theme?: ShikiHighlighterProps[\"theme\"];\n} & Pick;\n\n/**\n * SyntaxHighlighter component, using react-shiki\n * Use it by passing to `defaultComponents` in `markdown-text.tsx`\n *\n * @example\n * const defaultComponents = memoizeMarkdownComponents({\n * SyntaxHighlighter,\n * h1: //...\n * //...other elements...\n * });\n */\nexport const SyntaxHighlighter: FC = ({\n code,\n language,\n theme = { dark: \"kanagawa-wave\", light: \"kanagawa-lotus\" },\n className,\n addDefaultStyles = false, // assistant-ui requires custom base styles\n showLanguage = false, // assistant-ui/react-markdown handles language labels\n node: _node,\n components: _components,\n ...props\n}) => {\n return (\n \n {code.trim()}\n \n );\n};\n\nSyntaxHighlighter.displayName = \"SyntaxHighlighter\";\n" }, { "path": "apps/www/components/assistant-ui/thread-list.tsx", "content": "import type { FC } from \"react\";\nimport {\n ThreadListItemPrimitive,\n ThreadListPrimitive,\n useAuiState,\n} from \"@assistant-ui/react\";\nimport { ArchiveIcon, PlusIcon } from \"lucide-react\";\n\nimport { Button } from \"@/components/ui/button\";\nimport { TooltipIconButton } from \"@/components/assistant-ui/tooltip-icon-button\";\nimport { Skeleton } from \"@/components/ui/skeleton\";\n\nexport const ThreadList: FC = () => {\n return (\n \n \n \n \n );\n};\n\nconst ThreadListNew: FC = () => {\n return (\n \n \n \n New Thread\n \n \n );\n};\n\nconst ThreadListItems: FC = () => {\n const isLoading = useAuiState(({ threads }) => threads.isLoading);\n\n if (isLoading) {\n return ;\n }\n\n return ;\n};\n\nconst ThreadListSkeleton: FC = () => {\n return (\n <>\n {Array.from({ length: 5 }, (_, i) => (\n \n \n \n ))}\n \n );\n};\n\nconst ThreadListItem: FC = () => {\n return (\n \n \n \n \n \n \n );\n};\n\nconst ThreadListItemTitle: FC = () => {\n return (\n \n \n \n );\n};\n\nconst ThreadListItemArchive: FC = () => {\n return (\n \n \n \n \n \n );\n};\n" }, { "path": "apps/www/components/assistant-ui/thread.tsx", "content": "import {\n ComposerAddAttachment,\n ComposerAttachments,\n UserMessageAttachments,\n} from \"@/components/assistant-ui/attachment\";\nimport { MarkdownText } from \"@/components/assistant-ui/markdown-text\";\nimport { ToolFallback } from \"@/components/assistant-ui/tool-fallback\";\nimport { TooltipIconButton } from \"@/components/assistant-ui/tooltip-icon-button\";\nimport { Button } from \"@/components/ui/button\";\nimport { cn } from \"@/lib/ui/cn\";\nimport {\n ActionBarPrimitive,\n AssistantIf,\n BranchPickerPrimitive,\n ComposerPrimitive,\n ErrorPrimitive,\n MessagePrimitive,\n ThreadPrimitive,\n} from \"@assistant-ui/react\";\nimport {\n ArrowDownIcon,\n ArrowUpIcon,\n CheckIcon,\n ChevronLeftIcon,\n ChevronRightIcon,\n CopyIcon,\n DownloadIcon,\n PencilIcon,\n RefreshCwIcon,\n SquareIcon,\n} from \"lucide-react\";\nimport type { FC } from \"react\";\n\nexport const Thread: FC = () => {\n return (\n \n \n thread.isEmpty}>\n \n \n\n \n\n \n \n \n \n \n \n );\n};\n\nconst ThreadScrollToBottom: FC = () => {\n return (\n \n \n \n \n \n );\n};\n\nconst ThreadWelcome: FC = () => {\n return (\n
\n
\n
\n

\n Hello there!\n

\n

\n How can I help you today?\n

\n
\n
\n \n
\n );\n};\n\nconst SUGGESTIONS = [\n {\n title: \"What's the weather\",\n label: \"in San Francisco?\",\n prompt: \"What's the weather in San Francisco?\",\n },\n {\n title: \"Explain React hooks\",\n label: \"like useState and useEffect\",\n prompt: \"Explain React hooks like useState and useEffect\",\n },\n] as const;\n\nconst ThreadSuggestions: FC = () => {\n return (\n
\n {SUGGESTIONS.map((suggestion, index) => (\n \n \n \n \n {suggestion.title}\n \n \n {suggestion.label}\n \n \n \n
\n ))}\n \n );\n};\n\nconst Composer: FC = () => {\n return (\n \n \n \n \n \n \n \n );\n};\n\nconst ComposerAction: FC = () => {\n return (\n
\n \n\n !thread.isRunning}>\n \n \n \n \n \n \n\n thread.isRunning}>\n \n \n \n \n \n \n
\n );\n};\n\nconst MessageError: FC = () => {\n return (\n \n \n \n \n \n );\n};\n\nconst AssistantMessage: FC = () => {\n return (\n \n
\n \n \n
\n\n
\n \n \n
\n \n );\n};\n\nconst AssistantActionBar: FC = () => {\n return (\n \n \n \n message.isCopied}>\n \n \n !message.isCopied}>\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n );\n};\n\nconst UserMessage: FC = () => {\n return (\n *)]:col-start-2\"\n data-role=\"user\"\n >\n \n\n
\n
\n \n
\n
\n \n
\n
\n\n \n \n );\n};\n\nconst UserActionBar: FC = () => {\n return (\n \n \n \n \n \n \n \n );\n};\n\nconst EditComposer: FC = () => {\n return (\n \n \n \n
\n \n \n \n \n \n \n
\n \n \n );\n};\n\nconst BranchPicker: FC = ({\n className,\n ...rest\n}) => {\n return (\n \n \n \n \n \n \n \n / \n \n \n \n \n \n \n \n );\n};\n" }, { "path": "apps/www/components/assistant-ui/threadlist-sidebar.tsx", "content": "import * as React from \"react\";\nimport { Github, MessagesSquare } from \"lucide-react\";\nimport Link from \"next/link\";\nimport {\n Sidebar,\n SidebarContent,\n SidebarFooter,\n SidebarHeader,\n SidebarMenu,\n SidebarMenuButton,\n SidebarMenuItem,\n SidebarRail,\n} from \"@/components/ui/sidebar\";\nimport { ThreadList } from \"@/components/assistant-ui/thread-list\";\n\nexport function ThreadListSidebar({\n ...props\n}: React.ComponentProps) {\n return (\n \n \n
\n \n \n \n \n
\n \n
\n
\n \n assistant-ui\n \n
\n \n \n \n \n
\n \n \n \n \n \n \n \n \n \n \n
\n \n
\n
\n \n GitHub\n \n View Source\n
\n \n \n \n \n \n \n );\n}\n" }, { "path": "apps/www/components/assistant-ui/tool-fallback.tsx", "content": "import type { ToolCallMessagePartComponent } from \"@assistant-ui/react\";\nimport {\n CheckIcon,\n ChevronDownIcon,\n ChevronUpIcon,\n XCircleIcon,\n} from \"lucide-react\";\nimport { useState } from \"react\";\nimport { Button } from \"@/components/ui/button\";\nimport { cn } from \"@/lib/ui/cn\";\n\nexport const ToolFallback: ToolCallMessagePartComponent = ({\n toolName,\n argsText,\n result,\n status,\n}) => {\n const [isCollapsed, setIsCollapsed] = useState(true);\n\n const isCancelled =\n status?.type === \"incomplete\" && status.reason === \"cancelled\";\n const cancelledReason =\n isCancelled && status.error\n ? typeof status.error === \"string\"\n ? status.error\n : JSON.stringify(status.error)\n : null;\n\n return (\n \n
\n {isCancelled ? (\n \n ) : (\n \n )}\n \n {isCancelled ? \"Cancelled tool: \" : \"Used tool: \"}\n {toolName}\n

\n \n
\n {!isCollapsed && (\n
\n {cancelledReason && (\n
\n

\n Cancelled reason:\n

\n

\n {cancelledReason}\n

\n
\n )}\n \n 
\n              {argsText}\n
\n
\n {!isCancelled && result !== undefined && (\n
\n

\n Result:\n

\n 
\n                {typeof result === \"string\"\n                  ? result\n                  : JSON.stringify(result, null, 2)}\n
\n
\n )}\n \n )}\n \n );\n};\n" }, { "path": "apps/www/components/assistant-ui/tooltip-icon-button.tsx", "content": "\"use client\";\n\nimport { ComponentPropsWithRef, forwardRef } from \"react\";\nimport { Slottable } from \"@radix-ui/react-slot\";\n\nimport {\n Tooltip,\n TooltipContent,\n TooltipTrigger,\n} from \"@/components/ui/tooltip\";\nimport { Button } from \"@/components/ui/button\";\nimport { cn } from \"@/lib/ui/cn\";\n\nexport type TooltipIconButtonProps = ComponentPropsWithRef & {\n tooltip: string;\n side?: \"top\" | \"bottom\" | \"left\" | \"right\";\n};\n\nexport const TooltipIconButton = forwardRef<\n HTMLButtonElement,\n TooltipIconButtonProps\n>(({ children, tooltip, side = \"bottom\", className, ...rest }, ref) => {\n return (\n \n \n \n {children}\n {tooltip}\n \n \n {tooltip}\n \n );\n});\n\nTooltipIconButton.displayName = \"TooltipIconButton\";\n" }, { "path": "apps/www/components/tool-ui/approval-card/README.md", "content": "# Approval Card\n\nImplementation for the \"approval-card\" Tool UI surface.\n\n## Files\n\n- public exports: components/tool-ui/approval-card/index.tsx\n- serializable schema + parse helpers: components/tool-ui/approval-card/schema.ts\n\n## Companion assets\n\n- Docs page: app/docs/approval-card/content.mdx\n- Preset payload: lib/presets/approval-card.ts\n\n## Quick check\n\nRun this after edits:\n\npnpm test\n" }, { "path": "apps/www/components/tool-ui/approval-card/_adapter.tsx", "content": "/**\n * Adapter: UI and utility re-exports for copy-standalone portability.\n *\n * When copying this component to another project, update these imports\n * to match your project's paths:\n *\n * cn → Your Tailwind merge utility (e.g., \"@/lib/utils\", \"~/lib/cn\")\n */\n\nexport { cn } from \"@/lib/utils\";\nexport { Separator } from \"@/components/ui/separator\";\n" }, { "path": "apps/www/components/tool-ui/approval-card/approval-card.tsx", "content": "\"use client\";\n\nimport * as React from \"react\";\nimport { cn, Separator } from \"./_adapter\";\nimport type { ApprovalCardProps, ApprovalDecision } from \"./schema\";\nimport { ActionButtons } from \"../shared/action-buttons\";\nimport { type Action } from \"../shared/schema\";\n\nimport { icons, Check, X } from \"lucide-react\";\n\ntype LucideIcon = React.ComponentType<{ className?: string }>;\n\nfunction getLucideIcon(name: string): LucideIcon | null {\n const pascalName = name\n .split(\"-\")\n .map((part) => part.charAt(0).toUpperCase() + part.slice(1))\n .join(\"\");\n\n const Icon = icons[pascalName as keyof typeof icons];\n return Icon ?? null;\n}\n\ninterface ApprovalCardReceiptProps {\n id: string;\n title: string;\n choice: ApprovalDecision;\n actionLabel?: string;\n className?: string;\n}\n\nfunction ApprovalCardReceipt({\n id,\n title,\n choice,\n actionLabel,\n className,\n}: ApprovalCardReceiptProps) {\n const isApproved = choice === \"approved\";\n const displayLabel = actionLabel ?? (isApproved ? \"Approved\" : \"Denied\");\n\n return (\n \n \n \n {isApproved ? : }\n \n
\n {displayLabel}\n {title}\n
\n \n \n );\n}\n\nexport function ApprovalCard({\n id,\n title,\n description,\n icon,\n metadata,\n variant,\n confirmLabel,\n cancelLabel,\n className,\n choice,\n onConfirm,\n onCancel,\n}: ApprovalCardProps) {\n const resolvedVariant = variant ?? \"default\";\n const resolvedConfirmLabel = confirmLabel ?? \"Approve\";\n const resolvedCancelLabel = cancelLabel ?? \"Deny\";\n const Icon = icon ? getLucideIcon(icon) : null;\n\n const handleAction = React.useCallback(\n async (actionId: string) => {\n if (actionId === \"confirm\") {\n await onConfirm?.();\n } else if (actionId === \"cancel\") {\n await onCancel?.();\n }\n },\n [onConfirm, onCancel],\n );\n\n const handleKeyDown = React.useCallback(\n (event: React.KeyboardEvent) => {\n if (event.key === \"Escape\") {\n event.preventDefault();\n onCancel?.();\n }\n },\n [onCancel],\n );\n\n const isDestructive = resolvedVariant === \"destructive\";\n\n const actions: Action[] = [\n {\n id: \"cancel\",\n label: resolvedCancelLabel,\n variant: \"ghost\",\n },\n {\n id: \"confirm\",\n label: resolvedConfirmLabel,\n variant: isDestructive ? \"destructive\" : \"default\",\n },\n ];\n\n const viewKey = choice ? `receipt-${choice}` : \"interactive\";\n\n return (\n
\n {choice ? (\n \n ) : (\n \n
\n
\n {Icon && (\n \n \n \n )}\n
\n \n {title}\n \n {description && (\n \n {description}\n

\n )}\n
\n
\n\n {metadata && metadata.length > 0 && (\n <>\n \n
\n {metadata.map((item, index) => (\n
\n
\n {item.key}\n
\n
{item.value}
\n
\n ))}\n
\n \n )}\n
\n
\n \n
\n
\n )}\n \n );\n}\n" }, { "path": "apps/www/components/tool-ui/approval-card/index.tsx", "content": "export { ApprovalCard } from \"./approval-card\";\nexport {\n type SerializableApprovalCard,\n type ApprovalCardProps,\n type ApprovalDecision,\n type MetadataItem,\n} from \"./schema\";\n" }, { "path": "apps/www/components/tool-ui/approval-card/schema.ts", "content": "import { z } from \"zod\";\nimport { ToolUIIdSchema, ToolUIRoleSchema } from \"../shared/schema\";\nimport { defineToolUiContract } from \"../shared/contract\";\n\nexport const MetadataItemSchema = z.object({\n key: z.string().min(1),\n value: z.string(),\n});\n\nexport type MetadataItem = z.infer;\n\nexport const ApprovalDecisionSchema = z.enum([\"approved\", \"denied\"]);\n\nexport type ApprovalDecision = z.infer;\n\nexport const SerializableApprovalCardSchema = z.object({\n id: ToolUIIdSchema,\n role: ToolUIRoleSchema.optional(),\n\n title: z.string().min(1),\n description: z.string().optional(),\n icon: z.string().optional(),\n metadata: z.array(MetadataItemSchema).optional(),\n\n variant: z.enum([\"default\", \"destructive\"]).optional(),\n\n confirmLabel: z.string().optional(),\n cancelLabel: z.string().optional(),\n\n choice: ApprovalDecisionSchema.optional(),\n});\n\nexport type SerializableApprovalCard = z.infer<\n typeof SerializableApprovalCardSchema\n>;\n\nconst SerializableApprovalCardSchemaContract = defineToolUiContract(\n \"ApprovalCard\",\n SerializableApprovalCardSchema,\n);\n\nexport const parseSerializableApprovalCard: (\n input: unknown,\n) => SerializableApprovalCard = SerializableApprovalCardSchemaContract.parse;\n\nexport const safeParseSerializableApprovalCard: (\n input: unknown,\n) => SerializableApprovalCard | null =\n SerializableApprovalCardSchemaContract.safeParse;\nexport interface ApprovalCardProps extends SerializableApprovalCard {\n className?: string;\n onConfirm?: () => void | Promise;\n onCancel?: () => void | Promise;\n}\n" }, { "path": "apps/www/components/tool-ui/audio/README.md", "content": "# Audio\n\nImplementation for the \"audio\" Tool UI surface.\n\n## Files\n\n- public exports: components/tool-ui/audio/index.ts\n- serializable schema + parse helpers: components/tool-ui/audio/schema.ts\n\n## Companion assets\n\n- Docs page: app/docs/audio/content.mdx\n- Preset payload: lib/presets/audio.ts\n\n## Quick check\n\nRun this after edits:\n\npnpm test\n" }, { "path": "apps/www/components/tool-ui/audio/_adapter.tsx", "content": "/**\n * Adapter: UI and utility re-exports for copy-standalone portability.\n */\n\"use client\";\n\nexport { cn } from \"@/lib/utils\";\nexport { Button } from \"@/components/ui/button\";\nexport { Slider } from \"@/components/ui/slider\";\n" }, { "path": "apps/www/components/tool-ui/audio/audio.tsx", "content": "\"use client\";\n\nimport * as React from \"react\";\nimport { Pause, Play } from \"lucide-react\";\nimport { cn, Button, Slider } from \"./_adapter\";\n\nimport { AudioProvider, useAudio } from \"./context\";\nimport type { SerializableAudio, AudioVariant } from \"./schema\";\n\nconst FALLBACK_LOCALE = \"en-US\";\n\nfunction formatTime(seconds: number): string {\n if (!Number.isFinite(seconds)) return \"0:00\";\n const mins = Math.floor(seconds / 60);\n const secs = Math.floor(seconds % 60);\n return `${mins}:${secs.toString().padStart(2, \"0\")}`;\n}\n\nexport interface AudioProps extends SerializableAudio {\n variant?: AudioVariant;\n className?: string;\n onMediaEvent?: (type: \"play\" | \"pause\" | \"mute\" | \"unmute\") => void;\n}\n\nexport function Audio(props: AudioProps) {\n return (\n \n \n \n );\n}\n\ninterface PlayerControls {\n isPlaying: boolean;\n currentTime: number;\n duration: number;\n onPlayPause: () => void;\n onSeek: (value: number[]) => void;\n onSeekStart: () => void;\n onSeekEnd: () => void;\n}\n\ninterface FullPlayerProps {\n artwork?: string;\n title?: string;\n description?: string;\n controls: PlayerControls;\n}\n\nfunction FullPlayer({\n artwork,\n title,\n description,\n controls,\n}: FullPlayerProps) {\n return (\n
\n {artwork && (\n
\n \n
\n )}\n
\n {(title || description) && (\n
\n {title && (\n
\n {title}\n
\n )}\n {description && (\n
\n {description}\n
\n )}\n
\n )}\n
\n
\n \n
\n {formatTime(controls.currentTime)}\n {formatTime(controls.duration)}\n
\n
\n \n {controls.isPlaying ? (\n \n ) : (\n \n )}\n \n
\n
\n
\n );\n}\n\ninterface CompactPlayerProps {\n artwork?: string;\n title?: string;\n description?: string;\n controls: PlayerControls;\n}\n\nfunction CompactPlayer({\n artwork,\n title,\n description,\n controls,\n}: CompactPlayerProps) {\n const progress =\n controls.duration > 0\n ? (controls.currentTime / controls.duration) * 100\n : 0;\n\n return (\n
\n {artwork && (\n <>\n \n
\n \n )}\n {artwork && (\n
\n \n
\n )}\n
\n {title && (\n
\n {title}\n
\n )}\n {description && (\n
\n {description}\n
\n )}\n {controls.duration > 0 && (\n
\n
\n \n
\n \n {formatTime(controls.currentTime)}\n \n
\n )}\n
\n \n {controls.isPlaying ? (\n \n ) : (\n \n )}\n \n
\n );\n}\n\nfunction AudioInner(props: AudioProps) {\n const { variant = \"full\", className, onMediaEvent, ...serializable } = props;\n\n const {\n id,\n src,\n title,\n description,\n artwork,\n locale: providedLocale,\n } = serializable;\n\n const locale = providedLocale ?? FALLBACK_LOCALE;\n\n const { state, setState, setAudioElement } = useAudio();\n const audioRef = React.useRef(null);\n const [currentTime, setCurrentTime] = React.useState(0);\n const [duration, setDuration] = React.useState(0);\n const [isSeeking, setIsSeeking] = React.useState(false);\n\n React.useEffect(() => {\n setAudioElement(audioRef.current);\n return () => setAudioElement(null);\n }, [setAudioElement]);\n\n React.useEffect(() => {\n const audio = audioRef.current;\n if (!audio) return;\n if (state.playing && audio.paused) {\n void audio.play().catch(() => undefined);\n } else if (!state.playing && !audio.paused) {\n audio.pause();\n }\n }, [state.playing]);\n\n const handlePlayPause = () => {\n const audio = audioRef.current;\n if (!audio) return;\n if (audio.paused) {\n void audio.play().catch(() => undefined);\n } else {\n audio.pause();\n }\n };\n\n const handleSeek = (value: number[]) => {\n const audio = audioRef.current;\n if (!audio) return;\n const newTime = value[0];\n audio.currentTime = newTime;\n setCurrentTime(newTime);\n };\n\n const handleSeekStart = () => {\n setIsSeeking(true);\n };\n\n const handleSeekEnd = () => {\n setIsSeeking(false);\n };\n\n const controls: PlayerControls = {\n isPlaying: state.playing,\n currentTime,\n duration,\n onPlayPause: handlePlayPause,\n onSeek: handleSeek,\n onSeekStart: handleSeekStart,\n onSeekEnd: handleSeekEnd,\n };\n\n const isCompact = variant === \"compact\";\n\n return (\n \n \n {isCompact ? (\n \n ) : (\n \n )}\n\n {\n setState({ playing: true });\n onMediaEvent?.(\"play\");\n }}\n onPause={() => {\n setState({ playing: false });\n onMediaEvent?.(\"pause\");\n }}\n onTimeUpdate={(event) => {\n if (!isSeeking) {\n setCurrentTime(event.currentTarget.currentTime);\n }\n }}\n onLoadedMetadata={(event) => {\n setDuration(event.currentTarget.duration);\n }}\n onDurationChange={(event) => {\n setDuration(event.currentTarget.duration);\n }}\n />\n
\n \n );\n}\n" }, { "path": "apps/www/components/tool-ui/audio/context.tsx", "content": "\"use client\";\n\nimport * as React from \"react\";\n\nexport interface AudioPlaybackState {\n playing: boolean;\n muted: boolean;\n}\n\nexport interface AudioContextValue {\n state: AudioPlaybackState;\n setState: (patch: Partial) => void;\n audioElement: HTMLAudioElement | null;\n setAudioElement: (node: HTMLAudioElement | null) => void;\n}\n\nconst AudioContext = React.createContext(null);\n\nexport function useAudio() {\n const ctx = React.use(AudioContext);\n if (!ctx) {\n throw new Error(\"useAudio must be used within an \");\n }\n return ctx;\n}\n\nexport interface AudioProviderProps {\n children: React.ReactNode;\n defaultState?: Partial;\n}\n\nexport function AudioProvider({ children, defaultState }: AudioProviderProps) {\n const [state, setStateInternal] = React.useState({\n playing: defaultState?.playing ?? false,\n muted: defaultState?.muted ?? false,\n });\n\n const [audioElement, setAudioElement] =\n React.useState(null);\n\n const setState = React.useCallback((patch: Partial) => {\n setStateInternal((prev) => ({ ...prev, ...patch }));\n }, []);\n\n const value = React.useMemo(\n () => ({ state, setState, audioElement, setAudioElement }),\n [state, setState, audioElement],\n );\n\n return (\n {children}\n );\n}\n" }, { "path": "apps/www/components/tool-ui/audio/index.ts", "content": "export { Audio } from \"./audio\";\nexport type { AudioProps } from \"./audio\";\nexport { AudioProvider, useAudio } from \"./context\";\nexport type { AudioPlaybackState, AudioContextValue } from \"./context\";\nexport type { SerializableAudio, Source, AudioVariant } from \"./schema\";\n" }, { "path": "apps/www/components/tool-ui/audio/schema.ts", "content": "import { z } from \"zod\";\nimport { defineToolUiContract } from \"../shared/contract\";\nimport {\n ToolUIIdSchema,\n ToolUIReceiptSchema,\n ToolUIRoleSchema,\n} from \"../shared/schema\";\n\nexport const SourceSchema = z.object({\n label: z.string(),\n iconUrl: z.url().optional(),\n url: z.url().optional(),\n});\n\nexport type Source = z.infer;\n\nexport const SerializableAudioSchema = z.object({\n id: ToolUIIdSchema,\n role: ToolUIRoleSchema.optional(),\n receipt: ToolUIReceiptSchema.optional(),\n assetId: z.string(),\n src: z.url(),\n title: z.string().optional(),\n description: z.string().optional(),\n artwork: z.url().optional(),\n durationMs: z.number().int().positive().optional(),\n fileSizeBytes: z.number().int().positive().optional(),\n createdAt: z.string().datetime().optional(),\n locale: z.string().optional(),\n source: SourceSchema.optional(),\n});\n\nexport type SerializableAudio = z.infer;\n\nconst SerializableAudioSchemaContract = defineToolUiContract(\n \"Audio\",\n SerializableAudioSchema,\n);\n\nexport const parseSerializableAudio: (input: unknown) => SerializableAudio =\n SerializableAudioSchemaContract.parse;\n\nexport const safeParseSerializableAudio: (\n input: unknown,\n) => SerializableAudio | null = SerializableAudioSchemaContract.safeParse;\nexport type AudioVariant = \"full\" | \"compact\";\n" }, { "path": "apps/www/components/tool-ui/chart/README.md", "content": "# Chart\n\nImplementation for the \"chart\" Tool UI surface.\n\n## Files\n\n- public exports: components/tool-ui/chart/index.tsx\n- serializable schema + parse helpers: components/tool-ui/chart/schema.ts\n\n## Companion assets\n\n- Docs page: app/docs/chart/content.mdx\n- Preset payload: lib/presets/chart.ts\n\n## Quick check\n\nRun this after edits:\n\npnpm test\n" }, { "path": "apps/www/components/tool-ui/chart/_adapter.tsx", "content": "/**\n * Adapter: UI and utility re-exports for copy-standalone portability.\n *\n * When copying this component to another project, update these imports\n * to match your project's paths:\n *\n * cn → Your Tailwind merge utility (e.g., \"@/lib/utils\", \"~/lib/cn\")\n * Chart → shadcn/ui Chart (recharts wrapper)\n * Card → shadcn/ui Card\n */\n\nexport { cn } from \"@/lib/utils\";\nexport {\n ChartContainer,\n ChartTooltip,\n ChartTooltipContent,\n ChartLegend,\n ChartLegendContent,\n type ChartConfig,\n} from \"@/components/ui/chart\";\nexport {\n Card,\n CardHeader,\n CardTitle,\n CardDescription,\n CardContent,\n} from \"@/components/ui/card\";\n" }, { "path": "apps/www/components/tool-ui/chart/chart.tsx", "content": "\"use client\";\n\nimport { useMemo, useCallback, memo } from \"react\";\nimport {\n BarChart,\n LineChart,\n Bar,\n Line,\n XAxis,\n YAxis,\n CartesianGrid,\n} from \"recharts\";\n\nimport {\n cn,\n ChartContainer,\n ChartTooltip,\n ChartTooltipContent,\n ChartLegend,\n ChartLegendContent,\n Card,\n CardHeader,\n CardTitle,\n CardDescription,\n CardContent,\n type ChartConfig,\n} from \"./_adapter\";\nimport type { ChartProps } from \"./schema\";\n\nconst DEFAULT_COLORS = [\n \"var(--chart-1)\",\n \"var(--chart-2)\",\n \"var(--chart-3)\",\n \"var(--chart-4)\",\n \"var(--chart-5)\",\n];\n\nexport const Chart = memo(function Chart({\n id,\n type,\n title,\n description,\n data,\n xKey,\n series,\n colors,\n showLegend = false,\n showGrid = true,\n className,\n onDataPointClick,\n}: ChartProps) {\n const palette = colors?.length ? colors : DEFAULT_COLORS;\n\n const seriesColors = useMemo(\n () =>\n series.map(\n (seriesItem, index) =>\n seriesItem.color ?? palette[index % palette.length],\n ),\n [series, palette],\n );\n\n const chartConfig: ChartConfig = useMemo(\n () =>\n Object.fromEntries(\n series.map((seriesItem, index) => [\n seriesItem.key,\n {\n label: seriesItem.label,\n color: seriesColors[index],\n },\n ]),\n ),\n [series, seriesColors],\n );\n\n const handleDataPointClick = useCallback(\n (\n seriesKey: string,\n seriesLabel: string,\n payload: Record,\n index: number,\n ) => {\n onDataPointClick?.({\n seriesKey,\n seriesLabel,\n xValue: payload[xKey],\n yValue: payload[seriesKey],\n index,\n payload,\n });\n },\n [onDataPointClick, xKey],\n );\n\n const ChartComponent = type === \"bar\" ? BarChart : LineChart;\n\n const chartContent = (\n \n \n {showGrid && }\n \n \n } />\n {showLegend && } />}\n\n {type === \"bar\" &&\n series.map((s, i) => (\n \n handleDataPointClick(s.key, s.label, data.payload, data.index)\n }\n cursor={onDataPointClick ? \"pointer\" : undefined}\n />\n ))}\n\n {type === \"line\" &&\n series.map((s, i) => (\n ; index: number },\n ) => {\n handleDataPointClick(\n s.key,\n s.label,\n dotData.payload,\n dotData.index,\n );\n }) as unknown as React.MouseEventHandler,\n }}\n />\n ))}\n \n \n );\n\n return (\n \n {(title || description) && (\n \n {title && {title}}\n {description && (\n \n {description}\n \n )}\n \n )}\n {chartContent}\n \n );\n});\n" }, { "path": "apps/www/components/tool-ui/chart/index.tsx", "content": "export { Chart } from \"./chart\";\nexport {\n type ChartProps,\n type ChartSeries,\n type ChartDataPoint,\n type ChartClientProps,\n type SerializableChart,\n} from \"./schema\";\n" }, { "path": "apps/www/components/tool-ui/chart/schema.ts", "content": "import { z } from \"zod\";\nimport { defineToolUiContract } from \"../shared/contract\";\nimport {\n ToolUIIdSchema,\n ToolUIReceiptSchema,\n ToolUIRoleSchema,\n} from \"../shared/schema\";\n\nexport const ChartSeriesSchema = z.object({\n key: z.string().min(1),\n label: z.string().min(1),\n color: z.string().optional(),\n});\n\nexport type ChartSeries = z.infer;\n\nexport const ChartPropsSchema = z\n .object({\n id: ToolUIIdSchema,\n role: ToolUIRoleSchema.optional(),\n receipt: ToolUIReceiptSchema.optional(),\n type: z.enum([\"bar\", \"line\"]),\n title: z.string().optional(),\n description: z.string().optional(),\n data: z.array(z.record(z.string(), z.unknown())).min(1),\n xKey: z.string().min(1),\n series: z.array(ChartSeriesSchema).min(1),\n /** Color palette applied to series in order. Individual series.color takes precedence. */\n colors: z.array(z.string().min(1)).min(1).optional(),\n showLegend: z.boolean().optional(),\n showGrid: z.boolean().optional(),\n })\n .superRefine((value, ctx) => {\n const seenSeriesKeys = new Set();\n value.series.forEach((series, index) => {\n if (seenSeriesKeys.has(series.key)) {\n ctx.addIssue({\n code: \"custom\",\n path: [\"series\", index, \"key\"],\n message: `Duplicate series key \"${series.key}\".`,\n });\n return;\n }\n seenSeriesKeys.add(series.key);\n });\n\n value.data.forEach((row, rowIndex) => {\n if (!(value.xKey in row)) {\n ctx.addIssue({\n code: \"custom\",\n path: [\"data\", rowIndex, value.xKey],\n message: `Missing xKey \"${value.xKey}\" in data row.`,\n });\n } else {\n const xVal = row[value.xKey];\n const isValidX = typeof xVal === \"string\" || typeof xVal === \"number\";\n if (!isValidX) {\n ctx.addIssue({\n code: \"custom\",\n path: [\"data\", rowIndex, value.xKey],\n message: `Expected \"${value.xKey}\" to be a string or number.`,\n });\n }\n }\n\n value.series.forEach((series) => {\n if (!(series.key in row)) {\n ctx.addIssue({\n code: \"custom\",\n path: [\"data\", rowIndex, series.key],\n message: `Missing series key \"${series.key}\" in data row.`,\n });\n return;\n }\n\n const yVal = row[series.key];\n if (yVal === null) {\n return;\n }\n if (typeof yVal !== \"number\" || !Number.isFinite(yVal)) {\n ctx.addIssue({\n code: \"custom\",\n path: [\"data\", rowIndex, series.key],\n message: `Expected \"${series.key}\" to be a finite number (or null).`,\n });\n }\n });\n });\n });\n\nexport type ChartDataPoint = {\n seriesKey: string;\n seriesLabel: string;\n xValue: unknown;\n yValue: unknown;\n index: number;\n payload: Record;\n};\n\nexport type ChartClientProps = {\n className?: string;\n onDataPointClick?: (point: ChartDataPoint) => void;\n};\n\nexport type ChartProps = z.infer & ChartClientProps;\n\nexport const SerializableChartSchema = ChartPropsSchema;\n\nexport type SerializableChart = z.infer;\n\nconst SerializableChartSchemaContract = defineToolUiContract(\n \"Chart\",\n SerializableChartSchema,\n);\n\nexport const parseSerializableChart: (input: unknown) => SerializableChart =\n SerializableChartSchemaContract.parse;\n\nexport const safeParseSerializableChart: (\n input: unknown,\n) => SerializableChart | null = SerializableChartSchemaContract.safeParse;\n" }, { "path": "apps/www/components/tool-ui/citation/README.md", "content": "# Citation\n\nImplementation for the \"citation\" Tool UI surface.\n\n## Files\n\n- public exports: components/tool-ui/citation/index.ts\n- serializable schema + parse helpers: components/tool-ui/citation/schema.ts\n\n## Companion assets\n\n- Docs page: app/docs/citation/content.mdx\n- Preset payload: lib/presets/citation.ts\n\n## Quick check\n\nRun this after edits:\n\npnpm test\n" }, { "path": "apps/www/components/tool-ui/citation/_adapter.tsx", "content": "/**\n * Adapter: UI and utility re-exports for copy-standalone portability.\n *\n * When copying this component to another project, update these imports\n * to match your project's paths:\n *\n * cn → Your Tailwind merge utility (e.g., \"@/lib/utils\", \"~/lib/cn\")\n * Tooltip → shadcn/ui Tooltip (only needed for variant=\"inline\")\n * Popover → shadcn/ui Popover (only needed for CitationList)\n */\n\"use client\";\n\nexport { cn } from \"@/lib/utils\";\nexport {\n Popover,\n PopoverContent,\n PopoverTrigger,\n} from \"@/components/ui/popover\";\n" }, { "path": "apps/www/components/tool-ui/citation/citation-list.tsx", "content": "\"use client\";\n\nimport * as React from \"react\";\nimport type { LucideIcon } from \"lucide-react\";\nimport {\n FileText,\n Globe,\n Code2,\n Newspaper,\n Database,\n File,\n ExternalLink,\n} from \"lucide-react\";\nimport { cn, Popover, PopoverContent, PopoverTrigger } from \"./_adapter\";\nimport { Citation } from \"./citation\";\nimport type {\n SerializableCitation,\n CitationType,\n CitationVariant,\n} from \"./schema\";\nimport {\n openSafeNavigationHref,\n resolveSafeNavigationHref,\n} from \"../shared/media\";\n\nconst TYPE_ICONS: Record = {\n webpage: Globe,\n document: FileText,\n article: Newspaper,\n api: Database,\n code: Code2,\n other: File,\n};\n\nfunction useHoverPopover(delay = 100) {\n const [open, setOpen] = React.useState(false);\n const timeoutRef = React.useRef | null>(null);\n const containerRef = React.useRef(null);\n\n const handleMouseEnter = React.useCallback(() => {\n if (timeoutRef.current) clearTimeout(timeoutRef.current);\n timeoutRef.current = setTimeout(() => setOpen(true), delay);\n }, [delay]);\n\n const handleMouseLeave = React.useCallback(() => {\n if (timeoutRef.current) clearTimeout(timeoutRef.current);\n timeoutRef.current = setTimeout(() => setOpen(false), delay);\n }, [delay]);\n\n const handleFocus = React.useCallback(() => {\n if (timeoutRef.current) clearTimeout(timeoutRef.current);\n setOpen(true);\n }, []);\n\n const handleBlur = React.useCallback(\n (e: React.FocusEvent) => {\n const relatedTarget = e.relatedTarget as HTMLElement | null;\n if (containerRef.current?.contains(relatedTarget)) {\n return;\n }\n if (relatedTarget?.closest(\"[data-radix-popper-content-wrapper]\")) {\n return;\n }\n if (timeoutRef.current) clearTimeout(timeoutRef.current);\n timeoutRef.current = setTimeout(() => setOpen(false), delay);\n },\n [delay],\n );\n\n React.useEffect(() => {\n return () => {\n if (timeoutRef.current) clearTimeout(timeoutRef.current);\n };\n }, []);\n\n return {\n open,\n setOpen,\n containerRef,\n handleMouseEnter,\n handleMouseLeave,\n handleFocus,\n handleBlur,\n };\n}\n\nexport interface CitationListProps {\n id: string;\n citations: SerializableCitation[];\n variant?: CitationVariant;\n maxVisible?: number;\n className?: string;\n onNavigate?: (href: string, citation: SerializableCitation) => void;\n}\n\nexport function CitationList(props: CitationListProps) {\n const {\n id,\n citations,\n variant = \"default\",\n maxVisible,\n className,\n onNavigate,\n } = props;\n\n const shouldTruncate =\n maxVisible !== undefined && citations.length > maxVisible;\n const visibleCitations = shouldTruncate\n ? citations.slice(0, maxVisible)\n : citations;\n const overflowCitations = shouldTruncate ? citations.slice(maxVisible) : [];\n const overflowCount = overflowCitations.length;\n\n const wrapperClass =\n variant === \"inline\"\n ? \"flex flex-wrap items-center gap-1.5\"\n : \"flex flex-col gap-2\";\n\n // Stacked variant: overlapping favicons with popover\n if (variant === \"stacked\") {\n return (\n \n );\n }\n\n if (variant === \"default\") {\n return (\n \n {visibleCitations.map((citation) => (\n \n ))}\n {shouldTruncate && (\n \n )}\n \n );\n }\n\n return (\n \n {visibleCitations.map((citation) => (\n \n ))}\n {shouldTruncate && (\n \n )}\n \n );\n}\n\ninterface OverflowIndicatorProps {\n citations: SerializableCitation[];\n count: number;\n variant: CitationVariant;\n onNavigate?: (href: string, citation: SerializableCitation) => void;\n}\n\nfunction OverflowIndicator({\n citations,\n count,\n variant,\n onNavigate,\n}: OverflowIndicatorProps) {\n const { open, handleMouseEnter, handleMouseLeave } = useHoverPopover();\n\n const handleClick = (citation: SerializableCitation) => {\n const href = resolveSafeNavigationHref(citation.href);\n if (!href) return;\n if (onNavigate) {\n onNavigate(href, citation);\n } else {\n openSafeNavigationHref(href);\n }\n };\n\n const popoverContent = (\n
\n {citations.map((citation) => (\n handleClick(citation)}\n />\n ))}\n
\n );\n\n if (variant === \"inline\") {\n return (\n \n \n \n +{count} more\n \n \n e.preventDefault()}\n >\n {popoverContent}\n \n \n );\n }\n\n // Default variant\n return (\n \n \n \n \n +{count} more sources\n \n \n \n e.preventDefault()}\n >\n {popoverContent}\n \n \n );\n}\n\ninterface OverflowItemProps {\n citation: SerializableCitation;\n onClick: () => void;\n}\n\nfunction OverflowItem({ citation, onClick }: OverflowItemProps) {\n const TypeIcon = TYPE_ICONS[citation.type ?? \"webpage\"] ?? Globe;\n\n return (\n \n {citation.favicon ? (\n \n ) : (\n \n )}\n
\n

\n {citation.title}\n

\n

\n {citation.domain}\n

\n
\n \n \n );\n}\n\ninterface StackedCitationsProps {\n id: string;\n citations: SerializableCitation[];\n className?: string;\n onNavigate?: (href: string, citation: SerializableCitation) => void;\n}\n\nfunction StackedCitations({\n id,\n citations,\n className,\n onNavigate,\n}: StackedCitationsProps) {\n const {\n open,\n setOpen,\n containerRef,\n handleMouseEnter,\n handleMouseLeave,\n handleBlur,\n } = useHoverPopover();\n const maxIcons = 4;\n const visibleCitations = citations.slice(0, maxIcons);\n const remainingCount = Math.max(0, citations.length - maxIcons);\n\n const handleClick = (citation: SerializableCitation) => {\n const href = resolveSafeNavigationHref(citation.href);\n if (!href) return;\n if (onNavigate) {\n onNavigate(href, citation);\n } else {\n openSafeNavigationHref(href);\n }\n };\n\n return (\n
\n \n \n {\n if (e.key === \"Enter\" || e.key === \" \") {\n e.preventDefault();\n setOpen(true);\n }\n }}\n className={cn(\n \"isolate inline-flex cursor-pointer items-center gap-2 rounded-lg px-3 py-2\",\n \"bg-muted/40 outline-none\",\n \"transition-colors duration-150\",\n \"hover:bg-muted/70\",\n \"focus-visible:ring-ring focus-visible:ring-2\",\n className,\n )}\n >\n
\n {visibleCitations.map((citation, index) => {\n const TypeIcon =\n TYPE_ICONS[citation.type ?? \"webpage\"] ?? Globe;\n return (\n 0 && \"-ml-2\",\n )}\n style={{ zIndex: maxIcons - index }}\n >\n {citation.favicon ? (\n \n ) : (\n \n )}\n
\n );\n })}\n {remainingCount > 0 && (\n \n \n •••\n \n
\n )}\n \n \n {citations.length} source{citations.length !== 1 && \"s\"}\n \n \n \n setOpen(false)}\n >\n
\n {citations.map((citation) => (\n handleClick(citation)}\n />\n ))}\n
\n \n \n \n );\n}\n" }, { "path": "apps/www/components/tool-ui/citation/citation.tsx", "content": "\"use client\";\n\nimport * as React from \"react\";\nimport type { LucideIcon } from \"lucide-react\";\nimport {\n FileText,\n Globe,\n Code2,\n Newspaper,\n Database,\n File,\n ExternalLink,\n} from \"lucide-react\";\nimport { cn, Popover, PopoverContent, PopoverTrigger } from \"./_adapter\";\n\nimport { openSafeNavigationHref, sanitizeHref } from \"../shared/media\";\nimport type {\n SerializableCitation,\n CitationType,\n CitationVariant,\n} from \"./schema\";\n\nconst FALLBACK_LOCALE = \"en-US\";\n\nconst TYPE_ICONS: Record = {\n webpage: Globe,\n document: FileText,\n article: Newspaper,\n api: Database,\n code: Code2,\n other: File,\n};\n\nfunction extractDomain(url: string): string | undefined {\n try {\n const urlObj = new URL(url);\n return urlObj.hostname.replace(/^www\\./, \"\");\n } catch {\n return undefined;\n }\n}\n\nfunction formatDate(isoString: string, locale: string): string {\n try {\n const date = new Date(isoString);\n return date.toLocaleDateString(locale, {\n year: \"numeric\",\n month: \"short\",\n });\n } catch {\n return isoString;\n }\n}\n\nfunction useHoverPopover(delay = 100) {\n const [open, setOpen] = React.useState(false);\n const timeoutRef = React.useRef | null>(null);\n\n const handleMouseEnter = React.useCallback(() => {\n if (timeoutRef.current) clearTimeout(timeoutRef.current);\n timeoutRef.current = setTimeout(() => setOpen(true), delay);\n }, [delay]);\n\n const handleMouseLeave = React.useCallback(() => {\n if (timeoutRef.current) clearTimeout(timeoutRef.current);\n timeoutRef.current = setTimeout(() => setOpen(false), delay);\n }, [delay]);\n\n React.useEffect(() => {\n return () => {\n if (timeoutRef.current) clearTimeout(timeoutRef.current);\n };\n }, []);\n\n return { open, setOpen, handleMouseEnter, handleMouseLeave };\n}\n\nexport interface CitationProps extends SerializableCitation {\n variant?: CitationVariant;\n className?: string;\n onNavigate?: (href: string, citation: SerializableCitation) => void;\n}\n\nexport function Citation(props: CitationProps) {\n const { variant = \"default\", className, onNavigate, ...serializable } = props;\n\n const {\n id,\n href: rawHref,\n title,\n snippet,\n domain: providedDomain,\n favicon,\n author,\n publishedAt,\n type = \"webpage\",\n locale: providedLocale,\n } = serializable;\n\n const locale = providedLocale ?? FALLBACK_LOCALE;\n const sanitizedHref = sanitizeHref(rawHref);\n const domain = providedDomain ?? extractDomain(rawHref);\n\n const citationData: SerializableCitation = {\n ...serializable,\n href: sanitizedHref ?? rawHref,\n domain,\n locale,\n };\n\n const TypeIcon = TYPE_ICONS[type] ?? Globe;\n\n const handleClick = () => {\n if (!sanitizedHref) return;\n if (onNavigate) {\n onNavigate(sanitizedHref, citationData);\n } else {\n openSafeNavigationHref(sanitizedHref);\n }\n };\n\n const handleKeyDown = (e: React.KeyboardEvent) => {\n if (sanitizedHref && (e.key === \"Enter\" || e.key === \" \")) {\n e.preventDefault();\n handleClick();\n }\n };\n\n const iconElement = favicon ? (\n \n ) : (\n \n );\n\n const { open, handleMouseEnter, handleMouseLeave } = useHoverPopover();\n\n // Inline variant: compact chip with hover popover\n if (variant === \"inline\") {\n return (\n \n \n \n {iconElement}\n {domain}\n \n \n e.preventDefault()}\n onCloseAutoFocus={(e) => e.preventDefault()}\n onClick={handleClick}\n >\n
\n
\n {iconElement}\n {domain}\n
\n

{title}

\n {snippet && (\n

\n {snippet}\n

\n )}\n
\n \n \n );\n }\n\n // Default variant: full card\n return (\n \n \n
\n
\n
\n {iconElement}\n {domain}\n {(author || publishedAt) && (\n \n — \n {author}\n {author && publishedAt && \", \"}\n {publishedAt && (\n \n )}\n \n )}\n
\n {sanitizedHref && (\n \n )}\n
\n\n

\n \n {title}\n \n

\n\n {snippet && (\n

\n {snippet}\n

\n )}\n
\n \n \n );\n}\n" }, { "path": "apps/www/components/tool-ui/citation/index.ts", "content": "export { Citation } from \"./citation\";\nexport type { CitationProps } from \"./citation\";\nexport { CitationList } from \"./citation-list\";\nexport type { CitationListProps } from \"./citation-list\";\nexport type {\n SerializableCitation,\n CitationType,\n CitationVariant,\n} from \"./schema\";\n" }, { "path": "apps/www/components/tool-ui/citation/schema.ts", "content": "import { z } from \"zod\";\nimport { defineToolUiContract } from \"../shared/contract\";\nimport {\n ToolUIIdSchema,\n ToolUIReceiptSchema,\n ToolUIRoleSchema,\n} from \"../shared/schema\";\n\nexport const CitationTypeSchema = z.enum([\n \"webpage\",\n \"document\",\n \"article\",\n \"api\",\n \"code\",\n \"other\",\n]);\n\nexport type CitationType = z.infer;\n\nexport const CitationVariantSchema = z.enum([\"default\", \"inline\", \"stacked\"]);\n\nexport type CitationVariant = z.infer;\n\nexport const SerializableCitationSchema = z.object({\n id: ToolUIIdSchema,\n role: ToolUIRoleSchema.optional(),\n receipt: ToolUIReceiptSchema.optional(),\n href: z.string().url(),\n title: z.string(),\n snippet: z.string().optional(),\n domain: z.string().optional(),\n favicon: z.string().url().optional(),\n author: z.string().optional(),\n publishedAt: z.string().datetime().optional(),\n type: CitationTypeSchema.optional(),\n locale: z.string().optional(),\n});\n\nexport type SerializableCitation = z.infer;\n\nconst SerializableCitationSchemaContract = defineToolUiContract(\n \"Citation\",\n SerializableCitationSchema,\n);\n\nexport const parseSerializableCitation: (\n input: unknown,\n) => SerializableCitation = SerializableCitationSchemaContract.parse;\n\nexport const safeParseSerializableCitation: (\n input: unknown,\n) => SerializableCitation | null = SerializableCitationSchemaContract.safeParse;\n" }, { "path": "apps/www/components/tool-ui/code-block/README.md", "content": "# Code Block\n\nImplementation for the \"code-block\" Tool UI surface.\n\n## Files\n\n- public exports: components/tool-ui/code-block/index.tsx\n- serializable schema + parse helpers: components/tool-ui/code-block/schema.ts\n\n## Companion assets\n\n- Docs page: app/docs/code-block/content.mdx\n- Preset payload: lib/presets/code-block.ts\n\n## Quick check\n\nRun this after edits:\n\npnpm test\n" }, { "path": "apps/www/components/tool-ui/code-block/_adapter.tsx", "content": "/**\n * Adapter: UI and utility re-exports for copy-standalone portability.\n *\n * When copying this component to another project, update these imports\n * to match your project's paths:\n *\n * cn → Your Tailwind merge utility (e.g., \"@/lib/utils\", \"~/lib/cn\")\n * Button → shadcn/ui Button\n * Collapsible → shadcn/ui Collapsible\n */\n\nexport { cn } from \"@/lib/utils\";\nexport { Button } from \"@/components/ui/button\";\nexport { Collapsible, CollapsibleTrigger } from \"@/components/ui/collapsible\";\n" }, { "path": "apps/www/components/tool-ui/code-block/code-block.tsx", "content": "\"use client\";\n\nimport {\n useState,\n useCallback,\n useEffect,\n createContext,\n use,\n type ReactNode,\n} from \"react\";\nimport {\n createHighlighter,\n createJavaScriptRegexEngine,\n type Highlighter,\n} from \"shiki\";\nimport { Copy, Check, ChevronDown, ChevronUp } from \"lucide-react\";\nimport pierreDarkTheme from \"../shared/pierre-dark-theme.js\";\nimport pierreLightTheme from \"../shared/pierre-light-theme.js\";\nimport type { CodeBlockLineNumbersMode, CodeBlockProps } from \"./schema\";\nimport { useCopyToClipboard } from \"../shared/use-copy-to-clipboard\";\n\nimport { Button, cn, Collapsible, CollapsibleTrigger } from \"./_adapter\";\n\nconst COPY_ID = \"codeblock-code\";\nconst MAX_HTML_CACHE_ENTRIES = 64;\n\nlet highlighterPromise: Promise | null = null;\n\nfunction getHighlighter(): Promise {\n if (!highlighterPromise) {\n highlighterPromise = createHighlighter({\n themes: [pierreDarkTheme as never, pierreLightTheme as never],\n langs: [],\n engine: createJavaScriptRegexEngine(),\n });\n }\n return highlighterPromise;\n}\n\nconst htmlCache = new Map();\n\nfunction getCacheKey(\n code: string,\n language: string,\n theme: string,\n lineNumbers: CodeBlockLineNumbersMode,\n highlightLines?: number[],\n): string {\n return JSON.stringify({\n code,\n language,\n theme,\n lineNumbers,\n highlightLines: highlightLines ?? null,\n });\n}\n\nfunction setCachedHtml(cacheKey: string, html: string): void {\n if (htmlCache.has(cacheKey)) {\n htmlCache.set(cacheKey, html);\n return;\n }\n\n if (htmlCache.size >= MAX_HTML_CACHE_ENTRIES) {\n const oldestKey = htmlCache.keys().next().value;\n if (typeof oldestKey === \"string\") {\n htmlCache.delete(oldestKey);\n }\n }\n\n htmlCache.set(cacheKey, html);\n}\n\nconst LANGUAGE_DISPLAY_NAMES: Record = {\n typescript: \"TypeScript\",\n javascript: \"JavaScript\",\n python: \"Python\",\n tsx: \"TSX\",\n jsx: \"JSX\",\n json: \"JSON\",\n bash: \"Bash\",\n shell: \"Shell\",\n css: \"CSS\",\n html: \"HTML\",\n markdown: \"Markdown\",\n sql: \"SQL\",\n yaml: \"YAML\",\n go: \"Go\",\n rust: \"Rust\",\n text: \"Plain Text\",\n};\n\nfunction getLanguageDisplayName(lang: string): string {\n return LANGUAGE_DISPLAY_NAMES[lang.toLowerCase()] || lang.toUpperCase();\n}\n\nfunction getSystemTheme(): \"light\" | \"dark\" {\n if (typeof window === \"undefined\") return \"light\";\n return window.matchMedia?.(\"(prefers-color-scheme: dark)\").matches\n ? \"dark\"\n : \"light\";\n}\n\nfunction getDocumentTheme(): \"light\" | \"dark\" | null {\n if (typeof document === \"undefined\") return null;\n const root = document.documentElement;\n const dataTheme = root.getAttribute(\"data-theme\")?.toLowerCase();\n if (dataTheme === \"dark\") return \"dark\";\n if (dataTheme === \"light\") return \"light\";\n if (root.classList.contains(\"dark\")) return \"dark\";\n if (root.classList.contains(\"light\")) return \"light\";\n return null;\n}\n\nfunction useResolvedTheme(): \"light\" | \"dark\" {\n const [theme, setTheme] = useState<\"light\" | \"dark\">(() => {\n return getDocumentTheme() ?? getSystemTheme();\n });\n\n useEffect(() => {\n if (typeof window === \"undefined\" || typeof document === \"undefined\") {\n return;\n }\n\n const update = () => setTheme(getDocumentTheme() ?? getSystemTheme());\n\n const mql = window.matchMedia?.(\"(prefers-color-scheme: dark)\");\n mql?.addEventListener(\"change\", update);\n\n const observer = new MutationObserver(update);\n observer.observe(document.documentElement, {\n attributes: true,\n attributeFilter: [\"class\", \"data-theme\"],\n });\n\n return () => {\n mql?.removeEventListener(\"change\", update);\n observer.disconnect();\n };\n }, []);\n\n return theme;\n}\n\nexport type CodeBlockRootProps = CodeBlockProps & {\n children: ReactNode;\n expanded?: boolean;\n defaultExpanded?: boolean;\n onExpandedChange?: (expanded: boolean) => void;\n};\n\ntype CodeBlockSharedState = {\n id: string;\n code: string;\n language: string;\n filename?: string;\n highlightedHtml: string | null;\n isCopied: boolean;\n copyCode: () => void;\n lineCount: number;\n isCollapsed: boolean;\n shouldCollapse: boolean;\n toggleExpanded: () => void;\n};\n\nconst CodeBlockContext = createContext(null);\n\nfunction useCodeBlock(): CodeBlockSharedState {\n const context = use(CodeBlockContext);\n if (!context) {\n throw new Error(\n \"CodeBlock subcomponents must be used within .\",\n );\n }\n return context;\n}\n\nfunction CodeBlockRoot({\n id,\n code,\n language = \"text\",\n lineNumbers = \"visible\",\n filename,\n highlightLines,\n maxCollapsedLines,\n className,\n children,\n expanded: expandedProp,\n defaultExpanded = false,\n onExpandedChange,\n}: CodeBlockRootProps) {\n const resolvedTheme = useResolvedTheme();\n const [expandedState, setExpandedState] = useState(defaultExpanded);\n const { copiedId, copy } = useCopyToClipboard();\n const isCopied = copiedId === COPY_ID;\n\n const expanded = expandedProp ?? expandedState;\n const setExpanded = useCallback(\n (nextExpanded: boolean) => {\n if (expandedProp === undefined) {\n setExpandedState(nextExpanded);\n }\n onExpandedChange?.(nextExpanded);\n },\n [expandedProp, onExpandedChange],\n );\n\n const theme = resolvedTheme === \"dark\" ? \"pierre-dark\" : \"pierre-light\";\n const cacheKey = getCacheKey(\n code,\n language,\n theme,\n lineNumbers,\n highlightLines,\n );\n\n const [highlightedHtml, setHighlightedHtml] = useState(\n () => htmlCache.get(cacheKey) ?? null,\n );\n\n useEffect(() => {\n const cached = htmlCache.get(cacheKey);\n if (cached) {\n setHighlightedHtml(cached);\n return;\n }\n\n let cancelled = false;\n const showLineNumbers = lineNumbers === \"visible\";\n\n async function highlight() {\n if (!code) {\n if (!cancelled) setHighlightedHtml(\"\");\n return;\n }\n\n try {\n const highlighter = await getHighlighter();\n const loadedLangs = highlighter.getLoadedLanguages();\n\n if (!loadedLangs.includes(language)) {\n await highlighter.loadLanguage(\n language as Parameters[0],\n );\n }\n\n const lineCount = code.split(\"\\n\").length;\n const lineNumberWidth = `${String(lineCount).length + 0.5}ch`;\n\n const html = highlighter.codeToHtml(code, {\n lang: language,\n theme,\n transformers: [\n {\n line(node, line) {\n node.properties[\"data-line\"] = line;\n if (highlightLines?.includes(line)) {\n const highlightBg =\n resolvedTheme === \"dark\"\n ? \"rgba(255,255,255,0.1)\"\n : \"rgba(0,0,0,0.05)\";\n node.properties.style = `background:${highlightBg};`;\n }\n if (showLineNumbers) {\n node.children.unshift({\n type: \"element\",\n tagName: \"span\",\n properties: {\n style: `display:inline-block;width:${lineNumberWidth};text-align:right;margin-right:1.5em;user-select:none;opacity:0.5;`,\n \"aria-hidden\": \"true\",\n },\n children: [{ type: \"text\", value: String(line) }],\n });\n }\n },\n },\n ],\n });\n if (!cancelled) {\n setCachedHtml(cacheKey, html);\n setHighlightedHtml(html);\n }\n } catch {\n const escaped = code\n .replace(/&/g, \"&\")\n .replace(//g, \">\");\n if (!cancelled) {\n setHighlightedHtml(`
${escaped}
`);\n }\n }\n }\n void highlight();\n return () => {\n cancelled = true;\n };\n }, [\n cacheKey,\n code,\n language,\n lineNumbers,\n theme,\n highlightLines,\n resolvedTheme,\n ]);\n\n const lineCount = code.split(\"\\n\").length;\n const shouldCollapse = !!maxCollapsedLines && lineCount > maxCollapsedLines;\n const isCollapsed = shouldCollapse && !expanded;\n\n const copyCode = useCallback(() => {\n void copy(code, COPY_ID);\n }, [code, copy]);\n\n const toggleExpanded = useCallback(() => {\n setExpanded(!expanded);\n }, [expanded, setExpanded]);\n\n const state: CodeBlockSharedState = {\n id,\n code,\n language,\n filename,\n highlightedHtml,\n isCopied,\n copyCode,\n lineCount,\n shouldCollapse,\n isCollapsed,\n toggleExpanded,\n };\n\n return (\n \n \n
\n {children}\n
\n \n \n );\n}\n\nexport type CodeBlockSectionProps = {\n className?: string;\n};\n\nfunction CodeBlockHeader({ className }: CodeBlockSectionProps) {\n const { language, filename, isCopied, copyCode } = useCodeBlock();\n return (\n \n
\n \n {getLanguageDisplayName(language)}\n \n {filename && (\n <>\n •\n \n {filename}\n \n \n )}\n
\n \n {isCopied ? (\n \n ) : (\n \n )}\n \n \n );\n}\n\nfunction CodeBlockContent({ className }: CodeBlockSectionProps) {\n const { highlightedHtml, isCollapsed } = useCodeBlock();\n return (\n \n {highlightedHtml && (\n
\n )}\n
\n );\n}\n\nfunction CodeBlockCollapseToggle({ className }: CodeBlockSectionProps) {\n const { shouldCollapse, isCollapsed, toggleExpanded, lineCount } =\n useCodeBlock();\n\n if (!shouldCollapse) return null;\n\n return (\n \n \n {isCollapsed ? (\n <>\n \n Show all {lineCount} lines\n \n ) : (\n <>\n \n Collapse\n \n )}\n \n \n );\n}\n\nexport type CodeBlockComposedProps = Omit;\n\nfunction CodeBlockComposed(props: CodeBlockComposedProps) {\n return (\n \n \n \n \n \n );\n}\n\ntype CodeBlockComponent = typeof CodeBlockComposed & {\n Root: typeof CodeBlockRoot;\n Header: typeof CodeBlockHeader;\n Content: typeof CodeBlockContent;\n CollapseToggle: typeof CodeBlockCollapseToggle;\n};\n\nexport const CodeBlock = Object.assign(CodeBlockComposed, {\n Root: CodeBlockRoot,\n Header: CodeBlockHeader,\n Content: CodeBlockContent,\n CollapseToggle: CodeBlockCollapseToggle,\n}) as CodeBlockComponent;\n" }, { "path": "apps/www/components/tool-ui/code-block/index.tsx", "content": "export { CodeBlock } from \"./code-block\";\nexport type {\n CodeBlockRootProps,\n CodeBlockComposedProps,\n CodeBlockSectionProps,\n} from \"./code-block\";\nexport type {\n CodeBlockProps,\n CodeBlockLineNumbersMode,\n SerializableCodeBlock,\n} from \"./schema\";\n" }, { "path": "apps/www/components/tool-ui/code-block/schema.ts", "content": "import { z } from \"zod\";\nimport { defineToolUiContract } from \"../shared/contract\";\nimport {\n ToolUIIdSchema,\n ToolUIReceiptSchema,\n ToolUIRoleSchema,\n} from \"../shared/schema\";\n\nexport const CodeBlockPropsSchema = z.object({\n id: ToolUIIdSchema,\n role: ToolUIRoleSchema.optional(),\n receipt: ToolUIReceiptSchema.optional(),\n code: z.string(),\n language: z.string().trim().min(1).default(\"text\"),\n lineNumbers: z.enum([\"visible\", \"hidden\"]).default(\"visible\"),\n filename: z.string().optional(),\n highlightLines: z.array(z.number().int().positive()).optional(),\n maxCollapsedLines: z.number().min(1).optional(),\n className: z.string().optional(),\n});\n\nexport type CodeBlockProps = z.infer;\nexport type CodeBlockLineNumbersMode = CodeBlockProps[\"lineNumbers\"];\n\nexport const SerializableCodeBlockSchema = CodeBlockPropsSchema.omit({\n className: true,\n});\n\nexport type SerializableCodeBlock = z.infer;\n\nconst SerializableCodeBlockSchemaContract = defineToolUiContract(\n \"CodeBlock\",\n SerializableCodeBlockSchema,\n);\n\nexport const parseSerializableCodeBlock: (\n input: unknown,\n) => SerializableCodeBlock = SerializableCodeBlockSchemaContract.parse;\n\nexport const safeParseSerializableCodeBlock: (\n input: unknown,\n) => SerializableCodeBlock | null =\n SerializableCodeBlockSchemaContract.safeParse;\n" }, { "path": "apps/www/components/tool-ui/code-diff/_adapter.tsx", "content": "/**\n * Adapter: UI and utility re-exports for copy-standalone portability.\n *\n * When copying this component to another project, update these imports\n * to match your project's paths:\n *\n * cn -> Your Tailwind merge utility (e.g., \"@/lib/utils\", \"~/lib/cn\")\n * Button -> shadcn/ui Button\n * Collapsible -> shadcn/ui Collapsible\n */\n\nexport { cn } from \"@/lib/utils\";\nexport { Button } from \"@/components/ui/button\";\nexport { Collapsible, CollapsibleTrigger } from \"@/components/ui/collapsible\";\n" }, { "path": "apps/www/components/tool-ui/code-diff/code-diff.tsx", "content": "\"use client\";\n\nimport {\n useState,\n useCallback,\n useEffect,\n useMemo,\n createContext,\n use,\n type ReactNode,\n} from \"react\";\nimport {\n FileDiff as PierreFileDiff,\n PatchDiff as PierrePatchDiff,\n} from \"@pierre/diffs/react\";\nimport { parseDiffFromFile, RegisteredCustomThemes } from \"@pierre/diffs\";\nimport type { FileDiffMetadata, ThemesType } from \"@pierre/diffs\";\nimport { Copy, Check, ChevronDown, ChevronUp } from \"lucide-react\";\nimport type { CodeDiffProps } from \"./schema\";\nimport { useCopyToClipboard } from \"../shared/use-copy-to-clipboard\";\nimport { Button, cn, Collapsible, CollapsibleTrigger } from \"./_adapter\";\n\n/*\n * Pierre's shared_highlighter registers custom themes with dynamic imports\n * (`import(\"../themes/pierre-dark.js\")`) that fail under Turbopack because the\n * package `exports` field doesn't include those subpaths. We override the\n * RegisteredCustomThemes map entries with loaders that point to local vendored\n * theme files in `components/tool-ui/shared`, which Turbopack can resolve.\n */\nRegisteredCustomThemes.set(\"pierre-dark\", () =>\n import(\"../shared/pierre-dark-theme.js\").then((m) => m.default as never),\n);\nRegisteredCustomThemes.set(\"pierre-light\", () =>\n import(\"../shared/pierre-light-theme.js\").then((m) => m.default as never),\n);\n\nconst COPY_ID = \"codediff-code\";\n\n/* ── Theme detection (mirrors CodeBlock) ────────────────────────── */\n\nfunction getSystemTheme(): \"light\" | \"dark\" {\n if (typeof window === \"undefined\") return \"light\";\n return window.matchMedia?.(\"(prefers-color-scheme: dark)\").matches\n ? \"dark\"\n : \"light\";\n}\n\nfunction getDocumentTheme(): \"light\" | \"dark\" | null {\n if (typeof document === \"undefined\") return null;\n const root = document.documentElement;\n const dataTheme = root.getAttribute(\"data-theme\")?.toLowerCase();\n if (dataTheme === \"dark\") return \"dark\";\n if (dataTheme === \"light\") return \"light\";\n if (root.classList.contains(\"dark\")) return \"dark\";\n if (root.classList.contains(\"light\")) return \"light\";\n return null;\n}\n\nfunction useResolvedTheme(): \"light\" | \"dark\" {\n const [theme, setTheme] = useState<\"light\" | \"dark\">(() => {\n return getDocumentTheme() ?? getSystemTheme();\n });\n\n useEffect(() => {\n if (typeof window === \"undefined\" || typeof document === \"undefined\") {\n return;\n }\n\n const update = () => setTheme(getDocumentTheme() ?? getSystemTheme());\n\n const mql = window.matchMedia?.(\"(prefers-color-scheme: dark)\");\n mql?.addEventListener(\"change\", update);\n\n const observer = new MutationObserver(update);\n observer.observe(document.documentElement, {\n attributes: true,\n attributeFilter: [\"class\", \"data-theme\"],\n });\n\n return () => {\n mql?.removeEventListener(\"change\", update);\n observer.disconnect();\n };\n }, []);\n\n return theme;\n}\n\n/* ── Language display names (mirrors CodeBlock) ─────────────────── */\n\nconst LANGUAGE_DISPLAY_NAMES: Record = {\n typescript: \"TypeScript\",\n javascript: \"JavaScript\",\n python: \"Python\",\n tsx: \"TSX\",\n jsx: \"JSX\",\n json: \"JSON\",\n bash: \"Bash\",\n shell: \"Shell\",\n css: \"CSS\",\n html: \"HTML\",\n markdown: \"Markdown\",\n sql: \"SQL\",\n yaml: \"YAML\",\n go: \"Go\",\n rust: \"Rust\",\n text: \"Plain Text\",\n};\n\nfunction getLanguageDisplayName(lang: string): string {\n return LANGUAGE_DISPLAY_NAMES[lang.toLowerCase()] || lang.toUpperCase();\n}\n\n/* ── Shared context ─────────────────────────────────────────────── */\n\ntype CodeDiffSharedState = {\n id: string;\n isPatchMode: boolean;\n language: string;\n lineNumbers: \"visible\" | \"hidden\";\n filename?: string;\n diffStyle: \"unified\" | \"split\";\n copyableCode: string;\n isCopied: boolean;\n copyCode: () => void;\n isCollapsed: boolean;\n shouldCollapse: boolean;\n toggleExpanded: () => void;\n resolvedTheme: \"light\" | \"dark\";\n pierreThemes: ThemesType;\n fileDiffMetadata: FileDiffMetadata | null;\n patch: string | null;\n additions: number;\n deletions: number;\n};\n\nconst CodeDiffContext = createContext(null);\n\nfunction useCodeDiff(): CodeDiffSharedState {\n const context = use(CodeDiffContext);\n if (!context) {\n throw new Error(\n \"CodeDiff subcomponents must be used within .\",\n );\n }\n return context;\n}\n\n/* ── Subcomponents ──────────────────────────────────────────────── */\n\nexport type CodeDiffRootProps = CodeDiffProps & {\n children: ReactNode;\n expanded?: boolean;\n defaultExpanded?: boolean;\n onExpandedChange?: (expanded: boolean) => void;\n};\n\nfunction CodeDiffRoot({\n id,\n oldCode,\n newCode,\n patch,\n language = \"text\",\n filename,\n lineNumbers = \"visible\",\n diffStyle = \"unified\",\n maxCollapsedLines,\n className,\n children,\n expanded: expandedProp,\n defaultExpanded = false,\n onExpandedChange,\n}: CodeDiffRootProps) {\n const resolvedTheme = useResolvedTheme();\n const [expandedState, setExpandedState] = useState(defaultExpanded);\n const { copiedId, copy } = useCopyToClipboard();\n const isCopied = copiedId === COPY_ID;\n\n const expanded = expandedProp ?? expandedState;\n const setExpanded = useCallback(\n (nextExpanded: boolean) => {\n if (expandedProp === undefined) {\n setExpandedState(nextExpanded);\n }\n onExpandedChange?.(nextExpanded);\n },\n [expandedProp, onExpandedChange],\n );\n\n const pierreThemes: ThemesType = {\n dark: \"pierre-dark\",\n light: \"pierre-light\",\n };\n\n // Auto-detect mode: if `patch` is provided, use patch mode; otherwise files mode\n const isPatchMode = !!patch;\n\n const fileDiffMetadata = useMemo(() => {\n if (isPatchMode) return null;\n return parseDiffFromFile(\n {\n name: filename ?? \"file\",\n contents: oldCode ?? \"\",\n lang: language as never,\n },\n {\n name: filename ?? \"file\",\n contents: newCode ?? \"\",\n lang: language as never,\n },\n );\n }, [isPatchMode, oldCode, newCode, filename, language]);\n\n const copyableCode = isPatchMode ? (patch ?? \"\") : (newCode ?? oldCode ?? \"\");\n\n const lineCount = useMemo(() => {\n if (isPatchMode) {\n return (patch ?? \"\").split(\"\\n\").length;\n }\n if (fileDiffMetadata) {\n return fileDiffMetadata.unifiedLineCount;\n }\n return 0;\n }, [isPatchMode, patch, fileDiffMetadata]);\n\n const { additions, deletions } = useMemo(() => {\n if (!isPatchMode && fileDiffMetadata) {\n let add = 0;\n let del = 0;\n for (const hunk of fileDiffMetadata.hunks) {\n add += hunk.additionLines;\n del += hunk.deletionLines;\n }\n return { additions: add, deletions: del };\n }\n if (isPatchMode && patch) {\n let add = 0;\n let del = 0;\n for (const line of patch.split(\"\\n\")) {\n if (line.startsWith(\"+\") && !line.startsWith(\"+++ \")) add++;\n else if (line.startsWith(\"-\") && !line.startsWith(\"--- \")) del++;\n }\n return { additions: add, deletions: del };\n }\n return { additions: 0, deletions: 0 };\n }, [isPatchMode, fileDiffMetadata, patch]);\n\n const shouldCollapse = !!maxCollapsedLines && lineCount > maxCollapsedLines;\n const isCollapsed = shouldCollapse && !expanded;\n\n const copyCode = useCallback(() => {\n void copy(copyableCode, COPY_ID);\n }, [copyableCode, copy]);\n\n const toggleExpanded = useCallback(() => {\n setExpanded(!expanded);\n }, [expanded, setExpanded]);\n\n const state: CodeDiffSharedState = {\n id,\n isPatchMode,\n language,\n lineNumbers,\n filename,\n diffStyle,\n copyableCode,\n isCopied,\n copyCode,\n isCollapsed,\n shouldCollapse,\n toggleExpanded,\n resolvedTheme,\n pierreThemes,\n fileDiffMetadata,\n patch: isPatchMode ? (patch ?? null) : null,\n additions,\n deletions,\n };\n\n return (\n \n \n
\n {children}\n
\n \n \n );\n}\n\nexport type CodeDiffSectionProps = {\n className?: string;\n};\n\nfunction CodeDiffHeader({ className }: CodeDiffSectionProps) {\n const { language, filename, isCopied, copyCode, additions, deletions } =\n useCodeDiff();\n const hasChanges = additions > 0 || deletions > 0;\n return (\n \n
\n \n {getLanguageDisplayName(language)}\n \n {filename && (\n <>\n •\n \n {filename}\n \n \n )}\n
\n {hasChanges && (\n \n {additions > 0 && (\n +{additions}\n )}\n {additions > 0 && deletions > 0 && \" \"}\n {deletions > 0 && (\n -{deletions}\n )}\n \n )}\n \n {isCopied ? (\n \n ) : (\n \n )}\n \n \n );\n}\n\nfunction CodeDiffContent({ className }: CodeDiffSectionProps) {\n const {\n isPatchMode,\n diffStyle,\n lineNumbers,\n isCollapsed,\n resolvedTheme,\n pierreThemes,\n fileDiffMetadata,\n patch,\n } = useCodeDiff();\n\n const disableLineNumbers = lineNumbers === \"hidden\";\n\n return (\n \n {!isPatchMode && fileDiffMetadata && (\n \n )}\n {isPatchMode && patch && (\n \n )}\n \n );\n}\n\nfunction CodeDiffCollapseToggle({ className }: CodeDiffSectionProps) {\n const { shouldCollapse, isCollapsed, toggleExpanded } = useCodeDiff();\n\n if (!shouldCollapse) return null;\n\n return (\n \n \n {isCollapsed ? (\n <>\n \n Show full diff\n \n ) : (\n <>\n \n Collapse\n \n )}\n \n \n );\n}\n\n/* ── Composed preset (callable as a flat component) ─────────────── */\n\nexport type CodeDiffComposedProps = Omit;\n\nfunction CodeDiffComposed(props: CodeDiffComposedProps) {\n return (\n \n \n \n \n \n );\n}\n\n/* ── Compound export: CodeDiff is callable AND has subcomponents ── */\n\ntype CodeDiffComponent = typeof CodeDiffComposed & {\n Root: typeof CodeDiffRoot;\n Header: typeof CodeDiffHeader;\n Content: typeof CodeDiffContent;\n CollapseToggle: typeof CodeDiffCollapseToggle;\n};\n\nexport const CodeDiff = Object.assign(CodeDiffComposed, {\n Root: CodeDiffRoot,\n Header: CodeDiffHeader,\n Content: CodeDiffContent,\n CollapseToggle: CodeDiffCollapseToggle,\n}) as CodeDiffComponent;\n" }, { "path": "apps/www/components/tool-ui/code-diff/index.tsx", "content": "export { CodeDiff } from \"./code-diff\";\nexport type {\n CodeDiffRootProps,\n CodeDiffComposedProps,\n CodeDiffSectionProps,\n} from \"./code-diff\";\nexport type { CodeDiffProps, SerializableCodeDiff } from \"./schema\";\n" }, { "path": "apps/www/components/tool-ui/code-diff/schema.ts", "content": "import { z } from \"zod\";\nimport { defineToolUiContract } from \"../shared/contract\";\nimport {\n ToolUIIdSchema,\n ToolUIReceiptSchema,\n ToolUIRoleSchema,\n} from \"../shared/schema\";\n\nconst CodeDiffPropsSchemaBase = z.object({\n id: ToolUIIdSchema,\n role: ToolUIRoleSchema.optional(),\n receipt: ToolUIReceiptSchema.optional(),\n oldCode: z.string().optional(),\n newCode: z.string().optional(),\n patch: z.string().optional(),\n language: z.string().trim().min(1).default(\"text\"),\n filename: z.string().optional(),\n lineNumbers: z.enum([\"visible\", \"hidden\"]).default(\"visible\"),\n diffStyle: z.enum([\"unified\", \"split\"]).default(\"unified\"),\n maxCollapsedLines: z.number().min(1).optional(),\n className: z.string().optional(),\n});\n\nfunction validateCodeDiffInputMode(\n data: { patch?: string; oldCode?: string; newCode?: string },\n ctx: z.RefinementCtx,\n) {\n const hasPatch = !!data.patch;\n const hasFiles = !!data.oldCode || !!data.newCode;\n\n if (!hasPatch && !hasFiles) {\n ctx.addIssue({\n code: \"custom\",\n message:\n \"Provide either a patch string or at least one of oldCode/newCode\",\n });\n }\n\n if (hasPatch && hasFiles) {\n ctx.addIssue({\n code: \"custom\",\n message:\n \"Cannot mix patch mode with oldCode/newCode — use one or the other\",\n });\n }\n}\n\nexport const CodeDiffPropsSchema = CodeDiffPropsSchemaBase.superRefine(\n validateCodeDiffInputMode,\n);\n\nexport type CodeDiffProps = z.infer;\n\nexport const SerializableCodeDiffSchema = CodeDiffPropsSchemaBase.omit({\n className: true,\n}).superRefine(validateCodeDiffInputMode);\n\nexport type SerializableCodeDiff = z.infer;\n\nconst SerializableCodeDiffSchemaContract = defineToolUiContract(\n \"CodeDiff\",\n SerializableCodeDiffSchema,\n);\n\nexport const parseSerializableCodeDiff: (\n input: unknown,\n) => SerializableCodeDiff = SerializableCodeDiffSchemaContract.parse;\n\nexport const safeParseSerializableCodeDiff: (\n input: unknown,\n) => SerializableCodeDiff | null = SerializableCodeDiffSchemaContract.safeParse;\n" }, { "path": "apps/www/components/tool-ui/data-table/README.md", "content": "# Data Table\n\nImplementation for the \"data-table\" Tool UI surface.\n\n## Files\n\n- public exports: components/tool-ui/data-table/index.tsx\n- serializable schema + parse helpers: components/tool-ui/data-table/schema.ts\n\n## Companion assets\n\n- Docs page: app/docs/data-table/content.mdx\n- Preset payload: lib/presets/data-table.ts\n\n## Quick check\n\nRun this after edits:\n\npnpm test\n" }, { "path": "apps/www/components/tool-ui/data-table/_adapter.tsx", "content": "/**\n * Adapter: UI and utility re-exports for copy-standalone portability.\n *\n * When copying this component to another project, update these imports\n * to match your project's paths:\n *\n * cn → Your Tailwind merge utility (e.g., \"@/lib/utils\", \"~/lib/cn\")\n * Button → shadcn/ui Button\n * DropdownMenu → shadcn/ui DropdownMenu\n * Accordion → shadcn/ui Accordion\n * Tooltip → shadcn/ui Tooltip\n * Badge → shadcn/ui Badge\n * Table → shadcn/ui Table\n */\n\nexport { cn } from \"@/lib/utils\";\nexport { Button } from \"@/components/ui/button\";\nexport {\n DropdownMenu,\n DropdownMenuContent,\n DropdownMenuItem,\n DropdownMenuTrigger,\n} from \"@/components/ui/dropdown-menu\";\nexport {\n Accordion,\n AccordionContent,\n AccordionItem,\n AccordionTrigger,\n} from \"@/components/ui/accordion\";\nexport {\n Tooltip,\n TooltipContent,\n TooltipProvider,\n TooltipTrigger,\n} from \"@/components/ui/tooltip\";\nexport { Badge } from \"@/components/ui/badge\";\nexport {\n Table,\n TableHeader,\n TableBody,\n TableHead,\n TableRow,\n TableCell,\n} from \"@/components/ui/table\";\n" }, { "path": "apps/www/components/tool-ui/data-table/data-table.tsx", "content": "\"use client\";\n\nimport * as React from \"react\";\nimport {\n cn,\n Table,\n TableBody,\n TableRow,\n TableCell,\n TableHeader,\n TableHead,\n Button,\n Tooltip,\n TooltipContent,\n TooltipProvider,\n TooltipTrigger,\n Accordion,\n AccordionContent,\n AccordionItem,\n AccordionTrigger,\n} from \"./_adapter\";\nimport {\n sortData,\n createDataTableRowKeys,\n getDataTableMobileDescriptionId,\n} from \"./utilities\";\nimport { renderFormattedValue } from \"./formatters\";\nimport type {\n DataTableProps,\n DataTableContextValue,\n RowData,\n DataTableRowData,\n ColumnKey,\n Column,\n} from \"./types\";\nimport type { FormatConfig } from \"./formatters\";\n\nexport const DEFAULT_LOCALE = \"en-US\" as const;\n\nfunction isNumericFormat(format?: FormatConfig): boolean {\n const kind = format?.kind;\n return (\n kind === \"number\" ||\n kind === \"currency\" ||\n kind === \"percent\" ||\n kind === \"delta\"\n );\n}\n\nfunction getAlignmentClass(\n align?: \"left\" | \"right\" | \"center\",\n): string | undefined {\n if (align === \"right\") return \"text-right\";\n if (align === \"center\") return \"text-center\";\n return undefined;\n}\n\nconst DataTableContext = React.createContext<\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n DataTableContextValue | undefined\n>(undefined);\n\nexport function useDataTable() {\n const context = React.use(DataTableContext) as\n | DataTableContextValue\n | undefined;\n if (!context) {\n throw new Error(\"useDataTable must be used within \");\n }\n return context;\n}\n\ntype DataTableLayout = \"auto\" | \"table\" | \"cards\";\n\ntype DataTableBaseProps = DataTableProps & {\n layout: DataTableLayout;\n};\n\ntype DataTableProviderProps = Pick<\n DataTableProps,\n | \"columns\"\n | \"data\"\n | \"rowIdKey\"\n | \"defaultSort\"\n | \"sort\"\n | \"onSortChange\"\n | \"id\"\n | \"locale\"\n> & {\n children: React.ReactNode;\n};\n\nfunction DataTableProvider({\n columns,\n data: rawData,\n rowIdKey,\n defaultSort,\n sort: controlledSort,\n id,\n onSortChange,\n locale,\n children,\n}: DataTableProviderProps) {\n // Default locale avoids SSR/client formatting mismatches.\n const resolvedLocale = locale ?? DEFAULT_LOCALE;\n\n const [internalSortBy, setInternalSortBy] = React.useState<\n ColumnKey | undefined\n >(defaultSort?.by);\n const [internalSortDirection, setInternalSortDirection] = React.useState<\n \"asc\" | \"desc\" | undefined\n >(defaultSort?.direction);\n\n const sortBy = controlledSort?.by ?? internalSortBy;\n const sortDirection = controlledSort?.direction ?? internalSortDirection;\n\n const data = React.useMemo(() => {\n if (!sortBy || !sortDirection) return rawData;\n return sortData(rawData, sortBy, sortDirection, resolvedLocale);\n }, [rawData, sortBy, sortDirection, resolvedLocale]);\n\n const handleSort = React.useCallback(\n (key: ColumnKey) => {\n let newDirection: \"asc\" | \"desc\" | undefined;\n\n if (sortBy === key) {\n if (sortDirection === \"asc\") {\n newDirection = \"desc\";\n } else if (sortDirection === \"desc\") {\n newDirection = undefined;\n } else {\n newDirection = \"asc\";\n }\n } else {\n newDirection = \"asc\";\n }\n\n const next = {\n by: newDirection ? key : undefined,\n direction: newDirection,\n } as const;\n\n if (controlledSort) {\n onSortChange?.(next);\n } else {\n setInternalSortBy(next.by);\n setInternalSortDirection(next.direction);\n }\n },\n [sortBy, sortDirection, controlledSort, onSortChange],\n );\n\n const contextValue: DataTableContextValue = {\n columns,\n data,\n rowIdKey,\n sortBy,\n sortDirection,\n toggleSort: handleSort,\n id,\n locale: resolvedLocale,\n };\n\n return (\n \n {children}\n \n );\n}\n\ninterface DataTableLayoutProps {\n layout: DataTableLayout;\n emptyMessage: string;\n maxHeight?: string;\n className?: string;\n}\n\nfunction DataTableLayout({\n layout,\n emptyMessage,\n maxHeight,\n className,\n}: DataTableLayoutProps) {\n const { columns, data, rowIdKey, sortBy, sortDirection, id } = useDataTable();\n const rowKeys = React.useMemo(\n () =>\n createDataTableRowKeys(\n data as Array>,\n rowIdKey ? String(rowIdKey) : undefined,\n ),\n [data, rowIdKey],\n );\n const mobileDescriptionId = React.useMemo(\n () => getDataTableMobileDescriptionId(String(id ?? \"data-table\")),\n [id],\n );\n\n const sortAnnouncement = React.useMemo(() => {\n const col = columns.find((c) => c.key === sortBy);\n const label = col?.label ?? sortBy;\n return sortBy && sortDirection\n ? `Sorted by ${label}, ${sortDirection === \"asc\" ? \"ascending\" : \"descending\"}`\n : \"\";\n }, [columns, sortBy, sortDirection]);\n\n return (\n \n \n
\n \n \n {columns.length > 0 && (\n \n {columns.map((col) => (\n \n ))}\n \n )}\n {data.length === 0 ? (\n \n ) : (\n \n )}\n
\n
\n \n \n\n \n
\n Table data shown as expandable cards. Each card represents one row.\n {columns.length > 0 &&\n ` Columns: ${columns.map((c) => c.label).join(\", \")}.`}\n
\n\n {data.length === 0 ? (\n
\n {emptyMessage}\n
\n ) : (\n
\n {data.map((row, i) => {\n const rowKey = rowKeys[i];\n return (\n \n );\n })}\n
\n )}\n \n\n {sortAnnouncement && (\n
\n {sortAnnouncement}\n
\n )}\n \n );\n}\n\nfunction DataTableBase(\n props: DataTableBaseProps,\n) {\n const {\n columns,\n data,\n rowIdKey,\n defaultSort,\n sort,\n onSortChange,\n id,\n locale,\n layout,\n emptyMessage = \"No data available\",\n maxHeight,\n className,\n } = props;\n\n return (\n \n \n \n );\n}\n\nfunction DataTableRoot(props: DataTableProps) {\n return ;\n}\n\nfunction DataTableTable(props: DataTableProps) {\n return ;\n}\n\nfunction DataTableCards(props: DataTableProps) {\n return ;\n}\n\ntype DataTableComponent = {\n (props: DataTableProps): React.ReactElement;\n Table: typeof DataTableTable;\n Cards: typeof DataTableCards;\n Provider: typeof DataTableProvider;\n};\n\nexport const DataTable = Object.assign(DataTableRoot, {\n Table: DataTableTable,\n Cards: DataTableCards,\n Provider: DataTableProvider,\n}) as DataTableComponent;\n\nfunction DataTableContent() {\n return (\n <>\n \n \n \n );\n}\n\nfunction DataTableEmpty({ message }: { message: string }) {\n const { columns } = useDataTable();\n\n return (\n \n \n \n {message}\n \n \n \n );\n}\n\nfunction SortIcon({ state }: { state?: \"asc\" | \"desc\" }) {\n let char = \"⇅\";\n let className = \"opacity-20\";\n\n if (state === \"asc\") {\n char = \"↑\";\n className = \"\";\n }\n\n if (state === \"desc\") {\n char = \"↓\";\n className = \"\";\n }\n\n return (\n \n {char}\n \n );\n}\n\nfunction DataTableHeader() {\n const { columns } = useDataTable();\n\n return (\n \n \n \n {columns.map((column, columnIndex) => (\n \n ))}\n \n \n \n );\n}\n\ninterface DataTableHeadProps {\n column: Column;\n columnIndex?: number;\n totalColumns?: number;\n}\n\nfunction DataTableHead({\n column,\n columnIndex = 0,\n totalColumns = 1,\n}: DataTableHeadProps) {\n const { sortBy, sortDirection, toggleSort } = useDataTable();\n const isFirstColumn = columnIndex === 0;\n const isLastColumn = columnIndex === totalColumns - 1;\n\n const isSortable = column.sortable !== false;\n\n const isSorted = sortBy === column.key;\n const direction = isSorted ? sortDirection : undefined;\n const isDisabled = !isSortable;\n\n const handleClick = () => {\n if (!isDisabled && toggleSort) {\n toggleSort(column.key);\n }\n };\n\n const displayText = column.abbr || column.label;\n const shouldShowTooltip = column.abbr || displayText.length > 15;\n const isNumericKind = isNumericFormat(column.format);\n const align =\n column.align ??\n (columnIndex === 0 ? \"left\" : isNumericKind ? \"right\" : \"left\");\n const alignClass = getAlignmentClass(align);\n const buttonAlignClass = cn(\n \"min-w-0 gap-1 font-normal\",\n align === \"right\" && \"text-right\",\n align === \"center\" && \"text-center\",\n align === \"left\" && \"text-left\",\n );\n const labelAlignClass =\n align === \"right\"\n ? \"text-right\"\n : align === \"center\"\n ? \"text-center\"\n : \"text-left\";\n\n return (\n \n {\n if (isDisabled) return;\n if (e.key === \"Enter\" || e.key === \" \") {\n e.preventDefault();\n handleClick();\n }\n }}\n disabled={isDisabled}\n variant=\"ghost\"\n className={cn(\n buttonAlignClass,\n \"w-fit min-w-10\",\n isFirstColumn && \"pl-4\",\n isLastColumn && \"pr-4\",\n )}\n aria-label={\n `Sort by ${column.label}` +\n (isSorted && direction\n ? ` (${direction === \"asc\" ? \"ascending\" : \"descending\"})`\n : \"\")\n }\n aria-disabled={isDisabled || undefined}\n >\n {shouldShowTooltip ? (\n \n \n \n {column.abbr ? (\n \n {column.abbr}\n \n ) : (\n {column.label}\n )}\n \n \n \n

{column.label}

\n \n \n ) : (\n \n {column.label}\n \n )}\n {isSortable && }\n \n \n );\n}\n\nfunction DataTableBody() {\n const { data, rowIdKey } = useDataTable();\n const rowKeys = React.useMemo(\n () =>\n createDataTableRowKeys(\n data as Array>,\n rowIdKey ? String(rowIdKey) : undefined,\n ),\n [data, rowIdKey],\n );\n const hasWarnedRowKeyRef = React.useRef(false);\n\n React.useEffect(() => {\n if (hasWarnedRowKeyRef.current) return;\n if (process.env.NODE_ENV !== \"production\" && !rowIdKey && data.length > 0) {\n hasWarnedRowKeyRef.current = true;\n console.warn(\n \"[DataTable] Missing `rowIdKey` prop. Falling back to inferred/content-derived row keys. \" +\n \"Strongly recommended: Pass a `rowIdKey` prop that points to a unique identifier in your row data (e.g., 'id', 'uuid', 'symbol').\\n\" +\n 'Example: ',\n );\n }\n }, [rowIdKey, data.length]);\n\n return (\n \n {data.map((row, index) => {\n const rowKey = rowKeys[index];\n return ;\n })}\n \n );\n}\n\ninterface DataTableRowProps {\n row: DataTableRowData;\n className?: string;\n}\n\nfunction DataTableRow({ row, className }: DataTableRowProps) {\n const { columns } = useDataTable();\n\n return (\n \n {columns.map((column, columnIndex) => (\n \n ))}\n \n );\n}\n\ninterface DataTableCellProps {\n value:\n | string\n | number\n | boolean\n | null\n | (string | number | boolean | null)[];\n column: Column;\n row: DataTableRowData;\n className?: string;\n columnIndex?: number;\n}\n\nfunction DataTableCell({\n value,\n column,\n row,\n className,\n columnIndex = 0,\n}: DataTableCellProps) {\n const { locale } = useDataTable();\n const isNumericKind = isNumericFormat(column.format);\n const isNumericValue = typeof value === \"number\";\n const displayValue = renderFormattedValue({ value, column, row, locale });\n const align =\n column.align ??\n (columnIndex === 0\n ? \"left\"\n : isNumericKind || isNumericValue\n ? \"right\"\n : \"left\");\n const alignClass = getAlignmentClass(align);\n\n return (\n \n {displayValue}\n \n );\n}\n\nfunction categorizeColumns(columns: Column[]) {\n const primary: Column[] = [];\n const secondary: Column[] = [];\n\n let visibleColumnCount = 0;\n columns.forEach((col) => {\n if (col.hideOnMobile) return;\n\n if (col.priority === \"primary\") {\n primary.push(col);\n } else if (col.priority === \"secondary\") {\n secondary.push(col);\n } else if (col.priority === \"tertiary\") {\n return;\n } else {\n if (visibleColumnCount < 2) {\n primary.push(col);\n } else {\n secondary.push(col);\n }\n visibleColumnCount++;\n }\n });\n\n return { primary, secondary };\n}\n\ninterface DataTableAccordionCardProps {\n row: DataTableRowData;\n index: number;\n rowKey: string;\n isFirst?: boolean;\n}\n\nfunction getDataTableRowDomId(rowKey: string): string {\n return encodeURIComponent(rowKey).replace(/%/g, \"_\");\n}\n\nfunction DataTableAccordionCard({\n row,\n index,\n rowKey,\n isFirst = false,\n}: DataTableAccordionCardProps) {\n const { columns, locale } = useDataTable();\n\n const { primary, secondary } = React.useMemo(\n () => categorizeColumns(columns),\n [columns],\n );\n\n if (secondary.length === 0) {\n return (\n \n );\n }\n\n const primaryColumn = primary[0];\n const remainingPrimaryColumns = primary.slice(1);\n\n const stableRowId = getDataTableRowDomId(rowKey);\n\n const headingId = `row-${stableRowId}-heading`;\n const detailsId = `row-${stableRowId}-details`;\n const remainingPrimaryDataIds = remainingPrimaryColumns.map(\n (col) => `row-${stableRowId}-${String(col.key)}`,\n );\n\n const primaryValue = primaryColumn\n ? String(row[primaryColumn.key] ?? \"\")\n : \"\";\n const rowLabel = `Row ${index + 1}: ${primaryValue}`;\n const accordionItemId = `row-${stableRowId}`;\n\n return (\n \n \n 0 ? \"Expand for details\" : \"\"}`}\n >\n
\n {primaryColumn && (\n \n {renderFormattedValue({\n value: row[primaryColumn.key],\n column: primaryColumn,\n row,\n locale,\n })}\n
\n )}\n\n {remainingPrimaryColumns.length > 0 && (\n \n {remainingPrimaryColumns.map((col, idx) => (\n \n {col.label}:\n {col.label}:\n \n {renderFormattedValue({\n value: row[col.key],\n column: col,\n row,\n locale,\n })}\n \n \n ))}\n \n )}\n \n \n\n \n {secondary.length > 0 && (\n \n {secondary.map((col) => (\n \n \n {col.label}\n \n \n {renderFormattedValue({\n value: row[col.key],\n column: col,\n row,\n locale,\n })}\n \n \n ))}\n \n )}\n \n \n \n );\n}\n\n/**\n * Simple card with no accordion, for when there are only primary columns\n */\nfunction SimpleCard({\n row,\n columns,\n index,\n rowKey,\n isFirst = false,\n}: {\n row: DataTableRowData;\n columns: Column[];\n index: number;\n rowKey: string;\n isFirst?: boolean;\n}) {\n const { locale } = useDataTable();\n const primaryColumn = columns[0];\n const otherColumns = columns.slice(1);\n\n const stableRowId = getDataTableRowDomId(rowKey);\n\n const primaryValue = primaryColumn\n ? String(row[primaryColumn.key] ?? \"\")\n : \"\";\n const rowLabel = `Row ${index + 1}: ${primaryValue}`;\n\n return (\n \n {primaryColumn && (\n \n {renderFormattedValue({\n value: row[primaryColumn.key],\n column: primaryColumn,\n row,\n locale,\n })}\n \n )}\n\n {otherColumns.map((col) => (\n \n \n {col.label}:\n \n \n {renderFormattedValue({\n value: row[col.key],\n column: col,\n row,\n locale,\n })}\n \n \n ))}\n \n );\n}\n" }, { "path": "apps/www/components/tool-ui/data-table/formatters.tsx", "content": "\"use client\";\n\nimport * as React from \"react\";\nimport { cn, Badge, Tooltip, TooltipContent, TooltipTrigger } from \"./_adapter\";\nimport { resolveSafeNavigationHref } from \"../shared/media\";\n\ntype Tone = \"success\" | \"warning\" | \"danger\" | \"info\" | \"neutral\";\n\nexport type FormatConfig =\n | { kind: \"text\" }\n | {\n kind: \"number\";\n decimals?: number;\n unit?: string;\n compact?: boolean;\n showSign?: boolean;\n }\n | { kind: \"currency\"; currency: string; decimals?: number }\n | {\n kind: \"percent\";\n decimals?: number;\n showSign?: boolean;\n basis?: \"fraction\" | \"unit\";\n }\n | { kind: \"date\"; dateFormat?: \"short\" | \"long\" | \"relative\" }\n | {\n kind: \"delta\";\n decimals?: number;\n upIsPositive?: boolean;\n showSign?: boolean;\n }\n | {\n kind: \"status\";\n statusMap: Record;\n }\n | { kind: \"boolean\"; labels?: { true: string; false: string } }\n | { kind: \"link\"; hrefKey?: string; external?: boolean }\n | { kind: \"badge\"; colorMap?: Record }\n | { kind: \"array\"; maxVisible?: number };\n\ninterface DeltaValueProps {\n value: number;\n options?: Extract;\n locale?: string;\n}\n\nexport function DeltaValue({ value, options, locale }: DeltaValueProps) {\n const decimals = options?.decimals ?? 2;\n const upIsPositive = options?.upIsPositive ?? true;\n const showSign = options?.showSign ?? true;\n\n const isPositive = value > 0;\n const isNegative = value < 0;\n const isNeutral = value === 0;\n\n const isGood = upIsPositive ? isPositive : isNegative;\n const isBad = upIsPositive ? isNegative : isPositive;\n\n const colorClass = isGood\n ? \"text-green-700 dark:text-green-500\"\n : isBad\n ? \"text-destructive\"\n : \"text-muted-foreground\";\n\n const absValue = Math.abs(value);\n const formatted = new Intl.NumberFormat(locale, {\n minimumFractionDigits: decimals,\n maximumFractionDigits: decimals,\n }).format(absValue);\n\n const display =\n showSign && !isNeutral\n ? isNegative\n ? `-${formatted}`\n : `+${formatted}`\n : formatted;\n\n const arrow = isPositive ? \"↑\" : isNegative ? \"↓\" : \"\";\n\n return (\n \n {display}\n {!isNeutral && {arrow}}\n \n );\n}\n\ninterface StatusBadgeProps {\n value: string;\n options?: Extract;\n}\n\nexport function StatusBadge({ value, options }: StatusBadgeProps) {\n const config = options?.statusMap?.[value] ?? {\n tone: \"neutral\" as Tone,\n label: value,\n };\n const label = config.label ?? value;\n\n const variant =\n config.tone === \"danger\"\n ? \"destructive\"\n : config.tone === \"neutral\"\n ? \"outline\"\n : \"secondary\";\n\n return (\n \n {label}\n \n );\n}\n\ninterface CurrencyValueProps {\n value: number;\n options?: Extract;\n locale?: string;\n}\n\nexport function CurrencyValue({ value, options, locale }: CurrencyValueProps) {\n const currency = options?.currency ?? \"USD\";\n const decimals = options?.decimals ?? 2;\n\n const formatted = new Intl.NumberFormat(locale, {\n style: \"currency\",\n currency,\n minimumFractionDigits: decimals,\n maximumFractionDigits: decimals,\n }).format(value);\n\n return {formatted};\n}\n\ninterface PercentValueProps {\n value: number;\n options?: Extract;\n locale?: string;\n}\n\nexport function PercentValue({ value, options, locale }: PercentValueProps) {\n const decimals = options?.decimals ?? 2;\n const showSign = options?.showSign ?? false;\n const basis = options?.basis ?? \"fraction\";\n\n const numeric = basis === \"fraction\" ? value : value / 100;\n\n const formatted = new Intl.NumberFormat(locale, {\n style: \"percent\",\n minimumFractionDigits: decimals,\n maximumFractionDigits: decimals,\n signDisplay: showSign ? \"always\" : \"auto\",\n }).format(numeric);\n\n return {formatted};\n}\n\ninterface DateValueProps {\n value: string;\n options?: Extract;\n locale?: string;\n}\n\nexport function DateValue({ value, options, locale }: DateValueProps) {\n const dateFormat = options?.dateFormat ?? \"short\";\n const date = new Date(value);\n\n if (isNaN(date.getTime())) {\n return {value};\n }\n\n let formatted: string;\n\n if (dateFormat === \"relative\") {\n formatted = getRelativeTime(date, locale);\n } else if (dateFormat === \"long\") {\n formatted = new Intl.DateTimeFormat(locale, {\n year: \"numeric\",\n month: \"long\",\n day: \"numeric\",\n }).format(date);\n } else {\n formatted = new Intl.DateTimeFormat(locale, {\n year: \"numeric\",\n month: \"short\",\n day: \"numeric\",\n }).format(date);\n }\n\n const title = new Intl.DateTimeFormat(locale, {\n year: \"numeric\",\n month: \"long\",\n day: \"numeric\",\n hour: \"2-digit\",\n minute: \"2-digit\",\n }).format(date);\n\n return (\n \n {formatted}\n \n );\n}\n\nfunction getRelativeTime(date: Date, locale?: string): string {\n const now = new Date();\n const diffInSeconds = Math.trunc((date.getTime() - now.getTime()) / 1000);\n const absDiffInSeconds = Math.abs(diffInSeconds);\n\n if (absDiffInSeconds < 60) return \"just now\";\n\n const rtf = new Intl.RelativeTimeFormat(locale, { numeric: \"auto\" });\n\n if (absDiffInSeconds < 3600) {\n const mins = Math.trunc(diffInSeconds / 60);\n return rtf.format(mins, \"minute\");\n }\n if (absDiffInSeconds < 86400) {\n const hours = Math.trunc(diffInSeconds / 3600);\n return rtf.format(hours, \"hour\");\n }\n if (absDiffInSeconds < 604800) {\n const days = Math.trunc(diffInSeconds / 86400);\n return rtf.format(days, \"day\");\n }\n\n return new Intl.DateTimeFormat(locale, {\n year: \"numeric\",\n month: \"short\",\n day: \"numeric\",\n }).format(date);\n}\n\ninterface BooleanValueProps {\n value: boolean;\n options?: Extract;\n}\n\nexport function BooleanValue({ value, options }: BooleanValueProps) {\n const labels = options?.labels ?? { true: \"Yes\", false: \"No\" };\n const label = value ? labels.true : labels.false;\n const variant = value ? \"secondary\" : \"outline\";\n\n return {label};\n}\n\ninterface LinkValueProps {\n value: string;\n options?: Extract;\n row?: Record<\n string,\n string | number | boolean | null | (string | number | boolean | null)[]\n >;\n}\n\nexport function LinkValue({ value, options, row }: LinkValueProps) {\n const rawHref =\n options?.hrefKey && row ? String(row[options.hrefKey] ?? \"\") : value;\n const href = resolveSafeNavigationHref(rawHref);\n const external = options?.external ?? false;\n\n if (!href) {\n return {value};\n }\n\n return (\n e.stopPropagation()}\n >\n {value}\n {external && (\n \n ↗\n \n )}\n \n );\n}\n\ninterface NumberValueProps {\n value: number;\n options?: Extract;\n locale?: string;\n}\n\nexport function NumberValue({ value, options, locale }: NumberValueProps) {\n const decimals = options?.decimals ?? 0;\n const unit = options?.unit ?? \"\";\n const compact = options?.compact ?? false;\n const showSign = options?.showSign ?? false;\n\n const formatted = new Intl.NumberFormat(locale, {\n minimumFractionDigits: decimals,\n maximumFractionDigits: decimals,\n notation: compact ? \"compact\" : \"standard\",\n }).format(value);\n\n const display = showSign && value > 0 ? `+${formatted}` : formatted;\n\n return (\n \n {display}\n {unit}\n \n );\n}\n\ninterface BadgeValueProps {\n value: string;\n options?: Extract;\n}\n\nexport function BadgeValue({ value, options }: BadgeValueProps) {\n const tone = options?.colorMap?.[value] ?? \"neutral\";\n\n const variant =\n tone === \"danger\"\n ? \"destructive\"\n : tone === \"neutral\"\n ? \"outline\"\n : \"secondary\";\n\n return (\n \n {value}\n \n );\n}\n\ninterface ArrayValueProps {\n value: (string | number | boolean | null)[] | string;\n options?: Extract;\n}\n\nexport function ArrayValue({ value, options }: ArrayValueProps) {\n const maxVisible = options?.maxVisible ?? 3;\n const items: (string | number | boolean | null)[] = Array.isArray(value)\n ? value\n : typeof value === \"string\"\n ? value.split(\",\").map((s) => s.trim())\n : [];\n\n if (items.length === 0) {\n return —;\n }\n\n const visible = items.slice(0, maxVisible);\n const remaining = items.length - maxVisible;\n\n const hidden = items.slice(maxVisible);\n\n return (\n \n {visible.map((item, i) => (\n \n {item === null ? \"null\" : String(item)}\n \n ))}\n {remaining > 0 && (\n \n \n \n +{remaining} more\n \n \n \n {hidden\n .map((item) => (item === null ? \"null\" : String(item)))\n .join(\", \")}\n \n \n )}\n \n );\n}\n\ninterface RenderFormattedValueParams {\n value:\n | string\n | number\n | boolean\n | null\n | (string | number | boolean | null)[];\n column: { format?: FormatConfig };\n row?: Record<\n string,\n string | number | boolean | null | (string | number | boolean | null)[]\n >;\n locale?: string;\n}\n\nexport function renderFormattedValue({\n value,\n column,\n row,\n locale,\n}: RenderFormattedValueParams): React.ReactNode {\n if (value == null || value === \"\") {\n return —;\n }\n\n const fmt = column.format;\n\n switch (fmt?.kind) {\n case \"delta\":\n return ;\n case \"status\":\n return ;\n case \"currency\":\n return (\n \n );\n case \"percent\":\n return (\n \n );\n case \"date\":\n return ;\n case \"boolean\":\n return ;\n case \"link\":\n return ;\n case \"number\":\n return (\n \n );\n case \"badge\":\n return ;\n case \"array\":\n return (\n \n );\n case \"text\":\n default:\n return String(value);\n }\n}\n" }, { "path": "apps/www/components/tool-ui/data-table/index.tsx", "content": "export { DataTable, useDataTable } from \"./data-table\";\n\nexport { renderFormattedValue } from \"./formatters\";\nexport {\n NumberValue,\n CurrencyValue,\n PercentValue,\n DeltaValue,\n DateValue,\n BooleanValue,\n LinkValue,\n BadgeValue,\n StatusBadge,\n ArrayValue,\n} from \"./formatters\";\n\nexport type {\n Column,\n DataTableProps,\n DataTableSerializableProps,\n DataTableClientProps,\n DataTableRowData,\n RowPrimitive,\n RowData,\n ColumnKey,\n} from \"./types\";\nexport type { FormatConfig } from \"./formatters\";\n\nexport { sortData, parseNumericLike } from \"./utilities\";\n" }, { "path": "apps/www/components/tool-ui/data-table/schema.ts", "content": "import { z } from \"zod\";\nimport {\n ToolUIIdSchema,\n ToolUIReceiptSchema,\n ToolUIRoleSchema,\n} from \"../shared/schema\";\nimport { defineToolUiContract } from \"../shared/contract\";\nimport type { Column, DataTableProps, RowData } from \"./types\";\n\nconst AlignEnum = z.enum([\"left\", \"right\", \"center\"]);\nconst PriorityEnum = z.enum([\"primary\", \"secondary\", \"tertiary\"]);\n\nconst formatSchema = z.discriminatedUnion(\"kind\", [\n z.object({ kind: z.literal(\"text\") }),\n z.object({\n kind: z.literal(\"number\"),\n decimals: z.number().optional(),\n unit: z.string().optional(),\n compact: z.boolean().optional(),\n showSign: z.boolean().optional(),\n }),\n z.object({\n kind: z.literal(\"currency\"),\n currency: z.string(),\n decimals: z.number().optional(),\n }),\n z.object({\n kind: z.literal(\"percent\"),\n decimals: z.number().optional(),\n showSign: z.boolean().optional(),\n basis: z.enum([\"fraction\", \"unit\"]).optional(),\n }),\n z.object({\n kind: z.literal(\"date\"),\n dateFormat: z.enum([\"short\", \"long\", \"relative\"]).optional(),\n }),\n z.object({\n kind: z.literal(\"delta\"),\n decimals: z.number().optional(),\n upIsPositive: z.boolean().optional(),\n showSign: z.boolean().optional(),\n }),\n z.object({\n kind: z.literal(\"status\"),\n statusMap: z.record(\n z.string(),\n z.object({\n tone: z.enum([\"success\", \"warning\", \"danger\", \"info\", \"neutral\"]),\n label: z.string().optional(),\n }),\n ),\n }),\n z.object({\n kind: z.literal(\"boolean\"),\n labels: z\n .object({\n true: z.string(),\n false: z.string(),\n })\n .optional(),\n }),\n z.object({\n kind: z.literal(\"link\"),\n hrefKey: z.string().optional(),\n external: z.boolean().optional(),\n }),\n z.object({\n kind: z.literal(\"badge\"),\n colorMap: z\n .record(\n z.string(),\n z.enum([\"success\", \"warning\", \"danger\", \"info\", \"neutral\"]),\n )\n .optional(),\n }),\n z.object({\n kind: z.literal(\"array\"),\n maxVisible: z.number().optional(),\n }),\n]);\n\nexport const serializableColumnSchema = z.object({\n key: z.string(),\n label: z.string(),\n abbr: z.string().optional(),\n sortable: z.boolean().optional(),\n align: AlignEnum.optional(),\n width: z.string().optional(),\n truncate: z.boolean().optional(),\n priority: PriorityEnum.optional(),\n hideOnMobile: z.boolean().optional(),\n format: formatSchema.optional(),\n});\n\nconst JsonPrimitiveSchema = z.union([\n z.string(),\n z.number(),\n z.boolean(),\n z.null(),\n]);\n\n/**\n * Schema for serializable row data.\n *\n * Supports:\n * - Primitives: string, number, boolean, null\n * - Arrays of primitives: string[], number[], boolean[], or mixed primitive arrays\n *\n * Does NOT support:\n * - Functions\n * - Class instances (Date, Map, Set, etc.)\n * - Plain objects (use format configs instead)\n *\n * @example\n * Valid row data:\n * ```json\n * {\n * \"name\": \"Widget\",\n * \"price\": 29.99,\n * \"active\": true,\n * \"tags\": [\"electronics\", \"featured\"],\n * \"metrics\": [1.2, 3.4, 5.6],\n * \"flags\": [true, false, true],\n * \"mixed\": [\"label\", 42, true]\n * }\n * ```\n */\nexport const serializableDataSchema = z.record(\n z.string(),\n z.union([JsonPrimitiveSchema, z.array(JsonPrimitiveSchema)]),\n);\n\n/**\n * Zod schema for validating DataTable payloads from LLM tool calls.\n *\n * This schema validates the serializable parts of a DataTable:\n * - id: Unique identifier for this tool UI in the conversation\n * - columns: Column definitions (keys, labels, formatting, etc.)\n * - data: Data rows (primitives only - no functions or class instances)\n * - optional presentation props: rowIdKey, sort/defaultSort, locale, etc.\n *\n * Non-serializable props like `onSortChange`, `className`, and sibling action surfaces\n * must be provided separately in your React component.\n *\n * @example\n * ```ts\n * const result = SerializableDataTableSchema.safeParse(llmResponse)\n * if (result.success) {\n * // result.data contains validated id, columns, and data\n * }\n * ```\n */\nexport const SerializableDataTableSchema = z.object({\n id: ToolUIIdSchema,\n role: ToolUIRoleSchema.optional(),\n receipt: ToolUIReceiptSchema.optional(),\n columns: z.array(serializableColumnSchema),\n data: z.array(serializableDataSchema),\n rowIdKey: z.string().optional(),\n defaultSort: z\n .object({\n by: z.string().optional(),\n direction: z.enum([\"asc\", \"desc\"]).optional(),\n })\n .optional(),\n sort: z\n .object({\n by: z.string().optional(),\n direction: z.enum([\"asc\", \"desc\"]).optional(),\n })\n .optional(),\n emptyMessage: z.string().optional(),\n maxHeight: z.string().optional(),\n locale: z.string().optional(),\n});\n\nconst SerializableDataTableSchemaContract = defineToolUiContract(\n \"DataTable\",\n SerializableDataTableSchema,\n);\n\n/**\n * Type representing the serializable parts of a DataTable payload.\n *\n * This type includes only JSON-serializable data that can come from LLM tool calls:\n * - Column definitions (format configs, alignment, labels, etc.)\n * - Row data (primitives: strings, numbers, booleans, null, string arrays)\n *\n * Excluded from this type:\n * - Event handlers (`onSortChange`)\n * - React-specific props (`className`)\n *\n * @example\n * ```ts\n * const payload: SerializableDataTable = {\n * id: \"data-table-expenses\",\n * columns: [\n * { key: \"name\", label: \"Name\" },\n * { key: \"price\", label: \"Price\", format: { kind: \"currency\", currency: \"USD\" } }\n * ],\n * data: [\n * { name: \"Widget\", price: 29.99 }\n * ]\n * }\n * ```\n */\nexport type SerializableDataTable = z.infer;\n\n/**\n * Validates and parses a DataTable payload from unknown data (e.g., LLM tool call result).\n *\n * This function:\n * 1. Validates the input against the `SerializableDataTableSchema`\n * 2. Throws a descriptive error if validation fails\n * 3. Returns typed serializable props ready to pass to the `` component\n *\n * The returned props are **serializable only** - you must provide client-side props\n * separately (onSortChange, className).\n *\n * @param input - Unknown data to validate (typically from an LLM tool call)\n * @returns Validated and typed DataTable serializable props (id, columns, data)\n * @throws Error with validation details if input is invalid\n *\n * @example\n * ```tsx\n * function MyToolUI({ result }: { result: unknown }) {\n * const serializableProps = parseSerializableDataTable(result)\n *\n * return (\n * \n * )\n * }\n * ```\n */\nexport function parseSerializableDataTable(\n input: unknown,\n): Pick<\n DataTableProps,\n | \"id\"\n | \"role\"\n | \"receipt\"\n | \"columns\"\n | \"data\"\n | \"rowIdKey\"\n | \"defaultSort\"\n | \"sort\"\n | \"emptyMessage\"\n | \"maxHeight\"\n | \"locale\"\n> {\n const {\n id,\n role,\n receipt,\n columns,\n data,\n rowIdKey,\n defaultSort,\n sort,\n emptyMessage,\n maxHeight,\n locale,\n } = SerializableDataTableSchemaContract.parse(input);\n return {\n id,\n role,\n receipt,\n columns: columns as unknown as Column[],\n data: data as RowData[],\n rowIdKey: rowIdKey as keyof RowData | undefined,\n defaultSort: defaultSort\n ? {\n by: defaultSort.by as keyof RowData | undefined,\n direction: defaultSort.direction,\n }\n : undefined,\n sort: sort\n ? {\n by: sort.by as keyof RowData | undefined,\n direction: sort.direction,\n }\n : undefined,\n emptyMessage,\n maxHeight,\n locale,\n };\n}\n\nexport function safeParseSerializableDataTable(\n input: unknown,\n): Pick<\n DataTableProps,\n | \"id\"\n | \"role\"\n | \"receipt\"\n | \"columns\"\n | \"data\"\n | \"rowIdKey\"\n | \"defaultSort\"\n | \"sort\"\n | \"emptyMessage\"\n | \"maxHeight\"\n | \"locale\"\n> | null {\n const res = SerializableDataTableSchemaContract.safeParse(input);\n if (!res) return null;\n const {\n id,\n role,\n receipt,\n columns,\n data,\n rowIdKey,\n defaultSort,\n sort,\n emptyMessage,\n maxHeight,\n locale,\n } = res;\n return {\n id,\n role,\n receipt,\n columns: columns as unknown as Column[],\n data: data as RowData[],\n rowIdKey: rowIdKey as keyof RowData | undefined,\n defaultSort: defaultSort\n ? {\n by: defaultSort.by as keyof RowData | undefined,\n direction: defaultSort.direction,\n }\n : undefined,\n sort: sort\n ? {\n by: sort.by as keyof RowData | undefined,\n direction: sort.direction,\n }\n : undefined,\n emptyMessage,\n maxHeight,\n locale,\n };\n}\n" }, { "path": "apps/www/components/tool-ui/data-table/types.ts", "content": "import type { ToolUIId, ToolUIReceipt, ToolUIRole } from \"../shared/schema\";\nimport type { FormatConfig } from \"./formatters\";\n\n/**\n * JSON primitive type that can be serialized.\n */\ntype JsonPrimitive = string | number | boolean | null;\n\n/**\n * Valid row value types for serializable DataTable data.\n *\n * Supports:\n * - Primitives: string, number, boolean, null\n * - Arrays of primitives: string[], number[], boolean[], or mixed primitive arrays\n *\n * For complex data (objects with href/label, etc.), use column format configs\n * instead of putting objects in row data.\n *\n * @example\n * ```ts\n * // 👍 Good: Use primitives and primitive arrays\n * const row = {\n * name: \"Widget\",\n * price: 29.99,\n * tags: [\"electronics\", \"featured\"],\n * metrics: [1.2, 3.4, 5.6]\n * }\n *\n * // 🚫 Bad: Don't put objects in row data\n * const row = {\n * link: { href: \"/path\", label: \"Click\" } // Use format: { kind: 'link' } instead\n * }\n * ```\n */\nexport type RowPrimitive = JsonPrimitive | JsonPrimitive[];\nexport type DataTableRowData = Record;\nexport type RowData = Record;\nexport type ColumnKey = Extract;\n\nexport type FormatFor = V extends number\n ? Extract\n : V extends boolean\n ? Extract\n : V extends (string | number | boolean | null)[]\n ? Extract\n : V extends string\n ? Extract<\n FormatConfig,\n { kind: \"text\" | \"link\" | \"date\" | \"badge\" | \"status\" }\n >\n : Extract;\n\n/**\n * Column definition for DataTable\n *\n * @remarks\n * **Important:** Columns are sortable by default (opt-out pattern).\n * Set `sortable: false` explicitly to disable sorting for specific columns.\n */\nexport interface Column<\n T extends object = DataTableRowData,\n K extends ColumnKey = ColumnKey,\n> {\n /** Unique identifier that maps to a key in the row data */\n key: K;\n /** Display text for the column header */\n label: string;\n /** Abbreviated label for narrow viewports */\n abbr?: string;\n /** Whether column is sortable. Default: true (opt-out pattern) */\n sortable?: boolean;\n /** Text alignment for column cells */\n align?: \"left\" | \"right\" | \"center\";\n /** Optional fixed width (CSS value) */\n width?: string;\n /** Enable text truncation with ellipsis */\n truncate?: boolean;\n /** Mobile display priority (primary = always visible, secondary = expandable, tertiary = hidden) */\n priority?: \"primary\" | \"secondary\" | \"tertiary\";\n /** Completely hide column on mobile viewports */\n hideOnMobile?: boolean;\n /** Formatting configuration for cell values */\n format?: FormatFor;\n}\n\n/**\n * Serializable props that can come from LLM tool calls or be JSON-serialized.\n *\n * These props contain only primitive values, arrays, and plain objects -\n * no functions, class instances, or other non-serializable values.\n *\n * @example\n * ```tsx\n * const serializableProps: DataTableSerializableProps = {\n * columns: [...],\n * data: [...],\n * rowIdKey: \"id\",\n * defaultSort: { by: \"price\", direction: \"desc\" }\n * }\n * ```\n */\nexport interface DataTableSerializableProps {\n /**\n * Unique identifier for this tool UI instance in the conversation.\n *\n * Used for:\n * - Assistant referencing (\"the table above\")\n * - Receipt generation (linking actions to their source)\n * - Narration context\n *\n * Should be stable across re-renders, meaningful, and unique within the conversation.\n *\n * @example \"data-table-expenses-q3\", \"search-results-repos\"\n */\n id: ToolUIId;\n /** Optional surface role metadata (serializable) */\n role?: ToolUIRole;\n /** Optional receipt metadata for consequential outcomes (serializable) */\n receipt?: ToolUIReceipt;\n /** Column definitions */\n columns: Column[];\n /** Row data (primitives only - no functions or class instances) */\n data: T[];\n /**\n * Key in row data to use as unique identifier for React keys\n *\n * **Strongly recommended:** Always provide this for dynamic data to prevent\n * reconciliation issues (focus traps, animation glitches, incorrect state preservation)\n * when data reorders. Falls back to array index if omitted (only acceptable for static mock data).\n *\n * @example rowIdKey=\"id\" or rowIdKey=\"uuid\"\n */\n rowIdKey?: ColumnKey;\n /**\n * Uncontrolled initial sort state (table manages its own sort state internally)\n *\n * **Sorting cycle:** Clicking column headers cycles through tri-state:\n * 1. none (unsorted) → 2. asc → 3. desc → 4. none (back to unsorted)\n *\n * @example\n * ```tsx\n * // Start with descending price sort\n * \n * ```\n */\n defaultSort?: { by?: ColumnKey; direction?: \"asc\" | \"desc\" };\n /**\n * Controlled sort state (use with onSortChange from client props)\n *\n * When provided, you must also provide `onSortChange` to handle sort updates.\n * The table will cycle through: none → asc → desc → none.\n *\n * @example\n * ```tsx\n * const [sort, setSort] = useState({ by: \"price\", direction: \"desc\" })\n * \n * ```\n */\n sort?: { by?: ColumnKey; direction?: \"asc\" | \"desc\" };\n /** Empty state message */\n emptyMessage?: string;\n /** Max table height with vertical scroll (CSS value) */\n maxHeight?: string;\n /**\n * BCP47 locale for formatting and sorting (e.g., 'en-US', 'de-DE', 'ja-JP')\n *\n * Defaults to 'en-US' to ensure consistent server/client rendering.\n * Pass explicit locale for internationalization.\n *\n * @example\n * ```tsx\n * // German formatting\n * // Japanese formatting\n * // Uses 'en-US' default\n * ```\n */\n locale?: string;\n}\n\n/**\n * Client-side React-only props that cannot be serialized.\n *\n * These props contain functions, component state, or other React-specific values\n * that must be provided by your React code (not from LLM tool calls).\n *\n * @example\n * ```tsx\n * const clientProps: DataTableClientProps = {\n * className: \"my-table\",\n * onSortChange: (next) => setSort(next),\n * // Compose local/decision actions externally via LocalActions/DecisionActions\n * }\n * ```\n */\nexport interface DataTableClientProps {\n /** Additional CSS classes */\n className?: string;\n /**\n * Sort change handler for controlled mode (required if sort is provided)\n *\n * **Tri-state cycle behavior:**\n * - Click unsorted column: `{ by: \"column\", direction: \"asc\" }`\n * - Click asc column: `{ by: \"column\", direction: \"desc\" }`\n * - Click desc column: `{ by: \"column\", direction: undefined }` (returns to unsorted)\n * - Click different column: `{ by: \"newColumn\", direction: \"asc\" }`\n *\n * @example\n * ```tsx\n * const [sort, setSort] = useState<{ by?: string; direction?: \"asc\" | \"desc\" }>({})\n *\n * {\n * console.log(\"Sort changed:\", next)\n * setSort(next)\n * }}\n * />\n * ```\n */\n onSortChange?: (next: {\n by?: ColumnKey;\n direction?: \"asc\" | \"desc\";\n }) => void;\n}\n\n/**\n * Complete props for the DataTable component.\n *\n * Combines serializable props (can come from LLM tool calls) with client-side\n * React-only props. This separation makes the boundary explicit and prevents\n * accidental serialization of non-serializable values.\n *\n * @see {@link DataTableSerializableProps} for props that can be JSON-serialized\n * @see {@link DataTableClientProps} for React-only props\n * @see {@link parseSerializableDataTable} for parsing LLM tool call results\n *\n * @example\n * ```tsx\n * // From LLM tool call\n * const serializableProps = parseSerializableDataTable(llmResult)\n *\n * // Combine with React-specific props\n * \n * ```\n */\nexport interface DataTableProps\n extends DataTableSerializableProps, DataTableClientProps {}\n\nexport interface DataTableContextValue {\n columns: Column[];\n data: T[];\n rowIdKey?: ColumnKey;\n sortBy?: ColumnKey;\n sortDirection?: \"asc\" | \"desc\";\n toggleSort?: (key: ColumnKey) => void;\n id?: string;\n locale?: string;\n}\n" }, { "path": "apps/www/components/tool-ui/data-table/utilities.ts", "content": "/**\n * Sort an array of objects by a key\n */\nexport function sortData>(\n data: T[],\n key: K,\n direction: \"asc\" | \"desc\",\n locale?: string,\n): T[] {\n const get = (obj: T, k: K): unknown => (obj as Record)[k];\n const collator = new Intl.Collator(locale, {\n numeric: true,\n sensitivity: \"base\",\n });\n return [...data].sort((a, b) => {\n const aVal = get(a, key);\n const bVal = get(b, key);\n\n // Handle nulls\n if (aVal == null && bVal == null) return 0;\n if (aVal == null) return 1;\n if (bVal == null) return -1;\n\n // Type-specific comparison\n // Numbers\n if (typeof aVal === \"number\" && typeof bVal === \"number\") {\n return direction === \"asc\" ? aVal - bVal : bVal - aVal;\n }\n // Dates (Date instances)\n if (aVal instanceof Date && bVal instanceof Date) {\n const diff = aVal.getTime() - bVal.getTime();\n return direction === \"asc\" ? diff : -diff;\n }\n // Booleans: false < true\n if (typeof aVal === \"boolean\" && typeof bVal === \"boolean\") {\n const diff = aVal === bVal ? 0 : aVal ? 1 : -1;\n return direction === \"asc\" ? diff : -diff;\n }\n // Arrays: compare length\n if (Array.isArray(aVal) && Array.isArray(bVal)) {\n const diff = aVal.length - bVal.length;\n return direction === \"asc\" ? diff : -diff;\n }\n // Strings that look like numbers -> numeric compare\n if (typeof aVal === \"string\" && typeof bVal === \"string\") {\n const numA = parseNumericLike(aVal);\n const numB = parseNumericLike(bVal);\n if (numA != null && numB != null) {\n const diff = numA - numB;\n return direction === \"asc\" ? diff : -diff;\n }\n // ISO-like date strings\n if (/^\\d{4}-\\d{2}-\\d{2}/.test(aVal) && /^\\d{4}-\\d{2}-\\d{2}/.test(bVal)) {\n const da = new Date(aVal).getTime();\n const db = new Date(bVal).getTime();\n const diff = da - db;\n return direction === \"asc\" ? diff : -diff;\n }\n }\n\n // Fallback: locale-aware string compare with numeric collation\n const aStr = String(aVal);\n const bStr = String(bVal);\n const comparison = collator.compare(aStr, bStr);\n return direction === \"asc\" ? comparison : -comparison;\n });\n}\n\n/**\n * Return a human-friendly identifier for a row using common keys\n *\n * Accepts any JSON-serializable primitive or array of primitives.\n * Arrays are converted to comma-separated strings.\n */\nexport function getRowIdentifier(\n row: Record<\n string,\n string | number | boolean | null | (string | number | boolean | null)[]\n >,\n identifierKey?: string,\n): string {\n const candidate =\n (identifierKey ? row[identifierKey] : undefined) ??\n (row as Record).name ??\n (row as Record).title ??\n (row as Record).id;\n\n if (candidate == null) {\n return \"\";\n }\n\n // Handle arrays by joining them\n if (Array.isArray(candidate)) {\n return candidate.map((v) => (v === null ? \"null\" : String(v))).join(\", \");\n }\n\n return String(candidate).trim();\n}\n\nfunction stableStringify(value: unknown): string {\n if (value == null) return \"null\";\n if (typeof value === \"string\") return JSON.stringify(value);\n if (\n typeof value === \"number\" ||\n typeof value === \"boolean\" ||\n typeof value === \"bigint\"\n ) {\n return String(value);\n }\n if (Array.isArray(value)) {\n return `[${value.map((item) => stableStringify(item)).join(\",\")}]`;\n }\n if (typeof value === \"object\") {\n const entries = Object.entries(value as Record).sort(\n ([a], [b]) => a.localeCompare(b),\n );\n return `{${entries\n .map(([key, item]) => `${JSON.stringify(key)}:${stableStringify(item)}`)\n .join(\",\")}}`;\n }\n return JSON.stringify(String(value));\n}\n\nfunction hashString(value: string): string {\n let hash = 5381;\n for (let i = 0; i < value.length; i++) {\n hash = (hash * 33) ^ value.charCodeAt(i);\n }\n return (hash >>> 0).toString(36);\n}\n\n/**\n * Create deterministic, reorder-stable React keys for DataTable rows.\n *\n * - Uses `identifierKey` or common identifier fields as the primary base.\n * - Falls back to stable content fingerprints when no identifier exists.\n * - Disambiguates duplicates without relying on array index.\n */\nexport function createDataTableRowKeys(\n rows: Array>,\n identifierKey?: string,\n): string[] {\n const canonicalRows = rows.map((row) => stableStringify(row));\n\n const baseKeys = rows.map((row, index) => {\n const identifier = getRowIdentifier(\n row as Record<\n string,\n string | number | boolean | null | (string | number | boolean | null)[]\n >,\n identifierKey,\n );\n\n if (identifier) {\n return `id:${identifier}`;\n }\n\n return `row:${hashString(canonicalRows[index])}`;\n });\n\n const baseCounts = new Map();\n baseKeys.forEach((key) => {\n baseCounts.set(key, (baseCounts.get(key) ?? 0) + 1);\n });\n\n const usedKeys = new Map();\n\n return rows.map((row, index) => {\n const baseKey = baseKeys[index];\n if ((baseCounts.get(baseKey) ?? 0) === 1) {\n return baseKey;\n }\n\n const rowFingerprint = hashString(canonicalRows[index]);\n let disambiguatedKey = `${baseKey}::${rowFingerprint}`;\n\n const seenCount = usedKeys.get(disambiguatedKey) ?? 0;\n usedKeys.set(disambiguatedKey, seenCount + 1);\n if (seenCount > 0) {\n disambiguatedKey = `${disambiguatedKey}::d${seenCount + 1}`;\n }\n\n return disambiguatedKey;\n });\n}\n\nfunction sanitizeDomIdToken(value: string): string {\n return encodeURIComponent(value).replace(/%/g, \"_\");\n}\n\nexport function getDataTableMobileDescriptionId(surfaceId: string): string {\n return `${sanitizeDomIdToken(surfaceId)}-mobile-table-description`;\n}\n\n/**\n * Parse a string that represents a numeric value, handling various formats:\n * - Currency symbols: $, €, £, ¥, etc.\n * - Percent symbols: %\n * - Accounting negatives: (1234) → -1234\n * - Thousands/decimal separators: 1,234.56 or 1.234,56\n * - Compact notation: 2.8T (trillion), 1.5M (million), 500K (thousand)\n * - Byte suffixes: 768B (bytes), 1.5KB, 2GB, 1TB\n *\n * Note: Single \"B\" is disambiguated - integers < 1024 are bytes, otherwise billions.\n *\n * @param input - String to parse\n * @returns Parsed number or null if unparseable\n *\n * @example\n * parseNumericLike(\"$1,234.56\") // 1234.56\n * parseNumericLike(\"2.8T\") // 2800000000000\n * parseNumericLike(\"768B\") // 768\n * parseNumericLike(\"50%\") // 50\n * parseNumericLike(\"(1234)\") // -1234\n */\nexport function parseNumericLike(input: string): number | null {\n // Normalize whitespace (spaces, NBSPs, thin spaces)\n let s = input.replace(/[\\u00A0\\u202F\\s]/g, \"\").trim();\n if (!s) return null;\n\n // Accounting negatives: (1234) -> -1234\n s = s.replace(/^\\((.*)\\)$/g, \"-$1\");\n\n // Strip common currency and percent symbols\n s = s.replace(/[%$€£¥₩₹₽₺₪₫฿₦₴₡₲₵₸]/g, \"\");\n\n function hasGroupedThousands(value: string, sep: \",\" | \".\"): boolean {\n const unsigned = value.replace(/^[+-]/, \"\");\n const parts = unsigned.split(sep);\n if (parts.length < 2) return false;\n if (parts.some((part) => part.length === 0)) return false;\n if (!/^\\d{1,3}$/.test(parts[0])) return false;\n if (parts[0] === \"0\") return false;\n return parts.slice(1).every((part) => /^\\d{3}$/.test(part));\n }\n\n const lastComma = s.lastIndexOf(\",\");\n const lastDot = s.lastIndexOf(\".\");\n if (lastComma !== -1 && lastDot !== -1) {\n // Decide decimal by whichever occurs last\n const decimalSep = lastComma > lastDot ? \",\" : \".\";\n const thousandSep = decimalSep === \",\" ? \".\" : \",\";\n s = s.split(thousandSep).join(\"\");\n s = s.replace(decimalSep, \".\");\n } else if (lastComma !== -1) {\n // Only comma present\n if (hasGroupedThousands(s, \",\")) {\n s = s.replace(/,/g, \"\");\n } else {\n const frac = s.length - lastComma - 1;\n if (frac >= 1 && frac <= 3) s = s.replace(/,/g, \".\");\n else s = s.replace(/,/g, \"\");\n }\n } else if (lastDot !== -1) {\n // Only dot present; normalize grouped thousands separators.\n if (hasGroupedThousands(s, \".\")) {\n s = s.replace(/\\./g, \"\");\n } else if ((s.match(/\\./g) || []).length > 1) {\n s = s.replace(/\\./g, \"\");\n }\n }\n\n // Handle compact notation (K, M, B, T, P, G) and byte suffixes (KB, MB, GB, TB, PB)\n const compactMatch = s.match(/^([+-]?\\d+\\.?\\d*|\\d*\\.\\d+)([KMBTPG]B?|B)$/i);\n if (compactMatch) {\n const baseNum = Number(compactMatch[1]);\n if (Number.isNaN(baseNum)) return null;\n\n const suffix = compactMatch[2].toUpperCase();\n\n // Disambiguate single \"B\" (bytes vs billions)\n // If whole number < 1024, treat as bytes. Otherwise, billions.\n if (suffix === \"B\") {\n const isLikelyBytes = Number.isInteger(baseNum) && baseNum < 1024;\n return isLikelyBytes ? baseNum : baseNum * 1e9;\n }\n\n const multipliers: Record = {\n K: 1e3,\n KB: 1024, // Kilo: metric vs binary\n M: 1e6,\n MB: 1024 ** 2, // Mega\n G: 1e9,\n GB: 1024 ** 3, // Giga\n T: 1e12,\n TB: 1024 ** 4, // Tera\n P: 1e15,\n PB: 1024 ** 5, // Peta\n };\n\n return baseNum * (multipliers[suffix] ?? 1);\n }\n\n if (/^[+-]?(?:\\d+\\.?\\d*|\\d*\\.\\d+)$/.test(s)) {\n const n = Number(s);\n return Number.isNaN(n) ? null : n;\n }\n return null;\n}\n" }, { "path": "apps/www/components/tool-ui/geo-map/README.md", "content": "# Geo Map\n\nImplementation for the \"geo-map\" Tool UI surface.\n\n## Files\n\n- public exports: components/tool-ui/geo-map/index.tsx\n- serializable schema + parse helpers: components/tool-ui/geo-map/schema.ts\n- public facade component: components/tool-ui/geo-map/geo-map.tsx\n- internal Leaflet engine: components/tool-ui/geo-map/geo-map-engine.tsx\n- colocated Leaflet shell theme styles: components/tool-ui/geo-map/geo-map-theme.module.css\n- icon construction helpers: components/tool-ui/geo-map/geo-map-icons.ts\n- popup/tooltip overlay renderer: components/tool-ui/geo-map/geo-map-overlays.tsx\n\n## Companion assets\n\n- Docs page: app/docs/geo-map/content.mdx\n- Preset payload: lib/presets/geo-map.ts\n\n## Quick check\n\nRun this after edits:\n\npnpm test\n" }, { "path": "apps/www/components/tool-ui/geo-map/_adapter.tsx", "content": "/**\n * Adapter: UI and utility re-exports for copy-standalone portability.\n *\n * When copying this component to another project, update these imports\n * to match your project's paths:\n *\n * cn → Your Tailwind merge utility (e.g., \"@/lib/utils\", \"~/lib/cn\")\n * Leaflet → map primitives from react-leaflet\n */\n\nexport { cn } from \"@/lib/utils\";\nexport {\n CircleMarker,\n MapContainer,\n Marker,\n Polyline,\n Popup,\n TileLayer,\n Tooltip,\n ZoomControl,\n useMap,\n useMapEvents,\n} from \"react-leaflet\";\n" }, { "path": "apps/www/components/tool-ui/geo-map/geo-map-engine.tsx", "content": "\"use client\";\n\nimport type { Map as LeafletMap } from \"leaflet\";\nimport { memo, useCallback, useEffect, useMemo, useRef, useState } from \"react\";\nimport Supercluster from \"supercluster\";\nimport {\n CircleMarker,\n MapContainer,\n Marker,\n Polyline,\n TileLayer,\n ZoomControl,\n useMap,\n useMapEvents,\n} from \"./_adapter\";\nimport { createClusterIcon, resolveMarkerIcon } from \"./geo-map-icons\";\nimport { GeoMapOverlays } from \"./geo-map-overlays\";\nimport type {\n GeoMapClustering,\n GeoMapFitTarget,\n GeoMapMarker,\n GeoMapRoute,\n GeoMapViewport,\n} from \"./schema\";\n\nconst TILE_ATTRIBUTION =\n '© OpenStreetMap contributors © CARTO';\nconst ROUTE_DEFAULT_COLOR = \"var(--primary)\";\nconst ROUTE_DEFAULT_WEIGHT = 3;\nconst ROUTE_DEFAULT_OPACITY = 0.85;\nconst EMPTY_ROUTES: GeoMapRoute[] = [];\n\nconst CLUSTER_RADIUS_DEFAULT = 60;\nconst CLUSTER_MAX_ZOOM_DEFAULT = 16;\nconst CLUSTER_MIN_POINTS_DEFAULT = 2;\n\nconst DEFAULT_CENTER: [number, number] = [20, 0];\nexport const DEFAULT_VIEW_ZOOM = 2;\nconst SINGLE_LOCATION_ZOOM = 13;\nconst DEFAULT_VIEWPORT_PADDING = 32;\n\ntype LeafletRuntime = Pick<\n typeof import(\"leaflet\"),\n \"divIcon\" | \"latLngBounds\"\n>;\n\nexport type GeoMapBbox = [\n west: number,\n south: number,\n east: number,\n north: number,\n];\nexport type GeoMapLatLng = [lat: number, lng: number];\n\nexport type GeoMapClusterProperties = {\n cluster?: boolean;\n cluster_id?: number;\n point_count?: number;\n markerId?: string;\n};\n\nexport type GeoMapClusterFeature = GeoJSON.Feature<\n GeoJSON.Point,\n GeoMapClusterProperties\n>;\n\ntype MarkerClusterPointProperties = GeoMapClusterProperties & {\n markerId?: string;\n marker?: GeoMapMarker;\n};\n\ntype MapViewportState = {\n bbox: GeoMapBbox;\n zoom: number;\n};\n\nfunction roundCoordinate(value: number): number {\n return Math.round(value * 1_000_000) / 1_000_000;\n}\n\nfunction normalizeViewportState(state: MapViewportState): MapViewportState {\n return {\n bbox: [\n roundCoordinate(state.bbox[0]),\n roundCoordinate(state.bbox[1]),\n roundCoordinate(state.bbox[2]),\n roundCoordinate(state.bbox[3]),\n ],\n zoom: state.zoom,\n };\n}\n\nfunction areViewportStatesEqual(\n a: MapViewportState | null,\n b: MapViewportState,\n): boolean {\n if (!a) {\n return false;\n }\n\n return (\n a.zoom === b.zoom &&\n a.bbox[0] === b.bbox[0] &&\n a.bbox[1] === b.bbox[1] &&\n a.bbox[2] === b.bbox[2] &&\n a.bbox[3] === b.bbox[3]\n );\n}\n\nfunction serializeFitPoints(points: [number, number][]): string {\n return points\n .map(([lat, lng]) => `${roundCoordinate(lat)},${roundCoordinate(lng)}`)\n .join(\"|\");\n}\n\nfunction readViewportState(map: LeafletMap): MapViewportState {\n const bounds = map.getBounds();\n return normalizeViewportState({\n bbox: [\n bounds.getWest(),\n bounds.getSouth(),\n bounds.getEast(),\n bounds.getNorth(),\n ],\n zoom: Math.round(map.getZoom()),\n });\n}\n\nexport function collectFitPoints(\n markers: GeoMapMarker[],\n routes: GeoMapRoute[],\n target: GeoMapFitTarget,\n): GeoMapLatLng[] {\n const markerPoints =\n target === \"markers\" || target === \"all\"\n ? markers.map((marker) => [marker.lat, marker.lng] as GeoMapLatLng)\n : [];\n\n const routePoints =\n target === \"routes\" || target === \"all\"\n ? routes.flatMap((route) =>\n route.points.map((point) => [point.lat, point.lng] as GeoMapLatLng),\n )\n : [];\n\n return [...markerPoints, ...routePoints];\n}\n\nexport function resolveFitPointsWithFallback(\n markers: GeoMapMarker[],\n routes: GeoMapRoute[],\n target: GeoMapFitTarget,\n): GeoMapLatLng[] {\n const selected = collectFitPoints(markers, routes, target);\n if (selected.length > 0) {\n return selected;\n }\n\n if (target !== \"markers\") {\n return collectFitPoints(markers, routes, \"markers\");\n }\n\n return [];\n}\n\nexport function splitDatelineBbox(bbox: GeoMapBbox): GeoMapBbox[] {\n const [west, south, east, north] = bbox;\n\n if (west <= east) {\n return [bbox];\n }\n\n return [\n [west, south, 180, north],\n [-180, south, east, north],\n ];\n}\n\nfunction getClusterFeatureKey(feature: GeoMapClusterFeature): string {\n const properties = feature.properties ?? {};\n\n if (properties.cluster && typeof properties.cluster_id === \"number\") {\n return `cluster:${properties.cluster_id}`;\n }\n\n if (\n typeof properties.markerId === \"string\" &&\n properties.markerId.length > 0\n ) {\n return `marker:${properties.markerId}`;\n }\n\n if (feature.id !== undefined && feature.id !== null) {\n return `id:${String(feature.id)}`;\n }\n\n const [lng, lat] = feature.geometry.coordinates;\n return `point:${lat}:${lng}`;\n}\n\nfunction dedupeClusterFeatures(\n features: GeoMapClusterFeature[],\n): GeoMapClusterFeature[] {\n const seen = new Set();\n const deduped: GeoMapClusterFeature[] = [];\n\n features.forEach((feature) => {\n const key = getClusterFeatureKey(feature);\n if (seen.has(key)) {\n return;\n }\n\n seen.add(key);\n deduped.push(feature);\n });\n\n return deduped;\n}\n\nexport function getClustersForDatelineAwareBbox(\n bbox: GeoMapBbox,\n zoom: number,\n getClustersForBbox: (\n candidateBbox: GeoMapBbox,\n zoom: number,\n ) => GeoMapClusterFeature[],\n): GeoMapClusterFeature[] {\n const queried = splitDatelineBbox(bbox).flatMap((candidateBbox) =>\n getClustersForBbox(candidateBbox, zoom),\n );\n\n return dedupeClusterFeatures(queried);\n}\n\nexport function toSafeExpansionZoom(\n zoom: number,\n options?: { minZoom?: number; maxZoom?: number; fallback?: number },\n): number {\n const minZoom = options?.minZoom ?? 1;\n const maxZoom = options?.maxZoom ?? 22;\n const fallback = options?.fallback ?? 2;\n\n if (!Number.isFinite(zoom)) {\n return fallback;\n }\n\n return Math.min(maxZoom, Math.max(minZoom, Math.round(zoom)));\n}\n\nfunction resolveInitialView(\n markers: GeoMapMarker[],\n routes: GeoMapRoute[],\n viewport: GeoMapViewport | undefined,\n): { center: [number, number]; zoom: number } {\n if (viewport?.mode === \"center\") {\n return {\n center: [viewport.center.lat, viewport.center.lng],\n zoom: viewport.zoom,\n };\n }\n\n const fitTarget = viewport?.target ?? \"all\";\n const fitPoints = resolveFitPointsWithFallback(markers, routes, fitTarget);\n\n if (fitPoints.length === 1) {\n return {\n center: [fitPoints[0][0], fitPoints[0][1]],\n zoom: viewport?.maxZoom\n ? Math.min(SINGLE_LOCATION_ZOOM, viewport.maxZoom)\n : SINGLE_LOCATION_ZOOM,\n };\n }\n\n return { center: DEFAULT_CENTER, zoom: DEFAULT_VIEW_ZOOM };\n}\n\nfunction ViewportController({\n markers,\n routes,\n viewport,\n leafletRuntime,\n}: {\n markers: GeoMapMarker[];\n routes: GeoMapRoute[];\n viewport: GeoMapViewport | undefined;\n leafletRuntime: LeafletRuntime;\n}) {\n const map = useMap();\n const lastAppliedViewportRef = useRef(null);\n\n useEffect(() => {\n lastAppliedViewportRef.current = null;\n }, [map]);\n\n useEffect(() => {\n if (viewport?.mode === \"center\") {\n const viewportKey = `center:${roundCoordinate(viewport.center.lat)}:${roundCoordinate(viewport.center.lng)}:${viewport.zoom}`;\n if (lastAppliedViewportRef.current === viewportKey) {\n return;\n }\n\n lastAppliedViewportRef.current = viewportKey;\n map.setView([viewport.center.lat, viewport.center.lng], viewport.zoom);\n return;\n }\n\n const fitTarget = viewport?.target ?? \"all\";\n const fitPoints = resolveFitPointsWithFallback(markers, routes, fitTarget);\n if (fitPoints.length === 0) {\n return;\n }\n\n const maxZoom = viewport?.maxZoom;\n if (fitPoints.length === 1) {\n const [lat, lng] = fitPoints[0];\n const zoom = maxZoom\n ? Math.min(SINGLE_LOCATION_ZOOM, maxZoom)\n : SINGLE_LOCATION_ZOOM;\n const viewportKey = `fit-single:${roundCoordinate(lat)}:${roundCoordinate(lng)}:${zoom}`;\n if (lastAppliedViewportRef.current === viewportKey) {\n return;\n }\n\n lastAppliedViewportRef.current = viewportKey;\n map.setView([lat, lng], zoom);\n return;\n }\n\n const padding = viewport?.padding ?? DEFAULT_VIEWPORT_PADDING;\n const viewportKey = `fit:${fitTarget}:${padding}:${maxZoom ?? \"none\"}:${serializeFitPoints(fitPoints)}`;\n if (lastAppliedViewportRef.current === viewportKey) {\n return;\n }\n\n lastAppliedViewportRef.current = viewportKey;\n const bounds = leafletRuntime.latLngBounds(fitPoints);\n map.fitBounds(bounds, {\n maxZoom,\n padding: [padding, padding],\n });\n }, [leafletRuntime, map, markers, routes, viewport]);\n\n return null;\n}\n\nfunction MapObserver({\n onViewportChange,\n onMapReady,\n}: {\n onViewportChange: (state: MapViewportState) => void;\n onMapReady: (map: LeafletMap) => void;\n}) {\n const map = useMapEvents({\n moveend: () => {\n onViewportChange(readViewportState(map));\n },\n zoomend: () => {\n onViewportChange(readViewportState(map));\n },\n });\n\n useEffect(() => {\n onMapReady(map);\n onViewportChange(readViewportState(map));\n }, [map, onMapReady, onViewportChange]);\n\n return null;\n}\n\nfunction resolveMarkerAriaLabel(marker: GeoMapMarker): string {\n if (marker.label && marker.description) {\n return `${marker.label}. ${marker.description}`;\n }\n\n return (\n marker.label ??\n marker.description ??\n `Marker at ${marker.lat.toFixed(4)}, ${marker.lng.toFixed(4)}`\n );\n}\n\nexport const GeoMapEngine = memo(function GeoMapEngine({\n id,\n markers,\n routes,\n clustering,\n viewport,\n showZoomControl,\n tileUrl,\n mapAriaLabel,\n tooltipClassName,\n popupClassName,\n onMarkerClick,\n onRouteClick,\n onReadyChange,\n}: {\n id: string;\n markers: GeoMapMarker[];\n routes?: GeoMapRoute[];\n clustering?: GeoMapClustering;\n viewport?: GeoMapViewport;\n showZoomControl: boolean;\n tileUrl: string;\n mapAriaLabel: string;\n tooltipClassName?: string;\n popupClassName?: string;\n onMarkerClick?: (marker: GeoMapMarker) => void;\n onRouteClick?: (route: GeoMapRoute) => void;\n onReadyChange?: (isReady: boolean) => void;\n}) {\n const resolvedRoutes = routes ?? EMPTY_ROUTES;\n const [leafletRuntime, setLeafletRuntime] = useState(\n null,\n );\n const [mapInstance, setMapInstance] = useState(null);\n const [viewportState, setViewportState] = useState(\n null,\n );\n\n const handleViewportChange = useCallback((nextState: MapViewportState) => {\n const normalized = normalizeViewportState(nextState);\n setViewportState((previousState) =>\n areViewportStatesEqual(previousState, normalized)\n ? previousState\n : normalized,\n );\n }, []);\n\n useEffect(() => {\n let isActive = true;\n\n void import(\"leaflet\").then((module) => {\n if (!isActive) {\n return;\n }\n\n setLeafletRuntime({\n divIcon: module.divIcon,\n latLngBounds: module.latLngBounds,\n });\n });\n\n return () => {\n isActive = false;\n };\n }, []);\n\n const isReady = leafletRuntime !== null;\n\n useEffect(() => {\n onReadyChange?.(isReady);\n }, [isReady, onReadyChange]);\n\n useEffect(() => {\n if (!mapInstance) {\n return;\n }\n\n const container = mapInstance.getContainer();\n container.setAttribute(\"role\", \"region\");\n container.setAttribute(\"aria-label\", mapAriaLabel);\n }, [mapAriaLabel, mapInstance]);\n\n useEffect(() => {\n if (!mapInstance) {\n return;\n }\n\n const handleEscape = (event: KeyboardEvent) => {\n if (event.key === \"Escape\") {\n mapInstance.closePopup();\n }\n };\n\n document.addEventListener(\"keydown\", handleEscape);\n return () => {\n document.removeEventListener(\"keydown\", handleEscape);\n };\n }, [mapInstance]);\n\n const initialView = useMemo(\n () => resolveInitialView(markers, resolvedRoutes, viewport),\n [markers, resolvedRoutes, viewport],\n );\n\n const markerById = useMemo(() => {\n const map = new Map();\n markers.forEach((marker, index) => {\n map.set(marker.id ?? `marker-${index}`, marker);\n });\n return map;\n }, [markers]);\n\n const clusterConfig = useMemo(\n () => ({\n enabled: clustering?.enabled === true,\n radius: clustering?.radius ?? CLUSTER_RADIUS_DEFAULT,\n maxZoom: clustering?.maxZoom ?? CLUSTER_MAX_ZOOM_DEFAULT,\n minPoints: clustering?.minPoints ?? CLUSTER_MIN_POINTS_DEFAULT,\n }),\n [clustering],\n );\n\n const clusterIndex = useMemo(() => {\n if (!clusterConfig.enabled) {\n return null;\n }\n\n const index = new Supercluster({\n radius: clusterConfig.radius,\n maxZoom: clusterConfig.maxZoom,\n minPoints: clusterConfig.minPoints,\n });\n\n const points = markers.map((marker, index) => {\n const markerId = marker.id ?? `marker-${index}`;\n return {\n type: \"Feature\" as const,\n id: markerId,\n geometry: {\n type: \"Point\" as const,\n coordinates: [marker.lng, marker.lat] as [number, number],\n },\n properties: {\n markerId,\n marker,\n },\n };\n });\n\n index.load(points);\n return index;\n }, [\n clusterConfig.enabled,\n clusterConfig.maxZoom,\n clusterConfig.minPoints,\n clusterConfig.radius,\n markers,\n ]);\n\n const clusteredFeatures = useMemo(() => {\n if (!clusterConfig.enabled || !clusterIndex || !viewportState) {\n return [] as GeoMapClusterFeature[];\n }\n\n return getClustersForDatelineAwareBbox(\n viewportState.bbox,\n viewportState.zoom,\n (bbox, zoom) =>\n clusterIndex.getClusters(bbox, zoom) as GeoMapClusterFeature[],\n );\n }, [clusterConfig.enabled, clusterIndex, viewportState]);\n\n const renderMarker = useCallback(\n (\n marker: GeoMapMarker,\n markerKey: string,\n markerPositionOverride?: [number, number],\n ) => {\n const markerPosition: [number, number] = markerPositionOverride ?? [\n marker.lat,\n marker.lng,\n ];\n const tooltipMode = marker.tooltip ?? \"hover\";\n const tooltipContent = marker.label ?? marker.description;\n const icon = marker.icon;\n const markerAriaLabel = resolveMarkerAriaLabel(marker);\n\n if (!leafletRuntime) {\n return null;\n }\n\n const leafletIcon = resolveMarkerIcon(icon, leafletRuntime);\n if (leafletIcon) {\n return (\n onMarkerClick?.(marker),\n }}\n >\n \n \n );\n }\n\n const markerStroke =\n icon?.type === \"dot\"\n ? (icon.borderColor ?? \"var(--border)\")\n : \"var(--border)\";\n const markerFill =\n icon?.type === \"dot\"\n ? (icon.color ?? \"var(--primary)\")\n : \"var(--primary)\";\n const markerRadius = icon?.type === \"dot\" ? (icon.radius ?? 7) : 7;\n\n return (\n onMarkerClick?.(marker),\n }}\n >\n \n \n );\n },\n [leafletRuntime, onMarkerClick, popupClassName, tooltipClassName],\n );\n\n if (!leafletRuntime) {\n return null;\n }\n\n return (\n \n \n {showZoomControl && }\n \n \n\n {resolvedRoutes.map((route, routeIndex) => {\n const routeKey = route.id ?? `${id}-route-${routeIndex}`;\n const positions = route.points.map((point) => [\n point.lat,\n point.lng,\n ]) as [number, number][];\n const tooltipMode = route.tooltip ?? \"hover\";\n const tooltipContent = route.label ?? route.description;\n\n return (\n onRouteClick?.(route),\n }}\n >\n \n \n );\n })}\n\n {clusterConfig.enabled && clusterIndex && viewportState\n ? clusteredFeatures.map((feature, index) => {\n const [lng, lat] = feature.geometry.coordinates;\n const properties = (feature.properties ??\n {}) as MarkerClusterPointProperties;\n\n if (\n properties.cluster &&\n typeof properties.cluster_id === \"number\"\n ) {\n const pointCount = properties.point_count ?? 0;\n const clusterId = properties.cluster_id;\n const clusterIcon = createClusterIcon(pointCount, leafletRuntime);\n const clusterAriaLabel = `Cluster containing ${pointCount} locations`;\n\n return (\n {\n if (!mapInstance) {\n return;\n }\n\n const expansionZoom = toSafeExpansionZoom(\n clusterIndex.getClusterExpansionZoom(clusterId),\n {\n maxZoom: 22,\n fallback:\n (viewportState.zoom ?? DEFAULT_VIEW_ZOOM) + 2,\n },\n );\n mapInstance.flyTo([lat, lng], expansionZoom);\n },\n }}\n />\n );\n }\n\n const marker =\n properties.marker ??\n markerById.get(properties.markerId ?? `marker-${index}`);\n if (!marker) {\n return null;\n }\n\n const markerKey =\n marker.id ?? properties.markerId ?? `${id}-cluster-leaf-${index}`;\n return renderMarker(marker, markerKey, [lat, lng]);\n })\n : markers.map((marker, index) =>\n renderMarker(marker, marker.id ?? `${id}-marker-${index}`),\n )}\n \n );\n});\n" }, { "path": "apps/www/components/tool-ui/geo-map/geo-map-icons.ts", "content": "import type { DivIcon } from \"leaflet\";\nimport type { GeoMapMarker } from \"./schema\";\n\ntype LeafletIconRuntime = Pick;\n\nfunction isSafeHttpUrl(value: string | undefined): boolean {\n if (!value) {\n return false;\n }\n\n try {\n const parsed = new URL(value);\n return parsed.protocol === \"http:\" || parsed.protocol === \"https:\";\n } catch {\n return false;\n }\n}\n\nfunction escapeHtml(value: string): string {\n return value\n .replaceAll(\"&\", \"&\")\n .replaceAll(\"<\", \"<\")\n .replaceAll(\">\", \">\")\n .replaceAll('\"', \""\")\n .replaceAll(\"'\", \"'\");\n}\n\nfunction createEmojiIcon(\n icon: Extract, { type: \"emoji\" }>,\n leafletRuntime: LeafletIconRuntime,\n): DivIcon {\n const size = icon.size ?? 24;\n const background = icon.bgColor ?? \"var(--card)\";\n const border = icon.borderColor ?? \"var(--border)\";\n\n return leafletRuntime.divIcon({\n className: \"\",\n html: `${escapeHtml(icon.value)}`,\n iconSize: [size, size],\n iconAnchor: [size / 2, size / 2],\n popupAnchor: [0, -Math.round(size / 2)],\n tooltipAnchor: [0, -Math.round(size / 2)],\n });\n}\n\nfunction createImageIcon(\n icon: Extract, { type: \"image\" }>,\n leafletRuntime: LeafletIconRuntime,\n): DivIcon {\n const width = icon.width ?? 28;\n const height = icon.height ?? 28;\n const borderRadius = icon.borderRadius ?? Math.min(width, height) / 2;\n const border = icon.borderColor ?? \"var(--border)\";\n\n return leafletRuntime.divIcon({\n className: \"\",\n html: `\"\"`,\n iconSize: [width, height],\n iconAnchor: [width / 2, height / 2],\n popupAnchor: [0, -Math.round(height / 2)],\n tooltipAnchor: [0, -Math.round(height / 2)],\n });\n}\n\nexport function createClusterIcon(\n count: number,\n leafletRuntime: LeafletIconRuntime,\n): DivIcon {\n const size = count >= 100 ? 42 : count >= 10 ? 38 : 34;\n const background = \"var(--primary)\";\n const border = \"var(--background)\";\n\n return leafletRuntime.divIcon({\n className: \"\",\n html: `${count}`,\n iconSize: [size, size],\n iconAnchor: [size / 2, size / 2],\n popupAnchor: [0, -Math.round(size / 2)],\n tooltipAnchor: [0, -Math.round(size / 2)],\n });\n}\n\nexport function resolveMarkerIcon(\n icon: GeoMapMarker[\"icon\"] | undefined,\n leafletRuntime: LeafletIconRuntime,\n): DivIcon | null {\n if (icon?.type === \"emoji\") {\n return createEmojiIcon(icon, leafletRuntime);\n }\n\n if (icon?.type === \"image\" && isSafeHttpUrl(icon.url)) {\n return createImageIcon(icon, leafletRuntime);\n }\n\n return null;\n}\n" }, { "path": "apps/www/components/tool-ui/geo-map/geo-map-overlays.tsx", "content": "\"use client\";\n\nimport { useMemo, useState } from \"react\";\n\nimport { Popup, Tooltip, cn } from \"./_adapter\";\n\nfunction GeoMapPopupContent({\n label,\n description,\n}: {\n label?: string;\n description?: string;\n}) {\n return (\n
\n {label && (\n

\n {label}\n

\n )}\n {description && (\n

\n {description}\n

\n )}\n
\n );\n}\n\nfunction GeoMapTooltipContent({ text }: { text: string }) {\n return {text};\n}\n\nexport function GeoMapOverlays({\n tooltipMode,\n tooltipContent,\n label,\n description,\n tooltipClassName,\n popupClassName,\n}: {\n tooltipMode: \"none\" | \"hover\" | \"always\";\n tooltipContent?: string;\n label?: string;\n description?: string;\n tooltipClassName?: string;\n popupClassName?: string;\n}) {\n const hasPopup = Boolean(label || description);\n const [isPopupOpen, setIsPopupOpen] = useState(false);\n const shouldRenderTooltip =\n tooltipMode !== \"none\" && tooltipContent && (!hasPopup || !isPopupOpen);\n const popupEventHandlers = useMemo(\n () => ({\n add: () => setIsPopupOpen(true),\n remove: () => setIsPopupOpen(false),\n }),\n [],\n );\n\n return (\n <>\n {shouldRenderTooltip && (\n \n \n \n )}\n {hasPopup && (\n \n \n \n )}\n \n );\n}\n" }, { "path": "apps/www/components/tool-ui/geo-map/geo-map-theme.module.css", "content": ".root[data-slot=\"geo-map\"] {\n --geo-map-canvas-bg: var(--muted);\n --geo-map-tooltip-bg: var(--foreground);\n --geo-map-tooltip-fg: var(--background);\n --geo-map-tooltip-shadow: 0 8px 20px\n oklch(from var(--foreground) l c h / 0.18);\n --geo-map-tooltip-radius: calc(var(--radius) - 2px);\n --geo-map-tooltip-padding: 0.375rem 0.625rem;\n --geo-map-tooltip-font-size: 0.75rem;\n --geo-map-tooltip-font-weight: 500;\n --geo-map-tooltip-line-height: 1.2;\n --geo-map-popup-margin-bottom: 12px;\n --geo-map-popup-border: var(--border);\n --geo-map-popup-radius: calc(var(--radius) + 2px);\n --geo-map-popup-bg: oklch(from var(--popover) l c h / 0.96);\n --geo-map-popup-fg: var(--popover-foreground);\n --geo-map-popup-shadow: 0 10px 30px oklch(from var(--foreground) l c h / 0.12);\n --geo-map-popup-blur: 8px;\n --geo-map-popup-content-padding: 0.625rem 0.75rem;\n --geo-map-popup-max-width: min(80vw, 18rem);\n --geo-map-popup-font-family: var(\n --font-sans,\n ui-sans-serif,\n system-ui,\n sans-serif\n );\n --geo-map-zoom-bg: oklch(from var(--background) l c h / 0.78);\n --geo-map-zoom-fg: var(--foreground);\n --geo-map-zoom-border: var(--border);\n --geo-map-zoom-hover-bg: oklch(from var(--accent) l c h / 0.82);\n --geo-map-zoom-hover-fg: var(--accent-foreground);\n --geo-map-zoom-disabled-bg: oklch(from var(--muted) l c h / 0.72);\n --geo-map-zoom-disabled-fg: var(--muted-foreground);\n --geo-map-zoom-shadow: 0 1px 2px oklch(from var(--foreground) l c h / 0.08);\n --geo-map-zoom-focus-ring: var(--ring);\n --geo-map-zoom-radius: 0.5rem;\n --geo-map-zoom-size: 2.25rem;\n --geo-map-zoom-font-size: 1.125rem;\n}\n\n.root[data-slot=\"geo-map\"] :global(.leaflet-container) {\n background: var(--geo-map-canvas-bg);\n}\n\n.root[data-slot=\"geo-map\"] :global(.leaflet-control-zoom) {\n border: 1px solid var(--geo-map-zoom-border);\n box-shadow: var(--geo-map-zoom-shadow);\n background: var(--geo-map-zoom-bg);\n backdrop-filter: blur(var(--geo-map-popup-blur));\n -webkit-backdrop-filter: blur(var(--geo-map-popup-blur));\n}\n\n.root[data-slot=\"geo-map\"] :global(.leaflet-control-zoom.leaflet-bar) {\n border-radius: var(--geo-map-zoom-radius) !important;\n}\n\n.root[data-slot=\"geo-map\"] :global(.leaflet-control-zoom a) {\n display: flex;\n align-items: center;\n justify-content: center;\n width: var(--geo-map-zoom-size);\n height: var(--geo-map-zoom-size);\n line-height: 1;\n text-indent: 0;\n border: 0;\n background: transparent;\n color: var(--geo-map-zoom-fg);\n font-size: var(--geo-map-zoom-font-size);\n font-weight: 500;\n box-shadow: none;\n cursor: default;\n transition:\n background-color 150ms ease,\n color 150ms ease,\n border-color 150ms ease,\n box-shadow 150ms ease,\n opacity 150ms ease;\n border-radius: 0 !important;\n}\n\n.root[data-slot=\"geo-map\"] :global(.leaflet-control-zoom a + a) {\n border-top: 1px solid var(--geo-map-zoom-border);\n}\n\n.root[data-slot=\"geo-map\"] :global(.leaflet-control-zoom a:first-child),\n.root[data-slot=\"geo-map\"]\n :global(.leaflet-touch .leaflet-control-zoom a:first-child),\n.root[data-slot=\"geo-map\"]\n :global(.leaflet-control-zoom .leaflet-control-zoom-in) {\n border-radius: var(--geo-map-zoom-radius) var(--geo-map-zoom-radius) 0 0 !important;\n}\n\n.root[data-slot=\"geo-map\"] :global(.leaflet-control-zoom a:last-child),\n.root[data-slot=\"geo-map\"]\n :global(.leaflet-touch .leaflet-control-zoom a:last-child),\n.root[data-slot=\"geo-map\"]\n :global(.leaflet-control-zoom .leaflet-control-zoom-out) {\n border-top: 0;\n border-radius: 0 0 var(--geo-map-zoom-radius) var(--geo-map-zoom-radius) !important;\n}\n\n.root[data-slot=\"geo-map\"] :global(.leaflet-control-zoom a:hover) {\n background: var(--geo-map-zoom-hover-bg);\n color: var(--geo-map-zoom-hover-fg);\n}\n\n.root[data-slot=\"geo-map\"] :global(.leaflet-control-zoom a:focus),\n.root[data-slot=\"geo-map\"] :global(.leaflet-control-zoom a:focus-visible) {\n position: relative;\n z-index: 1;\n outline: 2px solid var(--geo-map-zoom-focus-ring);\n outline-offset: 1px;\n}\n\n.root[data-slot=\"geo-map\"] :global(.leaflet-control-zoom a.leaflet-disabled),\n.root[data-slot=\"geo-map\"]\n :global(.leaflet-control-zoom a.leaflet-disabled:hover) {\n background: var(--geo-map-zoom-disabled-bg);\n color: var(--geo-map-zoom-disabled-fg);\n opacity: 0.55;\n}\n\n.root[data-slot=\"geo-map\"] :global(.leaflet-tooltip.geo-map-tooltip) {\n border: 0;\n border-radius: var(--geo-map-tooltip-radius);\n background: var(--geo-map-tooltip-bg);\n color: var(--geo-map-tooltip-fg);\n box-shadow: var(--geo-map-tooltip-shadow);\n font-size: var(--geo-map-tooltip-font-size);\n font-weight: var(--geo-map-tooltip-font-weight);\n line-height: var(--geo-map-tooltip-line-height);\n padding: var(--geo-map-tooltip-padding);\n}\n\n.root[data-slot=\"geo-map\"]\n :global(.leaflet-tooltip-top.geo-map-tooltip::before) {\n border-top-color: var(--geo-map-tooltip-bg);\n}\n\n.root[data-slot=\"geo-map\"]\n :global(.leaflet-tooltip-bottom.geo-map-tooltip::before) {\n border-bottom-color: var(--geo-map-tooltip-bg);\n}\n\n.root[data-slot=\"geo-map\"]\n :global(.leaflet-tooltip-left.geo-map-tooltip::before) {\n border-left-color: var(--geo-map-tooltip-bg);\n}\n\n.root[data-slot=\"geo-map\"]\n :global(.leaflet-tooltip-right.geo-map-tooltip::before) {\n border-right-color: var(--geo-map-tooltip-bg);\n}\n\n.root[data-slot=\"geo-map\"] :global(.leaflet-popup.geo-map-popup) {\n margin-bottom: var(--geo-map-popup-margin-bottom);\n}\n\n.root[data-slot=\"geo-map\"]\n :global(.leaflet-popup.geo-map-popup .leaflet-popup-content-wrapper) {\n border: 1px solid var(--geo-map-popup-border);\n border-radius: var(--geo-map-popup-radius);\n background: var(--geo-map-popup-bg);\n color: var(--geo-map-popup-fg);\n box-shadow: var(--geo-map-popup-shadow);\n backdrop-filter: blur(var(--geo-map-popup-blur));\n -webkit-backdrop-filter: blur(var(--geo-map-popup-blur));\n padding: 0;\n}\n\n.root[data-slot=\"geo-map\"]\n :global(.leaflet-popup.geo-map-popup .leaflet-popup-content) {\n margin: 0;\n min-width: 0;\n width: max-content;\n max-width: var(--geo-map-popup-max-width);\n padding: var(--geo-map-popup-content-padding);\n font-family: var(--geo-map-popup-font-family);\n}\n\n.root[data-slot=\"geo-map\"]\n :global(.leaflet-popup.geo-map-popup .leaflet-popup-content p) {\n margin: 0;\n}\n\n.root[data-slot=\"geo-map\"]\n :global(.leaflet-popup.geo-map-popup .leaflet-popup-tip-container) {\n display: none;\n}\n\n.root[data-slot=\"geo-map\"]\n :global(.leaflet-popup.geo-map-popup .leaflet-popup-close-button) {\n color: var(--geo-map-popup-fg);\n opacity: 0.75;\n top: 0.25rem;\n right: 0.25rem;\n width: 1.5rem;\n height: 1.5rem;\n font-size: 1rem;\n line-height: 1.5rem;\n border-radius: calc(var(--radius) - 2px);\n}\n\n.root[data-slot=\"geo-map\"]\n :global(.leaflet-popup.geo-map-popup .leaflet-popup-close-button:hover) {\n opacity: 1;\n background: oklch(from var(--muted) l c h / 0.65);\n}\n\n.root[data-slot=\"geo-map\"]\n :global(\n .leaflet-popup.geo-map-popup .leaflet-popup-close-button:focus-visible\n ) {\n outline: 2px solid var(--ring);\n outline-offset: 1px;\n}\n" }, { "path": "apps/www/components/tool-ui/geo-map/geo-map.tsx", "content": "\"use client\";\n\nimport { memo, useEffect, useState } from \"react\";\nimport { cn } from \"./_adapter\";\nimport { GeoMapEngine } from \"./geo-map-engine\";\nimport styles from \"./geo-map-theme.module.css\";\nimport type { GeoMapProps, GeoMapStyle } from \"./schema\";\n\nconst LIGHT_TILE_URL =\n \"https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}{r}.png\";\nconst DARK_TILE_URL =\n \"https://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}{r}.png\";\n\nfunction getSystemTheme(): \"light\" | \"dark\" {\n if (typeof window === \"undefined\") return \"light\";\n return window.matchMedia?.(\"(prefers-color-scheme: dark)\").matches\n ? \"dark\"\n : \"light\";\n}\n\nfunction getDocumentTheme(): \"light\" | \"dark\" | null {\n if (typeof document === \"undefined\") return null;\n\n const root = document.documentElement;\n const dataTheme = root.getAttribute(\"data-theme\")?.toLowerCase();\n if (dataTheme === \"dark\") return \"dark\";\n if (dataTheme === \"light\") return \"light\";\n if (root.classList.contains(\"dark\")) return \"dark\";\n if (root.classList.contains(\"light\")) return \"light\";\n\n return null;\n}\n\nfunction useInheritedTheme(): \"light\" | \"dark\" {\n const [theme, setTheme] = useState<\"light\" | \"dark\">(() => {\n return getDocumentTheme() ?? getSystemTheme();\n });\n\n useEffect(() => {\n if (typeof window === \"undefined\" || typeof document === \"undefined\") {\n return;\n }\n\n const update = () => setTheme(getDocumentTheme() ?? getSystemTheme());\n\n const mql = window.matchMedia?.(\"(prefers-color-scheme: dark)\");\n mql?.addEventListener(\"change\", update);\n\n const observer = new MutationObserver(update);\n observer.observe(document.documentElement, {\n attributes: true,\n attributeFilter: [\"class\", \"data-theme\"],\n });\n\n return () => {\n mql?.removeEventListener(\"change\", update);\n observer.disconnect();\n };\n }, []);\n\n return theme;\n}\n\nfunction resolveMapAriaLabel(title?: string, description?: string): string {\n if (title && description) {\n return `${title}. ${description}`;\n }\n\n return title ?? description ?? \"Geographic map\";\n}\n\nexport const GeoMap = memo(function GeoMap({\n id,\n role: _role,\n receipt: _receipt,\n title,\n description,\n markers,\n routes,\n clustering,\n viewport,\n showZoomControl = true,\n theme,\n className,\n style,\n tooltipClassName,\n popupClassName,\n onMarkerClick,\n onRouteClick,\n}: GeoMapProps) {\n const inheritedTheme = useInheritedTheme();\n const resolvedTheme = theme ?? inheritedTheme;\n const [isMapReady, setIsMapReady] = useState(false);\n const tileUrl = resolvedTheme === \"dark\" ? DARK_TILE_URL : LIGHT_TILE_URL;\n const mapAriaLabel = resolveMapAriaLabel(title, description);\n const resolvedRootStyle: GeoMapStyle = {\n \"--geo-map-canvas-bg\":\n resolvedTheme === \"dark\" ? \"var(--background)\" : \"var(--muted)\",\n ...style,\n };\n\n return (\n \n \n \n\n {(title || description) && (\n \n {title && (\n

\n {title}\n

\n )}\n {description && (\n

\n {description}\n

\n )}\n \n )}\n\n {!isMapReady && (\n \n Loading map...\n \n )}\n \n \n );\n});\n" }, { "path": "apps/www/components/tool-ui/geo-map/index.tsx", "content": "export { GeoMap } from \"./geo-map\";\nexport {\n type GeoMapClustering,\n type GeoMapFitTarget,\n type GeoMapMarker,\n type GeoMapMarkerIcon,\n type GeoMapStyle,\n type GeoMapRoute,\n type GeoMapViewport,\n type GeoMapProps,\n type GeoMapClientProps,\n type SerializableGeoMap,\n} from \"./schema\";\n" }, { "path": "apps/www/components/tool-ui/geo-map/schema.ts", "content": "import { z } from \"zod\";\nimport type { CSSProperties } from \"react\";\nimport { defineToolUiContract } from \"../shared/contract\";\nimport {\n ToolUIIdSchema,\n ToolUIReceiptSchema,\n ToolUIRoleSchema,\n} from \"../shared/schema\";\n\nconst LatitudeSchema = z.number().finite().min(-90).max(90);\nconst LongitudeSchema = z.number().finite().min(-180).max(180);\nconst HttpUrlSchema = z\n .string()\n .url()\n .refine((value) => /^https?:\\/\\//i.test(value), {\n message: \"Expected an http or https URL.\",\n });\n\nconst GeoMapMarkerIconDotSchema = z.object({\n type: z.literal(\"dot\"),\n color: z.string().optional(),\n borderColor: z.string().optional(),\n radius: z.number().min(3).max(16).optional(),\n});\n\nconst GeoMapMarkerIconEmojiSchema = z.object({\n type: z.literal(\"emoji\"),\n value: z.string().min(1),\n size: z.number().min(16).max(40).optional(),\n bgColor: z.string().optional(),\n borderColor: z.string().optional(),\n});\n\nconst GeoMapMarkerIconImageSchema = z.object({\n type: z.literal(\"image\"),\n url: HttpUrlSchema,\n width: z.number().min(16).max(64).optional(),\n height: z.number().min(16).max(64).optional(),\n borderRadius: z.number().min(0).max(999).optional(),\n borderColor: z.string().optional(),\n});\n\nexport const GeoMapMarkerIconSchema = z.union([\n GeoMapMarkerIconDotSchema,\n GeoMapMarkerIconEmojiSchema,\n GeoMapMarkerIconImageSchema,\n]);\n\nexport type GeoMapMarkerIcon = z.infer;\n\nexport const GeoMapMarkerSchema = z.object({\n id: z.string().min(1).optional(),\n lat: LatitudeSchema,\n lng: LongitudeSchema,\n label: z.string().optional(),\n description: z.string().optional(),\n tooltip: z.enum([\"none\", \"hover\", \"always\"]).optional(),\n icon: GeoMapMarkerIconSchema.optional(),\n});\n\nexport type GeoMapMarker = z.infer;\n\nexport const GeoMapRoutePointSchema = z.object({\n lat: LatitudeSchema,\n lng: LongitudeSchema,\n});\n\nexport const GeoMapRouteSchema = z.object({\n id: z.string().min(1).optional(),\n points: z.array(GeoMapRoutePointSchema).min(2),\n label: z.string().optional(),\n description: z.string().optional(),\n tooltip: z.enum([\"none\", \"hover\", \"always\"]).optional(),\n color: z.string().optional(),\n weight: z.number().min(1).max(12).optional(),\n opacity: z.number().min(0).max(1).optional(),\n dashArray: z.string().optional(),\n});\n\nexport type GeoMapRoute = z.infer;\n\nexport const GeoMapClusteringSchema = z.object({\n enabled: z.boolean().optional(),\n radius: z.number().min(20).max(120).optional(),\n maxZoom: z.number().min(1).max(22).optional(),\n minPoints: z.number().min(2).max(20).optional(),\n});\n\nexport type GeoMapClustering = z.infer;\n\nexport const GeoMapFitTargetSchema = z.enum([\"markers\", \"routes\", \"all\"]);\nexport type GeoMapFitTarget = z.infer;\n\nconst GeoMapFitViewportSchema = z.object({\n mode: z.literal(\"fit\"),\n padding: z.number().nonnegative().optional(),\n maxZoom: z.number().min(1).max(22).optional(),\n target: GeoMapFitTargetSchema.optional(),\n});\n\nconst GeoMapCenterViewportSchema = z.object({\n mode: z.literal(\"center\"),\n center: z.object({\n lat: LatitudeSchema,\n lng: LongitudeSchema,\n }),\n zoom: z.number().min(1).max(22),\n});\n\nexport const GeoMapViewportSchema = z.union([\n GeoMapFitViewportSchema,\n GeoMapCenterViewportSchema,\n]);\n\nexport type GeoMapViewport = z.infer;\n\nexport const GeoMapPropsSchema = z\n .object({\n id: ToolUIIdSchema,\n role: ToolUIRoleSchema.optional(),\n receipt: ToolUIReceiptSchema.optional(),\n title: z.string().optional(),\n description: z.string().optional(),\n markers: z.array(GeoMapMarkerSchema).min(1),\n routes: z.array(GeoMapRouteSchema).optional(),\n clustering: GeoMapClusteringSchema.optional(),\n viewport: GeoMapViewportSchema.optional(),\n showZoomControl: z.boolean().optional(),\n theme: z.enum([\"light\", \"dark\"]).optional(),\n })\n .superRefine((value, ctx) => {\n const seenMarkerIds = new Set();\n\n value.markers.forEach((marker, index) => {\n if (!marker.id) {\n return;\n }\n\n if (seenMarkerIds.has(marker.id)) {\n ctx.addIssue({\n code: \"custom\",\n path: [\"markers\", index, \"id\"],\n message: `Duplicate marker id \"${marker.id}\".`,\n });\n return;\n }\n\n seenMarkerIds.add(marker.id);\n });\n\n const seenRouteIds = new Set();\n value.routes?.forEach((route, index) => {\n if (!route.id) {\n return;\n }\n\n if (seenRouteIds.has(route.id)) {\n ctx.addIssue({\n code: \"custom\",\n path: [\"routes\", index, \"id\"],\n message: `Duplicate route id \"${route.id}\".`,\n });\n return;\n }\n\n seenRouteIds.add(route.id);\n });\n });\n\nexport type GeoMapStyle = CSSProperties &\n Partial>;\n\nexport type GeoMapClientProps = {\n className?: string;\n style?: GeoMapStyle;\n tooltipClassName?: string;\n popupClassName?: string;\n onMarkerClick?: (marker: GeoMapMarker) => void;\n onRouteClick?: (route: GeoMapRoute) => void;\n};\n\nexport type GeoMapProps = z.infer & GeoMapClientProps;\n\nexport const SerializableGeoMapSchema = GeoMapPropsSchema;\n\nexport type SerializableGeoMap = z.infer;\n\nconst SerializableGeoMapSchemaContract = defineToolUiContract(\n \"GeoMap\",\n SerializableGeoMapSchema,\n);\n\nexport const parseSerializableGeoMap: (input: unknown) => SerializableGeoMap =\n SerializableGeoMapSchemaContract.parse;\n\nexport const safeParseSerializableGeoMap: (\n input: unknown,\n) => SerializableGeoMap | null = SerializableGeoMapSchemaContract.safeParse;\n" }, { "path": "apps/www/components/tool-ui/image/README.md", "content": "# Image\n\nImplementation for the \"image\" Tool UI surface.\n\n## Files\n\n- public exports: components/tool-ui/image/index.ts\n- serializable schema + parse helpers: components/tool-ui/image/schema.ts\n\n## Companion assets\n\n- Docs page: app/docs/image/content.mdx\n- Preset payload: lib/presets/image.ts\n\n## Quick check\n\nRun this after edits:\n\npnpm test\n" }, { "path": "apps/www/components/tool-ui/image/_adapter.tsx", "content": "/**\n * Adapter: UI and utility re-exports for copy-standalone portability.\n *\n * When copying this component to another project, update these imports\n * to match your project's paths:\n *\n * cn → Your Tailwind merge utility (e.g., \"@/lib/utils\", \"~/lib/cn\")\n */\n\"use client\";\n\nexport { cn } from \"@/lib/utils\";\n" }, { "path": "apps/www/components/tool-ui/image/image.tsx", "content": "\"use client\";\n\nimport * as React from \"react\";\nimport { cn } from \"./_adapter\";\n\nimport {\n RATIO_CLASS_MAP,\n getFitClass,\n openSafeNavigationHref,\n resolveSafeNavigationHref,\n sanitizeHref,\n} from \"../shared/media\";\nimport type { SerializableImage, Source } from \"./schema\";\n\nconst FALLBACK_LOCALE = \"en-US\";\n\nexport interface ImageProps extends SerializableImage {\n className?: string;\n onNavigate?: (href: string, image: SerializableImage) => void;\n}\n\nexport function Image(props: ImageProps) {\n const { className, onNavigate, ...serializable } = props;\n\n const {\n id,\n src,\n alt,\n title,\n href: rawHref,\n domain,\n ratio = \"auto\",\n fit = \"cover\",\n source,\n locale: providedLocale,\n } = serializable;\n\n const locale = providedLocale ?? FALLBACK_LOCALE;\n const sanitizedHref = sanitizeHref(rawHref);\n const resolvedSourceUrl = sanitizeHref(source?.url);\n\n const imageData: SerializableImage = {\n ...serializable,\n href: sanitizedHref,\n source: source ? { ...source, url: resolvedSourceUrl } : undefined,\n locale,\n };\n\n const sourceLabel = source?.label ?? domain;\n const fallbackInitial = (sourceLabel ?? \"\").trim().charAt(0).toUpperCase();\n const hasSource = Boolean(sourceLabel || source?.iconUrl);\n\n const handleSourceClick = (event: React.MouseEvent) => {\n event.preventDefault();\n event.stopPropagation();\n const targetUrl = resolveSafeNavigationHref(\n resolvedSourceUrl,\n source?.url,\n sanitizedHref,\n src,\n );\n if (!targetUrl) return;\n if (onNavigate) {\n onNavigate(targetUrl, imageData);\n } else {\n openSafeNavigationHref(targetUrl);\n }\n };\n\n const handleImageClick = () => {\n if (!sanitizedHref) return;\n if (onNavigate) {\n onNavigate(sanitizedHref, imageData);\n } else {\n openSafeNavigationHref(sanitizedHref);\n }\n };\n\n const hasMetadata = title || hasSource;\n\n return (\n \n \n <>\n {\n if (e.key === \"Enter\" || e.key === \" \") {\n e.preventDefault();\n handleImageClick();\n }\n }\n : undefined\n }\n >\n \n \n {hasMetadata && (\n
\n \n
\n )}\n \n \n \n );\n}\n\ninterface SourceAttributionProps {\n source?: Source;\n sourceLabel?: string;\n fallbackInitial: string;\n hasClickableUrl: boolean;\n onSourceClick: (event: React.MouseEvent) => void;\n title?: string;\n}\n\nfunction SourceAttribution({\n source,\n sourceLabel,\n fallbackInitial,\n hasClickableUrl,\n onSourceClick,\n title,\n}: SourceAttributionProps) {\n const hasSource = Boolean(sourceLabel || source?.iconUrl);\n\n const content = (\n
\n {source?.iconUrl ? (\n \n ) : fallbackInitial ? (\n
\n {fallbackInitial}\n
\n ) : null}\n
\n {title && (\n
\n {title}\n
\n )}\n {sourceLabel && (\n
\n {sourceLabel}\n
\n )}\n
\n
\n );\n\n if (hasClickableUrl && hasSource) {\n return (\n \n {content}\n \n );\n }\n\n return
{content}
;\n}\n" }, { "path": "apps/www/components/tool-ui/image/index.ts", "content": "export { Image } from \"./image\";\nexport type { ImageProps } from \"./image\";\nexport type { SerializableImage, Source } from \"./schema\";\n" }, { "path": "apps/www/components/tool-ui/image/schema.ts", "content": "import { z } from \"zod\";\nimport { defineToolUiContract } from \"../shared/contract\";\nimport {\n ToolUIIdSchema,\n ToolUIReceiptSchema,\n ToolUIRoleSchema,\n} from \"../shared/schema\";\n\nimport { AspectRatioSchema, MediaFitSchema } from \"../shared/media\";\n\nexport const SourceSchema = z.object({\n label: z.string(),\n iconUrl: z.url().optional(),\n url: z.url().optional(),\n});\n\nexport type Source = z.infer;\n\nexport const SerializableImageSchema = z.object({\n id: ToolUIIdSchema,\n role: ToolUIRoleSchema.optional(),\n receipt: ToolUIReceiptSchema.optional(),\n assetId: z.string(),\n src: z.url(),\n alt: z.string().min(1, \"Images require alt text for accessibility\"),\n title: z.string().optional(),\n description: z.string().optional(),\n href: z.url().optional(),\n domain: z.string().optional(),\n ratio: AspectRatioSchema.optional(),\n fit: MediaFitSchema.optional(),\n fileSizeBytes: z.number().int().positive().optional(),\n createdAt: z.string().datetime().optional(),\n locale: z.string().optional(),\n source: SourceSchema.optional(),\n});\n\nexport type SerializableImage = z.infer;\n\nconst SerializableImageSchemaContract = defineToolUiContract(\n \"Image\",\n SerializableImageSchema,\n);\n\nexport const parseSerializableImage: (input: unknown) => SerializableImage =\n SerializableImageSchemaContract.parse;\n\nexport const safeParseSerializableImage: (\n input: unknown,\n) => SerializableImage | null = SerializableImageSchemaContract.safeParse;\n" }, { "path": "apps/www/components/tool-ui/image-gallery/README.md", "content": "# Image Gallery\n\nImplementation for the \"image-gallery\" Tool UI surface.\n\n## Files\n\n- public exports: components/tool-ui/image-gallery/index.tsx\n- serializable schema + parse helpers: components/tool-ui/image-gallery/schema.ts\n\n## Companion assets\n\n- Docs page: app/docs/image-gallery/content.mdx\n- Preset payload: lib/presets/image-gallery.ts\n\n## Quick check\n\nRun this after edits:\n\npnpm test\n" }, { "path": "apps/www/components/tool-ui/image-gallery/_adapter.tsx", "content": "/**\n * Adapter: UI and utility re-exports for copy-standalone portability.\n *\n * When copying this component to another project, update these imports\n * to match your project's paths:\n *\n * cn → Your Tailwind merge utility (e.g., \"@/lib/utils\", \"~/lib/cn\")\n * Button → shadcn/ui Button\n */\n\nexport { cn } from \"@/lib/utils\";\nexport { Button } from \"@/components/ui/button\";\nexport { ChevronLeft, ChevronRight, X, ImageOff } from \"lucide-react\";\n" }, { "path": "apps/www/components/tool-ui/image-gallery/context.tsx", "content": "\"use client\";\n\nimport {\n createContext,\n use,\n useState,\n useCallback,\n useMemo,\n useRef,\n} from \"react\";\nimport { flushSync } from \"react-dom\";\nimport type { ImageGalleryItem } from \"./schema\";\n\nconst VIEW_TRANSITION_NAME = \"active-gallery-image\";\n\ninterface ImageGalleryContextValue {\n images: ImageGalleryItem[];\n activeIndex: number | null;\n openLightbox: (index: number) => void;\n closeLightbox: () => void;\n registerImage: (id: string, element: HTMLElement | null) => void;\n lightboxContentRef: React.RefObject;\n setDialogRef: (element: HTMLDialogElement | null) => void;\n}\n\nconst ImageGalleryContext = createContext(\n null,\n);\n\nexport function useImageGallery(): ImageGalleryContextValue {\n const context = use(ImageGalleryContext);\n if (!context) {\n throw new Error(\"useImageGallery must be used within ImageGalleryProvider\");\n }\n return context;\n}\n\nfunction supportsViewTransitions(): boolean {\n return (\n typeof document !== \"undefined\" &&\n \"startViewTransition\" in document &&\n typeof window !== \"undefined\" &&\n !window.matchMedia?.(\"(prefers-reduced-motion: reduce)\")?.matches\n );\n}\n\nfunction withViewTransition(\n element: HTMLElement,\n domUpdate: () => void,\n onFinished?: () => void,\n): void {\n if (!supportsViewTransitions()) {\n domUpdate();\n onFinished?.();\n return;\n }\n\n element.style.viewTransitionName = VIEW_TRANSITION_NAME;\n\n const transition = document.startViewTransition(() => domUpdate());\n\n transition.finished.finally(() => {\n element.style.removeProperty(\"view-transition-name\");\n onFinished?.();\n });\n}\n\ninterface ImageGalleryProviderProps {\n images: ImageGalleryItem[];\n children: React.ReactNode;\n}\n\nexport function ImageGalleryProvider({\n images,\n children,\n}: ImageGalleryProviderProps) {\n const [activeIndex, setActiveIndex] = useState(null);\n\n const imageElementsRef = useRef>(new Map());\n const lightboxContentRef = useRef(null);\n const dialogRef = useRef(null);\n const originalParentRef = useRef(null);\n\n const registerImage = useCallback(\n (id: string, element: HTMLElement | null) => {\n if (element) {\n imageElementsRef.current.set(id, element);\n } else {\n imageElementsRef.current.delete(id);\n }\n },\n [],\n );\n\n const setDialogRef = useCallback((element: HTMLDialogElement | null) => {\n dialogRef.current = element;\n }, []);\n\n const openLightbox = useCallback(\n (index: number) => {\n const image = images[index];\n if (!image) return;\n\n const imageElement = imageElementsRef.current.get(image.id);\n const container = lightboxContentRef.current;\n const dialog = dialogRef.current;\n\n if (!imageElement || !container || !dialog) {\n setActiveIndex(index);\n dialog?.showModal();\n return;\n }\n\n originalParentRef.current = imageElement.parentElement;\n\n withViewTransition(imageElement, () => {\n container.appendChild(imageElement);\n flushSync(() => setActiveIndex(index));\n dialog.showModal();\n });\n },\n [images],\n );\n\n const closeLightbox = useCallback(() => {\n if (activeIndex === null) return;\n\n const image = images[activeIndex];\n const dialog = dialogRef.current;\n\n if (!image) {\n setActiveIndex(null);\n dialog?.close();\n return;\n }\n\n const imageElement = imageElementsRef.current.get(image.id);\n const originalParent = originalParentRef.current;\n\n if (!imageElement || !originalParent) {\n setActiveIndex(null);\n dialog?.close();\n return;\n }\n\n withViewTransition(\n imageElement,\n () => {\n originalParent.appendChild(imageElement);\n flushSync(() => setActiveIndex(null));\n dialog?.close();\n },\n () => {\n originalParentRef.current = null;\n },\n );\n }, [activeIndex, images]);\n\n const value = useMemo(\n () => ({\n images,\n activeIndex,\n openLightbox,\n closeLightbox,\n registerImage,\n lightboxContentRef,\n setDialogRef,\n }),\n [\n images,\n activeIndex,\n openLightbox,\n closeLightbox,\n registerImage,\n setDialogRef,\n ],\n );\n\n return (\n \n {children}\n \n );\n}\n" }, { "path": "apps/www/components/tool-ui/image-gallery/gallery-grid.tsx", "content": "\"use client\";\n\nimport { useState, useCallback, useEffect, useRef } from \"react\";\nimport { cn, ImageOff } from \"./_adapter\";\nimport { useImageGallery } from \"./context\";\nimport type { ImageGalleryItem } from \"./schema\";\n\ntype GridImage = Pick<\n ImageGalleryItem,\n \"id\" | \"src\" | \"alt\" | \"width\" | \"height\"\n>;\n\ninterface GalleryGridProps {\n onImageClick?: (imageId: string) => void;\n}\n\nexport function GalleryGrid({ onImageClick }: GalleryGridProps) {\n const { images, openLightbox } = useImageGallery();\n\n const handleOpen = useCallback(\n (index: number) => {\n const image = images[index];\n if (image && onImageClick) {\n onImageClick(image.id);\n }\n openLightbox(index);\n },\n [images, onImageClick, openLightbox],\n );\n\n return (\n \n {images.map((image, index) => (\n \n ))}\n \n );\n}\n\ninterface GridImageCardProps {\n image: GridImage;\n index: number;\n onClick: (index: number) => void;\n}\n\nfunction GridImageCard({ image, index, onClick }: GridImageCardProps) {\n const [hasError, setHasError] = useState(false);\n const wrapperRef = useRef(null);\n\n const { registerImage } = useImageGallery();\n\n const shouldSpanTwoRows = isPortraitImage(image);\n\n useEffect(() => {\n const wrapper = wrapperRef.current;\n const img = wrapper?.querySelector(\"img\");\n if (img) {\n registerImage(image.id, img);\n }\n return () => {\n registerImage(image.id, null);\n };\n }, [image.id, registerImage]);\n\n const handleClick = useCallback(() => {\n onClick(index);\n }, [onClick, index]);\n\n return (\n \n \n\n \n {hasError ? (\n \n ) : (\n setHasError(true)}\n className=\"h-full w-full object-cover\"\n />\n )}\n \n \n );\n}\n\nfunction isPortraitImage(image: GridImage): boolean {\n const aspectRatio = image.width / image.height;\n const isPortrait = aspectRatio < 1;\n const isSquarish = aspectRatio >= 0.9 && aspectRatio <= 1.1;\n return isPortrait && !isSquarish;\n}\n\nfunction ImageErrorState({ alt }: { alt: string }) {\n return (\n
\n \n \n {alt}\n \n
\n );\n}\n" }, { "path": "apps/www/components/tool-ui/image-gallery/gallery-lightbox.tsx", "content": "\"use client\";\n\nimport { useRef, useCallback } from \"react\";\nimport { cn, Button, X } from \"./_adapter\";\nimport { useImageGallery } from \"./context\";\nimport type { ImageGalleryItem } from \"./schema\";\nimport { resolveSafeNavigationHref } from \"../shared/media\";\n\ntype LightboxImage = Pick;\n\nexport function GalleryLightbox() {\n const dialogRef = useRef(null);\n\n const {\n images,\n activeIndex,\n closeLightbox,\n lightboxContentRef,\n setDialogRef,\n } = useImageGallery();\n\n const isOpen = activeIndex !== null;\n const currentImage = isOpen ? images[activeIndex] : null;\n\n const handleDialogRef = useCallback(\n (element: HTMLDialogElement | null) => {\n dialogRef.current = element;\n setDialogRef(element);\n },\n [setDialogRef],\n );\n\n const handleBackdropClick = useCallback(\n (e: React.MouseEvent) => {\n if (e.target === dialogRef.current) {\n closeLightbox();\n }\n },\n [closeLightbox],\n );\n\n const handleCancel = useCallback(\n (e: React.SyntheticEvent) => {\n e.preventDefault();\n closeLightbox();\n },\n [closeLightbox],\n );\n\n return (\n \n
\n {isOpen && }\n
\n img]:block [&>img]:max-h-[80vh] [&>img]:max-w-full\",\n \"[&>img]:h-auto [&>img]:w-auto [&>img]:object-contain [&>img]:select-none\",\n )}\n />\n {currentImage && }\n
\n
\n \n );\n}\n\nfunction CloseButton({ onClose }: { onClose: () => void }) {\n return (\n
\n \n \n \n
\n );\n}\n\nfunction Metadata({ image }: { image: LightboxImage }) {\n const { title, caption, source } = image;\n const hasTitle = Boolean(title);\n const hasCaption = Boolean(caption);\n const hasSource = Boolean(source?.label);\n\n if (!hasTitle && !hasCaption && !hasSource) {\n return null;\n }\n\n return (\n
\n {hasTitle && (\n

\n {title}\n

\n )}\n {(hasCaption || hasSource) && (\n

\n {caption}\n {hasCaption && hasSource && \" · \"}\n {hasSource && }\n

\n )}\n
\n );\n}\n\nfunction SourceLink({\n source,\n}: {\n source: NonNullable;\n}) {\n const href = resolveSafeNavigationHref(source.url);\n if (!href) {\n return <>{source.label};\n }\n\n return (\n \n {source.label}\n \n );\n}\n" }, { "path": "apps/www/components/tool-ui/image-gallery/image-gallery.tsx", "content": "\"use client\";\n\nimport \"./styles.css\";\nimport { cn } from \"./_adapter\";\nimport { ImageGalleryProvider } from \"./context\";\nimport { GalleryGrid } from \"./gallery-grid\";\nimport { GalleryLightbox } from \"./gallery-lightbox\";\nimport type { ImageGalleryProps } from \"./schema\";\n\nexport function ImageGallery({\n id,\n images,\n title,\n description,\n className,\n onImageClick,\n}: ImageGalleryProps) {\n const handleImageClick = (imageId: string) => {\n if (!onImageClick) return;\n\n const image = images.find((img) => img.id === imageId);\n if (image) {\n onImageClick(imageId, image);\n }\n };\n\n return (\n \n \n \n
\n
\n \n
\n \n \n \n \n );\n}\n\ninterface HeaderProps {\n title?: string;\n description?: string;\n}\n\nfunction Header({ title, description }: HeaderProps) {\n if (!title && !description) {\n return null;\n }\n\n return (\n
\n {title && (\n

\n {title}\n

\n )}\n {description && (\n

\n {description}\n

\n )}\n
\n );\n}\n" }, { "path": "apps/www/components/tool-ui/image-gallery/index.tsx", "content": "export { ImageGallery } from \"./image-gallery\";\nexport type {\n ImageGalleryProps,\n ImageGalleryItem,\n SerializableImageGallery,\n} from \"./schema\";\n" }, { "path": "apps/www/components/tool-ui/image-gallery/schema.ts", "content": "import { z } from \"zod\";\nimport { defineToolUiContract } from \"../shared/contract\";\nimport {\n ToolUIIdSchema,\n ToolUIReceiptSchema,\n ToolUIRoleSchema,\n} from \"../shared/schema\";\n\nexport const ImageGallerySourceSchema = z.object({\n label: z.string(),\n url: z.string().url().optional(),\n});\n\nexport type ImageGallerySource = z.infer;\n\nexport const ImageGalleryItemSchema = z.object({\n id: z.string().min(1),\n src: z.string().url(),\n alt: z.string().min(1, \"Images require alt text for accessibility\"),\n width: z.number().positive(),\n height: z.number().positive(),\n title: z.string().optional(),\n caption: z.string().optional(),\n source: ImageGallerySourceSchema.optional(),\n});\n\nexport type ImageGalleryItem = z.infer;\n\nexport const SerializableImageGallerySchema = z.object({\n id: ToolUIIdSchema,\n role: ToolUIRoleSchema.optional(),\n receipt: ToolUIReceiptSchema.optional(),\n images: z.array(ImageGalleryItemSchema).min(1),\n title: z.string().optional(),\n description: z.string().optional(),\n});\n\nexport type SerializableImageGallery = z.infer<\n typeof SerializableImageGallerySchema\n>;\n\nexport interface ImageGalleryProps extends SerializableImageGallery {\n className?: string;\n onImageClick?: (imageId: string, image: ImageGalleryItem) => void;\n}\n\nconst SerializableImageGallerySchemaContract = defineToolUiContract(\n \"ImageGallery\",\n SerializableImageGallerySchema,\n);\n\nexport const parseSerializableImageGallery: (\n input: unknown,\n) => SerializableImageGallery = SerializableImageGallerySchemaContract.parse;\n\nexport const safeParseSerializableImageGallery: (\n input: unknown,\n) => SerializableImageGallery | null =\n SerializableImageGallerySchemaContract.safeParse;\n" }, { "path": "apps/www/components/tool-ui/image-gallery/styles.css", "content": "@supports (view-transition-name: none) {\n ::view-transition-group(active-gallery-image) {\n animation-duration: 300ms;\n animation-timing-function: cubic-bezier(0.16, 1, 0.3, 1);\n overflow: clip;\n border-radius: 0.75rem;\n }\n\n ::view-transition-image-pair(active-gallery-image) {\n overflow: clip;\n border-radius: 0.75rem;\n }\n\n ::view-transition-old(active-gallery-image),\n ::view-transition-new(active-gallery-image) {\n border-radius: 0.75rem;\n mix-blend-mode: normal;\n }\n\n @media (prefers-reduced-motion: reduce) {\n ::view-transition-group(active-gallery-image) {\n animation-duration: 0ms;\n }\n }\n}\n" }, { "path": "apps/www/components/tool-ui/index.ts", "content": "export * as ApprovalCardToolUi from \"./approval-card\";\nexport * as AudioToolUi from \"./audio\";\nexport * as ChartToolUi from \"./chart\";\nexport * as CitationToolUi from \"./citation\";\nexport * as CodeBlockToolUi from \"./code-block\";\nexport * as CodeDiffToolUi from \"./code-diff\";\nexport * as DataTableToolUi from \"./data-table\";\nexport * as GeoMapToolUi from \"./geo-map\";\nexport * as ImageToolUi from \"./image\";\nexport * as ImageGalleryToolUi from \"./image-gallery\";\nexport * as InstagramPostToolUi from \"./instagram-post\";\nexport * as ItemCarouselToolUi from \"./item-carousel\";\nexport * as LinkPreviewToolUi from \"./link-preview\";\nexport * as LinkedInPostToolUi from \"./linkedin-post\";\nexport * as MessageDraftToolUi from \"./message-draft\";\nexport * as OptionListToolUi from \"./option-list\";\nexport * as OrderSummaryToolUi from \"./order-summary\";\nexport * as ParameterSliderToolUi from \"./parameter-slider\";\nexport * as PlanToolUi from \"./plan\";\nexport * as PreferencesPanelToolUi from \"./preferences-panel\";\nexport * as ProgressTrackerToolUi from \"./progress-tracker\";\nexport * as QuestionFlowToolUi from \"./question-flow\";\nexport * as SharedToolUi from \"./shared\";\nexport * as StatsDisplayToolUi from \"./stats-display\";\nexport * as TerminalToolUi from \"./terminal\";\nexport * as VideoToolUi from \"./video\";\nexport * as WeatherWidgetToolUi from \"./weather-widget/runtime\";\nexport * as XPostToolUi from \"./x-post\";\n" }, { "path": "apps/www/components/tool-ui/instagram-post/README.md", "content": "# Instagram Post\n\nImplementation for the \"instagram-post\" Tool UI surface.\n\n## Files\n\n- public exports: components/tool-ui/instagram-post/index.ts\n- serializable schema + parse helpers: components/tool-ui/instagram-post/schema.ts\n\n## Companion assets\n\n- Docs page: app/docs/social-post/content.mdx\n- Preset payload: lib/presets/instagram-post.ts\n\n## Quick check\n\nRun this after edits:\n\npnpm test\n" }, { "path": "apps/www/components/tool-ui/instagram-post/_adapter.tsx", "content": "/**\n * Adapter: UI and utility re-exports for copy-standalone portability.\n *\n * When copying this component to another project, update these imports\n * to match your project's paths:\n *\n * cn → Your Tailwind merge utility (e.g., \"@/lib/utils\", \"~/lib/cn\")\n * Button → shadcn/ui Button\n * Tooltip → shadcn/ui Tooltip\n */\n\nexport { cn } from \"@/lib/utils\";\nexport { Button } from \"@/components/ui/button\";\nexport {\n Tooltip,\n TooltipContent,\n TooltipProvider,\n TooltipTrigger,\n} from \"@/components/ui/tooltip\";\n" }, { "path": "apps/www/components/tool-ui/instagram-post/index.ts", "content": "export { InstagramPost } from \"./instagram-post\";\nexport type { InstagramPostProps } from \"./instagram-post\";\nexport type {\n InstagramPostData,\n InstagramPostAuthor,\n InstagramPostMedia,\n InstagramPostStats,\n} from \"./schema\";\n" }, { "path": "apps/www/components/tool-ui/instagram-post/instagram-post.tsx", "content": "\"use client\";\n\nimport * as React from \"react\";\nimport { BadgeCheck, Heart, Share } from \"lucide-react\";\nimport {\n cn,\n Button,\n Tooltip,\n TooltipContent,\n TooltipProvider,\n TooltipTrigger,\n} from \"./_adapter\";\nimport { formatRelativeTime } from \"../shared/utils\";\n\nimport type { InstagramPostData, InstagramPostMedia } from \"./schema\";\n\nexport interface InstagramPostProps {\n post: InstagramPostData;\n className?: string;\n onAction?: (action: string, post: InstagramPostData) => void;\n}\n\nfunction InstagramLogo({ className }: { className?: string }) {\n const id = React.useId();\n const gradientPrimaryId = `ig-primary-${id}`;\n const gradientSecondaryId = `ig-secondary-${id}`;\n\n return (\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n );\n}\n\nfunction Header({\n author,\n createdAt,\n}: {\n author: InstagramPostData[\"author\"];\n createdAt?: string;\n}) {\n return (\n
\n \n
\n {author.handle}\n {author.verified && (\n \n )}\n {createdAt && (\n <>\n ·\n \n {formatRelativeTime(createdAt)}\n \n \n )}\n
\n \n
\n );\n}\n\nfunction MediaGrid({\n media,\n onOpen,\n}: {\n media: InstagramPostMedia[];\n onOpen?: (index: number) => void;\n}) {\n if (media.length === 0) return null;\n\n const renderItem = (item: InstagramPostMedia, index: number) => (\n onOpen?.(index)}\n >\n {item.type === \"image\" ? (\n \n ) : (\n