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.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
docs: integrate refreshed quickstart videos and production guidance
kashorinb8e2a9b2400a
diff --cc docs/guide/author-packages.mdindex 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.mdindex 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.mdindex 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 semanticModules, 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.mdindex 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.mdindex 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.mdindex 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.mdindex 0e48d84b,0e48d84b..34f53387--- a/docs/guide/skill.md+++ b/docs/guide/skill.md@@@ -19,17 -19,17 +19,26 @@@ through their own installation channelsUnderstanding a reference moves between the whole piece and the details that explain it: why theopening 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 canchange 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 bepublished 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 actualfinished 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.mdindex 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.mdindex 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:FrameVideodiff --cc docs/quickstart/images.mdindex 1f20b2d2,1f20b2d2..8efdd1a5--- a/docs/quickstart/images.md+++ b/docs/quickstart/images.md@@@ -12,8 -12,8 +12,8 @@@ source of another operationThey 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 onyour 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 picturerather 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.mdindex 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.mdindex 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 Runtimeneeds no deployment credentials; with a selected Runtime, its cheap preflight checks that demandedcredential 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_KEYread -r -s KIE_API_KEYexport KIE_API_KEYread -r -s MIMO_API_KEY@@@ -269,7 -269,7 +277,6 @@@ export MIMO_API_KEIn 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 workflowKeep credentials, generated media, Runtime data and logs out of commits. A project may live anywhere:diff --cc docs/quickstart/timing.mdindex 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.mdindex 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, eachempty, 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 Selectionnames one contiguous interval and a Moment names one point; author another item when an effect shouldappear again.diff --cc docs/zh/guide/author-packages.mdindex 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.mdindex 00000000,00000000..a7e3ebcanew 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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```bashnpx 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.mdindex 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:FrameVideodiff --cc docs/zh/quickstart/images.mdindex 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.mdindex 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.mdindex 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_KEYread -r -s KIE_API_KEYexport KIE_API_KEYread -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.mdindex 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.mdindex 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`。它们都没有默认值:一个效果要么把自己的形状说全,要么被拒绝。