feat: add source-pinned Penpot design-system bindings

.aisteering/LANGUAGE.md

@@ -0,0 +1,61 @@
+# Project language
+
+## Binding contract
+
+The explicit record connecting a Penpot library component to repository source, package exports, variant semantics, and an immutable source pin.
+
+## Source pin
+
+An immutable Git commit plus a SHA-256 checksum of the bound component source file. The commit identifies the upstream repository state; the checksum detects source drift on the feature branch.
+
+## Design identity
+
+The Penpot team, project, file, component, and variant identifiers used to resolve an exact design asset.
+
+## Canonical component ID
+
+A portable identifier such as `ai.confirmation` shared by Penpot metadata and the repository manifest.
+
+## Binding contract version
+
+An integer that versions the metadata shape and resolution semantics. It is separate from the source pin and from future package release versions.
+
+## Variant mapping
+
+An exhaustive translation from Penpot variant values to React state, approval data, compound exports, or theme context. Missing mappings are errors; the tooling does not guess.
+
+## Heterogeneous variant axes
+
+Component-owned Penpot dimensions such as `State`, `Variant`, `Header`, `Visibility`, or `Change`, followed by `Theme`. The binding validator derives the required Cartesian product from each component's declared axes rather than imposing one shared state model.
+
+## Penpot page export
+
+A versioned JSON scene graph captured through Penpot MCP. It records a board's native nodes, linked component identities, reference dimensions, and explicit implementation contract without embedding an expected screenshot or generated code.
+
+## Implementation contract
+
+Board metadata that names the target source file, route, theme, and binding manifest for a design-to-code task. Missing contract values block implementation rather than selecting defaults.
+
+## Blind implementation run
+
+An evaluation in which an agent receives only the implementation skill, raw design export, binding manifest, target project, and user-level request. It does not receive the design conversation, expected screenshot, or a hand-written solution.
+
+## Section gallery
+
+A consumer-lab board containing linked instances for every mapped variant in one rollout section. A section gallery is proof of library consumption, not a source for detached design copies.
+
+## Reference export
+
+The explicit Penpot shape UUID and PNG format recorded for visual verification of a component family. It points to the stable variant container rendered and inspected during the release gate.
+
+## Composite binding dependency
+
+A linked library instance embedded inside another bound component, such as Code Block or Stack Trace inside Sandbox. The nested instance remains attached to its source component and is never replaced by a detached copy.
+
+## Device-conditioned state
+
+A visual state whose live data depends on browser media APIs, permissions, or hardware enumeration. Penpot proofs use named synthetic devices and record permission, loading, and error behavior explicitly rather than querying the designer's host.
+
+## Animated media snapshot
+
+A deterministic raster captured from an animated source at a declared component state. Persona snapshots preserve the pinned Rive visual for each style, runtime state, and theme while the React implementation remains responsible for animation and model playback.

.aisteering/README.md

@@ -0,0 +1,11 @@
+# Repository steering
+
+This directory is the source of truth for agent-facing repository knowledge added by the Penpot design-binding work.
+
+- `LANGUAGE.md` defines stable binding terminology.
+- `VALIDATION.md` defines runnable validation commands.
+- `policy-exceptions.md` records approved exceptions to explicit-behavior policy.
+- `plans/completed/penpot-design-bindings.md` records the completed implementation checklist.
+- `scratchpads/` contains selective durable working notes.
+
+Upstream project conventions remain authoritative for existing AI Elements source. This steering layer must not silently change component behavior or package APIs.

.aisteering/VALIDATION.md

@@ -0,0 +1,100 @@
+# Validation
+
+## Local component documentation
+
+```bash
+pnpm --filter docs dev --hostname 127.0.0.1 --port 3000
+```
+
+Open `http://localhost:3000/en/components/<component-slug>`. The explicit English prefix is required because the docs application stores every rendered route under `[lang]`; hiding the only locale causes a rewrite/redirect loop with the pinned Next.js and Fumadocs versions. The Chatbot release smoke-checks all 19 routes from `attachments` through `tool`, including the source-ahead `question` route. The Code release smoke-checks `agent`, `artifact`, `code-block`, `commit`, `environment-variables`, `file-tree`, `jsx-preview`, `package-info`, `sandbox`, `schema-display`, `snippet`, `stack-trace`, `terminal`, `test-results`, and `web-preview`. The Voice release smoke-checks `audio-player`, `mic-selector`, `persona`, `speech-input`, `transcription`, and `voice-selector`. The Utilities release smoke-checks `image` and `open-in-chat`.
+
+## Penpot binding tooling
+
+```bash
+pnpm penpot:bindings:test
+pnpm penpot:bindings:validate
+pnpm penpot:bindings:resolve penpot/fixtures/confirmation-component-lab.json
+pnpm penpot:bindings:resolve penpot/fixtures/code-component-lab.json
+pnpm penpot:bindings:resolve penpot/fixtures/voice-component-lab.json
+pnpm penpot:bindings:resolve penpot/fixtures/utilities-component-lab.json
+```
+
+The test command covers valid and intentionally corrupted manifests plus successful and failed instance resolution. It synthesizes and resolves every declared variant combination; the Chatbot, Code, Voice, and Utilities manifest resolves 286 variants across 42 components. The validation command verifies the checked-in manifest against the current repository, source checksum, exhaustive runtime/type exports, documentation/example paths, required Penpot identities, PNG reference targets, and exhaustive variant mappings. The resolve command translates a Penpot instance snapshot into explicit React imports and render inputs.
+
+## Utilities component behavior
+
+```bash
+cd packages/elements
+pnpm exec vitest run __tests__/image.test.tsx __tests__/open-in-chat.test.tsx
+```
+
+The Utilities release runs two focused browser suites, including the Open in Chat example query regression. Reference matrices are stored under `penpot/exports/utilities/` after visual inspection.
+
+## Voice component behavior
+
+```bash
+cd packages/elements
+pnpm exec vitest run \
+  __tests__/audio-player.test.tsx __tests__/mic-selector.test.tsx \
+  __tests__/persona.test.tsx __tests__/speech-input.test.tsx \
+  __tests__/transcription.test.tsx __tests__/voice-selector.test.tsx
+```
+
+The Voice release runs six focused browser suites. Reference matrices are stored under `penpot/exports/voice/` after visual inspection. Device and media tests use deterministic browser mocks; they do not require a host microphone, permission prompt, audio output, or a live voice service.
+
+The Audio Player suite includes an SSR regression assertion for the media element's default `tabindex="-1"`. Runtime validation must also load `/en/components/audio-player` in a real browser and confirm hydration produces no console errors.
+
+## Code component behavior
+
+```bash
+cd packages/elements
+pnpm exec vitest run \
+  __tests__/agent.test.tsx __tests__/artifact.test.tsx \
+  __tests__/code-block.test.tsx __tests__/commit.test.tsx \
+  __tests__/environment-variables.test.tsx __tests__/file-tree.test.tsx \
+  __tests__/jsx-preview.test.tsx __tests__/package-info.test.tsx \
+  __tests__/sandbox.test.tsx __tests__/schema-display.test.tsx \
+  __tests__/snippet.test.tsx __tests__/stack-trace.test.tsx \
+  __tests__/terminal.test.tsx __tests__/test-results.test.tsx \
+  __tests__/web-preview.test.tsx
+```
+
+The Code release runs 15 focused browser suites. Reference matrices are stored under `penpot/exports/code/` after visual inspection.
+
+## Chatbot component behavior
+
+```bash
+cd packages/elements
+pnpm exec vitest run \
+  __tests__/attachments.test.tsx __tests__/chain-of-thought.test.tsx \
+  __tests__/checkpoint.test.tsx __tests__/confirmation.test.tsx \
+  __tests__/context.test.tsx __tests__/conversation.test.tsx \
+  __tests__/inline-citation.test.tsx __tests__/message.test.tsx \
+  __tests__/model-selector.test.tsx __tests__/plan.test.tsx \
+  __tests__/prompt-input.test.tsx __tests__/question.test.tsx \
+  __tests__/queue.test.tsx __tests__/reasoning.test.tsx \
+  __tests__/shimmer.test.tsx __tests__/sources.test.tsx \
+  __tests__/suggestion.test.tsx __tests__/task.test.tsx \
+  __tests__/tool.test.tsx
+```
+
+Run these focused suites for a Chatbot binding release. The Attachments and Checkpoint tests close the two gaps that existed in the pinned source test inventory.
+
+On Ubuntu 26.04, Playwright 1.58 requires its explicit compatibility override for the one-time browser download:
+
+```bash
+PLAYWRIGHT_HOST_PLATFORM_OVERRIDE=ubuntu24.04-x64 packages/elements/node_modules/.bin/playwright install chromium
+```
+
+The full Elements suite now uses explicitly sized Canvas fixtures in `controls.test.tsx` and `panel.test.tsx`, avoiding React Flow's zero-size parent warning in browser tests. Run `pnpm test` before a PR; the September 2026 pre-PR run passed all 967 Elements tests and six Penpot demo tests.
+
+## Live Penpot validation
+
+1. Read shared `ai-elements/code-binding` metadata from every component variant.
+2. Confirm each source pin, checksum, export inventory, documentation path, and variant axis matches `penpot/component-bindings.json`.
+3. Verify the `Chatbot Component Lab` gallery (`fdc5d385-a945-806e-8008-864e7d404d82`) contains 76 linked instances from library `f9c80ed1-fe5b-8098-8008-85f67c505174`, with no detached copies or variant errors.
+4. Confirm the gallery has 38 Light and 38 Dark instances and all 18 newly ported component families. Confirmation remains in its preserved six-instance gallery.
+5. Export and inspect the PNG target recorded in each binding's `design.referenceExport`.
+6. Verify `Code Component Lab` (`cebd822e-5596-8078-8008-865a8fdf6abb`) contains 98 linked instances: 49 Light, 49 Dark, 15 families, zero detached proof shapes, and no foreign-library roots.
+7. Verify `Voice Component Lab` (`8633c2af-b930-8087-8008-87a4b8475c0f`) contains 100 linked instances across six families, zero detached proof shapes, no foreign-library roots, and no file validation errors.
+8. Verify `Utilities Component Lab` (`ef8ecfcc-e8fd-8021-8008-a99e412158e1`) contains six linked instances across Image and Open in Chat, three Light and three Dark, no detached proof shapes, no foreign-library roots, and no file validation errors.

.aisteering/plans/active/ai-elements-penpot-library-rollout.md

@@ -0,0 +1,113 @@
+# AI Elements Penpot library rollout
+
+Date: 2026-08-22
+
+## Objective
+
+Port the remaining AI Elements component catalog into the shared Penpot `AI Elements` file and bind every design component to the pinned React implementation. Execute one documentation section at a time because all sections mutate the same live Penpot library and binding manifest.
+
+## Shared contract
+
+- Repository: `/home/igor/Documents/code/design-system/ai-sdk-elements-shared`
+- Upstream baseline revision: `6a9d5b1822ffb10bba4bd97175f01edd7d8651cd`
+- Audio Player SSR fix revision: `e3292f6b2bb6c247fde4d74f716d3535a07f43e4`
+- Penpot library file: `f9c80ed1-fe5b-8098-8008-85f67c505174`
+- Consumer lab file: `f9c80ed1-fe5b-8098-8008-8618092b66d2`
+- Binding manifest: `penpot/component-bindings.json`
+- Canonical IDs: `ai.<component-slug>`
+- Every component requires an exact source-file SHA-256, code export inventory, Penpot UUIDs, explicit variant/state mapping, Light and Dark coverage where the component renders UI, focused tests, binding validation, and a consumer-file proof instance.
+- Linked Penpot component instances remain opaque during page implementation and must resolve through the binding manifest.
+- Publish and create a Penpot file version only after the whole section validates.
+- Only one section task may mutate Penpot or `penpot/component-bindings.json` at a time.
+
+## Section tasks
+
+### 1. Chatbot — complete
+
+- [x] attachments
+- [x] chain-of-thought
+- [x] checkpoint
+- [x] confirmation
+- [x] context
+- [x] conversation
+- [x] inline-citation
+- [x] message
+- [x] model-selector
+- [x] plan
+- [x] prompt-input
+- [x] question
+- [x] queue
+- [x] reasoning
+- [x] shimmer
+- [x] sources
+- [x] suggestion
+- [x] task
+- [x] tool
+
+Question is intentionally included from the pinned repository source and docs even though it is source-ahead of the deployed public sidebar.
+
+### 2. Code — complete
+
+- [x] agent
+- [x] artifact
+- [x] code-block
+- [x] commit
+- [x] environment-variables
+- [x] file-tree
+- [x] jsx-preview
+- [x] package-info
+- [x] sandbox
+- [x] schema-display
+- [x] snippet
+- [x] stack-trace
+- [x] terminal
+- [x] test-results
+- [x] web-preview
+
+Code adds 15 component families, 98 mapped variants, 98 linked consumer instances, and 15 checked reference PNGs. Code Block filenames and code-content layers use Geist Mono in every Light/Dark variant. Artifact composes linked Numbered Code Block instances, while Sandbox composes linked Code Block or Stack Trace instances according to the pinned examples. The preserved 19-entry Chatbot manifest slice retains its pre-Code canonical hash.
+
+### 3. Voice — complete
+
+- [x] audio-player
+- [x] mic-selector
+- [x] persona
+- [x] speech-input
+- [x] transcription
+- [x] voice-selector
+
+Voice adds six component families, 100 mapped variants, 100 linked consumer instances, and six checked reference PNGs. Persona uses source-faithful Rive snapshots across six visual styles, five runtime states, and both themes. Device-backed selectors use deterministic synthetic devices and voices for design proof while browser permission, enumeration, and media playback remain runtime concerns.
+
+Audio Player carries a repository-local source pin at `e3292f6b2bb6c247fde4d74f716d3535a07f43e4`. It preserves the upstream component API while emitting the media controller's default `tabindex="-1"` during SSR so `media-chrome` does not introduce a client-only hydration difference.
+
+### 4. Workflow — staged
+
+- [ ] canvas
+- [ ] connection
+- [ ] controls
+- [ ] edge
+- [ ] node
+- [ ] panel
+- [ ] toolbar
+
+### 5. Utilities — complete
+
+- [x] image
+- [x] open-in-chat
+
+Utilities adds two component families, six mapped variants, six linked consumer instances, and two checked reference PNGs. Image uses the existing repository example image in Light and Dark. Open in Chat covers closed/open menu states and six provider links in both themes. The documented example now supplies `query` to the parent `OpenIn` context, with a focused regression test.
+
+## Per-section acceptance gates
+
+- [x] Source and documentation/example inventory is complete.
+- [x] Every component has representative Light and Dark Penpot visuals or an explicit documented nonvisual exception.
+- [x] Every design component has stable UUID metadata and a manifest entry.
+- [x] Manifest source hashes and variant mappings validate mechanically.
+- [x] A section gallery in the consumer lab resolves to library components rather than detached copies.
+- [x] Reference PNG exports are visually checked.
+- [x] Focused tests, binding tests, and binding validation pass.
+- [x] `.aisteering/LANGUAGE.md`, scratchpad, and section summary are current.
+- [x] Changes are committed on the feature branch before the next section starts.
+
+## Execution order
+
+Chatbot → Code → Voice → Utilities → Workflow. Chatbot, Code, Voice, and Utilities are accepted. On 2026-09-19, the user requested that Utilities be finished ahead of Workflow. Utilities is the completed writer slot; Workflow is next after the Utilities commit handoff and must revalidate the 42-binding baseline before writing.

.aisteering/plans/completed/mcp-design-implementation-evaluation.md

@@ -0,0 +1,24 @@
+# MCP design-to-implementation evaluation
+
+Date: 2026-08-22
+
+## Objective
+
+Test whether a fresh agent can implement a simple Penpot page from raw MCP artifacts by following a reusable repo-local skill, without access to the design conversation or an expected implementation.
+
+## Acceptance criteria
+
+- [x] A new Penpot page contains ordinary layout/text plus linked `ai.confirmation` component instances.
+- [x] The page exposes an explicit implementation contract and can be exported through MCP.
+- [x] A repo-local skill explains identity checks, binding resolution, layout translation, asset handling, and validation.
+- [x] An empty demo project defines its framework, commands, and acceptance tests without containing the solution.
+- [x] A fresh agent with no conversation context implements the page using only the skill and raw artifacts.
+- [x] The resulting project builds, runs, resolves linked components correctly, and is visually compared against Penpot.
+- [x] Skill gaps discovered by the blind run were corrected and revalidated.
+
+## Isolation rules used
+
+- The fresh agent did not receive the expected screenshot, intended DOM, or a hand-written solution.
+- The fresh agent did not receive the design conversation or conclusions about likely mistakes.
+- The handoff contained only the skill path, raw MCP artifact path, binding manifest path, demo-project path, and user-level request.
+- The first attempt was committed before corrections and documented in `penpot/evaluations/2026-08-22-blind-first-attempt.md`.

.aisteering/plans/completed/penpot-design-bindings.md

@@ -0,0 +1,27 @@
+# Penpot design binding and source pin
+
+Date: 2026-08-22
+
+Status: completed
+
+## Objective
+
+Resolve the Penpot `ai.confirmation` component to the exact AI Elements React implementation without relying on a moving branch, implicit package version, or inferred variant behavior.
+
+## Acceptance criteria
+
+- [x] A checked-in manifest records the immutable upstream Git commit and SHA-256 checksum for `packages/elements/src/confirmation.tsx`.
+- [x] The manifest records the Penpot file/component identities and shared-plugin-data location.
+- [x] The manifest maps all `State` and `Theme` values explicitly to runtime semantics.
+- [x] Validation fails for a mismatched source checksum, missing required variant, missing export, invalid identity, or non-ancestor source revision.
+- [x] Tests cover the valid manifest and representative invalid manifests.
+- [x] Penpot shared metadata carries the same source pin and binding contract version.
+- [x] A linked consumer instance resolves back to the same component and source pin.
+- [x] Existing Confirmation component behavior remains unchanged.
+
+## Boundaries
+
+- Do not modify the Confirmation component API for metadata needs.
+- Do not infer or default missing mappings.
+- Do not use a mutable branch name such as `main` as the authoritative source version.
+- Do not publish credentials, browser state, or Penpot MCP tokens.

.aisteering/policy-exceptions.md

@@ -0,0 +1,3 @@
+# Policy exceptions
+
+No exceptions are approved.