@clear-capabilities/agentic-security-scanner 0.145.0 → 0.147.5

package/dist/frontend/src/lib/query-language.js

@@ -0,0 +1,240 @@
+// PRD §15.2's query language: a small DSL for filtering the Data Flow
+// Explorer's views (e.g. `class:PCI AND sink:(log,database,external_api)`).
+// This module is ONLY the tokenizer + recursive-descent parser, producing
+// an AST — no evaluation, no UI. A later increment consumes the AST to
+// actually filter a graph/view.
+//
+// Hand-written tokenizer, not regex-based single-pass lexing — the grammar
+// has quoted strings (which must suppress internal `:`/`(`/`)`/`,`
+// interpretation) and needs real position tracking for actionable error
+// messages, both easier to get right with an explicit character-scanning
+// loop.
+//
+// `parseQuery` NEVER throws to its caller, matching `state.js`'s own
+// convention of never letting a malformed/adversarial user-supplied string
+// (there, a URL hash; here, a query string) crash the caller — a bad query
+// returns a structured `{error: {message, pos}}` instead, so a caller can
+// check `.error` and keep the prior state rather than losing the page.
+
+import { isAiRelevantFlow, flowPathNodeIds } from './flow-path.js';
+
+const KEYWORDS = new Set(['and', 'or']);
+
+export function tokenize(input) {
+  const tokens = [];
+  let i = 0;
+  const isFieldChar = (c) => /[a-zA-Z0-9_.]/.test(c);
+
+  while (i < input.length) {
+    const c = input[i];
+    if (c === ' ' || c === '\t' || c === '\n') { i++; continue; }
+    if (c === '(') { tokens.push({ type: 'LPAREN', value: '(', pos: i }); i++; continue; }
+    if (c === ')') { tokens.push({ type: 'RPAREN', value: ')', pos: i }); i++; continue; }
+    if (c === ',') { tokens.push({ type: 'COMMA', value: ',', pos: i }); i++; continue; }
+    if (c === '!' && input[i + 1] === '=') { tokens.push({ type: 'OP', value: '!=', pos: i }); i += 2; continue; }
+    if (c === ':') { tokens.push({ type: 'OP', value: ':', pos: i }); i++; continue; }
+    if (c === '"') {
+      const start = i;
+      i++;
+      let value = '';
+      while (i < input.length && input[i] !== '"') { value += input[i]; i++; }
+      if (input[i] !== '"') return { error: true, pos: start, message: 'unterminated quoted string' };
+      i++; // consume closing quote
+      tokens.push({ type: 'VALUE', value, pos: start });
+      continue;
+    }
+    if (isFieldChar(c)) {
+      const start = i;
+      let word = '';
+      while (i < input.length && isFieldChar(input[i])) { word += input[i]; i++; }
+      const lower = word.toLowerCase();
+      if (lower === 'and') tokens.push({ type: 'AND', value: word, pos: start });
+      else if (lower === 'or') tokens.push({ type: 'OR', value: word, pos: start });
+      else {
+        // A bare word followed by ':' or '!=' is a FIELD; otherwise it's a
+        // TEXT-search VALUE (a later increment evaluates TEXT nodes; the
+        // parser just needs to tell the two shapes apart here by lookahead).
+        const nextNonSpace = input.slice(i).match(/^\s*(:|!=)/);
+        tokens.push({ type: nextNonSpace ? 'FIELD' : 'VALUE', value: word, pos: start });
+      }
+      continue;
+    }
+    return { error: true, pos: i, message: `unexpected character "${c}"` };
+  }
+  return tokens;
+}
+
+// A standard recursive-descent parser: parseOr calls parseAnd repeatedly
+// across OR tokens; parseAnd calls parseAtom repeatedly across explicit AND
+// tokens; parseAtom handles `(expr)`, `field OP value-or-list`, and bare
+// TEXT terms.
+export function parseQuery(input) {
+  if (input.trim() === '') return { ast: null };
+  const tokenResult = tokenize(input);
+  if (!Array.isArray(tokenResult)) return { error: { message: tokenResult.message, pos: tokenResult.pos } };
+  const tokens = tokenResult;
+  let pos = 0;
+
+  function peek() { return tokens[pos]; }
+  function advance() { return tokens[pos++]; }
+  function fail(message) {
+    const t = peek();
+    throw { message, pos: t ? t.pos : input.length };
+  }
+
+  function parseOr() {
+    let node = parseAnd();
+    while (peek()?.type === 'OR') {
+      advance();
+      node = { type: 'OR', left: node, right: parseAnd() };
+    }
+    return node;
+  }
+
+  function parseAnd() {
+    let node = parseAtom();
+    while (peek()?.type === 'AND') {
+      advance();
+      node = { type: 'AND', left: node, right: parseAtom() };
+    }
+    return node;
+  }
+
+  function parseAtom() {
+    const t = peek();
+    if (!t) fail('unexpected end of query');
+    if (t.type === 'LPAREN') {
+      advance();
+      const inner = parseOr();
+      if (peek()?.type !== 'RPAREN') fail('expected closing ")"');
+      advance();
+      return inner;
+    }
+    if (t.type === 'FIELD') {
+      advance();
+      const opToken = advance();
+      if (!opToken || opToken.type !== 'OP') fail(`expected ":" or "!=" after field "${t.value}"`);
+      const values = parseValueList();
+      return { type: 'COMPARISON', field: t.value, op: opToken.value, values };
+    }
+    if (t.type === 'VALUE') {
+      advance();
+      return { type: 'TEXT', value: t.value };
+    }
+    fail(`unexpected token "${t.value}"`);
+  }
+
+  function parseValueList() {
+    if (peek()?.type === 'LPAREN') {
+      advance();
+      const values = [];
+      values.push(expectValue());
+      while (peek()?.type === 'COMMA') { advance(); values.push(expectValue()); }
+      if (peek()?.type !== 'RPAREN') fail('expected closing ")" in value list');
+      advance();
+      return values;
+    }
+    return [expectValue()];
+  }
+
+  function expectValue() {
+    const t = peek();
+    if (!t || t.type !== 'VALUE') fail('expected a value');
+    advance();
+    return t.value;
+  }
+
+  try {
+    const ast = parseOr();
+    if (pos < tokens.length) fail(`unexpected trailing token "${peek().value}"`);
+    return { ast };
+  } catch (e) {
+    if (e && typeof e.message === 'string') return { error: e };
+    throw e; // a genuine bug, not a user-facing parse error — do not swallow
+  }
+}
+
+// AST -> predicate. `compileQuery(ast, graph) -> (flow) -> boolean`. The
+// predicate operates on a FLOW (matching how filtering already works
+// throughout this codebase — Privacy/Inventory both filter at the flow
+// level), with field accessors reaching into the flow's own source/sink
+// nodes, data element, and edges as needed.
+
+// Field name -> accessor function: (graph, flow) -> string[] (the set of
+// real values that field name means for THIS flow — a comparison
+// matches if ANY of a COMPARISON's own `values` appears in this set).
+// Grounded in the parent scoping doc's own real-vs-inert audit — every
+// accessor here reads a field CONFIRMED populated by real scan code.
+const FIELD_ACCESSORS = {
+  class: (graph, flow) => {
+    const de = graph.dataElements.find((d) => flow.dataElementIds.includes(d.id));
+    return de?.dataClasses ?? [];
+  },
+  field: (graph, flow) => {
+    const de = graph.dataElements.find((d) => flow.dataElementIds.includes(d.id));
+    return de?.name ? [de.name] : [];
+  },
+  sink: (graph, flow) => {
+    const sinkNode = graph.nodes.find((n) => n.id === flow.sink);
+    return sinkNode?.subtype ? [sinkNode.subtype] : [];
+  },
+  source: (graph, flow) => {
+    const sourceNode = graph.nodes.find((n) => n.id === flow.source);
+    return sourceNode?.subtype ? [sourceNode.subtype] : [];
+  },
+  'transit.verdict': (graph, flow) => edgeVerdicts(graph, flow, 'transit'),
+  'at_rest.verdict': (graph, flow) => edgeVerdicts(graph, flow, 'atRest'),
+  'handling.verdict': (graph, flow) => edgeVerdicts(graph, flow, 'handling'),
+  policy: (graph, flow) => (flow.policyVerdict ? [flow.policyVerdict] : []),
+  coverage: (graph, flow) => {
+    const pathNodeIds = flowPathNodeIds(graph, flow);
+    return graph.nodes.filter((n) => pathNodeIds.has(n.id)).map((n) => n.coverageStatus);
+  },
+  ai: (graph, flow) => [String(isAiRelevantFlow(graph, flow))],
+  'destination.external': (graph, flow) => {
+    const pathNodeIds = flowPathNodeIds(graph, flow);
+    const anyExternal = graph.nodes.some((n) => pathNodeIds.has(n.id) && n.externality?.value === 'external');
+    return [String(anyExternal)];
+  },
+};
+
+function edgeVerdicts(graph, flow, dimension) {
+  return flow.edgeIds
+    .map((id) => graph.edges.find((e) => e.id === id))
+    .filter(Boolean)
+    .map((e) => e.protection[dimension].verdict);
+}
+
+export function compileQuery(ast, graph) {
+  if (ast === null || ast === undefined) return () => true;
+  return (flow) => evaluateNode(ast, graph, flow);
+}
+
+function evaluateNode(node, graph, flow) {
+  if (node.type === 'AND') return evaluateNode(node.left, graph, flow) && evaluateNode(node.right, graph, flow);
+  if (node.type === 'OR') return evaluateNode(node.left, graph, flow) || evaluateNode(node.right, graph, flow);
+  if (node.type === 'TEXT') return matchesText(graph, flow, node.value);
+  if (node.type === 'COMPARISON') {
+    const accessor = FIELD_ACCESSORS[node.field];
+    if (!accessor) {
+      // Real, reported condition (Step 1's own deliberately-open test) —
+      // throwing here, caught by compileQuery's own caller (Task 4's
+      // query bar), is the chosen mechanism: it surfaces as a real error
+      // to the user rather than silently matching nothing. Document
+      // this choice at the call site too.
+      throw new Error(`unrecognized query field "${node.field}"`);
+    }
+    const realValues = accessor(graph, flow).map((v) => String(v).toLowerCase());
+    const matches = node.values.some((v) => realValues.includes(v.toLowerCase()));
+    return node.op === '!=' ? !matches : matches;
+  }
+  throw new Error(`unknown AST node type "${node.type}"`);
+}
+
+function matchesText(graph, flow, term) {
+  const lower = term.toLowerCase();
+  const sourceLabel = graph.nodes.find((n) => n.id === flow.source)?.label ?? '';
+  const sinkLabel = graph.nodes.find((n) => n.id === flow.sink)?.label ?? '';
+  const de = graph.dataElements.find((d) => flow.dataElementIds.includes(d.id));
+  return [sourceLabel, sinkLabel, de?.name ?? ''].some((s) => s.toLowerCase().includes(lower));
+}

package/dist/frontend/src/lib/row-filters.js

@@ -0,0 +1,43 @@
+// Shared, deduplicated row-vs-active-filters matcher — was previously two
+// near-identical private copies (privacy-view.js's and inventory-view.js's
+// own rowMatchesFilters). Every check here reads a PRE-ATTACHED row
+// property (never the graph directly) — the caller's own row-computation
+// step is responsible for attaching whichever of these properties make
+// sense for that row's own shape (see lib/filter-rail.js's own facet list
+// and each view's own row-building code). A facet whose property the row
+// does not carry AT ALL is skipped (never a hide) — this is what makes it
+// safe for a single shared function to serve row shapes as different as a
+// Privacy flow-row and an Inventory dataElement-row.
+const LIST_FACETS = [
+  ['dataClass', 'dataClasses', true], // true = row property is itself an array (dataClasses), match if ANY overlaps
+  ['protection', 'protectionSummary', false], // false = row property is a single value, match if included in the filter's list
+  ['transitVerdict', 'transitVerdict', false],
+  ['atRestVerdict', 'atRestVerdict', false],
+  ['handlingVerdict', 'handlingVerdict', false],
+  ['sourceCategory', 'sourceCategory', false],
+  ['sinkCategory', 'sinkCategory', false],
+  ['destinationExternality', 'destinationExternality', false],
+  ['policyVerdict', 'policyVerdict', false],
+];
+
+export function matchesFilters(row, filters) {
+  for (const [filterKey, rowProp, rowIsArray] of LIST_FACETS) {
+    const activeValues = filters[filterKey];
+    if (!activeValues?.length) continue; // this facet isn't active at all
+    if (!(rowProp in row)) continue; // row doesn't carry this property — unaffected, not hidden
+    if (rowIsArray) {
+      if (!(row[rowProp] ?? []).some((v) => activeValues.includes(v))) return false;
+    } else {
+      if (row[rowProp] !== undefined && !activeValues.includes(row[rowProp])) return false;
+    }
+  }
+  // Unlike the 9 facets above (list-of-selected-values), `ai` is a single
+  // boolean toggle, matching its existing shape in both views — kept as
+  // its own explicit check, not folded into LIST_FACETS's generic loop,
+  // since it's structurally different (a boolean flag, not a multi-select).
+  // Checked for ANY row carrying `isAiRelevant` — this is the real fix for
+  // Inventory's own previously-missing AI check (its private
+  // rowMatchesFilters never checked `ai` at all; Privacy's did).
+  if (filters.ai && 'isAiRelevant' in row && !row.isAiRelevant) return false;
+  return true;
+}

package/dist/frontend/src/lib/state.js

@@ -0,0 +1,84 @@
+// Shared cross-view selection/filter state, persisted in the URL hash so
+// switching views preserves the selected canonical ID and filters (AC-16),
+// and so state is shareable/bookmarkable without a server. Per PRD §7.11:
+// "URL state contains canonical IDs and non-sensitive filter expressions,
+// never source snippets, field values, or secret-bearing endpoints" — this
+// module only ever carries canonical IDs and filter keys/values the caller
+// supplies, never arbitrary text.
+//
+// `state.filters` is an opaque, caller-defined object — this module never
+// validates individual keys inside it, only that the blob as a whole is
+// valid JSON. Milestone 3, sub-project M3-UX-Query adds `filters.query`
+// (PRD §15.2's query-language string, a plain string) as one more key
+// alongside the pre-existing `dataClass`/`protection`/`ai` keys — it
+// round-trips through the hash for free via the same generic JSON
+// serialize/parse path below, with no code change needed here beyond this
+// note. Validating/parsing the query text itself is `lib/query-language.js`'s
+// and `components/query-bar.js`'s job, not this module's — exactly like
+// `dataClass`/`protection`/`ai` are validated by their own consumers
+// (filter-rail.js, privacy-view.js, inventory-view.js), never here.
+
+const VALID_VIEWS = new Set(['architecture', 'privacy', 'trace', 'inventory']);
+
+// PRD §7.6's own 11 required inventory categories, in the order that
+// section lists them. The canonical id list — inventory-view.js's
+// per-category compute dispatch and its sub-nav strip both key off this
+// exact array, so a rename here must update both call sites too.
+export const INVENTORY_TABLES = Object.freeze([
+  'sources',
+  'sinks',
+  'fields',
+  'externalDestinations',
+  'stores',
+  'aiSystems',
+  'transformations',
+  'unprotectedEdges',
+  'policyPermittedFlows',
+  'manualGovernanceGaps',
+  'unsupportedCandidates',
+]);
+
+const DEFAULT_STATE = Object.freeze({ view: 'architecture', selectedId: null, filters: {}, table: INVENTORY_TABLES[0] });
+
+export function parseStateFromHash(hash) {
+  const raw = String(hash ?? '').replace(/^#/, '');
+  if (!raw) return { ...DEFAULT_STATE, filters: {} };
+
+  let params;
+  try {
+    params = new URLSearchParams(raw);
+  } catch {
+    return { ...DEFAULT_STATE, filters: {} };
+  }
+
+  const view = params.get('view');
+  const selectedId = params.get('selected');
+  const filtersRaw = params.get('filters');
+  const tableRaw = params.get('table');
+
+  let filters = {};
+  if (filtersRaw) {
+    try {
+      const parsed = JSON.parse(filtersRaw);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) filters = parsed;
+    } catch {
+      filters = {};
+    }
+  }
+
+  return {
+    view: VALID_VIEWS.has(view) ? view : DEFAULT_STATE.view,
+    selectedId: selectedId || null,
+    filters,
+    table: INVENTORY_TABLES.includes(tableRaw) ? tableRaw : DEFAULT_STATE.table,
+  };
+}
+
+export function serializeStateToHash(state) {
+  const params = new URLSearchParams();
+  params.set('view', VALID_VIEWS.has(state.view) ? state.view : DEFAULT_STATE.view);
+  if (state.selectedId) params.set('selected', state.selectedId);
+  if (state.filters && Object.keys(state.filters).length > 0) params.set('filters', JSON.stringify(state.filters));
+  if (state.table && state.table !== DEFAULT_STATE.table) params.set('table', state.table);
+  return `#${params.toString()}`;
+}

package/dist/frontend/src/main.js

@@ -0,0 +1,83 @@
+// main.js — Milestone 3, sub-project Wire.
+//
+// The page's real entry point, external to index.html for one reason:
+// index.html's own inline <script type="module"> block would need
+// `script-src 'unsafe-inline'` under the explore server's static-asset CSP
+// (scanner/src/server/static-assets.js's STATIC_CSP_HEADER_VALUE). Moving
+// this logic into its own file, loaded via
+// `<script type="module" src="./src/main.js">`, lets that CSP stay a
+// strict `script-src 'self'` with no exception — see the M3-Wire plan's own
+// "load-bearing correction" on this point.
+//
+// Replaces the old static import of FLAGSHIP_GRAPH with a live fetch
+// against the explore server's own /api/v1/graph endpoint, authenticated
+// via the token carried in the page's own URL fragment. bootstrap() itself
+// is UNCHANGED — it already takes a plain graph object with no assumption
+// about where it came from.
+
+import { bootstrap } from './app.js';
+import { el, clear } from './lib/dom.js';
+import { extractTokenFromFragment, fetchGraph } from './lib/api-client.js';
+
+// Exported for test/golden-state-matrix.test.js (AC-22's "Error" state row)
+// only. This is a disclosed, deliberate choice, not an oversight: Node's
+// stable `node:test` in this repo's Node version (confirmed this session —
+// `node:test`'s `mock` object has no `.module` method here) has no ESM
+// module-mocking primitive, so there is no way to make main.js's real
+// `init()`/fetch-catch path exercise a REAL failing `fetchGraph` without
+// either (a) a network-mocking dependency this repo doesn't otherwise carry,
+// or (b) exporting the real render function and calling it directly with the
+// same message shape `init()`'s own catch block already builds. (b) is the
+// smaller footprint — it adds one keyword to an existing function instead of
+// a parallel test-only reimplementation or a new dependency, and it matches
+// this sub-project's own golden-DOM pattern elsewhere (golden-architecture.
+// test.js / golden-privacy.test.js call the real compute/render functions
+// directly rather than a test double). The exported symbol is the exact
+// function `init()` calls on a fetch failure — no test-only duplicate logic.
+export function showError(rootEl, message) {
+  clear(rootEl);
+  rootEl.appendChild(
+    el('div', { class: 'app-error' }, [
+      el('div', { class: 'app-error__title' }, 'Data Flow Explorer could not load'),
+      el('div', { class: 'app-error__message' }, message),
+    ]),
+  );
+}
+
+async function init() {
+  const rootEl = document.getElementById('app-root');
+
+  const token = extractTokenFromFragment();
+  if (!token) {
+    showError(
+      rootEl,
+      'No session token found in this page’s URL. Start a new session with `agentic-security explore` and open the URL it prints (including the "#token=..." part).',
+    );
+    return;
+  }
+
+  let graph;
+  try {
+    graph = await fetchGraph({ token });
+  } catch (err) {
+    showError(rootEl, `Failed to load the data flow graph: ${err && err.message ? err.message : String(err)}`);
+    return;
+  }
+
+  bootstrap(rootEl, graph);
+}
+
+// Guarded on the mount point actually existing before auto-invoking, rather
+// than calling init() unconditionally: this file's ONLY export
+// (`showError`, above) is imported directly by test/golden-state-matrix.
+// test.js, and importing an ES module always runs its top-level statements
+// — including this one — as a side effect. Without this guard, importing
+// main.js under test/dom-shim.js's minimal document (no `#app-root` element
+// exists, since dom-shim builds a bare virtual tree, not a full page)
+// crashed with an unhandled rejection from `document.getElementById`
+// returning something the rest of init() can't use. The guard is also a
+// real, sensible defensive property outside of tests — this script is never
+// meant to run against a page lacking its own mount point.
+if (typeof document !== 'undefined' && typeof document.getElementById === 'function' && document.getElementById('app-root')) {
+  init();
+}

package/dist/frontend/src/shell.js

@@ -0,0 +1,184 @@
+import { el, clear } from './lib/dom.js';
+import { parseStateFromHash, serializeStateToHash } from './lib/state.js';
+
+const VIEWS = [
+  { id: 'architecture', label: 'Architecture' },
+  { id: 'privacy', label: 'Privacy' },
+  { id: 'trace', label: 'Trace' },
+  { id: 'inventory', label: 'Inventory' },
+];
+
+/**
+ * @param {HTMLElement} rootEl
+ * @param {object} graph - a DataFlowGraph v1 envelope (already validated at build time)
+ * @returns {{
+ *   setActiveView: (viewName: string) => void,
+ *   getState: () => {view: string, selectedId: string|null, filters: object},
+ *   setSelection: (selectedId: string|null) => void,
+ *   setFilters: (filters: object) => void,
+ *   setTable: (tableId: string) => void,
+ *   onStateChange: (listener: (state: object) => void) => (() => void),
+ *   getCanvasEl: () => HTMLElement,
+ *   getInspectorEl: () => HTMLElement,
+ *   getContextRailEl: () => HTMLElement,
+ *   getLeftRailEl: () => HTMLElement,
+ *   getQueryBarEl: () => HTMLElement,
+ *   destroy: () => void,
+ * }}
+ */
+export function mountShell(rootEl, graph) {
+  let state = parseStateFromHash(window.location.hash);
+  let stateChangeListeners = [];
+  let inspectorOverlayOpen = false;
+
+  const shell = el('div', { class: 'shell' });
+  const header = buildHeader(graph);
+  const coverageBanner = buildCoverageBanner(graph);
+  const tabs = buildViewTabs(state.view, (nextView) => {
+    updateState({ ...state, view: nextView });
+  });
+  const leftRail = el('div', { class: 'shell__left-rail' }, 'Filters (wired by the next plan)');
+  const canvas = el('div', { class: 'shell__canvas' });
+  const inspector = el('div', { class: 'shell__inspector', id: 'shell-inspector' }, 'Evidence inspector (wired by the next plan)');
+  const contextRail = el('div', { class: 'shell__context-rail' }, buildContextRailText(graph));
+
+  const inspectorToggle = el(
+    'button',
+    {
+      class: 'shell__inspector-toggle',
+      'aria-expanded': 'false',
+      'aria-controls': 'shell-inspector',
+      onClick: () => {
+        inspectorOverlayOpen = !inspectorOverlayOpen;
+        inspector.setAttribute('data-overlay-open', String(inspectorOverlayOpen));
+        inspectorToggle.setAttribute('aria-expanded', String(inspectorOverlayOpen));
+      },
+    },
+    'Inspector',
+  );
+  tabs.appendChild(inspectorToggle);
+
+  // Milestone 3, sub-project M3-UX-Query, Task 4: the query bar's own real
+  // slot. Placed into the existing view-tabs row (shell__view-tabs) rather
+  // than a new grid region, matching this session's own A11y precedent of
+  // adding a new control into an existing shell row (inspectorToggle,
+  // directly above) instead of widening shell.css's grid-template-areas.
+  const queryBar = el('div', { class: 'shell__query-bar-slot' });
+  tabs.appendChild(queryBar);
+
+  shell.appendChild(header);
+  shell.appendChild(coverageBanner);
+  shell.appendChild(tabs);
+  shell.appendChild(leftRail);
+  shell.appendChild(canvas);
+  shell.appendChild(inspector);
+  shell.appendChild(contextRail);
+
+  clear(rootEl);
+  rootEl.appendChild(shell);
+
+  function notifyStateChange() {
+    const snapshot = { ...state };
+    for (const listener of stateChangeListeners) listener(snapshot);
+  }
+
+  // Shared by setActiveView/setSelection/setFilters/the tab-click handler:
+  // update the closure state, sync the URL hash, refresh the tab UI, notify.
+  function updateState(nextState) {
+    state = nextState;
+    window.location.hash = serializeStateToHash(state);
+    applyActiveTab(tabs, state.view);
+    notifyStateChange();
+  }
+
+  function handleHashChange() {
+    state = parseStateFromHash(window.location.hash);
+    applyActiveTab(tabs, state.view);
+    notifyStateChange();
+  }
+
+  window.addEventListener('hashchange', handleHashChange);
+
+  return {
+    setActiveView(viewName) {
+      updateState({ ...state, view: viewName });
+    },
+    getState() {
+      return { ...state };
+    },
+    setSelection(selectedId) {
+      updateState({ ...state, selectedId });
+    },
+    setFilters(filters) {
+      updateState({ ...state, filters });
+    },
+    setTable(tableId) {
+      updateState({ ...state, table: tableId });
+    },
+    onStateChange(listener) {
+      stateChangeListeners.push(listener);
+      return () => {
+        stateChangeListeners = stateChangeListeners.filter((l) => l !== listener);
+      };
+    },
+    getCanvasEl: () => canvas,
+    getInspectorEl: () => inspector,
+    getContextRailEl: () => contextRail,
+    getLeftRailEl: () => leftRail,
+    getQueryBarEl: () => queryBar,
+    destroy() {
+      window.removeEventListener('hashchange', handleHashChange);
+      stateChangeListeners = [];
+    },
+  };
+}
+
+function buildHeader(graph) {
+  const repo = graph.scope?.repository ?? 'unknown repository';
+  const env = graph.scope?.environment ?? 'unknown environment';
+  const scanStatus = graph.scanHealth?.status ?? 'unknown';
+  const isFixture = graph.scope?.source === 'fixture';
+  return el('div', { class: 'shell__header' }, [
+    el('div', { class: 'shell__header-title' }, 'Data Flow Explorer'),
+    el('div', { class: 'shell__header-meta' }, `${repo} · ${env} · Scan ${scanStatus}`),
+    isFixture ? el('div', { class: 'shell__header-meta', 'data-illustrative': 'true' }, 'Illustrative demo data') : null,
+  ]);
+}
+
+function buildCoverageBanner(graph) {
+  const status = graph.coverage?.status ?? graph.scanHealth?.status;
+  const banner = el('div', { class: 'shell__coverage-banner' }, `Coverage: ${status ?? 'unknown'} — not a complete assessment`);
+  if (status && status !== 'complete') banner.setAttribute('data-visible', 'true');
+  return banner;
+}
+
+function buildViewTabs(activeView, onSelect) {
+  const tabs = el(
+    'div',
+    { class: 'shell__view-tabs', role: 'tablist' },
+    VIEWS.map((v) =>
+      el(
+        'button',
+        {
+          class: 'shell__view-tab',
+          role: 'tab',
+          'aria-selected': String(v.id === activeView),
+          'data-view-id': v.id,
+          onClick: () => onSelect(v.id),
+        },
+        v.label,
+      ),
+    ),
+  );
+  return tabs;
+}
+
+function applyActiveTab(tabsEl, activeView) {
+  for (const btn of tabsEl.querySelectorAll('[data-view-id]')) {
+    btn.setAttribute('aria-selected', String(btn.getAttribute('data-view-id') === activeView));
+  }
+}
+
+export function buildContextRailText(graph) {
+  return `${graph.nodes.length} nodes · ${graph.edges.length} edges · ${graph.flows.length} flows`;
+}