mcplane 0.4.1 → 0.5.0

package/dist/report.js

@@ -1,25 +1,41 @@
 import { STORE_NAMES } from './types.js';
 const tty = process.stdout.isTTY;
 const c = (code, s) => (tty ? `\x1b[${code}m${s}\x1b[0m` : s);
-const MARK = { pass: c('32', '✓'), warn: c('33', '!'), fail: c('31', '✗'), skip: c('90', '-') };
-export function printPreflight(r, opts = {}) {
-    const fails = r.checks.filter((x) => x.level === 'fail');
-    const warns = r.checks.filter((x) => x.level === 'warn');
-    console.log(c('1', `Preflight for ${r.stores.map((s) => STORE_NAMES[s]).join(', ')}`));
-    console.log('');
-    for (const x of r.checks) {
-        if (x.level === 'pass' && !opts.verbose)
+const MARK = { pass: c('32', '✓'), warn: c('33', '!'), fail: c('31', '✗'), skip: c('90', '-'), info: c('36', 'i') };
+/** Readiness for the next MCP revision gets its own section, so it never reads as a store requirement. */
+const isReadiness = (x) => x.id.startsWith('readiness.');
+function printChecks(checks, verbose, indent = '') {
+    for (const x of checks) {
+        if (x.level === 'pass' && !verbose)
             continue;
         const where = x.stores?.length ? c('90', ` [${x.stores.map((s) => STORE_NAMES[s]).join(', ')}]`) : '';
-        console.log(`${MARK[x.level]} ${x.title}${where}`);
+        console.log(`${indent}${MARK[x.level]} ${x.title}${where}`);
         if (x.detail)
-            console.log(c('90', `    ${x.detail}`));
+            console.log(c('90', `${indent}    ${x.detail}`));
         if (x.fix && x.level !== 'pass')
-            console.log(`    ${x.fix}`);
+            console.log(`${indent}    ${x.fix}`);
     }
-    const passed = r.checks.length - fails.length - warns.length;
+}
+export function printPreflight(r, opts = {}) {
+    const fails = r.checks.filter((x) => x.level === 'fail');
+    const warns = r.checks.filter((x) => x.level === 'warn');
+    const notes = r.checks.filter((x) => x.level === 'info');
+    const main = r.checks.filter((x) => !isReadiness(x));
+    const ready = r.checks.filter(isReadiness);
+    console.log(c('1', `Preflight for ${r.stores.map((s) => STORE_NAMES[s]).join(', ')}`));
+    console.log('');
+    printChecks(main, opts.verbose);
+    const passed = main.filter((x) => x.level === 'pass').length;
     if (!opts.verbose && passed)
         console.log(c('32', `✓ ${passed} checks passed`) + c('90', ' (--verbose to list them)'));
+    if (ready.length) {
+        console.log('');
+        console.log(c('1', 'Readiness for MCP 2026-07-28') + c('90', ' (never blocking)'));
+        printChecks(ready, opts.verbose, '  ');
+        const ok = ready.filter((x) => x.level === 'pass').length;
+        if (!opts.verbose && ok)
+            console.log(`  ${c('32', `✓ ${ok} ready`)}`);
+    }
     if (r.reminders.length) {
         console.log('');
         console.log(c('1', 'Check these yourself'));
@@ -27,5 +43,6 @@ export function printPreflight(r, opts = {}) {
             console.log(`  • ${t}`);
     }
     console.log('');
-    console.log(fails.length ? c('31', `${fails.length} blocking, ${warns.length} to review.`) : warns.length ? c('33', `No blockers, ${warns.length} to review.`) : c('32', 'Ready to submit.'));
+    const noteLine = notes.length ? `, ${notes.length} note${notes.length === 1 ? '' : 's'}` : '';
+    console.log(fails.length ? c('31', `${fails.length} blocking, ${warns.length} to review${noteLine}.`) : warns.length ? c('33', `No blockers, ${warns.length} to review${noteLine}.`) : c('32', `Ready to submit${noteLine ? ` (${notes.length} note${notes.length === 1 ? '' : 's'})` : ''}.`));
 }

package/dist/skills.d.ts

@@ -0,0 +1,21 @@
+import type { ZipEntry } from './zip.js';
+export type FrontMatter = {
+    data: Record<string, unknown>;
+    body: string;
+} | {
+    error: string;
+};
+/**
+ * Reads SKILL.md front matter: the YAML a skill loader sees, for the subset skills use (plain,
+ * quoted and block scalars, nested maps and lists). A plain value holding ": " is an error, as in
+ * YAML itself, because strict loaders refuse the whole skill over it.
+ */
+export declare function frontMatter(raw: string): FrontMatter;
+export interface SkillBundle {
+    files: ZipEntry[];
+    names: string[];
+    problems: string[];
+    todo: string[];
+}
+/** Reads, checks and lays out skills for skills/<folder>/ in a plugin package. */
+export declare function bundleSkills(spec: string | string[] | undefined, dir: string, pluginName: string): Promise<SkillBundle>;

package/dist/skills.js

@@ -0,0 +1,180 @@
+/**
+ * Agent Skills for plugin packages: each skill is a folder with a SKILL.md, bundled under
+ * skills/<folder>/ with its scripts and references, executable bits kept. Checked against the
+ * Agent Skills spec (agentskills.io) and the skill rules in OpenAI's submission errors.
+ */
+import { lstat, readFile, readdir } from 'node:fs/promises';
+import { basename, join, relative, resolve, sep } from 'node:path';
+/** Front matter fields the Agent Skills spec defines. */
+const SPEC_FIELDS = new Set(['name', 'description', 'license', 'compatibility', 'metadata', 'allowed-tools']);
+const NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const DESCRIPTION_MAX = 1024;
+/** Noise and bulk that never belongs in a package. */
+const SKIPPED = new Set(['.DS_Store', 'Thumbs.db', 'node_modules', '.git']);
+function unquoteDouble(s) {
+    try {
+        return JSON.parse(s.replace(/\\'/g, "'").replace(/\\\n/g, ''));
+    }
+    catch {
+        return s.slice(1, -1);
+    }
+}
+/**
+ * Reads SKILL.md front matter: the YAML a skill loader sees, for the subset skills use (plain,
+ * quoted and block scalars, nested maps and lists). A plain value holding ": " is an error, as in
+ * YAML itself, because strict loaders refuse the whole skill over it.
+ */
+export function frontMatter(raw) {
+    const lines = raw.replace(/^/, '').replace(/\r\n/g, '\n').split('\n');
+    if (lines[0].trimEnd() !== '---')
+        return { error: 'SKILL.md must start with front matter between --- lines' };
+    const close = lines.findIndex((l, i) => i > 0 && /^(---|\.\.\.)\s*$/.test(l));
+    if (close < 0)
+        return { error: 'the front matter has no closing --- line' };
+    const fm = lines.slice(1, close);
+    const data = {};
+    for (let i = 0; i < fm.length; i++) {
+        const line = fm[i];
+        if (!line.trim() || /^\s*#/.test(line))
+            continue;
+        const m = /^([A-Za-z0-9_-]+)\s*:(?:[ \t]+(.*))?$/.exec(line);
+        if (!m)
+            return { error: `front matter line ${i + 2} isn't "key: value": ${line.trim().slice(0, 60)}` };
+        const key = m[1];
+        const value = (m[2] ?? '').trim();
+        const more = [];
+        while (i + 1 < fm.length && (fm[i + 1].trim() === '' || /^\s/.test(fm[i + 1])))
+            more.push(fm[++i]);
+        while (more.length && !more[more.length - 1].trim())
+            more.pop();
+        if (/^[|>][+-]?\d*(\s+#.*)?$/.test(value)) {
+            const indent = Math.min(...more.filter((l) => l.trim()).map((l) => l.length - l.trimStart().length));
+            const body = more.map((l) => l.slice(Number.isFinite(indent) ? indent : 0));
+            data[key] = value.startsWith('|') ? body.join('\n') : body.reduce((s, l) => (!l.trim() ? `${s}\n` : s && !s.endsWith('\n') ? `${s} ${l}` : `${s}${l}`), '');
+        }
+        else if (!value && more.length) {
+            const items = more.filter((l) => l.trim());
+            data[key] = items.every((l) => /^\s*-\s/.test(l))
+                ? items.map((l) => l.replace(/^\s*-\s+/, '').trim())
+                : Object.fromEntries(items.map((l) => /^\s*([^:]+):\s*(.*)$/.exec(l)).filter(Boolean).map((r) => [r[1].trim(), r[2].trim().replace(/^(["'])(.*)\1$/, '$2')]));
+        }
+        else if (value.startsWith('"')) {
+            data[key] = unquoteDouble([value, ...more.map((l) => l.trim())].join(' '));
+        }
+        else if (value.startsWith("'")) {
+            data[key] = [value, ...more.map((l) => l.trim())].join(' ').slice(1, -1).replace(/''/g, "'");
+        }
+        else {
+            const text = [value, ...more.map((l) => l.trim())].join(' ').replace(/\s+#.*$/, '');
+            if (/:\s/.test(text))
+                return { error: `"${key}" holds ": " without quotes, which YAML reads as a nested key; quote the value` };
+            data[key] = text;
+        }
+    }
+    return { data, body: lines.slice(close + 1).join('\n') };
+}
+async function walk(root, problems, skipped, at = root) {
+    const out = [];
+    for (const name of (await readdir(at)).sort()) {
+        const abs = join(at, name);
+        const inner = relative(root, abs).split(sep).join('/');
+        if (SKIPPED.has(name))
+            continue;
+        if (name.startsWith('.')) {
+            skipped.push(inner);
+            continue;
+        }
+        const st = await lstat(abs);
+        if (st.isSymbolicLink())
+            problems.push(`${basename(root)}/${inner} is a symbolic link; packages can't hold one (OpenAI ignores the skill). Copy the file in instead`);
+        else if (st.isDirectory())
+            out.push(...(await walk(root, problems, skipped, abs)));
+        else if (st.isFile())
+            out.push({ inner, abs, mode: st.mode & 0o111 ? 0o755 : 0o644 });
+    }
+    return out;
+}
+/** Skill folders from the manifest setting: one folder of skills, or a list of skill folders. Null when the folder isn't there. */
+async function skillDirs(spec, dir) {
+    if (Array.isArray(spec))
+        return spec.map((p) => resolve(dir, p));
+    const parent = resolve(dir, spec);
+    const names = await readdir(parent).catch(() => null);
+    if (!names)
+        return null;
+    const dirs = [];
+    for (const n of names.sort())
+        if (!n.startsWith('.') && !SKIPPED.has(n) && (await lstat(join(parent, n))).isDirectory())
+            dirs.push(join(parent, n));
+    return dirs;
+}
+/** Reads, checks and lays out skills for skills/<folder>/ in a plugin package. */
+export async function bundleSkills(spec, dir, pluginName) {
+    const out = { files: [], names: [], problems: [], todo: [] };
+    if (spec === undefined)
+        return out;
+    const dirs = await skillDirs(spec, dir);
+    if (!dirs) {
+        out.problems.push(`chatgpt.skills: ${spec} isn't a folder (paths are relative to mcplane.json)`);
+        return out;
+    }
+    if (!dirs.length && typeof spec === 'string')
+        out.todo.push(`chatgpt.skills: ${spec} holds no skill folders, so the package has no skills.`);
+    const seen = new Map();
+    for (const root of dirs) {
+        const folder = basename(root);
+        const where = `skills/${folder}`;
+        const st = await lstat(root).catch(() => null);
+        if (!st?.isDirectory()) {
+            out.problems.push(`${where}: ${relative(dir, root) || root} isn't a folder`);
+            continue;
+        }
+        const skipped = [];
+        const found = await walk(root, out.problems, skipped);
+        if (skipped.length)
+            out.todo.push(`Left out of ${where}: ${skipped.join(', ')} (hidden files never go in the package).`);
+        const md = found.find((f) => f.inner === 'SKILL.md');
+        if (!md) {
+            out.problems.push(`${where} has no SKILL.md`);
+            continue;
+        }
+        const raw = await readFile(md.abs, 'utf8');
+        const fm = frontMatter(raw);
+        if ('error' in fm) {
+            out.problems.push(`${where}/SKILL.md: ${fm.error}`);
+            continue;
+        }
+        const { name, description } = fm.data;
+        if (typeof name !== 'string' || !name.trim())
+            out.problems.push(`${where}/SKILL.md: "name" is required`);
+        else {
+            if (!NAME.test(name) || name.length > 64)
+                out.problems.push(`${where}/SKILL.md: name "${name}" must be lowercase letters, digits and single hyphens, at most 64 characters`);
+            if (name !== folder)
+                out.problems.push(`${where}/SKILL.md: name "${name}" doesn't match its folder "${folder}"; the Agent Skills spec requires a match, and strict clients skip the skill`);
+            if (`${pluginName}:${name}`.length > 64)
+                out.problems.push(`${where}: "${pluginName}:${name}" is over 64 characters, OpenAI's limit for a skill's full name`);
+            if (seen.has(name))
+                out.problems.push(`${where}: the name "${name}" is also used by ${seen.get(name)}`);
+            seen.set(name, where);
+            out.names.push(name);
+        }
+        if (typeof description !== 'string' || !description.trim())
+            out.problems.push(`${where}/SKILL.md: "description" is required`);
+        else if (description.trim().length > DESCRIPTION_MAX)
+            out.problems.push(`${where}/SKILL.md: the description is ${description.trim().length} characters; the limit is ${DESCRIPTION_MAX}`);
+        if (!fm.body.trim())
+            out.problems.push(`${where}/SKILL.md has no instructions after the front matter`);
+        const extra = Object.keys(fm.data).filter((k) => !SPEC_FIELDS.has(k));
+        if (extra.length)
+            out.todo.push(`${where}/SKILL.md: ${extra.map((k) => `"${k}"`).join(', ')} ${extra.length === 1 ? "isn't" : "aren't"} in the Agent Skills spec. OpenAI ignores unknown fields, but strict clients may refuse the skill.`);
+        const own = new Set(found.map((f) => f.inner));
+        for (const ref of new Set([...raw.matchAll(/\bscripts\/[A-Za-z0-9._/-]*[A-Za-z0-9_-]/g)].map((r) => r[0]))) {
+            if (!own.has(ref))
+                out.problems.push(`${where}/SKILL.md refers to ${ref}, which isn't in the skill's folder. Installed on its own, the skill can't run it`);
+        }
+        for (const f of found)
+            out.files.push({ path: `${where}/${f.inner}`, data: await readFile(f.abs), mode: f.mode });
+    }
+    return out;
+}

package/dist/submissions.js

@@ -17,6 +17,7 @@ const RT_SLUG = {
     'claude-plugins': 'claude-plugins',
     cursor: 'cursor',
     muse: 'muse',
+    'vercel-connect': 'vercel-connect',
 };
 const TRACKED_FROM_GITHUB = ['grok', 'docker'];
 export async function load(dir = process.cwd()) {
@@ -36,7 +37,7 @@ const today = () => new Date().toISOString().slice(0, 10);
 function listingRef(m, store, appId) {
     if (store === 'chatgpt')
         return appId;
-    if (store === 'claude-connectors' || store === 'muse')
+    if (store === 'claude-connectors' || store === 'muse' || store === 'vercel-connect')
         return m.server.url;
     if (store === 'claude-plugins' || store === 'cursor')
         return m.repository;

package/dist/types.d.ts

@@ -1,4 +1,5 @@
-export type Level = 'pass' | 'warn' | 'fail' | 'skip';
+/** info: optional or advisory. It never blocks and isn't counted as something to review. */
+export type Level = 'pass' | 'warn' | 'fail' | 'skip' | 'info';
 export interface Check {
     id: string;
     level: Level;
@@ -10,7 +11,7 @@ export interface Check {
     /** The stores this matters for; empty means all. */
     stores?: StoreId[];
 }
-export type StoreId = 'mcp-registry' | 'chatgpt' | 'claude-connectors' | 'claude-plugins' | 'cursor' | 'grok' | 'docker' | 'muse' | 'smithery' | 'glama' | 'cline' | 'lobehub' | 'awesome-mcp-servers' | 'awesome-remote-mcp-servers';
+export type StoreId = 'mcp-registry' | 'chatgpt' | 'claude-connectors' | 'claude-plugins' | 'cursor' | 'grok' | 'docker' | 'muse' | 'smithery' | 'glama' | 'cline' | 'lobehub' | 'awesome-mcp-servers' | 'awesome-remote-mcp-servers' | 'vercel-connect';
 export declare const STORE_NAMES: Record<StoreId, string>;
 export interface Manifest {
     $schema?: string;
@@ -23,6 +24,11 @@ export interface Manifest {
     server: {
         url: string;
         auth?: 'none' | 'oauth';
+        /**
+         * Sign-in pages and identity-provider URLs your consent screen sends people to (e.g. https://accounts.example.com/sign-in).
+         * Preflight GETs them with the authorization endpoint to find bot challenges and 403s reviewers would hit.
+         */
+        signIn?: string[];
     };
     repository?: string;
     author?: {
@@ -36,6 +42,7 @@ export interface Manifest {
         terms?: string;
         docs?: string;
     };
+    /** A direct image URL. The ChatGPT package also takes a local path, relative to mcplane.json. */
     icon?: string;
     prompts?: string[];
     stores?: StoreId[];
@@ -54,7 +61,10 @@ export interface Manifest {
             prompt: string;
         }[];
     };
-    /** Hand-written ChatGPT hint justifications, per tool; they replace mcplane's drafts. */
+    /**
+     * @deprecated OpenAI no longer asks for hint justifications. Still accepted: the ChatGPT pack lists them
+     * as optional notes for an appeal if review flags a hint.
+     */
     justifications?: Record<string, {
         readOnly?: string;
         openWorld?: string;
@@ -77,9 +87,15 @@ export interface Manifest {
         /** #RRGGBB with 2:1 contrast against white; the dark one against #212121. */
         brandColor?: string;
         brandColorDark?: string;
-        /** Direct image URLs; default to "icon". */
+        /** Image URLs or local paths (relative to mcplane.json), bundled into the package. logo and composerIcon default to "icon". */
+        logo?: string;
         composerIcon?: string;
         logoDark?: string;
+        /**
+         * Agent Skills to bundle under skills/ in the package: a folder whose subfolders each hold a SKILL.md,
+         * or a list of skill folders. Paths are relative to mcplane.json.
+         */
+        skills?: string | string[];
         /** Reviewer-accessible video URL showing the main use cases (required for review). */
         demoVideo?: string;
         commerce?: boolean;
@@ -100,6 +116,23 @@ export interface Manifest {
         keywords?: string[];
         domains?: string[];
     };
+    /** Vercel Connect's Submit a Service form fields with no shared equivalent. */
+    vercelConnect?: {
+        /** Base URL of a REST API your users also call, listed as a second target. */
+        apiBase?: string;
+        /** Default scopes for the OAuth method. Defaults to the discovery document's scopes_supported. */
+        scopes?: string[];
+        /** Offer an API key connection method: where users create a key, and the header it's sent in. */
+        apiKey?: {
+            docs?: string;
+            header?: string;
+        };
+    };
+    /** The Claude Code plugin that ships this server, for "mcplane pack claude-eval". Read from the plugin repo when left out. */
+    claudePlugin?: {
+        name?: string;
+        server?: string;
+    };
     /** Named workflows, run with "mcplane <lane>": each step is a command line without "mcplane". */
     lanes?: Record<string, string[]>;
     /** How reviewers get in, for servers behind sign-in. Never put the password here; say where it lives. */

package/dist/types.js

@@ -13,4 +13,5 @@ export const STORE_NAMES = {
     lobehub: 'LobeHub Market',
     'awesome-mcp-servers': 'awesome-mcp-servers',
     'awesome-remote-mcp-servers': 'awesome-remote-mcp-servers',
+    'vercel-connect': 'Vercel Connect',
 };

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.4.1";
+export declare const VERSION = "0.5.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.4.1';
+export const VERSION = '0.5.0';

package/dist/video.d.ts

@@ -0,0 +1,58 @@
+/** One screencast frame: a JPEG relative to the work folder, and when it was shown (seconds). */
+export interface Frame {
+    file: string;
+    ts: number;
+}
+export interface Scene {
+    caption: string;
+    frames: Frame[];
+    /** When recording stopped; the last frame is held until then. */
+    end: number;
+}
+/** ffmpeg's concat-demuxer list: each frame held until the next one, the last until `end`. */
+export declare function concatList(frames: Frame[], end: number): string;
+/** How long a scene runs once assembled. */
+export declare function sceneSeconds(s: Scene): number;
+/**
+ * Escapes a value for a filter option inside an ffmpeg filtergraph. Two levels:
+ * the option value (\ ' :) and then the filtergraph itself (\ ' [ ] , ;).
+ */
+export declare function ffEscape(value: string): string;
+/**
+ * A caption as at most `maxLines` lines of about `width` characters. Control
+ * characters become spaces (drawtext would draw them as boxes); anything that
+ * doesn't fit ends in an ellipsis.
+ */
+export declare function wrapCaption(text: string, width?: number, maxLines?: number): string[];
+/** Width and height from a JPEG's start-of-frame marker. */
+export declare function jpegSize(b: Uint8Array): {
+    width: number;
+    height: number;
+} | null;
+/** Even dimensions (H.264 needs them) within the maximum, keeping the aspect ratio. */
+export declare function outputSize(width: number, height: number, maxWidth?: number, maxHeight?: number): {
+    width: number;
+    height: number;
+};
+export declare function findFfmpeg(path?: string): string | null;
+/** Text colours that read on a background, given as 0xRRGGBB: light on dark, dark on light. */
+export declare function inkFor(bg: string): {
+    text: string;
+    muted: string;
+};
+/**
+ * Builds the video in `work` (where the frames are) and writes it to `out`.
+ * Every part is encoded the same way so they join without re-encoding.
+ */
+export declare function buildVideo(o: {
+    scenes: Scene[];
+    title: string;
+    subtitle?: string;
+    out: string;
+    work: string;
+    ffmpeg: string;
+    size: {
+        width: number;
+        height: number;
+    };
+}): Promise<number>;

package/dist/video.js

@@ -0,0 +1,190 @@
+/**
+ * Recorded scenes to one mp4 with ffmpeg: a title card, then each scene at real
+ * speed with its caption burned in. A DevTools screencast only sends a frame when
+ * something on screen changes, so each frame is held until the next one arrives
+ * (ffmpeg's concat demuxer with a duration per frame).
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { delimiter, join, resolve } from 'node:path';
+const FPS = 30;
+const DARK = '0x16181d';
+const TITLE_SECONDS = 3;
+const FONTS = ['/System/Library/Fonts/SFNS.ttf', '/System/Library/Fonts/Helvetica.ttc', '/Library/Fonts/Arial Unicode.ttf'];
+/** ffmpeg's concat-demuxer list: each frame held until the next one, the last until `end`. */
+export function concatList(frames, end) {
+    if (!frames.length)
+        throw new Error('No frames were recorded for this scene.');
+    const sorted = [...frames].sort((a, b) => a.ts - b.ts);
+    const entry = (f) => `file '${f.file.replace(/'/g, "'\\''")}'`;
+    const lines = [];
+    sorted.forEach((f, i) => {
+        const until = i + 1 < sorted.length ? sorted[i + 1].ts : Math.max(end, f.ts + 1 / FPS);
+        lines.push(entry(f), `duration ${Math.max(0.001, until - f.ts).toFixed(3)}`);
+    });
+    // The demuxer ignores the last entry's duration, so the last frame is listed once more.
+    lines.push(entry(sorted[sorted.length - 1]));
+    return `${lines.join('\n')}\n`;
+}
+/** How long a scene runs once assembled. */
+export function sceneSeconds(s) {
+    if (!s.frames.length)
+        return 0;
+    return Math.max(s.end, Math.max(...s.frames.map((f) => f.ts))) - Math.min(...s.frames.map((f) => f.ts));
+}
+/**
+ * Escapes a value for a filter option inside an ffmpeg filtergraph. Two levels:
+ * the option value (\ ' :) and then the filtergraph itself (\ ' [ ] , ;).
+ */
+export function ffEscape(value) {
+    const option = value.replace(/[\\':]/g, (c) => `\\${c}`);
+    return option.replace(/[\\'[\],;]/g, (c) => `\\${c}`);
+}
+/**
+ * A caption as at most `maxLines` lines of about `width` characters. Control
+ * characters become spaces (drawtext would draw them as boxes); anything that
+ * doesn't fit ends in an ellipsis.
+ */
+export function wrapCaption(text, width = 64, maxLines = 2) {
+    const words = text.replace(/[\u0000-\u001f\u007f]+/g, ' ').trim().split(/\s+/).filter(Boolean);
+    const lines = [];
+    for (const w of words) {
+        const last = lines[lines.length - 1];
+        if (last !== undefined && `${last} ${w}`.length <= width)
+            lines[lines.length - 1] = `${last} ${w}`;
+        else
+            lines.push(w);
+    }
+    if (lines.length <= maxLines)
+        return lines;
+    const kept = lines.slice(0, maxLines);
+    let tail = kept[maxLines - 1];
+    while (tail.length > width - 1 && tail.includes(' '))
+        tail = tail.slice(0, tail.lastIndexOf(' '));
+    kept[maxLines - 1] = `${tail.replace(/[\s,;:.]+$/, '')}…`;
+    return kept;
+}
+/** Width and height from a JPEG's start-of-frame marker. */
+export function jpegSize(b) {
+    if (b.length < 4 || b[0] !== 0xff || b[1] !== 0xd8)
+        return null;
+    let i = 2;
+    while (i + 8 < b.length) {
+        if (b[i] !== 0xff) {
+            i++;
+            continue;
+        }
+        const marker = b[i + 1];
+        if (marker === 0xff) {
+            i++;
+            continue;
+        }
+        if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd8)) {
+            i += 2;
+            continue;
+        }
+        if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+            return { height: (b[i + 5] << 8) | b[i + 6], width: (b[i + 7] << 8) | b[i + 8] };
+        }
+        i += 2 + ((b[i + 2] << 8) | b[i + 3]);
+    }
+    return null;
+}
+/** Even dimensions (H.264 needs them) within the maximum, keeping the aspect ratio. */
+export function outputSize(width, height, maxWidth = 1920, maxHeight = 1200) {
+    const s = Math.min(1, maxWidth / width, maxHeight / height);
+    const even = (n) => Math.max(2, Math.floor((n * s) / 2) * 2);
+    return { width: even(width), height: even(height) };
+}
+export function findFfmpeg(path = process.env.PATH ?? '') {
+    for (const dir of [...path.split(delimiter), '/opt/homebrew/bin', '/usr/local/bin']) {
+        if (dir && existsSync(join(dir, 'ffmpeg')))
+            return join(dir, 'ffmpeg');
+    }
+    return null;
+}
+/** A drawtext filter reading its text from a file, so no caption needs filtergraph escaping. */
+function drawtext(o) {
+    return [`drawtext=fontfile=${ffEscape(o.font)}`, `textfile=${ffEscape(o.textfile)}`, 'expansion=none', `fontsize=${o.size}`, `fontcolor=${o.color}`, 'x=(w-tw)/2', `y=${o.y}`].join(':');
+}
+/** Text colours that read on a background, given as 0xRRGGBB: light on dark, dark on light. */
+export function inkFor(bg) {
+    const n = parseInt(bg.replace(/^(0x|#)/, ''), 16);
+    const [r, g, b] = [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+    const light = 0.2126 * r + 0.7152 * g + 0.0722 * b > 140;
+    return light ? { text: '0x1d1d1f', muted: '0x5f6673' } : { text: 'white', muted: '0x9aa3b2' };
+}
+/** The app's background colour, from a frame's bottom-left corner, so the borders and caption band blend in. */
+function sampleBackground(ffmpeg, file, cwd) {
+    return new Promise((done) => {
+        const p = spawn(ffmpeg, ['-v', 'error', '-i', file, '-vf', 'format=rgb24,crop=1:1:4:ih-5', '-frames:v', '1', '-f', 'rawvideo', 'pipe:1'], { cwd, stdio: ['ignore', 'pipe', 'ignore'] });
+        const chunks = [];
+        p.stdout.on('data', (d) => chunks.push(d));
+        p.on('error', () => done(null));
+        p.on('close', (code) => {
+            const px = Buffer.concat(chunks);
+            done(code === 0 && px.length >= 3 ? `0x${[px[0], px[1], px[2]].map((v) => v.toString(16).padStart(2, '0')).join('')}` : null);
+        });
+    });
+}
+function run(cmd, args, cwd) {
+    return new Promise((done, fail) => {
+        const p = spawn(cmd, args, { cwd, stdio: ['ignore', 'ignore', 'pipe'] });
+        let err = '';
+        p.stderr.on('data', (d) => (err += d));
+        p.on('error', fail);
+        p.on('close', (code) => (code === 0 ? done() : fail(new Error(`ffmpeg failed: ${err.trim().split('\n').slice(-3).join(' ')}`))));
+    });
+}
+/**
+ * Builds the video in `work` (where the frames are) and writes it to `out`.
+ * Every part is encoded the same way so they join without re-encoding.
+ */
+export async function buildVideo(o) {
+    const { width: W, height: H } = o.size;
+    const k = H / 1200;
+    const font = FONTS.find((f) => existsSync(f));
+    if (!font)
+        throw new Error(`No font for captions; looked for ${FONTS.join(', ')}`);
+    const enc = ['-an', '-c:v', 'libx264', '-preset', 'medium', '-crf', '18', '-pix_fmt', 'yuv420p', '-r', String(FPS), '-video_track_timescale', '15360'];
+    const parts = [];
+    const first = o.scenes.find((s) => s.frames.length)?.frames[0];
+    const bg = (first && (await sampleBackground(o.ffmpeg, first.file, o.work))) ?? DARK;
+    const ink = inkFor(bg);
+    // Title card: the name large, one line of what it does underneath.
+    await writeFile(join(o.work, 'title.txt'), o.title);
+    const sub = o.subtitle ? wrapCaption(o.subtitle, 70) : [];
+    for (const [i, line] of sub.entries())
+        await writeFile(join(o.work, `title-${i}.txt`), line);
+    const titleSize = Math.round(76 * k);
+    const subSize = Math.round(38 * k);
+    const titleY = sub.length ? `(h/2)-th-${Math.round(24 * k)}` : '(h-th)/2';
+    const titleFilters = [
+        drawtext({ textfile: 'title.txt', font, size: titleSize, color: ink.text, y: titleY }),
+        ...sub.map((_, i) => drawtext({ textfile: `title-${i}.txt`, font, size: subSize, color: ink.muted, y: `(h/2)+${Math.round((24 + i * 54) * k)}` })),
+        'format=yuv420p',
+    ];
+    await run(o.ffmpeg, ['-y', '-v', 'error', '-f', 'lavfi', '-i', `color=c=${bg}:s=${W}x${H}:r=${FPS}:d=${TITLE_SECONDS}`, '-vf', titleFilters.join(','), ...enc, 'part-title.mp4'], o.work);
+    parts.push('part-title.mp4');
+    // Scenes: the window at real speed above a band that holds the caption, so it never covers the app.
+    const band = Math.round((136 * k) / 2) * 2;
+    const capSize = Math.round(38 * k);
+    const lineH = Math.round(50 * k);
+    for (const [i, s] of o.scenes.entries()) {
+        await writeFile(join(o.work, `scene-${i}.txt`), concatList(s.frames, s.end));
+        const lines = wrapCaption(s.caption, 80);
+        const filters = [`scale=${W}:${H - band}:force_original_aspect_ratio=decrease:flags=lanczos`, `pad=${W}:${H}:(ow-iw)/2:0:color=${bg}`, `fps=${FPS}`];
+        const top = H - band + Math.round((band - lines.length * lineH) / 2);
+        for (const [j, line] of lines.entries()) {
+            await writeFile(join(o.work, `caption-${i}-${j}.txt`), line);
+            filters.push(drawtext({ textfile: `caption-${i}-${j}.txt`, font, size: capSize, color: ink.text, y: `${top + j * lineH}+(${lineH}-th)/2` }));
+        }
+        filters.push('format=yuv420p');
+        await run(o.ffmpeg, ['-y', '-v', 'error', '-f', 'concat', '-safe', '0', '-i', `scene-${i}.txt`, '-vf', filters.join(','), ...enc, `part-${i}.mp4`], o.work);
+        parts.push(`part-${i}.mp4`);
+    }
+    await writeFile(join(o.work, 'parts.txt'), parts.map((p) => `file '${p}'`).join('\n') + '\n');
+    await run(o.ffmpeg, ['-y', '-v', 'error', '-f', 'concat', '-safe', '0', '-i', 'parts.txt', '-c', 'copy', '-movflags', '+faststart', resolve(o.out)], o.work);
+    return TITLE_SECONDS + o.scenes.reduce((n, s) => n + sceneSeconds(s), 0);
+}

package/dist/zip.d.ts

@@ -1,4 +1,18 @@
-export declare function zip(files: {
+/** 1980-01-01 00:00 in DOS format: (year - 1980) << 9 | month << 5 | day. */
+export declare const DOS_DATE: number;
+export interface ZipEntry {
     path: string;
     data: Uint8Array | string;
-}[]): Uint8Array;
+    /** Unix permission bits; 0o644 unless given. Use 0o755 for scripts. */
+    mode?: number;
+}
+export declare function zip(files: ZipEntry[]): Uint8Array;
+export interface UnzippedEntry {
+    path: string;
+    data: Uint8Array;
+    /** Unix permission bits, when the archive was made on Unix. */
+    mode: number | null;
+    dosDate: number;
+}
+/** Reads every entry from the central directory, inflating and checking each CRC. */
+export declare function unzip(buf: Uint8Array): UnzippedEntry[];