Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
Graphics
Experimental graphics editor with a framework-independent scene tree.
For a short implementation-based reference, start with the Graphics API guide.
Status reviewed 2026-09-28. The parity plan is the progress/next-checkpoint index. Canvas Next now includes rich text/mentions, shape labels, connectors, media, document cards and full embeds as the default canvas editor. Versioned JSON persistence is wired at the Canvas host boundary. Canvas Next binds the Loro adapter to its production shared collaboration runtime. The next product checkpoint is a legacy bridge and color policy, kept outside the pure core. Expanding peer support is deferred.
@macro-inc/graphics: document, affine math, scene queries, selection, editing, validation and local history. No DOM, Solid, app or Loro imports.@macro-inc/graphics/browser: pointer capture, keyboard and wheel input.@macro-inc/graphics/solid: read-only reactive projection and keyed renderers.@macro-inc/graphics/loro: optional Loro backend and presence APIs. The in-memory peer transport lives in test support only.@macro-inc/graphics/loro/solid: optional awareness rendering and smoothing.
Scene contract
Documents have one surface root and a normalized node map. Shapes
and groups have one authoritative placement: { parentId, sortKey } and a local
affine transform: [a,b,c,d,e,f]. Rectangles and ellipses own local width/height and appearance. Pencil owns raw
local [x, y, pressure] samples and simulatePressure; ink is derived.
Groups own no intrinsic geometry; their bounds come from descendants. Child lists
and paint order are derived from case-sensitive fractional string keys allocated
by fractional-indexing.
Use sortKeysBetween(lower, upper, count) to create keys; null means an open end.
Keys must be unique among siblings; different parents may reuse keys. Comparison
uses code-unit ordering, never locale-sensitive sorting. Rendering and reverse
hit testing consume the same depth-first scene order.
Flat scenes are ordinary trees with shapes directly under the surface. Additional
typed kinds are text, connector, image, video, document and artifact; their feature contracts
are documented below. Shape labels are owned by rectangle, ellipse or connector
geometry.
Matrices use column vectors: x'=ax+cy+e, y'=bx+dy+f. World transforms compose parent * local. Positive rotation is clockwise; angles are radians. Core queries own coordinate conversion, inverse transforms, transformed corners, polygon intersection and topmost hits. Invalid roots, cycles, missing/leaf parents, nonfinite or noninvertible local/world transforms and invalid dimensions are rejected before an atomic document commit.
createScene accepts only current typed nodes. Schema versions, legacy formats and
migrations belong to durable host boundaries such as Canvas Next.
Editing
The editor composes the selection feature through its explicit SelectionHost
contract. Selection, box previews and transform overrides are session state.
Creation, move, rotation, resize, grouping, ungrouping, reparenting and subtree
deletion commit once, with bounded 100-entry local undo/redo. Navigation and
selection never enter history. Invalid operations make no partial changes.
Local history stores reversible item deltas: each entry references only the items added, removed or replaced, plus changed root/surface metadata. Unchanged immutable items and geometry are shared across commits; moving a pencil stroke retains its existing samples. Undo/redo applies the whole delta atomically and restores the original item references. No document snapshots are retained by the stacks. Validation still checks scene-wide containment, ordering and connector invariants. The optional backend owns its own history; Loro continues using its UndoManager.
fitScene(viewport) centers the full scene's world bounds and zooms in or out
until the first axis fills the current viewport with 100 screen pixels per side.
It respects camera zoom limits and reduces padding in small embedded viewports.
The host supplies its actual current dimensions; selection and current camera
offset do not influence the fit.
Group/reparent/ungroup preserve world transforms. Selected ancestors suppress
descendants as edit targets, preventing double movement/deletion. Mixed-parent
moves and pivoted rotation operate in world space, then convert back into each
parent's coordinates. selectionFrame is pure derived state shared by the Solid
overlay and the resize operation. One shape uses its full local-to-world frame;
a group or multiple roots always use a dashed world-axis-aligned box, regardless
of their rotation. Single shapes retain their local oriented solid outline.
Click-drag anywhere inside the selected box moves its selected roots, including
empty space and unfilled interiors. Shift and deep-select modifiers still pick
individual shapes. This does not change hit testing for unselected shapes.
Editors accept snapUnit in their options, with getSnapUnit() and
setSnapUnit(unit) for local configuration. Any positive finite scene-unit
interval is supported, including fractions; undefined disables grid snapping.
It is independent of camera zoom, document serialization and backend choice.
Changing the unit cancels active drawing/transform previews without adding history.
CommandContext.snapUnit and the pure snapValue, snapPoint, and
snapTranslation helpers let contributed commands use the same policy.
Rectangle/ellipse drawing and free connector endpoints snap positions. Moves, nudges, duplicates and pasted fragments snap their common world-bounds anchor, preserving internal spacing, pointer grab offsets and untouched axes. Resizing snaps physical dimensions along the selection's axes, accounting for ancestor scale. Proportional resizing snaps its controlling dimension while preserving aspect ratio; center resizing keeps its center. Image boundaries, connector bindings and angle/axis constraints take priority over the grid. Freehand samples, rotation, equal distribution and exact alignment retain their own semantics. Snapping does not round existing documents on load or remote updates.
Object snapping is a separate opt-in editor option (objectSnapping, default
false) controlled by setObjectSnapping(enabled) and exposed in the session.
Canvas enables it by default. Moves align the selection's combined world bounds'
edges and centers; axis-aligned resize handles align their moving edges. Rotated
resize frames keep local-axis behavior, and image surfaces do not object-snap.
The index caches sorted anchors and perpendicular interval trees per immutable
scene snapshot, with O(n log n) construction and a constant number of spatially
pruned anchor queries per pointer update. Selected objects and their ancestors /
descendants are excluded. Tolerance is six screen pixels; perpendicular reach is
160 screen pixels. Object matches override grid values on matched axes without
breaking axis or aspect constraints. transform.snapGuides drives the Solid
overlay and transform.snapStats exposes aggregate query work to host telemetry.
Changing the setting cancels active transforms without adding history.
The Solid surface's dot grid is camera-aware presentation: scene-unit intervals
1, 4, 16, 64, 256, etc. appear progressively as zoom increases. Fine dots fade in
from invisible at 4 screen pixels apart to full strength at 36; coarser dots stay
steady. At 800% individual canvas pixels are marked subtly at 12.5% opacity.
Three screen-space SVG patterns use fixed 1 px marks and crisp edges to avoid
resampling gradient tiles at fractional zoom. Each surface has unique pattern
IDs, and pattern count is independent of viewport size or dot count. All levels
share the scene origin and the caller's gridColor. The pure dotGridLevels(scale)
helper exposes those same intervals and opacities so hosts can choose a matching
snap unit. The surface itself does not change snap policy or document data.
Hold Shift during rotation to snap a single shape/group's world angle to 30° increments.
Hold Shift during movement to constrain the world-space delta to its dominant
horizontal or vertical axis, including nested selections and Option-drag duplicates.
Rectangle/ellipse drawing accepts DrawingModifiers.proportional to create a square
or circle; the browser maps Shift to it. The original pointer endpoint is retained,
so pressing/releasing Shift updates the preview immediately. Image-surface drawing
reduces both dimensions together when a constrained shape reaches the image edge.
Shift-click still toggles selection on release; crossing 3 screen pixels begins
a move instead. Shift-drag on empty canvas remains additive marquee selection.
Multiple selections snap the rotation delta while preserving relative angles.
The rotation circle sits 16 screen pixels outside a single shape's oriented top
edge, or above the world-aligned bounds for groups and multiple selections, with
no connecting stem. Single-shape resize adjusts local dimensions and placement while
keeping the opposite corner or edge midpoint fixed. Hold Shift to preserve the
original aspect ratio. Hold Alt/Option to resize from the original center;
Shift+Alt/Option combines both. Modifiers update even without pointer movement.
Invisible targets along each full edge also resize single shapes, multiple selections and groups.
Selected rectangles also have inset circular radius controls. radius-nw/ne/se/sw
gestures adjust the existing uniform appearance.cornerRadius in local shape units,
in whole-pixel steps independent of scene snapping, with a half-short-side clamp,
ephemeral preview, cancellation, and one
history commit. Geometry and pose stay unchanged. The controls follow affine parent
transforms while their visual size stays fixed on screen.
During a radius drag, the active handle shows the whole-pixel value as white text
on the filled selection-color badge.
Each target spans 10 screen pixels across the edge at any zoom. Visible corner
handles take priority where they overlap the edge targets.
Handles stay square to the screen. Top/bottom edges use ns-resize; side edges use
ew-resize. Corners use nwse-resize or nesw-resize according to their world-space
quadrant relative to the selection center, including rotated or flipped shapes.
The chosen cursor stays visible during the drag preview.
Active gestures follow their pointer at the window level until release, even if
pointer capture is lost or the pointer leaves the canvas. Escape, pointer cancellation,
focus loss and disposal still discard previews; capture loss alone does not.
Left/right changes width; top/bottom changes height. Single-shape handles follow
the selection frame's axes. Perpendicular pointer motion is
ignored. Alt/Option anchors the center. Shift preserves proportions and centers
changes on the perpendicular axis, including when shrinking.
Shared corner and edge drags can stretch axes independently only when every selected node and descendant has axes parallel to the frame (quarter turns are compatible). Otherwise the entire gesture scales proportionally, keeping the opposite anchor fixed and the content fitted to the box without adding shear. Existing affine shear is preserved; shared resizing of such selections is uniform.
Nonuniform shared resizing uses stretchShapes to move leaf centers and resize
geometry, retaining group frames and placements. Crossing the opposite edge
reflects the leaf axes as well as their positions, so the contents truly flip.
Uniform resizing transforms selected roots once. Stroke width/radius stay local
dimensions during geometry resizing and scale with uniform root transforms.
Shapes opting into regenerateOnScale (pencil) instead absorb the added scale
into samples and compensate in their local pose, preserving nominal brush width.
Single and shared resizing continue through zero and invert each crossed axis.
Only a tiny minimum magnitude (1e-6 of the starting extent) keeps transforms
invertible at the exact crossing. Shift proportions and Alt/Option center anchors
apply on both sides of zero. Every gesture previews, cancels and commits once.
Grouping initially requires a common parent. Noncontiguous siblings become one
contiguous group at their earliest selected sibling position, which can change
stacking relative to unselected siblings. Ungroup splices children back in order.
Reparent takes a position: 'front' (default), 'back', { before: siblingId }
or { after: siblingId }. It allocates a new key for the moved node. Grouping
retains child keys and places the group at the backmost selected key. Ungrouping
allocates new keys only for children released into the parent's order.
reorderNodes(document, ids, 'front' | 'back' | 'forward' | 'backward') and
editor.reorderSelection(operation) preserve selected nodes' relative order and
operate independently within each parent. Forward/backward move selected runs
past one unselected sibling; front/back move them to the ends. Only moved nodes
receive new keys; other siblings are never renumbered. Each command is one undo
step, with no history entry for a no-op. Groups remain contiguous subtrees.
These keys support stable local edits and serialization, not concurrent allocation on their own. Duplicate sibling keys are rejected at the document boundary. Concurrent inserts can generate the same key; the Loro adapter must resolve or replace this allocation with ordered-tree positions before shared documents are enabled. An isolated Loro experiment now exercises these cases; its mapping and conflict policy are documented separately below.
Solid renders drawable IDs in tree paint order with computed world matrices. Grouping/reparenting/reordering preserves keyed component identity. The surface isolates its content stack from the app, each item wrapper isolates its renderer, and editor overlays live above content. Renderers may layer their internal children, but must keep document content inside their item wrapper; portals are reserved for explicitly coordinated editor UI. Selection polygons, a solid oriented box for a single shape, a dashed axis-aligned box for groups and multiple selections, corner handles, invisible edge targets and rotation handles are drawn in a viewport overlay, so their size is independent of ancestor scale/rotation. The shared box and handles hide during transform previews; individual outlines remain visible. Selected shapes (including selected groups' leaves) also get a one-screen-pixel selection-color trace along their geometry: the pencil's streamlined centerline, rounded rectangle perimeter, or ellipse. In groups or multiple selections, rounded rectangles and ellipses show only that geometry trace inside the shared selection box, without individual rectangular boxes. These non-interactive SVG traces use non-scaling strokes in the viewport overlay. The Select tool previews the same trace on hover, using the exact pointer-down target policy (3 screen px tolerance, click-through, group/deep selection, and selected box interiors). Hover stays local to the browser/Solid adapter, repicks after camera/document/modifier changes, and hides while dragging, panning or drawing. It never enters core session state, history, persistence or collaboration awareness. The scene tree does not require a matching DOM tree.
Boundaries and verification
One surface per document, a centrally compiled typed shape registry, linear scene queries are deliberate prototype limits. Text, connectors and embedded item contracts are implemented. Frames/clipping, layout, multi-surface documents, per-host core registries and runtime plugin loading are not. Affine reflection/shear compose correctly, but have no dedicated UI controls. The Canvas host owns SyncService integration and persistence. Loro uses native local undo; never apply local item-delta undo to a shared document.
The scene foundation specification
describes the intended longer-term boundary and collaboration questions.
Run bun run test and bun run type-check here. Tests cover tree invariants,
transform math, document reset, pose preservation, nested editing, history, selection,
input routing and stable Solid mounts. The no-DOM compilation/import checks
enforce the pure TypeScript core boundary.
Pencil
shapes/pencil.ts wraps perfect-freehand with private brush settings. Documents
store the raw local centerline and normalized pressure values, not SVG paths,
brush presets, timestamps, or generated bounds. Mouse strokes use spacing-based
pressure simulation; pen strokes retain hardware pressure. Resize scales samples
and regenerates the ink, including simulated pressure, without changing nominal
stroke width. Reflections and nested placement remain scene transforms.
Rendering, hit testing and selection bounds share the generated ink polygon. The selected pencil's centerline highlight comes from the same brush calculation; it does not trace the raw samples or the outer ink polygon. Click tolerance is measured in world space after ancestor transforms; marquee uses polygon/box intersection, so empty loops and unused bounds do not hit. Immutable core geometries cache derived ink. The Solid projection exposes both a reconciled store for fine-grained UI reads and a reactive immutable snapshot for rendering and geometry queries. Pan, hover, selection, move and rotation previews reuse cached ink; geometry or stroke-width changes regenerate it. The keyed renderer emits one filled SVG path. Fill/radius have no pencil meaning; stroke color, width and opacity control its ink.
Browser coalesced pointer samples are processed as a batch. Preview and commit use the same brush endpoint policy to avoid a release-time change in shape. One stroke creates one history entry; cancellation creates none. A tap creates a dot. Samples are deeply frozen and limited to 16,384 per stroke; further samples are ignored at this prototype limit. Point editing, erasing, straight segments, compact point encoding and spatial indexing remain later work.
Adding a shape
Shape registration is explicit and compile-time. There is no mutable global registry or runtime plugin loading. Rectangle, ellipse and pencil follow the same path:
- Add a pure module under
src/core/shapes/exporting its geometry type andShapeDefinition<'kind'>. Add the geometry type toShapeGeometryMapinmodel.ts, then add the definition to the mapped registry inshapes/registry.ts. TypeScript checks the kind/definition pairing. - Implement geometry validation, deep freezing, local bounds, point hit testing,
box intersection, resize and geometry equality. Bounds may have a nonzero local
origin (pencil ink extends around its samples).
resizescales geometry about the local origin without changing identity/placement/transform; the selection feature applies translation and reflection. A brush may regenerate its outline rather than making painted bounds fit the target box exactly. Opt intoregenerateOnScalewhen uniform group scaling must also rebuild geometry. - Point picking receives a local point, the complete world transform,
and a tolerance in world units (
3 / camera.scale). Measure outline distance in world space to preserve screen tolerance through nested affine transforms. Marquee intersection uses the actual shape, regardless of fill. - Add a Solid component under
src/solid/shapes/withShapeViewProps<'kind'>, and register it indefaultRenderersinsolid/shape-renderers.tsx. It receives a reactive item, effective scale and optional preview state. Hosts can supply typed overrides viarenderers; image markup retains its rectangle renderer. The core never imports these. Register the geometry-only selection indicator in the typedoutlinesmap insolid/selection-outline.tsx; it must usenon-scaling-strokeand local geometry. - Add a typed acquisition gesture to
core/drawing.ts, separate from the shape definition. Boxes collect two corners; pencil collects samples. Browser input callsbeginShape, batchedupdateDrawing,commitShape,cancelShape;getDrawingPreview(appearance)produces the typed temporary shape. Rectangle aliases remain for the image host. Selection and rendering consume definitions and typed previews without shape-specific gesture branches. - Cover curve/interior picking, zoom tolerance, box intersection, invalid geometry, transforms and history, and verify the actual component and controls in-browser.
Ellipse performs analytic curve picking after transforming to principal axes; marquee queries transform the box into ellipse-normalized coordinates. Neither uses the ellipse's bounding rectangle as its hit area. Selection handles still use the local bounding rectangle, as they do for other bounded shapes.
This checkpoint proves typed shape modules, not a general-purpose extension API: text and connector gestures now have explicit feature contracts; layout, per-host core registry composition and dynamic plugins remain future work. Schema versioning and import/export boundaries can be introduced when real persistence is needed.
Typed commands and everyday editing
GraphicsCommand<Payload> is a pure contribution with id and
apply({ document, selection }, payload). Return a proposed document and optional
selection. editor.execute(command, payload) validates the proposal and makes one
history step; returning the original document is a no-op. The command receives no
Solid, browser, persistence or collaboration objects. Inject ID factories in the
payload for operations that allocate nodes.
Built-ins: selectAllCommand, nudgeCommand, duplicateCommand, pasteCommand,
styleCommand, alignCommand, and distributeCommand. copyFragment extracts
selected subtrees in paint order, with root transforms expressed in world space.
parseFragment validates bounded clipboard input; pasteFragment remaps every ID
and reconstructs local transforms in the destination parent. Canvas supplies OS
clipboard and shortcut policy. See the Canvas Next notes.
Groups have no inherited appearance. Styling a group updates its leaves. Stroke
width (default 2), opacity (1), and rectangle radius (0) are optional typed fields;
resolveAppearance supplies defaults. Width/radius use local units and scale with
the node transform. The Loro adapter writes each style field independently so local
undo of one property preserves a peer's edit to another.
The Solid renderer calculates one world-space offset for ordinary move previews
and applies CSS translation only to moving wrappers and outlines. Selected shapes
(including group descendants) retain their keyed mounts, geometry, and flat paint
order. Content and unselected shapes do not receive pointer updates. Connectors
retain their live geometry path so bindings track moving ends.
Resize/rotation and committed document changes use the regular projection. Shape
renderer item props are live views: read their fields in reactive scopes, as with
Solid props, rather than relying on the outer object's identity changing. Nested
geometry and appearance retain their immutable identities for core caches.
beginTransform optionally takes an ID factory to preview subtree duplication.
Its session-only preview document includes new nodes; the durable document remains
unchanged until a moved gesture commits. Cancellation discards the preview and
restores the previous selection. Solid keeps original keyed mounts intact.
Loro adapter
createLoroGraphicsBackendFromDoc binds to a host-owned Loro document without
freeing it on disposal. Host bookkeeping tagged GRAPHICS_METADATA_ORIGIN is
excluded from scene undo. The in-memory peer harness gives tests two real Loro replicas with independent
selection, camera and local undo. See the adapter notes for
its ordered tree mapping, geometry conflict policy, limitations and validation cases.
The optional @macro-inc/graphics/loro/solid wrapper adds colored peer cursors,
selection outlines and ghosts of pending drawing/move/resize/rotation gestures.
Awareness uses a separate ephemeral channel: it never enters the document, local
selection, hit testing or undo. Disconnect clears remote overlays; reconnect sends
fresh presence. The core and ordinary browser/Solid surfaces do not depend on it.
Rich text
text is an explicit shape kind. TextGeometry.content is a host-defined opaque
string; geometry also stores measured width/height, typography and auto-width.
Core checks only that content is a string of at most 2,000,000 UTF-16 code units
and preserves it verbatim, including empty strings. The host owns format validation
and decides whether a completed edit sets content, deletes a text item or clears a
label. setTextCommand stores content as one history entry; setShapeLabelCommand
clears a label only when the host omits it. Existing transforms, picking, ordering
and clipboard work unchanged.
Pass {measureText} to the editor for actual font metrics. The default browser
measurer and Solid TextView treat content as literal plain text. A host using an
encoded format supplies a contentView to TextView/RectangleView/EllipseView and a
matching TextMeasurer. Graphics does not parse editor JSON or infer empty content.
Canvas Next owns its Lexical codec in apps/web/src/features/block-canvas/core/text-codec.ts, including
bounded tree validation, seed construction, serialization and empty-content
checks. Its clipboard adapter validates imported text/labels.
It uses the shared Markdown builder and StaticLexical renderer for editing,
display and measurement, and owns the matching markup styles. Only the active item
mounts an editable editor. The optional Loro adapter continues storing the whole
string without parsing it; no content migration is needed.
The shared host supports mentions in both text and labels. Mention decorators scale with typography; active editing keeps the native caret without an extra box outline. Backend mention tracking/notifications remain disabled in Canvas Next.
Single-text side edges change wrapping width; other grips scale font and box proportionally. Completed content is one LWW string in the optional Loro adapter, independent of pose. This is the chosen collaboration granularity, not a character CRDT. GraphicsSurface accepts overlays, hidden selection and suspended input so host editing stays separate from geometric tools.
Mixed selections containing text scale uniformly to preserve letter proportions;
use a single text shape’s side edges to change wrapping width. Shape definitions
express this through the canDeform capability used by selection-frame math.
Rectangles, ellipses and connectors accept geometry.label?: ShapeLabel, containing
portable rich content, font family/size, and measured height. Box label width is
derived from the padded shape interior. Connector labels store a measured width
and sit at the route midpoint. setShapeLabelCommand edits/clears only the label.
shapeLabelLayout supplies a shared local transform for rendering, editing, and
picking. Box labels wrap and fit uniformly inside their owner. Shape resizing uses
the injected measurer to update label height; headless hosts without one retain the
stored height and should remeasure before displaying changed wrapping. Labels are
part of shape geometry in the core; fragments preserve their serialized strings.
The Loro adapter stores label content and layout separately from pose, allowing
label creation or editing to merge with moving its owner.
textTargetAt is a text-gesture query that includes unfilled shape interiors;
ordinary shape picking adds only the label's visible layout box.
Connectors and references
ShapeItem<'connector'> stores two local endpoints, route (straight, stepped,
smooth), and start/end heads (none, arrow, arrow-filled, circle,
circle-small). Each endpoint has a fallback point, optional outgoing direction,
and an optional { targetId, anchor } reference. Anchors are center, top,
right, bottom, left. References are independent of scene containment;
connectors remain ordinary keyed shape components in document paint order.
core/connectors.ts resolves references through the target's current world matrix
and geometry, including uncommitted transform overrides. Side ports stay at edge
midpoints. A center port automatically intersects the target outline toward the
other endpoint (exact ellipse and rounded rectangle outlines; bounds for other
shapes). Groups are not attachment targets; their eligible shape children are.
Connectors cannot target pencil strokes, other connectors or themselves. Missing
or ineligible targets use stored fallback coordinates, so older pencil bindings
still load without following the ink. No route cache or Solid state is persisted
in geometry.
connector-routing.ts ports the original Canvas route math: straight segments,
36-unit rectilinear leads with rounded 10-unit corners, cubic smooth curves and the
same arrow/dot styles. Rotated target normals preserve an outward lead. Picking
follows the sampled rendered path and head geometry, with screen tolerance supplied
by the host. It does not select the empty path bounding box.
createConnectorInteraction owns a disposable draft and preview scene. The browser
endpoint adapter captures the gesture; GraphicsSurface.attachControls owns that
adapter's viewport lifecycle. The app owns tools, defaults, inspector and hover-only
screen-sized endpoint circles. connectorTargetAt is the shared hover/start/drop
policy: only the frontmost hovered shape exposes ports; nearby edge points win,
and the interior core activates the center. Only the active port gets a larger
blue halo. Releasing submits setConnectorCommand as one history
entry. Escape cancels; Shift snaps free endpoints to 45 degrees. Both endpoints can
be reattached independently. Moving a connector body moves free endpoints while
bound endpoints remain on their targets, matching legacy Canvas.
Copy/paste and duplicate remap references when the targets are copied too. External references detach at their current visible endpoints. Deleting a target detaches surviving connectors in the same history transaction; undo restores the references. Reparenting keeps world positions through the existing tree math. The existing Loro adapter transports connector geometry and references without core dependencies on collaboration. Connector labels share the existing label/text path and Loro mapping. Endpoint drafts are local only; connector-specific remote gesture awareness remains follow-up work.
Embedded items
image and video store box dimensions, a name, and a stable MediaSource
(document ID, static-file ID, or safe HTTP(S)/root-relative URL). document stores
box dimensions, document ID, file type and a fallback name. Definitions participate
in the same transform, selection, connector, clipboard, grouping and Loro paths as
other shapes. insertShapesCommand inserts an ordered batch in one undo step.
Default Solid renderers show placeholders; hosts provide asset and preview views.
No upload, storage-service, player or application preview dependency enters core.
Artifacts
artifact stores box dimensions, a title, a self-contained HTML document, its
design size and a presentation sort key. The HTML lays out at the design size and
scales to fit the box. Core treats the HTML as opaque content: it never parses or
executes it, and the default Solid renderer shows a placeholder. Hosts own
sandboxed rendering. setArtifactCommand edits content fields in one undo step;
box size and pose stay with transform commands. presentationOrder lists artifacts
for presenting, and setPresentationOrderCommand reorders them in one undo step.
Host-measured text fitting
Canvas loads Inter Variable, Playfair Display Variable and Roboto Mono Variable for the shared sans/serif/mono map, keeping browser and headless glyphs consistent. Other hosts can use the declared system fallbacks when those fonts are unavailable.
fitTextLayout(document, requests, textMeasurer) uses the host's actual text
renderer and returns an immutable candidate plus measured effects. The persistent
fitText policy on text/labels is grow (preserve font and increase height),
contain (explicit fixed geometry and scaling), or error (reject overflow).
Shape labels reuse measureShapeLabel and shapeLabelLayout, including the safe
ellipse interior. Hosts must remeasure text/font/wrapping-width changes and
revalidate asynchronous measurements against concurrent edits before committing.
AI awareness previews may carry bounded validated geometry/text and per-target
preconditions; human previews retain their document-clock guard.