From c3edcab0f5d3393ebedb564087cdcd3e238e7ca2 Mon Sep 17 00:00:00 2001 From: rohan Date: Tue, 29 Sep 2026 20:09:34 +0530 Subject: [PATCH] docs: record home launcher and preference ownership decision --- CONTEXT.md | 2 ++ ...e-presentation-as-pinned-reduced-vendor.md | 5 +-- ...-catalog-and-apply-themes-independently.md | 21 +++++++++++ docs/agents/topology.md | 36 ++++++++++--------- 4 files changed, 45 insertions(+), 19 deletions(-) create mode 100644 docs/adr/0037-own-saved-presentation-preferences-in-catalog-and-apply-themes-independently.md diff --git a/CONTEXT.md b/CONTEXT.md index 073b5c66..a4463937 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -65,6 +65,8 @@ cluster that matches the task, followed by its related ADRs when the task needs - **Renderer Port** — the Secant-owned Interface around the terminal renderer, covering lifecycle only: size, key input, resize, and teardown. It exists so the whole shell lifecycle is exercisable against a fake with no terminal, and it carries the teardown ordering the legacy Windows console host requires. See [ADR 0018](./docs/adr/0018-adopt-opencode-presentation-as-pinned-reduced-vendor.md). +- **Preferences** — saved presentation choices shared across **Workspaces** within one Secant home: the theme and its dark or light appearance. + They determine a TUI's initial appearance; its active appearance can differ during a preview or after an unsuccessful save. ### Secant clusters diff --git a/docs/adr/0018-adopt-opencode-presentation-as-pinned-reduced-vendor.md b/docs/adr/0018-adopt-opencode-presentation-as-pinned-reduced-vendor.md index dee99707..11c5f121 100644 --- a/docs/adr/0018-adopt-opencode-presentation-as-pinned-reduced-vendor.md +++ b/docs/adr/0018-adopt-opencode-presentation-as-pinned-reduced-vendor.md @@ -103,8 +103,9 @@ this ADR already drops — Cursor, Vercel, GitHub, Material, and Monokai — it generic community palettes: `opencode`, `orng`, and `lucent-orng` (OpenCode's signature theme and its two orange house palettes). Shipping a theme that carries the upstream tool's own identity inside Crucible raises the same naming question the product-named five did, so the same answer applies. That leaves 25 of the 33 upstream theme assets shipped, each attributed by one line in `THIRD-PARTY-NOTICES.md`. Because the default OpenCode theme was -among the drops, Crucible's shipped default is `nord` — a widely-known MIT community palette — and there is no theme picker and no persisted preference -yet. +among the drops, Crucible initially shipped `nord` with no picker or persisted preference. Amended 2026-09-29: [ADR 0036](./0036-the-run-workbench-mirrors-the-agent.md) +chooses everforest as the default, and [ADR 0037](./0037-own-saved-presentation-preferences-in-catalog-and-apply-themes-independently.md) adds the picker, +dark and light appearance, and persisted Preferences. ## Amendment (ADR 0030): runtime resolved, legacy conhost dropped diff --git a/docs/adr/0037-own-saved-presentation-preferences-in-catalog-and-apply-themes-independently.md b/docs/adr/0037-own-saved-presentation-preferences-in-catalog-and-apply-themes-independently.md new file mode 100644 index 00000000..2281b965 --- /dev/null +++ b/docs/adr/0037-own-saved-presentation-preferences-in-catalog-and-apply-themes-independently.md @@ -0,0 +1,21 @@ +# Own Saved Presentation Preferences in Catalog and Apply Themes Independently + +Secant adds saved **Preferences** for theme and dark or light appearance, shared across Workspaces within one Secant home. The human confirmed the +home launcher, theme picker, and headless settings behavior on +[Decide what the home screen offers: commands and settings](https://github.com/secantdev/secant/issues/246); that ticket holds the UX decision. + +Application owns preference reads and changes through the existing Projection Port, and Catalog owns their persistence in `catalog.db`. Composition +supplies the resolved Secant home. Catalog already stores home-wide Workspace approvals, so extending that owner keeps transaction ordering, +validation, and failure translation in one place without introducing another storage system or allowing presentation to own durable files. This +extends [ADR 0025](./0025-organize-target-code-around-owned-deep-modules.md)'s Catalog responsibility. TUI and headless settings use the same +Application Interface; the TUI command catalog, search, focus, theme assets, and rendering remain presentation concerns. + +Applying an appearance is independent of saving Preferences. TUI preview and confirmed appearance are local presentation state; successful saves +change the durable Preferences. A failed save reports that the choice was not saved and leaves the chosen appearance active. Missing or unsupported +preference values use everforest and dark appearance; a preference read failure reports a notice and uses those defaults, while a failure affecting +the whole Catalog retains its existing handling. Updates preserve unrelated preferences atomically, with the latest committed change winning for +the same preference. Other running instances adopt saved changes on their next launch; cross-process live synchronization is outside this decision. + +The defaults are everforest, as decided in [ADR 0036](./0036-the-run-workbench-mirrors-the-agent.md), and dark appearance. The picker uses the 25 +existing vendored themes and their existing dark and light palettes. This supersedes ADR 0018's initial fixed-theme, no-picker, no-persistence choice; +its vendor and attribution rules remain in force. Custom theme files, automatic terminal-mode detection, and animation or mouse settings are deferred. diff --git a/docs/agents/topology.md b/docs/agents/topology.md index 9211ce30..fe3ddda0 100644 --- a/docs/agents/topology.md +++ b/docs/agents/topology.md @@ -8,23 +8,23 @@ The [Module design](./module-design.md), [dependency](./dependencies.md), and [t One ESM package contains these ownership areas. Every path exists; new files land under the area that owns their behavior, never in a new one. -| Source area | Responsibility | -| -------------------------- | -------------------------------------------------------------------------------------------------------------- | -| `src/cli/` | CLI hosting and dispatch to the selected client; one executable entry | -| `src/composition/` | Outermost construction, configuration wiring, and lifecycle wiring | -| `src/application/` | Projection Port, separate Bundle-management Interface, Preflight, launch, and cross-domain coordination | -| `src/workflow/` | Execution-free Routing composition, static Step-kind contracts, and their authored value vocabulary | -| `src/bundle/` | Non-executing archive validation/build, Bundle Asset capture, and managed Bundle bytes | -| `src/catalog/` | `catalog.db`, installation lifetime, Trust grants and their Operation receipts, replaceable Run index | -| `src/drizzle/` | Generated per-database SQL migrations and the embedded ordered migration journals | -| `src/run/execution/` | Run lifecycle policy, uniform scheduling/retries, and private executable Step kinds | -| `src/run/store/` | Run creation/deletion, Workspace coordination and fencing, `run.db`, canonical records, and atomic publication | -| `src/run/store/artifacts/` | Private Run Artifact capture, Git staging/history, and verified Workspace materialization | -| `src/process/` | Owned child process: PATH-walk executable resolution, Windows shim resolution, direct spawn, tree-reaping kill | -| `src/harness/` | Secant's Harness Interface, discovery/qualification, and private native Adapters | -| `src/tui/` | Secant presentation plus the reduced OpenCode-derived presentation subset | -| `src/tui/renderer/` | Renderer Port lifecycle and terminal teardown ordering | -| `src/headless/` | Headless client, including Bundle-management commands | +| Source area | Responsibility | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | +| `src/cli/` | CLI hosting and dispatch to the selected client; one executable entry | +| `src/composition/` | Outermost construction, configuration wiring, and lifecycle wiring | +| `src/application/` | Projection Port, separate Bundle-management Interface, Preferences use cases, Preflight, launch, and cross-domain coordination | +| `src/workflow/` | Execution-free Routing composition, static Step-kind contracts, and their authored value vocabulary | +| `src/bundle/` | Non-executing archive validation/build, Bundle Asset capture, and managed Bundle bytes | +| `src/catalog/` | `catalog.db`, Preferences persistence, installation lifetime, Trust grants and their Operation receipts, replaceable Run index | +| `src/drizzle/` | Generated per-database SQL migrations and the embedded ordered migration journals | +| `src/run/execution/` | Run lifecycle policy, uniform scheduling/retries, and private executable Step kinds | +| `src/run/store/` | Run creation/deletion, Workspace coordination and fencing, `run.db`, canonical records, and atomic publication | +| `src/run/store/artifacts/` | Private Run Artifact capture, Git staging/history, and verified Workspace materialization | +| `src/process/` | Owned child process: PATH-walk executable resolution, Windows shim resolution, direct spawn, tree-reaping kill | +| `src/harness/` | Secant's Harness Interface, discovery/qualification, and private native Adapters | +| `src/tui/` | Secant presentation plus the reduced OpenCode-derived presentation subset | +| `src/tui/renderer/` | Renderer Port lifecycle and terminal teardown ordering | +| `src/headless/` | Headless client, including Bundle-management commands | `cli/main.ts` and `composition/main.ts` name entrypoints, not single-file implementations. A composition root may span cohesive private wiring files and invoke child composition roots. Only the hosting entrypoint or parent root invokes a root; domain Modules receive dependencies. @@ -40,6 +40,8 @@ An `index.ts` is valid for one cohesive Module after declaring it in that table. - Clients receive Application Interfaces; they import `projection-port.ts` and, for headless Bundle management, `bundle-management.ts`. `application.ts` is the construction surface for composition, not a client shortcut. Client contracts and their `contracts/` subtree remain self-contained; they expose normalized semantic values rather than internal runtime, storage, or Harness objects. +- Preferences cross the Projection Port; Catalog owns their durable storage and the TUI owns active appearance. Read + [ADR 0037](../adr/0037-own-saved-presentation-preferences-in-catalog-and-apply-themes-independently.md) before changing preference ownership or save handling. - Application coordinates the domain Modules through their Interfaces. Bundle and Catalog depend only on the static Workflow vocabulary. Catalog's Run index is advisory; Application uses Run Store authority for lifecycle decisions. - Drizzle owns only generated migration assets and their ordered journal Interface. Catalog and Run Store keep their schemas, queries, SQLite