@hypit/hypit 0.0.1 → 0.1.1

package/packages/studio/src/ui/writeback.ts

@@ -0,0 +1,10 @@
+import type { StudioMutation } from "../shared.js";
+
+export async function applyStudioMutation(mutation: StudioMutation): Promise<void> {
+  const response = await fetch("/__studio/mutation", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(mutation),
+  });
+  if (!response.ok) throw new Error(await response.text());
+}

package/packages/studio/src/ui/zoom.ts

@@ -0,0 +1,129 @@
+/**
+ * How much of the programme the timeline shows.
+ *
+ * A sixteen-second Source fits; a three-minute one does not, and reading a
+ * cutaway that lasts twelve frames out of five thousand is not possible at one
+ * pixel per forty frames. So the whole programme is drawn as a bar, and the
+ * part currently on the timeline is a window inside it - dragged to move, or
+ * taken by either edge to widen and narrow.
+ */
+
+export type Window = { readonly start: number; readonly end: number };
+
+export type Zoom = {
+  readonly element: HTMLElement;
+  /** The visible fraction of the programme, from 0 to 1. */
+  window(): Window;
+  subscribe(listen: (window: Window) => void): void;
+  /** Zoom about a point, given as a fraction across the visible window. */
+  pinch(at: number, factor: number): void;
+  /** Slide the window by a fraction of its own width. */
+  slide(by: number): void;
+  /** Show a particular programme interval, keeping it inside the strip. */
+  focus(start: number, end: number): void;
+  /** Show the whole programme. */
+  fit(): void;
+};
+
+/** Nothing smaller than this is readable, and nothing larger than all of it exists. */
+// Keep a small amount of surrounding context even at maximum magnification.
+// For the short-form projects Studio targets this is roughly a few hundred
+// milliseconds, enough to read individual frames without turning the ruler
+// into an unbounded microscope.
+const NARROWEST = 0.02;
+
+export function createZoom(): Zoom {
+  const element = document.createElement("div");
+  element.className = "zoom";
+  element.innerHTML = `
+    <div class="zoom-window" data-window>
+      <span class="zoom-grip zoom-grip-start" data-start></span>
+      <span class="zoom-grip zoom-grip-end" data-end></span>
+    </div>`;
+  const held = element.querySelector<HTMLElement>("[data-window]")!;
+  const startGrip = element.querySelector<HTMLElement>("[data-start]")!;
+  const endGrip = element.querySelector<HTMLElement>("[data-end]")!;
+
+  let window_: Window = { start: 0, end: 1 };
+  const listeners: ((window: Window) => void)[] = [];
+
+  const paint = (): void => {
+    held.style.left = `${window_.start * 100}%`;
+    held.style.width = `${(window_.end - window_.start) * 100}%`;
+    for (const listen of listeners) listen(window_);
+  };
+
+  const settle = (start: number, end: number): void => {
+    const width = Math.max(NARROWEST, Math.min(1, end - start));
+    const from = Math.max(0, Math.min(1 - width, start));
+    window_ = { start: from, end: from + width };
+    paint();
+  };
+
+  /** Where a pointer is along the whole bar, as a fraction. */
+  const fraction = (event: PointerEvent): number => {
+    const box = element.getBoundingClientRect();
+    return box.width === 0 ? 0 : Math.max(0, Math.min(1, (event.clientX - box.left) / box.width));
+  };
+
+  const drag = (
+    node: HTMLElement,
+    onMove: (at: number, began: Window, from: number) => void,
+  ): void => {
+    node.addEventListener("pointerdown", (event) => {
+      event.preventDefault();
+      event.stopPropagation();
+      node.setPointerCapture(event.pointerId);
+      const began = window_;
+      const from = fraction(event);
+      const move = (moved: PointerEvent): void => onMove(fraction(moved), began, from);
+      const done = (): void => {
+        node.removeEventListener("pointermove", move);
+        node.removeEventListener("pointerup", done);
+        node.releasePointerCapture(event.pointerId);
+      };
+      node.addEventListener("pointermove", move);
+      node.addEventListener("pointerup", done);
+    });
+  };
+
+  drag(held, (at, began, from) => {
+    const shift = at - from;
+    settle(began.start + shift, began.end + shift);
+  });
+  drag(startGrip, (at, began) => settle(Math.min(at, began.end - NARROWEST), began.end));
+  drag(endGrip, (at, began) => settle(began.start, Math.max(at, began.start + NARROWEST)));
+
+  // Clicking the bar outside the window centres the window there, which is the
+  // fastest way across a long programme.
+  element.addEventListener("pointerdown", (event) => {
+    const width = window_.end - window_.start;
+    const at = fraction(event);
+    settle(at - width / 2, at + width / 2);
+  });
+
+  paint();
+  return {
+    element,
+    window: () => window_,
+    subscribe(listen) { listeners.push(listen); listen(window_); },
+    /**
+     * Pinching over the strip zooms about the point under the fingers, which is
+     * how every other timeline behaves and the only gesture that keeps the clip
+     * being read where it was.
+     */
+    pinch(at: number, factor: number) {
+      const width = window_.end - window_.start;
+      const wanted = Math.max(NARROWEST, Math.min(1, width * factor));
+      const held = window_.start + width * Math.max(0, Math.min(1, at));
+      settle(held - wanted * at, held + wanted * (1 - at));
+    },
+    /** Two fingers moved sideways slide the window without resizing it. */
+    slide(by: number) {
+      const width = window_.end - window_.start;
+      settle(window_.start + by * width, window_.end + by * width);
+    },
+    focus(start: number, end: number) { settle(start, end); },
+    fit() { settle(0, 1); },
+  };
+}

package/packages/studio/start.ts

@@ -0,0 +1,143 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { CliIo } from "@hypit/cli";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+export function writeStudioHelp(io: Pick<CliIo, "write">): void {
+  io.write(`hypit studio
+Open a Run in the browser to inspect its composition, Sources and Results.
+
+  hypit studio --run <build.svrun> [--runtime <hypit.runtime.json>]
+    [--port <number>] [--workspace <directory>] [--package-root <directory>]
+
+Paths are relative to the invoking project. Without --runtime, Studio uses
+that project's selected Runtime Profile. The server prints its browser URL;
+press Ctrl+C to stop it.
+`);
+}
+
+function invalidArguments(message: string): never {
+  throw new Error(`${message}. See hypit studio --help.`);
+}
+
+function argumentsByName(argv: readonly string[]): ReadonlyMap<string, string> {
+  const accepted = new Set(["run", "runtime", "port", "workspace", "package-root"]);
+  const result = new Map<string, string>();
+  for (let index = 0; index < argv.length; index += 2) {
+    const flag = argv[index];
+    const value = argv[index + 1];
+    if (flag === undefined || !flag.startsWith("--") || value === undefined || value.startsWith("--")) {
+      invalidArguments(`Malformed argument near ${flag ?? "end of command"}`);
+    }
+    const name = flag.slice(2);
+    if (!accepted.has(name)) invalidArguments(`Unknown option --${name}`);
+    result.set(name, value);
+  }
+  return result;
+}
+
+export async function runStudio(argv: readonly string[], io: Pick<CliIo, "write">): Promise<void> {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    writeStudioHelp(io);
+    return;
+  }
+  const values = argumentsByName(argv[0] === "--" ? argv.slice(1) : argv);
+  const invokedFrom = process.env.INIT_CWD ?? process.cwd();
+  const runArgument = values.get("run");
+  if (runArgument === undefined || runArgument.trim().length === 0) invalidArguments("Missing --run");
+  const { createServer } = await import("vite");
+  const { findRuntimeProfile, resolveProjectRoot } = await import("@hypit/cli");
+  const { resolveDistributionPackageImport } = await import("@hypit/package-loader-node");
+  const { videoCliDistribution, videoStudioCompanionPackages } = await import("@hypit/video-cli");
+  const { openStudioBuildLibrary } = await import("./src/build-library.js");
+  const { loadStudioCompanionRegistry } = await import("./src/companion-assembly.js");
+  const { loadStudioDomain } = await import("./src/domain.js");
+  const { loadStudioRun } = await import("./src/run.js");
+  const { studioPlugin } = await import("./src/server.js");
+  const { inspectStudioRun } = await import("./src/studio-preflight.js");
+  const runPath = resolve(invokedFrom, runArgument);
+  const packageRootArgument = values.get("package-root");
+  const workspaceArgument = values.get("workspace");
+  const requestedWorkspaceRoot = workspaceArgument === undefined
+    ? undefined
+    : resolve(invokedFrom, workspaceArgument);
+  const workspaceRoot = await resolveProjectRoot({
+    ...(requestedWorkspaceRoot === undefined ? {} : { workspaceRoot: requestedWorkspaceRoot }),
+    cwd: invokedFrom,
+  });
+  const packageRoot = packageRootArgument === undefined
+    ? workspaceRoot
+    : resolve(invokedFrom, packageRootArgument);
+  const runtimeArgument = values.get("runtime");
+  const selectedRuntime = runtimeArgument === undefined
+    ? await findRuntimeProfile(workspaceRoot)
+    : undefined;
+  const runtimePath = runtimeArgument === undefined
+    ? selectedRuntime?.profile
+    : resolve(invokedFrom, runtimeArgument);
+  const port = Number(values.get("port") ?? "5179");
+  if (!Number.isSafeInteger(port) || port <= 0) invalidArguments("--port must be a positive integer");
+
+  const distributionPackageRoot = videoCliDistribution.packageRoot ?? resolve(here, "../..");
+  const domain = await loadStudioDomain({ run: runPath, workspaceRoot, packageRoot });
+  const registry = await loadStudioCompanionRegistry({
+    distributionPackageRoot,
+    distributionPackages: videoStudioCompanionPackages,
+    sourcePackages: domain.packages,
+  });
+  const buildLibrary = await openStudioBuildLibrary(runtimePath, packageRoot, workspaceRoot, distributionPackageRoot);
+  let run;
+  try {
+    run = await loadStudioRun({
+      run: runPath,
+      domain,
+      registry,
+      buildLibrary,
+    });
+  } catch (error) {
+    await buildLibrary.close();
+    throw error;
+  }
+  const source = run.authorSource;
+  try {
+    inspectStudioRun(registry, run.source, run);
+  } catch (error) {
+    await buildLibrary.close();
+    throw error;
+  }
+  const distributionImports = {
+    name: "hypit-distribution-imports",
+    enforce: "pre" as const,
+    resolveId(specifier: string): string | undefined {
+      return resolveDistributionPackageImport(distributionPackageRoot, specifier);
+    },
+  };
+  const server = await createServer({
+    configFile: false,
+    root: here,
+    server: {
+      port,
+      // Vite resolves package assets through pnpm's real paths. The package root
+      // must therefore be readable for self-hosted fonts and other declared
+      // Studio dependencies, while the author workspace remains separately
+      // available for Source and material previews.
+      fs: { allow: [workspaceRoot, packageRoot, distributionPackageRoot, here] },
+    },
+    plugins: [distributionImports, studioPlugin({
+      source,
+      runPath,
+      workspaceRoot,
+      domain,
+      registry,
+      ...(buildLibrary === undefined ? {} : { buildLibrary }),
+    })],
+  });
+  server.httpServer?.once("close", () => {
+    void buildLibrary.close().catch((error: unknown) => {
+      console.error(error instanceof Error ? error.message : String(error));
+    });
+  });
+  await server.listen();
+  server.printUrls();
+}

package/packages/studio-adapter/README.md

@@ -0,0 +1,186 @@
+# `@hypit/hypit/studio-adapter`
+
+The stable companion-package ABI understood by Hypit Studio. It carries only
+presentation, lineage, inspector and interaction DTOs plus helpers that do not
+encode the official video UI policy. Domain computation and manifests do not depend on it;
+package activation can combine domain facets with a separate Companion implementation.
+
+External packages use the public imports below with `@hypit/hypit` as a development dependency, then ship
+compiled JavaScript. The active Distribution supplies these APIs when Studio loads the component.
+
+## A minimal project Track Companion
+
+Suppose `@studio/score-strip@1` already owns a `track` Surface that emits a public VisualTrack and
+accepts a literal string `label` attribute. The Companion can reuse generic terminal entities while
+adding package-specific presentation and one Inspector field:
+
+```ts
+import { compositionTypes } from "@hypit/hypit/composition";
+import type { StudioTrackCompanion } from "@hypit/hypit/studio-adapter";
+
+export const companions: readonly StudioTrackCompanion[] = [{
+  id: "score-strip",
+  role: "track",
+  output: {
+    type: compositionTypes.visualTrack,
+    surface: "track",
+    modules: [{ name: "@studio/score-strip", version: "1" }],
+  },
+  family: "score-strip",
+  label: "Score strip",
+  icon: "ranking",
+  tone: "orange",
+  lane: { heightPx: 64 },
+  poster: { source: "surface-preview" },
+  bindings: [{ name: "label", writable: true }],
+  inspector: [{
+    binding: "label",
+    label: "Label",
+    domain: "how",
+    section: { id: "content", label: "Content" },
+    control: "text",
+  }],
+}];
+```
+
+The names and lane height are this example's choices. Use the real Module ABI, Surface name,
+nominal output Type and authored input names of the component. A Companion does not create a new
+author attribute. Omitting `project` uses generic terminal entities; `poster` adds the declared
+Surface preview when one exists, without changing the component's rendered video.
+
+Merge the facet into the package's existing activation. In this example `authorContribution`
+exports its existing modules, deterministic component and Markup facets:
+
+```ts
+import { createStudioTrackCompanionHostFacet } from "@hypit/hypit/studio-adapter";
+import authorContribution from "./author-activation.js";
+import { companions } from "./studio.js";
+
+export default {
+  ...authorContribution,
+  hostFacets: [
+    ...(authorContribution.hostFacets ?? []),
+    createStudioTrackCompanionHostFacet(companions),
+  ],
+};
+```
+
+Point the package's existing `hypit.activation` at that combined export and include the compiled
+Companion file in the package. Keep the real modules, Producers and Surface facets; a Companion-only
+replacement would remove the component itself. Use the active Distribution's adapter ABI, as
+described in the [Studio README](../studio/README.md), rather than a `workspace:*` dependency in an
+external project.
+
+Studio loads facets from packages selected by the Source closure alongside the Distribution's
+explicit official Companion selection. It qualifies this local id as
+`@studio/score-strip#score-strip`. There is no extra Studio Profile, plugin scan or Core registration.
+Restart the Studio process after changing activation or package code.
+
+## Project domain entities and material
+
+A terminal VisualTrack is enough for generic display. When it loses meaningful domain structure,
+publish a deterministic schedule/program output from the same Surface and name its port in
+`requiredValues`. Inside `project(context)`, retrieve it with `requiredSurfaceValue(context, "schedule")`.
+The port must exist in the Surface's public output mappings; inventing a port name in a Companion
+does not make an internal Producer value observable. `requiredReferencedValue(context, input, type)`
+instead follows one exact typed author reference, such as a CaptionDocument.
+
+`project` returns `StudioEntityDraft[]`. Each entity has an id, authored identity, display title and
+ordered layers, `startFrame`, `endFrameExclusive` and `stackOrder`. Useful optional fields include:
+
+| Field/helper | Purpose |
+| --- | --- |
+| `presentation` | Name the entity's role and choose `standard`, `group` or `point` chrome |
+| `textLayer(text)` | Put explicit domain text in the timeline body |
+| `previewLayer(artifactPreview(kind, resource), layout)` | Show a declared image/video/audio Resource with a finite layout; Studio resolves transport |
+| `renderIds` | Relate an entity to its actual rendered elements |
+| `parameterReferences` | Select exact per-entity authored references, such as the Style really used by this Cue |
+| `temporal` | Carry the executed Instant/Window lineage and its edit authority |
+| `lane` and Companion `attachments` | Put child entities on a declared additional lane, with its own bindings and Inspector |
+| `childEntities` / `authoredChildFor` | Resolve children from public identity and exact Spec Types rather than source order guesses |
+
+Use the program's frame space and half-open intervals. Persistent visibility and its activation are
+different facts: a board item can remain visible until the board ends while its reveal occupies only
+a short child interval. Expose that distinction rather than making a long rectangle imply a long
+entrance animation. Qualify child ids across Track instances; never use an array index as authored
+identity merely because it currently lines up.
+
+Read [Ranking's Companion](../ranking-studio/src/index.ts) for board/reveal lanes,
+[Caption Fine's](../caption-fine-studio/src/index.ts) for Cue text and Style selection, and
+[Media Track's](../media-track-studio/src/index.ts) for material and occupancy.
+
+## Preserve executed temporal lineage
+
+`StudioTrackCompanionContext.temporalBindings` exposes the executed Instant/Window records in the selected
+Track closure, including projection expressions, source identity and direct consumer inputs.
+`temporalLineageFor()` joins a domain entity to those edges through the identity of a value consumed
+beside the projection; it does not inspect author attribute names. No match is read-only, one match
+is used, and several matches are an error rather than a first-result guess. The generic terminal
+fallback tries only the terminal object's exact `subjectId`/`authoredId`; renderer ids and marker ids
+are not alternate guesses.
+
+Track Companions match terminal outputs by complete `TypeRef` and their authoring origin by complete
+`ModuleRef + Surface`; Film and Script companions use the same versioned origin match. Short Type
+and module names remain available for UI text and diagnostics but never decide which Companion is
+allowed to interpret a value.
+
+Trace references retain the exact author input name and resolved TypeRef. A Companion that needs a
+CaptionDocument or another referenced domain value selects that declared edge; it never scans all
+values for a familiar object shape. Child entities follow the same rule: when an optional Source id
+was omitted, a Companion may name the exact domain Spec Type whose public `id` owns that child.
+Studio then recovers the Source range from the typed observed Record, without ordinal matching.
+
+A project companion contributes package-local Track Companion ids through
+`createStudioTrackCompanionHostFacet()`. The Host qualifies them with the selected
+physical package identity, so executable package code cannot impersonate an
+official Companion. The Source closure selects project packages; Studio does not
+scan `node_modules` for plugins or use Runtime Profiles to select Companions.
+
+The same host facet can contribute Film and Script boundary companions. A Film companion declares
+the accepted `timeSources` (author attribute and Type) and its terminal Tracks. Film accepts either
+a SemanticTrack or a declared ProgramSpace. Track Companion context includes `semantic` when the
+time source supplies a semantic timeline; pure animation leaves it undefined. A Script companion owns
+raw source observation and marker adjustment. Studio core only matches and invokes these declarations;
+it does not import either domain package.
+
+For a domain item whose Spec is consumed beside a Window or Instant, call
+`temporalLineageFor(context, item.id, "window")` using the actual projection input name. Attach the
+returned lineage to that entity; the input may instead be `activation`, `outer` or another declared
+port. Studio derives common timeline gestures from endpoint authority. No matching lineage means
+no inferred semantic edit; several matching edges require resolving the ambiguity in the component
+projection. Visible frame coincidence is not a source relationship.
+
+## Expose authored parameters deliberately
+
+Inspector editing deliberately has two declarations:
+
+- `bindings` names exact author endpoints, including explicit reference paths
+  into authored elements or SVS Recipes. A binding is not visible by itself;
+- `inspector` selects writable bindings and gives them a `where`, `how` or
+  `when` domain, an optional package-owned page, a section and one of Studio's
+  finite controls (`text`, `number`, `boolean`, `select`, `color`, `list` or
+  `record`). A domain Recipe may declare a shared canonical-value schema; the
+  companion chooses its presentation while Studio derives and validates the
+  finite structured control without learning domain syntax.
+
+This keeps source traversal, timeline inverses and editor presentation from
+silently becoming one policy. Studio resolves the declarations against the
+current Source closure, publishes only real writable fields, renders all DOM
+and CSS itself, and commits changes through `parameter.adjust`.
+
+Structured controls keep a local draft and commit one complete canonical value.
+Their codec is the author language (`@hypit/svs` for Recipe values), not a
+Companion callback. Companions cannot inject DOM, CSS, parsing code or filesystem
+mutations. Official companions also use explicit field tables: an undeclared
+new domain property fails Companion loading instead of inheriting UI from its name.
+
+`referenced` follows declared authored-element references; `recipe` names an explicit path through
+authored references to one SVS Recipe and its admitted properties. These paths are independent of
+the `inspector` field table. Keep shared values shared: editing a Recipe affects its consumers, while
+an entity-specific `parameterReferences` override must identify the actual authored value it uses.
+
+Verify the integration in an ordinary Run: the intended Module/Surface matches, the expected entity
+is selected, its field reaches the correct Source or Recipe, and changing it recomputes the preview.
+For semantic handles, verify the exact marker and its other consumers too. Read-only derived timing
+is preferable to an invented inverse. The Companion explains the component; its Producers remain
+responsible for identical video behavior in Studio, seeking and encoded rendering.

package/packages/studio-adapter/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@hypit/studio-adapter",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@hypit/host": "workspace:*",
+    "@hypit/protocol": "workspace:*"
+  }
+}