Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

refactor: own HTML programs and local frame rasterization

kashorin589062efafe3
diff --git a/packages/html-program/README.md b/packages/html-program/README.md
new file mode 100644
index 00000000..856da6e8
--- /dev/null
+++ b/packages/html-program/README.md
@@ -0,0 +1,70 @@
+# @hypit/html-program
+
+`@hypit/html-program` owns Hypit's portable, frame-addressed HTML visual program.
+It compiles a `Composition` and its absolute `Timeline` into one `HtmlProgram`.
+It does not launch a browser, encode video, mix audio, or select a local Provider.
+
+## Boundary
+
+An `HtmlProgram` contains:
+
+- the integer frame domain and canvas;
+- one self-contained HTML document;
+- typed byte dependencies and their conservative frame usage;
+- typed compositable Surface dependencies;
+- typed source-video frame functions.
+
+The page exposes one ABI:
+
+```ts
+window.__hypitFrameProgram.prepare(): Promise<void>
+window.__hypitFrameProgram.applyFrame(frame: number): Promise<void>
+```
+
+`frame` is an absolute integer in `[0, frameCount)`. The page emits
+`hypit-frame` with the same integer. It never converts the request to seconds and
+does not require sequential playback, so independent workers can enter at any
+legal frame.
+
+`HtmlProgram.frameSources` is the compiler-owned source-time plan. A Provider
+uses it to decode exact video frames; it must not recover sampling semantics by
+parsing generated markup. Resource URLs in the HTML remain inert
+`hypit-resource://` placeholders until execution materializes the program.
+
+## Execution ABI
+
+This package also owns the method-neutral requests and result types for executing
+an `HtmlProgram`:
+
+- `@hypit/html-program@1#rasterize-visual` accepts a program and an optional
+ absolute half-open frame range, and returns `TimelineVisual`;
+- `@hypit/html-program@1#rasterize-frames` accepts any strictly increasing set
+ of absolute frames, and returns PNG BlobRefs in request order.
+
+These Capabilities describe demanded results, not a browser, FFmpeg, a machine,
+or a particular Provider. `@hypit/provider-html-local` is one implementation.
+
+## HTML visuals
+
+`hypit.html-visual@1` is the low-level extension for component-owned HTML,
+CSS and synchronous frame drawing. Its setup function returns
+`render(localFrame)`, where `localFrame` is an integer relative to the owning
+Present. Components may use this when ordinary Visual IR elements do not express
+their shared behaviour.
+
+Asynchronous resources must be prepared before drawing. A frame callback may
+not race capture. The page ABI and Provider readiness checks settle declared
+fonts, images and frame listeners before pixels are accepted.
+
+## Ownership rules
+
+- Visual semantics stay in Composition and component packages.
+- Absolute time stays in Timeline.
+- HTML lowering and the frame-page ABI stay here.
+- Browser lifecycle, filesystem staging, source decoding, screenshots and encoding stay in a Provider.
+- Audio planning stays in Media Operations; concrete audio processing and final mux stay in the
+ selected Provider implementation.
+
+There is no raw-HTML reverse compiler. A snapshot or Provider receives the typed
+`HtmlProgram` produced by compilation; generated HTML is not treated as a second
+source language.
diff --git a/packages/hyperframes/package.json b/packages/html-program/package.json
similarity index 58%
rename from packages/hyperframes/package.json
rename to packages/html-program/package.json
index b58cabb7..256a6636 100644
--- a/packages/hyperframes/package.json
+++ b/packages/html-program/package.json
@@ -1,35 +1,34 @@
{
- "name": "@hypit/hyperframes",
+ "name": "@hypit/html-program",
"version": "0.0.0-dev",
"license": "SEE LICENSE IN LICENSE",
"private": true,
"type": "module",
"exports": {
- ".": "./src/index.ts",
- "./project": "./src/project.ts"
+ ".": "./src/index.ts"
},
"hypit": {
"activation": "./src/activation.ts"
},
"dependencies": {
- "@hypit/component-kit": "workspace:*",
+ "@hypit/producer": "workspace:*",
"@hypit/composition": "workspace:*",
- "@hypit/elaborator": "workspace:*",
+ "@hypit/author": "workspace:*",
"@hypit/media": "workspace:*",
"@hypit/protocol": "workspace:*",
- "@hypit/visual-ir": "workspace:*",
- "@hypit/timeline": "workspace:*"
+ "@hypit/timeline": "workspace:*",
+ "@hypit/admission": "workspace:*"
},
"devDependencies": {
"@hypit/caption": "workspace:*",
"@hypit/depth-stack": "workspace:*",
- "@hypit/fonts-open": "workspace:*",
+ "@hypit/fontsource": "workspace:*",
"@hypit/visual-track": "workspace:*",
"@hypit/ranking": "workspace:*",
- "@hypit/screen-overlay": "workspace:*",
"@hypit/script": "workspace:*",
"@hypit/spatial": "workspace:*",
- "@hypit/svs": "workspace:*",
- "@hypit/text-fine": "workspace:*"
+ "@hypit/recipe": "workspace:*",
+ "@hypit/text-fine": "workspace:*",
+ "linkedom": "0.18.13"
}
}
diff --git a/packages/html-program/src/activation.ts b/packages/html-program/src/activation.ts
new file mode 100644
index 00000000..db03fb16
--- /dev/null
+++ b/packages/html-program/src/activation.ts
@@ -0,0 +1,10 @@
+import { createAdmissionPackageFacet } from "@hypit/admission";
+import { createProducerPackageFacet } from "@hypit/producer";
+import { htmlProgramComponent, htmlProgramManifest } from "./index.js";
+
+export const hypitPackage = {
+ format: "hypit.package@1" as const,
+ modules: [{ manifest: htmlProgramManifest }],
+ facets: [...[htmlProgramComponent].flatMap((component) => [createProducerPackageFacet(component), createAdmissionPackageFacet(component)])],
+};
+export default hypitPackage;
diff --git a/packages/hyperframes/src/capture-scope.ts b/packages/html-program/src/capture-scope.ts
similarity index 80%
rename from packages/hyperframes/src/capture-scope.ts
rename to packages/html-program/src/capture-scope.ts
index a4d5f123..19b88fbb 100644
--- a/packages/hyperframes/src/capture-scope.ts
+++ b/packages/html-program/src/capture-scope.ts
@@ -13,6 +13,12 @@ export const presentationCaptureScopeRuntime = String.raw`
const deferred = 'data-hypit-resource-' + attribute;
const value = element.getAttribute(deferred);
if (value === null) continue;
+ // Compiler-planned source-time video is decoded once by the Provider
+ // and supplied as exact source frames. Leaving its URL inert prevents
+ // every browser Worker from independently traversing the same video.
+ // Studio has no frame selection and therefore keeps native playback.
+ if (htmlRequestedFrameSpans !== null && attribute === 'src'
+ && element.matches('video[data-hypit-sampling-part]')) continue;
element.setAttribute(attribute, value);
element.removeAttribute(deferred);
}
@@ -36,7 +42,7 @@ export const presentationCaptureScopeRuntime = String.raw`
// never request this Present. Detach it before DOMContentLoaded so generic
// browser adapters discover only live selected work. Compiler-owned shared
// definitions live outside Present roots; Present-local masks, paths and
- // Browser Program structure leave with their owner.
+ // HtmlVisual structure leave with their owner.
root.remove();
};
for (const root of presents) {
@@ -44,9 +50,9 @@ export const presentationCaptureScopeRuntime = String.raw`
const endFrameExclusive = Number(root.getAttribute('data-hypit-present-end-frame'));
if (!Number.isSafeInteger(startFrame) || !Number.isSafeInteger(endFrameExclusive)
|| startFrame < 0 || endFrameExclusive <= startFrame) {
- throw new Error('HyperFrames Present has an invalid capture span.');
+ throw new Error('HTML renderer Present has an invalid capture span.');
}
- if (hyperframesSelectionOverlaps(startFrame, endFrameExclusive)) selected.push(root);
+ if (htmlSelectionOverlaps(startFrame, endFrameExclusive)) selected.push(root);
else exclude(root);
}
// Compiler-owned direct media URLs become observable to the browser only
diff --git a/packages/html-program/src/component.ts b/packages/html-program/src/component.ts
new file mode 100644
index 00000000..588f9aa2
--- /dev/null
+++ b/packages/html-program/src/component.ts
@@ -0,0 +1,62 @@
+import type { AdmissionPackage } from "@hypit/admission";
+import { plannedNeedInputs } from "@hypit/producer";
+import type { ProducerPackage } from "@hypit/producer";
+import type { Composition } from "@hypit/composition";
+import type { Timeline } from "@hypit/timeline";
+import type { CanonicalValue, StoredValue } from "@hypit/protocol";
+import { canonicalize } from "@hypit/protocol";
+
+import { compileHtmlProgram } from "./document.js";
+import type { MediaFrameRange } from "@hypit/media";
+import { htmlRasterRequest } from "./execution.js";
+import type { HtmlRasterRequest } from "./execution.js";
+import { htmlProgramCapabilities, htmlProgramProducers } from "./manifest.js";
+
+function inline(value: StoredValue, subject: string): CanonicalValue {
+ if (value.kind !== "inline") throw new Error(`${subject} must be inline`);
+ return value.value;
+}
+
+/** Trusted deterministic lowering only; this component never renders frames or reads Artifacts. */
+export const htmlProgramComponent = {
+ producers: [{
+ producer: htmlProgramProducers.compile,
+ handler: ({ inputs }: { inputs: Record<string, { value: StoredValue } | undefined> }) => ({
+ outputs: {
+ program: {
+ kind: "inline",
+ value: canonicalize(compileHtmlProgram(
+ inline(inputs.composition!.value, "Composition") as unknown as Composition,
+ inline(inputs.timeline!.value, "Timeline") as unknown as Timeline,
+ )),
+ },
+ },
+ needs: {},
+ }),
+ }, ...[htmlProgramProducers.requestVisual, htmlProgramProducers.requestVisualRange].map((producer) => ({
+ producer,
+ handler: ({ inputs }: { inputs: Record<string, { value: StoredValue } | undefined> }) => ({
+ outputs: {},
+ needs: { visual: htmlRasterRequest(
+ inline(inputs.program!.value, "HtmlProgram") as never,
+ inputs.range === undefined ? {} : { range: inline(inputs.range.value, "MediaFrameRange") as unknown as MediaFrameRange },
+ ) },
+ }),
+ }))],
+ plannedNeeds: [htmlProgramProducers.requestVisual, htmlProgramProducers.requestVisualRange].map((producer) => ({
+ producer,
+ port: "visual",
+ capability: htmlProgramCapabilities.rasterizeVisual,
+ plan({ state, step }) { return { constraints: {}, pendingInputs: plannedNeedInputs(state, step) }; },
+ present(specification) {
+ const request = specification.constraints as Partial<HtmlRasterRequest>;
+ if (request.program === undefined) return { fields: {}, references: {} };
+ const { program, range } = request;
+ return { fields: {
+ width: [program.canvas.width], height: [program.canvas.height],
+ startFrame: [range?.startFrame ?? 0], endFrameExclusive: [range?.endFrameExclusive ?? program.frameCount],
+ frameRate: [`${program.frameRate.numerator}/${program.frameRate.denominator}`],
+ }, references: {} };
+ },
+ })),
+} satisfies ProducerPackage & AdmissionPackage;
diff --git a/packages/hyperframes/src/document.ts b/packages/html-program/src/document.ts
similarity index 82%
rename from packages/hyperframes/src/document.ts
rename to packages/html-program/src/document.ts
index 5dacfcab..709acfe0 100644
--- a/packages/hyperframes/src/document.ts
+++ b/packages/html-program/src/document.ts
@@ -17,17 +17,18 @@ import type {
} from "@hypit/composition";
import { canonicalStringify, isResourceId } from "@hypit/protocol";
import type { BlobRef, ResourceId } from "@hypit/protocol";
-import { VISUAL_IR_V1 } from "@hypit/visual-ir";
-import { readBrowserProgram, browserProgramHtml, browserProgramScript } from "./browser-program.js";
+import { VISUAL_IR_V1 } from "@hypit/composition";
+import { readHtmlVisual, htmlVisualHtml, htmlVisualScript } from "./html-visual.js";
import { presentationCaptureScopeRuntime } from "./capture-scope.js";
import { presentationVisibilityScript } from "./visibility.js";
import { frameSelectionRuntime, frameWorkIndexRuntime } from "./frame-work.js";
import type {
ResourceUrlResolver,
- HyperframesArtifact,
- HyperframesDocument,
- HyperframesFrameSpan,
+ HtmlArtifact,
+ HtmlProgram,
+ HtmlFrameSpan,
+ HtmlFrameSource,
} from "./types.js";
import {
collectTerminalTextFonts,
@@ -71,7 +72,7 @@ function fpsRational(numerator: number, denominator: number): string {
}
function rationalDecimal(numerator: bigint, denominator: bigint): string {
- if (denominator <= 0n) throw new Error("HyperFrames rational denominator must be positive.");
+ if (denominator <= 0n) throw new Error("HTML renderer rational denominator must be positive.");
const scale = 1_000_000_000_000n;
const scaled = numerator * scale / denominator;
const whole = scaled / scale;
@@ -96,7 +97,7 @@ function sourcePosition(piece: VisualSourceTimePiece, offset: number): {
+ BigInt(offset) * BigInt(piece.rate.numerator) * BigInt(piece.sourceAtStart.denominator);
if (piece.wrap === undefined) {
if (raw < 0n || raw > BigInt(Number.MAX_SAFE_INTEGER) || denominator > BigInt(Number.MAX_SAFE_INTEGER)) {
- throw new Error("HyperFrames visual source time exceeds safe arithmetic.");
+ throw new Error("HTML renderer visual source time exceeds safe arithmetic.");
}
return { position: { numerator: Number(raw), denominator: Number(denominator) }, cycle: 0n };
}
@@ -107,7 +108,7 @@ function sourcePosition(piece: VisualSourceTimePiece, offset: number): {
const wrapped = ((delta % length) + length) % length;
const numerator = start + wrapped;
if (numerator > BigInt(Number.MAX_SAFE_INTEGER) || denominator > BigInt(Number.MAX_SAFE_INTEGER)) {
- throw new Error("HyperFrames visual sampling exceeds safe arithmetic.");
+ throw new Error("HTML renderer visual sampling exceeds safe arithmetic.");
}
return { position: { numerator: Number(numerator), denominator: Number(denominator) }, cycle };
}
@@ -177,14 +178,14 @@ function percentage(frame: number, totalFrames: number): string {
return `${whole}.${String(remainder).padStart(9, "0").replace(/0+$/u, "")}%`;
}
-export function hyperframesResourceUri(resource: ResourceId): string {
- if (!isResourceId(resource)) throw new Error("HyperFrames Resource id is invalid.");
+export function htmlProgramResourceUri(resource: ResourceId): string {
+ if (!isResourceId(resource)) throw new Error("HTML renderer Resource id is invalid.");
return `hypit-resource://${resource}`;
}
/** Keep compiler-owned media inert until the page has applied its render selection. */
function deferredResource(attribute: "src" | "href", resource: ResourceId): string {
- return `data-hypit-resource-${attribute}="${escapeHtml(hyperframesResourceUri(resource))}"`;
+ return `data-hypit-resource-${attribute}="${escapeHtml(htmlProgramResourceUri(resource))}"`;
}
function css(style: readonly VisualStyleDeclaration[]): string {
@@ -247,6 +248,7 @@ type ElementContext = {
readonly emittedFilterIds: Set<string>;
readonly sharedGlyphFilterDefinitions: string[];
readonly stableId: StableDomId;
+ readonly frameSources: HtmlFrameSource[];
};
/** Every emitted element, including SVG mask sources, keeps the same authored frame clock. */
@@ -267,7 +269,7 @@ function elementPresentation(element: VisualElement, context: ElementContext) {
`animation-duration:${animationDuration}s`,
"animation-fill-mode:both",
// An independently launched render worker may begin at any frame. Keep
- // CSS animations inert from first paint so HyperFrames' exact seek is
+ // CSS animations inert from first paint so HTML renderer' exact seek is
// the only clock; otherwise page-load time leaks into the first frame of
// each partition before the runtime pauses the animation.
"animation-play-state:paused",
@@ -340,9 +342,9 @@ function renderElement(
return `<svg ${common}${viewport} width="100%" height="100%" overflow="visible"><defs><mask id="${maskId}" x="0" y="0" width="100%" height="100%" maskUnits="userSpaceOnUse" maskContentUnits="userSpaceOnUse" style="mask-type:${element.mode}">${maskSource}</mask></defs><foreignObject x="0" y="0" width="100%" height="100%" mask="url(#${maskId})"><div xmlns="http://www.w3.org/1999/xhtml" style="position:relative;width:100%;height:100%">${renderOwned(contentRoot)}</div></foreignObject></svg>`;
}
if (element.kind === "program") {
- const program = readBrowserProgram(element.program);
+ const program = readHtmlVisual(element.program);
const slots = new Map((children.get(element.id) ?? []).map(child => [child.id, renderElement(child, children, context)]));
- return `<div ${common}>${browserProgramHtml(program, slots)}</div>`;
+ return `<div ${common}>${htmlVisualHtml(program, slots)}</div>`;
}
const descendants = (children.get(element.id) ?? [])
.map((child) => renderElement(child, children, context))
@@ -381,15 +383,19 @@ function renderElement(
const startFrame = context.presentStartFrame + run.startFrame;
const durationFrames = run.endFrameExclusive - run.startFrame;
const partId = `${id}-sample-${String(part).padStart(4, "0")}`;
+ context.frameSources.push({
+ id: partId,
+ resource: artifact.resource,
+ startFrame,
+ endFrameExclusive: startFrame + durationFrames,
+ sourceFrame: { ...run.sourceFrame },
+ sourceRate: { ...piece.rate },
+ sourceFrameRate: { ...element.sourceTime!.sourceFrameRate },
+ });
const media = [
`id="${partId}"`,
`data-hypit-element-id="${escapeHtml(element.id)}"`,
`data-hypit-sampling-part="${part}"`,
- `data-start="${frameSeconds(startFrame, context.programNumerator, context.programDenominator)}"`,
- `data-duration="${frameSeconds(durationFrames, context.programNumerator, context.programDenominator)}"`,
- `data-track-index="${context.stackIndex}"`,
- `data-media-start="${sourceSeconds(run.sourceFrame, element.sourceTime!.sourceFrameRate)}"`,
- `data-playback-rate="${sampledPlaybackRate(piece.rate, element.sourceTime!.sourceFrameRate, context.programNumerator, context.programDenominator)}"`,
`data-hypit-source-frame="${run.sourceFrame.numerator}/${run.sourceFrame.denominator}"`,
`data-hypit-source-rate="${piece.rate.numerator}/${piece.rate.denominator}"`,
`data-hypit-start-frame="${startFrame}"`,
@@ -413,9 +419,6 @@ function renderElement(
if (element.kind === "surface") {
const surface = [
`data-hypit-surface-resource="${element.surface.artifact.resource}"`,
- `data-start="${context.presentStart}"`,
- `data-duration="${context.presentDuration}"`,
- `data-track-index="${context.stackIndex}"`,
`data-hypit-alpha-mode="${element.surface.alphaMode}"`,
`data-hypit-color-space="${element.surface.colorSpace}"`,
`width="${element.surface.width}"`,
@@ -426,9 +429,6 @@ function renderElement(
}
const media = [
- `data-start="${context.presentStart}"`,
- `data-duration="${context.presentDuration}"`,
- `data-track-index="${context.stackIndex}"`,
element.kind === "video" && element.muted !== false ? "muted" : "",
element.kind === "video" ? "playsinline" : "",
].filter(Boolean).join(" ");
@@ -445,6 +445,7 @@ function renderVisualPresent(
emittedFilterIds: Set<string>,
sharedGlyphFilterDefinitions: string[],
stableId: StableDomId,
+ frameSources: HtmlFrameSource[],
): string {
const start = frameSeconds(present.span.startFrame, numerator, denominator);
const duration = frameSeconds(present.span.endFrameExclusive - present.span.startFrame, numerator, denominator);
@@ -470,8 +471,9 @@ function renderVisualPresent(
emittedFilterIds,
sharedGlyphFilterDefinitions,
stableId,
+ frameSources,
});
- return `<div class="clip hypit-visual-present" data-hypit-track-id="${escapeHtml(track.id)}" data-hypit-present-id="${escapeHtml(present.id)}" data-hypit-present-start-frame="${present.span.startFrame}" data-hypit-present-end-frame="${present.span.endFrameExclusive}" data-hypit-present-order="${present.order}" data-hypit-z="${present.z}" data-track-index="${stackIndex}" data-start="${start}" data-duration="${duration}" style="position:absolute;inset:0;z-index:${stackIndex};overflow:hidden;pointer-events:none">${present.visibility === undefined ? contents : `<div data-hypit-visibility="${escapeHtml(JSON.stringify(present.visibility))}" style="position:absolute;inset:0">${contents}</div>`}</div>`;
+ return `<div class="hypit-visual-present" data-hypit-track-id="${escapeHtml(track.id)}" data-hypit-present-id="${escapeHtml(present.id)}" data-hypit-present-start-frame="${present.span.startFrame}" data-hypit-present-end-frame="${present.span.endFrameExclusive}" data-hypit-present-order="${present.order}" data-hypit-z="${present.z}" style="position:absolute;inset:0;z-index:${stackIndex};overflow:hidden;pointer-events:none">${present.visibility === undefined ? contents : `<div data-hypit-visibility="${escapeHtml(JSON.stringify(present.visibility))}" style="position:absolute;inset:0">${contents}</div>`}</div>`;
}
function renderAnimationRules(track: VisualTrack, present: VisualPresent, stableId: StableDomId): string[] {
@@ -504,8 +506,8 @@ function orderedVisualPresents(tracks: readonly Track[]): Array<{ readonly track
|| left.present.id.localeCompare(right.present.id));
}
-function mergeFrameSpans(spans: readonly HyperframesFrameSpan[]): HyperframesFrameSpan[] {
- const result: HyperframesFrameSpan[] = [];
+function mergeFrameSpans(spans: readonly HtmlFrameSpan[]): HtmlFrameSpan[] {
+ const result: HtmlFrameSpan[] = [];
for (const span of [...spans].sort((left, right) => left.startFrame - right.startFrame
|| left.endFrameExclusive - right.endFrameExclusive)) {
const previous = result.at(-1);
@@ -519,10 +521,10 @@ function mergeFrameSpans(spans: readonly HyperframesFrameSpan[]): HyperframesFra
return result;
}
-function collectArtifacts(composition: Composition): HyperframesArtifact[] {
- const artifacts = new Map<ResourceId, { artifact: BlobRef; always: boolean; spans: HyperframesFrameSpan[] }>();
+function collectArtifacts(composition: Composition): HtmlArtifact[] {
+ const artifacts = new Map<ResourceId, { artifact: BlobRef; always: boolean; spans: HtmlFrameSpan[] }>();
const add = (artifact: Pick<BlobRef, "resource" | "size" | "mediaType">,
- usage: "always" | HyperframesFrameSpan): void => {
+ usage: "always" | HtmlFrameSpan): void => {
const next: BlobRef = {
kind: "blob",
resource: artifact.resource,
@@ -531,7 +533,7 @@ function collectArtifacts(composition: Composition): HyperframesArtifact[] {
};
const existing = artifacts.get(artifact.resource);
if (existing !== undefined && (existing.artifact.size !== next.size || existing.artifact.mediaType !== next.mediaType)) {
- throw new Error(`HyperFrames Artifact ${artifact.resource} has conflicting metadata.`);
+ throw new Error(`HTML renderer Artifact ${artifact.resource} has conflicting metadata.`);
}
const entry = existing ?? { artifact: next, always: false, spans: [] };
if (usage === "always") entry.always = true;
@@ -544,8 +546,8 @@ function collectArtifacts(composition: Composition): HyperframesArtifact[] {
for (const element of present.elements) {
if (element.kind === "image" || element.kind === "video") add(element.artifact, present.span);
if (element.kind === "surface") add(element.surface.artifact, present.span);
- // Browser Program HTML, CSS and setup are intentionally opaque. Their
- // declared dependencies stay conservative even though the Program root
+ // HtmlVisual HTML, CSS and setup are intentionally opaque. Their
+ // declared dependencies stay conservative even though the visual root
// itself has a Present span.
if (element.kind === "program") for (const artifact of element.program.artifacts) add(artifact, "always");
if (element.kind === "text") {
@@ -579,7 +581,7 @@ function collectSurfaces(composition: Composition): CompositableSurfaceRef[] {
const surface = structuredClone(element.surface);
const existing = surfaces.get(surface.artifact.resource);
if (existing !== undefined && canonicalStringify(existing) !== canonicalStringify(surface)) {
- throw new Error(`HyperFrames Surface ${surface.artifact.resource} has conflicting declarations.`);
+ throw new Error(`HTML renderer Surface ${surface.artifact.resource} has conflicting declarations.`);
}
surfaces.set(surface.artifact.resource, surface);
}
@@ -623,7 +625,7 @@ function renderFontFaces(composition: Composition, stableId: StableDomId): strin
return collectFonts(composition).flatMap((font) => font.sources.map((source) => [
"@font-face{",
`font-family:${exactFontFamily(font, stableId)};`,
- `src:url(\"${hyperframesResourceUri(source.artifact.resource)}\") format(\"${fontFormat(source.artifact.mediaType)}\");`,
+ `src:url(\"${htmlProgramResourceUri(source.artifact.resource)}\") format(\"${fontFormat(source.artifact.mediaType)}\");`,
`font-weight:${font.weight};`,
`font-style:${font.style};`,
"font-display:block;",
@@ -660,14 +662,14 @@ function frameAnimationRuntime(numerator: number, denominator: number): string {
if (!Number.isSafeInteger(end)) throw new Error("Visual IR frame animation Present span exceeds safe arithmetic.");
// CSS already keeps every authored animation paused. Only materialize the
// browser Animation objects which this render can actually sample.
- if (!hyperframesSelectionOverlaps(start, end)) continue;
+ if (!htmlSelectionOverlaps(start, end)) continue;
void element.getBoundingClientRect();
const animation = element.getAnimations()[0];
if (animation === undefined) throw new Error("Visual IR frame animation did not materialize.");
// The authored keyframes are already the compact state function. Keep them
// instead of expanding every Present frame into a second table of
// computed-style strings in every render Worker, but do not leave the CSS
- // animation live: HyperFrames' css and waapi adapters seek every live
+ // animation live: HTML renderer' css and waapi adapters seek every live
// document animation to absolute composition time, which replaces this
// Present-relative pose whenever the Present does not start at frame 0.
const keyframes = animation.effect.getKeyframes();
@@ -691,14 +693,13 @@ function frameAnimationRuntime(numerator: number, denominator: number): string {
}
// The shared index owns only frame-span lookup. Animation materialization and
// absolute currentTime evaluation remain private to this adapter.
- const workIndex = hyperframesCreateFrameWorkIndex([...groupsBySpan.values()]);
+ const workIndex = htmlCreateFrameWorkIndex([...groupsBySpan.values()]);
const read = (style, name) => name.startsWith("--") ? style.getPropertyValue(name) : style[name];
const write = (style, name, value) => {
if (name.startsWith("--")) style.setProperty(name, value);
else style[name] = value;
};
- const applyFrame = (time) => {
- const programFrame = Math.max(0, Math.round(Number(time || 0) * numerator / denominator));
+ const applyFrame = (programFrame) => {
const active = [];
for (const work of workIndex.at(programFrame)) {
const localTime = (programFrame - work.startFrame) * millisecondsPerFrame;
@@ -709,7 +710,7 @@ function frameAnimationRuntime(numerator: number, denominator: number): string {
}
// Evaluate each pose with a transient Animation, read it and cancel it before
// this seek returns, so no adapter ever sees it. The Animation constructor,
- // unlike Element.animate, is not tracked by HyperFrames' waapi adapter. Only
+ // unlike Element.animate, is not tracked by HTML renderer' waapi adapter. Only
// the resulting inline style reaches the captured frame.
const probes = active.map(({ item, localTime }) => {
const probe = new Animation(new KeyframeEffect(item.element, item.keyframes, item.timing), document.timeline);
@@ -727,11 +728,41 @@ function frameAnimationRuntime(numerator: number, denominator: number): string {
void document.documentElement.getBoundingClientRect();
};
void document.documentElement.getBoundingClientRect();
- window.addEventListener("hf-seek", (event) => applyFrame(event.detail?.time));
+ window.addEventListener("hypit-frame", (event) => applyFrame(event.detail?.frame));
})();`;
}
-function emitHtml(composition: Composition, timeline: Timeline): string {
+function frameProgramRuntime(frameCount: number): string {
+ return `(() => {
+ const presents = [...document.querySelectorAll('[data-hypit-present-start-frame]')].map(element => ({
+ element,
+ startFrame: Number(element.getAttribute('data-hypit-present-start-frame')),
+ endFrameExclusive: Number(element.getAttribute('data-hypit-present-end-frame')),
+ }));
+ const applyFrame = async frame => {
+ if (!Number.isSafeInteger(frame) || frame < 0 || frame >= ${frameCount}) {
+ throw new Error('HTML Program frame is outside its domain.');
+ }
+ for (const present of presents) {
+ present.element.style.display = frame >= present.startFrame && frame < present.endFrameExclusive ? '' : 'none';
+ }
+ const pending = [];
+ window.dispatchEvent(new CustomEvent('hypit-frame', { detail: {
+ frame,
+ waitUntil(value) { pending.push(Promise.resolve(value)); },
+ }}));
+ await Promise.all(pending);
+ void document.documentElement.getBoundingClientRect();
+ };
+ Object.defineProperty(window, '__hypitFrameProgram', { configurable: false, writable: false, value: Object.freeze({
+ frameCount: ${frameCount},
+ async prepare() { await document.fonts.ready; await applyFrame(0); },
+ applyFrame,
+ }) });
+ })();`;
+}
+
+function emitHtml(composition: Composition, timeline: Timeline, frameSources: HtmlFrameSource[]): string {
const { numerator, denominator } = timeline.frameRate;
const visuals = orderedVisualPresents(composition.tracks);
// One document, one set of glyph filter definitions. Keep definitions outside
@@ -741,7 +772,7 @@ function emitHtml(composition: Composition, timeline: Timeline): string {
const sharedGlyphFilterDefinitions: string[] = [];
const stableId = createStableDomId();
const visualHtml = visuals.map(({ track, present }, index) => renderVisualPresent(track, present, index,
- numerator, denominator, emittedFilterIds, sharedGlyphFilterDefinitions, stableId)).join("\n ");
+ numerator, denominator, emittedFilterIds, sharedGlyphFilterDefinitions, stableId, frameSources)).join("\n ");
const sharedDefinitionsHtml = sharedGlyphFilterDefinitions.length === 0 ? ""
: `<svg data-hypit-document-definitions aria-hidden="true" width="0" height="0" style="position:absolute;overflow:hidden"><defs>${sharedGlyphFilterDefinitions.join("")}</defs></svg>`;
const animationCss = visuals.flatMap(({ track, present }) => renderAnimationRules(track, present, stableId)).join("\n ");
@@ -750,11 +781,11 @@ function emitHtml(composition: Composition, timeline: Timeline): string {
id: stableId([track.id, present.id, element.id]),
startFrame: present.span.startFrame,
durationFrames: present.span.endFrameExclusive - present.span.startFrame,
- program: readBrowserProgram(element.program),
+ program: readHtmlVisual(element.program),
}]));
const programCss = programs.map(entry => `@scope (#${entry.id}) { ${entry.program.css ?? ""} }`).join("\n");
const hasVisibility = visuals.some(({ present }) => present.visibility !== undefined);
- const programRuntime = programs.length === 0 ? "" : `<script>${browserProgramScript(programs, numerator, denominator)}</script>`;
+ const programRuntime = programs.length === 0 ? "" : `<script>${htmlVisualScript(programs, numerator, denominator)}</script>`;
const visibilityRuntime = hasVisibility ? `<script>${presentationVisibilityScript(numerator, denominator)}</script>` : "";
const duration = frameSeconds(timelineFrameCount(timeline), numerator, denominator);
const fps = fpsRational(numerator, denominator);
@@ -771,7 +802,7 @@ function emitHtml(composition: Composition, timeline: Timeline): string {
<meta name="viewport" content="width=device-width,initial-scale=1"/>
<style>
html,body{margin:0;width:100%;height:100%;overflow:hidden;background:${composition.canvas.clearColor}}
- [data-composition-id]{position:relative;overflow:hidden;background:${composition.canvas.clearColor}}
+ [data-hypit-program-root]{position:relative;overflow:hidden;background:${composition.canvas.clearColor}}
*,*::before,*::after{box-sizing:border-box}
${fontCss}
${animationCss}
@@ -779,16 +810,17 @@ function emitHtml(composition: Composition, timeline: Timeline): string {
</style>
</head>
<body>
- <div data-composition-id="${escapeHtml(composition.id)}" data-start="0" data-no-timeline data-width="${composition.canvas.width}" data-height="${composition.canvas.height}" data-duration="${duration}" data-fps="${fps}" data-hypit-frame-count="${frameCount}">
+ <div data-hypit-program-root data-hypit-program-id="${escapeHtml(composition.id)}" data-hypit-width="${composition.canvas.width}" data-hypit-height="${composition.canvas.height}" data-hypit-frame-numerator="${numerator}" data-hypit-frame-denominator="${denominator}" data-hypit-frame-count="${frameCount}" style="width:${composition.canvas.width}px;height:${composition.canvas.height}px">
${sharedDefinitionsHtml}${sharedDefinitionsHtml.length === 0 ? "" : "\n "}${visualHtml}
</div>${frameRuntime}${programRuntime}
${visibilityRuntime}
+ <script>${frameProgramRuntime(frameCount)}</script>
</body>
</html>
`;
}
-function normalizedDocument(value: HyperframesDocument): HyperframesDocument {
+function normalizedDocument(value: HtmlProgram): HtmlProgram {
return {
visualIr: value.visualIr,
frameRate: { ...value.frameRate },
@@ -802,12 +834,19 @@ function normalizedDocument(value: HyperframesDocument): HyperframesDocument {
surfaces: [...value.surfaces]
.map((surface) => structuredClone(surface))
.sort((left, right) => left.artifact.resource.localeCompare(right.artifact.resource)),
+ frameSources: [...value.frameSources].map((source) => ({
+ ...source,
+ sourceFrame: { ...source.sourceFrame },
+ sourceRate: { ...source.sourceRate },
+ sourceFrameRate: { ...source.sourceFrameRate },
+ })).sort((left, right) => left.startFrame - right.startFrame || left.id.localeCompare(right.id)),
html: value.html,
};
}
-export function compileHyperframesDocument(composition: Composition, timeline: Timeline): HyperframesDocument {
+export function compileHtmlProgram(composition: Composition, timeline: Timeline): HtmlProgram {
assertCompositionIdentity(composition, timeline);
+ const frameSources: HtmlFrameSource[] = [];
const content = normalizedDocument({
visualIr: VISUAL_IR_V1,
frameRate: { ...timeline.frameRate },
@@ -818,13 +857,14 @@ export function compileHyperframesDocument(composition: Composition, timeline: T
},
artifacts: collectArtifacts(composition),
surfaces: collectSurfaces(composition),
- html: emitHtml(composition, timeline),
+ frameSources,
+ html: emitHtml(composition, timeline, frameSources),
});
return content;
}
-export function assertHyperframesDocument(document: HyperframesDocument): void {
- if (document.visualIr !== VISUAL_IR_V1) throw new Error("Unsupported HyperframesDocument visual IR.");
+export function assertHtmlProgram(document: HtmlProgram): void {
+ if (document.visualIr !== VISUAL_IR_V1) throw new Error("Unsupported HtmlProgram visual IR.");
if (
!Number.isSafeInteger(document.frameRate.numerator)
|| document.frameRate.numerator <= 0
@@ -837,9 +877,9 @@ export function assertHyperframesDocument(document: HyperframesDocument): void {
|| !Number.isSafeInteger(document.canvas.height)
|| document.canvas.height <= 0
) {
- throw new Error("HyperframesDocument frame domain or canvas is invalid.");
+ throw new Error("HtmlProgram frame domain or canvas is invalid.");
}
- if (!document.html.startsWith("<!doctype html>")) throw new Error("HyperframesDocument HTML is invalid.");
+ if (!document.html.startsWith("<!doctype html>")) throw new Error("HtmlProgram HTML is invalid.");
const declared = [...document.artifacts];
if (declared.some((entry) => {
const item = entry?.artifact;
@@ -853,50 +893,67 @@ export function assertHyperframesDocument(document: HyperframesDocument): void {
|| span.endFrameExclusive > document.frameCount)) return true;
return JSON.stringify(mergeFrameSpans(entry.usage.spans)) !== JSON.stringify(entry.usage.spans);
}) || new Set(declared.map((entry) => entry.artifact.resource)).size !== declared.length) {
- throw new Error("HyperframesDocument Artifact set is invalid.");
+ throw new Error("HtmlProgram Artifact set is invalid.");
}
const referenced = [...document.html.matchAll(RESOURCE_URI)].map((match) => match[1] as ResourceId);
const actual = [...new Set(referenced)].sort();
if (JSON.stringify(actual) !== JSON.stringify(declared.map((entry) => entry.artifact.resource).sort())) {
- throw new Error("HyperframesDocument Artifact placeholders do not match its declared dependencies.");
+ throw new Error("HtmlProgram Artifact placeholders do not match its declared dependencies.");
+ }
+ if (!Array.isArray(document.surfaces)) throw new Error("HtmlProgram Surface set is invalid.");
+ if (!Array.isArray(document.frameSources) || document.frameSources.some((source) =>
+ typeof source?.id !== "string" || source.id.length === 0 || !isResourceId(source.resource)
+ || !Number.isSafeInteger(source.startFrame) || !Number.isSafeInteger(source.endFrameExclusive)
+ || source.startFrame < 0 || source.endFrameExclusive <= source.startFrame
+ || source.endFrameExclusive > document.frameCount
+ || !Number.isSafeInteger(source.sourceFrame?.numerator) || source.sourceFrame.numerator < 0
+ || !Number.isSafeInteger(source.sourceFrame?.denominator) || source.sourceFrame.denominator <= 0
+ || !Number.isSafeInteger(source.sourceRate?.numerator)
+ || !Number.isSafeInteger(source.sourceRate?.denominator) || source.sourceRate.denominator <= 0
+ || !Number.isSafeInteger(source.sourceFrameRate?.numerator) || source.sourceFrameRate.numerator <= 0
+ || !Number.isSafeInteger(source.sourceFrameRate?.denominator) || source.sourceFrameRate.denominator <= 0
+ || !declared.some((entry) => entry.artifact.resource === source.resource))) {
+ throw new Error("HtmlProgram frame-source plan is invalid.");
+ }
+ if (new Set(document.frameSources.map((source) => source.id)).size !== document.frameSources.length) {
+ throw new Error("HtmlProgram frame-source identities must be unique.");
}
- if (!Array.isArray(document.surfaces)) throw new Error("HyperframesDocument Surface set is invalid.");
const surfaceArtifacts = new Set<string>();
for (const [index, surface] of document.surfaces.entries()) {
- assertCompositableSurfaceRef(surface, `HyperframesDocument.surfaces.${index}`);
+ assertCompositableSurfaceRef(surface, `HtmlProgram.surfaces.${index}`);
if (surfaceArtifacts.has(surface.artifact.resource)) {
- throw new Error("HyperframesDocument Surface set repeats an Artifact.");
+ throw new Error("HtmlProgram Surface set repeats an Artifact.");
}
surfaceArtifacts.add(surface.artifact.resource);
const artifact = declared.find((entry) => entry.artifact.resource === surface.artifact.resource)?.artifact;
if (artifact === undefined
|| artifact.size !== surface.artifact.size
|| artifact.mediaType !== surface.artifact.mediaType) {
- throw new Error("HyperframesDocument Surface is not bound to its declared Artifact.");
+ throw new Error("HtmlProgram Surface is not bound to its declared Artifact.");
}
}
const referencedSurfaces = [...new Set(
[...document.html.matchAll(SURFACE_RESOURCE)].map((match) => match[1]!),
)].sort();
if (JSON.stringify(referencedSurfaces) !== JSON.stringify([...surfaceArtifacts].sort())) {
- throw new Error("HyperframesDocument Surface markers do not match its typed dependencies.");
+ throw new Error("HtmlProgram Surface markers do not match its typed dependencies.");
}
}
/** Validate one independently renderable frame index without parsing generated HTML. */
-export function assertHyperframesFrameIndex(document: HyperframesDocument, frame: number): void {
- assertHyperframesDocument(document);
+export function assertHtmlFrameIndex(document: HtmlProgram, frame: number): void {
+ assertHtmlProgram(document);
if (!Number.isSafeInteger(frame) || frame < 0 || frame >= document.frameCount) {
- throw new Error(`HyperFrames frame ${frame} is outside [0, ${document.frameCount}).`);
+ throw new Error(`HTML renderer frame ${frame} is outside [0, ${document.frameCount}).`);
}
}
/** Validate a Provider-owned half-open chunk of the document's exact frame domain. */
-export function assertHyperframesFrameSpan(
- document: HyperframesDocument,
- span: HyperframesFrameSpan,
+export function assertHtmlFrameSpan(
+ document: HtmlProgram,
+ span: HtmlFrameSpan,
): void {
- assertHyperframesDocument(document);
+ assertHtmlProgram(document);
if (
!Number.isSafeInteger(span.startFrame)
|| !Number.isSafeInteger(span.endFrameExclusive)
@@ -905,16 +962,16 @@ export function assertHyperframesFrameSpan(
|| span.endFrameExclusive > document.frameCount
) {
throw new Error(
- `HyperFrames frame span [${span.startFrame}, ${span.endFrameExclusive}) is outside [0, ${document.frameCount}).`,
+ `HTML renderer frame span [${span.startFrame}, ${span.endFrameExclusive}) is outside [0, ${document.frameCount}).`,
);
}
}
-function assertHyperframesFrameSelection(
- document: HyperframesDocument,
- selection: readonly HyperframesFrameSpan[],
+function assertHTMLFrameSelection(
+ document: HtmlProgram,
+ selection: readonly HtmlFrameSpan[],
): void {
- if (selection.length === 0) throw new Error("HyperFrames Artifact selection must not be empty");
+ if (selection.length === 0) throw new Error("HTML renderer Artifact selection must not be empty");
let previousEnd = 0;
for (const [index, span] of selection.entries()) {
if (span === null || typeof span !== "object"
@@ -922,15 +979,15 @@ function assertHyperframesFrameSelection(
|| span.startFrame < 0 || span.endFrameExclusive <= span.startFrame
|| span.endFrameExclusive > document.frameCount
|| (index > 0 && span.startFrame < previousEnd)) {
- throw new Error("HyperFrames Artifact selection must contain ordered, disjoint spans inside the document frame domain");
+ throw new Error("HTML renderer Artifact selection must contain ordered, disjoint spans inside the document frame domain");
}
previousEnd = span.endFrameExclusive;
}
}
function artifactUsageOverlaps(
- usage: readonly HyperframesFrameSpan[],
- selection: readonly HyperframesFrameSpan[],
+ usage: readonly HtmlFrameSpan[],
+ selection: readonly HtmlFrameSpan[],
): boolean {
return usage.some((span) => {
let low = 0;
@@ -948,29 +1005,29 @@ function artifactUsageOverlaps(
* Project one whole render selection onto the compiler's conservative byte dependencies.
* The result is shared by every worker; no worker or traversal state enters the proof.
*/
-export function selectHyperframesArtifacts(
- document: HyperframesDocument,
- frameSelection?: readonly HyperframesFrameSpan[],
-): readonly HyperframesArtifact[] {
- assertHyperframesDocument(document);
+export function selectHtmlArtifacts(
+ document: HtmlProgram,
+ frameSelection?: readonly HtmlFrameSpan[],
+): readonly HtmlArtifact[] {
+ assertHtmlProgram(document);
if (frameSelection === undefined) return document.artifacts;
- assertHyperframesFrameSelection(document, frameSelection);
+ assertHTMLFrameSelection(document, frameSelection);
return document.artifacts.filter((entry) => entry.usage.kind === "always"
|| artifactUsageOverlaps(entry.usage.spans, frameSelection));
}
/** Runtime-only URL materialization. The returned HTML is intentionally not a new compiled Record. */
-export function materializeHyperframesHtml(
- document: HyperframesDocument,
+export function materializeHtmlProgram(
+ document: HtmlProgram,
resolve: ResourceUrlResolver,
): string {
- assertHyperframesDocument(document);
+ assertHtmlProgram(document);
const artifacts = new Map(document.artifacts.map((entry) => [entry.artifact.resource, entry.artifact]));
return document.html.replace(RESOURCE_URI, (_uri, resource: ResourceId) => {
const artifact = artifacts.get(resource);
- if (artifact === undefined) throw new Error(`HyperFrames Resource ${resource} is undeclared.`);
+ if (artifact === undefined) throw new Error(`HTML renderer Resource ${resource} is undeclared.`);
return escapeHtml(resolve(artifact));
});
}
-export const hyperframesTime = { frameSeconds, fpsDecimal, fpsRational } as const;
+export const htmlProgramTime = { frameSeconds, fpsDecimal, fpsRational } as const;
diff --git a/packages/html-program/src/execution.ts b/packages/html-program/src/execution.ts
new file mode 100644
index 00000000..62324b11
--- /dev/null
+++ b/packages/html-program/src/execution.ts
@@ -0,0 +1,63 @@
+import type { CanonicalValue, BlobRef } from "@hypit/protocol";
+import { isResourceId } from "@hypit/protocol";
+import { verifyMediaFrameRange } from "@hypit/media";
+import type { MediaFrameRange } from "@hypit/media";
+import { assertHtmlProgram } from "./document.js";
+import type { HtmlProgram } from "./types.js";
+
+export type HtmlRasterRequest = {
+ readonly program: HtmlProgram;
+ readonly range?: MediaFrameRange;
+};
+
+/** Select original program frames in strictly increasing order. */
+export type HtmlFrameRequest = {
+ readonly program: HtmlProgram;
+ readonly frames: readonly number[];
+};
+
+/** PNG images in request order; the request owns their frame identities. */
+export type HtmlFrameImages = readonly BlobRef[];
+
+export function verifyHtmlFrameRequest(value: unknown): asserts value is HtmlFrameRequest {
+ if (!value || typeof value !== "object" || Array.isArray(value)
+ || Object.keys(value).some(key => !["program", "frames"].includes(key))) {
+ throw new Error("HTML frame request needs one program and frames");
+ }
+ const request = value as HtmlFrameRequest;
+ assertHtmlProgram(request.program);
+ if (!Array.isArray(request.frames) || request.frames.length === 0 || request.frames.some((frame, index) =>
+ !Number.isSafeInteger(frame) || frame < 0 || frame >= request.program.frameCount
+ || (index > 0 && frame <= request.frames[index - 1]!))) {
+ throw new Error(`Frames must be strictly increasing integers in [0, ${request.program.frameCount})`);
+ }
+}
+
+export function htmlFrameRequest(request: HtmlFrameRequest): CanonicalValue {
+ verifyHtmlFrameRequest(request);
+ return request as unknown as CanonicalValue;
+}
+
+export function verifyHtmlFrameImages(value: unknown): asserts value is HtmlFrameImages {
+ if (!Array.isArray(value) || value.length === 0 || value.some(blob => !blob || blob.kind !== "blob"
+ || !isResourceId(blob.resource) || blob.mediaType !== "image/png"
+ || !Number.isSafeInteger(blob.size) || blob.size <= 0)) {
+ throw new Error("HTML frame images must be PNG BlobRefs in request order");
+ }
+}
+
+export function verifyHtmlRasterRequest(value: unknown): asserts value is HtmlRasterRequest {
+ if (value === null || typeof value !== "object" || Array.isArray(value)
+ || Object.keys(value).some((key) => key !== "program" && key !== "range")) {
+ throw new Error("HTML raster request requires program and an optional range");
+ }
+ const request = value as HtmlRasterRequest;
+ assertHtmlProgram(request.program);
+ if (request.range !== undefined) verifyMediaFrameRange(request.range, request.program.frameCount);
+}
+
+export function htmlRasterRequest(program: HtmlProgram, options: { readonly range?: MediaFrameRange } = {}): CanonicalValue {
+ assertHtmlProgram(program);
+ if (options.range !== undefined) verifyMediaFrameRange(options.range, program.frameCount);
+ return { program, ...(options.range === undefined ? {} : { range: options.range }) };
+}
diff --git a/packages/hyperframes/src/fragment.ts b/packages/html-program/src/fragment.ts
similarity index 60%
rename from packages/hyperframes/src/fragment.ts
rename to packages/html-program/src/fragment.ts
index 7eaeea82..ff4b9e6a 100644
--- a/packages/hyperframes/src/fragment.ts
+++ b/packages/html-program/src/fragment.ts
@@ -1,32 +1,32 @@
import { compositionTypes } from "@hypit/composition";
import type { Composition } from "@hypit/composition";
-import { sealGraphFragment } from "@hypit/elaborator";
+import { sealGraphFragment } from "@hypit/author";
import { timelineTypes } from "@hypit/timeline";
-import { hyperframesProducers, hyperframesTypes } from "./manifest.js";
+import { htmlProgramProducers, htmlProgramTypes } 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.
+ * Compile one already assembled Composition into a HTML document.
* Film is intentionally absent: any package capable of producing Composition
* can use this ordinary downstream Fragment.
*/
-export const hyperframesDocumentFragment = sealGraphFragment({
+export const htmlProgramFragment = sealGraphFragment({
inputs: [
{ name: "composition", type: compositionTypes.composition },
{ name: "timeline", type: timelineTypes.timeline },
],
operations: [{
- id: "compile-document",
- producer: hyperframesProducers.compile,
+ id: "compile-program",
+ producer: htmlProgramProducers.compile,
inputs: { composition: input("composition"), timeline: input("timeline") },
- result: { kind: "output", name: "document" },
+ result: { kind: "output", name: "program" },
}],
exports: [{
- name: "document",
- type: hyperframesTypes.document,
- root: operation("compile-document"),
+ name: "program",
+ type: htmlProgramTypes.program,
+ root: operation("compile-program"),
}],
});
diff --git a/packages/hyperframes/src/frame-work.ts b/packages/html-program/src/frame-work.ts
similarity index 76%
rename from packages/hyperframes/src/frame-work.ts
rename to packages/html-program/src/frame-work.ts
index d52f2221..babffa66 100644
--- a/packages/hyperframes/src/frame-work.ts
+++ b/packages/html-program/src/frame-work.ts
@@ -1,59 +1,59 @@
-import type { HyperframesFrameSpan } from "./types.js";
+import type { HtmlFrameSpan } from "./types.js";
/**
- * Page-local absolute-frame work lookup shared by HyperFrames runtime features.
+ * Page-local absolute-frame work lookup shared by HTML renderer runtime features.
*
* The index deliberately knows only half-open frame spans, stable order and an
* opaque payload. Text, animation and media semantics remain with their own
* evaluators. Every render page derives and discards its own index.
*/
export const frameSelectionRuntime = String.raw`
-const hyperframesRequestedFrameSpans = (() => {
- const source = globalThis.__hyperframesRequestedFrameSpans;
+const htmlRequestedFrameSpans = (() => {
+ const source = globalThis.__htmlRequestedFrameSpans;
if (source === undefined) return null;
- if (!Array.isArray(source)) throw new Error('HyperFrames requested frame spans must be an array.');
+ if (!Array.isArray(source)) throw new Error('HTML renderer requested frame spans must be an array.');
let previousEnd = -1;
return Object.freeze(source.map((span) => {
if (!Array.isArray(span) || span.length !== 2) {
- throw new Error('HyperFrames requested frame span must be a [start, end) pair.');
+ throw new Error('HTML renderer requested frame span must be a [start, end) pair.');
}
const startFrame = Number(span[0]);
const endFrameExclusive = Number(span[1]);
if (!Number.isSafeInteger(startFrame) || !Number.isSafeInteger(endFrameExclusive)
|| startFrame < 0 || endFrameExclusive <= startFrame || startFrame < previousEnd) {
- throw new Error('HyperFrames requested frame spans must be ordered, disjoint and valid.');
+ throw new Error('HTML renderer requested frame spans must be ordered, disjoint and valid.');
}
previousEnd = endFrameExclusive;
return Object.freeze({ startFrame, endFrameExclusive });
}));
})();
-const hyperframesSelectionOverlaps = (startFrame, endFrameExclusive) => {
+const htmlSelectionOverlaps = (startFrame, endFrameExclusive) => {
if (!Number.isSafeInteger(startFrame) || !Number.isSafeInteger(endFrameExclusive)
|| startFrame < 0 || endFrameExclusive <= startFrame) {
- throw new Error('HyperFrames selection query span is invalid.');
+ throw new Error('HTML renderer selection query span is invalid.');
}
- if (hyperframesRequestedFrameSpans === null) return true;
+ if (htmlRequestedFrameSpans === null) return true;
let low = 0;
- let high = hyperframesRequestedFrameSpans.length;
+ let high = htmlRequestedFrameSpans.length;
while (low < high) {
const middle = (low + high) >>> 1;
- if (hyperframesRequestedFrameSpans[middle].endFrameExclusive <= startFrame) low = middle + 1;
+ if (htmlRequestedFrameSpans[middle].endFrameExclusive <= startFrame) low = middle + 1;
else high = middle;
}
- const candidate = hyperframesRequestedFrameSpans[low];
+ const candidate = htmlRequestedFrameSpans[low];
return candidate !== undefined && candidate.startFrame < endFrameExclusive;
};
`;
export const frameWorkIndexRuntime = String.raw`${frameSelectionRuntime}
-const hyperframesCreateFrameWorkIndex = (sourceEntries) => {
+const htmlCreateFrameWorkIndex = (sourceEntries) => {
const entries = sourceEntries.map((entry, serial) => {
const startFrame = Number(entry.startFrame);
const endFrameExclusive = Number(entry.endFrameExclusive);
const order = entry.order === undefined ? serial : Number(entry.order);
if (!Number.isSafeInteger(startFrame) || !Number.isSafeInteger(endFrameExclusive)
|| startFrame < 0 || endFrameExclusive <= startFrame || !Number.isSafeInteger(order)) {
- throw new Error('HyperFrames frame work has an invalid span or order.');
+ throw new Error('HTML renderer frame work has an invalid span or order.');
}
return Object.freeze({ startFrame, endFrameExclusive, order, serial, payload: entry.payload });
});
@@ -110,7 +110,7 @@ const hyperframesCreateFrameWorkIndex = (sourceEntries) => {
const ordered = (result) => result.sort((left, right) => left.order - right.order || left.serial - right.serial);
return Object.freeze({
at(frame) {
- if (!Number.isSafeInteger(frame) || frame < 0) throw new Error('HyperFrames frame work query is invalid.');
+ if (!Number.isSafeInteger(frame) || frame < 0) throw new Error('HTML renderer frame work query is invalid.');
const result = [];
collect(root, frame, result);
return ordered(result);
@@ -120,7 +120,7 @@ const hyperframesCreateFrameWorkIndex = (sourceEntries) => {
const endFrameExclusive = Number(span?.endFrameExclusive);
if (!Number.isSafeInteger(startFrame) || !Number.isSafeInteger(endFrameExclusive)
|| startFrame < 0 || endFrameExclusive <= startFrame) {
- throw new Error('HyperFrames frame work query span is invalid.');
+ throw new Error('HTML renderer frame work query span is invalid.');
}
const result = [];
collectOverlapping(root, { startFrame, endFrameExclusive }, result);
@@ -134,15 +134,15 @@ const hyperframesCreateFrameWorkIndex = (sourceEntries) => {
* only absolute frame spans; worker assignment and capture machinery remain
* private to the Provider.
*/
-export function hyperframesFrameSelectionPrelude(spans: readonly HyperframesFrameSpan[]): string {
+export function htmlFrameSelectionPrelude(spans: readonly HtmlFrameSpan[]): string {
let previousEnd = -1;
const encoded = spans.map((span) => {
if (!Number.isSafeInteger(span.startFrame) || !Number.isSafeInteger(span.endFrameExclusive)
|| span.startFrame < 0 || span.endFrameExclusive <= span.startFrame || span.startFrame < previousEnd) {
- throw new Error("HyperFrames requested frame spans must be ordered, disjoint and valid.");
+ throw new Error("HTML renderer requested frame spans must be ordered, disjoint and valid.");
}
previousEnd = span.endFrameExclusive;
return [span.startFrame, span.endFrameExclusive];
});
- return `Object.defineProperty(globalThis,"__hyperframesRequestedFrameSpans",{value:${JSON.stringify(encoded)},writable:false,configurable:false});`;
+ return `Object.defineProperty(globalThis,"__htmlRequestedFrameSpans",{value:${JSON.stringify(encoded)},writable:false,configurable:false});`;
}
diff --git a/packages/hyperframes/src/browser-program.ts b/packages/html-program/src/html-visual.ts
similarity index 67%
rename from packages/hyperframes/src/browser-program.ts
rename to packages/html-program/src/html-visual.ts
index fa8e7299..2e74d469 100644
--- a/packages/hyperframes/src/browser-program.ts
+++ b/packages/html-program/src/html-visual.ts
@@ -2,9 +2,9 @@ import { canonicalize } from "@hypit/protocol";
import type { BlobRef, CanonicalValue } from "@hypit/protocol";
import type { VisualProgramElement } from "@hypit/composition";
-export const BROWSER_PROGRAM_FORMAT = "hypit.browser-program@1" as const;
+export const HTML_VISUAL_FORMAT = "hypit.html-visual@1" as const;
-export type BrowserProgram = {
+export type HtmlVisual = {
/** HTML fragment. {{child-id}} inserts an owned VisualElement, including frame-sampled video. */
readonly html: string;
/** CSS in an @scope rooted at this program's element. */
@@ -14,33 +14,33 @@ export type BrowserProgram = {
readonly data?: CanonicalValue;
};
-export function browserProgram(value: BrowserProgram, artifacts: readonly BlobRef[] = []): VisualProgramElement["program"] {
- return { format: BROWSER_PROGRAM_FORMAT, payload: canonicalize(value) as VisualProgramElement["program"]["payload"], artifacts: [...artifacts] };
+export function htmlVisual(value: HtmlVisual, artifacts: readonly BlobRef[] = []): VisualProgramElement["program"] {
+ return { format: HTML_VISUAL_FORMAT, payload: canonicalize(value) as VisualProgramElement["program"]["payload"], artifacts: [...artifacts] };
}
-export function readBrowserProgram(program: VisualProgramElement["program"]): BrowserProgram {
- if (program.format !== BROWSER_PROGRAM_FORMAT) {
- throw new Error(`HyperFrames does not support visual program format ${program.format}.`);
+export function readHtmlVisual(program: VisualProgramElement["program"]): HtmlVisual {
+ if (program.format !== HTML_VISUAL_FORMAT) {
+ throw new Error(`HTML renderer does not support visual program format ${program.format}.`);
}
- const value = program.payload as unknown as BrowserProgram;
+ const value = program.payload as unknown as HtmlVisual;
if (value === null || typeof value !== "object" || typeof value.html !== "string"
|| (value.css !== undefined && typeof value.css !== "string")
|| (value.setup !== undefined && typeof value.setup !== "string")) {
- throw new Error("Browser program requires HTML and optional CSS and setup source.");
+ throw new Error("HTML visual requires HTML and optional CSS and setup source.");
}
return value;
}
-export function browserProgramHtml(program: BrowserProgram, children: ReadonlyMap<string, string>): string {
+export function htmlVisualHtml(program: HtmlVisual, children: ReadonlyMap<string, string>): string {
const used = new Set<string>();
const result = program.html.replace(/\{\{([^{}]+)\}\}/gu, (_match, name: string) => {
const child = children.get(name);
- if (child === undefined || used.has(name)) throw new Error(`Browser program slot ${name} is missing or repeated.`);
+ if (child === undefined || used.has(name)) throw new Error(`HTML visual slot ${name} is missing or repeated.`);
used.add(name);
return child;
});
for (const name of children.keys()) {
- if (!used.has(name)) throw new Error(`Browser program does not place owned child ${name}.`);
+ if (!used.has(name)) throw new Error(`HTML visual does not place owned child ${name}.`);
}
return result;
}
@@ -48,26 +48,26 @@ export function browserProgramHtml(program: BrowserProgram, children: ReadonlyMa
/** JSON is embedded as data, so author text cannot close the surrounding script element. */
const scriptJson = (value: unknown): string => JSON.stringify(value).replaceAll("<", "\\u003c");
-export function browserProgramScript(entries: readonly {
+export function htmlVisualScript(entries: readonly {
readonly id: string;
readonly startFrame: number;
readonly durationFrames: number;
- readonly program: BrowserProgram;
-}[], numerator: number, denominator: number): string {
+ readonly program: HtmlVisual;
+}[], _numerator: number, _denominator: number): string {
return `(() => {
- const fail = error => { window.__hypitBrowserProgramError = String(error?.stack || error); };
+ const fail = error => { window.__hypitHtmlVisualError = String(error?.stack || error); };
const entries = ${scriptJson(entries)}.filter(entry =>
- hyperframesSelectionOverlaps(entry.startFrame, entry.startFrame + entry.durationFrames));
+ htmlSelectionOverlaps(entry.startFrame, entry.startFrame + entry.durationFrames));
const renders = entries.map((entry, order) => {
const root = document.getElementById(entry.id);
try {
const render = entry.program.setup === undefined ? () => {} :
new Function('root', 'data', entry.program.setup)(root, entry.program.data);
- if (typeof render !== 'function') throw new Error('Browser program setup must return render(localFrame).');
+ if (typeof render !== 'function') throw new Error('HTML visual setup must return render(localFrame).');
return { ...entry, order, render, region: undefined };
} catch (error) { fail(error); return { ...entry, order, render: () => {}, region: undefined }; }
});
- const workIndex = hyperframesCreateFrameWorkIndex(renders.map(entry => ({
+ const workIndex = htmlCreateFrameWorkIndex(renders.map(entry => ({
startFrame: entry.startFrame,
endFrameExclusive: entry.startFrame + entry.durationFrames,
order: entry.order,
@@ -85,14 +85,13 @@ export function browserProgramScript(entries: readonly {
if (result != null && typeof result.then === 'function') {
// Observe a later rejection, but never let asynchronous drawing race frame capture.
Promise.resolve(result).catch(fail);
- throw new Error('Browser program render(localFrame) must be synchronous; prepare asynchronous resources before rendering.');
+ throw new Error('HTML visual render(localFrame) must be synchronous; prepare asynchronous resources before rendering.');
}
entry.region = region;
}
catch (error) { fail(error); }
};
- const apply = time => {
- const frame = Math.max(0, Math.round(Number(time || 0) * ${numerator} / ${denominator}));
+ const apply = frame => {
if (previousFrame === undefined) {
// Establish every compiler-owned root's boundary pose once. Later work
// is limited to active programs and spans crossed by an arbitrary seek.
@@ -112,6 +111,6 @@ export function browserProgramScript(entries: readonly {
previousFrame = frame;
};
apply(0);
- window.addEventListener('hf-seek', event => apply(event.detail?.time));
+ window.addEventListener('hypit-frame', event => apply(event.detail?.frame));
})();`;
}
diff --git a/packages/html-program/src/index.ts b/packages/html-program/src/index.ts
new file mode 100644
index 00000000..48a46c76
--- /dev/null
+++ b/packages/html-program/src/index.ts
@@ -0,0 +1,17 @@
+export { htmlProgramFragment } from "./fragment.js";
+export { htmlProgramComponent } from "./component.js";
+export { assertHtmlProgram, assertHtmlFrameIndex, assertHtmlFrameSpan, compileHtmlProgram, htmlProgramResourceUri, htmlProgramTime, materializeHtmlProgram, selectHtmlArtifacts } from "./document.js";
+export {
+ htmlProgramSchema,
+ htmlProgramCapabilities,
+ htmlProgramManifest,
+ htmlProgramModuleRef,
+ htmlProgramProducers,
+ htmlProgramTypes,
+} from "./manifest.js";
+export { htmlRasterRequest, verifyHtmlRasterRequest, htmlFrameRequest, verifyHtmlFrameRequest, verifyHtmlFrameImages } from "./execution.js";
+export type { HtmlRasterRequest, HtmlFrameRequest, HtmlFrameImages } from "./execution.js";
+export type * from "./types.js";
+export { htmlVisual, HTML_VISUAL_FORMAT } from "./html-visual.js";
+export type { HtmlVisual } from "./html-visual.js";
+export { htmlFrameSelectionPrelude } from "./frame-work.js";
diff --git a/packages/html-program/src/manifest.ts b/packages/html-program/src/manifest.ts
new file mode 100644
index 00000000..aa324af6
--- /dev/null
+++ b/packages/html-program/src/manifest.ts
@@ -0,0 +1,111 @@
+import { compositionDependency, compositionTypes, VISUAL_IR_V1 } from "@hypit/composition";
+import { compositableSurfaceSchema, mediaDependency, mediaTypes } from "@hypit/media";
+import type { CapabilityRef, ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
+import { timelineDependency, timelineTypes } from "@hypit/timeline";
+
+export const htmlProgramModuleRef = { name: "@hypit/html-program", version: "1" } as const;
+export const htmlProgramTypes = {
+ program: { module: htmlProgramModuleRef, name: "HtmlProgram" },
+ frameImages: { module: htmlProgramModuleRef, name: "FrameImages" },
+} satisfies Record<string, TypeRef>;
+export const htmlProgramCapabilities = {
+ rasterizeVisual: { module: htmlProgramModuleRef, name: "rasterize-visual" },
+ rasterizeFrames: { module: htmlProgramModuleRef, name: "rasterize-frames" },
+} satisfies Record<string, CapabilityRef>;
+export const htmlProgramProducers = {
+ compile: { module: htmlProgramModuleRef, name: "compile-composition" },
+ requestVisual: { module: htmlProgramModuleRef, name: "request-visual" },
+ requestVisualRange: { module: htmlProgramModuleRef, name: "request-visual-range" },
+} 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 htmlProgramSchema: 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: {
+ artifact: { schema: { kind: "object", fields: {
+ kind: { schema: { kind: "literal", value: "blob" } },
+ resource: { schema: resource },
+ size: { schema: nonNegativeInteger },
+ mediaType: { schema: { kind: "string", minLength: 1 } },
+ } } },
+ usage: { schema: { kind: "oneOf", variants: [
+ { kind: "object", fields: { kind: { schema: { kind: "literal", value: "always" } } } },
+ { kind: "object", fields: {
+ kind: { schema: { kind: "literal", value: "frames" } },
+ spans: { schema: { kind: "array", minItems: 1, items: { kind: "object", fields: {
+ startFrame: { schema: nonNegativeInteger },
+ endFrameExclusive: { schema: positiveInteger },
+ } } } },
+ } },
+ ] } },
+ },
+ } } },
+ surfaces: { schema: { kind: "array", items: compositableSurfaceSchema } },
+ frameSources: { schema: { kind: "array", items: { kind: "object", fields: {
+ id: { schema: { kind: "string", minLength: 1 } },
+ resource: { schema: resource },
+ startFrame: { schema: nonNegativeInteger },
+ endFrameExclusive: { schema: positiveInteger },
+ sourceFrame: { schema: { kind: "object", fields: {
+ numerator: { schema: nonNegativeInteger }, denominator: { schema: positiveInteger },
+ } } },
+ sourceRate: { schema: { kind: "object", fields: {
+ numerator: { schema: { kind: "number", integer: true } }, denominator: { schema: positiveInteger },
+ } } },
+ sourceFrameRate: { schema: { kind: "object", fields: {
+ numerator: { schema: positiveInteger }, denominator: { schema: positiveInteger },
+ } } },
+ } } } },
+ html: { schema: { kind: "string", minLength: 1 } },
+ },
+};
+
+export const htmlProgramManifest: ModuleManifest = {
+ format: "hypit.module@1",
+ name: htmlProgramModuleRef.name,
+ version: htmlProgramModuleRef.version,
+ dependencies: [compositionDependency, mediaDependency, timelineDependency],
+ types: [{ name: htmlProgramTypes.program.name }, { name: htmlProgramTypes.frameImages.name }],
+ capabilities: [
+ { name: htmlProgramCapabilities.rasterizeVisual.name, returns: mediaTypes.timelineVisual },
+ { name: htmlProgramCapabilities.rasterizeFrames.name, returns: htmlProgramTypes.frameImages },
+ ],
+ producers: [{
+ name: htmlProgramProducers.compile.name,
+ inputs: [
+ { name: "composition", type: compositionTypes.composition },
+ { name: "timeline", type: timelineTypes.timeline },
+ ],
+ outputs: [{ name: "program", type: htmlProgramTypes.program }],
+ needs: [],
+ }, {
+ name: htmlProgramProducers.requestVisual.name,
+ inputs: [{ name: "program", type: htmlProgramTypes.program }], outputs: [],
+ needs: [{ name: "visual", capability: htmlProgramCapabilities.rasterizeVisual, returns: mediaTypes.timelineVisual }],
+ }, {
+ name: htmlProgramProducers.requestVisualRange.name,
+ inputs: [{ name: "program", type: htmlProgramTypes.program }, { name: "range", type: mediaTypes.frameRange }], outputs: [],
+ needs: [{ name: "visual", capability: htmlProgramCapabilities.rasterizeVisual, returns: mediaTypes.timelineVisual }],
+ }],
+};
diff --git a/packages/hyperframes/src/text.ts b/packages/html-program/src/text.ts
similarity index 94%
rename from packages/hyperframes/src/text.ts
rename to packages/html-program/src/text.ts
index 7d43042b..21643e86 100644
--- a/packages/hyperframes/src/text.ts
+++ b/packages/html-program/src/text.ts
@@ -81,7 +81,7 @@ function typographyCss(
const decorations = typography.decorations;
const decoration = decorations[0];
if (decorations.some((item) => item.paint.kind !== "solid")) {
- throw new Error("HyperFrames Text decorations currently require solid Paint.");
+ throw new Error("HTML renderer Text decorations currently require solid Paint.");
}
if (decoration !== undefined && decorations.some((item) =>
item.style !== decoration.style
@@ -91,7 +91,7 @@ function typographyCss(
|| item.thicknessPx !== decoration.thicknessPx
|| item.offsetPx !== decoration.offsetPx
|| item.skipInk !== decoration.skipInk)) {
- throw new Error("HyperFrames Text decorations on one run must share Paint and metric settings.");
+ throw new Error("HTML renderer Text decorations on one run must share Paint and metric settings.");
}
return [
...exactFontCss(typography.fonts, exactFontFamily),
@@ -204,7 +204,7 @@ function glyphFilterDefinition(
): string {
const color = solidPaint(paint.paint);
if (color === undefined) {
- throw new Error(`HyperFrames ${paint.kind} Text Paint requires solid color; materialize gradient ${paint.kind} as a Surface.`);
+ throw new Error(`HTML renderer ${paint.kind} Text Paint requires solid color; materialize gradient ${paint.kind} as a Surface.`);
}
const id = glyphFilterId(paint, context);
const flood = `<feFlood flood-color="${context.escape(color)}" result="paint"/>`;
@@ -279,7 +279,7 @@ function glyphLayerCss(
// outside without passing the descender through an SVG filter input box first.
const color = solidPaint(paint.paint);
if (color === undefined) {
- throw new Error("HyperFrames outside Text stroke requires solid color; materialize a gradient stroke as a Surface.");
+ throw new Error("HTML renderer outside Text stroke requires solid color; materialize a gradient stroke as a Surface.");
}
return [
...common,
@@ -376,7 +376,7 @@ function boxCss(
}
if (decoration.border !== undefined) {
const color = solidPaint(decoration.border.paint);
- if (color === undefined) throw new Error("HyperFrames Text Box borders require solid Paint.");
+ if (color === undefined) throw new Error("HTML renderer Text Box borders require solid Paint.");
result.push(
`border-style:${decoration.border.style}`,
`border-color:${color}`,
@@ -389,7 +389,7 @@ function boxCss(
);
for (const shadow of decoration.shadows) {
const color = solidPaint(shadow.paint);
- if (color === undefined) throw new Error("HyperFrames Text Box shadows require solid Paint.");
+ if (color === undefined) throw new Error("HTML renderer Text Box shadows require solid Paint.");
shadows.push(`${number(shadow.offsetX)}px ${number(shadow.offsetY)}px ${number(shadow.blurPx)}px ${number(shadow.spreadPx)}px ${color}`);
}
}
@@ -474,7 +474,7 @@ function unitAnimationCss(
_context: TextRenderContext,
): string[] {
// Unit-local animation is installed once as typed WAAPI keyframes after
- // exact-font layout. HyperFrames owns the frame clock and seeks those
+ // exact-font layout. HTML renderer owns the frame clock and seeks those
// persistent animations; no renderer script samples wall time.
return [];
}
@@ -712,7 +712,7 @@ function pathPaintLayerCount(element: VisualPathTextElement): number {
const inspect = (paints: readonly VisualTextPaintLayer[] | undefined): void => {
for (const paint of paints ?? []) {
if (paint.kind === "box") {
- throw new Error("HyperFrames Path Text requires Box Paint to be materialized by its owning package.");
+ throw new Error("HTML renderer Path Text requires Box Paint to be materialized by its owning package.");
}
}
count = Math.max(count, glyphPaintLayers(paints ?? []).length);
@@ -836,7 +836,7 @@ const svmlTextRootSelected = (root) => {
|| startFrame < 0 || durationFrames <= 0 || !Number.isSafeInteger(startFrame + durationFrames)) {
throw new Error('Invalid terminal Text Present span.');
}
- return hyperframesSelectionOverlaps(startFrame, startFrame + durationFrames);
+ return htmlSelectionOverlaps(startFrame, startFrame + durationFrames);
};
const svmlSelectedTextElements = (selector) => [...document.querySelectorAll(selector)].filter((element) => {
const root = element.closest('[data-hypit-text-clock]');
@@ -875,15 +875,13 @@ const svmlUpdateStaticTextPathPlacements = () => {
textPath.setAttribute('startOffset', String(data.align === 'start' ? start : data.align === 'end' ? end : (start + end) / 2));
}
};
-const svmlUpdateTextPathMargins = (time) => {
+const svmlUpdateTextPathMargins = (programFrame) => {
for (const path of svmlSelectedTextElements('[data-hypit-text-path-margin]')) {
const data = JSON.parse(path.getAttribute('data-hypit-text-path-margin'));
const frames = data.keyframes;
- // HyperFrames may reach the same source frame through an incremental seek
- // or a fresh worker seek. Quantize the absolute clock back to the authored
- // integer frame before evaluating package-owned motion so both routes are
- // byte-identical.
- const local = Math.round(time * data.numerator / data.denominator - data.startFrame);
+ // The page ABI already supplies the authored integer frame; no seconds
+ // conversion or worker history participates in package-owned motion.
+ const local = programFrame - data.startFrame;
let value = frames[0].startMarginPx;
if (local >= frames[frames.length - 1].atFrame) value = frames[frames.length - 1].startMarginPx;
else {
@@ -958,12 +956,11 @@ const svmlTextSequenceClock = (sequence, rank, frame) => {
return (frame - start) % sequence.unitDurationFrames;
};
const svmlTextUnitSelector = '[data-hypit-text-unit-paragraph],[data-hypit-text-unit-run],[data-hypit-text-unit-word],[data-hypit-text-unit-grapheme]';
-let svmlTextAnimationIndex = hyperframesCreateFrameWorkIndex([]);
+let svmlTextAnimationIndex = htmlCreateFrameWorkIndex([]);
let svmlTextAnimationFrameRate;
const svmlPrepareTextRootApplications = (prepared) => {
if (prepared.units !== undefined) return prepared.units;
const sequences = JSON.parse(prepared.encodedSequences || '[]').map(svmlTextPrepareSequence);
- const nativeAnimate = Element.prototype.__hfOriginalAnimate;
prepared.units = [...prepared.root.querySelectorAll(svmlTextUnitSelector)].map((unit) => {
const applications = [];
for (const sequence of sequences) {
@@ -972,9 +969,7 @@ const svmlPrepareTextRootApplications = (prepared) => {
const index = Number(unit.getAttribute(attribute));
const rank = Number.isSafeInteger(index) ? svmlTextSequenceRank(sequence, index) : null;
if (rank === null) continue;
- const animation = typeof nativeAnimate === 'function'
- ? nativeAnimate.call(unit, sequence.nativeKeyframes, { duration: sequence.unitDurationFrames, fill: 'both', iterations: 1 })
- : unit.animate(sequence.nativeKeyframes, { duration: sequence.unitDurationFrames, fill: 'both', iterations: 1 });
+ const animation = unit.animate(sequence.nativeKeyframes, { duration: sequence.unitDurationFrames, fill: 'both', iterations: 1 });
animation.pause();
animation.currentTime = 0;
applications.push({ sequence, rank, animation });
@@ -1009,11 +1004,10 @@ const svmlPrepareTextUnitAnimations = () => {
},
};
});
- svmlTextAnimationIndex = hyperframesCreateFrameWorkIndex(work);
+ svmlTextAnimationIndex = htmlCreateFrameWorkIndex(work);
};
-const svmlSeekTextUnitAnimations = (time) => {
+const svmlSeekTextUnitAnimations = (programFrame) => {
if (svmlTextAnimationFrameRate === undefined) return;
- const programFrame = Math.max(0, Math.round(time * svmlTextAnimationFrameRate.numerator / svmlTextAnimationFrameRate.denominator));
for (const work of svmlTextAnimationIndex.at(programFrame)) {
const units = svmlPrepareTextRootApplications(work.payload);
const localFrame = programFrame - work.startFrame;
@@ -1026,36 +1020,20 @@ const svmlSeekTextUnitAnimations = (time) => {
}
}
};
-const svmlTextComposition = document.querySelector('[data-composition-id]');
-if (!svmlTextComposition) throw new Error('Terminal Text could not resolve the containing HyperFrames composition.');
-const svmlTextCompositionId = svmlTextComposition.getAttribute('data-composition-id');
-if (!svmlTextCompositionId) throw new Error('Terminal Text composition identity is empty.');
-let svmlTextAbsoluteTime = 0;
+let svmlTextAbsoluteFrame = 0;
let svmlTextReady = false;
-const svmlTextTimeline = {
- pause() { return this; },
- seek(time) { return this.totalTime(time); },
- totalTime(time) {
- if (time === undefined) return svmlTextAbsoluteTime;
- // Register and remember seeks synchronously, even while exact fonts are
- // still loading. A worker may begin at any frame; once layout becomes
- // ready the latest requested absolute frame is evaluated exactly once.
- svmlTextAbsoluteTime = Math.max(0, Number(time) || 0);
+const svmlApplyTextFrame = (frame) => {
+ svmlTextAbsoluteFrame = Math.max(0, Number(frame) || 0);
if (svmlTextReady) {
- svmlSeekTextUnitAnimations(svmlTextAbsoluteTime);
- svmlUpdateTextPathMargins(svmlTextAbsoluteTime);
+ svmlSeekTextUnitAnimations(svmlTextAbsoluteFrame);
+ svmlUpdateTextPathMargins(svmlTextAbsoluteFrame);
// Attribute changes on SVG text paths and browser text layout are
// sampled synchronously for the exact authored frame. Do not wait for a
- // requestAnimationFrame from HyperFrames' seek barrier: capture is
+ // requestAnimationFrame from HTML renderer' seek barrier: capture is
// paused behind that barrier, so doing so would deadlock both clocks.
document.documentElement.getBoundingClientRect();
}
- return this;
- },
};
-window.__timelines = window.__timelines || {};
-window.__timelines[svmlTextCompositionId] = svmlTextTimeline;
-if (typeof window.__hfForceTimelineRebind === 'function') window.__hfForceTimelineRebind();
const svmlTextLayoutReady = document.fonts.ready.then(() => {
svmlUpdateStaticTextPathPlacements();
svmlUpdateUprightTextPaths();
@@ -1194,11 +1172,12 @@ const svmlTextLayoutReady = document.fonts.ready.then(() => {
}
svmlPrepareTextUnitAnimations();
svmlTextReady = true;
- svmlTextTimeline.totalTime(svmlTextAbsoluteTime);
+ svmlApplyTextFrame(svmlTextAbsoluteFrame);
});
-window.addEventListener('hf-seek', (event) => {
+window.addEventListener('hypit-frame', (event) => {
if (!event?.detail || typeof event.detail.waitUntil !== 'function') return;
- // HyperFrames requires waitUntil to be registered synchronously while the
+ svmlApplyTextFrame(event.detail.frame);
+ // HTML renderer requires waitUntil to be registered synchronously while the
// seek event is dispatched. The Promise itself waits for exact fonts and
// deterministic static layout validation. Per-frame sampling is synchronous
// inside the registered timeline and forces layout before it returns. A
diff --git a/packages/hyperframes/src/types.ts b/packages/html-program/src/types.ts
similarity index 52%
rename from packages/hyperframes/src/types.ts
rename to packages/html-program/src/types.ts
index 7e89087f..b143b6b1 100644
--- a/packages/hyperframes/src/types.ts
+++ b/packages/html-program/src/types.ts
@@ -1,8 +1,9 @@
import type { BlobRef, ResourceId } from "@hypit/protocol";
import type { CompositableSurfaceRef } from "@hypit/media";
+import { VISUAL_IR_V1 } from "@hypit/composition";
-export type HyperframesFrameDomain = {
+export type HtmlFrameDomain = {
readonly frameRate: {
readonly numerator: number;
readonly denominator: number;
@@ -11,42 +12,53 @@ export type HyperframesFrameDomain = {
readonly frameCount: number;
};
-export type HyperframesCanvas = {
+export type HtmlCanvas = {
readonly width: number;
readonly height: number;
};
-export type HyperframesArtifactUsage =
+export type HtmlArtifactUsage =
| { readonly kind: "always" }
| {
readonly kind: "frames";
/** Ordered, disjoint absolute half-open spans where this Artifact can be observed. */
- readonly spans: readonly HyperframesFrameSpan[];
+ readonly spans: readonly HtmlFrameSpan[];
};
/** One byte dependency and the compiler's conservative proof of when it can be observed. */
-export type HyperframesArtifact = {
+export type HtmlArtifact = {
readonly artifact: BlobRef;
- readonly usage: HyperframesArtifactUsage;
+ readonly usage: HtmlArtifactUsage;
};
-/** Portable input to a local or remote HyperFrames renderer. */
-export type HyperframesDocument = HyperframesFrameDomain & {
+export type HtmlFrameSource = HtmlFrameSpan & {
+ /** Document-local DOM identity of the compiled source occurrence. */
+ readonly id: string;
+ /** Artifact resource whose exact decoded frames feed this occurrence. */
+ readonly resource: ResourceId;
+ readonly sourceFrame: { readonly numerator: number; readonly denominator: number };
+ readonly sourceRate: { readonly numerator: number; readonly denominator: number };
+ readonly sourceFrameRate: { readonly numerator: number; readonly denominator: number };
+};
+
+/** Portable, frame-addressed HTML visual program. */
+export type HtmlProgram = HtmlFrameDomain & {
readonly visualIr: typeof VISUAL_IR_V1;
- readonly canvas: HyperframesCanvas;
+ readonly canvas: HtmlCanvas;
/** Every byte resource referenced by the HTML template, with its conservative temporal usage. */
- readonly artifacts: readonly HyperframesArtifact[];
- /** Typed Surface dependencies that a Runtime must verify before rendering. */
+ readonly artifacts: readonly HtmlArtifact[];
+ /** Typed Surface dependencies that a Runtime must verify before rasterization. */
readonly surfaces: readonly CompositableSurfaceRef[];
+ /** Exact source-frame functions emitted alongside HTML; execution never parses them back out of markup. */
+ readonly frameSources: readonly HtmlFrameSource[];
/** Media URLs remain hypit-resource:// placeholders until a Runtime materializes them. */
readonly html: string;
};
/** A half-open interval on the document frame clock, also used for local worker partitions. */
-export type HyperframesFrameSpan = {
+export type HtmlFrameSpan = {
readonly startFrame: number;
readonly endFrameExclusive: number;
};
export type ResourceUrlResolver = (artifact: BlobRef) => string;
-import { VISUAL_IR_V1 } from "@hypit/visual-ir";
diff --git a/packages/hyperframes/src/visibility.ts b/packages/html-program/src/visibility.ts
similarity index 67%
rename from packages/hyperframes/src/visibility.ts
rename to packages/html-program/src/visibility.ts
index 8f3f4a0d..59aa4597 100644
--- a/packages/hyperframes/src/visibility.ts
+++ b/packages/html-program/src/visibility.ts
@@ -1,13 +1,13 @@
/** Page-private Present visibility. The shared index owns only interval lookup. */
-export function presentationVisibilityScript(numerator: number, denominator: number): string {
+export function presentationVisibilityScript(_numerator: number, _denominator: number): string {
return `(() => {
const entries = [...document.querySelectorAll('[data-hypit-visibility]')].map((element, order) => ({
element,
order,
spans: JSON.parse(element.dataset.hypitVisibility),
}));
- const workIndex = hyperframesCreateFrameWorkIndex(entries.flatMap(entry => entry.spans
- .filter(span => hyperframesSelectionOverlaps(span.startFrame, span.endFrameExclusive)).map(span => ({
+ const workIndex = htmlCreateFrameWorkIndex(entries.flatMap(entry => entry.spans
+ .filter(span => htmlSelectionOverlaps(span.startFrame, span.endFrameExclusive)).map(span => ({
startFrame: span.startFrame,
endFrameExclusive: span.endFrameExclusive,
order: entry.order,
@@ -15,8 +15,7 @@ export function presentationVisibilityScript(numerator: number, denominator: num
}))));
let visible = new Set();
for (const entry of entries) entry.element.style.opacity = '0';
- const apply = time => {
- const frame = Math.max(0, Math.round(Number(time || 0) * ${numerator} / ${denominator}));
+ const apply = frame => {
const next = new Set(workIndex.at(frame).map(work => work.payload));
// A presentation mask controls painting, not layout or animation existence.
// Only roots whose absolute visibility changed need a DOM write.
@@ -25,6 +24,6 @@ export function presentationVisibilityScript(numerator: number, denominator: num
visible = next;
};
apply(0);
- window.addEventListener('hf-seek', event => apply(event.detail?.time));
+ window.addEventListener('hypit-frame', event => apply(event.detail?.frame));
})();`;
}
diff --git a/packages/hyperframes/test/capture-scope.test.ts b/packages/html-program/test/capture-scope.test.ts
similarity index 93%
rename from packages/hyperframes/test/capture-scope.test.ts
rename to packages/html-program/test/capture-scope.test.ts
index 359c8fe2..a3c5cb2d 100644
--- a/packages/hyperframes/test/capture-scope.test.ts
+++ b/packages/html-program/test/capture-scope.test.ts
@@ -4,7 +4,7 @@ import test from "node:test";
import { parseHTML } from "linkedom";
import { presentationCaptureScopeRuntime } from "../src/capture-scope.js";
-import { frameSelectionRuntime, hyperframesFrameSelectionPrelude } from "../src/frame-work.js";
+import { frameSelectionRuntime, htmlFrameSelectionPrelude } from "../src/frame-work.js";
test("compiled capture scope retains selected roots and makes unrelated media inert", () => {
const { document } = parseHTML(`<!doctype html><body>
@@ -24,7 +24,7 @@ test("compiled capture scope retains selected roots and makes unrelated media in
const earlyVideo = document.getElementById("early-video")!;
const earlySvg = document.getElementById("early-svg")!;
const context: { document: Document; __hypitCaptureRoots?: readonly Element[] } = { document };
- runInNewContext(`${hyperframesFrameSelectionPrelude([{ startFrame: 100, endFrameExclusive: 101 }])}
+ runInNewContext(`${htmlFrameSelectionPrelude([{ startFrame: 100, endFrameExclusive: 101 }])}
${frameSelectionRuntime}\n${presentationCaptureScopeRuntime}`, context);
assert.deepEqual(JSON.parse(JSON.stringify(context.__hypitCaptureRoots?.map(root => root.id))), ["definitions", "selected"]);
@@ -52,7 +52,7 @@ test("compiled capture scope removes unselected Present descendants from generic
</body>`);
const before = document.querySelectorAll("*").length;
const context: { document: Document; __hypitCaptureRoots?: readonly Element[] } = { document };
- runInNewContext(`${hyperframesFrameSelectionPrelude([{ startFrame: 0, endFrameExclusive: 1 }])}
+ runInNewContext(`${htmlFrameSelectionPrelude([{ startFrame: 0, endFrameExclusive: 1 }])}
${frameSelectionRuntime}\n${presentationCaptureScopeRuntime}`, context);
assert.ok(before >= 400);
diff --git a/packages/hyperframes/test/document.test.ts b/packages/html-program/test/document.test.ts
similarity index 81%
rename from packages/hyperframes/test/document.test.ts
rename to packages/html-program/test/document.test.ts
index a1fb4134..4af0c334 100644
--- a/packages/hyperframes/test/document.test.ts
+++ b/packages/html-program/test/document.test.ts
@@ -1,22 +1,22 @@
import {
- assertHyperframesDocument,
- assertHyperframesFrameIndex,
- assertHyperframesFrameSpan,
- compileHyperframesDocument,
- hyperframesTime,
- materializeHyperframesHtml,
-} from "@hypit/hyperframes";
+ assertHtmlProgram,
+ assertHtmlFrameIndex,
+ assertHtmlFrameSpan,
+ compileHtmlProgram,
+ htmlProgramTime,
+ materializeHtmlProgram,
+} from "@hypit/html-program";
import type { FontArtifactRef } from "@hypit/media";
import { sealTimeline } from "@hypit/timeline";
import { sealAudioTrack, sealComposition, sealVisualTrack } from "@hypit/composition";
import type { Track } from "@hypit/composition";
-import { VISUAL_IR_V1 } from "@hypit/visual-ir";
+import { VISUAL_IR_V1 } from "@hypit/composition";
import assert from "node:assert/strict";
import test from "node:test";
import { fixtureResource } from "../../../test/fixture-resource.js";
const fixtureFont: FontArtifactRef = {
- sources: [{ artifact: { kind: "blob", resource: fixtureResource("hyperframes:fixture-font"), size: 1_024, mediaType: "font/woff2" } }],
+ sources: [{ artifact: { kind: "blob", resource: fixtureResource("html-program:fixture-font"), size: 1_024, mediaType: "font/woff2" } }],
weight: 700,
style: "normal",
};
@@ -26,13 +26,13 @@ function fixture() {
});
const picture = {
kind: "blob" as const,
- resource: fixtureResource("hyperframes:picture"),
+ resource: fixtureResource("html-program:picture"),
size: 10,
mediaType: "image/png",
};
const sound = {
kind: "blob" as const,
- resource: fixtureResource("hyperframes:sound"),
+ resource: fixtureResource("html-program:sound"),
size: 20,
mediaType: "audio/wav",
};
@@ -96,10 +96,10 @@ function fixture() {
return { composition, picture, sound, timeline };
}
-test("HyperFrames flattens generic peer visual Track Presents without absorbing audio rendering", () => {
+test("HTML renderer flattens generic peer visual Track Presents without absorbing audio rendering", () => {
const { composition, picture, sound, timeline } = fixture();
- const document = compileHyperframesDocument(composition, timeline);
- assert.doesNotThrow(() => assertHyperframesDocument(document));
+ const document = compileHtmlProgram(composition, timeline);
+ assert.doesNotThrow(() => assertHtmlProgram(document));
assert.equal(document.visualIr, VISUAL_IR_V1);
assert.deepEqual(new Set(document.artifacts.map(({ artifact }) => artifact.resource)),
new Set([picture.resource, fixtureFont.sources[0]!.artifact.resource]));
@@ -111,7 +111,7 @@ test("HyperFrames flattens generic peer visual Track Presents without absorbing
assert.doesNotMatch(document.html, /<img\b[^>]*\ssrc=/u,
"compiler-owned images stay inert until the page applies its render selection");
assert.ok(document.html.indexOf('data-hypit-track-id="lower"') < document.html.indexOf('data-hypit-track-id="upper"'));
- assert.equal((document.html.match(/class="clip hypit-visual-present"/gu) ?? []).length, 2);
+ assert.equal((document.html.match(/class="hypit-visual-present"/gu) ?? []).length, 2);
assert.doesNotMatch(document.html, /<audio/u);
assert.doesNotMatch(document.html, new RegExp(sound.resource, "u"));
assert.doesNotMatch(document.html, /isolation:isolate|hypit-visual-track/u);
@@ -149,7 +149,7 @@ test("equal-z Presents use stable Track identity and Track-local order", () => {
],
});
- const html = compileHyperframesDocument(composition, timeline).html;
+ const html = compileHtmlProgram(composition, timeline).html;
const a = html.indexOf('data-hypit-present-id="a"');
const first = html.indexOf('data-hypit-present-id="b-first"');
const second = html.indexOf('data-hypit-present-id="b-second"');
@@ -168,9 +168,9 @@ test("shared glyph filter definitions live outside temporal Present capture root
{ kind: "glow", paint: { kind: "solid", color: "#ff00ff" }, blurPx: 4, spreadPx: 1 },
{ kind: "fill", paint: { kind: "solid", color: "#ffffff" } },
] });
- const html = compileHyperframesDocument(changed, timeline).html;
+ const html = compileHtmlProgram(changed, timeline).html;
const definitions = html.indexOf("data-hypit-document-definitions");
- const present = html.indexOf('class="clip hypit-visual-present"');
+ const present = html.indexOf('class="hypit-visual-present"');
assert.ok(definitions >= 0 && definitions < present);
assert.equal((html.match(/<filter id="hypit-/gu) ?? []).length, 1);
assert.equal((html.match(/filter:url\(#hypit-/gu) ?? []).length, 1);
@@ -266,7 +266,7 @@ test("Text shrink preserves authored hug sizing and trims metrics inside the con
],
}],
});
- const document = compileHyperframesDocument(sealComposition({
+ const document = compileHtmlProgram(sealComposition({
id: "text-boxes",
canvas: { width: 720, height: 1280, clearColor: "#000000" },
tracks: [track],
@@ -282,9 +282,9 @@ test("Text shrink preserves authored hug sizing and trims metrics inside the con
test("visual Artifact placeholders are materialized only by the Runtime boundary", () => {
const { composition, picture, sound, timeline } = fixture();
- const document = compileHyperframesDocument(composition, timeline);
+ const document = compileHtmlProgram(composition, timeline);
assert.match(document.html, /hypit-resource:\/\/res_/u);
- const resolved = materializeHyperframesHtml(document,
+ const resolved = materializeHtmlProgram(document,
(artifact) => `https://assets.example/${artifact.resource}?x=1&y=2`);
assert.doesNotMatch(resolved, /hypit-resource:\/\//u);
assert.match(resolved, new RegExp(`https://assets\\.example/${picture.resource}\\?x=1&amp;y=2`, "u"));
@@ -292,27 +292,28 @@ test("visual Artifact placeholders are materialized only by the Runtime boundary
assert.equal(document.html.includes("assets.example"), false, "materialization must not mutate the compiled document");
});
-test("HyperframesDocument carries render facts while its Record binds integrity", () => {
+test("HtmlProgram carries render facts while its Record binds integrity", () => {
const { composition, timeline } = fixture();
- const document = compileHyperframesDocument(composition, timeline);
+ const document = compileHtmlProgram(composition, timeline);
assert.equal("digest" in document, false);
assert.deepEqual(document.frameRate, { numerator: 30_000, denominator: 1_001 });
assert.equal(document.frameCount, 30);
assert.deepEqual(document.canvas, { width: 1080, height: 1920 });
- assert.match(document.html, /data-fps="30000\/1001"/u);
+ assert.match(document.html, /data-hypit-frame-numerator="30000"/u);
+ assert.match(document.html, /data-hypit-frame-denominator="1001"/u);
assert.match(document.html, /data-hypit-frame-count="30"/u);
- assert.equal(hyperframesTime.frameSeconds(30, 30_000, 1_001), "1.001");
- assert.equal(hyperframesTime.fpsDecimal(30_000, 1_001), "29.970029970029");
+ assert.equal(htmlProgramTime.frameSeconds(30, 30_000, 1_001), "1.001");
+ assert.equal(htmlProgramTime.fpsDecimal(30_000, 1_001), "29.970029970029");
});
test("any legal frame and Provider-owned chunk can be addressed without traversing earlier frames", () => {
const fixtureValue = fixture();
- const document = compileHyperframesDocument(fixtureValue.composition, fixtureValue.timeline);
- assert.doesNotThrow(() => assertHyperframesFrameIndex(document, 0));
- assert.doesNotThrow(() => assertHyperframesFrameIndex(document, 17));
- assert.doesNotThrow(() => assertHyperframesFrameIndex(document, 29));
- assert.throws(() => assertHyperframesFrameIndex(document, -1), /outside/u);
- assert.throws(() => assertHyperframesFrameIndex(document, 30), /outside/u);
+ const document = compileHtmlProgram(fixtureValue.composition, fixtureValue.timeline);
+ assert.doesNotThrow(() => assertHtmlFrameIndex(document, 0));
+ assert.doesNotThrow(() => assertHtmlFrameIndex(document, 17));
+ assert.doesNotThrow(() => assertHtmlFrameIndex(document, 29));
+ assert.throws(() => assertHtmlFrameIndex(document, -1), /outside/u);
+ assert.throws(() => assertHtmlFrameIndex(document, 30), /outside/u);
const chunks = [
{ startFrame: 0, endFrameExclusive: 7 },
@@ -321,17 +322,17 @@ test("any legal frame and Provider-owned chunk can be addressed without traversi
{ startFrame: 21, endFrameExclusive: 28 },
{ startFrame: 28, endFrameExclusive: 30 },
];
- for (const chunk of chunks) assert.doesNotThrow(() => assertHyperframesFrameSpan(document, chunk));
+ for (const chunk of chunks) assert.doesNotThrow(() => assertHtmlFrameSpan(document, chunk));
assert.equal(chunks[0]?.startFrame, 0);
assert.equal(chunks.at(-1)?.endFrameExclusive, document.frameCount);
assert.equal(chunks.reduce((frames, chunk) => frames + chunk.endFrameExclusive - chunk.startFrame, 0), document.frameCount);
assert.throws(
- () => assertHyperframesFrameSpan(document, { startFrame: 29, endFrameExclusive: 31 }),
+ () => assertHtmlFrameSpan(document, { startFrame: 29, endFrameExclusive: 31 }),
/outside/u,
);
});
-test("HyperFrames emits compact absolute-frame animation without creating a Track stacking context", async () => {
+test("HTML renderer emits compact absolute-frame animation without creating a Track stacking context", async () => {
const { composition, timeline } = fixture();
const lower = composition.tracks.find((track) => track.id === "lower");
assert(lower?.kind === "visual");
@@ -352,7 +353,7 @@ test("HyperFrames emits compact absolute-frame animation without creating a Trac
}],
}],
});
- const document = compileHyperframesDocument(sealComposition({
+ const document = compileHtmlProgram(sealComposition({
...composition,
tracks: composition.tracks.map((track) => track.id === "lower" ? animated : track),
}), timeline);
@@ -360,20 +361,20 @@ test("HyperFrames emits compact absolute-frame animation without creating a Trac
assert.match(document.html, /33\.333333333%\{opacity:1;transform:translateY\(0%\)/u);
assert.match(document.html, /animation-duration:1\.001s/u);
assert.match(document.html, /100%\{opacity:1;transform:translateY\(0%\)\}/u);
- assert.match(document.html, /hyperframesCreateFrameWorkIndex/u);
+ assert.match(document.html, /htmlCreateFrameWorkIndex/u);
assert.match(document.html, /new Animation\(new KeyframeEffect\(/u);
assert.doesNotMatch(document.html, /const frames = \[\]/u, "poses are evaluated per seek, not tabulated per Present frame");
- assert.doesNotMatch(document.html, /\.animate\(/u, "HyperFrames' waapi adapter tracks Element.animate");
+ assert.doesNotMatch(document.html, /\.animate\(/u, "HTML renderer' waapi adapter tracks Element.animate");
assert.doesNotMatch(document.html, /isolation:isolate/u);
const marker = document.html.indexOf("const millisecondsPerFrame");
assert.ok(marker >= 0);
const scriptStart = document.html.lastIndexOf("<script>", marker) + "<script>".length;
const scriptEnd = document.html.indexOf("</script>", marker);
- const { frameWorkIndexRuntime, hyperframesFrameSelectionPrelude } = await import("../src/frame-work.js");
+ const { frameWorkIndexRuntime, htmlFrameSelectionPrelude } = await import("../src/frame-work.js");
const runtime = `${frameWorkIndexRuntime}\n${document.html.slice(scriptStart, scriptEnd)}`;
const toFrame = (milliseconds: number) => Math.round(milliseconds * 30 / 1_001);
- // The fake engine advances every animation that remains live after Hypit's
+ // The test page advances every animation that remains live after Hypit's
// seek handler. This is the collision which made later Presents use absolute
// composition time even though Hypit had first applied a local pose.
const evaluate = async (
@@ -387,7 +388,7 @@ test("HyperFrames emits compact absolute-frame animation without creating a Trac
const positions = spans.map((): number[] => []);
const live = new Set<FakeAnimation>();
let materialized = 0;
- let seek: (event: { detail: { time: number } }) => void = () => {};
+ let seek: (event: { detail: { frame: number } }) => void = () => {};
const animate = (target: FakeElement, record?: number[], effect?: object): FakeAnimation => {
const animation = {
target,
@@ -425,7 +426,7 @@ test("HyperFrames emits compact absolute-frame animation without creating a Trac
});
return element;
});
- runInNewContext(`${selection === undefined ? "" : hyperframesFrameSelectionPrelude(selection)}\n${runtime}`, {
+ runInNewContext(`${selection === undefined ? "" : htmlFrameSelectionPrelude(selection)}\n${runtime}`, {
document: { querySelectorAll: () => elements, documentElement: { getBoundingClientRect() {} }, timeline: {} },
window: { addEventListener(_name: string, callback: typeof seek) { seek = callback; } },
KeyframeEffect: class {
@@ -438,7 +439,7 @@ test("HyperFrames emits compact absolute-frame animation without creating a Trac
getComputedStyle: (element: FakeElement) => ({ opacity: String(element.pose) }),
});
for (const frame of frames) {
- seek({ detail: { time: frame * 1_001 / 30_000 } });
+ seek({ detail: { frame } });
for (const animation of live) animation.currentTime = frame * 1_001 / 30;
}
const shown = elements.map((element) => element.pose === undefined ? element.style.opacity : String(element.pose));
@@ -459,7 +460,7 @@ test("HyperFrames emits compact absolute-frame animation without creating a Trac
live: 0,
positions: [[3, 30, 56]],
shown: ["56"],
- }, "a Present starting after frame 0 keeps its Present-relative pose when HyperFrames seeks live animations");
+ }, "a Present starting after frame 0 keeps its Present-relative pose when HTML renderer seeks live animations");
assert.deepEqual(await evaluate([
{ start: 0, duration: 30 },
{ start: 90, duration: 30 },
@@ -487,7 +488,7 @@ test("HyperFrames emits compact absolute-frame animation without creating a Trac
}, "the point index preserves overlap, half-open boundaries, distant spans and reverse seeks");
});
-test("HyperFrames clips a long animation by Present visibility instead of rejecting it", () => {
+test("HTML renderer clips a long animation by Present visibility instead of rejecting it", () => {
const { composition, timeline } = fixture();
const lower = composition.tracks.find((track) => track.id === "lower");
assert(lower?.kind === "visual");
@@ -499,7 +500,7 @@ test("HyperFrames clips a long animation by Present visibility instead of reject
{ atFrame: 45, style: [{ name: "opacity", value: 1 }] },
] } }] }],
});
- const document = compileHyperframesDocument(sealComposition({
+ const document = compileHtmlProgram(sealComposition({
...composition,
tracks: composition.tracks.map((track) => track.id === "lower" ? animated : track),
}), timeline);
@@ -515,14 +516,14 @@ test("content-bound fonts and typed compositable Surfaces cross the same Artifac
const font: FontArtifactRef = {
sources: [{ artifact: {
kind: "blob",
- resource: fixtureResource("hyperframes:font"),
+ resource: fixtureResource("html-program:font"),
size: 1_024,
mediaType: "font/woff2",
} }],
weight: 700,
style: "normal",
};
- const surfaceDigest = fixtureResource("hyperframes:alpha-surface");
+ const surfaceDigest = fixtureResource("html-program:alpha-surface");
const track = sealVisualTrack({ timelineId: "test-space",
visualIr: "hypit.visual-ir@1",
id: "bound-render-dependencies",
@@ -573,12 +574,12 @@ test("content-bound fonts and typed compositable Surfaces cross the same Artifac
],
}],
});
- const document = compileHyperframesDocument(sealComposition({
+ const document = compileHtmlProgram(sealComposition({
id: "render-dependencies",
canvas: { width: 1080, height: 1920, clearColor: "#000000" },
tracks: [track],
}), space);
- assert.doesNotThrow(() => assertHyperframesDocument(document));
+ assert.doesNotThrow(() => assertHtmlProgram(document));
assert.deepEqual(document.artifacts.map(({ artifact }) => artifact.resource), [font.sources[0]!.artifact.resource, surfaceDigest].sort());
assert.deepEqual(document.artifacts.find(({ artifact }) => artifact.resource === font.sources[0]!.artifact.resource)?.usage,
{ kind: "always" });
@@ -589,7 +590,7 @@ test("content-bound fonts and typed compositable Surfaces cross the same Artifac
assert.match(document.html, /font-synthesis:none/u);
assert.match(document.html, /data-hypit-alpha-mode="straight"/u);
assert.match(document.html, /data-hypit-color-space="srgb"/u);
- const materialized = materializeHyperframesHtml(document,
+ const materialized = materializeHtmlProgram(document,
(artifact) => `https://assets.example/${artifact.resource}?token=1&part=2`);
assert.doesNotMatch(materialized, /hypit-resource:\/\//u);
assert.match(materialized, new RegExp(font.sources[0]!.artifact.resource, "u"));
@@ -601,7 +602,7 @@ test("exact timed sampling keeps a held frame as one compact interval without ze
});
const artifact = {
kind: "blob" as const,
- resource: fixtureResource("hyperframes:sampled-video"),
+ resource: fixtureResource("html-program:sampled-video"),
size: 1_000,
mediaType: "video/mp4",
};
@@ -640,16 +641,16 @@ test("exact timed sampling keeps a held frame as one compact interval without ze
}],
}],
});
- const document = compileHyperframesDocument(sealComposition({
+ const document = compileHtmlProgram(sealComposition({
id: "sampled",
canvas: { width: 100, height: 100, clearColor: "#000000" },
tracks: [track],
}), timeline);
assert.equal((document.html.match(/data-hypit-sampling-part=/gu) ?? []).length, 3);
- assert.match(document.html, /data-media-start="0\.066666666666"/u);
- assert.match(document.html, /data-media-start="0"/u);
- assert.equal((document.html.match(/data-playback-rate="1"/gu) ?? []).length, 3);
- assert.doesNotMatch(document.html, /data-playback-rate="0"/u);
+ assert.equal(document.frameSources.length, 3);
+ assert.deepEqual(document.frameSources.map(source => source.sourceFrame), [
+ { numerator: 2, denominator: 1 }, { numerator: 0, denominator: 1 }, { numerator: 3, denominator: 1 },
+ ]);
assert.equal((document.html.match(/data-hypit-resource-src="hypit-resource:\/\//gu) ?? []).length, 3);
assert.doesNotMatch(document.html, /<video\b[^>]*\ssrc=/u,
"compiler-owned video stays inert while its exact slots remain statically readable");
@@ -657,8 +658,8 @@ test("exact timed sampling keeps a held frame as one compact interval without ze
});
test("a Track naming five takes still lowers to DOM identities a Windows path can hold", () => {
- // HyperFrames spends the video element's id as a directory name for that video's extracted
- // frames, under `%TEMP%\hf-render-XXXXXX\compiled\__hyperframes_video_frames\<id>\frame_%05d.png`.
+ // HTML renderer spends the video element's id as a directory name for that video's extracted
+ // frames, under the Provider execution's private decoded-frame directory.
// That surround is 103 characters of a 260-character budget, so the id is what decides whether
// extraction can write at all. These identities are the ones a five-take speech Track produces:
// the Track names every take, and the Present and the layer each repeat the Track.
@@ -681,7 +682,7 @@ test("a Track naming five takes still lowers to DOM identities a Windows path ca
kind: "video",
artifact: {
kind: "blob" as const,
- resource: fixtureResource("hyperframes:long-identity-video"),
+ resource: fixtureResource("html-program:long-identity-video"),
size: 1_000,
mediaType: "video/mp4",
},
@@ -707,7 +708,7 @@ test("a Track naming five takes still lowers to DOM identities a Windows path ca
}],
}],
});
- const document = compileHyperframesDocument(sealComposition({
+ const document = compileHtmlProgram(sealComposition({
id: "long-identity",
canvas: { width: 100, height: 100, clearColor: "#000000" },
tracks: [track],
@@ -723,28 +724,28 @@ test("a Track naming five takes still lowers to DOM identities a Windows path ca
assert.ok(document.html.includes(`data-hypit-element-id="${presentId}:foreground"`));
});
-test("browser programs own local HTML while retaining typed child resources and format boundaries", async () => {
- const { browserProgram } = await import("../src/browser-program.js");
+test("HTML visuals own local HTML while retaining typed child resources and format boundaries", async () => {
+ const { htmlVisual } = await import("../src/html-visual.js");
const { timeline, picture } = fixture();
- const opaqueArtifact = { kind: "blob" as const, resource: fixtureResource("hyperframes:opaque-program"),
+ const opaqueArtifact = { kind: "blob" as const, resource: fixtureResource("html-program:opaque-program"),
size: 12, mediaType: "image/png" };
const visual = sealVisualTrack({ id: "scene", timelineId: timeline.id, visualIr: VISUAL_IR_V1,
presents: [{ id: "scene", order: 0, z: 0, span: { startFrame: 0, endFrameExclusive: 30 },
- elements: [{ id: "root", kind: "program", order: 0, style: [], program: browserProgram({
+ elements: [{ id: "root", kind: "program", order: 0, style: [], program: htmlVisual({
html: `<section class="viewport">{{photo}}<img class="opaque" src="hypit-resource://${opaqueArtifact.resource}"><svg><path d="M0 0H20"/></svg></section>`,
css: '.viewport { backdrop-filter:blur(4px); display:grid; }',
setup: 'return frame => { root.dataset.frame = String(frame); };',
}, [opaqueArtifact]) }, { id: "photo", parent: "root", kind: "image", order: 1, artifact: picture, style: [] }] }] });
const composition = sealComposition({ id: "scene", canvas: { width: 200, height: 200, clearColor: "#000000" }, tracks: [visual] });
- const document = compileHyperframesDocument(composition, timeline);
+ const document = compileHtmlProgram(composition, timeline);
assert.equal(document.artifacts.length, 2);
assert.deepEqual(document.artifacts.find(({ artifact }) => artifact.resource === opaqueArtifact.resource)?.usage,
- { kind: "always" }, "opaque Browser Program dependencies remain conservative");
+ { kind: "always" }, "opaque HtmlVisual dependencies remain conservative");
assert.deepEqual(document.artifacts.find(({ artifact }) => artifact.resource === picture.resource)?.usage,
{ kind: "frames", spans: [{ startFrame: 0, endFrameExclusive: 30 }] });
assert.ok(document.html.includes('<section class="viewport">'));
assert.ok(document.html.includes(`class="opaque" src="hypit-resource://${opaqueArtifact.resource}"`),
- "opaque Browser Program markup is not rewritten by the structural compiler");
+ "opaque HtmlVisual markup is not rewritten by the structural compiler");
assert.ok(document.html.includes(`data-hypit-resource-src="hypit-resource://${picture.resource}"`),
"a typed child keeps the structural compiler's selection-gated resource behavior");
assert.ok(document.html.includes('@scope'));
@@ -753,56 +754,56 @@ test("browser programs own local HTML while retaining typed child resources and
if (root.kind !== "visual" || root.presents[0]!.elements[0]!.kind !== "program") throw new Error("fixture");
const program = root.presents[0]!.elements[0]!.program;
(program as { format: string }).format = "another.renderer@1";
- assert.throws(() => compileHyperframesDocument(missing, timeline), /does not support visual program format/);
+ assert.throws(() => compileHtmlProgram(missing, timeline), /does not support visual program format/);
});
-test("browser program state follows direct seeks and reports authored evaluation failures", async () => {
+test("HTML visual state follows direct seeks and reports authored evaluation failures", async () => {
const { runInNewContext } = await import("node:vm");
- const { browserProgramScript } = await import("../src/browser-program.js");
+ const { htmlVisualScript } = await import("../src/html-visual.js");
const { frameWorkIndexRuntime } = await import("../src/frame-work.js");
const root = { frame: -1 };
- let seek: (event: { detail: { time: number } }) => void = () => {};
- const window: { addEventListener: (name: string, callback: typeof seek) => void; __hypitBrowserProgramError?: string } = {
+ let seek: (event: { detail: { frame: number } }) => void = () => {};
+ const window: { addEventListener: (name: string, callback: typeof seek) => void; __hypitHtmlVisualError?: string } = {
addEventListener: (_name, callback) => { seek = callback; },
};
- runInNewContext(`${frameWorkIndexRuntime}\n${browserProgramScript([{ id: "scene", startFrame: 30, durationFrames: 90,
+ runInNewContext(`${frameWorkIndexRuntime}\n${htmlVisualScript([{ id: "scene", startFrame: 30, durationFrames: 90,
program: { html: "", setup: 'return frame => { if(frame===60) throw new Error("bad pose"); root.frame=frame; };' },
}], 30, 1)}`, { window, document: { getElementById: () => root } });
- seek({ detail: { time: 2.5 } });
+ seek({ detail: { frame: 75 } });
assert.equal(root.frame, 45);
- seek({ detail: { time: 1.2 } });
+ seek({ detail: { frame: 36 } });
assert.equal(root.frame, 6);
- seek({ detail: { time: 3 } });
- assert.match(window.__hypitBrowserProgramError!, /bad pose/);
+ seek({ detail: { frame: 90 } });
+ assert.match(window.__hypitHtmlVisualError!, /bad pose/);
});
test("inactive programs settle once, while re-entry and repeated active seeks still redraw ready assets", async () => {
const { runInNewContext } = await import("node:vm");
- const { browserProgramScript } = await import("../src/browser-program.js");
+ const { htmlVisualScript } = await import("../src/html-visual.js");
const { frameWorkIndexRuntime } = await import("../src/frame-work.js");
const root = { frames: [] as number[], ready: false, painted: false };
- let seek: (event: { detail: { time: number } }) => void = () => {};
- runInNewContext(`${frameWorkIndexRuntime}\n${browserProgramScript([{ id: "scene", startFrame: 30, durationFrames: 30,
+ let seek: (event: { detail: { frame: number } }) => void = () => {};
+ runInNewContext(`${frameWorkIndexRuntime}\n${htmlVisualScript([{ id: "scene", startFrame: 30, durationFrames: 30,
program: { html: "", setup: 'return frame => { root.frames.push(frame); root.painted=root.ready; };' },
}], 30, 1)}`, { window: { addEventListener: (_: string, callback: typeof seek) => { seek = callback; } },
document: { getElementById: () => root } });
- seek({ detail: { time: 0.5 } });
+ seek({ detail: { frame: 15 } });
assert.deepEqual(root.frames, [0]);
- seek({ detail: { time: 1 } });
+ seek({ detail: { frame: 30 } });
root.ready = true;
- seek({ detail: { time: 1 } });
+ seek({ detail: { frame: 30 } });
assert.equal(root.painted, true);
- seek({ detail: { time: 2 } });
- seek({ detail: { time: 3 } });
+ seek({ detail: { frame: 60 } });
+ seek({ detail: { frame: 90 } });
assert.deepEqual(root.frames, [0, 0, 0, 30]);
- seek({ detail: { time: 1.5 } });
- seek({ detail: { time: 0.5 } });
+ seek({ detail: { frame: 45 } });
+ seek({ detail: { frame: 15 } });
assert.deepEqual(root.frames, [0, 0, 0, 30, 15, 0]);
});
-test("sequential Browser Program work follows active and crossed spans instead of all Programs", async () => {
+test("sequential HtmlVisual work follows active and crossed spans instead of every visual", async () => {
const { runInNewContext } = await import("node:vm");
- const { browserProgramScript } = await import("../src/browser-program.js");
+ const { htmlVisualScript } = await import("../src/html-visual.js");
const { frameWorkIndexRuntime } = await import("../src/frame-work.js");
const entries = Array.from({ length: 100 }, (_, index) => ({
id: `scene-${index}`,
@@ -811,20 +812,20 @@ test("sequential Browser Program work follows active and crossed spans instead o
program: { html: "", setup: "return () => { root.calls += 1; };" },
}));
const roots = new Map(entries.map(entry => [entry.id, { calls: 0 }]));
- let seek: (event: { detail: { time: number } }) => void = () => {};
- runInNewContext(`${frameWorkIndexRuntime}\n${browserProgramScript(entries, 30, 1)}`, {
+ let seek: (event: { detail: { frame: number } }) => void = () => {};
+ runInNewContext(`${frameWorkIndexRuntime}\n${htmlVisualScript(entries, 30, 1)}`, {
window: { addEventListener: (_: string, callback: typeof seek) => { seek = callback; } },
document: { getElementById: (id: string) => roots.get(id) },
});
for (const root of roots.values()) root.calls = 0;
- for (let frame = 0; frame < 1_000; frame++) seek({ detail: { time: frame / 30 } });
+ for (let frame = 0; frame < 1_000; frame++) seek({ detail: { frame } });
assert.equal([...roots.values()].reduce((sum, root) => sum + root.calls, 0), 1_099);
});
-test("browser program setup is limited to Presents overlapping the render selection", async () => {
+test("HTML visual setup is limited to Presents overlapping the render selection", async () => {
const { runInNewContext } = await import("node:vm");
- const { browserProgramScript } = await import("../src/browser-program.js");
- const { frameWorkIndexRuntime, hyperframesFrameSelectionPrelude } = await import("../src/frame-work.js");
+ const { htmlVisualScript } = await import("../src/html-visual.js");
+ const { frameWorkIndexRuntime, htmlFrameSelectionPrelude } = await import("../src/frame-work.js");
const roots = new Map([
["early", { setups: 0, renders: 0 }],
["selected", { setups: 0, renders: 0 }],
@@ -835,8 +836,8 @@ test("browser program setup is limited to Presents overlapping the render select
{ id: "selected", startFrame: 90, durationFrames: 30,
program: { html: "", setup: "root.setups += 1; return () => { root.renders += 1; };" } },
];
- runInNewContext(`${hyperframesFrameSelectionPrelude([{ startFrame: 100, endFrameExclusive: 101 }])}
- ${frameWorkIndexRuntime}\n${browserProgramScript(entries, 30, 1)}`, {
+ runInNewContext(`${htmlFrameSelectionPrelude([{ startFrame: 100, endFrameExclusive: 101 }])}
+ ${frameWorkIndexRuntime}\n${htmlVisualScript(entries, 30, 1)}`, {
window: { addEventListener() {} },
document: { getElementById: (id: string) => roots.get(id) },
});
@@ -844,15 +845,15 @@ test("browser program setup is limited to Presents overlapping the render select
assert.deepEqual(roots.get("selected"), { setups: 1, renders: 1 });
});
-test("an asynchronous browser program reports its unsupported frame behavior instead of racing capture", async () => {
+test("an asynchronous HTML visual reports its unsupported frame behavior instead of racing capture", async () => {
const { runInNewContext } = await import("node:vm");
- const { browserProgramScript } = await import("../src/browser-program.js");
+ const { htmlVisualScript } = await import("../src/html-visual.js");
const { frameWorkIndexRuntime } = await import("../src/frame-work.js");
- const window = { addEventListener() {}, __hypitBrowserProgramError: undefined as string | undefined };
- runInNewContext(`${frameWorkIndexRuntime}\n${browserProgramScript([{ id: "scene", startFrame: 0, durationFrames: 30,
+ const window = { addEventListener() {}, __hypitHtmlVisualError: undefined as string | undefined };
+ runInNewContext(`${frameWorkIndexRuntime}\n${htmlVisualScript([{ id: "scene", startFrame: 0, durationFrames: 30,
program: { html: "", setup: 'return async frame => { await Promise.resolve(); throw new Error("late drawing failure"); };' },
}], 30, 1)}`, { window, document: { getElementById: () => ({}) } });
- assert.match(window.__hypitBrowserProgramError!, /must be synchronous/u);
+ assert.match(window.__hypitHtmlVisualError!, /must be synchronous/u);
await new Promise(resolve => setImmediate(resolve));
- assert.match(window.__hypitBrowserProgramError!, /late drawing failure/u);
+ assert.match(window.__hypitHtmlVisualError!, /late drawing failure/u);
});
diff --git a/packages/hyperframes/test/frame-work.test.ts b/packages/html-program/test/frame-work.test.ts
similarity index 80%
rename from packages/hyperframes/test/frame-work.test.ts
rename to packages/html-program/test/frame-work.test.ts
index c2219289..5e14cd3a 100644
--- a/packages/hyperframes/test/frame-work.test.ts
+++ b/packages/html-program/test/frame-work.test.ts
@@ -2,28 +2,28 @@ import assert from "node:assert/strict";
import { runInNewContext } from "node:vm";
import test from "node:test";
-import { frameWorkIndexRuntime, hyperframesFrameSelectionPrelude } from "../src/frame-work.js";
+import { frameWorkIndexRuntime, htmlFrameSelectionPrelude } from "../src/frame-work.js";
test("render-local frame selection uses compact absolute spans and defaults to the whole document", () => {
const context: { result?: boolean[] } = {};
- const prelude = hyperframesFrameSelectionPrelude([
+ const prelude = htmlFrameSelectionPrelude([
{ startFrame: 10, endFrameExclusive: 20 },
{ startFrame: 40, endFrameExclusive: 41 },
]);
runInNewContext(`${prelude}\n${frameWorkIndexRuntime}
result = [
- hyperframesSelectionOverlaps(0, 10),
- hyperframesSelectionOverlaps(9, 11),
- hyperframesSelectionOverlaps(20, 40),
- hyperframesSelectionOverlaps(40, 41),
- hyperframesSelectionOverlaps(41, 50),
+ htmlSelectionOverlaps(0, 10),
+ htmlSelectionOverlaps(9, 11),
+ htmlSelectionOverlaps(20, 40),
+ htmlSelectionOverlaps(40, 41),
+ htmlSelectionOverlaps(41, 50),
];`, context);
assert.deepEqual(JSON.parse(JSON.stringify(context.result)), [false, true, false, true, false]);
const unrestricted: { result?: boolean } = {};
- runInNewContext(`${frameWorkIndexRuntime}\nresult = hyperframesSelectionOverlaps(100, 200);`, unrestricted);
+ runInNewContext(`${frameWorkIndexRuntime}\nresult = htmlSelectionOverlaps(100, 200);`, unrestricted);
assert.equal(unrestricted.result, true);
- assert.throws(() => hyperframesFrameSelectionPrelude([
+ assert.throws(() => htmlFrameSelectionPrelude([
{ startFrame: 5, endFrameExclusive: 10 },
{ startFrame: 4, endFrameExclusive: 6 },
]), /ordered, disjoint/u);
@@ -45,7 +45,7 @@ test("page-local frame work lookup preserves half-open spans and stable order",
queryFrames: [0, 3, 4, 5, 7, 8, 100, 101, 102, 6],
};
runInNewContext(`${frameWorkIndexRuntime}
- const index = hyperframesCreateFrameWorkIndex(entries);
+ const index = htmlCreateFrameWorkIndex(entries);
result = queryFrames.map((frame) => index.at(frame).map((entry) => entry.payload));`, context);
assert.deepEqual(JSON.parse(JSON.stringify(context.result)), [
["early"],
@@ -64,7 +64,7 @@ test("page-local frame work lookup preserves half-open spans and stable order",
test("page-local frame work lookup returns only spans overlapping an arbitrary range", () => {
const context: { result?: string[][] } = {};
runInNewContext(`${frameWorkIndexRuntime}
- const index = hyperframesCreateFrameWorkIndex([
+ const index = htmlCreateFrameWorkIndex([
{ startFrame: 0, endFrameExclusive: 5, order: 0, payload: 'early' },
{ startFrame: 3, endFrameExclusive: 8, order: 1, payload: 'overlap' },
{ startFrame: 8, endFrameExclusive: 10, order: 2, payload: 'adjacent' },
@@ -86,10 +86,10 @@ test("frame work lookup rejects invalid spans and query frames", () => {
const evaluate = (entries: object[], frame = 0): unknown => {
const context: { entries: object[]; frame: number; result?: unknown } = { entries, frame };
return assert.throws(() => runInNewContext(`${frameWorkIndexRuntime}
- result = hyperframesCreateFrameWorkIndex(entries).at(frame);`, context));
+ result = htmlCreateFrameWorkIndex(entries).at(frame);`, context));
};
evaluate([{ startFrame: 2, endFrameExclusive: 2, payload: null }]);
evaluate([{ startFrame: 0, endFrameExclusive: 1, order: 0, payload: null }], -1);
assert.throws(() => runInNewContext(`${frameWorkIndexRuntime}
- hyperframesCreateFrameWorkIndex([]).overlapping({ startFrame: 2, endFrameExclusive: 2 });`));
+ htmlCreateFrameWorkIndex([]).overlapping({ startFrame: 2, endFrameExclusive: 2 });`));
});
diff --git a/packages/hyperframes/test/text-runtime.test.ts b/packages/html-program/test/text-runtime.test.ts
similarity index 88%
rename from packages/hyperframes/test/text-runtime.test.ts
rename to packages/html-program/test/text-runtime.test.ts
index 4fccca97..fbe742ab 100644
--- a/packages/hyperframes/test/text-runtime.test.ts
+++ b/packages/html-program/test/text-runtime.test.ts
@@ -2,7 +2,7 @@ import assert from "node:assert/strict";
import { runInNewContext } from "node:vm";
import test from "node:test";
-import { frameWorkIndexRuntime, hyperframesFrameSelectionPrelude } from "../src/frame-work.js";
+import { frameWorkIndexRuntime, htmlFrameSelectionPrelude } from "../src/frame-work.js";
import { terminalTextLayoutScript } from "../src/text.js";
test("terminal Text lazily prepares one persistent Animation per active Unit × Sequence", async () => {
@@ -59,12 +59,12 @@ test("terminal Text lazily prepares one persistent Animation per active Unit ×
};
const roots = [root(0, units), root(30, futureUnits)];
const composition = { getAttribute: (name: string) => name === "data-composition-id" ? "main" : null };
- let seekListener: ((event: { detail: { waitUntil(value: Promise<void>): void } }) => void) | undefined;
+ let seekListener: ((event: { detail: { frame: number; waitUntil(value: Promise<void>): void } }) => void) | undefined;
const window = {
addEventListener(name: string, listener: typeof seekListener) {
- if (name === "hf-seek") seekListener = listener;
+ if (name === "hypit-frame") seekListener = listener;
},
- } as { addEventListener(name: string, listener: typeof seekListener): void; __timelines?: Record<string, { totalTime(time: number): void }> };
+ } as { addEventListener(name: string, listener: typeof seekListener): void };
let seededSteps = 0;
const countedMath = Object.create(Math) as Math;
countedMath.imul = (left, right) => {
@@ -88,7 +88,7 @@ test("terminal Text lazily prepares one persistent Animation per active Unit ×
});
assert.ok(seekListener);
let ready: Promise<void> | undefined;
- seekListener({ detail: { waitUntil(value) { ready = value; } } });
+ seekListener({ detail: { frame: 0, waitUntil(value) { ready = value; } } });
assert.ok(ready);
await ready;
@@ -102,14 +102,14 @@ test("terminal Text lazily prepares one persistent Animation per active Unit ×
}
assert.ok(units.every((unit) => unit.animationPositions[0]!.length === 2), "the active root receives the initial absolute seek");
assert.ok(futureUnits.every((unit) => unit.animationKeyframes.length === 0), "the future root is not prepared in this Worker");
- for (let frame = 1; frame <= 20; frame += 1) window.__timelines!.main!.totalTime(frame / 30);
+ for (let frame = 1; frame <= 20; frame += 1) seekListener({ detail: { frame, waitUntil() {} } });
assert.equal(seededSteps, 2, "seeks reuse the prepared inverse rank map");
for (const unit of units) {
assert.equal(unit.animationKeyframes.length, 1);
assert.equal(unit.animationKeyframes[0], preparedKeyframes, "Units in one root reuse prepared native keyframes");
assert.equal(unit.animationPositions[0]!.length, 22);
}
- window.__timelines!.main!.totalTime(1);
+ seekListener({ detail: { frame: 30, waitUntil() {} } });
assert.ok(units.every((unit) => unit.animationPositions[0]!.length === 22), "the expired Text root remains untouched");
assert.ok(futureUnits.every((unit) => unit.animationPositions[0]!.length === 2), "the newly active Text root is evaluated");
assert.equal(seededSteps, 4, "the newly active root prepares its random order once on first use");
@@ -142,11 +142,10 @@ test("terminal Text static layout ignores roots outside the render selection", a
const composition = { getAttribute: () => "main" };
let ready: Promise<void> | undefined;
const window = {
- addEventListener(name: string, listener: (event: { detail: { waitUntil(value: Promise<void>): void } }) => void) {
- if (name === "hf-seek") listener({ detail: { waitUntil(value) { ready = value; } } });
+ addEventListener(name: string, listener: (event: { detail: { frame: number; waitUntil(value: Promise<void>): void } }) => void) {
+ if (name === "hypit-frame") listener({ detail: { frame: 100, waitUntil(value) { ready = value; } } });
},
- } as { addEventListener(name: string, listener: (event: { detail: { waitUntil(value: Promise<void>): void } }) => void): void;
- __timelines?: Record<string, unknown> };
+ } as { addEventListener(name: string, listener: (event: { detail: { frame: number; waitUntil(value: Promise<void>): void } }) => void): void };
const document = {
fonts: { ready: Promise.resolve() },
documentElement: { getBoundingClientRect() {} },
@@ -157,7 +156,7 @@ test("terminal Text static layout ignores roots outside the render selection", a
},
getElementById() { return null; },
};
- runInNewContext(`${hyperframesFrameSelectionPrelude([{ startFrame: 100, endFrameExclusive: 101 }])}
+ runInNewContext(`${htmlFrameSelectionPrelude([{ startFrame: 100, endFrameExclusive: 101 }])}
${frameWorkIndexRuntime}\n${terminalTextLayoutScript}`, { document, Element: MockElement, window });
assert.ok(ready);
await ready;
diff --git a/packages/hyperframes/test/visibility.test.ts b/packages/html-program/test/visibility.test.ts
similarity index 82%
rename from packages/hyperframes/test/visibility.test.ts
rename to packages/html-program/test/visibility.test.ts
index c272be60..98e55a47 100644
--- a/packages/hyperframes/test/visibility.test.ts
+++ b/packages/html-program/test/visibility.test.ts
@@ -19,17 +19,17 @@ test("Present visibility updates only absolute active-set changes across arbitra
};
const a = element("a", [{ startFrame: 2, endFrameExclusive: 5 }, { startFrame: 8, endFrameExclusive: 10 }]);
const b = element("b", [{ startFrame: 4, endFrameExclusive: 9 }]);
- let seek: (event: { detail: { time: number } }) => void = () => {};
+ let seek: (event: { detail: { frame: number } }) => void = () => {};
runInNewContext(`${frameWorkIndexRuntime}\n${presentationVisibilityScript(30, 1)}`, {
window: { addEventListener: (_: string, callback: typeof seek) => { seek = callback; } },
document: { querySelectorAll: () => [a, b] },
Set,
});
assert.deepEqual(writes, ["a:0", "b:0"]);
- seek({ detail: { time: 2 / 30 } });
- seek({ detail: { time: 4 / 30 } });
- seek({ detail: { time: 6 / 30 } });
- seek({ detail: { time: 8 / 30 } });
- seek({ detail: { time: 1 / 30 } });
+ seek({ detail: { frame: 2 } });
+ seek({ detail: { frame: 4 } });
+ seek({ detail: { frame: 6 } });
+ seek({ detail: { frame: 8 } });
+ seek({ detail: { frame: 1 } });
assert.deepEqual(writes, ["a:0", "b:0", "a:", "b:", "a:0", "a:", "a:0", "b:0"]);
});
diff --git a/packages/html-video/README.md b/packages/html-video/README.md
new file mode 100644
index 00000000..bf3f807a
--- /dev/null
+++ b/packages/html-video/README.md
@@ -0,0 +1,24 @@
+# @hypit/html-video
+
+`@hypit/html-video` is the author-facing video assembly that selects Hypit's HTML
+visual path:
+
+```xml
+<html:Video id="video" composition="main" />
+```
+
+The package contributes only the `html` author Surface and its orchestration
+Fragment. It:
+
+1. compiles the selected Composition and Timeline with `@hypit/html-program`;
+2. requests a `TimelineVisual` through `rasterize-visual`;
+3. prepares Timeline audio through the media path;
+4. muxes the two frame-exact products into the Film artifact.
+
+It does not own the `HtmlProgram` ABI, browser execution, frame capture, source
+decoding, or the rasterization Capabilities. Consequently a local Provider,
+Studio snapshot, or another executor never depends on this author package.
+
+The name describes the selected representation and product assembly, not an
+implementation command. There is intentionally no `<render:Video>` compatibility
+alias: `render` confuses the desired video with one possible execution method.
diff --git a/packages/html-video/package.json b/packages/html-video/package.json
new file mode 100644
index 00000000..f8de2f58
--- /dev/null
+++ b/packages/html-video/package.json
@@ -0,0 +1,42 @@
+{
+ "name": "@hypit/html-video",
+ "version": "0.1.0",
+ "license": "SEE LICENSE IN LICENSE",
+ "private": true,
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "files": [
+ "dist",
+ "README.md"
+ ],
+ "hypit": {
+ "activation": "./src/activation.ts"
+ },
+ "dependencies": {
+ "@hypit/media-operations": "workspace:^"
+ },
+ "peerDependencies": {
+ "@hypit/hypit": "workspace:^"
+ },
+ "devDependencies": {
+ "@hypit/compiler": "workspace:*",
+ "@hypit/blob": "workspace:*",
+ "@hypit/composition": "workspace:*",
+ "@hypit/author": "workspace:*",
+ "@hypit/source": "workspace:*",
+ "@hypit/html-program": "workspace:*",
+ "@hypit/media": "workspace:*",
+ "@hypit/producer": "workspace:*",
+ "@hypit/timeline": "workspace:*",
+ "@hypit/markup": "workspace:*",
+ "@hypit/temporal": "workspace:*",
+ "@hypit/kernel": "workspace:*",
+ "@hypit/executor": "workspace:*",
+ "@hypit/recipe": "workspace:*",
+ "@hypit/admission": "workspace:*",
+ "@hypit/hypit": "workspace:*",
+ "@hypit/protocol": "workspace:*"
+ }
+}
diff --git a/packages/html-video/src/activation.ts b/packages/html-video/src/activation.ts
new file mode 100644
index 00000000..a4378bb8
--- /dev/null
+++ b/packages/html-video/src/activation.ts
@@ -0,0 +1,17 @@
+import { createMarkupSurfaceFacet } from "@hypit/hypit/markup";
+import {
+ decodeHtmlVideoSurface, htmlVideoManifest,
+ htmlVideoModuleRef,
+ htmlVideoMarkupSurfaces,
+} from "./index.js";
+
+export const hypitPackage = {
+ format: "hypit.package@1" as const,
+ modules: [{ manifest: htmlVideoManifest }],
+ facets: [createMarkupSurfaceFacet({
+ module: htmlVideoModuleRef,
+ declaration: htmlVideoMarkupSurfaces.find((item) => item.name === "video")!,
+ handler: decodeHtmlVideoSurface,
+ })],
+};
+export default hypitPackage;
diff --git a/packages/render-hyperframes/src/fragment.ts b/packages/html-video/src/fragment.ts
similarity index 51%
rename from packages/render-hyperframes/src/fragment.ts
rename to packages/html-video/src/fragment.ts
index e635468f..e90b18dd 100644
--- a/packages/render-hyperframes/src/fragment.ts
+++ b/packages/html-video/src/fragment.ts
@@ -1,20 +1,16 @@
-import { timelineTypes } from "@hypit/timeline";
-import { mediaTypes } from "@hypit/media";
-import { artifactTypes } from "@hypit/artifact";
+import { timelineTypes } from "@hypit/hypit/timeline";
+import { mediaTypes } from "@hypit/hypit/media";
+import { blobTypes } from "@hypit/hypit/blob";
-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";
+import { compositionTypes } from "@hypit/hypit/composition";
+import { sealGraphFragment } from "@hypit/hypit/author";
+import { htmlProgramProducers } from "@hypit/hypit/html-program";
+import { mediaOperationsProducers } from "@hypit/media-operations";
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) {
+export function createHtmlVideoFragment(selectedRange = false) {
return sealGraphFragment({
inputs: [
{ name: "composition", type: compositionTypes.composition },
@@ -23,52 +19,52 @@ export function createRenderHyperframesFragment(selectedRange = false) {
],
operations: [
{
- id: "compile-document",
- producer: hyperframesProducers.compile,
+ id: "compile-program",
+ producer: htmlProgramProducers.compile,
inputs: { composition: input("composition"), timeline: input("timeline") },
- result: { kind: "output", name: "document" },
+ result: { kind: "output", name: "program" },
},
{
- id: "request-visual-render",
- producer: selectedRange ? renderHyperframesProducers.requestVisualRange : renderHyperframesProducers.requestVisual,
- inputs: { document: operation("compile-document"), ...(selectedRange ? { range: input("range") } : {}) },
+ id: "request-visual",
+ producer: selectedRange ? htmlProgramProducers.requestVisualRange : htmlProgramProducers.requestVisual,
+ inputs: { program: operation("compile-program"), ...(selectedRange ? { range: input("range") } : {}) },
result: { kind: "need", name: "visual" },
},
{
id: "compile-audio-program",
- producer: mediaPipelineProducers.planAudio,
+ producer: mediaOperationsProducers.planAudio,
inputs: { composition: input("composition"), timeline: input("timeline") },
result: { kind: "output", name: "plan" },
},
{
id: "request-audio-render",
- producer: selectedRange ? mediaPipelineProducers.renderAudioRange : mediaPipelineProducers.renderAudio,
+ producer: selectedRange ? mediaOperationsProducers.renderAudioRange : mediaOperationsProducers.renderAudio,
inputs: { plan: operation("compile-audio-program"), ...(selectedRange ? { range: input("range") } : {}) },
result: { kind: "need", name: "audio" },
},
{
id: "request-mux",
- producer: mediaPipelineProducers.mux,
+ producer: mediaOperationsProducers.mux,
inputs: {
- visual: operation("request-visual-render"),
+ visual: operation("request-visual"),
audio: operation("request-audio-render"),
},
result: { kind: "need", name: "media" },
},
{
id: "project-video",
- producer: mediaPipelineProducers.projectMuxed,
+ producer: mediaOperationsProducers.projectMuxed,
inputs: { media: operation("request-mux") },
result: { kind: "output", name: "video" },
},
],
exports: [{
name: "video",
- type: artifactTypes.blob,
+ type: blobTypes.blob,
root: operation("project-video"),
}],
});
}
-export const renderHyperframesFragment = createRenderHyperframesFragment();
+export const htmlVideoFragment = createHtmlVideoFragment();
diff --git a/packages/html-video/src/index.ts b/packages/html-video/src/index.ts
new file mode 100644
index 00000000..8680d74c
--- /dev/null
+++ b/packages/html-video/src/index.ts
@@ -0,0 +1,3 @@
+export { htmlVideoFragment, createHtmlVideoFragment } from "./fragment.js";
+export { htmlVideoManifest, htmlVideoMarkupSurfaces, htmlVideoModuleRef } from "./manifest.js";
+export { decodeHtmlVideoSurface } from "./surface.js";
diff --git a/packages/html-video/src/manifest.ts b/packages/html-video/src/manifest.ts
new file mode 100644
index 00000000..08139279
--- /dev/null
+++ b/packages/html-video/src/manifest.ts
@@ -0,0 +1,60 @@
+import { temporalContextAttributeVocabulary } from "@hypit/hypit/temporal/markup";
+import { blobDependency, blobTypes } from "@hypit/hypit/blob";
+import { mediaDependency, mediaTypes } from "@hypit/hypit/media";
+import { compositionDependency, compositionTypes } from "@hypit/hypit/composition";
+import { timelineDependency } from "@hypit/hypit/timeline";
+import { htmlProgramModuleRef } from "@hypit/hypit/html-program";
+import type { ModuleManifest } from "@hypit/hypit/protocol";
+import {
+ mediaOperationsModuleRef,
+} from "@hypit/media-operations";
+
+export const htmlVideoModuleRef = { name: "@hypit/html-video", version: "1" } as const;
+export const htmlVideoMarkupSurfaces = [{
+ name: "video",
+ tag: "Video",
+ mode: "structured",
+ outputs: [mediaTypes.frameRange],
+ vocabulary: {
+ summary:
+ "Produces one final video from a Composition on its selected film time axis, publishing the muxed result as a Blob.",
+ attributes: [
+ { name: "id", kind: "identifier", required: true,
+ summary: "Names this video assembly and the final video it publishes." },
+ { name: "composition", kind: "reference", required: true,
+ accepts: [compositionTypes.composition],
+ summary: "Selects the Composition this element compiles, rasterizes and muxes." },
+ ...temporalContextAttributeVocabulary,
+ { name: "start-frame", kind: "literal", required: false, summary: "First original program 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: blobTypes.blob,
+ summary: "The final muxed video Artifact, addressed as `<id>.video`." },
+ ],
+ example: '<html:Video id="final" composition={main.composition} timeline={speech.timeline}/>',
+ notes: [
+ "Supply id, composition and timeline. Write both frame bounds to select a range. The element is empty.",
+ "Visual rasterization, audio preparation and 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 htmlVideoManifest: ModuleManifest = {
+ format: "hypit.module@1",
+ name: htmlVideoModuleRef.name,
+ version: htmlVideoModuleRef.version,
+ dependencies: [
+ blobDependency,
+ mediaDependency,
+ compositionDependency,
+ timelineDependency,
+ { module: htmlProgramModuleRef },
+ { module: mediaOperationsModuleRef },
+ ],
+ types: [],
+ capabilities: [],
+ producers: [],
+};
diff --git a/packages/render-hyperframes/src/surface.ts b/packages/html-video/src/surface.ts
similarity index 83%
rename from packages/render-hyperframes/src/surface.ts
rename to packages/html-video/src/surface.ts
index a85d122d..1da63cb9 100644
--- a/packages/render-hyperframes/src/surface.ts
+++ b/packages/html-video/src/surface.ts
@@ -1,13 +1,9 @@
-import { 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 { resolveTemporalContext } from "@hypit/hypit/temporal/markup";
+import { compositionTypes } from "@hypit/hypit/composition";
+import { mediaTypes, verifyMediaFrameRange } from "@hypit/hypit/media";
+import type { StructuredElement, StructuredSurfaceHandler, MarkupAttributeValue } from "@hypit/hypit/markup";
-import { createRenderHyperframesFragment } from "./fragment.js";
+import { createHtmlVideoFragment } from "./fragment.js";
function stringAttribute(element: StructuredElement, name: string): string {
const value = element.attributes[name];
@@ -23,7 +19,7 @@ function referenceAttribute(element: StructuredElement, name: string): string {
return value.path;
}
-export const decodeHyperframesRenderSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+export const decodeHtmlVideoSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
const names = Object.keys(element.attributes).sort();
if (names.some((name) => !["composition", "id", "timeline", "start-frame", "end-frame-exclusive"].includes(name))) {
throw new Error(`${element.name} contains unsupported attributes`);
@@ -49,7 +45,7 @@ export const decodeHyperframesRenderSurface: StructuredSurfaceHandler = ({ eleme
};
const range = selected ? { startFrame: frame("start-frame"), endFrameExclusive: frame("end-frame-exclusive") } : undefined;
if (range !== undefined) verifyMediaFrameRange(range);
- const fragment = createRenderHyperframesFragment(selected);
+ const fragment = createHtmlVideoFragment(selected);
const rangeId = `${id}.frame-range`;
return {
records: range === undefined ? [] : [{ id: rangeId, type: mediaTypes.frameRange, value: { kind: "inline", value: range }, range: element.range }],
diff --git a/packages/render-hyperframes/test/presentation.test.ts b/packages/html-video/test/presentation.test.ts
similarity index 65%
rename from packages/render-hyperframes/test/presentation.test.ts
rename to packages/html-video/test/presentation.test.ts
index c0699eed..43b25e34 100644
--- a/packages/render-hyperframes/test/presentation.test.ts
+++ b/packages/html-video/test/presentation.test.ts
@@ -1,19 +1,19 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { renderHyperframesComponent } from "../src/component.js";
+import { htmlProgramComponent } from "@hypit/html-program";
test("render requests describe their own frame range and canvas without exposing HTML", () => {
- const present = renderHyperframesComponent.plannedNeeds[0]!.present;
- const document = {
+ const present = htmlProgramComponent.plannedNeeds[0]!.present;
+ const program = {
canvas: { width: 1080, height: 1920 }, frameRate: { numerator: 30000, denominator: 1001 },
- frameCount: 600, html: "large HTML belongs to execution", artifacts: [], surfaces: [],
+ frameCount: 600, html: "large HTML belongs to execution", artifacts: [], surfaces: [], frameSources: [],
};
assert.deepEqual(present({ constraints: {}, pendingInputs: [] }), { fields: {}, references: {} });
- const whole = present({ constraints: { document }, pendingInputs: [] });
+ const whole = present({ constraints: { program }, pendingInputs: [] });
assert.deepEqual(whole.fields, {
width: [1080], height: [1920], startFrame: [0], endFrameExclusive: [600], frameRate: ["30000/1001"],
});
- const range = present({ constraints: { document, range: { startFrame: 30, endFrameExclusive: 91 } }, pendingInputs: [] });
+ const range = present({ constraints: { program, range: { startFrame: 30, endFrameExclusive: 91 } }, pendingInputs: [] });
assert.equal(range.fields.startFrame?.[0], 30);
assert.equal(range.fields.endFrameExclusive?.[0], 91);
assert.equal("html" in range.fields, false);
diff --git a/packages/render-hyperframes/test/render.test.ts b/packages/html-video/test/render.test.ts
similarity index 66%
rename from packages/render-hyperframes/test/render.test.ts
rename to packages/html-video/test/render.test.ts
index 17e76fed..d7bba2e7 100644
--- a/packages/render-hyperframes/test/render.test.ts
+++ b/packages/html-video/test/render.test.ts
@@ -1,11 +1,11 @@
import { sealTimeline, timelineDependency, timelineTypes, timelineComponent } from "@hypit/timeline";
import { compositionComponent, videoContractManifests } from "../../../test/support/video-domain.js";
-import { artifactTypes } from "@hypit/artifact";
+import { blobTypes } from "@hypit/blob";
import {
registerProducerFacets,
- registerTypeValidatorFacets,
-} from "@hypit/component-kit";
-import { mediaTypes, sealMuxedMedia, sealRenderedVisual, sealTimelineAudio } from "@hypit/media";
+} from "@hypit/producer";
+import { registerTypeValidatorFacets } from "@hypit/admission";
+import { mediaTypes, sealMuxedMedia, sealTimelineVisual, sealTimelineAudio } from "@hypit/media";
import { compositionDependency, compositionTypes, sealComposition } from "@hypit/composition";
import type { Composition } from "@hypit/composition";
import assert from "node:assert/strict";
@@ -20,54 +20,53 @@ import {
sealCompiledGraph,
sealRecord,
start,
-} from "@hypit/core";
+} from "@hypit/kernel";
import {
ProducerRegistry,
- NodeDriver,
+ Executor,
EndpointRegistry,
-} from "@hypit/driver-node";
+} from "@hypit/executor";
import {
AuthorFrontendRegistry,
bindAuthorFragment,
- compileSourceClosure,
elaborateGraphFragment,
resolveCompiledSourceExport,
-} from "@hypit/elaborator";
-import type { AuthorSourceUnit } from "@hypit/elaborator";
+} from "@hypit/author";
+import { compileSourceClosure } from "@hypit/compiler";
+import type { ResolvedSource } from "@hypit/source";
+import { resolveSelfDescribedTextSource } from "@hypit/source/text";
import {
- compileHyperframesDocument,
- hyperframesComponent,
- hyperframesManifest,
- hyperframesProducers,
-} from "@hypit/hyperframes";
+ compileHtmlProgram,
+ htmlProgramComponent,
+ htmlProgramManifest,
+ htmlProgramProducers,
+ htmlProgramCapabilities,
+ htmlRasterRequest,
+} from "@hypit/html-program";
import {
- decodeHyperframesRenderSurface,
- renderHyperframesCapabilities,
- renderHyperframesComponent,
- renderHyperframesFragment,
- createRenderHyperframesFragment,
- renderHyperframesManifest,
- renderHyperframesMarkupSurfaces,
- renderHyperframesModuleRef,
- renderHyperframesProducers,
- hyperframesVisualRequest,
-} from "@hypit/render-hyperframes";
+ decodeHtmlVideoSurface,
+ htmlVideoFragment,
+ createHtmlVideoFragment,
+ htmlVideoManifest,
+ htmlVideoMarkupSurfaces,
+ htmlVideoModuleRef,
+} from "@hypit/html-video";
import {
compileAudioProgramPlan,
decodeExtractFrameSurface,
- mediaPipelineComponent,
- mediaPipelineComponents,
- mediaPipelineCapabilities,
- mediaPipelineManifest,
- mediaPipelineMarkupSurfaces,
- mediaPipelineModuleRef,
- mediaPipelineProducers,
-} from "@hypit/media-pipeline";
+ mediaOperationsComponent,
+ mediaOperationsComponents,
+ mediaOperationsCapabilities,
+ mediaOperationsManifest,
+ mediaOperationsMarkupSurfaces,
+ mediaOperationsModuleRef,
+ mediaOperationsProducers,
+} from "@hypit/media-operations";
import {
admitRecord,
createRecordAdmitter,
TypeValidatorRegistry,
-} from "@hypit/validation";
+} from "@hypit/admission";
import type {
CanonicalValue,
ModuleManifest,
@@ -97,9 +96,9 @@ function inline(record: TypedRecord | undefined): CanonicalValue {
const closure = createResolvedClosure([
...videoContractManifests,
- hyperframesManifest,
- mediaPipelineManifest,
- renderHyperframesManifest,
+ htmlProgramManifest,
+ mediaOperationsManifest,
+ htmlVideoManifest,
]);
const compositionRecord = await admitRecord(closure, sealRecord({
id: "composition",
@@ -112,9 +111,9 @@ const spaceRecord = await admitRecord(closure, sealRecord({
value: stored(space),
}), validatorRegistry());
const linked = link(closure, [compositionRecord, spaceRecord]);
-const instance = elaborateGraphFragment(linked, renderHyperframesFragment, {
+const instance = elaborateGraphFragment(linked, htmlVideoFragment, {
id: "final",
- fragment: renderHyperframesFragment.id,
+ fragment: htmlVideoFragment.id,
inputs: {
composition: { kind: "record", id: compositionRecord.id },
timeline: { kind: "record", id: spaceRecord.id },
@@ -131,9 +130,8 @@ function build() {
function producerRegistry(): ProducerRegistry {
const registry = new ProducerRegistry();
- registerProducerFacets(registry, mediaPipelineComponent.producers);
- registerProducerFacets(registry, hyperframesComponent.producers);
- registerProducerFacets(registry, renderHyperframesComponent.producers);
+ registerProducerFacets(registry, mediaOperationsComponent.producers);
+ registerProducerFacets(registry, htmlProgramComponent.producers);
registerProducerFacets(registry, timelineComponent.producers);
return registry;
}
@@ -141,28 +139,28 @@ function producerRegistry(): ProducerRegistry {
function validatorRegistry(): TypeValidatorRegistry {
const registry = new TypeValidatorRegistry();
registerTypeValidatorFacets(registry, compositionComponent.validators);
- for (const component of mediaPipelineComponents) {
+ for (const component of mediaOperationsComponents) {
registerTypeValidatorFacets(registry, component.validators);
}
return registry;
}
-test("HyperFrames rendering is an explicit exact Need after ordinary document compilation", async () => {
+test("HTML renderer rendering is an explicit exact Need after ordinary document compilation", async () => {
assert.deepEqual(build().plan.steps.map((step) => step.producer.name).sort(), [
- hyperframesProducers.compile.name,
- renderHyperframesProducers.requestVisual.name,
- mediaPipelineProducers.planAudio.name,
- mediaPipelineProducers.renderAudio.name,
- mediaPipelineProducers.mux.name,
- mediaPipelineProducers.projectMuxed.name,
+ htmlProgramProducers.compile.name,
+ htmlProgramProducers.requestVisual.name,
+ mediaOperationsProducers.planAudio.name,
+ mediaOperationsProducers.renderAudio.name,
+ mediaOperationsProducers.mux.name,
+ mediaOperationsProducers.projectMuxed.name,
].sort());
- const result = await new NodeDriver({ producers: producerRegistry(), validators: validatorRegistry() }).run(build());
+ const result = await new Executor({ producers: producerRegistry(), validators: validatorRegistry() }).run(build());
assert.equal(result.status, "paused");
assert.equal(result.state.needs.length, 2);
- const visual = result.state.needs.find((need) => need.capability.name === renderHyperframesCapabilities.renderVisual.name)!;
- assert.equal(visual.returns.name, mediaTypes.renderedVisual.name);
- assert.deepEqual(visual.constraints, hyperframesVisualRequest(compileHyperframesDocument(composition, space)));
+ const visual = result.state.needs.find((need) => need.capability.name === htmlProgramCapabilities.rasterizeVisual.name)!;
+ assert.equal(visual.returns.name, mediaTypes.timelineVisual.name);
+ assert.deepEqual(visual.constraints, htmlRasterRequest(compileHtmlProgram(composition, space)));
const audio = result.state.needs.find((need) => need.capability.name === "render-timeline-audio")!;
assert.equal(audio.returns.name, mediaTypes.timelineAudio.name);
assert.equal(result.blocked.every((item) => item.reason === "missing-endpoint"), true);
@@ -171,36 +169,36 @@ test("HyperFrames rendering is an explicit exact Need after ordinary document co
test("separate visual, audio and mux Endpoints complete one author-visible render", async () => {
const visualArtifact = {
kind: "blob" as const,
- resource: fixtureResource("render-hyperframes:visual"),
+ resource: fixtureResource("html-video:visual"),
size: 12_345,
mediaType: "video/mp4",
};
const audioArtifact = {
kind: "blob" as const,
- resource: fixtureResource("render-hyperframes:audio"),
+ resource: fixtureResource("html-video:audio"),
size: 4_096,
mediaType: "audio/wav",
};
const finalArtifact = {
kind: "blob" as const,
- resource: fixtureResource("render-hyperframes:final-video"),
+ resource: fixtureResource("html-video:final-video"),
size: 16_441,
mediaType: "video/mp4",
};
const endpoints = new EndpointRegistry();
endpoints.registerImmediateEndpoint(
- "example.hyperframes.local",
- renderHyperframesCapabilities.renderVisual,
- mediaTypes.renderedVisual,
+ "example.html.local",
+ htmlProgramCapabilities.rasterizeVisual,
+ mediaTypes.timelineVisual,
({ need }) => {
const request = need.constraints as {
- readonly document: ReturnType<typeof compileHyperframesDocument>;
+ readonly program: ReturnType<typeof compileHtmlProgram>;
};
return {
- value: stored(sealRenderedVisual({
- frameRate: request.document.frameRate,
- frameCount: request.document.frameCount,
- canvas: request.document.canvas,
+ value: stored(sealTimelineVisual({
+ frameRate: request.program.frameRate,
+ frameCount: request.program.frameCount,
+ canvas: request.program.canvas,
artifact: visualArtifact,
})),
};
@@ -208,7 +206,7 @@ test("separate visual, audio and mux Endpoints complete one author-visible rende
);
endpoints.registerImmediateEndpoint(
"example.media.audio-real",
- mediaPipelineCapabilities.renderAudio,
+ mediaOperationsCapabilities.renderAudio,
mediaTypes.timelineAudio,
({ need }) => {
const request = need.constraints as { contract: string; plan: ReturnType<typeof compileAudioProgramPlan> };
@@ -222,10 +220,10 @@ test("separate visual, audio and mux Endpoints complete one author-visible rende
);
endpoints.registerImmediateEndpoint(
"example.media.mux",
- mediaPipelineCapabilities.mux,
+ mediaOperationsCapabilities.mux,
mediaTypes.muxed,
({ need }) => {
- const request = need.constraints as { visual: ReturnType<typeof sealRenderedVisual>; audio: ReturnType<typeof sealTimelineAudio> };
+ const request = need.constraints as { visual: ReturnType<typeof sealTimelineVisual>; audio: ReturnType<typeof sealTimelineAudio> };
return {
value: stored(sealMuxedMedia({
frameRate: request.visual.frameRate,
@@ -237,36 +235,36 @@ test("separate visual, audio and mux Endpoints complete one author-visible rende
};
},
);
- const result = await new NodeDriver({
+ const result = await new Executor({
producers: producerRegistry(),
endpoints,
validators: validatorRegistry(),
}).run(build());
assert.equal(result.status, "complete");
const video = result.state.records.find((record) =>
- record.type.module.name === artifactTypes.blob.module.name
- && record.type.name === artifactTypes.blob.name
+ record.type.module.name === blobTypes.blob.module.name
+ && record.type.name === blobTypes.blob.name
&& record.value.kind === "blob"
&& record.value.resource === finalArtifact.resource);
- assert(video, "missing final BlobArtifact");
+ assert(video, "missing final Blob");
assert.deepEqual(video.value, finalArtifact);
});
test("a render Product with another frame domain is rejected by the explicit downstream join", async () => {
- const document = compileHyperframesDocument(composition, space);
+ const document = compileHtmlProgram(composition, space);
const endpoints = new EndpointRegistry();
endpoints.registerImmediateEndpoint(
- "example.hyperframes.wrong-domain",
- renderHyperframesCapabilities.renderVisual,
- mediaTypes.renderedVisual,
+ "example.html.wrong-domain",
+ htmlProgramCapabilities.rasterizeVisual,
+ mediaTypes.timelineVisual,
() => ({
- value: stored(sealRenderedVisual({
+ value: stored(sealTimelineVisual({
frameRate: document.frameRate,
frameCount: document.frameCount + 1,
canvas: document.canvas,
artifact: {
kind: "blob",
- resource: fixtureResource("render-hyperframes:wrong-domain"),
+ resource: fixtureResource("html-video:wrong-domain"),
size: 1,
mediaType: "video/mp4",
},
@@ -275,7 +273,7 @@ test("a render Product with another frame domain is rejected by the explicit dow
);
endpoints.registerImmediateEndpoint(
"example.media.audio-for-domain-check",
- mediaPipelineCapabilities.renderAudio,
+ mediaOperationsCapabilities.renderAudio,
mediaTypes.timelineAudio,
({ need }) => {
const request = need.constraints as { readonly plan: ReturnType<typeof compileAudioProgramPlan> };
@@ -283,7 +281,7 @@ test("a render Product with another frame domain is rejected by the explicit dow
value: stored(sealTimelineAudio({
artifact: {
kind: "blob",
- resource: fixtureResource("render-hyperframes:domain-check-audio"),
+ resource: fixtureResource("html-video:domain-check-audio"),
size: 1,
mediaType: "audio/wav",
},
@@ -292,7 +290,7 @@ test("a render Product with another frame domain is rejected by the explicit dow
};
},
);
- const result = await new NodeDriver({
+ const result = await new Executor({
producers: producerRegistry(),
endpoints,
validators: validatorRegistry(),
@@ -317,21 +315,21 @@ const fixtureManifest: ModuleManifest = {
producers: [],
};
-function source(text: string): AuthorSourceUnit {
- return {
+function source(text: string): ResolvedSource {
+ return resolveSelfDescribedTextSource({
id: "/project/main.svml",
name: "main.svml",
text: `<?svml using="@hypit/markup@1"?>\n${text}`,
- };
+ });
}
for (const selectedRange of [false, true]) {
-test(`the ${selectedRange ? "selected" : "full"} rendered video remains an ordinary BlobArtifact for downstream components`, async () => {
+test(`the ${selectedRange ? "selected" : "full"} rendered video remains an ordinary Blob for downstream components`, async () => {
const sourceClosure = createResolvedClosure([
...videoContractManifests,
- hyperframesManifest,
- mediaPipelineManifest,
- renderHyperframesManifest,
+ htmlProgramManifest,
+ mediaOperationsManifest,
+ htmlVideoManifest,
fixtureManifest,
]);
const surfaces = new MarkupSurfaceRegistry();
@@ -344,31 +342,31 @@ test(`the ${selectedRange ? "selected" : "full"} rendered video remains an ordin
fragments: [],
}) });
surfaces.registerStructured({
- module: renderHyperframesModuleRef,
- declaration: renderHyperframesMarkupSurfaces.find((item) => item.name === "video")!,
- handler: decodeHyperframesRenderSurface,
+ module: htmlVideoModuleRef,
+ declaration: htmlVideoMarkupSurfaces.find((item) => item.name === "video")!,
+ handler: decodeHtmlVideoSurface,
});
surfaces.registerStructured({
- module: mediaPipelineModuleRef,
- declaration: mediaPipelineMarkupSurfaces.find((item) => item.name === "extract-frame")!,
+ module: mediaOperationsModuleRef,
+ declaration: mediaOperationsMarkupSurfaces.find((item) => item.name === "extract-frame")!,
handler: decodeExtractFrameSurface,
});
const frontends = new AuthorFrontendRegistry();
frontends.register(createMarkupAuthorFrontend({
registry: surfaces,
resolveModule(request) {
- if (request.from.startsWith("@hypit/render-hyperframes")) return renderHyperframesModuleRef;
- if (request.from.startsWith("@hypit/media-pipeline")) return mediaPipelineModuleRef;
+ if (request.from.startsWith("@hypit/html-video")) return htmlVideoModuleRef;
+ if (request.from.startsWith("@hypit/media-operations")) return mediaOperationsModuleRef;
return fixtureModule;
},
}));
const compiled = await compileSourceClosure({
entry: source(`<svml>
<import as="fixture" from="example.composition-fixture@1"/>
- <import as="render" from="@hypit/render-hyperframes@1"/>
- <import as="media" from="@hypit/media-pipeline@1"/>
+ <import as="html" from="@hypit/html-video@1"/>
+ <import as="media" from="@hypit/media-operations@1"/>
<fixture:Composition/>
- <render:Video id="final" composition={composition} timeline={semantic} ${selectedRange ? 'start-frame="15" end-frame-exclusive="45"' : ""}/>
+ <html:Video id="final" composition={composition} timeline={semantic} ${selectedRange ? 'start-frame="15" end-frame-exclusive="45"' : ""}/>
<media:ExtractFrame id="poster" source={final.video} video="primary-moving" at="last"/>
</svml>`),
closure: sourceClosure,
@@ -378,20 +376,20 @@ test(`the ${selectedRange ? "selected" : "full"} rendered video remains an ordin
},
admitRecord: createRecordAdmitter(validatorRegistry()),
});
- const target = resolveCompiledSourceExport(compiled, "poster.image", artifactTypes.blob);
+ const target = resolveCompiledSourceExport(compiled, "poster.image", blobTypes.blob);
assert.equal(target.ref.kind, "logical-output");
const state = start(compiled.program, compiled.graph, sealBuildRequest({
targets: [{ output: target.ref.kind === "logical-output" ? target.ref.id : "" }],
}));
assert.deepEqual(state.plan.steps.map((step) => step.producer.name).sort(), [
- hyperframesProducers.compile.name,
- selectedRange ? renderHyperframesProducers.requestVisualRange.name : renderHyperframesProducers.requestVisual.name,
- mediaPipelineProducers.planAudio.name,
- selectedRange ? mediaPipelineProducers.renderAudioRange.name : mediaPipelineProducers.renderAudio.name,
- mediaPipelineProducers.mux.name,
- mediaPipelineProducers.projectMuxed.name,
- mediaPipelineProducers.inspect.name,
- mediaPipelineProducers.extractFrame.name,
+ htmlProgramProducers.compile.name,
+ selectedRange ? htmlProgramProducers.requestVisualRange.name : htmlProgramProducers.requestVisual.name,
+ mediaOperationsProducers.planAudio.name,
+ selectedRange ? mediaOperationsProducers.renderAudioRange.name : mediaOperationsProducers.renderAudio.name,
+ mediaOperationsProducers.mux.name,
+ mediaOperationsProducers.projectMuxed.name,
+ mediaOperationsProducers.inspect.name,
+ mediaOperationsProducers.extractFrame.name,
].sort());
});
}
@@ -402,7 +400,7 @@ test("selected render frames reach both visual and audio Needs through the ordin
const rangeRecord = await admitRecord(closure, sealRecord({ id: "selection", type: mediaTypes.frameRange,
value: stored(range) }), validatorRegistry());
const program = link(closure, [compositionRecord, spaceRecord, rangeRecord]);
- const fragment = createRenderHyperframesFragment(true);
+ const fragment = createHtmlVideoFragment(true);
const selected = elaborateGraphFragment(program, fragment, {
id: "selected", fragment: fragment.id, inputs: {
composition: { kind: "record", id: compositionRecord.id },
@@ -411,11 +409,11 @@ test("selected render frames reach both visual and audio Needs through the ordin
},
});
const selectedGraph = sealCompiledGraph(bindAuthorFragment(selected, { video: "selected.video" }));
- const result = await new NodeDriver({ producers: producerRegistry(), validators: validatorRegistry() }).run(
+ const result = await new Executor({ producers: producerRegistry(), validators: validatorRegistry() }).run(
start(program, selectedGraph, sealBuildRequest({ targets: [{ output: "selected.video" }] })),
);
assert.equal(result.state.needs.length, 2);
for (const need of result.state.needs) assert.deepEqual((need.constraints as { range: unknown }).range, range);
- assert.throws(() => hyperframesVisualRequest(compileHyperframesDocument(composition, space),
+ assert.throws(() => htmlRasterRequest(compileHtmlProgram(composition, space),
{ range: { startFrame: 0, endFrameExclusive: 61 } }), /frame range/);
});
diff --git a/packages/hyperframes/README.md b/packages/hyperframes/README.md
deleted file mode 100644
index 180fb75d..00000000
--- a/packages/hyperframes/README.md
+++ /dev/null
@@ -1,132 +0,0 @@
-# @hypit/hyperframes
-
-Deterministic reference lowering from the generic `Composition` contract to a portable
-`HyperframesDocument`.
-
-This package renders `hypit.visual-ir@1` structural elements and `hypit.browser-program@1`
-local programs. Structural elements cover ordinary boxes, exact-font text and frame-sampled media.
-A browser program carries HTML, CSS and frame-driven JavaScript for a component's own composition.
-Track and Composition remain owned by `@hypit/composition`; the browser format is owned here.
-
-This package understands only `VisualTrack`, `Timeline` and canvas geometry. It
-does not know Caption, Speech, B-roll, Seedance or any other author-domain component. It flattens
-every Track's Presents, orders them by absolute `z`, stable Track identity, Track-local Present
-`order` and Present identity, then emits frame-bound local
-keyframes. An authoring Track never becomes an isolated render stacking surface.
-Terminal text and SVG mask sources retain the same Present-relative frame animations as other
-elements, including direct seeks into the middle of a Present.
-
-It deliberately ignores `AudioTrack`. HyperFrames produces a silent visual fact; the media pipeline
-compiles and renders program audio separately, then an explicit mux Provider joins the two. Changing
-audio can therefore never be implemented by secretly changing HyperFrames HTML or its renderer.
-
-Media remains resource-referenced in compiled HTML as `hypit-resource://` placeholders. Each
-document Artifact declaration carries its complete `BlobRef` (Resource id, byte count and MIME) and
-the compiler's conservative usage proof: `always`, or ordered absolute half-open frame spans. Direct
-image, video and typed Surface uses inherit their Present spans; repeated spans merge. Document-level
-fonts and opaque Browser Program dependencies remain `always`. This fact belongs to the compiled
-HyperFrames document, not Core, a worker partition or a cross-render registry. A local or hosted
-render Runtime calls `materializeHyperframesHtml()` with its own Artifact URL resolver before
-handing the HTML to HyperFrames. That environment-specific materialization is not a new compiled
-Record and does not change the compiled document.
-
-For observation of already materialized HTML, `HyperframesHtmlProject` carries the HTML and the
-BlobRefs addressed by its media/font URLs. `hyperframesHtmlDomain` reads the compiler's exact root
-frame clock and canvas; `stageHyperframesHtmlProject` stages those resources. This input does not
-reconstruct a Composition or invent typed Surface facts from HTML. A caller with the original
-`HyperframesDocument`, such as Studio, should pass that document to preserve all declared dependencies,
-including resources embedded in browser-program data. The document remains the complete typed input.
-Staging assigns short local filenames; opaque Resource IDs are never interpreted as filesystem
-paths or filenames, so their length and punctuation do not restrict the host filesystem.
-`stageHyperframesProject` streams each asset into its staged file. Its `validateSurface(surface, path,
-signal)` callback borrows that completed file during inspection; it receives neither a whole-file
-byte copy nor ownership of the file. The staging caller keeps the directory alive until all work
-has settled, including cancellation. `maxConcurrentArtifacts` bounds complete read/write/inspection
-lifecycles and defaults to one; a deployment Provider may supply its own local policy. Failure stops
-new claims and drains the already-started lifecycles before cleanup.
-When `frameSelection` is supplied, staging reads only `always` Artifacts and frame-scoped Artifacts
-whose usage intersects the whole render selection. All workers share that one staged project. Stable
-local names still derive from the complete document order, so selection does not renumber resources.
-Unselected structural media remain inert and are removed by the compiled page before their missing
-local paths could be activated. Unknown or opaque usage is never guessed into a narrower scope.
-`selectHyperframesArtifacts(document, selection)` exposes the same pure projection to callers that
-must transport bytes before staging; the Studio snapshot CLI uses it rather than eagerly fetching
-every Document resource. Selection validation is one ordered pass, and each Artifact's canonical
-usage spans query a sparse selection by binary search instead of scanning every requested frame.
-
-The document exposes its render domain directly rather than asking an Endpoint to scrape HTML:
-exact rational `frameRate`, integer `frameCount`, and canvas dimensions are explicit document
-content. The Timeline relationship is an input edge of the Producer and is not copied into the
-document as lineage metadata. Legal frame addresses are exactly `[0, frameCount)`. A local worker pool or a
-hosted renderer may independently evaluate any legal frame or half-open chunk; partition size and
-worker count are Runtime policy, not author intent and not Core graph nodes. The emitted root also
-uses the rational HyperFrames `data-fps` form, so NTSC rates do not drift through a decimal guess.
-
-A renderer may install `hyperframesFrameSelectionPrelude()` before the compiled page scripts to
-describe this render's ordered union of absolute half-open frame spans. The page-private animation,
-Terminal Text, visibility and Browser Program adapters use that hint to avoid initializing work
-whose Present cannot be sampled. Absence of the hint means the whole document, so ordinary browser
-preview remains unchanged. The hint contains no Worker identity or batch cursor: every Worker can
-start at any selected frame, and correctness still comes from absolute-frame evaluation.
-
-The compiled page also derives a capture scope from the same selection. Compiler-owned image,
-video, Surface and SVG-image URLs remain inert while HTML is parsed. After the page has classified
-Presents, only resources inside selected roots receive live `src`/`href` attributes; unselected
-roots are made non-painting, stripped of any remaining direct media URL attributes and detached
-from the live document before DOMContentLoaded. Opaque Browser Program HTML/CSS is not rewritten.
-Selected Present roots and document-level shared definitions are exposed to a capture adapter as
-generic DOM roots; the adapter does not need
-to understand Present or frame semantics. Shared glyph filter definitions live outside temporal
-Present roots so detaching one Present cannot break another Present's `url(#id)` reference. Local
-masks, paths and Browser Program structure remain within their owning Present. This is an
-execution-local projection of the complete compiled document, not a partial Composition, a Worker
-partition or a Core protocol. Without an injected selection, every Present remains live and every
-compiler-owned media URL is activated, preserving ordinary browser preview.
-
-Exact `FontArtifactRef` dependencies lower to generated `@font-face` declarations with font
-synthesis disabled; a Unicode-range-sharded logical face emits one rule per exact source. Terminal
-text without a non-empty exact Font stack is invalid rather than falling back to machine fonts.
-`CompositableSurfaceRef` values lower as typed image/video surfaces carrying
-their declared alpha, color-space and frame-domain metadata. The package never guesses either fact
-from a user font name or filename extension. The document carries a deduplicated typed Surface set
-beside its Artifact set so a staging Runtime can verify the exact bytes before rendering.
-
-The ordinary test suite validates deterministic HTML, frame sampling markers and Artifact collection.
-The local Provider owns the Chrome integration tests. Run its tests with `HYPIT_BROWSER_TESTS=1`
-to exercise real multi-worker rendering, compare selected video frames with a full render, and check
-straight-alpha composition. These tests use the engine capture API and require Chrome and FFmpeg.
-
-## Local browser programs
-
-`browserProgram({ html, css, setup, data }, artifacts)` builds a program payload. Place it on a
-`kind: "program"` VisualElement inside a normal Present. `html` is a local fragment; `{{child-id}}`
-places a direct typed child. Every child is placed once, including sampled video and exact-font text.
-This keeps actual video available to the renderer's exact source-frame preparation.
-
-CSS is scoped to the generated program root with `@scope`; `:scope` styles that root. The HTML can
-contain arbitrary local structure, SVG, internal stacking, masks and backdrop filters.
-CSS scope does not isolate HTML/SVG IDs. Use classes or data attributes for local queries; when an
-SVG needs an ID for `url(#...)` or `href`, derive it from the unique `root.id` in `setup` and set both
-the definition and its references there. Reusable instances must not repeat hard-coded SVG IDs.
-
-The optional `setup` string is a JavaScript function body with `root` and `data` arguments. It returns a synchronous
-`render(localFrame)` function. Initial load establishes every selected root's boundary pose; later `hf-seek`
-events use the page-private absolute-frame index to visit only active Programs and Present spans
-crossed by that seek. Outside the Present's lifetime, the dispatcher settles the boundary pose once
-instead of repeatedly scanning and updating every invisible Program. Active seeks always redraw,
-including the same frame after resources become ready, and seeking back into the Present computes its requested pose directly. Prepare stable
-objects in `setup`; express animation state as a function of frame and inputs so any worker can
-begin at any frame. Async work belongs to
-material preparation before rendering; browser resources belong in the program's declared artifacts.
-Use `hyperframesResourceUri(artifact.resource)` in resource-bearing markup or CSS.
-Returning a Promise from `render` reports an authoring error; frame capture never waits for an
-unbounded asynchronous drawing task or races it.
-
-Ordinary child sampling follows the Present clock. Reframing the parent leaves source playback
-unchanged. Components receive ordinary normalized media, absolute Windows and explicit sampling when
-they need prepared footage; target and source spans follow that authored relation. Speech audio is an
-independently selected Audio Track.
-
-`program.format` is explicit: this backend reports an unsupported format rather than interpreting
-another renderer's program. Core and the build graph do not contain browser-specific cases.
-The `examples/semantic-composition` project demonstrates a complete package using this interface.
diff --git a/packages/hyperframes/src/activation.ts b/packages/hyperframes/src/activation.ts
deleted file mode 100644
index c361231f..00000000
--- a/packages/hyperframes/src/activation.ts
+++ /dev/null
@@ -1,8 +0,0 @@
-import { hyperframesComponent, hyperframesManifest } from "./index.js";
-
-export const hypitPackage = {
- format: "hypit.node-package@1" as const,
- modules: [{ manifest: hyperframesManifest }],
- components: [hyperframesComponent],
-};
-export default hypitPackage;
diff --git a/packages/hyperframes/src/component.ts b/packages/hyperframes/src/component.ts
deleted file mode 100644
index 9966e1ab..00000000
--- a/packages/hyperframes/src/component.ts
+++ /dev/null
@@ -1,32 +0,0 @@
-import type { ComponentPackage } from "@hypit/component-kit";
-import type { Composition } from "@hypit/composition";
-import type { Timeline } from "@hypit/timeline";
-import type { CanonicalValue, StoredValue } from "@hypit/protocol";
-import { canonicalize } from "@hypit/protocol";
-
-import { compileHyperframesDocument } from "./document.js";
-import { hyperframesProducers } from "./manifest.js";
-
-function inline(value: StoredValue, subject: string): CanonicalValue {
- if (value.kind !== "inline") throw new Error(`${subject} must be inline`);
- return value.value;
-}
-
-/** Trusted deterministic lowering only; this component never renders frames or reads Artifacts. */
-export const hyperframesComponent = {
- producers: [{
- producer: hyperframesProducers.compile,
- handler: ({ inputs }) => ({
- outputs: {
- document: {
- kind: "inline",
- value: canonicalize(compileHyperframesDocument(
- inline(inputs.composition!.value, "Composition") as unknown as Composition,
- inline(inputs.timeline!.value, "Timeline") as unknown as Timeline,
- )),
- },
- },
- needs: {},
- }),
- }],
-} satisfies ComponentPackage;
diff --git a/packages/hyperframes/src/html-project.ts b/packages/hyperframes/src/html-project.ts
deleted file mode 100644
index 60515279..00000000
--- a/packages/hyperframes/src/html-project.ts
+++ /dev/null
@@ -1,99 +0,0 @@
-import type { BlobRef } from "@hypit/protocol";
-import { isResourceId } from "@hypit/protocol";
-import type { HyperframesCanvas, HyperframesFrameDomain } from "./types.js";
-
-/** An already materialized HTML programme and the local files its URLs address. */
-export type HyperframesHtmlProject = {
- readonly html: string;
- readonly assets: readonly { readonly url: string; readonly artifact: BlobRef }[];
-};
-
-/** Read the exact clock emitted by this package. Seconds never reconstruct frame identity. */
-export function hyperframesHtmlDomain(html: string): HyperframesFrameDomain & { readonly canvas: HyperframesCanvas } {
- const attributeValue = (tag: string, name: string): string | undefined => {
- const marker = `${name}="`;
- for (let at = tag.indexOf(marker); at !== -1; at = tag.indexOf(marker, at + marker.length)) {
- const previous = tag[at - 1];
- if (previous === undefined || !" \t\r\n\f".includes(previous)) continue;
- const start = at + marker.length;
- const end = tag.indexOf('"', start);
- return end === -1 ? undefined : tag.slice(start, end);
- }
- return undefined;
- };
- let root: string | undefined;
- for (let at = html.indexOf("<div"); at !== -1; at = html.indexOf("<div", at)) {
- const end = html.indexOf(">", at + 4);
- if (end === -1) break;
- const tag = html.slice(at, end + 1);
- at = end + 1;
- if (attributeValue(tag, "data-composition-id") === undefined) continue;
- if (root !== undefined) throw new Error("Snapshot HTML needs exactly one compiled HyperFrames composition root");
- root = tag;
- }
- if (root === undefined) throw new Error("Snapshot HTML needs exactly one compiled HyperFrames composition root");
- const attribute = (name: string) => {
- const value = attributeValue(root, name);
- if (value === undefined) throw new Error(`Snapshot HTML lacks ${name}; use the compiled HyperFrames HTML`);
- return value;
- };
- const positive = (value: string, name: string) => {
- const number = Number(value);
- if (!/^\d+$/u.test(value) || !Number.isSafeInteger(number) || number <= 0) throw new Error(`Invalid HyperFrames ${name}`);
- return number;
- };
- const fps = attribute("data-fps").split("/");
- if (fps.length > 2) throw new Error("HyperFrames data-fps must be an exact rational");
- return {
- frameRate: { numerator: positive(fps[0]!, "frame rate"), denominator: positive(fps[1] ?? "1", "frame rate denominator") },
- frameCount: positive(attribute("data-hypit-frame-count"), "frame count"),
- canvas: { width: positive(attribute("data-width"), "width"), height: positive(attribute("data-height"), "height") },
- };
-}
-
-function unescape(value: string): string {
- return value.replaceAll("&quot;", '"').replaceAll("&#39;", "'").replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&amp;", "&");
-}
-
-/** Resource URL positions in the compiler's self-contained HTML (inline JS and CSS). */
-export function mapHyperframesHtmlUrls(html: string, map: (url: string) => string): string {
- const escape = (value: string) => value.replaceAll("&", "&amp;").replaceAll('"', "&quot;");
- const cssUrls = (css: string) => css.replace(/url\(\s*(["']?)([^)"']+)\1\s*\)/gu,
- (_all, _quote: string, url: string) => `url("${map(url.trim()).replaceAll("\\", "\\\\").replaceAll('"', '\\"')}")`);
- return html.replace(/<style\b([^>]*)>([\s\S]*?)<\/style>/gu,
- (_all, attributes: string, css: string) => `<style${attributes}>${cssUrls(css)}</style>`)
- .replace(/<[a-z][^>]*>/gu, tag => {
- const attributes = /^(?:<(?:img|video|source|image|use|script|link)\b)/u.test(tag)
- ? tag.replace(/\s(src|poster|href|data-hypit-resource-src|data-hypit-resource-href)="([^"]*)"/gu,
- (_all, key: string, url: string) => ` ${key}="${escape(map(unescape(url)))}"`) : tag;
- return attributes.replace(/\sstyle="([^"]*)"/gu,
- (_all, css: string) => ` style="${escape(cssUrls(unescape(css)))}"`);
- });
-}
-
-export function hyperframesHtmlAssetUrls(html: string): readonly string[] {
- const urls = new Set<string>();
- mapHyperframesHtmlUrls(html, url => {
- if (url !== "" && !url.startsWith("#") && !url.startsWith("data:")) urls.add(url);
- return url;
- });
- return [...urls];
-}
-
-export function assertHyperframesHtmlProject(value: unknown): asserts value is HyperframesHtmlProject {
- const project = value as HyperframesHtmlProject;
- if (!project || typeof project.html !== "string" || !Array.isArray(project.assets)) throw new Error("HyperFrames HTML project needs html and assets");
- hyperframesHtmlDomain(project.html);
- if (/hypit-resource:\/\//u.test(project.html)) throw new Error("HTML still has unresolved resources; materialize its HyperframesDocument first");
- const urls = new Set<string>();
- for (const asset of project.assets) {
- const blob = asset?.artifact;
- if (typeof asset?.url !== "string" || urls.has(asset.url) || blob?.kind !== "blob" || !isResourceId(blob.resource)
- || !Number.isSafeInteger(blob.size) || blob.size < 0 || typeof blob.mediaType !== "string" || !blob.mediaType) {
- throw new Error("Invalid or repeated HyperFrames HTML asset");
- }
- urls.add(asset.url);
- }
- const referenced = hyperframesHtmlAssetUrls(project.html);
- if (referenced.length !== urls.size || referenced.some(url => !urls.has(url))) throw new Error("HyperFrames HTML assets must address its referenced URLs");
-}
diff --git a/packages/hyperframes/src/index.ts b/packages/hyperframes/src/index.ts
deleted file mode 100644
index 0dd2de21..00000000
--- a/packages/hyperframes/src/index.ts
+++ /dev/null
@@ -1,16 +0,0 @@
-export { hyperframesDocumentFragment } from "./fragment.js";
-export { hyperframesComponent } from "./component.js";
-export { assertHyperframesDocument, assertHyperframesFrameIndex, assertHyperframesFrameSpan, compileHyperframesDocument, hyperframesResourceUri, hyperframesTime, materializeHyperframesHtml, selectHyperframesArtifacts } 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";
-export { hyperframesFrameSelectionPrelude } from "./frame-work.js";
-export { assertHyperframesHtmlProject, hyperframesHtmlDomain, hyperframesHtmlAssetUrls, mapHyperframesHtmlUrls } from "./html-project.js";
-export type { HyperframesHtmlProject } from "./html-project.js";
diff --git a/packages/hyperframes/src/manifest.ts b/packages/hyperframes/src/manifest.ts
deleted file mode 100644
index 3bbd7dbb..00000000
--- a/packages/hyperframes/src/manifest.ts
+++ /dev/null
@@ -1,79 +0,0 @@
-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";
-import { timelineDependency, timelineTypes } from "@hypit/timeline";
-
-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: {
- artifact: { schema: { kind: "object", fields: {
- kind: { schema: { kind: "literal", value: "blob" } },
- resource: { schema: resource },
- size: { schema: nonNegativeInteger },
- mediaType: { schema: { kind: "string", minLength: 1 } },
- } } },
- usage: { schema: { kind: "oneOf", variants: [
- { kind: "object", fields: { kind: { schema: { kind: "literal", value: "always" } } } },
- { kind: "object", fields: {
- kind: { schema: { kind: "literal", value: "frames" } },
- spans: { schema: { kind: "array", minItems: 1, items: { kind: "object", fields: {
- startFrame: { schema: nonNegativeInteger },
- endFrameExclusive: { schema: positiveInteger },
- } } } },
- } },
- ] } },
- },
- } } },
- 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, timelineDependency],
- types: [{ name: hyperframesTypes.document.name }],
- capabilities: [],
- producers: [{
- name: hyperframesProducers.compile.name,
- inputs: [
- { name: "composition", type: compositionTypes.composition },
- { name: "timeline", type: timelineTypes.timeline },
- ],
- outputs: [{ name: "document", type: hyperframesTypes.document }],
- needs: [],
- }],
-};
diff --git a/packages/hyperframes/test/html-project.test.ts b/packages/hyperframes/test/html-project.test.ts
deleted file mode 100644
index 6f0ee7ee..00000000
--- a/packages/hyperframes/test/html-project.test.ts
+++ /dev/null
@@ -1,27 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-import { hyperframesHtmlAssetUrls, hyperframesHtmlDomain, mapHyperframesHtmlUrls } from "../src/index.js";
-
-test("materialized composition HTML retains its exact frame domain", () => {
- const root = '<div data-composition-id="main" data-width="1080" data-height="1920" data-fps="30000/1001" data-hypit-frame-count="90">';
- assert.deepEqual(hyperframesHtmlDomain(`<style>.a{color:red}</style>${root}</div>`), {
- frameRate: { numerator: 30000, denominator: 1001 },
- frameCount: 90,
- canvas: { width: 1080, height: 1920 },
- });
- assert.throws(() => hyperframesHtmlDomain(`${root}</div>${root}</div>`), /exactly one compiled HyperFrames composition root/u);
-});
-
-test("materialized HTML preserves CSS attribute quoting and internal SVG references while relocating media", () => {
- const html = '<style>@font-face{src:url("./font.woff2")}</style><div style="background-image:url(&quot;./picture.png&quot;);filter:url(#mask)">'
- + '<img src="./picture.png"><img data-hypit-resource-src="./later.png">'
- + '<svg><image data-hypit-resource-href="./mask.png"/></svg><a href="https://example.org">link</a></div>';
- assert.deepEqual(hyperframesHtmlAssetUrls(html), ["./font.woff2", "./picture.png", "./later.png", "./mask.png"]);
- const mapped = mapHyperframesHtmlUrls(html, url => url.startsWith("./") ? `./assets/${url.slice(2)}` : url);
- assert.match(mapped, /background-image:url\(&quot;\.\/assets\/picture.png&quot;\)/u);
- assert.match(mapped, /filter:url\(&quot;#mask&quot;\)/u);
- assert.match(mapped, /src="\.\/assets\/picture.png"/u);
- assert.match(mapped, /data-hypit-resource-src="\.\/assets\/later.png"/u);
- assert.match(mapped, /data-hypit-resource-href="\.\/assets\/mask.png"/u);
- assert.match(mapped, /href="https:\/\/example.org"/u);
-});
diff --git a/packages/provider-html-local/README.md b/packages/provider-html-local/README.md
new file mode 100644
index 00000000..dc0efdf2
--- /dev/null
+++ b/packages/provider-html-local/README.md
@@ -0,0 +1,94 @@
+# @hypit/provider-html-local
+
+Trusted local implementation of:
+
+- `@hypit/html-program@1#rasterize-visual` → `TimelineVisual`;
+- `@hypit/html-program@1#rasterize-frames` → ordered PNG BlobRefs.
+
+The Provider consumes the typed `HtmlProgram` directly. It serves the staged
+program to independent Puppeteer/Chrome processes, applies absolute integer
+frames through `window.__hypitFrameProgram`, decodes compiler-declared source
+video frames with FFmpeg, captures PNG pixels through Chrome DevTools Protocol,
+and streams ordered frames into one H.264 encoder. It has no external HTML video
+engine or producer dependency.
+
+Filesystem staging is private to this local Provider. `@hypit/html-program`
+retains only the portable program and its pure materialization function; it
+does not expose a Node project/staging subpath for hypothetical executors.
+Inspection of staged Compositable Surface files and probing the selected media
+tools are private here for the same reason: they validate inputs used by this
+executor and do not establish a shared media-execution ABI.
+
+## Runtime boundary
+
+The Endpoint facet is `rasterize`. Runtime configuration owns deployment policy:
+
+- `workers`: fixed browser count or `auto`;
+- `maxWorkers`: automatic ceiling;
+- `defaultConcurrency`: whole requests admitted in this Endpoint pool;
+- `browserCapacity`: Chrome slots reserved across admitted requests;
+- `chromePath`, or exact `browserVersion` plus `browserCacheDirectory`;
+- `ffmpegPath` and `ffprobePath`;
+- optional process/stage deadlines and byte budgets.
+
+The package recommendation is stored as `hypit.htmlBrowser.version`. Managed
+Chrome defaults to `~/.cache/hypit/html-rasterizer/chrome`; its ManagedProgram
+state is stored below `.hypit-html-browser-program`. Browser installation occurs
+only through explicit Runtime preparation:
+
+```sh
+hypit programs prepare --runtime ./hypit.runtime.json --endpoint html.local
+```
+
+Inspection and execution never search environment variables or silently choose a
+different system browser. `chromePath` selects a user-managed executable;
+`browserVersion` selects one exact managed Chrome for Testing version. The two
+selection modes are mutually exclusive.
+
+## Frame selection and parallelism
+
+A continuous request retains original absolute frame identities. A sparse request
+accepts strictly increasing, non-contiguous frames. Workers are independent
+browser processes and may start at any requested frame; they do not wait for an
+earlier worker to traverse the program.
+
+The compiler's typed `frameSources` plan determines exact source-video samples,
+including reverse, hold, loop and rational-rate mappings. The Provider probes
+needed sources, decodes bounded windows lazily, shares decoded frames only within
+the current execution, and leases them under `maxDecodedSourceBytes`. Chrome does
+not independently decode those same videos. Arbitrary author HTML is not parsed
+to infer source-time semantics.
+
+Completed PNGs enter a bounded ordered sink. FFmpeg is the necessary local
+serialization point for one MP4 stream, not a scheduler or shared metadata
+service. Capture of later frames can continue while earlier frames are encoded.
+Sparse frame output writes only requested PNGs and is bounded by
+`maxRenderedBytes`.
+
+## Lifecycle and failure
+
+Each request owns its temporary directory, localhost server, Chrome processes,
+decoded-frame store and encoder. Nothing is shared across requests. Cancellation
+or failure closes page sessions, source leases, processes and resource I/O.
+Process-tree cleanup is best effort after abnormal exits; hard OS termination
+requires containment supplied by the deployment.
+
+The executor waits for page frame listeners, declared fonts, dynamic image
+decodes and compositor settlement before accepting a screenshot. Readiness is
+scoped to compiler-published capture roots when available; real global stylesheet
+edits intentionally fall back to whole-document inspection.
+
+## Direct use
+
+```ts
+import { rasterizeHtmlProgram } from "@hypit/provider-html-local";
+
+const visual = await rasterizeHtmlProgram(
+ { program, range: { startFrame: 240, endFrameExclusive: 360 } },
+ { resources, workers: 4 },
+);
+```
+
+Omit `range` for the complete program. Audio is not part of this result;
+`@hypit/media-local` and the author assembly prepare audio and mux the
+final artifact.
diff --git a/packages/provider-html-local/package.json b/packages/provider-html-local/package.json
new file mode 100644
index 00000000..af17de50
--- /dev/null
+++ b/packages/provider-html-local/package.json
@@ -0,0 +1,43 @@
+{
+ "name": "@hypit/provider-html-local",
+ "version": "0.1.0",
+ "license": "SEE LICENSE IN LICENSE",
+ "private": true,
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "files": ["dist", "README.md"],
+ "hypit": {
+ "activation": "./src/activation.ts",
+ "htmlBrowser": {
+ "version": "152.0.7928.2"
+ }
+ },
+ "dependencies": {
+ "@puppeteer/browsers": "3.2.2",
+ "puppeteer-core": "25.10.0",
+ "tsx": "4.21.0"
+ },
+ "peerDependencies": {
+ "@hypit/hypit": "workspace:^",
+ "@hypit/runtime-local": "workspace:^"
+ },
+ "devDependencies": {
+ "@fontsource-variable/inter": "5.3.0",
+ "@hypit/caption-fine": "workspace:*",
+ "@hypit/composition": "workspace:*",
+ "@hypit/executor": "workspace:*",
+ "@hypit/endpoint": "workspace:*",
+ "@hypit/html-program": "workspace:*",
+ "@hypit/hypit": "workspace:*",
+ "@hypit/media": "workspace:*",
+ "@hypit/protocol": "workspace:*",
+ "@hypit/runtime": "workspace:*",
+ "@hypit/runtime-local": "workspace:*",
+ "@hypit/script": "workspace:*",
+ "@hypit/timeline": "workspace:*",
+ "@hypit/visual-track": "workspace:*",
+ "sharp": "0.35.4"
+ }
+}
diff --git a/packages/provider-hyperframes-local/src/activation.ts b/packages/provider-html-local/src/activation.ts
similarity index 70%
rename from packages/provider-hyperframes-local/src/activation.ts
rename to packages/provider-html-local/src/activation.ts
index e90403b0..543414fe 100644
--- a/packages/provider-hyperframes-local/src/activation.ts
+++ b/packages/provider-html-local/src/activation.ts
@@ -5,45 +5,45 @@ import {
runtimeConfigObject,
runtimeConfigPositiveInteger,
runtimeConfigString,
-} from "@hypit/runtime-kit";
+} from "@hypit/runtime-local/extension";
import {
diagnoseRuntimeExecutable,
resolveRuntimeExecutable,
-} from "@hypit/runtime-host-node";
+} from "@hypit/runtime-local/node";
-import { createLocalHyperframesProvider } from "./provider.js";
+import { createLocalHtmlProvider } from "./provider.js";
import { configuredBrowserPath, browserExecutablePath, selectedBrowserVersion } from "./browser.js";
-import type { HyperframesBrowserGpu, HyperframesQuality, HyperframesWorkers } from "./provider.js";
-import { localHyperframesBrowserProgram } from "./program.js";
+import type { HtmlBrowserGpu, HtmlQuality, HtmlWorkers } from "./provider.js";
+import { localHtmlBrowserProgram } from "./program.js";
-const localHyperframesRuntimeAdapter = createRuntimeEndpointAdapterFacet({
- use: "@hypit/provider-hyperframes-local",
+const localHTMLRuntimeAdapter = createRuntimeEndpointAdapterFacet({
+ use: "@hypit/provider-html-local",
activate(context) {
- if (context.pool === undefined) throw new Error("local HyperFrames Provider Pool is required");
- const config = runtimeConfigObject(context.config, "local HyperFrames");
+ if (context.pool === undefined) throw new Error("local HTML renderer Provider Pool is required");
+ const config = runtimeConfigObject(context.config, "local HTML renderer");
runtimeConfigExact(config, [
"nodePath", "chromePath", "browserVersion", "browserCacheDirectory", "browserDownloadBaseUrl", "ffprobePath", "ffmpegPath", "workers", "maxWorkers", "quality", "browserGpu",
"defaultConcurrency", "browserCapacity", "initializationTimeoutMs", "frameTimeoutMs", "processTimeoutMs", "maxProcessOutputBytes", "artifactStagingConcurrency", "maxPendingFrameBytes", "maxDecodedSourceBytes", "maxRenderedBytes",
- ], "local HyperFrames");
- runtimeConfigString(config.nodePath, "HyperFrames nodePath");
- runtimeConfigString(config.ffprobePath, "HyperFrames ffprobePath");
+ ], "local HTML renderer");
+ runtimeConfigString(config.nodePath, "HTML renderer nodePath");
+ runtimeConfigString(config.ffprobePath, "HTML renderer ffprobePath");
const workers = config.workers;
if (workers !== undefined && workers !== "auto") {
- runtimeConfigPositiveInteger(workers, "HyperFrames workers");
+ runtimeConfigPositiveInteger(workers, "HTML renderer workers");
}
- const quality = runtimeConfigString(config.quality, "HyperFrames quality");
+ const quality = runtimeConfigString(config.quality, "HTML renderer quality");
if (quality !== undefined && quality !== "draft" && quality !== "standard" && quality !== "high") {
- throw new Error("HyperFrames quality is invalid");
+ throw new Error("HTML renderer quality is invalid");
}
- const browserGpu = runtimeConfigString(config.browserGpu, "HyperFrames browserGpu");
+ const browserGpu = runtimeConfigString(config.browserGpu, "HTML renderer browserGpu");
if (browserGpu !== undefined && browserGpu !== "auto" && browserGpu !== "software" && browserGpu !== "hardware") {
- throw new Error("HyperFrames browserGpu is invalid");
+ throw new Error("HTML renderer browserGpu is invalid");
}
- const configuredNode = runtimeConfigString(config.nodePath, "HyperFrames nodePath");
- const configuredChrome = runtimeConfigString(config.chromePath, "HyperFrames chromePath");
- const browserVersion = runtimeConfigString(config.browserVersion, "HyperFrames browserVersion");
- const browserDownloadBaseUrl = runtimeConfigString(config.browserDownloadBaseUrl, "HyperFrames browserDownloadBaseUrl");
- const configuredCache = runtimeConfigString(config.browserCacheDirectory, "HyperFrames browserCacheDirectory");
+ const configuredNode = runtimeConfigString(config.nodePath, "HTML renderer nodePath");
+ const configuredChrome = runtimeConfigString(config.chromePath, "HTML renderer chromePath");
+ const browserVersion = runtimeConfigString(config.browserVersion, "HTML renderer browserVersion");
+ const browserDownloadBaseUrl = runtimeConfigString(config.browserDownloadBaseUrl, "HTML renderer browserDownloadBaseUrl");
+ const configuredCache = runtimeConfigString(config.browserCacheDirectory, "HTML renderer browserCacheDirectory");
const chromePath = configuredBrowserPath({ ...(configuredChrome === undefined ? {} : {
chromePath: resolve(context.dataRoot, configuredChrome),
}) });
@@ -53,34 +53,34 @@ const localHyperframesRuntimeAdapter = createRuntimeEndpointAdapterFacet({
...(chromePath === undefined ? {} : { chromePath }),
...(configuredCache === undefined ? {} : { browserCacheDirectory: resolve(context.dataRoot, configuredCache) }),
};
- const configuredFfprobe = runtimeConfigString(config.ffprobePath, "HyperFrames ffprobePath");
+ const configuredFfprobe = runtimeConfigString(config.ffprobePath, "HTML renderer ffprobePath");
const nodePath = resolveRuntimeExecutable(context.dataRoot, configuredNode ?? process.execPath);
- const configuredFfmpeg = runtimeConfigString(config.ffmpegPath, "HyperFrames ffmpegPath");
+ const configuredFfmpeg = runtimeConfigString(config.ffmpegPath, "HTML renderer ffmpegPath");
const ffmpegPath = resolveRuntimeExecutable(context.dataRoot, configuredFfmpeg ?? "ffmpeg");
const ffprobePath = resolveRuntimeExecutable(context.dataRoot, configuredFfprobe ?? "ffprobe");
- const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "HyperFrames defaultConcurrency");
- const maxWorkers = runtimeConfigPositiveInteger(config.maxWorkers, "HyperFrames maxWorkers");
- const browserCapacity = runtimeConfigPositiveInteger(config.browserCapacity, "HyperFrames browserCapacity");
- const initializationTimeoutMs = runtimeConfigPositiveInteger(config.initializationTimeoutMs, "HyperFrames initializationTimeoutMs");
- const frameTimeoutMs = runtimeConfigPositiveInteger(config.frameTimeoutMs, "HyperFrames frameTimeoutMs");
- const processTimeoutMs = runtimeConfigPositiveInteger(config.processTimeoutMs, "HyperFrames processTimeoutMs");
- const maxProcessOutputBytes = runtimeConfigPositiveInteger(config.maxProcessOutputBytes, "HyperFrames maxProcessOutputBytes");
- const artifactStagingConcurrency = runtimeConfigPositiveInteger(config.artifactStagingConcurrency, "HyperFrames artifactStagingConcurrency");
- const maxPendingFrameBytes = runtimeConfigPositiveInteger(config.maxPendingFrameBytes, "HyperFrames maxPendingFrameBytes");
- const maxDecodedSourceBytes = runtimeConfigPositiveInteger(config.maxDecodedSourceBytes, "HyperFrames maxDecodedSourceBytes");
- const maxRenderedBytes = runtimeConfigPositiveInteger(config.maxRenderedBytes, "HyperFrames maxRenderedBytes");
+ const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "HTML renderer defaultConcurrency");
+ const maxWorkers = runtimeConfigPositiveInteger(config.maxWorkers, "HTML renderer maxWorkers");
+ const browserCapacity = runtimeConfigPositiveInteger(config.browserCapacity, "HTML renderer browserCapacity");
+ const initializationTimeoutMs = runtimeConfigPositiveInteger(config.initializationTimeoutMs, "HTML renderer initializationTimeoutMs");
+ const frameTimeoutMs = runtimeConfigPositiveInteger(config.frameTimeoutMs, "HTML renderer frameTimeoutMs");
+ const processTimeoutMs = runtimeConfigPositiveInteger(config.processTimeoutMs, "HTML renderer processTimeoutMs");
+ const maxProcessOutputBytes = runtimeConfigPositiveInteger(config.maxProcessOutputBytes, "HTML renderer maxProcessOutputBytes");
+ const artifactStagingConcurrency = runtimeConfigPositiveInteger(config.artifactStagingConcurrency, "HTML renderer artifactStagingConcurrency");
+ const maxPendingFrameBytes = runtimeConfigPositiveInteger(config.maxPendingFrameBytes, "HTML renderer maxPendingFrameBytes");
+ const maxDecodedSourceBytes = runtimeConfigPositiveInteger(config.maxDecodedSourceBytes, "HTML renderer maxDecodedSourceBytes");
+ const maxRenderedBytes = runtimeConfigPositiveInteger(config.maxRenderedBytes, "HTML renderer maxRenderedBytes");
return {
- endpoint: createLocalHyperframesProvider({
+ endpoint: createLocalHtmlProvider({
instance: context.instance,
pool: context.pool,
nodePath,
...browser,
ffprobePath,
ffmpegPath,
- ...(workers === undefined ? {} : { workers: workers as HyperframesWorkers }),
+ ...(workers === undefined ? {} : { workers: workers as HtmlWorkers }),
...(maxWorkers === undefined ? {} : { maxWorkers }),
- ...(quality === undefined ? {} : { quality: quality as HyperframesQuality }),
- ...(browserGpu === undefined ? {} : { browserGpu: browserGpu as HyperframesBrowserGpu }),
+ ...(quality === undefined ? {} : { quality: quality as HtmlQuality }),
+ ...(browserGpu === undefined ? {} : { browserGpu: browserGpu as HtmlBrowserGpu }),
...(defaultConcurrency === undefined ? {} : { defaultConcurrency }),
...(browserCapacity === undefined ? {} : { browserCapacity }),
...(initializationTimeoutMs === undefined ? {} : { initializationTimeoutMs }),
@@ -92,7 +92,7 @@ const localHyperframesRuntimeAdapter = createRuntimeEndpointAdapterFacet({
...(maxDecodedSourceBytes === undefined ? {} : { maxDecodedSourceBytes }),
...(maxRenderedBytes === undefined ? {} : { maxRenderedBytes }),
}),
- program: localHyperframesBrowserProgram({
+ program: localHtmlBrowserProgram({
id: context.instance,
nodePath,
...browser,
@@ -100,7 +100,7 @@ const localHyperframesRuntimeAdapter = createRuntimeEndpointAdapterFacet({
ffmpegPath,
}),
diagnose: async () => [
- { severity: "info", code: "HYPERFRAMES_BROWSER_SELECTION", subject: context.instance,
+ { severity: "info", code: "HTML_BROWSER_SELECTION", subject: context.instance,
message: `${chromePath === undefined ? `Managed Chrome Headless Shell ${selectedBrowserVersion(browser)} (${browserVersion === undefined ? "Provider recommendation" : "Profile version"})` : "Profile browser"}: ${browserExecutablePath(browser)}` },
...await diagnoseRuntimeExecutable({ root: context.dataRoot, configured: configuredFfmpeg, fallback: "ffmpeg", subject: "FFmpeg" }),
...await diagnoseRuntimeExecutable({
@@ -121,8 +121,8 @@ const localHyperframesRuntimeAdapter = createRuntimeEndpointAdapterFacet({
});
export const hypitPackage = {
- format: "hypit.node-package@1" as const,
- hostFacets: [localHyperframesRuntimeAdapter],
+ format: "hypit.package@1" as const,
+ facets: [localHTMLRuntimeAdapter],
};
export default hypitPackage;
diff --git a/packages/provider-html-local/src/browser-install.ts b/packages/provider-html-local/src/browser-install.ts
new file mode 100644
index 00000000..5105cd2f
--- /dev/null
+++ b/packages/provider-html-local/src/browser-install.ts
@@ -0,0 +1,5 @@
+import { installHtmlBrowser } from "./browser.js";
+
+const [cacheDir, version, baseUrl] = process.argv.slice(2);
+if (process.argv.length < 4 || process.argv.length > 5 || !cacheDir || !version) throw new Error("Expected the HTML browser cache directory, exact version and optional archive base URL");
+await installHtmlBrowser(cacheDir, version, baseUrl);
diff --git a/packages/provider-hyperframes-local/src/browser.ts b/packages/provider-html-local/src/browser.ts
similarity index 77%
rename from packages/provider-hyperframes-local/src/browser.ts
rename to packages/provider-html-local/src/browser.ts
index e9f7b637..b892f3a1 100644
--- a/packages/provider-hyperframes-local/src/browser.ts
+++ b/packages/provider-html-local/src/browser.ts
@@ -6,14 +6,14 @@ import { homedir } from "node:os";
import { join, resolve } from "node:path";
import { Browser, computeExecutablePath, detectBrowserPlatform, getDownloadUrl, install, uninstall } from "@puppeteer/browsers";
-// The Provider's release owns this recommendation alongside its engine dependencies.
+// The Provider's release owns this recommendation alongside its browser integration.
// It is installation input, not a second browser discovery policy in executable code.
const manifest = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
-export const recommendedBrowserVersion: string = exactBrowserVersion(manifest.hypit?.renderBrowser?.version);
+export const recommendedBrowserVersion: string = exactBrowserVersion(manifest.hypit?.htmlBrowser?.version);
function exactBrowserVersion(value: unknown): string {
if (typeof value !== "string" || !/^\d+\.\d+\.\d+\.\d+$/u.test(value)) {
- throw new Error("HyperFrames browserVersion must be an exact four-part Chrome version; channels such as latest are not selections");
+ throw new Error("HTML renderer browserVersion must be an exact four-part Chrome version; channels such as latest are not selections");
}
return value;
}
@@ -30,14 +30,14 @@ export function browserDownloadBaseUrl(options: BrowserOptions): string | undefi
const value = options.browserDownloadBaseUrl;
if (value === undefined) return undefined;
if (options.chromePath !== undefined) {
- throw new Error("HyperFrames chromePath and browserDownloadBaseUrl are mutually exclusive; a user-managed browser is not downloaded");
+ throw new Error("HTML renderer chromePath and browserDownloadBaseUrl are mutually exclusive; a user-managed browser is not downloaded");
}
let url: URL;
try { url = new URL(value); } catch {
- throw new Error("HyperFrames browserDownloadBaseUrl must be an absolute HTTP(S) archive base URL");
+ throw new Error("HTML renderer browserDownloadBaseUrl must be an absolute HTTP(S) archive base URL");
}
if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
- throw new Error("HyperFrames browserDownloadBaseUrl must be an HTTP(S) archive base URL without credentials, query or fragment");
+ throw new Error("HTML renderer browserDownloadBaseUrl must be an HTTP(S) archive base URL without credentials, query or fragment");
}
return url.href.replace(/\/+$/u, "");
}
@@ -47,7 +47,7 @@ export function browserDownloadUrl(options: BrowserOptions): string {
const version = selectedBrowserVersion(options);
if (version === undefined) throw new Error("A user-managed browser has no download URL");
const platform = detectBrowserPlatform();
- if (platform === undefined) throw new Error("The managed render browser is unavailable for this host; select chromePath");
+ if (platform === undefined) throw new Error("The managed HTML browser is unavailable for this host; select chromePath");
return getDownloadUrl(Browser.CHROMEHEADLESSSHELL, platform, version, baseUrl).href;
}
@@ -55,9 +55,9 @@ export function browserDownloadUrl(options: BrowserOptions): string {
export function configuredBrowserPath(options: BrowserOptions): string | undefined {
browserDownloadBaseUrl(options);
if (options.chromePath !== undefined && options.browserVersion !== undefined) {
- throw new Error("HyperFrames chromePath and browserVersion are mutually exclusive");
+ throw new Error("HTML renderer chromePath and browserVersion are mutually exclusive");
}
- if (options.chromePath === "") throw new Error("HyperFrames chromePath must not be empty");
+ if (options.chromePath === "") throw new Error("HTML renderer chromePath must not be empty");
return options.chromePath === undefined ? undefined : resolve(options.chromePath);
}
@@ -67,7 +67,7 @@ export function selectedBrowserVersion(options: BrowserOptions): string | undefi
}
export function browserCacheDirectory(options: BrowserOptions): string {
- return resolve(options.browserCacheDirectory ?? join(homedir(), ".cache", "hyperframes", "chrome"));
+ return resolve(options.browserCacheDirectory ?? join(homedir(), ".cache", "hypit", "html-rasterizer", "chrome"));
}
export function browserExecutablePath(options: BrowserOptions): string {
@@ -79,7 +79,7 @@ export function browserExecutablePath(options: BrowserOptions): string {
browser: Browser.CHROMEHEADLESSSHELL, buildId: version, cacheDir: browserCacheDirectory(options),
});
} catch (error) {
- throw new Error("The managed render browser is unavailable for this host. Select an installed Chrome/Chromium with the Provider's chromePath.", { cause: error });
+ throw new Error("The managed HTML browser is unavailable for this host. Select an installed Chrome/Chromium with the Provider's chromePath.", { cause: error });
}
}
@@ -94,12 +94,12 @@ export async function requireBrowserExecutable(path: string, version?: string):
}
}
catch (error) {
- throw new Error(`Render browser is unavailable at ${path}: ${error instanceof Error ? error.message : String(error)}. Prepare the selected Runtime with hypit runtime up --runtime <profile>, or correct its chromePath.`, { cause: error });
+ throw new Error(`HTML browser is unavailable at ${path}: ${error instanceof Error ? error.message : String(error)}. Prepare the selected Runtime with hypit runtime up --runtime <profile>, or correct its chromePath.`, { cause: error });
}
}
/** Called only by the selected ManagedProgram's explicit installation command. */
-export async function installRenderBrowser(cacheDir: string, version: string, downloadBaseUrl?: string): Promise<void> {
+export async function installHtmlBrowser(cacheDir: string, version: string, downloadBaseUrl?: string): Promise<void> {
const buildId = exactBrowserVersion(version);
const options = { browserVersion: buildId, ...(downloadBaseUrl === undefined ? {} : { browserDownloadBaseUrl: downloadBaseUrl }) };
const baseUrl = browserDownloadBaseUrl(options);
diff --git a/packages/provider-hyperframes-local/src/capture-exit.ts b/packages/provider-html-local/src/capture-exit.ts
similarity index 82%
rename from packages/provider-hyperframes-local/src/capture-exit.ts
rename to packages/provider-html-local/src/capture-exit.ts
index 150bcc56..8a31fa28 100644
--- a/packages/provider-hyperframes-local/src/capture-exit.ts
+++ b/packages/provider-html-local/src/capture-exit.ts
@@ -1,8 +1,8 @@
import { writeSync } from "node:fs";
import { killRenderDescendantsSync } from "./process-tree.js";
-// Installed before loading the engine: process.exit and uncaught exceptions can
-// bypass async finally blocks, including during engine import/browser launch.
+// Installed before loading capture: process.exit and uncaught exceptions can
+// bypass async finally blocks, including during module import or browser launch.
// Keep cleanup inside the still-live owner, not a history of browser PIDs.
const cleanup = () => {
try { killRenderDescendantsSync(process.pid); }
diff --git a/packages/provider-hyperframes-local/src/capture-process.ts b/packages/provider-html-local/src/capture-process.ts
similarity index 76%
rename from packages/provider-hyperframes-local/src/capture-process.ts
rename to packages/provider-html-local/src/capture-process.ts
index b2bf6655..af9acbcf 100644
--- a/packages/provider-hyperframes-local/src/capture-process.ts
+++ b/packages/provider-html-local/src/capture-process.ts
@@ -1,9 +1,9 @@
-import type { ExecutionDiagnostic } from "@hypit/runtime";
+import type { ExecutionDiagnostic } from "@hypit/hypit/endpoint";
import { spawn } from "node:child_process";
import { fileURLToPath } from "node:url";
import { killRenderTree } from "./process-tree.js";
import type { CaptureInput } from "./capture.js";
-import type { HyperframesRenderProgress } from "./render.js";
+import type { HtmlRasterProgress } from "./render.js";
const cleanupMs = 5_000;
@@ -11,18 +11,15 @@ const cleanupMs = 5_000;
export async function runCaptureProcess(
input: CaptureInput,
signal: AbortSignal,
- onProgress: (event: HyperframesRenderProgress) => void,
- entry = new URL("./capture-worker.ts", import.meta.url),
+ onProgress: (event: HtmlRasterProgress) => void,
+ entry = new URL("./capture-worker.js", import.meta.url),
onDiagnostic?: (diagnostic: ExecutionDiagnostic) => Promise<void>,
): Promise<void> {
signal.throwIfAborted();
await new Promise<void>((resolve, reject) => {
- // The launcher's resolver hooks are process-local, so this child preloads the same
- // environment before it imports any package the Distribution owns.
const child = spawn(process.execPath, [
"--import", import.meta.resolve("tsx"),
- "--import", new URL("./capture-bootstrap.ts", import.meta.url).href,
- "--import", new URL("./capture-exit.ts", import.meta.url).href,
+ "--import", new URL("./capture-exit.js", import.meta.url).href,
fileURLToPath(entry),
], {
detached: process.platform !== "win32", windowsHide: true,
@@ -49,7 +46,7 @@ export async function runCaptureProcess(
}
killing ??= (child.pid === undefined ? Promise.resolve() : killRenderTree(child.pid)).catch((error) => {
if (!completed) failure = new Error(`${failure?.message ?? "Render cleanup failed"}; ${String(error)}`);
- diagnostic({ level: "warning", message: `Render process-tree cleanup could not be confirmed: ${String(error)}` });
+ diagnostic({ level: "warning", message: `Rasterizer process-tree cleanup could not be confirmed: ${String(error)}` });
child.kill("SIGKILL");
});
return killing;
@@ -68,8 +65,8 @@ export async function runCaptureProcess(
const awaitExit = () => {
grace ??= setTimeout(() => {
diagnostic({ level: "warning", message: exited
- ? `Render process exited but its output pipes did not close within ${cleanupMs} ms; closing this execution's pipes`
- : `Render process did not exit within ${cleanupMs} ms; terminating its remaining process tree` });
+ ? `Rasterizer process exited but its output pipes did not close within ${cleanupMs} ms; closing this execution's pipes`
+ : `Rasterizer process did not exit within ${cleanupMs} ms; terminating its remaining process tree` });
void kill();
}, cleanupMs);
};
@@ -78,7 +75,7 @@ export async function runCaptureProcess(
const log = (chunk: Buffer, error: boolean) => {
outputBytes += chunk.byteLength;
if (error) stderr = `${stderr}${chunk.toString()}`.slice(-32_000);
- if (outputBytes > input.config.maxProcessOutputBytes) stop(new Error("HyperFrames process output exceeded the configured limit"));
+ if (outputBytes > input.config.maxProcessOutputBytes) stop(new Error("HTML renderer process output exceeded the configured limit"));
};
for (const [stream, pipe] of [["stdout", child.stdout], ["stderr", child.stderr]] as const) {
pipe?.setEncoding("utf8");
@@ -87,7 +84,7 @@ export async function runCaptureProcess(
if (text.trim()) diagnostic({ stream, level: "info", message: text.trimEnd() });
});
}
- child.on("message", (value: { type: string; event?: HyperframesRenderProgress; error?: string }) => {
+ child.on("message", (value: { type: string; event?: HtmlRasterProgress; error?: string }) => {
if (value.type === "progress" && value.event !== undefined) {
try { onProgress(value.event); } catch (error) { stop(error instanceof Error ? error : new Error(String(error))); }
} else if (value.type === "stopping") {
@@ -109,10 +106,10 @@ export async function runCaptureProcess(
child.once("exit", (code, exitSignal) => {
exited = true;
if (!completed && failure === undefined) {
- failure = new Error(`HyperFrames process exited before completion (${exitSignal ?? `code ${String(code)}`})`);
+ failure = new Error(`HTML renderer process exited before completion (${exitSignal ?? `code ${String(code)}`})`);
}
if (exitSignal !== null && killing === undefined) {
- diagnostic({ level: "warning", message: `Render process was terminated by ${exitSignal}; descendant cleanup could not be confirmed` });
+ diagnostic({ level: "warning", message: `Rasterizer process was terminated by ${exitSignal}; descendant cleanup could not be confirmed` });
}
// An abruptly orphaned descendant may still hold stdout/stderr open.
awaitExit();
@@ -124,7 +121,7 @@ export async function runCaptureProcess(
void (killing ?? Promise.resolve()).then(async () => {
await diagnostics;
if (failure !== undefined) reject(new Error(`${failure.message}${stderr ? `\n${stderr}` : ""}`, { cause: failure }));
- else if (!completed) reject(new Error(`HyperFrames process exited before completion (${exitSignal ?? `code ${String(code)}`}): ${stderr}`));
+ else if (!completed) reject(new Error(`HTML renderer process exited before completion (${exitSignal ?? `code ${String(code)}`}): ${stderr}`));
else resolve();
});
});
diff --git a/packages/provider-hyperframes-local/src/capture-worker.ts b/packages/provider-html-local/src/capture-worker.ts
similarity index 100%
rename from packages/provider-hyperframes-local/src/capture-worker.ts
rename to packages/provider-html-local/src/capture-worker.ts
diff --git a/packages/provider-hyperframes-local/src/capture.ts b/packages/provider-html-local/src/capture.ts
similarity index 77%
rename from packages/provider-hyperframes-local/src/capture.ts
rename to packages/provider-html-local/src/capture.ts
index d6662573..3c4b7512 100644
--- a/packages/provider-hyperframes-local/src/capture.ts
+++ b/packages/provider-html-local/src/capture.ts
@@ -1,35 +1,38 @@
-import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { mkdir, rm, stat, writeFile } from "node:fs/promises";
import { join, relative, resolve, sep } from "node:path";
-import { hyperframesFrameSelectionPrelude } from "@hypit/hyperframes";
-import type { HyperframesDocument } from "@hypit/hyperframes";
-import type { MediaFrameRange } from "@hypit/media";
-import type { HyperframesRenderProgress, resolveExecutionOptions } from "./render.js";
+import puppeteer from "puppeteer-core";
+import type { Browser } from "puppeteer-core";
+import type { HtmlProgram } from "@hypit/hypit/html-program";
+import type { MediaFrameRange } from "@hypit/hypit/media";
+import type { HtmlRasterProgress, resolveExecutionOptions } from "./render.js";
import { assert, mediaExecutablePath, openProcessInput } from "./process.js";
import { verifyOutput } from "./output.js";
import { distributeFrameRange, requestedFrameRanges, sourceFrameAt, sourceWindows, videoSlots } from "./sampling.js";
import type { VideoSlot } from "./sampling.js";
-import { renderWorkerLimit } from "./render.js";
-import { CaptureConcurrency } from "./concurrency.js";
+import { CaptureConcurrency, renderWorkerLimit } from "./concurrency.js";
import { createOpaqueFrameCapture } from "./opaque-capture.js";
import { FrameSpanIndex } from "./frame-span-index.js";
import { OrderedFrameSink } from "./ordered-frame-sink.js";
-import { decodeSourceFrameWindow } from "./source-frame-decoder.js";
+import { decodeSourceFrameWindow, probeSourceVideo } from "./source-frame-decoder.js";
import { SourceFrameStore } from "./source-frame-store.js";
import type { SourceFrameWindow } from "./source-frame-store.js";
+import { serveHtmlProgram } from "./server.js";
export type CaptureInput = {
- readonly document: Pick<HyperframesDocument, "frameRate" | "frameCount" | "canvas">;
+ readonly document: HtmlProgram;
readonly frames?: readonly number[];
readonly range: MediaFrameRange;
readonly config: ReturnType<typeof resolveExecutionOptions> & { readonly chromePath: string };
readonly directory: string;
- readonly engineModule: string;
- readonly producerModule: string;
+ /** Complete browser prelude prepared by the Program owner before entering the child process. */
+ readonly frameSelectionPrelude: string;
+ /** Program Artifact identities projected onto the already-staged local project. */
+ readonly artifactPaths: readonly (readonly [resource: string, path: string])[];
};
/** All browser and codec work belongs to this render's disposable process. */
export async function captureStagedVisual(input: CaptureInput, controller: AbortController,
- onProgress: (event: HyperframesRenderProgress) => void): Promise<string> {
+ onProgress: (event: HtmlRasterProgress) => void): Promise<string> {
const { document, range, config, directory: work } = input;
const signal = controller.signal;
const frameCount = input.frames?.length ?? range.endFrameExclusive - range.startFrame;
@@ -45,22 +48,15 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
let nextBatch = 0;
const started = performance.now();
const elapsedMs = () => Math.round(performance.now() - started);
- const engine = await import(input.engineModule) as typeof import("@hyperframes/engine");
const [ffmpegPath, ffprobePath] = await Promise.all([
mediaExecutablePath(config.ffmpegPath), mediaExecutablePath(config.ffprobePath),
]);
- // This is one disposable render process. Use the engine's public override
- // ports here without changing the Runtime owner's environment or other renders.
- process.env[engine.FFMPEG_PATH_ENV] = ffmpegPath;
- process.env[engine.FFPROBE_PATH_ENV] = ffprobePath;
- const { createFileServer } = await import(input.producerModule) as typeof import("@hyperframes/producer");
- type Session = Awaited<ReturnType<typeof engine.createCaptureSession>>;
- const sessions = new Set<Session>();
- const closing = new Map<Session, Promise<void>>();
- const close = (session: Session): Promise<void> => {
+ const sessions = new Set<Browser>();
+ const closing = new Map<Browser, Promise<void>>();
+ const close = (session: Browser): Promise<void> => {
let promise = closing.get(session);
if (promise === undefined) {
- promise = engine.closeCaptureSession(session).finally(() => { sessions.delete(session); });
+ promise = session.close().finally(() => { sessions.delete(session); });
closing.set(session, promise);
}
return promise;
@@ -69,7 +65,7 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
signal.throwIfAborted();
const timeout = timeoutMs === undefined
? undefined
- : setTimeout(() => controller.abort(new Error(`HyperFrames ${subject} timed out after ${timeoutMs} ms`)), timeoutMs);
+ : setTimeout(() => controller.abort(new Error(`HTML renderer ${subject} timed out after ${timeoutMs} ms`)), timeoutMs);
let onAbort: () => void = () => {};
const stopped = new Promise<never>((_, reject) => {
onAbort = () => reject(signal.reason);
@@ -81,7 +77,7 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
signal.removeEventListener("abort", onAbort);
}
};
- let server: Awaited<ReturnType<typeof createFileServer>> | undefined;
+ let server: Awaited<ReturnType<typeof serveHtmlProgram>> | undefined;
let encoderCompletion: Promise<unknown> | undefined;
let sourceFrameStore: SourceFrameStore | undefined;
// Closing pages interrupts an in-flight capture as well as the next loop iteration.
@@ -89,20 +85,26 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
signal.addEventListener("abort", abort, { once: true });
try {
signal.throwIfAborted();
- const slots = videoSlots(await readFile(join(work, "index.html"), "utf8"));
+ const artifactPaths = new Map(input.artifactPaths);
+ const slots = videoSlots(document.frameSources, resource => {
+ const path = artifactPaths.get(resource);
+ assert(path !== undefined, `HTML renderer Artifact ${resource} has no staged path`);
+ return `./${path}`;
+ });
const slotIndex = new FrameSpanIndex(slots);
const requestedRanges = requestedFrameRanges(range, input.frames);
const plannedSources = sourceWindows(slots, requestedRanges);
const sourceTotal = plannedSources.reduce((sum, source) => sum + source.windows.reduce((count, window) =>
count + window.endFrameExclusive - window.startFrame, 0), 0);
const sources = new Map<string, { path: string; fps: VideoSlot["sourceFps"];
- metadata: Awaited<ReturnType<typeof engine.extractMediaMetadata>> }>();
+ metadata: Awaited<ReturnType<typeof probeSourceVideo>> }>();
// Chrome needs dimensions before initialization. Pixel frames themselves
// are decoded lazily for the screenshots that lease them.
for (const source of plannedSources) {
const path = resolve(work, source.src);
- assert(path.startsWith(`${work}${sep}`), "HyperFrames source is outside the staged project");
- const metadata = await engine.extractMediaMetadata(path);
+ assert(path.startsWith(`${work}${sep}`), "HTML renderer source is outside the staged project");
+ const metadata = await probeSourceVideo({ executable: ffprobePath, path,
+ timeoutMs: config.processTimeoutMs, maxOutputBytes: config.maxProcessOutputBytes, signal });
signal.throwIfAborted();
sources.set(source.src, { path, fps: source.fps, metadata });
}
@@ -110,7 +112,7 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
sourceFrameStore = new SourceFrameStore({ maxBytes: config.maxDecodedSourceBytes, signal,
decode: (src, window) => {
const source = sources.get(src);
- assert(source !== undefined, `HyperFrames source ${src} is outside the requested render`);
+ assert(source !== undefined, `HTML renderer source ${src} is outside the requested render`);
return decodeSourceFrameWindow({ executable: ffmpegPath, path: source.path, outputDir: join(work, "decoded"),
outputPrefix: `source-${extraction++}`, window, fps: source.fps, metadata: source.metadata,
timeoutMs: config.processTimeoutMs, maxProcessOutputBytes: config.maxProcessOutputBytes, signal });
@@ -122,25 +124,19 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
const frameRanges = (startIndex: number, endIndex: number): MediaFrameRange[] => input.frames === undefined
? [{ startFrame: at(startIndex), endFrameExclusive: at(endIndex - 1) + 1 }]
: input.frames.slice(startIndex, endIndex).map(frame => ({ startFrame: frame, endFrameExclusive: frame + 1 }));
- class SelectedFrameLookup extends engine.FrameLookupTable {
- constructor(readonly strict: () => boolean) { super(); }
- override getActiveFramePayloads(time: number) {
- const frame = Math.round(time * fps.num / fps.den);
+ const activeFramePayloads = (frame: number) => {
const payloads = new Map<string, { framePath: string; frameIndex: number }>();
for (const slot of slotIndex.at(frame)) {
const frameIndex = sourceFrameAt(slot, frame);
// Browser initialization may seek outside the requested interval.
if (selected === undefined ? frame < range.startFrame || frame >= range.endFrameExclusive : !selected.has(frame)) continue;
const framePath = sourceFrameStore!.path(slot.src, frameIndex);
- if (framePath === undefined && !this.strict()) continue;
- assert(framePath !== undefined, `HyperFrames has no decoded frame ${frameIndex} for ${slot.id}`);
+ assert(framePath !== undefined, `HTML renderer has no decoded frame ${frameIndex} for ${slot.id}`);
payloads.set(slot.id, { framePath, frameIndex });
}
return payloads;
- }
- }
- server = await createFileServer({ projectDir: work, port: 0, fps,
- preHeadScripts: [hyperframesFrameSelectionPrelude(requestedRanges)] });
+ };
+ server = await serveHtmlProgram(work);
const serverUrl = server.url;
const outputFrames = join(work, "frames");
const output = join(work, "visual.mp4");
@@ -178,7 +174,7 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
void jobs[worker]!.catch(() => {});
};
const runWorker = async (worker: number): Promise<void> => {
- let session: Session | undefined;
+ let session: Browser | undefined;
let ready = false;
let capturing = false;
active++;
@@ -188,29 +184,30 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
let setupMs = 0;
try {
signal.throwIfAborted();
- const directory = join(work, `worker-${worker}`);
- await mkdir(directory);
- const injector = engine.createVideoFrameInjector(slots.length === 0 ? null : new SelectedFrameLookup(() => capturing), {
- frameSrcResolver: (path) => new URL(relative(work, path).split(sep).map(encodeURIComponent).join("/"), `${serverUrl}/`).href,
- });
- session = await engine.createCaptureSession(serverUrl, directory, {
- // Engine initialization couples PNG to transparent-export mode. Use
- // its opaque session setup; our capture adapter writes lossless PNG.
- ...document.canvas, fps, format: "jpeg",
- compositionDurationSeconds: document.frameCount * fps.den / fps.num,
- skipReadinessVideoIds: slots.map((slot) => slot.id),
- videoMetadataHints: slots.flatMap((slot) => {
- const source = sources.get(slot.src);
- return source === undefined ? [] : [{ id: slot.id, width: source.metadata.width, height: source.metadata.height }];
- }),
- }, injector, { chromePath: config.chromePath, browserGpuMode: config.browserGpu, enableBrowserPool: false, forceScreenshot: true, useDrawElement: false });
+ session = await puppeteer.launch({ executablePath: config.chromePath, headless: true,
+ defaultViewport: { width: document.canvas.width, height: document.canvas.height, deviceScaleFactor: 1 },
+ args: ["--no-sandbox", "--disable-dev-shm-usage",
+ ...(config.browserGpu === "software" ? ["--disable-gpu"] : []),
+ ] });
sessions.add(session);
signal.throwIfAborted();
- const activeSession = session;
- const browserPid = session.browser.process()?.pid;
+ const page = await session.newPage();
+ if (config.initializationTimeoutMs !== undefined) {
+ page.setDefaultTimeout(config.initializationTimeoutMs);
+ page.setDefaultNavigationTimeout(config.initializationTimeoutMs);
+ }
+ await page.evaluateOnNewDocument(input.frameSelectionPrelude);
+ const browserPid = session.process()?.pid;
onProgress?.({ phase: "worker-initializing", worker, range, browserPid, elapsedMs: elapsedMs() });
- await stage(`worker ${worker} initialization`, config.initializationTimeoutMs, () => engine.initializeSession(activeSession));
- const captureFrame = await createOpaqueFrameCapture(activeSession);
+ await stage(`worker ${worker} initialization`, config.initializationTimeoutMs, async () => {
+ await page.goto(serverUrl, { waitUntil: "load" });
+ await page.evaluate(async () => {
+ const program = (window as unknown as { __hypitFrameProgram?: { prepare(): Promise<void> } }).__hypitFrameProgram;
+ if (program === undefined) throw new Error("HTML Program page ABI is missing");
+ await program.prepare();
+ });
+ });
+ const captureFrame = await createOpaqueFrameCapture(page, document.canvas);
setupMs = performance.now() - launched;
startupMs = Math.max(startupMs, setupMs);
ready = true;
@@ -238,7 +235,11 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
sourceAcquireWorkerMs += performance.now() - sourceAcquireStarted;
let captured: Awaited<ReturnType<typeof captureFrame>>;
try {
- captured = await stage(`worker ${worker} frame ${frame}`, config.frameTimeoutMs, () => captureFrame(frame));
+ const payloads = activeFramePayloads(frame);
+ const sourceUpdates = [...payloads].map(([id, payload]) => ({ id,
+ url: new URL(relative(work, payload.framePath).split(sep).map(encodeURIComponent).join("/"), serverUrl).href }));
+ captured = await stage(`worker ${worker} frame ${frame}`, config.frameTimeoutMs,
+ () => captureFrame(frame, sourceUpdates));
} finally {
// Output submission may block behind an earlier frame. Never
// retain source leases across that independent backpressure.
@@ -246,7 +247,7 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
}
if (input.frames !== undefined) {
capturedBytes += captured.buffer.byteLength;
- assert(capturedBytes <= config.maxRenderedBytes, "HyperFrames PNG output exceeds its byte limit");
+ assert(capturedBytes <= config.maxRenderedBytes, "HTML renderer PNG output exceeds its byte limit");
}
timing.seekMs += captured.seekMs;
timing.prepareMs += captured.prepareMs;
@@ -312,7 +313,7 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
onProgress({ phase: "encoding", elapsedMs: elapsedMs() });
await orderedFrames!.close();
const outputStat = await stat(output);
- assert(outputStat.size > 0 && outputStat.size <= config.maxRenderedBytes, "HyperFrames output is empty or exceeds its byte limit");
+ assert(outputStat.size > 0 && outputStat.size <= config.maxRenderedBytes, "HTML renderer output is empty or exceeds its byte limit");
await verifyOutput({ path: output, document: { ...document, frameCount }, ffprobePath,
timeoutMs: config.processTimeoutMs, maxOutputBytes: config.maxProcessOutputBytes, signal });
signal.throwIfAborted();
diff --git a/packages/provider-hyperframes-local/src/concurrency.ts b/packages/provider-html-local/src/concurrency.ts
similarity index 90%
rename from packages/provider-hyperframes-local/src/concurrency.ts
rename to packages/provider-html-local/src/concurrency.ts
index 39303e41..c678b6eb 100644
--- a/packages/provider-hyperframes-local/src/concurrency.ts
+++ b/packages/provider-html-local/src/concurrency.ts
@@ -13,6 +13,15 @@ export function autoWorkerLimit(cpu = availableParallelism(), memory = hostMemor
return Math.max(1, Math.min(Math.max(1, cpu - 2), byMemory));
}
+/** Exact browser reservation shared by Runtime admission and the admitted capture attempt. */
+export function renderWorkerLimit(
+ config: { readonly maxWorkers: number; readonly workers: "auto" | number },
+ frameCount: number,
+ fps: number,
+): number {
+ return Math.min(config.maxWorkers, config.workers === "auto" ? Math.max(1, Math.ceil(frameCount / fps)) : frameCount);
+}
+
/**
* Online throughput comparison of useful capture batches. All samples and
* decisions die with this attempt. A change never invalidates captured frames.
diff --git a/packages/provider-hyperframes-local/src/frame-span-index.ts b/packages/provider-html-local/src/frame-span-index.ts
similarity index 100%
rename from packages/provider-hyperframes-local/src/frame-span-index.ts
rename to packages/provider-html-local/src/frame-span-index.ts
diff --git a/packages/provider-html-local/src/index.ts b/packages/provider-html-local/src/index.ts
new file mode 100644
index 00000000..7c1580f6
--- /dev/null
+++ b/packages/provider-html-local/src/index.ts
@@ -0,0 +1,10 @@
+export { createLocalHtmlProvider, localHtmlProviderModuleRef } from "./provider.js";
+export type {
+ CreateLocalHtmlProviderOptions,
+ HtmlBrowserGpu,
+ HtmlQuality,
+ HtmlWorkers,
+} from "./provider.js";
+
+export { rasterizeHtmlProgram, rasterizeHtmlFrames } from "./render.js";
+export type { HtmlRasterOptions, HtmlRasterProgress } from "./render.js";
diff --git a/packages/provider-hyperframes-local/src/opaque-capture.ts b/packages/provider-html-local/src/opaque-capture.ts
similarity index 79%
rename from packages/provider-hyperframes-local/src/opaque-capture.ts
rename to packages/provider-html-local/src/opaque-capture.ts
index eb8f0883..8a534e01 100644
--- a/packages/provider-hyperframes-local/src/opaque-capture.ts
+++ b/packages/provider-html-local/src/opaque-capture.ts
@@ -1,26 +1,21 @@
-import type { CaptureSession, HfProtocol } from "@hyperframes/engine";
-import { getCdpSession } from "@hyperframes/engine";
+import type { Page } from "puppeteer-core";
-/** The optional completion hooks supplied by the pinned Hyperframes page runtime. */
+/** The optional completion hooks supplied by the pinned HTML page runtime. */
type RenderWindow = Window & {
- __hf: HfProtocol & { colorGrading?: { waitForActiveLuts?: () => Promise<void> } };
- __hfWaitForSeekCompletion?: () => Promise<void>;
- __hf_page_composite_pending?: boolean;
- __hf_page_composite_prepare?: () => Promise<void>;
- __hf_page_composite_resolve?: () => void;
- __hypitBrowserProgramError?: string;
+ __hypitFrameProgram: { prepare(): Promise<void>; applyFrame(frame: number): Promise<void> };
+ __hypitHtmlVisualError?: string;
__hypitCaptureRoots?: readonly Element[];
};
+export type SourceFrameUpdate = { readonly id: string; readonly url: string };
+
/**
- * A screenshot adapter for this Provider's opaque MP4 output. Session lifecycle,
- * the page's seek protocol and the video injector remain engine-owned. Encoding
- * the already-composited frame as a fast PNG does not change source alpha.
- * No engine/session methods are replaced and no installed dependency is patched.
+ * Capture one already-composited page state as an opaque PNG. The Provider owns
+ * the page ABI, exact source-frame overlays and CDP session directly; there is
+ * no intermediate rendering engine or patched installed dependency.
*/
-export async function createOpaqueFrameCapture(session: CaptureSession) {
- const { page, options } = session;
- const cdp = await getCdpSession(page);
+export async function createOpaqueFrameCapture(page: Page, canvas: { readonly width: number; readonly height: number }) {
+ const cdp = await page.createCDPSession();
// MP4 has no alpha channel. The authored Canvas paints over this final matte.
await cdp.send("Emulation.setDefaultBackgroundColorOverride", { color: { r: 0, g: 0, b: 0, a: 1 } });
// Image readiness belongs to this page. A seek can select a new image through
@@ -42,7 +37,7 @@ export async function createOpaqueFrameCapture(session: CaptureSession) {
const image = new Image();
image.src = absolute;
ready = image.decode().catch(error => {
- throw new Error(`HyperFrames image could not be decoded: ${absolute}`, { cause: error });
+ throw new Error(`HTML renderer image could not be decoded: ${absolute}`, { cause: error });
});
decoded.set(absolute, ready);
}
@@ -119,7 +114,7 @@ export async function createOpaqueFrameCapture(session: CaptureSession) {
&& (element.currentSrc || element.getAttribute("src") || element.getAttribute("srcset"))
&& (!element.complete || element.naturalWidth === 0)) {
pending.push(element.decode().catch(error => {
- throw new Error(`HyperFrames image could not be decoded: ${element.currentSrc || element.src}`, { cause: error });
+ throw new Error(`HTML renderer image could not be decoded: ${element.currentSrc || element.src}`, { cause: error });
}));
}
images.style(getComputedStyle(element), pending);
@@ -238,44 +233,53 @@ export async function createOpaqueFrameCapture(session: CaptureSession) {
do await readiness.preparePass(); while (dirtyRoots.size > 0);
await document.fonts.ready;
document.fonts.forEach(font => {
- if (font.status === "error") throw new Error(`HyperFrames font could not be loaded: ${font.family}`);
+ if (font.status === "error") throw new Error(`HTML renderer font could not be loaded: ${font.family}`);
});
};
});
- return async (frame: number) => {
- const time = frame * options.fps.den / options.fps.num;
+ return async (frame: number, sources: readonly SourceFrameUpdate[] = []) => {
const start = performance.now();
- await page.evaluate(async t => {
+ await page.evaluate(async (input) => {
const w = window as unknown as RenderWindow;
- await w.__hf.seek(t);
- }, time);
+ await w.__hypitFrameProgram.applyFrame(input.frame);
+ const active = new Set(input.sources.map(source => source.id));
+ for (const image of Array.from(document.querySelectorAll<HTMLImageElement>('[data-hypit-source-frame-image]'))) {
+ if (!active.has(image.dataset.hypitSourceFrameImage!)) image.style.display = 'none';
+ }
+ await Promise.all(input.sources.map(async source => {
+ const video = document.getElementById(source.id) as HTMLVideoElement | null;
+ if (video === null) throw new Error(`HTML Program source element ${source.id} is missing.`);
+ let image = document.querySelector<HTMLImageElement>(`[data-hypit-source-frame-image="${CSS.escape(source.id)}"]`);
+ if (image === null) {
+ image = document.createElement('img');
+ image.dataset.hypitSourceFrameImage = source.id;
+ image.className = video.className;
+ video.insertAdjacentElement('afterend', image);
+ }
+ image.style.cssText = video.style.cssText;
+ image.style.visibility = video.dataset.hypitAuthoredVisibility ?? video.style.visibility;
+ image.style.display = video.style.display;
+ image.width = video.width;
+ image.height = video.height;
+ if (video.dataset.hypitAuthoredVisibility === undefined) {
+ video.dataset.hypitAuthoredVisibility = video.style.visibility;
+ }
+ video.style.visibility = 'hidden';
+ if (image.src !== source.url) image.src = source.url;
+ await image.decode();
+ }));
+ }, { frame, sources });
const sought = performance.now();
- await session.onBeforeCapture?.(page, time);
- const composite = await page.evaluate(async () => {
+ await page.evaluate(async () => {
const w = window as unknown as RenderWindow & { __hypitPrepareImages: () => Promise<void> };
- await w.__hfWaitForSeekCompletion?.();
- await w.__hf.colorGrading?.waitForActiveLuts?.();
await w.__hypitPrepareImages();
- if (w.__hypitBrowserProgramError !== undefined) throw new Error(w.__hypitBrowserProgramError);
- if (w.__hf_page_composite_pending) {
- await w.__hf_page_composite_prepare?.();
- return true;
- }
- return false;
+ if (w.__hypitHtmlVisualError !== undefined) throw new Error(w.__hypitHtmlVisualError);
});
- if (composite) {
- // The runtime's shader compositor needs a paint between preparing its DOM
- // layers and resolving them. A 1 px capture flushes Chrome's compositor.
- await cdp.send("Page.captureScreenshot", {
- format: "jpeg", quality: 1, clip: { x: 0, y: 0, width: 1, height: 1, scale: 1 },
- });
- await page.evaluate(() => (window as unknown as RenderWindow).__hf_page_composite_resolve?.());
- }
const prepared = performance.now();
const result = await cdp.send("Page.captureScreenshot", {
format: "png", optimizeForSpeed: true, fromSurface: true,
- captureBeyondViewport: options.captureBeyondViewport ?? false,
- clip: { x: 0, y: 0, width: options.width, height: options.height, scale: options.deviceScaleFactor ?? 1 },
+ captureBeyondViewport: false,
+ clip: { x: 0, y: 0, width: canvas.width, height: canvas.height, scale: 1 },
});
return { buffer: Buffer.from(result.data, "base64"),
seekMs: sought - start, prepareMs: prepared - sought, screenshotMs: performance.now() - prepared };
diff --git a/packages/provider-hyperframes-local/src/options.ts b/packages/provider-html-local/src/options.ts
similarity index 72%
rename from packages/provider-hyperframes-local/src/options.ts
rename to packages/provider-html-local/src/options.ts
index 77676144..300fb2f9 100644
--- a/packages/provider-hyperframes-local/src/options.ts
+++ b/packages/provider-html-local/src/options.ts
@@ -1,18 +1,18 @@
-export type HyperframesWorkers = number | "auto";
-export type HyperframesQuality = "draft" | "standard" | "high";
-export type HyperframesBrowserGpu = "auto" | "software" | "hardware";
+export type HtmlWorkers = number | "auto";
+export type HtmlQuality = "draft" | "standard" | "high";
+export type HtmlBrowserGpu = "auto" | "software" | "hardware";
-export type HyperframesExecutionOptions = import("./browser.js").BrowserOptions & {
+export type HtmlExecutionOptions = import("./browser.js").BrowserOptions & {
readonly ffprobePath?: string;
/** Selected FFmpeg command for both source extraction and final H.264 encoding. */
readonly ffmpegPath?: string;
/** Parallel Chrome workers inside one render. This is separate from Provider request concurrency. */
- readonly workers?: HyperframesWorkers;
+ readonly workers?: HtmlWorkers;
/** Upper bound for auto's browser reservation; explicit workers remain fixed. */
readonly maxWorkers?: number;
- readonly quality?: HyperframesQuality;
+ readonly quality?: HtmlQuality;
/** Chrome's rasterizer, default hardware. Use software without a usable GPU. */
- readonly browserGpu?: HyperframesBrowserGpu;
+ readonly browserGpu?: HtmlBrowserGpu;
readonly processTimeoutMs?: number;
readonly initializationTimeoutMs?: number;
readonly frameTimeoutMs?: number;
diff --git a/packages/provider-hyperframes-local/src/ordered-frame-sink.ts b/packages/provider-html-local/src/ordered-frame-sink.ts
similarity index 100%
rename from packages/provider-hyperframes-local/src/ordered-frame-sink.ts
rename to packages/provider-html-local/src/ordered-frame-sink.ts
diff --git a/packages/provider-hyperframes-local/src/output.ts b/packages/provider-html-local/src/output.ts
similarity index 91%
rename from packages/provider-hyperframes-local/src/output.ts
rename to packages/provider-html-local/src/output.ts
index 22fd3d35..1fcb82f9 100644
--- a/packages/provider-hyperframes-local/src/output.ts
+++ b/packages/provider-html-local/src/output.ts
@@ -1,4 +1,4 @@
-import type { HyperframesDocument } from "@hypit/hyperframes";
+import type { HtmlProgram } from "@hypit/hypit/html-program";
import { assert, runProcess } from "./process.js";
type ProbeStream = {
@@ -38,7 +38,7 @@ function outputFrameCount(stream: ProbeStream): number {
export async function verifyOutput(args: {
readonly path: string;
- readonly document: Pick<HyperframesDocument, "frameRate" | "frameCount" | "canvas">;
+ readonly document: Pick<HtmlProgram, "frameRate" | "frameCount" | "canvas">;
readonly ffprobePath: string;
readonly timeoutMs: number;
readonly maxOutputBytes: number;
@@ -55,10 +55,10 @@ export async function verifyOutput(args: {
try {
value = JSON.parse(Buffer.from(probe.stdout).toString("utf8"));
} catch {
- throw new Error("ffprobe returned invalid JSON for the HyperFrames output");
+ throw new Error("ffprobe returned invalid JSON for the HTML renderer output");
}
assert(value !== null && typeof value === "object" && !Array.isArray(value),
- "ffprobe returned an invalid HyperFrames inspection");
+ "ffprobe returned an invalid HTML renderer inspection");
const streams = (value as { readonly streams?: unknown }).streams;
assert(Array.isArray(streams) && streams.length === 1, "Rendered visual must contain exactly one stream");
const stream = streams[0] as ProbeStream;
diff --git a/packages/provider-hyperframes-local/src/process-tree.ts b/packages/provider-html-local/src/process-tree.ts
similarity index 96%
rename from packages/provider-hyperframes-local/src/process-tree.ts
rename to packages/provider-html-local/src/process-tree.ts
index a72e43b4..a7d5275e 100644
--- a/packages/provider-hyperframes-local/src/process-tree.ts
+++ b/packages/provider-html-local/src/process-tree.ts
@@ -47,7 +47,7 @@ export async function killRenderTree(pid: number): Promise<void> {
catch (error) { if ((error as NodeJS.ErrnoException).code === "ESRCH") return false; throw error; }
});
if (remaining.length === 0) break;
- if (Date.now() >= deadline) throw new Error(`Render process ${remaining[0]} did not stop after SIGKILL`);
+ if (Date.now() >= deadline) throw new Error(`Rasterizer process ${remaining[0]} did not stop after SIGKILL`);
await delay(20);
}
}
diff --git a/packages/provider-hyperframes-local/src/process.ts b/packages/provider-html-local/src/process.ts
similarity index 93%
rename from packages/provider-hyperframes-local/src/process.ts
rename to packages/provider-html-local/src/process.ts
index 6ce00507..75dd550a 100644
--- a/packages/provider-hyperframes-local/src/process.ts
+++ b/packages/provider-html-local/src/process.ts
@@ -24,7 +24,7 @@ export function positiveInteger(value: number, subject: string): number {
return value;
}
-/** The engine's binary override requires a path; resolve our selected command without its fallback search. */
+/** Resolve the selected media command once, without adding another fallback search policy. */
export async function mediaExecutablePath(value: string): Promise<string> {
const pathLike = isAbsolute(value) || value.includes("/") || value.includes("\\");
const bases = pathLike ? [resolve(value)]
@@ -40,12 +40,12 @@ export async function mediaExecutablePath(value: string): Promise<string> {
if (!["ENOENT", "ENOTDIR", "EACCES"].includes((error as NodeJS.ErrnoException).code ?? "")) throw error;
}
}
- throw new Error(`HyperFrames media executable ${value} is unavailable; correct the Provider's ffmpegPath or ffprobePath.`);
+ throw new Error(`HTML renderer media executable ${value} is unavailable; correct the Provider's ffmpegPath or ffprobePath.`);
}
export function processEnvironment(platform: NodeJS.Platform = process.platform): NodeJS.ProcessEnv {
- // POSIX temp is TMPDIR; Windows is TEMP/TMP. HyperFrames writes extracted
- // frames under %TEMP%\hf-render-… and ffmpeg creates temporary files the same way.
+ // POSIX temp is TMPDIR; Windows is TEMP/TMP. Browser and media subprocesses
+ // inherit only the environment needed for deterministic local execution.
const names = platform === "win32"
? ["PATH", "PATHEXT", "SYSTEMROOT", "WINDIR", "ComSpec", "TEMP", "TMP", "USERPROFILE", "LANG", "LC_ALL"] as const
: ["PATH", "HOME", "TMPDIR", "LANG", "LC_ALL"] as const;
diff --git a/packages/provider-hyperframes-local/src/program.ts b/packages/provider-html-local/src/program.ts
similarity index 52%
rename from packages/provider-hyperframes-local/src/program.ts
rename to packages/provider-html-local/src/program.ts
index 9c64f356..02094de4 100644
--- a/packages/provider-hyperframes-local/src/program.ts
+++ b/packages/provider-html-local/src/program.ts
@@ -1,17 +1,47 @@
import { fileURLToPath } from "node:url";
import { join } from "node:path";
-import { probeMediaToolchain } from "@hypit/media-execution";
-import type { ManagedProgram, ManagedProgramState } from "@hypit/runtime-kit";
+import type { ManagedProgram, ManagedProgramState } from "@hypit/runtime-local/extension";
import { browserCacheDirectory, browserDownloadBaseUrl, browserDownloadUrl, browserExecutablePath, configuredBrowserPath, requireBrowserExecutable, selectedBrowserVersion } from "./browser.js";
import type { BrowserOptions } from "./browser.js";
-import { processEnvironment } from "./process.js";
+import { runProcess } from "./process.js";
+
+type MediaToolVersion =
+ | { readonly state: "ready"; readonly version: string }
+ | { readonly state: "down" | "mismatch"; readonly detail: string };
+
+async function mediaToolVersion(path: string): Promise<MediaToolVersion> {
+ try {
+ const result = await runProcess({
+ executable: path,
+ argv: ["-version"],
+ timeoutMs: 15_000,
+ maxOutputBytes: 4 * 1024 * 1024,
+ });
+ const version = Buffer.from(result.stdout).toString("utf8").split(/\r?\n/u, 1)[0]?.trim() ?? "";
+ return version.length > 0
+ ? { state: "ready", version }
+ : { state: "mismatch", detail: `${path} returned no version` };
+ } catch (error) {
+ return { state: "down", detail: error instanceof Error ? error.message : String(error) };
+ }
+}
+
+async function probeHtmlMediaTools(ffprobePath: string, ffmpegPath?: string): Promise<ManagedProgramState> {
+ const ffprobe = await mediaToolVersion(ffprobePath);
+ if (ffprobe.state !== "ready") return { state: ffprobe.state, detail: ffprobe.detail };
+ if (ffmpegPath === undefined) return { state: "ready" };
+ const ffmpeg = await mediaToolVersion(ffmpegPath);
+ return ffmpeg.state === "ready"
+ ? { state: "ready" }
+ : { state: ffmpeg.state, detail: ffmpeg.detail };
+}
/**
* This Provider owns browser selection and preparation. Probes never install;
- * rendering receives the same selected executable instead of invoking engine discovery.
+ * rasterization receives the same selected executable instead of invoking browser discovery.
*/
-export function localHyperframesBrowserProgram(
+export function localHtmlBrowserProgram(
input: BrowserOptions & {
readonly id: string;
readonly nodePath: string;
@@ -31,13 +61,12 @@ export function localHyperframesBrowserProgram(
id: input.id,
...(configuredBrowserPath(input) === undefined ? {
// Projects sharing this installation also share the existing Program lifecycle lock/logs.
- stateRoot: join(browserCacheDirectory(input), ".hypit-render-program"),
+ stateRoot: join(browserCacheDirectory(input), ".hypit-html-browser-program"),
installation: {
probe: probeBrowser,
commands: [{ label: `Install Chrome Headless Shell ${version} at ${selectedPath} from ${browserDownloadUrl(input)}`, command: input.nodePath, args: [
"--import", import.meta.resolve("tsx"),
- "--import", new URL("./capture-bootstrap.ts", import.meta.url).href,
- fileURLToPath(new URL("./browser-install.ts", import.meta.url)), browserCacheDirectory(input), version!,
+ fileURLToPath(new URL("./browser-install.js", import.meta.url)), browserCacheDirectory(input), version!,
...(baseUrl === undefined ? [] : [baseUrl]),
] }],
},
@@ -45,10 +74,7 @@ export function localHyperframesBrowserProgram(
async probe(): Promise<ManagedProgramState> {
const browser = await probeBrowser();
if (browser.state !== "ready") return browser;
- const media = await probeMediaToolchain({ environment: processEnvironment(), ffprobePath: input.ffprobePath, ...(input.ffmpegPath === undefined ? {} : { ffmpegPath: input.ffmpegPath }) });
- return media.state === "ready"
- ? { state: "ready" }
- : { state: media.state, detail: media.detail };
+ return await probeHtmlMediaTools(input.ffprobePath, input.ffmpegPath);
},
};
}
diff --git a/packages/provider-hyperframes-local/src/progress.ts b/packages/provider-html-local/src/progress.ts
similarity index 85%
rename from packages/provider-hyperframes-local/src/progress.ts
rename to packages/provider-html-local/src/progress.ts
index 740e5590..78dfbe1e 100644
--- a/packages/provider-hyperframes-local/src/progress.ts
+++ b/packages/provider-html-local/src/progress.ts
@@ -1,7 +1,7 @@
-import type { OperationProgress } from "@hypit/endpoint-kit";
-import type { HyperframesRenderProgress } from "./render.js";
+import type { OperationProgress } from "@hypit/hypit/endpoint";
+import type { HtmlRasterProgress } from "./render.js";
-/** Reduce parallel capture events to one readable progress report for this render request. */
+/** Reduce parallel capture events to one readable progress report for this rasterization request. */
export function renderProgressReporter(
report: ((progress: OperationProgress) => Promise<void>) | undefined,
totalFrames: number,
@@ -12,10 +12,10 @@ export function renderProgressReporter(
let lastPhase: string | undefined;
let lastAt = -Infinity;
let writes = Promise.resolve();
- const frames = () => ({ phase: "rendering frames", completed: [...workers.values()].reduce((a, b) => a + b, 0),
+ const frames = () => ({ phase: "rasterizing frames", completed: [...workers.values()].reduce((a, b) => a + b, 0),
total: totalFrames, unit: "frames" });
return {
- onProgress(event: HyperframesRenderProgress): void {
+ onProgress(event: HtmlRasterProgress): void {
if (report === undefined) return;
let progress: OperationProgress;
switch (event.phase) {
diff --git a/packages/provider-hyperframes-local/src/provider.ts b/packages/provider-html-local/src/provider.ts
similarity index 59%
rename from packages/provider-hyperframes-local/src/provider.ts
rename to packages/provider-html-local/src/provider.ts
index 425ad4ca..f2e6dadb 100644
--- a/packages/provider-hyperframes-local/src/provider.ts
+++ b/packages/provider-html-local/src/provider.ts
@@ -1,14 +1,15 @@
-import { defineEndpointPackage } from "@hypit/endpoint-kit";
-import { mediaTypes } from "@hypit/media";
-import { renderHyperframesCapabilities, renderHyperframesTypes, verifyHyperframesFramesRequest, hyperframesFramesDomain, verifyHyperframesVisualRequest } from "@hypit/render-hyperframes";
-import { canonicalize } from "@hypit/protocol";
-import { renderHyperframesVisual, renderHyperframesFrames, resolveExecutionOptions, renderWorkerLimit } from "./render.js";
-import type { HyperframesExecutionOptions } from "./options.js";
+import { defineEndpoint } from "@hypit/hypit/endpoint";
+import { mediaTypes } from "@hypit/hypit/media";
+import { htmlProgramCapabilities, htmlProgramTypes, verifyHtmlFrameRequest, verifyHtmlRasterRequest } from "@hypit/hypit/html-program";
+import { canonicalize } from "@hypit/hypit/protocol";
+import { rasterizeHtmlProgram, rasterizeHtmlFrames, resolveExecutionOptions } from "./render.js";
+import { renderWorkerLimit } from "./concurrency.js";
+import type { HtmlExecutionOptions } from "./options.js";
import { renderProgressReporter } from "./progress.js";
export type * from "./options.js";
-export const localHyperframesProviderModuleRef = { name: "@hypit/provider-hyperframes-local", version: "1" } as const;
-export type CreateLocalHyperframesProviderOptions = HyperframesExecutionOptions & {
+export const localHtmlProviderModuleRef = { name: "@hypit/provider-html-local", version: "1" } as const;
+export type CreateLocalHtmlProviderOptions = HtmlExecutionOptions & {
readonly instance?: string;
readonly pool?: string;
/** Used by managed browser installation, not frame capture. */
@@ -19,44 +20,42 @@ export type CreateLocalHyperframesProviderOptions = HyperframesExecutionOptions
readonly browserCapacity?: number;
};
-export function createLocalHyperframesProvider(config: CreateLocalHyperframesProviderOptions) {
+export function createLocalHtmlProvider(config: CreateLocalHtmlProviderOptions) {
const execution = resolveExecutionOptions(config);
- const pool = config.pool ?? config.instance ?? "hyperframes.local";
+ const pool = config.pool ?? config.instance ?? "html.local";
const browsers = `capacity:${pool}/browsers`;
if (config.browserCapacity !== undefined && (!Number.isSafeInteger(config.browserCapacity) || config.browserCapacity < 1)) {
- throw new Error("HyperFrames browserCapacity must be a positive integer");
+ throw new Error("HTML renderer browserCapacity must be a positive integer");
}
const maxWorkers = execution.workers === "auto" ? Math.min(execution.maxWorkers, config.browserCapacity ?? Infinity) : execution.maxWorkers;
const reserved = { ...execution, maxWorkers };
- return defineEndpointPackage({
- module: localHyperframesProviderModuleRef,
- facet: "render",
- instance: config.instance ?? "hyperframes.local",
+ return defineEndpoint({
+ instance: config.instance ?? "html.local",
pool,
pricing: { kind: "local" },
defaultConcurrency: config.defaultConcurrency ?? 1,
capabilities: [{
lifecycle: "immediate" as const,
- capability: renderHyperframesCapabilities.renderVisual,
- returns: mediaTypes.renderedVisual,
+ capability: htmlProgramCapabilities.rasterizeVisual,
+ returns: mediaTypes.timelineVisual,
...(config.browserCapacity === undefined ? {} : {
resources: [{ id: browsers, limit: config.browserCapacity }],
- unitsForRequest: (request: import("@hypit/endpoint-kit").EndpointRequest) => {
- verifyHyperframesVisualRequest(request.constraints);
- const { document, range } = request.constraints;
+ unitsForRequest: (request: import("@hypit/hypit/endpoint").EndpointRequest) => {
+ verifyHtmlRasterRequest(request.constraints);
+ const { program, range } = request.constraints;
return { [browsers]: renderWorkerLimit(reserved,
- range === undefined ? document.frameCount : range.endFrameExclusive - range.startFrame,
- document.frameRate.numerator / document.frameRate.denominator) };
+ range === undefined ? program.frameCount : range.endFrameExclusive - range.startFrame,
+ program.frameRate.numerator / program.frameRate.denominator) };
},
}),
handler: async (context) => {
const request = context.need.constraints;
- verifyHyperframesVisualRequest(request);
- const frameCount = request.range === undefined ? request.document.frameCount
+ verifyHtmlRasterRequest(request);
+ const frameCount = request.range === undefined ? request.program.frameCount
: request.range.endFrameExclusive - request.range.startFrame;
const progress = renderProgressReporter(context.reportProgress, frameCount);
try {
- const visual = await renderHyperframesVisual(request, { ...config,
+ const visual = await rasterizeHtmlProgram(request, { ...config,
...(execution.chromePath === undefined ? { browserVersion: execution.browserVersion! } : { chromePath: execution.chromePath }),
browserCacheDirectory: execution.browserCacheDirectory,
workers: execution.workers, maxWorkers,
@@ -69,23 +68,23 @@ export function createLocalHyperframesProvider(config: CreateLocalHyperframesPro
},
}, {
lifecycle: "immediate" as const,
- capability: renderHyperframesCapabilities.renderFrames,
- returns: renderHyperframesTypes.frames,
+ capability: htmlProgramCapabilities.rasterizeFrames,
+ returns: htmlProgramTypes.frameImages,
...(config.browserCapacity === undefined ? {} : {
resources: [{ id: browsers, limit: config.browserCapacity }],
- unitsForRequest: (request: import("@hypit/endpoint-kit").EndpointRequest) => {
- verifyHyperframesFramesRequest(request.constraints);
- const document = hyperframesFramesDomain(request.constraints);
+ unitsForRequest: (request: import("@hypit/hypit/endpoint").EndpointRequest) => {
+ verifyHtmlFrameRequest(request.constraints);
+ const document = request.constraints.program;
return { [browsers]: renderWorkerLimit(reserved, request.constraints.frames.length,
document.frameRate.numerator / document.frameRate.denominator) };
},
}),
handler: async context => {
const request = context.need.constraints;
- verifyHyperframesFramesRequest(request);
+ verifyHtmlFrameRequest(request);
const progress = renderProgressReporter(context.reportProgress, request.frames.length);
try {
- const frames = await renderHyperframesFrames(request, { ...config,
+ const frames = await rasterizeHtmlFrames(request, { ...config,
...(execution.chromePath === undefined ? { browserVersion: execution.browserVersion! } : { chromePath: execution.chromePath }),
browserCacheDirectory: execution.browserCacheDirectory,
workers: execution.workers, maxWorkers,
diff --git a/packages/provider-hyperframes-local/src/render.ts b/packages/provider-html-local/src/render.ts
similarity index 70%
rename from packages/provider-hyperframes-local/src/render.ts
rename to packages/provider-html-local/src/render.ts
index 46eae457..7ea15fa9 100644
--- a/packages/provider-hyperframes-local/src/render.ts
+++ b/packages/provider-html-local/src/render.ts
@@ -2,23 +2,23 @@ import { createReadStream } from "node:fs";
import { mkdtemp, readFile, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
-import type { EndpointInvocationContext } from "@hypit/endpoint-kit";
-import { stageHyperframesProject, stageHyperframesHtmlProject } from "@hypit/hyperframes/project";
-import { sealRenderedVisual } from "@hypit/media";
-import type { MediaFrameRange, RenderedVisual } from "@hypit/media";
-import { verifyCompositableSurfaceFile } from "@hypit/media-execution";
-import { verifyHyperframesVisualRequest, verifyHyperframesFramesRequest, hyperframesFramesDomain } from "@hypit/render-hyperframes";
-import type { HyperframesVisualRequest, HyperframesFramesRequest, HyperframesFrames } from "@hypit/render-hyperframes";
-import { isStreamingResourceStore } from "@hypit/runtime";
-import type { HyperframesExecutionOptions } from "./options.js";
+import type { EndpointInvocationContext } from "@hypit/hypit/endpoint";
+import { sealTimelineVisual } from "@hypit/hypit/media";
+import type { MediaFrameRange, TimelineVisual } from "@hypit/hypit/media";
+import { verifyCompositableSurfaceFile } from "./surface-validation.js";
+import { htmlFrameSelectionPrelude, verifyHtmlRasterRequest, verifyHtmlFrameRequest } from "@hypit/hypit/html-program";
+import type { HtmlRasterRequest, HtmlFrameRequest, HtmlFrameImages } from "@hypit/hypit/html-program";
+import { isStreamingResourceStore } from "@hypit/hypit/endpoint";
+import type { HtmlExecutionOptions } from "./options.js";
import { assert, positiveInteger } from "./process.js";
import { runCaptureProcess } from "./capture-process.js";
import { finished } from "node:stream/promises";
-import { autoWorkerLimit } from "./concurrency.js";
+import { autoWorkerLimit, renderWorkerLimit } from "./concurrency.js";
import { requestedFrameRanges } from "./sampling.js";
import { browserCacheDirectory, browserExecutablePath, configuredBrowserPath, requireBrowserExecutable, selectedBrowserVersion } from "./browser.js";
+import { htmlArtifactRelativePath, stageHtmlProgram } from "./stage.js";
-export type HyperframesRenderProgress =
+export type HtmlRasterProgress =
| { readonly phase: "staging" | "encoding" | "storing"; readonly elapsedMs: number }
| { readonly phase: "decoding"; readonly completed: number; readonly total: number; readonly elapsedMs: number }
| { readonly phase: "worker-progress"; readonly worker: number; readonly completed: number; readonly elapsedMs: number }
@@ -29,21 +29,21 @@ export type HyperframesRenderProgress =
readonly browserPid: number | undefined; readonly elapsedMs: number }
| { readonly phase: "complete"; readonly frames: number; readonly elapsedMs: number };
-export type RenderHyperframesVisualOptions = HyperframesExecutionOptions & {
+export type HtmlRasterOptions = HtmlExecutionOptions & {
readonly resources: EndpointInvocationContext["resources"];
readonly signal?: AbortSignal;
- readonly onDiagnostic?: (diagnostic: import("@hypit/runtime").ExecutionDiagnostic) => Promise<void>;
- readonly onProgress?: (event: HyperframesRenderProgress) => void;
+ readonly onDiagnostic?: (diagnostic: import("@hypit/hypit/endpoint").ExecutionDiagnostic) => Promise<void>;
+ readonly onProgress?: (event: HtmlRasterProgress) => void;
};
-export function resolveExecutionOptions(options: HyperframesExecutionOptions) {
+export function resolveExecutionOptions(options: HtmlExecutionOptions) {
const workers = options.workers ?? "auto";
assert(workers === "auto" || (Number.isSafeInteger(workers) && workers > 0),
"workers must be auto or a positive safe integer");
const quality = options.quality ?? "standard";
- assert(["draft", "standard", "high"].includes(quality), "HyperFrames quality is invalid");
+ assert(["draft", "standard", "high"].includes(quality), "HTML renderer quality is invalid");
const browserGpu = options.browserGpu ?? "hardware";
- assert(["auto", "software", "hardware"].includes(browserGpu), "HyperFrames browserGpu is invalid");
+ assert(["auto", "software", "hardware"].includes(browserGpu), "HTML renderer browserGpu is invalid");
return {
chromePath: configuredBrowserPath(options),
browserVersion: selectedBrowserVersion(options),
@@ -68,39 +68,37 @@ export function resolveExecutionOptions(options: HyperframesExecutionOptions) {
};
}
-/** Same deterministic reservation for Runtime admission and the capture attempt. */
-export function renderWorkerLimit(config: ReturnType<typeof resolveExecutionOptions>, frameCount: number, fps: number): number {
- return Math.min(config.maxWorkers, config.workers === "auto" ? Math.max(1, Math.ceil(frameCount / fps)) : frameCount);
-}
+export { renderWorkerLimit } from "./concurrency.js";
/** Execute one attempt. Its deadline includes resource preparation and output storage. */
-export async function renderHyperframesVisual(
- request: HyperframesVisualRequest,
- options: RenderHyperframesVisualOptions,
-): Promise<RenderedVisual> {
- verifyHyperframesVisualRequest(request);
- return capture(request, options) as Promise<RenderedVisual>;
+export async function rasterizeHtmlProgram(
+ request: HtmlRasterRequest,
+ options: HtmlRasterOptions,
+): Promise<TimelineVisual> {
+ verifyHtmlRasterRequest(request);
+ return capture(request, options) as Promise<TimelineVisual>;
}
-export async function renderHyperframesFrames(request: HyperframesFramesRequest, options: RenderHyperframesVisualOptions): Promise<HyperframesFrames> {
- verifyHyperframesFramesRequest(request);
- return capture(request, options) as Promise<HyperframesFrames>;
+export async function rasterizeHtmlFrames(request: HtmlFrameRequest, options: HtmlRasterOptions): Promise<HtmlFrameImages> {
+ verifyHtmlFrameRequest(request);
+ return capture(request, options) as Promise<HtmlFrameImages>;
}
-async function capture(request: HyperframesVisualRequest | HyperframesFramesRequest, options: RenderHyperframesVisualOptions): Promise<RenderedVisual | HyperframesFrames> {
+async function capture(request: HtmlRasterRequest | HtmlFrameRequest, options: HtmlRasterOptions): Promise<TimelineVisual | HtmlFrameImages> {
const config = { ...resolveExecutionOptions(options), chromePath: browserExecutablePath(options) };
const frames = "frames" in request ? request.frames : undefined;
- const document = "frames" in request ? hyperframesFramesDomain(request) : request.document;
+ const document = request.program;
const range = frames === undefined
- ? (request as HyperframesVisualRequest).range ?? { startFrame: 0, endFrameExclusive: document.frameCount }
+ ? (request as HtmlRasterRequest).range ?? { startFrame: 0, endFrameExclusive: document.frameCount }
: { startFrame: frames[0]!, endFrameExclusive: frames.at(-1)! + 1 };
const frameCount = frames?.length ?? range.endFrameExclusive - range.startFrame;
+ const frameSelection = requestedFrameRanges(range, frames);
const controller = new AbortController();
const signal = options.signal === undefined ? controller.signal : AbortSignal.any([controller.signal, options.signal]);
const started = performance.now();
let phaseStarted = started;
let phase = "preparing resources";
- const timer = setTimeout(() => controller.abort(new Error(`HyperFrames render timed out during ${phase}`)), config.processTimeoutMs);
+ const timer = setTimeout(() => controller.abort(new Error(`HTML renderer render timed out during ${phase}`)), config.processTimeoutMs);
let work: string | undefined;
const diagnostics: Promise<void>[] = [];
const diagnostic = (message: string) => {
@@ -124,17 +122,16 @@ async function capture(request: HyperframesVisualRequest | HyperframesFramesRequ
+ `; decoded source budget ${config.maxDecodedSourceBytes} bytes`
+ (frames === undefined ? `; quality ${config.quality}; ordered FFmpeg pipe; pending PNG budget ${config.maxPendingFrameBytes} bytes; encoder ${config.ffmpegPath}` : "; PNG output") });
options.onProgress?.({ phase: "staging", elapsedMs: 0 });
- work = await mkdtemp(join(tmpdir(), "hypit-hyperframes-local-"));
- const read: import("@hypit/hyperframes/project").HyperframesArtifactReader = async (artifact, readSignal) => {
+ work = await mkdtemp(join(tmpdir(), "hypit-html-local-"));
+ const read: import("./stage.js").HtmlArtifactReader = async (artifact, readSignal) => {
const io = { signal: readSignal! };
const bytes = isStreamingResourceStore(options.resources)
? await options.resources.open(artifact.resource, io) : await options.resources.get(artifact.resource, io);
- assert(bytes !== undefined, `HyperFrames Artifact ${artifact.resource} is unavailable`);
+ assert(bytes !== undefined, `HTML renderer Artifact ${artifact.resource} is unavailable`);
return bytes;
};
- if ("project" in request) await stageHyperframesHtmlProject({ project: request.project, directory: work, signal, read });
- else await stageHyperframesProject({ document: request.document, directory: work, signal, read,
- frameSelection: requestedFrameRanges(range, frames),
+ await stageHtmlProgram({ document, directory: work, signal, read,
+ frameSelection,
maxConcurrentArtifacts: config.artifactStagingConcurrency,
validateSurface: (surface, path, probeSignal) => verifyCompositableSurfaceFile({ surface, path,
ffprobePath: config.ffprobePath, processTimeoutMs: config.processTimeoutMs,
@@ -142,8 +139,9 @@ async function capture(request: HyperframesVisualRequest | HyperframesFramesRequ
});
changePhase("preparing source media");
await runCaptureProcess({ document, range, ...(frames === undefined ? {} : { frames }), config, directory: work,
- engineModule: import.meta.resolve("@hyperframes/engine"),
- producerModule: import.meta.resolve("@hyperframes/producer"),
+ frameSelectionPrelude: htmlFrameSelectionPrelude(frameSelection),
+ artifactPaths: document.artifacts.map(({ artifact }) =>
+ [artifact.resource, htmlArtifactRelativePath(document, artifact.resource)] as const),
}, signal, (event) => {
if (event.phase === "prepared") changePhase("starting browsers");
if (event.phase === "worker-start" && phase === "starting browsers") changePhase("capturing frames");
@@ -163,9 +161,9 @@ async function capture(request: HyperframesVisualRequest | HyperframesFramesRequ
}
return options.resources.put(await readFile(output, { signal }), mediaType, { signal });
};
- let result: RenderedVisual | HyperframesFrames;
+ let result: TimelineVisual | HtmlFrameImages;
if (frames === undefined) {
- result = sealRenderedVisual({ frameRate: document.frameRate, frameCount, canvas: document.canvas,
+ result = sealTimelineVisual({ frameRate: document.frameRate, frameCount, canvas: document.canvas,
artifact: await store(join(work, "visual.mp4"), "video/mp4") });
} else {
const artifacts = [];
diff --git a/packages/provider-hyperframes-local/src/sampling.ts b/packages/provider-html-local/src/sampling.ts
similarity index 59%
rename from packages/provider-hyperframes-local/src/sampling.ts
rename to packages/provider-html-local/src/sampling.ts
index e3721fa1..21deaac3 100644
--- a/packages/provider-hyperframes-local/src/sampling.ts
+++ b/packages/provider-html-local/src/sampling.ts
@@ -1,4 +1,5 @@
-import type { MediaFrameRange } from "@hypit/media";
+import type { MediaFrameRange } from "@hypit/hypit/media";
+import type { HtmlFrameSource } from "@hypit/hypit/html-program";
import { FrameSpanIndex } from "./frame-span-index.js";
import { assert } from "./process.js";
@@ -16,54 +17,31 @@ export function requestedFrameRanges(range: MediaFrameRange, frames?: readonly n
if (frames === undefined) return [{ ...range }];
const result: MediaFrameRange[] = [];
for (const frame of frames) {
- assert(Number.isSafeInteger(frame) && frame >= 0, "HyperFrames requested frame is invalid");
+ assert(Number.isSafeInteger(frame) && frame >= 0, "HTML Program requested frame is invalid");
const previous = result.at(-1);
if (previous !== undefined && previous.endFrameExclusive === frame) {
result[result.length - 1] = { startFrame: previous.startFrame, endFrameExclusive: frame + 1 };
} else {
assert(previous === undefined || previous.endFrameExclusive < frame,
- "HyperFrames requested frames must be strictly increasing");
+ "HTML Program requested frames must be strictly increasing");
result.push({ startFrame: frame, endFrameExclusive: frame + 1 });
}
}
- assert(result.length > 0, "HyperFrames requested frames must not be empty");
+ assert(result.length > 0, "HTML Program requested frames must not be empty");
return result;
}
-function rational(value: string, label: string, signed = false): Rational {
- const pattern = signed ? /^-?\d+\/[1-9]\d*$/u : /^\d+\/[1-9]\d*$/u;
- assert(pattern.test(value), `HyperFrames ${label} must be a ${signed ? "signed" : "non-negative"} rational`);
- const [a, b] = value.split("/");
- return { numerator: BigInt(a!), denominator: BigInt(b!) };
-}
-
-/** Read the compiler's exact frame markers, without reconstructing author intent from seconds. */
-export function videoSlots(html: string): VideoSlot[] {
- return [...html.matchAll(/<video\b[^>]*>/gu)].map(([tag]) => {
- const optionalAttribute = (name: string): string | undefined => {
- const value = new RegExp(`(?:\\s)${name}="([^"]*)"`, "u").exec(tag)?.[1];
- return value?.replaceAll("&amp;", "&").replaceAll("&quot;", '"').replaceAll("&lt;", "<").replaceAll("&gt;", ">");
- };
- const attribute = (name: string): string => {
- const value = optionalAttribute(name);
- assert(value !== undefined, `HyperFrames video lacks ${name}; compile its frame sampling before rendering`);
- return value;
- };
- const sourceFps = rational(attribute("data-hypit-source-fps"), "source frame rate");
- const slot = {
- id: attribute("id"), src: optionalAttribute("data-hypit-resource-src") ?? attribute("src"),
- startFrame: Number(attribute("data-hypit-start-frame")),
- endFrameExclusive: Number(attribute("data-hypit-end-frame")),
- sourceFrame: rational(attribute("data-hypit-source-frame"), "source frame"),
- sourceRate: rational(attribute("data-hypit-source-rate"), "source rate", true),
- sourceFps: { num: Number(sourceFps.numerator), den: Number(sourceFps.denominator) },
- };
- assert(Number.isSafeInteger(slot.startFrame) && slot.startFrame >= 0
- && Number.isSafeInteger(slot.endFrameExclusive) && slot.endFrameExclusive > slot.startFrame
- && Number.isSafeInteger(slot.sourceFps.num) && slot.sourceFps.num > 0
- && Number.isSafeInteger(slot.sourceFps.den), "HyperFrames video frame mapping is invalid");
- return slot;
- });
+/** Project the compiler's typed source plan onto staged paths; markup is never parsed back into execution data. */
+export function videoSlots(sources: readonly HtmlFrameSource[], pathFor: (resource: string) => string): VideoSlot[] {
+ return sources.map((source) => ({
+ id: source.id,
+ src: pathFor(source.resource),
+ startFrame: source.startFrame,
+ endFrameExclusive: source.endFrameExclusive,
+ sourceFrame: { numerator: BigInt(source.sourceFrame.numerator), denominator: BigInt(source.sourceFrame.denominator) },
+ sourceRate: { numerator: BigInt(source.sourceRate.numerator), denominator: BigInt(source.sourceRate.denominator) },
+ sourceFps: { num: source.sourceFrameRate.numerator, den: source.sourceFrameRate.denominator },
+ }));
}
/** A decoded frame owns [n, n+1) in source-frame coordinates. */
@@ -72,7 +50,7 @@ export function sourceFrameAt(slot: VideoSlot, frame: number): number {
const r = slot.sourceRate;
const value = Number((a.numerator * r.denominator
+ BigInt(frame - slot.startFrame) * r.numerator * a.denominator) / (a.denominator * r.denominator));
- assert(Number.isSafeInteger(value) && value >= 0, "HyperFrames source frame exceeds safe arithmetic");
+ assert(Number.isSafeInteger(value) && value >= 0, "HTML Program source frame exceeds safe arithmetic");
return value;
}
@@ -90,7 +68,7 @@ export function sourceWindows(slots: readonly VideoSlot[], selection: MediaFrame
sources.set(slot.src, source);
}
assert(source.fps.num * slot.sourceFps.den === slot.sourceFps.num * source.fps.den,
- "One HyperFrames source has conflicting frame rates");
+ "One HTML Program source has conflicting frame rates");
const firstSource = sourceFrameAt(slot, first);
const lastSource = sourceFrameAt(slot, last);
source.windows.push({
diff --git a/packages/provider-html-local/src/server.ts b/packages/provider-html-local/src/server.ts
new file mode 100644
index 00000000..753edce4
--- /dev/null
+++ b/packages/provider-html-local/src/server.ts
@@ -0,0 +1,52 @@
+import { createReadStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import { createServer } from "node:http";
+import { extname, resolve, sep } from "node:path";
+
+const mediaTypes: Readonly<Record<string, string>> = {
+ ".html": "text/html; charset=utf-8",
+ ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp",
+ ".mp4": "video/mp4", ".webm": "video/webm",
+ ".woff": "font/woff", ".woff2": "font/woff2", ".ttf": "font/ttf", ".otf": "font/otf",
+};
+
+/** Serve one staged program and its lazily decoded frames to local capture pages. */
+export async function serveHtmlProgram(root: string): Promise<{ readonly url: string; close(): Promise<void> }> {
+ const base = resolve(root);
+ const server = createServer(async (request, response) => {
+ try {
+ const pathname = decodeURIComponent(new URL(request.url ?? "/", "http://127.0.0.1").pathname);
+ const path = resolve(base, pathname === "/" ? "index.html" : `.${pathname}`);
+ if (path !== base && !path.startsWith(`${base}${sep}`)) {
+ response.writeHead(403).end(); return;
+ }
+ const info = await stat(path);
+ if (!info.isFile()) { response.writeHead(404).end(); return; }
+ const range = /^bytes=(\d+)-(\d*)$/u.exec(request.headers.range ?? "");
+ const start = range === null ? 0 : Number(range[1]);
+ const end = range === null || range[2] === "" ? info.size - 1 : Number(range[2]);
+ if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 0 || end < start || end >= info.size) {
+ response.writeHead(416, { "Content-Range": `bytes */${info.size}` }).end(); return;
+ }
+ response.writeHead(range === null ? 200 : 206, {
+ "Content-Type": mediaTypes[extname(path).toLowerCase()] ?? "application/octet-stream",
+ "Content-Length": end - start + 1,
+ "Accept-Ranges": "bytes",
+ ...(range === null ? {} : { "Content-Range": `bytes ${start}-${end}/${info.size}` }),
+ });
+ createReadStream(path, { start, end }).on("error", () => response.destroy()).pipe(response);
+ } catch (error) {
+ response.writeHead((error as NodeJS.ErrnoException).code === "ENOENT" ? 404 : 500).end();
+ }
+ });
+ await new Promise<void>((resolveReady, reject) => {
+ server.once("error", reject);
+ server.listen(0, "127.0.0.1", () => { server.off("error", reject); resolveReady(); });
+ });
+ const address = server.address();
+ if (address === null || typeof address === "string") throw new Error("HTML Program server did not bind a TCP port");
+ return {
+ url: `http://127.0.0.1:${address.port}/`,
+ close: () => new Promise<void>((resolveClose, reject) => server.close(error => error ? reject(error) : resolveClose())),
+ };
+}
diff --git a/packages/provider-hyperframes-local/src/source-frame-decoder.ts b/packages/provider-html-local/src/source-frame-decoder.ts
similarity index 74%
rename from packages/provider-hyperframes-local/src/source-frame-decoder.ts
rename to packages/provider-html-local/src/source-frame-decoder.ts
index 8001194d..9b90ee1c 100644
--- a/packages/provider-hyperframes-local/src/source-frame-decoder.ts
+++ b/packages/provider-html-local/src/source-frame-decoder.ts
@@ -1,13 +1,40 @@
import { spawn } from "node:child_process";
import { mkdir, writeFile } from "node:fs/promises";
import { join } from "node:path";
-import type { VideoMetadata } from "@hyperframes/engine";
-import { assert, processEnvironment } from "./process.js";
+import { assert, processEnvironment, runProcess } from "./process.js";
import type { DecodedSourceFrame, SourceFrameWindow } from "./source-frame-store.js";
const pngSignature = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
const alphaCodecs = new Set(["vp9", "vp8", "prores"]);
+export type SourceVideoMetadata = {
+ readonly width: number;
+ readonly height: number;
+ readonly videoCodec: string;
+ readonly isVFR: boolean;
+ readonly colorSpace?: { readonly colorTransfer?: string };
+};
+
+export async function probeSourceVideo(args: {
+ readonly executable: string; readonly path: string; readonly timeoutMs: number;
+ readonly maxOutputBytes: number; readonly signal?: AbortSignal;
+}): Promise<SourceVideoMetadata> {
+ const result = await runProcess({ executable: args.executable, argv: ["-v", "error", "-select_streams", "v:0",
+ "-show_entries", "stream=width,height,codec_name,color_transfer,avg_frame_rate,r_frame_rate", "-of", "json", args.path],
+ timeoutMs: args.timeoutMs, maxOutputBytes: args.maxOutputBytes, ...(args.signal === undefined ? {} : { signal: args.signal }) });
+ const data = JSON.parse(Buffer.from(result.stdout).toString("utf8")) as { streams?: Array<Record<string, unknown>> };
+ const stream = data.streams?.[0];
+ const width = Number(stream?.width), height = Number(stream?.height);
+ const codec = stream?.codec_name;
+ assert(Number.isSafeInteger(width) && width > 0 && Number.isSafeInteger(height) && height > 0
+ && typeof codec === "string" && codec.length > 0, `HTML renderer source ${args.path} has no usable video stream`);
+ const avg = String(stream?.avg_frame_rate ?? "");
+ const nominal = String(stream?.r_frame_rate ?? "");
+ const transfer = typeof stream?.color_transfer === "string" ? stream.color_transfer : undefined;
+ return { width, height, videoCodec: codec, isVFR: avg.length > 0 && nominal.length > 0 && avg !== nominal,
+ ...(transfer === undefined ? {} : { colorSpace: { colorTransfer: transfer } }) };
+}
+
/** Incremental parser for concatenated PNGs from FFmpeg image2pipe. */
export class PngFrameParser {
readonly #maxFrameBytes: number;
@@ -69,7 +96,7 @@ export async function* decodeSourceFrameWindow(args: {
readonly outputPrefix: string;
readonly window: Omit<SourceFrameWindow, "source">;
readonly fps: { readonly num: number; readonly den: number };
- readonly metadata: VideoMetadata;
+ readonly metadata: SourceVideoMetadata;
readonly timeoutMs: number;
readonly maxProcessOutputBytes: number;
readonly signal?: AbortSignal;
@@ -110,18 +137,18 @@ export async function* decodeSourceFrameWindow(args: {
};
const abort = () => stop(args.signal?.reason instanceof Error ? args.signal.reason : new Error(String(args.signal?.reason)));
args.signal?.addEventListener("abort", abort, { once: true });
- const timer = setTimeout(() => stop(new Error(`HyperFrames source decoder timed out after ${args.timeoutMs} ms`)), args.timeoutMs);
+ const timer = setTimeout(() => stop(new Error(`HTML renderer source decoder timed out after ${args.timeoutMs} ms`)), args.timeoutMs);
child.stderr!.on("data", (chunk: Buffer) => {
stderrBytes += chunk.byteLength;
stderr = `${stderr}${chunk.toString()}`.slice(-32_000);
- if (stderrBytes > args.maxProcessOutputBytes) stop(new Error("HyperFrames source decoder output exceeded its byte limit"));
+ if (stderrBytes > args.maxProcessOutputBytes) stop(new Error("HTML renderer source decoder output exceeded its byte limit"));
});
const outcome = new Promise<{ code: number | null; signal: NodeJS.Signals | null }>((resolve, reject) => {
child.once("error", reject);
child.once("close", (code, signal) => { closed = true; resolve({ code, signal }); });
});
const maxFrameBytes = args.metadata.width * args.metadata.height * 10 + 64 * 1024;
- assert(Number.isSafeInteger(maxFrameBytes), "HyperFrames decoded source frame limit exceeds safe arithmetic");
+ assert(Number.isSafeInteger(maxFrameBytes), "HTML renderer decoded source frame limit exceeds safe arithmetic");
const parser = new PngFrameParser(maxFrameBytes);
let produced = 0;
let completed = false;
@@ -140,7 +167,7 @@ export async function* decodeSourceFrameWindow(args: {
if (stopped !== undefined) throw stopped;
args.signal?.throwIfAborted();
assert(result.code === 0, `FFmpeg source decoder exited ${result.signal ?? `code ${String(result.code)}`}: ${stderr}`);
- assert(produced === count, `HyperFrames expected ${count} source frames, decoded ${produced}`);
+ assert(produced === count, `HTML renderer expected ${count} source frames, decoded ${produced}`);
completed = true;
} finally {
clearTimeout(timer);
diff --git a/packages/provider-hyperframes-local/src/source-frame-store.ts b/packages/provider-html-local/src/source-frame-store.ts
similarity index 96%
rename from packages/provider-hyperframes-local/src/source-frame-store.ts
rename to packages/provider-html-local/src/source-frame-store.ts
index a3eaba72..f40aa0be 100644
--- a/packages/provider-hyperframes-local/src/source-frame-store.ts
+++ b/packages/provider-html-local/src/source-frame-store.ts
@@ -146,11 +146,11 @@ export class SourceFrameStore {
let retained = false;
try {
this.#throwIfStopped();
- assert(frame.frame === expected, `HyperFrames source decoder returned frame ${frame.frame}, expected ${expected}`);
+ assert(frame.frame === expected, `HTML renderer source decoder returned frame ${frame.frame}, expected ${expected}`);
expected++;
- assert(Number.isSafeInteger(frame.bytes) && frame.bytes > 0, "HyperFrames decoded source frame is empty");
+ assert(Number.isSafeInteger(frame.bytes) && frame.bytes > 0, "HTML renderer decoded source frame is empty");
assert(!this.#resident.get(job.source)?.has(frame.frame),
- `HyperFrames decoded source frame ${frame.frame} more than once concurrently`);
+ `HTML renderer decoded source frame ${frame.frame} more than once concurrently`);
const hard = target.required.get(job.source)?.has(frame.frame) === true;
retained = await this.#admit(job.source, frame, this.#requiredDemand(target),
this.#preferredDemand(target), target, hard);
@@ -220,7 +220,7 @@ export class SourceFrameStore {
const leased: ResidentFrame[] = [];
for (const [source, frames] of waiter.required) for (const frame of frames) {
const resident = this.#resident.get(source)?.get(frame);
- assert(resident !== undefined, `HyperFrames has no decoded source frame ${frame}`);
+ assert(resident !== undefined, `HTML renderer has no decoded source frame ${frame}`);
resident.leases++;
resident.lastUse = ++this.#clock;
leased.push(resident);
@@ -232,7 +232,7 @@ export class SourceFrameStore {
if (released) return;
released = true;
for (const frame of leased) {
- assert(frame.leases > 0, "HyperFrames source frame lease underflow");
+ assert(frame.leases > 0, "HTML renderer source frame lease underflow");
frame.leases--;
}
this.#activeLeases--;
diff --git a/packages/hyperframes/src/project.ts b/packages/provider-html-local/src/stage.ts
similarity index 58%
rename from packages/hyperframes/src/project.ts
rename to packages/provider-html-local/src/stage.ts
index ddd14c69..216aaa2f 100644
--- a/packages/hyperframes/src/project.ts
+++ b/packages/provider-html-local/src/stage.ts
@@ -1,21 +1,18 @@
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 { materializeHyperframesHtml, selectHyperframesArtifacts } from "./document.js";
-import type { HyperframesDocument, HyperframesFrameSpan } from "./types.js";
-import { assertHyperframesHtmlProject, mapHyperframesHtmlUrls } from "./html-project.js";
-import type { HyperframesHtmlProject } from "./html-project.js";
+import { materializeHtmlProgram, selectHtmlArtifacts } from "@hypit/hypit/html-program";
+import type { HtmlProgram, HtmlFrameSpan } from "@hypit/hypit/html-program";
+import type { CompositableSurfaceRef } from "@hypit/hypit/media";
+import type { BlobRef } from "@hypit/hypit/protocol";
/** Reads one execution resource. Whose store it comes from is the caller's business. */
-export type HyperframesArtifactReader = (
+export type HtmlArtifactReader = (
artifact: BlobRef,
signal?: AbortSignal,
) => Promise<Uint8Array | AsyncIterable<Uint8Array>>;
/** Inspect the completed staged file; its lifetime belongs to the staging caller. */
-export type HyperframesSurfaceValidator = (
+export type HtmlSurfaceValidator = (
surface: CompositableSurfaceRef,
path: string,
signal?: AbortSignal,
@@ -35,59 +32,29 @@ const EXTENSIONS: Readonly<Record<string, string>> = {
function extension(mediaType: string): string {
const found = EXTENSIONS[mediaType];
- if (found === undefined) throw new Error(`HyperFrames does not support Artifact media type ${mediaType}`);
+ if (found === undefined) throw new Error(`HTML renderer does not support Artifact media type ${mediaType}`);
return found;
}
-/** Stage an existing HTML programme; no reverse compilation or inferred Surface declarations. */
-export async function stageHyperframesHtmlProject(options: {
- readonly project: HyperframesHtmlProject;
- readonly directory: string;
- readonly read: HyperframesArtifactReader;
- readonly signal?: AbortSignal;
-}): Promise<void> {
- assertHyperframesHtmlProject(options.project);
- await mkdir(join(options.directory, "artifacts"), { recursive: true });
- const paths = new Map<string, string>();
- const resourcePaths = new Map<string, { readonly artifact: BlobRef; readonly path: string }>();
- for (const asset of options.project.assets) {
- options.signal?.throwIfAborted();
- let staged = resourcePaths.get(asset.artifact.resource);
- if (staged !== undefined) {
- if (staged.artifact.size !== asset.artifact.size || staged.artifact.mediaType !== asset.artifact.mediaType) {
- throw new Error(`HyperFrames Artifact ${asset.artifact.resource} has conflicting metadata`);
- }
- } else {
- const path = `artifacts/asset-${resourcePaths.size}${extension(asset.artifact.mediaType)}`;
- const bytes = await options.read(asset.artifact, options.signal);
- const file = await open(join(options.directory, path), "w");
- try {
- if (bytes instanceof Uint8Array) await file.writeFile(bytes);
- else for await (const chunk of bytes) { options.signal?.throwIfAborted(); await file.writeFile(chunk); }
- } finally { await file.close(); }
- staged = { artifact: asset.artifact, path };
- resourcePaths.set(asset.artifact.resource, staged);
- }
- paths.set(asset.url, `./${staged.path}`);
- }
- await writeFile(join(options.directory, "index.html"), mapHyperframesHtmlUrls(options.project.html, url => paths.get(url) ?? url), {
- encoding: "utf8", ...(options.signal === undefined ? {} : { signal: options.signal }),
- });
+export function htmlArtifactRelativePath(document: HtmlProgram, resource: string): string {
+ const index = document.artifacts.findIndex((entry) => entry.artifact.resource === resource);
+ if (index < 0) throw new Error(`HTML Program Artifact ${resource} is not declared`);
+ return `artifacts/asset-${index}${extension(document.artifacts[index]!.artifact.mediaType)}`;
}
/**
- * Lay one document out as a directory HyperFrames can render.
+ * Lay one document out as a directory HTML renderer can render.
*
- * A local or hosted Provider can serve the same staged document to its capture engine.
+ * This local Provider serves the staged document to its browser workers.
* Resource names are local to this staged project and carry no content claim.
*/
-export async function stageHyperframesProject(options: {
- readonly document: HyperframesDocument;
+export async function stageHtmlProgram(options: {
+ readonly document: HtmlProgram;
readonly directory: string;
- readonly read: HyperframesArtifactReader;
- readonly validateSurface?: HyperframesSurfaceValidator;
+ readonly read: HtmlArtifactReader;
+ readonly validateSurface?: HtmlSurfaceValidator;
/** Whole-request absolute selection. Omit only when every frame may be rendered. */
- readonly frameSelection?: readonly HyperframesFrameSpan[];
+ readonly frameSelection?: readonly HtmlFrameSpan[];
/** Maximum complete Artifact read/write/validation lifecycles in flight. */
readonly maxConcurrentArtifacts?: number;
readonly signal?: AbortSignal;
@@ -96,11 +63,11 @@ export async function stageHyperframesProject(options: {
const controller = new AbortController();
const signal = options.signal === undefined ? controller.signal : AbortSignal.any([options.signal, controller.signal]);
signal.throwIfAborted();
- const selectedResources = new Set(selectHyperframesArtifacts(document, options.frameSelection)
+ const selectedResources = new Set(selectHtmlArtifacts(document, options.frameSelection)
.map((entry) => entry.artifact.resource));
const maxConcurrentArtifacts = options.maxConcurrentArtifacts ?? 1;
if (!Number.isSafeInteger(maxConcurrentArtifacts) || maxConcurrentArtifacts < 1) {
- throw new Error("HyperFrames Artifact staging concurrency must be a positive safe integer");
+ throw new Error("HTML renderer Artifact staging concurrency must be a positive safe integer");
}
const artifactDirectory = join(directory, "artifacts");
await mkdir(artifactDirectory, { recursive: true });
@@ -114,7 +81,7 @@ export async function stageHyperframesProject(options: {
const surfaces = new Map(document.surfaces.map((surface) => [surface.artifact.resource, surface]));
if (options.validateSurface === undefined
&& selected.some(({ entry }) => surfaces.has(entry.artifact.resource))) {
- throw new Error("HyperFrames Runtime has no Surface-byte validator");
+ throw new Error("HTML renderer Runtime has no Surface-byte validator");
}
let nextArtifact = 0;
let failure: unknown;
@@ -148,7 +115,7 @@ export async function stageHyperframesProject(options: {
await target.close();
}
if (size !== artifact.size) {
- throw new Error(`HyperFrames Artifact ${artifact.resource} size differs`);
+ throw new Error(`HTML renderer Artifact ${artifact.resource} size differs`);
}
if (surface !== undefined) {
// The validator borrows the completed staged file for this call only.
@@ -172,9 +139,9 @@ export async function stageHyperframesProject(options: {
signal.throwIfAborted();
if (failure !== undefined) throw failure;
// All writes have settled before the caller can remove the staged directory.
- const html = materializeHyperframesHtml(document, (artifact) => {
+ const html = materializeHtmlProgram(document, (artifact) => {
const path = paths.get(artifact.resource);
- if (path === undefined) throw new Error(`HyperFrames Artifact ${artifact.resource} has no materialized path`);
+ if (path === undefined) throw new Error(`HTML renderer Artifact ${artifact.resource} has no materialized path`);
return path;
});
await writeFile(join(directory, "index.html"), html, { encoding: "utf8", signal });
diff --git a/packages/provider-html-local/src/surface-validation.ts b/packages/provider-html-local/src/surface-validation.ts
new file mode 100644
index 00000000..daa8e1f7
--- /dev/null
+++ b/packages/provider-html-local/src/surface-validation.ts
@@ -0,0 +1,209 @@
+import { stat } from "node:fs/promises";
+
+import { assertCompositableSurfaceRef } from "@hypit/hypit/media";
+import type { CompositableSurfaceRef } from "@hypit/hypit/media";
+import { runProcess } from "./process.js";
+
+type JsonObject = Record<string, unknown>;
+
+type ProbeStream = {
+ readonly codec_type?: unknown;
+ readonly codec_name?: unknown;
+ readonly width?: unknown;
+ readonly height?: unknown;
+ readonly pix_fmt?: unknown;
+ readonly sample_aspect_ratio?: unknown;
+ readonly avg_frame_rate?: unknown;
+ readonly r_frame_rate?: unknown;
+ readonly nb_read_frames?: unknown;
+ readonly nb_frames?: unknown;
+ readonly color_range?: unknown;
+ readonly color_space?: unknown;
+ readonly color_transfer?: unknown;
+ readonly color_primaries?: unknown;
+ readonly field_order?: unknown;
+ readonly disposition?: { readonly attached_pic?: unknown };
+ readonly tags?: { readonly rotate?: unknown; readonly alpha_mode?: unknown };
+ readonly side_data_list?: readonly unknown[];
+};
+
+type PixelFormat = {
+ readonly name?: unknown;
+ readonly flags?: { readonly alpha?: unknown };
+};
+
+function assert(condition: unknown, message: string): asserts condition {
+ if (!condition) throw new Error(message);
+}
+
+function object(value: unknown): JsonObject | undefined {
+ return value !== null && typeof value === "object" && !Array.isArray(value)
+ ? value as JsonObject
+ : undefined;
+}
+
+function json(bytes: Uint8Array, subject: string): JsonObject {
+ let value: unknown;
+ try {
+ value = JSON.parse(Buffer.from(bytes).toString("utf8"));
+ } catch {
+ throw new Error(`${subject} returned invalid JSON`);
+ }
+ const result = object(value);
+ assert(result !== undefined, `${subject} returned an invalid object`);
+ return result;
+}
+
+function positiveInteger(value: unknown, subject: string): number {
+ const parsed = typeof value === "number"
+ ? value
+ : typeof value === "string" && /^\d+$/u.test(value) ? Number(value) : NaN;
+ assert(Number.isSafeInteger(parsed) && parsed > 0, `${subject} is not a positive integer`);
+ return parsed;
+}
+
+function rational(value: unknown, subject: string): { readonly numerator: number; readonly denominator: number } {
+ assert(typeof value === "string" && /^\d+\/\d+$/u.test(value), `${subject} is not a rational`);
+ const [rawNumerator, rawDenominator] = value.split("/");
+ const numerator = Number(rawNumerator);
+ const denominator = Number(rawDenominator);
+ assert(Number.isSafeInteger(numerator) && numerator > 0
+ && Number.isSafeInteger(denominator) && denominator > 0, `${subject} is invalid`);
+ return { numerator, denominator };
+}
+
+function sameRational(
+ left: { readonly numerator: number; readonly denominator: number },
+ right: { readonly numerator: number; readonly denominator: number },
+): boolean {
+ return BigInt(left.numerator) * BigInt(right.denominator)
+ === BigInt(right.numerator) * BigInt(left.denominator);
+}
+
+function rotation(stream: ProbeStream): number {
+ const side = stream.side_data_list?.map(object).find((item) => item?.side_data_type === "Display Matrix");
+ const value = side?.rotation ?? stream.tags?.rotate ?? 0;
+ const parsed = typeof value === "number" ? value : Number(value);
+ assert(Number.isFinite(parsed), "Surface rotation metadata is invalid");
+ return ((parsed % 360) + 360) % 360;
+}
+
+function assertSrgb(stream: ProbeStream): void {
+ const allowed = {
+ color_space: new Set([undefined, "unknown", "gbr", "rgb", "bt709"]),
+ color_transfer: new Set([undefined, "unknown", "iec61966-2-1", "bt709"]),
+ color_primaries: new Set([undefined, "unknown", "bt709"]),
+ color_range: new Set([undefined, "unknown", "pc", "tv"]),
+ } as const;
+ for (const [name, values] of Object.entries(allowed)) {
+ const value = stream[name as keyof typeof allowed];
+ assert(typeof value === "string" || value === undefined, `Surface ${name} metadata is invalid`);
+ assert(values.has(value), `Surface ${name} ${String(value)} is not SDR sRGB-compatible`);
+ }
+}
+
+const pixelFormats = new Map<string, Map<string, boolean>>();
+
+async function pixelFormatAlpha(
+ ffprobePath: string,
+ timeoutMs: number,
+ maxOutputBytes: number,
+ signal: AbortSignal,
+): Promise<Map<string, boolean>> {
+ signal.throwIfAborted();
+ const cached = pixelFormats.get(ffprobePath);
+ if (cached !== undefined) return cached;
+ const root = json((await runProcess({ executable: ffprobePath,
+ argv: ["-v", "error", "-print_format", "json", "-show_pixel_formats"],
+ timeoutMs, maxOutputBytes, signal,
+ })).stdout, "ffprobe pixel-format query");
+ assert(Array.isArray(root.pixel_formats), "ffprobe returned no pixel-format table");
+ const result = new Map<string, boolean>();
+ for (const raw of root.pixel_formats) {
+ const format = object(raw) as PixelFormat | undefined;
+ if (typeof format?.name === "string") result.set(format.name, format.flags?.alpha === 1);
+ }
+ // Cache completed facts only; cancelling one caller cannot cancel another's probe.
+ pixelFormats.set(ffprobePath, result);
+ return result;
+}
+
+type SurfaceInspectionOptions = {
+ readonly surface: CompositableSurfaceRef;
+ readonly ffprobePath?: string;
+ readonly processTimeoutMs?: number;
+ readonly maxProbeOutputBytes?: number;
+ readonly signal?: AbortSignal;
+};
+
+/**
+ * Inspect an existing execution file without copying it. The caller owns the file
+ * and keeps it unchanged until this call settles. Success returns no side-channel facts.
+ */
+export async function verifyCompositableSurfaceFile(options: SurfaceInspectionOptions & {
+ readonly path: string;
+}): Promise<void> {
+ const controller = new AbortController();
+ const signal = options.signal === undefined ? controller.signal : AbortSignal.any([controller.signal, options.signal]);
+ signal.throwIfAborted();
+ assertCompositableSurfaceRef(options.surface);
+ assert((await stat(options.path)).size === options.surface.artifact.size,
+ `Surface ${options.surface.artifact.resource} byte size differs`);
+ signal.throwIfAborted();
+ const ffprobePath = options.ffprobePath ?? "ffprobe";
+ const timeoutMs = options.processTimeoutMs ?? 120_000;
+ const maxOutputBytes = options.maxProbeOutputBytes ?? 8 * 1024 * 1024;
+ const pending = [
+ runProcess({
+ executable: ffprobePath,
+ argv: ["-v", "error", "-print_format", "json", "-show_streams", "-count_frames", options.path],
+ timeoutMs,
+ maxOutputBytes, signal,
+ }).then(result => result.stdout),
+ pixelFormatAlpha(ffprobePath, timeoutMs, maxOutputBytes, signal),
+ ] as const;
+ await Promise.allSettled(pending.map(async (job) => {
+ try { return await job; } catch (error) { controller.abort(error); throw error; }
+ }));
+ signal.throwIfAborted();
+ const [probe, formats] = await Promise.all(pending);
+ const root = json(probe, "ffprobe Surface query");
+ assert(Array.isArray(root.streams) && root.streams.length === 1,
+ "Surface must contain exactly one visual stream and no audio or auxiliary streams");
+ const stream = root.streams[0] as ProbeStream;
+ assert(stream.codec_type === "video", "Surface stream is not visual");
+ assert(stream.disposition?.attached_pic !== 1, "Surface cannot be an attached-picture stream");
+ const width = positiveInteger(stream.width, "Surface width");
+ const height = positiveInteger(stream.height, "Surface height");
+ assert(width === options.surface.width && height === options.surface.height,
+ "Surface decoded dimensions differ from its declaration");
+ assert(stream.sample_aspect_ratio === undefined || stream.sample_aspect_ratio === "1:1",
+ "Surface must use square pixels");
+ assert(rotation(stream) === 0, "Surface must not depend on display rotation metadata");
+ assert(stream.field_order === undefined || stream.field_order === "progressive" || stream.field_order === "unknown",
+ "Surface must be progressive");
+ assertSrgb(stream);
+
+ assert(typeof stream.pix_fmt === "string" && stream.pix_fmt.length > 0,
+ "Surface pixel format is absent");
+ const pixelAlpha = formats.get(stream.pix_fmt);
+ assert(pixelAlpha !== undefined, `Surface pixel format ${stream.pix_fmt} is unknown to ffprobe`);
+ const taggedAlpha = stream.tags?.alpha_mode === "1" || stream.tags?.alpha_mode === "straight";
+ const hasAlpha = pixelAlpha || taggedAlpha;
+ if (options.surface.alphaMode === "straight") {
+ assert(hasAlpha, "Surface declares straight alpha but its bytes carry no alpha channel");
+ } else {
+ assert(!hasAlpha, "Surface declares opaque pixels but its encoded format carries alpha");
+ }
+
+ const frameCount = positiveInteger(stream.nb_read_frames ?? stream.nb_frames, "Surface frame count");
+ if (options.surface.timing.kind === "still") {
+ assert(frameCount === 1, "Still Surface must decode to exactly one frame");
+ } else {
+ assert(frameCount === options.surface.timing.frameCount,
+ "Surface decoded frame count differs from its declaration");
+ const rate = rational(stream.avg_frame_rate ?? stream.r_frame_rate, "Surface frame rate");
+ assert(sameRational(rate, options.surface.timing.frameRate),
+ "Surface decoded frame rate differs from its declaration");
+ }
+}
diff --git a/packages/provider-hyperframes-local/src/weighted-capacity.ts b/packages/provider-html-local/src/weighted-capacity.ts
similarity index 100%
rename from packages/provider-hyperframes-local/src/weighted-capacity.ts
rename to packages/provider-html-local/src/weighted-capacity.ts
diff --git a/packages/provider-hyperframes-local/test/alpha.test.ts b/packages/provider-html-local/test/alpha.test.ts
similarity index 91%
rename from packages/provider-hyperframes-local/test/alpha.test.ts
rename to packages/provider-html-local/test/alpha.test.ts
index c857a65b..56768363 100644
--- a/packages/provider-hyperframes-local/test/alpha.test.ts
+++ b/packages/provider-html-local/test/alpha.test.ts
@@ -4,7 +4,7 @@ import { mkdir, mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { sealComposition } from "@hypit/composition";
-import { compileHyperframesDocument } from "@hypit/hyperframes";
+import { compileHtmlProgram } from "@hypit/html-program";
import { sealTimeline } from "@hypit/timeline";
import { appendVisualClip, appendTimedMediaLayer, createMediaLayerSet, createVisualTrackSet,
finalizeVisualTrack, projectVisualTrack, sealVisualClipSpec, sealMediaSampleLayerSpec,
@@ -12,7 +12,7 @@ import { appendVisualClip, appendTimedMediaLayer, createMediaLayerSet, createVis
import { projectProgramWindow } from "../../../test/temporal-fixture.js";
import { MemoryResourceStore, ffmpegBytes, normalizeTestVideo, transparentVideoFixture, writeTestArtifact } from "../../../test/alpha-video-fixture.js";
import sharp from "sharp";
-import { renderHyperframesVisual, renderHyperframesFrames } from "../src/index.js";
+import { rasterizeHtmlProgram, rasterizeHtmlFrames } from "../src/index.js";
test("transparent normalized media composites through an explicit Visual Clip in Chrome", {
skip: process.env.HYPIT_BROWSER_TESTS !== "1",
@@ -52,9 +52,9 @@ test("transparent normalized media composites through an explicit Visual Clip in
projection: { start: { ref: "timeline.start" }, end: { ref: "timeline.end" } } }));
const speechVisual = projectVisualTrack(space, finalizeVisualTrack(speechSet, speechHeader, space));
const brollVisual = projectVisualTrack(space, finalizeVisualTrack(items, header, space));
- const document = compileHyperframesDocument(sealComposition({ id: "alpha-proof",
+ const document = compileHtmlProgram(sealComposition({ id: "alpha-proof",
canvas: { width: 192, height: 64, clearColor: "#143cdc" }, tracks: [speechVisual, brollVisual] }), space);
- const rendered = await renderHyperframesVisual({ document }, { resources, workers: 2, quality: "high", processTimeoutMs: 120_000 });
+ const rendered = await rasterizeHtmlProgram({ program: document }, { resources, workers: 2, quality: "high", processTimeoutMs: 120_000 });
const video = await writeTestArtifact(resources, rendered.artifact, join(directory, "speech-and-broll.mp4"));
const pixels = ffmpegBytes(["-i", video, "-pix_fmt", "rgb24", "-f", "rawvideo", "pipe:1"]);
assert.equal(pixels.length, 192 * 64 * 3 * 12);
@@ -67,7 +67,7 @@ test("transparent normalized media composites through an explicit Visual Clip in
close(pixel(f, left + 32, 32), [240, 20, 20]);
close(pixel(f, left + 60, 32), [130, 40, 120]);
}
- const snapshots = await renderHyperframesFrames({ document, frames: [0, 11] }, { resources, workers: 2 });
+ const snapshots = await rasterizeHtmlFrames({ program: document, frames: [0, 11] }, { resources, workers: 2 });
for (const snapshot of snapshots) {
const pixels = await sharp((await resources.get(snapshot.resource))!).removeAlpha().raw().toBuffer();
const at = (x: number, y: number) => [...pixels.subarray((y * 192 + x) * 3, (y * 192 + x) * 3 + 3)];
diff --git a/packages/provider-hyperframes-local/test/browser-download.test.ts b/packages/provider-html-local/test/browser-download.test.ts
similarity index 94%
rename from packages/provider-hyperframes-local/test/browser-download.test.ts
rename to packages/provider-html-local/test/browser-download.test.ts
index 8fce201e..85411287 100644
--- a/packages/provider-hyperframes-local/test/browser-download.test.ts
+++ b/packages/provider-html-local/test/browser-download.test.ts
@@ -9,9 +9,9 @@ import { chmod, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises
import { tmpdir } from "node:os";
import { dirname, join, relative } from "node:path";
import { canonicalize } from "@hypit/protocol";
-import type { RuntimeEndpointAdapterImplementation } from "@hypit/runtime-kit";
+import type { RuntimeEndpointAdapterImplementation } from "@hypit/runtime-local/extension";
import { hypitPackage } from "../src/activation.js";
-import { browserDownloadBaseUrl, browserDownloadUrl, browserExecutablePath, installRenderBrowser, recommendedBrowserVersion, requireBrowserExecutable } from "../src/browser.js";
+import { browserDownloadBaseUrl, browserDownloadUrl, browserExecutablePath, installHtmlBrowser, recommendedBrowserVersion, requireBrowserExecutable } from "../src/browser.js";
test("download source accepts an archive base and rejects ignored or malformed configuration", () => {
assert.equal(browserDownloadBaseUrl({ browserDownloadBaseUrl: "https://mirror.example/chrome///" }), "https://mirror.example/chrome");
@@ -49,7 +49,7 @@ test("Profile mirror reaches the real preparation command and installs its archi
t.after(() => new Promise<void>((resolve, reject) => server.close(error => error ? reject(error) : resolve())));
const address = server.address() as import("node:net").AddressInfo;
const baseUrl = `http://127.0.0.1:${address.port}/chrome`;
- const adapter = hypitPackage.hostFacets[0]!.implementation as RuntimeEndpointAdapterImplementation;
+ const adapter = hypitPackage.facets[0]!.implementation as RuntimeEndpointAdapterImplementation;
const activation = await adapter.activate({
hostStateRoot: directory, dataRoot: directory, instance: "render", pool: "machine",
config: canonicalize({ browserCacheDirectory: "cache", browserDownloadBaseUrl: `${baseUrl}/` }),
@@ -96,7 +96,7 @@ test("failed mirror download or unpack never requests the official source", asyn
syncBuiltinESMExports();
t.after(() => { t.mock.restoreAll(); syncBuiltinESMExports(); });
for (status of [503, 200]) {
- await assert.rejects(installRenderBrowser(join(directory, String(status)), recommendedBrowserVersion, baseUrl), error => {
+ await assert.rejects(installHtmlBrowser(join(directory, String(status)), recommendedBrowserVersion, baseUrl), error => {
assert.ok(error instanceof Error);
assert.ok(error.message.includes(baseUrl));
assert.ok(error.message.includes(recommendedBrowserVersion));
diff --git a/packages/provider-hyperframes-local/test/browser.test.ts b/packages/provider-html-local/test/browser.test.ts
similarity index 75%
rename from packages/provider-hyperframes-local/test/browser.test.ts
rename to packages/provider-html-local/test/browser.test.ts
index dc463e44..f20319f5 100644
--- a/packages/provider-hyperframes-local/test/browser.test.ts
+++ b/packages/provider-html-local/test/browser.test.ts
@@ -4,40 +4,40 @@ import { chmod, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from "node:fs
import { tmpdir } from "node:os";
import { dirname, join } from "node:path";
import { browserExecutablePath, recommendedBrowserVersion } from "../src/browser.js";
-import { localHyperframesBrowserProgram } from "../src/program.js";
+import { localHtmlBrowserProgram } from "../src/program.js";
import { resolveExecutionOptions } from "../src/render.js";
-test("browser inspection is read-only and ignores unrelated installed browsers", async (t) => {
+test("browser inspection is read-only and ignores environment browser hints", async (t) => {
const directory = await mkdtemp(join(tmpdir(), "hypit-browser-"));
- const saved = [process.env.HYPERFRAMES_BROWSER_PATH, process.env.PRODUCER_HEADLESS_SHELL_PATH];
- delete process.env.HYPERFRAMES_BROWSER_PATH;
- delete process.env.PRODUCER_HEADLESS_SHELL_PATH;
+ const saved = [process.env.CHROME_PATH, process.env.BROWSER];
+ delete process.env.CHROME_PATH;
+ delete process.env.BROWSER;
t.after(async () => {
- for (const [index, key] of ["HYPERFRAMES_BROWSER_PATH", "PRODUCER_HEADLESS_SHELL_PATH"].entries()) {
+ for (const [index, key] of ["CHROME_PATH", "BROWSER"].entries()) {
if (saved[index] === undefined) delete process.env[key]; else process.env[key] = saved[index];
}
await rm(directory, { recursive: true, force: true });
});
const options = { browserCacheDirectory: directory };
- const program = localHyperframesBrowserProgram({ ...options, id: "render", nodePath: process.execPath, ffprobePath: "ffprobe" });
+ const program = localHtmlBrowserProgram({ ...options, id: "render", nodePath: process.execPath, ffprobePath: "ffprobe" });
const state = await program.probe();
assert.equal(state.state, "down");
assert.ok(state.detail.includes(browserExecutablePath(options)));
assert.match(state.detail, /runtime up/u);
assert.deepEqual(await readdir(directory), [], "diagnosis must not prepare or download anything");
- const otherProject = localHyperframesBrowserProgram({ ...options, id: "other-render", nodePath: process.execPath, ffprobePath: "ffprobe" });
+ const otherProject = localHtmlBrowserProgram({ ...options, id: "other-render", nodePath: process.execPath, ffprobePath: "ffprobe" });
assert.equal(otherProject.stateRoot, program.stateRoot, "shared browser installation uses the existing shared Program lifecycle");
assert.equal(resolveExecutionOptions(options).browserCacheDirectory, directory);
// Two different overrides previously selected different binaries in the CLI and engine.
- process.env.HYPERFRAMES_BROWSER_PATH = process.execPath;
- process.env.PRODUCER_HEADLESS_SHELL_PATH = join(directory, "wrong-env-browser");
+ process.env.CHROME_PATH = process.execPath;
+ process.env.BROWSER = join(directory, "wrong-env-browser");
assert.equal(resolveExecutionOptions(options).chromePath, undefined);
assert.equal(resolveExecutionOptions(options).browserVersion, recommendedBrowserVersion);
assert.notEqual(browserExecutablePath(options), process.execPath);
assert.equal((await program.probe()).state, "down", "system/environment browsers do not satisfy this selection");
const invalid = { ...options, chromePath: join(directory, "missing-explicit-browser") };
- const configured = localHyperframesBrowserProgram({ ...invalid, id: "render", nodePath: process.execPath, ffprobePath: "ffprobe" });
+ const configured = localHtmlBrowserProgram({ ...invalid, id: "render", nodePath: process.execPath, ffprobePath: "ffprobe" });
assert.equal(configured.installation, undefined, "explicit paths must never cause a managed replacement download");
assert.equal((await configured.probe()).state, "down");
assert.equal(resolveExecutionOptions(invalid).chromePath, invalid.chromePath);
@@ -50,7 +50,7 @@ test("browser selection rejects ambiguous choices and floating versions", () =>
assert.throws(() => browserExecutablePath({ browserVersion: "latest" }), /exact four-part/u);
assert.throws(() => browserExecutablePath({ chromePath: "" }), /must not be empty/u);
const chosen = { browserVersion: "151.0.7922.71", browserCacheDirectory: join(tmpdir(), "explicit-browser-cache") };
- const program = localHyperframesBrowserProgram({ ...chosen, id: "render", nodePath: process.execPath, ffprobePath: "ffprobe" });
+ const program = localHtmlBrowserProgram({ ...chosen, id: "render", nodePath: process.execPath, ffprobePath: "ffprobe" });
assert.equal(program.installation!.commands[0]!.args.at(-1), chosen.browserVersion);
assert.equal(program.installation!.commands[0]!.args.at(-2), chosen.browserCacheDirectory);
assert.ok(program.installation!.commands[0]!.label!.includes(browserExecutablePath(chosen)));
@@ -66,7 +66,7 @@ test("a wrong-version managed executable cannot satisfy readiness or trigger a d
await mkdir(dirname(path), { recursive: true });
await writeFile(path, `#!${process.execPath}\nconsole.log('Chrome Headless Shell 999.0.0.0');\n`);
await chmod(path, 0o755);
- const program = localHyperframesBrowserProgram({ ...options, id: "render", nodePath: process.execPath, ffprobePath: "ffprobe" });
+ const program = localHtmlBrowserProgram({ ...options, id: "render", nodePath: process.execPath, ffprobePath: "ffprobe" });
const state = await program.probe();
assert.equal(state.state, "down");
assert.match(state.detail, /Expected Chrome Headless Shell 151\.0\.7922\.71/u);
diff --git a/packages/provider-hyperframes-local/test/capture-process.test.ts b/packages/provider-html-local/test/capture-process.test.ts
similarity index 75%
rename from packages/provider-hyperframes-local/test/capture-process.test.ts
rename to packages/provider-html-local/test/capture-process.test.ts
index e3f330f9..d68966f9 100644
--- a/packages/provider-hyperframes-local/test/capture-process.test.ts
+++ b/packages/provider-html-local/test/capture-process.test.ts
@@ -29,30 +29,28 @@ function assertStopped(pid: number): void {
}
-test("abrupt engine exit closes its actual Chrome without disturbing another browser", {
+test("abrupt rasterizer exit closes its actual Chrome without disturbing another browser", {
skip: process.env.HYPIT_BROWSER_TESTS !== "1",
}, async () => {
const { default: puppeteer } = await import("puppeteer-core");
- const chromePath = browserExecutablePath({});
+ const chromePath = process.env.HYPIT_TEST_CHROME_PATH ?? browserExecutablePath({});
const other = await puppeteer.launch({ executablePath: chromePath, headless: true, args: ["--no-sandbox"] });
const root = await mkdtemp(join(tmpdir(), "hypit-abrupt-chrome-"));
const pidFile = join(root, "browser");
let browserPid: number | undefined;
try {
- const engine = join(root, "engine.mjs");
- await writeFile(engine, `import { acquireBrowser } from ${JSON.stringify(import.meta.resolve("@hyperframes/engine"))};
+ const worker = join(root, "worker.mjs");
+ await writeFile(worker, `import puppeteer from ${JSON.stringify(import.meta.resolve("puppeteer-core"))};
import { writeFileSync } from 'node:fs';
-const { browser } = await acquireBrowser(['--no-sandbox'], {
- chromePath: ${JSON.stringify(chromePath)}, forceScreenshot: true, enableBrowserPool: false,
-});
+const browser = await puppeteer.launch({ executablePath: ${JSON.stringify(chromePath)}, headless: true, args: ['--no-sandbox'] });
await browser.newPage();
writeFileSync(${JSON.stringify(pidFile)}, String(browser.process().pid));
process.exit(7);`);
await assert.rejects(runCaptureProcess({
document: { frameRate: { numerator: 30, denominator: 1 } },
range: { startFrame: 0, endFrameExclusive: 1 }, config: resolveExecutionOptions({}),
- directory: root, engineModule: pathToFileURL(engine).href,
- } as CaptureInput, new AbortController().signal, () => {}), /exited before completion/u);
+ directory: root,
+ } as unknown as CaptureInput, new AbortController().signal, () => {}, pathToFileURL(worker)), /exited before completion/u);
browserPid = Number(await readFile(pidFile, "utf8"));
assertStopped(browserPid);
const page = await other.newPage();
@@ -82,7 +80,7 @@ process.once('message', () => {
process.send({ type: 'progress', event: { phase: 'worker-start', browserPid: child.pid } },
() => process.kill(process.pid, 'SIGKILL'));
});`);
- await assert.rejects(runCaptureProcess({ config: resolveExecutionOptions({}) } as CaptureInput,
+ await assert.rejects(runCaptureProcess({ config: resolveExecutionOptions({}) } as unknown as CaptureInput,
new AbortController().signal, event => {
if ("browserPid" in event) descendant = event.browserPid;
}, pathToFileURL(entry), async event => { diagnostics.push(event.message); }), /SIGKILL/u);
@@ -102,11 +100,11 @@ for (const scenario of ["exit-zero", "exit-error", "uncaught", "SIGTERM"] as con
const pidFile = join(root, "descendant");
let descendant: number | undefined;
try {
- const engine = join(root, "engine.mjs");
- const end = scenario === "uncaught" ? "setImmediate(() => { throw new Error('unexpected engine crash'); }); await new Promise(() => {});"
+ const worker = join(root, "worker.mjs");
+ const end = scenario === "uncaught" ? "setImmediate(() => { throw new Error('unexpected rasterizer crash'); }); await new Promise(() => {});"
: scenario === "SIGTERM" ? "process.kill(process.pid, 'SIGTERM'); await new Promise(() => {});"
: `process.exit(${scenario === "exit-zero" ? 0 : 7});`;
- await writeFile(engine, `import { spawn } from 'node:child_process';
+ await writeFile(worker, `import { spawn } from 'node:child_process';
import { writeFileSync } from 'node:fs';
const child = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], { detached: true, stdio: 'ignore' });
child.unref();
@@ -115,8 +113,8 @@ ${end}`);
await assert.rejects(runCaptureProcess({
document: { frameRate: { numerator: 30, denominator: 1 } },
range: { startFrame: 0, endFrameExclusive: 1 }, config: resolveExecutionOptions({}),
- directory: root, engineModule: pathToFileURL(engine).href,
- } as CaptureInput, new AbortController().signal, () => {}), /exited before completion/u);
+ directory: root,
+ } as unknown as CaptureInput, new AbortController().signal, () => {}, pathToFileURL(worker)), /exited before completion/u);
descendant = Number(await readFile(pidFile, "utf8"));
assertStopped(descendant);
} finally {
@@ -132,19 +130,20 @@ test("a capture failure still terminates a detached process left by failed resou
const root = await mkdtemp(join(tmpdir(), "hypit-worker-failed-cleanup-"));
let descendant: number | undefined;
try {
- const engine = join(root, "engine.mjs");
+ const worker = join(root, "worker.mjs");
const pidFile = join(root, "descendant");
- await writeFile(engine, `import { spawn } from 'node:child_process';
+ await writeFile(worker, `import { spawn } from 'node:child_process';
import { writeFileSync } from 'node:fs';
const child = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], { detached: true, stdio: 'ignore' });
child.unref();
writeFileSync(${JSON.stringify(pidFile)}, String(child.pid));
-throw new Error('engine initialization failed after starting a child');`);
+throw new Error('rasterizer initialization failed after starting a child');`);
await assert.rejects(runCaptureProcess({
document: { frameRate: { numerator: 30, denominator: 1 } },
range: { startFrame: 0, endFrameExclusive: 1 }, config: resolveExecutionOptions({}),
- directory: root, engineModule: pathToFileURL(engine).href,
- } as CaptureInput, new AbortController().signal, () => {}), /engine initialization failed/);
+ directory: root,
+ } as unknown as CaptureInput, new AbortController().signal, () => {}, pathToFileURL(worker)),
+ /rasterizer initialization failed/);
descendant = Number(await readFile(pidFile, "utf8"));
assertStopped(descendant);
} finally {
@@ -165,7 +164,7 @@ process.once('message', () => {
releaseCaptureExitCleanup();
process.send({ type: 'completed' }, () => setTimeout(() => process.disconnect(), 100));
});`);
- await runCaptureProcess({ config: resolveExecutionOptions({}) } as CaptureInput,
+ await runCaptureProcess({ config: resolveExecutionOptions({}) } as unknown as CaptureInput,
new AbortController().signal, () => {}, pathToFileURL(entry));
assert.equal(await readFile(marker, "utf8"), "natural exit");
} finally { await rm(root, { recursive: true, force: true }); }
@@ -184,7 +183,7 @@ process.once('message', () => {
});
setInterval(() => {}, 1000);
`);
- await assert.rejects(runCaptureProcess({ config: resolveExecutionOptions({}) } as CaptureInput,
+ await assert.rejects(runCaptureProcess({ config: resolveExecutionOptions({}) } as unknown as CaptureInput,
controller.signal, (event) => {
if ("browserPid" in event) descendant = event.browserPid;
controller.abort(new Error("render deadline"));
@@ -197,55 +196,9 @@ setInterval(() => {}, 1000);
}
});
-test("a capture process resolves Distribution packages without workspace links", async () => {
- // A packed Distribution ships its package sources with no node_modules link between them,
- // and the launcher's resolver hooks are process-local. Starting this entry outside the
- // checkout reproduces exactly that: nothing above it declares @hypit/hyperframes.
- const root = await mkdtemp(join(tmpdir(), "hypit-capture-resolution-"));
- const tsx = import.meta.resolve("tsx");
- const bootstrap = new URL("../src/capture-bootstrap.ts", import.meta.url).href;
- try {
- const probe = join(root, "probe.mjs");
- await writeFile(probe, `const module = await import("@hypit/hyperframes/project");
-process.stdout.write("resolved:" + Object.keys(module).join(",") + "\\n");`);
-
- // Control: the preload is the only difference between the two arms below.
- const unresolved = spawnSync(process.execPath, ["--import", tsx, probe], { encoding: "utf8", timeout: 120_000 });
- assert.notEqual(unresolved.status, 0);
- assert.match(unresolved.stderr, /ERR_MODULE_NOT_FOUND/u);
-
- const resolved = spawnSync(process.execPath, ["--import", tsx, "--import", bootstrap, probe],
- { encoding: "utf8", timeout: 120_000 });
- assert.equal(resolved.status, 0, resolved.stderr);
- assert.match(resolved.stdout, /stageHyperframesProject/u);
-
- const stale = spawnSync(process.execPath, ["--import", tsx, "--import", bootstrap, probe], {
- encoding: "utf8", timeout: 120_000,
- env: { ...process.env, HYPIT_DISTRIBUTION_ROOT: join(root, "old-installation") },
- });
- assert.equal(stale.status, 0, stale.stderr);
- assert.match(stale.stdout, /stageHyperframesProject/u);
-
- // The render entry point must actually pass that preload to its child.
- const worker = join(root, "worker.mjs");
- await writeFile(worker, `import { releaseCaptureExitCleanup } from ${JSON.stringify(exitCleanup)};
-process.once("message", async () => {
- const module = await import("@hypit/hyperframes/project");
- process.stdout.write("resolved:" + Object.keys(module).join(",") + "\\n");
- releaseCaptureExitCleanup();
- process.send({ type: "completed" }, () => process.disconnect());
- });`);
- const diagnostics: string[] = [];
- await runCaptureProcess({ config: resolveExecutionOptions({}) } as CaptureInput,
- new AbortController().signal, () => {}, pathToFileURL(worker),
- async (message) => { diagnostics.push(message.message); });
- assert.ok(diagnostics.some((message) => message.startsWith("resolved:")), diagnostics.join("\n"));
- } finally { await rm(root, { recursive: true, force: true }); }
-});
-
test("renderer stdout and stderr diagnostics are drained before reporting success", async () => {
const root = await mkdtemp(join(tmpdir(), "hypit-render-diagnostics-"));
- const messages: import("@hypit/runtime").ExecutionDiagnostic[] = [];
+ const messages: import("@hypit/hypit/endpoint").ExecutionDiagnostic[] = [];
try {
const entry = join(root, "report.mjs");
await writeFile(entry, `import { releaseCaptureExitCleanup } from ${JSON.stringify(exitCleanup)};
@@ -255,7 +208,7 @@ process.once('message', () => {
releaseCaptureExitCleanup();
process.send({ type: 'completed' }, () => process.disconnect());
});`);
- await runCaptureProcess({ config: resolveExecutionOptions({}) } as CaptureInput,
+ await runCaptureProcess({ config: resolveExecutionOptions({}) } as unknown as CaptureInput,
new AbortController().signal, () => {}, pathToFileURL(entry), async (message) => {
await new Promise((resolve) => setTimeout(resolve, 5)); messages.push(message);
});
diff --git a/packages/provider-hyperframes-local/test/concurrency.test.ts b/packages/provider-html-local/test/concurrency.test.ts
similarity index 100%
rename from packages/provider-hyperframes-local/test/concurrency.test.ts
rename to packages/provider-html-local/test/concurrency.test.ts
diff --git a/packages/provider-hyperframes-local/test/frame-span-index.test.ts b/packages/provider-html-local/test/frame-span-index.test.ts
similarity index 100%
rename from packages/provider-hyperframes-local/test/frame-span-index.test.ts
rename to packages/provider-html-local/test/frame-span-index.test.ts
diff --git a/packages/provider-hyperframes-local/test/frames.test.ts b/packages/provider-html-local/test/frames.test.ts
similarity index 57%
rename from packages/provider-hyperframes-local/test/frames.test.ts
rename to packages/provider-html-local/test/frames.test.ts
index 5e70b3f4..b995107c 100644
--- a/packages/provider-hyperframes-local/test/frames.test.ts
+++ b/packages/provider-html-local/test/frames.test.ts
@@ -6,42 +6,43 @@ import { join } from "node:path";
import sharp from "sharp";
import { sealComposition, sealVisualTrack } from "@hypit/composition";
import { sealTimeline } from "@hypit/timeline";
-import { browserProgram, compileHyperframesDocument, hyperframesHtmlDomain } from "@hypit/hyperframes";
-import { stageHyperframesProject } from "@hypit/hyperframes/project";
-import { verifyHyperframesFramesRequest } from "@hypit/render-hyperframes";
-import { MemoryResourceStore } from "@hypit/driver-node";
-import { renderHyperframesFrames } from "../src/index.js";
+import { htmlVisual, compileHtmlProgram } from "@hypit/html-program";
+import { verifyHtmlFrameRequest } from "@hypit/html-program";
+import { MemoryResourceStore } from "@hypit/executor";
+import { rasterizeHtmlFrames } from "../src/index.js";
+
+const testBrowser = process.env.HYPIT_TEST_CHROME_PATH;
function fixture() {
const space = sealTimeline({ id: "space", frameCount: 12, frameRate: { numerator: 12, denominator: 1 } });
- return compileHyperframesDocument(sealComposition({ id: "frames", canvas: { width: 96, height: 64, clearColor: "#000000" },
+ return compileHtmlProgram(sealComposition({ id: "frames", canvas: { width: 96, height: 64, clearColor: "#000000" },
tracks: [sealVisualTrack({ id: "motion", timelineId: space.id, visualIr: "hypit.visual-ir@1", presents: [{ id: "reveal",
order: 0, z: 0, span: { startFrame: 3, endFrameExclusive: 12 }, elements: [{ id: "program", order: 0,
kind: "program", style: [{ name: "position", value: "absolute" }, { name: "inset", value: 0 }],
- program: browserProgram({ html: '<div class="box"></div>', css: '.box{position:absolute;top:0;width:8px;height:64px;background:#ff0000}',
+ program: htmlVisual({ html: '<div class="box"></div>', css: '.box{position:absolute;top:0;width:8px;height:64px;background:#ff0000}',
setup: 'return frame => { root.querySelector(".box").style.left = `${frame * 8}px`; };' }),
}] }] })] }), space);
}
test("frame selection validates original-frame bounds and exact HTML clock", () => {
const document = fixture();
- verifyHyperframesFramesRequest({ document, frames: [0, 3, 11] });
- for (const frames of [[], [12], [3, 2], [1.5]]) assert.throws(() => verifyHyperframesFramesRequest({ document, frames }));
- assert.deepEqual(hyperframesHtmlDomain(document.html), { frameRate: document.frameRate, frameCount: 12, canvas: document.canvas });
+ verifyHtmlFrameRequest({ program: document, frames: [0, 3, 11] });
+ for (const frames of [[], [12], [3, 2], [1.5]]) assert.throws(() => verifyHtmlFrameRequest({ program: document, frames }));
+ assert.deepEqual({ frameRate: document.frameRate, frameCount: document.frameCount, canvas: document.canvas },
+ { frameRate: document.frameRate, frameCount: 12, canvas: document.canvas });
});
-test("snapshot captures original browser-program frames from document and staged HTML without video encoding", {
+test("snapshot captures original html-visual frames without video encoding", {
skip: process.env.HYPIT_BROWSER_TESTS !== "1",
}, async () => {
const resources = new MemoryResourceStore();
const document = fixture();
const directory = await mkdtemp(join(tmpdir(), "hypit-frames-proof-"));
try {
- await stageHyperframesProject({ document, directory, read: async artifact => (await resources.get(artifact.resource))! });
- const html = await readFile(join(directory, "index.html"), "utf8");
- for (const input of [{ document }, { project: { html, assets: [] } }]) {
+ for (const input of [{ program: document }]) {
const phases: string[] = [];
- const images = await renderHyperframesFrames({ ...input, frames: [0, 3, 4, 11] }, { resources, workers: 2,
+ const images = await rasterizeHtmlFrames({ ...input, frames: [0, 3, 4, 11] }, { resources, workers: 2,
+ ...(testBrowser === undefined ? {} : { chromePath: testBrowser }),
onProgress: event => { phases.push(event.phase); } });
assert.equal(images.length, 4);
assert.ok(!phases.includes("encoding"));
@@ -53,6 +54,7 @@ test("snapshot captures original browser-program frames from document and staged
if (expectedX > 0) assert.deepEqual(pixel(0), [0, 0, 0]);
}
}
- await assert.rejects(renderHyperframesFrames({ document, frames: [3] }, { resources, workers: 1, maxRenderedBytes: 1 }), /PNG output exceeds/u);
+ await assert.rejects(rasterizeHtmlFrames({ program: document, frames: [3] }, { resources, workers: 1, maxRenderedBytes: 1,
+ ...(testBrowser === undefined ? {} : { chromePath: testBrowser }) }), /PNG output exceeds/u);
} finally { await rm(directory, { recursive: true, force: true }); }
});
diff --git a/packages/provider-hyperframes-local/test/ordered-frame-sink.test.ts b/packages/provider-html-local/test/ordered-frame-sink.test.ts
similarity index 100%
rename from packages/provider-hyperframes-local/test/ordered-frame-sink.test.ts
rename to packages/provider-html-local/test/ordered-frame-sink.test.ts
diff --git a/packages/provider-hyperframes-local/test/process-env.test.ts b/packages/provider-html-local/test/process-env.test.ts
similarity index 70%
rename from packages/provider-hyperframes-local/test/process-env.test.ts
rename to packages/provider-html-local/test/process-env.test.ts
index d5ce4208..68b61a98 100644
--- a/packages/provider-hyperframes-local/test/process-env.test.ts
+++ b/packages/provider-html-local/test/process-env.test.ts
@@ -3,37 +3,37 @@ import test from "node:test";
import { openProcessInput, processEnvironment, runProcess } from "../src/process.js";
-test("Windows HyperFrames children receive TEMP and process-creation variables, not Host secrets", () => {
- const previous = process.env.HYPIT_HF_ENV_PROBE;
+test("Windows HTML rasterizer children receive TEMP and process-creation variables, not Host secrets", () => {
+ const previous = process.env.HYPIT_PRIVATE_ENV_PROBE;
const previousTemp = process.env.TEMP;
- process.env.HYPIT_HF_ENV_PROBE = "secret";
+ process.env.HYPIT_PRIVATE_ENV_PROBE = "secret";
process.env.TEMP = "C:\\Windows\\Temp";
try {
const env = processEnvironment("win32");
assert.equal(env.PATH, process.env.PATH);
assert.equal(env.TEMP, "C:\\Windows\\Temp");
- assert.equal(env.HYPIT_HF_ENV_PROBE, undefined);
+ assert.equal(env.HYPIT_PRIVATE_ENV_PROBE, undefined);
assert.equal(env.HOME, undefined);
assert.equal(env.TMPDIR, undefined);
} finally {
- if (previous === undefined) delete process.env.HYPIT_HF_ENV_PROBE;
- else process.env.HYPIT_HF_ENV_PROBE = previous;
+ if (previous === undefined) delete process.env.HYPIT_PRIVATE_ENV_PROBE;
+ else process.env.HYPIT_PRIVATE_ENV_PROBE = previous;
if (previousTemp === undefined) delete process.env.TEMP;
else process.env.TEMP = previousTemp;
}
});
-test("POSIX HyperFrames children receive TMPDIR without Host secrets", async () => {
- const previous = process.env.HYPIT_HF_ENV_PROBE;
- process.env.HYPIT_HF_ENV_PROBE = "secret";
+test("POSIX HTML rasterizer children receive TMPDIR without Host secrets", async () => {
+ const previous = process.env.HYPIT_PRIVATE_ENV_PROBE;
+ process.env.HYPIT_PRIVATE_ENV_PROBE = "secret";
try {
const env = processEnvironment("darwin");
- assert.equal(env.HYPIT_HF_ENV_PROBE, undefined);
+ assert.equal(env.HYPIT_PRIVATE_ENV_PROBE, undefined);
assert.equal(env.PATH, process.env.PATH);
assert.equal(env.TMPDIR, process.env.TMPDIR);
const { stdout } = await runProcess({
executable: process.execPath,
- argv: ["-e", "process.stdout.write(JSON.stringify({ probe: process.env.HYPIT_HF_ENV_PROBE, path: Boolean(process.env.PATH) }))"],
+ argv: ["-e", "process.stdout.write(JSON.stringify({ probe: process.env.HYPIT_PRIVATE_ENV_PROBE, path: Boolean(process.env.PATH) }))"],
timeoutMs: 5_000,
maxOutputBytes: 4_096,
});
@@ -41,8 +41,8 @@ test("POSIX HyperFrames children receive TMPDIR without Host secrets", async ()
assert.equal(body.probe, undefined);
assert.equal(body.path, true);
} finally {
- if (previous === undefined) delete process.env.HYPIT_HF_ENV_PROBE;
- else process.env.HYPIT_HF_ENV_PROBE = previous;
+ if (previous === undefined) delete process.env.HYPIT_PRIVATE_ENV_PROBE;
+ else process.env.HYPIT_PRIVATE_ENV_PROBE = previous;
}
});
diff --git a/packages/provider-hyperframes-local/test/progress.test.ts b/packages/provider-html-local/test/progress.test.ts
similarity index 91%
rename from packages/provider-hyperframes-local/test/progress.test.ts
rename to packages/provider-html-local/test/progress.test.ts
index 60aec738..bf376b33 100644
--- a/packages/provider-hyperframes-local/test/progress.test.ts
+++ b/packages/provider-html-local/test/progress.test.ts
@@ -1,6 +1,6 @@
import assert from "node:assert/strict";
import test from "node:test";
-import type { OperationProgress } from "@hypit/endpoint-kit";
+import type { OperationProgress } from "@hypit/endpoint";
import { renderProgressReporter } from "../src/progress.js";
test("parallel render progress sums frames and does not regress when another browser starts", async () => {
@@ -23,7 +23,7 @@ test("parallel render progress sums frames and does not regress when another bro
await reporter.flush();
assert.deepEqual(reports.map((p) => [p.phase, p.completed]), [
["preparing resources", undefined], ["decoding source frames", 0],
- ["rendering frames", 0], ["rendering frames", 7], ["rendering frames", 20],
+ ["rasterizing frames", 0], ["rasterizing frames", 7], ["rasterizing frames", 20],
["encoding video", undefined], ["storing output", undefined],
]);
});
diff --git a/packages/provider-hyperframes-local/test/provider.test.ts b/packages/provider-html-local/test/provider.test.ts
similarity index 66%
rename from packages/provider-hyperframes-local/test/provider.test.ts
rename to packages/provider-html-local/test/provider.test.ts
index 873e2a33..4b41d466 100644
--- a/packages/provider-hyperframes-local/test/provider.test.ts
+++ b/packages/provider-html-local/test/provider.test.ts
@@ -3,21 +3,21 @@ import { mkdtemp, readdir, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import test from "node:test";
-import { mediaTypes, verifyRenderedVisual } from "@hypit/media";
-import type { CompositableSurfaceRef, RenderedVisual } from "@hypit/media";
+import { mediaTypes, verifyTimelineVisual } from "@hypit/media";
+import type { CompositableSurfaceRef, TimelineVisual } from "@hypit/media";
import { sealTimeline } from "@hypit/timeline";
import { sealComposition, sealVisualTrack } from "@hypit/composition";
import assert from "node:assert/strict";
-import { MemoryResourceStore, EndpointRegistry } from "@hypit/driver-node";
-import type { EndpointRegistration } from "@hypit/driver-node";
-import type { ImmediateEndpointHandler } from "@hypit/endpoint-kit";
-import { compileHyperframesDocument } from "@hypit/hyperframes";
-import { renderHyperframesCapabilities, renderHyperframesTypes, hyperframesVisualRequest } from "@hypit/render-hyperframes";
+import { MemoryResourceStore, EndpointRegistry } from "@hypit/executor";
+import type { EndpointRegistration } from "@hypit/executor";
+import type { ImmediateEndpointHandler } from "@hypit/endpoint";
+import { compileHtmlProgram } from "@hypit/html-program";
+import { htmlProgramCapabilities, htmlProgramTypes, htmlRasterRequest } from "@hypit/html-program";
import { canonicalize } from "@hypit/protocol";
import type { CanonicalValue, Need } from "@hypit/protocol";
-import { createLocalHyperframesProvider, renderHyperframesVisual } from "../src/index.js";
-import { localHyperframesBrowserProgram } from "../src/program.js";
+import { createLocalHtmlProvider, rasterizeHtmlProgram } from "../src/index.js";
+import { localHtmlBrowserProgram } from "../src/program.js";
import { browserExecutablePath } from "../src/browser.js";
const liveEnabled = process.env.HYPIT_BROWSER_TESTS === "1";
@@ -30,21 +30,21 @@ test("rendering with a missing selection fails without installing or substitutin
{ browserVersion: "0.0.0.1", browserCacheDirectory: directory },
{ chromePath: join(directory, "missing-browser") },
]) {
- await assert.rejects(renderHyperframesVisual({ document: documentFixture() }, {
+ await assert.rejects(rasterizeHtmlProgram({ program: documentFixture() }, {
...selection, resources: new MemoryResourceStore(),
- }), /Render browser is unavailable/u);
+ }), /HTML browser is unavailable/u);
assert.deepEqual(await readdir(directory), []);
}
} finally { await rm(directory, { recursive: true, force: true }); }
});
test("an explicit browser renders without installing a managed replacement", { skip: !liveEnabled || !hasFfprobe }, async () => {
- const chromePath = browserExecutablePath({});
- const program = localHyperframesBrowserProgram({ chromePath, id: "external", nodePath: process.execPath, ffprobePath: "ffprobe" });
+ const chromePath = process.env.HYPIT_TEST_CHROME_PATH ?? browserExecutablePath({});
+ const program = localHtmlBrowserProgram({ chromePath, id: "external", nodePath: process.execPath, ffprobePath: "ffprobe" });
assert.equal(program.installation, undefined);
assert.equal((await program.probe()).state, "ready");
const diagnostics: string[] = [];
- const visual = await renderHyperframesVisual({ document: documentFixture() }, {
+ const visual = await rasterizeHtmlProgram({ program: documentFixture() }, {
chromePath, resources: new MemoryResourceStore(), workers: 1,
onDiagnostic: async event => { diagnostics.push(event.message); },
});
@@ -90,21 +90,21 @@ function documentFixture(surface?: CompositableSurfaceRef) {
],
}],
});
- return compileHyperframesDocument(sealComposition({
- id: "local-hyperframes-provider-fixture",
+ return compileHtmlProgram(sealComposition({
+ id: "local-html-provider-fixture",
canvas: { width: 160, height: 96, clearColor: "#000000" },
tracks: [track],
}), timeline);
}
function requestNeed(document = documentFixture()): Need {
- const constraints = hyperframesVisualRequest(document);
+ const constraints = htmlRasterRequest(document);
return {
- id: "need:local-hyperframes-fixture",
- capability: renderHyperframesCapabilities.renderVisual,
- returns: mediaTypes.renderedVisual,
+ id: "need:local-html-fixture",
+ capability: htmlProgramCapabilities.rasterizeVisual,
+ returns: mediaTypes.timelineVisual,
constraints,
- result: "record:local-hyperframes-fixture",
+ result: "record:local-html-fixture",
};
}
@@ -113,10 +113,12 @@ async function handlerFor(request: Need): Promise<{
readonly registration: EndpointRegistration;
}> {
const registry = new EndpointRegistry();
- await createLocalHyperframesProvider({
+ await createLocalHtmlProvider({
workers: 2,
defaultConcurrency: 1,
processTimeoutMs: 120_000,
+ ...(process.env.HYPIT_TEST_CHROME_PATH === undefined
+ ? {} : { chromePath: process.env.HYPIT_TEST_CHROME_PATH }),
}).install(registry);
const resolution = registry.resolve(request);
assert.equal(resolution.status, "resolved");
@@ -124,32 +126,32 @@ async function handlerFor(request: Need): Promise<{
return { handler: resolution.registration.handler, registration: resolution.registration };
}
-test("local HyperFrames Provider exposes visual and frame capabilities and two separate concurrency levels", async () => {
- const provider = createLocalHyperframesProvider({ workers: 4, defaultConcurrency: 2 });
- assert.equal(provider.instance.id, "hyperframes.local");
+test("local HTML renderer Provider exposes visual and frame capabilities and two separate concurrency levels", async () => {
+ const provider = createLocalHtmlProvider({ workers: 4, defaultConcurrency: 2 });
+ assert.equal(provider.instance.id, "html.local");
assert.deepEqual(provider.offers, [{
- capability: renderHyperframesCapabilities.renderVisual,
- returns: mediaTypes.renderedVisual,
- endpoint: "hyperframes.local",
- }, { capability: renderHyperframesCapabilities.renderFrames, returns: renderHyperframesTypes.frames, endpoint: "hyperframes.local" }]);
+ capability: htmlProgramCapabilities.rasterizeVisual,
+ returns: mediaTypes.timelineVisual,
+ endpoint: "html.local",
+ }, { capability: htmlProgramCapabilities.rasterizeFrames, returns: htmlProgramTypes.frameImages, endpoint: "html.local" }]);
const resolved = await handlerFor(requestNeed());
assert.equal(resolved.registration.scheduling?.resources.find((item) =>
item.id.startsWith("pool:"))?.limit, 1,
- "Runtime request admission must remain separate from HyperFrames frame workers");
+ "Runtime request admission must remain separate from HTML renderer frame workers");
});
-test("the selected HyperFrames Provider owns one idempotent browser installation", () => {
- const program = localHyperframesBrowserProgram({
- id: "hyperframes",
+test("the selected HTML renderer Provider owns one idempotent browser installation", () => {
+ const program = localHtmlBrowserProgram({
+ id: "html.local",
nodePath: process.execPath,
ffprobePath: "ffprobe",
});
- assert.equal(program.id, "hyperframes");
+ assert.equal(program.id, "html.local");
assert.equal(program.start, undefined);
- assert.match(program.installation!.commands[0]!.args.at(-3)!, /browser-install\.ts$/u);
+ assert.match(program.installation!.commands[0]!.args.at(-3)!, /browser-install\.js$/u);
});
-test("local HyperFrames Provider really renders a silent frame-exact MP4 with parallel workers", {
+test("local HTML renderer Provider really renders a silent frame-exact MP4 with parallel workers", {
skip: !liveEnabled || !hasFfprobe,
}, async () => {
const resources = new MemoryResourceStore();
@@ -169,15 +171,15 @@ test("local HyperFrames Provider really renders a silent frame-exact MP4 with pa
const request = requestNeed(documentFixture(surface));
const { handler } = await handlerFor(request);
const output = await handler({
- command: { kind: "fulfill-need", id: "command:local-hyperframes-fixture", need: request },
+ command: { kind: "fulfill-need", id: "command:local-html-fixture", need: request },
need: request,
resources,
credentials: {},
});
assert.equal(output.value.kind, "inline");
const value: CanonicalValue = output.value.kind === "inline" ? output.value.value : canonicalize(null);
- verifyRenderedVisual(value);
- const visual = value as unknown as RenderedVisual;
+ verifyTimelineVisual(value);
+ const visual = value as unknown as TimelineVisual;
assert.equal(visual.frameCount, 12);
assert.deepEqual(visual.canvas, { width: 160, height: 96 });
assert.equal(await resources.has(visual.artifact.resource), true);
diff --git a/packages/provider-hyperframes-local/test/range.test.ts b/packages/provider-html-local/test/range.test.ts
similarity index 78%
rename from packages/provider-hyperframes-local/test/range.test.ts
rename to packages/provider-html-local/test/range.test.ts
index 1d966325..c89caa31 100644
--- a/packages/provider-hyperframes-local/test/range.test.ts
+++ b/packages/provider-html-local/test/range.test.ts
@@ -8,20 +8,20 @@ import { setTimeout as delay } from "node:timers/promises";
import type { ResourceIOOptions } from "@hypit/runtime";
import { sealComposition, sealVisualTrack } from "@hypit/composition";
import { mediaFrameRangeSamples } from "@hypit/media";
-import { EndpointRegistry, MemoryResourceStore } from "@hypit/driver-node";
-import { compileHyperframesDocument } from "@hypit/hyperframes";
+import { EndpointRegistry, MemoryResourceStore } from "@hypit/executor";
+import { compileHtmlProgram } from "@hypit/html-program";
import { sealTimeline } from "@hypit/timeline";
import type { BlobRef } from "@hypit/protocol";
import sharp from "sharp";
-import { renderHyperframesVisual, renderHyperframesFrames } from "../src/index.js";
+import { rasterizeHtmlProgram, rasterizeHtmlFrames } from "../src/index.js";
import { resolveExecutionOptions } from "../src/render.js";
import { hypitPackage } from "../src/activation.js";
-import type { RuntimeEndpointAdapterImplementation } from "@hypit/runtime-kit";
-import { endpointResourceClaims } from "@hypit/endpoint-kit";
-import { renderHyperframesCapabilities } from "@hypit/render-hyperframes";
+import type { RuntimeEndpointAdapterImplementation } from "@hypit/runtime-local/extension";
+import { endpointResourceClaims } from "@hypit/endpoint";
+import { htmlProgramCapabilities } from "@hypit/html-program";
import { mediaTypes } from "@hypit/media";
import { canonicalize } from "@hypit/protocol";
-import type { HyperframesRenderProgress } from "../src/index.js";
+import type { HtmlRasterProgress } from "../src/index.js";
import { distributeFrameRange, requestedFrameRanges, sourceFrameAt, sourceWindows, videoSlots } from "../src/sampling.js";
function documentFor(artifact: BlobRef) {
@@ -41,7 +41,7 @@ function documentFor(artifact: BlobRef) {
] },
}] }],
});
- return compileHyperframesDocument(sealComposition({ id: "range-video",
+ return compileHtmlProgram(sealComposition({ id: "range-video",
canvas: { width: 64, height: 64, clearColor: "#000000" }, tracks: [track] }), space);
}
@@ -57,7 +57,7 @@ test("a render deadline cancels resource preparation and awaits the reader's cle
const resources = new StalledResources();
const document = documentFor({ kind: "blob", resource: "res_waiting", size: 1, mediaType: "video/mp4" });
// This test stops during resource preparation, before any browser is launched.
- await assert.rejects(renderHyperframesVisual({ document }, { resources, chromePath: process.execPath, processTimeoutMs: 100 }),
+ await assert.rejects(rasterizeHtmlProgram({ program: document }, { resources, chromePath: process.execPath, processTimeoutMs: 100 }),
/render timed out during preparing resources/u);
assert.equal(resources.active, 0, "the failed render must not leave its reader running");
});
@@ -82,7 +82,7 @@ test("the render deadline is global while stage deadlines are explicit deploymen
test("source selection retains loop, hold and fractional-speed sampling and shares decoded frames", () => {
const document = documentFor({ kind: "blob", resource: "res_range_source", size: 1, mediaType: "video/mp4" });
- const slots = videoSlots(document.html);
+ const slots = videoSlots(document.frameSources, resource => `hypit-resource://${resource}`);
assert.ok(slots.every(slot => slot.src === "hypit-resource://res_range_source"));
assert.equal(slots.length, 4, "the two-frame hold remains one slot instead of one slot per target frame");
const hold = slots.find((slot) => slot.sourceRate.numerator === 0n);
@@ -105,21 +105,10 @@ test("source selection retains loop, hold and fractional-speed sampling and shar
]);
});
-test("video slot inspection accepts direct HTML sources without requiring compiler-owned activation", () => {
- const [slot] = videoSlots('<video id="direct" src="direct.mp4" data-hypit-start-frame="2" data-hypit-end-frame="4" data-hypit-source-frame="1/1" data-hypit-source-rate="1/1" data-hypit-source-fps="30/1"></video>');
- assert.deepEqual(slot, {
- id: "direct",
- src: "direct.mp4",
- startFrame: 2,
- endFrameExclusive: 4,
- sourceFrame: { numerator: 1n, denominator: 1n },
- sourceRate: { numerator: 1n, denominator: 1n },
- sourceFps: { num: 30, den: 1 },
- });
-});
-
test("reverse source time selects the same bounded decoded window without forward traversal", () => {
- const [slot] = videoSlots('<video id="reverse" src="direct.mp4" data-hypit-start-frame="0" data-hypit-end-frame="4" data-hypit-source-frame="3/1" data-hypit-source-rate="-1/1" data-hypit-source-fps="30/1"></video>');
+ const [slot] = videoSlots([{ id: "reverse", resource: "res_reverse", startFrame: 0, endFrameExclusive: 4,
+ sourceFrame: { numerator: 3, denominator: 1 }, sourceRate: { numerator: -1, denominator: 1 },
+ sourceFrameRate: { numerator: 30, denominator: 1 } }], () => "direct.mp4");
assert.ok(slot !== undefined);
assert.deepEqual(Array.from({ length: 4 }, (_, frame) => sourceFrameAt(slot, frame)), [3, 2, 1, 0]);
assert.deepEqual(sourceWindows([slot], { startFrame: 0, endFrameExclusive: 4 }), [{
@@ -142,14 +131,8 @@ test("real selected renders sample video correctly across wrap, hold and fractio
skip: process.env.HYPIT_BROWSER_TESTS !== "1",
}, async (t) => {
const root = await mkdtemp(join(tmpdir(), "hypit-render-range-test-"));
- const saved = [process.env.HYPERFRAMES_FFMPEG_PATH, process.env.HYPERFRAMES_FFPROBE_PATH];
- process.env.HYPERFRAMES_FFMPEG_PATH = join(root, "unselected-ffmpeg");
- process.env.HYPERFRAMES_FFPROBE_PATH = join(root, "unselected-ffprobe");
- t.after(() => {
- for (const [index, key] of ["HYPERFRAMES_FFMPEG_PATH", "HYPERFRAMES_FFPROBE_PATH"].entries()) {
- if (saved[index] === undefined) delete process.env[key]; else process.env[key] = saved[index];
- }
- });
+ const browser = process.env.HYPIT_TEST_CHROME_PATH === undefined
+ ? {} : { chromePath: process.env.HYPIT_TEST_CHROME_PATH };
try {
const colors = [[240, 20, 20], [20, 220, 20], [20, 20, 240], [220, 220, 20]];
const raw = Buffer.concat(colors.map((color) => Buffer.from(Array.from({ length: 64 * 64 }, () => color).flat())));
@@ -159,12 +142,12 @@ test("real selected renders sample video correctly across wrap, hold and fractio
assert.equal(encoded.status, 0, encoded.stderr.toString());
const resources = new MemoryResourceStore();
const document = documentFor(await resources.put(await readFile(path), "video/mp4"));
- const events: HyperframesRenderProgress[] = [];
+ const events: HtmlRasterProgress[] = [];
const render = async (name: string, range: { startFrame: number; endFrameExclusive: number } | undefined,
workers: number) => {
const warnings: string[] = [];
- const visual = await renderHyperframesVisual({ document, ...(range === undefined ? {} : { range }) },
- { resources, workers, quality: "high", processTimeoutMs: 120000,
+ const visual = await rasterizeHtmlProgram({ program: document, ...(range === undefined ? {} : { range }) },
+ { resources, workers, quality: "high", processTimeoutMs: 120000, ...browser,
maxPendingFrameBytes: 1, maxDecodedSourceBytes: 1,
onProgress: (e) => events.push(e),
onDiagnostic: async (event) => { if (event.level === "warning") warnings.push(event.message); } });
@@ -178,7 +161,7 @@ test("real selected renders sample video correctly across wrap, hold and fractio
const full = await render("full", undefined, 1);
events.length = 0;
const selected = await render("selected", { startFrame: 3, endFrameExclusive: 11 }, 3);
- const starts = events.filter((e): e is Extract<HyperframesRenderProgress, { browserPid: number | undefined }> => e.phase === "worker-start");
+ const starts = events.filter((e): e is Extract<HtmlRasterProgress, { browserPid: number | undefined }> => e.phase === "worker-start");
assert.equal(starts.length, 3);
assert.equal(new Set(starts.map((e) => e.browserPid)).size, 3);
const one = await render("one", { startFrame: 7, endFrameExclusive: 8 }, 4);
@@ -193,18 +176,20 @@ test("real selected renders sample video correctly across wrap, hold and fractio
}
}
for (let channel = 0; channel < 3; channel++) assert.ok(Math.abs(one[center + channel]! - colors[3]![channel]!) < 12);
- const snapshots = await renderHyperframesFrames({ document, frames: [3, 7, 8, 11] }, { resources, workers: 2 });
+ const snapshots = await rasterizeHtmlFrames({ program: document, frames: [3, 7, 8, 11] },
+ { resources, workers: 2, ...browser });
for (const [index, source] of [1, 3, 0, 1].entries()) {
const pixels = await sharp((await resources.get(snapshots[index]!.resource))!).removeAlpha().raw().toBuffer();
for (let channel = 0; channel < 3; channel++) assert.ok(Math.abs(pixels[center + channel]! - colors[source]![channel]!) < 12);
}
- await assert.rejects(renderHyperframesVisual({ document, range: { startFrame: 7, endFrameExclusive: 8 } },
- { resources, workers: 2, initializationTimeoutMs: 1, processTimeoutMs: 30_000 }), /worker 0 initialization timed out/);
+ await assert.rejects(rasterizeHtmlProgram({ program: document, range: { startFrame: 7, endFrameExclusive: 8 } },
+ { resources, workers: 2, initializationTimeoutMs: 1, processTimeoutMs: 30_000, ...browser }),
+ /worker 0 initialization timed out/);
assert.equal((await render("after-timeout", { startFrame: 7, endFrameExclusive: 8 }, 1)).length, stride);
// One cancelled attempt must not interrupt a different render using the same source store.
const controller = new AbortController();
- const stopped = renderHyperframesVisual({ document }, { resources, workers: 4, signal: controller.signal,
+ const stopped = rasterizeHtmlProgram({ program: document }, { resources, workers: 4, signal: controller.signal, ...browser,
onProgress: (event) => { if (event.phase === "worker-start") controller.abort(new Error("stop this attempt")); } });
const [failed, completed] = await Promise.allSettled([stopped, render("concurrent", undefined, 2)]);
assert.equal(failed.status, "rejected");
@@ -223,8 +208,8 @@ test("real selected renders sample video correctly across wrap, hold and fractio
}
const storeController = new AbortController();
const outputResources = new StalledOutput();
- await assert.rejects(renderHyperframesVisual({ document, range: { startFrame: 0, endFrameExclusive: 1 } },
- { resources: outputResources, workers: 1, signal: storeController.signal }), /stop output storage/u);
+ await assert.rejects(rasterizeHtmlProgram({ program: document, range: { startFrame: 0, endFrameExclusive: 1 } },
+ { resources: outputResources, workers: 1, signal: storeController.signal, ...browser }), /stop output storage/u);
assert.equal(outputResources.active, false);
} finally { await rm(root, { recursive: true, force: true }); }
});
@@ -236,11 +221,11 @@ test("fractional frame rates keep selected audio duration on the output frame cl
});
-test("Hyperframes claims actual browser count including a range shorter than workers", async () => {
+test("HTML claims actual browser count including a range shorter than workers", async () => {
const document = documentFor({ kind: "blob", resource: "res_range_source", size: 1, mediaType: "video/mp4" });
- const request = { id: "visual", capability: renderHyperframesCapabilities.renderVisual,
- returns: mediaTypes.renderedVisual, constraints: canonicalize({ document }), result: "visual-result" };
- const adapter = hypitPackage.hostFacets[0]!.implementation as RuntimeEndpointAdapterImplementation;
+ const request = { id: "visual", capability: htmlProgramCapabilities.rasterizeVisual,
+ returns: mediaTypes.timelineVisual, constraints: canonicalize({ program: document }), result: "visual-result" };
+ const adapter = hypitPackage.facets[0]!.implementation as RuntimeEndpointAdapterImplementation;
for (const [workers, browserCapacity, expectedUnits] of [[4, 6, 4], [128, 128, 12]] as const) {
const registry = new EndpointRegistry();
const activation = await adapter.activate({
@@ -252,7 +237,7 @@ test("Hyperframes claims actual browser count including a range shorter than wor
assert.equal(selected.status, "resolved");
const claims = endpointResourceClaims(selected.registration.scheduling!, request);
assert.deepEqual(claims.at(-1), { id: "capacity:machine/browsers", limit: browserCapacity, units: expectedUnits });
- const single = { ...request, constraints: canonicalize({ document, range: { startFrame: 7, endFrameExclusive: 8 } }) };
+ const single = { ...request, constraints: canonicalize({ program: document, range: { startFrame: 7, endFrameExclusive: 8 } }) };
assert.deepEqual(endpointResourceClaims(selected.registration.scheduling!, single).at(-1),
{ id: "capacity:machine/browsers", limit: browserCapacity, units: 1 });
}
diff --git a/packages/provider-hyperframes-local/test/source-frame-decoder.test.ts b/packages/provider-html-local/test/source-frame-decoder.test.ts
similarity index 100%
rename from packages/provider-hyperframes-local/test/source-frame-decoder.test.ts
rename to packages/provider-html-local/test/source-frame-decoder.test.ts
diff --git a/packages/provider-hyperframes-local/test/source-frame-store.test.ts b/packages/provider-html-local/test/source-frame-store.test.ts
similarity index 100%
rename from packages/provider-hyperframes-local/test/source-frame-store.test.ts
rename to packages/provider-html-local/test/source-frame-store.test.ts
diff --git a/packages/hyperframes/test/project.test.ts b/packages/provider-html-local/test/stage.test.ts
similarity index 70%
rename from packages/hyperframes/test/project.test.ts
rename to packages/provider-html-local/test/stage.test.ts
index bb4acbd4..dd9bba61 100644
--- a/packages/hyperframes/test/project.test.ts
+++ b/packages/provider-html-local/test/stage.test.ts
@@ -4,11 +4,10 @@ import { tmpdir } from "node:os";
import { join } from "node:path";
import { setTimeout as delay } from "node:timers/promises";
import test from "node:test";
-import { compileHyperframesDocument } from "../src/document.js";
-import { browserProgram } from "../src/browser-program.js";
-import { stageHyperframesHtmlProject, stageHyperframesProject } from "../src/project.js";
+import { htmlVisual, compileHtmlProgram } from "@hypit/html-program";
import { sealComposition, sealVisualTrack } from "@hypit/composition";
import { sealTimeline } from "@hypit/timeline";
+import { stageHtmlProgram } from "../src/stage.js";
test("typed Surface inspection borrows the completed streamed file used by capture", async () => {
const surface = { artifact: { kind: "blob" as const, resource: "res_streamed-surface" as const,
@@ -18,13 +17,13 @@ test("typed Surface inspection borrows the completed streamed file used by captu
const track = sealVisualTrack({ id: "surface", visualIr: "hypit.visual-ir@1", timelineId: space.id,
presents: [{ id: "surface", order: 0, z: 0, span: { startFrame: 0, endFrameExclusive: 30 },
elements: [{ id: "surface", kind: "surface", surface, order: 0, style: [] }] }] });
- const document = compileHyperframesDocument(sealComposition({ id: "main",
+ const document = compileHtmlProgram(sealComposition({ id: "main",
canvas: { width: 64, height: 64, clearColor: "#000000" }, tracks: [track] }), space);
const directory = await mkdtemp(join(tmpdir(), "hypit-stage-surface-"));
let inspected = false;
let streamFinished = false;
try {
- await stageHyperframesProject({ document, directory, read: async () => (async function* () {
+ await stageHtmlProgram({ document, directory, read: async () => (async function* () {
// Readers may reuse their chunk buffer after each write.
const chunk = new Uint8Array([1, 2, 3]);
yield chunk;
@@ -51,12 +50,12 @@ test("staging cancels and joins sibling reads before exposing a failure", async
elements: [{ id, order: 0, kind: "image" as const, style: [],
artifact: { kind: "blob" as const, resource: `res_${id}` as const, size: 1, mediaType: "image/png" } }],
})) });
- const document = compileHyperframesDocument(sealComposition({ id: "main", canvas: { width: 64, height: 64, clearColor: "#000000" }, tracks: [track] }), space);
+ const document = compileHtmlProgram(sealComposition({ id: "main", canvas: { width: 64, height: 64, clearColor: "#000000" }, tracks: [track] }), space);
const directory = await mkdtemp(join(tmpdir(), "hypit-stage-cancel-"));
let active = 0;
let started = 0;
try {
- await assert.rejects(stageHyperframesProject({ document, directory, read: async (artifact, signal) => {
+ await assert.rejects(stageHtmlProgram({ document, directory, read: async (artifact, signal) => {
active++;
started++;
try {
@@ -78,14 +77,14 @@ test("document staging bounds complete Artifact lifecycles without changing dete
elements: [{ id, order: 0, kind: "image" as const, style: [],
artifact: { kind: "blob" as const, resource: `res_${id}` as const, size: 1, mediaType: "image/png" } }],
})) });
- const document = compileHyperframesDocument(sealComposition({ id: "main",
+ const document = compileHtmlProgram(sealComposition({ id: "main",
canvas: { width: 64, height: 64, clearColor: "#000000" }, tracks: [track] }), space);
const directory = await mkdtemp(join(tmpdir(), "hypit-stage-bounded-"));
let active = 0;
let peak = 0;
let reads = 0;
try {
- await stageHyperframesProject({ document, directory, maxConcurrentArtifacts: 3, read: async () => {
+ await stageHtmlProgram({ document, directory, maxConcurrentArtifacts: 3, read: async () => {
active++;
reads++;
peak = Math.max(peak, active);
@@ -118,16 +117,16 @@ test("document staging reads only Artifacts whose compiler usage overlaps the wh
elements: [{ id: "late", order: 0, kind: "image" as const, style: [], artifact: late }] },
{ id: "opaque", order: 3, z: 3, span: { startFrame: 20, endFrameExclusive: 30 },
elements: [{ id: "opaque", order: 0, kind: "program" as const, style: [],
- program: browserProgram({ html: `<img src="hypit-resource://${always.resource}">` }, [always]) }] },
+ program: htmlVisual({ html: `<img src="hypit-resource://${always.resource}">` }, [always]) }] },
] });
- const document = compileHyperframesDocument(sealComposition({ id: "main",
+ const document = compileHtmlProgram(sealComposition({ id: "main",
canvas: { width: 64, height: 64, clearColor: "#000000" }, tracks: [track] }), space);
assert.deepEqual(document.artifacts.find(({ artifact }) => artifact.resource === first.resource)?.usage,
{ kind: "frames", spans: [{ startFrame: 0, endFrameExclusive: 10 }] }, "adjacent uses merge canonically");
const directory = await mkdtemp(join(tmpdir(), "hypit-stage-selection-"));
const reads: string[] = [];
try {
- await stageHyperframesProject({ document, directory,
+ await stageHtmlProgram({ document, directory,
frameSelection: [{ startFrame: 2, endFrameExclusive: 3 }],
read: async artifact => { reads.push(artifact.resource); return new Uint8Array([1]); } });
assert.deepEqual(reads, [always.resource, first.resource], "opaque dependencies remain conservative");
@@ -147,8 +146,8 @@ test("document staging rejects an invalid concurrency bound", async () => {
})();
const directory = await mkdtemp(join(tmpdir(), "hypit-stage-invalid-bound-"));
try {
- await assert.rejects(stageHyperframesProject({
- document: compileHyperframesDocument(composition, timeline), directory,
+ await assert.rejects(stageHtmlProgram({
+ document: compileHtmlProgram(composition, timeline), directory,
maxConcurrentArtifacts: 0, read: async () => new Uint8Array(),
}), /concurrency must be a positive safe integer/u);
} finally { await rm(directory, { recursive: true, force: true }); }
@@ -161,7 +160,7 @@ test("document staging drains readers and preserves an external cancellation rea
elements: [{ id, order: 0, kind: "image" as const, style: [],
artifact: { kind: "blob" as const, resource: `res_${id}` as const, size: 1, mediaType: "image/png" } }],
})) });
- const document = compileHyperframesDocument(sealComposition({ id: "main",
+ const document = compileHtmlProgram(sealComposition({ id: "main",
canvas: { width: 64, height: 64, clearColor: "#000000" }, tracks: [track] }), space);
const directory = await mkdtemp(join(tmpdir(), "hypit-stage-external-cancel-"));
const controller = new AbortController();
@@ -169,7 +168,7 @@ test("document staging drains readers and preserves an external cancellation rea
let active = 0;
let started = 0;
try {
- const staging = stageHyperframesProject({ document, directory, maxConcurrentArtifacts: 2,
+ const staging = stageHtmlProgram({ document, directory, maxConcurrentArtifacts: 2,
signal: controller.signal, read: async (_artifact, signal) => {
active++;
started++;
@@ -192,10 +191,10 @@ test("staging gives opaque Resource identities portable local names and writes c
presents: [{ id: "image", order: 0, z: 0, span: { startFrame: 0, endFrameExclusive: 30 },
elements: [{ id: "image", kind: "image", order: 0, style: [],
artifact: { kind: "blob", resource, size: 5, mediaType: "image/png" } }] }] });
- const document = compileHyperframesDocument(sealComposition({ id: "main", canvas: { width: 64, height: 64, clearColor: "#000000" }, tracks: [track] }), space);
+ const document = compileHtmlProgram(sealComposition({ id: "main", canvas: { width: 64, height: 64, clearColor: "#000000" }, tracks: [track] }), space);
const directory = await mkdtemp(join(tmpdir(), "hypit-stage-identity-"));
try {
- await stageHyperframesProject({ document, directory, read: async artifact => {
+ await stageHtmlProgram({ document, directory, read: async artifact => {
assert.equal(artifact.resource, resource);
return (async function* () { yield new Uint8Array([1, 2]); yield new Uint8Array([3, 4, 5]); })();
} });
@@ -208,74 +207,3 @@ test("staging gives opaque Resource identities portable local names and writes c
assert.ok(document.html.includes(resource), "materialization does not rewrite the portable document");
} finally { await rm(directory, { recursive: true, force: true }); }
});
-
-test("HTML staging writes one file when several URLs name the same Resource", async () => {
- const directory = await mkdtemp(join(tmpdir(), "hypit-stage-html-alias-"));
- const artifact = {
- kind: "blob" as const,
- resource: "res_shared-html-image" as const,
- size: 3,
- mediaType: "image/png",
- };
- let reads = 0;
- try {
- await stageHyperframesHtmlProject({
- directory,
- project: {
- html: '<div data-composition-id="main" data-fps="30/1" data-hypit-frame-count="30" data-width="64" data-height="64"><img src="first.png"><img src="second.png"></div>',
- assets: [
- { url: "first.png", artifact },
- { url: "second.png", artifact: { ...artifact } },
- ],
- },
- read: async () => {
- reads += 1;
- return new Uint8Array([1, 2, 3]);
- },
- });
- assert.equal(reads, 1);
- assert.deepEqual(await readdir(join(directory, "artifacts")), ["asset-0.png"]);
- const html = await readFile(join(directory, "index.html"), "utf8");
- assert.equal(html.match(/\.\/artifacts\/asset-0\.png/gu)?.length, 2);
- } finally { await rm(directory, { recursive: true, force: true }); }
-});
-
-test("HTML staging relocates compiler-deferred media URLs without activating them", async () => {
- const directory = await mkdtemp(join(tmpdir(), "hypit-stage-html-deferred-"));
- const artifact = {
- kind: "blob" as const,
- resource: "res_deferred-html-image" as const,
- size: 3,
- mediaType: "image/png",
- };
- try {
- await stageHyperframesHtmlProject({
- directory,
- project: {
- html: '<div data-composition-id="main" data-fps="30/1" data-hypit-frame-count="30" data-width="64" data-height="64"><img data-hypit-resource-src="picture.png"></div>',
- assets: [{ url: "picture.png", artifact }],
- },
- read: async () => new Uint8Array([1, 2, 3]),
- });
- const html = await readFile(join(directory, "index.html"), "utf8");
- assert.match(html, /data-hypit-resource-src="\.\/artifacts\/asset-0\.png"/u);
- assert.doesNotMatch(html, /<img\b[^>]*\ssrc=/u);
- } finally { await rm(directory, { recursive: true, force: true }); }
-});
-
-test("HTML staging rejects conflicting metadata for one Resource identity", async () => {
- const directory = await mkdtemp(join(tmpdir(), "hypit-stage-html-conflict-"));
- try {
- await assert.rejects(stageHyperframesHtmlProject({
- directory,
- project: {
- html: '<div data-composition-id="main" data-fps="30" data-hypit-frame-count="30" data-width="64" data-height="64"><img src="first.png"><img src="second.png"></div>',
- assets: [
- { url: "first.png", artifact: { kind: "blob", resource: "res_conflicting-html-image", size: 3, mediaType: "image/png" } },
- { url: "second.png", artifact: { kind: "blob", resource: "res_conflicting-html-image", size: 4, mediaType: "image/png" } },
- ],
- },
- read: async () => new Uint8Array([1, 2, 3]),
- }), /conflicting metadata/u);
- } finally { await rm(directory, { recursive: true, force: true }); }
-});
diff --git a/packages/provider-html-local/test/surface-validation.test.ts b/packages/provider-html-local/test/surface-validation.test.ts
new file mode 100644
index 00000000..f62f4199
--- /dev/null
+++ b/packages/provider-html-local/test/surface-validation.test.ts
@@ -0,0 +1,153 @@
+import { spawn, spawnSync } from "node:child_process";
+import { chmod, mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import assert from "node:assert/strict";
+import test from "node:test";
+import { setTimeout as delay } from "node:timers/promises";
+
+import { verifyCompositableSurfaceFile } from "../src/surface-validation.js";
+import type { CompositableSurfaceRef } from "@hypit/media";
+
+const hasMediaTools = spawnSync("ffmpeg", ["-version"], { stdio: "ignore", windowsHide: true }).status === 0
+ && spawnSync("ffprobe", ["-version"], { stdio: "ignore", windowsHide: true }).status === 0;
+
+async function ffmpeg(argv: readonly string[]): Promise<void> {
+ await new Promise<void>((resolve, reject) => {
+ const child = spawn("ffmpeg", ["-hide_banner", "-loglevel", "error", ...argv], {
+ shell: false,
+ windowsHide: true,
+ stdio: ["ignore", "ignore", "pipe"],
+ });
+ let stderr = "";
+ child.stderr.on("data", (chunk: Buffer) => { stderr += chunk.toString(); });
+ child.on("error", reject);
+ child.on("close", (code) => code === 0 ? resolve() : reject(new Error(stderr)));
+ });
+}
+
+let surfaceId = 0;
+
+function surface(bytes: Uint8Array, options: {
+ readonly mediaType: string;
+ readonly width: number;
+ readonly height: number;
+ readonly alphaMode: "opaque" | "straight";
+ readonly timing: CompositableSurfaceRef["timing"];
+}): CompositableSurfaceRef {
+ const resource = `res_surface-${surfaceId += 1}` as const;
+ return {
+ artifact: { kind: "blob", resource, size: bytes.byteLength, mediaType: options.mediaType },
+ width: options.width,
+ height: options.height,
+ colorSpace: "srgb",
+ alphaMode: options.alphaMode,
+ timing: options.timing,
+ };
+}
+
+test("cancelling staged Surface inspection stops both probes and preserves the caller's file", {
+ skip: process.platform === "win32",
+}, async () => {
+ const directory = await mkdtemp(join(tmpdir(), "hypit-surface-cancel-"));
+ const program = join(directory, "ffprobe");
+ const marker = join(directory, "running");
+ const bytes = new Uint8Array([0]);
+ const value = surface(bytes, { mediaType: "image/png", width: 1, height: 1,
+ alphaMode: "opaque", timing: { kind: "still" } });
+ try {
+ await writeFile(program, `#!${process.execPath}
+const fs = require('node:fs');
+fs.writeFileSync(${JSON.stringify(marker)} + '-' + process.pid, '');
+setInterval(() => {}, 1000);
+`);
+ await chmod(program, 0o755);
+ const path = join(directory, "staged.png");
+ await writeFile(path, bytes);
+ const controller = new AbortController();
+ const checking = verifyCompositableSurfaceFile({ surface: value, path, ffprobePath: program,
+ signal: controller.signal });
+ const rejected = assert.rejects(checking, /stop probes/u);
+ let pids: number[] = [];
+ for (let i = 0; i < 200; i++) {
+ pids = (await readdir(directory)).filter((name) => name.startsWith("running-"))
+ .map((name) => Number(name.slice("running-".length)));
+ if (pids.length === 2) break;
+ await delay(10);
+ }
+ controller.abort(new Error("stop probes"));
+ await rejected;
+ assert.equal(pids.length, 2);
+ for (const pid of pids) assert.throws(() => process.kill(pid, 0), { code: "ESRCH" });
+ assert.deepEqual([...await readFile(path)], [...bytes]);
+ await writeFile(program, `#!${process.execPath}
+console.log(JSON.stringify(process.argv.includes('-show_pixel_formats')
+ ? { pixel_formats: [{ name: 'rgb24', flags: { alpha: 0 } }] }
+ : { streams: [{ codec_type: 'video', width: 1, height: 1, pix_fmt: 'rgb24', nb_read_frames: '1' }] }));
+`);
+ await verifyCompositableSurfaceFile({ surface: value, path, ffprobePath: program });
+ } finally { await rm(directory, { recursive: true, force: true }); }
+});
+
+test("Surface file admission accepts matching still/video bytes and rejects contradictions", {
+ skip: !hasMediaTools,
+}, async () => {
+ const directory = await mkdtemp(join(tmpdir(), "hypit-surface-test-"));
+ try {
+ const opaquePath = join(directory, "opaque.png");
+ const alphaPath = join(directory, "alpha.png");
+ const videoPath = join(directory, "video.mp4");
+ await ffmpeg(["-f", "lavfi", "-i", "color=c=red:s=8x6:d=1", "-frames:v", "1", opaquePath]);
+ await ffmpeg(["-f", "lavfi", "-i", "[email protected]:s=8x6:d=1,format=rgba", "-frames:v", "1", alphaPath]);
+ await ffmpeg([
+ "-f", "lavfi", "-i", "color=c=blue:s=8x6:r=4:d=1",
+ "-frames:v", "4", "-c:v", "libx264", "-pix_fmt", "yuv420p", videoPath,
+ ]);
+ const [opaque, alpha, video] = await Promise.all([
+ readFile(opaquePath), readFile(alphaPath), readFile(videoPath),
+ ]);
+ const opaqueSurface = surface(opaque, {
+ mediaType: "image/png", width: 8, height: 6, alphaMode: "opaque", timing: { kind: "still" },
+ });
+ const alphaSurface = surface(alpha, {
+ mediaType: "image/png", width: 8, height: 6, alphaMode: "straight", timing: { kind: "still" },
+ });
+ const videoSurface = surface(video, {
+ mediaType: "video/mp4", width: 8, height: 6, alphaMode: "opaque",
+ timing: { kind: "frames", frameRate: { numerator: 4, denominator: 1 }, frameCount: 4 },
+ });
+
+ await verifyCompositableSurfaceFile({ surface: opaqueSurface, path: opaquePath });
+ await verifyCompositableSurfaceFile({ surface: alphaSurface, path: alphaPath });
+ await verifyCompositableSurfaceFile({ surface: videoSurface, path: videoPath });
+ await verifyCompositableSurfaceFile({ surface: videoSurface, path: videoPath });
+ await assert.rejects(verifyCompositableSurfaceFile({ surface: {
+ ...videoSurface, artifact: { ...videoSurface.artifact, size: video.byteLength + 1 },
+ }, path: videoPath }), /byte size differs/u);
+ await assert.rejects(verifyCompositableSurfaceFile({ surface: {
+ ...videoSurface, width: 10,
+ }, path: videoPath }), /dimensions differ/u);
+ assert.deepEqual(await readFile(videoPath), video, "inspection never rewrites or deletes the caller's file");
+
+ await assert.rejects(
+ verifyCompositableSurfaceFile({ surface: { ...opaqueSurface, width: 9 }, path: opaquePath }),
+ /dimensions differ/u,
+ );
+ await assert.rejects(
+ verifyCompositableSurfaceFile({ surface: { ...alphaSurface, alphaMode: "opaque" }, path: alphaPath }),
+ /encoded format carries alpha/u,
+ );
+ await assert.rejects(
+ verifyCompositableSurfaceFile({
+ surface: {
+ ...videoSurface,
+ timing: { kind: "frames", frameRate: { numerator: 4, denominator: 1 }, frameCount: 3 },
+ },
+ path: videoPath,
+ }),
+ /frame count differs/u,
+ );
+ } finally {
+ await rm(directory, { recursive: true, force: true });
+ }
+});
diff --git a/packages/provider-hyperframes-local/test/visual-readiness.test.ts b/packages/provider-html-local/test/visual-readiness.test.ts
similarity index 66%
rename from packages/provider-hyperframes-local/test/visual-readiness.test.ts
rename to packages/provider-html-local/test/visual-readiness.test.ts
index 308ba71b..d8224a1e 100644
--- a/packages/provider-hyperframes-local/test/visual-readiness.test.ts
+++ b/packages/provider-html-local/test/visual-readiness.test.ts
@@ -1,19 +1,24 @@
import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
import { createServer } from "node:http";
import test from "node:test";
import puppeteer from "puppeteer-core";
import sharp from "sharp";
-import type { CaptureSession } from "@hyperframes/engine";
-import { MemoryResourceStore } from "@hypit/driver-node";
+import { fineCaptionStyle, renderFineCaption, scheduleFineCaption } from "@hypit/caption-fine";
+import { MemoryResourceStore } from "@hypit/executor";
import { sealComposition, sealVisualTrack } from "@hypit/composition";
import type { VisualElement, VisualTextTypography } from "@hypit/composition";
-import { compileHyperframesDocument, materializeHyperframesHtml } from "@hypit/hyperframes";
+import { compileHtmlProgram, materializeHtmlProgram } from "@hypit/html-program";
+import { captionDocument, parseScript } from "@hypit/script";
import { sealTimeline } from "@hypit/timeline";
import { browserExecutablePath } from "../src/browser.js";
import { createOpaqueFrameCapture } from "../src/opaque-capture.js";
-import { renderHyperframesFrames } from "../src/render.js";
+import { rasterizeHtmlFrames } from "../src/render.js";
const live = { skip: process.env.HYPIT_BROWSER_TESTS !== "1" };
+const testBrowser = () => process.env.HYPIT_TEST_CHROME_PATH ?? browserExecutablePath({});
+const testBrowserOption = () => process.env.HYPIT_TEST_CHROME_PATH === undefined
+ ? {} : { chromePath: process.env.HYPIT_TEST_CHROME_PATH };
test("capture waits for dynamic images and rejects broken images or exact fonts", live, async (t) => {
const png = await sharp({ create: { width: 64, height: 64, channels: 3, background: "#ff0000" } }).png().toBuffer();
@@ -29,7 +34,7 @@ test("capture waits for dynamic images and rejects broken images or exact fonts"
const address = server.address();
assert.ok(address !== null && typeof address !== "string");
const origin = `http://127.0.0.1:${address.port}`;
- const browser = await puppeteer.launch({ executablePath: browserExecutablePath({}), headless: true, args: ["--no-sandbox"] });
+ const browser = await puppeteer.launch({ executablePath: testBrowser(), headless: true, args: ["--no-sandbox"] });
try {
for (const kind of ["class", "pseudo", "mask", "svg", "broken", "font"] as const) await t.test(kind, async () => {
const page = await browser.newPage();
@@ -45,14 +50,13 @@ test("capture waits for dynamic images and rejects broken images or exact fonts"
await page.setContent(`<style>body{margin:0}${css}</style>${html}`);
if (kind === "broken") await page.waitForFunction(() => document.images[0]!.complete);
await page.evaluate(({ kind, origin }) => {
- (window as unknown as { __hf: unknown }).__hf = { async seek() {
+ (window as unknown as { __hypitFrameProgram: unknown }).__hypitFrameProgram = { async applyFrame() {
const target = document.getElementById("target");
if (kind === "svg") target!.setAttribute("href", `${origin}/svg.png`);
else if (target !== null) target.classList.add("paint");
} };
}, { kind, origin });
- const capture = await createOpaqueFrameCapture({ page,
- options: { fps: { num: 30, den: 1 }, width: 64, height: 64 } } as unknown as CaptureSession);
+ const capture = await createOpaqueFrameCapture(page, { width: 64, height: 64 });
if (kind === "broken") await assert.rejects(capture(0), /image could not be decoded/u);
else if (kind === "font") await assert.rejects(capture(0), /font could not be loaded/u);
else {
@@ -70,19 +74,18 @@ test("capture waits for dynamic images and rejects broken images or exact fonts"
await page.setContent(`<style>body{margin:0}</style><div id="target" style="width:64px;height:64px;background:#000"></div>${"<span></span>".repeat(200)}`);
await page.evaluate(origin => {
const original = window.getComputedStyle.bind(window);
- const state = window as unknown as { __styleReads: number; __hf: unknown };
+ const state = window as unknown as { __styleReads: number; __hypitFrameProgram: unknown };
state.__styleReads = 0;
Object.defineProperty(window, "getComputedStyle", { configurable: true, value(...args: Parameters<typeof getComputedStyle>) {
state.__styleReads += 1;
return original(...args);
} });
- state.__hf = { async seek(time: number) {
- if (time >= 1 / 30) document.getElementById("target")!.style.opacity = "0.999";
- if (time >= 2 / 30) document.getElementById("target")!.style.backgroundImage = `url(${origin}/local.png)`;
+ state.__hypitFrameProgram = { async applyFrame(frame: number) {
+ if (frame >= 1) document.getElementById("target")!.style.opacity = "0.999";
+ if (frame >= 2) document.getElementById("target")!.style.backgroundImage = `url(${origin}/local.png)`;
} };
}, origin);
- const capture = await createOpaqueFrameCapture({ page,
- options: { fps: { num: 30, den: 1 }, width: 64, height: 64 } } as unknown as CaptureSession);
+ const capture = await createOpaqueFrameCapture(page, { width: 64, height: 64 });
await capture(0);
const initialReads = await page.evaluate(() => (window as unknown as { __styleReads: number }).__styleReads);
assert.ok(initialReads >= 600, "the initial pass should discover the complete existing document");
@@ -104,7 +107,7 @@ test("capture waits for dynamic images and rejects broken images or exact fonts"
await page.setContent(`<style>body{margin:0}</style><div id="selected" style="width:64px;height:64px;background:#000"></div><div id="unselected">${"<span></span>".repeat(200)}</div>`);
await page.evaluate(origin => {
const original = window.getComputedStyle.bind(window);
- const state = window as unknown as { __styleReads: number; __hf: unknown; __hypitCaptureRoots: readonly Element[] };
+ const state = window as unknown as { __styleReads: number; __hypitFrameProgram: unknown; __hypitCaptureRoots: readonly Element[] };
state.__styleReads = 0;
Object.defineProperty(window, "getComputedStyle", { configurable: true, value(...args: Parameters<typeof getComputedStyle>) {
state.__styleReads += 1;
@@ -112,12 +115,11 @@ test("capture waits for dynamic images and rejects broken images or exact fonts"
} });
const selected = document.getElementById("selected")!;
state.__hypitCaptureRoots = [selected];
- state.__hf = { async seek(time: number) {
+ state.__hypitFrameProgram = { async applyFrame(time: number) {
if (time >= 1 / 30) selected.style.backgroundImage = `url(${origin}/scoped.png)`;
} };
}, origin);
- const capture = await createOpaqueFrameCapture({ page,
- options: { fps: { num: 30, den: 1 }, width: 64, height: 64 } } as unknown as CaptureSession);
+ const capture = await createOpaqueFrameCapture(page, { width: 64, height: 64 });
await capture(0);
const initialReads = await page.evaluate(() => (window as unknown as { __styleReads: number }).__styleReads);
assert.ok(initialReads <= 6, `one capture root unexpectedly caused ${initialReads} style reads`);
@@ -139,10 +141,9 @@ test("capture waits for dynamic images and rejects broken images or exact fonts"
{ backgroundImage: `url(${origin}/blue.png)` },
], { duration: 1_000, fill: "both" });
animation.pause();
- (window as unknown as { __hf: unknown }).__hf = { async seek(time: number) { animation.currentTime = time * 1_000; } };
+ (window as unknown as { __hypitFrameProgram: unknown }).__hypitFrameProgram = { async applyFrame(time: number) { animation.currentTime = time * 1_000; } };
}, origin);
- const capture = await createOpaqueFrameCapture({ page,
- options: { fps: { num: 30, den: 1 }, width: 64, height: 64 } } as unknown as CaptureSession);
+ const capture = await createOpaqueFrameCapture(page, { width: 64, height: 64 });
const first = await capture(0);
const last = await capture(30);
for (const [frame, expected] of [[first, [255, 0, 0]], [last, [0, 0, 255]]] as const) {
@@ -159,15 +160,14 @@ test("capture waits for dynamic images and rejects broken images or exact fonts"
await page.setContent('<style>body{margin:0}</style><div id="target" style="width:64px;height:64px"></div>');
await page.evaluate(origin => {
let changed = false;
- (window as unknown as { __hf: unknown }).__hf = { async seek(time: number) {
+ (window as unknown as { __hypitFrameProgram: unknown }).__hypitFrameProgram = { async applyFrame(time: number) {
if (!changed && time >= 1 / 30) {
changed = true;
document.styleSheets[0]!.insertRule(`#target{background-image:url(${origin}/cssom.png)}`);
}
} };
}, origin);
- const capture = await createOpaqueFrameCapture({ page,
- options: { fps: { num: 30, den: 1 }, width: 64, height: 64 } } as unknown as CaptureSession);
+ const capture = await createOpaqueFrameCapture(page, { width: 64, height: 64 });
await capture(0);
const frame = await capture(1);
const { data, info } = await sharp(frame.buffer).raw().toBuffer({ resolveWithObject: true });
@@ -200,16 +200,16 @@ test("compiled frame selection neither stages nor waits for unrelated image reso
elements: [{ id: "red", order: 0, kind: "image", artifact: red,
style: [{ name: "width", value: "64px" }, { name: "height", value: "64px" }] }] },
] });
- const document = compileHyperframesDocument(sealComposition({ id: "capture-scope",
+ const document = compileHtmlProgram(sealComposition({ id: "capture-scope",
canvas: { width: 64, height: 64, clearColor: "#000000" }, tracks: [track] }), space);
- const [artifact] = await renderHyperframesFrames({ document, frames: [45] },
- { resources, workers: 1, processTimeoutMs: 120_000 });
+ const [artifact] = await rasterizeHtmlFrames({ program: document, frames: [45] },
+ { resources, workers: 1, processTimeoutMs: 120_000, ...testBrowserOption() });
const pixels = await sharp((await resources.get(artifact!.resource))!).removeAlpha().raw().toBuffer();
const center = (32 * 64 + 32) * 3;
assert.deepEqual([...pixels.subarray(center, center + 3)], [255, 0, 0]);
- await assert.rejects(renderHyperframesFrames({ document, frames: [15] },
- { resources, workers: 1, processTimeoutMs: 120_000 }), /image could not be decoded/u);
+ await assert.rejects(rasterizeHtmlFrames({ program: document, frames: [15] },
+ { resources, workers: 1, processTimeoutMs: 120_000, ...testBrowserOption() }), /image could not be decoded/u);
});
test("real capture keeps later Present animation local with picture content and independent workers", live, async () => {
@@ -235,11 +235,11 @@ test("real capture keeps later Present animation local with picture content and
] } }],
})),
});
- const document = compileHyperframesDocument(sealComposition({ id: "local-animation", canvas: {
+ const document = compileHtmlProgram(sealComposition({ id: "local-animation", canvas: {
width: 64, height: 64, clearColor: "#000000",
}, tracks: [picture, animated] }), timeline);
- const frames = await renderHyperframesFrames({ document, frames: [15, 45, 75] }, {
- resources, workers: 2, processTimeoutMs: 120_000,
+ const frames = await rasterizeHtmlFrames({ program: document, frames: [15, 45, 75] }, {
+ resources, workers: 2, processTimeoutMs: 120_000, ...testBrowserOption(),
});
for (const [index, artifact] of frames.entries()) {
const pixels = await sharp((await resources.get(artifact.resource))!).removeAlpha().raw().toBuffer();
@@ -250,6 +250,119 @@ test("real capture keeps later Present animation local with picture content and
}
});
+test("Fine Caption Cues stay isolated over Picture during reverse seeks and independent workers", live, async () => {
+ const resources = new MemoryResourceStore();
+ const blackBytes = await sharp({
+ create: { width: 320, height: 180, channels: 3, background: "#000000" },
+ }).png().toBuffer();
+ const black = await resources.put(blackBytes, "image/png");
+ const fontBytes = await readFile(new URL(import.meta.resolve(
+ "@fontsource-variable/inter/files/inter-latin-wght-normal.woff2",
+ )));
+ const font = {
+ sources: [{ artifact: await resources.put(fontBytes, "font/woff2") }],
+ weight: 400,
+ style: "normal" as const,
+ };
+ const timeline = sealTimeline({ id: "fine-caption-isolation", frameCount: 90,
+ frameRate: { numerator: 30, denominator: 1 } });
+ const document = captionDocument(parseScript("caption-isolation.svml",
+ "<line>FIRST || SECOND || THIRD</line>"), "story.caption", "story");
+ assert.equal(document.units.length, 3);
+
+ const recipe = (path: string, fill: string) => ({ path, properties: {
+ align: "center", background: "#00000000", fill, "line-height": 1,
+ padding: "0", radius: 0, size: 72, "stack-order": 10, width: 1, x: 0.5, y: 0.5,
+ "anchor-x": "center", "anchor-y": "center", "inline-size": "fixed",
+ karaoke: "off", "stroke-width": 0, "shadow-opacity": 0,
+ "lead-frames": 0, "tail-frames": 0, handoff: "cut",
+ "cue-enter": "fade", "cue-enter-frames": 10,
+ } });
+ const styles = [
+ fineCaptionStyle("red", recipe("caption.red", "#FF0000"), [font]),
+ fineCaptionStyle("green", recipe("caption.green", "#00FF00"), [font]),
+ fineCaptionStyle("blue", recipe("caption.blue", "#0000FF"), [font]),
+ ];
+ const useWindow = (id: string, startFrame: number, endFrameExclusive: number) => ({
+ id, subjectId: id,
+ start: { id: `${id}.start`, subjectId: id, timelineId: timeline.id, frame: startFrame },
+ end: { id: `${id}.end`, subjectId: id, timelineId: timeline.id, frame: endFrameExclusive },
+ span: { startFrame, endFrameExclusive },
+ });
+ const program = { id: "captions", documentId: document.id, styles, uses: [
+ { styleId: "red", window: useWindow("red-use", 0, 30) },
+ { styleId: "green", window: useWindow("green-use", 30, 60) },
+ { styleId: "blue", window: useWindow("blue-use", 60, 90) },
+ ] };
+ const timing = { timelineId: timeline.id, documentId: document.id, cues: document.units.map((unit, index) => ({
+ id: `cue-${index + 1}`, startFrame: index * 30, endFrameExclusive: index * 30 + 30,
+ units: [{ unitId: unit.id, startFrame: index * 30, endFrameExclusive: index * 30 + 30 }],
+ })) };
+ const captions = renderFineCaption(scheduleFineCaption(timing, program, document), program, document,
+ timeline, { xPx: 0, yPx: 0, widthPx: 320, heightPx: 180 });
+ assert.deepEqual(captions.presents.map(present => present.span), [
+ { startFrame: 0, endFrameExclusive: 30 },
+ { startFrame: 30, endFrameExclusive: 60 },
+ { startFrame: 60, endFrameExclusive: 90 },
+ ]);
+
+ const picture = sealVisualTrack({ id: "picture", timelineId: timeline.id,
+ visualIr: "hypit.visual-ir@1", presents: [{ id: "picture", order: 0, z: 0,
+ span: { startFrame: 0, endFrameExclusive: 90 }, elements: [{ id: "picture", order: 0,
+ kind: "image", artifact: black, style: [{ name: "position", value: "absolute" },
+ { name: "inset", value: 0 }, { name: "width", value: "320px" }, { name: "height", value: "180px" }],
+ animation: { keyframes: [{ atFrame: 0, style: [{ name: "opacity", value: 1 }] },
+ { atFrame: 90, style: [{ name: "opacity", value: 1 }] }] } }] }] });
+ const html = compileHtmlProgram(sealComposition({ id: "fine-caption-isolation",
+ canvas: { width: 320, height: 180, clearColor: "#000000" }, tracks: [picture, captions] }), timeline);
+
+ const assertCueColors = async (buffer: Uint8Array, wanted: "red" | "green" | "blue", label: string) => {
+ const { data } = await sharp(buffer).removeAlpha().raw().toBuffer({ resolveWithObject: true });
+ const colors = { red: 0, green: 0, blue: 0 };
+ for (let offset = 0; offset < data.length; offset += 3) {
+ const red = data[offset]!, green = data[offset + 1]!, blue = data[offset + 2]!;
+ if (red > 96 && green < red / 3 && blue < red / 3) colors.red += 1;
+ if (green > 96 && red < green / 3 && blue < green / 3) colors.green += 1;
+ if (blue > 96 && red < blue / 3 && green < blue / 3) colors.blue += 1;
+ }
+ assert.ok(colors[wanted] > 100, `${label} lost ${wanted} Cue glyphs`);
+ for (const color of ["red", "green", "blue"] as const) if (color !== wanted) assert.equal(colors[color], 0,
+ `${label} leaked ${color} Cue glyphs: ${JSON.stringify(colors)}`);
+ };
+
+ const materialized = materializeHtmlProgram(html, artifact => {
+ if (artifact.resource === black.resource) return `data:image/png;base64,${blackBytes.toString("base64")}`;
+ if (artifact.resource === font.sources[0]!.artifact.resource) {
+ return `data:font/woff2;base64,${fontBytes.toString("base64")}`;
+ }
+ throw new Error(`unexpected Fine Caption fixture Resource ${artifact.resource}`);
+ });
+ const browser = await puppeteer.launch({ executablePath: testBrowser(), headless: true, args: ["--no-sandbox"] });
+ try {
+ const page = await browser.newPage();
+ try {
+ await page.setViewport({ width: 320, height: 180 });
+ await page.setContent(materialized);
+ const capture = await createOpaqueFrameCapture(page, { width: 320, height: 180 });
+ for (const [frame, color] of [[75, "blue"], [15, "red"], [45, "green"]] as const) {
+ await assertCueColors((await capture(frame)).buffer, color, `direct reverse seek frame ${frame}`);
+ }
+ } finally { await page.close(); }
+ } finally { await browser.close(); }
+
+ const requested = [15, 45, 75];
+ const expected = ["red", "green", "blue"] as const;
+ for (const workers of [1, 3]) {
+ const rendered = await rasterizeHtmlFrames({ program: html, frames: requested }, {
+ resources, workers, processTimeoutMs: 120_000, ...testBrowserOption(),
+ });
+ for (const [index, artifact] of rendered.entries()) {
+ await assertCueColors((await resources.get(artifact.resource))!, expected[index]!,
+ `worker count ${workers}, frame ${requested[index]}`);
+ }
+ }
+});
+
test("terminal text and SVG mask sources retain their Present frame animations across direct seeks and fresh workers", live, async () => {
const space = sealTimeline({ id: "animations", frameCount: 60, frameRate: { numerator: 30, denominator: 1 } });
const image = { kind: "blob", resource: "res_mask", size: 1, mediaType: "image/png" } as const;
@@ -288,24 +401,19 @@ test("terminal text and SVG mask sources retain their Present frame animations a
];
const track = sealVisualTrack({ id: "visual", timelineId: space.id, visualIr: "hypit.visual-ir@1",
presents: [{ id: "later", order: 0, z: 0, span: { startFrame: 15, endFrameExclusive: 60 }, elements }] });
- const compiled = compileHyperframesDocument(sealComposition({ id: "animation", canvas: { width: 128, height: 128, clearColor: "#000000" }, tracks: [track] }), space);
- const html = materializeHyperframesHtml(compiled, artifact => artifact.resource === "res_font"
+ const compiled = compileHtmlProgram(sealComposition({ id: "animation", canvas: { width: 128, height: 128, clearColor: "#000000" }, tracks: [track] }), space);
+ const html = materializeHtmlProgram(compiled, artifact => artifact.resource === "res_font"
? "data:font/woff2;base64,AA==" : "data:image/png;base64,AA==");
- const browser = await puppeteer.launch({ executablePath: browserExecutablePath({}), headless: true, args: ["--no-sandbox"] });
+ const browser = await puppeteer.launch({ executablePath: testBrowser(), headless: true, args: ["--no-sandbox"] });
try {
const page = await browser.newPage();
// Glyph appearance is irrelevant to this element-opacity test; the tiny invalid font
// settles immediately. Font loading and painted text have separate integration coverage.
await page.setContent(html);
const valuesAt = async (target: typeof page, frame: number) => await target.evaluate(async frame => {
- const waits: Promise<void>[] = [];
- window.dispatchEvent(new CustomEvent("hf-seek", { detail: {
- time: frame / 30,
- waitUntil(value: Promise<void>) { waits.push(value); },
- } }));
- await Promise.all(waits);
- const timelines = (window as typeof window & { __timelines?: Record<string, { totalTime(time: number): void }> }).__timelines;
- timelines?.animation?.totalTime(frame / 30);
+ await (window as typeof window & {
+ __hypitFrameProgram: { applyFrame(frame: number): Promise<void> };
+ }).__hypitFrameProgram.applyFrame(frame);
const roots = ["flow", "path", "mask-image"].map(id => Number(getComputedStyle(document.querySelector(`[data-hypit-element-id="${id}"]`)!).opacity));
const units = ["flow", "path"].map(id => Number(getComputedStyle(document.querySelector(`[data-hypit-element-id="${id}"] [data-hypit-text-unit-grapheme="0"]`)!).opacity));
return { roots, units };
diff --git a/packages/provider-hyperframes-local/test/weighted-capacity.test.ts b/packages/provider-html-local/test/weighted-capacity.test.ts
similarity index 100%
rename from packages/provider-hyperframes-local/test/weighted-capacity.test.ts
rename to packages/provider-html-local/test/weighted-capacity.test.ts
diff --git a/packages/provider-hyperframes-local/README.md b/packages/provider-hyperframes-local/README.md
deleted file mode 100644
index 29664226..00000000
--- a/packages/provider-hyperframes-local/README.md
+++ /dev/null
@@ -1,316 +0,0 @@
-# @hypit/provider-hyperframes-local
-
-Trusted local Provider for `@hypit/render-hyperframes@1#render-visual` and `#render-frames`. It stages the
-Resource dependencies declared by a `HyperframesDocument`, renders a silent MP4 with the
-HyperFrames engine, probes the bytes, and returns a verified `RenderedVisual`. Before capturing a typed
-Surface it decodes the exact bytes and checks declared dimensions, still/frame timing, SDR/sRGB and
-opaque/straight-alpha facts. These checks validate the typed rendering input; they do not create
-content identity or hidden output metadata.
-
-`render-frames` uses the same staging, source-frame mapping, readiness and opaque PNG capture as
-video export, returning the PNGs before encoding. It accepts a compiled document or a materialized
-HTML project. For selected frames it merges only their required source-frame windows; continuous
-windows decode sequentially inside a render-local working set. A complete batch shares one staged
-project and browser lifetime.
-The existing browser selection, explicit preparation, worker settings and cancellation apply.
-Document staging runs at most `artifactStagingConcurrency` complete Artifact lifecycles at once
-(4 by default). A lifecycle includes Resource Store reading, local-file writing and typed Surface
-inspection. The limit is local to one render and is independent of Chrome workers and Runtime request
-capacity. The first failure stops new Artifact claims; already-started lifecycles settle before the
-temporary directory can be removed. Existing HTML-project staging is already sequential.
-For a compiled Document, the Provider intersects the whole continuous range or sparse frame list
-with each Artifact's compiler-owned usage proof before claiming bytes. Direct image, video and typed
-Surface dependencies outside the selection are not opened or written. `always` dependencies—such as
-document fonts and opaque Browser Program resources—remain conservative. This selection happens once
-per render; every Chrome worker shares the same staged project and may still evaluate any requested
-frame in any order. Materialized HTML-project input has no such structural proof and remains complete.
-`maxRenderedBytes` bounds the total returned PNG bytes, or the encoded MP4 for a video request.
-For MP4 requests, completed PNGs are submitted individually to one ordered FFmpeg pipe instead of
-being retained as a complete frame directory. `maxPendingFrameBytes` (256 MiB by default) bounds
-completed out-of-order PNGs waiting for an earlier frame. When that budget is full, the affected
-worker stops claiming work. The exact next frame may always pass, and one otherwise-empty waiting
-set accepts a single oversized PNG, so the byte budget cannot deadlock ordered progress. This limit
-does not change quality, drop frames, reduce an explicit worker count, or bound the encoded artifact.
-`maxDecodedSourceBytes` (1 GiB by default) separately bounds decoded source PNGs retained for browser
-injection. A screenshot leases only the exact source frames it is currently reading and releases
-them before its output PNG can wait on the ordered encoder. Missing contiguous frames are grouped into
-FFmpeg `image2pipe` jobs of at most 16 frames; each PNG is parsed and admitted as soon as it is complete instead of
-waiting for the whole extraction. Remaining, not-yet-consumed frames in each live Worker's short batch
-are soft preferences: they are reused when space permits, never displace another live soft preference,
-and remain evictable for an exact screenshot requirement. Admission uses each completed PNG's actual
-byte size. One exact screenshot requirement may occupy the set alone when it exceeds the budget. The
-reported peak covers resident decoded PNG files; one bounded PNG may additionally be in the decoder
-pipe/parser. It does not cover source assets, Chrome memory or FFmpeg's internal buffers.
-Resident accounting is an attempt-local weighted-capacity lease that knows only integer units; source
-identity, frame choice, eviction and prefetch remain in the SourceFrameStore. It is not Runtime capacity
-and is never shared across renders.
-`render-frames` has its own capability binding; it does not inherit a `render-visual` binding.
-For immediate CLI invocation, the host calls the handler directly: Build admission reservations do
-not coordinate separate CLI processes. Worker limits still bound browsers inside each invocation.
-
-Normalized transparent videos displayed by Media or project components use the ordinary video path.
-The engine decodes them to PNG frames with alpha, then Chrome blends them with lower layers and
-the authored Canvas background. Final frames use fast PNG encoding after Chrome has composited
-the image onto an opaque canvas (black beneath the authored background). This trades intermediate
-compression effort for speed without JPEG frame compression. Source alpha, CSS filters, canvas and
-WebGL remain part of the browser composition. The returned MP4 contains the completed composition.
-
-Runtime configuration separates work size from shared capacity:
-
-- `defaultConcurrency` limits whole render requests admitted by the Endpoint's Runtime capacity resource.
-- Optional `browserCapacity` limits Chrome slots shared by all render Needs in the same `pool`.
- Each Need reserves its fixed count or automatic ceiling atomically with the whole-request slot.
- An explicit count larger than this budget reports a configuration error. Auto fits its ceiling
- to the shared budget before admission.
- Both reservations last for the whole Need, including preparation and final encoding. Closing one
- Chrome early does not release part of that reservation. Without `browserCapacity`, admission uses
- the whole-request limit alone.
-- `workers` controls independent Chrome processes inside one admitted render. Explicit counts are
- honored, capped only by selected frame count. `auto` starts below its ceiling, then compares useful
- capture batches before adding another browser. Insufficient benefit or falling throughput retires
- surplus browsers between batches. Completed frames are retained; there is no calibration render.
-- Optional `maxWorkers` sets the automatic ceiling. Without it, the Provider leaves two CPU slots
- and half the machine/container memory for other work, budgeting about 1.5 GiB per Chrome process.
- Auto also caps the reservation to the number of roughly one-second batches in the selected range.
-
-The Runtime Profile configures these controls through the Provider because they are deployment policy.
-The automatic ceiling is fixed at activation, and range sizing is identical in admission and execution.
-Actual concurrency adapts inside that reservation; it is not a machine-wide history or performance database. It never
-renders program audio; `@hypit/provider-media-local` separately prepares `TimelineAudio` and muxes
-the final media.
-
-For a Runtime Profile, place `pool` on the Endpoint entry and these Provider settings inside
-`config`. This is an illustrative entry to merge into the Profile's existing `endpoints`:
-
-```json
-"hyperframes.local": {
- "use": "@hypit/provider-hyperframes-local",
- "pool": "local-render",
- "config": {
- "workers": 4,
- "defaultConcurrency": 2,
- "browserCapacity": 6
- }
-}
-```
-
-This configuration admits one 4-worker request at a time under its 6-browser budget even though
-the whole-request limit is 2. Two 4-worker requests would need 8 browser slots. Choose budgets from
-the actual machine and shared workloads; the example is not an automatic tuning recommendation.
-New Builds use the edited Provider configuration; active Builds retain their selected configuration.
-Restart Studio if its existing session needs to load the edited Profile.
-
-`browserGpu` picks Chrome's rasterizer and defaults to `hardware`. Set `software` without a usable
-GPU, or `auto` to let the engine decide. Capture uses screenshots and independent browser processes;
-the CLI's automatic worker and drawElement policies do not override the count. The opaque screenshot
-adapter uses the engine's public session, video injector and page seek protocol plus Chrome CDP.
-It waits for seek completion, dynamic images/fonts and the page compositor before capturing PNGs.
-Image readiness includes CSS class and pseudo-element images, CSS masks and SVG images. A failed
-image decode reports its URL instead of producing a successful frame with missing media. Failed
-declared fonts also fail capture instead of silently leaving fallback glyphs in the output.
-When a page publishes capture roots, initial computed-style and image discovery is limited to those
-roots. Descendant changes stay local, while an ancestor class/id change is routed back to the roots
-it can affect. A real CSSOM stylesheet edit remains an explicit whole-document fallback because an
-opaque rule can select anything. Pages that publish no roots, including arbitrary materialized HTML,
-retain whole-document discovery.
-The pinned engine couples its PNG session setup to transparent export, so this adapter initializes
-an opaque session and chooses PNG separately at capture. It does not patch engine methods or files.
-
-The Runtime Adapter declares one managed browser program. Prepare it explicitly:
-
-```sh
-hypit programs prepare --runtime ./hypit.runtime.json --endpoint hyperframes.local
-```
-
-Use the instance name from the Profile. `runtime up` also prepares it and starts the Runtime Worker.
-The Provider's `package.json` declares its recommended Chrome Headless Shell version in
-`hypit.renderBrowser.version`, alongside the engine dependency used to test that release. The
-installer consumes that declaration; it does not have a browser version constant or fetch a
-"latest" channel. `config.browserVersion` explicitly selects another exact four-part version.
-Changing the recommendation belongs to a Provider release and requires real rendering tests; a
-Puppeteer recommendation alone is not a HyperFrames compatibility guarantee.
-
-The default cache is `~/.cache/hyperframes/chrome`; `config.browserCacheDirectory` selects another
-location. Only the selected version is used, regardless of other cached or system browsers.
-Projects sharing this cache use the existing ManagedProgram preparation lock/logs under
-`.hypit-render-program`. Readiness comes from the executable and its reported version, not a receipt.
-Explicit preparation reuses a healthy installation or repairs only the selected managed version.
-A failed download reports failure without selecting another version or browser.
-
-`config.browserDownloadBaseUrl` selects a Chrome for Testing archive mirror for explicit preparation.
-It is an absolute HTTP(S) base URL, without credentials, a query or a fragment. The browser library
-appends the selected version, platform and archive name; the mirror must serve that same layout.
-For example, a base of `https://mirror.example/chrome-for-testing` serves archives beneath
-`<base>/<version>/<platform>/chrome-headless-shell-<platform>.zip`. Choose a source maintained by
-the user or organization; this Provider does not keep a mirror list or choose one by region.
-Omitting the setting uses the browser library's official Chrome for Testing source. A configured
-source replaces it: failed transfers or invalid archives fail preparation without trying the official
-source or another mirror. Normal HTTP redirects supplied by the selected server are handled by the
-download library. Preparation displays the complete archive URL, version and destination before
-download. An npm registry setting does not redirect this binary download.
-
-The download source only determines where missing installation bytes come from. It does not change
-the executable selection, and changing it does not invalidate a healthy cached version. No source
-receipt is stored. To install into an empty location, explicitly choose `browserCacheDirectory`.
-
-`config.chromePath` selects a user-managed Chrome/Chromium executable. It cannot be combined with
-`browserVersion` or `browserDownloadBaseUrl`; invalid combinations fail instead of assigning precedence. Relative paths resolve
-from the Runtime data root, as does `browserCacheDirectory`. The Profile's `dataRoot` itself resolves
-relative to the Profile file. This mode never downloads or repairs a browser. Its version remains
-under the user's control, including system-browser auto-updates. `HYPERFRAMES_BROWSER_PATH` and
-`PRODUCER_HEADLESS_SHELL_PATH` do not select browsers in this Provider; configure `chromePath`.
-On platforms without a supported managed download, explicitly select an installed browser.
-
-`doctor` displays the selected path and its source, and only inspects it. Build preflight, rendering
-and previews never install a browser. `programs prepare`, `programs up` and `runtime up` display the selected managed
-version, installation location and download URL before running preparation. The probe runs `--version` and checks
-FFmpeg/FFprobe; it does not promise GPU or page compatibility. Capture receives that same selected
-path as the engine's `chromePath`, including its GPU probe. New Builds read current Endpoint
-configuration and project implementation; active Builds keep their selected configuration. A
-Distribution update or change to the Worker's inherited environment requires an explicit Worker
-restart when active work permits. Ordinary Profile edits do not require restarting every process.
-
-The Provider's `hypit.dependencyInstallEnv` disables Puppeteer's browser download while preparing its
-engine/producer npm dependencies. The repository `.puppeteerrc.cjs` does the same for checkout installs.
-No browser postinstall allowlist is required. The former `hyperframesCliPath` option is removed.
-
-The same executor is exported for callers with an already compiled document:
-
-```ts
-import { renderHyperframesVisual } from "@hypit/provider-hyperframes-local";
-
-const visual = await renderHyperframesVisual(
- { document, range: { startFrame: 240, endFrameExclusive: 360 } },
- { resources, workers: 4, onProgress: (event) => console.log(event) },
-);
-```
-
-Omit `range` for the complete document. Ranges are zero-based and half-open on the original
-programme clock. At 30 fps, `[240, 360)` returns 120 frames covering seconds 8–12.
-`onProgress` reports resource staging, source decoding, the requested range, per-worker frame counts, browser PIDs,
-encoding, storage and elapsed time to direct executor callers. The Provider reduces parallel worker
-events to a single phase and aggregate count through `context.reportProgress`. CLI status and follow
-display that activity without `--verbose`. Counter writes are coalesced to about once per second;
-phase changes and completed counts are reported promptly. Local activity belongs to the running
-Command, not a remote Operation or a repeatedly rewritten Result manifest.
-`processTimeoutMs` defaults to 30 minutes and starts one deadline before resource preparation. It
-covers resource reads, Surface validation, rendering and output storage. `signal` can end the same
-execution earlier. ResourceStore I/O and Surface probes receive the cancellation signal; a custom
-ResourceStore must implement the port's cancellation behavior, including streaming reads and writes.
-
-Browser launch, source extraction, capture and encoding run in one disposable child process per
-render. After successful capture closes its resources, the child sends its completion message,
-flushes that message and disconnects IPC so it can exit normally. The owner awaits exit and drains
-diagnostics before returning. Normal completion does not enumerate or forcibly terminate processes.
-On failure, cleanup may be incomplete: the child reports the error and keeps IPC open while the owner
-discovers and terminates the remaining process tree, before it can become orphaned.
-The capture child also installs synchronous exit cleanup before loading the engine. Early
-`process.exit()`, uncaught exceptions, and catchable `SIGINT`/`SIGTERM` exits stop descendants
-while their owner still exists, even if browser initialization never returned a session.
-Successful resource closure removes this exit handler. No historical browser PID list is retained.
-
-Uncatchable termination (`SIGKILL`, native crashes, or OS termination on Windows) cannot run that
-cleanup. The owner reports the termination and cannot confirm descendant cleanup; it never searches
-by an already-exited root PID. If an orphan keeps the output pipes open, the owner closes its pipe
-ends after five seconds so the failed invocation can settle. Guaranteed cleanup after an OS hard
-kill requires containment supplied by that deployment (for example a process job or container);
-this local Node implementation does not provide that guarantee.
-
-At cancellation the child receives a stop request and has up to five seconds to clean up. A child
-that remains after cancellation or its completion message is forcibly terminated along with its discovered
-process tree, including Chrome's separate process groups. Cleanup problems are reported through the
-existing diagnostic callback; they do not discard a render already reported as completed. If process
-enumeration fails, the owner still terminates the direct child but cannot confirm descendant cleanup.
-This also covers engine calls that do not accept a signal. The deadline initiates shutdown; the call
-may spend additional time closing resources. Completed Outputs in the Build remain available for a
-new Run and Build.
-
-Deployments may additionally set `initializationTimeoutMs` or `frameTimeoutMs` when they have a
-measured stage deadline. Initialization here means initializing an already created browser session;
-Chrome launch precedes it. Stage deadlines are otherwise unset, allowing a busy machine to spend
-more of the shared render budget on a slow initialization or frame.
-An explicit stage-timeout error names the worker and stage/frame, aborts sibling workers and awaits
-cleanup. A completed worker closes its Chrome immediately.
-
-One call stages the HTML and every declared asset once. Typed Surface inspection reads the completed
-staged file directly, without retaining its chunks, assembling another whole-file buffer, or writing
-a second temporary copy. The caller keeps that file until inspection and capture have settled.
-Typed Surface validation includes a complete decoded-frame count, even for a short render interval.
-Capture probes the dimensions of source media needed by the requested range, but does not decode
-the range before launching browsers. Each Worker initializes its own page, then takes short
-contiguous output-frame batches from the render's in-memory queue. Before one screenshot it leases that frame's exact source inputs;
-missing inputs and live unconsumed batch preferences are merged into bounded continuous decode windows.
-One FFmpeg process streams multiple PNGs for such a window, while the render-local store applies
-backpressure and actual-byte admission between frames.
-Decoded source PNGs are shared by all workers in this call. A free worker can continue with another
-batch instead of waiting for a worker assigned a more expensive passage. Batches span at
-most about one second and preserve the original absolute frame times. Output numbering starts at
-zero. Every completed output PNG is submitted immediately; a render-local ordered sink writes each
-consecutive frame to FFmpeg and releases it, while later frames wait within the configured byte
-budget. H.264 encoding overlaps capture before final verification. This division is internal to one
-render call; it does not create or resume Builds. Extra workers help only while aggregate throughput
-improves. Staging, validation, source extraction and final verification still contribute their own cost.
-
-The requested continuous range or sparse frame list is compacted into ordered half-open spans and
-injected into every page before compiled scripts run. HyperFrames uses this render-local selection
-to skip Browser Program setup, browser Animation materialization, Terminal Text static layout and
-visibility-span indexing for Presents that cannot contribute. All Workers receive the same absolute
-selection because batches may move between them; no Worker order or previous-frame cursor is part
-of the result. Compiler-owned direct media URLs stay inert during parsing and are activated only
-inside intersecting Present roots. The compiled page makes other Present roots non-painting, removes
-any remaining direct media URL attributes, detaches them from the live DOM and publishes only
-selected roots plus shared document definitions to opaque readiness. In a 200-unrelated-node browser
-probe, this reduced initial computed-style reads
-from at least 600 for an unscoped document to at most 6 for one selected root. These counts describe
-the exercised DOM shape, not a machine-wide timing promise.
-
-The complete staged HTML is still prepared, while declared Artifacts with a compiler-proven disjoint
-frame usage are omitted from byte staging. Selection-gated URL activation also avoids browser requests
-for that unselected compiler-owned media; arbitrary HTML/CSS, Browser Program resources and
-document-level fonts remain conservative. The pinned engine's
-document-level animation discovery now sees only selected live Present roots and document-level
-definitions. Font readiness remains a browser-wide settlement
-boundary, although fonts used only by hidden unselected Presents are no longer demanded in the
-compiled-page path. Arbitrary HTML without the page-owned root protocol retains safe full-document
-resource discovery. This is therefore execution-local loading/readiness projection rather than a
-partial-document rewrite or a claim that every browser startup cost is proportional to the selection.
-
-Each call has its own temporary directory, local server port and Chrome processes. Separate renders
-do not share staged files or decoded PNGs. Exact compiler sampling markers retain loops, holds and
-fractional playback rates. There is no SVML rewrite, intermediate cut MP4 or repeat normalization.
-Already compiled video documents need the current compiler's frame markers.
-
-`ffmpegPath` selects both source decoding and final H.264 encoding; `ffprobePath` selects source,
-output and typed Surface inspection. Bare commands resolve through PATH. The capture child passes
-these selected executables to the engine's public binary overrides; inherited
-`HYPERFRAMES_FFMPEG_PATH` / `HYPERFRAMES_FFPROBE_PATH` cannot select a different decoding toolchain.
-`nodePath` selects the managed
-browser installer's Node executable. Capture uses the current Node process's executable.
-The requested frame range travels in the Model's Need; browser paths stay in the Provider.
-
-```ts
-import { createLocalHyperframesProvider } from "@hypit/provider-hyperframes-local";
-
-const provider = createLocalHyperframesProvider({
- pool: "local-render",
- workers: 4,
- defaultConcurrency: 2,
- browserCapacity: 6,
-});
-```
-
-Two instances in `local-render`, configured with 4 and 2 workers and identical capacity limits, can
-render together. With `browserCapacity: 4`, the second waits. Coordination applies to Builds sharing
-the same Runtime Execution Store; the pool name alone does not coordinate separate stores or machines.
-Direct `renderHyperframesVisual()` calls do not enter Runtime's shared admission system.
-
-The current package executes trusted official code in a local process. It is not a sandbox for
-untrusted documents or community renderer implementations.
-
-Provider calls forward renderer diagnostics through `context.reportDiagnostic`. The initial record
-states the frame count, worker policy/ceiling, capture path, quality, GPU mode and selected encoder.
-Phase timings, concurrency changes and per-worker seek/preparation/PNG totals are recorded once
-per phase, decision or finished worker. Disposable capture-process
-stdout/stderr are streamed as diagnostics and drained before the call returns; existing output limits
-still apply. Phase changes cover preparation, decoding, browser startup, capture, encoding and storage.
-`hypit logs <build-id>` retains those records after temporary rendering files have been removed.
diff --git a/packages/provider-hyperframes-local/package.json b/packages/provider-hyperframes-local/package.json
deleted file mode 100644
index e14bd8f1..00000000
--- a/packages/provider-hyperframes-local/package.json
+++ /dev/null
@@ -1,44 +0,0 @@
-{
- "name": "@hypit/provider-hyperframes-local",
- "version": "0.0.0-dev",
- "license": "SEE LICENSE IN LICENSE",
- "private": true,
- "type": "module",
- "exports": {
- ".": "./src/index.ts"
- },
- "hypit": {
- "activation": "./src/activation.ts",
- "renderBrowser": {
- "version": "152.0.7928.2"
- },
- "dependencyInstallEnv": {
- "@hyperframes/engine": {
- "PUPPETEER_SKIP_DOWNLOAD": "true"
- },
- "@hyperframes/producer": {
- "PUPPETEER_SKIP_DOWNLOAD": "true"
- }
- }
- },
- "dependencies": {
- "@hyperframes/engine": "0.7.101",
- "@hyperframes/producer": "0.7.101",
- "@hypit/endpoint-kit": "workspace:*",
- "@hypit/hyperframes": "workspace:*",
- "@hypit/media": "workspace:*",
- "@hypit/media-execution": "workspace:*",
- "@hypit/protocol": "workspace:*",
- "@hypit/render-hyperframes": "workspace:*",
- "@hypit/runtime": "workspace:*",
- "@hypit/runtime-host-node": "workspace:*",
- "@hypit/runtime-kit": "workspace:*",
- "@puppeteer/browsers": "3.2.2",
- "tsx": "4.21.0"
- },
- "devDependencies": {
- "@hypit/composition": "workspace:*",
- "@hypit/driver-node": "workspace:*",
- "@hypit/timeline": "workspace:*"
- }
-}
diff --git a/packages/provider-hyperframes-local/src/browser-install.ts b/packages/provider-hyperframes-local/src/browser-install.ts
deleted file mode 100644
index 02b57d6f..00000000
--- a/packages/provider-hyperframes-local/src/browser-install.ts
+++ /dev/null
@@ -1,5 +0,0 @@
-import { installRenderBrowser } from "./browser.js";
-
-const [cacheDir, version, baseUrl] = process.argv.slice(2);
-if (process.argv.length < 4 || process.argv.length > 5 || !cacheDir || !version) throw new Error("Expected the render browser cache directory, exact version and optional archive base URL");
-await installRenderBrowser(cacheDir, version, baseUrl);
diff --git a/packages/provider-hyperframes-local/src/capture-bootstrap.ts b/packages/provider-hyperframes-local/src/capture-bootstrap.ts
deleted file mode 100644
index 01f18590..00000000
--- a/packages/provider-hyperframes-local/src/capture-bootstrap.ts
+++ /dev/null
@@ -1,23 +0,0 @@
-/**
- * Preloaded into capture and browser-install processes, which never enter `bin/hypit.mjs`.
- *
- * `module.registerHooks` is process-local, so the resolver the launcher installs does not
- * reach a child that Node starts directly. This registers the same resolution environment
- * in the child, so its view of `@hypit/*` and of the machine packages those modules declare
- * is identical to its parent's.
- *
- * Only relative paths can be used here: no hook exists yet, and a Distribution ships its
- * package sources without any `node_modules` link between them.
- */
-import { resolve } from "node:path";
-
-// This preload belongs to the Provider the parent actually loaded. Inherited shell
-// hints must not redirect its dependencies to a different Hypit installation.
-const distributionRoot = resolve(import.meta.dirname, "../../..");
-
-const { installDistributionPackageResolution, installExternalPackageResolution } =
- await import("../../package-loader-node/src/distribution-resolution.js");
-installDistributionPackageResolution([distributionRoot]);
-
-const { hypitHostPackageRoot } = await import("../../runtime-host-node/src/index.js");
-installExternalPackageResolution([hypitHostPackageRoot()]);
diff --git a/packages/provider-hyperframes-local/src/index.ts b/packages/provider-hyperframes-local/src/index.ts
deleted file mode 100644
index 85c1fc91..00000000
--- a/packages/provider-hyperframes-local/src/index.ts
+++ /dev/null
@@ -1,10 +0,0 @@
-export { createLocalHyperframesProvider, localHyperframesProviderModuleRef } from "./provider.js";
-export type {
- CreateLocalHyperframesProviderOptions,
- HyperframesBrowserGpu,
- HyperframesQuality,
- HyperframesWorkers,
-} from "./provider.js";
-
-export { renderHyperframesVisual, renderHyperframesFrames } from "./render.js";
-export type { RenderHyperframesVisualOptions, HyperframesRenderProgress } from "./render.js";
diff --git a/packages/render-hyperframes/README.md b/packages/render-hyperframes/README.md
deleted file mode 100644
index 263d1ba8..00000000
--- a/packages/render-hyperframes/README.md
+++ /dev/null
@@ -1,67 +0,0 @@
-# `@hypit/render-hyperframes`
-
-The Surface accepts `timeline={program.timeline}` and passes that Timeline directly to rendering.
-Its Fragment receives it as `timeline`; rendering works with partial, overlapping or absent
-semantic coverage through the same frame and audio pipeline.
-
-Explicit author and capability boundary for final HyperFrames video rendering.
-
-`@hypit/render-hyperframes@1#render-frames` captures an existing programme's selected frames.
-`hyperframesFramesRequest({ document, frames })` accepts a `HyperframesDocument` and strictly
-increasing original-frame indices. `{ project: { html, assets }, frames }` accepts already
-materialized HTML with its URL-addressed assets. The `Frames` result is a PNG `BlobRef[]` in request
-order; the request already owns the frame identities. Canvas and clock stay in the input.
-This capability requests picture capture only. File names, contact sheets and pagination belong to
-the caller. `hypit snapshot` invokes it immediately through a selected Profile; there is no Build
-or video encoding in that observation path.
-
-The package owns `<render:Video composition={...}/>` and lowers it to ordinary Operations that:
-
-1. compile the referenced `Composition` against the Timeline into a `HyperframesDocument`;
-2. request a silent, frame-exact `RenderedVisual`;
-3. compile every peer `AudioTrack` into one `AudioProgramPlan`;
-4. request an exact 48 kHz `TimelineAudio`;
-5. request one `MuxedMedia` from those two independently verified Products;
-6. expose the verified mux Artifact unchanged as a domain-neutral `BlobArtifact`.
-
-The package is not a renderer and contains no queue, credentials or deployment choice. A local
-HyperFrames process, a hosted endpoint or another conforming execution package may register a
-Provider for the exact visual capability. Media Providers independently realize audio rendering and
-mux. None parses SVML or decides which Composition to render. Every result is bound to the same
-Timeline and exact frame/sample domain before it can become a final video Record.
-
-The output does not carry copied duration or lineage metadata. It is an ordinary Resource-backed
-Blob and can therefore be connected directly to any later component that accepts Blob bytes. A
-consumer that needs stream or duration facts must request explicit media inspection.
-
-Core therefore sees three real byte-operation Needs, not one opaque mega-render. Frame workers,
-contiguous or interleaved chunks, retries and image-sequence assembly remain inside the selected
-visual Endpoint; clip decoding/mixing remains inside the audio Endpoint; container encoding remains
-inside the mux Endpoint. A single Provider package may implement all three locally, or a Runtime may
-bind them to separate compatible Endpoints. The author still sees one `<render:Video>` result.
-
-Film is not a dependency of this author meaning. Any package that produces the common Composition
-contract can feed the render Surface. Conversely, targeting Composition never demands this package;
-rendering exists only when the author declares and the Build targets the video output.
-
-`@hypit/provider-hyperframes-local` is the first concrete visual implementation. It stages the
-document's exact `BlobRef` dependencies, partitions the requested frame domain across
-configured Chrome workers, emits a silent MP4 and rejects output unless ffprobe proves one H.264
-stream with the declared canvas, rational frame rate and frame count.
-
-Select a contiguous interval using zero-based, half-open frame bounds:
-
-```xml
-<render:Video id="preview" composition={main.composition} timeline={speech.timeline}
- start-frame="240" end-frame-exclusive="360"/>
-```
-
-At 30 fps this renders seconds 8–12, with 120 output frames. Write both bounds, or omit both to
-render the whole programme. The HTML and animation clock remain unchanged. Visual and audio Needs
-receive the same range; mux consumes their selected outputs. `workers` belongs in the local
-Provider's Runtime configuration.
-
-In TypeScript, `hyperframesVisualRequest(document, { range })` constructs the visual request;
-`createRenderHyperframesFragment(true)` accepts a `MediaFrameRange` input and connects it to visual
-and audio requests. Provider support checks establish range support for other deployments. Selection limits
-final rendering work; it does not prune upstream generation dependencies.
diff --git a/packages/render-hyperframes/package.json b/packages/render-hyperframes/package.json
deleted file mode 100644
index 574d1ddb..00000000
--- a/packages/render-hyperframes/package.json
+++ /dev/null
@@ -1,32 +0,0 @@
-{
- "name": "@hypit/render-hyperframes",
- "version": "0.0.0-dev",
- "license": "SEE LICENSE IN LICENSE",
- "private": true,
- "type": "module",
- "exports": {
- ".": "./src/index.ts"
- },
- "hypit": {
- "activation": "./src/activation.ts"
- },
- "dependencies": {
- "@hypit/artifact": "workspace:*",
- "@hypit/component-kit": "workspace:*",
- "@hypit/composition": "workspace:*",
- "@hypit/elaborator": "workspace:*",
- "@hypit/hyperframes": "workspace:*",
- "@hypit/media": "workspace:*",
- "@hypit/media-pipeline": "workspace:*",
- "@hypit/protocol": "workspace:*",
- "@hypit/timeline": "workspace:*",
- "@hypit/markup": "workspace:*",
- "@hypit/temporal-markup": "workspace:*"
- },
- "devDependencies": {
- "@hypit/core": "workspace:*",
- "@hypit/driver-node": "workspace:*",
- "@hypit/svs": "workspace:*",
- "@hypit/validation": "workspace:*"
- }
-}
diff --git a/packages/render-hyperframes/src/activation.ts b/packages/render-hyperframes/src/activation.ts
deleted file mode 100644
index 8a826256..00000000
--- a/packages/render-hyperframes/src/activation.ts
+++ /dev/null
@@ -1,18 +0,0 @@
-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;
diff --git a/packages/render-hyperframes/src/component.ts b/packages/render-hyperframes/src/component.ts
deleted file mode 100644
index 6939facb..00000000
--- a/packages/render-hyperframes/src/component.ts
+++ /dev/null
@@ -1,47 +0,0 @@
-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 type { 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) {
- const request = specification.constraints as Partial<HyperframesVisualRequest>;
- if (request.document === undefined) return { fields: {}, references: {} };
- const { document, range } = request;
- const startFrame = range?.startFrame ?? 0;
- const endFrameExclusive = range?.endFrameExclusive ?? document.frameCount;
- return { fields: {
- width: [document.canvas.width], height: [document.canvas.height],
- startFrame: [startFrame], endFrameExclusive: [endFrameExclusive],
- frameRate: [`${document.frameRate.numerator}/${document.frameRate.denominator}`],
- }, references: {} };
- },
- })),
-} satisfies ComponentPackage;
-
-function inline(value: StoredValue, subject: string): unknown {
- if (value.kind !== "inline") throw new Error(`${subject} must be inline`);
- return value.value;
-}
diff --git a/packages/render-hyperframes/src/index.ts b/packages/render-hyperframes/src/index.ts
deleted file mode 100644
index 472f81ab..00000000
--- a/packages/render-hyperframes/src/index.ts
+++ /dev/null
@@ -1,9 +0,0 @@
-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";
-export { renderHyperframesTypes } from "./manifest.js";
-export { hyperframesFramesRequest, hyperframesFramesDomain, verifyHyperframesFramesRequest, verifyHyperframesFrames } from "./product.js";
-export type { HyperframesFramesRequest, HyperframesFrames } from "./product.js";
diff --git a/packages/render-hyperframes/src/manifest.ts b/packages/render-hyperframes/src/manifest.ts
deleted file mode 100644
index be423306..00000000
--- a/packages/render-hyperframes/src/manifest.ts
+++ /dev/null
@@ -1,105 +0,0 @@
-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 { timelineDependency } from "@hypit/timeline";
-import {
- hyperframesManifest,
- hyperframesModuleRef,
- hyperframesTypes,
-} from "@hypit/hyperframes";
-import type {
- CapabilityRef,
- ModuleManifest,
- ProducerRef,
- TypeRef,
-} 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" },
- renderFrames: { module: renderHyperframesModuleRef, name: "render-frames" },
-} satisfies Record<string, CapabilityRef>;
-export const renderHyperframesTypes = {
- frames: { module: renderHyperframesModuleRef, name: "Frames" },
-} satisfies Record<string, TypeRef>;
-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} timeline={speech.timeline}/>',
- notes: [
- "Supply id, composition and timeline. 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,
- timelineDependency,
- { module: hyperframesModuleRef },
- { module: mediaPipelineModuleRef },
- ],
- types: [{ name: renderHyperframesTypes.frames.name }],
- capabilities: [{
- name: renderHyperframesCapabilities.renderVisual.name,
- returns: mediaTypes.renderedVisual,
- }, { name: renderHyperframesCapabilities.renderFrames.name, returns: renderHyperframesTypes.frames }],
- 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,
- }],
- },
- ],
-};
diff --git a/packages/render-hyperframes/src/product.ts b/packages/render-hyperframes/src/product.ts
deleted file mode 100644
index 375ba3a6..00000000
--- a/packages/render-hyperframes/src/product.ts
+++ /dev/null
@@ -1,68 +0,0 @@
-import type { CanonicalValue } from "@hypit/protocol";
-import { assertHyperframesDocument, assertHyperframesHtmlProject, hyperframesHtmlDomain } from "@hypit/hyperframes";
-import type { HyperframesDocument, HyperframesHtmlProject } from "@hypit/hyperframes";
-import type { BlobRef } from "@hypit/protocol";
-import { isResourceId } from "@hypit/protocol";
-import { verifyMediaFrameRange } from "@hypit/media";
-import type { MediaFrameRange } from "@hypit/media";
-
-export type HyperframesVisualRequest = {
- readonly document: HyperframesDocument;
- readonly range?: MediaFrameRange;
-};
-
-/** Select original programme frames, in strictly increasing order. */
-export type HyperframesFramesRequest = ({ readonly document: HyperframesDocument } | { readonly project: HyperframesHtmlProject }) & {
- readonly frames: readonly number[];
-};
-/** PNG images in request order. The request already supplies each frame's identity. */
-export type HyperframesFrames = readonly BlobRef[];
-
-export function hyperframesFramesDomain(request: HyperframesFramesRequest) {
- return "document" in request ? request.document : hyperframesHtmlDomain(request.project.html);
-}
-
-export function verifyHyperframesFramesRequest(value: unknown): asserts value is HyperframesFramesRequest {
- if (!value || typeof value !== "object" || Array.isArray(value)
- || Object.keys(value).some(key => !["document", "project", "frames"].includes(key))
- || ("document" in value) === ("project" in value)) throw new Error("Frame request needs exactly one document or HTML project, and frames");
- const request = value as HyperframesFramesRequest;
- if ("document" in request) assertHyperframesDocument(request.document);
- else assertHyperframesHtmlProject(request.project);
- const { frameCount } = hyperframesFramesDomain(request);
- if (!Array.isArray(request.frames) || request.frames.length === 0 || request.frames.some((frame, index) =>
- !Number.isSafeInteger(frame) || frame < 0 || frame >= frameCount || (index > 0 && frame <= request.frames[index - 1]!))) {
- throw new Error(`Frames must be strictly increasing integers in [0, ${frameCount})`);
- }
-}
-
-export function hyperframesFramesRequest(request: HyperframesFramesRequest): CanonicalValue {
- verifyHyperframesFramesRequest(request);
- return request as unknown as CanonicalValue;
-}
-
-export function verifyHyperframesFrames(value: unknown): asserts value is HyperframesFrames {
- if (!Array.isArray(value) || value.length === 0 || value.some(blob => !blob || blob.kind !== "blob"
- || !isResourceId(blob.resource) || blob.mediaType !== "image/png" || !Number.isSafeInteger(blob.size) || blob.size <= 0)) {
- throw new Error("HyperFrames frames must be PNG BlobRefs in request order");
- }
-}
-
-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 }),
- };
-}
diff --git a/packages/transport-aws-lambda/README.md b/packages/transport-aws-lambda/README.md
deleted file mode 100644
index 0f6a8d2f..00000000
--- a/packages/transport-aws-lambda/README.md
+++ /dev/null
@@ -1,20 +0,0 @@
-# `@hypit/transport-aws-lambda`
-
-Low-level synchronous JSON invocation for Endpoint packages that execute work through AWS Lambda.
-It is deliberately not an Endpoint and declares no SVML capability.
-
-Endpoint-specific code owns:
-
-- the request/response schema;
-- whether one call completes work or returns a remote checkpoint;
-- conversion into `EndpointOutcome`;
-- artifact locations and intrinsic result validation;
-- the function name, version/alias and retry semantics included in Endpoint configuration identity.
-
-The transport always uses `RequestResponse`. Lambda `Event` invocation has its own at-least-once
-queue and no immediate result/checkpoint, so treating it as an asynchronous Hypit Endpoint would be
-misleading. An Endpoint may invoke a coordinator Lambda synchronously; that coordinator can submit
-long work and return a checkpoint which the Endpoint later polls through another synchronous call.
-
-AWS authentication uses the SDK credential chain or an injected trusted client. Large media belongs
-in ResourceStore; JSON payloads are bounded by Lambda's synchronous payload limit.
diff --git a/packages/transport-aws-lambda/package.json b/packages/transport-aws-lambda/package.json
deleted file mode 100644
index f9a75eef..00000000
--- a/packages/transport-aws-lambda/package.json
+++ /dev/null
@@ -1,14 +0,0 @@
-{
- "name": "@hypit/transport-aws-lambda",
- "version": "0.0.0-dev",
- "license": "SEE LICENSE IN LICENSE",
- "private": true,
- "type": "module",
- "exports": {
- ".": "./src/index.ts"
- },
- "dependencies": {
- "@aws-sdk/client-lambda": "3.1103.0",
- "@hypit/protocol": "workspace:*"
- }
-}
diff --git a/packages/transport-aws-lambda/src/index.ts b/packages/transport-aws-lambda/src/index.ts
deleted file mode 100644
index 22048a5d..00000000
--- a/packages/transport-aws-lambda/src/index.ts
+++ /dev/null
@@ -1,131 +0,0 @@
-import {
- InvokeCommand,
- LambdaClient,
-} from "@aws-sdk/client-lambda";
-import type {
- LambdaClientConfig,
-} from "@aws-sdk/client-lambda";
-import { canonicalize } from "@hypit/protocol";
-import type { CanonicalValue } from "@hypit/protocol";
-
-/** One canonical JSON exchange; callers may inject any structurally compatible transport. */
-export interface JsonInvoker {
- invoke(request: CanonicalValue, options?: { readonly signal?: AbortSignal }): Promise<CanonicalValue>;
-}
-
-export type LambdaInvocationInput = {
- readonly functionName: string;
- readonly payload: Uint8Array;
- readonly qualifier?: string;
- readonly tenantId?: string;
-};
-
-export type LambdaInvocationOutput = {
- readonly statusCode?: number;
- readonly functionError?: string;
- readonly payload?: Uint8Array;
-};
-
-export type LambdaInvocationClient = {
- invoke(input: LambdaInvocationInput, signal?: AbortSignal): Promise<LambdaInvocationOutput>;
-};
-
-export type AwsLambdaJsonInvokerOptions = {
- readonly functionName: string;
- readonly qualifier?: string;
- readonly tenantId?: string;
- readonly region?: string;
- readonly endpoint?: string;
- readonly maxPayloadBytes?: number;
- /** Injection point for tests and specially configured trusted AWS clients. */
- readonly client?: LambdaInvocationClient;
-};
-
-function assert(condition: unknown, message: string): asserts condition {
- if (!condition) throw new Error(message);
-}
-
-function positiveInteger(value: number, subject: string): number {
- assert(Number.isSafeInteger(value) && value > 0, `${subject} must be a positive safe integer`);
- return value;
-}
-
-function decode(bytes: Uint8Array): string {
- return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
-}
-
-class AwsSdkLambdaInvocationClient implements LambdaInvocationClient {
- readonly #client: LambdaClient;
-
- constructor(config: LambdaClientConfig = {}) {
- this.#client = new LambdaClient(config);
- }
-
- async invoke(input: LambdaInvocationInput, signal?: AbortSignal): Promise<LambdaInvocationOutput> {
- const response = await this.#client.send(new InvokeCommand({
- FunctionName: input.functionName,
- InvocationType: "RequestResponse",
- Payload: input.payload,
- ...(input.qualifier === undefined ? {} : { Qualifier: input.qualifier }),
- ...(input.tenantId === undefined ? {} : { TenantId: input.tenantId }),
- }), signal === undefined ? {} : { abortSignal: signal });
- return {
- ...(response.StatusCode === undefined ? {} : { statusCode: response.StatusCode }),
- ...(response.FunctionError === undefined ? {} : { functionError: response.FunctionError }),
- ...(response.Payload === undefined ? {} : { payload: Uint8Array.from(response.Payload) }),
- };
- }
-}
-
-/**
- * Synchronous JSON transport. Endpoint packages still own request shape and outcomes.
- */
-export class AwsLambdaJsonInvoker implements JsonInvoker {
- readonly #client: LambdaInvocationClient;
- readonly #functionName: string;
- readonly #qualifier: string | undefined;
- readonly #tenantId: string | undefined;
- readonly #maxPayloadBytes: number;
-
- constructor(options: AwsLambdaJsonInvokerOptions) {
- assert(options.functionName.trim().length > 0, "Lambda functionName must not be empty");
- if (options.qualifier !== undefined) assert(options.qualifier.trim().length > 0, "Lambda qualifier must not be empty");
- if (options.tenantId !== undefined) assert(options.tenantId.trim().length > 0, "Lambda tenantId must not be empty");
- this.#functionName = options.functionName;
- this.#qualifier = options.qualifier;
- this.#tenantId = options.tenantId;
- this.#maxPayloadBytes = positiveInteger(options.maxPayloadBytes ?? 6 * 1024 * 1024, "maxPayloadBytes");
- this.#client = options.client ?? new AwsSdkLambdaInvocationClient({
- ...(options.region === undefined ? {} : { region: options.region }),
- ...(options.endpoint === undefined ? {} : { endpoint: options.endpoint }),
- });
- }
-
- async invoke(
- request: CanonicalValue,
- options: { readonly signal?: AbortSignal } = {},
- ): Promise<CanonicalValue> {
- const payload = new TextEncoder().encode(JSON.stringify(canonicalize(request)));
- assert(payload.byteLength <= this.#maxPayloadBytes,
- `Lambda JSON request is ${payload.byteLength} bytes, over limit ${this.#maxPayloadBytes}`);
- const response = await this.#client.invoke({
- functionName: this.#functionName,
- payload,
- ...(this.#qualifier === undefined ? {} : { qualifier: this.#qualifier }),
- ...(this.#tenantId === undefined ? {} : { tenantId: this.#tenantId }),
- }, options.signal);
- if (response.statusCode !== 200) {
- throw new Error(`Lambda ${this.#functionName} returned invocation status ${response.statusCode ?? "unknown"}`);
- }
- const responsePayload = response.payload ?? new Uint8Array();
- assert(responsePayload.byteLength <= this.#maxPayloadBytes,
- `Lambda JSON response is ${responsePayload.byteLength} bytes, over limit ${this.#maxPayloadBytes}`);
- const text = decode(responsePayload);
- if (response.functionError !== undefined) {
- // Function payloads may contain deployment secrets; do not copy them into framework errors.
- throw new Error(`Lambda ${this.#functionName} failed (${response.functionError})`);
- }
- assert(text.length > 0, `Lambda ${this.#functionName} returned an empty JSON response`);
- return canonicalize(JSON.parse(text));
- }
-}
diff --git a/packages/transport-aws-lambda/test/invoker.test.ts b/packages/transport-aws-lambda/test/invoker.test.ts
deleted file mode 100644
index 9ddad506..00000000
--- a/packages/transport-aws-lambda/test/invoker.test.ts
+++ /dev/null
@@ -1,58 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-
-import {
- AwsLambdaJsonInvoker,
-} from "@hypit/transport-aws-lambda";
-import type { LambdaInvocationClient } from "@hypit/transport-aws-lambda";
-
-test("Lambda transport uses synchronous JSON and leaves Endpoint semantics to its caller", async () => {
- let invocation: Parameters<LambdaInvocationClient["invoke"]>[0] | undefined;
- const client: LambdaInvocationClient = {
- async invoke(input) {
- invocation = input;
- const request = JSON.parse(new TextDecoder().decode(input.payload));
- return {
- statusCode: 200,
- payload: new TextEncoder().encode(JSON.stringify({ accepted: request.job })),
- };
- },
- };
- const transport = new AwsLambdaJsonInvoker({
- functionName: "whisperx-dev",
- qualifier: "live",
- client,
- });
- assert.deepEqual(await transport.invoke({ job: "operation:1" }), { accepted: "operation:1" });
- assert.equal(invocation?.functionName, "whisperx-dev");
- assert.equal(invocation?.qualifier, "live");
-});
-
-test("Lambda function errors and invalid JSON responses fail at the transport boundary", async () => {
- const failed = new AwsLambdaJsonInvoker({
- functionName: "failed",
- client: {
- async invoke() {
- return {
- statusCode: 200,
- functionError: "Unhandled",
- payload: new TextEncoder().encode('{"message":"boom"}'),
- };
- },
- },
- });
- await assert.rejects(failed.invoke({}), /failed \(Unhandled\)/u);
-
- const invalid = new AwsLambdaJsonInvoker({
- functionName: "invalid",
- client: {
- async invoke() {
- return {
- statusCode: 200,
- payload: new TextEncoder().encode('{"value":'),
- };
- },
- },
- });
- await assert.rejects(invalid.invoke({}), /JSON/u);
-});
diff --git a/packages/visual-ir/README.md b/packages/visual-ir/README.md
deleted file mode 100644
index 408e0a79..00000000
--- a/packages/visual-ir/README.md
+++ /dev/null
@@ -1,36 +0,0 @@
-# `@hypit/visual-ir`
-
-The terminal visual vocabulary includes structural elements and explicit renderer-program payloads.
-HyperFrames renders both structural elements and its browser program format.
-
-## Writing a visual program
-
-`VISUAL_IR_V1` identifies the supported visual vocabulary. A component emits ordinary Track,
-Present and element data through `@hypit/composition`. The exported constants
-`VISUAL_STYLE_NAMES_V1` and `VISUAL_STYLE_ENUM_VALUES_V1` describe supported CSS-shaped declarations;
-`assertVisualStyleV1` checks an individual property/value pair. Element schemas are exposed by
-`hypit vocabulary --visual <kind>`.
-
-Static style values are strings or numbers. Resource-bearing image, video and text elements carry
-their actual artifacts or font references as fields. Parents are local to one Present, and child
-coordinates are relative to their parent.
-
-An element may have an `animation` with ordered `keyframes`. Each keyframe has `atFrame`, optional
-`easing`, and `style`. `atFrame` is measured from the containing Present's start. Supported animated
-properties are `opacity`, `transform`, `filter`, `backdrop-filter` and `clip-path`; easing is `linear`, `ease-in`,
-`ease-out` or `ease-in-out`. A renderer can evaluate these values at any requested frame.
-
-Video playback uses the element's separate `sampling` map. Its local target intervals select source
-frame positions and rates, with explicit loops or held frames where wanted. Typography can carry
-richer text layout and unit motion through the text-flow/path-text shapes.
-
-For prepared pixels from another rendering tool, emit a `surface` element with a typed
-CompositableSurfaceRef. Its resource, geometry, color/alpha and temporal metadata let composition
-place and sample it through the same Track model. Local masks name their owned content and mask
-children. Preparation that transforms another material receives that material as an explicit input.
-
-A `program` element carries an explicit format, an object payload and referenced artifacts. The
-rendering package owns that payload's language and execution. It can place owned structural children
-inside a local program, retaining typed media and fonts. For browser HTML/CSS/JavaScript see
-[HyperFrames](../hyperframes/README.md#local-browser-programs). This separates structural convenience
-from the renderer's fuller composition capabilities.
diff --git a/packages/visual-ir/package.json b/packages/visual-ir/package.json
deleted file mode 100644
index 016e4bf3..00000000
--- a/packages/visual-ir/package.json
+++ /dev/null
@@ -1,16 +0,0 @@
-{
- "name": "@hypit/visual-ir",
- "version": "0.0.0-dev",
- "license": "SEE LICENSE IN LICENSE",
- "private": true,
- "type": "module",
- "exports": {
- ".": "./src/index.ts"
- },
- "hypit": {
- "activation": "./src/activation.ts"
- },
- "dependencies": {
- "@hypit/protocol": "workspace:*"
- }
-}
diff --git a/packages/visual-ir/src/activation.ts b/packages/visual-ir/src/activation.ts
deleted file mode 100644
index 3bce7905..00000000
--- a/packages/visual-ir/src/activation.ts
+++ /dev/null
@@ -1,3 +0,0 @@
-import { visualIrManifest } from "./index.js";
-export const hypitPackage = { format: "hypit.node-package@1" as const, modules: [{ manifest: visualIrManifest }] };
-export default hypitPackage;
diff --git a/packages/visual-ir/src/index.ts b/packages/visual-ir/src/index.ts
deleted file mode 100644
index 6d05f8b1..00000000
--- a/packages/visual-ir/src/index.ts
+++ /dev/null
@@ -1,7 +0,0 @@
-import type { ModuleManifest } from "@hypit/protocol";
-export { assertVisualStyleV1, VISUAL_IR_V1, VISUAL_STYLE_ENUM_VALUES_V1, VISUAL_STYLE_NAMES_V1 } from "./style.js";
-export type * from "./style.js";
-export const visualIrModuleRef = { name: "@hypit/visual-ir", version: "1" } as const;
-export const visualIrManifest: ModuleManifest = { format: "hypit.module@1", name: visualIrModuleRef.name, version: visualIrModuleRef.version,
- dependencies: [], types: [], capabilities: [], producers: [] };
-export const visualIrDependency = { module: visualIrModuleRef } as const;
diff --git a/packages/visual-ir/src/style.ts b/packages/visual-ir/src/style.ts
deleted file mode 100644
index 70a23254..00000000
--- a/packages/visual-ir/src/style.ts
+++ /dev/null
@@ -1,222 +0,0 @@
-/** Structural style vocabulary. Renderer programs own their richer layout and code formats. */
-export const VISUAL_IR_V1 = "hypit.visual-ir@1" as const;
-
-/**
- * Closed CSS-shaped vocabulary for public visual Visual IR v1.
- *
- * Values remain serialized declarations because the target is browser based,
- * but components cannot silently extend the language by inventing another CSS
- * property. New semantics require a versioned IR revision; unusual visuals use
- * CompositableSurface instead.
- */
-export const VISUAL_STYLE_NAMES_V1 = [
- "-webkit-background-clip",
- "-webkit-box-decoration-break",
- "-webkit-box-orient",
- "-webkit-line-clamp",
- "-webkit-text-fill-color",
- "-webkit-text-stroke",
- "-webkit-text-stroke-color",
- "-webkit-text-stroke-width",
- "align-content",
- "align-items",
- "align-self",
- "aspect-ratio",
- "background",
- "backdrop-filter",
- "mix-blend-mode",
- "isolation",
- "background-clip",
- "background-color",
- "background-image",
- "background-position",
- "background-repeat",
- "background-size",
- "border",
- "border-bottom",
- "border-bottom-color",
- "border-bottom-left-radius",
- "border-bottom-right-radius",
- "border-bottom-style",
- "border-bottom-width",
- "border-color",
- "border-left",
- "border-left-color",
- "border-left-style",
- "border-left-width",
- "border-radius",
- "border-right",
- "border-right-color",
- "border-right-style",
- "border-right-width",
- "border-style",
- "border-top",
- "border-top-color",
- "border-top-left-radius",
- "border-top-right-radius",
- "border-top-style",
- "border-top-width",
- "border-width",
- "bottom",
- "box-decoration-break",
- "box-shadow",
- "box-sizing",
- "clip-path",
- "color",
- "column-gap",
- "column-count",
- "direction",
- "display",
- "filter",
- "flex",
- "flex-basis",
- "flex-direction",
- "flex-grow",
- "flex-shrink",
- "flex-wrap",
- "font-family",
- "font-feature-settings",
- "font-kerning",
- "font-size",
- "font-style",
- "font-synthesis",
- "font-variant-caps",
- "font-variation-settings",
- "font-weight",
- "gap",
- "grid-area",
- "grid-template-columns",
- "grid-template-rows",
- "height",
- "inset",
- "justify-content",
- "justify-items",
- "justify-self",
- "left",
- "letter-spacing",
- "line-height",
- "margin",
- "margin-bottom",
- "margin-left",
- "margin-right",
- "margin-top",
- "max-height",
- "max-width",
- "min-height",
- "min-width",
- "object-fit",
- "object-position",
- "opacity",
- "outline",
- "outline-color",
- "outline-style",
- "outline-width",
- "overflow",
- "overflow-wrap",
- "overflow-x",
- "overflow-y",
- "padding",
- "padding-bottom",
- "padding-left",
- "padding-right",
- "padding-top",
- "paint-order",
- "perspective",
- "perspective-origin",
- "position",
- "right",
- "row-gap",
- "text-align",
- "text-decoration",
- "text-decoration-color",
- "text-decoration-line",
- "text-decoration-skip-ink",
- "text-decoration-style",
- "text-decoration-thickness",
- "text-overflow",
- "text-indent",
- "text-orientation",
- "text-spacing-trim",
- "text-shadow",
- "text-transform",
- "text-underline-offset",
- "top",
- "tab-size",
- "transform",
- "transform-origin",
- "transform-style",
- "vertical-align",
- "visibility",
- "white-space",
- "width",
- "word-break",
- "word-spacing",
- "writing-mode",
-] as const;
-
-export type VisualStyleNameV1 = typeof VISUAL_STYLE_NAMES_V1[number];
-
-const STYLE_NAMES = new Set<string>(VISUAL_STYLE_NAMES_V1);
-
-export const VISUAL_STYLE_ENUM_VALUES_V1 = {
- "box-sizing": ["border-box", "content-box"],
- direction: ["ltr", "rtl"],
- display: ["block", "inline", "inline-block", "flex", "inline-flex", "grid", "inline-grid", "-webkit-box", "none"],
- "flex-direction": ["row", "row-reverse", "column", "column-reverse"],
- "flex-wrap": ["nowrap", "wrap", "wrap-reverse"],
- "object-fit": ["contain", "cover", "fill", "none", "scale-down"],
- overflow: ["visible", "hidden", "clip"],
- "overflow-x": ["visible", "hidden", "clip"],
- "overflow-y": ["visible", "hidden", "clip"],
- position: ["absolute", "relative"],
- "text-align": ["left", "right", "center", "start", "end", "justify"],
- "text-transform": ["none", "capitalize", "uppercase", "lowercase"],
- visibility: ["visible", "hidden"],
- "white-space": ["normal", "nowrap", "pre", "pre-wrap", "pre-line", "break-spaces"],
- "writing-mode": ["horizontal-tb", "vertical-rl", "vertical-lr"],
-} as const satisfies Partial<Record<VisualStyleNameV1, readonly string[]>>;
-
-const ENUM_VALUES = new Map<string, ReadonlySet<string>>(
- Object.entries(VISUAL_STYLE_ENUM_VALUES_V1)
- .map(([name, values]) => [name, new Set<string>(values)]),
-);
-
-export function assertVisualStyleV1(
- name: string,
- value: string | number,
- label: string,
-): void {
- if (!/^-?[a-z][a-z0-9-]*$/u.test(name)) {
- throw new Error(`${label} contains invalid style name ${name}.`);
- }
- if (!STYLE_NAMES.has(name)) {
- throw new Error(`${label} style ${name} is outside ${VISUAL_IR_V1}.`);
- }
- const values = ENUM_VALUES.get(name);
- if (values !== undefined) {
- if (typeof value !== "string" || !values.has(value)) {
- throw new Error(`${label} style ${name} has unsupported value ${String(value)}.`);
- }
- return;
- }
- if (typeof value === "number") {
- if (!Number.isFinite(value)) throw new Error(`${label} contains a non-finite style value.`);
- return;
- }
- if (value.length === 0) throw new Error(`${label} contains an empty style value.`);
- if (/url\s*\(/iu.test(value)) {
- throw new Error(`${label} must use typed Artifact references instead of CSS url().`);
- }
- if (/(?:-webkit-)?image-set\s*\(/iu.test(value)) {
- throw new Error(`${label} must use typed Artifact references instead of CSS image-set().`);
- }
- if (/[;{}]/u.test(value)) {
- throw new Error(`${label} contains a style value that escapes its declaration.`);
- }
- if (/!important|[\u0000-\u001f\u007f]/iu.test(value)) {
- throw new Error(`${label} contains an unsafe style value.`);
- }
- if (/(?:var|env|attr)\s*\(/iu.test(value)) {
- throw new Error(`${label} contains an environment-dependent style value.`);
- }
-}