@formicoidea/labre-core 0.41.0 → 0.43.1

package/dist/_pkgs/std/extension/command-registry.d.ts

@@ -2,6 +2,7 @@ import type { ExtensionType } from '../../store/index.js';
 import type { TemplateResult } from 'lit';
 import type { z } from 'zod';
 import type { BlockStdScope } from '../scope/index.js';
+import type { RoleId } from '../gfx/model/surface/role.js';
 import { type ShortcutDescriptor, type ShortcutScope } from './shortcut.js';
 /**
  * Where an element/tool creation was triggered from. Historically declared in
@@ -20,9 +21,25 @@ export type ElementCreationSource = 'shortcut' | 'toolbar:general' | 'toolbar:dn
  * `ddd-aggregate` is deliberately absent: it ships DDD *templates* only — no
  * senior button, no commands — so it is a packaging bundle, not a framework.
  */
-export declare const FRAMEWORK_IDS: readonly ["wardley", "edgy", "cynefin-estuarine", "bpmn", "c4", "ddd-event-storming", "ddd-core-domain", "ddd-context-map"];
+export declare const FRAMEWORK_IDS: readonly ["wardley", "edgy", "cynefin-estuarine", "bpmn", "c4", "ddd-event-storming", "ddd-core-domain", "ddd-context-map", "uml"];
 export type FrameworkId = (typeof FRAMEWORK_IDS)[number];
 export type CommandOwner = 'core' | FrameworkId;
+/**
+ * `'wardley:component'` → `'wardley'`, when that names a real framework.
+ *
+ * A role id is namespaced by its framework (`<framework>:<role>`, see
+ * `gfx/model/surface/role.ts`), so the namespace IS the framework — for every
+ * element that carries one, board included (`wardley:map`, `edgy:board`…).
+ * Anything else — a neutral element, a namespace no framework claims — answers
+ * `undefined`, which is what "this element belongs to no framework" means
+ * everywhere this is read.
+ *
+ * Lives here, beside {@link FRAMEWORK_IDS}, because it is the only knowledge it
+ * needs and because four call sites had each copied it: the materiality
+ * publisher, the pivot and tag commands, and now the colour pickers' palette
+ * carousel.
+ */
+export declare function frameworkOfRole(role: string | undefined): FrameworkId | undefined;
 /**
  * Serializable precondition. Closed union; extended only by an amendment to
  * `docs/adr/0008`. `'always'` is the default when omitted.
@@ -130,6 +147,28 @@ export interface CommandDescriptor<P = void> {
      * it as the `role` dimension.
      */
     telemetry?: CommandTelemetry;
+    /**
+     * The legend row (or rows) this command's artefact puts in its board's
+     * legend — `docs/adr/0009`'s sibling for the legend: a framework subscribes
+     * its notation instead of maintaining a second table of it.
+     *
+     * Declared on the command that DRAWS the thing, so the row and the gesture
+     * cannot drift: renaming the role renames the row, restyling the preset
+     * restyles the swatch. The board's own command declares {@link legendBox}
+     * instead — it is the sheet the legend is drawn on, not an artefact on it.
+     *
+     * A LIST because one command may put several rows down: EDGY's twelve
+     * official elements are all stamped by one template command, and no "add a
+     * Content" gesture exists to hang them off individually.
+     */
+    legend?: CommandLegendEntry | readonly CommandLegendEntry[];
+    /**
+     * How the legend BOX of this framework's board is laid out, and what it adds
+     * beyond the rows. Declared on the board command (`telemetry.board`) and
+     * read by nothing else — a framework whose rows are 16-unit chips declares
+     * none of it.
+     */
+    legendBox?: CommandLegendBox;
 }
 /** See {@link CommandDescriptor.telemetry}. */
 export interface CommandTelemetry {
@@ -137,6 +176,124 @@ export interface CommandTelemetry {
     element: string;
     board?: true;
 }
+/**
+ * What a legend SWATCH is, without its label: the command already carries a
+ * wording, and the role it stamps carries one too, so a table that restated the
+ * text would be a third spelling of the same word.
+ */
+export interface CommandLegendRow {
+    swatch: 'dot' | 'square' | 'line' | 'glyph' | 'edge' | 'custom';
+    color: string;
+    /** `square` swatches: the letter drawn inside it (Team Topologies' C/X/F). */
+    letter?: string;
+    /** `line` swatches: draw the sample as two segments, so a dash reads as one. */
+    dashed?: boolean;
+    /**
+     * `glyph` / `edge` swatches: the props of the REAL element to draw in the
+     * swatch box, geometry excluded — the layout fills in `xywh` (a glyph) or the
+     * two endpoint positions (an edge).
+     *
+     * A `role` here is stripped by the drawing side and must not be declared: a
+     * legend is drawn ON the board it describes and the scan detects by role, so
+     * a swatch carrying one would list itself the next time a legend is
+     * generated — and would be counted by every validation rule.
+     */
+    props?: Record<string, unknown>;
+    /** `glyph` swatches: the artefact's aspect ratio, fitted inside the box. */
+    aspect?: number;
+    /**
+     * `glyph` swatches: an explicit size in model units, which SHORT-CIRCUITS the
+     * fit-to-box. Wardley's gradation (component 16 < method 18 < ecosystem 20 <
+     * market 22) is notation rather than decoration, and fitting every pastille
+     * to the same box would erase it.
+     */
+    size?: readonly [width: number, height: number];
+    /**
+     * `custom` swatches: draw the sample yourself and return the ids created.
+     *
+     * The escape hatch for a COMPOSITE glyph — Wardley's market (a circle, three
+     * dots and three connectors), its pipeline (a body and a handle), its Porter
+     * rose (a circle, four derived arrows and a letter). Their geometry is
+     * derived rather than literal, and a table of static rectangles would re-fix
+     * what the framework computes.
+     */
+    draw?: (surface: CommandLegendSurface, box: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    }, std: BlockStdScope) => string[];
+}
+/**
+ * Where a `custom` swatch (and a {@link CommandLegendExtra}) puts what it
+ * draws. Structural on purpose: `std` declares WHAT a framework may say, and
+ * the surface block that receives it is what knows how to draw — importing it
+ * here would point this layer at one of its own consumers.
+ */
+export interface CommandLegendSurface {
+    addElement(props: Record<string, unknown>): string;
+}
+/** See {@link CommandDescriptor.legend}. */
+export interface CommandLegendEntry {
+    /**
+     * The role this row stands for — usually the one the command stamps, but not
+     * always: C4 writes ONE "Boundary" row on the parent `c4:boundary` for its
+     * two boundary commands, and the second declares nothing.
+     */
+    role: RoleId;
+    row: CommandLegendRow;
+    /**
+     * Match `role` and `role` ALONE, without the specialisation walk. Reach for
+     * it when the parent row would be a lie on a board carrying only children —
+     * EDGY's bare "Object", BPMN's blank "Task".
+     */
+    exact?: boolean;
+    /** Static prefix kept in front of the resolved wording ("PS — Partnership"). */
+    labelPrefix?: string;
+    /**
+     * The row's OWN wording, ahead of the role's. Wardley's rows explain the
+     * notation ("Need / capability (activity, practice, data…)") where the role
+     * merely names it ("Component"); without this the legend would lose its prose.
+     */
+    labelWording?: readonly [key: string, fallback: string];
+    /**
+     * The sub-title this row files itself under, ahead of the command's
+     * `category`. Three of the DDD frameworks put every command in ONE category
+     * and still show two or three sub-titles, and EDGY's twelve elements come
+     * from one command and span four.
+     */
+    section?: readonly [key: string, fallback: string];
+}
+/**
+ * A block of the legend box that is not a row: Wardley's evolution gradient,
+ * its Porter panel. `height` is a VALUE rather than a second callback because
+ * the box has to be measured before it is placed.
+ */
+export interface CommandLegendExtra {
+    /** Total height in model units, separator included. Known BEFORE drawing. */
+    height: number;
+    draw(surface: CommandLegendSurface, std: BlockStdScope, x: number, y: number, width: number): string[];
+}
+/** See {@link CommandLegendBox.extras}. */
+export type CommandLegendExtras = (ctx: {
+    std: BlockStdScope;
+    /** The board the legend describes. Cast by whoever needs more than its box. */
+    board: {
+        xywh: string;
+    };
+    present: ReadonlySet<RoleId>;
+}) => CommandLegendExtra[];
+/** See {@link CommandDescriptor.legendBox}. */
+export interface CommandLegendBox {
+    /** Box title; every board that has one says "Legend" and omits this. */
+    titleWording?: readonly [key: string, fallback: string];
+    width?: number;
+    /** Row pitch; the swatch is drawn centred in it. */
+    rowHeight?: number;
+    swatchWidth?: number;
+    swatchHeight?: number;
+    extras?: CommandLegendExtras;
+}
 /**
  * A command with its parameter contract erased — what the REGISTRY holds.
  *

package/dist/_pkgs/std/extension/command-registry.js

@@ -19,7 +19,29 @@ export const FRAMEWORK_IDS = [
     'ddd-event-storming',
     'ddd-core-domain',
     'ddd-context-map',
+    'uml',
 ];
+/**
+ * `'wardley:component'` → `'wardley'`, when that names a real framework.
+ *
+ * A role id is namespaced by its framework (`<framework>:<role>`, see
+ * `gfx/model/surface/role.ts`), so the namespace IS the framework — for every
+ * element that carries one, board included (`wardley:map`, `edgy:board`…).
+ * Anything else — a neutral element, a namespace no framework claims — answers
+ * `undefined`, which is what "this element belongs to no framework" means
+ * everywhere this is read.
+ *
+ * Lives here, beside {@link FRAMEWORK_IDS}, because it is the only knowledge it
+ * needs and because four call sites had each copied it: the materiality
+ * publisher, the pivot and tag commands, and now the colour pickers' palette
+ * carousel.
+ */
+export function frameworkOfRole(role) {
+    const namespace = role?.split(':')[0];
+    return FRAMEWORK_IDS.includes(namespace ?? '')
+        ? namespace
+        : undefined;
+}
 /** Multi-instance: one registered {@link CommandDescriptor} per impl. */
 export const CommandDescriptorIdentifier = createIdentifier('CommandDescriptor');
 /** Multi-instance: one `iconKey → template` table per contributing package. */

package/dist/_pkgs/std/gfx/index.d.ts

@@ -20,7 +20,7 @@ export { GfxLocalElementModel, prop, } from './model/surface/local-element-model
 export { collectPivotOccurrences, isPivotBound, type PivotBoundElement, type PivotOccurrence, resolvePivotBinding, } from './model/surface/pivot.js';
 export { type EdgeDirectionDef, findRoleDef, isTypedEdgeRole, type RoleDef, type RoleDefs, type RoleId, roleIsA, type RoleKind, RoleVocabularyExtension, RoleVocabularyIdentifier, } from './model/surface/role.js';
 export { ELEMENT_TAGS_FIELD, type ElementTags, elementTagValues, hasElementTagValue, readElementTags, setElementTag, tagsPropToY, } from './model/surface/tags.js';
-export { type ElementUpdatedData, SURFACE_TEXT_UNIQ_IDENTIFIER, SURFACE_YMAP_UNIQ_IDENTIFIER, SurfaceBlockModel, type SurfaceBlockProps, type SurfaceMiddleware, } from './model/surface/surface-model.js';
+export { type ElementUpdatedData, SURFACE_TEXT_UNIQ_IDENTIFIER, SURFACE_YMAP_UNIQ_IDENTIFIER, SurfaceBlockModel, type SurfaceBlockProps, type SurfaceDamageReason, type SurfaceElementDamage, type SurfaceElementDamageReport, type SurfaceMiddleware, } from './model/surface/surface-model.js';
 export { measureOperation } from './perf.js';
 export { GfxSelectionManager } from './selection.js';
 export { SurfaceMiddlewareBuilder, SurfaceMiddlewareExtension, } from './surface-middleware.js';

package/dist/_pkgs/std/gfx/interactivity/gfx-view-event-handler.d.ts

@@ -59,6 +59,18 @@ export declare class GfxViewEventManager {
      * cannot see.
      */
     private _answersAt;
+    /**
+     * Whether ANY view answers at a model point — "is this spot taken?" asked of
+     * the view layer rather than of the models.
+     *
+     * The two layers do not answer the same thing (see {@link _answersAt}), so
+     * whoever treats a point as empty canvas has to ask both: the model says
+     * "select me?", the view says "is this mine?". A framework background is the
+     * case that forced this out — it is picked by its border alone, yet its
+     * labels answer the double-click that renames them, so the model calls their
+     * zone empty while the view is about to use it.
+     */
+    hasViewAt(x: number, y: number): boolean;
     /**
      * The views under a MODEL point, in PAINT ORDER — the topmost last.
      *

package/dist/_pkgs/std/gfx/interactivity/gfx-view-event-handler.js

@@ -71,7 +71,12 @@ export class GfxViewEventManager {
                 if (this._draggingElement) {
                     this._draggingElement.dispatch('dragend', _evt);
                 }
-                this._draggingElement = last(this._hoveredElementsStack) ?? null;
+                // The same re-pick by point a click makes, and for the same reason: a
+                // stack only `pointermove` rebuilds is stale whenever the pointer
+                // arrived without one — after a toolbar action that rewrote what is
+                // under it, for instance — and a drag would then be handed to the view
+                // that USED to be there.
+                this._draggingElement = this._targetOf(_evt);
                 return this._draggingElement?.dispatch('dragstart', _evt) ?? false;
             }
             case 'dragmove': {
@@ -109,6 +114,20 @@ export class GfxViewEventManager {
                 ? (model.externalBound?.isPointInBound([x, y]) ?? false)
                 : false));
     }
+    /**
+     * Whether ANY view answers at a model point — "is this spot taken?" asked of
+     * the view layer rather than of the models.
+     *
+     * The two layers do not answer the same thing (see {@link _answersAt}), so
+     * whoever treats a point as empty canvas has to ask both: the model says
+     * "select me?", the view says "is this mine?". A framework background is the
+     * case that forced this out — it is picked by its border alone, yet its
+     * labels answer the double-click that renames them, so the model calls their
+     * zone empty while the view is about to use it.
+     */
+    hasViewAt(x, y) {
+        return this._viewsAt(x, y).length > 0;
+    }
     /**
      * The views under a MODEL point, in PAINT ORDER — the topmost last.
      *

package/dist/_pkgs/std/gfx/interactivity/manager.d.ts

@@ -45,6 +45,16 @@ export declare class InteractivityManager extends GfxExtension {
         preventDefaultState: boolean;
         handledByView: boolean;
     } | undefined;
+    /**
+     * Whether a view claims the model point — the answer the pointer router will
+     * give this coordinate, made available BEFORE the router runs.
+     *
+     * `dispatchEvent` emits to the extensions first and to the views second, so
+     * an extension that wants to know whether the point is free (rather than
+     * react after the fact) has no `handledByView` to read yet. This is that
+     * answer, asked ahead of time.
+     */
+    hasViewAt(x: number, y: number): boolean;
     private _getSelectionConfig;
     private _getSuggestedTarget;
     /**

package/dist/_pkgs/std/gfx/interactivity/manager.js

@@ -78,6 +78,18 @@ export class InteractivityManager extends GfxExtension {
             handledByView,
         };
     }
+    /**
+     * Whether a view claims the model point — the answer the pointer router will
+     * give this coordinate, made available BEFORE the router runs.
+     *
+     * `dispatchEvent` emits to the extensions first and to the views second, so
+     * an extension that wants to know whether the point is free (rather than
+     * react after the fact) has no `handledByView` to read yet. This is that
+     * answer, asked ahead of time.
+     */
+    hasViewAt(x, y) {
+        return this.canvasEventHandler.hasViewAt(x, y);
+    }
     _getSelectionConfig(models) {
         const selectionConfigMap = new Map();
         models.forEach(model => {

package/dist/_pkgs/std/gfx/model/surface/element-model.js

@@ -45,20 +45,25 @@ import { convertProps, field, getDerivedProps, getFieldPropsSet, hasObserveMeta,
 /**
  * Declared `@field()`s that {@link GfxPrimitiveElementModel.clearField} refuses
  * to remove, because they have no meaningful ABSENT state: every one of them is
- * read unconditionally, with no fallback, by code that has no way to cope.
+ * read unconditionally by code that has no way to cope with its absence.
  *
  * - `index` — the fractional z-order key. Gone, the element's stacking is
  *   `undefined` and the layer manager sorts it nowhere, silently.
- * - `xywh` — gone, `elementBound` collapses to `{0,0,0,0}` and the renderer
- *   throws `"undefined" is not valid JSON` on every frame.
+ * - `xywh` — gone, the element reads `[0,0,0,0]` (its declared fallback, so it
+ *   draws nothing rather than a phantom shape at the origin) and the surface
+ *   reports it once, at mount. A zero-size element is unusable, not optional,
+ *   so it stays here: nothing may CLEAR a bound on purpose.
  * - `seed` — the roughness seed; gone, the hand-drawn renderers produce a
  *   different shape on every repaint.
  *
  * An optional field is exactly one whose accessor declares a usable default (or
- * `undefined`), and those stay clearable. This list is the short answer to
- * "which declared fields are not optional"; it is a deny-list on purpose, so a
- * new optional field needs no ceremony and a new structural one is a deliberate
- * addition here.
+ * `undefined`), and those stay clearable. A read fallback is not the same thing
+ * as a usable default: `xywh` now falls back to `[0,0,0,0]` so a damaged
+ * document keeps painting, which is damage control, not an optional state.
+ *
+ * This list is the short answer to "which declared fields are not optional"; it
+ * is a deny-list on purpose, so a new optional field needs no ceremony and a
+ * new structural one is a deliberate addition here.
  */
 const UNCLEARABLE_ELEMENT_FIELDS = new Set(['index', 'seed', 'xywh']);
 /**

package/dist/_pkgs/std/gfx/model/surface/role.d.ts

@@ -77,12 +77,17 @@ export interface EdgeDirectionDef {
     gestureHintFallback?: string;
     /**
      * CSS colour of the chip the reveal draws this verb in (M2). Absent — which
-     * is every role but one — keeps the house affordance blue the mechanism has
-     * always used, so declaring nothing repaints nothing.
+     * is every role today — leaves the chip on the chrome's accent token, so
+     * every typed edge of every framework wears one blue and follows a host
+     * re-skin with the rest of the chrome.
      *
-     * A colour belongs to the ROLE rather than to the widget because the chip is
-     * per-relation: the PO may want one framework's central relation to stand out
-     * without every other framework's edges changing with it. The chip's text is
+     * An extension point, deliberately unused. One role took it (PR #203) so its
+     * framework's central relation would stand out, and the result on a map
+     * carrying two typed relations was two different blues, with nothing
+     * comparing them. Reversed on the PO recette of 23/09/2026; the field stays
+     * because a framework may one day have a real reason to claim its own, and
+     * `affine/all/src/__tests__/direction-chip-accent.unit.spec.ts` is what makes
+     * that a reviewed decision rather than a silent one. The chip's text is
      * white, so a colour declared here must be dark enough to carry it.
      */
     chipColor?: string;

package/dist/_pkgs/std/gfx/model/surface/surface-model.d.ts

@@ -32,6 +32,17 @@ export type MiddlewareCtx = {
     };
 };
 export type SurfaceMiddleware = (ctx: MiddlewareCtx) => void;
+/** Why an element is considered damaged. One reason so far. */
+export type SurfaceDamageReason = 'missing-xywh';
+/** What the surface knows about one damaged element. */
+export type SurfaceElementDamage = {
+    type: string;
+    reason: SurfaceDamageReason;
+};
+/** The same fact, pushed as it happens. */
+export type SurfaceElementDamageReport = SurfaceElementDamage & {
+    id: string;
+};
 export declare class SurfaceBlockModel extends BlockModel<SurfaceBlockProps> {
     /**
      * The props that are known to move the bound of the containing group, so a
@@ -73,6 +84,12 @@ export declare class SurfaceBlockModel extends BlockModel<SurfaceBlockProps> {
         local: boolean;
     }>;
     elementUpdated: Subject<ElementUpdatedData>;
+    /**
+     * An element was found damaged — see {@link damagedElements}. Pushed at the
+     * same moment the console line is written, so a subscriber that arrives
+     * later reads the map instead and misses nothing.
+     */
+    elementDamaged: Subject<SurfaceElementDamageReport>;
     localElementAdded: Subject<GfxLocalElementModel>;
     localElementDeleted: Subject<GfxLocalElementModel>;
     localElementUpdated: Subject<{
@@ -81,6 +98,20 @@ export declare class SurfaceBlockModel extends BlockModel<SurfaceBlockProps> {
         oldValues: Record<string, unknown>;
     }>;
     private readonly _isEmpty$;
+    private readonly _damagedElements;
+    /**
+     * The elements this surface built from a Y.Map that was missing a key it
+     * declares — today only `xywh`, the bound without which the element paints
+     * nothing (see {@link _createElementFromYMap}).
+     *
+     * **State, not just a signal.** The element models are built when the block
+     * model is created, before any view or `LifeCycleWatcher` is mounted, so a
+     * subscriber to {@link elementDamaged} would always be too late for the
+     * elements the document opened with. Whoever wants to count damaged
+     * documents reads this map at mount, then subscribes for what sync brings
+     * afterwards.
+     */
+    get damagedElements(): ReadonlyMap<string, SurfaceElementDamage>;
     get elementModels(): GfxPrimitiveElementModel<import("./element-model.js").BaseElementProps>[];
     get elements(): Boxed<Y.Map<Y.Map<unknown>>>;
     get localElementModels(): Set<GfxLocalElementModel>;
@@ -166,6 +197,31 @@ export declare class SurfaceBlockModel extends BlockModel<SurfaceBlockProps> {
     addElement<T extends object = Record<string, unknown>>(props: Partial<T> & {
         type: string;
     }): string;
+    /**
+     * Build the element `addElement` would build from `props`, and stop there:
+     * FOR PREVIEWS ONLY — the model never enters the document.
+     *
+     * The props take the insertion path up to the moment the Y.Map would be
+     * attached — the `beforeAdd` middlewares (the author's last-used style), the
+     * class's `propsToY` (a string `text` becomes a `Y.Text`), the declared-prop
+     * routing — so a preview paints exactly what the placed element will. What
+     * `addElement` does next is skipped: the model is not registered (no
+     * `getElementById`, no `elementModels`), is never mounted (no observers, no
+     * `onChange`), emits no `elementAdded`, and opens no transaction.
+     *
+     * Its Y.Map is then parked in a throwaway `Y.Doc` of its own, because the
+     * values of a map that belongs to no document cannot be read (a `Y.Text`
+     * reads empty) — and a renderer needs to read them. That doc is not the
+     * store's; a renderer that WROTE to the model would still reach the store's
+     * `transact`, which is why a preview must only ever be rendered.
+     *
+     * `props.id` is required and is the caller's: nothing checks it against the
+     * document, since nothing is added to it.
+     */
+    createDetachedElement(props: Record<string, unknown> & {
+        type: string;
+        id: string;
+    }): GfxPrimitiveElementModel;
     addLocalElement(elem: GfxLocalElementModel): void;
     applyMiddlewares(middlewares: SurfaceMiddleware[]): void;
     deleteElement(id: string): void;

package/dist/_pkgs/std/gfx/model/surface/surface-model.js

@@ -189,6 +189,21 @@ export class SurfaceBlockModel extends BlockModel {
         'rotate',
         'hidden',
     ]); }
+    /**
+     * The elements this surface built from a Y.Map that was missing a key it
+     * declares — today only `xywh`, the bound without which the element paints
+     * nothing (see {@link _createElementFromYMap}).
+     *
+     * **State, not just a signal.** The element models are built when the block
+     * model is created, before any view or `LifeCycleWatcher` is mounted, so a
+     * subscriber to {@link elementDamaged} would always be too late for the
+     * elements the document opened with. Whoever wants to count damaged
+     * documents reads this map at mount, then subscribes for what sync brings
+     * afterwards.
+     */
+    get damagedElements() {
+        return this._damagedElements;
+    }
     get elementModels() {
         const models = [];
         this._elementModels.forEach(model => models.push(model.model));
@@ -219,10 +234,17 @@ export class SurfaceBlockModel extends BlockModel {
         this.elementAdded = new Subject();
         this.elementRemoved = new Subject();
         this.elementUpdated = new Subject();
+        /**
+         * An element was found damaged — see {@link damagedElements}. Pushed at the
+         * same moment the console line is written, so a subscriber that arrives
+         * later reads the map instead and misses nothing.
+         */
+        this.elementDamaged = new Subject();
         this.localElementAdded = new Subject();
         this.localElementDeleted = new Subject();
         this.localElementUpdated = new Subject();
         this._isEmpty$ = signal(false);
+        this._damagedElements = new Map();
         const subscription = this.created.subscribe(() => {
             this._init();
             subscription.unsubscribe();
@@ -338,6 +360,27 @@ export class SurfaceBlockModel extends BlockModel {
         delete Ctor['_decoratorState'];
         state.creating = false;
         state.skipField = false;
+        // A document whose Yjs state still has pending structs can carry an element
+        // whose `xywh` key never arrived. The element reads its `[0,0,0,0]` fallback
+        // and paints nothing instead of a phantom shape at the origin — say so ONCE
+        // here, where every element model is built from its Y.Map, and never again
+        // from a getter that runs several times per frame. Group-like elements are
+        // excluded for free: their `xywh` is a derived getter, not a declared field.
+        //
+        // Only a map that is IN the document is asked: a brand-new element is built
+        // from a detached Y.Map whose keys still sit in Yjs' preliminary content,
+        // where `has()` sees nothing (and warns about the premature read).
+        if (yMap.doc &&
+            getFieldPropsSet(elementModel).has('xywh') &&
+            !yMap.has('xywh')) {
+            // The console line stays: std runs standalone, with no telemetry bus of
+            // its own. The state and the subject below are what makes the same fact
+            // COUNTABLE by a host that has one.
+            console.warn(`[labre] surface element ${type} ${id} has no xywh: rendering it with ` +
+                `a zero-size bound; the document is damaged`);
+            this._damagedElements.set(id, { type, reason: 'missing-xywh' });
+            this.elementDamaged.next({ id, type, reason: 'missing-xywh' });
+        }
         const unmount = () => {
             mounted = false;
             elementModel.onDestroyed();
@@ -458,6 +501,7 @@ export class SurfaceBlockModel extends BlockModel {
                             const { model, unmount } = this._elementModels.get(id);
                             removeFromType(model.type, model);
                             this._elementModels.delete(id);
+                            this._damagedElements.delete(id);
                             deletedElements.push({ model, unmount });
                         }
                         break;
@@ -510,10 +554,11 @@ export class SurfaceBlockModel extends BlockModel {
                     if (isGfxGroupCompatibleModel(payload.model)) {
                         this._groupLikeModels.delete(payload.id);
                     }
-                    // Same rule as `_watchGroupRelationChange`: the author already
+                    // Same rule as `_watchGroupRelationChange`: cascade only on a local
+                    // edit, and only if the store is writeable. The author already
                     // dropped the block from its group, and `removeChild` is a raw
                     // `transact` — on a readonly viewer it would be a silent write.
-                    if (payload.isLocal) {
+                    if (payload.isLocal && !this.store.readonly) {
                         const group = this.getGroup(payload.id);
                         if (group) {
                             // oxlint-disable-next-line unicorn/prefer-dom-node-remove
@@ -572,7 +617,10 @@ export class SurfaceBlockModel extends BlockModel {
             // the same sync. Reacting to a REMOTE update with a local write is
             // redundant on a writeable peer and, on a readonly viewer, the
             // production exception `Cannot remove element in readonly mode`.
-            if (!local)
+            // A readonly peer never cascades either, whatever the provenance of
+            // the update: it may not write at all, and a lingering empty group is
+            // harmless — the author's own cascade arrives through sync.
+            if (!local || this.store.readonly)
                 return;
             const element = this.getElementById(id);
             if (isGroup(element) &&
@@ -640,6 +688,37 @@ export class SurfaceBlockModel extends BlockModel {
         });
         return id;
     }
+    /**
+     * Build the element `addElement` would build from `props`, and stop there:
+     * FOR PREVIEWS ONLY — the model never enters the document.
+     *
+     * The props take the insertion path up to the moment the Y.Map would be
+     * attached — the `beforeAdd` middlewares (the author's last-used style), the
+     * class's `propsToY` (a string `text` becomes a `Y.Text`), the declared-prop
+     * routing — so a preview paints exactly what the placed element will. What
+     * `addElement` does next is skipped: the model is not registered (no
+     * `getElementById`, no `elementModels`), is never mounted (no observers, no
+     * `onChange`), emits no `elementAdded`, and opens no transaction.
+     *
+     * Its Y.Map is then parked in a throwaway `Y.Doc` of its own, because the
+     * values of a map that belongs to no document cannot be read (a `Y.Text`
+     * reads empty) — and a renderer needs to read them. That doc is not the
+     * store's; a renderer that WROTE to the model would still reach the store's
+     * `transact`, which is why a preview must only ever be rendered.
+     *
+     * `props.id` is required and is the caller's: nothing checks it against the
+     * document, since nothing is added to it.
+     */
+    createDetachedElement(props) {
+        const middlewareCtx = {
+            type: 'beforeAdd',
+            payload: { type: props.type, props: { ...props } },
+        };
+        this._middlewares.forEach(mid => mid(middlewareCtx));
+        const { model } = this._createElementFromProps({ ...middlewareCtx.payload.props, id: props.id }, { onChange: () => { } });
+        new Y.Doc().getMap('preview').set(props.id, model.yMap);
+        return model;
+    }
     addLocalElement(elem) {
         this.localElements.add(elem);
         this.localElementAdded.next(elem);
@@ -682,8 +761,10 @@ export class SurfaceBlockModel extends BlockModel {
         this.elementAdded.complete();
         this.elementRemoved.complete();
         this.elementUpdated.complete();
+        this.elementDamaged.complete();
         this._elementModels.forEach(({ unmount }) => unmount());
         this._elementModels.clear();
+        this._damagedElements.clear();
     }
     getElementById(id) {
         return this._elementModels.get(id)?.model ?? null;

package/dist/_pkgs/std/gfx/view/view.d.ts

@@ -1,6 +1,6 @@
 import { type Container } from '../../../global/di/index.js';
 import { DisposableGroup } from '../../../global/disposable/index.js';
-import { type Bound, type IVec } from '../../../global/gfx/index.js';
+import { Bound, type IVec } from '../../../global/gfx/index.js';
 import type { Extension } from '../../../store/index.js';
 import type { PointerEventState } from '../../event/index.js';
 import type { EditorHost } from '../../view/index.js';
@@ -57,7 +57,16 @@ export declare class GfxElementModelView<T extends GfxLocalElementModel | GfxPri
     onDragStart(_: DragStartContext): void;
     onDragEnd(_: DragEndContext): void;
     onDragMove({ dx, dy, currentBound }: DragMoveContext): void;
-    onBoxSelected(_: BoxSelectionContext): boolean | void;
+    /**
+     * Whether a box (marquee) selection takes this element. `false` keeps it
+     * out; anything else keeps the default (any overlap selects).
+     *
+     * A model may carry its own answer as `boxSelectable(box)` — a framework
+     * background does, to join a marquee only when the marquee contains it —
+     * and the default view defers to it, so every view of such a model gets the
+     * rule without restating it.
+     */
+    onBoxSelected(context: BoxSelectionContext): boolean | void;
     /**
      * Called when the view is destroyed.
      * Override this method requires calling `super.onDestroyed()`.