@osmo.inc/cli 0.1.18 → 0.1.19

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

@@ -1,491 +0,0 @@
-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); }