@starci/hfs 4.7.47 → 4.9.0

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

@@ -1,175 +0,0 @@
-#!/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

@@ -1,188 +0,0 @@
-// 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));
-}