ngvoicu/kluris / vendored/specmint-core-html
specmint-core-html
VerifiedPersistent spec management for AI coding workflows, producing rich HTML SPEC.html files. Use this skill when the user explicitly mentions specs, forging, or structured planning: says "forge", "forge a spec", "write a spec for X", "create a spec", "plan X as a spec", "resume", "what was I working on", "spec list/status/pause/switch/activate", "implement the spec", "implement phase N", "implement all phases", "generate openapi", or exits plan mode (offer to save as a spec). Also trigger when a `.specs/` directory exists at session start. Do NOT trigger on general feature requests, coding tasks, or questions that don't mention specs or forging.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 41.5 KB |
| assets/spec-runtime.js | script | 34.7 KB |
| assets/spec-styles.css | other | 50.5 KB |
| references/command-contracts.md | markdown | 5.8 KB |
| references/edit-recipes.md | markdown | 12.5 KB |
| references/html-template.html | other | 10.2 KB |
| references/mockup-library.md | markdown | 9.8 KB |
| references/researcher.md | markdown | 11.4 KB |
| references/spec-format.md | markdown | 11.8 KB |
| references/validate.md | markdown | 5.7 KB |
| references/wireframe-library.md | markdown | 9.4 KB |
assets/spec-runtime.js
View on GitHub/*
* spec-runtime.js — single shared runtime for every SPEC.html in this project.
*
* Lives at .specs/assets/spec-runtime.js. Each SPEC.html loads it via:
* <script src="../assets/spec-runtime.js" defer></script>
*
* Functions (called from init() in this order):
* deriveProgress() — Walks [data-task] and [data-phase], counts
* completed vs total, writes derived strings into
* every [data-progress-target] element. Re-runs
* on any data-status mutation.
* mountMermaid() — Loads Mermaid v11 ESM from jsDelivr only when
* at least one <pre class="mermaid"> exists.
* mountDiffs() — Parses every figure.code-diff into a row-based
* GitHub-style grid ([line# | sign | code]) and
* loads PrismJS core + autoloader (no diff-highlight
* plugin) to syntax-highlight the stripped code.
* mountAnnotationArrows() — For each .wf-annotation[data-points-to], draws
* an SVG line from the annotation to the referenced
* element. Redraws on resize (debounced 100ms).
* mountCopyButtons() — Click handler for [data-copy-section] buttons
* that copies the section's text to the clipboard.
* mountTocActiveSection() — Highlights the current section in a left-rail
* [data-toc] using IntersectionObserver.
* validate() — Dev-mode only (localStorage.specmintDebug = "1").
* Confirms #spec-meta JSON parses and every
* <!-- region:X --> has a matching endregion.
*
* Source of truth split:
* - <script id="spec-meta"> JSON — slow-moving identity (id, title, dates)
* - data-status / data-current / data-tdd-phase — lifecycle state
* - All progress strings — DERIVED, never authored
*
* One data-status swap is the only edit needed to update every progress display.
*/
(function () {
'use strict';
// ---------------------------------------------------------------------------
// deriveProgress
// ---------------------------------------------------------------------------
function deriveProgress() {
const tasks = document.querySelectorAll('[data-task][data-status]');
const phases = document.querySelectorAll('[data-phase][data-status]');
const ac = document.querySelectorAll('[data-ac][data-status]');
const counts = {
spec: { done: 0, total: 0 },
phases: { done: 0, total: phases.length },
ac: { done: 0, total: ac.length },
blockers: 0,
perPhase: {},
};
tasks.forEach((el) => {
counts.spec.total++;
const status = el.getAttribute('data-status');
if (status === 'completed') counts.spec.done++;
if (status === 'blocked') counts.blockers++;
const phase = el.closest('[data-phase]');
if (phase) {
const id = phase.getAttribute('data-phase');
counts.perPhase[id] ||= { done: 0, total: 0 };
counts.perPhase[id].total++;
if (status === 'completed') counts.perPhase[id].done++;
}
});
phases.forEach((el) => {
if (el.getAttribute('data-status') === 'completed') counts.phases.done++;
});
ac.forEach((el) => {
if (el.getAttribute('data-status') === 'completed') counts.ac.done++;
});
const pct = (d, t) => (t === 0 ? 0 : Math.round((d / t) * 100));
const values = {
'spec-done': counts.spec.done,
'spec-tasks-total': counts.spec.total,
'spec-total': `${counts.spec.done}/${counts.spec.total}`,
'spec-pct': `${pct(counts.spec.done, counts.spec.total)}%`,
'phases-done': counts.phases.done,
'phases-total': counts.phases.total,
'ac-done': counts.ac.done,
'ac-total': counts.ac.total,
'ac-pct': `${pct(counts.ac.done, counts.ac.total)}%`,
blockers: counts.blockers,
};
Object.entries(counts.perPhase).forEach(([id, { done, total }]) => {
values[`phase-${id}-done`] = done;
values[`phase-${id}-total`] = `${done}/${total}`;
values[`phase-${id}-pct`] = `${pct(done, total)}%`;
});
document.querySelectorAll('[data-progress-target]').forEach((el) => {
const key = el.getAttribute('data-progress-target');
if (key in values) el.textContent = String(values[key]);
});
document.querySelectorAll('[data-progress-bar]').forEach((bar) => {
const key = bar.getAttribute('data-progress-bar');
const m = key.match(/^(spec|ac|phase-(.+))$/);
if (!m) return;
let done, total;
if (m[1] === 'spec') { done = counts.spec.done; total = counts.spec.total; }
else if (m[1] === 'ac') { done = counts.ac.done; total = counts.ac.total; }
else { ({ done = 0, total = 0 } = counts.perPhase[m[2]] || {}); }
bar.style.setProperty('--progress', total === 0 ? '0%' : `${(done / total) * 100}%`);
});
// Auto-inject a progress bar into each .scorecard__cell based on the
// data-progress-target it contains. Detection is purely DOM-driven — no
// SKILL.md change required for existing specs to upgrade.
const cellRules = [
{ needles: ['spec-done', 'spec-tasks-total', 'spec-total'], done: counts.spec.done, total: counts.spec.total },
{ needles: ['phases-done', 'phases-total'], done: counts.phases.done, total: counts.phases.total },
{ needles: ['ac-done', 'ac-total'], done: counts.ac.done, total: counts.ac.total },
];
document.querySelectorAll('.scorecard__cell').forEach((cell) => {
const keys = Array.from(cell.querySelectorAll('[data-progress-target]'))
.map((el) => el.getAttribute('data-progress-target'));
const rule = cellRules.find((r) => r.needles.some((n) => keys.includes(n)));
if (!rule) return;
let bar = cell.querySelector(':scope > .scorecard__bar');
if (!bar) {
bar = document.createElement('div');
bar.className = 'scorecard__bar';
cell.appendChild(bar);
}
const pctNum = rule.total === 0 ? 0 : (rule.done / rule.total) * 100;
bar.style.setProperty('--progress', `${pctNum}%`);
if (rule.total === 0) cell.setAttribute('data-progress', 'empty');
else if (rule.done >= rule.total) cell.setAttribute('data-progress', 'complete');
else cell.setAttribute('data-progress', 'partial');
});
// Per-phase header progress strip — set --progress on each <details class="phase" data-phase>.
document.querySelectorAll('.phase[data-phase]').forEach((phase) => {
const id = phase.getAttribute('data-phase');
const { done = 0, total = 0 } = counts.perPhase[id] || {};
phase.style.setProperty('--progress', total === 0 ? '0%' : `${(done / total) * 100}%`);
});
}
// ---------------------------------------------------------------------------
// mountMermaid
// ---------------------------------------------------------------------------
async function mountMermaid() {
const nodes = document.querySelectorAll('pre.mermaid');
if (!nodes.length) return;
// Stash original Mermaid source on each node BEFORE render — Mermaid v11
// replaces the pre's content with the rendered SVG, so the source is
// otherwise lost (and the validator can't re-parse it later).
nodes.forEach((n) => {
if (!n.hasAttribute('data-mermaid-source')) {
n.setAttribute('data-mermaid-source', n.textContent || '');
}
});
let mermaid;
try {
const mod = await import('https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs');
mod.default.initialize({
startOnLoad: false,
theme: 'base',
securityLevel: 'loose',
themeVariables: {
background: '#FFFFFF',
primaryColor: '#FFFFFF',
primaryBorderColor: '#D0D7DE',
primaryTextColor: '#1F2328',
secondaryColor: '#F6F8FA',
tertiaryColor: '#DDE7FF',
lineColor: '#656D76',
textColor: '#1F2328',
actorBkg: '#F6F8FA',
actorBorder: '#AFB8C1',
actorTextColor: '#1F2328',
actorLineColor: '#D0D7DE',
signalColor: '#0535C1',
signalTextColor: '#1F2328',
labelBoxBkgColor: '#DDE7FF',
labelBoxBorderColor: '#0535C1',
labelTextColor: '#0535C1',
loopTextColor: '#656D76',
noteBkgColor: '#FFF8C5',
noteBorderColor: '#9A6700',
noteTextColor: '#1F2328',
activationBkgColor: '#DDE7FF',
activationBorderColor: '#0535C1',
attributeBackgroundColorOdd: '#FFFFFF',
attributeBackgroundColorEven: '#F6F8FA',
mainBkg: '#FFFFFF',
nodeBorder: '#AFB8C1',
nodeTextColor: '#1F2328',
clusterBkg: '#F6F8FA',
clusterBorder: '#D0D7DE',
edgeLabelBackground: '#FFFFFF',
fontFamily: '-apple-system, BlinkMacSystemFont, "Inter", "Segoe UI", Roboto, sans-serif',
fontSize: '13px',
},
});
mermaid = mod.default;
window.__specmintMermaid = mermaid;
} catch (e) {
console.warn('[specmint] Mermaid library failed to load — diagram source remains readable as text.', e);
return;
}
// Render each diagram in its own try/catch so one bad block doesn't
// abort the rest (or skip mountDiagramModal). Mermaid's run() mutates
// nodes in place and replaces content with the SVG (or an error svg).
for (const node of nodes) {
try {
await mermaid.run({ nodes: [node] });
} catch (e) {
const fig = node.closest('figure.diagram');
const label = fig && fig.querySelector('.diagram__label');
const tag = label ? `"${label.textContent.trim()}"` : '(unlabeled)';
console.warn(`[specmint] Mermaid parse error in diagram ${tag} — source preserved on data-mermaid-source. Page continues.`, e);
if (fig) fig.classList.add('diagram--error');
}
}
mountDiagramModal();
}
// ---------------------------------------------------------------------------
// mountDiagramModal — click a figure.diagram to open it in a fullscreen
// dialog with wheel-zoom + click-drag pan. Called from mountMermaid after
// SVGs exist; if there are no diagrams it is a no-op.
// ---------------------------------------------------------------------------
function mountDiagramModal() {
const diagrams = document.querySelectorAll('figure.diagram');
if (!diagrams.length) return;
const dialog = document.createElement('dialog');
dialog.className = 'diagram-modal';
dialog.innerHTML =
'<button type="button" class="diagram-modal__close" aria-label="Close (Esc)">×</button>' +
'<div class="diagram-modal__hint">Wheel = zoom · Drag = pan · Double-click = reset · Esc = close</div>' +
'<div class="diagram-modal__viewport"><div class="diagram-modal__pan"></div></div>';
document.body.appendChild(dialog);
const viewport = dialog.querySelector('.diagram-modal__viewport');
const pan = dialog.querySelector('.diagram-modal__pan');
const closeBtn = dialog.querySelector('.diagram-modal__close');
let scale = 1, tx = 0, ty = 0;
let dragging = false, startX = 0, startY = 0, startTx = 0, startTy = 0;
function applyTransform() {
pan.style.transform = `translate(${tx}px, ${ty}px) scale(${scale})`;
}
function fit() { scale = 1; tx = 0; ty = 0; applyTransform(); }
diagrams.forEach((fig) => {
fig.addEventListener('click', () => {
const svg = fig.querySelector('svg');
if (!svg) return;
const clone = svg.cloneNode(true);
clone.removeAttribute('width');
clone.removeAttribute('height');
clone.removeAttribute('style');
clone.style.width = '100%';
clone.style.height = '100%';
pan.replaceChildren(clone);
fit();
dialog.showModal();
});
});
closeBtn.addEventListener('click', () => dialog.close());
dialog.addEventListener('click', (e) => { if (e.target === dialog) dialog.close(); });
dialog.addEventListener('close', () => pan.replaceChildren());
viewport.addEventListener('wheel', (e) => {
e.preventDefault();
const rect = viewport.getBoundingClientRect();
const px = e.clientX - rect.left;
const py = e.clientY - rect.top;
const factor = Math.pow(1.15, -Math.sign(e.deltaY));
const newScale = Math.max(0.2, Math.min(10, scale * factor));
tx = px - (px - tx) * (newScale / scale);
ty = py - (py - ty) * (newScale / scale);
scale = newScale;
applyTransform();
}, { passive: false });
viewport.addEventListener('pointerdown', (e) => {
dragging = true;
startX = e.clientX; startY = e.clientY;
startTx = tx; startTy = ty;
viewport.setPointerCapture(e.pointerId);
});
viewport.addEventListener('pointermove', (e) => {
if (!dragging) return;
tx = startTx + (e.clientX - startX);
ty = startTy + (e.clientY - startY);
applyTransform();
});
viewport.addEventListener('pointerup', (e) => {
dragging = false;
if (viewport.hasPointerCapture(e.pointerId)) viewport.releasePointerCapture(e.pointerId);
});
viewport.addEventListener('dblclick', fit);
}
// ---------------------------------------------------------------------------
// mountDiffs — GitHub-style code-diff renderer.
// ---------------------------------------------------------------------------
// The AI emits `<figure class="code-diff"><pre class="language-diff-LANG
// diff-highlight"><code>+ line\n context\n- line</code></pre></figure>`.
// Instead of letting PrismJS's diff-highlight plugin tokenize the prefix
// chars inline, we parse the raw text ourselves and rebuild the DOM as a
// table-like grid: each line becomes a row of [line# | sign | code], with
// the code column highlighted by Prism using only the base language grammar
// (no diff- prefix). Net result: a real left gutter, no phantom 2-space
// indent on context lines, and full row backgrounds for added/removed.
function mountDiffs() {
const figures = document.querySelectorAll('figure.code-diff');
if (figures.length === 0) return;
const blocks = [];
const langs = new Set();
figures.forEach((fig) => {
const pre = fig.querySelector('pre');
if (!pre) return;
const view = fig.getAttribute('data-view') || 'unified';
// Resolve language: data-language wins, otherwise pull out of
// `language-diff-LANG` class hook.
let lang = (fig.getAttribute('data-language') || '').toLowerCase();
if (!lang) {
const m = Array.from(pre.classList)
.map((c) => c.match(/^language-diff-(.+)$/))
.find(Boolean);
if (m) lang = m[1].toLowerCase();
}
lang = lang.replace(/[^a-z0-9+#-]/g, '') || 'plaintext';
// Snapshot the raw diff source from <code> (or bare <pre>) before
// we rewrite the DOM. Preserve it on data-diff-source for the
// validator + manual inspection.
const codeEl = pre.querySelector(':scope > code');
const raw = codeEl ? codeEl.textContent : pre.textContent;
pre.setAttribute('data-diff-source', raw);
pre.setAttribute('data-language', lang);
pre.setAttribute('data-view', view);
// Language chip in the figcaption / meta slot.
if (lang !== 'plaintext') {
const meta = fig.querySelector('.code-diff__meta') || fig.querySelector('figcaption');
if (meta && !meta.querySelector(':scope > .code-diff__lang')) {
const chip = document.createElement('span');
chip.className = 'code-diff__lang';
chip.textContent = lang;
meta.prepend(chip);
}
}
langs.add(lang);
blocks.push({ fig, pre, raw, lang, view });
});
if (blocks.length === 0) return;
const renderAll = () => blocks.forEach(renderDiffBlock);
const needsPrism = blocks.some((b) => b.lang !== 'plaintext');
if (!needsPrism) { renderAll(); return; }
// PrismJS core + autoloader only (no diff-highlight plugin — we tokenize
// diffs ourselves and only ask Prism to highlight the stripped code).
const themeLink = document.createElement('link');
themeLink.rel = 'stylesheet';
themeLink.href = 'https://cdn.jsdelivr.net/npm/prismjs@1/themes/prism.min.css';
document.head.appendChild(themeLink);
const jsSrcs = [
'https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-core.min.js',
'https://cdn.jsdelivr.net/npm/prismjs@1/plugins/autoloader/prism-autoloader.min.js',
];
let i = 0;
const loadNext = () => {
if (i >= jsSrcs.length) {
const al = window.Prism && window.Prism.plugins && window.Prism.plugins.autoloader;
if (al) {
al.languages_path = 'https://cdn.jsdelivr.net/npm/prismjs@1/components/';
al.loadLanguages(Array.from(langs), renderAll, () => renderAll());
} else {
renderAll();
}
return;
}
const s = document.createElement('script');
s.src = jsSrcs[i++];
s.onload = loadNext;
s.onerror = () => {
console.warn('[specmint] PrismJS failed to load — diffs render as plain text.');
renderAll();
};
document.head.appendChild(s);
};
loadNext();
}
function parseDiffLines(raw) {
const lines = raw.replace(/\n$/, '').split('\n');
let oldNum = 1, newNum = 1;
return lines.map((line) => {
let type, content;
const head = line[0];
if (head === '+') {
type = 'added';
content = line.length > 1 && line[1] === ' ' ? line.slice(2) : line.slice(1);
} else if (head === '-') {
type = 'removed';
content = line.length > 1 && line[1] === ' ' ? line.slice(2) : line.slice(1);
} else if (head === ' ') {
type = 'context';
content = line.length > 1 && line[1] === ' ' ? line.slice(2) : line.slice(1);
} else if (line === '') {
type = 'context'; content = '';
} else {
type = 'context'; content = line;
}
const rec = { type, content, oldNum: null, newNum: null };
if (type === 'added') rec.newNum = newNum++;
else if (type === 'removed') rec.oldNum = oldNum++;
else { rec.oldNum = oldNum++; rec.newNum = newNum++; }
return rec;
});
}
function buildDiffCell(rec, lang) {
const cell = document.createElement('div');
cell.className = `diff-cell diff-cell--${rec.type}`;
const numEl = document.createElement('span');
numEl.className = 'diff-num';
numEl.textContent = String(rec.type === 'added' ? rec.newNum : rec.oldNum);
numEl.setAttribute('aria-hidden', 'true');
const signEl = document.createElement('span');
signEl.className = 'diff-sign';
signEl.textContent = rec.type === 'added' ? '+' : rec.type === 'removed' ? '-' : ' ';
signEl.setAttribute('aria-hidden', 'true');
const codeEl = document.createElement('span');
codeEl.className = 'diff-code';
const grammar = window.Prism && window.Prism.languages && window.Prism.languages[lang];
if (grammar) {
try {
codeEl.innerHTML = window.Prism.highlight(rec.content, grammar, lang);
} catch (e) {
codeEl.textContent = rec.content;
}
} else {
codeEl.textContent = rec.content;
}
cell.append(numEl, signEl, codeEl);
return cell;
}
function buildEmptyCell(side) {
const cell = document.createElement('div');
cell.className = `diff-cell diff-cell--empty diff-cell--empty-${side}`;
cell.setAttribute('aria-hidden', 'true');
return cell;
}
function renderDiffBlock(block) {
const { pre, raw, lang, view } = block;
const records = parseDiffLines(raw);
const container = document.createElement('div');
container.className = `diff-rows diff-rows--${view}`;
if (view === 'split') {
// Group consecutive removed+added into "change hunks" so we can pair
// them left/right with empty placeholders for unequal counts. Context
// lines flush any pending hunk and render as a full-width row.
const runs = [];
let change = null;
const flush = () => { if (change) { runs.push(change); change = null; } };
for (const rec of records) {
if (rec.type === 'context') {
flush();
runs.push({ kind: 'context', record: rec });
} else {
if (!change) change = { kind: 'change', removed: [], added: [] };
(rec.type === 'removed' ? change.removed : change.added).push(rec);
}
}
flush();
runs.forEach((run) => {
if (run.kind === 'context') {
const pair = document.createElement('div');
pair.className = 'diff-pair diff-pair--context';
pair.appendChild(buildDiffCell(run.record, lang));
container.appendChild(pair);
return;
}
const max = Math.max(run.removed.length, run.added.length);
for (let i = 0; i < max; i++) {
const pair = document.createElement('div');
pair.className = 'diff-pair diff-pair--change';
pair.appendChild(run.removed[i] ? buildDiffCell(run.removed[i], lang) : buildEmptyCell('removed'));
pair.appendChild(run.added[i] ? buildDiffCell(run.added[i], lang) : buildEmptyCell('added'));
container.appendChild(pair);
}
});
} else {
// Unified — one cell per record, single column.
records.forEach((rec) => container.appendChild(buildDiffCell(rec, lang)));
}
// Replace the pre's content with the row container. Strip language-diff-*
// and diff-highlight classes so any leftover Prism logic skips this <pre>.
pre.innerHTML = '';
Array.from(pre.classList)
.filter((c) => c.startsWith('language-') || c === 'diff-highlight')
.forEach((c) => pre.classList.remove(c));
pre.classList.add('diff-rendered');
pre.appendChild(container);
}
// ---------------------------------------------------------------------------
// mountAnnotationArrows
// ---------------------------------------------------------------------------
function mountAnnotationArrows() {
const frames = document.querySelectorAll('.wf-frame');
if (frames.length === 0) return;
const draw = () => {
frames.forEach((frame) => {
let svg = frame.querySelector('svg.wf-arrow-overlay');
if (!svg) {
svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
svg.classList.add('wf-arrow-overlay');
svg.setAttribute('aria-hidden', 'true');
frame.appendChild(svg);
}
const frameRect = frame.getBoundingClientRect();
svg.setAttribute('viewBox', `0 0 ${frameRect.width} ${frameRect.height}`);
svg.setAttribute('width', frameRect.width);
svg.setAttribute('height', frameRect.height);
svg.innerHTML = '';
frame.querySelectorAll('.wf-annotation[data-points-to]').forEach((note) => {
const targetId = note.getAttribute('data-points-to');
const target = frame.querySelector(`#${CSS.escape(targetId)}`);
if (!target) return;
const noteRect = note.getBoundingClientRect();
const targetRect = target.getBoundingClientRect();
const x1 = noteRect.left + noteRect.width / 2 - frameRect.left;
const y1 = noteRect.top + noteRect.height / 2 - frameRect.top;
const x2 = targetRect.left + targetRect.width / 2 - frameRect.left;
const y2 = targetRect.top + targetRect.height / 2 - frameRect.top;
const line = document.createElementNS('http://www.w3.org/2000/svg', 'path');
const dx = (x2 - x1) * 0.3;
line.setAttribute('d', `M ${x1} ${y1} C ${x1 + dx} ${y1}, ${x2 - dx} ${y2}, ${x2} ${y2}`);
line.setAttribute('class', 'wf-arrow-path');
svg.appendChild(line);
});
});
};
draw();
let timer;
window.addEventListener('resize', () => {
clearTimeout(timer);
timer = setTimeout(draw, 100);
});
}
// ---------------------------------------------------------------------------
// mountCopyButtons
// ---------------------------------------------------------------------------
function mountCopyButtons() {
document.querySelectorAll('[data-copy-section]').forEach((btn) => {
btn.addEventListener('click', async () => {
const targetSel = btn.getAttribute('data-copy-section');
const target = document.querySelector(targetSel);
if (!target) return;
try {
await navigator.clipboard.writeText(target.innerText.trim());
const original = btn.textContent;
btn.textContent = 'Copied';
setTimeout(() => { btn.textContent = original; }, 1200);
} catch (e) {
console.warn('[specmint] Copy failed:', e);
}
});
});
}
// ---------------------------------------------------------------------------
// mountTocActiveSection
// ---------------------------------------------------------------------------
function mountTocActiveSection() {
const toc = document.querySelector('[data-toc]');
if (!toc) return;
const sections = document.querySelectorAll('section[id], article[id]');
if (sections.length === 0) return;
const links = new Map();
toc.querySelectorAll('a[href^="#"]').forEach((a) => links.set(a.getAttribute('href').slice(1), a));
const observer = new IntersectionObserver((entries) => {
entries.forEach((entry) => {
const link = links.get(entry.target.id);
if (!link) return;
if (entry.isIntersecting) {
links.forEach((l) => l.classList.remove('is-active'));
link.classList.add('is-active');
}
});
}, { rootMargin: '-40% 0px -55% 0px' });
sections.forEach((s) => observer.observe(s));
}
// ---------------------------------------------------------------------------
// validate — full spec validator. Returns an array of {area, level, msg}.
// - Auto-runs after init; logs only when issues exist.
// - Manual invocation: call window.specmintValidate() — always logs.
// - Verbose dev mode: localStorage.specmintDebug = "1" forces a summary
// even when the spec is clean.
// ---------------------------------------------------------------------------
async function validate({ alwaysLog = false } = {}) {
const issues = [];
const debug = (typeof localStorage !== 'undefined' && localStorage.getItem('specmintDebug') === '1');
// 1. JSON metadata
const meta = document.getElementById('spec-meta');
if (!meta) {
issues.push({ area: 'meta', level: 'error', msg: '#spec-meta script missing from <head>' });
} else {
try {
const obj = JSON.parse(meta.textContent);
['id', 'title', 'status', 'created', 'updated'].forEach((k) => {
if (!(k in obj)) issues.push({ area: 'meta', level: 'error', msg: `Required field "${k}" missing from spec-meta JSON` });
});
} catch (e) {
issues.push({ area: 'meta', level: 'error', msg: `spec-meta JSON parse error: ${e.message}` });
}
}
// 2. Region / endregion pairing
const htmlText = document.documentElement.outerHTML;
const opens = (htmlText.match(/<!--\s*region:([\w-]+)\s*-->/g) || []).map((s) => s.match(/region:([\w-]+)/)[1]);
const closes = (htmlText.match(/<!--\s*endregion:([\w-]+)\s*-->/g) || []).map((s) => s.match(/endregion:([\w-]+)/)[1]);
const oSorted = [...opens].sort().join('|');
const cSorted = [...closes].sort().join('|');
if (oSorted !== cSorted) {
const onlyOpens = opens.filter((n) => !closes.includes(n));
const onlyCloses = closes.filter((n) => !opens.includes(n));
issues.push({
area: 'regions',
level: 'error',
msg: `region/endregion mismatch — unclosed: [${onlyOpens.join(', ') || 'none'}] orphan close: [${onlyCloses.join(', ') || 'none'}]`,
});
}
// 3. Task code uniqueness
const taskCodes = Array.from(document.querySelectorAll('[data-task]')).map((el) => el.getAttribute('data-task'));
const counts = Object.create(null);
taskCodes.forEach((c) => { counts[c] = (counts[c] || 0) + 1; });
const dupCodes = Object.keys(counts).filter((c) => counts[c] > 1);
if (dupCodes.length) {
issues.push({ area: 'tasks', level: 'error', msg: `Duplicate task code(s): ${dupCodes.join(', ')}` });
}
// 4. Required regions present (warn only — some are optional)
const required = ['meta', 'header', 'overview', 'acceptance', 'architecture', 'phases', 'decisions'];
required.forEach((name) => {
if (!opens.includes(name)) issues.push({ area: 'regions', level: 'warn', msg: `Recommended region "${name}" not found` });
});
// 5. Mermaid block render status (rendered nodes are marked diagram--error
// by mountMermaid; if Mermaid is loaded we can also re-parse sources).
const mermaidNodes = Array.from(document.querySelectorAll('pre.mermaid'));
const errFigs = Array.from(document.querySelectorAll('figure.diagram--error'));
errFigs.forEach((fig) => {
const label = fig.querySelector('.diagram__label');
const tag = label ? `"${label.textContent.trim()}"` : '(unlabeled)';
issues.push({ area: 'mermaid', level: 'error', msg: `Render failed for diagram ${tag} — inspect data-mermaid-source on its <pre class="mermaid">` });
});
// If Mermaid is available, try parse() for any node that wasn't already flagged.
if (window.__specmintMermaid && typeof window.__specmintMermaid.parse === 'function') {
for (const node of mermaidNodes) {
const fig = node.closest('figure.diagram');
if (fig && fig.classList.contains('diagram--error')) continue;
const src = node.getAttribute('data-mermaid-source') || node.textContent || '';
try {
await window.__specmintMermaid.parse(src);
} catch (e) {
const label = fig && fig.querySelector('.diagram__label');
const tag = label ? `"${label.textContent.trim()}"` : '(unlabeled)';
issues.push({ area: 'mermaid', level: 'error', msg: `Parse error in diagram ${tag}: ${(e && e.message ? e.message.split('\n')[0] : String(e))}` });
}
}
}
// 6. HTML-entity contamination inside Mermaid source (common AI authoring bug)
mermaidNodes.forEach((node) => {
const src = node.getAttribute('data-mermaid-source') || '';
const hit = src.match(/&(amp|lt|gt|quot|#\d+);/);
if (hit) {
const fig = node.closest('figure.diagram');
const label = fig && fig.querySelector('.diagram__label');
const tag = label ? `"${label.textContent.trim()}"` : '(unlabeled)';
issues.push({ area: 'mermaid', level: 'warn', msg: `Diagram ${tag} contains HTML entity "${hit[0]}" — Mermaid parses pre-content as plain text; use raw "<", ">", "&" characters` });
}
});
// 7. ASCII art inside mockup figures (common AI authoring bug — mockups
// MUST compose from .wf-* / .ui-* primitives, never <pre> with boxes)
document.querySelectorAll('figure.mockup').forEach((fig) => {
const pres = fig.querySelectorAll('pre');
pres.forEach((pre) => {
const text = pre.textContent || '';
const pipes = (text.match(/\|/g) || []).length;
const dashRuns = (text.match(/-{4,}/g) || []).length;
const corners = (text.match(/\+[-+]{2,}\+/g) || []).length;
if ((pipes >= 6 && dashRuns >= 2) || corners >= 2) {
const cap = fig.querySelector('figcaption');
const tag = cap ? `"${cap.textContent.trim().slice(0, 60)}"` : '(uncaptioned)';
issues.push({ area: 'mockup', level: 'warn', msg: `ASCII art detected inside mockup ${tag} — compose from .wf-* / .ui-* components instead (see references/wireframe-library.md or mockup-library.md)` });
}
});
});
// 8. Unescaped HTML special chars inside <pre><code> code blocks.
// <pre><code> is NOT a raw-text element in HTML5; unescaped "<", ">",
// "&" in the source are parsed as markup. Common AI authoring bug:
// pasting Java/TS generics (List<Object>), JSX (<Foo />), shell
// redirects (>>) or "&&" operators creates bogus child elements that
// silently swallow downstream <figure> / <section> content (often
// surfaces upstream as a region/endregion mismatch in check 2). Fix
// by replacing "<" with "<", ">" with ">", "&" with "&" in
// the code body. See edit-recipes.md "CRITICAL: escape HTML inside
// <pre><code>".
document.querySelectorAll('pre > code').forEach((code) => {
const bogus = new Set();
// PrismJS wraps tokens in <span class="token …">. Anything else inside
// <pre><code> almost certainly came from unescaped angle brackets.
code.querySelectorAll('*').forEach((el) => {
if (el.tagName !== 'SPAN') bogus.add(el.tagName.toLowerCase());
});
if (bogus.size) {
const fig = code.closest('figure');
const cap = fig && fig.querySelector('figcaption');
const tag = cap ? `"${cap.textContent.trim().slice(0, 80)}"` : '(uncaptioned)';
issues.push({
area: 'code',
level: 'error',
msg: `Unescaped angle bracket(s) inside <pre><code> in ${tag} — parser created bogus element(s) [${[...bogus].join(', ')}]. Replace "<" / ">" / "&" with "<" / ">" / "&" in the code body.`,
});
}
});
// Reporting
const errors = issues.filter((i) => i.level === 'error').length;
const warnings = issues.filter((i) => i.level === 'warn').length;
if (issues.length === 0) {
if (alwaysLog || debug) console.info(`[specmint] validate OK — ${mermaidNodes.length} diagram(s), ${taskCodes.length} task(s)`);
} else {
const label = `[specmint] validate — ${errors} error(s), ${warnings} warning(s)`;
console.groupCollapsed(label);
issues.forEach((i) => (i.level === 'error' ? console.warn : console.info)(`[${i.area}] ${i.msg}`));
console.groupEnd();
}
return issues;
}
// Expose for manual invocation in the page console.
window.specmintValidate = () => validate({ alwaysLog: true });
// ---------------------------------------------------------------------------
// init
// ---------------------------------------------------------------------------
async function init() {
deriveProgress();
mountDiffs();
mountAnnotationArrows();
mountCopyButtons();
mountTocActiveSection();
// mountMermaid is awaited so validate() sees the final diagram--error
// state for failed blocks.
await mountMermaid();
await validate();
const observer = new MutationObserver(deriveProgress);
observer.observe(document.body, {
attributes: true,
attributeFilter: ['data-status'],
subtree: true,
});
}
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', init);
} else {
init();
}
})();
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |