# Shared Secrets UI Consistency Implementation Plan > **For Codex:** REQUIRED SUB-SKILL: Use `executeplan` to implement this plan task-by-task. **Goal:** Isolate secret-editor targets, make privileged administration accessible and recoverable, and ship one consistent UI to every sister host. **Architecture:** Fix target/draft identity before visual changes, then adopt the reviewed Theme API and shared interaction recipes in the existing Razor library. Preserve metadata-only lists, separate manage/reveal authorization, fail-closed reveal auditing, committed mutation semantics, tombstones and cache invalidation. Domain services remain unchanged; generic modal behavior is only considered for extraction after two real consumer pilots. **Tech Stack:** .NET 10 Razor Class Library, ZB.MOM.WW.Theme, existing ISecretStore/ISecretCipher/IAuditWriter, xUnit 2.9.3, bUnit 2.7.2 after GB (`BunitContext` / `Render`), native DOM dialog/focus APIs when required. --- ## Required testing prerequisite Complete [bUnit standardization](BUnit.md) and close **GB before any task in this chapter**, including local fixes and candidate UI pilots. All bUnit snippets below use the post-GB `BunitContext` / `Render` / `AddAuthorization` API; their inherited helpers must be migrated in GB. Preserve framework HtmlRenderer methods and xUnit runner APIs where used. Non-bUnit runtimes retain their existing harnesses, but their UI work also waits for the family gate. Old package pins are discovery baselines, not targets for this chapter. ## Scope, baseline and dependencies - Cwd for all commands: `/Users/dohertj2/Desktop/scadaproj/ZB.MOM.WW.Secrets`; all task files below are relative to that cwd. - Inputs: `/Users/dohertj2/Desktop/scadaproj/impeccable/Secrets.md`, shared recommendations, master plan and Theme G1 gate. Review source unchanged between review baseline and current umbrella HEAD `d93ca7b`; record actual execution HEAD. - Current library source version: `Directory.Build.props` → `0.6.6`; Theme central pin `Directory.Packages.props` → `0.2.0`. Consumers may resolve higher Theme versions; use restored graphs as truth. - `THEME_VERSION`: actual compatible release after G1. `SECRETS_UI_VERSION`: actual package release selected for these changes after its own compatibility review. Neither string is a version to commit literally. Do not assume `0.6.0` or republish an existing immutable package. - SEC-01 target isolation may proceed after GB closes while Theme G1 is pending. All visual/API adoption tasks depend on G1. Host adoption depends on both chosen packages. - G1 API: additive `TechField.For`, `HintId`, `ErrorId`; callers provide matching control `id`, `aria-describedby`, `aria-invalid`. BusyText/aria-busy are shared; caller live outcome regions must never contain plaintext. Theme status text uses dedicated ink tokens; information-state blue is independent of product accent. - Complete the required bUnit 2.7.2 migration in GB first. Subsequent tasks preserve that validated test stack; backend/storage redesign, real-secret fixtures and real reveals are outside these UI tasks. Run baseline from the stated cwd: ```sh dotnet test tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj ``` Expected PASS; record restore warnings/count. Feed/SDK or existing parser/test-stack failures are baseline blockers, to record in GB; the prescribed 2.7.2 migration and compatibility verification must close before these tasks. New tests below extend the named existing classes and retain their existing usings/helpers. Test data is synthetic. ## SEC-01 · Isolate Add/Rotate targets and pending editor lifetimes **Covers:** review SEC-06; highest priority before aesthetic work. **Depends:** baseline only. **Modify:** `src/ZB.MOM.WW.Secrets.Ui/Components/SecretEditor.razor`; `src/ZB.MOM.WW.Secrets.Ui/Components/SecretsList.razor`; `tests/ZB.MOM.WW.Secrets.Ui.Tests/SecretEditorTests.cs`; `tests/ZB.MOM.WW.Secrets.Ui.Tests/SecretsListTests.cs`; `tests/ZB.MOM.WW.Secrets.Ui.Tests/Fakes/RecordingSecretStore.cs` for optional delayed-call hooks. 1. Add this test inside `SecretEditorTests`, reusing `RegisterServices()`: ```csharp [Fact] public void ChangingRotateTarget_DoesNotReuseAnotherSecretsDraft() { var (store, _, cipher) = RegisterServices(); var a = new SecretName("app/a"); var b = new SecretName("app/b"); store.Seed(cipher.Encrypt(a, "old-a", SecretContentType.Text) with { Description = "A" }); store.Seed(cipher.Encrypt(b, "old-b", SecretContentType.Json) with { Description = "B" }); var auth = this.AddAuthorization(); auth.SetAuthorized("reviewer"); auth.SetPolicies(SecretsAuthorization.ManagePolicy); var cut = Render(p => p.Add(x => x.ExistingName, a)); cut.Find("[data-testid=secret-value]").Change("draft-for-a"); cut.Render(p => p.Add(x => x.ExistingName, b)); cut.WaitForAssertion(() => { Assert.Equal("B", cut.Find("[data-testid=secret-description]").GetAttribute("value")); Assert.Equal("", cut.Find("[data-testid=secret-value]").GetAttribute("value") ?? ""); }); } ``` 2. Run `dotnet test tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj --filter FullyQualifiedName~ChangingRotateTarget_DoesNotReuseAnotherSecretsDraft`; expected FAIL because `_metadataLoaded` and `_value` survive target changes. 3. Track editor identity explicitly (Add vs Rotate + exact secret name). On identity change, increment a generation, cancel the previous metadata read and reset name/description/type/value/error/restore-confirmation/loading flags before loading the new metadata. Apply read results only if generation and identity still match. Capture immutable target identity when submitting. Preserve failed-save drafts only for that identity. The list also keys editor instances by mode/name and tracks its editor generation so a superseded completion cannot close a newer editor. Disable Add/Rotate/Cancel target switching while a committed mutation outcome is pending; explain pending state instead of claiming cancellation rolled back a write. 4. Add tests for Rotate→Add; same-target rerender preserving unsaved text; delayed A metadata completing after B; parent row A→B switching; cancellation during pending write; and stale `OnSaved` not closing a new editor. Add optional `GetOverride`/`UpsertOverride` delegates to the recording fake for TaskCompletionSource-controlled delay rather than sleeping. Run `dotnet test tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj --filter "FullyQualifiedName~SecretEditor|FullyQualifiedName~SecretsList|FullyQualifiedName~AuditFailureAfterCommit"`; expected PASS and existing audit/cache semantics unchanged. 5. Stage only the five named files; commit `fix(secrets-ui): isolate drafts and pending operations by editor target`. ## SEC-02 · Adopt the shared Theme field and state API **Covers:** SEC-01; DS-01/02/04/06. **Depends:** SEC-01 + G1. **Modify:** `Directory.Packages.props`; `src/ZB.MOM.WW.Secrets.Ui/Components/SecretEditor.razor`; `tests/ZB.MOM.WW.Secrets.Ui.Tests/SecretEditorTests.cs`. 1. Add a rendered association regression in `SecretEditorTests`: ```csharp [Fact] public void EveryEditorControl_HasAnAssociatedLabel() { RegisterServices(); var cut = Render(); foreach (var control in cut.FindAll("input:not([type=hidden]),select")) { var id = control.Id; Assert.False(string.IsNullOrWhiteSpace(id)); Assert.NotNull(cut.Find($"label[for='{id}']")); } } ``` 2. Run `dotnet test tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj --filter FullyQualifiedName~EveryEditorControl_HasAnAssociatedLabel`; expected FAIL on absent IDs/associations. 3. Set the actual Theme pin to `THEME_VERSION`. Give each editor instance stable unique control/hint/error IDs, pass `For`, `HintId`, `ErrorId`, and wire child attributes. Include required/name-format hints and field-local errors. New secret value stays a password input with `autocomplete="new-password"`; never prefill stored plaintext. Use BusyText and aria-busy; error/status text uses new semantic ink classes, not signal colors. 4. Add two-instance unique-ID and invalid-name `aria-invalid`/description tests; run the `SecretEditorTests` filter then the whole UI suite. Expected PASS. Browser-verify label activation, correct names and field errors with keyboard/screen reader; never announce new values. Use computed contrast and visual inspection for palette changes, not CSS-string tests. 5. Stage the three named files; commit `fix(secrets-ui): adopt shared field associations and readable states`. ## SEC-03 · Make deletion keyboard accessible inside real hosts **Covers:** SEC-02; DS-04/05. **Depends:** G1 dialog recipe + SEC-01. **Modify:** `src/ZB.MOM.WW.Secrets.Ui/Components/ConfirmDeleteModal.razor`; `src/ZB.MOM.WW.Secrets.Ui/Components/SecretsList.razor`; `tests/ZB.MOM.WW.Secrets.Ui.Tests/ConfirmDeleteModalTests.cs`. **Create if recipe requires DOM enhancement:** `src/ZB.MOM.WW.Secrets.Ui/wwwroot/js/secrets-dialog.js`. 1. Add a regression inside `ConfirmDeleteModalTests` (same registration/auth setup as existing first test): ```csharp [Fact] public void DeleteDialog_HasANameLinkedToTheExactTarget() { Services.AddSingleton(new RecordingSecretStore()); Services.AddSingleton(new CapturingAuditWriter()); var cut = Render(p => p .Add(x => x.Visible, true).Add(x => x.Name, new SecretName("app/a"))); var dialog = cut.Find("[role=dialog]"); var titleId = dialog.GetAttribute("aria-labelledby"); Assert.False(string.IsNullOrWhiteSpace(titleId)); Assert.Contains("app/a", cut.Find($"[id='{titleId}']").TextContent); Assert.Equal("true", dialog.GetAttribute("aria-modal")); } ``` 2. Run `dotnet test tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj --filter FullyQualifiedName~DeleteDialog_HasANameLinkedToTheExactTarget`; expected FAIL on missing association. If DOM module initialization is introduced, add an exact bUnit module stub in test setup before rerunning; do not weaken the existing strict assertion to allow arbitrary browser `confirm`/`alert`. 3. Apply the shared confirmation recipe: unique heading/description association, initial Cancel focus, contained tab order, inert background, safe Escape, focus return to originating row. Retain `.zb-secrets-*` namespace to avoid the documented Bootstrap `.modal{display:none}` collision. Retain awaited busy operation and exact target; after deletion choose next logical row/heading if trigger vanished. DOM handler receives its actual event argument; never use `window.event`. Dispose event listeners and restore any prior inert state. 4. Add cancel-does-not-delete, busy double activation, failed delete retains target and error, and next-focus-target selection tests in the named files. Run the `ConfirmDeleteModalTests` filter and whole UI suite; expected PASS. Browser-test actual focus/Escape/background isolation in two hosts including one Bootstrap host: bUnit markup cannot establish focus containment. 5. Stage only named modified files plus the module if created; commit `fix(secrets-ui): apply accessible confirmation lifecycle`. ## SEC-04 · Separate list loading, commit and refresh outcomes **Covers:** SEC-03; DS-04/05. **Depends:** SEC-01. **Modify:** `src/ZB.MOM.WW.Secrets.Ui/Components/SecretsList.razor`; `tests/ZB.MOM.WW.Secrets.Ui.Tests/SecretsListTests.cs`; `tests/ZB.MOM.WW.Secrets.Ui.Tests/Fakes/RecordingSecretStore.cs`. 1. Extend the recording fake with optional `ListFault` and `ListCalls`; preserve normal behavior when unset. Add a list regression inside `SecretsListTests`: ```csharp [Fact] public void InitialListFailure_IsRetryableAndIsNotAnEmptyInventory() { var store = new RecordingSecretStore { ListFault = new IOException("synthetic outage") }; Services.AddSingleton(store); Services.AddSingleton(new FakeCipher()); Services.AddSingleton(new CapturingAuditWriter()); var cut = Render(); cut.WaitForAssertion(() => Assert.NotNull(cut.Find("[data-testid=list-error]"))); Assert.DoesNotContain("No secrets.", cut.Markup); store.ListFault = null; cut.Find("[data-testid=list-retry]").Click(); cut.WaitForAssertion(() => Assert.Contains("No secrets.", cut.Markup)); } ``` 2. Run `dotnet test tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj --filter FullyQualifiedName~InitialListFailure_IsRetryableAndIsNotAnEmptyInventory`; expected FAIL from unhandled initial list exception (after fake compiles). 3. Catch list failures locally, preserve previous metadata if present, and show Retry with a polite status region. Keep initial loading distinct from empty. Track mutation committed separately from list refresh; show “Change saved; list refresh failed” if necessary. Retry refresh only; never replay upsert/delete to fix a read. Preserve generation ownership and CTS disposal from SEC-01. 4. Add delayed initial load, metadata-only Retry, mutation-committed/reload-failed and disposed-load tests. Run `dotnet test tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj`; expected PASS, especially `AuditFailureAfterCommitTests` and reveal fail-closed tests. 5. Stage the three named files; commit `fix(secrets-ui): distinguish list recovery from committed mutations`. ## SEC-05 · Improve metadata scanning and row-action context **Covers:** SEC-04; DS-01/05. **Depends:** G1 + SEC-01–04. **Modify:** `src/ZB.MOM.WW.Secrets.Ui/Components/SecretsList.razor`; `src/ZB.MOM.WW.Secrets.Ui/Components/RevealButton.razor`; `tests/ZB.MOM.WW.Secrets.Ui.Tests/SecretsListTests.cs`. 1. Add a behavior regression inside `SecretsListTests`, reusing `RegisterStore`/`SecretOne`/`SecretTwo`: ```csharp [Fact] public void NameFilter_CanBeClearedWithoutHidingMetadataPermanently() { RegisterStore(SecretOne, SecretTwo); var cut = Render(); cut.Find("input[data-testid=secret-filter]").Input("db/primary"); Assert.Single(cut.FindAll("tbody tr[data-secret-row]")); cut.Find("[data-testid=clear-secret-filter]").Click(); Assert.Equal(2, cut.FindAll("tbody tr[data-secret-row]").Count); } ``` 2. Run `dotnet test tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj --filter FullyQualifiedName~NameFilter_CanBeClearedWithoutHidingMetadataPermanently`; expected FAIL: no filter. 3. Add a visibly labelled local name filter (metadata already loaded, no value access), clear action and zero-match state. Keep name/description/update time prominent. Move KEK/revision/type/by into native details or responsive secondary cells without deleting metadata. Name each action with its row target (“Rotate app/a”); use a real Actions header and proper row/header semantics. Preserve manage/reveal policies both in markup and handlers. 4. Add no-match/clear, long-name and accessible action-context tests; run `--filter FullyQualifiedName~SecretsListTests`, expected PASS. Inspect 390px, 1440px, 200% zoom, keyboard, long unbroken names and multiple simultaneous rows. The document may not overflow; scoped table/payload scrolling is acceptable. Layout-only changes need visual checks, not tests counting CSS classes. 5. Stage the three named files; commit `feat(secrets-ui): add metadata filtering and clear row actions`. ## SEC-06 · Keep reveal outcomes discoverable without announcing plaintext **Covers:** SEC-05; DS-04. **Depends:** SEC-05 + G1 busy/focus recipe. **Modify:** `src/ZB.MOM.WW.Secrets.Ui/Components/RevealButton.razor`; `tests/ZB.MOM.WW.Secrets.Ui.Tests/RevealButtonTests.cs`; `tests/ZB.MOM.WW.Secrets.Ui.Tests/RevealAuditFailureTests.cs`. 1. Extend `RevealButtonTests` with a regression using the same fake registrations as its existing reveal test: seed `cipher.Encrypt(new SecretName("app/a"), "synthetic-value", SecretContentType.Text)`, authorize RevealPolicy, render Name app/a, click `[data-testid=reveal-button]`. Add these assertions: ```csharp cut.WaitForAssertion(() => { var status = cut.Find("[data-testid=reveal-status][role=status]"); Assert.Contains("Value revealed", status.TextContent); Assert.DoesNotContain("synthetic-value", status.TextContent); }); cut.Find("[data-testid=hide-button]").Click(); Assert.Empty(cut.FindAll("[data-testid=revealed-value]")); ``` 2. Run `dotnet test tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj --filter FullyQualifiedName~RevealButtonTests`; expected FAIL in the new regression on absent outcome status. 3. Keep a stable non-sensitive outcome region and a logically stable trigger/Hide focus path. Announce reveal success/failure only, never plaintext. Clear rendered value on Hide; preserve audit-before-disclosure and handler authorization. Do not add auto-hide without an explicit product policy: current review proposes evaluation, not a mandate. Document the chosen “visible until Hide/navigation” behavior in local help for this release. 4. Run the named RevealButtonTests/RevealAuditFailureTests filters and entire UI suite; expected PASS. Browser-test keyboard reveal/error/hide with synthetic data. Inspect accessibility tree and audit payload to ensure plaintext occurs only in the intentional rendered value, never live status, labels, URL or event details. Use no real-secret screenshot. 5. Stage the three named files; commit `fix(secrets-ui): announce reveal outcomes without disclosing values`. ## SEC-07 · Package and host integration evidence **Covers:** SEC-01–06, DS-06. **Depends:** all tasks + G1. **Modify at version-selection time:** `src/ZB.MOM.WW.Secrets.Ui/ZB.MOM.WW.Secrets.Ui.csproj`, `README.md`; modify `Directory.Build.props` only if deliberately coordinating a complete dependency release. **Create:** `docs/ui-consistency-validation.md`. 1. Run `dotnet build src/ZB.MOM.WW.Secrets.Ui/ZB.MOM.WW.Secrets.Ui.csproj -c Release`; expected zero new warnings. 2. Run `dotnet test tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj -c Release`; expected all tests pass, including authorization, audit-failure-after-commit and reveal-audit-failure suites. Record restored Theme/transitive dependencies. 3. Exercise packaged UI in OtOpcUa's per-page-interactive wrapper and another Bootstrap/global-interactive host using synthetic values. Verify no duplicate `/admin/secrets` route, dead @onclick, missing scoped assets or Bootstrap modal collision. Verify manages-only/reveals-authorized/denied, empty/load/reload failure, target switches, long names, 390/1440px, zoom, reduced motion and actual modal focus. Cross-check shared recipes against the OtOpcUa dialog pilot before extracting generic code. 4. Choose the smallest valid package release set. Prefer a UI-only project-level `` override in `src/ZB.MOM.WW.Secrets.Ui/ZB.MOM.WW.Secrets.Ui.csproj`, leaving the shared `Directory.Build.props` version and Abstractions unchanged. A global version bump would also change the UI's ProjectReference-derived Abstractions dependency; UI-only packing would then reference a possibly unpublished package. Verify the exact Abstractions version exists in the feed. If it does not, coordinate the minimal dependency package set explicitly; do not assume a global version number implies every package is available. Document the actual Theme lower bound and host adoption order. 5. Commit the source/version changes before packing, recording a clean committed source identity. Run `dotnet pack src/ZB.MOM.WW.Secrets.Ui/ZB.MOM.WW.Secrets.Ui.csproj -c Release -o artifacts/ui-consistency`; expected a local new immutable `SECRETS_UI_VERSION` artifact. If a coordinated Abstractions package is required, also run `dotnet pack src/ZB.MOM.WW.Secrets.Abstractions/ZB.MOM.WW.Secrets.Abstractions.csproj -c Release -o artifacts/ui-consistency`. Inspect each `.nuspec` inside its `.nupkg` for actual ID/version/Theme/Abstractions dependencies; record SHA-256 and repository commit. Do not infer dependency versions from folder names. 6. Verify an isolated restore before feed publication. Create a disposable `/tmp/scada-ui-consistency-secrets-restore/UiSmoke.csproj` with `Microsoft.NET.Sdk.Web`, `net10.0`, and PackageReferences to the exact selected UI and Theme versions, plus a minimal `Program.cs` containing `WebApplication.CreateBuilder(args).Build().Run();` with the ASP.NET builder using. Run `dotnet restore /tmp/scada-ui-consistency-secrets-restore/UiSmoke.csproj --packages /tmp/scada-ui-consistency-secrets-restore/packages --source /Users/dohertj2/Desktop/scadaproj/ZB.MOM.WW.Secrets/artifacts/ui-consistency --source ACTUAL_APPROVED_FEED_URL` with the existing authenticated feed configuration; substitute the actual URL rather than commit that placeholder. Include every other approved configured package source needed by the dependency graph, including the approved public source when required: explicit `--source` flags override source selection. Keep the isolated package directory empty initially so success is not masked by a developer global package cache. Run `dotnet build /tmp/scada-ui-consistency-secrets-restore/UiSmoke.csproj --no-restore`; expected restore/build success using the exact minimal package set, with no fallback to an unintended source build. Inspect `obj/project.assets.json` and record the resolved graph. 7. After the master release gate and later explicit authorization, publish only the exact validated package set through the established package release process. Download those feed artifacts into a separate empty verification directory, compare SHA-256 to the validated local artifacts, and repeat isolated restore against the feed without the local package source. Consumer package-pin adoption remains blocked until this succeeds. No publication or deployment occurs while writing or reviewing this plan. 8. Record validation, checksums, dependency graph, actual versions and screenshot links in the validation doc; finish Impeccable audit/polish. Stage only readme/validation updates and commit `docs(secrets-ui): record package and host UI acceptance gates`. ## Complete finding coverage | Review finding | Plan task | Shared contract | |---|---|---| | SEC-06 target/draft leakage | SEC-01, SEC-07 | local state identity; independent of G1 | | SEC-01 unnamed fields | SEC-02, SEC-07 | DS-01/02/04/06 | | SEC-02 dialog name/focus | SEC-03, SEC-07 | DS-04/05 | | SEC-03 loading/refresh recovery | SEC-04, SEC-07 | DS-04/05 | | SEC-04 metadata/action context | SEC-05, SEC-07 | DS-01/05 | | SEC-05 reveal feedback | SEC-06, SEC-07 | DS-04 | ## Rollout and rollback This chapter prepares source, tests, package and host acceptance only. Consumers adopt `SECRETS_UI_VERSION` and `THEME_VERSION` through their own reviewed package pins after gates. Keep the previous immutable library/host artifacts and restored graphs. Roll back package/host assets together; do not undo tombstones, rotate credentials, replay mutations or change encryption/storage formats as a visual rollback. If target isolation is fixed independently, preserve that correction rather than reverting it with later aesthetic work. No data migration is planned.