@clipwright/core 0.33.0 → 0.35.0

package/CHANGELOG.md

@@ -18,6 +18,257 @@ 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
+
+- `@clipwright/core` exports `PUBLIC_MCP_URL`, the hosted MCP server address `https://mcp.clipwright.io/mcp`.
+- *Dashboard:* a public `/mcp` page answers "Yes, Clipwright has an MCP server": the hosted address with the
+  `claude mcp add` command (sign in, no key), the local package with a key, and the tool list. `llms.txt` names the
+  hosted MCP address, the `/mcp` page and the CLI. The home page and `/pricing` carry schema.org data with the price
+  of the cheapest credit pack, and the sitemap dates the comparison pages by the day their facts were checked.
+
+- *Server-side:* video assets. An MP4 in h264 or hevc up to 120 seconds and 100 MB comes from an own `generate_video`
+  run, a public url (`{ url, kind: "video" }`), a presigned PUT (`{ put: { media_type, bytes, sha256 } }`, also for
+  pictures) or `POST /v1/assets/bytes` up to 32 MB. A url or a PUT answers `202` with `state: "processing"` or
+  `"awaiting_upload"`; the worker task `ingest-asset-media` measures frames, fps, codec and `pix_fmt` from the bytes
+  and publishes the asset, and `GET /v1/assets/{id}` says `ready` or `failed` with the reason. Clips are kept for
+  assembly and are no generation reference.
+- MCP: `create_asset` takes `put` and a url clip; on stdio a local MP4 `path` is uploaded through a PUT.
+- `generate_video` and `quote_video` take an optional `camera`: `static`, `push_in`, `pull_back` or `pan`. It
+  becomes the first line of the prompt the model gets and does not change the price.
+- `GET /v1/generations/models` lists `duration_values` for a model that takes only some lengths inside its
+  `duration_s` range; the schema and the quote refuse the others. The resolution `360p` is part of the contract.
+- New clip models: `kling-3.0` at 720p in 9:16 and 16:9, 3 to 15 seconds, and `gemini-omni-flash-1.1` at 720p in both
+  formats and 360p 16:9, for 4, 6, 8 or 10 seconds. `seedance-2.5` adds 480p 9:16 and 720p 16:9.
+- *Server-side:* a clip refused for a real face in its input picture, or turned away as rate-limited before it was
+  accepted, is made by a second provider at the same quote where that row was measured there. A clip is always
+  delivered without an audio track.
+- *Dashboard:* the Assets page. It lists the account's pictures and clips in a grid of small, medium or large tiles,
+  with filters by role and kind, a name search and the usage of the 2,000 assets and 20 GB. A selected asset opens on
+  the right: rename it, change its role, copy its `asset_id`, open the file or delete it. Pictures up to 10 MB and MP4
+  clips up to 32 MB upload from the page; a clip shows as processing until it is checked.
+- *Server-side:* each asset gets a preview of at most 512 pixels on the long side, made by the worker after the asset
+  is saved and caught up hourly. The Assets page shows the preview, never the original, in its grid. The API does not
+  return the preview yet.
+- *Server-side:* more clip formats. `seedance-2.0` adds 480p in 9:16 and 16:9 at 18 credits a second and 720p 16:9;
+  `seedance-2.0-fast` adds 480p in both formats and 720p 16:9; `seedance-2.0-mini` and `seedance-2.5` add 480p 16:9.
+  The 480p clip of `seedance-2.0`, `-mini` and `-fast` is 496×864 or 864×496, and `warnings[]` says so.
+- A `make_ugc` image insert can name `asset_id` instead of `media_url`, exactly one of the two. The quote and the run
+  accept only a ready PNG or JPEG asset of the same account, with a `media_type` that matches it. A foreign, deleted
+  or unfinished asset answers `400 reference_not_usable` before any credits are reserved. The worker reads the
+  file admission recorded and checks its sha256, so a later delete does not change a started run.
+- `get_run` in the MCP server returns `created_actor` on a succeeded `create_actor` run, so an agent sees the
+  `actor_id` to pass to `make_ugc`.
+- `make_ugc` takes `overlays`: pictures anchored to words like inserts, drawn over the presenter in a corner or as a
+  band across the top or bottom, entering with `cut`, `fade`, `slide` or `tilt_in`. At most two show at once, and two
+  on screen together need positions that share no corner. Captions move to the middle or the bottom of the frame when
+  an overlay meets them, never up over the face, and hide when neither place is free. An overlay steps aside while a full-frame insert is on screen, and one wholly under inserts is refused.
+- `make_ugc` takes `layout_windows`: `split` puts the presenter in the top half and the picture in the bottom half with
+  captions on the seam (9:16 only); `card` shows the picture in a centred card, and `blur_presenter` blurs the
+  presenter behind it. Windows may not overlap one another or an insert.
+- Inserts take `transition`: `cut`, `wipe`, `flash` or `zoom`. It plays inside the insert's own frames and never moves
+  its start or end. A `caption_emphasis` item takes `punch_in: true` to zoom into the presenter while the quote is
+  spoken.
+- *Server-side:* overlays and layout windows follow the insert rules: `script`, long-form qualification, 1080p and
+  `broll_policy=anyone`, exactly one of `media_url` and `asset_id`, and ids unique across inserts, overlays and
+  windows. A script with overlays or windows alone runs as long form. They change
+  neither the presenter's slots nor the price: a blurred or covered presenter is billed face time. A run whose
+  composition is off, skipped or failed names undrawn overlays, windows, transitions and punch-in in `warnings[]`.
+- `make_ugc` inserts, overlays and layout windows take `media_type: "video"`, by `media_url` or by the `asset_id` of an
+  MP4 asset. The clip plays muted from its first frame and is cut by time where its words end, so a variable frame
+  rate does not shift it. A clip shorter than its words holds its last frame, and `warnings[]` names the insert or
+  layer: in the quote for an `asset_id` the slow speech edge may outlast, otherwise on the run. H.264 and HEVC in 8 bits
+  without HDR are accepted.
+- *Server-side:* a 10-bit video asset answers `400 reference_not_usable` before any credits are reserved. A
+  `media_url` clip, and the colour transfer of an asset clip, are measured by the worker before the first paid call:
+  another codec, 10 bits or more, or a PQ or HLG transfer fails the run uncharged with `media_source_rejected` naming
+  the insert or layer. A video `segments` item is still refused. Customer video costs nothing: the same script with a
+  picture or a clip quotes and bills the same face seconds.
+- *Server-side:* graphic templates on `make_ugc`. `templates[]` takes up to 12 items
+  `{ id, kind, anchor, cover_words?, placement?, transition?, data }` of three kinds: `tag` (a gradient pill, also
+  over an insert), `lower_third` (a name and role bar) and `end_card` (a site pill with an optional call to action);
+  captions are hidden under the last two and under a tag without `position`, which sits in the caption spot. Each kind
+  takes `size` small, medium (the default) or large, and long text shrinks to fit. Templates are accepted on any
+  `script` run without `segments` and never change its tariff or price: a plain run is billed 30 credits a second of
+  finished video, and a run with inserts, overlays or layout windows is billed long-form-v1 (#840). Text over its
+  limit (a wide CJK character counts 2), emoji, letters the run's fonts cannot draw, overlapping footprints and the
+  other refusals answer 400 with a path before any hold. `@clipwright/core` exports the catalog (`TEMPLATE_KINDS`)
+  and `@clipwright/mcp-server` offers a slim template item with the catalog in its description.
+- *Server-side:* full-frame templates and template pictures. `title_card` (a hook card: a title in up to two lines on
+  a white card, an optional logo picture shown whole and a gradient chip) and `quote` (up to four lines, an author and
+  an optional round photo) fill the frame; `stat` counts a number up from zero, on a full frame or over the presenter.
+  A full-frame template hides captions, overlays and over-presenter templates while it shows, takes a `wipe`, `flash`
+  or `zoom` drawn over the live presenter, and on a long-form run the presenter under it is still billed as face time.
+  `logo` and `photo` take `{ asset_id }`: pinned at admission under the template id and slot, a video or another
+  account's asset is refused 400 `reference_not_usable` before any hold, and a photo cut to its circle is named in
+  `warnings[]`. On a plain run a template picture needs explicit `broll_policy=anyone`, like a layer (#840).
+- *Server-side:* templates on a plain script run (#840). A `script` run without inserts, overlays or layout windows
+  takes `templates`, `template_theme` and `template_sounds` at 30 credits a second, with no minimum and no face
+  seconds. The templates are drawn over its one take; if they cannot be drawn, the video is delivered at the same
+  price and `warnings[]` says `templates was not drawn: <reason>`.
+- Quotes carry `tariff`: `ugc-per-second-v1` on a plain run, or long form's `pricingVersion` (`long-form-v1`). The
+  field is an optional string, so older clients and stored quotes still parse; templates never change it.
+- *Server-side:* the `callout` template and template looks. `callout` draws an arrow or a ring onto a point given
+  as `target { x, y }` in percent of the frame, pulses twice and rests, with an optional label pill below the point,
+  or above it when there is no room or the face is below; the point may sit anywhere, the face rule covers the label.
+  A run-level `template_theme { preset?, accent? }` picks `clean_light` (the default when absent) or `bold_dark`, and
+  `accent` takes a `#RRGGBB` colour for the pills and accent text. A customer accent under 3:1 against the colours it
+  meets is refused 400 at `template_theme.accent` before any hold, never shifted. The look freezes into the timeline,
+  so a resumed run draws what it was admitted with, and footprints come from the frozen kind version.
+- *Server-side:* three interactive templates with inner quotes. `checklist` draws 2–4 rows of switches or check boxes
+  that a cursor clicks in turn; `phone_call` rings an incoming call on a neutral phone at the side and answers it; and
+  `compare` sweeps an after picture in over a before picture on a diagonal, full frame. An inner quote
+  (`clicks[].quote`, `answer_at`, `reveal_at`) names words inside the template's own: the click, answer or reveal lands
+  on their first word, and a click without one is spread evenly. A quote missing from the script, outside the item's
+  words, out of the script's order, or on words an insert or full-frame template covers is refused 400 by its path
+  before any hold. `compare` takes two pictures, pinned apart as `before` and `after`. Templates still change no price.
+- *Server-side:* three more templates and three more looks. `notification` drops a phone notification (an icon, the
+  app, a title and a body line) into the band above the face, holds it at least 1.2 s and takes it away before its
+  span ends; `progress` completes 2–5 steps in turn, each on its `advance_at` quote (exactly one per step) or spread
+  evenly; `rating` fills five stars in turn up to a score in halves. `advance_at` is refused like the other inner
+  quotes, and a list of the wrong length too. `template_theme.preset` adds `neon`, `paper` and `mono`, and a customer
+  accent is checked against each look's own colours.
+- *Server-side:* templates play sounds, well under the voice, from a library of 31 bundled with the composition: a
+  checklist click and its switch landing, a phone ringing until it is answered and the answer, a notification dropping
+  in, each progress step and rating star, a compare reveal, and a full-frame wipe, zoom or flash. A run plays the
+  defaults; `template_sounds: { beat: name }` swaps a beat's sound and `template_sounds: false` plays none. An unknown
+  beat or name, or `template_sounds` without templates, is refused 400 by its path before any hold. `GET
+  /v1/template-sounds` and the MCP tool `list_template_sounds` list each beat, its default and its names, free. A run
+  frozen before this plays none. Sounds change no price. `@clipwright/sdk` adds `listTemplateSounds()`.
+
+### Changed
+
+- *Server-side:* in `mono` the callout's ring and arrow have a white outline, so they read over a dark suit.
+- *Server-side:* a template beat spoken before its template has entered (a checklist click before its rows and cursor are
+  in, or an answer, step or reveal during the enter) moves to the first frame after the enter, the beats after it keep
+  6 frames apart, and `warnings[]` names each move. Runs already rendered keep their frames.
+- *Server-side:* captions and the light template look are blue, with no purple: the two-tier and pill captions and the
+  `punch` keyword use the reference's periwinkle-to-sky blue, `clean_light` follows it, `bold_dark` sits on a neutral
+  near-black ground, `checklist` switches are green when on and red when off in every look, and the `phone_call` screen
+  is the device's own teal-to-blue.
+- *Server-side:* a template no longer moves captions. While it meets their band it hides them, as the checklist and
+  the phone do; a small one elsewhere, such as a notification at the top, leaves them on screen.
+- *Server-side:* `generate_image` and `generate_video` cost less. A `seedream-5.0-flash` image costs 5 credits instead
+  of 12 and a `flare` image 6 instead of 18; a second of `seedance-2.0-mini` at 720p costs 10 instead of 50,
+  `seedance-2.0` at 1080p 91 instead of 250, `kling-3.0` 17 instead of 50 and `gemini-omni-flash-1.1` 19 instead of 55.
+  A run already admitted keeps its quoted price.
+- *Server-side:* a second of `seedance-2.5` at 480p costs 25 credits instead of 34.
+- *Server-side:* every delivered video is encoded once, at a quality setting chosen by eye on text frames, so a
+  35-second 1080×1920 video is about 11 MB instead of 27 MB. The resolution is unchanged (#845).
+
+### Fixed
+
+- *Server-side:* a dropped connection while the worker checks on an ordered `make_ugc` clip no longer fails the run
+  and charges for it. The worker checks again until its wait deadline, and a run that stays cut off ends with no charge.
+
 ## [0.33.0] - 2026-10-20
 
 ### 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[];