Slide Dsl

The slide DSL

A slide page is a JSON document. Editing it well means writing the exact field that holds the thing you want to change, in the exact shape the renderer reads, and leaving every neighbouring field byte-identical.

Read this part first, because it changes how you should use everything below. The write path stores what you send. There is no markup allow-list, no sanitizer, no colour or font normalisation, no geometry clamping, no house style applied on the way in. patch_stage checks one thing — that the resulting document still matches the DSL structure schema (field names, types, required fields, closed objects) — and then persists your value byte for byte.

So there is nothing between you and the screen. A structurally legal page can still be an unreadable page: markup the renderer never styles, a colour on a field nothing paints, a formula snapshot that disagrees with its source. The guard rail catches shape, not meaning. This manual is the meaning. Where it tells you how the renderer behaves, that is the whole of your knowledge — write against it, then read the page back and check what you wrote is what is there.

Contents

1. Reading before writing — the three read depths
2. The document — content → canvas
3. The canvas — viewport, theme, background, animations, paint order
4. How an edit reaches the JSON — three ops, pointer rules
5. What the structure schema refuses — the only hard boundary
6. Two renderers paint your page — playback vs. preview
7. Fields every element carries
8. The ten element types — one section each
9. The rendering truth of content HTML — the most important section
10. Quick reference — one row per element type
11. Where this sits
12. Hard rules

Reading before writing

read_stage has three depths — detail:"tree", detail:"source" and detail:"text" — and they are not interchangeable.

• inventory strips the markup. Its text is the element's HTML with tags replaced by spaces and whitespace collapsed. A patch built from it invents style values that were never there and deletes the ones that were.
• source always returns the whole page. There is no per-element projection, so array indices cannot drift between what you read and what you write. It returns the full content object — type, schemaVersion and the complete canvas, background, theme and animations included.
• detail:"text" gives you pointers. Each path is that element's own /content/canvas/elements/N, so a residue check hands you the pointer to fix. Note that its text for a latex element is the LaTeX source, for code the lines joined by newlines, and for table the cells joined by |.

The document

A slide scene's content is:

{ type: 'slide', schemaVersion?: number, canvas: Slide }

type and schemaVersion sit outside /content/canvas/ and are therefore not reachable by a slide-canvas patch path — such a pointer begins /content/canvas/. Everything you can write lives under canvas.

The canvas

All of them are patchable. /content/canvas/theme/fontColor, /content/canvas/background/color, /content/canvas/animations/0/duration are ordinary pointer paths. The only two writes the identity guard blocks are changing /content/canvas/id and changing an element's id or type. Optional branches can be created wholesale — set on /content/canvas/background adds the object; remove deletes it again.

Geometry — what a pixel means

viewportSize is the design-space width, not a screen width. Every element's left / top / width / height is in those same design pixels, origin at the top-left of the canvas, x to the right and y downwards. At render time the whole canvas is scaled by one factor to fit its container, so design pixels are proportions in disguise — a width: 500 element is always half the page wide.

Useful constants for the standard page:

• Canvas: 0 ≤ left ≤ 1000, 0 ≤ top ≤ 562.5
• Horizontal centre: left = (1000 - width) / 2
• Vertical centre: top = (562.5 - height) / 2
• Nothing clips at the canvas edge in the DOM, but anything outside the box is cropped in a snapshot/export capture, so off-canvas geometry is a bug.

background

{ type, color?, image?, gradient? }. type is solid | image | gradient.

The renderer resolves it in a fixed order, and a type whose payload is missing falls through to plain white #fff, not to another payload you left behind:

gradient.colors is [{ pos, color }, …] where pos is a percentage number (0–100, written without the %) and color any CSS colour. rotate is degrees.

Setting background.color while type is still 'gradient' changes nothing you can see. The type field is the selector; the payload fields are inert unless type names them.

theme

{ backgroundColor, themeColors[], fontColor, fontName, outline?, shadow? } — all four scalars required.

What the renderer actually does with it: only fontColor and fontName are painted. They are set on the wrapper around every element, so they are the inherited default for any glyph whose own element and inline styles do not override them. theme.backgroundColor is not the page background (that is canvas.background); theme.themeColors, theme.outline and theme.shadow are authoring defaults consumed by the editor when it creates new elements, not by the renderer.

animations

[{ id, elId, effect, type, duration, trigger }, …], type one of in / out / attention, trigger one of click / meantime / auto.

Nothing plays them in playback. Neither renderer reads canvas.animations; the only consumer is the Pro-mode editor's animation panel. They are stored, validated and preserved — treat them as data you must not destroy, never as a way to make something move on a learner's screen. Deleting an element deletes the animations bound to its id for you.

elements is the z-order

Depth is array position: index 0 paints first (bottom), the last element paints last (top). There is no zIndex field, and the renderer assigns the CSS z-index from the array index itself. This is the one change with no leaf to address — see the restacking note below.

How an edit reaches the JSON

For slide canvases, patch_stage exposes five operations.

• set without value fails; remove with a value fails.
• add_element refuses an element that carries an id — identity is the server's. It takes afterId or index, never both; index must be an integer from 0 to the current element count; omit both and the element lands on top.
• Creating an element is a full-element write, not a patch — every DSL-required field for that type must be present (the type sections mark them).

Addressing a field

path is a JSON Pointer rooted at the exact scene returned by read_stage detail:"source", so a slide field begins /content/canvas/. A field you read at /content/canvas/elements/2/left is written back through that same path.

• Address the leaf, not the branch. Give the smallest path that isolates the change. Writing a whole object back is how a neighbouring style field gets silently dropped.
• Array indices are canonical and bounded. 0, 1, 2 — 03, -1, +1 and an index past the end are all rejected.
• Every segment before the last must already exist. The last one need not: set on a key the object does not have yet adds that optional field (giving a text element a fill, a shape a text), and remove deletes it again. remove on a path that is not there fails.
• A path may not cross a scalar. /content/canvas/elements/0/content/0 fails because content is a string, not a container.
• remove on an array index splices the array shorter. There is no insert-at-index for arrays other than rewriting the array whole.
• ~1 and ~0 escape / and ~ inside a key. A bare ~ or ~2 is rejected.
• The value is deep-cloned on the way in, so a nested object you send is stored as its own tree.

Worked examples, one call each:

Z-order has no leaf to address, because paint order is array position. Write /content/canvas/elements whole, carrying every element back unchanged in a new order — the id set and every id→type pairing has to come back identical.

What the structure schema refuses

This is the whole of the enforcement, and a rejected write changes nothing — an error is information, not damage. Every check below runs before anything is stored, and the error message names the offending path.

Pointer-level refusals

1. A slide-canvas path that does not begin /content/canvas/.
2. A malformed ~ escape.
3. A non-canonical array index (03, -1) or one out of bounds.
4. A missing intermediate segment, or a path that crosses a non-container.
5. remove on a key or index that is not there.
6. set without value, or remove carrying one.

Identity refusals (checked on the result of the write)

7. Changing /content/canvas/id.
8. Adding, removing, renaming or duplicating an element id — that is what add_element and delete_element are for.
9. Changing an existing id's type. Turning a text element into a shape is a delete plus an add.
10. add_element with an id in the element, or with both afterId and index.

Schema refusals (the whole canvas is re-validated, at every nesting level)

11. An unknown field anywhere — every object in the contract is closed (additionalProperties: false). A misspelt defaultFontname does not land as a stray key; it fails the call.
12. A wrong type — a string where a number belongs, a number where a string belongs, an object where an array belongs.
13. A value outside a closed union — style: 'double' on a line, a chartType that is not one of the eight, an align that is not in its set.
14. A required field removed — remove on /content/canvas/elements/0/content, on a table's colWidths, on viewportSize, on any theme scalar.
15. A tuple of the wrong arity — viewBox must be exactly two numbers, points exactly two markers, clip.range exactly two pairs.
16. A field on the wrong type — latex on a text element, content on an image.

That list is exhaustive for the write path. Notice what is not on it: no tag check, no CSS check, no colour-format check, no length limit, no geometry bound, no contrast rule, no check that html agrees with latex, no check that a chart's series matches its labels. Those are all yours to get right.

The one thing the server rewrites for you: when a patch changes an element's latex, the server re-renders that element's html snapshot from the new source (KaTeX, display mode, errors rendered rather than thrown) and stores it. If the render returns nothing, html is removed instead. Nothing else in the document is touched, ever.

Two renderers paint your page

The same JSON is drawn by two different implementations, and knowing which is which explains most "it looks right in one place and wrong in another" reports.

They agree on every field that matters most (geometry, fills, precedence, html-over-latex). Where they differ, this manual says so, and the rule is always the same: write for the intersection. The known divergences are

• list markers — restored by the preview renderer's stylesheet, absent in playback (see the HTML section);
• paragraphSpace on a text element — honoured by the preview renderer, inert in playback;
• vAlign on a text element and per-side borders on a table cell — honoured by the preview renderer, ignored in playback;
• a plain-text content with newlines — the preview renderer sets white-space: pre-line when the string contains no markup at all, so the newlines become line breaks; playback does not, so they collapse to spaces;
• audio elements — drawn as a click-to-play button by the preview renderer, not rendered at all in playback;
• an oversized formula — the preview renderer only ever shrinks a formula to fit its box, playback also enlarges it to fill the box.

Fields every element carries

id, left, top, width, height, rotate — all required — plus optional lock, groupId, link { type, target } and name.

• left / top / width / height are canvas px, origin top-left. rotate is degrees, clockwise, about the box centre.
• A line element is the exception: it has no height and no rotate, because its extent and direction come from its endpoints. Patching either onto a line is an unknown-field rejection.
• lock, groupId and name are editor bookkeeping — no renderer reads them. Preserve them; do not expect them to change a pixel.
• link is likewise not painted by either renderer. An element-level hyperlink is stored and exported, not clickable in playback.
• Rotation is applied to a wrapper inside the positioned box, so left / top / width / height always describe the unrotated box. To reason about the visual bounds of a rotated element you have to rotate the rectangle yourself.

The ten element types

text · shape · image · line · chart · table · latex · video · audio · code. They are not interchangeable, and the field that holds an element's words is different in every one of them.

text

Required: content (HTML string), defaultFontName, defaultColor, plus the common geometry.

Words live in content.

The four things that go wrong here

1. defaultColor and defaultFontName are only defaults. They are set on the container, so any inline color / font-family inside content wins by ordinary inheritance. An element whose paragraphs carry color:#C00000 does not change colour when you patch defaultColor. Change the inline span, or change both.
2. The box has 10 px of padding on all four sides, so the usable text area is (width - 20) × (height - 20).
3. height does not clip. The content box is auto-height inside a fixed-height frame with visible overflow, so text longer than the box spills out and can land on top of the element below it. The fill colour and the outline stop at the declared height, which is what makes the overflow obvious once you look. Text that no longer fits needs a smaller font-size or a bigger height, not a hope that it will be cropped.
4. paragraphSpace is inert in playback. Playback sets it as a CSS variable that no rule reads, so stacked <p> tags sit with zero gap. If you need breathing room between paragraphs in playback, put margin-bottom in the <p>'s own inline style.

shape

Required: viewBox [w, h], path (an SVG d), fixedRatio, fill, plus the common geometry.

Fill precedence: pattern beats gradient beats fill. The renderer picks the first one present, in that order. Patching fill on a shape that carries a gradient changes nothing you can see — remove the loser first, or patch the winner.

Geometry. path is in viewBox coordinates; the renderer scales it by width / viewBox[0] and height / viewBox[1]. So resizing a shape means patching width / height and leaving viewBox and path alone — unless the shape has a pathFormula, in which case the path is recomputed from it. Never hand-edit path to resize a shape.

Words live in text.content — a nested ShapeText:

A shape with no text object has no words at all; giving it one means supplying the whole object (content, defaultFontName, defaultColor, align are all required). Horizontal alignment comes from text-align inside the HTML, never from align. The label sits inside 10 px of padding in playback and flush to the box edges in the preview renderer — keep a margin of your own if a tight fit matters.

image

Required: src, fixedRatio, plus the common geometry. No words.

clip.shape is one of rect, rect2, rect3, roundRect, ellipse, triangle, triangle2, triangle3, rhombus, pentagon, hexagon, heptagon, octagon, chevron, point, arrow, parallelogram, parallelogram2, trapezoid, trapezoid2. A name outside that set resolves to nothing and the picture disappears.

src is the pitfall. Anything matching http:, https:, data:, blob:, / or ./ is treated as a concrete address and rendered directly. Anything else is treated as a generation placeholder and the element renders a skeleton, an error box or a disabled badge instead of a picture, depending on whether a generation task exists for that reference. Writing a made-up id into src therefore does not show a picture — it shows a placeholder forever. A real picture comes from the image generation tool, whose returned reference you then store.

Swapping src does not touch the box, so a picture with a different aspect ratio needs width and height re-derived together.

line

Required: start [x, y], end [x, y], style, color, points, plus left, top and width. No height and no rotate. No words.

The control points are checked in the order broken, broken2, curve, cubic and the first one present wins — leaving a stale curve behind while adding a broken means the curve is silently ignored. Remove the loser.

Moving a line means patching left / top; changing its direction or length means patching start / end.

chart

Required: chartType, data, themeColors[], plus the common geometry.

Words live in data.labels[] and data.legends[]; numbers live in data.series[][] — one series row per legend, one entry per label. Relabelling is therefore usually one path for the label and one for its matching series entry (/content/canvas/elements/N/data/labels/2), not a rewrite of data.

How each type reads that dataset:

The two that catch people out: bar is the vertical one and column is the horizontal one — the names are the opposite way round from the shape; and scatter reads two series as coordinate arrays rather than as two data sets.

Two more renderer facts: the legend is only drawn when there is more than one series (pie and ring always draw one), and a chart whose series is missing or empty renders nothing at all — an empty box, not an empty axis.

table

Required: colWidths[], cellMinHeight, outline, data, plus the common geometry.

A cell is { id, colspan, rowspan, text, style?, padding?, vAlign?, borders? }. id, colspan, rowspan and text are all required — a normal cell is colspan: 1, rowspan: 1. style may carry bold, em, underline, strikethrough, color, backcolor, fontsize (a string with its unit), fontname, align (left / center / right / justify).

Words live in data[row][col].text. One cell is one path: /content/canvas/elements/5/data/0/0/text. Address the cell's text and never the row or the grid, and every id, colspan, rowspan and per-cell style around it survives untouched — a colspan you drop takes the table's shape with it.

Cell text is its own dialect. Playback runs the cell's text through a transform before injecting it as HTML: every \n becomes <br/> and every space becomes  . That has three consequences you must design around:

1. \n in a cell is a line break — the one pl

…(truncated)