create-yss-spec 2.1.8 → 2.1.9

package/template/.codex/skills/web-video-presentation/templates/src/components/ProgressBar.tsx

@@ -1,109 +0,0 @@
-import { useEffect, useRef } from "react";
-import type { ChapterDef } from "../registry/types";
-import "./ProgressBar.css";
-
-interface Props {
-  chapters: ChapterDef[];
-  cursor: { chapter: number; step: number };
-  onJumpChapter(idx: number, step?: number): void;
-  /**
-   * Optional GitHub link rendered next to the bar; reveals/hides together
-   * with the chapter list on hover. Pass `null` to hide.
-   */
-  githubUrl?: string | null;
-}
-
-const DEFAULT_GITHUB_URL =
-  "https://github.com/ConardLi/garden-skills";
-
-/**
- * Hidden-on-hover progress bar, fixed to the bottom of the viewport.
- * Click chapter pill or pip to jump.
- *
- * Width is content-adaptive and capped at `100vw - 32px`; if total chapters
- * (or an active chapter's step pips) overflow, the bar scrolls horizontally
- * instead of squeezing items. The active chapter is auto-scrolled into view
- * on chapter change so it's visible the moment hover reveals the bar.
- *
- * A GitHub link sits to the right of the viewport, sharing the same hover
- * trigger so it appears/disappears in sync with the bar.
- */
-export function ProgressBar({
-  chapters,
-  cursor,
-  onJumpChapter,
-  githubUrl = DEFAULT_GITHUB_URL,
-}: Props) {
-  const activeRef = useRef<HTMLButtonElement | null>(null);
-
-  useEffect(() => {
-    activeRef.current?.scrollIntoView({
-      behavior: "smooth",
-      block: "nearest",
-      inline: "center",
-    });
-  }, [cursor.chapter]);
-
-  return (
-    <div className="pb-hover" data-no-advance>
-      <div className="pb">
-        {chapters.map((c, i) => {
-          const isActive = i === cursor.chapter;
-          return (
-            <button
-              key={c.id}
-              ref={isActive ? activeRef : undefined}
-              className={`pb-chapter ${isActive ? "pb-active" : ""}`}
-              onClick={(e) => {
-                e.stopPropagation();
-                onJumpChapter(i, 0);
-              }}
-            >
-              <span className="pb-num">{String(i + 1).padStart(2, "0")}</span>
-              <span className="pb-title">{c.title}</span>
-              {isActive && (
-                <div className="pb-pips">
-                  {Array.from({ length: c.narrations.length }, (_, s) => (
-                    <span
-                      key={s}
-                      className={`pb-pip ${
-                        s <= cursor.step ? "pb-pip-on" : ""
-                      }`}
-                      onClick={(e) => {
-                        e.stopPropagation();
-                        onJumpChapter(i, s);
-                      }}
-                    />
-                  ))}
-                </div>
-              )}
-            </button>
-          );
-        })}
-      </div>
-      {githubUrl && (
-        <a
-          className="pb-github"
-          href={githubUrl}
-          target="_blank"
-          rel="noopener noreferrer"
-          aria-label="View source on GitHub"
-          onClick={(e) => e.stopPropagation()}
-        >
-          <svg
-            viewBox="0 0 24 24"
-            width="20"
-            height="20"
-            aria-hidden="true"
-            focusable="false"
-          >
-            <path
-              fill="currentColor"
-              d="M12 .5C5.65.5.5 5.65.5 12.02c0 5.08 3.29 9.39 7.86 10.91.58.11.79-.25.79-.56 0-.27-.01-1-.02-1.96-3.2.7-3.87-1.54-3.87-1.54-.52-1.33-1.28-1.69-1.28-1.69-1.04-.71.08-.7.08-.7 1.16.08 1.77 1.19 1.77 1.19 1.03 1.76 2.7 1.25 3.36.96.1-.75.4-1.25.73-1.54-2.55-.29-5.24-1.28-5.24-5.69 0-1.26.45-2.29 1.18-3.1-.12-.29-.51-1.46.11-3.04 0 0 .97-.31 3.18 1.18a11 11 0 0 1 5.79 0c2.2-1.49 3.17-1.18 3.17-1.18.63 1.58.23 2.75.12 3.04.74.81 1.18 1.84 1.18 3.1 0 4.42-2.69 5.39-5.25 5.68.41.36.78 1.06.78 2.13 0 1.54-.01 2.78-.01 3.16 0 .31.21.68.8.56 4.56-1.52 7.85-5.83 7.85-10.91C23.5 5.65 18.35.5 12 .5Z"
-            />
-          </svg>
-        </a>
-      )}
-    </div>
-  );
-}

package/template/.codex/skills/web-video-presentation/templates/src/components/Stage.tsx

@@ -1,48 +0,0 @@
-import type { CSSProperties, ReactNode } from "react";
-import { useStageScale } from "../hooks/useStageScale";
-
-interface Props {
-  onAdvance(): void;
-  children: ReactNode;
-}
-
-/**
- * The 16:9 stage. Click anywhere except interactive children = advance.
- *
- * Layout structure (3 nested elements):
- *   .app-shell    ← full viewport, flex-centers the fitter
- *   .stage-fitter ← sized to ACTUAL VISIBLE px (1920*scale × 1080*scale)
- *                   so the layout system honestly sees what's on screen
- *                   and centers it bulletproof on every viewport / DPR.
- *   .stage-frame  ← raw 1920×1080 box, scaled from top-left into the fitter.
- *
- * Surface colors come from the active theme's CSS custom properties
- * (var(--shell), var(--surface)) — see themes/<id>/tokens.css.
- */
-export function Stage({ onAdvance, children }: Props) {
-  const scale = useStageScale();
-  const fitterStyle: CSSProperties = {
-    width: 1920 * scale,
-    height: 1080 * scale,
-  };
-  const frameStyle: CSSProperties = {
-    transform: `scale(${scale})`,
-  };
-  return (
-    <div className="app-shell">
-      <div className="stage-fitter" style={fitterStyle}>
-        <div
-          className="stage-frame"
-          style={frameStyle}
-          onClick={(e) => {
-            const t = e.target as HTMLElement;
-            if (t.closest("button, a, input, [data-no-advance]")) return;
-            onAdvance();
-          }}
-        >
-          {children}
-        </div>
-      </div>
-    </div>
-  );
-}

package/template/.codex/skills/web-video-presentation/templates/src/hooks/useAudioPlayer.ts

@@ -1,112 +0,0 @@
-import { useEffect, useRef } from "react";
-
-export type PlaybackMode = "manual" | "audio" | "auto";
-
-interface Options {
-  /** Audio file path. `null` = no audio for this step (silent). */
-  src: string | null;
-  /** `manual` = no playback. `audio` = play but don't auto-advance.
-   *  `auto` = play and auto-advance when finished. */
-  mode: PlaybackMode;
-  /** Small breathing pad (ms) after audio finishes before advancing,
-   *  in `auto` mode. Default 200ms. Set to 0 if mp3 already has trailing
-   *  silence. */
-  trailMs?: number;
-  /** Fallback duration (ms) for `auto` mode when the audio file is missing
-   *  or fails to play. Typically computed from text length. */
-  estimateFallbackMs?: number;
-  /** Called when `auto` mode determines the step is finished. */
-  onAutoAdvance: () => void;
-  /** Has the user started auto playback? (Browsers block autoplay until
-   *  the page receives a user gesture; the AutoStartGate flips this.) */
-  autoStarted: boolean;
-}
-
-/**
- * Per-step audio playback for the presentation.
- *
- * Manages a single hidden `<audio>` element. Switches `src` whenever the
- * current step changes.
- *
- * In `auto` mode:
- *   • Audio file present → advance `trailMs` after the audio's `ended` event.
- *   • Audio file missing / blocked / src = null → advance after
- *     `estimateFallbackMs` (so previews and silent steps still work).
- *
- * Audio playback is the sole driver of step duration — there is intentionally
- * no "minimum hold" knob. If a chapter's visual animation needs more time,
- * the chapter should write longer narration, split the step, or speed the
- * animation up. This keeps Auto-mode behavior trivially predictable.
- */
-export function useAudioPlayer({
-  src,
-  mode,
-  trailMs = 200,
-  estimateFallbackMs = 1500,
-  onAutoAdvance,
-  autoStarted,
-}: Options) {
-  const audioRef = useRef<HTMLAudioElement | null>(null);
-  // Latest callback ref so timers don't capture stale closures.
-  const onAdvanceRef = useRef(onAutoAdvance);
-  onAdvanceRef.current = onAutoAdvance;
-
-  useEffect(() => {
-    const prev = audioRef.current;
-    if (prev) {
-      prev.pause();
-      prev.removeAttribute("src");
-      prev.load();
-      audioRef.current = null;
-    }
-
-    if (mode === "manual") return;
-    if (mode === "auto" && !autoStarted) return;
-
-    let advanced = false;
-    let timer: number | null = null;
-
-    const advanceAfter = (ms: number) => {
-      if (mode !== "auto" || advanced) return;
-      timer = window.setTimeout(() => {
-        if (advanced) return;
-        advanced = true;
-        onAdvanceRef.current();
-      }, Math.max(0, ms));
-    };
-
-    if (src) {
-      const audio = new Audio(src);
-      audioRef.current = audio;
-      audio.preload = "auto";
-
-      audio.addEventListener("ended", () => advanceAfter(trailMs));
-      audio.addEventListener("error", () => {
-        // Audio file missing or undecodable — fall back to estimate.
-        if (mode === "auto") advanceAfter(estimateFallbackMs);
-      });
-
-      audio.play().catch((err) => {
-        // Autoplay blocked (rare, AutoStartGate should prevent this) or
-        // file missing — fall back to estimate in auto mode.
-        console.warn("audio play failed:", err);
-        if (mode === "auto") advanceAfter(estimateFallbackMs);
-      });
-    } else if (mode === "auto") {
-      // No audio for this step (silent / empty narration) — use estimate.
-      advanceAfter(estimateFallbackMs);
-    }
-
-    return () => {
-      advanced = true;
-      if (timer != null) clearTimeout(timer);
-      const a = audioRef.current;
-      if (a) {
-        a.pause();
-        a.removeAttribute("src");
-        a.load();
-        audioRef.current = null;
-      }
-    };
-  }, [src, mode, trailMs, estimateFallbackMs, autoStarted]);
-}

package/template/.codex/skills/web-video-presentation/templates/src/hooks/useAutoMode.ts

@@ -1,66 +0,0 @@
-import { useCallback, useEffect, useState } from "react";
-import type { PlaybackMode } from "./useAudioPlayer";
-
-const ORDER: PlaybackMode[] = ["manual", "audio", "auto"];
-
-function readModeFromURL(): PlaybackMode {
-  if (typeof window === "undefined") return "manual";
-  const q = new URLSearchParams(window.location.search);
-  if (q.get("auto") === "1") return "auto";
-  if (q.get("audio") === "1") return "audio";
-  return "manual";
-}
-
-/**
- * Playback mode state machine + URL sync + keyboard toggle.
- *
- * Modes:
- *   • `manual` — silent, you click / arrow-key to advance
- *   • `audio`  — audio plays per step, but you still click to advance
- *   • `auto`   — audio plays AND advances automatically (full recording mode)
- *
- * Initial mode is read from URL: `?auto=1` or `?audio=1`. Press `M` to
- * cycle: manual → audio → auto → manual. URL stays in sync so reload
- * preserves the mode.
- *
- * `autoStarted` exists separately because browsers require a user gesture
- * before audio can autoplay — `AutoStartGate` flips it on space-press.
- */
-export function useAutoMode() {
-  const [mode, setModeState] = useState<PlaybackMode>(() => readModeFromURL());
-  const [autoStarted, setAutoStarted] = useState(false);
-
-  const setMode = useCallback((m: PlaybackMode) => {
-    setModeState(m);
-    if (typeof window === "undefined") return;
-    const url = new URL(window.location.href);
-    url.searchParams.delete("audio");
-    url.searchParams.delete("auto");
-    if (m === "audio") url.searchParams.set("audio", "1");
-    if (m === "auto") url.searchParams.set("auto", "1");
-    window.history.replaceState(null, "", url.toString());
-    if (m !== "auto") setAutoStarted(false);
-  }, []);
-
-  const cycleMode = useCallback(() => {
-    setMode(ORDER[(ORDER.indexOf(mode) + 1) % ORDER.length]!);
-  }, [mode, setMode]);
-
-  // Keyboard: `M` cycles mode. `Space` starts auto if gated.
-  useEffect(() => {
-    const onKey = (e: KeyboardEvent) => {
-      if (e.target instanceof HTMLInputElement) return;
-      if (e.key === "m" || e.key === "M") {
-        e.preventDefault();
-        cycleMode();
-      } else if (e.key === " " && mode === "auto" && !autoStarted) {
-        e.preventDefault();
-        setAutoStarted(true);
-      }
-    };
-    window.addEventListener("keydown", onKey);
-    return () => window.removeEventListener("keydown", onKey);
-  }, [mode, autoStarted, cycleMode]);
-
-  return { mode, setMode, cycleMode, autoStarted, setAutoStarted };
-}

package/template/.codex/skills/web-video-presentation/templates/src/hooks/useStageScale.ts

@@ -1,28 +0,0 @@
-import { useEffect, useState } from "react";
-
-/**
- * Compute the scale needed to fit a 1920x1080 stage inside the current
- * viewport, leaving `marginX` / `marginY` of breathing room around it
- * (so absolutely-positioned UI like the progress bar isn't cropped).
- */
-export function useStageScale(
-  baseW = 1920,
-  baseH = 1080,
-  marginX = 80,
-  marginY = 100,
-) {
-  const [scale, setScale] = useState(1);
-
-  useEffect(() => {
-    function update() {
-      const usefulW = Math.max(320, window.innerWidth - marginX * 2);
-      const usefulH = Math.max(180, window.innerHeight - marginY * 2);
-      setScale(Math.min(usefulW / baseW, usefulH / baseH));
-    }
-    update();
-    window.addEventListener("resize", update);
-    return () => window.removeEventListener("resize", update);
-  }, [baseW, baseH, marginX, marginY]);
-
-  return scale;
-}

package/template/.codex/skills/web-video-presentation/templates/src/hooks/useStepper.ts

@@ -1,174 +0,0 @@
-import { useCallback, useEffect, useMemo, useState } from "react";
-import type { ChapterDef } from "../registry/types";
-
-/**
- * Bump this when chapter step counts / structure change so old persisted
- * cursors don't land mid-removed-step.
- */
-const STORAGE_KEY = "presentation-cursor-v4";
-
-export type Cursor = { chapter: number; step: number };
-
-export interface StepperState {
-  cursor: Cursor;
-  totalChapters: number;
-  chapterTotalSteps: number;
-  globalIndex: number;
-  totalGlobal: number;
-  next(): void;
-  prev(): void;
-  jumpToChapter(idx: number, step?: number): void;
-  jumpToGlobal(globalIdx: number): void;
-}
-
-const clamp = (n: number, lo: number, hi: number) =>
-  Math.max(lo, Math.min(hi, n));
-
-/**
- * Clamp a (possibly stale) cursor to the current chapter list. Persisted
- * cursors can outlive structural changes — fewer chapters, fewer steps,
- * a different scaffolded project sharing the same dev-server origin — so
- * we always re-validate before handing one to React.
- */
-function sanitize(cursor: Cursor, chapters: ChapterDef[]): Cursor {
-  if (chapters.length === 0) return { chapter: 0, step: 0 };
-  const chapter = clamp(cursor.chapter | 0, 0, chapters.length - 1);
-  const stepCount = chapters[chapter]!.narrations.length;
-  const step = clamp(cursor.step | 0, 0, Math.max(0, stepCount - 1));
-  return { chapter, step };
-}
-
-export function useStepper(chapters: ChapterDef[]): StepperState {
-  const [cursor, setCursor] = useState<Cursor>(() => {
-    const fallback = { chapter: 0, step: 0 };
-    if (typeof window === "undefined") return fallback;
-    try {
-      const raw = window.localStorage.getItem(STORAGE_KEY);
-      if (raw) return sanitize(JSON.parse(raw), chapters);
-    } catch {
-      /* ignore */
-    }
-    return fallback;
-  });
-
-  // Re-sanitize if the chapter list shape changes after mount (e.g. HMR
-  // updates `chapters.ts`) — keeps a stale persisted cursor from leaking
-  // into a render where it's now out of range.
-  useEffect(() => {
-    setCursor((cur) => {
-      const next = sanitize(cur, chapters);
-      return next.chapter === cur.chapter && next.step === cur.step
-        ? cur
-        : next;
-    });
-  }, [chapters]);
-
-  useEffect(() => {
-    try {
-      window.localStorage.setItem(STORAGE_KEY, JSON.stringify(cursor));
-    } catch {
-      /* ignore */
-    }
-  }, [cursor]);
-
-  const offsets = useMemo(() => {
-    const arr: number[] = [];
-    let acc = 0;
-    for (const c of chapters) {
-      arr.push(acc);
-      acc += c.narrations.length;
-    }
-    return arr;
-  }, [chapters]);
-  const totalGlobal = useMemo(
-    () => chapters.reduce((s, c) => s + c.narrations.length, 0),
-    [chapters],
-  );
-  const globalIndex = (offsets[cursor.chapter] ?? 0) + cursor.step;
-
-  const next = useCallback(() => {
-    setCursor((cur) => {
-      const c = chapters[cur.chapter]!;
-      if (cur.step < c.narrations.length - 1)
-        return { ...cur, step: cur.step + 1 };
-      if (cur.chapter < chapters.length - 1)
-        return { chapter: cur.chapter + 1, step: 0 };
-      return cur;
-    });
-  }, [chapters]);
-
-  const prev = useCallback(() => {
-    setCursor((cur) => {
-      if (cur.step > 0) return { ...cur, step: cur.step - 1 };
-      if (cur.chapter > 0) {
-        const p = chapters[cur.chapter - 1]!;
-        return { chapter: cur.chapter - 1, step: p.narrations.length - 1 };
-      }
-      return cur;
-    });
-  }, [chapters]);
-
-  const jumpToChapter = useCallback(
-    (idx: number, step = 0) => {
-      const ch = clamp(idx, 0, chapters.length - 1);
-      const c = chapters[ch]!;
-      setCursor({
-        chapter: ch,
-        step: clamp(step, 0, c.narrations.length - 1),
-      });
-    },
-    [chapters],
-  );
-
-  const jumpToGlobal = useCallback(
-    (g: number) => {
-      const target = clamp(g, 0, totalGlobal - 1);
-      let acc = 0;
-      for (let i = 0; i < chapters.length; i++) {
-        const t = chapters[i]!.narrations.length;
-        if (target < acc + t) {
-          setCursor({ chapter: i, step: target - acc });
-          return;
-        }
-        acc += t;
-      }
-    },
-    [chapters, totalGlobal],
-  );
-
-  useEffect(() => {
-    const onKey = (e: KeyboardEvent) => {
-      if (e.target instanceof HTMLInputElement) return;
-      if (e.key === "ArrowRight" || e.key === " ") {
-        e.preventDefault();
-        next();
-      } else if (e.key === "ArrowLeft" || e.key === "Backspace") {
-        e.preventDefault();
-        prev();
-      } else if (e.key === "Home") {
-        jumpToChapter(0, 0);
-      } else if (e.key === "End") {
-        const last = chapters.length - 1;
-        jumpToChapter(last, chapters[last]!.narrations.length - 1);
-      } else if (e.key >= "1" && e.key <= "9") {
-        const n = Number(e.key) - 1;
-        if (n < chapters.length) jumpToChapter(n, 0);
-      }
-    };
-    window.addEventListener("keydown", onKey);
-    return () => window.removeEventListener("keydown", onKey);
-  }, [next, prev, jumpToChapter, chapters]);
-
-  const ch = chapters[cursor.chapter]!;
-  return {
-    cursor,
-    totalChapters: chapters.length,
-    chapterTotalSteps: ch.narrations.length,
-    globalIndex,
-    totalGlobal,
-    next,
-    prev,
-    jumpToChapter,
-    jumpToGlobal,
-  };
-}

package/template/.codex/skills/web-video-presentation/templates/src/main.tsx

@@ -1,9 +0,0 @@
-import { StrictMode } from "react";
-import { createRoot } from "react-dom/client";
-import App from "./App";
-
-createRoot(document.getElementById("root")!).render(
-  <StrictMode>
-    <App />
-  </StrictMode>,
-);

package/template/.codex/skills/web-video-presentation/templates/src/registry/chapters.ts

@@ -1,23 +0,0 @@
-import type { ChapterDef } from "./types";
-import ExampleChapter from "../chapters/01-example/Example";
-import { narrations as exampleNarrations } from "../chapters/01-example/narrations";
-
-/**
- * Order = order of presentation.
- *
- * Each chapter MUST provide a `narrations: Narration[]` array. Its length
- * is the chapter's step count — there is no `totalSteps` to maintain
- * separately. This guarantees the audio synthesis pipeline, the runtime
- * stepper, and the chapter `.tsx` switch on `step` cannot drift apart.
- *
- * Visual styling (color, fonts) comes entirely from the active theme —
- * chapters never hard-code palette / font names. See THEMES.md.
- */
-export const CHAPTERS: ChapterDef[] = [
-  {
-    id: "example",
-    title: "示例章节",
-    narrations: exampleNarrations,
-    Component: ExampleChapter,
-  },
-];

package/template/.codex/skills/web-video-presentation/templates/src/registry/types.ts

@@ -1,25 +0,0 @@
-import type { ComponentType } from "react";
-
-export interface ChapterStepProps {
-  step: number; // 0..(narrations.length - 1)
-}
-
-/**
- * One narration entry — the spoken text for that step.
- *
- * Empty string ("") means "no audio for this step" (e.g. silent transition
- * shot). Auto mode falls back to a short estimate when audio is missing or
- * the text is empty.
- */
-export type Narration = string;
-
-export interface ChapterDef {
-  id: string;
-  title: string;
-  /**
-   * Per-step narration text. **Length === total steps in this chapter.**
-   * This is the single source of truth for step count and audio synthesis.
-   */
-  narrations: Narration[];
-  Component: ComponentType<ChapterStepProps>;
-}

package/template/.codex/skills/web-video-presentation/templates/src/styles/animations.css

@@ -1,63 +0,0 @@
-/* ─────────────────────────────────────────────────────────────────────
- * animations.css — generic, theme-agnostic motion vocabulary.
- *
- * All durations / easings come from the active theme's tokens.
- * ───────────────────────────────────────────────────────────────────── */
-
-/* MaskReveal — clip-path text wipe (left → right) */
-.mask-reveal {
-  clip-path: inset(0 100% 0 0);
-  transition: clip-path 700ms var(--ease-quart);
-}
-.mask-reveal.in { clip-path: inset(0 0 0 0); }
-
-/* Hairline rule grow — scaleX from 0 → 1, transform-origin: left */
-.rule-grow {
-  transform: scaleX(0);
-  transform-origin: left;
-  transition: transform var(--dur-cinematic) var(--ease-expo);
-}
-.rule-grow.in { transform: scaleX(1); }
-
-/* Generic vertical rise + opacity (small UI labels, captions) */
-@keyframes rise-in {
-  from { opacity: 0; transform: translateY(14px); }
-  to   { opacity: 1; transform: translateY(0); }
-}
-
-/* Scale-in with overshoot (use for stamp / badge / accent moment) */
-@keyframes scale-in {
-  0%   { opacity: 0; transform: scale(0.8); }
-  60%  { opacity: 1; transform: scale(1.04); }
-  100% { opacity: 1; transform: scale(1); }
-}
-
-/* Pop with overshoot ease (more spring) */
-@keyframes pop-in {
-  0%   { opacity: 0; transform: scale(0.6) rotate(-2deg); }
-  100% { opacity: 1; transform: scale(1) rotate(0); }
-}
-
-/* Caret blink (bounded — for use INSIDE a sized animation) */
-@keyframes caret-blink {
-  50% { opacity: 0; }
-}
-
-/* Slow-pulse halo (rings, notifications) */
-@keyframes pulse-halo {
-  0%   { opacity: 0.6; transform: scale(0.9); }
-  70%  { opacity: 0;   transform: scale(1.6); }
-  100% { opacity: 0;   transform: scale(1.6); }
-}
-
-/* Letter stagger (use with .letter-stagger > .letter, set --i: 0..n) */
-.letter-stagger > .letter {
-  display: inline-block;
-  opacity: 0;
-  transform: translateY(40px) scale(0.85);
-  animation: letter-rise var(--dur-slow) var(--ease-expo) forwards;
-  animation-delay: calc(var(--i, 0) * 60ms);
-}
-@keyframes letter-rise {
-  to { opacity: 1; transform: translateY(0) scale(1); }
-}