@bovinphang/frontend-craft 2.6.0 → 2.7.0

package/skills/fec-web-video-presentation/references/chapter-craft.md

@@ -0,0 +1,37 @@
+# Chapter Craft
+
+## Stage Rules
+
+- Use a fixed 16:9 stage, normally 1920 by 1080, scaled to the viewport.
+- A chapter is a pure function of the current step.
+- One step should focus on one visual idea.
+- Lists reveal one meaningful item at a time.
+- Use hidden or low-emphasis controls so the recording surface stays clean.
+- Keep large text readable when screen-recorded and compressed.
+
+## Visual Decisions
+
+Before implementing a chapter, answer:
+
+- What is the relationship between this step and the previous step: contrast, reveal, zoom, sequence, proof, consequence, or recap?
+- What should the viewer remember after this step?
+- Which source detail makes the screen more specific than a generic slide?
+- Is this a diagram, object, quote, metric, timeline, interface state, or spatial metaphor?
+- What can move because the content itself changes, rather than because everything needs an entrance animation?
+
+## Anti-Patterns
+
+- Synchronized stagger of many bullets when the narration discusses them one by one.
+- Purple gradient backgrounds, floating decoration, or generic cards that do not explain the content.
+- Fake dashboards, fake screenshots, fake citations, or invented metrics.
+- Tiny body text that looks fine in a browser but fails in recorded video.
+- Persistent chrome, large page numbers, or visible instructions in the recording frame.
+
+## Completion Check
+
+- Every step renders a complete screen.
+- Text fits at the target stage size.
+- The chapter still makes sense if the recording pauses on any step.
+- Visual state follows narration order.
+- Any media used is local, real, generated for the task, or clearly marked as a placeholder.
+- Keyboard and click navigation still work after the chapter is registered.

package/skills/fec-web-video-presentation/references/content-plan.md

@@ -0,0 +1,38 @@
+# Content Plan
+
+## Script
+
+Use the same language as the source material unless the user asks otherwise. Convert written text into spoken wording, but keep the author's claims, order, names, and important numbers intact.
+
+For every script:
+
+- Keep one idea per beat.
+- Remove footnote-like detours unless they are central to the story.
+- Mark uncertain facts instead of smoothing them into confident claims.
+- Keep technical names exact.
+- Prefer short sentences that can be spoken without rereading.
+
+## Outline
+
+The outline is the implementation contract for the web presentation.
+
+Include:
+
+- Title and intended audience.
+- Total target duration.
+- Chapters with stable ids.
+- Step count per chapter.
+- One screen task per step.
+- Content pool per chapter: facts, numbers, quotes, examples, media, diagrams, or UI states available for visuals.
+- Asset list with owner, path, missing status, and replacement strategy.
+
+Avoid:
+
+- Naming concrete animations too early.
+- Specifying CSS implementation details.
+- Stuffing several list items into one step when they need separate attention.
+- Adding unsupported claims just to make a scene feel full.
+
+## Acceptance
+
+A content plan is ready when another implementer can build the presentation without deciding what each chapter says, what each step reveals, or which source facts are available for visuals.

package/skills/fec-web-video-presentation/references/recording-and-audio.md

@@ -0,0 +1,33 @@
+# Recording And Audio
+
+## Recording Modes
+
+Manual mode:
+
+- Click, Space, ArrowRight, or PageDown advances one step.
+- ArrowLeft or PageUp goes back.
+- Best when a human narrator is recording live.
+
+Auto mode:
+
+- Uses per-step durations from the project data.
+- Best when narration audio is already aligned or when making a clean screen capture.
+
+## Recording Checklist
+
+- Browser console has no errors.
+- Stage is centered and scaled without distortion.
+- No horizontal or vertical scrollbars appear inside the capture frame.
+- Controls are hidden unless hovered or focused.
+- Current step persists only when helpful; reset it after changing chapter order or step count.
+- Record a 10 second sample before doing the full take.
+
+## Audio Policy
+
+Audio is optional. A project may use:
+
+- Existing narration files from the user.
+- Host-native TTS or voiceover tools.
+- A project-owned TTS pipeline.
+
+Keep audio alignment provider-neutral. Store segment text and file paths in project data, but do not encode a vendor-specific API contract into the skill.

package/skills/fec-web-video-presentation/references/theme-system.md

@@ -0,0 +1,36 @@
+# Theme System
+
+Themes are starting points, not templates. A theme defines the visual climate of the recording surface while leaving chapters free to create content-specific layouts.
+
+## Token Roles
+
+Use semantic CSS variables:
+
+- `--stage-bg`
+- `--stage-fg`
+- `--muted-fg`
+- `--accent`
+- `--accent-2`
+- `--panel`
+- `--line`
+- `--shadow`
+- `--font-display`
+- `--font-body`
+- `--radius`
+- `--step-duration`
+
+## Starter Theme Policy
+
+The bundled starter themes are intentionally few:
+
+- Use them to create a runnable skeleton.
+- Replace colors and type choices when a real brand or product context exists.
+- Do not let all chapters become identical; keep typography and color coherent while varying layout and visual devices per chapter.
+
+## Custom Theme Checklist
+
+- Contrast passes for recorded text.
+- Accent colors have different semantic jobs.
+- Background supports compression without muddy gradients.
+- Typography remains readable at 1080p and in lower-resolution reuploads.
+- Motion can be reduced without destroying meaning.

package/skills/fec-web-video-presentation/scripts/create-video-presentation.mjs

@@ -0,0 +1,430 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const skillDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const themesPath = path.join(skillDir, "data", "starter-themes.json");
+const themes = JSON.parse(fs.readFileSync(themesPath, "utf8"));
+
+const args = process.argv.slice(2);
+const options = parseArgs(args);
+
+if (options.help) {
+  printHelp();
+  process.exit(0);
+}
+
+if (options.listThemes) {
+  for (const theme of themes) {
+    console.log(`${theme.id}\t${theme.name}\t${theme.bestFor}`);
+  }
+  process.exit(0);
+}
+
+const target = path.resolve(process.cwd(), options.target ?? "presentation");
+const theme = themes.find((candidate) => candidate.id === options.theme);
+
+if (!theme) {
+  fail(`Unknown theme "${options.theme}". Run with --list-themes to see available themes.`);
+}
+
+const files = buildFiles(theme);
+
+if (options.dryRun) {
+  console.log(`Would create ${files.length} files in ${target}`);
+  console.log(`Theme: ${theme.id} (${theme.name})`);
+  for (const file of files) console.log(`- ${file.name}`);
+  process.exit(0);
+}
+
+if (fs.existsSync(target) && fs.readdirSync(target).length > 0) {
+  fail(`Target directory is not empty: ${target}`);
+}
+
+for (const file of files) {
+  const fullPath = path.join(target, file.name);
+  fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+  fs.writeFileSync(fullPath, file.body, "utf8");
+}
+
+console.log(`Created web video presentation at ${target}`);
+console.log(`Theme: ${theme.id} (${theme.name})`);
+console.log("Next:");
+console.log("  cd " + path.relative(process.cwd(), target));
+console.log("  npm install");
+console.log("  npm run dev");
+
+function parseArgs(values) {
+  const out = {
+    dryRun: false,
+    help: false,
+    listThemes: false,
+    target: undefined,
+    theme: themes[0]?.id ?? "editorial-slate",
+  };
+
+  for (let index = 0; index < values.length; index += 1) {
+    const value = values[index];
+    if (value === "--help" || value === "-h") out.help = true;
+    else if (value === "--dry-run") out.dryRun = true;
+    else if (value === "--list-themes") out.listThemes = true;
+    else if (value.startsWith("--theme=")) out.theme = value.slice("--theme=".length);
+    else if (value === "--theme") {
+      const next = values[index + 1];
+      if (!next || next.startsWith("--")) fail("Missing value for --theme.");
+      out.theme = next;
+      index += 1;
+    }
+    else if (value.startsWith("--")) fail(`Unknown option: ${value}`);
+    else if (!out.target) out.target = value;
+    else fail(`Unexpected argument: ${value}`);
+  }
+
+  return out;
+}
+
+function buildFiles(theme) {
+  const tokenCss = renderTokens(theme.tokens);
+  return [
+    {
+      name: "package.json",
+      body: JSON.stringify(
+        {
+          scripts: {
+            dev: "vite",
+            build: "tsc --noEmit && vite build",
+            preview: "vite preview",
+          },
+          dependencies: {
+            react: "latest",
+            "react-dom": "latest",
+          },
+          devDependencies: {
+            "@types/react": "latest",
+            "@types/react-dom": "latest",
+            "@vitejs/plugin-react": "latest",
+            typescript: "latest",
+            vite: "latest",
+          },
+        },
+        null,
+        2,
+      ) + "\n",
+    },
+    {
+      name: "index.html",
+      body: `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Web Video Presentation</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+`,
+    },
+    {
+      name: "tsconfig.json",
+      body: JSON.stringify(
+        {
+          compilerOptions: {
+            target: "ES2022",
+            useDefineForClassFields: true,
+            lib: ["DOM", "DOM.Iterable", "ES2022"],
+            allowJs: false,
+            skipLibCheck: true,
+            esModuleInterop: true,
+            allowSyntheticDefaultImports: true,
+            strict: true,
+            forceConsistentCasingInFileNames: true,
+            module: "ESNext",
+            moduleResolution: "Node",
+            resolveJsonModule: true,
+            isolatedModules: true,
+            noEmit: true,
+            jsx: "react-jsx",
+          },
+          include: ["src"],
+        },
+        null,
+        2,
+      ) + "\n",
+    },
+    {
+      name: "vite.config.ts",
+      body: `import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+});
+`,
+    },
+    {
+      name: "src/main.tsx",
+      body: `import React, { useEffect, useMemo, useState } from 'react';
+import { createRoot } from 'react-dom/client';
+import './styles.css';
+
+type Scene = {
+  eyebrow: string;
+  title: string;
+  body: string;
+  detail: string;
+};
+
+const scenes: Scene[] = [
+  {
+    eyebrow: '01 / Hook',
+    title: 'Replace this with the first spoken beat',
+    body: 'One step equals one idea. Keep it readable in a 1080p recording.',
+    detail: 'Use source facts, product states, diagrams, or real assets to make the screen specific.',
+  },
+  {
+    eyebrow: '02 / Proof',
+    title: 'Show the evidence, not a generic slide',
+    body: 'Turn a claim into a visual: timeline, interface state, metric, map, comparison, or system diagram.',
+    detail: 'Advance with Space, ArrowRight, PageDown, or click. Go back with ArrowLeft or PageUp.',
+  },
+  {
+    eyebrow: '03 / Close',
+    title: 'End on the idea the viewer should remember',
+    body: 'Swap this starter content for your script and outline.',
+    detail: 'Controls stay quiet so the stage is clean for recording.',
+  },
+];
+
+const storageKey = 'fec-web-video-presentation-step-v1';
+
+function App() {
+  const [step, setStep] = useState(() => Number(localStorage.getItem(storageKey) ?? 0));
+  const current = scenes[Math.min(Math.max(step, 0), scenes.length - 1)];
+  const progress = useMemo(() => ((step + 1) / scenes.length) * 100, [step]);
+
+  useEffect(() => {
+    localStorage.setItem(storageKey, String(step));
+  }, [step]);
+
+  useEffect(() => {
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'ArrowRight' || event.key === 'PageDown' || event.key === ' ') {
+        event.preventDefault();
+        setStep((value) => Math.min(value + 1, scenes.length - 1));
+      }
+      if (event.key === 'ArrowLeft' || event.key === 'PageUp') {
+        event.preventDefault();
+        setStep((value) => Math.max(value - 1, 0));
+      }
+      if (event.key.toLowerCase() === 'r') {
+        setStep(0);
+      }
+    };
+    window.addEventListener('keydown', onKeyDown);
+    return () => window.removeEventListener('keydown', onKeyDown);
+  }, []);
+
+  return (
+    <main className="viewport" onClick={() => setStep((value) => Math.min(value + 1, scenes.length - 1))}>
+      <section className="stage" aria-live="polite">
+        <div className="scene-grid">
+          <div className="copy">
+            <p className="eyebrow">{current.eyebrow}</p>
+            <h1>{current.title}</h1>
+            <p className="body">{current.body}</p>
+          </div>
+          <div className="visual" aria-label="Visual evidence placeholder">
+            <span>{String(step + 1).padStart(2, '0')}</span>
+            <p>{current.detail}</p>
+          </div>
+        </div>
+        <div className="progress" aria-hidden="true">
+          <span style={{ width: \`\${progress}%\` }} />
+        </div>
+      </section>
+    </main>
+  );
+}
+
+createRoot(document.getElementById('root')!).render(<App />);
+`,
+    },
+    {
+      name: "src/styles.css",
+      body: `${tokenCss}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body,
+#root {
+  margin: 0;
+  min-height: 100%;
+}
+
+body {
+  background: #111;
+  color: var(--stage-fg);
+  font-family: var(--font-body);
+}
+
+.viewport {
+  min-height: 100vh;
+  display: grid;
+  place-items: center;
+  padding: 24px;
+}
+
+.stage {
+  width: min(100vw - 48px, calc((100vh - 48px) * 16 / 9));
+  aspect-ratio: 16 / 9;
+  position: relative;
+  overflow: hidden;
+  background: var(--stage-bg);
+  color: var(--stage-fg);
+  box-shadow: var(--shadow);
+}
+
+.scene-grid {
+  height: 100%;
+  display: grid;
+  grid-template-columns: 1.12fr 0.88fr;
+  gap: 72px;
+  align-items: center;
+  padding: 96px;
+}
+
+.eyebrow {
+  color: var(--accent);
+  font-size: 24px;
+  font-weight: 700;
+  margin: 0 0 26px;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+}
+
+h1 {
+  font-family: var(--font-display);
+  font-size: clamp(48px, 6vw, 104px);
+  line-height: 0.96;
+  letter-spacing: 0;
+  margin: 0;
+  text-wrap: balance;
+}
+
+.body {
+  color: var(--muted-fg);
+  font-size: 32px;
+  line-height: 1.35;
+  margin: 36px 0 0;
+  max-width: 820px;
+  text-wrap: pretty;
+}
+
+.visual {
+  min-height: 560px;
+  border: 1px solid var(--line);
+  border-radius: var(--radius);
+  background: var(--panel);
+  display: grid;
+  align-content: space-between;
+  padding: 42px;
+}
+
+.visual span {
+  color: var(--accent-2);
+  font-family: var(--font-display);
+  font-size: 132px;
+  line-height: 1;
+  font-variant-numeric: tabular-nums;
+}
+
+.visual p {
+  margin: 0;
+  color: var(--muted-fg);
+  font-size: 26px;
+  line-height: 1.4;
+}
+
+.progress {
+  position: absolute;
+  left: 32px;
+  right: 32px;
+  bottom: 28px;
+  height: 3px;
+  background: color-mix(in srgb, var(--line) 70%, transparent);
+  opacity: 0;
+  transition: opacity 160ms ease;
+}
+
+.stage:hover .progress,
+.stage:focus-within .progress {
+  opacity: 1;
+}
+
+.progress span {
+  display: block;
+  height: 100%;
+  background: var(--accent);
+  transition: width var(--step-duration) ease;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .progress,
+  .progress span {
+    transition: none;
+  }
+}
+`,
+    },
+    {
+      name: "README.md",
+      body: `# Web Video Presentation
+
+Generated with Frontend Craft.
+
+- 16:9 browser recording stage
+- Step-driven scenes
+- Keyboard and click navigation
+- Theme tokens in \`src/styles.css\`
+
+Replace the starter scenes in \`src/main.tsx\` with your script and outline.
+`,
+    },
+  ];
+}
+
+function renderTokens(tokens) {
+  return `:root {
+  --stage-bg: ${tokens.stageBg};
+  --stage-fg: ${tokens.stageFg};
+  --muted-fg: ${tokens.mutedFg};
+  --accent: ${tokens.accent};
+  --accent-2: ${tokens.accent2};
+  --panel: ${tokens.panel};
+  --line: ${tokens.line};
+  --shadow: ${tokens.shadow};
+  --font-display: ${tokens.fontDisplay};
+  --font-body: ${tokens.fontBody};
+  --radius: ${tokens.radius};
+  --step-duration: ${tokens.stepDuration};
+}`;
+}
+
+function printHelp() {
+  console.log(`Usage:
+  node skills/fec-web-video-presentation/scripts/create-video-presentation.mjs [target] [--theme=<id>] [--dry-run]
+  node skills/fec-web-video-presentation/scripts/create-video-presentation.mjs --list-themes
+`);
+}
+
+function fail(message) {
+  console.error(`[create-video-presentation] ${message}`);
+  process.exit(1);
+}