@formicoidea/labre-core 0.40.0 → 0.42.0

package/dist/_pkgs/affine-widget-slash-menu/utils.d.ts

@@ -1,4 +1,5 @@
-import type { SlashMenuActionItem, SlashMenuConfig, SlashMenuContext, SlashMenuItem, SlashMenuSubMenu } from './types.js';
+import type { BlockStdScope } from '../std/index.js';
+import type { SlashMenuActionItem, SlashMenuConfig, SlashMenuContext, SlashMenuItem, SlashMenuSubMenu, SlashMenuTooltip } from './types.js';
 /**
  * Whether a keydown is the user typing one more character into the query.
  *
@@ -11,6 +12,24 @@ export declare function isTextInputKey(event: KeyboardEvent): boolean;
 export declare function isActionItem(item: SlashMenuItem): item is SlashMenuActionItem;
 export declare function isSubMenuItem(item: SlashMenuItem): item is SlashMenuSubMenu;
 export declare function slashItemClassName({ name }: SlashMenuItem): string;
+/**
+ * What an item SAYS, whether it declared a wording or a literal `name`.
+ * Mirrors `toolbarActionLabel`: the widget resolves `nameWording` at render,
+ * `name` stays the English identity used by tests and `searchAlias`.
+ */
+export declare function resolveSlashItemName(std: BlockStdScope, item: SlashMenuItem): string;
+/** {@link resolveSlashItemName}, for `description`. */
+export declare function resolveSlashItemDescription(std: BlockStdScope, item: SlashMenuItem): string | undefined;
+/** {@link resolveSlashItemName}, for a tooltip's `caption`. */
+export declare function resolveSlashTooltipCaption(std: BlockStdScope, tooltip: SlashMenuTooltip): string;
+/**
+ * Whether `item` matches a slash-menu search `query` — against its RESOLVED
+ * (translated) name, its English `name`, and its `searchAlias`, so a French
+ * user typing the translated word and a habitual user typing the English one
+ * both find the item. With no `TranslationProvider` the resolved name equals
+ * `name`, so this is unchanged from before wordings existed.
+ */
+export declare function slashItemMatchesQuery(std: BlockStdScope, item: SlashMenuItem, query: string): boolean;
 export declare function parseGroup(group: NonNullable<SlashMenuItem['group']>): readonly [number, string, number];
 export declare function buildSlashMenuItems(items: SlashMenuItem[], context: SlashMenuContext, transform?: (item: SlashMenuItem) => SlashMenuItem): SlashMenuItem[];
 export declare function mergeSlashMenuConfigs(configs: Map<string, SlashMenuConfig>): SlashMenuConfig;

package/dist/_pkgs/affine-widget-slash-menu/utils.js

@@ -1,3 +1,5 @@
+import { translateKey } from '../affine-shared/services/index.js';
+import { isFuzzyMatch } from '../affine-shared/utils/index.js';
 /**
  * Whether a keydown is the user typing one more character into the query.
  *
@@ -31,6 +33,41 @@ export function isSubMenuItem(item) {
 export function slashItemClassName({ name }) {
     return name.split(' ').join('-').toLocaleLowerCase();
 }
+/**
+ * What an item SAYS, whether it declared a wording or a literal `name`.
+ * Mirrors `toolbarActionLabel`: the widget resolves `nameWording` at render,
+ * `name` stays the English identity used by tests and `searchAlias`.
+ */
+export function resolveSlashItemName(std, item) {
+    return item.nameWording ? translateKey(std, ...item.nameWording) : item.name;
+}
+/** {@link resolveSlashItemName}, for `description`. */
+export function resolveSlashItemDescription(std, item) {
+    return item.descriptionWording
+        ? translateKey(std, ...item.descriptionWording)
+        : item.description;
+}
+/** {@link resolveSlashItemName}, for a tooltip's `caption`. */
+export function resolveSlashTooltipCaption(std, tooltip) {
+    return tooltip.captionWording
+        ? translateKey(std, ...tooltip.captionWording)
+        : tooltip.caption;
+}
+/**
+ * Whether `item` matches a slash-menu search `query` — against its RESOLVED
+ * (translated) name, its English `name`, and its `searchAlias`, so a French
+ * user typing the translated word and a habitual user typing the English one
+ * both find the item. With no `TranslationProvider` the resolved name equals
+ * `name`, so this is unchanged from before wordings existed.
+ */
+export function slashItemMatchesQuery(std, item, query) {
+    const { name, searchAlias = [] } = item;
+    const resolvedName = resolveSlashItemName(std, item);
+    const candidates = resolvedName === name
+        ? [name, ...searchAlias]
+        : [name, resolvedName, ...searchAlias];
+    return candidates.some(str => isFuzzyMatch(str, query));
+}
 export function parseGroup(group) {
     return [
         parseInt(group.split('_')[0]),

package/dist/_pkgs/affine-widget-toolbar/translations.d.ts

@@ -0,0 +1,9 @@
+import type { ChromeWording } from '../affine-shared/services/index.js';
+/**
+ * The row's own "⋮" overflow menu button — its `aria-label` (naming the
+ * whole dropdown), distinct from `TOOLBAR_MORE` (`chrome.ts`, "More": the
+ * icon-button's own tooltip inside it).
+ */
+export declare const TOOLBAR_MORE_MENU_ARIA: ChromeWording;
+/** Every wording this package declares, in the order it renders them. */
+export declare const TOOLBAR_WIDGET_WORDINGS: readonly ChromeWording[];

package/dist/_pkgs/affine-widget-toolbar/translations.js

@@ -0,0 +1,13 @@
+/**
+ * The row's own "⋮" overflow menu button — its `aria-label` (naming the
+ * whole dropdown), distinct from `TOOLBAR_MORE` (`chrome.ts`, "More": the
+ * icon-button's own tooltip inside it).
+ */
+export const TOOLBAR_MORE_MENU_ARIA = [
+    'com.labre.toolbar.more-menu',
+    'More menu',
+];
+/** Every wording this package declares, in the order it renders them. */
+export const TOOLBAR_WIDGET_WORDINGS = [
+    TOOLBAR_MORE_MENU_ARIA,
+];

package/dist/_pkgs/affine-widget-toolbar/utils.js

@@ -14,6 +14,7 @@ import mergeWith from 'lodash-es/mergeWith.js';
 import orderBy from 'lodash-es/orderBy.js';
 import partition from 'lodash-es/partition.js';
 import toPairs from 'lodash-es/toPairs.js';
+import { TOOLBAR_MORE_MENU_ARIA } from './translations.js';
 export const sideMap = new Map([
     // includes frame element
     ['affine:surface:frame', { top: 28 }],
@@ -456,7 +457,7 @@ export function renderToolbar(toolbar, context, flavour, source = () => emptyToo
                 action: { id: 'more' },
                 template: html `${keyed(`${flavour}:${key}`, html `
             <editor-menu-button
-              aria-label="More menu"
+              aria-label="${translateKey(context.std, ...TOOLBAR_MORE_MENU_ARIA)}"
               .contentPadding="${'8px'}"
               .button=${html `
                 <editor-icon-button

package/dist/_pkgs/global/gfx/xywh.js

@@ -2,6 +2,13 @@ export function serializeXYWH(x, y, w, h) {
     return `[${x},${y},${w},${h}]`;
 }
 export function deserializeXYWH(xywh) {
+    // An ABSENT value is not a parse failure: a document whose Yjs state has
+    // pending structs can hand us an element whose `xywh` key is simply missing.
+    // Say nothing here — this getter runs several times per frame per element,
+    // and the surface already reports the damaged element once, at mount.
+    if (xywh === null || xywh === undefined) {
+        return [0, 0, 0, 0];
+    }
     try {
         return JSON.parse(xywh);
     }

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/extension/translation-manifest.d.ts

@@ -13,6 +13,13 @@ import { type AnyCommandDescriptor } from './command-registry.js';
  * `packages/affine/all/src/commands.ts` and `scripts/build-bundles.mjs`).
  */
 export type TranslationKeySource = 'command' | 'framework' | 'role' | 'background' | 'rule' | 'nudge' | 'profile' | 'audit-criterion' | 'reading'
+/**
+ * A `UniverseTagDefs` tag or tag-value label (`@labre/affine-shared`'s
+ * `TagDef.labelKey` / `TagValueDef.labelKey`) — the library's OWN pack only
+ * (`WARDLEY_TAG_DEFS`). A host's app-seeded pack carries its own wording in
+ * `label` and needs no key at all.
+ */
+ | 'tag'
 /**
  * The words a framework WRITES ONTO THE CANVAS when an artefact is placed —
  * the "Task" a fresh BPMN task is captioned with, the "People" under an EDGY

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/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;