@motionscript/code 0.1.0-alpha.0 → 0.1.0-alpha.10

package/CHANGELOG.md

@@ -1,5 +1,101 @@
 # @motionscript/code
 
+## 0.1.0-alpha.10
+
+## 0.1.0-alpha.9
+
+## 0.1.0-alpha.8
+
+## 0.1.0-alpha.7
+
+## 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
+
+- da6f97a: Every package ships a `NOTICE`, and a browser build lists what it bundles.
+
+  - Each tarball carries the repository `NOTICE`: the copyright line and the MIT attributions for the noise functions in `skia-render`'s fractal-noise fill (David Hoskins' "Hash without Sine", Inigo Quilez's 2D simplex noise).
+  - `@motionscript/canvaskit` ships `THIRD_PARTY_NOTICES.txt` with the licences of the libraries compiled into the binary: FreeType, HarfBuzz, ICU 74, zlib, libpng, Brotli, WOFF2, Emscripten and musl.
+  - `dist/browser/manifest.json` gains `thirdParty`, the packages the browser build bundled (`name`, `version`, `license`), and their licence and NOTICE files are written to `dist/browser/THIRD_PARTY_LICENSES.txt`. `@motionscript/browser` bundles mediabunny (MPL-2.0, unmodified; source at https://github.com/Vanilagy/mediabunny), esbuild-wasm and three; `@motionscript/math` bundles MathJax.
+
+- 1778355: The published packages carry what a user needs and say what they are.
+
+  - `@motionscript/code` no longer ships `dist/tests/diff.bench.*`, and `@motionscript/math` no longer ships `dist/tests/harness.*` or `mathjax.setup.*`: test helpers under a `tests` folder are left out of every package's build.
+  - `@motionscript/sdk`'s description no longer repeats core's, and `@motionscript/math`'s names the coordinate systems, plots, 3D graphs and network graphs it has as well as formulas.
+  - The READMEs of `@motionscript/canvaskit`, `@motionscript/charts`, `@motionscript/geo`, `@motionscript/grids`, `@motionscript/skia-render` and `@motionscript/geography` say what to install, and `@motionscript/sdk`'s example now opens the document in an engine and plays it. Links between packages point at the repository, so they work on npm.
+
+## 0.1.0-alpha.4
+
+### Minor Changes
+
+- c9535a6: `Code` can mark whole rows, beside dimming what is outside a range.
+
+  - `highlightRows` (`target`, `color`, `radius`) lays a band behind every line a range touches, across the block and under the text. A second call slides and resizes the band onto its new rows; several ranges give a band each, and one with no counterpart fades. A band is tied to its lines, so it moves with them through an `append`, `insert` or `remove`.
+  - `resetRowHighlight` fades the bands out.
+  - `drawCode` takes the bands as optional fields of its state (`rowBands`, `rowsEdit`, `boxW`), so a caller that draws a listing itself is unaffected.
+
+### Patch Changes
+
+- 3ba3e98: A `code` node reports what it cannot highlight, follows its `language` and `theme`, reads Windows line endings, and diffs long edits within a budget.
+
+  - An unknown language, a grammar whose import is rejected and an unknown theme name each logged nothing and fell back silently. Each now logs one `[Code]` warning per name, with the import's reason where there is one. `''`, `text` and `plaintext` mean plain text and stay silent.
+  - A tweened or bound `theme` or `language` left the old colours once any listing command had run, because only `set()` re-tokenized. The listing now re-derives from `code`, `language` and `theme` on every read, and a theme-only change keeps the token ids a highlight names.
+  - `\r\n` and a lone `\r` are line breaks, in `code`, in the text a command brings in and in `to({ code })`; they used to survive as a character at the end of each line. `normalizeSource` is exported from the engine barrel.
+  - The kit's own commands (`append`, `prepend`, `insert`, `remove`, `replace`, `highlight`, `resetHighlight`, `to`) run their duration and write nothing on a node that is not in a tree.
+  - Aligning the lines of an edit was quadratic (741 ms for 1,000 lines). Lines equal at either end and lines that occur once on both sides now anchor the alignment, and only the runs between anchors are compared, within `LINE_ALIGN_CELLS` per run and `EDIT_ALIGN_CELLS` per edit; a larger run leaves and enters as whole rows. `pnpm bench` measures it.
+
+- ad28707: Component kit fixes.
+
+  - Charts: a bar chart maps its columns across the plot panel as laid out (and takes the line chart's top headroom), so a column ends on its marker's grid line. A pie chart's wedges, labels and legend follow `data` and the palette once they are set. A restated value-axis or y/x-axis `range` or `ticks` in `to()` rescales continuously from the axis as drawn, instead of cutting at the midpoint. Without a legend (or without series) the entrance keeps that beat's share, so the call-out and legend land where the slot lays them out. A constant line series gets a scale with width, a `NaN` or infinite cell reads as 0, and tick captions gain decimals when the step is finer than 0.1.
+  - Code: the compiled highlighter is cached per style object, so two styles sharing a name no longer colour alike. A `CodeRanges` chain serialises as its ranges, so a stored `highlight` target selects what it did before it was saved.
+  - LaTeX: seeking from inside a morph to a time before it restores the source formula instead of leaving the last morph frame.
+  - Geo: custom border rings are wound for d3, so a GeoJSON counter-clockwise ring draws as the small region it encloses; a great-circle path between antipodal points runs over the north pole instead of wherever rounding lands.
+  - Audio: bottom-aligned waveform bars stand on the floor of the box instead of hanging from the top.
+  - `Code` and `Latex` take an optional props bag, so `new Registry({ nodes: NODES })` and `createBrowserEngine({ nodes: NODES })` type-check without a cast.
+
+## 0.1.0-alpha.3
+
+### Patch Changes
+
+- 4b23387: A `code` node draws the listing its props describe until its first command starts.
+
+  - The structure, highlight and in-flight transitions the listing commands own live outside the props, and only a command that had started wrote them, so before the first one a frame showed whatever the last evaluation left: the end of every command. A listing appended to at 1 s drew the new rows from 0 s, and a `highlight` at 0.8 s, as in the README's own example, dimmed the listing from 0 s, jumped to full brightness when it started, then faded back. A seek back past an edit or a highlight also left it drawn mid-transition. Until a command applies, all three are now derived from the props, so a frame is the same however the playhead reached it, and a highlight still selects the tokens it was built against when a later edit returns the source to the same text.
+  - The README says what the host supplies: a monospaced face under `fontFamily` (`Fira Mono` by default) in the engine's asset manifest, without which the listing draws no text or falls back to another registered face.
+
+## 0.1.0-alpha.2
+
+### Patch Changes
+
+- 0227e28: A document's `remove` command on a `code` node erases its `target` range. It used to reach `Node.remove` instead of `Code.erase` and leave the listing as it was.
+
+## 0.1.0-alpha.1
+
+### Minor Changes
+
+- 59cecba: Build on `@motionscript/sdk` instead of `@motionscript/core`. The peer dependency is now `@motionscript/sdk`, every import goes through it (and `@motionscript/sdk/component` for the component machinery), and the browser build leaves `@motionscript/sdk` an import, so an import map names it once. A component copied with `ms add` imports the SDK too, and its registry item depends on `@motionscript/sdk` rather than `@motionscript/core`. `@motionscript/charts/kit` re-exports `@motionscript/sdk/component` where it re-exported `@motionscript/core/component`.
+
 ## 0.1.0-alpha.0
 
 Initial release.

package/NOTICE

@@ -0,0 +1,49 @@
+Motionscript
+Copyright 2026 Motionscript LLC
+
+This product includes the third-party code below, each part under the MIT
+License reproduced at the end of this file.
+
+- packages/renderer/crates/renderer/src/shaders/prim.wgsl (`fn_hash2`):
+  "Hash without Sine" by David Hoskins (https://www.shadertoy.com/view/4djSRW).
+  Copyright (c) 2014 David Hoskins.
+
+- packages/renderer/crates/renderer/src/shaders/prim.wgsl (`simplex_noise`): "Noise - simplex - 2D" by Inigo Quilez
+  (https://www.shadertoy.com/view/Msf3WH). Copyright (c) 2013 Inigo Quilez.
+
+- packages/renderer/crates/render3d (in @motionscript/renderer's WebAssembly):
+  its shaders (src/shaders/mesh.wgsl) port three.js r185's mesh programs and
+  src/geometry.rs its primitive generators (https://threejs.org).
+  Copyright (c) 2010-2026 three.js authors.
+
+@motionscript/renderer's WebAssembly (dist/ms_renderer_bg.wasm) compiles in
+Rust crates under MIT, Apache-2.0, Zlib and Unicode-3.0 terms (wgpu, naga,
+harfrust, read-fonts, kurbo, wasm-bindgen and others); their notices are in
+packages/renderer/THIRD_PARTY_NOTICES.txt.
+
+MP3 export loads @mediabunny/mp3-encoder (MPL-2.0), a WebAssembly build of
+the LAME MP3 encoder (LGPL, https://lame.sourceforge.io), on first use.
+
+The browser builds under dist/browser/ bundle each package's npm dependencies;
+dist/browser/THIRD_PARTY_LICENSES.txt in each package lists them with their
+licences.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,70 +1,168 @@
 # @motionscript/code
 
-Animated, syntax-highlighted code blocks for [Motion Script](https://motionscript.dev).
-The `Code` node tokenizes source with [Shiki](https://shiki.style) and animates
-edits at the token level, so appending, inserting, removing, replacing, and
-highlighting code all morph smoothly instead of snapping.
-
-```tsx
-import { createScene, createRef } from '@motionscript/core';
-import { Code, lines, word } from '@motionscript/code';
-
-export default createScene(function* (stage) {
-  const code = createRef<Code>();
-
-  stage.add(
-    <Code
-      ref={code}
-      language="typescript"
-      theme="github-dark"
-      fontSize={28}
-      code={`function greet(name) {\n  return "hi";\n}`}
-    />,
-  );
-
-  yield* code().append('\ngreet("world");', 0.6);
-  yield* code().highlight(lines(2), 0.4);
-  yield* code().replace(word(2, 10, 4), '`hi, ${name}`', 0.6);
-});
+Animated, syntax-highlighted code listings for [Motion Script](https://motionscript.dev).
+The `Code` node highlights source with [Lezer](https://lezer.codemirror.net)
+grammars and animates edits at the token level: each edit is diffed against the
+listing it becomes, so tokens that survive travel to their new columns, removed
+ones fade out and new ones fade in, rather than the listing snapping.
+
+Hand `Code` to the engine through your project entry's `nodes`, and any
+document that engine opens can name it as `code`:
+
+```ts
+// src/project.ts
+import { Code } from '@motionscript/code';
+
+export const nodes = [Code];
+```
+
+```ts
+import type { CompositionDocument } from '@motionscript/sdk';
+import { lines } from '@motionscript/code';
+
+export default {
+  kind: 'composition',
+  nodes: [
+    { id: 'listing', type: 'code', parentId: null, layerOrder: 0,
+      props: { code: 'function greet(name) {\n  return "hi";\n}', language: 'typescript',
+               theme: 'github-dark', fontSize: 28 } },
+  ],
+  commands: [
+    { id: 'call', type: 'append', targetId: 'listing', at: 0, duration: 0.6,
+      args: { code: '\ngreet("world");' } },
+    { id: 'focus', type: 'highlight', targetId: 'listing', at: 0.8, duration: 0.4,
+      args: { target: lines(2) } },
+  ],
+} satisfies CompositionDocument;
 ```
 
 ## What's in here
 
-- **`Code`** node, a hugging block of syntax-highlighted source. Set `code`,
-  `language`, and `theme` to switch what is shown; tune `fontSize`,
+- **`Code`**, a hugging block of highlighted source, written with
+  `component2d`: call it (`Code({ ... })`) or construct it (`new Code({ ... })`).
+  Set `code`, `language` and `theme` to choose what is shown; tune `fontSize`,
   `fontFamily`, `lineHeight`, `letterSpacing`, `showLineNumbers`,
-  `lineNumberGap`, and `padding` for layout.
-- **Token-level transitions**, generator methods you `yield*` from a scene:
-  - `append(code, duration)` / `prepend(code, duration)`, fade in lines at the
-    end or start.
-  - `insert([line, col], code, duration)`, splice code into a line or grow new
-    lines mid-document.
-  - `remove(range, duration)`, collapse tokens (and whole lines) so surrounding
-    text reflows.
-  - `replace(range, next, duration)`, cross-fade old tokens out and new ones in.
-  - `highlight(range, duration)` / `resetHighlight(duration)`, dim everything
-    outside the range, then restore it.
-- **Range helpers**, `word(line, col, length)`, `lines(from, to)`, and
-  `range(startLine, startCol, endLine, endCol)` build the `CodeRange` values the
-  transitions take. `findFirstRange`, `findRangeAt`, and `findAllRanges` locate
-  ranges by matching literal text.
-- **`initSyntaxHighlighter(themes, langs)`**, optional preloading of Shiki
-  themes and languages so the first frame renders fully highlighted.
+  `lineNumberGap` and `padding` for layout.
+- **Token-level commands**: `append`/`prepend` (lines at the end or start),
+  `insert` (at a `[line, col]` position), `remove`, `replace`,
+  `highlight`/`resetHighlight` (dim everything outside a range, then restore
+  it), and `highlightRows`/`resetRowHighlight` (a coloured band behind whole
+  lines, which slides onto the next rows it is given and follows its lines
+  through an edit). A `to` command on `code` diffs the whole listing the same way;
+  while it runs, `code` holds a `CodeBlend` (`{ from, to, t }`) rather than a
+  string, and a source again at either end.
+- **Range helpers**: `word(line, col, length)`, `lines(from, to)` and the
+  chainable `CodeRanges` build the ranges those commands take.
+- **Themes**: `github-dark`, `github-light`, `vscode-dark`, `vscode-light`
+  and a default, plus `registerCodeTheme` for your own.
+  `initSyntaxHighlighter(themes, langs)` preloads grammars so the first frame
+  renders fully highlighted.
 
 Every token keeps a stable identity across edits, so concurrent animations at
 different positions do not clobber each other while one is mid-flight.
 
-This package builds on [`@motionscript/core`](../../core) (the scene graph and
-animation runtime) and renders through whatever backend draws the scene, such as
-[`@motionscript/browser`](../../browser).
+This package is written against [`@motionscript/sdk`](https://github.com/motionscript-dev/motionscript/tree/main/packages/sdk), which it
+takes as a peer dependency, and renders through whatever backend draws the
+scene, such as [`@motionscript/browser`](https://github.com/motionscript-dev/motionscript/tree/main/packages/browser).
+
+## Languages, themes and line endings
+
+- **Languages**: `typescript` (`ts`), `tsx`, `javascript` (`js`), `jsx`, `python`
+  (`py`), `json`, `html`, `css`, `rust`, `go`, `java`, `cpp` (`c++`), `php`,
+  `markdown` (`md`), `xml` and `yaml` (`yml`). `shell` is an alias of
+  `javascript`, because no shell grammar is bundled. Names are case-insensitive.
+- **An unknown language, a grammar whose import is rejected and an unknown theme
+  name** each fall back (plain text, plain text and the default theme) and log one
+  `[Code]` warning per name for the life of the process. `''`, `text` and
+  `plaintext` mean plain text on purpose and say nothing.
+- **`language` and `theme` can be tweened or bound.** The listing is re-coloured
+  from the props on the next frame, keeping the token identities a highlight
+  already names.
+- **`\r\n` and a lone `\r` are line breaks**, in `code` and in the text a command
+  brings in; the node's `code` reads back with `\n` after its first command.
+- **Edits are diffed within a budget.** Lines are paired by the same text at the
+  ends of the listing and by lines that occur once on both sides, so an edit
+  to a long listing costs in proportion to what changed. Only a run of changed
+  lines between two such anchors is compared pairwise, up to
+  `LINE_ALIGN_CELLS` (40,000) line pairs per run and 160,000 per edit; beyond
+  that its lines leave and enter as whole rows instead of morphing into each
+  other.
+- **A command on a node that is not in a tree** runs its duration and writes
+  nothing. A document cannot reach this, because the validator rejects a command
+  that starts before its target is present.
+
+## Ranges, queries and what a copy holds
+
+- **Ranges are 1-indexed** in lines and columns. `endLine`/`endCol` may be
+  `Infinity` (to the end of the line or document); a range that went through
+  JSON holds `null` there and reads the same. Positions clamp, so no command
+  throws for a bad range, and a `CodeRanges` chain serialises as its array of
+  ranges.
+- **`findAllRanges(source, text)`, `findRangeAt(source, text, index)` and
+  `findFirstRange(source, text)`** return the literal matches in a source as
+  ranges: pass a listing's `code`. `listingOf(node)` is what a listing shows now:
+  its source, its token rows and the edit in flight.
+- **`remove` is the command's key, and a node has no method of that name for it**:
+  `Node.remove` already takes a child out of the tree, so the command is
+  dispatched by key (a document, a host's registry) and reaches the node's
+  `_command_remove`.
+- **A `Code` takes no children and has no `fill`, `stroke` or `shadow`**; a panel
+  behind it is a parent `Rect`. It also refuses the ambient text style
+  (`<DefaultTextStyle>`): its columns are measured against its own face, so an
+  inherited family or weight would shape glyphs the geometry never measured.
+- **`diffStrategy` and `phaseStrategy`** (`CodeStrategies`) replace how an edit is
+  paired and how its out/move/in windows are timed. They are arguments of
+  `defineCode({ diffStrategy, phaseStrategy })`, which returns a `code` component
+  using them: hand that to the engine in place of `Code`. A strategy is a
+  function, which a prop would read as a binding, so a document cannot set one.
+- **Each listing command writes the listing it acted on**, so the token ids a
+  highlight or a band captured are the ones drawn. Two commands of one kind
+  that overlap (two edits, two highlights) hand over from the later one's first
+  frame: the later command's state replaces the earlier's while both run.
+- **A `Code` is drawn from what its last measure laid out**, which its parent
+  asks for before every frame; one that was never measured draws nothing.
+- **Highlighter state is per process.** Loaded grammars, registered themes and
+  token ids are shared by every `Code` in it.
+- **A copy of `code` takes only `node.ts`** (`registry.json`). The highlighter,
+  diff, layout and drawing stay in this package behind `src/engine.ts`, which the
+  copy imports from `@motionscript/code`; the grammars are dynamic imports, so a
+  host's bundler must resolve `@lezer/*` from where the package is installed.
+
+## The monospaced face is yours to supply
+
+`Code` measures and draws every token in its `fontFamily`, `Fira Mono` by
+default, and lines its columns up on that face's advances. The package ships no
+font file and names no URL: list a monospaced face under that family in the
+engine's asset manifest, alongside the node itself.
+
+```ts
+const engine = await createBrowserEngine({
+  wasmUrl,
+  nodes: [Code],
+  manifest: {
+    image: {}, video: {}, audio: {},
+    font: {
+      'Fira Mono@400': {
+        fontFamily: 'Fira Mono', fontWeight: 400,
+        src: '/fonts/FiraMono-Regular.ttf', sizeBytes: 0,
+      },
+    },
+  },
+});
+```
+
+A family the manifest does not list is never loaded. The loader warns once, and
+the listing draws no text, or shapes in whichever other face is registered. To
+use another face, set `fontFamily` on the node and list that family instead.
 
 ## Usage
 
 ```bash
-npm install @motionscript/code
+npm install @motionscript/code @motionscript/sdk
 ```
 
-See the [docs](https://motionscript.dev/docs) for the full feature set and API
+See the
+[docs](https://motionscript.dev/docs) for the full feature set and API
 reference.
 
 ## Development