@starci/hfs 4.7.31 → 4.7.33

package/runtime/scripts/work/draw-grammar.mjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+// draw-grammar.mjs — which @starci/grammar a drawing renders against (owner ruling 2026-09-27: the draw must render
+// against the grammar version the product will SHIP).
+//
+// Candidates, in order:
+//   product      the grammar the product has installed (resolved from the product app dir, as its bundler would)
+//   claude-dist  the runtime-built package (.claude/packages/grammar/dist, the grammar main carries - possibly
+//                newer than the product's install, e.g. Meter segments 0.5.2 against an installed 0.5.0)
+// The product's install wins when it SATISFIES what the draw needs, and "satisfies" is decided by TypeScript: the
+// draw file type-checks against that candidate's types (scripts/work/draw/draw-source.mjs typecheckDraw). When only
+// claude-dist satisfies, the drawing renders against it through an alias in the draw bundle ONLY (draw-render.mjs
+// --grammar-root), the provenance says so (grammarSource claude-dist@<v>) and an upgrade of the product is OWED
+// (upgradeOwed {status: owed, from, to, range, inRange}) - interface.implement bumps the product's dependency; the
+// draw never touches the product's package.json. When neither satisfies: DRAW_TYPECHECK_FAILED.
+//
+//   starci work draw-grammar --product <app dir> [--file <X.draw.tsx>] [--grammar auto|product|claude-dist]
+//        [--grammar-dist <package root>]   (default .claude/packages/grammar; env STARCI_GRAMMAR_DIST; a lane checkout
+//        without a built dist points it at the live checkout's)
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { revParseQuery } from '../api/git/rev-parse-query.mjs';
+import { findPackage } from '../lib/package-at.mjs';
+import { readJsonFile } from '../lib/json.mjs';
+import { GRAMMAR_PACKAGE, typecheckDraw } from './draw/draw-typecheck.mjs';
+import { grammarDistStatus } from '../gates/grammar-dist.mjs';
+import { isFile } from './work-io.mjs';
+import { isMain } from '../lib/is-main.mjs';
+
+const GRAMMAR_SOURCES = Object.freeze(['product', 'claude-dist']);
+export const PREFERENCES = Object.freeze(['auto', ...GRAMMAR_SOURCES]);
+const SKILL_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+/** The product's declared range for the grammar (dependencies/devDependencies/peerDependencies), or null. */
+function productRangeOf(productDir) {
+  const pkg = readJsonFile(path.join(productDir, 'package.json'));
+  return pkg?.dependencies?.[GRAMMAR_PACKAGE] ?? pkg?.devDependencies?.[GRAMMAR_PACKAGE] ?? pkg?.peerDependencies?.[GRAMMAR_PACKAGE] ?? null;
+}
+
+/** A built grammar package root: its package.json plus dist/<family>/index.d.ts and .js. */
+const builtGrammar = (root) => isFile(path.join(root, 'package.json')) && isFile(path.join(root, 'dist', 'core', 'index.d.ts')) && isFile(path.join(root, 'dist', 'core', 'index.js'));
+
+/**
+ * The main worktree of the git checkout `dir` lives in (a lane worktree's live runtime), or null: a lane checkout never
+ * builds packages/grammar/dist (dist/ is untracked), so its drawings resolve the live runtime's build.
+ */
+function mainWorktreeOf(dir) {
+  try {
+    const r = revParseQuery(['--path-format=absolute', '--git-common-dir'], { dir, timeout: 10_000 });
+    const common = r.status === 0 ? r.stdout.trim() : '';
+    if (!common || path.basename(common) !== '.git') return null;
+    const main = path.dirname(common);
+    return path.resolve(main) === path.resolve(dir) ? null : main;
+  } catch { return null; }
+}
+
+/**
+ * The claude-dist roots, best first: --grammar-dist / STARCI_GRAMMAR_DIST when given (used as is), else the runtime's
+ * packages/grammar when its build is FRESH (grammar-dist.mjs: stamped from the current source), else the live main
+ * worktree's fresh build (a lane checkout), else the runtime's built but stale dist - named stale, never silently.
+ */
+function claudeDistRoots({ skillRoot = SKILL_ROOT, grammarDist = null, env = process.env, status = grammarDistStatus, mainOf = mainWorktreeOf } = {}) {
+  const pinned = grammarDist ?? env.STARCI_GRAMMAR_DIST ?? null;
+  if (pinned) return [{ root: path.resolve(pinned), status: null, via: grammarDist ? '--grammar-dist' : 'STARCI_GRAMMAR_DIST' }];
+  const own = path.join(skillRoot, 'packages', 'grammar');
+  const main = mainOf(skillRoot);
+  const tried = [{ root: own, via: 'runtime' }, ...(main ? [{ root: path.join(main, 'packages', 'grammar'), via: 'main-worktree' }] : [])]
+    .filter((c) => builtGrammar(c.root)).map((c) => ({ ...c, status: status(c.root) }));
+  const fresh = tried.filter((c) => c.status?.ok);
+  return fresh.length ? [fresh[0]] : tried.slice(0, 1);
+}
+
+function grammarCandidates({ productDir, skillRoot = SKILL_ROOT, grammarDist = null, claudeRoots = null }) {
+  const out = [];
+  const installed = productDir ? findPackage([productDir], [GRAMMAR_PACKAGE]) : null;
+  if (installed && builtGrammar(installed.root)) out.push({ source: 'product', root: installed.root, version: installed.version });
+  for (const c of claudeRoots ?? claudeDistRoots({ skillRoot, grammarDist })) {
+    if (!builtGrammar(c.root)) continue;
+    out.push({ source: 'claude-dist', root: c.root, version: readJsonFile(path.join(c.root, 'package.json'))?.version ?? null, via: c.via,
+      ...(c.status ? { dist: { state: c.status.state, ok: c.status.ok, detail: c.status.detail } } : {}) });
+  }
+  return out;
+}
+
+const parse = (v) => { const m = /^(\d+)\.(\d+)\.(\d+)/.exec(String(v ?? '').trim()); return m ? m.slice(1, 4).map(Number) : null; };
+const cmp = (a, b) => (a[0] - b[0]) || (a[1] - b[1]) || (a[2] - b[2]);
+/** Minimal semver range test: exact, ^, ~, >=, * (enough for a dependency line); null when unreadable. */
+function satisfiesRange(version, range) {
+  const v = parse(version);
+  if (!v || range == null) return null;
+  const r = String(range).trim();
+  if (r === '*' || r === 'latest' || r === '') return true;
+  const m = /^(\^|~|>=|=)?\s*v?(\d+\.\d+\.\d+)/.exec(r);
+  if (!m) return null;
+  const base = parse(m[2]);
+  if (cmp(v, base) < 0) return false;
+  if (m[1] === '>=') return true;
+  if (!m[1] || m[1] === '=') return cmp(v, base) === 0;
+  if (m[1] === '~') return v[0] === base[0] && v[1] === base[1];
+  // caret: the left-most non-zero part is fixed
+  if (base[0] > 0) return v[0] === base[0];
+  if (base[1] > 0) return v[0] === 0 && v[1] === base[1];
+  return v[0] === 0 && v[1] === 0 && v[2] === base[2];
+}
+
+function tryGrammarCandidates(candidates, { file, productDir, typecheck }) {
+  const attempts = [];
+  let pick = null;
+  for (const c of candidates) {
+    if (!file) { pick = c; break; }
+    const r = typecheck({ file, productDir, grammarRoot: c.root });
+    attempts.push({ source: c.source, version: c.version, root: c.root, ok: r.ok, errors: r.errors.slice(0, 20), typescript: r.typescript ?? null, ...(c.dist ? { dist: c.dist } : {}) });
+    if (r.ok) { pick = c; break; }
+  }
+  return { attempts, pick };
+}
+
+function upgradeOwedFor(pick, product, productRange) {
+  return pick?.source === 'claude-dist' ? { status: 'owed', package: GRAMMAR_PACKAGE, from: product?.version ?? null, to: pick.version, range: productRange,
+    inRange: satisfiesRange(pick.version, productRange), why: product ? `the product's installed ${GRAMMAR_PACKAGE}@${product.version} does not satisfy the drawing (it fails to type-check); ${pick.version} does` : `the product has no built ${GRAMMAR_PACKAGE} install` } : null;
+}
+
+function missingGrammarError(candidates, skillRoot) {
+  return candidates.length
+    ? `no grammar candidate type-checks the drawing (${candidates.map((candidate) => candidate.source + '@' + candidate.version + (candidate.dist && !candidate.dist.ok ? ' - its dist is ' + candidate.dist.state + ': ' + candidate.dist.detail + '; run npm run build in packages/grammar' : '')).join(', ')})`
+    : `no built ${GRAMMAR_PACKAGE} (product install, ${path.join(skillRoot, 'packages', 'grammar', 'dist')} or the main worktree's; run npm run build in packages/grammar, or pass --grammar-dist)`;
+}
+
+/**
+ * Resolve the grammar a draw file renders against. `typecheck` is injectable (tests). Without `file` the first
+ * candidate of the preference wins untested. Returns {ok, pick, grammarSource, productVersion, productRange,
+ * upgradeOwed, attempts:[{source, version, root, ok, errors}], error?}.
+ */
+export function resolveDrawGrammar({ file = null, productDir, skillRoot = SKILL_ROOT, grammarDist = null, prefer = 'auto', typecheck = typecheckDraw, claudeRoots = null }) {
+  if (!PREFERENCES.includes(prefer)) throw new Error(`--grammar must be one of ${PREFERENCES.join('|')}`);
+  const all = grammarCandidates({ productDir, skillRoot, grammarDist, claudeRoots });
+  const product = all.find((c) => c.source === 'product') ?? null;
+  const productRange = productRangeOf(productDir);
+  const candidates = prefer === 'auto' ? all : all.filter((c) => c.source === prefer);
+  const { attempts, pick } = tryGrammarCandidates(candidates, { file, productDir, typecheck });
+  const upgradeOwed = upgradeOwedFor(pick, product, productRange);
+  return {
+    ok: Boolean(pick), pick, grammarSource: pick ? `${pick.source}@${pick.version}` : null, productVersion: product?.version ?? null, productRange, upgradeOwed, attempts,
+    ...(pick ? {} : { error: missingGrammarError(candidates, skillRoot) }),
+  };
+}
+
+/** The file a grammar subpath import resolves to inside a grammar root (package exports; `import` for JS). */
+export function grammarEntry(root, subpath = '') {
+  const pkg = readJsonFile(path.join(root, 'package.json'));
+  const key = subpath ? `./${subpath.replace(/^\//, '')}` : '.';
+  const mapped = pkg?.exports?.[key];
+  const target = typeof mapped === 'string' ? mapped : mapped?.import ?? mapped?.default ?? mapped?.style ?? null;
+  if (target) return path.join(root, target);
+  if (!subpath) return path.join(root, 'dist', 'core', 'index.js');
+  return path.join(root, subpath);
+}
+
+async function main(argv) {
+  const val = (k) => { const i = argv.indexOf(k); return i >= 0 ? argv[i + 1] : null; };
+  const productDir = val('--product');
+  if (!productDir) { process.stderr.write('use: starci work draw-grammar --product <app dir> [--file <X.draw.tsx>] [--grammar auto|product|claude-dist] [--json]\n'); return 2; }
+  const r = resolveDrawGrammar({ file: val('--file') ? path.resolve(val('--file')) : null, productDir: path.resolve(productDir), prefer: val('--grammar') ?? 'auto', grammarDist: val('--grammar-dist') });
+  if (argv.includes('--json')) process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
+  else {
+    const summary = r.ok ? 'grammar ' + r.grammarSource : 'UNRESOLVED: ' + r.error;
+    const upgrade = r.upgradeOwed ? `; product upgrade owed ${r.upgradeOwed.from} -> ${r.upgradeOwed.to} (range ${r.upgradeOwed.range}, in range ${r.upgradeOwed.inRange})` : '';
+    const attempts = r.attempts.map((a) => '  ' + a.source + '@' + a.version + ': ' + (a.ok ? 'type-checks' : a.errors.length + ' error(s): ' + a.errors.slice(0, 3).map((e) => e.code + ' ' + e.message).join(' | '))).join('\n');
+    process.stdout.write(`${summary}${upgrade}\n${attempts}\n`);
+  }
+  return r.ok ? 0 : 1;
+}
+
+if (isMain(import.meta.url)) {
+  try { process.exitCode = await main(process.argv.slice(2)); } catch (e) { process.stderr.write(`draw-grammar: ${e?.stack ?? e}\n`); process.exitCode = 2; }
+}

package/runtime/scripts/work/draw-render-page.mjs

@@ -0,0 +1,188 @@
+// draw-render-page.mjs - the in-page half of draw-render.mjs. A page function is serialized to a string, so it cannot
+// reach the module scope: measureInPage assembles one script from the source of every function below (each is a
+// top-level declaration that reads only the page's globals and its own parameters) and runs it in the page.
+
+function measurePage({ generic, exemptSelector, layoutAttr = 'data-draw-layout' }) {
+  const faces = [...document.fonts].map((face) => ({ family: face.family.replace(/^(["'])(.*)\1$/, '$2'), weight: face.weight, style: face.style, status: face.status }));
+  const fontData = measureFonts(generic);
+  const de = document.documentElement;
+  const pageWidth = de.clientWidth;
+  const scrollWidth = Math.max(de.scrollWidth, document.body?.scrollWidth ?? 0);
+  const overflowing = measureOverflow(pageWidth, scrollWidth);
+  const root = document.getElementById('root');
+  const accentExempt = measureAccentExempt(exemptSelector);
+  const artwork = measureArtwork();
+  const anatomy = measureAnatomy();
+  const { ownership, dom } = measureOwnership(root, layoutAttr);
+  return { ownership, dom, anatomy, accentExempt, artwork, faces, stacks: [...fontData.stacks], local: fontData.local, pageWidth, innerWidth, scrollWidth, overflowing, documentHeight: de.scrollHeight,
+    rendered: document.documentElement.dataset.drawHarness === 'component' ? Boolean(root && root.childElementCount) : null };
+}
+
+function visible(el) {
+  const style = getComputedStyle(el);
+  return style.display !== 'none' && style.visibility !== 'hidden';
+}
+
+function measureFonts(genericFamilies) {
+  const stacks = new Set();
+  const walker = document.createTreeWalker(document.body ?? document.documentElement, NodeFilter.SHOW_TEXT);
+  for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+    const el = node.parentElement;
+    if (el && node.textContent.trim() && !['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEMPLATE'].includes(el.tagName) && visible(el)) { stacks.add(getComputedStyle(el).fontFamily); }
+  }
+  for (const el of document.querySelectorAll('input,textarea,select,button')) {
+    if (visible(el)) { stacks.add(getComputedStyle(el).fontFamily); }
+  }
+  const ctx = document.createElement('canvas').getContext('2d');
+  const sample = 'mmmmmmmmmmlli10WQ@#';
+  const width = (font) => { ctx.font = `72px ${font}`; return ctx.measureText(sample).width; };
+  const families = new Set([...stacks].flatMap((stack) => stack.split(',').map((family) => family.trim().replace(/^(["'])(.*)\1$/, '$2'))).filter((family) => family && !genericFamilies.includes(family.toLowerCase())));
+  const local = [...families].filter((family) => ['monospace', 'serif', 'sans-serif'].some((base) => width(`"${family}", ${base}`) !== width(base)));
+  return { stacks, local };
+}
+
+function measureOverflow(width, scroll) {
+  if (scroll > width) {
+    return [...document.querySelectorAll('body *')].filter((el) => el.getBoundingClientRect().right > width + 0.5)
+      .slice(0, 10).map((el) => el.tagName.toLowerCase() + (el.id ? '#' + el.id : '') + (typeof el.className === 'string' && el.className ? '.' + el.className.trim().split(/\s+/).slice(0, 3).join('.') : ''));
+  }
+  return [];
+}
+
+function measureAccentExempt(exemptSelector) {
+  try {
+    return [...document.querySelectorAll(exemptSelector)].map((el) => el.getBoundingClientRect())
+      .filter((rect) => rect.width > 0 && rect.height > 0).map((rect) => ({ x: rect.left + scrollX, y: rect.top + scrollY, width: rect.width, height: rect.height }));
+  } catch { return []; }
+}
+
+function measureArtwork() {
+  try {
+    return [...document.querySelectorAll('img')].filter((el) => visible(el) && (el.currentSrc || el.src)).map((el) => {
+      const rect = el.getBoundingClientRect();
+      let x0 = rect.left, y0 = rect.top, x1 = rect.right, y1 = rect.bottom;
+      for (let ancestor = el.parentElement; ancestor; ancestor = ancestor.parentElement) {
+        const style = getComputedStyle(ancestor);
+        if (style.overflowX !== 'visible' || style.overflowY !== 'visible') {
+          const clip = ancestor.getBoundingClientRect();
+          x0 = Math.max(x0, clip.left); y0 = Math.max(y0, clip.top); x1 = Math.min(x1, clip.right); y1 = Math.min(y1, clip.bottom);
+        }
+      }
+      return { src: el.currentSrc || el.src, slot: el.closest('[data-artwork-slot]')?.dataset.artworkSlot ?? null,
+        x: x0 + scrollX, y: y0 + scrollY, width: Math.max(0, x1 - x0), height: Math.max(0, y1 - y0) };
+    }).filter((art) => art.width > 0 && art.height > 0);
+  } catch { return []; }
+}
+
+function tagOf(el) {
+  return el.tagName.toLowerCase() + (el.id ? '#' + el.id : '');
+}
+
+function partIn(rootEl, names) {
+  return [...rootEl.querySelectorAll('[data-grammar-part]')].find((part) => names.includes(part.dataset.grammarPart.trim()));
+}
+
+function measureAnatomy() {
+  const anatomy = { alerts: [], meters: [] };
+  try {
+    const probe = document.createElement('div');
+    probe.style.cssText = 'position:absolute;visibility:hidden;background-color:var(--surface)';
+    document.body.appendChild(probe);
+    const surface = getComputedStyle(probe).backgroundColor;
+    probe.remove();
+    for (const el of document.querySelectorAll('[data-grammar-component="Alert"],[data-component="Alert"]')) {
+      const alert = measureAlert(el, surface);
+      if (alert) { anatomy.alerts.push(alert); }
+    }
+    for (const el of document.querySelectorAll('[data-grammar-component="Meter"],[data-component="Meter"]')) {
+      const meter = measureMeter(el);
+      if (meter) { anatomy.meters.push(meter); }
+    }
+  } catch { /* the anatomy is advisory measurement; the static gate still runs */ }
+  return anatomy;
+}
+
+function measureAlert(el, surface) {
+  if ('grammarPart' in el.dataset) { return null; }
+  const indicator = partIn(el, ['alert-indicator', 'indicator']) ?? el.querySelector('.alert__indicator');
+  const title = partIn(el, ['alert-title', 'title']) ?? el.querySelector('.alert__title');
+  const box = indicator?.getBoundingClientRect();
+  return { desc: tagOf(el), background: getComputedStyle(el).backgroundColor, surface,
+    indicator: box ? { width: box.width, height: box.height } : null, tile: Boolean(el.querySelector('[data-grammar-component="IconTile"],[data-component="IconTile"]')),
+    indicatorColor: indicator ? getComputedStyle(indicator.querySelector('svg') ?? indicator).color : null, titleColor: title ? getComputedStyle(title).color : null };
+}
+
+function measureMeter(el) {
+  if ('grammarPart' in el.dataset) { return null; }
+  const track = partIn(el, ['meter-track', 'track']) ?? el.querySelector('.meter__track');
+  const band = el.parentElement;
+  if (!track || !band) { return null; }
+  const style = getComputedStyle(band);
+  const trackRect = track.getBoundingClientRect();
+  const segments = [...el.querySelectorAll('[data-grammar-part*="segment"]:not([data-grammar-part$="segments"]), .starci-core-meter-segment, [data-grammar-meter-segment]')]
+    .map((part) => part.getBoundingClientRect()).map((rect) => ({ x: rect.left, width: rect.width }));
+  const segmented = 'grammarMeterSegments' in el.dataset || 'segments' in el.dataset || segments.length > 1;
+  return { desc: tagOf(el), segmented, track: { width: trackRect.width, height: trackRect.height },
+    band: { width: band.clientWidth - Number.parseFloat(style.paddingLeft || '0') - Number.parseFloat(style.paddingRight || '0') }, segments };
+}
+
+function marked(el) {
+  return 'component' in el.dataset || [...el.attributes].some((attr) => attr.name.startsWith('data-grammar-')) || [...el.classList].some((name) => name.startsWith('starci-core-'));
+}
+
+function paints(el) {
+  const style = getComputedStyle(el);
+  if (style.display === 'none' || style.visibility === 'hidden') { return false; }
+  if (['img', 'svg', 'canvas', 'video', 'picture'].includes(el.tagName.toLowerCase())) { return true; }
+  if ([...el.childNodes].some((node) => node.nodeType === 3 && node.textContent.trim())) { return true; }
+  if (style.backgroundColor && !/^(?:transparent|rgba\(0, 0, 0, 0\))$/.test(style.backgroundColor)) { return true; }
+  if (style.backgroundImage && style.backgroundImage !== 'none') { return true; }
+  if (['Top', 'Right', 'Bottom', 'Left'].some((side) => Number.parseFloat(style[`border${side}Width`]) > 0 && style[`border${side}Style`] !== 'none' && !/rgba\(0, 0, 0, 0\)/.test(style[`border${side}Color`]))) { return true; }
+  return Boolean(style.boxShadow && style.boxShadow !== 'none');
+}
+
+function measureOwnership(rootEl, layoutAttribute) {
+  let ownership = null, dom = null;
+  if (document.documentElement.dataset.drawHarness !== 'component' || !rootEl) { return { ownership, dom }; }
+  const components = new Set();
+  const unowned = [];
+  let layoutElements = 0;
+  for (const el of rootEl.querySelectorAll('*')) {
+    if ('component' in el.dataset) { components.add(el.dataset.component); }
+    layoutElements += Number(el.hasAttribute(layoutAttribute));
+    if ((el.closest('svg') && el.tagName.toLowerCase() !== 'svg') || !paints(el)) { continue; }
+    const owner = ownerOf(el, rootEl, layoutAttribute);
+    if (owner !== 'grammar') { unowned.push(ownershipLabel(el, owner)); }
+  }
+  ownership = { components: [...components].sort((left, right) => { if (left < right) { return -1; } if (left > right) { return 1; } return 0; }), layoutElements, unownedCount: unowned.length, unowned: unowned.slice(0, 20) };
+  const clone = document.documentElement.cloneNode(true);
+  for (const el of clone.querySelectorAll('[data-component]')) {
+    if (!('grammarComponent' in el.dataset)) { el.dataset.grammarComponent = el.dataset.component; }
+  }
+  for (const el of clone.querySelectorAll('script')) { el.remove(); }
+  dom = `<!doctype html>
+${clone.outerHTML}`;
+  return { ownership, dom };
+}
+
+function ownerOf(el, rootEl, layoutAttribute) {
+  for (let ancestor = el; ancestor && ancestor !== rootEl; ancestor = ancestor.parentElement) {
+    if (marked(ancestor)) { return 'grammar'; }
+    if (ancestor.hasAttribute(layoutAttribute)) { return 'layout'; }
+  }
+  return null;
+}
+
+function ownershipLabel(el, owner) {
+  return el.tagName.toLowerCase() + (typeof el.className === 'string' && el.className ? '.' + el.className.trim().split(/\s+/).slice(0, 3).join('.') : '') + (el.textContent.trim() ? ' "' + el.textContent.trim().slice(0, 40) + '"' : '') + ` (${owner ?? 'no owner'})`;
+}
+
+/** The expression that declares `functions` and returns what `entry` makes of `arg` (JSON data) in the page. */
+function pageScript(entry, functions, arg) {
+  return `(() => {\n${functions.map(String).join('\n')}\nreturn ${entry.name}(${JSON.stringify(arg)});\n})()`;
+}
+
+/** What the page measures: `arg` is {generic, exemptSelector, layoutAttr}. */
+export function measureInPage(page, arg) {
+  return page.evaluate(pageScript(measurePage, [measurePage, visible, measureFonts, measureOverflow, measureAccentExempt, measureArtwork, tagOf, partIn, measureAnatomy, measureAlert, measureMeter, marked, paints, measureOwnership, ownerOf, ownershipLabel], arg));
+}