@hypit/hypit 0.1.3 → 0.1.5

package/packages/performance/src/style.ts

@@ -0,0 +1,35 @@
+import { sealGraphFragment } from "@hypit/elaborator";
+import type { GraphFragment } from "@hypit/elaborator";
+import { compositionTypes } from "@hypit/composition";
+import { timelineTypes } from "@hypit/timeline";
+import { spatialTypes } from "@hypit/spatial";
+import { temporalTypes } from "@hypit/temporal";
+import { sameType } from "@hypit/protocol";
+import type { SurfaceResolvedReference } from "@hypit/markup";
+
+/** Author-time closure: bound references become ordinary graph edges at each Use. */
+export type PerformanceStyle = {
+  readonly fragment: GraphFragment;
+  readonly bindings: Readonly<Record<string, { readonly type: SurfaceResolvedReference["type"]; readonly ref: SurfaceResolvedReference["ref"] }>>;
+};
+export function performanceStyle(fragment: GraphFragment, bindings: PerformanceStyle["bindings"] = {}): PerformanceStyle {
+  fragment = sealGraphFragment(fragment);
+  const common = { timeline: timelineTypes.track, canvas: spatialTypes.canvas, window: temporalTypes.window };
+  for (const [name, type] of Object.entries(common)) {
+    const port = fragment.inputs.find(port => port.name === name);
+    if (port === undefined || !sameType(port.type, type)) throw new Error(`Performance Style requires ${name} input.`);
+    if (bindings[name] !== undefined) throw new Error(`Performance supplies ${name} at each Use.`);
+  }
+  for (const port of fragment.inputs) {
+    if (port.name in common) continue;
+    const binding = bindings[port.name];
+    if (binding === undefined || !sameType(port.type, binding.type)) throw new Error(`Performance Style binding ${port.name} has the wrong Type.`);
+  }
+  for (const name of Object.keys(bindings)) {
+    if (!fragment.inputs.some(port => port.name === name)) throw new Error(`Performance Style has unknown binding ${name}.`);
+  }
+  if (fragment.exports.length !== 1 || fragment.exports[0]?.name !== "visual" || !sameType(fragment.exports[0].type, compositionTypes.visualTrack)) {
+    throw new Error("Performance Style must export visual: VisualTrack.");
+  }
+  return { fragment, bindings: Object.fromEntries(Object.entries(bindings).map(([name, value]) => [name, { ref: value.ref, type: value.type }])) };
+}

package/packages/performance/src/surface.ts

@@ -0,0 +1,99 @@
+import { assertAttributes, assertEmptyElement, textAttribute, optionalTextAttribute } from "@hypit/markup";
+import type { StructuredSurfaceHandler, SurfaceResolvedReference, SurfaceRecordDraft, SurfaceComponentDraft, StructuredElement } from "@hypit/markup";
+import { canonicalize, sameType } from "@hypit/protocol";
+import type { TypeRef } from "@hypit/protocol";
+import { sealGraphFragment } from "@hypit/elaborator";
+import type { FragmentOperation } from "@hypit/elaborator";
+import { createTemporalWindowProjection, resolveTemporalContext, temporalWindowAttributeNames } from "@hypit/temporal-markup";
+import { temporalTypes } from "@hypit/temporal";
+import { compositionTypes } from "@hypit/composition";
+import { timelineTypes } from "@hypit/timeline";
+import { spatialTypes } from "@hypit/spatial";
+import { svsRecipeType } from "@hypit/svs";
+import type { SvsRecipe } from "@hypit/svs";
+import { decodeMediaFit, decodeMediaSampleSpec, decodeMediaItemSpec, mediaTrackTypes } from "@hypit/media-track";
+import { performanceStyle } from "./style.js";
+import type { PerformanceStyle } from "./style.js";
+import { performanceTypes, performanceProducers, ordinaryInputs } from "./manifest.js";
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
+function reference(element: StructuredElement, name: string, type: TypeRef, resolve: (path: string) => SurfaceResolvedReference | undefined): SurfaceResolvedReference {
+  const raw = element.attributes[name];
+  if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${element.name}.${name} must be a reference.`);
+  const found = resolve(raw.path);
+  if (found === undefined || !sameType(found.type, type)) throw new Error(`${element.name}.${name} has the wrong Type.`);
+  return found;
+}
+function authored<T>(value: SurfaceResolvedReference): T {
+  if (value.record?.value.kind !== "inline") throw new Error("A presentation Style or Recipe must be an authored inline value.");
+  return value.record.value.value as unknown as T;
+}
+export const ordinaryPerformanceFragment = sealGraphFragment({
+  inputs: ordinaryInputs,
+  operations: [{ id: "ordinary", producer: performanceProducers.ordinary,
+    inputs: Object.fromEntries(ordinaryInputs.map(port => [port.name, input(port.name)])), result: { kind: "output", name: "visual" } }],
+  exports: [{ name: "visual", type: compositionTypes.visualTrack, root: operation("ordinary") }],
+});
+export const decodePerformanceStyleSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  assertAttributes(element, ["id", "frame", "appearance"]); assertEmptyElement(element);
+  const id = textAttribute(element, "id");
+  const frame = reference(element, "frame", spatialTypes.frame, resolveReference);
+  const recipe = authored<SvsRecipe>(reference(element, "appearance", svsRecipeType, resolveReference));
+  if (["playback", "trim-start", "trim-end"].some(key => recipe.properties[key] !== undefined)) throw new Error("Performance uses Timeline source positions; select its presentation interval on Use.");
+  const records: SurfaceRecordDraft[] = [];
+  const bind = (name: string, type: TypeRef, value: unknown) => {
+    const recordId = `${id}.${name}`;
+    records.push({ id: recordId, type, value: { kind: "inline", value: canonicalize(value) }, range: element.range });
+    return { ref: { kind: "record" as const, id: recordId }, type };
+  };
+  const style = performanceStyle(ordinaryPerformanceFragment, {
+    frame,
+    fit: bind("fit", spatialTypes.fit, decodeMediaFit(recipe)),
+    sample: bind("sample", mediaTrackTypes.sampleLayerSpec, decodeMediaSampleSpec(recipe, "content", "timed", undefined, true)),
+    spec: bind("spec", mediaTrackTypes.itemSpec, decodeMediaItemSpec(recipe, { id, motion: { sustain: [] } })),
+  });
+  records.push({ id, type: performanceTypes.style, value: { kind: "inline", value: canonicalize(style) }, range: element.range });
+  return { records, components: [], fragments: [] };
+};
+
+export const decodePerformanceTrackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  assertAttributes(element, ["id", "timeline", "canvas"]);
+  const id = textAttribute(element, "id"), context = resolveTemporalContext({ element, resolveReference });
+  const canvas = reference(element, "canvas", spatialTypes.canvas, resolveReference);
+  const records: SurfaceRecordDraft[] = [{ id: `${id}.header`, type: performanceTypes.header, value: { kind: "inline", value: { id } }, range: element.range }];
+  const components: SurfaceComponentDraft[] = [];
+  const fragments = [] as ReturnType<typeof sealGraphFragment>[];
+  const collectorInputs = [{ name: "timeline", type: timelineTypes.track }, { name: "header", type: performanceTypes.header }];
+  const bindings: Record<string, SurfaceResolvedReference["ref"]> = { timeline: context.timeline.ref, header: { kind: "record", id: `${id}.header` } };
+  const operations: FragmentOperation[] = [{ id: "empty", producer: performanceProducers.create, inputs: {}, result: { kind: "output", name: "set" } }];
+  let previous = "empty", index = 0;
+  for (const child of element.children) {
+    if (child.kind === "text") { if (child.value.trim()) throw new Error("Performance Track accepts Use children."); continue; }
+    if (child.name.split(":").at(-1) !== "Use") throw new Error("Performance Track accepts Use children.");
+    assertAttributes(child, ["id", "style", ...temporalWindowAttributeNames]); assertEmptyElement(child);
+    const useId = optionalTextAttribute(child, "id") ?? `${id}.use.${index + 1}`;
+    index += 1;
+    const hasTime = temporalWindowAttributeNames.some(name => child.attributes[name] !== undefined);
+    const temporal = createTemporalWindowProjection({ id: useId, ...context, resolveReference,
+      element: hasTime ? child : { ...child, attributes: { ...child.attributes, during: "program" } } });
+    records.push(...temporal.records); components.push(...temporal.components); fragments.push(...temporal.fragments);
+    const value = authored<PerformanceStyle>(reference(child, "style", performanceTypes.style, resolveReference));
+    const style = performanceStyle(value.fragment, value.bindings);
+    fragments.push(style.fragment);
+    const visualId = `${useId}.visual`;
+    components.push({ id: `${useId}.__style`, fragment: style.fragment.id,
+      inputs: { ...Object.fromEntries(Object.entries(style.bindings).map(([key, bound]) => [key, bound.ref])),
+        timeline: context.timeline.ref, canvas: canvas.ref, window: temporal.ref }, outputs: { visual: visualId }, range: child.range });
+    const suffix = `use-${operations.length}`;
+    collectorInputs.push({ name: `${suffix}-window`, type: temporalTypes.window }, { name: `${suffix}-visual`, type: compositionTypes.visualTrack });
+    bindings[`${suffix}-window`] = temporal.ref; bindings[`${suffix}-visual`] = { kind: "component-output", component: `${useId}.__style`, output: "visual" };
+    operations.push({ id: suffix, producer: performanceProducers.append, inputs: { set: operation(previous), window: input(`${suffix}-window`), visual: input(`${suffix}-visual`) }, result: { kind: "output", name: "set" } });
+    previous = suffix;
+  }
+  operations.push({ id: "resolve", producer: performanceProducers.resolve, inputs: { set: operation(previous), timeline: input("timeline"), header: input("header") }, result: { kind: "output", name: "visual" } });
+  const collector = sealGraphFragment({ inputs: collectorInputs, operations, exports: [{ name: "visual", type: compositionTypes.visualTrack, root: operation("resolve") }, { name: "program", type: performanceTypes.set, root: operation(previous) }] });
+  fragments.push(collector);
+  components.push({ id, fragment: collector.id, inputs: bindings, outputs: { visual: `${id}.visual`, program: `${id}.program` }, range: element.range });
+  return { records, components, fragments, exports: [`${id}.visual`, `${id}.program`] };
+};

package/packages/performance-studio/README.md

@@ -0,0 +1,25 @@
+# Performance Studio Companion
+
+The Companion contributes one Performance Track with a content area and an internal Uses band:
+
+- **Performance** shows the Timeline's placed picture Takes, with source thumbnails. These are available contents, independent of which Use presents or hides them. Audio-only Takes have no picture item.
+- **Uses** shows each authored Style application as a named interval in the bottom label band. Declaration order sets overlap order; selecting an item raises it for editing without changing the authored priority. Covered and empty applications remain available.
+
+`performance:Track.program` exports the ordered windows and unresolved visuals. The Companion reads that value instead of reconstructing author rules from the final visibility masks. The Timeline supplies the content lane. Typed temporal values identify each Use's exact author element even when its id was omitted.
+
+One Performance label spans the content and Uses band; selection targets a picture Take or a Use.
+A Take shows its Segment and placed frame range. A Use shows its resolved range and Style reference.
+These are small read-only facts within When and How, alongside the editable fields in the same domains.
+The displayed range uses an exclusive end frame.
+
+Selecting a Use exposes its ordinary Style's referenced Frame and Media appearance Recipe. Frame edits write to SVML; appearance edits write to SVS. A shared Style or Recipe remains shared. Temporal gestures follow the same Selection/Moment/clock projection and source-writeback path as other components.
+
+Project Styles receive the same Use interval and title. Their parameters are contributed through `createStudioCompanionHostFacet({ parameters })`, matching
+the Style's own Module and Surface. The Track opts its `style` reference into this declaration.
+Ordinary Style fields live in their own parameter Companion. See the project
+[performance Styles](../../examples/semantic-composition/packages/performance-styles/README.md) for an example.
+
+The internal `bands`, field bindings and content chrome are public Studio Companion declarations. Uses are entities in the same Track; independent child Tracks still use `attachments`. Studio does not recognize Performance names or scene-specific layouts. Caption and Sound can describe their own content and applications through the same interface.
+
+Use picture selection follows exact rendered Present ids supplied by Performance. Take content uses
+its Segment identity rather than array position, so reordering Takes preserves selection identity.

package/packages/performance-studio/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@hypit/performance-studio",
+  "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/performance": "workspace:*",
+    "@hypit/timeline": "workspace:*",
+    "@hypit/temporal": "workspace:*",
+    "@hypit/composition": "workspace:*",
+    "@hypit/studio-adapter": "workspace:*",
+    "@hypit/media-track-studio": "workspace:*"
+  }
+}

package/packages/performance-studio/src/activation.ts

@@ -0,0 +1,6 @@
+import { createStudioCompanionHostFacet } from "@hypit/studio-adapter";
+import { performanceStudioTrackCompanions, performanceStudioParameterCompanions } from "./index.js";
+export default {
+  format: "hypit.node-package@1" as const,
+  hostFacets: [createStudioCompanionHostFacet({ tracks: performanceStudioTrackCompanions, parameters: performanceStudioParameterCompanions })],
+};

package/packages/performance-studio/src/index.ts

@@ -0,0 +1,84 @@
+import { performanceModuleRef, performancePresentId } from "@hypit/performance";
+import type { PerformanceSet } from "@hypit/performance";
+import { projectTimelineMedia, timelineTypes } from "@hypit/timeline";
+import type { Timeline } from "@hypit/timeline";
+import { temporalTypes } from "@hypit/temporal";
+import { compositionTypes } from "@hypit/composition";
+import { mediaAppearanceStudioFields } from "@hypit/media-track-studio";
+import { artifactPreview, authoredChildFor, previewLayer, requiredReferencedValue, requiredSurfaceValue, temporalLineageFor, temporalSemanticSource } from "@hypit/studio-adapter";
+import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioEntityDraft, StudioSourceBindingDeclaration } from "@hypit/studio-adapter";
+
+const frameFields = ["left", "top", "right", "bottom", "x", "y", "width", "height"];
+const frameBindings: readonly StudioSourceBindingDeclaration[] = frameFields.map(name => ({ name, writable: true }));
+// Ordinary Performance uses Timeline playback. The rest is the same Media appearance vocabulary.
+const playbackFields = new Set(["playback", "trim-start", "trim-end"]);
+const appearanceBindings = mediaAppearanceStudioFields.bindings.filter(field => !playbackFields.has(field.name));
+const appearanceInspector = mediaAppearanceStudioFields.inspector.filter(field =>
+  !playbackFields.has(field.binding.slice("appearance.".length)));
+
+export function projectPerformance(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
+  const timeline = requiredReferencedValue(context, "timeline", timelineTypes.track) as Timeline;
+  const program = requiredSurfaceValue(context, "program") as PerformanceSet;
+  // Source content keeps its own placement. A Use changes its presentation, not its media clock.
+  const content: StudioEntityDraft[] = projectTimelineMedia(timeline).flatMap((clip, index) => {
+    if (clip.media.visual === undefined) return [];
+    return [{
+      id: `${context.track.outputRef}:content:${clip.segmentId}`,
+      authoredId: clip.segmentId,
+      display: { title: clip.segmentId, layers: [previewLayer(artifactPreview("video", clip.media.visual.artifact.resource), "storyboard")] },
+      ...clip.span, stackOrder: index,
+      inspector: [
+        { id: "segment", label: "Segment", domain: "how", section: { id: "content", label: "Content" }, value: clip.segmentId },
+        { id: "range", label: "Range", domain: "when", section: { id: "placement", label: "Placement" }, value: `${clip.span.startFrame}–${clip.span.endFrameExclusive}`, unit: "f", summary: "Placed interval; the end frame is exclusive." },
+      ],
+      presentation: { entity: "performance-content", chrome: "standard" },
+    }];
+  });
+  const uses: StudioEntityDraft[] = program.uses.map((use, index) => {
+    const authoredId = use.window.subjectId;
+    const child = authoredChildFor(context, authoredId, [temporalTypes.windowSpec]);
+    if (child === undefined) throw new Error(`Performance Use ${authoredId} has no author provenance.`);
+    const style = child.referenceAttributes.style;
+    const temporal = temporalLineageFor(context, authoredId, "window");
+    const semantic = temporalSemanticSource(temporal);
+    return {
+      id: `${context.track.outputRef}:use:${authoredId}`, authoredId,
+      display: { title: style ?? authoredId, layers: [] },
+      ...use.window.span, stackOrder: index,
+      elementRange: child.range,
+      ...(temporal === undefined ? {} : { temporal }),
+      ...(semantic === undefined ? {} : { markerId: semantic.id }),
+      presentation: { entity: "performance-use", chrome: "standard" },
+      band: "uses",
+      renderIds: use.visual.presents.map(present => performancePresentId(authoredId, present.id)),
+      inspector: [{ id: "range", label: "Range", domain: "when", section: { id: "placement", label: "Placement" }, value: `${use.window.span.startFrame}–${use.window.span.endFrameExclusive}`, unit: "f", summary: "Resolved Use interval; the end frame is exclusive. Timeline gestures follow this Use's author timing." }],
+    };
+  });
+  return [...content, ...uses];
+}
+
+export const performanceStudioTrackCompanions: readonly StudioTrackCompanion[] = [{
+  id: "visual", role: "track",
+  output: { type: compositionTypes.visualTrack, surface: "track", modules: [performanceModuleRef] },
+  family: "performance", label: "Performance", tone: "blue", icon: "video",
+  lane: { heightPx: 60 },
+  requiredValues: ["program"],
+  bands: [{
+    id: "uses", placement: "after", heightPx: 15, display: "label",
+    bindings: [{ name: "style", companion: true }],
+    inspector: [{ binding: "style", label: "Style", domain: "how", section: { id: "style", label: "Style" }, control: "text", summary: "The referenced Style is shared by every Use that selects it." }],
+  }],
+  project: projectPerformance,
+}];
+
+export const performanceStudioParameterCompanions: readonly import("@hypit/studio-adapter").StudioParameterCompanion[] = [{
+  id: "style", match: { module: performanceModuleRef, surface: "style" },
+  bindings: [ { name: "frame", referenced: frameBindings },
+    { name: "appearance", recipe: { bindings: appearanceBindings } } ],
+  inspector: [
+    ...frameFields.map(name => ({ binding: `frame.${name}`, label: name[0]!.toUpperCase() + name.slice(1),
+      domain: "where" as const, page: { id: "frame", label: "Frame" }, section: { id: "placement", label: "Placement" },
+      control: "number" as const, number: { suffixes: ["%", "px"], step: 1 } })),
+    ...appearanceInspector,
+  ],
+}];

package/packages/program-space/README.md

@@ -1,20 +1,11 @@
 # `@hypit/program-space`
 
-The time and frame domain shared by a compiled film. ProgramSpace contains `id`, `durationSec` and
-`frameRate`. Script identity belongs to semantic data; the physical film clock also serves animation
-with no speech or source media.
-
-For spoken work, SemanticTrack projects the selected performance's real duration and frame rate.
-For authored animation, `Space` declares them directly:
-
-```svml
-<import as="time" from="@hypit/program-space@1"/>
-<time:Space id="animation" frame-rate="30" duration="8s"/>
-```
-
-`duration` accepts seconds, milliseconds or frames (`8s`, `8000ms`, `240f`); the result must end on an
-exact frame boundary. The rate may be rational, such as `30000/1001`. `Space` publishes an ordinary
-inline ProgramSpace value and performs no media generation.
-
-`Clock` is the duration-free frame-rate input for media normalization. A clock does not prescribe
-how long a performance will be; its actual normalized material establishes that later.
+`ProgramClock` supplies a positive rational frame rate before material exists. The `Clock` Surface
+publishes it for normalization and Timeline assembly; the same Clock Surface is available from
+`@hypit/timeline-author`.
+
+`ProgramSpace` is the lightweight physical range consumed by rendering: `id`, `durationSec` and
+`frameRate`. Its positive duration ends on an exact frame boundary. The Timeline projects this
+view, whether it contains speaking Takes, wordless media, gaps or no Takes at all. Authors declare
+that complete work through [Timeline](../timeline-author/README.md), then components obtain the
+range and any semantic evidence they need. The range itself carries no media or word table.

package/packages/program-space/src/activation.ts

@@ -1,6 +1,6 @@
 import { createMarkupSurfaceHostFacet } from "@hypit/markup";
 
-import { decodeClockSurface, decodeSpaceSurface } from "./surface.js";
+import { decodeClockSurface } from "./surface.js";
 import { programSpaceManifest, programSpaceMarkupSurfaces, programSpaceModuleRef } from "./index.js";
 
 export const hypitPackage = {
@@ -10,10 +10,6 @@ export const hypitPackage = {
     module: programSpaceModuleRef,
     declaration: programSpaceMarkupSurfaces.find((item) => item.name === "clock")!,
     handler: decodeClockSurface,
-  }), createMarkupSurfaceHostFacet({
-    module: programSpaceModuleRef,
-    declaration: programSpaceMarkupSurfaces.find((item) => item.name === "space")!,
-    handler: decodeSpaceSurface,
   })],
 };
 export default hypitPackage;

package/packages/program-space/src/index.ts

@@ -40,17 +40,6 @@ export const programSpaceManifest: ModuleManifest = {
 export const programSpaceDependency = { module: programSpaceModuleRef } as const;
 export const programSpaceMarkupSurfaces = [
   { name: "clock", tag: "Clock", mode: "structured", outputs: [programSpaceTypes.clock] },
-  { name: "space", tag: "Space", mode: "structured", outputs: [programSpaceTypes.programSpace],
-    vocabulary: {
-      summary: "Declares a film's frame rate and authored duration, for animation whose timing is directed without a performance.",
-      attributes: [
-        { name: "id", kind: "identifier", required: true, summary: "Names the shared film time axis." },
-        { name: "frame-rate", kind: "literal", required: true, summary: "Frames per second, such as 30 or 30000/1001." },
-        { name: "duration", kind: "literal", required: true, summary: "Total duration in seconds, milliseconds or frames, such as 8s or 240f; ends on a frame boundary." },
-      ],
-      example: '<time:Space id="animation" frame-rate="30" duration="8s"/>',
-    },
-  },
 ] as const;
 
 export function sealProgramClock(value: ProgramClock): ProgramClock {
@@ -105,3 +94,5 @@ export function assertProgramSpaceIdentity(programSpace: ProgramSpace): void {
   }
   programSpaceFrameCount(programSpace);
 }
+
+export { decodeClockSurface } from "./surface.js";

package/packages/program-space/src/surface.ts

@@ -5,7 +5,7 @@ import {
   type StructuredSurfaceHandler,
 } from "@hypit/markup";
 
-import { assertProgramSpaceIdentity, programSpaceTypes, sealProgramClock, type ProgramClock } from "./index.js";
+import { programSpaceTypes, sealProgramClock, type ProgramClock } from "./index.js";
 
 function frameRate(element: StructuredElement): ProgramClock["frameRate"] {
   const value = text(element, "frame-rate");
@@ -34,22 +34,3 @@ export const decodeClockSurface: StructuredSurfaceHandler = ({ element }) => {
     fragments: [],
   };
 };
-
-export const decodeSpaceSurface: StructuredSurfaceHandler = ({ element }) => {
-  const expected = ["duration", "frame-rate", "id"];
-  if (Object.keys(element.attributes).sort().join("\0") !== expected.join("\0")) {
-    throw new Error(`${element.name} requires exactly id, frame-rate and duration.`);
-  }
-  empty(element);
-  const id = text(element, "id");
-  const rate = frameRate(element);
-  const duration = text(element, "duration");
-  const match = /^(\d+(?:\.\d+)?)(s|ms|f)$/u.exec(duration);
-  if (match === null) throw new Error(`${element.name}.duration must be a duration such as 8s, 8000ms or 240f.`);
-  const value = Number(match[1]);
-  const durationSec = match[2] === "f" ? value * rate.denominator / rate.numerator
-    : match[2] === "ms" ? value / 1000 : value;
-  const space = { id, durationSec, frameRate: rate };
-  assertProgramSpaceIdentity(space);
-  return { records: [{ id, type: programSpaceTypes.programSpace, value: { kind: "inline", value: space }, range: element.range }], components: [], fragments: [] };
-};

package/packages/project-context-node/README.md

@@ -0,0 +1,20 @@
+# `@hypit/project-context-node`
+
+Shared project and Runtime selection for Node entrypoints: CLI, Studio and creation tools.
+This package resolves locations and reads or explicitly changes the project's Runtime pointer.
+It does not load Providers, install programs, inspect credentials or select services.
+
+1. `resolveProjectRoot({ workspaceRoot?, cwd? })` uses the explicit Workspace, otherwise the nearest
+   `package.json` above cwd, otherwise cwd itself. Source and Run filenames do not choose the project.
+2. `findRuntimeProfile(projectRoot)` reads only that project's `.hypit/runtime` file and resolves its
+   path relative to the project. An entrypoint's explicit `--runtime` overrides this read for that invocation.
+3. The selected Runtime implementation interprets the Profile, including `dataRoot`, Credentials,
+   Providers and capability bindings. This package does not interpret its contents.
+
+`selectRuntimeProfile(projectRoot, profile)` writes the explicit choice; `clearRuntimeProfile` removes
+only that pointer. A directory occupying the pointer path is reported without replacing it. Runtime
+working data belongs at the Profile's separate `dataRoot`.
+
+Project packages, the installed Distribution and machine-managed executables have different owners.
+The Distribution supplies code; it does not supply a second project environment. Provider adapters
+resolve their executable configuration and report availability through the Runtime's existing ports.

package/packages/project-context-node/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@hypit/project-context-node",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  }
+}

package/packages/project-context-node/src/index.ts

@@ -0,0 +1,3 @@
+export { resolveProjectRoot, resolvePackageRoot } from "./project-context.js";
+export { findRuntimeProfile, selectRuntimeProfile, clearRuntimeProfile } from "./runtime-selection.js";
+export type { RuntimeProfileSelection } from "./runtime-selection.js";

package/packages/{cli → project-context-node}/src/runtime-selection.ts

@@ -1,4 +1,4 @@
-import { mkdir, readFile, realpath, unlink, writeFile } from "node:fs/promises";
+import { mkdir, readFile, realpath, stat, unlink, writeFile } from "node:fs/promises";
 import { relative, resolve } from "node:path";
 
 const stateDirectoryName = ".hypit";
@@ -24,6 +24,10 @@ async function readSelectionFile(projectRoot: string): Promise<{
   const root = resolve(projectRoot);
   const selectionFile = resolve(root, stateDirectoryName, selectionFileName);
   try {
+    if (!(await stat(selectionFile)).isFile()) {
+      throw new Error(`Runtime selection must be a file: ${selectionFile}; this path is occupied by a directory. `
+        + "Move that directory and update its configuration before running hypit runtime use <profile>.");
+    }
     return {
       projectRoot: root,
       selectionFile,
@@ -36,7 +40,7 @@ async function readSelectionFile(projectRoot: string): Promise<{
 }
 
 /**
- * Remember one Runtime Profile for a project. This is local CLI context, not
+ * Remember one Runtime Profile for a project. This is project execution context, not
  * Author Source, Run Source, package selection or Core state.
  */
 export async function selectRuntimeProfile(projectRoot: string, profile: string): Promise<RuntimeProfileSelection> {
@@ -50,6 +54,7 @@ export async function selectRuntimeProfile(projectRoot: string, profile: string)
   } catch (error) {
     if (errorCode(error) !== "EEXIST") throw error;
   }
+  await readSelectionFile(root);
   const stored = relative(root, selectedProfile) || ".";
   await writeFile(selectionFile, `${stored}\n`, "utf8");
   return { profile: selectedProfile, projectRoot: root, selectionFile };

package/packages/provider-hyperframes-local/README.md

@@ -9,24 +9,32 @@ content identity or hidden output metadata.
 
 Normalized transparent videos displayed by Media or project components use the ordinary video path.
 The engine decodes them to PNG frames with alpha, then Chrome blends them with lower layers and
-the authored Canvas background. PNG is the intermediate capture format; it does not ask to erase
-the Film's background. The returned MP4 contains the completed composition.
+the authored Canvas background. Final frames use fast PNG encoding after Chrome has composited
+the image onto an opaque canvas (black beneath the authored background). This trades intermediate
+compression effort for speed without JPEG frame compression. Source alpha, CSS filters, canvas and
+WebGL remain part of the browser composition. The returned MP4 contains the completed composition.
 
 Runtime configuration separates work size from shared capacity:
 
 - `defaultConcurrency` limits whole render requests admitted by the Endpoint's Runtime capacity resource.
 - Optional `browserCapacity` limits Chrome slots shared by all render Needs in the same `pool`.
-  Each Need reserves its actual worker count atomically with the whole-request slot. A request larger
-  than this budget reports a configuration error; it does not silently reduce the requested workers.
+  Each Need reserves its fixed count or automatic ceiling atomically with the whole-request slot.
+  An explicit count larger than this budget reports a configuration error. Auto fits its ceiling
+  to the shared budget before admission.
   Both reservations last for the whole Need, including preparation and final encoding. Closing one
   Chrome early does not release part of that reservation. Without `browserCapacity`, admission uses
   the whole-request limit alone.
 - `workers` controls independent Chrome processes inside one admitted render. Explicit counts are
-  honored, capped only by selected frame count. `auto` uses half the available CPU parallelism,
-  bounded to 1–4 workers.
+  honored, capped only by selected frame count. `auto` starts below its ceiling, then compares useful
+  capture batches before adding another browser. Insufficient benefit or falling throughput retires
+  surplus browsers between batches. Completed frames are retained; there is no calibration render.
+- Optional `maxWorkers` sets the automatic ceiling. Without it, the Provider leaves two CPU slots
+  and half the machine/container memory for other work, budgeting about 1.5 GiB per Chrome process.
+  Auto also caps the reservation to the number of roughly one-second batches in the selected range.
 
 The Runtime Profile configures these controls through the Provider because they are deployment policy.
-`auto` is resolved when the Provider is activated, so admission and execution use the same count. It never
+The automatic ceiling is fixed at activation, and range sizing is identical in admission and execution.
+Actual concurrency adapts inside that reservation; it is not a machine-wide history or performance database. It never
 renders program audio; `@hypit/provider-media-local` separately prepares `TimelineAudio` and muxes
 the final media.
 
@@ -48,11 +56,16 @@ For a Runtime Profile, place `pool` on the Endpoint entry and these Provider set
 This configuration admits one 4-worker request at a time under its 6-browser budget even though
 the whole-request limit is 2. Two 4-worker requests would need 8 browser slots. Choose budgets from
 the actual machine and shared workloads; the example is not an automatic tuning recommendation.
-Reload the Runtime Worker after changing its Profile and restart Studio if it uses that Profile.
+New Builds use the edited Provider configuration; active Builds retain their selected configuration.
+Restart Studio if its existing session needs to load the edited Profile.
 
 `browserGpu` picks Chrome's rasterizer and defaults to `hardware`. Set `software` without a usable
 GPU, or `auto` to let the engine decide. Capture uses screenshots and independent browser processes;
-the CLI's automatic worker and drawElement policies do not override the count.
+the CLI's automatic worker and drawElement policies do not override the count. The opaque screenshot
+adapter uses the engine's public session, video injector and page seek protocol plus Chrome CDP.
+It waits for seek completion, dynamic images/fonts and the page compositor before capturing PNGs.
+The pinned engine couples its PNG session setup to transparent export, so this adapter initializes
+an opaque session and chooses PNG separately at capture. It does not patch engine methods or files.
 
 The Runtime Adapter also declares one managed browser program. `programs up` invokes the pinned
 HyperFrames CLI's `browser ensure`; its probe resolves and starts that browser and checks
@@ -71,8 +84,12 @@ const visual = await renderHyperframesVisual(
 
 Omit `range` for the complete document. Ranges are zero-based and half-open on the original
 programme clock. At 30 fps, `[240, 360)` returns 120 frames covering seconds 8–12.
-`onProgress` reports preparation, worker ranges, browser PIDs, completion and elapsed time to direct
-executor callers. The Runtime Provider does not currently forward these events as Build progress.
+`onProgress` reports resource staging, source decoding, the requested range, per-worker frame counts, browser PIDs,
+encoding, storage and elapsed time to direct executor callers. The Provider reduces parallel worker
+events to a single phase and aggregate count through `context.reportProgress`. CLI status and follow
+display that activity without `--verbose`. Counter writes are coalesced to about once per second;
+phase changes and completed counts are reported promptly. Local activity belongs to the running
+Command, not a remote Operation or a repeatedly rewritten Result manifest.
 `processTimeoutMs` defaults to 30 minutes and starts one deadline before resource preparation. It
 covers resource reads, Surface validation, rendering and output storage. `signal` can end the same
 execution earlier. ResourceStore I/O and Surface probes receive the cancellation signal; a custom
@@ -95,10 +112,13 @@ cleanup. A completed worker closes its Chrome immediately.
 One call stages the HTML and every declared asset once. Typed Surface validation includes a complete
 decoded-frame count, even for a short render interval. The renderer then finds source-frame windows
 needed by that interval, merges overlapping windows, and extracts them one source/window at a time.
-Decoded PNGs are shared by all workers in this call. Each worker initializes its own page and captures
-its assigned frames at their original absolute times. Output numbering starts at zero; final H.264
-encoding runs once after all workers finish. More workers parallelize capture, while staging,
-validation, source extraction and final encoding still contribute their own cost.
+Decoded PNGs are shared by all workers in this call. Each worker initializes its own page, then takes
+short contiguous frame batches from the render's in-memory queue. A free worker can continue with
+another batch instead of waiting for a worker assigned a more expensive passage. Batches span at
+most about one second and preserve the original absolute frame times. Output numbering starts at
+zero; final H.264 encoding runs once after all workers finish. This division is internal to one
+render call; it does not create or resume Builds. Extra workers help only while aggregate throughput
+improves. Staging, validation, source extraction and final encoding still contribute their own cost.
 
 Each call has its own temporary directory, local server port and Chrome processes. Separate renders
 do not share staged files or decoded PNGs. Exact compiler sampling markers retain loops, holds and
@@ -127,3 +147,11 @@ Direct `renderHyperframesVisual()` calls do not enter Runtime's shared admission
 
 The current package executes trusted official code in a local process. It is not a sandbox for
 untrusted documents or community renderer implementations.
+
+Provider calls forward renderer diagnostics through `context.reportDiagnostic`. The initial record
+states the frame count, worker policy/ceiling, capture path, quality, GPU mode and selected encoder.
+Phase timings, concurrency changes and per-worker seek/preparation/PNG totals are recorded once
+per phase, decision or finished worker. Disposable capture-process
+stdout/stderr are streamed as diagnostics and drained before the call returns; existing output limits
+still apply. Phase changes cover preparation, decoding, browser startup, capture, encoding and storage.
+`hypit logs <build-id>` retains those records after temporary rendering files have been removed.

package/packages/provider-hyperframes-local/src/activation.ts

@@ -21,7 +21,7 @@ const localHyperframesRuntimeAdapter = createRuntimeEndpointAdapterFacet({
     if (context.pool === undefined) throw new Error("local HyperFrames Provider Pool is required");
     const config = runtimeConfigObject(context.config, "local HyperFrames");
     runtimeConfigExact(config, [
-      "nodePath", "hyperframesCliPath", "ffprobePath", "ffmpegPath", "workers", "quality", "browserGpu",
+      "nodePath", "hyperframesCliPath", "ffprobePath", "ffmpegPath", "workers", "maxWorkers", "quality", "browserGpu",
       "defaultConcurrency", "browserCapacity", "initializationTimeoutMs", "frameTimeoutMs", "processTimeoutMs", "maxProcessOutputBytes", "maxRenderedBytes",
     ], "local HyperFrames");
     runtimeConfigString(config.nodePath, "HyperFrames nodePath");
@@ -43,11 +43,12 @@ const localHyperframesRuntimeAdapter = createRuntimeEndpointAdapterFacet({
     const configuredCli = runtimeConfigString(config.hyperframesCliPath, "HyperFrames hyperframesCliPath");
     const configuredFfprobe = runtimeConfigString(config.ffprobePath, "HyperFrames ffprobePath");
     const nodePath = resolveRuntimeExecutable(context.dataRoot, configuredNode ?? process.execPath);
-    const hyperframesCliPath = resolveRuntimeExecutable(context.dataRoot, configuredCli ?? defaultHyperframesCliPath());
+    const hyperframesCliPath = () => resolveRuntimeExecutable(context.dataRoot, configuredCli ?? defaultHyperframesCliPath());
     const configuredFfmpeg = runtimeConfigString(config.ffmpegPath, "HyperFrames ffmpegPath");
     const ffmpegPath = resolveRuntimeExecutable(context.dataRoot, configuredFfmpeg ?? "ffmpeg");
     const ffprobePath = resolveRuntimeExecutable(context.dataRoot, configuredFfprobe ?? "ffprobe");
     const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "HyperFrames defaultConcurrency");
+    const maxWorkers = runtimeConfigPositiveInteger(config.maxWorkers, "HyperFrames maxWorkers");
     const browserCapacity = runtimeConfigPositiveInteger(config.browserCapacity, "HyperFrames browserCapacity");
     const initializationTimeoutMs = runtimeConfigPositiveInteger(config.initializationTimeoutMs, "HyperFrames initializationTimeoutMs");
     const frameTimeoutMs = runtimeConfigPositiveInteger(config.frameTimeoutMs, "HyperFrames frameTimeoutMs");
@@ -59,10 +60,10 @@ const localHyperframesRuntimeAdapter = createRuntimeEndpointAdapterFacet({
         instance: context.instance,
         pool: context.pool,
         nodePath,
-        hyperframesCliPath,
         ffprobePath,
         ffmpegPath,
         ...(workers === undefined ? {} : { workers: workers as HyperframesWorkers }),
+        ...(maxWorkers === undefined ? {} : { maxWorkers }),
         ...(quality === undefined ? {} : { quality: quality as HyperframesQuality }),
         ...(browserGpu === undefined ? {} : { browserGpu: browserGpu as HyperframesBrowserGpu }),
         ...(defaultConcurrency === undefined ? {} : { defaultConcurrency }),