atris 3.25.2 → 3.27.0

package/lib/memory-view.js

@@ -0,0 +1,95 @@
+// Memory view — another way to look at memory updates. Reads the workspace's
+// compounding memory (lessons.md, learnings.jsonl, task projection) and builds a
+// content spec rendered as a beautiful HTML page by lib/html-render.
+//
+// Pure-ish: file reads in, a { theme, brand, slides } spec out. Anti-slop by
+// construction (the renderer sanitizes, so em dashes in the raw lessons file
+// never reach the page).
+
+const fs = require('fs');
+const path = require('path');
+
+// "- **[2026-06-18] some-id** — pass — text..." -> { date, id, status, text }
+function parseLessons(text) {
+  const out = [];
+  for (const line of String(text || '').split('\n')) {
+    const m = line.match(/^-\s*\*\*\[([^\]]+)\]\s*([^*]+?)\*\*\s*[—:-]*\s*(pass|fail)?\s*[—:-]*\s*(.*)$/i);
+    if (!m) continue;
+    out.push({ date: m[1].trim(), id: m[2].trim(), status: (m[3] || '').toLowerCase(), text: m[4].trim() });
+  }
+  return out; // append-only file: oldest first
+}
+
+function parseLearnings(text) {
+  const out = [];
+  for (const line of String(text || '').split('\n')) {
+    if (!line.trim()) continue;
+    try { const j = JSON.parse(line); out.push({ ts: j.ts, type: j.type, key: j.key, insight: j.insight }); } catch {}
+  }
+  return out;
+}
+
+function readFileSafe(p) { try { return fs.readFileSync(p, 'utf8'); } catch { return ''; } }
+
+function readTaskCounts(root) {
+  try {
+    const j = JSON.parse(readFileSafe(path.join(root, '.atris', 'state', 'tasks.projection.json')));
+    const tasks = Array.isArray(j.tasks) ? j.tasks : [];
+    const by = (s) => tasks.filter((t) => (t.status || '').toLowerCase() === s).length;
+    return { total: tasks.length, done: by('done') + by('accepted'), active: by('active') + by('in_progress'), review: by('review') + by('ready') };
+  } catch { return null; }
+}
+
+function gatherMemory(root = process.cwd()) {
+  const lessons = parseLessons(readFileSafe(path.join(root, 'atris', 'lessons.md')));
+  const learnings = parseLearnings(readFileSafe(path.join(root, 'atris', 'learnings.jsonl')));
+  const tasks = readTaskCounts(root);
+  return { lessons, learnings, tasks };
+}
+
+function clip(s, n) { s = String(s || ''); return s.length > n ? s.slice(0, n - 1).trimEnd() + '…' : s; }
+function titleize(id) { return String(id || '').replace(/[-_]+/g, ' ').trim(); }
+function plural(n, word) { return `${n} ${word}${n === 1 ? '' : 's'}`; }
+
+function buildMemorySpec(root = process.cwd(), opts = {}) {
+  const theme = opts.theme || 'atris';
+  const brand = { name: opts.brand || 'Atris', accent: '.' };
+  const { lessons, learnings, tasks } = gatherMemory(root);
+  const recent = lessons.slice(-8).reverse(); // newest first
+
+  const slides = [];
+  slides.push({
+    type: 'title',
+    headline: 'What the workspace **learned**',
+    sub: `${plural(lessons.length, 'lesson')} and ${plural(learnings.length, 'note')} compounded into memory${tasks ? `, ${plural(tasks.done, 'task')} done` : ''}.`,
+  });
+  slides.push({ type: 'bignumber', number: String(lessons.length), label: 'lessons compounded into the workspace' });
+
+  if (recent.length) {
+    slides.push({
+      type: 'columns', heading: 'Most recent lessons',
+      columns: recent.slice(0, 3).map((l) => ({ h: titleize(l.id), b: clip(l.text, 150) })),
+    });
+    slides.push({
+      type: 'panel', heading: 'Memory updates', sub: 'Lessons and notes, newest first.',
+      panel: {
+        header: { title: 'Recent updates', meta: `${recent.length} shown` },
+        rows: recent.map((l, i) => ({
+          title: titleize(l.id), sub: l.date,
+          value: l.status || 'note', sev: l.status === 'fail' ? 0 : (l.status === 'pass' ? 2 : 1),
+          active: i === 0,
+        })),
+      },
+    });
+  }
+  if (learnings.length) {
+    slides.push({
+      type: 'columns', heading: 'Notes from the field',
+      columns: learnings.slice(-3).reverse().map((n) => ({ h: titleize(n.key || n.type || 'note'), b: clip(n.insight, 150) })),
+    });
+  }
+  slides.push({ type: 'close', tagline: 'Memory lives in the filesystem, not the model.', footer: `${brand.name} workspace memory` });
+  return { theme, brand, slides };
+}
+
+module.exports = { buildMemorySpec, gatherMemory, parseLessons, parseLearnings, readTaskCounts };

package/lib/next-moves.js

@@ -0,0 +1,362 @@
+'use strict';
+
+// Alive onboarding: the engine behind `atris moves`.
+//
+// It reads the workspace for the highest-leverage next moves (the goal in
+// ROADMAP.md, work already in flight, fresh inbox ideas), ranks them, and lets
+// the human approve, kill, or skip. Approved moves are seeded into today's
+// inbox, which the loop's hasWork() already reads, so onboarding feeds the
+// loop without touching the autonomous core.
+
+const fs = require('fs');
+const path = require('path');
+
+function safeRead(p) {
+  try { return fs.readFileSync(p, 'utf8'); } catch { return ''; }
+}
+
+// Normalize a title for dedup and suppression, the same way moveId does, so a
+// move matches itself across case and whitespace.
+function norm(title) {
+  return String(title == null ? '' : title).trim().toLowerCase();
+}
+
+// Short, stable id so a kill on Tuesday still suppresses the same move on
+// Wednesday. Pure function of (source, title).
+function moveId(source, title) {
+  const s = `${source}:${String(title).trim().toLowerCase()}`;
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return `m_${(h >>> 0).toString(36)}`;
+}
+
+const WEIGHT = { roadmap: 100, task: 60, inbox: 40 };
+
+// One section-boundary shape for every reader and writer: tolerate a header
+// suffix (e.g. "(priority)"), stop at a sibling/parent heading (## or #) or a
+// malformed "##Next", but NOT at a child ### inside the section. Keeping a single
+// definition is the whole point: divergent boundaries are how the gate and the
+// picker drift apart.
+const SECTION_TAIL = '\\b[^\\n]*\\r?\\n([\\s\\S]*?)(?=\\r?\\n##[^#]|\\r?\\n# |$)';
+const OPEN_ITEMS_RE = new RegExp(`##\\s+Open loop items${SECTION_TAIL}`, 'i');
+const INBOX_RE = new RegExp(`##\\s+Inbox${SECTION_TAIL}`, 'i');
+
+// Locate a section's body and its character span, so a writer can splice an edit
+// back into exactly the region a reader parsed.
+function findSection(text, re) {
+  const m = text.match(re);
+  if (!m) return null;
+  const bodyStart = m.index + m[0].length - m[1].length;
+  return { body: m[1], start: bodyStart, end: bodyStart + m[1].length };
+}
+
+// Clean inbox titles out of a journal's ## Inbox section. The one inbox parser,
+// shared by latestInboxItems, todayInboxItems, and the run.js work gate.
+function parseInboxTitles(text) {
+  const m = (text || '').match(INBOX_RE);
+  if (!m) return [];
+  return m[1]
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter((l) => l.startsWith('- ') && l.length > 2)
+    .map((l) => l.replace(/^-\s*\*\*[IC]?\d*:?\*\*\s*/, '').replace(/^-\s*\*\*/, '').replace(/\*\*$/, '').replace(/^-\s*/, '').trim())
+    .filter(Boolean);
+}
+
+function readRoadmapOpenItems(root) {
+  const text = safeRead(path.join(root, 'ROADMAP.md'));
+  if (!text) return [];
+  const section = findSection(text, OPEN_ITEMS_RE);
+  if (!section) return [];
+  return section.body
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter((l) => /^- \[ \]/.test(l))
+    .map((l) => l.replace(/^- \[ \]\s*/, '').trim())
+    .filter(Boolean)
+    .map((title) => ({
+      title,
+      why: 'open item in ROADMAP.md, the goal the loop pursues',
+      source: 'roadmap',
+      weight: WEIGHT.roadmap,
+    }));
+}
+
+function readActiveTasks(root) {
+  const text = safeRead(path.join(root, '.atris', 'state', 'tasks.projection.json'));
+  if (!text) return [];
+  let proj;
+  try { proj = JSON.parse(text); } catch { return []; }
+  const tasks = Array.isArray(proj && proj.tasks) ? proj.tasks : [];
+  return tasks
+    .filter((t) => t && t.title && ['open', 'claimed'].includes(String(t.status || '').toLowerCase()))
+    .map((t) => ({
+      title: String(t.title).trim(),
+      why: `task in flight (${t.status}${t.claimed_by ? `, ${t.claimed_by}` : ''})`,
+      source: 'task',
+      ref: t.display_id || t.id || null,
+      weight: WEIGHT.task,
+    }));
+}
+
+function inboxItemsFrom(text) {
+  return parseInboxTitles(text).map((title) => ({ title, why: 'fresh idea in today\'s inbox', source: 'inbox', weight: WEIGHT.inbox }));
+}
+
+// Most recent journal under atris/logs/YYYY/, parsed for ## Inbox items. Used to
+// SURFACE ideas in `atris moves`.
+function latestInboxItems(root) {
+  const logsDir = path.join(root, 'atris', 'logs');
+  let years;
+  try { years = fs.readdirSync(logsDir).filter((d) => /^\d{4}$/.test(d)).sort(); } catch { return []; }
+  if (!years.length) return [];
+  const yearDir = path.join(logsDir, years[years.length - 1]);
+  let files;
+  try { files = fs.readdirSync(yearDir).filter((f) => /^\d{4}-\d{2}-\d{2}\.md$/.test(f)).sort(); } catch { return []; }
+  if (!files.length) return [];
+  return inboxItemsFrom(safeRead(path.join(yearDir, files[files.length - 1])));
+}
+
+// TODAY's journal inbox only. The loop's work gate and the seed-suppression must
+// read the SAME file the seeder writes (today's), or a prior-day duplicate makes
+// them disagree. Returns [] if today's file is absent.
+function todayInboxItems(root) {
+  const { file } = todayLogFile(root);
+  if (!fs.existsSync(file)) return [];
+  return inboxItemsFrom(safeRead(file));
+}
+
+function gatherCandidates(root = process.cwd()) {
+  return [
+    ...readRoadmapOpenItems(root),
+    ...readActiveTasks(root),
+    ...latestInboxItems(root),
+  ];
+}
+
+// Pure ranking: drop killed/approved, sort by weight, then dedupe by title
+// (keeping the highest-weight copy), take `limit`.
+//
+// Suppression: the exact move the operator acted on is dropped by id. Titles are
+// only suppressed for IDEAS (roadmap/inbox), never for a real `task`, so killing
+// or approving an idea can't hide a genuine in-flight task that happens to share
+// the title.
+function pickNextMoves(candidates, { limit = 3, killedIds = [], killedTitles = [], approvedIds = [], approvedTitles = [] } = {}) {
+  const blockedIds = new Set([...killedIds, ...approvedIds]);
+  const blockedTitles = new Set([...killedTitles, ...approvedTitles].map(norm));
+  const seen = new Set();
+  return candidates
+    .map((c) => ({ ...c, id: moveId(c.source, c.title), _key: norm(c.title) }))
+    .filter((c) => {
+      if (!c._key) return false;
+      if (blockedIds.has(c.id)) return false;
+      if (c.source !== 'task' && blockedTitles.has(c._key)) return false;
+      return true;
+    })
+    .sort((a, b) => (b.weight || 0) - (a.weight || 0))
+    .filter((c) => {
+      if (seen.has(c._key)) return false;
+      seen.add(c._key);
+      return true;
+    })
+    .map(({ _key, ...c }) => c)
+    .slice(0, limit);
+}
+
+const DECISIONS_FILE = ['.atris', 'state', 'moves.decisions.jsonl'];
+
+function decisionsPath(root) {
+  return path.join(root, ...DECISIONS_FILE);
+}
+
+function readDecisions(root = process.cwd()) {
+  const text = safeRead(decisionsPath(root));
+  const rows = text.split(/\r?\n/).map((l) => l.trim()).filter(Boolean)
+    .map((l) => { try { return JSON.parse(l); } catch { return null; } })
+    .filter(Boolean);
+  const idsFor = (decision) => rows.filter((r) => r.decision === decision).map((r) => r.id);
+  const titlesFor = (decision) => rows.filter((r) => r.decision === decision).map((r) => norm(r.title));
+  return {
+    killedIds: idsFor('kill'),
+    killedTitles: titlesFor('kill'),
+    approvedIds: idsFor('approve'),
+    approvedTitles: titlesFor('approve'),
+  };
+}
+
+function recordDecision(root, move, decision, stamp) {
+  const p = decisionsPath(root);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const row = { id: move.id, title: move.title, source: move.source, decision, at: stamp || null };
+  fs.appendFileSync(p, `${JSON.stringify(row)}\n`, 'utf8');
+  return row;
+}
+
+function todayLogFile(root, date = new Date()) {
+  const y = date.getFullYear();
+  const m = String(date.getMonth() + 1).padStart(2, '0');
+  const d = String(date.getDate()).padStart(2, '0');
+  const dateFormatted = `${y}-${m}-${d}`;
+  return { file: path.join(root, 'atris', 'logs', String(y), `${dateFormatted}.md`), dateFormatted };
+}
+
+// The canonical day-journal sections every reader expects (status, analytics,
+// section parsers). Mirrors lib/journal.js createLogFile, minus the em dash in
+// its title, so a journal first created by the idle-seed path is not malformed.
+function canonicalJournal(dateFormatted) {
+  return `# Log ${dateFormatted}\n\n## Handoff\n\n---\n\n## Completed ✅\n\n---\n\n## In Progress 🔄\n\n---\n\n## Backlog\n\n---\n\n## Notes\n\n---\n\n## Inbox\n\n`;
+}
+
+// Seed an approved move into today's inbox so the loop's hasWork() finds it.
+// Idempotent by title: if the same title is already in today's inbox, it is not
+// appended again (so a retry or a concurrent cycle cannot duplicate it).
+function seedInboxFromMove(root, move, date) {
+  const { file, dateFormatted } = todayLogFile(root, date);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  let content = safeRead(file);
+  if (!content) {
+    content = canonicalJournal(dateFormatted);
+  }
+  if (!/##\s+Inbox/i.test(content)) {
+    content = content.replace(/^(#.*\n)/, `$1\n## Inbox\n`);
+    if (!/##\s+Inbox/i.test(content)) content += `\n## Inbox\n`;
+  }
+  const target = norm(move.title);
+  if (parseInboxTitles(content).some((t) => norm(t) === target)) {
+    return { file, line: null, nextId: null, alreadyPresent: true };
+  }
+  const existingIds = (content.match(/-\s*\*\*I(\d+):/g) || []).map((m2) => parseInt(m2.match(/I(\d+)/)[1], 10));
+  const nextId = existingIds.length ? Math.max(...existingIds) + 1 : 1;
+  const line = `- **I${nextId}:** ${move.title}`;
+  // Insert right after the Inbox header line only (do not consume blank lines or
+  // following sections). Use a function replacer so a title containing $ tokens
+  // ($1, $&, $$) is inserted literally, not interpreted as a replacement pattern.
+  content = content.replace(/(##\s+Inbox[^\n]*\r?\n)/i, (m) => `${m}${line}\n`);
+  fs.writeFileSync(file, content, 'utf8');
+  return { file, line, nextId };
+}
+
+// Claim an open ROADMAP item for the loop by flipping its `- [ ]` to `- [~]`
+// (claimed, in flight) WITHIN the "## Open loop items" section only. This is the
+// single source of truth for "the loop took this on": readRoadmapOpenItems only
+// returns `- [ ]`, so a claimed item is excluded, and the work gate and the seed
+// picker stay in agreement. Scoped to the section so a same-titled `- [ ]` in
+// another section (Big jobs, an example block) is never flipped by mistake.
+// `- [~]` is distinct from human `- [x]` (done) so a reader is not misled.
+function claimRoadmapItem(root, title) {
+  const p = path.join(root, 'ROADMAP.md');
+  const text = safeRead(p);
+  if (!text) return false;
+  const section = findSection(text, OPEN_ITEMS_RE);
+  if (!section) return false;
+  const target = norm(title);
+  let changed = false;
+  const newBody = section.body.split(/\r?\n/).map((line) => {
+    if (changed) return line;
+    const m = line.match(/^(\s*)- \[ \]\s*(.+?)\s*$/);
+    if (m && norm(m[2]) === target) {
+      changed = true;
+      return `${m[1]}- [~] ${m[2].trim()}`;
+    }
+    return line;
+  }).join('\n');
+  if (!changed) return false;
+  const out = text.slice(0, section.start) + newBody + text.slice(section.end);
+  fs.writeFileSync(p, out, 'utf8');
+  return true;
+}
+
+// Add one bounded item to the "## Open loop items" section so the loop (and
+// `atris moves`) will pursue it: messy input straight into the working queue,
+// no markdown editing. Creates ROADMAP.md and the section if missing. Dedups
+// against existing OPEN items only (a done/claimed one can be re-added).
+function addRoadmapItem(root, text) {
+  // Collapse any whitespace/newlines to single spaces (a multi-line title would
+  // break the markdown line) and strip a leading bullet/checkbox the user may
+  // have pasted, so the item is exactly one well-formed `- [ ]` line.
+  const title = String(text || '').replace(/\s+/g, ' ').trim().replace(/^- \[[ x~]\]\s*/, '').replace(/^- /, '').trim();
+  if (!title) return { added: false, reason: 'empty', title: null };
+  const p = path.join(root, 'ROADMAP.md');
+  let content = safeRead(p);
+  if (!content) content = '# Roadmap\n\n## Open loop items\n\n';
+  let section = findSection(content, OPEN_ITEMS_RE);
+  if (!section) {
+    if (!content.endsWith('\n')) content += '\n';
+    content += '\n## Open loop items\n\n';
+    section = findSection(content, OPEN_ITEMS_RE);
+  }
+  const openTitles = section.body.split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter((l) => /^- \[ \]/.test(l))
+    .map((l) => norm(l.replace(/^- \[ \]\s*/, '')));
+  if (openTitles.includes(norm(title))) return { added: false, reason: 'already an open item', title };
+  // Insert at the top of the section body so the loop pulls it next.
+  const out = `${content.slice(0, section.start)}\n- [ ] ${title}\n${content.slice(section.start)}`;
+  fs.writeFileSync(p, out, 'utf8');
+  return { added: true, title };
+}
+
+// Group the Open loop items by state: queued `- [ ]`, in-flight `- [~]` (claimed
+// by the loop), done `- [x]`. The evidence for a loop report.
+function roadmapItemsByState(root) {
+  const out = { open: [], claimed: [], done: [] };
+  const text = safeRead(path.join(root, 'ROADMAP.md'));
+  if (!text) return out;
+  const section = findSection(text, OPEN_ITEMS_RE);
+  if (!section) return out;
+  for (const raw of section.body.split(/\r?\n/)) {
+    const l = raw.trim();
+    let m;
+    if ((m = l.match(/^- \[ \]\s*(.+)$/))) out.open.push(m[1].trim());
+    else if ((m = l.match(/^- \[~\]\s*(.+)$/))) out.claimed.push(m[1].trim());
+    else if ((m = l.match(/^- \[x\]\s*(.+)$/))) out.done.push(m[1].trim());
+  }
+  return out;
+}
+
+// The top open ROADMAP item the loop has not already handled. Claimed items are
+// marked `- [~]` (so readRoadmapOpenItems drops them); this also skips anything
+// already in TODAY's inbox or killed/approved, so an idle loop advances to the
+// next item each cycle. todayInboxItems (not latestInboxItems) so the picker, the
+// work gate, and the seeder all read the same file. Root-explicit and pure of
+// cwd, so it is testable without a live runner.
+function pickRoadmapSeed(root = process.cwd()) {
+  const items = readRoadmapOpenItems(root);
+  if (!items.length) return null;
+  const inbox = todayInboxItems(root).map((i) => norm(i.title));
+  const { killedTitles, approvedTitles } = readDecisions(root);
+  const blocked = new Set([...inbox, ...killedTitles, ...approvedTitles]);
+  return items.find((it) => !blocked.has(norm(it.title))) || null;
+}
+
+// Shared "3 next moves" recipe used by both `atris moves` and `atris activate`,
+// so the ranking inputs live in one place.
+function nextMoves(root = process.cwd(), limit = 3) {
+  const { killedIds, killedTitles, approvedIds, approvedTitles } = readDecisions(root);
+  return pickNextMoves(gatherCandidates(root), { limit, killedIds, killedTitles, approvedIds, approvedTitles });
+}
+
+module.exports = {
+  moveId,
+  norm,
+  WEIGHT,
+  parseInboxTitles,
+  readRoadmapOpenItems,
+  readActiveTasks,
+  latestInboxItems,
+  todayInboxItems,
+  gatherCandidates,
+  pickNextMoves,
+  nextMoves,
+  readDecisions,
+  recordDecision,
+  seedInboxFromMove,
+  pickRoadmapSeed,
+  claimRoadmapItem,
+  addRoadmapItem,
+  roadmapItemsByState,
+  todayLogFile,
+};

package/lib/reel.js

@@ -0,0 +1,52 @@
+// atris reel — a card, animated. A reel is the card from lib/card.js rendered at
+// progress t in [0,1]: each element fades and rises in on a staggered schedule.
+// Pure: (spec, t) -> HTML for that single frame. commands/reel.js screenshots the
+// frames (same Chrome as card) and ffmpeg-encodes them. No new dependency.
+
+const { buildCard } = require('./card');
+
+const clamp01 = (x) => Math.max(0, Math.min(1, x));
+const easeOutCubic = (p) => 1 - Math.pow(1 - clamp01(p), 3);
+// reveal progress of an element whose window is [a,b], at global time t
+const win = (t, a, b) => easeOutCubic((t - a) / (b - a));
+
+// staggered reveal windows by element class. A kind only has some of these;
+// overriding a class that isn't present is harmless.
+const STAGGER = [
+  ['.rule', 0.00, 0.16],
+  ['.kicker', 0.10, 0.30],
+  ['.qmark', 0.10, 0.30],
+  ['.headline', 0.18, 0.46],
+  ['.qtext', 0.20, 0.50],
+  ['.big', 0.16, 0.46],
+  ['.statlabel', 0.34, 0.58],
+  ['.sub', 0.40, 0.62],
+  ['.by', 0.46, 0.66],
+  ['.foot', 0.58, 0.80],
+];
+
+// CSS that places every element at its reveal state for time t (one-shot, no loops)
+function revealCss(t, dist = 16) {
+  const tt = clamp01(t);
+  let css = '';
+  for (const [sel, a, b] of STAGGER) {
+    const p = win(tt, a, b);
+    css += `${sel}{opacity:${p.toFixed(3)};transform:translateY(${((1 - p) * dist).toFixed(2)}px)}`;
+  }
+  return css;
+}
+
+// HTML for a single reel frame at time t. Reuses the card, appends the reveal styles.
+function buildReelFrame(spec, t, opts = {}) {
+  const card = buildCard(spec, opts);
+  const overrides = `<style id="reel">${revealCss(t)}</style>`;
+  return { html: card.html.replace('</head>', `${overrides}</head>`), width: card.width, height: card.height };
+}
+
+// the list of t values for a reel of `seconds` at `fps` (>=2 frames)
+function reelFrames(seconds = 2.6, fps = 20) {
+  const n = Math.max(2, Math.round(seconds * fps));
+  return Array.from({ length: n }, (_, i) => i / (n - 1));
+}
+
+module.exports = { buildReelFrame, revealCss, reelFrames, win, STAGGER };

package/lib/site.js

@@ -0,0 +1,114 @@
+// Static site generator — point it at a folder of markdown (docs, your wiki,
+// memory) and get a beautiful, navigable HTML site in the design system.
+// Builds on lib/deck-from-md (parse) + lib/html-render (render).
+//
+// buildSite(input, opts) -> { outDir, indexPath, pages }. Pure file I/O.
+
+const fs = require('fs');
+const path = require('path');
+const http = require('http');
+const { parseMarkdownToSpec } = require('./deck-from-md');
+const { renderHtml, THEMES: BUILTIN } = require('./html-render');
+const { mergedThemes } = require('./theme');
+
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'out', 'coverage', '.cache']);
+const MD_EXTS = new Set(['.md', '.mdx']);
+
+function collectMd(input) {
+  const stat = fs.statSync(input);
+  if (stat.isFile()) return MD_EXTS.has(path.extname(input)) ? [input] : [];
+  const out = [];
+  (function walk(dir) {
+    for (const name of fs.readdirSync(dir).sort()) {
+      if (name.startsWith('.')) continue;
+      const full = path.join(dir, name);
+      let st; try { st = fs.statSync(full); } catch { continue; }
+      if (st.isDirectory()) { if (!SKIP_DIRS.has(name)) walk(full); }
+      else if (MD_EXTS.has(path.extname(name))) out.push(full);
+    }
+  })(input);
+  return out;
+}
+
+function slugFor(file, root) {
+  // base = the dir the site was built from (root may be a dir or a single .md file)
+  const base = MD_EXTS.has(path.extname(root)) ? path.dirname(root) : root;
+  const rel = path.relative(base, file).replace(/\.[^.]+$/, '');
+  return rel.replace(/[\\/]+/g, '-').replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '').toLowerCase() || 'page';
+}
+
+function firstHeading(md) {
+  const m = md.match(/^#{1,2}\s+(.+)$/m);
+  return m ? m[1].replace(/\*\*/g, '').trim() : null;
+}
+function firstParagraph(md) {
+  const body = md.replace(/^---\n[\s\S]*?\n---\n/, '');
+  for (const line of body.split('\n')) {
+    const t = line.trim();
+    if (!t || /^[#<>]/.test(t) || /^[-*+]/.test(t) || /^\|/.test(t) || /^```/.test(t)) continue;
+    return t.replace(/\*\*/g, '');
+  }
+  return '';
+}
+function clip(s, n) { s = String(s || ''); return s.length > n ? s.slice(0, n - 1).trimEnd() + '…' : s; }
+function titleFromSlug(slug) { return slug.replace(/[-_]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase()); }
+
+function buildSite(input, opts = {}) {
+  const THEMES = mergedThemes(BUILTIN, opts.root || process.cwd());
+  const theme = THEMES[opts.theme] ? opts.theme : 'atris';
+  const siteTitle = opts.title || 'Atris';
+  const accent = opts.accent || '.';
+  const outDir = opts.out || 'dist';
+  const files = collectMd(input);
+  fs.mkdirSync(outDir, { recursive: true });
+  const nav = { home: 'index.html', label: siteTitle, accent };
+
+  const pages = [];
+  const seen = new Set();
+  for (const file of files) {
+    const md = fs.readFileSync(file, 'utf8');
+    const spec = parseMarkdownToSpec(md, { theme });
+    if (!THEMES[spec.theme]) spec.theme = theme;
+    let slug = slugFor(file, input);
+    while (seen.has(slug)) slug += '-1';
+    seen.add(slug);
+    const title = firstHeading(md) || titleFromSlug(slug);
+    const summary = firstParagraph(md);
+    const outFile = path.join(outDir, slug + '.html');
+    fs.writeFileSync(outFile, renderHtml(spec, { title, nav, themes: THEMES }));
+    pages.push({ src: file, out: outFile, href: slug + '.html', title, summary });
+  }
+
+  const indexSpec = {
+    theme, brand: { name: siteTitle, accent },
+    slides: [
+      { type: 'title', headline: opts.headline || `${siteTitle} **docs**`, sub: opts.sub || `${pages.length} page${pages.length === 1 ? '' : 's'}, one design system.` },
+      { type: 'toc', heading: 'Pages', items: pages.map((p) => ({ href: p.href, title: p.title, summary: clip(p.summary, 120) })) },
+      { type: 'close', tagline: opts.tagline || 'One workspace, one design system.', footer: siteTitle },
+    ],
+  };
+  const indexPath = path.join(outDir, 'index.html');
+  fs.writeFileSync(indexPath, renderHtml(indexSpec, { title: siteTitle, themes: THEMES }));
+  return { outDir, indexPath, pages };
+}
+
+const MIME = { '.html': 'text/html; charset=utf-8', '.css': 'text/css', '.js': 'text/javascript', '.json': 'application/json', '.png': 'image/png', '.jpg': 'image/jpeg', '.svg': 'image/svg+xml' };
+
+// minimal static preview server for a built site dir (no deps)
+function serveSite(dir, port = 4321) {
+  const root = path.resolve(dir);
+  const server = http.createServer((req, res) => {
+    let rel = decodeURIComponent((req.url || '/').split('?')[0]);
+    if (rel.endsWith('/')) rel += 'index.html';
+    const file = path.normalize(path.join(root, rel));
+    if (!file.startsWith(root)) { res.writeHead(403); res.end('forbidden'); return; }
+    fs.readFile(file, (err, data) => {
+      if (err) { res.writeHead(404, { 'Content-Type': 'text/plain' }); res.end('not found'); return; }
+      res.writeHead(200, { 'Content-Type': MIME[path.extname(file)] || 'application/octet-stream' });
+      res.end(data);
+    });
+  });
+  return new Promise((resolve) => server.listen(port, () => resolve({ server, url: `http://localhost:${port}` })));
+}
+
+module.exports = { buildSite, serveSite, collectMd, slugFor, firstHeading, firstParagraph };