@nodaro/sdk 1.30.1 → 2.1.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { CollaboratorRole, GenericNode, GenericEdge, WorkflowExport, WorkflowImportReport, WorkflowVisibility, Scene3DReference, Scene3DPlan, Scene3DEditOperation, Scene3DJobOutput as Scene3DJobOutput$1, ModelInputAdjustment, ConnectedReference, DescribedReference, TtsProvider, EntityStyle, CharacterAspectRatio, CharacterAttachColumn, LocationAssetType, LocationAttachColumn, SurroundDirection, ObjectAssetType, ObjectAttachColumn, ObjectAspectRatio, CreatureAttachColumn, PipelineInput, PipelineStatus, PipelineMode, PipelineStageName, SubGateName, ChatEnabledStage, ProposedChange, ReduceStrategyId, ReduceMeta, Voice, VoiceLibraryParams, VoiceLibraryResponse, VoiceClone, AudioFxPreset, BrowseCommunityParams, BrowseCommunityResult, CommunityCard, CommunityFullDetail, CommunityEntityType, CloneListingResult, FavoriteListingResult, CommunityReportReason, ReportListingResult, PublishListingParams, PublishListingResult, SharedListing, OrganizationView, OrgKind, OrgSettings, OrgPage, OrgMemberView, MemberStatus, WorkspaceRole, InvitationDelivery, InvitationState, InvitationView, InvitationPreview, OrgAuditEntry, UsageQuery, UsageReport, UsageLogEntry, WorkspaceSummary, WorkspaceView, WorkspaceSettings, WorkspaceMemberView, JoinCodeView, MeOrganizations } from '@nodaro/shared';
+import { CollaboratorRole, GenericNode, GenericEdge, WorkflowExport, WorkflowImportReport, WorkflowVisibility, Scene3DReference, Scene3DPlan, Scene3DEditOperation, Scene3DV2EditOperation, Scene3DJobOutputAny, Scene3DPlanV2, ModelInputAdjustment, ConnectedReference, DescribedReference, Scene3DAssetRef, TtsProvider, EntityStyle, CharacterAspectRatio, CharacterAttachColumn, LocationAssetType, LocationAttachColumn, SurroundDirection, ObjectAssetType, ObjectAttachColumn, ObjectAspectRatio, CreatureAttachColumn, PipelineInput, PipelineStatus, PipelineMode, PipelineStageName, SubGateName, ChatEnabledStage, ProposedChange, ReduceStrategyId, ReduceMeta, Voice, VoiceLibraryParams, VoiceLibraryResponse, VoiceClone, AudioFxPreset, BrowseCommunityParams, BrowseCommunityResult, CommunityCard, CommunityFullDetail, CommunityEntityType, CloneListingResult, FavoriteListingResult, CommunityReportReason, ReportListingResult, PublishListingParams, PublishListingResult, SharedListing, OrganizationView, OrgKind, OrgSettings, OrgPage, OrgMemberView, MemberStatus, WorkspaceRole, InvitationDelivery, InvitationState, InvitationView, InvitationPreview, OrgAuditEntry, UsageQuery, UsageReport, UsageLogEntry, WorkspaceSummary, WorkspaceView, WorkspaceSettings, WorkspaceMemberView, JoinCodeView, MeOrganizations } from '@nodaro/shared';
 export { AudioFxPreset, BrowseCommunityParams, BrowseCommunityResult, CHARACTER_ASPECT_DEFAULTS, CHARACTER_ASPECT_OPTIONS, CHARACTER_STYLES, OBJECT_ASPECT_DEFAULTS as CREATURE_ASPECT_DEFAULTS, OBJECT_ASPECT_OPTIONS as CREATURE_ASPECT_OPTIONS, CREATURE_ATTACH_COLUMNS, CharacterAspectRatio, CloneListingResult, CommunityCard, CommunityEntityType, CommunityReportReason, CommunitySort, ConnectedReference, ObjectAspectRatio as CreatureAspectRatio, CreatureAttachColumn, DescribedReference, EntityStyle, FavoriteListingResult, GenericEdge, GenericNode, InvitationDelivery, InvitationPreview, InvitationState, InvitationView, JoinCodeView, LOCATION_ASSET_TYPES, LOCATION_ATTACH_COLUMNS, LocationAssetType, LocationAttachColumn, MeOrganizations, MemberStatus, OBJECT_ASPECT_DEFAULTS, OBJECT_ASPECT_OPTIONS, OBJECT_ASSET_TYPES, OBJECT_ATTACH_COLUMNS, ObjectAspectRatio, ObjectAssetType, ObjectAttachColumn, OrgAuditEntry, OrgErrorCode, OrgKind, OrgMemberView, OrgPage, OrgRole, OrgSettings, OrgStatus, OrganizationSummary, OrganizationView, PROMPT_PREFIX_KEY, PROMPT_SUFFIX_KEY, PipelineStageName, PromptAffixFields, PublishListingParams, PublishListingResult, ReduceMeta, ReduceStrategyId, ReportListingResult, SURROUND_DIRECTIONS, SharedListing, SharedVoice, SurroundDirection, USAGE_GROUP_BYS, UsageGroupBy, UsageLogEntry, UsageQuery, UsageReport, UsageReportRow, UsageReportTotals, UsageVarianceRow, Voice, VoiceClone, VoiceLibraryParams, VoiceLibraryResponse, WORKSPACE_HEADER, WorkflowExport, WorkflowExportCharacter, WorkflowExportLocation, WorkflowExportObject, WorkspaceMemberView, WorkspaceRole, WorkspaceSettings, WorkspaceSummary, WorkspaceView } from '@nodaro/shared';
 import { DirectionFields, SubjectFields, PersonValue, WizardNodeContext, WizardQuestion, WizardSelection, RecommendedModel, FactoryPreset } from '@nodaro/prompts';
 export { PEOPLE, PERSON_DIMENSION_LABELS, PERSON_DIMENSION_ORDER, PersonValue, RecommendedModel, WizardNodeContext, WizardOption, WizardQuestion, WizardSelection, buildPersonHints } from '@nodaro/prompts';
@@ -648,8 +648,40 @@ declare class ExecutionsResource {
     }>;
 }
 
+/** Reuse newRevisionId for transport retries of the same immutable edit. */
+interface RetainedScene3DEditParams {
+    newRevisionId: string;
+    expectedContentHash: string;
+    operations: readonly Scene3DV2EditOperation[];
+    lockedObjectIds?: readonly string[];
+}
+interface RetainedScene3DEditResult {
+    scenePlan: Scene3DPlanV2;
+    changeSummary: string;
+}
+type Scene3DAuthoringEngine = "basic" | "blender-cloud" | "blender-local";
+interface Scene3DCapabilities {
+    basic: {
+        available: boolean;
+        sceneSchemaVersions: number[];
+    };
+    advanced: null | {
+        version: string;
+        engines: Array<Exclude<Scene3DAuthoringEngine, "basic">>;
+        sceneSchemaVersions: number[];
+        maxRepairPasses: number;
+    };
+}
+interface Scene3DEngineParams {
+    /** Basic is the default. Discover optional engines through scene3d.capabilities(). */
+    engine?: Scene3DAuthoringEngine;
+    acceptedSceneSchemaVersions?: readonly number[];
+    localConnectionId?: string;
+    quoteId?: string;
+    maxRepairPasses?: number;
+}
 /** Structured authoring inputs; reference roles are interpreted by the platform. */
-interface GenerateScene3DParams extends Record<string, unknown> {
+interface GenerateScene3DParams extends Record<string, unknown>, Scene3DEngineParams {
     prompt: string;
     durationSeconds?: number;
     fps?: number;
@@ -661,14 +693,14 @@ interface GenerateScene3DParams extends Record<string, unknown> {
     nodeId?: string;
 }
 /** Editing creates a new revision and never mutates the supplied scene. */
-interface EditScene3DParams extends Record<string, unknown> {
+interface EditScene3DParams extends Record<string, unknown>, Scene3DEngineParams {
     scenePlan: Scene3DPlan;
     expectedRevisionId: string;
     /** Replace the complete reference set, including clearing it with an empty list. Default: merge by id. */
     replaceReferences?: boolean;
     /** Supply an instruction or deterministic operations, never both. */
     prompt?: string;
-    operations?: readonly Scene3DEditOperation[];
+    operations?: readonly (Scene3DEditOperation | Scene3DV2EditOperation)[];
     references?: readonly Scene3DReference[];
     lockedObjectIds?: readonly string[];
     selectedObjectIds?: readonly string[];
@@ -685,7 +717,7 @@ interface RenderScene3DParams extends Record<string, unknown> {
     nodeId?: string;
 }
 /** Preserve the shared wire contract while allowing additive job metadata. */
-type Scene3DJobOutput = Readonly<Scene3DJobOutput$1> & Readonly<Record<string, unknown>>;
+type Scene3DJobOutput = Readonly<Scene3DJobOutputAny> & Readonly<Record<string, unknown>>;
 
 type NodeCategory = "input" | "parameter" | "ai-image" | "ai-video" | "ai-audio" | "ai-text" | "processing" | "composition" | "trigger" | "output" | "control" | "entity" | "utility";
 type OutputType = "text" | "image" | "video" | "audio" | "data" | "none";
@@ -1013,6 +1045,30 @@ declare class NodesResource {
     private pollJob;
 }
 
+/** Scene authoring and render-only export through the same platform nodes. */
+declare class Scene3DResource {
+    private client;
+    constructor(client: NodaroClient);
+    capabilities(): Promise<Scene3DCapabilities>;
+    /** Persist deterministic overlays without an LLM or a generation charge. */
+    applyEdits(revisionId: string, params: RetainedScene3DEditParams): Promise<RetainedScene3DEditResult>;
+    /** Asset access is scoped to an exact retained revision, with fresh authentication. */
+    assetBytes(revisionId: string, asset: Scene3DAssetRef, options?: {
+        signal?: AbortSignal;
+    }): Promise<ArrayBuffer>;
+    /** The editable native file has its own authorization lane. */
+    sourceBytes(revisionId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ArrayBuffer>;
+    generate(params: GenerateScene3DParams): Promise<RunNodeResult>;
+    generateAndWait(params: GenerateScene3DParams, options?: RunAndWaitOptions): Promise<Scene3DJobOutput>;
+    edit(params: EditScene3DParams): Promise<RunNodeResult>;
+    editAndWait(params: EditScene3DParams, options?: RunAndWaitOptions): Promise<Scene3DJobOutput>;
+    /** Uses the supplied immutable revision; never starts authoring or a rebuild. */
+    render(params: RenderScene3DParams): Promise<RunNodeResult>;
+    renderAndWait(params: RenderScene3DParams, options?: RunAndWaitOptions): Promise<NodeJobOutput>;
+}
+
 /**
  * OAuth scopes that a developer app may request. Mirrors
  * `backend/src/lib/scopes.ts#ALL_SCOPES`.
@@ -5487,6 +5543,481 @@ declare class RecastResource {
     resolveGate(recastId: string, input: ResolveRecastGateInput): Promise<Record<string, unknown>>;
 }
 
+/**
+ * Studio productions — `/v1/studio/productions`.
+ *
+ * A production is a Nodaro workflow whose `settings.studio` holds the shots:
+ * each shot a framed still, an optional animated clip, and the plan, looks,
+ * cast bindings and voice that made them. These routes are the platform's own
+ * reader and writer of that document, so an agent, a script and the studio app
+ * are looking at ONE production rather than three opinions about one row.
+ *
+ * Two rules run through the whole surface:
+ *
+ * - **Every change is an OPERATION** ({@link StudioProductionsResource.ops}),
+ *   addressed by stable key — a shot id, a role slug, a result's job id or url
+ *   — and never by position. That is what lets two writers hold the same
+ *   production open: a batch composed against a slightly older version still
+ *   applies correctly to the newest one, and the response says whether it was
+ *   rebased.
+ * - **Generation is run-then-poll.** A still or clip run returns job ids and
+ *   records a marker on the production; the results land when anyone — your
+ *   poll, the app, a later {@link StudioProductionsResource.reconcile} —
+ *   reports the finished job. Nothing waits minutes inside a request.
+ *
+ * Reads are `detail: "summary"` by default (counts and the active urls);
+ * `detail: "full"` adds every result with the context that regenerates it.
+ *
+ * **The ENVELOPES are typed here; the production DOCUMENT is not.** A view, a
+ * summary, a shot and an operation are open JSON on this surface
+ * ({@link StudioProduction}, `ops: unknown[]`) — their field-level types ship
+ * with the studio app, which is the one consumer that narrows them, and a
+ * second spelling of that vocabulary in the SDK would drift from it the first
+ * time either grew. Everything a caller branches on — `version`, `rebased`,
+ * `receipts`, `warnings`, a quote's `credits`, a run's `jobIds` — is typed.
+ *
+ * Cloud edition only: these routes 404 on deployments that do not serve them.
+ * Feature-detect once with `list()` — a deployment without them 404s that too,
+ * where a deployment with them answers an empty page.
+ */
+/**
+ * A production, a summary, a shot, a receipt's target: open JSON.
+ *
+ * Deliberately not narrowed here — see the note at the top of this module.
+ */
+type StudioProduction = Record<string, unknown>;
+/** How much of a production a read returns. */
+type StudioProductionDetail = "summary" | "full";
+/** One thing wrong with a plan, addressed at the field that is wrong. */
+interface StudioPlanIssue {
+    path: string;
+    message: string;
+    hint?: string;
+}
+/** `GET …/skill` — the authoring skill, rendered at request time from what is live. */
+interface StudioSkillResponse {
+    /** The authoring guide. */
+    skill: string;
+    /** Every picker, model and enum, in full. */
+    catalog: string;
+    /** The strict JSON Schema a plan is validated against. */
+    schema: Record<string, unknown>;
+    /** The operating guide: the tool map, the loops, the rules. */
+    operating: string;
+    /** The versions the three were rendered from — bare semver, no package names. */
+    generatedFrom: {
+        prompts: string;
+        shared: string;
+        codec: string;
+    };
+}
+interface StudioValidatePlanResponse {
+    valid: boolean;
+    errors: StudioPlanIssue[];
+    warnings: StudioPlanIssue[];
+    summary?: {
+        name?: string;
+        scenes: number;
+        shots: number;
+        cast: number;
+        /** Cast entries that matched a row in the caller's library. */
+        bound: number;
+    };
+}
+interface StudioListProductionsResponse {
+    data: StudioProduction[];
+    nextCursor?: string;
+}
+/** What a create or an import did, in the words a receipt would use. */
+interface StudioImportSummary {
+    shotsAdded: number;
+    castEnrolled: number;
+    /** Cast entries that resolved to a row in the caller's library. */
+    castBound: number;
+}
+interface StudioProductionResponse {
+    production: StudioProduction;
+    warnings?: StudioPlanIssue[];
+    summary?: StudioImportSummary;
+}
+interface StudioCreateProductionRequest {
+    name?: string;
+    plan?: Record<string, unknown>;
+}
+/** The caller's own retry token — 8–128 chars of `A-Za-z0-9_.:-`, never derived. */
+type StudioClientRequestId = string;
+/**
+ * A batch of operations, applied atomically.
+ *
+ * `ops` is `unknown[]`: the operation union is the studio app's vocabulary and
+ * the route validates it, refusing the whole batch with the offending index.
+ * The served operating guide is the runtime reference for what an operation
+ * looks like.
+ */
+interface StudioOpsRequest {
+    /** Applied in order. At most 100 per request. */
+    ops: unknown[];
+    /**
+     * The version the batch was composed against. INFORMATIONAL by default: the
+     * operations address by stable KEY, so a batch built on a slightly older
+     * document still applies exactly to the newest one, and the response says
+     * `rebased: true`. Omitting it means "apply to whatever is there".
+     */
+    baseVersion?: number;
+    /**
+     * Refuse to rebase. With `strict: true` a `baseVersion` older than the stored
+     * one is a 409 `workflow_conflict` carrying the current production, instead
+     * of a rebased apply — for the rare "replace exactly what I read" intent.
+     */
+    strict?: boolean;
+    /** Your own token for this batch, so a transport retry is not applied twice. */
+    clientRequestId?: StudioClientRequestId;
+}
+/**
+ * One line of what an operation did, in the words a change log would use.
+ *
+ * Past tense, the target named the way the user sees it, the side effect in a
+ * trailing parenthetical: `Deleted take 2 of Shot 1 (in the bin).`
+ */
+interface StudioOpsReceipt {
+    /** The operation this line reports, by name. */
+    op: string;
+    /** Past tense, naming the target the way a person would. */
+    summary: string;
+    /** Ids the operation MINTED — never ids the caller supplied. */
+    ids?: string[];
+}
+/** What a batch produced. Adopt `production` whole; do not merge into it. */
+interface StudioOpsResponse {
+    /** The canonical production AFTER the batch. */
+    production: StudioProduction;
+    /** The version the batch produced. Carry it as the next `baseVersion`. */
+    version: number;
+    /** True when the batch was applied to a newer document than it named. */
+    rebased: boolean;
+    /** One per operation, in order. */
+    receipts: StudioOpsReceipt[];
+    /**
+     * Things worth saying that are not failures — an operation that changed
+     * nothing, a rename that rewrote four prompts. A warning never rejects a
+     * batch; a refusal does.
+     */
+    warnings: string[];
+}
+/** What landing the finished jobs did. */
+interface StudioReconcileResponse {
+    /** Job ids whose media is now on the production. */
+    landed: string[];
+    /** Job ids still running — their markers stay; call again later. */
+    pending: string[];
+    /** Job ids that failed or were cancelled; their markers are cleared. */
+    failed: string[];
+    /** One line per landing that had something to say. */
+    warnings: string[];
+    /** The production after the landings. */
+    production: StudioProduction;
+    /** Its version — unchanged when nothing landed. */
+    version: number;
+}
+/** `POST …/:id/describe` — a Director run that will land as scenes. */
+interface StudioDescribeRequest {
+    brief: string;
+    llmModel: string;
+    /** `"append"` adds the drafted scenes; `"replace"` rewrites the film. */
+    mode?: "append" | "replace";
+    label?: string;
+    clientRequestId?: StudioClientRequestId;
+}
+/**
+ * `POST …/:id/generate` — one framing or directing run for one shot.
+ *
+ * `overrides` is what the CALL owns over what the shot's plan says: the model,
+ * the prose, the aspect, the direction ids. Open JSON, because the request
+ * builders' own option types are the contract and they ship with the studio.
+ */
+interface StudioGenerateRequest {
+    kind: "still" | "clip";
+    shotId: string;
+    /** Candidates to fan out (stills); the builder clamps it to the catalog's range. */
+    count?: number;
+    /** The directing input mode for a clip; absent ⇒ derived from the inputs. */
+    mode?: "start" | "references";
+    /** Price the run and return; nothing is submitted and nothing is written. */
+    dryRun?: boolean;
+    clientRequestId?: StudioClientRequestId;
+    overrides?: Record<string, unknown>;
+}
+/** Which video route a directing run went to — chosen from the inputs, never asked for. */
+type StudioVideoLane = "generate-video" | "text-to-video";
+/** `dryRun: true` — what this run would cost, and nothing else. */
+interface StudioGenerateEstimate {
+    dryRun: true;
+    provider: string;
+    count: number;
+    /** `null` when the model is unpriced or the instance runs without credits. */
+    credits: number | null;
+    lane?: StudioVideoLane;
+}
+/**
+ * A started (or already-started) run.
+ *
+ * `deduped` means the same `clientRequestId` came back and the job ids were
+ * answered from the production's own markers — nothing was submitted and
+ * nothing was charged, so `production` is absent.
+ */
+interface StudioGenerateResponse {
+    jobIds: string[];
+    lane?: StudioVideoLane;
+    deduped?: true;
+    production?: StudioProduction;
+    receipts?: StudioOpsReceipt[];
+    warnings?: string[];
+}
+/** `POST …/:id/frame` — a still pulled out of the shot's clip. */
+interface StudioFrameRequest {
+    shotId: string;
+    mode?: "first" | "last" | "timestamp";
+    /** Seconds, when `mode` is `"timestamp"`. */
+    timestamp?: number;
+    /** Where the grabbed image lands. `"new-shot"` inserts a shot after this one. */
+    target?: "new-shot" | "start-frame" | "end-frame" | "still";
+    clientRequestId?: StudioClientRequestId;
+}
+/** `POST …/:id/voice` — synthesize a shot's spoken line and record it. */
+interface StudioVoiceRequest {
+    shotId: string;
+    text: string;
+    voiceId?: string;
+    voiceType?: "premade" | "custom" | "library";
+    ttsProvider?: string;
+    /** The delivery levers; the text-to-speech route owns their bounds. */
+    delivery?: Record<string, number>;
+    clientRequestId?: StudioClientRequestId;
+}
+/** `POST …/:id/revoice` — recast the voices of the shot's active clip. */
+interface StudioRevoiceRequest {
+    shotId: string;
+    /** The speaker-ordered recast plan, forwarded to the voice route verbatim. */
+    plan: Record<string, unknown>;
+    clientRequestId?: StudioClientRequestId;
+}
+/** `POST …/:id/music` — the film's soundtrack. */
+interface StudioMusicRequest {
+    prompt: string;
+    duration?: number;
+    instrumental?: boolean;
+    vocalGender?: string;
+    model?: string;
+    clientRequestId?: StudioClientRequestId;
+}
+/**
+ * What a route that finished its work answers with: the production as it now
+ * stands, plus whatever that route produced.
+ *
+ * `jobId` is present on the routes that only STARTED something (a revoice, a
+ * soundtrack, a draft) — the result lands through its marker.
+ */
+interface StudioMediaResponse {
+    production: StudioProduction;
+    /** The grabbed frame's url, on the frame route. */
+    url?: string;
+    jobId?: string;
+    receipts?: StudioOpsReceipt[];
+    warnings?: string[];
+}
+/**
+ * `GET …/:id/export-plan` — the ordered steps an export would run.
+ *
+ * The caller runs them with the verbs that already exist; a route that chained
+ * three minutes-long jobs is the long-lived request every client times out on.
+ */
+interface StudioExportPlanResponse {
+    /** False when the production has fewer than two clips — nothing to stitch. */
+    canExport: boolean;
+    steps: StudioExportStep[];
+    /** The step whose output IS the film, or `null` when nothing can run. */
+    resultStepId: string | null;
+    /** Total credits, or `null` when ANY step is unpriced (a partial sum understates). */
+    estimate: number | null;
+    /** The credit models with no price, each named once, in step order. */
+    unpriced: string[];
+}
+interface StudioExportStep {
+    /** Stable within one plan and derived from the production, never minted. */
+    id: string;
+    label: string;
+    /** The node this step runs — `merge-video-audio`, `combine-videos`, `video-upscale`. */
+    node: string;
+    creditModel: string;
+    credits: number | null;
+    params: Record<string, unknown>;
+}
+/** `POST …/:id/clone` — a copy, which always starts private and visible. */
+interface StudioCloneRequest {
+    name?: string;
+}
+/** Either arm of a generation reply: the quote, or the run that started. */
+type StudioGenerateResult = StudioGenerateEstimate | StudioGenerateResponse;
+/** True when a generation reply is the `dryRun` QUOTE rather than a started run. */
+declare function isStudioGenerateEstimate(result: StudioGenerateResult): result is StudioGenerateEstimate;
+/** What a `generateStill` / `generateClip` call decides, beyond `kind` and the shot. */
+type StudioGenerateOptions = Omit<StudioGenerateRequest, "kind" | "shotId">;
+/**
+ * A route that only STARTED something — a draft, a revoice, a soundtrack. Its
+ * `jobId` is always there, which is what makes `const { jobId } = await …` and
+ * a poll the honest next line.
+ *
+ * `StudioMediaResponse` leaves `jobId` optional because the routes that FINISH
+ * their work (a frame, a voiceover) share the shape and have no job to name.
+ */
+type StudioJobStartedResponse = StudioMediaResponse & {
+    jobId: string;
+};
+interface ListStudioProductionsOptions {
+    limit?: number;
+    /** From a previous page's `nextCursor`. */
+    cursor?: string;
+    /** Include the rows the dashboard hides. Off by default. */
+    includeArchived?: boolean;
+}
+interface GetProductionOptions {
+    detail?: StudioProductionDetail;
+    /** Read ONE shot — the cheap way to re-read after a generation. */
+    shotId?: string;
+}
+interface StudioExportPlanOptions {
+    /** Plan the 4K finish too. Expensive, so it is always explicit. */
+    upscale?: boolean;
+}
+/** `client.studio.productions` — see the note at the top of this module. */
+declare class StudioProductionsResource {
+    private client;
+    constructor(client: NodaroClient);
+    private path;
+    /**
+     * The authoring guide, the full catalog, the plan's JSON Schema and the
+     * operating guide — rendered server-side from the version that is live, so
+     * they describe the platform you are actually talking to. Free.
+     */
+    skill(): Promise<StudioSkillResponse>;
+    /**
+     * Check a plan before it becomes anything. Free, persists nothing, and
+     * resolves cast names against YOUR library — loop on `errors` until
+     * `valid: true`, then `create({ plan })`.
+     */
+    validatePlan(plan: Record<string, unknown>): Promise<StudioValidatePlanResponse>;
+    /** Your productions, newest first. Archived rows are hidden unless asked for. */
+    list(opts?: ListStudioProductionsOptions): Promise<StudioListProductionsResponse>;
+    /**
+     * One production. A pure read — it never lands a finished job, so call
+     * {@link reconcile} first if you are waiting on one.
+     */
+    get(productionId: string, opts?: GetProductionOptions): Promise<StudioProduction>;
+    /**
+     * The ordered steps that assemble the film, with what they will cost. Run
+     * them yourself with the ordinary verbs — nothing here blocks for minutes,
+     * and nothing here spends.
+     */
+    exportPlan(productionId: string, opts?: StudioExportPlanOptions): Promise<StudioExportPlanResponse>;
+    /** A new production, optionally landed from a plan in the same call. */
+    create(input?: StudioCreateProductionRequest): Promise<StudioProductionResponse>;
+    /**
+     * Apply a batch of operations. Atomic: one bad operation refuses the whole
+     * batch with a `StudioOpError` naming its index, and nothing is written. On
+     * success adopt `production` wholesale and carry `version` forward as the
+     * next `baseVersion`.
+     */
+    ops(productionId: string, input: StudioOpsRequest): Promise<StudioOpsResponse>;
+    /**
+     * Land every generation that has finished since you last looked, and report
+     * what is still running. The one call that turns finished jobs into results
+     * without a browser open. It writes only when something actually landed.
+     */
+    reconcile(productionId: string): Promise<StudioReconcileResponse>;
+    /** Add a plan's scenes to a production that already exists. */
+    importPlan(productionId: string, plan: Record<string, unknown>, opts?: {
+        mode?: "append";
+    }): Promise<StudioProductionResponse>;
+    /**
+     * Turn a brief into scenes. The run is a platform job: poll it, and its
+     * scenes land through {@link reconcile}. The production comes back with the
+     * run recorded on it as a pending draft.
+     */
+    describe(productionId: string, input: StudioDescribeRequest): Promise<StudioJobStartedResponse>;
+    /**
+     * Frame or animate one shot.
+     *
+     * The request is assembled server-side from the shot's own plan, looks and
+     * bound references, so a scripted run and a press of the button in the app
+     * produce the same media; `overrides` changes THIS run without changing the
+     * shot. Prefer {@link generateStill} / {@link generateClip}, which say which
+     * kind they mean.
+     *
+     * `dryRun: true` returns the quote and writes nothing — narrow the reply with
+     * {@link isStudioGenerateEstimate}.
+     */
+    generate(productionId: string, input: StudioGenerateRequest & {
+        dryRun: true;
+    }): Promise<StudioGenerateEstimate>;
+    generate(productionId: string, input: StudioGenerateRequest): Promise<StudioGenerateResult>;
+    /**
+     * Frame a shot: submit `count` candidates and record a pending marker for
+     * each. Results ACCUMULATE — a generate never replaces what is there.
+     *
+     * `clientRequestId` makes a retry safe: the same token answers with the jobs
+     * the first call started (`deduped: true`) and submits nothing. Never retry a
+     * spend without it.
+     */
+    generateStill(productionId: string, shotId: string, opts: StudioGenerateOptions & {
+        dryRun: true;
+    }): Promise<StudioGenerateEstimate>;
+    generateStill(productionId: string, shotId: string, opts?: StudioGenerateOptions): Promise<StudioGenerateResult>;
+    /**
+     * Animate a shot. The LANE is chosen from the shot's inputs (a start frame,
+     * references, a prompt) — never passed in — and reported back as `lane`.
+     */
+    generateClip(productionId: string, shotId: string, opts: StudioGenerateOptions & {
+        dryRun: true;
+    }): Promise<StudioGenerateEstimate>;
+    generateClip(productionId: string, shotId: string, opts?: StudioGenerateOptions): Promise<StudioGenerateResult>;
+    /**
+     * Extract a frame from a shot's active clip and put it where `target` says —
+     * a new shot after this one (the default), this shot's sticky start or end
+     * frame, or another still of the same shot. Seconds, not minutes: this one
+     * waits for the job and answers with the changed production.
+     */
+    frame(productionId: string, input: StudioFrameRequest): Promise<StudioMediaResponse>;
+    /** Synthesize a shot's spoken line and record it. Waits for the job. */
+    voice(productionId: string, input: StudioVoiceRequest): Promise<StudioMediaResponse>;
+    /**
+     * Recast the voices of a shot's active clip. Minutes of work, so it answers
+     * `jobId` and the new clip lands as a result through its own marker.
+     */
+    revoice(productionId: string, input: StudioRevoiceRequest): Promise<StudioJobStartedResponse>;
+    /** Score the film. The finished track lands through its pending marker. */
+    music(productionId: string, input: StudioMusicRequest): Promise<StudioJobStartedResponse>;
+    /**
+     * Open the share-by-link read. Deliberately its own route rather than an
+     * operation: who may see the work is decided by the owner, never as a side
+     * effect of a batch that was editing something else.
+     */
+    share(productionId: string): Promise<StudioProduction>;
+    /** Close it again. Sharing is opt-in AND reversible. */
+    unshare(productionId: string): Promise<StudioProduction>;
+    /**
+     * Copy a production you own or can see into your own Studio project. The
+     * copy starts PRIVATE and visible — sharing and archiving never travel — and
+     * it is copied through YOUR view of the source, so somebody else's bin does
+     * not come with it.
+     */
+    clone(productionId: string, input?: StudioCloneRequest): Promise<StudioProduction>;
+}
+/** `client.studio` — the studio's own surface on the platform. */
+declare class StudioResource {
+    readonly productions: StudioProductionsResource;
+    constructor(client: NodaroClient);
+}
+
 /**
  * The community-listing types are the single source of truth in
  * `@nodaro/shared` (re-used by the backend, frontend, and CLI). Re-export them
@@ -6072,6 +6603,7 @@ declare class NodaroClient {
     readonly videoPro: VideoProResource;
     readonly executions: ExecutionsResource;
     readonly nodes: NodesResource;
+    readonly scene3d: Scene3DResource;
     readonly developerApps: DeveloperAppsResource;
     readonly oauth: OAuthResource;
     readonly apps: AppsResource;
@@ -6095,6 +6627,7 @@ declare class NodaroClient {
     readonly models: ModelsResource;
     readonly shots: ShotsResource;
     readonly recast: RecastResource;
+    readonly studio: StudioResource;
     readonly community: CommunityResource;
     readonly templates: TemplatesResource;
     readonly tutorials: TutorialsResource;
@@ -6123,6 +6656,10 @@ declare class NodaroClient {
      * ({@link request}) and the text path ({@link requestText}) go through here.
      */
     private send;
+    /** Authenticated, bounded binary reads through the normal timeout/error transport. */
+    requestBytes(method: string, path: string, options: RequestOptions & {
+        maxBytes: number;
+    }): Promise<ArrayBuffer>;
     request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
     /**
      * Like {@link request}, for endpoints that answer text (CSV exports). Errors
@@ -6187,7 +6724,39 @@ declare class WorkflowConflictError extends NodaroError {
     readonly currentUpdatedAt?: string | undefined;
     readonly currentVersion?: number | undefined;
     readonly currentRecord?: Record<string, unknown> | undefined;
-    constructor(message?: string, currentUpdatedAt?: string | undefined, currentVersion?: number | undefined, currentRecord?: Record<string, unknown> | undefined);
+    constructor(message?: string, currentUpdatedAt?: string | undefined, currentVersion?: number | undefined, currentRecord?: Record<string, unknown> | undefined, 
+    /**
+     * The wire code this conflict actually arrived with.
+     *
+     * `production_busy` is the studio production routes' own 409: the row
+     * changed under a read-modify-write and the server exhausted its retries.
+     * It is the same situation and the same remedy — re-read and apply again —
+     * so it is the same ERROR, and a caller catching `WorkflowConflictError`
+     * handles both. The code stays truthful because a caller that logs or
+     * branches on it should see what the server said, not what the class is
+     * usually called.
+     */
+    code?: WorkflowConflictCode);
+}
+/** The 409 codes that mean "somebody else wrote first; re-read and retry". */
+type WorkflowConflictCode = "workflow_conflict" | "production_busy";
+/**
+ * A studio operation batch was refused, and the error names WHICH operation
+ * (`opIndex`, zero-based) was wrong. Nothing in the batch was written: a batch
+ * applies atomically or not at all, so fix that one operation and send the
+ * whole batch again.
+ *
+ * Selected by SHAPE — any 4xx carrying a numeric `opIndex` — not by a list of
+ * codes, so a new refusal reason (`op_invalid`, `op_target_missing`, whatever
+ * the server adds next) reaches the caller as this error without an SDK
+ * release. `code` is whatever the server sent.
+ */
+declare class StudioOpError extends NodaroError {
+    /** Zero-based index into the `ops` array that was sent. */
+    readonly opIndex: number;
+    constructor(message: string, code: string, status: number, 
+    /** Zero-based index into the `ops` array that was sent. */
+    opIndex: number);
 }
 /**
  * HTTP 422 `job_blocked`. A job policy registered by this deployment refused
@@ -6266,9 +6835,10 @@ interface ApiErrorBody {
         required?: number;
         available?: number;
         limitBytes?: number;
+        opIndex?: number;
         [key: string]: unknown;
     };
 }
 declare function throwFromResponse(status: number, body: ApiErrorBody): never;
 
-export { type AccessTokenResponse, type AnalyzeInput, type AnalyzeResult, type AppRun, type AppRunResult, type ApplyChatProposalResult, type ApproveCreatureMainImageResult, type ApproveMainImageResult, type ApproveObjectMainImageResult, type ApprovePortraitResult, AppsResource, AudioResource, type Auth, type BranchPipelineInput, type BranchPipelineResult, type BrowseTemplatesParams, type BrowseTemplatesResult, CREATURE_ASSET_TYPES, CallbackAuth, type CancelExecutionParams, type CancelJobResult, CatalogsResource, type Character, type CharacterDetail, type CharacterUsage, CharactersResource, type ChatStageResult, type ChatTurn, type ClientOptions, type CloneTemplateParams, type CloneTemplateResult, CommunityResource, type ContinueVideoProResult, type CreateCreatureInput, type CreateDeveloperAppInput, type CreateDeveloperAppResult, type CreateLocationInput, type CreateObjectInput, type CreateOrgInput, type CreateProjectInput, type CreateRecastInput, type CreateShotInput, type CreateWorkflowInput, type CreateWorkspaceInput, type Creature, type CreatureAssetType, type CreatureDetail, type CreatureReferencePhoto, type CreatureReferencePhotoKind, CreaturesResource, type CreditStatus, CreditsResource, type DeleteAppRunResult, type DeleteJobResult, type DeveloperApp, type DeveloperAppScope, type DeveloperAppStatus, DeveloperAppsResource, type DownloadVideoProgress, type DubbingInput, type DuplicateCharacterInput, type EditScene3DParams, type EnhanceInput, type EstimateRecastInput, type EstimateRecastRescoreInput, type ExchangeCodeInput, type ExecutionStatus, type ExecutionTriggerType, ExecutionsResource, type FactoryPresetsResult, ForbiddenError, type GenerateAssetInput, type GenerateCharacterInput, type GenerateCharacterResult, type GenerateCreatureAssetInput, type GenerateCreatureAssetResult, type GenerateCreatureInput, type GenerateCreatureMotionInput, type GenerateCreatureMotionResult, type GenerateCreatureResult, type GenerateImageParams, type GenerateInput, type GenerateLocationAssetInput, type GenerateLocationInput, type GenerateLocationResult, type GenerateMotionInput, type GenerateObjectAssetInput, type GenerateObjectAssetResult, type GenerateObjectInput, type GenerateObjectMotionInput, type GenerateObjectMotionResult, type GenerateObjectResult, type GenerateScene3DParams, type GenerateSurroundContinuationInput, type GenerateVideoParams, type GetPickerCatalogOptions, InsufficientCreditsError, type InviteInput, type Job, JobAbortedError, JobBlockedError, type JobErrorHint, JobFailedError, JobHeldError, type JobStatus, type JobStatusResult, JobTimeoutError, JobsResource, type LibraryAsset, LibraryResource, type ListAppRunsParams, type ListAppsParams, type ListAppsResult, type ListCharactersParams, type ListCharactersResult, type ListCreaturesParams, type ListExecutionsForWorkflowParams, type ListExecutionsPage, type ListInvitationsOptions, type ListJobsPage, type ListJobsParams, type ListLibraryParams, type ListLibraryResult, type ListLocationsParams, type ListModelsOptions, type ListObjectsParams, type ListWorkflowsParams, LlmResource, type LlmStructuredInput, type LlmStructuredJobInput, type LlmStructuredJobOutput, type LlmStructuredResult, type Location, type LocationDetail, type LocationReferencePhoto, type LocationReferencePhotoKind, LocationsResource, type MediaProcessInput, type MediaProcessResult, MediaResource, type ModelCostsResult, type ModelSummary, type ModelsListResult, ModelsResource, NodaroClient, NodaroError, type NodeCategory, type NodeDescriptor, type NodeExecutionState, type NodeInputField, type NodeInputSchema, type NodeJobOutput, type NodePreset, type NodePresetGroup, NodesResource, NotFoundError, type OAuthAppInfo, OAuthResource, type Object$1 as Object, type ObjectCategory, type ObjectDetail, type ObjectReferencePhoto, type ObjectReferencePhotoKind, ObjectsResource, OrganizationsResource, type OutputType, type PickerCatalog, type PickerCatalogSummary, PickerCatalogsResource, type PickerDimension, type PickerOption, PipelinesResource, type PolicyBlockHint, PresetsResource, type Project, type ProjectedCatalog, type ProjectedCatalogDimension, type ProjectedCatalogOption, ProjectsResource, PromptHelperResource, type PromptResult, type PublishedApp, type PublishedAppDetail, RateLimitedError, type RecaptionCreatureResult, type RecaptionLocationResult, type RecaptionObjectResult, type RecaptionResult, type RecastAudioLayerName, type RecastAudioManifestV1, type RecastAudioMix, type RecastAudioMixControl, type RecastAudioSectionReplacement, type RecastEstimate, type RecastRescoreOperation, type RecastRescoreQuote, type RecastRescoreReplacement, type RecastRescoreRequestV2, type RecastRescoreResponse, RecastResource, type RecastRunSnapshot, type RecastScriptImportResult, type RecastScriptValidation, type RecastScriptValidationError, type ReduceInput, ReduceResource, type ReduceResult, type ReferencePhoto, type ReferencePhotoKind, type RenderScene3DParams, type ResolveRecastGateInput, type RotateSecretResult, type RunAndWaitOptions, type RunAppOptions, type RunManyResult, type RunNodeAdjustment, type RunNodeResult, type RunWorkflowParams, type RunWorkflowResult, type SafetyBlockHint, type Scene3DJobOutput, type Shot, type ShotEntityRef, type ShotMode, ShotsResource, StaticTokenAuth, type StopVideoProResult, StorageExceededError, type StructuredReferenceParams, type Template, type TemplateBrowseCard, type TemplateSort, TemplatesResource, type TextToVideoParams, type TutorialCategory, type TutorialFlowItem, type TutorialVideoItem, TutorialsResource, UnauthorizedError, type UpdateCreatureInput, type UpdateCreatureResult, type UpdateDeveloperAppInput, type UpdateLocationInput, type UpdateLocationResult, type UpdateObjectInput, type UpdateObjectResult, type UpdateProjectInput, type UpdateShotInput, type UpdateWorkflowInput, type UploadResult, UploadsResource, type UpsertCharacterInput, type UpsertCharacterResult, type UpsertCreatureInput, type UpsertCreatureResult, type UpsertObjectInput, type UpsertObjectResult, type UserBalance, type UserIdentity, type VcpAnalysis, type VcpAnalysisSpeaker, type VcpAnalyzeInput, type VcpExportInput, type VcpExportTrack, type VideoMetadata, VideoProResource, type VoiceChangerProInput, type VoiceChangerProVoice, type VoiceDesignInput, type VoiceRemixInput, VoicesResource, type Workflow, WorkflowConflictError, type WorkflowExecution, type WorkflowExecutionSummary, WorkflowsResource, WorkspacesResource, buildPersonSeedPrompt, createClient, supabaseAuth, throwFromResponse };
+export { type AccessTokenResponse, type AnalyzeInput, type AnalyzeResult, type AppRun, type AppRunResult, type ApplyChatProposalResult, type ApproveCreatureMainImageResult, type ApproveMainImageResult, type ApproveObjectMainImageResult, type ApprovePortraitResult, AppsResource, AudioResource, type Auth, type BranchPipelineInput, type BranchPipelineResult, type BrowseTemplatesParams, type BrowseTemplatesResult, CREATURE_ASSET_TYPES, CallbackAuth, type CancelExecutionParams, type CancelJobResult, CatalogsResource, type Character, type CharacterDetail, type CharacterUsage, CharactersResource, type ChatStageResult, type ChatTurn, type ClientOptions, type CloneTemplateParams, type CloneTemplateResult, CommunityResource, type ContinueVideoProResult, type CreateCreatureInput, type CreateDeveloperAppInput, type CreateDeveloperAppResult, type CreateLocationInput, type CreateObjectInput, type CreateOrgInput, type CreateProjectInput, type CreateRecastInput, type CreateShotInput, type CreateWorkflowInput, type CreateWorkspaceInput, type Creature, type CreatureAssetType, type CreatureDetail, type CreatureReferencePhoto, type CreatureReferencePhotoKind, CreaturesResource, type CreditStatus, CreditsResource, type DeleteAppRunResult, type DeleteJobResult, type DeveloperApp, type DeveloperAppScope, type DeveloperAppStatus, DeveloperAppsResource, type DownloadVideoProgress, type DubbingInput, type DuplicateCharacterInput, type EditScene3DParams, type EnhanceInput, type EstimateRecastInput, type EstimateRecastRescoreInput, type ExchangeCodeInput, type ExecutionStatus, type ExecutionTriggerType, ExecutionsResource, type FactoryPresetsResult, ForbiddenError, type GenerateAssetInput, type GenerateCharacterInput, type GenerateCharacterResult, type GenerateCreatureAssetInput, type GenerateCreatureAssetResult, type GenerateCreatureInput, type GenerateCreatureMotionInput, type GenerateCreatureMotionResult, type GenerateCreatureResult, type GenerateImageParams, type GenerateInput, type GenerateLocationAssetInput, type GenerateLocationInput, type GenerateLocationResult, type GenerateMotionInput, type GenerateObjectAssetInput, type GenerateObjectAssetResult, type GenerateObjectInput, type GenerateObjectMotionInput, type GenerateObjectMotionResult, type GenerateObjectResult, type GenerateScene3DParams, type GenerateSurroundContinuationInput, type GenerateVideoParams, type GetPickerCatalogOptions, type GetProductionOptions, InsufficientCreditsError, type InviteInput, type Job, JobAbortedError, JobBlockedError, type JobErrorHint, JobFailedError, JobHeldError, type JobStatus, type JobStatusResult, JobTimeoutError, JobsResource, type LibraryAsset, LibraryResource, type ListAppRunsParams, type ListAppsParams, type ListAppsResult, type ListCharactersParams, type ListCharactersResult, type ListCreaturesParams, type ListExecutionsForWorkflowParams, type ListExecutionsPage, type ListInvitationsOptions, type ListJobsPage, type ListJobsParams, type ListLibraryParams, type ListLibraryResult, type ListLocationsParams, type ListModelsOptions, type ListObjectsParams, type ListStudioProductionsOptions, type ListWorkflowsParams, LlmResource, type LlmStructuredInput, type LlmStructuredJobInput, type LlmStructuredJobOutput, type LlmStructuredResult, type Location, type LocationDetail, type LocationReferencePhoto, type LocationReferencePhotoKind, LocationsResource, type MediaProcessInput, type MediaProcessResult, MediaResource, type ModelCostsResult, type ModelSummary, type ModelsListResult, ModelsResource, NodaroClient, NodaroError, type NodeCategory, type NodeDescriptor, type NodeExecutionState, type NodeInputField, type NodeInputSchema, type NodeJobOutput, type NodePreset, type NodePresetGroup, NodesResource, NotFoundError, type OAuthAppInfo, OAuthResource, type Object$1 as Object, type ObjectCategory, type ObjectDetail, type ObjectReferencePhoto, type ObjectReferencePhotoKind, ObjectsResource, OrganizationsResource, type OutputType, type PickerCatalog, type PickerCatalogSummary, PickerCatalogsResource, type PickerDimension, type PickerOption, PipelinesResource, type PolicyBlockHint, PresetsResource, type Project, type ProjectedCatalog, type ProjectedCatalogDimension, type ProjectedCatalogOption, ProjectsResource, PromptHelperResource, type PromptResult, type PublishedApp, type PublishedAppDetail, RateLimitedError, type RecaptionCreatureResult, type RecaptionLocationResult, type RecaptionObjectResult, type RecaptionResult, type RecastAudioLayerName, type RecastAudioManifestV1, type RecastAudioMix, type RecastAudioMixControl, type RecastAudioSectionReplacement, type RecastEstimate, type RecastRescoreOperation, type RecastRescoreQuote, type RecastRescoreReplacement, type RecastRescoreRequestV2, type RecastRescoreResponse, RecastResource, type RecastRunSnapshot, type RecastScriptImportResult, type RecastScriptValidation, type RecastScriptValidationError, type ReduceInput, ReduceResource, type ReduceResult, type ReferencePhoto, type ReferencePhotoKind, type RenderScene3DParams, type ResolveRecastGateInput, type RetainedScene3DEditParams, type RetainedScene3DEditResult, type RotateSecretResult, type RunAndWaitOptions, type RunAppOptions, type RunManyResult, type RunNodeAdjustment, type RunNodeResult, type RunWorkflowParams, type RunWorkflowResult, type SafetyBlockHint, type Scene3DAuthoringEngine, type Scene3DCapabilities, type Scene3DJobOutput, Scene3DResource, type Shot, type ShotEntityRef, type ShotMode, ShotsResource, StaticTokenAuth, type StopVideoProResult, StorageExceededError, type StructuredReferenceParams, type StudioClientRequestId, type StudioCloneRequest, type StudioCreateProductionRequest, type StudioDescribeRequest, type StudioExportPlanOptions, type StudioExportPlanResponse, type StudioExportStep, type StudioFrameRequest, type StudioGenerateEstimate, type StudioGenerateOptions, type StudioGenerateRequest, type StudioGenerateResponse, type StudioGenerateResult, type StudioImportSummary, type StudioJobStartedResponse, type StudioListProductionsResponse, type StudioMediaResponse, type StudioMusicRequest, StudioOpError, type StudioOpsReceipt, type StudioOpsRequest, type StudioOpsResponse, type StudioPlanIssue, type StudioProduction, type StudioProductionDetail, type StudioProductionResponse, StudioProductionsResource, type StudioReconcileResponse, StudioResource, type StudioRevoiceRequest, type StudioSkillResponse, type StudioValidatePlanResponse, type StudioVideoLane, type StudioVoiceRequest, type Template, type TemplateBrowseCard, type TemplateSort, TemplatesResource, type TextToVideoParams, type TutorialCategory, type TutorialFlowItem, type TutorialVideoItem, TutorialsResource, UnauthorizedError, type UpdateCreatureInput, type UpdateCreatureResult, type UpdateDeveloperAppInput, type UpdateLocationInput, type UpdateLocationResult, type UpdateObjectInput, type UpdateObjectResult, type UpdateProjectInput, type UpdateShotInput, type UpdateWorkflowInput, type UploadResult, UploadsResource, type UpsertCharacterInput, type UpsertCharacterResult, type UpsertCreatureInput, type UpsertCreatureResult, type UpsertObjectInput, type UpsertObjectResult, type UserBalance, type UserIdentity, type VcpAnalysis, type VcpAnalysisSpeaker, type VcpAnalyzeInput, type VcpExportInput, type VcpExportTrack, type VideoMetadata, VideoProResource, type VoiceChangerProInput, type VoiceChangerProVoice, type VoiceDesignInput, type VoiceRemixInput, VoicesResource, type Workflow, type WorkflowConflictCode, WorkflowConflictError, type WorkflowExecution, type WorkflowExecutionSummary, WorkflowsResource, WorkspacesResource, buildPersonSeedPrompt, createClient, isStudioGenerateEstimate, supabaseAuth, throwFromResponse };