forma-arch 0.4.0 → 0.6.0

package/README.md

@@ -8,6 +8,9 @@ them.
 Forma is the companion to `arbiter`: arbiter governs the process, Forma shows the system and
 guarantees the picture matches reality.
 
+**[▶ Live demo](https://LucaDominici.github.io/forma/)** — forma's own architecture, generated by
+forma from this repo on every push to `main`.
+
 ## Why
 
 A hand-drawn architecture diagram is stale the moment code changes. Forma walks your source for the
@@ -49,10 +52,15 @@ npx forma-arch <command>        # or: npm i -D forma-arch
 | `--enricher` | Use it when | Network |
 |---|---|---|
 | `agent` | **An agent is driving forma.** Writes `enrich-plan.json` with the holes; the agent writes the sentences (reading the sources if it wants) and `gen --enrich-apply <file>` applies them with the same cache and provenance. | none |
-| `anthropic` (default) | Headless / CI, with `ANTHROPIC_API_KEY`. | REST |
+| `anthropic` | Headless / CI, with `ANTHROPIC_API_KEY`. | REST |
 | `openai` | Same, with `OPENAI_API_KEY`. | REST |
 | `ollama` | Sensitive repos: a local model, nothing leaves the machine. | localhost |
 
+`--enricher` has **no default**: `forma gen --enrich` on its own fails loud and lists the four. A
+default provider is a silent choice about your network and your API keys — and the old default
+(`anthropic`) meant that anyone without `ANTHROPIC_API_KEY` exported got a skip line, exit 0 and the
+same empty boxes they ran `--enrich` to fill.
+
 ## How it fits together
 
 ```
@@ -81,7 +89,11 @@ The viewer is a live C4 map, not a static picture:
 - **Drag boxes** to lay out the view your way; **RESET LAYOUT** restores the arrangement (your curated hints if the topology has them, the automatic one otherwise). To keep a layout, drag it, pick **Export layout JSON**, and paste the result under `"layout"` in the topology — `gen` carries it into `meta.layout` and the viewer pins those boxes, auto-arranging everything else clear of them.
 - **Arrow labels** are painted on the diagram while the level stays readable (≤14 arrows) and turn off above that; **LABELS** forces them on or off, and hovering an arrow always reveals its label.
 - **PRINT / EXPORT** to SVG or PNG for docs and slides — exported arrows carry their labels.
-- The breadcrumb names the C4 level you are on (`C4-L1 · CONTEXT` → `C4-L3 · COMPONENTS`).
+- The breadcrumb names the C4 level you are on (`C4-L1 · CONTEXT` → `C4-L3 · COMPONENTS`) and,
+  when the level carries curated state, tallies it: a dot per status with its count plus mean
+  completion, so a level reads as a programme board and not just a diagram.
+- **Every level shrink-wraps its own content** — a context with four boxes renders zoomed and
+  dense instead of adrift in a fixed canvas.
 
 ## Skins
 

package/lib/cluster.mjs

@@ -13,14 +13,17 @@ export function containerOf(node, byId) {
   return n ? n.id : null
 }
 
-// Group a flat container's leaves by common `foo_*` prefix. Deterministic: sorted group keys.
+// Group a flat container's leaves by common `foo<sep>*` prefix, where sep is any of - _ . — the
+// three conventions real repos use (kebab dominates JS/TS, snake Python, dot some Java/config
+// layouts). Splitting on `_` alone gave kebab and dot repos no component level at all.
+// Deterministic: sorted group keys.
 // Returns { components: Node[], reparent: Map(leafId → componentId) }. Leftovers stay under the container.
 export function componentsFor(container, leaves, opts = {}) {
   const groupMin = opts.groupMin || 3
   const groups = new Map()
   for (const l of leaves) {
     const base = String(l.name)
-    const i = base.indexOf('_')
+    const i = base.search(/[-_.]/)
     if (i <= 0) continue // no prefix (e.g. "health", "version") → stays flat
     const prefix = base.slice(0, i)
     if (!groups.has(prefix)) groups.set(prefix, [])

package/lib/describe.mjs

@@ -60,6 +60,19 @@ function buildArc42Index(repo, docPath) {
   return idx
 }
 
+// Last resort for a node that HAS children: say what it measurably holds. Never the language —
+// a box reading "TypeScript" states the one thing the reader can already see in the header.
+function measuredFunc(node, ctx) {
+  const kids = [...ctx.byId.values()].filter((k) => k.parent === node.id)
+    .sort((a, b) => (String(a.name) < String(b.name) ? -1 : String(a.name) > String(b.name) ? 1 : 0))
+  if (!kids.length) return null
+  const count = (k) => kids.filter((x) => x.kind === k).length
+  const parts = [['container', count('container')], ['component', count('component')], ['file', count('leaf')]]
+    .filter((p) => p[1]).map((p) => `${p[1]} ${p[0]}${p[1] === 1 ? '' : 's'}`)
+  const names = kids.slice(0, 3).map((k) => k.name).join(', ')
+  return `${parts.join(' + ')}: ${names}${kids.length > 3 ? ', …' : '.'}`.slice(0, 240)
+}
+
 export function makeDescribeCtx({ repo, byId, descriptions, docPath, containerOf }) {
   return { repo, byId, D: descriptions || {}, containerOf, readmeCache: new Map(), arc42: buildArc42Index(repo, docPath) }
 }
@@ -79,12 +92,18 @@ export function resolveDescription(node, ctx) {
     const rd = readmeFirstPara(dirname(abs), ctx.readmeCache)
     if (rd) return { func: rd, descSource: 'readme' }
   }
+  // A container's evidence is a GLOB over its own directory, never a `path` — which is why the
+  // README sitting in that very directory never reached it, and the box fell through to `tech`.
+  const glb = (node.evidence || []).find((e) => e.type === 'glob')
+  if (!pth && glb) {
+    const rd = readmeFirstPara(join(ctx.repo, glb.ref), ctx.readmeCache)
+    if (rd) return { func: rd, descSource: 'readme' }
+  }
   const a = ctx.arc42.get(norm(node.name)) || ctx.arc42.get(norm(node.id))
   if (a) return { func: a, descSource: 'arc42' }
   if (node.kind === 'leaf') {
     const cn = (ctx.byId.get(cont) || {}).name || cont || node.parent
     return { func: `Component of module ${cn}.`, descSource: 'fallback' }
   }
-  if (node.kind === 'component') return { func: `Groups related files under ${node.name}.`, descSource: 'fallback' }
-  return { func: node.description || '', descSource: 'fallback' }
+  return { func: node.description || measuredFunc(node, ctx) || '', descSource: 'fallback' }
 }

package/lib/enrich.mjs

@@ -36,15 +36,21 @@ export function descInputHash(node, ctx) {
 
 function promptFor(node, ctx, opts = {}) {
   const { cont, siblings } = siblingsOf(node, ctx)
+  // A container is its OWN container: unguarded, the prompt tells the model that "auth" belongs to
+  // the container "auth" and calls its own children its siblings. Its filesystem pointer is a glob
+  // over its directory, not a path, so it also had nothing to read.
+  const self = cont === node.id
   const contName = (ctx.byId && ctx.byId.get(cont) || {}).name || cont || 'the system'
   const path = (node.evidence || []).find((e) => e.type === 'path')
+  const glob = !path && (node.evidence || []).find((e) => e.type === 'glob')
   return [
-    `In ONE plain sentence (max 18 words), say what the software module "${node.name}" does.`,
-    `It belongs to the container "${contName}".`,
-    siblings.length ? `Sibling modules: ${siblings.slice(0, 40).join(', ')}.` : '',
+    `In ONE plain sentence (max 18 words), say what the software ${self ? 'module group' : 'module'} "${node.name}" does.`,
+    self ? '' : `It belongs to the container "${contName}".`,
+    siblings.length ? `${self ? 'The modules it holds' : 'Sibling modules'}: ${siblings.slice(0, 40).join(', ')}.` : '',
     // Only the agent enricher can act on this: a REST provider has no filesystem. That asymmetry
     // IS the point of the agent mode — the model driving forma can read the source it describes.
     (opts.canRead && path) ? `Read the file at ${path.ref} if you need certainty.` : '',
+    (opts.canRead && glob) ? `Read the sources under ${glob.ref}/ if you need certainty.` : '',
     'Answer with the sentence only — no preamble, no quotes.',
   ].filter(Boolean).join('\n')
 }
@@ -103,8 +109,11 @@ export function mergeCache(nodes, cache) {
 }
 
 // The holes an enricher would fill: never-described nodes, plus llm prose whose inputs moved.
+// Containers count. They were excluded on the theory that the topology describes them — but on a
+// repo with no curated topology (i.e. anything `forma init` seeded) they are exactly the boxes
+// left on a measured fallback, and the biggest ones on screen.
 export function holesIn(nodes, ctx) {
-  return nodes.filter((n) => (n.kind === 'leaf' || n.kind === 'component') &&
+  return nodes.filter((n) => (n.kind === 'leaf' || n.kind === 'component' || n.kind === 'container') &&
     (n.descSource === 'fallback' || (n.descSource === 'llm' && n.descInputHash !== descInputHash(n, ctx))))
 }
 

package/lib/gen.mjs

@@ -15,10 +15,10 @@ const arg = (f, d) => { const i = process.argv.indexOf(f); return i > -1 ? proce
 const REPO = arg('--repo', process.cwd())
 const TOPO = arg('--topology', join(REPO, 'docs/architecture/c4-topology.json'))
 const OUT = arg('--out', join(REPO, 'docs/architecture/c4-model.json'))
-const SCHEMA_VERSION = '1.3.0'
+const SCHEMA_VERSION = '1.4.0' // +status2:"unknown" (additive enum value → MINOR)
 const CLUSTER = !process.argv.includes('--no-cluster') // §2: auto-cluster flat containers; --no-cluster to disable
 const ENRICH = process.argv.includes('--enrich')       // §7: opt-in LLM prose for description holes
-const ENRICHER = arg('--enricher', 'anthropic')
+const ENRICHER = arg('--enricher', null)
 const ENRICH_MODEL = arg('--enrich-model', null)
 const STATUS = arg('--status', join(REPO, 'docs/architecture/c4-status.json')) // curated programme state, optional
 const STATUS_SET = process.argv.includes('--status')
@@ -31,6 +31,12 @@ const fail = (m) => { console.error('[gen-c4] FAIL: ' + m); process.exit(1) }
 // (`length >= NaN` is false for every group), so a bad value fails loud instead.
 const posInt = (flag, dflt) => { const v = Number(arg(flag, dflt)); if (!Number.isInteger(v) || v < 1) fail(`${flag}: expected a positive integer, got "${arg(flag, dflt)}"`); return v }
 const CLUSTER_MIN = posInt('--cluster-min', 8), GROUP_MIN = posInt('--group-min', 3)
+// §7 has no default provider ON PURPOSE. It used to be `anthropic`, i.e. the one path that needs
+// an API key most people have not exported — so `--enrich` "worked", printed a skip line, exited 0
+// and left every box empty: the defect this command exists to fix, reintroduced by its own default.
+// Flipping the default to `agent` would be just as silent the other way (a CI job with a key would
+// quietly stop filling boxes and start writing a plan file). So: choose, explicitly.
+if (ENRICH && !ENRICHER) fail('--enrich needs an explicit --enricher: `agent` (no key — an agent writes the prose, see --enrich-apply), `anthropic`/`openai` (REST, needs the API key in the environment), `ollama` (localhost), or `echo` (offline, testing).')
 
 function walk(spec) {
   const dir = rp(spec.dir)
@@ -114,12 +120,16 @@ if (CLUSTER) for (const cid of [...new Set(topo.leafSources.map((s) => s.parent)
   console.log(`[gen-c4] container ${cid}: clustered ${leaves.length} leaves into ${components.length} component(s)`)
 }
 
-// enrich: fill hologram defaults (category, 5-status, completion, current/target) where absent
+// enrich: fill hologram defaults (category, 6-status, completion, current/target) where absent
 for (const n of nodes) {
   const par = n.parent ? byId.get(n.parent) : null
   if (!n.category) n.category = n.kind === 'leaf' ? (par && par.category) || 'leaf' : n.kind
-  if (!n.status2) n.status2 = n.status === 'planned' ? 'planned' : 'done'
-  if (n.completion == null) n.completion = n.status === 'planned' ? 0 : 100
+  // Code can prove a file EXISTS; it cannot prove the work behind it is finished. Marking every
+  // undecorated node done/100 turned a virgin repo into a board reading "10/10 complete" — the
+  // exact false green this tool exists to kill. No overlay (§WP-A1), no verdict: `unknown`, and
+  // no completion at all (a percentage nobody curated is a made-up number, including 0).
+  if (!n.status2) n.status2 = n.status === 'planned' ? 'planned' : 'unknown'
+  if (n.completion == null && n.status === 'planned') n.completion = 0
   // `current` is left EMPTY unless curated (topology or status overlay): the viewer falls back to
   // `func`, which since §1a carries the module's real documentation. The old "Exists: <path>"
   // filler restated the evidence path in the one field meant for programme facts.
@@ -226,7 +236,11 @@ if (!process.argv.includes('--no-auto-edges')) {
     for (const to of exposes.keys()) {
       if (to === from || have.has(from + '|' + to)) continue
       let c = 0
-      for (const nm of exposes.get(to)) { if (new RegExp('\\b' + nm.replace(/[^\w]/g, '') + '\\b').test(t)) c++ }
+      // A module name is matched VERBATIM (metacharacters escaped, never deleted: stripping them
+      // turned "session-store" into /\bsessionstore\b/, which matches nothing — every kebab-case
+      // repo, i.e. most JS/TS ones, rendered edges=0). `-` and `.` are word separators here, so
+      // the boundary is spelled out instead of using \b (which sits INSIDE "session-store").
+      for (const nm of exposes.get(to)) { if (new RegExp('(^|[^\\w-])' + nm.replace(/[.*+?^${}()|[\]\\\/-]/g, '\\$&') + '([^\\w-]|$)').test(t)) c++ }
       if (c > 0) { derived.push({ from, to, label: c + '×', kind: 'import', estatus: 'active' }); have.add(from + '|' + to); have.add(to + '|' + from) }
     }
   }

package/lib/schema/c4-model.schema.json

@@ -179,9 +179,10 @@
               "in-progress",
               "next",
               "planned",
-              "problem"
+              "problem",
+              "unknown"
             ],
-            "description": "Hologram completion status (colour)."
+            "description": "Hologram completion status (colour). `unknown` is the default for a node no curated overlay has ruled on — code proves existence, never completion."
           },
           "completion": {
             "type": "integer",

package/lib/viewer/c4-hologram.html

@@ -9,7 +9,7 @@
  --bg:#050d14; --grid:rgba(62,231,255,.04); --halo:rgba(62,231,255,.10);
  --cyan:#3ee7ff; --sec:#6fa8bc; --ter:#4c7f94; --ter2:#41738a; --nm:#bfe9f7;
  --stagebg:rgba(4,12,19,.72); --stageborder:#143547; --nodebg:rgba(8,26,38,.92); --detailbg:rgba(6,20,30,.97);
- --border:#1e4a5e; --done:#2fe08a; --prog:#ffc74d; --next:#3ee7ff; --plan:#2d5a72; --planTxt:#7fb3c6; --prob:#ff5d5d;
+ --border:#1e4a5e; --done:#2fe08a; --prog:#ffc74d; --next:#3ee7ff; --plan:#2d5a72; --planTxt:#7fb3c6; --prob:#ff5d5d; --unk:#7d8f99;
  --edge:#2b6e8a; --edgeplan:#264d61; --elbl:#3d7f9c; --ddtxt:#7fb3c6; --now:#cfeefb; --tgt:#8fd8ec; --src:#4fbf8d;}
 *{box-sizing:border-box;margin:0;padding:0}
 body{font-family:"SF Mono",Menlo,Consolas,ui-monospace,monospace;background:var(--bg);color:var(--nm);overflow-x:hidden}
@@ -29,6 +29,9 @@ button.on{background:rgba(62,231,255,.18);color:var(--cyan);border-color:var(--c
 #back[disabled]{opacity:.28;cursor:default;border-color:var(--border);color:var(--ter)}
 select#skin option{background:#08202e;color:var(--nm)}
 #crumb{font-size:11px;color:var(--sec);margin:8px 0}
+#crumb .agg{float:right;color:var(--ter2);letter-spacing:.05em}
+#crumb .agg i{display:inline-block;width:7px;height:7px;border-radius:50%;margin:0 3px 0 8px;vertical-align:baseline}
+#crumb .agg b{color:var(--nm)}
 #crumb b{color:var(--cyan)}
 #crumb a{color:#8fd8ec;cursor:pointer}
 #crumb a:hover{text-decoration:underline}
@@ -57,6 +60,8 @@ svg{width:100%;height:100%;display:block}
 .s-plan .tt,.s-plan .pp{fill:var(--planTxt)}
 .s-prob rect{stroke:var(--prob);filter:drop-shadow(0 0 8px rgba(255,93,93,.6))}
 .s-prob .tt,.s-prob .pp{fill:var(--prob)}
+.s-unk rect{stroke:var(--unk);stroke-dasharray:1 3}
+.s-unk .tt,.s-unk .pp{fill:var(--unk)}
 .mode-t .nd rect{stroke:var(--next)!important;stroke-dasharray:none!important;filter:drop-shadow(0 0 8px rgba(62,231,255,.5))!important}
 .mode-t .nd .tt,.mode-t .nd .pp{fill:var(--next)!important}
 .edge{stroke:var(--edge);stroke-width:1.3;fill:none;marker-end:url(#ar);cursor:help}
@@ -64,7 +69,8 @@ svg{width:100%;height:100%;display:block}
 .edge.plan{stroke:var(--edgeplan);stroke-dasharray:3 6;opacity:.6;marker-end:url(#arp)}
 .edge.hot{stroke:var(--cyan);stroke-width:2.6;opacity:1}
 .edgehit{stroke:transparent;stroke-width:14;fill:none;cursor:help}
-.elbl{font-size:8.2px;fill:var(--elbl);letter-spacing:.04em;pointer-events:none}
+.elbl{font-size:8.2px;fill:var(--elbl);letter-spacing:.04em;pointer-events:none;
+ paint-order:stroke;stroke:var(--stagebg);stroke-width:3px;stroke-linejoin:round}
 @keyframes dash{to{stroke-dashoffset:-24}}
 .nd.pulse rect{animation:pul 2.4s ease-in-out infinite}
 @keyframes pul{0%,100%{filter:drop-shadow(0 0 8px rgba(62,231,255,.5))}50%{filter:drop-shadow(0 0 18px rgba(62,231,255,.95))}}
@@ -115,7 +121,7 @@ svg{width:100%;height:100%;display:block}
 html[data-skin="blueprint"]{--bg:#eef3f9;--grid:rgba(31,119,180,.10);--halo:rgba(31,119,180,.08);
  --cyan:#1f77b4;--sec:#5a6b7d;--ter:#6b7b8c;--ter2:#5a6b7d;--nm:#16273a;
  --stagebg:#ffffff;--stageborder:rgba(31,119,180,.25);--nodebg:#ffffff;--detailbg:#ffffff;--border:rgba(31,119,180,.35);
- --done:#1f9d57;--prog:#c07a12;--next:#1f77b4;--plan:#8592a3;--planTxt:#5a6b7d;--prob:#d1453b;
+ --done:#1f9d57;--prog:#c07a12;--next:#1f77b4;--plan:#8592a3;--planTxt:#5a6b7d;--prob:#d1453b;--unk:#8a97a3;
  --edge:#8aa0b4;--edgeplan:#b9c6d3;--elbl:#5a6b7d;--ddtxt:#40536a;--now:#16273a;--tgt:#1f5f8a;--src:#1f9d57}
 html[data-skin="blueprint"] h1{text-shadow:none}
 html[data-skin="blueprint"] .s-done rect,html[data-skin="blueprint"] .s-prog rect,html[data-skin="blueprint"] .s-next rect,html[data-skin="blueprint"] .s-prob rect{filter:none}
@@ -156,6 +162,7 @@ html[data-skin="blueprint"] button.on{text-shadow:none}
   <span><i style="background:#3ee7ff"></i><span id="lg-next"></span></span>
   <span><i style="background:#2d5a72"></i><span id="lg-plan"></span></span>
   <span><i style="background:#ff5d5d"></i><span id="lg-prob"></span></span>
+  <span><i style="background:#7d8f99"></i><span id="lg-unk"></span></span>
   <span class="hint" id="lg-hint"></span>
  </div>
  <div id="detail"></div>
@@ -172,13 +179,14 @@ var STRINGS={
   resetLayout:"RESET LAYOUT", resetLayoutTitle:"re-arrange",
   printExport:"PRINT / EXPORT", exportSvg:"Export SVG", exportPng:"Export PNG", exportLayout:"Export layout JSON", print:"Print",
   legDone:"DONE (proven)", legProg:"IN PROGRESS", legNext:"NEXT", legPlan:"PLAN ONLY", legProb:"PROBLEM",
+  legUnk:"UNKNOWN (no curated state)", stUnk:"?",
   legHint:"— animated arrow = active flow · dashed = to build",
   crumbRoot:"Context", crumbLevel:"C4", lvlContext:"CONTEXT",
   lvlNames:{context:"Context",container:"Container",component:"Components",leaf:"Leaves"},
   detClose:"[x] close", detFunc:"What it does", detNow:"Current state (facts)",
   detTgt:"Target state (project)", detSrc:"Verification source", detIssue:"Issue",
   detTarget:"TARGET",
-  rosterSearch:"filter…", rosterCount:"members", rosterEmpty:"no match",
+  rosterSearch:"filter…", rosterCount:"members", rosterEmpty:"no match", aggProgress:"progress",
   stampBase:"Fact base:", stampMethod:"method:", stampVerify:"code+topology", staticSrc:"(static source)",
   errEmpty:"Model unreachable or empty.",
   errNotFound:"Model not found (./c4-model.json). Open via `forma serve` or inject window.__C4_MODEL__.",
@@ -191,13 +199,14 @@ var STRINGS={
   resetLayout:"RESET LAYOUT", resetLayoutTitle:"ridisponi",
   printExport:"STAMPA / ESPORTA", exportSvg:"Esporta SVG", exportPng:"Esporta PNG", exportLayout:"Esporta layout JSON", print:"Stampa",
   legDone:"FATTO (provato)", legProg:"IN CORSO", legNext:"PROSSIMO", legPlan:"SOLO PROGETTO", legProb:"PROBLEMA",
+  legUnk:"IGNOTO (stato non curato)", stUnk:"?",
   legHint:"— freccia animata = flusso attivo · tratteggio = da costruire",
   crumbRoot:"Contesto", crumbLevel:"C4", lvlContext:"CONTESTO",
   lvlNames:{context:"Contesto",container:"Container",component:"Componenti",leaf:"Foglie"},
   detClose:"[x] chiudi", detFunc:"Cosa fa", detNow:"Stato attuale (fatti)",
   detTgt:"Stato finito (progetto)", detSrc:"Fonte verifica", detIssue:"Issue",
   detTarget:"TARGET",
-  rosterSearch:"filtra…", rosterCount:"elementi", rosterEmpty:"nessun risultato",
+  rosterSearch:"filtra…", rosterCount:"elementi", rosterEmpty:"nessun risultato", aggProgress:"avanzamento",
   stampBase:"Base fatti:", stampMethod:"metodo:", stampVerify:"code+topology", staticSrc:"(fonte statica)",
   errEmpty:"Modello non raggiungibile o vuoto.",
   errNotFound:"Modello non trovato (./c4-model.json). Apri via `forma serve` o inietta window.__C4_MODEL__.",
@@ -215,8 +224,9 @@ var CATALOG_THRESHOLD=24; // group of same-category siblings above this collapse
 var LABEL_AUTO_MAX=14;    // above this many arrows in the current level, fixed labels would knot the view
 var LABELS=null;          // null = auto (by arrow count); true/false = user override for this session
 var SKINS=[["holo","◆ holo"],["blueprint","▭ blueprint"]], SKIN_IDS=["holo","blueprint"];
-var STMAP={done:"done","in-progress":"prog",next:"next",planned:"plan",problem:"prob"};
-var M=null, stack=[null], mode="now", POS={}, drag=null, justDragged=false, CATNODES={}, FETCHED=false;
+var STMAP={done:"done","in-progress":"prog",next:"next",planned:"plan",problem:"prob",unknown:"unk"};
+var M=null, stack=[null], mode="now", POS={}, drag=null, justDragged=false, CATNODES={}, FETCHED=false
+var VBOX={}; // last fitted viewBox per level — frozen while dragging so the canvas does not rescale
 function $(i){return document.getElementById(i)}
 function esc(s){return String(s==null?"":s).replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/"/g,"&quot;")}
 function setSkin(s){var k=SKIN_IDS.indexOf(s)>-1?s:"holo";document.documentElement.dataset.skin=k;var el=$("skin");if(el)el.value=k;}
@@ -253,9 +263,9 @@ function collapseCatalogs(pid,kids){
 }
 function makeCatalogNode(pid,g){
  // Aggregate status: worst-of-a-few heuristic — problem > next > in-progress > planned > done.
- var rank={problem:5,next:4,"in-progress":3,planned:2,done:1},best=0,bestKey="done",done=0,tot=g.members.length;
+ var rank={problem:5,next:4,"in-progress":3,planned:2,unknown:1.5,done:1},best=0,bestKey="unknown",done=0,tot=g.members.length;
  for(var i=0;i<g.members.length;i++){
-  var s2=g.members[i].status2||(g.members[i].status==="planned"?"planned":"done");
+  var s2=g.members[i].status2||(g.members[i].status==="planned"?"planned":"unknown");
   if((rank[s2]||0)>best){best=rank[s2]||0;bestKey=s2;}
   if(s2==="done")done++;
  }
@@ -324,28 +334,53 @@ function draw(animate){
  function mapId(id){return memberMap[id]||id;}
  var edges=(M.edges||[]).map(function(e){return {from:mapId(e.from),to:mapId(e.to),label:e.label,estatus:e.estatus};})
   .filter(function(e){return idset[e.from]&&idset[e.to]&&e.from!==e.to;});
- var s='<svg viewBox="0 0 '+lay.W+' '+lay.H+'" preserveAspectRatio="xMidYMid meet" class="'+(mode==="target"?"mode-t":"")+'">'
-  +'<defs><marker id="ar" markerWidth="9" markerHeight="7" refX="9" refY="3.5" orient="auto"><polygon points="0 0,9 3.5,0 7" fill="'+cssv("--edge")+'"/></marker>'
-  +'<marker id="arp" markerWidth="9" markerHeight="7" refX="9" refY="3.5" orient="auto"><polygon points="0 0,9 3.5,0 7" fill="'+cssv("--edgeplan")+'"/></marker></defs>';
  // fixed arrow labels: on by default while the level stays readable, else hover-only (the tooltip
  // is always there). A level with 40 arrows would be unreadable with every label painted at once.
  var showLbl=(LABELS===null)?(edges.length<=LABEL_AUTO_MAX):LABELS;
  var blbl=$("blbl");if(blbl)blbl.className=showLbl?"on":"";
- for(var i=0;i<edges.length;i++){
+ // geometry pre-pass: edge paths first, so the viewBox can shrink-wrap nodes AND label anchors
+ var geo=[],i;
+ for(i=0;i<edges.length;i++){
   var a=pos[edges[i].from],b=pos[edges[i].to];if(!a||!b)continue;
-  var e=edgePath(a,b),cl=(edges[i].estatus==="to-build"?"plan":"flow");
-  s+='<path class="edge '+cl+'" data-e="'+i+'" d="'+e.d+'"/>';
-  s+='<path class="edgehit" data-e="'+i+'" data-label="'+esc(edges[i].label||"")+'" d="'+e.d+'"/>';
-  if(showLbl&&edges[i].label){var lb=String(edges[i].label);if(lb.length>28)lb=lb.slice(0,27)+"…";
+  geo.push({e:edges[i],i:i,g:edgePath(a,b)});
+ }
+ // Fit-to-content viewBox: a sparse level renders zoomed and dense instead of lost in a fixed
+ // 1020px canvas — the hand-made status boards read well precisely because they waste no space.
+ // Minimums stop a single box from becoming comically large; extra room is split evenly so the
+ // content stays centred inside the enforced window.
+ var bx1=Infinity,by1=Infinity,bx2=-Infinity,by2=-Infinity,j,pp;
+ for(j=0;j<kids.length;j++){pp=pos[kids[j].id];if(!pp)continue;
+  if(pp.x<bx1)bx1=pp.x;if(pp.y<by1)by1=pp.y;if(pp.x+pp.w>bx2)bx2=pp.x+pp.w;if(pp.y+pp.h>by2)by2=pp.y+pp.h;}
+ for(j=0;j<geo.length;j++){var gm=geo[j].g;
+  if(gm.mx-14<bx1)bx1=gm.mx-14;if(gm.my-18<by1)by1=gm.my-18;
+  if(gm.mx+14>bx2)bx2=gm.mx+14;if(gm.my+6>by2)by2=gm.my+6;}
+ if(bx2<bx1){bx1=0;by1=0;bx2=lay.W;by2=lay.H;}
+ var VPAD=56,MINW=880,MINH=460;
+ var cw=bx2-bx1+2*VPAD,ch=by2-by1+2*VPAD;
+ var vw=Math.max(MINW,cw),vh=Math.max(MINH,ch);
+ var vx=bx1-VPAD-(vw-cw)/2,vy=by1-VPAD-(vh-ch)/2;
+ // …but hold it still while a box is being dragged: draw() runs on every mousemove, so a live
+ // refit would rescale the whole canvas under the pointer. The drop refits (see mouseup).
+ var vbk=keyOf();
+ if(drag&&VBOX[vbk]){vx=VBOX[vbk][0];vy=VBOX[vbk][1];vw=VBOX[vbk][2];vh=VBOX[vbk][3];}
+ else VBOX[vbk]=[vx,vy,vw,vh];
+ var s='<svg viewBox="'+vx.toFixed(1)+' '+vy.toFixed(1)+' '+vw.toFixed(1)+' '+vh.toFixed(1)+'" preserveAspectRatio="xMidYMid meet" class="'+(mode==="target"?"mode-t":"")+'">'
+  +'<defs><marker id="ar" markerWidth="9" markerHeight="7" refX="9" refY="3.5" orient="auto"><polygon points="0 0,9 3.5,0 7" fill="'+cssv("--edge")+'"/></marker>'
+  +'<marker id="arp" markerWidth="9" markerHeight="7" refX="9" refY="3.5" orient="auto"><polygon points="0 0,9 3.5,0 7" fill="'+cssv("--edgeplan")+'"/></marker></defs>';
+ for(j=0;j<geo.length;j++){
+  var e=geo[j].g,ed=geo[j].e,cl=(ed.estatus==="to-build"?"plan":"flow");
+  s+='<path class="edge '+cl+'" data-e="'+geo[j].i+'" d="'+e.d+'"/>';
+  s+='<path class="edgehit" data-e="'+geo[j].i+'" data-label="'+esc(ed.label||"")+'" d="'+e.d+'"/>';
+  if(showLbl&&ed.label){var lb=String(ed.label);if(lb.length>28)lb=lb.slice(0,27)+"…";
    s+='<text class="elbl" x="'+e.mx+'" y="'+(e.my-4)+'" text-anchor="middle">'+esc(lb)+'</text>';}
  }
  for(var j=0;j<kids.length;j++){
   var n=kids[j],p=pos[n.id];
-  var st=STMAP[n.status2]||(n.status==="planned"?"plan":"done");
+  var st=STMAP[n.status2]||(n.status==="planned"?"plan":"unk");
   var pulse=(st==="next"||st==="prog")&&mode!=="target"&&!n.__catalog;
   var isCat=!!n.__catalog,dr=!isCat&&hasKids(n.id),cls="nd s-"+st+(dr?" drill":"")+(isCat?" cat":"")+(pulse?" pulse":"");
-  var desc=isCat?(n.count+" "+STR.rosterCount):(mode==="target"?(n.target||n.func||""):(n.current||n.func||n.tech||""));
-  var badge=isCat?String(n.count):(mode==="target"?STR.detTarget:(n.statusWord||(n.completion!=null?n.completion+"%":(n.tech||""))));
+  var desc=isCat?(n.count+" "+STR.rosterCount):(mode==="target"?(n.target||n.func||""):(n.current||n.func||""));
+  var badge=isCat?String(n.count):(mode==="target"?STR.detTarget:(n.statusWord||(n.completion!=null?n.completion+"%":STR.stUnk)));
   // the title runs until the badge, so reserve the badge's actual width (9px text ≈ 5.4px/char)
   // instead of a flat 70px — a fixed reserve clipped names that had all the room they needed
   var tmax=Math.floor((p.w-34-String(badge).length*5.4)/6.7),tt=n.name;
@@ -358,7 +393,7 @@ function draw(animate){
   // Description lines: how many fit comes from the geometry (text starts at y+51, 12.5px apart,
   // and must clear the footer control at h-25), so a curated layout hint with short boxes cannot
   // print through [+] DRILL. wrapDesc is pure and clamps every line to the box width.
-  var floorY=p.h-((dr||isCat)?25:6),MAXL=Math.min(3,Math.floor((floorY-51)/12.5)+1);
+  var floorY=p.h-((dr||isCat)?25:6),MAXL=Math.min(4,Math.floor((floorY-51)/12.5)+1);
   var dlines=wrapDesc(desc,Math.floor((p.w-26)/5.4),MAXL);
   for(var q=0;q<dlines.length;q++)s+='<text class="dd" x="'+(p.x+13)+'" y="'+(p.y+51+q*12.5)+'">'+esc(dlines[q])+'</text>';
   if(dr)s+='<rect class="drillhit" data-drill="1" x="'+(p.x+p.w-96)+'" y="'+(p.y+p.h-25)+'" width="88" height="20" rx="5"/>'
@@ -379,6 +414,21 @@ function draw(animate){
  var lvlIdx=((M.levels||[]).indexOf(lvlKey));
  var cb=(lvlIdx>-1?STR.crumbLevel+"-L"+(lvlIdx+1):STR.crumbLevel)+" · "+lvl.toUpperCase()+"  &nbsp;&nbsp; <a data-d='-1'>"+esc(STR.crumbRoot)+"</a>";
  for(var w=0;w<chain.length;w++)cb+=" &rsaquo; "+(w===chain.length-1?"<b>"+esc(chain[w].name)+"</b>":"<a data-d='"+w+"'>"+esc(chain[w].name)+"</a>");
+ // Per-level programme tally — the status-board essence in one glance: the status mix of THIS
+ // view plus mean completion. Counts use the real children (a collapsed catalogue still counts
+ // its members), so the tally never changes when the catalogue threshold does.
+ var cnt={},tot=0,sum=0,nc=0,st3;
+ for(j=0;j<realKids.length;j++){
+  st3=STMAP[realKids[j].status2]||(realKids[j].status==="planned"?"plan":"unk");
+  cnt[st3]=(cnt[st3]||0)+1;tot++;
+  if(realKids[j].completion!=null){sum+=(+realKids[j].completion||0);nc++;}
+ }
+ if(tot){
+  var DOT={done:"#2fe08a",prog:"#ffc74d",next:"#3ee7ff",plan:"#2d5a72",prob:"#ff5d5d",unk:"#7d8f99"},ord=["done","prog","next","plan","prob","unk"],agg="";
+  for(j=0;j<ord.length;j++)if(cnt[ord[j]])agg+='<i style="background:'+DOT[ord[j]]+'"></i>'+cnt[ord[j]];
+  if(nc)agg+=' &nbsp;'+esc(STR.aggProgress)+' <b>'+Math.round(sum/nc)+'%</b>';
+  cb='<span class="agg">'+agg+'</span>'+cb;
+ }
  $("crumb").innerHTML=cb;
  $("back").disabled=stack.length<2;
  $("detail").style.display="none";
@@ -399,9 +449,15 @@ function wrapDesc(desc,cpl,max){
 }
 // Returns the path plus the point ON the curve at t=0.5 — the label anchor. (The quadratic's
 // control point sits at twice the bow, so anchoring a label there would float it off the arrow.)
+// Endpoints are trimmed at the true RECTANGLE border (not a radial guess): with wide boxes the
+// radial trim landed inside the box on shallow angles, dragging the label anchor under the node.
 function edgePath(a,b){
  var ax=a.x+a.w/2,ay=a.y+a.h/2,bx=b.x+b.w/2,by=b.y+b.h/2,dx=bx-ax,dy=by-ay,L=Math.sqrt(dx*dx+dy*dy)||1;
- var x1=ax+(a.w/2+10)*dx/L,y1=ay+(a.h/2+10)*dy/L,x2=bx-(b.w/2+12)*dx/L,y2=by-(b.h/2+12)*dy/L;
+ var ux=dx/L,uy=dy/L;
+ var ta=Math.min(ux?(a.w/2)/Math.abs(ux):Infinity,uy?(a.h/2)/Math.abs(uy):Infinity)+8;
+ var tb=Math.min(ux?(b.w/2)/Math.abs(ux):Infinity,uy?(b.h/2)/Math.abs(uy):Infinity)+11;
+ if(ta+tb>L-4){ta=(a.w/2+10);tb=(b.w/2+12);} // boxes touch/overlap: fall back to the radial trim
+ var x1=ax+ta*ux,y1=ay+ta*uy,x2=bx-tb*ux,y2=by-tb*uy;
  var cx=(x1+x2)/2+(y2-y1)*.12,cy=(y1+y2)/2-(x2-x1)*.12;
  return {d:"M"+x1+","+y1+" Q"+cx+","+cy+" "+x2+","+y2, mx:(x1+2*cx+x2)/4, my:(y1+2*cy+y2)/4};
 }
@@ -410,7 +466,7 @@ function cssv(v){try{return getComputedStyle(document.documentElement).getProper
 
 function showDetail(n){
  if(n&&n.__catalog)return showRoster(n);
- var src=srcOf(n),cur=n.current||n.func||n.tech||"",showSrc=src&&String(cur).indexOf(src)<0;
+ var src=srcOf(n),cur=n.current||n.func||"",showSrc=src&&String(cur).indexOf(src)<0;
  $("detail").innerHTML='<span class="cl" id="dc">'+esc(STR.detClose)+'</span><h3>'+esc(n.name)+' <span class="cat">· '+esc(n.category||n.kind||"")+(n.tech?" · "+esc(n.tech):"")+'</span></h3>'
   +(n.func?'<div class="row"><span class="lbl">'+esc(STR.detFunc)+'</span><span class="func">'+esc(n.func)+'</span></div>':'')
   +(cur&&cur!==n.func?'<div class="row"><span class="lbl">'+esc(STR.detNow)+'</span><span class="now">'+esc(cur)+'</span></div>':'')
@@ -431,7 +487,7 @@ function showRoster(cat){
  $("detail").innerHTML=head;$("detail").style.display="block";
  var dc=$("dc");if(dc)dc.addEventListener("click",function(){$("detail").style.display="none";});
  function rowHtml(m){
-  var d=m.current||m.func||m.tech||"";
+  var d=m.current||m.func||"";
   var pct=m.completion!=null?(m.completion+"%"):(m.statusWord||"");
   return '<span class="ritem">'+(pct?'<span class="rp">'+esc(pct)+'</span>':'')
    +'<span class="rn">'+esc(m.name)+'</span>'
@@ -471,7 +527,9 @@ function wire(){
   pos[drag.id].y=clamp(p.y-drag.oy,4,lay.H-pos[drag.id].h-4);
   drag.moved=true;draw(false);
  });
- document.addEventListener("mouseup",function(){if(drag){if(drag.moved)justDragged=true;drag=null;}});
+ document.addEventListener("mouseup",function(){if(!drag)return;var m=drag.moved;drag=null;
+  // refit after the drop, deferred so the click that follows mouseup still lands on the live DOM
+  if(m){justDragged=true;setTimeout(function(){draw(false);},0);}});
  // edge label on hover (invisible fat hit-path)
  stage.addEventListener("mouseover",function(ev){
   if(ev.target.classList&&ev.target.classList.contains("edgehit")){
@@ -534,7 +592,7 @@ function applyStrings(){
  set("pexp",STR.printExport);set("pexpSvg",STR.exportSvg);set("pexpPng",STR.exportPng);
  set("pexpLayout",STR.exportLayout);set("pexpPrint",STR.print);
  set("lg-done",STR.legDone);set("lg-prog",STR.legProg);set("lg-next",STR.legNext);
- set("lg-plan",STR.legPlan);set("lg-prob",STR.legProb);set("lg-hint",STR.legHint);
+ set("lg-plan",STR.legPlan);set("lg-prob",STR.legProb);set("lg-unk",STR.legUnk);set("lg-hint",STR.legHint);
 }
 // ---- FEATURE #2: PRINT / EXPORT (all client-side, offline) ----
 function exportBaseName(){
@@ -551,7 +609,7 @@ function collectSvgCss(){
   if(!rules)continue;
   for(j=0;j<rules.length;j++){var r=rules[j],t=r.cssText||"";
    // keep rules that target svg-internal classes/elements + the color vars on :root/html
-   if(/\.(nd|edge|edgehit|elbl|s-done|s-prog|s-next|s-plan|s-prob|mode-t|tt|kk|dd|pp|plus|cat)\b/.test(t)
+   if(/\.(nd|edge|edgehit|elbl|s-done|s-prog|s-next|s-plan|s-prob|s-unk|mode-t|tt|kk|dd|pp|plus|cat)\b/.test(t)
       ||/(^|[\s,])svg\b/.test(t)||/:root|html\[data-skin/.test(t)){
     // drop animations for a static export (keepdefs stable)
     out.push(t);
@@ -564,7 +622,7 @@ function collectSvgCss(){
 // with the on-screen palette. Returns a "--k:v;--k:v" inline-style string.
 var SVG_VARS=["--bg","--grid","--halo","--cyan","--sec","--ter","--ter2","--nm",
  "--stagebg","--stageborder","--nodebg","--detailbg","--border","--done","--prog",
- "--next","--plan","--planTxt","--prob","--edge","--edgeplan","--elbl","--ddtxt",
+ "--next","--plan","--planTxt","--prob","--unk","--edge","--edgeplan","--elbl","--ddtxt",
  "--now","--tgt","--src"];
 function resolvedVars(){
  var cs;try{cs=getComputedStyle(document.documentElement);}catch(e){return "";}
@@ -577,14 +635,14 @@ function serializeSvg(){
  clone.setAttribute("xmlns","http://www.w3.org/2000/svg");
  clone.setAttribute("xmlns:xlink","http://www.w3.org/1999/xlink");
  var vb=(svg.getAttribute("viewBox")||"0 0 1080 660").split(/\s+/);
- var w=+vb[2]||1080,h=+vb[3]||660;
+ var vbx=+vb[0]||0,vby=+vb[1]||0,w=+vb[2]||1080,h=+vb[3]||660;
  clone.setAttribute("width",w);clone.setAttribute("height",h);
  // Inline the resolved variables on the root so var(--x) resolves standalone,
  // independent of the skin-selector chain that won't exist in the exported file.
  var vars=resolvedVars();if(vars)clone.setAttribute("style",vars);
  // solid dark/light background so the standalone file isn't transparent
  var bg=cssv("--stagebg")||"#050d14";
- var rect='<rect x="0" y="0" width="'+w+'" height="'+h+'" fill="'+bg+'"/>';
+ var rect='<rect x="'+vbx+'" y="'+vby+'" width="'+w+'" height="'+h+'" fill="'+bg+'"/>';
  var style="<style>"+collectSvgCss()+"</style>";
  var inner=clone.innerHTML;
  var attrs='';for(var a=0;a<clone.attributes.length;a++){var at=clone.attributes[a];attrs+=' '+at.name+'="'+String(at.value).replace(/"/g,"&quot;")+'"';}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forma-arch",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Forma — present your architecture instead of slides. An interactive, stack-agnostic C4 explorer (context → container → component → leaf) generated from your code and kept true to it by a deterministic drift check.",
   "keywords": [
     "architecture",