@starci/hfs 4.8.0 → 4.9.0

package/runtime/scripts/work/png.mjs

@@ -1,237 +0,0 @@
-// 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

@@ -1,64 +0,0 @@
-// 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('; ');