@motionscript/sdk 0.1.0-alpha.5 → 0.1.0-alpha.6

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @motionscript/sdk
 
+## 0.1.0-alpha.6
+
+### Minor Changes
+
+- 163b708: Node types are components: one spec object handed to `component2d`, `component3d` or `componentAudio`, with no classes, decorators or JSX.
+
+  - **Writing a node type.** A component is one object literal: `key`, `state` (literals and `Types`), `defaults`, `commands`, `children`, `allowedChildren`/`allowedParents`, `provide`, `load`, and its tree's own fields (`measure`, `layout`, `render` for 2D). Behaviour comes from modules you spread in and call: `Paint`, `Flow`, `Shapes`, `Typeface`, `TextLayout`, `Aim`, `Material`, `View3D`. ADR 0007 and the custom-node docs cover it.
+  - **Building nodes in code** uses calls: `Rect({ fill: 'tomato', children: [Text({ text: 'Hi' })] })`, or `new Rect({...})` for the node itself.
+  - **Every built-in and every kit node is a component**, under the same document key. Code that tested `instanceof` a class now uses the component's `.is`, or `instanceof X.node`. Changed members:
+    - `SurfacePlot3d.valueAt` and `FunctionPlot.valueAt` are now the functions `surfaceValueAt` and `curveValue`.
+    - A system's `coordinates` is replaced by `planeMap`/`axesMap`/`systemMap`.
+    - `PieChart.isSelected` is replaced by `isSliceSelected`.
+    - `ItemGrid` is a kit module (`ItemGrid.isGrid`, `ItemGrid.define`), not a base class.
+  - **The sdk no longer exports the class surface:**
+    - the decorators: `node`, `property` and every `*Property`, `command`, `withdraw`, `driveCommand`;
+    - the authoring bases: `PaintNode`, `ShapeNode`, `TextBase`, `Mesh3DBase`, `Canvas3DBase` and the `*Base` geometry classes;
+    - `asCommand`, `compose`, `drive` and `declarePaints` from `@motionscript/sdk/component`;
+    - the `jsx-runtime` and `jsx-dev-runtime` subpaths.
+    - `Node`, `Node2D`, `Node3D` and `NodeAudio` remain as types.
+  - **Editor metadata leaves the engine.** The kits no longer declare `parentKey`, `forkable`, `layout`, `seed`, `within`, `beside` or `closed`; a host keeps those in its own configs. `describe()` now reports `holds`, the trees a type takes children from, and the placement checks use it, so a 2D viewport of your own that takes 3D children places them.
+  - A command called from code with no argument runs, and a refused child is told what its parent takes (`allowedChildren`) or where it goes (`allowedParents`).
+
 ## 0.1.0-alpha.5
 
 ### Patch Changes

package/README.md

@@ -1,13 +1,13 @@
 # @motionscript/sdk
 
-**Motion Script** is a TypeScript/JSX framework for making videos with code.
+**Motion Script** is a TypeScript framework for making videos with code.
 Describe animations as documents of nodes and commands, then preview
 them live in the browser and export straight to MP4 — no timeline UI, no
 keyframe panel, just a codebase you can version, review, and generate.
 
 `@motionscript/sdk` is the flagship package: the authoring surface of
-[`@motionscript/core`](https://github.com/motionscript-dev/motionscript/tree/main/packages/core) (the document model, scene graph, runtime,
-layout, and JSX runtime) behind a single import.
+[`@motionscript/core`](https://github.com/motionscript-dev/motionscript/tree/main/packages/core) (the document model, scene graph, layout,
+and the factories a node type is written with) behind a single import.
 
 ## Getting started
 
@@ -20,7 +20,8 @@ npm install @motionscript/sdk @motionscript/core @motionscript/browser @motionsc
 
 `@motionscript/core` is a peer dependency rather than a bundled one: the
 backend and every component kit share the one copy your project installs,
-because two copies of the engine in one module graph break class identity.
+because two copies of the engine in one module graph break class identity
+(a component generates a class, and identity is per copy).
 
 ## Quick example
 
@@ -51,8 +52,8 @@ session.playback!.play();
 
 A scene is data: nodes, and commands placed at times, so any frame can be asked
 for directly and a seek costs the same in either direction. Custom drawing, and
-anything JSON cannot express, belongs in a node class registered with the engine
-and named by key. Flow layout,
+anything JSON cannot express, belongs in a component registered with the engine
+and named by key (see [Writing a node type](#writing-a-node-type)). Flow layout,
 fills, gradients, filters, SkSL shader effects, paths, text, audio and 3D are
 all supported. See the
 [docs](https://motionscript.dev/docs) for the full feature set.
@@ -66,9 +67,15 @@ all supported. See the
   `Polygram`, `MaskGroup`, `BooleanGroup`), text (`Text`,
   `RichText`, `NumberNode`), structure (`Canvas2D`, `Canvas3D`, `Camera`), and
   media (`Video`; images are a fill, `Fills.image`). Layout is the `flow` prop,
-  through `flowOps`.
-- **Animation**: commands (`to`, `set`, `variableTo`/`variableSet` and a node's
-  own `@command` methods), each placed at a time, easing (`linear`, `easeIn`,
+  through `flowOps`. Each is a component: call it to build one
+  (`Rect({ fill: 'red', children: [...] })`).
+- **Components**: the factories `component2d`, `component3d` and
+  `componentAudio`, the `Types` a component's state is declared with,
+  `commandsFor`, `provides`, and the modules a component spreads in and calls:
+  `Paint`, `Flow`, `Shapes`, `Aim`, `Typeface`, `TextLayout`, `Material`,
+  `View3D`.
+- **Animation**: commands (`to`, `set`, `variableTo`/`variableSet` and a node
+  type's own), each placed at a time, easing (`linear`, `easeIn`,
   `easeOut`, `easeInOut`), and interpolation (`lerpNumber`).
 - **Styling & effects**: `Fills`, `Effects`, `Adjustments`, `VideoAdjustments`,
   `AudioFilters`, plus the `Stroke`/`Shadow`/`Corners` attribute types.
@@ -76,17 +83,11 @@ all supported. See the
   next major.
 - **Audio**: the `SoundNode` and `AudioBus` nodes.
 - **Utilities**: `createRef`, `clamp`, `generateList`, `createContext`,
-  `Random`, the `@property` decorator.
-- **JSX runtime**: `@motionscript/sdk/jsx-runtime` and
-  `@motionscript/sdk/jsx-dev-runtime`, so a composite node can build its children
-  as TSX (see [JSX](#jsx)).
+  `Random`.
 - **Component machinery**: `@motionscript/sdk/component`, what a component
-  package needs beyond the barrel: seekable entrances (`at`, `sequence`,
-  `together`, `hold`, `compose`, `drive`, and `asCommand` to return one from a
-  `@command()` method), `declarePaints`, number formatting and the
-  orbit-camera lerps. It is a subpath because a scene author never needs it and
-  `hold` is a name on both sides: the barrel's is an audio curve, this one is a
-  seekable pause. A file that needs both aliases one.
+  package needs beyond the barrel: number formatting, text defaults, the named
+  shape outlines and the orbit-camera lerps. It is a subpath because a scene
+  author never needs it.
 
 Component kits such as [`@motionscript/code`](https://github.com/motionscript-dev/motionscript/tree/main/packages/components/code) and
 [`@motionscript/math`](https://github.com/motionscript-dev/motionscript/tree/main/packages/components/math) are not bundled here. They are
@@ -118,23 +119,39 @@ until core has been built. `src/tests/sdk-parity.test.ts` in core compares this
 barrel's value names with core's `sdk/index.ts`; it fails when core's `dist/` is
 stale or absent.
 
-## JSX
+## Writing a node type
 
-Configure TypeScript with `"jsx": "react-jsx"` and `"jsxImportSource":
-"@motionscript/sdk"` (`"react-jsxdev"` for the dev runtime), plus
-`"experimentalDecorators": true` for `@property` and `@node`. Only the automatic
-runtime exists: there is no `createElement` or `h`. An element is a node
-instance: `JSX.Element` is `Node`, `IntrinsicElements` is empty (no lowercase
-tag), and the tag must be a class (an arrow function throws `TypeError: type is
-not a constructor`). A fragment is an array at run time. `key` is written to the
-node's `key`, and `ref` takes a `createRef()`. Which children a node accepts is a
-run-time check, not a type, so annotate `const r: Node = <Rect />`, not `Rect`.
+A node type is one object handed to a factory. `key` is its document key;
+`state` its entries, plain values or `Types` builders, plus whatever modules it
+spreads in; `commands` what it does on the timeline; `render` what it draws:
+
+```ts
+import { component2d, Graphics2D, Paint, Types } from '@motionscript/sdk';
+import { createBrowserEngine } from '@motionscript/browser';
+
+export const Gauge = component2d({
+  key: 'gauge',
+  state: { ...Paint.state, value: Types.number(0, { min: 0, max: 1 }) },
+  commands: { ...Paint.commands, fillUp: { args: ['value'] } },
+  render: (ctx, state) => Paint.draw(ctx, state, new Graphics2D().ellipse({
+    width: ctx.size.width, height: ctx.size.height, ratio: 0.75, startAngle: -90, sweep: 360 * state.value,
+  })),
+});
+
+const engine = await createBrowserEngine({ wasmUrl: '/canvaskit.wasm', nodes: [Gauge] });
+```
+
+The factory generates the node class, declares its key and writes its entries
+and commands where the registry reads them, so a document can name `gauge`
+once it is handed to an engine. Calling `Gauge({ value: 0.4 })` builds one in
+code, typed by its entries. No decorators and no JSX are needed: a component
+compiles with plain TypeScript. The guide is the
+[custom node docs](https://motionscript.dev/docs/custom-node/introduction).
 
 ## Loading from a CDN
 
 `dist/browser/` holds one ES module per export. Core is a peer, so the modules
-leave `@motionscript/core/sdk`, `/component`, `/jsx/jsx-runtime` and
-`/jsx/jsx-dev-runtime` as imports, and `dist/browser/manifest.json` maps each
+leave `@motionscript/core/sdk` and `/component` as imports, and `dist/browser/manifest.json` maps each
 export to its file and lists core under `peers`. An import map names
 `@motionscript/sdk` (and its subpaths) and `@motionscript/core` (and its
 subpaths) once, and every kit loaded beside them shares both.

package/dist/browser/manifest.json

@@ -1,11 +1,9 @@
 {
   "name": "@motionscript/sdk",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.6",
   "exports": {
     ".": "dist/browser/index.js",
-    "./component": "dist/browser/component.js",
-    "./jsx-runtime": "dist/browser/jsx-runtime.js",
-    "./jsx-dev-runtime": "dist/browser/jsx-dev-runtime.js"
+    "./component": "dist/browser/component.js"
   },
   "peers": [
     "@motionscript/core"

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@motionscript/sdk",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.6",
   "type": "module",
-  "description": "The Motion Script authoring surface behind one import: document types, nodes, commands, styling, the JSX runtime, and the machinery component kits build on.",
+  "description": "The Motion Script authoring surface behind one import: document types, components and their modules, commands, styling, and the machinery component kits build on.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/motionscript-dev/motionscript.git",
@@ -38,18 +38,10 @@
     "./component": {
       "types": "./dist/component.d.ts",
       "default": "./dist/component.js"
-    },
-    "./jsx-runtime": {
-      "types": "./dist/jsx-runtime.d.ts",
-      "default": "./dist/jsx-runtime.js"
-    },
-    "./jsx-dev-runtime": {
-      "types": "./dist/jsx-dev-runtime.d.ts",
-      "default": "./dist/jsx-dev-runtime.js"
     }
   },
   "peerDependencies": {
-    "@motionscript/core": "^0.1.0-alpha.5"
+    "@motionscript/core": "^0.1.0-alpha.6"
   },
   "devDependencies": {
     "@types/node": "^25.6.2",
@@ -61,7 +53,7 @@
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.48.0",
     "vitest": "^4.1.5",
-    "@motionscript/core": "0.1.0-alpha.5"
+    "@motionscript/core": "0.1.0-alpha.6"
   },
   "scripts": {
     "build": "eslint . && tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json && node ../../scripts/build-browser.mjs",

package/dist/browser/jsx-dev-runtime.js

@@ -1,2 +0,0 @@
-import{jsxDEV as m,Fragment as o}from"@motionscript/core/jsx/jsx-dev-runtime";export{o as Fragment,m as jsxDEV};
-//# sourceMappingURL=jsx-dev-runtime.js.map

package/dist/browser/jsx-dev-runtime.js.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../src/jsx-dev-runtime.ts"],
-  "sourcesContent": ["export { jsxDEV, Fragment } from '@motionscript/core/jsx/jsx-dev-runtime';\r\nexport type { JSX } from '@motionscript/core/jsx/jsx-runtime';\r\n"],
-  "mappings": "AAAA,OAAS,UAAAA,EAAQ,YAAAC,MAAgB",
-  "names": ["jsxDEV", "Fragment"]
-}

package/dist/browser/jsx-runtime.js

@@ -1,2 +0,0 @@
-import{jsx as x,jsxs as e,Fragment as j}from"@motionscript/core/jsx/jsx-runtime";export{j as Fragment,x as jsx,e as jsxs};
-//# sourceMappingURL=jsx-runtime.js.map

package/dist/browser/jsx-runtime.js.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../src/jsx-runtime.ts"],
-  "sourcesContent": ["export { jsx, jsxs, Fragment } from '@motionscript/core/jsx/jsx-runtime';\r\nexport type { JSX } from '@motionscript/core/jsx/jsx-runtime';\r\n"],
-  "mappings": "AAAA,OAAS,OAAAA,EAAK,QAAAC,EAAM,YAAAC,MAAgB",
-  "names": ["jsx", "jsxs", "Fragment"]
-}