luckiest-co 1.0.19 → 1.0.21

package/skills/luckiest-video-studio-cards/references/card-contract.md

@@ -0,0 +1,77 @@
+# Card contract
+
+Every card in `packs/` follows these rules. A new card that breaks one is not
+added to a pack.
+
+## Layout of a pack
+
+```
+packs/NN-slug/
+  style.json   manifest: id, name, palette, fonts, motion, and every card with its slots
+  DESIGN.md    the look: palette meanings, type voices, motion rules, what not to do
+  tokens.css   CSS variables for colors, fonts, easings; cards read only these
+  cards/tier1/ full-frame takeovers
+  cards/tier2/ overlays that keep the speaker visible
+```
+
+`packs/registry.json` is generated from every `style.json` by
+`scripts/build-registry.mjs`. Never edit it by hand.
+
+## Ids
+
+- Pack folder `NN-slug` (for example `02-aurora-glass`), pack id `slug`.
+- Card id `<pack>.<tier>.<purpose>[.<treatment>]`, for example
+  `aurora-glass.t1.stat.dotgrid`. Stable and unique.
+
+## Each card
+
+1. A standalone HyperFrames composition: a root `<div>` with `id`,
+   `data-composition-id`, `data-start="0"`, `data-width="1920"`,
+   `data-height="1080"`, directly in `<body>`, with its own pinned GSAP script tag.
+2. Exactly one paused GSAP timeline, registered on
+   `window.__timelines["<data-composition-id>"]`.
+3. Colors, fonts, and easings come from `tokens.css` variables, linked as
+   `<link rel="stylesheet" href="cards/<pack-id>/tokens.css" />`. Paths are
+   relative to the run's `composition/` folder; HyperFrames lint rejects `../`
+   paths because Studio preview resolves them against the project root. A card that still
+   holds a literal color is listed in `references/palette-leftovers.md`.
+4. Background by tier: `tier1` is opaque edge to edge; `tier2` is transparent
+   everywhere except the card itself and never covers the speaker's face.
+5. All text sits in elements with `data-slot="<name>"`, and every slot is declared
+   in `style.json` with its name and type.
+6. Deterministic: no `Math.random()`, no `Date.now()`, no network calls.
+
+## Mounting a card inside another scene
+
+Cards are written standalone so they preview and render alone. To place a tier2
+card over a talk scene, wrap the card's root `<div>` in
+`<template id="<id>-template">`, drop its GSAP tag (the parent loads GSAP), and
+mount it from the scene:
+
+```html
+<div id="lt-1" data-composition-id="<card-composition-id>"
+     data-composition-src="compositions/cards/<card>.html"
+     data-start="3.2" data-duration="12" data-track-index="3"></div>
+```
+
+## QA status
+
+`style.json` cards carry a `qa` field that `scripts/qa-cards.mjs` sets:
+`lint-ok` (HyperFrames lint clean), `render-ok` (also rendered and inspected), or
+`broken` (lint errors; do not use until fixed). New cards start `unchecked`.
+
+At 1.0.0: 396 `lint-ok` and 10 `render-ok`, none `broken`. The 57 cards the kit
+shipped with lint errors were fixed:
+
+- Starting transforms moved from CSS into a `gsap.set` right after the timeline is
+  created, so GSAP owns the whole transform (`gsap_css_transform_conflict`).
+- Template-literal selectors became plain strings (`template_literal_selector`).
+- Tweens on `left` and `top` became `x` or percent centering, and one
+  `letterSpacing` tween was dropped (`gsap_non_transform_motion`).
+
+Rendered before and after, 14 of 15 sampled fixes match within encoding noise.
+The kinetic section card changed on purpose: its entrance no longer reflows onto
+two lines and jumps back.
+
+Keep new cards to the same rules: no CSS `transform` on anything GSAP tweens,
+plain-string selectors, and motion through transforms only.

package/skills/luckiest-video-studio-cards/references/palette-leftovers.md

@@ -0,0 +1,28 @@
+# Palette leftovers
+
+Cards that still hold literal colors after the palette colors were moved to
+`tokens.css` variables. These colors do not follow `brand.json`. Most are shades
+of the pack palette inside scripts or gradients. Check them on a branded render,
+and move a color to a variable when it clashes with the brand.
+
+White (`#ffffff`) is left as a neutral highlight in every pack and is not listed.
+
+| Card | Colors |
+|---|---|
+| `01-paper-collage/cards/tier1/t1-overview-board.html` | `#1f1a12` |
+| `01-paper-collage/cards/tier1/t1-section-crt.html` | `#120f0a` x3, `#efe7d4`, `#2a2317`, `#3a3120`, `#1c1810`, `#1b2620`, `#0c1310`, `#060a08`, `#f3ecda` |
+| `01-paper-collage/cards/tier1/t1-section-fullbleed.html` | `#1a160f`, `#2a241a` |
+| `01-paper-collage/cards/tier1/t1-stat-heat.html` | `#e6dcc4`, `#4f8cff`, `#f26a1b`, `#e23b2e` |
+| `01-paper-collage/cards/tier1/t1-stat-isotype.html` | `#4f8cff`, `#17130e` |
+| `01-paper-collage/cards/tier1/t1-stat-photo.html` | `#7d756a` |
+| `01-paper-collage/cards/tier1/t1-stat-spotlight.html` | `#2a231a`, `#0d0b08` |
+| `02-aurora-glass/cards/tier1/t1-overview-dashboard.html` | `#4f8cff` |
+| `02-aurora-glass/cards/tier1/t1-overview-kpirow.html` | `#4ade80` |
+| `02-aurora-glass/cards/tier1/t1-overview-legend.html` | `#4f8cff`, `#ff8a5c`, `#f5d82a`, `#ff3b30` |
+| `02-aurora-glass/cards/tier1/t1-section-eclipse.html` | `#0e1620`, `#050c14` |
+| `02-aurora-glass/cards/tier1/t1-section-kinetic.html` | `#a8e6ff` |
+| `02-aurora-glass/cards/tier1/t1-stat-beforeafter.html` | `#37e68c` |
+| `02-aurora-glass/cards/tier1/t1-stat-pictobar.html` | `#4f8cff` |
+| `02-aurora-glass/cards/tier1/t1-stat-tickerstat.html` | `#37e68c` x2 |
+| `02-aurora-glass/cards/tier2/t2-lt-gradient.html` | `#d0effe` |
+| `02-aurora-glass/cards/tier2/t2-lt-micname.html` | `#ff5f58` |

package/skills/luckiest-video-studio-cards/scripts/apply-brand.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+// Copy a card pack into a run and rewrite its tokens.css from the run's brand.json.
+//
+// Usage: node apply-brand.mjs <run-dir> <pack-id> [--accent-only]
+//   Writes <run-dir>/composition/cards/<pack-id>/ (tokens.css, style.json, DESIGN.md, cards/).
+//   --accent-only keeps the pack's own surfaces and text colors and takes only the
+//   accent and fonts from brand.json (use it when the brand's paper is light and the
+//   pack is dark, or the other way round).
+//
+// Which brand role feeds which variable lives in the pack's style.json "brandMap":
+//   "paper" | "paper2" | "ink" | "muted" | "accent" | "rule"  -> the color
+//   "rgb:<role>"                                               -> "r, g, b" of that color
+//   "font:display" | "font:text" | "font:mono"                 -> a font-family stack
+// Fonts found in <run-dir>/composition/assets/fonts/ get @font-face rules; nothing loads remotely.
+
+import { cpSync, existsSync, readFileSync, readdirSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, resolve, dirname, extname, basename } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PACKS = resolve(dirname(fileURLToPath(import.meta.url)), "../packs");
+const ACCENT_ONLY = new Set(["accent", "rgb:accent", "font:display", "font:text", "font:mono"]);
+const FALLBACK = { display: "system-ui, sans-serif", text: "system-ui, sans-serif", mono: "ui-monospace, monospace" };
+const FONT_EXT = new Set([".woff2", ".woff", ".ttf", ".otf"]);
+
+export function hexToRgb(color) {
+  const m = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(String(color).trim());
+  if (!m) return null;
+  const h = m[1].length === 3 ? [...m[1]].map((c) => c + c).join("") : m[1];
+  return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16)).join(", ");
+}
+
+// Pure: returns the new tokens.css text and what changed.
+export function brandTokens(css, brandMap, brand, { accentOnly = false, fonts = [] } = {}) {
+  const changed = [], skipped = [];
+  for (const [varName, role] of Object.entries(brandMap)) {
+    if (accentOnly && !ACCENT_ONLY.has(role)) continue;
+    let value;
+    if (role.startsWith("rgb:")) value = hexToRgb(brand[role.slice(4)] ?? "");
+    else if (role.startsWith("font:")) {
+      const key = role.slice(5), fam = brand[key];
+      value = fam ? `"${fam}", ${FALLBACK[key]}` : null;
+    } else value = brand[role] ?? null;
+    if (!value) { skipped.push(varName); continue; }
+    const re = new RegExp(`(^\\s*${varName.replace(/-/g, "\\-")}\\s*:)[^;]*;`, "m");
+    if (!re.test(css)) { skipped.push(varName); continue; }
+    css = css.replace(re, `$1 ${value};`);
+    changed.push(varName);
+  }
+  const faces = fonts.map(({ family, file }) =>
+    `@font-face { font-family: "${family}"; src: url("../../assets/fonts/${file}"); font-display: block; }`);
+  if (faces.length) css = `/* Brand fonts, local files only. */\n${faces.join("\n")}\n\n${css}`;
+  return { css, changed, skipped };
+}
+
+// Match font files to brand families by name: "Instrument Serif" -> InstrumentSerif-Regular.woff2.
+export function matchFonts(files, brand) {
+  const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, "");
+  const out = [];
+  for (const key of ["display", "text", "mono"]) {
+    const fam = brand[key];
+    if (!fam) continue;
+    for (const f of files) if (FONT_EXT.has(extname(f).toLowerCase()) && norm(basename(f)).startsWith(norm(fam))) out.push({ family: fam, file: f });
+  }
+  return out.filter((x, i) => out.findIndex((y) => y.file === x.file) === i);
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const [runArg, packId, ...flags] = process.argv.slice(2);
+  if (!runArg || !packId) { console.error("Usage: apply-brand.mjs <run-dir> <pack-id> [--accent-only]"); process.exit(1); }
+  const run = resolve(runArg);
+  const folder = readdirSync(PACKS).find((d) => d === packId || d.replace(/^\d\d-/, "") === packId);
+  if (!folder) { console.error(`no pack ${packId} in ${PACKS}`); process.exit(1); }
+  const brandPath = join(run, "brand.json");
+  if (!existsSync(brandPath)) { console.error(`missing ${brandPath}; write it first (references/brand.md)`); process.exit(1); }
+  const brand = JSON.parse(readFileSync(brandPath, "utf8"));
+  const manifest = JSON.parse(readFileSync(join(PACKS, folder, "style.json"), "utf8"));
+  if (!manifest.brandMap) { console.error(`${folder}/style.json has no brandMap`); process.exit(1); }
+
+  const id = folder.replace(/^\d\d-/, "");
+  const dest = join(run, "composition", "cards", id);
+  mkdirSync(dirname(dest), { recursive: true });
+  cpSync(join(PACKS, folder), dest, { recursive: true });
+
+  const fontDir = join(run, "composition", "assets", "fonts");
+  const fonts = existsSync(fontDir) ? matchFonts(readdirSync(fontDir), brand) : [];
+  const tokensPath = join(dest, "tokens.css");
+  const result = brandTokens(readFileSync(tokensPath, "utf8"), manifest.brandMap, brand, { accentOnly: flags.includes("--accent-only"), fonts });
+  writeFileSync(tokensPath, result.css);
+  console.log(JSON.stringify({ pack: id, dest, changed: result.changed, skipped: result.skipped, fonts: fonts.map((f) => f.file) }, null, 2));
+}

package/skills/luckiest-video-studio-cards/scripts/apply-brand.test.mjs

@@ -0,0 +1,62 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { brandTokens, hexToRgb, matchFonts } from "./apply-brand.mjs";
+
+const brand = { paper: "#101010", paper2: "#181818", ink: "#F7F4EE", muted: "#9A9A9A",
+  accent: "#FF4D00", display: "Instrument Serif", text: "Geist", mono: "Geist Mono" };
+
+test("hexToRgb handles long, short, and bad input", () => {
+  assert.equal(hexToRgb("#FF4D00"), "255, 77, 0");
+  assert.equal(hexToRgb("#fff"), "255, 255, 255");
+  assert.equal(hexToRgb("rgba(1,2,3,1)"), null);
+});
+
+test("brandTokens rewrites mapped variables and leaves the rest", () => {
+  const css = ":root {\n  --accent: #4F8CFF;\n  --accent-rgb: 79, 140, 255;\n  --canvas: #0A0E14;\n  --radius: 28px;\n}\n";
+  const map = { "--accent": "accent", "--accent-rgb": "rgb:accent", "--canvas": "paper", "--missing": "ink" };
+  const out = brandTokens(css, map, brand);
+  assert.match(out.css, /--accent: #FF4D00;/);
+  assert.match(out.css, /--accent-rgb: 255, 77, 0;/);
+  assert.match(out.css, /--canvas: #101010;/);
+  assert.match(out.css, /--radius: 28px;/);
+  assert.deepEqual(out.skipped, ["--missing"]);
+});
+
+test("accent-only keeps the pack surfaces", () => {
+  const css = ":root {\n  --accent: #4F8CFF;\n  --canvas: #0A0E14;\n}\n";
+  const out = brandTokens(css, { "--accent": "accent", "--canvas": "paper" }, brand, { accentOnly: true });
+  assert.match(out.css, /--accent: #FF4D00;/);
+  assert.match(out.css, /--canvas: #0A0E14;/);
+});
+
+test("fonts become a family stack and local @font-face rules", () => {
+  const fonts = matchFonts(["InstrumentSerif-Regular.woff2", "Geist-Variable.ttf", "notes.txt"], brand);
+  assert.deepEqual(fonts.map((f) => f.file), ["InstrumentSerif-Regular.woff2", "Geist-Variable.ttf"]);
+  const out = brandTokens(":root {\n  --font-display: \"Fraunces\", serif;\n}\n", { "--font-display": "font:display" }, brand, { fonts });
+  assert.match(out.css, /--font-display: "Instrument Serif", system-ui, sans-serif;/);
+  assert.match(out.css, /@font-face \{ font-family: "Instrument Serif"; src: url\("\.\.\/\.\.\/assets\/fonts\/InstrumentSerif-Regular\.woff2"\)/);
+  assert.doesNotMatch(out.css, /https?:\/\//);
+});
+
+test("CLI brands every shipped pack from a run's brand.json", () => {
+  const run = mkdtempSync(join(tmpdir(), "cards-brand-"));
+  writeFileSync(join(run, "brand.json"), JSON.stringify(brand));
+  for (const pack of ["paper-collage", "aurora-glass"]) {
+    const r = spawnSync(process.execPath, [join(import.meta.dirname, "apply-brand.mjs"), run, pack], { encoding: "utf8" });
+    assert.equal(r.status, 0, r.stderr);
+    const tokens = readFileSync(join(run, "composition/cards", pack, "tokens.css"), "utf8");
+    assert.match(tokens, /#FF4D00/, `${pack} did not take the brand accent`);
+    assert.doesNotMatch(tokens, /#4F8CFF/i, `${pack} still holds the default accent`);
+  }
+});
+
+test("CLI fails without brand.json", () => {
+  const run = mkdtempSync(join(tmpdir(), "cards-brand-"));
+  mkdirSync(join(run, "composition"));
+  const r = spawnSync(process.execPath, [join(import.meta.dirname, "apply-brand.mjs"), run, "aurora-glass"], { encoding: "utf8" });
+  assert.equal(r.status, 1);
+});

package/skills/luckiest-video-studio-cards/scripts/build-registry.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// Scan packs/ for NN-slug pack folders, read each style.json, and write
+// packs/registry.json: the index luckiest-video-studio reads to pick cards.
+// Usage: node scripts/build-registry.mjs
+
+import { readdirSync, statSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const LIB = resolve(dirname(fileURLToPath(import.meta.url)), "../packs");
+
+const packDirs = readdirSync(LIB)
+  .filter((d) => /^\d\d-/.test(d) && statSync(join(LIB, d)).isDirectory())
+  .sort();
+
+const packs = [];
+const warnings = [];
+for (const dir of packDirs) {
+  const manifestPath = join(LIB, dir, "style.json");
+  if (!existsSync(manifestPath)) { warnings.push(`${dir}: no style.json`); continue; }
+  let m;
+  try { m = JSON.parse(readFileSync(manifestPath, "utf8")); }
+  catch (e) { warnings.push(`${dir}: invalid style.json (${e.message})`); continue; }
+
+  const cards = (m.cards ?? []).map((c) => {
+    if (c.file && !existsSync(join(LIB, dir, c.file))) warnings.push(`${dir}: card file missing: ${c.file}`);
+    return {
+      id: c.id, pack: m.id, tier: c.tier, purpose: c.purpose, treatment: c.treatment ?? null,
+      file: `${dir}/${c.file}`,
+      slots: (c.slots ?? []).map((s) => s.name),
+      duration: c.duration ?? null,
+      qa: c.qa ?? "unchecked",
+    };
+  });
+
+  packs.push({
+    id: m.id, number: m.number, name: m.name, status: m.status ?? "draft",
+    folder: dir, summary: m.inspiration ?? null,
+    palette: m.palette ?? null, fonts: m.fonts ?? null,
+    cardCount: cards.length,
+    cards,
+  });
+}
+
+const registry = {
+  generated_by: "scripts/build-registry.mjs",
+  packCount: packs.length,
+  cardCount: packs.reduce((n, p) => n + p.cardCount, 0),
+  tiers: ["tier1", "tier2", "custom"],
+  packs,
+  warnings,
+};
+writeFileSync(join(LIB, "registry.json"), JSON.stringify(registry, null, 2) + "\n");
+console.log(JSON.stringify({ packs: packs.length, cards: registry.cardCount, warnings }, null, 2));

package/skills/luckiest-video-studio-cards/scripts/new-pack.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+// Scaffold a new card pack by cloning packs/_blueprint/ and substituting the id.
+// Usage: node scripts/new-pack.mjs <NN> <slug> ["Human Name"]
+//   e.g. node scripts/new-pack.mjs 03 ink-grid "Ink Grid"
+
+import { cpSync, existsSync, readFileSync, writeFileSync, renameSync, readdirSync, statSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { argv, exit } from "node:process";
+
+const LIB = resolve(dirname(fileURLToPath(import.meta.url)), "../packs");
+const [, , numRaw, slug, ...nameParts] = argv;
+if (!numRaw || !slug) { console.error('Usage: new-pack.mjs <NN> <slug> ["Human Name"]'); exit(1); }
+if (!/^[a-z0-9][a-z0-9-]*$/.test(slug)) { console.error("slug must be kebab-case"); exit(1); }
+
+const num = String(numRaw).padStart(2, "0");
+const id = slug;
+const name = nameParts.join(" ") || slug.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+const dest = join(LIB, `${num}-${slug}`);
+if (existsSync(dest)) { console.error(`already exists: ${dest}`); exit(1); }
+
+cpSync(join(LIB, "_blueprint"), dest, { recursive: true });
+
+// substitute STYLE_ID / NN / name placeholders in text files
+function walk(dir) {
+  for (const entry of readdirSync(dir)) {
+    const p = join(dir, entry);
+    if (statSync(p).isDirectory()) { walk(p); continue; }
+    if (!/\.(json|css|md|html)$/.test(entry)) continue;
+    let txt = readFileSync(p, "utf8");
+    const next = txt.replaceAll("STYLE_ID", id).replaceAll('"number": "NN"', `"number": "${num}"`).replaceAll("Human Readable Style Name", name);
+    if (next !== txt) writeFileSync(p, next);
+  }
+}
+walk(dest);
+
+// rename the example card files to be style-scoped (optional convenience)
+console.log(JSON.stringify({ created: dest, id, number: num, name, next: [
+  `1. fill DESIGN.md, tokens.css, and style.json identity fields`,
+  `2. build cards under packs/${num}-${slug}/cards/`,
+  `3. node scripts/build-registry.mjs`,
+] }, null, 2));

package/skills/luckiest-video-studio-cards/scripts/qa-cards.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+// Record a QA status on every card in packs/*/style.json, then rebuild the registry.
+//
+//   node qa-cards.mjs lint [--pack <id>] [--jobs 6] [--bin <hyperframes>]
+//       Lints each card on its own with `hyperframes lint --json`. Sets qa to "lint-ok",
+//       or "broken" when lint reports errors. Never downgrades a "render-ok" card that
+//       still lints clean. Uses `hyperframes` on PATH, else the cached
+//       `npx --no-install hyperframes@0.8.84` (it never downloads).
+//   node qa-cards.mjs mark <status> <card-id>...
+//       Sets qa by hand, for example "render-ok" after a rendered card was inspected.
+//   node qa-cards.mjs sample <run-dir> [--pack <id>]
+//       Writes a run folder with one tier1 and one tier2 card per purpose per pack as
+//       motion scenes, ready for render-scenes.mjs.
+
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn, spawnSync } from "node:child_process";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PACKS = resolve(HERE, "../packs");
+const HF_VERSION = "0.8.84";
+const args = process.argv.slice(2);
+const flag = (n, d) => { const i = args.indexOf(n); return i >= 0 ? args[i + 1] : d; };
+const packDirs = () => readdirSync(PACKS).filter((d) => /^\d\d-/.test(d)).filter((d) => !flag("--pack") || d.endsWith(flag("--pack")));
+const readManifest = (d) => JSON.parse(readFileSync(join(PACKS, d, "style.json"), "utf8"));
+const writeManifest = (d, m) => writeFileSync(join(PACKS, d, "style.json"), JSON.stringify(m, null, 2) + "\n");
+const rebuild = () => spawnSync(process.execPath, [join(HERE, "build-registry.mjs")], { stdio: "inherit" });
+
+function hfCommand() {
+  const bin = flag("--bin");
+  if (bin) return [bin];
+  return spawnSync("hyperframes", ["--version"], { encoding: "utf8" }).status === 0
+    ? ["hyperframes"] : ["npx", "--no-install", `hyperframes@${HF_VERSION}`];
+}
+
+// Lint one card as the root index.html of a scratch project, with the pack's tokens at
+// cards/<pack-id>/tokens.css, the same root-relative path a run uses.
+function lintCard(hf, packDir, file) {
+  return new Promise((done) => {
+    const proj = mkdtempSync(join(tmpdir(), "card-lint-"));
+    mkdirSync(join(proj, "cards", packDir.replace(/^\d\d-/, "")), { recursive: true });
+    cpSync(join(PACKS, packDir, "tokens.css"), join(proj, "cards", packDir.replace(/^\d\d-/, ""), "tokens.css"));
+    writeFileSync(join(proj, "index.html"), readFileSync(join(PACKS, packDir, file), "utf8"));
+    const p = spawn(hf[0], [...hf.slice(1), "lint", "--json", proj], { stdio: ["ignore", "pipe", "pipe"] });
+    let out = "", err = "";
+    p.stdout.on("data", (b) => (out += b));
+    p.stderr.on("data", (b) => (err += b));
+    p.on("close", (code) => {
+      rmSync(proj, { recursive: true, force: true });
+      let errors = null;
+      try {
+        const j = JSON.parse(out.slice(out.indexOf("{")));
+        const findings = j.findings ?? j.results ?? j.issues ?? [];
+        errors = typeof j.errorCount === "number" ? j.errorCount : findings.filter((f) => (f.severity ?? f.level) === "error").length;
+      } catch { errors = code === 0 ? 0 : null; }
+      done({ errors, code, detail: errors ? out.slice(0, 400) : err.slice(0, 200) });
+    });
+  });
+}
+
+async function lintAll() {
+  const hf = hfCommand(), jobs = Number(flag("--jobs", 6));
+  const summary = { "lint-ok": 0, broken: 0, "render-ok": 0, unknown: 0 };
+  const broken = [];
+  for (const d of packDirs()) {
+    const m = readManifest(d);
+    const queue = [...m.cards];
+    const worker = async () => {
+      for (let c = queue.shift(); c; c = queue.shift()) {
+        const r = await lintCard(hf, d, c.file);
+        if (r.errors === null) { summary.unknown++; continue; }
+        if (r.errors > 0) { c.qa = "broken"; broken.push({ id: c.id, errors: r.errors }); }
+        else if (c.qa !== "render-ok") c.qa = "lint-ok";
+        summary[c.qa]++;
+      }
+    };
+    await Promise.all(Array.from({ length: jobs }, worker));
+    writeManifest(d, m);
+  }
+  rebuild();
+  console.log(JSON.stringify({ summary, broken }, null, 2));
+  process.exitCode = summary.unknown ? 2 : 0;
+}
+
+function mark(status, ids) {
+  let n = 0;
+  for (const d of packDirs()) {
+    const m = readManifest(d);
+    for (const c of m.cards) if (ids.includes(c.id)) { c.qa = status; n++; }
+    writeManifest(d, m);
+  }
+  rebuild();
+  console.log(`marked ${n} card(s) ${status}`);
+}
+
+function sample(runDir) {
+  const run = resolve(runDir), comp = join(run, "composition");
+  mkdirSync(join(comp, "compositions"), { recursive: true });
+  const scenes = [];
+  for (const d of packDirs()) {
+    const m = readManifest(d), id = m.id;
+    cpSync(join(PACKS, d), join(comp, "cards", id), { recursive: true });
+    const seen = new Set();
+    for (const c of m.cards) {
+      const key = `${c.tier}.${c.purpose}`;
+      if (seen.has(key) || c.qa === "broken") continue;
+      seen.add(key);
+      const sceneId = c.id.replace(/\./g, "-");
+      const dur = c.duration?.min ?? 5;
+      const html = readFileSync(join(PACKS, d, c.file), "utf8");
+      writeFileSync(join(comp, "compositions", `${sceneId}.html`), html);
+      scenes.push({ id: sceneId, kind: "motion", duration: dur, composition: `compositions/${sceneId}.html`, line: c.id });
+    }
+  }
+  writeFileSync(join(run, "storyboard.json"), JSON.stringify({ version: 1, title: "Card QA sample", mode: "launch",
+    hyperframes: HF_VERSION, format: { width: 1920, height: 1080, fps: 30 }, scenes }, null, 2) + "\n");
+  console.log(JSON.stringify({ run, scenes: scenes.map((s) => s.line) }, null, 2));
+}
+
+const [cmd, ...rest] = args;
+if (cmd === "lint") await lintAll();
+else if (cmd === "mark" && rest.length > 1) mark(rest[0], rest.slice(1));
+else if (cmd === "sample" && rest[0]) sample(rest[0]);
+else { console.error("Usage: qa-cards.mjs lint [--pack id] [--jobs n] [--bin path] | mark <status> <id>... | sample <run-dir>"); process.exit(1); }

package/skills/luckiest-video-studio-cards/templates/glass-popout/DESIGN.md

@@ -0,0 +1,24 @@
+## Style Prompt
+
+Use The original edited-video glassmorphism look: crisp face-cam video, restrained dark frosted panels, white editorial text, rounded card edges, visible border highlights, and a heavy soft shadow. The motion should feel like a left-side information panel entering over a camera reframe, not like a full-screen takeover.
+
+## Colors
+
+- Canvas black: `#000000`
+- Glass base: `rgba(8, 14, 26, 0.62)`
+- Glass dim: `rgba(10, 18, 32, 0.58)`
+- Border highlight: `rgba(125, 211, 252, 0.18)`
+- Text: `#ffffff`
+- Accent: `#7dd3fc`
+
+## Typography
+
+- Primary: `sans-serif`
+- Label: `monospace`
+
+## What Not To Do
+
+- Do not cover the face in the center of the source frame.
+- Do not use a full-screen dark overlay.
+- Do not use decorative gradients behind the video.
+- Do not truncate the source video for this prototype.

package/skills/luckiest-video-studio-cards/templates/glass-popout/hyperframes.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://hyperframes.heygen.com/schema/hyperframes.json",
+  "paths": {
+    "blocks": "compositions",
+    "components": "compositions/components",
+    "assets": "assets"
+  }
+}