@nodaro/sdk 2.34.0 → 2.39.0

package/dist/entries/errors.d.ts

@@ -1,4 +1,4 @@
-import { x as StudioOpsResponse } from '../studio-productions-vbCNSbtf.js';
+import { x as StudioOpsResponse } from '../studio-productions-DtTE8mdl.js';
 import '../developer-apps-zSQXWmEG.js';
 import '@nodaro/shared/apps';
 import '@nodaro/shared/organizations';
@@ -6,7 +6,15 @@ import '@nodaro/shared/organizations';
 declare class NodaroError extends Error {
     readonly code: string;
     readonly status: number;
-    constructor(message: string, code: string, status: number);
+    /**
+     * Every other field of the server's error envelope (`{ error: { code,
+     * message, … } }`), as it was sent: for example a trend refusal's `slot`, a
+     * publish refusal's `reasons`, a validation error's `issues`. Empty when the
+     * envelope had nothing else, or for an error the SDK made itself. A copy —
+     * changing it changes nothing else.
+     */
+    readonly details: Readonly<Record<string, unknown>>;
+    constructor(message: string, code: string, status: number, details?: Readonly<Record<string, unknown>>);
 }
 declare class UnauthorizedError extends NodaroError {
     constructor(message?: string);
@@ -21,10 +29,38 @@ declare class NotFoundError extends NodaroError {
 declare class RateLimitedError extends NodaroError {
     constructor(message?: string);
 }
+/**
+ * HTTP 402: the run costs more than the caller may spend. `code` is the
+ * refusal's own code — `insufficient_credits` for the caller's own balance, or
+ * another 402 code such as `free_video_limit`. A spending cap someone else set
+ * (a workspace budget, a member cap, a per-user allowance) is the subclass
+ * {@link CreditCapExceededError}, so `instanceof InsufficientCreditsError`
+ * still catches every 402.
+ */
 declare class InsufficientCreditsError extends NodaroError {
     readonly required?: number | undefined;
     readonly available?: number | undefined;
-    constructor(message?: string, required?: number | undefined, available?: number | undefined);
+    constructor(message?: string, required?: number | undefined, available?: number | undefined, code?: string);
+}
+/** The 402 codes of a spending cap set by someone other than the caller. */
+type CreditCapCode = "budget_exceeded" | "member_cap_exceeded" | "user_allowance_exceeded";
+/**
+ * The 402 codes {@link CreditCapExceededError} carries: the workspace's budget
+ * (`budget_exceeded`), the caller's cap in that workspace
+ * (`member_cap_exceeded`), the deployment's per-user allowance
+ * (`user_allowance_exceeded`).
+ */
+declare const CREDIT_CAP_CODES: ReadonlySet<CreditCapCode>;
+/**
+ * HTTP 402 from a spending cap, not from the caller's own balance: topping up
+ * does not help — whoever set the cap (the workspace's owner, the deployment's
+ * operator) has to raise it. An {@link InsufficientCreditsError}, so existing
+ * catches keep working; `code` says which cap. `available`, when sent, is what
+ * the cap has left.
+ */
+declare class CreditCapExceededError extends InsufficientCreditsError {
+    readonly code: CreditCapCode;
+    constructor(code: CreditCapCode, message?: string, required?: number, available?: number);
 }
 declare class StorageExceededError extends NodaroError {
     readonly limitBytes?: number | undefined;
@@ -329,10 +365,12 @@ interface ApiErrorBody {
     required?: unknown;
     /** …and what the caller has (withheld on a deployment-paid instance). */
     balance?: unknown;
+    /** A per-user allowance's 402: what the allowance has left. */
+    remaining?: unknown;
     /** `app_run_version_changed`: the version the run ran, and the one the caller is on. */
     runVersion?: unknown;
     appVersion?: unknown;
 }
 declare function throwFromResponse(status: number, body: ApiErrorBody): never;
 
-export { AlreadyRunningError, AppRunVersionChangedError, ContinuationPreviewPendingError, ContinuationRefusedError, ForbiddenError, type HeldFinalRun, InsufficientCreditsError, JobAbortedError, JobBlockedError, JobFailedError, JobHeldError, JobTimeoutError, NodaroError, NotFoundError, RateLimitedError, StorageExceededError, StudioOpError, StudioPreviewAppliedError, StudioPreviewUnavailable, UnauthorizedError, type WorkflowConflictCode, WorkflowConflictError, throwFromResponse };
+export { AlreadyRunningError, AppRunVersionChangedError, CREDIT_CAP_CODES, ContinuationPreviewPendingError, ContinuationRefusedError, type CreditCapCode, CreditCapExceededError, ForbiddenError, type HeldFinalRun, InsufficientCreditsError, JobAbortedError, JobBlockedError, JobFailedError, JobHeldError, JobTimeoutError, NodaroError, NotFoundError, RateLimitedError, StorageExceededError, StudioOpError, StudioPreviewAppliedError, StudioPreviewUnavailable, UnauthorizedError, type WorkflowConflictCode, WorkflowConflictError, throwFromResponse };

package/dist/entries/errors.js

@@ -1,4 +1,4 @@
 import '../chunk-CJFIOVBA.js';
-export { AlreadyRunningError, AppRunVersionChangedError, ContinuationPreviewPendingError, ContinuationRefusedError, ForbiddenError, InsufficientCreditsError, JobAbortedError, JobBlockedError, JobFailedError, JobHeldError, JobTimeoutError, NodaroError, NotFoundError, RateLimitedError, StorageExceededError, StudioOpError, StudioPreviewAppliedError, StudioPreviewUnavailable, UnauthorizedError, WorkflowConflictError, throwFromResponse } from '../chunk-JGS6YBDW.js';
+export { AlreadyRunningError, AppRunVersionChangedError, CREDIT_CAP_CODES, ContinuationPreviewPendingError, ContinuationRefusedError, CreditCapExceededError, ForbiddenError, InsufficientCreditsError, JobAbortedError, JobBlockedError, JobFailedError, JobHeldError, JobTimeoutError, NodaroError, NotFoundError, RateLimitedError, StorageExceededError, StudioOpError, StudioPreviewAppliedError, StudioPreviewUnavailable, UnauthorizedError, WorkflowConflictError, throwFromResponse } from '../chunk-L6T44A3G.js';
 //# sourceMappingURL=errors.js.map
 //# sourceMappingURL=errors.js.map

package/dist/entries/jobs.cjs

@@ -1,13 +1,13 @@
 'use strict';
 
 require('../chunk-EHRWTYGR.cjs');
-var chunk3QBH2VE2_cjs = require('../chunk-3QBH2VE2.cjs');
+var chunkA7QSOD2S_cjs = require('../chunk-A7QSOD2S.cjs');
 
 
 
 Object.defineProperty(exports, "JobsResource", {
   enumerable: true,
-  get: function () { return chunk3QBH2VE2_cjs.JobsResource; }
+  get: function () { return chunkA7QSOD2S_cjs.JobsResource; }
 });
 //# sourceMappingURL=jobs.cjs.map
 //# sourceMappingURL=jobs.cjs.map

package/dist/entries/jobs.d.cts

@@ -31,6 +31,11 @@ type SafetyBlockHint = {
     class: "copyright" | "likeness" | "safety";
     retried: boolean;
     suggestedProvider?: string;
+    /**
+     * Present when the provider refused the INPUT VIDEO itself — not the prompt,
+     * a reference image or the output. Sending a different clip is the fix.
+     */
+    subject?: "input_video";
 };
 /**
  * A NODARO-side verdict, not a provider's: a job policy registered by the
@@ -50,10 +55,36 @@ type PolicyBlockHint = {
     reason: string;
     hookPoint: "request" | "result";
 };
+/**
+ * The job ran out of credits partway: a step that reserves its own credits
+ * (for example, the video a Cast Swap or trend run dispatches) was refused —
+ * the balance could not cover it, or a plan or workspace cap was reached. The
+ * job failed and its credits were refunded; ask the person to top up (or raise
+ * the cap), then run it again.
+ *
+ * `code` is the refusal's own code, a lowercase snake_case token — for
+ * example `insufficient_credits`, `free_video_limit`, `instance_cap_reached`,
+ * `budget_exceeded`, `member_cap_exceeded` or `user_allowance_exceeded`. Treat
+ * an unknown code like `insufficient_credits`.
+ */
+type CreditsHint = {
+    kind: "credits";
+    code: string;
+};
+/**
+ * The provider refused the job's input video without naming a content-policy
+ * class (its message is about the file, not a policy). Treat it like any
+ * other failure — no fallback model is offered — except that the input to
+ * change is known: send a different clip.
+ */
+type InputRefusedHint = {
+    kind: "input-refused";
+    subject: "input_video";
+};
 /**
  * A job's `jobs.error_hint` (migration 376) — a user-safe, machine-readable
  * failure verdict, so a caller can act on it without parsing `error_message`
- * prose. One column, two verdict sources; `kind` is the discriminant.
+ * prose. One column, several verdict sources; `kind` is the discriminant.
  *
  * HAND-COPIED MIRROR of `ErrorHint` in the platform's
  * `backend/src/lib/safety-block.ts` (which names this file in its own
@@ -61,7 +92,7 @@ type PolicyBlockHint = {
  * pasted here verbatim in the same change, with a changeset.
  * `packages/client/dist/index.d.ts` is REBUILT, never hand-edited.
  */
-type JobErrorHint = SafetyBlockHint | PolicyBlockHint;
+type JobErrorHint = SafetyBlockHint | PolicyBlockHint | CreditsHint | InputRefusedHint;
 /**
  * The billing lifecycle of a job's credit reservation — `usage_logs.status`
  * for the job's `usage_log_id`. `null` when the job has no usage log (e.g. a
@@ -145,6 +176,12 @@ interface Job {
 interface CancelJobResult {
     success: true;
     cancelled: number;
+    /**
+     * `true` when the job could not be stopped because its provider call is
+     * already running — a metered LLM job's call, an external provider task. It
+     * finishes and is charged only what it used.
+     */
+    inFlight?: boolean;
 }
 interface DeleteJobResult {
     success: true;
@@ -175,6 +212,24 @@ interface RateJobResult {
         rating: JobRating | null;
     };
 }
+/**
+ * {@link JobsResource.fromUpload}'s body: an image edited in the browser,
+ * already stored with `client.uploads.upload`, and what it was made from.
+ */
+interface JobFromUploadParams {
+    /** The edited image's `assetId`, as `client.uploads.upload` returned it. */
+    assetId: string;
+    /** The job whose image was edited. */
+    sourceJobId?: string;
+    /** Which of `sourceJobId`'s images was edited, when it made several. Default: its `imageUrl`. */
+    sourceImageUrl?: string;
+    /** The upload that was edited, when the source is not a job. Not with `sourceJobId`. */
+    sourceAssetId?: string;
+    /** The editor's design state, stored with `client.uploads.uploadJson`, so the edit can be reopened. */
+    editStateUrl?: string;
+    /** The generation session to file the job in. */
+    sessionId?: string;
+}
 interface ListJobsPage {
     /**
      * A page may hold fewer than `limit` rows — even none — and still carry a
@@ -219,6 +274,18 @@ declare class JobsResource {
      * carries `favorited` and `rating`.
      */
     list(params?: ListJobsParams): Promise<ListJobsPage>;
+    /**
+     * Record an image edited in the browser as a job (`POST /v1/jobs/from-upload`):
+     * a completed, private, free `image-edit` job whose `output_data.imageUrl` is
+     * the upload, linked to its source in `input_data` (`sourceJobId` /
+     * `sourceAssetId`, `sourceImageUrl`). It then lists, rates, favorites and
+     * files into a session like any image job. One upload is one job: the same
+     * `assetId` again returns the same job. OAuth apps need the `assets:write`
+     * scope. A deployment's job policy can refuse the image ({@link JobBlockedError}).
+     */
+    fromUpload(params: JobFromUploadParams): Promise<{
+        data: Job;
+    }>;
     /**
      * Rate one of your jobs `"good"` or `"bad"`, or clear the rating with
      * `null` (`PUT /v1/jobs/:id/rating`). Only the job's owner rates it — anyone
@@ -237,7 +304,12 @@ declare class JobsResource {
     }>;
     /**
      * Cancel a job. Server route is `POST /v1/jobs/:jobId/cancel`.
-     * Refunds any reserved credit holds.
+     * Refunds any reserved credit holds. A running LLM job priced per model
+     * (metered) whose call has already started answers
+     * `{ success: true, cancelled: 0, inFlight: true }`: it finishes and is
+     * charged only what it used. A job stopped before its call starts is
+     * refunded, except for what an earlier attempt of the same job already used
+     * (a retry after a billed attempt): that is charged.
      */
     cancel(id: string): Promise<CancelJobResult>;
     /**
@@ -249,4 +321,4 @@ declare class JobsResource {
     delete(id: string): Promise<DeleteJobResult>;
 }
 
-export { type CancelJobResult, type CreditStatus, type DeleteJobResult, type Job, type JobErrorHint, type JobRating, type JobRatingFilter, type JobStatus, type JobStatusResult, JobsResource, type ListJobsPage, type ListJobsParams, type PolicyBlockHint, type RateJobResult, type SafetyBlockHint };
+export { type CancelJobResult, type CreditStatus, type CreditsHint, type DeleteJobResult, type InputRefusedHint, type Job, type JobErrorHint, type JobFromUploadParams, type JobRating, type JobRatingFilter, type JobStatus, type JobStatusResult, JobsResource, type ListJobsPage, type ListJobsParams, type PolicyBlockHint, type RateJobResult, type SafetyBlockHint };

package/dist/entries/jobs.d.ts

@@ -31,6 +31,11 @@ type SafetyBlockHint = {
     class: "copyright" | "likeness" | "safety";
     retried: boolean;
     suggestedProvider?: string;
+    /**
+     * Present when the provider refused the INPUT VIDEO itself — not the prompt,
+     * a reference image or the output. Sending a different clip is the fix.
+     */
+    subject?: "input_video";
 };
 /**
  * A NODARO-side verdict, not a provider's: a job policy registered by the
@@ -50,10 +55,36 @@ type PolicyBlockHint = {
     reason: string;
     hookPoint: "request" | "result";
 };
+/**
+ * The job ran out of credits partway: a step that reserves its own credits
+ * (for example, the video a Cast Swap or trend run dispatches) was refused —
+ * the balance could not cover it, or a plan or workspace cap was reached. The
+ * job failed and its credits were refunded; ask the person to top up (or raise
+ * the cap), then run it again.
+ *
+ * `code` is the refusal's own code, a lowercase snake_case token — for
+ * example `insufficient_credits`, `free_video_limit`, `instance_cap_reached`,
+ * `budget_exceeded`, `member_cap_exceeded` or `user_allowance_exceeded`. Treat
+ * an unknown code like `insufficient_credits`.
+ */
+type CreditsHint = {
+    kind: "credits";
+    code: string;
+};
+/**
+ * The provider refused the job's input video without naming a content-policy
+ * class (its message is about the file, not a policy). Treat it like any
+ * other failure — no fallback model is offered — except that the input to
+ * change is known: send a different clip.
+ */
+type InputRefusedHint = {
+    kind: "input-refused";
+    subject: "input_video";
+};
 /**
  * A job's `jobs.error_hint` (migration 376) — a user-safe, machine-readable
  * failure verdict, so a caller can act on it without parsing `error_message`
- * prose. One column, two verdict sources; `kind` is the discriminant.
+ * prose. One column, several verdict sources; `kind` is the discriminant.
  *
  * HAND-COPIED MIRROR of `ErrorHint` in the platform's
  * `backend/src/lib/safety-block.ts` (which names this file in its own
@@ -61,7 +92,7 @@ type PolicyBlockHint = {
  * pasted here verbatim in the same change, with a changeset.
  * `packages/client/dist/index.d.ts` is REBUILT, never hand-edited.
  */
-type JobErrorHint = SafetyBlockHint | PolicyBlockHint;
+type JobErrorHint = SafetyBlockHint | PolicyBlockHint | CreditsHint | InputRefusedHint;
 /**
  * The billing lifecycle of a job's credit reservation — `usage_logs.status`
  * for the job's `usage_log_id`. `null` when the job has no usage log (e.g. a
@@ -145,6 +176,12 @@ interface Job {
 interface CancelJobResult {
     success: true;
     cancelled: number;
+    /**
+     * `true` when the job could not be stopped because its provider call is
+     * already running — a metered LLM job's call, an external provider task. It
+     * finishes and is charged only what it used.
+     */
+    inFlight?: boolean;
 }
 interface DeleteJobResult {
     success: true;
@@ -175,6 +212,24 @@ interface RateJobResult {
         rating: JobRating | null;
     };
 }
+/**
+ * {@link JobsResource.fromUpload}'s body: an image edited in the browser,
+ * already stored with `client.uploads.upload`, and what it was made from.
+ */
+interface JobFromUploadParams {
+    /** The edited image's `assetId`, as `client.uploads.upload` returned it. */
+    assetId: string;
+    /** The job whose image was edited. */
+    sourceJobId?: string;
+    /** Which of `sourceJobId`'s images was edited, when it made several. Default: its `imageUrl`. */
+    sourceImageUrl?: string;
+    /** The upload that was edited, when the source is not a job. Not with `sourceJobId`. */
+    sourceAssetId?: string;
+    /** The editor's design state, stored with `client.uploads.uploadJson`, so the edit can be reopened. */
+    editStateUrl?: string;
+    /** The generation session to file the job in. */
+    sessionId?: string;
+}
 interface ListJobsPage {
     /**
      * A page may hold fewer than `limit` rows — even none — and still carry a
@@ -219,6 +274,18 @@ declare class JobsResource {
      * carries `favorited` and `rating`.
      */
     list(params?: ListJobsParams): Promise<ListJobsPage>;
+    /**
+     * Record an image edited in the browser as a job (`POST /v1/jobs/from-upload`):
+     * a completed, private, free `image-edit` job whose `output_data.imageUrl` is
+     * the upload, linked to its source in `input_data` (`sourceJobId` /
+     * `sourceAssetId`, `sourceImageUrl`). It then lists, rates, favorites and
+     * files into a session like any image job. One upload is one job: the same
+     * `assetId` again returns the same job. OAuth apps need the `assets:write`
+     * scope. A deployment's job policy can refuse the image ({@link JobBlockedError}).
+     */
+    fromUpload(params: JobFromUploadParams): Promise<{
+        data: Job;
+    }>;
     /**
      * Rate one of your jobs `"good"` or `"bad"`, or clear the rating with
      * `null` (`PUT /v1/jobs/:id/rating`). Only the job's owner rates it — anyone
@@ -237,7 +304,12 @@ declare class JobsResource {
     }>;
     /**
      * Cancel a job. Server route is `POST /v1/jobs/:jobId/cancel`.
-     * Refunds any reserved credit holds.
+     * Refunds any reserved credit holds. A running LLM job priced per model
+     * (metered) whose call has already started answers
+     * `{ success: true, cancelled: 0, inFlight: true }`: it finishes and is
+     * charged only what it used. A job stopped before its call starts is
+     * refunded, except for what an earlier attempt of the same job already used
+     * (a retry after a billed attempt): that is charged.
      */
     cancel(id: string): Promise<CancelJobResult>;
     /**
@@ -249,4 +321,4 @@ declare class JobsResource {
     delete(id: string): Promise<DeleteJobResult>;
 }
 
-export { type CancelJobResult, type CreditStatus, type DeleteJobResult, type Job, type JobErrorHint, type JobRating, type JobRatingFilter, type JobStatus, type JobStatusResult, JobsResource, type ListJobsPage, type ListJobsParams, type PolicyBlockHint, type RateJobResult, type SafetyBlockHint };
+export { type CancelJobResult, type CreditStatus, type CreditsHint, type DeleteJobResult, type InputRefusedHint, type Job, type JobErrorHint, type JobFromUploadParams, type JobRating, type JobRatingFilter, type JobStatus, type JobStatusResult, JobsResource, type ListJobsPage, type ListJobsParams, type PolicyBlockHint, type RateJobResult, type SafetyBlockHint };

package/dist/entries/jobs.js

@@ -1,4 +1,4 @@
 import '../chunk-I3TYBAOX.js';
-export { JobsResource } from '../chunk-E5BM4BLO.js';
+export { JobsResource } from '../chunk-7IWVDWSP.js';
 //# sourceMappingURL=jobs.js.map
 //# sourceMappingURL=jobs.js.map

package/dist/entries/locations.d.cts

@@ -1,7 +1,7 @@
 import { LocationAssetType, CharacterAspectRatio, LocationAttachColumn, SurroundDirection } from '@nodaro/shared/entities';
 export { LOCATION_ASSET_TYPES, LOCATION_ATTACH_COLUMNS, LocationAssetType, LocationAttachColumn, SURROUND_DIRECTIONS, SurroundDirection } from '@nodaro/shared/entities';
 import { N as NodaroClientCore } from '../developer-apps-zSQXWmEG.cjs';
-import { l as GenerationSessionParams } from '../nodes-CTujw6Qd.cjs';
+import { l as GenerationSessionParams } from '../nodes-BDUk5Aej.cjs';
 import '@nodaro/shared/apps';
 import '@nodaro/shared/organizations';
 import '@nodaro/shared/types';
@@ -14,7 +14,7 @@ import '@nodaro/shared/scene3d';
 import '@nodaro/shared/credits';
 import './jobs.cjs';
 import './errors.cjs';
-import '../studio-productions-DUHvdSvk.cjs';
+import '../studio-productions-r2-VZsKj.cjs';
 import '@nodaro/shared/model-catalog';
 import '@nodaro/prompts/prompt-builder';
 

package/dist/entries/locations.d.ts

@@ -1,7 +1,7 @@
 import { LocationAssetType, CharacterAspectRatio, LocationAttachColumn, SurroundDirection } from '@nodaro/shared/entities';
 export { LOCATION_ASSET_TYPES, LOCATION_ATTACH_COLUMNS, LocationAssetType, LocationAttachColumn, SURROUND_DIRECTIONS, SurroundDirection } from '@nodaro/shared/entities';
 import { N as NodaroClientCore } from '../developer-apps-zSQXWmEG.js';
-import { l as GenerationSessionParams } from '../nodes-D2tbtzt7.js';
+import { l as GenerationSessionParams } from '../nodes-9WpYNWtS.js';
 import '@nodaro/shared/apps';
 import '@nodaro/shared/organizations';
 import '@nodaro/shared/types';
@@ -14,7 +14,7 @@ import '@nodaro/shared/scene3d';
 import '@nodaro/shared/credits';
 import './jobs.js';
 import './errors.js';
-import '../studio-productions-vbCNSbtf.js';
+import '../studio-productions-DtTE8mdl.js';
 import '@nodaro/shared/model-catalog';
 import '@nodaro/prompts/prompt-builder';
 

package/dist/entries/media.cjs

@@ -1,15 +1,15 @@
 'use strict';
 
 require('../chunk-RHETJOUM.cjs');
-var chunkOXQKE5EG_cjs = require('../chunk-OXQKE5EG.cjs');
-require('../chunk-KNMW722T.cjs');
-require('../chunk-N6GLZOE4.cjs');
+var chunkETX3TLNB_cjs = require('../chunk-ETX3TLNB.cjs');
+require('../chunk-FRQJNGJS.cjs');
+require('../chunk-FM2KM5TY.cjs');
 
 
 
 Object.defineProperty(exports, "MediaResource", {
   enumerable: true,
-  get: function () { return chunkOXQKE5EG_cjs.MediaResource; }
+  get: function () { return chunkETX3TLNB_cjs.MediaResource; }
 });
 //# sourceMappingURL=media.cjs.map
 //# sourceMappingURL=media.cjs.map

package/dist/entries/media.d.cts

@@ -431,8 +431,32 @@ declare class MediaResource {
      * to 5 minutes at 30 fps (a faster clip counts
      * proportionally longer), priced by the clip's length. Poll
      * `jobs.get(jobId)`: the output carries `videoUrl` (the mask), `width`,
-     * `height`, `frames` and `coverage` (the fraction of pixels selected). Feed
-     * the mask to {@link MediaResource.maskComposite}.
+     * `height`, `frames`, `coverage` (the fraction of pixels selected, rounded
+     * to 4 decimals) and `kept` (any region left on any frame: false only when
+     * the size / zone filters left an empty mask — read it rather than
+     * `coverage`, which a few pixels round to 0). Feed the mask to
+     * {@link MediaResource.maskComposite}.
+     *
+     * `holdLastMask: true` keeps the last mask on frames where the subject is
+     * lost (a mask covering under 0.002 % of the frame, e.g. a face behind a
+     * hand): each such frame after the first detection repeats the most recent
+     * non-empty one; the output then also carries `heldFrames`.
+     * `minSubjectHeightPct` (0–100, default 0 = off) drops every connected
+     * region whose bounding box is shorter than that % of the frame height
+     * (extras' small faces behind the main subject); it runs before
+     * `holdLastMask`, and the output then carries `droppedRegions`.
+     * `maxSubjectHeightPct` (0–100, default 0 = off) is its mirror: it drops
+     * regions TALLER than that % (keep only the small background faces). With
+     * both set a region is kept when min ≤ height ≤ max; min > max is a 400.
+     * `zone` (`{ leftPct, rightPct, topPct, bottomPct }`, each 0–49 % of the
+     * frame, a margin left out = 0; default null = off) keeps only the regions
+     * whose bounding-box centre lies inside the frame minus those margins (after
+     * the size cuts, before `holdLastMask`). `perShot: true` finds the clip's
+     * scene cuts first and segments each shot on its own: the subject is
+     * detected again after every cut, `holdLastMask` never crosses a cut, and
+     * each shot's mask is fitted to that shot's exact frame count; on a clip
+     * with no cut it gives the same mask, fitted to the clip's exact frame
+     * count. The output carries `shots` (1 when off).
      */
     videoMask(input: VideoMaskRequest): Promise<{
         jobId: string;
@@ -443,9 +467,19 @@ declare class MediaResource {
      * The result follows the foreground's size, frame rate and length; the
      * background is fitted (`backgroundFit`, default cover) and loops when
      * shorter; the mask holds its last frame when shorter. Optional
-     * `invertMask`, `feather` (0–20 px), `grow` (−10–10 px) and `audioSource`
-     * (foreground / background / mix / none). Priced per started 5 seconds of
-     * the result (foreground up to 300 s). Poll `jobs.get(jobId)` for `videoUrl`.
+     * `invertMask`, `feather` (0–20 px), `grow` (−10–10 px), `opacity` (0–1,
+     * default 1: how strongly the foreground covers the background inside the
+     * mask) and `audioSource` (foreground / background / mix / none). Priced per started 5 seconds of
+     * the result (the video it follows up to 300 s). Poll `jobs.get(jobId)` for `videoUrl`.
+     *
+     * `fill` picks what fills the masked area: `video` (default — the
+     * foreground, required then), `pixelate` (the background itself in
+     * blocks of `pixelSizePct` % of the frame width, 0.2–10, default 1.25) or
+     * `blur` (the background blurred, sigma `blurStrengthPct` % of the frame
+     * width, 0.1–5, default 2). Pixelate and blur take no
+     * `foregroundUrl` (one sent is ignored): the result follows the background
+     * and is priced on its length, and it always carries the background's sound
+     * (`audioSource` is ignored).
      */
     maskComposite(input: MaskCompositeRequest): Promise<{
         jobId: string;

package/dist/entries/media.d.ts

@@ -431,8 +431,32 @@ declare class MediaResource {
      * to 5 minutes at 30 fps (a faster clip counts
      * proportionally longer), priced by the clip's length. Poll
      * `jobs.get(jobId)`: the output carries `videoUrl` (the mask), `width`,
-     * `height`, `frames` and `coverage` (the fraction of pixels selected). Feed
-     * the mask to {@link MediaResource.maskComposite}.
+     * `height`, `frames`, `coverage` (the fraction of pixels selected, rounded
+     * to 4 decimals) and `kept` (any region left on any frame: false only when
+     * the size / zone filters left an empty mask — read it rather than
+     * `coverage`, which a few pixels round to 0). Feed the mask to
+     * {@link MediaResource.maskComposite}.
+     *
+     * `holdLastMask: true` keeps the last mask on frames where the subject is
+     * lost (a mask covering under 0.002 % of the frame, e.g. a face behind a
+     * hand): each such frame after the first detection repeats the most recent
+     * non-empty one; the output then also carries `heldFrames`.
+     * `minSubjectHeightPct` (0–100, default 0 = off) drops every connected
+     * region whose bounding box is shorter than that % of the frame height
+     * (extras' small faces behind the main subject); it runs before
+     * `holdLastMask`, and the output then carries `droppedRegions`.
+     * `maxSubjectHeightPct` (0–100, default 0 = off) is its mirror: it drops
+     * regions TALLER than that % (keep only the small background faces). With
+     * both set a region is kept when min ≤ height ≤ max; min > max is a 400.
+     * `zone` (`{ leftPct, rightPct, topPct, bottomPct }`, each 0–49 % of the
+     * frame, a margin left out = 0; default null = off) keeps only the regions
+     * whose bounding-box centre lies inside the frame minus those margins (after
+     * the size cuts, before `holdLastMask`). `perShot: true` finds the clip's
+     * scene cuts first and segments each shot on its own: the subject is
+     * detected again after every cut, `holdLastMask` never crosses a cut, and
+     * each shot's mask is fitted to that shot's exact frame count; on a clip
+     * with no cut it gives the same mask, fitted to the clip's exact frame
+     * count. The output carries `shots` (1 when off).
      */
     videoMask(input: VideoMaskRequest): Promise<{
         jobId: string;
@@ -443,9 +467,19 @@ declare class MediaResource {
      * The result follows the foreground's size, frame rate and length; the
      * background is fitted (`backgroundFit`, default cover) and loops when
      * shorter; the mask holds its last frame when shorter. Optional
-     * `invertMask`, `feather` (0–20 px), `grow` (−10–10 px) and `audioSource`
-     * (foreground / background / mix / none). Priced per started 5 seconds of
-     * the result (foreground up to 300 s). Poll `jobs.get(jobId)` for `videoUrl`.
+     * `invertMask`, `feather` (0–20 px), `grow` (−10–10 px), `opacity` (0–1,
+     * default 1: how strongly the foreground covers the background inside the
+     * mask) and `audioSource` (foreground / background / mix / none). Priced per started 5 seconds of
+     * the result (the video it follows up to 300 s). Poll `jobs.get(jobId)` for `videoUrl`.
+     *
+     * `fill` picks what fills the masked area: `video` (default — the
+     * foreground, required then), `pixelate` (the background itself in
+     * blocks of `pixelSizePct` % of the frame width, 0.2–10, default 1.25) or
+     * `blur` (the background blurred, sigma `blurStrengthPct` % of the frame
+     * width, 0.1–5, default 2). Pixelate and blur take no
+     * `foregroundUrl` (one sent is ignored): the result follows the background
+     * and is priced on its length, and it always carries the background's sound
+     * (`audioSource` is ignored).
      */
     maskComposite(input: MaskCompositeRequest): Promise<{
         jobId: string;

package/dist/entries/media.js

@@ -1,6 +1,6 @@
 import '../chunk-ES2E65HT.js';
-export { MediaResource } from '../chunk-4NLVBYMW.js';
-import '../chunk-JMOKD6ZP.js';
-import '../chunk-JGS6YBDW.js';
+export { MediaResource } from '../chunk-DQAYIVVS.js';
+import '../chunk-7CUWAVWB.js';
+import '../chunk-L6T44A3G.js';
 //# sourceMappingURL=media.js.map
 //# sourceMappingURL=media.js.map

package/dist/entries/nodes.cjs

@@ -1,8 +1,8 @@
 'use strict';
 
 var chunk7CK6I4CT_cjs = require('../chunk-7CK6I4CT.cjs');
-var chunkEAGD6NEE_cjs = require('../chunk-EAGD6NEE.cjs');
-require('../chunk-N6GLZOE4.cjs');
+var chunkQZHRXPN5_cjs = require('../chunk-QZHRXPN5.cjs');
+require('../chunk-FM2KM5TY.cjs');
 
 
 
@@ -16,7 +16,7 @@ Object.defineProperty(exports, "PROMPT_SUFFIX_KEY", {
 });
 Object.defineProperty(exports, "NodesResource", {
   enumerable: true,
-  get: function () { return chunkEAGD6NEE_cjs.NodesResource; }
+  get: function () { return chunkQZHRXPN5_cjs.NodesResource; }
 });
 //# sourceMappingURL=nodes.cjs.map
 //# sourceMappingURL=nodes.cjs.map

package/dist/entries/nodes.d.cts

@@ -4,7 +4,7 @@ export { GeminiOmniVoicePresetId, ImageAspectRatio, ImageEditProvider, ImageEdit
 export { PROMPT_PREFIX_KEY, PROMPT_SUFFIX_KEY, PromptAffixFields } from '@nodaro/shared/nodes';
 export { SocialPlatform, SocialPost, SocialPostAuthor, SocialPostMedia, SocialPostMetrics, SocialSearchCount, SocialSearchMode, SocialSearchParams, SocialSearchPeriod, SocialSearchSort, SocialSearchVideoKind } from '@nodaro/shared/social';
 export { GenerateMaskOutput, GenerateMaskRequest, VideoDepthColormap, VideoDepthModelSize, VideoDepthProvider, VideoDepthResolution } from '@nodaro/shared/media';
-export { A as AssembleNarratedVideoParams, B as BatchJobOutcome, E as EditImageCommonParams, a as EditImageFromTaskParams, b as EditImageFromUrlParams, c as EditImageParams, G as GenerateImageBatchGroup, e as GenerateImageBatchOutput, f as GenerateImageBatchResult, g as GenerateImageParams, h as GenerateMaskJobOutput, i as GenerateMaskParams, k as GenerateVideoParams, l as GenerationSessionParams, I as ImageJobStarted, m as ImageToImageParams, J as JobOutputImage, N as NodeCategory, n as NodeCreditRate, o as NodeDescriptor, p as NodeInputField, q as NodeInputSchema, r as NodeJobOutput, s as NodeQuote, t as NodesResource, O as OutputType, Q as QuoteAdjustment, y as QuoteWarning, R as ReferenceCaptionParams, F as RunAndWaitOptions, H as RunManyResult, K as RunNodeAdjustment, L as RunNodeOptions, M as RunNodeResult, S as RunNodeWarning, _ as SocialSearchJobOutput, $ as SplitImageParams, a0 as SplitImageResult, a1 as SplitImageTile, a2 as StructuredReferenceParams, a3 as Subject, a4 as TextToSpeechParams, a5 as TextToVideoParams, a6 as VideoDepthParams, a7 as VideoToVideoParams, a8 as VideoUpscaleParams } from '../nodes-CTujw6Qd.cjs';
+export { A as AssembleNarratedVideoParams, B as BatchJobOutcome, E as EditImageCommonParams, a as EditImageFromTaskParams, b as EditImageFromUrlParams, c as EditImageParams, G as GenerateImageBatchGroup, e as GenerateImageBatchOutput, f as GenerateImageBatchResult, g as GenerateImageParams, h as GenerateMaskJobOutput, i as GenerateMaskParams, k as GenerateVideoParams, l as GenerationSessionParams, I as ImageJobStarted, m as ImageToImageParams, J as JobOutputImage, N as NodeCategory, n as NodeCreditRate, o as NodeDescriptor, p as NodeInputField, q as NodeInputSchema, r as NodeJobOutput, s as NodeQuote, t as NodesResource, O as OutputType, Q as QuoteAdjustment, y as QuoteWarning, R as ReferenceCaptionParams, F as RunAndWaitOptions, H as RunManyResult, K as RunNodeAdjustment, L as RunNodeOptions, M as RunNodeResult, S as RunNodeWarning, _ as SocialSearchJobOutput, $ as SplitImageParams, a0 as SplitImageResult, a1 as SplitImageTile, a2 as StructuredReferenceParams, a3 as Subject, a4 as TextToSpeechParams, a5 as TextToVideoParams, a6 as VideoDepthParams, a7 as VideoToVideoParams, a8 as VideoUpscaleParams } from '../nodes-BDUk5Aej.cjs';
 export { TopazUpscaleFactor } from '@nodaro/shared/credits';
 export { ImageToImageAttachColumn } from '@nodaro/shared/entities';
 import '@nodaro/shared/scene3d';
@@ -13,6 +13,6 @@ import '@nodaro/shared/apps';
 import '@nodaro/shared/organizations';
 import './jobs.cjs';
 import './errors.cjs';
-import '../studio-productions-DUHvdSvk.cjs';
+import '../studio-productions-r2-VZsKj.cjs';
 import '@nodaro/shared/model-catalog';
 import '@nodaro/prompts/prompt-builder';

package/dist/entries/nodes.d.ts

@@ -4,7 +4,7 @@ export { GeminiOmniVoicePresetId, ImageAspectRatio, ImageEditProvider, ImageEdit
 export { PROMPT_PREFIX_KEY, PROMPT_SUFFIX_KEY, PromptAffixFields } from '@nodaro/shared/nodes';
 export { SocialPlatform, SocialPost, SocialPostAuthor, SocialPostMedia, SocialPostMetrics, SocialSearchCount, SocialSearchMode, SocialSearchParams, SocialSearchPeriod, SocialSearchSort, SocialSearchVideoKind } from '@nodaro/shared/social';
 export { GenerateMaskOutput, GenerateMaskRequest, VideoDepthColormap, VideoDepthModelSize, VideoDepthProvider, VideoDepthResolution } from '@nodaro/shared/media';
-export { A as AssembleNarratedVideoParams, B as BatchJobOutcome, E as EditImageCommonParams, a as EditImageFromTaskParams, b as EditImageFromUrlParams, c as EditImageParams, G as GenerateImageBatchGroup, e as GenerateImageBatchOutput, f as GenerateImageBatchResult, g as GenerateImageParams, h as GenerateMaskJobOutput, i as GenerateMaskParams, k as GenerateVideoParams, l as GenerationSessionParams, I as ImageJobStarted, m as ImageToImageParams, J as JobOutputImage, N as NodeCategory, n as NodeCreditRate, o as NodeDescriptor, p as NodeInputField, q as NodeInputSchema, r as NodeJobOutput, s as NodeQuote, t as NodesResource, O as OutputType, Q as QuoteAdjustment, y as QuoteWarning, R as ReferenceCaptionParams, F as RunAndWaitOptions, H as RunManyResult, K as RunNodeAdjustment, L as RunNodeOptions, M as RunNodeResult, S as RunNodeWarning, _ as SocialSearchJobOutput, $ as SplitImageParams, a0 as SplitImageResult, a1 as SplitImageTile, a2 as StructuredReferenceParams, a3 as Subject, a4 as TextToSpeechParams, a5 as TextToVideoParams, a6 as VideoDepthParams, a7 as VideoToVideoParams, a8 as VideoUpscaleParams } from '../nodes-D2tbtzt7.js';
+export { A as AssembleNarratedVideoParams, B as BatchJobOutcome, E as EditImageCommonParams, a as EditImageFromTaskParams, b as EditImageFromUrlParams, c as EditImageParams, G as GenerateImageBatchGroup, e as GenerateImageBatchOutput, f as GenerateImageBatchResult, g as GenerateImageParams, h as GenerateMaskJobOutput, i as GenerateMaskParams, k as GenerateVideoParams, l as GenerationSessionParams, I as ImageJobStarted, m as ImageToImageParams, J as JobOutputImage, N as NodeCategory, n as NodeCreditRate, o as NodeDescriptor, p as NodeInputField, q as NodeInputSchema, r as NodeJobOutput, s as NodeQuote, t as NodesResource, O as OutputType, Q as QuoteAdjustment, y as QuoteWarning, R as ReferenceCaptionParams, F as RunAndWaitOptions, H as RunManyResult, K as RunNodeAdjustment, L as RunNodeOptions, M as RunNodeResult, S as RunNodeWarning, _ as SocialSearchJobOutput, $ as SplitImageParams, a0 as SplitImageResult, a1 as SplitImageTile, a2 as StructuredReferenceParams, a3 as Subject, a4 as TextToSpeechParams, a5 as TextToVideoParams, a6 as VideoDepthParams, a7 as VideoToVideoParams, a8 as VideoUpscaleParams } from '../nodes-9WpYNWtS.js';
 export { TopazUpscaleFactor } from '@nodaro/shared/credits';
 export { ImageToImageAttachColumn } from '@nodaro/shared/entities';
 import '@nodaro/shared/scene3d';
@@ -13,6 +13,6 @@ import '@nodaro/shared/apps';
 import '@nodaro/shared/organizations';
 import './jobs.js';
 import './errors.js';
-import '../studio-productions-vbCNSbtf.js';
+import '../studio-productions-DtTE8mdl.js';
 import '@nodaro/shared/model-catalog';
 import '@nodaro/prompts/prompt-builder';

package/dist/entries/nodes.js

@@ -1,5 +1,5 @@
 export { PROMPT_PREFIX_KEY, PROMPT_SUFFIX_KEY } from '../chunk-ZYPH2FPT.js';
-export { NodesResource } from '../chunk-4JKI6JRC.js';
-import '../chunk-JGS6YBDW.js';
+export { NodesResource } from '../chunk-ZDSC6KBT.js';
+import '../chunk-L6T44A3G.js';
 //# sourceMappingURL=nodes.js.map
 //# sourceMappingURL=nodes.js.map