Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

docs: integrate refreshed quickstart videos and production guidance

kashorinb8e2a9b2400a
diff --cc docs/guide/author-packages.md
index db31aa03,db31aa03..bb3c159a
--- a/docs/guide/author-packages.md
+++ b/docs/guide/author-packages.md
@@@ -1,369 -1,369 +1,83 @@@
---
title: Adding an Author Package
--description: Step-by-step guide for adding a new author-level component.
++description: Build a project component, use it in a video, and share it when useful.
---
# Adding an Author Package
--An author package extends the video vocabulary with a new component. Authors use it through
--`<import>` and XML elements in their `.svml` source. No change to Core, the CLI or any aggregate
--package is needed.
++Creating a component is part of making a video. Start with the behavior the scene needs: what stays
++together, what changes, and which events drive it. An ordinary media presentation may use Media
++Track. A video viewport that moves aside while a diagram appears can belong to one project component,
++with independent captions remaining separate.
--## Public ids for Style-like Surfaces
++## Start from a complete package
--When a Surface publishes a Style-like value, its public record is the bare authored id (`${id}`),
--not `${id}.style` or `${id}.value`. Author Source then references it with the bare id, for example
--`style={board-style}`. Suffixes such as `.track` remain appropriate for separate Track outputs; they
--must not be added to the Style record merely to describe its role.
++The installed `hypit` Distribution includes
++[`examples/minimal-author-package/packages/example-component`](https://github.com/hypit-ai/hypit/tree/main/examples/minimal-author-package/packages/example-component).
++Copy that directory into your video's `packages/` directory. Give its package and Module your own
++scope and name, and replace the fixture's `workspace:*` Hypit development dependency with the
++Distribution release used by the project.
--## 1. Create the package
++From the copied package directory:
```bash
--mkdir -p packages/my-component/src
++npm install --save-dev hypit@<selected-release>
++npm run build
```
--Create it inside the video project. Use the owner's package scope; `@hypit/*` belongs to the active
--Distribution.
++The example includes TypeScript build configuration, Manifest, Surface, Fragment, Producers,
++activation and a small preview Source. Its [README](https://github.com/hypit-ai/hypit/blob/main/examples/minimal-author-package/packages/example-component/README.md)
++explains the exact files and package setup. The project can use its package manager's workspace or
++local package dependency to install the component.
--## 2. Write package.json
++## Give the component a useful interface
--```json
--{
-- "name": "@your-studio/my-component",
-- "version": "0.0.0-dev",
-- "private": true,
-- "type": "module",
-- "files": ["dist", "preview", "README.md"],
-- "exports": { ".": "./dist/index.js" },
-- "hypit": {
-- "activation": "./dist/activation.js"
-- },
-- "devDependencies": {
-- "hypit": "^0.1.0",
-- "typescript": "^5.9.0"
-- }
--}
--```
--
--The package uses public `hypit/*` subpaths while it is developed and publishes only its own compiled
--files. See [Package architecture](./packages.md) for layer rules.
--
--## 3. Define the Module Manifest
--
--In `src/index.ts`, declare your Module's identity, Types and Producers:
--
--```typescript
--import type { ModuleManifest, ModuleRef } from "hypit/author-kit";
--
--export const myComponentModuleRef: ModuleRef = {
-- name: "@your-studio/my-component",
-- version: "1",
--};
--
--export const myComponentManifest: ModuleManifest = {
-- format: "hypit.module@1",
-- name: myComponentModuleRef.name,
-- version: myComponentModuleRef.version,
-- dependencies: [],
-- types: [{ name: "Widget" }, { name: "WidgetProgram" }],
-- capabilities: [],
-- producers: [{
-- name: "render-widget",
-- inputs: [{ name: "space", type: { module: { name: "@hypit/program-space", version: "1" }, name: "ProgramSpace" } }],
-- outputs: [{ name: "track", type: { module: myComponentModuleRef, name: "WidgetTrack" } }],
-- needs: [],
-- }],
--};
--
--export const myComponentMarkupSurfaces = [{
-- name: "widget",
-- tag: "Widget",
-- mode: "structured",
-- outputs: [{ module: myComponentModuleRef, name: "Widget" }],
-- vocabulary: { /* see step 5 */ },
--}] as const;
--```
--
--Types are nominally owned by Modules. Core does not maintain a central union of every domain
--type — installing a new package can add a new Type without a Core release.
--
--## 4. Implement the Surface handler
--
--The Surface handler decodes the Markup Frontend's XML elements into typed author declarations.
++Expose the decisions another video author would want to change: content, materials, placement,
++appearance and meaningful events. A transition can accept a Moment for when the layout changes and
++a Selection for how long the scene appears. A pure animation can accept authored event times instead.
++Project those inputs onto the chosen clock, then use the resulting schedule to draw the scene.
--```typescript
--// src/surface.ts
--import type { StructuredSurfaceHandler } from "hypit/author-kit";
++For an existing spoken performance, consume its SemanticTrack so picture sampling follows the same
++takes and source positions as the speech. Other video inputs enter the timeline as normalized media.
++The [responsive explainer example](https://github.com/hypit-ai/hypit/tree/main/examples/semantic-composition/packages/responsive-explainer)
++shows a continuously playing video moving from full screen to a side portrait inside an HTML scene.
++The [chat example](https://github.com/hypit-ai/hypit/tree/main/examples/semantic-composition/packages/chat-scene)
++shows the same event interface accepting authored times or Script Moments.
--export const decodeMyComponentSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
-- const id = textAttribute(element, "id");
-- const space = resolveReference(referenceAttribute(element, "space"));
-- if (space === undefined) throw new Error("Widget.space cannot be resolved");
-- const record: SurfaceRecordDraft = {
-- id: `${id}.value`, type: widgetTypes.widget,
-- value: { kind: "inline", value: { id } }, range: element.range,
-- };
-- const fragment = sealGraphFragment({
-- inputs: [{ name: "space", type: programSpaceTypes.programSpace }],
-- operations: [{ id: "render-widget", producer: widgetProducers.render,
-- inputs: { space: { kind: "fragment-input", name: "space" } },
-- result: { kind: "output", name: "track" } }],
-- exports: [{ name: "track", type: compositionTypes.visualTrack,
-- root: { kind: "fragment-operation", operation: "render-widget" } }],
-- });
-- const component: SurfaceComponentDraft = {
-- id, fragment: fragment.id, inputs: { space: space.ref },
-- outputs: { track: `${id}.track` }, range: element.range,
-- };
-- return { records: [record], components: [component], fragments: [fragment], exports: [`${id}.value`, `${id}.track`] };
--};
--```
--
--[Component Anatomy](./component-anatomy.md) names every role a component package fills and points to
--the minimal fixture's corresponding role, so a new package does not need to inspect a business package.
++A Style-like Surface publishes its value under the bare authored id, such as `style={board-style}`.
++Separate outputs can use descriptive suffixes such as `.visual`, `.audio` or `.track`. Document the
++chosen names and the accepted values in the component's own vocabulary and README.
--For a generic package, use the complete fixture at
--`examples/minimal-author-package/packages/example-component/` rather than copying an unrelated
--business package. A package whose vocabulary is structurally the same as an installed sibling may
--use that sibling's README and only the necessary role files as an implementation skeleton; create a
--new Module identity and do not edit the sibling.
++## Implement and inspect the scene
--## 5. Declare the Surface vocabulary and its preview
++Use `hypit/author-kit` for the author package API and public domain subpaths for the values you
++consume. [Component Anatomy](./component-anatomy.md) explains how the Manifest, Surface, Fragment and
++Producer cooperate. Keep project copy and media as inputs; draw the component's own panels, frames
++and decoration in its implementation.
--`vocabulary` is how the element explains itself. Authors read it, and so does every tool that
--inspects installed packages instead of reading source. A Surface without it is legal and invisible:
--whoever meets your element next has only the tag name to go on.
++A preview Source gives authors a small example they can open or render. Inspect the states that
++explain the behavior: entry, meaningful changes, held layout and exit. Check the component in the
++actual composition too, where its content, space and timing have a purpose.
--```typescript
--// src/manifest.ts
--import { readFile } from "node:fs/promises";
++For richer interactive editing, add a Studio Companion. The
++[Companion SDK](https://github.com/hypit-ai/hypit/blob/main/packages/studio-adapter/README.md)
++shows how to expose timeline entities, properties and source bindings. The rendering code and
++Companion are separate contributions in the same package.
--const previewImage = (file: string) => ({
-- mediaType: "image/png",
-- path: `preview/${file}`,
-- open: async () => Uint8Array.from(await readFile(new URL(`../preview/${file}`, import.meta.url))),
--});
--
--vocabulary: {
-- summary: "One sentence naming what this element produces and what it is placed on.",
-- appearance: "What a viewer actually sees, including how it enters, holds and leaves.",
-- preview: previewImage("Widget.png"),
-- attributes: [
-- { name: "id", kind: "identifier", required: true, summary: "Names this Widget." },
-- ],
-- children: [ /* accepted child elements */ ],
-- ports: [ /* declared edges */ ],
-- example: "<mine:Widget id=\"first\"/>",
-- notes: [ /* rules a reader would otherwise have to discover by failing */ ],
--}
--```
++## Use and share it
--Declare a `preview` for every Surface a reader should recognise at a glance in Studio's timeline or
--in a catalogue: the poster. A poster is a designed picture, not a frame of output. It says what the
--component *is* in the most abstract, most recognisable form the small space allows, the way a film
--poster is not a screenshot of the film: `@hypit/ranking`'s Column poster is a column of rank badges
--beside a column of icons; its Tier board is lettered rows with icons. Draw it as an SVG committed
--beside the package, rasterise it to the PNG the manifest names under `preview/`, and keep it stable
--while the component's look evolves. Skip it for a Surface with nothing to show, such as one that only
--assembles a request.
++Import the installed component's logical Module in Source:
--`appearance` and `preview` answer different questions and neither replaces the other. `appearance`
--says what the element draws in every case; the poster says what the element is for.
--
--The fixture's manifest is the canonical small vocabulary example. For a close sibling, read that
--package's own README and vocabulary first, then only the role files needed for the changed behavior.
--`hypit vocabulary <package>` prints the installed declarations; author from that output rather than
--from another package's source.
--
--## 6. Write the activation descriptor
--
--```typescript
--// src/activation.ts
--import { createMarkupSurfaceHostFacet } from "hypit/author-kit";
--import {
-- myComponentManifest,
-- myComponentMarkupSurfaces,
-- myComponentModuleRef,
-- decodeMyComponentSurface,
--} from "./index.js";
--
--export const hypitPackage = {
-- format: "hypit.node-package@1" as const,
-- modules: [{
-- manifest: myComponentManifest,
-- }],
-- hostFacets: [
-- createMarkupSurfaceHostFacet({
-- module: myComponentModuleRef,
-- declaration: myComponentMarkupSurfaces[0],
-- handler: decodeMyComponentSurface,
-- }),
-- ],
--};
--
--export default hypitPackage;
--```
--
--The Module automatically offers its exact `[email protected]`, so authors import
--`@your-studio/my-component@1` without a duplicate alias declaration. Use optional `specifiers` only
--when the package intentionally owns a genuinely different logical alias. The Surface declaration
--determines the accepted tag (`<mine:Widget>` when imported as `mine`). It is a Markup Host facet,
--not part of the semantic Module Manifest or Core.
--
--## 7. Build the package
--
--```bash
--pnpm build
--```
--
--Use `hypit/author-kit` for the framework-facing declarations and the relevant public domain subpaths,
--such as `hypit/composition`, for the values the component consumes or produces. The active
--Distribution supplies those same APIs while loading the compiled activation; the component tarball
--does not bundle a second copy of Hypit.
--
--## 8. Install
--
--```bash
--pnpm install --frozen-lockfile
++```svml
++<import as="mine" from="@your-studio/my-component@1"/>
```
--The package manager owns installation, versions and integrity. Hypit loads the package when an
--Author or Run Source imports one of its logical offers. Exact Module dependencies declared by its
--Manifest are loaded from its installed dependencies.
--
--## 9. Use in Author Source
--
--```xml
--<?svml using="@hypit/markup@1"?>
--<svml>
-- <import as="mine" from="@your-studio/my-component@1"/>
--
-- <mine:Widget id="demo" during={story.selection.example}/>
--</svml>
--```
--
--The `<import>` activates only author vocabulary. It never grants network, filesystem or credential
--authority.
--
--The fixture deliberately uses explicit role filenames so a new author does not need to infer the
--architecture from a large production package.
--
--## 10. Keep or share the same package
--
--Creating this package is ordinary production work. While it belongs only to the current video, keep
--it private under that project's `packages/`. When its owner wants another project to use it, compile
--the same package and either send a versioned `npm pack` tarball or publish it under the owner's npm
--scope or private registry. The consumer installs the chosen release with its package manager and
--commits the resulting lockfile; the logical Module import remains unchanged while that interface is
--compatible.
--
--For a public release, remove `private: true` and add ordinary npm discovery and ownership metadata:
--
--```json
--{
-- "description": "A speech-timed score strip for Hypit videos.",
-- "keywords": ["hypit", "hypit-author-package", "scoreboard"],
-- "repository": {
-- "type": "git",
-- "url": "git+https://github.com/studio/score-strip.git"
-- },
-- "license": "MIT"
--}
--```
--
--Its README should include a copyable Source example, public outputs, visual evidence of the component,
--and the Hypit release used to check it. After installation, `hypit vocabulary <package>` reads the
--selected release's own Surface declarations. Package discovery, publication, versions and integrity
--remain with npm or the selected private registry; Hypit loads the package only when Source imports
--one of its logical offers.
--
--## The complete literal shapes
--
--The fixture is the authoritative small example. These are the same object shapes in abbreviated
--form; there is no need to inspect a business package to discover them.
--
--```typescript
--const input = (name: string) => ({ kind: "fragment-input" as const, name });
--const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
--
--const fragment = sealGraphFragment({
-- inputs: [{ name: "space", type: programSpaceTypes.programSpace }],
-- operations: [{
-- id: "render-widget", producer: widgetProducers.render,
-- inputs: { space: input("space") },
-- result: { kind: "output", name: "track" },
-- }],
-- exports: [{ name: "track", type: compositionTypes.visualTrack, root: operation("render-widget") }],
--});
--
--// A structured Surface always returns these four collections. `exports` is optional.
--const decoded: SurfaceDecodeOutput = {
-- records: [{ id: "widget.value", type: widgetTypes.widget,
-- value: { kind: "inline", value: { id: "widget" } }, range: element.range }],
-- components: [{ id: "widget", fragment: fragment.id, inputs: { space: space.ref },
-- outputs: { track: "widget.track" }, range: element.range }],
-- fragments: [fragment],
-- exports: ["widget.value", "widget.track"],
--};
--```
--
--For temporal elements, the Surface side is `@hypit/temporal-markup`, not the graph-side
--`@hypit/temporal` module. Use `createTemporalWindowProjection` or
--`createTemporalInstantProjection` with the element, semantic reference and resolver, then append
--the returned `records`, `components` and `fragments` to the same `SurfaceDecodeOutput`. Because those
--projections publish records that other Surface code may reference, the declaration's `outputs` must
--include every generated public type (`TemporalInstantSpec`, `TemporalWindowSpec`, `TemporalInstant`
--and `TemporalWindow`) in addition to the component's own records and terminal Track. The minimal
--fixture's temporal helper shows the two packages and the attribute vocabulary without requiring a
--business package source read.
--
--Producer ports are exact, not variadic: the keys supplied by a Fragment operation must match the
--Manifest's `inputs`, `outputs` and `needs` exactly. For a variable number of child items, emit one
--operation per item and feed those operations into an append/merge Producer with fixed named ports;
--do not invent an `items[]` port that the Manifest did not declare.
--
--### Less-common literal shapes
--
--These details are part of the public vocabulary metadata and are easy to miss:
--
--```typescript
--children: [{ tag: "Row", cardinality: "many", summary: "Rows in display order." }];
--attributes: [{ name: "appearance", kind: "reference", required: true, summary: "Recipe sheet.",
-- recipe: [{ name: "accent", required: true, summary: "Colour for the active row.", values: ["red", "blue"] }] }];
--```
--
--`cardinality` and recipe-property `required` are mandatory. A validator receives the stored wrapper,
--so unwrap an inline value before inspecting it:
--
--```typescript
--handler: ({ value }) => {
-- if (value.kind !== "inline") throw new Error("Widget must be inline");
-- if (typeof value.value !== "object" || value.value === null) throw new Error("Widget is empty");
--}
--```
--
--When a component input refers to an authored Record, use `{ kind: "record", id: "record.id" }`;
--`space.ref` is a resolved reference, not the literal input shape. A temporal projection stores its
--resolved frame range at `window.span` (`startFrame` and `endFrameExclusive`), not beside the window.
--Media slots are Fragment inputs carrying a Blob Artifact; child elements and recipe properties belong
--in the Surface vocabulary, while deterministic rendering belongs in the Producer. Keep parent nesting
--and animation in the sealed `VisualElement` (`parent`, `order`, `animation.keyframes`) rather than
--inventing package-specific fields.
--
--```typescript
--// A child can be nested under a parent and animate an admitted local style.
--const panel = { id: "panel", kind: "box", order: 0, style: [] };
--const label = {
-- id: "label", parent: "panel", kind: "text", order: 1, style: [],
-- text: "A", fonts: [fontArtifact],
-- animation: { keyframes: [
-- { atFrame: 0, style: [{ name: "opacity", value: 0 }] },
-- { atFrame: 12, style: [{ name: "opacity", value: 1 }] },
-- ] },
--};
--```
++Use its declared elements and outputs in the composition. `hypit vocabulary` exposes their authored
++interface; `hypit check` checks a Source or Run. The component's README should include a copyable
++example, its outputs, useful creative choices and a picture of the behavior.
--The exact `fontArtifact` fields are shown by `inspect_visual_schema`; use a real Blob Artifact in
--`sources`, with an explicit weight and style. The important boundary is that parent links, child
--cardinality, recipe properties, slot inputs and animation are declared explicitly and validated by
--their owning layer.
++Keep the package with its video project while it serves that work. To share it, choose a release
++version, compile and pack its code and assets with `npm pack`, or publish under the owner's scope
++in npm or a private registry. For registry publication, remove `private: true` and supply the normal
++package metadata. Consumers install the selected version and commit their package-manager lockfile.
++A Hypit repository checkout or upstream pull request is not needed to use the component.
diff --cc docs/guide/component-anatomy.md
index 67c5d7d2,67c5d7d2..a503e194
--- a/docs/guide/component-anatomy.md
+++ b/docs/guide/component-anatomy.md
@@@ -1,82 -1,82 +1,65 @@@
---
title: Component Anatomy
--description: The roles a component package fills, illustrated by the minimal author-package fixture.
++description: Turn a scene's creative interface into a reusable graph contribution.
---
# Component Anatomy
--Every component package fills the same set of roles. This page describes the roles and their
--canonical fixture locations;
--[Adding an Author Package](./author-packages.md) is the step-by-step.
++A component connects an author-facing idea to its implementation. For a ranking board, that idea
++might be “introduce each contender on its line, then move its icon into the ranked position.” Its
++inputs express those relationships; its code supplies the drawing and motion.
--Read this instead of reading a neighbouring package end to end. One package's specifics are a worse
--thing to copy than its structure.
++Start with [Adding an Author Package](./author-packages.md) for a complete buildable example.
++[Ranking](https://github.com/hypit-ai/hypit/blob/main/packages/ranking/README.md) is a richer example
++of semantic events, persistent state and a Studio Companion.
--## The roles
++## The implementation roles
--| Role | What it owns | Called |
--|---|---|---|
--| Manifest | Module identity, nominal Types, Producers, Surface declarations and their vocabulary | `manifest.ts`, sometimes `index.ts` |
--| Types | The TypeScript shapes those nominal Types carry | `types.ts` |
--| Value layer | `assert…`, `seal…` and `create…` for every authored value | `program.ts`, `schedule.ts` |
--| Style decoder | One SVS Recipe plus exact fonts into a Style value | `author.ts`, `style.ts` |
--| Renderer | A Program into the elements a Track presents | `lower.ts`, `render.ts`, `presentation.ts` |
--| Surface | XML element into typed records and inputs | `surface.ts` |
--| Producers | The deterministic handlers the Manifest declared, and Validators | `component.ts` |
--| Fragment | The graph a Surface expands into: inputs, operations, outputs | `fragment.ts` |
--| Activation | The host facets a Host installs | `activation.ts` |
++These roles can be organized into files that suit the component's size:
--Use `examples/minimal-author-package/packages/example-component/` for the canonical role layout.
--Only when vocabulary inspection proves a close structural sibling should you inspect that sibling's
--README and the specific role files you must adapt; do not compare unrelated business packages to
--infer generic architecture.
++| Role | Responsibility |
++| --- | --- |
++| Manifest and Types | Name the values, Producers, inputs and outputs the package provides |
++| Surface | Read the authored element and resolve its explicit inputs |
++| Fragment | Describe the operations and dependencies connecting those inputs to outputs |
++| Producer | Perform the declared computation |
++| Value and Style helpers | Validate inputs, apply documented defaults and decode the accepted Recipe properties |
++| Schedule and drawing | Project events and draw the scene at each frame |
++| Activation | Publish the contributions the selected package offers |
++| Studio Companion | Describe timeline entities and editable properties for Studio |
--## What each role must get right
++The [Author SDK](https://github.com/hypit-ai/hypit/blob/main/packages/author-kit/README.md)
++and included example own the exact object shapes. A small component can keep related roles together;
++a larger component benefits from separating reusable scheduling, styling and drawing logic.
--**Types and Manifest are the contract.** Everything else agrees with them, so write them first and
--stop changing them. A nominal Type belongs to your Module; Core keeps no central union, so adding one
--needs no Core release.
++## Design around relationships
--**The value layer is where authored data becomes trustworthy.** Every value that crosses a boundary
--gets an `assert…` that states what is wrong in the author's terms, and a `seal…` that canonicalises
--it. A Producer that receives an unsealed value has no way to tell a mistake from a shape it has not
--met. The fixture's value layer is the minimal pattern; a close sibling may be used as a bounded
--implementation skeleton only after vocabulary inspection.
++For spoken work, accept Selections and Moments for behavior tied to the words. Their projection
++provides exact windows and instants after the performance exists. For an authored animation,
++seconds or frames can express the reading rhythm. A duration such as `12f` can describe the length
++of a transition in either case.
--**The Style decoder reads a Recipe, not a stylesheet.** It takes one decoded `SvsRecipe` shaped as
--`{ path, properties }` and the exact fonts, validates the keys it admits, and produces a Style value.
--Unknown keys fail; defaults are declared, not implied. Use the fixture's decoder for the generic boundary, or the selected close sibling when
--the new package intentionally extends that sibling's domain contract.
++Media presentation, spatial layout and time each have their own inputs. A normalized clip supplies
++sampleable media; a SemanticTrack can supply the prepared performance and its source positions.
++A Frame can locate the scene, while its internal HTML/CSS or element tree coordinates videos,
++text, masks and graphics. Group content that shares behavior. Independent contributions can stay
++as peer Tracks with their own paint order.
--**The renderer turns a Program into elements and nothing else.** It resolves no timing of its own and
--reaches into no other Track. Timing arrives already projected; placement arrives as a Frame.
++A caption component benefits from the existing caption document, style selection and semantic
++timing. Use the fine-caption family for the styles it expresses; a new family can consume those
++same caption relationships and draw a different visual treatment.
--**The Surface decodes one element.** It reads attributes and children, resolves references, pushes
--typed records, and returns the graph declarations. It is the only place that knows the markup exists.
++## Make it useful to another author
--**The Fragment is the shape, not the work.** It declares which inputs the Surface supplies, which
--operations run, and which outputs the element publishes. Producers do the work; the Fragment says how
--they are wired.
++Choose parameter names from the creative decision: the reveal event, the content, the placement,
++the appearance. Document defaults and what an override changes. A Style decoder receives an SVS
++Recipe shaped as `{ path, properties }` and explicit font resources; a Source references the Style
++by its authored id.
--An author package's Surface returns this Graph Fragment; it is not the `run-fragment-host` facet used
--by preview or other Run-side replacement packages. Every operation must use a Producer declared by
--the same Module. Producer port bindings are exact: variable-length collections require repeated
--operations followed by a fixed-port append/merge Producer rather than an undeclared variadic input.
++Keep the video's particular copy and media as inputs. The component draws its own graphic
++structure and can ship reusable assets such as fonts or icons. Its example Source should show the
++states that matter, including how it behaves with different content or a changed event time.
--## Assets a package ships
--
--A component's own chrome — its paper, board, panel or default backdrop — is drawn by the component's
--own code, and the preview image its Surface declares is captured from that rendering. A small static
--file a component ships, such as a font or an icon set the author already owns, is read with
--`readFile(new URL("../assets/…", import.meta.url))`. None of this is an input the installing project
--supplies, and none of it is produced by a Build or by an image model.
--
--A component that cannot draw itself without a Source supplying its background is the wrong shape.
--The symptom is unmistakable — it imports cleanly and renders nothing.
--
--## What does not belong in a component package
--
--- Credentials, HTTP, queues or Provider selection. A model package owns request semantics only.
--- Timing resolved from anything other than the ProgramSpace and SemanticMap it was given.
--- Access to another Track's values.
--- A field added to Core, Composition or Visual IR to make one component work.
++The package's README and vocabulary give authors enough information to choose and use it. A Studio
++Companion can add editing handles for the source values that have a clear interpretation. New visual
++behavior belongs in this package; a Provider handles external execution when the graph needs it.
diff --cc docs/guide/conventions.md
index 0a19011f,0a19011f..231d4ebc
--- a/docs/guide/conventions.md
+++ b/docs/guide/conventions.md
@@@ -5,6 -5,6 +5,8 @@@ description: Naming, module boundaries
# Conventions
++These conventions describe work inside the Hypit repository. Project extensions use their owner's scope and the public `hypit/*` SDK subpaths; see [Packages and Extension](./packages.md).
++
## Naming
| Thing | Convention | Example |
@@@ -18,7 -18,7 +20,7 @@@
## Module boundaries
--- Each package has exactly one public entry point: `src/index.ts`.
++- A package declares its public entry points in `package.json` exports; `src/index.ts` is the usual workspace entry.
- Internal modules use explicit `.js` extensions (NodeNext resolution).
- Cross-package imports use `@hypit/*`, never relative paths across package boundaries.
- Circular production dependencies are forbidden.
@@@ -44,8 -44,8 +46,8 @@@ Adding a package does not require chang
- All persisted data uses the `@1` wire format version.
- Project-owned Module and Frontend identities use the literal logical version `1`.
--- Workspace `package.json` versions remain `0.0.0-dev` until publication. They are physical package
-- metadata, not logical protocol identities.
++- Package versions select physical releases through npm or pnpm. They are distinct from logical
++ Module and Frontend interface versions.
- npm or pnpm owns installed package versions and bytes. Hypit identities describe semantic
Modules, Frontends, Fragments and implementations rather than pretending to hash an installed package.
- Wire types are defined in `@hypit/protocol` and are immutable.
@@@ -56,5 -56,5 +58,6 @@@
- Compilation failures throw with descriptive messages including source location.
- Runtime failures are recorded as Operation failures in the Build state machine.
--- Recoverable failures trigger retry according to Endpoint policy after Scheduler capacity acquisition.
--- Fatal failures transition the Build to a terminal state.
++- Providers own bounded transport retries where their service protocol permits them.
++- A failed execution attempt ends the Build. Further work uses a new Run and Build, with completed
++ Outputs explicitly selected for reuse.
diff --cc docs/guide/develop.md
index 2a322a87,2a322a87..ec73d6aa
--- a/docs/guide/develop.md
+++ b/docs/guide/develop.md
@@@ -9,7 -9,7 +9,7 @@@ description: Getting started with Hypi
| Tool | Version | Required for |
|---|---|---|
--| Node.js | 22+ | everything |
++| Node.js | 22.12+ | everything |
| pnpm | 10.33.x | workspace management; selected by the root `packageManager` field |
| Python | 3.10–3.13 | local WhisperX and OpenCV Managed Programs |
| uv | latest | Python environment management |
@@@ -52,10 -52,10 +52,10 @@@ hypit
| Guide | Topic |
|---|---|
--| [Hypit Skill Architecture](./skill.md) | Route entry points, tools, handoffs and durable JSON state |
--| [Package architecture](./packages.md) | Layers, dependency rules, package anatomy, facets |
++| [Making videos with an Agent](./skill.md) | Creative direction, service choices and editable projects |
++| [Packages and Extension](./packages.md) | Component, model and service ownership; installation and sharing |
| [Adding an author package](./author-packages.md) | Step-by-step: new component, Surface, vocabulary and preview, activation |
--| [Adding a Provider](./providers.md) | Step-by-step: new Endpoint adapter |
++| [Models and Providers](./providers.md) | Select accounts and APIs; develop a Model or Provider package |
| [Runtime](./runtime.md) | Profile, Workspace, execution and lifecycle boundaries |
| [Testing](./testing.md) | Test runner, patterns, examples, boundary tests |
| [Conventions](./conventions.md) | Naming, module boundaries, wire data, TypeScript config |
diff --cc docs/guide/packages.md
index 1653eee5,1653eee5..4a961368
--- a/docs/guide/packages.md
+++ b/docs/guide/packages.md
@@@ -1,300 -1,300 +1,70 @@@
---
--title: Package Architecture
--description: The seven layers, dependency boundaries, package anatomy and facets.
++title: Packages and Extension
++description: How video projects select components, models and services as ordinary packages.
---
--# Package Architecture
++# Packages and Extension
--Internal modules under `packages/` are organized into seven architectural layers. Dependencies are
--declared by each module itself. The published `hypit` Distribution includes the complete official
--module tree so the Package Loader can resolve any explicitly selected package, while TypeScript has
--no central path alias that can hide an undeclared import.
++Hypit separates what a video asks for from the code and services that fulfill it. A new graphic,
++model or API source can be supplied by a package and selected by the project. Each package owns its
++interface and implementation; the execution system runs the resulting dependency graph.
--The complete official tree is source/code, not an eager download of every upstream dependency.
--The base npm install contains only the launcher dependency. Selected Runtime adapters prepare their
--ordinary npm dependencies in the shared machine package home during explicit `runtime up`; optional
--author assets such as Fontsource families are installed with the exact `hypit packages install`
--command reported by compilation. npm's package manifest remains the authority—Hypit adds no second
--lock, receipt or hash inventory. Project-scoped third-party components and their dependencies remain
--owned by that project's package manager.
++## What belongs where
--## The seven layers
++| Part | Responsibility | Where it is selected |
++| --- | --- | --- |
++| Author component | Turns author inputs into media requests, visual behavior or other graph outputs | Source imports |
++| Model | Defines an exact generation request and its outputs | Source imports |
++| Provider Endpoint | Executes supported requests through an API or local tool | Runtime Profile |
++| Credential store | Resolves the named credentials for an Endpoint | Runtime Profile |
++| Result repository | Keeps a project's Build records and produced files | Project Result configuration |
++| Distribution | Supplies the executable applications and official packages | Installed `hypit` release |
--### Layer 1: Hypit Core
++For example, a Model describes a requested video, while a Provider maps that request to a service.
++A ranking component describes how a board behaves, while the renderer draws its contribution into
++the final composition. Both participate in the same graph, with explicit inputs and outputs.
--The immutable graph protocol, demand compiler and Build state machine. This closure is domain
--neutral and knows nothing about source syntax, files, networks, models or video.
++## Components follow the work
--```text
--@hypit/protocol immutable wire contracts
--@hypit/core Demand compiler and Build state machine
--```
++A video's spatial structure is organized where that organization is useful. Media Track can present
++an ordinary clip or picture; a project component can coordinate a moving video viewport, labels and
++a diagram inside one scene. Independent captions or overlays can remain separate contributions.
++Each component owns the content whose behavior belongs together.
--### Layer 2: Compiler
++For a spoken video, Script Selections and Moments let those components follow the meaning of the
++performance. An authored animation can instead use seconds or frames on its declared clock.
++[Film and Rendering](../quickstart/composition.md) explains how these contributions fit together.
--Source discovery, Frontends, imports, graph elaboration and the reference Node Host. A source
--selects its own Frontend in its mandatory header; no central parser knows every language feature.
++New components normally live in the video's `packages/` directory and use the owner's package
++scope. The project declares them with its ordinary package manager. When cross-project reuse is
++useful, the owner can publish the same component as a versioned npm or private-registry package.
++The consumer installs a chosen version and keeps its lockfile with the project.
--```text
--@hypit/source mandatory Source Header
--@hypit/elaborator author declarations and Fragment expansion
--@hypit/run syntax-neutral Run Graph
--@hypit/validation semantic validation
--@hypit/host opaque Host-facet envelope
--@hypit/workspace replaceable Source/Asset session
--@hypit/compiler-node reference Node compiler Host
--@hypit/workspace-fs-node workspace filesystem abstraction
--@hypit/package-loader-node installed package selection
--@hypit/markup official .svml Markup Frontend
--@hypit/svs SVS Recipe Frontend
--@hypit/run-markup official .svrun Markup Frontend
--@hypit/compiler-markup-node Markup Frontend + Surface Host assembly
--```
++## Installation and Source imports
--### Layer 3: Foundations
++The Skill, executable Distribution and video project are installed and updated separately. The
++`hypit` Distribution includes the official author packages and public extension APIs. Its selected
++Runtime adapters can prepare additional service dependencies through `hypit runtime up`; optional
++author assets can be installed with the precise `hypit packages install` command reported by the CLI.
++A project's own component dependencies are managed in that project.
--Reusable values and deterministic building blocks. They support video authoring but do not decide a
--film's creative structure or call an external service.
++Source uses a logical Module address such as `@your-studio/scoreboard@1`. npm's installed package
++version selects the implementation; the logical `@1` identifies its author interface. Building a
++video uses those installed versions. Missing packages are reported with the information needed to
++install them.
--```text
--@hypit/artifact Runtime-referenced byte values
--@hypit/component-kit Producer and validator registration
--@hypit/text graph-native text templates
--@hypit/media media values
--@hypit/temporal Selection and Moment projection
--@hypit/spatial layout geometry
--@hypit/visual-ir renderer-neutral visual vocabulary
--@hypit/fonts-open redistributable font assets
--@hypit/media-pipeline media inspection and normalization
--@hypit/media-execution shared ffmpeg execution body
--@hypit/transport invocation seams
--@hypit/transport-aws-lambda Lambda transport
--```
++## Write and share an extension
--### Layer 4: Video authoring
++An external package develops against public subpaths such as `hypit/author-kit`,
++`hypit/composition`, `hypit/model-kit` or `hypit/endpoint-kit`. Use the selected `hypit` release as a
++development dependency, compile the extension to JavaScript, and ship its own code and assets. Its
++`package.json` names an activation entry describing what it provides. The active Distribution
++supplies the public Hypit APIs when it loads the selected extension.
--The packages that give SVML its video vocabulary: narrative, exact model requests, speech,
--captions, peer Tracks, Film and render declarations. They depend on shared contracts, never on a
--specific Provider deployment.
++- [Adding an Author Package](./author-packages.md) starts from an included, buildable component.
++- [Component Anatomy](./component-anatomy.md) explains the roles within a component.
++- [Models and Providers](./providers.md) explains new models, services and credentials.
++- [Runtime](./runtime.md) covers Endpoint and credential configuration.
--```text
--@hypit/narrative authored narrative products
--@hypit/script Script Surface
--@hypit/program-space exact frame/sample domain
--@hypit/generation image/video/audio generation contracts
--@hypit/model-kit model family abstractions
--@hypit/seedance Seedance model family + author Surface
--@hypit/seedance-kits data-only Seedance semantic Text Templates
--@hypit/minimax-h3 MiniMax H3 model family
--@hypit/grok-imagine Grok Imagine model family
--@hypit/gpt-image GPT Image model family
--@hypit/nano-banana Nano Banana model family
--@hypit/seedream Seedream model family
--@hypit/mimo-speech Xiaomi MiMo Voice Design and Voice Clone models + author Surfaces
--@hypit/estimate creation-time speech measurement (hypit measure) and the estimate policy type
--@hypit/speech shared speech products
--@hypit/speech-evidence acoustic evidence products
--@hypit/speech-alignment speech alignment
--@hypit/semantic-track continuous semantic program skeleton
--@hypit/speech-track ordered speech-take compilation
--@hypit/whisperx WhisperX component
--@hypit/caption Script-owned caption document, selection projection and timing
--@hypit/caption-fine field-free fine caption Track family
--@hypit/media-track unified Media Item/Sequence Track
--@hypit/typography-track typography overlay Track
--@hypit/audio-track arbitrary sample-domain Audio Track
--@hypit/deck-track depth-stack collection Track
--@hypit/ranking three ranking component families
--@hypit/screen-overlay self-contained full-canvas overlays
--@hypit/film Film composition
--@hypit/composition peer Track composition
--@hypit/hyperframes HyperFrames document compiler
--@hypit/render-hyperframes explicit HyperFrames rendering component
--@hypit/image-transform image processing component
--@hypit/image-compose ordered still-image composition
--@hypit/interview-emoji-reveal reusable top-of-frame answer icon strip
--@hypit/raster shared deterministic raster execution contract
--@hypit/background-removal external image cutout capability
--```
--
--### Layer 5: Providers
--
--Privileged external capabilities. Depend on Runtime ports and shared capability vocabularies,
--never on exact-model packages or the CLI.
--
--```text
--@hypit/provider-kie KIE generation plus background removal
--@hypit/provider-hypihub HypiHub generation, WhisperX gateway
--@hypit/provider-media-local local ffprobe/ffmpeg
--@hypit/provider-whisperx-local local WhisperX service
--@hypit/provider-hyperframes-local local Chrome rendering
--@hypit/provider-hyperframes-aws-lambda asynchronous distributed rendering
--@hypit/provider-image-opencv-local local OpenCV Raster execution
--@hypit/provider-media-aws-lambda synchronous AWS media execution
--@hypit/provider-xiaomi-mimo official Xiaomi MiMo Voice Design and Voice Clone API
--```
--
--### Layer 6: Runtime
--
--Domain-neutral execution ports plus replaceable deployment implementations. The local Runtime owns
--its queue, active stores and process lifecycle as one implementation; credentials, Endpoints and the
--project Build Result repository are the intentional package-selected boundaries.
--
--```text
--@hypit/runtime Scheduler, Worker and Store ports
--@hypit/endpoint-kit Endpoint declarations
--@hypit/driver-node trusted Node command executor
--@hypit/runtime-kit deployment package ABI
--@hypit/runtime-host-node Node Runtime Host ABI
--@hypit/runtime-local local Worker and assembly
--@hypit/store-sqlite SQLite state
--@hypit/resource-store-fs internal filesystem working Resources
--@hypit/resource-store-s3 library for Runtime implementations needing S3 working Resources
--@hypit/build-result storage-neutral project Result model
--@hypit/build-result-kit Build Result repository package ABI
--@hypit/build-result-fs default project Result repository
--@hypit/build-result-s3 optional S3-compatible project Result repository
--@hypit/credential-store-env environment credentials
--@hypit/credential-store-os macOS Keychain or Windows Credential Locker
--```
--
--### Layer 7: Applications
--
--```text
--@hypit/cli generic command engine (requires explicit Distribution)
--@hypit/video-cli video command application (selects Markup compiler, no built-in author packages)
--@hypit/studio-adapter stable Studio companion ABI and presentation DTOs
--@hypit/*-studio independent official Studio companions selected explicitly by the Distribution
--@hypit/studio development preview for a Run, never runs a Provider
--```
--
--## Dependency rules
--
--The package layout follows three dependency rules:
--
--1. **Acyclic production graph.** No dependency cycle among any `@hypit/*` packages.
--
--2. **Domain-neutral Core closure.** Layer 1 contains only `protocol` and `core`; `core` depends only
-- on `protocol`. Compiler and Runtime may also be domain neutral, but they remain outside Core.
--
--3. **CLI independence.** Neither `@hypit/cli` nor `@hypit/video-cli` transitively depends on any
-- Provider package. The video CLI also does not depend on any author-level video package
-- (`@hypit/script`, `@hypit/seedance`, `@hypit/media-track`, `@hypit/typography-track`, `@hypit/film`).
-- Author packages are activated through Source imports, not compile-time CLI
-- dependencies. These rules are kept visible in package manifests and reviewed as architecture,
-- rather than approximated by source-text regex tests.
--
--## Package anatomy
--
--Every package lives under `packages/<name>/` with this structure:
--
--```text
--packages/example/
--├── package.json
--├── src/
--│ ├── index.ts public API entry point
--│ └── activation.ts package contribution descriptor (if installable)
--└── test/
-- └── example.test.ts
--```
--
--### package.json
--
--```json
--{
-- "name": "@hypit/example",
-- "version": "0.0.0-dev",
-- "private": true,
-- "type": "module",
-- "exports": {
-- ".": "./src/index.ts"
-- },
-- "hypit": {
-- "activation": "./src/activation.ts"
-- },
-- "dependencies": {
-- "@hypit/protocol": "workspace:*"
-- }
--}
--```
--
--- `"exports"` points to TypeScript source directly during development. pnpm's workspace links resolve
-- `@hypit/*` imports through the dependency declared by the importing package.
--- `"hypit.activation"` is the entry point that the Package Loader reads when this package is
-- selected. It must default-export a `NodePackageContribution`.
--- The physical package version remains `0.0.0-dev` until publication. Module and Frontend manifests
-- use the independent logical protocol version `1`.
--
--### activation.ts
--
--Every installable package exports a passive contribution descriptor — an inventory of what it
--offers, not an authority grant. See [Adding an author package](./author-packages.md) and
--[Adding a Provider](./providers.md) for concrete examples.
--
--## Package facets
--
--A physical package may expose independently activated facets:
--
--| Facet | ABI | Authority | Selected by |
--|---|---|---|---|
--| `static` | Manifest and identity | none | always available after loading |
--| `author` | Frontend, Surface, Graph Fragment | author vocabulary only | source `<import>` through the compiler Host |
--| `compute` | deterministic Producer, Type Validator | pure computation | compiler Host |
--| `endpoint` | privileged external capability | network, filesystem, process, credentials | Runtime Profile |
--| `credential-store` | resolves explicitly named credentials | secret storage | Runtime Profile |
--| `result-repository` | completed Build Results | project history storage | project `hypit.results.json` |
--| `infrastructure` | Runtime Host, Scheduler and Worker implementation | persistence, scheduling | application Distribution |
--| `application` | Host-specific interpretation such as a Studio Track Companion | only that application's UI/operations | Distribution or selected Source package |
--
--A source `<import>` activates only author facets. It never grants network, filesystem, process,
--credential or queue authority.
--
--## Package selection
--
--Hypit does not maintain a package registry or a second package-resolution layer. npm or pnpm
--installs packages and owns their versions and integrity. Each owner has one explicit selection path:
--
--| Selection | Packages activated |
--|---|---|
--| Application Distribution | Runtime Host and trusted bootstrap packages |
--| Source imports | Frontends, Surfaces, Producers and Validators |
--| Runtime Profile `credentials.*.use` / `endpoints.*.use` | Credential Stores and Provider Endpoints |
--| Project Result config `use` | one Build Result Repository |
--| Studio Distribution + selected Source packages | official Companions plus project Companions used by that Source closure |
--
--A Source import never grants network, filesystem, process, credential or queue authority. Those
--remain available only to the Runtime Host and packages explicitly selected at environmental
--boundaries.
--
--### Logical package addresses and Source discovery
--
--Source code names logical language capabilities. By convention the logical name maps directly to
--the installed npm package name. A Module and a Run Fragment may share a spelling because their Host
--ABIs remain different, and one physical package may offer several logical names.
--
--Compilation reads only the mandatory Source Header first. It resolves that Frontend from installed
--packages, calls the Frontend's own `discover()` method, resolves the reported Modules,
--Run Fragments and child Sources, and repeats until the exact package subset stops growing. Only
--then does semantic decoding begin. Markup is the video Distribution's bootstrap Frontend; Script,
--SVS, Run Markup and third-party Frontends otherwise follow the same discovery protocol. The package
--selector contains no parser-specific branch.
--
--Frontend implementations are not privileged fields in the physical package format. They advertise
--the ordinary `hypit.source-frontend@1` Host facet, exactly as Run Fragments, Markup Surfaces and
--Runtime Adapters advertise their own Host ABIs. Only the Source Host interprets that facet.
--
--Runtime Profiles follow the same rule for the two facets they actually select. Each `use` names one
--Credential Store or Endpoint Adapter offer. Project Result configuration independently selects one
--Repository offer. The application Distribution supplies the Runtime Host itself; it is not repeated
--as a fake selector inside that Host's Profile. The generic CLI therefore contains neither a Provider
--registry nor a hard-coded Result Repository, and different Adapter kinds may share a logical spelling
--without colliding.
--
--The loader never downloads packages and never scans unrelated installed dependencies for plugins.
--It loads only packages selected by Source discovery, environmental configuration or the application
--Distribution, plus exact Module dependencies declared by those packages.
--
--An authored project is a separate directory and Git/workspace boundary. Its explicit packages are
--resolved from its own `packages/` or installation; the active tool Distribution supplies the
--reserved `@hypit/*` namespace. Project companion packages use their own npm scope, and neither a
--project nor its package globs are added to the Hypit workspace.
++Exact SDK types and implementation examples live with the corresponding package's README and
++source, which also ship in the Distribution.
diff --cc docs/guide/providers.md
index 05f72e6d,05f72e6d..7f7b06e4
--- a/docs/guide/providers.md
+++ b/docs/guide/providers.md
@@@ -1,246 -1,246 +1,72 @@@
---
--title: Adding a Provider
--description: Step-by-step guide for adding a new Endpoint adapter.
++title: Models and Providers
++description: Choose an account, connect a service or add a model without changing the video execution system.
---
--# Adding a Provider
++# Models and Providers
--A Provider package implements a privileged external capability — video generation, media
--processing, alignment or rendering. Caption authoring and cue grouping are Script-owned and do not
--need a Provider. A Provider is activated through the Runtime Profile,
--never through `<import>` in Author Source.
++A **Model** defines what you ask to generate: its inputs, supported parameters and output type.
++A **Provider** knows how to fulfill that request through a particular service. An **Endpoint** is a
++configured instance of that Provider, with its service address, credential reference and capacity.
++The Runtime Profile binds the requested capability to an Endpoint.
--No change to Core, the CLI or any author package is required.
++## Choose the change that matches the need
--## 1. Create the package
++| You want to… | Change |
++| --- | --- |
++| Use another key for the same service | The credential reference and selected Endpoint configuration |
++| Use another compatible service address | The address or deployment options supported by the Provider |
++| Use the same model through a different API | Install or write a Provider for that API and select its Endpoint |
++| Use a model not yet defined | Add a Model package and a Provider that supports its request |
--```bash
--mkdir -p packages/provider-my-service/src packages/provider-my-service/test
--```
++Two services offering the same model can have different request formats, limits or available
++parameters. The Provider checks the request against that service's support and explains a mismatch.
++A Profile chooses the route; an error on that route does not authorize spending through another account.
--## 2. Write package.json
--
--Provider packages depend on Runtime ports and shared capability vocabularies, never on exact-model
--packages or the CLI:
--
--```json
--{
-- "name": "@hypit/provider-my-service",
-- "version": "0.0.0-dev",
-- "private": true,
-- "type": "module",
-- "exports": {
-- ".": "./src/index.ts"
-- },
-- "hypit": { "activation": "./src/activation.ts" },
-- "dependencies": {
-- "@hypit/endpoint-kit": "workspace:*",
-- "@hypit/protocol": "workspace:*",
-- "@hypit/runtime": "workspace:*",
-- "@hypit/runtime-kit": "workspace:*",
-- "@hypit/runtime-host-node": "workspace:*",
-- "@hypit/generation": "workspace:*"
-- }
--}
--```
++For an existing installation, inspect the selected Profile and credential status first. A starter
++Profile supplies configuration examples; choose the services you want before connecting accounts or
++preparing their dependencies. [Runs and Builds](../quickstart/run.md) shows the commands.
--## 3. Implement the Provider
--
--The Provider handles Commands from the Scheduler: request submission, polling, download and writing
--the accepted Resource into the current Build's working byte area.
--
--```typescript
--// src/provider.ts
--import { defineEndpointPackage } from "@hypit/endpoint-kit";
--
--export function createMyServiceProvider(options: {
-- instance: string;
-- pool: string;
-- apiKey: CredentialRef;
-- defaultConcurrency?: number;
--}) {
-- return defineEndpointPackage({
-- module: { name: "@hypit/provider-my-service", version: "1" },
-- facet: "service",
-- instance: options.instance,
-- pool: options.pool,
-- credentials: { apiKey: options.apiKey },
-- defaultConcurrency: options.defaultConcurrency ?? 2,
-- capabilities: [{
-- capability: myCapability,
-- returns: myResultType,
-- capacity: "generate",
-- lifecycle: "asynchronous",
-- endpoint: myAsyncEndpoint,
-- }],
-- });
--}
--```
++## Add a Model
--Look at existing Providers for reference:
--- `packages/provider-kie/src/provider.ts` — remote generation with upload, polling and download
--- `packages/provider-media-local/` — local process execution (ffprobe/ffmpeg)
--- `packages/provider-whisperx-local/` — local HTTP service
--- `packages/provider-hyperframes-local/` — local Chrome rendering
--- `packages/provider-hyperframes-aws-lambda/` — asynchronous Step Functions/Lambda rendering
--- `packages/provider-media-aws-lambda/` — synchronous Lambda media execution over the shared ffmpeg body
--- `packages/provider-xiaomi-mimo/` — immediate official Voice Design and Voice Clone API without importing the MiMo model package
--
--## 4. Write the activation descriptor
--
--```typescript
--// src/activation.ts
--import {
-- createRuntimeEndpointAdapterFacet,
-- runtimeConfigCredentialRef,
-- runtimeConfigExact,
-- runtimeConfigObject,
-- runtimeConfigPositiveInteger,
--} from "@hypit/runtime-kit";
--import { createMyServiceProvider } from "./provider.js";
--
--const adapter = createRuntimeEndpointAdapterFacet({
-- use: "@hypit/provider-my-service",
--
-- activate(context) {
-- if (context.pool === undefined) throw new Error("MyService pool is required");
-- const config = runtimeConfigObject(context.config, "MyService");
-- runtimeConfigExact(config, ["apiKey", "defaultConcurrency"], "MyService");
-- const apiKey = runtimeConfigCredentialRef(config.apiKey, "MyService apiKey");
-- if (apiKey === undefined) throw new Error("MyService apiKey CredentialRef is required");
-- const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "concurrency");
-- return {
-- endpoint: createMyServiceProvider({
-- instance: context.instance,
-- pool: context.pool,
-- apiKey,
-- ...(defaultConcurrency === undefined ? {} : { defaultConcurrency }),
-- }),
-- };
-- },
--});
--
--export const hypitPackage = {
-- format: "hypit.node-package@1" as const,
-- hostFacets: [adapter],
--};
--
--export default hypitPackage;
--```
++Develop a project package against `hypit/model-kit`, `hypit/generation` and `hypit/author-kit`.
++Declare the exact request ports, parameter values, result type and capability. Its author Surface
++connects prompt Text and reference media to the request, then publishes the resulting media as a
++normal graph Output.
--`activate` is the one pure deployment declaration. The Endpoint it returns owns the credential
--references, capabilities and scheduling facts used by both `doctor` and execution.
--Activation must not resolve secrets or environment-sourced deployment values, access the network or
--start work. It keeps environment names as references until a matching Need is handled. Credential
--presence is diagnosed through the generic CredentialStore path; a Provider must not special-case
--environment variables as a secret Store.
--
--An activation may also return `diagnose(context)`. It runs only for an explicit active `doctor`, after
--the Runtime has resolved that Endpoint's declared credential slots. It may make a bounded, read-only
--request to the real service, such as reading the authenticated model catalog. It must not be called by
--Build preflight and must never submit generation work.
--
--A Provider that charges declares where it publishes prices with `pricing: { kind: "page", url }` on
--`defineEndpointPackage`; a Provider that runs on this machine declares `pricing: { kind: "local" }`.
--An Endpoint may additionally return current Provider-shaped documents from `readPricing`; a service
--with only a web page keeps that page as its interface. `hypit pricing <run> --runtime <profile>` places
--the material beside the Run's Needs without creating a Build. The Agent can calculate and explain the
--cost from those two facts, while the user's decision remains the spending authority. The shared
--interface carries a source URL, Provider-shaped JSON and an optional concise rate summary, so a newly supported relay does not
--require a new Hypit pricing category.
--
--`hypit plan --runtime <profile>` remains local and prints the Endpoint behind each request. Planning
--applies the selected Endpoint's ordinary `supports` check and does not maintain a second selection
--table. When an upstream file will only exist during the Build, the capability package reconstructs the authored
--request parameters and leaves that file as a symbolic Resource slot. The same `supports` predicate still
--runs before the Build is queued. A package that cannot describe the request stops planning instead of
--falling back to capability-only selection.
--
--## 5. Declare a Managed Program when needed
--
--If the Provider depends on a warm external program, export its declaration beside the Endpoint.
--There is no second manifest flag or central program registry:
--
--```typescript
--// src/program.ts
--import type { ManagedProgram } from "@hypit/runtime-kit";
--
--export function createMyProgram(): ManagedProgram {
-- return {
-- id: "my-service",
-- prepare: { command: "uv", args: ["sync", "--project", "services/my-service", "--frozen"] },
-- start: { command: "uv", args: ["run", "--project", "services/my-service", "--frozen", "hypit-my-service"] },
-- probe: async () => {
-- // Return { state: "ready" } or { state: "down", detail: "..." }
-- },
-- };
--}
--```
++The [Model SDK](https://github.com/hypit-ai/hypit/blob/main/packages/model-kit/README.md) includes a
++request definition and explains activation. The package owns the model interface; credentials and
++HTTP mapping belong to the Provider.
--Return it beside the Endpoint from the same activation:
--
--```typescript
--const adapter = createRuntimeEndpointAdapterFacet({
-- use: "@hypit/provider-my-service",
-- activate(context) {
-- return {
-- endpoint: createMyServiceProvider(/* parsed config */),
-- program: createMyProgram(),
-- };
-- },
--});
--```
++## Add a Provider
--`hypit runtime up` prepares, starts and probes declared **local** Managed Programs before starting the
--durable Worker. `build` only preflights Programs backing capabilities demanded by its plan and
--fails before submission when one is not ready; it never installs or starts one. Providers that call
--only remote APIs omit `program` entirely; Hypit has no `up` or `down` lifecycle for those services.
++Use the selected `hypit` release as a development dependency and import the public SDK:
--## 6. Install
++```ts
++import { defineEndpointPackage } from "hypit/endpoint-kit";
++import type { AsyncEndpoint, CredentialRef, EndpointRequest } from "hypit/endpoint-kit";
++```
--Declare every imported package in the Provider's own `package.json`:
++Implement the exact capabilities and result types the service supports. Map request ports to the
++service API, resolve the declared credentials, and return its results. An immediate operation
++returns directly; a remote task can submit an ID, poll for completion and collect the output files.
++Concurrency and action limits belong to the Endpoint's resource declarations.
--```json
--"dependencies": {
-- "@hypit/runtime-kit": "workspace:*"
--}
--```
++A genuine failure ends that execution attempt. Build Results preserve completed Outputs and public
++task receipts. Further work uses a new Run and Build with suitable existing Outputs selected for reuse.
--Install the package with the project's package manager. It remains inert until the Runtime Profile
--explicitly selects its `use` id.
--
--## 7. Reference from hypit.runtime.json
--
--```json
--{
-- "endpoints": {
-- "my-service": {
-- "use": "@hypit/provider-my-service",
-- "pool": "my-service.account",
-- "config": {
-- "apiKey": { "store": "os", "key": "my-service.api-key" },
-- "defaultConcurrency": 2
-- }
-- }
-- }
--}
--```
++The [Endpoint SDK](https://github.com/hypit-ai/hypit/blob/main/packages/endpoint-kit/README.md)
++owns the handler interfaces, activation, resource declarations and pricing API. Compile the package
++to JavaScript and install it in the project through its package manager. Configure its Endpoint
++under `endpoints` and select it in `bindings` in the [Runtime Profile](./runtime.md).
--Verify the configuration:
++## Prices and permission
--```bash
--hypit doctor hypit.runtime.json
--```
++The Provider declares local work without a Provider charge, or supplies its published pricing page.
++It can also read current rates using the Endpoint's credentials and return a concise summary with
++the original pricing documents. `hypit pricing <run>` brings those rates together with the planned
++requests. Pending media measurements remain unknown until the material exists.
--## Existing Providers to study
--
--| Package | Pattern |
--|---|---|
--| `provider-kie` | Remote API: upload, paid submission, checkpointed polling, bounded download into the current Build workspace |
--| `provider-media-local` | Local process: shell-free ffprobe/ffmpeg with bounded execution |
--| `provider-whisperx-local` | Local HTTP service with a warm model, single-admit concurrency |
--| `provider-hyperframes-local` | Local process: Chrome rendering with worker parallelism and output probe validation |
--| `provider-hyperframes-aws-lambda` | Remote asynchronous job: Step Functions submission, polling and S3 streaming |
--| `provider-image-opencv-local` | Local Python: bounded OpenCV/NumPy with locked Python environment |
--| `provider-media-aws-lambda` | Remote synchronous Lambda: the same nine capabilities as local media |
--| `provider-xiaomi-mimo` | Remote immediate API: exact MiMo Voice Design and Voice Clone requests to persisted audio Resources |
++Rates help explain the cost. The user's agreement supplies permission to spend through the selected
++account for the agreed work and budget. That permission is separate from a successful login or an
++available balance.
diff --cc docs/guide/skill.md
index 0e48d84b,0e48d84b..34f53387
--- a/docs/guide/skill.md
+++ b/docs/guide/skill.md
@@@ -19,17 -19,17 +19,26 @@@ through their own installation channels
Understanding a reference moves between the whole piece and the details that explain it: why the
opening catches attention, how a performance carries the argument, and what pictures, captions,
--graphics, and sound contribute. Observation, transcription, and focused frames or clips supply the
--evidence for that judgment.
++graphics, and sound contribute. Word-timed transcripts and frame sequences help locate the details:
++what enters, how it moves, and why it matters at that point. The Agent records the overall reading
++and the precise observations in the project's reference notes.
Making the target moves between intention and visible results. Replacing a presenter or product can
change the script, performance, setting, and payoff as well as the reference images. The Agent works
--through those consequences with the new goal in mind, then uses Studio and rendered media to refine
--the result.
++through those consequences with the new goal in mind. It puts the visual identity, reference
++relationships, pronunciation and performance direction into the image prompts, Script and video
++prompts before generating material. Components and captions can be developed while generation runs.
++With the actual material present, a focused composition review checks hierarchy, placement,
++entrances, exits and timing against the intended effect.
--You decide the goal, private facts, and spending. The Agent handles ordinary creative and technical
--choices within that direction. Before paid requests, it explains the selected services, request
--quantities, and the pricing information supplied by their Providers.
++You decide the goal, private facts, service accounts and spending. The Agent checks relevant existing
++capabilities and explains the choices when something is missing. For a spoken reference, that can
++mean preparing local WhisperX or choosing hosted transcription; image and video generation can use
++supported services with your own keys or a HypiHub account.
++
++Before paid work, agree on the account, scope and budget using the available pricing information.
++The Agent handles ordinary creative and technical decisions within that commission, explains its
++findings and progress, and brings changes in scope or cost back to you.
## Keep the project editable
@@@ -42,7 -42,7 +51,9 @@@ The project keeps the work in ordinary
- Build Results retain produced Outputs and the facts of that execution.
Project components are part of making a video. They live with the project and can express a new
--visual role, Caption family, or graphic behavior. A component that needs cross-project reuse can be
++visual role, Caption family, or graphic behavior. Content that shares layout or motion can form one
++scene; independent graphics and captions can stay separate. Spoken work uses Script events to drive
++these relationships, while purely visual animation can use an authored clock. A component that needs cross-project reuse can be
published as an ordinary versioned package under its owner's scope.
When revising the work, the Run can reuse suitable Outputs from earlier Results, including useful
@@@ -50,6 -50,6 +61,6 @@@ media produced before a Build failed.
selected work and writes supported edits back to its Source files; the Agent reviews the actual
finished video against the intended result.
--[Quickstart](../quickstart.md) introduces the file formats and commands.
++[Quickstart](../quickstart.md) walks through making a video with your Agent.
[Runs and Builds](../quickstart/run.md) explains execution and Output reuse.
[Studio](../quickstart/preview.md) explains interactive preview and editing.
diff --cc docs/quickstart.md
index 238159c0,3bf56973..deb8eb96
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@@ -1,19 -1,14 +1,18 @@@
---
title: Quickstart for Agent users
- description: Create, review and ship Hypit videos from a Coding Agent without writing SVML or SVS by hand.
-description: Clone a video from a Coding Agent in five steps.
++description: Turn a reference video into a new video for your presenter, product and audience.
---
- You do not need to know SVML, SVS, JavaScript or the command line. Describe your video in ordinary
- language; the Agent uses the `/hypit` skill to understand the reference, direct the work and deliver
- a video with an editable project.
-Describe the video you want in plain language. The Agent uses the `/hypit` skill to do the rest.
++# Make a video with your Agent
+
- The recordings illustrate example conversations and editing views. Interface details and commands
- may differ; the guidance below describes the current workflow.
++Bring a video you like and tell the Agent what you want to make from it: your face, your product,
++a new audience, or another variation. Hypit gives it the production knowledge and tools to understand
++the reference, create the material, and compose an editable video.
## What you need
- A Coding Agent that can use skills, such as Claude Code or Codex.
- - A reference video or a creative brief.
-- A reference video.
++- A reference video or a description of the video you want.
## 1. Install the Hypit skill
@@@ -23,164 -16,45 +20,66 @@@
npx skills add hypit-ai/hypit -g
```
- Then start a Coding Agent anywhere; the Hypit skill is available globally. The Skill supplies
- production knowledge. The Agent checks whether the Hypit command is installed and sets up the
- executable tools when needed, explaining any setup that needs your choice.
-
- ## 2. Describe the video you want
-
- <video controls playsInline preload="metadata" width="100%" src="https://storage.googleapis.com/hypit-public-assets/quickstart/2026-09-09/describe_the_video_you_want.mp4"></video>
-
- Start with a reference to adapt or an idea to develop.
-
- ### Clone a reference video
-
- Ask the Agent to clone a video and provide its local file path:
-
- ```text
- /hypit clone this video: /path/to/video.mp4
- ```
-
- You can also provide a link from an online video platform. The Agent uses `yt-dlp` to download the
- source from supported sites. For example:
-Start a Coding Agent anywhere. The Agent installs the Hypit tools on first use.
++Open your video project in the Agent. The Skill supplies production knowledge; the `hypit` package
++supplies the executable tools. The Agent checks for an existing installation and helps prepare any
++missing tools. You do not need to clone the Hypit repository.
- ```text
- /hypit clone this video: https://www.youtube.com/watch?v=VIDEO_ID
- /hypit clone this video: https://www.instagram.com/reel/REEL_ID/
- ```
-
- Tell the Agent what should change, if anything: the host, language, product, aspect ratio, visual
- style or call to action. The Agent studies what makes the reference work and adapts its script, performances and visual
- relationships to your goal. You receive a finished video and an editable project.
-## 2. Clone a video and swap in your product
++## 2. Bring a reference and explain what should change
- ### Create an original video
-
- You can describe an idea just as you would brief a human producer. For example:
-Give the Agent a file or a link, and say what changes:
++Give the Agent a file or a supported platform link, together with any face, product or brand material:
```text
- Create a ranking video with a ranking board that has five rows. The left side labels the rows S, A, B,
- C and D, with a different color for each tier; the right side is for placing the icons assigned to
- each tier. Put Hypit in S tier and explain its advantages. Also include Arcads, Higgsfield, Seedance
- and CapCut. Give each competitor a fair, concise summary of its strengths and weaknesses. Make the
- result clear, energetic and suitable for a short social video.
-/hypit Clone this video: /path/to/video.mp4, and replace the product with Hypit (hypit.ai).
++/hypit Use this video as a reference: /path/to/video.mp4.
++Replace the product with Hypit (hypit.ai), keeping the energetic opening and ranking format.
```
- You can add constraints such as audience, duration, language, tone, brand colors, presenter, platform
- or aspect ratio. The Agent turns the brief into a complete plan and fills in production details from
- the information you provide.
-YouTube, Instagram and other platform links work; the Agent downloads the source. Change the host,
-product, language, aspect ratio or call to action in the same sentence.
++You can change the presenter, product, language, aspect ratio or call to action. The Agent studies
++what makes the reference work, including how graphics and captions land on particular words, then
++adapts the script and visual direction to your goal. It keeps its understanding and decisions in the
++project and explains the direction as the work develops.
- ## 3. Choose the services for your project
+ ### **👉 [Get 100 FREE AI Avatars with unique voices](https://drive.google.com/drive/u/2/folders/18J9Fz7mkU3OQNJ-2Res3eIyFQ2cemIK5)**
- <video controls playsInline preload="metadata" width="100%" src="https://storage.googleapis.com/hypit-public-assets/quickstart/2026-09-09/provide_credentials_when_the_agent_asks.mp4"></video>
-<video controls playsInline preload="metadata" width="100%" src="./quickstart/videos/clone_a_video_with_your_product.mp4"></video>
++<video controls playsInline preload="metadata" width="100%" src="https://storage.googleapis.com/hypit-public-assets/quickstart/2026-09-10/clone_a_video_with_your_product.mp4"></video>
- The Agent first checks the tools and services already available for this project. It explains any
- missing capability and helps you choose how to provide it. For a spoken reference, WhisperX supplies
- the transcript and word timings used to understand the video. The Agent checks for a local setup;
- if needed, it can help prepare one or use a hosted service you choose.
-## 3. Log in to Hypit, or bring your own keys
++## 3. Choose the services you want to use
- You can use your own provider accounts, or choose HypiHub for hosted transcription and generation
- through one account. Tell the Agent which services you already use and whether you prefer local
- setup or hosted tools. It opens login after you choose to connect that service. The recording shows
- the HypiHub login option.
-<video controls playsInline preload="metadata" width="100%" src="./quickstart/videos/log_in_to_hypit_or_bring_your_own_key.mp4"></video>
++The Agent checks the relevant tools and services already available. For a spoken reference, WhisperX
++provides the words and their timing so the Agent can relate the picture to what is being said.
++If it is missing, the Agent can help prepare it locally or explain the hosted option.
- Use the service's login or credential setup to connect your account. Credentials belong in the
- configured credential store, while the project records which services to use.
-When a model needs a credential, the Agent asks. One hypit.ai login covers every model Hypit hosts;
-or give the Agent API keys for the providers you prefer. Credentials go into the system credential
-store.
++[HypiHub](https://hypit.ai) offers hosted WhisperX and image, video and voice models through one
++account. You can also use your own keys with supported Providers, and combine local and hosted
++capabilities. The Agent explains what is needed and helps connect the services you choose.
- ## 4. Agree on the paid work
-## 4. Check the quote, then approve
++<video controls playsInline preload="metadata" width="100%" src="https://storage.googleapis.com/hypit-public-assets/quickstart/2026-09-10/log_in_to_hypit_or_bring_your_own_key.mp4"></video>
- <video controls playsInline preload="metadata" width="100%" src="https://storage.googleapis.com/hypit-public-assets/quickstart/2026-09-09/approve_and_submit_the_paid_build.mp4"></video>
-<video controls playsInline preload="metadata" width="100%" src="./quickstart/videos/check_the_quote_and_approve.mp4"></video>
++## 4. Agree on the cost and let production run
- Before using a paid service, the Agent explains the account, work to be performed and available
- pricing information. Agree on the production scope and budget, for example:
-Before spending anything, the Agent lists every paid request with its price. Approve, and it submits
-the Build:
++Before paid work, the Agent explains the selected account, planned work and available rates or
++estimated cost, including anything still unknown. Agree on the scope and budget; calls covered by
++that agreement can then proceed together. A change of account, scope or budget gives you a new decision.
```text
- Use my selected account to make this video, including transcription and media generation,
- within a total budget of $5. Keep me informed as it progresses.
-Go.
++Use my HypiHub account for this video, within the budget we agreed. Go ahead.
```
- Your authorization covers that agreed work as it proceeds. If you want only an analysis first,
- authorize that scope; the production can be priced once its direction is clear. An expanded scope,
- a different paying account or work beyond the budget brings a new decision back to you.
-
- The recording illustrates approving a production request. Actual prices and local or hosted
- processing depend on the services selected for your project.
-
- ## 5. Let the Agent produce the video
-
- <video controls playsInline preload="metadata" width="100%" src="https://storage.googleapis.com/hypit-public-assets/quickstart/2026-09-09/let_the_agent_do_the_production_work.mp4"></video>
-
- The Agent understands the reference in terms of your goal. Timed frames and words help it explain
- the story, pacing, and the purpose and timing of captions, B-roll and graphics. A replacement person
- or product shapes the script and creative direction from the beginning.
-
- It records the direction, writes the image and performance prompts, and arranges the references
- that connect the generated material. While independent generation is running, it can write the
- components and prepare the composition. Spoken material supplies the semantic timing for captions
- and graphics; wordless animation can use its own authored rhythm.
-
- With the actual material available, the Agent checks how the layout, motion and timing work together
- and refines the relevant components. Existing media stays available for reuse, and you receive
- updates about creative decisions, progress and problems.
-
- Builds save their completed media and outputs. If an attempt fails, the Agent explains what happened
- and uses available work in a new Run and Build, within the agreed scope.
-
- ## 6. Review the finished video
-
- <video controls playsInline preload="metadata" width="100%" src="https://storage.googleapis.com/hypit-public-assets/quickstart/2026-09-09/review_the_paid_result.mp4"></video>
-
- When the Build finishes, the Agent provides the final video and its saved location. Review the
- content, captions, transitions, framing and sound against your goal. Describe any changes you want;
- the project retains editable Sources and generated media.
-
- ### Explore the editable project in Studio
-
- <video controls playsInline preload="metadata" width="100%" src="https://storage.googleapis.com/hypit-public-assets/quickstart/2026-09-09/review_the_mock_studio.mp4"></video>
-
- Alongside the finished video, the Agent can open Studio to show the editable composition. Its
- Preview, Timeline and Inspector let you explore how the media, captions and graphics fit together.
-
- The recording shows the timeline and editing interface with placeholder media. In your project,
- the Agent opens a Run that selects your existing production material. If you are working remotely,
- a screenshot or short recording can introduce the project too.
-
- You can make a concrete request such as:
-
- ```text
- Bring the board in with the words introducing the ranking, and make the captions larger.
- ```
-
- The Agent changes the relevant source or component and checks the updated composition.
-
- ## 7. Request natural-language changes
-
- <video controls playsInline preload="metadata" width="100%" src="https://storage.googleapis.com/hypit-public-assets/quickstart/2026-09-09/request_natural_language_changes.mp4"></video>
-
- After a successful Build, you can continue directing the project conversationally. You may change
- the host, replace B-roll, alter the ranking-board treatment, translate the script, adjust the tone or
- switch the aspect ratio. For example:
-
- ```text
- Keep the script and ranking order, but replace the host with a calm male presenter and make the board
- look like a paper sports magazine.
- ```
-## 5. Watch the finished video
++<video controls playsInline preload="metadata" width="100%" src="https://storage.googleapis.com/hypit-public-assets/quickstart/2026-09-10/check_the_quote_and_approve.mp4"></video>
+
- The Agent traces each request to the relevant source and component, preserves what you asked it to
- keep, and reuses existing outputs. New paid generation follows your authorized scope.
++The Agent prepares the script, performance direction and image references to get the material right
++from the start. While generation runs, it can build the graphics and captions. Hypit keeps the
++execution and produced files in Build Results; the Agent reports progress as the work takes shape.
+
- ## 8. Create multiple variants in parallel
++## 5. Watch the finished video and make it yours
+
- <video controls playsInline preload="metadata" width="100%" src="https://storage.googleapis.com/hypit-public-assets/quickstart/2026-09-09/create_multiple_variants_in_parallel.mp4"></video>
++With the actual material in place, the Agent checks whether the layout, captions, graphics and
++B-roll appear clearly and at the right moments. It delivers the video and can open Studio so you
++can explore its timeline and edit supported properties.
+
- When you want several versions, first tell the Agent the dimensions that may vary. It will discuss
- the intended directions with you, for example:
++<video controls playsInline preload="metadata" width="100%" src="https://storage.googleapis.com/hypit-public-assets/quickstart/2026-09-10/watch_the_finished_video.mp4"></video>
- - one version with a different host;
- - one version translated into Spanish;
- - one version with a product-focused opening;
- - one version with faster cuts and denser B-roll.
-<video controls playsInline preload="metadata" width="100%" src="./quickstart/videos/watch_the_finished_video.mp4"></video>
++Keep talking to make changes or variants. Suitable existing material stays in use while the Agent
++changes the relevant script, component or placement. Your project remains editable in ordinary files.
- The Agent records the shared parts and each version's changes, then gives every variant explicit
- production choices. Independent work can execute concurrently within the Runtime's configured
- capacity; shared media can be reused. You receive each finished video, its project files and a clear
- account of completion.
-The Agent delivers the video and shows it to you in Studio. If you want changes, keep talking to the
-Agent.
++For more detail, see [Making videos with an Agent](./guide/skill.md),
++[Runs and Builds](./quickstart/run.md), and [Studio](./quickstart/preview.md).
diff --cc docs/quickstart/generation.md
index e6625f36,e6625f36..f1888ff5
--- a/docs/quickstart/generation.md
+++ b/docs/quickstart/generation.md
@@@ -119,9 -119,9 +119,10 @@@ Prompt-only generation. This is the onl
<seedance:TextVideo id="ambient" model="mini"
prompt={ambient-direction} duration="5" web-search="false"/>
```
--Craft requires every take to start from an accepted image, so a first frame or ordered references are
--the shapes to author with. This shape is documented because the model has it, not because a take
--should begin without a picture.
++For a recurring presenter, product or setting, authoring reference images first gives the video
++model a concrete visual direction. Reuse those references across takes, with the Script and action
++prompt directing each performance. TextVideo remains useful when the intended scene can be described
++directly without a particular visual identity to preserve.
### seedance:FrameVideo
diff --cc docs/quickstart/images.md
index 1f20b2d2,1f20b2d2..8efdd1a5
--- a/docs/quickstart/images.md
+++ b/docs/quickstart/images.md
@@@ -12,8 -12,8 +12,8 @@@ source of another operation
They all need an endpoint. `image-compose` and `image-transform` ask for the raster capability, which
`@hypit/provider-image-opencv-local` answers by running OpenCV in a bounded Python process on
your own machine; `background-removal` asks for its own capability, which `@hypit/provider-kie`
--answers remotely. No example in this repository binds either, so add the endpoint to your
--[Runtime Profile](/guide/runtime) before planning a Build that uses one.
++answers remotely. Select the supporting Endpoint in your [Runtime Profile](/guide/runtime)
++when using these operations.
## Composing layers
@@@ -100,3 -100,3 +100,20 @@@ that is the endpoint's business, not th
**Output:** `{cutout.image}` — typically fed to a Media Item so a presenter sits over the picture
rather than in a box.
++
++## Removing a moving person's background
++
++For a presenter over another picture, process the generated or supplied video with
++[`@hypit/volcengine-matting`](https://github.com/hypit-ai/hypit/blob/main/packages/volcengine-matting/README.md),
++served by a supporting HypiHub Endpoint:
++
++```svml
++<import as="matte" from="@hypit/volcengine-matting@1"/>
++<matte:Portrait id="cutout" source={performance.video}/>
++```
++
++Normalize `cutout.video` to prepare it for the timeline. If it establishes the spoken program,
++align that prepared media to its Script Segment and assemble it through Speech Track. Present the
++picture with Media Track or a project scene, at the chosen location and paint order. As B-roll,
++the normalized cutout can enter Media Track directly. Matting changes the picture's background;
++the composition determines its role.
diff --cc docs/quickstart/preview.md
index 503f1e4d,503f1e4d..6946e29d
--- a/docs/quickstart/preview.md
+++ b/docs/quickstart/preview.md
@@@ -1,81 -1,81 +1,82 @@@
---
title: Hypit Studio
--description: Open a satisfied Run, inspect its picture and timeline, and edit real author Sources.
++description: Explore a composition, its Sources and Results, and edit its timing and appearance.
---
# Hypit Studio
--Hypit Studio opens one `.svrun`, traces its Film or Render target back to explainable Semantic and Track projections, and presents four regions: Source at the upper left, Preview in the center, Inspector at the upper right, and Timeline below.
++Studio opens an editable video project in the browser. Play the composition, move through its
++frames, select words or graphics on the timeline, and change the properties a component exposes.
++It is also a useful way to hand over a finished project alongside the exported video.
--Studio opens the composition selected by the Run, using project files and completed Build Outputs.
--Use `<build-record>` and `satisfy` to keep the material being edited. Studio can ask the selected
--Runtime Profile to perform media operations such as inspection and normalization when the Provider
--supports transient authoring. Generation and Build submission use the CLI; Studio provides playback,
--semantic navigation and edits to the actual Sources.
++## Open the work you want to edit
```bash
--hypit-studio --run examples/ranking-football/swap-effect-banana/studio.svrun \
-- --workspace examples/ranking-football/swap-effect-banana
--# ➜ http://localhost:5179/
++cd /path/to/my-video
++hypit-studio --run build.svrun
```
--| Argument | Meaning |
--| --- | --- |
--| `--run <build.svrun>` | Run Source to open. Required. |
--| `--runtime <hypit.runtime.json>` | Runtime Profile used for transient media execution and active `BuildView` information. Historical Results and `<build-record>` still come from the project Result Repository. |
--| `--workspace <directory>` | Source access and writeback boundary; defaults to the Run directory. |
--| `--port <number>` | HTTP port; defaults to `5179`. |
--
--The unit of work is the Run, not an isolated `.svml`. The Run chooses the Author Source, targets and Candidates. Every Studio recompile continues to use that same Run instead of selecting another set of material in the background.
--
--## Which Runs can open
--
--Studio requires:
--
--- a real Film or Render target;
--- a traceable Semantic Track and display Tracks;
--- explicitly selected material Candidates;
--- a display closure completed by deterministic Producers and transient capabilities declared by their Providers.
++Open the address printed by the command. Studio uses the Author Source and material selected in
++that Run. To keep generated material while editing, select completed Outputs with
++[`build-record` and `satisfy`](./run.md#reusing-results).
--Studio refuses a Run that supplies only an opaque finished movie or whose display graph still requires external generation. It edits the current author graph and Tracks; it does not reconstruct a project from final pixels.
--
--A project file can satisfy an output directly. A result from an earlier Build can be reused through `<build-record>`:
--
--```svml
--<file id="take-1" type="@hypit/artifact@1#BlobArtifact"
-- from="./assets/take-1.mp4" media-type="video/mp4"/>
--<satisfy output="take-opening.video" candidate="take-1"/>
--```
--
--## The four regions
++| Argument | Use |
++| --- | --- |
++| `--run <file.svrun>` | Select the Run to open. |
++| `--runtime <profile.json>` | Select a Runtime Profile; otherwise use the project's saved Runtime selection. |
++| `--workspace <directory>` | Set the project boundary for Source access and edits. |
++| `--port <number>` | Request a browser-server port; the default is `5179`. |
--### Source
++The selected target must lead to one Film and its time source. A spoken performance supplies a
++SemanticTrack; an animation can supply an authored ProgramSpace. Both support visual components and
++property editing. The material needed to display the composition must already be available through
++the Run. Studio can perform media preparation supported by the selected Runtime; submit generation
++and encoded renders through `hypit build`.
--The upper-left pane shows the current Author SVML with line numbers, highlighting, synchronized selection and text editing. It is not yet a complete Source workspace; browsing related SVS, SVRun, tasks and artifacts remains under separate design review.
++## Explore the project
--### Preview
++The library at the left has three views:
--The center pane uses real material and a HyperFrames picture. Structure, Frames, padding, stacking, motion and Track layout come from the same domain programs used by a Build, not from a Studio approximation.
++- **Source** lists the selected Run and its Author and Recipe files. Select a file to inspect or edit it.
++- **Tasks** shows completed project Builds and, with a selected Runtime, active execution information.
++- **Artifacts** lets you inspect public files retained in Build Results.
--### Inspector
++Choosing an Artifact opens it for inspection. To use it in the composition, update the Run's
++Candidate selection. This keeps the material choice in the editable project.
--The upper-right pane shows the current entity's origin, timing, operations and adapter-exposed author parameters. Writable fields carry exact Source ranges. Values without one unambiguous write target remain read-only.
++## Picture, timeline and Inspector
--### Timeline
++The central Preview draws the composition with HyperFrames. It uses the same component layout,
++media sampling and motion as an encoded render. Check the actual picture when adjusting caption
++placement, graphic emphasis or coverage.
--The lower pane places Semantic Segments, Words, Selections, Moments and component Tracks in one frame domain. Clicking selects and seeks; transport, frame stepping, zoom and scrolling are available. Move and trim are enabled only when an adapter declares the gesture and Studio resolves one author target.
++The Timeline shows component appearances on a shared clock. A semantic composition also shows
++Segments, Words, Selections and Moments. Select an entity to seek to it; playback, frame stepping,
++zoom and scrolling help examine a particular transition or layout.
--## How edits return to Source
++The Inspector shows the selected entity's properties. Editable fields and timeline handles depend
++on the component's **Studio Companion**, which describes the component to Studio. A project component
++can supply its own Companion alongside its rendering code. Renderability and the available editing
++controls are separate: a field or gesture needs a clear source value to change.
--Studio exposes two structured author mutations:
++## Make an edit
--- timeline gestures submit `timeline.adjust`;
--- Inspector fields submit `parameter.adjust`.
++Source edits change the selected `.svml`, `.svs` or `.svrun` file. Supported Inspector changes and
++timeline gestures write to the corresponding author value, then recompile the same Run.
++Moving a shared Selection or Moment changes its position in the Script, so all consumers follow
++that change. Editing a shared Frame or Recipe can likewise affect several appearances.
--They follow the executed lineage selected by the Run to a real SVML or SVS preimage. Studio recompiles with the same Run after a change. It publishes the new picture only on success; on failure it restores the files and reports the domain error. It creates no hidden Build, submits no generation, and never turns a Selection into an anonymous frame span.
++Check the save status after an edit. If recompilation fails, Studio reports the error and restores
++the previous files. Use Apply or Reset for a structured Inspector draft. The Run and loaded Source
++files are watched; restart Studio after changing installed packages, component code or Runtime
++selection so those changes are loaded too.
--The complete selection, projection, consumption and writeback model is documented in [Studio Temporal Lineage](../guide/studio-temporal-windows.md).
++## Sound and delivery
--## Sound
++Preview playback includes the AudioTracks selected in Film, such as speech, music and effects.
++The exported video's audio is assembled by the render's media pipeline. Deliver the encoded video;
++Studio lets the recipient explore the editable composition as well.
--HyperFrames owns the picture; the media pipeline assembles programme audio at the end. Studio may play the real Speech Track audio while previewing so B-roll can be judged against speech. Visual material without explicit audio is not given sound automatically.
++For component authors, [Studio Temporal Lineage](../guide/studio-temporal-windows.md) explains semantic
++editing, and the [Companion SDK](https://github.com/hypit-ai/hypit/blob/main/packages/studio-adapter/README.md)
++explains how to expose component entities and controls.
diff --cc docs/quickstart/run.md
index e291c011,e291c011..d309bbe5
--- a/docs/quickstart/run.md
+++ b/docs/quickstart/run.md
@@@ -247,7 -247,7 +247,17 @@@ a Profile from a conventional filename
`check` and `plan` never make live Provider requests. A graph-only `plan` without a selected Runtime
needs no deployment credentials; with a selected Runtime, its cheap preflight checks that demanded
credential references are present. Before `doctor` or a paid/external `build`, configure only the
--variables referenced by the selected Runtime Profile:
++credentials referenced by the selected Runtime Profile. First inspect the existing selection:
++
++```bash
++hypit auth status
++```
++
++If a needed service is not ready, choose whether to configure that service or another supported
++local or hosted option. For example, WhisperX can run locally or through HypiHub. A starter Endpoint
++is a configuration starting point, not evidence that an account was chosen.
++
++After choosing a service, connect its credential:
| Variable | Provider/use |
|---|---|
@@@ -258,8 -258,8 +268,6 @@@
Run only the lines for the Endpoints in your Profile. In macOS/Linux shells:
```bash
--read -r -s HYPIHUB_API_KEY
--export HYPIHUB_API_KEY
read -r -s KIE_API_KEY
export KIE_API_KEY
read -r -s MIMO_API_KEY
@@@ -269,7 -269,7 +277,6 @@@ export MIMO_API_KE
In Windows PowerShell:
```powershell
--$env:HYPIHUB_API_KEY = "your-key"
$env:KIE_API_KEY = "your-key"
$env:MIMO_API_KEY = "your-key"
```
@@@ -277,6 -277,6 +284,28 @@@
Keep credentials out of Author Source, Run Source, Runtime Profile source, and committed files.
`doctor` validates required credential presence without printing secret values.
++## Read prices for the selected Run
++
++```bash
++hypit pricing reference.svrun
++hypit pricing reference.svrun --json
++```
++
++The selected Runtime determines which Endpoint serves each request. `pricing` reads those Providers'
++rate information and groups matching requests, showing known parameters and request counts. Work
++explicitly declared local without a Provider charge is summarized; unknown prices, unsupported
++requests and failed price reads remain visible. `--verbose` includes the local request details and
++original pricing documents.
++
++Use the report to explain the intended spend: the chosen account, planned material, published units
++and applicable rates. The command reads prices; it does not submit generation or calculate a guaranteed
++total. A future media input may not yet have a known duration, so preserve that uncertainty in the
++estimate. JSON keeps request parameters in `groups[].requests` and source material in
++`groups[].pricingDocuments`.
++
++Agree on the account, work and budget before paid calls. Existing authorization covers the work
++within that agreement; pricing output and successful authentication are information, not approval.
++
## Build workflow
Keep credentials, generated media, Runtime data and logs out of commits. A project may live anywhere:
diff --cc docs/quickstart/timing.md
index 887d2ed3,887d2ed3..15c58854
--- a/docs/quickstart/timing.md
+++ b/docs/quickstart/timing.md
@@@ -5,19 -5,19 +5,26 @@@ description: Per-take normalization an
# Timing & Assembly
--Hypit's timing authority is a `SemanticTrack`. Build it in segment-sized pieces:
++For spoken video, a `SemanticTrack` connects the authored Script to the actual performance. This is
++the natural time source for captions, word-triggered graphics and coverage. Build it in segment-sized pieces:
1. normalize each accepted A/V take into one exact frame domain;
2. align that normalized media with its authored Script Segment to create a self-contained `SemanticTake`;
3. assemble the Semantic Takes in program order with `speech:Track`.
--Every Take is already semantic before it enters the Track.
++Every Take is already semantic before it enters the Speech Track. Pictures can be presented by
++Media Track or a project component independently of this semantic and audio assembly.
++
++A purely visual animation can instead declare its own duration and frame rate in a ProgramSpace.
++See [an authored film clock](./composition.md#a-film-drawn-entirely-by-components). It can use seconds
++or frames for events; spoken work can use Script Selections and Moments for the same visual behavior.
```svml
<import as="program" from="@hypit/program-space@1"/>
<import as="pipeline" from="@hypit/media-pipeline@1"/>
<import as="whisperx" from="@hypit/whisperx@1"/>
<import as="speech" from="@hypit/speech-track@1"/>
++<import as="media-track" from="@hypit/media-track@1"/>
<import as="space" from="@hypit/spatial@1"/>
<import as="recipes" source="./recipes.svs"/>
```
diff --cc docs/quickstart/tracks.md
index 642f3df6,959b7ec1..06aed460
--- a/docs/quickstart/tracks.md
+++ b/docs/quickstart/tracks.md
@@@ -417,7 -417,7 +417,7 @@@ A direct child of the stack, self-closi
|---|---|
| `source` | required — a still image, a Synchronized Medium, or a Compositable Surface |
| `extent` | required for a still image and refused for anything else |
--| `at` | required — the Moment the card is dealt on |
++| `at` | required — the reveal event: a Moment or an authored time such as `2s` or `12f` |
| `appearance` | optional — its own Recipe, otherwise the stack's |
| `label` | optional — a `deck:Label` record |
@@@ -447,7 -447,7 +447,7 @@@ effect bound to its own window
<import as="screen" from="@hypit/screen-overlay@1"/>
```
--`screen:Track` takes `id`, `canvas` and `space`. Its children are the effects, at least one, each
++`screen:Track` takes `id`, `canvas` and one time source: `semantic` or `space`. Its children are the effects, at least one, each
empty, each with a required `z` for stacking order and a window that is one of:
| Window | Written |
@@@ -457,7 -457,7 +457,7 @@@
| A Moment, for a length | `at={story.moment.x} for="12f"` on an item whose Track has `semantic={speech.semantic}` |
| An explicit span | `start="…" end="…"`, optionally against a `selection=` or `moment=` |
--The Track takes `id`, `canvas` and `semantic`. Lengths are `12f`, `250ms` or `1.5s`. A Selection
++Lengths are `12f`, `250ms` or `1.5s`. A Selection
names one contiguous interval and a Moment names one point; author another item when an effect should
appear again.
diff --cc docs/zh/guide/author-packages.md
index 786067bd,786067bd..edff98b3
--- a/docs/zh/guide/author-packages.md
+++ b/docs/zh/guide/author-packages.md
@@@ -1,230 -1,230 +1,49 @@@
---
--title: 添加 Author 包
--description: 添加新的作者层组件的分步指南。
++title: 添加作者包
++description: 制作项目组件、将其用于视频,并在有需要时分享。
---
--# 添加 Author 包
++# 添加作者包
--作者包用一个新组件扩展视频词汇。作者在自己的 `.svml` 源码里通过 `<import>` 和 XML 元素来使用它。无需改动 Core、CLI 或任何聚合包。
++创建组件是制作视频的一部分。从场景需要的行为出发:哪些内容共同出现,哪些内容会变化,由什么事件驱动。普通素材呈现可以使用 Media Track;一个播放中的视频移到侧面、同时让出空间展示流程图,可以属于同一个项目组件,独立字幕继续分开。
--## Style-like Surface 的公开 id
++## 从完整的包开始
--如果 Surface 发布的是 Style-like 值,公开 Record 必须使用作者写下的裸 id(`${id}`),不能写成
--`${id}.style` 或 `${id}.value`。Author Source 也使用裸 id,例如 `style={board-style}`;只有真正
--独立的 Track 等输出才使用 `.track` 一类后缀。
++安装的 `hypit` Distribution 包含 [`examples/minimal-author-package/packages/example-component`](https://github.com/hypit-ai/hypit/tree/main/examples/minimal-author-package/packages/example-component)。将该目录复制到视频项目的 `packages/`,把包名与 Module 改为自己的 scope 和名称,将示例中的 `workspace:*` Hypit 开发依赖改成项目所用的 Distribution 版本。
--## 1. 创建包
++在复制后的包目录执行:
```bash
--mkdir -p packages/my-component/src packages/my-component/test
++npm install --save-dev hypit@<selected-release>
++npm run build
```
--在视频项目中创建它,并从一开始使用所有者自己的 scope;`@hypit/*` 由当前 Distribution 拥有。
--
--## 2. 编写 package.json
--
--```json
--{
-- "name": "@your-studio/my-component",
-- "version": "0.0.0-dev",
-- "private": true,
-- "type": "module",
-- "files": ["dist", "preview", "README.md"],
-- "exports": { ".": "./dist/index.js" },
-- "hypit": {
-- "activation": "./dist/activation.js"
-- },
-- "devDependencies": {
-- "hypit": "^0.1.0",
-- "typescript": "^5.9.0"
-- }
--}
--```
--
--开发时使用公开的 `hypit/*` subpath,发布物只包含组件自己的编译文件。分层规则参见
--[包架构](./packages.md)。
--
--## 3. 定义 Module Manifest
--
--在 `src/index.ts` 中声明你的 Module 的身份、Type 和 Producer:
--
--```typescript
--import type { ModuleManifest, ModuleRef } from "hypit/author-kit";
--
--export const myComponentModuleRef: ModuleRef = {
-- name: "@your-studio/my-component",
-- version: "1",
--};
--
--export const myComponentManifest: ModuleManifest = {
-- format: "hypit.module@1",
-- name: myComponentModuleRef.name,
-- version: myComponentModuleRef.version,
-- dependencies: [],
-- types: [ /* your nominal Types */ ],
-- capabilities: [],
-- producers: [ /* your deterministic Producers */ ],
--};
--
--export const myComponentMarkupSurfaces = [{
-- name: "widget",
-- tag: "Widget",
-- mode: "structured",
-- outputs: [ /* 这段语法可以创作的 Type */ ],
-- vocabulary: { /* 这个元素是什么、长什么样 —— 见第 5 步 */ },
--}] as const;
--```
--
--Type 在名义上归属于 Module。Core 并不维护一个包含所有领域类型的中央联合类型 —— 安装一个新包就能添加新的 Type,无需发布新的 Core 版本。
--
--## 4. 实现 Surface handler
--
--Surface handler 把 Markup Frontend 的 XML 元素解码成带类型的作者声明。
--
--```typescript
--// src/surface.ts
--import type { StructuredSurfaceHandler } from "hypit/author-kit";
--
--export const decodeMyComponentSurface: StructuredSurfaceHandler = ({ element }) => {
-- // Read attributes and children from the XML element
-- // Validate inputs
-- // Emit typed Records and Operations into context
-- // Return authored graph declarations
--};
--```
--
--通用包不要从业务包源码推断写法。使用仓库内的最小完整 fixture:
--`examples/minimal-author-package/packages/example-component/`。它包含完整的
--Surface 返回值、Fragment literal、Manifest ports、Producer 和 activation 形状。
--只有 `hypit vocabulary` 已证明存在高度相似的结构性 sibling 时,才允许读取该
--sibling 的 README 和实现所需的少数 role 文件,并将其复制为新的 Module;不得比较无关业务包。
--
--## 5. 声明 Surface 词表与预览图
--
--`vocabulary` 是这个元素自我说明的地方。创作者要读它,任何不去翻源码、只检视已安装包的工具也要读它。一个没有词表的 Surface 是合法的,同时也是不可见的:下一个碰到你这个元素的人,手上只有一个标签名。
--
--```typescript
--// src/manifest.ts
--import { readFile } from "node:fs/promises";
--
--const previewImage = (file: string) => ({
-- mediaType: "image/png",
-- path: `preview/${file}`,
-- open: async () => Uint8Array.from(await readFile(new URL(`../preview/${file}`, import.meta.url))),
--});
--
--vocabulary: {
-- summary: "一句话说明这个元素产出什么、被放在什么之上。",
-- appearance: "观众实际看到的东西,包括它如何进入、如何保持、如何离开。",
-- preview: previewImage("Widget.png"),
-- attributes: [
-- { name: "id", kind: "identifier", required: true, summary: "为这个 Widget 命名。" },
-- ],
-- children: [ /* 接受的子元素 */ ],
-- ports: [ /* 声明的边 */ ],
-- example: "<mine:Widget id=\"first\"/>",
-- notes: [ /* 读者不看就只能靠报错发现的规则 */ ],
--}
--```
--
--凡是读者应该在 Studio 时间轴或目录里一眼认出的 Surface,都要声明 `preview`:它是海报。海报是设计出来的图,不是产出的一帧。它用这一小块位置所允许的最抽象、最形象的方式说明组件是什么,就像电影海报不是电影截屏:`@hypit/ranking` 的 Column 海报是一列名次徽章挨着一列图标,Tier 榜是带字母的几行加图标。把它画成 SVG 随包提交,栅格化成 manifest 在 `preview/` 下指名的 PNG,组件外观演进时海报保持稳定。没有可展示产出的 Surface 可以不声明,例如只负责装配请求的那种。
--
--`appearance` 和 `preview` 回答的是两个不同的问题,谁都替代不了谁:`appearance` 说的是这个元素在所有情况下都会画出什么,海报说的是这个元素是干什么的。
--
--完整词表和预览声明以最小 fixture 为权威示例。`hypit vocabulary <package>` 打印已安装包的公开声明;从这份输出写作,而不是打开别的业务包源码。
--
--## 6. 编写 activation 描述符
--
--```typescript
--// src/activation.ts
--import { createMarkupSurfaceHostFacet } from "hypit/author-kit";
--import {
-- myComponentManifest,
-- myComponentMarkupSurfaces,
-- myComponentModuleRef,
-- decodeMyComponentSurface,
--} from "./index.js";
--
--export const hypitPackage = {
-- format: "hypit.node-package@1" as const,
-- modules: [{
-- manifest: myComponentManifest,
-- }],
-- hostFacets: [
-- createMarkupSurfaceHostFacet({
-- module: myComponentModuleRef,
-- declaration: myComponentMarkupSurfaces[0],
-- handler: decodeMyComponentSurface,
-- }),
-- ],
--};
--
--export default hypitPackage;
--```
--
--Module 会自动提供精确的 `[email protected]`,所以作者直接导入 `@your-studio/my-component@1`,无需再声明一份重复别名。只有包确实拥有另一个逻辑名称时才使用可选的 `specifiers`。Surface declaration 决定可接受的标签(以 `mine` 导入时即为 `<mine:Widget>`)。它属于 Markup Host facet,不属于语义 Module Manifest,更不属于 Core。
--
--## 7. 编译包
--
--```bash
--pnpm build
--```
++示例提供 TypeScript 构建配置、Manifest、Surface、Fragment、Producer、activation 和小型 preview Source。[包的 README](https://github.com/hypit-ai/hypit/blob/main/examples/minimal-author-package/packages/example-component/README.md) 介绍准确文件与设置。项目可以用普通包管理器的 workspace 或本地包依赖安装组件。
--框架声明从 `hypit/author-kit` 导入;组件使用的领域值从 `hypit/composition` 等所属
--subpath 导入。加载 activation 时由当前 Distribution 提供这些 API,组件 tarball 不携带另一份 Hypit。
++## 给组件有用的接口
--## 8. 安装
++公开另一个视频作者真正会改的决定:内容、素材、位置、外观和有意义的事件。转场可以接收一个 Moment,决定何时改变布局;接收一个 Selection,决定整个场景何时存在。纯动画则可以接收作者指定的事件时间。将这些输入投影到选定时钟,再按得到的调度绘制场景。
--```bash
--pnpm install --frozen-lockfile
--```
--
--包管理器负责安装、版本与完整性。Author 或 Run Source 导入逻辑能力时,Hypit 才会加载对应包;Manifest 声明的精确 Module 依赖从该包的已安装依赖中加载。
++呈现已有说话表演时,消费它的 SemanticTrack,让画面采样与口播使用相同的 Take 和素材位置。其他视频输入以归一化媒体进入时间线。[响应式讲解场景](https://github.com/hypit-ai/hypit/tree/main/examples/semantic-composition/packages/responsive-explainer) 展示持续播放的视频如何在 HTML 场景里从全屏移到侧边竖屏。[聊天示例](https://github.com/hypit-ai/hypit/tree/main/examples/semantic-composition/packages/chat-scene) 展示同一个事件接口如何接受作者时间或 Script Moment。
--## 9. 在 Author Source 中使用
++Style 一类 Surface 在裸作者 id 下公开其值,例如 `style={board-style}`;独立输出可以使用 `.visual`、`.audio`、`.track` 等有意义的后缀。在组件自己的 vocabulary 和 README 中说明名称与可用值。
--```xml
--<?svml using="@hypit/markup@1"?>
--<svml>
-- <import as="mine" from="@your-studio/my-component@1"/>
++## 实现并查看场景
-- <mine:Widget id="demo" during={story.selection.example}/>
--</svml>
--```
++作者包 API 使用 `hypit/author-kit`,消费的领域值使用对应公开子路径。[组件结构](./component-anatomy.md) 介绍 Manifest、Surface、Fragment 和 Producer 如何配合。项目文案与素材作为输入,组件自己的面板、边框与装饰由实现绘制。
--`<import>` 只会 activate 作者词汇。它绝不授予网络、文件系统或凭据权限。
++preview Source 为作者提供可打开或渲染的小例子。查看能说明行为的状态:进入、关键变化、停留布局和退出。也要在实际编排中查看,这时内容、空间和时机才有具体用途。
--## 10. 保留或分享同一份包
++需要更丰富的交互编辑时,可以添加 Studio Companion。[Companion SDK](https://github.com/hypit-ai/hypit/blob/main/packages/studio-adapter/README.md) 介绍如何公开时间线实体、属性和 Source 绑定。绘制代码和 Companion 是同一个包中分别提供的贡献。
--创建这个包是正常的视频制作工作。只有当前视频需要它时,就把它作为私有包保存在项目的
--`packages/` 中。所有者希望其他项目使用时,编译同一份包,再通过版本化的 `npm pack` tarball
--直接交付,或发布到所有者自己的 npm scope 或私有 registry。使用方通过自己的包管理器安装选定
--版本并提交 lockfile;只要逻辑接口保持兼容,Source 中的 Module import 就不需要变化。
++## 使用与分享
--公开发布时,移除 `private: true`,并补充普通的 npm 发现与归属信息:
++在 Source 中导入已安装组件的逻辑 Module:
--```json
--{
-- "description": "A speech-timed score strip for Hypit videos.",
-- "keywords": ["hypit", "hypit-author-package", "scoreboard"],
-- "repository": {
-- "type": "git",
-- "url": "git+https://github.com/studio/score-strip.git"
-- },
-- "license": "MIT"
--}
++```svml
++<import as="mine" from="@your-studio/my-component@1"/>
```
--README 应包含可直接使用的 Source 示例、公开输出、组件的视觉证据,以及验证时采用的 Hypit
--版本。安装后,`hypit vocabulary <package>` 会读取所选版本自己的 Surface 声明。包的发现、发布、
--版本和完整性继续由 npm 或选定的私有 registry 负责;只有 Source 导入了某个逻辑能力时,Hypit
--才加载对应包。
--
--## 实现分流
--
--没有高度相似 sibling 时,只读规范文档、已安装包的 vocabulary 输出和
--`examples/minimal-author-package/packages/example-component/` fixture。
++将它声明的元素与输出用于编排。`hypit vocabulary` 展示作者接口,`hypit check` 检查 Source 或 Run。组件 README 应包含可复制示例、输出、实用的创作选择和行为示意图。
--当 vocabulary 证明输入/输出 Type、timing contract、终端 Track 和 Surface ports 高度相似,
--才可走 close-sibling 路径:读取该 sibling 的 README 与必要 role 文件,复制结构,重建
--Module/Producer identity,并直接检查 Source 使用方式与 preview 结果。
++组件服务于当前作品时,就与项目一起保存。需要分享时,选择发布版本,编译并用 `npm pack` 打包代码和素材,或通过所有者自己的 scope 发布到 npm 或私有 Registry。发布到 Registry 时去掉 `private: true`,补充普通包元信息。使用者安装选定版本并提交包管理器 lockfile。使用组件不需要 Hypit 仓库 checkout,也不需要向主仓库提 PR。
diff --cc docs/zh/guide/component-anatomy.md
index 00000000,00000000..a7e3ebca
new file mode 100644
--- /dev/null
+++ b/docs/zh/guide/component-anatomy.md
@@@ -1,0 -1,0 +1,43 @@@
++---
++title: 组件结构
++description: 将场景的创作接口变成可复用的图贡献。
++---
++
++# 组件结构
++
++组件把作者面对的创作想法与具体实现连接起来。对于榜单,这个想法可以是“说到每个候选时介绍它,再让图标移动到对应排名位置”。输入表达这些关系,代码完成绘制和运动。
++
++[添加作者包](./author-packages.md) 提供完整可构建的起点。[Ranking](https://github.com/hypit-ai/hypit/blob/main/packages/ranking/README.md) 则展示更丰富的语义事件、持久视觉状态和 Studio Companion。
++
++## 实现中的职责
++
++这些职责可以按组件规模组织到合适的文件中:
++
++| 部分 | 职责 |
++| --- | --- |
++| Manifest 与 Types | 命名包提供的值、Producer、输入和输出 |
++| Surface | 读取作者元素,解析明确输入 |
++| Fragment | 描述输入到输出之间的操作与依赖 |
++| Producer | 完成声明的计算 |
++| 值与样式辅助函数 | 验证输入、应用已说明的默认值、解析接受的 Recipe 属性 |
++| 调度与绘制 | 投影事件,并在每一帧绘制场景 |
++| Activation | 公开所选包提供的贡献 |
++| Studio Companion | 描述时间线实体与可编辑属性 |
++
++精确对象形状由 [Author SDK](https://github.com/hypit-ai/hypit/blob/main/packages/author-kit/README.md) 和随包示例维护。小组件可以把相关职责放在一起;大组件则可以分离可复用的调度、样式和绘制逻辑。
++
++## 围绕关系设计
++
++对于说话视频,接受 Selection 和 Moment 来表达随词语发生的行为。表演产生后,投影提供准确区间与时刻。作者决定节奏的动画可以使用秒或帧;`12f` 这样的时长在两种情况下都能表达一次转场的长度。
++
++素材呈现、空间布局与时间各有自己的输入。归一化视频提供可采样素材,SemanticTrack 可以提供准备好的表演及其素材位置。Frame 定位场景,内部 HTML/CSS 或元素树协调视频、文字、遮罩和图形。共享行为的内容组织在一起,独立贡献可以继续作为具有自己绘制顺序的 Track。
++
++字幕组件可以沿用已有字幕文档、样式选择与语义时间。细粒度字幕族能表达的样式可以直接使用;新的样式族则可以消费相同字幕关系,绘制不同的视觉呈现。
++
++## 让另一个作者用得好
++
++从创作决定命名参数:出现事件、内容、位置、外观。说明默认值和覆盖后改变什么。Style 解码器接收 `{ path, properties }` 形状的 SVS Recipe 与明确字体资源,Source 通过作者 id 引用 Style。
++
++具体视频的文案和媒体作为输入。组件绘制自己的图形结构,也可以携带可复用字体或图标等资源。示例 Source 展示关键状态,包括换内容或改变事件时间后的行为。
++
++包的 README 与 vocabulary 帮助作者选择和使用组件。Studio Companion 可以为含义明确的 Source 值添加编辑手柄。新的视觉行为在组件包内实现;图需要外部执行时,由 Provider 完成。
diff --cc docs/zh/guide/conventions.md
index 42e40fc3,42e40fc3..84e285bb
--- a/docs/zh/guide/conventions.md
+++ b/docs/zh/guide/conventions.md
@@@ -5,6 -5,6 +5,8 @@@ description: 命名、模块边界、Ty
# 代码规范
++这些规范面向 Hypit 仓库内的工作。项目扩展使用所有者自己的 scope 和公开的 `hypit/*` SDK 子路径,见 [包与扩展](./packages.md)。
++
## 命名
| 项目 | 约定 | 示例 |
@@@ -18,7 -18,7 +20,7 @@@
## 模块边界
--- 每个包有且只有一个公开入口点:`src/index.ts`。
++- 包通过 `package.json` 的 exports 声明公开入口;`src/index.ts` 是常见的工作区入口。
- 内部模块使用显式的 `.js` 扩展名(NodeNext 解析)。
- 跨包导入使用 `@hypit/*`,绝不跨包边界使用相对路径。
- 禁止生产依赖形成循环。
@@@ -43,8 -43,8 +45,8 @@@
- 所有持久化数据使用 `@1` wire 格式版本。
- 项目自有的 Module 与 Frontend 身份统一使用逻辑版本字面量 `1`。
--- 工作区 `package.json` 在真正发布前保持 `0.0.0-dev`;它是物理包元数据,不是逻辑协议身份。
--- 真正的可执行实现身份来自锁定后的包字节与闭包摘要,而不是以上任意一个版本字符串。
++- 包版本通过 npm 或 pnpm 选择物理发行,与逻辑 Module 和 Frontend 接口版本分别表达。
++- 包管理器和 lockfile 负责固定安装版本及其依赖。
- wire 类型定义在 `@hypit/protocol` 中,且不可变。
- Nominal Type 由 Module 拥有,不在中心化的联合类型中注册。
- 类型 schema 使用与 JSON 兼容的结构,而不是 TypeScript 接口。
@@@ -53,5 -53,5 +55,5 @@@
- 编译失败时抛出带有描述性信息的错误,其中包含源码位置。
- 运行时失败在 Build 状态机中记录为 Operation 失败。
--- 可恢复的失败会在 Scheduler 资源准入后按照 Endpoint 策略触发重试。
--- 致命失败会让 Build 转入终止状态。
++- 服务协议允许的有限传输重试由 Provider 负责。
++- 执行尝试失败会结束 Build;后续工作使用新的 Run 与 Build,显式选择已完成 Output 复用。
diff --cc docs/zh/guide/develop.md
index e4364817,e4364817..2a65b2cb
--- a/docs/zh/guide/develop.md
+++ b/docs/zh/guide/develop.md
@@@ -9,7 -9,7 +9,7 @@@ description: 开始 Hypit 开发工作�
| 工具 | 版本 | 用于 |
|---|---|---|
--| Node.js | 22+ | 所有工作 |
++| Node.js | 22.12+ | 所有工作 |
| pnpm | 10.33.x | workspace 管理;由根目录 `packageManager` 字段选择 |
| Python | 3.10–3.13 | 本地 WhisperX 与 OpenCV Managed Program |
| uv | latest | Python 环境管理 |
@@@ -52,10 -52,10 +52,10 @@@ hypit
| 指南 | 主题 |
|---|---|
--| [Hypit Skill 架构](./skill.md) | 四条路径的入口、工具、路由和持久化 JSON 状态 |
--| [包架构](./packages.md) | 分层、依赖规则、包的构成、facets |
++| [与 Agent 一起制作视频](./skill.md) | 创作方向、服务选择与可编辑项目 |
++| [包与扩展](./packages.md) | 组件、模型与服务的职责,安装与分享 |
| [添加 Author 包](./author-packages.md) | 分步说明:新增组件、Surface、词表与预览图、activation |
--| [添加 Provider](./providers.md) | 分步说明:新增 Endpoint 适配器 |
++| [模型与 Provider](./providers.md) | 选择账户与 API,开发 Model 或 Provider 包 |
| [Runtime](./runtime.md) | Profile、Workspace、执行与生命周期边界 |
| [测试](./testing.md) | 测试运行器、写法、示例、boundary tests |
| [代码规范](./conventions.md) | 命名、模块边界、wire 数据、TypeScript 配置 |
diff --cc docs/zh/guide/packages.md
index cab583a3,cab583a3..29f3b99f
--- a/docs/zh/guide/packages.md
+++ b/docs/zh/guide/packages.md
@@@ -1,273 -1,273 +1,46 @@@
---
--title: 包架构
--description: 七个分层、依赖边界、包的结构与 facet。
++title: 包与扩展
++description: 视频项目如何通过普通包选择组件、模型和服务。
---
--# 包架构
++# 包与扩展
--`packages/` 下的内部模块被组织成七个架构分层。每个模块自行声明依赖。发布的 `hypit` Distribution
--包含完整官方模块树,让 Package Loader 能解析任意被显式选择的包;但 TypeScript 不维护会掩盖漏依赖的中央路径别名。
++Hypit 把视频需要什么,与哪些代码和服务完成它,分别表达。新的图形、模型或 API 来源可以由包提供,再由项目选择。每个包拥有自己的接口和实现,执行系统负责运行它们组成的依赖图。
--这里的完整官方树指首方源码/代码,并不意味着首次安装就下载全部上游依赖。基础 npm 安装只带
--启动器必需依赖;显式 `runtime up` 才会把所选 Runtime Adapter 的普通 npm 依赖准备到机器共享
--目录。Fontsource 等作者侧可选素材由编译器给出精确的 `hypit packages install` 命令。npm 的标准
--`package.json` 是唯一包集合依据;Hypit 不再造第二份 lock、receipt 或哈希库存。项目自己的第三方
--组件及依赖仍由项目包管理器负责。
++## 各部分的职责
--## 七个分层
++| 部分 | 职责 | 在哪里选择 |
++| --- | --- | --- |
++| 作者组件 | 将作者输入转成素材请求、视觉行为或其他图输出 | Source 导入 |
++| Model | 定义明确的生成请求与输出 | Source 导入 |
++| Provider Endpoint | 通过 API 或本地工具执行支持的请求 | Runtime Profile |
++| 凭据存储 | 为 Endpoint 解析具名凭据 | Runtime Profile |
++| Result 仓库 | 保留项目的 Build 记录与产物文件 | 项目 Result 配置 |
++| Distribution | 提供可执行应用与官方包 | 安装的 `hypit` 版本 |
--### Layer 1:Hypit Core
++例如,Model 描述要生成的视频,Provider 将请求映射到服务;Ranking 组件描述榜单的行为,渲染器将其贡献绘制到最终编排。两者都通过明确输入与输出参与同一个图。
--不可变图协议、需求编译器与 Build 状态机。这个闭包与领域无关,不认识源码语法、文件、网络、模型或视频。
++## 组件随作品需要组织
--```text
--@hypit/protocol immutable wire contracts
--@hypit/core Demand compiler and Build state machine
--```
++在适合提取秩序的地方组织空间。Media Track 可以呈现普通视频或图片;项目组件可以把移动的视频视口、标签和流程图作为一个场景协调起来。独立字幕或叠加层仍可分开。共享行为决定哪些内容属于同一个组件。
--### Layer 2:Compiler
++对于说话视频,Script Selection 与 Moment 让组件跟随表演的含义;作者主导节奏的动画,则可以在声明的时钟上使用秒或帧。[Film 与渲染](../quickstart/composition.md) 介绍这些贡献如何组成作品。
--负责 Source 发现、Frontend、导入、图展开与参考 Node Host。Source 在强制 Header 中选择自己的
--Frontend;不存在一个认识全部语法的中央解析器。
++新组件通常放在视频项目的 `packages/` 中,使用所有者自己的 scope,由项目的普通包管理器声明。需要跨项目复用时,所有者可以把同一个组件发布为有版本的 npm 或私有 Registry 包。使用方安装选定版本,并将 lockfile 与项目一起保存。
--```text
--@hypit/source mandatory Source Header
--@hypit/elaborator author declarations and Fragment expansion
--@hypit/run syntax-neutral Run Graph
--@hypit/validation semantic validation
--@hypit/host opaque Host-facet envelope
--@hypit/workspace replaceable Source/Asset session
--@hypit/compiler-node reference Node compiler Host
--@hypit/workspace-fs-node workspace filesystem abstraction
--@hypit/package-loader-node installed package selection
--@hypit/markup official .svml Markup Frontend
--@hypit/svs SVS Recipe Frontend
--@hypit/run-markup official .svrun Markup Frontend
--@hypit/compiler-markup-node Markup Frontend + Surface Host assembly
--```
++## 安装与 Source 导入
--### Layer 3:Foundations
++Skill、可执行 Distribution 和视频项目分别安装与更新。`hypit` Distribution 包含官方作者包和公开扩展 API。所选 Runtime Adapter 可以通过 `hypit runtime up` 准备额外服务依赖;可选作者素材可以按 CLI 给出的准确 `hypit packages install` 命令安装。项目组件自己的依赖由项目管理。
--可复用的数据与确定性构件。它们支撑视频创作,但不决定成片的创作结构,也不调用外部服务。
++Source 使用 `@your-studio/scoreboard@1` 这样的逻辑 Module 地址。npm 安装的包版本决定实际实现,逻辑 `@1` 标识作者接口。视频 Build 使用这些已安装的版本;缺包时会报告安装所需的信息。
--```text
--@hypit/artifact 内容寻址字节
--@hypit/component-kit Producer 与 Validator 注册
--@hypit/text 图原生文字模板
--@hypit/media 媒体值
--@hypit/temporal Selection 与 Moment 投影
--@hypit/spatial 布局几何
--@hypit/visual-ir 渲染器无关的视觉词汇
--@hypit/fonts-open 可分发字体资产
--@hypit/media-pipeline 媒体探测与规范化
--@hypit/media-execution 共享 ffmpeg 执行体
--@hypit/transport 调用边界
--@hypit/transport-aws-lambda Lambda transport
--```
++## 编写与分享扩展
--### Layer 4:Video authoring
++外部包使用 `hypit/author-kit`、`hypit/composition`、`hypit/model-kit` 或 `hypit/endpoint-kit` 等公开子路径。将选定的 `hypit` 版本作为开发依赖,把扩展编译为 JavaScript,分发它自己的代码与素材。`package.json` 中的 activation 入口描述它提供的能力;加载选中的扩展时,当前 Distribution 提供公开 Hypit API。
--赋予 SVML 视频词汇的包:稿件、精确模型需求、语音、字幕、平级 Track、Film 与渲染声明。
--它们依赖公共合同,但不依赖某个具体 Provider 部署。
++- [添加作者包](./author-packages.md):从随发行包提供的可构建组件开始。
++- [组件结构](./component-anatomy.md):组件内部各部分的职责。
++- [模型与 Provider](./providers.md):新模型、服务与凭据的选择。
++- [Runtime](./runtime.md):Endpoint 和凭据配置。
--```text
--@hypit/narrative authored narrative products
--@hypit/script Script Surface
--@hypit/program-space exact frame/sample domain
--@hypit/generation 图像/视频/音频生成合同
--@hypit/model-kit model family abstractions
--@hypit/seedance Seedance model family + author Surface
--@hypit/seedance-kits 数据化的 Seedance 语义 Text Template
--@hypit/minimax-h3 MiniMax H3 model family
--@hypit/grok-imagine Grok Imagine model family
--@hypit/gpt-image GPT Image model family
--@hypit/nano-banana Nano Banana model family
--@hypit/seedream Seedream model family
--@hypit/mimo-speech Xiaomi MiMo 音色设计与音色克隆模型及作者 Surface
--@hypit/estimate 创作期量稿(hypit measure)与估算策略类型
--@hypit/speech shared speech products
--@hypit/speech-evidence acoustic evidence products
--@hypit/speech-alignment speech alignment
--@hypit/semantic-track continuous semantic program skeleton
--@hypit/speech-track ordered speech-take compilation
--@hypit/whisperx WhisperX component
--@hypit/caption Script-owned CaptionDocument、Selection 投影与定时
--@hypit/caption-fine 无字段细粒度字幕 Track family
--@hypit/media-track 统一的 Media Item/Sequence Track
--@hypit/typography-track typography overlay Track
--@hypit/audio-track arbitrary sample-domain Audio Track
--@hypit/deck-track depth-stack collection Track
--@hypit/ranking three ranking component families
--@hypit/screen-overlay self-contained full-canvas overlays
--@hypit/film Film composition
--@hypit/composition peer Track composition
--@hypit/hyperframes HyperFrames document compiler
--@hypit/render-hyperframes explicit HyperFrames rendering component
--@hypit/image-transform image processing component
--@hypit/image-compose 有序静态图像合成
--@hypit/interview-emoji-reveal 可复用的顶部答案图标条
--@hypit/raster 共享确定性光栅执行合同
--@hypit/background-removal 外部图像去背景能力
--```
--
--### Layer 5:Providers
--
--具备特权的外部能力。依赖 Runtime 端口与共享能力词汇,不依赖精确模型包,也绝不依赖 CLI。
--
--```text
--@hypit/provider-kie KIE 生成与去背景
--@hypit/provider-hypihub HypiHub 生成、WhisperX 网关
--@hypit/provider-media-local local ffprobe/ffmpeg
--@hypit/provider-whisperx-local local WhisperX service
--@hypit/provider-hyperframes-local local Chrome rendering
--@hypit/provider-hyperframes-aws-lambda asynchronous distributed rendering
--@hypit/provider-image-opencv-local 本地 OpenCV 光栅执行
--@hypit/provider-media-aws-lambda synchronous AWS media execution
--@hypit/provider-xiaomi-mimo Xiaomi 官方 MiMo 音色设计与音色克隆 API
--```
--
--### Layer 6:Runtime
--
--领域无关的执行端口与可替换部署实现。本地 Runtime 把队列、活跃 Store 与进程生命周期作为一个
--整体实现;真正由包选择的边界是凭据、Endpoint 与项目 Build Result 仓库。
--
--```text
--@hypit/runtime Scheduler、Worker 与 Store 端口
--@hypit/endpoint-kit Endpoint 声明
--@hypit/driver-node 可信 Node Command 执行器
--@hypit/runtime-kit 部署包 ABI
--@hypit/runtime-host-node Node Runtime Host ABI
--@hypit/runtime-local 本地 Worker 与组装
--@hypit/store-sqlite SQLite 状态
--@hypit/resource-store-fs Runtime 内部文件系统临时 Resource
--@hypit/resource-store-s3 供需要 S3 临时 Resource 的 Runtime 实现使用的库
--@hypit/build-result 存储无关的项目 Result 模型
--@hypit/build-result-kit Build Result 仓库包 ABI
--@hypit/build-result-fs 默认项目 Result 仓库
--@hypit/build-result-s3 可选 S3 兼容项目 Result 仓库
--@hypit/credential-store-env 环境变量凭据
--@hypit/credential-store-os macOS 钥匙串或 Windows 凭据锁
--```
--
--### Layer 7:Applications
--
--```text
--@hypit/cli generic command engine (requires explicit Distribution)
--@hypit/video-cli video command application (selects Markup compiler, no built-in author packages)
--@hypit/studio-adapter stable Studio companion ABI and presentation DTOs
--@hypit/*-studio 由 Distribution 显式选择的独立官方 Studio Companion
--@hypit/studio development preview for a Run, never runs a Provider
--```
--
--## 依赖规则
--
--包结构遵循三条依赖规则:
--
--1. **无环的生产依赖图。** 任何 `@hypit/*` 包之间都不存在依赖环。
--
--2. **领域无关 Core 闭包。** Layer 1 只有 `protocol` 与 `core`,且 `core` 只依赖 `protocol`。
-- Compiler 与 Runtime 也可以领域无关,但它们不属于 Core。
--
--3. **CLI 独立性。** `@hypit/cli` 和 `@hypit/video-cli` 都不会传递依赖任何 Provider 包。video CLI 同样不依赖任何作者层的视频包(`@hypit/script`、`@hypit/seedance`、`@hypit/media-track`、`@hypit/typography-track`、`@hypit/film`)。Source import 按需激活作者包,Runtime Profile 的逻辑 `use` 名称按需激活 Credential Store 与 Endpoint 包;两者都不是 CLI 的编译期依赖。
--
--## 包的结构
--
--每个包都位于 `packages/<name>/` 下,结构如下:
--
--```text
--packages/example/
--├── package.json
--├── src/
--│ ├── index.ts public API entry point
--│ └── activation.ts package contribution descriptor (if installable)
--└── test/
-- └── example.test.ts
--```
--
--### package.json
--
--```json
--{
-- "name": "@hypit/example",
-- "version": "0.0.0-dev",
-- "private": true,
-- "type": "module",
-- "exports": {
-- ".": "./src/index.ts"
-- },
-- "hypit": {
-- "activation": "./src/activation.ts"
-- },
-- "dependencies": {
-- "@hypit/protocol": "workspace:*"
-- }
--}
--```
--
--- `"exports"` 在开发期间直接指向 TypeScript 源码。pnpm 工作区链接根据导入包自身声明的依赖解析 `@hypit/*`。
--- `"hypit.activation"` 是该包被选择时 Package Loader 会读取的入口。它必须默认导出一个 `NodePackageContribution`。
--- 物理包版本在真正发布前保持 `0.0.0-dev`。Module 与 Frontend manifest 使用相互独立的逻辑协议版本 `1`。
--
--### activation.ts
--
--每个可安装的包都会导出一个被动的 contribution 描述符 —— 它是对自身所提供内容的清单,而不是一份权限授予。具体示例参见 [添加作者包](./author-packages.md) 和 [添加 Provider](./providers.md)。
--
--## 包 facet
--
--一个物理包可以暴露多个可独立 activate 的 facet:
--
--| Facet | ABI | 能力边界 | 由谁选择 |
--|---|---|---|---|
--| `static` | Manifest 与身份 | 无 | 加载后始终可用 |
--| `author` | Frontend、Surface、Graph Fragment | 仅作者词汇 | 源码中的 `<import>`,经由编译器 Host |
--| `compute` | 确定性 Producer、Type Validator | 纯计算 | 编译器 Host |
--| `endpoint` | 具备特权的外部能力 | 网络、文件系统、进程、凭据 | Runtime Profile |
--| `credential-store` | 解析被显式命名的凭据 | 密钥存储 | Runtime Profile |
--| `result-repository` | 已结束的 Build Result | 项目历史存储 | 项目 `hypit.results.json` |
--| `infrastructure` | Runtime Host、Scheduler 与 Worker 实现 | 持久化、调度 | 应用 Distribution |
--| `application` | Studio Track Companion 等特定应用解释 | 仅该应用的 UI/操作 | Distribution 或已选 Source 包 |
--
--源码中的 `<import>` 只会 activate author facet。它绝不授予网络、文件系统、进程、凭据或队列权限。
--
--## 包选择
--
--Hypit 不维护中央包注册表,也不维护自定义包锁。npm 或 pnpm 负责安装、版本与字节完整性。
--每个所有者只有一条明确的选择路径:
--
--| 选择来源 | 被激活的包 |
--|---|---|
--| 应用 Distribution | Runtime Host 与可信启动包 |
--| Source import | Frontend、Surface、Producer、Validator |
--| Runtime Profile 的 `credentials.*.use` / `endpoints.*.use` | Credential Store 与 Provider Endpoint |
--| 项目 Result 配置的 `use` | 一个 Build Result Repository |
--| Studio Distribution + 已选 Source 包 | 官方 Companion 与当前 Source 实际使用的项目 Companion |
--
--Source import 绝不授予网络、文件系统、进程、凭据或队列权限;这些权限只属于 Runtime
--Host 以及在环境边界被显式选择的包。
--
--### 逻辑包地址与 Source 发现
--
--Source 写的是逻辑语言能力。逻辑名按约定直接对应已安装的 npm 包名;Host ABI 仍让 Module
--与 Run Fragment 可以使用同一名字而不混为一种能力,一个物理包也可以提供多个逻辑名字。
--
--编译首先只读取强制 Source Header,从已安装包解析对应 Frontend,调用该 Frontend 自己的
--`discover()`,继续解析它报告的 Module、Run Fragment 与子 Source,直到本次需要的精确包
--子集不再增长,然后才开始语义解码。Markup 是 video Distribution 的启动 Frontend;除此
--之外,Script、SVS、Run Markup 和第三方 Frontend 都走同一套发现协议,包选择器不再含有
--针对某种解析器的分支。
--
--Frontend 实现不是物理包格式里的特权字段。它们与 Run Fragment、Markup Surface、Runtime
--Adapter 一样,通过自己的 Host ABI 发布普通 facet;Frontend 使用
--`hypit.source-frontend@1`,只有 Source Host 会解释它。
--
--Runtime Profile 对它真正拥有的两种 facet 遵循同一规则:每个 `use` 只选择一个 Credential Store
--或 Endpoint Adapter。项目 Result 配置独立选择一个 Repository;应用 Distribution 自己提供 Runtime
--Host,不在该 Host 的 Profile 里重复伪造一次选择。通用 CLI 因而既不维护 Provider 注册表,也不写死
--Result Repository;不同 Adapter 种类仍可使用相同逻辑名而不冲突。
--
--加载器不会下载包,也不会扫描无关依赖来寻找插件。它只加载 Source、环境配置或应用 Distribution
--明确选择的包,以及这些包 Manifest 精确声明的 Module 依赖。
--
--作者项目拥有独立目录以及自己的 Git/workspace 边界。它的显式项目包从项目自己的
--`packages/` 或安装结果解析;当前工具 Distribution 独占并提供 `@hypit/*` 命名空间。项目
--companion 包使用项目自己的 npm scope,项目及其 package glob 都不会加入 Hypit workspace。
++精确 SDK 类型与实现示例留在对应包的 README 和源码中,它们也随 Distribution 分发。
diff --cc docs/zh/guide/providers.md
index 569364e9,569364e9..66a0552b
--- a/docs/zh/guide/providers.md
+++ b/docs/zh/guide/providers.md
@@@ -1,233 -1,233 +1,48 @@@
---
--title: 添加 Provider
--description: 添加新 Endpoint 适配器的分步指南。
++title: 模型与 Provider
++description: 选择账户、连接服务或添加模型,沿用同一套视频执行系统。
---
--# 添加 Provider
++# 模型与 Provider
--一个 Provider 包实现一项受控的外部能力——视频生成、媒体处理、对齐或渲染。字幕作者语义
--和 Cue 分组由 Script 自己负责,不需要 Provider。Provider 通过 Runtime Profile 激活,而不是
--通过 Author Source 里的 `<import>`。
++**Model** 定义要生成什么:输入、支持的参数和输出类型。**Provider** 知道如何通过某个服务完成这个请求。**Endpoint** 是配置好的 Provider 实例,包含服务地址、凭据引用和容量。Runtime Profile 将所需能力绑定到 Endpoint。
--不需要改动 Core、CLI 或任何作者包。
++## 根据需求选择修改位置
--## 1. 创建包
++| 你想做什么 | 修改哪里 |
++| --- | --- |
++| 同一服务换 Key | 凭据引用与所选 Endpoint 配置 |
++| 换成协议兼容的服务地址 | Provider 已支持的地址或部署配置 |
++| 同一模型换成不同 API 来源 | 安装或编写该 API 的 Provider,并选择它的 Endpoint |
++| 使用尚未定义的新模型 | 添加 Model 包,并由支持其请求的 Provider 执行 |
--```bash
--mkdir -p packages/provider-my-service/src packages/provider-my-service/test
--```
++两个服务即使提供同一个模型,请求格式、限制和可用参数也可能不同。Provider 检查请求是否受该服务支持,并说明不匹配的原因。Profile 决定使用哪个来源;该来源报错并不授权通过另一个账户花钱。
--## 2. 编写 package.json
--
--Provider 包依赖 Runtime 端口与共享能力词汇,不依赖精确模型包,也绝不依赖 CLI:
--
--```json
--{
-- "name": "@hypit/provider-my-service",
-- "version": "0.0.0-dev",
-- "private": true,
-- "type": "module",
-- "exports": {
-- ".": "./src/index.ts"
-- },
-- "hypit": { "activation": "./src/activation.ts" },
-- "dependencies": {
-- "@hypit/endpoint-kit": "workspace:*",
-- "@hypit/protocol": "workspace:*",
-- "@hypit/runtime": "workspace:*",
-- "@hypit/runtime-kit": "workspace:*",
-- "@hypit/runtime-host-node": "workspace:*",
-- "@hypit/generation": "workspace:*"
-- }
--}
--```
++已有安装时,先检查所选 Profile 和凭据状态。起始 Profile 提供配置示例;连接账户或准备依赖前,先选择想使用的服务。[Run 与 Build](../quickstart/run.md) 介绍相关命令。
--## 3. 实现 Provider
--
--Provider 处理来自 Scheduler 的 Command:提交请求、轮询、下载,并把字节交给当前 Build 的临时工作区。
--
--```typescript
--// src/provider.ts
--import { defineEndpointPackage } from "@hypit/endpoint-kit";
--
--export function createMyServiceProvider(options: {
-- instance: string;
-- pool: string;
-- apiKey: CredentialRef;
-- defaultConcurrency?: number;
--}) {
-- return defineEndpointPackage({
-- module: { name: "@hypit/provider-my-service", version: "1" },
-- facet: "service",
-- instance: options.instance,
-- pool: options.pool,
-- credentials: { apiKey: options.apiKey },
-- defaultConcurrency: options.defaultConcurrency ?? 2,
-- capabilities: [{
-- capability: myCapability,
-- returns: myResultType,
-- capacity: "generate",
-- lifecycle: "asynchronous",
-- endpoint: myAsyncEndpoint,
-- }],
-- });
--}
--```
++## 添加 Model
--可以参考现有的 Provider:
--- `packages/provider-kie/src/provider.ts` — 带上传、轮询和下载的远程生成
--- `packages/provider-media-local/` — 本地进程执行(ffprobe/ffmpeg)
--- `packages/provider-whisperx-local/` — 本地 HTTP 服务
--- `packages/provider-hyperframes-local/` — 本地 Chrome 渲染
--- `packages/provider-hyperframes-aws-lambda/` — 异步 Step Functions/Lambda 渲染
--- `packages/provider-media-aws-lambda/` — 通过共享 ffmpeg 执行体完成同步 Lambda 媒体操作
--- `packages/provider-xiaomi-mimo/` — 不依赖 MiMo 模型包的官方即时音色设计与音色克隆 API
--
--## 4. 编写 activation 描述符
--
--```typescript
--// src/activation.ts
--import {
-- createRuntimeEndpointAdapterFacet,
-- runtimeConfigCredentialRef,
-- runtimeConfigExact,
-- runtimeConfigObject,
-- runtimeConfigPositiveInteger,
--} from "@hypit/runtime-kit";
--import { createMyServiceProvider } from "./provider.js";
--
--const adapter = createRuntimeEndpointAdapterFacet({
-- use: "@hypit/provider-my-service",
--
-- activate(context) {
-- if (context.pool === undefined) throw new Error("MyService pool is required");
-- const config = runtimeConfigObject(context.config, "MyService");
-- runtimeConfigExact(config, ["apiKey", "defaultConcurrency"], "MyService");
-- const apiKey = runtimeConfigCredentialRef(config.apiKey, "MyService apiKey");
-- if (apiKey === undefined) throw new Error("MyService apiKey CredentialRef is required");
-- const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "concurrency");
-- return {
-- endpoint: createMyServiceProvider({
-- instance: context.instance,
-- pool: context.pool,
-- apiKey,
-- ...(defaultConcurrency === undefined ? {} : { defaultConcurrency }),
-- }),
-- };
-- },
--});
--
--export const hypitPackage = {
-- format: "hypit.node-package@1" as const,
-- hostFacets: [adapter],
--};
--
--export default hypitPackage;
--```
++项目包使用 `hypit/model-kit`、`hypit/generation` 和 `hypit/author-kit`。声明准确的请求端口、参数取值、输出类型和能力。作者 Surface 把 Prompt Text 与参考素材连接到请求,再将生成素材作为普通图输出公开。
--`activate` 是唯一的纯部署声明。它返回的 Endpoint 同时拥有供 `doctor` 与执行使用的凭据引用、
--capability 和调度事实。Activation 不得解析密钥或环境来源的部署值、访问网络或启动任务;环境变量名会作为引用保留到真正处理匹配 Need 时。凭据是否存在由通用 CredentialStore 路径诊断,
--Provider 不得把环境变量硬编码成特殊的密钥 Store。
--
--Activation 还可以返回 `diagnose(context)`。它只会在用户显式运行主动 `doctor` 时执行,而且
--Runtime 会先解析该 Endpoint 自己声明的凭据槽。它可以对真实服务做一次有界只读请求,例如读取
--已认证账户的模型目录;Build 预检不能调用它,它也绝不能提交生成任务。
--
--收费的 Provider 用 `pricing: { kind: "page", url }` 声明价格发布页面;在本机运行的 Provider
--声明 `pricing: { kind: "local" }`。Endpoint 还可以通过 `readPricing` 返回 Provider 当前发布的
--原始费率文档;只有网页的服务继续以该网页作为价格入口。`hypit pricing <run> --runtime <profile>`
--把这些材料放在 Run 的 Needs 旁边,而且不会创建 Build。Agent 可以据此计算并解释费用,用户的
--决定仍然是支出授权。共享接口包含来源 URL、保持 Provider 原始形状的 JSON 和可选的简短费率说明,因此接入新的
--中转站不需要先给 Hypit 增加一种价格表分类。
--
--`hypit plan --runtime <profile>` 仍然完全在本地执行并列出每个请求的 Endpoint。上游文件尚未
--生成时,能力包仍重建全部作者参数,只把未来文件保留为符号 Resource 槽;同一个 Endpoint 的
--普通 `supports` 会在 Build 入队前检查这份规格。包无法说明请求时直接停止,不回退成
--capability-only 的假验证,也不维护第二张选择表。
--
--## 5. 按需声明 Managed Program
--
--如果 Provider 依赖需要保持温热的外部程序,就在 Endpoint 旁边导出它的声明。这里没有第二个
--manifest 开关,也没有中央 Program 注册表:
--
--```typescript
--// src/program.ts
--import type { ManagedProgram } from "@hypit/runtime-kit";
--
--export function createMyProgram(): ManagedProgram {
-- return {
-- id: "my-service",
-- prepare: { command: "uv", args: ["sync", "--project", "services/my-service", "--frozen"] },
-- start: { command: "uv", args: ["run", "--project", "services/my-service", "--frozen", "hypit-my-service"] },
-- probe: async () => {
-- // 返回 { state: "ready" } 或 { state: "down", detail: "..." }
-- },
-- };
--}
--```
++[Model SDK](https://github.com/hypit-ai/hypit/blob/main/packages/model-kit/README.md) 提供请求定义与 activation 示例。包拥有模型接口;凭据与 HTTP 映射由 Provider 负责。
--在同一个 activation 中把它与 Endpoint 一起返回:
--
--```typescript
--const adapter = createRuntimeEndpointAdapterFacet({
-- use: "@hypit/provider-my-service",
-- activate(context) {
-- return {
-- endpoint: createMyServiceProvider(/* 已解析配置 */),
-- program: createMyProgram(),
-- };
-- },
--});
--```
++## 添加 Provider
--`hypit runtime up` 会准备、启动并探测**本地** Managed Program,然后启动耐久 Worker。`build` 只预检
--本次 Plan 所需 Capability 对应的 Program;未就绪时在提交前失败,绝不安装或启动它。只调用
--远程 API 的 Provider 不返回 `program`,Hypit 也没有可以启动或停止这类服务的生命周期。
++将选定的 `hypit` 版本作为开发依赖,使用公开 SDK:
--## 6. 声明依赖
++```ts
++import { defineEndpointPackage } from "hypit/endpoint-kit";
++import type { AsyncEndpoint, CredentialRef, EndpointRequest } from "hypit/endpoint-kit";
++```
--在 Provider 自己的 `package.json` 中声明所有导入包:
++实现服务支持的准确能力与输出类型,将请求端口映射到服务 API,解析声明的凭据并返回结果。即时操作可以直接返回;远程任务可以先提交得到 ID,再轮询完成情况、收集输出文件。并发和动作限制由 Endpoint 的资源声明负责。
--```json
--"dependencies": {
-- "@hypit/runtime-kit": "workspace:*"
--}
--```
++真正的失败会结束本次执行尝试。Build Result 保留已完成的 Output 与公开任务回执。后续工作通过新的 Run 与 Build,选择仍适用的已有 Output 复用。
--用项目的包管理器安装它。Runtime Profile 用 `use` 显式实例化之前,这个包始终不会运行。
--
--## 7. 在 hypit.runtime.json 中引用
--
--```json
--{
-- "endpoints": {
-- "my-service": {
-- "use": "@hypit/provider-my-service",
-- "pool": "my-service.account",
-- "config": {
-- "apiKey": { "store": "os", "key": "my-service.api-key" },
-- "defaultConcurrency": 2
-- }
-- }
-- }
--}
--```
++[Endpoint SDK](https://github.com/hypit-ai/hypit/blob/main/packages/endpoint-kit/README.md) 维护处理接口、activation、资源声明和价格 API。将包编译为 JavaScript,由项目包管理器安装。在 [Runtime Profile](./runtime.md) 的 `endpoints` 中配置实例,并通过 `bindings` 选择它。
--验证配置:
++## 价格与授权
--```bash
--hypit doctor hypit.runtime.json
--```
++Provider 可以声明本地执行没有 Provider 调用费用,或提供公开费率页面。它也可以使用 Endpoint 凭据读取当前费率,返回简洁摘要及原始价格材料。`hypit pricing <run>` 将费率与计划请求一起展示;未来素材的测量值在产物存在前仍是未知的。
--## 可供研究的现有 Provider
--
--| 包 | 模式 |
--|---|---|
--| `provider-kie` | 远程 API:上传、付费提交、带检查点的轮询、有界下载、写入当前 Build 工作区 |
--| `provider-media-local` | 本地进程:不经 shell 的 ffprobe/ffmpeg,执行有界 |
--| `provider-whisperx-local` | 本地 HTTP 服务:带热模型,单次准入并发 |
--| `provider-hyperframes-local` | 本地进程:Chrome 渲染,带 worker 并行与输出探测校验 |
--| `provider-hyperframes-aws-lambda` | 远程异步任务:按 Operation 自行暂存、Step Functions 轮询与结果流式回收 |
--| `provider-image-opencv-local` | 本地 Python:有界的 OpenCV/NumPy,配合锁定的 Python 环境 |
--| `provider-media-aws-lambda` | 远程同步 Lambda:与本地媒体相同的九项能力 |
--| `provider-xiaomi-mimo` | 远程即时 API:把精确 MiMo 音色设计与音色克隆请求落成持久化音频 Resource |
++费率帮助说明费用。用户的委托授权使用所选账户、按约定范围与预算付费。登录成功或账户有余额,是与这份授权分别成立的事实。
diff --cc docs/zh/guide/skill.md
index 35b0687c,35b0687c..56a16ceb
--- a/docs/zh/guide/skill.md
+++ b/docs/zh/guide/skill.md
@@@ -12,11 -12,11 +12,13 @@@ Skill 提供制作知识,可执行�
## 发展作品
--理解参考片会在整片与细节之间往返:开头为什么抓人,表演怎样推进论述,画面、字幕、图形和声音各自发挥什么作用。观察、转写、针对性的帧和短片,为这些判断提供证据。
++理解参考片会在整片与细节之间往返:开头为什么抓人,表演怎样推进论述,画面、字幕、图形和声音各自发挥什么作用。带词时间的转写与帧序列帮助定位细节:什么出现了,如何运动,为什么在此刻重要。Agent 把整体理解与精确观察记入项目的参考笔记。
--制作目标片会在意图与可见结果之间往返。换人物或产品,可能同时影响剧本、表演、场景和收尾,也会改变参考图片。Agent 围绕新的目标想清楚这些关系,再通过 Studio 和渲染结果细化作品。
++制作目标片会在意图与可见结果之间往返。换人物或产品,可能同时影响剧本、表演、场景和收尾,也会改变参考图片。Agent 围绕新的目标想清楚这些关系,在生成素材前,把视觉形象、参考关系、发音与表演方向写进图片 Prompt、Script 和视频 Prompt。等待生成时,可以同时制作组件与字幕。真实素材到位后,集中检查视觉层次、位置、出入场和时机是否承载了预期效果。
--目标、私有事实和花费由你决定。Agent 在这个方向内承担日常创作与技术选择。付费请求开始前,它会说明所选服务、请求数量,以及 Provider 提供的价格信息。
++目标、私有事实、服务账户和花费由你决定。Agent 检查相关已有能力,在缺少某项能力时解释选择。例如,理解说话参考片可能需要准备本地 WhisperX 或选择托管转写;图片、视频生成可以通过支持的服务使用你自己的 Key,或使用 HypiHub 账户。
++
++付费工作前,根据可用价格信息确认账户、制作范围与预算。Agent 在委托内承担日常创作与技术决定,说明理解与制作进展;范围或费用变化时再交给你决定。
## 保持项目可编辑
@@@ -28,10 -28,10 +30,10 @@@
- `.svrun` 选择 Author Source、已有 Output 和本次执行的目标。
- Build Result 留存实际产物与本次执行的事实。
--项目组件是视频制作的一部分。它们与项目一起保存,可以表达新的视觉角色、Caption 样式族或图形行为。需要跨项目共享时,可以通过所有者自己的 scope 发布普通的版本化包。
++项目组件是视频制作的一部分。它们与项目一起保存,可以表达新的视觉角色、Caption 样式族或图形行为。共享布局或动作的内容可以组织为同一场景,独立图形与字幕继续分开。说话视频用 Script 事件驱动这些关系,纯视觉动画则可以使用作者声明的时钟。需要跨项目共享时,可以通过所有者自己的 scope 发布普通的版本化包。
修改作品时,Run 可以复用已有 Result 中仍适用的 Output,也包括失败 Build 在失败前已经产出的可用素材。新的 Build 执行修改后的 Run。Studio 显示这份作品,并把支持的编辑写回 Source;Agent 对照目标审看实际成片。
--[快速开始](../quickstart.md) 介绍文件格式和命令。
++[快速开始](../quickstart.md) 展示与 Agent 一起制作视频的过程。
[Run 与 Build](../quickstart/run.md) 介绍执行和产物复用。
[Studio](../quickstart/preview.md) 介绍交互预览与编辑。
diff --cc docs/zh/quickstart.md
index d244ac3b,1e215413..ddf55298
--- a/docs/zh/quickstart.md
+++ b/docs/zh/quickstart.md
@@@ -1,141 -1,55 +1,66 @@@
---
--title: 面向 Agent 使用者的快速开始
- description: 无需手写 SVML 或 SVS,通过 Coding Agent 创建、审阅并交付 Hypit 视频。
-description: 通过 Coding Agent 复刻一条视频,共五步。
++title: Agent 用户快速开始
++description: 从参考视频出发,为你的人物、产品和受众制作新视频。
---
- 你不需要了解 SVML、SVS、JavaScript 或命令行。用日常语言向 Coding Agent 描述视频,Agent 会通过 `/hypit` skill 理解参考、设计内容、制作视频,并交付可继续修改的项目。
-用日常语言描述你要的视频,其余交给 Agent 和 `/hypit` skill。
++# 和 Agent 一起制作视频
- 录屏用于展示对话和编辑操作。界面与个别命令可能有所不同,当前的使用方式请参照下文。
-## 你需要准备什么
++带来一条你喜欢的视频,告诉 Agent 想怎么改:换成你的脸、你的产品,面向新的受众,或再做一个变体。Hypit 提供制作知识与工具,让它理解参考片、制作素材,并编排出可以继续编辑的视频。
- ## 你需要准备什么
-- 一个能够使用 skill 的 Coding Agent,例如 Claude Code 或 Codex;
-- 一条参考视频。
++## 你需要准备
- - 一个能够使用 skill 的 Coding Agent,例如 Claude Code 或 Codex;
- - 一条用于复刻的视频,或一份用于原创视频的创意简报。
-## 1. 安装 Hypit skill
++- 支持 Skill 的 Coding Agent,例如 Claude Code 或 Codex。
++- 参考视频,或对目标视频的描述。
+
- ## 1. 安装 Hypit skill
-
- 先安装 Hypit skill:
++## 1. 安装 Hypit Skill
```bash
npx skills add hypit-ai/hypit -g
```
- 然后在任意处启动 Coding Agent,Hypit skill 将全局可用。Skill 提供制作知识;Agent 会检查 Hypit 命令是否可用,并在需要时准备可执行工具,说明其中需要你选择的安装事项。
-
- ### **👉 [免费获得 100 个拥有独特音色的 AI 人物形象](https://drive.google.com/drive/u/2/folders/18J9Fz7mkU3OQNJ-2Res3eIyFQ2cemIK5)**
-
- ## 2. 描述你想制作的视频
-
- <video controls playsInline preload="metadata" width="100%" src="https://storage.googleapis.com/hypit-public-assets/quickstart/2026-09-09/describe_the_video_you_want.mp4"></video>
-
- 可以从一条想改编的参考视频开始,也可以从一个创意开始。
-
- ### 复刻一条参考视频
-
- 要求 Agent 复刻视频,并提供本地视频文件路径:
-
- ```text
- /hypit 克隆这条视频:/path/to/video.mp4
- ```
-
- 你也可以直接提供在线视频平台的链接。对于支持的平台,Agent 会使用 `yt-dlp` 下载视频。例如:
-
- ```text
- /hypit 克隆这条视频:https://www.youtube.com/watch?v=VIDEO_ID
- /hypit 克隆这条视频:https://www.instagram.com/reel/REEL_ID/
- ```
-
- 如果需要改变内容,也可以一并说明,例如更换主持人、语言、产品、画幅比例、视觉风格或行动号召。Agent 会理解原片为什么有效,并根据你的目标改编剧本、人物表演和画面关系。你会得到成片和可继续编辑的项目。
-
- ### 原创一条视频
-
- 你可以像给一位真人制片人写 brief 一样描述想法。例如:
-
- ```text
- 请制作一条 ranking 视频。视频中有一个 ranking 板子,包含五行:左侧是 S、A、B、C、D 五个等级,每个等级使用不同的颜色;右侧用于摆放对应等级的图标。把 Hypit 排到 S 级,并解释它的优势;同时加入 Arcads、Higgsfield、Seedance 和 CapCut,对每个竞品给出公平而简洁的优点与缺点说明。整体要清晰、有活力,适合短视频平台。
- ```
-
- 你还可以补充目标受众、时长、语言、语气、品牌色、主持人、发布平台或画幅比例等要求。Agent 会把 brief 转换成完整计划,并自行补全制作所需的细节。
-
- ## 3. 选择项目使用的服务
-
- <video controls playsInline preload="metadata" width="100%" src="https://storage.googleapis.com/hypit-public-assets/quickstart/2026-09-09/provide_credentials_when_the_agent_asks.mp4"></video>
-
- Agent 会先检查当前项目已有的工具和服务,说明缺少什么,并帮助你选择接入方式。对于有对白的参考视频,WhisperX 提供理解视频所需的转写和词时间。Agent 会检查本地是否已有可用环境;需要时,可以帮助准备本地环境,也可以使用你选择的托管服务。
-
- 你可以使用自己的 Provider 账号,也可以选择 HypiHub,通过一个账号使用托管转写和生成服务。告诉 Agent 你已经使用哪些服务,以及更倾向本地配置还是托管工具。确定连接某项服务后,它再打开登录。录屏展示的是 HypiHub 登录选项。
-在任意位置启动 Coding Agent。首次使用时,Agent 会自行安装 Hypit 工具。
++在 Agent 中打开你的视频项目。Skill 提供制作知识,`hypit` 包提供可执行工具。Agent 会检查已有安装,协助准备缺少的工具。你无需克隆 Hypit 仓库。
- 通过服务的登录或凭据配置完成连接。凭据保存在配置的凭据存储中,项目记录使用哪些服务。
-## 2. 复刻一条视频,换成你的产品
++## 2. 提供参考,说明想改什么
- ## 4. 约定付费范围
-
- <video controls playsInline preload="metadata" width="100%" src="https://storage.googleapis.com/hypit-public-assets/quickstart/2026-09-09/approve_and_submit_the_paid_build.mp4"></video>
-
- 使用付费服务前,Agent 会说明使用的账号、准备执行的工作和可查到的价格信息。一起确定制作范围与预算,例如:
-给 Agent 一个文件或链接,并说明要改什么:
++把视频文件或支持的平台链接交给 Agent,也可以附上人物照片、产品或品牌素材:
```text
- 使用我选定的账号完成这条视频,包括转写和素材生成,总预算不超过 5 美元。制作过程中及时告诉我进展。
-/hypit 克隆这条视频:/path/to/video.mp4,把产品换成 Hypit(hypit.ai)。
++/hypit 参考这个视频:/path/to/video.mp4。
++把产品换成 Hypit(hypit.ai),保留抓人的开场和 Ranking 呈现方式。
```
- 这份授权覆盖约定范围内后续开展的工作。如果你只想先分析,就先授权分析;明确制作方向后,再估算制作费用。扩大范围、更换付费账号或超出预算时,再由你作出新的决定。
-
- 录屏展示如何确认一项制作请求。实际费用,以及哪些处理在本地或托管服务上执行,取决于当前项目选择的服务。
-
- ## 5. 让 Agent 制作视频
-
- <video controls playsInline preload="metadata" width="100%" src="https://storage.googleapis.com/hypit-public-assets/quickstart/2026-09-09/let_the_agent_do_the_production_work.mp4"></video>
-YouTube、Instagram 等平台链接都可以,Agent 会自动下载。主持人、产品、语言、画幅、行动号召,都可以在同一句话里说明。
++人物、产品、语言、画幅和行动号召都可以调整。Agent 会理解原片为什么有效,包括图形、字幕如何落在具体词语上,再根据你的目标改写剧本、设计画面。理解和决定会记进项目,制作过程中也会向你说明作品的方向与进展。
- Agent 会从你的目的出发理解参考视频,结合带时间的帧图和台词,弄清故事、节奏,以及字幕、B-roll、图形的作用与出现时机。换人或换产品的要求会从一开始影响剧本和设计。
-### **👉 [免费获得 100 个拥有独特音色的 AI 人物形象](https://drive.google.com/drive/u/2/folders/18J9Fz7mkU3OQNJ-2Res3eIyFQ2cemIK5)**
++### **👉 [免费领取 100 个拥有独特音色的 AI 人物](https://drive.google.com/drive/u/2/folders/18J9Fz7mkU3OQNJ-2Res3eIyFQ2cemIK5)**
- 它记录制作方向,写好图片和表演的 prompt,安排素材之间的参考关系。独立素材正在生成时,可以同时编写组件、准备编排。有对白的素材提供字幕与图形所依附的语义时间;纯动画也可以按自身的表达节奏安排时间。
-<video controls playsInline preload="metadata" width="100%" src="../quickstart/videos/clone_a_video_with_your_product.mp4"></video>
++<video controls playsInline preload="metadata" width="100%" src="https://storage.googleapis.com/hypit-public-assets/quickstart/2026-09-10/clone_a_video_with_your_product.mp4"></video>
- 实际素材到位后,Agent 检查版面、运动和时机如何配合,并调整相应组件。已有素材保留用于复用;创作决定、进展和问题会及时告诉你。
-## 3. 登录 Hypit,或使用自己的 key
++## 3. 选择你想使用的服务
- Build 会保存已完成的素材和输出。如果某次执行失败,Agent 会说明情况,并在约定范围内通过新的 Run 和 Build 使用已有成果继续制作。
-<video controls playsInline preload="metadata" width="100%" src="../quickstart/videos/log_in_to_hypit_or_bring_your_own_key.mp4"></video>
++Agent 会先检查相关工具与已有服务。对于有对白的参考视频,WhisperX 提供词语及其时间,帮助 Agent 把画面变化和说话内容联系起来。缺少时,Agent 可以协助在本机准备,也会说明托管选项。
- ## 6. 查看成片
-模型需要凭据时,Agent 会向你索要。登录一次 hypit.ai 即可使用 Hypit 托管的全部模型;也可以把你偏好的 Provider 的 API key 交给 Agent。凭据保存在系统凭据存储中。
++[HypiHub](https://hypit.ai) 通过一个账户提供托管 WhisperX 和图片、视频、音色模型。你也可以通过支持的 Provider 使用自己的 Key,或组合本地与托管能力。Agent 会解释需要什么,再协助连接你选择的服务。
- <video controls playsInline preload="metadata" width="100%" src="https://storage.googleapis.com/hypit-public-assets/quickstart/2026-09-09/review_the_paid_result.mp4"></video>
-## 4. 查看报价,批准生成
++<video controls playsInline preload="metadata" width="100%" src="https://storage.googleapis.com/hypit-public-assets/quickstart/2026-09-10/log_in_to_hypit_or_bring_your_own_key.mp4"></video>
- Build 完成后,Agent 会提供最终视频及保存位置。查看内容、字幕、转场、构图和声音是否符合你的目标。需要修改时,直接告诉 Agent;项目保留可编辑的源码和已生成素材。
-<video controls playsInline preload="metadata" width="100%" src="../quickstart/videos/check_the_quote_and_approve.mp4"></video>
++## 4. 确认费用,开始制作
- ### 在 Studio 里了解可编辑项目
-
- <video controls playsInline preload="metadata" width="100%" src="https://storage.googleapis.com/hypit-public-assets/quickstart/2026-09-09/review_the_mock_studio.mp4"></video>
-
- 交付成片时,Agent 也可以打开 Studio,展示这条视频的可编辑编排。你可以通过预览、时间线和属性面板,了解素材、字幕与图形如何配合。
-
- 录屏用占位素材展示时间线和编辑界面。在你的项目里,Agent 会打开选用了实际制作素材的 Run。远程协作时,也可以通过截图或短录屏了解项目。
-
- 你可以提出具体要求,例如:
-花钱之前,Agent 会列出每一项付费请求及其价格。批准后,它提交 Build:
++付费工作开始前,Agent 会说明使用哪个账户、准备做什么、可用费率或预计费用,以及还不确定的部分。确认制作范围和预算后,约定覆盖的调用就可以连续推进。更换账户、扩大范围或超出预算时,再由你决定。
```text
- 让 ranking 板跟着介绍排名的台词出现,并把字幕放大一些。
-开始。
++用我的 HypiHub 账户完成这条视频,按我们确认的预算推进,开始吧。
```
- Agent 会修改对应的源码或组件,并检查更新后的编排。
-
- ## 7. 继续用自然语言提出修改
-
- <video controls playsInline preload="metadata" width="100%" src="https://storage.googleapis.com/hypit-public-assets/quickstart/2026-09-09/request_natural_language_changes.mp4"></video>
-
- Build 成功后,你仍然可以用对话继续指导项目。你可以更换主持人、替换 B-roll、改变 ranking 板的样式、翻译台词、调整语气或切换画幅比例。例如:
-
- ```text
- 保留台词和排名顺序,但把主持人换成沉稳的男主持,并把 ranking 板做成纸质体育杂志风格。
- ```
-## 5. 查看成片
++<video controls playsInline preload="metadata" width="100%" src="https://storage.googleapis.com/hypit-public-assets/quickstart/2026-09-10/check_the_quote_and_approve.mp4"></video>
+
- Agent 会把每项要求落实到对应的源码和组件,保留你要求不变的部分,并复用已有产物。新的付费生成遵循你授权的范围。
++Agent 会从一开始写好剧本、表演方向和图片参考关系,让生成素材承载明确的创作意图。等待生成时,可以同时制作图形与字幕。Hypit 将执行情况和产物保存在 Build Result 中;Agent 随制作进展向你说明情况。
+
- ## 8. 并行制作多个变体
++## 5. 看成片,继续修改与创作
+
- <video controls playsInline preload="metadata" width="100%" src="https://storage.googleapis.com/hypit-public-assets/quickstart/2026-09-09/create_multiple_variants_in_parallel.mp4"></video>
++真实素材到位后,Agent 会检查版面、字幕、图形和 B-roll 是否清楚、时机是否恰当。交付视频时,也可以打开 Studio,让你浏览时间线、调整支持的属性。
+
- 如果需要多个版本,先告诉 Agent 哪些维度可以变化。它会与你讨论具体方向,例如:
++<video controls playsInline preload="metadata" width="100%" src="https://storage.googleapis.com/hypit-public-assets/quickstart/2026-09-10/watch_the_finished_video.mp4"></video>
- - 更换主持人的版本;
- - 翻译成西班牙语的版本;
- - 把产品卖点放到开头的版本;
- - 加快剪辑、增加 B-roll 密度的版本。
-<video controls playsInline preload="metadata" width="100%" src="../quickstart/videos/watch_the_finished_video.mp4"></video>
++继续对话就能修改作品或制作变体。仍适用的素材会继续复用,Agent 调整相关剧本、组件或位置。项目保存在普通文件里,可以继续编辑。
- Agent 会整理各版本共用的内容和各自的变化,为每个版本写出明确的制作选择。独立工作可以并发执行,具体并发量由运行配置控制;共用素材可显式复用。最终你会得到每个版本的成片、项目文件和完成情况。
-Agent 交付视频,并在 Studio 中展示给你。如果还有修改意见,继续与 Agent 沟通即可。
++进一步了解:[与 Agent 一起制作视频](./guide/skill.md)、[Run 与 Build](./quickstart/run.md)、[Studio](./quickstart/preview.md)。
diff --cc docs/zh/quickstart/generation.md
index 06365599,06365599..efd18e6b
--- a/docs/zh/quickstart/generation.md
+++ b/docs/zh/quickstart/generation.md
@@@ -108,7 -108,7 +108,7 @@@ Seedance 2.5 复用同样的 Surface,
<seedance:TextVideo id="ambient" model="mini"
prompt={ambient-direction} duration="5" web-search="false"/>
```
--创作规则要求每条 take 都从一张已验收的图开始,所以实际创作用的是首帧或有序引用这两种形状。这里记录这个形状是因为模型有它,而不是因为一条 take 应该在没有画面的情况下开始。
++对于反复出现的人物、产品或场景,先制作参考图能给视频模型明确的视觉方向。多个 Take 可以复用这些参考,再由 Script 与 action Prompt 指导各段表演。当场景可以直接描述、不需要保持特定视觉身份时,也可以使用 TextVideo。
### seedance:FrameVideo
diff --cc docs/zh/quickstart/images.md
index 84b8ffe3,84b8ffe3..e8c23941
--- a/docs/zh/quickstart/images.md
+++ b/docs/zh/quickstart/images.md
@@@ -7,7 -7,7 +7,7 @@@ description: 在图片流向生成器�
有三个包接收一张图片、交还一张图片。它们都不产出 Track:每个输出都是一张可供下游引用的图片——作为 Seedance 的参考帧、作为 Media Item,或作为下一次操作的来源。
--它们都需要 Endpoint。`image-compose` 与 `image-transform` 索取 raster 能力,由 `@hypit/provider-image-opencv-local` 在本机运行 OpenCV 来满足;`background-removal` 索取的是它自己声明的能力,由 `@hypit/provider-kie` 远程满足。本仓库没有示例默认绑定这两者,所以在 plan 一次用到它们的 Build 之前,先把 Endpoint 加进你的 [Runtime Profile](/zh/guide/runtime)。
++它们都需要 Endpoint。`image-compose` 与 `image-transform` 索取 raster 能力,由 `@hypit/provider-image-opencv-local` 在本机运行 OpenCV 来满足;`background-removal` 索取的是它自己声明的能力,由 `@hypit/provider-kie` 远程满足。使用这些操作时,在 [Runtime Profile](/zh/guide/runtime) 中选择支持它们的 Endpoint。
## 合成图层
@@@ -87,3 -87,3 +87,14 @@@
```
**输出:** `{cutout.image}`——通常喂给一个 Media Item,好让出镜者叠在画面上,而不是待在一个方框里。
++
++## 移动人物抠像
++
++人物需要出现在其他画面之上时,可以将生成或已有视频交给 [`@hypit/volcengine-matting`](https://github.com/hypit-ai/hypit/blob/main/packages/volcengine-matting/README.md),由支持该能力的 HypiHub Endpoint 执行:
++
++```svml
++<import as="matte" from="@hypit/volcengine-matting@1"/>
++<matte:Portrait id="cutout" source={performance.video}/>
++```
++
++将 `cutout.video` 归一化,准备进入时间线。如果它建立说话节目的语义骨架,再把准备好的媒体与 Script Segment 对齐,通过 Speech Track 装配。画面由 Media Track 或项目场景按选择的位置、绘制顺序呈现。作为 B-roll 时,归一化后的抠像可以直接进入 Media Track。抠像改变画面背景,具体角色由编排决定。
diff --cc docs/zh/quickstart/preview.md
index dcab9919,dcab9919..909e675e
--- a/docs/zh/quickstart/preview.md
+++ b/docs/zh/quickstart/preview.md
@@@ -1,77 -1,77 +1,56 @@@
---
--title: Studio 实时预览
--description: 打开一份素材已经满足的 Run,检查画面、时间线并修改真实作者 Source。
++title: Hypit Studio
++description: 浏览编排、Source 和 Result,编辑作品的时机与外观。
---
--# Studio 实时预览
++# Hypit Studio
--Hypit Studio 打开一份 `.svrun`,把它的 Film 或 Render target 回溯到可解释的 Semantic 与 Track 投影,并用四个区域呈现:左上 Source、中上 Preview、右上 Inspector、下方 Timeline。
++Studio 在浏览器中打开可编辑的视频项目。你可以播放编排、逐帧查看,在时间线上选择词语或图形,并修改组件公开的属性。交付成片时,也可以一起打开 Studio,展示作品的可编辑结构。
--Studio 打开 Run 选择的编排,使用项目文件和已完成的 Build Output。通过 `<build-record>` 和 `satisfy` 保留正在编辑的素材。Provider 支持临时创作执行时,Studio 可请求所选 Runtime Profile 完成检查、归一化等媒体操作。生成和 Build 提交通过 CLI 进行;Studio 提供播放、语义定位和对实际 Source 的编辑。
++## 打开要编辑的作品
```bash
--hypit-studio --run examples/ranking-football/swap-effect-banana/studio.svrun \
-- --workspace examples/ranking-football/swap-effect-banana
--# ➜ http://localhost:5179/
++cd /path/to/my-video
++hypit-studio --run build.svrun
```
--| 参数 | 含义 |
--| --- | --- |
--| `--run <build.svrun>` | 要打开的 Run Source。必填。 |
--| `--runtime <hypit.runtime.json>` | 用于临时媒体执行和显示活动 `BuildView`;历史 Result 与 `<build-record>` 仍来自项目 Result Repository。 |
--| `--workspace <directory>` | Source 访问与写回边界;默认是 Run 所在目录。 |
--| `--port <number>` | HTTP 端口,默认 `5179`。 |
--
--Studio 的工作单元是 Run,不是孤立的 `.svml`。Run 决定当前 Author Source、目标和 Candidate;Studio 的每次重新编译都继续使用同一份 Run,不会在后台选择另一套素材。
--
--## 什么样的 Run 可以打开
--
--Studio 需要:
--
--- 一个真实存在的 Film 或 Render target;
--- 可以追溯的 Semantic Track 与可展示 Track;
--- 明确选择的素材 Candidate;
--- 能由确定性 Producer 和 Provider 声明的临时能力完成的显示闭包。
++打开命令打印的网址。Studio 使用这份 Run 选择的 Author Source 和素材。编辑时要保留已生成素材,可以通过 [`build-record` 与 `satisfy`](./run.md) 选择已完成的 Output。
--如果 Run 只提供一个不透明成片,或某条显示链仍要求外部生成,Studio 会拒绝启动。它编辑的是当前作者图和 Track,不从最终视频反推一份新工程。
--
--项目文件可以直接满足一个输出;早先 Build 的结果可以通过 `<build-record>` 复用:
--
--```svml
--<file id="take-1" type="@hypit/artifact@1#BlobArtifact"
-- from="./assets/take-1.mp4" media-type="video/mp4"/>
--<satisfy output="take-opening.video" candidate="take-1"/>
--```
--
--## 四个区域
++| 参数 | 用途 |
++| --- | --- |
++| `--run <file.svrun>` | 选择要打开的 Run。 |
++| `--runtime <profile.json>` | 选择 Runtime Profile;省略时使用项目保存的 Runtime 选择。 |
++| `--workspace <directory>` | 设置 Source 访问与修改的项目边界。 |
++| `--port <number>` | 指定浏览器服务端口,默认请求 `5179`。 |
--### Source
++所选目标需要指向一个 Film 及其时间来源。说话表演可以提供 SemanticTrack,动画可以使用作者声明的 ProgramSpace,两者都支持视觉组件与属性编辑。显示编排所需的素材应已通过 Run 提供。Studio 可以完成所选 Runtime 支持的媒体准备;生成和编码渲染通过 `hypit build` 提交。
--左上显示当前 Author SVML,支持行号、高亮、选择联动和文本编辑。当前版本还不是完整的 Source workspace;相关 SVS、SVRun、任务与产物浏览仍在单独调研。
++## 浏览项目
--### Preview
++左侧资源库包含三个视图:
--中上使用真实素材和 HyperFrames 画面。结构、Frame、padding、堆叠、动效和 Track 布局来自与 Build 相同的领域程序,不是 Studio 的近似重绘。
++- **Source** 列出所选 Run 及其 Author、Recipe 文件,可以选择文件查看或编辑。
++- **Tasks** 显示项目已完成的 Build;选择 Runtime 后,也能查看活动执行信息。
++- **Artifacts** 用于查看 Build Result 中保留的公开产物文件。
--### Inspector
++选择 Artifact 会打开它供查看。要将它用于编排,修改 Run 的 Candidate 选择,让素材选择留在可编辑的项目中。
--右上显示当前实体的来源、时间、操作能力和 adapter 公开的作者参数。可写字段都带精确 Source range;没有唯一写回目标的值保持只读。
++## 画面、时间线与 Inspector
--### Timeline
++中央 Preview 使用 HyperFrames 绘制编排,组件布局、素材采样和动作与编码渲染来自同一份编排。调整字幕位置、图形重点或覆盖画面时,可以对照真实素材查看。
--下方把 Semantic Segment、Word、Selection、Moment 和组件 Track 放到同一帧域。点击实体会选择并 seek;可以播放、逐帧移动、缩放和滚动。只有 adapter 声明且能够解析到唯一作者目标的 move/trim 手势才会启用。
++Timeline 把组件的出现放在同一时钟上。语义编排还会显示 Segment、Word、Selection 和 Moment。选择实体即可定位;播放、逐帧、缩放和滚动便于查看具体转场或版面。
--## 修改怎样落回 Source
++Inspector 显示所选实体的属性。可编辑字段与时间线手柄由组件的 **Studio Companion** 提供,它负责向 Studio 描述组件。项目组件可以随绘制代码一起提供自己的 Companion。组件能够渲染,与它开放了哪些编辑控件,是两件事:字段或手势需要明确可修改的 Source 值。
--Studio 有两类结构化作者操作:
++## 修改作品
--- 时间线手势提交 `timeline.adjust`;
--- Inspector 参数提交 `parameter.adjust`。
++Source 编辑修改所选 `.svml`、`.svs` 或 `.svrun` 文件。支持的 Inspector 修改和时间线手势会写回对应作者值,然后用同一份 Run 重新编译。移动共享的 Selection 或 Moment,会改变它在 Script 中的位置,使用它的组件随之更新;修改共享 Frame 或 Recipe,也可能影响多个画面元素。
--它们沿本次 Run 的真实执行谱系找到 SVML/SVS 中的作者逆像。修改后 Studio 使用同一 Run 重新编译;成功才发布新画面,失败就恢复文件并显示真实领域错误。它不会创建隐藏 Build、提交生成,或把 Selection 偷换成绝对帧。
++编辑后查看保存状态。重新编译失败时,Studio 显示错误并恢复之前的文件。结构化 Inspector 草稿使用 Apply 或 Reset。Run 和已加载 Source 文件会被监听;更换安装包、组件代码或 Runtime 选择后,需要重启 Studio 来加载这些变化。
--选择、投影、消费与写回的完整语义见 [Studio 时间谱系](../guide/studio-temporal-windows.md) 和 [Studio 作者操作](../guide/studio-timeline-operations.md)。
++## 声音与交付
--## 声音
++预览播放包含 Film 选中的 AudioTrack,例如口播、音乐与音效。导出视频的音频由渲染的媒体管线装配。交付编码后的成片,同时可以用 Studio 浏览其可编辑编排。
--HyperFrames 只负责画面;Programme audio 最终由媒体管线装配。为了按口播检查 B-roll 时机,Studio 播放时可以同步播放 Speech Track 的真实音频。没有显式音频的视觉素材不会被自动赋予声音。
++组件作者可以阅读 [Studio 时间谱系](../guide/studio-temporal-windows.md) 了解语义编辑,以及 [Companion SDK](https://github.com/hypit-ai/hypit/blob/main/packages/studio-adapter/README.md) 了解如何公开组件实体和控件。
diff --cc docs/zh/quickstart/run.md
index f074ab7f,f074ab7f..2642dd56
--- a/docs/zh/quickstart/run.md
+++ b/docs/zh/quickstart/run.md
@@@ -212,7 -212,7 +212,15 @@@ CLI 必须先确定项目:显式 `--w
`check` 与 `plan` 不会请求在线 Provider。没有所选 Runtime 的 `plan` 只看图,不需要部署
凭据;有 Runtime 时,便宜预检会检查本次 Plan 所需凭据是否存在。在运行 `doctor` 或付费/
--外部 `build` 之前,只配置当前 Runtime Profile 实际引用的环境变量:
++外部 `build` 之前,只配置当前 Runtime Profile 实际引用的凭据。先检查已有选择:
++
++```bash
++hypit auth status
++```
++
++需要的服务未就绪时,先决定配置它,还是选择其他支持的本地或托管方式。例如 WhisperX 可以在本机或通过 HypiHub 运行。起始 Endpoint 是配置起点,并不代表已经选择某个账户。
++
++选择服务后,再连接其凭据:
| 变量 | Provider / 用途 |
|---|---|
@@@ -223,8 -223,8 +231,6 @@@
只执行 Profile 中所选 Endpoint 对应的行。在 macOS/Linux Shell 中:
```bash
--read -r -s HYPIHUB_API_KEY
--export HYPIHUB_API_KEY
read -r -s KIE_API_KEY
export KIE_API_KEY
read -r -s MIMO_API_KEY
@@@ -234,13 -234,13 +240,25 @@@ export MIMO_API_KE
在 Windows PowerShell 中:
```powershell
--$env:HYPIHUB_API_KEY = "your-key"
$env:KIE_API_KEY = "your-key"
$env:MIMO_API_KEY = "your-key"
```
不要把凭据写进 Author Source、Run Source、Runtime Profile 源文件或提交内容。`doctor` 会验证所需凭据是否存在,但不会打印秘密值。
++## 查询所选 Run 的费用信息
++
++```bash
++hypit pricing reference.svrun
++hypit pricing reference.svrun --json
++```
++
++所选 Runtime 决定每个请求由哪个 Endpoint 执行。`pricing` 读取对应 Provider 的费率信息,将匹配请求分组,展示已知参数与请求数量。明确声明为本地无 Provider 调用费用的工作汇总显示;未知价格、不支持的请求和价格读取失败继续可见。`--verbose` 补充本地请求细节与原始价格材料。
++
++用报告说明准备怎么花费:所选账户、计划素材、计价单位与适用费率。命令读取价格,不提交生成,也不计算一个保证准确的总价。未来素材的时长可能还未知,估价时保留这部分不确定性。JSON 在 `groups[].requests` 中保留请求参数,在 `groups[].pricingDocuments` 中保留价格来源材料。
++
++付费调用前,确认账户、工作范围和预算。已有授权覆盖约定内的工作;价格输出与登录成功提供信息,本身不代表同意花费。
++
## Build 工作流
不要提交凭据、生成媒体、Runtime 状态/数据库或日志。
diff --cc docs/zh/quickstart/timing.md
index 538d3ff7,538d3ff7..ab8297ba
--- a/docs/zh/quickstart/timing.md
+++ b/docs/zh/quickstart/timing.md
@@@ -5,19 -5,19 +5,22 @@@ description: 逐 Take 归一化与语�
# 时序与装配
--Hypit 的时间真相是 `SemanticTrack`。它按 Segment 粒度构建:
++对于说话视频,`SemanticTrack` 把作者的 Script 与实际表演联系起来,是字幕、随词语出现的图形和覆盖画面的自然时间来源。它按 Segment 粒度构建:
1. 把每个已接受的音视频 Take 归一化到同一个精确帧域;
2. 将归一化媒体与对应的 Script Segment 对齐,得到自包含的 `SemanticTake`;
3. 用 `speech:Track` 按节目顺序装配这些 Semantic Take。
--每个 Take 在进入 Track 之前就已经具有语义。
++每个 Take 在进入 Speech Track 之前就已经具有语义。画面由 Media Track 或项目组件呈现,与这里的语义和音频装配分别表达。
++
++纯视觉动画也可以通过 ProgramSpace 声明自己的时长与帧率,见 [纯组件绘制的影片](./composition.md)。其事件可以使用秒或帧;说话视频则可以用 Script Selection 和 Moment 驱动相同的视觉行为。
```svml
<import as="program" from="@hypit/program-space@1"/>
<import as="pipeline" from="@hypit/media-pipeline@1"/>
<import as="whisperx" from="@hypit/whisperx@1"/>
<import as="speech" from="@hypit/speech-track@1"/>
++<import as="media-track" from="@hypit/media-track@1"/>
<import as="space" from="@hypit/spatial@1"/>
<import as="recipes" source="./recipes.svs"/>
```
diff --cc docs/zh/quickstart/tracks.md
index ba7d93a9,220619d3..6c5d9451
--- a/docs/zh/quickstart/tracks.md
+++ b/docs/zh/quickstart/tracks.md
@@@ -340,7 -340,7 +340,7 @@@ DepthStack 的直接子元素,自闭�
|---|---|
| `source` | 必填——静态图片、Synchronized Medium 或 Compositable Surface |
| `extent` | 静态图片必填,其余情况给了会被拒绝 |
--| `at` | 必填——这张卡发出的 Moment |
++| `at` | 必填——这张卡发出的事件,可以是 Moment 或 `2s`、`12f` 等作者时间 |
| `appearance` | 可选——它自己的 Recipe,否则沿用整叠的 |
| `label` | 可选——一条 `deck:Label` 记录 |
@@@ -367,7 -367,7 +367,7 @@@
<import as="screen" from="@hypit/screen-overlay@1"/>
```
--`screen:Track` 接受 `id`、`canvas` 与 `space`。它的子元素就是各个效果,至少一个,各自为空,都必须带 `z` 决定层叠顺序,并且各有一个时间窗,形式是以下之一:
++`screen:Track` 接受 `id`、`canvas`,以及 `semantic` 或 `space` 之一作为时间来源。它的子元素就是各个效果,至少一个,各自为空,都必须带 `z` 决定层叠顺序,并且各有一个时间窗,形式是以下之一:
| 时间窗 | 写法 |
|---|---|
@@@ -376,7 -376,7 +376,7 @@@
| 一个 Moment,持续一段时长 | 在带有 `semantic={speech.semantic}` 的 Track 内写 `at={story.moment.x} for="12f"` |
| 显式区间 | `start="…" end="…"`,可另外指定 `selection=` 或 `moment=` |
--Track 接受 `id`、`canvas` 与 `semantic`。时长写作 `12f`、`250ms` 或 `1.5s`。一个 Selection
++时长写作 `12f`、`250ms` 或 `1.5s`。一个 Selection
只表示一个连续区间,一个 Moment 只表示一个点;同一效果需要再次出现时,应再写一个 item。
可用的效果有十一种——`Flash`、`ColorWash`、`Vignette`、`ScanLines`、`DirectionalMatte`、`WhipVeil`、`GlitchVeil`、`Grain`、`LightLeak`、`Bokeh` 与 `TVStatic`——每种各有自己的必填属性,例如 `Flash` 的 `color` / `intensity` / `attack` / `hold` / `decay`,或 `Vignette` 的 `center-x` / `center-y` / `radius-x` / `radius-y` / `softness` / `color` / `opacity`。它们都没有默认值:一个效果要么把自己的形状说全,要么被拒绝。