rcf-lite 0.30.0 → 0.31.0

package/src/view/html-page.js

@@ -59,7 +59,7 @@ import { renderEntitySelector } from './components/entity-selector.js';
 import { renderSubTabStrip } from './components/sub-tab-strip.js';
 import { buildDagLayout, buildDagInspectorPayload, renderBuildDag } from './build-dag.js';
 import { computeReqNeedsWorkIds, needsWorkReasonFor } from './needs-work.js';
-import { renderLookupModal, renderSearchButton } from './view-index.js';
+import { renderLookupModal, renderSearchButton, renderThemeControl } from './view-index.js';
 
 // Umbrella version stamped at module load (same pattern as src/ruleset/index.js).
 // Used by the shell footer so the muted "RCF Lite X.Y.Z" line tracks the
@@ -81,10 +81,21 @@ const LIVE_WRAPPER_CLOSE = '</div>';
  * Render the complete index.html string. Phase 3.8: always includes the
  * live-content wrapper and the live-client script tag.
  *
+ * `opts.embed = true` strips the three-state theme control from the
+ * emitted HTML entirely (ADR-4137 server-side layer). The production
+ * server path at `renderModelToPage` serves one page to every client,
+ * so it never passes `embed`; the client-side layer in `page-init.js`
+ * removes `[data-rcf-theme-control]` from the DOM when `?embed=1` is
+ * on the URL. The option is here so `renderPage({ embed: true })` is
+ * a one-call proof that the control markup can be absent (used by
+ * `test/view/theme-control.test.js` for AC-206-9).
+ *
  * @param {import('./tree-model.js').BuiltTreeModel} model
+ * @param {{ embed?: boolean }} [opts]
  * @returns {string}
  */
-export function renderPage(model) {
+export function renderPage(model, opts) {
+  const embed = Boolean(opts && opts.embed);
   const header = resolveProductHeader(model);
   const projectName = header.projectName ?? 'RCF project';
   const contentHtml = renderContent(model);
@@ -124,6 +135,7 @@ export function renderPage(model) {
       </nav>
       <div class="tools" aria-label="Viewer tools">
         ${renderSearchButton()}
+        ${embed ? '' : renderThemeControl()}
       </div>
     </div>
   </header>

package/src/view/page-init.js

@@ -62,15 +62,151 @@
     else root.removeAttribute('data-embed');
   }
 
+  // Theme provenance (PR 291 landing review F1). live-client re-runs
+  // rcfPage.init() after every SSE swap, so the boot theme must be
+  // resolved and applied ONCE. The state lives on <html> (which
+  // survives every swap and any re-evaluation of this script), like
+  // the __rcf*Wired sentinels elsewhere in this file. `source` is the
+  // last thing that set the theme: 'query' (?theme=), 'stored'
+  // (rcf-view:v1:theme), 'default' (auto), 'host' (rcf-view-theme
+  // postMessage) or 'control' (a click on the theme control). A
+  // re-init never overrides 'host' or 'control'.
+  function themeState() {
+    var root = document.documentElement;
+    if (!root.__rcfThemeState) root.__rcfThemeState = { booted: false, source: null, choice: 'auto' };
+    return root.__rcfThemeState;
+  }
+
+  function setTheme(mode, source) {
+    applyTheme(mode === 'auto' ? null : mode);
+    var st = themeState();
+    st.source = source;
+    st.choice = mode;
+  }
+
+  // Three-state theme control (ADR-4137 standalone-theme-persistence,
+  // Baz 2026-10-04 w-2026-10-04-dave-001). The control writes
+  // `rcf-view:v1:theme` in non-embed mode only; under embed the control
+  // is removed from the DOM entirely and the key is never read or
+  // written. The key sits under the shared `rcf-view:v1:` namespace so
+  // the PR 9 localStorage namespace lint stays green.
+  var THEME_STORAGE_KEY = 'rcf-view:v1:theme';
+
+  function isEmbedActive() {
+    try { return document.documentElement.getAttribute('data-embed') === '1'; }
+    catch (e) { return false; }
+  }
+
+  function safeStorage() {
+    try {
+      if (typeof window === 'undefined' || !window.localStorage) return null;
+      return window.localStorage;
+    } catch (e) {
+      // localStorage can throw on strict privacy modes; treat as absent.
+      return null;
+    }
+  }
+
+  function readStoredTheme() {
+    // The storage boundary (ADR-4137 consequences): under embed we
+    // never read the shared key, so a future re-render of the control
+    // under embed cannot accidentally pick up a value either.
+    if (isEmbedActive()) return null;
+    var s = safeStorage();
+    if (!s) return null;
+    try {
+      var v = s.getItem(THEME_STORAGE_KEY);
+      if (v === 'light' || v === 'dark' || v === 'auto') return v;
+      return null;
+    } catch (e) { return null; }
+  }
+
+  function writeStoredTheme(v) {
+    if (isEmbedActive()) return; // never write under embed (ADR-4137)
+    if (v !== 'light' && v !== 'dark' && v !== 'auto') return;
+    var s = safeStorage();
+    if (!s) return;
+    try { s.setItem(THEME_STORAGE_KEY, v); } catch (e) { /* quota or disabled */ }
+  }
+
+  // Reflect the current effective theme choice (light|dark|auto) on
+  // the control's three buttons. Idempotent across live swaps so the
+  // Router re-run after an SSE innerHTML swap of `#rcf-live-content`
+  // re-syncs (the control itself sits outside the swap wrapper so it
+  // survives, but a fresh page-init call still re-wires guards).
+  function reflectThemeChoice(mode) {
+    var buttons = document.querySelectorAll('[data-rcf-theme-control] [data-rcf-theme]');
+    for (var i = 0; i < buttons.length; i += 1) {
+      var b = buttons[i];
+      var isTarget = b.getAttribute('data-rcf-theme') === mode;
+      b.setAttribute('aria-pressed', isTarget ? 'true' : 'false');
+    }
+  }
+
+  function wireThemeControl() {
+    if (isEmbedActive()) {
+      // ADR-4137: control is absent from the DOM entirely under embed,
+      // not merely hidden by CSS. renderPage({ embed: true }) already
+      // omits the markup; this strip-on-boot is the client-side layer
+      // for the production path where the server renders one page for
+      // every client regardless of the client's query.
+      var ctl = document.querySelector('[data-rcf-theme-control]');
+      if (ctl && ctl.parentNode) ctl.parentNode.removeChild(ctl);
+      return;
+    }
+    var buttons = document.querySelectorAll('[data-rcf-theme-control] [data-rcf-theme]');
+    for (var i = 0; i < buttons.length; i += 1) {
+      var btn = buttons[i];
+      if (btn.__rcfThemeWired) continue;
+      btn.__rcfThemeWired = true;
+      btn.addEventListener('click', function (ev) {
+        var mode = ev.currentTarget.getAttribute('data-rcf-theme');
+        if (mode !== 'light' && mode !== 'dark' && mode !== 'auto') return;
+        setTheme(mode, 'control');
+        writeStoredTheme(mode);
+        reflectThemeChoice(mode);
+      });
+    }
+  }
+
+  // Resolve the effective theme choice for boot, in the precedence
+  // ADR-4137 pins: explicit ?theme= wins first; then (non-embed only)
+  // the stored value; then auto. The stored value is NEVER consulted
+  // under embed. Returns { mode: 'light'|'dark'|'auto', source:
+  // 'query'|'stored'|'default' }.
+  function resolveBootTheme(query) {
+    var q = query && (query.theme === 'light' || query.theme === 'dark' || query.theme === 'auto')
+      ? query.theme : null;
+    if (q) return { mode: q, source: 'query' };
+    var stored = readStoredTheme();
+    if (stored === 'light' || stored === 'dark' || stored === 'auto') return { mode: stored, source: 'stored' };
+    return { mode: 'auto', source: 'default' };
+  }
+
   function initShellFromQuery() {
     var q = parseQuery(window.location.search);
-    // theme: explicit light|dark wins, auto falls through to the
-    // :root:not([data-theme]) + @media prefers-color-scheme block in
-    // style.css. Absent stays light (the base :root tokens).
-    var theme = q.theme;
-    if (theme === 'light' || theme === 'dark' || theme === 'auto') applyTheme(theme === 'auto' ? null : theme);
-    // embed: any value other than exactly "1" is ignored.
+    // embed first so isEmbedActive() reads the right boundary when
+    // the theme precedence check consults storage.
     applyEmbed(q.embed === '1');
+    var st = themeState();
+    var qTheme = (q.theme === 'light' || q.theme === 'dark' || q.theme === 'auto') ? q.theme : null;
+    if (!st.booted) {
+      // First init: resolve the boot theme in ADR-4137 precedence and
+      // apply it once.
+      st.booted = true;
+      var boot = resolveBootTheme(q);
+      setTheme(boot.mode, boot.source);
+    } else if (qTheme && st.source === 'query') {
+      // Re-init (SSE swap): re-assert ?theme= only while it is still
+      // the last thing that set the theme. A host postMessage or a
+      // control click since boot wins and is never overridden; with no
+      // ?theme= a re-init applies nothing (embed host themes survive).
+      setTheme(qTheme, 'query');
+    }
+    // Strip or wire the control after embed has been stamped; the
+    // helper reads data-embed to pick the branch.
+    wireThemeControl();
+    reflectThemeChoice(st.choice);
   }
 
   var messageListenerWired = false;
@@ -84,7 +220,12 @@
       if (!ev || ev.origin !== window.location.origin) return;
       var data = ev.data || {};
       if (data.type !== 'rcf-view-theme') return;
-      if (data.theme === 'light' || data.theme === 'dark') applyTheme(data.theme);
+      if (data.theme === 'light' || data.theme === 'dark') {
+        setTheme(data.theme, 'host');
+        // Live postMessage never writes the stored key (ADR-4137):
+        // the host-driven swap is a session-only override.
+        reflectThemeChoice(data.theme);
+      }
     });
   }
 
@@ -632,7 +773,7 @@
       btn.__rcfFixtureThemeWired = true;
       btn.addEventListener('click', function (ev) {
         var mode = ev.currentTarget.getAttribute('data-rcf-fixture-theme');
-        applyTheme(mode === 'auto' ? null : mode);
+        setTheme(mode === 'light' || mode === 'dark' ? mode : 'auto', 'control');
         var buttons = document.querySelectorAll('[data-rcf-fixture-theme]');
         for (var j = 0; j < buttons.length; j += 1) {
           var b = buttons[j];

package/src/view/style.css

@@ -810,7 +810,10 @@ footer.app-footer a {
 
 footer.app-footer a:hover { text-decoration: underline; }
 
-footer.app-footer .sep { color: var(--sv-control); }
+/* Baz 2026-10-04 w-2026-10-04-dave-001: separator was `--sv-control`
+   which fell under 4.5:1 in both themes (3.51:1 light, 4.21:1 dark);
+   `--sv-muted` is the "muted text" token designed for this. */
+footer.app-footer .sep { color: var(--sv-muted); }
 
 footer.app-footer .live {
   margin-left: auto;
@@ -955,7 +958,7 @@ html[data-embed="1"] .pm-controls { top: 3rem; }
   color: var(--sv-ink);
   font-weight: 600;
   box-shadow: var(--shadow-sm);
-  border-color: var(--sv-border);
+  border-color: var(--sv-control);
 }
 
 .pm-status-filter {
@@ -1151,7 +1154,10 @@ details.pm-bucket[open] > summary.pm-bucket-heading {
 .pm-mini-review { color: var(--sv-link); background: var(--sv-active); border-color: var(--sv-link); }
 .pm-mini-draft { color: var(--sv-muted); background: var(--sv-raised); border-color: var(--sv-border); }
 .pm-mini-needsRevision { color: var(--sv-danger); background: var(--sv-dangerbg); border-color: var(--sv-danger); }
-.pm-mini-superseded { color: var(--sv-control); background: var(--sv-raised); border-color: var(--sv-border); }
+/* Baz 2026-10-04 w-2026-10-04-dave-001: `--sv-control` on `--sv-raised`
+   was 3.51:1 light / 4.21:1 dark, below the 4.5:1 floor for small text.
+   `--sv-muted` is the matching muted-text token and clears AA in both. */
+.pm-mini-superseded { color: var(--sv-muted); background: var(--sv-raised); border-color: var(--sv-border); }
 
 .pm-bucket-body { padding: 0.75rem 1rem 1rem; }
 .pm-bucket-body .pm-tad-root { margin-bottom: 0.65rem; }
@@ -1225,7 +1231,9 @@ details.pm-bucket[open] > summary.pm-bucket-heading {
 }
 .pm-blueprint-cap-count {
   font-weight: 500;
-  color: var(--sv-control);
+  /* Baz 2026-10-04 w-2026-10-04-dave-001: `--sv-control` fell under
+     the 4.5:1 small-text floor; switched to `--sv-muted`. */
+  color: var(--sv-muted);
   margin-left: 0.25rem;
 }
 .pm-blueprint-cap-body { display: block; }
@@ -2260,19 +2268,38 @@ details.rcf-row.rcf-row--inner > summary { padding: 0.4rem 0.6rem; }
   align-items: center;
   gap: 0.35rem;
   padding: 0.3rem 0.6rem;
-  background: var(--sv-surface, #ffffff);
-  color: var(--sv-text, inherit);
-  border: 1px solid var(--sv-border, #d6dbe3);
+  background: var(--sv-surface);
+  color: var(--sv-ink);
+  border: 1px solid var(--sv-border);
   border-radius: 999px;
   font: inherit;
   font-size: 0.85rem;
   line-height: 1;
   cursor: pointer;
-  transition: background-color 0.1s ease-out, border-color 0.1s ease-out;
+  transition: background-color 0.1s ease-out, border-color 0.1s ease-out, color 0.1s ease-out;
+}
+/* Baz 2026-10-04 w-2026-10-04-dave-001: hover previously fell back to
+   a hard-coded light grey (`#f0f3f8`) because `--sv-surface-hover` was
+   never declared; in dark that painted dark ink on a light grey and
+   made the FIND button unreadable. The hover now uses `--sv-active`
+   (the Stravica brand "selected / hovered surface" token, defined in
+   both the `:root` and `:root[data-theme="dark"]` blocks) with the
+   control-strength border so the boundary stays >= 3:1 against the
+   header surface in both themes. The focus-visible outline uses
+   `--sv-focus` (brand focus token) at 3px with 2px offset. */
+.rcf-search-btn:hover,
+.rcf-search-btn:focus-visible {
+  background: var(--sv-active);
+  color: var(--sv-ink);
+  border-color: var(--sv-control);
+}
+.rcf-search-btn:active {
+  background: var(--sv-active);
+  color: var(--sv-ink);
+  border-color: var(--sv-focus);
 }
-.rcf-search-btn:hover { background: var(--sv-surface-hover, #f0f3f8); }
 .rcf-search-btn:focus-visible { outline: 3px solid var(--sv-focus); outline-offset: 2px; }
-.rcf-search-btn .rcf-search-icon { flex-shrink: 0; opacity: 0.75; }
+.rcf-search-btn .rcf-search-icon { flex-shrink: 0; opacity: 0.85; color: var(--sv-ink); }
 .rcf-search-btn .rcf-search-kbd {
   display: inline-flex;
   gap: 0.1rem;
@@ -2282,9 +2309,10 @@ details.rcf-row.rcf-row--inner > summary { padding: 0.4rem 0.6rem; }
 }
 .rcf-search-btn .rcf-search-kbd kbd {
   padding: 0 0.25rem;
-  border: 1px solid var(--sv-border, #d6dbe3);
+  border: 1px solid var(--sv-border);
   border-radius: 3px;
-  background: var(--sv-surface, #ffffff);
+  background: var(--sv-surface);
+  color: var(--sv-ink);
   font-family: inherit;
 }
 
@@ -2292,6 +2320,57 @@ details.rcf-row.rcf-row--inner > summary { padding: 0.4rem 0.6rem; }
   .rcf-search-btn .rcf-search-kbd { display: none; }
 }
 
+/* --------------------------------------------------------------------
+ * Three-state theme control (ADR-4137, Baz 2026-10-04).
+ *
+ * Sits in `.tools` right of the SearchButton in non-embed mode; absent
+ * from the DOM entirely under `data-embed="1"` (page-init.js removes
+ * the element, renderPage({ embed: true }) also skips the markup).
+ * The group buttons use the same ink/active/control tokens as the
+ * SearchButton so hover and focus states stay above WCAG AA in both
+ * themes.
+ * -------------------------------------------------------------------- */
+
+.rcf-theme {
+  display: inline-flex;
+  align-items: stretch;
+  border: 1px solid var(--sv-border);
+  border-radius: 999px;
+  overflow: hidden;
+  background: var(--sv-surface);
+}
+.rcf-theme-btn {
+  appearance: none;
+  background: transparent;
+  color: var(--sv-ink);
+  border: 0;
+  padding: 0.3rem 0.55rem;
+  font: inherit;
+  font-size: 0.75rem;
+  line-height: 1;
+  cursor: pointer;
+  transition: background-color 0.1s ease-out, color 0.1s ease-out;
+}
+.rcf-theme-btn + .rcf-theme-btn { border-left: 1px solid var(--sv-border); }
+.rcf-theme-btn:hover {
+  background: var(--sv-active);
+  color: var(--sv-ink);
+}
+.rcf-theme-btn:focus-visible {
+  outline: 3px solid var(--sv-focus);
+  outline-offset: -3px;
+  background: var(--sv-active);
+}
+.rcf-theme-btn:active {
+  background: var(--sv-active);
+  color: var(--sv-ink);
+}
+.rcf-theme-btn[aria-pressed="true"] {
+  background: var(--sv-button);
+  color: var(--sv-onbutton);
+}
+html[data-embed="1"] .rcf-theme { display: none; }
+
 .rcf-lookup[hidden] { display: none !important; }
 .rcf-lookup {
   position: fixed;
@@ -2346,7 +2425,7 @@ details.rcf-row.rcf-row--inner > summary { padding: 0.4rem 0.6rem; }
   border-radius: 4px;
   cursor: pointer;
 }
-.rcf-lookup-close:hover { color: var(--sv-text); border-color: var(--sv-border); }
+.rcf-lookup-close:hover { color: var(--sv-text); border-color: var(--sv-control); }
 .rcf-lookup-close:focus-visible { outline: 3px solid var(--sv-focus); outline-offset: 1px; }
 
 .rcf-lookup-field { display: flex; flex-direction: column; gap: 0.25rem; }
@@ -2360,9 +2439,9 @@ details.rcf-row.rcf-row--inner > summary { padding: 0.4rem 0.6rem; }
   padding: 0.55rem 0.75rem;
   font: inherit;
   font-size: 0.95rem;
-  border: 1px solid var(--sv-border, #d6dbe3);
+  border: 1px solid var(--sv-control);
   border-radius: 6px;
-  background: var(--sv-surface-sub, #fbfcfe);
+  background: var(--sv-surface);
   color: var(--sv-text);
 }
 .rcf-lookup-input:focus-visible { outline: 3px solid var(--sv-focus); outline-offset: 1px; border-color: var(--sv-link, #3a5bb5); }
@@ -2389,9 +2468,9 @@ details.rcf-row.rcf-row--inner > summary { padding: 0.4rem 0.6rem; }
   cursor: pointer;
   border: 1px solid transparent;
 }
-.rcf-lookup-row:hover { background: var(--sv-surface-hover, #f0f3f8); }
+.rcf-lookup-row:hover { background: var(--sv-active); }
 .rcf-lookup-row.is-active {
-  background: var(--sv-surface-hover, #f0f3f8);
+  background: var(--sv-active);
   border-color: var(--sv-link, #3a5bb5);
 }
 .rcf-lookup-row mark {
@@ -2467,7 +2546,7 @@ details.rcf-row.rcf-row--inner > summary { padding: 0.4rem 0.6rem; }
   font: inherit;
   font-size: 0.85rem;
 }
-.rcf-lookup-reload:hover { background: var(--sv-surface-hover, #f0f3f8); }
+.rcf-lookup-reload:hover { background: var(--sv-active); }
 .rcf-lookup-reload:focus-visible { outline: 3px solid var(--sv-focus); outline-offset: 1px; }
 
 html[data-theme="dark"] .rcf-lookup-backdrop { background: rgba(0, 0, 0, 0.55); }

package/src/view/view-index.js

@@ -321,3 +321,25 @@ export function renderSearchButton() {
   <span class="rcf-search-kbd" aria-hidden="true"><kbd>Ctrl</kbd>+<kbd>F</kbd></span>
 </button>`;
 }
+
+/**
+ * Three-state Light|Dark|Auto theme control for the standalone viewer
+ * shell (viewer UI refresh design section 11 recommendation 6, Baz's
+ * 2026-10-04 review `w-2026-10-04-dave-001`). The control is rendered
+ * server-side without an initial `aria-pressed=true` on any button; the
+ * boot path in `page-init.js` reads `?theme=`, then (non-embed only)
+ * `localStorage['rcf-view:v1:theme']` per ADR-4137, then defaults to
+ * Auto, and stamps the right button with `aria-pressed="true"` from
+ * that resolved value. Under `embed=1` `html-page.js` omits this call
+ * entirely so no element with `[data-rcf-theme-control]` reaches the
+ * DOM and the storage key is never read or written (ADR-4137).
+ *
+ * @returns {string}
+ */
+export function renderThemeControl() {
+  return `<div class="rcf-theme" data-rcf-theme-control role="group" aria-label="Theme">
+  <button type="button" class="rcf-theme-btn" data-rcf-theme="light" aria-pressed="false" title="Light theme" aria-label="Light theme">Light</button>
+  <button type="button" class="rcf-theme-btn" data-rcf-theme="dark" aria-pressed="false" title="Dark theme" aria-label="Dark theme">Dark</button>
+  <button type="button" class="rcf-theme-btn" data-rcf-theme="auto" aria-pressed="false" title="Follow system theme" aria-label="Follow system theme">Auto</button>
+</div>`;
+}