page-clone

name	page-clone
title	页面克隆
description	Building one page that looks like a page the course already has — copy the model page with `duplicate_scene`, then rewrite the copy's words with one `patch_stage` op per content slot. Use when a new page has to inherit an existing page's design, whether the model page came from an imported deck or the course wrote it earlier. Not for revising a page that is already the page you want (that is `pro-editing`), and not for the course-level work of cataloguing layouts and assigning one per outline entry (that is `style-clone`).

Cloning one page's design

The design already exists on another page. Your job is to put new content into that design without redrawing it: copy the page, then swap what it says.

Copy-then-edit is the only clone path in this runtime. generate_scene always re-rolls a page from its outline entry — the model invents a fresh element tree every time — so calling it on a copied page destroys exactly the design you came for. Nothing here validates the shape of your result either: the design is preserved because you copied it, and the judgement about which elements are content and which are the skeleton is yours.

The sequence

1. duplicate_scene({ templateSceneId, targetOrder, title }) — an exact copy of the model page at the position you want (templateOrder works too, but an id is safer). The copy carries the full content, no narration actions, and a new outline entry. Pass a title that names the NEW page; the entry inherits the model page's brief, and a copy still called 「第 3 章回顾」 misleads both the learner and the narration step.
2. Read the copy with read_stage, path:/scenes/<order|id>, detail:"source" — this is your address space and your fidelity source. It returns the whole page's persisted JSON, including raw content HTML, inline spans, fonts, colours, fills, shadows, geometry and z-order, and it is the root your patch paths are written against: a field you read at /content/canvas/elements/2/content is written back through that same path. Copy unchanged markup and style fields from this result; do not reconstruct them from stripped text.
3. Decide, element by element, what each one is. Content slots are the ones whose words belong to the old subject. Skeleton is everything else — rules, bands, page numbers, logos, decorative shapes, background art — and it stays untouched even when it holds text.
4. Call patch_stage once per content slot, with op:"set" on the exact path that holds that slot's words — /content/canvas/elements/3/content for a paragraph, /content/canvas/elements/5/data/0/0/text for a table cell. One leaf per call: everything you do not name keeps the value you copied. slide-dsl is the manual for which field holds the words in each element type. Do not patch geometry or style paths while cloning — they ARE the design you copied.
5. Read the copy with read_stage detail:"text" after the edits. It returns every text-bearing element as { path, id, type, text } plus a page-wide combinedText, so you read the whole page's words in one call and get the pointer to fix with them. Search it for source-topic residue; the read reports, and you decide what is stale, then set, remove, or delete_element it.
6. generate_actions on the copy to give it narration (audio is on by default). A duplicated page arrives silent.

Work one page at a time and re-read before you edit. Every patch_stage result already carries the page's fresh inventory, so a run of edits on the same page needs one read_stage call at the start, not one per call.

Where a change goes

For a cloned slide, patch_stage uses set, remove, str_replace, add_element, and delete_element; for cloning the usual choice is set on the smallest content leaf. The only question is which path carries the change.

Need	Call	What really happens
New words in a text block	set /content/canvas/elements/N/content	Stores your HTML byte for byte — nothing filters it; preserve the source element's <span> marks and inline styles while changing the words
New words in a shape's label	set /content/canvas/elements/N/text/content	Only the label's HTML moves; font, colour, vertical alignment, line height, shape fill and path all stay
One table cell	set /content/canvas/elements/N/data/0/0/text	One cell's plain text; every other cell, id, colspan, rowspan and per-cell style is untouched
One line of code	set /content/canvas/elements/N/lines/1/content	One line's text, with every line id kept — language, filename, font size and box survive
A formula	set /content/canvas/elements/N/latex	Replaces the source and re-renders the cached KaTeX html the renderer actually paints
A chart label or number	set /content/canvas/elements/N/data/labels/2	One entry; keep labels, legends and series dimensionally consistent
A different image	set /content/canvas/elements/N/src	Points the element at another source. It never creates a picture — get a real src from generate_image first, and keep the original rather than invent a URL
Nudge a box	set /content/canvas/elements/N/left (or top / width / height)	One number at a time. On a cloned page this is a repair, not a step
Drop an optional field	remove /content/canvas/elements/N/fill	Deletes that key. on a path that is not there fails, and so does removing a required field

Three properties make this safe to lean on, and all three are worth knowing before you do: only the path you name changes, identity is not patchable (the id set and each id's type must come back identical, which is why adding or removing an element has its own op), and a rejected patch changes nothing — a bad path, an unknown field, unsafe HTML or an invalid result fails loud with the page as it was. Nothing normalises your colours or fonts toward a house style either, which is the property that makes a copied design survive editing at all.

The content rule is simple: source HTML in, source HTML out. Change the text inside the returned paragraphs and spans; do not flatten the block to plain text or synthesize fresh styling. For lists, keep one <p> per item with the marker in the text (slide-craft explains why <ul> does not render its markers here).

When a cloned page needs one more slot, the cheapest honest source is an element already on it: read its JSON and add_element a copy with the words and box you want. add_element is full fidelity, so its caller supplies every geometry and style field — which is why an existing element is a better starting point than a blank one, and why this is the last resort rather than a step.

When the new content does not fit the layout

This is the normal case, not an error: a layout with three bullet slots and content with seven points is a mismatch you resolve, and no tool will resolve it for you. In order of preference:

1. Cut the content to the layout's capacity. A borrowed layout is a statement about how much can be said on one page. Tightening the expression preserves the design; growing the page destroys it.
2. Split across two clones. Duplicate the model page again and carry the remainder onto the second copy. Two pages in the deck's own form beat one overstuffed page.
3. Pick a roomier model page. If the course has a layout built for more content, clone that one and abandon this copy (edit_deck delete).
4. Grow the layout, only as a last resort — add_element a copy of the closest content element, with its box set into the rhythm of the ones around it (match their left edge and spacing exactly, taken from the source boxes) and the new words already in it. You are now drawing, and it shows if you are careless.

Fewer content slots than the layout has is the easier direction: fill what you can meaningfully fill and delete_element the rest. Never leave a template's words standing on the page. A slot you neither replaced nor deleted is a bug — the old subject leaking into the new one — and a detail:"text" read with read_stage detail:"text" is the sweep that catches it before shipping.

Overflow discipline

Text sized for the model page's words is not sized for yours. Aim for the same order of magnitude as the text you replaced — that length was chosen for that box, and it is the only sizing information you have. When your replacement runs much longer, shorten the wording rather than resizing the box.

Verify with render_scene_preview when it is registered, and spend the calls where they buy something: the first page you clone from a given model page, and any later clone whose text is visibly longer than what it replaced. Skip it otherwise; previews cost calls. If a page overflows, load pro-editing and converge inside its budget of two preview rounds — shorten text first, and set a box only when the text is already tight. If two rounds have not converged, move the content to a roomier layout or name the page to the user. Do not ship a page with text running off it.

Finish the page

generate_actions on the copy, with a styleDirective when the surrounding pages have a register worth matching. Narration is written from the page's persisted content plus its outline entry, and that entry's brief came from the model page — so the content you just wrote has to be unambiguous on its own, and the title has to be the new page's title. Then read the result back with read_stage detail:"source" and check both halves of the result: every speech action carries an audioId, and every speech line is about this page's subject rather than the model page's — a narrated wrap-up or a topic name inherited from the brief is residue exactly as template words on the slide are. Repair it with patch_stage on that action's /actions/N/text pointer, then generate_tts the page so the audio matches the words.

Where this sits

• style-clone governs the course-level job: reading an imported deck as a library of layouts, classifying them, and assigning one to each outline entry. It calls into this skill for the per-page mechanics.
• slide-dsl is the field manual for the JSON you are patching — the ten element types, which field holds the words in each, what values are legal, and what the renderer really does with the HTML you write. Load it when you are about to patch a field you have not patched before, or when a patch comes back rejected.
• pro-editing governs editing a page that is already the page you want. Load it when a clone comes out wrong, and follow its preview budget.
• slide-craft is the design law the replacement content has to satisfy — the height table, the type scale, contrast pairs, how rich text really renders. Load it when a slot needs more than a like-for-like sentence swap.
• stage-design still governs the build of the stage as a whole.

Hard rules

• Copy, then edit. Never generate_scene on a copied page. It re-rolls the element tree from the outline entry and the borrowed design is gone.
• Content changes; design does not. No geometry path, no style path, no new element and no restacking while cloning, unless the layout genuinely has to grow and you have read the neighbouring boxes first.
• Every element ends up replaced, deliberately kept, or deleted. No template words survive by accident.
• Always run the text sweep. read_stage detail:"text" returns every element's words plus one combinedText; read all of it, and fix what it turns up at the path it hands you. The read reports — it never decides or edits.
• Facts do not travel with the layout. Text carried over from the model page is a claim in its new context; if it belongs to the old subject, it goes.
• One page at a time. duplicate_scene, then that page's edits, then its actions — then the next page. Each write persists as it lands.