@hypit/hypit 0.0.1 → 0.1.0

package/packages/render-hyperframes/src/activation.ts

@@ -0,0 +1,18 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+import {
+  decodeHyperframesRenderSurface, renderHyperframesComponent, renderHyperframesManifest,
+  renderHyperframesModuleRef,
+  renderHyperframesMarkupSurfaces,
+} from "./index.js";
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{ manifest: renderHyperframesManifest }],
+  components: [renderHyperframesComponent],
+  hostFacets: [createMarkupSurfaceHostFacet({
+    module: renderHyperframesModuleRef,
+    declaration: renderHyperframesMarkupSurfaces.find((item) => item.name === "video")!,
+    handler: decodeHyperframesRenderSurface,
+  })],
+};
+export default hypitPackage;

package/packages/render-hyperframes/src/component.ts

@@ -0,0 +1,37 @@
+import type { MediaFrameRange } from "@hypit/media";
+import { plannedNeedInputs } from "@hypit/component-kit";
+import type { ComponentPackage } from "@hypit/component-kit";
+import type { StoredValue } from "@hypit/protocol";
+
+import { hyperframesVisualRequest } from "./product.js";
+import { renderHyperframesCapabilities, renderHyperframesProducers } from "./manifest.js";
+
+/** Declares the visual Need. It contains no renderer, queue, credentials or deployment choice. */
+export const renderHyperframesComponent = {
+  producers: [renderHyperframesProducers.requestVisual, renderHyperframesProducers.requestVisualRange].map((producer) => ({
+    producer,
+    handler: ({ inputs }) => ({
+      outputs: {},
+      needs: {
+        visual: hyperframesVisualRequest(inline(inputs.document!.value, "HyperframesDocument") as never,
+          inputs.range === undefined ? {} : { range: inline(inputs.range.value, "MediaFrameRange") as MediaFrameRange }),
+      },
+    }),
+  })),
+  plannedNeeds: [renderHyperframesProducers.requestVisual, renderHyperframesProducers.requestVisualRange].map((producer) => ({
+    producer,
+    port: "visual",
+    capability: renderHyperframesCapabilities.renderVisual,
+    plan({ state, step }) {
+      return { constraints: {}, pendingInputs: plannedNeedInputs(state, step) };
+    },
+    present(specification) {
+      return { fields: {}, references: {} };
+    },
+  })),
+} satisfies ComponentPackage;
+
+function inline(value: StoredValue, subject: string): unknown {
+  if (value.kind !== "inline") throw new Error(`${subject} must be inline`);
+  return value.value;
+}

package/packages/render-hyperframes/src/fragment.ts

@@ -0,0 +1,73 @@
+import { mediaTypes } from "@hypit/media";
+import { artifactTypes } from "@hypit/artifact";
+import { programSpaceTypes } from "@hypit/program-space";
+import { compositionTypes } from "@hypit/composition";
+import { sealGraphFragment } from "@hypit/elaborator";
+import { hyperframesProducers } from "@hypit/hyperframes";
+import { mediaPipelineProducers } from "@hypit/media-pipeline";
+
+import {
+  renderHyperframesProducers,
+} from "./manifest.js";
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
+
+export function createRenderHyperframesFragment(selectedRange = false) {
+  return sealGraphFragment({
+    inputs: [
+      { name: "composition", type: compositionTypes.composition },
+      { name: "space", type: programSpaceTypes.programSpace },
+      ...(selectedRange ? [{ name: "range", type: mediaTypes.frameRange }] : []),
+    ],
+    operations: [
+      {
+        id: "compile-document",
+        producer: hyperframesProducers.compile,
+        inputs: { composition: input("composition"), space: input("space") },
+        result: { kind: "output", name: "document" },
+      },
+      {
+        id: "request-visual-render",
+        producer: selectedRange ? renderHyperframesProducers.requestVisualRange : renderHyperframesProducers.requestVisual,
+        inputs: { document: operation("compile-document"), ...(selectedRange ? { range: input("range") } : {}) },
+        result: { kind: "need", name: "visual" },
+      },
+      {
+        id: "compile-audio-program",
+        producer: mediaPipelineProducers.planAudio,
+        inputs: { composition: input("composition"), space: input("space") },
+        result: { kind: "output", name: "plan" },
+      },
+      {
+        id: "request-audio-render",
+        producer: selectedRange ? mediaPipelineProducers.renderAudioRange : mediaPipelineProducers.renderAudio,
+        inputs: { plan: operation("compile-audio-program"), ...(selectedRange ? { range: input("range") } : {}) },
+        result: { kind: "need", name: "audio" },
+      },
+      {
+        id: "request-mux",
+        producer: mediaPipelineProducers.mux,
+        inputs: {
+          visual: operation("request-visual-render"),
+          audio: operation("request-audio-render"),
+        },
+        result: { kind: "need", name: "media" },
+      },
+      {
+        id: "project-video",
+        producer: mediaPipelineProducers.projectMuxed,
+        inputs: { media: operation("request-mux") },
+        result: { kind: "output", name: "video" },
+      },
+    ],
+    exports: [{
+      name: "video",
+      type: artifactTypes.blob,
+      root: operation("project-video"),
+    }],
+  });
+
+}
+
+export const renderHyperframesFragment = createRenderHyperframesFragment();

package/packages/render-hyperframes/src/index.ts

@@ -0,0 +1,6 @@
+export { renderHyperframesFragment, createRenderHyperframesFragment } from "./fragment.js";
+export { renderHyperframesComponent } from "./component.js";
+export { renderHyperframesCapabilities, renderHyperframesManifest, renderHyperframesMarkupSurfaces, renderHyperframesModuleRef, renderHyperframesProducers } from "./manifest.js";
+export { hyperframesVisualRequest, verifyHyperframesVisualRequest } from "./product.js";
+export type { HyperframesVisualRequest } from "./product.js";
+export { decodeHyperframesRenderSurface } from "./surface.js";

package/packages/render-hyperframes/src/manifest.ts

@@ -0,0 +1,100 @@
+import { temporalContextAttributeVocabulary } from "@hypit/temporal-markup";
+import { artifactDependency, artifactTypes } from "@hypit/artifact";
+import { mediaDependency, mediaTypes } from "@hypit/media";
+import { compositionDependency, compositionTypes } from "@hypit/composition";
+import { semanticTrackDependency } from "@hypit/semantic-track";
+import {
+  hyperframesManifest,
+  hyperframesModuleRef,
+  hyperframesTypes,
+} from "@hypit/hyperframes";
+import type {
+  CapabilityRef,
+  ModuleManifest,
+  ProducerRef,
+} from "@hypit/protocol";
+import {
+  mediaPipelineModuleRef,
+} from "@hypit/media-pipeline";
+
+export const renderHyperframesModuleRef = { name: "@hypit/render-hyperframes", version: "1" } as const;
+export const renderHyperframesCapabilities = {
+  renderVisual: { module: renderHyperframesModuleRef, name: "render-visual" },
+} satisfies Record<string, CapabilityRef>;
+export const renderHyperframesProducers = {
+  requestVisualRange: { module: renderHyperframesModuleRef, name: "request-visual-range" },
+  requestVisual: { module: renderHyperframesModuleRef, name: "request-visual-render" },
+} satisfies Record<string, ProducerRef>;
+
+export const renderHyperframesMarkupSurfaces = [{
+    name: "video",
+    tag: "Video",
+    mode: "structured",
+    outputs: [mediaTypes.frameRange],
+    vocabulary: {
+      summary:
+        "Renders one Composition on its selected film time axis into a final video, publishing the muxed result as a BlobArtifact.",
+      attributes: [
+        { name: "id", kind: "identifier", required: true,
+          summary: "Names the render component and the final video this element publishes." },
+        { name: "composition", kind: "reference", required: true,
+          accepts: [compositionTypes.composition],
+          summary: "Selects the Composition this element compiles, renders and muxes." },
+        ...temporalContextAttributeVocabulary,
+        { name: "start-frame", kind: "literal", required: false, summary: "First original programme frame to render; requires end-frame-exclusive." },
+        { name: "end-frame-exclusive", kind: "literal", required: false, summary: "First excluded frame; requires start-frame." },
+      ],
+      ports: [
+        { name: "video", type: artifactTypes.blob,
+          summary: "The final muxed video Artifact, addressed as `<id>.video`." },
+      ],
+      example: '<render:Video id="final" composition={main.composition} semantic={speech.semantic}/>',
+      notes: [
+        "Supply id, composition and one time source: semantic or space. Write both frame bounds to select a range. The element is empty.",
+        "The visual render, the audio render and the mux are three separate Needs, each realized by a Provider this package does not choose.",
+        "The published Artifact carries no duration or lineage metadata, so a consumer that needs stream facts requests explicit media inspection.",
+      ],
+    },
+  }] as const;
+
+
+export const renderHyperframesManifest: ModuleManifest = {
+  format: "hypit.module@1",
+  name: renderHyperframesModuleRef.name,
+  version: renderHyperframesModuleRef.version,
+  dependencies: [
+    artifactDependency,
+    mediaDependency,
+    compositionDependency,
+    semanticTrackDependency,
+    { module: hyperframesModuleRef },
+    { module: mediaPipelineModuleRef },
+  ],
+  types: [],
+  capabilities: [{
+    name: renderHyperframesCapabilities.renderVisual.name,
+    returns: mediaTypes.renderedVisual,
+  }],
+  producers: [
+    {
+      name: renderHyperframesProducers.requestVisual.name,
+      inputs: [{ name: "document", type: hyperframesTypes.document }],
+      outputs: [],
+      needs: [{
+        name: "visual",
+        capability: renderHyperframesCapabilities.renderVisual,
+        returns: mediaTypes.renderedVisual,
+      }],
+    },
+    {
+      name: renderHyperframesProducers.requestVisualRange.name,
+      inputs: [{ name: "document", type: hyperframesTypes.document }, { name: "range", type: mediaTypes.frameRange }],
+      outputs: [],
+      needs: [{
+        name: "visual",
+        capability: renderHyperframesCapabilities.renderVisual,
+        returns: mediaTypes.renderedVisual,
+      }],
+    },
+  ],
+};

package/packages/render-hyperframes/src/product.ts

@@ -0,0 +1,29 @@
+import type { CanonicalValue } from "@hypit/protocol";
+import { assertHyperframesDocument } from "@hypit/hyperframes";
+import type { HyperframesDocument } from "@hypit/hyperframes";
+import { verifyMediaFrameRange } from "@hypit/media";
+import type { MediaFrameRange } from "@hypit/media";
+
+export type HyperframesVisualRequest = {
+  readonly document: HyperframesDocument;
+  readonly range?: MediaFrameRange;
+};
+
+export function verifyHyperframesVisualRequest(value: unknown): asserts value is HyperframesVisualRequest {
+  if (value === null || typeof value !== "object" || Array.isArray(value)
+    || Object.keys(value).some((key) => key !== "document" && key !== "range")) {
+    throw new Error("HyperFrames visual request requires document and an optional range");
+  }
+  const request = value as HyperframesVisualRequest;
+  assertHyperframesDocument(request.document);
+  if (request.range !== undefined) verifyMediaFrameRange(request.range, request.document.frameCount);
+}
+
+export function hyperframesVisualRequest(document: HyperframesDocument, options: { readonly range?: MediaFrameRange } = {}): CanonicalValue {
+  assertHyperframesDocument(document);
+  if (options.range !== undefined) verifyMediaFrameRange(options.range, document.frameCount);
+  return {
+    document,
+    ...(options.range === undefined ? {} : { range: options.range }),
+  };
+}

package/packages/render-hyperframes/src/surface.ts

@@ -0,0 +1,65 @@
+import { createTemporalSpace, resolveTemporalContext } from "@hypit/temporal-markup";
+import { compositionTypes } from "@hypit/composition";
+import { mediaTypes, verifyMediaFrameRange } from "@hypit/media";
+import type {
+  StructuredElement,
+  StructuredSurfaceHandler,
+  MarkupAttributeValue,
+} from "@hypit/markup";
+
+import { createRenderHyperframesFragment } from "./fragment.js";
+
+function stringAttribute(element: StructuredElement, name: string): string {
+  const value = element.attributes[name];
+  if (typeof value !== "string" || value.length === 0) throw new Error(`${element.name}.${name} must be a string`);
+  return value;
+}
+
+function referenceAttribute(element: StructuredElement, name: string): string {
+  const value: MarkupAttributeValue | undefined = element.attributes[name];
+  if (typeof value !== "object" || value.kind !== "reference") {
+    throw new Error(`${element.name}.${name} must be a reference`);
+  }
+  return value.path;
+}
+
+export const decodeHyperframesRenderSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  const names = Object.keys(element.attributes).sort();
+  if (names.some((name) => !["composition", "id", "semantic", "space", "start-frame", "end-frame-exclusive"].includes(name))) {
+    throw new Error(`${element.name} contains unsupported attributes`);
+  }
+  if (element.children.some((child) => child.kind === "element" || child.value.trim().length > 0)) {
+    throw new Error(`${element.name} does not accept children`);
+  }
+  const id = stringAttribute(element, "id");
+  const path = referenceAttribute(element, "composition");
+  const composition = resolveReference(path);
+  if (composition === undefined
+    || composition.type.module.name !== compositionTypes.composition.module.name
+    || composition.type.module.version !== compositionTypes.composition.module.version
+    || composition.type.name !== compositionTypes.composition.name) {
+    throw new Error(`${element.name}.composition must reference Composition`);
+  }
+  const time = createTemporalSpace({ id, element, ...resolveTemporalContext({ element, resolveReference }) });
+  const selected = element.attributes["start-frame"] !== undefined || element.attributes["end-frame-exclusive"] !== undefined;
+  const frame = (name: string): number => {
+    const text = stringAttribute(element, name);
+    if (!/^\d+$/u.test(text)) throw new Error(`${element.name}.${name} must be a non-negative integer`);
+    return Number(text);
+  };
+  const range = selected ? { startFrame: frame("start-frame"), endFrameExclusive: frame("end-frame-exclusive") } : undefined;
+  if (range !== undefined) verifyMediaFrameRange(range);
+  const fragment = createRenderHyperframesFragment(selected);
+  const rangeId = `${id}.frame-range`;
+  return {
+    records: range === undefined ? [] : [{ id: rangeId, type: mediaTypes.frameRange, value: { kind: "inline", value: range }, range: element.range }],
+    components: [...time.components, {
+      id,
+      fragment: fragment.id,
+      inputs: { composition: composition.ref, space: time.space.ref, ...(selected ? { range: { kind: "record" as const, id: rangeId } } : {}) },
+      outputs: { video: `${id}.video` },
+      range: element.range,
+    }],
+    fragments: [...time.fragments, fragment],
+  };
+};

package/packages/resource-store-fs/README.md

@@ -0,0 +1,13 @@
+# `@hypit/resource-store-fs`
+
+Filesystem implementation of the Runtime's transient byte port. The local Runtime gives each Build
+its own working directory and removes it after the project Build Result has accepted the public
+Outputs.
+
+The Runtime Profile does not select this package or its path. It stores no Build Result, credentials
+or author source. Code embedding the Runtime directly may still construct `FileResourceStore`.
+
+Read and write methods accept `{ signal }`. Reads close their file stream on cancellation; writes
+close the file and remove the unfinished `.incoming` file before rejecting. Existing resources are
+retained. For `putStream` and `writeStream`, the caller's chunk producer observes the same signal
+while waiting for input.

package/packages/resource-store-fs/package.json

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

package/packages/resource-store-fs/src/index.ts

@@ -0,0 +1,2 @@
+export { FileResourceStore } from "./store.js";
+export type * from "./store.js";

package/packages/resource-store-fs/src/store.ts

@@ -0,0 +1,154 @@
+import { createReadStream } from "node:fs";
+import { randomUUID } from "node:crypto";
+import {
+  link,
+  mkdir,
+  open as openFile,
+  rm,
+  stat,
+} from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+import { isResourceId } from "@hypit/protocol";
+import type { BlobRef, ResourceId } from "@hypit/protocol";
+import type { ResourceIOOptions, ResourceStore } from "@hypit/runtime";
+
+function resourcePath(root: string, resource: ResourceId): string {
+  if (!isResourceId(resource)) throw new Error("Resource id is invalid");
+  return join(root, "resources", resource);
+}
+
+function isNodeError(error: unknown, code: string): boolean {
+  return error instanceof Error && "code" in error && error.code === code;
+}
+
+/** Build-local files keyed by opaque resource instance identity. */
+export class FileResourceStore implements ResourceStore {
+  readonly root: string;
+
+  constructor(root: string) {
+    if (root.trim().length === 0) throw new Error("Resource root must not be empty");
+    this.root = resolve(root);
+  }
+
+  async #store(
+    resource: ResourceId,
+    chunks: AsyncIterable<Uint8Array>,
+    options: ResourceIOOptions,
+    expectedSize?: number,
+  ): Promise<number> {
+    options.signal?.throwIfAborted();
+    const incoming = join(this.root, ".incoming");
+    await mkdir(incoming, { recursive: true });
+    const temporary = join(incoming, `res_${randomUUID()}`);
+    const handle = await openFile(temporary, "wx");
+    let size = 0;
+    try {
+      try {
+        for await (const value of chunks) {
+          options.signal?.throwIfAborted();
+          if (!(value instanceof Uint8Array)) throw new Error("Resource stream yielded non-bytes");
+          const chunk = Uint8Array.from(value);
+          size += chunk.byteLength;
+          if (!Number.isSafeInteger(size)) throw new Error("Resource stream exceeds the supported size");
+          let offset = 0;
+          while (offset < chunk.byteLength) {
+            options.signal?.throwIfAborted();
+            const written = await handle.write(chunk, offset, chunk.byteLength - offset);
+            offset += written.bytesWritten;
+          }
+        }
+      } finally {
+        await handle.close();
+      }
+      options.signal?.throwIfAborted();
+      if (expectedSize !== undefined && size !== expectedSize) {
+        throw new Error(`Resource ${resource} has size ${size}, expected ${expectedSize}`);
+      }
+      const path = resourcePath(this.root, resource);
+      await mkdir(join(this.root, "resources"), { recursive: true });
+      try {
+        options.signal?.throwIfAborted();
+        await link(temporary, path);
+      } catch (error) {
+        if (!isNodeError(error, "EEXIST")) throw error;
+      }
+      return size;
+    } finally {
+      await rm(temporary, { force: true });
+    }
+  }
+
+  async put(bytes: Uint8Array, mediaType: string, options: ResourceIOOptions = {}): Promise<BlobRef> {
+    options.signal?.throwIfAborted();
+    const copy = Uint8Array.from(bytes);
+    return await this.putStream((async function* () { yield copy; })(), mediaType, options);
+  }
+
+  async putStream(chunks: AsyncIterable<Uint8Array>, mediaType: string, options: ResourceIOOptions = {}): Promise<BlobRef> {
+    if (mediaType.trim().length === 0) throw new Error("Resource mediaType must not be empty");
+    const resource = `res_${randomUUID()}` as ResourceId;
+    const size = await this.#store(resource, chunks, options);
+    return { kind: "blob", resource, size, mediaType };
+  }
+
+  async write(resource: BlobRef, bytes: Uint8Array, options: ResourceIOOptions = {}): Promise<void> {
+    options.signal?.throwIfAborted();
+    const copy = Uint8Array.from(bytes);
+    await this.writeStream(resource, (async function* () { yield copy; })(), options);
+  }
+
+  async writeStream(resource: BlobRef, chunks: AsyncIterable<Uint8Array>, options: ResourceIOOptions = {}): Promise<void> {
+    if (!isResourceId(resource.resource)) throw new Error("Resource id is invalid");
+    if (resource.mediaType.trim().length === 0) throw new Error("Resource mediaType must not be empty");
+    await this.#store(resource.resource, chunks, options, resource.size);
+  }
+
+  async get(resource: ResourceId, options: ResourceIOOptions = {}): Promise<Uint8Array | undefined> {
+    const stream = await this.open(resource, options);
+    if (stream === undefined) return undefined;
+    const chunks: Uint8Array[] = [];
+    let size = 0;
+    for await (const chunk of stream) {
+      chunks.push(chunk);
+      size += chunk.byteLength;
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+      bytes.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
+    return bytes;
+  }
+
+  async open(resource: ResourceId, options: ResourceIOOptions = {}): Promise<AsyncIterable<Uint8Array> | undefined> {
+    options.signal?.throwIfAborted();
+    const path = resourcePath(this.root, resource);
+    try {
+      if (!(await stat(path)).isFile()) throw new Error(`Resource ${resource} is not a file`);
+    } catch (error) {
+      if (isNodeError(error, "ENOENT")) return undefined;
+      throw error;
+    }
+    return (async function* () {
+      options.signal?.throwIfAborted();
+      const stream = createReadStream(path, { signal: options.signal });
+      try {
+        for await (const chunk of stream) yield Uint8Array.from(chunk as Buffer);
+      } finally {
+        stream.destroy();
+      }
+    })();
+  }
+
+  async has(resource: ResourceId, options: ResourceIOOptions = {}): Promise<boolean> {
+    options.signal?.throwIfAborted();
+    try {
+      return (await stat(resourcePath(this.root, resource))).isFile();
+    } catch (error) {
+      if (isNodeError(error, "ENOENT")) return false;
+      throw error;
+    }
+  }
+}

package/packages/resource-store-s3/README.md

@@ -0,0 +1,15 @@
+# `@hypit/resource-store-s3`
+
+S3 implementation of the Runtime's internal byte port. It is a library for a Runtime implementation
+that deliberately embeds it; the local Runtime does not expose it as a Runtime Profile choice.
+
+This package is not a Build Result repository and is not needed for ordinary local use. A project that
+wants complete, reusable Build Results in S3 selects `@hypit/build-result-s3` instead. The injected AWS
+client owns authentication; this package stores no Build history or credentials.
+
+Resource methods accept `{ signal }` and forward it to the object client. The AWS implementation
+aborts both pending HTTP requests and response-body reads. Stream producers supplied to writes use
+the same signal. A cancelled multipart write aborts its known upload with a separate five-second
+cleanup deadline; if cleanup fails, the error includes the upload id. Completed objects are retained.
+Streaming writes require the client's create, part-upload, completion and abort methods as well as
+streaming reads. This transfer cleanup does not resume or resubmit a Build.

package/packages/resource-store-s3/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@hypit/resource-store-s3",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "3.1103.0",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/runtime": "workspace:*"
+  }
+}