@navipartner/demo-video 0.4.0 → 0.5.1

package/bin/pitch.mjs

@@ -0,0 +1,261 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { z } from "zod";
+
+// The brand half of `demo-video pitch <proposal.json>`: turns a pitch
+// research's proposal into a brand folder for one render. The proposal comes
+// from an AI that read the open web, so nothing in it is trusted: colours,
+// fonts and config values are checked, and assets are downloaded here (not
+// by the AI), over https, as images only. An SVG with script in it is
+// refused. What goes back into the workflow and the reply (the customer,
+// links, notes) is one line each, and plain text.
+
+const MAX_ASSET_BYTES = 8 * 1024 * 1024;
+// Sites behind a bot challenge (Cloudflare) refuse a bare fetch.
+const HEADERS = {
+  "user-agent":
+    "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36",
+  accept: "image/avif,image/webp,image/svg+xml,image/*,*/*;q=0.8",
+};
+
+const hex = z.string().regex(/^#[0-9a-fA-F]{6}$/, "a #rrggbb colour");
+// A new line would start another workflow output.
+const line = z.string().refine(
+  // eslint-disable-next-line no-control-regex -- they are what it rejects
+  (v) => !/[\u0000-\u001f\u007f]/.test(v),
+  "one line, no control characters",
+);
+const httpsUrl = line
+  .pipe(z.string().max(2000))
+  .refine((v) => {
+    try {
+      return new URL(v).protocol === "https:";
+    } catch {
+      return false;
+    }
+  }, "an https URL")
+  // Normalised, so it can't close the <…> it's printed in.
+  .transform((v) => new URL(v).href);
+const font = z
+  .string()
+  .regex(/^[\w .-]{1,64}$/, "a font name: letters, digits, spaces, . and -");
+// Values go into the app's own branding API mock: no markup, no CSS breakout.
+const configValue = z.union([
+  z
+    .string()
+    .max(200)
+    .refine((v) => !/[<>{};`]/.test(v), "no < > { } ; or ` in a value"),
+  z.number(),
+  z.boolean(),
+]);
+
+const proposalSchema = z
+  .object({
+    // The brand's tenantName takes 64 at most.
+    customer: line.pipe(z.string().min(1).max(64)),
+    website: httpsUrl,
+    sources: z.array(httpsUrl).min(1).max(20),
+    config: z.record(z.string().regex(/^\w{1,64}$/), configValue).default({}),
+    assets: z
+      .record(z.string().regex(/^[A-Za-z]{1,32}$/), httpsUrl)
+      .default({}),
+    video: z
+      .object({
+        primary: hex,
+        ink: hex,
+        accent: hex,
+        text: hex,
+        headingFont: font,
+        bodyFont: font,
+      })
+      .strict(),
+    logoColor: hex.optional(),
+    notes: line.pipe(z.string().max(1000)).optional(),
+  })
+  .strict();
+
+/** "Northwind Århus" → "pitch-northwind-arhus". */
+export const pitchName = (customer) => {
+  const slug = customer
+    .toLowerCase()
+    .replace(/æ/g, "ae")
+    .replace(/ø/g, "o")
+    .replace(/ß/g, "ss")
+    .normalize("NFKD")
+    .replace(/[̀-ͯ]/g, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40)
+    .replace(/-+$/, "");
+  return `pitch-${slug || "customer"}`;
+};
+
+/** Text for the reply: no links, markup or mentions a web page slipped in. */
+export const plainText = (text) =>
+  text
+    .replace(/\b[a-z][\w+.-]*:\/\/\S+/gi, "(link removed)")
+    .replace(/\bwww\.\S+/gi, "(link removed)")
+    .replace(/[[\]<>`*_~|\\]/g, "")
+    // A # starts a heading or an issue link, except in a colour (#1F5494).
+    .replace(/#(?![0-9a-f]{6}\b|[0-9a-f]{3}\b)/gi, "")
+    .replace(/@/g, "@\u200b")
+    .trim();
+
+const SVG_DANGER =
+  /<script|<foreignObject|<iframe|<embed|<object|\son\w+\s*=|javascript:/i;
+
+/** The image type of a download, by its bytes, or null. */
+export const imageType = (bytes) => {
+  const b = bytes;
+  if (b.length >= 8 && b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e) {
+    return ".png";
+  }
+  if (b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) {
+    return ".jpg";
+  }
+  if (
+    b.length >= 12 &&
+    b.toString("latin1", 0, 4) === "RIFF" &&
+    b.toString("latin1", 8, 12) === "WEBP"
+  ) {
+    return ".webp";
+  }
+  // An SVG file starts with <svg, after an XML declaration, a doctype or
+  // comments. A web page with an inline icon doesn't.
+  const head = b
+    .toString("utf8", 0, Math.min(b.length, 4096))
+    .replace(/^\uFEFF/, "")
+    .replace(/^(\s+|<\?xml[\s\S]*?\?>|<!--[\s\S]*?-->|<!DOCTYPE[^>]*>)*/i, "");
+  if (/^<svg[\s/>]/i.test(head) && !head.includes("\u0000")) {
+    return ".svg";
+  }
+  return null;
+};
+
+const download = async (url, fetchImpl) => {
+  const parsed = new URL(url);
+  if (parsed.protocol !== "https:") {
+    throw new Error(`${url}: only https downloads`);
+  }
+  const response = await fetchImpl(url, {
+    headers: HEADERS,
+    redirect: "follow",
+    signal: AbortSignal.timeout(20_000),
+  });
+  if (!response.ok) {
+    throw new Error(`${url}: HTTP ${response.status}`);
+  }
+  if (response.url && new URL(response.url).protocol !== "https:") {
+    throw new Error(`${url}: redirected off https`);
+  }
+  // The usual mistake: the page the logo is on, not the logo's own URL.
+  if (/text\/html/i.test(response.headers.get("content-type") ?? "")) {
+    throw new Error(`${url}: a web page, not an image file`);
+  }
+  const length = Number(response.headers.get("content-length") ?? 0);
+  if (length > MAX_ASSET_BYTES) {
+    throw new Error(`${url}: larger than 8 MB`);
+  }
+  const bytes = Buffer.from(await response.arrayBuffer());
+  if (bytes.length > MAX_ASSET_BYTES) {
+    throw new Error(`${url}: larger than 8 MB`);
+  }
+  const ext = imageType(bytes);
+  if (!ext) {
+    throw new Error(`${url}: not an SVG, PNG, JPEG or WebP image`);
+  }
+  if (ext === ".svg" && SVG_DANGER.test(bytes.toString("utf8"))) {
+    throw new Error(`${url}: an SVG with script or embedded content`);
+  }
+  return { bytes, ext };
+};
+
+// The video loads its fonts from Google Fonts: a name it doesn't know would
+// silently fall back to a system font.
+const checkGoogleFont = async (family, fetchImpl) => {
+  const url = `https://fonts.googleapis.com/css2?family=${encodeURIComponent(family).replace(/%20/g, "+")}`;
+  const response = await fetchImpl(url, {
+    signal: AbortSignal.timeout(20_000),
+  });
+  if (!response.ok) {
+    throw new Error(
+      `"${family}" is not a Google Fonts family (fonts.googleapis.com answered ${response.status})`,
+    );
+  }
+};
+
+// WCAG contrast of a #rrggbb colour against white.
+export const contrastOnWhite = (colour) => {
+  const n = parseInt(colour.slice(1), 16);
+  const channel = (c) => {
+    const v = c / 255;
+    return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+  };
+  const l =
+    0.2126 * channel((n >> 16) & 255) +
+    0.7152 * channel((n >> 8) & 255) +
+    0.0722 * channel(n & 255);
+  return 1.05 / (l + 0.05);
+};
+
+/**
+ * Builds `<outDir>/<name>.json` and `<outDir>/<name>/` from a proposal.
+ * Returns what the reply names: the brand, the customer and the sources.
+ */
+export const buildPitchBrand = async (
+  proposal,
+  outDir,
+  { fetch: fetchImpl = globalThis.fetch } = {},
+) => {
+  const result = proposalSchema.safeParse(proposal);
+  if (!result.success) {
+    throw new Error(
+      `The proposal isn't a brand: ${result.error.issues
+        .map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`)
+        .join("; ")}`,
+    );
+  }
+  const p = result.data;
+  const name = pitchName(p.customer);
+  // Headings and text sit on pale cards.
+  for (const key of ["ink", "text"]) {
+    const ratio = contrastOnWhite(p.video[key]);
+    if (ratio < 4.5) {
+      throw new Error(
+        `video.${key} ${p.video[key]} doesn't read on white (contrast ${ratio.toFixed(1)}, needs 4.5)`,
+      );
+    }
+  }
+  await checkGoogleFont(p.video.headingFont, fetchImpl);
+  if (p.video.bodyFont !== p.video.headingFont) {
+    await checkGoogleFont(p.video.bodyFont, fetchImpl);
+  }
+  const assetDir = path.join(outDir, name);
+  fs.rmSync(assetDir, { recursive: true, force: true });
+  fs.mkdirSync(assetDir, { recursive: true });
+  const assets = {};
+  for (const [slot, url] of Object.entries(p.assets)) {
+    const { bytes, ext } = await download(url, fetchImpl);
+    fs.writeFileSync(path.join(assetDir, `${slot}${ext}`), bytes);
+    assets[slot] = `${name}/${slot}${ext}`;
+  }
+  const brand = {
+    tenantName: p.customer,
+    config: p.config,
+    assets,
+    video: p.video,
+    ...(p.logoColor ? { logoColor: p.logoColor } : {}),
+  };
+  fs.writeFileSync(
+    path.join(outDir, `${name}.json`),
+    JSON.stringify(brand, null, 2),
+  );
+  return {
+    brand: name,
+    customer: plainText(p.customer),
+    website: p.website,
+    sources: p.sources,
+    notes: plainText(p.notes ?? ""),
+  };
+};

package/dist/{adapter-CWqMoNdw.d.ts → adapter-D_iU2dh2.d.ts}

@@ -112,6 +112,17 @@ interface DemoAction<S extends z.ZodRawShape = z.ZodRawShape> {
     params: z.ZodObject<S>;
     run(d: DirectorApi, params: z.infer<z.ZodObject<S>>): Promise<void>;
 }
+/** One thing a brand gives the app: what it is and where it shows. */
+type BrandNeed = string | {
+    what: string;
+    optional?: boolean;
+};
+interface BrandNeeds {
+    /** `brand.config` keys that `setup` applies. */
+    config?: Record<string, BrandNeed>;
+    /** Asset slots that `setup` uses (`brand.assetUrls[slot]`). */
+    assets?: Record<string, BrandNeed>;
+}
 interface DemoAdapter {
     /** Must equal the storyboard's `app`. */
     app: string;
@@ -148,6 +159,14 @@ interface DemoAdapter {
     brands?: string;
     /** Default "navipartner". */
     defaultBrand?: string;
+    /**
+     * What this app takes from a brand, each with what it is and where it
+     * shows ("full-screen photo behind the menu, landscape"). Apps differ: one
+     * shows a background image, another a secondary colour. Whoever makes a
+     * brand reads this (`demo-video brand-needs`), and a brand without a need
+     * that isn't `optional` fails `check`.
+     */
+    brandNeeds?: BrandNeeds;
     /** App-specific steps, used in storyboards as { "do": "<name>", …params }. */
     actions?: Record<string, DemoAction<any>>;
 }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { D as DemoAdapter } from './adapter-CWqMoNdw.js';
-export { B as Brand, C as CardSpec, a as DemoAction, b as DirectorApi, T as Target, V as VideoBrand, d as defineAction, c as defineDemo } from './adapter-CWqMoNdw.js';
+import { D as DemoAdapter } from './adapter-D_iU2dh2.js';
+export { B as Brand, C as CardSpec, a as DemoAction, b as DirectorApi, T as Target, V as VideoBrand, d as defineAction, c as defineDemo } from './adapter-D_iU2dh2.js';
 import { Page } from '@playwright/test';
 import { z } from 'zod';
 export { z } from 'zod';
@@ -240,7 +240,7 @@ interface Storyboard {
     brand?: string;
     /** The story a variant extends. */
     variantOf?: string;
-    /** What the story shows, for people (and the Linear agent) choosing one. */
+    /** What the story shows, for people choosing one (and the menu). */
     description?: string;
     /** The app's primary journey: the story filmed when none is named. One per app. */
     primary?: boolean;

package/dist/runner/index.d.ts

@@ -1,5 +1,5 @@
 import { PlaywrightTestConfig, Page } from '@playwright/test';
-import { D as DemoAdapter } from '../adapter-CWqMoNdw.js';
+import { D as DemoAdapter } from '../adapter-D_iU2dh2.js';
 import 'zod';
 
 /**
@@ -7,7 +7,7 @@ import 'zod';
  * `defineConfig` and loads no Playwright of its own. `demoDir` is the app's
  * demo/ folder; `runnerDir` holds the spec the CLI generated.
  */
-declare const createDemoConfig: (adapter: DemoAdapter, demoDir: string, runnerDir: string) => PlaywrightTestConfig;
+declare const createDemoConfig: (adapter: DemoAdapter, demoDir: string, runnerDir: string, mode?: string | undefined) => PlaywrightTestConfig;
 
 /** The app's own Playwright `test`, passed in so only one Playwright loads. */
 type DemoTest = (title: string, body: (args: {

package/dist/runner/index.js

@@ -34,7 +34,7 @@ import {
 
 // src/runner/config.ts
 import path from "path";
-var createDemoConfig = (adapter, demoDir, runnerDir) => ({
+var createDemoConfig = (adapter, demoDir, runnerDir, mode = process.env.DEMO_MODE) => ({
   testDir: runnerDir,
   testMatch: ["demo.spec.mjs"],
   // Beside the runner, in the run's work folder: kept only on failure.
@@ -55,7 +55,7 @@ var createDemoConfig = (adapter, demoDir, runnerDir) => ({
     video: "off",
     screenshot: "off"
   },
-  webServer: {
+  webServer: mode === "needs" ? void 0 : {
     command: adapter.webServer.command,
     // demo/ sits in the app's root, where its dev script lives.
     cwd: path.dirname(demoDir),
@@ -213,6 +213,34 @@ var routeBrandAssets = async (page, brand) => {
     );
   }
 };
+var VIDEO_NEEDS = {
+  tenantName: "The customer's name, as the app shows it.",
+  "assets.logo": "The customer's logo: SVG, or a PNG with a transparent background. Shown on the video's cards.",
+  "video.primary": "The main brand colour (#rrggbb): full-bleed cards, the emphasis word, the background tint.",
+  "video.ink": "A dark brand colour for headings on pale cards. Must read well on white.",
+  "video.accent": "A lighter brand colour for the soft background bloom.",
+  "video.text": "Body text on pale cards: near-black.",
+  "video.headingFont": "A Google Fonts family for headings.",
+  "video.bodyFont": "A Google Fonts family for sub-lines.",
+  logoColor: "Optional: replaces white fills in an SVG logo, so a white logo shows on pale cards."
+};
+var needOf = (need) => typeof need === "string" ? { what: need, optional: false } : { what: need.what, optional: need.optional === true };
+var describeNeeds = (needs = {}) => ({
+  config: Object.fromEntries(
+    Object.entries(needs.config ?? {}).map(([k, v]) => [k, needOf(v)])
+  ),
+  assets: Object.fromEntries(
+    Object.entries(needs.assets ?? {}).map(([k, v]) => [k, needOf(v)])
+  )
+});
+var missingNeeds = (brand, needs = {}) => {
+  const { config, assets } = describeNeeds(needs);
+  const empty = (value) => value === void 0 || value === null || value === "";
+  return [
+    ...Object.entries(config).filter(([key, need]) => !need.optional && empty(brand.config[key])).map(([key, need]) => `config.${key}: ${need.what}`),
+    ...Object.entries(assets).filter(([slot, need]) => !need.optional && !brand.assets[slot]).map(([slot, need]) => `assets.${slot}: ${need.what}`)
+  ];
+};
 
 // src/changes.ts
 var watchChanges = (target) => target.evaluate((el) => {
@@ -1075,6 +1103,7 @@ var readRunEnv = (env = process.env) => {
     outDir,
     workDir: env.DEMO_WORK || `${outDir}/.work`,
     brand: env.DEMO_BRAND || void 0,
+    brandsDir: env.DEMO_BRANDS || void 0,
     draft: env.DEMO_DRAFT === "1"
   };
 };
@@ -1124,6 +1153,23 @@ var writeJson = (file, value) => {
   fs3.writeFileSync(file, JSON.stringify(value, null, 2));
 };
 var registerDemoTests = (test, adapter, demoDir) => {
+  if (process.env.DEMO_MODE === "needs") {
+    test("demo", async () => {
+      writeJson(path4.join(process.env.DEMO_WORK ?? demoDir, "needs.json"), {
+        app: adapter.app,
+        viewport: adapter.viewport ?? DEFAULT_VIEWPORT,
+        video: VIDEO_NEEDS,
+        appNeeds: describeNeeds(adapter.brandNeeds),
+        example: JSON.parse(
+          fs3.readFileSync(
+            path4.join(sharedBrandsDir(), "navipartner.json"),
+            "utf8"
+          )
+        )
+      });
+    });
+    return;
+  }
   test("demo", async ({ page }) => {
     const env = readRunEnv();
     if (env.mode === "check") {
@@ -1156,9 +1202,21 @@ var registerDemoTests = (test, adapter, demoDir) => {
       );
     }
     const brand = loadBrand(
-      brandDirs(demoDir, adapter.brands),
+      [
+        ...env.brandsDir ? [env.brandsDir] : [],
+        ...brandDirs(demoDir, adapter.brands)
+      ],
       env.brand ?? storyboard.brand ?? adapter.defaultBrand ?? "navipartner"
     );
+    const missing = missingNeeds(brand, adapter.brandNeeds);
+    if (missing.length > 0) {
+      throw new Error(
+        [
+          `Brand "${brand.name}" lacks what ${adapter.app} needs (the adapter's brandNeeds):`,
+          ...missing.map((m) => `  ${m}`)
+        ].join("\n")
+      );
+    }
     await adapter.setup(page, { brand });
     await routeBrandAssets(page, brand);
     await page.route(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@navipartner/demo-video",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Marketing demo videos of a React app, filmed by Playwright against the app's own e2e mocks.",
   "license": "UNLICENSED",
   "repository": {