@xplainer/motion 0.0.0-stage → 0.1.1

package/dist/spring.d.ts

@@ -0,0 +1,76 @@
+/**
+ * `spring()` and `measureSpring()` — physical motion as a pure function of the frame.
+ *
+ * **The curve is the closed-form solution of a damped harmonic oscillator**, not a step-by-step
+ * simulation. A mass `m` on a spring of stiffness `k` with damping `c` starts at rest at 0 and is
+ * released towards 1:
+ *
+ *     m·x″ + c·x′ + k·(x − 1) = 0,   x(0) = 0,   x′(0) = 0
+ *
+ * With `ω₀ = √(k/m)` and `ζ = c / (2·√(k·m))` the textbook solution has three regimes —
+ * under-damped (`ζ < 1`, it overshoots and rings), critically damped (`ζ = 1`) and over-damped
+ * (`ζ > 1`, it creeps in without overshooting) — and each is evaluated directly at the frame's
+ * time. Two consequences matter for a renderer that captures frames in any order: the value at
+ * frame 90 does not depend on frames 0–89 having been computed first, and it is identical whether
+ * the video is rendered or a single still is taken. `math.test.ts` holds the curve against an
+ * independent RK4 integration of the equation above at 1e-9.
+ *
+ * The curve is normalised (0 → 1) and then scaled onto `from → to`, so `overshootClamping`, the
+ * rest threshold and the duration stretch all mean the same thing whatever the two ends are.
+ *
+ * **`overshootClamping` stops the motion at the target.** It is React Native Animated's flag of
+ * the same name: once the value first reaches `to`, it stays there. That is the first root of
+ * `x(t) = 1`, at `ω_d·t* = π − atan2(ω_d, ζ·ω₀)`, and only an under-damped spring has one —
+ * critically and over-damped motion never reaches the target, so the flag changes nothing for them.
+ * Clamping each sample to `min(x, 1)` instead would not be the same thing: after the first swing
+ * the oscillator falls back below the target, so a clamped sample sinks away from `to` and climbs
+ * back — the default spring at 30 fps would hold 1.000 from frame 8 to 18, dip to 0.973 at 22 and
+ * return at 29.
+ *
+ * The values follow the equation, not any other library's numerical scheme, so a scene ported
+ * from elsewhere can differ in the last few hundredths of its overshoot.
+ */
+export type SpringConfig = {
+    /** Default 1. */
+    mass: number;
+    /** Default 10. 0 never settles; `measureSpring` refuses it. */
+    damping: number;
+    /** Default 100. */
+    stiffness: number;
+    /** Default false. When true the value stops at `to` the first time it reaches it. */
+    overshootClamping: boolean;
+};
+export type SpringOptions = {
+    /** The frame to evaluate, usually `useCurrentFrame()`. */
+    frame: number;
+    /** Frames per second, usually `useVideoConfig().fps`. */
+    fps: number;
+    config?: Partial<SpringConfig>;
+    /** Default 0. */
+    from?: number;
+    /** Default 1. */
+    to?: number;
+    /** Stretch time so the spring's natural settle (`measureSpring`) lands on this many frames. */
+    durationInFrames?: number;
+    /** Frames to hold at the start value before the spring is released. Default 0. */
+    delay?: number;
+    /** Run the motion backwards in time: settled at the start, back at `from` at the end. */
+    reverse?: boolean;
+    /** The threshold `durationInFrames` and `reverse` measure the natural settle with. Default 0.005. */
+    durationRestThreshold?: number;
+};
+export type MeasureSpringOptions = {
+    fps: number;
+    config?: Partial<SpringConfig>;
+    /** How close to the target, in normalised units (0 → 1), counts as settled. Default 0.005. */
+    threshold?: number;
+};
+/**
+ * The number of frames until the spring stays within `threshold` of its target for good: the
+ * first frame `F` such that every frame from `F` on is inside. A spring with no damping never
+ * settles, and is refused rather than looped over; so is one that takes more than an hour to
+ * settle — so lightly damped it rings for that long, or so heavily that it creeps — with a
+ * `RangeError` that says which.
+ */
+export declare function measureSpring(options: MeasureSpringOptions): number;
+export declare function spring(options: SpringOptions): number;

package/dist/spring.js

@@ -0,0 +1 @@
+const DEFAULT_CONFIG={mass:1,damping:10,stiffness:100,overshootClamping:!1},DEFAULT_THRESHOLD=.005;function resolveConfig(config){const resolved={...DEFAULT_CONFIG,...config},{mass,damping,stiffness}=resolved;if(!(Number.isFinite(mass)&&mass>0))throw new RangeError(`spring: config.mass must be a positive number, got ${String(mass)}.`);if(!(Number.isFinite(stiffness)&&stiffness>0))throw new RangeError(`spring: config.stiffness must be a positive number, got ${String(stiffness)}.`);if(!(Number.isFinite(damping)&&damping>=0))throw new RangeError(`spring: config.damping must be zero or a positive number, got ${String(damping)}.`);return resolved}function assertFps(fps,caller){if(!(Number.isFinite(fps)&&fps>0))throw new RangeError(`${caller}: fps must be a positive number, got ${String(fps)}.`)}function position(seconds,config){const omega=Math.sqrt(config.stiffness/config.mass),zeta=config.damping/(2*Math.sqrt(config.stiffness*config.mass));if(zeta<1){const omegaD=omega*Math.sqrt(1-zeta*zeta);return 1-Math.exp(-zeta*omega*seconds)*(Math.cos(omegaD*seconds)+zeta*omega/omegaD*Math.sin(omegaD*seconds))}if(zeta===1)return 1-Math.exp(-omega*seconds)*(1+omega*seconds);const root=Math.sqrt(zeta*zeta-1),r1=-omega/(zeta+root),r2=-omega*(zeta+root);return 1+(r2*Math.exp(r1*seconds)-r1*Math.exp(r2*seconds))/(r1-r2)}function firstArrival(config){const omega=Math.sqrt(config.stiffness/config.mass),zeta=config.damping/(2*Math.sqrt(config.stiffness*config.mass));if(zeta>=1)return Number.POSITIVE_INFINITY;const omegaD=omega*Math.sqrt(1-zeta*zeta);return(Math.PI-Math.atan2(omegaD,zeta*omega))/omegaD}function shown(seconds,config){return seconds<=0?0:config.overshootClamping&&seconds>=firstArrival(config)?1:position(seconds,config)}const settleCache=new Map,MAX_SETTLE_SECONDS=3600;function tooSlowToSettle(fps,zeta,threshold){return new RangeError(`measureSpring: this spring takes more than ${MAX_SETTLE_SECONDS} s to stay within ${threshold} of its target at ${fps} fps (damping ratio \u03B6 = ${zeta}); ${zeta<1?"give it more damping":"give it less damping or more stiffness"}.`)}function settleFrames(fps,config,threshold){const key=`${fps}|${config.mass}|${config.damping}|${config.stiffness}|${config.overshootClamping}|${threshold}`,cached=settleCache.get(key);if(cached!==void 0)return cached;const distance=frame=>Math.abs(shown(frame/fps,config)-1),omega=Math.sqrt(config.stiffness/config.mass),zeta=config.damping/(2*Math.sqrt(config.stiffness*config.mass)),limit=Math.ceil(MAX_SETTLE_SECONDS*fps);let frames=0;if(zeta<1&&!config.overshootClamping){const amplitude=1/Math.sqrt(1-zeta*zeta),horizon=amplitude<=threshold?0:Math.ceil(Math.log(amplitude/threshold)/(zeta*omega)*fps);if(horizon>limit)throw tooSlowToSettle(fps,zeta,threshold);for(let frame=0;frame<=horizon;frame+=1)distance(frame)>=threshold&&(frames=frame+1)}else for(;distance(frames)>=threshold;)if(frames+=1,frames>limit)throw tooSlowToSettle(fps,zeta,threshold);return settleCache.set(key,frames),frames}export function measureSpring(options){const{fps,threshold=DEFAULT_THRESHOLD}=options;assertFps(fps,"measureSpring");const config=resolveConfig(options.config);if(config.damping===0)throw new RangeError("measureSpring: a spring with damping 0 oscillates forever and never settles; give config.damping a positive value.");if(!(Number.isFinite(threshold)&&threshold>0))throw new RangeError(`measureSpring: threshold must be a positive number, got ${String(threshold)}.`);return settleFrames(fps,config,threshold)}export function spring(options){const{frame,fps,from=0,to=1,delay=0,reverse=!1,durationInFrames,durationRestThreshold=DEFAULT_THRESHOLD}=options;if(typeof frame!="number"||Number.isNaN(frame))throw new TypeError(`spring: frame must be a number, got ${String(frame)}.`);assertFps(fps,"spring");const config=resolveConfig(options.config);if(!Number.isFinite(delay))throw new RangeError(`spring: delay must be a finite number, got ${String(delay)}.`);if(durationInFrames!==void 0&&!(Number.isFinite(durationInFrames)&&durationInFrames>0))throw new RangeError(`spring: durationInFrames must be a positive number, got ${String(durationInFrames)}.`);let local=frame-delay;if(durationInFrames!==void 0||reverse){const natural=measureSpring({fps,config,threshold:durationRestThreshold});durationInFrames!==void 0&&(local=local*natural/durationInFrames),reverse&&(local=natural-local)}return from+(to-from)*shown(local/fps,config)}

package/dist/static-fetch.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `fetch(staticFile(name))` answered from memory.
+ *
+ * The scaffold's `Root.tsx` fetches `timings.json` and `captions.json` with `fetch(staticFile(…))`
+ * at metadata time, and is a fixture that must not change. The renderer serves the page over
+ * loopback HTTP, which would answer those requests too, but the two documents are what decides the
+ * video's length, so they travel in the bundle instead and never depend on a request. The
+ * bundle's classic `static-data.js` carries both files' text in `window.__XPLAINER_STATIC__`, and
+ * the harness's `fetch` answers a request for one of those names before the network ever sees it.
+ * A URL matches when it resolves to the same absolute URL as `staticFile(name)` does; anything else
+ * goes to the real `fetch`.
+ */
+/** The URL of whatever `fetch` was handed: a string, a `URL` or a `Request`. */
+export declare function requestUrl(input: RequestInfo | URL): string;
+/** The entry of `table` that `url` names, or `undefined`. `toAbsolute` resolves against the page. */
+export declare function findStaticText(url: string, table: Readonly<Record<string, string>> | undefined, toAbsolute: (url: string) => string): {
+    name: string;
+    text: string;
+} | undefined;
+/** The `content-type` the answer carries: JSON for `.json`, plain text otherwise. */
+export declare function contentTypeFor(name: string): string;

package/dist/static-fetch.js

@@ -0,0 +1 @@
+import{staticFile}from"./static-file.js";export function requestUrl(input){return typeof input=="string"?input:input instanceof URL?input.href:input.url}export function findStaticText(url,table,toAbsolute){if(table===void 0)return;const target=toAbsolute(url);for(const[name,text]of Object.entries(table))if(toAbsolute(staticFile(name))===target)return{name,text}}export function contentTypeFor(name){return name.toLowerCase().endsWith(".json")?"application/json":"text/plain; charset=utf-8"}

package/dist/static-file.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `staticFile(name)` — the URL of a file the narration step wrote beside the video.
+ *
+ * A scene never knows where its bundle will be opened from: the renderer writes it to a per-job
+ * directory and serves it from a loopback address on a port of its own. So the base is not baked
+ * into the scene; the bundle's
+ * classic `static-data.js` sets `globalThis.__XPLAINER_PUBLIC_BASE__` (a URL ending in `/`, pointing
+ * at `public/<slug>/`) before any module runs, and this function appends the name to it. In Node,
+ * where nothing sets it, the base is empty and the result is the encoded name alone — which is
+ * what makes this function testable without a page.
+ *
+ * Each path segment is `encodeURIComponent`-encoded and the slashes between them are kept, so
+ * `staticFile("shots/step 1.png")` is `<base>shots/step%201.png`. A name that is already encoded is
+ * encoded again; pass the name as it is on disk.
+ *
+ * **The name stays inside `public/<slug>/`, or it is refused.** A URL is refused rather than
+ * mangled, and so are the two spellings of a path that would resolve somewhere else: one starting
+ * with `/`, and one with a `..` segment, which the browser resolves against the base and walks out
+ * of the video's own directory. Each is a `TypeError` naming the name and the rule.
+ */
+export declare function staticFile(name: string): string;

package/dist/static-file.js

@@ -0,0 +1 @@
+const URL_SCHEME=/^[a-z][a-z0-9+.-]*:/i;function publicBase(){const value=Reflect.get(globalThis,"__XPLAINER_PUBLIC_BASE__");return typeof value=="string"?value:""}export function staticFile(name){if(typeof name!="string"||name.length===0)throw new TypeError(`staticFile: pass the name of a file in this video's public directory, such as "logo.png".`);if(URL_SCHEME.test(name))throw new TypeError(`staticFile(${JSON.stringify(name)}): pass a file name inside this video's public directory, not a URL.`);if(name.startsWith("/"))throw new TypeError(`staticFile(${JSON.stringify(name)}): pass the name relative to this video's public directory, without a leading "/".`);const segments=name.split("/");if(segments.includes(".."))throw new TypeError(`staticFile(${JSON.stringify(name)}): a ".." segment would leave this video's public directory; pass a file inside it.`);const path=segments.map(segment=>encodeURIComponent(segment)).join("/");return`${publicBase()}${path}`}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@xplainer/motion",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "type": "module",
+  "description": "The authoring API explainer scenes are written against — frame hooks, interpolate, Easing, spring, Sequence — and the page-side capture harness the xplainer renderer drives one frame at a time.",
+  "homepage": "https://xplainer.video",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BrewMyTech/xplainer.video.git",
+    "directory": "packages/motion"
+  },
+  "author": "Rishav Anand <rishav@brewmytech.com>",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "xplainer": {
+    "tier": "open-later"
+  },
+  "sideEffects": [
+    "./dist/harness.js"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./harness": {
+      "types": "./dist/harness.d.ts",
+      "default": "./dist/harness.js"
+    }
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "peerDependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "26.4.1",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.7",
+    "@xplainer/config": "0.0.0",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "typescript": "7.0.2",
+    "vitest": "5.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && xplainer-minify-dist",
+    "lint": "biome check .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }