@hypit/hypit 0.0.1 → 0.1.1

package/packages/studio/src/domain.ts

@@ -0,0 +1,139 @@
+import { loadDiscoveredSourcePackages } from "@hypit/cli";
+import { registerProducerFacets, registerTypeValidatorFacets } from "@hypit/component-kit";
+import { createResolvedClosure } from "@hypit/core";
+import { ProducerRegistry } from "@hypit/driver-node";
+import {
+  AuthorFrontendRegistry,
+  installAuthorFrontendHostFacets,
+} from "@hypit/elaborator";
+import {
+  createMarkupAuthorFrontend,
+  installMarkupSurfaceHostFacets,
+  MarkupSurfaceRegistry,
+} from "@hypit/markup";
+import type { MarkupSurfaceRegistryLike } from "@hypit/markup";
+import type { LoadedPackage, NodePackageContribution } from "@hypit/package-loader-node";
+import { ModulePackageRegistry, NodeCompiler } from "@hypit/compiler-node";
+import type { ModuleRef, ResolvedModuleClosure } from "@hypit/protocol";
+import { TypeValidatorRegistry } from "@hypit/validation";
+import { createVideoCompiler, createVideoWorkspace, videoCliDistribution } from "@hypit/video-cli";
+
+export type StudioDomain = {
+  readonly packages: readonly LoadedPackage[];
+  readonly contributions: readonly NodePackageContribution[];
+  readonly compiler: NodeCompiler;
+  readonly createCompiler: (surfaces?: MarkupSurfaceRegistryLike) => NodeCompiler;
+  readonly closure: ResolvedModuleClosure;
+  readonly surfaces: MarkupSurfaceRegistry;
+  readonly producers: ProducerRegistry;
+  readonly validators: TypeValidatorRegistry;
+  readonly resolveModule: (specifier: string) => ModuleRef | undefined;
+  readonly frontends: (surfaces?: MarkupSurfaceRegistryLike) => AuthorFrontendRegistry;
+};
+
+/**
+ * Assemble Studio from the same recursive package selection as the official CLI.
+ * The application owns this video-domain view; packages never register Studio metadata.
+ */
+export async function loadStudioDomain(input: {
+  readonly run: string;
+  readonly workspaceRoot: string;
+  readonly packageRoot: string;
+}): Promise<StudioDomain> {
+  const packages = await loadDiscoveredSourcePackages(videoCliDistribution, {
+    source: input.run,
+    workspaceRoot: input.workspaceRoot,
+    packageRoot: input.packageRoot,
+    ...(videoCliDistribution.packageRoot === undefined
+      ? {}
+      : { distributionPackageRoot: videoCliDistribution.packageRoot }),
+  });
+  const contributions = packages.map((item) => item.contribution);
+  const manifests = contributions.flatMap((item) =>
+    (item.modules ?? []).map((module) => module.manifest));
+  const closure = createResolvedClosure(manifests);
+
+  const modules = new Map<string, ModuleRef>();
+  const moduleRegistry = new ModulePackageRegistry();
+  for (const contribution of contributions) {
+    for (const module of contribution.modules ?? []) {
+      moduleRegistry.register(module);
+      const ref = { name: module.manifest.name, version: module.manifest.version };
+      for (const specifier of [
+        module.manifest.name,
+        `${module.manifest.name}@${module.manifest.version}`,
+        ...(module.specifiers ?? []),
+      ]) modules.set(specifier, ref);
+    }
+  }
+  const resolveModule = (specifier: string): ModuleRef | undefined => modules.get(specifier);
+  const facets = contributions.flatMap((item) => item.hostFacets ?? []);
+  const surfaces = new MarkupSurfaceRegistry();
+  installMarkupSurfaceHostFacets(facets, surfaces);
+  const domainFrontends = (registry: MarkupSurfaceRegistryLike): AuthorFrontendRegistry => {
+    const frontends = new AuthorFrontendRegistry();
+    frontends.register(createMarkupAuthorFrontend({
+      registry,
+      resolveModule(request) {
+        const found = resolveModule(request.from);
+        if (found === undefined) throw new Error(`No selected Source package satisfies ${request.from}`);
+        return found;
+      },
+    }));
+    installAuthorFrontendHostFacets(facets, frontends);
+    return frontends;
+  };
+
+  const producers = new ProducerRegistry();
+  const validators = new TypeValidatorRegistry();
+  for (const contribution of contributions) {
+    for (const component of contribution.components ?? []) {
+      registerProducerFacets(producers, component.producers ?? []);
+      registerTypeValidatorFacets(validators, component.validators ?? []);
+    }
+  }
+
+  return {
+    packages,
+    contributions,
+    compiler: createVideoCompiler({
+      workspaceRoot: input.workspaceRoot,
+      packageRoot: input.packageRoot,
+      ...(videoCliDistribution.packageRoot === undefined
+        ? {}
+        : { distributionPackageRoot: videoCliDistribution.packageRoot }),
+      packageContributions: contributions,
+    }),
+    createCompiler(registry) {
+      if (registry === undefined) {
+        return createVideoCompiler({
+          workspaceRoot: input.workspaceRoot,
+          packageRoot: input.packageRoot,
+          ...(videoCliDistribution.packageRoot === undefined
+            ? {}
+            : { distributionPackageRoot: videoCliDistribution.packageRoot }),
+          packageContributions: contributions,
+        });
+      }
+      const frontends = domainFrontends(registry);
+      return new NodeCompiler({
+        modules: moduleRegistry,
+        frontends,
+        validators,
+        workspace: createVideoWorkspace({
+          workspaceRoot: input.workspaceRoot,
+          packageRoot: input.packageRoot,
+          ...(videoCliDistribution.packageRoot === undefined
+            ? {}
+            : { distributionPackageRoot: videoCliDistribution.packageRoot }),
+        }),
+      });
+    },
+    closure,
+    surfaces,
+    producers,
+    validators,
+    resolveModule,
+    frontends(registry = surfaces) { return domainFrontends(registry); },
+  };
+}

package/packages/studio/src/execute.ts

@@ -0,0 +1,57 @@
+import { MemoryResourceStore, NodeDriver } from "@hypit/driver-node";
+import type { ResourceStore } from "@hypit/runtime";
+import type { BuildState } from "@hypit/protocol";
+import type { RuntimeHostTransientExecution } from "@hypit/runtime-host-node";
+
+import type { StudioDomain } from "./domain.js";
+
+export type Executed = {
+  readonly state: BuildState;
+  readonly status: string;
+  readonly unserved: readonly { readonly capability: string; readonly count: number }[];
+  readonly errors: readonly string[];
+};
+
+/**
+ * Run the display closure: deterministic Producers, plus Needs the Runtime explicitly permits in
+ * a disposable authoring execution. The Runtime owns Endpoint selection and invocation; Studio
+ * never filters Providers or sees their handlers.
+ */
+export async function executeStudioProjection(
+  domain: StudioDomain,
+  planned: BuildState,
+  resources: ResourceStore,
+  execution?: RuntimeHostTransientExecution,
+): Promise<Executed> {
+  const result = execution === undefined
+    ? await new NodeDriver({
+        producers: domain.producers,
+        validators: domain.validators,
+        resources,
+      }).run(planned)
+    : await execution.evaluate({
+        state: planned,
+        producers: domain.producers,
+        validators: domain.validators,
+        resources,
+      });
+  const counts = new Map<string, number>();
+  for (const item of result.blocked) {
+    const command = result.state.outstanding.find((candidate) => candidate.id === item.command);
+    const capability = command?.kind === "fulfill-need" ? command.need.capability : undefined;
+    const name = capability === undefined
+      ? item.subject
+      : `${capability.module.name}@${capability.module.version}#${capability.name}`;
+    counts.set(name, (counts.get(name) ?? 0) + 1);
+  }
+  return {
+    state: result.state,
+    status: result.status,
+    unserved: [...counts].map(([capability, count]) => ({ capability, count })),
+    errors: result.outcomes
+      .filter((entry) => entry.status === "error")
+      .map((entry) => entry.message ?? "a Producer failed without saying why"),
+  };
+}
+
+export { MemoryResourceStore };

package/packages/studio/src/fallback-companions.ts

@@ -0,0 +1,98 @@
+import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioEntityDraft } from "@hypit/studio-adapter";
+import { artifactPreview, previewLayer, temporalLineageFor, temporalSemanticSource } from "@hypit/studio-adapter";
+import { compositionTypes } from "@hypit/composition";
+import { semanticTrackTypes } from "@hypit/semantic-track";
+
+type TerminalVisualTrack = {
+  readonly presents?: readonly {
+    readonly id: string;
+    readonly subjectId?: string;
+    readonly elements?: readonly {
+      readonly kind?: string;
+      readonly artifact?: { readonly resource?: string };
+    }[];
+  }[];
+};
+
+type TerminalAudioTrack = {
+  readonly clips?: readonly {
+    readonly id: string;
+    readonly subjectId?: string;
+    readonly artifact?: { readonly resource?: string };
+  }[];
+};
+
+function withTemporalLineage(
+  context: StudioTrackCompanionContext,
+  entity: StudioEntityDraft,
+): StudioEntityDraft {
+  const temporal = temporalLineageFor(context, entity.authoredId);
+  if (temporal === undefined) return entity;
+  const semanticSource = temporalSemanticSource(temporal);
+  return {
+    ...entity,
+    ...(semanticSource?.id === undefined
+      ? {}
+      : { markerId: semanticSource.id }),
+    temporal,
+  };
+}
+
+function projectTerminalVisual(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
+  const presents = new Map(((context.track.value as TerminalVisualTrack).presents ?? [])
+    .map((present) => [present.id, present] as const));
+  return context.generic().map((entity) => {
+    const present = entity.presentId === undefined ? undefined : presents.get(entity.presentId);
+    const material = present?.elements?.find((element) =>
+      (element.kind === "image" || element.kind === "video") && element.artifact?.resource !== undefined);
+    const resource = material?.artifact?.resource;
+    return withTemporalLineage(context, {
+      ...entity,
+      ...(present?.subjectId === undefined ? {} : { authoredId: present.subjectId }),
+      display: {
+        title: present?.subjectId ?? entity.display.title,
+        layers: resource === undefined ? [] : [previewLayer(artifactPreview(material?.kind === "image" ? "image" : "video", resource), material?.kind === "image" ? "repeat-x" : "storyboard")],
+      },
+      presentation: { entity: "media-item", chrome: "standard" },
+    });
+  });
+}
+
+function projectTerminalAudio(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
+  const clips = new Map(((context.track.value as TerminalAudioTrack).clips ?? [])
+    .map((clip) => [clip.id, clip] as const));
+  return context.generic().map((entity, index) => {
+    const clip = clips.get(context.spans[index]?.id ?? "");
+    const resource = clip?.artifact?.resource;
+    return withTemporalLineage(context, {
+      ...entity,
+      ...(clip?.subjectId === undefined ? {} : { authoredId: clip.subjectId }),
+      display: {
+        title: clip?.subjectId ?? entity.display.title,
+        layers: resource === undefined ? [] : [previewLayer(artifactPreview("audio", resource), "waveform")],
+      },
+      presentation: { entity: "audio-clip", chrome: "standard" },
+    });
+  });
+}
+
+/** Cross-domain terminal protocols understood even when no Companion is installed. */
+export const fallbackStudioTrackCompanions: readonly StudioTrackCompanion[] = [
+  {
+    id: "@hypit/studio#semantic-track", role: "semantic-track", output: { type: semanticTrackTypes.track },
+    family: "semantic", tone: "teal", label: "Semantic", icon: "brand",
+    lane: { heightPx: 45 },
+  },
+  {
+    id: "@hypit/studio#audio-track", role: "track", output: { type: compositionTypes.audioTrack },
+    family: "audio", tone: "green", icon: "waveform",
+    project: projectTerminalAudio,
+    lane: { heightPx: 48 },
+  },
+  {
+    id: "@hypit/studio#visual-track", role: "track", output: { type: compositionTypes.visualTrack },
+    family: "media", tone: "blue", icon: "video",
+    project: projectTerminalVisual,
+    lane: { heightPx: 76 },
+  },
+];

package/packages/studio/src/observe.ts

@@ -0,0 +1,202 @@
+/**
+ * Watch a compile without changing it.
+ *
+ * A preview has to point at the words that produced a picture, and the compiler
+ * does not carry that: an element's source range reaches its Surface and is
+ * dropped when the Records it returns are sealed. Rather than decode the Source
+ * a second time, both decorators here delegate to the real implementation and
+ * keep what passes through.
+ */
+import type {
+  MarkupSurfaceRegistryLike, RegisteredSurface, StructuredElement, StructuredSurfaceInput, SurfaceDecodeOutput,
+} from "@hypit/markup";
+import type { ModuleRef } from "@hypit/protocol";
+import type { StudioObservedValue, StudioPlacement, StudioScriptSourceMap } from "@hypit/studio-adapter";
+
+import type { Range } from "./shared.js";
+import type { StudioCompanionRegistry } from "./studio-registry.js";
+
+export type ObservedValue = StudioObservedValue;
+
+/** One authored element, where it was written, and what it produced. */
+export type Placement = StudioPlacement;
+
+export type Observations = {
+  readonly placements: readonly Placement[];
+  /** Whatever the Surfaces mapped back onto the Source, such as a Script's markers. */
+  readonly sourceMaps: readonly StudioScriptSourceMap[];
+};
+
+export type Observer = {
+  readonly surfaces: MarkupSurfaceRegistryLike;
+  readonly frontend: <T extends { readonly id: string }>(frontend: T) => T;
+  readonly observations: () => Observations;
+};
+
+/**
+ * Wrap the Surface registry and the markup Frontend a compile will use.
+ *
+ * Neither wrapper decides anything: the Surface still decodes the element and
+ * the Frontend still decodes the Source. Only the positions they discard are
+ * kept, which is why this stays correct as packages change.
+ */
+/** Attributes the author wrote as plain text, by name. */
+function written(element: StructuredElement): Record<string, string> {
+  const held: Record<string, string> = {};
+  for (const [name, value] of Object.entries(element.attributes)) {
+    if (typeof value === "string") held[name] = value;
+  }
+  return held;
+}
+
+/** Every whole-value reference an element points at, in written order. */
+function referenced(element: StructuredElement): string[] {
+  return Object.values(referenceAttributes(element));
+}
+
+/** Whole-value references retained by attribute name for reversible interpretation. */
+function referenceAttributes(element: StructuredElement): Record<string, string> {
+  const held: Record<string, string> = {};
+  for (const [name, value] of Object.entries(element.attributes)) {
+    if (typeof value === "object" && value !== null
+      && (value as { kind?: string }).kind === "reference") {
+      held[name] = (value as { path: string }).path;
+    }
+  }
+  return held;
+}
+
+export function createObserver(
+  surfaces: MarkupSurfaceRegistryLike,
+  registry: StudioCompanionRegistry,
+): Observer {
+  const placements: Placement[] = [];
+  const sourceMaps: StudioScriptSourceMap[] = [];
+
+  // A Frontend may reach a Surface by name or by walking a module's whole list,
+  // so both ways in are wrapped: an unwatched Surface decodes silently and the
+  // preview loses the tag that placed the picture.
+  const watch = (found: RegisteredSurface | undefined, module: ModuleRef): RegisteredSurface | undefined => {
+      // A raw Surface parses its own body and reports its own positions, so
+      // there is nothing here to recover.
+      if (found === undefined) return found;
+      if (found.mode !== "structured") {
+        const raw = found.handler as (input: RawInput) => unknown;
+        return {
+          ...found,
+          async handler(input: RawInput) {
+            const output = await raw(input);
+            const nextOffset = typeof output === "object" && output !== null
+              && Number.isInteger((output as { readonly nextOffset?: unknown }).nextOffset)
+              ? (output as { readonly nextOffset: number }).nextOffset
+              : undefined;
+            const sourceMap = registry.observeScript(module, found.surface, {
+              ...input,
+              ...(nextOffset === undefined ? {} : { nextOffset }),
+            });
+            if (sourceMap !== undefined) sourceMaps.push(sourceMap);
+            return output;
+          },
+        } as RegisteredSurface;
+      }
+      const handler = found.handler as (input: StructuredSurfaceInput) => unknown;
+      return {
+        ...found,
+        async handler(input: StructuredSurfaceInput) {
+          const output = await handler(input) as SurfaceDecodeOutput;
+          const id = input.element.attributes.id;
+          const observed = output.records.flatMap((record): ObservedValue[] => record.value.kind === "inline" ? [{
+            id: record.id,
+            type: { module: { ...record.type.module }, name: record.type.name },
+            value: structuredClone(record.value.value),
+          }] : []);
+          const valuesFor = (range: { readonly start: number; readonly end: number }): readonly ObservedValue[] =>
+            observed.filter((value) => output.records.some((record) =>
+              record.id === value.id && record.range.start === range.start && record.range.end === range.end));
+          const referenceTypes = (element: StructuredElement): Readonly<Record<string, string>> => Object.fromEntries(
+            Object.entries(referenceAttributes(element)).flatMap(([name, path]) => {
+              const resolved = input.resolveReference(path);
+              return resolved === undefined ? [] : [[name, resolved.type.name]];
+            }),
+          );
+          placements.push({
+            tag: input.element.name,
+            module: { ...module },
+            sourcePath: input.sourceName,
+            attributeValueRanges: input.element.attributeValueRanges ?? {},
+            surface: found.surface,
+            ...(typeof id === "string" ? { id } : {}),
+            range: { start: input.element.range.start, end: input.element.range.end },
+            records: output.records.map((record) => record.id),
+            values: valuesFor(input.element.range),
+            outputs: output.components.flatMap((component) => Object.values(component.outputs)),
+            outputPorts: output.components.flatMap((component) =>
+              Object.entries(component.outputs).map(([name, ref]) => ({ name, ref }))),
+            attributes: written(input.element),
+            referenceAttributes: referenceAttributes(input.element),
+            referenceTypes: referenceTypes(input.element),
+            references: [
+              ...referenced(input.element),
+              ...input.element.children
+                .filter((child): child is StructuredElement => child.kind === "element")
+                .flatMap(referenced),
+            ],
+            children: input.element.children
+              .filter((child): child is StructuredElement => child.kind === "element")
+              .map((child) => {
+                const childId = child.attributes.id;
+                return {
+                  tag: child.name,
+                  sourcePath: input.sourceName,
+                  attributeValueRanges: child.attributeValueRanges ?? {},
+                  ...(typeof childId === "string" ? { id: childId } : {}),
+                  range: { start: child.range.start, end: child.range.end },
+                  attributes: written(child),
+                  references: referenced(child),
+                  referenceAttributes: referenceAttributes(child),
+                  referenceTypes: referenceTypes(child),
+                  values: valuesFor(child.range),
+                };
+              }),
+          });
+          return output;
+        },
+      } as RegisteredSurface;
+  };
+
+  const watchedSurfaces: MarkupSurfaceRegistryLike = {
+    surfaces(module) {
+      return surfaces.surfaces(module).map((found) => watch(found, module)!) as readonly RegisteredSurface[];
+    },
+    resolve(module, surface) { return watch(surfaces.resolve(module, surface), module); },
+  };
+
+  return {
+    surfaces: watchedSurfaces,
+    frontend<T extends { readonly id: string }>(frontend: T): T { return frontend; },
+    observations: () => ({ placements, sourceMaps }),
+  };
+}
+
+/** The Frontend registry a compile is handed, with every Frontend observed. */
+export function observeFrontends<R extends { resolve(id: string): unknown }>(
+  registry: R,
+  observer: Observer,
+): R {
+  return {
+    resolve(id: string) {
+      const frontend = registry.resolve(id) as { readonly id: string } | undefined;
+      return frontend === undefined ? undefined : observer.frontend(frontend);
+    },
+  } as unknown as R;
+}
+
+/** What a raw Surface is handed: the whole Source and where its body begins. */
+type RawInput = {
+  readonly sourceName: string;
+  readonly source: string;
+  readonly tag: string;
+  readonly openingStart: number;
+  readonly contentStart: number;
+  readonly attributes: Readonly<Record<string, unknown>>;
+};

package/packages/studio/src/parameter-values.ts

@@ -0,0 +1,81 @@
+import type { CanonicalValue, ValueSchema } from "@hypit/protocol";
+import { formatSvsValue } from "@hypit/svs";
+
+function fail(path: string, expectation: string): never {
+  throw new Error(`${path} ${expectation}.`);
+}
+
+export function validateParameterValue(value: CanonicalValue, schema: ValueSchema, path: string): void {
+  if (schema.kind === "null") {
+    if (value !== null) fail(path, "expects null");
+    return;
+  }
+  if (schema.kind === "boolean") {
+    if (typeof value !== "boolean") fail(path, "expects true or false");
+    return;
+  }
+  if (schema.kind === "number") {
+    if (typeof value !== "number" || !Number.isFinite(value)) fail(path, "expects a finite number");
+    if (schema.integer === true && !Number.isInteger(value)) fail(path, "expects a whole number");
+    if (schema.minimum !== undefined && value < schema.minimum) fail(path, `must be at least ${schema.minimum}`);
+    if (schema.maximum !== undefined && value > schema.maximum) fail(path, `must be at most ${schema.maximum}`);
+    return;
+  }
+  if (schema.kind === "string") {
+    if (typeof value !== "string") fail(path, "expects text");
+    if (schema.enum !== undefined && !schema.enum.includes(value)) fail(path, `does not accept ${value}`);
+    if (schema.minLength !== undefined && value.length < schema.minLength) fail(path, "is too short");
+    if (schema.maxLength !== undefined && value.length > schema.maxLength) fail(path, "is too long");
+    if (schema.format === "color" && !/^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/iu.test(value)) {
+      fail(path, "expects #RRGGBB or #RRGGBBAA");
+    }
+    return;
+  }
+  if (schema.kind === "literal") {
+    if (JSON.stringify(value) !== JSON.stringify(schema.value)) fail(path, "does not match its required literal");
+    return;
+  }
+  if (schema.kind === "array") {
+    if (!Array.isArray(value)) fail(path, "expects a list");
+    if (schema.minItems !== undefined && value.length < schema.minItems) fail(path, `requires at least ${schema.minItems} items`);
+    if (schema.maxItems !== undefined && value.length > schema.maxItems) fail(path, `accepts at most ${schema.maxItems} items`);
+    value.forEach((item, index) => validateParameterValue(item, schema.items, `${path}[${index}]`));
+    return;
+  }
+  if (schema.kind === "object") {
+    if (value === null || Array.isArray(value) || typeof value !== "object") fail(path, "expects a record");
+    const record = value as Readonly<Record<string, CanonicalValue>>;
+    for (const [name, field] of Object.entries(schema.fields)) {
+      const held = record[name];
+      if (held === undefined) {
+        if (field.optional !== true) fail(`${path}.${name}`, "is required");
+      } else {
+        validateParameterValue(held, field.schema, `${path}.${name}`);
+      }
+    }
+    if (schema.allowUnknown !== true) {
+      const unknown = Object.keys(record).find((name) => schema.fields[name] === undefined);
+      if (unknown !== undefined) fail(`${path}.${unknown}`, "is not declared");
+    }
+    return;
+  }
+  if (schema.kind === "oneOf") {
+    const accepted = schema.variants.some((variant) => {
+      try {
+        validateParameterValue(value, variant, path);
+        return true;
+      } catch {
+        return false;
+      }
+    });
+    if (!accepted) fail(path, "does not match an accepted value shape");
+    return;
+  }
+  fail(path, "cannot edit blob values");
+}
+
+export function serializeParameterValue(value: CanonicalValue, language: "svml" | "svs" | "svrun"): string {
+  if (language === "svs") return formatSvsValue(value);
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return String(value);
+  throw new Error(`${language.toUpperCase()} parameter bindings currently accept scalar values only.`);
+}