reelkit-cli 0.4.0 → 0.6.0

package/src/render/static-check.ts

@@ -0,0 +1,156 @@
+import ts from "typescript";
+
+// The check a component's source gets before it is used or shared: which modules it may import, which names it may not touch, and that
+// it exports what its file name says. Kept apart from the rest of validation because it needs nothing from this package's own folder
+// or from the machine: it is pure text in, problems out, so a server can bundle it.
+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$/, "");
+
+export 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",
+};
+
+export 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.
+export 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.

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");
 
@@ -189,3 +42,30 @@ export function typecheck(files: string[]): string[] {
       return `${basename(d.file!.fileName)} line ${pos.line + 1}: ${ts.flattenDiagnosticMessageText(d.messageText, "\n")}`;
     });
 }
+
+const isLiteral = (e: ts.Expression): boolean => {
+  const x = unwrap(e);
+  if (ts.isStringLiteralLike(x) || ts.isNumericLiteral(x) || x.kind === ts.SyntaxKind.TrueKeyword || x.kind === ts.SyntaxKind.FalseKeyword || x.kind === ts.SyntaxKind.NullKeyword) return true;
+  if (ts.isPrefixUnaryExpression(x)) return ts.isNumericLiteral(x.operand);
+  if (ts.isArrayLiteralExpression(x)) return x.elements.every(isLiteral);
+  if (ts.isObjectLiteralExpression(x)) return x.properties.every((p) => ts.isPropertyAssignment(p) && (ts.isIdentifier(p.name) || ts.isStringLiteralLike(p.name)) && isLiteral(p.initializer));
+  return false;
+};
+
+// Every use of <tag> in the file, as it would be written on its own: the opening tag with its props, closed with "/>". `literal` is false
+// when a prop is anything but a literal value (a variable, urls[...], s.words, a function, a spread), which would mean nothing outside this file.
+export function jsxUses(source: string, file: string, tag: string): { example: string; literal: boolean }[] {
+  const sf = sourceFile(source, file);
+  const out: { example: string; literal: boolean }[] = [];
+  const visit = (node: ts.Node) => {
+    const opening = ts.isJsxSelfClosingElement(node) ? node : ts.isJsxElement(node) ? node.openingElement : undefined;
+    if (opening && opening.tagName.getText(sf) === tag) {
+      const literal = opening.attributes.properties.every((a) => ts.isJsxAttribute(a) && (!a.initializer || ts.isStringLiteralLike(a.initializer) || (ts.isJsxExpression(a.initializer) && a.initializer.expression !== undefined && isLiteral(a.initializer.expression))));
+      const props = opening.attributes.properties.map((a) => a.getText(sf).replace(/\s*\n\s*/g, " ")).join(" ");
+      out.push({ example: `<${tag}${props ? ` ${props}` : ""} />`, literal });
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  return out;
+}

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));

package/src/testing/fake-api.ts

@@ -6,6 +6,7 @@ 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 { staticCheck } from "../render/validate";
 import { PIXEL_PNG, silentWav } from "./fixtures";
 
 type Blob = { filename: string; contentType: string; bytes: Uint8Array };
@@ -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 };