@appinternalleads/ui 0.4.2 → 0.4.3

package/tools/ask/mcp.mjs

@@ -44,6 +44,8 @@ const PROTOCOL = '2025-06-18';
  */
 const HERE = dirname(fileURLToPath(import.meta.url));
 const PKG = resolve(HERE, '../..');
+/* The server is the package's: one version, read where it is written. */
+const VERSION = JSON.parse(readFileSync(resolve(PKG, 'package.json'), 'utf8')).version;
 const QUESTION_SCHEMA = JSON.parse(
   readFileSync(resolve(PKG, 'spec/question.generate.json'), 'utf8'),
 );
@@ -667,7 +669,7 @@ const CHECK_ANIMATION_REQUEST = {
 /**
  * **The neon sign — the one animation this server renders itself.** The five templates above are
  * rendered by Remotion from the repository; the neon is the package's own `NeonCanvas`, which
- * ships, so a headless browser can draw it wherever the package is installed (`neon-render.mjs`).
+ * ships, so a headless browser can draw it wherever the package is installed (`render.mjs`).
  *
  * It is listed, described and checked by the same three tools as every other animation (template
  * `neon-sign`). This tool carries the schema in full as well, because a model reads a tool's
@@ -677,20 +679,158 @@ const CHECK_ANIMATION_REQUEST = {
 const NEON_TEMPLATE = 'neon-sign';
 const RENDER_NEON = {
   name: 'render_neon_sign',
-  title: 'Render a neon sign to a video file',
+  title: 'Render a neon sign to an image or a video file',
   description:
-    'Render an animated neon sign and save it as a video (MP4, WebM or GIF): glowing neon text, '
-    + 'emoji or artwork on a brick wall, with natural flicker and glitches. Each element has its own '
-    + 'colour and font, so a sign in two colours is two `elements`. The scene contains exactly what '
-    + 'you send. Returns { success, outputPath, animation, format, width, height, durationSeconds, '
-    + 'fps, frameCount, validationErrors }; when success is false, fix each validationErrors path '
-    + 'and call again. `describe_animation` with template "neon-sign" lists every colour name, font '
+    'Render a neon sign and save it as a still image (PNG, JPG) or a video (MP4, WebM, GIF): glowing '
+    + 'neon text, emoji or artwork on a brick wall, with natural flicker and glitches. Each element has '
+    + 'its own colour and font, so a sign in two colours is two `elements`. The scene contains exactly '
+    + 'what you send. A still is one frame drawn directly; with no timeSeconds a glitching sign is caught '
+    + 'mid-glitch. Returns { success, outputPath, animation, format, width, height, validationErrors } '
+    + 'with timestampSeconds for a still, or durationSeconds, fps and frameCount for a video; when '
+    + 'success is false, fix each validationErrors path and call again. `describe_animation` with template "neon-sign" lists every colour name, font '
     + 'and level; `check_animation_request` checks a request without rendering it.',
   /* Filled from the bundle on first `tools/list`: the schema lives beside the code that reads it. */
   inputSchema: { type: 'object', properties: {} },
 };
 
-const ANIMATION_TOOLS = ['list_animations', 'describe_animation', 'check_animation_request', 'render_neon_sign'];
+/**
+ * **Objects built from parts.** `TypeSurface` in `@comppack/ui/motion` has no catalogue of objects:
+ * a tumbler is a hollow tapered cylinder, a ring and a foot. These three tools are that layer over
+ * MCP: read what can be built, check a request, and get a PNG or JPG. The renderer is the package's own
+ * (`render.mjs`), so it draws wherever the package is installed.
+ */
+const DESCRIBE_OBJECTS = {
+  name: 'describe_object_construction',
+  title: 'What objects can be built, and from what',
+  description:
+    'For product-style objects with text on them (a tumbler, mug, can, bottle, vase, jar, lamp, or anything round that has no name here): '
+    + 'the primitives (cylinder, sphere, ring, revolve, tube, box) with every parameter and its range, the manipulators each accepts '
+    + '(taper, flare, bulge, twist, bend, scale), the materials, how the text attaches, the recipes with their full specs to copy and edit, '
+    + 'the fonts, and what cannot be done. There is no object catalogue: compose a spec from these. Then check_object_request and render_object.',
+  inputSchema: { type: 'object', properties: {} },
+};
+
+const CHECK_OBJECT = {
+  name: 'check_object_request',
+  title: 'Check an object request without rendering it',
+  description:
+    'Validate a render_object request. Valid → { valid: true, object: { parts, text, fontSize, pose… }, config } where `config` is the '
+    + 'full TypeSurface config (the reusable preset: save it, or draw it with <TypeSurfaceCanvas config>). '
+    + 'Invalid → { valid: false, errors: [{ path, message }] }: fix each path and check again. Costs no browser.',
+  inputSchema: { type: 'object', properties: { request: { type: 'object', description: 'The render_object arguments, without outputPath.' } }, required: ['request'] },
+};
+
+const RENDER_OBJECT = {
+  name: 'render_object',
+  title: 'Render an object with text on it to an image',
+  description:
+    'Build an object from parts and save a picture of it (PNG or JPG): a recipe (tumbler, mug, can, bottle) in any colour and material, or any '
+    + 'spec of primitives you compose, with words wrapped on it. The text is sized to the part and inked to read on it unless you say otherwise. '
+    + 'Returns { success, outputPath, format, width, height, object, fonts, validationErrors }; when success is false, fix each '
+    + 'validationErrors path and call again. `describe_object_construction` lists every shape, manipulator, material and range.',
+  /* Filled from the bundle on first `tools/list`: the schema lives beside the code that reads it. */
+  inputSchema: { type: 'object', properties: {} },
+};
+
+/**
+ * **Words on a surface.** The other half of `TypeSurface`: a newspaper page, a sheet of paper, a
+ * bottle label, a wrapper, cloth, with the text printed into it. One tool, because the whole
+ * request fits in its arguments: the surface, its state, and optionally a ready-made motion whose
+ * timeline a video plays.
+ */
+const RENDER_SURFACE = {
+  name: 'render_surface',
+  title: 'Render words printed on a surface to an image or a video',
+  description:
+    'Print words on a newspaper page, a sheet of paper, a bottle label, a wrapper or fabric and save the picture (PNG, JPG) or a video '
+    + 'of the surface transforming (MP4, WebM, GIF): a headline on a newspaper, a note on crumpled paper, a print on cloth. `state` sets '
+    + 'how the surface lies (flat, folded, rolled, crumpled); `motion` picks a ready-made transformation whose timeline the video plays. '
+    + 'A still shows the finished picture unless timeSeconds names a moment. Returns { success, outputPath, format, width, height, '
+    + 'surface, validationErrors }; when success is false, fix each validationErrors path and call again. For a tumbler, mug, can or '
+    + 'anything built from parts, use render_object.',
+  /* Filled from the bundle on first `tools/list`. */
+  inputSchema: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'] },
+};
+
+async function surfaceRenderTool() {
+  try {
+    const s = (await componentsModule()).SURFACE_INPUT_SCHEMA;
+    return { ...RENDER_SURFACE, inputSchema: { ...s, properties: { ...s.properties, outputPath: { type: 'string', description: 'Where to save the image or video, absolute or relative to the working directory. Default comppack-renders/surface-<surface>-<text>.<format>.' } } } };
+  } catch { return RENDER_SURFACE; }
+}
+
+const OBJECT_TOOLS = ['describe_object_construction', 'check_object_request', 'render_object', 'render_surface'];
+
+const problems = (errors) => `${errors.length} ${errors.length === 1 ? 'problem' : 'problems'}:\n${errors.map(e => `  ${e.path || '(request)'}: ${e.message}`).join('\n')}`;
+
+async function objectTool(id, name, args) {
+  let m;
+  try { m = await componentsModule(); } catch (e) {
+    return toolError(id, `The object catalogue did not load (run \`npm run ask:build\`): ${e.message}`);
+  }
+  if (name === 'render_surface') {
+    return renderFile(id, {
+      kind: 'surface', args, base: {}, formats: ['png', 'jpg', 'mp4', 'webm', 'gif'],
+      build: content => m.buildSurfaceConfig(content),
+      name: built => `surface-${`${built.config.surface.type}-${built.config.text}`.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 40)}`,
+      describe: summary => ({ surface: summary }),
+      say: summary => `: “${summary.text}” on ${summary.surface} (${summary.state})${summary.motion ? `, motion ${summary.motion}` : ''}. Look at the file before reporting it done.`,
+    });
+  }
+  if (name === 'describe_object_construction') {
+    const d = m.describeObjectConstruction();
+    return answer(id, d, JSON.stringify(d, null, 2));
+  }
+  if (name === 'check_object_request') {
+    const r = m.validateObjectRequest(args?.request);
+    if (!r.valid) return answer(id, r, `Not valid — ${problems(r.errors)}`, true);
+    return answer(id, r, `Valid — ${r.object.name}: ${r.object.composition} “${r.object.text}” on ${r.object.textOn}, size ${r.object.fontSize}. Call render_object with the same arguments to save it as PNG or JPG.`);
+  }
+
+  return renderFile(id, {
+    kind: 'object', args, base: {}, formats: ['png', 'jpg'],
+    build: content => m.buildObjectConfig(content),
+    name: built => `object-${`${built.config.object.name}-${built.config.text}`.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 40) || 'object'}`,
+    describe: summary => ({ object: summary }),
+    say: summary => `: ${summary.composition} “${summary.text}” at size ${summary.fontSize}. Look at the file before reporting it done.`,
+  });
+}
+
+/** The object tool with its schema, read from the bundle; without the bundle, the tool as declared. */
+async function objectRenderTool() {
+  try {
+    const s = (await componentsModule()).OBJECT_INPUT_SCHEMA;
+    return { ...RENDER_OBJECT, inputSchema: { ...s, properties: { ...s.properties, outputPath: { type: 'string', description: 'Where to save the image, absolute or relative to the working directory. Default comppack-renders/object-<name>-<text>.<format>.' } } } };
+  } catch { return RENDER_OBJECT; }
+}
+
+/**
+ * **The templates, rendered where the package is installed.** Their MP4s used to exist only in the
+ * repository, through Remotion. The package ships each template's own player, which holds any frame
+ * it is given, so the same headless browser that draws the neon steps a template through its frames.
+ */
+const RENDER_ANIMATION = {
+  name: 'render_animation',
+  title: 'Render an animation template to an image or a video file',
+  description:
+    'Render a motion/1 request (the one check_animation_request accepts) and save it as a video (MP4, WebM, GIF) '
+    + 'or as one still frame (PNG, JPG). The motion is the template\'s own: nothing here changes timing. For a still, '
+    + 'timeSeconds chooses the moment; without it the middle of the animation is used, moved on if that frame is empty. '
+    + 'Returns { success, outputPath, animation, format, width, height, validationErrors } with timestampSeconds for a '
+    + 'still, or durationSeconds, fps and frameCount for a video. list_animations and describe_animation give the '
+    + 'templates and their contracts; for a neon sign, render_neon_sign takes the sign directly.',
+  /* Filled from the bundle on first `tools/list`. */
+  inputSchema: { type: 'object', properties: { request: { type: 'object' } }, required: ['request'] },
+};
+
+async function animationRenderTool() {
+  try {
+    const s = (await componentsModule()).ANIMATION_INPUT_SCHEMA;
+    return { ...RENDER_ANIMATION, inputSchema: { ...s, properties: { ...s.properties, outputPath: { type: 'string', description: 'Where to save the image or video, absolute or relative to the working directory. Default comppack-renders/<template>.<format>.' } } } };
+  } catch { return RENDER_ANIMATION; }
+}
+
+const ANIMATION_TOOLS = ['list_animations', 'describe_animation', 'check_animation_request', 'render_animation', 'render_neon_sign'];
 const SITE_URL = process.env.COMPPACK_SITE_URL || 'https://comppack.vercel.app';
 
 async function animationTool(id, name, args) {
@@ -699,6 +839,7 @@ async function animationTool(id, name, args) {
     return toolError(id, `The animation catalogue did not load (run \`npm run ask:build\`): ${e.message}`);
   }
   if (name === 'render_neon_sign') return renderNeonSign(id, m, args);
+  if (name === 'render_animation') return renderAnimation(id, m, args);
   if (name === 'list_animations') {
     const list = [...m.listMotionTemplates(), m.listNeonAnimation()];
     return answer(id, { animations: list }, JSON.stringify(list, null, 2));
@@ -725,56 +866,83 @@ async function animationTool(id, name, args) {
     return answer(id, r, `Not valid — ${r.errors.length} ${r.errors.length === 1 ? 'problem' : 'problems'}:\n${r.errors.map(e => `  ${e.path || '(request)'}: ${e.message}`).join('\n')}`, true);
   }
   const previewUrl = m.motionPreviewUrl(r.request, SITE_URL);
-  return answer(id, { valid: true, seconds: r.seconds, previewUrl, previewFormat: 'HTML + CSS (DOM), played live in the browser', request: r.request }, `Valid — ${r.seconds}s of ${r.request.template}. Preview (live HTML + CSS in the browser, not a video file): ${previewUrl}. The same request renders to MP4 (H.264) with Remotion.`);
+  return answer(id, { valid: true, seconds: r.seconds, previewUrl, previewFormat: 'HTML + CSS (DOM), played live in the browser', request: r.request }, `Valid — ${r.seconds}s of ${r.request.template}. Preview (live HTML + CSS in the browser, not a video file): ${previewUrl}. Call render_animation with this request to save it as a video or a still.`);
 }
 
 /**
- * `args` is the neon content plus `outputPath`. Checked in node first (the package's own
- * `validateNeonScene`), so a bad request costs no browser; the page checks again with real fonts.
+ * **One render, whatever is drawn.** The three render tools differ in what they build; from there
+ * the path is the same: the arguments are the request plus `outputPath`, the request is checked in
+ * node first (so a bad one costs no browser), the page checks it again with real fonts, and the
+ * result says what the file is. A path that names its format is a format.
  */
-async function renderNeonSign(id, m, args) {
+async function renderFile(id, { kind, args, base, formats, build, name, describe, say = () => '.' }) {
   const { outputPath: wanted, ...content } = args ?? {};
-  const base = { success: false, animation: NEON_TEMPLATE };
-  const refuse = (errors) => answer(id, { ...base, validationErrors: errors },
-    `Not rendered — ${errors.length} ${errors.length === 1 ? 'problem' : 'problems'}:\n${errors.map(e => `  ${e.path || '(request)'}: ${e.message}`).join('\n')}`, true);
-
+  const refuse = (errors) => answer(id, { success: false, ...base, validationErrors: errors }, `Not rendered — ${problems(errors)}`, true);
   if (wanted !== undefined && (typeof wanted !== 'string' || !wanted.trim())) return refuse([{ path: 'outputPath', message: 'Must be a file path.' }]);
-  /* A path that names its format is a format. */
-  const ext = wanted ? extname(wanted).slice(1).toLowerCase() : '';
-  if (content.format === undefined && ['mp4', 'webm', 'gif'].includes(ext)) content.format = ext;
-  const built = m.buildNeonScene(content);
+  const ext = wanted ? extname(wanted).slice(1).toLowerCase().replace('jpeg', 'jpg') : '';
+  if (content.format === undefined && formats.includes(ext)) content.format = ext;
+  const built = build(content);
   if (!built.valid) return refuse(built.errors);
 
   const { output } = built;
-  const slug = m.neonSceneSummary(built.scene).map(e => e.content).join('-').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 40) || 'sign';
-  const outputPath = resolve(process.cwd(), wanted ?? `comppack-renders/neon-${slug}.${output.format}`);
   if (ext && ext !== output.format) return refuse([{ path: 'outputPath', message: `Ends in .${ext} but the format is ${output.format}.` }]);
-
+  const outputPath = resolve(process.cwd(), wanted ?? `comppack-renders/${name(built)}.${output.format}`);
   const started = Date.now();
   let r;
   try {
-    const { renderNeon } = await import('./neon-render.mjs');
-    r = await renderNeon({ content, output, outputPath, backgroundColor: built.backgroundColor });
+    const { render } = await import('./render.mjs');
+    r = await render({ kind, content: built.content ?? content, output, outputPath, backgroundColor: built.backgroundColor });
   } catch (e) {
     const message = e instanceof Error ? e.message : String(e);
-    return answer(id, { ...base, validationErrors: [], error: message }, `Not rendered: ${message}`, true);
+    return answer(id, { success: false, ...base, validationErrors: [], error: message }, `Not rendered: ${message}`, true);
   }
   if (r.errors.length) return refuse(r.errors);
 
+  const moment = output.still && (kind !== 'object') ? { timestampSeconds: r.timestampSeconds } : {};
   const result = {
-    success: true, outputPath, animation: NEON_TEMPLATE, format: output.format, width: output.width, height: output.height,
-    durationSeconds: output.durationSeconds, fps: output.fps, frameCount: output.frameCount, validationErrors: [],
-    bytes: r.bytes, renderSeconds: Math.round((Date.now() - started) / 100) / 10, elements: r.elements, fonts: r.fonts,
+    success: true, outputPath, ...base, format: output.format, width: output.width, height: output.height,
+    ...(output.still ? moment : { durationSeconds: output.durationSeconds, fps: output.fps, frameCount: output.frameCount }),
+    validationErrors: [], bytes: r.bytes, renderSeconds: Math.round((Date.now() - started) / 100) / 10,
+    ...describe(r.summary), fonts: r.fonts, ...(r.blank ? { blank: true } : {}),
   };
   const fallback = (r.fonts ?? []).filter(f => !f.loaded).map(f => f.family);
+  const what = output.still
+    ? `${output.format.toUpperCase()}, ${output.width}×${output.height}${moment.timestampSeconds !== undefined ? `, the frame at ${moment.timestampSeconds}s` : ''}`
+    : `${output.format.toUpperCase()}, ${output.width}×${output.height}, ${output.durationSeconds}s at ${output.fps} fps (${output.frameCount} frames)`;
   return answer(id, result,
-    `Rendered ${outputPath} — ${output.format.toUpperCase()}, ${output.width}×${output.height}, ${output.durationSeconds}s at ${output.fps} fps (${output.frameCount} frames).`
+    `Rendered ${outputPath} — ${what}${say(r.summary)}`
+    + (r.blank ? ' That frame is empty (one flat colour): the animation shows nothing at that moment. Choose another timeSeconds.' : '')
     + (fallback.length ? ` These fonts did not load and fell back: ${fallback.join(', ')}.` : ''));
 }
 
+const renderNeonSign = (id, m, args) => renderFile(id, {
+  kind: 'neon', args, base: { animation: NEON_TEMPLATE }, formats: ['png', 'jpg', 'mp4', 'webm', 'gif'],
+  build: content => m.buildNeonScene(content),
+  name: built => `neon-${m.neonSceneSummary(built.scene).map(e => e.content).join('-').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 40) || 'sign'}`,
+  describe: summary => ({ elements: summary }),
+});
+
+/**
+ * The five templates, through their own players. A `neon-sign` request goes to the neon: the same
+ * file comes out whichever tool was called.
+ */
+function renderAnimation(id, m, args) {
+  const request = args?.request;
+  if (request?.template === NEON_TEMPLATE && request.content && typeof request.content === 'object') {
+    const output = Object.fromEntries(Object.entries(args).filter(([k]) => k !== 'request'));
+    return renderNeonSign(id, m, { ...request.content, ...output });
+  }
+  return renderFile(id, {
+    kind: 'animation', args, base: { animation: typeof request?.template === 'string' ? request.template : undefined }, formats: ['png', 'jpg', 'mp4', 'webm', 'gif'],
+    build: content => m.buildAnimationRender(content),
+    name: built => built.request.template,
+    describe: () => ({}),
+  });
+}
+
 /** The neon tool with its schema, read from the bundle; without the bundle, the tool as declared. */
 async function neonTool() {
-  try { return { ...RENDER_NEON, inputSchema: { ...(await componentsModule()).NEON_INPUT_SCHEMA, properties: { ...(await componentsModule()).NEON_INPUT_SCHEMA.properties, outputPath: { type: 'string', description: 'Where to save the video, absolute or relative to the working directory. Default comppack-renders/neon-<text>.<format>.' } } } }; } catch { return RENDER_NEON; }
+  try { return { ...RENDER_NEON, inputSchema: { ...(await componentsModule()).NEON_INPUT_SCHEMA, properties: { ...(await componentsModule()).NEON_INPUT_SCHEMA.properties, outputPath: { type: 'string', description: 'Where to save the image or video, absolute or relative to the working directory. Default comppack-renders/neon-<text>.<format>.' } } } }; } catch { return RENDER_NEON; }
 }
 
 const answer = (id, structured, text, isError = false) =>
@@ -826,11 +994,11 @@ const HANDLERS = {
   initialize: (id) => ok(id, {
     protocolVersion: PROTOCOL,
     capabilities: { tools: {}, resources: {}, completions: {} },
-    serverInfo: { name: 'comppack-ask', version: '0.1.2' },
+    serverInfo: { name: 'comppack-ask', version: VERSION },
   }),
   'notifications/initialized': () => {},
   ping: id => ok(id, {}),
-  'tools/list': async id => ok(id, { tools: [ASK, VALIDATE, ELICIT, SEARCH_COMPONENTS, DESCRIBE_COMPONENT, CHECK_RENDER_REQUEST, LIST_COMPONENTS, CHECK_COMPONENT_CONFIG, LIST_ANIMATIONS, DESCRIBE_ANIMATION, CHECK_ANIMATION_REQUEST, await neonTool()] }),
+  'tools/list': async id => ok(id, { tools: [ASK, VALIDATE, ELICIT, SEARCH_COMPONENTS, DESCRIBE_COMPONENT, CHECK_RENDER_REQUEST, LIST_COMPONENTS, CHECK_COMPONENT_CONFIG, LIST_ANIMATIONS, DESCRIBE_ANIMATION, CHECK_ANIMATION_REQUEST, await animationRenderTool(), await neonTool(), DESCRIBE_OBJECTS, CHECK_OBJECT, await objectRenderTool(), await surfaceRenderTool()] }),
   'tools/call': (id, params) => {
     const args = params?.arguments ?? {};
     if (params?.name === 'ask_user') return askUser(id, args);
@@ -838,6 +1006,7 @@ const HANDLERS = {
     if (params?.name === 'to_elicitation') return toElicitationTool(id, args);
     if (COMPONENT_TOOLS.includes(params?.name)) return componentTool(id, params.name, args);
     if (ANIMATION_TOOLS.includes(params?.name)) return animationTool(id, params.name, args);
+    if (OBJECT_TOOLS.includes(params?.name)) return objectTool(id, params.name, args);
     return fail(id, -32602, `Unknown tool: ${params?.name}`);
   },
   /* `file` is where the text lives on disk and is nobody's business over the wire — a resource

package/tools/ask/render.mjs

@@ -0,0 +1,248 @@
+/**
+ * **A render request as an image or video file.** `render_neon_sign`, `render_object`, `render_surface` and
+ * `render_animation` call this.
+ *
+ * What they draw is SVG with filters, WebGL or animated DOM, with web fonts, so a browser has to
+ * draw it — the same reason `ask_user` goes to one (`serve.mjs`). The shape is the same too: a
+ * one-shot loopback server, a token, a prebuilt page (`dist/render.js`, the package's own
+ * components) and the request in the document. The difference is who looks: a headless browser
+ * shows the page each moment and photographs it.
+ *
+ *   still   one page, one moment, one screenshot written straight to the output path
+ *   video   a few pages step through every frame; ffmpeg joins them
+ *
+ * ⚠ **Playwright and ffmpeg are found, not depended on.** The library takes five peers and no
+ * more, so neither can be a dependency of the package. Playwright is resolved from the project
+ * the server was launched in, then from the package; ffmpeg from `PATH`, and only a video needs
+ * it. When one is missing the tool says which and how to get it, and every other tool keeps working.
+ *
+ * No sleeps: the page's `ready` promise resolves when fonts, images and the first frame are in,
+ * and each frame's promise resolves after the browser has painted it.
+ */
+import { Buffer } from 'node:buffer';
+import { createServer } from 'node:http';
+import { createRequire } from 'node:module';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { inflateSync } from 'node:zlib';
+import { randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { cpus, tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/** A failure the caller can act on: reported in the tool's result, not as a protocol error. */
+export class RenderError extends Error {}
+
+async function chromiumFrom() {
+  for (const from of [join(process.cwd(), 'package.json'), import.meta.url]) {
+    const require = createRequire(from);
+    for (const name of ['playwright', 'playwright-core', '@playwright/test']) {
+      try {
+        const m = await import(pathToFileURL(require.resolve(name)).href);
+        const chromium = m.chromium ?? m.default?.chromium;
+        if (chromium) return chromium;
+      } catch { /* not here; try the next */ }
+    }
+  }
+  throw new RenderError(
+    'Rendering needs Playwright to draw the frames, and it is not installed in this project. '
+    + 'Run `npm install -D playwright && npx playwright install chromium`, then call again.',
+  );
+}
+
+/**
+ * How a WebGL scene gets a GL, in the order tried. The machine's own GPU first: measured on a
+ * newspaper page, 2.5 s for a still against 11 s, and 3 s for 90 frames against 92 s. Software GL
+ * second, so the same scene still draws on a machine with no GPU (a container, a CI runner).
+ */
+const GL = [
+  ['--ignore-gpu-blocklist', '--enable-gpu', '--use-gl=angle', ...(process.platform === 'darwin' ? ['--use-angle=metal'] : [])],
+  ['--use-gl=angle', '--use-angle=swiftshader', '--enable-unsafe-swiftshader', '--ignore-gpu-blocklist'],
+];
+
+async function launch(chromium, args) {
+  const options = args ? { args } : {};
+  try { return await chromium.launch(options); } catch (first) {
+    /* No downloaded browser: the machine's own Chrome draws the same page. */
+    try { return await chromium.launch({ ...options, channel: 'chrome' }); } catch {
+      throw new RenderError(`No browser to render with (${String(first.message).split('\n')[0]}). Run \`npx playwright install chromium\`, then call again.`);
+    }
+  }
+}
+
+const CODECS = {
+  /* JPEG frames are full-range; players expect video range, so convert rather than tag. */
+  mp4: ['-vf', 'scale=out_range=tv', '-c:v', 'libx264', '-pix_fmt', 'yuv420p', '-color_range', 'tv', '-crf', '16', '-preset', 'medium', '-movflags', '+faststart'],
+  webm: ['-vf', 'scale=out_range=tv', '-c:v', 'libvpx-vp9', '-pix_fmt', 'yuv420p', '-color_range', 'tv', '-crf', '28', '-b:v', '0'],
+  gif: ['-filter_complex', '[0:v]split[a][b];[a]palettegen=stats_mode=diff[p];[b][p]paletteuse=dither=bayer'],
+};
+
+/**
+ * **True when a PNG is one flat colour.** Some templates open a scene on an empty frame; a still
+ * taken there is a picture of nothing, and the file looks like a success. Reads the screenshot's
+ * own bytes (8-bit RGB or RGBA, as the browser writes them) and samples every eighth pixel.
+ */
+export function isBlankPng(png) {
+  let width = 0, height = 0, bpp = 0;
+  const idat = [];
+  for (let p = 8; p < png.length;) {
+    const length = png.readUInt32BE(p);
+    const type = png.toString('latin1', p + 4, p + 8);
+    const data = png.subarray(p + 8, p + 8 + length);
+    if (type === 'IHDR') {
+      width = data.readUInt32BE(0); height = data.readUInt32BE(4);
+      bpp = data[8] === 8 && data[12] === 0 ? (data[9] === 6 ? 4 : data[9] === 2 ? 3 : 0) : 0;
+      if (!bpp) return false;
+    } else if (type === 'IDAT') idat.push(data);
+    p += 12 + length;
+  }
+  if (!bpp) return false;
+  const raw = inflateSync(Buffer.concat(idat));
+  const stride = width * bpp;
+  let prev = Buffer.alloc(stride);
+  let first = null;
+  for (let y = 0; y < height; y++) {
+    const filter = raw[y * (stride + 1)];
+    const line = Buffer.from(raw.subarray(y * (stride + 1) + 1, (y + 1) * (stride + 1)));
+    for (let x = 0; x < stride; x++) {
+      const a = x >= bpp ? line[x - bpp] : 0;
+      const b = prev[x];
+      const c = x >= bpp ? prev[x - bpp] : 0;
+      let add = 0;
+      if (filter === 1) add = a;
+      else if (filter === 2) add = b;
+      else if (filter === 3) add = (a + b) >> 1;
+      else if (filter === 4) { const q = a + b - c; const qa = Math.abs(q - a); const qb = Math.abs(q - b); const qc = Math.abs(q - c); add = qa <= qb && qa <= qc ? a : qb <= qc ? b : c; }
+      line[x] = (line[x] + add) & 255;
+    }
+    if (y % 8 === 0) {
+      for (let x = 0; x < width; x += 8) {
+        const i = x * bpp;
+        if (!first) first = [line[i], line[i + 1], line[i + 2]];
+        else if (Math.abs(line[i] - first[0]) + Math.abs(line[i + 1] - first[1]) + Math.abs(line[i + 2] - first[2]) > 12) return false;
+      }
+    }
+    prev = line;
+  }
+  return true;
+}
+
+function encode(dir, output, outputPath) {
+  return new Promise((res, rej) => {
+    const ff = spawn('ffmpeg', ['-y', '-loglevel', 'error', '-framerate', String(output.fps), '-i', join(dir, 'f-%05d.jpg'), ...CODECS[output.format], outputPath], { stdio: ['ignore', 'ignore', 'pipe'] });
+    let err = '';
+    ff.stderr.on('data', (d) => { err += d; });
+    ff.on('error', (e) => rej(new RenderError(e.code === 'ENOENT'
+      ? 'A video needs ffmpeg to join the frames, and it is not on PATH. Install it (`brew install ffmpeg`, `apt install ffmpeg`), then call again. A png or jpg needs no ffmpeg.'
+      : `ffmpeg did not start: ${e.message}`)));
+    ff.on('exit', (code) => (code === 0 ? res() : rej(new RenderError(`ffmpeg failed (${code}): ${err.trim().split('\n').slice(-3).join(' ')}`))));
+  });
+}
+
+/**
+ * @param {{kind: 'neon' | 'object' | 'surface' | 'animation', content: object,
+ *          output: {format: string, still: boolean, width: number, height: number, fps: number, frameCount: number, timestampSeconds?: number},
+ *          outputPath: string, backgroundColor?: string}} job  `content` is the request; `output` is what its builder resolved from it.
+ * @returns {Promise<{errors: object[], summary?: unknown, fonts?: object[], bytes?: number, timestampSeconds?: number, blank?: boolean}>} `errors` are the page's validation errors.
+ */
+export async function render({ kind, content, output, outputPath, backgroundColor = 'black' }) {
+  let js;
+  try { js = readFileSync(resolve(here, 'dist/render.js'), 'utf8'); } catch {
+    throw new RenderError('The render page is missing (tools/ask/dist/render.js). In this repository run `npm run ask:build`; as an installed package, reinstall without --ignore-scripts.');
+  }
+  const chromium = await chromiumFrom();
+
+  const token = randomUUID();
+  const json = JSON.stringify({ kind, content, width: output.width }).replace(/</g, '\\u003c');
+  const html = '<!doctype html><html><head><meta charset="utf-8"><title>CompPack render</title>'
+    + `<style>html,body,#root{margin:0;width:100%;height:100%;overflow:hidden;background:${backgroundColor}}</style></head>`
+    + `<body><div id="root"></div><script id="comppack-render" type="application/json">${json}</script>`
+    + '<script type="module" src="/render.js"></script></body></html>';
+  const server = createServer((req, res) => {
+    /* A throw in a request listener takes the process down (see serve.mjs). */
+    let url;
+    try { url = new URL(req.url, 'http://127.0.0.1'); } catch { res.writeHead(400).end('bad request'); return; }
+    if (req.method === 'GET' && url.pathname === '/' && url.searchParams.get('t') === token) {
+      res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' }).end(html);
+    } else if (req.method === 'GET' && url.pathname === '/render.js' && req.headers.referer?.includes(token)) {
+      res.writeHead(200, { 'content-type': 'text/javascript; charset=utf-8' }).end(js);
+    } else res.writeHead(404).end();
+  });
+  server.on('clientError', (_e, socket) => socket.destroy());
+  const port = await new Promise((res, rej) => { server.once('error', rej); server.listen(0, '127.0.0.1', () => res(server.address().port)); });
+
+  const webgl = kind === 'object' || kind === 'surface';
+  try {
+    /* `COMPPACK_GL=software` skips the GPU: the same pixels on every machine, slowly. */
+    const attempts = !webgl ? [undefined] : process.env.COMPPACK_GL === 'software' ? GL.slice(-1) : GL;
+    for (const [attempt, args] of attempts.entries()) {
+      const last = attempt === attempts.length - 1;
+      try {
+        const r = await draw(args);
+        /* No GL from the GPU: the page says so, and the software one is tried. */
+        if (!last && r.errors.some((e) => /WebGL/i.test(e.message))) continue;
+        return r;
+      } catch (e) {
+        if (last || e instanceof RenderError) throw e;
+      }
+    }
+  } finally {
+    server.close();
+  }
+
+  async function draw(args) {
+  let dir;
+  let browser;
+  try {
+    browser = await launch(chromium, args);
+    const context = await browser.newContext({ viewport: { width: output.width, height: output.height }, deviceScaleFactor: 1 });
+    const open = async () => {
+      const page = await context.newPage();
+      await page.goto(`http://127.0.0.1:${port}/?t=${token}`);
+      return { page, ready: await page.evaluate(() => globalThis.__render.ready) };
+    };
+
+    /* The first page decides whether the request can be drawn at all, with real fonts measured. */
+    const first = await open();
+    if (first.ready.errors.length) return { errors: first.ready.errors };
+    mkdirSync(dirname(outputPath), { recursive: true });
+
+    if (output.still) {
+      /* The one frame, drawn directly: no video is made and none is cut. */
+      let at = output.timestampSeconds ?? 0;
+      let png;
+      let blank = false;
+      for (let tries = 0; ; tries++) {
+        await first.page.evaluate((ms) => globalThis.__render.frame(ms), at * 1000);
+        png = await first.page.screenshot({ type: 'png' });
+        blank = kind === 'animation' && isBlankPng(png);
+        /* A moment the request named is drawn as asked, empty or not. One this server chose moves on to the next frame that shows something. */
+        if (!blank || !output.timestampChosen || tries >= 16 || at + 0.2 > output.durationSeconds) break;
+        at = Math.round((at + 0.2) * 1000) / 1000;
+      }
+      if (output.format === 'png') writeFileSync(outputPath, png);
+      else await first.page.screenshot({ path: outputPath, type: 'jpeg', quality: 92 });
+      return { errors: [], summary: first.ready.summary, fonts: first.ready.fonts, bytes: statSync(outputPath).size, timestampSeconds: at, blank };
+    } else {
+      /* Frames are independent (each is a moment the page is asked for), so a few pages draw them side by side. */
+      dir = mkdtempSync(join(tmpdir(), 'comppack-render-'));
+      const workers = Math.max(1, Math.min(4, cpus().length - 1, Math.ceil(output.frameCount / 8)));
+      const pages = [first.page, ...(await Promise.all(Array.from({ length: workers - 1 }, open))).map((o) => o.page)];
+      let next = 0;
+      await Promise.all(pages.map(async (page) => {
+        for (let i = next++; i < output.frameCount; i = next++) {
+          await page.evaluate((ms) => globalThis.__render.frame(ms), (i * 1000) / output.fps);
+          await page.screenshot({ path: join(dir, `f-${String(i).padStart(5, '0')}.jpg`), type: 'jpeg', quality: 95 });
+        }
+      }));
+      await encode(dir, output, outputPath);
+    }
+    return { errors: [], summary: first.ready.summary, fonts: first.ready.fonts, bytes: statSync(outputPath).size };
+  } finally {
+    await browser?.close().catch(() => {});
+    if (dir) rmSync(dir, { recursive: true, force: true });
+  }
+  }
+}