@kheleshikhi/studio-agent 0.6.1 → 0.9.0

package/dist/shot-provenance.d.ts

@@ -0,0 +1,66 @@
+export type Api = <T>(method: string, route: string, body?: unknown) => Promise<T>;
+export declare const DEPENDENCY_SCHEMA = "kheleshikhi.scene-dependencies.v1";
+export type DependencyRecord = {
+    schema: string;
+    compilerVersion?: string;
+    componentHeader?: string;
+    components?: Array<{
+        id: string;
+        definitionHash: string | null;
+    }>;
+    behaviors?: Array<{
+        id: string;
+        definitionHash: string | null;
+    }>;
+    audio?: Array<{
+        id: string;
+        sha256: string | null;
+    }>;
+    digest: string;
+};
+export type SceneIdentity = {
+    /** Experience Scene id (manifest id) or "main" for a Studio Scene shot. */
+    scene: string;
+    kind: "studio_source" | "approved_revision" | "gallery_package";
+    asset?: string | null;
+    revision?: string | null;
+    source_hash?: string | null;
+    manifest_path?: string | null;
+    package?: string | null;
+    package_sha256?: string | null;
+    dependencies_digest: string | null;
+    dependencies?: DependencyRecord | null;
+    note?: string;
+};
+export type ExperienceProvenance = {
+    schema: "kheleshikhi.experience-scene-provenance.v1";
+    preview_source_hash: string | null;
+    scenes: Record<string, SceneIdentity>;
+    /** Audio stable id -> sha256 of its exact bytes. */
+    audio: Record<string, string>;
+    digest: string;
+};
+export declare function canonicalJson(value: unknown): string;
+export declare function digestOf(value: unknown): string;
+/** A dependency record from a compile response, or null when it has none. */
+export declare function dependencyRecord(compileResult: unknown): DependencyRecord | null;
+/** Compile a Studio source and return its dependency record. */
+export declare function compileDependencies(api: Api, asset: string, source: unknown): Promise<{
+    compiled: boolean;
+    source_hash: string | null;
+    dependencies: DependencyRecord | null;
+}>;
+/**
+ * One approved Scene revision's identity: the asset's approved source (when
+ * it is the asset's current source, i.e. no newer draft hides it) compiled
+ * for its dependency record. A draft over the revision leaves the record
+ * unknown, which is said, never guessed.
+ */
+export declare function approvedSceneIdentity(api: Api, scene: string, asset: string, revision: string, manifestPath: string | null): Promise<SceneIdentity>;
+/**
+ * Every Scene and sound an Experience document resolves to right now, from
+ * the server's draft preview (the same resolution the player uses).
+ */
+export declare function experienceProvenance(api: Api, document: unknown, options?: {
+    dependencies?: boolean;
+}): Promise<ExperienceProvenance>;

package/dist/shot-provenance.js

@@ -0,0 +1,114 @@
+/**
+ * What a render was made from, exactly enough to key a cache on.
+ *
+ * A Scene render is made from one Scene Source (its source hash) compiled
+ * against exact Component, Behavior and Audio definitions: the server's
+ * compile response carries that record (`artifacts.dependencies`, schema
+ * `kheleshikhi.scene-dependencies.v1`, with its own digest). An Experience
+ * render is made from the Experience Source and, for each of its Scenes, the
+ * approved revision the draft preview resolved (asset, revision, stored
+ * manifest) plus that revision's dependency record when it can be read, and
+ * from the exact bytes of every sound it names.
+ *
+ * Nothing here decides validity on its own; the episode runner hashes these
+ * facts into a shot key. Library or project membership is never an input.
+ */
+import { createHash } from "node:crypto";
+export const DEPENDENCY_SCHEMA = "kheleshikhi.scene-dependencies.v1";
+export function canonicalJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    const record = value;
+    return `{${Object.keys(record).filter((key) => record[key] !== undefined).sort()
+        .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
+}
+export function digestOf(value) {
+    return createHash("sha256").update(canonicalJson(value)).digest("hex");
+}
+/** A dependency record from a compile response, or null when it has none. */
+export function dependencyRecord(compileResult) {
+    const artifacts = compileResult?.artifacts;
+    const record = artifacts?.dependencies;
+    if (!record || record.schema !== DEPENDENCY_SCHEMA || typeof record.digest !== "string")
+        return null;
+    return record;
+}
+/** Compile a Studio source and return its dependency record. */
+export async function compileDependencies(api, asset, source) {
+    const result = await api("POST", `/v1/agent/studio/${encodeURIComponent(asset)}/compile`, { source });
+    return {
+        compiled: result.compiled === true,
+        source_hash: typeof result.source_hash === "string" ? result.source_hash : null,
+        dependencies: dependencyRecord(result),
+    };
+}
+/**
+ * One approved Scene revision's identity: the asset's approved source (when
+ * it is the asset's current source, i.e. no newer draft hides it) compiled
+ * for its dependency record. A draft over the revision leaves the record
+ * unknown, which is said, never guessed.
+ */
+export async function approvedSceneIdentity(api, scene, asset, revision, manifestPath) {
+    const identity = { scene, kind: "approved_revision", asset, revision, manifest_path: manifestPath, dependencies_digest: null };
+    try {
+        const loaded = await api("GET", `/v1/agent/studio/${encodeURIComponent(asset)}`);
+        if (loaded.source_origin === "approved" && loaded.base_revision_public_id === revision && loaded.source) {
+            const compiled = await compileDependencies(api, asset, loaded.source);
+            identity.source_hash = typeof loaded.source_hash === "string" ? loaded.source_hash : compiled.source_hash;
+            identity.dependencies = compiled.dependencies;
+            identity.dependencies_digest = compiled.dependencies?.digest ?? null;
+        }
+        else {
+            identity.note = "A newer draft or revision hides this revision's source; keyed by revision and stored manifest only.";
+        }
+    }
+    catch (error) {
+        identity.note = `Source not readable: ${error instanceof Error ? error.message : String(error)}`.slice(0, 300);
+    }
+    return identity;
+}
+/**
+ * Every Scene and sound an Experience document resolves to right now, from
+ * the server's draft preview (the same resolution the player uses).
+ */
+export async function experienceProvenance(api, document, options = {}) {
+    const preview = await api("POST", "/v1/agent/authoring/experience/preview", { document });
+    const scenes = {};
+    for (const [scene, raw] of Object.entries((preview.scenes ?? {}))) {
+        if (raw.kind === "media") {
+            const origin = (raw.provenance ?? {});
+            const asset = typeof origin.asset === "string" ? origin.asset : null;
+            const revision = typeof origin.revision === "string" ? origin.revision : null;
+            const manifestPath = typeof raw.manifestPath === "string" ? raw.manifestPath : null;
+            if (asset && revision && options.dependencies !== false) {
+                scenes[scene] = await approvedSceneIdentity(api, scene, asset, revision, manifestPath);
+            }
+            else {
+                scenes[scene] = { scene, kind: "approved_revision", asset, revision, manifest_path: manifestPath,
+                    source_hash: typeof origin.sourceHash === "string" ? origin.sourceHash : null, dependencies_digest: null };
+            }
+        }
+        else {
+            scenes[scene] = { scene, kind: "gallery_package", package: raw.package ?? null, package_sha256: raw.packageSha256 ?? null,
+                dependencies_digest: null, note: "An approved Gallery package: its sha256 is its identity." };
+        }
+    }
+    const audio = {};
+    for (const entry of Object.values((preview.audio ?? {}))) {
+        if (typeof entry.audio === "string" && typeof entry.sha256 === "string")
+            audio[entry.audio] = entry.sha256;
+    }
+    const body = { preview_source_hash: typeof preview.sourceHash === "string" ? preview.sourceHash : null, scenes, audio };
+    return {
+        schema: "kheleshikhi.experience-scene-provenance.v1",
+        ...body,
+        digest: digestOf({
+            preview_source_hash: body.preview_source_hash,
+            scenes: Object.fromEntries(Object.entries(scenes).map(([key, value]) => [key, { ...value, dependencies: undefined, note: undefined }])),
+            audio,
+        }),
+    };
+}
+//# sourceMappingURL=shot-provenance.js.map

package/dist/shot-provenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shot-provenance.js","sourceRoot":"","sources":["../src/shot-provenance.ts"],"names":[],"mappings":"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"}

package/dist/state.js

@@ -5,25 +5,29 @@ import path from "node:path";
 import { CliError } from "./types.js";
 export const DEFAULT_API_ORIGIN = "https://api.nerdbro.org";
 export function stateDirectory(env = process.env, platform = process.platform) {
+    // Paths follow the target platform's convention, wherever this runs.
+    const join = platform === "win32" ? path.win32.join : path.posix.join;
     if (env.NERDBRO_AGENT_STATE_DIR)
         return path.resolve(env.NERDBRO_AGENT_STATE_DIR);
     if (platform === "win32") {
-        return path.join(env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local"), "NerdBro", "Studio Agent");
+        return join(env.LOCALAPPDATA || join(os.homedir(), "AppData", "Local"), "NerdBro", "Studio Agent");
     }
     if (platform === "darwin") {
-        return path.join(os.homedir(), "Library", "Application Support", "NerdBro", "Studio Agent");
+        return join(os.homedir(), "Library", "Application Support", "NerdBro", "Studio Agent");
     }
-    return path.join(env.XDG_STATE_HOME || path.join(os.homedir(), ".local", "state"), "nerdbro-studio-agent");
+    return join(env.XDG_STATE_HOME || join(os.homedir(), ".local", "state"), "nerdbro-studio-agent");
 }
 export function cacheDirectory(env = process.env, platform = process.platform) {
+    // Paths follow the target platform's convention, wherever this runs.
+    const join = platform === "win32" ? path.win32.join : path.posix.join;
     if (env.NERDBRO_AGENT_CACHE_DIR)
         return path.resolve(env.NERDBRO_AGENT_CACHE_DIR);
     if (platform === "win32") {
-        return path.join(env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local"), "NerdBro", "Studio Agent", "Cache");
+        return join(env.LOCALAPPDATA || join(os.homedir(), "AppData", "Local"), "NerdBro", "Studio Agent", "Cache");
     }
     if (platform === "darwin")
-        return path.join(os.homedir(), "Library", "Caches", "NerdBro Studio Agent");
-    return path.join(env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache"), "nerdbro-studio-agent");
+        return join(os.homedir(), "Library", "Caches", "NerdBro Studio Agent");
+    return join(env.XDG_CACHE_HOME || join(os.homedir(), ".cache"), "nerdbro-studio-agent");
 }
 function daemonPath() {
     return path.join(stateDirectory(), "daemon.json");

package/dist/state.js.map

@@ -1 +1 @@
-{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"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"}

package/dist/video.d.ts

@@ -0,0 +1,197 @@
+export declare const RECIPE_KIND = "kheleshikhi.video-render-recipe.v1";
+export declare const RENDER_KIND = "kheleshikhi.video-render.v1";
+export type RenderSubject = "scene" | "experience";
+/** Learner actions a recipe may schedule, per subject. */
+export declare const RENDER_OPS: Record<RenderSubject, readonly string[]>;
+export type RenderAction = {
+    /** Video second at which the action happens. */
+    at: number;
+    op: string;
+    target?: string;
+    value?: string | number | boolean;
+};
+/** The native output sizes: the presentation host renders at exactly these. */
+export declare const RENDER_PROFILES: {
+    readonly "landscape-720p": {
+        readonly width: 1280;
+        readonly height: 720;
+    };
+    readonly "landscape-1080p": {
+        readonly width: 1920;
+        readonly height: 1080;
+    };
+    readonly "portrait-720p": {
+        readonly width: 720;
+        readonly height: 1280;
+    };
+    readonly "portrait-1080p": {
+        readonly width: 1080;
+        readonly height: 1920;
+    };
+};
+export type RenderProfile = keyof typeof RENDER_PROFILES;
+export type RenderRecipe = {
+    kind: typeof RECIPE_KIND;
+    /** Output frames per second. */
+    fps: number;
+    /** SceneClock seconds rendered: [start, end); frame k at start + k / fps. */
+    start: number;
+    end: number;
+    /** One of [RENDER_PROFILES]; its size is the output size. */
+    profile: RenderProfile;
+    /** Output size: the presentation viewport, every PNG and the MP4. */
+    width: number;
+    height: number;
+    /** `scene` mixes the runtime's own sounds from canonical assets; `silent` writes a silent AAC track. */
+    audio: "silent" | "scene";
+    /** Learner actions at exact logical times. */
+    actions: RenderAction[];
+    crf: number;
+};
+export declare const RECIPE_LIMITS: {
+    maxSeconds: number;
+    maxFps: number;
+    maxFrames: number;
+    maxActions: number;
+};
+/** Parse and bound a render recipe. Unknown fields are refused, never ignored. */
+export declare function parseRecipe(value: unknown, subject?: RenderSubject): RenderRecipe;
+/** Width and height of a PNG, from its IHDR chunk; refuses anything else. */
+export declare function pngSize(data: Uint8Array): {
+    width: number;
+    height: number;
+};
+/** The exact logical second of frame `index`: computed, never accumulated. */
+export declare function frameTime(recipe: RenderRecipe, index: number): number;
+/**
+ * The frame grid. Frame k exists exactly when `start + k / fps < end`: the
+ * span is half open, so a frame at `end` is not rendered and every frame
+ * before it is. The count is the smallest n with `start + n / fps >= end`,
+ * i.e. `ceil((end - start) * fps)`, with a tolerance of a billionth of a
+ * frame so a decimal end that is exactly on the grid (16 s at 30 fps is
+ * 480.00000000000006 in binary) is not rounded up a frame.
+ */
+export declare function frameCountFor(start: number, end: number, fps: number): number;
+export declare function frameCount(recipe: RenderRecipe): number;
+/** Learner actions due after `previous` and at or before `time`. */
+export declare function actionsBetween(recipe: RenderRecipe, previous: number, time: number): RenderAction[];
+export declare function sha256(data: string | Uint8Array): string;
+export type Encoder = {
+    ffmpeg: string;
+    ffprobe: string;
+    version: string;
+    libx264: boolean;
+};
+/**
+ * FFmpeg is an explicit, local dependency: `NERDBRO_FFMPEG` (and
+ * `NERDBRO_FFPROBE`) or `ffmpeg`/`ffprobe` on PATH. It is never downloaded.
+ */
+export declare function findEncoder(environment?: NodeJS.ProcessEnv): Promise<Encoder>;
+/** Audio is mixed and encoded at 48 kHz stereo. */
+export declare const MIX_SAMPLE_RATE = 48000;
+/** The exact audio length of `frames` video frames, in 48 kHz samples. */
+export declare function sampleCount(frames: number, fps: number): number;
+/**
+ * The FFmpeg arguments for one recipe: H.264 High, yuv420p, CFR, AAC audio,
+ * faststart. Frames are already the output size (proved per PNG), so the
+ * picture is never scaled. `audio` is the mixed track, or none for silence.
+ */
+export declare function encodeArguments(recipe: RenderRecipe, frames: string, output: string, audio?: string): string[];
+export declare function encode(encoder: Encoder, recipe: RenderRecipe, frames: string, output: string, audio?: string): Promise<void>;
+export type Probe = {
+    duration: number;
+    frames: number;
+    width: number;
+    height: number;
+    video_codec: string;
+    audio_codec: string | null;
+    pix_fmt: string;
+    fps: string;
+};
+export declare function probe(encoder: Encoder, file: string): Promise<Probe>;
+/** Refuse an encode that does not match its recipe: frame count, size, codecs and duration. */
+export declare function verifyProbe(recipe: RenderRecipe, result: Probe): void;
+/** One play or stop the runtime logged during a render (never sounded). */
+export type RenderAudioEvent = {
+    at_ms: number;
+    action: "play" | "stop" | string;
+    id: string;
+    /** Experience Scene key for a Scene's own sound; absent for an Experience sound. */
+    scene?: string;
+    /** Where in the asset playback starts (an audio clock resuming mid-file). */
+    offset_ms?: number;
+    loop?: boolean;
+    volume?: number;
+    role?: string;
+    sha256?: string | null;
+};
+/** One stretch of one sound in the mix. */
+export type AudioSegment = {
+    key: string;
+    at_ms: number;
+    offset_ms: number;
+    length_ms: number;
+    loop: boolean;
+    volume: number;
+};
+export declare const MIX_LIMITS: {
+    maxSegments: number;
+    maxSources: number;
+};
+export declare function audioKey(event: {
+    id: string;
+    scene?: string;
+}): string;
+/**
+ * The logged plays and stops as segments of a video that shows video time
+ * [startMs, endMs): a play opens one; the next stop or play of the same
+ * sound (a restart) closes it, and so does the end. A sound already playing
+ * at `startMs` enters the video that far into its asset. Times in the
+ * result are relative to the video's first frame. Events are in log order,
+ * which is time order.
+ */
+export declare function audioSegments(events: RenderAudioEvent[], endMs: number, startMs?: number): AudioSegment[];
+/**
+ * FFmpeg arguments that mix [segments] from their canonical files into one
+ * 48 kHz stereo PCM track of exactly `round(durationMs * 48)` samples. Each
+ * segment is its own input (a looping sound is an endlessly looped input),
+ * trimmed from its offset to its length, scaled by its volume and delayed
+ * to its start; the segments are summed without normalisation, so a sound
+ * is as loud as the runtime would play it. Returns null when nothing sounded.
+ *
+ * Everything is counted in samples, not timestamps: a looped AAC input
+ * leaves a 1,024-sample timestamp gap at every wrap (its priming is skipped
+ * again), so a timestamp trim came out one AAC frame short per loop. Each
+ * input is renumbered by decoded sample (`asetpts=N/SR/TB`), which makes a
+ * loop gapless at the asset's own decoded length, and the mix is padded and
+ * trimmed to the exact sample count.
+ */
+export declare function mixArguments(segments: AudioSegment[], files: Map<string, string>, durationMs: number, output: string): string[] | null;
+export declare function mix(encoder: Encoder, segments: AudioSegment[], files: Map<string, string>, durationMs: number, output: string): Promise<string[] | null>;
+/** Peak and mean level of a file's audio, in dBFS: proof the track is not silence. */
+export declare function audioLevel(encoder: Encoder, file: string): Promise<{
+    mean_db: number | null;
+    max_db: number | null;
+}>;
+export type PhaseSummary = {
+    count: number;
+    total_ms: number;
+    per_frame_ms: number;
+    p50_ms: number;
+    p95_ms: number;
+    max_ms: number;
+};
+/**
+ * Where capture time goes, per phase, across a render's frames: the frame
+ * loop records each phase's wall time and render.json reports totals,
+ * per-frame means and percentiles. Diagnostic only; it never affects a frame.
+ */
+export declare class PhaseTimes {
+    private readonly samples;
+    /** Only the frame loop records; setup and audio collection do not. */
+    active: boolean;
+    add(phase: string, milliseconds: number): void;
+    /** Time `body` as `phase`. */
+    time<T>(phase: string, body: () => Promise<T>): Promise<T>;
+    summary(frames: number): Record<string, PhaseSummary>;
+}