slide-dsl

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
name: slide-dsl
title: "页面数据结构"
description: The complete slide DSL manual — the canvas and its background, the ten element types field by field with units, defaults and legal values, where each type keeps its words, which field the renderer actually paints when two disagree, exactly what happens to the HTML you put in `content`, and the structure schema that is now the ONLY thing a write is checked against. Nothing filters your markup and nothing normalises your values, so this manual is the whole of what makes a page render correctly. Load it before patching a field you have not patched before, when a patch comes back rejected, when a patch lands but nothing moves on screen, or when you need to know where a colour, a font, a table cell or a code line really lives. This is a field reference and not a procedure — `page-clone` and `pro-editing` decide which pages to touch, `slide-craft` decides what a good page looks like, and this one says what the JSON means.
---

# 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](#reading-before-writing) — the three read depths
2. [The document](#the-document) — `content` → `canvas`
3. [The canvas](#the-canvas) — viewport, theme, background, animations, paint order
4. [How an edit reaches the JSON](#how-an-edit-reaches-the-json) — three ops, pointer rules
5. [What the structure schema refuses](#what-the-structure-schema-refuses) — the only hard boundary
6. [Two renderers paint your page](#two-renderers-paint-your-page) — playback vs. preview
7. [Fields every element carries](#fields-every-element-carries)
8. [The ten element types](#the-ten-element-types) — one section each
9. [The rendering truth of `content` HTML](#the-rendering-truth-of-content-html) — the most important section
10. [Quick reference](#quick-reference) — one row per element type
11. [Where this sits](#where-this-sits)
12. [Hard rules](#hard-rules)

## Reading before writing

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

| `detail`        | What comes back                                                                                              | Use it for                                        |
| --------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
| `inventory` (default) | One compact line per element — `id`, `type`, plain-text `text`, `left`, `top`, `width`, `height`, `src` | Finding an element. **Never** as a patch source.  |
| `source`        | The exact persisted page JSON — the root every patch path is written against                                   | Every patch. Read it again after a write.         |
| `text`          | Every text-bearing element as `{ path, id, type, te