create-yss-spec 1.0.0

package/template/.agents/skills/web-video-presentation/templates/scripts/tts-providers/openai.sh

@@ -0,0 +1,70 @@
+# ────────────────────────────────────────────────────────────────────
+# OpenAI TTS provider — uses the Audio Speech REST API via curl.
+#
+# Docs:    https://platform.openai.com/docs/api-reference/audio/createSpeech
+# Env:     OPENAI_API_KEY=sk-...     required
+#          OPENAI_BASE_URL=https://api.openai.com/v1   optional (for proxies / Azure-OpenAI)
+#          OPENAI_TTS_MODEL=tts-1    optional (tts-1 = fast, tts-1-hd = higher quality)
+# Voices:  alloy / echo / fable / onyx / nova / shimmer
+#          (default: alloy)
+#
+# Strengths: many agents already have OPENAI_API_KEY set; predictable
+# pricing; very fast.
+# ────────────────────────────────────────────────────────────────────
+
+tts_check() {
+  if ! command -v curl >/dev/null; then
+    echo "✗ curl not found in PATH." >&2
+    return 1
+  fi
+  if ! command -v jq >/dev/null; then
+    echo "✗ jq is required to build the request payload safely." >&2
+    return 1
+  fi
+  if [[ -z "${OPENAI_API_KEY:-}" ]]; then
+    echo "✗ OPENAI_API_KEY is not set." >&2
+    return 1
+  fi
+}
+
+tts_install_help() {
+  cat <<'EOF' >&2
+To use the OpenAI provider:
+
+  Set your key:    export OPENAI_API_KEY=sk-...
+                   (get one at https://platform.openai.com/api-keys)
+  Optional:        export OPENAI_BASE_URL=https://your-proxy/v1
+                   export OPENAI_TTS_MODEL=tts-1-hd   # higher quality, ~2× cost
+
+Install deps (only if missing):
+  curl  — brew install curl  / apt-get install curl
+  jq    — brew install jq    / apt-get install jq
+
+Or pick another provider:  PRESENTATION_TTS=<name> npm run synthesize-audio
+EOF
+}
+
+tts_synthesize() {
+  local text="$1"
+  local out="$2"
+  local voice="${3:-}"
+  [[ -z "$voice" ]] && voice="alloy"
+
+  local base="${OPENAI_BASE_URL:-https://api.openai.com/v1}"
+  local model="${OPENAI_TTS_MODEL:-tts-1}"
+
+  local payload
+  payload=$(jq -n \
+    --arg t "$text" \
+    --arg v "$voice" \
+    --arg m "$model" \
+    '{model:$m, input:$t, voice:$v, response_format:"mp3"}')
+
+  # On HTTP error curl with -f exits non-zero, runner marks FAILED.
+  # We capture stderr so a single segment's API error doesn't spam,
+  # but if every segment fails the user should run with `bash -x`.
+  curl -fsS -o "$out" -X POST "$base/audio/speech" \
+    -H "Authorization: Bearer $OPENAI_API_KEY" \
+    -H "Content-Type: application/json" \
+    -d "$payload" 2>/dev/null
+}

package/template/.agents/skills/web-video-presentation/templates/src/App.tsx

@@ -0,0 +1,73 @@
+import "./styles/fonts.css"; // Google Fonts for built-in themes
+import "./styles/tokens.css"; // active theme — generated by scaffold (see THEMES.md)
+import "./styles/base.css";
+import "./styles/animations.css";
+
+import { useCallback } from "react";
+import { AutoStartGate } from "./components/AutoStartGate";
+import { AutoToggle } from "./components/AutoToggle";
+import { ProgressBar } from "./components/ProgressBar";
+import { Stage } from "./components/Stage";
+import { useAudioPlayer } from "./hooks/useAudioPlayer";
+import { useAutoMode } from "./hooks/useAutoMode";
+import { useStepper } from "./hooks/useStepper";
+import { CHAPTERS } from "./registry/chapters";
+
+/**
+ * Estimate spoken duration of a Chinese narration string. Native pace
+ * ≈ 4 char/s → 250ms per char. Used as Auto-mode fallback ONLY when the
+ * audio file is missing / fails / the narration is empty. When audio plays
+ * normally, this value is unused — auto-advance fires on `audio.ended`.
+ */
+function estimateMs(text: string): number {
+  if (!text) return 1500;
+  return Math.max(1500, text.length * 250);
+}
+
+export default function App() {
+  const stepper = useStepper(CHAPTERS);
+  const ch = CHAPTERS[stepper.cursor.chapter]!;
+  const Cmp = ch.Component;
+  const stepText = ch.narrations[stepper.cursor.step] ?? "";
+
+  const { mode, cycleMode, autoStarted, setAutoStarted } = useAutoMode();
+
+  // Audio path follows the convention: /audio/<chapter-id>/<step+1>.mp3
+  // (1-indexed file names match what `extract-narrations.ts` outputs.)
+  // Empty narration → no audio src, Auto mode falls back to estimate.
+  const audioSrc =
+    mode === "manual" || stepText === ""
+      ? null
+      : `${import.meta.env.BASE_URL}audio/${ch.id}/${stepper.cursor.step + 1}.mp3`;
+
+  const onAutoAdvance = useCallback(() => stepper.next(), [stepper]);
+
+  useAudioPlayer({
+    src: audioSrc,
+    mode,
+    trailMs: 200,
+    estimateFallbackMs: estimateMs(stepText),
+    onAutoAdvance,
+    autoStarted,
+  });
+
+  return (
+    <>
+      <Stage onAdvance={stepper.next}>
+        <div key={ch.id} className="scene">
+          <Cmp step={stepper.cursor.step} />
+        </div>
+      </Stage>
+      <ProgressBar
+        chapters={CHAPTERS}
+        cursor={stepper.cursor}
+        onJumpChapter={stepper.jumpToChapter}
+      />
+      <AutoToggle mode={mode} onCycle={cycleMode} />
+      <AutoStartGate
+        visible={mode === "auto" && !autoStarted}
+        onStart={() => setAutoStarted(true)}
+      />
+    </>
+  );
+}

package/template/.agents/skills/web-video-presentation/templates/src/chapters/01-example/Example.css

@@ -0,0 +1,80 @@
+/* ─────────────────────────────────────────────────────────────────────
+ * Example chapter — uses ONLY semantic tokens from the active theme.
+ * Replace this file freely; it's just demo content.
+ * ───────────────────────────────────────────────────────────────────── */
+
+.ex-scene { color: var(--text); }
+
+.ex-em { color: var(--accent); }
+
+/* ─── step 0: cover ─── */
+.ex-cover-body {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  gap: var(--space-5);
+  padding-top: var(--space-7);
+}
+.ex-cover-h {
+  font-size: var(--t-display-2);
+  line-height: 1.05;
+  margin: 0;
+  max-width: 24ch;
+}
+.ex-cover-foot {
+  margin-top: var(--space-7);
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+}
+
+/* ─── step 1: split ─── */
+.ex-split {
+  flex: 1;
+  display: grid;
+  grid-template-columns: minmax(240px, 320px) 1fr;
+  gap: var(--space-9);
+  padding-top: var(--space-7);
+  align-items: start;
+}
+.ex-split-num {
+  font-size: var(--t-display-1);
+}
+.ex-split-body {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-4);
+}
+.ex-split-h {
+  font-size: var(--t-h1);
+  line-height: 1.1;
+  margin: 0;
+}
+.ex-split-p {
+  font-family: var(--font-body);
+  font-size: var(--t-body);
+  line-height: 1.6;
+  color: var(--text-2);
+  max-width: 56ch;
+  margin: 0;
+}
+
+/* ─── step 2: close pull-quote ─── */
+.ex-close { padding: 0; }
+.ex-close-inner {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  padding: var(--stage-pad-y) var(--stage-pad-x);
+  gap: var(--space-5);
+}
+.ex-quote {
+  font-size: var(--t-display-2);
+  line-height: 1.15;
+  max-width: 22ch;
+}
+.ex-close-foot {
+  margin-top: var(--space-7);
+}

package/template/.agents/skills/web-video-presentation/templates/src/chapters/01-example/Example.tsx

@@ -0,0 +1,104 @@
+import { MaskReveal } from "../../components/MaskReveal";
+import type { ChapterStepProps } from "../../registry/types";
+import "./Example.css";
+
+/**
+ * Reference chapter — replace with your own.
+ *
+ * Demonstrates the per-step takeover pattern AND the design-token system:
+ * each step uses SEMANTIC tokens (--text, --accent, --t-*, --space-*) so
+ * you can swap themes without editing the chapter at all.
+ *
+ * See SKILL.md "non-negotiable #3" for why each step is its own layout.
+ */
+export default function ExampleChapter({ step }: ChapterStepProps) {
+  /* Step 0 — magazine cover, headline + kicker + click cue */
+  if (step === 0) {
+    return (
+      <div className="ex-scene scene-pad">
+        <header className="masthead">
+          <span className="brand">Your Presentation</span>
+          <span className="issue">Issue · 01 — Replace this</span>
+        </header>
+        <hr className="rule" style={{ marginTop: "var(--space-5)" }} />
+
+        <div className="ex-cover-body">
+          <div className="kicker">Chapter 01 — Example</div>
+          <h1 className="ex-cover-h">
+            <MaskReveal show duration={900}>
+              <span className="serif-cn">这是&nbsp;</span>
+            </MaskReveal>
+            <MaskReveal show delay={300} duration={900}>
+              <span className="serif-it ex-em">first&nbsp;step</span>
+            </MaskReveal>
+            <MaskReveal show delay={650} duration={900}>
+              <span className="serif-cn">.</span>
+            </MaskReveal>
+          </h1>
+          <div className="ex-cover-foot label-mono">
+            <span className="dot-accent" /> &nbsp;Tap anywhere to advance
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  /* Step 1 — split layout: hero number + body */
+  if (step === 1) {
+    return (
+      <div className="ex-scene scene-pad">
+        <header className="masthead">
+          <span className="brand">Your Presentation</span>
+          <span className="issue">Issue · 01</span>
+        </header>
+        <hr className="rule" style={{ marginTop: "var(--space-5)" }} />
+
+        <div className="ex-split">
+          <div className="ex-split-num hero-num">02</div>
+          <div className="ex-split-body">
+            <div className="kicker">每一步</div>
+            <h2 className="ex-split-h">
+              <MaskReveal show duration={900}>
+                <span className="serif-cn">独占&nbsp;</span>
+              </MaskReveal>
+              <MaskReveal show delay={300} duration={900}>
+                <span className="serif-it ex-em">整个屏幕</span>
+              </MaskReveal>
+              <MaskReveal show delay={650} duration={900}>
+                <span className="serif-cn">.</span>
+              </MaskReveal>
+            </h2>
+            <p className="ex-split-p">
+              The current theme controls every visual detail — palette,
+              fonts, hero-number style, rule weight, decoration, motion.
+              The chapter code is theme-agnostic.
+            </p>
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  /* Step 2 — pull-quote close */
+  return (
+    <div className="ex-scene scene-pad ex-close">
+      <div className="ex-close-inner">
+        <div className="kicker">Now</div>
+        <div className="pull-quote ex-quote">
+          <MaskReveal show duration={1100}>
+            <span className="serif-cn">Replace this with </span>
+          </MaskReveal>
+          <MaskReveal show delay={400} duration={1100}>
+            <span className="serif-it ex-em">your own&nbsp;</span>
+          </MaskReveal>
+          <MaskReveal show delay={760} duration={1100}>
+            <span className="serif-cn">chapters.</span>
+          </MaskReveal>
+        </div>
+        <div className="ex-close-foot label-mono">
+          See SKILL.md / CHAPTER-CRAFT.md / THEMES.md
+        </div>
+      </div>
+    </div>
+  );
+}

package/template/.agents/skills/web-video-presentation/templates/src/chapters/01-example/narrations.ts

@@ -0,0 +1,28 @@
+import type { Narration } from "../../registry/types";
+
+/**
+ * Per-step narration for this chapter.
+ *
+ * Length === number of steps the chapter component renders.
+ * Index i === the spoken text for `step === i` in `Example.tsx`.
+ *
+ * Audio synthesis uses this file directly (see scripts/extract-narrations.ts).
+ * Auto-play mode plays `public/audio/<chapter-id>/<i+1>.mp3` at each step
+ * and advances when the audio ends (+ a tiny trail pad).
+ *
+ * Empty string ("") = no audio for this step (silent transition);
+ * Auto mode falls back to a short estimate so the presentation still
+ * progresses.
+ *
+ * Rule of thumb: visual animation duration MUST be ≤ narration duration.
+ * If your animation needs more time, write longer narration, split the
+ * step, or speed the animation up — there is no "minimum hold" knob.
+ */
+export const narrations: Narration[] = [
+  // step 0 — magazine cover
+  "这是示例章节的第一步。把这一行换成你这一步的口播文案。",
+  // step 1 — split layout
+  "第二步。每个数组元素对应章节里 step === N 的那一屏。长度必须严格相等。",
+  // step 2 — pull-quote close
+  "第三步。这个数组就是音频合成 + 自动播放的唯一真相源——再也不会和章节代码漂移。",
+];

package/template/.agents/skills/web-video-presentation/templates/src/components/AutoStartGate.css

@@ -0,0 +1,55 @@
+.auto-gate {
+  position: fixed;
+  inset: 0;
+  z-index: 100;
+  display: grid;
+  place-items: center;
+  background: rgba(0, 0, 0, 0.78);
+  backdrop-filter: blur(20px);
+  -webkit-backdrop-filter: blur(20px);
+  cursor: pointer;
+  animation: auto-gate-fade-in 320ms ease-out;
+}
+@keyframes auto-gate-fade-in {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+.auto-gate-card {
+  text-align: center;
+  color: #f4f4f5;
+  padding: 48px 64px;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  align-items: center;
+}
+.auto-gate-kicker {
+  font-family: var(--font-mono);
+  font-size: 11px;
+  letter-spacing: 0.22em;
+  text-transform: uppercase;
+  color: rgba(244, 244, 245, 0.55);
+}
+.auto-gate-title {
+  font-family: var(--font-display-en, system-ui);
+  font-size: 56px;
+  font-weight: 600;
+  letter-spacing: -0.02em;
+  line-height: 1.1;
+}
+.auto-gate-sub {
+  font-family: var(--font-body, var(--font-display-en));
+  font-size: 16px;
+  color: rgba(244, 244, 245, 0.65);
+  line-height: 1.6;
+  margin-top: 8px;
+}
+.auto-gate-sub kbd {
+  font-family: var(--font-mono);
+  font-size: 12px;
+  background: rgba(255, 255, 255, 0.12);
+  border-radius: 4px;
+  padding: 2px 6px;
+  border: 1px solid rgba(255, 255, 255, 0.18);
+}

package/template/.agents/skills/web-video-presentation/templates/src/components/AutoStartGate.tsx

@@ -0,0 +1,36 @@
+import "./AutoStartGate.css";
+
+interface Props {
+  visible: boolean;
+  onStart(): void;
+}
+
+/**
+ * Full-screen overlay shown ONCE when `?auto=1` is loaded. Browsers block
+ * audio playback until the page receives a user gesture, so we show this
+ * gate and let the user press Space (or click) to release auto playback.
+ *
+ * After the user starts, the gate is hidden for the rest of the session.
+ */
+export function AutoStartGate({ visible, onStart }: Props) {
+  if (!visible) return null;
+  return (
+    <div
+      className="auto-gate"
+      data-no-advance
+      onClick={onStart}
+      role="button"
+      tabIndex={0}
+    >
+      <div className="auto-gate-card">
+        <div className="auto-gate-kicker">AUTO PLAYBACK</div>
+        <div className="auto-gate-title">Press SPACE to start</div>
+        <div className="auto-gate-sub">
+          Audio plays per step and advances automatically.
+          <br />
+          Press <kbd>M</kbd> any time to switch modes.
+        </div>
+      </div>
+    </div>
+  );
+}

package/template/.agents/skills/web-video-presentation/templates/src/components/AutoToggle.css

@@ -0,0 +1,53 @@
+.at-hover {
+  position: fixed;
+  top: 0;
+  right: 0;
+  width: 160px;
+  height: 60px;
+  z-index: 11;
+  display: flex;
+  align-items: flex-start;
+  justify-content: flex-end;
+  padding: 12px;
+  pointer-events: auto;
+}
+.at-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  background: rgba(0, 0, 0, 0.85);
+  backdrop-filter: blur(20px);
+  -webkit-backdrop-filter: blur(20px);
+  color: #f4f4f5;
+  font-family: var(--font-mono);
+  font-size: 11px;
+  letter-spacing: 0.18em;
+  padding: 8px 14px;
+  border-radius: 0 0 0 8px;
+  cursor: pointer;
+  opacity: 0;
+  transform: translateY(-100%);
+  transition: opacity 280ms ease, transform 280ms ease;
+}
+.at-hover:hover .at-btn {
+  opacity: 1;
+  transform: translateY(0);
+}
+.at-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: #888;
+  display: inline-block;
+}
+.at-manual .at-dot {
+  background: #888;
+}
+.at-audio .at-dot {
+  background: #facc15;
+  box-shadow: 0 0 8px rgba(250, 204, 21, 0.6);
+}
+.at-auto .at-dot {
+  background: #4ade80;
+  box-shadow: 0 0 8px rgba(74, 222, 128, 0.7);
+}

package/template/.agents/skills/web-video-presentation/templates/src/components/AutoToggle.tsx

@@ -0,0 +1,36 @@
+import type { PlaybackMode } from "../hooks/useAudioPlayer";
+import "./AutoToggle.css";
+
+interface Props {
+  mode: PlaybackMode;
+  onCycle(): void;
+}
+
+const LABEL: Record<PlaybackMode, string> = {
+  manual: "MANUAL",
+  audio: "AUDIO",
+  auto: "AUTO",
+};
+
+/**
+ * Hidden-on-hover playback mode toggle, fixed top-right.
+ * Default opacity 0; hover the corner reveals it. Click cycles the mode.
+ * `data-no-advance` so clicking the button doesn't advance the stage.
+ */
+export function AutoToggle({ mode, onCycle }: Props) {
+  return (
+    <div className="at-hover" data-no-advance>
+      <button
+        className={`at-btn at-${mode}`}
+        onClick={(e) => {
+          e.stopPropagation();
+          onCycle();
+        }}
+        title="切换播放模式（M）"
+      >
+        <span className="at-dot" />
+        <span className="at-label">{LABEL[mode]}</span>
+      </button>
+    </div>
+  );
+}

package/template/.agents/skills/web-video-presentation/templates/src/components/MaskReveal.tsx

@@ -0,0 +1,35 @@
+import type { CSSProperties, ReactNode } from "react";
+
+interface Props {
+  show: boolean;
+  delay?: number;
+  duration?: number;
+  className?: string;
+  children: ReactNode;
+}
+
+/**
+ * clip-path text wipe. Pair with `.mask-reveal` and `.mask-reveal.in` from
+ * animations.css. Use for any text that should appear (not fade).
+ */
+export function MaskReveal({
+  show,
+  delay = 0,
+  duration,
+  className,
+  children,
+}: Props) {
+  const cls = ["mask-reveal", show ? "in" : "", className]
+    .filter(Boolean)
+    .join(" ");
+  const style: CSSProperties = {
+    display: "inline-block",
+    transitionDelay: show ? `${delay}ms` : "0ms",
+    ...(duration ? { transitionDuration: `${duration}ms` } : null),
+  };
+  return (
+    <span className={cls} style={style}>
+      {children}
+    </span>
+  );
+}

package/template/.agents/skills/web-video-presentation/templates/src/components/ProgressBar.css

@@ -0,0 +1,122 @@
+.pb-hover {
+  position: fixed;
+  bottom: 0;
+  left: 0;
+  right: 0;
+  height: 60px;
+  z-index: 10;
+  display: flex;
+  align-items: flex-end;
+  justify-content: center;
+  pointer-events: auto;
+}
+.pb {
+  background: rgba(0, 0, 0, 0.85);
+  backdrop-filter: blur(20px);
+  padding: 12px 20px;
+  border-radius: 12px 12px 0 0;
+  display: flex;
+  gap: 6px;
+  /* Adapt to content; if it would exceed the viewport, scroll horizontally
+     instead of squeezing chapter pills / step pips. */
+  max-width: calc(100vw - 32px);
+  overflow-x: auto;
+  overflow-y: hidden;
+  scrollbar-width: thin;
+  scrollbar-color: var(--text-faint) transparent;
+  opacity: 0;
+  transform: translateY(100%);
+  transition: opacity var(--dur-base) var(--ease-quart),
+    transform var(--dur-base) var(--ease-quart);
+}
+.pb::-webkit-scrollbar {
+  height: 4px;
+}
+.pb::-webkit-scrollbar-track {
+  background: transparent;
+}
+.pb::-webkit-scrollbar-thumb {
+  background: var(--text-faint);
+  border-radius: 2px;
+}
+.pb-hover:hover .pb {
+  opacity: 1;
+  transform: translateY(0);
+}
+
+.pb-chapter {
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  background: transparent;
+  border: 1px solid transparent;
+  color: var(--text-mute);
+  padding: 6px 12px;
+  border-radius: 4px;
+  font-family: var(--font-mono);
+  font-size: 11px;
+  cursor: pointer;
+  transition: color var(--dur-quick), border-color var(--dur-quick);
+}
+.pb-chapter:hover {
+  color: var(--text);
+}
+.pb-active {
+  color: var(--text);
+  border-color: var(--accent);
+}
+.pb-num {
+  color: var(--accent);
+  font-weight: 600;
+}
+
+.pb-pips {
+  flex-shrink: 0;
+  display: flex;
+  gap: 3px;
+  margin-left: 8px;
+}
+.pb-pip {
+  flex-shrink: 0;
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: var(--text-faint);
+  cursor: pointer;
+  transition: background var(--dur-quick);
+}
+.pb-pip-on {
+  background: var(--accent);
+}
+
+.pb-github {
+  position: absolute;
+  right: 16px;
+  bottom: 12px;
+  width: 36px;
+  height: 36px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: rgba(0, 0, 0, 0.85);
+  backdrop-filter: blur(20px);
+  border-radius: 8px;
+  color: var(--text);
+  text-decoration: none;
+  opacity: 0;
+  transform: translateY(100%);
+  transition: opacity var(--dur-base) var(--ease-quart),
+    transform var(--dur-base) var(--ease-quart),
+    color var(--dur-quick);
+}
+.pb-github:hover {
+  color: var(--accent);
+}
+.pb-hover:hover .pb-github {
+  opacity: 1;
+  transform: translateY(0);
+}
+.pb-github svg {
+  display: block;
+}