@meltemi/diagrams-canvas 0.0.0-stage → 1.10.0

package/LICENSE

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

package/README.md

@@ -1,3 +1,78 @@
-# Temporary Holding Version
+# @meltemi/diagrams-canvas
 
-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.
+The canvas: the browser application that draws a diagram beside its code and turns every gesture
+(move, resize, route, label, group, align, play) into a small edit of the text. It runs in a host
+that implements `CanvasHostApi`, such as the VS Code webview or the playground, and styles itself
+with `canvas.css`.
+
+It is part of [Meltemi Diagrams](https://github.com/askenaz-dev/meltemi-diagrams#readme), diagrams as code with a canvas, motion and
+exports. Every package of the product has the same version.
+
+## Install
+
+```bash
+npm install @meltemi/diagrams-canvas
+```
+
+Node 22.12.0 or later. The package is an ES module with type declarations.
+
+## Use
+
+```js
+import { CanvasApp } from "@meltemi/diagrams-canvas";
+import { resolveLocale, setLocale } from "@meltemi/diagrams-i18n";
+import "@meltemi/diagrams-canvas/canvas.css";
+
+// The interface language, English or Spanish, is set before the canvas is created.
+const locale = resolveLocale(navigator.language);
+setLocale(locale);
+document.documentElement.lang = locale;
+// `host` posts canvas messages to the editor services and delivers their answers.
+const app = new CanvasApp(document.getElementById("canvas"), host);
+```
+
+The canvas speaks the interface language of `@meltemi/diagrams-i18n`: its toolbar, palette,
+menus, inspector controls, dialogs, announcements and story timeline. The words the host sends,
+such as field labels and statuses, are shown as they arrive. The page's `lang` lets the stylesheet
+make room for longer words.
+
+A host can make the canvas only show by sending `readOnly: true` in the settings of its `settings`
+message (`CanvasSettings`, in `@meltemi/diagrams-editor`); each `settings` message replaces the
+settings as a whole, so a later one without it makes the canvas edit again, with no reload. While
+it is on the canvas sends no message that changes the document, and selection, zoom, pan, the
+minimap, stories and effects keep working ([editor guide](https://github.com/askenaz-dev/meltemi-diagrams/blob/main/docs/editor.md)).
+A host that never sends it, such as the VS Code extension, sees no change.
+
+A host that shares the diagram can show who else is in it with `presence` messages (`HostMessage`,
+in `@meltemi/diagrams-editor`): the other people, each with a name, a colour and the ids they have
+selected. The canvas draws an outline in the person's colour around each of those and a tag with
+the name (always text, never markup) on a layer above the scene that is never selected, copied or
+exported and that nothing of is sent back. A person may also have a `pointer` (`{ x, y }` in
+diagram units): the canvas draws a cursor in their colour with the name at its tail, which glides
+to the next point in 200 ms and keeps its size at every zoom. Each message replaces the last; a
+message with nobody, an empty canvas or another diagram clears it, and ids the diagram does not
+have, and pointers that are not two finite numbers, are ignored. Once a host has sent `presence`,
+the canvas tells it where the person's own pointer is with `presencePointer` messages (diagram
+units and the diagram's id, `null` when it leaves), at most every 50 ms.
+
+The Pointer tool (K, or its toggle before the grid's) draws a trail that fades in 800 ms and edits
+nothing, on every canvas, read-only ones included; the trail is no part of the document or of any
+export. In the colour of the person: the `me: { colour }` of the last `presence` message, else the
+render's `colors.accent`. A person's `laser` (`{ batch, points }`, at most 64 points `{ x, y, t }`,
+`t` in milliseconds since the batch's first point) is drawn once per `batch` as that person's trail,
+and the canvas posts the points of the person's own strokes with `presenceLaser` messages to a host
+that has sent `presence`, at most every 50 ms.
+
+Popovers, menus, side panels, tooltips and target outlines open and close with short transitions
+on the motion tokens of `canvas.css` (`--mdg-motion-fast`, `--mdg-motion`, `--mdg-motion-slow`,
+`--mdg-ease`). When the system asks for reduced motion they are zero and nothing moves.
+
+## Documentation
+
+- [Editor guide](https://github.com/askenaz-dev/meltemi-diagrams/blob/main/docs/editor.md)
+- [Playground](https://github.com/askenaz-dev/meltemi-diagrams/blob/main/docs/playground.md)
+- [All documentation](https://github.com/askenaz-dev/meltemi-diagrams/blob/main/docs/README.md)
+
+## Licence
+
+MIT. Third-party components and their licences are listed in [THIRD_PARTY_LICENSES.md](https://github.com/askenaz-dev/meltemi-diagrams/blob/main/THIRD_PARTY_LICENSES.md).