Ideallo format

Complete format specification for Ideallo, Cloudillo’s collaborative infinite-canvas whiteboard and diagramming app.

Overview

Ideallo is a real-time collaborative whiteboard that supports freehand drawing, shapes, text labels, sticky notes, polygons, connectors, and images on an infinite canvas. Documents are stored as Yjs CRDT structures for conflict-free concurrent editing.

  • Content type: application/vnd.cloudillo.ideallo+json
  • Format version: 2.0.0
  • File extension: .ideallo

Design Philosophy

  • Compact field names: All stored types use short keys (t, xy, wh, sc) to minimize CRDT sync overhead. This section documents the compact names directly – they map 1:1 to what you see in the code and on the wire.
  • Separate maps by content type: Objects, text content, polygon geometry, freehand paths, and z-order each get their own top-level Yjs shared type. This enables targeted observers and prevents the CRDT shared-type nesting pitfall.
  • Flat object model: Unlike Prezillo’s hierarchy of layers, groups, views, and style inheritance, Ideallo uses a flat structure – all objects live in a single map with no parent-child relationships, no layers, and no global style system. Every style property is inline on each object.

Document Architecture

graph LR
    Doc[Y.Doc]

    subgraph Content
        o["o (Y.Map&lt;StoredObject&gt;)<br/>Objects"]
        r["r (Y.Array&lt;string&gt;)<br/>Z-Order"]
        txt["txt (Y.Map&lt;Y.Text&gt;)<br/>Text Content"]
        geo["geo (Y.Map&lt;Y.Array&lt;number&gt;&gt;)<br/>Polygon Geometry"]
        paths["paths (Y.Map&lt;string&gt;)<br/>Freehand Paths"]
    end

    subgraph Settings
        m["m (Y.Map)<br/>Metadata"]
    end

    Doc --> Content
    Doc --> Settings

Quick Reference

Map Key Yjs Type Purpose
o Y.Map<StoredObject> All canvas objects (rects, text, images, etc.) keyed by ObjectId
r Y.Array<string> Z-order array of ObjectId values (index 0 = backmost)
txt Y.Map<Y.Text> Text content for Text and Sticky objects (Quill Delta format)
geo Y.Map<Y.Array<number>> Flat vertex arrays for Polygon objects
paths Y.Map<string> SVG path strings for Freehand objects
m Y.Map Document metadata (name, background color, grid settings)

Detailed Documentation

  • Document Structure – Top-level CRDT maps, initialization, ID system, and metadata
  • Object Types – All 9 object types with their fields and supporting types
  • Linked Copies – Content sharing between objects via tid/gid/pid
  • Export Format – JSON export envelope and serialization details

See Also