@motionscript/code 0.0.0-stage → 0.1.0-alpha.10

package/CHANGELOG.md

@@ -0,0 +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/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

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,4 +1,175 @@
-# Temporary Holding Version
+# @motionscript/code
 
-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.
-If no other versions are published within 30 days, this package and version will be deleted.
+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`**, 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 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 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 @motionscript/sdk
+```
+
+See the
+[docs](https://motionscript.dev/docs) for the full feature set and API
+reference.
+
+## Development
+
+From the monorepo root:
+
+```bash
+pnpm --filter @motionscript/code build
+pnpm --filter @motionscript/code test
+```