@hypit/hypit 0.1.4 → 0.1.5

package/packages/package-loader-node/package.json

@@ -5,11 +5,14 @@
   "private": true,
   "type": "module",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./module-scope": "./src/module-scope.ts"
   },
   "dependencies": {
     "@hypit/component-kit": "workspace:*",
     "@hypit/host": "workspace:*",
-    "@hypit/protocol": "workspace:*"
+    "@hypit/protocol": "workspace:*",
+    "cjs-module-lexer": "2.2.1",
+    "typescript": "5.9.3"
   }
 }

package/packages/package-loader-node/src/distribution-resolution.ts

@@ -5,6 +5,7 @@ import { pathToFileURL } from "node:url";
 
 import {
   distributionPackageDirectory,
+  declaredExternalPackageRoot,
   setActiveDistributionPackageRoots,
   setActiveExternalPackageRoots,
 } from "./location.js";
@@ -100,7 +101,7 @@ export function installDistributionPackageResolution(roots: readonly string[]):
         }
         for (const root of installed) {
           const entry = resolveDistributionPackageImport(root, specifier);
-          if (entry !== undefined) return { url: pathToFileURL(entry).href, shortCircuit: true };
+          if (entry !== undefined) return nextResolve(pathToFileURL(entry).href, context);
         }
         throw new Error(`Active Hypit Distribution does not provide ${specifier}`);
       }
@@ -123,7 +124,6 @@ export function installExternalPackageResolution(roots: readonly string[]): void
   }
   externalInstalled = next;
   setActiveExternalPackageRoots(externalInstalled);
-  const parentUrls = externalInstalled.map((root) => pathToFileURL(join(root, "__hypit_external__.mjs")).href);
   registerHooks({
     resolve(specifier, context, nextResolve) {
       if (specifier.startsWith("@hypit/") || !barePackageSpecifier(specifier)) {
@@ -132,8 +132,15 @@ export function installExternalPackageResolution(roots: readonly string[]): void
       try {
         return nextResolve(specifier, context);
       } catch (original) {
-        for (const parentURL of parentUrls) {
+        if (context.parentURL === undefined || !context.parentURL.startsWith("file:")) throw original;
+        if (installed.length > 0 && !installed.some((root) =>
+          context.parentURL!.startsWith(pathToFileURL(`${root}/`).href))) throw original;
+        for (const root of externalInstalled) {
           try {
+            const name = packageAddress(specifier)?.name;
+            const selected = name === undefined ? undefined : declaredExternalPackageRoot(root, context.parentURL, name);
+            if (selected === undefined) continue;
+            const parentURL = pathToFileURL(join(selected, "__hypit_external__.mjs")).href;
             return nextResolve(specifier, { ...context, parentURL });
           } catch {
             // Try the next machine package root before preserving Node's error.

package/packages/package-loader-node/src/index.ts

@@ -15,6 +15,7 @@ export {
 } from "./distribution-resolution.js";
 export {
   locateNodePackage,
+  externalPackageInstallRoot,
   resolveNodePackageExecutable,
   resolveNodePackageResource,
   resolveNodePackageSource,

package/packages/package-loader-node/src/loader.ts

@@ -97,10 +97,12 @@ function activationPath(item: ResolvedPackage): string {
   return target;
 }
 
-async function importContribution(item: ResolvedPackage): Promise<NodePackageContribution> {
+async function importContribution(item: ResolvedPackage, options: NodePackageLoadOptions): Promise<NodePackageContribution> {
   const target = activationPath(item);
   assert((await stat(target)).isFile(), `${item.json.name} activation is not a file`);
-  const imported = await import(pathToFileURL(target).href) as { readonly default?: unknown };
+  const url = pathToFileURL(target).href;
+  const imported = await (options.importModule !== undefined && !item.json.name.startsWith("@hypit/")
+    ? options.importModule(url) : import(url)) as { readonly default?: unknown };
   assert(imported.default !== null && typeof imported.default === "object", `${item.json.name} activation has no default package export`);
   const contribution = imported.default as Partial<NodePackageContribution>;
   assert(contribution.format === "hypit.node-package@1", `${item.json.name} activation has an unsupported package format`);
@@ -185,7 +187,7 @@ export async function distributionExternalPackageRequirements(
   const root = resolve(distributionRoot);
   const queue = [...new Set(specifiers.filter((name) => name.startsWith("@hypit/")))].sort();
   const visited = new Set<string>();
-  const external = new Map<string, string>();
+  const external = new Map<string, { readonly name: string; readonly version: string; readonly specifier: string }>();
   while (queue.length > 0) {
     const name = queue.shift()!;
     if (visited.has(name)) continue;
@@ -196,16 +198,11 @@ export async function distributionExternalPackageRequirements(
         queue.push(dependency);
         continue;
       }
-      const previous = external.get(dependency);
-      if (previous !== undefined && previous !== version) {
-        throw new Error(`${dependency} is required at both ${previous} and ${version} by the selected Distribution packages`);
-      }
-      external.set(dependency, version);
+      const specifier = `${dependency}@${version}`;
+      external.set(specifier, { name: dependency, version, specifier });
     }
   }
-  return [...external.entries()]
-    .sort(([left], [right]) => left.localeCompare(right))
-    .map(([name, version]) => ({ name, version, specifier: `${name}@${version}` }));
+  return [...external.values()].sort((left, right) => left.specifier.localeCompare(right.specifier));
 }
 
 /**
@@ -256,8 +253,8 @@ export async function loadNodePackageSelection(
   for (const item of await Promise.all(roots.map(async (physical) => ({
     physical,
     contribution: await (async () => {
-      await assertExternalDependencies(physical, distributionRoots, externalRoots);
-      return await importContribution(physical);
+      if (!options.deferExternalDependencies) await assertExternalDependencies(physical, distributionRoots, externalRoots);
+      return await importContribution(physical, options);
     })(),
   })))) add(item);
 
@@ -270,8 +267,8 @@ export async function loadNodePackageSelection(
       providerPackage,
       resolutionRoots(providerPackage, [requirement.from, root], distributionRoots),
     );
-    await assertExternalDependencies(physical, distributionRoots, externalRoots);
-    const provider = { physical, contribution: await importContribution(physical) };
+    if (!options.deferExternalDependencies) await assertExternalDependencies(physical, distributionRoots, externalRoots);
+    const provider = { physical, contribution: await importContribution(physical, options) };
     add(provider);
     assert(providedModules.has(requirement.key), `${providerPackage} does not provide the required ${requirement.key}`);
   }

package/packages/package-loader-node/src/location.ts

@@ -66,6 +66,31 @@ function packageName(value: string): string {
   return value;
 }
 
+/** One ordinary npm installation per exact upstream release; no shared mutable node_modules. */
+export function externalPackageInstallRoot(root: string, name: string, version: string): string {
+  packageName(name);
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u.test(version)) {
+    throw new Error(`${name}@${version} must select an exact upstream version`);
+  }
+  return join(resolve(root), ...name.split("/"), version);
+}
+
+/** The importing package's own manifest owns its upstream version selection. */
+export function declaredExternalPackageRoot(root: string, from: string | URL, name: string): string | undefined {
+  let cursor = dirname(fromPath(from));
+  while (true) {
+    const manifest = join(cursor, "package.json");
+    if (existsSync(manifest)) {
+      const value = JSON.parse(readFileSync(manifest, "utf8")) as { dependencies?: Record<string, string> };
+      const version = value.dependencies?.[name];
+      return version === undefined ? undefined : externalPackageInstallRoot(root, name, version);
+    }
+    const parent = dirname(cursor);
+    if (parent === cursor) return undefined;
+    cursor = parent;
+  }
+}
+
 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`);
@@ -187,7 +212,8 @@ export function locateNodePackage(nameValue: string, options: LocateNodePackageO
     ?? distributionRoots.some((root) => within(root, dirname(from)));
   if (allowExternal) {
     for (const root of externalRoots) {
-      const found = nodeModulesPackage(root, name);
+      const installation = declaredExternalPackageRoot(root, from, name);
+      const found = installation === undefined ? undefined : nodeModulesPackage(installation, name);
       if (found !== undefined) return found;
     }
   }

package/packages/package-loader-node/src/module-scope.ts

@@ -0,0 +1,183 @@
+import Module, { createRequire, findPackageJSON, isBuiltin, registerHooks } from "node:module";
+import { readFileSync } from "node:fs";
+import { dirname, extname, isAbsolute, join, sep } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { compileFunction } from "node:vm";
+import { initSync, parse as parseCommonJs } from "cjs-module-lexer";
+import { transpileModule, ModuleKind, ScriptTarget, JsxEmit } from "typescript";
+
+/** A module identity namespace, not a filesystem directory. No files are written here. */
+const prefix = pathToFileURL(join(tmpdir(), ".hypit-module-scopes", String(process.pid)) + sep).href;
+const bridge = "hypit-internal:module-scope";
+const requestPrefix = "hypit-module-request:";
+const scopes = new Map<string, NodeModuleScope>();
+let serial = 0;
+let installed = false;
+
+function address(value: string | undefined): { scope: string; url: string } | undefined {
+  if (value === undefined) return undefined;
+  const url = isAbsolute(value) ? pathToFileURL(value).href : value;
+  if (!url.startsWith(prefix)) return undefined;
+  const [scope, encoded] = url.slice(prefix.length).split("/");
+  if (!scope || !encoded) return undefined;
+  return { scope, url: Buffer.from(encoded.slice(0, -4), "base64url").toString("utf8") };
+}
+
+function moduleUrl(scope: string, url: string): string {
+  return `${prefix}${scope}/${Buffer.from(url).toString("base64url")}.mjs`;
+}
+
+function commonJsSource(filename: string): string {
+  const source = readFileSync(filename, "utf8").replace(/^#!/u, "//");
+  return /\.[cm]?tsx?$|\.jsx$/u.test(filename) ? transpileModule(source, {
+    fileName: filename,
+    compilerOptions: { module: ModuleKind.CommonJS, target: ScriptTarget.ES2023, jsx: JsxEmit.ReactJSX, esModuleInterop: true },
+  }).outputText : source;
+}
+
+function esmSource(filename: string): string {
+  const source = readFileSync(filename, "utf8").replace(/^#!/u, "//");
+  return /\.[cm]?tsx?$|\.jsx$/u.test(filename)
+    ? transpileModule(source, {
+      fileName: filename,
+      compilerOptions: { module: ModuleKind.ESNext, target: ScriptTarget.ES2023, jsx: JsxEmit.ReactJSX, esModuleInterop: true },
+    }).outputText : source;
+}
+
+function exportNames(filename: string, visited = new Set<string>()): readonly string[] {
+  // Node's CJS named-export discovery does not infer names from ESM or JSON reexports.
+  if (visited.has(filename) || isEsModule(filename) || extname(filename) === ".json") return [];
+  visited.add(filename);
+  const parsed = parseCommonJs(commonJsSource(filename));
+  const require = createRequire(filename);
+  return [...new Set([...parsed.exports, ...parsed.reexports.flatMap((specifier) => {
+    const target = require.resolve(specifier);
+    return isBuiltin(target) || target.endsWith(".node") ? Object.keys(require(specifier) as object) : exportNames(target, visited);
+  })])].filter((name) => name !== "default" && name !== "module.exports");
+}
+
+function isEsModule(filename: string): boolean {
+  const extension = extname(filename);
+  if (extension === ".mjs" || extension === ".mts") return true;
+  if (extension === ".cjs" || extension === ".cts") return false;
+  const manifest = findPackageJSON(pathToFileURL(filename));
+  return manifest !== undefined && (JSON.parse(readFileSync(manifest, "utf8")) as { type?: string }).type === "module";
+}
+
+function scopeFor(id: string): NodeModuleScope {
+  const scope = scopes.get(id);
+  if (scope === undefined) throw new Error(`Module scope ${id} has ended`);
+  return scope;
+}
+
+/** Internal bridge used by Node's ESM/CommonJS interop. */
+export function scopedCommonJs(id: string, filename: string): unknown { return scopeFor(id).commonJs(filename); }
+
+function install(): void {
+  if (installed) return;
+  initSync();
+  installed = true;
+  registerHooks({
+    resolve(specifier, context, nextResolve) {
+      if (specifier === bridge) return { url: import.meta.url, shortCircuit: true };
+      if (specifier.startsWith(requestPrefix)) {
+        const [scope, request, parentURL] = JSON.parse(Buffer.from(specifier.slice(requestPrefix.length), "base64url").toString("utf8")) as [string, string, string];
+        scopeFor(scope);
+        const found = nextResolve(request, { ...context, parentURL });
+        return found.url.startsWith("file:") && !request.startsWith("@hypit/") ? { ...found, url: moduleUrl(scope, found.url) } : found;
+      }
+      const direct = address(specifier);
+      const parent = address(context.parentURL);
+      const scope = direct?.scope ?? parent?.scope;
+      const target = direct === undefined ? specifier
+        : new Set(context.conditions).has("require") ? fileURLToPath(direct.url) : direct.url;
+      const found = nextResolve(target, parent ? { ...context, parentURL: parent.url } : context);
+      // The installed Distribution is process code. Its package APIs remain shared; each
+      // invocation still creates the Build's own registries, adapters and configuration.
+      if (scope === undefined || !found.url.startsWith("file:") || specifier.startsWith("@hypit/")) return found;
+      scopeFor(scope);
+      return { ...found, url: moduleUrl(scope, found.url) };
+    },
+    load(url, context, nextLoad) {
+      const item = address(url);
+      if (item === undefined) return nextLoad(url, context);
+      scopeFor(item.scope);
+      const filename = fileURLToPath(item.url);
+      // The scope owns loading its JS/TS implementation closure. It must not rely
+      // on an outer TS hook recognizing the namespace's synthetic .mjs address.
+      if (!/\.[cm]?[jt]sx?$/u.test(filename)) return nextLoad(item.url, { ...context, format: undefined });
+      if (!isEsModule(filename)) {
+        const names = exportNames(filename);
+        return { format: "module", shortCircuit: true, source: [
+          `import {scopedCommonJs} from ${JSON.stringify(bridge)};`,
+          `const value=scopedCommonJs(${JSON.stringify(item.scope)},${JSON.stringify(filename)});`,
+          "export default value; export {value as 'module.exports'};",
+          ...names.map((name, i) => `const e${i}=value[${JSON.stringify(name)}];export {e${i} as ${JSON.stringify(name)}};`),
+        ].join("\n") };
+      }
+      const source = esmSource(filename);
+      // Author-visible filesystem addresses stay real, including import.meta.resolve().
+      // Keep metadata restoration local: requiring a synchronous project ESM module
+      // must not add an edge back into the asynchronously bootstrapped loader.
+      const prelude = `import.meta.url=${JSON.stringify(item.url)};import.meta.filename=${JSON.stringify(filename)};` +
+        `import.meta.dirname=${JSON.stringify(dirname(filename))};` +
+        `{const resolve=import.meta.resolve;import.meta.resolve=(id)=>{const url=resolve(id);` +
+        `if(!url.startsWith(${JSON.stringify(prefix)}))return url;` +
+        `return globalThis.Buffer.from(url.slice(${prefix.length}).split('/')[1].slice(0,-4),'base64url').toString('utf8');};}\n`;
+      return { format: "module", shortCircuit: true, source: prelude + source };
+    },
+  });
+}
+
+/** Independent loaded bindings in a shared trusted Node process; not a security sandbox. */
+export class NodeModuleScope {
+  readonly #id = String(++serial);
+  readonly #commonJs: Record<string, NodeJS.Module> = Object.create(null) as Record<string, NodeJS.Module>;
+  constructor() { install(); scopes.set(this.#id, this); }
+
+  async import(url: string): Promise<unknown> { return await import(moduleUrl(this.#id, url)); }
+
+  commonJs(filename: string, parent?: NodeJS.Module): unknown {
+    const cached = this.#commonJs[filename];
+    if (cached !== undefined) return cached.exports;
+    const nativeRequire = createRequire(filename);
+    const mod = new Module(filename, parent);
+    mod.filename = filename;
+    mod.path = dirname(filename);
+    mod.paths = nativeRequire.resolve.paths("module") ?? [];
+    const require = Object.assign((specifier: string): unknown => {
+      if (isBuiltin(specifier)) return nativeRequire(specifier);
+      const resolved = nativeRequire.resolve(specifier);
+      if (specifier.startsWith("@hypit/") || resolved.endsWith(".node")) return nativeRequire(specifier);
+      if (resolved.endsWith(".json")) {
+        if (this.#commonJs[resolved] === undefined) {
+          const json = new Module(resolved, mod);
+          json.exports = JSON.parse(readFileSync(resolved, "utf8")); json.loaded = true;
+          this.#commonJs[resolved] = json;
+        }
+        return this.#commonJs[resolved]!.exports;
+      }
+      if (isEsModule(resolved)) return nativeRequire(fileURLToPath(moduleUrl(this.#id, pathToFileURL(resolved).href)));
+      return this.commonJs(resolved, mod);
+    }, { resolve: nativeRequire.resolve, cache: this.#commonJs, extensions: nativeRequire.extensions, main: undefined }) as NodeRequire;
+    mod.require = require;
+    this.#commonJs[filename] = mod;
+    try {
+      compileFunction(commonJsSource(filename), ["exports", "require", "module", "__filename", "__dirname"], {
+        filename,
+        importModuleDynamically: async (specifier) => await import(requestPrefix + Buffer.from(JSON.stringify([
+          this.#id, specifier, pathToFileURL(filename).href,
+        ])).toString("base64url")),
+      })
+        .call(mod.exports, mod.exports, require, mod, filename, dirname(filename));
+      mod.loaded = true;
+      return mod.exports;
+    } catch (error) { delete this.#commonJs[filename]; throw error; }
+  }
+
+  close(): void {
+    scopes.delete(this.#id);
+    for (const key of Object.keys(this.#commonJs)) delete this.#commonJs[key];
+  }
+}

package/packages/package-loader-node/src/types.ts

@@ -47,6 +47,8 @@ export type NodePackageSelectionRequest = {
 };
 
 export type NodePackageLoadOptions = {
+  /** Host-owned module scope. Omitting this uses Node's ordinary process imports. */
+  readonly importModule?: (url: string) => Promise<unknown>;
   /**
    * Additional read-only Distribution roots. They are fallbacks for project-scoped packages;
    * the reserved @hypit namespace resolves only from these roots when they are present.
@@ -57,4 +59,6 @@ export type NodePackageLoadOptions = {
    * dependencies. Defaults to the roots installed by the Hypit launcher.
    */
   readonly externalRoots?: readonly string[];
+  /** Runtime declarations can be read before their optional execution tools are prepared. */
+  readonly deferExternalDependencies?: boolean;
 };

package/packages/performance/README.md

@@ -0,0 +1,83 @@
+# Performance
+
+Performance presents footage already placed on a Timeline. Media Items receive independent assets;
+Performance Uses select how the existing footage appears. [Sound](../sound/README.md) presents existing audio. Include the wanted visual and audio outputs
+separately in Film.
+
+```svml
+<import as="performance" from="@hypit/performance@1"/>
+<performance:Style id="full" frame={layout.full} appearance={recipes.media.presenter}/>
+<performance:Style id="side" frame={layout.side} appearance={recipes.media.presenter}/>
+<performance:Track id="presenter" timeline={program.timeline} canvas={canvas}>
+  <performance:Use style={full}/>
+  <performance:Use during={story.selection.explanation} style={side}/>
+</performance:Track>
+```
+
+Select `presenter.visual` in Film. A Style's appearance uses Media fitting, clipping, radius, padding,
+border, shadows and sample appearance. `stack-order` places its Presents among Film contributions.
+A Use with no time selector covers the complete Timeline. Later Uses replace earlier rules locally;
+they do not add another copy of the picture. No matching Use means no picture. An empty winning
+Style stays empty. Separate Performance Tracks can independently show the same material.
+
+## Time, sources and visibility
+
+Use accepts shared `during`, `at` + `for`, `until` + `for`, or `start` + `end`. A Window says when a
+presentation applies. Timeline determines source positions: a Take placed at second 5 shows source
+second 2 at program second 7. Styles receive the original Use Window even when partially covered.
+Visibility does not restart playback or animation. The ordinary Style presents available videos in
+Timeline declaration order, later above earlier; no Takes, audio-only Takes and source gaps supply
+no picture. The Timeline can extend past all material without filling that time with a clip.
+
+Two independently bound endpoints can describe a physical overlap that is backwards in Script order:
+
+```svml
+<performance:Use style={mix}
+  start-source={story.segment.next} start="segment.start"
+  end-source={story.segment.previous} end="segment.end"/>
+```
+
+The concrete Style determines which sources are outgoing/incoming. Window endpoints do not select
+those roles implicitly. There is no automatic crossfade when source spans overlap.
+
+## Write a project Style
+
+`performanceStyle(fragment, bindings)` creates an authored Style. The fragment takes `timeline`,
+`canvas`, and `window`, plus any family-defined typed inputs, and exports `visual: VisualTrack`.
+`bindings` binds those extra inputs to resolved author references. A Style Surface returns this as
+an inline Record of `performanceTypes.style`. At each Use, the Track expands the fragment and turns
+every binding into a normal graph edge, including references to generated outputs. No family
+registry or effect-name dispatch is involved. The Style is an author-time definition, not a
+runtime-produced choice of executable code.
+
+```ts
+const style = performanceStyle(fragment, {
+  from: resolveFrame("from"),
+  to: resolveFrame("to"),
+});
+// Each value is a SurfaceResolvedReference; all fragment inputs except the three
+// occurrence inputs above must be bound. Your Surface owns its parameter names.
+```
+
+A family may bind Segment references, Moments, prepared assets, Frames, Recipes or computed outputs.
+Its Producers use the Timeline and shared projections to obtain exact source spans and event times.
+`projectTimelineMedia` returns zero, one or several sources with their identities and native source
+positions. Known sources without visual material differ from invalid references. Rendering can use
+ordinary structural elements, Media helpers or a browser program with HTML, CSS and frame code.
+`ordinaryPerformance` provides reusable fixed framing; a whole coordinated diagram/presenter scene
+can instead be an independent component.
+
+The [project Style example](../../examples/semantic-composition/packages/performance-styles/README.md)
+implements movement and two-source blending through these public interfaces. It demonstrates an
+extension path, not a required library of built-in transitions.
+
+## Implementation boundary
+
+`resolvePerformance` resolves last-declared Window coverage. It retains each Present's original
+`span` and intersects its optional `visibility` subranges with the winning intervals. The renderer
+uses `span` for animation and sampling and `visibility` only for display. Empty Uses still participate
+in coverage. Nothing in this package changes audio, Script, Timeline placement or generation.
+
+`Track.visual` is the resolved picture. `Track.program` retains the ordered Use windows and their
+unresolved VisualTracks, including covered and empty applications. The
+[Studio Companion](../performance-studio/README.md) uses this program to expose individual Uses.

package/packages/performance/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@hypit/performance",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "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/narrative": "workspace:*",
+    "@hypit/program-space": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/timeline": "workspace:*",
+    "@hypit/spatial": "workspace:*",
+    "@hypit/svs": "workspace:*",
+    "@hypit/markup": "workspace:*",
+    "@hypit/temporal": "workspace:*",
+    "@hypit/temporal-markup": "workspace:*",
+    "@hypit/media-track": "workspace:*"
+  }
+}

package/packages/performance/src/activation.ts

@@ -0,0 +1,11 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+import { performanceManifest, performanceModuleRef, performanceMarkupSurfaces } from "./manifest.js";
+import { performanceComponent } from "./component.js";
+import { decodePerformanceStyleSurface, decodePerformanceTrackSurface } from "./surface.js";
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{ manifest: performanceManifest }], components: [performanceComponent],
+  hostFacets: performanceMarkupSurfaces.map(declaration => createMarkupSurfaceHostFacet({ module: performanceModuleRef, declaration,
+    handler: declaration.name === "style" ? decodePerformanceStyleSurface : decodePerformanceTrackSurface })),
+};
+export default hypitPackage;

package/packages/performance/src/component.ts

@@ -0,0 +1,46 @@
+import { canonicalize } from "@hypit/protocol";
+import type { StoredValue } from "@hypit/protocol";
+import type { ComponentPackage } from "@hypit/component-kit";
+import type { Timeline } from "@hypit/timeline";
+import { sealVisualTrack } from "@hypit/composition";
+import type { VisualTrack } from "@hypit/composition";
+import type { CanvasSpace, SpatialFrame, ContentFit } from "@hypit/spatial";
+import type { TemporalWindow } from "@hypit/temporal";
+import { createMediaLayerSet, createMediaSoundSet, createMediaTrackSet, finalizeMediaTrack, projectMediaVisualTrack } from "@hypit/media-track";
+import type { MediaItemSpec, MediaSampleLayerSpec } from "@hypit/media-track";
+import { appendMediaPerformance } from "./media.js";
+import { appendPerformanceUse, resolvePerformance } from "./program.js";
+import type { PerformanceSet } from "./program.js";
+import { performanceProducers } from "./manifest.js";
+
+function inline<T>(value: StoredValue | undefined): T {
+  if (value?.kind !== "inline") throw new Error("Performance input must be inline.");
+  return value.value as unknown as T;
+}
+const output = (value: unknown) => ({ kind: "inline" as const, value: canonicalize(value) });
+export function ordinaryPerformance(input: {
+  timeline: Timeline; canvas: CanvasSpace; window: TemporalWindow; frame: SpatialFrame;
+  fit: ContentFit; sample: MediaSampleLayerSpec; spec: MediaItemSpec;
+}): VisualTrack {
+  const id = input.window.subjectId;
+  const header = { id };
+  const set = appendMediaPerformance({ ...input, header, set: createMediaTrackSet(), layers: createMediaLayerSet(),
+    sounds: createMediaSoundSet(), spec: { ...input.spec, id } }, input.fit, input.sample);
+  if (set.items.length === 0) return sealVisualTrack({ id, programSpaceId: input.timeline.id, visualIr: "hypit.visual-ir@1", presents: [] });
+  return projectMediaVisualTrack(input.timeline, finalizeMediaTrack(set, header, input.timeline));
+}
+export const performanceComponent: ComponentPackage = {
+  producers: [
+    { producer: performanceProducers.create, handler: () => ({ outputs: { set: output({ uses: [] }) }, needs: {} }) },
+    { producer: performanceProducers.append, handler: ({ inputs }) => ({ outputs: { set: output(appendPerformanceUse(
+      inline<PerformanceSet>(inputs.set?.value), inline<TemporalWindow>(inputs.window?.value), inline<VisualTrack>(inputs.visual?.value),
+    )) }, needs: {} }) },
+    { producer: performanceProducers.resolve, handler: ({ inputs }) => ({ outputs: { visual: output(resolvePerformance(
+      inline<Timeline>(inputs.timeline?.value), inline<{ id: string }>(inputs.header?.value).id, inline<PerformanceSet>(inputs.set?.value),
+    )) }, needs: {} }) },
+    { producer: performanceProducers.ordinary, handler: ({ inputs }) => ({ outputs: { visual: output(ordinaryPerformance({
+      timeline: inline(inputs.timeline?.value), canvas: inline(inputs.canvas?.value), window: inline(inputs.window?.value),
+      frame: inline(inputs.frame?.value), fit: inline(inputs.fit?.value), sample: inline(inputs.sample?.value), spec: inline(inputs.spec?.value),
+    })) }, needs: {} }) },
+  ],
+};

package/packages/performance/src/index.ts

@@ -0,0 +1,6 @@
+export * from "./style.js";
+export * from "./program.js";
+export * from "./component.js";
+export * from "./surface.js";
+export * from "./manifest.js";
+export { appendMediaPerformance } from "./media.js";

package/packages/performance/src/manifest.ts

@@ -0,0 +1,53 @@
+import { compositionDependency, compositionTypes } from "@hypit/composition";
+import { timelineDependency, timelineTypes } from "@hypit/timeline";
+import { spatialDependency, spatialTypes } from "@hypit/spatial";
+import { temporalDependency, temporalTypes } from "@hypit/temporal";
+import { mediaTrackDependency, mediaTrackTypes } from "@hypit/media-track";
+import { svsRecipeType } from "@hypit/svs";
+import { temporalWindowAttributeVocabulary } from "@hypit/temporal-markup";
+import type { ModuleManifest, ProducerRef, TypeRef } from "@hypit/protocol";
+
+export const performanceModuleRef = { name: "@hypit/performance", version: "1" } as const;
+export const performanceTypes = Object.fromEntries(["Style", "Set", "Header"].map(name => [name.toLowerCase(), { module: performanceModuleRef, name: `Performance${name}` }])) as Record<"style" | "set" | "header", TypeRef>;
+export const performanceProducers = Object.fromEntries(["create", "append", "resolve", "ordinary"].map(name => [name, { module: performanceModuleRef, name }])) as Record<"create" | "append" | "resolve" | "ordinary", ProducerRef>;
+export const ordinaryInputs = [
+  { name: "timeline", type: timelineTypes.track }, { name: "canvas", type: spatialTypes.canvas },
+  { name: "window", type: temporalTypes.window }, { name: "frame", type: spatialTypes.frame },
+  { name: "fit", type: spatialTypes.fit }, { name: "sample", type: mediaTrackTypes.sampleLayerSpec },
+  { name: "spec", type: mediaTrackTypes.itemSpec },
+];
+export const performanceManifest: ModuleManifest = {
+  format: "hypit.module@1", ...performanceModuleRef,
+  dependencies: [compositionDependency, timelineDependency, spatialDependency, temporalDependency, mediaTrackDependency],
+  types: Object.values(performanceTypes).map(type => ({ name: type.name })), capabilities: [],
+  producers: [
+    { name: "create", inputs: [], outputs: [{ name: "set", type: performanceTypes.set }], needs: [] },
+    { name: "append", inputs: [{ name: "set", type: performanceTypes.set }, { name: "window", type: temporalTypes.window }, { name: "visual", type: compositionTypes.visualTrack }], outputs: [{ name: "set", type: performanceTypes.set }], needs: [] },
+    { name: "resolve", inputs: [{ name: "set", type: performanceTypes.set }, { name: "timeline", type: timelineTypes.track }, { name: "header", type: performanceTypes.header }], outputs: [{ name: "visual", type: compositionTypes.visualTrack }], needs: [] },
+    { name: "ordinary", inputs: ordinaryInputs, outputs: [{ name: "visual", type: compositionTypes.visualTrack }], needs: [] },
+  ],
+};
+export const performanceMarkupSurfaces = [
+  { name: "style", tag: "Style", mode: "structured", outputs: [performanceTypes.style, spatialTypes.fit, mediaTrackTypes.sampleLayerSpec, mediaTrackTypes.itemSpec], vocabulary: {
+    summary: "Defines ordinary A-roll framing using Media appearance properties.",
+    example: `<performance:Style id="full" frame={layout.full} appearance={recipes.media.presenter}/>`,
+    attributes: [
+      { name: "id", kind: "identifier", required: true, summary: "Style name." },
+      { name: "frame", kind: "reference", required: true, accepts: [spatialTypes.frame], summary: "Destination Frame." },
+      { name: "appearance", kind: "reference", required: true, accepts: [svsRecipeType], summary: "Media appearance Recipe: fitting, clipping, border and color." },
+    ],
+  } },
+  { name: "track", tag: "Track", mode: "structured", outputs: [compositionTypes.visualTrack, performanceTypes.set, performanceTypes.header, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window], vocabulary: {
+    summary: "Presents Timeline footage through ordered Use rules, retaining source playback time.",
+    example: `<performance:Track id="presenter" timeline={program.timeline} canvas={canvas}><performance:Use style={full}/></performance:Track>`,
+    attributes: [
+      { name: "id", kind: "identifier", required: true, summary: "Presentation name." },
+      { name: "timeline", kind: "reference", required: true, accepts: [timelineTypes.track], summary: "Placed material and film time." },
+      { name: "canvas", kind: "reference", required: true, accepts: [spatialTypes.canvas], summary: "Composition Canvas." },
+    ], children: [{ tag: "Use", cardinality: "many", summary: "Last matching Use wins. No time selector means the whole Timeline.", attributes: [
+      { name: "id", kind: "identifier", required: false, summary: "Optional occurrence identity." },
+      { name: "style", kind: "reference", required: true, accepts: [performanceTypes.style], summary: "Ordinary or project-authored presentation Style." },
+      ...temporalWindowAttributeVocabulary,
+    ] }],
+  } },
+] as const;