@scenerok/sdk 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,177 @@
+import type { IRAnimation, IREffect, IRMotionTrack, IRTextStyle } from './ir.js';
+import type { Duration, TimeInput } from './duration.js';
+import type { GridSpec } from './grid.js';
+export type SdkKind = 'video' | 'text' | 'audio' | 'filter' | 'shader' | 'transition' | 'timeline' | 'animation';
+export interface SdkNodeBase {
+    readonly __sdk: true;
+    readonly kind: SdkKind;
+}
+export interface AnimationDescriptor {
+    readonly __sdk: true;
+    readonly kind: 'animation';
+    type: string;
+    from: Record<string, unknown>;
+    to: Record<string, unknown>;
+    duration: number;
+    align?: 'start' | 'end';
+    easing?: string;
+    loop?: boolean;
+    plugin?: string;
+}
+export interface VideoOptions {
+    width?: number;
+    height?: number;
+    x?: number;
+    y?: number;
+    opacity?: number;
+    trimStart?: TimeInput;
+    trimEnd?: TimeInput;
+    speed?: number;
+    loop?: number;
+    /** Explicit duration in seconds when the asset cannot be probed yet. */
+    duration?: TimeInput;
+    animate?: AnimationDescriptor | AnimationDescriptor[];
+}
+export interface VideoClip extends SdkNodeBase {
+    kind: 'video';
+    source: string;
+    options: VideoOptions;
+    /** Resolved or declared duration in seconds. */
+    duration: number;
+    animations: AnimationDescriptor[];
+    animate(anim: AnimationDescriptor | AnimationDescriptor[]): VideoClip;
+    with(opts: Partial<VideoOptions>): VideoClip;
+}
+export interface TextOptions {
+    font?: string;
+    size?: number;
+    color?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    bold?: boolean;
+    italic?: boolean;
+    x?: number | string;
+    y?: number | string;
+    rotation?: number;
+    opacity?: number;
+    align?: 'left' | 'center' | 'right';
+    lineHeight?: number;
+    letterSpacing?: number;
+    position?: string;
+    area?: string;
+    fit?: IRTextStyle['fit'];
+    overflow?: IRTextStyle['overflow'];
+    maxWidth?: number | string;
+    maxHeight?: number | string;
+    maxLines?: number;
+    anchor?: IRTextStyle['anchor'];
+    shadowColor?: string;
+    shadowBlur?: number;
+    shadowOffsetX?: number;
+    shadowOffsetY?: number;
+    animate?: AnimationDescriptor | AnimationDescriptor[];
+}
+export interface TextLayer extends SdkNodeBase {
+    kind: 'text';
+    content: string;
+    options: TextOptions;
+    animations: AnimationDescriptor[];
+    animate(anim: AnimationDescriptor | AnimationDescriptor[]): TextLayer;
+    with(opts: Partial<TextOptions>): TextLayer;
+}
+export interface AudioOptions {
+    volume?: number;
+    fadeIn?: TimeInput;
+    fadeOut?: TimeInput;
+    duration?: TimeInput;
+    loudnessNormalization?: 'ebu-r128';
+    targetLufs?: number;
+}
+export interface AudioTrack extends SdkNodeBase {
+    kind: 'audio';
+    source: string;
+    options: AudioOptions;
+    duration: number;
+    with(opts: Partial<AudioOptions>): AudioTrack;
+}
+export interface FilterEffect extends SdkNodeBase {
+    kind: 'filter';
+    name: string;
+    params: Record<string, number | string>;
+}
+export interface ShaderEffect extends SdkNodeBase {
+    kind: 'shader';
+    shaderSource: string;
+    params: Record<string, number | string>;
+}
+export interface TransitionOptions {
+    direction?: string;
+    ease?: string;
+    strength?: string | number;
+    /** `roll` | `freeze` — omit to auto-resolve from clip adjacency. */
+    mode?: string;
+    /** Override catalog default duration (0.6s) for `push` / auto-append. */
+    duration?: TimeInput;
+    width?: number;
+    height?: number;
+    x?: number | string;
+    y?: number | string;
+    opacity?: number;
+}
+export interface TransitionEffect extends SdkNodeBase {
+    kind: 'transition';
+    /** Catalog function name, e.g. `dissolve`. */
+    name: string;
+    /** Shader library key used by the render engine. */
+    shaderName: string;
+    options: TransitionOptions;
+    /** Default / declared duration in seconds. */
+    duration: number;
+    with(opts: Partial<TransitionOptions>): TransitionEffect;
+}
+export type Schedulable = VideoClip | TextLayer | AudioTrack | FilterEffect | ShaderEffect | TransitionEffect | TimelineLike;
+export interface TimelineOptions {
+    width?: number;
+    height?: number;
+    fps?: number;
+    background?: string;
+    output?: {
+        path?: string;
+        format?: string;
+        codec?: string;
+        bitrate?: string;
+        resolution?: string;
+        fps?: number;
+    };
+    /** Optional name for nested timeline metadata. */
+    name?: string;
+}
+export interface TimelineLike extends SdkNodeBase {
+    kind: 'timeline';
+    readonly options: TimelineOptions;
+    /** Visual playhead (seconds) after last scheduled visual item. */
+    readonly duration: number;
+    /** Alias used in plan examples (`scene1.length`). */
+    readonly length: number;
+    /** Declare CSS-grid named regions for `area:` text placement. */
+    grid(spec: GridSpec): this;
+    push(value: Schedulable, duration?: TimeInput): this;
+    range(start: TimeInput, end: TimeInput, value: Schedulable): this;
+    toIR(): import('./ir.js').IRTimeline;
+}
+export type TimeKey = TimeInput | '-';
+export interface RangeBinder {
+    [end: string | number | symbol]: Schedulable | undefined;
+}
+/** Host hooks for duration probing / asset resolution (injected by sdk-runtime). */
+export interface SdkHost {
+    probeDuration?(source: string): number | Promise<number>;
+    resolveAsset?(source: string): string | Promise<string>;
+}
+export type BuiltEffect = IREffect;
+export type BuiltMotion = IRMotionTrack[];
+export type BuiltAnimations = IRAnimation[];
+export declare function isSdkNode(value: unknown): value is SdkNodeBase;
+export declare function isSchedulable(value: unknown): value is Schedulable;
+export type { Duration };
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,14 @@
+export function isSdkNode(value) {
+    return typeof value === 'object' && value !== null && value.__sdk === true;
+}
+export function isSchedulable(value) {
+    if (!isSdkNode(value))
+        return false;
+    return (value.kind === 'video'
+        || value.kind === 'text'
+        || value.kind === 'audio'
+        || value.kind === 'filter'
+        || value.kind === 'shader'
+        || value.kind === 'transition'
+        || value.kind === 'timeline');
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@scenerok/sdk",
+  "version": "0.2.0",
+  "description": "TypeScript-first SceneRok authoring SDK — build IRTimeline for complex agent-authored scenes",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./stdlib": {
+      "types": "./dist/stdlib.d.ts",
+      "import": "./dist/stdlib.js"
+    },
+    "./xai": {
+      "types": "./dist/plugins/xai.d.ts",
+      "import": "./dist/plugins/xai.js"
+    },
+    "./cloudflare": {
+      "types": "./dist/plugins/cloudflare.d.ts",
+      "import": "./dist/plugins/cloudflare.js"
+    },
+    "./elevenlabs-music": {
+      "types": "./dist/plugins/elevenlabs-music.d.ts",
+      "import": "./dist/plugins/elevenlabs-music.js"
+    },
+    "./transitions": {
+      "types": "./dist/transitions/index.d.ts",
+      "import": "./dist/transitions/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc --watch",
+    "test": "node --import tsx --test src/**/*.test.ts"
+  },
+  "keywords": [
+    "scenerok",
+    "vidscript",
+    "video",
+    "timeline",
+    "ir",
+    "sdk"
+  ],
+  "author": "SceneRok",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}