@hypit/hypit 0.0.1 → 0.1.1

package/packages/studio/src/preview/runtime-shim.ts

@@ -0,0 +1,184 @@
+/**
+ * Studio's frame driver for a compiled HyperFrames document.
+ *
+ * HyperFrames remains the owner of layout and animation. Studio only supplies
+ * an absolute Program frame, places every timed Present/material at that
+ * instant, and waits until a discrete media seek is actually decoded.
+ */
+function shim(): string {
+  return String.raw`
+<script>
+(function () {
+  var muted = false;
+  var root = document.querySelector('[data-composition-id]');
+  var fpsAttr = (root && root.getAttribute('data-fps')) || '30';
+  var slash = fpsAttr.indexOf('/');
+  var fps = slash === -1
+    ? parseFloat(fpsAttr)
+    : parseFloat(fpsAttr.slice(0, slash)) / parseFloat(fpsAttr.slice(slash + 1));
+  var frameSeconds = 1 / fps;
+  var currentSeconds = 0;
+  var playing = false;
+  var seekRevision = 0;
+  if (root) {
+    root.style.width = (root.getAttribute('data-width') || '0') + 'px';
+    root.style.height = (root.getAttribute('data-height') || '0') + 'px';
+  }
+
+  var visualClips = [];
+  for (var clip of document.querySelectorAll('.hypit-visual-present')) {
+    visualClips.push({
+      element: clip,
+      start: parseFloat(clip.getAttribute('data-start') || '0') || 0,
+      duration: parseFloat(clip.getAttribute('data-duration') || '0') || 0
+    });
+  }
+  // Sampling runs are separate video elements with their own absolute spans.
+  // Addressing only their containing Present makes every run paint at once.
+  var media = [];
+  for (var element of document.querySelectorAll('.hypit-visual-present video')) {
+    var present = element.closest('.hypit-visual-present');
+    var ownStart = element.getAttribute('data-start');
+    var ownDuration = element.getAttribute('data-duration');
+    media.push({
+      element: element,
+      start: parseFloat(ownStart || (present && present.getAttribute('data-start')) || '0') || 0,
+      duration: parseFloat(ownDuration || (present && present.getAttribute('data-duration')) || '0') || 0,
+      mediaStart: parseFloat(element.getAttribute('data-media-start') || '0') || 0,
+      rate: parseFloat(element.getAttribute('data-playback-rate') || '1') || 1
+    });
+  }
+  var programmeAudio = [];
+  for (var element of document.querySelectorAll('.hypit-studio-audio')) {
+    programmeAudio.push({
+      element: element,
+      start: parseFloat(element.getAttribute('data-start') || '0') || 0,
+      duration: parseFloat(element.getAttribute('data-duration') || '0') || 0,
+      mediaStart: parseFloat(element.getAttribute('data-media-start') || '0') || 0,
+      mediaEnd: parseFloat(element.getAttribute('data-media-end') || '0') || 0,
+      loop: element.getAttribute('data-loop') === 'true',
+      phase: parseFloat(element.getAttribute('data-phase') || '0') || 0,
+      rate: parseFloat(element.getAttribute('data-playback-rate') || '1') || 1,
+      gain: parseFloat(element.getAttribute('data-gain') || '1') || 1
+    });
+  }
+
+  function seekDecoded(element, target) {
+    if (Math.abs(element.currentTime - target) < 0.0005 && element.readyState >= 2) return Promise.resolve();
+    return new Promise(function (resolve) {
+      var done = function () {
+        element.removeEventListener('seeked', done);
+        element.removeEventListener('error', done);
+        resolve();
+      };
+      element.addEventListener('seeked', done, { once: true });
+      element.addEventListener('error', done, { once: true });
+      try { element.currentTime = target; }
+      catch (error) { done(); }
+    });
+  }
+
+  function placeHyperframes(seconds) {
+    var pending = [];
+    var event = new CustomEvent('hf-seek', { detail: {
+      time: seconds,
+      waitUntil: function (promise) { pending.push(Promise.resolve(promise)); }
+    }});
+    window.dispatchEvent(event);
+    var compositionId = root && root.getAttribute('data-composition-id');
+    var timeline = compositionId && window.__timelines && window.__timelines[compositionId];
+    if (timeline) {
+      if (typeof timeline.pause === 'function') timeline.pause();
+      if (typeof timeline.totalTime === 'function') timeline.totalTime(seconds);
+      else if (typeof timeline.seek === 'function') timeline.seek(seconds);
+    }
+    return Promise.all(pending);
+  }
+
+  function apply(seconds, scrubbing) {
+    currentSeconds = Math.max(0, seconds);
+    var revision = ++seekRevision;
+    var waits = [];
+    for (var record of visualClips) {
+      var local = currentSeconds - record.start;
+      record.element.style.visibility = local >= 0 && local < record.duration ? 'visible' : 'hidden';
+    }
+    for (var record of media) {
+      var local = currentSeconds - record.start;
+      var inside = local >= 0 && local < record.duration;
+      var element = record.element;
+      element.style.visibility = inside ? 'visible' : 'hidden';
+      // Normalized picture Artifacts are deliberately silent. Programme sound
+      // comes from the exact AudioTrack below rather than from a video sidecar.
+      element.muted = true;
+      if (!inside) { element.pause(); continue; }
+      var target = record.mediaStart + (local + frameSeconds / 2) * record.rate;
+      if (Number.isFinite(element.duration) && element.duration > 0) {
+        target = Math.min(target, Math.max(0, element.duration - 0.001));
+      }
+      if (scrubbing || local >= record.duration - frameSeconds - 0.000001) {
+        element.pause();
+        waits.push(seekDecoded(element, target));
+      } else {
+        // During continuous playback the decoder owns its clock. A frame event
+        // only corrects visible drift; making every refresh a media seek is what
+        // previously froze the preview between frames.
+        if (Math.abs(element.currentTime - target) > 0.08) element.currentTime = target;
+        element.playbackRate = record.rate;
+        if (element.paused) {
+          var started = element.play();
+          if (started) started.catch(function () {});
+        }
+      }
+    }
+    for (var record of programmeAudio) {
+      var local = currentSeconds - record.start;
+      var inside = local >= 0 && local < record.duration;
+      var element = record.element;
+      element.muted = muted || scrubbing;
+      if (!inside) { element.pause(); continue; }
+      var interval = Math.max(0, record.mediaEnd - record.mediaStart);
+      var advanced = (local + frameSeconds / 2) * record.rate;
+      var target = record.mediaStart + advanced;
+      if (record.loop && interval > 0) target = record.mediaStart + ((record.phase + advanced) % interval);
+      else target = Math.min(target, Math.max(record.mediaStart, record.mediaEnd - 0.000001));
+      if (scrubbing || local >= record.duration - frameSeconds - 0.000001) {
+        element.pause();
+        waits.push(seekDecoded(element, target));
+      } else {
+        if (Math.abs(element.currentTime - target) > 0.08) element.currentTime = target;
+        element.playbackRate = record.rate;
+        element.volume = Math.max(0, Math.min(1, record.gain));
+        if (element.paused) {
+          var started = element.play();
+          if (started) started.catch(function () {});
+        }
+      }
+    }
+    waits.push(placeHyperframes(currentSeconds));
+    return Promise.all(waits).then(function () { return revision === seekRevision; });
+  }
+
+  window.__hypitSetMuted = function (value) {
+    muted = !!value;
+    return apply(currentSeconds, !playing);
+  };
+  window.__hypitSeekFrame = function (frame) {
+    playing = false;
+    return apply(frame / fps, true);
+  };
+  window.__hypitPlayFrame = function (frame) {
+    playing = true;
+    return apply(frame / fps, false);
+  };
+  window.__hypitFrameReady = apply(0, true);
+  window.addEventListener('load', function () { window.__hypitFrameReady = apply(currentSeconds, true); });
+})();
+</script>`;
+}
+
+export function injectRuntimeShim(html: string, audio = ""): string {
+  const script = audio + shim();
+  const at = html.lastIndexOf("</body>");
+  return at < 0 ? html + script : html.slice(0, at) + script + html.slice(at);
+}

package/packages/studio/src/programme.ts

@@ -0,0 +1,276 @@
+import type { ArtifactAttachment } from "@hypit/workspace";
+import type { BlobRef, ResourceId, StoredValue } from "@hypit/protocol";
+import { sameType } from "@hypit/protocol";
+import type { Composition } from "@hypit/composition";
+import { compositionTypes } from "@hypit/composition";
+import {
+  projectSemanticProgramSpace,
+  semanticAnchorFrames,
+  semanticTrackSpans,
+} from "@hypit/semantic-track";
+import type { SemanticTrack } from "@hypit/semantic-track";
+import { semanticTrackTypes } from "@hypit/semantic-track";
+import { assertProgramSpaceIdentity, programSpaceTypes } from "@hypit/program-space";
+import type { ProgramSpace } from "@hypit/program-space";
+import type { StudioResolvedTrack, StudioTemporalBinding } from "@hypit/studio-adapter";
+import type { RuntimeHostTransientExecution } from "@hypit/runtime-host-node";
+
+import type { CompiledSource, ServedFile } from "./compile.js";
+import type { StudioDomain } from "./domain.js";
+import { executeStudioProjection, MemoryResourceStore } from "./execute.js";
+import type { RunPlan } from "./run.js";
+import type { StudioViewRequirement } from "./studio-preflight.js";
+import { studioSurfacePreview } from "./surface-preview.js";
+import { executedTemporalBindings } from "./temporal-graph.js";
+
+function playable(type: import("@hypit/protocol").TypeRef): boolean {
+  return sameType(type, compositionTypes.visualTrack) || sameType(type, compositionTypes.audioTrack);
+}
+
+export type BuiltTrack = StudioResolvedTrack;
+
+export type Preview = {
+  readonly source: CompiledSource;
+  readonly tracks: readonly BuiltTrack[];
+  /** Resolved Companion realizations keyed by exact graph output ref. */
+  readonly values: ReadonlyMap<string, unknown>;
+  readonly temporalBindings: ReadonlyMap<string, readonly StudioTemporalBinding[]>;
+  readonly composition: Composition;
+  readonly timing: "measured" | "authored";
+  readonly narrativeId?: string;
+  readonly timingOutput?: { readonly name: string; readonly ref: string };
+  readonly timingCandidateId?: string;
+  readonly timingCandidateOrigin: "run" | "source" | "none";
+  readonly served: ReadonlyMap<string, ServedFile>;
+  readonly canvas: { readonly width: number; readonly height: number; readonly clearColor: string };
+  readonly frameRate: { readonly numerator: number; readonly denominator: number };
+  readonly space: ProgramSpace;
+  readonly anchors: ReadonlyMap<string, number>;
+  readonly tokens: readonly {
+    readonly id: string;
+    readonly startAnchorId: string;
+    readonly endAnchorId: string;
+  }[];
+};
+
+async function bytesOf(attachment: ArtifactAttachment): Promise<Uint8Array> {
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  for await (const chunk of await attachment.open()) {
+    const copy = Uint8Array.from(chunk);
+    chunks.push(copy);
+    size += copy.byteLength;
+  }
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+}
+
+type ExecutionState = Awaited<ReturnType<typeof executeStudioProjection>>["state"];
+
+function selectedValue(
+  state: ExecutionState,
+  output: string,
+): StoredValue | undefined {
+  const selection = state.plan.outputBindings.find((item) => item.output === output);
+  if (selection === undefined) return state.program.records.find((item) => item.id === output)?.value;
+  const executed = state.records.find((item) => item.id === selection.record)?.value;
+  if (executed !== undefined) return executed;
+  // Inline Source and Run candidates both belong to this freshly recompiled
+  // revision. There is no stale-plan distinction to reconstruct here.
+  return state.program.records.find((item) => item.id === selection.record)?.value;
+}
+
+function compositionArtifacts(composition: Composition): readonly BlobRef[] {
+  const found = new Map<ResourceId, BlobRef>();
+  const visit = (value: unknown): void => {
+    if (value === null || typeof value !== "object") return;
+    if ((value as { readonly kind?: unknown }).kind === "blob") {
+      const artifact = value as BlobRef;
+      found.set(artifact.resource, artifact);
+      return;
+    }
+    if (Array.isArray(value)) {
+      for (const item of value) visit(item);
+      return;
+    }
+    for (const item of Object.values(value)) visit(item);
+  };
+  visit(composition);
+  return [...found.values()];
+}
+
+/** Build only the Studio-approved deterministic projection of one explicit Run. */
+export async function preview(input: {
+  readonly source: CompiledSource;
+  readonly run: RunPlan;
+  readonly domain: StudioDomain;
+  readonly outputRefs: readonly string[];
+  readonly compositionRef: string;
+  readonly timeRef: string;
+  readonly projections: readonly StudioViewRequirement[];
+  /** Runtime-owned execution for capabilities explicitly safe outside a Build. */
+  readonly transientExecution?: RuntimeHostTransientExecution;
+}): Promise<Preview> {
+  const exportsByRef = new Map(input.source.exports.map((item) => [item.ref, item] as const));
+  const targets = input.outputRefs.flatMap((ref) => {
+    const found = exportsByRef.get(ref);
+    return found === undefined ? [] : [found];
+  });
+  const store = new MemoryResourceStore();
+  const served = new Map(input.source.served);
+  for (const attachment of input.run.attachments) {
+    const bytes = await bytesOf(attachment);
+    await store.write(attachment.artifact, bytes);
+    served.set(attachment.artifact.resource, {
+      mediaType: attachment.artifact.mediaType,
+      bytes,
+    });
+  }
+  for (const [resource, file] of input.source.served) {
+    await store.write({ kind: "blob", resource: resource as ResourceId, size: file.bytes.byteLength, mediaType: file.mediaType }, file.bytes);
+  }
+  const resources = {
+    async get(resource: ResourceId) {
+      return await store.get(resource);
+    },
+    async put(bytes: Uint8Array, mediaType: string) {
+      const ref = await store.put(bytes, mediaType);
+      served.set(ref.resource, { mediaType, bytes });
+      return ref;
+    },
+    async write(resource: BlobRef, bytes: Uint8Array) {
+      await store.write(resource, bytes);
+      served.set(resource.resource, { mediaType: resource.mediaType, bytes });
+    },
+    async has(resource: ResourceId) {
+      return await store.has(resource);
+    },
+  };
+  const planned = input.run.plan(input.run.run, targets.map((target) => target.ref));
+  const executed = await executeStudioProjection(
+    input.domain,
+    planned.state,
+    resources,
+    input.transientExecution,
+  );
+  if (executed.unserved.length > 0) {
+    throw new Error(
+      `Studio projection is unresolved: ${executed.unserved.map((item) => item.capability).join(", ")}`,
+    );
+  }
+  if (executed.errors.length > 0) throw new Error(executed.errors.join("\n"));
+
+  const satisfactions = new Map(
+    input.run.run.graph.satisfactions.map((item) => [item.output, item.candidate]),
+  );
+  const timingOutput = input.source.exports.find((target) => target.ref === input.timeRef);
+  const timingRecord = executed.state.program.records.find((record) => record.id === input.timeRef);
+  const timingType = timingOutput?.typeRef ?? timingRecord?.type;
+  const timingValue = selectedValue(executed.state, input.timeRef);
+  if (timingValue?.kind !== "inline" || timingType === undefined) throw new Error("Studio requires a resolved film time source.");
+  const semantic = sameType(timingType, semanticTrackTypes.track) ? timingValue.value as unknown as SemanticTrack : undefined;
+  if (semantic === undefined && !sameType(timingType, programSpaceTypes.programSpace)) throw new Error("Unsupported Studio time source.");
+  const spans = semantic === undefined ? [] : semanticTrackSpans(semantic);
+  const anchors = semantic === undefined ? new Map<string, number>() : semanticAnchorFrames(semantic);
+  const space = semantic === undefined ? timingValue.value as unknown as ProgramSpace : projectSemanticProgramSpace(semantic);
+  assertProgramSpaceIdentity(space);
+  const rate = space.frameRate;
+  const compositionValue = selectedValue(executed.state, input.compositionRef);
+  if (compositionValue?.kind !== "inline") {
+    throw new Error("Studio Film composition did not produce an inline Composition.");
+  }
+  const composition = compositionValue.value as unknown as Composition;
+  for (const artifact of compositionArtifacts(composition)) {
+    if (!served.has(artifact.resource)) {
+      throw new Error(`Studio composition Resource ${artifact.resource} has no Run attachment.`);
+    }
+  }
+  const projectionByRef = new Map(input.projections.map((projection) => [projection.ref, projection]));
+  const tracks: BuiltTrack[] = targets.flatMap((target) => {
+    if (!playable(target.typeRef)) return [];
+    const stored = selectedValue(executed.state, target.ref);
+    const candidateId = satisfactions.get(target.ref);
+    if (stored?.kind !== "inline") {
+      throw new Error(`Studio projection ${target.name} did not produce an inline Track.`);
+    }
+    const projection = projectionByRef.get(target.ref);
+    if (projection === undefined) {
+      throw new Error(`Studio projection ${target.name} has no Studio trace.`);
+    }
+    const surfacePreview = projection.trace.module === undefined || projection.trace.surface === undefined
+      ? undefined
+      : studioSurfacePreview(input.domain, projection.trace.module, projection.trace.surface);
+    return [{
+      name: target.name,
+      type: target.type,
+      typeRef: target.typeRef,
+      outputRef: target.ref,
+      ...(candidateId === undefined ? {} : { candidateId }),
+      candidateOrigin: candidateId === undefined ? "source" as const : "run" as const,
+      role: projection.role,
+      trace: projection.trace,
+      ...(surfacePreview === undefined ? {} : { surfacePreview }),
+      value: stored.value,
+    }];
+  });
+  const temporalBindings = new Map(tracks.map((track) => [
+    track.outputRef,
+    executedTemporalBindings(executed.state, track.outputRef),
+  ] as const));
+  const values = new Map<string, unknown>();
+  for (const target of targets) {
+    const stored = selectedValue(executed.state, target.ref);
+    if (stored?.kind === "inline") values.set(target.ref, stored.value);
+  }
+  // Author Records are already deterministic inline values from this exact
+  // compilation. Studio Track Companions may need them to name a resolved projection
+  // (for example Caption cue text); exposing them here avoids recomputing the
+  // domain value or turning a Record into a fake graph target.
+  for (const placement of input.source.observations.placements) {
+    for (const value of placement.values) {
+      const suffixes = [`::record::${value.id}`, `::output::${value.id}`];
+      for (const reference of input.projections.flatMap((projection) => projection.trace.references)) {
+        if (suffixes.some((suffix) => reference.ref.endsWith(suffix))) values.set(reference.ref, value.value);
+      }
+    }
+  }
+  // Script is a raw Surface, so its inline Records are not among the structured
+  // element observations above. They are still ordinary Author values from
+  // the same compilation and are needed to turn Caption atom ids back into the
+  // text the author actually sees.
+  for (const record of input.source.compiled.program.records) {
+    if (record.value.kind !== "inline") continue;
+    if (input.projections.some((projection) => projection.trace.references
+      .some((reference) => reference.ref === record.id))) {
+      values.set(record.id, record.value.value);
+    }
+  }
+  const timingCandidateId = satisfactions.get(input.timeRef);
+  return {
+    source: input.source,
+    tracks,
+    values,
+    temporalBindings,
+    composition,
+    timing: semantic === undefined ? "authored" : "measured",
+    ...(semantic === undefined ? {} : { narrativeId: semantic.narrativeId }),
+    timingOutput: { name: timingOutput?.name ?? space.id, ref: input.timeRef },
+    ...(timingCandidateId === undefined ? {} : { timingCandidateId }),
+    timingCandidateOrigin: timingCandidateId === undefined ? "source" : "run",
+    served,
+    canvas: composition.canvas,
+    frameRate: rate,
+    space,
+    anchors,
+    tokens: spans.flatMap(({ item }) => item.take.tokens.map((token) => ({
+      id: token.tokenId,
+      startAnchorId: token.startAnchorId,
+      endAnchorId: token.endAnchorId,
+    }))),
+  };
+}

package/packages/studio/src/run.ts

@@ -0,0 +1,85 @@
+import type { PlannedBuild } from "@hypit/compiler-node";
+import { NodeRunCompiler } from "@hypit/compiler-node";
+import type { Candidate, OperationNode, Satisfaction, BuildTarget } from "@hypit/protocol";
+import type { ArtifactAttachment } from "@hypit/workspace";
+import {
+  installRunFragmentHostFacets,
+  runFrontendsFromHostFacets,
+  RunFragmentRegistry,
+  RunFrontendRegistry,
+} from "@hypit/run";
+
+import type { StudioBuildLibrary } from "./build-library.js";
+import { observedCompiledSource } from "./compile.js";
+import type { CompiledSource } from "./compile.js";
+import type { StudioDomain } from "./domain.js";
+import { createObserver } from "./observe.js";
+
+export type RunCompilation = {
+  readonly graph: {
+    readonly candidates: readonly Candidate[];
+    readonly operations: readonly OperationNode[];
+    readonly satisfactions: readonly Satisfaction[];
+    readonly targets: readonly BuildTarget[];
+  };
+};
+
+export type RunPlan = {
+  readonly runPath: string;
+  readonly authorSource: string;
+  /** The observed Author graph used by this exact Run compilation. */
+  readonly source: CompiledSource;
+  readonly run: RunCompilation;
+  readonly targets: readonly string[];
+  readonly attachments: readonly ArtifactAttachment[];
+  readonly plan: (run: RunCompilation, targets: readonly string[]) => PlannedBuild;
+};
+
+/** Compile the exact Run Source selected for Studio, using normal Run facets. */
+export async function loadStudioRun(input: {
+  readonly run: string;
+  readonly domain: StudioDomain;
+  readonly registry: import("./studio-registry.js").StudioCompanionRegistry;
+  readonly buildLibrary?: StudioBuildLibrary;
+}): Promise<RunPlan> {
+  const fragments = new RunFragmentRegistry();
+  const frontends = new RunFrontendRegistry();
+  for (const contribution of input.domain.contributions) {
+    installRunFragmentHostFacets(contribution.hostFacets ?? [], fragments);
+    for (const frontend of runFrontendsFromHostFacets(contribution.hostFacets ?? [])) {
+      frontends.register(frontend);
+    }
+  }
+  const observer = createObserver(input.domain.surfaces, input.registry);
+  const compiler = new NodeRunCompiler({
+    authorCompiler: input.domain.createCompiler(observer.surfaces),
+    fragments,
+    frontends,
+    ...(input.buildLibrary === undefined ? {} : {
+      resolveHistoricalOutput: input.buildLibrary.resolveHistoricalOutput,
+    }),
+  });
+  const compiled = await compiler.compileFile(input.run);
+  const source = await observedCompiledSource(compiled.author, observer.observations());
+  const targets = compiled.run.graph.targets.map((target) => target.output);
+  return {
+    runPath: input.run,
+    authorSource: compiled.authorSource,
+    source,
+    run: compiled.run as RunCompilation,
+    targets,
+    attachments: compiled.attachments,
+    plan(run, selected) {
+      return compiler.planCompilation({
+        ...compiled,
+        run: {
+          ...compiled.run,
+          graph: {
+            ...run.graph,
+            targets: selected.map((output) => ({ output })),
+          },
+        },
+      } as never);
+    },
+  };
+}