@rasamjs/core 0.1.2 → 0.3.0

package/API.md

@@ -1,7 +1,7 @@
 # Public entry points
 
 Generated from emitted declarations and document-free runtime imports.
-Run `npm run api:check` to detect changes; review differences before `api:update`.
+Run `bun run api:check` to detect changes; review differences before `api:update`.
 
 Only documented operations are supported application APIs. Deep imports, mutable
 service bookkeeping, TypeScript-private methods and undocumented symbol hooks remain internal,
@@ -14,9 +14,9 @@ Runtime exports (32):
 
 `BBox`, `Circle`, `ClipPath`, `Defs`, `Ellipse`, `Group`, `Line`, `LinearGradient`, `Marker`, `Matrix`, `Path`, `PathArray`, `PathBuilder`, `PointArray`, `Polygon`, `Polyline`, `RadialGradient`, `Rect`, `Renderer`, `SVG`, `Shape`, `Stop`, `Svg`, `SvgNode`, `SvgTemplate`, `SvgText`, `Use`, `Vec2`, `ViewBox`, `ViewportError`, `attr`, `svg`.
 
-Type-only exports (46):
+Type-only exports (48):
 
-`AnyNode`, `AttributeValue`, `Bounds`, `Box`, `CircleOptions`, `ClipPathOptions`, `CommonAttributes`, `Disposable`, `DrawingPointerEvent`, `EllipseOptions`, `GeometryChange`, `GradientStop`, `Length`, `LineOptions`, `LinearGradientOptions`, `MarkerOptions`, `MatrixDecomposition`, `MatrixValues`, `NestedSvgOptions`, `NodeEvents`, `PaintValue`, `PathAttributes`, `PathCommand`, `PathInput`, `PathOptions`, `PathSegment`, `Point`, `PointInput`, `PointerEventType`, `PolygonOptions`, `PolylineAttributes`, `PolylineOptions`, `RadialGradientOptions`, `RectOptions`, `ResourceReference`, `SVGOptions`, `StyleProperties`, `SvgAttributes`, `SvgOptions`, `TemplateInstance`, `TemplateValue`, `TextAttributes`, `TextMeasurementProvider`, `TextOptions`, `TransformState`, `UseOptions`.
+`AnyNode`, `AttributeValue`, `Bounds`, `Box`, `CircleOptions`, `ClipPathOptions`, `CommonAttributes`, `Disposable`, `DrawingPointerEvent`, `EditRules`, `EllipseOptions`, `GeometryChange`, `GradientStop`, `Length`, `LineOptions`, `LinearGradientOptions`, `MarkerOptions`, `MatrixDecomposition`, `MatrixValues`, `NestedSvgOptions`, `NodeEvents`, `PaintValue`, `PathAttributes`, `PathCommand`, `PathInput`, `PathOptions`, `PathSegment`, `Point`, `PointInput`, `PointerEventType`, `PolygonOptions`, `PolylineAttributes`, `PolylineOptions`, `PortDefinition`, `RadialGradientOptions`, `RectOptions`, `ResourceReference`, `SVGOptions`, `StyleProperties`, `SvgAttributes`, `SvgOptions`, `TemplateInstance`, `TemplateValue`, `TextAttributes`, `TextMeasurementProvider`, `TextOptions`, `TransformState`, `UseOptions`.
 
 ## @rasamjs/core/advanced
 
@@ -24,9 +24,9 @@ Runtime exports (57):
 
 `Attributes`, `BBox`, `BoundsService`, `Circle`, `ClipPath`, `Creatable`, `Defs`, `DefsManager`, `DomFactory`, `DrawingContext`, `Elements`, `Ellipse`, `Emitter`, `Gradient`, `Group`, `Guards`, `Line`, `LinearGradient`, `Marker`, `Matrix`, `Namespace`, `Parent`, `Path`, `PathArray`, `PathBuilder`, `PathGeometry`, `PointArray`, `PointerRouter`, `Polygon`, `Polyline`, `RadialGradient`, `Rect`, `Registry`, `Renderer`, `SVG`, `Scheduler`, `Shape`, `Sizable`, `Stop`, `Styleable`, `Svg`, `SvgNode`, `SvgTag`, `SvgTemplate`, `SvgText`, `Textual`, `Transformable`, `Use`, `Vec2`, `ViewBox`, `ViewportError`, `attr`, `isParent`, `isTextual`, `isTransformable`, `mix`, `svg`.
 
-Type-only exports (52):
+Type-only exports (55):
 
-`AnyNode`, `AttributeValue`, `Bounds`, `Box`, `CircleOptions`, `ClipPathOptions`, `CommonAttributes`, `CreatableFeature`, `Ctor`, `Disposable`, `DrawingPointerEvent`, `ElementClass`, `EllipseOptions`, `GeometryChange`, `GradientStop`, `Length`, `LineOptions`, `LinearGradientOptions`, `MarkerOptions`, `MatrixDecomposition`, `MatrixValues`, `NestedSvgOptions`, `NodeEvents`, `PaintValue`, `ParentFeature`, `ParentNode`, `PathAttributes`, `PathCommand`, `PathInput`, `PathOptions`, `PathSegment`, `Point`, `PointInput`, `PointerEventType`, `PolygonOptions`, `PolylineAttributes`, `PolylineOptions`, `RadialGradientOptions`, `RectOptions`, `ResourceReference`, `SVGOptions`, `SizableFeature`, `StyleProperties`, `SvgAttributes`, `SvgOptions`, `TemplateInstance`, `TemplateValue`, `TextAttributes`, `TextMeasurementProvider`, `TextOptions`, `TransformState`, `UseOptions`.
+`AnyNode`, `AttributeValue`, `Bounds`, `Box`, `CircleOptions`, `ClipPathOptions`, `CommonAttributes`, `CreatableFeature`, `Ctor`, `Disposable`, `DrawingPointerEvent`, `EditRules`, `ElementClass`, `ElementVariant`, `EllipseOptions`, `GeometryChange`, `GradientStop`, `Length`, `LineOptions`, `LinearGradientOptions`, `MarkerOptions`, `MatrixDecomposition`, `MatrixValues`, `NestedSvgOptions`, `NodeEvents`, `PaintValue`, `ParentFeature`, `ParentNode`, `PathAttributes`, `PathCommand`, `PathInput`, `PathOptions`, `PathSegment`, `Point`, `PointInput`, `PointerEventType`, `PolygonOptions`, `PolylineAttributes`, `PolylineOptions`, `PortDefinition`, `RadialGradientOptions`, `RectOptions`, `ResourceReference`, `SVGOptions`, `SizableFeature`, `StyleProperties`, `SvgAttributes`, `SvgOptions`, `TemplateInstance`, `TemplateValue`, `TextAttributes`, `TextMeasurementProvider`, `TextOptions`, `TransformState`, `UseOptions`.
 
 ## @rasamjs/core/animation
 
@@ -50,13 +50,23 @@ Type-only exports (7):
 
 ## @rasamjs/core/changes
 
-Runtime exports (14):
+Runtime exports (15):
 
-`ChangeConflictError`, `ChangeObserverError`, `ChangeRollbackError`, `beginChangeGroup`, `captureModelState`, `changeKey`, `claimRecorder`, `combineChanges`, `observeChanges`, `restoreChanges`, `restoreModelState`, `sameState`, `validateModelState`, `withChanges`.
+`ChangeConflictError`, `ChangeObserverError`, `ChangeRollbackError`, `beginChangeGroup`, `captureModelState`, `changeKey`, `claimRecorder`, `combineChanges`, `deriveChanges`, `observeChanges`, `restoreChanges`, `restoreModelState`, `sameState`, `validateModelState`, `withChanges`.
 
-Type-only exports (13):
+Type-only exports (14):
 
-`ChangeBatch`, `ChangeEvent`, `ChangeGroup`, `ChangeMetadata`, `ContentState`, `ModelChange`, `ModelFeatures`, `ModelSnapshot`, `NativeNodeState`, `NodeHandle`, `Placement`, `PropertyState`, `TextPolicies`.
+`ChangeBatch`, `ChangeDerivation`, `ChangeEvent`, `ChangeGroup`, `ChangeMetadata`, `ContentState`, `ModelChange`, `ModelFeatures`, `ModelSnapshot`, `NativeNodeState`, `NodeHandle`, `Placement`, `PropertyState`, `TextPolicies`.
+
+## @rasamjs/core/components
+
+Runtime exports (7):
+
+`Component`, `ComponentTypes`, `action`, `component`, `isComponentChild`, `prop`, `state`.
+
+Type-only exports (9):
+
+`ActionDefinition`, `ComponentClass`, `ComponentDefinition`, `ComponentFields`, `ComponentOptions`, `ComponentProps`, `PropDefinition`, `PropOptions`, `PropValue`.
 
 ## @rasamjs/core/data
 
@@ -128,6 +138,16 @@ Type-only exports (1):
 
 `NodePredicate`.
 
+## @rasamjs/core/raster
+
+Runtime exports (1):
+
+`exportImage`.
+
+Type-only exports (1):
+
+`RasterOptions`.
+
 ## @rasamjs/core/resources
 
 Runtime exports (4):

package/CHANGELOG.md

@@ -1,6 +1,103 @@
 # Changelog
 
-## [0.1.2] (unreleased)
+## Unreleased
+
+## [0.3.0] - 2026-11-07
+
+- Add `DefsManager.consumersOf(target)`, the nodes holding a typed reference to a target,
+  read from the reference index instead of scanning the drawing.
+- Treat connector ends (`data-rasam-connector-start` and `-end`) as links, not
+  resources: exporting or copying a connector no longer copies its targets into
+  `<defs>`, and importing one whose target was left out drops that link instead of
+  throwing.
+- Add component ports: override `ports()` to declare named connection points from
+  props and the saved size, in local coordinates with an optional side. The frozen,
+  validated `portDefinitions` getter is computed again only when saved props change,
+  and core exports the structural `PortDefinition` type that connectors read.
+- Add `actionDefinitions` to components: their `@action` methods with undo labels.
+- Add `resize: 'props'` components and edit rules: the size is saved as built-in
+  `width` and `height` props that `render()` reads through `width()` and `height()`,
+  `size()` changes them as one undo step and redraws at once, and the transformer
+  resizes such a component through `size()` instead of scaling it.
+- Add the `notation: 'si'` prop option, so editors accept and show engineering
+  notation such as `4.7k`, `4k7` or `4.7 kΩ`.
+- Render `@state` changes for every component in one shared frame per drawing, as one
+  temporary change. History now restores a component's props, position and existence
+  but not its rendered children; after undo, redo or a cancelled group the component
+  redraws them from restored props and current live state. Live renders that add or
+  remove nodes no longer make undo fail, recreated instances start from state
+  defaults, and the conflict exception for live-painted holes is removed.
+- Preserve restored props and redo when `created()` writes defaults; the hook still
+  runs on every copy. Isolate internal edits from application `edit()` methods,
+  validate raw props JSON before mutation, and rebuild saved views with extra attrs.
+- Share component change routing per drawing, discover only added subtrees, and cache
+  sibling order between structural edits so moves do not scale with drawing size.
+- Rename the type registry to `ComponentTypes` and infer `create()` option names and
+  value types from public primitive fields. Record delegated 34 KiB catalog, 41 KiB
+  components and 20.5 KiB root gzip caps, with a reproducible component benchmark.
+- Add the opt-in `@rasamjs/core/components` entry: class components, `@component`,
+  `@prop`, `@state`, `@action`, per-drawing type registries, metadata and icons.
+  Preserve classes and props through migration, native adoption, import, clone,
+  clipboard and replay; bind saved children before subsequent updates. Batch live
+  state per frame as temporary changes and reject inherited-member field collisions.
+
+- Compare template bindings with current model values so rendering after undo or
+  cancellation restores attributes and text without replacing element nodes.
+- Add element variants: a class with `static variant` registers for one `data-*`
+  attribute value of its tag, next to the tag's base class. Creation, adoption, import,
+  clone and change replay resolve it, and the identifying value is fixed and reserved.
+  The registry adds `resolve(element)`, `registered(Constructor)` and `variant()`.
+- Templates render nested templates in holes between elements or at the top level:
+  a template, an iterable of templates, or `null`/`undefined`/booleans/`''` for
+  nothing. Items whose literal matches by index update in place; updates validate and
+  build new items off the drawing before changing it. Replacing a template, or removing
+  nested items, now disposes them semantically, so undo restores them and no longer
+  clears history.
+- Add the structural `EditRules` type that editing tools read from `node.editRules`
+  to limit rotation, resizing and flips per node.
+- Add `static ownsChildren` for containers whose class owns its children. Outside
+  structural edits throw before allocating or moving anything; the class edits them
+  through `withOwnChildren()`, and core's adoption, replay and owner destruction pass.
+
+## [0.2.0] - 2026-11-06
+
+- Add `document: 'presentation'` imports to retain scoped root styles and compositing
+  while omitting the viewport envelope. Validate document envelopes before unwrapping.
+  Add `document: 'replace'` for empty drawings so full-document restoration does not
+  apply configured root presentation twice; fragments retain their defaults.
+- Isolate the text-policy cloning bridge so interchange bundles do not retain the
+  rich-text implementation; keep the existing interchange size budget.
+
+- Preserve omitted ancestor transforms and nested SVG viewports in content-framed
+  subtree exports, including raster exports of nested shapes.
+
+- Keep matrix and transform-snapshot reads outside model edit transactions.
+  Release destroyed native image sources and avoid restarting a missing-source
+  request when disposing a completed image metadata probe.
+
+- Add opt-in `deriveChanges()` to include synchronous dependent writes in the same
+  operation/group before recording, skipping getters and restoration. Recognize reserved
+  connector endpoint references during SVG export/import and clone ID remapping.
+
+- Restore exported embedded image data URLs on `<image>` elements during SVG import.
+  Data URLs on links and Use instances, unsupported MIME types and active URL schemes
+  remain rejected.
+
+- Add optional `./raster` PNG/JPEG/WebP export with scale, background, content/viewBox
+  framing, same-origin/data image embedding, snapshot isolation and clear decode or
+  tainted-canvas failures. Document nonembedded web fonts/styles and pixel limits.
+- Add an isolated 12 KiB raster budget; existing entry budgets are unchanged.
+
+- Add labelled change groups and `ChangeGroup.cancel()`, including rollback without
+  history, restored completion signals, conflict detection and observer-error reporting.
+- Add content-framed SVG export with padding and whole-document import with `SyntaxError`
+  parse diagnostics. Document import accepts an XML declaration and a DOCTYPE without an
+  internal subset. Default export and nested SVG import behavior remain compatible.
+
+- Add editor Phase 0 test-only group rollback spikes for text creation, attribute edits,
+  observer notifications and preservation of unrelated edits.
+
+## [0.1.2] - 2026-11-02
 
 ### Fixed
 

package/COMPONENTS.md

@@ -0,0 +1,229 @@
+# Class components
+
+Import the opt-in `@rasamjs/core/components` entry. Components are trusted application
+classes extending `Component`, which is a closed `Group`. Position, rotation and scale
+belong to that group; transforming it never calls `render()`.
+
+```ts
+import { SVG, svg } from '@rasamjs/core';
+import {
+  Component,
+  ComponentTypes,
+  component,
+  prop,
+  state,
+  action,
+} from '@rasamjs/core/components';
+
+@component({ type: 'status', name: 'Status', category: 'Indicators', version: 1 })
+class Status extends Component {
+  @prop({ label: 'Caption' }) caption = 'Ready';
+  @prop() active = false;
+  @state() brightness = 1;
+
+  @action('Toggle status')
+  toggle() {
+    this.active = !this.active;
+  }
+
+  override render() {
+    return svg`<circle r="15" fill="${this.active ? 'lime' : 'gray'}" opacity="${this.brightness}"/><text y="35">${this.caption}</text>`;
+  }
+}
+
+const drawing = SVG(document.querySelector<HTMLElement>('#canvas')!, { elements: [Status] });
+const types = new ComponentTypes(drawing, [Status]);
+const status = drawing.create(Status, { caption: 'Connected' });
+status.translate(100, 80);
+status.toggle();
+```
+
+Use standard TypeScript decorators with `useDefineForClassFields` (the default for
+ES2022). Do not enable legacy `experimentalDecorators`. The playground's Vite transform
+handles these decorators. Each concrete type needs its own `@component` decorator.
+Application classes declare no static fields: the decorator supplies core's variant
+registration, and the base class supplies owned-child behavior.
+
+`@prop()` supports strings, finite numbers, booleans and null. Defaults come from field
+initializers. Its options are `label`, `unit`, `min`, `max`, `step`, `options`,
+`type: 'color'` and `notation: 'si'` for property-panel metadata. With `notation: 'si'`,
+editors accept `4.7k`, `4k7` or `100n` and show values as `4.7 kΩ`. Numeric limits and choice lists are checked
+on construction, loading and assignment. Unknown props and fields colliding with
+rasam's inherited members are rejected. Use names such as `active` and `renderedFill`:
+`on` and `fill` already name rasam methods. `propDefinitions` exposes frozen metadata.
+The same validation applies to direct `data-rasam-props` writes, before any model
+or rendered value changes.
+
+`create(Type, options)` infers field names and value types from the concrete class,
+so misspelled keys and wrong value types are TypeScript errors. Standard decorators
+cannot distinguish `@prop` from state, helpers or getters in TypeScript's type system:
+the inferred `ComponentFields<Type>` includes public primitive values. Runtime
+validation still rejects every creation option that is not a decorated prop.
+
+Every changed prop creates one labelled edit. Rendering runs synchronously as a
+derived change in that edit, updating existing template holes. An enclosing core
+change group or `@action('Label')` groups several writes into one undo step. Actions
+must be synchronous. Failed actions roll back saved props and rendered children;
+live state remains outside history. `actionDefinitions` lists an instance's `@action`
+methods as frozen `{ name, label }` entries, inherited ones first; an overriding
+`@action` keeps its place and takes the new label. Editors use it for action buttons. Plain helper fields do not trigger rendering.
+
+`@state()` keeps values in memory. Assignments coalesce into one shared animation
+frame per drawing: every changed instance renders once, together, as one temporary
+`components` change, so a thousand animated instances cost one change event per frame.
+They never create undo steps or dirty the editor's document autosave. Live state may
+change structure too, for example a glow drawn only while `on` is true, or a row of
+pins whose length is a state value.
+
+If one instance's render throws, the others still render and the error surfaces from
+that frame. `resetState()` restores the instance's
+initial state; `types.resetState()` resets its drawing. Object state defaults must be
+structured-cloneable; nested mutations do not trigger a render, so assign a new value.
+
+Subclasses inherit decorated fields, ordinary methods and edit rules, and can add
+fields or override `render()`. Redeclaring an inherited decorated field is rejected.
+`created()` runs synchronously after initialization for every instance, including
+load, clone, paste and history reconstruction. It may initialize props for a brand-new
+instance. On restored instances (`this.adopting`), prop assignments in this hook are
+ignored, including raw props-attribute writes, so saved values and redo remain intact.
+Use the hook for per-instance state and subscriptions; use `migrate` to update saved
+props. `destroyed()` runs on disposal and `changed(name)` for decorated-field changes,
+including replayed prop changes.
+
+Rendered children are derived from props and live state. History restores a
+component's props, position and existence, never its children: right after undo,
+redo or a cancelled group, each restored or recreated component redraws, as one
+temporary change, from its restored props and its current live state. A recreated
+instance starts from its state defaults. So live renders that add or remove nodes
+never break undo, and an outside write to a rendered child lasts only until the next
+render.
+
+`@component` takes a stable lowercase hyphenated `type`, a display `name`, optional
+`category` (default `General`), `version` (default 1), and editing rules. `rotate` is
+`'free'`, `false`, or a positive degree step dividing 360; `flip` defaults to true;
+`resize` defaults to `'scale'` and can be false or `'props'`. The read-only `editRules`
+getter lets the existing transformer and flip commands enforce them without importing
+this entry.
+
+With `resize: 'props'`, a resize changes the component's size instead of scaling it,
+so strokes and text keep their size. The size is saved as built-in `width` and `height`
+props, with defaults from `@component({ resize: 'props', width, height })` (100 when
+left out). Read them in `render()` with `this.width()` and `this.height()`; set them
+with `size(width, height)`, `width(value)`, `height(value)` or `create(Type, { width })`.
+Each change is one undo step and redraws at once. Sizes are at least 1 user unit. The
+transformer resizes such a component through `size()` when it is selected alone; a
+multi-selection that contains one cannot resize. Draw the component inside the box
+from (0, 0) to its width and height, so resize handles follow the pointer exactly.
+
+```ts
+@component({ type: 'panel', name: 'Panel', resize: 'props', width: 150, height: 90 })
+class Panel extends Component {
+  @prop() title = 'Notes';
+  override render() {
+    return svg`<g><rect width="${this.width()}" height="${this.height()}" fill="white" stroke="black"/><text x="10" y="17">${this.title}</text></g>`;
+  }
+}
+```
+
+Multi-selections use the strictest permissions and the smallest rotation step shared
+by all members. The editor's geometry properties follow the same rules. Application
+commands can use `combineEditRules` from `@rasamjs/transformer` before making edits;
+core setters remain available for programmatic transforms.
+
+Outside structural child edits throw before allocating or moving anything. Components
+can themselves be moved, removed, cloned and edited as normal nodes. Compose
+`!isComponentChild(node)` with a selection filter to prevent drilling into their
+rendered children. The editor playground demonstrates that composition.
+`@rasamjs/editor/components` adds editor registration, palette placement tools and a
+properties service built from `@prop` metadata.
+
+## Ports
+
+Ports are named points where links attach, such as the two ends of a resistor or the
+pins of a chip. Override `ports()` to declare them. Like `render()`, it reads `this`:
+use props and, with `resize: 'props'`, the saved size. Points are in the component's
+local coordinates at 0°, so moves, rotations and flips carry them along. The optional
+`side` (`'left'`, `'right'`, `'top'` or `'bottom'`) is the direction a link leaves in.
+
+```ts
+@component({ type: 'chip', name: 'Chip' })
+class Chip extends Component {
+  @prop({ min: 2, max: 16, step: 2 }) pins = 4;
+
+  override ports(): PortDefinition[] {
+    const half = this.pins / 2;
+    return Array.from({ length: this.pins }, (_, index) => ({
+      name: `p${index + 1}`,
+      x: index < half ? 0 : 60,
+      y: 10 + (index % half) * 20,
+      side: index < half ? 'left' : 'right',
+    }));
+  }
+
+  override render() {
+    return svg`<rect width="60" height="${(this.pins / 2) * 20}"/>`;
+  }
+}
+```
+
+`portDefinitions` returns them validated and frozen. It calls `ports()` again only when
+the saved props change, including after undo, redo or a raw props write. Names must be
+unique, non-empty strings, `x` and `y` finite numbers, and `side` one of the four
+names; anything else throws a clear error. Live state never moves a port: reading a
+`@state` field inside `ports()` throws. Subclasses inherit ports and can extend them
+with `super.ports()`. Components have no ports by default. `PortDefinition` comes from
+`@rasamjs/core`, so other packages can read `node.portDefinitions` without importing
+this entry, the way tools read `editRules`. `@rasamjs/connectors` attaches link ends
+to them with `{ target, port }`.
+
+## Save, load and migrate
+
+Saved SVG contains the rendered children and three attributes on the component group:
+
+```xml
+<g data-rasam-component="status" data-rasam-version="1"
+   data-rasam-props='{"caption":"Connected","active":false}'>…</g>
+```
+
+Register constructors through `SVG(..., { elements: [Status] })` before loading, or
+`new ComponentTypes(drawing, [Status])` before import. Core's `parent.create()` also
+registers the constructor for that drawing. Loads, clones, clipboard operations and
+history retain the class. Reconstruction finishes after references and model features
+are copied; the engine then binds matching saved wrappers or replaces the saved tree
+when the template structure changed. Later rendering never appends a second copy.
+Saved hosts or descendants with attributes absent from the template are rebuilt,
+including unmanaged native attributes, so loading cannot retain stale styling.
+
+For a new saved version, provide `migrate(props, oldVersion)` returning props for the
+current version. It is called once on older saved input. Missing props use current
+field defaults. Future versions, missing migrations for old versions, malformed JSON
+and invalid props throw. Migration code should be synchronous and free of external
+side effects. Unknown types remain plain groups with their saved appearance; a
+`ComponentTypes` service reports each unknown type once through `console.warn`.
+
+State fields are absent from saved props. Explicit SVG export includes their current
+appearance, so passive viewers see the current drawing. Loading recomputes the look
+from saved props and fresh state defaults.
+
+## Type registry and icons
+
+`ComponentTypes.register(Type)` registers another type locally. `list(category?)` returns
+sorted frozen definitions; `get(type)` returns the constructor. `icon(type, parent)`
+renders a default instance through the same class into a supplied drawing or group.
+Use a separate small drawing for palette icons. `destroy()` stops the service's
+observer; drawing disposal also cleans it up.
+
+The engine shares one change observer and one derivation callback per drawing.
+Dispatch targets changed components, and type discovery visits only newly added
+subtrees or a node whose type attribute changed. Movement does not scan the drawing.
+
+The Phase 1 demos use primitive template bindings. Core's separately developed
+template-power work controls nested templates and arrays; component definitions
+do not require those features. Filters, embedded HTML and component nesting are not
+part of this phase.
+
+Validate the entry with `bun run check:size:components` (42 KiB gzip cap).
+`bun run api:check`, `bun run check:consumer`
+and `bun run check:docs` also cover the new public entry.
+Use `bun run bench:components` for the 2,000-object/200-move benchmark, or
+`bun run bench:components --revision=07a1160` to reproduce the reviewed version.