@hypit/film 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,26 @@
+# Open Source License
+
+Hypit is licensed under a modified version of the Apache License 2.0, with the following additional conditions:
+
+1. Hypit may be utilized commercially for your own organization's purposes, including as a rendering or generation backend for applications your organization operates for itself, and as internal tooling within an enterprise. Should any of the conditions below be met, a commercial license must be obtained from the producer:
+
+a. Multi-tenant service: Unless explicitly authorized by Hypit.AI in writing, you may not use the Hypit source code, or any derivative work of it, to operate a multi-tenant environment, or to offer Hypit's functionality to third parties as a hosted, managed, or software-as-a-service offering.
+    - Tenant Definition: Within the context of Hypit, one tenant corresponds to one workspace — the isolated set of projects, artifacts, credentials, and configuration belonging to a single party. Operating an environment in which two or more parties outside your own organization hold separate workspaces constitutes a multi-tenant service, whether or not a fee is charged.
+
+b. Commercial redistribution: Unless explicitly authorized by Hypit.AI in writing, you may not sell, license for a fee, or otherwise supply for commercial gain Hypit or any derivative work of it, whether standalone or as a component of, or bundled with, any product, application, package, or device provided to third parties.
+    - Forking, modifying, and publishing the source code of Hypit or a derivative work is permitted, provided the result is made available under the terms of this same license and is not supplied for commercial gain.
+
+    - Permitted without a commercial license under clauses (a) and (b): obtaining Hypit and running it yourself on your own infrastructure; using it for your own organization's work, including commercial work and work performed for your clients; and single-tenant deployments operated by and for one organization.
+
+c. LOGO and copyright information: In the process of using Hypit, you may not remove or modify the name, LOGO, or copyright information presented in the Hypit command-line interface, its generated run reports and manifests, or any user-facing surface derived from them. This restriction is inapplicable to uses of Hypit that do not surface these components to a user.
+
+2. As a contributor, you should agree that:
+
+a. The producer can adjust the open-source agreement to be more strict or relaxed as deemed necessary.
+b. Your contributed code may be used for commercial purposes, including but not limited to its cloud business operations.
+
+3. Ownership of output: The producer claims no rights in the content you create with Hypit. Videos, audio, images, manifests, and any other artifacts produced through your use of Hypit belong to you, and this license imposes no conditions on their use — including commercial use. Note that content generated by way of third-party model or service providers may additionally be subject to the terms of those providers.
+
+Apart from the specific conditions mentioned above, all other rights and restrictions follow the Apache License 2.0. Detailed information about the Apache License 2.0 can be found at http://www.apache.org/licenses/LICENSE-2.0.
+
+© 2026 Hypit.AI

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# `@hypit/film`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Surface, Fragment and assembly Producers receive the same Timeline through a `timeline` input.
+Partial, overlapping or absent semantic coverage all use that complete range.
+
+Official package-owned assembly layer between peer Tracks and the generic Composition waist.
+Film is an ordinary author component and an optional Target, not a Core root or a privileged video
+type.
+
+The official video Distribution installs Film as an ordinary default npm dependency. Film owns its
+author Surface, assembly Producers and Studio film companion together; the reusable companion is
+published as `@hypit/film/studio`. Composition remains the shared value below it, so another author
+package can assemble the same public result without importing Film.
+
+The package lowers one concrete Film declaration into a finite `FilmTrackSet` fold, then compiles
+that set into `Composition`. This supports any number and mix
+of VisualTrack and AudioTrack inputs while every Core Operation retains a fixed manifest-declared
+port list and one atomic result.
+
+`FilmTrackSet` is an immutable lowering value, not an author-facing workflow collection. Each append
+receives the previous set and newly added Track through explicit graph edges. The domain value copies
+no lineage metadata. Final Composition
+remains order-independent because the public contract canonicalizes Tracks and visual ordering
+belongs to each Present's absolute `z`, Track-local `order` and stable identity fallback.
+
+The official Structured Surface validates an imported generic SVS Recipe into a nominal
+`FilmProgram`, receives Canvas and the selected time source through separate explicit edges,
+passes the Timeline directly, type-checks
+each `<film:Track source={...}/>` reference and generates the finite fold. Canvas is the only
+dimension truth, Timeline is the only time-range truth, and FilmProgram owns only assembly
+identity and clear color.
+Child order is organizational: Track and Present identity, timing and absolute stacking remain in
+their own typed values. Final rendering is a separate author package and capability.
+
+For example, after the named inputs are declared:
+
+```svml
+<film:Film id="main" canvas={vertical.canvas} timeline={speech.timeline}
+  appearance={recipes.film.vertical}>
+  <film:Track source={picture.visual}/>
+  <film:Track source={mix.audio}/>
+  <film:Track source={coverage.visual}/>
+  <film:Track source={captions.visual}/>
+  <film:Track source={music.audio}/>
+</film:Film>
+```
+
+The public output is `main.composition`. Including a Visual Track output does not automatically include
+an Audio Track output derived from the same media. An opaque upper layer can cover a performance while
+its separately included audio continues;
+reordering these children is not how an author changes that visual stacking.
+
+The `appearance` Recipe uses `background`, for example `film.vertical { background: #18212A; }`.
+The compiled FilmProgram's field is `clearColor`; it is not a Recipe key named `clear-color`.

package/dist/activation.d.ts

@@ -0,0 +1,8 @@
+export declare const hypitPackage: {
+    format: "hypit.package@1";
+    modules: {
+        manifest: import("@hypit/hypit/protocol").ModuleManifest;
+    }[];
+    facets: import("@hypit/hypit/facet").Facet[];
+};
+export default hypitPackage;

package/dist/activation.js

@@ -0,0 +1,19 @@
+import { createAdmissionPackageFacet } from "@hypit/hypit/admission";
+import { createProducerPackageFacet } from "@hypit/hypit/producer";
+import { createMarkupSurfaceFacet } from "@hypit/hypit/markup";
+import { createStudioCompanionFacet } from "@hypit/studio-companion";
+import { decodeFilmSurface, filmComponent, filmManifest, filmModuleRef, filmMarkupSurfaces, } from "./index.js";
+import { filmStudioCompanions } from "./studio.js";
+export const hypitPackage = {
+    format: "hypit.package@1",
+    modules: [{ manifest: filmManifest }],
+    facets: [
+        ...[filmComponent].flatMap((component) => [createProducerPackageFacet(component), createAdmissionPackageFacet(component)]),
+        createMarkupSurfaceFacet({
+            module: filmModuleRef,
+            declaration: filmMarkupSurfaces.find((item) => item.name === "film"), handler: decodeFilmSurface,
+        }),
+        createStudioCompanionFacet({ films: filmStudioCompanions }),
+    ],
+};
+export default hypitPackage;

package/dist/component.d.ts

@@ -0,0 +1,37 @@
+export declare const filmComponent: {
+    producers: ({
+        producer: {
+            module: {
+                readonly name: "@hypit/film";
+                readonly version: "1";
+            };
+            name: string;
+        };
+        handler: ({ inputs }: import("@hypit/hypit/producer").ProducerHandlerContext) => {
+            outputs: {
+                set: {
+                    kind: "inline";
+                    value: import("@hypit/hypit/protocol").CanonicalValue;
+                };
+            };
+            needs: {};
+        };
+    } | {
+        producer: {
+            module: {
+                readonly name: "@hypit/film";
+                readonly version: "1";
+            };
+            name: string;
+        };
+        handler: ({ inputs }: import("@hypit/hypit/producer").ProducerHandlerContext) => {
+            outputs: {
+                composition: {
+                    kind: "inline";
+                    value: import("@hypit/hypit/protocol").CanonicalValue;
+                };
+            };
+            needs: {};
+        };
+    })[];
+};

package/dist/component.js

@@ -0,0 +1,40 @@
+import { canonicalize } from "@hypit/hypit/protocol";
+import { filmProducers } from "./manifest.js";
+import { appendFilmAudioTrack, appendFilmVisualTrack, compileFilmComposition, createFilmTrackSet } from "./program.js";
+function inline(value, subject) {
+    if (value?.kind !== "inline")
+        throw new Error(`${subject} must be inline`);
+    return value.value;
+}
+export const filmComponent = {
+    producers: [
+        {
+            producer: filmProducers.createTrackSet,
+            handler: () => ({
+                outputs: { set: { kind: "inline", value: canonicalize(createFilmTrackSet()) } },
+                needs: {},
+            }),
+        },
+        {
+            producer: filmProducers.appendVisualTrack,
+            handler: ({ inputs }) => ({
+                outputs: { set: { kind: "inline", value: canonicalize(appendFilmVisualTrack(inline(inputs.set?.value, "FilmTrackSet"), inline(inputs.timeline?.value, "Timeline"), inline(inputs.track?.value, "VisualTrack"))) } },
+                needs: {},
+            }),
+        },
+        {
+            producer: filmProducers.appendAudioTrack,
+            handler: ({ inputs }) => ({
+                outputs: { set: { kind: "inline", value: canonicalize(appendFilmAudioTrack(inline(inputs.set?.value, "FilmTrackSet"), inline(inputs.timeline?.value, "Timeline"), inline(inputs.track?.value, "AudioTrack"))) } },
+                needs: {},
+            }),
+        },
+        {
+            producer: filmProducers.compileComposition,
+            handler: ({ inputs }) => ({
+                outputs: { composition: { kind: "inline", value: canonicalize(compileFilmComposition(inline(inputs.program?.value, "FilmProgram"), inline(inputs.canvas?.value, "Canvas"), inline(inputs.timeline?.value, "Timeline"), inline(inputs.set?.value, "FilmTrackSet"))) } },
+                needs: {},
+            }),
+        },
+    ],
+};

package/dist/fragment.d.ts

@@ -0,0 +1,7 @@
+import type { FilmAssemblyFragmentOptions } from "./types.js";
+/**
+ * Create one hygienic, finite Fragment for a concrete Film declaration. The
+ * author module decides how many Track references it has; Core still receives
+ * ordinary fixed-port Operations after this lowering.
+ */
+export declare function createFilmAssemblyFragment(options: FilmAssemblyFragmentOptions): import("@hypit/hypit/author").GraphFragment;

package/dist/fragment.js

@@ -0,0 +1,78 @@
+import { sealGraphFragment } from "@hypit/hypit/author";
+import { compositionTypes } from "@hypit/hypit/composition";
+import { spatialTypes } from "@hypit/hypit/spatial";
+import { timelineTypes } from "@hypit/hypit/timeline";
+import { filmProducers, filmTypes } from "./manifest.js";
+const input = (name) => ({ kind: "fragment-input", name });
+const operation = (id) => ({ kind: "fragment-operation", operation: id });
+function assertTrackInputs(tracks) {
+    const names = new Set(["program", "canvas", "timeline"]);
+    return [...tracks]
+        .map((track) => ({ name: track.name.trim(), kind: track.kind }))
+        .sort((left, right) => left.name.localeCompare(right.name))
+        .map((track) => {
+        if (!track.name)
+            throw new Error("Film Track input name must not be empty.");
+        if (names.has(track.name))
+            throw new Error(`Film Track input name ${track.name} is reserved or duplicated.`);
+        names.add(track.name);
+        return track;
+    });
+}
+/**
+ * Create one hygienic, finite Fragment for a concrete Film declaration. The
+ * author module decides how many Track references it has; Core still receives
+ * ordinary fixed-port Operations after this lowering.
+ */
+export function createFilmAssemblyFragment(options) {
+    const tracks = assertTrackInputs(options.tracks);
+    const operations = [
+        {
+            id: "track-set:empty",
+            producer: filmProducers.createTrackSet,
+            inputs: {},
+            result: { kind: "output", name: "set" },
+        },
+    ];
+    let current = "track-set:empty";
+    tracks.forEach((track, index) => {
+        const id = `track-set:append:${String(index).padStart(4, "0")}`;
+        operations.push({
+            id,
+            producer: track.kind === "visual" ? filmProducers.appendVisualTrack : filmProducers.appendAudioTrack,
+            inputs: { set: operation(current), timeline: input("timeline"), track: input(track.name) },
+            result: { kind: "output", name: "set" },
+        });
+        current = id;
+    });
+    operations.push({
+        id: "film:composition",
+        producer: filmProducers.compileComposition,
+        inputs: {
+            program: input("program"),
+            canvas: input("canvas"),
+            timeline: input("timeline"),
+            set: operation(current),
+        },
+        result: { kind: "output", name: "composition" },
+    });
+    return sealGraphFragment({
+        inputs: [
+            { name: "program", type: filmTypes.program },
+            { name: "canvas", type: spatialTypes.canvas },
+            { name: "timeline", type: timelineTypes.timeline },
+            ...tracks.map((track) => ({
+                name: track.name,
+                type: track.kind === "visual" ? compositionTypes.visualTrack : compositionTypes.audioTrack,
+            })),
+        ],
+        operations,
+        exports: [
+            {
+                name: "composition",
+                type: compositionTypes.composition,
+                root: operation("film:composition"),
+            },
+        ],
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { createFilmAssemblyFragment } from "./fragment.js";
+export { filmComponent } from "./component.js";
+export { filmManifest, filmMarkupSurfaces, filmModuleRef, filmProgramSchema, filmProducers, filmTrackSetSchema, filmTypes } from "./manifest.js";
+export { appendFilmAudioTrack, appendFilmVisualTrack, assertFilmProgramIdentity, assertFilmTrackSetIdentity, compileFilmComposition, createFilmTrackSet, sealFilmProgram } from "./program.js";
+export { assertFilmRecipe, filmAppearanceFromRecipe, } from "./recipe.js";
+export type { FilmAppearance } from "./recipe.js";
+export { decodeFilmSurface } from "./surface.js";
+export type * from "./types.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { createFilmAssemblyFragment } from "./fragment.js";
+export { filmComponent } from "./component.js";
+export { filmManifest, filmMarkupSurfaces, filmModuleRef, filmProgramSchema, filmProducers, filmTrackSetSchema, filmTypes } from "./manifest.js";
+export { appendFilmAudioTrack, appendFilmVisualTrack, assertFilmProgramIdentity, assertFilmTrackSetIdentity, compileFilmComposition, createFilmTrackSet, sealFilmProgram } from "./program.js";
+export { assertFilmRecipe, filmAppearanceFromRecipe, } from "./recipe.js";
+export { decodeFilmSurface } from "./surface.js";

package/dist/manifest.d.ts

@@ -0,0 +1,154 @@
+import type { ModuleManifest, ValueSchema } from "@hypit/hypit/protocol";
+export declare const filmModuleRef: {
+    readonly name: "@hypit/film";
+    readonly version: "1";
+};
+export declare const filmTypes: {
+    program: {
+        module: {
+            readonly name: "@hypit/film";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    trackSet: {
+        module: {
+            readonly name: "@hypit/film";
+            readonly version: "1";
+        };
+        name: string;
+    };
+};
+export declare const filmProducers: {
+    createTrackSet: {
+        module: {
+            readonly name: "@hypit/film";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    appendVisualTrack: {
+        module: {
+            readonly name: "@hypit/film";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    appendAudioTrack: {
+        module: {
+            readonly name: "@hypit/film";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    compileComposition: {
+        module: {
+            readonly name: "@hypit/film";
+            readonly version: "1";
+        };
+        name: string;
+    };
+};
+export declare const filmProgramSchema: ValueSchema;
+export declare const filmTrackSetSchema: ValueSchema;
+export declare const filmMarkupSurfaces: readonly [{
+    readonly name: "film";
+    readonly tag: "Film";
+    readonly mode: "structured";
+    readonly outputs: readonly [{
+        module: {
+            readonly name: "@hypit/film";
+            readonly version: "1";
+        };
+        name: string;
+    }];
+    readonly vocabulary: {
+        readonly summary: "Assembles any number of peer VisualTrack and AudioTrack references into one Composition against a Canvas and a Timeline.";
+        readonly appearance: "One flat fill of the entire Canvas, in the single hexadecimal color the Recipe's `background` carries, lying behind everything else in the Frame. It covers the full Canvas width and height, holds that one color from the first Frame to the last, and never moves, fades or changes. Wherever nothing is painted over it, that color is what the Frame shows; the Film puts no mark of its own on top of it.";
+        readonly attributes: readonly [{
+            readonly name: "id";
+            readonly kind: "identifier";
+            readonly required: true;
+            readonly summary: "Names the Film component and the Composition binding it publishes.";
+        }, {
+            readonly name: "canvas";
+            readonly kind: "reference";
+            readonly required: true;
+            readonly accepts: readonly [{
+                module: {
+                    readonly name: "@hypit/spatial";
+                    readonly version: "1";
+                };
+                name: string;
+            }];
+            readonly summary: "Selects the Canvas that decides the Composition's dimensions.";
+        }, {
+            readonly name: "timeline";
+            readonly kind: "reference";
+            readonly required: true;
+            readonly accepts: readonly [{
+                module: {
+                    readonly name: "@hypit/timeline";
+                    readonly version: "1";
+                };
+                name: string;
+            }];
+            readonly summary: "The complete absolute film Timeline.";
+        }, {
+            readonly name: "appearance";
+            readonly kind: "reference";
+            readonly required: true;
+            readonly accepts: readonly [{
+                module: {
+                    readonly name: "@hypit/recipe";
+                    readonly version: "1";
+                };
+                name: string;
+            }];
+            readonly summary: "Selects the SVS Recipe that decides the clear color behind every Track.";
+            readonly recipe: readonly [{
+                readonly name: "background";
+                readonly required: true;
+                readonly summary: "Decides the color the Film clears to behind every Track, written as `#rrggbb` or `#rrggbbaa`.";
+            }];
+        }];
+        readonly children: readonly [{
+            readonly tag: "Track";
+            readonly cardinality: "many";
+            readonly summary: "Adds one VisualTrack or AudioTrack to the assembly.";
+            readonly attributes: readonly [{
+                readonly name: "source";
+                readonly kind: "reference";
+                readonly required: true;
+                readonly accepts: readonly [{
+                    module: {
+                        readonly name: "@hypit/composition";
+                        readonly version: "1";
+                    };
+                    name: string;
+                }, {
+                    module: {
+                        readonly name: "@hypit/composition";
+                        readonly version: "1";
+                    };
+                    name: string;
+                }];
+                readonly summary: "Selects the Track this entry contributes to the Composition.";
+            }];
+        }];
+        readonly ports: readonly [{
+            readonly name: "composition";
+            readonly type: {
+                module: {
+                    readonly name: "@hypit/composition";
+                    readonly version: "1";
+                };
+                name: string;
+            };
+            readonly summary: "The assembled Composition, addressed as `<id>.composition`.";
+        }];
+        readonly example: string;
+        readonly notes: readonly ["At least one `Track` is required.", "The Recipe carries exactly one property, `background`, written as a hexadecimal color; any other property is rejected, and Canvas geometry and frame rate stay on their own edges.", "Child order is organizational: Track identity, timing and absolute stacking stay in their own typed values."];
+    };
+}];
+export declare const filmManifest: ModuleManifest;

package/dist/manifest.js

@@ -0,0 +1,138 @@
+import { audioTrackSchema, compositionDependency, compositionTypes, visualTrackSchema } from "@hypit/hypit/composition";
+import { spatialDependency, spatialTypes } from "@hypit/hypit/spatial";
+import { recipeManifest, recipeModuleRef, recipeType } from "@hypit/hypit/recipe";
+import { temporalContextAttributeVocabulary } from "@hypit/hypit/temporal/markup";
+import { timelineTypes, timelineDependency } from "@hypit/hypit/timeline";
+export const filmModuleRef = { name: "@hypit/film", version: "1" };
+export const filmTypes = {
+    program: { module: filmModuleRef, name: "FilmProgram" },
+    trackSet: { module: filmModuleRef, name: "FilmTrackSet" },
+};
+export const filmProducers = {
+    createTrackSet: { module: filmModuleRef, name: "create-track-set" },
+    appendVisualTrack: { module: filmModuleRef, name: "append-visual-track" },
+    appendAudioTrack: { module: filmModuleRef, name: "append-audio-track" },
+    compileComposition: { module: filmModuleRef, name: "compile-composition" },
+};
+const string = { kind: "string", minLength: 1 };
+const object = (fields) => ({
+    kind: "object",
+    fields,
+});
+export const filmProgramSchema = object({
+    id: { schema: string },
+    clearColor: { schema: string },
+});
+export const filmTrackSetSchema = object({
+    tracks: {
+        schema: {
+            kind: "array",
+            items: { kind: "oneOf", variants: [visualTrackSchema, audioTrackSchema] },
+        },
+    },
+});
+export const filmMarkupSurfaces = [{
+        name: "film",
+        tag: "Film",
+        mode: "structured",
+        outputs: [filmTypes.program],
+        vocabulary: {
+            summary: "Assembles any number of peer VisualTrack and AudioTrack references into one Composition against a Canvas and a Timeline.",
+            appearance: "One flat fill of the entire Canvas, in the single hexadecimal color the Recipe's `background` carries, lying behind everything else in the Frame. It covers the full Canvas width and height, holds that one color from the first Frame to the last, and never moves, fades or changes. Wherever nothing is painted over it, that color is what the Frame shows; the Film puts no mark of its own on top of it.",
+            attributes: [
+                { name: "id", kind: "identifier", required: true,
+                    summary: "Names the Film component and the Composition binding it publishes." },
+                { name: "canvas", kind: "reference", required: true,
+                    accepts: [spatialTypes.canvas],
+                    summary: "Selects the Canvas that decides the Composition's dimensions." },
+                ...temporalContextAttributeVocabulary,
+                { name: "appearance", kind: "reference", required: true,
+                    accepts: [recipeType],
+                    summary: "Selects the SVS Recipe that decides the clear color behind every Track.",
+                    recipe: [
+                        { name: "background", required: true,
+                            summary: "Decides the color the Film clears to behind every Track, written as `#rrggbb` or `#rrggbbaa`." },
+                    ] },
+            ],
+            children: [
+                { tag: "Track", cardinality: "many",
+                    summary: "Adds one VisualTrack or AudioTrack to the assembly.",
+                    attributes: [
+                        { name: "source", kind: "reference", required: true,
+                            accepts: [compositionTypes.visualTrack, compositionTypes.audioTrack],
+                            summary: "Selects the Track this entry contributes to the Composition." },
+                    ] },
+            ],
+            ports: [
+                { name: "composition", type: compositionTypes.composition,
+                    summary: "The assembled Composition, addressed as `<id>.composition`." },
+            ],
+            example: [
+                '<film:Film id="main" canvas={vertical.canvas} timeline={speech.timeline} appearance={recipes.film.vertical}>',
+                "  <film:Track source={performance.visual}/>",
+                "  <film:Track source={voice.audio}/>",
+                "  <film:Track source={captions.visual}/>",
+                "</film:Film>",
+            ].join("\n"),
+            notes: [
+                "At least one `Track` is required.",
+                "The Recipe carries exactly one property, `background`, written as a hexadecimal color; any other property is rejected, and Canvas geometry and frame rate stay on their own edges.",
+                "Child order is organizational: Track identity, timing and absolute stacking stay in their own typed values.",
+            ],
+        },
+    }];
+export const filmManifest = {
+    format: "hypit.module@1",
+    name: filmModuleRef.name,
+    version: filmModuleRef.version,
+    dependencies: [
+        timelineDependency,
+        spatialDependency,
+        compositionDependency,
+        { module: recipeModuleRef },
+    ],
+    types: [
+        { name: filmTypes.program.name },
+        { name: filmTypes.trackSet.name },
+    ],
+    capabilities: [],
+    producers: [
+        {
+            name: filmProducers.createTrackSet.name,
+            inputs: [],
+            outputs: [{ name: "set", type: filmTypes.trackSet }],
+            needs: [],
+        },
+        {
+            name: filmProducers.appendVisualTrack.name,
+            inputs: [
+                { name: "set", type: filmTypes.trackSet },
+                { name: "timeline", type: timelineTypes.timeline },
+                { name: "track", type: compositionTypes.visualTrack },
+            ],
+            outputs: [{ name: "set", type: filmTypes.trackSet }],
+            needs: [],
+        },
+        {
+            name: filmProducers.appendAudioTrack.name,
+            inputs: [
+                { name: "set", type: filmTypes.trackSet },
+                { name: "timeline", type: timelineTypes.timeline },
+                { name: "track", type: compositionTypes.audioTrack },
+            ],
+            outputs: [{ name: "set", type: filmTypes.trackSet }],
+            needs: [],
+        },
+        {
+            name: filmProducers.compileComposition.name,
+            inputs: [
+                { name: "program", type: filmTypes.program },
+                { name: "canvas", type: spatialTypes.canvas },
+                { name: "timeline", type: timelineTypes.timeline },
+                { name: "set", type: filmTypes.trackSet },
+            ],
+            outputs: [{ name: "composition", type: compositionTypes.composition }],
+            needs: [],
+        },
+    ],
+};

package/dist/program.d.ts

@@ -0,0 +1,11 @@
+import type { AudioTrack, Composition, VisualTrack } from "@hypit/hypit/composition";
+import type { Canvas } from "@hypit/hypit/spatial";
+import type { Timeline } from "@hypit/hypit/timeline";
+import type { FilmProgram, FilmTrackSet } from "./types.js";
+export declare function sealFilmProgram(value: FilmProgram): FilmProgram;
+export declare function assertFilmProgramIdentity(program: FilmProgram): void;
+export declare function assertFilmTrackSetIdentity(set: FilmTrackSet): void;
+export declare function createFilmTrackSet(): FilmTrackSet;
+export declare function appendFilmVisualTrack(set: FilmTrackSet, timeline: Timeline, track: VisualTrack): FilmTrackSet;
+export declare function appendFilmAudioTrack(set: FilmTrackSet, timeline: Timeline, track: AudioTrack): FilmTrackSet;
+export declare function compileFilmComposition(program: FilmProgram, canvas: Canvas, timeline: Timeline, set: FilmTrackSet): Composition;

package/dist/program.js

@@ -0,0 +1,89 @@
+import { assertAudioTrackIdentity, assertCompositionIdentity, assertVisualTrackIdentity, sealComposition } from "@hypit/hypit/composition";
+import { assertCanvas } from "@hypit/hypit/spatial";
+import { assertTimelineIdentity } from "@hypit/hypit/timeline";
+function assertNonEmpty(value, label) {
+    if (!value.trim())
+        throw new Error(`${label} must not be empty.`);
+}
+function trackKey(track) {
+    return `${track.kind}\u0000${track.id}`;
+}
+function filmProgramContent(value) {
+    return {
+        id: value.id,
+        clearColor: value.clearColor,
+    };
+}
+function filmTrackSetContent(value) {
+    return {
+        tracks: [...value.tracks]
+            .map((track) => structuredClone(track))
+            .sort((left, right) => trackKey(left).localeCompare(trackKey(right))),
+    };
+}
+export function sealFilmProgram(value) {
+    return filmProgramContent(value);
+}
+export function assertFilmProgramIdentity(program) {
+    assertNonEmpty(program.id, "FilmProgram id");
+    if (!/^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/iu.test(program.clearColor)) {
+        throw new Error("FilmProgram clear color is invalid.");
+    }
+}
+function sealFilmTrackSet(value) {
+    return filmTrackSetContent(value);
+}
+export function assertFilmTrackSetIdentity(set) {
+    const ids = new Set();
+    for (const track of set.tracks) {
+        if (ids.has(track.id))
+            throw new Error(`FilmTrackSet contains duplicate Track id ${track.id}.`);
+        ids.add(track.id);
+        if (track.kind === "visual")
+            assertVisualTrackIdentity(track);
+        else
+            assertAudioTrackIdentity(track);
+    }
+}
+export function createFilmTrackSet() {
+    return sealFilmTrackSet({
+        tracks: [],
+    });
+}
+function appendTrack(set, timeline, track) {
+    assertFilmTrackSetIdentity(set);
+    assertTimelineIdentity(timeline);
+    if (track.kind === "visual")
+        assertVisualTrackIdentity(track, timeline);
+    else
+        assertAudioTrackIdentity(track, timeline);
+    if (set.tracks.some((existing) => existing.id === track.id)) {
+        throw new Error(`FilmTrackSet already contains Track id ${track.id}.`);
+    }
+    return sealFilmTrackSet({
+        tracks: [...set.tracks, track],
+    });
+}
+export function appendFilmVisualTrack(set, timeline, track) {
+    return appendTrack(set, timeline, track);
+}
+export function appendFilmAudioTrack(set, timeline, track) {
+    return appendTrack(set, timeline, track);
+}
+export function compileFilmComposition(program, canvas, timeline, set) {
+    assertFilmProgramIdentity(program);
+    assertCanvas(canvas);
+    assertTimelineIdentity(timeline);
+    assertFilmTrackSetIdentity(set);
+    const composition = sealComposition({
+        id: program.id,
+        canvas: {
+            width: canvas.widthPx,
+            height: canvas.heightPx,
+            clearColor: program.clearColor,
+        },
+        tracks: set.tracks,
+    });
+    assertCompositionIdentity(composition, timeline);
+    return composition;
+}

package/dist/recipe.d.ts

@@ -0,0 +1,10 @@
+import type { Recipe } from "@hypit/hypit/recipe";
+/**
+ * The Film Recipe owns Film appearance only. Canvas geometry and Timeline
+ * remain separate graph inputs and cannot be smuggled into a stylesheet.
+ */
+export type FilmAppearance = {
+    readonly clearColor: string;
+};
+export declare function assertFilmRecipe(properties: Recipe["properties"]): void;
+export declare function filmAppearanceFromRecipe(properties: Recipe["properties"]): FilmAppearance;

package/dist/recipe.js

@@ -0,0 +1,14 @@
+export function assertFilmRecipe(properties) {
+    const actual = Object.keys(properties).sort().join(" ");
+    if (actual !== "background") {
+        throw new Error("Film Recipe requires exactly background");
+    }
+}
+export function filmAppearanceFromRecipe(properties) {
+    assertFilmRecipe(properties);
+    const background = properties["background"];
+    if (typeof background !== "string" || !/^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/iu.test(background)) {
+        throw new Error("Film Recipe background must be a hexadecimal color");
+    }
+    return { clearColor: background };
+}

package/dist/studio.d.ts

@@ -0,0 +1,3 @@
+import type { StudioFilmCompanion } from "@hypit/studio-companion";
+/** Film owns the author vocabulary that selects its time source and peer Tracks. */
+export declare const filmStudioCompanions: readonly StudioFilmCompanion[];

package/dist/studio.js

@@ -0,0 +1,14 @@
+import { compositionTypes } from "@hypit/hypit/composition";
+import { timelineTypes } from "@hypit/hypit/timeline";
+import { filmModuleRef } from "./manifest.js";
+/** Film owns the author vocabulary that selects its time source and peer Tracks. */
+export const filmStudioCompanions = [{
+        id: "film",
+        match: { module: filmModuleRef, surface: "film", outputType: compositionTypes.composition },
+        timeSources: [{ attribute: "timeline", type: timelineTypes.timeline }],
+        tracks: {
+            childSurface: "Track",
+            sourceAttribute: "source",
+            types: [compositionTypes.visualTrack, compositionTypes.audioTrack],
+        },
+    }];

package/dist/surface.d.ts

@@ -0,0 +1,2 @@
+import type { StructuredSurfaceHandler } from "@hypit/hypit/markup";
+export declare const decodeFilmSurface: StructuredSurfaceHandler;

package/dist/surface.js

@@ -0,0 +1,127 @@
+import { compositionTypes } from "@hypit/hypit/composition";
+import { spatialTypes } from "@hypit/hypit/spatial";
+import { recipeType } from "@hypit/hypit/recipe";
+import { resolveTemporalContext } from "@hypit/hypit/temporal/markup";
+import { createFilmAssemblyFragment } from "./fragment.js";
+import { filmTypes } from "./manifest.js";
+import { sealFilmProgram } from "./program.js";
+import { filmAppearanceFromRecipe } from "./recipe.js";
+function localName(value) {
+    return value.includes(":") ? value.slice(value.lastIndexOf(":") + 1) : value;
+}
+function exactAttributes(element, names) {
+    const actual = Object.keys(element.attributes).sort();
+    const expected = [...names].sort();
+    if (actual.join("\u0000") !== expected.join("\u0000")) {
+        throw new Error(`${element.name} requires exactly ${expected.join(", ")}`);
+    }
+}
+function stringAttribute(element, name) {
+    const value = element.attributes[name];
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`${element.name}.${name} must be a non-empty string`);
+    }
+    return value;
+}
+function referenceAttribute(element, name) {
+    const value = element.attributes[name];
+    if (typeof value !== "object" || value.kind !== "reference" || value.path.length === 0) {
+        throw new Error(`${element.name}.${name} must be a whole-value reference`);
+    }
+    return value.path;
+}
+function sameType(left, right) {
+    return left.module.name === right.module.name
+        && left.module.version === right.module.version
+        && left.name === right.name;
+}
+function requiredReference(element, name, resolve) {
+    const path = referenceAttribute(element, name);
+    const resolved = resolve(path);
+    if (resolved === undefined)
+        throw new Error(`${element.name}.${name} cannot resolve ${path}`);
+    return resolved;
+}
+function recipe(reference, label) {
+    if (!sameType(reference.type, recipeType))
+        throw new Error(`${label} must reference an SVS Recipe`);
+    const value = reference.record?.value;
+    if (value?.kind !== "inline" || value.value === null || Array.isArray(value.value)
+        || typeof value.value !== "object") {
+        throw new Error(`${label} must reference an authored Recipe value`);
+    }
+    return value.value;
+}
+function trackChildren(element) {
+    const tracks = [];
+    for (const child of element.children) {
+        if (child.kind === "text") {
+            if (child.value.trim().length > 0)
+                throw new Error(`${element.name} accepts only Track children`);
+            continue;
+        }
+        if (localName(child.name) !== "Track")
+            throw new Error(`${element.name} accepts only Track children`);
+        exactAttributes(child, ["source"]);
+        tracks.push(child);
+    }
+    if (tracks.length === 0)
+        throw new Error(`${element.name} requires at least one Track`);
+    return tracks;
+}
+function trackKind(reference) {
+    if (sameType(reference.type, compositionTypes.visualTrack))
+        return "visual";
+    if (sameType(reference.type, compositionTypes.audioTrack))
+        return "audio";
+    throw new Error(`Film Track ${reference.path} must be a VisualTrack or AudioTrack`);
+}
+export const decodeFilmSurface = ({ element, resolveReference }) => {
+    exactAttributes(element, ["id", "canvas", "timeline", "appearance"]);
+    const id = stringAttribute(element, "id");
+    const canvas = requiredReference(element, "canvas", resolveReference);
+    if (!sameType(canvas.type, spatialTypes.canvas)) {
+        throw new Error(`${element.name}.canvas must reference Canvas`);
+    }
+    const context = resolveTemporalContext({ element, resolveReference });
+    const appearanceReference = requiredReference(element, "appearance", resolveReference);
+    const appearance = filmAppearanceFromRecipe(recipe(appearanceReference, `${element.name}.appearance`).properties);
+    const programId = `${id}.program`;
+    const program = sealFilmProgram({
+        id,
+        clearColor: appearance.clearColor,
+    });
+    const tracks = trackChildren(element).map((child, index) => {
+        const source = requiredReference(child, "source", resolveReference);
+        const name = `track-${index + 1}`;
+        return { name, kind: trackKind(source), source };
+    });
+    const sourceKeys = tracks.map(({ source: { ref } }) => ref.kind === "record"
+        ? `record\u0000${ref.id}`
+        : `component-output\u0000${ref.component}\u0000${ref.output}`);
+    if (new Set(sourceKeys).size !== tracks.length) {
+        throw new Error(`${element.name} cannot include the same Track more than once`);
+    }
+    const fragment = createFilmAssemblyFragment({ name: "@hypit/film/surface-assembly@1", tracks });
+    return {
+        records: [{
+                id: programId,
+                type: filmTypes.program,
+                value: { kind: "inline", value: program },
+                range: element.range,
+            }],
+        components: [{
+                id,
+                fragment: fragment.id,
+                inputs: {
+                    program: { kind: "record", id: programId },
+                    canvas: canvas.ref,
+                    timeline: context.timeline.ref,
+                    ...Object.fromEntries(tracks.map((track) => [track.name, track.source.ref])),
+                },
+                outputs: { composition: `${id}.composition` },
+                range: element.range,
+            }],
+        fragments: [fragment],
+    };
+};

package/dist/types.d.ts

@@ -0,0 +1,22 @@
+import type { Track } from "@hypit/hypit/composition";
+/** Package-owned authoring value. A future Film Surface may produce this record. */
+export type FilmProgram = {
+    readonly id: string;
+    readonly clearColor: string;
+};
+/**
+ * Immutable package-private fold value used to collect an arbitrary number of
+ * peer Tracks without adding variadic Operation ports to Core.
+ */
+export type FilmTrackSet = {
+    readonly tracks: readonly Track[];
+};
+export type FilmTrackInput = {
+    /** Fragment input name used by the author module lowering this Film instance. */
+    readonly name: string;
+    readonly kind: "visual" | "audio";
+};
+export type FilmAssemblyFragmentOptions = {
+    readonly name?: string;
+    readonly tracks: readonly FilmTrackInput[];
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "@hypit/film",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./studio": "./dist/studio.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "hypit": {
+    "activation": "./dist/activation.js"
+  },
+  "peerDependencies": {
+    "@hypit/hypit": "^0.3.0",
+    "@hypit/studio-companion": "^0.1.0"
+  },
+  "dependencies": {}
+}