@formicoidea/labre-core 0.30.1 → 0.32.0

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

@@ -0,0 +1,246 @@
+/**
+ * Reading and writing the level-3 qualification carried by
+ * {@link GfxPrimitiveElementModel.tags} (ADR 0007 § 4).
+ *
+ * The persisted shape is a nested `Y.Map<string[]>` keyed by tag def id, so two
+ * people qualifying one element on two DIFFERENT tags both keep their work.
+ * Everything that reads it wants a plain object, and everything that writes it
+ * has exactly three cases to get right (create the map, mutate it in place,
+ * remove the key when the last tag goes). Both live here so no call site has to
+ * remember either.
+ *
+ * Nothing in this module knows what a tag MEANS. Definitions are runtime
+ * configuration owned by the host (`UniverseTagDefsProvider`) and are never
+ * persisted: a value whose def has vanished still loads, and is displayed as its
+ * raw id.
+ */
+import * as Y from 'yjs';
+/** The `@field()` key. Spelled once. */
+export const ELEMENT_TAGS_FIELD = 'tags';
+/**
+ * Value ids, cleaned: strings only, no blanks, no duplicates, order preserved.
+ *
+ * Persisted values are plain `string`s and are never narrowed, because a
+ * document may legitimately carry an id whose def was removed, renamed or never
+ * seeded in this deployment — and it must still open. What this rejects is not
+ * an unknown id but a non-value: `null`, a number, an object, the empty string.
+ */
+function cleanValues(values) {
+    if (!Array.isArray(values))
+        return [];
+    const seen = new Set();
+    const cleaned = [];
+    for (const value of values) {
+        if (typeof value !== 'string' || value.length === 0)
+            continue;
+        if (seen.has(value))
+            continue;
+        seen.add(value);
+        cleaned.push(value);
+    }
+    return cleaned;
+}
+const sameValues = (a, b) => a.length === b.length && a.every((value, i) => value === b[i]);
+/**
+ * The **degraded shape**: `tags` stored as a plain object rather than a
+ * `Y.Map`.
+ *
+ * This is not a hypothetical. A client that predates this field does not
+ * DECLARE it, so on the five element-creation-from-props paths (paste,
+ * duplicate, alt-drag clone, turn-into-linked-doc, `updateElement` with an
+ * undeclared key) `_assignElementProp` routes it down the unknown-key branch —
+ * and that branch's encodability guard accepts the serialized form of the
+ * nested map perfectly, because it IS flat JSON: an object of arrays of
+ * strings. So the value is written verbatim, as a plain object.
+ *
+ * The unknown-key branch is doing exactly its job — preserving a key it does
+ * not understand. It is THIS side that has to meet it halfway, and in this
+ * release rather than a later one: the whole point of shipping the declaration
+ * before anything writes the field is that the fleet floor tolerates the key,
+ * and tolerance that cannot read the only other shape in existence is not
+ * tolerance.
+ *
+ * Reading normalizes it (below); the first write CONVERTS it
+ * ({@link setElementTag}), so the degraded shape is transitional per element
+ * and never persists past a qualification gesture.
+ */
+function isDegradedTags(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !(value instanceof Y.AbstractType) &&
+        !Array.isArray(value) &&
+        !(value instanceof Uint8Array));
+}
+/**
+ * The element's tags as `[tagId, rawValues]` pairs, whichever shape they are
+ * stored in. One place normalizes the two vintages so no reader has to know
+ * that there are two.
+ */
+function tagEntries(element) {
+    const stored = element.tags;
+    if (stored instanceof Y.Map)
+        return [...stored.entries()];
+    if (isDegradedTags(stored))
+        return Object.entries(stored);
+    return [];
+}
+/**
+ * Every tag on the element, as plain JSON. `{}` when unqualified — absent and
+ * empty are the same fact, and no caller should have to distinguish them.
+ *
+ * Defensive by construction: the map is a document value, so a client of any
+ * vintage may have written something else into it. Both shapes a real client
+ * can produce are read ({@link isDegradedTags}); a malformed entry is skipped,
+ * never thrown on. A board that cannot be read is worse than a tag that is not.
+ */
+export function readElementTags(element) {
+    const tags = {};
+    for (const [tagId, values] of tagEntries(element)) {
+        if (typeof tagId !== 'string' || tagId.length === 0)
+            continue;
+        const cleaned = cleanValues(values);
+        if (cleaned.length)
+            tags[tagId] = cleaned;
+    }
+    return tags;
+}
+/** The value ids selected for one tag, `[]` when it carries none. */
+export function elementTagValues(element, tagId) {
+    const stored = element.tags;
+    if (stored instanceof Y.Map)
+        return cleanValues(stored.get(tagId));
+    if (isDegradedTags(stored))
+        return cleanValues(stored[tagId]);
+    return [];
+}
+/** Whether the element carries `valueId` under `tagId`. */
+export function hasElementTagValue(element, tagId, valueId) {
+    return elementTagValues(element, tagId).includes(valueId);
+}
+/**
+ * Set (or, with an empty `values`, remove) ONE tag on ONE element. Returns
+ * whether anything was written — a gesture that changes nothing must not cost an
+ * undo step and must not be reported.
+ *
+ * The caller owns `store.captureSync()`, and owes it BEFORE this call: the undo
+ * manager is built with no `captureTimeout`, so a qualification issued within
+ * 500 ms of a drag would otherwise be undone together with the drag — making a
+ * promotion look like it moved geometry, which is exactly what the ladder's
+ * invariants forbid.
+ *
+ * ## The cases, and why the first one is the point
+ *
+ * - **A `Y.Map` already** — the entry is set IN PLACE. Replacing the whole map
+ *   instead would restore whole-blob last-write-wins and silently drop a
+ *   concurrent edit on a different tag, which is the single reason the field is
+ *   a nested map at all. Removing the last entry removes the key with
+ *   `clearField` rather than leaving an empty map behind: an element qualified
+ *   and then un-qualified goes back to costing nothing, like one that never was.
+ * - **Nothing yet** — a map is created and assigned through `updateElement`,
+ *   which is what attaches it to the document and starts the nested observer.
+ * - **The degraded shape** ({@link isDegradedTags}) — the map is created from
+ *   what is ALREADY there, plus the change. This is the one case where
+ *   replacing wholesale is right, because a plain object was never mergeable in
+ *   the first place; what would be wrong, and was, is replacing it with a map
+ *   holding only the new tag. A colleague's qualification, written by a client
+ *   that predates this field, would leave without a word.
+ *
+ * ## Read-only
+ *
+ * A read-only store is a no-op with a warning, not a throw and not a write.
+ * This is exported from `@labre/std/gfx`, so a host can call it directly, and
+ * the three write paths below reach the document three different ways: an
+ * in-place `store.transact` and `clearField` carry no read-only guard of their
+ * own (they would silently succeed), while `updateElement` throws. Three
+ * behaviours for one refusal is not a contract; one guard here is.
+ */
+export function setElementTag(element, tagId, values) {
+    if (typeof tagId !== 'string' || tagId.length === 0)
+        return false;
+    if (element.surface.store.readonly) {
+        console.warn(`Refusing to qualify element "${element.id}" with "${tagId}": the document is read-only.`);
+        return false;
+    }
+    const next = cleanValues(values);
+    const stored = element.tags;
+    if (sameValues(elementTagValues(element, tagId), next))
+        return false;
+    // The native shape: merge per tag, which is the whole design.
+    if (stored instanceof Y.Map) {
+        if (next.length === 0) {
+            element.surface.store.transact(() => {
+                stored.delete(tagId);
+            });
+            if (stored.size === 0)
+                element.clearField(ELEMENT_TAGS_FIELD);
+        }
+        else {
+            element.surface.store.transact(() => {
+                stored.set(tagId, next);
+            });
+        }
+        return true;
+    }
+    // Absent, or the degraded shape. `readElementTags` normalizes both, so the
+    // conversion preserves whatever a pre-declaration client left behind.
+    const merged = readElementTags(element);
+    if (next.length === 0)
+        delete merged[tagId];
+    else
+        merged[tagId] = next;
+    const entries = Object.entries(merged);
+    if (entries.length === 0) {
+        // A degraded value emptied by this call: remove the key rather than write
+        // an empty map. (Absent-and-empty returned above, at `sameValues`.)
+        element.clearField(ELEMENT_TAGS_FIELD);
+        return true;
+    }
+    const created = new Y.Map();
+    for (const [id, cleaned] of entries)
+        created.set(id, cleaned);
+    element.surface.updateElement(element.id, { tags: created });
+    return true;
+}
+/**
+ * Rebuild `tags` as a `Y.Map` when it arrives as plain JSON.
+ *
+ * Called by `SurfaceBlockModel._propsToY` for EVERY element type, because the
+ * field is declared on the base class and per-class `propsToY` hooks are not.
+ * Without it, paste / duplicate / alt-drag clone would each store the copy's
+ * qualification as one opaque plain object — indistinguishable from a correct
+ * copy until two people edited it and one of them lost their tag.
+ *
+ * `element.serialize()` is `yMap.toJSON()`, so the nested map reaches every one
+ * of those paths as a plain object with no wrapper; the snapshot path arrives
+ * already converted by the `SURFACE_YMAP_UNIQ_IDENTIFIER` branch above the call
+ * and is passed through untouched. An empty (or unusable) value drops the key
+ * entirely rather than writing a tombstone.
+ */
+export function tagsPropToY(props) {
+    if (!(ELEMENT_TAGS_FIELD in props))
+        return;
+    const value = props[ELEMENT_TAGS_FIELD];
+    if (value instanceof Y.AbstractType)
+        return;
+    if (value === null || typeof value !== 'object') {
+        delete props[ELEMENT_TAGS_FIELD];
+        return;
+    }
+    const entries = Object.entries(value)
+        .filter(([tagId]) => tagId.length > 0)
+        .map(([tagId, values]) => [tagId, cleanValues(values)])
+        .filter(([, cleaned]) => cleaned.length > 0);
+    if (entries.length === 0) {
+        delete props[ELEMENT_TAGS_FIELD];
+        return;
+    }
+    const map = new Y.Map();
+    for (const [tagId, cleaned] of entries)
+        map.set(tagId, cleaned);
+    // The entry count is taken from the array above and NOT from `map.size`: a
+    // `Y.Map` that has not been integrated into a document yet holds its content
+    // in `_prelimContent`, so `size` reads 0 and logs "Add Yjs type to a document
+    // before reading data". Silently dropping every pasted qualification is
+    // exactly the failure this whole conversion exists to prevent.
+    props[ELEMENT_TAGS_FIELD] = map;
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Measure the cost of an operation through the Performance API when the host
+ * provides one, and just run it when it does not.
+ *
+ * This is a devtools aid, not telemetry: nothing is sent anywhere, and the
+ * editor's telemetry bus stays the single reporting seam. The marks are
+ * cleared, while the measure entries are kept on purpose so the operation
+ * shows up in a browser performance profile.
+ */
+export declare const measureOperation: <T>(name: string, fn: () => T) => T;

package/dist/_pkgs/std/gfx/perf.js

@@ -0,0 +1,30 @@
+let opMeasureSeq = 0;
+/**
+ * Measure the cost of an operation through the Performance API when the host
+ * provides one, and just run it when it does not.
+ *
+ * This is a devtools aid, not telemetry: nothing is sent anywhere, and the
+ * editor's telemetry bus stays the single reporting seam. The marks are
+ * cleared, while the measure entries are kept on purpose so the operation
+ * shows up in a browser performance profile.
+ */
+export const measureOperation = (name, fn) => {
+    if (typeof performance === 'undefined' ||
+        typeof performance.mark !== 'function' ||
+        typeof performance.measure !== 'function') {
+        return fn();
+    }
+    const operationId = opMeasureSeq++;
+    const startMark = `${name}:${operationId}:start`;
+    const endMark = `${name}:${operationId}:end`;
+    performance.mark(startMark);
+    try {
+        return fn();
+    }
+    finally {
+        performance.mark(endMark);
+        performance.measure(name, startMark, endMark);
+        performance.clearMarks(startMark);
+        performance.clearMarks(endMark);
+    }
+};

package/dist/_pkgs/std/gfx/selection.js

@@ -1,7 +1,7 @@
 import { DisposableGroup } from '../../global/disposable/index.js';
 import { getCommonBoundWithRotation, } from '../../global/gfx/index.js';
 import { assertType } from '../../global/utils/index.js';
-import groupBy from 'lodash-es/groupBy';
+import groupBy from 'lodash-es/groupBy.js';
 import { Subject } from 'rxjs';
 import { BlockSelection, CursorSelection, SurfaceSelection, TextSelection, } from '../selection/index.js';
 import { GfxExtension, GfxExtensionIdentifier } from './extension.js';

package/dist/_pkgs/std/gfx/tool/tool-controller.d.ts

@@ -36,6 +36,19 @@ export interface ToolEventTarget {
      */
     addHook<K extends SupportedHooks | SupportedEvents>(evtName: K, handler: (evtState: K extends SupportedHooks ? BuiltInEventMap[K] : PointerEventState) => void | boolean): void;
 }
+/**
+ * The only tools a readonly document will activate: selection, panning, the
+ * presentation navigator and the no-op placeholder. Everything else — brush,
+ * highlighter, connector, shape, polygon, text, note, frame, template, eraser —
+ * creates or erases on its first gesture, calling `surface.addElement` /
+ * `store.addBlock` directly, which used to raise uncaught `BlockSuiteError`s on
+ * ordinary keystrokes.
+ *
+ * A whitelist rather than a blacklist, and enforced at {@link
+ * ToolController.setTool}: a new tool is a writer until someone proves
+ * otherwise, and no new entry point can bypass the check by construction.
+ */
+export declare const READONLY_SAFE_TOOLS: Set<string>;
 export declare class ToolController extends GfxExtension {
     static key: string;
     private readonly _builtInHookSlot;

package/dist/_pkgs/std/gfx/tool/tool-controller.js

@@ -25,6 +25,24 @@ export var MouseButton;
     MouseButton[MouseButton["MIDDLE"] = 1] = "MIDDLE";
     MouseButton[MouseButton["SECONDARY"] = 2] = "SECONDARY";
 })(MouseButton || (MouseButton = {}));
+/**
+ * The only tools a readonly document will activate: selection, panning, the
+ * presentation navigator and the no-op placeholder. Everything else — brush,
+ * highlighter, connector, shape, polygon, text, note, frame, template, eraser —
+ * creates or erases on its first gesture, calling `surface.addElement` /
+ * `store.addBlock` directly, which used to raise uncaught `BlockSuiteError`s on
+ * ordinary keystrokes.
+ *
+ * A whitelist rather than a blacklist, and enforced at {@link
+ * ToolController.setTool}: a new tool is a writer until someone proves
+ * otherwise, and no new entry point can bypass the check by construction.
+ */
+export const READONLY_SAFE_TOOLS = new Set([
+    'default',
+    'pan',
+    'frameNavigator',
+    'empty',
+]);
 export class ToolController extends GfxExtension {
     constructor() {
         super(...arguments);
@@ -110,6 +128,14 @@ export class ToolController extends GfxExtension {
         };
         this.setTool = (toolType, options) => {
             const toolNameStr = toolType.toolName;
+            // THE bottleneck for tool activation: keyboard managers, the toolbar and
+            // its mixins, senior buttons and framework modules all land here. A guard
+            // placed higher up is an inventory that goes stale — `s` (shape) is bound
+            // by `shape-draggable.ts` through the toolbar mixin and never sees the
+            // keyboard manager at all.
+            if (this.std.store.readonly && !READONLY_SAFE_TOOLS.has(toolNameStr)) {
+                return;
+            }
             const beforeUpdateCtx = this._createBuiltInHookCtx('beforeToolUpdate', {
                 toolName: toolNameStr,
             });

package/dist/_pkgs/std/gfx/viewport-element.d.ts

@@ -1,6 +1,6 @@
-import { type EditorHost, ShadowlessElement } from '../view';
-import { GfxBlockElementModel } from './model/gfx-block-model';
-import { Viewport } from './viewport';
+import { type EditorHost, ShadowlessElement } from '../view/index.js';
+import { GfxBlockElementModel } from './model/gfx-block-model.js';
+import { Viewport } from './viewport.js';
 /**
  * A wrapper around `requestConnectedFrame` that only calls at most once in one frame
  */

package/dist/_pkgs/std/gfx/viewport-element.js

@@ -36,11 +36,11 @@ import { WithDisposable } from '../../global/lit/index.js';
 import { batch } from '@preact/signals-core';
 import { css, html } from 'lit';
 import { property } from 'lit/decorators.js';
-import { isGfxBlockComponent, ShadowlessElement, } from '../view';
-import { PropTypes, requiredProperties } from '../view/decorators/required';
-import { GfxControllerIdentifier } from './identifiers';
-import { GfxBlockElementModel } from './model/gfx-block-model';
-import { Viewport } from './viewport';
+import { isGfxBlockComponent, ShadowlessElement, } from '../view/index.js';
+import { PropTypes, requiredProperties } from '../view/decorators/required.js';
+import { GfxControllerIdentifier } from './identifiers.js';
+import { GfxBlockElementModel } from './model/gfx-block-model.js';
+import { Viewport } from './viewport.js';
 /**
  * A wrapper around `requestConnectedFrame` that only calls at most once in one frame
  */

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

@@ -1,6 +1,6 @@
 import { Bound, type IPoint, type IVec } from '../../global/gfx/index.js';
 import { BehaviorSubject, Subject } from 'rxjs';
-import type { GfxViewportElement } from '.';
+import type { GfxViewportElement } from './index.js';
 export declare const ZOOM_MAX = 6;
 export declare const ZOOM_MIN = 0.1;
 export declare const ZOOM_STEP = 0.25;
@@ -67,6 +67,18 @@ export declare class Viewport {
      * Note this is different from the zoom property.
      * The editor itself may be scaled by outer container which is common in nested editor scenarios.
      * This property is used to calculate the scale of the editor.
+     *
+     * The scale is read as "what the host paints" over "what the host lays out":
+     * `getBoundingClientRect().width` is the painted width, transforms included
+     * and fractional; `offsetWidth` is the laid out width with no transform, but
+     * the browser gives it as an integer — it rounds both border-box edges, so it
+     * can sit up to a pixel away from the fractional width even when nothing is
+     * scaled at all. A host that is merely a fraction of a pixel wide (a HiDPI
+     * window, a flex remainder) would otherwise report a phantom scale of
+     * ~1.0001, and every pointer delta divided by it comes back short: a 100px
+     * drag moves the element 99.986. Below the rounding error there is no scale
+     * to read, so answer exactly 1; a container that really scales the editor is
+     * orders of magnitude past that pixel.
      */
     get viewScale(): number;
     get top(): number;

package/dist/_pkgs/std/gfx/viewport.js

@@ -1,5 +1,5 @@
 import { Bound, clamp, Vec, } from '../../global/gfx/index.js';
-import debounce from 'lodash-es/debounce';
+import debounce from 'lodash-es/debounce.js';
 import { BehaviorSubject, debounceTime, Subject } from 'rxjs';
 function cutoff(value, ref, sign) {
     if (sign > 0 && value > ref)
@@ -132,13 +132,31 @@ export class Viewport {
      * Note this is different from the zoom property.
      * The editor itself may be scaled by outer container which is common in nested editor scenarios.
      * This property is used to calculate the scale of the editor.
+     *
+     * The scale is read as "what the host paints" over "what the host lays out":
+     * `getBoundingClientRect().width` is the painted width, transforms included
+     * and fractional; `offsetWidth` is the laid out width with no transform, but
+     * the browser gives it as an integer — it rounds both border-box edges, so it
+     * can sit up to a pixel away from the fractional width even when nothing is
+     * scaled at all. A host that is merely a fraction of a pixel wide (a HiDPI
+     * window, a flex remainder) would otherwise report a phantom scale of
+     * ~1.0001, and every pointer delta divided by it comes back short: a 100px
+     * drag moves the element 99.986. Below the rounding error there is no scale
+     * to read, so answer exactly 1; a container that really scales the editor is
+     * orders of magnitude past that pixel.
      */
     get viewScale() {
         if (!this._shell ||
             this._cachedOffsetWidth === null ||
             this._cachedOffsetWidth === 0)
             return 1;
-        return this.boundingClientRect.width / this._cachedOffsetWidth;
+        const width = this.boundingClientRect.width;
+        // offsetWidth is rounded to an integer while the client rect is not:
+        // on fractional devicePixelRatio displays an untransformed shell has a
+        // fractional CSS width, which must not be mistaken for an outer scale.
+        if (Math.abs(width - this._cachedOffsetWidth) <= 0.5)
+            return 1;
+        return width / this._cachedOffsetWidth;
     }
     get top() {
         return this._top;

package/dist/_pkgs/std/inline/extensions/index.d.ts

@@ -1,4 +1,4 @@
-export * from './inline-manager';
-export * from './inline-spec';
-export * from './markdown-matcher';
-export * from './type';
+export * from './inline-manager.js';
+export * from './inline-spec.js';
+export * from './markdown-matcher.js';
+export * from './type.js';

package/dist/_pkgs/std/inline/extensions/index.js

@@ -1,4 +1,4 @@
-export * from './inline-manager';
-export * from './inline-spec';
-export * from './markdown-matcher';
-export * from './type';
+export * from './inline-manager.js';
+export * from './inline-spec.js';
+export * from './markdown-matcher.js';
+export * from './type.js';

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

@@ -1,8 +1,8 @@
-export * from './components';
-export * from './consts';
-export * from './extensions';
-export * from './inline-editor';
-export * from './range';
-export * from './services';
-export * from './types';
-export * from './utils';
+export * from './components/index.js';
+export * from './consts.js';
+export * from './extensions/index.js';
+export * from './inline-editor.js';
+export * from './range/index.js';
+export * from './services/index.js';
+export * from './types.js';
+export * from './utils/index.js';

package/dist/_pkgs/std/inline/index.js

@@ -1,8 +1,8 @@
-export * from './components';
-export * from './consts';
-export * from './extensions';
-export * from './inline-editor';
-export * from './range';
-export * from './services';
-export * from './types';
-export * from './utils';
+export * from './components/index.js';
+export * from './consts.js';
+export * from './extensions/index.js';
+export * from './inline-editor.js';
+export * from './range/index.js';
+export * from './services/index.js';
+export * from './types.js';
+export * from './utils/index.js';

package/dist/_pkgs/std/inline/range/active.js

@@ -1,4 +1,4 @@
-import { RANGE_SYNC_EXCLUDE_ATTR } from './consts';
+import { RANGE_SYNC_EXCLUDE_ATTR } from './consts.js';
 /**
  * Check if the active element is in the editor host.
  * TODO(@mirone): this is a trade-off, we need to use separate awareness store for every store to make sure the selection is isolated.

package/dist/_pkgs/std/inline/range/range-binding.js

@@ -1,4 +1,4 @@
-import throttle from 'lodash-es/throttle';
+import throttle from 'lodash-es/throttle.js';
 import { TextSelection } from '../../selection/index.js';
 import { EditorHost } from '../../view/index.js';
 import { isActiveInEditor } from './active.js';

package/dist/_pkgs/std/inline/services/event.d.ts

@@ -4,6 +4,8 @@ export declare class EventService<TextAttributes extends BaseTextAttributes> {
     readonly editor: InlineEditor<TextAttributes>;
     private _compositionInlineRange;
     private _isComposing;
+    private readonly _getClosestInlineRoot;
+    private readonly _containsNode;
     private readonly _isRangeCompletelyInRoot;
     private readonly _onBeforeInput;
     private readonly _onClick;