Project and artwork API

static create(options: ProjectOptions): StoryboardProject;

static fromJSON(input: unknown, options: {
    actor?: string;
} = {}): StoryboardProject;

static async open(path: string, options: {
    actor?: string;
} = {}): Promise<StoryboardProject>;

get id(): string;

get title(): string;

get canUndo(): boolean;

get canRedo(): boolean;

get version(): number;

toJSON(): StoryboardDocument;

previewComponentUpgrade(instanceId: string, options: ComponentUpgradeOptions = {}): {
    conflicts: ValueMergeConflict[];
    incomingChanges: string[];
    retainedLocalChanges: string[];
    version: number;
    instanceId: string;
    sourceVersion: number;
    owner: { kind: "panel" | "animation"; id: string; };
    inputHash: string;
    conflictsResolved: boolean;
};

componentOriginData(instanceId: string, options: PageOptions = {}): {
    version: number;
    instanceId: string;
    componentId: string;
    baselineVersion: number;
    sha256: string;
    instanceState: "missing" | "detached" | "matching" | "stale";
    instanceSource: { id: Id; version: number; } | null;
    libraryVersion: number | null;
    offset: number;
    limit: number;
    total: number;
    nextOffset: number | null;
    items: { location: "missing" | "instance" | "elsewhere"; sourceId: string; copyId: string; }[];
};

shotDependencyData(animationId: string, options: PageOptions = {}): {
    version: number;
    animationId: string;
    dependencyHash: string;
    total: number;
    offset: number;
    limit: number;
    nextOffset: number | null;
    items: ShotDependency[];
};

get studio(): import("../model/types/studio.js").StudioContent;

boardPanels(options: PageOptions = {}): { id: string; shotId: string; startFrame: number; durationFrames: number; transition: Transition; width: number; height: number; revision: number; }[];

shotAnimation(id: string): ShotAnimation;

editorialSequence(id: string): EditorialSequence;

shotCoordinates(animationId: string, targetId: string, options: CoordinateOptions = {}): ShotCoordinateSpace;

shotControllerData(animationId: string, controllerId: string, query: ShotControllerQuery = { collection: "keyframes" }): { collection: "targets" | "keyframes"; total: number; nextOffset: number | null; items: { frame: number; weight: number; easing: Easing; index: number; }[]; animationId: string; controllerId: string; name: string; mode: "replace" | "additive"; stackIndex: number; staticWeight: number; activeRange: { startFrame: number; endFrame: number; } | null; frame: number | null; evaluatedWeight: number | null; counts: { targets: number; keyframes: number; }; offset: number; limit: number; } | { collection: "targets" | "keyframes"; total: number; nextOffset: number | null; items: { evaluatedState: EvaluatedLayerState | null; layerId: string; values: Partial<Record<LayerChannel, number>>; index: number; }[]; animationId: string; controllerId: string; name: string; mode: "replace" | "additive"; stackIndex: number; staticWeight: number; activeRange: { startFrame: number; endFrame: number; } | null; frame: number | null; evaluatedWeight: number | null; counts: { targets: number; keyframes: number; }; offset: number; limit: number; };

shotMeshData(animationId: string, layerId: string, query: ShotMeshQuery = { collection: "keyframes" }): { animationId: string; layerId: string; bindingKind: "skin" | "mesh" | "curve" | "envelope"; curveRest: CurveMeshPose | null; curveSegments: number | null; envelopeRest: EnvelopeMeshPose | null; envelopeGrid: { columns: number; rows: number; } | null; collection: "joints"; offset: number; limit: number; total: number; nextOffset: number | null; counts: { joints: number; weights: number; vertices: number; triangles: number; keyframes: number; }; items: { layerId: string; id: string; bind: Readonly<AffineMatrix>; index: number; }[]; } | { animationId: string; layerId: string; bindingKind: "skin" | "mesh" | "curve" | "envelope"; curveRest: CurveMeshPose | null; curveSegments: number | null; envelopeRest: EnvelopeMeshPose | null; envelopeGrid: { columns: number; rows: number; } | null; collection: "weights"; offset: number; limit: number; total: number; nextOffset: number | null; counts: { joints: number; weights: number; vertices: number; triangles: number; keyframes: number; }; items: { index: number; influences: readonly { jointId: string; weight: number; }[]; }[]; } | { animationId: string; layerId: string; bindingKind: "skin" | "mesh" | "curve" | "envelope"; curveRest: CurveMeshPose | null; curveSegments: number | null; envelopeRest: EnvelopeMeshPose | null; envelopeGrid: { columns: number; rows: number; } | null; collection: "triangles"; offset: number; limit: number; total: number; nextOffset: number | null; counts: { joints: number; weights: number; vertices: number; triangles: number; keyframes: number; }; items: { index: number; vertices: number[]; }[]; } | { animationId: string; layerId: string; bindingKind: "skin" | "mesh" | "curve" | "envelope"; curveRest: CurveMeshPose | null; curveSegments: number | null; envelopeRest: EnvelopeMeshPose | null; envelopeGrid: { columns: number; rows: number; } | null; collection: "keyframes"; offset: number; limit: number; total: number; nextOffset: number | null; counts: { joints: number; weights: number; vertices: number; triangles: number; keyframes: number; }; items: { index: number; frame: number; easing: Easing; }[]; } | { frame: number | null; animationId: string; layerId: string; bindingKind: "skin" | "mesh" | "curve" | "envelope"; curveRest: CurveMeshPose | null; curveSegments: number | null; envelopeRest: EnvelopeMeshPose | null; envelopeGrid: { columns: number; rows: number; } | null; collection: "vertices"; offset: number; limit: number; total: number; nextOffset: number | null; counts: { joints: number; weights: number; vertices: number; triangles: number; keyframes: number; }; items: { x: number; y: number; index: number; }[]; };

shotPointCoordinates(animationId: string, targetId: string, point: {
    x: number;
    y: number;
}, options: ShotPointOptions): {
    animationId: string;
    targetId: string;
    frame: number;
    direction: "localToFrame" | "frameToLocal";
    candidates: ShotPointCandidate[];
};

editorialClips(sequenceId: string, options: PageOptions = {}): EditorialClip[];

scriptSummary(): { id: string; title: string; revision: number; entryCount: number; } | null;

palettes(options: PageOptions = {}): { id: string; name: string; swatchCount: number; }[];

paletteSwatches(id: string, options: PageOptions = {}): PaletteSwatch[];

paletteBindings(swatchId: string, options: PageOptions = {}): PaletteBindingUsage[];

putPalette(palette: Palette): this;

removePalette(id: string): this;

setColorBinding(elementId: string, channel: ColorChannel, binding: ColorBinding | null): this;

scriptEntries(options: PageOptions = {}): ScriptEntry[];

replaceScript(input: ScriptInput, expectedRevision: number): ScriptChangeReport;

shotBoardPanels(animationId: string, options: PageOptions = {}): { id: Id; shotId: Id; number: string; title: string; width: number; height: number; durationFrames: number; startFrame: number; transition: Transition; status: "working" | "review" | "approved"; action: string; dialogue: string; camera: string; notes: string; revision: number; }[];

studioAudioTracks(ownerId: string, options: PageOptions = {}): { clipCount: number; id: string; name: string; muted: boolean; }[];

studioAudioClips(ownerId: string, trackId: string, options: PageOptions = {}): StudioAudioClip[];

addShotElement(animationId: string, layerId: string, element: DrawingElement): this;

removeShotElements(animationId: string, layerId: string, ids: readonly string[]): this;

reviseShotElement(animationId: string, layerId: string, id: string, element: DrawingElement): this;

patchShotPixels(animationId: string, layerId: string, id: string, x: number, y: number, patch: import("../model/types.js").PixelBuffer): this;

setStudio(content: import("../model/types/studio.js").StudioContent): this;

capturePanelAnimation(panelId: string, options: PanelCaptureOptions): PanelCaptureResult;

duplicateShotAnimation(sourceAnimationId: string, options: ShotDuplicateOptions): ShotDuplicateResult;

instantiateShotCharacter(sourceAnimationId: string, options: CharacterInstanceOptions): CharacterInstanceResult;

editShotAnimation(id: string, edits: readonly import("../model/types/shot.js").ShotAnimationEdit[]): this;

putShotAnimation(animation: ShotAnimation): this;

putEditorialSequence(sequence: EditorialSequence): this;

editStudioAudio(ownerId: string, edits: readonly import("../model/types/studio-audio.js").StudioAudioEdit[]): this;

setStudioAudio(ownerId: string, tracks: readonly import("../model/types/studio-audio.js").StudioAudioTrack[]): this;

editEditorial(id: string, edits: readonly EditorialEdit[]): this;

removeShotAnimation(id: string): this;

removeEditorialSequence(id: string): this;

/** Validate serializable changes on an isolated draft, without changing this session. */
plan(label: string, commands: EditCommand[]): EditPlan;

/** Atomically save a plan and its receipt to this session's existing .cboard. */
async commit(input: EditPlan, options: {
    requestId: string;
}): Promise<CommitResult>;

readAsset(id: string): Buffer;

/** Capture the saved media source independently of later session saves or Save As. */
captureAssetReader(): (id: string) => Buffer;

async save(path: string, options: {
    overwrite?: boolean;
    expectedVersion?: number;
    assetRoot?: string;
} = {}): Promise<void>;

transaction<T>(label: string, work: () => T): T;

undo(): boolean;

redo(): boolean;

setMetadata(key: string, value: string): this;

configure(changes: ProjectChanges): this;

addScene(name: string, id?: Id): SceneHandle;

addSequence(name: string, id?: Id): SequenceHandle;

scene(id: Id): SceneHandle;

panel(id: Id): PanelHandle;

panelCaptions(id: Id): {
    id: string;
    title: string;
    action: string;
    dialogue: string;
    camera: string;
    notes: string;
};

select(query: {
    panelId: Id;
    layerId?: Id;
    elementIds?: Id[];
}): Selection;

/** Copy the current saved document; never replaces a source or existing destination. */
export async function migrateProject(sourcePath: string, targetPath: string, options: {
    expectedVersion?: number;
} = {}): Promise<ProjectMigrationReport>;

addScene(name: string, id?: Id): SceneHandle;

addShot(name: string, id?: Id): ShotHandle;

addPanel(options: PanelOptions = {}): PanelHandle;

addRasterLayer(name: string, options: LayerOptions = {}, parentGroupId?: Id): LayerHandle;

addVectorLayer(name: string, options: LayerOptions = {}, parentGroupId?: Id): LayerHandle;

addGroup(name: string, options: LayerOptions = {}, parentGroupId?: Id): LayerHandle;

addMotion(label: string, from: Point, to: Point, color = "#d14a32", id?: Id): Id;

revise(changes: Partial<Pick<Panel, "title" | "durationFrames" | "action" | "dialogue" | "camera" | "notes">>): this;

layer(id: Id): LayerHandle;

scene3D(scene: Scene3D, options: Partial<Pick<Scene3DElement, "id" | "name" | "matrix" | "opacity" | "visible">> = {}): Id;

rasterSurface(image: PixelBuffer, options: Partial<Pick<RasterSurface, "id" | "name" | "matrix" | "opacity" | "visible">> = {}): Id;

readPixels(elementId: Id, region?: PixelRegion): PixelBuffer;

editPixels(elementId: Id, region: PixelRegion, edit: (patch: PixelBuffer) => void): this;

rasterStroke(points: Point[], brush: BrushPreset, options: StrokeOptions = {}): Id;

erase(points: Point[], brush: BrushPreset, options: Omit<StrokeOptions, "erase"> = {}): Id;

vectorStroke(points: Point[], options: VectorStrokeOptions = {}): Id;

path(commands: PathCommand[], options: {
    id?: Id;
    name?: string;
    fill?: VectorFill;
    stroke?: string;
    strokeWidth?: number;
    opacity?: number;
} = {}): Id;

text(text: string, x: number, y: number, options: {
    id?: Id;
    name?: string;
    color?: string;
    font?: string;
    align?: "left" | "center" | "right";
    opacity?: number;
} = {}): Id;

set(changes: LayerChanges): this;

edit(elementId: Id, updater: (element: DrawingElement) => DrawingElement): this;

outlineStroke(elementId: Id): this;

booleanPath(elementId: Id, tool: readonly PathCommand[], operation: PathBooleanOperation): this;

transform(transform: Partial<Transform>, options: {
    pivot?: Pivot;
} = {}): this;

opacity(value: number): this;

remove(): void;

toJSON(): {
    code: ErrorCode;
    message: string;
    retryable: boolean;
    details: Readonly<Record<string, unknown>>;
};

/** Implementation inventory, not a production qualification or codec guarantee. */
export async function capabilities(options: {
    probeDependencies?: boolean;
    ffmpegPath?: string;
    ffprobePath?: string;
} = {}): Promise<CapabilityReport>;

function planDrawingElement(element: DrawingElement): PlanDrawingElement;

function planShotElement(element: DrawingElement): PlanDrawingElement;

function planShotAnimation(input: ShotAnimation): PlanShotAnimation;

function planComponentSource(input: readonly Layer[]): PlanStudioLayer[];

/** Prepare an atomic caption-only plan; the caller persists it and commits with a request ID. */
export function planCaptionImport(project: StoryboardProject, input: readonly CaptionImportRow[]): CaptionImportReport;

/** Import explicit stable entry IDs and panel links; does not mutate a project. */
export function importScriptCSV(csv: string, options: ScriptCSVOptions): ScriptInput;

/** Export editable script fields; callers retain project/script revision separately. */
export function exportScriptCSV(input: ScriptInput | ProductionScript): string;

/** Inspect the supported screenplay subset and every omitted element/attribute before binding IDs. */
export function inspectScriptFDX(xml: string): FDXInspection;

/** Import hash-bound, explicitly identified records; project revision and panel checks apply later. */
export function importScriptFDX(xml: string, input: FDXImportOptions): {
    script: ScriptInput;
    sourceSha256: string;
    losses: FDXLoss[];
};

/** Create explicitly staged panels and append their script links in the same recoverable commit. */
export function planScriptBoard(project: StoryboardProject, input: readonly ScriptBoardPanel[]): ScriptBoardReport;

/** Capture every board panel and conform its frozen incoming transitions in one version-pinned plan. */
export function planBoardCapture(project: StoryboardProject, input: BoardCaptureOptions): {
    plan: EditPlan;
    source: { projectId: string; version: number; durationFrames: number; };
    sequenceId: string;
    panels: { startFrame: number; durationFrames: number; revision: number; panelId: string; animationId: string; clipId: string; }[];
    audio: { mode: "omit" | "convert"; omittedTracks: number; mappings: { sourceId: string; targetId: string; }[]; quantizedPositions: number; };
};

/** Replace only the selected local-frame window of an existing shot mouth drawing track. */
export function planShotLipSync(project: StoryboardProject, animationId: string, layerId: string, options: LipSyncOptions): EditPlan;

/** Strict CSV: commas, escaped quotes and multiline quoted fields; no inferred panel matching. */
export function parseCaptionCSV(input: string): CaptionImportRow[];