@osmo.inc/cli 0.1.15

package/runtime/packages/scene/src/elements.ts

@@ -0,0 +1,491 @@
+import type { EffectInstance } from "./effects.js";
+import type { KnobRef, KnobSet, KnobBindings } from "./knobs.js";
+import type { Knobs } from "./knob-schema.js";
+import type { Motion, MotionValue } from "./motion.js";
+
+export type Vec2 = readonly [number, number];
+export type Vec3 = readonly [number, number, number];
+/** Hex #RGB/#RGBA/#RRGGBB/#RRGGBBAA or transparent; no CSS color names. */
+export type Color = `#${string}` | "transparent";
+/** JSX accepts compatible knob references and numeric motion tracks, including tuple components.
+ * Scene metadata and media timing stay static; CLI Strict also checks expression syntax. */
+export type Input<T> = KnobRef<T> | (T extends number
+	? T | Motion<T>
+	: T extends readonly number[]
+		? T | Motion<T> | { readonly [K in keyof T]: Input<T[K]> }
+		: T extends object
+			? { readonly [K in keyof T]: Input<T[K]> }
+			: T);
+export type InputProps<P> = {
+	[K in keyof P]: K extends "children"
+        ? P[K] extends string | number ? P[K] | KnobRef<P[K]> : P[K]
+        : K extends
+        | "id"
+        | "label"
+        | "hidden"
+        | "solo"
+        | "track"
+        | "knobs"
+        | "values"
+		| "effects"
+        | "mask"
+		| "d"
+		| "start"
+		| "duration"
+		| "trimIn"
+		| "playbackRate"
+		? P[K]
+		: Input<P[K]>;
+};
+
+export interface FrameContext {
+	readonly frame: number;
+	readonly time: number;
+	readonly fps: number;
+	readonly width: number;
+	readonly height: number;
+	readonly duration: number;
+}
+/** Shared clip contract. Root clips require track in Studio; nested layers omit it.
+ * Existing scenes without tracks are upgraded when opened in the timeline. */
+export interface ClipProps {
+	/** Stable source identity, unique within its animation file. */
+	id?: string;
+	/** Literal root timeline lane, 0–99. Required at the Scene root; forbidden on nested layers. Does not change paint order. */
+	track?: number;
+	/** Start in the parent clock, in seconds. Motion uses time relative to this start. Default: 0. */
+	start?: number;
+	/** Visible window in seconds; omitted means remaining parent duration. Trimming does not stretch motion. */
+	duration?: number;
+}
+/** Explicit contract for root clips; JSX parent placement is checked by the validator. */
+export interface RootClipProps extends ClipProps { track: number; }
+export interface TransformProps extends ClipProps {
+	/** Applied in array order; each pass receives the previous result. Default: none. */
+	effects?: readonly EffectInstance[];
+	/** Local [x, y] in pixels; +X right, +Y down. Default: [0, 0]. */
+	position?: Vec2;
+	/** Depth in composition pixels; positive is toward the viewer. */
+	z?: number;
+	/** Clockwise degrees around origin. Default: 0. */
+	rotation?: number;
+	/** Uniform factor or [x, y] factors. Default: 1. */
+	scale?: number | Vec2;
+	/** Local pivot in pixels, not a fraction. Default: [0, 0]. */
+	origin?: Vec2;
+	/** 0–1. Group opacity composites its children together. Default: 1. */
+	opacity?: number;
+}
+export interface SceneProps {
+	/** Optional lane metadata keyed by track number (0–99). Labels are static, one word maximum. Does not change paint order. */
+	tracks?: Readonly<Record<number, TrackMetadata>>;
+	/** Filter the complete viewport, including 3D surfaces; array order matters. */
+	effects?: readonly EffectInstance[];
+	/** Positive composition width in pixels; static. */
+	width: number;
+	/** Positive composition height in pixels; static. */
+	height: number;
+	/** Positive duration in seconds; static. */
+	duration: number;
+	/** Positive frames per second; static. Default: 30. */
+	fps?: number;
+	/** Fixed viewport backdrop, independent of camera and layout. Default: transparent. */
+	background?: Color;
+	children?: Child;
+}
+/** Timeline lane metadata; independent of the clips occupying the lane. */
+export interface TrackMetadata {
+	/** Optional static display name, one word maximum, e.g. "Titles". */
+	label?: string;
+	/** Hide this lane's visuals; audio continues unless muted. Default: false. */
+	hidden?: boolean;
+	/** Play only soloed lanes, including their audio. Multiple lanes can be soloed. Default: false. */
+	solo?: boolean;
+	/** Silence all Audio/Video descendants on this lane; visuals continue. Default: false. */
+	muted?: boolean;
+}
+export interface CameraProps {
+	/** Composition coordinates; defaults to the scene center. */
+	position?: Vec2;
+	/** Camera depth in composition pixels; defaults to 2000. */
+	z?: number;
+	/** World-space point to look at; defaults to scene center at z=0. */
+	target?: Vec3;
+	/** Vertical field of view in degrees; defaults to the existing framing. */
+	fov?: number;
+}
+export interface Stroke {
+	color: Color;
+	width: number;
+}
+export type Mask = string | false | { source: string; mode?: "alpha" | "vector" | "luminance"; invert?: boolean };
+export interface GroupStyleProps extends TransformProps {
+    /** Direct child used as a mask; false disables it. Default mode: alpha. */
+    mask?: Mask;
+    /** Hide this group's visuals without changing layout, timing or audio. */
+    hidden?: boolean;
+    /** Isolate this group among its siblings, including audio. Multiple solos are allowed. */
+    solo?: boolean;
+	/** Optional static display name, two words maximum, e.g. "Orbiting circles". Separate from stable id. */
+	label?: string;
+	/** Thickness behind the front face in pixels; nonnegative. Default: 0 (flat). */
+	depth?: number;
+	/** Sides/back color; defaults to fill, with directional shading. Front effects do not filter sides. */
+	sideFill?: Color;
+	/** Pixels, fill (parent size), or auto (content). Omitted: parent size in free layout, content in flow layout. */
+	width?: number | "auto" | "fill";
+	/** Pixels, fill (parent size), or auto (content). Omitted: parent size in free layout, content in flow layout. */
+	height?: number | "auto" | "fill";
+	/** free: positioned children; row/column: flow layout. Default: free. */
+	layout?: "free" | "row" | "column";
+	/** Nonnegative spacing between flow children, in pixels. Default: 0. */
+	gap?: number;
+	/** Pixels on all sides or [top, right, bottom, left]. Default: 0. */
+	padding?: number | readonly [number, number, number, number];
+	/** Cross-axis alignment in flow layout. Default: start. */
+	align?: "start" | "center" | "end" | "stretch";
+	/** Main-axis distribution in flow layout. Default: start. */
+	justify?: "start" | "center" | "end" | "spaceBetween" | "spaceAround";
+	/** Solid background color. Default: transparent. */
+	fill?: Color;
+	/** Border color and nonnegative width in pixels; omitted by default. */
+	stroke?: Stroke;
+	/** Nonnegative box corner radius in pixels. Default: 0. */
+	rounding?: number;
+	/** Use ellipse for circles/ovals; box for panels and thin lines. Default: box. */
+	shape?: "box" | "ellipse";
+	/** Clip children to the group shape. Default: true. Set false to allow overflow.
+	 * Effects such as blur still spill past the default clip; write `clip` explicitly to bound them to the shape too. */
+	clip?: boolean;
+	children?: Child;
+}
+export type GroupProps<K extends Knobs = Knobs> = GroupStyleProps & (
+  | {
+      /** Own a defineKnobs scope. Descendants can bind this set's references. */
+      knobs: KnobSet<K>;
+      /** Override knob defaults with literals, motion tracks, or parent knob references. */
+      values?: KnobBindings<NoInfer<K>>;
+    }
+  | { knobs?: never; values?: never }
+);
+/** Props accepted by a reusable Group imported from a local TSX file.
+ * values override its declared knobs; children and knob definitions belong to the source. */
+export type GroupInstanceProps = Omit<InputProps<GroupStyleProps>, "children"> & {
+	values?: Readonly<Record<string, MotionValue | Motion | KnobRef>>;
+};
+/** Placement of an imported Scene. Viewport overrides belong to this instance. */
+export type SceneInstanceProps = InputProps<TransformProps & {
+    /** Viewport width in pixels; defaults to the source scene width. Does not scale content. */
+    width?: number;
+    /** Viewport height in pixels; defaults to the source scene height. Does not scale content. */
+    height?: number;
+}> & { label?: string; hidden?: boolean; solo?: boolean; trimIn?: number };
+/** JSX attribute contract for imported static Group documents (legacy) and Scenes. */
+export type GroupInstance = (props: GroupInstanceProps) => Element;
+export interface ImageProps extends TransformProps {
+	/** Local PNG/JPEG/WebP/SVG path, relative to this TSX file; no remote URLs. */
+	src: string;
+	/** Positive box width in pixels. */
+	width: number;
+	/** Positive box height in pixels. */
+	height: number;
+	/** cover crops; contain fits inside; fill stretches. Default: cover. */
+	fit?: "cover" | "contain" | "fill";
+	/** Corner radius in pixels. Default: 0. */
+	rounding?: number;
+}
+export type UniformValue = number | Vec2 | Vec3 | readonly [number, number, number, number];
+export interface ShaderProps extends TransformProps {
+	/** Local .wgsl path. Implement fn effect(uv: vec2f, time: f32) -> vec4f; return straight-alpha sRGB. */
+	src: string;
+	/** Sample the scene beneath; "replace" also replaces transparent sampled pixels. */
+	backdrop?: boolean | "replace";
+	/** Positive box width in pixels. */
+	width: number;
+	/** Positive box height in pixels. */
+	height: number;
+	/** Corner radius in pixels. Default: 0. */
+	rounding?: number;
+	/** Match every field in WGSL struct Uniforms: f32 or vec2f/vec3f/vec4f. Host binds uniforms automatically. */
+	uniforms?: Readonly<Record<string, UniformValue>>;
+}
+
+/** A selector is a unique GLB name or its document index. */
+export type ModelSelector = string | number;
+export interface ModelProps extends ClipProps {
+	/** Local .glb path. Uses the default GLB scene; inspect node/material/clip names before targeting them. */
+	src: string;
+	/** Composition [x, y] in pixels. Default: scene center. */
+	position?: Vec2;
+	/** Depth in pixels; positive toward the viewer. Default: 0. */
+	z?: number;
+	/** Positive model height in pixels, normalized from default-pose bounds. */
+	height: number;
+	/** [x, y, z] degrees in the asset’s right-handed Y-up space; composes Y × X × Z. Default: [0, 0, 0]. */
+	rotation?: Vec3;
+	/** Positive uniform factor. Default: 1. */
+	scale?: number;
+	/** 0–1. Default: 1. */
+	opacity?: number;
+	/** GLB clip name → normalized progress 0–1; numeric motion tracks work in JSX. Use #index for unnamed/duplicate clips. Omitted clips do not play; overlapping target tracks are rejected. */
+	animations?: Readonly<Record<string, number>>;
+	/** Surface children only. Model must be a direct Scene child. */
+	children?: Child;
+}
+export interface SurfaceProps {
+	/** Exact GLB node name/index, not descendants; mutually exclusive with nodes. */
+	node?: ModelSelector;
+	/** Exact node names/indices sharing one texture atlas. */
+	nodes?: readonly ModelSelector[];
+	/** GLB material name/index; intersects any node selector. Require a node(s) or material selector. */
+	material?: ModelSelector;
+	/** Zero-based primitive index within the selected node mesh. */
+	primitive?: number;
+	/** Only baseColor is supported. Default: baseColor. */
+	slot?: "baseColor";
+	/** Texture canvas width; required with children, positive and static. Does not resize the model. */
+	width?: number;
+	/** Texture canvas height; required with children, positive and static. Does not resize the model. */
+	height?: number;
+	/** unlit preserves UI colors; lit uses engine lighting. Omitted: retain imported setting. */
+	shading?: "lit" | "unlit";
+	/** Material tint; live content defaults to white. Omitted without children: retain imported color. */
+	color?: Color;
+	/** Material metallic factor, 0–1. Omitted: retain imported setting. */
+	metalness?: number;
+	/** Material roughness, 0–1. Omitted: retain imported setting. */
+	roughness?: number;
+	/** Filter the surface canvas in array order. */
+	effects?: readonly EffectInstance[];
+	/** Group/Text/Image/Video/Shader content for this texture; omit to override material settings only. */
+	children?: Child;
+}
+
+export interface MediaTiming extends ClipProps {
+	/** Offset into the source in seconds; static, nonnegative. Default: 0. */
+	trimIn?: number;
+	/** Source-time multiplier from 0.25–4; static. Default: 1. */
+	playbackRate?: number;
+	/** Gain from 0–1; animatable in JSX. Use 0 to mute video audio. Default: 1. */
+	volume?: number;
+}
+export interface VideoProps extends ImageProps, MediaTiming {}
+export interface AudioProps extends MediaTiming {
+	/** Local audio file path, relative to this TSX file. */
+	src: string;
+}
+
+/** SVG-style stroke painted along the contour, centered on its geometry. */
+export interface PathStroke extends Stroke {
+  /** Endpoint shape for open subpaths. Default: butt. */
+  cap?: "butt" | "round" | "square";
+  /** Corner treatment. Default: miter. */
+  join?: "miter" | "round" | "bevel";
+  /** Maximum miter length relative to half-width, from 1–100. Default: 4. */
+  miterLimit?: number;
+  /** Where the visible stroke begins, as a fraction 0–1 of total path length. Default: 0. Animatable. */
+  trimStart?: number;
+  /** Where the visible stroke ends, as a fraction 0–1 of total path length. Default: 1. Animate 0 → 1 to draw the line on. Fill is unaffected. */
+  trimEnd?: number;
+}
+export interface PathProps extends TransformProps {
+  /** Positive viewport size in pixels. One dimension preserves the source aspect ratio. */
+  width?: number;
+  height?: number;
+  /** Source [minX, minY, width, height]. Omitted: tight geometry bounds (excluding stroke). */
+  viewBox?: readonly [number, number, number, number];
+  /** Center geometry in the viewport: contain preserves aspect; fill stretches. Default: contain. Stroke scales with geometry; overflow is not clipped. */
+  fit?: "contain" | "fill";
+  /** Static SVG path data in local pixels; supports M/L/H/V/C/S/Q/T/A/Z, relative commands and multiple subpaths. Original coordinates are preserved unless sizing is supplied. */
+  d: string;
+  /** Solid interior color. Default: #ffffff; use transparent for an unfilled line. Open subpaths close for fill only. */
+  fill?: Color;
+  /** Determines holes and overlaps. Default: nonzero; evenodd cuts holes regardless of winding. */
+  fillRule?: "nonzero" | "evenodd";
+  /** Centered contour stroke; width is pixels, from 0–2048. Omitted: no stroke. */
+  stroke?: PathStroke;
+}
+
+export interface RectProps extends TransformProps {
+	/** Nonnegative width in pixels. Prefer Group for new shapes. */
+	width: number;
+	/** Nonnegative height in pixels. */
+	height: number;
+	/** Solid color. Default: #ffffff. */
+	fill?: Color;
+	/** Corner radius in pixels. Default: 0. */
+	radius?: number;
+}
+export type TextPath = {
+	/** Distance as a fraction of total arc length; 1 = one lap. Default: 0. Closed contours wrap; open contours let text enter/exit. */
+	progress?: number;
+} & (
+	| {
+      /** Ellipse starts at the top and travels clockwise. */
+      shape: "ellipse";
+      /** Positive [rx, ry] in pixels; center is [rx, ry]. Radii are animatable. */
+      radius: Vec2;
+      d?: never;
+    }
+	| {
+      shape: "svg";
+      /** Static SVG path data in local pixels; one continuous contour, no auto-fitting. Z closes it. */
+      d: string;
+      radius?: never;
+    }
+);
+export interface TextStyleProps extends TransformProps {
+	/** Whole string or number; the renderer handles shaping, kerning and glyph placement. */
+	children: string | number;
+	/** Bundled Inter or a local .ttf/.otf path relative to this TSX file. Default: Inter. */
+	font?: string;
+	/** Positive size in pixels. Default: 48. */
+	fontSize?: number;
+	/** Requested font weight; omitted uses the selected face’s default. */
+	fontWeight?: 400 | 500 | 600 | 700;
+	/** Text color. Default: #ffffff. */
+	color?: Color;
+	/** Extra tracking between glyph clusters in pixels (not em); animatable. Default: 0. */
+	letterSpacing?: number;
+}
+export type TextProps = TextStyleProps & (
+	| {
+      path?: never;
+      /** Positive wrapping width in pixels; omitted uses natural text width. */
+      width?: number;
+      /** Positive text-box height. Overflow remains visible; use a clipping Group to crop. */
+      height?: number;
+      /** Vertical placement within height. Requires height. Default: top. */
+      verticalAlign?: "top" | "center" | "bottom";
+      /** Alignment bounds: line box (stable while text changes) or visible glyph bounds. Default: lineBox. Glyph bounds are recomputed when text changes. */
+      alignBounds?: "lineBox" | "glyphs";
+      /** Horizontal alignment within the text box. Default: left. */
+      align?: "left" | "center" | "right";
+      /** Positive font-size multiplier. Default: 1.2. */
+      lineHeight?: number;
+    }
+	| {
+      /** Move a whole string along a curve by animating progress. No width, align, lineHeight or line breaks. */
+      path: TextPath;
+      width?: never;
+      height?: never;
+      verticalAlign?: never;
+      alignBounds?: never;
+      align?: never;
+      lineHeight?: never;
+    }
+);
+
+export type Child = Element | readonly Child[] | null | undefined | boolean;
+// A component receives resolved props, even when its JSX inputs are motion tracks.
+export type Component<P = Record<string, unknown>> = (
+	props: P,
+	context: FrameContext,
+) => Child;
+export type Primitive =
+	| "camera"
+	| "scene"
+	| "group"
+	| "rect"
+	| "path"
+	| "text"
+	| "image"
+	| "video"
+	| "audio"
+	| "shader"
+	| "fragment"
+	| "model"
+	| "surface"
+	| "composition";
+export interface Element {
+	readonly type: Primitive | Component<any>;
+	readonly props: Readonly<Record<string, unknown>>;
+	readonly key?: string | number;
+	readonly sourceFile?: string;
+}
+export function element(
+	type: Element["type"],
+	props: object,
+	key?: string | number,
+): Element {
+	return Object.freeze({
+		type,
+		props: Object.freeze({ ...props }),
+		...(key === undefined ? {} : { key }),
+	});
+}
+
+/** Root composition with fixed dimensions, duration and FPS.
+ * @example <Scene width={1080} height={1080} duration={4} fps={30} background="#141414"><Text track={0}>Hello</Text></Scene> */
+export const Scene = Object.assign(
+	(props: SceneProps): Element => element("scene", props),
+	{ sceneRoot: true as const },
+);
+/** Layout, transform and style children together; also draws boxes, ellipses and thin lines.
+ * Isolated groups flatten their contents; use sibling layers for independent 3D depth.
+ * @example <Group layout="row" gap={16} width={400} height={120} fill="#222222" rounding={16}><Text>One</Text><Text>Two</Text></Group> */
+export function Group<const K extends Knobs = Knobs>(props: GroupProps<K>): Element {
+	return element("group", props);
+}
+/** Legacy rectangle. Prefer Group with fill and rounding for new scenes.
+ * @example <Rect width={200} height={100} fill="#ff4400" radius={12} /> */
+export function Rect(props: RectProps): Element {
+	return element("rect", props);
+}
+/** Render a whole string. For circular, curved or figure-eight typography, try path before per-letter tracks.
+ * Path text uses outline glyphs; bitmap/color glyphs are unsupported.
+ * @example <Text path={{ shape: "ellipse", radius: [180, 120], progress: 0.25 }} fontSize={32}>FOLLOW THE CURVE</Text>
+ * @example <Text path={{ shape: "svg", d: "M0 100 C0 0 200 200 200 100 C200 0 0 200 0 100 Z", progress: 0.5 }}>FIGURE EIGHT</Text> */
+export function Text(props: TextProps): Element {
+	return element("text", props);
+}
+/** Group JSX siblings without creating a layout or transform node.
+ * @example <><Text>One</Text><Text position={[0, 60]}>Two</Text></> */
+export function Fragment(props: { children?: Child }): Element {
+	return element("fragment", props);
+}
+
+/** Place a local image in a sized box; supports transforms and effects.
+ * @example <Image src="./assets/photo.jpg" width={320} height={240} fit="cover" /> */
+export function Image(props: ImageProps): Element {
+	return element("image", props);
+}
+/** Place local video with synchronized audio; start/trimIn/duration/playbackRate are static.
+ * Group opacity affects its picture, not audio; set volume explicitly.
+ * @example <Video src="./assets/clip.mp4" width={640} height={360} trimIn={1} volume={0} /> */
+export function Video(props: VideoProps): Element {
+	return element("video", props);
+}
+/** Add a local soundtrack; no visual box or transform.
+ * @example <Audio src="./assets/music.wav" start={0} volume={0.5} /> */
+export function Audio(props: AudioProps): Element {
+	return element("audio", props);
+}
+/** One direct Scene child controls the shared 3D view. Defaults preserve the camera-free framing.
+ * @example <Camera position={[640, 360]} z={2000} target={[540, 360, 0]} /> */
+export function Camera(props: CameraProps): Element {
+	return element("camera", props);
+}
+
+/** Draw procedural WGSL, optionally sampling the backdrop. CLI Strict accepts a static local src path.
+ * uv is local 0–1; time is scene seconds; eng_box_size() returns logical pixels.
+ * @example <Shader src="./assets/petrol.wgsl" width={400} height={300} uniforms={{ intensity: 0.5 }} /> */
+export function Shader(props: ShaderProps): Element {
+	return element("shader", props);
+}
+
+/** Place a GLB in the same camera space as scene layers. Direct Scene child; Surface children target its materials.
+ * Base-color textures and scalar metallic/roughness are supported; normal maps, transmission and compressed meshes are not.
+ * @example <Model src="./assets/phone.glb" height={700} rotation={[0, 20, 0]} animations={{ Fold: 0.5 }} /> */
+export function Model(props: ModelProps): Element { return element("model", props); }
+/** Map scene children onto a GLB texture slot without changing model size. Direct Model child only.
+ * Selectors must match the asset; overlapping overrides are rejected.
+ * @example <Surface material="Display" width={800} height={1200} shading="unlit"><Text>Hello</Text></Surface> */
+export function Surface(props: SurfaceProps): Element { return element("surface", props); }
+
+/** Draw native vector geometry. Prefer Group for basic boxes/ellipses and Text.path for typography on curves.
+ * Unsized paths preserve authored coordinates, including negative values. Sized paths fit tight geometry or viewBox into a centered viewport.
+ * Numeric stroke styling, transforms, z, opacity and effects can animate; d stays a literal in CLI Strict.
+ * @example <Path d="M10 80 Q95 10 180 80" fill="transparent" stroke={{ color: "#ffffff", width: 4, cap: "round" }} />
+ */
+export function Path(props: PathProps): Element { return element("path", props); }