@starci/hfs 4.7.32 → 4.7.34

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

@@ -0,0 +1,279 @@
+#!/usr/bin/env node
+// grammar-proposal.mjs — what a drawing needs that the Grammar's DNA does not have (owner ruling 2026-09-27: "anything
+// DNA lacks becomes a grammar proposal, never invented inline").
+//
+// A drawing that needs a component or variant DNA lacks composes the closest DNA components, marks the spot
+// data-grammar-proposal="<name>" (scripts/work/draw/draw-dna.mjs), and writes the proposal beside its render source or
+// in its draw-loop directory:
+//   grammar-proposal.yaml   schema starci/grammar-proposal@1, proposals: [{name, gap, anatomy, tokens, claims, render,
+//                           status?}] - render is the isolated render (an .html/.png path relative to the file, or
+//                           inline html)
+//   grammar-proposal.md     one heading per proposal naming it (the name itself, `Meter` variant `segments`, or
+//                           data-grammar-proposal="Meter.segments"), its section stating the gap in DNA, the anatomy,
+//                           the tokens, the knowledge rules it claims (rule ids) and an isolated render (an html block
+//                           or a render path)
+// A proposal missing one of those is no entry: the element that cites it is DRAW_OFF_GRAMMAR_COMPONENT.
+//
+// A proposal is the owner's to accept, never the drawing worker's and never automatic: interface.draw's draw-review
+// ask lists every proposal of the record (question.grammarProposals, their isolated renders among question.assets), the
+// job's settle records one `grammar-proposal-filed` ledger event per proposal (status proposed), and `starci kernel status`
+// lists the workflow's open ones as grammarProposals[] until a grammar lane records `grammar-proposal-resolved`.
+//
+//   starci work grammar-proposal list <file|dir>... [--json]     every proposal found, complete or not
+//   starci work grammar-proposal check <file|dir>... [--json]    exit 1 when one is incomplete
+import fs from 'node:fs';
+import path from 'node:path';
+import { isMain } from '../lib/is-main.mjs';
+import { parseYaml } from '../../engine/yaml.mjs';
+import { sha256File } from '../../engine/digest.mjs';
+import { openEventItems } from '../lib/event-items.mjs';
+import { isDir, isFile } from './work-io.mjs';
+import { altOf } from '../lib/source-phrases.mjs';
+
+export const GRAMMAR_PROPOSAL_FILED = 'grammar-proposal-filed';
+const GRAMMAR_PROPOSAL_RESOLVED = 'grammar-proposal-resolved';
+export const PROPOSAL_FILE_NAMES = Object.freeze(['grammar-proposal.yaml', 'grammar-proposal.yml', 'grammar-proposal.md']);
+const PROPOSAL_FIELDS = Object.freeze(['gap', 'anatomy', 'tokens', 'claims', 'render']);
+/** A proposal is never accepted by the runtime: it stays proposed until the owner, through a grammar lane, decides. */
+export const PROPOSED = 'proposed';
+
+/** Section headings inside a proposal, never a proposal's name. */
+const SECTION_WORDS = new Set(['gap', 'why', 'anatomy', 'tokens', 'claims', 'render', 'rules', 'values', 'summary', 'notes', 'rationale', 'a11y', 'accessibility', 'usage', 'example', 'examples']);
+const RULE_ID = /\b[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*-\d+\b/;
+const HEADING_DASH_DELIMITER = /(?<!\s)\s+[\u2014\u2013-]\s+/;
+const HEADING_PAREN_DELIMITER = /(?<!\s)\s*\(/;
+const HTML_FENCE_OPENING = /```\s*html/i;
+const LINE_BREAK = /[\r\n\u2028\u2029]/;
+const WHITESPACE = /\s/;
+// A section marker matches in either language: the Vietnamese alternatives are lexicon data
+// (modules/goal/source-phrases.yaml proposal).
+const MD_FIELDS = {
+  gap: new RegExp(String.raw`\bgap\b|\bwhy\b|does not (have|publish|describe)|no (dna|component|variant)|lacks?\b|${altOf('proposal.gap')}`, 'i'),
+  anatomy: new RegExp(String.raw`\banatomy\b|\bslots?\b|\bparts?\b|${altOf('proposal.anatomy')}`, 'i'),
+  tokens: /\btokens?\b|var\(--|--[a-z][\w-]*|\b\d+px\b/i,
+  claims: RULE_ID,
+  render: /```\s*html|<(div|section|span|article|button|svg)\b|\.(png|html)\b|isolated render/i,
+};
+
+function headingLead(heading) {
+  const dash = HEADING_DASH_DELIMITER.exec(heading);
+  const paren = HEADING_PAREN_DELIMITER.exec(heading);
+  let end = heading.length;
+  if (dash) end = dash.index;
+  if (paren && paren.index < end) end = paren.index;
+  return heading.slice(0, end).trim();
+}
+
+function markdownHeading(line) {
+  let hashCount = 0;
+  while (hashCount < 4 && line[hashCount] === '#') hashCount += 1;
+  if (hashCount === 0 || !WHITESPACE.test(line[hashCount] ?? '')) return null;
+  let contentStart = hashCount;
+  while (WHITESPACE.test(line[contentStart] ?? '')) contentStart += 1;
+  const content = line.slice(contentStart);
+  const { firstText, lastText } = textExtent(content);
+  if (firstText < 0) return whitespaceOnlyHeading(line, hashCount);
+  if (LINE_BREAK.test(content.slice(firstText, lastText + 1))) return null;
+  return { level: hashCount, raw: content.slice(firstText, lastText + 1) };
+}
+
+/** The first and last index of non-whitespace in `content` (both -1 when it has none). */
+function textExtent(content) {
+  let firstText = -1;
+  let lastText = -1;
+  for (const [index, unit] of content.split('').entries()) {
+    if (!WHITESPACE.test(unit)) {
+      if (firstText < 0) firstText = index;
+      lastText = index;
+    }
+  }
+  return { firstText, lastText };
+}
+
+/** A heading with no text after its hashes: the last character after the first that is not a line break, if any. */
+function whitespaceOnlyHeading(line, hashCount) {
+  const whitespaceTail = line.slice(hashCount);
+  for (let index = whitespaceTail.length - 1; index > 0; index -= 1) {
+    if (!LINE_BREAK.test(whitespaceTail[index])) return { level: hashCount, raw: whitespaceTail[index] };
+  }
+  return null;
+}
+
+function fencedHtml(body) {
+  const opening = HTML_FENCE_OPENING.exec(body);
+  if (!opening) return null;
+  const contentStart = opening.index + opening[0].length;
+  const closingIndex = body.indexOf('```', contentStart);
+  if (closingIndex < 0) return null;
+  return body.slice(contentStart, closingIndex).trim();
+}
+
+const RENDER_EXTENSIONS = ['.png', '.html'];
+/** The first `<open>file.png|html<close>` span of a body, as {at, text}: a span ends at the first `close` after its `open`. */
+function markedRender(body, open, close) {
+  for (let at = body.indexOf(open); at >= 0;) {
+    const end = body.indexOf(close, at + 1);
+    if (end < 0) return null;
+    if (RENDER_EXTENSIONS.some((ext) => end - ext.length >= at + 2 && body.startsWith(ext, end - ext.length))) return { at, text: body.slice(at + 1, end) };
+    at = body.indexOf(open, open === close ? end : end + 1);
+  }
+  return null;
+}
+
+/** The render file a proposal body points at, in parentheses or backticks: the earlier of the two. */
+function renderReferenceOf(body) {
+  const paren = markedRender(body, '(', ')');
+  const tick = markedRender(body, '`', '`');
+  if (paren && tick) return (paren.at < tick.at ? paren : tick).text;
+  return (paren ?? tick)?.text ?? null;
+}
+
+/** The names a markdown heading declares for its proposal. */
+function headingNames(raw) {
+  const names = new Set();
+  for (const q of String(raw).matchAll(/data-grammar-proposal=["']([^"']+)["']/g)) names.add(q[1].trim());
+  const heading = String(raw).replace(/[`*]/g, '').trim().replace(/^\d+[.)]\s*/, '');
+  const variant = /^([A-Z]\w*)\s+(?:variant|slot|part)\s+([A-Za-z][\w-]*)/.exec(heading);
+  if (variant) names.add(`${variant[1]}.${variant[2]}`);
+  if (!names.size) for (const q of String(raw).matchAll(/`([A-Z]\w*(?:\.[\w-]+)?)`/g)) names.add(q[1]);
+  const lead = /^([A-Za-z][\w.-]*)$/.exec(headingLead(heading).split(':')[0].trim());
+  if (!names.size && lead && !SECTION_WORDS.has(lead[1].toLowerCase())) names.add(lead[1]);
+  return [...names];
+}
+
+function markdownProposals(text, file) {
+  const lines = String(text).split(/\r?\n/);
+  const heads = [];
+  lines.forEach((line, i) => { const heading = markdownHeading(line); if (heading) heads.push({ ...heading, line: i }); });
+  const out = [];
+  for (const [k, h] of heads.entries()) {
+    const names = headingNames(h.raw);
+    if (!names.length) continue;
+    const end = heads.slice(k + 1).find((n) => n.level <= h.level)?.line ?? lines.length;
+    const body = lines.slice(h.line + 1, end).join('\n');
+    const fields = Object.fromEntries(Object.entries(MD_FIELDS).map(([f, rx]) => [f, rx.test(body) || (f === 'gap' && rx.test(h.raw))]));
+    const missing = PROPOSAL_FIELDS.filter((f) => !fields[f]);
+    // A heading whose section states none of the fields (a document title over several proposals) is not a proposal.
+    if (missing.length === PROPOSAL_FIELDS.length) continue;
+    const gap = /(?:^|\n)#{1,4}\s*gap[^\n]*\n+([^\n#]+)/i.exec(body)?.[1] ?? body.split('\n').find((l) => MD_FIELDS.gap.test(l)) ?? '';
+    out.push({ name: names[0], names, file, format: 'md', gap: gap.trim().slice(0, 300), claims: [...new Set([...body.matchAll(new RegExp(RULE_ID.source, 'g'))].map((m) => m[0]))],
+      render: fencedHtml(body) ?? renderReferenceOf(body),
+      status: PROPOSED, complete: missing.length === 0, missing });
+  }
+  return out;
+}
+
+function yamlProposals(doc, file) {
+  let list = [];
+  if (Array.isArray(doc?.proposals)) list = doc.proposals;
+  else if (doc?.name) list = [doc];
+  return list.filter((p) => p && typeof p === 'object' && p.name).map((p) => {
+    const missing = PROPOSAL_FIELDS.filter((f) => p[f] == null || p[f] === '' || (Array.isArray(p[f]) && !p[f].length && f !== 'tokens'));
+    return { name: String(p.name).trim(), names: [String(p.name).trim()], file, format: 'yaml', gap: String(p.gap ?? '').slice(0, 300),
+      claims: Array.isArray(p.claims) ? p.claims.map(String) : [...String(p.claims ?? '').matchAll(new RegExp(RULE_ID.source, 'g'))].map((m) => m[0]),
+      render: typeof p.render === 'string' ? p.render : p.render?.path ?? null, status: p.status === PROPOSED || p.status == null ? PROPOSED : String(p.status),
+      complete: missing.length === 0, missing };
+  });
+}
+
+/** Every proposal in the given grammar-proposal files: [{name, names, file, format, gap, claims, render, status, complete, missing}]. */
+export function readProposals(files) {
+  const out = [];
+  for (const file of files ?? []) {
+    let text = '';
+    try { text = fs.readFileSync(file, 'utf8'); } catch { continue; }
+    if (/\.ya?ml$/i.test(file)) {
+      let doc = null;
+      try { doc = parseYaml(text); } catch { doc = null; }
+      out.push(...yamlProposals(doc, file));
+    } else out.push(...markdownProposals(text, file));
+  }
+  return out;
+}
+
+function collectProposalFiles(dir, left, out) {
+  let entries = [];
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (!e.isDirectory()) { if (PROPOSAL_FILE_NAMES.includes(e.name)) out.push(full); }
+    else if (left > 0 && !['node_modules', '.git'].includes(e.name)) collectProposalFiles(full, left - 1, out);
+  }
+}
+
+/** The grammar-proposal files under `dir` (at most `depth` levels, never node_modules or .git). */
+export function proposalFilesUnder(dir, depth = 6) {
+  const out = [];
+  if (isDir(dir)) collectProposalFiles(dir, depth, out);
+  else if (isFile(dir) && PROPOSAL_FILE_NAMES.includes(path.basename(dir))) out.push(dir);
+  return out;
+}
+
+/** The proposal files among `files` (files or directories). */
+function proposalFilesIn(files) {
+  const out = new Map();
+  for (const f of files ?? []) for (const p of proposalFilesUnder(f)) out.set(path.resolve(p).toLowerCase(), path.resolve(p));
+  return [...out.values()];
+}
+
+/** The isolated render image of a proposal, when it names a .png that exists. */
+export function proposalImageOf(p) {
+  if (!p?.render || !/\.png$/i.test(p.render)) return null;
+  const abs = path.resolve(path.dirname(p.file), p.render);
+  return isFile(abs) ? abs : null;
+}
+
+/**
+ * Record one `grammar-proposal-filed` event per proposal the job's files carry, once per (name, file sha256):
+ * never an acceptance. Returns the proposals newly recorded. `ledger` is an open ledger (appendEvent).
+ */
+export function recordGrammarProposals(ledger, { job, repo, files, now = Date.now() }) {
+  const db = ledger.db;
+  const found = readProposals(proposalFilesIn(files));
+  const recorded = [];
+  for (const p of found) {
+    let sha = null;
+    try { sha = sha256File(p.file); } catch { sha = null; }
+    const rel = path.relative(repo, p.file).replaceAll('\\', '/');
+    const seen = db.prepare("SELECT 1 FROM events WHERE workflow_id=? AND kind=? AND json_extract(payload_json,'$.name')=? AND json_extract(payload_json,'$.sha256') IS ? LIMIT 1")
+      .get(job.workflow_id, GRAMMAR_PROPOSAL_FILED, p.name, sha);
+    if (seen) continue;
+    const payload = { name: p.name, file: rel, sha256: sha, jobId: job.job_id, opId: job.op_id, attempt: job.attempt, status: PROPOSED, complete: p.complete,
+      ...(p.missing.length ? { missing: p.missing } : {}), gap: p.gap, claims: p.claims, render: p.render && p.render.length < 300 ? p.render : null };
+    ledger.appendEvent({ workflowId: job.workflow_id, entityType: 'job', entityId: job.job_id, kind: GRAMMAR_PROPOSAL_FILED, createdAt: now, payload });
+    recorded.push(payload);
+  }
+  return recorded;
+}
+
+/** The workflow's open grammar proposals (filed, not resolved): [{name, file, jobId, opId, filedAt, status, complete}]. */
+export function openGrammarProposals(db, workflowId) {
+  return openEventItems(db, workflowId, {
+    owedKind: GRAMMAR_PROPOSAL_FILED, resolvedKind: GRAMMAR_PROPOSAL_RESOLVED, keyOf: (p) => p.name,
+    item: (p, row) => ({ name: p.name, file: p.file ?? null, jobId: p.jobId ?? null, opId: p.opId ?? null, filedAt: row.created_at, status: PROPOSED, complete: p.complete !== false }),
+  });
+}
+
+function main(argv) {
+  const [cmd, ...rest] = argv;
+  const json = rest.includes('--json');
+  const targets = rest.filter((a) => !a.startsWith('--'));
+  if (!['list', 'check'].includes(cmd) || !targets.length) {
+    process.stderr.write('use: starci work grammar-proposal list|check <file|dir>... [--json]\n');
+    return 2;
+  }
+  const proposals = readProposals(proposalFilesIn(targets.map((t) => path.resolve(t))));
+  const incomplete = proposals.filter((p) => !p.complete);
+  if (json) process.stdout.write(`${JSON.stringify({ ok: cmd === 'list' || !incomplete.length, proposals }, null, 2)}\n`);
+  else {
+    const lines = proposals.map((p) => {
+      const status = p.complete ? 'ok  ' : 'INCOMPLETE';
+      const missing = p.missing.length ? ` missing ${p.missing.join(', ')}` : '';
+      return `${status} ${p.name} (${path.basename(p.file)})${missing}`;
+    }).join('\n') || 'no grammar proposals';
+    process.stdout.write(`${lines}\n`);
+  }
+  return cmd === 'check' && incomplete.length ? 1 : 0;
+}
+
+if (isMain(import.meta.url)) process.exitCode = main(process.argv.slice(2));

package/runtime/scripts/work/png.mjs

@@ -0,0 +1,237 @@
+// png.mjs — the PNG reader and writer the layout-tree tooling composes with.
+//
+// No dependency: `node:zlib` inflates and deflates, and `zlib.crc32` (Node >= 22.2) stamps the chunks. It
+// exists so a composite direction is a deterministic function of its inputs on every host - a consumer
+// install has no sharp, and a native image library would make the same inputs produce different bytes on
+// two machines. What it reads: bit depths 1/2/4/8/16, colour types 0 (greyscale), 2 (truecolour), 3
+// (palette, with tRNS), 4 (greyscale + alpha) and 6 (truecolour + alpha), non-interlaced. Everything else
+// throws `unsupported png: <why>` rather than guessing. Every image is handed back as 8-bit RGBA.
+import zlib from 'node:zlib';
+
+const SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const CHANNELS = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 };
+
+const paeth = (a, b, c) => {
+  const p = a + b - c, pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
+  if (pa <= pb && pa <= pc) return a;
+  return pb <= pc ? b : c;
+};
+
+function pngChunks(buf) {
+  let header = null, palette = null, trns = null;
+  const idat = [];
+  for (let at = 8; at + 8 <= buf.length;) {
+    const length = buf.readUInt32BE(at), type = buf.toString('latin1', at + 4, at + 8), start = at + 8;
+    if (start + length + 4 > buf.length) throw new Error(`unsupported png: chunk ${type} runs past the end of the file`);
+    const body = buf.subarray(start, start + length);
+    if (type === 'IHDR') header = { width: body.readUInt32BE(0), height: body.readUInt32BE(4), depth: body[8], colour: body[9], interlace: body[12] };
+    else if (type === 'PLTE') palette = body;
+    else if (type === 'tRNS') trns = body;
+    else if (type === 'IDAT') idat.push(body);
+    else if (type === 'IEND') break;
+    at = start + length + 4;
+  }
+  return { header, palette, trns, idat };
+}
+
+function sampleAt(line, depth, index) {
+  if (depth === 8) return line[index];
+  if (depth === 16) return line[index * 2];
+  const bit = index * depth, byte = line[bit >> 3], shift = 8 - depth - (bit & 7);
+  return (byte >> shift) & ((1 << depth) - 1);
+}
+
+function unfilterRow(raw, at, line, prior, filter, bpp) {
+  for (let i = 0; i < line.length; i += 1) {
+    const x = raw[at + 1 + i], a = i >= bpp ? line[i - bpp] : 0, b = prior[i], c = i >= bpp ? prior[i - bpp] : 0;
+    let value = x;
+    if (filter === 1) value += a;
+    else if (filter === 2) value += b;
+    else if (filter === 3) value += (a + b) >> 1;
+    else if (filter === 4) value += paeth(a, b, c);
+    line[i] = value & 0xff;
+  }
+}
+
+function writePixel(out, offset, sample, colour, scale, palette, trns) {
+  if (colour === 3) {
+    const index = sample(0);
+    out[offset] = palette[index * 3] ?? 0; out[offset + 1] = palette[index * 3 + 1] ?? 0; out[offset + 2] = palette[index * 3 + 2] ?? 0;
+    out[offset + 3] = trns && index < trns.length ? trns[index] : 255;
+  } else if (colour === 0 || colour === 4) {
+    const g = Math.round(sample(0) * scale);
+    out[offset] = g; out[offset + 1] = g; out[offset + 2] = g; out[offset + 3] = colour === 4 ? sample(1) : 255;
+  } else {
+    out[offset] = sample(0); out[offset + 1] = sample(1); out[offset + 2] = sample(2); out[offset + 3] = colour === 6 ? sample(3) : 255;
+  }
+}
+
+function decodeRows(raw, header, palette, trns, channels, stride, bpp) {
+  const { width, height, depth, colour } = header;
+  if (raw.length < (stride + 1) * height) throw new Error('unsupported png: image data shorter than the header declares');
+  const out = new Uint8Array(width * height * 4);
+  let prior = new Uint8Array(stride);
+  const line = new Uint8Array(stride);
+  const scale = depth < 8 && colour !== 3 ? 255 / ((1 << depth) - 1) : 1;
+  for (let y = 0; y < height; y += 1) {
+    const at = y * (stride + 1), filter = raw[at];
+    if (filter > 4) throw new Error(`unsupported png: filter type ${filter}`);
+    unfilterRow(raw, at, line, prior, filter, bpp);
+    const sample = (index) => sampleAt(line, depth, index);
+    for (let x = 0; x < width; x += 1) writePixel(out, (y * width + x) * 4, (index) => sample(x * channels + index), colour, scale, palette, trns);
+    prior = Uint8Array.from(line);
+  }
+  return out;
+}
+
+/** Decode PNG bytes into {width, height, data: Uint8Array RGBA}. Throws `unsupported png: ...`. */
+export function decodePng(bytes) {
+  const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes ?? []);
+  if (buf.length < 8 || !buf.subarray(0, 8).equals(SIGNATURE)) throw new Error('unsupported png: not a PNG signature');
+  const { header, palette, trns, idat } = pngChunks(buf);
+  if (!header?.width || !header?.height) throw new Error('unsupported png: no usable IHDR');
+  const { width, height, depth, colour } = header;
+  if (!(colour in CHANNELS)) throw new Error(`unsupported png: colour type ${colour}`);
+  if (![1, 2, 4, 8, 16].includes(depth) || ((colour === 2 || colour === 4 || colour === 6) && depth < 8) || (colour === 3 && depth > 8)) throw new Error(`unsupported png: bit depth ${depth} for colour type ${colour}`);
+  if (header.interlace !== 0) throw new Error('unsupported png: interlaced (Adam7) images are not read');
+  if (colour === 3 && !palette) throw new Error('unsupported png: palette image without PLTE');
+  let raw;
+  try { raw = zlib.inflateSync(Buffer.concat(idat)); } catch (error) { throw new Error(`unsupported png: image data does not inflate (${error.message})`); }
+  const channels = CHANNELS[colour];
+  const bitsPerPixel = channels * depth;
+  const stride = Math.ceil((width * bitsPerPixel) / 8);
+  const bpp = Math.max(1, bitsPerPixel >> 3);
+  return { width, height, data: decodeRows(raw, header, palette, trns, channels, stride, bpp) };
+}
+
+const chunk = (type, body) => {
+  const head = Buffer.alloc(8);
+  head.writeUInt32BE(body.length, 0);
+  head.write(type, 4, 'latin1');
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(zlib.crc32(Buffer.concat([Buffer.from(type, 'latin1'), body])) >>> 0, 0);
+  return Buffer.concat([head, body, crc]);
+};
+
+/** Encode {width, height, data RGBA} as PNG: truecolour when fully opaque, else truecolour + alpha. Filter 0, fixed deflate level. */
+export function encodePng({ width, height, data }) {
+  let opaque = true;
+  for (let i = 3; i < data.length; i += 4) if (data[i] !== 255) { opaque = false; break; }
+  const channels = opaque ? 3 : 4, stride = width * channels;
+  const raw = Buffer.alloc((stride + 1) * height);
+  for (let y = 0; y < height; y += 1) {
+    const row = y * (stride + 1);
+    raw[row] = 0;
+    for (let x = 0; x < width; x += 1) {
+      const s = (y * width + x) * 4, d = row + 1 + x * channels;
+      raw[d] = data[s]; raw[d + 1] = data[s + 1]; raw[d + 2] = data[s + 2];
+      if (!opaque) raw[d + 3] = data[s + 3];
+    }
+  }
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0); ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8; ihdr[9] = opaque ? 2 : 6; ihdr[10] = 0; ihdr[11] = 0; ihdr[12] = 0;
+  return Buffer.concat([SIGNATURE, chunk('IHDR', ihdr), chunk('IDAT', zlib.deflateSync(raw, { level: 9 })), chunk('IEND', Buffer.alloc(0))]);
+}
+
+/** A blank RGBA image filled with one colour [r, g, b, a]. */
+export function blankImage(width, height, rgba = [255, 255, 255, 255]) {
+  const data = new Uint8Array(width * height * 4);
+  for (let i = 0; i < data.length; i += 4) { data[i] = rgba[0]; data[i + 1] = rgba[1]; data[i + 2] = rgba[2]; data[i + 3] = rgba[3]; }
+  return { width, height, data };
+}
+
+/**
+ * Resample `image` to width x height. Downscaling by more than half averages the covered source area (a box
+ * filter), everything else is bilinear. Pure arithmetic, so the same inputs give the same pixels anywhere.
+ */
+function resizeBox(image, width, height, sx, sy, src, out) {
+  for (let y = 0; y < height; y += 1) {
+    const y0 = Math.floor(y * sy), y1 = Math.max(y0 + 1, Math.floor((y + 1) * sy));
+    for (let x = 0; x < width; x += 1) {
+      const x0 = Math.floor(x * sx), x1 = Math.max(x0 + 1, Math.floor((x + 1) * sx));
+      const sum = [0, 0, 0, 0];
+      for (let yy = y0; yy < y1; yy += 1) for (let xx = x0; xx < x1; xx += 1) { const s = (yy * image.width + xx) * 4; sum[0] += src[s]; sum[1] += src[s + 1]; sum[2] += src[s + 2]; sum[3] += src[s + 3]; }
+      const n = (y1 - y0) * (x1 - x0), d = (y * width + x) * 4;
+      for (let c = 0; c < 4; c += 1) out[d + c] = Math.round(sum[c] / n);
+    }
+  }
+  return { width, height, data: out };
+}
+
+function resizeBilinear(image, width, height, sx, sy, src, out) {
+  for (let y = 0; y < height; y += 1) {
+    const fy = Math.min(image.height - 1, Math.max(0, (y + 0.5) * sy - 0.5)), y0 = Math.floor(fy), y1 = Math.min(image.height - 1, y0 + 1), wy = fy - y0;
+    for (let x = 0; x < width; x += 1) {
+      const fx = Math.min(image.width - 1, Math.max(0, (x + 0.5) * sx - 0.5)), x0 = Math.floor(fx), x1 = Math.min(image.width - 1, x0 + 1), wx = fx - x0;
+      const a = (y0 * image.width + x0) * 4, b = (y0 * image.width + x1) * 4, c = (y1 * image.width + x0) * 4, e = (y1 * image.width + x1) * 4, d = (y * width + x) * 4;
+      for (let k = 0; k < 4; k += 1) out[d + k] = Math.round((src[a + k] * (1 - wx) + src[b + k] * wx) * (1 - wy) + (src[c + k] * (1 - wx) + src[e + k] * wx) * wy);
+    }
+  }
+  return { width, height, data: out };
+}
+
+export function resizeImage(image, width, height) {
+  if (image.width === width && image.height === height) return { width, height, data: Uint8Array.from(image.data) };
+  const out = new Uint8Array(width * height * 4), sx = image.width / width, sy = image.height / height, src = image.data;
+  if (sx > 2 || sy > 2) return resizeBox(image, width, height, sx, sy, src, out);
+  return resizeBilinear(image, width, height, sx, sy, src, out);
+}
+
+/** Crop a rectangle out of `image`. */
+export function cropImage(image, { x, y, width, height }) {
+  const out = new Uint8Array(width * height * 4);
+  for (let row = 0; row < height; row += 1) {
+    const s = ((y + row) * image.width + x) * 4;
+    out.set(image.data.subarray(s, s + width * 4), row * width * 4);
+  }
+  return { width, height, data: out };
+}
+
+function compositePixel(base, top, source, target, alphaByte) {
+  if (alphaByte === 255) { base.data[target] = top.data[source]; base.data[target + 1] = top.data[source + 1]; base.data[target + 2] = top.data[source + 2]; base.data[target + 3] = 255; return; }
+  if (alphaByte === 0) return;
+  const alpha = alphaByte / 255, beneath = base.data[target + 3] / 255, outA = alpha + beneath * (1 - alpha);
+  for (let c = 0; c < 3; c += 1) base.data[target + c] = Math.round((top.data[source + c] * alpha + base.data[target + c] * beneath * (1 - alpha)) / (outA || 1));
+  base.data[target + 3] = Math.round(outA * 255);
+}
+
+/** Alpha-composite `top` over `base` (mutated) with its top-left corner at (x, y); pixels outside `base` are dropped. */
+export function drawOver(base, top, x, y) {
+  for (let row = 0; row < top.height; row += 1) {
+    const by = y + row;
+    if (by < 0 || by >= base.height) continue;
+    for (let col = 0; col < top.width; col += 1) {
+      const bx = x + col;
+      if (bx < 0 || bx >= base.width) continue;
+      const s = (row * top.width + col) * 4, d = (by * base.width + bx) * 4;
+      compositePixel(base, top, s, d, top.data[s + 3]);
+    }
+  }
+  return base;
+}
+
+/** Darken every pixel of `image` (mutated) by a black scrim of opacity `amount` in [0, 1]. */
+export function dimImage(image, amount) {
+  const keep = 1 - amount;
+  for (let i = 0; i < image.data.length; i += 4) for (let c = 0; c < 3; c += 1) image.data[i + c] = Math.round(image.data[i + c] * keep);
+  return image;
+}
+
+/**
+ * The bounding rectangle of the pixels matching `key` ([r, g, b], within `tolerance` per channel), and how much
+ * of that rectangle they fill. A capture or a drawn layout marks its page slot with one flat key colour, so the
+ * slot is measured from the image rather than typed in.
+ */
+export function keyRect(image, key = [255, 0, 255], tolerance = 8) {
+  let minX = Infinity, minY = Infinity, maxX = -1, maxY = -1, count = 0;
+  const hits = (i) => Math.abs(image.data[i] - key[0]) <= tolerance && Math.abs(image.data[i + 1] - key[1]) <= tolerance && Math.abs(image.data[i + 2] - key[2]) <= tolerance && image.data[i + 3] > 200;
+  for (let y = 0; y < image.height; y += 1) for (let x = 0; x < image.width; x += 1) {
+    if (!hits((y * image.width + x) * 4)) continue;
+    count += 1;
+    minX = Math.min(minX, x); maxX = Math.max(maxX, x); minY = Math.min(minY, y); maxY = Math.max(maxY, y);
+  }
+  if (!count) return null;
+  const rect = { x: minX, y: minY, width: maxX - minX + 1, height: maxY - minY + 1 };
+  return { rect, fill: count / (rect.width * rect.height) };
+}

package/runtime/scripts/work/render-tools.mjs

@@ -0,0 +1,64 @@
+// render-tools.mjs - the tools a capture needs (Playwright with a browser, esbuild) and where they come from.
+//
+// A product declares neither: a drawing is captured by the runtime, so the runtime pins and installs both (package.json devDependencies,
+// the browser download Playwright keeps in its own cache). The product's own install, when it has one, comes first (its tailwindcss,
+// React and tsconfig paths resolve from the product regardless); the runtime's install is always the last candidate. This is the same
+// order layout-render.mjs uses for its capture. A host with neither a project install nor the runtime's, or with Playwright and no browser,
+// is RENDER_TOOL_UNAVAILABLE: one typed host fact the dispatch of an op that needs a capture checks before it spends an attempt.
+import fs from 'node:fs';
+import { skillRoot } from '../../engine/runtime-root.mjs';
+import { findPackage, requirePackage } from '../lib/package-at.mjs';
+import { toolSearchDirs } from '../lib/roots.mjs';
+
+/** The catalogued code of a host that cannot take a capture (modules/kernel/failure-codes.yaml). */
+export const RENDER_TOOL_UNAVAILABLE = 'RENDER_TOOL_UNAVAILABLE';
+/** The hint an op manifest carries in route.riskHints when its steps capture a render. */
+export const RENDER_CAPABILITY_HINT = 'host-capability-required:render';
+const PLAYWRIGHT_PACKAGES = Object.freeze(['playwright', '@playwright/test', 'playwright-core']);
+
+/** The first install of `names` resolvable from each of `dirs` in turn, one per distinct package root. */
+function installsOf(dirs, names) {
+  const seen = new Set();
+  const out = [];
+  for (const dir of dirs) {
+    const found = findPackage([dir], names);
+    if (found && !seen.has(found.root)) { seen.add(found.root); out.push(found); }
+  }
+  return out;
+}
+
+/** Whether the browser a Playwright install would launch is on the disk. */
+function browserOf(found) {
+  try { return fs.existsSync(requirePackage(found).chromium.executablePath()); } catch { return false; }
+}
+
+/**
+ * The Playwright install a capture launches: the first of the project's and the runtime's whose browser exists, else the first install
+ * (its launch then names the missing browser). Null when no directory resolves one.
+ */
+export function playwrightInstall(dirs, { runtime = skillRoot } = {}) {
+  const installs = installsOf(toolSearchDirs(dirs, runtime), PLAYWRIGHT_PACKAGES);
+  return installs.find(browserOf) ?? installs[0] ?? null;
+}
+
+/** The esbuild install a capture bundles with: the project's, else the runtime's; null when neither resolves one. */
+export const esbuildInstall = (dirs, { runtime = skillRoot } = {}) => findPackage(toolSearchDirs(dirs, runtime), ['esbuild']);
+
+/**
+ * What this host can capture with, from `dirs` (the tree the op runs in) and the runtime: {ok, missing: [{tool, why}], playwright, esbuild}.
+ * `missing` names each absent tool with the one-line reason a Kernel and the owner read.
+ */
+export function renderToolStatus(dirs = [], { runtime = skillRoot } = {}) {
+  const playwright = playwrightInstall(dirs, { runtime });
+  const esbuild = esbuildInstall(dirs, { runtime });
+  const missing = [];
+  if (!playwright) missing.push({ tool: 'playwright', why: 'no Playwright install resolves from the project or the runtime' });
+  else if (!browserOf(playwright)) missing.push({ tool: 'chromium', why: `Playwright ${playwright.version} resolves at ${playwright.root.split(/[\\/]/).slice(-2).join('/')} and its Chromium download is absent from the browser cache` });
+  if (!esbuild) missing.push({ tool: 'esbuild', why: 'no esbuild install resolves from the project or the runtime' });
+  return { ok: missing.length === 0, missing, playwright, esbuild };
+}
+
+/** The one-line instruction for a missing tool: what provisions it. */
+export const renderToolFix = (missing) => missing.map((item) => (item.tool === 'chromium'
+  ? 'run `npx playwright install chromium` once on the host (the browser cache is the owner\'s to fill)'
+  : `install the runtime's dependencies (\`npm install\` in the runtime checkout) so ${item.tool} resolves`)).join('; ');