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
feat(authoring): load reusable sources from installed packages
kashorinf258b9923b9c
diff --git a/docs/guide/author-packages.md b/docs/guide/author-packages.mdindex d751124a..4c74e26b 100644--- a/docs/guide/author-packages.md+++ b/docs/guide/author-packages.md@@ -22,40 +22,41 @@ must not be added to the Style record merely to describe its role.mkdir -p packages/my-component/src```+Create it inside the video project. Use the owner's package scope; `@hypit/*` belongs to the active+Distribution.+## 2. Write package.json```json{- "name": "@hypit/my-component",+ "name": "@your-studio/my-component","version": "0.0.0-dev","private": true,"type": "module",- "exports": {- ".": "./src/index.ts"- },+ "files": ["dist", "preview", "README.md"],+ "exports": { ".": "./dist/index.js" },"hypit": {- "activation": "./src/activation.ts"+ "activation": "./dist/activation.js"},- "dependencies": {- "@hypit/protocol": "workspace:*",- "@hypit/elaborator": "workspace:*",- "@hypit/markup": "workspace:*"+ "devDependencies": {+ "hypit": "^0.1.0",+ "typescript": "^5.9.0"}}```-Add only the dependencies your package actually imports. See-[Package architecture](./packages.md) for layer rules.+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 ManifestIn `src/index.ts`, declare your Module's identity, Types and Producers:```typescript-import type { ModuleManifest, ModuleRef } from "@hypit/protocol";+import type { ModuleManifest, ModuleRef } from "hypit/author-kit";export const myComponentModuleRef: ModuleRef = {- name: "@hypit/my-component",+ name: "@your-studio/my-component",version: "1",};@@ -92,7 +93,7 @@ The Surface handler decodes the Markup Frontend's XML elements into typed author```typescript// src/surface.ts-import type { StructuredSurfaceHandler } from "@hypit/markup";+import type { StructuredSurfaceHandler } from "hypit/author-kit";export const decodeMyComponentSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {const id = textAttribute(element, "id");@@ -178,7 +179,7 @@ from another package's source.```typescript// src/activation.ts-import { createMarkupSurfaceHostFacet } from "@hypit/markup";+import { createMarkupSurfaceHostFacet } from "hypit/author-kit";import {myComponentManifest,myComponentMarkupSurfaces,@@ -204,20 +205,21 @@ export default hypitPackage;```The Module automatically offers its exact `[email protected]`, so authors import-`@hypit/my-component@1` without a duplicate alias declaration. Use optional `specifiers` only+`@your-studio/my-component@1` without a duplicate alias declaration. Use optional `specifiers` onlywhen the package intentionally owns a genuinely different logical alias. The Surface declarationdetermines 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. Declare package dependencies+## 7. Build the package-```json-"dependencies": {- "@hypit/protocol": "workspace:*"-}+```bash+pnpm build```-pnpm workspace links resolve the package. No root path registry is involved.+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@@ -234,7 +236,7 @@ Manifest are loaded from its installed dependencies.```xml<?svml using="@hypit/markup@1"?><svml>- <import as="mine" from="@hypit/my-component@1"/>+ <import as="mine" from="@your-studio/my-component@1"/><mine:Widget id="demo" during={story.selection.example}/></svml>diff --git a/docs/zh/guide/author-packages.md b/docs/zh/guide/author-packages.mdindex 0db2bf6f..36ee46a0 100644--- a/docs/zh/guide/author-packages.md+++ b/docs/zh/guide/author-packages.md@@ -19,39 +19,40 @@ description: 添加新的作者层组件的分步指南。mkdir -p packages/my-component/src packages/my-component/test```+在视频项目中创建它,并从一开始使用所有者自己的 scope;`@hypit/*` 由当前 Distribution 拥有。+## 2. 编写 package.json```json{- "name": "@hypit/my-component",+ "name": "@your-studio/my-component","version": "0.0.0-dev","private": true,"type": "module",- "exports": {- ".": "./src/index.ts"- },+ "files": ["dist", "preview", "README.md"],+ "exports": { ".": "./dist/index.js" },"hypit": {- "activation": "./src/activation.ts"+ "activation": "./dist/activation.js"},- "dependencies": {- "@hypit/protocol": "workspace:*",- "@hypit/elaborator": "workspace:*",- "@hypit/markup": "workspace:*"+ "devDependencies": {+ "hypit": "^0.1.0",+ "typescript": "^5.9.0"}}```-只添加你的包实际导入的依赖。分层规则参见 [包架构](./packages.md)。+开发时使用公开的 `hypit/*` subpath,发布物只包含组件自己的编译文件。分层规则参见+[包架构](./packages.md)。## 3. 定义 Module Manifest在 `src/index.ts` 中声明你的 Module 的身份、Type 和 Producer:```typescript-import type { ModuleManifest, ModuleRef } from "@hypit/protocol";+import type { ModuleManifest, ModuleRef } from "hypit/author-kit";export const myComponentModuleRef: ModuleRef = {- name: "@hypit/my-component",+ name: "@your-studio/my-component",version: "1",};@@ -82,7 +83,7 @@ Surface handler 把 Markup Frontend 的 XML 元素解码成带类型的作者声```typescript// src/surface.ts-import type { StructuredSurfaceHandler } from "@hypit/markup";+import type { StructuredSurfaceHandler } from "hypit/author-kit";export const decodeMyComponentSurface: StructuredSurfaceHandler = ({ element }) => {// Read attributes and children from the XML element@@ -136,7 +137,7 @@ vocabulary: {```typescript// src/activation.ts-import { createMarkupSurfaceHostFacet } from "@hypit/markup";+import { createMarkupSurfaceHostFacet } from "hypit/author-kit";import {myComponentManifest,myComponentMarkupSurfaces,@@ -161,17 +162,16 @@ export const hypitPackage = {export default hypitPackage;```-Module 会自动提供精确的 `[email protected]`,所以作者直接导入 `@hypit/my-component@1`,无需再声明一份重复别名。只有包确实拥有另一个逻辑名称时才使用可选的 `specifiers`。Surface declaration 决定可接受的标签(以 `mine` 导入时即为 `<mine:Widget>`)。它属于 Markup Host facet,不属于语义 Module Manifest,更不属于 Core。+Module 会自动提供精确的 `[email protected]`,所以作者直接导入 `@your-studio/my-component@1`,无需再声明一份重复别名。只有包确实拥有另一个逻辑名称时才使用可选的 `specifiers`。Surface declaration 决定可接受的标签(以 `mine` 导入时即为 `<mine:Widget>`)。它属于 Markup Host facet,不属于语义 Module Manifest,更不属于 Core。-## 7. 声明包依赖+## 7. 编译包-```json-"dependencies": {- "@hypit/protocol": "workspace:*"-}+```bash+pnpm build```-pnpm 工作区链接负责解析包,不需要根路径注册表。+框架声明从 `hypit/author-kit` 导入;组件使用的领域值从 `hypit/composition` 等所属+subpath 导入。加载 activation 时由当前 Distribution 提供这些 API,组件 tarball 不携带另一份 Hypit。## 8. 安装@@ -186,7 +186,7 @@ pnpm install --frozen-lockfile```xml<?svml using="@hypit/markup@1"?><svml>- <import as="mine" from="@hypit/my-component@1"/>+ <import as="mine" from="@your-studio/my-component@1"/><mine:Widget id="demo" during={story.selection.example}/></svml>diff --git a/examples/minimal-author-package/README.md b/examples/minimal-author-package/README.mdindex b5557c05..60907a4f 100644--- a/examples/minimal-author-package/README.md+++ b/examples/minimal-author-package/README.md@@ -9,3 +9,10 @@ The fixture's Surface decoder also demonstrates the public value boundary: Stylea decoded recipe shaped as `{ path, properties }`, exact `FontStackRef` records and inline valuesonly after checking `record.value.kind === "inline"`. Media slots remain graph inputs rather thanpackage files.++The package builds against the single public `hypit` development dependency and emits JavaScript.+`pnpm --dir packages/example-component pack` produces a tarball with no Runtime dependencies of its+own. Installing that tarball in another project and importing `@example/example-component@1` loads+the same Module and Surface through the consumer's active Hypit Distribution. The packaged+`@example/example-component/preview` Source exists so this boundary can be checked without copying a+Source out of the package.diff --git a/examples/minimal-author-package/packages/example-component/README.md b/examples/minimal-author-package/packages/example-component/README.mdindex ded68498..24e5cb35 100644--- a/examples/minimal-author-package/packages/example-component/README.md+++ b/examples/minimal-author-package/packages/example-component/README.md@@ -1,7 +1,10 @@# Example component fixtureThis is the smallest complete author-package fixture. It is the canonical generic-package reference,-not a production component or a video example.+not a production component or a video example. Framework-facing imports come from+`hypit/author-kit`; video-domain imports use their owning `hypit/*` subpaths. The package has one+development dependency on the released Hypit Distribution and no Runtime dependency bundled into+its tarball.It contains a Module Manifest with nominal Types and deterministic Producers, validators, a structuredSurface decoder returning `records`, `components`, `fragments` and `exports`, and sealed Fragments with@@ -13,3 +16,9 @@ The Surfaces demonstrate a box, a text surface, a media slot and a Style decoderinput; it is not a file bundled by the package. `preview/Box.png` is a real catalogue frame suppliedby the package's vocabulary. `exampleAppendFragment` and `append-example-items` show a fixed-portappend that can be chained once per child.++While the component belongs to one project, keep this directory under that project's `packages/`+and use its owner-scoped package name. If the owner chooses to share it, compile and publish the same+package through npm or a private registry. Consumers install a chosen release with their ordinary+package manager and commit the resulting lockfile. The Source's logical Module import remains the+same whether the package is linked from the project workspace or installed from a registry.diff --git a/examples/minimal-author-package/packages/example-component/package.json b/examples/minimal-author-package/packages/example-component/package.jsonindex cd1604eb..b35339f0 100644--- a/examples/minimal-author-package/packages/example-component/package.json+++ b/examples/minimal-author-package/packages/example-component/package.json@@ -3,21 +3,22 @@"version": "0.0.0-dev","private": true,"type": "module",- "exports": { ".": "./src/index.ts" },- "hypit": { "activation": "./src/activation.ts" },- "dependencies": {- "@hypit/artifact": "workspace:*",- "@hypit/component-kit": "workspace:*",- "@hypit/composition": "workspace:*",- "@hypit/elaborator": "workspace:*",- "@hypit/media": "workspace:*",- "@hypit/markup": "workspace:*",- "@hypit/protocol": "workspace:*",- "@hypit/program-space": "workspace:*",- "@hypit/semantic-track": "workspace:*",- "@hypit/svs": "workspace:*",- "@hypit/temporal": "workspace:*",- "@hypit/temporal-markup": "workspace:*",- "@hypit/visual-ir": "workspace:*"+ "files": [+ "dist",+ "preview",+ "README.md"+ ],+ "exports": {+ ".": "./dist/index.js",+ "./preview": "./preview/preview.svml"+ },+ "hypit": { "activation": "./dist/activation.js" },+ "scripts": {+ "build": "tsc -p tsconfig.json",+ "prepack": "pnpm build"+ },+ "devDependencies": {+ "hypit": "workspace:*",+ "typescript": "5.9.3"}}diff --git a/examples/minimal-author-package/packages/example-component/src/activation.ts b/examples/minimal-author-package/packages/example-component/src/activation.tsindex a9a95f02..a9259005 100644--- a/examples/minimal-author-package/packages/example-component/src/activation.ts+++ b/examples/minimal-author-package/packages/example-component/src/activation.ts@@ -1,4 +1,4 @@-import { createMarkupSurfaceHostFacet } from "@hypit/markup";+import { createMarkupSurfaceHostFacet } from "hypit/author-kit";import { decodeExampleSurface, exampleComponent, exampleManifest, exampleMarkupSurfaces, exampleModuleRef } from "./index.js";export const hypitPackage = {diff --git a/examples/minimal-author-package/packages/example-component/src/component.ts b/examples/minimal-author-package/packages/example-component/src/component.tsindex 3c5c885a..7a5a120b 100644--- a/examples/minimal-author-package/packages/example-component/src/component.ts+++ b/examples/minimal-author-package/packages/example-component/src/component.ts@@ -1,9 +1,8 @@-import { sealVisualTrack } from "@hypit/composition";-import type { ProgramSpace } from "@hypit/program-space";-import type { ComponentPackage, ProducerHandler } from "@hypit/component-kit";-import { canonicalize } from "@hypit/protocol";-import type { BlobRef, TypedRecord } from "@hypit/protocol";-import { VISUAL_IR_V1 } from "@hypit/visual-ir";+import { sealVisualTrack } from "hypit/composition";+import type { ProgramSpace } from "hypit/program-space";+import { canonicalize } from "hypit/author-kit";+import type { BlobRef, ComponentPackage, ProducerHandler, TypedRecord } from "hypit/author-kit";+import { VISUAL_IR_V1 } from "hypit/visual-ir";import { exampleProducers, exampleTypes } from "./manifest.js";const inline = <T>(record: { readonly value: { readonly kind: string; readonly value?: unknown } } | undefined): T => {diff --git a/examples/minimal-author-package/packages/example-component/src/fragment.ts b/examples/minimal-author-package/packages/example-component/src/fragment.tsindex 4ee3de1c..92f850be 100644--- a/examples/minimal-author-package/packages/example-component/src/fragment.ts+++ b/examples/minimal-author-package/packages/example-component/src/fragment.ts@@ -1,8 +1,8 @@-import { compositionTypes } from "@hypit/composition";-import { artifactTypes } from "@hypit/artifact";-import { sealGraphFragment } from "@hypit/elaborator";-import { semanticTrackProducers, semanticTrackTypes } from "@hypit/semantic-track";-import { programSpaceTypes } from "@hypit/program-space";+import { compositionTypes } from "hypit/composition";+import { artifactTypes } from "hypit/artifact";+import { sealGraphFragment } from "hypit/author-kit";+import { semanticTrackProducers, semanticTrackTypes } from "hypit/semantic-track";+import { programSpaceTypes } from "hypit/program-space";import { exampleProducers } from "./manifest.js";import { exampleTypes } from "./manifest.js";diff --git a/examples/minimal-author-package/packages/example-component/src/manifest.ts b/examples/minimal-author-package/packages/example-component/src/manifest.tsindex b3916deb..026822e2 100644--- a/examples/minimal-author-package/packages/example-component/src/manifest.ts+++ b/examples/minimal-author-package/packages/example-component/src/manifest.ts@@ -1,12 +1,12 @@import { readFile } from "node:fs/promises";-import { compositionTypes } from "@hypit/composition";-import type { ModuleManifest, ProducerRef, TypeRef } from "@hypit/protocol";-import { programSpaceTypes } from "@hypit/program-space";-import { semanticTrackTypes } from "@hypit/semantic-track";-import { temporalTypes } from "@hypit/temporal";-import { mediaTypes } from "@hypit/media";-import { svsRecipeType } from "@hypit/svs";-import { artifactTypes } from "@hypit/artifact";+import { compositionTypes } from "hypit/composition";+import type { ModuleManifest, ProducerRef, TypeRef } from "hypit/author-kit";+import { programSpaceTypes } from "hypit/program-space";+import { semanticTrackTypes } from "hypit/semantic-track";+import { temporalTypes } from "hypit/temporal";+import { mediaTypes } from "hypit/media";+import { svsRecipeType } from "hypit/svs";+import { artifactTypes } from "hypit/artifact";const previewImage = (file: string) => ({mediaType: "image/png",diff --git a/examples/minimal-author-package/packages/example-component/src/style.ts b/examples/minimal-author-package/packages/example-component/src/style.tsindex aab9cf2d..2f83dbd1 100644--- a/examples/minimal-author-package/packages/example-component/src/style.ts+++ b/examples/minimal-author-package/packages/example-component/src/style.ts@@ -1,5 +1,5 @@-import type { FontStackRef } from "@hypit/media";-import type { SvsRecipe } from "@hypit/svs";+import type { FontStackRef } from "hypit/media";+import type { SvsRecipe } from "hypit/svs";/** The two values a Style decoder receives after author references are resolved. */export type ExampleStyleInput = {diff --git a/examples/minimal-author-package/packages/example-component/src/surface.ts b/examples/minimal-author-package/packages/example-component/src/surface.tsindex 188332dd..9a4f76d1 100644--- a/examples/minimal-author-package/packages/example-component/src/surface.ts+++ b/examples/minimal-author-package/packages/example-component/src/surface.ts@@ -1,9 +1,9 @@-import type { StructuredElement, StructuredSurfaceHandler, SurfaceComponentDraft, SurfaceRecordDraft, SurfaceResolvedReference } from "@hypit/markup";+import type { StructuredElement, StructuredSurfaceHandler, SurfaceComponentDraft, SurfaceRecordDraft, SurfaceResolvedReference } from "hypit/author-kit";import { exampleBoxFragment, exampleMediaFragment, exampleTextFragment } from "./fragment.js";import { exampleMarkupSurfaces, exampleTypes } from "./manifest.js";-import { mediaTypes } from "@hypit/media";-import { svsRecipeType } from "@hypit/svs";-import { artifactTypes } from "@hypit/artifact";+import { mediaTypes } from "hypit/media";+import { svsRecipeType } from "hypit/svs";+import { artifactTypes } from "hypit/artifact";function text(element: StructuredElement, name: string): string {const value = element.attributes[name];diff --git a/examples/minimal-author-package/packages/example-component/src/temporal.ts b/examples/minimal-author-package/packages/example-component/src/temporal.tsindex a455a4e7..96e54457 100644--- a/examples/minimal-author-package/packages/example-component/src/temporal.ts+++ b/examples/minimal-author-package/packages/example-component/src/temporal.ts@@ -1,4 +1,4 @@-import { createTemporalInstantProjection, createTemporalWindowProjection, temporalInstantAttributeNames, temporalWindowAttributeNames } from "@hypit/temporal-markup";+import { createTemporalInstantProjection, createTemporalWindowProjection, temporalInstantAttributeNames, temporalWindowAttributeNames } from "hypit/temporal-markup";/** The fixture intentionally exposes both projection helpers and their vocabularies. */export { temporalInstantAttributeNames, temporalWindowAttributeNames };diff --git a/examples/minimal-author-package/packages/example-component/tsconfig.json b/examples/minimal-author-package/packages/example-component/tsconfig.jsonnew file mode 100644index 00000000..6d5a18e7--- /dev/null+++ b/examples/minimal-author-package/packages/example-component/tsconfig.json@@ -0,0 +1,18 @@+{+ "compilerOptions": {+ "target": "ES2023",+ "module": "NodeNext",+ "moduleResolution": "NodeNext",+ "lib": ["ES2023"],+ "strict": true,+ "noUncheckedIndexedAccess": true,+ "exactOptionalPropertyTypes": true,+ "verbatimModuleSyntax": true,+ "declaration": true,+ "sourceMap": true,+ "rootDir": "src",+ "outDir": "dist",+ "skipLibCheck": true+ },+ "include": ["src/**/*.ts"]+}diff --git a/package.json b/package.jsonindex d58f3f64..ef7f1d67 100644--- a/package.json+++ b/package.json@@ -4,6 +4,20 @@"description": "Hypit video authoring Distribution for AI agents","license": "SEE LICENSE IN LICENSE","type": "module",+ "exports": {+ "./artifact": "./packages/artifact/src/index.ts",+ "./author-kit": "./packages/author-kit/src/index.ts",+ "./composition": "./packages/composition/src/index.ts",+ "./media": "./packages/media/src/index.ts",+ "./program-space": "./packages/program-space/src/index.ts",+ "./semantic-track": "./packages/semantic-track/src/index.ts",+ "./spatial": "./packages/spatial/src/index.ts",+ "./studio-adapter": "./packages/studio-adapter/src/index.ts",+ "./svs": "./packages/svs/src/index.ts",+ "./temporal": "./packages/temporal/src/index.ts",+ "./temporal-markup": "./packages/temporal-markup/src/index.ts",+ "./visual-ir": "./packages/visual-ir/src/index.ts"+ },"bin": {"hypit": "./bin/hypit.mjs","hypit-studio": "./bin/hypit-studio.mjs"@@ -51,6 +65,7 @@},"devDependencies": {"@hypit/artifact": "workspace:*",+ "@hypit/author-kit": "workspace:*","@hypit/resource-store-fs": "workspace:*","@hypit/resource-store-s3": "workspace:*","@hypit/build-result": "workspace:*",@@ -77,6 +92,7 @@"@hypit/generation": "workspace:*","@hypit/gemini": "workspace:*","@hypit/gpt-image": "workspace:*",+ "@hypit/gpt-image-kits": "workspace:*","@hypit/grok-imagine": "workspace:*","@hypit/hyperframes": "workspace:*","@hypit/image-compose": "workspace:*",diff --git a/packages/author-kit/README.md b/packages/author-kit/README.mdnew file mode 100644index 00000000..905b3282--- /dev/null+++ b/packages/author-kit/README.md@@ -0,0 +1,26 @@+# `hypit/author-kit`++Small public framework API for an Author Package.++It joins four stable authoring boundaries: nominal Module declarations, deterministic component+handlers, sealed Graph Fragments and Markup Surface handlers. Domain facts still come from their+owners—for example `@hypit/composition`, `@hypit/semantic-track` and `@hypit/spatial`. This package+does not re-export the video vocabulary or turn those packages into one central object.++`hypit/author-kit` contains no registry, package search, installer, Runtime, Provider or Studio+selection. Importing it makes no component visible. A project's Source explicitly selects an+installed Author Package; the Host then consumes only the contribution exported by that package's+declared activation entry.++An external Author Package normally has one development dependency on the released `hypit`+Distribution. It imports this boundary from `hypit/author-kit` and the relevant domain owners from+subpaths such as `hypit/composition`, compiles its activation to JavaScript, and publishes only its+own built files and assets. At execution time the active Hypit Distribution supplies those exact+public subpaths. This keeps one framework implementation in the process and prevents a component+tarball from carrying private copies of Core.++The minimal independent fixture is+[`examples/minimal-author-package/packages/example-component`](../../examples/minimal-author-package/packages/example-component).+It can remain a project workspace package, or its owner can publish the same package name and install+that release in another project through npm or a private registry. Neither path changes the logical+Module import written by the Source.diff --git a/packages/author-kit/package.json b/packages/author-kit/package.jsonnew file mode 100644index 00000000..2085337b--- /dev/null+++ b/packages/author-kit/package.json@@ -0,0 +1,16 @@+{+ "name": "@hypit/author-kit",+ "version": "0.0.0-dev",+ "license": "SEE LICENSE IN LICENSE",+ "private": true,+ "type": "module",+ "exports": {+ ".": "./src/index.ts"+ },+ "dependencies": {+ "@hypit/component-kit": "workspace:*",+ "@hypit/elaborator": "workspace:*",+ "@hypit/markup": "workspace:*",+ "@hypit/protocol": "workspace:*"+ }+}diff --git a/packages/author-kit/src/index.ts b/packages/author-kit/src/index.tsnew file mode 100644index 00000000..23b7455d--- /dev/null+++ b/packages/author-kit/src/index.ts@@ -0,0 +1,59 @@+/**+ * Stable framework-facing author-package surface.+ *+ * Domain values stay with their owning packages; this module only joins the small set of framework+ * interfaces needed to declare a Module, lower a Surface into a Fragment and provide deterministic+ * handlers. It performs no discovery, registration, installation or execution.+ */+export {+ canonicalize,+ isResourceId,+ sameType,+} from "@hypit/protocol";+export type {+ BlobRef,+ CanonicalValue,+ ModuleManifest,+ ModuleRef,+ ProducerRef,+ StoredValue,+ TypeRef,+ TypedRecord,+ ValueSchema,+} from "@hypit/protocol";++export type {+ ComponentPackage,+ ProducerFacet,+ ProducerHandler,+ ProducerHandlerContext,+ ProducerHandlerResult,+ TypeValidatorFacet,+ TypeValidatorHandler,+} from "@hypit/component-kit";++export {+ sealGraphFragment,+} from "@hypit/elaborator";+export type {+ FragmentOperation,+ GraphFragment,+} from "@hypit/elaborator";++export {+ assertAttributes,+ assertEmptyElement,+ assertExactAttributes,+ createMarkupSurfaceHostFacet,+ localName,+ optionalTextAttribute,+ textAttribute,+} from "@hypit/markup";+export type {+ MarkupSurfaceHostFacetOptions,+ StructuredElement,+ StructuredSurfaceHandler,+ SurfaceComponentDraft,+ SurfaceRecordDraft,+ SurfaceResolvedReference,+} from "@hypit/markup";diff --git a/packages/cli/src/distribution.ts b/packages/cli/src/distribution.tsindex 4c0c88e7..4a1c7b3b 100644--- a/packages/cli/src/distribution.ts+++ b/packages/cli/src/distribution.ts@@ -11,6 +11,10 @@ export type CliCompilerOptions = {readonly workspaceRoot?: string;/** Additional Host-authorized asset roots. These never widen Source imports. */readonly assetRoots?: readonly string[];+ /** Project-owned package resolution boundary for package Source imports. */+ readonly packageRoot?: string;+ /** Read-only application Distribution that owns the reserved @hypit namespace. */+ readonly distributionPackageRoot?: string;readonly packageContributions: readonly NodePackageContribution[];};@@ -37,6 +41,8 @@ export type CliDistribution = {*/discoverSourcePackages?(path: string, options?: {readonly workspaceRoot?: string;+ readonly packageRoot?: string;+ readonly distributionPackageRoot?: string;/** Exact packages already trusted for the current fixed-point discovery pass. */readonly packages?: readonly LoadedPackage[];}): Promise<{diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.tsindex fa8b9bec..6920f00c 100644--- a/packages/cli/src/main.ts+++ b/packages/cli/src/main.ts@@ -251,6 +251,10 @@ export async function runCli(const compiler = distribution.createCompiler({...(effectiveWorkspaceRoot === undefined ? {} : { workspaceRoot: effectiveWorkspaceRoot }),...(args.assetRoots.length === 0 ? {} : { assetRoots: args.assetRoots }),+ packageRoot: sourcePackageRoot,+ ...(distribution.packageRoot === undefined+ ? {}+ : { distributionPackageRoot: distribution.packageRoot }),packageContributions,});const workspace = await compiler.openFile(args.source);diff --git a/packages/cli/src/source-discovery.ts b/packages/cli/src/source-discovery.tsindex 9ed4edc9..3063e195 100644--- a/packages/cli/src/source-discovery.ts+++ b/packages/cli/src/source-discovery.ts@@ -3,7 +3,7 @@ import { dirname, isAbsolute, relative, resolve } from "node:path";import { authorFrontendsFromHostFacets, prepareAuthorSource } from "@hypit/elaborator";import type { AuthorFrontend } from "@hypit/elaborator";-import { physicalPackageName } from "@hypit/package-loader-node";+import { physicalPackageName, resolveNodePackageSource } from "@hypit/package-loader-node";import type { LogicalPackageAddress, LoadedPackage } from "@hypit/package-loader-node";import { modulePackageAbi } from "@hypit/protocol";import { prepareRunSource, runFragmentHostAbi, runFrontendsFromHostFacets } from "@hypit/run";@@ -21,13 +21,6 @@ function selectedPackage(request: string): string {return physicalPackageName(request);}-function relativeSource(importer: string, request: string): string {- if (!request.startsWith("./") && !request.startsWith("../")) {- throw new Error(`Source import ${request} in ${importer} must be relative`);- }- return resolve(dirname(importer), request);-}-function addressKey(value: LogicalPackageAddress): string {return `${value.abi}\u0000${value.name}`;}@@ -41,6 +34,8 @@ export async function discoverSourcePackages(sourcePath: string,options: {readonly workspaceRoot?: string;+ readonly packageRoot?: string;+ readonly distributionPackageRoot?: string;readonly packages?: readonly LoadedPackage[];readonly bootstrapAuthorFrontends?: readonly AuthorFrontend[];readonly bootstrapRunFrontends?: readonly RunFrontend[];@@ -48,6 +43,7 @@ export async function discoverSourcePackages(): Promise<{ readonly selected: readonly string[]; readonly logical: readonly LogicalPackageAddress[] }> {const canonicalSource = await realpath(resolve(sourcePath));const root = await realpath(resolve(options.workspaceRoot ?? dirname(canonicalSource)));+ const packageRoot = resolve(options.packageRoot ?? root);if (!isWithin(root, canonicalSource)) throw new Error(`Source ${canonicalSource} is outside workspace root ${root}`);const packages = options.packages ?? [];@@ -82,13 +78,35 @@ export async function discoverSourcePackages(logical.set(addressKey(address), address);selected.add(physical ?? selectedPackage(address.name));};- const discover = async (path: string): Promise<void> => {+ const resolveImportedSource = (+ importer: string,+ importerRoot: string,+ request: string,+ ): { readonly source: string; readonly root: string } => {+ if (request.startsWith("./") || request.startsWith("../")) {+ return { source: resolve(dirname(importer), request), root: importerRoot };+ }+ const located = resolveNodePackageSource(request, {+ from: importer,+ workspaceRoots: [packageRoot],+ ...(options.distributionPackageRoot === undefined+ ? {}+ : { distributionRoots: [options.distributionPackageRoot] }),+ externalRoots: [],+ allowExternal: false,+ });+ return { source: located.source, root: located.root };+ };+ const discover = async (path: string, sourceRoot: string): Promise<void> => {const canonical = await realpath(path);- if (!isWithin(root, canonical)) throw new Error(`Source ${canonical} is outside workspace root ${root}`);+ const canonicalRoot = await realpath(sourceRoot);+ if (!isWithin(canonicalRoot, canonical)) {+ throw new Error(`Source ${canonical} is outside its source root ${canonicalRoot}`);+ }if (visited.has(canonical)) return;visited.add(canonical);const text = await readFile(canonical, "utf8");- const name = relative(root, canonical);+ const name = relative(canonicalRoot, canonical);const header = parseSourceHeader(name, text);const authors = authorFrontends.filter((item) => item.frontend.id === header.using);const runs = runFrontends.filter((item) => item.frontend.id === header.using);@@ -106,7 +124,10 @@ export async function discoverSourcePackages(for (const request of discovery.modules) {requireLogical({ abi: modulePackageAbi, name: request }, moduleOwners.get(request));}- for (const child of discovery.sources) await discover(relativeSource(canonical, child.from));+ for (const child of discovery.sources) {+ const imported = resolveImportedSource(canonical, canonicalRoot, child.from);+ await discover(imported.source, imported.root);+ }return;}const owner = runs[0]!;@@ -117,10 +138,11 @@ export async function discoverSourcePackages(for (const item of discovery.imports) {requireLogical({ abi: runFragmentHostAbi, name: item.from }, fragmentOwners.get(item.from));}- await discover(relativeSource(canonical, discovery.author.source));+ const imported = resolveImportedSource(canonical, canonicalRoot, discovery.author.source);+ await discover(imported.source, imported.root);};- await discover(canonicalSource);+ await discover(canonicalSource, root);return {selected: [...selected].sort(),logical: [...logical.values()].sort((left, right) => addressKey(left).localeCompare(addressKey(right))),diff --git a/packages/cli/src/source-packages.ts b/packages/cli/src/source-packages.tsindex 3d0d8174..77ecdee1 100644--- a/packages/cli/src/source-packages.ts+++ b/packages/cli/src/source-packages.ts@@ -30,6 +30,10 @@ async function discover() {const selection = await distribution.discoverSourcePackages?.(options.source, {...(options.workspaceRoot === undefined ? {} : { workspaceRoot: options.workspaceRoot }),+ packageRoot: options.packageRoot,+ ...(options.distributionPackageRoot === undefined+ ? {}+ : { distributionPackageRoot: options.distributionPackageRoot }),packages,});if (selection === undefined) throw new Error("this Distribution cannot discover Source packages");diff --git a/packages/compiler-node/README.md b/packages/compiler-node/README.mdindex 7aa2d744..213169c8 100644--- a/packages/compiler-node/README.md+++ b/packages/compiler-node/README.md@@ -22,10 +22,12 @@ embedding application must register the manifests and matching Frontend/Surfacehas chosen to trust.`NodeCompiler` requires the host-neutral `Workspace` contract. The reference CLI explicitly selects-`@hypit/workspace-fs-node`, where relative recursive Source imports are confined to one canonical-root, symlink escapes are rejected and each edge is locked to the first bytes read for that-compilation. A browser, Git, memory or remote Host can supply another Workspace without-changing Frontends, Surfaces, Source Closure identity or Core.+`@hypit/workspace-fs-node`, where every recursive Source import is confined to the canonical root+that owns the importing SourceUnit, symlink escapes are rejected and each edge is locked to the+first bytes read for that compilation. The Host may explicitly mount another Source root; the+Compiler sees only the resulting Workspace units and does not know whether that root came from an+installed data package, Git, memory or another source. Another Host can supply a different+Workspace without changing Frontends, Surfaces, Source Closure identity or Core.The Workspace session owns a separate Source Asset capability. A Frontend/Surface may request anasset and assign its exact media type, but it never receives a path, filesystem handle or ambientdiff --git a/packages/compiler-node/test/compiler.test.ts b/packages/compiler-node/test/compiler.test.tsindex 4db10bcd..bea0b43b 100644--- a/packages/compiler-node/test/compiler.test.ts+++ b/packages/compiler-node/test/compiler.test.ts@@ -623,6 +623,38 @@ test("an asset root widens bytes without widening Source imports", async () => {}), (error: unknown) => error instanceof WorkspaceError && error.code === "SOURCE_OUTSIDE_ROOT");});+test("a Host-resolved Source keeps relative imports inside its own read boundary", async () => {+ const parent = await mkdtemp(join(tmpdir(), "hypit-external-source-"));+ const project = join(parent, "project");+ const packageRoot = join(parent, "package");+ await mkdir(project);+ await mkdir(packageRoot);+ const entryPath = join(project, "main.svml");+ const kitPath = join(packageRoot, "kit.svs");+ const childPath = join(packageRoot, "child.svs");+ const outsidePath = join(parent, "outside.svs");+ await writeFile(entryPath, "entry", "utf8");+ await writeFile(kitPath, "kit", "utf8");+ await writeFile(childPath, "child", "utf8");+ await writeFile(outsidePath, "outside", "utf8");+ const workspace = await new NodeFilesystemWorkspace({+ root: project,+ externalSourceResolver(_importer, request) {+ assert.equal(request.from, "@acme/kits/example");+ return { root: packageRoot, source: kitPath };+ },+ }).open(entryPath);+ const kit = await workspace.resolveSource(workspace.entry, {+ from: "@acme/kits/example",+ alias: "kit",+ });+ assert.equal((await workspace.resolveSource(kit, { from: "./child.svs", alias: "child" })).text, "child");+ await assert.rejects(+ async () => await workspace.resolveSource(kit, { from: "../outside.svs", alias: "outside" }),+ (error: unknown) => error instanceof WorkspaceError && error.code === "SOURCE_OUTSIDE_ROOT",+ );+});+test("filesystem and in-memory Workspaces load identical asset bytes", async () => {const root = await mkdtemp(join(tmpdir(), "hypit-workspace-equivalence-"));const file = join(root, "main.svml");diff --git a/packages/component-kit/README.md b/packages/component-kit/README.mdindex b84925f7..f050eabb 100644--- a/packages/component-kit/README.md+++ b/packages/component-kit/README.md@@ -13,3 +13,85 @@ SDK.This is dependency inversion, not a sandbox. Until components run in an isolated Worker, selectedJavaScript packages remain trusted code and may still possess ambient authority from their process.++## Wiring a project Author Package++A component normally lives in the video's `packages/` and is installed through that project's+ordinary package manager. Use the owner's scope, such as `@studio/score-strip`; the active+Distribution reserves `@hypit/*`. A Source imports the package's logical Module ABI, for example+`<import as="score" from="@studio/score-strip@1"/>`. That `1` is not its npm release version.++External Author Packages use the released Distribution's public subpaths. The small framework-facing+surface is `hypit/author-kit`; domain values continue to come from their own owners:++| Owner | Interface |+| --- | --- |+| `hypit/author-kit` | Module declarations, deterministic handlers, sealed Fragments and Markup Surface handlers |+| `hypit/temporal-markup` | author-time semantic Window/Instant projection helpers |+| `hypit/composition`, `hypit/visual-ir` | peer Track values and renderer-independent visual representation |+| `hypit/studio-adapter` (optional, in Companion code) | editor entity projection, Inspector bindings and executed temporal lineage |++The Author Package keeps one development dependency on `hypit`, compiles its activation to+JavaScript, and publishes only its own files. The active Distribution supplies these subpaths at+execution, so a component does not carry a second Core or choose its own framework version. This+package remains the internal deterministic-handler owner; `hypit/author-kit` is the deliberately+small public composition boundary, not a facade for every video domain.++An ESM package names its activation entry in `package.json`, for example+`"hypit": { "activation": "./dist/activation.js" }`. The built files, preview assets and package+dependencies must actually be included. A TypeScript entry can be used when the selected development+Host supports it; a compiled JavaScript entry avoids depending on a TypeScript loader.++The activation module connects the implementation pieces; this is a wiring excerpt, assuming the+local Manifest, ComponentPackage and Surface declarations/handlers already exist:++```ts+import { createMarkupSurfaceHostFacet } from "hypit/author-kit";+import { manifest, moduleRef, surfaces } from "./manifest.js";+import { component } from "./component.js";+import { decodeTrack } from "./surface.js";++export const hypitPackage = {+ format: "hypit.node-package@1" as const,+ modules: [{ manifest }],+ components: [component],+ hostFacets: surfaces.map((declaration) => createMarkupSurfaceHostFacet({+ module: moduleRef, declaration, handler: decodeTrack,+ })),+};+export default hypitPackage;+```++If several Surfaces have different handlers, bind each declaration to its actual handler instead of+mapping them all to `decodeTrack`. Surface metadata is registered through the Markup Host facet;+it does not make Markup syntax part of the semantic Module Manifest.++Structured handlers return `records`, `components`, `fragments` and optionally explicit `exports`.+A resolved input contains its nominal `type` and graph `ref`; only authored values necessarily carry+an inline `record`. A future generated image has a reference, not image bytes available during+Source compilation. Decode Recipes or Styles from inline authored values, and retain produced+inputs as graph edges.++Component output mappings use **Fragment export name → public Source name**. If a Fragment exports+`track`, the mapping is ``outputs: { track: `${id}.track` }``; choosing another public name does not+rename the Fragment port. The Manifest's Producer ports, Fragment wiring and handler output names+must agree for that operation.++Read the closest installed implementation for the behavior being authored: Emoji Reveal for a+persistent event-driven strip, Media Track for sampling and transitions, Caption Fine for a+schedule/render split. Their package-local files supply concrete patterns without requiring a+monorepo checkout. A new component owns its own mechanics, not a fork of the framework loader or+Runtime.++## Optional Studio presentation++A component can render through the ordinary Track protocol without custom editor behavior. When it+needs meaningful timeline entities or Inspector fields, put a Companion in a separate file and+merge `createStudioTrackCompanionHostFacet(companions)` into the same activation's `hostFacets`.+Retain the existing Module, Producer and Surface contributions. The selected project's package+supplies the extension; do not edit Studio's registry or add editor metadata to the domain Manifest.++The [Studio Adapter README](../studio-adapter/README.md) owns the working declaration and activation+example. Expose any required deterministic schedule/program values through actual Surface outputs,+and retain the real temporal input edges. The Companion describes those facts and writable Source+parameters; it neither renders the video nor performs Source filesystem writes.diff --git a/packages/composition/README.md b/packages/composition/README.mdindex 0ff9c4e5..85eb1246 100644--- a/packages/composition/README.md+++ b/packages/composition/README.md@@ -1,3 +1,48 @@# `@hypit/composition`Provider-neutral visual and audio Track contracts and their final Composition.++## VisualTrack++`sealVisualTrack` accepts `id`, `programSpaceId`, `visualIr: VISUAL_IR_V1` and `presents` and returns+a value with `kind: "visual"`. `assertVisualTrackIdentity(track, space)` also checks it against a+specific ProgramSpace. Both functions are exported from this package.++Each Present supplies:++| Field | Meaning |+| --- | --- |+| `id`, optional `subjectId` | Appearance identity and, when useful, the domain entity it depicts |+| `span` | `{ startFrame, endFrameExclusive }` in program frames |+| `stacking` | `{ order, tieBreak }`, absolute paint order across Presents |+| `elements` | One rooted element tree owned by the Present |++Higher stacking order paints later. Element `order` values are distinct within a Present and+determine order inside its tree. A child names+its `parent`; its position is relative to that parent. Root positioning is relative to the Canvas.+Animation keyframes use `atFrame` offsets from the Present's start. Media sampling targets use the+same local frame origin and map to exact source frames.++The exported `VisualElement` union covers `box`, `mask`, `text`, `text-flow`, `path-text`, `image`,+`video` and `surface`. Text carries exact FontArtifactRef values; images and videos carry BlobRefs;+`surface` carries a CompositableSurfaceRef. The schema and exported TypeScript types in `src/track.ts`+give each shape. `hypit vocabulary --visual visual-track` and focused element queries expose those+schemas through the installed Distribution.++## AudioTrack++An AudioTrack contributes explicit clips with source audio artifacts, source sample ranges, target+sample ranges, gain, fades and playback. Target positions use the ProgramSpace's canonical 48 kHz+sample domain. Use `programSpaceSampleFrames` and the temporal/media helpers when converting an+authored event into that domain. Source timing and target timing are separate.++`sealAudioTrack` and `assertAudioTrackIdentity` are the corresponding public constructors/checks.+An Author Package can publish visual and audio Tracks as separate Outputs; the composition includes+each selected Output explicitly.++## Composition++A Composition carries its id, Canvas with clear color, and peer Tracks. The Tracks retain their+ProgramSpace identity; assembly and rendering receive the corresponding time domain separately.+`@hypit/film` is one author-facing way to assemble it;+`@hypit/render-hyperframes` consumes it to produce a video.diff --git a/packages/gpt-image-kits/README.md b/packages/gpt-image-kits/README.mdnew file mode 100644index 00000000..1df9dfde--- /dev/null+++ b/packages/gpt-image-kits/README.md@@ -0,0 +1,79 @@+# `@hypit/gpt-image-kits`++Data-only Text Templates for image direction. `phone-ugc-v1` carries one fixed iPhone-video capture+language, with current-shot direction supplied as ordinary Text. It introduces no model wrapper,+Provider, media generation, or activation hook.++## When to use phone-ugc++Use this template for images that should feel like frames from phone-shot social video: a creator,+an interview view, a lifestyle or product-use shot, or even an imagined person or animal inhabiting+a photographed world. It favors natural-looking lighting, fine texture, and a readable background+without depth-of-field blur. These are the chosen capture assumptions of this Kit, rather than+requirements imposed by GPT Image. A different capture language can use a different template or+authored Text.++The capture paragraph is a versioned English text block and remains unchanged whenever this Kit is+selected. Its skin wording is part of that whole capture direction, including for an animal or+fantastical subject. When another subject or visual form genuinely needs a different capture language,+author another Text Template instead of conditionally rewriting this one. Portrait framing stays in+the `shot` input, while beauty, styling, material and scene-specific light stay in `direction`.++| Text slot | Meaning |+| --- | --- |+| `shot` (required) | Fluent direction for framing, comfortable camera distance, subject placement and its spatial reason, including space needed by later composition. Output aspect ratio and resolution belong to model parameters. |+| `direction` (required) | Fluent direction for the subject's presence, styling, physical state, setting, materials, intended feeling, and the palette and tonal relationship across the frame. |+| `references` (optional) | What each connected reference supplies and what this image should change. |++Character, beauty, color, mood, subject position, camera distance and lighting remain fluent authored+decisions in `shot` and `direction`. The optional `references` text explains actual reference edges;+it does not create them or set model attributes. Describe a useful scene around an offset person, and+compose around later MG without asking the image model to draw that MG.++Set aspect ratio and resolution through the model's parameters. For `@hypit/gpt-image`, the example+below uses `aspect-ratio="9:16"` and `resolution="2K"` on `gpt:Image`. Those parameters are the+authoritative output shape and size, so numeric values usually need no repetition in the prompt.+Keep directional camera or orientation language in `shot` when it materially clarifies the composition.++## Use it in a project++Import the package's public Source directly. The package manager or active Distribution owns its+installed version; the Source Closure reads the exported template without copying it into the video+project or executing package code.++```svml+<?svml using="@hypit/markup@1"?>+<svml>+ <import as="text" from="@hypit/text@1"/>+ <import as="gpt" from="@hypit/gpt-image@1"/>+ <import as="ugc" source="@hypit/gpt-image-kits/phone-ugc-v1"/>++ <text:Value id="shot">+ Generate a half-body view of a woman seated slightly to the right, comfortably near the camera,+ with her face, shoulders, and gesturing hand clearly visible and naturally proportioned.+ </text:Value>+ <text:Value id="direction">+ A Latina woman in her thirties has the striking beauty and commanding presence of a leading+ Italian film actress, with broad shoulders and excellent head-to-shoulder proportions.+ Her attitude says, "Stay out of my husband's business."+ She wears a leopard-print fur coat over a black low-cut top, layered gold chains, and gold hoop+ earrings. Her dark-brown hair falls in voluminous waves; her lipstick is classic red and her+ long nails are deep red. She holds a handheld microphone while speaking to the camera, her free hand+ gesturing naturally. She sits in a leather booth in an expensive Italian restaurant, with an+ oil painting behind her, a bar farther back, and candles on a windowsill. Red upholstery and gold+ accents establish the room, while the patterned coat and black top give her figure definition.+ </text:Value>+ <text:Render id="prompt" template={ugc.phone-ugc-v1}>+ <text:Set name="shot" text={shot}/>+ <text:Set name="direction" text={direction}/>+ </text:Render>++ <gpt:Image id="portrait" prompt={prompt} aspect-ratio="9:16" resolution="2K"/>+</svml>+```++When references are needed, add `gpt:Reference` children to `gpt:Image` and a `references` Text slot+describing those same inputs, for example “Use the first image for the person's identity; create+the new camera view described here.” A reference for identity alone does not lock its camera or pose.+Keep aspect ratio, resolution, model options, and Resource bindings on their owning Surfaces. The+ordinary Run selects Targets and Candidates; the Runtime Profile selects the execution Endpoint.diff --git a/packages/gpt-image-kits/kits/phone-ugc-v1.svs b/packages/gpt-image-kits/kits/phone-ugc-v1.svsnew file mode 100644index 00000000..0f306cab--- /dev/null+++ b/packages/gpt-image-kits/kits/phone-ugc-v1.svs@@ -0,0 +1,34 @@+<?svml using="@hypit/text/svs@1"?>++<sheet version="1" id="phone-ugc-v1">+ text-template.phone-ugc-v1 {+ separator: paragraph;+ }++ text-template.phone-ugc-v1.block.capture {+ kind: fixed;+ order: 10;+ text: "A photograph with the texture of real iPhone footage, captured as a single frame from a video actually shot on an iPhone. The image looks real, without an oily, overprocessed finish, and has the texture of video footage. The background is clearly visible, with no depth-of-field blur. Skin texture is natural and fine, the lighting is natural, and the image is coherent and free of visual artifacts.";+ }++ text-template.phone-ugc-v1.block.shot {+ kind: slot;+ order: 20;+ slot: shot;+ optional: false;+ }++ text-template.phone-ugc-v1.block.direction {+ kind: slot;+ order: 30;+ slot: direction;+ optional: false;+ }++ text-template.phone-ugc-v1.block.references {+ kind: slot;+ order: 40;+ slot: references;+ optional: true;+ }+</sheet>diff --git a/packages/gpt-image-kits/package.json b/packages/gpt-image-kits/package.jsonnew file mode 100644index 00000000..f9c5904e--- /dev/null+++ b/packages/gpt-image-kits/package.json@@ -0,0 +1,15 @@+{+ "name": "@hypit/gpt-image-kits",+ "version": "0.0.0-dev",+ "license": "SEE LICENSE IN LICENSE",+ "private": true,+ "type": "module",+ "exports": {+ "./phone-ugc-v1": "./kits/phone-ugc-v1.svs"+ },+ "files": ["kits", "README.md"],+ "devDependencies": {+ "@hypit/svs": "workspace:*",+ "@hypit/text": "workspace:*"+ }+}diff --git a/packages/package-loader-node/README.md b/packages/package-loader-node/README.mdindex bd9227d9..96583d2a 100644--- a/packages/package-loader-node/README.md+++ b/packages/package-loader-node/README.md@@ -3,9 +3,15 @@Loads installed Hypit packages selected by source discovery or a Runtime Profile.The user's package manager owns installation, versions and package bytes. This loader resolves only-the requested packages, imports their declared `hypit.activation` entry and validates the-contribution boundary consumed by Hypit. It never scans the dependency tree for plugins and is-not a package manager or registry.+the requested packages. An implementation package selected by Source discovery or a Runtime+Profile may expose `hypit.activation`; the loader imports that entry and validates the contribution+boundary consumed by Hypit. It never scans the dependency tree for plugins and is not a package+manager or registry.++A data-only package may instead expose an exact Source subpath through ordinary package `exports`.+The Host can resolve that one requested file without importing `hypit.activation` or granting the+package executable authority. Package-internal relative Sources and assets remain confined to the+package root. Executable activation and Source-data lookup are deliberately separate operations.Module dependencies declared by selected packages are loaded from ordinary installed dependencies.Syntax, components and Runtime facets remain inert until a matching Host ABI consumes them.diff --git a/packages/package-loader-node/src/distribution-resolution.ts b/packages/package-loader-node/src/distribution-resolution.tsindex b5043759..5fdb112b 100644--- a/packages/package-loader-node/src/distribution-resolution.ts+++ b/packages/package-loader-node/src/distribution-resolution.ts@@ -46,6 +46,18 @@ function distributionPackageEntry(root: string, specifier: string): string | undreturn declared === undefined ? undefined : resolve(packageRoot, declared);}+function distributionPublicEntry(root: string, specifier: string): string | undefined {+ if (!specifier.startsWith("hypit/")) return undefined;+ const manifestPath = join(root, "package.json");+ const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as {+ readonly name?: string;+ readonly exports?: Readonly<Record<string, string>>;+ };+ if (manifest.name !== "hypit") return undefined;+ const declared = manifest.exports?.[`./${specifier.slice("hypit/".length)}`];+ return declared === undefined ? undefined : resolve(root, declared);+}+/*** Let external project activations import official packages from a read-only Distribution checkout.* The @hypit namespace belongs to the active Distribution and cannot be shadowed by project installs.@@ -59,7 +71,7 @@ export function installDistributionPackageResolution(roots: readonly string[]):const rootUrls = installed.map((root) => pathToFileURL(`${root}/`).href);registerHooks({resolve(specifier, context, nextResolve) {- if (specifier.startsWith("@hypit/")) {+ if (specifier.startsWith("@hypit/") || specifier.startsWith("hypit/")) {// A contributor checkout may resolve through workspace links. An installed// monolithic Distribution resolves from its own packages/services tree.// Accept ordinary resolution only when its real target remains inside this@@ -73,7 +85,9 @@ export function installDistributionPackageResolution(roots: readonly string[]):// Try the explicit Distribution resolvers below.}for (const root of installed) {- const entry = distributionPackageEntry(root, specifier);+ const entry = specifier.startsWith("@hypit/")+ ? distributionPackageEntry(root, specifier)+ : distributionPublicEntry(root, specifier);if (entry !== undefined) return { url: pathToFileURL(entry).href, shortCircuit: true };}throw new Error(`Active Hypit Distribution does not provide ${specifier}`);@@ -100,7 +114,7 @@ export function installExternalPackageResolution(roots: readonly string[]): voidconst parentUrls = externalInstalled.map((root) => pathToFileURL(join(root, "__hypit_external__.mjs")).href);registerHooks({resolve(specifier, context, nextResolve) {- if (specifier.startsWith("@hypit/") || !barePackageSpecifier(specifier)) {+ if (specifier.startsWith("@hypit/") || specifier.startsWith("hypit/") || !barePackageSpecifier(specifier)) {return nextResolve(specifier, context);}try {diff --git a/packages/package-loader-node/src/index.ts b/packages/package-loader-node/src/index.tsindex 868a1411..3617eff7 100644--- a/packages/package-loader-node/src/index.ts+++ b/packages/package-loader-node/src/index.ts@@ -16,9 +16,11 @@ export {locateNodePackage,resolveNodePackageExecutable,resolveNodePackageResource,+ resolveNodePackageSource,} from "./location.js";export type {LocatedNodePackage,+ LocatedNodePackageSource,LocateNodePackageOptions,} from "./location.js";export type * from "./types.js";diff --git a/packages/package-loader-node/src/location.ts b/packages/package-loader-node/src/location.tsindex 095b0370..d73a8a26 100644--- a/packages/package-loader-node/src/location.ts+++ b/packages/package-loader-node/src/location.ts@@ -11,6 +11,13 @@ export type LocatedNodePackage = {};};+export type LocatedNodePackageSource = {+ readonly specifier: string;+ readonly package: string;+ readonly root: string;+ readonly source: string;+};+export type LocateNodePackageOptions = {/** File or module URL whose owning package is requesting the dependency. */readonly from: string | URL;@@ -59,6 +66,23 @@ function packageName(value: string): string {return value;}+function packageSourceAddress(value: string): { readonly name: string; readonly subpath: string } {+ if (value.startsWith(".") || value.startsWith("/") || value.startsWith("#") || value.includes(":")) {+ throw new Error(`${value} must be one npm package Source export`);+ }+ const parts = value.split("/");+ const name = value.startsWith("@")+ ? parts.length >= 2 ? `${parts[0]}/${parts[1]}` : ""+ : parts[0] ?? "";+ const subpath = value.startsWith("@") ? parts.slice(2).join("/") : parts.slice(1).join("/");+ packageName(name);+ if (subpath.length > 0+ && subpath.split("/").some((part) => part.length === 0 || part === "." || part === "..")) {+ throw new Error(`${value} has an invalid package Source export path`);+ }+ return { name, subpath };+}+function fromPath(value: string | URL): string {return value instanceof URL || value.startsWith("file:") ? fileURLToPath(value) : resolve(value);}@@ -198,6 +222,40 @@ export function resolveNodePackageResource(return packageFile(locateNodePackage(name, options), relativePath, `${name} resource path`);}+/**+ * Resolve one explicitly imported Source through the owning package's standard `exports` map.+ * This reads package data only; it never imports `hypit.activation` or executes package code.+ */+export function resolveNodePackageSource(+ specifier: string,+ options: LocateNodePackageOptions,+): LocatedNodePackageSource {+ const address = packageSourceAddress(specifier);+ const located = locateNodePackage(address.name, options);+ const manifestPath = join(located.root, "package.json");+ const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as {+ readonly name?: unknown;+ readonly exports?: unknown;+ };+ if (manifest.name !== address.name) throw new Error(`${manifestPath} does not describe ${address.name}`);+ const key = address.subpath.length === 0 ? "." : `./${address.subpath}`;+ let declared: unknown;+ if (typeof manifest.exports === "string") {+ if (key === ".") declared = manifest.exports;+ } else if (manifest.exports !== null && typeof manifest.exports === "object" && !Array.isArray(manifest.exports)) {+ declared = (manifest.exports as Readonly<Record<string, unknown>>)[key];+ }+ if (typeof declared !== "string") {+ throw new Error(`${address.name} does not export Source ${key}`);+ }+ return {+ specifier,+ package: address.name,+ root: located.root,+ source: packageFile(located, declared, `${address.name} Source export ${key}`),+ };+}+/** Resolve a command from the package's standard npm `bin` declaration. */export function resolveNodePackageExecutable(name: string,diff --git a/packages/package-loader-node/test/distribution-resolution.test.ts b/packages/package-loader-node/test/distribution-resolution.test.tsnew file mode 100644index 00000000..67cccf81--- /dev/null+++ b/packages/package-loader-node/test/distribution-resolution.test.ts@@ -0,0 +1,12 @@+import assert from "node:assert/strict";+import test from "node:test";++import { installDistributionPackageResolution } from "../src/distribution-resolution.js";++test("an external Author Package imports the active Distribution public API", async () => {+ installDistributionPackageResolution([process.cwd()]);+ const author = await import(String("hypit/author-kit")) as { readonly sealGraphFragment?: unknown };+ const composition = await import(String("hypit/composition")) as { readonly sealVisualTrack?: unknown };+ assert.equal(typeof author.sealGraphFragment, "function");+ assert.equal(typeof composition.sealVisualTrack, "function");+});diff --git a/packages/package-loader-node/test/location.test.ts b/packages/package-loader-node/test/location.test.tsindex 8a00038e..0d6df09e 100644--- a/packages/package-loader-node/test/location.test.ts+++ b/packages/package-loader-node/test/location.test.ts@@ -9,6 +9,7 @@ import {locateNodePackage,resolveNodePackageExecutable,resolveNodePackageResource,+ resolveNodePackageSource,} from "@hypit/package-loader-node";async function machinePackage(@@ -79,3 +80,34 @@ test("machine npm fallback preserves ESM import conditions", async () => {await rm(machine, { recursive: true, force: true });}});++test("package Source resolution reads one public export without activating package code", async () => {+ const project = await mkdtemp(join(tmpdir(), "hypit-package-source-project-"));+ try {+ const root = await machinePackage(project, "@acme/image-kits", {+ version: "1.2.3",+ type: "module",+ exports: {+ ".": "./activation-that-must-not-run.mjs",+ "./phone-ugc-v1": "./kits/phone-ugc-v1.svs",+ },+ hypit: { activation: "./activation-that-must-not-run.mjs" },+ }, {+ "activation-that-must-not-run.mjs": "throw new Error('activation ran');\n",+ "kits/phone-ugc-v1.svs": "<?svml using=\"@hypit/svs@1\"?>\n<sheet version=\"1\"/>\n",+ });+ const options = { from: join(project, "main.svml") } as const;+ assert.deepEqual(resolveNodePackageSource("@acme/image-kits/phone-ugc-v1", options), {+ specifier: "@acme/image-kits/phone-ugc-v1",+ package: "@acme/image-kits",+ root: await realpath(root),+ source: join(await realpath(root), "kits", "phone-ugc-v1.svs"),+ });+ assert.throws(+ () => resolveNodePackageSource("@acme/image-kits/private", options),+ /does not export Source/u,+ );+ } finally {+ await rm(project, { recursive: true, force: true });+ }+});diff --git a/packages/studio-adapter/README.md b/packages/studio-adapter/README.mdindex ab7c8977..a7f58948 100644--- a/packages/studio-adapter/README.md+++ b/packages/studio-adapter/README.md@@ -2,7 +2,111 @@The stable companion-package ABI understood by Hypit Studio. It carries onlypresentation, lineage, inspector and interaction DTOs plus helpers that do not-encode the official video UI policy. Domain packages do not depend on it.+encode the official video UI policy. Domain computation and manifests do not depend on it;+package activation can combine domain facets with a separate Companion implementation.++## A minimal project Track Companion++Suppose `@studio/score-strip@1` already owns a `track` Surface that emits a public VisualTrack and+accepts a literal string `label` attribute. The Companion can reuse generic terminal entities while+adding package-specific presentation and one Inspector field:++```ts+import { compositionTypes } from "@hypit/composition";+import type { StudioTrackCompanion } from "@hypit/studio-adapter";++export const companions: readonly StudioTrackCompanion[] = [{+ id: "score-strip",+ role: "track",+ output: {+ type: compositionTypes.visualTrack,+ surface: "track",+ modules: [{ name: "@studio/score-strip", version: "1" }],+ },+ family: "score-strip",+ label: "Score strip",+ icon: "ranking",+ tone: "orange",+ lane: { heightPx: 64 },+ poster: { source: "surface-preview" },+ bindings: [{ name: "label", writable: true }],+ inspector: [{+ binding: "label",+ label: "Label",+ domain: "how",+ section: { id: "content", label: "Content" },+ control: "text",+ }],+}];+```++The names and lane height are this example's choices. Use the real Module ABI, Surface name,+nominal output Type and authored input names of the component. A Companion does not create a new+author attribute. Omitting `project` uses generic terminal entities; `poster` adds the declared+Surface preview when one exists, without changing the component's rendered video.++Merge the facet into the package's existing activation. In this example `authorContribution`+exports its existing modules, deterministic component and Markup facets:++```ts+import { createStudioTrackCompanionHostFacet } from "@hypit/studio-adapter";+import authorContribution from "./author-activation.js";+import { companions } from "./studio.js";++export default {+ ...authorContribution,+ hostFacets: [+ ...(authorContribution.hostFacets ?? []),+ createStudioTrackCompanionHostFacet(companions),+ ],+};+```++Point the package's existing `hypit.activation` at that combined export and include the compiled+Companion file in the package. Keep the real modules, Producers and Surface facets; a Companion-only+replacement would remove the component itself. Use the active Distribution's adapter ABI, as+described in the [Studio README](../studio/README.md), rather than a `workspace:*` dependency in an+external project.++Studio loads facets from packages selected by the Source closure alongside the Distribution's+explicit official Companion selection. It qualifies this local id as+`@studio/score-strip#score-strip`. There is no extra Studio Profile, plugin scan or Core registration.+Restart the Studio process after changing activation or package code.++## Project domain entities and material++A terminal VisualTrack is enough for generic display. When it loses meaningful domain structure,+publish a deterministic schedule/program output from the same Surface and name its port in+`requiredValues`. Inside `project(context)`, retrieve it with `requiredSurfaceValue(context, "schedule")`.+The port must exist in the Surface's public output mappings; inventing a port name in a Companion+does not make an internal Producer value observable. `requiredReferencedValue(context, input, type)`+instead follows one exact typed author reference, such as a CaptionDocument.++`project` returns `StudioEntityDraft[]`. Each entity has an id, authored identity, display title and+ordered layers, `startFrame`, `endFrameExclusive` and `stackOrder`. Useful optional fields include:++| Field/helper | Purpose |+| --- | --- |+| `presentation` | Name the entity's role and choose `standard`, `group` or `point` chrome |+| `textLayer(text)` | Put explicit domain text in the timeline body |+| `previewLayer(artifactPreview(kind, resource), layout)` | Show a declared image/video/audio Resource with a finite layout; Studio resolves transport |+| `renderIds` | Relate an entity to its actual rendered elements |+| `parameterReferences` | Select exact per-entity authored references, such as the Style really used by this Cue |+| `temporal` | Carry the executed Instant/Window lineage and its edit authority |+| `lane` and Companion `attachments` | Put child entities on a declared additional lane, with its own bindings and Inspector |+| `childEntities` / `authoredChildFor` | Resolve children from public identity and exact Spec Types rather than source order guesses |++Use the program's frame space and half-open intervals. Persistent visibility and its activation are+different facts: a board item can remain visible until the board ends while its reveal occupies only+a short child interval. Expose that distinction rather than making a long rectangle imply a long+entrance animation. Qualify child ids across Track instances; never use an array index as authored+identity merely because it currently lines up.++Read [Ranking's Companion](../ranking-studio/src/index.ts) for board/reveal lanes,+[Caption Fine's](../caption-fine-studio/src/index.ts) for Cue text and Style selection, and+[Media Track's](../media-track-studio/src/index.ts) for material and occupancy.++## Preserve executed temporal lineage`StudioTrackCompanionContext.temporalBindings` exposes the executed Instant/Window records in the selectedTrack closure, including projection expressions, source identity and direct consumer inputs.@@ -26,14 +130,23 @@ Studio then recovers the Source range from the typed observed Record, without orA project companion contributes package-local Track Companion ids through`createStudioTrackCompanionHostFacet()`. The Host qualifies them with the selectedphysical package identity, so executable package code cannot impersonate an-official Companion. Project profiles select those packages explicitly; Studio-does not scan `node_modules` for plugins.+official Companion. The Source closure selects project packages; Studio does not+scan `node_modules` for plugins or use Runtime Profiles to select Companions.The same host facet can contribute Film and Script boundary companions. A Film companion declaresthe references that select one semantic axis and its terminal Tracks. A Script companion owns rawsource observation and marker adjustment. Studio core only matches and invokes these declarations;it does not import either domain package.+For a domain item whose Spec is consumed beside a Window or Instant, call+`temporalLineageFor(context, item.id, "window")` using the actual projection input name. Attach the+returned lineage to that entity; the input may instead be `activation`, `outer` or another declared+port. Studio derives common timeline gestures from endpoint authority. No matching lineage means+no inferred semantic edit; several matching edges require resolving the ambiguity in the component+projection. Visible frame coincidence is not a source relationship.++## Expose authored parameters deliberately+Inspector editing deliberately has two declarations:- `bindings` names exact author endpoints, including explicit reference paths@@ -55,3 +168,14 @@ Their codec is the author language (`@hypit/svs` for Recipe values), not aCompanion callback. Companions cannot inject DOM, CSS, parsing code or filesystemmutations. Official companions also use explicit field tables: an undeclarednew domain property fails Companion loading instead of inheriting UI from its name.++`referenced` follows declared authored-element references; `recipe` names an explicit path through+authored references to one SVS Recipe and its admitted properties. These paths are independent of+the `inspector` field table. Keep shared values shared: editing a Recipe affects its consumers, while+an entity-specific `parameterReferences` override must identify the actual authored value it uses.++Verify the integration in an ordinary Run: the intended Module/Surface matches, the expected entity+is selected, its field reaches the correct Source or Recipe, and changing it recomputes the preview.+For semantic handles, verify the exact marker and its other consumers too. Read-only derived timing+is preferable to an invented inverse. The Companion explains the component; its Producers remain+responsible for identical video behavior in Studio, seeking and encoded rendering.diff --git a/packages/studio/README.md b/packages/studio/README.mdindex da8d8211..6c2c9fc7 100644--- a/packages/studio/README.md+++ b/packages/studio/README.md@@ -2,7 +2,7 @@The single official Web Studio for SVML. It opens an explicit Run Source,traces its Film or Render target back to the semantic and visual projections-Studio can edit, runs deterministic Producers only, and composites the+Studio can edit, runs deterministic Producers and explicitly permitted transient Needs, and composites theresulting Tracks with HyperFrames.```bash@@ -10,19 +10,52 @@ cd /path/to/external-video-projecthypit-studio --run build.svrun```-When `--runtime` is omitted, Studio uses the nearest Runtime selection made by-`hypit runtime use`. That selection's directory is the default environment-boundary. The upper-left library is intentionally not a filesystem browser:+When `--runtime` is omitted, Studio reads the resolved project's `.hypit/runtime`+selection made by `hypit runtime use`. It does not search parent projects for a+Profile. `--workspace` explicitly selects the project boundary; `--package-root`+overrides the author package resolution root when those locations intentionally differ.+The upper-left library is intentionally not a filesystem browser:- Source is the exact Run + Author closure and writes back only the selected file;- Tasks combine finished project Results with read-only active `BuildView` and Operation information;- Artifacts are public files exposed by project Build Results.No project manifest, Studio database, output-directory scan or inferred campaign-folder structure is involved. With no selected Runtime, Source, Preview, finished-Result tasks and Artifacts still work; only active execution status is unavailable.+folder structure is involved. With no selected Runtime, finished Result tasks and+Artifacts remain available. Preview and Source display work when the selected display+closure can resolve without Endpoint execution; active status and Provider-backed+transient processing require the selected Runtime.-Studio is an application boundary. Core and domain packages do not import it or+## Opening and editing a session++The selected targets must reach one Film and its semantic projection. Studio rejects+several distinct Films in one view; use separate Runs/sessions for those. The semantic+axis can include ordinary wordless Script Segments with media spans.++Open the URL printed by Vite. Studio requests port 5179 by default, accepts `--port`,+and Vite can choose another available port when it is occupied. Reuse that process+for edits to the same Run. The Run and loaded Author/Recipe files are watched and+recompiled together. Domain packages, Companion registry, Runtime and Result library+are opened at startup; restart this Studio process after changing those selections,+package code or imports that introduce new packages. Browser refresh does not reload+server-side package modules.++The Source pane can edit the selected `.svml`, `.svs` or `.svrun` file. The Inspector+shows project facts when no entity is selected and only declared writable fields for+the selected entity. A reference can resolve to a shared Frame or Recipe, so one edit+may affect several consumers. Structured fields use Apply/Reset for their local draft.+Check save status; source conflicts reject stale edits rather than overwrite newer files.++Timeline gestures use explicit temporal authority. Moving a shared Selection or+Moment edits Script and moves its consumers after recompilation. A parameter-based+handle edits its exact authored parameter. Fixed or derived values with no supported+inverse remain read-only. Seeing an entity does not promise every drag gesture.+Tasks and Artifacts are inspection surfaces; selecting an Artifact does not write a+Run Candidate. Use `build-record`/`satisfy` in the Run for explicit Output reuse.++## Component presentation++Studio is an application boundary. Core and domain computation do not import it orregister UI metadata. The installed Distribution explicitly selects one independentStudio Companion per supported official domain. Packages actually selected by thecurrent Source closure may contribute their own Companion facet. The application@@ -40,10 +73,10 @@ runtime, so the project does not install or lock another copy.The companion owns what its Track means: matching, required same-Surface values,entities, lane range, finite chrome, title and ordered text/material layers,-source bindings, Inspector fields and exact timeline inverses. Inspector fields+source bindings, Inspector fields and executed temporal lineage. Inspector fieldsselect real writable bindings and organize them under the Studio-owned`Where / How / When` domains, optional companion-owned pages and sections. A-source binding is never shown merely because Studio can reach it. Material layers carry an+source binding is never shown merely because Studio can reach it. Material layers carry aResource id or Surface identity, never a Studio HTTP URL. Studio always ownstime formatting and transport resolution, so chrome and material cannot hide atitle or its time.@@ -86,3 +119,6 @@ full target closure and sends the resulting HyperFrames document to the chosenrender Endpoint. A separate review Run is useful only when the author wants adifferent Candidate selection. Its path and filename carry no executionsemantics.++Read [`@hypit/studio-adapter`](../studio-adapter/README.md) for the Companion ABI,+project activation example, value projection and Inspector declarations.diff --git a/packages/studio/src/domain.ts b/packages/studio/src/domain.tsindex 5c7627dc..3de6d4ac 100644--- a/packages/studio/src/domain.ts+++ b/packages/studio/src/domain.ts@@ -16,8 +16,7 @@ import type { LoadedPackage, NodePackageContribution } from "@hypit/package-loadimport { ModulePackageRegistry, NodeCompiler } from "@hypit/compiler-node";import type { ModuleRef, ResolvedModuleClosure } from "@hypit/protocol";import { TypeValidatorRegistry } from "@hypit/validation";-import { createVideoCompiler, videoCliDistribution } from "@hypit/video-cli";-import { NodeFilesystemWorkspace } from "@hypit/workspace-fs-node";+import { createVideoCompiler, createVideoWorkspace, videoCliDistribution } from "@hypit/video-cli";export type StudioDomain = {readonly packages: readonly LoadedPackage[];@@ -99,12 +98,20 @@ export async function loadStudioDomain(input: {contributions,compiler: createVideoCompiler({workspaceRoot: input.workspaceRoot,+ packageRoot: input.packageRoot,+ ...(videoCliDistribution.packageRoot === undefined+ ? {}+ : { distributionPackageRoot: videoCliDistribution.packageRoot }),packageContributions: contributions,}),createCompiler(registry) {if (registry === undefined) {return createVideoCompiler({workspaceRoot: input.workspaceRoot,+ packageRoot: input.packageRoot,+ ...(videoCliDistribution.packageRoot === undefined+ ? {}+ : { distributionPackageRoot: videoCliDistribution.packageRoot }),packageContributions: contributions,});}@@ -113,7 +120,13 @@ export async function loadStudioDomain(input: {modules: moduleRegistry,frontends,validators,- workspace: new NodeFilesystemWorkspace({ root: input.workspaceRoot }),+ workspace: createVideoWorkspace({+ workspaceRoot: input.workspaceRoot,+ packageRoot: input.packageRoot,+ ...(videoCliDistribution.packageRoot === undefined+ ? {}+ : { distributionPackageRoot: videoCliDistribution.packageRoot }),+ }),});},closure,diff --git a/packages/temporal-markup/README.md b/packages/temporal-markup/README.mdnew file mode 100644index 00000000..322760d0--- /dev/null+++ b/packages/temporal-markup/README.md@@ -0,0 +1,61 @@+# `@hypit/temporal-markup`++Shared SVML author-time projection helpers for `@hypit/temporal`. The Surface lowers authored+Selection, Segment, Moment or explicit clock expressions to ordinary Instant projections and Window+composition. A domain consumer receives the projected values and explicit ProgramSpace; it does not+locate Script words or infer a semantic source inside its renderer.++The package exports `createTemporalWindowProjection`, `createTemporalInstantProjection`, their+attribute vocabulary, and the exact duration/instant parsers. These are helpers for component+Surfaces, not standalone author tags or a new Track.++## Window forms++A Surface using the shared Window vocabulary accepts one complete form:++| Authored attributes | Meaning |+| --- | --- |+| `during="program"` | The complete program Window. |+| `during={story.segment.opening}` | A Segment's Window. |+| `during={story.selection.proof}` | A Selection's Window, including its authored endpoint affinity. |+| `at={story.moment.reveal} for="8f"` | Start at a Moment and last eight program frames. |+| `until={story.moment.reveal} for="250ms"` | End at a Moment after a span of 250 milliseconds. |+| `start="program.start" end="moment.cue" moment={story.moment.reveal}` | Compose independently authored endpoints. |++Do not combine forms: `during="program" until={...}` is not shorthand for a shortened program.+Use explicit `start` and `end` for that relationship. Expressions can reference `program.start`,+`program.end`, `selection.start`, `selection.end`, `segment.start`, `segment.end` or `moment.cue`.+Bind the corresponding `selection`, `segment` or `moment` reference attribute when an expression+uses it. An endpoint may also be an absolute duration from program start, such as `1.5s`.++Offsets use an explicit sign and duration, for example `selection.start - 2f`. Frames and milliseconds+are integers (`8f`, `250ms`); seconds may be fractional (`1.5s`). Projection preserves the expression+and its authority. Invalid or out-of-program results are errors rather than silently clipped time.++## Instant forms++An Instant consumer has a different job: an event or activation with one temporal point.++| Authored attributes | Meaning |+| --- | --- |+| `at={story.moment.reveal}` | The authored Moment. |+| `at={story.selection.proof} boundary="start"` | An explicitly chosen Selection boundary. |+| `at={story.segment.opening} boundary="end"` | An explicitly chosen Segment boundary. |+| `instant="program.start + 8f"` | A projected clock expression. |++The domain component decides what happens after that point. An answer may remain visible, a Sequence+may replace its member, or a motion may run according to its own authored schedule. Instant projection+does not impose the event's visible duration. A component whose public role requires a Script Moment+can deliberately admit only that form; consumers need not expose unrelated temporal options.++## Component boundary++The Surface supplies an author-facing `subjectId` for the actual item whose time is being projected,+separately from graph-qualified operation ids. The graph wires the resulting Instant or Window and+ProgramSpace into the consumer. Keep projection outside the domain Producer: it consumes resolved+time and implements its own schedule or state, while the shared temporal protocol retains where that+time came from. An outer lifetime and child activations are separate inputs when a component persists+between events.++Script's `@`, `~@`, close markers and Moment syntax belong to `@hypit/script`; media playback belongs+to `@hypit/media-track`; a graphic component's reveal or preset semantics belong to that component.diff --git a/packages/video-cli/src/compiler.ts b/packages/video-cli/src/compiler.tsindex 2ac4177f..23588a0d 100644--- a/packages/video-cli/src/compiler.ts+++ b/packages/video-cli/src/compiler.ts@@ -1,13 +1,32 @@import type { CliCompilerOptions } from "@hypit/cli";import { createMarkupNodeCompiler } from "@hypit/compiler-markup-node";+import { resolveNodePackageSource } from "@hypit/package-loader-node";import { NodeFilesystemWorkspace } from "@hypit/workspace-fs-node";+export function createVideoWorkspace(options: Pick<CliCompilerOptions,+ "workspaceRoot" | "assetRoots" | "packageRoot" | "distributionPackageRoot">) {+ const packageRoot = options.packageRoot ?? options.workspaceRoot ?? process.cwd();+ return new NodeFilesystemWorkspace({+ ...(options.workspaceRoot === undefined ? {} : { root: options.workspaceRoot }),+ ...(options.assetRoots === undefined ? {} : { assetRoots: options.assetRoots }),+ externalSourceResolver(importer, request) {+ const located = resolveNodePackageSource(request.from, {+ from: importer.id,+ workspaceRoots: [packageRoot],+ ...(options.distributionPackageRoot === undefined+ ? {}+ : { distributionRoots: [options.distributionPackageRoot] }),+ externalRoots: [],+ allowExternal: false,+ });+ return { root: located.root, source: located.source };+ },+ });+}+/** Assemble the Markup compiler Host from only the packages selected for this invocation. */export function createVideoCompiler(options: CliCompilerOptions) {return createMarkupNodeCompiler(options.packageContributions, {- workspace: new NodeFilesystemWorkspace({- ...(options.workspaceRoot === undefined ? {} : { root: options.workspaceRoot }),- ...(options.assetRoots === undefined ? {} : { assetRoots: options.assetRoots }),- }),+ workspace: createVideoWorkspace(options),});}diff --git a/packages/video-cli/src/creation.ts b/packages/video-cli/src/creation.tsindex 1d8ce6fa..eef1d448 100644--- a/packages/video-cli/src/creation.ts+++ b/packages/video-cli/src/creation.ts@@ -420,6 +420,10 @@ async function segmentSpeech(source: string, segment: string, projectRoot: strin});const compiler = videoCliDistribution.createCompiler({workspaceRoot: projectRoot,+ packageRoot: projectRoot,+ ...(videoCliDistribution.packageRoot === undefined+ ? {}+ : { distributionPackageRoot: videoCliDistribution.packageRoot }),packageContributions: loaded.map((item) => item.contribution),});const workspace = await compiler.openFile(source);diff --git a/packages/video-cli/src/index.ts b/packages/video-cli/src/index.tsindex c610e477..8c942369 100644--- a/packages/video-cli/src/index.ts+++ b/packages/video-cli/src/index.ts@@ -14,6 +14,7 @@ import { runVocabularyCli } from "./vocabulary.js";export {createVideoCompiler,+ createVideoWorkspace,} from "./compiler.js";export { videoCliDistribution } from "./distribution.js";export { videoStudioCompanionPackages } from "./studio-distribution.js";diff --git a/packages/video-cli/src/package-selection.ts b/packages/video-cli/src/package-selection.tsindex accbd667..ba4f8f75 100644--- a/packages/video-cli/src/package-selection.ts+++ b/packages/video-cli/src/package-selection.ts@@ -17,11 +17,17 @@ export async function discoverVideoSourcePackages(sourcePath: string,options: {readonly workspaceRoot?: string;+ readonly packageRoot?: string;+ readonly distributionPackageRoot?: string;readonly packages?: readonly LoadedPackage[];} = {},) {return await discoverSourcePackages(sourcePath, {...(options.workspaceRoot === undefined ? {} : { workspaceRoot: options.workspaceRoot }),+ ...(options.packageRoot === undefined ? {} : { packageRoot: options.packageRoot }),+ ...(options.distributionPackageRoot === undefined+ ? {}+ : { distributionPackageRoot: options.distributionPackageRoot }),...(options.packages === undefined ? {} : { packages: options.packages }),bootstrapAuthorFrontends: [markupFrontend],});diff --git a/packages/video-cli/test/cli.test.ts b/packages/video-cli/test/cli.test.tsindex be399f3e..ffd8a086 100644--- a/packages/video-cli/test/cli.test.ts+++ b/packages/video-cli/test/cli.test.ts@@ -1,5 +1,5 @@import assert from "node:assert/strict";-import { mkdtemp, rm, writeFile } from "node:fs/promises";+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";import { tmpdir } from "node:os";import { join } from "node:path";import test from "node:test";@@ -60,3 +60,41 @@ test("provider-free example plans from installed Source packages", async () => {assert.equal(plan.steps > 0, true);assert.equal(plan.targets.length, 1);});++test("check compiles a data-only package Source export without a project copy", async () => {+ const root = await mkdtemp(join(tmpdir(), "hypit-cli-package-source-"));+ try {+ const kitRoot = join(root, "packages", "image-kits");+ await mkdir(join(kitRoot, "kits"), { recursive: true });+ await writeFile(join(kitRoot, "package.json"), JSON.stringify({+ name: "@acme/image-kits",+ version: "1.0.0",+ type: "module",+ exports: { "./ugc-v1": "./kits/ugc-v1.svs" },+ }), "utf8");+ await writeFile(join(kitRoot, "kits", "ugc-v1.svs"), `<?svml using="@hypit/text/svs@1"?>+<sheet version="1" id="ugc-v1">+ text-template.ugc-v1 { separator: paragraph; }+ text-template.ugc-v1.block.direction { kind: slot; order: 10; slot: direction; optional: false; }+</sheet>`, "utf8");+ const source = join(root, "main.svml");+ await writeFile(source, `<?svml using="@hypit/markup@1"?>+<svml>+ <import as="text" from="@hypit/text@1"/>+ <import as="kit" source="@acme/image-kits/ugc-v1"/>+ <text:Value id="direction">A useful photographed scene.</text:Value>+ <text:Render id="prompt" template={kit.ugc-v1}>+ <text:Set name="direction" text={direction}/>+ </text:Render>+</svml>`, "utf8");+ let output = "";+ await runCli(["check", source, "--workspace", root], {+ write: (text) => { output += text; },+ });+ const checked = JSON.parse(output) as { readonly sourceKind: string; readonly units: number };+ assert.equal(checked.sourceKind, "author");+ assert.equal(checked.units, 2);+ } finally {+ await rm(root, { recursive: true, force: true });+ }+});diff --git a/packages/visual-ir/README.md b/packages/visual-ir/README.mdindex 8cb13cd3..285e0ae6 100644--- a/packages/visual-ir/README.md+++ b/packages/visual-ir/README.md@@ -2,3 +2,29 @@The renderer-neutral, code-free terminal visual vocabulary. HyperFrames is the current referencerender route, not the identity or only possible implementation of this IR.++## Writing a visual program++`VISUAL_IR_V1` identifies the supported visual vocabulary. A component emits ordinary Track,+Present and element data through `@hypit/composition`. The exported constants+`VISUAL_STYLE_NAMES_V1` and `VISUAL_STYLE_ENUM_VALUES_V1` describe supported CSS-shaped declarations;+`assertVisualStyleV1` checks an individual property/value pair. Element schemas are exposed by+`hypit vocabulary --visual <kind>`.++Static style values are strings or numbers. Resource-bearing image, video and text elements carry+their actual artifacts or font references as fields. Parents are local to one Present, and child+coordinates are relative to their parent.++An element may have an `animation` with ordered `keyframes`. Each keyframe has `atFrame`, optional+`easing`, and `style`. `atFrame` is measured from the containing Present's start. Supported animated+properties are `opacity`, `transform`, `filter` and `clip-path`; easing is `linear`, `ease-in`,+`ease-out` or `ease-in-out`. A renderer can evaluate these values at any requested frame.++Video playback uses the element's separate `sampling` map. Its local target intervals select source+frame positions and rates, with explicit loops or held frames where wanted. Typography can carry+richer text layout and unit motion through the text-flow/path-text shapes.++For prepared pixels from another rendering tool, emit a `surface` element with a typed+CompositableSurfaceRef. Its resource, geometry, color/alpha and temporal metadata let composition+place and sample it through the same Track model. Local masks name their owned content and mask+children. Preparation that transforms another material receives that material as an explicit input.diff --git a/packages/workspace-fs-node/README.md b/packages/workspace-fs-node/README.mdindex 34d4903c..466508ef 100644--- a/packages/workspace-fs-node/README.md+++ b/packages/workspace-fs-node/README.md@@ -3,6 +3,11 @@Reference Node filesystem implementation of the host-neutral `Workspace` contract.Every `open()` call creates one isolated compilation session. It canonicalizes real paths, confines-SourceUnit and Source Asset reads to the configured root, rejects symlink escapes, locks each edge-to the first bytes observed and returns defensive Resource attachments. It contains no-Frontend, package, Core, Runtime, Provider or domain knowledge.+local SourceUnit and Source Asset reads to the configured root, rejects symlink escapes, locks each+edge to the first bytes observed and returns defensive Resource attachments.++A Host may supply an external Source resolver. One explicit non-relative Source locator can then+open a SourceUnit in a separate canonical root; that Source's relative imports and assets remain+inside its own root instead of inheriting project filesystem authority. The resolver returns a+locator and a root—it does not widen either root or grant executable-package authority. This+adapter itself contains no Frontend, package-manager, Core, Runtime, Provider or domain knowledge.diff --git a/packages/workspace-fs-node/src/index.ts b/packages/workspace-fs-node/src/index.tsindex 255b91a9..d25ff151 100644--- a/packages/workspace-fs-node/src/index.ts+++ b/packages/workspace-fs-node/src/index.ts@@ -1,2 +1,6 @@export { NodeFilesystemWorkspace } from "./workspace.js";-export type { NodeFilesystemWorkspaceOptions } from "./workspace.js";+export type {+ NodeFilesystemExternalSource,+ NodeFilesystemExternalSourceResolver,+ NodeFilesystemWorkspaceOptions,+} from "./workspace.js";diff --git a/packages/workspace-fs-node/src/workspace.ts b/packages/workspace-fs-node/src/workspace.tsindex 2d9c43ce..11719cf7 100644--- a/packages/workspace-fs-node/src/workspace.ts+++ b/packages/workspace-fs-node/src/workspace.ts@@ -4,6 +4,7 @@ import { readFile, realpath, stat } from "node:fs/promises";import { basename, dirname, isAbsolute, relative, resolve } from "node:path";import type {+ Awaitable,SourceAssetRequest,SourceImportRequest,SourceUnit,@@ -21,28 +22,48 @@ function isWithin(root: string, path: string): boolean {return relation === "" || (!relation.startsWith("..") && !isAbsolute(relation));}+export type NodeFilesystemExternalSource = {+ readonly root: string;+ readonly source: string;+};++export type NodeFilesystemExternalSourceResolver = (+ importer: SourceUnit,+ request: SourceImportRequest,+) => Awaitable<NodeFilesystemExternalSource>;+class NodeFilesystemWorkspaceSession implements WorkspaceSession {readonly root: string;readonly entry: SourceUnit;readonly #assetRoots: readonly string[];+ readonly #externalSourceResolver: NodeFilesystemExternalSourceResolver | undefined;readonly #sourceCache = new Map<string, SourceUnit>();+ readonly #sourceRoots = new Map<string, string>();readonly #assetIdentity = new Map<string, {readonly resource: BlobRef["resource"];readonly size: number;}>();readonly #attachments = new Map<string, ArtifactAttachment>();- private constructor(root: string, entry: SourceUnit, assetRoots: readonly string[]) {+ private constructor(+ root: string,+ entry: SourceUnit,+ assetRoots: readonly string[],+ externalSourceResolver: NodeFilesystemExternalSourceResolver | undefined,+ ) {this.root = root;this.entry = entry;this.#assetRoots = assetRoots;+ this.#externalSourceResolver = externalSourceResolver;this.#sourceCache.set(entry.id, entry);+ this.#sourceRoots.set(entry.id, root);}static async open(rootLocator: string,entryLocator: string,assetRootLocators: readonly string[],+ externalSourceResolver: NodeFilesystemExternalSourceResolver | undefined,): Promise<NodeFilesystemWorkspaceSession> {const root = await realpath(resolve(rootLocator));const assetRoots = await Promise.all(assetRootLocators.map(async (path) => await realpath(resolve(path))));@@ -59,26 +80,38 @@ class NodeFilesystemWorkspaceSession implements WorkspaceSession {name: relative(root, canonicalEntry) || basename(canonicalEntry) || canonicalEntry,text: await readFile(canonicalEntry, "utf8"),};- return new NodeFilesystemWorkspaceSession(root, entry, [root, ...assetRoots]);+ return new NodeFilesystemWorkspaceSession(root, entry, [root, ...assetRoots], externalSourceResolver);}- async #loadSource(path: string): Promise<SourceUnit> {+ async #loadSource(path: string, sourceRootLocator: string): Promise<SourceUnit> {+ const sourceRoot = await realpath(resolve(sourceRootLocator));const canonical = await realpath(resolve(path));- if (!isWithin(this.root, canonical)) {+ if (!isWithin(sourceRoot, canonical)) {throw new WorkspaceError("SOURCE_OUTSIDE_ROOT",- `Source ${canonical} is outside workspace root ${this.root}`,+ `Source ${canonical} is outside its source root ${sourceRoot}`,canonical,);}const cached = this.#sourceCache.get(canonical);- if (cached !== undefined) return cached;+ if (cached !== undefined) {+ const previousRoot = this.#sourceRoots.get(canonical);+ if (previousRoot !== sourceRoot) {+ throw new WorkspaceError(+ "SOURCE_ROOT_CONFLICT",+ `Source ${canonical} was resolved through both ${previousRoot ?? "an unknown root"} and ${sourceRoot}`,+ canonical,+ );+ }+ return cached;+ }const unit: SourceUnit = {id: canonical,- name: relative(this.root, canonical) || basename(canonical) || canonical,+ name: relative(sourceRoot, canonical) || basename(canonical) || canonical,text: await readFile(canonical, "utf8"),};this.#sourceCache.set(canonical, unit);+ this.#sourceRoots.set(canonical, sourceRoot);return unit;}@@ -86,17 +119,22 @@ class NodeFilesystemWorkspaceSession implements WorkspaceSession {importer: SourceUnit,request: SourceImportRequest,): Promise<SourceUnit> => {- if (!request.from.startsWith("./") && !request.from.startsWith("../")) {+ const importerRoot = this.#sourceRoots.get(importer.id);+ if (importerRoot === undefined) {+ throw new WorkspaceError("UNKNOWN_SOURCE_IMPORTER", `${importer.id} is outside this Workspace`, importer.id);+ }+ if (request.from.startsWith("./") || request.from.startsWith("../")) {+ return await this.#loadSource(resolve(dirname(importer.id), request.from), importerRoot);+ }+ if (this.#externalSourceResolver === undefined) {throw new WorkspaceError("UNSUPPORTED_SOURCE_IMPORT",- `Source import ${request.from} must be relative; package imports are module imports`,+ `Source import ${request.from} has no resolver in this Workspace`,request.from,);}- if (!isWithin(this.root, importer.id)) {- throw new WorkspaceError("UNKNOWN_SOURCE_IMPORTER", `${importer.id} is outside this Workspace`, importer.id);- }- return await this.#loadSource(resolve(dirname(importer.id), request.from));+ const external = await this.#externalSourceResolver(importer, request);+ return await this.#loadSource(external.source, external.root);};readonly resolveAsset = async (@@ -110,11 +148,13 @@ class NodeFilesystemWorkspaceSession implements WorkspaceSession {request.from,);}- if (!isWithin(this.root, importer.id)) {+ const importerRoot = this.#sourceRoots.get(importer.id);+ if (importerRoot === undefined) {throw new WorkspaceError("UNKNOWN_SOURCE_IMPORTER", `${importer.id} is outside this Workspace`, importer.id);}const canonical = await realpath(resolve(dirname(importer.id), request.from));- if (!this.#assetRoots.some((root) => isWithin(root, canonical))) {+ const allowedRoots = importerRoot === this.root ? this.#assetRoots : [importerRoot];+ if (!allowedRoots.some((root) => isWithin(root, canonical))) {throw new WorkspaceError("SOURCE_ASSET_OUTSIDE_ROOT",`Source asset ${canonical} is outside the workspace and every allowed asset root`,@@ -158,20 +198,29 @@ export type NodeFilesystemWorkspaceOptions = {readonly root?: string;/** Additional read-only roots for asset bytes. They never permit Source imports. */readonly assetRoots?: readonly string[];+ /** Host-owned resolver for explicit non-relative Source locators, each with its own read boundary. */+ readonly externalSourceResolver?: NodeFilesystemExternalSourceResolver;};/** Node filesystem implementation of the host-neutral, one-compilation Workspace contract. */export class NodeFilesystemWorkspace implements Workspace {readonly #root: string | undefined;readonly #assetRoots: readonly string[];+ readonly #externalSourceResolver: NodeFilesystemExternalSourceResolver | undefined;constructor(options: NodeFilesystemWorkspaceOptions = {}) {this.#root = options.root;this.#assetRoots = options.assetRoots ?? [];+ this.#externalSourceResolver = options.externalSourceResolver;}async open(entryLocator: string): Promise<WorkspaceSession> {const entry = resolve(entryLocator);- return await NodeFilesystemWorkspaceSession.open(this.#root ?? dirname(entry), entry, this.#assetRoots);+ return await NodeFilesystemWorkspaceSession.open(+ this.#root ?? dirname(entry),+ entry,+ this.#assetRoots,+ this.#externalSourceResolver,+ );}}diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 6d8d4b81..6e69a7b0 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -21,6 +21,9 @@ importers:'@hypit/audio-track-studio':specifier: workspace:*version: link:packages/audio-track-studio+ '@hypit/author-kit':+ specifier: workspace:*+ version: link:packages/author-kit'@hypit/background-removal':specifier: workspace:*version: link:packages/background-removal@@ -87,6 +90,9 @@ importers:'@hypit/gpt-image':specifier: workspace:*version: link:packages/gpt-image+ '@hypit/gpt-image-kits':+ specifier: workspace:*+ version: link:packages/gpt-image-kits'@hypit/grok-imagine':specifier: workspace:*version: link:packages/grok-imagine@@ -278,46 +284,13 @@ importers:version: 1.6.4(@algolia/[email protected])(@types/[email protected])([email protected])([email protected])([email protected])examples/minimal-author-package/packages/example-component:- dependencies:- '@hypit/artifact':- specifier: workspace:*- version: link:../../../../packages/artifact- '@hypit/component-kit':- specifier: workspace:*- version: link:../../../../packages/component-kit- '@hypit/composition':- specifier: workspace:*- version: link:../../../../packages/composition- '@hypit/elaborator':- specifier: workspace:*- version: link:../../../../packages/elaborator- '@hypit/markup':- specifier: workspace:*- version: link:../../../../packages/markup- '@hypit/media':- specifier: workspace:*- version: link:../../../../packages/media- '@hypit/program-space':- specifier: workspace:*- version: link:../../../../packages/program-space- '@hypit/protocol':- specifier: workspace:*- version: link:../../../../packages/protocol- '@hypit/semantic-track':- specifier: workspace:*- version: link:../../../../packages/semantic-track- '@hypit/svs':- specifier: workspace:*- version: link:../../../../packages/svs- '@hypit/temporal':- specifier: workspace:*- version: link:../../../../packages/temporal- '@hypit/temporal-markup':- specifier: workspace:*- version: link:../../../../packages/temporal-markup- '@hypit/visual-ir':+ devDependencies:+ hypit:specifier: workspace:*- version: link:../../../../packages/visual-ir+ version: link:../../../..+ typescript:+ specifier: 5.9.3+ version: 5.9.3packages/artifact:dependencies:@@ -398,6 +371,21 @@ importers:specifier: workspace:*version: link:../studio-adapter+ packages/author-kit:+ dependencies:+ '@hypit/component-kit':+ specifier: workspace:*+ version: link:../component-kit+ '@hypit/elaborator':+ specifier: workspace:*+ version: link:../elaborator+ '@hypit/markup':+ specifier: workspace:*+ version: link:../markup+ '@hypit/protocol':+ specifier: workspace:*+ version: link:../protocol+packages/background-removal:dependencies:'@hypit/artifact':@@ -1454,6 +1442,15 @@ importers:specifier: workspace:*version: link:../speech+ packages/gpt-image-kits:+ devDependencies:+ '@hypit/svs':+ specifier: workspace:*+ version: link:../svs+ '@hypit/text':+ specifier: workspace:*+ version: link:../text+packages/grok-imagine:dependencies:'@hypit/artifact':