feat(app): widget settings view — rail, scheme tiles, scope menu (#572 part 3)

[omridevk]

Stacked on #592 (issue-572-settings-foundation-v2). This branch is rebased onto that PR's head and contains only the widget settings UI; review #592 first, and merge it first.

Part 3 of #572: the widget settings view. A nested settings route under the panel with a trace-rail section nav, an appearance section whose scheme preview tiles apply instantly, and a provenance badge that doubles as the scope menu. SegmentGroup lands in @conciv/ui-kit-system as an Ark segment group whose indicator slides between segments, plus a switch thumb that actually travels; both snap under reduced motion.

Adaptation to the #592 contract

The branch was originally written against the closed #574 (sqlite) foundation. The rebase dropped that foundation commit wholesale and replayed the UI work onto #592, so nothing server-side or contract-side comes from this branch any more. What changed in the UI to meet the shipped contract:

One read. settings.get returns the effective value, the controlling layer, each layer's raw value and validity, and each layer's revision. The scope badge used to open a second history query to decide whether a global value existed; it now reads layers.global.state from the same read. There is no inspect call and no reference to the old audit name. One read replaces two.

Key namespaced. scheme is appearance.scheme, and the fallback is read from the registry entry rather than hardcoded.

New shapes. SettingsRead / SettingsKeyView replace ResolvedSetting[], so the optimistic cache update rewrites the key view rather than a flat row array. The optimistic value and source are computed by the same project ?? global ?? default rule the server uses, applied to the layers the write is about to produce, instead of three hand-written expected states.

Ordinary edits always write the project layer. Previously the write followed provenance, so editing a globally-scoped value silently rewrote the global layer for every project. Now a value inherited from the global layer moves to this project when you change it: the badge flips GLOBAL to PROJECT, the footer reads "Changes save automatically to this project.", the announcement says the global setting still applies elsewhere, and the badge menu offers "Use global value" to go back. The global value is left intact.

Apply-to-all is one server call. The branch composed a global set plus a project clear client-side. It now calls settings.applyGlobally, which does both under one lock, one opId and one settings-changed event. Covered by a test that counts the wire calls.

Every write carries its expected revision, read from get's layers[scope].revision. A REVISION_CONFLICT reloads the settings and surfaces a non-blocking inline message rather than retrying over whatever the other writer stored. LAYER_UNPARSEABLE says the file has a syntax error and offers no retry until it is fixed; LOCK_TIMEOUT and the value/key errors get their own copy. Live-region announcements are worded separately from the inline copy so both surfaces are independently assertable.

Event payload. The settings-changed listener keys on the event name only and invalidates the settings query, which is idempotent, so the {opId, keys, scopes} payload change needed no listener change.

Test plumbing. bootCoreKit / bootEmbedKit forward globalSettingsDir, matching createApp's actual option name (the branch passed globalStateDir, which createApp does not accept).

No visual change: layout, rail geometry, motion, spacing and tokens are exactly as approved.

Tests

13 integration tests in packages/embed/tests/e2e/settings-panel.it.test.ts, against the prebuilt embed and a real server writing real files in temp dirs. Three are new for the contract deltas above:

• an edit while the value comes from the global layer moves the setting to this project (and the global value survives, proven by "Use global value" still being offered)
• applying to all projects goes through one server call, not a set plus a clear
• a stale revision surfaces a conflict the user can retry, and never clobbers the stored value

The conflict test does not stub anything: it rewrites the outgoing request's expectedRevision at the network boundary so the real server returns a real 409.

TDD, batched. The three tests were written first and run once against the un-adapted branch: 3 failed for their own reasons (badge read GLOBAL where PROJECT was expected; zero applyGlobally calls; no conflict message), 10 passed. After the fix, 13/13. Revert-check: with only the behavioral source reverted and the tests untouched, the same 3 failed again and the other 10 stayed green.

Gates

• TURBO_CONCURRENCY=70% pnpm turbo run typecheck --filter=@conciv/app --filter=@conciv/embed --filter=@conciv/extension-testkit --filter=@conciv/ui-kit-system --filter=@conciv/client - pass (36/36)
• TURBO_CONCURRENCY=1 VITEST_MAX_FORKS=1 pnpm turbo run test --concurrency=1 --filter=@conciv/app --filter=@conciv/ui-kit-system --filter=@conciv/client --filter=@conciv/extension-testkit - pass (324 tests)
• TURBO_CONCURRENCY=1 VITEST_MAX_FORKS=1 pnpm turbo run test --concurrency=1 --filter=@conciv/embed - pass (22 unit, 146 integration)
• pnpm lint - pass (0 errors)
• pnpm format:check - pass
• pnpm exec fallow audit --changed-since origin/issue-572-settings-foundation-v2 --format json - verdict pass, 0 introduced
• pnpm exec conciv-publish check-changesets --require-coverage --base origin/issue-572-settings-foundation-v2 - pass

Flagged

Resetting to the default when both layers hold a value still sends two clear calls, one per layer. Resolved (delta 15). #592 landed a settings.reset({key, expectedRevisions}) op mirroring applyGlobally. Reset now goes through that single call instead of a per-scope clear loop, covered by a test that counts the wire calls (one settings.reset, zero clear).

The panel does not surface layers[scope].path, format, parseError or the both-files-present warning. Nothing in the frozen design has a place for a file path, and adding one is a visual change. The unparseable-file case does reach the user through the write error copy.

Part 3 of #572.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 5fb61584-0b70-45f0-ab11-27fde02ac4bf

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[omridevk]

New commit: settings nested under the session route (chat stays mounted, back is instant with no refetch flash), enter/exit view motion, horizontal rail underline fixed and tab row redesigned, SOON chips on disabled sections, nav rail scales with panel width, and scheme writes serialize with fresh revisions (fixes the applyGlobally-then-edit 409 race). All verified live in the browser; gates green: 201 app + 22 embed unit + 149 e2e, lint, format, fallow 0 introduced.