@appinternalleads/ui 0.4.0 → 0.4.2

package/tools/ask/mcp.mjs

@@ -20,7 +20,7 @@
 import { createInterface } from 'node:readline';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { dirname, resolve } from 'node:path';
+import { dirname, extname, resolve } from 'node:path';
 import { spawn } from 'node:child_process';
 import { askInBrowser } from './serve.mjs';
 /* The blocking policy lives in its own file so a test can check every rule name against the
@@ -614,6 +614,169 @@ const CHECK_COMPONENT_CONFIG = {
 
 const COMPONENT_TOOLS = ['search_components', 'describe_component', 'check_render_request', 'list_components', 'check_component_config'];
 
+/* ── motion templates: animations authored once, filled with content ──────── */
+
+/**
+ * **Animations an agent fills, never writes.** A motion template (`@appinternalleads/ui/motion`) is
+ * authored once in Remotion; its timing, easing, layout and type are fixed. An agent sends
+ * `{ schema: "motion/1", template, content }` — text slots within their word limits, optional theme
+ * colours, optional scenes — and gets back either slot-level errors or a link that plays it.
+ */
+const LIST_ANIMATIONS = {
+  name: 'list_animations',
+  title: 'List the animation templates',
+  description:
+    'Every motion template: id, title, what it shows, canvas size and length. Animations are fixed; '
+    + 'you choose one and fill its content. Then call describe_animation.',
+  inputSchema: { type: 'object', properties: {} },
+};
+
+const DESCRIBE_ANIMATION = {
+  name: 'describe_animation',
+  title: 'The content contract of one animation',
+  description:
+    'For one template: every text slot with maxWords and maxChars (text wider than a slot is scaled '
+    + 'down automatically), the theme colour tokens with defaults (hex #rrggbb), which scenes are '
+    + 'optional (omit them or set null), what is NOT configurable, and a complete example request. '
+    + 'Sequence templates (e.g. word-motion) take a LIST of scenes instead: `sequence` '
+    + 'gives its length limits and each item\'s choices (enums such as layout, theme, transition), and '
+    + '`aspectRatio` the canvases (9:16, 16:9). To change words, change only `text`/`line2`; never invent motion. '
+    + 'Build a motion/1 request from it and check it with check_animation_request.',
+  inputSchema: {
+    type: 'object',
+    properties: { template: { type: 'string', description: 'A template id from list_animations, e.g. hey-template or word-motion.' } },
+    required: ['template'],
+  },
+};
+
+const CHECK_ANIMATION_REQUEST = {
+  name: 'check_animation_request',
+  title: 'Check an animation request and get a preview link',
+  description:
+    'Validate { schema: "motion/1", template, content }. Valid → { valid: true, seconds, previewUrl, previewFormat } '
+    + '(the link plays it live as HTML + CSS on the CompPack site; the same request renders to MP4 (H.264) with Remotion). '
+    + 'Invalid → { valid: false, errors: [{ path, message }] } — fix each slot and check again. Never '
+    + 'send timing, positions, fonts, CSS or markup: they are rejected.',
+  inputSchema: {
+    type: 'object',
+    properties: { request: { type: 'object', description: 'The motion/1 request.' } },
+    required: ['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`).
+ *
+ * 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
+ * arguments before it reads a contract: the request is discoverable from `tools/list` alone.
+ * `dist/components.mjs` holds the schema and the request → scene translation (`tools/ask/neon.ts`).
+ */
+const NEON_TEMPLATE = 'neon-sign';
+const RENDER_NEON = {
+  name: 'render_neon_sign',
+  title: 'Render a neon sign to 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 '
+    + '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'];
+const SITE_URL = process.env.COMPPACK_SITE_URL || 'https://comppack.vercel.app';
+
+async function animationTool(id, name, args) {
+  let m;
+  try { m = await componentsModule(); } catch (e) {
+    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 === 'list_animations') {
+    const list = [...m.listMotionTemplates(), m.listNeonAnimation()];
+    return answer(id, { animations: list }, JSON.stringify(list, null, 2));
+  }
+  if (name === 'describe_animation') {
+    if (args?.template === NEON_TEMPLATE) {
+      const neon = m.describeNeonAnimation();
+      return answer(id, neon, JSON.stringify(neon, null, 2));
+    }
+    const d = m.describeMotionTemplate(args?.template);
+    if (!d) return toolError(id, `No animation template called ${JSON.stringify(args?.template)}. Available: ${m.listMotionTemplates().map(t => t.template).join(', ')}, ${NEON_TEMPLATE}.`);
+    /* The JSON Schema is for validators; an agent reads the contract. */
+    const contract = { ...d };
+    delete contract.schema;
+    return answer(id, contract, JSON.stringify(contract, null, 2));
+  }
+  if (args?.request?.template === NEON_TEMPLATE) {
+    const n = m.validateNeonRequest(args.request);
+    if (!n.valid) return answer(id, n, `Not valid — ${n.errors.length} ${n.errors.length === 1 ? 'problem' : 'problems'}:\n${n.errors.map(e => `  ${e.path || '(request)'}: ${e.message}`).join('\n')}`, true);
+    return answer(id, n, `Valid — ${n.seconds}s of ${NEON_TEMPLATE}: ${n.elements.map(e => `${e.content} (${e.color})`).join(', ')}. Call render_neon_sign with the request's content to save it as ${n.output.format.toUpperCase()}.`);
+  }
+  const r = m.validateMotionRequest(args?.request);
+  if (!r.valid) {
+    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.`);
+}
+
+/**
+ * `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.
+ */
+async function renderNeonSign(id, m, args) {
+  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);
+
+  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);
+  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 started = Date.now();
+  let r;
+  try {
+    const { renderNeon } = await import('./neon-render.mjs');
+    r = await renderNeon({ 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);
+  }
+  if (r.errors.length) return refuse(r.errors);
+
+  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,
+  };
+  const fallback = (r.fonts ?? []).filter(f => !f.loaded).map(f => f.family);
+  return answer(id, result,
+    `Rendered ${outputPath} — ${output.format.toUpperCase()}, ${output.width}×${output.height}, ${output.durationSeconds}s at ${output.fps} fps (${output.frameCount} frames).`
+    + (fallback.length ? ` These fonts did not load and fell back: ${fallback.join(', ')}.` : ''));
+}
+
+/** 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; }
+}
+
 const answer = (id, structured, text, isError = false) =>
   ok(id, { content: [{ type: 'text', text }], structuredContent: structured, ...(isError ? { isError: true } : {}) });
 
@@ -667,13 +830,14 @@ const HANDLERS = {
   }),
   'notifications/initialized': () => {},
   ping: id => ok(id, {}),
-  'tools/list': id => ok(id, { tools: [ASK, VALIDATE, ELICIT, SEARCH_COMPONENTS, DESCRIBE_COMPONENT, CHECK_RENDER_REQUEST, LIST_COMPONENTS, CHECK_COMPONENT_CONFIG] }),
+  '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/call': (id, params) => {
     const args = params?.arguments ?? {};
     if (params?.name === 'ask_user') return askUser(id, args);
     if (params?.name === 'validate_question') return validateQuestion(id, args);
     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);
     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/neon-render.mjs

@@ -0,0 +1,143 @@
+/**
+ * **A neon request as a video file.** `render_neon_sign` calls this.
+ *
+ * The neon is an SVG with filters and 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/neon.js`, the package's `NeonCanvas`) and the request in the
+ * document. The difference is who looks: a headless browser steps the page through every frame,
+ * photographs each, and 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`. When one is missing the
+ * tool says which and how to get it, and every other tool of the server keeps working.
+ *
+ * No sleeps: the page's `ready` promise resolves when fonts, wall and the first frame are in,
+ * and each frame's promise resolves after the browser has painted it.
+ */
+import { createServer } from 'node:http';
+import { createRequire } from 'node:module';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs';
+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 NeonRenderError extends Error {}
+
+async function chromiumFrom() {
+  const tried = [];
+  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 (e) { tried.push(`${name}: ${e.code ?? e.message}`); }
+    }
+  }
+  throw new NeonRenderError(
+    '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.',
+  );
+}
+
+async function launch(chromium) {
+  try { return await chromium.launch(); } catch (first) {
+    /* No downloaded browser: the machine's own Chrome draws the same SVG. */
+    try { return await chromium.launch({ channel: 'chrome' }); } catch {
+      throw new NeonRenderError(`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'],
+};
+
+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 NeonRenderError(e.code === 'ENOENT'
+      ? 'Rendering needs ffmpeg to join the frames into a video, and it is not on PATH. Install it (`brew install ffmpeg`, `apt install ffmpeg`), then call again.'
+      : `ffmpeg did not start: ${e.message}`)));
+    ff.on('exit', (code) => (code === 0 ? res() : rej(new NeonRenderError(`ffmpeg failed (${code}): ${err.trim().split('\n').slice(-3).join(' ')}`))));
+  });
+}
+
+/**
+ * @param {{content: object, output: {format: string, width: number, height: number, durationSeconds: number, fps: number, frameCount: number},
+ *          outputPath: string, backgroundColor?: string}} job  `content` is the request; `output` is what `buildNeonScene` resolved from it.
+ * @returns {Promise<{errors: object[], elements?: object[], fonts?: object[], bytes?: number}>} `errors` are the page's validation errors.
+ */
+export async function renderNeon({ content, output, outputPath, backgroundColor = 'black' }) {
+  let js;
+  try { js = readFileSync(resolve(here, 'dist/neon.js'), 'utf8'); } catch {
+    throw new NeonRenderError('The neon render page is missing (tools/ask/dist/neon.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({ content }).replace(/</g, '\\u003c');
+  const html = '<!doctype html><html><head><meta charset="utf-8"><title>CompPack neon 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-neon" type="application/json">${json}</script>`
+    + '<script type="module" src="/neon.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 === '/neon.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 dir = mkdtempSync(join(tmpdir(), 'comppack-neon-'));
+  let browser;
+  try {
+    browser = await launch(chromium);
+    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.__neon.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 };
+
+    /* Frames are independent (the canvas is pure in time), so a few pages draw them side by side. */
+    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.__neon.frame(ms), (i * 1000) / output.fps);
+        await page.screenshot({ path: join(dir, `f-${String(i).padStart(5, '0')}.jpg`), type: 'jpeg', quality: 95 });
+      }
+    }));
+
+    mkdirSync(dirname(outputPath), { recursive: true });
+    await encode(dir, output, outputPath);
+    return { errors: [], elements: first.ready.elements, fonts: first.ready.fonts, bytes: statSync(outputPath).size };
+  } finally {
+    await browser?.close().catch(() => {});
+    server.close();
+    rmSync(dir, { recursive: true, force: true });
+  }
+}