graphlin 0.1.3 → 0.2.1

package/runtime/web/platform.js

@@ -0,0 +1,445 @@
+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';
+
+const DISCOVERY_STATES = ['idle', 'waiting', 'queued', 'running', 'complete', 'partial', 'unavailable'];
+const DISCOVERY_BLOCKED = ['source_consent_required', 'missing_key', 'no_source', 'paused', 'unsupported_service', 'endpoint_unavailable'];
+const DISCOVERY_REASONS = {
+  source_consent_required: 'Architecture discovery needs source-transmission consent. Enable source mode for this project in Graphlin setup.',
+  missing_key: 'Configure a classification service key in Graphlin setup to discover architecture.',
+  no_source: 'No source evidence is available yet. Let Graphlin inspect project files, then try again.',
+  paused: 'Classification is paused. Resume classification to discover architecture.',
+  analysis_failed: 'Architecture discovery could not finish. Try again; supported boundaries remain available.',
+  unsupported_service: 'The configured classification service does not support architecture discovery.',
+  source_changed: 'Source changed during discovery. Boundaries will be checked against current evidence.',
+  partial_coverage: 'Some evidence is unavailable. The shown boundaries cover only inspected evidence.',
+  none_supported: 'No supported application or component boundaries were found. Source scopes remain available.',
+  endpoint_unavailable: 'Architecture discovery requires a newer local service.',
+  request_failed: 'Could not check architecture discovery. Reconnect to the local service or try again.',
+};
+function discoveryStatus(value) {
+  if (!value || !DISCOVERY_STATES.includes(value.status)) throw new Error('invalid_architecture_status');
+  const result = { status: value.status, reason: typeof value.reason === 'string' ? value.reason : '' };
+  for (const name of ['applications', 'components', 'pending', 'inspected', 'total']) {
+    if (Number.isSafeInteger(value[name]) && value[name] >= 0 && value[name] <= 1_000_000) result[name] = value[name];
+  }
+  return result;
+}
+
+export function createViewPlatform({ document, request, onView, onSelect, onFollow = () => {},
+  createFrame = createExtensionFrame, grantPollMs = 2000, architecturePollMs = 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 architectureWatch, architectureState, architectureProject, architectureBusy = false, suspended = false;
+  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() {
+    stopArchitecture();
+    if (grantWatch) { clearTimeout(grantWatch.timer); grantWatch.controller?.abort(); grantWatch = null; }
+    instance?.dispose(); instance = null;
+  }
+  const architectureLive = () => !closed && !suspended && model && active === 'graphlin.c4' && !selection.checkpoint;
+  function stopArchitecture() {
+    if (architectureWatch) {
+      clearTimeout(architectureWatch.timer);
+      clearTimeout(architectureWatch.deadline);
+      architectureWatch.controller?.abort();
+      architectureWatch = null;
+    }
+    architectureBusy = false;
+  }
+  function renderArchitecture() {
+    const shown = active === 'graphlin.c4';
+    $('architecture-discover').hidden = !shown;
+    $('architecture-status').hidden = !shown;
+    const state = architectureState;
+    $('architecture-discover').disabled = !architectureLive() || architectureBusy ||
+      ['queued', 'running'].includes(state?.status) || DISCOVERY_BLOCKED.includes(state?.reason);
+    $('architecture-discover').setAttribute('aria-busy', String(architectureBusy));
+    if (!shown) return;
+    if (selection.checkpoint) {
+      $('architecture-status').textContent = 'Recorded architecture. Return to Live to discover current boundaries.';
+      return;
+    }
+    if (!state) { $('architecture-status').textContent = 'Checking architecture discovery…'; return; }
+    const messages = {
+      idle: 'Ready to discover application and component boundaries for this project.',
+      waiting: 'Waiting for source evidence before architecture discovery can continue.',
+      queued: 'Architecture discovery queued.',
+      running: 'Discovering architecture…',
+      complete: 'Architecture discovery complete.',
+      partial: 'Architecture is partly discovered; some boundaries remain unknown.',
+      unavailable: 'Architecture discovery is unavailable. Check project source settings and the classification service.',
+    };
+    const counts = ['applications', 'components'].filter(name => state[name] !== undefined)
+      .map(name => `${state[name]} ${name}`);
+    if (state.inspected !== undefined && state.total !== undefined) counts.push(`${state.inspected} of ${state.total} inspected`);
+    if (state.pending > 0) counts.push(`${state.pending} pending`);
+    $('architecture-status').textContent = [
+      DISCOVERY_REASONS[state.reason] || messages[state.status], counts.join(' · '),
+    ].filter(Boolean).join(' ');
+  }
+  async function refreshArchitecture(watch, manual = false) {
+    const controller = new AbortController();
+    watch.controller = controller;
+    const deadline = watch.deadline = setTimeout(() => controller.abort(), 8000);
+    try {
+      const result = await request(manual ? '/api/architecture/discover' : '/api/architecture',
+        { signal: controller.signal, ...(manual ? { method: 'POST', body: '{}' } : {}) });
+      if (architectureWatch !== watch || !architectureLive()) return;
+      architectureState = discoveryStatus(manual && !DISCOVERY_STATES.includes(result?.status) ? { status: 'queued' } : result);
+    } catch (error) {
+      if (architectureWatch !== watch || !architectureLive()) return;
+      architectureState = { status: 'unavailable', reason: error.status === 404 ? 'endpoint_unavailable' : 'request_failed' };
+    } finally {
+      clearTimeout(deadline);
+      if (architectureWatch === watch && architectureLive()) {
+        architectureBusy = false;
+        renderArchitecture();
+        if (architectureState?.reason !== 'endpoint_unavailable')
+          watch.timer = setTimeout(() => refreshArchitecture(watch), architecturePollMs);
+      }
+    }
+  }
+  function syncArchitecture() {
+    if (!architectureLive()) stopArchitecture();
+    else if (!architectureWatch) {
+      if (architectureProject !== model.projectId) { architectureState = null; architectureProject = model.projectId; }
+      architectureWatch = {};
+      void refreshArchitecture(architectureWatch);
+    }
+    renderArchitecture();
+  }
+  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';
+    syncArchitecture();
+    $('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('architecture-discover', 'click', () => {
+    if (!architectureLive() || $('architecture-discover').disabled) return;
+    stopArchitecture();
+    architectureBusy = true;
+    architectureState = { status: 'queued' };
+    architectureWatch = {};
+    renderArchitecture();
+    void refreshArchitecture(architectureWatch, 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() { suspended = false; 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() { suspended = true; 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,53 @@
 
 * { 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); }
+.architecture-status { padding: 5px 12px; font-size: 11px; color: var(--muted); border-bottom: 1px solid var(--line); }
+.view-context #architecture-discover { color: var(--blue); border-color: var(--blue); }
+.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 +211,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;