@xplainer/motion 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,110 @@
+Copyright (c) 2026 BrewMyTech.
+
+This repository is NOT under a single licence. Part of it is open source and
+part of it is proprietary, and the line between them is drawn per directory
+below. Read the whole of this file before copying anything out of here.
+
+
+PART ONE — OPEN SOURCE, APACHE LICENCE 2.0
+
+The eight packages published to npm — seven under the `@xplainer/` scope, plus
+the unscoped `xplainer`, which is an alias for `@xplainer/cli` — are licensed
+under the Apache Licence, Version 2.0:
+
+    apps/cli                 @xplainer/cli
+    packages/alias           xplainer
+    packages/mcp-server      @xplainer/mcp-server
+    packages/motion          @xplainer/motion
+    packages/protocol        @xplainer/protocol
+    packages/render-core     @xplainer/render-core
+    packages/skill           @xplainer/skill
+    packages/tts-client      @xplainer/tts-client
+
+Everything inside those eight directories is Apache-2.0, including the workspace
+template and the scaffold templates under `packages/render-core`.
+The full licence text is in LICENSE-APACHE-2.0 at the root of this repository,
+and a copy of it is committed as `LICENSE` inside each of the eight package
+directories so that it also travels inside every published tarball. The
+attribution notice Apache-2.0 section 4(d) propagates is the NOTICE file, at
+the root and inside each of the eight.
+
+Each of those eight manifests declares `"license": "Apache-2.0"`. That SPDX
+identifier is the authoritative statement for machine consumers.
+
+    Licensed under the Apache Licence, Version 2.0 (the "Licence"); you may
+    not use these files except in compliance with the Licence. You may obtain
+    a copy of the Licence at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the Licence is distributed on an "AS IS" BASIS, WITHOUT
+    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+    Licence for the specific language governing permissions and limitations
+    under the Licence.
+
+
+PART TWO — PROPRIETARY, ALL RIGHTS RESERVED
+
+Every file that neither Part One nor Part Three names is proprietary. No
+permission is granted to use, copy, modify, merge, publish, distribute,
+sublicense, or sell any part of it. This covers, without being limited to:
+
+    apps/desktop             the desktop client                (tier: open-later)
+    packages/config          shared build presets and tooling  (tier: open-later)
+    services/tts-sidecar     the packaged TTS sidecar          (tier: open-later)
+
+    infra/ (but not infra/ffmpeg/, which is Part Three), scripts/, docs/,
+    .github/ (but not .github/workflows/ffmpeg-macos.yml, also Part Three),
+    and every other file at the root
+
+No `hosted` member remains in this repository. `apps/api`, `apps/web` and
+`services/media-service` were relocated to a private repository on 2026-09-06
+(ADR 0023) and this file stopped listing them when they went; that tier stays
+proprietary wherever it lives.
+
+The three `open-later` members listed above are on a path to being opened but
+have NOT been relicensed: opening the published packages did not open them,
+and each still declares `"license": "UNLICENSED"` in its own manifest. Nothing
+in Part One extends to them. Making this repository public did not change that
+either — it made them readable, not usable.
+
+The tier each package belongs to is declared in its own package.json as
+`"xplainer": { "tier": "hosted" | "open-later" }`, and the boundary between
+the tiers is machine-checked. The tier field describes intent; this file
+describes the grant. Where they appear to disagree, this file and the
+`license` field of the package's own manifest govern.
+
+
+PART THREE — THE macOS FFMPEG BUILD SCRIPTS, MIT LICENCE
+
+The scripts that build the macOS FFmpeg which `xplainer setup` downloads, and
+the workflow that runs them, are licensed under the MIT Licence:
+
+    infra/ffmpeg/                          except infra/ffmpeg/keys/
+    .github/workflows/ffmpeg-macos.yml
+
+They are published beside every build as part of its complete corresponding
+source ("the scripts used to control compilation and installation of the
+executable", GPLv2 section 3), so that whoever receives the binary can rebuild
+it. The full licence text is in infra/ffmpeg/LICENSE. Each of those files
+carries `SPDX-License-Identifier: MIT`.
+
+infra/ffmpeg/keys/ holds the OpenPGP public keys of FFmpeg's release signer and
+of zlib's maintainer, unmodified, so that the build can check their signatures.
+They are their owners'; nothing in this file licenses them.
+
+The FFmpeg binary those scripts produce is not covered by any part of this
+file. It is FFmpeg, x264 and zlib under the GNU General Public License version
+2 or later, and every download carries their licences in its LICENSE file.
+
+
+THIRD PARTY COMPONENTS
+
+This software depends on components that others own, and `xplainer setup`
+downloads more of them onto the machine it runs on, each under its own licence.
+The Apache-2.0 grant in Part One covers this software only and grants you
+nothing in respect of any of them. The NOTICE file names them and their terms.
+
+
+Questions: rishav@brewmytech.com

package/NOTICE

@@ -0,0 +1,68 @@
+xplainer.video
+Copyright 2026 BrewMyTech
+
+This product includes software developed by BrewMyTech (https://xplainer.video).
+
+The packages published to npm — those under the `@xplainer/` scope and the
+unscoped `xplainer`, which is an alias for `@xplainer/cli` — are licensed under
+the Apache Licence, Version 2.0. See the LICENSE file distributed with each
+package, or LICENSE-APACHE-2.0 in the source repository.
+
+--------------------------------------------------------------------------------
+
+THIRD PARTY COMPONENTS
+
+This software depends on components owned by others, each under its own
+licence. Those licences govern those components.
+
+`@xplainer/render-core` redistributes the CMU Pronouncing Dictionary
+(`cmudict.dict`), Copyright (C) 1993-2015 Carnegie Mellon University, under the
+2-clause BSD licence reproduced verbatim beside it at
+`packages/render-core/src/g2p/data/cmudict.LICENSE` and shipped in the package
+at `dist/g2p/data/cmudict.LICENSE`. That licence's clause 1 requires the notice
+and the disclaimer to travel with the source, which is why the file is copied
+into the tarball rather than referenced.
+
+`@xplainer/render-core` also redistributes the tokenizer of
+`onnx-community/Kokoro-82M-v1.0-ONNX-timestamped` (`kokoro-tokenizer.json`),
+Apache-2.0, as the authoritative list of the symbols the speech model accepts.
+The model weights themselves are neither bundled nor redistributed here; they
+are fetched from their upstream home, pinned by revision and digest.
+
+`@xplainer/cli` depends on xz-decompress
+(https://github.com/httptoolkit/xz-decompress), MIT, to unpack the `.tar.xz`
+FFmpeg builds `xplainer setup` downloads on Linux. It is installed from the npm
+registry as a declared dependency, not bundled. It contains, compiled to
+WebAssembly, xzwasm (Copyright (c) Steve Sanderson, MIT), XZ Embedded by Lasse
+Collin and Igor Pavlov (public domain) and walloc (Copyright (c) 2020 Igalia,
+S.L., MIT). Its package carries no licence file; those are the terms its
+`package.json` and the header of its own code state.
+
+`xplainer setup` fetches two more components onto the machine it runs on, and
+neither is bundled in or redistributed by any package here. The speech model
+weights and voice pack of `onnx-community/Kokoro-82M-v1.0-ONNX-timestamped` are
+Apache-2.0 and come from that repository, pinned by revision and digest. ONNX
+Runtime (`onnxruntime-node` and `onnxruntime-common`, Copyright (c) Microsoft
+Corporation) is MIT and comes from the npm registry, pinned by version and
+digest; only the host platform's build is kept. `setup` is the one command that
+downloads, it says what it is fetching and what each artefact must hash to, and
+nothing is installed behind your back.
+
+`xplainer setup` also acquires FFmpeg (https://ffmpeg.org), which xplainer
+runs as a separate program and does not link, modify or bundle. On macOS,
+`xplainer setup` downloads an FFmpeg program built by xplainer.video from
+unmodified FFmpeg 9.0.2, x264 b35605ace3ddf7c1a5d67a2eb553f034aef41d55 and zlib
+1.3.2, licensed under the GNU General Public License version 2 or later. Its
+complete corresponding source is listed at
+https://cdn.xplainer.video/toolchain/v1/ffmpeg/9.0.2/source/README.txt. On
+Linux and Windows it downloads the GPL build BtbN publishes as FFmpeg-Builds
+(https://github.com/FFmpeg-Builds/FFmpeg-Builds), licensed under the GNU
+General Public License version 3 or later, from that project's own release.
+The GPL texts travel with each download, not in these packages.
+docs/third-party-components.md in the source repository lists every
+component `setup` acquires. FFmpeg is a trademark of Fabrice Bellard,
+originator of the FFmpeg project.
+
+Apache-2.0 governs this software. It does not govern the components named above
+— the FFmpeg builds and everything else `xplainer setup` acquires among them —
+and nothing here grants you any right to them.

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# @xplainer/motion
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**The API explainer scenes are written against, and the page-side harness the xplainer renderer
+drives one frame at a time.** A scene is ordinary React: it reads the frame, computes its picture
+from it, and the renderer captures that picture once per frame.
+
+```bash
+npm i @xplainer/motion react react-dom
+```
+
+```tsx
+import { AbsoluteFill, Easing, interpolate, spring, useCurrentFrame, useVideoConfig } from "@xplainer/motion";
+
+export const Title: React.FC<{ text: string }> = ({ text }) => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+  const opacity = interpolate(frame, [0, 15], [0, 1], { extrapolateRight: "clamp" });
+  const scale = spring({ frame, fps, config: { damping: 12 } });
+  const y = interpolate(frame, [0, 30], [40, 0], {
+    easing: Easing.out(Easing.cubic),
+    extrapolateRight: "clamp",
+  });
+  return (
+    <AbsoluteFill style={{ justifyContent: "center", alignItems: "center" }}>
+      <h1 style={{ opacity, transform: `translateY(${y}px) scale(${scale})` }}>{text}</h1>
+    </AbsoluteFill>
+  );
+};
+```
+
+## What is in it
+
+| Kind | Exports |
+|---|---|
+| Frame and video | `useCurrentFrame`, `useVideoConfig` |
+| Motion | `interpolate`, `Easing`, `spring`, `measureSpring`, `random` |
+| Timing and layout | `Sequence`, `Series`, `Loop`, `Freeze`, `AbsoluteFill` |
+| Media | `Img`, `Audio` (the narration marker), `staticFile` |
+| Render holds | `delayRender`, `continueRender`, `cancelRender` |
+| The video itself | `registerRoot`, `Composition`, `registerVideo`, `CalculateMetadataFunction` |
+| Captions | `paginateCaptions`, `Caption`, `TikTokPage` |
+
+Every motion function is a pure function of the frame, so a frame rendered out of order, or a
+single still, is the same picture the full render shows. `spring` is the closed-form solution of a
+damped harmonic oscillator; `Easing` holds the textbook closed forms; `random(seed)` is
+deterministic per seed.
+
+`<Video>` and `<OffthreadVideo>` throw `NOT_SUPPORTED_IN_V1` when rendered: video assets are not
+supported by this renderer yet, so use `<Img>` stills. A second `<Audio>` beside the narration fails
+the same way, because the narration is the only audio track the video gets. `staticFile()` takes a
+name inside the video's public directory and refuses one that starts with `/` or climbs out of it
+with `..`.
+
+## The harness
+
+`@xplainer/motion/harness` is a separate entry point with side effects, imported only by the
+renderer's generated bundle, before the scene code. It runs the page on film time — `Date`,
+`performance.now`, `setTimeout`, `setInterval` and `requestAnimationFrame` all advance only when the
+renderer asks for the next frame — and before each frame is captured it waits for render holds,
+images and fonts, and for the page to stop changing, so an image a scene's effects mount a few
+React updates after the frame is still in that frame; a frame that never stops changing is released
+with a warning in the job log. `Math.random` in the page is seeded, so it repeats from run to run.
+A scene never imports it.
+
+The exported surface of the main entry point is recorded in `api/motion.api.md` in the repository.
+
+## Docs
+
+- [Architecture][architecture] — the members and the dependency direction
+- [Decision records][adr]
+- [Roadmap][roadmap] — what is built and what is not
+
+## Licence
+
+Apache-2.0. See `LICENSE` and `NOTICE`, both shipped inside this package.
+
+[architecture]: https://github.com/BrewMyTech/xplainer.video/blob/main/docs/ARCHITECTURE.md
+[adr]: https://github.com/BrewMyTech/xplainer.video/blob/main/docs/adr/README.md
+[roadmap]: https://github.com/BrewMyTech/xplainer.video/blob/main/docs/ROADMAP.md

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.0",
+  "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"
+  }
 }