graphlin 0.1.3 → 0.2.0

package/runtime/web/platform.js

@@ -0,0 +1,337 @@
+import { BUILTIN_VIEWS, createBuiltin } from '../visualizers/index.mjs';
+import { createModelClient, modelQuery, hydrateModel } from './model-client.js';
+import { ancestors } from '../visualizers/structure.mjs';
+import { createExtensionFrame } from './extension-frame.js';
+import { DATA_FIELDS, extensionId, digest, id as validId } from '../extensions/contracts.mjs';
+import { filterScene } from './scene.js';
+
+export function createViewPlatform({ document, request, onView, onSelect, onFollow = () => {},
+  createFrame = createExtensionFrame, grantPollMs = 2000 }) {
+  const $ = id => document.getElementById(id);
+  let model, active = 'graphlin.code', instance, installed = [], generation = 0, closed = false;
+  let projectionController;
+  let analysisBusy = false;
+  let grantWatch;
+  let selection = {}, canonicalSelection = null, follow = true, query = '', kinds = null, focusEntityId = null;
+  const settings = new Map(), listeners = [];
+  const ownSettings = () => {
+    if (!settings.has(active)) settings.set(active, { expanded: [], collapsed: [], level: 'applications' });
+    return settings.get(active);
+  };
+  const element = (tag, text) => {
+    const value = document.createElement(tag);
+    if (text !== undefined) value.textContent = text;
+    return value;
+  };
+  const listen = (id, event, handler) => {
+    const node = $(id);
+    if (node) { node.addEventListener(event, handler); listeners.push(() => node.removeEventListener(event, handler)); }
+  };
+  function status(message = '') {
+    $('view-status').textContent = message;
+    $('view-status').hidden = !message;
+    $('view-retry').hidden = !message;
+  }
+  function dispose() {
+    if (grantWatch) { clearTimeout(grantWatch.timer); grantWatch.controller?.abort(); grantWatch = null; }
+    instance?.dispose(); instance = null;
+  }
+  function watchGrant(row) {
+    if (grantWatch?.instance === instance) return;
+    const watch = { instance, id: row.id, digest: row.digest, grant: JSON.stringify(row.grant), timer: null };
+    grantWatch = watch;
+    const check = async () => {
+      if (closed || grantWatch !== watch || instance !== watch.instance) return;
+      watch.controller = new AbortController();
+      try {
+        const response = await request('/api/extensions', { signal: watch.controller.signal });
+        if (closed || grantWatch !== watch) return;
+        const rows = Array.isArray(response) ? response : response.extensions;
+        if (!Array.isArray(rows)) throw new Error('invalid_extension_catalogue');
+        const current = rows.find(value => value.id === watch.id);
+        if (!current || current.digest !== watch.digest || !current.grant?.approved ||
+          JSON.stringify(current.grant) !== watch.grant) {
+          generation++; dispose(); onView({ clear: true });
+          installed = rows; controls();
+          if (current) consent(current);
+          status('Visualizer access or its installed version changed. Review access before continuing.');
+          return;
+        }
+      } catch {
+        if (closed || grantWatch !== watch) return;
+        generation++; dispose(); onView({ clear: true });
+        status('Visualizer access could not be verified. Retry the view after reconnecting.');
+        return;
+      }
+      if (grantWatch === watch) watch.timer = setTimeout(check, grantPollMs);
+    };
+    watch.timer = setTimeout(check, grantPollMs);
+  }
+  function descriptor() { return BUILTIN_VIEWS.find(view => view.id === active) || installed.find(view => view.id === active); }
+  const profilesFor = row => Array.isArray(row?.profiles) ? row.profiles.filter(profile => validId(profile?.id)) : [];
+  function options(select, values, chosen) {
+    const signature = JSON.stringify(values);
+    if (select.dataset.options !== signature) {
+      select.replaceChildren(...values.map(([id, label]) => { const option = element('option', label); option.value = id; return option; }));
+      select.dataset.options = signature;
+    }
+    select.value = chosen || '';
+  }
+  function controls() {
+    options($('visualizer'), [...BUILTIN_VIEWS.map(view => [view.id, view.name]),
+      ...installed.map(view => [view.id, view.manifest.name || view.id])], active);
+    for (const option of $('visualizer').children) option.disabled = !model && option.value !== 'graphlin.code';
+    $('view-context').hidden = !model;
+    $('c4-level-label').hidden = active !== 'graphlin.c4';
+    $('baseline-label').hidden = active !== 'graphlin.changes';
+    $('baseline-create').hidden = active !== 'graphlin.changes';
+    $('baseline-create').disabled = Boolean(selection.checkpoint);
+    const row = descriptor(), profiles = profilesFor(row);
+    $('analysis-controls').hidden = !profiles.length;
+    options($('analysis-profile'), profiles.map(profile => [profile.id,
+      `${profile.id}${row.grant?.profiles?.includes(profile.id) ? '' : ' (approval needed)'}`]),
+    ownSettings().profile || profiles[0]?.id);
+    $('analysis-run').disabled = analysisBusy || Boolean(selection.checkpoint) ||
+      !row?.grant?.approved || !row.grant.profiles?.includes($('analysis-profile').value) || !model?.entities.length;
+    $('c4-level').value = ownSettings().level;
+    const checkpoints = (model?.checkpoints || []).map(checkpoint => [checkpoint.id, checkpoint.label || `Revision ${checkpoint.revision}`]);
+    options($('task-baseline'), [['', 'Choose checkpoint'], ...checkpoints], ownSettings().baseline);
+    options($('model-position'), [['', 'Live'], ...checkpoints], selection.checkpoint);
+    const byId = new Map((model?.entities || []).map(entity => [entity.id, entity]));
+    const path = selection.scope ? [...ancestors(selection.scope, byId).reverse(), selection.scope] : [];
+    const crumbs = [['', 'Project'], ...path.map(id => [id, byId.get(id)?.label || 'Scope'])];
+    const breadcrumbSignature = JSON.stringify(crumbs);
+    if ($('scope-breadcrumbs').dataset.signature === breadcrumbSignature) return;
+    const buttons = crumbs.map(([id, label]) => {
+      const button = element('button', label); button.setAttribute('type', 'button');
+      button.setAttribute('aria-current', id === (selection.scope || '') ? 'location' : 'false');
+      button.addEventListener('click', () => scope(id));
+      return button;
+    });
+    $('scope-breadcrumbs').replaceChildren(...buttons);
+    $('scope-breadcrumbs').dataset.signature = breadcrumbSignature;
+  }
+  function consent(row) {
+    $('extension-access').hidden = false;
+    const key = `${model.projectId}:${row.id}:${row.digest}:${JSON.stringify(row.grant)}`;
+    if ($('extension-access').dataset.key === key) return;
+    $('extension-access').dataset.key = key;
+    $('extension-access-description').textContent = `${row.manifest.name || row.id} can read the selected project data. ` +
+      'Approval applies to this installed version. Source text, excerpts, prompts, and transcripts are never provided.';
+    const capabilities = row.manifest.capabilities || [];
+    const fields = DATA_FIELDS.filter(field => field !== 'checkpoints' &&
+      capabilities.includes(field === 'activity' ? 'activity.read' : 'model.read'));
+    $('extension-fields').replaceChildren(...fields.map(field => {
+      const label = element('label'), checkbox = element('input');
+      checkbox.type = 'checkbox'; checkbox.value = field;
+      checkbox.checked = row.grant ? row.grant.fields?.includes(field) : ['entities', 'relations', 'coverage', 'activity'].includes(field);
+      label.append(checkbox, element('span', field)); return label;
+    }));
+    $('extension-history').checked = row.grant?.history === true;
+    $('extension-history').disabled = !capabilities.includes('history.read');
+    const profiles = profilesFor(row);
+    $('extension-profiles').replaceChildren(...profiles.map(profile => {
+      const label = element('label'), checkbox = element('input');
+      checkbox.type = 'checkbox'; checkbox.value = profile.id;
+      checkbox.checked = row.grant?.profiles?.includes(profile.id) || false;
+      label.append(checkbox, element('span', `Allow ${profile.id} analysis (${(profile.selectors?.fields || []).join(', ') || 'declared fields'})`));
+      return label;
+    }));
+    $('analysis-note').hidden = !profiles.length;
+  }
+  async function catalogue(signal) {
+    try {
+      const result = await request('/api/extensions', { signal });
+      if (closed) return;
+      installed = (Array.isArray(result) ? result : result.extensions || []).filter(row =>
+        extensionId(row.id) && digest(row.digest) && row.manifest?.graphlinApi === '1' &&
+        row.manifest?.modelSchema === '2' && ['custom', 'graphlin-scene'].includes(row.manifest?.renderer?.kind));
+      controls();
+    } catch { /* Older daemons still provide the legacy code map. */ }
+  }
+  async function project(streamed = false, force = false) {
+    if (!model || closed) return;
+    projectionController?.abort();
+    const controller = new AbortController();
+    projectionController = controller;
+    const mine = ++generation, view = descriptor();
+    controls();
+    $('extension-access').hidden = true;
+    if (!view) { dispose(); onView({ clear: true }); status('This visualizer is no longer installed. Choose another view.'); return; }
+    try {
+      let inputModel = model;
+      const inputSettings = { ...ownSettings(), ...selection, query, kinds: kinds ? [...kinds] : null, follow };
+      if (BUILTIN_VIEWS.some(item => item.id === active)) {
+        if (!instance) instance = createBuiltin(active, { root: $('custom-view'), select: onSelect });
+        let baseline;
+        if (active === 'graphlin.changes' && inputSettings.baseline) {
+          const baselineSelection = { ...selection, checkpoint: inputSettings.baseline };
+          const raw = await request(`/api/model/v1/snapshot${modelQuery(baselineSelection)}`, { signal: controller.signal });
+          baseline = await hydrateModel(raw, { request, selection: baselineSelection, signal: controller.signal });
+          if (mine !== generation || closed) return;
+        }
+        const result = await instance.update({ model: inputModel, settings: inputSettings, baseline,
+          apiVersion: 1, projectId: model.projectId, revision: model.revision, viewEpoch: mine });
+        if (mine !== generation || closed) return;
+        if (result.scene) result.scene = filterScene(result.scene, { query, kinds }, inputModel);
+        status();
+        onView({ ...result, model: inputModel, id: active, name: view.name, streamed, force,
+          focusEntityId: streamed ? focusEntityId : null, selection: canonicalSelection });
+      } else {
+        // Re-read catalogue/grant for every delivery; an old row is never a
+        // continuing permission. Clear controlled content before policy refresh.
+        onView({ clear: true });
+        await catalogue(controller.signal);
+        if (mine !== generation || closed) return;
+        const current = installed.find(row => row.id === active);
+        if (!current || current.digest !== view.digest) { dispose(); status('The installed version changed. Select it again to review access.'); return; }
+        if (JSON.stringify(current.grant) !== JSON.stringify(view.grant)) dispose();
+        if (!current.grant?.approved || current.grant.projectId !== model.projectId ||
+          current.grant.digest !== current.digest || (selection.checkpoint && !current.grant.history)) {
+          dispose(); consent(current); status(); return;
+        }
+        inputModel = await request(`/api/extensions/data/${encodeURIComponent(active)}${modelQuery(selection)}`, { signal: controller.signal });
+        if (mine !== generation || closed) return;
+        if (!instance) instance = createFrame({
+          root: $('custom-view'), extension: current, onSelect,
+          onFailure: () => { dispose(); onView({ clear: true }); status('Visualizer stopped. Retry view to restart it.'); },
+        });
+        watchGrant(current);
+        const requestedSelection = inputModel.entities.some(entity => entity.id === canonicalSelection)
+          ? { entityId: canonicalSelection } : null;
+        const result = await instance.update({ model: inputModel, settings: inputSettings, selection: requestedSelection, viewEpoch: mine });
+        if (mine !== generation || closed) return;
+        if (result.scene) result.scene = filterScene(result.scene, { query, kinds }, inputModel);
+        status();
+        onView({ ...result, model: inputModel, id: active, name: current.manifest.name || active, streamed, force,
+          focusEntityId: streamed ? focusEntityId : null, selection: canonicalSelection });
+      }
+    } catch (error) {
+      if (mine !== generation || closed) return;
+      if ([401, 403, 404].includes(error.status)) { dispose(); onView({ clear: true }); }
+      else if (view.manifest) {
+        await choose('graphlin.code');
+        status('The visualizer stopped. Code is shown; select the visualizer to retry.');
+        return;
+      }
+      status('Visualizer unavailable. Retry the view or choose Code.');
+    }
+  }
+  const client = createModelClient({ request, onError: status, onSnapshot(value, streamed) {
+    focusEntityId = null;
+    if (model && streamed && follow && !selection.checkpoint && value.projectId === model.projectId) {
+      const known = new Set(model.entities.map(entity => entity.id));
+      const arrival = value.entities.filter(entity => !known.has(entity.id)).at(-1)?.id;
+      const observed = value.activity.filter(event => event.sequence > model.sequence).at(-1)?.entityIds?.[0];
+      focusEntityId = observed || arrival || null;
+      if (focusEntityId) {
+        const byId = new Map(value.entities.map(entity => [entity.id, entity]));
+        ownSettings().expanded = [...new Set([...ownSettings().expanded, ...ancestors(focusEntityId, byId)])];
+      }
+    }
+    if (model && model.projectId !== value.projectId) {
+      dispose(); settings.clear(); canonicalSelection = null; selection = {};
+      onView({ clear: true });
+    }
+    model = value;
+    void project(streamed);
+  } });
+  function choose(id) {
+    if (id === active) return;
+    if (!model) { $('visualizer').value = 'graphlin.code'; status('Model views require a newer local service. The Code map remains available.'); return; }
+    generation++; dispose(); active = id;
+    onView({ clear: true });
+    return project(false, true);
+  }
+  function scope(id) {
+    selection.scope = id || undefined;
+    generation++; dispose();
+    void client.open(selection);
+  }
+  async function grant(approved) {
+    const row = installed.find(value => value.id === active);
+    if (!row) return;
+    generation++; dispose(); onView({ clear: true });
+    const fields = approved ? [...$('extension-fields').children]
+      .map(label => label.children[0]).filter(input => input.checked).map(input => input.value) : [];
+    const history = approved && $('extension-history').checked;
+    const profiles = approved ? [...$('extension-profiles').children].map(label => label.children[0])
+      .filter(input => input.checked).map(input => input.value) : [];
+    if (history) fields.push('checkpoints');
+    try {
+      await request('/api/extensions/grant', { method: 'POST',
+        body: JSON.stringify({ id: row.id, digest: row.digest, fields, history, approved, profiles }) });
+      await catalogue();
+      if (approved) await project(false, true);
+      else { $('extension-access').hidden = true; status('Access denied. Choose another view.'); }
+    } catch { status('Access could not be updated. Retry after reconnecting.'); }
+  }
+  listen('visualizer', 'change', () => choose($('visualizer').value));
+  listen('view-retry', 'click', () => { dispose(); void client.open(selection); });
+  listen('c4-level', 'change', () => { ownSettings().level = $('c4-level').value; void project(false, true); });
+  listen('task-baseline', 'change', () => { ownSettings().baseline = $('task-baseline').value; void project(false, true); });
+  listen('baseline-create', 'click', async () => {
+    if (selection.checkpoint) return;
+    const button = $('baseline-create');
+    button.disabled = true;
+    try {
+      const marker = await request('/api/model/v1/checkpoints', { method: 'POST',
+        body: JSON.stringify({ label: 'Task baseline', ...(selection.session ? { sessionId: selection.session } : {}) }) });
+      ownSettings().baseline = marker.id || marker.checkpoint?.id || marker.marker?.id;
+      await client.open(selection);
+    } catch { status('The checkpoint could not be saved. Retry after reconnecting.'); }
+    finally { button.disabled = Boolean(selection.checkpoint); }
+  });
+  listen('model-position', 'change', () => {
+    selection.checkpoint = $('model-position').value;
+    controls();
+    void client.open(selection);
+  });
+  listen('follow-agent', 'change', () => { follow = $('follow-agent').checked; onFollow(follow); void project(); });
+  listen('extension-approve', 'click', () => grant(true));
+  listen('extension-deny', 'click', () => grant(false));
+  listen('analysis-profile', 'change', () => { ownSettings().profile = $('analysis-profile').value; controls(); });
+  listen('analysis-access', 'click', () => { const row = descriptor(); if (row?.manifest) consent(row); });
+  listen('analysis-run', 'click', async () => {
+    const row = descriptor(), profile = profilesFor(row).find(profile => profile.id === $('analysis-profile').value);
+    if (analysisBusy || !profile || !row.grant?.approved || !row.grant.profiles?.includes(profile.id) || selection.checkpoint) return;
+    const byId = new Map(model.entities.map(entity => [entity.id, entity]));
+    const candidates = byId.has(canonicalSelection) ? [canonicalSelection] : model.entities
+      .filter(entity => !selection.scope || entity.id === selection.scope || ancestors(entity.id, byId).includes(selection.scope))
+      .map(entity => entity.id);
+    const entityIds = candidates.filter(id => !profile.selectors?.candidateIds?.length || profile.selectors.candidateIds.includes(id)).slice(0, 256);
+    if (!entityIds.length) { status('Select a supported entity in the current scope before running this profile.'); return; }
+    analysisBusy = true; controls();
+    try {
+      const result = await request('/api/extensions/analysis', { method: 'POST',
+        body: JSON.stringify({ id: row.id, digest: row.digest, profileId: profile.id, entityIds, revision: model.revision }) });
+      if (active === row.id && !closed) status(result.status === 'complete' ? 'Analysis complete.'
+        : result.status === 'unavailable' ? 'Analysis is unavailable under the current source-transmission settings or service status.'
+        : 'Analysis requested. Accepted results will arrive with model updates.');
+    } catch {
+      if (active === row.id && !closed) status('Analysis was not accepted. Check profile/data approval and this project’s source-transmission setting.');
+    } finally { analysisBusy = false; if (!closed) controls(); }
+  });
+  controls();
+  return {
+    async start() { if (await client.open(selection)) await catalogue(); },
+    choose,
+    filter(nextQuery, nextKinds) { query = nextQuery; kinds = nextKinds; void project(false, true); },
+    selected(id) { canonicalSelection = id; },
+    scope,
+    session(id) { selection.session = id || undefined; generation++; dispose(); void client.open(selection); },
+    live() { selection.checkpoint = undefined; generation++; dispose(); void client.open(selection); },
+    toggle(id, isCollapsed = true) {
+      const own = ownSettings(), expanded = new Set(own.expanded), collapsed = new Set(own.collapsed);
+      if (!isCollapsed) { expanded.delete(id); collapsed.add(id); }
+      else { expanded.add(id); collapsed.delete(id); }
+      own.expanded = [...expanded]; own.collapsed = [...collapsed];
+      void project(false, true);
+    },
+    close() { closed = true; generation++; projectionController?.abort(); client.close(); dispose(); listeners.forEach(remove => remove()); },
+    suspend() { generation++; projectionController?.abort(); client.suspend(); dispose(); },
+    get active() { return active; },
+    get model() { return model; },
+    get selection() { return selection; },
+  };
+}

package/runtime/web/scene.js

@@ -0,0 +1,111 @@
+import { ancestors, sceneKind } from '../visualizers/structure.mjs';
+
+const SHAPES = {
+  client: 'browser', service: 'component', datastore: 'cylinder', queue: 'queue', external: 'cloud',
+  module: 'rect', function: 'hexagon', class: 'class_box', interface: 'interface_box',
+  event: 'document', configuration: 'parallelogram', package: 'folder', unknown: 'rect', group: 'group',
+};
+
+export function filterScene(scene, { query = '', kinds = null } = {}, model) {
+  if (!query && kinds === null) return scene;
+  const entities = new Map(model.entities.map(entity => [entity.id, entity]));
+  const matches = entityId => {
+    const entity = entities.get(entityId);
+    return entity && (!kinds || kinds.has(entity.kind)) &&
+      `${entity.label} ${entity.qualifiedName || ''}`.toLowerCase().includes(query.toLowerCase());
+  };
+  const retained = new Set(), groups = new Map(scene.groups.map(group => [group.id, group]));
+  const keep = item => {
+    retained.add(item.id);
+    let parent = item.parentId;
+    while (parent && !retained.has(parent)) { retained.add(parent); parent = groups.get(parent)?.parentId; }
+  };
+  scene.nodes.filter(node => matches(node.entityId)).forEach(keep);
+  scene.groups.filter(group => group.entityIds.some(matches) ||
+    (query && group.label.toLowerCase().includes(query.toLowerCase()) &&
+      (!kinds || group.entityIds.some(id => kinds.has(entities.get(id)?.kind))))).forEach(keep);
+  return { ...scene, nodes: scene.nodes.filter(node => retained.has(node.id)),
+    groups: scene.groups.filter(group => retained.has(group.id)),
+    edges: scene.edges.filter(edge => retained.has(edge.source) && retained.has(edge.target)) };
+}
+
+/** Containment uses padding and a title band; sibling boxes never overlap.
+ * Layout algorithms still apply to ordinary flat scenes through the old viewer.
+ */
+export function layoutScene(scene) {
+  const items = new Map([...scene.groups, ...scene.nodes].map(item => [item.id, { ...item }]));
+  const groups = new Set(scene.groups.map(group => group.id)), children = new Map();
+  for (const item of items.values()) {
+    const parent = item.parentId || null;
+    if (!children.has(parent)) children.set(parent, []);
+    children.get(parent).push(item);
+  }
+  function pack(parent, x, y) {
+    const siblings = children.get(parent) || [];
+    let cursorX = x, cursorY = y, rowHeight = 0, maxX = x;
+    const columns = Math.max(1, Math.ceil(Math.sqrt(siblings.length)));
+    siblings.forEach((item, index) => {
+      if (index && index % columns === 0) { cursorX = x; cursorY += rowHeight + 64; rowHeight = 0; }
+      item.x = cursorX; item.y = cursorY;
+      if (groups.has(item.id) && !item.collapsed && children.has(item.id)) {
+        const content = pack(item.id, cursorX + 28, cursorY + 64);
+        item.width = Math.max(246, content.width + 56);
+        item.height = Math.max(144, content.height + 92);
+      } else {
+        item.width = groups.has(item.id) ? Math.max(190, Math.min(300, item.label.length * 8 + 70)) : 190;
+        item.height = 104;
+      }
+      cursorX += item.width + 80; maxX = Math.max(maxX, cursorX - 80);
+      rowHeight = Math.max(rowHeight, item.height);
+    });
+    return { width: maxX - x, height: cursorY - y + rowHeight };
+  }
+  pack(null, 0, 0);
+  return { ...scene, groups: scene.groups.map(group => items.get(group.id)), nodes: scene.nodes.map(node => items.get(node.id)) };
+}
+
+export function sceneGraph(scene, model) {
+  const entities = new Map(model.entities.map(entity => [entity.id, entity]));
+  const relations = new Map(model.relations.map(relation => [relation.id, relation]));
+  const claim = entity => ({
+    sourceRefs: entity?.sourceRefs || [], validity: entity?.validity || 'current',
+    classification: entity?.classification || 'unknown', basis: entity?.basis || 'metadata',
+    evidenceState: entity?.basis === 'parsed' ? 'observed' : 'proposed', activityState: 'idle',
+  });
+  const active = new Map();
+  for (const event of model.activity) for (const id of event.entityIds || []) active.set(id, event.outcome);
+  const nodes = [
+    ...scene.groups.map(group => {
+      const entity = entities.get(group.entityIds[0]);
+      const interpretation = group.membershipId && model.interpretations.find(value => value.id === group.membershipId);
+      return { ...claim(interpretation || entity), ...group, kind: group.kind || entity?.kind || 'unknown',
+        entityId: entity?.id, shape: 'group', isGroup: true, label: group.label,
+        memberCount: group.entityIds.length, activityCount: group.entityIds.filter(id => active.has(id)).length,
+        activityState: 'idle' };
+    }),
+    ...scene.nodes.map(node => {
+      const entity = entities.get(node.entityId);
+      return { ...claim(entity), ...node, kind: entity?.kind || node.kind,
+        shape: node.shape || SHAPES[sceneKind(node.kind)] || 'rect',
+        activityState: active.get(node.entityId) === 'pending' ? 'pending' : active.get(node.entityId) === 'failed' ? 'failed' : 'idle' };
+    }),
+  ].map(node => ({ x: 0, y: 0, ...node }));
+  return { revision: model.revision, nodes, edges: scene.edges.map(edge => ({
+    ...claim(relations.get(edge.relationIds?.[0])), ...edge, relation: edge.kind,
+    label: edge.label || edge.kind.replaceAll('_', ' '),
+    sourceRefs: (edge.relationIds || []).flatMap(id => relations.get(id)?.sourceRefs || []).slice(0, 32),
+  })) };
+}
+
+export function representedSelection(entityId, scene, model) {
+  if (!entityId) return null;
+  const byId = new Map(model.entities.map(entity => [entity.id, entity]));
+  for (const id of [entityId, ...ancestors(entityId, byId)]) {
+    const node = scene.nodes.find(node => node.entityId === id);
+    if (node) return node.id;
+    // Reverse order prefers a deeper group over an outer frame.
+    const group = [...scene.groups].reverse().find(group => group.entityIds.includes(id));
+    if (group) return group.id;
+  }
+  return null;
+}

package/runtime/web/style.css

@@ -15,6 +15,51 @@
 
 * { box-sizing: border-box; }
 [hidden] { display: none !important; }
+.view-context { display: flex; align-items: center; flex-wrap: wrap; gap: 6px 12px; padding: 5px 12px; border-bottom: 1px solid var(--line); font-size: 11px; }
+.view-context label { display: inline-flex; gap: 5px; align-items: center; }
+.view-context select, .view-context button { max-width: 210px; font-size: 11px; min-height: 28px; padding: 3px 7px; color: var(--ink); background: var(--white); border: 1px solid var(--line); border-radius: 5px; }
+#scope-breadcrumbs { display: flex; flex-wrap: wrap; gap: 4px; flex: 1; }
+.view-status, .view-coverage { padding: 4px 12px; font-size: 11px; color: var(--muted); }
+.extension-access { padding: 12px; border-bottom: 1px solid var(--line); background: var(--paper); font-size: 12px; }
+.extension-access p { max-width: 78ch; margin-bottom: 8px; }
+#extension-fields { display: flex; flex-wrap: wrap; gap: 12px; margin-bottom: 8px; }
+#extension-profiles { display: flex; flex-wrap: wrap; gap: 8px 14px; margin: 8px 0; }
+#analysis-controls { display: inline-flex; flex-wrap: wrap; gap: 6px; align-items: center; }
+.diagram-group .group-frame { fill: var(--paper); fill-opacity: .7; stroke: var(--node-ink); stroke-width: 1.5; }
+.diagram-group[data-change="unknown"] .group-frame, .diagram-group[data-change="discovered"] .group-frame { stroke-dasharray: 5 4; }
+.diagram-group[data-change="modified"] .group-frame { stroke: var(--amber); }
+.diagram-group[data-change="added"] .group-frame { stroke: var(--teal); }
+.diagram-group:focus-visible { outline: none; }
+.diagram-group:focus-visible .group-frame, .diagram-group[aria-pressed="true"] .group-frame { stroke: var(--diagram-focus); stroke-width: 3; }
+.diagram-group[data-change="stale"] .group-frame { stroke-dasharray: 7 4; opacity: .65; }
+.group-heading { fill: var(--ink); font: 600 14px var(--body); }
+.group-summary { fill: var(--muted); font: 11px var(--body); }
+.group-toggle { cursor: pointer; }
+.group-toggle rect { fill: var(--white); stroke: var(--line); }
+.group-toggle text { fill: var(--ink); font: 16px var(--body); }
+.group-toggle:focus-visible { outline: none; }
+.group-toggle:focus-visible rect { stroke: var(--diagram-focus); stroke-width: 3; }
+.diagram-node[data-change="added"] .node-shape { stroke: var(--teal); stroke-width: 3; }
+.diagram-node[data-change="discovered"] .node-shape { stroke-dasharray: 3 3; }
+.diagram-node[data-change="modified"] .node-shape { stroke: var(--amber); stroke-width: 3; }
+.diagram-node[data-change="removed"] { opacity: .6; }
+.custom-view { position: absolute; inset: 0; overflow: auto; background: var(--canvas); }
+.custom-view iframe { width: 100%; height: 100%; border: 0; background: var(--canvas); }
+.timeline-note { padding: 14px 18px; font-size: 12px; color: var(--muted); }
+.timeline-events { padding: 0 18px 20px; margin: 0; list-style: none; }
+.timeline-event { display: grid; grid-template-columns: 85px minmax(95px, .7fr) minmax(180px, 2fr) 90px; gap: 6px 12px; align-items: center; padding: 9px 0; border-top: 1px solid var(--line); font-size: 12px; }
+.timeline-event button { text-align: left; padding: 4px 8px; min-height: 30px; }
+.timeline-lane { overflow-wrap: anywhere; }
+.timeline-attribution { grid-column: 3; color: var(--muted); font-size: 11px; }
+.timeline-outcome { color: var(--muted); }
+.timeline-event[data-outcome="failed"] .timeline-outcome { color: var(--red); }
+.timeline-event[data-outcome="succeeded"] .timeline-outcome { color: var(--teal); }
+@media (max-width: 650px) {
+  .timeline-event { grid-template-columns: 75px 1fr; }
+  .timeline-event button, .timeline-attribution { grid-column: 2; }
+  .view-context { gap: 6px; }
+  #scope-breadcrumbs { flex-basis: 100%; }
+}
 body { margin: 0; color: var(--ink); background: var(--paper); font: 14px/1.5 var(--body); }
 button, input, select { font: inherit; }
 button, a, input, select { -webkit-tap-highlight-color: transparent; }
@@ -164,6 +209,10 @@ h1 { font-size: clamp(27px, 2.3vw, 36px); letter-spacing: -1px; font-weight: 650
 .drawing [data-kind="event"], .sidebar-theme [data-kind="event"] { --node-fill: var(--role-event); }
 .drawing [data-kind="configuration"], .sidebar-theme [data-kind="configuration"] { --node-fill: var(--role-configuration); }
 .drawing [data-kind="package"], .sidebar-theme [data-kind="package"] { --node-fill: var(--role-package); }
+.drawing [data-kind="method"] { --node-fill: var(--role-function); }
+.drawing [data-kind="enum"] { --node-fill: var(--role-class); }
+.drawing [data-kind="type_alias"] { --node-fill: var(--role-interface); }
+.drawing [data-kind="namespace"], .drawing [data-kind="directory"], .drawing [data-kind="project"] { --node-fill: var(--role-package); }
 .drawing button:hover:not(:disabled) { background: var(--soft); border-color: var(--diagram-focus); }
 .drawing :is(button, input, select, summary):focus-visible { outline-color: var(--diagram-focus); }
 .drawing-toolbar { display: flex; flex-wrap: wrap; align-items: center; padding: 6px 12px; gap: 6px 18px; background: var(--canvas); border-bottom: 1px solid var(--line); flex-shrink: 0; }

package/schemas/graph.schema.json

@@ -134,7 +134,10 @@
           ]
         },
         "basis": {
-          "const": "jev_interpretation"
+          "enum": [
+            "jev_interpretation",
+            "decision_interpretation"
+          ]
         },
         "sourceRef": {
           "oneOf": [

package/scripts/arguments.mjs

@@ -21,8 +21,12 @@ export function parseArguments(args, { worker = false } = {}) {
       const value = args.shift();
       if (!/^\d{1,5}$/.test(value ?? '') || Number(value) > 65535) throw new Error('invalid_port');
       values.port = Number(value);
+    } else if (argument === '--local-source') {
+      if (seen.has('--allow-source') || seen.has('--no-source')) throw new Error('conflicting_arguments');
+      values.allowSource = false;
+      values.localSource = true;
     } else if (argument === '--allow-source' || argument === '--no-source' && !worker) {
-      if (seen.has(argument === '--allow-source' ? '--no-source' : '--allow-source')) throw new Error('conflicting_arguments');
+      if (seen.has('--local-source') || seen.has(argument === '--allow-source' ? '--no-source' : '--allow-source')) throw new Error('conflicting_arguments');
       values.allowSource = argument === '--allow-source';
     }
     else if (argument === '--persist-evidence') values.persistEvidence = true;

package/scripts/build-packages.mjs

@@ -7,6 +7,7 @@ import { publicPackageFiles, validatePackage } from './validate-packages.mjs';
 
 const SOURCE = fileURLToPath(new URL('../', import.meta.url));
 const SOURCE_DIRECTORIES = ['.claude-plugin', '.codex-plugin', 'skills', 'scripts', 'runtime', 'schemas', 'adapters'];
+const PROTECTED_DIRECTORIES = [...SOURCE_DIRECTORIES, 'docs', 'node_modules'];
 
 async function assertDestination(destination, { directory = false } = {}) {
   const absolute = path.resolve(destination), root = path.parse(absolute).root;
@@ -57,7 +58,7 @@ async function copy(source, destination) {
 export async function buildPackages({ outputDir = path.join(SOURCE, 'dist'), sourceDir = SOURCE } = {}) {
   const source = path.resolve(sourceDir), output = path.resolve(outputDir);
   if (output === source || source.startsWith(`${output}${path.sep}`)) throw new Error('unsafe_output_directory');
-  if (SOURCE_DIRECTORIES.some(file => output === path.join(source, file) || output.startsWith(`${path.join(source, file)}${path.sep}`))) {
+  if (PROTECTED_DIRECTORIES.some(file => output === path.join(source, file) || output.startsWith(`${path.join(source, file)}${path.sep}`))) {
     throw new Error('unsafe_output_directory');
   }
   // Preflight every output before replacing even the first generated profile.
@@ -92,6 +93,9 @@ export async function buildPackages({ outputDir = path.join(SOURCE, 'dist'), sou
     await mkdir(temporary);
     try {
       const profileFiles = files.filter(file => profile === 'claude' || file !== '.claude-plugin/plugin.json');
+      // publicPackageFiles includes every reviewed file of the full pinned
+      // parser under Graphlin's own node_modules. Never resolve a hoisted or
+      // inspected-project dependency, and never copy an arbitrary dependency tree.
       for (const file of profileFiles) await copy(path.join(source, file), path.join(temporary, file));
       const metadata = JSON.parse(await readFile(path.join(temporary, 'package.json'), 'utf8'));
       metadata.files = metadata.files.filter(file => profileFiles.includes(file.slice(2)));
@@ -114,7 +118,7 @@ export async function buildPackages({ outputDir = path.join(SOURCE, 'dist'), sou
         await chmod(path.join(temporary, 'scripts', file), 0o755);
       }
       await writeFile(path.join(temporary, 'PACKAGE-NOTES.md'),
-        `# Graphlin ${profile} package\n\nNode.js 22.14+; macOS/Linux. Self-contained source bundle; no dependency install.\n` +
+        `# Graphlin ${profile} package\n\nNode.js 22.14+; macOS/Linux. Self-contained runtime and parser bundle; no dependency install.\n` +
         'Run scripts/graphlin.mjs --help for local controls. This package does not install itself.\n' +
         'Hook activation/trust has not been certified. Kiro is inactive and experimental.\n' +
         'See adapters/README.md and skills/graphlin/SKILL.md for privacy and coverage.\n');

package/scripts/control.mjs

@@ -39,7 +39,7 @@ async function handle(line) {
     const supported = ['2024-11-05', '2025-03-26', '2025-06-18'];
     return result({ protocolVersion: supported.includes(message.params?.protocolVersion) ? message.params.protocolVersion : '2025-06-18',
       capabilities: { tools: { listChanged: false } },
-      serverInfo: { name: 'graphlin', version: '0.1.3' },
+      serverInfo: { name: 'graphlin', version: '0.2.0' },
       instructions: 'Controls only. Passive host hooks provide observations when separately activated. No drawing calls after each action.' });
   }
   if (message.method === 'ping') return result({});

package/scripts/daemon.mjs

@@ -5,7 +5,8 @@ process.umask(0o077);
 let server;
 try {
   const options = parseArguments(process.argv.slice(2), { worker: true });
-  const policy = { transmitSource: options.allowSource, persistEvidence: options.persistEvidence,
+  const policy = { readSource: options.localSource || options.allowSource,
+    transmitSource: options.allowSource, persistEvidence: options.persistEvidence,
     displayEvidence: options.displayEvidence };
   let decisionService;
   if (options.mode === 'demo') {

package/scripts/extensions.mjs

@@ -0,0 +1,44 @@
+import path from 'node:path';
+import { projectPaths, defaultDataDir } from '../runtime/daemon/paths.mjs';
+import { createExtensionRegistry, extensionError } from '../runtime/extensions/index.mjs';
+
+/** Parent CLI dispatches its already-parsed extension arguments here. This
+ * module neither parses global CLI options nor starts/stops the daemon. */
+export async function runExtensions(args, {
+  projectRoot, dataDir = defaultDataDir(), signal, transport, output = process.stdout,
+  registry: suppliedRegistry,
+} = {}) {
+  if (!Array.isArray(args) || args.some(value => typeof value !== 'string')) throw extensionError('invalid_extension_arguments');
+  const [command = 'list', source, ...rest] = args;
+  if (!['list', 'add', 'update', 'remove', 'doctor', 'dev'].includes(command) || rest.length ||
+    (['add', 'update', 'remove', 'dev'].includes(command) ? !source : source !== undefined)) {
+    throw extensionError('usage_extensions_list_add_update_remove_doctor_dev');
+  }
+  let registry = suppliedRegistry;
+  if (!registry) {
+    const paths = await projectPaths(projectRoot ?? process.cwd(), dataDir);
+    registry = await createExtensionRegistry({ dataDir: paths.dataDir, projectId: paths.projectId, transport });
+  }
+  const resolveSource = value => value.startsWith('.') || path.isAbsolute(value)
+    ? path.resolve(projectRoot ?? process.cwd(), value) : value;
+  let result;
+  if (command === 'list') result = await registry.list();
+  if (command === 'doctor') result = await registry.doctor();
+  if (command === 'remove') result = await registry.remove(source);
+  if (command === 'add' || command === 'update') result = await registry.install(resolveSource(source), { signal });
+  if (command === 'dev') {
+    if (!(source.startsWith('.') || path.isAbsolute(source))) throw extensionError('development_directory_required');
+    result = await registry.dev(resolveSource(source), { signal });
+  }
+  if (output) {
+    if (Array.isArray(result)) output.write(result.length ? result.map(row =>
+      `${row.id} ${row.version} ${row.digest.slice(0, 12)}${row.development ? ' development' : ''} ${row.grant ? 'granted' : 'approval required'}`
+    ).join('\n') + '\n' : 'No visualizer extensions installed.\n');
+    else if (command === 'doctor') output.write(`${result.ok ? 'Extension checks passed.' : 'Extension checks failed.'}\n${
+      result.results.map(row => `${row.id ?? 'catalogue'}: ${row.code}`).join('\n')}${result.results.length ? '\n' : ''}`);
+    else output.write(command === 'remove' ? `Removed ${result.id} and its grants.\n` :
+      `Installed ${result.id} ${result.version}${result.development ? ' (development snapshot)' : ''}. ${
+        result.grant ? 'Existing digest approval retained.' : 'Project approval is required before data delivery.'}\n`);
+  }
+  return result;
+}