stickyflow 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,157 @@
+# Changelog
+
+All notable changes to this package are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+**While the version is below `1.0.0`, the minor slot carries breaking changes** —
+`0.1.x` → `0.2.0` may break the API. Pin an exact version if that matters to you.
+
+Two things count as breaking here that are easy to overlook:
+
+- **A change in rendered SVG output.** The golden suite (`test/__golden__/`) exists
+  precisely to make those visible; regenerating a golden is never a silent act.
+- **A bump of `DOM_CONTRACT_VERSION`.** Renderer and viewer negotiate on it, so a
+  mismatch makes `createViewer()` refuse to mount.
+
+## [Unreleased]
+
+## [0.2.0] - 2026-10-15
+
+### Added
+
+- **Data binding.** A document can declare `DataSource` blocks with typed fields
+  and bind properties to them with `key: <- expression`. The runtime
+  (`createBindingRuntime`, `renderBound`, `createDataSource`) validates the
+  bindings against the declared types, re-renders only what changed, and reports
+  problems as diagnostics. Expressions support arithmetic, comparisons,
+  `&&` / `||`, boolean literals and number functions such as `moveToward`.
+- **Events and handlers.** `onPress`, `onRelease`, `onTap` and `onDrag` on
+  Shapes, Texts and Widgets, and `onTick` on a record `DataSource`, write to
+  data sources (`onTap: counter.value <- counter.value + 1`). Element state is
+  readable in expressions as `id.pressed`, `id.hovered` and `id.pointer`.
+  `connectInteraction(viewer, runtime)` from `stickyflow/viewer` wires pointer
+  input to the runtime; `viewer.setPaused()` freezes shader time and ticks.
+- **Shaders and widgets.** A `Shader` block with parameters that can be bound to
+  data, new built-in shaders (`plasmaGauge`, `tickScale`, `button`,
+  `chromaticGlassPlate`, orb and halo effects), `shaderProgram` and
+  `SHADER_DEFAULTS` as exports, a native `RollingNumber` widget, a `tickScale`
+  widget with numbers and a `ruler` widget with a bending wire and a knob.
+- **Text block** with wider font weights and letter spacing, and editable
+  `Shader` blocks.
+- **Line charts:** `lineWidth`, `lineGlow`, `pointSize`, `pointFill`,
+  `pointStrokeWidth`, per-series `dash` and `strokeWidth`, gradient strokes,
+  and `highlightPoints` with a guide and a label.
+- **Pie charts:** `pieStartAngle`, `pieSweep`, `pieExplode` (and a per-series
+  `offset`), `pieGlow`, `pieStroke`, `pieStrokeWidth`, `pieLabelPosition`,
+  `pieLabelContent`, `pieLabelColor` and `pieCenterText`.
+- **Bar charts:** horizontal bars, segmented bars with gap and snap, tracks with
+  hatching, photo backgrounds with frosted glass, per-bar gradients, glow, value
+  labels, axis lines and ticks.
+- Change-highlighting: `viewer.update()` takes an opt-in `highlightChanges` flag
+  that briefly flashes the shapes an update added or changed, plus a `sceneDiff`
+  event (always emitted) with added, removed and changed owner ids.
+  `highlightChanges` also accepts `{ color }`.
+- Bending orthogonal links with segment handles, editable frame titles, move and
+  resize of widgets, an isometric snap grid for move and axis resize.
+- Circular `radial` charts and configurable polar `areaOpacity`.
+- Tier layering, viewer encapsulation and the headless guarantee are enforced by
+  `test/boundary.test.ts`. A jsdom-based test project (`npm run test:dom`) covers
+  the DOM-bound interaction tier.
+
+### Changed
+
+- **Breaking (terminology).** Runtime and interaction APIs use the canvas-object
+  vocabulary: `entityClick` is `canvasObjectClick`, and the pure patch helpers
+  are `insertCanvasObject` / `removeCanvasObject`. Diagnostic ownership is
+  exposed as `ownerId` instead of `entityId`. The legacy SFL `Entity` block and
+  the version-1 `data-sf-role="entity"` value remain supported.
+- **Breaking (isometric objects).** One `fill` replaces `topFill`, `frontFill`
+  and `sideFill`; the shaded sides are derived from it.
+- **Breaking (internal module layout).** `rendering/renderScene` is split into
+  `rendering/scene`, `rendering/renderInput` and `rendering/domContractVersion`.
+  Only deep imports into `dist/rendering/renderScene` are affected.
+- **Breaking (`Token`).** Lexer tokens carry required `endLine` and `endCol`.
+- DOM-contract access moved into its own `domContract` tier, used by both the
+  viewer and the interaction tier. `stickyflow/interaction` uses only the public
+  `stickyflow/viewer` API.
+- A pie label drag writes `labelOffsetX` and `labelOffsetY` instead of a
+  `labelPulled` flag.
+- The legend is off by default; `showLegend: true` turns it on.
+- The package contains no comments in its sources, and the largest functions are
+  split into small ones. Rendered output is byte-identical.
+
+### Fixed
+
+- `stickyflow/web-component` can be imported where there is no DOM (SSR). It no
+  longer throws at import time, and `defineStickyflowDiagram()` does nothing
+  without `customElements`.
+- A property change on a chart no longer lands in a nested block that happens
+  to share the key (for example the `text` of a `Rule`).
+- A pie label can be pulled out of the ring again; its offset was clamped to zero.
+- Pie and polar-area labels on black or gray slices stay readable.
+- A glow on a small element is no longer cut to a box by the filter region.
+- SFL patching no longer corrupts documents containing `"""` multiline strings.
+  Block and property positions come from the real lexer, so there is a single
+  SFL grammar.
+- Property values that span multiple lines are replaced as a whole.
+- A throwing host event handler no longer prevents the remaining handlers from
+  running; the error is rethrown asynchronously.
+- A press that the document handles no longer selects the element afterwards.
+- Widget digits follow a changed value on update; shader surfaces render at the
+  size shown on screen, so zoomed widgets stay sharp.
+
+## [0.1.0] - 2026-07-26
+
+First versioned release. Not yet published to npm.
+
+### Added
+
+- **`stickyflow`** — the static tier. `render()` / `renderCanvas()` turn SFL text
+  into a self-contained SVG string with no DOM involved, so it runs in Node, in
+  SSR, or in a build step. Also exposes the staged pipeline behind it
+  (`parse`, `canonicalize`, `sflToCanvasState`, `sflToImportJson`,
+  `sflToRenderInput`) for tools that need an intermediate representation.
+- **`stickyflow/viewer`** — the read-only interactive tier. `createViewer()`
+  mounts a diagram into a container element with select, hover, pan and zoom, and
+  emits serializable events. Never mutates its own model.
+- **`stickyflow/interaction`** — the editing tier, layered on top of the viewer.
+  Two halves that can be used independently:
+  - `bindEditing()` binds DOM gestures — double-click text edit, drag-to-move
+    (including multi-selection), drag-to-resize, and drag-to-reconnect link
+    endpoints — each reporting a serializable event rather than mutating anything.
+  - Pure patch functions with no DOM dependency, usable from Node:
+    `applyTextChange`, `applyMoveChange`, `applyResizeChange`,
+    `applyLinkReconnectChange` turn a gesture's event into updated SFL text;
+    `insertEntity`, `removeEntity`, `insertLink`, `removeLink` cover structural
+    changes that no gesture produces.
+- **`stickyflow/web-component`** — `defineStickyflowDiagram()` registers a drop-in
+  `<stickyflow-diagram>` element.
+- **`Table` as a first-class SFL block kind.** `Table t { … }` alongside the
+  existing `Container t { kind: table … }`, which keeps working.
+- **Interactive DOM contract** (`DOM_CONTRACT_VERSION`, currently `1`) — every
+  rendered node carries its owner's role and id, so an interaction layer can map
+  any sub-node back to the entity it belongs to.
+- **Committed golden renders** (`test/__golden__/`) locking the pipeline's output,
+  plus a repeat-render check asserting byte-identical results.
+
+### Fixed
+
+- **Link `segments:` were silently dropped.** A list-valued property never reached
+  the renderer, because the generic string-props reader used for every other link
+  property cannot stringify a list. Manually adjusted orthogonal routes now
+  survive the round trip and render as authored.
+- **Single-line blocks were mis-measured when patching SFL.** Block ranges were
+  found by counting braces per line as a net delta, which cannot tell a block that
+  opens and closes on one line apart from a line with no braces at all — so an
+  edit could swallow the following sibling block. Brace matching is now a real
+  character scan.
+- **`Table` was missing from the patcher's block-header pattern**, making every
+  `apply*Change` call a silent no-op for tables declared with the new keyword.
+- **Locale-dependent node ordering.** Equal-order scene nodes were tie-broken with
+  `localeCompare`, which is host- and ICU-dependent and could reorder output
+  across machines. Now a locale-independent code-point compare.
+
+[Unreleased]: https://github.com/D-Queck/stickyflow.js/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/D-Queck/stickyflow.js/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 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/README.md

@@ -1,3 +1,168 @@
-# Temporary Holding Version
+```text
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+@@*-  -                *                                       =                                            .         *@
+@@*++-::-::-:::::---::.:.:::::::::::-:::::-::::-:---:-:.   .@@@@@@@.   ::::::---:-:::::::::---::::::--:--:-:::::---:: %@
+@@ .::---::::::-::::::::::-:::::::::::::::-:::::::::.   -@@@@@: -@@@@@+   :::------:-::-::-:::.:::::::::::-::---::-:: #@
+@@*-::::.:::-::::::::-----::::::::-::::::::-:-:::.   *@@@@@    -*+-+@@@@@*   .::::-::::--:::::-:::::-:-::::-:-::::::: %@
+@@.----:--::::::::::::::::-:::::::::.::::--::.   .%@@@@%   .::.-%***+-+@@@@@%.   ::::----:::::::::::::-::::::::::::-: %@
+@@ ------:-:::-::::::-::::-:-::::::-::-::..   +@@@@@@   .-:::::-%*%*%**:  %@@@@@+   :::-:---::-::::::::::.:::::::-::- *@
+@@ .:-:-::-:-::::::-:::-:::::::::::::::    *@@@@@*@@@-.-:-::::.-%%*%**%-.:   +@@@@@*   .--::::::-::::::::::::::::::.: %@
+@@.:.-:---:::::::-::-::::::::::::::.    @@@@@%+. +@@@-:-::-::.:+**%*%%**.-::. @@@@@@@@%   .::::-:::::::::::::::-::.:: %@
+@@:-----::-::::::::-::.:::::::::.   -@@@@@*--    +@@@-.:::-:+*.+=%%**%%+::--: @@@@@@@@@@@@   .:.::::::.:--::-::-:---- %@
+@@ .:::.-:::::::::::---::::::    -@@@@@.:-. .    +@@@-.---:. *-+*=*%%%%-.:-::.@@@@@@@@@%@@@@@    ::::::-:::::--:::::: %@
+@@ ::::::::-::::::--:::::.    %@@@@@ :+-:  .-%%@ =@@@+.::..*%:-@*#*+%*%+.::::.@@@@@@*@@@@@#@@@@@.   .::-:-:-::::::::: %@
+@@:::::::::::::::-::-:.   -@@@@@* -++   +@%@**%@ *@@@-.-:*%*+#%+*+*%%%%+.:-::.@@@@@@@@@@@@@@@@@@@@@+   .:--:::::::::: %@
+@@ .::::::-::.::::..   *@@@@@*.---  .   -@@@*%*- *@@@-.:.. +*%**%#***##+.---:.@@@@@@@@+   -@@@@@@#@@@@%   .:::::::::: %@
+@@ ::::-:::::::.    #@@@@#-   :-*@@ .+@%.@%:-.   *@@@.     .. -*+%##@#@=.-:-:.@@@@@@%  ::.***@@@@   %@@@@#.   .::--:: %@
+@@ :::-:-:::.   .@@@@@@   ::: . #@@ %@@++   -@--:*@@@%@@@@ .:*=**-*%%#@+.:--..@@@@@@: ::..%%*@@@@ ...  :@@@@@-   .::: %@
+@@ .:::-::   -@@@@@@@@@ ::--- . @@@-    -##-+@*- *@@@@@@@@:  - -  *%%%#+.--:::@@@@@@:.-:- %%*@@@@...-+- **+@@@@@+   . %@
+@@ :::    +@@@@#@@@@@@@ -----..    %@@+ *@@+  %  *@@@  #=  @@%.-  *%*@@=.::::.@@@@@@: :-:.%%%@@@@ ..-=* #***+-@@@@@=  *@
+@@ .   %@@@@%%@@@@@@@@@ -----.... .-@@**-   -@:  =@@@.   @@@@+ . -@@@::-=+-:..@@@@@@@ .:: %*%@@@@ :.+=+ #%*%*%+* #@@@@@@
+@@ *@@@@@*   @@@@@@@@@@ ::--+ ...%@@:   *@%+ @+#@@@%@@@  @@@@@@@@@----+----%+:@@@@@@@@  . %%%@@@@...++*.%*%*%*%%-     *@
+@@ -%@-  :--:@@@@@@@@@@ ----- . +   *@@.+@@@@@@@%*+  @@@@@@@@@@@@   -+*%*@@*@#%#@@@@@@@*  %*%@@@@ ..-**.%*%*%*%%+.:.- %@
+@@ : ---+-+--@@@@@@@@@@ ---:-.. .@% %@#++:...+*+   #@@@@@@@@@@@@@  :. .@%-*%@@@%%%%#@@@@@ +**@@@@...=*% %%*%%%-+-:::: *@
+@@ -.-*+-+-+:@@@@@@@@@@ ::-*-  . @**-+-++-     :@@@@@@@@@@@@@@@@@#+    %+ ..-+*@@##%%*@@@@@#+%@@@...=%*.%%%%+-=+--::- %@
+@@ -.++---+::@@@%@@@@@@ ::.     .+-*-+   @@@@@@@@@@#@@@@*:*%#@@@@%%%%**++     .--*@@@#%%%*@@@@@@@...+*% %*%%:-::-::-- %@
+@@ -.+-+--+-:#@@@@@@@@@ .  %@@@@*    %@@@@@@@@@@@@@@@@@@%   :-+*%%***+#@@@@@-   ..:--@@@##%%%@@@@...*%%.#*-*@%:+-:::- %@
+@@ :.-+:-+---@@@@@@@@@@ :@@@@@@@@@@@@@@@@@@@@@@@@@@@@***% ....:%-  %@@@+   @@@@-.   .--+#@@%...-@:. +*% -::-+-.-+.::- %@
+@@ ::+-+-----@@@@@@@@@@ .%==*@@@@@@@@@@@*@@@@@@@@***%%%%*:-.:.-    +@@@@#*@@@@@*%%*-    :--**+--=+*:*%%.%-:.---+-:::- %@
+@@ :.*-+-+--:@@@@@@@@@@ .@@@@@%+#@@@@@@@@@@@@@@@@@%**%%%*.=:..+ :*-** -@@@@%. *%*%*%%*-. .   +*%-+. *%%.#+:+.:---:-:- %@
+@@ ::+----+--@@@@@@@@@@ +  .%@@@@%*#@@@@@@@@@@@@@@@@@***#%=-  :  :+%%        -##@@%%%%%%%+. .  ...: *##::.*#* %%:::-- %@
+@@ :.+++-----@@@@@@@@@.@@@@@   -@@@@*  #@@@@@@@@@@@%@@@@**%%#%*%%%%*=. ..    -=-- -%%%*%%%-    :::: *%#.-*%%%*@*:..-- %@
+@@ :.+:-++--:@@@@@@@@@@   *@@@@%          *@@@@@@@@@@@@@@@@%+*%%%*%##%******%%%:. +#%%*%**%***:+-.:.*%%-*+. #@**@%--- %@
+@@ ::=+------@@@@@@* %@@@@+   @@@*-....--:   -@@@@@@@@+  @@@@@%+*%*%%%##@##%%%% . :****%*%*+=-#*.::  *% :-#@%%*@%.:-- *@
+@@ ::-+-+-+--@@@@@@@@+  -@@@@@+  :-....-----:.  .@%    .    @@@@@@***%%%%%%%*%*+-+*%*#**=*%@@@@% ::.*@%-+:-:-%+-:.::-.%@
+@@ .:+-------@@@@  .@@@@@-  @%----+ ...---+----:.. .::.---::   #@@@@@%+**%*%*%*++-=**+%#@@@@@@@% :: *@@@@***-#-*%*-:- %@
+@@ :.+--+-+-:@@%@@@@:  %@@@@- :--:-   .-+--+------::.::--=+---:   *@@@@@#+-+*%*%-+=@@@@@@@@@@@@+   .*@@@#: :+**-  -:- %@
+@@ ..*-------@@:  *@@@@%  . -:-:..:-%%+**+--+-+-+-:::::--  -+--:::   -@@@@@@*--@@@@@@@@@@@% *##%*****%*#%:.. + .::-:- %@
+@@ ::*+-+--. *@@@@%  -@@@#--:...#@%:   --+++--+--+.-:::-:.@-  :---:-:   :@@@@@@@@@@@@@%-  - :.-%%%%*%#@%%  . + .  %*- %@
+@@ :-*+---+@@%  .@@@@@       @@*:.: ...+:-----.-+-::-::-:-@  %%. ---::::    @@@@@@@.-  -+-* --: ..%###%*%*+. - -%*-.: %@
+@@ .:*--.  :@@@@@   @@- .*@@@@@ :-+ ...-+-.:%@%::+:::::::+%.@@@%+**--+----:.   *  .:*.-*+-*:%  .::..:*##%**%*@*:...:: %@
+@@ .-*:-@@@@*  @@@@@+:#@@@@@@@@ ---....--:%@@@@@#-.:::.-.    -+ + --* .-------::..++% +*+-% @@@%:.:---:.*@%-. ..::::: %@
+@@ .:***. -@@@@% .@@@@@@@@@@@@@ -:+ ...+-:%@@@@@@-:::..-: @*#- -+:*%@ ..   -+ ....+-%.-*+-* @@@@@@:-+----: ..:::::::: %@
+@@ ..*@@@@@- :@@@@@@@@@@@*:@@@@ ---.. .---:%@@@*--..:..--.%#@@  %% -@.+: . *@@@-  ++% +**+* @@@@@@.--+-+---::::-:-::- %@
+@@ :.@+  *@@@@@@@@@@@%=--=-@@@@ --+ ...-+--    :--.-++-::-.  +=-@@@@+ --.. *@@@@@%++% +*+-% @@@@@% *=+-+-+:::::-:::-- %@
+@@...+%@@@@#@@@@@@*---==**+@@@@ ---....---------**%%+-@@-.:---  +%@*-..: . *@@@@@@*+% +**-* @@@@@# -::+=---::--:----- %@
+@@ ::.  -@@@@@@@ :.:++****+@@@@ ---   .-::-++**%*-   :@@@@@:**=+-  -%.-- . *@@@@@@--%.-*+-* @@@@@#   : -**::--------- %@
+@@ ::-: *@@@@@@@+@@@#+****+@@@@ :---+++-*+-%**       *@@@@: ..-****+. -: . %@@@@@@-*%.+=-**-@@@@@%*@@@@@ .--::-:-:--- *@
+@@ ::-:.*@@@@@@@-@@@@#****-@@@@ *%%+=**##%.%*    .+#@%*=*@+   . .-*****+++:.*@@@@@-=*.:*+-*-%@@@@%@@%#@@@*.+--:---:-- %@
+@@ .--:.*@@@@@@@-@@@@@***%-@@@@-=+-*@@@@@+ += +*@@@@##@#%%%##*-   ..-=**+--++:.-@@-=**:*%=**@#%@@%@@@@@@##- :+:::---- %@
+@@ :--:.%@@@@@@@-@@@@@****-@@@@++++-+.   *@#@%%@@%*:   +%@######%-   ..:-%*******-*+**%****+*@@@@*.@@@@@@@@@  ---::-- #@
+@@ ::-:.*@@@@@@@-@@@@@****+@@@@-**%.-. -=@@@@#+.    .*.   +%@@@#@#@%+      -*%-:  ***-*%**#+@%%@@% *@@@@#%@@@= -+-::- %@
+@@ ::-:.%@@@@@@@-@@@@*****+@@@@:%%%*-     .:    .=*%%****.   -#@@@%%%@#%#@@+.   . ****-*%***@%--@%   #@@@@@@@@   -+.- %@
+@@ .-+:.*@@@@@@@-@@@%+++-*@@   ---.*%**+: .  :%***+.  +*****.   .%@@#@%@@%--*-... **%+-#++%+@%@@@% :. +@#@@@@@@@-..=- *@
+@@ :.--:*@@@@@@@-@@::+%@@@.-   -=++@#%%%%**#%***-:+@@#+--*%**%*.   :#@#%*-  .: .. *** -+-=+.@@@@@% -:: %@@@@@#@@*  :- %@
+@@ ::--:%@@@@@@@::*@@@%..-.-*.-#* @@*-+%###**--+:@@@@@@%::.+***%**:   -%%...::   :%-*.:+--*--.*@@* .   .=##@@@@@@@  - %@
+@@ .:+:.*@@@@@@@@@@*::--+-.*@@@@% @@%+++***++*+--      :*@*---=*%*%**-  .    -+**=***+.---*-+- .@* -#@@@%. @@@#@@@@@* %@
+@@ ::--.*@@@@%%*::-+-+-:%@@@@@@@* @@%*%*#%*   -+*=+--@@@@%*#*+++++%*%*%++.-=++++=*%*%=*%=.+:   :@@@@@+ =*--@@@@@@@@*- %@
+@@ .-+.:%@@#+  -***+-@@@@@@@@@@@* @::*%%*%*=-    .=**%@@@+*+*+:  :%*%%*%%***#%**+-+********:+@@@@+.  -+.-**@@#@.    . %@
+@@ ::-:.**:+=. *#%%@@@@@@@@@@@@%  ---%%*%%%%%*+-    .-+-+*+      +%%**=++-*#**%=##++**#%%*@@@@@-   :+**:****+-+%+.::: *@
+@@ ::---#+   *@*   @@@@@@@@@.   ::*%*#%%**%**%%%*=-    .     :+*@%=+*%**%*@%#@##**%###%*#*.  @@@@@=   +###%**%: ..:.: %@
+@@ --+--#* ..  ... @@@@@@   .:-=+-*+-**%%%%%%*%%%%%**- .  -%%%%+-=*%%%*%*%**%**=-%%%%%%%%*--:   @@@@@*   -**+. .::::: %@
+@@ ::::.**  .::...:@@*   --+***==+#*%++=+*%%*%*%*%%%%%%%%@%**==%%%%**%%%+--++-*+--:+%%%%%%.:---:   @@@@%+=@**%=-. ..- %@
+@@.--*%@#*+:. ..--   .-*%@*****%**%*+***%*=*%%%%%*%*%%***-*%%%%*: +**-. :-++= ++++---:+*@%*+-::---.:@@@: .+-  .%#*+.- #@
+@@  ..-*@#%**+-..:-*%#@@##%*%%**++*****%*%*%+*=*%%%%-***%%%**+  .---: *#*..-* ++++=*=++ +%++=**-...-@@@- .-.. .*##@%: %@
+@@@#    .:%###%*%#%@@@##@#**++=****+**%**%%*****+++*%%%#* *#*=+++++-@@@@@@@-+ -++**+ *%*-@-+-+-***:-@@@*. .  -*@*:  . %@
+@@@@@@@     -%@##%*##@@#@#*=*-++***#%***%**%%*%**%%%*:   :--+--+-++- *@@@* +***%   -#*@%-@+*++-*+=**@@@*%*###-.      .@@
+@@@@@@@@@*     :##@%%%%#%%%++*=*%*****#%*#%***%%*%*%%-**=++-+++-++++-     -** .. :%%%-@*:@**%++++=%*%%#@#%. ...   +@@@@@
+@@@@@@@@@@@@*     :#####%#*****=+******%%%#@%%*%*%==++++-+++++++++-+=**%*+ -**%*+#%**+#*+@*%****++%%@#+       :@@@@@@@@@
+@@@@@@@@@@@@@@@%     =%@##%%%*+****%**%%%#####%%%+ ::+=+++++++++++=**+: :*%*-%@@:%+-+ #*-%*%*%*%*%*-      .*@@@@@@@@@@@@
+@@@@@@@@@@@@@@@@@@*     +%#%*%%%****%%%*%###@%%%%*.@#  -***++-=+*+:-   +*%*: ..:--.:= ++=#%%##%*:..    -@@@@@@@@@@@@@@@@
+@@@@@@@@@@@@@@@@@@@@@*    .-@#%*##%****%*#@#%%*%%*.@%-@*: -***-:.-**+%%%%**-:-::-++*% %%*@@*+.      *@@@@@@@@@@@@@@@@@@@
+@@@@@@@@@@@@@@@@@@@@@@@@*     +#@#%%%%**####%%@%#* @#.*%#*++.+%#+%@@*+%*%-.*+--.:-+*%*@#*- .     @@@@@@@@@@@@@@@@@@@@@@@
+@@@@@@@@@@@@@@@@@@@@@@@@@@@:     +@##%#@@%%%%%%%#*.%*=#%*--- -**.: -*=-:++ =-+++.***#- ...   -@@@@@@@@@@@@@@@@@@@@@@@@@@
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@      *@@#@#@#%*%%%*+@%-***--+ -++:+-..++=+-.*-+=*%#-...    %@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@-     %@@@#@#%*%*+%+-**=--+ *%*----.+--++-%%**: ..   -@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@+    .%@@#@##%:***+-****.+*****+.:-+=**+ :.   .*@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@.    -%@@#%%%%++*****-***+-+=*%%+-::    +@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@#     -%##%*%**+-=+-***%***+. .    %@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@%     -#@%*%*%++*%%#*-:..    @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@*     +##%*%%#*...    .@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@-    .%#-. .    *@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@-        -#@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 
-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.
+-------------------------------------------------- StickyFlow.js----------------------------------------------------------
+```
+
+SFL parser, scene builder, SVG renderer, interactive viewer and editing runtime in one package. No runtime dependencies, no React, no Konva. The static tier is DOM-free and runs in Node.
+
+## Install
+
+```bash
+npm install stickyflow
+```
+
+Node 18 or newer. The package ships ESM, CJS and TypeScript types.
+
+## Quick start
+
+```ts
+import { render } from 'stickyflow'
+
+const { svg, width, height, diagnostics } = render(sfl)
+// A complete, deterministic SVG string. render() never touches the DOM.
+```
+
+## Four entry points
+
+| Import | What it is |
+|---|---|
+| `stickyflow` | Static tier. SFL text in, SVG string out. Node, SSR, CLI. |
+| `stickyflow/viewer` | Read-only viewer in the DOM: select, hover, pan, zoom, typed events. |
+| `stickyflow/interaction` | Editing gestures on a viewer. Reports what changed; the host applies the patch to the SFL text. |
+| `stickyflow/web-component` | `<stickyflow-diagram>` custom element in Shadow DOM, no build step. |
+
+Each tier only depends on the one below it; `test/boundary.test.ts` enforces that.
+
+```ts
+import { createViewer } from 'stickyflow/viewer'
+import { bindEditing, applyMoveChange } from 'stickyflow/interaction'
+
+const viewer = createViewer({ container, source: sfl, interactive: true })
+const editing = bindEditing(viewer)
+
+editing.on('moveChange', (event) => {
+  sfl = applyMoveChange(sfl, event)   // the text changes, nothing else does
+  viewer.update({ source: sfl })
+})
+```
+
+## What it draws
+
+Shapes, links, frames, swimlanes, paths and text. Fifteen chart types. Isometric objects. Shader surfaces and widgets. Data sources with bindings, and events with handlers, so a document can react to data and input.
+
+## Principles
+
+- **Deterministic.** The same SFL gives the same SVG, byte for byte.
+- **Text stays the source.** Edits patch the SFL text; comments and order survive.
+- **Layered.** Language, semantic, render input, scene, SVG, runtime, each with one job and one direction.
+
+```
+src/
+  sflLanguage/   AST, lexer, parser, canonical emitter
+  sflSemantic/   SFL AST to canvas state
+  renderInput/   renderer contract and style decoding
+  renderScene/   deterministic scene construction
+  svg/           SVG serialization and the DOM contract
+  runtime/       viewer, interaction, web component
+```
+
+## Develop
+
+```bash
+npm run ci      # lint, typecheck, tests, build, smoke
+npm run build   # tsup
+```
+
+Adding a new placeable object: [docs/ADDING_CANVAS_OBJECT.md](docs/ADDING_CANVAS_OBJECT.md). Changes: [CHANGELOG.md](CHANGELOG.md).
+
+## More
+
+- Docs and examples: [stickyflow.org/docs](https://stickyflow.org/docs)
+- The language: [stickyflow.org/sfl-language](https://stickyflow.org/sfl-language)
+- Playground: [stickyflow.org/playground](https://stickyflow.org/playground)
+
+## License
+
+[Apache-2.0](LICENSE)