@bitmagic/cli 0.1.65-dev.1 → 0.1.65-dev.10

package/dist/scaffold/skill-files.js

@@ -11,7 +11,17 @@
  * `project-files.test.ts` enforces the frontmatter (name == directory) and that AGENTS.md names
  * every shipped skill. The same template-literal rule applies: the markdown is full of backticks,
  * so every one inside is escaped as \` and the test checks the rendered output.
+ *
+ * One renderer here breaks the template-literal rule on purpose: `renderTrailerCraftReference`
+ * reads `assets/skills/trailer-craft.md`, because that file is the SOURCE OF TRUTH for trailer
+ * craft in two places at once — the skill scaffolded into a creator's project, and the monorepo's
+ * own `make-trailer` skill, which symlinks to the same file. Craft is the half of trailer guidance
+ * that is not about commands, so both readers need all of it and neither owns it; a second copy
+ * would drift the moment either was edited, and the drift is silent (both files still look like
+ * guidance). A shipped asset is the only shape that lets a symlink do the sharing.
  */
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { describeSkillsDir } from './agent-targets.js';
 /**
  * `.kiro/steering/bitmagic.md` — Kiro's startup instructions, and the only per-agent extra file
@@ -105,11 +115,14 @@ in \`AGENTS.md\` — both are left alone.
  * `<skills dir>/making-a-trailer/SKILL.md` — the whole trailer flow, and the craft that makes a
  * cut watchable.
  *
- * Two kinds of knowledge live here on purpose. The FLOW (record → make → look → publish) is plain
- * command routing an agent could read off \`--help\`. The CRAFT — ordering, pacing, the five variety
- * axes, the selection rules the repo's own trailer reviews paid for — is not derivable from any
- * command, and without it the agent's "tuning" is random. The tuning table at the end is the part
- * the creator actually experiences: a prompt in, a shots.json edit out, one command to see it.
+ * Two kinds of knowledge live here on purpose, and they are split across two files. The FLOW
+ * (record → make → look → publish) is plain command routing an agent could read off \`--help\`,
+ * and it is what SKILL.md carries. The CRAFT — ordering, pacing, the five variety axes, the
+ * selection rules earlier trailer reviews paid for — is not derivable from any command, and
+ * without it the agent's "tuning" is random; it lives in \`references/trailer-craft.md\`
+ * (\`renderTrailerCraftReference\`) because it is longer than the flow and read once per trailer
+ * rather than once per command. The tuning table at the end is the part the creator actually
+ * experiences: a prompt in, a shots.json edit out, one command to see it.
  */
 export function renderTrailerSkill() {
     return `---
@@ -128,19 +141,43 @@ and running one command again.
 
 1. **Have \`bitmagic dev\` running** (it is the sink the recorder streams frames to, and the HUD
    replay for \`--ui\`). ffmpeg and Google Chrome must be installed; the commands say so if not.
-2. **Record.** \`bitmagic trailer record --seconds 60\` opens Chrome on the dev view, waits for the
-   creator to press Play, starts the recorder for them, stops after 60 s (or when they press F9),
-   and prints the recording directory. Ask the creator to PLAY WELL — the trailer is only as good
-   as the footage: overtakes, jumps, kills, close calls, a finish. \`--seconds\` is wall-clock; the
-   recording counts FRAMES at 60 fps, and the game runs as fast as the machine encodes them — on a
-   machine capturing at 30 fps, 60 s of play becomes 30 s of footage (the command reports both).
-   After stop the frames are extracted from the capture; the command waits for that. Aim for
-   footage of about 3x the trailer length: a 30 s trailer wants
-   90 s of footage, so \`--seconds 120\` or two sittings. Two sittings?
-   \`bitmagic trailer merge <dirA> <dirB> --out <dir>\`.
-   No human available: author \`trailer/flythrough.json\` (below) and
-   \`bitmagic trailer record --flythrough trailer/flythrough.json\` records a camera path with
-   nobody playing — scenery trailers, world reveals.
+2. **Record — played footage, a fly-through, or both.** Decide this BEFORE you ask anyone to play:
+
+   \`\`\`
+   bitmagic trailer record --seconds 60                              # they play
+   bitmagic trailer record --flythrough trailer/flythrough.json      # nobody plays
+   \`\`\`
+
+   **Played footage** is the bulk of any trailer — it is the only thing that shows what the game
+   does. \`record\` opens Chrome on the dev view, waits for the creator to press Play, starts the
+   recorder for them, stops after 60 s (or when they press F9), and prints the recording directory.
+   Ask them to PLAY WELL — the trailer is only as good as the footage: overtakes, jumps, kills,
+   close calls, a finish. \`--seconds\` is wall-clock; the recording counts FRAMES at 60 fps, and the
+   game runs as fast as the machine encodes them — on a machine capturing at 30 fps, 60 s of play
+   becomes 30 s of footage (the command reports both). After stop the frames are extracted from the
+   capture; the command waits for that. Aim for about 3x the trailer length: a 30 s trailer wants
+   90 s of footage, so \`--seconds 120\` or two sittings.
+
+   **A fly-through needs nobody.** \`--flythrough\` clicks through the menu and Play itself, then
+   glides the camera along an authored path WHILE THE GAME RUNS — traffic drives, animations play,
+   physics ticks — and stops at the last marker. It is the whole trailer flow with no human in it,
+   so reach for it when the creator is not around, when you are working on your own, or when they
+   would rather not be filmed playing badly.
+
+   **Offer it even when there IS gameplay.** A chase camera almost never gives you the two shots
+   the craft doc asks for by name — a composed cold open and one calm wide breath before the end —
+   and a fly-through costs the creator nothing. Record a short one as well and join the two:
+
+   \`\`\`
+   bitmagic trailer merge <gameplay-dir> <flythrough-dir> --out <dir>
+   \`\`\`
+
+   \`merge\` is how two sittings become one cuttable recording, and it does not care how the
+   footage was made — only that the runs share a resolution and post-processing state. So the cut
+   can pull an establishing shot from the fly-through and everything else from play.
+   Tell the creator the offer in one line ("I can also fly a camera through the level for the
+   opening shot — you don't have to do anything"), and write the path yourself from the level you
+   built: \`world.json\` has the coordinates.
 3. **Make.** \`bitmagic trailer make --music-prompt "<style that fits the game>" --title "<name>"\`
    analyzes the recording, generates a music bed (sparks — say so to the creator; \`--music <file>\`
    uses their own track, \`--no-music\` skips it), writes a first cut to \`trailer/shots.json\`,
@@ -163,7 +200,7 @@ cut before delivering.
 | File | What it is |
 |---|---|
 | \`trailer/shots.json\` | **The cut.** Committed. Your edits live here; \`make\` re-cuts from it every run. |
-| \`trailer/flythrough.json\` | Optional camera path for a no-human recording. |
+| \`trailer/flythrough.json\` | A camera path you author. Committed. Records with nobody playing — the whole trailer, or just the opening shot. |
 | \`.bitmagic/trailer/recordings/<name>/\` | A recording: \`<name>_%06d.png\` at 60 fps + \`timeline.json\` (events, sounds, HUD). |
 | \`.bitmagic/trailer/<name>/analysis.json\` | Scored highlight windows: \`startFrame\`, \`endFrame\`, \`score\`, event digests (\`"f3121 explosion i0.9"\`), \`sheet\`. |
 | \`.bitmagic/trailer/<name>/sheets/\` | Contact sheets, one per window — read these. |
@@ -200,46 +237,26 @@ seconds or \`"last-clip"\` for the end card. \`bitmagic trailer cut\` turns this
 
 Positions are world units (\`engine/agent-docs/coordinate-system.md\`); \`timestamp\` is seconds,
 ascending from 0; \`lookAt\` (or an Euler \`rotation\`) per marker. The camera glides through the
-markers and the recording stops at the last one.
-
-## Craft — read before touching the cut
-
-**Order: Genre → Hook → Anchors → Content.** The first 1–2 shots must say what kind of game this
-is. The hook — the thing only this game has — lands inside the first third. The middle holds the
-anchors people expect from the genre; breadth (levels, modes) comes last.
-
-**Skeleton first, footage last.** Cold open → introduction → escalation → climax → one breath →
-end card. Reserve the end card (2–3 s, one card) before anything else, then find the ONE clip
-that proves each beat — not "fifteen great clips", which drifts toward sameness.
-
-**Pacing.** Shots run 1.5–3 s for arcade action, with a few longer holds where one continuous
-action is the payoff. Vary lengths (2, 3, 4, 6 beats); do not cut on every beat — let a musical
-hit land on an in-clip impact sometimes. Build to a peak, then a calmer wider shot, then build
-again. 30–45 s total. More cutting is not better editing: if one take shows the whole stunt,
-keep the take.
-
-**Variety, five axes** — audit the labels in shots.json top to bottom, repetition shows in text
-before you ever re-watch: content (different actions, escalate rather than repeat), composition
-(camera distance and framing), energy (intense vs quiet), pacing (section tempo), shot length.
-**Rule of three**: never more than three similar things in a row, and max three of any shot
-type in the whole cut.
-
-**Text.** End card only, unless the footage cannot say it. ≤ 6 words, evocative verbs, sounds
-like this game and no other. Banned: quantities ("5 unique levels"), genre stacks, verb lists
-("Race! Drift! Win!"), stock phrases ("Get ready…", "…like never before"). Cards get their own
-beat — never over action.
-
-## Selection rules this project already paid for
-
-- **Never slow motion.** On gameplay footage it reads as a low framerate. \`speed\` is 1.0.
-- **Numbers are not interest.** A high \`impactSpeed\` is often a car dead against a wall — the
-  worst clip. A crash earns its slot only if things visibly break and motion continues.
-- **Low speed can BE the drama.** Wheelspin recoveries, plowing back onto the track, being
-  overtaken while struggling — often the best clips, and they score near zero.
-- **"Some shots of X" means a few.** One standing start is an opener; five is a broken trailer.
-- **Menu and selection screens need \`"ui": false\`** — the HUD replay paints the race HUD over them.
-- **Verify on pixels.** Sheets and stills, every candidate. Then render — iterating is minutes and
-  revisions are kept, so render rather than debate.
+markers and the recording stops at the last one (600 s is the ceiling).
+
+You write this file — take the coordinates from the level you built, in \`world.json\`. Aim the
+first marker at whatever makes the game recognisable, keep the camera moving slowly and in one
+direction per leg (a drifting push or a slow arc reads as deliberate; a whip-pan reads as a
+mistake), and give each leg several seconds. Six markers over 20 s is plenty for the two or three
+shots a cut will actually use — you are recording candidate footage, not the trailer.
+
+## Craft — read \`references/trailer-craft.md\` before touching the cut
+
+Everything about WHICH moments and in what order lives in
+\`references/trailer-craft.md\`, next to this file: the Genre → Hook → Anchors → Content ordering,
+laying the timeline out as a skeleton before hunting footage, pacing and shot length, the five
+variety axes, the rules for on-screen text, a section-by-section structure template, and the
+selection rules earlier trailers already paid for (never slow motion; a high \`impactSpeed\` is
+usually a car dead against a wall; low speed can BE the drama; menus need \`"ui": false\`).
+
+Read it in full the first time you cut a trailer for this game. The tool finds candidate windows
+and snaps cuts to the beat — it has no opinion about any of the above, so without that file your
+"tuning" is random.
 
 ## Tuning from prompts
 
@@ -254,6 +271,8 @@ The creator talks; you edit \`trailer/shots.json\`, run \`bitmagic trailer make\
 | "show the menu / the map / the start" | add ONE shot from the recording's opening with \`"ui": false\` |
 | "put the title at the end" / "change the tagline" | \`titles: [{ "at": "last-clip", "text": "…", "sub": "…", "style": "card" }]\` |
 | "add a title at the start" | a \`title\`-style cue at \`at: 0\` for ~2.5 s, and make the first shot calm enough to read over |
+| "show more of the world / the level", "a wider shot", "an establishing shot" | record a fly-through, \`merge\` it with the gameplay recording, and take the cold open (and the breath) from it |
+| "I can't play right now", "you do it", nobody available | \`record --flythrough\` — it clicks Play itself and needs no one |
 | "different music", "more epic / chill" | \`--music-prompt\` with the new direction (spends sparks), or \`--music <file>\`; shots keep their beat counts and re-snap |
 | "no HUD" / "show the HUD" | drop or add \`--ui\` (per shot: \`"ui": false\`) |
 | "the HUD stutters" / "smoother HUD" | raise \`--ui-keyframe-rate\` on \`make\` or \`render\` (default 30/s; 0 = every change) |
@@ -265,6 +284,25 @@ Then: **quota check** the labels (rule of three, one standing start), render, ex
 from the changed region, compare with the previous \`-rN\`, deliver the URL.
 `;
 }
+/**
+ * `<skills dir>/making-a-trailer/references/trailer-craft.md` — the only shipped skill file that is
+ * read from disk rather than written as a template literal.
+ *
+ * It is a shipped asset (`assets/skills/`, listed in package.json's `files`) because two skills
+ * need the same bytes: this one, and the monorepo's own `.claude/skills/make-trailer/`, whose copy
+ * is a SYMLINK to the asset. Trailer craft is editing knowledge — it says nothing about the CLI, so
+ * neither reader owns it and neither can be given an abridgement without going stale against the
+ * other. The same reasoning as the repo's `.agents/skills -> ../.claude/skills` link: a link is not
+ * a copy, so there is nothing to keep in step and no check to forget to run.
+ *
+ * Resolved from this module's own location the way `defaultTitleFont` resolves the bundled font:
+ * `../../assets/` is the same hop from `src/scaffold/` and from `dist/scaffold/`, so it works run
+ * from source and from an installed package alike.
+ */
+export function renderTrailerCraftReference() {
+    const source = fileURLToPath(new URL('../../assets/skills/trailer-craft.md', import.meta.url));
+    return fs.readFileSync(source, 'utf-8');
+}
 /**
  * `<skills dir>/publishing-a-game/SKILL.md` — the whole ship-it path, and every way it refuses.
  *

package/dist/scaffold/skill-files.js.map

@@ -1 +1 @@
-{"version":3,"file":"skill-files.js","sourceRoot":"","sources":["../../src/scaffold/skill-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAGvD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO;;;;;;;;;;;;;;;;;;CAkBR,CAAC;AACF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,EAAE,SAAS,EAAE,SAAS,EAAsB;IAC7E,2FAA2F;IAC3F,6EAA6E;IAC7E,MAAM,QAAQ,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,GAAG,GAAG,IAAI,CAAC,CAAC;IAC7F,6FAA6F;IAC7F,0EAA0E;IAC1E,MAAM,WAAW,GACf,QAAQ,CAAC,MAAM,KAAK,CAAC;QACnB,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC,8FAA8F;YAC9F,mEAAmE;YACnE,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;YAC5C,iFAAiF,CAAC;IAExF,OAAO;;sBAEa,SAAS,SAAS,iBAAiB,CAAC,SAAS,CAAC;;;EAGlE,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BZ,CAAC;AACF,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuJR,CAAC;AACF,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB;IACnC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+HR,CAAC;AACF,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,+BAA+B;IAC7C,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkER,CAAC;AACF,CAAC"}
+{"version":3,"file":"skill-files.js","sourceRoot":"","sources":["../../src/scaffold/skill-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAGvD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO;;;;;;;;;;;;;;;;;;CAkBR,CAAC;AACF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,EAAE,SAAS,EAAE,SAAS,EAAsB;IAC7E,2FAA2F;IAC3F,6EAA6E;IAC7E,MAAM,QAAQ,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,GAAG,GAAG,IAAI,CAAC,CAAC;IAC7F,6FAA6F;IAC7F,0EAA0E;IAC1E,MAAM,WAAW,GACf,QAAQ,CAAC,MAAM,KAAK,CAAC;QACnB,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC,8FAA8F;YAC9F,mEAAmE;YACnE,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;YAC5C,iFAAiF,CAAC;IAExF,OAAO;;sBAEa,SAAS,SAAS,iBAAiB,CAAC,SAAS,CAAC;;;EAGlE,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BZ,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6JR,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,2BAA2B;IACzC,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,sCAAsC,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/F,OAAO,EAAE,CAAC,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB;IACnC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+HR,CAAC;AACF,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,+BAA+B;IAC7C,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkER,CAAC;AACF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitmagic/cli",
-  "version": "0.1.65-dev.1",
+  "version": "0.1.65-dev.10",
   "description": "Build Bitmagic games from your own agent tool",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": "Bitmagic Oy",
@@ -25,9 +25,9 @@
     "playwright-core": "^1.59.1",
     "tar": "^7.4.3",
     "ws": "^8.21.3",
-    "@bitmagic/animation-forger": "0.1.20-dev.1",
-    "@bitmagic/asset-core": "0.2.20-dev.1",
-    "@bitmagic/world-forger": "0.1.25-dev.1"
+    "@bitmagic/animation-forger": "0.1.20-dev.10",
+    "@bitmagic/asset-core": "0.2.20-dev.10",
+    "@bitmagic/world-forger": "0.1.25-dev.10"
   },
   "devDependencies": {
     "@eslint/js": "^9.38.0",