PaperClipAI/maps/storybook-map/REVIEW.md

Initial Storybook review — 2026-10-12

Source baseline: f0e12c851971a21f7aadf0835b016bfaf2067314. Scope: complete source inventory and initial classification, with targeted source comparison and browser checks. This is not full state parity, full interaction coverage, or production acceptance for all stories.

Inventory and organization

There is one Storybook, already centralized under ui/storybook/. At the initial baseline, its 223 story files were split between 176 files at the stories root and 47 nested files, with 51 top-level sidebar groups. The initial pass recorded product meaning, provenance, and review status before changing that organization. The follow-up organization pass below moves the files and sidebar together.

The downstream catalog gives each file a primary feature home and related stable capability IDs. The generated index includes all 171 upstream capabilities across 35 feature areas. The existing Overview story now provides searchable feature navigation into the actual built story index. The initial pass kept sidebar titles stable; the follow-up uses explicit IDs to preserve links while changing titles.

Dimension	Initial classification
Product alignment	18 current subjects, 4 proposals, 5 historical suites, 8 mixed suites, 188 requiring deeper parity review
Rendered subject	199 production, 8 prototype, 11 mixed, 5 guides
Data boundary	217 fixture-based, 1 separate fixture server, 5 static guides

A production subject can have unreviewed state parity. A current subject can still have untested loading, error, permission, or backend behavior. The catalog's notes and source references qualify these labels; none are a substitute for live proof.

Corrections and retained history

• Question dismissal and send: the local interaction-above-composer harness kept a pending badge for dismissed questions and left the question open after a normal send. Production TaskChatThread excludes questions from pendingReminderInputs and dismisses the selected question on send. The harness now matches those rules. Added question-dismiss and confirmation-reopen cases; corrected the send case's stale editor selector. The story still does not prove persisted dismissal or history behavior.
• Fast response helpers: empty, configured, and result were exported fixtures which Storybook also treated as stories. Their IDs collided with Empty, Configured, and Result. Explicit exclusion removes the false exports while retaining the real stories and imported fixtures. Browser review also exposed a missing explicit onConnectionChange spy after the production view began calling it on mount; added that fixture callback.
• Chat provenance: the main chat wrapper combines production conversation/task pages with a local landing view. The separate first-created-agent chat-entry design is historical; current primary-agent examples are its replacement.
• Historical designs retained: GitHub chat, old agent onboarding, connect-model tiles, paused composer, and chat-entry remain available with their purpose and replacement references. Local proposals are labeled rather than deleted.
• Prototype folder is not a verdict: some files re-export production subjects; others implement local compositions. Static import traversal found no obvious orphan prototype TS/TSX module. This is not proof that each is still useful.
• Contributor guidance: replaced the old Overview's manual coverage claims, corrected the interaction-authoring skill's obsolete story path, and updated the prototype README's catalog source count to match the shipped five sources.

Verification

Environment: local macOS, headless Chromium, built Storybook 10.6.0, fixture data. The following nine play cases reached Storybook's storyFinished: success event without a browser page exception. These results establish story interactions only.

Story ID	Subject / assertion
composer-interaction-above-composer--ask-user-questions-and-send	Production card/composer in local harness; normal send dismisses question without a pending badge
composer-interaction-above-composer--dismiss-question-without-pending-badge	Production card/composer; dismiss leaves editable composer without pending badge
composer-interaction-above-composer--dismiss-confirmation-keeps-pending-badge	Production card/composer; dismiss retains confirmation badge and reopening works
composer-new-task--empty	Production composer wrapper; existing play assertions
design-explorations-agent-chat-sidebar-components--add-and-reopen-chat	Production sidebar; fixture add/reopen assertions
assistant-connections-consent--choose-organization	Production consent surface; fixture organization selection assertions
historical-github-chat-prototypes--standard-trust-warning	Historical prototype; existing trust-warning assertions, not current GitHub acceptance
design-previews-recovery-notice--retry-request-failed	Production recovery notice; fixture failure-state assertions
composer-mobile-assignee-picker--picker-open	Production picker; existing open-picker assertions

Additional manual browser checks passed: search the guide for steering/queue, follow its link to the real queued-message story, dismiss a question, then reload and verify that the fixture resets to an open question. Screenshots were inspected locally and are not committed as new regression baselines.

Built-index comparison: all 2,208 prior story IDs remain; only the two new dismissal regressions were added (2,210 total). Catalog validation, eight checker tests, feature-map validation, both skill validators, token gates, workspace typecheck, and workspace build passed. Fast-response settings empty, configured, and result subsequently reached storyFinished: success with no page exceptions following the explicit callback fix. These three cases are render checks, not save or backend-persistence tests. The UI Vitest project passed all 8,176 tests in 728 files. The full pnpm test:run reported a 15-second timeout in the unchanged backend case connects advertised Workspace gmail.read without mutating definitions in authenticated. That exact case passed standalone without changing expectations or timeouts. The remaining broad run was stopped after this failure; a complete repository suite pass is not established.

Automated review found missing directly rendered subjects in the initial dependency list. Expanded the catalog across affected suites, including relative production imports, all direct non-primitive subjects in local wrappers, and the primitives that foundation stories demonstrate. Explanatory review guides keep their separate guide classification. This records change detection, not new parity acceptance. Added a real CSF parser regression for nested discovery, include/exclude rules, stable explicit IDs, and play counts.

Feature organization follow-up — 2026-10-12

Source baseline: 75bd3c977cd828d5222823850339e8204f40eb47 (parent PR #16046). The 223 story files now live under their primary feature area in ui/storybook/stories/. The sidebar uses the feature map's section and feature labels in map order. Existing scenario groups remain below those labels. Overview and shared Foundations have dedicated homes. Areas without stories do not get empty sidebar groups; their gaps remain visible in the catalog.

Nineteen supporting files moved to ui/storybook/support/, including fixtures, shared wrappers, guide READMEs, an HTML fixture, and a fixture test. Relative imports, active documentation, catalog sources, and replacement references follow the moves. Classification and review scope did not change. The upstream feature map and its skill are unchanged.

Every suite now has an explicit meta ID, recorded as stableId in the catalog. The built index comparison preserved all 2,210 story IDs, the single docs ID, and all entry names. No story was removed or added. Catalog validation checks primary feature folders, sidebar prefixes, and stable meta IDs; its nine tests passed.

The Storybook build, UI typecheck, all 8,176 UI tests in 728 files, token gates, map checks, and the maintenance-skill validator passed. A source comparison found only changed meta titles/IDs, rebased relative references, and updated fixture path text in story files. The full repository suite was not repeated for these file moves; the prior full-suite limitation above still applies.

Local Chromium verified the sidebar's section/feature order, rendered the guide, searched steering/queue, and followed its link to the unchanged composer-steering-and-queued-messages--queued-while-running ID. The nine play cases listed above and fast-responses-01-settings--empty all reached storyFinished: success without page exceptions after relocation. This is a sample of interactions and rendering, not execution of all 2,210 stories. The fixture-server story and visual-baseline comparisons remain untested for the reasons below. The owned static preview was left running for the requested test-drive.

Remaining review work

1. Review the 188 unreviewed suites by capability and production subject. Compare state transitions, payloads, errors, gates, and reset behavior before promoting a suite. Start with large route wrappers and shared fixture dependencies.
2. Shared preview mocks can fall through to the original fetch; some route harnesses return empty arrays for unmatched APIs. These can hide missing fixtures. Audit affected endpoints per feature rather than treating a render as API coverage.
3. The managed-accounts test-drive story needs the separately owned local API/DB fixture at port 4310. Its upstream providers are simulated. It was not exercised against an unknown existing service.
4. Screenshot comparison is blocked: the existing baseline manifest has zero snapshots and no published archive. Keep using the established Linux baseline workflow when its baseline is published. Do not bless new baselines as part of catalog cleanup.
5. Review fingerprints track declared sources, including feature recipes and local support; they do not traverse every production dependency. Add missing subjects when a review discovers them. Shared setup changes require reviewing callers.

Use maintain-storybook to correct drift and review-storybook to record separate source, render, interaction, visual-comparison, and production evidence. Both skills consume the feature map; neither changes its upstream contract.

Native runtime prerequisite: scoped source follow-up — 2026-10-12

Source comparison: 9f59ff36cf2da963709ca19c06ab005510c835a6 against actual master 4b958ecbd8f33a7782fe6f29ec825f80f636b833. The reviewed maps/feature-map/runs-adapters.md bytes have SHA-256 ca5aff86608b7d7987dc0ee814475a7b93e3faff1f99ce090429d2e932b7e16b.

Twenty-one entries in Runs, harnesses, and model accounts and Task creation and lifecycle had review-fingerprint drift. Their 117 unique declared sources have one changed input: the runs-adapters feature recipe. All 21 story files and the other 116 declared production subjects, wrappers and fixture sources are unchanged from master. The recipe adds bounded native startup and registration retirement controls. It separates those provider-free controls from real daemon and installed-provider proof; it changes no represented UI or fixture contract.

Refreshed only those 21 reviewed fingerprints. No story, fixture, export, stable ID, title, capability reference or product/implementation/data classification changed. Existing mixed and unreviewed parity limitations remain. No fixture correction is needed for this scoped prerequisite; this does not establish full state parity for the affected suites.

This follow-up is source inspection only. Rendering, play assertions, visual comparisons and production provider acceptance were not run. Native lifecycle behavior remains with the linked transport controls and their existing hosted CI fixtures. Catalog validation proves structure and reviewed dependency hashes, not that these live journeys passed.