@laitszkin/apollo-toolkit 3.11.0 → 3.11.2

package/init-project-html/lib/atlas/cli.js

@@ -22,7 +22,7 @@
 //   help / --help / -h                            usage
 //
 // Global flags:
-//   --project <root>     project root (default: nearest ancestor with resources/project-architecture/)
+//   --project <root>     project root; creates resources/project-architecture/ if missing
 //   --spec <spec_dir>    spec directory; mutations go to <spec_dir>/architecture_diff/atlas/
 //   --no-render          skip auto-render after a mutation
 //   --no-open            for open/diff: skip launching the browser
@@ -67,7 +67,7 @@ Verbs:
   help                                  show this help
 
 Global flags:
-  --project <root>                      project root (default: nearest ancestor with resources/project-architecture/)
+  --project <root>                      explicit project root (default: nearest ancestor with atlas markers, else cwd); missing directories under resources/project-architecture/ are created automatically
   --spec <spec_dir>                     mutations write to <spec_dir>/architecture_diff/atlas/
   --no-render                           skip auto-render after a mutation
   --no-open                             for open/diff: skip launching the browser
@@ -77,6 +77,8 @@ Examples:
   apltk architecture feature add --slug register --title "User registration" --story "..."
   apltk architecture submodule add --feature register --slug api --kind api --role "HTTP endpoint"
   apltk architecture function add --feature register --submodule api --name handlePost --side network --purpose "..."
+  apltk architecture variable add --feature register --submodule api --name token --type "string" --scope call --purpose "..."
+  apltk architecture dataflow add --feature register --submodule api --step "Validate body" --fn handlePost --reads "body" --writes "token"
   apltk architecture --spec docs/plans/2026-05-11/add-2fa submodule set --feature register --slug api --role "..."
   apltk architecture validate
   apltk architecture diff
@@ -96,6 +98,10 @@ function openInBrowser(filePath) {
   } catch (_e) { /* best effort */ }
 }
 
+function ensureResourcesLayout(projectRoot) {
+  fs.mkdirSync(path.join(projectRoot, ATLAS_REL), { recursive: true });
+}
+
 function findProjectRoot(startDir) {
   let dir = path.resolve(startDir);
   while (true) {
@@ -152,10 +158,15 @@ function requireFlag(flags, name) {
 }
 
 function resolveProjectRoot(flags) {
-  if (flags.project) return path.resolve(String(flags.project));
-  const root = findProjectRoot(process.cwd());
-  if (!root) throw new Error('Could not find resources/project-architecture/. Pass --project <root> or run inside the project.');
-  return root;
+  const finish = (root) => {
+    ensureResourcesLayout(root);
+    return root;
+  };
+  if (flags.project) return finish(path.resolve(String(flags.project)));
+  const discovered = findProjectRoot(process.cwd());
+  if (discovered) return finish(discovered);
+  // No marker walking parents — use cwd and create resources/project-architecture/.
+  return finish(process.cwd());
 }
 
 function specOverlayDir(projectRoot, specFlag) {
@@ -449,13 +460,14 @@ async function verbDataflow(action, flags, projectRoot) {
     sub.dataflow = sub.dataflow || [];
     if (action === 'add') {
       const step = String(requireFlag(flags, 'step'));
+      const item = buildDataflowItem(step, flags);
       const atRaw = flags.at;
       if (atRaw !== undefined) {
         const at = Number(atRaw);
         if (!Number.isFinite(at) || at < 0) throw new Error('--at must be a non-negative integer');
-        sub.dataflow.splice(at, 0, step);
+        sub.dataflow.splice(at, 0, item);
       } else {
-        sub.dataflow.push(step);
+        sub.dataflow.push(item);
       }
     } else if (action === 'remove') {
       if (flags.at !== undefined) {
@@ -464,7 +476,7 @@ async function verbDataflow(action, flags, projectRoot) {
         sub.dataflow.splice(at, 1);
       } else {
         const step = String(requireFlag(flags, 'step'));
-        sub.dataflow = sub.dataflow.filter((s) => s !== step);
+        sub.dataflow = sub.dataflow.filter((s) => stepText(s) !== step);
       }
     } else if (action === 'reorder') {
       const from = Number(requireFlag(flags, 'from'));
@@ -481,6 +493,31 @@ async function verbDataflow(action, flags, projectRoot) {
   });
 }
 
+function stepText(item) {
+  return typeof item === 'string' ? item : (item && typeof item.step === 'string' ? item.step : '');
+}
+
+function parseNameList(raw) {
+  if (raw === undefined || raw === null) return undefined;
+  return String(raw)
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+function buildDataflowItem(step, flags) {
+  const fn = flags.fn === undefined ? undefined : String(flags.fn).trim();
+  const reads = parseNameList(flags.reads);
+  const writes = parseNameList(flags.writes);
+  const annotated = (fn && fn.length > 0) || (reads && reads.length > 0) || (writes && writes.length > 0);
+  if (!annotated) return step;
+  const item = { step };
+  if (fn) item.fn = fn;
+  if (reads && reads.length > 0) item.reads = reads;
+  if (writes && writes.length > 0) item.writes = writes;
+  return item;
+}
+
 async function verbError(action, flags, projectRoot) {
   const featureSlug = String(requireFlag(flags, 'feature'));
   const subSlug = String(requireFlag(flags, 'submodule'));
@@ -627,14 +664,10 @@ async function verbUndo(flags, projectRoot, io) {
 async function verbOpen(flags, projectRoot, io) {
   const atlas = path.join(projectRoot, ATLAS_INDEX_REL);
   if (!fs.existsSync(atlas)) {
-    // Try to render fresh if state exists
-    const baseDir = baseAtlasDir(projectRoot);
-    if (fs.existsSync(path.join(baseDir, stateLib.INDEX_FILE))) {
-      await runRender({ projectRoot, flags: { ...flags, spec: undefined } });
-    }
+    await runRender({ projectRoot, flags: { ...flags, spec: undefined } });
   }
   if (!fs.existsSync(atlas)) {
-    io.stderr.write(`Atlas not found: ${atlas}\n`);
+    io.stderr.write(`Atlas not found after render: ${atlas}\n`);
     return 1;
   }
   io.stdout.write(`${atlas}\n`);

package/init-project-html/lib/atlas/layout.js

@@ -11,18 +11,111 @@
 
 const ELK = require('elkjs');
 
+// Default fallback box. The actual width/height for each sub-module
+// is computed per node by measureSubmodule() so the role/description
+// fits without overflowing the rectangle.
 const SUB_WIDTH = 240;
 const SUB_HEIGHT = 92;
+
+// Box-sizing knobs (intrinsic SVG coordinates).
+const SUB_WIDTH_MIN = 220;
+const SUB_WIDTH_MAX = 360;
+const SUB_HEIGHT_MIN = 92;
+const SUB_HEIGHT_MAX = 220;
+const SUB_SIDE_PAD = 16;
+const SUB_TOP_PAD = 14;
+const SUB_BOTTOM_PAD = 14;
+const TITLE_LINE = 22;     // slug line
+const KIND_LINE = 16;      // kind chip line
+const ROLE_LINE = 16;      // each role line
+const KIND_GAP = 4;
+const ROLE_GAP = 8;
+const MAX_ROLE_LINES = 4;
+
 const CLUSTER_PAD_TOP = 60;
 const CLUSTER_PAD_SIDE = 24;
 const CLUSTER_PAD_BOTTOM = 28;
 const EDGE_LABEL_HEIGHT = 18;
 
+const KIND_LABELS = {
+  ui: 'UI',
+  api: 'API',
+  service: 'service',
+  db: 'database',
+  'pure-fn': 'pure function',
+  queue: 'queue',
+  external: 'external',
+};
+
 function estimateLabelWidth(text) {
   if (!text) return 0;
   return Math.min(220, Math.max(40, String(text).length * 7 + 16));
 }
 
+// Approximate render width of a string in the target font. The 0.6
+// factor is a deliberate over-estimate for our sans-serif stack so
+// the chosen width almost always leaves a little breathing room.
+function approxTextWidth(text, fontPx) {
+  return String(text || '').length * fontPx * 0.6;
+}
+
+function wrapToLines(text, maxChars) {
+  if (!text) return [];
+  const words = String(text).split(/\s+/).filter(Boolean);
+  const lines = [];
+  let current = '';
+  for (const word of words) {
+    if (!current) { current = word; continue; }
+    if ((current.length + 1 + word.length) <= maxChars) current = `${current} ${word}`;
+    else { lines.push(current); current = word; }
+  }
+  if (current) lines.push(current);
+  return lines;
+}
+
+// measureSubmodule picks a width + height that fit the slug, the kind
+// chip, and the wrapped role text. Both layout.js (when telling elkjs
+// how much room each node needs) and render.js (when actually drawing
+// the text inside the box) call it so the rendered text never spills
+// outside the rectangle the layout engine reserved.
+function measureSubmodule(sub) {
+  const slug = (sub && sub.slug) || '';
+  const kindLabel = KIND_LABELS[sub && sub.kind] || (sub && sub.kind) || 'service';
+  const role = (sub && sub.role) || '';
+
+  const slugW = approxTextWidth(slug, 14);
+  const kindW = approxTextWidth(kindLabel, 11);
+  const baseInner = Math.max(slugW, kindW);
+
+  // Aim to keep the role within ~3 lines: choose a width whose text
+  // area can hold ceil(roleLen / 3) characters, then clamp.
+  const roleLen = role.length;
+  let chosenInner;
+  if (!role) {
+    chosenInner = baseInner;
+  } else {
+    const targetCharsPerLine = Math.max(20, Math.ceil(roleLen / 3));
+    chosenInner = Math.max(baseInner, targetCharsPerLine * 11 * 0.55);
+  }
+  const width = Math.max(SUB_WIDTH_MIN, Math.min(SUB_WIDTH_MAX, Math.ceil(chosenInner + SUB_SIDE_PAD * 2)));
+
+  // With the chosen width fixed, wrap the role for real and count lines.
+  const innerW = width - SUB_SIDE_PAD * 2;
+  const charsPerLine = Math.max(12, Math.floor(innerW / (11 * 0.55)));
+  let roleLines = role ? wrapToLines(role, charsPerLine) : [];
+  if (roleLines.length > MAX_ROLE_LINES) {
+    roleLines = roleLines.slice(0, MAX_ROLE_LINES);
+    const last = roleLines[MAX_ROLE_LINES - 1];
+    roleLines[MAX_ROLE_LINES - 1] = last.length > 3 ? `${last.slice(0, -1)}…` : `${last}…`;
+  }
+
+  const roleBlock = roleLines.length > 0 ? ROLE_GAP + roleLines.length * ROLE_LINE : 0;
+  const intrinsicH = SUB_TOP_PAD + TITLE_LINE + KIND_GAP + KIND_LINE + roleBlock + SUB_BOTTOM_PAD;
+  const height = Math.max(SUB_HEIGHT_MIN, Math.min(SUB_HEIGHT_MAX, Math.ceil(intrinsicH)));
+
+  return { width, height, roleLines, kindLabel };
+}
+
 function endpointId(endpoint, ownerFeature) {
   if (typeof endpoint === 'string') {
     return `submodule::${ownerFeature}::${endpoint}`;
@@ -53,17 +146,20 @@ function buildGraph(state) {
       'elk.layered.spacing.nodeNodeBetweenLayers': '36',
       'elk.nodeLabels.placement': '[H_CENTER, V_TOP, INSIDE]',
     },
-    children: (feature.submodules || []).map((sub) => ({
-      id: `submodule::${feature.slug}::${sub.slug}`,
-      width: SUB_WIDTH,
-      height: SUB_HEIGHT,
-      labels: [{
-        id: `submodule::${feature.slug}::${sub.slug}::label`,
-        text: sub.slug,
-        width: estimateLabelWidth(sub.slug),
-        height: 18,
-      }],
-    })),
+    children: (feature.submodules || []).map((sub) => {
+      const box = measureSubmodule(sub);
+      return {
+        id: `submodule::${feature.slug}::${sub.slug}`,
+        width: box.width,
+        height: box.height,
+        labels: [{
+          id: `submodule::${feature.slug}::${sub.slug}::label`,
+          text: sub.slug,
+          width: estimateLabelWidth(sub.slug),
+          height: 18,
+        }],
+      };
+    }),
   }));
 
   let nextEdgeId = 0;
@@ -223,7 +319,12 @@ async function layoutMacro(state) {
 module.exports = {
   SUB_WIDTH,
   SUB_HEIGHT,
+  SUB_WIDTH_MIN,
+  SUB_WIDTH_MAX,
+  SUB_HEIGHT_MIN,
+  SUB_HEIGHT_MAX,
   layoutMacro,
   assertNoOverlap,
   buildGraph,
+  measureSubmodule,
 };

package/init-project-html/lib/atlas/render.js

@@ -13,7 +13,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
-const { layoutMacro } = require('./layout');
+const { layoutMacro, measureSubmodule } = require('./layout');
 
 const KIND_LABEL = {
   ui: 'UI',
@@ -115,21 +115,27 @@ function renderMacroSvg(layout, state) {
 
   for (const sub of layout.submodules) {
     const subState = ((state.features || []).find((f) => f.slug === sub.featureSlug) || {}).submodules || [];
-    const meta = subState.find((s) => s.slug === sub.slug);
-    const kind = (meta && meta.kind) || 'service';
+    const meta = subState.find((s) => s.slug === sub.slug) || {};
+    const kind = meta.kind || 'service';
+    const role = meta.role || '';
+    const measured = measureSubmodule({ slug: sub.slug, kind, role });
+
     const cx = sub.x + sub.width / 2;
-    const labelY = sub.y + 28;
-    const kindLabelY = sub.y + 52;
-    const role = meta && meta.role ? meta.role : '';
+    const titleY = sub.y + 14 + 16; // SUB_TOP_PAD (14) + ascent for the title line
+    const kindY = titleY + 4 + 12; // KIND_GAP + kind ascent
+    const roleStartY = kindY + 8 + 12; // ROLE_GAP + first role line ascent
+
     const href = `features/${sub.featureSlug}/${sub.slug}.html`;
-    parts.push(`    <a class="m-node m-node--${kind}" href="${htmlEscape(href)}" data-feature="${htmlEscape(sub.featureSlug)}" data-submodule="${htmlEscape(sub.slug)}">`);
+    const tooltip = role ? `${sub.slug} — ${role}` : sub.slug;
+    parts.push(`    <a class="m-node m-node--${kind}" href="${htmlEscape(href)}" data-feature="${htmlEscape(sub.featureSlug)}" data-submodule="${htmlEscape(sub.slug)}" tabindex="0" aria-label="${htmlEscape(tooltip)} — open sub-module page">`);
+    parts.push(`      <title>${htmlEscape(tooltip)}</title>`);
     parts.push(`      <rect x="${sub.x.toFixed(2)}" y="${sub.y.toFixed(2)}" width="${sub.width.toFixed(2)}" height="${sub.height.toFixed(2)}" rx="10" ry="10" />`);
-    parts.push(`      <text class="m-node__title" x="${cx.toFixed(2)}" y="${labelY.toFixed(2)}" text-anchor="middle">${htmlEscape(sub.slug)}</text>`);
-    parts.push(`      <text class="m-node__kind" x="${cx.toFixed(2)}" y="${kindLabelY.toFixed(2)}" text-anchor="middle">${htmlEscape(KIND_LABEL[kind] || kind)}</text>`);
-    if (role) {
-      const truncated = role.length > 38 ? `${role.slice(0, 36)}…` : role;
-      parts.push(`      <text class="m-node__role" x="${cx.toFixed(2)}" y="${(sub.y + sub.height - 14).toFixed(2)}" text-anchor="middle">${htmlEscape(truncated)}</text>`);
-    }
+    parts.push(`      <text class="m-node__title" x="${cx.toFixed(2)}" y="${titleY.toFixed(2)}" text-anchor="middle">${htmlEscape(sub.slug)}</text>`);
+    parts.push(`      <text class="m-node__kind" x="${cx.toFixed(2)}" y="${kindY.toFixed(2)}" text-anchor="middle">${htmlEscape(measured.kindLabel || KIND_LABEL[kind] || kind)}</text>`);
+    measured.roleLines.forEach((line, idx) => {
+      const ly = roleStartY + idx * 16;
+      parts.push(`      <text class="m-node__role" x="${cx.toFixed(2)}" y="${ly.toFixed(2)}" text-anchor="middle">${htmlEscape(line)}</text>`);
+    });
     parts.push('    </a>');
   }
 
@@ -286,33 +292,111 @@ ${rows.map((r) => `          <tr>${r.map((c) => `<td>${htmlEscape(c == null ? ''
       </table>`;
 }
 
+function normalizeDataflowStep(item) {
+  if (typeof item === 'string') return { step: item, fn: '', reads: [], writes: [] };
+  if (!item || typeof item !== 'object') return { step: '', fn: '', reads: [], writes: [] };
+  return {
+    step: typeof item.step === 'string' ? item.step : '',
+    fn: typeof item.fn === 'string' ? item.fn.trim() : '',
+    reads: Array.isArray(item.reads) ? item.reads.filter((v) => typeof v === 'string' && v.trim()) : [],
+    writes: Array.isArray(item.writes) ? item.writes.filter((v) => typeof v === 'string' && v.trim()) : [],
+  };
+}
+
 function renderInternalDataflowSvg(steps) {
   if (!steps || steps.length === 0) {
     return '<p class="sub-dataflow__empty">No internal dataflow steps recorded.</p>';
   }
-  const boxW = 360;
-  const boxH = 56;
-  const gap = 28;
-  const totalH = steps.length * boxH + (steps.length - 1) * gap + 40;
+
+  // Each step renders as a box with three optional zones: a top fn pill
+  // (which function executes this step), the step description in the
+  // middle, and a bottom row of variable chips (← reads / → writes).
+  // The surrounding viewport handles zoom/pan, so we size boxes to the
+  // content rather than the viewport.
+  const boxW = 520;
+  const lineHeight = 20;
+  const innerPadY = 18;
+  const fnRowH = 32;       // fn pill + spacing
+  const chipsRowH = 26;    // chips row + spacing
+  const minBoxH = 72;
+  const gap = 44;
+  const padLeft = 80;      // room for the left-side step-number badge
+  const padTop = 32;
+  const padBottom = 32;
+  const padRight = 28;
+
+  const normalized = steps.map(normalizeDataflowStep);
+  const layouts = normalized.map((s) => {
+    const lines = wrapText(s.step, 60);
+    const hasFn = s.fn.length > 0;
+    const hasChips = s.reads.length > 0 || s.writes.length > 0;
+    const textBlockH = lines.length * lineHeight;
+    const boxH = Math.max(minBoxH, innerPadY * 2 + (hasFn ? fnRowH : 0) + textBlockH + (hasChips ? chipsRowH : 0));
+    return { lines, hasFn, hasChips, boxH };
+  });
+
+  const totalH = padTop + layouts.reduce((a, l) => a + l.boxH, 0) + (normalized.length - 1) * gap + padBottom;
+  const totalW = padLeft + boxW + padRight;
+
   const parts = [];
-  parts.push(`<svg class="sub-dataflow__svg" viewBox="0 0 ${boxW + 40} ${totalH}" role="img" aria-label="Internal dataflow">`);
-  parts.push('  <defs><marker id="sub-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 Z" /></marker></defs>');
-  steps.forEach((step, i) => {
-    const y = 20 + i * (boxH + gap);
-    parts.push(`  <g class="sub-dataflow__step">`);
-    parts.push(`    <rect x="20" y="${y}" width="${boxW}" height="${boxH}" rx="8" ry="8" />`);
-    const lines = wrapText(step, 52);
-    lines.forEach((line, idx) => {
-      const ly = y + 24 + idx * 16;
-      parts.push(`    <text x="${20 + boxW / 2}" y="${ly}" text-anchor="middle">${htmlEscape(line)}</text>`);
+  parts.push(`<svg class="sub-dataflow__svg" data-atlas-svg="sub-dataflow" viewBox="0 0 ${totalW} ${totalH}" role="img" aria-label="Internal dataflow">`);
+  parts.push('  <defs>');
+  parts.push('    <marker id="sub-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 Z" /></marker>');
+  parts.push('  </defs>');
+
+  let cursorY = padTop;
+  normalized.forEach((s, i) => {
+    const layout = layouts[i];
+    const boxX = padLeft;
+    const boxY = cursorY;
+    const boxH = layout.boxH;
+    const badgeCx = padLeft - 38;
+    const badgeCy = boxY + boxH / 2;
+
+    parts.push('  <g class="sub-dataflow__step">');
+    parts.push(`    <circle class="sub-dataflow__badge" cx="${badgeCx}" cy="${badgeCy}" r="18" />`);
+    parts.push(`    <text class="sub-dataflow__badge-text" x="${badgeCx}" y="${badgeCy + 5}" text-anchor="middle">${i + 1}</text>`);
+    parts.push(`    <rect class="sub-dataflow__box" x="${boxX}" y="${boxY}" width="${boxW}" height="${boxH}" rx="14" ry="14" />`);
+
+    if (layout.hasFn) {
+      const fnLabel = `fn ${s.fn}`;
+      const pillX = boxX + 14;
+      const pillY = boxY + 14;
+      const pillW = Math.max(72, fnLabel.length * 7.4 + 20);
+      parts.push(`    <rect class="sub-dataflow__fn-bg" x="${pillX}" y="${pillY}" width="${pillW}" height="20" rx="10" ry="10" />`);
+      parts.push(`    <text class="sub-dataflow__fn-text" x="${pillX + 10}" y="${pillY + 14}">${htmlEscape(fnLabel)}</text>`);
+    }
+
+    const topUsed = layout.hasFn ? fnRowH : 0;
+    const bottomUsed = layout.hasChips ? chipsRowH : 0;
+    const textZoneH = boxH - topUsed - bottomUsed;
+    const textBlockH = layout.lines.length * lineHeight;
+    const textStartY = boxY + topUsed + (textZoneH - textBlockH) / 2 + lineHeight - 4;
+    layout.lines.forEach((line, idx) => {
+      parts.push(`    <text class="sub-dataflow__text" x="${boxX + boxW / 2}" y="${textStartY + idx * lineHeight}" text-anchor="middle">${htmlEscape(line)}</text>`);
     });
+
+    if (layout.hasChips) {
+      const chipY = boxY + boxH - 12;
+      if (s.reads.length > 0) {
+        const text = `← reads: ${s.reads.join(', ')}`;
+        parts.push(`    <text class="sub-dataflow__chip sub-dataflow__chip--reads" x="${boxX + 14}" y="${chipY}">${htmlEscape(text)}</text>`);
+      }
+      if (s.writes.length > 0) {
+        const text = `→ writes: ${s.writes.join(', ')}`;
+        parts.push(`    <text class="sub-dataflow__chip sub-dataflow__chip--writes" x="${boxX + boxW - 14}" y="${chipY}" text-anchor="end">${htmlEscape(text)}</text>`);
+      }
+    }
+
     parts.push('  </g>');
-    if (i < steps.length - 1) {
-      const aY = y + boxH;
-      const bY = aY + gap;
-      const x = 20 + boxW / 2;
+
+    if (i < normalized.length - 1) {
+      const aY = boxY + boxH + 6;
+      const bY = aY + gap - 14;
+      const x = boxX + boxW / 2;
       parts.push(`  <line class="sub-dataflow__arrow" x1="${x}" y1="${aY}" x2="${x}" y2="${bY}" marker-end="url(#sub-arrow)" />`);
     }
+    cursorY += boxH + gap;
   });
   parts.push('</svg>');
   return parts.join('\n');
@@ -329,7 +413,9 @@ function wrapText(text, maxChars) {
     else { lines.push(current); current = word; }
   }
   if (current) lines.push(current);
-  return lines.slice(0, 3);
+  // Allow up to 4 lines so long error/rollback notes stay readable; the
+  // surrounding viewport handles scroll/zoom for anything beyond.
+  return lines.slice(0, 4);
 }
 
 function renderSubmodulePage({ feature, sub, outDir }) {
@@ -361,7 +447,18 @@ function renderSubmodulePage({ feature, sub, outDir }) {
     </section>
     <section class="sub-dataflow" aria-label="Internal data flow">
       <h2>Internal data flow</h2>
-      ${renderInternalDataflowSvg(sub.dataflow)}
+      ${(sub.dataflow && sub.dataflow.length > 0)
+        ? `<div class="sub-dataflow__canvas" data-pan-zoom-container>
+        <div class="sub-dataflow__toolbar" role="toolbar" aria-label="Diagram controls">
+          <button type="button" data-pan-zoom="zoom-in" aria-label="Zoom in">+</button>
+          <button type="button" data-pan-zoom="zoom-out" aria-label="Zoom out">−</button>
+          <button type="button" data-pan-zoom="fit" aria-label="Reset view">Fit</button>
+        </div>
+        <div class="sub-dataflow__viewport" data-pan-zoom-viewport>
+          ${renderInternalDataflowSvg(sub.dataflow)}
+        </div>
+      </div>`
+        : renderInternalDataflowSvg(sub.dataflow)}
     </section>
     <section class="sub-errors" aria-label="Errors">
       <h2>Errors</h2>
@@ -370,6 +467,7 @@ function renderSubmodulePage({ feature, sub, outDir }) {
         : '<p class="sub-section__empty">No errors recorded.</p>'}
     </section>
   </main>
+  <script src="${assetRel}/viewer.client.js" defer></script>
 </body>
 </html>`;
 

package/init-project-html/lib/atlas/schema.js

@@ -128,10 +128,47 @@ function validateSubmodule(sub, errors, where) {
   }
   if (sub && sub.dataflow) {
     if (!Array.isArray(sub.dataflow)) {
-      errors.push(`${where}: "dataflow" must be an array of step strings`);
+      errors.push(`${where}: "dataflow" must be an array`);
     } else {
+      const fnNames = new Set((sub.functions || []).map((f) => f && f.name).filter(Boolean));
+      const varNames = new Set((sub.variables || []).map((v) => v && v.name).filter(Boolean));
       sub.dataflow.forEach((step, i) => {
-        if (typeof step !== 'string') errors.push(`${where}.dataflow[${i}]: must be a string`);
+        const stepWhere = `${where}.dataflow[${i}]`;
+        if (typeof step === 'string') {
+          if (!step.trim()) errors.push(`${stepWhere}: step text must be non-empty`);
+          return;
+        }
+        if (!step || typeof step !== 'object') {
+          errors.push(`${stepWhere}: must be a string or an object with "step"`);
+          return;
+        }
+        if (!isNonEmptyString(step.step)) {
+          errors.push(`${stepWhere}: "step" must be a non-empty string`);
+        }
+        if (step.fn !== undefined) {
+          if (typeof step.fn !== 'string' || !step.fn.trim()) {
+            errors.push(`${stepWhere}: "fn" must be a non-empty string when present`);
+          } else if (!fnNames.has(step.fn)) {
+            errors.push(`${stepWhere}: "fn" references unknown function "${step.fn}" — declare it via \`function add\` first`);
+          }
+        }
+        for (const field of ['reads', 'writes']) {
+          if (step[field] === undefined) continue;
+          if (!Array.isArray(step[field])) {
+            errors.push(`${stepWhere}: "${field}" must be an array of variable names`);
+            continue;
+          }
+          step[field].forEach((name, j) => {
+            const refWhere = `${stepWhere}.${field}[${j}]`;
+            if (typeof name !== 'string' || !name.trim()) {
+              errors.push(`${refWhere}: variable name must be a non-empty string`);
+              return;
+            }
+            if (!varNames.has(name)) {
+              errors.push(`${refWhere}: unknown variable "${name}" — declare it via \`variable add\` first`);
+            }
+          });
+        }
       });
     }
   }

package/init-project-html/references/TEMPLATE_SPEC.md

@@ -60,7 +60,7 @@ CLI: `apltk architecture feature add --slug <kebab> --title "..." --story "..."
 | role       | string | no | Own responsibility in one sentence. Renders as macro node footnote + feature card subtitle. |
 | functions  | array of function row | no | Renders the `sub-io` table. |
 | variables  | array of variable row | no | Renders the `sub-vars` table. |
-| dataflow   | array of string (ordered) | no | Renders the `sub-dataflow` internal flow SVG. |
+| dataflow   | array of dataflow step (string OR object — see below) | no | Renders the `sub-dataflow` internal flow SVG. |
 | errors     | array of error row | no | Renders the `sub-errors` table. |
 
 CLI: `apltk architecture submodule add --feature X --slug Y --kind api --role "..."`
@@ -90,9 +90,22 @@ CLI: `apltk architecture variable add --feature X --submodule Y --name v --type
 
 ### `dataflow` step
 
-A simple ordered string. Appended at the tail by default; pass `--at N` to insert at index N. Reorder with `apltk architecture dataflow reorder --feature X --submodule Y --from i --to j`.
+Each step is either a plain string OR an object with one required and three optional fields. The renderer arranges them top-to-bottom inside a pan/zoom viewport; `--fn` becomes a function pill at the top of the step box, `--reads` becomes a green chip on the bottom-left, `--writes` becomes an orange chip on the bottom-right.
 
-CLI: `apltk architecture dataflow add --feature X --submodule Y --step "..."`
+| Field   | Type | Required | Notes |
+| ------- | ---- | -------- | ----- |
+| step    | string | yes | The action / observation in one short sentence. |
+| fn      | string | no  | Name of a `function` already declared in the SAME sub-module. `validate` fails otherwise. Use it to surface function-to-function transitions inside the sub-module. |
+| reads   | array of variable names | no | Each name must be a `variable` declared in the SAME sub-module. Shows up as `← reads: …` chip. |
+| writes  | array of variable names | no | Same constraint as `reads`. Shows up as `→ writes: …` chip. |
+
+Appended at the tail by default; pass `--at N` to insert at index N. Reorder with `apltk architecture dataflow reorder --feature X --submodule Y --from i --to j`. `--reads` / `--writes` accept comma-separated lists (`--reads "a, b"`).
+
+CLI:
+
+```
+apltk architecture dataflow add --feature X --submodule Y --step "..." [--fn <declared-fn>] [--reads "v1,v2"] [--writes "v3,v4"]
+```
 
 ### `error` row
 
@@ -125,13 +138,18 @@ These are emitted automatically by `lib/atlas/render.js`. Agents do **not** writ
 | `.atlas-header`, `.atlas-summary`, `.atlas-canvas`, `.atlas-submodule-index`, `.atlas-legend` | macro |
 | `.m-cluster`, `.m-cluster__title`, `.m-node`, `.m-node--<kind>`, `.m-node__title/__kind/__role`, `.m-edge`, `.m-edge--<kind>`, `.m-edge__label` | macro SVG |
 | `.feature-header`, `.feature-story`, `.submodule-nav`, `.submodule-card`, `.feature-edges` | feature page |
-| `.submodule-header`, `.submodule-role`, `.sub-io`, `.sub-vars`, `.sub-dataflow`, `.sub-errors`, `.submodule-kind--<kind>` | sub-module page |
+| `.submodule-header`, `.submodule-role`, `.sub-io`, `.sub-vars`, `.sub-dataflow`, `.sub-dataflow__canvas`, `.sub-dataflow__toolbar`, `.sub-dataflow__viewport`, `.sub-dataflow__step`, `.sub-dataflow__badge`, `.sub-dataflow__fn-text`, `.sub-dataflow__chip--reads`, `.sub-dataflow__chip--writes`, `.sub-errors`, `.submodule-kind--<kind>` | sub-module page |
+
+## Pan/zoom
+
+The CLI copies `assets/viewer.client.js` into the atlas. Two viewports exist:
 
-## Pan/zoom on the macro
+- macro `index.html` — one `[data-pan-zoom-viewport]` wrapping the atlas SVG.
+- each sub-module page — one `[data-pan-zoom-viewport]` wrapping the sub-dataflow SVG (when the sub-module has any `dataflow` step).
 
-The CLI copies `assets/viewer.client.js` into the atlas. The macro page mounts a `[data-pan-zoom-viewport]` element wrapping the SVG; the script wires:
+For every viewport the script wires:
 
 - mouse wheel zoom around the cursor,
 - click + drag to pan,
-- `+` / `−` / `Fit` buttons on the toolbar,
-- keyboard `←` `→` `↑` `↓` (pan), `+` `=` (zoom in), `−` `_` (zoom out), `0` (reset).
+- `+` / `−` / `Fit` buttons on the toolbar (scoped to the surrounding `[data-pan-zoom-container]`),
+- keyboard `←` `→` `↑` `↓` (pan), `+` `=` (zoom in), `−` `_` (zoom out), `0` (reset) — applied to the page's primary viewport.