@elytracms/studio 0.0.99 → 0.0.101

package/dist/components/builder/reuse.d.ts

@@ -2,6 +2,8 @@ import type { ComponentManifest } from '@elytracms/core/component-registry';
 import type { CmsDocument, CollectionDef, DocumentRef, LocaleConfig } from '@elytracms/core/cms-core';
 import type { ComponentNode, PlacementScope, PlacementVerdict } from '@elytracms/core/project-graph';
 import type { CustomizationIssue } from '@elytracms/core/studio-core';
+import type { DeleteCreatedOutcome } from '../../lib/operations/cms-persistence.js';
+import type { CanvasHistoryEffect } from './builder-store.js';
 /**
  * The reuse capability (EC-282): the engine-generic description of how a project
  * models reusable elements. **AD-a (EC-467): reusable elements are SINGULAR per
@@ -9,40 +11,22 @@ import type { CustomizationIssue } from '@elytracms/core/studio-core';
  * Multiple reuse collections are deliberately not supported, which is why this is
  * one value and never a list.
  *
- * The capability is normally DERIVED from config (manifests + collections) — no
- * declaration needed, so a consumer that already has a transcluding embed gets the
- * in-canvas gestures for free (the EC-296 "works automatically" pattern). The
- * derivation predicate for a "reusable embed" component: it contributes no slots of
- * its own and has exactly ONE `relation` prop (cardinality `one`) whose target
- * collection holds a `blocks` field — i.e. it embeds a single document and renders
- * that document's composition by transclusion (EC-254/EC-281). For Konditorei that
- * is uniquely `project.Reusable` → `element` → `reusable.content`.
+ * **EC-728 (owner ruling 2026-10-31, "Declare, never infer"): the capability exists
+ * only when the project DECLARES its embed** — `defineStudio({ reuse: { component } })`
+ * ({@link StudioReuseConfig}). The engine never guesses one from a component's shape.
+ * The shape test it used to run (no slots, exactly one cardinality-one `relation`
+ * prop whose target collection holds a `blocks` field) cannot tell an embed from an
+ * ordinary card that links to a page with a canvas: EC-462 refused the guess when two
+ * components matched, and EC-728 measured the one-candidate guess crowning a "read
+ * next" link card — *Make reusable* then moved a block's content into a new document
+ * and left a link card in its place. A guess with a destructive gesture attached is
+ * the bug, so there is no guess.
  *
- * EC-462 — the predicate additionally DISQUALIFIES a candidate whose own manifest
- * explicitly declares its relation prop to be something other than an embed
- * pointer. The shape test alone proved unsound the moment a relation prop's
- * target collection gains a `blocks` field of its own (a category/page with a
- * canvas — a completely natural content shape): the EC-276 sprint's ProductGrid
- * and the demo's OptionBox were both claimed as "the embed", so their ordinary
- * relation picks rendered the reusable-element placeholder, grew Detach/Make-
- * reusable gestures, and fed embed-worded publish-integrity issues. Two
- * explicit-declaration disqualifiers close the observed class:
- *
- * - a manifest with a `listing` declaration is a QUERY host (EC-255) — its
- *   relation prop feeds the query (a `{ prop }` operand of `listing.where`),
- *   never a transclusion pointer;
- * - a relation prop with `form.hidden` (predicate or `true`) is conditional/
- *   auxiliary — EC-394 strips a hidden relation's ref at publish, so it cannot
- *   coherently be what the component transcludes.
- *
- * Both read only the CANDIDATE manifest's own declarations (never the target's
- * contents) and can only EXCLUDE, so a genuine pure embed (which declares
- * neither) is always kept. EC-462's residual — a bare unconditional
- * single-relation display component (e.g. a page teaser) is at rest
- * indistinguishable from a genuine embed — is closed by EC-467's optional
- * {@link StudioReuseConfig} declaration: a project that hits ambiguity declares
- * its way out, and the ambiguity is LOUD instead of silently disabling the
- * gestures. See {@link resolveReuse}.
+ * What the capability drives (and therefore what an undeclared project does not get):
+ * the in-canvas gestures (*Make reusable* / *Detach to local copy*), the canvas
+ * placeholder for an embed whose target is a draft or missing (EC-300), and the reuse
+ * config issues. Transclusion itself does not depend on it — the runtime renderer
+ * injects `renderBlocks` for every manifest that consumes relations.
  */
 export interface ReuseCapability {
     /** The embed component, e.g. `project.Reusable`. */
@@ -57,8 +41,8 @@ export interface ReuseCapability {
     contentCardinality: 'one' | 'many';
 }
 /**
- * EC-467 (AD-b) — the OPTIONAL studio-config declaration of the reuse embed:
- * `defineStudio({ reuse: { component: 'project.Reusable' } })`. See
+ * EC-467 (AD-b) → EC-728 — THE declaration of the reuse embed (absent: the project has
+ * no reusable elements): `defineStudio({ reuse: { component: 'project.Reusable' } })`. See
  * {@link import('../app-views/studio-config').StudioConfig.reuse} for the
  * consumer-facing contract; this is the shape {@link resolveReuse} consumes.
  *
@@ -78,16 +62,17 @@ export interface StudioReuseConfig {
 }
 /**
  * EC-467 — the resolution of the project's reuse capability: the capability (or
- * `null`), plus the config issues a developer must SEE.
+ * `null`), plus the config issues a developer must SEE (a declaration that cannot
+ * resolve).
  *
  * The issues ride the EC-236 {@link CustomizationIssue} surface (`point: 'reuse'`),
- * exactly like the sidebar's and the field renderers' — so they render at the
- * studio rail foot on every surface, which is the studio's home for
+ * exactly like the sidebar's and the field renderers' — so they render in the header
+ * Issues popover on every surface (EC-690's one issues tray), the studio's home for
  * project-CONFIGURATION problems (the document-scoped Issues pane is the wrong
  * home: this is not a content problem in one document).
  *
  * EC-478: each issue carries a `messageRef` (catalog key + identifier values)
- * alongside its prebuilt English, so the rail foot renders it in the active UI
+ * alongside its prebuilt English, so the tray renders it in the active UI
  * locale. This module stays pure — it names a key, it never calls `translate`;
  * `lib/persona/labels.ts` resolves it at the render site. That is what makes the
  * whole list localize together, which is the mixed-language outcome EC-467
@@ -95,41 +80,30 @@ export interface StudioReuseConfig {
  */
 export interface ReuseResolution {
     capability: ReuseCapability | null;
-    /** Empty whenever the capability is unambiguous — including "this project has none". */
+    /** Empty whenever the declaration resolves — and when there is none ("this project has none"). */
     issues: CustomizationIssue[];
 }
 /**
- * The components whose SHAPE makes them plausible reuse embeds (the zero-config
- * heuristic + EC-462's disqualifiers), in manifest order. Exported for the tests
- * and for issue copy; the resolution rule lives in {@link resolveReuse}.
- */
-export declare function inferredEmbedCandidates(manifests: readonly ComponentManifest[], collections: readonly CollectionDef[]): ReuseCapability[];
-/**
- * Resolve the project's ONE reuse capability (AD-a) plus any config issues —
- * EC-467's full matrix (AD-c):
- *
- * | Declaration | Candidates | Result |
- * | --- | --- | --- |
- * | present, resolves | any | the declared capability, no issue |
- * | present, does not resolve | any | `null` + an ERROR issue (misconfiguration) |
- * | absent | exactly 1 | that candidate, no issue (the zero-config default) |
- * | absent | 2 or more | `null` + a WARNING issue naming every candidate |
- * | absent | 0 | `null`, **no issue** — a project need not use reusable elements |
+ * Resolve the project's ONE reuse capability (AD-a) plus any config issues — EC-728's
+ * matrix (declare, never infer):
  *
- * Severity is the honest split: a declaration that cannot resolve is broken
- * config the developer asked for (error); inference ambiguity is nothing broken —
- * the engine declines to guess and asks for one line (warning). Both disable the
- * gestures, and both render identically in the rail's issue list.
+ * | Declaration | Result |
+ * | --- | --- |
+ * | present, resolves | the declared capability, no issue |
+ * | present, does not resolve | `null` + an ERROR issue (misconfiguration) |
+ * | absent | `null`, **no issue** — the project has no reusable elements |
  *
- * The zero-candidate row is deliberately silent: crying wolf at every project
- * that has no reusable elements would train developers to ignore the surface.
+ * The absent row is deliberately silent: a project need not use reusable elements,
+ * and naming a component that "looks like an embed" would be the guess again, as
+ * advice (EC-728). An unresolvable declaration disables the gestures and is reported
+ * once, in the header Issues popover.
  */
 export declare function resolveReuse(manifests: readonly ComponentManifest[], collections: readonly CollectionDef[], declaration?: StudioReuseConfig): ReuseResolution;
 /**
- * The project's reuse capability alone, or `null` when it is absent, ambiguous, or
+ * The project's reuse capability alone, or `null` when it is undeclared or
  * misdeclared — for callers that act on the capability and do not surface config
- * issues themselves (the publish-integrity walk). The issues are surfaced ONCE, by
- * the shell rail; see {@link resolveReuse}.
+ * issues themselves (the gestures, the canvas placeholder). The issues are surfaced
+ * ONCE, by the shell; see {@link resolveReuse}.
  */
 export declare function resolveReuseCapability(manifests: readonly ComponentManifest[], collections: readonly CollectionDef[], declaration?: StudioReuseConfig): ReuseCapability | null;
 /** A slug for `name`, suffixed `-2`/`-3`/… until it is free among `taken`. */
@@ -137,7 +111,7 @@ export declare function uniqueSlug(name: string, taken: ReadonlySet<string>): st
 /**
  * The values for a new reusable document promoted from `node` (EC-282): seeded
  * defaults, the given `name` on the title field, the node on the content field,
- * and a collision-safe slug on any UNIQUE text field (e.g. Konditorei's
+ * and a collision-safe slug on any UNIQUE text field (e.g. a production site's
  * `internalId`) so the created document is publish-valid without hardcoding that
  * field's name. Other required fields, if any, are completed by the editor when
  * they open the new reusable.
@@ -155,7 +129,16 @@ export declare function buildReusableValues(collection: CollectionDef, capabilit
  * whose target doesn't resolve (→ placeholder) without reaching into prop internals.
  */
 export declare function reuseEmbedRef(node: ComponentNode, capability: ReuseCapability): DocumentRef | null;
-/** The `Reusable` embed node referencing the new document (id minted by the action). */
+/**
+ * The `Reusable` embed node referencing the new document (id minted by the action).
+ *
+ * EC-728 — CANONICAL from the first write: the prop is core's `staticProp` (bare `{ value }`,
+ * EC-312), never `{ kind: 'static', value }`. The canvas commits its node patches raw, while
+ * the draft takes the same write through the self-typing lens, which strips a redundant
+ * `kind`; a non-canonical node therefore made the two views of the canvas field disagree, the
+ * draft reported the disagreement as a change made underneath the canvas, and the rebase
+ * dropped *Make reusable*'s own undo step (`reuse-undo.test.ts`).
+ */
 export declare function makeEmbedNode(capability: ReuseCapability, documentId: string): ComponentNode;
 /**
  * Why a reuse gesture is refused before it does anything: the one core placement
@@ -205,7 +188,11 @@ export declare function detachRefusal(args: {
 export interface PromoteEffects {
     newDocumentId(): string;
     insertDocument(doc: CmsDocument): void;
-    replaceInCanvas(nodeId: string, embed: ComponentNode): void;
+    /**
+     * The in-place swap — ONE history entry carrying `effect` (EC-728: the created document, so
+     * Undo can remove it when that is safe and Redo can re-insert it).
+     */
+    replaceInCanvas(nodeId: string, embed: ComponentNode, effect: CanvasHistoryEffect): void;
     /** Publish the new reusable; resolves `true` only when the document IS published afterwards. */
     publish(ref: DocumentRef): Promise<boolean>;
     refused(refusal: ReuseRefusal): void;
@@ -216,8 +203,9 @@ export interface PromoteEffects {
 /**
  * Run "Make reusable" (EC-282) — the preflight first (EC-584: a refusal creates,
  * publishes and replaces NOTHING), then ONE insert-if-absent create of the reusable
- * document (EC-595 A2), the in-place swap for the embed, and the chosen publish,
- * whose success notice is shown only when the document is actually published.
+ * document (EC-595 A2), the in-place swap for the embed — one canvas history entry that
+ * records the created document (EC-728) — and the chosen publish, whose success notice is
+ * shown only when the document is actually published.
  */
 export declare function runPromote(args: {
     root: ComponentNode;
@@ -235,3 +223,51 @@ export declare function runPromote(args: {
     canvasFieldLabel: string;
     effects: PromoteEffects;
 }): Promise<'refused' | 'draft' | 'published' | 'publish-failed'>;
+/**
+ * What Undo did with the document *Make reusable* created: `deleted`, or already `gone`, or
+ * KEPT — because it is `published`, was `edited` since it was made, is `referenced` elsewhere,
+ * or the removal `failed`. The block is restored in every case (the canvas entry is a snapshot).
+ */
+export type PromoteUndoOutcome = 'deleted' | 'gone' | 'published' | 'edited' | 'referenced' | 'failed';
+/** The authoritative reads and the one write Undo needs — injected, so every branch is testable. */
+export interface PromoteUndoDeps {
+    /** Await every queued write: the page's restored value lands before anything is judged. */
+    flush(): Promise<void>;
+    /** The document's record now (`undefined`: it no longer exists). */
+    read(ref: DocumentRef): Promise<{
+        published: boolean;
+    } | undefined>;
+    /** How many reference-index entries (draft or published, any document) point at it now. */
+    referrers(ref: DocumentRef): Promise<number>;
+    /** The conditional delete — at the revision this session's create landed at (`CmsPersister.deleteCreated`). */
+    deleteCreated(ref: DocumentRef): Promise<DeleteCreatedOutcome>;
+}
+/**
+ * EC-728 — Undo of *Make reusable*, the document side. The created document is deleted ONLY
+ * when every authoritative fact at Undo time says nobody else has it: never published (the
+ * record), referenced nowhere — after the page's own restore has landed — (the reference
+ * index, both variants), and unchanged since its create (the delete's revision precondition,
+ * checked by the store in its own step, which also refuses a strict referrer). Anything else
+ * keeps it, with the reason. A read that throws keeps it too: an unproven fact never deletes.
+ */
+export declare function undoPromote(effect: CanvasHistoryEffect, deps: PromoteUndoDeps): Promise<PromoteUndoOutcome>;
+/** The catalog keys of the kept-document notices (EN + DE in the studio catalogs). */
+export type ReuseUndoNoticeKey = 'builder.reuse.undoKeptPublished' | 'builder.reuse.undoKeptEdited' | 'builder.reuse.undoKeptReferenced' | 'builder.reuse.undoKeptFailed';
+/** The notice for a KEPT document (EC-728 — it names the document and why); none when it went. */
+export declare function undoPromoteNotice(outcome: PromoteUndoOutcome): ReuseUndoNoticeKey | undefined;
+/**
+ * EC-728 — the document side of every Undo/Redo that crosses a *Make reusable* step, for one
+ * canvas. Crossings run strictly in order (a Redo waits for the Undo before it), so a fast
+ * Undo → Redo never re-inserts a document whose removal is still in flight. Redo re-inserts
+ * (the same id, insert-if-absent) exactly the documents ITS Undo removed or found gone — never
+ * one Undo kept (it is still there) — and the canvas entry re-swaps the embed.
+ */
+export declare function createPromoteHistory(deps: PromoteUndoDeps & {
+    insert(document: CmsDocument): void;
+    notify(key: ReuseUndoNoticeKey, name: string): void;
+}): {
+    crossed(step: {
+        direction: 'undo' | 'redo';
+        effect: CanvasHistoryEffect;
+    }): Promise<void>;
+};

package/dist/components/builder/reuse.js

@@ -1,6 +1,6 @@
-import { manifestPropFields, manifestSlots } from '@elytracms/core/component-registry';
-import { fieldAllowList, itemLimit, readDocumentRef, referenceNode, seedDefaults, titleFieldOf, writeField, } from '@elytracms/core/cms-core';
-import { editBlockRoots, isStaticProp, replacePlacementRefusal, valuePlacementRefusal } from '@elytracms/core/project-graph';
+import { manifestPropFields } from '@elytracms/core/component-registry';
+import { documentKey, fieldAllowList, itemLimit, readDocumentRef, referenceNode, seedDefaults, titleFieldOf, writeField, } from '@elytracms/core/cms-core';
+import { editBlockRoots, isStaticProp, replacePlacementRefusal, staticProp, valuePlacementRefusal, } from '@elytracms/core/project-graph';
 import { slugify } from '../../lib/utils.js';
 import { fieldLabel } from '../cms/cms-labels.js';
 /** The customization point name stamped onto every reuse issue (EC-236 locator). */
@@ -11,13 +11,7 @@ function relationPropsOf(manifest) {
     for (const field of manifestPropFields(manifest)) {
         if (field.type !== 'relation')
             continue;
-        const hidden = field.form?.hidden;
-        props.push({
-            name: field.name,
-            target: field.target,
-            multiple: field.multiple === true,
-            conditional: hidden !== undefined && hidden !== false,
-        });
+        props.push({ name: field.name, target: field.target, multiple: field.multiple === true });
     }
     return props;
 }
@@ -47,7 +41,6 @@ const REUSE_KEYS = {
     ambiguousRelationProp: 'builder.reuse.config.ambiguousRelationProp',
     unknownCollection: 'builder.reuse.config.unknownCollection',
     noBlocksField: 'builder.reuse.config.noBlocksField',
-    ambiguousInference: 'builder.reuse.config.ambiguousInference',
 };
 function reuseIssue(code, severity, message, messageRef, id) {
     return {
@@ -64,54 +57,11 @@ function quotedList(names) {
     return names.map((name) => `"${name}"`).join(', ');
 }
 /**
- * The components whose SHAPE makes them plausible reuse embeds (the zero-config
- * heuristic + EC-462's disqualifiers), in manifest order. Exported for the tests
- * and for issue copy; the resolution rule lives in {@link resolveReuse}.
- */
-export function inferredEmbedCandidates(manifests, collections) {
-    const matches = [];
-    for (const manifest of manifests) {
-        // EC-591 (COMPOSITION #15): the DERIVED slots — a `blocks` prop is a child
-        // region (`manifestSlots`), so a manifest with `slots: []` and a blocks prop is
-        // NOT slot-less; reading raw `manifest.slots` inferred it as a reuse embed.
-        if (manifestSlots(manifest).length > 0)
-            continue;
-        // EC-462: a `listing` manifest is a query host by its own declaration — its
-        // relation prop is the filter source, never an embed pointer.
-        if (manifest.listing)
-            continue;
-        // The heuristic requires the relation to be UNAMBIGUOUS within the manifest:
-        // exactly ONE relation prop of any kind, which must then be targeted,
-        // cardinality-one and unconditional. (Counting all relation props — not just
-        // the embeddable ones — is deliberate: a component with a second, list-valued
-        // relation is not the single-purpose shape the heuristic is allowed to claim.)
-        const relations = relationPropsOf(manifest);
-        const relation = relations.length === 1 ? relations[0] : undefined;
-        if (!relation || relation.target === undefined || relation.multiple || relation.conditional)
-            continue;
-        const collection = collections.find((c) => c.id === relation.target);
-        if (!collection)
-            continue;
-        const blocksField = blocksFieldOf(collection);
-        if (!blocksField)
-            continue;
-        matches.push({
-            embedComponentId: manifest.id,
-            relationProp: relation.name,
-            collectionId: collection.id,
-            contentField: blocksField.name,
-            contentCardinality: itemLimit(blocksField) === 1 ? 'one' : 'many',
-        });
-    }
-    return matches;
-}
-/**
- * Resolve the DECLARED embed (EC-467, AD-b). An explicit declaration is the
- * developer's authority, so the inference disqualifiers are NOT applied here: a
- * declared component may have slots, may declare `listing`, and its relation prop
- * may be `form.hidden` — those exist to stop the engine GUESSING, not to overrule
- * a stated intent. Only structural impossibilities are issues (see AD-c row 2):
- * an unknown component id, no usable relation prop (or an ambiguous set with no
+ * Resolve the DECLARED embed (EC-467, AD-b). The declaration is the developer's
+ * authority: a declared component may have slots, may declare `listing`, and its
+ * relation prop may be `form.hidden` — the engine does not second-guess a stated
+ * intent. Only structural impossibilities are issues (see AD-c row 2): an unknown
+ * component id, no usable relation prop (or an ambiguous set with no
  * `relationProp`), an undefined target collection, or a target with no `blocks`
  * field — each of which would leave nothing coherent to transclude.
  */
@@ -126,7 +76,7 @@ function resolveDeclaredReuse(declaration, manifests, collections) {
         return {
             capability: null,
             issues: [
-                reuseIssue('unknown-override-target', 'error', `Reusable elements: studio config declares reuse.component "${component}", which is not a registered component. Fix the id, or remove the reuse block to let the studio infer the embed.`, { key: REUSE_KEYS.unknownComponent, vars: { component } }, component),
+                reuseIssue('unknown-override-target', 'error', `Reusable elements: studio config declares reuse.component "${component}", which is not a registered component. Fix the id to name your embed component — until then the reuse gestures are off.`, { key: REUSE_KEYS.unknownComponent, vars: { component } }, component),
             ],
         };
     }
@@ -181,51 +131,30 @@ function resolveDeclaredReuse(declaration, manifests, collections) {
     };
 }
 /**
- * Resolve the project's ONE reuse capability (AD-a) plus any config issues —
- * EC-467's full matrix (AD-c):
- *
- * | Declaration | Candidates | Result |
- * | --- | --- | --- |
- * | present, resolves | any | the declared capability, no issue |
- * | present, does not resolve | any | `null` + an ERROR issue (misconfiguration) |
- * | absent | exactly 1 | that candidate, no issue (the zero-config default) |
- * | absent | 2 or more | `null` + a WARNING issue naming every candidate |
- * | absent | 0 | `null`, **no issue** — a project need not use reusable elements |
+ * Resolve the project's ONE reuse capability (AD-a) plus any config issues — EC-728's
+ * matrix (declare, never infer):
  *
- * Severity is the honest split: a declaration that cannot resolve is broken
- * config the developer asked for (error); inference ambiguity is nothing broken —
- * the engine declines to guess and asks for one line (warning). Both disable the
- * gestures, and both render identically in the rail's issue list.
+ * | Declaration | Result |
+ * | --- | --- |
+ * | present, resolves | the declared capability, no issue |
+ * | present, does not resolve | `null` + an ERROR issue (misconfiguration) |
+ * | absent | `null`, **no issue** — the project has no reusable elements |
  *
- * The zero-candidate row is deliberately silent: crying wolf at every project
- * that has no reusable elements would train developers to ignore the surface.
+ * The absent row is deliberately silent: a project need not use reusable elements,
+ * and naming a component that "looks like an embed" would be the guess again, as
+ * advice (EC-728). An unresolvable declaration disables the gestures and is reported
+ * once, in the header Issues popover.
  */
 export function resolveReuse(manifests, collections, declaration) {
-    if (declaration)
-        return resolveDeclaredReuse(declaration, manifests, collections);
-    const candidates = inferredEmbedCandidates(manifests, collections);
-    if (candidates.length === 1)
-        return { capability: candidates[0], issues: [] };
-    if (candidates.length === 0)
+    if (!declaration)
         return { capability: null, issues: [] };
-    return {
-        capability: null,
-        issues: [
-            reuseIssue('ambiguous-inference', 'warning', `Reusable elements: ${candidates.length} components have the reusable-embed shape (${quotedList(candidates.map((c) => c.embedComponentId))}). A project has exactly one reusable-element embed, so the studio will not guess — declare it in studio.config as reuse: { component: '<id>' }. Until then the reuse gestures are off.`, {
-                key: REUSE_KEYS.ambiguousInference,
-                vars: {
-                    count: candidates.length,
-                    components: quotedList(candidates.map((c) => c.embedComponentId)),
-                },
-            }),
-        ],
-    };
+    return resolveDeclaredReuse(declaration, manifests, collections);
 }
 /**
- * The project's reuse capability alone, or `null` when it is absent, ambiguous, or
+ * The project's reuse capability alone, or `null` when it is undeclared or
  * misdeclared — for callers that act on the capability and do not surface config
- * issues themselves (the publish-integrity walk). The issues are surfaced ONCE, by
- * the shell rail; see {@link resolveReuse}.
+ * issues themselves (the gestures, the canvas placeholder). The issues are surfaced
+ * ONCE, by the shell; see {@link resolveReuse}.
  */
 export function resolveReuseCapability(manifests, collections, declaration) {
     return resolveReuse(manifests, collections, declaration).capability;
@@ -241,7 +170,7 @@ export function uniqueSlug(name, taken) {
 /**
  * The values for a new reusable document promoted from `node` (EC-282): seeded
  * defaults, the given `name` on the title field, the node on the content field,
- * and a collision-safe slug on any UNIQUE text field (e.g. Konditorei's
+ * and a collision-safe slug on any UNIQUE text field (e.g. a production site's
  * `internalId`) so the created document is publish-valid without hardcoding that
  * field's name. Other required fields, if any, are completed by the editor when
  * they open the new reusable.
@@ -285,17 +214,23 @@ export function reuseEmbedRef(node, capability) {
     const ref = isStaticProp(prop) ? readDocumentRef(prop.value) : undefined;
     return ref ?? null;
 }
-/** The `Reusable` embed node referencing the new document (id minted by the action). */
+/**
+ * The `Reusable` embed node referencing the new document (id minted by the action).
+ *
+ * EC-728 — CANONICAL from the first write: the prop is core's `staticProp` (bare `{ value }`,
+ * EC-312), never `{ kind: 'static', value }`. The canvas commits its node patches raw, while
+ * the draft takes the same write through the self-typing lens, which strips a redundant
+ * `kind`; a non-canonical node therefore made the two views of the canvas field disagree, the
+ * draft reported the disagreement as a change made underneath the canvas, and the rebase
+ * dropped *Make reusable*'s own undo step (`reuse-undo.test.ts`).
+ */
 export function makeEmbedNode(capability, documentId) {
     return {
         id: 'reuse-embed',
         componentId: capability.embedComponentId,
         props: {
-            [capability.relationProp]: {
-                kind: 'static',
-                // EC-589 / EC-586: a reference is a typed envelope from the first write.
-                value: referenceNode({ collection: capability.collectionId, id: documentId }),
-            },
+            // EC-589 / EC-586: a reference is a typed envelope from the first write.
+            [capability.relationProp]: staticProp(referenceNode({ collection: capability.collectionId, id: documentId })),
         },
     };
 }
@@ -339,8 +274,9 @@ export function detachRefusal(args) {
 /**
  * Run "Make reusable" (EC-282) — the preflight first (EC-584: a refusal creates,
  * publishes and replaces NOTHING), then ONE insert-if-absent create of the reusable
- * document (EC-595 A2), the in-place swap for the embed, and the chosen publish,
- * whose success notice is shown only when the document is actually published.
+ * document (EC-595 A2), the in-place swap for the embed — one canvas history entry that
+ * records the created document (EC-728) — and the chosen publish, whose success notice is
+ * shown only when the document is actually published.
  */
 export async function runPromote(args) {
     const { root, nodeId, node, name, capability, collection, placement, canvasFieldLabel, effects } = args;
@@ -351,8 +287,9 @@ export async function runPromote(args) {
     }
     const ref = { collection: capability.collectionId, id: effects.newDocumentId() };
     const content = buildReusableValues(collection, capability, name, node, args.existing, args.locales);
-    effects.insertDocument({ ...ref, ...content });
-    effects.replaceInCanvas(nodeId, makeEmbedNode(capability, ref.id));
+    const document = { ...ref, ...content };
+    effects.insertDocument(document);
+    effects.replaceInCanvas(nodeId, makeEmbedNode(capability, ref.id), { kind: 'reusable-created', ref, name, document });
     if (!args.publish) {
         effects.madeDraft(name);
         return 'draft';
@@ -365,4 +302,84 @@ export async function runPromote(args) {
     effects.publishFailed(name);
     return 'publish-failed';
 }
+/**
+ * EC-728 — Undo of *Make reusable*, the document side. The created document is deleted ONLY
+ * when every authoritative fact at Undo time says nobody else has it: never published (the
+ * record), referenced nowhere — after the page's own restore has landed — (the reference
+ * index, both variants), and unchanged since its create (the delete's revision precondition,
+ * checked by the store in its own step, which also refuses a strict referrer). Anything else
+ * keeps it, with the reason. A read that throws keeps it too: an unproven fact never deletes.
+ */
+export async function undoPromote(effect, deps) {
+    try {
+        await deps.flush();
+        const record = await deps.read(effect.ref);
+        if (!record)
+            return 'gone';
+        if (record.published)
+            return 'published';
+        if ((await deps.referrers(effect.ref)) > 0)
+            return 'referenced';
+        switch (await deps.deleteCreated(effect.ref)) {
+            case 'deleted':
+                return 'deleted';
+            case 'gone':
+                return 'gone';
+            case 'changed':
+                return 'edited';
+            case 'referenced':
+                return 'referenced';
+            default:
+                return 'failed';
+        }
+    }
+    catch {
+        return 'failed';
+    }
+}
+/** The notice for a KEPT document (EC-728 — it names the document and why); none when it went. */
+export function undoPromoteNotice(outcome) {
+    switch (outcome) {
+        case 'published':
+            return 'builder.reuse.undoKeptPublished';
+        case 'edited':
+            return 'builder.reuse.undoKeptEdited';
+        case 'referenced':
+            return 'builder.reuse.undoKeptReferenced';
+        case 'failed':
+            return 'builder.reuse.undoKeptFailed';
+        default:
+            return undefined;
+    }
+}
+/**
+ * EC-728 — the document side of every Undo/Redo that crosses a *Make reusable* step, for one
+ * canvas. Crossings run strictly in order (a Redo waits for the Undo before it), so a fast
+ * Undo → Redo never re-inserts a document whose removal is still in flight. Redo re-inserts
+ * (the same id, insert-if-absent) exactly the documents ITS Undo removed or found gone — never
+ * one Undo kept (it is still there) — and the canvas entry re-swaps the embed.
+ */
+export function createPromoteHistory(deps) {
+    const removed = new Set();
+    let chain = Promise.resolve();
+    return {
+        crossed(step) {
+            chain = chain.then(async () => {
+                const key = documentKey(step.effect.ref);
+                if (step.direction === 'redo') {
+                    if (removed.delete(key))
+                        deps.insert(step.effect.document);
+                    return;
+                }
+                const outcome = await undoPromote(step.effect, deps);
+                if (outcome === 'deleted' || outcome === 'gone')
+                    removed.add(key);
+                const notice = undoPromoteNotice(outcome);
+                if (notice)
+                    deps.notify(notice, step.effect.name);
+            });
+            return chain;
+        },
+    };
+}
 //# sourceMappingURL=reuse.js.map