@rasamjs/core 0.0.0-stage → 0.1.1

package/API.md

@@ -0,0 +1,169 @@
+# 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`.
+
+Only documented operations are supported application APIs. Deep imports, mutable
+service bookkeeping, TypeScript-private methods and undocumented symbol hooks remain internal,
+even when JavaScript can reach them. Prototype reachability is recorded separately
+in `reports/public-api-contract.json` for review; it is not a support commitment.
+
+## @rasamjs/core
+
+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):
+
+`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`.
+
+## @rasamjs/core/advanced
+
+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):
+
+`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`.
+
+## @rasamjs/core/animation
+
+Runtime exports (3):
+
+`ManualClock`, `animate`, `timeline`.
+
+Type-only exports (11):
+
+`AnimatedValue`, `AnimationClock`, `AnimationRunner`, `AnimationTarget`, `Easing`, `MotionPreference`, `RunnerOptions`, `RunnerOutcome`, `RunnerState`, `Timeline`, `TimelineOptions`.
+
+## @rasamjs/core/catalog
+
+Runtime exports (21):
+
+`Description`, `ForeignObject`, `GenericContainer`, `GenericElement`, `HTML_NAMESPACE`, `Metadata`, `SVG_NAMESPACE`, `SvgFragment`, `SvgStyle`, `Title`, `XLINK_NAMESPACE`, `XML_NAMESPACE`, `catalogElements`, `defineElement`, `description`, `foreignObject`, `fragment`, `metadata`, `registerCatalog`, `stylesheet`, `title`.
+
+Type-only exports (7):
+
+`CssDeclarations`, `DescriptiveOptions`, `ElementDefinition`, `ForeignObjectOptions`, `GenericAttributes`, `HtmlElementOptions`, `StylesheetOptions`.
+
+## @rasamjs/core/changes
+
+Runtime exports (14):
+
+`ChangeConflictError`, `ChangeObserverError`, `ChangeRollbackError`, `beginChangeGroup`, `captureModelState`, `changeKey`, `claimRecorder`, `combineChanges`, `observeChanges`, `restoreChanges`, `restoreModelState`, `sameState`, `validateModelState`, `withChanges`.
+
+Type-only exports (13):
+
+`ChangeBatch`, `ChangeEvent`, `ChangeGroup`, `ChangeMetadata`, `ContentState`, `ModelChange`, `ModelFeatures`, `ModelSnapshot`, `NativeNodeState`, `NodeHandle`, `Placement`, `PropertyState`, `TextPolicies`.
+
+## @rasamjs/core/data
+
+Runtime exports (5):
+
+`data`, `forget`, `memory`, `remember`, `round`.
+
+Type-only exports (0):
+
+.
+
+## @rasamjs/core/events
+
+Runtime exports (6):
+
+`dispatch`, `dispatchCustom`, `focusable`, `onCustom`, `onDom`, `onMany`.
+
+Type-only exports (5):
+
+`DomEventType`, `DomListener`, `DomListenerOptions`, `DrawingDomEvent`, `FocusOptions`.
+
+## @rasamjs/core/interchange
+
+Runtime exports (3):
+
+`cloneNode`, `exportSvg`, `importSvg`.
+
+Type-only exports (3):
+
+`CloneOptions`, `ExportOptions`, `ImportOptions`.
+
+## @rasamjs/core/masks
+
+Runtime exports (7):
+
+`Mask`, `mask`, `maskElements`, `maskWith`, `masker`, `registerMasks`, `unmask`.
+
+Type-only exports (1):
+
+`MaskOptions`.
+
+## @rasamjs/core/media
+
+Runtime exports (11):
+
+`Link`, `SvgImage`, `SvgSymbol`, `image`, `link`, `linkTo`, `linker`, `mediaElements`, `registerMedia`, `symbol`, `unlink`.
+
+Type-only exports (8):
+
+`ImageLoadCallbacks`, `ImageLoadError`, `ImageLoadResult`, `ImageLoadingState`, `ImageOptions`, `IntrinsicSize`, `LinkOptions`, `SymbolOptions`.
+
+## @rasamjs/core/patterns
+
+Runtime exports (4):
+
+`Pattern`, `pattern`, `patternElements`, `registerPatterns`.
+
+Type-only exports (1):
+
+`PatternOptions`.
+
+## @rasamjs/core/query
+
+Runtime exports (4):
+
+`matches`, `query`, `queryFirst`, `queryNative`.
+
+Type-only exports (1):
+
+`NodePredicate`.
+
+## @rasamjs/core/resources
+
+Runtime exports (4):
+
+`classifyReference`, `consumers`, `resolveReference`, `unbindConsumers`.
+
+Type-only exports (1):
+
+`LocalReference`.
+
+## @rasamjs/core/text
+
+Runtime exports (5):
+
+`TextPath`, `Tspan`, `registerText`, `textElements`, `textOnPath`.
+
+Type-only exports (7):
+
+`FontOptions`, `TextContentPart`, `TextOnPathOptions`, `TextPathAttributes`, `TextPathOptions`, `TextRunMeasurementProvider`, `TspanOptions`.
+
+## @rasamjs/core/tree
+
+Runtime exports (25):
+
+`after`, `ancestors`, `back`, `backward`, `before`, `clear`, `detachChildren`, `first`, `flatten`, `forward`, `front`, `index`, `insertAfter`, `insertBefore`, `last`, `next`, `previous`, `reparentTo`, `reparentToRoot`, `replace`, `rootNode`, `siblings`, `ungroup`, `unwrap`, `wrap`.
+
+Type-only exports (0):
+
+.
+
+## @rasamjs/core/viewport
+
+Runtime exports (7):
+
+`ViewportError`, `boundsIn`, `clientBounds`, `isRoot`, `nested`, `viewbox`, `zoom`.
+
+Type-only exports (2):
+
+`NestedSvgOptions`, `ViewBoxInput`.

package/CHANGELOG.md

@@ -0,0 +1,196 @@
+# Changelog
+
+## [0.1.1] (unreleased)
+
+### Fixed
+
+- Reading `width()` or `height()` no longer opens a change run. With change listeners
+  attached (for example a transformer, selection or history), each read used to capture
+  the node's sibling order, so measuring n fresh siblings was O(n²). The first snapping
+  drag over 1,000 shapes drops from 0.4–0.8 s to under 50 ms. Writes are still recorded.
+
+## [0.1.0] - 2026-10-29
+
+Initial release, coordinated with `@rasamjs/history` and `@rasamjs/transformer`.
+
+### Fixed
+
+- Change observation preserves a sole `ChangeConflictError` for rejected writes.
+  Failed restoration recovery throws a typed `ChangeRollbackError`.
+
+- `rotate()` and `scale()` pivot on the center of the current geometry bounds until
+  `origin()` is called, so shapes placed by x/y, `translate`, `move` or a parent group
+  turn and scale identically. Previously the implicit origin was local `(0, 0)`.
+  After a resize or other geometry edit, the next `rotate()` or `scale()` keeps the
+  shape in place; position absorbs the pivot move instead of the shape jumping.
+
+- Independent position, rotation, scale, width and height animations can run
+  together. Manual seek/finish commits before completion callbacks, singular matrix
+  morphs retain shear, and negative size endpoints fail before scheduling.
+- Root zoom uses CSS viewport dimensions, including percentage sizing, while
+  excluding ancestor transforms from the reported level.
+- Numerical rounding preserves URLs, paint, identifiers and application values,
+  including explicitly selected attributes.
+
+- Opening `playground/index.html` directly now loads a standalone browser script
+  generated by `npm run build`. The Vite route retains live TypeScript loading,
+  and startup failures display instructions instead of an empty drawing area.
+
+### Added
+
+- Drawing-wide semantic model changes through `@rasamjs/core/changes`, normalized local
+  `attributechange` events, neutral interaction groups, and validated state
+  restoration/reconstruction for the optional `@rasamjs/history` package.
+
+- Transformer core APIs: `Matrix.decompose()` and `PathArray.transform()`;
+  side-effect-free `rotation()`, `scale()` and `origin()` getters; public
+  `geometryMatrix()`; immutable, JSON-compatible `transformState()` save/restore
+  including editable geometry; and shape-specific `bakeSizing()`.
+- Affine path transforms retain elliptical arcs through principal-axis recovery,
+  reverse sweep under reflection and turn degenerate arcs into lines. Baking
+  preserves geometric placement; unsupported shape sizing remains a transform.
+- Animation reads exact component values without setter probes, including
+  negative scales, multiple turns and collapsed sizing.
+
+- Opt-in `@rasamjs/core/data`: `data()` stores values in `data-*` attributes, `remember()`,
+  `memory()` and `forget()` keep per-node values in memory until destruction, and
+  `round()` rounds unitless numeric attributes. This closes the last two omitted
+  comparison actions without adding shared methods.
+
+- P13 acceptance tooling: a complete migration guide, generated runtime/type export
+  and prototype inventory, source-consistent release checks, documentation/evidence
+  link validation, every-subpath packed imports, debugger source inclusion and
+  serial creation/adoption/interchange/update/animation measurements. A combined
+  scene exercises resources, rich text, interactions, motion and a passive round trip.
+  `private: true` remains the publication guard; no publish operation is automated.
+
+- P11 opt-in `@rasamjs/core/query` and `@rasamjs/core/interchange`: frozen managed/native query
+  snapshots, typed predicates and matches; logical-state clones with fresh IDs,
+  internal reference remapping, shared or copied external resources, independent
+  sizing and multiline policies; referenced-defs XML export and staged passive SVG
+  import with namespace/schema/URL checks and rollback. Includes round-trip examples,
+  declarations, three-engine tests and separate 5/16 KiB bundle budgets.
+
+- P12 opt-in `@rasamjs/core/animation`: root-owned timelines, runners with duration,
+  delay, CSS easing, loops, yoyo, `after` sequencing, pause/play/seek/reverse/finish/
+  cancel and settled outcomes, an injectable clock with `ManualClock`, and
+  reduced-motion handling that follows the system preference. Values interpolate for
+  matching units, number lists, hex/rgb colours, component and decomposed matrix
+  transforms, sizes, equal-length points and same-topology paths; other values are
+  rejected before scheduling. The latest runner takes over shared channels, direct
+  writes interrupt them, and destruction cancels. Frames write through existing
+  setters and commit once. No core code changes; the entry point has a 12 KiB budget.
+
+- P10 opt-in `@rasamjs/core/catalog`: descriptive content and stylesheet factories,
+  explicit generic schemas/capabilities, namespaced attribute bindings,
+  ForeignObject native DOM boundaries and reusable detached fragments. Adoption
+  preserves unmanaged metadata and opaque native content; forest insertion
+  prevalidates ownership and rolls back native failures. Includes a runnable
+  catalog example, declarations, namespace tests and three-engine browser coverage.
+
+- P9 opt-in `@rasamjs/core/masks` and `@rasamjs/core/patterns`: defs-owned Mask and Pattern
+  resources with validated units, regions, `mask-type`, tiles, viewBox and
+  `patternTransform`; `maskWith`/`unmask`/`masker` with self and ancestor masking
+  rejected; pattern paint through `fill()`/`stroke()`; atomic content updates;
+  per-drawing registration for adoption and templates. Masks and patterns never
+  change geometric bounds. Core gains the `mask` attribute (about 25 bytes gzip).
+  Includes three-engine pixel tests and a runnable example.
+
+- P8 `@rasamjs/core/text` constructors/registration for Tspan and TextPath, ordered managed
+  text runs, explicit rich builds and plain replacement, font/line helpers, native
+  glyph advance measurement and typed path-label creation. Adoption and static
+  primitive templates retain mixed order and native text/span identity. Local-font
+  browser tests and an interactive text example cover layout and reference lifetime.
+
+- P7 opt-in `@rasamjs/core/media`: Image, Symbol and Link constructors, typed factories,
+  per-drawing catalogs for adoption/templates, image metadata callbacks with stale
+  request suppression and teardown cleanup, intrinsic sizing, reference-protected
+  symbol instances and link/unlink operations. Use dimensions map symbol/nested SVG
+  viewports while ordinary target sizing remains geometric. Includes local image
+  fixtures, three-engine browser coverage and a runnable media example.
+
+- P5 nested viewport geometry: x/y, viewBox and every `preserveAspectRatio`
+  alignment of nested `<svg>` elements map into root-space bounds, conversions, hit
+  tests, `Use` references and tree moves. Unresolved viewports report `unavailable`
+  bounds, and `worldMatrix()`/`toRoot()` throw `ViewportError`. Opt-in
+  `@rasamjs/core/viewport` adds `viewbox()`, focal `zoom()`, `nested()`, `isRoot()`,
+  `boundsIn()` and `clientBounds()`, with a runnable viewport example. Root drawings
+  register `Svg`, so nested `<svg>` markup is adoptable. The selective budget rose from 15 KiB to 16 KiB gzip, and the catalog budget from 24 KiB to 25 KiB, for the core mapping. After the final review fixes, the selective budget rose again to 20 KiB.
+
+- P4 opt-in `@rasamjs/core/events`: typed native/custom events, shared bubbling delegation,
+  direct capture/passive/non-bubbling listeners, once, AbortSignal, multiple-event
+  registration, dispatch/cancellation and lifecycle cleanup. Opt-in `focusable()`
+  configures keyboard focus; existing pointer `on()` contracts are preserved.
+
+- P6 resource APIs: stable `getDefs()` shared with mounting, gradient paint matrices
+  and endpoints, staged stop replacement, child-returning `createStop()`, partial
+  stop updates, marker helpers and validated clip/marker content replacement.
+  Opt-in `@rasamjs/core/resources` provides typed consumer queries/unbinding, explicit raw
+  local lookup and reference classification, with a runnable resource example.
+
+- Opt-in `@rasamjs/core/tree` traversal, ordering, reference-safe clear/detach, replacement,
+  wrapping, affine reparenting, ungrouping and flattening. Shared indexed `add()`
+  preserves managed/native order and connected pointer capture; moves across nested
+  viewports preserve root geometry since P5. Static drawing bundles exclude tree helpers.
+
+- P0–P2 SVG.js capability milestone: regenerable comparison probes and action
+  coverage, documented contracts, typed attribute snapshots, class/visibility and
+  style conveniences, atomic size/radius helpers, parent-space bounds placement,
+  explicit affine composition, immutable point/path values, plot editing and
+  adapter-backed native path length/point reads. Later roadmap phases remain deferred.
+
+- Typed SVG creation and adoption through `SVG()`, concrete element classes, and
+  per-drawing registration, with no runtime dependencies or DOM access on import.
+- Shapes, text, groups, gradients, markers, clip paths, and typed local references.
+- Fluent geometry, paint, sizing, affine transforms, coordinate conversion, and
+  geometric bounds with explicit empty and unavailable results.
+- Frame-coalesced writes, synchronous batches and flushes, reusable detachment,
+  permanent destruction, and reference-aware resource ownership.
+- Static SVG templates with primitive bindings and stable node identity on updates.
+- Delegated pointer events, pointer capture, a rectangle example, and an interactive
+  LED playground.
+- Main and advanced ESM entry points with declarations; unit, three-engine browser,
+  packed-consumer, size, and benchmark checks.
+- MIT license and documented public API review, limitations, and release status.
+
+### Changed
+
+- Native text/span wrapper inference returns `SvgText | Tspan`, reflecting their
+  structurally identical DOM interfaces; factory returns remain concrete. Narrow
+  native results with `instanceof`. The P8 catalog budget is 28 KiB gzip (was 25),
+  with a separate 12 KiB text budget and unchanged 16 KiB selective budget.
+
+- Renamed the internal class decorator from `@attributes` to `@attrs` and its module
+  to `src/decorators/attrs.ts`. The public field decorator remains `@attr`.
+- `TemplateInstance` is now a type-only export; create instances with
+  `Renderer.render()`. `@rasamjs/core/advanced` re-exports the main entry point instead of
+  repeating its export list.
+- Selected `@rasamjs/core` and candidate version `0.1.0`. npm returned 404 for the name on
+  2026-10-25; availability must be checked again before publication.
+
+### Fixed
+
+- P6 resource disposal rejects new references and reattachment to any selected old
+  descendant during cleanup callbacks. Raw lookup skips targets pending disposal.
+- Resource URLs and typed hrefs encode authored IDs; raw lookup decodes fragments
+  once and rejects malformed encodings, CSS escapes and control characters.
+- Failed reference validation leaves target IDs unchanged; unsupported resource
+  owners and rejecting defs hosts leave no staged wrappers. Undefined marker
+  options retain creation defaults. Existing drawing teardown/listener behavior is preserved.
+
+### Performance snapshot — 2026-10-25
+
+| Check                                                     | Measured                                             | Budget                     |
+| --------------------------------------------------------- | ---------------------------------------------------- | -------------------------- |
+| Selective root + rectangle bundle                         | 43,258 bytes minified; 13,257 bytes gzip (12.95 KiB) | 15,360 bytes gzip (15 KiB) |
+| 1,000 existing circles, changed fill + synchronous commit | 0.50 ms median; 1.10 ms p95                          | Median below 16 ms         |
+
+Bundle fixture: `fixtures/size.ts`; unrelated shapes and templates are excluded.
+Fill fixture: `scripts/benchmark.mjs`, 20 warmups followed by 100 measured batches;
+includes logical updates and DOM commits, excludes paint.
+
+Reference environment: Windows 10.0.26200, Intel Core i7-10610U at 1.80 GHz,
+8 logical CPUs, Node v24.21.0, Chromium 156.0.8078.4.
+Raw samples and bundle composition are in `reports/benchmark.json` and
+`reports/size.json`. These are operation timings on the recorded machine, not
+end-to-end frame rates.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rasam contributors
+
+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.