reelkit-cli 0.5.0 → 0.8.0

package/src/render/validate.ts

@@ -7,157 +7,10 @@ export const PKG_ROOT = fileURLToPath(new URL("../..", import.meta.url));
 export const KIT_INDEX = join(PKG_ROOT, "src", "remotion", "kit", "index.ts");
 export const ROOT_FILE = join(PKG_ROOT, "src", "remotion", "Root.tsx");
 
-export const MAIN_FILE = "Video.tsx";
-export const FILE_NAME = /^[A-Z][A-Za-z0-9]*\.tsx$/;
-export const componentName = (file: string) => file.replace(/\.tsx$/, "");
+// The static check lives in its own module, which a server can bundle; everything it exports is available from here as before.
+export { FILE_NAME, MAIN_FILE, componentName, importSpecifiers, staticCheck } from "./static-check";
+import { KIT, sourceFile, unwrap } from "./static-check";
 
-const KIT = "reelkit/kit";
-const BASE_IMPORTS = new Set(["react", "remotion", KIT]);
-
-// This check keeps honest compositions deterministic and self-contained. It is NOT a security boundary:
-// code in src/ runs on the user's machine when it is bundled and rendered, and anyone determined can get around a list of names.
-// It looks at the code (the TypeScript syntax tree), never at text, so words in on-screen copy, strings and comments are not flagged.
-// Only a reference to the global counts: `style.process`, `{ fetch: 1 }`, and a name the file declares itself (a component called
-// `Worker`, a parameter called `window`) are fine. Scope comes from the TypeScript binder, so a declaration only covers where it is in scope.
-const FORBIDDEN_NAMES: Record<string, string> = {
-  require: "require()", eval: "eval()", fetch: "fetch()",
-  process: "process", globalThis: "globalThis", window: "window", self: "self",
-  XMLHttpRequest: "XMLHttpRequest", WebSocket: "WebSocket", EventSource: "EventSource",
-  navigator: "navigator", localStorage: "localStorage", sessionStorage: "sessionStorage", indexedDB: "indexedDB",
-  Function: "Function", Worker: "Worker", SharedWorker: "SharedWorker", importScripts: "importScripts", child_process: "child_process",
-};
-
-const sourceFile = (source: string, file = "Video.tsx") => ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
-
-// True when this identifier names a property, a label or a JSX attribute rather than referring to a variable.
-function isNamePosition(node: ts.Identifier): boolean {
-  const p = node.parent;
-  if (!p) return false;
-  if ((ts.isPropertyAccessExpression(p) || ts.isQualifiedName(p)) && (ts.isQualifiedName(p) ? p.right : p.name) === node) return true;
-  if ((ts.isPropertyAssignment(p) || ts.isPropertyDeclaration(p) || ts.isPropertySignature(p) || ts.isMethodDeclaration(p) || ts.isMethodSignature(p)
-    || ts.isGetAccessorDeclaration(p) || ts.isSetAccessorDeclaration(p) || ts.isEnumMember(p) || ts.isJsxAttribute(p)) && p.name === node) return true;
-  if (ts.isBindingElement(p) && p.propertyName === node) return true;
-  if ((ts.isImportSpecifier(p) || ts.isExportSpecifier(p)) && p.propertyName === node) return true;
-  if ((ts.isLabeledStatement(p) || ts.isBreakOrContinueStatement(p)) && p.label === node) return true;
-  return false;
-}
-
-// Looks through the wrappers that do not change what an expression is: (x), x as T, x!, x satisfies T, <T>x.
-function unwrap(e: ts.Expression): ts.Expression {
-  while (ts.isParenthesizedExpression(e) || ts.isAsExpression(e) || ts.isNonNullExpression(e) || ts.isSatisfiesExpression(e) || ts.isTypeAssertionExpression(e)) e = e.expression;
-  return e;
-}
-
-// A one-file program with no libraries: a name the file declares has a symbol with a declaration in it; a global has none.
-function declaredHere(sf: ts.SourceFile): (id: ts.Identifier) => boolean {
-  const host: ts.CompilerHost = {
-    getSourceFile: (name) => (name === sf.fileName ? sf : undefined),
-    getDefaultLibFileName: () => "lib.d.ts", writeFile: () => {}, getCurrentDirectory: () => "", getCanonicalFileName: (f) => f,
-    useCaseSensitiveFileNames: () => true, getNewLine: () => "\n", fileExists: (f) => f === sf.fileName, readFile: () => undefined, getDirectories: () => [],
-  };
-  const program = ts.createProgram([sf.fileName], { noLib: true, noResolve: true, jsx: ts.JsxEmit.Preserve, target: ts.ScriptTarget.Latest }, host);
-  const checker = program.getTypeChecker();
-  return (id) => {
-    const p = id.parent;
-    const symbol = p && ts.isShorthandPropertyAssignment(p) && p.name === id ? checker.getShorthandAssignmentValueSymbol(p) : checker.getSymbolAtLocation(id);
-    return Boolean(symbol?.declarations?.some((d) => d.getSourceFile() === sf));
-  };
-}
-
-const textOf = (n: ts.Node | undefined) => (n && (ts.isStringLiteralLike(n)) ? n.text : undefined);
-
-type Finding = { specifiers: string[]; forbidden: string[] };
-
-function inspectSource(source: string, file?: string): Finding {
-  const specifiers: string[] = [];
-  const forbidden = new Set<string>();
-  const add = (s: string | undefined) => { if (s !== undefined) specifiers.push(s); };
-
-  const sf = sourceFile(source, file);
-  const declared = declaredHere(sf);
-  // True when the expression is the global with this name, not a variable the file declares.
-  const isGlobal = (e: ts.Expression | undefined, name: string) => {
-    const x = e && unwrap(e);
-    return Boolean(x && ts.isIdentifier(x) && x.text === name && !declared(x));
-  };
-  const flagMember = (object: ts.Expression | undefined, member: string | undefined) => {
-    if (isGlobal(object, "Math") && member === "random") forbidden.add("Math.random (use random(seed) from remotion)");
-    if (isGlobal(object, "Date") && member === "now") forbidden.add("the clock (Date)");
-  };
-  // The key a destructuring element reads: `random` in `{ random }` and in `{ random: r }`, "random" in `{ ["random"]: r }`.
-  const keyOf = (name: ts.PropertyName | undefined) =>
-    name && (ts.isIdentifier(name) || ts.isStringLiteralLike(name) ? name.text : ts.isComputedPropertyName(name) ? textOf(name.expression) : undefined);
-
-  const visit = (node: ts.Node, inType: boolean) => {
-    if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) add(textOf(node.moduleSpecifier));
-    else if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference)) add(textOf(node.moduleReference.expression));
-    else if (ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument)) add(textOf(node.argument.literal));
-    else if (ts.isCallExpression(node)) {
-      const callee = node.expression;
-      if (callee.kind === ts.SyntaxKind.ImportKeyword) { forbidden.add("dynamic import()"); add(textOf(node.arguments[0])); }
-      else if (isGlobal(callee, "require")) add(textOf(node.arguments[0]));
-      else if (ts.isPropertyAccessExpression(callee) && isGlobal(callee.expression, "require")) add(textOf(node.arguments[0]));
-      if (isGlobal(callee, "Function")) forbidden.add("Function()");
-      if (isGlobal(callee, "Date")) forbidden.add("the clock (Date)");
-    } else if (ts.isNewExpression(node)) {
-      if (isGlobal(node.expression, "Function")) forbidden.add("new Function");
-      if (isGlobal(node.expression, "Date")) forbidden.add("the clock (Date)");
-    }
-
-    // Math.random and Date.now, also written Math["random"], (Math).random, or taken out by destructuring.
-    if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) {
-      flagMember(node.expression, ts.isPropertyAccessExpression(node) ? node.name.text : textOf(node.argumentExpression));
-    } else if (ts.isVariableDeclaration(node) && ts.isObjectBindingPattern(node.name) && node.initializer) {
-      for (const el of node.name.elements) flagMember(node.initializer, keyOf(el.propertyName) ?? (ts.isIdentifier(el.name) ? el.name.text : undefined));
-    } else if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken && ts.isObjectLiteralExpression(unwrap(node.left))) {
-      for (const prop of (unwrap(node.left) as ts.ObjectLiteralExpression).properties) {
-        if (ts.isShorthandPropertyAssignment(prop)) flagMember(node.right, prop.name.text);
-        else if (ts.isPropertyAssignment(prop)) flagMember(node.right, keyOf(prop.name));
-      }
-    }
-    if (!inType && ts.isIdentifier(node) && !isNamePosition(node) && Object.hasOwn(FORBIDDEN_NAMES, node.text) && !declared(node)) {
-      // A plain call or `new` of Function is already reported as Function() or new Function.
-      const p = node.parent;
-      const reported = node.text === "Function" && (ts.isCallExpression(p) || ts.isNewExpression(p)) && p.expression === node;
-      if (!reported) forbidden.add(FORBIDDEN_NAMES[node.text]);
-    }
-
-    const nextInType = inType || (ts.isTypeNode(node) && !ts.isExpressionWithTypeArguments(node));
-    ts.forEachChild(node, (c) => visit(c, nextInType));
-  };
-  visit(sf, false);
-  return { specifiers, forbidden: [...forbidden] };
-}
-
-// Every module a file pulls in: import and export declarations, import(), require() and require.x(), however they are spaced or commented.
-export function importSpecifiers(source: string): string[] {
-  return inspectSource(source).specifiers;
-}
-
-// Video.tsx may import sibling component files; a component must be self-contained so it can be reused on its own.
-export function staticCheck(source: string, file: string, siblings: string[]): string[] {
-  const errors: string[] = [];
-  const isMain = file === MAIN_FILE;
-  const allowedSiblings = new Set(isMain ? siblings.filter((s) => s !== MAIN_FILE).map((s) => `./${componentName(s)}`) : []);
-  const found = inspectSource(source, file);
-  for (const s of found.specifiers) {
-    if (BASE_IMPORTS.has(s) || allowedSiblings.has(s)) continue;
-    errors.push(
-      isMain
-        ? `${file}: import not allowed: "${s}". Use react, remotion, ${KIT}, or a component file that exists ("./Name").`
-        : `${file}: import not allowed: "${s}". A component may only import react, remotion and ${KIT}.`,
-    );
-  }
-  for (const name of found.forbidden) errors.push(`${file}: not allowed: ${name}.`);
-  const exported = isMain ? "Video" : componentName(file);
-  const exportsIt = sourceFile(source, file).statements.some((s) =>
-    ts.isVariableStatement(s) && s.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)
-    && s.declarationList.flags & ts.NodeFlags.Const && s.declarationList.declarations.some((d) => ts.isIdentifier(d.name) && d.name.text === exported));
-  if (!exportsIt) errors.push(`${file} must contain \`export const ${exported}\`.`);
-  return errors;
-}
-
-// The project folder has no node_modules. These map its imports to the copies installed with this package.
 const typesReact = packageDir("@types/react");
 export const remotionDir = packageDir("remotion");
 

package/src/render/word-check.ts

@@ -0,0 +1,181 @@
+// What a composition's source says statically about the spoken words it is timed to: which helper calls name a word, in which scene, and whether
+// the word is in that scene's narration. Pure text in, findings out (the TypeScript syntax tree, never regular expressions on code), so `check`
+// and `preview` can both use it.
+import ts from "typescript";
+import { normalizeWord, wordFrame, type WordScene } from "../remotion/kit/word-anchor";
+import { sourceFile, unwrap } from "./static-check";
+
+export const WORD_HELPERS = ["wordFrame", "wordFrames", "onWord", "onWordBeat"] as const;
+const isHelper = (n: string): n is (typeof WORD_HELPERS)[number] => (WORD_HELPERS as readonly string[]).includes(n);
+
+export type WordCall = {
+  fn: (typeof WORD_HELPERS)[number];
+  // The scene, when the call's first argument is a scene found by a literal id (sceneById(manifest, "id"), or manifest.scenes[2], or S.id and S["id"]).
+  sceneId?: string;
+  // One entry per literal word the call names; a word that is not a literal is left out.
+  words: { word: string; nth?: number }[];
+  line: number;
+};
+
+type PlanScene = { id: string; narration: string };
+
+const literalText = (e: ts.Expression | undefined): string | undefined => {
+  const x = e && unwrap(e);
+  return x && ts.isStringLiteralLike(x) ? x.text : undefined;
+};
+const literalNumber = (e: ts.Expression | undefined): number | undefined => {
+  const x = e && unwrap(e);
+  return x && ts.isNumericLiteral(x) ? Number(x.text) : undefined;
+};
+
+// Where a source says `<something>.scenes`: the manifest's list of scenes, however the manifest is called.
+const isScenesList = (e: ts.Expression): boolean => { const x = unwrap(e); return ts.isPropertyAccessExpression(x) && x.name.text === "scenes"; };
+
+// Calls of the word helpers in `source`. `ids` are the plan's scene ids in order, so that a scene reached by position or by `S.hook` can be named.
+export function wordCalls(source: string, ids: string[], file = "Video.tsx"): WordCall[] {
+  const sf = sourceFile(source, file);
+  // Every `const name = expression` and `const [a, b] = list` in the file, flat: the names a composition gives its scenes are not scoped carefully.
+  const consts = new Map<string, ts.Expression>();
+  const positions = new Map<string, number>();
+  const visitDecl = (node: ts.Node) => {
+    if (ts.isVariableDeclaration(node) && node.initializer) {
+      if (ts.isIdentifier(node.name)) consts.set(node.name.text, node.initializer);
+      else if (ts.isArrayBindingPattern(node.name) && isScenesList(node.initializer)) {
+        node.name.elements.forEach((el, i) => { if (ts.isBindingElement(el) && ts.isIdentifier(el.name)) positions.set(el.name.text, i); });
+      }
+    }
+    ts.forEachChild(node, visitDecl);
+  };
+  visitDecl(sf);
+
+  const resolve = (e: ts.Expression, depth = 0): string | undefined => {
+    if (depth > 6) return undefined;
+    const x = unwrap(e);
+    if (ts.isCallExpression(x) && ts.isIdentifier(x.expression) && x.expression.text === "sceneById") {
+      const id = literalText(x.arguments[1]);
+      return id !== undefined && ids.includes(id) ? id : undefined;
+    }
+    if (ts.isIdentifier(x)) {
+      const pos = positions.get(x.text);
+      if (pos !== undefined) return ids[pos];
+      const init = consts.get(x.text);
+      return init ? resolve(init, depth + 1) : undefined;
+    }
+    if (ts.isElementAccessExpression(x) && isScenesList(x.expression)) {
+      const i = literalNumber(x.argumentExpression);
+      return i !== undefined ? ids[i] : undefined;
+    }
+    // A record of scenes by id: `const S = Object.fromEntries(manifest.scenes.map(...))`, then S.hook or S["hook"].
+    if (ts.isPropertyAccessExpression(x) || ts.isElementAccessExpression(x)) {
+      const key = ts.isPropertyAccessExpression(x) ? x.name.text : literalText(x.argumentExpression);
+      const base = unwrap(x.expression);
+      if (key !== undefined && ids.includes(key) && ts.isIdentifier(base)) {
+        const init = consts.get(base.text);
+        if (init && init.getText(sf).includes("scenes")) return key;
+      }
+    }
+    return undefined;
+  };
+
+  const out: WordCall[] = [];
+  const visit = (node: ts.Node) => {
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && isHelper(node.expression.text)) {
+      const fn = node.expression.text;
+      const [scene, arg] = node.arguments;
+      const options = node.arguments.slice(2).map((a) => unwrap(a)).find((a): a is ts.ObjectLiteralExpression => ts.isObjectLiteralExpression(a));
+      const nthProp = options?.properties.find((p): p is ts.PropertyAssignment => ts.isPropertyAssignment(p) && ts.isIdentifier(p.name) && p.name.text === "nth");
+      const nth = literalNumber(nthProp?.initializer);
+      const named: string[] = [];
+      if (arg) {
+        const single = literalText(arg);
+        if (fn === "wordFrames") { const list = unwrap(arg); if (ts.isArrayLiteralExpression(list)) for (const el of list.elements) { const t = literalText(el); if (t !== undefined) named.push(t); } }
+        else if (single !== undefined) named.push(single);
+      }
+      out.push({
+        fn, ...(scene ? (() => { const id = resolve(scene); return id !== undefined ? { sceneId: id } : {}; })() : {}),
+        words: named.map((word) => ({ word, ...(nth !== undefined ? { nth } : {}) })),
+        line: sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1,
+      });
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  return out;
+}
+
+// Whether this narration says `word` (a word or a phrase of consecutive words, ignoring case and punctuation) at least `nth` times.
+export function narrationHas(narration: string, word: string, nth = 1): boolean {
+  const parts = word.split(/\s+/).map(normalizeWord).filter(Boolean);
+  if (!parts.length) return false;
+  const list = narration.split(/\s+/).map(normalizeWord).filter(Boolean);
+  let seen = 0;
+  for (let i = 0; i + parts.length <= list.length; i++) if (parts.every((p, k) => list[i + k] === p) && ++seen >= nth) return true;
+  return false;
+}
+
+// The errors: a literal word that the narration of a literally named scene does not contain.
+export function wordErrors(file: string, calls: WordCall[], scenes: PlanScene[]): string[] {
+  const errors: string[] = [];
+  for (const c of calls) {
+    const scene = c.sceneId ? scenes.find((s) => s.id === c.sceneId) : undefined;
+    if (!scene) continue;
+    for (const w of c.words) {
+      if (narrationHas(scene.narration, w.word, w.nth ?? 1)) continue;
+      errors.push(`${file} line ${c.line}: ${c.fn}(... "${w.word}"${w.nth && w.nth > 1 ? `, { nth: ${w.nth} }` : ""}) names a word that scene ${scene.id} never says. Its narration is: "${scene.narration}". The render would stop on it; use a word from the narration.`);
+    }
+  }
+  return errors;
+}
+
+// True when the file times anything to a spoken word: it calls a word helper, or reads a scene's `.words` for something other than the captions.
+export function usesWordTiming(source: string, file = "Video.tsx"): boolean {
+  const sf = sourceFile(source, file);
+  let used = false;
+  const visit = (node: ts.Node) => {
+    if (used) return;
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && isHelper(node.expression.text)) { used = true; return; }
+    if ((ts.isPropertyAccessExpression(node) && node.name.text === "words") || (ts.isElementAccessExpression(node) && literalText(node.argumentExpression) === "words")) {
+      // `words={s.words}` on <Captions> is not timing: it is the captions' own input.
+      let p: ts.Node | undefined = node.parent;
+      while (p && (ts.isParenthesizedExpression(p) || ts.isAsExpression(p) || ts.isNonNullExpression(p))) p = p.parent;
+      const inCaptions = p && ts.isJsxExpression(p) && ts.isJsxAttribute(p.parent) && p.parent.name.getText(sf) === "words"
+        && (() => { let q: ts.Node | undefined = p.parent.parent.parent; return Boolean(q && (ts.isJsxSelfClosingElement(q) || ts.isJsxOpeningElement(q)) && q.tagName.getText(sf) === "Captions"); })();
+      if (!inCaptions) used = true;
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  return used;
+}
+
+// How many frames after a word starts the preview looks: the thing the word names should already be there.
+export const WORD_FRAME_AFTER = 4;
+// At most this many word frames go on the contact sheet.
+export const MAX_WORD_FRAMES = 16;
+
+export type WordTarget = { sceneId: string; word: string; nth?: number; wordStart: number; frame: number; label: string };
+
+// The words the preview can look at: every literal word of a helper call whose scene is known, as the frame 4 frames after the word starts (kept
+// inside its scene), in film order, without repeats, at most `cap`. `skipped` counts what could not be shown: a word or a scene that is not a
+// literal (the code does not say which), and what was left out past the cap.
+export function wordTargets(calls: WordCall[], manifest: { scenes: (WordScene & { id: string; durationFrames: number })[] }, cap = MAX_WORD_FRAMES): { targets: WordTarget[]; skipped: number; undecidable: number; capped: number } {
+  const seen = new Set<string>();
+  const found: WordTarget[] = [];
+  let undecidable = 0;
+  for (const c of calls) {
+    const scene = c.sceneId ? manifest.scenes.find((s) => s.id === c.sceneId) : undefined;
+    if (!scene || !c.words.length) { undecidable += Math.max(1, c.words.length); continue; }
+    for (const w of c.words) {
+      const key = `${scene.id}|${normalizeWord(w.word) || w.word}|${w.nth ?? 1}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      let start: number;
+      try { start = wordFrame(scene, w.word, { nth: w.nth, absolute: true }); } catch { undecidable++; continue; }
+      const last = scene.startFrame + scene.durationFrames - 1;
+      found.push({ sceneId: scene.id, word: w.word, ...(w.nth && w.nth > 1 ? { nth: w.nth } : {}), wordStart: start, frame: Math.min(start + WORD_FRAME_AFTER, last), label: `${w.word}${w.nth && w.nth > 1 ? ` #${w.nth}` : ""} \u25B8 ${scene.id}` });
+    }
+  }
+  found.sort((a, b) => a.wordStart - b.wordStart);
+  const targets = found.slice(0, cap);
+  return { targets, skipped: undecidable + (found.length - targets.length), undecidable, capped: found.length - targets.length };
+}

package/src/testing/conformance.ts

@@ -166,7 +166,7 @@ export function runConformance(name: string, start: (opts: StartOptions) => Prom
         ["an image type for an sfx", { kind: "sfx", contentType: "image/png" }],
         ["zero bytes", { bytes: 0 }],
         ["more than 200 MB", { bytes: MAX_UPLOAD_BYTES + 1 }],
-        ["a component", { kind: "component", filename: "X.tsx", contentType: "text/plain" }],
+        ["a component without a description or an example", { kind: "component", filename: "X.tsx", contentType: "text/plain" }],
       ])("refuses %s with invalid_request", async (_what, over) => {
         const e = await failure((await as("user-up00008"))("libraryUpload", upload(over) as never));
         expect(e.code).toBe("invalid_request");
@@ -182,6 +182,54 @@ export function runConformance(name: string, start: (opts: StartOptions) => Prom
       });
     });
 
+    describe("component uploads", () => {
+      const SOURCE = new TextEncoder().encode('import React from "react";\nexport const ZipBadge: React.FC<{ label: string }> = ({ label }) => <b>{label}</b>;\n');
+      const component = (over: object = {}) => upload({
+        kind: "component", title: "ZipBadge", description: "A small bold badge that shows a label.", tags: ["badge"], meta: { example: '<ZipBadge label="New" />' },
+        filename: "ZipBadge.tsx", contentType: "text/plain", bytes: SOURCE.length, ...over,
+      });
+
+      it("is committed into review, can be pulled by its owner, and is never in search or the public listing", async () => {
+        const mine = await as("user-cmp00001"), other = await as("user-cmp00002");
+        const up = await mine("libraryUpload", component());
+        expect((await put(up.uploadUrl, SOURCE, "text/plain")).ok).toBe(true);
+        const { item } = await mine("libraryCommit", { id: up.id });
+        expect(item).toMatchObject({ id: up.id, kind: "component", visibility: "review" });
+        expect((await mine("librarySearch", { q: "zipbadge badge", kind: "component" })).items.map((i) => i.id)).not.toContain(up.id);
+        expect((await other("librarySearch", { q: "zipbadge badge" })).items.map((i) => i.id)).not.toContain(up.id);
+        expect((await anon("publicLibrary", { q: "zipbadge badge" })).items.map((i) => i.id)).not.toContain(up.id);
+        expect((await mine("me", {})).contributions).toBe(0);
+        expect((await failure(other("libraryPull", { id: up.id }))).code).toBe("not_found");
+      });
+
+      it("refuses at commit a source that fails the static check, with the first problem", async () => {
+        const mine = await as("user-cmp00003");
+        const bad = new TextEncoder().encode('import fs from "node:fs";\nexport const ZipBadge = () => null;\n');
+        const up = await mine("libraryUpload", component({ bytes: bad.length }));
+        await put(up.uploadUrl, bad, "text/plain");
+        const e = await failure(mine("libraryCommit", { id: up.id }));
+        expect(e.code).toBe("invalid_request");
+        expect(e.message).toContain("node:fs");
+        expect((await failure(mine("libraryPull", { id: up.id }))).code).toBe("not_found");
+      });
+
+      it.each([
+        ["a file name that is not PascalCase .tsx", { filename: "zipBadge.tsx" }],
+        ["a file name that is not .tsx", { filename: "ZipBadge.ts" }],
+        ["a content type that is not text/plain", { contentType: "image/png" }],
+        ["more than 64 KB", { bytes: 65_537 }],
+        ["a description under 20 characters", { description: "a badge" }],
+        ["no example", { meta: {} }],
+        ["an example that does not start with the component's name", { meta: { example: '<Other label="x" />' } }],
+        ["an example over 2000 characters", { meta: { example: `<ZipBadge label="${"x".repeat(2000)}" />` } }],
+        ["a component that is not meant to be shared", { shareable: false }],
+      ])("refuses %s with invalid_request", async (_what, over) => {
+        const e = await failure((await as("user-cmp00004"))("libraryUpload", component(over) as never));
+        expect(e.code).toBe("invalid_request");
+        expect(e.message.length).toBeGreaterThan(0);
+      });
+    });
+
     describe("the library", () => {
       it("a seeded published item is found, pulled and downloaded byte for byte", async () => {
         const bytes = new Uint8Array(Array.from({ length: 300 }, (_, i) => i % 251));
@@ -308,6 +356,18 @@ export function runConformance(name: string, start: (opts: StartOptions) => Prom
         expect((await api("me", {})).quota.images.used).toBe(2);
       });
 
+      it("images: a request for format svg returns an svg, and a request with no format still returns a raster image", async () => {
+        const api = await as("user-gen00008");
+        const svg = await api("images", { prompt: "a red circle, transparent background", aspect: "1:1", shareable: false, tags: [], format: "svg" });
+        expect(svg.ext).toBe("svg");
+        expect(svg.contentType).toBe("image/svg+xml");
+        await download(svg.url, join(dest, "mark.svg"));
+        expect(readFileSync(join(dest, "mark.svg"), "utf8")).toMatch(/^\s*<svg/);
+        const raster = await api("images", { prompt: "a quiet lake", aspect: "16:9", shareable: false, tags: [] });
+        expect(raster.ext).not.toBe("svg");
+        expect((await api("me", {})).quota.images.used).toBe(2);
+      });
+
       it("a shared image's title is the first 60 characters of the prompt, cut on a code point, never inside an emoji", async () => {
         const api = await as("user-gen00007");
         const prompt = "\u{1F30B}".repeat(70);

package/src/testing/fake-api.ts

@@ -6,7 +6,8 @@ import type { AddressInfo } from "node:net";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { MAX_UPLOAD_BYTES, routes, type ErrorCode, type LibraryItem, type RouteName, type Voice } from "../contract";
-import { PIXEL_PNG, silentWav } from "./fixtures";
+import { staticCheck } from "../render/validate";
+import { FAKE_SVG, PIXEL_PNG, silentWav } from "./fixtures";
 
 type Blob = { filename: string; contentType: string; bytes: Uint8Array };
 // owner is the uploader's user id; a seeded item has none. An upload is not an item for anyone until it is committed.
@@ -23,7 +24,7 @@ const WORD_SEC = 0.4;
 // of long media (music, overlays, clips) and a component's source do not. Any kind with a preview of its own would use that instead
 // (the fake has none).
 const PREVIEW_OF_ORIGINAL: readonly string[] = ["image", "sfx"];
-const MIME_PREFIX: Record<string, string> = { image: "image/", clip: "video/", overlay: "video/", sfx: "audio/", music: "audio/" };
+const MIME_PREFIX: Record<string, string> = { component: "text/plain", image: "image/", clip: "video/", overlay: "video/", sfx: "audio/", music: "audio/" };
 // The device-flow user of the fake is "tester"; anyone else is named from their id, as the API names a user with no profile.
 const handleOf = (userId: string) => (userId === "u-test" ? "tester" : `user-${userId.slice(0, 8)}`);
 const nextMonthStart = (now = new Date()) => new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + 1, 1));
@@ -190,6 +191,11 @@ export async function startFakeApi(opts: { voiceoverCharLimit?: number; imageLim
       const s = store.get(id);
       if (!s || s.owner !== userId) throw new Fail(404, "not_found", `No upload with id ${id}.`);
       if (!s.file) throw new Fail(400, "invalid_request", `Nothing was uploaded for ${id}. Send the file to the upload URL first.`);
+      // A user's component is checked like a pulled one would be, before it is anything but an upload. It stays in review for the owner.
+      if (!s.committed && s.item.kind === "component") {
+        const problem = staticCheck(new TextDecoder().decode(s.file.bytes), s.filename, [])[0];
+        if (problem) throw new Fail(400, "invalid_request", `The component was refused: ${problem}`);
+      }
       // Committing again returns the same item and counts once.
       if (!s.committed) { s.committed = true; usage.uploads++; if (s.item.visibility === "review") meter(userId).uploads++; }
       return { item: s.item };
@@ -206,15 +212,15 @@ export async function startFakeApi(opts: { voiceoverCharLimit?: number; imageLim
       const durationSec = list.length * WORD_SEC;
       return { url: fileUrl({ filename: "vo.wav", contentType: "audio/wav", bytes: silentWav(durationSec) }), ext: "wav", contentType: "audio/wav", durationSec, words: list, chars: text.length };
     },
-    images: ({ prompt, aspect, shareable, tags }, { userId }) => {
+    images: ({ prompt, aspect, shareable, tags, format }, { userId }) => {
       const m = meter(userId);
       if (m.images + 1 > limits.images) throw new Fail(429, "quota_exceeded", `Image quota used up. It resets on ${resetDate().slice(0, 10)}.`);
       m.images++;
       usage.images++;
       const id = nextId("image");
-      const file = { filename: "image.png", contentType: "image/png", bytes: PIXEL_PNG };
+      const file = format === "svg" ? { filename: "image.svg", contentType: "image/svg+xml", bytes: new TextEncoder().encode(FAKE_SVG) } : { filename: "image.png", contentType: "image/png", bytes: PIXEL_PNG };
       if (shareable) store.set(id, { item: { id, kind: "image", title: cut(prompt, 60), description: prompt, tags, meta: { aspect }, visibility: "review" }, file, filename: file.filename, contentType: file.contentType, owner: userId, committed: true });
-      return { url: fileUrl(file), ext: "png", contentType: "image/png", ...(shareable ? { libraryId: id } : {}) };
+      return { url: fileUrl(file), ext: format === "svg" ? "svg" : "png", contentType: file.contentType, ...(shareable ? { libraryId: id } : {}) };
     },
     clipStart: (input, { userId }) => {
       if (opts.noClipProvider) throw new Fail(400, "invalid_request", "Clip generation is not available on this server yet.");

package/src/testing/fixtures.ts

@@ -42,3 +42,6 @@ export const Video: React.FC<VideoProps> = ({ manifest, urls }) => {
   );
 };
 `;
+
+// A tiny valid vector graphic, what the fake API returns for format "svg".
+export const FAKE_SVG = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><circle cx="50" cy="50" r="40" fill="#e02020"/><rect x="30" y="30" width="40" height="40" fill="#2040e0"/></svg>';