@hypit/hypit 0.1.4 → 0.1.6

package/packages/{media-track/src/performance.ts → performance/src/media.ts}

@@ -1,22 +1,21 @@
-import { projectSemanticMedia } from "@hypit/semantic-track";
-import type { SemanticTrack } from "@hypit/semantic-track";
+import { projectTimelineMedia } from "@hypit/timeline";
+import type { Timeline } from "@hypit/timeline";
 import type { ContentFit } from "@hypit/spatial";
-import { appendTimedMediaLayer, createMediaLayerSet } from "./layers.js";
-import { appendMediaItem } from "./program.js";
-import type { MediaSampleLayerSpec } from "./types.js";
+import { appendTimedMediaLayer, createMediaLayerSet } from "@hypit/media-track";
+import { appendMediaItem } from "@hypit/media-track";
+import type { MediaSampleLayerSpec } from "@hypit/media-track";
 
 type ItemArguments = Parameters<typeof appendMediaItem>;
 type PerformanceInput = {
-  set: ItemArguments[0]; header: ItemArguments[1]; space: ItemArguments[2]; canvas: ItemArguments[3];
+  set: ItemArguments[0]; header: ItemArguments[1]; timeline: ItemArguments[2]; canvas: ItemArguments[3];
   layers: ItemArguments[4]; frame: ItemArguments[5]; spec: ItemArguments[6];
   sounds: ItemArguments[7]; window: ItemArguments[8];
 };
 
 /** One framed unit and lifecycle containing all selected performance spans. */
-export function appendMediaPerformance(input: PerformanceInput, semantic: SemanticTrack, fit: ContentFit, sample: MediaSampleLayerSpec) {
-  if (semantic.id !== input.space.id) throw new Error("Media performance must belong to the composition's ProgramSpace.");
+export function appendMediaPerformance(input: PerformanceInput, fit: ContentFit, sample: MediaSampleLayerSpec) {
   const layers = [...input.layers.layers];
-  for (const clip of projectSemanticMedia(semantic, input.window.span)) {
+  for (const clip of projectTimelineMedia(input.timeline, input.window.span)) {
     if (clip.media.visual === undefined) continue;
     const [layer] = appendTimedMediaLayer(createMediaLayerSet(), clip.media, fit, {
       ...sample, id: `${input.spec.id}:${clip.segmentId}`, trim: clip.source, occupancy: { mode: "once", align: "start" },
@@ -32,6 +31,6 @@ export function appendMediaPerformance(input: PerformanceInput, semantic: Semant
     } });
   }
   if (layers.length === 0) return input.set;
-  return appendMediaItem(input.set, input.header, input.space, input.canvas, { layers }, input.frame,
+  return appendMediaItem(input.set, input.header, input.timeline, input.canvas, { layers }, input.frame,
     input.spec, input.sounds, input.window);
 }

package/packages/performance/src/program.ts

@@ -0,0 +1,51 @@
+import { sealVisualTrack, assertVisualTrackIdentity } from "@hypit/composition";
+import type { FrameSpan, VisualTrack } from "@hypit/composition";
+import { assertTemporalWindowFor } from "@hypit/temporal";
+import type { TemporalWindow } from "@hypit/temporal";
+import type { Timeline } from "@hypit/timeline";
+import { VISUAL_IR_V1 } from "@hypit/visual-ir";
+
+export type PerformanceUse = { readonly window: TemporalWindow; readonly visual: VisualTrack };
+export type PerformanceSet = { readonly uses: readonly PerformanceUse[] };
+
+export function appendPerformanceUse(set: PerformanceSet, window: TemporalWindow, visual: VisualTrack): PerformanceSet {
+  assertVisualTrackIdentity(visual);
+  if (visual.programSpaceId !== window.start.source.spaceId) throw new Error("Performance Use and picture belong to different Timelines.");
+  return { uses: [...set.uses, { window, visual }] };
+}
+
+export function intersectVisibility(left: readonly FrameSpan[], right: readonly FrameSpan[]): FrameSpan[] {
+  return left.flatMap(a => right.flatMap(b => {
+    const startFrame = Math.max(a.startFrame, b.startFrame), endFrameExclusive = Math.min(a.endFrameExclusive, b.endFrameExclusive);
+    return endFrameExclusive > startFrame ? [{ startFrame, endFrameExclusive }] : [];
+  }));
+}
+
+export function performancePresentId(useId: string, presentId: string): string {
+  return `${useId}:${presentId}`;
+}
+
+/** Keep original animation/sample origins. Only the visibility mask changes. */
+export function resolvePerformance(timeline: Timeline, id: string, set: PerformanceSet): VisualTrack {
+  const presents: VisualTrack["presents"][number][] = [];
+  for (const [index, use] of set.uses.entries()) {
+    assertTemporalWindowFor(use.window, { subjectId: use.window.subjectId, space: timeline });
+    if (use.visual.programSpaceId !== timeline.id || use.window.start.source.spaceId !== timeline.id) throw new Error("Performance uses another Timeline.");
+    let visible = [use.window.span];
+    for (const later of set.uses.slice(index + 1)) {
+      visible = visible.flatMap(span => {
+        const cut = later.window.span;
+        if (cut.endFrameExclusive <= span.startFrame || cut.startFrame >= span.endFrameExclusive) return [span];
+        return [
+          ...(cut.startFrame > span.startFrame ? [{ startFrame: span.startFrame, endFrameExclusive: cut.startFrame }] : []),
+          ...(cut.endFrameExclusive < span.endFrameExclusive ? [{ startFrame: cut.endFrameExclusive, endFrameExclusive: span.endFrameExclusive }] : []),
+        ];
+      });
+    }
+    for (const present of use.visual.presents) {
+      const visibility = intersectVisibility(visible, present.visibility ?? [present.span]);
+      if (visibility.length) presents.push({ ...present, id: performancePresentId(use.window.subjectId, present.id), visibility });
+    }
+  }
+  return sealVisualTrack({ id, programSpaceId: timeline.id, visualIr: VISUAL_IR_V1, presents });
+}

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 };