@hypit/hypit 0.0.1 → 0.1.0

package/dist/public/visual-ir.d.ts

@@ -0,0 +1,98 @@
+type ModuleRef = {
+    readonly name: string;
+    readonly version: string;
+};
+/**
+ * A Type is its owning Module and its name, and nothing else is compared. Two Types whose values
+ * carry identical shapes are distinct, so one is refused where the other is declared — there is no
+ * structural fallback to fall back to.
+ */
+type TypeRef = {
+    readonly module: ModuleRef;
+    readonly name: string;
+};
+type CapabilityRef = {
+    readonly module: ModuleRef;
+    readonly name: string;
+};
+
+type ModuleDependency = {
+    readonly module: ModuleRef;
+};
+type TypeDeclaration = {
+    readonly name: string;
+};
+type PortDeclaration = {
+    readonly name: string;
+    readonly type: TypeRef;
+};
+type NeedPortDeclaration = {
+    readonly name: string;
+    readonly capability: CapabilityRef;
+    readonly returns: TypeRef;
+};
+type CapabilityDeclaration = {
+    readonly name: string;
+    readonly returns: TypeRef;
+};
+type ProducerDeclaration = {
+    readonly name: string;
+    readonly inputs: readonly PortDeclaration[];
+    readonly outputs: readonly PortDeclaration[];
+    readonly needs: readonly NeedPortDeclaration[];
+};
+type ModuleManifest = {
+    readonly format: "hypit.module@1";
+    readonly name: string;
+    readonly version: string;
+    readonly dependencies: readonly ModuleDependency[];
+    readonly types: readonly TypeDeclaration[];
+    readonly capabilities: readonly CapabilityDeclaration[];
+    readonly producers: readonly ProducerDeclaration[];
+};
+
+/** Structural style vocabulary. Renderer programs own their richer layout and code formats. */
+declare const VISUAL_IR_V1: "hypit.visual-ir@1";
+/**
+ * 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.
+ */
+declare const VISUAL_STYLE_NAMES_V1: readonly ["-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"];
+type VisualStyleNameV1 = typeof VISUAL_STYLE_NAMES_V1[number];
+declare const VISUAL_STYLE_ENUM_VALUES_V1: {
+    readonly "box-sizing": readonly ["border-box", "content-box"];
+    readonly direction: readonly ["ltr", "rtl"];
+    readonly display: readonly ["block", "inline", "inline-block", "flex", "inline-flex", "grid", "inline-grid", "-webkit-box", "none"];
+    readonly "flex-direction": readonly ["row", "row-reverse", "column", "column-reverse"];
+    readonly "flex-wrap": readonly ["nowrap", "wrap", "wrap-reverse"];
+    readonly "object-fit": readonly ["contain", "cover", "fill", "none", "scale-down"];
+    readonly overflow: readonly ["visible", "hidden", "clip"];
+    readonly "overflow-x": readonly ["visible", "hidden", "clip"];
+    readonly "overflow-y": readonly ["visible", "hidden", "clip"];
+    readonly position: readonly ["absolute", "relative"];
+    readonly "text-align": readonly ["left", "right", "center", "start", "end", "justify"];
+    readonly "text-transform": readonly ["none", "capitalize", "uppercase", "lowercase"];
+    readonly visibility: readonly ["visible", "hidden"];
+    readonly "white-space": readonly ["normal", "nowrap", "pre", "pre-wrap", "pre-line", "break-spaces"];
+    readonly "writing-mode": readonly ["horizontal-tb", "vertical-rl", "vertical-lr"];
+};
+declare function assertVisualStyleV1(name: string, value: string | number, label: string): void;
+
+declare const visualIrModuleRef: {
+    readonly name: "@hypit/visual-ir";
+    readonly version: "1";
+};
+declare const visualIrManifest: ModuleManifest;
+declare const visualIrDependency: {
+    readonly module: {
+        readonly name: "@hypit/visual-ir";
+        readonly version: "1";
+    };
+};
+
+export { VISUAL_IR_V1, VISUAL_STYLE_ENUM_VALUES_V1, VISUAL_STYLE_NAMES_V1, assertVisualStyleV1, visualIrDependency, visualIrManifest, visualIrModuleRef };
+export type { VisualStyleNameV1 };

package/docs/public/hypit-logo-dark.svg

@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" viewBox="54.9 186.2 732.1 222.8">
+  <!-- Generator: Adobe Illustrator 30.0.0, SVG Export Plug-In . SVG Version: 2.1.1 Build 123)  -->
+  <defs>
+    <style>
+      .st0 {
+        fill: #010101;
+      }
+
+      .st1 {
+        fill: url(#linear-gradient);
+      }
+
+      .st2 {
+        fill: #e83f5f;
+      }
+    </style>
+    <linearGradient id="linear-gradient" x1="103.04" y1="194.28" x2="261.09" y2="393.77" gradientTransform="translate(0 .83)" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#e83f5f"/>
+      <stop offset=".14" stop-color="#e94765"/>
+      <stop offset=".33" stop-color="#ec5774"/>
+      <stop offset=".56" stop-color="#f1738c"/>
+      <stop offset=".8" stop-color="#f599af"/>
+      <stop offset=".88" stop-color="#f6a9bd"/>
+    </linearGradient>
+  </defs>
+  <g id="Layer_3">
+    <path class="st1" d="M303.78,277.82c-5.98-8.63-15.83-13.77-26.32-13.77h-93.41c-12.28,0-24.92,7.44-29.6,18.8l-28.26,75.82c-4.6,11.25-4.54,24.05,2.22,34.16,6.79,10.15,19.36,16.15,31.57,16.15h85.98c14.12,0,26.9-8.88,31.84-22.1l29.69-79.57c3.67-9.84,2.29-20.86-3.69-29.48v-.02h-.02ZM252.02,377.25c-.94,2.52-3.39,4.22-6.08,4.22h-83.45c-4.34,0-6.68-2.8-7.49-3.99s-2.5-4.43-.84-8.44l23.85-66.24c2.29-6.35,8.08-10.87,14.82-11.22.33-.02.67-.02,1.02-.02h75.41s12.51,1.42,9.29,14.61l-26.53,71.09h0ZM106.85,361.73s-22.36-11.59-17.66-32.66l29.67-82.23c4.78-13.25,17.36-22.09,31.45-22.09h95.02c6.25,0,12.1,3.03,15.71,8.14l13.89,19.68h-112.97c-8.7,0-16.49,5.41-19.52,13.57l-35.59,95.6h0ZM73.3,323.27s-22.37-11.59-17.66-32.66l29.67-82.23c4.79-13.25,17.37-22.09,31.45-22.09h89.91c6.25,0,12.1,3.03,15.71,8.14l13.89,19.68h-107.84c-8.7,0-16.49,5.41-19.52,13.57l-35.59,95.6h-.02Z"/>
+    <rect class="st0" x="692.47" y="276.19" width="19.22" height="90.09" rx="4.12" ry="4.12"/>
+    <path class="st0" d="M462.31,293.32c-4.51-11.11-12.93-15.68-28.26-17.66-15.52-2-31.17,1.58-36.41,2.96v-38.42c0-2.22-1.8-4.02-4.02-4.02h-11.19c-2.22,0-4.02,1.8-4.02,4.02v123.26c0,2.22,1.8,4.02,4.02,4.02h11.19c2.22,0,4.02-1.8,4.02-4.02v-66.25c3.68-1.46,16.84-6.13,30.89-4.57,12.12,1.35,15.81,10.13,16.92,14.75.32,1.33.47,2.68.47,4.03v53.36c0,1.49,1.2,2.68,2.68,2.68h13.65c1.49,0,2.68-1.2,2.68-2.68v-57.38c0-4.82-.82-9.63-2.63-14.09h.01Z"/>
+    <path class="st0" d="M568.55,346.34v-67.42c0-1.57-1.27-2.85-2.85-2.85h-14.66c-1.57,0-2.85,1.27-2.85,2.85v64.51c0,.58-.19,1.16-.58,1.6-1.62,1.88-7.33,6.23-25.19,5.92-2.22.05-6.37-.58-8.51-1.13-14.03-3.61-12.62-17.41-12.62-33.16v-37.73c0-1.57-1.27-2.85-2.85-2.85h-13.68c-1.57,0-2.85,1.27-2.85,2.85v57.63s-2.72,24.49,25.91,30.92c0,0,3.11.67,7.45,1.01h-.02s.13,0,.38.03c.07,0,.15,0,.23.02.19.02.42.02.69.04.25.02.51.02.77.04,2.94.14,8.59.25,14.08-.44h-.05c6.97-.77,13.42-2.51,17.37-5.02,0,0-1.77,20.45-18.82,23.73-9.86,1.13-24.24-.46-31.62-1.65-2.22-.36-4.33,1.06-4.84,3.24l-2.55,10.92c-.49,2.08.99,4.09,3.1,4.28,7.44.63,23.6,1.84,34.54,1.37,14.62-.61,26.8-6.24,34.06-21.17,7.26-14.93,5.93-37.54,5.93-37.54h.03Z"/>
+    <path class="st0" d="M674.19,297.63c-8.46-21.2-28.09-21.76-37.64-22.58-7.78-.66-37.08.93-47.69,1.54-2.17.13-3.86,1.92-3.86,4.1v119.88c0,1.74,1.41,3.14,3.14,3.14h14.17c1.74,0,3.14-1.41,3.14-3.14v-34.16c45.01,4.23,52.91-1.5,60.82-8.86,8.8-8.2,15.13-37.91,7.91-59.92h.01ZM656.46,330.82c-.27,4.64-1.91,18-19.5,19.22-17.59,1.23-31.5-2.32-31.5-2.32v-54.21c4.62-.18,16.65-.61,25.09-.61,10.64,0,15.27,1.5,21.82,8.32s4.37,24.96,4.09,29.59h0Z"/>
+    <circle class="st2" cx="703.1" cy="250.37" r="14.18"/>
+    <path class="st0" d="M784.34,292.92c1.41,0,2.56-1.15,2.56-2.56v-11.6c0-1.41-1.15-2.56-2.56-2.56h-27.3v-19.11c0-1.32-1.07-2.38-2.38-2.38h-14.87c-1.32,0-2.38,1.07-2.38,2.38v19.11h-10.74c-1.41,0-2.56,1.15-2.56,2.56v11.6c0,1.41,1.15,2.56,2.56,2.56h10.74v48.61c0,14.46,11.72,26.19,26.19,26.19h19.46c2.13,0,3.86-1.73,3.86-3.86v-9.69c0-2.13-1.73-3.86-3.86-3.86h-13.53c-6.9,0-12.48-5.59-12.48-12.48v-44.92h27.3-.01Z"/>
+  </g>
+</svg>

package/docs/public/hypit-logo-light.svg

@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" viewBox="54.9 186.2 732.1 222.8">
+  <!-- Generator: Adobe Illustrator 30.0.0, SVG Export Plug-In . SVG Version: 2.1.1 Build 123)  -->
+  <defs>
+    <style>
+      .st1 {
+        fill: url(#linear-gradient);
+      }
+
+      .st2 {
+        fill: #e83f5f;
+      }
+
+      .st3 {
+        fill: #fff;
+      }
+    </style>
+    <linearGradient id="linear-gradient" x1="103.04" y1="194.28" x2="261.09" y2="393.77" gradientTransform="translate(0 .83)" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#e83f5f"/>
+      <stop offset=".14" stop-color="#e94765"/>
+      <stop offset=".33" stop-color="#ec5774"/>
+      <stop offset=".56" stop-color="#f1738c"/>
+      <stop offset=".8" stop-color="#f599af"/>
+      <stop offset=".88" stop-color="#f6a9bd"/>
+    </linearGradient>
+  </defs>
+  <g id="Layer_11" data-name="Layer_1">
+  </g>
+  <g id="Layer_2">
+    <path class="st1" d="M303.78,277.82c-5.98-8.63-15.83-13.77-26.32-13.77h-93.41c-12.28,0-24.92,7.44-29.6,18.8l-28.26,75.82c-4.6,11.25-4.54,24.05,2.22,34.16,6.79,10.15,19.36,16.15,31.57,16.15h85.98c14.12,0,26.9-8.88,31.84-22.1l29.69-79.57c3.67-9.84,2.29-20.86-3.69-29.48v-.02h-.02ZM252.02,377.25c-.94,2.52-3.39,4.22-6.08,4.22h-83.45c-4.34,0-6.68-2.8-7.49-3.99s-2.5-4.43-.84-8.44l23.85-66.24c2.29-6.35,8.08-10.87,14.82-11.22.33-.02.67-.02,1.02-.02h75.41s12.51,1.42,9.29,14.61l-26.53,71.09h0ZM106.85,361.73s-22.36-11.59-17.66-32.66l29.67-82.23c4.78-13.25,17.36-22.09,31.45-22.09h95.02c6.25,0,12.1,3.03,15.71,8.14l13.89,19.68h-112.97c-8.7,0-16.49,5.41-19.52,13.57l-35.59,95.6h0ZM73.3,323.27s-22.37-11.59-17.66-32.66l29.67-82.23c4.79-13.25,17.37-22.09,31.45-22.09h89.91c6.25,0,12.1,3.03,15.71,8.14l13.89,19.68h-107.84c-8.7,0-16.49,5.41-19.52,13.57l-35.59,95.6h-.02Z"/>
+    <rect class="st3" x="692.47" y="276.19" width="19.22" height="90.09" rx="4.12" ry="4.12"/>
+    <path class="st3" d="M462.31,293.32c-4.51-11.11-12.93-15.68-28.26-17.66-15.52-2-31.17,1.58-36.41,2.96v-38.42c0-2.22-1.8-4.02-4.02-4.02h-11.19c-2.22,0-4.02,1.8-4.02,4.02v123.26c0,2.22,1.8,4.02,4.02,4.02h11.19c2.22,0,4.02-1.8,4.02-4.02v-66.25c3.68-1.46,16.84-6.13,30.89-4.57,12.12,1.35,15.81,10.13,16.92,14.75.32,1.33.47,2.68.47,4.03v53.36c0,1.49,1.2,2.68,2.68,2.68h13.65c1.49,0,2.68-1.2,2.68-2.68v-57.38c0-4.82-.82-9.63-2.63-14.09h.01Z"/>
+    <path class="st3" d="M568.55,346.34v-67.42c0-1.57-1.27-2.85-2.85-2.85h-14.66c-1.57,0-2.85,1.27-2.85,2.85v64.51c0,.58-.19,1.16-.58,1.6-1.62,1.88-7.33,6.23-25.19,5.92-2.22.05-6.37-.58-8.51-1.13-14.03-3.61-12.62-17.41-12.62-33.16v-37.73c0-1.57-1.27-2.85-2.85-2.85h-13.68c-1.57,0-2.85,1.27-2.85,2.85v57.63s-2.72,24.49,25.91,30.92c0,0,3.11.67,7.45,1.01h-.02s.13,0,.38.03c.07,0,.15,0,.23.02.19.02.42.02.69.04.25.02.51.02.77.04,2.94.14,8.59.25,14.08-.44h-.05c6.97-.77,13.42-2.51,17.37-5.02,0,0-1.77,20.45-18.82,23.73-9.86,1.13-24.24-.46-31.62-1.65-2.22-.36-4.33,1.06-4.84,3.24l-2.55,10.92c-.49,2.08.99,4.09,3.1,4.28,7.44.63,23.6,1.84,34.54,1.37,14.62-.61,26.8-6.24,34.06-21.17,7.26-14.93,5.93-37.54,5.93-37.54h.03Z"/>
+    <path class="st3" d="M674.19,297.63c-8.46-21.2-28.09-21.76-37.64-22.58-7.78-.66-37.08.93-47.69,1.54-2.17.13-3.86,1.92-3.86,4.1v119.88c0,1.74,1.41,3.14,3.14,3.14h14.17c1.74,0,3.14-1.41,3.14-3.14v-34.16c45.01,4.23,52.91-1.5,60.82-8.86,8.8-8.2,15.13-37.91,7.91-59.92h.01ZM656.46,330.82c-.27,4.64-1.91,18-19.5,19.22-17.59,1.23-31.5-2.32-31.5-2.32v-54.21c4.62-.18,16.65-.61,25.09-.61,10.64,0,15.27,1.5,21.82,8.32s4.37,24.96,4.09,29.59h0Z"/>
+    <circle class="st2" cx="703.1" cy="250.37" r="14.18"/>
+    <path class="st3" d="M784.34,292.92c1.41,0,2.56-1.15,2.56-2.56v-11.6c0-1.41-1.15-2.56-2.56-2.56h-27.3v-19.11c0-1.32-1.07-2.38-2.38-2.38h-14.87c-1.32,0-2.38,1.07-2.38,2.38v19.11h-10.74c-1.41,0-2.56,1.15-2.56,2.56v11.6c0,1.41,1.15,2.56,2.56,2.56h10.74v48.61c0,14.46,11.72,26.19,26.19,26.19h19.46c2.13,0,3.86-1.73,3.86-3.86v-9.69c0-2.13-1.73-3.86-3.86-3.86h-13.53c-6.9,0-12.48-5.59-12.48-12.48v-44.92h27.3-.01Z"/>
+  </g>
+</svg>

package/examples/README.md

@@ -0,0 +1,24 @@
+# Video examples
+
+Each of the three formats has one complete generation entry, `reference.svml`, with an adjacent
+`reference.svrun`. These Sources generate their main images, recurring voice references and video
+Takes, then normalize media, align the Script and compose the finished video. They need no earlier
+Build Result or manually supplied presenter, host or scene image.
+
+| Example | What its reference entry demonstrates |
+| --- | --- |
+| [Football ranking](ranking-football/README.md) | One generated goth host, eight generated comic B-roll images, real player icons, independent speaking Takes and a persistent tier board |
+| [Podcast](podcast/README.md) | Related host views, a generated creatine product, holding views, a split opening and a three-scene lifestyle montage |
+| [Street interview](interview/README.md) | A shared encounter and two derived close views, motivated cuts, coordinated Moment reveals, and a fresh-footage Caption tracking extension |
+
+Self-contained here means a project directory: SVML, its imported SVS/Kits and the selected local
+assets. The installed Hypit Distribution supplies the imported packages. A Runtime Profile and
+credentials supply execution; the Sources contain neither. Real identifiers, prepared reveal art,
+music and sound effects may remain explicit local assets. Copy the whole example directory when
+using it outside this repository.
+
+The other `swap-*` and nested projects preserve separate variations and reuse studies. They have not
+all been rebuilt to the same generation standard as these three reference entries. A linked showcase
+video demonstrates the original production; a fresh generation is a new result and will differ.
+
+`minimal-author-package/` demonstrates independent component packaging.

package/examples/minimal-author-package/README.md

@@ -0,0 +1,18 @@
+# Minimal author-package fixture
+
+The `packages/example-component` directory contains a small complete Author Package. Its `preview/`
+asset demonstrates a Surface preview, and its Style Surface reads an SVS Recipe and exact FontStackRef.
+The Distribution includes these sources. The package README explains copying it into a video project,
+selecting a released Hypit development dependency, compiling it and sharing its tarball.
+
+The fixture's Surface decoder also demonstrates the public value boundary: Style-like values consume
+a decoded recipe shaped as `{ path, properties }`, exact `FontStackRef` records and inline values
+only after checking `record.value.kind === "inline"`. Media slots remain graph inputs rather than
+package files.
+
+The package builds against one public Hypit framework dependency, `hypit`, and emits JavaScript.
+`pnpm --dir packages/example-component pack` produces a tarball with no Runtime dependencies of its
+own. Installing that tarball in another project and importing `@example/example-component@1` loads
+the same Module and Surface through the consumer's active Hypit Distribution. The packaged
+`@example/example-component/preview` Source exists so this boundary can be checked without copying a
+Source out of the package.

package/examples/minimal-author-package/packages/example-component/README.md

@@ -0,0 +1,44 @@
+# Example component fixture
+
+A small complete package for learning Manifest, Surface, Fragment, Producer and activation wiring. Framework-facing imports come from
+`@hypit/hypit/author-kit`; video-domain imports use their owning `@hypit/hypit/*` subpaths. Its only Hypit
+framework dependency is the released `@hypit/hypit` Distribution; TypeScript and Node types are ordinary
+build tooling. No Runtime dependency is bundled into its tarball.
+
+It contains a Module Manifest with nominal Types and deterministic Producers, validators, a structured
+Surface decoder returning `records`, `components`, `fragments` and `exports`, and sealed Fragments with
+literal `fragment-input`, `fragment-operation` and `output` references. `src/temporal.ts` shows the
+Surface-side `@hypit/hypit/temporal-markup` Window/Moment projections; that package is distinct from the
+graph-side `@hypit/hypit/temporal` Producers.
+
+The Surfaces demonstrate a box, a text surface, a media slot and a Style decoder. The slot is a graph
+input; it is not a file bundled by the package. `preview/Box.png` is a real catalogue frame supplied
+by the package's vocabulary. `exampleAppendFragment` and `append-example-items` show a fixed-port
+append that can be chained once per child.
+
+While the component belongs to one project, keep this directory under that project's `packages/`
+and use its owner-scoped package name. If the owner chooses to share it, compile and publish the same
+package through npm or a private registry. Consumers install a chosen release with their ordinary
+package manager and commit the resulting lockfile. The Source's logical Module import remains the
+same whether the package is linked from the project workspace or installed from a registry.
+
+## Use the included source outside the Hypit repository
+
+Copy this directory into the video project's `packages/` and give the package and Module the owner's
+name. The checked-in fixture's `workspace:*` dependency connects it to the repository during Hypit
+development. In the copied package, replace that development dependency with the selected release:
+
+```bash
+npm install --save-dev @hypit/hypit@<selected-release>
+npm run build
+npm pack
+```
+
+If the selected Distribution was supplied as a tarball, use its path in the install command instead.
+Installing it as a development dependency supplies public types; the consumer's active Hypit
+Distribution supplies the runtime APIs. The resulting component tarball contains its own built code
+and preview assets. For registry publication, select a release version and remove the fixture's
+`private: true` after the owner chooses to publish it.
+
+The active Distribution's `packages/ranking/README.md` is the richer example for semantic input
+projection, persistent visual state and a Companion. Its README and source ship with that Distribution.

package/examples/minimal-author-package/packages/example-component/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@example/example-component",
+  "version": "0.0.0-dev",
+  "private": true,
+  "type": "module",
+  "files": [
+    "dist",
+    "preview",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./preview": "./preview/preview.svml"
+  },
+  "hypit": {
+    "activation": "./dist/activation.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.1",
+    "@hypit/hypit": "workspace:*",
+    "typescript": "5.9.3"
+  }
+}

package/examples/minimal-author-package/packages/example-component/preview/build.svrun

@@ -0,0 +1,6 @@
+<?svml using="@hypit/run-markup@1"?>
+
+<svrun version="1">
+  <author source="./preview.svml"/>
+  <target output="final.video"/>
+</svrun>

package/examples/minimal-author-package/packages/example-component/preview/preview.svml

@@ -0,0 +1,47 @@
+<?svml using="@hypit/markup@1"?>
+
+<!-- A complete catalogue Source. Its Run is ordinary: Studio can open it once the required media
+     Candidates are supplied, and a normal Build of the same Run can regenerate the catalogue frame. -->
+<svml>
+  <import as="media-track" from="@hypit/media-track@1"/>
+  <import from="@hypit/script@1"/>
+  <import as="wording" from="@hypit/text@1"/>
+  <import as="seedance" from="@hypit/seedance@1"/>
+  <import as="pipeline" from="@hypit/media-pipeline@1"/>
+  <import as="speech" from="@hypit/speech-track@1"/>
+  <import as="whisperx" from="@hypit/whisperx@1"/>
+  <import as="space" from="@hypit/spatial@1"/>
+  <import as="program" from="@hypit/program-space@1"/>
+  <import as="film" from="@hypit/film@1"/>
+  <import as="render" from="@hypit/render-hyperframes@1"/>
+  <import as="example" from="@example/example-component@1"/>
+  <import as="recipes" source="./recipes.svs"/>
+
+  <script id="story">
+    <showcase><HOST>A deterministic example surface for the package catalogue.</showcase>
+  </script>
+
+  <space:Canvas id="vertical" width="720" height="1280"/>
+  <program:Clock id="clock" frame-rate="30"/>
+  <space:Frame id="speech-frame" within={vertical} left="0%" top="0%" right="100%" bottom="100%"/>
+
+  <wording:Value id="direction">A neutral catalogue card in a quiet studio.</wording:Value>
+  <seedance:TextVideo id="take" model="mini" prompt={direction} duration="4" generate-audio="true"/>
+  <pipeline:Normalize id="take-media" source={take.video} recipe={recipes.media.aroll} clock={clock}/>
+  <whisperx:SemanticTake id="showcase-semantic" narrative={story} segment={story.segment.showcase} media={take-media.media} language="en"/>
+  <speech:Track id="speech">
+    <speech:Take source={showcase-semantic.take}/>
+  </speech:Track>
+  <media-track:Track id="speech-picture" semantic={speech.semantic} canvas={vertical}>
+    <media-track:Performance during="program" frame={speech-frame}
+      appearance={recipes.media.performance}/>
+  </media-track:Track>
+
+  <example:Box id="box" semantic={speech.semantic}/>
+  <film:Film id="main" canvas={vertical} semantic={speech.semantic} appearance={recipes.film.vertical}>
+    <film:Track source={speech-picture.visual}/>
+    <film:Track source={speech.audio}/>
+    <film:Track source={box.track}/>
+  </film:Film>
+  <render:Video id="final" composition={main.composition} semantic={speech.semantic}/>
+</svml>

package/examples/minimal-author-package/packages/example-component/preview/recipes.svs

@@ -0,0 +1,8 @@
+<?svml using="@hypit/svs@1"?>
+
+<sheet version="1">
+  film.vertical { background: #09090B; }
+  media.performance { stack-order: 0; fit: cover; }
+  speech.normal { language: en; pace: normal; rounding: round; }
+  media.aroll { video: primary-moving; audio: default; span-authority: video; }
+</sheet>

package/examples/minimal-author-package/packages/example-component/src/activation.ts

@@ -0,0 +1,10 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/hypit/author-kit";
+import { decodeExampleSurface, exampleComponent, exampleManifest, exampleMarkupSurfaces, exampleModuleRef } from "./index.js";
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{ manifest: exampleManifest }],
+  components: [exampleComponent],
+  hostFacets: exampleMarkupSurfaces.map((declaration) => createMarkupSurfaceHostFacet({ module: exampleModuleRef, declaration, handler: decodeExampleSurface })),
+};
+export default hypitPackage;

package/examples/minimal-author-package/packages/example-component/src/component.ts

@@ -0,0 +1,44 @@
+import { sealVisualTrack } from "@hypit/hypit/composition";
+import type { ProgramSpace } from "@hypit/hypit/program-space";
+import { canonicalize } from "@hypit/hypit/author-kit";
+import type { BlobRef, ComponentPackage, ProducerHandler, TypedRecord } from "@hypit/hypit/author-kit";
+import { VISUAL_IR_V1 } from "@hypit/hypit/visual-ir";
+import { exampleProducers, exampleTypes } from "./manifest.js";
+
+const inline = <T>(record: { readonly value: { readonly kind: string; readonly value?: unknown } } | undefined): T => {
+  if (record?.value.kind !== "inline") throw new Error("example producer input must be inline");
+  return record.value.value as T;
+};
+const output = (value: unknown) => ({ kind: "inline" as const, value: canonicalize(value) });
+function blob(record: TypedRecord | undefined): BlobRef | undefined {
+  return record?.value.kind === "blob" ? record.value : undefined;
+}
+function render(kind: string, space: ProgramSpace, media?: BlobRef) {
+  const frames = Math.max(1, Math.round(space.durationSec * space.frameRate.numerator / space.frameRate.denominator));
+  return sealVisualTrack({
+    programSpaceId: space.id,
+    visualIr: VISUAL_IR_V1,
+    id: `example-${kind}`,
+    presents: [{ id: `present-${kind}`, span: { startFrame: 0, endFrameExclusive: frames }, stacking: { order: 0, tieBreak: kind }, elements: [{
+      id: `${kind}-root`, kind: "box", order: 0,
+      style: [{ name: "background-color", value: "#6b7280" }],
+    }, ...(kind === "media" && media !== undefined ? [{ id: `${kind}-content`, parent: `${kind}-root`, kind: media.mediaType.startsWith("video/") ? "video" as const : "image" as const, artifact: media, order: 1, style: [{ name: "position", value: "absolute" }, { name: "left", value: 0 }, { name: "top", value: 0 }, { name: "width", value: "100%" }, { name: "height", value: "100%" }, { name: "object-fit", value: "contain" }] }] : []),
+    ] }],
+  });
+}
+const producer = (kind: string): { readonly handler: ProducerHandler } => ({ handler: ({ inputs }) => ({ outputs: { track: output(render(kind, inline<ProgramSpace>(inputs.space), blob(inputs.media))) }, needs: {} }) });
+const appendItems: { readonly handler: ProducerHandler } = { handler: ({ inputs }) => ({ outputs: { set: output({ items: [inline<{ items: readonly unknown[] }>(inputs.previous).items, inline<{ items: readonly unknown[] }>(inputs.item).items].flat() }) }, needs: {} }) };
+
+export const exampleComponent = {
+  producers: [
+    { producer: exampleProducers.renderBox, ...producer("box") },
+    { producer: exampleProducers.renderText, ...producer("text") },
+    { producer: exampleProducers.renderMedia, ...producer("media") },
+    { producer: exampleProducers.appendItems, ...appendItems },
+  ],
+  validators: [
+    { type: exampleTypes.box, handler: () => {} },
+    { type: exampleTypes.text, handler: () => {} },
+    { type: exampleTypes.mediaSlot, handler: () => {} },
+  ],
+} satisfies ComponentPackage;

package/examples/minimal-author-package/packages/example-component/src/fragment.ts

@@ -0,0 +1,32 @@
+import { compositionTypes } from "@hypit/hypit/composition";
+import { artifactTypes } from "@hypit/hypit/artifact";
+import { sealGraphFragment } from "@hypit/hypit/author-kit";
+import { semanticTrackProducers, semanticTrackTypes } from "@hypit/hypit/semantic-track";
+import { programSpaceTypes } from "@hypit/hypit/program-space";
+import { exampleProducers } from "./manifest.js";
+import { exampleTypes } from "./manifest.js";
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
+
+export function createExampleFragment(producer: typeof exampleProducers[keyof typeof exampleProducers], id: string, media = false) {
+  const inputs = [{ name: "semantic", type: semanticTrackTypes.track }, ...(media ? [{ name: "media", type: artifactTypes.blob }] : [])];
+  const renderInputs = { space: operation("space"), ...(media ? { media: input("media") } : {}) };
+  return sealGraphFragment({
+    inputs,
+    operations: [
+      { id: "space", producer: semanticTrackProducers.projectProgramSpace, inputs: { track: input("semantic") }, result: { kind: "output", name: "space" } },
+      { id, producer, inputs: renderInputs, result: { kind: "output", name: "track" } },
+    ],
+    exports: [{ name: "track", type: compositionTypes.visualTrack, root: operation(id) }],
+  });
+}
+
+export const exampleBoxFragment = createExampleFragment(exampleProducers.renderBox, "render-box");
+export const exampleTextFragment = createExampleFragment(exampleProducers.renderText, "render-text");
+export const exampleMediaFragment = createExampleFragment(exampleProducers.renderMedia, "render-media-slot", true);
+export const exampleAppendFragment = sealGraphFragment({
+  inputs: [{ name: "previous", type: exampleTypes.itemSet }, { name: "item", type: exampleTypes.itemSet }],
+  operations: [{ id: "append-items", producer: exampleProducers.appendItems, inputs: { previous: input("previous"), item: input("item") }, result: { kind: "output", name: "set" } }],
+  exports: [{ name: "set", type: exampleTypes.itemSet, root: operation("append-items") }],
+});

package/examples/minimal-author-package/packages/example-component/src/index.ts

@@ -0,0 +1,6 @@
+export { exampleComponent } from "./component.js";
+export { exampleAppendFragment, exampleBoxFragment, exampleMediaFragment, exampleTextFragment } from "./fragment.js";
+export { exampleManifest, exampleMarkupSurfaces, exampleModuleRef, exampleProducers, exampleTypes } from "./manifest.js";
+export { decodeExampleSurface } from "./surface.js";
+export { decodeExampleStyle } from "./style.js";
+export { projectExampleMoment, projectExampleWindow, temporalInstantAttributeNames, temporalWindowAttributeNames } from "./temporal.js";

package/examples/minimal-author-package/packages/example-component/src/manifest.ts

@@ -0,0 +1,82 @@
+import { readFile } from "node:fs/promises";
+import { compositionTypes } from "@hypit/hypit/composition";
+import type { ModuleManifest, ProducerRef, TypeRef } from "@hypit/hypit/author-kit";
+import { programSpaceTypes } from "@hypit/hypit/program-space";
+import { semanticTrackTypes } from "@hypit/hypit/semantic-track";
+import { temporalTypes } from "@hypit/hypit/temporal";
+import { mediaTypes } from "@hypit/hypit/media";
+import { svsRecipeType } from "@hypit/hypit/svs";
+import { artifactTypes } from "@hypit/hypit/artifact";
+
+const previewImage = (file: string) => ({
+  mediaType: "image/png",
+  path: `preview/${file}`,
+  open: async () => Uint8Array.from(await readFile(new URL(`../preview/${file}`, import.meta.url))),
+});
+
+export const exampleModuleRef = { name: "@example/example-component", version: "1" } as const;
+export const exampleTypes = {
+  box: { module: exampleModuleRef, name: "ExampleBox" },
+  text: { module: exampleModuleRef, name: "ExampleText" },
+  mediaSlot: { module: exampleModuleRef, name: "ExampleMediaSlot" },
+  style: { module: exampleModuleRef, name: "ExampleStyle" },
+  itemSet: { module: exampleModuleRef, name: "ExampleItemSet" },
+} satisfies Record<string, TypeRef>;
+export const exampleProducers = {
+  renderBox: { module: exampleModuleRef, name: "render-example-box" },
+  renderText: { module: exampleModuleRef, name: "render-example-text" },
+  renderMedia: { module: exampleModuleRef, name: "render-example-media-slot" },
+  appendItems: { module: exampleModuleRef, name: "append-example-items" },
+} satisfies Record<string, ProducerRef>;
+
+export const exampleManifest: ModuleManifest = {
+  format: "hypit.module@1", name: exampleModuleRef.name, version: exampleModuleRef.version,
+  dependencies: [
+    { module: artifactTypes.blob.module },
+    { module: compositionTypes.visualTrack.module },
+    { module: mediaTypes.fontStack.module },
+    { module: programSpaceTypes.programSpace.module },
+    { module: semanticTrackTypes.track.module },
+    { module: svsRecipeType.module },
+    { module: temporalTypes.window.module },
+  ],
+  types: Object.values(exampleTypes).map(({ name }) => ({ name })),
+  capabilities: [],
+  producers: Object.values(exampleProducers).map((producer) => ({
+    name: producer.name,
+    inputs: producer === exampleProducers.appendItems
+      ? [{ name: "previous", type: exampleTypes.itemSet }, { name: "item", type: exampleTypes.itemSet }]
+      : [{ name: "space", type: programSpaceTypes.programSpace }, ...(producer === exampleProducers.renderMedia ? [{ name: "media", type: artifactTypes.blob }] : [])],
+    outputs: producer === exampleProducers.appendItems
+      ? [{ name: "set", type: exampleTypes.itemSet }]
+      : [{ name: "track", type: compositionTypes.visualTrack }],
+    needs: [],
+  })),
+};
+
+const vocabulary = (summary: string, example: string) => ({
+  summary,
+  appearance: "A deterministic, self-contained example surface rendered on the supplied ProgramSpace.",
+  preview: previewImage("Box.png"),
+  attributes: [
+    { name: "id", kind: "identifier" as const, required: true, summary: "Names this instance." },
+    { name: "semantic", kind: "reference" as const, required: true, accepts: [semanticTrackTypes.track], summary: "Selects the semantic timing track." },
+  ],
+  ports: [{ name: "track", type: compositionTypes.visualTrack, summary: "The terminal VisualTrack." }],
+  example,
+  notes: ["The same shape is used for box, text and media-slot surfaces; only the terminal Producer changes."],
+});
+
+export const exampleMarkupSurfaces = [
+  { name: "box", tag: "Box", mode: "structured", outputs: [exampleTypes.box, compositionTypes.visualTrack], vocabulary: { ...vocabulary("A framed box surface.", "<example:Box id=\"box\" semantic={speech.semantic}/>") , preview: previewImage("Box.png") } },
+  { name: "text", tag: "Text", mode: "structured", outputs: [exampleTypes.text, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, compositionTypes.visualTrack], vocabulary: { ...vocabulary("A text-bearing surface.", "<example:Text id=\"title\" semantic={speech.semantic}>Hello</example:Text>"), preview: previewImage("Box.png") } },
+  { name: "media-slot", tag: "MediaSlot", mode: "structured", outputs: [exampleTypes.mediaSlot, compositionTypes.visualTrack], vocabulary: { ...vocabulary("A media slot whose content is a graph input.", "<example:MediaSlot id=\"shot\" semantic={speech.semantic} media={shot-media}/>") , attributes: [...vocabulary("", "").attributes, { name: "media", kind: "reference" as const, required: false, accepts: [artifactTypes.blob], summary: "Optional image or video Blob Artifact." }], preview: previewImage("Box.png") } },
+  { name: "style", tag: "Style", mode: "structured", outputs: [exampleTypes.style], vocabulary: {
+    summary: "Decodes one SVS Recipe and exact FontStackRef into a Style value.",
+    attributes: [
+      { name: "id", kind: "identifier", required: true, summary: "Names this Style." },
+      { name: "recipe", kind: "reference", required: true, accepts: [svsRecipeType], summary: "The decoded recipe with path and properties." },
+      { name: "font", kind: "reference", required: true, accepts: [mediaTypes.fontStack], summary: "An exact FontStackRef." },
+    ], example: "<example:Style id=\"card\" recipe={recipes.card} font={caption-font}/>",
+  } },
+] as const;

package/examples/minimal-author-package/packages/example-component/src/style.ts

@@ -0,0 +1,13 @@
+import type { FontStackRef } from "@hypit/hypit/media";
+import type { SvsRecipe } from "@hypit/hypit/svs";
+
+/** The two values a Style decoder receives after author references are resolved. */
+export type ExampleStyleInput = {
+  readonly recipe: { readonly path: string; readonly properties: SvsRecipe["properties"] };
+  readonly fonts: FontStackRef;
+};
+
+/** A deliberately small, runnable Style boundary for the fixture. */
+export function decodeExampleStyle(input: ExampleStyleInput): { readonly recipe: ExampleStyleInput["recipe"]; readonly fonts: FontStackRef } {
+  return { recipe: { path: input.recipe.path, properties: { ...input.recipe.properties } }, fonts: input.fonts };
+}

package/examples/minimal-author-package/packages/example-component/src/surface.ts

@@ -0,0 +1,41 @@
+import type { StructuredElement, StructuredSurfaceHandler, SurfaceComponentDraft, SurfaceRecordDraft, SurfaceResolvedReference } from "@hypit/hypit/author-kit";
+import { exampleBoxFragment, exampleMediaFragment, exampleTextFragment } from "./fragment.js";
+import { exampleMarkupSurfaces, exampleTypes } from "./manifest.js";
+import { mediaTypes } from "@hypit/hypit/media";
+import { svsRecipeType } from "@hypit/hypit/svs";
+import { artifactTypes } from "@hypit/hypit/artifact";
+
+function text(element: StructuredElement, name: string): string {
+  const value = element.attributes[name];
+  if (typeof value !== "string" || value.trim().length === 0) throw new Error(`${element.name}.${name} must be text.`);
+  return value.trim();
+}
+function reference(element: StructuredElement, name: string, resolve: (path: string) => SurfaceResolvedReference | undefined): SurfaceResolvedReference {
+  const value = element.attributes[name];
+  if (typeof value !== "object" || value.kind !== "reference") throw new Error(`${element.name}.${name} must be a reference.`);
+  const resolved = resolve(value.path);
+  if (resolved === undefined) throw new Error(`${element.name}.${name} cannot resolve ${value.path}`);
+  return resolved;
+}
+
+export const decodeExampleSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  const id = text(element, "id");
+  if (element.name.endsWith(":Style")) {
+    const recipe = reference(element, "recipe", resolveReference);
+    const font = reference(element, "font", resolveReference);
+    if (recipe.type.module.name !== svsRecipeType.module.name || recipe.type.name !== svsRecipeType.name) throw new Error("Style.recipe must be an SVS Recipe.");
+    if (font.type.module.name !== mediaTypes.fontStack.module.name || font.type.name !== mediaTypes.fontStack.name) throw new Error("Style.font must be a FontStackRef.");
+    if (recipe.record?.value.kind !== "inline" || font.record?.value.kind !== "inline") throw new Error("Style references must resolve to inline records.");
+    return { records: [{ id, type: exampleTypes.style, value: { kind: "inline", value: { recipe: recipe.record.value.value, fonts: font.record.value.value } }, range: element.range }], components: [], fragments: [], exports: [id] };
+  }
+  const semantic = reference(element, "semantic", resolveReference);
+  const surface = exampleMarkupSurfaces.find((item) => item.tag === element.name.split(":").at(-1));
+  if (surface === undefined) throw new Error(`Unknown example surface ${element.name}`);
+  const fragment = surface.name === "box" ? exampleBoxFragment : surface.name === "text" ? exampleTextFragment : exampleMediaFragment;
+  const type = surface.name === "box" ? exampleTypes.box : surface.name === "text" ? exampleTypes.text : exampleTypes.mediaSlot;
+  const record: SurfaceRecordDraft = { id: `${id}.value`, type, value: { kind: "inline", value: { id } }, range: element.range };
+  const media = element.attributes.media === undefined ? undefined : reference(element, "media", resolveReference);
+  if (media !== undefined && (media.type.module.name !== artifactTypes.blob.module.name || media.type.name !== artifactTypes.blob.name)) throw new Error(`${element.name}.media must be a Blob Artifact.`);
+  const component: SurfaceComponentDraft = { id, fragment: fragment.id, inputs: { semantic: semantic.ref, ...(media === undefined ? {} : { media: media.ref }) }, outputs: { track: `${id}.track` }, range: element.range };
+  return { records: [record], components: [component], fragments: [fragment], exports: [`${id}.value`, `${id}.track`] };
+};

package/examples/minimal-author-package/packages/example-component/src/temporal.ts

@@ -0,0 +1,6 @@
+import { createTemporalInstantProjection, createTemporalWindowProjection, temporalInstantAttributeNames, temporalWindowAttributeNames } from "@hypit/hypit/temporal-markup";
+
+/** The fixture intentionally exposes both projection helpers and their vocabularies. */
+export { temporalInstantAttributeNames, temporalWindowAttributeNames };
+export const projectExampleWindow = createTemporalWindowProjection;
+export const projectExampleMoment = createTemporalInstantProjection;