videowright 0.1.0

package/skill/assets/hello_world/audio/audio_plan.md

@@ -0,0 +1,14 @@
+# Audio Plan
+
+## Plan
+
+No audio configured. The hello-world template ships silent — `videowright
+render` produces a video-only MP4 when `default_audio_track` is unset on the
+timeline. To add audio, run `videowright script --write` to generate a
+voiceover script, send it to your TTS provider (or use ElevenLabs via the
+skill), then place the result in `audio/originals/voiceovers/v1/` and build a
+track under `audio/tracks/v1/`.
+
+## Log
+
+(No entries yet.)

package/skill/assets/hello_world/segments/hello_intro.ts

@@ -0,0 +1,69 @@
+import { defineSegment } from "videowright";
+
+let host: HTMLElement | null = null;
+
+export default defineSegment({
+	id: "hello-intro",
+	// 2 advances: first resolves waitForNext at 2s, second transitions to next segment at 4s
+	advances: [2.0, 4.0],
+	voiceover: "Welcome to Videowright. Build animated videos with HTML, CSS, and JavaScript.",
+
+	mount(el) {
+		host = el;
+		el.innerHTML = `
+      <div style="
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+        height: 100%;
+        background: var(--color-bg);
+        color: var(--color-fg);
+        font-family: var(--font-display);
+      ">
+        <h1 style="
+          font-size: 4rem;
+          font-weight: 700;
+          margin: 0;
+          opacity: 0;
+        " data-ref="title">Hello Videowright</h1>
+        <p style="
+          font-family: var(--font-body);
+          font-size: 1.5rem;
+          color: var(--color-fg);
+          margin-top: 1rem;
+          opacity: 0;
+        " data-ref="subtitle">Built with HTML, CSS, and JavaScript</p>
+      </div>
+    `;
+	},
+
+	async play(ctx) {
+		const title = host?.querySelector('[data-ref="title"]') as HTMLElement;
+		const subtitle = host?.querySelector('[data-ref="subtitle"]') as HTMLElement;
+
+		// Animate title in
+		title.animate(
+			[
+				{ opacity: 0, transform: "translateY(20px)" },
+				{ opacity: 1, transform: "translateY(0)" },
+			],
+			{ duration: 600, fill: "forwards", easing: "ease-out" },
+		);
+
+		// Animate subtitle in — staggered via WAAPI delay (render-safe)
+		subtitle.animate(
+			[
+				{ opacity: 0, transform: "translateY(10px)" },
+				{ opacity: 1, transform: "translateY(0)" },
+			],
+			{ duration: 400, delay: 400, fill: "forwards", easing: "ease-out" },
+		);
+
+		await ctx.waitForNext(); // Beat 1: content fully revealed, wait for user to advance
+	},
+
+	unmount() {
+		host = null;
+	},
+});

package/skill/assets/hello_world/segments/hello_outro.ts

@@ -0,0 +1,71 @@
+import { defineSegment } from "videowright";
+
+let host: HTMLElement | null = null;
+
+export default defineSegment({
+	id: "hello-outro",
+	advances: [3.0],
+	voiceover: "Tell the agent what to change next. Swap the style, add content, and make it yours.",
+
+	mount(el) {
+		host = el;
+		el.innerHTML = `
+      <div style="
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+        height: 100%;
+        background: var(--color-bg);
+        color: var(--color-fg);
+        font-family: var(--font-body);
+      ">
+        <h1 style="
+          font-family: var(--font-display);
+          font-size: 3rem;
+          font-weight: 700;
+          margin: 0;
+          opacity: 0;
+        " data-ref="heading">Start Building</h1>
+        <p style="
+          font-size: 1.25rem;
+          color: var(--color-fg);
+          margin-top: 1.5rem;
+          max-width: 600px;
+          text-align: center;
+          line-height: 1.6;
+          opacity: 0;
+        " data-ref="cta">Tell the agent what to change next. Swap the style, add content, and make it yours.
+        </p>
+      </div>
+    `;
+	},
+
+	async play(ctx) {
+		const heading = host?.querySelector('[data-ref="heading"]') as HTMLElement;
+		const cta = host?.querySelector('[data-ref="cta"]') as HTMLElement;
+
+		// Animate heading in
+		heading.animate(
+			[
+				{ opacity: 0, transform: "scale(0.9)" },
+				{ opacity: 1, transform: "scale(1)" },
+			],
+			{ duration: 500, fill: "forwards", easing: "ease-out" },
+		);
+
+		// Animate call-to-action in — staggered via WAAPI delay (render-safe)
+		cta.animate([{ opacity: 0 }, { opacity: 1 }], {
+			duration: 400,
+			delay: 500,
+			fill: "forwards",
+		});
+
+		// No waitForNext -- last segment. play() resolves after the animation.
+		// The player shows "end of timeline" in the HUD.
+	},
+
+	unmount() {
+		host = null;
+	},
+});

package/skill/assets/hello_world/timeline.ts

@@ -0,0 +1,15 @@
+import "../../styles/editorial-mono/tokens.css";
+import type { Timeline } from "videowright";
+
+const timeline: Timeline = {
+	meta: {
+		title: "Hello Videowright",
+	},
+	segments: [
+		{ id: "hello-intro" },
+		{ id: "editorial-mono-sample-kinetic", transition: "fade" },
+		{ id: "hello-outro", transition: "fade" },
+	],
+};
+
+export default timeline;

package/skill/assets/hello_world/voiceover_script/script.md

@@ -0,0 +1,10 @@
+# Hello Videowright
+
+## hello-intro
+Welcome to Videowright. Build animated videos with HTML, CSS, and JavaScript.
+
+## editorial-mono-sample-kinetic
+Kinetic statements in Editorial Mono. Words enter one at a time, the last marked in red.
+
+## hello-outro
+Tell the agent what to change next. Swap the style, add content, and make it yours.

package/skill/assets/install/package.json

@@ -0,0 +1,10 @@
+{
+	"name": "my-videowright-project",
+	"version": "0.1.0",
+	"private": true,
+	"type": "module",
+	"scripts": {
+		"dev": "npx videowright dev",
+		"render": "npx videowright render"
+	}
+}

package/skill/assets/install/tsconfig.json

@@ -0,0 +1,23 @@
+{
+	"compilerOptions": {
+		"strict": true,
+		"target": "ES2022",
+		"module": "ESNext",
+		"moduleResolution": "Bundler",
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"forceConsistentCasingInFileNames": true,
+		"isolatedModules": true,
+		"verbatimModuleSyntax": true,
+		"resolveJsonModule": true,
+		"noEmit": true
+	},
+	"include": [
+		"segments/**/*",
+		"components/**/*",
+		"transitions/**/*",
+		"styles/**/*",
+		"videos/**/*",
+		"videowright.config.ts"
+	]
+}

package/skill/assets/styles/editorial-mono/STYLE.md

@@ -0,0 +1,124 @@
+---
+title: Editorial Mono
+slug: editorial-mono
+picker_description: 'Black ink on cream paper. One red accent. Reads like a magazine.'
+font_sources:
+  - https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&display=swap
+  - https://fonts.googleapis.com/css2?family=Geist:wght@300;400;500;600&display=swap
+  - https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500&display=swap
+mood: [serious, considered, literary, high-contrast, calm]
+good_for:
+  - AI/research lab launches
+  - Fintech and B2B product introductions
+  - Thought-leadership essays turned to video
+  - Annual reports and investor updates
+  - Long-form narrative explainers
+bad_for:
+  - Consumer apps that need warmth or whimsy
+  - Hype reels, sizzle videos, social-media shorts
+  - Anything that needs to feel fast, loud, or trendy
+  - Heavily data-driven dashboards (use Swiss Console)
+tags: [editorial, serif, minimal, print, high-contrast, light-mode]
+references: [Bloomberg Businessweek, Stripe Press, The Browser Company, The Atlantic]
+---
+
+# Editorial Mono — STYLE.md
+
+Agent-facing guide. Read this before composing scenes.
+
+---
+
+## Identity
+
+Editorial Mono is the visual register of a thoughtful long-form magazine — *Bloomberg Businessweek*, *Stripe Press*, *The Atlantic*. Black ink on warm cream paper. High-contrast serif display set against a clean grotesk body. A single red accent, used like an editor's mark. The page breathes.
+
+**Mood:** serious, considered, literary, calm, high-contrast.
+
+## When to use
+
+- AI/research launches, fintech intros, B2B product announcements
+- Thought-leadership essays adapted to video
+- Annual reports, investor updates, founder letters
+- Long-form narrative explainers
+
+## When to avoid
+
+- Consumer apps that need warmth or whimsy → use Risograph
+- Dev tools, dashboards, data-dense products → use Swiss Console
+- Anything dark-mode native → use Neon Terminal
+- Sizzle reels, social-media shorts, hype videos
+
+---
+
+## Layout principles
+
+- **Anchor to the left.** Most scenes left-align headlines on a 128px safe margin. Centered layouts are reserved for title cards and section headers.
+- **Generous negative space.** A scene with 30% of the canvas filled is the *norm*, not minimalism. If you find yourself filling a scene, cut content.
+- **One focal element per scene.** A headline, or a stat, or a quote — never two competing equals.
+- **Hairline rules as structure.** A 1px rule across the top or bottom of the safe area frames the page like a magazine.
+- **Small labels carry their weight.** A `VOL. 01 / CHAPTER 03` label in mono uppercase at 14px sets the editorial register before the headline does.
+
+## Color application
+
+- **Cream `--color-bg` everywhere.** White (`#fff`) is forbidden — it kills the paper feel.
+- **Ink `--color-fg` for all primary type.** Never pure black.
+- **Red `--color-accent` appears once per scene, maximum.** Use it for: a single word emphasis, an underline draw, a small symbol, an arrow tip. Never for whole headlines, never for backgrounds.
+- **Muted `--color-muted` for labels, captions, and secondary type only.**
+- **Surface `--color-surface` is for the rare card or callout** — almost imperceptible against the page.
+
+## Type rules
+
+- **Display = Instrument Serif.** Use the italic for emphasis — its italic is iconic. Display sizes range 96–220px.
+- **Body = Geist.** Medium (500) for headlines that need a grotesk; Regular (400) for body. Body sizes range 24–40px.
+- **Mono = JetBrains Mono.** Uppercase, tracked +0.08em, for editorial labels only (`VOL. 01`, `CHAPTER ONE`, timestamps, page numbers). Never for body copy.
+- **Line breaks for rhythm, not for width.** Break a headline at a comma or a verb, not at the edge of the column.
+- **Emphasis hierarchy:** italic (serif) > color (red accent) > weight. Never underline for emphasis (reserve underline for the kinetic statement's draw-on motion).
+- **No ALL CAPS in body type.** Reserve uppercase for the mono labels only.
+
+## Motion principles
+
+- **Entries are subtle and downward-settling.** Text fades in while drifting up 16px. Duration `--duration-normal` (480ms). Easing `--ease-out` (cubic-bezier(0.16, 1, 0.3, 1)).
+- **Stagger increments at `--stagger` (80ms).** A four-item bullet list reveals over ~800ms total.
+- **Exits cut.** Almost never animate out — a hard cut between scenes is faster and more print-like.
+- **Scene transitions are dip-to-cream.** Fade through `--color-bg` (no white flash) for 200ms between scenes.
+- **The red accent draws.** Underlines, marks, and arrows draw in left-to-right or top-down over `--duration-normal`.
+- **Forbidden:** bounce, spring, overshoot, elastic. Anything that feels "designed" rather than "set."
+- **Camera:** none. The page does not move.
+
+## Pacing
+
+Editorial Mono is **slow**. Scenes hold 3.5–5s by default. A scene with one headline and no other elements can hold 6s and feel right. If a script is fast-cut, this is the wrong template.
+
+## Per-scene recipes
+
+Each recipe gives sizing, max element count, and motion beat. See `reference/scenes.html` for rendered examples.
+
+| Scene | Recipe |
+|---|---|
+| **Title card** | Top-left mono label (`VOL. XX / YYYY`, 14px). Centered or top-left display headline at 180–220px serif. One subtitle line at 32px Geist Regular below. Optional rule above. Headline enters 480ms after label; subtitle 80ms after headline. |
+| **Section header** | Top mono label (`CHAPTER ONE`). Centered display at 140px, often italic. One rule above, one below the headline. Holds 4s. |
+| **Kinetic statement** | One sentence, 80–110px serif italic, left-aligned, breaks mid-line for rhythm. One word per beat enters fading-up at `--stagger` intervals. Last word may get a red underline draw on exit. |
+| **Bullet reveal** | Left rail. Mono numerals (`01`, `02`, …) in muted color. Each item: numeral + em dash + 40px Geist Medium label. Stagger 120ms (slightly longer than default — list items breathe). Max 5 items. |
+| **Stat card** | One number at 320px serif, left-aligned in column 1. Right column holds 40px Geist label (1–2 lines). Number counts up over `--duration-slow` (900ms). Red underline draws under the number on hold. |
+| **Feature card** | Single feature. Small icon (or numeral) top-left. Display name at 80px serif. 24px Geist body description, max 2 lines. Lots of negative space below. |
+| **Card grid** | 3 items in a row, gutters at `--space-lg` (64px). Each card: small label (mono), name (40px serif), one-line description (20px Geist). Cards enter in staggered sequence. |
+| **UI / product showcase** | Centered product mock at ~60% of canvas. Hairline rule frame. 1–2 callouts with arrow leaders in red, label set in mono. Arrows draw in after the mock settles. |
+| **Content card** | Generic catch-all. Top-left section label (mono). Headline at 80px serif. Body paragraph at 28px Geist Regular, max-width ~900px, line-height 1.4. |
+| **CTA / outro** | Top mono label optional. Central headline at 100px serif italic. Below: a call-to-action line (URL or imperative) with red accent on the destination. Logo placeholder bottom-left or centered. |
+
+### Connective elements
+
+- **Lower third:** mono label (uppercase, tracked) over the bottom safe area, with a hairline rule above. Used when narration runs over a held visual. Enters and exits with a fade.
+- **Scene transition:** dip-to-cream (200ms) between most scenes. Hard cut allowed for emphasis.
+- **Ambient layer:** none. The page does not move.
+
+## Pitfalls
+
+- **Don't use pure white.** Cream only. White kills the identity instantly.
+- **Don't use red for more than one element per scene.** It's an accent, not a color in the palette.
+- **Don't fill the canvas.** If you're tempted to add a fourth element, cut one of the first three.
+- **Don't center body type.** Center headlines, never paragraphs.
+- **Don't use bounce or overshoot in motion.** This style does not jiggle.
+- **Don't use Title Case for body labels.** Mono labels are UPPERCASE; everything else sentence case.
+- **Don't add gradients, shadows, glows, or textures.** Flat ink on flat paper.
+- **Don't use emoji.** Ever.

package/skill/assets/styles/editorial-mono/brand.md

@@ -0,0 +1,85 @@
+# Editorial Mono — Brand
+
+Human-readable rationale for the token values in `tokens.css`. Read together.
+
+---
+
+## Color
+
+**`--color-bg` = `#F2EFE8` (warm cream).** Print-feeling, slightly yellow-warm.
+Replaces pure white because white reads as "screen" — cream reads as "page."
+Used edge-to-edge on every scene, no exceptions.
+
+**`--color-fg` = `#14110E` (near-black ink).** Avoids pure black for the same
+reason cream replaces white — pure black is screen-flat, this is ink on paper.
+Primary type, hairline rules, logo marks.
+
+**`--color-accent` = `#C8392C` (editorial red).** The kind of red an editor
+marks the page with — saturated, slightly warm, never neon. Used as an
+emphasis tool, not a fill. Underlines, single-word color, arrow tips, the
+period at the end of a headline. **Once per scene, maximum.**
+
+**`--color-muted` = `#7B756B` (warm gray).** For mono labels, captions,
+secondary type, dim numerals. Warm-toned so it sits in the same family as
+the cream background.
+
+**`--color-border` = `#D9D3C7` (subtle warm).** For hairline rules and
+unobtrusive separators. The rule is meant to be felt, not read.
+
+**`--color-surface` = `#EBE7DD` (slightly darker paper).** For the rare
+card or callout box. Almost imperceptible against the page — that's the
+point. Editorial Mono does not use elevated surfaces.
+
+## Typography
+
+**Display: Instrument Serif.** A high-contrast modern serif with a striking
+italic. Built for editorial display use. Free, web-available. Pairs with a
+clean grotesk body without competing.
+
+**Body: Geist.** Vercel's open-source grotesk. Neutral but with personality.
+Reads small as well as large. Not Inter — Inter is overused.
+
+**Mono: JetBrains Mono.** For editorial labels only. Tracked +0.08em and set
+in UPPERCASE, it gives a tertiary structural layer (`VOL. 01 / CHAPTER 03`).
+
+## Spacing
+
+Spacing is opinionated and on a doubling scale (`16 / 32 / 64 / 128`) — the
+same proportional thinking as a print grid. Safe-area margins are set to
+`--space-xl` (128px) on the long axis and `--space-lg × 1.5` (96px) on the
+short axis, which gives every scene the same negative-space ratio as a
+hardcover page.
+
+## Geometry
+
+`--radius-sm` and `--radius-md` are deliberately small (2 and 4 px). The page
+does not have rounded corners. The radii exist for tiny details — chip
+labels, button hint hovers — not for cards. Cards have hairline borders
+instead.
+
+`--rule-weight` is `1px` flat. Two-pixel rules feel heavy and the editorial
+register depends on hairlines.
+
+## Motion
+
+**Durations:**
+- `--duration-fast` `220ms` — small things (cursor blinks, accent marks)
+- `--duration-normal` `480ms` — most entries (text, cards)
+- `--duration-slow` `900ms` — emphasis moments (stat count-up, underline draw)
+
+**Easing:**
+- `--ease-out` `cubic-bezier(0.16, 1, 0.3, 1)` — easeOutQuart. Settles down.
+- `--ease-in` `cubic-bezier(0.7, 0, 0.84, 0)` — for the rare exit.
+
+**Stagger:** `80ms` base. Lists use `120ms` for breathing room.
+
+**Scene hold:** `4s` default. Headlines may hold up to `6s`. Faster than this
+breaks the editorial register.
+
+## What this brand is not
+
+- Not a "modern minimal" template. The negative space is on purpose, but the
+  serif and the red are warm and opinionated.
+- Not a luxury or fashion register — no metallic, no jewel-tone, no foil.
+- Not "marketing site for a startup." It's "the magazine the marketing site
+  links to."