@clipwright/core 0.34.0 → 0.35.0

package/CHANGELOG.md

@@ -18,6 +18,113 @@ listed under.
 
 ## [Unreleased]
 
+## [0.35.0] - 2026-10-30
+
+### Changed
+
+- The texts an agent reads describe the `parts-v1` tariff (#933). The `call` field says the call adds production
+  seconds and that a live-avatar still has its own price; the templates description and the remake plan's tariff
+  note drop the retired per-second rate. The MCP server's SKILL.md and the CLI README point to `list_prices` and the
+  quotes instead of fixed faceless prices, and the `quote_ugc` example shows `price_lines` for 12 s.
+- *Dashboard:* /pricing lists only the presenter a request can get, and prints single images and clips as price
+  ranges per resolution without model names (#800). Two comparison pages are rewritten from the other products'
+  sites as read on 2026-10-30.
+
+- *Server-side:* `make_ugc` is priced by its parts, one tariff `parts-v1` for short and long videos (#800): 12 credits
+  for every second a presenter take fills on HeyGen (22 on OmniHuman), plus 1 for every second of the finished video,
+  plus 400 for each live-avatar still of a call, at least 50 for a delivered video. A plain 35 s video costs 455
+  instead of 1 050. The quote itemizes it in `price_lines` and names `minimum_credits`; the terms are frozen at
+  admission, so a run admitted before keeps its own.
+- *Server-side:* `analyze_reference` costs 70 credits (#927): held at the start and charged once the analysis
+  succeeds; a failed analysis costs nothing, and starting it again on the same asset answers the same analysis for
+  free. The analysis carries `credits_reserved`, `credits_charged` and `balance_after_credits`.
+- *Server-side:* single generations are priced at ×2.5 of their cheapest route instead of ×2: an image from 6 credits,
+  a clip from 6 credits a second. `seedance-2.0-mini` is rendered by one route only.
+- *Server-side:* `make_faceless` is priced by its parts, tariff `faceless-parts-v1` (#800): 7 credits for each picture
+  we generate, the opening clip's still included, 49 for the opening clip and 1 for every second of the delivered
+  video, at least 50. Your own pictures are not charged. The quote is the most a selection is charged: 212 at 30 s,
+  356 at 90 s, instead of 350 and 420. `faceless_billing` names `images` and `imageCredits`; a run admitted before
+  keeps its tariff.
+- *Server-side:* edits and personal actors are repriced at ×2.5 of their cost (#800): a revision's new picture 7, clip
+  49, clip with a new picture 56, render 13, and a shot candidate the same unit prices; an actor's portrait 4 and each
+  other format 8 at `medium`, 12 and 18 at `high`. Runs admitted before keep their snapshot.
+
+### Added
+
+- *Server-side:* `POST /v1/reference-analyses/quote`, the `quote_analysis` tool and `ClipwrightClient.quoteAnalysis()`
+  price an analysis before it starts (#927).
+- *Server-side:* every settled run carries `balance_after_credits`, the account's balance read in the transaction
+  that settled it (#927).
+
+- *Server-side:* `GET /v1/public/prices` lists the price of every action in credits, without a key: one entry per tool
+  and variant, its price as lines of credits per unit plus a minimum, or a formula; free tools are listed at 0. No price
+  changed (#927).
+- The `list_prices` tool and `ClipwrightClient.listPrices()` read that list, and the description of every paid tool
+  ends with its price line, built from the same list.
+- `@clipwright/core` exports `PRICE_LIST`, `priceLine` and `pricesResponse`, with the constants the list reads:
+  `CREDITS_PER_SECOND`, `ACTOR_UNIT_CREDITS`, `EDIT_UNIT_PRICES`, `EDIT_RENDER_PRICE`, `EDIT_ZERO_UNIT_PRICE` and the
+  numbers of the faceless tariff.
+
+- *Server-side:* `GET /openapi.json` serves an OpenAPI 3.1 description of the REST API without a key: every public
+  route with its request and response schemas, the error envelope and `warnings[]`. The API's own tests check
+  their real responses against it.
+- `@clipwright/core/openapi` exports `buildOpenApiDocument()` and the route marking `OPENAPI_ROUTES`;
+  `@clipwright/core` exports `ENDPOINT_NOTES`, `healthResponse` and `publicSkillsResponse`.
+- `make_ugc` takes `voice_pace` (0.7–1.2): `eleven_flash_v2_5` and `eleven_turbo_v2_5` get it as their speed,
+  `gemini-3.8-flash-tts` as a "speaking rapidly" or "speaking slowly" style with a warning. `eleven_v4` has no speed
+  setting: it gets no speed, and a `voice_pace` other than 1 is named in `warnings[]` (#890).
+- `list_voices` gives each English voice on `eleven_v4` its measured pace, `words_per_second`. On that model the voice
+  sets the pace, so pick the voice nearest a reference presenter's pace (#890).
+- *Server-side:* all ElevenLabs speech goes to `eleven_v4`, now the model of every preset, catalog voice and raw
+  `voice_id`. `tts_model: "eleven_v3"` is still accepted: the run speaks `eleven_v4` and `warnings[]` says so.
+  `eleven_v4` gives no pause for a `<break>` tag, so the tag is cut with a warning on the default path too.
+- `make_ugc` takes `pause_trim`, targets in seconds per gap class: after synthesis a pause longer than its target is cut
+  down to it inside silence only, with a crossfade, and word timings move with the audio. A joint that would click is
+  kept and named in `warnings[]`.
+- *Server-side:* a reference analysis measures the presenter's voice from the words it already transcribes: pace,
+  pauses in three layers, hinge pauses, pitch and loudness range, in the profile's new `voice` section.
+  `plan_reference_remake` sets `voice_pace` from it on a model with a speed. On `eleven_v4` it sets none and, when
+  the voice is more than 5% off the presenter, names the measured voices nearer the presenter's pace (#890).
+- `@clipwright/core` exports `referenceVoice`, the schema of that section, and `narrationPaceFromVoice`.
+
+- *Dashboard:* a public `/captions` page plays every caption style on the same presenter and the same words, each
+  with the description `tools/list` gives it; the `caption_style` description links to the page.
+- `SKILL.md` names every caption style and tells the agent to ask whether the user wants captions, to offer three
+  or four fitting styles with the gallery link, and to take the style closest to a reference video's captions.
+- *Server-side:* `hormozi` now matches the canonical look: Montserrat Black uppercase, white with a thick black outline,
+  one yellow (`#FFD93D`) keyword per cue, up to three words. The previous look (condensed Oswald, orange keyword, no
+  outline) is the new style `accent`. `hormozi` stays the default; there are 24 styles.
+- *Server-side:* `make_ugc` takes `edit_sounds: true` on a run with `inserts` or `layout_windows`: a low sound plays on
+  every cut, to or from an insert, at a full-frame template's cut in or out and at a layout window's in and out, with
+  its peak on the cut. `template_sounds.edit` picks it from `swell_hit` (default), `whoosh_deep`, `whoosh_low`,
+  `boom_low`, `sub_drop`, `riser_boom` and `riser_hit`. A cut that already plays a template's whoosh or flash gets no
+  second sound. Without the field a run plays no edit sounds, as before; `edit_sounds` with nothing to cut, with
+  `template_sounds: false`, or `template_sounds.edit` without `edit_sounds`, is refused 400 by its path before any
+  hold. The price does not change.
+- *Server-side:* new template sounds: a `pop` (`plop`) when a `tag` or a `callout` pops in, a `hangup` (`phone`) just
+  before an answered `phone_call` leaves, and `money` (`cash_register`, `coins`) when a `stat` with a currency sign in
+  its prefix or suffix counts up. `answer` adds `pickup`, `whoosh` adds `slide_quick` and `flash` adds `swish`.
+  `list_template_sounds` lists them. A run frozen before them keeps its sounds.
+- *Server-side:* `make_ugc` takes `framing`, presenter sizes on their words: `close` (1.18 times larger about the face)
+  or `medium`, each a hard cut that settles over 8 frames, or with `transition: "flash"` a warm light leak over the cut.
+  It needs long-form qualification, works without captions, refuses overlap with inserts, layout windows and other framing,
+  and names in `warnings[]` a framing wholly under full-frame templates. With `edit_sounds`, each framing cut plays the
+  edit sound. `plan_reference_remake` turns a `punch_in` camera into a close framing and a flash into a speaking beat
+  into a flashed one.
+- `create_actor` takes `from_actor_id` with `framing: "wide"`, `holding` (one or two objects, each with words, an
+  optional image asset of the object and a hand) or `setting`: it derives a new personal actor from a library actor or
+  your own, with the same face checked against the source. A face that does not match costs nothing. The price is the
+  usual per-image units. *Server-side:* the fields are open only where `CLIPWRIGHT_ACTOR_VIEWS` is on; elsewhere they
+  are refused 400 `rejected_field`. A wide derived actor's 9:16 is listed with `framing: "wide"`, and `make_ugc`
+  renders it as a wide view. `@clipwright/core` exports `storedActorSource`, `storedHoldingItem`,
+  `createActorDispositions`, `createActorRejectedFields` and `isActorViewsEnabled`.
+
+### Changed
+
+- *Server-side:* the template sound library is re-recorded from CC0 sounds the owner chose by ear: 25 of the 31 files
+  play a new recording under the same name; the rings, `glitch`, `switch_heavy` and `paper_swipe` stay as they were.
+  Every source is named in `THIRD_PARTY_NOTICES`.
+
 ## [0.34.0] - 2026-10-24
 
 ### Added

package/README.md

@@ -17,7 +17,9 @@ edit: `runShots`, `runEdit` and `saveRunEdit` are what the API emits and takes;
 that a name a later API adds does not break it.
 
 The `./idempotency` subpath export is separate because it pulls in a Node
-built-in and would otherwise break bundlers targeting the browser.
+built-in and would otherwise break bundlers targeting the browser. So is
+`./openapi`: `buildOpenApiDocument()` builds the OpenAPI 3.1 document the API
+serves at `GET /openapi.json` from the route registry and these schemas.
 
 ## Changelog
 

package/dist/account-actors.d.ts

@@ -1,10 +1,10 @@
 import { z } from "zod";
-import { type ActorQuality } from "./actor-qualities.js";
+import { type ActorQuality, type ActorQualityAccepted } from "./actor-qualities.js";
 import { type AspectRatio } from "./skills.js";
 /** Personal actors of an account. */
 export { ACTOR_DEFAULT_QUALITY, ACTOR_QUALITIES_ACCEPTED, ACTOR_QUALITIES_KNOWN } from "./actor-qualities.js";
 export type { ActorQuality, ActorQualityAccepted } from "./actor-qualities.js";
-export { ACTOR_AGE_FLOOR, ACTOR_ASPECTS_KNOWN, ACTOR_DESCRIPTION_MAX_CHARS, ACTOR_GENDERS_ACCEPTED, ACTOR_GENDERS_KNOWN, ACTOR_MAX_AGE, ACTOR_MIN_AGE, ACTOR_NAME_MAX_CHARS, } from "./actor-bounds.js";
+export { ACTOR_AGE_FLOOR, ACTOR_ASPECTS_KNOWN, ACTOR_DESCRIPTION_MAX_CHARS, ACTOR_GENDERS_ACCEPTED, ACTOR_GENDERS_KNOWN, ACTOR_HOLDING_DESCRIPTION_MAX_CHARS, ACTOR_HOLDING_MAX_ITEMS, ACTOR_MAX_AGE, ACTOR_MIN_AGE, ACTOR_NAME_MAX_CHARS, ACTOR_SETTING_MAX_CHARS, } from "./actor-bounds.js";
 export type { ActorAspectKnown, ActorGender } from "./actor-bounds.js";
 export declare const PERSONAL_ACTOR_ID_PREFIX = "actor_u_";
 /** `actor_u_` plus 26 base32 characters (RFC 4648, lowercase): 128 random bits. */
@@ -32,36 +32,70 @@ export declare const ACTOR_SIZE_SET: {
         readonly height: 1024;
     };
 };
+export declare const ACTOR_VIEW_FRAMINGS: readonly ["wide"];
+export declare const ACTOR_HANDS: readonly ["left", "right"];
+/** The fields of a view derived from an actor (#898). */
+export declare const ACTOR_VIEW_FIELDS: readonly ["from_actor_id", "framing", "holding", "setting"];
 type AcceptedQualities = readonly [ActorQuality, ...ActorQuality[]];
 /** The input for a given set of accepted qualities. */
 export declare function createActorInputWith<const Q extends AcceptedQualities>(accepted: Q, defaultQuality: Q[number]): z.ZodObject<{
-    description: z.ZodString;
-    gender: z.ZodEnum<{
+    description: z.ZodOptional<z.ZodString>;
+    gender: z.ZodOptional<z.ZodEnum<{
         female: "female";
         male: "male";
-    }>;
-    approximate_age: z.ZodNumber;
+    }>>;
+    approximate_age: z.ZodOptional<z.ZodNumber>;
     name: z.ZodString;
     aspect_ratios: z.ZodDefault<z.ZodArray<z.ZodEnum<{
         "16:9": "16:9";
         "1:1": "1:1";
         "9:16": "9:16";
     }>>>;
+    from_actor_id: z.ZodOptional<z.ZodString>;
+    framing: z.ZodOptional<z.ZodEnum<{
+        wide: "wide";
+    }>>;
+    holding: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        description: z.ZodString;
+        reference: z.ZodOptional<z.ZodObject<{
+            asset_id: z.ZodString;
+        }, z.core.$strict>>;
+        hand: z.ZodOptional<z.ZodEnum<{
+            left: "left";
+            right: "right";
+        }>>;
+    }, z.core.$strict>>>;
+    setting: z.ZodOptional<z.ZodString>;
     quality: z.ZodDefault<z.ZodEnum<{ [k in Q[number]]: k; } extends infer T ? { [k in keyof T]: T[k]; } : never>>;
 }, z.core.$strict>;
 export declare const createActorInput: z.ZodObject<{
-    description: z.ZodString;
-    gender: z.ZodEnum<{
+    description: z.ZodOptional<z.ZodString>;
+    gender: z.ZodOptional<z.ZodEnum<{
         female: "female";
         male: "male";
-    }>;
-    approximate_age: z.ZodNumber;
+    }>>;
+    approximate_age: z.ZodOptional<z.ZodNumber>;
     name: z.ZodString;
     aspect_ratios: z.ZodDefault<z.ZodArray<z.ZodEnum<{
         "16:9": "16:9";
         "1:1": "1:1";
         "9:16": "9:16";
     }>>>;
+    from_actor_id: z.ZodOptional<z.ZodString>;
+    framing: z.ZodOptional<z.ZodEnum<{
+        wide: "wide";
+    }>>;
+    holding: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        description: z.ZodString;
+        reference: z.ZodOptional<z.ZodObject<{
+            asset_id: z.ZodString;
+        }, z.core.$strict>>;
+        hand: z.ZodOptional<z.ZodEnum<{
+            left: "left";
+            right: "right";
+        }>>;
+    }, z.core.$strict>>>;
+    setting: z.ZodOptional<z.ZodString>;
     quality: z.ZodDefault<z.ZodEnum<{
         high: "high";
         medium: "medium";
@@ -73,18 +107,33 @@ export type CreateActorInput = z.infer<typeof createActorInput>;
 export type CreateActorInputArgs = z.input<typeof createActorInput>;
 /** Flat shape for MCP: the tool publishes the same schema the server checks. */
 export declare const createActorInputShape: {
-    description: z.ZodString;
-    gender: z.ZodEnum<{
+    description: z.ZodOptional<z.ZodString>;
+    gender: z.ZodOptional<z.ZodEnum<{
         female: "female";
         male: "male";
-    }>;
-    approximate_age: z.ZodNumber;
+    }>>;
+    approximate_age: z.ZodOptional<z.ZodNumber>;
     name: z.ZodString;
     aspect_ratios: z.ZodDefault<z.ZodArray<z.ZodEnum<{
         "16:9": "16:9";
         "1:1": "1:1";
         "9:16": "9:16";
     }>>>;
+    from_actor_id: z.ZodOptional<z.ZodString>;
+    framing: z.ZodOptional<z.ZodEnum<{
+        wide: "wide";
+    }>>;
+    holding: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        description: z.ZodString;
+        reference: z.ZodOptional<z.ZodObject<{
+            asset_id: z.ZodString;
+        }, z.core.$strict>>;
+        hand: z.ZodOptional<z.ZodEnum<{
+            left: "left";
+            right: "right";
+        }>>;
+    }, z.core.$strict>>>;
+    setting: z.ZodOptional<z.ZodString>;
     quality: z.ZodDefault<z.ZodEnum<{
         high: "high";
         medium: "medium";
@@ -94,6 +143,10 @@ export declare const actorUnitCredits: z.ZodObject<{
     portrait: z.ZodNumber;
     variant: z.ZodNumber;
 }, z.core.$strip>;
+/** Unit prices of a personal actor (owner's decision, clipwright#120). Admission copies them into the */
+/** run's snapshot and settlement reads the snapshot, so a change here leaves old runs alone. ×2.5 over the S0 costs (owner, 29.10, */
+/** #800): a portrait is a generate call ($0.0103 medium, $0.039 high), another format an edit ($0.024, $0.0581). */
+export declare const ACTOR_UNIT_CREDITS: Readonly<Record<ActorQualityAccepted, z.infer<typeof actorUnitCredits>>>;
 /** Unit prices and requested formats fixed at admission; settlement uses these, not the price table. */
 export declare const actorPricingSnapshot: z.ZodObject<{
     quality: z.ZodEnum<{
@@ -127,6 +180,43 @@ export declare const admittedActorPricingSnapshot: z.ZodObject<{
         "9:16": "9:16";
     }>>;
 }, z.core.$strip>;
+/** The source image admission resolved for `from_actor_id`: the worker reads these bytes, not a payload. */
+export declare const storedActorSource: z.ZodObject<{
+    actor_id: z.ZodString;
+    scope: z.ZodEnum<{
+        account: "account";
+        clipwright: "clipwright";
+    }>;
+    key: z.ZodString;
+    sha256: z.ZodString;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    framing: z.ZodEnum<{
+        close: "close";
+        wide: "wide";
+    }>;
+}, z.core.$strip>;
+export type StoredActorSource = z.infer<typeof storedActorSource>;
+/** A held object as admitted: a `reference` carries the asset row admission found. */
+export declare const storedHoldingItem: z.ZodObject<{
+    description: z.ZodString;
+    hand: z.ZodOptional<z.ZodEnum<{
+        left: "left";
+        right: "right";
+    }>>;
+    reference: z.ZodOptional<z.ZodObject<{
+        asset_id: z.ZodString;
+    }, z.core.$strip>>;
+    picture: z.ZodOptional<z.ZodObject<{
+        asset_id: z.ZodString;
+        key: z.ZodString;
+        mime: z.ZodEnum<{
+            "image/jpeg": "image/jpeg";
+            "image/png": "image/png";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type StoredHoldingItem = z.infer<typeof storedHoldingItem>;
 /** A stored run input. Quality and formats must match the snapshot, or generation would diverge */
 /** from the charge, so such a run does not read (`run_input_unreadable`, zero credits). */
 export declare const storedCreateActorInput: z.ZodObject<{
@@ -161,6 +251,44 @@ export declare const storedCreateActorInput: z.ZodObject<{
             "9:16": "9:16";
         }>>;
     }, z.core.$strip>;
+    from_actor_id: z.ZodOptional<z.ZodString>;
+    source_actor: z.ZodOptional<z.ZodObject<{
+        actor_id: z.ZodString;
+        scope: z.ZodEnum<{
+            account: "account";
+            clipwright: "clipwright";
+        }>;
+        key: z.ZodString;
+        sha256: z.ZodString;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        framing: z.ZodEnum<{
+            close: "close";
+            wide: "wide";
+        }>;
+    }, z.core.$strip>>;
+    framing: z.ZodOptional<z.ZodEnum<{
+        wide: "wide";
+    }>>;
+    holding: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        description: z.ZodString;
+        hand: z.ZodOptional<z.ZodEnum<{
+            left: "left";
+            right: "right";
+        }>>;
+        reference: z.ZodOptional<z.ZodObject<{
+            asset_id: z.ZodString;
+        }, z.core.$strip>>;
+        picture: z.ZodOptional<z.ZodObject<{
+            asset_id: z.ZodString;
+            key: z.ZodString;
+            mime: z.ZodEnum<{
+                "image/jpeg": "image/jpeg";
+                "image/png": "image/png";
+            }>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    setting: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type StoredCreateActorInput = z.infer<typeof storedCreateActorInput>;
 export declare const createActorQuote: z.ZodObject<{
@@ -235,7 +363,11 @@ export type CreateActorDisposition = {
     kind: "warned";
     warning: string;
     triggersWhen: "present";
+} | {
+    kind: "rejected";
+    message: string;
 };
+type CreateActorField = keyof typeof createActorInput.shape;
 export declare const CREATE_ACTOR_FIELD_DISPOSITIONS: {
     readonly description: {
         readonly kind: "implemented";
@@ -261,7 +393,31 @@ export declare const CREATE_ACTOR_FIELD_DISPOSITIONS: {
         readonly kind: "implemented";
         readonly provenBy: "egress";
     };
+    readonly from_actor_id: {
+        readonly kind: "implemented";
+        readonly provenBy: "egress";
+    };
+    readonly framing: {
+        readonly kind: "implemented";
+        readonly provenBy: "egress";
+    };
+    readonly holding: {
+        readonly kind: "implemented";
+        readonly provenBy: "egress";
+    };
+    readonly setting: {
+        readonly kind: "implemented";
+        readonly provenBy: "egress";
+    };
 };
+export declare const ACTOR_VIEWS_DISABLED_MESSAGE = "is switched off on this deployment: deriving an actor from an actor is not available; create an actor from a description instead";
+/** The registry with `CLIPWRIGHT_ACTOR_VIEWS` applied: switched off, the view fields are refused, not ignored. */
+export declare function createActorDispositions(viewsEnabled: boolean): Record<CreateActorField, CreateActorDisposition>;
+/** Present fields whose disposition is `rejected`, in registry order, for `rejectedFieldBody`. */
+export declare function createActorRejectedFields(input: Readonly<Record<string, unknown>>, dispositions: Readonly<Record<string, CreateActorDisposition>>): {
+    field: string;
+    message: string;
+}[];
 /** Admission warnings come only from the registry; written to `runs.warnings`, not recomputed on read. */
 export declare function createActorAdmissionWarnings(input: Readonly<Record<string, unknown>>, dispositions?: Readonly<Record<string, CreateActorDisposition>>): string[];
 /** `create_actor` run failure codes, each charging zero credits. The `error` column reads `code: text`. */
@@ -275,6 +431,9 @@ export declare const CREATE_ACTOR_RUN_ERRORS: {
     readonly actor_generation_disabled: "actor generation is disabled right now; no actor was created and nothing was charged";
     readonly actor_run_interrupted: "the run stopped before it finished; no actor was created and nothing was charged";
     readonly actor_spend_refused: "our spend guard refused the paid call; no actor was created and nothing was charged. Retry later";
+    readonly actor_identity_not_kept: "the edited portrait did not keep the source actor's face; no actor was created and nothing was charged";
+    readonly actor_source_unreadable: "the source actor or a held object's picture could not be read; no actor was created and nothing was charged";
+    readonly actor_views_disabled: "deriving an actor from an actor is disabled right now; no actor was created and nothing was charged";
 };
 export type CreateActorRunErrorCode = keyof typeof CREATE_ACTOR_RUN_ERRORS;
 export declare const CREATE_ACTOR_RUN_ERROR_CODES: CreateActorRunErrorCode[];

package/dist/account-actors.js

@@ -1,10 +1,11 @@
 import { z } from "zod";
 import { ACTOR_DEFAULT_QUALITY, ACTOR_QUALITIES_ACCEPTED, ACTOR_QUALITIES_KNOWN, } from "./actor-qualities.js";
-import { ACTOR_AGE_FLOOR, ACTOR_ASPECTS_KNOWN, ACTOR_DESCRIPTION_MAX_CHARS, ACTOR_GENDERS_ACCEPTED, ACTOR_GENDERS_KNOWN, ACTOR_MAX_AGE, ACTOR_MIN_AGE, ACTOR_NAME_MAX_CHARS, } from "./actor-bounds.js";
-import { ASPECT_RATIOS } from "./skills.js";
+import { ACTOR_AGE_FLOOR, ACTOR_ASPECTS_KNOWN, ACTOR_DESCRIPTION_MAX_CHARS, ACTOR_GENDERS_ACCEPTED, ACTOR_GENDERS_KNOWN, ACTOR_HOLDING_DESCRIPTION_MAX_CHARS, ACTOR_HOLDING_MAX_ITEMS, ACTOR_MAX_AGE, ACTOR_MIN_AGE, ACTOR_NAME_MAX_CHARS, ACTOR_SETTING_MAX_CHARS, } from "./actor-bounds.js";
+import { assetId } from "./asset-identity.js";
+import { actorId, ASPECT_RATIOS } from "./skills.js";
 /** Personal actors of an account. */
 export { ACTOR_DEFAULT_QUALITY, ACTOR_QUALITIES_ACCEPTED, ACTOR_QUALITIES_KNOWN } from "./actor-qualities.js";
-export { ACTOR_AGE_FLOOR, ACTOR_ASPECTS_KNOWN, ACTOR_DESCRIPTION_MAX_CHARS, ACTOR_GENDERS_ACCEPTED, ACTOR_GENDERS_KNOWN, ACTOR_MAX_AGE, ACTOR_MIN_AGE, ACTOR_NAME_MAX_CHARS, } from "./actor-bounds.js";
+export { ACTOR_AGE_FLOOR, ACTOR_ASPECTS_KNOWN, ACTOR_DESCRIPTION_MAX_CHARS, ACTOR_GENDERS_ACCEPTED, ACTOR_GENDERS_KNOWN, ACTOR_HOLDING_DESCRIPTION_MAX_CHARS, ACTOR_HOLDING_MAX_ITEMS, ACTOR_MAX_AGE, ACTOR_MIN_AGE, ACTOR_NAME_MAX_CHARS, ACTOR_SETTING_MAX_CHARS, } from "./actor-bounds.js";
 export const PERSONAL_ACTOR_ID_PREFIX = "actor_u_";
 const PERSONAL_ACTOR_ID_BYTES = 16;
 const BASE32_ALPHABET = "abcdefghijklmnopqrstuvwxyz234567";
@@ -46,23 +47,39 @@ export const ACTOR_SIZE_SET = {
 };
 const includesPortrait = (ratios) => ratios.includes(ACTOR_PORTRAIT_ASPECT);
 const hasNoRepeats = (ratios) => new Set(ratios).size === ratios.length;
+export const ACTOR_VIEW_FRAMINGS = ["wide"];
+export const ACTOR_HANDS = ["left", "right"];
+/** One held object: words, and optionally a picture of the object itself. */
+const holdingItem = z.strictObject({
+    description: z.string().min(1).max(ACTOR_HOLDING_DESCRIPTION_MAX_CHARS).describe("The object, e.g. \"a white coffee mug\"."),
+    reference: z
+        .strictObject({ asset_id: assetId })
+        .optional()
+        .describe("A PNG or JPEG picture of the object: an image asset of this account (upload, URL import or a found picture, rights_confirmed)."),
+    hand: z.enum(ACTOR_HANDS).optional().describe("left | right; omitted lets the edit choose."),
+});
 /** Strict input fields without quality. Bounds come from actor-bounds.ts; read schemas do not use them. */
+/** Words, gender and age are required without `from_actor_id` and refused with it (`checkActorSource`). */
 const actorFieldShape = {
     description: z
         .string()
         .min(1)
         .max(ACTOR_DESCRIPTION_MAX_CHARS)
+        .optional()
         .describe("Words describing a fictional adult: appearance, clothing, setting. Naming a real person or a likeness " +
-        "to one is refused before any charge (actor_prompt_refused)."),
+        "to one is refused before any charge (actor_prompt_refused). Required unless from_actor_id is given."),
     gender: z
         .enum(ACTOR_GENDERS_ACCEPTED)
-        .describe(`${ACTOR_GENDERS_ACCEPTED.join(" | ")}. Fixes the actor's gender and the default voice of videos with this actor.`),
+        .optional()
+        .describe(`${ACTOR_GENDERS_ACCEPTED.join(" | ")}. Fixes the actor's gender and the default voice of videos with this actor. ` +
+        "Required unless from_actor_id is given."),
     approximate_age: z
         .number()
         .int()
         .min(ACTOR_MIN_AGE)
         .max(ACTOR_MAX_AGE)
-        .describe(`Approximate age in years, ${ACTOR_MIN_AGE} to ${ACTOR_MAX_AGE}: actors are adults.`),
+        .optional()
+        .describe(`Approximate age in years, ${ACTOR_MIN_AGE} to ${ACTOR_MAX_AGE}: actors are adults. Required unless from_actor_id is given.`),
     name: z.string().min(1).max(ACTOR_NAME_MAX_CHARS).describe("Name shown in list_actors."),
     aspect_ratios: z
         .array(z.enum(ASPECT_RATIOS))
@@ -75,12 +92,65 @@ const actorFieldShape = {
         .default([...ASPECT_RATIOS])
         .describe(`Formats to create: ${ASPECT_RATIOS.join(" | ")}, always including ${ACTOR_PORTRAIT_ASPECT}. Omitted means all ` +
         "three. Formats that fail the identity check are not charged and are named in warnings."),
+    from_actor_id: actorId
+        .optional()
+        .describe("Derive a new personal actor from this one (a library actor or your own): the same face, gender and age, " +
+        "with the view changed by framing, holding or setting. Omit description, gender and approximate_age."),
+    framing: z
+        .enum(ACTOR_VIEW_FRAMINGS)
+        .optional()
+        .describe("wide: the camera further back, the head lower with room above; make_ugc then renders it as a wide view."),
+    holding: z
+        .array(holdingItem)
+        .min(1)
+        .max(ACTOR_HOLDING_MAX_ITEMS)
+        .optional()
+        .describe(`Up to ${ACTOR_HOLDING_MAX_ITEMS} objects the presenter holds, one per hand.`),
+    setting: z
+        .string()
+        .min(1)
+        .max(ACTOR_SETTING_MAX_CHARS)
+        .optional()
+        .describe("The room or background to put the presenter in, in words."),
 };
+/** The fields of a view derived from an actor (#898). */
+export const ACTOR_VIEW_FIELDS = ["from_actor_id", "framing", "holding", "setting"];
+const ACTOR_VIEW_CHANGES = ["framing", "holding", "setting"];
+const ACTOR_SOURCE_FIELDS = ["description", "gender", "approximate_age"];
+/** A described actor needs its words, a derived one takes them from the source: neither is silently dropped (rule 3). */
+function checkActorSource(input, ctx) {
+    const refuse = (field, message) => ctx.addIssue({ code: z.ZodIssueCode.custom, path: [field], message });
+    if (input.from_actor_id === undefined) {
+        for (const field of ACTOR_SOURCE_FIELDS) {
+            if (input[field] === undefined) {
+                refuse(field, `${field} is required: describe a fictional adult, or pass from_actor_id to derive a view of an existing actor`);
+            }
+        }
+        for (const field of ACTOR_VIEW_CHANGES) {
+            if (input[field] !== undefined) {
+                refuse(field, `${field} needs from_actor_id: create the actor first, then derive a view of it with from_actor_id`);
+            }
+        }
+        return;
+    }
+    for (const field of ACTOR_SOURCE_FIELDS) {
+        if (input[field] !== undefined)
+            refuse(field, `${field} comes from the source actor with from_actor_id; omit it`);
+    }
+    if (ACTOR_VIEW_CHANGES.every((field) => input[field] === undefined)) {
+        refuse("from_actor_id", "from_actor_id needs a change: framing, holding or setting");
+    }
+    const hands = (input.holding ?? []).flatMap((item) => (item.hand === undefined ? [] : [item.hand]));
+    if (new Set(hands).size !== hands.length)
+        refuse("holding", "holding names the same hand twice: one object per hand");
+}
 function unknownFieldsRefusal(keys) {
     if (keys.includes("image")) {
-        return "create_actor takes no image or other reference: describe a fictional adult in description";
+        return "create_actor takes no image of a person: describe a fictional adult in description, or derive a view of " +
+            "an existing actor with from_actor_id; a held object's picture goes in holding[].reference";
     }
-    return `unknown field(s) ${keys.join(", ")}: create_actor accepts description, gender, approximate_age, name, quality, aspect_ratios`;
+    return `unknown field(s) ${keys.join(", ")}: create_actor accepts description, gender, approximate_age, name, quality, ` +
+        "aspect_ratios, from_actor_id, framing, holding, setting";
 }
 /** The input for a given set of accepted qualities. */
 export function createActorInputWith(accepted, defaultQuality) {
@@ -95,7 +165,7 @@ export function createActorInputWith(accepted, defaultQuality) {
             "quote shows it before any charge."),
     }, {
         error: (issue) => (issue.code === "unrecognized_keys" ? unknownFieldsRefusal(issue.keys) : undefined),
-    });
+    }).superRefine(checkActorSource);
 }
 export const createActorInput = createActorInputWith(ACTOR_QUALITIES_ACCEPTED, ACTOR_DEFAULT_QUALITY);
 /** Flat shape for MCP: the tool publishes the same schema the server checks. */
@@ -104,6 +174,13 @@ export const actorUnitCredits = z.object({
     portrait: z.number().int().positive(),
     variant: z.number().int().positive(),
 });
+/** Unit prices of a personal actor (owner's decision, clipwright#120). Admission copies them into the */
+/** run's snapshot and settlement reads the snapshot, so a change here leaves old runs alone. ×2.5 over the S0 costs (owner, 29.10, */
+/** #800): a portrait is a generate call ($0.0103 medium, $0.039 high), another format an edit ($0.024, $0.0581). */
+export const ACTOR_UNIT_CREDITS = {
+    medium: { portrait: 4, variant: 8 },
+    high: { portrait: 12, variant: 18 },
+};
 /** Read schemas depend only on what could have been written: the known sets and the DB check. */
 /** Intake bounds stay out, so narrowing intake never breaks old runs. */
 const storedAspects = z.array(z.enum(ACTOR_ASPECTS_KNOWN)).min(1);
@@ -126,6 +203,24 @@ function sameFormats(left, right) {
     const b = new Set(right);
     return a.size === b.size && [...a].every((ratio) => b.has(ratio));
 }
+const sha256Hex = z.string().regex(/^[a-f0-9]{64}$/);
+/** The source image admission resolved for `from_actor_id`: the worker reads these bytes, not a payload. */
+export const storedActorSource = z.object({
+    actor_id: z.string().min(1),
+    scope: z.enum(ACTOR_SCOPES),
+    key: z.string().min(1),
+    sha256: sha256Hex,
+    width: z.number().int().positive(),
+    height: z.number().int().positive(),
+    framing: z.enum(["close", "wide"]),
+});
+/** A held object as admitted: a `reference` carries the asset row admission found. */
+export const storedHoldingItem = z.object({
+    description: z.string().min(1),
+    hand: z.enum(ACTOR_HANDS).optional(),
+    reference: z.object({ asset_id: z.string().min(1) }).optional(),
+    picture: z.object({ asset_id: z.string().min(1), key: z.string().min(1), mime: z.enum(["image/png", "image/jpeg"]) }).optional(),
+});
 /** A stored run input. Quality and formats must match the snapshot, or generation would diverge */
 /** from the charge, so such a run does not read (`run_input_unreadable`, zero credits). */
 export const storedCreateActorInput = z
@@ -137,6 +232,11 @@ export const storedCreateActorInput = z
     aspect_ratios: storedAspects,
     quality: z.enum(ACTOR_QUALITIES_KNOWN),
     pricing_snapshot: actorPricingSnapshot,
+    from_actor_id: z.string().min(1).optional(),
+    source_actor: storedActorSource.optional(),
+    framing: z.enum(ACTOR_VIEW_FRAMINGS).optional(),
+    holding: z.array(storedHoldingItem).optional(),
+    setting: z.string().min(1).optional(),
 })
     .refine((input) => input.quality === input.pricing_snapshot.quality, {
     error: "stored quality differs from pricing_snapshot.quality",
@@ -145,6 +245,16 @@ export const storedCreateActorInput = z
     .refine((input) => sameFormats(input.aspect_ratios, input.pricing_snapshot.requested_aspects), {
     error: "stored aspect_ratios differ from pricing_snapshot.requested_aspects",
     path: ["aspect_ratios"],
+})
+    .refine((input) => (input.from_actor_id === undefined) === (input.source_actor === undefined)
+    && (input.source_actor === undefined || input.source_actor.actor_id === input.from_actor_id), {
+    error: "stored from_actor_id and source_actor disagree",
+    path: ["source_actor"],
+})
+    .refine((input) => (input.holding ?? []).every((item) => (item.reference === undefined) === (item.picture === undefined)
+    && (item.picture === undefined || item.picture.asset_id === item.reference?.asset_id)), {
+    error: "a stored holding reference has no admitted picture",
+    path: ["holding"],
 });
 export const createActorQuote = z.object({
     skill: z.literal("create_actor"),
@@ -178,7 +288,23 @@ export const CREATE_ACTOR_FIELD_DISPOSITIONS = {
     name: { kind: "implemented", provenBy: "listing" },
     quality: { kind: "implemented", provenBy: "egress" },
     aspect_ratios: { kind: "implemented", provenBy: "egress" },
+    from_actor_id: { kind: "implemented", provenBy: "egress" },
+    framing: { kind: "implemented", provenBy: "egress" },
+    holding: { kind: "implemented", provenBy: "egress" },
+    setting: { kind: "implemented", provenBy: "egress" },
 };
+export const ACTOR_VIEWS_DISABLED_MESSAGE = "is switched off on this deployment: deriving an actor from an actor is not available; create an actor from a description instead";
+/** The registry with `CLIPWRIGHT_ACTOR_VIEWS` applied: switched off, the view fields are refused, not ignored. */
+export function createActorDispositions(viewsEnabled) {
+    if (viewsEnabled)
+        return CREATE_ACTOR_FIELD_DISPOSITIONS;
+    const rejected = (field) => ({ kind: "rejected", message: `${field} ${ACTOR_VIEWS_DISABLED_MESSAGE}` });
+    return { ...CREATE_ACTOR_FIELD_DISPOSITIONS, ...Object.fromEntries(ACTOR_VIEW_FIELDS.map((field) => [field, rejected(field)])) };
+}
+/** Present fields whose disposition is `rejected`, in registry order, for `rejectedFieldBody`. */
+export function createActorRejectedFields(input, dispositions) {
+    return Object.entries(dispositions).flatMap(([field, disposition]) => disposition.kind === "rejected" && input[field] !== undefined ? [{ field, message: disposition.message }] : []);
+}
 /** Admission warnings come only from the registry; written to `runs.warnings`, not recomputed on read. */
 export function createActorAdmissionWarnings(input, dispositions = CREATE_ACTOR_FIELD_DISPOSITIONS) {
     return Object.entries(dispositions).flatMap(([field, disposition]) => disposition.kind === "warned" && input[field] !== undefined ? [disposition.warning] : []);
@@ -195,6 +321,9 @@ export const CREATE_ACTOR_RUN_ERRORS = {
     actor_generation_disabled: "actor generation is disabled right now; no actor was created and nothing was charged",
     actor_run_interrupted: "the run stopped before it finished; no actor was created and nothing was charged",
     actor_spend_refused: "our spend guard refused the paid call; no actor was created and nothing was charged. Retry later",
+    actor_identity_not_kept: "the edited portrait did not keep the source actor's face; no actor was created and nothing was charged",
+    actor_source_unreadable: "the source actor or a held object's picture could not be read; no actor was created and nothing was charged",
+    actor_views_disabled: "deriving an actor from an actor is disabled right now; no actor was created and nothing was charged",
 };
 export const CREATE_ACTOR_RUN_ERROR_CODES = Object.keys(CREATE_ACTOR_RUN_ERRORS);
 export function createActorRunError(code) {
@@ -218,5 +347,8 @@ export const CREATE_ACTOR_DESCRIPTION = "Create a personal actor for this accoun
     "one face, plus the other requested formats edited from it. Returns a run_id immediately; poll get_run until " +
     "'succeeded' (created_actor.actor_id, then pass it as actor_id to make_ugc) or 'failed'. Each published image is " +
     "charged at the price quote shows; refused descriptions and unusable portraits cost nothing. When generation is " +
-    "switched off the call fails with actor_generation_disabled.";
+    "switched off the call fails with actor_generation_disabled. With from_actor_id it derives a new personal actor " +
+    "from a library or own actor: the same face (checked; a mismatch costs nothing), with framing wide, objects in " +
+    "holding or a new setting. A held object's picture is an image asset (upload, URL import or a found picture, " +
+    "rights_confirmed).";
 //# sourceMappingURL=account-actors.js.map