rcf-lite 0.12.0 → 0.14.0

package/src/view/live-client.js

@@ -1,8 +1,10 @@
 // Live-view client. Loaded by the server-rendered page as
 // `<script src="/live-client.js" defer>`. Handles the SSE `/events`
-// stream, in-place `innerHTML` swaps into `#rcf-live-content`, and
-// persists `<details>` open-set + main scrollTop to `localStorage`
-// across every swap and every full reload.
+// stream, in-place `innerHTML` swaps into `#rcf-live-content`, persists
+// `<details>` open-set + main scrollTop to `localStorage` across every
+// swap and every full reload, AND applies the URL-driven scope filter
+// (deep-link deep-links: blueprint / node — w-2026-08-30-dave-020) on
+// every load and every swap.
 //
 // Vanilla classic script (no ESM syntax) so the base HTML script tag
 // stays plain. The IIFE exposes its internals as `window.__rcfLiveClient`
@@ -10,7 +12,9 @@
 // jsdom.
 //
 // Spec: projects/rcf-build-lite/specs/phase-3.8-live-view.md D12, D13a,
-// D13b, D14.
+// D13b, D14. Deep-link overlay: see `src/view/scope.js`
+// (server-side truth) and `test/view/scope-client.test.js`
+// (browser-side proofs).
 
 (function () {
   var STORAGE_NS = 'rcf-view:v1:';
@@ -18,6 +22,232 @@
   var STORAGE_SCROLL = STORAGE_NS + 'scrollTop';
   var HEARTBEAT_STALE_MS = 45000;
 
+  // ---- deep-link scope --------------------------------------------------
+
+  // Scope model: { blueprint: string|null, node: string|null }. Read on
+  // load and after every SSE swap; the DOM class hooks below drive the
+  // stylesheet's opacity / focus rules.
+
+  function parseUrlScope(search) {
+    var out = { blueprint: null, node: null };
+    if (typeof search !== 'string' || search.length === 0) return out;
+    var raw = search.charAt(0) === '?' ? search.slice(1) : search;
+    if (raw.length === 0) return out;
+    var pairs = raw.split('&');
+    for (var i = 0; i < pairs.length; i += 1) {
+      var eq = pairs[i].indexOf('=');
+      if (eq === -1) continue;
+      var key = decodeSafely(pairs[i].slice(0, eq));
+      var val = decodeSafely(pairs[i].slice(eq + 1));
+      if (typeof val !== 'string') continue;
+      var trimmed = val.replace(/^\s+|\s+$/g, '');
+      if (trimmed.length === 0) continue;
+      if (key === 'blueprint' && out.blueprint === null) out.blueprint = trimmed;
+      else if (key === 'node' && out.node === null) out.node = trimmed;
+    }
+    return out;
+  }
+
+  function decodeSafely(s) {
+    try { return decodeURIComponent(String(s).replace(/\+/g, ' ')); }
+    catch (e) { return null; }
+  }
+
+  function markScopeIds(doc, contributionIds, customisedIds) {
+    if (!doc) return { inScopeCount: 0, customisedCount: 0 };
+    clearScopeMarkers(doc);
+    var inSet = toIdSet(contributionIds);
+    var customSet = toIdSet(customisedIds);
+    var inScopeCount = 0;
+    var customisedCount = 0;
+    // A doc container carries data-doc-id; we walk them and mark the
+    // matching ones. Ancestors of an in-scope doc are also marked so
+    // the tree drill-down (details wrappers, tabpanels) stays visible.
+    var nodes = doc.querySelectorAll('[data-doc-id]');
+    for (var i = 0; i < nodes.length; i += 1) {
+      var el = nodes[i];
+      var id = el.getAttribute('data-doc-id');
+      if (!id) continue;
+      // The raw-json disclosures carry ids like `PRD-001::raw`;
+      // strip the ::raw suffix so the scope hit matches the parent
+      // doc's contribution id.
+      var canonical = id.replace(/::raw$/, '');
+      if (!inSet[canonical]) continue;
+      el.classList.add('rcf-in-scope');
+      inScopeCount += 1;
+      if (customSet[canonical]) {
+        el.classList.add('rcf-customised');
+        customisedCount += 1;
+      }
+      // Walk ancestors and mark them as containing an in-scope doc
+      // so the CSS can keep them at full opacity.
+      var cur = el.parentNode;
+      while (cur && cur !== doc.body) {
+        if (cur.classList && !cur.classList.contains('rcf-scope-ancestor')) {
+          cur.classList.add('rcf-scope-ancestor');
+        }
+        cur = cur.parentNode;
+      }
+      // Auto-open the ancestor <details> so the drill-down surfaces
+      // the contribution without a manual click.
+      openAncestorDetailsChain(el);
+    }
+    return { inScopeCount: inScopeCount, customisedCount: customisedCount };
+  }
+
+  function toIdSet(list) {
+    var out = Object.create(null);
+    if (!Array.isArray(list)) return out;
+    for (var i = 0; i < list.length; i += 1) {
+      if (typeof list[i] === 'string') out[list[i]] = true;
+    }
+    return out;
+  }
+
+  function openAncestorDetailsChain(node) {
+    var cur = node.parentNode;
+    while (cur && cur.tagName) {
+      if (cur.tagName.toLowerCase() === 'details') {
+        cur.open = true;
+      }
+      cur = cur.parentNode;
+    }
+  }
+
+  function clearScopeMarkers(doc) {
+    var scoped = doc.querySelectorAll('.rcf-in-scope, .rcf-customised, .rcf-scope-ancestor');
+    for (var i = 0; i < scoped.length; i += 1) {
+      scoped[i].classList.remove('rcf-in-scope');
+      scoped[i].classList.remove('rcf-customised');
+      scoped[i].classList.remove('rcf-scope-ancestor');
+    }
+  }
+
+  function renderScopeBanner(doc, meta) {
+    // Idempotent: reuse the same banner across swaps rather than
+    // stacking one banner per SSE tick.
+    if (!doc || !doc.body) return null;
+    var main = doc.querySelector('main');
+    if (!main) return null;
+    var banner = doc.getElementById('rcf-scope-banner');
+    if (!banner) {
+      banner = doc.createElement('aside');
+      banner.id = 'rcf-scope-banner';
+      banner.setAttribute('role', 'status');
+      main.insertBefore(banner, main.firstChild);
+    }
+    var lines = [];
+    if (meta.blueprint) {
+      var counted = 'scoped to blueprint ' + escapeText(meta.blueprint)
+        + ' (' + meta.inScopeCount + ' contribution' + (meta.inScopeCount === 1 ? '' : 's');
+      if (typeof meta.customisedCount === 'number' && meta.customisedCount > 0) {
+        counted += ', ' + meta.customisedCount + ' customised';
+      }
+      counted += ')';
+      lines.push(counted);
+    }
+    if (meta.node) {
+      lines.push('focus: ' + escapeText(meta.node));
+    }
+    if (typeof meta.warning === 'string' && meta.warning.length > 0) {
+      lines.push(meta.warning);
+    }
+    lines.push('<a href="?">clear scope</a>');
+    banner.innerHTML = lines.join(' · ');
+    return banner;
+  }
+
+  function removeScopeBanner(doc) {
+    if (!doc) return;
+    var banner = doc.getElementById('rcf-scope-banner');
+    if (banner && banner.parentNode) banner.parentNode.removeChild(banner);
+  }
+
+  function escapeText(s) {
+    return String(s).replace(/[&<>"']/g, function (ch) {
+      return ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[ch];
+    });
+  }
+
+  function focusNode(doc, id) {
+    if (!doc || !id) return false;
+    var target = doc.getElementById(id) || doc.querySelector('[data-doc-id="' + id.replace(/"/g, '\\"') + '"]');
+    if (!target) return false;
+    openAncestorDetailsChain(target);
+    if (target.tagName && target.tagName.toLowerCase() === 'details') target.open = true;
+    try { target.scrollIntoView({ block: 'start' }); }
+    catch (e) { try { target.scrollIntoView(); } catch (_e) { /* soft */ } }
+    return true;
+  }
+
+  // Fetch the scope payload from /scope.json for a given slug. Kept as
+  // a small helper so the tests can substitute a fake fetch impl.
+  function fetchScope(slug, fetchImpl) {
+    var f = typeof fetchImpl === 'function' ? fetchImpl : (typeof fetch === 'function' ? fetch : null);
+    if (!f) return Promise.reject(new Error('no fetch available'));
+    var url = '/scope.json?blueprint=' + encodeURIComponent(slug);
+    return Promise.resolve(f(url)).then(function (resp) {
+      if (!resp) throw new Error('scope: no response');
+      var okFlag = resp.ok !== undefined ? resp.ok : (resp.status >= 200 && resp.status < 300);
+      return Promise.resolve(resp.json ? resp.json() : null).then(function (body) {
+        return { ok: !!okFlag, status: resp.status, body: body };
+      });
+    });
+  }
+
+  // Apply the URL scope to the currently-rendered DOM. Returns a
+  // Promise that resolves with a summary object; never rejects (any
+  // failure is downgraded to a banner warning).
+  function applyUrlScope(deps) {
+    var doc = deps.document;
+    var win = deps.window;
+    var scope = parseUrlScope((win && win.location && win.location.search) || '');
+    if (!scope.blueprint && !scope.node) {
+      if (doc && doc.body) doc.body.classList.remove('rcf-scoped');
+      clearScopeMarkers(doc);
+      removeScopeBanner(doc);
+      return Promise.resolve({ scope: scope, applied: false });
+    }
+    if (doc && doc.body) doc.body.classList.add('rcf-scoped');
+
+    var meta = {
+      blueprint: scope.blueprint,
+      node: scope.node,
+      inScopeCount: 0,
+      customisedCount: 0,
+      warning: '',
+    };
+
+    var blueprintPart = scope.blueprint
+      ? fetchScope(scope.blueprint, deps.fetch).then(function (r) {
+        if (!r.ok) {
+          meta.warning = r.status === 404
+            ? 'blueprint ' + scope.blueprint + ' is not applied to this project'
+            : 'scope lookup failed (status ' + r.status + ')';
+          return;
+        }
+        var body = r.body || {};
+        var marks = markScopeIds(doc, body.contributionIds || [], body.customisedIds || []);
+        meta.inScopeCount = marks.inScopeCount;
+        meta.customisedCount = marks.customisedCount;
+      }).catch(function (err) {
+        meta.warning = 'scope lookup error: ' + (err && err.message ? err.message : 'unknown');
+      })
+      : Promise.resolve();
+
+    return blueprintPart.then(function () {
+      renderScopeBanner(doc, meta);
+      if (scope.node) {
+        var focused = focusNode(doc, scope.node);
+        if (!focused && !meta.warning) {
+          meta.warning = 'node ' + scope.node + ' is not present on the tree';
+          renderScopeBanner(doc, meta);
+        }
+      }
+      return { scope: scope, applied: true, meta: meta };
+    });
+  }
+
   // ---- state persistence ------------------------------------------------
 
   function safeGetItem(storage, key) {
@@ -142,12 +372,22 @@
     // whitelisted deltas from Phase 3.6).
     injectConnectionDot(doc);
 
-    // Restore prior state on initial load.
+    // Restore prior state on initial load, then apply URL-driven scope
+    // so a deep-link (?blueprint=…&node=…) surfaces the target section
+    // even on the very first render.
+    var applyScope = function () { applyUrlScope(deps).catch(function () { /* soft */ }); };
     if (doc.readyState === 'loading') {
-      doc.addEventListener('DOMContentLoaded', function () { restoreState(deps); });
+      doc.addEventListener('DOMContentLoaded', function () {
+        restoreState(deps);
+        applyScope();
+      });
     } else {
       restoreState(deps);
+      applyScope();
     }
+    // Scope tracks URL changes without a reload (agent pushes a new
+    // deep-link into the same tab, or the user clicks "clear scope").
+    win.addEventListener('popstate', applyScope);
 
     var currentVersion = null;
     var lastEventAt = Date.now();
@@ -203,6 +443,7 @@
       // the payload have no `data-processed` yet.
       resyncTabsAfterSwap(doc, win);
       restoreState(deps);
+      applyScope();
       setState('connected');
     });
 
@@ -319,6 +560,12 @@
     injectConnectionDot: injectConnectionDot,
     updateDot: updateDot,
     resyncTabsAfterSwap: resyncTabsAfterSwap,
+    parseUrlScope: parseUrlScope,
+    applyUrlScope: applyUrlScope,
+    markScopeIds: markScopeIds,
+    renderScopeBanner: renderScopeBanner,
+    removeScopeBanner: removeScopeBanner,
+    focusNode: focusNode,
     STORAGE_OPEN: STORAGE_OPEN,
     STORAGE_SCROLL: STORAGE_SCROLL,
     HEARTBEAT_STALE_MS: HEARTBEAT_STALE_MS,

package/src/view/scope.js

@@ -0,0 +1,231 @@
+// Deep-link scope resolution. Pure helpers shared by the server-side
+// /scope.json endpoint, the CLI `audit view open` verb, and the
+// live-client filter. Nothing here reads process.env, prints, or
+// mutates state.
+//
+// Scope model (spec: w-2026-08-30-dave-020, Baz-ratified 2026-08-30):
+//   * blueprint scope  -> the applied blueprint's namespaced
+//     contribution ids, read from manifest.blueprints[].contributions[].
+//     The applied record IS the truth (project-local), never the
+//     shipping blueprint source (which may drift or vanish).
+//   * node scope       -> a single document id (any kind in tree.byId),
+//     resolved by the existing hash-router in the client script. Server
+//     validates existence so a bad id refuses at the CLI seam rather
+//     than opening a dead browser tab.
+//   * customisation set -> the subset of contribution ids whose current
+//     on-disk bytes differ from the shipping blueprint source's file.
+//     Best-effort: any read failure (source missing, unreadable) treats
+//     the file as "unknown" (excluded), which the renderer displays as
+//     plain in-scope rather than as customised.
+
+import { readFile, stat } from 'node:fs/promises';
+import { isAbsolute, join, resolve } from 'node:path';
+
+import { loadBlueprint } from '../blueprint/loader.js';
+import { resolveBlueprintSource } from '../blueprint/shelf-resolver.js';
+import { isRcfError } from '../core/errors/index.js';
+
+/**
+ * Parse the recognised scope keys from a URL query string.
+ *
+ * @param {URLSearchParams} params
+ * @returns {{ blueprint: string|null, node: string|null }}
+ */
+export function parseUrlScope(params) {
+  const blueprint = normaliseString(params.get('blueprint'));
+  const node = normaliseString(params.get('node'));
+  return { blueprint, node };
+}
+
+function normaliseString(v) {
+  if (typeof v !== 'string') return null;
+  const trimmed = v.trim();
+  return trimmed.length === 0 ? null : trimmed;
+}
+
+/**
+ * Resolve the applied blueprint record for a slug.
+ *
+ * @param {object|null} manifest
+ * @param {string} slug
+ * @returns {{ found: false } | { found: true, record: object, contributionIds: string[] }}
+ */
+export function contributionsForBlueprint(manifest, slug) {
+  if (!manifest || !Array.isArray(manifest.blueprints)) return { found: false };
+  const record = manifest.blueprints.find((b) => b?.slug === slug);
+  if (!record) return { found: false };
+  const contributionIds = Array.isArray(record.contributions)
+    ? record.contributions.map((c) => c?.id).filter((id) => typeof id === 'string')
+    : [];
+  return { found: true, record, contributionIds };
+}
+
+/**
+ * List every applied blueprint slug present in the manifest. Used by
+ * the client to preflight scope requests without a round trip per view.
+ *
+ * @param {object|null} manifest
+ * @returns {string[]}
+ */
+export function listAppliedSlugs(manifest) {
+  if (!manifest || !Array.isArray(manifest.blueprints)) return [];
+  return manifest.blueprints
+    .map((b) => (typeof b?.slug === 'string' ? b.slug : null))
+    .filter((s) => s !== null);
+}
+
+/**
+ * Detect which of the applied blueprint's contribution files have been
+ * modified on disk since apply. Compares current file bytes to the
+ * shipping source file bytes. Source paths that no longer resolve are
+ * treated as "unknown" (excluded from the result), so a deleted
+ * shipping tree does not fake a full-tree customisation banner.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot - absolute path to the project root
+ * @param {object} args.record - applied blueprint record
+ * @param {(abs: string) => Promise<string>} [args._readFile] - test seam
+ * @returns {Promise<{ customisedIds: string[], missingSourceIds: string[] }>}
+ */
+export async function detectCustomisations({ projectRoot, record, _readFile, _loadBlueprint, _resolveSource }) {
+  const readImpl = _readFile ?? ((abs) => readFile(abs, 'utf8'));
+  const loadImpl = _loadBlueprint ?? loadBlueprint;
+  const resolveImpl = _resolveSource ?? resolveBlueprintSource;
+  const customisedIds = [];
+  const missingSourceIds = [];
+  if (!record || !Array.isArray(record.contributions)) {
+    return { customisedIds, missingSourceIds };
+  }
+  const sourceAbs = await resolveSourceAbs(projectRoot, record.source, resolveImpl);
+  const sourceIndex = await loadSourceContributionIndex({ sourceAbs, loadImpl });
+  for (const c of record.contributions) {
+    if (typeof c?.id !== 'string' || typeof c?.path !== 'string') continue;
+    const projectAbs = resolve(projectRoot, c.path);
+    let currentBytes = null;
+    try {
+      currentBytes = await readImpl(projectAbs);
+    } catch {
+      // No project-side file: not a customisation (nothing on disk).
+      continue;
+    }
+    if (!sourceIndex) {
+      missingSourceIds.push(c.id);
+      continue;
+    }
+    // Cross-reference by CONTRIBUTION INDEX (position). The applied
+    // record and the shipping blueprint list contributions in the same
+    // order at apply time; the applied record's ids are namespaced
+    // (stampId) but the position map is stable and does not rely on
+    // any string derivation.
+    const sourcePathRelative = sourceIndex.byAppliedId(c.id);
+    if (!sourcePathRelative) {
+      missingSourceIds.push(c.id);
+      continue;
+    }
+    const sourceFileAbs = join(sourceAbs, 'contributions', sourcePathRelative);
+    let sourceBytes = null;
+    try {
+      sourceBytes = await readImpl(sourceFileAbs);
+    } catch {
+      missingSourceIds.push(c.id);
+      continue;
+    }
+    if (currentBytes !== sourceBytes) customisedIds.push(c.id);
+  }
+  return { customisedIds, missingSourceIds };
+}
+
+async function resolveSourceAbs(projectRoot, source, resolveImpl) {
+  if (typeof source !== 'string' || source.length === 0) return null;
+  if (isAbsolute(source)) return source;
+  // Non-path sources - a library colon ref (`wsd:auth-oauth2`), an
+  // `@stock/<slug>` sugar, or a bare shelf slug - need re-resolution
+  // through the blueprint resolver against the project registry and the
+  // packaged shelf. Without this, the applied-record's source is a
+  // token the FS cannot open and every contribution renders as
+  // missingSource in /scope.json (integration review d-2026-08-31-046).
+  // A relative filesystem path still falls through to the pre-fix
+  // resolve() below so an existing manifest carrying `./blueprint-foo`
+  // keeps its behaviour.
+  if (typeof projectRoot === 'string' && projectRoot.length > 0) {
+    const resolved = await resolveImpl(source, { projectRoot }).catch(() => null);
+    if (resolved && !isRcfError(resolved) && typeof resolved.resolved === 'string') {
+      return resolved.resolved;
+    }
+  }
+  // Fallback: treat as a relative filesystem path against projectRoot.
+  // Matches pre-fix behaviour byte-for-byte; a missing directory
+  // surfaces as `missingSource` via the loader below rather than here.
+  return typeof projectRoot === 'string' && projectRoot.length > 0
+    ? resolve(projectRoot, source)
+    : null;
+}
+
+/**
+ * Load the shipping blueprint's contribution list and build an
+ * applied-id -> source-relative-path index. Falls back to id-based
+ * lookup when positions don't align (a re-apply that added ids will
+ * still resolve the shared prefix).
+ */
+async function loadSourceContributionIndex({ sourceAbs, loadImpl }) {
+  if (!sourceAbs) return null;
+  const loaded = await loadImpl(sourceAbs).catch(() => null);
+  if (!loaded || loaded.kind) return null;
+  const contributions = Array.isArray(loaded.contributions) ? loaded.contributions : [];
+  // Two indexes: exact id match (works whenever the operator used the
+  // default namespace, i.e. shipping id === applied id) and bare-id
+  // suffix match (works when the applied id carries a namespace prefix
+  // over a bare shipping id, e.g. `myproj-application-spa-REQ-001`
+  // over shipping `application-spa-REQ-001`).
+  const exact = new Map();
+  for (const sc of contributions) {
+    if (typeof sc?.id !== 'string' || typeof sc?.path !== 'string') continue;
+    exact.set(sc.id, sc.path);
+  }
+  return {
+    byAppliedId(appliedId) {
+      if (exact.has(appliedId)) return exact.get(appliedId);
+      // Namespace fall-back: strip the leading namespace segment and
+      // retry. The applied stampId only prefixes; it never rewrites
+      // the trailing bare id.
+      const idx = appliedId.indexOf('-');
+      if (idx > 0) {
+        const tail = appliedId.slice(idx + 1);
+        if (exact.has(tail)) return exact.get(tail);
+      }
+      return null;
+    },
+  };
+}
+
+/**
+ * Best-effort node-id existence check against a tree model. Kept here
+ * (not in tree-model.js) so the CLI can validate a --node argument
+ * without pulling the full renderer pipeline in.
+ *
+ * @param {import('#core/store/walker.js').Tree} tree
+ * @param {string} id
+ * @returns {boolean}
+ */
+export function treeHasId(tree, id) {
+  if (!tree || typeof id !== 'string' || id.length === 0) return false;
+  if (tree.byId && typeof tree.byId.get === 'function') return tree.byId.has(id);
+  return false;
+}
+
+/**
+ * Fast async-friendly stat wrapper. Handy for tests that want to prove
+ * the customisation check honours missing files without stubbing the
+ * whole fs module.
+ *
+ * @param {string} abs
+ * @returns {Promise<boolean>}
+ */
+export async function fileExists(abs) {
+  try {
+    const s = await stat(abs);
+    return s.isFile();
+  } catch {
+    return false;
+  }
+}

package/src/view/style.css

@@ -733,3 +733,45 @@ footer {
   details.doc-details > .req-body,
   details.doc-details > .us-body { padding: 0.75rem 1rem; }
 }
+
+/* --------------------------------------------------------------------
+ * Deep-link scope overlay (w-2026-08-30-dave-020)
+ *
+ * When body.rcf-scoped is present the client has applied a URL-driven
+ * scope (blueprint / node). Everything inside #rcf-live-content is
+ * dimmed except:
+ *   - .rcf-in-scope         a doc that IS in the scope set
+ *   - .rcf-scope-ancestor   an ancestor of an in-scope doc (kept full
+ *                           strength so the drill-down chain is legible)
+ *   - .rcf-customised       an in-scope doc whose bytes differ from
+ *                           the shipping blueprint source (a project
+ *                           customisation over the applied contribution)
+ *
+ * Left visible-but-dimmed rather than hidden so the reader can see
+ * where in the tree the scoped set sits.
+ * -------------------------------------------------------------------- */
+
+body.rcf-scoped #rcf-live-content [data-doc-id]:not(.rcf-in-scope):not(.rcf-scope-ancestor) {
+  opacity: 0.28;
+  transition: opacity 120ms ease-in-out;
+}
+body.rcf-scoped #rcf-live-content [data-doc-id].rcf-in-scope {
+  opacity: 1;
+  outline: 2px solid #4c9a2a;
+  outline-offset: 2px;
+}
+body.rcf-scoped #rcf-live-content [data-doc-id].rcf-in-scope.rcf-customised {
+  outline-color: #d68f00;
+  box-shadow: 0 0 0 3px rgba(214, 143, 0, 0.18);
+}
+
+#rcf-scope-banner {
+  margin: 0 0 1rem;
+  padding: 0.5rem 0.8rem;
+  border: 1px solid #d68f00;
+  background: #fff7e6;
+  color: #6b4300;
+  font-size: 0.9rem;
+  border-radius: 4px;
+}
+#rcf-scope-banner a { color: #b03a2e; text-decoration: underline; }