@vibeframe/cli 0.113.26 → 0.113.27

package/dist/commands/_shared/build-plan.d.ts

@@ -122,4 +122,11 @@ export interface CreateBuildPlanOptions {
  * (e.g. 7 beats quoted as ~$21 when the real cost is ~$0.35–1.40).
  */
 export declare function backdropCostUsd(quality: "standard" | "hd"): number;
+/**
+ * Per-beat narration cost by resolved TTS provider. Kokoro runs locally and
+ * costs $0 — a flat per-narration charge here is what made zero-key builds
+ * report phantom spend. Shared by the dry-run estimate and the post-build
+ * actuals so the two can never disagree.
+ */
+export declare function narrationCostUsd(provider: string | undefined): number;
 export declare function createBuildPlan(opts: CreateBuildPlanOptions): Promise<BuildPlanResult>;

package/dist/commands/_shared/compose-beat-prompt.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @module _shared/compose-beat-prompt
+ *
+ * Per-beat authoring contract handed to the HOST agent. `getComposePrompts()`
+ * (and therefore `vibe scene compose-prompts` / `scene_compose_prompts`) uses
+ * this to describe exactly what one `compositions/scene-<id>.html` fragment
+ * must contain: the bare `<template>` shape, the paused GSAP timeline anchored
+ * to the full beat duration, full-window `.clip` rules, and which generated
+ * assets to reference.
+ *
+ * These rules were written against the Hyperframes sub-composition contract
+ * and every one of them encodes a render bug we hit: black holds from a short
+ * timeline, stacked text from non-zero `data-start` phase clips, shimmer from
+ * transforms on text ancestors.
+ */
+import type { Beat } from "./storyboard-parse.js";
+import type { SceneTranscriptWord } from "./scene-html-emit.js";
+/** The slice of beat context the prompt builder needs. */
+export interface ComposeBeatPromptContext {
+    beat: Beat;
+    storyboardGlobal: string;
+    retryFeedback?: string;
+    finalDurationSec?: number;
+    transcript?: SceneTranscriptWord[];
+}
+/**
+ * Word-level timing entries above this count are downgraded to coarse,
+ * phrase-level anchors in the prompt. A token-budget guard: a 60s narration
+ * can exceed 150 words, and inlining every `[start, "word"]` pair bloats the
+ * prompt (and the cache key) for little composer benefit past a point.
+ */
+export declare const TRANSCRIPT_PROMPT_MAX_WORDS = 120;
+/**
+ * Render narration word timings as a compact, deterministic prompt section.
+ * Token-budget guard (the `oversized` case is the reason this is a function,
+ * not an inline template):
+ *   - no transcript → `""` (section omitted entirely; prompt unchanged).
+ *   - ≤ {@link TRANSCRIPT_PROMPT_MAX_WORDS} → full word-level `[start, "word"]`
+ *     table the composer can map 1:1 to GSAP reveals.
+ *   - more → group into ~`MAX/2` phrase anchors (start time of each phrase),
+ *     tagged "approximate" so the composer paces reveals across the beat
+ *     rather than over-trusting per-word truth.
+ * Pure and stable for a given input → the compose cache stays consistent.
+ */
+export declare function formatTranscriptSection(transcript: SceneTranscriptWord[] | undefined, maxWords?: number): string;
+/** Build the user prompt — instructions + storyboard global + beat body. */
+export declare function buildUserPrompt(ctx: ComposeBeatPromptContext): string;

package/dist/commands/_shared/compose-prompts.d.ts

@@ -13,7 +13,7 @@
  *     "projectDir": "<abs>",
  *     "designReference":     "DESIGN.md",
  *     "storyboardReference": "STORYBOARD.md",
- *     "skillReference":      "SKILL.md",        // present after `scene install-skill`
+ *     "skillReference":      ".agents/skills/hyperframes/SKILL.md",
  *     "compositionsDir":     "compositions",
  *     "beats": [
  *       { "id": "hook", "outputPath": "compositions/scene-hook.html",
@@ -22,14 +22,14 @@
  *     "instructions": [...]
  *   }
  *
- * Pairs with H1 (`vibe scene install-skill`) — the host agent reads
- * `SKILL.md` for framework rules, `DESIGN.md` for visual identity, then
+ * Pairs with `vibe scene install-skill` — the host agent reads the
+ * Hyperframes rules, `DESIGN.md` for visual identity, then
  * writes each `compositions/scene-<id>.html`. After authoring, runs
- * `vibe scene lint --fix` to verify and `vibe render` to produce MP4.
+ * `vibe build <project> --stage sync` to assemble the root composition,
+ * `vibe scene lint <project> --fix` to verify, and `vibe render` for MP4.
  *
- * The internal-LLM path (`vibe scene build`, PR #176) still works — it's
- * the batch / non-agent fallback. H3 will add mode dispatch so a single
- * entry point picks between agentic and batch depending on context.
+ * This is the only model-authored compose path: the host agent writes each
+ * file. `--composer template` is the deterministic alternative.
  */
 export interface ComposePromptsBeat {
     /** Stable beat id from `parseStoryboard().deriveBeatId()`. */
@@ -54,7 +54,7 @@ export interface ComposePromptsBeat {
     /**
      * Pre-built user prompt — the same shape `composeBeatHtml` would send to
      * Claude / OpenAI / Gemini. The host agent consumes this directly so the
-     * agentic and batch paths produce equivalent HTML.
+     * the host agent and the template composer produce equivalent structure.
      */
     userPrompt: string;
     /**
@@ -95,8 +95,6 @@ export interface ComposePromptsResult {
     beats: ComposePromptsBeat[];
     /** Step-by-step instructions for the host agent. */
     instructions: string[];
-    /** Hyperframes bundle version — informational; ties cache keys back to the internal-LLM path. */
-    bundleVersion: string;
     /** Non-fatal hints surfaced to the agent (e.g. missing SKILL.md). */
     warnings: string[];
     /** Set when {@link success} is false. */

package/dist/commands/_shared/install-skill.d.ts

@@ -1,117 +1,94 @@
 /**
  * @module _shared/install-skill
  *
- * Phase H1 — install the vendored Hyperframes skill bundle into a user's
- * scene project so that the host agent (Claude Code, Cursor, Codex, Aider,
- * etc.) can read the framework rules + house style directly. This is the
- * agentic-CLI-native pattern: the host agent is the sole LLM that reasons
- * about scene composition, and it does so with the skill files in its
- * context — VibeFrame's CLI is the deterministic toolbelt.
+ * Put the Hyperframes composition rules where the host agent will read them,
+ * by running upstream's own installer instead of shipping a copy.
  *
- * Layout written:
+ * VibeFrame used to vendor a snapshot of Hyperframes' skill markdown and write
+ * it into each project under hand-maintained per-host layouts (project-root
+ * `SKILL.md` + `references/`, `.claude/skills/hyperframes/`,
+ * `.cursor/rules/hyperframes.mdc`). That snapshot went stale - upstream has
+ * since restructured the skill into a router plus a `references/` tree and
+ * ships 31 skills, none of which a frozen copy can follow - and the two host
+ * layouts covered a fraction of what upstream's installer reaches.
  *
- *   <project>/
- *     SKILL.md                              # universal — all agents see this
- *     references/
- *       house-style.md
- *       motion-principles.md
- *       typography.md
- *       transitions.md
- *     .claude/skills/hyperframes/           # if hosts includes "claude-code"
- *       SKILL.md (copy)
- *       references/{house-style,...}.md
- *     .cursor/rules/hyperframes.mdc         # if hosts includes "cursor"
+ *   npx skills add heygen-com/hyperframes -s hyperframes -y
  *
- * Codex + Aider are AGENTS.md-driven hosts; they discover the project-root
- * SKILL.md because AGENTS.md points at it in prose (the init-templates
- * AGENTS_MD "Composition rules" section, not an `@`-import).
+ * installs to `.agents/skills/hyperframes/`, serves ~19 agents universally
+ * (Amp, Antigravity, Cline, Codex, and more), symlinks the ones that want
+ * their own directory (Claude Code, Eve), and records the result in
+ * `skills-lock.json`. The generated `AGENTS.md` has pointed users at this
+ * command for a while; now the code agrees with the docs.
  *
- * The content is byte-identical to what `loadHyperframesSkillBundle()`
- * uses — same vendored files, same `BUNDLE_VERSION`. Build/render never read
- * these project files (they use the vendored bundle); they exist only so host
- * agents can read the rules and so users can edit them per project.
- *
- * Lean scaffolds: the automatic `vibe init` path passes `lean: true`, so when
- * the Hyperframes skill is already installed globally
- * (`hasGlobalHyperframesSkill()`) it skips the redundant copies — the
- * `.claude/skills/hyperframes/` copy always, and the root `SKILL.md` +
- * `references/` unless a root-reading host (codex/aider/gemini/opencode) needs
- * them. Explicit `vibe scene install-skill` omits `lean`, fully materializing
- * editable copies regardless (the "eject").
+ * Nothing in build or render reads these files. They exist so the host agent
+ * can read the rules while it authors scene HTML.
  */
-import type { AgentHostId } from "../../utils/agent-host-detect.js";
+/** Upstream repository the `skills` CLI installs from. */
+export declare const HYPERFRAMES_SKILL_PACKAGE = "heygen-com/hyperframes";
+/** The command a user can run by hand to get the same result. */
+export declare const HYPERFRAMES_SKILL_INSTALL_COMMAND = "npx skills add heygen-com/hyperframes";
+/** Where upstream's installer puts the skill inside a project. */
+export declare const PROJECT_SKILL_PATH: string;
 /**
  * True when the Hyperframes skill is installed at the user's global Claude
- * skills dir (`~/.claude/skills/hyperframes/`). When present, materializing the
- * skill into a project is redundant — the host agent already loads it globally —
- * so `vibe init` keeps the scaffold lean and skips the copies. Explicit
- * `vibe scene install-skill` ignores this (it's the opt-in "eject" path).
+ * skills dir (`~/.claude/skills/hyperframes/`). A host agent already loads it
+ * from there, so installing into the project is redundant.
  */
 export declare function hasGlobalHyperframesSkill(): boolean;
-/** Hosts the install-skill command knows file layouts for. */
-export type InstallSkillHost = "claude-code" | "cursor" | "all";
+/** True when upstream's installer has already run in this project. */
+export declare function hasProjectHyperframesSkill(projectDir: string): boolean;
+/**
+ * Project-relative path to the composition rules a host agent should read, or
+ * `null` when neither the project nor the global install has them.
+ *
+ * The bare root `SKILL.md` is still honoured: projects scaffolded before the
+ * switch to upstream's installer have one, and it should keep working.
+ */
+export declare function resolveSkillReference(projectDir: string): string | null;
+/**
+ * True when the host agent can read the Hyperframes rules from anywhere -
+ * this project or the user's global skills dir. Callers that only need to
+ * decide whether to nag should use this rather than
+ * {@link resolveSkillReference}, which is about the in-project path and is
+ * null for a global-only install.
+ */
+export declare function hyperframesSkillAvailable(projectDir: string): boolean;
+export type InstallSkillStatus = "installed" | "already-installed" | "would-install" | "failed";
 export interface InstallSkillOptions {
-    /** Project directory (must exist or be creatable). */
+    /** Project to install into. The installer runs with this as its cwd. */
     projectDir: string;
-    /**
-     * Hosts to install host-specific copies for. The universal `SKILL.md` +
-     * `references/` directory at the project root are always written.
-     * Pass `["all"]` to install every host-specific layout.
-     */
-    hosts: InstallSkillHost[];
-    /** Overwrite existing files. Default false (skip-on-exist). */
+    /** Install at user level (`~/.claude/skills/...`) rather than per project. */
+    global?: boolean;
+    /** Reinstall even when the skill is already present. */
     force?: boolean;
-    /** Don't write — just describe what would happen. */
+    /** Report the command without running it. */
     dryRun?: boolean;
     /**
-     * Opt into redundancy gating: skip copies the globally-installed Hyperframes
-     * skill already provides. The automatic `vibe init` path sets this so the
-     * scaffold stays lean; the explicit `vibe scene install-skill` path leaves it
-     * false to fully materialize editable copies (the "eject"). Default false.
-     */
-    lean?: boolean;
-    /**
-     * Caller signals a root-reading host (codex / aider / gemini / opencode) is
-     * present, so the root `SKILL.md` + `references/` must be written even when
-     * the global Claude skill exists. Default false. Only consulted when `lean`.
-     */
-    rootReaderHostPresent?: boolean;
-    /**
-     * Override the global-skill probe (testing seam). Defaults to
-     * {@link hasGlobalHyperframesSkill}. Only consulted when `lean`.
+     * Override the global-skill probe. Testing seam - a developer machine that
+     * already has the skill would otherwise short-circuit every install.
      */
     hasGlobalSkill?: boolean;
 }
-export type InstallSkillFileStatus = "wrote" | "skipped-exists" | "would-write" | "would-skip-exists";
-export interface InstallSkillFileAction {
-    path: string;
-    status: InstallSkillFileStatus;
-    bytes: number;
-}
 export interface InstallSkillResult {
     success: boolean;
-    bundleVersion: string;
-    files: InstallSkillFileAction[];
+    status: InstallSkillStatus;
+    /** The exact command run (or that would run). */
+    command: string;
+    /** Project-relative path to the installed rules, when they are present. */
+    skillPath: string | null;
+    /** Installer output, trimmed. Present on a real run. */
+    output?: string;
+    error?: string;
+    retryWith?: string[];
 }
+/** Build the argv for upstream's installer. Pure - unit-testable. */
+export declare function buildInstallSkillArgs(opts?: {
+    global?: boolean;
+}): string[];
 /**
- * Map an `AgentHostId[]` to whether a root-reading host is present. Codex,
- * Aider, Gemini, and OpenCode read the project-root `SKILL.md` via AGENTS.md
- * prose — they have no global-skill mechanism, so the root files must be
- * written for them even when the global Claude skill exists.
- */
-export declare function deriveRootReaderPresent(detected: AgentHostId[]): boolean;
-/**
- * Install Hyperframes skill files at the project + host-specific paths.
+ * Run upstream's installer for the Hyperframes skill.
  *
- * Idempotent by default — existing files are skipped (logged as
- * `skipped-exists`). Pass `force: true` to overwrite. `dryRun: true`
- * reports the same actions but with `would-*` status and writes nothing.
+ * Skips when the skill is already available (globally or in the project)
+ * unless `force` is set, so calling it twice costs nothing.
  */
 export declare function installHyperframesSkill(opts: InstallSkillOptions): Promise<InstallSkillResult>;
-/**
- * Map an `AgentHostId[]` (from `detectedAgentHosts()`) to the
- * install-skill command's host vocabulary. Codex / Aider don't get
- * host-specific layouts — they read the universal `SKILL.md` via
- * AGENTS.md, so they're filtered out here.
- */
-export declare function deriveInstallHosts(detected: AgentHostId[]): InstallSkillHost[];

package/dist/commands/_shared/scene-build-mode.d.ts

@@ -1,4 +1,19 @@
 export type SceneBuildMode = "agent" | "batch" | "auto";
+/**
+ * Resolve which compose path a build takes.
+ *
+ * `agent` is the only LLM-authored path VibeFrame ships: the host's agent
+ * writes each `compositions/scene-<id>.html` and the CLI lints, syncs, and
+ * renders around it. `batch` now means one thing - the deterministic
+ * `--composer template` path, which authors HTML without any model.
+ *
+ * The mode used to also select a CLI-internal LLM composer that called
+ * Claude/OpenAI/Gemini directly. That path is gone: the host agent is the
+ * outer loop, and duplicating its job inside the CLI meant carrying a stale
+ * copy of upstream's authoring skill and demanding an extra API key.
+ * `VIBE_BUILD_MODE=batch` therefore no longer forces a model-authored build;
+ * without `--composer template` it resolves to `agent`.
+ */
 export declare function resolveSceneBuildMode(opts: {
     mode?: SceneBuildMode;
 }): "agent" | "batch";

package/dist/commands/_shared/scene-build.d.ts

@@ -19,7 +19,6 @@
  *     already have one with sub-composition references.
  */
 import { type ImageOptions } from "@vibeframe/ai-providers";
-import { type ComposeEffort, type ComposeProgressEvent, type ComposeScenesActionResult } from "./compose-scenes-skills.js";
 import type { ComposerProvider } from "./composer-resolve.js";
 import { type ComposePromptsBeat } from "./compose-prompts.js";
 import { type SceneRenderResult } from "./scene-render.js";
@@ -155,7 +154,7 @@ export type SceneBuildProgressEvent = {
     type: "music-skipped";
     beatId: string;
     reason: string;
-} | ComposeProgressEvent | {
+} | {
     type: "render-start";
 } | {
     type: "render-done";
@@ -240,8 +239,6 @@ export interface SceneBuildOptions {
      * Build mode dispatch. See {@link SceneBuildMode}. Default: `auto`.
      */
     mode?: SceneBuildMode;
-    /** Compose effort tier — passed through to `compose-scenes-with-skills`. */
-    effort?: ComposeEffort;
     /**
      * Composer LLM provider. Defaults to whatever `resolveComposer()` picks
      * based on env keys (claude > gemini > openai). Pass an explicit value
@@ -343,7 +340,6 @@ export interface SceneBuildResult {
     beats: BeatBuildOutcome[];
     /** MP4 path when `skipRender` is false and render succeeded. */
     outputPath?: string;
-    composeData?: ComposeScenesActionResult["data"];
     renderResult?: SceneRenderResult;
     /**
      * Populated only in agent mode when {@link phase} === `"needs-author"`.
@@ -358,7 +354,6 @@ export interface SceneBuildResult {
         compositionsDir: string;
         instructions: string[];
         beats: ComposePromptsBeat[];
-        bundleVersion: string;
         warnings: string[];
     };
     selectedStage?: BuildStage;
@@ -463,7 +458,6 @@ declare function toBuildReport(projectDir: string, result: SceneBuildResult): {
             path: string;
             exists: boolean;
             status: BuildReportCompositionStatus;
-            cacheKey?: string;
         };
         narrationPath: string | undefined;
         narrationDurationSec: number | undefined;
@@ -505,4 +499,4 @@ declare function toBuildReport(projectDir: string, result: SceneBuildResult): {
     retryWith: string[];
     totalLatencyMs: number;
 };
-type BuildReportCompositionStatus = "generated" | "cached" | "exists" | "needs-author" | "skipped" | "failed";
+type BuildReportCompositionStatus = "exists" | "needs-author" | "skipped" | "failed";

package/dist/commands/_shared/scene-lint.d.ts

@@ -137,3 +137,26 @@ export declare function runProjectLint(opts: RunProjectLintOptions): Promise<Pro
 /** True if `root` exists and is a regular file. Used by callers that want to
  *  pre-validate before invoking `runProjectLint`. */
 export declare function rootExists(projectDir: string, rootRel?: string): Promise<boolean>;
+export interface BeatLintResult {
+    errorCount: number;
+    warningCount: number;
+    findings: LintFinding[];
+}
+/**
+ * Lint one beat's HTML in memory, with no temp project shell and no
+ * subprocess. Sub-composition false positives are filtered the same way
+ * `vibe scene lint` filters them, so an agent submitting a beat sees the
+ * findings it would see after the file landed in the project.
+ */
+export declare function lintBeatHtml(html: string, beatId: string): Promise<BeatLintResult>;
+/** Thrown when a submission carries no recoverable HTML. */
+export declare class BeatHtmlError extends Error {
+    readonly code: "no-html-in-response";
+    constructor(code: "no-html-in-response", message: string);
+}
+/**
+ * Pull the HTML fragment out of an agent's reply. Prefers a fenced ```html
+ * block and accepts a bare fragment, since hosts often skip the fence when
+ * the whole reply is the document.
+ */
+export declare function extractHtml(responseText: string): string;

package/dist/commands/_shared/scene-render.d.ts

@@ -12,7 +12,7 @@
  * tool and the C5 `--format scenes` pipeline can call it the same way. It
  * returns a structured result instead of throwing or exiting.
  */
-import { type RenderConfig } from "@hyperframes/producer";
+import { type RenderConfigInput } from "@hyperframes/producer";
 import { type SceneAspect } from "./scene-project.js";
 export type RenderFps = 24 | 30 | 60;
 export type RenderQuality = "draft" | "standard" | "high";
@@ -105,8 +105,14 @@ export declare function defaultOutputPath(opts: {
     now?: Date;
 }): string;
 /**
- * Build the producer's `RenderConfig` from caller options. Pure — useful for
+ * Build the producer's render config from caller options. Pure - useful for
  * unit tests that want to assert defaults without touching Chrome.
+ *
+ * Returns `RenderConfigInput` (not `RenderConfig`) so `fps` stays an integer:
+ * the producer models fps as a rational `{num, den}` internally but accepts a
+ * plain number on the way in. The intersection pins `fps`/`format` to our
+ * narrower unions so callers keep arithmetic on fps and never see the
+ * producer-only formats (`gif`, `png-sequence`) VibeFrame does not expose.
  */
 export declare function buildRenderConfig(opts: {
     fps?: RenderFps;
@@ -114,7 +120,10 @@ export declare function buildRenderConfig(opts: {
     format?: RenderFormat;
     workers?: number;
     entryFile?: string;
-}): RenderConfig;
+}): RenderConfigInput & {
+    fps: RenderFps;
+    format: RenderFormat;
+};
 export declare function buildMediaOpenCommand(action: RenderOpenAction, filePath: string, platform?: NodeJS.Platform): MediaOpenCommand;
 /**
  * Render a scene project. Mirrors the contract of the existing Hyperframes

package/dist/commands/_shared/walkthroughs/walkthroughs.d.ts

@@ -12,7 +12,7 @@
  * a terminal) gets the same step-by-step authoring guide that the
  * slash commands deliver in Claude Code. The content is vendored as
  * TS template-literal strings so the CLI binary ships with zero
- * filesystem dependencies — same approach as `hf-skill-bundle`.
+ * filesystem dependencies.
  *
  * Source of truth lives here. The Claude Code slash command files
  * under `.claude/skills/vibe-{scene,pipeline}/SKILL.md` mirror this