graphlin 0.1.2 → 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;
+}