graphlin 0.1.2 → 0.2.0

package/runtime/web/extension-frame.js

@@ -0,0 +1,128 @@
+import { validateScene } from '../extensions/scene.mjs';
+import { jsonBytes, id, integer, EXTENSION_LIMITS } from '../extensions/contracts.mjs';
+import { validateMessage } from '../extensions/sdk.mjs';
+
+const CONTEXT = ['instanceId', 'projectId', 'revision', 'viewEpoch', 'requestId'];
+const nonceValue = () => {
+  const bytes = new Uint8Array(24);
+  globalThis.crypto.getRandomValues(bytes);
+  return [...bytes].map(value => value.toString(16).padStart(2, '0')).join('');
+};
+
+/** Only the host's projected-data route supplies `model`. A frame never receives
+ * fetch, cookies, a daemon token, or the host's unprojected snapshot.
+ */
+export function createExtensionFrame({
+  root, extension, onSelect = () => {}, onFailure = () => {},
+  Channel = globalThis.MessageChannel, nonce = nonceValue(), timeout = 5000,
+}) {
+  const frame = root.ownerDocument.createElement('iframe');
+  frame.setAttribute('sandbox', 'allow-scripts');
+  frame.setAttribute('referrerpolicy', 'no-referrer');
+  frame.setAttribute('title', extension.manifest.name || extension.id);
+  frame.setAttribute('src', `/api/extensions/frame/${encodeURIComponent(extension.id)}?nonce=${encodeURIComponent(nonce)}`);
+  const channel = new Channel(), port = channel.port1;
+  let stopped = false, loaded = false, ready = false, requestNumber = 0, pending, latest;
+  const granted = model => extension.grant?.approved === true &&
+    extension.grant.projectId === model?.projectId && extension.grant.extensionId === extension.id &&
+    extension.grant.digest === extension.digest;
+  let readyResolve, readyReject;
+  const readyPromise = new Promise((resolve, reject) => { readyResolve = resolve; readyReject = reject; });
+  // A frame can fail before update attaches its await handler.
+  readyPromise.catch(() => {});
+  const readyTimer = setTimeout(() => fail(new Error('extension_ready_timeout')), timeout);
+  function rejectPending(error) {
+    if (pending) { clearTimeout(pending.timer); pending.reject(error); pending = null; }
+  }
+  function stop(error = new Error('extension_disposed')) {
+    if (stopped) return;
+    stopped = true;
+    clearTimeout(readyTimer);
+    readyReject(error); rejectPending(error);
+    port.onmessage = null; port.close(); channel.port2.close();
+    frame.removeEventListener('load', onLoad); frame.remove();
+    latest = null;
+  }
+  function fail(error) { stop(error); onFailure(); }
+  function onLoad() {
+    if (stopped) return;
+    if (loaded) { fail(new Error('extension_navigated')); return; }
+    loaded = true;
+    // Opaque-origin sandbox recipients require "*"; the exact frame WindowProxy,
+    // a fresh nonce, and the one-use port bind this bootstrap to its document.
+    frame.contentWindow.postMessage({ type: 'graphlin:bootstrap', apiVersion: 1, nonce }, '*', [channel.port2]);
+  }
+  let windowStart = Date.now(), messages = 0;
+  port.onmessage = event => {
+    if (stopped) return;
+    try {
+      if (Date.now() - windowStart > 1000) { windowStart = Date.now(); messages = 0; }
+      if (++messages > 120) throw new Error('extension_message_rate');
+      const message = event.data;
+      jsonBytes(message, EXTENSION_LIMITS.projectionBytes, 'extension_message_limit');
+      if (!ready) {
+        if (!loaded || message?.type !== 'graphlin:ready' || message.apiVersion !== 1 || message.nonce !== nonce)
+          throw new Error('invalid_extension_ready');
+        ready = true; clearTimeout(readyTimer); readyResolve(); return;
+      }
+      if (!message || message.apiVersion !== 1 || !latest ||
+        !CONTEXT.every(key => message[key] === latest.context[key])) return;
+      validateMessage(message, { model: latest.model, context: { apiVersion: 1, ...latest.context } });
+      if (message.type === 'graphlin:select') {
+        const capabilities = extension.manifest.capabilities || [];
+        const field = message.selection?.entityId ? 'entities' : message.selection?.relationId ? 'relations' : 'activity';
+        if (!granted(latest.model) || !capabilities.some(value => ['selection.request', 'inspection.request'].includes(value)) ||
+          !extension.grant.fields?.includes(field) || (field === 'relations' && !extension.grant.fields.includes('entities'))) return;
+        const selection = message.selection;
+        if (selection?.entityId && latest.model.entities.some(entity => entity.id === selection.entityId))
+          onSelect({ entityId: selection.entityId });
+        else if (selection?.relationId && latest.model.relations.some(relation => relation.id === selection.relationId))
+          onSelect({ relationId: selection.relationId });
+        else if (selection?.activityId && latest.model.activity.some(activity => activity.id === selection.activityId))
+          onSelect({ activityId: selection.activityId });
+        return;
+      }
+      if (!pending) return;
+      if (message.type === 'graphlin:status' && message.status === 'busy') return;
+      if (message.type === 'graphlin:status' && message.status === 'error') {
+        rejectPending(new Error('extension_projection_failed')); return;
+      }
+      let result;
+      if (message.type === 'graphlin:scene' && extension.manifest.renderer.kind === 'graphlin-scene')
+        result = { kind: 'scene', scene: validateScene(message.scene, { model: latest.model }) };
+      else if (message.type === 'graphlin:status' && extension.manifest.renderer.kind === 'custom' &&
+        ['ready', 'empty'].includes(message.status) && integer(message.itemCount, 20000))
+        result = { kind: 'custom', status: message.status, itemCount: message.itemCount };
+      else if (message.type === 'graphlin:error') { rejectPending(new Error('extension_projection_failed')); return; }
+      else throw new Error('invalid_extension_response');
+      clearTimeout(pending.timer); const resolve = pending.resolve; pending = null; resolve(result);
+    } catch (error) { fail(error); }
+  };
+  port.start();
+  frame.addEventListener('load', onLoad);
+  root.replaceChildren(frame);
+  return {
+    async update({ model, settings = {}, selection = null, viewEpoch = 0 }) {
+      if (!granted(model)) throw new Error('extension_grant_denied');
+      await readyPromise;
+      if (stopped) throw new Error('extension_disposed');
+      rejectPending(new Error('extension_superseded'));
+      const context = {
+        instanceId: `frame.${nonce}`, projectId: model.projectId, revision: model.revision,
+        viewEpoch, requestId: `request.${++requestNumber}`,
+      };
+      if (!id(context.projectId) || !integer(context.revision)) throw new Error('invalid_extension_context');
+      const message = { type: 'graphlin:project', apiVersion: 1, ...context, model, settings, selection };
+      jsonBytes(message, EXTENSION_LIMITS.projectionBytes);
+      latest = { context, model };
+      return new Promise((resolve, reject) => {
+        pending = { resolve, reject, timer: setTimeout(() => fail(new Error('extension_projection_timeout')), timeout) };
+        port.postMessage(message);
+      });
+    },
+    dispose() {
+      if (!stopped && ready && latest) port.postMessage({ type: 'graphlin:dispose', apiVersion: 1, ...latest.context });
+      stop();
+    },
+  };
+}

package/runtime/web/index.html

@@ -6,8 +6,9 @@
   <meta name="color-scheme" content="light">
   <meta name="darkreader-lock">
   <meta name="referrer" content="no-referrer">
-  <meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src 'self' data:; font-src 'self'; base-uri 'none'; form-action 'none'; object-src 'none'">
+  <meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'self'; frame-src 'self'; img-src 'self' data:; font-src 'self'; base-uri 'none'; form-action 'none'; object-src 'none'">
   <title>Graphlin — Live architecture</title>
+  <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg' viewBox='0 0 32 32'%3E%3Crect x='4' y='3' width='20' height='24' rx='4' fill='white' stroke='%233d60bc' stroke-width='2'/%3E%3Crect x='18' y='18' width='11' height='11' rx='3' fill='%23399783'/%3E%3C/svg%3E">
   <link rel="stylesheet" href="/style.css">
   <script type="module" src="/app.js"></script>
 </head>
@@ -16,6 +17,15 @@
   <div class="page">
     <header class="masthead">
       <a class="brand" href="/" aria-label="Graphlin live viewer"><span class="brand-mark" aria-hidden="true"></span>graphlin</a>
+      <section class="project-details" aria-label="Project and Graphlin version">
+        <p id="project-label" class="project-label">Local project</p>
+        <dl>
+          <div><dt>Branch</dt><dd id="project-branch">Checking…</dd></div>
+          <div class="project-path"><dt>Path</dt><dd id="project-path">Checking…</dd></div>
+          <div><dt>Graphlin</dt><dd id="graphlin-version">Checking…</dd></div>
+        </dl>
+      </section>
+      <button class="update-indicator" id="version-update-indicator" type="button" aria-controls="version-update-guide" hidden>Update available</button>
       <div class="connection" id="connection" data-state="connecting">
         <span class="connection-dot" aria-hidden="true"></span>
         <span id="connection-label" role="status">Connecting to local service</span>
@@ -24,29 +34,7 @@
     </header>
 
     <main id="main">
-      <div class="intro">
-        <div>
-          <h1>Architecture, as it happens.</h1>
-          <p>Follow the work. Inspect the evidence behind each connection.</p>
-        </div>
-        <p id="project-label" class="project-label">Local project</p>
-      </div>
-
-      <section class="project-details" aria-label="Project and Graphlin version">
-        <dl>
-          <div><dt>Branch</dt><dd id="project-branch">Checking…</dd></div>
-          <div class="project-path"><dt>Path</dt><dd id="project-path">Checking…</dd></div>
-          <div><dt>Graphlin</dt><dd id="graphlin-version">Checking…</dd></div>
-        </dl>
-        <p id="version-update-status" role="status">Checking for updates…</p>
-        <details id="version-update-guide" hidden>
-          <summary>How to update</summary>
-          <p id="version-update-steps">Press Ctrl+C in the viewer terminal, then run this command. Start a new Claude Code or Codex session after setup finishes.</p>
-          <pre id="version-update-command" tabindex="0"></pre>
-          <button id="version-update-copy" type="button">Copy update command</button>
-          <span id="version-update-copy-status" role="status"></span>
-        </details>
-      </section>
+      <h1 class="screen-reader">Live architecture workspace</h1>
 
       <div id="demo-banner" class="notice demo-notice" role="status" hidden>
         <strong>Demo session</strong>
@@ -57,34 +45,65 @@
 
       <section class="workspace" aria-label="Session workspace">
         <div class="workspace-toolbar">
+          <label class="session-picker" for="visualizer">
+            <span>View</span>
+            <select id="visualizer" aria-label="Visualizer"><option value="graphlin.code">Code</option></select>
+          </label>
           <label class="session-picker" for="session">
             <span>Session</span>
             <select id="session" disabled><option value="">Waiting for a session</option></select>
           </label>
+          <div class="panel-controls" role="group" aria-label="Workspace panels">
+            <button type="button" id="details-toggle" aria-expanded="false" aria-controls="live-sidebar">Details</button>
+            <button type="button" id="history-toggle" aria-expanded="false" aria-controls="history-panel">History</button>
+            <button type="button" id="activity-toggle" aria-expanded="false" aria-controls="activity-panel">Activity</button>
+          </div>
           <div class="session-actions">
             <button type="button" id="classification-log" aria-haspopup="dialog" aria-controls="diagnostics-dialog">Classification log</button>
-            <button type="button" id="how-to-connect" aria-haspopup="dialog" aria-controls="connection-dialog">How to connect</button>
+            <button type="button" id="how-to-connect" aria-haspopup="dialog" aria-controls="connection-dialog">Connect</button>
             <button type="button" id="pause" aria-describedby="capture-note" disabled>Pause classification</button>
             <button type="button" id="export" disabled>Export JSON</button>
           </div>
         </div>
 
-        <div class="status-strip" aria-label="Capture and classification status">
-          <div class="classification-status">
-            <span class="status-dot" id="classifier-dot" data-state="waiting" aria-hidden="true"></span>
-            <strong id="classifier-label">Waiting for local service</strong>
-            <span id="capture-note">Capture status will appear with the first snapshot.</span>
-          </div>
-          <div class="coverage-status"><span id="coverage-label">Coverage not reported</span><span id="queue-label">No snapshot yet</span></div>
-        </div>
-
-        <div class="workspace-body">
+        <div class="workspace-body" id="workspace-body" data-details-open="false">
           <section class="drawing" id="drawing" data-theme="sketchbook" aria-labelledby="canvas-title">
             <div class="drawing-toolbar">
               <div class="drawing-heading">
                 <h2 id="canvas-title">Live architecture</h2>
                 <span id="revision">Revision —</span>
               </div>
+              <div class="layout-toolbar" role="group" aria-label="Diagram arrangement">
+                <label for="layout">Layout
+                  <select id="layout" aria-describedby="layout-note" disabled>
+                    <option value="hierarchy">Hierarchy top-down</option>
+                    <option value="dependency">Dependency left-right</option>
+                    <option value="grouped">Group by type</option>
+                    <option value="circular">Circular</option>
+                    <option value="grid">Grid</option>
+                    <option value="original">Original</option>
+                  </select>
+                </label>
+                <button type="button" id="arrange" disabled>Arrange</button>
+                <label class="auto-arrange" for="auto-arrange"><input id="auto-arrange" type="checkbox" checked disabled> Auto-arrange</label>
+                <div class="theme-picker">
+                  <label for="theme">Theme
+                    <select id="theme" aria-describedby="theme-note" disabled>
+                      <option value="sketchbook">Sketchbook</option>
+                      <option value="ocean">Ocean</option>
+                      <option value="forest">Forest</option>
+                      <option value="sunset">Sunset</option>
+                      <option value="berry">Berry</option>
+                      <option value="sepia">Sepia</option>
+                      <option value="blueprint">Blueprint dark</option>
+                      <option value="midnight">Midnight dark</option>
+                    </select>
+                  </label>
+                  <span class="theme-preview" aria-hidden="true"><i></i><i></i><i></i><i></i></span>
+                </div>
+                <span class="screen-reader" id="theme-note">Colors follow component types. Themes change appearance only.</span>
+                <span class="screen-reader" id="layout-note">Arranges when components or connections change.</span>
+              </div>
               <div class="zoom-controls" role="group" aria-label="Diagram zoom">
                 <button type="button" id="zoom-out" aria-label="Zoom out" disabled>−</button>
                 <output id="zoom-level" aria-label="Zoom level">100%</output>
@@ -92,44 +111,47 @@
                 <button type="button" id="fit" disabled>Fit</button>
               </div>
             </div>
-            <div class="layout-toolbar" role="group" aria-label="Diagram arrangement">
-              <label for="layout">Layout
-                <select id="layout" disabled>
-                  <option value="hierarchy">Hierarchy top-down</option>
-                  <option value="dependency">Dependency left-right</option>
-                  <option value="grouped">Group by type</option>
-                  <option value="circular">Circular</option>
-                  <option value="grid">Grid</option>
-                  <option value="original">Original</option>
-                </select>
-              </label>
-              <button type="button" id="arrange" disabled>Arrange</button>
-              <label class="auto-arrange" for="auto-arrange"><input id="auto-arrange" type="checkbox" checked disabled> Auto-arrange</label>
-              <div class="theme-picker">
-                <label for="theme">Theme
-                  <select id="theme" aria-describedby="theme-note" disabled>
-                    <option value="sketchbook">Sketchbook</option>
-                    <option value="ocean">Ocean</option>
-                    <option value="forest">Forest</option>
-                    <option value="sunset">Sunset</option>
-                    <option value="berry">Berry</option>
-                    <option value="sepia">Sepia</option>
-                    <option value="blueprint">Blueprint dark</option>
-                    <option value="midnight">Midnight dark</option>
-                  </select>
-                </label>
-                <span class="theme-preview" aria-hidden="true"><i></i><i></i><i></i><i></i></span>
+            <div class="filter-toolbar">
+              <div class="diagram-search-bar" role="search" aria-label="Diagram search">
+                <label class="screen-reader" for="diagram-search">Find components</label>
+                <input id="diagram-search" type="search" maxlength="200" autocomplete="off" spellcheck="false" placeholder="Find components…" aria-controls="architecture" aria-describedby="diagram-search-hint" aria-keyshortcuts="/">
+                <button id="diagram-search-clear" type="button" hidden>Clear search</button>
+                <span class="screen-reader" id="diagram-search-hint">/ to search · Esc to clear</span>
+                <span id="diagram-search-status" role="status" aria-live="polite" aria-atomic="true"></span>
+              </div>
+              <div class="node-type-toolbar" role="group" aria-label="Component type filters">
+                <button type="button" id="node-types-all">All types</button>
+                <button type="button" id="node-types-none">Clear all</button>
+                <div id="node-type-filters" role="group" aria-label="Visible component types"></div>
               </div>
-              <span class="screen-reader" id="theme-note">Colors follow component types. Themes change appearance only.</span>
-              <span id="layout-note">Arranges when components or connections change.</span>
             </div>
-            <div class="diagram-search-bar" role="search" aria-label="Diagram search">
-              <label for="diagram-search">Find components</label>
-              <input id="diagram-search" type="search" maxlength="200" autocomplete="off" spellcheck="false" placeholder="Search labels…" aria-controls="architecture" aria-describedby="diagram-search-hint" aria-keyshortcuts="/">
-              <button id="diagram-search-clear" type="button" hidden>Clear search</button>
-              <span id="diagram-search-hint">/ to search · Esc to clear</span>
-              <span id="diagram-search-status" role="status" aria-live="polite" aria-atomic="true"></span>
+            <div class="view-context" id="view-context" hidden>
+              <nav id="scope-breadcrumbs" aria-label="Source scope"></nav>
+              <label id="c4-level-label" hidden>Level <select id="c4-level">
+                <option value="context">Context</option><option value="applications" selected>Applications / datastores</option>
+                <option value="components">Components</option><option value="code">Code</option>
+              </select></label>
+              <label id="baseline-label" hidden>Baseline <select id="task-baseline"><option value="">Choose checkpoint</option></select></label>
+              <button id="baseline-create" type="button" hidden>Set baseline now</button>
+              <label>Position <select id="model-position"><option value="">Live</option></select></label>
+              <label class="follow-control"><input id="follow-agent" type="checkbox" checked> Follow agent</label>
+              <button id="view-retry" type="button" hidden>Retry view</button>
+              <div id="analysis-controls" hidden>
+                <label>Analysis <select id="analysis-profile" aria-describedby="analysis-note"></select></label>
+                <button id="analysis-run" type="button" aria-describedby="analysis-note">Run analysis</button>
+                <button id="analysis-access" type="button">Manage access</button>
+              </div>
             </div>
+            <p class="view-status" id="view-status" role="status" hidden></p>
+            <section class="extension-access" id="extension-access" aria-label="Visualizer data access" hidden>
+              <p id="extension-access-description"></p>
+              <div id="extension-fields"></div>
+              <label><input type="checkbox" id="extension-history"> Allow retained history</label>
+              <div id="extension-profiles"></div>
+              <p id="analysis-note" hidden>Running an approved profile can send locally filtered source evidence to the configured classification service. This project must already allow source transmission. Approving a visualizer does not enable source transmission. Analysis runs only when you choose Run analysis, using the selected entity or up to 256 entities in the current scope.</p>
+              <button id="extension-approve" type="button">Allow selected data</button>
+              <button id="extension-deny" type="button">Deny access</button>
+            </section>
             <div class="diagram-stage" id="diagram-stage">
               <svg id="architecture" viewBox="0 0 920 510" role="group" tabindex="0" aria-labelledby="diagram-title diagram-desc">
                 <title id="diagram-title">Architecture diagram</title>
@@ -139,11 +161,13 @@
                   <marker id="arrow-proposed" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M 0 0 L 10 5 L 0 10 Z" class="arrow-proposed"></path></marker>
                   <marker id="arrow-stale" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M 0 0 L 10 5 L 0 10 Z" class="arrow-stale"></path></marker>
                 </defs>
+                <g id="group-layer"></g>
                 <g id="edge-layer"></g>
                 <g id="edge-label-layer"></g>
                 <g id="node-layer"></g>
                 <g id="effects-layer" aria-hidden="true" pointer-events="none"></g>
               </svg>
+              <section id="custom-view" class="custom-view" aria-label="Custom visualizer" hidden></section>
               <div class="empty-canvas" id="empty-canvas">
                 <div class="empty-map" aria-hidden="true"><i></i><span></span><i></i></div>
                 <h3 id="empty-title">Your architecture starts here.</h3>
@@ -164,15 +188,30 @@
               </div>
               <span id="graph-count">No components yet</span>
             </div>
-            <details class="shape-key">
-              <summary>Shape key</summary>
-              <div id="shape-key-items"></div>
-              <p>Shapes describe component types. Display overrides change appearance only.</p>
-            </details>
+            <p class="view-coverage" id="view-coverage" role="status" hidden></p>
             <p class="diagram-note" id="diagram-note">Code classification does not establish runtime connectivity.</p>
           </section>
 
-          <aside class="live-sidebar" id="live-sidebar" aria-label="Live activity and evidence">
+          <aside class="live-sidebar" id="live-sidebar" aria-label="Live activity and evidence" hidden>
+            <div class="details-heading" id="details-heading"><h2>Details</h2><button type="button" id="details-close" aria-label="Close details">Close</button></div>
+            <div class="status-strip" aria-label="Capture and classification status">
+              <div class="classification-status">
+                <span class="status-dot" id="classifier-dot" data-state="waiting" aria-hidden="true"></span>
+                <strong id="classifier-label">Waiting for local service</strong>
+                <span id="capture-note">Capture status will appear with the first snapshot.</span>
+              </div>
+              <div class="coverage-status"><span id="coverage-label">Coverage not reported</span><span id="queue-label">No snapshot yet</span></div>
+            </div>
+            <section class="version-details" aria-label="Graphlin updates">
+              <p id="version-update-status" role="status">Checking for updates…</p>
+              <details id="version-update-guide" hidden>
+                <summary>How to update</summary>
+                <p id="version-update-steps">Press Ctrl+C in the viewer terminal, then run this command. Start a new Claude Code or Codex session after setup finishes.</p>
+                <pre id="version-update-command" tabindex="0"></pre>
+                <button id="version-update-copy" type="button">Copy update command</button>
+                <span id="version-update-copy-status" role="status"></span>
+              </details>
+            </section>
             <section class="onboarding" aria-labelledby="onboarding-title">
               <h2 id="onboarding-title">Getting your first shape</h2>
               <ol class="onboarding-progress" aria-label="Observed setup progress">
@@ -193,6 +232,11 @@
               <ol id="sidebar-hook-list" class="hook-receipts" aria-label="Received hooks across this project, newest first"></ol>
             </details>
             <section class="sidebar-history sidebar-theme" id="sidebar-history" data-theme="sketchbook" aria-labelledby="sidebar-change-heading">
+              <details class="shape-key">
+                <summary>Shape key</summary>
+                <div id="shape-key-items"></div>
+                <p>Shapes describe component types. Display overrides change appearance only.</p>
+              </details>
               <div class="sidebar-heading"><h2 id="sidebar-change-heading">Diagram changes</h2><span class="sidebar-count" id="sidebar-change-count">0</span></div>
               <p class="sidebar-note" id="sidebar-change-note">Newest changes first. Select a shape to inspect it, or a revision to replay.</p>
               <p class="sidebar-empty" id="sidebar-change-empty">Shape changes will stack here as this session discovers or changes the architecture.</p>
@@ -212,7 +256,7 @@
           </aside>
         </div>
 
-        <div class="playback">
+        <div class="playback" id="history-panel" role="region" aria-label="Architecture history" hidden>
           <div class="mode-buttons" role="group" aria-label="Architecture view">
             <button id="live" type="button" aria-pressed="true">Live</button>
             <button id="replay" type="button" aria-pressed="false" disabled>Replay</button>
@@ -226,13 +270,12 @@
         </div>
       </section>
 
-      <section class="activity-section" aria-labelledby="activity-heading">
+      <section class="activity-section" id="activity-panel" aria-labelledby="activity-heading" hidden>
         <div class="activity-heading">
           <div><h2 id="activity-heading">Activity stream</h2><p id="activity-note">Observable work, independent of classification.</p></div>
           <span id="activity-count">0 events</span>
-          <button id="activity-toggle" type="button" aria-expanded="true" aria-controls="activity-content">Hide activity log</button>
         </div>
-        <div id="activity-content">
+        <div id="activity-content" hidden>
           <p class="activity-empty" id="activity-empty">No activity received. Start work in a connected agent session; its captured events will appear here.</p>
           <ol id="activity-list" class="activity-list" aria-label="Recent activity, newest first"></ol>
         </div>

package/runtime/web/model-client.js

@@ -0,0 +1,162 @@
+import { id, integer, jsonBytes } from '../extensions/contracts.mjs';
+
+const COLLECTIONS = ['entities', 'relations', 'interpretations', 'activity', 'sessions', 'checkpoints'];
+export const VIEW_MODEL_LIMITS = Object.freeze({
+  entities: 2048, relations: 4096, interpretations: 512, activity: 2048, sessions: 100, checkpoints: 100,
+});
+const stalePage = () => Object.assign(new Error('inconsistent_model_page'), { status: 409 });
+
+export function readModel(value) {
+  if (value?.schemaVersion !== 2 || !id(value.projectId) ||
+    !integer(value.revision) || !integer(value.sequence)) throw new Error('invalid_model');
+  for (const [key, max] of Object.entries({
+    entities: 20000, relations: 40000, interpretations: 512, activity: 2048, sessions: 100, checkpoints: 100,
+  })) if (!Array.isArray(value[key]) || value[key].length > max) throw new Error('invalid_model');
+  jsonBytes(value, 8 * 1024 * 1024);
+  for (const entity of value.entities) if (!id(entity.id) || typeof entity.label !== 'string' ||
+    !Array.isArray(entity.sourceRefs)) throw new Error('invalid_model_entity');
+  if (new Set(value.entities.map(entity => entity.id)).size !== value.entities.length) throw new Error('duplicate_model_entity');
+  if (value.transport && (typeof value.transport.epoch !== 'string' ||
+    !integer(value.transport.sequence) || typeof value.transport.eventId !== 'string')) throw new Error('invalid_model_transport');
+  return value;
+}
+
+export function modelQuery(selection = {}) {
+  const params = new URLSearchParams();
+  for (const key of ['scope', 'session', 'checkpoint']) if (selection[key]) params.set(key, selection[key]);
+  return params.size ? `?${params}` : '';
+}
+
+/** Hydrates one scope, not an unlimited project index. Every cursor is bound by
+ * the server to the same revision, model sequence, policy fingerprint and epoch.
+ */
+export async function hydrateModel(raw, { request, selection = {}, signal,
+  limits = VIEW_MODEL_LIMITS, maxBytes = 6 * 1024 * 1024, fetchPages = true } = {}) {
+  readModel(raw);
+  const result = { ...raw, coverage: { ...raw.coverage }, pages: { ...raw.pages } };
+  let usedBytes = new TextEncoder().encode(JSON.stringify(raw)).length;
+  let incomplete = false;
+  const totals = {}, retained = {};
+  for (const kind of COLLECTIONS) {
+    const pageInfo = raw.pages?.[kind];
+    if (pageInfo && (!integer(pageInfo.total) || pageInfo.total < raw[kind].length ||
+      pageInfo.returned !== raw[kind].length)) throw new Error('invalid_model_pages');
+    const values = raw[kind].slice(0, limits[kind]), seenIds = new Set(values.map(value => value.id));
+    if (seenIds.size !== values.length) throw new Error('duplicate_model_record');
+    totals[kind] = raw.pages?.[kind]?.total ?? raw[kind].length;
+    let cursor = raw.pages?.[kind]?.nextCursor;
+    const seenCursors = new Set();
+    while (fetchPages && cursor && values.length < limits[kind] && usedBytes < maxBytes) {
+      if (typeof cursor !== 'string' || cursor.length > 2048 || seenCursors.has(cursor)) throw new Error('invalid_model_cursor');
+      seenCursors.add(cursor);
+      const params = new URLSearchParams(modelQuery(selection).slice(1));
+      params.set('cursor', cursor); params.set('limit', String(Math.min(200, limits[kind] - values.length)));
+      const page = await request(`/api/model/v1/${kind === 'checkpoints' ? 'history' : kind}?${params}`, { signal });
+      if (signal?.aborted) throw new Error('model_request_cancelled');
+      if (page?.projectId !== raw.projectId || page.revision !== raw.revision || page.sequence !== raw.sequence ||
+        page.transport?.epoch !== raw.transport?.epoch ||
+        JSON.stringify(page.selection) !== JSON.stringify(raw.selection)) throw stalePage();
+      if (page.kind !== kind || !Array.isArray(page.items) || page.items.length > 200 ||
+        page.page?.offset !== values.length || page.page.total !== totals[kind] ||
+        page.page.returned !== page.items.length || (!page.items.length && page.page.nextCursor))
+        throw new Error('invalid_model_page');
+      const bytes = new TextEncoder().encode(jsonBytes(page, 512 * 1024)).length;
+      if (usedBytes + bytes > maxBytes) { incomplete = true; break; }
+      usedBytes += bytes;
+      for (const value of page.items) {
+        if (!id(value?.id) || seenIds.has(value.id)) throw new Error('duplicate_model_record');
+        seenIds.add(value.id); values.push(value);
+      }
+      cursor = page.page.nextCursor;
+      result.pages[kind] = { total: totals[kind], returned: values.length, nextCursor: cursor };
+    }
+    result[kind] = values;
+    retained[kind] = values.length;
+    if (values.length < totals[kind]) incomplete = true;
+  }
+  const ids = new Set(result.entities.map(entity => entity.id));
+  const relations = result.relations.filter(relation => ids.has(relation.source) && ids.has(relation.target));
+  const interpretations = result.interpretations.filter(value => value.entityIds?.every(id => ids.has(id)));
+  if (relations.length !== result.relations.length || interpretations.length !== result.interpretations.length) incomplete = true;
+  result.relations = relations; result.interpretations = interpretations;
+  retained.relations = relations.length; retained.interpretations = interpretations.length;
+  result.partial = incomplete;
+  result.coverage.client = { truncated: incomplete, totals, retained };
+  if (incomplete) result.coverage.truncated = true;
+  return readModel(result);
+}
+
+export function createModelClient({ request, onSnapshot, onError = () => {}, Stream = globalThis.EventSource }) {
+  let epoch = 0, update = 0, stream, controller, hydration, closed = false, selection = {}, latest = null, received = null;
+  function stop() { update++; controller?.abort(); hydration?.abort(); stream?.close(); stream = null; }
+  function duplicate(raw) {
+    const previous = received || latest;
+    if (!previous || previous.projectId !== raw.projectId) return false;
+    if (raw.transport || previous.transport) return raw.transport?.epoch === previous.transport?.epoch &&
+      raw.transport.sequence <= previous.transport.sequence;
+    return raw.sequence <= previous.sequence;
+  }
+  async function accept(raw, streamed = false) {
+    readModel(raw);
+    if (streamed && duplicate(raw)) return;
+    received = raw;
+    hydration?.abort();
+    const active = new AbortController(), mine = ++update;
+    hydration = active;
+    let model, current = raw;
+    for (let attempt = 0; attempt < 3; attempt++) {
+      try {
+        model = await hydrateModel(current, { request, selection, signal: active.signal });
+        break;
+      } catch (error) {
+        if (active.signal.aborted || mine !== update || closed) return;
+        if (error.status !== 409) throw error;
+        current = await request(`/api/model/v1/snapshot${modelQuery(selection)}`, { signal: active.signal });
+      }
+    }
+    // A continuously changing scope can invalidate all page cursors. Its fresh
+    // first page is still consistent; retain it with explicit partial coverage.
+    if (!model) model = await hydrateModel(current, { fetchPages: false });
+    if (active.signal.aborted || mine !== update || closed) return;
+    const sameEpoch = !latest?.transport || latest.transport.epoch === model.transport?.epoch;
+    latest = model;
+    received = model;
+    onSnapshot(model, streamed && sameEpoch);
+  }
+  async function open(next = selection) {
+    selection = { ...next };
+    stop();
+    const mine = ++epoch;
+    controller = new AbortController();
+    try {
+      const model = await request(`/api/model/v1/snapshot${modelQuery(selection)}`, { signal: controller.signal });
+      if (closed || mine !== epoch) return false;
+      await accept(model);
+      if (closed || mine !== epoch) return false;
+      if (!selection.checkpoint && Stream) {
+        const active = new Stream(`/api/model/v1/events${modelQuery(selection)}`, { withCredentials: true });
+        stream = active;
+        active.addEventListener('snapshot', event => {
+          if (closed || stream !== active) return;
+          try {
+            if (event.data.length > 8 * 1024 * 1024) throw new Error('model_too_large');
+            const raw = JSON.parse(event.data);
+            if (event.lastEventId && raw.transport?.eventId !== event.lastEventId) throw new Error('invalid_model_event');
+            void accept(raw, true).catch(() => onError('An invalid model update was ignored. Reconnect to restore the view.'));
+          } catch { onError('An invalid model update was ignored. Reconnect to restore the view.'); }
+        });
+        active.addEventListener('reset', () => { if (stream === active) void open(); });
+        for (const type of ['unavailable', 'closed', 'revoked', 'expired'])
+          active.addEventListener(type, () => { if (stream === active) void open(); });
+        active.addEventListener('error', () => {
+          if (stream === active) onError('Model connection interrupted. The last received view is retained.');
+        });
+      }
+      return true;
+    } catch (error) {
+      if (!closed && mine === epoch && ![404, 405].includes(error.status)) onError('Model views unavailable. The code map remains available.');
+      return false;
+    }
+  }
+  return { open, suspend() { epoch++; stop(); }, close() { closed = true; epoch++; stop(); } };
+}