[Loop] issue-dev-loop state journal

[codeacme17]

This issue is the durable, append-only finalization journal for the repository's issue-dev-loop.\n\nAutomation will append SHA-256-bound terminal run records here so new worktrees can reconstruct logs/index.jsonl and evolve metrics. Human review, decisions, and merge authority remain on the relevant pull requests.\n\nDo not edit or delete automation-authored journal entries. Loop implementation and policy changes still require an owner-reviewed pull request.

[Ethandasw]

undefined

[Ethandasw]

{"schemaVersion":1,"kind":"active-checkpoint","run":{"schemaVersion":1,"runId":"20260724T132107Z-issue-108-743034","issueNumber":108,"issueTitle":"docs: close the remaining Island UI and content parity gaps in Nextra","issueUrl":"https://github.com/codeacme17/echo-ui/issues/108","baseBranch":"dev","baseSha":"9eea05360a90e46a4c66c2e821e9ad5bd6c71c67","branch":"codex/issue-108","status":"running","startedAt":"2026-07-24T13:21:07.375Z","finishedAt":null,"prUrl":null,"headSha":null,"mergeSha":null,"issueSnapshot":{"title":"docs: close the remaining Island UI and content parity gaps in Nextra","body":"## Context\n\nThis is a follow-up to #97 / #98. That work required the Nextra documentation to reproduce the established Island site exactly, with `https://echoui.dev/en/` as the visual source of truth. A fresh comparison against the current `dev` branch shows that the shell is closer, but substantial UI, information-architecture, and example-coverage differences remain.\n\nKeep Nextra. “Parity” here means preserving the Island presentation and documentation coverage while retaining factual improvements made for Echo UI 1.1.x (React 19, Tailwind CSS 4, Tone.js 15, accessibility, lifecycle, and error guidance). It does **not** mean restoring IslandJS, NextUI, stale setup instructions, or old implementation dependencies.\n\n## How to compare\n\n1. Run `pnpm dev:docs`.\n2. Compare the same English and Chinese routes against `https://echoui.dev/en/` and `https://echoui.dev/zh/`.\n3. At minimum, inspect `/`, `/guide/introduction`, `/guide/about`, `/component/button`, `/component/knob`, `/component/spectrogram`, and `/hook/usePlayer`.\n4. Compare 1440×900 and 390×844 in both light and dark themes.\n\n## Observed differences\n\n### 1. Site shell and navigation\n\n| Area | Island reference | Current Nextra site |\n| --- | --- | --- |\n| `/` | Redirects directly to `/en` | Shows a separate editorial “Choose your documentation language” landing page |\n| Links menu | GitHub, Discord, Twitter | Discussions, Issues, Discord |\n| Guide sidebar | Shows a `Guide` group heading and a separated `About` group | Renders a flat four-link list |\n| Contribution/navigation affordances | Exposes “Edit this page on GitHub”, last-updated metadata, and previous/next page navigation | `editLink={null}` and `navigation={false}`; only the timestamp remains |\n| Footer | Island configuration contains license/copyright and page navigation metadata | The Nextra footer is mounted but globally hidden |\n| External links | Plain Island link treatment | Nextra adds external-link arrow glyphs throughout prose |\n| Callouts | Neutral Island bordered panel | Blue Nextra info callout with icon and different spacing/color |\n\nThere is also a content/implementation contradiction: the Declaration page says readers can use “the edit link on each page”, while the layout explicitly disables edit links.\n\nRelevant files:\n\n- `docs/app/[lang]/layout.tsx`\n- `docs/app/[lang]/island-theme.css`\n- `docs/app/(landing)/page.tsx`\n- `docs/content/en/_meta.ts`\n- `docs/content/zh/_meta.ts`\n- `docs/content/*/guide/declaration.mdx`\n\n### 2. Guide content and hierarchy\n\n- Introduction feature bullets became five H3 sections. This materially changes page length, scan rhythm, and the table of contents.\n- All guide copy was rewritten rather than migrated in place. Some updates are useful and should remain, but the result is not content parity with the Island reference.\n- About removed the WeChat community option and QR code even though `wechat.jpg` is still shipped as a public asset.\n- Installation is correctly modernized for 1.1.x, but its presentation no longer follows the four-step Island structure.\n- The root language-selection page introduces a visual language that does not exist anywhere in the Island site.\n\n### 3. Component example coverage was reduced\n\nThe Island source had 30 files under `docs/src/components/UsageBox` and `docs/src/components/Example`. The current site consolidates the documentation into a small set of shared demo files and generally renders one demo per component page.\n\n| Component | Island examples no longer shown as equivalent live variants |\n| --- | --- |\n| Button | default, toggled, disabled, sizes, radii, group |\n| Checkbox | default, disabled, sizes, colors, group |\n| Envelope | ADSR, AHDSR, DADSR/delay |\n| Input | default, disabled, bilateral, text, sizes, radii, progress color, min/max, step/sensitivity |\n| Knob | default, disabled, bilateral, rotation range, labels, step/sensitivity, sizes, colors, group |\n| Radio | default, disabled, sizes, colors, group |\n| Slider | default, disabled, vertical, bilateral, axis, step, custom styling, uncontrolled |\n| Switch | default, toggled, disabled, sizes, custom styling |\n| LFO | default and delay |\n| Light | default, on, colors, sizes |\n| Spectrogram | default, axis, grid, EQ3 scenario |\n| VU Meter | default, horizontal, stereo, compact, segment count, custom colors |\n| Card | default, active, real-world scenario |\n\nOscilloscope and Waveform still have a live example, but they also lost the Island example affordance described below.\n\n### 4. The example and API presentation is different\n\n- Island gives every example a `Preview` / `Code` switch. The current demo frame has only a `Preview` label; source is no longer available beside each rendered variant.\n- Current demos add useful live status and more realistic audio flows, but they replace rather than supplement the variant matrix above.\n- Island API tables use `Attribute / Description / Type / Default`; current tables use `Prop / Type / Default / Description` and add a new inherited-props paragraph.\n- Dedicated Data Attributes/Data Tags sections were removed from most component pages. The current docs only surface a small subset (for example VU Meter `data-active` and Card `data-toggled`).\n- Full type-declaration blocks were removed in favor of generated API tables. Keep the tables if they are complete, but restore any public contract details that are no longer discoverable.\n- Hook pages gained live demos, lifecycle, and error guidance; preserve those improvements while matching the Island visual hierarchy and API discoverability.\n\nRelevant files:\n\n- `docs/app/_components/controller-demo.tsx`\n- `docs/app/_components/display-*.tsx`\n- `docs/app/_components/hook-demo.tsx`\n- `docs/app/_components/*-api.tsx`\n- `docs/app/_components/*-docs.module.css`\n- `docs/content/{en,zh}/component/*.mdx`\n- `docs/content/{en,zh}/hook/*.mdx`\n\n## Why the current regression check misses this\n\n`scripts/verify-docs-ui.mjs` compares the current site with hand-written style constants. It does not compare the output with an Island screenshot/DOM baseline. It verifies the shell mainly through the Button route and only requires each component route to contain at least one demo, so it cannot catch reduced example coverage, changed copy/hierarchy, missing links, or changed root behavior.\n\nThe two files under `docs/screenshots/` are unreferenced migration-preview captures, not Island parity baselines.\n\n## Acceptance criteria\n\n- [ ] Create and document an Island → Nextra parity matrix covering shell, navigation, content hierarchy, examples, API/data-attribute coverage, and intentional modernized exceptions.\n- [ ] Match the Island shell at 1440×900 and 390×844 in English/Chinese and light/dark themes, including the root-route behavior, sidebar grouping, callouts, link treatment, and page-level navigation affordances.\n- [ ] Restore the Island Links destinations, edit-page affordance, previous/next navigation, and footer behavior, or explicitly document an approved product decision for each deviation.\n- [ ] Fix the Declaration copy so it agrees with the actual edit-link behavior.\n- [ ] Give every Island component variant an equivalent live preview and adjacent copyable source, unless its removal is explicitly approved in the parity matrix.\n- [ ] Restore missing Data Attributes/Data Tags and public type/API details.\n- [ ] Preserve the current 1.1.x installation, Tone.js 15, accessibility, lifecycle, error-handling, and real-audio-demo improvements.\n- [ ] Replace the current style-constant-only check with maintained Island visual baselines (or an equivalent deterministic comparison) for representative guide, controller, visualization, Hook, and home routes.\n- [ ] Add content-inventory assertions for example labels/counts, Links destinations, edit/pagination controls, root behavior, and both locales.\n- [ ] `pnpm lint`, `pnpm typecheck:docs`, `pnpm build:docs`, and `pnpm test:docs` pass.\n\n## Out of scope\n\n- Reintroducing IslandJS, NextUI, or `react-live`\n- Reverting accurate Echo UI 1.1.x compatibility and API information\n- Removing accessibility or real Web Audio improvements solely to obtain pixel parity\n","labels":["codex-ready"],"url":"https://github.com/codeacme17/echo-ui/issues/108","capturedAt":"2026-07-24T13:21:07.375Z"},"briefDigest":null,"uiEvidenceRequired":null,"implementationCommit":null},"briefSource":"# Implementation brief\n\n- Run ID: `20260724T132107Z-issue-108-743034`\n- Issue: #108 — docs: close the remaining Island UI and content parity gaps in Nextra\n- Issue URL: https://github.com/codeacme17/echo-ui/issues/108\n- Base branch: `dev`\n- Base SHA: `9eea05360a90e46a4c66c2e821e9ad5bd6c71c67`\n- Branch: `codex/issue-108`\n- UI evidence required: UNSET\n\n## Issue snapshot\n\n## Context\n\nThis is a follow-up to #97 / #98. That work required the Nextra documentation to reproduce the established Island site exactly, with `https://echoui.dev/en/` as the visual source of truth. A fresh comparison against the current `dev` branch shows that the shell is closer, but substantial UI, information-architecture, and example-coverage differences remain.\n\nKeep Nextra. “Parity” here means preserving the Island presentation and documentation coverage while retaining factual improvements made for Echo UI 1.1.x (React 19, Tailwind CSS 4, Tone.js 15, accessibility, lifecycle, and error guidance). It does **not** mean restoring IslandJS, NextUI, stale setup instructions, or old implementation dependencies.\n\n## How to compare\n\n1. Run `pnpm dev:docs`.\n2. Compare the same English and Chinese routes against `https://echoui.dev/en/` and `https://echoui.dev/zh/`.\n3. At minimum, inspect `/`, `/guide/introduction`, `/guide/about`, `/component/button`, `/component/knob`, `/component/spectrogram`, and `/hook/usePlayer`.\n4. Compare 1440×900 and 390×844 in both light and dark themes.\n\n## Observed differences\n\n### 1. Site shell and navigation\n\n| Area | Island reference | Current Nextra site |\n| --- | --- | --- |\n| `/` | Redirects directly to `/en` | Shows a separate editorial “Choose your documentation language” landing page |\n| Links menu | GitHub, Discord, Twitter | Discussions, Issues, Discord |\n| Guide sidebar | Shows a `Guide` group heading and a separated `About` group | Renders a flat four-link list |\n| Contribution/navigation affordances | Exposes “Edit this page on GitHub”, last-updated metadata, and previous/next page navigation | `editLink={null}` and `navigation={false}`; only the timestamp remains |\n| Footer | Island configuration contains license/copyright and page navigation metadata | The Nextra footer is mounted but globally hidden |\n| External links | Plain Island link treatment | Nextra adds external-link arrow glyphs throughout prose |\n| Callouts | Neutral Island bordered panel | Blue Nextra info callout with icon and different spacing/color |\n\nThere is also a content/implementation contradiction: the Declaration page says readers can use “the edit link on each page”, while the layout explicitly disables edit links.\n\nRelevant files:\n\n- `docs/app/[lang]/layout.tsx`\n- `docs/app/[lang]/island-theme.css`\n- `docs/app/(landing)/page.tsx`\n- `docs/content/en/_meta.ts`\n- `docs/content/zh/_meta.ts`\n- `docs/content/*/guide/declaration.mdx`\n\n### 2. Guide content and hierarchy\n\n- Introduction feature bullets became five H3 sections. This materially changes page length, scan rhythm, and the table of contents.\n- All guide copy was rewritten rather than migrated in place. Some updates are useful and should remain, but the result is not content parity with the Island reference.\n- About removed the WeChat community option and QR code even though `wechat.jpg` is still shipped as a public asset.\n- Installation is correctly modernized for 1.1.x, but its presentation no longer follows the four-step Island structure.\n- The root language-selection page introduces a visual language that does not exist anywhere in the Island site.\n\n### 3. Component example coverage was reduced\n\nThe Island source had 30 files under `docs/src/components/UsageBox` and `docs/src/components/Example`. The current site consolidates the documentation into a small set of shared demo files and generally renders one demo per component page.\n\n| Component | Island examples no longer shown as equivalent live variants |\n| --- | --- |\n| Button | default, toggled, disabled, sizes, radii, group |\n| Checkbox | default, disabled, sizes, colors, group |\n| Envelope | ADSR, AHDSR, DADSR/delay |\n| Input | default, disabled, bilateral, text, sizes, radii, progress color, min/max, step/sensitivity |\n| Knob | default, disabled, bilateral, rotation range, labels, step/sensitivity, sizes, colors, group |\n| Radio | default, disabled, sizes, colors, group |\n| Slider | default, disabled, vertical, bilateral, axis, step, custom styling, uncontrolled |\n| Switch | default, toggled, disabled, sizes, custom styling |\n| LFO | default and delay |\n| Light | default, on, colors, sizes |\n| Spectrogram | default, axis, grid, EQ3 scenario |\n| VU Meter | default, horizontal, stereo, compact, segment count, custom colors |\n| Card | default, active, real-world scenario |\n\nOscilloscope and Waveform still have a live example, but they also lost the Island example affordance described below.\n\n### 4. The example and API presentation is different\n\n- Island gives every example a `Preview` / `Code` switch. The current demo frame has only a `Preview` label; source is no longer available beside each rendered variant.\n- Current demos add useful live status and more realistic audio flows, but they replace rather than supplement the variant matrix above.\n- Island API tables use `Attribute / Description / Type / Default`; current tables use `Prop / Type / Default / Description` and add a new inherited-props paragraph.\n- Dedicated Data Attributes/Data Tags sections were removed from most component pages. The current docs only surface a small subset (for example VU Meter `data-active` and Card `data-toggled`).\n- Full type-declaration blocks were removed in favor of generated API tables. Keep the tables if they are complete, but restore any public contract details that are no longer discoverable.\n- Hook pages gained live demos, lifecycle, and error guidance; preserve those improvements while matching the Island visual hierarchy and API discoverability.\n\nRelevant files:\n\n- `docs/app/_components/controller-demo.tsx`\n- `docs/app/_components/display-*.tsx`\n- `docs/app/_components/hook-demo.tsx`\n- `docs/app/_components/*-api.tsx`\n- `docs/app/_components/*-docs.module.css`\n- `docs/content/{en,zh}/component/*.mdx`\n- `docs/content/{en,zh}/hook/*.mdx`\n\n## Why the current regression check misses this\n\n`scripts/verify-docs-ui.mjs` compares the current site with hand-written style constants. It does not compare the output with an Island screenshot/DOM baseline. It verifies the shell mainly through the Button route and only requires each component route to contain at least one demo, so it cannot catch reduced example coverage, changed copy/hierarchy, missing links, or changed root behavior.\n\nThe two files under `docs/screenshots/` are unreferenced migration-preview captures, not Island parity baselines.\n\n## Acceptance criteria\n\n- [ ] Create and document an Island → Nextra parity matrix covering shell, navigation, content hierarchy, examples, API/data-attribute coverage, and intentional modernized exceptions.\n- [ ] Match the Island shell at 1440×900 and 390×844 in English/Chinese and light/dark themes, including the root-route behavior, sidebar grouping, callouts, link treatment, and page-level navigation affordances.\n- [ ] Restore the Island Links destinations, edit-page affordance, previous/next navigation, and footer behavior, or explicitly document an approved product decision for each deviation.\n- [ ] Fix the Declaration copy so it agrees with the actual edit-link behavior.\n- [ ] Give every Island component variant an equivalent live preview and adjacent copyable source, unless its removal is explicitly approved in the parity matrix.\n- [ ] Restore missing Data Attributes/Data Tags and public type/API details.\n- [ ] Preserve the current 1.1.x installation, Tone.js 15, accessibility, lifecycle, error-handling, and real-audio-demo improvements.\n- [ ] Replace the current style-constant-only check with maintained Island visual baselines (or an equivalent deterministic comparison) for representative guide, controller, visualization, Hook, and home routes.\n- [ ] Add content-inventory assertions for example labels/counts, Links destinations, edit/pagination controls, root behavior, and both locales.\n- [ ] `pnpm lint`, `pnpm typecheck:docs`, `pnpm build:docs`, and `pnpm test:docs` pass.\n\n## Out of scope\n\n- Reintroducing IslandJS, NextUI, or `react-live`\n- Reverting accurate Echo UI 1.1.x compatibility and API information\n- Removing accessibility or real Web Audio improvements solely to obtain pixel parity\n\n\n## Acceptance criteria\n\n<!-- Freeze concrete, testable criteria before invoking $implement. -->\n\n## In scope\n\n## Out of scope\n\n## Pre-agreed TDD seams\n\n## Required targeted checks\n\n## Required UI evidence\n\n## Risks and owner-confirmation boundaries\n\n## Stop conditions\n\nStop after committing. Do not push, create a PR, or merge.\n","events":[{"schemaVersion":1,"runId":"20260724T132107Z-issue-108-743034","type":"loop_started","timestamp":"2026-07-24T13:21:07.375Z","status":"running","payload":{"issueNumber":108,"branch":"codex/issue-108"}}],"artifacts":[],"updatedAt":"2026-07-24T13:21:07.375Z"}

[Ethandasw]

{"schemaVersion":1,"kind":"active-checkpoint","run":{"schemaVersion":1,"runId":"20260724T132107Z-issue-108-743034","issueNumber":108,"issueTitle":"docs: close the remaining Island UI and content parity gaps in Nextra","issueUrl":"https://github.com/codeacme17/echo-ui/issues/108","baseBranch":"dev","baseSha":"9eea05360a90e46a4c66c2e821e9ad5bd6c71c67","branch":"codex/issue-108","status":"running","startedAt":"2026-07-24T13:21:07.375Z","finishedAt":null,"prUrl":null,"headSha":null,"mergeSha":null,"issueSnapshot":{"title":"docs: close the remaining Island UI and content parity gaps in Nextra","body":"## Context\n\nThis is a follow-up to #97 / #98. That work required the Nextra documentation to reproduce the established Island site exactly, with `https://echoui.dev/en/` as the visual source of truth. A fresh comparison against the current `dev` branch shows that the shell is closer, but substantial UI, information-architecture, and example-coverage differences remain.\n\nKeep Nextra. “Parity” here means preserving the Island presentation and documentation coverage while retaining factual improvements made for Echo UI 1.1.x (React 19, Tailwind CSS 4, Tone.js 15, accessibility, lifecycle, and error guidance). It does **not** mean restoring IslandJS, NextUI, stale setup instructions, or old implementation dependencies.\n\n## How to compare\n\n1. Run `pnpm dev:docs`.\n2. Compare the same English and Chinese routes against `https://echoui.dev/en/` and `https://echoui.dev/zh/`.\n3. At minimum, inspect `/`, `/guide/introduction`, `/guide/about`, `/component/button`, `/component/knob`, `/component/spectrogram`, and `/hook/usePlayer`.\n4. Compare 1440×900 and 390×844 in both light and dark themes.\n\n## Observed differences\n\n### 1. Site shell and navigation\n\n| Area | Island reference | Current Nextra site |\n| --- | --- | --- |\n| `/` | Redirects directly to `/en` | Shows a separate editorial “Choose your documentation language” landing page |\n| Links menu | GitHub, Discord, Twitter | Discussions, Issues, Discord |\n| Guide sidebar | Shows a `Guide` group heading and a separated `About` group | Renders a flat four-link list |\n| Contribution/navigation affordances | Exposes “Edit this page on GitHub”, last-updated metadata, and previous/next page navigation | `editLink={null}` and `navigation={false}`; only the timestamp remains |\n| Footer | Island configuration contains license/copyright and page navigation metadata | The Nextra footer is mounted but globally hidden |\n| External links | Plain Island link treatment | Nextra adds external-link arrow glyphs throughout prose |\n| Callouts | Neutral Island bordered panel | Blue Nextra info callout with icon and different spacing/color |\n\nThere is also a content/implementation contradiction: the Declaration page says readers can use “the edit link on each page”, while the layout explicitly disables edit links.\n\nRelevant files:\n\n- `docs/app/[lang]/layout.tsx`\n- `docs/app/[lang]/island-theme.css`\n- `docs/app/(landing)/page.tsx`\n- `docs/content/en/_meta.ts`\n- `docs/content/zh/_meta.ts`\n- `docs/content/*/guide/declaration.mdx`\n\n### 2. Guide content and hierarchy\n\n- Introduction feature bullets became five H3 sections. This materially changes page length, scan rhythm, and the table of contents.\n- All guide copy was rewritten rather than migrated in place. Some updates are useful and should remain, but the result is not content parity with the Island reference.\n- About removed the WeChat community option and QR code even though `wechat.jpg` is still shipped as a public asset.\n- Installation is correctly modernized for 1.1.x, but its presentation no longer follows the four-step Island structure.\n- The root language-selection page introduces a visual language that does not exist anywhere in the Island site.\n\n### 3. Component example coverage was reduced\n\nThe Island source had 30 files under `docs/src/components/UsageBox` and `docs/src/components/Example`. The current site consolidates the documentation into a small set of shared demo files and generally renders one demo per component page.\n\n| Component | Island examples no longer shown as equivalent live variants |\n| --- | --- |\n| Button | default, toggled, disabled, sizes, radii, group |\n| Checkbox | default, disabled, sizes, colors, group |\n| Envelope | ADSR, AHDSR, DADSR/delay |\n| Input | default, disabled, bilateral, text, sizes, radii, progress color, min/max, step/sensitivity |\n| Knob | default, disabled, bilateral, rotation range, labels, step/sensitivity, sizes, colors, group |\n| Radio | default, disabled, sizes, colors, group |\n| Slider | default, disabled, vertical, bilateral, axis, step, custom styling, uncontrolled |\n| Switch | default, toggled, disabled, sizes, custom styling |\n| LFO | default and delay |\n| Light | default, on, colors, sizes |\n| Spectrogram | default, axis, grid, EQ3 scenario |\n| VU Meter | default, horizontal, stereo, compact, segment count, custom colors |\n| Card | default, active, real-world scenario |\n\nOscilloscope and Waveform still have a live example, but they also lost the Island example affordance described below.\n\n### 4. The example and API presentation is different\n\n- Island gives every example a `Preview` / `Code` switch. The current demo frame has only a `Preview` label; source is no longer available beside each rendered variant.\n- Current demos add useful live status and more realistic audio flows, but they replace rather than supplement the variant matrix above.\n- Island API tables use `Attribute / Description / Type / Default`; current tables use `Prop / Type / Default / Description` and add a new inherited-props paragraph.\n- Dedicated Data Attributes/Data Tags sections were removed from most component pages. The current docs only surface a small subset (for example VU Meter `data-active` and Card `data-toggled`).\n- Full type-declaration blocks were removed in favor of generated API tables. Keep the tables if they are complete, but restore any public contract details that are no longer discoverable.\n- Hook pages gained live demos, lifecycle, and error guidance; preserve those improvements while matching the Island visual hierarchy and API discoverability.\n\nRelevant files:\n\n- `docs/app/_components/controller-demo.tsx`\n- `docs/app/_components/display-*.tsx`\n- `docs/app/_components/hook-demo.tsx`\n- `docs/app/_components/*-api.tsx`\n- `docs/app/_components/*-docs.module.css`\n- `docs/content/{en,zh}/component/*.mdx`\n- `docs/content/{en,zh}/hook/*.mdx`\n\n## Why the current regression check misses this\n\n`scripts/verify-docs-ui.mjs` compares the current site with hand-written style constants. It does not compare the output with an Island screenshot/DOM baseline. It verifies the shell mainly through the Button route and only requires each component route to contain at least one demo, so it cannot catch reduced example coverage, changed copy/hierarchy, missing links, or changed root behavior.\n\nThe two files under `docs/screenshots/` are unreferenced migration-preview captures, not Island parity baselines.\n\n## Acceptance criteria\n\n- [ ] Create and document an Island → Nextra parity matrix covering shell, navigation, content hierarchy, examples, API/data-attribute coverage, and intentional modernized exceptions.\n- [ ] Match the Island shell at 1440×900 and 390×844 in English/Chinese and light/dark themes, including the root-route behavior, sidebar grouping, callouts, link treatment, and page-level navigation affordances.\n- [ ] Restore the Island Links destinations, edit-page affordance, previous/next navigation, and footer behavior, or explicitly document an approved product decision for each deviation.\n- [ ] Fix the Declaration copy so it agrees with the actual edit-link behavior.\n- [ ] Give every Island component variant an equivalent live preview and adjacent copyable source, unless its removal is explicitly approved in the parity matrix.\n- [ ] Restore missing Data Attributes/Data Tags and public type/API details.\n- [ ] Preserve the current 1.1.x installation, Tone.js 15, accessibility, lifecycle, error-handling, and real-audio-demo improvements.\n- [ ] Replace the current style-constant-only check with maintained Island visual baselines (or an equivalent deterministic comparison) for representative guide, controller, visualization, Hook, and home routes.\n- [ ] Add content-inventory assertions for example labels/counts, Links destinations, edit/pagination controls, root behavior, and both locales.\n- [ ] `pnpm lint`, `pnpm typecheck:docs`, `pnpm build:docs`, and `pnpm test:docs` pass.\n\n## Out of scope\n\n- Reintroducing IslandJS, NextUI, or `react-live`\n- Reverting accurate Echo UI 1.1.x compatibility and API information\n- Removing accessibility or real Web Audio improvements solely to obtain pixel parity\n","labels":["codex-ready"],"url":"https://github.com/codeacme17/echo-ui/issues/108","capturedAt":"2026-07-24T13:21:07.375Z"},"briefDigest":null,"uiEvidenceRequired":null,"implementationCommit":null},"briefSource":"# Implementation brief\n\n- Run ID: `20260724T132107Z-issue-108-743034`\n- Issue: #108 — docs: close the remaining Island UI and content parity gaps in Nextra\n- Issue URL: https://github.com/codeacme17/echo-ui/issues/108\n- Base branch: `dev`\n- Base SHA: `9eea05360a90e46a4c66c2e821e9ad5bd6c71c67`\n- Branch: `codex/issue-108`\n- UI evidence required: yes\n\n## Issue snapshot\n\n## Context\n\nThis is a follow-up to #97 / #98. That work required the Nextra documentation to reproduce the established Island site exactly, with `https://echoui.dev/en/` as the visual source of truth. A fresh comparison against the current `dev` branch shows that the shell is closer, but substantial UI, information-architecture, and example-coverage differences remain.\n\nKeep Nextra. “Parity” here means preserving the Island presentation and documentation coverage while retaining factual improvements made for Echo UI 1.1.x (React 19, Tailwind CSS 4, Tone.js 15, accessibility, lifecycle, and error guidance). It does **not** mean restoring IslandJS, NextUI, stale setup instructions, or old implementation dependencies.\n\n## How to compare\n\n1. Run `pnpm dev:docs`.\n2. Compare the same English and Chinese routes against `https://echoui.dev/en/` and `https://echoui.dev/zh/`.\n3. At minimum, inspect `/`, `/guide/introduction`, `/guide/about`, `/component/button`, `/component/knob`, `/component/spectrogram`, and `/hook/usePlayer`.\n4. Compare 1440×900 and 390×844 in both light and dark themes.\n\n## Observed differences\n\n### 1. Site shell and navigation\n\n| Area | Island reference | Current Nextra site |\n| --- | --- | --- |\n| `/` | Redirects directly to `/en` | Shows a separate editorial “Choose your documentation language” landing page |\n| Links menu | GitHub, Discord, Twitter | Discussions, Issues, Discord |\n| Guide sidebar | Shows a `Guide` group heading and a separated `About` group | Renders a flat four-link list |\n| Contribution/navigation affordances | Exposes “Edit this page on GitHub”, last-updated metadata, and previous/next page navigation | `editLink={null}` and `navigation={false}`; only the timestamp remains |\n| Footer | Island configuration contains license/copyright and page navigation metadata | The Nextra footer is mounted but globally hidden |\n| External links | Plain Island link treatment | Nextra adds external-link arrow glyphs throughout prose |\n| Callouts | Neutral Island bordered panel | Blue Nextra info callout with icon and different spacing/color |\n\nThere is also a content/implementation contradiction: the Declaration page says readers can use “the edit link on each page”, while the layout explicitly disables edit links.\n\nRelevant files:\n\n- `docs/app/[lang]/layout.tsx`\n- `docs/app/[lang]/island-theme.css`\n- `docs/app/(landing)/page.tsx`\n- `docs/content/en/_meta.ts`\n- `docs/content/zh/_meta.ts`\n- `docs/content/*/guide/declaration.mdx`\n\n### 2. Guide content and hierarchy\n\n- Introduction feature bullets became five H3 sections. This materially changes page length, scan rhythm, and the table of contents.\n- All guide copy was rewritten rather than migrated in place. Some updates are useful and should remain, but the result is not content parity with the Island reference.\n- About removed the WeChat community option and QR code even though `wechat.jpg` is still shipped as a public asset.\n- Installation is correctly modernized for 1.1.x, but its presentation no longer follows the four-step Island structure.\n- The root language-selection page introduces a visual language that does not exist anywhere in the Island site.\n\n### 3. Component example coverage was reduced\n\nThe Island source had 30 files under `docs/src/components/UsageBox` and `docs/src/components/Example`. The current site consolidates the documentation into a small set of shared demo files and generally renders one demo per component page.\n\n| Component | Island examples no longer shown as equivalent live variants |\n| --- | --- |\n| Button | default, toggled, disabled, sizes, radii, group |\n| Checkbox | default, disabled, sizes, colors, group |\n| Envelope | ADSR, AHDSR, DADSR/delay |\n| Input | default, disabled, bilateral, text, sizes, radii, progress color, min/max, step/sensitivity |\n| Knob | default, disabled, bilateral, rotation range, labels, step/sensitivity, sizes, colors, group |\n| Radio | default, disabled, sizes, colors, group |\n| Slider | default, disabled, vertical, bilateral, axis, step, custom styling, uncontrolled |\n| Switch | default, toggled, disabled, sizes, custom styling |\n| LFO | default and delay |\n| Light | default, on, colors, sizes |\n| Spectrogram | default, axis, grid, EQ3 scenario |\n| VU Meter | default, horizontal, stereo, compact, segment count, custom colors |\n| Card | default, active, real-world scenario |\n\nOscilloscope and Waveform still have a live example, but they also lost the Island example affordance described below.\n\n### 4. The example and API presentation is different\n\n- Island gives every example a `Preview` / `Code` switch. The current demo frame has only a `Preview` label; source is no longer available beside each rendered variant.\n- Current demos add useful live status and more realistic audio flows, but they replace rather than supplement the variant matrix above.\n- Island API tables use `Attribute / Description / Type / Default`; current tables use `Prop / Type / Default / Description` and add a new inherited-props paragraph.\n- Dedicated Data Attributes/Data Tags sections were removed from most component pages. The current docs only surface a small subset (for example VU Meter `data-active` and Card `data-toggled`).\n- Full type-declaration blocks were removed in favor of generated API tables. Keep the tables if they are complete, but restore any public contract details that are no longer discoverable.\n- Hook pages gained live demos, lifecycle, and error guidance; preserve those improvements while matching the Island visual hierarchy and API discoverability.\n\nRelevant files:\n\n- `docs/app/_components/controller-demo.tsx`\n- `docs/app/_components/display-*.tsx`\n- `docs/app/_components/hook-demo.tsx`\n- `docs/app/_components/*-api.tsx`\n- `docs/app/_components/*-docs.module.css`\n- `docs/content/{en,zh}/component/*.mdx`\n- `docs/content/{en,zh}/hook/*.mdx`\n\n## Why the current regression check misses this\n\n`scripts/verify-docs-ui.mjs` compares the current site with hand-written style constants. It does not compare the output with an Island screenshot/DOM baseline. It verifies the shell mainly through the Button route and only requires each component route to contain at least one demo, so it cannot catch reduced example coverage, changed copy/hierarchy, missing links, or changed root behavior.\n\nThe two files under `docs/screenshots/` are unreferenced migration-preview captures, not Island parity baselines.\n\n## Acceptance criteria\n\n- [ ] Create and document an Island → Nextra parity matrix covering shell, navigation, content hierarchy, examples, API/data-attribute coverage, and intentional modernized exceptions.\n- [ ] Match the Island shell at 1440×900 and 390×844 in English/Chinese and light/dark themes, including the root-route behavior, sidebar grouping, callouts, link treatment, and page-level navigation affordances.\n- [ ] Restore the Island Links destinations, edit-page affordance, previous/next navigation, and footer behavior, or explicitly document an approved product decision for each deviation.\n- [ ] Fix the Declaration copy so it agrees with the actual edit-link behavior.\n- [ ] Give every Island component variant an equivalent live preview and adjacent copyable source, unless its removal is explicitly approved in the parity matrix.\n- [ ] Restore missing Data Attributes/Data Tags and public type/API details.\n- [ ] Preserve the current 1.1.x installation, Tone.js 15, accessibility, lifecycle, error-handling, and real-audio-demo improvements.\n- [ ] Replace the current style-constant-only check with maintained Island visual baselines (or an equivalent deterministic comparison) for representative guide, controller, visualization, Hook, and home routes.\n- [ ] Add content-inventory assertions for example labels/counts, Links destinations, edit/pagination controls, root behavior, and both locales.\n- [ ] `pnpm lint`, `pnpm typecheck:docs`, `pnpm build:docs`, and `pnpm test:docs` pass.\n\n## Out of scope\n\n- Reintroducing IslandJS, NextUI, or `react-live`\n- Reverting accurate Echo UI 1.1.x compatibility and API information\n- Removing accessibility or real Web Audio improvements solely to obtain pixel parity\n\n\n## Frozen implementation contract\n\n### Acceptance criteria\n\n1. Add a maintained Island → Nextra parity matrix that covers:\n   - root-route behavior;\n   - desktop and mobile shell/navigation;\n   - both locales and both color schemes;\n   - guide hierarchy and content exceptions;\n   - component example labels/counts;\n   - Preview/Code behavior;\n   - API, public type, and data-attribute coverage;\n   - every intentional modernized exception.\n2. Make `/` follow the Island language-routing behavior instead of presenting a\n   separate editorial language picker.\n3. Match the Island shell on the required representative routes at 1440×900 and\n   390×844 in English and Chinese, light and dark:\n   - preserve the Island header and mobile-menu hierarchy;\n   - restore the Links destinations (GitHub, Discord, Twitter);\n   - restore Guide/About sidebar grouping;\n   - restore edit-page, last-updated, previous/next, and visible footer behavior;\n   - use Island-like external-link and callout treatments.\n4. Reconcile Declaration copy with the restored edit-page affordance.\n5. Restore the Island guide hierarchy and essential content, including the\n   Introduction feature list rhythm and the About WeChat option/QR image, while\n   retaining accurate Echo UI 1.1.x installation and compatibility guidance.\n6. Give every component variant listed in the issue snapshot an equivalent live\n   preview and adjacent copyable source. A deliberately omitted variant must be\n   named and justified in the parity matrix.\n7. Preserve the richer real-audio, status, accessibility, lifecycle, and error\n   handling added by the Nextra migration; these supplement rather than replace\n   the Island variant matrix.\n8. Restore discoverable Data Attributes/Data Tags and public API/type details.\n   Generated tables may remain when complete, but their visible column order and\n   hierarchy must follow the Island contract where parity is expected.\n9. Replace the style-constant-only regression coverage with deterministic,\n   maintained Island visual baselines (or an equivalent deterministic screenshot\n   comparison) for home, guide, controller, visualization, and Hook categories.\n10. Add content-inventory assertions for both locales covering example\n    labels/counts, Links destinations, root behavior, edit/pagination/footer\n    controls, guide grouping, and representative API/data-attribute details.\n11. `pnpm lint`, `pnpm typecheck:docs`, `pnpm build:docs`, `pnpm test:docs`, and\n    the full `pnpm verify` pass.\n\n### In scope\n\n- `docs/app/**`, `docs/content/{en,zh}/**`, and documentation-only styles/assets.\n- Shared documentation demo/source/API components.\n- Documentation route, content-inventory, and visual-parity verification scripts\n  and tests.\n- Documentation of the parity matrix and intentionally retained modern behavior.\n- Test fixtures/baselines that are deterministic and checked into the repository.\n\n### Out of scope\n\n- Reintroducing IslandJS, NextUI, or `react-live`.\n- Reverting React 19, Tailwind CSS 4, Tone.js 15, accessibility, lifecycle,\n  error-handling, or real Web Audio improvements.\n- Changing the shipped Echo UI component/hook runtime or public package API solely\n  to make the documentation resemble the legacy site.\n- New production dependencies, release/version changes, or unrelated refactors.\n\n### Pre-agreed TDD seams\n\n1. First make content-inventory tests fail for root behavior, navigation links,\n   Guide/About grouping, footer/edit/pagination controls, both locales, variant\n   labels/counts, source affordances, and representative data attributes/API rows.\n2. Add or revise deterministic visual-parity assertions so they fail against the\n   current Nextra shell before changing shell styles or structure.\n3. Implement the smallest shared demo/source model that can express all required\n   variants, adding targeted tests for each controller/display category before\n   populating page content.\n4. Keep modern audio-demo behavior covered while extending Preview/Code; source\n   disclosure and copy controls must be keyboard-accessible.\n5. Run the closest targeted Vitest/Node check after each seam and\n   `pnpm typecheck:docs` regularly.\n\n### Required targeted checks\n\n- Targeted Vitest tests for docs route/content inventory.\n- Targeted Node checks for Nextra output and visual-parity baselines.\n- `pnpm lint`\n- `pnpm typecheck:docs`\n- `pnpm build:docs`\n- `pnpm test:docs`\n- `pnpm verify` as the final implementation check.\n\n### Required UI evidence\n\nStore before/after evidence under\n`screen-shots/20260724T132107Z-issue-108-743034/` with an index that maps each\ncapture to its route, locale, theme, viewport, and acceptance criterion.\n\n- Viewports: 1440×900 and 390×844.\n- Locales/themes: English and Chinese, light and dark.\n- Routes: home, `/guide/introduction`, `/guide/about`, `/component/button`,\n  `/component/knob`, `/component/spectrogram`, and `/hook/usePlayer`.\n- Interaction evidence: desktop Links menu, mobile navigation, locale/theme\n  switching, previous/next navigation, edit link, Preview/Code switching, source\n  copy action, and at least one real-audio demo state.\n- Include focused before/after comparisons for representative home, guide,\n  controller, visualization, and Hook pages. The evidence index may use a\n  documented representative matrix instead of duplicating every unchanged\n  combination, but all locale/theme/viewport combinations must be exercised by a\n  deterministic check.\n- Record keyboard/focus and reduced-motion observations for new interactive UI.\n\n### Risks and owner-confirmation boundaries\n\n- The owner has explicitly approved the issue's >400-line implementation budget.\n- Stop for owner confirmation before adding a dependency, changing a shipped\n  package API/runtime, changing release metadata, weakening accessibility or\n  security behavior, or approving an intentional parity exception not already\n  stated above.\n- Treat the live Island site as the visual/content reference and the current\n  package implementation/types as the source of truth for modern API facts.\n- Prefer shared data-driven documentation structures over duplicating large\n  locale-specific React implementations.\n\n### Stop conditions\n\n- A requirement conflicts with the current public runtime/API and cannot be\n  resolved as documentation-only work.\n- A required Island reference/baseline cannot be captured deterministically.\n- An in-scope check fails twice for causes outside the issue's changes.\n- Work would require a new dependency, release change, security-sensitive change,\n  or product/API decision.\n- The implementation is complete and committed.\n\nStop after committing. Do not push, create a PR, or merge.\n","events":[{"schemaVersion":1,"runId":"20260724T132107Z-issue-108-743034","type":"loop_started","timestamp":"2026-07-24T13:21:07.375Z","status":"running","payload":{"issueNumber":108,"branch":"codex/issue-108"}}],"artifacts":[],"updatedAt":"2026-07-24T13:21:07.375Z"}

[Ethandasw]

{"schemaVersion":1,"kind":"active-checkpoint","run":{"schemaVersion":1,"runId":"20260724T132107Z-issue-108-743034","issueNumber":108,"issueTitle":"docs: close the remaining Island UI and content parity gaps in Nextra","issueUrl":"https://github.com/codeacme17/echo-ui/issues/108","baseBranch":"dev","baseSha":"9eea05360a90e46a4c66c2e821e9ad5bd6c71c67","branch":"codex/issue-108","status":"running","startedAt":"2026-07-24T13:21:07.375Z","finishedAt":null,"prUrl":null,"headSha":null,"mergeSha":null,"issueSnapshot":{"title":"docs: close the remaining Island UI and content parity gaps in Nextra","body":"## Context\n\nThis is a follow-up to #97 / #98. That work required the Nextra documentation to reproduce the established Island site exactly, with `https://echoui.dev/en/` as the visual source of truth. A fresh comparison against the current `dev` branch shows that the shell is closer, but substantial UI, information-architecture, and example-coverage differences remain.\n\nKeep Nextra. “Parity” here means preserving the Island presentation and documentation coverage while retaining factual improvements made for Echo UI 1.1.x (React 19, Tailwind CSS 4, Tone.js 15, accessibility, lifecycle, and error guidance). It does **not** mean restoring IslandJS, NextUI, stale setup instructions, or old implementation dependencies.\n\n## How to compare\n\n1. Run `pnpm dev:docs`.\n2. Compare the same English and Chinese routes against `https://echoui.dev/en/` and `https://echoui.dev/zh/`.\n3. At minimum, inspect `/`, `/guide/introduction`, `/guide/about`, `/component/button`, `/component/knob`, `/component/spectrogram`, and `/hook/usePlayer`.\n4. Compare 1440×900 and 390×844 in both light and dark themes.\n\n## Observed differences\n\n### 1. Site shell and navigation\n\n| Area | Island reference | Current Nextra site |\n| --- | --- | --- |\n| `/` | Redirects directly to `/en` | Shows a separate editorial “Choose your documentation language” landing page |\n| Links menu | GitHub, Discord, Twitter | Discussions, Issues, Discord |\n| Guide sidebar | Shows a `Guide` group heading and a separated `About` group | Renders a flat four-link list |\n| Contribution/navigation affordances | Exposes “Edit this page on GitHub”, last-updated metadata, and previous/next page navigation | `editLink={null}` and `navigation={false}`; only the timestamp remains |\n| Footer | Island configuration contains license/copyright and page navigation metadata | The Nextra footer is mounted but globally hidden |\n| External links | Plain Island link treatment | Nextra adds external-link arrow glyphs throughout prose |\n| Callouts | Neutral Island bordered panel | Blue Nextra info callout with icon and different spacing/color |\n\nThere is also a content/implementation contradiction: the Declaration page says readers can use “the edit link on each page”, while the layout explicitly disables edit links.\n\nRelevant files:\n\n- `docs/app/[lang]/layout.tsx`\n- `docs/app/[lang]/island-theme.css`\n- `docs/app/(landing)/page.tsx`\n- `docs/content/en/_meta.ts`\n- `docs/content/zh/_meta.ts`\n- `docs/content/*/guide/declaration.mdx`\n\n### 2. Guide content and hierarchy\n\n- Introduction feature bullets became five H3 sections. This materially changes page length, scan rhythm, and the table of contents.\n- All guide copy was rewritten rather than migrated in place. Some updates are useful and should remain, but the result is not content parity with the Island reference.\n- About removed the WeChat community option and QR code even though `wechat.jpg` is still shipped as a public asset.\n- Installation is correctly modernized for 1.1.x, but its presentation no longer follows the four-step Island structure.\n- The root language-selection page introduces a visual language that does not exist anywhere in the Island site.\n\n### 3. Component example coverage was reduced\n\nThe Island source had 30 files under `docs/src/components/UsageBox` and `docs/src/components/Example`. The current site consolidates the documentation into a small set of shared demo files and generally renders one demo per component page.\n\n| Component | Island examples no longer shown as equivalent live variants |\n| --- | --- |\n| Button | default, toggled, disabled, sizes, radii, group |\n| Checkbox | default, disabled, sizes, colors, group |\n| Envelope | ADSR, AHDSR, DADSR/delay |\n| Input | default, disabled, bilateral, text, sizes, radii, progress color, min/max, step/sensitivity |\n| Knob | default, disabled, bilateral, rotation range, labels, step/sensitivity, sizes, colors, group |\n| Radio | default, disabled, sizes, colors, group |\n| Slider | default, disabled, vertical, bilateral, axis, step, custom styling, uncontrolled |\n| Switch | default, toggled, disabled, sizes, custom styling |\n| LFO | default and delay |\n| Light | default, on, colors, sizes |\n| Spectrogram | default, axis, grid, EQ3 scenario |\n| VU Meter | default, horizontal, stereo, compact, segment count, custom colors |\n| Card | default, active, real-world scenario |\n\nOscilloscope and Waveform still have a live example, but they also lost the Island example affordance described below.\n\n### 4. The example and API presentation is different\n\n- Island gives every example a `Preview` / `Code` switch. The current demo frame has only a `Preview` label; source is no longer available beside each rendered variant.\n- Current demos add useful live status and more realistic audio flows, but they replace rather than supplement the variant matrix above.\n- Island API tables use `Attribute / Description / Type / Default`; current tables use `Prop / Type / Default / Description` and add a new inherited-props paragraph.\n- Dedicated Data Attributes/Data Tags sections were removed from most component pages. The current docs only surface a small subset (for example VU Meter `data-active` and Card `data-toggled`).\n- Full type-declaration blocks were removed in favor of generated API tables. Keep the tables if they are complete, but restore any public contract details that are no longer discoverable.\n- Hook pages gained live demos, lifecycle, and error guidance; preserve those improvements while matching the Island visual hierarchy and API discoverability.\n\nRelevant files:\n\n- `docs/app/_components/controller-demo.tsx`\n- `docs/app/_components/display-*.tsx`\n- `docs/app/_components/hook-demo.tsx`\n- `docs/app/_components/*-api.tsx`\n- `docs/app/_components/*-docs.module.css`\n- `docs/content/{en,zh}/component/*.mdx`\n- `docs/content/{en,zh}/hook/*.mdx`\n\n## Why the current regression check misses this\n\n`scripts/verify-docs-ui.mjs` compares the current site with hand-written style constants. It does not compare the output with an Island screenshot/DOM baseline. It verifies the shell mainly through the Button route and only requires each component route to contain at least one demo, so it cannot catch reduced example coverage, changed copy/hierarchy, missing links, or changed root behavior.\n\nThe two files under `docs/screenshots/` are unreferenced migration-preview captures, not Island parity baselines.\n\n## Acceptance criteria\n\n- [ ] Create and document an Island → Nextra parity matrix covering shell, navigation, content hierarchy, examples, API/data-attribute coverage, and intentional modernized exceptions.\n- [ ] Match the Island shell at 1440×900 and 390×844 in English/Chinese and light/dark themes, including the root-route behavior, sidebar grouping, callouts, link treatment, and page-level navigation affordances.\n- [ ] Restore the Island Links destinations, edit-page affordance, previous/next navigation, and footer behavior, or explicitly document an approved product decision for each deviation.\n- [ ] Fix the Declaration copy so it agrees with the actual edit-link behavior.\n- [ ] Give every Island component variant an equivalent live preview and adjacent copyable source, unless its removal is explicitly approved in the parity matrix.\n- [ ] Restore missing Data Attributes/Data Tags and public type/API details.\n- [ ] Preserve the current 1.1.x installation, Tone.js 15, accessibility, lifecycle, error-handling, and real-audio-demo improvements.\n- [ ] Replace the current style-constant-only check with maintained Island visual baselines (or an equivalent deterministic comparison) for representative guide, controller, visualization, Hook, and home routes.\n- [ ] Add content-inventory assertions for example labels/counts, Links destinations, edit/pagination controls, root behavior, and both locales.\n- [ ] `pnpm lint`, `pnpm typecheck:docs`, `pnpm build:docs`, and `pnpm test:docs` pass.\n\n## Out of scope\n\n- Reintroducing IslandJS, NextUI, or `react-live`\n- Reverting accurate Echo UI 1.1.x compatibility and API information\n- Removing accessibility or real Web Audio improvements solely to obtain pixel parity\n","labels":["codex-ready"],"url":"https://github.com/codeacme17/echo-ui/issues/108","capturedAt":"2026-07-24T13:21:07.375Z"},"briefDigest":"3cfea23d657797a80267c52400c3844b534417a8ecdf26620174af40dbaf0ed6","uiEvidenceRequired":true,"implementationCommit":null},"briefSource":"# Implementation brief\n\n- Run ID: `20260724T132107Z-issue-108-743034`\n- Issue: #108 — docs: close the remaining Island UI and content parity gaps in Nextra\n- Issue URL: https://github.com/codeacme17/echo-ui/issues/108\n- Base branch: `dev`\n- Base SHA: `9eea05360a90e46a4c66c2e821e9ad5bd6c71c67`\n- Branch: `codex/issue-108`\n- UI evidence required: yes\n\n## Issue snapshot\n\n## Context\n\nThis is a follow-up to #97 / #98. That work required the Nextra documentation to reproduce the established Island site exactly, with `https://echoui.dev/en/` as the visual source of truth. A fresh comparison against the current `dev` branch shows that the shell is closer, but substantial UI, information-architecture, and example-coverage differences remain.\n\nKeep Nextra. “Parity” here means preserving the Island presentation and documentation coverage while retaining factual improvements made for Echo UI 1.1.x (React 19, Tailwind CSS 4, Tone.js 15, accessibility, lifecycle, and error guidance). It does **not** mean restoring IslandJS, NextUI, stale setup instructions, or old implementation dependencies.\n\n## How to compare\n\n1. Run `pnpm dev:docs`.\n2. Compare the same English and Chinese routes against `https://echoui.dev/en/` and `https://echoui.dev/zh/`.\n3. At minimum, inspect `/`, `/guide/introduction`, `/guide/about`, `/component/button`, `/component/knob`, `/component/spectrogram`, and `/hook/usePlayer`.\n4. Compare 1440×900 and 390×844 in both light and dark themes.\n\n## Observed differences\n\n### 1. Site shell and navigation\n\n| Area | Island reference | Current Nextra site |\n| --- | --- | --- |\n| `/` | Redirects directly to `/en` | Shows a separate editorial “Choose your documentation language” landing page |\n| Links menu | GitHub, Discord, Twitter | Discussions, Issues, Discord |\n| Guide sidebar | Shows a `Guide` group heading and a separated `About` group | Renders a flat four-link list |\n| Contribution/navigation affordances | Exposes “Edit this page on GitHub”, last-updated metadata, and previous/next page navigation | `editLink={null}` and `navigation={false}`; only the timestamp remains |\n| Footer | Island configuration contains license/copyright and page navigation metadata | The Nextra footer is mounted but globally hidden |\n| External links | Plain Island link treatment | Nextra adds external-link arrow glyphs throughout prose |\n| Callouts | Neutral Island bordered panel | Blue Nextra info callout with icon and different spacing/color |\n\nThere is also a content/implementation contradiction: the Declaration page says readers can use “the edit link on each page”, while the layout explicitly disables edit links.\n\nRelevant files:\n\n- `docs/app/[lang]/layout.tsx`\n- `docs/app/[lang]/island-theme.css`\n- `docs/app/(landing)/page.tsx`\n- `docs/content/en/_meta.ts`\n- `docs/content/zh/_meta.ts`\n- `docs/content/*/guide/declaration.mdx`\n\n### 2. Guide content and hierarchy\n\n- Introduction feature bullets became five H3 sections. This materially changes page length, scan rhythm, and the table of contents.\n- All guide copy was rewritten rather than migrated in place. Some updates are useful and should remain, but the result is not content parity with the Island reference.\n- About removed the WeChat community option and QR code even though `wechat.jpg` is still shipped as a public asset.\n- Installation is correctly modernized for 1.1.x, but its presentation no longer follows the four-step Island structure.\n- The root language-selection page introduces a visual language that does not exist anywhere in the Island site.\n\n### 3. Component example coverage was reduced\n\nThe Island source had 30 files under `docs/src/components/UsageBox` and `docs/src/components/Example`. The current site consolidates the documentation into a small set of shared demo files and generally renders one demo per component page.\n\n| Component | Island examples no longer shown as equivalent live variants |\n| --- | --- |\n| Button | default, toggled, disabled, sizes, radii, group |\n| Checkbox | default, disabled, sizes, colors, group |\n| Envelope | ADSR, AHDSR, DADSR/delay |\n| Input | default, disabled, bilateral, text, sizes, radii, progress color, min/max, step/sensitivity |\n| Knob | default, disabled, bilateral, rotation range, labels, step/sensitivity, sizes, colors, group |\n| Radio | default, disabled, sizes, colors, group |\n| Slider | default, disabled, vertical, bilateral, axis, step, custom styling, uncontrolled |\n| Switch | default, toggled, disabled, sizes, custom styling |\n| LFO | default and delay |\n| Light | default, on, colors, sizes |\n| Spectrogram | default, axis, grid, EQ3 scenario |\n| VU Meter | default, horizontal, stereo, compact, segment count, custom colors |\n| Card | default, active, real-world scenario |\n\nOscilloscope and Waveform still have a live example, but they also lost the Island example affordance described below.\n\n### 4. The example and API presentation is different\n\n- Island gives every example a `Preview` / `Code` switch. The current demo frame has only a `Preview` label; source is no longer available beside each rendered variant.\n- Current demos add useful live status and more realistic audio flows, but they replace rather than supplement the variant matrix above.\n- Island API tables use `Attribute / Description / Type / Default`; current tables use `Prop / Type / Default / Description` and add a new inherited-props paragraph.\n- Dedicated Data Attributes/Data Tags sections were removed from most component pages. The current docs only surface a small subset (for example VU Meter `data-active` and Card `data-toggled`).\n- Full type-declaration blocks were removed in favor of generated API tables. Keep the tables if they are complete, but restore any public contract details that are no longer discoverable.\n- Hook pages gained live demos, lifecycle, and error guidance; preserve those improvements while matching the Island visual hierarchy and API discoverability.\n\nRelevant files:\n\n- `docs/app/_components/controller-demo.tsx`\n- `docs/app/_components/display-*.tsx`\n- `docs/app/_components/hook-demo.tsx`\n- `docs/app/_components/*-api.tsx`\n- `docs/app/_components/*-docs.module.css`\n- `docs/content/{en,zh}/component/*.mdx`\n- `docs/content/{en,zh}/hook/*.mdx`\n\n## Why the current regression check misses this\n\n`scripts/verify-docs-ui.mjs` compares the current site with hand-written style constants. It does not compare the output with an Island screenshot/DOM baseline. It verifies the shell mainly through the Button route and only requires each component route to contain at least one demo, so it cannot catch reduced example coverage, changed copy/hierarchy, missing links, or changed root behavior.\n\nThe two files under `docs/screenshots/` are unreferenced migration-preview captures, not Island parity baselines.\n\n## Acceptance criteria\n\n- [ ] Create and document an Island → Nextra parity matrix covering shell, navigation, content hierarchy, examples, API/data-attribute coverage, and intentional modernized exceptions.\n- [ ] Match the Island shell at 1440×900 and 390×844 in English/Chinese and light/dark themes, including the root-route behavior, sidebar grouping, callouts, link treatment, and page-level navigation affordances.\n- [ ] Restore the Island Links destinations, edit-page affordance, previous/next navigation, and footer behavior, or explicitly document an approved product decision for each deviation.\n- [ ] Fix the Declaration copy so it agrees with the actual edit-link behavior.\n- [ ] Give every Island component variant an equivalent live preview and adjacent copyable source, unless its removal is explicitly approved in the parity matrix.\n- [ ] Restore missing Data Attributes/Data Tags and public type/API details.\n- [ ] Preserve the current 1.1.x installation, Tone.js 15, accessibility, lifecycle, error-handling, and real-audio-demo improvements.\n- [ ] Replace the current style-constant-only check with maintained Island visual baselines (or an equivalent deterministic comparison) for representative guide, controller, visualization, Hook, and home routes.\n- [ ] Add content-inventory assertions for example labels/counts, Links destinations, edit/pagination controls, root behavior, and both locales.\n- [ ] `pnpm lint`, `pnpm typecheck:docs`, `pnpm build:docs`, and `pnpm test:docs` pass.\n\n## Out of scope\n\n- Reintroducing IslandJS, NextUI, or `react-live`\n- Reverting accurate Echo UI 1.1.x compatibility and API information\n- Removing accessibility or real Web Audio improvements solely to obtain pixel parity\n\n\n## Frozen implementation contract\n\n### Acceptance criteria\n\n1. Add a maintained Island → Nextra parity matrix that covers:\n   - root-route behavior;\n   - desktop and mobile shell/navigation;\n   - both locales and both color schemes;\n   - guide hierarchy and content exceptions;\n   - component example labels/counts;\n   - Preview/Code behavior;\n   - API, public type, and data-attribute coverage;\n   - every intentional modernized exception.\n2. Make `/` follow the Island language-routing behavior instead of presenting a\n   separate editorial language picker.\n3. Match the Island shell on the required representative routes at 1440×900 and\n   390×844 in English and Chinese, light and dark:\n   - preserve the Island header and mobile-menu hierarchy;\n   - restore the Links destinations (GitHub, Discord, Twitter);\n   - restore Guide/About sidebar grouping;\n   - restore edit-page, last-updated, previous/next, and visible footer behavior;\n   - use Island-like external-link and callout treatments.\n4. Reconcile Declaration copy with the restored edit-page affordance.\n5. Restore the Island guide hierarchy and essential content, including the\n   Introduction feature list rhythm and the About WeChat option/QR image, while\n   retaining accurate Echo UI 1.1.x installation and compatibility guidance.\n6. Give every component variant listed in the issue snapshot an equivalent live\n   preview and adjacent copyable source. A deliberately omitted variant must be\n   named and justified in the parity matrix.\n7. Preserve the richer real-audio, status, accessibility, lifecycle, and error\n   handling added by the Nextra migration; these supplement rather than replace\n   the Island variant matrix.\n8. Restore discoverable Data Attributes/Data Tags and public API/type details.\n   Generated tables may remain when complete, but their visible column order and\n   hierarchy must follow the Island contract where parity is expected.\n9. Replace the style-constant-only regression coverage with deterministic,\n   maintained Island visual baselines (or an equivalent deterministic screenshot\n   comparison) for home, guide, controller, visualization, and Hook categories.\n10. Add content-inventory assertions for both locales covering example\n    labels/counts, Links destinations, root behavior, edit/pagination/footer\n    controls, guide grouping, and representative API/data-attribute details.\n11. `pnpm lint`, `pnpm typecheck:docs`, `pnpm build:docs`, `pnpm test:docs`, and\n    the full `pnpm verify` pass.\n\n### In scope\n\n- `docs/app/**`, `docs/content/{en,zh}/**`, and documentation-only styles/assets.\n- Shared documentation demo/source/API components.\n- Documentation route, content-inventory, and visual-parity verification scripts\n  and tests.\n- Documentation of the parity matrix and intentionally retained modern behavior.\n- Test fixtures/baselines that are deterministic and checked into the repository.\n\n### Out of scope\n\n- Reintroducing IslandJS, NextUI, or `react-live`.\n- Reverting React 19, Tailwind CSS 4, Tone.js 15, accessibility, lifecycle,\n  error-handling, or real Web Audio improvements.\n- Changing the shipped Echo UI component/hook runtime or public package API solely\n  to make the documentation resemble the legacy site.\n- New production dependencies, release/version changes, or unrelated refactors.\n\n### Pre-agreed TDD seams\n\n1. First make content-inventory tests fail for root behavior, navigation links,\n   Guide/About grouping, footer/edit/pagination controls, both locales, variant\n   labels/counts, source affordances, and representative data attributes/API rows.\n2. Add or revise deterministic visual-parity assertions so they fail against the\n   current Nextra shell before changing shell styles or structure.\n3. Implement the smallest shared demo/source model that can express all required\n   variants, adding targeted tests for each controller/display category before\n   populating page content.\n4. Keep modern audio-demo behavior covered while extending Preview/Code; source\n   disclosure and copy controls must be keyboard-accessible.\n5. Run the closest targeted Vitest/Node check after each seam and\n   `pnpm typecheck:docs` regularly.\n\n### Required targeted checks\n\n- Targeted Vitest tests for docs route/content inventory.\n- Targeted Node checks for Nextra output and visual-parity baselines.\n- `pnpm lint`\n- `pnpm typecheck:docs`\n- `pnpm build:docs`\n- `pnpm test:docs`\n- `pnpm verify` as the final implementation check.\n\n### Required UI evidence\n\nStore before/after evidence under\n`screen-shots/20260724T132107Z-issue-108-743034/` with an index that maps each\ncapture to its route, locale, theme, viewport, and acceptance criterion.\n\n- Viewports: 1440×900 and 390×844.\n- Locales/themes: English and Chinese, light and dark.\n- Routes: home, `/guide/introduction`, `/guide/about`, `/component/button`,\n  `/component/knob`, `/component/spectrogram`, and `/hook/usePlayer`.\n- Interaction evidence: desktop Links menu, mobile navigation, locale/theme\n  switching, previous/next navigation, edit link, Preview/Code switching, source\n  copy action, and at least one real-audio demo state.\n- Include focused before/after comparisons for representative home, guide,\n  controller, visualization, and Hook pages. The evidence index may use a\n  documented representative matrix instead of duplicating every unchanged\n  combination, but all locale/theme/viewport combinations must be exercised by a\n  deterministic check.\n- Record keyboard/focus and reduced-motion observations for new interactive UI.\n\n### Risks and owner-confirmation boundaries\n\n- The owner has explicitly approved the issue's >400-line implementation budget.\n- Stop for owner confirmation before adding a dependency, changing a shipped\n  package API/runtime, changing release metadata, weakening accessibility or\n  security behavior, or approving an intentional parity exception not already\n  stated above.\n- Treat the live Island site as the visual/content reference and the current\n  package implementation/types as the source of truth for modern API facts.\n- Prefer shared data-driven documentation structures over duplicating large\n  locale-specific React implementations.\n\n### Stop conditions\n\n- A requirement conflicts with the current public runtime/API and cannot be\n  resolved as documentation-only work.\n- A required Island reference/baseline cannot be captured deterministically.\n- An in-scope check fails twice for causes outside the issue's changes.\n- Work would require a new dependency, release change, security-sensitive change,\n  or product/API decision.\n- The implementation is complete and committed.\n\nStop after committing. Do not push, create a PR, or merge.\n","events":[{"schemaVersion":1,"runId":"20260724T132107Z-issue-108-743034","type":"loop_started","timestamp":"2026-07-24T13:21:07.375Z","status":"running","payload":{"issueNumber":108,"branch":"codex/issue-108"}},{"schemaVersion":1,"runId":"20260724T132107Z-issue-108-743034","type":"brief_frozen","timestamp":"2026-07-24T13:28:52.219Z","status":"frozen","payload":{"briefDigest":"3cfea23d657797a80267c52400c3844b534417a8ecdf26620174af40dbaf0ed6","uiEvidenceRequired":true}}],"artifacts":[],"updatedAt":"2026-07-24T13:28:52.219Z"}

[Ethandasw]

{"schemaVersion":1,"kind":"active-checkpoint","run":{"schemaVersion":1,"runId":"20260724T132107Z-issue-108-743034","issueNumber":108,"issueTitle":"docs: close the remaining Island UI and content parity gaps in Nextra","issueUrl":"https://github.com/codeacme17/echo-ui/issues/108","baseBranch":"dev","baseSha":"9eea05360a90e46a4c66c2e821e9ad5bd6c71c67","branch":"codex/issue-108","status":"running","startedAt":"2026-07-24T13:21:07.375Z","finishedAt":null,"prUrl":null,"headSha":null,"mergeSha":null,"issueSnapshot":{"title":"docs: close the remaining Island UI and content parity gaps in Nextra","body":"## Context\n\nThis is a follow-up to #97 / #98. That work required the Nextra documentation to reproduce the established Island site exactly, with `https://echoui.dev/en/` as the visual source of truth. A fresh comparison against the current `dev` branch shows that the shell is closer, but substantial UI, information-architecture, and example-coverage differences remain.\n\nKeep Nextra. “Parity” here means preserving the Island presentation and documentation coverage while retaining factual improvements made for Echo UI 1.1.x (React 19, Tailwind CSS 4, Tone.js 15, accessibility, lifecycle, and error guidance). It does **not** mean restoring IslandJS, NextUI, stale setup instructions, or old implementation dependencies.\n\n## How to compare\n\n1. Run `pnpm dev:docs`.\n2. Compare the same English and Chinese routes against `https://echoui.dev/en/` and `https://echoui.dev/zh/`.\n3. At minimum, inspect `/`, `/guide/introduction`, `/guide/about`, `/component/button`, `/component/knob`, `/component/spectrogram`, and `/hook/usePlayer`.\n4. Compare 1440×900 and 390×844 in both light and dark themes.\n\n## Observed differences\n\n### 1. Site shell and navigation\n\n| Area | Island reference | Current Nextra site |\n| --- | --- | --- |\n| `/` | Redirects directly to `/en` | Shows a separate editorial “Choose your documentation language” landing page |\n| Links menu | GitHub, Discord, Twitter | Discussions, Issues, Discord |\n| Guide sidebar | Shows a `Guide` group heading and a separated `About` group | Renders a flat four-link list |\n| Contribution/navigation affordances | Exposes “Edit this page on GitHub”, last-updated metadata, and previous/next page navigation | `editLink={null}` and `navigation={false}`; only the timestamp remains |\n| Footer | Island configuration contains license/copyright and page navigation metadata | The Nextra footer is mounted but globally hidden |\n| External links | Plain Island link treatment | Nextra adds external-link arrow glyphs throughout prose |\n| Callouts | Neutral Island bordered panel | Blue Nextra info callout with icon and different spacing/color |\n\nThere is also a content/implementation contradiction: the Declaration page says readers can use “the edit link on each page”, while the layout explicitly disables edit links.\n\nRelevant files:\n\n- `docs/app/[lang]/layout.tsx`\n- `docs/app/[lang]/island-theme.css`\n- `docs/app/(landing)/page.tsx`\n- `docs/content/en/_meta.ts`\n- `docs/content/zh/_meta.ts`\n- `docs/content/*/guide/declaration.mdx`\n\n### 2. Guide content and hierarchy\n\n- Introduction feature bullets became five H3 sections. This materially changes page length, scan rhythm, and the table of contents.\n- All guide copy was rewritten rather than migrated in place. Some updates are useful and should remain, but the result is not content parity with the Island reference.\n- About removed the WeChat community option and QR code even though `wechat.jpg` is still shipped as a public asset.\n- Installation is correctly modernized for 1.1.x, but its presentation no longer follows the four-step Island structure.\n- The root language-selection page introduces a visual language that does not exist anywhere in the Island site.\n\n### 3. Component example coverage was reduced\n\nThe Island source had 30 files under `docs/src/components/UsageBox` and `docs/src/components/Example`. The current site consolidates the documentation into a small set of shared demo files and generally renders one demo per component page.\n\n| Component | Island examples no longer shown as equivalent live variants |\n| --- | --- |\n| Button | default, toggled, disabled, sizes, radii, group |\n| Checkbox | default, disabled, sizes, colors, group |\n| Envelope | ADSR, AHDSR, DADSR/delay |\n| Input | default, disabled, bilateral, text, sizes, radii, progress color, min/max, step/sensitivity |\n| Knob | default, disabled, bilateral, rotation range, labels, step/sensitivity, sizes, colors, group |\n| Radio | default, disabled, sizes, colors, group |\n| Slider | default, disabled, vertical, bilateral, axis, step, custom styling, uncontrolled |\n| Switch | default, toggled, disabled, sizes, custom styling |\n| LFO | default and delay |\n| Light | default, on, colors, sizes |\n| Spectrogram | default, axis, grid, EQ3 scenario |\n| VU Meter | default, horizontal, stereo, compact, segment count, custom colors |\n| Card | default, active, real-world scenario |\n\nOscilloscope and Waveform still have a live example, but they also lost the Island example affordance described below.\n\n### 4. The example and API presentation is different\n\n- Island gives every example a `Preview` / `Code` switch. The current demo frame has only a `Preview` label; source is no longer available beside each rendered variant.\n- Current demos add useful live status and more realistic audio flows, but they replace rather than supplement the variant matrix above.\n- Island API tables use `Attribute / Description / Type / Default`; current tables use `Prop / Type / Default / Description` and add a new inherited-props paragraph.\n- Dedicated Data Attributes/Data Tags sections were removed from most component pages. The current docs only surface a small subset (for example VU Meter `data-active` and Card `data-toggled`).\n- Full type-declaration blocks were removed in favor of generated API tables. Keep the tables if they are complete, but restore any public contract details that are no longer discoverable.\n- Hook pages gained live demos, lifecycle, and error guidance; preserve those improvements while matching the Island visual hierarchy and API discoverability.\n\nRelevant files:\n\n- `docs/app/_components/controller-demo.tsx`\n- `docs/app/_components/display-*.tsx`\n- `docs/app/_components/hook-demo.tsx`\n- `docs/app/_components/*-api.tsx`\n- `docs/app/_components/*-docs.module.css`\n- `docs/content/{en,zh}/component/*.mdx`\n- `docs/content/{en,zh}/hook/*.mdx`\n\n## Why the current regression check misses this\n\n`scripts/verify-docs-ui.mjs` compares the current site with hand-written style constants. It does not compare the output with an Island screenshot/DOM baseline. It verifies the shell mainly through the Button route and only requires each component route to contain at least one demo, so it cannot catch reduced example coverage, changed copy/hierarchy, missing links, or changed root behavior.\n\nThe two files under `docs/screenshots/` are unreferenced migration-preview captures, not Island parity baselines.\n\n## Acceptance criteria\n\n- [ ] Create and document an Island → Nextra parity matrix covering shell, navigation, content hierarchy, examples, API/data-attribute coverage, and intentional modernized exceptions.\n- [ ] Match the Island shell at 1440×900 and 390×844 in English/Chinese and light/dark themes, including the root-route behavior, sidebar grouping, callouts, link treatment, and page-level navigation affordances.\n- [ ] Restore the Island Links destinations, edit-page affordance, previous/next navigation, and footer behavior, or explicitly document an approved product decision for each deviation.\n- [ ] Fix the Declaration copy so it agrees with the actual edit-link behavior.\n- [ ] Give every Island component variant an equivalent live preview and adjacent copyable source, unless its removal is explicitly approved in the parity matrix.\n- [ ] Restore missing Data Attributes/Data Tags and public type/API details.\n- [ ] Preserve the current 1.1.x installation, Tone.js 15, accessibility, lifecycle, error-handling, and real-audio-demo improvements.\n- [ ] Replace the current style-constant-only check with maintained Island visual baselines (or an equivalent deterministic comparison) for representative guide, controller, visualization, Hook, and home routes.\n- [ ] Add content-inventory assertions for example labels/counts, Links destinations, edit/pagination controls, root behavior, and both locales.\n- [ ] `pnpm lint`, `pnpm typecheck:docs`, `pnpm build:docs`, and `pnpm test:docs` pass.\n\n## Out of scope\n\n- Reintroducing IslandJS, NextUI, or `react-live`\n- Reverting accurate Echo UI 1.1.x compatibility and API information\n- Removing accessibility or real Web Audio improvements solely to obtain pixel parity\n","labels":["codex-ready"],"url":"https://github.com/codeacme17/echo-ui/issues/108","capturedAt":"2026-07-24T13:21:07.375Z"},"briefDigest":"3cfea23d657797a80267c52400c3844b534417a8ecdf26620174af40dbaf0ed6","uiEvidenceRequired":true,"implementationCommit":"b15cded4fb9fa319bb35e56a70a4401cbf1d0e33"},"briefSource":"# Implementation brief\n\n- Run ID: `20260724T132107Z-issue-108-743034`\n- Issue: #108 — docs: close the remaining Island UI and content parity gaps in Nextra\n- Issue URL: https://github.com/codeacme17/echo-ui/issues/108\n- Base branch: `dev`\n- Base SHA: `9eea05360a90e46a4c66c2e821e9ad5bd6c71c67`\n- Branch: `codex/issue-108`\n- UI evidence required: yes\n\n## Issue snapshot\n\n## Context\n\nThis is a follow-up to #97 / #98. That work required the Nextra documentation to reproduce the established Island site exactly, with `https://echoui.dev/en/` as the visual source of truth. A fresh comparison against the current `dev` branch shows that the shell is closer, but substantial UI, information-architecture, and example-coverage differences remain.\n\nKeep Nextra. “Parity” here means preserving the Island presentation and documentation coverage while retaining factual improvements made for Echo UI 1.1.x (React 19, Tailwind CSS 4, Tone.js 15, accessibility, lifecycle, and error guidance). It does **not** mean restoring IslandJS, NextUI, stale setup instructions, or old implementation dependencies.\n\n## How to compare\n\n1. Run `pnpm dev:docs`.\n2. Compare the same English and Chinese routes against `https://echoui.dev/en/` and `https://echoui.dev/zh/`.\n3. At minimum, inspect `/`, `/guide/introduction`, `/guide/about`, `/component/button`, `/component/knob`, `/component/spectrogram`, and `/hook/usePlayer`.\n4. Compare 1440×900 and 390×844 in both light and dark themes.\n\n## Observed differences\n\n### 1. Site shell and navigation\n\n| Area | Island reference | Current Nextra site |\n| --- | --- | --- |\n| `/` | Redirects directly to `/en` | Shows a separate editorial “Choose your documentation language” landing page |\n| Links menu | GitHub, Discord, Twitter | Discussions, Issues, Discord |\n| Guide sidebar | Shows a `Guide` group heading and a separated `About` group | Renders a flat four-link list |\n| Contribution/navigation affordances | Exposes “Edit this page on GitHub”, last-updated metadata, and previous/next page navigation | `editLink={null}` and `navigation={false}`; only the timestamp remains |\n| Footer | Island configuration contains license/copyright and page navigation metadata | The Nextra footer is mounted but globally hidden |\n| External links | Plain Island link treatment | Nextra adds external-link arrow glyphs throughout prose |\n| Callouts | Neutral Island bordered panel | Blue Nextra info callout with icon and different spacing/color |\n\nThere is also a content/implementation contradiction: the Declaration page says readers can use “the edit link on each page”, while the layout explicitly disables edit links.\n\nRelevant files:\n\n- `docs/app/[lang]/layout.tsx`\n- `docs/app/[lang]/island-theme.css`\n- `docs/app/(landing)/page.tsx`\n- `docs/content/en/_meta.ts`\n- `docs/content/zh/_meta.ts`\n- `docs/content/*/guide/declaration.mdx`\n\n### 2. Guide content and hierarchy\n\n- Introduction feature bullets became five H3 sections. This materially changes page length, scan rhythm, and the table of contents.\n- All guide copy was rewritten rather than migrated in place. Some updates are useful and should remain, but the result is not content parity with the Island reference.\n- About removed the WeChat community option and QR code even though `wechat.jpg` is still shipped as a public asset.\n- Installation is correctly modernized for 1.1.x, but its presentation no longer follows the four-step Island structure.\n- The root language-selection page introduces a visual language that does not exist anywhere in the Island site.\n\n### 3. Component example coverage was reduced\n\nThe Island source had 30 files under `docs/src/components/UsageBox` and `docs/src/components/Example`. The current site consolidates the documentation into a small set of shared demo files and generally renders one demo per component page.\n\n| Component | Island examples no longer shown as equivalent live variants |\n| --- | --- |\n| Button | default, toggled, disabled, sizes, radii, group |\n| Checkbox | default, disabled, sizes, colors, group |\n| Envelope | ADSR, AHDSR, DADSR/delay |\n| Input | default, disabled, bilateral, text, sizes, radii, progress color, min/max, step/sensitivity |\n| Knob | default, disabled, bilateral, rotation range, labels, step/sensitivity, sizes, colors, group |\n| Radio | default, disabled, sizes, colors, group |\n| Slider | default, disabled, vertical, bilateral, axis, step, custom styling, uncontrolled |\n| Switch | default, toggled, disabled, sizes, custom styling |\n| LFO | default and delay |\n| Light | default, on, colors, sizes |\n| Spectrogram | default, axis, grid, EQ3 scenario |\n| VU Meter | default, horizontal, stereo, compact, segment count, custom colors |\n| Card | default, active, real-world scenario |\n\nOscilloscope and Waveform still have a live example, but they also lost the Island example affordance described below.\n\n### 4. The example and API presentation is different\n\n- Island gives every example a `Preview` / `Code` switch. The current demo frame has only a `Preview` label; source is no longer available beside each rendered variant.\n- Current demos add useful live status and more realistic audio flows, but they replace rather than supplement the variant matrix above.\n- Island API tables use `Attribute / Description / Type / Default`; current tables use `Prop / Type / Default / Description` and add a new inherited-props paragraph.\n- Dedicated Data Attributes/Data Tags sections were removed from most component pages. The current docs only surface a small subset (for example VU Meter `data-active` and Card `data-toggled`).\n- Full type-declaration blocks were removed in favor of generated API tables. Keep the tables if they are complete, but restore any public contract details that are no longer discoverable.\n- Hook pages gained live demos, lifecycle, and error guidance; preserve those improvements while matching the Island visual hierarchy and API discoverability.\n\nRelevant files:\n\n- `docs/app/_components/controller-demo.tsx`\n- `docs/app/_components/display-*.tsx`\n- `docs/app/_components/hook-demo.tsx`\n- `docs/app/_components/*-api.tsx`\n- `docs/app/_components/*-docs.module.css`\n- `docs/content/{en,zh}/component/*.mdx`\n- `docs/content/{en,zh}/hook/*.mdx`\n\n## Why the current regression check misses this\n\n`scripts/verify-docs-ui.mjs` compares the current site with hand-written style constants. It does not compare the output with an Island screenshot/DOM baseline. It verifies the shell mainly through the Button route and only requires each component route to contain at least one demo, so it cannot catch reduced example coverage, changed copy/hierarchy, missing links, or changed root behavior.\n\nThe two files under `docs/screenshots/` are unreferenced migration-preview captures, not Island parity baselines.\n\n## Acceptance criteria\n\n- [ ] Create and document an Island → Nextra parity matrix covering shell, navigation, content hierarchy, examples, API/data-attribute coverage, and intentional modernized exceptions.\n- [ ] Match the Island shell at 1440×900 and 390×844 in English/Chinese and light/dark themes, including the root-route behavior, sidebar grouping, callouts, link treatment, and page-level navigation affordances.\n- [ ] Restore the Island Links destinations, edit-page affordance, previous/next navigation, and footer behavior, or explicitly document an approved product decision for each deviation.\n- [ ] Fix the Declaration copy so it agrees with the actual edit-link behavior.\n- [ ] Give every Island component variant an equivalent live preview and adjacent copyable source, unless its removal is explicitly approved in the parity matrix.\n- [ ] Restore missing Data Attributes/Data Tags and public type/API details.\n- [ ] Preserve the current 1.1.x installation, Tone.js 15, accessibility, lifecycle, error-handling, and real-audio-demo improvements.\n- [ ] Replace the current style-constant-only check with maintained Island visual baselines (or an equivalent deterministic comparison) for representative guide, controller, visualization, Hook, and home routes.\n- [ ] Add content-inventory assertions for example labels/counts, Links destinations, edit/pagination controls, root behavior, and both locales.\n- [ ] `pnpm lint`, `pnpm typecheck:docs`, `pnpm build:docs`, and `pnpm test:docs` pass.\n\n## Out of scope\n\n- Reintroducing IslandJS, NextUI, or `react-live`\n- Reverting accurate Echo UI 1.1.x compatibility and API information\n- Removing accessibility or real Web Audio improvements solely to obtain pixel parity\n\n\n## Frozen implementation contract\n\n### Acceptance criteria\n\n1. Add a maintained Island → Nextra parity matrix that covers:\n   - root-route behavior;\n   - desktop and mobile shell/navigation;\n   - both locales and both color schemes;\n   - guide hierarchy and content exceptions;\n   - component example labels/counts;\n   - Preview/Code behavior;\n   - API, public type, and data-attribute coverage;\n   - every intentional modernized exception.\n2. Make `/` follow the Island language-routing behavior instead of presenting a\n   separate editorial language picker.\n3. Match the Island shell on the required representative routes at 1440×900 and\n   390×844 in English and Chinese, light and dark:\n   - preserve the Island header and mobile-menu hierarchy;\n   - restore the Links destinations (GitHub, Discord, Twitter);\n   - restore Guide/About sidebar grouping;\n   - restore edit-page, last-updated, previous/next, and visible footer behavior;\n   - use Island-like external-link and callout treatments.\n4. Reconcile Declaration copy with the restored edit-page affordance.\n5. Restore the Island guide hierarchy and essential content, including the\n   Introduction feature list rhythm and the About WeChat option/QR image, while\n   retaining accurate Echo UI 1.1.x installation and compatibility guidance.\n6. Give every component variant listed in the issue snapshot an equivalent live\n   preview and adjacent copyable source. A deliberately omitted variant must be\n   named and justified in the parity matrix.\n7. Preserve the richer real-audio, status, accessibility, lifecycle, and error\n   handling added by the Nextra migration; these supplement rather than replace\n   the Island variant matrix.\n8. Restore discoverable Data Attributes/Data Tags and public API/type details.\n   Generated tables may remain when complete, but their visible column order and\n   hierarchy must follow the Island contract where parity is expected.\n9. Replace the style-constant-only regression coverage with deterministic,\n   maintained Island visual baselines (or an equivalent deterministic screenshot\n   comparison) for home, guide, controller, visualization, and Hook categories.\n10. Add content-inventory assertions for both locales covering example\n    labels/counts, Links destinations, root behavior, edit/pagination/footer\n    controls, guide grouping, and representative API/data-attribute details.\n11. `pnpm lint`, `pnpm typecheck:docs`, `pnpm build:docs`, `pnpm test:docs`, and\n    the full `pnpm verify` pass.\n\n### In scope\n\n- `docs/app/**`, `docs/content/{en,zh}/**`, and documentation-only styles/assets.\n- Shared documentation demo/source/API components.\n- Documentation route, content-inventory, and visual-parity verification scripts\n  and tests.\n- Documentation of the parity matrix and intentionally retained modern behavior.\n- Test fixtures/baselines that are deterministic and checked into the repository.\n\n### Out of scope\n\n- Reintroducing IslandJS, NextUI, or `react-live`.\n- Reverting React 19, Tailwind CSS 4, Tone.js 15, accessibility, lifecycle,\n  error-handling, or real Web Audio improvements.\n- Changing the shipped Echo UI component/hook runtime or public package API solely\n  to make the documentation resemble the legacy site.\n- New production dependencies, release/version changes, or unrelated refactors.\n\n### Pre-agreed TDD seams\n\n1. First make content-inventory tests fail for root behavior, navigation links,\n   Guide/About grouping, footer/edit/pagination controls, both locales, variant\n   labels/counts, source affordances, and representative data attributes/API rows.\n2. Add or revise deterministic visual-parity assertions so they fail against the\n   current Nextra shell before changing shell styles or structure.\n3. Implement the smallest shared demo/source model that can express all required\n   variants, adding targeted tests for each controller/display category before\n   populating page content.\n4. Keep modern audio-demo behavior covered while extending Preview/Code; source\n   disclosure and copy controls must be keyboard-accessible.\n5. Run the closest targeted Vitest/Node check after each seam and\n   `pnpm typecheck:docs` regularly.\n\n### Required targeted checks\n\n- Targeted Vitest tests for docs route/content inventory.\n- Targeted Node checks for Nextra output and visual-parity baselines.\n- `pnpm lint`\n- `pnpm typecheck:docs`\n- `pnpm build:docs`\n- `pnpm test:docs`\n- `pnpm verify` as the final implementation check.\n\n### Required UI evidence\n\nStore before/after evidence under\n`screen-shots/20260724T132107Z-issue-108-743034/` with an index that maps each\ncapture to its route, locale, theme, viewport, and acceptance criterion.\n\n- Viewports: 1440×900 and 390×844.\n- Locales/themes: English and Chinese, light and dark.\n- Routes: home, `/guide/introduction`, `/guide/about`, `/component/button`,\n  `/component/knob`, `/component/spectrogram`, and `/hook/usePlayer`.\n- Interaction evidence: desktop Links menu, mobile navigation, locale/theme\n  switching, previous/next navigation, edit link, Preview/Code switching, source\n  copy action, and at least one real-audio demo state.\n- Include focused before/after comparisons for representative home, guide,\n  controller, visualization, and Hook pages. The evidence index may use a\n  documented representative matrix instead of duplicating every unchanged\n  combination, but all locale/theme/viewport combinations must be exercised by a\n  deterministic check.\n- Record keyboard/focus and reduced-motion observations for new interactive UI.\n\n### Risks and owner-confirmation boundaries\n\n- The owner has explicitly approved the issue's >400-line implementation budget.\n- Stop for owner confirmation before adding a dependency, changing a shipped\n  package API/runtime, changing release metadata, weakening accessibility or\n  security behavior, or approving an intentional parity exception not already\n  stated above.\n- Treat the live Island site as the visual/content reference and the current\n  package implementation/types as the source of truth for modern API facts.\n- Prefer shared data-driven documentation structures over duplicating large\n  locale-specific React implementations.\n\n### Stop conditions\n\n- A requirement conflicts with the current public runtime/API and cannot be\n  resolved as documentation-only work.\n- A required Island reference/baseline cannot be captured deterministically.\n- An in-scope check fails twice for causes outside the issue's changes.\n- Work would require a new dependency, release change, security-sensitive change,\n  or product/API decision.\n- The implementation is complete and committed.\n\nStop after committing. Do not push, create a PR, or merge.\n","events":[{"schemaVersion":1,"runId":"20260724T132107Z-issue-108-743034","type":"loop_started","timestamp":"2026-07-24T13:21:07.375Z","status":"running","payload":{"issueNumber":108,"branch":"codex/issue-108"}},{"schemaVersion":1,"runId":"20260724T132107Z-issue-108-743034","type":"brief_frozen","timestamp":"2026-07-24T13:28:52.219Z","status":"frozen","payload":{"briefDigest":"3cfea23d657797a80267c52400c3844b534417a8ecdf26620174af40dbaf0ed6","uiEvidenceRequired":true}},{"schemaVersion":1,"runId":"20260724T132107Z-issue-108-743034","type":"implementation_completed","timestamp":"2026-07-24T16:40:25.437Z","status":"passed","payload":{"agent":"$implement","invocationId":"978de939-8586-4fa8-aaa2-1a49db3d1048","startedAt":"2026-07-24T13:30:00.000Z","finishedAt":"2026-07-24T16:33:52.000Z","briefDigest":"3cfea23d657797a80267c52400c3844b534417a8ecdf26620174af40dbaf0ed6","commitSha":"b15cded4fb9fa319bb35e56a70a4401cbf1d0e33","resultPath":"logs/runs/20260724T132107Z-issue-108-743034/implementation-result-1.json","resultDigest":"0d4088340043de67edd52951fa8a513ef8d0a349a98ac5f7365ffd0b667781df"}}],"artifacts":[{"path":"logs/runs/20260724T132107Z-issue-108-743034/implementation-result-1.json","sha256":"0d4088340043de67edd52951fa8a513ef8d0a349a98ac5f7365ffd0b667781df","source":"{\n  \"schemaVersion\": 1,\n  \"runId\": \"20260724T132107Z-issue-108-743034\",\n  \"agent\": \"$implement\",\n  \"invocationId\": \"978de939-8586-4fa8-aaa2-1a49db3d1048\",\n  \"startedAt\": \"2026-07-24T13:30:00.000Z\",\n  \"finishedAt\": \"2026-07-24T16:33:52.000Z\",\n  \"briefDigest\": \"3cfea23d657797a80267c52400c3844b534417a8ecdf26620174af40dbaf0ed6\",\n  \"commitSha\": \"b15cded4fb9fa319bb35e56a70a4401cbf1d0e33\",\n  \"checks\": [\n    {\n      \"command\": \"pnpm vitest run tests/docs-parity.test.ts tests/docs-example-frame.test.tsx tests/docs-route-inventory.test.ts\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"node scripts/verify-nextra-output.mjs\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"node scripts/verify-docs-ui.mjs\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"node scripts/capture-docs-evidence.mjs\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm lint\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm typecheck:docs\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm build:docs\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm test:docs\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm verify\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Targeted Vitest tests for docs route/content inventory.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Targeted Node checks for Nextra output and visual-parity baselines.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm verify as the final implementation check.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"### Required UI evidence\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Store before/after evidence under\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"screen-shots/20260724T132107Z-issue-108-743034/ with an index that maps each\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"capture to its route, locale, theme, viewport, and acceptance criterion.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Viewports: 1440×900 and 390×844.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Locales/themes: English and Chinese, light and dark.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Routes: home, /guide/introduction, /guide/about, /component/button,\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"/component/knob, /component/spectrogram, and /hook/usePlayer.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Interaction evidence: desktop Links menu, mobile navigation, locale/theme\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"switching, previous/next navigation, edit link, Preview/Code switching, source\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"copy action, and at least one real-audio demo state.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Include focused before/after comparisons for representative home, guide,\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"controller, visualization, and Hook pages. The evidence index may use a\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"documented representative matrix instead of duplicating every unchanged\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"combination, but all locale/theme/viewport combinations must be exercised by a\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"deterministic check.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Record keyboard/focus and reduced-motion observations for new interactive UI.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"### Risks and owner-confirmation boundaries\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"The owner has explicitly approved the issue's >400-line implementation budget.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Stop for owner confirmation before adding a dependency, changing a shipped\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"package API/runtime, changing release metadata, weakening accessibility or\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"security behavior, or approving an intentional parity exception not already\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"stated above.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Treat the live Island site as the visual/content reference and the current\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"package implementation/types as the source of truth for modern API facts.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Prefer shared data-driven documentation structures over duplicating large\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"locale-specific React implementations.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"### Stop conditions\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"A requirement conflicts with the current public runtime/API and cannot be\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"resolved as documentation-only work.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"A required Island reference/baseline cannot be captured deterministically.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"An in-scope check fails twice for causes outside the issue's changes.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Work would require a new dependency, release change, security-sensitive change,\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"or product/API decision.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"The implementation is complete and committed.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Stop after committing. Do not push, create a PR, or merge.\",\n      \"status\": \"passed\"\n    }\n  ]\n}\n"}],"updatedAt":"2026-07-24T16:40:25.437Z"}

[Ethandasw]

{"schemaVersion":1,"kind":"active-checkpoint","run":{"schemaVersion":1,"runId":"20260724T132107Z-issue-108-743034","issueNumber":108,"issueTitle":"docs: close the remaining Island UI and content parity gaps in Nextra","issueUrl":"https://github.com/codeacme17/echo-ui/issues/108","baseBranch":"dev","baseSha":"9eea05360a90e46a4c66c2e821e9ad5bd6c71c67","branch":"codex/issue-108","status":"running","startedAt":"2026-07-24T13:21:07.375Z","finishedAt":null,"prUrl":"https://github.com/codeacme17/echo-ui/pull/111","headSha":"8ddb38818164f6b0b0d77b236c0dd3fb6cf2a626","mergeSha":null,"issueSnapshot":{"title":"docs: close the remaining Island UI and content parity gaps in Nextra","body":"## Context\n\nThis is a follow-up to #97 / #98. That work required the Nextra documentation to reproduce the established Island site exactly, with `https://echoui.dev/en/` as the visual source of truth. A fresh comparison against the current `dev` branch shows that the shell is closer, but substantial UI, information-architecture, and example-coverage differences remain.\n\nKeep Nextra. “Parity” here means preserving the Island presentation and documentation coverage while retaining factual improvements made for Echo UI 1.1.x (React 19, Tailwind CSS 4, Tone.js 15, accessibility, lifecycle, and error guidance). It does **not** mean restoring IslandJS, NextUI, stale setup instructions, or old implementation dependencies.\n\n## How to compare\n\n1. Run `pnpm dev:docs`.\n2. Compare the same English and Chinese routes against `https://echoui.dev/en/` and `https://echoui.dev/zh/`.\n3. At minimum, inspect `/`, `/guide/introduction`, `/guide/about`, `/component/button`, `/component/knob`, `/component/spectrogram`, and `/hook/usePlayer`.\n4. Compare 1440×900 and 390×844 in both light and dark themes.\n\n## Observed differences\n\n### 1. Site shell and navigation\n\n| Area | Island reference | Current Nextra site |\n| --- | --- | --- |\n| `/` | Redirects directly to `/en` | Shows a separate editorial “Choose your documentation language” landing page |\n| Links menu | GitHub, Discord, Twitter | Discussions, Issues, Discord |\n| Guide sidebar | Shows a `Guide` group heading and a separated `About` group | Renders a flat four-link list |\n| Contribution/navigation affordances | Exposes “Edit this page on GitHub”, last-updated metadata, and previous/next page navigation | `editLink={null}` and `navigation={false}`; only the timestamp remains |\n| Footer | Island configuration contains license/copyright and page navigation metadata | The Nextra footer is mounted but globally hidden |\n| External links | Plain Island link treatment | Nextra adds external-link arrow glyphs throughout prose |\n| Callouts | Neutral Island bordered panel | Blue Nextra info callout with icon and different spacing/color |\n\nThere is also a content/implementation contradiction: the Declaration page says readers can use “the edit link on each page”, while the layout explicitly disables edit links.\n\nRelevant files:\n\n- `docs/app/[lang]/layout.tsx`\n- `docs/app/[lang]/island-theme.css`\n- `docs/app/(landing)/page.tsx`\n- `docs/content/en/_meta.ts`\n- `docs/content/zh/_meta.ts`\n- `docs/content/*/guide/declaration.mdx`\n\n### 2. Guide content and hierarchy\n\n- Introduction feature bullets became five H3 sections. This materially changes page length, scan rhythm, and the table of contents.\n- All guide copy was rewritten rather than migrated in place. Some updates are useful and should remain, but the result is not content parity with the Island reference.\n- About removed the WeChat community option and QR code even though `wechat.jpg` is still shipped as a public asset.\n- Installation is correctly modernized for 1.1.x, but its presentation no longer follows the four-step Island structure.\n- The root language-selection page introduces a visual language that does not exist anywhere in the Island site.\n\n### 3. Component example coverage was reduced\n\nThe Island source had 30 files under `docs/src/components/UsageBox` and `docs/src/components/Example`. The current site consolidates the documentation into a small set of shared demo files and generally renders one demo per component page.\n\n| Component | Island examples no longer shown as equivalent live variants |\n| --- | --- |\n| Button | default, toggled, disabled, sizes, radii, group |\n| Checkbox | default, disabled, sizes, colors, group |\n| Envelope | ADSR, AHDSR, DADSR/delay |\n| Input | default, disabled, bilateral, text, sizes, radii, progress color, min/max, step/sensitivity |\n| Knob | default, disabled, bilateral, rotation range, labels, step/sensitivity, sizes, colors, group |\n| Radio | default, disabled, sizes, colors, group |\n| Slider | default, disabled, vertical, bilateral, axis, step, custom styling, uncontrolled |\n| Switch | default, toggled, disabled, sizes, custom styling |\n| LFO | default and delay |\n| Light | default, on, colors, sizes |\n| Spectrogram | default, axis, grid, EQ3 scenario |\n| VU Meter | default, horizontal, stereo, compact, segment count, custom colors |\n| Card | default, active, real-world scenario |\n\nOscilloscope and Waveform still have a live example, but they also lost the Island example affordance described below.\n\n### 4. The example and API presentation is different\n\n- Island gives every example a `Preview` / `Code` switch. The current demo frame has only a `Preview` label; source is no longer available beside each rendered variant.\n- Current demos add useful live status and more realistic audio flows, but they replace rather than supplement the variant matrix above.\n- Island API tables use `Attribute / Description / Type / Default`; current tables use `Prop / Type / Default / Description` and add a new inherited-props paragraph.\n- Dedicated Data Attributes/Data Tags sections were removed from most component pages. The current docs only surface a small subset (for example VU Meter `data-active` and Card `data-toggled`).\n- Full type-declaration blocks were removed in favor of generated API tables. Keep the tables if they are complete, but restore any public contract details that are no longer discoverable.\n- Hook pages gained live demos, lifecycle, and error guidance; preserve those improvements while matching the Island visual hierarchy and API discoverability.\n\nRelevant files:\n\n- `docs/app/_components/controller-demo.tsx`\n- `docs/app/_components/display-*.tsx`\n- `docs/app/_components/hook-demo.tsx`\n- `docs/app/_components/*-api.tsx`\n- `docs/app/_components/*-docs.module.css`\n- `docs/content/{en,zh}/component/*.mdx`\n- `docs/content/{en,zh}/hook/*.mdx`\n\n## Why the current regression check misses this\n\n`scripts/verify-docs-ui.mjs` compares the current site with hand-written style constants. It does not compare the output with an Island screenshot/DOM baseline. It verifies the shell mainly through the Button route and only requires each component route to contain at least one demo, so it cannot catch reduced example coverage, changed copy/hierarchy, missing links, or changed root behavior.\n\nThe two files under `docs/screenshots/` are unreferenced migration-preview captures, not Island parity baselines.\n\n## Acceptance criteria\n\n- [ ] Create and document an Island → Nextra parity matrix covering shell, navigation, content hierarchy, examples, API/data-attribute coverage, and intentional modernized exceptions.\n- [ ] Match the Island shell at 1440×900 and 390×844 in English/Chinese and light/dark themes, including the root-route behavior, sidebar grouping, callouts, link treatment, and page-level navigation affordances.\n- [ ] Restore the Island Links destinations, edit-page affordance, previous/next navigation, and footer behavior, or explicitly document an approved product decision for each deviation.\n- [ ] Fix the Declaration copy so it agrees with the actual edit-link behavior.\n- [ ] Give every Island component variant an equivalent live preview and adjacent copyable source, unless its removal is explicitly approved in the parity matrix.\n- [ ] Restore missing Data Attributes/Data Tags and public type/API details.\n- [ ] Preserve the current 1.1.x installation, Tone.js 15, accessibility, lifecycle, error-handling, and real-audio-demo improvements.\n- [ ] Replace the current style-constant-only check with maintained Island visual baselines (or an equivalent deterministic comparison) for representative guide, controller, visualization, Hook, and home routes.\n- [ ] Add content-inventory assertions for example labels/counts, Links destinations, edit/pagination controls, root behavior, and both locales.\n- [ ] `pnpm lint`, `pnpm typecheck:docs`, `pnpm build:docs`, and `pnpm test:docs` pass.\n\n## Out of scope\n\n- Reintroducing IslandJS, NextUI, or `react-live`\n- Reverting accurate Echo UI 1.1.x compatibility and API information\n- Removing accessibility or real Web Audio improvements solely to obtain pixel parity\n","labels":["codex-ready"],"url":"https://github.com/codeacme17/echo-ui/issues/108","capturedAt":"2026-07-24T13:21:07.375Z"},"briefDigest":"3cfea23d657797a80267c52400c3844b534417a8ecdf26620174af40dbaf0ed6","uiEvidenceRequired":true,"implementationCommit":"b15cded4fb9fa319bb35e56a70a4401cbf1d0e33"},"briefSource":"# Implementation brief\n\n- Run ID: `20260724T132107Z-issue-108-743034`\n- Issue: #108 — docs: close the remaining Island UI and content parity gaps in Nextra\n- Issue URL: https://github.com/codeacme17/echo-ui/issues/108\n- Base branch: `dev`\n- Base SHA: `9eea05360a90e46a4c66c2e821e9ad5bd6c71c67`\n- Branch: `codex/issue-108`\n- UI evidence required: yes\n\n## Issue snapshot\n\n## Context\n\nThis is a follow-up to #97 / #98. That work required the Nextra documentation to reproduce the established Island site exactly, with `https://echoui.dev/en/` as the visual source of truth. A fresh comparison against the current `dev` branch shows that the shell is closer, but substantial UI, information-architecture, and example-coverage differences remain.\n\nKeep Nextra. “Parity” here means preserving the Island presentation and documentation coverage while retaining factual improvements made for Echo UI 1.1.x (React 19, Tailwind CSS 4, Tone.js 15, accessibility, lifecycle, and error guidance). It does **not** mean restoring IslandJS, NextUI, stale setup instructions, or old implementation dependencies.\n\n## How to compare\n\n1. Run `pnpm dev:docs`.\n2. Compare the same English and Chinese routes against `https://echoui.dev/en/` and `https://echoui.dev/zh/`.\n3. At minimum, inspect `/`, `/guide/introduction`, `/guide/about`, `/component/button`, `/component/knob`, `/component/spectrogram`, and `/hook/usePlayer`.\n4. Compare 1440×900 and 390×844 in both light and dark themes.\n\n## Observed differences\n\n### 1. Site shell and navigation\n\n| Area | Island reference | Current Nextra site |\n| --- | --- | --- |\n| `/` | Redirects directly to `/en` | Shows a separate editorial “Choose your documentation language” landing page |\n| Links menu | GitHub, Discord, Twitter | Discussions, Issues, Discord |\n| Guide sidebar | Shows a `Guide` group heading and a separated `About` group | Renders a flat four-link list |\n| Contribution/navigation affordances | Exposes “Edit this page on GitHub”, last-updated metadata, and previous/next page navigation | `editLink={null}` and `navigation={false}`; only the timestamp remains |\n| Footer | Island configuration contains license/copyright and page navigation metadata | The Nextra footer is mounted but globally hidden |\n| External links | Plain Island link treatment | Nextra adds external-link arrow glyphs throughout prose |\n| Callouts | Neutral Island bordered panel | Blue Nextra info callout with icon and different spacing/color |\n\nThere is also a content/implementation contradiction: the Declaration page says readers can use “the edit link on each page”, while the layout explicitly disables edit links.\n\nRelevant files:\n\n- `docs/app/[lang]/layout.tsx`\n- `docs/app/[lang]/island-theme.css`\n- `docs/app/(landing)/page.tsx`\n- `docs/content/en/_meta.ts`\n- `docs/content/zh/_meta.ts`\n- `docs/content/*/guide/declaration.mdx`\n\n### 2. Guide content and hierarchy\n\n- Introduction feature bullets became five H3 sections. This materially changes page length, scan rhythm, and the table of contents.\n- All guide copy was rewritten rather than migrated in place. Some updates are useful and should remain, but the result is not content parity with the Island reference.\n- About removed the WeChat community option and QR code even though `wechat.jpg` is still shipped as a public asset.\n- Installation is correctly modernized for 1.1.x, but its presentation no longer follows the four-step Island structure.\n- The root language-selection page introduces a visual language that does not exist anywhere in the Island site.\n\n### 3. Component example coverage was reduced\n\nThe Island source had 30 files under `docs/src/components/UsageBox` and `docs/src/components/Example`. The current site consolidates the documentation into a small set of shared demo files and generally renders one demo per component page.\n\n| Component | Island examples no longer shown as equivalent live variants |\n| --- | --- |\n| Button | default, toggled, disabled, sizes, radii, group |\n| Checkbox | default, disabled, sizes, colors, group |\n| Envelope | ADSR, AHDSR, DADSR/delay |\n| Input | default, disabled, bilateral, text, sizes, radii, progress color, min/max, step/sensitivity |\n| Knob | default, disabled, bilateral, rotation range, labels, step/sensitivity, sizes, colors, group |\n| Radio | default, disabled, sizes, colors, group |\n| Slider | default, disabled, vertical, bilateral, axis, step, custom styling, uncontrolled |\n| Switch | default, toggled, disabled, sizes, custom styling |\n| LFO | default and delay |\n| Light | default, on, colors, sizes |\n| Spectrogram | default, axis, grid, EQ3 scenario |\n| VU Meter | default, horizontal, stereo, compact, segment count, custom colors |\n| Card | default, active, real-world scenario |\n\nOscilloscope and Waveform still have a live example, but they also lost the Island example affordance described below.\n\n### 4. The example and API presentation is different\n\n- Island gives every example a `Preview` / `Code` switch. The current demo frame has only a `Preview` label; source is no longer available beside each rendered variant.\n- Current demos add useful live status and more realistic audio flows, but they replace rather than supplement the variant matrix above.\n- Island API tables use `Attribute / Description / Type / Default`; current tables use `Prop / Type / Default / Description` and add a new inherited-props paragraph.\n- Dedicated Data Attributes/Data Tags sections were removed from most component pages. The current docs only surface a small subset (for example VU Meter `data-active` and Card `data-toggled`).\n- Full type-declaration blocks were removed in favor of generated API tables. Keep the tables if they are complete, but restore any public contract details that are no longer discoverable.\n- Hook pages gained live demos, lifecycle, and error guidance; preserve those improvements while matching the Island visual hierarchy and API discoverability.\n\nRelevant files:\n\n- `docs/app/_components/controller-demo.tsx`\n- `docs/app/_components/display-*.tsx`\n- `docs/app/_components/hook-demo.tsx`\n- `docs/app/_components/*-api.tsx`\n- `docs/app/_components/*-docs.module.css`\n- `docs/content/{en,zh}/component/*.mdx`\n- `docs/content/{en,zh}/hook/*.mdx`\n\n## Why the current regression check misses this\n\n`scripts/verify-docs-ui.mjs` compares the current site with hand-written style constants. It does not compare the output with an Island screenshot/DOM baseline. It verifies the shell mainly through the Button route and only requires each component route to contain at least one demo, so it cannot catch reduced example coverage, changed copy/hierarchy, missing links, or changed root behavior.\n\nThe two files under `docs/screenshots/` are unreferenced migration-preview captures, not Island parity baselines.\n\n## Acceptance criteria\n\n- [ ] Create and document an Island → Nextra parity matrix covering shell, navigation, content hierarchy, examples, API/data-attribute coverage, and intentional modernized exceptions.\n- [ ] Match the Island shell at 1440×900 and 390×844 in English/Chinese and light/dark themes, including the root-route behavior, sidebar grouping, callouts, link treatment, and page-level navigation affordances.\n- [ ] Restore the Island Links destinations, edit-page affordance, previous/next navigation, and footer behavior, or explicitly document an approved product decision for each deviation.\n- [ ] Fix the Declaration copy so it agrees with the actual edit-link behavior.\n- [ ] Give every Island component variant an equivalent live preview and adjacent copyable source, unless its removal is explicitly approved in the parity matrix.\n- [ ] Restore missing Data Attributes/Data Tags and public type/API details.\n- [ ] Preserve the current 1.1.x installation, Tone.js 15, accessibility, lifecycle, error-handling, and real-audio-demo improvements.\n- [ ] Replace the current style-constant-only check with maintained Island visual baselines (or an equivalent deterministic comparison) for representative guide, controller, visualization, Hook, and home routes.\n- [ ] Add content-inventory assertions for example labels/counts, Links destinations, edit/pagination controls, root behavior, and both locales.\n- [ ] `pnpm lint`, `pnpm typecheck:docs`, `pnpm build:docs`, and `pnpm test:docs` pass.\n\n## Out of scope\n\n- Reintroducing IslandJS, NextUI, or `react-live`\n- Reverting accurate Echo UI 1.1.x compatibility and API information\n- Removing accessibility or real Web Audio improvements solely to obtain pixel parity\n\n\n## Frozen implementation contract\n\n### Acceptance criteria\n\n1. Add a maintained Island → Nextra parity matrix that covers:\n   - root-route behavior;\n   - desktop and mobile shell/navigation;\n   - both locales and both color schemes;\n   - guide hierarchy and content exceptions;\n   - component example labels/counts;\n   - Preview/Code behavior;\n   - API, public type, and data-attribute coverage;\n   - every intentional modernized exception.\n2. Make `/` follow the Island language-routing behavior instead of presenting a\n   separate editorial language picker.\n3. Match the Island shell on the required representative routes at 1440×900 and\n   390×844 in English and Chinese, light and dark:\n   - preserve the Island header and mobile-menu hierarchy;\n   - restore the Links destinations (GitHub, Discord, Twitter);\n   - restore Guide/About sidebar grouping;\n   - restore edit-page, last-updated, previous/next, and visible footer behavior;\n   - use Island-like external-link and callout treatments.\n4. Reconcile Declaration copy with the restored edit-page affordance.\n5. Restore the Island guide hierarchy and essential content, including the\n   Introduction feature list rhythm and the About WeChat option/QR image, while\n   retaining accurate Echo UI 1.1.x installation and compatibility guidance.\n6. Give every component variant listed in the issue snapshot an equivalent live\n   preview and adjacent copyable source. A deliberately omitted variant must be\n   named and justified in the parity matrix.\n7. Preserve the richer real-audio, status, accessibility, lifecycle, and error\n   handling added by the Nextra migration; these supplement rather than replace\n   the Island variant matrix.\n8. Restore discoverable Data Attributes/Data Tags and public API/type details.\n   Generated tables may remain when complete, but their visible column order and\n   hierarchy must follow the Island contract where parity is expected.\n9. Replace the style-constant-only regression coverage with deterministic,\n   maintained Island visual baselines (or an equivalent deterministic screenshot\n   comparison) for home, guide, controller, visualization, and Hook categories.\n10. Add content-inventory assertions for both locales covering example\n    labels/counts, Links destinations, root behavior, edit/pagination/footer\n    controls, guide grouping, and representative API/data-attribute details.\n11. `pnpm lint`, `pnpm typecheck:docs`, `pnpm build:docs`, `pnpm test:docs`, and\n    the full `pnpm verify` pass.\n\n### In scope\n\n- `docs/app/**`, `docs/content/{en,zh}/**`, and documentation-only styles/assets.\n- Shared documentation demo/source/API components.\n- Documentation route, content-inventory, and visual-parity verification scripts\n  and tests.\n- Documentation of the parity matrix and intentionally retained modern behavior.\n- Test fixtures/baselines that are deterministic and checked into the repository.\n\n### Out of scope\n\n- Reintroducing IslandJS, NextUI, or `react-live`.\n- Reverting React 19, Tailwind CSS 4, Tone.js 15, accessibility, lifecycle,\n  error-handling, or real Web Audio improvements.\n- Changing the shipped Echo UI component/hook runtime or public package API solely\n  to make the documentation resemble the legacy site.\n- New production dependencies, release/version changes, or unrelated refactors.\n\n### Pre-agreed TDD seams\n\n1. First make content-inventory tests fail for root behavior, navigation links,\n   Guide/About grouping, footer/edit/pagination controls, both locales, variant\n   labels/counts, source affordances, and representative data attributes/API rows.\n2. Add or revise deterministic visual-parity assertions so they fail against the\n   current Nextra shell before changing shell styles or structure.\n3. Implement the smallest shared demo/source model that can express all required\n   variants, adding targeted tests for each controller/display category before\n   populating page content.\n4. Keep modern audio-demo behavior covered while extending Preview/Code; source\n   disclosure and copy controls must be keyboard-accessible.\n5. Run the closest targeted Vitest/Node check after each seam and\n   `pnpm typecheck:docs` regularly.\n\n### Required targeted checks\n\n- Targeted Vitest tests for docs route/content inventory.\n- Targeted Node checks for Nextra output and visual-parity baselines.\n- `pnpm lint`\n- `pnpm typecheck:docs`\n- `pnpm build:docs`\n- `pnpm test:docs`\n- `pnpm verify` as the final implementation check.\n\n### Required UI evidence\n\nStore before/after evidence under\n`screen-shots/20260724T132107Z-issue-108-743034/` with an index that maps each\ncapture to its route, locale, theme, viewport, and acceptance criterion.\n\n- Viewports: 1440×900 and 390×844.\n- Locales/themes: English and Chinese, light and dark.\n- Routes: home, `/guide/introduction`, `/guide/about`, `/component/button`,\n  `/component/knob`, `/component/spectrogram`, and `/hook/usePlayer`.\n- Interaction evidence: desktop Links menu, mobile navigation, locale/theme\n  switching, previous/next navigation, edit link, Preview/Code switching, source\n  copy action, and at least one real-audio demo state.\n- Include focused before/after comparisons for representative home, guide,\n  controller, visualization, and Hook pages. The evidence index may use a\n  documented representative matrix instead of duplicating every unchanged\n  combination, but all locale/theme/viewport combinations must be exercised by a\n  deterministic check.\n- Record keyboard/focus and reduced-motion observations for new interactive UI.\n\n### Risks and owner-confirmation boundaries\n\n- The owner has explicitly approved the issue's >400-line implementation budget.\n- Stop for owner confirmation before adding a dependency, changing a shipped\n  package API/runtime, changing release metadata, weakening accessibility or\n  security behavior, or approving an intentional parity exception not already\n  stated above.\n- Treat the live Island site as the visual/content reference and the current\n  package implementation/types as the source of truth for modern API facts.\n- Prefer shared data-driven documentation structures over duplicating large\n  locale-specific React implementations.\n\n### Stop conditions\n\n- A requirement conflicts with the current public runtime/API and cannot be\n  resolved as documentation-only work.\n- A required Island reference/baseline cannot be captured deterministically.\n- An in-scope check fails twice for causes outside the issue's changes.\n- Work would require a new dependency, release change, security-sensitive change,\n  or product/API decision.\n- The implementation is complete and committed.\n\nStop after committing. Do not push, create a PR, or merge.\n","events":[{"schemaVersion":1,"runId":"20260724T132107Z-issue-108-743034","type":"loop_started","timestamp":"2026-07-24T13:21:07.375Z","status":"running","payload":{"issueNumber":108,"branch":"codex/issue-108"}},{"schemaVersion":1,"runId":"20260724T132107Z-issue-108-743034","type":"brief_frozen","timestamp":"2026-07-24T13:28:52.219Z","status":"frozen","payload":{"briefDigest":"3cfea23d657797a80267c52400c3844b534417a8ecdf26620174af40dbaf0ed6","uiEvidenceRequired":true}},{"schemaVersion":1,"runId":"20260724T132107Z-issue-108-743034","type":"implementation_completed","timestamp":"2026-07-24T16:40:25.437Z","status":"passed","payload":{"agent":"$implement","invocationId":"978de939-8586-4fa8-aaa2-1a49db3d1048","startedAt":"2026-07-24T13:30:00.000Z","finishedAt":"2026-07-24T16:33:52.000Z","briefDigest":"3cfea23d657797a80267c52400c3844b534417a8ecdf26620174af40dbaf0ed6","commitSha":"b15cded4fb9fa319bb35e56a70a4401cbf1d0e33","resultPath":"logs/runs/20260724T132107Z-issue-108-743034/implementation-result-1.json","resultDigest":"0d4088340043de67edd52951fa8a513ef8d0a349a98ac5f7365ffd0b667781df"}},{"schemaVersion":1,"runId":"20260724T132107Z-issue-108-743034","type":"pr_published","timestamp":"2026-07-24T19:56:18.346Z","status":"draft","payload":{"prUrl":"https://github.com/codeacme17/echo-ui/pull/111","headSha":"8ddb38818164f6b0b0d77b236c0dd3fb6cf2a626","baseBranch":"dev","branch":"codex/issue-108"}}],"artifacts":[{"path":"logs/runs/20260724T132107Z-issue-108-743034/implementation-result-1.json","sha256":"0d4088340043de67edd52951fa8a513ef8d0a349a98ac5f7365ffd0b667781df","source":"{\n  \"schemaVersion\": 1,\n  \"runId\": \"20260724T132107Z-issue-108-743034\",\n  \"agent\": \"$implement\",\n  \"invocationId\": \"978de939-8586-4fa8-aaa2-1a49db3d1048\",\n  \"startedAt\": \"2026-07-24T13:30:00.000Z\",\n  \"finishedAt\": \"2026-07-24T16:33:52.000Z\",\n  \"briefDigest\": \"3cfea23d657797a80267c52400c3844b534417a8ecdf26620174af40dbaf0ed6\",\n  \"commitSha\": \"b15cded4fb9fa319bb35e56a70a4401cbf1d0e33\",\n  \"checks\": [\n    {\n      \"command\": \"pnpm vitest run tests/docs-parity.test.ts tests/docs-example-frame.test.tsx tests/docs-route-inventory.test.ts\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"node scripts/verify-nextra-output.mjs\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"node scripts/verify-docs-ui.mjs\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"node scripts/capture-docs-evidence.mjs\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm lint\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm typecheck:docs\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm build:docs\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm test:docs\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm verify\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Targeted Vitest tests for docs route/content inventory.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Targeted Node checks for Nextra output and visual-parity baselines.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm verify as the final implementation check.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"### Required UI evidence\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Store before/after evidence under\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"screen-shots/20260724T132107Z-issue-108-743034/ with an index that maps each\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"capture to its route, locale, theme, viewport, and acceptance criterion.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Viewports: 1440×900 and 390×844.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Locales/themes: English and Chinese, light and dark.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Routes: home, /guide/introduction, /guide/about, /component/button,\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"/component/knob, /component/spectrogram, and /hook/usePlayer.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Interaction evidence: desktop Links menu, mobile navigation, locale/theme\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"switching, previous/next navigation, edit link, Preview/Code switching, source\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"copy action, and at least one real-audio demo state.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Include focused before/after comparisons for representative home, guide,\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"controller, visualization, and Hook pages. The evidence index may use a\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"documented representative matrix instead of duplicating every unchanged\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"combination, but all locale/theme/viewport combinations must be exercised by a\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"deterministic check.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Record keyboard/focus and reduced-motion observations for new interactive UI.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"### Risks and owner-confirmation boundaries\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"The owner has explicitly approved the issue's >400-line implementation budget.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Stop for owner confirmation before adding a dependency, changing a shipped\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"package API/runtime, changing release metadata, weakening accessibility or\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"security behavior, or approving an intentional parity exception not already\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"stated above.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Treat the live Island site as the visual/content reference and the current\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"package implementation/types as the source of truth for modern API facts.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Prefer shared data-driven documentation structures over duplicating large\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"locale-specific React implementations.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"### Stop conditions\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"A requirement conflicts with the current public runtime/API and cannot be\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"resolved as documentation-only work.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"A required Island reference/baseline cannot be captured deterministically.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"An in-scope check fails twice for causes outside the issue's changes.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Work would require a new dependency, release change, security-sensitive change,\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"or product/API decision.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"The implementation is complete and committed.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Stop after committing. Do not push, create a PR, or merge.\",\n      \"status\": \"passed\"\n    }\n  ]\n}\n"}],"updatedAt":"2026-07-24T19:56:18.346Z"}

[Ethandasw]

{"schemaVersion":1,"kind":"active-checkpoint","run":{"schemaVersion":1,"runId":"20260724T132107Z-issue-108-743034","issueNumber":108,"issueTitle":"docs: close the remaining Island UI and content parity gaps in Nextra","issueUrl":"https://github.com/codeacme17/echo-ui/issues/108","baseBranch":"dev","baseSha":"9eea05360a90e46a4c66c2e821e9ad5bd6c71c67","branch":"codex/issue-108","status":"running","startedAt":"2026-07-24T13:21:07.375Z","finishedAt":null,"prUrl":"https://github.com/codeacme17/echo-ui/pull/111","headSha":"8ddb38818164f6b0b0d77b236c0dd3fb6cf2a626","mergeSha":null,"issueSnapshot":{"title":"docs: close the remaining Island UI and content parity gaps in Nextra","body":"## Context\n\nThis is a follow-up to #97 / #98. That work required the Nextra documentation to reproduce the established Island site exactly, with `https://echoui.dev/en/` as the visual source of truth. A fresh comparison against the current `dev` branch shows that the shell is closer, but substantial UI, information-architecture, and example-coverage differences remain.\n\nKeep Nextra. “Parity” here means preserving the Island presentation and documentation coverage while retaining factual improvements made for Echo UI 1.1.x (React 19, Tailwind CSS 4, Tone.js 15, accessibility, lifecycle, and error guidance). It does **not** mean restoring IslandJS, NextUI, stale setup instructions, or old implementation dependencies.\n\n## How to compare\n\n1. Run `pnpm dev:docs`.\n2. Compare the same English and Chinese routes against `https://echoui.dev/en/` and `https://echoui.dev/zh/`.\n3. At minimum, inspect `/`, `/guide/introduction`, `/guide/about`, `/component/button`, `/component/knob`, `/component/spectrogram`, and `/hook/usePlayer`.\n4. Compare 1440×900 and 390×844 in both light and dark themes.\n\n## Observed differences\n\n### 1. Site shell and navigation\n\n| Area | Island reference | Current Nextra site |\n| --- | --- | --- |\n| `/` | Redirects directly to `/en` | Shows a separate editorial “Choose your documentation language” landing page |\n| Links menu | GitHub, Discord, Twitter | Discussions, Issues, Discord |\n| Guide sidebar | Shows a `Guide` group heading and a separated `About` group | Renders a flat four-link list |\n| Contribution/navigation affordances | Exposes “Edit this page on GitHub”, last-updated metadata, and previous/next page navigation | `editLink={null}` and `navigation={false}`; only the timestamp remains |\n| Footer | Island configuration contains license/copyright and page navigation metadata | The Nextra footer is mounted but globally hidden |\n| External links | Plain Island link treatment | Nextra adds external-link arrow glyphs throughout prose |\n| Callouts | Neutral Island bordered panel | Blue Nextra info callout with icon and different spacing/color |\n\nThere is also a content/implementation contradiction: the Declaration page says readers can use “the edit link on each page”, while the layout explicitly disables edit links.\n\nRelevant files:\n\n- `docs/app/[lang]/layout.tsx`\n- `docs/app/[lang]/island-theme.css`\n- `docs/app/(landing)/page.tsx`\n- `docs/content/en/_meta.ts`\n- `docs/content/zh/_meta.ts`\n- `docs/content/*/guide/declaration.mdx`\n\n### 2. Guide content and hierarchy\n\n- Introduction feature bullets became five H3 sections. This materially changes page length, scan rhythm, and the table of contents.\n- All guide copy was rewritten rather than migrated in place. Some updates are useful and should remain, but the result is not content parity with the Island reference.\n- About removed the WeChat community option and QR code even though `wechat.jpg` is still shipped as a public asset.\n- Installation is correctly modernized for 1.1.x, but its presentation no longer follows the four-step Island structure.\n- The root language-selection page introduces a visual language that does not exist anywhere in the Island site.\n\n### 3. Component example coverage was reduced\n\nThe Island source had 30 files under `docs/src/components/UsageBox` and `docs/src/components/Example`. The current site consolidates the documentation into a small set of shared demo files and generally renders one demo per component page.\n\n| Component | Island examples no longer shown as equivalent live variants |\n| --- | --- |\n| Button | default, toggled, disabled, sizes, radii, group |\n| Checkbox | default, disabled, sizes, colors, group |\n| Envelope | ADSR, AHDSR, DADSR/delay |\n| Input | default, disabled, bilateral, text, sizes, radii, progress color, min/max, step/sensitivity |\n| Knob | default, disabled, bilateral, rotation range, labels, step/sensitivity, sizes, colors, group |\n| Radio | default, disabled, sizes, colors, group |\n| Slider | default, disabled, vertical, bilateral, axis, step, custom styling, uncontrolled |\n| Switch | default, toggled, disabled, sizes, custom styling |\n| LFO | default and delay |\n| Light | default, on, colors, sizes |\n| Spectrogram | default, axis, grid, EQ3 scenario |\n| VU Meter | default, horizontal, stereo, compact, segment count, custom colors |\n| Card | default, active, real-world scenario |\n\nOscilloscope and Waveform still have a live example, but they also lost the Island example affordance described below.\n\n### 4. The example and API presentation is different\n\n- Island gives every example a `Preview` / `Code` switch. The current demo frame has only a `Preview` label; source is no longer available beside each rendered variant.\n- Current demos add useful live status and more realistic audio flows, but they replace rather than supplement the variant matrix above.\n- Island API tables use `Attribute / Description / Type / Default`; current tables use `Prop / Type / Default / Description` and add a new inherited-props paragraph.\n- Dedicated Data Attributes/Data Tags sections were removed from most component pages. The current docs only surface a small subset (for example VU Meter `data-active` and Card `data-toggled`).\n- Full type-declaration blocks were removed in favor of generated API tables. Keep the tables if they are complete, but restore any public contract details that are no longer discoverable.\n- Hook pages gained live demos, lifecycle, and error guidance; preserve those improvements while matching the Island visual hierarchy and API discoverability.\n\nRelevant files:\n\n- `docs/app/_components/controller-demo.tsx`\n- `docs/app/_components/display-*.tsx`\n- `docs/app/_components/hook-demo.tsx`\n- `docs/app/_components/*-api.tsx`\n- `docs/app/_components/*-docs.module.css`\n- `docs/content/{en,zh}/component/*.mdx`\n- `docs/content/{en,zh}/hook/*.mdx`\n\n## Why the current regression check misses this\n\n`scripts/verify-docs-ui.mjs` compares the current site with hand-written style constants. It does not compare the output with an Island screenshot/DOM baseline. It verifies the shell mainly through the Button route and only requires each component route to contain at least one demo, so it cannot catch reduced example coverage, changed copy/hierarchy, missing links, or changed root behavior.\n\nThe two files under `docs/screenshots/` are unreferenced migration-preview captures, not Island parity baselines.\n\n## Acceptance criteria\n\n- [ ] Create and document an Island → Nextra parity matrix covering shell, navigation, content hierarchy, examples, API/data-attribute coverage, and intentional modernized exceptions.\n- [ ] Match the Island shell at 1440×900 and 390×844 in English/Chinese and light/dark themes, including the root-route behavior, sidebar grouping, callouts, link treatment, and page-level navigation affordances.\n- [ ] Restore the Island Links destinations, edit-page affordance, previous/next navigation, and footer behavior, or explicitly document an approved product decision for each deviation.\n- [ ] Fix the Declaration copy so it agrees with the actual edit-link behavior.\n- [ ] Give every Island component variant an equivalent live preview and adjacent copyable source, unless its removal is explicitly approved in the parity matrix.\n- [ ] Restore missing Data Attributes/Data Tags and public type/API details.\n- [ ] Preserve the current 1.1.x installation, Tone.js 15, accessibility, lifecycle, error-handling, and real-audio-demo improvements.\n- [ ] Replace the current style-constant-only check with maintained Island visual baselines (or an equivalent deterministic comparison) for representative guide, controller, visualization, Hook, and home routes.\n- [ ] Add content-inventory assertions for example labels/counts, Links destinations, edit/pagination controls, root behavior, and both locales.\n- [ ] `pnpm lint`, `pnpm typecheck:docs`, `pnpm build:docs`, and `pnpm test:docs` pass.\n\n## Out of scope\n\n- Reintroducing IslandJS, NextUI, or `react-live`\n- Reverting accurate Echo UI 1.1.x compatibility and API information\n- Removing accessibility or real Web Audio improvements solely to obtain pixel parity\n","labels":["codex-ready"],"url":"https://github.com/codeacme17/echo-ui/issues/108","capturedAt":"2026-07-24T13:21:07.375Z"},"briefDigest":"3cfea23d657797a80267c52400c3844b534417a8ecdf26620174af40dbaf0ed6","uiEvidenceRequired":true,"implementationCommit":"4b9818f7c2a77f4dea87c4eceb188bd41facb367"},"briefSource":"# Implementation brief\n\n- Run ID: `20260724T132107Z-issue-108-743034`\n- Issue: #108 — docs: close the remaining Island UI and content parity gaps in Nextra\n- Issue URL: https://github.com/codeacme17/echo-ui/issues/108\n- Base branch: `dev`\n- Base SHA: `9eea05360a90e46a4c66c2e821e9ad5bd6c71c67`\n- Branch: `codex/issue-108`\n- UI evidence required: yes\n\n## Issue snapshot\n\n## Context\n\nThis is a follow-up to #97 / #98. That work required the Nextra documentation to reproduce the established Island site exactly, with `https://echoui.dev/en/` as the visual source of truth. A fresh comparison against the current `dev` branch shows that the shell is closer, but substantial UI, information-architecture, and example-coverage differences remain.\n\nKeep Nextra. “Parity” here means preserving the Island presentation and documentation coverage while retaining factual improvements made for Echo UI 1.1.x (React 19, Tailwind CSS 4, Tone.js 15, accessibility, lifecycle, and error guidance). It does **not** mean restoring IslandJS, NextUI, stale setup instructions, or old implementation dependencies.\n\n## How to compare\n\n1. Run `pnpm dev:docs`.\n2. Compare the same English and Chinese routes against `https://echoui.dev/en/` and `https://echoui.dev/zh/`.\n3. At minimum, inspect `/`, `/guide/introduction`, `/guide/about`, `/component/button`, `/component/knob`, `/component/spectrogram`, and `/hook/usePlayer`.\n4. Compare 1440×900 and 390×844 in both light and dark themes.\n\n## Observed differences\n\n### 1. Site shell and navigation\n\n| Area | Island reference | Current Nextra site |\n| --- | --- | --- |\n| `/` | Redirects directly to `/en` | Shows a separate editorial “Choose your documentation language” landing page |\n| Links menu | GitHub, Discord, Twitter | Discussions, Issues, Discord |\n| Guide sidebar | Shows a `Guide` group heading and a separated `About` group | Renders a flat four-link list |\n| Contribution/navigation affordances | Exposes “Edit this page on GitHub”, last-updated metadata, and previous/next page navigation | `editLink={null}` and `navigation={false}`; only the timestamp remains |\n| Footer | Island configuration contains license/copyright and page navigation metadata | The Nextra footer is mounted but globally hidden |\n| External links | Plain Island link treatment | Nextra adds external-link arrow glyphs throughout prose |\n| Callouts | Neutral Island bordered panel | Blue Nextra info callout with icon and different spacing/color |\n\nThere is also a content/implementation contradiction: the Declaration page says readers can use “the edit link on each page”, while the layout explicitly disables edit links.\n\nRelevant files:\n\n- `docs/app/[lang]/layout.tsx`\n- `docs/app/[lang]/island-theme.css`\n- `docs/app/(landing)/page.tsx`\n- `docs/content/en/_meta.ts`\n- `docs/content/zh/_meta.ts`\n- `docs/content/*/guide/declaration.mdx`\n\n### 2. Guide content and hierarchy\n\n- Introduction feature bullets became five H3 sections. This materially changes page length, scan rhythm, and the table of contents.\n- All guide copy was rewritten rather than migrated in place. Some updates are useful and should remain, but the result is not content parity with the Island reference.\n- About removed the WeChat community option and QR code even though `wechat.jpg` is still shipped as a public asset.\n- Installation is correctly modernized for 1.1.x, but its presentation no longer follows the four-step Island structure.\n- The root language-selection page introduces a visual language that does not exist anywhere in the Island site.\n\n### 3. Component example coverage was reduced\n\nThe Island source had 30 files under `docs/src/components/UsageBox` and `docs/src/components/Example`. The current site consolidates the documentation into a small set of shared demo files and generally renders one demo per component page.\n\n| Component | Island examples no longer shown as equivalent live variants |\n| --- | --- |\n| Button | default, toggled, disabled, sizes, radii, group |\n| Checkbox | default, disabled, sizes, colors, group |\n| Envelope | ADSR, AHDSR, DADSR/delay |\n| Input | default, disabled, bilateral, text, sizes, radii, progress color, min/max, step/sensitivity |\n| Knob | default, disabled, bilateral, rotation range, labels, step/sensitivity, sizes, colors, group |\n| Radio | default, disabled, sizes, colors, group |\n| Slider | default, disabled, vertical, bilateral, axis, step, custom styling, uncontrolled |\n| Switch | default, toggled, disabled, sizes, custom styling |\n| LFO | default and delay |\n| Light | default, on, colors, sizes |\n| Spectrogram | default, axis, grid, EQ3 scenario |\n| VU Meter | default, horizontal, stereo, compact, segment count, custom colors |\n| Card | default, active, real-world scenario |\n\nOscilloscope and Waveform still have a live example, but they also lost the Island example affordance described below.\n\n### 4. The example and API presentation is different\n\n- Island gives every example a `Preview` / `Code` switch. The current demo frame has only a `Preview` label; source is no longer available beside each rendered variant.\n- Current demos add useful live status and more realistic audio flows, but they replace rather than supplement the variant matrix above.\n- Island API tables use `Attribute / Description / Type / Default`; current tables use `Prop / Type / Default / Description` and add a new inherited-props paragraph.\n- Dedicated Data Attributes/Data Tags sections were removed from most component pages. The current docs only surface a small subset (for example VU Meter `data-active` and Card `data-toggled`).\n- Full type-declaration blocks were removed in favor of generated API tables. Keep the tables if they are complete, but restore any public contract details that are no longer discoverable.\n- Hook pages gained live demos, lifecycle, and error guidance; preserve those improvements while matching the Island visual hierarchy and API discoverability.\n\nRelevant files:\n\n- `docs/app/_components/controller-demo.tsx`\n- `docs/app/_components/display-*.tsx`\n- `docs/app/_components/hook-demo.tsx`\n- `docs/app/_components/*-api.tsx`\n- `docs/app/_components/*-docs.module.css`\n- `docs/content/{en,zh}/component/*.mdx`\n- `docs/content/{en,zh}/hook/*.mdx`\n\n## Why the current regression check misses this\n\n`scripts/verify-docs-ui.mjs` compares the current site with hand-written style constants. It does not compare the output with an Island screenshot/DOM baseline. It verifies the shell mainly through the Button route and only requires each component route to contain at least one demo, so it cannot catch reduced example coverage, changed copy/hierarchy, missing links, or changed root behavior.\n\nThe two files under `docs/screenshots/` are unreferenced migration-preview captures, not Island parity baselines.\n\n## Acceptance criteria\n\n- [ ] Create and document an Island → Nextra parity matrix covering shell, navigation, content hierarchy, examples, API/data-attribute coverage, and intentional modernized exceptions.\n- [ ] Match the Island shell at 1440×900 and 390×844 in English/Chinese and light/dark themes, including the root-route behavior, sidebar grouping, callouts, link treatment, and page-level navigation affordances.\n- [ ] Restore the Island Links destinations, edit-page affordance, previous/next navigation, and footer behavior, or explicitly document an approved product decision for each deviation.\n- [ ] Fix the Declaration copy so it agrees with the actual edit-link behavior.\n- [ ] Give every Island component variant an equivalent live preview and adjacent copyable source, unless its removal is explicitly approved in the parity matrix.\n- [ ] Restore missing Data Attributes/Data Tags and public type/API details.\n- [ ] Preserve the current 1.1.x installation, Tone.js 15, accessibility, lifecycle, error-handling, and real-audio-demo improvements.\n- [ ] Replace the current style-constant-only check with maintained Island visual baselines (or an equivalent deterministic comparison) for representative guide, controller, visualization, Hook, and home routes.\n- [ ] Add content-inventory assertions for example labels/counts, Links destinations, edit/pagination controls, root behavior, and both locales.\n- [ ] `pnpm lint`, `pnpm typecheck:docs`, `pnpm build:docs`, and `pnpm test:docs` pass.\n\n## Out of scope\n\n- Reintroducing IslandJS, NextUI, or `react-live`\n- Reverting accurate Echo UI 1.1.x compatibility and API information\n- Removing accessibility or real Web Audio improvements solely to obtain pixel parity\n\n\n## Frozen implementation contract\n\n### Acceptance criteria\n\n1. Add a maintained Island → Nextra parity matrix that covers:\n   - root-route behavior;\n   - desktop and mobile shell/navigation;\n   - both locales and both color schemes;\n   - guide hierarchy and content exceptions;\n   - component example labels/counts;\n   - Preview/Code behavior;\n   - API, public type, and data-attribute coverage;\n   - every intentional modernized exception.\n2. Make `/` follow the Island language-routing behavior instead of presenting a\n   separate editorial language picker.\n3. Match the Island shell on the required representative routes at 1440×900 and\n   390×844 in English and Chinese, light and dark:\n   - preserve the Island header and mobile-menu hierarchy;\n   - restore the Links destinations (GitHub, Discord, Twitter);\n   - restore Guide/About sidebar grouping;\n   - restore edit-page, last-updated, previous/next, and visible footer behavior;\n   - use Island-like external-link and callout treatments.\n4. Reconcile Declaration copy with the restored edit-page affordance.\n5. Restore the Island guide hierarchy and essential content, including the\n   Introduction feature list rhythm and the About WeChat option/QR image, while\n   retaining accurate Echo UI 1.1.x installation and compatibility guidance.\n6. Give every component variant listed in the issue snapshot an equivalent live\n   preview and adjacent copyable source. A deliberately omitted variant must be\n   named and justified in the parity matrix.\n7. Preserve the richer real-audio, status, accessibility, lifecycle, and error\n   handling added by the Nextra migration; these supplement rather than replace\n   the Island variant matrix.\n8. Restore discoverable Data Attributes/Data Tags and public API/type details.\n   Generated tables may remain when complete, but their visible column order and\n   hierarchy must follow the Island contract where parity is expected.\n9. Replace the style-constant-only regression coverage with deterministic,\n   maintained Island visual baselines (or an equivalent deterministic screenshot\n   comparison) for home, guide, controller, visualization, and Hook categories.\n10. Add content-inventory assertions for both locales covering example\n    labels/counts, Links destinations, root behavior, edit/pagination/footer\n    controls, guide grouping, and representative API/data-attribute details.\n11. `pnpm lint`, `pnpm typecheck:docs`, `pnpm build:docs`, `pnpm test:docs`, and\n    the full `pnpm verify` pass.\n\n### In scope\n\n- `docs/app/**`, `docs/content/{en,zh}/**`, and documentation-only styles/assets.\n- Shared documentation demo/source/API components.\n- Documentation route, content-inventory, and visual-parity verification scripts\n  and tests.\n- Documentation of the parity matrix and intentionally retained modern behavior.\n- Test fixtures/baselines that are deterministic and checked into the repository.\n\n### Out of scope\n\n- Reintroducing IslandJS, NextUI, or `react-live`.\n- Reverting React 19, Tailwind CSS 4, Tone.js 15, accessibility, lifecycle,\n  error-handling, or real Web Audio improvements.\n- Changing the shipped Echo UI component/hook runtime or public package API solely\n  to make the documentation resemble the legacy site.\n- New production dependencies, release/version changes, or unrelated refactors.\n\n### Pre-agreed TDD seams\n\n1. First make content-inventory tests fail for root behavior, navigation links,\n   Guide/About grouping, footer/edit/pagination controls, both locales, variant\n   labels/counts, source affordances, and representative data attributes/API rows.\n2. Add or revise deterministic visual-parity assertions so they fail against the\n   current Nextra shell before changing shell styles or structure.\n3. Implement the smallest shared demo/source model that can express all required\n   variants, adding targeted tests for each controller/display category before\n   populating page content.\n4. Keep modern audio-demo behavior covered while extending Preview/Code; source\n   disclosure and copy controls must be keyboard-accessible.\n5. Run the closest targeted Vitest/Node check after each seam and\n   `pnpm typecheck:docs` regularly.\n\n### Required targeted checks\n\n- Targeted Vitest tests for docs route/content inventory.\n- Targeted Node checks for Nextra output and visual-parity baselines.\n- `pnpm lint`\n- `pnpm typecheck:docs`\n- `pnpm build:docs`\n- `pnpm test:docs`\n- `pnpm verify` as the final implementation check.\n\n### Required UI evidence\n\nStore before/after evidence under\n`screen-shots/20260724T132107Z-issue-108-743034/` with an index that maps each\ncapture to its route, locale, theme, viewport, and acceptance criterion.\n\n- Viewports: 1440×900 and 390×844.\n- Locales/themes: English and Chinese, light and dark.\n- Routes: home, `/guide/introduction`, `/guide/about`, `/component/button`,\n  `/component/knob`, `/component/spectrogram`, and `/hook/usePlayer`.\n- Interaction evidence: desktop Links menu, mobile navigation, locale/theme\n  switching, previous/next navigation, edit link, Preview/Code switching, source\n  copy action, and at least one real-audio demo state.\n- Include focused before/after comparisons for representative home, guide,\n  controller, visualization, and Hook pages. The evidence index may use a\n  documented representative matrix instead of duplicating every unchanged\n  combination, but all locale/theme/viewport combinations must be exercised by a\n  deterministic check.\n- Record keyboard/focus and reduced-motion observations for new interactive UI.\n\n### Risks and owner-confirmation boundaries\n\n- The owner has explicitly approved the issue's >400-line implementation budget.\n- Stop for owner confirmation before adding a dependency, changing a shipped\n  package API/runtime, changing release metadata, weakening accessibility or\n  security behavior, or approving an intentional parity exception not already\n  stated above.\n- Treat the live Island site as the visual/content reference and the current\n  package implementation/types as the source of truth for modern API facts.\n- Prefer shared data-driven documentation structures over duplicating large\n  locale-specific React implementations.\n\n### Stop conditions\n\n- A requirement conflicts with the current public runtime/API and cannot be\n  resolved as documentation-only work.\n- A required Island reference/baseline cannot be captured deterministically.\n- An in-scope check fails twice for causes outside the issue's changes.\n- Work would require a new dependency, release change, security-sensitive change,\n  or product/API decision.\n- The implementation is complete and committed.\n\nStop after committing. Do not push, create a PR, or merge.\n","events":[{"schemaVersion":1,"runId":"20260724T132107Z-issue-108-743034","type":"loop_started","timestamp":"2026-07-24T13:21:07.375Z","status":"running","payload":{"issueNumber":108,"branch":"codex/issue-108"}},{"schemaVersion":1,"runId":"20260724T132107Z-issue-108-743034","type":"brief_frozen","timestamp":"2026-07-24T13:28:52.219Z","status":"frozen","payload":{"briefDigest":"3cfea23d657797a80267c52400c3844b534417a8ecdf26620174af40dbaf0ed6","uiEvidenceRequired":true}},{"schemaVersion":1,"runId":"20260724T132107Z-issue-108-743034","type":"implementation_completed","timestamp":"2026-07-24T16:40:25.437Z","status":"passed","payload":{"agent":"$implement","invocationId":"978de939-8586-4fa8-aaa2-1a49db3d1048","startedAt":"2026-07-24T13:30:00.000Z","finishedAt":"2026-07-24T16:33:52.000Z","briefDigest":"3cfea23d657797a80267c52400c3844b534417a8ecdf26620174af40dbaf0ed6","commitSha":"b15cded4fb9fa319bb35e56a70a4401cbf1d0e33","resultPath":"logs/runs/20260724T132107Z-issue-108-743034/implementation-result-1.json","resultDigest":"0d4088340043de67edd52951fa8a513ef8d0a349a98ac5f7365ffd0b667781df"}},{"schemaVersion":1,"runId":"20260724T132107Z-issue-108-743034","type":"pr_published","timestamp":"2026-07-24T19:56:18.346Z","status":"draft","payload":{"prUrl":"https://github.com/codeacme17/echo-ui/pull/111","headSha":"8ddb38818164f6b0b0d77b236c0dd3fb6cf2a626","baseBranch":"dev","branch":"codex/issue-108"}},{"schemaVersion":1,"runId":"20260724T132107Z-issue-108-743034","type":"implementation_completed","timestamp":"2026-07-24T20:48:32.983Z","status":"passed","payload":{"agent":"$implement","invocationId":"aa574e93-b8da-438e-8229-a3fcf0168d22","startedAt":"2026-07-24T19:48:00.000Z","finishedAt":"2026-07-24T20:47:00.000Z","briefDigest":"3cfea23d657797a80267c52400c3844b534417a8ecdf26620174af40dbaf0ed6","commitSha":"4b9818f7c2a77f4dea87c4eceb188bd41facb367","resultPath":"logs/runs/20260724T132107Z-issue-108-743034/implementation-result-2.json","resultDigest":"4393b4c12f4bb52985fd5299ab223b8a95bf6aad7836fbc2b17c15e1edd5f95b"}}],"artifacts":[{"path":"logs/runs/20260724T132107Z-issue-108-743034/implementation-result-1.json","sha256":"0d4088340043de67edd52951fa8a513ef8d0a349a98ac5f7365ffd0b667781df","source":"{\n  \"schemaVersion\": 1,\n  \"runId\": \"20260724T132107Z-issue-108-743034\",\n  \"agent\": \"$implement\",\n  \"invocationId\": \"978de939-8586-4fa8-aaa2-1a49db3d1048\",\n  \"startedAt\": \"2026-07-24T13:30:00.000Z\",\n  \"finishedAt\": \"2026-07-24T16:33:52.000Z\",\n  \"briefDigest\": \"3cfea23d657797a80267c52400c3844b534417a8ecdf26620174af40dbaf0ed6\",\n  \"commitSha\": \"b15cded4fb9fa319bb35e56a70a4401cbf1d0e33\",\n  \"checks\": [\n    {\n      \"command\": \"pnpm vitest run tests/docs-parity.test.ts tests/docs-example-frame.test.tsx tests/docs-route-inventory.test.ts\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"node scripts/verify-nextra-output.mjs\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"node scripts/verify-docs-ui.mjs\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"node scripts/capture-docs-evidence.mjs\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm lint\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm typecheck:docs\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm build:docs\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm test:docs\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm verify\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Targeted Vitest tests for docs route/content inventory.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Targeted Node checks for Nextra output and visual-parity baselines.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm verify as the final implementation check.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"### Required UI evidence\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Store before/after evidence under\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"screen-shots/20260724T132107Z-issue-108-743034/ with an index that maps each\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"capture to its route, locale, theme, viewport, and acceptance criterion.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Viewports: 1440×900 and 390×844.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Locales/themes: English and Chinese, light and dark.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Routes: home, /guide/introduction, /guide/about, /component/button,\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"/component/knob, /component/spectrogram, and /hook/usePlayer.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Interaction evidence: desktop Links menu, mobile navigation, locale/theme\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"switching, previous/next navigation, edit link, Preview/Code switching, source\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"copy action, and at least one real-audio demo state.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Include focused before/after comparisons for representative home, guide,\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"controller, visualization, and Hook pages. The evidence index may use a\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"documented representative matrix instead of duplicating every unchanged\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"combination, but all locale/theme/viewport combinations must be exercised by a\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"deterministic check.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Record keyboard/focus and reduced-motion observations for new interactive UI.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"### Risks and owner-confirmation boundaries\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"The owner has explicitly approved the issue's >400-line implementation budget.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Stop for owner confirmation before adding a dependency, changing a shipped\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"package API/runtime, changing release metadata, weakening accessibility or\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"security behavior, or approving an intentional parity exception not already\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"stated above.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Treat the live Island site as the visual/content reference and the current\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"package implementation/types as the source of truth for modern API facts.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Prefer shared data-driven documentation structures over duplicating large\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"locale-specific React implementations.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"### Stop conditions\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"A requirement conflicts with the current public runtime/API and cannot be\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"resolved as documentation-only work.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"A required Island reference/baseline cannot be captured deterministically.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"An in-scope check fails twice for causes outside the issue's changes.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Work would require a new dependency, release change, security-sensitive change,\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"or product/API decision.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"The implementation is complete and committed.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Stop after committing. Do not push, create a PR, or merge.\",\n      \"status\": \"passed\"\n    }\n  ]\n}\n"},{"path":"logs/runs/20260724T132107Z-issue-108-743034/implementation-result-2.json","sha256":"4393b4c12f4bb52985fd5299ab223b8a95bf6aad7836fbc2b17c15e1edd5f95b","source":"{\n  \"schemaVersion\": 1,\n  \"runId\": \"20260724T132107Z-issue-108-743034\",\n  \"agent\": \"$implement\",\n  \"invocationId\": \"aa574e93-b8da-438e-8229-a3fcf0168d22\",\n  \"startedAt\": \"2026-07-24T19:48:00.000Z\",\n  \"finishedAt\": \"2026-07-24T20:47:00.000Z\",\n  \"briefDigest\": \"3cfea23d657797a80267c52400c3844b534417a8ecdf26620174af40dbaf0ed6\",\n  \"commitSha\": \"4b9818f7c2a77f4dea87c4eceb188bd41facb367\",\n  \"checks\": [\n    {\n      \"command\": \"pnpm vitest run tests/docs-parity.test.ts tests/docs-visual-contract.test.ts\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm vitest run tests/docs-rendered-visual-contract.test.ts\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm lint\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm typecheck:docs\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm build:docs\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm test:docs\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm verify\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"node loops/issue-dev-loop/scripts/validate-candidate-control-plane.mjs --loop-root loops/issue-dev-loop --run-id 20260724T132107Z-issue-108-743034 --base-sha 9eea05360a90e46a4c66c2e821e9ad5bd6c71c67 --head-sha 4b9818f7c2a77f4dea87c4eceb188bd41facb367\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Screenshot manifest structural validator (24 screenshots, 12 pairs).\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Targeted Vitest tests for docs route/content inventory.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Targeted Node checks for Nextra output and visual-parity baselines.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm verify as the final implementation check.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"### Required UI evidence\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Store before/after evidence under\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"screen-shots/20260724T132107Z-issue-108-743034/ with an index that maps each\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"capture to its route, locale, theme, viewport, and acceptance criterion.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Viewports: 1440×900 and 390×844.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Locales/themes: English and Chinese, light and dark.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Routes: home, /guide/introduction, /guide/about, /component/button,\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"/component/knob, /component/spectrogram, and /hook/usePlayer.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Interaction evidence: desktop Links menu, mobile navigation, locale/theme\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"switching, previous/next navigation, edit link, Preview/Code switching, source\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"copy action, and at least one real-audio demo state.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Include focused before/after comparisons for representative home, guide,\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"controller, visualization, and Hook pages. The evidence index may use a\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"documented representative matrix instead of duplicating every unchanged\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"combination, but all locale/theme/viewport combinations must be exercised by a\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"deterministic check.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Record keyboard/focus and reduced-motion observations for new interactive UI.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"### Risks and owner-confirmation boundaries\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"The owner has explicitly approved the issue's >400-line implementation budget.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Stop for owner confirmation before adding a dependency, changing a shipped\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"package API/runtime, changing release metadata, weakening accessibility or\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"security behavior, or approving an intentional parity exception not already\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"stated above.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Treat the live Island site as the visual/content reference and the current\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"package implementation/types as the source of truth for modern API facts.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Prefer shared data-driven documentation structures over duplicating large\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"locale-specific React implementations.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"### Stop conditions\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"A requirement conflicts with the current public runtime/API and cannot be\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"resolved as documentation-only work.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"A required Island reference/baseline cannot be captured deterministically.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"An in-scope check fails twice for causes outside the issue's changes.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Work would require a new dependency, release change, security-sensitive change,\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"or product/API decision.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"The implementation is complete and committed.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Stop after committing. Do not push, create a PR, or merge.\",\n      \"status\": \"passed\"\n    }\n  ]\n}\n"}],"updatedAt":"2026-07-24T20:48:32.983Z"}

[Ethandasw]

{"schemaVersion":1,"kind":"active-checkpoint","run":{"schemaVersion":1,"runId":"20260724T132107Z-issue-108-743034","issueNumber":108,"issueTitle":"docs: close the remaining Island UI and content parity gaps in Nextra","issueUrl":"https://github.com/codeacme17/echo-ui/issues/108","baseBranch":"dev","baseSha":"9eea05360a90e46a4c66c2e821e9ad5bd6c71c67","branch":"codex/issue-108","status":"running","startedAt":"2026-07-24T13:21:07.375Z","finishedAt":null,"prUrl":"https://github.com/codeacme17/echo-ui/pull/111","headSha":"c5100509fb33fc68ff36089c92cfb43c2ab22424","mergeSha":null,"issueSnapshot":{"title":"docs: close the remaining Island UI and content parity gaps in Nextra","body":"## Context\n\nThis is a follow-up to #97 / #98. That work required the Nextra documentation to reproduce the established Island site exactly, with `https://echoui.dev/en/` as the visual source of truth. A fresh comparison against the current `dev` branch shows that the shell is closer, but substantial UI, information-architecture, and example-coverage differences remain.\n\nKeep Nextra. “Parity” here means preserving the Island presentation and documentation coverage while retaining factual improvements made for Echo UI 1.1.x (React 19, Tailwind CSS 4, Tone.js 15, accessibility, lifecycle, and error guidance). It does **not** mean restoring IslandJS, NextUI, stale setup instructions, or old implementation dependencies.\n\n## How to compare\n\n1. Run `pnpm dev:docs`.\n2. Compare the same English and Chinese routes against `https://echoui.dev/en/` and `https://echoui.dev/zh/`.\n3. At minimum, inspect `/`, `/guide/introduction`, `/guide/about`, `/component/button`, `/component/knob`, `/component/spectrogram`, and `/hook/usePlayer`.\n4. Compare 1440×900 and 390×844 in both light and dark themes.\n\n## Observed differences\n\n### 1. Site shell and navigation\n\n| Area | Island reference | Current Nextra site |\n| --- | --- | --- |\n| `/` | Redirects directly to `/en` | Shows a separate editorial “Choose your documentation language” landing page |\n| Links menu | GitHub, Discord, Twitter | Discussions, Issues, Discord |\n| Guide sidebar | Shows a `Guide` group heading and a separated `About` group | Renders a flat four-link list |\n| Contribution/navigation affordances | Exposes “Edit this page on GitHub”, last-updated metadata, and previous/next page navigation | `editLink={null}` and `navigation={false}`; only the timestamp remains |\n| Footer | Island configuration contains license/copyright and page navigation metadata | The Nextra footer is mounted but globally hidden |\n| External links | Plain Island link treatment | Nextra adds external-link arrow glyphs throughout prose |\n| Callouts | Neutral Island bordered panel | Blue Nextra info callout with icon and different spacing/color |\n\nThere is also a content/implementation contradiction: the Declaration page says readers can use “the edit link on each page”, while the layout explicitly disables edit links.\n\nRelevant files:\n\n- `docs/app/[lang]/layout.tsx`\n- `docs/app/[lang]/island-theme.css`\n- `docs/app/(landing)/page.tsx`\n- `docs/content/en/_meta.ts`\n- `docs/content/zh/_meta.ts`\n- `docs/content/*/guide/declaration.mdx`\n\n### 2. Guide content and hierarchy\n\n- Introduction feature bullets became five H3 sections. This materially changes page length, scan rhythm, and the table of contents.\n- All guide copy was rewritten rather than migrated in place. Some updates are useful and should remain, but the result is not content parity with the Island reference.\n- About removed the WeChat community option and QR code even though `wechat.jpg` is still shipped as a public asset.\n- Installation is correctly modernized for 1.1.x, but its presentation no longer follows the four-step Island structure.\n- The root language-selection page introduces a visual language that does not exist anywhere in the Island site.\n\n### 3. Component example coverage was reduced\n\nThe Island source had 30 files under `docs/src/components/UsageBox` and `docs/src/components/Example`. The current site consolidates the documentation into a small set of shared demo files and generally renders one demo per component page.\n\n| Component | Island examples no longer shown as equivalent live variants |\n| --- | --- |\n| Button | default, toggled, disabled, sizes, radii, group |\n| Checkbox | default, disabled, sizes, colors, group |\n| Envelope | ADSR, AHDSR, DADSR/delay |\n| Input | default, disabled, bilateral, text, sizes, radii, progress color, min/max, step/sensitivity |\n| Knob | default, disabled, bilateral, rotation range, labels, step/sensitivity, sizes, colors, group |\n| Radio | default, disabled, sizes, colors, group |\n| Slider | default, disabled, vertical, bilateral, axis, step, custom styling, uncontrolled |\n| Switch | default, toggled, disabled, sizes, custom styling |\n| LFO | default and delay |\n| Light | default, on, colors, sizes |\n| Spectrogram | default, axis, grid, EQ3 scenario |\n| VU Meter | default, horizontal, stereo, compact, segment count, custom colors |\n| Card | default, active, real-world scenario |\n\nOscilloscope and Waveform still have a live example, but they also lost the Island example affordance described below.\n\n### 4. The example and API presentation is different\n\n- Island gives every example a `Preview` / `Code` switch. The current demo frame has only a `Preview` label; source is no longer available beside each rendered variant.\n- Current demos add useful live status and more realistic audio flows, but they replace rather than supplement the variant matrix above.\n- Island API tables use `Attribute / Description / Type / Default`; current tables use `Prop / Type / Default / Description` and add a new inherited-props paragraph.\n- Dedicated Data Attributes/Data Tags sections were removed from most component pages. The current docs only surface a small subset (for example VU Meter `data-active` and Card `data-toggled`).\n- Full type-declaration blocks were removed in favor of generated API tables. Keep the tables if they are complete, but restore any public contract details that are no longer discoverable.\n- Hook pages gained live demos, lifecycle, and error guidance; preserve those improvements while matching the Island visual hierarchy and API discoverability.\n\nRelevant files:\n\n- `docs/app/_components/controller-demo.tsx`\n- `docs/app/_components/display-*.tsx`\n- `docs/app/_components/hook-demo.tsx`\n- `docs/app/_components/*-api.tsx`\n- `docs/app/_components/*-docs.module.css`\n- `docs/content/{en,zh}/component/*.mdx`\n- `docs/content/{en,zh}/hook/*.mdx`\n\n## Why the current regression check misses this\n\n`scripts/verify-docs-ui.mjs` compares the current site with hand-written style constants. It does not compare the output with an Island screenshot/DOM baseline. It verifies the shell mainly through the Button route and only requires each component route to contain at least one demo, so it cannot catch reduced example coverage, changed copy/hierarchy, missing links, or changed root behavior.\n\nThe two files under `docs/screenshots/` are unreferenced migration-preview captures, not Island parity baselines.\n\n## Acceptance criteria\n\n- [ ] Create and document an Island → Nextra parity matrix covering shell, navigation, content hierarchy, examples, API/data-attribute coverage, and intentional modernized exceptions.\n- [ ] Match the Island shell at 1440×900 and 390×844 in English/Chinese and light/dark themes, including the root-route behavior, sidebar grouping, callouts, link treatment, and page-level navigation affordances.\n- [ ] Restore the Island Links destinations, edit-page affordance, previous/next navigation, and footer behavior, or explicitly document an approved product decision for each deviation.\n- [ ] Fix the Declaration copy so it agrees with the actual edit-link behavior.\n- [ ] Give every Island component variant an equivalent live preview and adjacent copyable source, unless its removal is explicitly approved in the parity matrix.\n- [ ] Restore missing Data Attributes/Data Tags and public type/API details.\n- [ ] Preserve the current 1.1.x installation, Tone.js 15, accessibility, lifecycle, error-handling, and real-audio-demo improvements.\n- [ ] Replace the current style-constant-only check with maintained Island visual baselines (or an equivalent deterministic comparison) for representative guide, controller, visualization, Hook, and home routes.\n- [ ] Add content-inventory assertions for example labels/counts, Links destinations, edit/pagination controls, root behavior, and both locales.\n- [ ] `pnpm lint`, `pnpm typecheck:docs`, `pnpm build:docs`, and `pnpm test:docs` pass.\n\n## Out of scope\n\n- Reintroducing IslandJS, NextUI, or `react-live`\n- Reverting accurate Echo UI 1.1.x compatibility and API information\n- Removing accessibility or real Web Audio improvements solely to obtain pixel parity\n","labels":["codex-ready"],"url":"https://github.com/codeacme17/echo-ui/issues/108","capturedAt":"2026-07-24T13:21:07.375Z"},"briefDigest":"3cfea23d657797a80267c52400c3844b534417a8ecdf26620174af40dbaf0ed6","uiEvidenceRequired":true,"implementationCommit":"4b9818f7c2a77f4dea87c4eceb188bd41facb367"},"briefSource":"# Implementation brief\n\n- Run ID: `20260724T132107Z-issue-108-743034`\n- Issue: #108 — docs: close the remaining Island UI and content parity gaps in Nextra\n- Issue URL: https://github.com/codeacme17/echo-ui/issues/108\n- Base branch: `dev`\n- Base SHA: `9eea05360a90e46a4c66c2e821e9ad5bd6c71c67`\n- Branch: `codex/issue-108`\n- UI evidence required: yes\n\n## Issue snapshot\n\n## Context\n\nThis is a follow-up to #97 / #98. That work required the Nextra documentation to reproduce the established Island site exactly, with `https://echoui.dev/en/` as the visual source of truth. A fresh comparison against the current `dev` branch shows that the shell is closer, but substantial UI, information-architecture, and example-coverage differences remain.\n\nKeep Nextra. “Parity” here means preserving the Island presentation and documentation coverage while retaining factual improvements made for Echo UI 1.1.x (React 19, Tailwind CSS 4, Tone.js 15, accessibility, lifecycle, and error guidance). It does **not** mean restoring IslandJS, NextUI, stale setup instructions, or old implementation dependencies.\n\n## How to compare\n\n1. Run `pnpm dev:docs`.\n2. Compare the same English and Chinese routes against `https://echoui.dev/en/` and `https://echoui.dev/zh/`.\n3. At minimum, inspect `/`, `/guide/introduction`, `/guide/about`, `/component/button`, `/component/knob`, `/component/spectrogram`, and `/hook/usePlayer`.\n4. Compare 1440×900 and 390×844 in both light and dark themes.\n\n## Observed differences\n\n### 1. Site shell and navigation\n\n| Area | Island reference | Current Nextra site |\n| --- | --- | --- |\n| `/` | Redirects directly to `/en` | Shows a separate editorial “Choose your documentation language” landing page |\n| Links menu | GitHub, Discord, Twitter | Discussions, Issues, Discord |\n| Guide sidebar | Shows a `Guide` group heading and a separated `About` group | Renders a flat four-link list |\n| Contribution/navigation affordances | Exposes “Edit this page on GitHub”, last-updated metadata, and previous/next page navigation | `editLink={null}` and `navigation={false}`; only the timestamp remains |\n| Footer | Island configuration contains license/copyright and page navigation metadata | The Nextra footer is mounted but globally hidden |\n| External links | Plain Island link treatment | Nextra adds external-link arrow glyphs throughout prose |\n| Callouts | Neutral Island bordered panel | Blue Nextra info callout with icon and different spacing/color |\n\nThere is also a content/implementation contradiction: the Declaration page says readers can use “the edit link on each page”, while the layout explicitly disables edit links.\n\nRelevant files:\n\n- `docs/app/[lang]/layout.tsx`\n- `docs/app/[lang]/island-theme.css`\n- `docs/app/(landing)/page.tsx`\n- `docs/content/en/_meta.ts`\n- `docs/content/zh/_meta.ts`\n- `docs/content/*/guide/declaration.mdx`\n\n### 2. Guide content and hierarchy\n\n- Introduction feature bullets became five H3 sections. This materially changes page length, scan rhythm, and the table of contents.\n- All guide copy was rewritten rather than migrated in place. Some updates are useful and should remain, but the result is not content parity with the Island reference.\n- About removed the WeChat community option and QR code even though `wechat.jpg` is still shipped as a public asset.\n- Installation is correctly modernized for 1.1.x, but its presentation no longer follows the four-step Island structure.\n- The root language-selection page introduces a visual language that does not exist anywhere in the Island site.\n\n### 3. Component example coverage was reduced\n\nThe Island source had 30 files under `docs/src/components/UsageBox` and `docs/src/components/Example`. The current site consolidates the documentation into a small set of shared demo files and generally renders one demo per component page.\n\n| Component | Island examples no longer shown as equivalent live variants |\n| --- | --- |\n| Button | default, toggled, disabled, sizes, radii, group |\n| Checkbox | default, disabled, sizes, colors, group |\n| Envelope | ADSR, AHDSR, DADSR/delay |\n| Input | default, disabled, bilateral, text, sizes, radii, progress color, min/max, step/sensitivity |\n| Knob | default, disabled, bilateral, rotation range, labels, step/sensitivity, sizes, colors, group |\n| Radio | default, disabled, sizes, colors, group |\n| Slider | default, disabled, vertical, bilateral, axis, step, custom styling, uncontrolled |\n| Switch | default, toggled, disabled, sizes, custom styling |\n| LFO | default and delay |\n| Light | default, on, colors, sizes |\n| Spectrogram | default, axis, grid, EQ3 scenario |\n| VU Meter | default, horizontal, stereo, compact, segment count, custom colors |\n| Card | default, active, real-world scenario |\n\nOscilloscope and Waveform still have a live example, but they also lost the Island example affordance described below.\n\n### 4. The example and API presentation is different\n\n- Island gives every example a `Preview` / `Code` switch. The current demo frame has only a `Preview` label; source is no longer available beside each rendered variant.\n- Current demos add useful live status and more realistic audio flows, but they replace rather than supplement the variant matrix above.\n- Island API tables use `Attribute / Description / Type / Default`; current tables use `Prop / Type / Default / Description` and add a new inherited-props paragraph.\n- Dedicated Data Attributes/Data Tags sections were removed from most component pages. The current docs only surface a small subset (for example VU Meter `data-active` and Card `data-toggled`).\n- Full type-declaration blocks were removed in favor of generated API tables. Keep the tables if they are complete, but restore any public contract details that are no longer discoverable.\n- Hook pages gained live demos, lifecycle, and error guidance; preserve those improvements while matching the Island visual hierarchy and API discoverability.\n\nRelevant files:\n\n- `docs/app/_components/controller-demo.tsx`\n- `docs/app/_components/display-*.tsx`\n- `docs/app/_components/hook-demo.tsx`\n- `docs/app/_components/*-api.tsx`\n- `docs/app/_components/*-docs.module.css`\n- `docs/content/{en,zh}/component/*.mdx`\n- `docs/content/{en,zh}/hook/*.mdx`\n\n## Why the current regression check misses this\n\n`scripts/verify-docs-ui.mjs` compares the current site with hand-written style constants. It does not compare the output with an Island screenshot/DOM baseline. It verifies the shell mainly through the Button route and only requires each component route to contain at least one demo, so it cannot catch reduced example coverage, changed copy/hierarchy, missing links, or changed root behavior.\n\nThe two files under `docs/screenshots/` are unreferenced migration-preview captures, not Island parity baselines.\n\n## Acceptance criteria\n\n- [ ] Create and document an Island → Nextra parity matrix covering shell, navigation, content hierarchy, examples, API/data-attribute coverage, and intentional modernized exceptions.\n- [ ] Match the Island shell at 1440×900 and 390×844 in English/Chinese and light/dark themes, including the root-route behavior, sidebar grouping, callouts, link treatment, and page-level navigation affordances.\n- [ ] Restore the Island Links destinations, edit-page affordance, previous/next navigation, and footer behavior, or explicitly document an approved product decision for each deviation.\n- [ ] Fix the Declaration copy so it agrees with the actual edit-link behavior.\n- [ ] Give every Island component variant an equivalent live preview and adjacent copyable source, unless its removal is explicitly approved in the parity matrix.\n- [ ] Restore missing Data Attributes/Data Tags and public type/API details.\n- [ ] Preserve the current 1.1.x installation, Tone.js 15, accessibility, lifecycle, error-handling, and real-audio-demo improvements.\n- [ ] Replace the current style-constant-only check with maintained Island visual baselines (or an equivalent deterministic comparison) for representative guide, controller, visualization, Hook, and home routes.\n- [ ] Add content-inventory assertions for example labels/counts, Links destinations, edit/pagination controls, root behavior, and both locales.\n- [ ] `pnpm lint`, `pnpm typecheck:docs`, `pnpm build:docs`, and `pnpm test:docs` pass.\n\n## Out of scope\n\n- Reintroducing IslandJS, NextUI, or `react-live`\n- Reverting accurate Echo UI 1.1.x compatibility and API information\n- Removing accessibility or real Web Audio improvements solely to obtain pixel parity\n\n\n## Frozen implementation contract\n\n### Acceptance criteria\n\n1. Add a maintained Island → Nextra parity matrix that covers:\n   - root-route behavior;\n   - desktop and mobile shell/navigation;\n   - both locales and both color schemes;\n   - guide hierarchy and content exceptions;\n   - component example labels/counts;\n   - Preview/Code behavior;\n   - API, public type, and data-attribute coverage;\n   - every intentional modernized exception.\n2. Make `/` follow the Island language-routing behavior instead of presenting a\n   separate editorial language picker.\n3. Match the Island shell on the required representative routes at 1440×900 and\n   390×844 in English and Chinese, light and dark:\n   - preserve the Island header and mobile-menu hierarchy;\n   - restore the Links destinations (GitHub, Discord, Twitter);\n   - restore Guide/About sidebar grouping;\n   - restore edit-page, last-updated, previous/next, and visible footer behavior;\n   - use Island-like external-link and callout treatments.\n4. Reconcile Declaration copy with the restored edit-page affordance.\n5. Restore the Island guide hierarchy and essential content, including the\n   Introduction feature list rhythm and the About WeChat option/QR image, while\n   retaining accurate Echo UI 1.1.x installation and compatibility guidance.\n6. Give every component variant listed in the issue snapshot an equivalent live\n   preview and adjacent copyable source. A deliberately omitted variant must be\n   named and justified in the parity matrix.\n7. Preserve the richer real-audio, status, accessibility, lifecycle, and error\n   handling added by the Nextra migration; these supplement rather than replace\n   the Island variant matrix.\n8. Restore discoverable Data Attributes/Data Tags and public API/type details.\n   Generated tables may remain when complete, but their visible column order and\n   hierarchy must follow the Island contract where parity is expected.\n9. Replace the style-constant-only regression coverage with deterministic,\n   maintained Island visual baselines (or an equivalent deterministic screenshot\n   comparison) for home, guide, controller, visualization, and Hook categories.\n10. Add content-inventory assertions for both locales covering example\n    labels/counts, Links destinations, root behavior, edit/pagination/footer\n    controls, guide grouping, and representative API/data-attribute details.\n11. `pnpm lint`, `pnpm typecheck:docs`, `pnpm build:docs`, `pnpm test:docs`, and\n    the full `pnpm verify` pass.\n\n### In scope\n\n- `docs/app/**`, `docs/content/{en,zh}/**`, and documentation-only styles/assets.\n- Shared documentation demo/source/API components.\n- Documentation route, content-inventory, and visual-parity verification scripts\n  and tests.\n- Documentation of the parity matrix and intentionally retained modern behavior.\n- Test fixtures/baselines that are deterministic and checked into the repository.\n\n### Out of scope\n\n- Reintroducing IslandJS, NextUI, or `react-live`.\n- Reverting React 19, Tailwind CSS 4, Tone.js 15, accessibility, lifecycle,\n  error-handling, or real Web Audio improvements.\n- Changing the shipped Echo UI component/hook runtime or public package API solely\n  to make the documentation resemble the legacy site.\n- New production dependencies, release/version changes, or unrelated refactors.\n\n### Pre-agreed TDD seams\n\n1. First make content-inventory tests fail for root behavior, navigation links,\n   Guide/About grouping, footer/edit/pagination controls, both locales, variant\n   labels/counts, source affordances, and representative data attributes/API rows.\n2. Add or revise deterministic visual-parity assertions so they fail against the\n   current Nextra shell before changing shell styles or structure.\n3. Implement the smallest shared demo/source model that can express all required\n   variants, adding targeted tests for each controller/display category before\n   populating page content.\n4. Keep modern audio-demo behavior covered while extending Preview/Code; source\n   disclosure and copy controls must be keyboard-accessible.\n5. Run the closest targeted Vitest/Node check after each seam and\n   `pnpm typecheck:docs` regularly.\n\n### Required targeted checks\n\n- Targeted Vitest tests for docs route/content inventory.\n- Targeted Node checks for Nextra output and visual-parity baselines.\n- `pnpm lint`\n- `pnpm typecheck:docs`\n- `pnpm build:docs`\n- `pnpm test:docs`\n- `pnpm verify` as the final implementation check.\n\n### Required UI evidence\n\nStore before/after evidence under\n`screen-shots/20260724T132107Z-issue-108-743034/` with an index that maps each\ncapture to its route, locale, theme, viewport, and acceptance criterion.\n\n- Viewports: 1440×900 and 390×844.\n- Locales/themes: English and Chinese, light and dark.\n- Routes: home, `/guide/introduction`, `/guide/about`, `/component/button`,\n  `/component/knob`, `/component/spectrogram`, and `/hook/usePlayer`.\n- Interaction evidence: desktop Links menu, mobile navigation, locale/theme\n  switching, previous/next navigation, edit link, Preview/Code switching, source\n  copy action, and at least one real-audio demo state.\n- Include focused before/after comparisons for representative home, guide,\n  controller, visualization, and Hook pages. The evidence index may use a\n  documented representative matrix instead of duplicating every unchanged\n  combination, but all locale/theme/viewport combinations must be exercised by a\n  deterministic check.\n- Record keyboard/focus and reduced-motion observations for new interactive UI.\n\n### Risks and owner-confirmation boundaries\n\n- The owner has explicitly approved the issue's >400-line implementation budget.\n- Stop for owner confirmation before adding a dependency, changing a shipped\n  package API/runtime, changing release metadata, weakening accessibility or\n  security behavior, or approving an intentional parity exception not already\n  stated above.\n- Treat the live Island site as the visual/content reference and the current\n  package implementation/types as the source of truth for modern API facts.\n- Prefer shared data-driven documentation structures over duplicating large\n  locale-specific React implementations.\n\n### Stop conditions\n\n- A requirement conflicts with the current public runtime/API and cannot be\n  resolved as documentation-only work.\n- A required Island reference/baseline cannot be captured deterministically.\n- An in-scope check fails twice for causes outside the issue's changes.\n- Work would require a new dependency, release change, security-sensitive change,\n  or product/API decision.\n- The implementation is complete and committed.\n\nStop after committing. Do not push, create a PR, or merge.\n","events":[{"schemaVersion":1,"runId":"20260724T132107Z-issue-108-743034","type":"loop_started","timestamp":"2026-07-24T13:21:07.375Z","status":"running","payload":{"issueNumber":108,"branch":"codex/issue-108"}},{"schemaVersion":1,"runId":"20260724T132107Z-issue-108-743034","type":"brief_frozen","timestamp":"2026-07-24T13:28:52.219Z","status":"frozen","payload":{"briefDigest":"3cfea23d657797a80267c52400c3844b534417a8ecdf26620174af40dbaf0ed6","uiEvidenceRequired":true}},{"schemaVersion":1,"runId":"20260724T132107Z-issue-108-743034","type":"implementation_completed","timestamp":"2026-07-24T16:40:25.437Z","status":"passed","payload":{"agent":"$implement","invocationId":"978de939-8586-4fa8-aaa2-1a49db3d1048","startedAt":"2026-07-24T13:30:00.000Z","finishedAt":"2026-07-24T16:33:52.000Z","briefDigest":"3cfea23d657797a80267c52400c3844b534417a8ecdf26620174af40dbaf0ed6","commitSha":"b15cded4fb9fa319bb35e56a70a4401cbf1d0e33","resultPath":"logs/runs/20260724T132107Z-issue-108-743034/implementation-result-1.json","resultDigest":"0d4088340043de67edd52951fa8a513ef8d0a349a98ac5f7365ffd0b667781df"}},{"schemaVersion":1,"runId":"20260724T132107Z-issue-108-743034","type":"pr_published","timestamp":"2026-07-24T19:56:18.346Z","status":"draft","payload":{"prUrl":"https://github.com/codeacme17/echo-ui/pull/111","headSha":"8ddb38818164f6b0b0d77b236c0dd3fb6cf2a626","baseBranch":"dev","branch":"codex/issue-108"}},{"schemaVersion":1,"runId":"20260724T132107Z-issue-108-743034","type":"implementation_completed","timestamp":"2026-07-24T20:48:32.983Z","status":"passed","payload":{"agent":"$implement","invocationId":"aa574e93-b8da-438e-8229-a3fcf0168d22","startedAt":"2026-07-24T19:48:00.000Z","finishedAt":"2026-07-24T20:47:00.000Z","briefDigest":"3cfea23d657797a80267c52400c3844b534417a8ecdf26620174af40dbaf0ed6","commitSha":"4b9818f7c2a77f4dea87c4eceb188bd41facb367","resultPath":"logs/runs/20260724T132107Z-issue-108-743034/implementation-result-2.json","resultDigest":"4393b4c12f4bb52985fd5299ab223b8a95bf6aad7836fbc2b17c15e1edd5f95b"}},{"schemaVersion":1,"runId":"20260724T132107Z-issue-108-743034","type":"pr_published","timestamp":"2026-07-25T07:43:34.309Z","status":"draft","payload":{"prUrl":"https://github.com/codeacme17/echo-ui/pull/111","headSha":"c5100509fb33fc68ff36089c92cfb43c2ab22424","baseBranch":"dev","branch":"codex/issue-108"}}],"artifacts":[{"path":"logs/runs/20260724T132107Z-issue-108-743034/implementation-result-1.json","sha256":"0d4088340043de67edd52951fa8a513ef8d0a349a98ac5f7365ffd0b667781df","source":"{\n  \"schemaVersion\": 1,\n  \"runId\": \"20260724T132107Z-issue-108-743034\",\n  \"agent\": \"$implement\",\n  \"invocationId\": \"978de939-8586-4fa8-aaa2-1a49db3d1048\",\n  \"startedAt\": \"2026-07-24T13:30:00.000Z\",\n  \"finishedAt\": \"2026-07-24T16:33:52.000Z\",\n  \"briefDigest\": \"3cfea23d657797a80267c52400c3844b534417a8ecdf26620174af40dbaf0ed6\",\n  \"commitSha\": \"b15cded4fb9fa319bb35e56a70a4401cbf1d0e33\",\n  \"checks\": [\n    {\n      \"command\": \"pnpm vitest run tests/docs-parity.test.ts tests/docs-example-frame.test.tsx tests/docs-route-inventory.test.ts\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"node scripts/verify-nextra-output.mjs\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"node scripts/verify-docs-ui.mjs\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"node scripts/capture-docs-evidence.mjs\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm lint\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm typecheck:docs\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm build:docs\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm test:docs\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm verify\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Targeted Vitest tests for docs route/content inventory.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Targeted Node checks for Nextra output and visual-parity baselines.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm verify as the final implementation check.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"### Required UI evidence\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Store before/after evidence under\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"screen-shots/20260724T132107Z-issue-108-743034/ with an index that maps each\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"capture to its route, locale, theme, viewport, and acceptance criterion.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Viewports: 1440×900 and 390×844.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Locales/themes: English and Chinese, light and dark.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Routes: home, /guide/introduction, /guide/about, /component/button,\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"/component/knob, /component/spectrogram, and /hook/usePlayer.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Interaction evidence: desktop Links menu, mobile navigation, locale/theme\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"switching, previous/next navigation, edit link, Preview/Code switching, source\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"copy action, and at least one real-audio demo state.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Include focused before/after comparisons for representative home, guide,\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"controller, visualization, and Hook pages. The evidence index may use a\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"documented representative matrix instead of duplicating every unchanged\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"combination, but all locale/theme/viewport combinations must be exercised by a\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"deterministic check.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Record keyboard/focus and reduced-motion observations for new interactive UI.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"### Risks and owner-confirmation boundaries\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"The owner has explicitly approved the issue's >400-line implementation budget.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Stop for owner confirmation before adding a dependency, changing a shipped\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"package API/runtime, changing release metadata, weakening accessibility or\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"security behavior, or approving an intentional parity exception not already\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"stated above.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Treat the live Island site as the visual/content reference and the current\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"package implementation/types as the source of truth for modern API facts.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Prefer shared data-driven documentation structures over duplicating large\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"locale-specific React implementations.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"### Stop conditions\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"A requirement conflicts with the current public runtime/API and cannot be\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"resolved as documentation-only work.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"A required Island reference/baseline cannot be captured deterministically.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"An in-scope check fails twice for causes outside the issue's changes.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Work would require a new dependency, release change, security-sensitive change,\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"or product/API decision.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"The implementation is complete and committed.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Stop after committing. Do not push, create a PR, or merge.\",\n      \"status\": \"passed\"\n    }\n  ]\n}\n"},{"path":"logs/runs/20260724T132107Z-issue-108-743034/implementation-result-2.json","sha256":"4393b4c12f4bb52985fd5299ab223b8a95bf6aad7836fbc2b17c15e1edd5f95b","source":"{\n  \"schemaVersion\": 1,\n  \"runId\": \"20260724T132107Z-issue-108-743034\",\n  \"agent\": \"$implement\",\n  \"invocationId\": \"aa574e93-b8da-438e-8229-a3fcf0168d22\",\n  \"startedAt\": \"2026-07-24T19:48:00.000Z\",\n  \"finishedAt\": \"2026-07-24T20:47:00.000Z\",\n  \"briefDigest\": \"3cfea23d657797a80267c52400c3844b534417a8ecdf26620174af40dbaf0ed6\",\n  \"commitSha\": \"4b9818f7c2a77f4dea87c4eceb188bd41facb367\",\n  \"checks\": [\n    {\n      \"command\": \"pnpm vitest run tests/docs-parity.test.ts tests/docs-visual-contract.test.ts\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm vitest run tests/docs-rendered-visual-contract.test.ts\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm lint\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm typecheck:docs\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm build:docs\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm test:docs\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm verify\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"node loops/issue-dev-loop/scripts/validate-candidate-control-plane.mjs --loop-root loops/issue-dev-loop --run-id 20260724T132107Z-issue-108-743034 --base-sha 9eea05360a90e46a4c66c2e821e9ad5bd6c71c67 --head-sha 4b9818f7c2a77f4dea87c4eceb188bd41facb367\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Screenshot manifest structural validator (24 screenshots, 12 pairs).\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Targeted Vitest tests for docs route/content inventory.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Targeted Node checks for Nextra output and visual-parity baselines.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"pnpm verify as the final implementation check.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"### Required UI evidence\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Store before/after evidence under\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"screen-shots/20260724T132107Z-issue-108-743034/ with an index that maps each\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"capture to its route, locale, theme, viewport, and acceptance criterion.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Viewports: 1440×900 and 390×844.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Locales/themes: English and Chinese, light and dark.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Routes: home, /guide/introduction, /guide/about, /component/button,\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"/component/knob, /component/spectrogram, and /hook/usePlayer.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Interaction evidence: desktop Links menu, mobile navigation, locale/theme\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"switching, previous/next navigation, edit link, Preview/Code switching, source\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"copy action, and at least one real-audio demo state.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Include focused before/after comparisons for representative home, guide,\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"controller, visualization, and Hook pages. The evidence index may use a\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"documented representative matrix instead of duplicating every unchanged\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"combination, but all locale/theme/viewport combinations must be exercised by a\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"deterministic check.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Record keyboard/focus and reduced-motion observations for new interactive UI.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"### Risks and owner-confirmation boundaries\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"The owner has explicitly approved the issue's >400-line implementation budget.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Stop for owner confirmation before adding a dependency, changing a shipped\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"package API/runtime, changing release metadata, weakening accessibility or\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"security behavior, or approving an intentional parity exception not already\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"stated above.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Treat the live Island site as the visual/content reference and the current\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"package implementation/types as the source of truth for modern API facts.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Prefer shared data-driven documentation structures over duplicating large\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"locale-specific React implementations.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"### Stop conditions\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"A requirement conflicts with the current public runtime/API and cannot be\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"resolved as documentation-only work.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"A required Island reference/baseline cannot be captured deterministically.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"An in-scope check fails twice for causes outside the issue's changes.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Work would require a new dependency, release change, security-sensitive change,\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"or product/API decision.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"The implementation is complete and committed.\",\n      \"status\": \"passed\"\n    },\n    {\n      \"command\": \"Stop after committing. Do not push, create a PR, or merge.\",\n      \"status\": \"passed\"\n    }\n  ]\n}\n"}],"updatedAt":"2026-07-25T07:43:34.309Z"}

[codeacme17]

{"schemaVersion":1,"kind":"control-plane-bootstrap","authorizationId":"BST-20260727-PR124-REVIEW-FIX","repository":"codeacme17/echo-ui","branch":"codex/bootstrap-trusted-verifier-sync","baseSha":"c0972f48451bdf0f0ce3918a1d73cd451429719c","headSha":"e412fde0191d27f57dd7b4c989912de245b2b70a","authorizedActor":"Ethandasw","purpose":"Authorize Ethandasw to publish the reviewed PR 124 bootstrap repair head.","expiresAt":"2026-07-27T18:23:58.867Z"}

[codeacme17]

{"schemaVersion":1,"kind":"control-plane-bootstrap","authorizationId":"BST-20260727-PR124-FINAL-REPAIR","repository":"codeacme17/echo-ui","branch":"codex/bootstrap-trusted-verifier-sync","baseSha":"c0972f48451bdf0f0ce3918a1d73cd451429719c","headSha":"66fc518dad9d16f7595210116363021cefdc4781","authorizedActor":"Ethandasw","purpose":"Authorize Ethandasw to publish the final reviewed PR 124 bootstrap repair head.","expiresAt":"2026-07-27T18:52:40.804Z"}

[codeacme17]

{"schemaVersion":1,"kind":"control-plane-bootstrap","authorizationId":"BST-LEGACY-BRIEF-20260803-4554B66","repository":"codeacme17/echo-ui","branch":"codex/bootstrap-legacy-brief-compat","baseSha":"9eb629c1b24ded82dc3b84c71906406cdc66ab5f","headSha":"4554b666bbe27f976b74edff7923f07a6b079382","authorizedActor":"Ethandasw","purpose":"Allow durable pre-marker frozen briefs to resume without weakening new freeze validation","expiresAt":"2026-08-04T08:49:43.157Z"}

[codeacme17]

{"schemaVersion":1,"kind":"control-plane-bootstrap","authorizationId":"BST-LEGACY-BRIEF-P1-20260803-228A7BD","repository":"codeacme17/echo-ui","branch":"codex/bootstrap-legacy-brief-compat","baseSha":"9eb629c1b24ded82dc3b84c71906406cdc66ab5f","headSha":"228a7bd33023d4e3bf3ac280a2132ef406a30ae8","authorizedActor":"Ethandasw","purpose":"Close Traviinam P1 findings by binding legacy brief selection to the frozen issue boundary","expiresAt":"2026-08-04T10:18:33.318Z"}