@12ui/design 0.2.29 → 0.2.31

package/open-design.json

@@ -3,7 +3,7 @@
   "specVersion": "1.0.0",
   "name": "12ui-design",
   "title": "12UI Design",
-  "version": "0.2.29",
+  "version": "0.2.31",
   "description": "Explore corpus-grounded interface directions, choose one, and convert it into production-ready responsive or native artifacts with 12UI.",
   "author": {
     "name": "Just Every",
@@ -49,7 +49,7 @@
           "command": "npx",
           "args": [
             "-y",
-            "@12ui/design@0.2.29",
+            "@12ui/design@0.2.31",
             "mcp"
           ]
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12ui/design",
-  "version": "0.2.29",
+  "version": "0.2.31",
   "type": "module",
   "description": "The canonical 12ui CLI, SDK, MCP server, and visual interface design skills",
   "main": "dist/index.js",
@@ -10,6 +10,7 @@
   },
   "files": [
     "dist/**/*",
+    "prototype-kit/**/*",
     "skills/**/*",
     "SKILL.md",
     "open-design.json",
@@ -22,14 +23,19 @@
     "start": "node dist/cli.js",
     "test": "vitest",
     "test:run": "vitest run",
+    "test:prototype": "node prototype-kit/tests/rules-check.mjs && node prototype-kit/tests/offline-check.mjs && node prototype-kit/tests/adversarial-runtime.mjs --assert",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.type-tests.json",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
     "@just-every/ensemble": "0.2.274",
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "linkedom": "^0.18.12",
     "sharp": "^0.35.3"
   },
+  "peerDependencies": {
+    "@playwright/test": "1.59.1"
+  },
   "devDependencies": {
     "@types/node": "^22.19.17",
     "typescript": "^5.9.3",

package/prototype-kit/analyze.mjs

@@ -0,0 +1,275 @@
+// Deterministic analysis of an inventory: states, shared shell, nav items, dropdowns, rows, buttons, link-like texts.
+// Usage: node analyze.mjs <inventory.json> <model.json>
+import fs from 'node:fs';
+import { matchPlannedPage } from './lib/navigation.mjs';
+import { compareCanonicalShells, isWithinShell, qualifiesShellCandidate, selectOneShellPerRegion } from './lib/shells.mjs';
+import { normalizeText as norm, slugText as slug } from './lib/text.mjs';
+
+const [invFile, outFile] = process.argv.slice(2);
+const inv = JSON.parse(fs.readFileSync(invFile, 'utf8'));
+const W = 1536, H = 1024;
+const planScreens = Array.isArray(inv.plan?.screens) ? inv.plan.screens : [];
+const chevronDown = (l) => /\b(down|caret down|chevron down|expand)\b/.test(norm(l)) && /chevron|caret|arrow|down/.test(norm(l));
+const chevronRight = (l) => /right/.test(norm(l)) && /chevron|arrow|caret/.test(norm(l));
+const linkVerb = /^(view|open|see|manage|clear|add|run|export|download|learn|read|sign|get|start|try|book|browse|explore|edit|approve|defer|review|show|load|invite|create|upgrade|contact|subscribe|join|buy|shop|reserve|rsvp|register|continue|back|cancel|save|send|submit|apply|filter|sort|search|show)\b/;
+
+// ---- states
+const states = [];
+for (const p of inv.pages) {
+  p.sections.forEach((s, i) => {
+    const slotMatch = s.sectionId.match(/^viewport-(\d+)-(\w+)$/);
+    const slot = slotMatch ? slotMatch[2] : String(i);
+    const screen = planScreens.find((x) => x.slot === slot);
+    const ordinal = i + 1;
+    const base = p.pageId.replace(/^p\d+-/, '');
+    states.push({
+      stateId: ordinal === 1 ? base : `${base}-${ordinal}`,
+      pageId: p.pageId,
+      pageIndex: p.planPage?.index ?? null,
+      file: p.file,
+      sectionId: s.sectionId,
+      slot,
+      ordinal,
+      title: p.planPage?.title || base.replace(/-/g, ' ').replace(/\b\p{L}/gu, (letter) => letter.toUpperCase()),
+      purpose: p.planPage?.purpose || '',
+      surfaceType: p.planPage?.surfaceType || '',
+      direction: screen?.direction || '',
+      content: screen?.content || '',
+      dependsOnSlot: screen?.dependsOnSlot || null,
+      isSource: !!p.planPage?.startsFromWinner && ordinal === 1,
+      items: s.items,
+      containers: s.containers,
+      height: s.height,
+      scriptDirection: s.scriptDirection,
+      writingMode: s.writingMode,
+    });
+  });
+}
+if (!states.length) throw new Error('Prototype input error: no semantic viewport sections found; exports require section ids shaped like viewport-<ordinal>-<slot>');
+const byId = Object.fromEntries(states.map((s) => [s.stateId, s]));
+const slotToState = Object.fromEntries(states.map((s) => [s.slot, s.stateId]));
+
+// ---- shell: elements repeated (same text/label, bbox within tol) across >= 60% of states
+const key = (it) => (it.text ? 't:' + norm(it.text) : it.label ? 'l:' + norm(it.label) : null);
+const TOL = 40;
+const minStates = Math.max(2, Math.ceil(states.length * 0.4));
+function repeatedKeys() {
+  const map = new Map();
+  for (const s of states) {
+    const seen = new Set();
+    for (const it of s.items) {
+      const k = key(it); if (!k || seen.has(k)) continue;
+      seen.add(k);
+      (map.get(k) || map.set(k, []).get(k)).push({ state: s.stateId, x: it.x, y: it.y, yb: s.height - it.y, w: it.w, h: it.h, id: it.id });
+    }
+  }
+  const rep = new Map();
+  for (const [k, occ] of map) {
+    if (occ.length < minStates) continue;
+    // cluster by position: count occurrences within TOL of the median
+    const mx = median(occ.map((o) => o.x)), my = median(occ.map((o) => o.y)), myb = median(occ.map((o) => o.yb));
+    const near = occ.filter((o) => Math.abs(o.x - mx) <= TOL && (Math.abs(o.y - my) <= TOL || Math.abs(o.yb - myb) <= TOL));
+    if (near.length >= minStates) rep.set(k, { x: mx, y: my, occ: near });
+  }
+  return rep;
+}
+function median(a) { const b = [...a].sort((x, y) => x - y); return b[Math.floor(b.length / 2)]; }
+const repeated = repeatedKeys();
+
+// top-level containers per state and their shell share
+function topContainers(s) {
+  const pre = s.sectionId + '-';
+  return s.containers.filter((c) => c.id.startsWith(pre) && !c.id.slice(pre.length).includes('-') && c.children > 0);
+}
+function regionOf(c) {
+  if (c.w <= 0.3 * W && c.h >= 0.7 * H && c.x <= 0.05 * W) return 'sidebar';
+  if (c.w >= 0.15 * W && c.h <= 0.2 * H && c.y <= 0.08 * H) return 'header';
+  if (c.w >= 0.6 * W && c.h <= 0.45 * H && c.y + c.h >= 0.9 * H) return 'footer';
+  return null;
+}
+const rejectedShellsByState = new Map();
+for (const s of states) {
+  s.shell = [];
+  const rejected = [];
+  for (const c of topContainers(s)) {
+    const inside = s.items.filter((it) => it.chain.includes(c.id) || it.id === c.id);
+    if (inside.length < 2) continue;
+    const shellCount = inside.filter((it) => { const k = key(it); return k && repeated.has(k) && repeated.get(k).occ.some((o) => o.state === s.stateId); }).length;
+    const share = shellCount / inside.length;
+    const region = regionOf(c);
+    const semantic = ['aside', 'header', 'footer', 'nav'].includes(c.tag) || /-(sidebar|nav|navbar|header|footer|topbar|sidenav)$/.test(c.id);
+    const shell = { containerId: c.id, region, share: +share.toFixed(2), semantic, items: inside.length, box: [c.x, c.y, c.w, c.h] };
+    const hasShellEvidence = region && (share >= 0.5 || (semantic && region === 'sidebar' && inside.length >= 3));
+    if (!hasShellEvidence) continue;
+    if (qualifiesShellCandidate(shell, W)) s.shell.push(shell);
+    else rejected.push(shell);
+  }
+  rejectedShellsByState.set(s.stateId, rejected);
+}
+const shellAmbiguities = [];
+for (const state of states) {
+  const { selected, dropped } = selectOneShellPerRegion(state.shell);
+  state.shell = selected;
+  for (const shell of [...dropped, ...(rejectedShellsByState.get(state.stateId) || [])]) {
+    const kept = selected.find((candidate) => candidate.region === shell.region);
+    if (!kept) continue;
+    shellAmbiguities.push({
+      state: state.stateId,
+      region: shell.region,
+      dropped: shell.containerId,
+      droppedBox: shell.box,
+      kept: kept?.containerId || null,
+      keptBox: kept?.box || null,
+    });
+  }
+}
+// canonical shell per region: prefer the source state, else the state whose container has the highest share*items
+let regions = [...new Set(states.flatMap((s) => s.shell.map((x) => x.region)))];
+const canonical = {};
+// how many short texts inside a container match a planned page title (used to rank competing shells)
+function pageMatches(s, cid) {
+  return s.items.filter((it) => it.text && it.text.length <= 32 && it.chain.includes(cid)).map((it) => matchPage(it.text)).filter(Boolean).length;
+}
+for (const r of regions) {
+  const cands = states.flatMap((s) => s.shell.filter((x) => x.region === r).map((x) => ({ ...x, stateId: s.stateId, isSource: s.isSource, matches: pageMatches(s, x.containerId) })));
+  if (cands.length < 2) { for (const s of states) s.shell = s.shell.filter((x) => x.region !== r); continue; }
+  cands.sort(compareCanonicalShells);
+  canonical[r] = { stateId: cands[0].stateId, containerId: cands[0].containerId, box: cands[0].box, presentIn: cands.map((c) => c.stateId), ranking: cands.map((c) => `${c.stateId}:${c.matches}m/${c.items}i/${c.share}`) };
+}
+regions = Object.keys(canonical);
+
+// ---- nav items: texts inside a canonical shell container that repeat, font >= 12, excluding long copy
+const nav = [];
+for (const r of regions) {
+  const can = canonical[r]; const s = byId[can.stateId];
+  const texts = s.items.filter((it) => it.text && it.chain.includes(can.containerId) && it.fontSize >= 12 && it.text.length <= 32 && !it.inButton && !/\d/.test(it.text));
+  // a nav list = >= 3 texts sharing the same x (vertical list) or same y (horizontal list)
+  const groups = new Map();
+  for (const t of texts) {
+    const gx = 'x' + Math.round(t.x / 6), gy = 'y' + Math.round(t.y / 6);
+    (groups.get(gx) || groups.set(gx, []).get(gx)).push(t);
+    (groups.get(gy) || groups.set(gy, []).get(gy)).push(t);
+  }
+  const best = [...groups.values()].sort((a, b) => b.length - a.length)[0] || [];
+  if (best.length >= 3) for (const t of best) nav.push({ region: r, id: t.id, text: t.text, x: t.x, y: t.y, w: t.w, h: t.h, fontSize: t.fontSize, color: t.color, fontWeight: t.fontWeight });
+}
+// match nav text -> page (first state of that page) by token overlap with title / pageId
+function matchPage(text) {
+  return matchPlannedPage(text, states.filter((state) => state.ordinal === 1))?.stateId || null;
+}
+for (const n of nav) { n.target = matchPage(n.text); }
+{ const first = nav.find((n) => n.region !== 'footer'); const home = states.find((s) => s.isSource) || states[0];
+  if (first && !first.target && /^(home|overview|dashboard|start)$/.test(norm(first.text))) { first.target = home.stateId; first.fallback = 'home'; } }
+for (const n of nav) n.holding = n.target ? null : 'holding-' + slug(n.text);
+
+// ---- per-state interactive candidates
+function smallestCommon(s, ids) {
+  const chains = ids.map((id) => { const it = s.items.find((x) => x.id === id); return it ? [it.id, ...it.chain] : []; });
+  for (const c of chains[0]) if (chains.every((ch) => ch.includes(c))) return c;
+  return null;
+}
+function containerItems(s, cid) { return s.items.filter((it) => it.id === cid || it.chain.includes(cid)); }
+for (const s of states) {
+  const shellIds = new Set(s.shell.map((x) => x.containerId));
+  const inShell = (it) => it.chain.some((c) => shellIds.has(c));
+  const cands = [];
+  // buttons
+  const btnMap = new Map();
+  for (const it of s.items) if (it.inButton && it.text) btnMap.set(it.buttonId, ((btnMap.get(it.buttonId) || '') + ' ' + it.text).trim());
+  for (const [bid, text] of btnMap) {
+    const c = s.containers.find((x) => x.id === bid);
+    cands.push({ id: bid, kind: 'button', text, box: c ? [c.x, c.y, c.w, c.h] : null, inShell: !!c && [...shellIds].some((sh) => s.items.find((it) => it.buttonId === bid)?.chain.includes(sh)) });
+  }
+  // dropdown triggers: a down-chevron icon whose smallest container with a text sibling
+  for (const ic of s.items.filter((it) => (it.cls.includes('icon') || it.tag === 'img') && chevronDown(it.label))) {
+    // find nearest text to the left on the same line
+    // prefer an enclosing input/select-like container; else the nearest text to the left on the same line
+    const fieldCid = ic.chain.find((cid) => /(input|select|filter|sort|dropdown|picker|menu)(-|$)/.test(cid) && (s.containers.find((x) => x.id === cid)?.w || 0) <= 420);
+    let near = fieldCid ? containerItems(s, fieldCid).filter((t) => t.text).sort((a, b) => a.x - b.x)[0] : null;
+    if (!near) near = s.items.filter((t) => t.text && Math.abs((t.y + t.h / 2) - (ic.y + ic.h / 2)) <= Math.max(8, t.h) && t.x + t.w <= ic.x + 4 && ic.x - (t.x + t.w) <= 260).sort((a, b) => (ic.x - (a.x + a.w)) - (ic.x - (b.x + b.w)))[0];
+    if (!near) continue;
+    const cid = fieldCid || smallestCommon(s, [ic.id, near.id]);
+    const c = s.containers.find((x) => x.id === cid);
+    if (cands.some((x) => x.id === (cid || near.id))) { const ex = cands.find((x) => x.id === (cid || near.id)); ex.kind = 'dropdown'; ex.textId = near.id; continue; }
+    cands.push({ id: cid || near.id, kind: 'dropdown', text: near.text, textId: near.id, iconId: ic.id, box: c ? [c.x, c.y, c.w, c.h] : [near.x, near.y, ic.x + ic.w - near.x, Math.max(near.h, ic.h)], inShell: inShell(near) });
+  }
+  // rows: right-chevron icon -> its row container (smallest container wider than 200px holding the icon and >=1 text)
+  for (const ic of s.items.filter((it) => (it.cls.includes('icon') || it.tag === 'img') && chevronRight(it.label))) {
+    // the full row = the widest ancestor that is still row-shaped (<= 140px tall)
+    let row = null;
+    for (const cid of ic.chain) { const c = s.containers.find((x) => x.id === cid); if (c && c.h <= 140 && c.w >= 200 && containerItems(s, cid).some((t) => t.text) && (!row || c.w * c.h >= row.w * row.h)) row = c; }
+    if (!row || shellIds.has(row.id) || isWithinShell(ic.chain, shellIds)) continue;
+    if (cands.some((x) => x.id === row.id)) continue;
+    const texts = containerItems(s, row.id).filter((t) => t.text).sort((a, b) => b.fontSize - a.fontSize);
+    cands.push({ id: row.id, kind: 'row', text: texts.slice(0, 2).map((t) => t.text).join(' — '), box: [row.x, row.y, row.w, row.h], inShell: false });
+  }
+  // link-like texts
+  for (const t of s.items) {
+    if (!t.text || t.inButton || t.text.length > 40) continue;
+    if (cands.some((c) => c.id === t.id || c.textId === t.id)) continue;
+    const isNav = inShell(t) && nav.some((n) => norm(n.text) === norm(t.text));
+    if (isNav) { cands.push({ id: t.id, kind: 'nav', text: t.text, box: [t.x, t.y, t.w, t.h], inShell: true }); continue; }
+    if (linkVerb.test(norm(t.text)) && t.text.split(' ').length <= 5) cands.push({ id: t.id, kind: 'link', text: t.text, box: [t.x, t.y, t.w, t.h], inShell: inShell(t) });
+  }
+  // card titles: prominent texts inside a sizeable card container (not the page title, not chrome)
+  const pageTitleY = Math.min(...s.items.filter((t) => t.text && t.fontSize >= 24 && !inShell(t)).map((t) => t.y), 1e9);
+  for (const t of s.items) {
+    if (!t.text || t.inButton || inShell(t) || t.fontSize < 17 || t.text.length > 48 || t.y <= pageTitleY + 4) continue;
+    if (cands.some((c) => c.id === t.id || c.textId === t.id || t.chain.includes(c.id))) continue;
+    const card = t.chain.map((cid) => s.containers.find((x) => x.id === cid)).find((c) => c && c.w >= 240 && c.h >= 80 && c.h <= 600 && c.bg && c.bg !== 'rgba(0, 0, 0, 0)');
+    if (!card) continue;
+    cands.push({ id: card.id, kind: 'card', text: t.text, textId: t.id, box: [card.x, card.y, card.w, card.h], inShell: false });
+  }
+  // search / bell / avatar icons in header: utility
+  for (const ic of s.items.filter((it) => (it.cls.includes('icon') || it.tag === 'img') && /search|magnif|bell|notification|avatar|profile|menu|hamburger|user/.test(norm(it.label)) && !it.inButton)) {
+    if (cands.some((c) => c.id === ic.id)) continue;
+    cands.push({ id: ic.id, kind: 'utility', text: ic.label, box: [ic.x, ic.y, ic.w, ic.h], inShell: inShell(ic) });
+  }
+  s.candidates = cands;
+  // form fields: containers whose id mentions input/field/composer/search and have a text child (placeholder)
+  s.fields = s.containers.filter((c) => /(input|field|composer|search|textarea|prompt)(-|$)/.test(c.id) && c.w >= 120 && c.h >= 28 && c.h <= 160 && !cands.some((x) => x.id === c.id)).map((c) => {
+    const texts = containerItems(s, c.id).filter((t) => t.text);
+    return { id: c.id, placeholder: texts[0]?.text || '', box: [c.x, c.y, c.w, c.h] };
+  });
+}
+
+// ---- style tokens from the source (or first) state
+const src = states.find((s) => s.isSource) || states[0];
+function mode(arr) { const m = new Map(); for (const a of arr) if (a) m.set(a, (m.get(a) || 0) + 1); return [...m.entries()].sort((a, b) => b[1] - a[1])[0]?.[0]; }
+const bodyTexts = src.items.filter((t) => t.text && t.fontSize >= 12 && t.fontSize <= 16);
+const heading = src.items.filter((t) => t.text).sort((a, b) => b.fontSize - a.fontSize)[0];
+const btnBgs = states.flatMap((s) => s.containers.filter((c) => c.tag === 'button' && c.bg && c.bg !== 'rgba(0, 0, 0, 0)').map((c) => c.bg));
+const accentText = mode(src.items.filter((t) => t.text && t.fontWeight >= 500 && !/rgb\((\d+), \1, \1\)/.test(t.color) && t.color !== 'rgb(0, 0, 0)').map((t) => t.color));
+const tokens = {
+  bodyFont: mode(bodyTexts.map((t) => t.fontFamily)),
+  bodySize: mode(bodyTexts.map((t) => Math.round(t.fontSize))),
+  bodyColor: mode(bodyTexts.map((t) => t.color)),
+  mutedColor: mode(src.items.filter((t) => t.text && t.fontSize < 13).map((t) => t.color)),
+  headingFont: heading?.fontFamily, headingSize: heading?.fontSize, headingColor: heading?.color, headingWeight: heading?.fontWeight,
+  accent: accentText,
+  buttonBg: mode(btnBgs),
+  cardRadius: mode(src.containers.filter((c) => c.w > 200 && c.h > 80 && c.radius !== '0px').map((c) => c.radius)),
+  cardBorder: mode(src.containers.filter((c) => c.w > 200 && c.h > 80 && !c.border.startsWith('0px')).map((c) => c.border)),
+  pageBg: src.containers.find((c) => c.x === 0 && c.y === 0 && c.w >= W - 1 && c.h >= H - 1)?.bg,
+  surfaceBg: mode(src.containers.filter((c) => c.w > 300 && c.h > 100 && c.bg !== 'rgba(0, 0, 0, 0)').map((c) => c.bg)),
+};
+
+const model = {
+  run: inv.runDir,
+  plan: { concept: typeof inv.plan?.concept === 'string' ? inv.plan.concept : '', sitePurpose: typeof inv.plan?.sitePurpose === 'string' ? inv.plan.sitePurpose : '', scope: inv.plan?.scope || null },
+  tokens,
+  canonicalShell: canonical,
+  shellAmbiguities,
+  nav,
+  states: states.map((s) => ({
+    stateId: s.stateId, pageId: s.pageId, file: s.file, sectionId: s.sectionId, slot: s.slot, ordinal: s.ordinal, title: s.title, purpose: s.purpose,
+    surfaceType: s.surfaceType, direction: s.direction, content: s.content, dependsOn: s.dependsOnSlot ? slotToState[s.dependsOnSlot] : null, isSource: s.isSource,
+    shell: s.shell, candidates: s.candidates, fields: s.fields, scriptDirection: s.scriptDirection, writingMode: s.writingMode,
+    texts: s.items.filter((t) => t.text).map((t) => ({ id: t.id, text: t.text })).length,
+  })),
+};
+fs.writeFileSync(outFile, JSON.stringify(model, null, 1));
+// summary
+console.error(`states: ${states.length}; shell regions: ${regions.join(',') || 'none'}; nav items: ${nav.length} (${nav.filter((n) => n.target).length} matched to pages)`);
+for (const s of model.states) console.error(` ${s.stateId.padEnd(28)} shell=${s.shell.map((x) => x.region).join('+') || '-'} cands=${s.candidates.length} [${['button', 'dropdown', 'row', 'link', 'nav', 'utility', 'card'].map((k) => k[0] + s.candidates.filter((c) => c.kind === k).length).join(' ')}] fields=${s.fields.length}`);
+console.error('tokens', JSON.stringify(tokens));