@mnstry/atelier 0.2.0-alpha.13 → 0.2.0-alpha.15

package/src/graph-workspace/browser/workspace.mjs

@@ -0,0 +1,431 @@
+// Default graph workspace shell: one graph, three rooms (constellation, workbench,
+// review), chosen by a work recipe. Coaches can use it as is, restyle it through a
+// theme, change its recipes, or build their own shell from the same rooms.
+//
+//   const workspace = mountGraphWorkspace(element, {
+//     model,                    // buildWorkspaceModel(...) with positions (layoutWorkspace)
+//     deps,                     // { Sigma, Graph, EdgeArrowProgram, FA2Layout? }
+//     recipes, theme, profile,
+//     storage, draftIdentity,   // optional: where drafts persist and whose they are
+//   })
+//
+// Drafts stay in this tab unless the host names an identity: `draftIdentity`
+// ({ workspace, reader?, ... }) or `profile.id`. With an identity and no storage
+// they persist in this browser; with a host storage port they persist there.
+//
+// One workspace per document (it uses fixed element ids). The host decides what
+// the model contains; nothing here fetches, grants or saves to a source.
+import { createConstellation } from './constellation.mjs'
+import { createWorkbench } from './workbench.mjs'
+import { renderReview } from './review.mjs'
+import { injectGraphWorkspaceStyles } from './styles.mjs'
+import { h, clear } from './dom.mjs'
+import { createDraftStore, readiness, memoryStorage } from '../authoring.mjs'
+import { composeRecipes, availableRecipes } from '../recipes.mjs'
+import { DEFAULT_THEME, validateTheme } from '../theme.mjs'
+
+const fmt = n => n.toLocaleString('en-US')
+const reduced = () => matchMedia('(prefers-reduced-motion: reduce)').matches
+const hasWebGL = () => { try { const c = document.createElement('canvas'); return !!(c.getContext('webgl2') || c.getContext('webgl')) } catch { return false } }
+
+export function applyTheme(theme, scheme, target) {
+  const problems = validateTheme(theme)
+  if (problems.length) throw new TypeError('Theme refused: ' + problems.join('; '))
+  const s = theme.schemes[scheme]
+  for (const [k, v] of Object.entries(s.vars)) target.style.setProperty(k, v)
+  target.dataset.colorScheme = scheme
+  return { ...s.graph, zones: [...s.graph.zones], mode: scheme }
+}
+
+const PRIMARY_LABELS = { search: 'Search', 'open-evidence': 'Open the evidence', 'next-step': 'Next step', walk: 'Walk to a neighbour', review: 'Review the proposal', pick: 'Choose' }
+
+/** Where drafts live. Persistent storage needs an identity so two workspaces never share drafts. */
+function draftStore(options, profile) {
+  const identity = options.draftIdentity ?? (profile.id ? { workspace: String(profile.id) } : null)
+  if (options.storage && !identity) throw new TypeError('A draft storage port needs draftIdentity or profile.id')
+  let storage = options.storage, persistence = options.storage ? (options.persistence ?? 'host') : 'browser'
+  if (!storage && identity) { try { storage = window.localStorage; storage.length } catch { storage = null } }
+  if (!storage || !identity) { storage = memoryStorage(); persistence = 'tab' }
+  const id = identity ?? { workspace: 'this-tab' }
+  const key = options.draftKey ?? 'atelier-graph-workspace:draft:' + encodeURIComponent(JSON.stringify(Object.keys(id).sort().map(k => [k, id[k]])))
+  return createDraftStore({ storage, key, identity: id, persistence })
+}
+
+export function mountGraphWorkspace(root, options) {
+  const {
+    model, deps = null, theme = DEFAULT_THEME, profile = {}, initialRecipe = null, intro = true,
+    webgl = hasWebGL() && !!deps,
+  } = options
+  const recipesAll = options.recipes ?? composeRecipes().recipes
+  const recipes = availableRecipes(recipesAll, model)
+  const byRecipe = new Map(recipes.map(r => [r.id, r]))
+  const vocab = { record: 'record', records: 'records', zone: 'zone', concept: 'concept', model: 'Concepts', ...(profile.vocabulary ?? {}) }
+  injectGraphWorkspaceStyles(root.ownerDocument)
+
+  const byNode = new Map(model.nodes.map(n => [n.id, n]))
+  const state = { recipe: null, room: 'constellation', selected: null, lens: null, questionId: null, conceptId: null, zoneId: null, textView: !webgl, scheme: options.scheme ?? theme.defaultScheme, zonesOn: true, linksOn: true, labelBoost: 1, savedCamera: null }
+  const counters = { dives: 0 }
+  let palette = null, constellation = null
+
+  // ── DOM ──
+  const el = {}
+  const make = (key, tag, props, ...children) => (el[key] = h(tag, props, ...children))
+  clear(root)
+  root.classList.add('atelier-gw')
+  const stage = h('div', { class: 'stage' })
+  stage.append(
+    make('constellation', 'div', { class: 'constellation', role: 'img', 'aria-label': 'Constellation of every record you can read. Use search, the selection card or Text view to move through it by keyboard.' }),
+    h('header', { class: 'top' },
+      h('div', { class: 'menu-wrap', 'data-graph-reserve': '' },
+        make('recipeBtn', 'button', { class: 'pill', type: 'button', 'aria-haspopup': 'menu', 'aria-expanded': 'false' }, h('span', { class: 'emblem', 'aria-hidden': 'true', text: profile.emblem ?? '◌' }), make('recipeLabel', 'span', { text: '' }), h('span', { class: 'caret', 'aria-hidden': 'true', text: '▾' })),
+        make('recipeMenu', 'div', { class: 'menu', role: 'menu', 'aria-label': 'What are you doing?', hidden: true }),
+        make('primaryBtn', 'button', { class: 'pill primary-action', type: 'button', 'data-gw': 'primary' }, '')),
+      make('commandWrap', 'div', { class: 'command-wrap', role: 'search', 'data-graph-reserve': '' },
+        h('label', { class: 'sr-only', for: 'gw-command', text: 'Search or type a command' }),
+        make('command', 'input', { id: 'gw-command', type: 'search', placeholder: 'Search or type a command', autocomplete: 'off', 'aria-autocomplete': 'list' }),
+        h('kbd', { 'aria-hidden': 'true', text: '⌘K' }),
+        make('results', 'ul', { class: 'command-results', role: 'listbox', 'aria-label': 'Results', hidden: true })),
+      h('div', { class: 'top-right', 'data-graph-reserve': '' },
+        make('textToggle', 'button', { class: 'pill', type: 'button', 'aria-pressed': 'false', disabled: !webgl }, 'Text view'),
+        h('div', { class: 'menu-wrap' },
+          make('displayBtn', 'button', { class: 'pill icon', type: 'button', 'aria-haspopup': 'true', 'aria-expanded': 'false', 'aria-label': 'Display' }, '◐'),
+          make('display', 'div', { class: 'menu display', hidden: true },
+            h('p', { class: 'menu-label', text: 'Display' }),
+            make('schemeBtn', 'button', { class: 'menu-item', type: 'button' }, ''),
+            h('label', { class: 'row' }, make('zonesToggle', 'input', { type: 'checkbox', checked: true }), ' Zones'),
+            h('label', { class: 'row' }, make('linksToggle', 'input', { type: 'checkbox', checked: true }), ' Link-only edges'),
+            h('label', { class: 'row col' }, 'Label density ', make('labelsRange', 'input', { type: 'range', min: '0.5', max: '2', step: '0.1', value: '1' })),
+            h('label', { class: 'row' }, make('physicsToggle', 'input', { type: 'checkbox', disabled: reduced() || !deps?.FA2Layout }), ' Let it move'))))),
+    h('footer', { class: 'corner', 'data-graph-reserve': '' }, h('strong', { text: profile.name ?? 'Workspace' }), make('coverage', 'span', {}), make('provenance', 'span', { class: 'provenance', text: profile.provenance ?? '' })),
+    h('div', { class: 'zoom', role: 'group', 'aria-label': 'Zoom', 'data-graph-reserve': '' },
+      make('zoomIn', 'button', { type: 'button', 'aria-label': 'Zoom in' }, '+'), make('zoomOut', 'button', { type: 'button', 'aria-label': 'Zoom out' }, '−'), make('fit', 'button', { type: 'button', 'aria-label': 'Fit the whole graph' }, '⤢')),
+    make('card', 'section', { class: 'card', 'aria-labelledby': 'card-title', hidden: true, 'data-graph-reserve': '' }),
+    make('questionCard', 'section', { class: 'question-card', 'data-gw': 'lens-card', hidden: true, 'data-graph-reserve': '' }),
+    make('textView', 'section', { class: 'text-view', 'aria-label': 'Text view' }),
+    make('workbench', 'section', { class: 'workbench', 'aria-label': 'Workbench', hidden: true }),
+    make('review', 'section', { class: 'review-room', 'aria-label': 'Review', hidden: true }),
+    make('toast', 'div', { class: 'toast', role: 'status', hidden: true }),
+    make('live', 'p', { class: 'sr-only', role: 'status', 'aria-live': 'polite' }))
+  root.append(stage)
+  if (!webgl) root.classList.add('text-mode', 'no-webgl')
+
+  const store = draftStore(options, profile)
+  const announce = text => { el.live.textContent = text }
+  let toastTimer = null
+  const toast = text => { el.toast.textContent = text; el.toast.hidden = false; clearTimeout(toastTimer); toastTimer = setTimeout(() => { el.toast.hidden = true }, 3200) }
+
+  function applyAppearance() {
+    palette = applyTheme(theme, state.scheme, root)
+    constellation?.setPalette(palette)
+    el.schemeBtn.textContent = state.scheme === 'dark' ? 'Light appearance' : 'Dark appearance'
+  }
+  applyAppearance()
+
+  const declared = model.edges.filter(e => e.kind === 'relation').length
+  el.coverage.textContent = `${fmt(model.nodes.length)} ${vocab.records} · ${model.zones.length} ${vocab.zone}s · ${fmt(model.edges.length)} links (${fmt(declared)} declared)${model.coverage.linksOutsideReadableSet ? ` · ${fmt(model.coverage.linksOutsideReadableSet)} point outside what you can read` : ''}`
+
+  const font = getComputedStyle(root).getPropertyValue('--font-sans').trim() || 'system-ui'
+  if (webgl) {
+    constellation = createConstellation({ container: el.constellation, model, palette, font, deps, onSelect: id => select(id), onOpen: id => openWorkbench({ kind: 'record', id }) })
+    if (intro) constellation.intro()
+  }
+  const workbench = createWorkbench({ root: el.workbench, model, palette, store, vocab, onBack: backToConstellation, onReview: () => openReview({ from: 'workbench' }), onShowOnMap: id => backToConstellation().then(() => { select(id); constellation?.showNode(id) }) })
+  el.workbench.hidden = true
+
+  // ── Recipes ──
+  function setRecipe(id) {
+    const recipe = byRecipe.get(id) ?? recipes[0]
+    if (!recipe) return
+    state.recipe = recipe.id
+    el.recipeLabel.textContent = recipe.label
+    el.primaryBtn.textContent = PRIMARY_LABELS[recipe.primary]
+    root.dataset.recipe = recipe.id
+    root.dataset.primary = recipe.primary
+    closeMenus()
+    state.lens = recipe.room === 'constellation' ? recipe.lens : null
+    renderLensCard()
+    if (recipe.room === 'workbench') {
+      // In the workbench the primary action is where focus lands (the top bar sits behind it).
+      const subject = recipe.subject === 'concept' ? { kind: 'concept', id: model.plan.concepts[0].id }
+        : recipe.subject === 'relation' ? { kind: 'relation', id: model.plan.relations[0].id }
+        : { kind: 'record', id: state.selected ?? [...model.nodes].sort((a, b) => b.relationDegree - a.relationDegree || b.degree - a.degree)[0].id }
+      const opened = openWorkbench(subject)
+      if (mounted) opened.then(() => focusPrimary(recipe.primary))
+    } else if (recipe.room === 'review') openReview({ from: 'recipe' })
+    else if (state.room !== 'constellation') backToConstellation()
+    announce(`${recipe.label}. ${recipe.description}`)
+  }
+  function renderLensCard() {
+    el.questionCard.hidden = !state.lens
+    el.questionCard.dataset.lens = state.lens ?? ''
+    if (state.lens !== 'zone') constellation?.setFocusZone(null)
+    if (state.lens === 'question') renderQuestionCard()
+    else if (state.lens === 'concept') renderConceptLens()
+    else if (state.lens === 'zone') renderZoneLens()
+    else { clear(el.questionCard); constellation?.setLens(null) }
+  }
+  function renderConceptLens() {
+    clear(el.questionCard)
+    const plan = model.plan
+    const c = plan.concepts.find(x => x.id === state.conceptId) ?? plan.concepts[0]
+    state.conceptId = c.id
+    const ids = c.declaredBy.filter(id => byNode.has(id))
+    constellation?.setLens(ids)
+    el.questionCard.append(h('p', { class: 'eyebrow', text: `The ${vocab.concept} in view` }),
+      h('select', { 'aria-label': vocab.concept, onchange: e => { state.conceptId = e.target.value; renderConceptLens() } }, plan.concepts.map(x => h('option', { value: x.id, selected: x.id === c.id, text: x.title }))),
+      h('p', { class: 'q-lit', 'data-gw': 'lens-lit', text: ids.length ? `${fmt(ids.length)} ${ids.length === 1 ? vocab.record : vocab.records} declare it.` : 'No record you can read declares it yet.' }),
+      h('button', { class: 'secondary small', type: 'button', onclick: () => openWorkbench({ kind: 'concept', id: c.id }) }, `Refine “${c.title}”`))
+  }
+  function renderZoneLens() {
+    clear(el.questionCard)
+    const z = model.zones.find(x => x.id === state.zoneId) ?? model.zones[0]
+    if (!z) return
+    state.zoneId = z.id
+    constellation?.setLens(null)
+    constellation?.setFocusZone(z.id)
+    el.questionCard.append(h('p', { class: 'eyebrow', text: `The ${vocab.zone} in view` }),
+      h('select', { 'aria-label': vocab.zone, onchange: e => { state.zoneId = e.target.value; renderZoneLens() } }, model.zones.map(x => h('option', { value: x.id, selected: x.id === z.id, text: x.label }))),
+      h('p', { class: 'q-lit', 'data-gw': 'lens-lit', text: `${fmt(z.count)} ${z.count === 1 ? vocab.record : vocab.records}. Others are dimmed, not removed.` }))
+  }
+  function runPrimary() {
+    const recipe = byRecipe.get(state.recipe)
+    if (!recipe) return
+    const a = recipe.primary
+    if (a === 'search') el.command.focus()
+    else if (a === 'pick') el.questionCard.querySelector('select')?.focus()
+    else if (a === 'review') openReview({ from: state.room === 'workbench' ? 'workbench' : 'recipe' })
+    else if (a === 'open-evidence') {
+      const lit = state.lens === 'question' ? questionLit() : state.lens === 'concept' ? (model.plan.concepts.find(c => c.id === state.conceptId)?.declaredBy ?? []).filter(id => byNode.has(id)) : []
+      const first = state.selected && lit.includes(state.selected) ? state.selected : lit[0]
+      if (first) openWorkbench({ kind: 'record', id: first }); else toast('Nothing lit to open yet.')
+    } else if (a === 'next-step' || a === 'walk') {
+      if (state.room === 'workbench') focusPrimary(a)
+      else if (state.selected) openWorkbench({ kind: 'record', id: state.selected }).then(() => focusPrimary(a))
+      else setRecipe(recipe.id)
+    }
+  }
+  function focusPrimary(action) {
+    if (action === 'walk') (el.workbench.querySelector('.wb-neighbour') ?? el.workbench.querySelector('#wb-title'))?.focus()
+    else if (action === 'next-step') el.workbench.querySelector('.wb-sheet textarea, .wb-sheet input, .wb-sheet button.primary')?.focus()
+  }
+  function questionLit() {
+    const plan = model.plan
+    const q = plan.questions.find(x => x.id === state.questionId) ?? plan.questions[0]
+    return [...new Set(q.concepts.flatMap(cid => plan.concepts.find(c => c.id === cid)?.declaredBy ?? []))].filter(id => byNode.has(id))
+  }
+  function renderQuestionCard() {
+    clear(el.questionCard)
+    const plan = model.plan
+    const q = plan.questions.find(x => x.id === state.questionId) ?? plan.questions[0]
+    state.questionId = q.id
+    const ids = new Set(questionLit())
+    constellation?.setLens([...ids])
+    const zones = new Set([...ids].map(id => byNode.get(id).zoneLabel))
+    el.questionCard.append(h('p', { class: 'eyebrow', text: 'The question on the table' }),
+      h('select', { 'aria-label': 'Question', onchange: e => { state.questionId = e.target.value; renderQuestionCard() } }, plan.questions.map(x => h('option', { value: x.id, selected: x.id === q.id, text: x.question }))),
+      h('p', { class: 'q-lit', 'data-gw': 'question-lit', text: ids.size ? `${fmt(ids.size)} ${ids.size === 1 ? vocab.record : vocab.records} declare its concepts, across ${zones.size} ${vocab.zone}${zones.size === 1 ? '' : 's'}.` : 'No record declares its concepts yet. That is an honest unknown, not an empty answer.' }),
+      h('p', { class: 'q-note', text: `Concepts: ${q.concepts.map(cid => plan.concepts.find(c => c.id === cid)?.title).join(', ') || 'none named'}. Lit records carry the concept tag themselves.` }),
+      ids.size && q.concepts[0] ? h('button', { class: 'secondary small', type: 'button', onclick: () => openWorkbench({ kind: 'concept', id: q.concepts[0] }) }, `Refine “${plan.concepts.find(c => c.id === q.concepts[0]).title}”`) : null)
+  }
+
+  // ── Selection and rooms ──
+  function select(id) {
+    state.selected = id
+    constellation?.select(id)
+    renderCard()
+    if (id) announce(`Selected ${model.nodes.find(n => n.id === id)?.title}.`)
+  }
+  function renderCard() {
+    clear(el.card)
+    const n = state.selected && model.nodes.find(x => x.id === state.selected)
+    el.card.hidden = !n
+    if (!n) return
+    const color = palette.zones[(model.zones.find(z => z.id === n.zone)?.index ?? 0) % palette.zones.length]
+    const near = []
+    const seen = new Set()
+    for (const e of model.edges) { const other = e.source === n.id ? e.target : e.target === n.id ? e.source : null; if (other && !seen.has(other)) { seen.add(other); near.push({ id: other, relation: e.kind === 'relation' }) } }
+    near.sort((a, b) => Number(b.relation) - Number(a.relation))
+    el.card.append(
+      h('button', { class: 'card-close', type: 'button', 'aria-label': 'Clear selection', onclick: () => select(null) }, '×'),
+      h('p', { class: 'eyebrow' }, h('i', { class: 'dot', style: `background:${color}` }), `${n.zoneLabel} · ${n.type}`),
+      h('h2', { id: 'card-title', text: n.title }),
+      n.summary ? h('p', { class: 'card-summary', text: n.summary }) : null,
+      h('p', { class: 'card-meta', text: `${n.degree} links · ${n.relationDegree} declared${n.concepts.length ? ' · declares ' + n.concepts.join(', ') : ''}` }),
+      h('div', { class: 'card-actions' },
+        h('button', { class: 'primary', type: 'button', 'data-gw': 'open-selected', onclick: () => openWorkbench({ kind: 'record', id: n.id }) }, 'Open in the workbench'),
+        constellation ? h('button', { class: 'quiet', type: 'button', onclick: () => constellation.showNode(n.id) }, 'Show on map') : null),
+      near.length ? h('details', { class: 'card-neighbours' }, h('summary', { text: `Walk to a neighbour (${near.length})` }),
+        h('ul', {}, near.slice(0, 12).map(x => h('li', {}, h('button', { class: 'link-row', type: 'button', onclick: () => { select(x.id); root.querySelector('#card-title')?.focus() } }, model.nodes.find(m => m.id === x.id).title))))) : null)
+  }
+  async function openWorkbench(subject) {
+    closeMenus()
+    let from = null
+    if (state.room === 'constellation' && constellation) {
+      state.savedCamera = constellation.camera.getState()
+      if (subject.kind === 'record') {
+        const p = constellation.nodeViewport(subject.id), r = el.constellation.getBoundingClientRect()
+        from = p ? { x: r.left + p.x, y: r.top + p.y } : null
+        root.classList.add('diving')
+        await constellation.dive(subject.id)
+      }
+    }
+    counters.dives++
+    state.room = 'workbench'
+    root.dataset.room = 'workbench'
+    root.classList.remove('diving')
+    el.review.hidden = true
+    workbench.open(subject, { from })
+  }
+  async function backToConstellation() {
+    workbench.close()
+    el.review.hidden = true
+    state.room = 'constellation'
+    root.dataset.room = 'constellation'
+    if (constellation && state.savedCamera) await constellation.restore(state.savedCamera)
+    constellation?.refresh()
+  }
+  function openReview({ from = 'workbench' } = {}) {
+    closeMenus()
+    if (state.room === 'workbench' && from !== 'workbench') workbench.close()
+    state.room = 'review'
+    root.dataset.room = 'review'
+    const toWorkbench = () => { el.review.hidden = true; state.room = 'workbench'; root.dataset.room = 'workbench' }
+    renderReview(el.review, {
+      model: { ...model, systemId: profile.id ?? 'workspace' }, store,
+      backLabel: from === 'workbench' ? '← Back to the workbench' : '← Back to the constellation',
+      onBack: () => { if (from === 'workbench') { toWorkbench(); workbench.refresh() } else { el.review.hidden = true; backToConstellation() } },
+      onOpen: s => { toWorkbench(); workbench.open(s) },
+    })
+  }
+
+  // ── Command bar ──
+  function commandResults(query) {
+    const q = query.trim().toLowerCase()
+    const commands = [
+      ...recipes.map(r => ({ kind: 'recipe', id: r.id, label: r.label, hint: r.description })),
+      ...(webgl ? [{ kind: 'command', id: 'text', label: state.textView ? 'Show the constellation' : 'Text view', hint: 'Every record as a structured list' }] : []),
+      { kind: 'command', id: 'scheme', label: state.scheme === 'dark' ? 'Light appearance' : 'Dark appearance', hint: 'Switch appearance' },
+      ...(constellation ? [{ kind: 'command', id: 'fit', label: 'Fit the whole graph', hint: 'Zoom out to everything' }] : []),
+    ]
+    if (!q) return commands.slice(0, 6)
+    const out = commands.filter(c => c.label.toLowerCase().includes(q))
+    for (const c of model.plan?.concepts ?? []) if (c.title.toLowerCase().includes(q)) out.push({ kind: 'concept', id: c.id, label: c.title, hint: 'Concept · refine in the workbench' })
+    for (const x of model.plan?.questions ?? []) if (x.question.toLowerCase().includes(q)) out.push({ kind: 'question', id: x.id, label: x.question, hint: 'Question · light its evidence' })
+    const scored = []
+    for (const n of model.nodes) { const t = n.title.toLowerCase(), at = t.indexOf(q); if (at >= 0) scored.push({ n, score: (at === 0 ? 0 : t[at - 1] === ' ' ? 1 : 2) * 1e6 - n.degree }) }
+    scored.sort((a, b) => a.score - b.score)
+    for (const { n } of scored.slice(0, 8)) out.push({ kind: 'record', id: n.id, label: n.title, hint: n.zoneLabel })
+    return out.slice(0, 10)
+  }
+  function renderCommand() {
+    clear(el.results)
+    const results = commandResults(el.command.value)
+    el.results.hidden = !results.length
+    results.forEach((r, i) => el.results.append(h('li', { role: 'option', 'aria-selected': String(i === 0) }, h('button', { type: 'button', class: 'cmd', dataset: { kind: r.kind, id: r.id }, onclick: () => runCommand(r) },
+      h('span', { class: 'cmd-label', text: r.label }), h('span', { class: 'cmd-hint', text: r.hint })))))
+  }
+  function runCommand(r) {
+    el.command.value = ''
+    el.results.hidden = true
+    if (r.kind === 'recipe') setRecipe(r.id)
+    else if (r.kind === 'concept') openWorkbench({ kind: 'concept', id: r.id })
+    else if (r.kind === 'question') { state.questionId = r.id; const q = recipes.find(x => x.lens === 'question'); if (q) setRecipe(q.id) }
+    else if (r.kind === 'zone') { state.zoneId = r.id; const z = recipes.find(x => x.lens === 'zone'); if (z) setRecipe(z.id) }
+    else if (r.kind === 'record') { if (state.room !== 'constellation') backToConstellation().then(() => select(r.id)); else select(r.id); root.querySelector('#card-title')?.focus() }
+    else if (r.id === 'text') toggleText()
+    else if (r.id === 'scheme') toggleScheme()
+    else if (r.id === 'fit') constellation?.fit()
+  }
+
+  // ── Text view ──
+  function renderTextView() {
+    clear(el.textView)
+    const filter = h('input', { type: 'search', 'data-gw': 'text-filter', placeholder: `Filter ${fmt(model.nodes.length)} ${vocab.records}…`, 'aria-label': `Filter ${vocab.records}` })
+    const lists = h('div', { class: 'tv-lists' })
+    const draw = () => {
+      clear(lists)
+      const q = filter.value.trim().toLowerCase()
+      if (model.plan?.concepts.length) {
+        lists.append(h('h3', { text: vocab.model }), h('ul', { class: 'tv-list' }, model.plan.concepts.filter(c => !q || c.title.toLowerCase().includes(q)).map(c => h('li', {}, h('button', { type: 'button', class: 'tv-item', onclick: () => openWorkbench({ kind: 'concept', id: c.id }) }, h('i', { class: 'dot-concept' }), c.title, h('small', { text: `${c.declaredBy.length} declaring` }))))))
+      }
+      for (const z of model.zones) {
+        const members = model.nodes.filter(n => n.zone === z.id && (!q || n.title.toLowerCase().includes(q)))
+        if (!members.length) continue
+        const d = h('details', { class: 'tv-zone', open: !!q || members.length <= 40 || z.index === 0 })
+        d.append(h('summary', {}, h('i', { class: 'dot', style: `background:${palette.zones[z.index % palette.zones.length]}` }), `${z.label} · ${fmt(members.length)}`))
+        d.append(h('ul', { class: 'tv-list' }, members.map(n => h('li', {}, h('button', { type: 'button', class: 'tv-item', dataset: { id: n.id }, onclick: () => select(n.id) }, n.title, h('small', { text: `${n.type} · ${n.degree} links` }))))))
+        lists.append(d)
+      }
+    }
+    filter.addEventListener('input', draw)
+    el.textView.append(h('h2', { class: 'tv-title', text: 'Text view' }), filter, lists)
+    draw()
+  }
+  function toggleText() {
+    if (!webgl) return
+    state.textView = !state.textView
+    root.classList.toggle('text-mode', state.textView)
+    el.textToggle.setAttribute('aria-pressed', String(state.textView))
+    if (state.textView) el.textView.querySelector('input')?.focus(); else constellation?.refresh()
+  }
+  function toggleScheme() { state.scheme = state.scheme === 'dark' ? 'light' : 'dark'; applyAppearance(); renderTextView(); renderCard(); if (state.room === 'workbench') workbench.refresh() }
+
+  // ── Menus and keys ──
+  function closeMenus() { el.recipeMenu.hidden = true; el.display.hidden = true; el.recipeBtn.setAttribute('aria-expanded', 'false'); el.displayBtn.setAttribute('aria-expanded', 'false') }
+  function toggle(menu, button) { const open = menu.hidden; closeMenus(); menu.hidden = !open; button.setAttribute('aria-expanded', String(open)); if (open) menu.querySelector('button, input')?.focus() }
+  function renderRecipeMenu() {
+    clear(el.recipeMenu)
+    for (const r of recipes) el.recipeMenu.append(h('button', { type: 'button', class: 'menu-item', role: 'menuitemradio', 'aria-checked': String(state.recipe === r.id), dataset: { recipe: r.id }, onclick: () => setRecipe(r.id) }, h('span', { text: r.label }), h('small', { text: r.description })))
+  }
+  const on = (target, type, fn, opts) => { target.addEventListener(type, fn, opts); cleanups.push(() => target.removeEventListener(type, fn, opts)) }
+  const cleanups = []
+  on(el.recipeBtn, 'click', () => { renderRecipeMenu(); toggle(el.recipeMenu, el.recipeBtn) })
+  on(el.primaryBtn, 'click', runPrimary)
+  on(el.displayBtn, 'click', () => toggle(el.display, el.displayBtn))
+  on(el.textToggle, 'click', toggleText)
+  on(el.schemeBtn, 'click', toggleScheme)
+  on(el.zonesToggle, 'change', e => { state.zonesOn = e.target.checked; constellation?.setOption('zonesOn', state.zonesOn) })
+  on(el.linksToggle, 'change', e => { state.linksOn = e.target.checked; constellation?.setOption('linksOn', state.linksOn) })
+  on(el.labelsRange, 'input', e => { state.labelBoost = +e.target.value; constellation?.setOption('labelBoost', state.labelBoost) })
+  on(el.physicsToggle, 'change', e => { e.target.checked = !!constellation?.setPhysics(e.target.checked) })
+  on(el.fit, 'click', () => constellation?.fit())
+  on(el.zoomIn, 'click', () => constellation?.zoom(1.5))
+  on(el.zoomOut, 'click', () => constellation?.zoom(1 / 1.5))
+  on(el.command, 'focus', renderCommand)
+  on(el.command, 'input', renderCommand)
+  on(el.command, 'keydown', e => {
+    const buttons = [...el.results.querySelectorAll('button')]
+    if (e.key === 'Enter') { e.preventDefault(); buttons[0]?.click() }
+    if (e.key === 'ArrowDown') { e.preventDefault(); buttons[0]?.focus() }
+    if (e.key === 'Escape') { el.command.value = ''; el.results.hidden = true; el.command.blur() }
+  })
+  on(el.results, 'keydown', e => {
+    const buttons = [...el.results.querySelectorAll('button')], i = buttons.indexOf(document.activeElement)
+    if (e.key === 'ArrowDown') { e.preventDefault(); buttons[Math.min(buttons.length - 1, i + 1)]?.focus() }
+    if (e.key === 'ArrowUp') { e.preventDefault(); (i <= 0 ? el.command : buttons[i - 1]).focus() }
+    if (e.key === 'Escape') { el.results.hidden = true; el.command.focus() }
+  })
+  on(root.ownerDocument, 'click', e => { if (!el.commandWrap.contains(e.target)) el.results.hidden = true; if (!e.target.closest('.atelier-gw .menu-wrap')) closeMenus() })
+  on(root.ownerDocument, 'keydown', e => {
+    if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'k') { e.preventDefault(); el.command.focus(); return }
+    if (e.target.closest?.('input, textarea, select') || e.metaKey || e.ctrlKey || e.altKey) return
+    if (e.key === '/') { e.preventDefault(); el.command.focus() }
+    else if (e.key === 'Escape') { if (!el.recipeMenu.hidden || !el.display.hidden) closeMenus(); else if (state.room === 'review') root.querySelector('#review-back')?.click(); else if (state.room === 'workbench') backToConstellation(); else select(null) }
+    else if (e.key === 't') { e.preventDefault(); toggleText() }
+    else if (e.key === 'o' && state.selected && state.room === 'constellation') openWorkbench({ kind: 'record', id: state.selected })
+  })
+
+  let mounted = false
+  renderTextView()
+  setRecipe(byRecipe.has(initialRecipe) ? initialRecipe : recipes[0]?.id)
+  mounted = true
+
+  return {
+    get state() { return { ...state, savedCamera: undefined, counters: { ...counters }, webgl, records: model.nodes.length, links: model.edges.length, workbench: workbench.subject, camera: constellation ? constellation.camera.getState() : null, draftStatus: store.status, draftPersistence: store.persistence } },
+    recipes, store, constellation, workbench,
+    select, openWorkbench, openReview, setRecipe, runPrimary, backToConstellation, toggleText,
+    setScheme(scheme) { state.scheme = scheme; applyAppearance() },
+    readiness: () => readiness(model.plan, store, new Set(model.nodes.map(n => n.id))).status,
+    destroy() { for (const fn of cleanups.splice(0)) fn(); constellation?.kill(); clear(root); root.classList.remove('atelier-gw') },
+  }
+}

package/src/graph-workspace/disclosure.mjs

@@ -0,0 +1,39 @@
+// Shippable-content gate for layered systems. When a coach or owner builds on top of
+// private workspaces, the shareable layer must not carry anything from them.
+// fingerprintsFrom() derives distinctive strings from a private knowledge graph and
+// plan (ids, paths, long titles, summary openings, plan wording, names);
+// scanForFingerprints() reports where any of them occurs in shareable text.
+// Findings name the file and a masked sample, never the full matched content.
+
+export function fingerprintsFrom({ graph = null, plan = null, names = [], extra = [] } = {}) {
+  const out = new Set()
+  const add = v => { if (typeof v === 'string' && v.trim().length >= 8) out.add(v.trim()) }
+  const distinctive = t => typeof t === 'string' && (t.length >= 24 || t.trim().split(/\s+/).length >= 4)
+  for (const n of graph?.nodes ?? []) {
+    add(n.id); add(n.path)
+    if (distinctive(n.title)) add(n.title)
+    const first = (n.summary ?? '').split('\n')[0]
+    if (first.length >= 40) add(first.slice(0, 60))
+  }
+  for (const c of plan?.concepts ?? []) for (const v of [c.definition, c.identityRule]) if ((v ?? '').length >= 30) add(v.slice(0, 60))
+  for (const q of plan?.questions ?? []) add(q.question ?? q.title)
+  for (const v of names) add(v)
+  for (const v of extra) if (typeof v === 'string' && v.length >= 4) out.add(v)
+  return [...out]
+}
+
+const mask = f => f.length > 10 ? `${f.slice(0, 4)}…${f.slice(-3)} (${f.length} chars)` : '(short value)'
+
+/** files: [{ path, text }]. Returns { ok, scanned, findings: [{ path, sample }] }. */
+export function scanForFingerprints(files, fingerprints) {
+  const byPrefix = new Map()
+  for (const f of fingerprints) { const k = f.slice(0, 6); if (!byPrefix.has(k)) byPrefix.set(k, []); byPrefix.get(k).push(f) }
+  const findings = []
+  for (const file of files) {
+    for (const [prefix, list] of byPrefix) {
+      if (!file.text.includes(prefix)) continue
+      for (const f of list) if (file.text.includes(f)) findings.push({ path: file.path, sample: mask(f) })
+    }
+  }
+  return { ok: findings.length === 0, scanned: files.length, findings }
+}

package/src/graph-workspace/geometry.mjs

@@ -0,0 +1,78 @@
+// Presentation geometry for the constellation. Positions are presentation only:
+// distance never asserts a relation. The force layout itself is injected so this
+// package carries no layout dependency; any ForceAtlas2-compatible function works.
+
+function prng(seed) { let s = seed >>> 0; return () => { s = (s + 0x6D2B79F5) >>> 0; let t = s; t = Math.imul(t ^ (t >>> 15), t | 1); t ^= t + Math.imul(t ^ (t >>> 7), t | 61); return ((t ^ (t >>> 14)) >>> 0) / 4294967296 } }
+
+/** Zone-seeded starting positions, deterministic for a seed. */
+export function seedPositions(model, { seed = 3 } = {}) {
+  const rnd = prng(seed)
+  const n = Math.max(1, model.zones.length)
+  const index = new Map(model.zones.map(z => [z.id, z.index]))
+  const out = new Map()
+  for (const node of model.nodes) {
+    const zi = index.get(node.zone) ?? 0
+    const angle = (zi / n) * Math.PI * 2
+    const r = 60 + zi * 6
+    out.set(node.id, { x: Math.cos(angle) * r + (rnd() - 0.5) * 40, y: Math.sin(angle) * r + (rnd() - 0.5) * 40 })
+  }
+  return out
+}
+
+/** Edge weights for a force layout: declared relations pull hardest, written links least. */
+export const LAYOUT_WEIGHTS = Object.freeze({ relation: 1, containment: 0.45, link: 0.22 })
+
+/**
+ * Run an injected force layout and write normalised x/y onto model nodes.
+ * `Graph` is a graphology constructor; `forceAtlas2` the graphology-layout-forceatlas2 default export.
+ */
+export function layoutWorkspace(model, { Graph, forceAtlas2, seed = 3, iterations = 700, settings = {} }) {
+  if (typeof Graph !== 'function' || typeof forceAtlas2?.assign !== 'function') throw new TypeError('Inject a graphology Graph and a ForceAtlas2 implementation')
+  const graph = new Graph({ type: 'directed', multi: true, allowSelfLoops: false })
+  const start = seedPositions(model, { seed })
+  for (const node of model.nodes) graph.addNode(node.id, { ...start.get(node.id), size: 1 + Math.sqrt(node.degree) })
+  for (const e of model.edges) graph.addEdge(e.source, e.target, { weight: LAYOUT_WEIGHTS[e.kind] ?? 0.22 })
+  const resolved = { ...forceAtlas2.inferSettings(graph), linLogMode: true, outboundAttractionDistribution: true, adjustSizes: false, barnesHutOptimize: graph.order > 600, barnesHutTheta: 0.6, gravity: 0.12, scalingRatio: 14, slowDown: 2, edgeWeightInfluence: 1, ...settings }
+  forceAtlas2.assign(graph, { iterations, settings: resolved, getEdgeWeight: 'weight' })
+  const positions = new Map()
+  graph.forEachNode((id, a) => positions.set(id, { x: a.x, y: a.y }))
+  normalizePositions(model, positions)
+  return { algorithm: 'forceatlas2-linlog', iterations, settings: resolved }
+}
+
+/** Fit positions into a stable 1000-unit frame centred on the origin and write them onto nodes. */
+export function normalizePositions(model, positions) {
+  let minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity
+  for (const p of positions.values()) { minX = Math.min(minX, p.x); maxX = Math.max(maxX, p.x); minY = Math.min(minY, p.y); maxY = Math.max(maxY, p.y) }
+  const scale = 1000 / Math.max(maxX - minX, maxY - minY, 1)
+  const cx = (minX + maxX) / 2, cy = (minY + maxY) / 2
+  for (const node of model.nodes) {
+    const p = positions.get(node.id) ?? { x: cx, y: cy }
+    node.x = Math.round((p.x - cx) * scale * 10) / 10
+    node.y = Math.round((p.y - cy) * scale * 10) / 10
+  }
+  return model
+}
+
+/** Zone glow and label geometry: a coarse density grid per zone and an anchor on its densest area. */
+export function zoneGeometry(model, { cell = 55 } = {}) {
+  const out = []
+  for (const zone of model.zones) {
+    const members = model.nodes.filter(n => n.zone === zone.id && Number.isFinite(n.x) && Number.isFinite(n.y))
+    if (!members.length) continue
+    const cx = members.reduce((s, n) => s + n.x, 0) / members.length
+    const cy = members.reduce((s, n) => s + n.y, 0) / members.length
+    const grid = new Map()
+    for (const n of members) {
+      const k = Math.round(n.x / cell) + ',' + Math.round(n.y / cell)
+      const g = grid.get(k) ?? { x: 0, y: 0, count: 0 }
+      g.x += n.x; g.y += n.y; g.count++
+      grid.set(k, g)
+    }
+    const blobs = [...grid.values()].map(g => ({ x: Math.round(g.x / g.count), y: Math.round(g.y / g.count), weight: g.count }))
+    const score = b => b.weight / (1 + Math.hypot(b.x - cx, b.y - cy) / 120)
+    const anchor = blobs.reduce((best, b) => score(b) > score(best) ? b : best, blobs[0])
+    out.push({ id: zone.id, label: zone.label, count: zone.count, index: zone.index, anchor: { x: anchor.x, y: anchor.y }, blobs })
+  }
+  return out
+}

package/src/graph-workspace/index.mjs

@@ -0,0 +1,11 @@
+// Graph workspace primitives: the read model, scale and layout helpers, label
+// placement, layered recipes and themes, focused authoring and a disclosure gate.
+// Pure modules only; browser rooms live under ./browser/index.mjs.
+export { buildWorkspaceModel, zoneOf, ROOT_ZONE, validateZoneRule, edgeClass, EDGE_CLASSES, neighbours } from './model.mjs'
+export { seedPositions, layoutWorkspace, normalizePositions, zoneGeometry, LAYOUT_WEIGHTS } from './geometry.mjs'
+export { planConstellation, aggregateZones, zoneSlice, rankRecords, DEFAULT_BUDGET } from './scale.mjs'
+export { placeLabels, labelThreshold, labelBudget, overlaps } from './labels.mjs'
+export { DEFAULT_RECIPES, composeRecipes, validateRecipe, availableRecipes, ROOMS, LENSES, SUBJECTS, LAYERS, PRIMARY_ACTIONS, primaryActionsFor } from './recipes.mjs'
+export { DEFAULT_THEME, composeTheme, validateTheme, contrastRatio } from './theme.mjs'
+export { conceptSteps, relationSteps, guideConcept, guideRelation, stepState, createDraftStore, memoryStorage, readiness } from './authoring.mjs'
+export { fingerprintsFrom, scanForFingerprints } from './disclosure.mjs'

package/src/graph-workspace/labels.mjs

@@ -0,0 +1,50 @@
+// Label placement for dense graphs. Pure: give it candidates, a text measurer and
+// the space available; it returns where each label goes, or leaves it out.
+// - importance first; zoom and a budget decide how deep into the list to go,
+// - four slots per label (right, left, above, below), first free slot wins,
+// - nothing overlaps another label, a reserved rectangle (zone names, chrome) or the edge,
+// - secondary labels are left out rather than shrunk.
+
+export const overlaps = (a, b, gap = 0) => a.left < b.right + gap && a.right + gap > b.left && a.top < b.bottom + gap && a.bottom + gap > b.top
+
+/**
+ * candidates: [{ id, x, y, r, priority, text, size }] in viewport pixels (any order).
+ * measure(text, size, emphasis) → width in pixels.
+ * Returns placed labels [{ id, text, size, x, y, left, right, top, bottom }].
+ */
+export function placeLabels({ candidates, measure, width, height, reserved = [], budget = 25, threshold = 0, margin = 4, cell = 80, minSize = 11 }) {
+  if (typeof measure !== 'function') throw new TypeError('A text measurer is required')
+  const ordered = candidates.filter(c => c.priority >= threshold && Number.isFinite(c.x) && Number.isFinite(c.y)).sort((a, b) => b.priority - a.priority)
+  const grid = new Map()
+  const cellsFor = r => { const out = []; for (let x = Math.floor(r.left / cell); x <= Math.floor(r.right / cell); x++) for (let y = Math.floor(r.top / cell); y <= Math.floor(r.bottom / cell); y++) out.push(x + ',' + y); return out }
+  const placed = []
+  for (const c of ordered) {
+    if (placed.length >= budget) break
+    const size = Math.max(minSize, c.size ?? 12)
+    const w = measure(c.text, size, !!c.emphasis)
+    const half = size * 0.72
+    const r = c.r ?? 4
+    const slots = [[c.x + r + 5, c.y], [c.x - r - 5 - w, c.y], [c.x - w / 2, c.y - r - size * 0.9], [c.x - w / 2, c.y + r + size * 0.9]]
+    for (const [sx, sy] of slots) {
+      const rect = { left: sx - 3, right: sx + w + 3, top: sy - half, bottom: sy + half }
+      if (rect.left < margin || rect.top < margin || rect.right > width - margin || rect.bottom > height - margin) continue
+      const cells = cellsFor(rect)
+      if (cells.some(k => (grid.get(k) ?? []).some(o => overlaps(o, rect, 3)))) continue
+      if (reserved.some(o => overlaps(o, rect, 4))) continue
+      for (const k of cells) { if (!grid.has(k)) grid.set(k, []); grid.get(k).push(rect) }
+      placed.push({ id: c.id, text: c.text, size, x: sx, y: sy, ...rect })
+      break
+    }
+  }
+  return placed
+}
+
+/** Rank-based label threshold for a camera ratio (1 = whole graph fitted, smaller = closer). */
+export function labelThreshold(ratio, boost = 1) {
+  return Math.max(0, Math.min(0.94, 0.8 * ratio - 0.04)) / Math.max(0.1, boost)
+}
+
+/** Label budget for a viewport: about 20–25 at a fitted desktop view, more as you zoom in. */
+export function labelBudget(width, height, ratio, boost = 1, cap = 45) {
+  return Math.round(Math.min(cap, Math.max(10, (width * height) / 52000 / Math.max(0.35, Math.min(1, ratio)))) * boost)
+}