summer-engine 4.3.0 → 4.6.0

package/dist/core/capabilities/content-make/types.d.ts

@@ -0,0 +1,173 @@
+/**
+ * The records content.make keeps in a piece's work folder. Each stage
+ * writes one; a run that finds a stage's record (and its inputs unchanged)
+ * skips that stage, so a stopped run picks up where it stopped.
+ */
+/** One beat of a reference, as Summer's reference library describes it. */
+export interface RefBeat {
+    t: [number, number];
+    shot: string;
+    vo: string;
+    caption: string;
+}
+/** A reference from content.list_references (the fields the engine reads). */
+export interface Reference {
+    referenceId: string;
+    title: string;
+    url?: string;
+    platform?: string;
+    formatType?: string | null;
+    format?: string;
+    locked?: boolean;
+    whyItPerforms?: string;
+    howGamesCanUseIt?: string;
+    hook?: string;
+    captionStyle?: string;
+    voPattern?: string;
+    idea?: string | null;
+    ideas?: Array<{
+        genre: string;
+        idea: string;
+    }>;
+    genres?: string[];
+    stats?: {
+        views?: number;
+        likes?: number;
+        postedAt?: string;
+    };
+    breakoutRatio?: number;
+    expiresAt?: string;
+    beats?: RefBeat[];
+}
+export interface CaptionStyle {
+    /** held: one line stays for its beats; words: the voice's words a few at a time; beats: each beat's own line. */
+    mode: "held" | "words" | "beats";
+    /** Most words on screen at once in words mode. */
+    chunk: number;
+    case: "lower" | "upper" | "sentence";
+    /** Centre of the text block, as a share of the height. */
+    y: number;
+    color: string;
+    /** The longest word of a chunk in this colour (words mode), or none. */
+    highlight: string | null;
+    font: "sans" | "rounded" | "serif";
+    size: number;
+    outline: boolean;
+    /** Wrap the text in quote marks. */
+    quoted: boolean;
+}
+export interface Study {
+    referenceId: string;
+    file: string;
+    duration: number;
+    width: number;
+    height: number;
+    /** Hard cuts, seconds. */
+    cuts: number[];
+    /** Shot index -> black (a black beat to copy). */
+    black: boolean[];
+    hasVoice: boolean;
+    /** Seconds to the first hard cut. */
+    firstCut: number;
+    caption: CaptionStyle;
+    music: boolean;
+}
+export interface FootageClip {
+    path: string;
+    kind: "video" | "image";
+    duration: number;
+    width: number;
+    height: number;
+    hasAudio: boolean;
+    /** Mean motion (YDIF) per half second. */
+    motion: number[];
+    /** Mean brightness (0-255) per half second. */
+    luma: number[];
+    /** Search words: file and folder names, sidecar notes. */
+    tags: string[];
+    /** What happens in it, from a sidecar (shots.json or <clip>.json), when there is one. */
+    about?: string;
+}
+export interface FootageIndex {
+    clips: FootageClip[];
+    music: string[];
+}
+/** One shot of the cut: a window of a clip, a still, or a colour (a black beat). */
+export interface ShotSpec {
+    src?: string;
+    t?: number;
+    speed?: number;
+    cx?: number;
+    cy?: number;
+    z0?: number;
+    z1?: number;
+    color?: string;
+    mute?: boolean;
+    /** Why this shot (the reference shot it copies). */
+    beat?: string;
+}
+export interface CaptionItem {
+    text: string;
+    from: number;
+    to: number;
+}
+export interface Plan {
+    version: 1;
+    referenceId: string;
+    contentGameId: string;
+    title: string;
+    format: string;
+    /** Our words, one per reference beat ("" for none). Lines still marked TODO block the render. */
+    lines: string[];
+    /** The reference's own words per beat, for whoever writes ours (never rendered). */
+    refLines: string[];
+    /** Cut times, seconds, from 0 to the end. */
+    cuts: number[];
+    shots: ShotSpec[];
+    caption: CaptionStyle;
+    /** Held or beat captions; words mode builds its own from the voice. */
+    captions: CaptionItem[];
+    voice: {
+        file: string | null;
+        needed: boolean;
+    };
+    /** The game's own song (never the reference's audio), from musicStart seconds in, and how loud the game's sound sits under it. */
+    audio: {
+        music: string | null;
+        musicStart?: number;
+        bedDb: number;
+    };
+    /** Post caption per platform. */
+    post: {
+        caption: string;
+        hashtags: string[];
+        title?: string;
+    };
+    /** Shown under the player on Today (content.save_piece why). */
+    why: {
+        referenceId: string;
+        fitReason: string;
+        refStats: {
+            views?: number;
+            likes?: number;
+            postedAt?: string;
+        };
+        commit?: {
+            sha: string;
+            title: string;
+        };
+    };
+    /** Pictures over the cut: a PNG (1080x1920, transparent) from one time to another. */
+    overlays: Array<{
+        file: string;
+        from: number;
+        to: number;
+    }>;
+}
+export interface Check {
+    /** The names Studio labels (content.save_piece checks). */
+    name: "hook_time" | "lowest_motion" | "safe_zones" | "loudness" | "length" | "gameplay_seconds";
+    value: string;
+    pass: boolean;
+    note?: string;
+}

package/dist/core/capabilities/content-make/types.js

@@ -0,0 +1,6 @@
+/**
+ * The records content.make keeps in a piece's work folder. Each stage
+ * writes one; a run that finds a stage's record (and its inputs unchanged)
+ * skips that stage, so a stopped run picks up where it stopped.
+ */
+export {};

package/dist/core/capabilities/content-make/voice.d.ts

@@ -0,0 +1,7 @@
+import type { Word } from "./plan.js";
+/**
+ * Word times of a voice-over, from a Whisper on this computer: mlx_whisper
+ * (Apple silicon) or the openai-whisper command. The words are cut to and
+ * captioned from these times.
+ */
+export declare function transcribeWords(audio: string, workDir: string): Promise<Word[]>;

package/dist/core/capabilities/content-make/voice.js

@@ -0,0 +1,27 @@
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+import { BuildToolError } from "../summer-bundle.js";
+import { run, which } from "./media.js";
+/**
+ * Word times of a voice-over, from a Whisper on this computer: mlx_whisper
+ * (Apple silicon) or the openai-whisper command. The words are cut to and
+ * captioned from these times.
+ */
+export async function transcribeWords(audio, workDir) {
+    const out = join(workDir, "whisper");
+    mkdirSync(out, { recursive: true });
+    const json = join(out, `${basename(audio, extname(audio))}.json`);
+    if (!existsSync(json)) {
+        if (which("mlx_whisper")) {
+            await run("mlx_whisper", [audio, "--model", "mlx-community/whisper-small.en-mlx", "--word-timestamps", "True", "--output-format", "json", "--output-dir", out]);
+        }
+        else if (which("whisper")) {
+            await run("whisper", [audio, "--model", "small.en", "--word_timestamps", "True", "--output_format", "json", "--output_dir", out]);
+        }
+        else {
+            throw new BuildToolError("content_tool_missing", "A voice-over needs Whisper on this computer for its word times.", "Install one (Apple silicon: pipx install mlx-whisper; else pipx install openai-whisper), then run it again.", undefined, { missing: "Whisper on this computer (pipx install mlx-whisper)" });
+        }
+    }
+    const parsed = JSON.parse(readFileSync(json, "utf8"));
+    return (parsed.segments ?? []).flatMap((segment) => (segment.words ?? []).map((word) => ({ w: word.word.trim(), s: Math.round(word.start * 100) / 100, e: Math.round(word.end * 100) / 100 }))).filter((word) => word.w);
+}

package/dist/core/capabilities/events.d.ts

@@ -94,12 +94,12 @@ export declare const recentEventsArgsSchema: z.ZodObject<{
     limit: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     kinds?: string[] | undefined;
-    since?: number | undefined;
     limit?: number | undefined;
+    since?: number | undefined;
 }, {
     kinds?: string[] | undefined;
-    since?: number | undefined;
     limit?: number | undefined;
+    since?: number | undefined;
 }>;
 export type RecentEventsArgs = z.infer<typeof recentEventsArgsSchema>;
 export interface WaitForEventResult {

package/dist/core/capabilities/export-game.d.ts

@@ -9,7 +9,8 @@ export { runEngine, SUMMER_GAMES_PRESET, type EngineRun };
  *
  *   <engine> --headless --summer-no-api --path <project> --export-release "<preset>" <out>
  *
- * format "bundle" (default): the summer.bundle.v1 .zip for build-publications
+ * format "bundle" (default): the summer.bundle.v2 .zip (summer.bundle.v1 from
+ * engines before 0.7.4) for build-publications
  * (summer_publish_build). Summer runs its client.pck on its own templates in
  * the Summer Games apps, so no template and no signing. Without targets the
  * engine's in-memory "summer.games" preset is used as is (every platform
@@ -62,8 +63,10 @@ export interface ExportGameResult {
     engine: string;
     durationMs: number;
     /** Bundle format: the bundle manifest. */
+    /** paths: every entry of the .zip, summer-bundle.json included (the fixed layout a release checklist compares). */
     bundle?: Omit<SummerBundle, "hostedBuild" | "files"> & {
         fileCount: number;
+        paths: string[];
     };
     /** Download format: the store versions platform id (web, macos-universal, windows-x64). */
     storePlatform?: string;

package/dist/core/capabilities/export-game.js

@@ -10,7 +10,7 @@ import { engineErrorLines, runEngine } from "./engine-run.js";
 import { assertExportEngine, ENGINE_UPDATE_HOW, installedEngineVersion, targetsNeedingNewerEngine } from "./export-engine-version.js";
 import { BUNDLE_TARGETS, DOWNLOAD_TARGETS, SUMMER_GAMES_PRESET, bundlePresetSpec, ensurePreset, normalizeTargets, variantString, } from "./export-presets.js";
 import { engineTemplateInfo, findInstalledTemplate, templateFileFor } from "./export-templates.js";
-import { BuildToolError, declarationMismatch, hashFile, readSummerBundle, samePlatforms } from "./summer-bundle.js";
+import { BUNDLE_MANIFEST, BuildToolError, declarationMismatch, hashFile, readSummerBundle, samePlatforms } from "./summer-bundle.js";
 export { runEngine, SUMMER_GAMES_PRESET };
 /**
  * summer_export_game: run the installed Summer Engine headless and return the
@@ -18,7 +18,8 @@ export { runEngine, SUMMER_GAMES_PRESET };
  *
  *   <engine> --headless --summer-no-api --path <project> --export-release "<preset>" <out>
  *
- * format "bundle" (default): the summer.bundle.v1 .zip for build-publications
+ * format "bundle" (default): the summer.bundle.v2 .zip (summer.bundle.v1 from
+ * engines before 0.7.4) for build-publications
  * (summer_publish_build). Summer runs its client.pck on its own templates in
  * the Summer Games apps, so no template and no signing. Without targets the
  * engine's in-memory "summer.games" preset is used as is (every platform
@@ -378,7 +379,7 @@ export async function exportGame(input, overrides = {}) {
         debug,
         engine: binary,
         durationMs: deps.now().getTime() - started.getTime(),
-        bundle: { ...summary, fileCount: files.length },
+        bundle: { ...summary, fileCount: files.length, paths: [BUNDLE_MANIFEST, ...files.map((file) => file.path)].sort() },
         ...(projectChanges.length ? { projectChanges } : {}),
         ...(warnings.length ? { warnings } : {}),
         next: "Upload it to the game's store listing with summer_publish_build (gameId, clientVersion).",

package/dist/core/capabilities/export-presets.d.ts

@@ -2,7 +2,8 @@
  * Store targets for summer_export_game, and the export presets that make them.
  *
  * The Summer Games store has two intakes:
- * - build-publications takes ONE summer.bundle.v1 .zip per Build. Summer runs
+ * - build-publications takes ONE summer.bundle .zip (v2, or v1 from older
+ *   engines) per Build. Summer runs
  *   its client.pck on its own client templates (the Summer Games iOS and
  *   Android apps, the Summer desktop app on macOS and Windows), so the creator
  *   needs no export template and signs nothing. A target only picks the

package/dist/core/capabilities/export-presets.js

@@ -6,7 +6,8 @@ import { BuildToolError } from "./summer-bundle.js";
  * Store targets for summer_export_game, and the export presets that make them.
  *
  * The Summer Games store has two intakes:
- * - build-publications takes ONE summer.bundle.v1 .zip per Build. Summer runs
+ * - build-publications takes ONE summer.bundle .zip (v2, or v1 from older
+ *   engines) per Build. Summer runs
  *   its client.pck on its own client templates (the Summer Games iOS and
  *   Android apps, the Summer desktop app on macOS and Windows), so the creator
  *   needs no export template and signs nothing. A target only picks the

package/dist/core/capabilities/go-live.d.ts

@@ -0,0 +1,14 @@
+import { type PublishBuildDependencies } from "./publish-build.js";
+export interface GoLiveInput {
+    gameId?: string;
+    /** The bundle Build to release (build-publications id). Default: the newest export that passed its checks. */
+    publicationId?: string;
+    confirm?: boolean;
+    waitSeconds?: number;
+    face: "cli" | "mcp";
+}
+export type GoLiveResult = Record<string, unknown> & {
+    ok: true;
+    status: string;
+};
+export declare function goLive(input: GoLiveInput, overrides?: Partial<PublishBuildDependencies>): Promise<GoLiveResult>;