@hypit/hypit 0.0.1 → 0.1.0

package/packages/hyperframes/src/fragment.ts

@@ -0,0 +1,32 @@
+import { programSpaceTypes } from "@hypit/program-space";
+import { compositionTypes } from "@hypit/composition";
+import type { Composition } from "@hypit/composition";
+import { sealGraphFragment } from "@hypit/elaborator";
+
+import { hyperframesProducers, hyperframesTypes } from "./manifest.js";
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
+
+/**
+ * Compile one already assembled Composition into a Hyperframes document.
+ * Film is intentionally absent: any package capable of producing Composition
+ * can use this ordinary downstream Fragment.
+ */
+export const hyperframesDocumentFragment = sealGraphFragment({
+  inputs: [
+    { name: "composition", type: compositionTypes.composition },
+    { name: "space", type: programSpaceTypes.programSpace },
+  ],
+  operations: [{
+    id: "compile-document",
+    producer: hyperframesProducers.compile,
+    inputs: { composition: input("composition"), space: input("space") },
+    result: { kind: "output", name: "document" },
+  }],
+  exports: [{
+    name: "document",
+    type: hyperframesTypes.document,
+    root: operation("compile-document"),
+  }],
+});

package/packages/hyperframes/src/index.ts

@@ -0,0 +1,13 @@
+export { hyperframesDocumentFragment } from "./fragment.js";
+export { hyperframesComponent } from "./component.js";
+export { assertHyperframesDocument, assertHyperframesFrameIndex, assertHyperframesFrameSpan, compileHyperframesDocument, hyperframesResourceUri, hyperframesTime, materializeHyperframesHtml } from "./document.js";
+export {
+  hyperframesDocumentSchema,
+  hyperframesManifest,
+  hyperframesModuleRef,
+  hyperframesProducers,
+  hyperframesTypes,
+} from "./manifest.js";
+export type * from "./types.js";
+export { browserProgram, BROWSER_PROGRAM_FORMAT } from "./browser-program.js";
+export type { BrowserProgram } from "./browser-program.js";

package/packages/hyperframes/src/manifest.ts

@@ -0,0 +1,67 @@
+import { programSpaceDependency, programSpaceTypes } from "@hypit/program-space";
+import { compositionDependency, compositionTypes } from "@hypit/composition";
+import { compositableSurfaceSchema, mediaDependency } from "@hypit/media";
+import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
+import { VISUAL_IR_V1 } from "@hypit/visual-ir";
+
+export const hyperframesModuleRef = { name: "@hypit/hyperframes", version: "1" } as const;
+export const hyperframesTypes = {
+  document: { module: hyperframesModuleRef, name: "HyperframesDocument" },
+} satisfies Record<string, TypeRef>;
+export const hyperframesProducers = {
+  compile: { module: hyperframesModuleRef, name: "compile-composition" },
+} satisfies Record<string, ProducerRef>;
+
+const resource = { kind: "string", minLength: 5, maxLength: 256 } as const;
+const positiveInteger = { kind: "number", integer: true, minimum: 1 } as const;
+const nonNegativeInteger = { kind: "number", integer: true, minimum: 0 } as const;
+export const hyperframesDocumentSchema: ValueSchema = {
+  kind: "object",
+  fields: {
+    visualIr: { schema: { kind: "literal", value: VISUAL_IR_V1 } },
+    frameRate: { schema: {
+      kind: "object",
+      fields: {
+        numerator: { schema: positiveInteger },
+        denominator: { schema: positiveInteger },
+      },
+    } },
+    frameCount: { schema: positiveInteger },
+    canvas: { schema: {
+      kind: "object",
+      fields: {
+        width: { schema: positiveInteger },
+        height: { schema: positiveInteger },
+      },
+    } },
+    artifacts: { schema: { kind: "array", items: {
+      kind: "object",
+      fields: {
+        kind: { schema: { kind: "literal", value: "blob" } },
+        resource: { schema: resource },
+        size: { schema: nonNegativeInteger },
+        mediaType: { schema: { kind: "string", minLength: 1 } },
+      },
+    } } },
+    surfaces: { schema: { kind: "array", items: compositableSurfaceSchema } },
+    html: { schema: { kind: "string", minLength: 1 } },
+  },
+};
+
+export const hyperframesManifest: ModuleManifest = {
+  format: "hypit.module@1",
+  name: hyperframesModuleRef.name,
+  version: hyperframesModuleRef.version,
+  dependencies: [compositionDependency, mediaDependency, programSpaceDependency],
+  types: [{ name: hyperframesTypes.document.name }],
+  capabilities: [],
+  producers: [{
+    name: hyperframesProducers.compile.name,
+    inputs: [
+      { name: "composition", type: compositionTypes.composition },
+      { name: "space", type: programSpaceTypes.programSpace },
+    ],
+    outputs: [{ name: "document", type: hyperframesTypes.document }],
+    needs: [],
+  }],
+};

package/packages/hyperframes/src/project.ts

@@ -0,0 +1,118 @@
+import { mkdir, open, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import type { CompositableSurfaceRef } from "@hypit/media";
+import type { BlobRef } from "@hypit/protocol";
+
+import { assertHyperframesDocument, materializeHyperframesHtml } from "./document.js";
+import type { HyperframesDocument } from "./types.js";
+
+/** Reads one execution resource. Whose store it comes from is the caller's business. */
+export type HyperframesArtifactReader = (
+  artifact: BlobRef,
+  signal?: AbortSignal,
+) => Promise<Uint8Array | AsyncIterable<Uint8Array>>;
+export type HyperframesSurfaceValidator = (
+  surface: CompositableSurfaceRef,
+  bytes: Uint8Array,
+  signal?: AbortSignal,
+) => Promise<void>;
+
+const EXTENSIONS: Readonly<Record<string, string>> = {
+  "image/png": ".png",
+  "image/jpeg": ".jpg",
+  "image/webp": ".webp",
+  "video/mp4": ".mp4",
+  "video/webm": ".webm",
+  "font/woff2": ".woff2",
+  "font/woff": ".woff",
+  "font/ttf": ".ttf",
+  "font/otf": ".otf",
+};
+
+function extension(mediaType: string): string {
+  const found = EXTENSIONS[mediaType];
+  if (found === undefined) throw new Error(`HyperFrames does not support Artifact media type ${mediaType}`);
+  return found;
+}
+
+/**
+ * Lay one document out as a directory HyperFrames can render.
+ *
+ * The same layout serves a local render and a distributed one: the local
+ * Provider serves it to the capture engine, and the AWS Provider tars it into a site. If
+ * the two laid it out differently, one Need would name two different projects.
+ * Resource names are local to this staged project and carry no content claim.
+ */
+export async function stageHyperframesProject(options: {
+  readonly document: HyperframesDocument;
+  readonly directory: string;
+  readonly read: HyperframesArtifactReader;
+  readonly validateSurface?: HyperframesSurfaceValidator;
+  readonly signal?: AbortSignal;
+}): Promise<void> {
+  const { document, directory, read } = options;
+  const controller = new AbortController();
+  const signal = options.signal === undefined ? controller.signal : AbortSignal.any([options.signal, controller.signal]);
+  signal.throwIfAborted();
+  assertHyperframesDocument(document);
+  if (document.surfaces.length > 0 && options.validateSurface === undefined) {
+    throw new Error("HyperFrames Runtime has no Surface-byte validator");
+  }
+  const artifactDirectory = join(directory, "artifacts");
+  await mkdir(artifactDirectory, { recursive: true });
+  const paths = new Map<string, string>();
+  const surfaces = new Map(document.surfaces.map((surface) => [surface.artifact.resource, surface]));
+  await Promise.allSettled(document.artifacts.map(async (artifact) => {
+    try {
+      signal.throwIfAborted();
+      const name = `${artifact.resource}${extension(artifact.mediaType)}`;
+      const opened = await read(artifact, signal);
+      signal.throwIfAborted();
+      const chunks = opened instanceof Uint8Array
+        ? (async function* () { yield opened; })()
+        : opened;
+      const surface = surfaces.get(artifact.resource);
+      const retained: Uint8Array[] = [];
+      let size = 0;
+      const target = await open(join(artifactDirectory, name), "w");
+      try {
+        for await (const chunk of chunks) {
+          signal.throwIfAborted();
+          await target.write(chunk);
+          size += chunk.byteLength;
+          if (surface !== undefined) retained.push(Uint8Array.from(chunk));
+        }
+      } finally {
+        await target.close();
+      }
+      if (size !== artifact.size) {
+        throw new Error(`HyperFrames Artifact ${artifact.resource} size differs`);
+      }
+      const bytes = surface === undefined ? undefined : (() => {
+        const value = new Uint8Array(size);
+        let offset = 0;
+        for (const chunk of retained) {
+          value.set(chunk, offset);
+          offset += chunk.byteLength;
+        }
+        return value;
+      })();
+      if (surface !== undefined) {
+        await options.validateSurface!(structuredClone(surface), bytes!.slice(), signal);
+      }
+      paths.set(artifact.resource, `./artifacts/${name}`);
+    } catch (error) {
+      controller.abort(error);
+      throw error;
+    }
+  }));
+  // All writes have settled before the caller can remove the staged directory.
+  signal.throwIfAborted();
+  const html = materializeHyperframesHtml(document, (artifact) => {
+    const path = paths.get(artifact.resource);
+    if (path === undefined) throw new Error(`HyperFrames Artifact ${artifact.resource} was not staged`);
+    return path;
+  });
+  await writeFile(join(directory, "index.html"), html, { encoding: "utf8", signal });
+}