@dxos/plugin-tldraw 0.10.0

package/LICENSE

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-Apache-2.0
+
+## Notice
+
+Copyright 2026 DXOS
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+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/PLUGIN.mdl

@@ -0,0 +1,412 @@
+---
+id: org.dxos.plugin.tldraw
+name: TldrawPlugin
+version: 0.1.0
+---
+
+A collaborative whiteboard plugin for `DXOS` Composer — powered by tldraw, persisted in ECHO, and available as a first-class workspace object.
+
+## Extensions
+
+The following extension dialects are used in this document.
+Each extension is defined in the Appendix or resolved via its URI.
+
+| Term        | URI                            |
+|-------------|--------------------------------|
+| `type`      | `org.dxos.mdl.type@1.0`        |
+| `feat`      | `org.dxos.mdl.feat@1.0`        |
+| `test`      | `org.dxos.mdl.test@1.0`        |
+| `component` | `org.dxos.mdl.component@1.0`   |
+| `op`        | `org.dxos.mdl.op@1.0`          |
+
+## Types
+
+```mdl
+type Canvas
+  desc: Low-level drawing document backed by a tldraw store.
+  fields:
+    schema?: string              # external schema reference (default: tldraw.com/2)
+    content: Map<string, any>    # tldraw store snapshot — shapes, bindings, assets
+```
+
+```mdl
+type Sketch
+  desc: User-facing whiteboard object that wraps a Canvas.
+  fields:
+    name?: string
+    canvas: Ref<Canvas>          # reference to the tldraw content store
+```
+
+```mdl
+type SketchGrid
+  literals: mesh | dotted
+```
+
+```mdl
+type Settings
+  fields:
+    showGrid?: boolean           # display a background grid on the canvas
+    gridType?: SketchGrid        # mesh or dotted pattern
+```
+
+```mdl
+type Scene
+  desc: |
+    Backend-neutral scene DSL (src/model). A diagram is a set of world objects
+    ("face", "hat") composed of elements in object-local units; a compiler maps
+    the scene to tldraw records with identity stamped in record meta
+    ({ object, element, kind, scale, dialect }) so edits address shapes by id.
+  fields:
+    objects: WorldObject[]
+```
+
+```mdl
+type WorldObject
+  fields:
+    id: string                   # semantic id ("face"); addressing key for edits
+    origin?: Point               # canvas px; derived from bbox top-left on read
+    scale?: number               # canvas px per local unit (default 1)
+    elements: Element[]          # rect | ellipse | circle | diamond | triangle |
+                                 # line | curve | arc | text | arrow
+```
+
+```mdl
+type Command
+  desc: Scene edit commands (D2-Oracle-style, addressed by id).
+  literals: upsert-object | upsert-elements | remove-elements | remove-object | move-object
+```
+
+## Components
+
+```mdl
+component SketchArticle
+  desc: Full-screen whiteboard surface for a Sketch object. Renders inside article, section, and slide roles.
+  props:
+    subject: Sketch
+    settings: Settings
+    attendableId: string
+    role: article | section | slide
+  state:
+    editor?: Editor              # tldraw Editor instance
+    hasAttention: boolean
+  slots:
+    toolbar?: ReactNode          # injected tldraw toolbar actions
+  actions:
+    createThread()               # opens a comment thread anchored to a selection
+  layout: |
+    ┌─────────────────────────────────┐
+    │ tldraw toolbar (when attended)  │
+    ├─────────────────────────────────┤
+    │                                 │
+    │   infinite canvas (tldraw)      │
+    │   shapes / freehand / text      │
+    │                                 │
+    │   [comment thread anchors]      │
+    │                                 │
+    └─────────────────────────────────┘
+```
+
+```mdl
+component SketchSettings
+  desc: Settings panel for the Sketch plugin — controls grid visibility and type.
+  props:
+    settings: Settings
+    onSettingsChange?: (updater: (s: Settings) => Settings) => void
+```
+
+## Operations
+
+```mdl
+op createSketch
+  desc: Creates a new Sketch with an associated Canvas and adds it to the target space or collection.
+  input:
+    name?: string
+    schema?: string              # tldraw schema version (default: tldraw.com/2)
+    content?: Map<string, any>   # optional initial tldraw store snapshot
+  output: Sketch
+  effects: [echo:write]
+```
+
+```mdl
+op readSketch
+  desc: |
+    Returns the derived Scene (world objects with object-local coordinates) read
+    from the live canvas records, plus a count of unmanaged (hand-drawn) shapes.
+    Origins derive from bounding boxes, so the scene stays coherent after users
+    drag shapes. The agent calls this before editing an existing sketch.
+  input:
+    sketch: Ref<Sketch>
+  output: { scene: Scene, unmanaged: number }
+  requires: [Database]
+```
+
+```mdl
+op editSketch
+  desc: |
+    Applies scene commands atomically (one Obj.update): upsert/move/remove world
+    objects or individual elements by id. Returns the resulting scene so the
+    agent can maintain its mental model across turns.
+  input:
+    sketch: Ref<Sketch>
+    commands: Command[]
+  output: { scene: Scene, unmanaged: number, upserted: string[], removed: number }
+  effects: [echo:write]
+  requires: [Database]
+```
+
+## Features
+
+```mdl
+feat F-1: Whiteboard Canvas
+
+  req F-1.1: Each Sketch owns exactly one Canvas; the Canvas holds the full tldraw store snapshot.
+  req F-1.2: Canvas content is stored as a plain record in ECHO — no binary blobs.
+  req F-1.3: All tldraw shape types (freehand, geometric, text, arrow, image) are supported.
+```
+
+```mdl
+feat F-2: ECHO Persistence
+
+  req F-2.1:
+    when: user makes any edit in the whiteboard
+    then: Canvas.content is updated in ECHO within the debounce window
+
+  req F-2.2:
+    when: Sketch is opened after a page reload
+    then: tldraw store is hydrated from Canvas.content; no drawing is lost
+
+  req F-2.3: Canvas is a separate ECHO object from Sketch so it can be replicated independently.
+```
+
+```mdl
+feat F-3: Real-time Collaboration
+
+  req F-3.1:
+    when: two or more peers open the same Sketch
+    then: edits by each peer appear on the other's canvas via ECHO replication
+
+  req F-3.2:
+    when: a peer is offline and makes edits
+    then: changes merge with remote state on reconnection using ECHO CRDT semantics
+```
+
+```mdl
+feat F-4: Roles and Presentation
+
+  req F-4.1:
+    when: role is article
+    then: full tldraw toolbar shown when the sketch has attention; hidden otherwise
+
+  req F-4.2:
+    when: role is slide
+    then: canvas is read-only; zoom capped at 1.5×
+
+  req F-4.3:
+    when: role is section
+    then: canvas auto-zooms to fit content; no toolbar shown
+```
+
+```mdl
+feat F-5: Comment Threads
+
+  req F-5.1:
+    when: user activates the thread tool in the toolbar
+    then: a new comment thread is created anchored to the current selection
+
+  req F-5.2: Thread anchor positions are stored alongside the drawing so they survive reloads.
+```
+
+```mdl
+feat F-6: Grid Settings
+
+  req F-6.1:
+    when: Settings.showGrid is true
+    then: a background grid rendered beneath drawing content
+
+  req F-6.2:
+    when: Settings.gridType is mesh
+    then: a square-mesh grid is shown
+
+  req F-6.3:
+    when: Settings.gridType is dotted
+    then: a dotted grid is shown
+```
+
+```mdl
+feat F-7: Create Sketch Operation
+
+  req F-7.1: Plugin contributes op:createSketch to the operation registry.
+  req F-7.2:
+    when: op:createSketch is invoked
+    then: a Sketch + Canvas pair is created and returned; the Sketch is added to the target collection
+```
+
+```mdl
+feat F-8: Scene DSL and Agent Skill
+
+  req F-8.1: The scene model (src/model) is backend-neutral — no tldraw imports in scene.ts;
+    the tldraw compiler (render.ts/read.ts) is one backend, Excalidraw can be added later.
+  req F-8.2: Every DSL-generated tldraw record carries meta { object, element, kind, scale, dialect };
+    record ids are deterministic (shape:<object>/<element>) so re-rendering an element reuses its id.
+  req F-8.3:
+    when: op:editSketch upserts elements of an existing object
+    then: only records with matching element ids are replaced; sibling elements are untouched
+  req F-8.4:
+    when: a shape bound by an arrow is removed
+    then: its bindings are removed too; no dangling binding records remain
+  req F-8.5:
+    when: op:readSketch runs after a user drags shapes in the UI
+    then: the derived scene reflects the moved geometry (origin = bbox top-left)
+  req F-8.6: Plugin contributes the org.dxos.skill.sketch skill (create/read/edit tools +
+    DSL instructions: object-local units, semantic ids, read-before-edit workflow).
+  req F-8.7: A dialect registry (scene only for now) reserves the extension point for
+    mermaid / d2 / sequence / uml-class compilers that emit scene commands.
+```
+
+## Acceptance
+
+```mdl
+test T-1: Create and open sketch
+  given: a Composer space is active
+  when: op:createSketch runs with name "My Diagram"
+  then:
+    - a Sketch object is created with name "My Diagram"
+    - Sketch.canvas references a new Canvas with empty content
+    - Sketch appears in the space object list
+```
+
+```mdl
+test T-2: Drawing persists across reload
+  given: a Sketch is open and the user draws a freehand stroke
+  when: the page is reloaded and the Sketch is reopened
+  then:
+    - the stroke is visible on the canvas
+    - Canvas.content is non-empty
+```
+
+```mdl
+test T-3: Collaborative edit
+  given: two peers have the same Sketch open
+  when: peer A draws a rectangle
+  then:
+    - peer B sees the rectangle appear within the ECHO sync window
+    - no data loss if both peers edit simultaneously
+```
+
+```mdl
+test T-4: Read-only slide role
+  given: a Sketch is rendered in role slide
+  then:
+    - tldraw toolbar is not shown
+    - all drawing tools are disabled
+    - zoom is capped at 1.5×
+```
+
+```mdl
+test T-5: Grid toggle
+  given: SketchSettings panel is open
+  when: user enables the grid and selects "dotted"
+  then:
+    - Settings.showGrid === true
+    - Settings.gridType === dotted
+    - dotted grid appears on the canvas immediately
+```
+
+```mdl
+test T-6: Attention-aware toolbar
+  given: a Sketch is open in article role alongside other articles
+  when: user clicks on the sketch to give it attention
+  then: tldraw toolbar becomes visible
+  when: user clicks away, removing attention
+  then: tldraw toolbar is hidden
+```
+
+```mdl
+test T-7: Scene DSL round-trip
+  given: an empty Sketch
+  when: editSketch upserts a "face" object (head/eyes/smile), then upserts a "hat" object and
+    replaces only the "smile" element, then removes the "hat"
+  then:
+    - readSketch returns the face with derived origin and all element ids
+    - the untouched face elements are byte-identical across the hat edit
+    - removing the hat removes exactly its records and no bindings dangle
+  # Covered by src/operations/operations.test.ts and src/model/scene.test.ts.
+```
+
+```mdl
+test T-8: Conversational drawing (live AI)
+  given: the stories-assistant Sketch storybook (config.remote) with the sketch skill bound
+  when: the user prompts "Draw a smiley face", then "Add a hat"
+  then:
+    - the agent creates a "face" world object via editSketch
+    - the follow-up adds a "hat" object WITHOUT redrawing the face (mental-model test)
+  # Manual: stories/stories-assistant/Sketch → DrawAndUpdateTest / Reflection (tags: ['!test']).
+  # Verified live 2026-07-23 (remote EDGE, claude-opus-4-8): face drawn, hat composed on top,
+  # face records untouched.
+```
+
+---
+
+## Appendix: Extension Definitions
+
+```mdl
+ext type
+  uri: org.dxos.mdl.type@1.0
+  desc: A named data structure with typed fields and optional literals.
+  fields:
+    desc?: Prose
+    fields?: FieldMap
+    literals?: UnionList
+    extends?: TypeRef[]
+```
+
+```mdl
+ext feat
+  uri: org.dxos.mdl.feat@1.0
+  desc: A named feature grouping one or more requirements.
+  fields:
+    desc?: Prose
+    req: RequirementList
+  nesting: self
+```
+
+```mdl
+ext test
+  uri: org.dxos.mdl.test@1.0
+  desc: An acceptance scenario expressed as given / when / then steps.
+  fields:
+    given?: Step | Step[]
+    when?: Step | Step[]
+    then: Step | Step[]
+    tags?: TagList
+```
+
+```mdl
+ext component
+  uri: org.dxos.mdl.component@1.0
+  desc: A UI component with props, internal state, slots, actions, and events.
+  fields:
+    desc?: Prose
+    props?: FieldMap
+    state?: FieldMap
+    slots?: FieldMap
+    actions?: ActionMap
+    emits?: EventMap
+    layout?: CodeBlock
+```
+
+```mdl
+ext op
+  uri: org.dxos.mdl.op@1.0
+  desc: |
+    A named operation with typed inputs, outputs, and declared errors.
+    Pure ops have no effects or requires. Effectful ops declare both.
+  fields:
+    desc?: Prose
+    input?: FieldMap
+    output?: TypeExpr
+    errors?: ErrorMap
+    effects?: EffectList
+    requires?: ServiceList
+    note?: Prose
+```

package/README.md

@@ -0,0 +1,3 @@
+# @dxos/plugin-sketch
+
+Surface plugin for sketch entities using Tldraw.