@formicoidea/labre-core 0.31.0 → 0.32.0

package/dist/_pkgs/affine-shared/services/audit-service.js

@@ -0,0 +1,228 @@
+/**
+ * `AuditProvider` — the injectable seam the **Labre Assistant** plugs into
+ * (PF14.1, ADR 0008 § surface `'agent'`, ADR 0006 § render-free host seam).
+ *
+ * ## What this is, and above all what it is not
+ *
+ * The executor is the Labre Assistant, app-side (PO decision, 01/08/2026). The
+ * library embarks **no model, no prompt runner and no dependency on one**. What
+ * it owns is the seam and only the seam:
+ *
+ * - the criteria, as versioned DATA a framework declares
+ *   ({@link AuditCriterion}) — the same declarative, host-shippable shape a
+ *   validation rule, a role or a background already has;
+ * - the FACTS of a map, collected render-free ({@link AuditFacts});
+ * - a channel out: {@link AuditFinding}s in `audit` severity, timestamped and
+ *   carrying the criterion they came from.
+ *
+ * ## The one invariant everything else defends
+ *
+ * **The deterministic engine never depends on the AI.** Levels 1 and 2 —
+ * `blocking-overridable` and `warning`, evaluated by `evaluateRules` inside the
+ * 16 ms budget — are computed, rendered and arbitrated with no knowledge that
+ * this file exists. An audit READS their output as a fact and writes into a
+ * separate signal. There is no path by which a provider (slow, absent, hostile
+ * or simply wrong) can change a verdict, delay a frame or move a mark on the
+ * canvas.
+ *
+ * That is why {@link normalizeFinding} FORCES `severity: 'audit'` rather than
+ * trusting the provider: `audit` is the severity that is invisible to the
+ * drawing user (`userFacingViolations`), so a provider returning `'warning'`
+ * would otherwise put an AI opinion behind a canvas bracket.
+ */
+import { createIdentifier } from '../../global/di/index.js';
+export const AuditProvider = createIdentifier('LabreAuditService');
+/**
+ * The ONLY way in. **No noop default is registered**, exactly as for
+ * `PivotPropertiesProvider`: absence is a *meaningful* state (standalone
+ * playground, unit tests, a labreapp build that has not wired its assistant),
+ * and making it the tested default is what keeps the degraded path honest.
+ */
+export function AuditExtension(service) {
+    return {
+        setup: di => {
+            di.override(AuditProvider, () => service);
+        },
+    };
+}
+/** Multi-instance: one registered {@link AuditCriterion} per impl. */
+export const AuditCriterionIdentifier = createIdentifier('AuditCriterion');
+/**
+ * Register a framework's audit criteria. Call it from the FLAG-GATED view
+ * extension, beside `ValidationRuleExtension`: criteria are tooling, so a
+ * disabled framework contributes none and an audit of its maps has nothing to
+ * ask about.
+ *
+ * ```ts
+ * context.register(AuditCriterionExtension(WARDLEY_AUDIT_CRITERIA));
+ * ```
+ */
+export function AuditCriterionExtension(criteria) {
+    return {
+        setup: di => {
+            for (const criterion of criteria) {
+                di.addImpl(AuditCriterionIdentifier(criterion.id), () => criterion);
+            }
+        },
+    };
+}
+/** Every criterion registered in this editor assembly. */
+export function getAuditCriteria(std) {
+    return [...std.provider.getAll(AuditCriterionIdentifier).values()];
+}
+/** Whether a rejection is the caller's own abort rather than a failure. */
+function isAbort(error, signal) {
+    if (signal?.aborted)
+        return true;
+    return error instanceof Error && error.name === 'AbortError';
+}
+/**
+ * Force a provider's answer into the ONE shape the library is willing to
+ * publish. Nothing here is a formality:
+ *
+ * - `severity` is OVERWRITTEN, never read. `'audit'` is the severity that stays
+ *   off the canvas; a provider returning `'blocking-overridable'` would
+ *   otherwise raise a bracket on an element over a sentence a model wrote.
+ * - `ruleId` is re-derived from the criterion, so a provider cannot attach its
+ *   finding to a registered rule id and inherit that rule's exceptions,
+ *   profile or toolbar arbitration.
+ * - a finding naming a criterion that was not in the request is DROPPED. The
+ *   library asked three questions; an answer to a fourth is not an answer.
+ * - `at` is stamped library-side from one clock, so every finding of one run
+ *   carries the same timestamp whatever the provider believes the time is.
+ */
+function normalizeFinding(raw, criteria, at) {
+    const criterion = criteria.get(raw.criterionId);
+    if (!criterion)
+        return null;
+    return {
+        ...raw,
+        ruleId: `audit:${criterion.id}`,
+        // Whatever came back: an id list is the only part a provider authors, and
+        // it must be an array of strings or nothing at all.
+        elementIds: Array.isArray(raw.elementIds)
+            ? raw.elementIds.filter((id) => typeof id === 'string')
+            : [],
+        severity: 'audit',
+        criterionId: criterion.id,
+        criterionVersion: criterion.version,
+        at,
+    };
+}
+/**
+ * The guarded call every in-library consumer uses — the one place the provider
+ * contract is enforced rather than trusted.
+ *
+ * - **No provider registered** → `{ status: 'unavailable', findings: [] }`. A
+ *   clean refusal, not a throw and not a crash: levels 1 and 2 are untouched
+ *   and the caller reports nothing.
+ * - **The provider throws or rejects** → `{ status: 'error' }`, with the reason
+ *   kept for logs and never rendered.
+ * - **The caller aborted** → `{ status: 'aborted' }`, keeping whatever findings
+ *   the provider had already returned.
+ * - **`onProgress` throws** → swallowed. A broken progress bar must not kill
+ *   the run that feeds it.
+ *
+ * ## The request is ISOLATED before it crosses (the outbound half)
+ *
+ * `normalizeFinding` exists because a provider is not believed on the way back.
+ * This is the same statement on the way out, and it was missing: the facts a
+ * collector assembles are not all fresh objects. `backgroundAxisFacts` returns
+ * `forward` straight from a module constant (`FORWARD` in
+ * `framework-background/facts.ts`) — `as const` is compile-time only and
+ * nothing is frozen — so every `frames[].axes[].forward` handed over WAS the
+ * very array the engine multiplies against in `evaluateOrientationAgainstAxis`.
+ * A provider writing into the facts it is given (normalising a vector in place,
+ * say) flipped the axis convention for the whole process, and correct arrows
+ * started reporting as violations on the canvas. That is precisely what this
+ * file's header declares impossible.
+ *
+ * `structuredClone` at the boundary fixes the whole class rather than that one
+ * field: no future fact can leak identity either, and the cost is a constraint
+ * the seam already claims (ADR 0006 § 5 — the request must be serializable, and
+ * a test round-trips it). Value-comparing tests were structurally blind to it;
+ * an identity assertion (`.toBe`) now guards it.
+ */
+export async function requestAudit(std, request, options = {}) {
+    const provider = std.getOptional(AuditProvider);
+    if (!provider)
+        return { status: 'unavailable', findings: [] };
+    const criteria = new Map(request.criteria.map(c => [c.id, c]));
+    const { signal } = options;
+    // Asked before the call as well as after: a caller that aborts between
+    // building the request and issuing it must not start a run at all.
+    if (signal?.aborted)
+        return { status: 'aborted', findings: [] };
+    const onProgress = options.onProgress
+        ? (progress) => {
+            try {
+                options.onProgress?.(progress);
+            }
+            catch (error) {
+                console.error('AuditProvider onProgress threw', error);
+            }
+        }
+        : undefined;
+    // The outbound half of "a provider is not believed" — see the note above.
+    // A throw here means the facts stopped being serializable, which is a library
+    // bug and not a host one; it is reported loudly and degraded rather than
+    // allowed to become a crash in front of a user.
+    let isolated;
+    try {
+        isolated = structuredClone(request);
+    }
+    catch (error) {
+        console.error('audit facts are not structured-cloneable — the request cannot be ' +
+            'isolated, so it is not sent (ADR 0006 § 5)', error);
+        return {
+            status: 'error',
+            findings: [],
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+    let raw;
+    try {
+        raw = await provider.runAudit(isolated, {
+            ...(onProgress ? { onProgress } : {}),
+            ...(signal ? { signal } : {}),
+        });
+    }
+    catch (error) {
+        if (isAbort(error, signal))
+            return { status: 'aborted', findings: [] };
+        console.error('AuditProvider.runAudit threw', error);
+        return {
+            status: 'error',
+            findings: [],
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+    const at = Date.now();
+    const findings = (raw?.findings ?? [])
+        .map(finding => normalizeFinding(finding, criteria, at))
+        .filter((finding) => finding !== null);
+    // A provider that resolved normally while the caller was aborting is still an
+    // abort: the caller asked to stop, and honouring that is not the provider's
+    // decision to make.
+    //
+    // `unavailable` passes through with `aborted` and `error`. A registered
+    // provider CAN be unable to answer — assistant behind an app-side feature
+    // flag, quota exhausted, no model configured — and folding that into
+    // `complete` would both inflate the completion series and empty the one
+    // number that says how often users reach for an audit this build cannot
+    // deliver. `superseded` is deliberately absent: it is the library's own
+    // arbitration between two of its calls, so a provider claiming it is read as
+    // `complete` and the arbitration stays where it belongs.
+    const status = signal?.aborted
+        ? 'aborted'
+        : raw?.status === 'aborted' ||
+            raw?.status === 'error' ||
+            raw?.status === 'unavailable'
+            ? raw.status
+            : 'complete';
+    return {
+        status,
+        findings,
+        ...(raw?.reason !== undefined ? { reason: raw.reason } : {}),
+    };
+}

package/dist/_pkgs/affine-shared/services/edit-props-store.d.ts

@@ -87,6 +87,13 @@ export declare class EditPropsStore extends LifeCycleWatcher {
     private readonly _disposables;
     private readonly innerProps$;
     lastProps$: Signal<LastProps>;
+    /**
+     * Flat accumulation of every style prop the user recorded, most recent
+     * value per prop, across element types. "Apply last style" (Mod+Y) reads
+     * this so a fill picked on a rect can repaint an ellipse, or a font style
+     * set on a text can restyle a shape.
+     */
+    lastUsedStyle$: Signal<Record<string, unknown>>;
     slots: {
         storageUpdated: Subject<{
             key: StoragePropsKey;

package/dist/_pkgs/affine-shared/services/edit-props-store.js

@@ -59,6 +59,13 @@ export class EditPropsStore extends LifeCycleWatcher {
         super(std);
         this._disposables = new DisposableGroup();
         this.innerProps$ = signal({});
+        /**
+         * Flat accumulation of every style prop the user recorded, most recent
+         * value per prop, across element types. "Apply last style" (Mod+Y) reads
+         * this so a fill picked on a rect can repaint an ellipse, or a font style
+         * set on a text can restyle a shape.
+         */
+        this.lastUsedStyle$ = signal({});
         this.slots = {
             storageUpdated: new Subject(),
         };
@@ -141,6 +148,10 @@ export class EditPropsStore extends LifeCycleWatcher {
         const overrideProps = schema.parse(props);
         if (Object.keys(overrideProps).length === 0)
             return;
+        this.lastUsedStyle$.value = {
+            ...this.lastUsedStyle$.value,
+            ...overrideProps,
+        };
         const innerProps = this.innerProps$.value;
         const nextProps = mergeWith(clonedeep(innerProps), { [key]: overrideProps }, customizer);
         this.innerProps$.value = OptionalPropsSchema.parse(nextProps);

package/dist/_pkgs/affine-shared/services/font-loader/font-loader-service.d.ts

@@ -3,8 +3,33 @@ import type { ExtensionType } from '../../../store/index.js';
 import type { FontConfig } from './config.js';
 export declare class FontLoaderService extends LifeCycleWatcher {
     static readonly key = "font-loader";
+    private static readonly DEFERRED_LOAD_DELAY_MS;
+    private static readonly DEFERRED_LOAD_BATCH_SIZE;
+    private static readonly DEFERRED_LOAD_BATCH_INTERVAL_MS;
+    private _idleLoadTaskId;
+    private _lazyLoadTimeoutId;
+    private _deferredFontsQueue;
+    private _deferredFontsCursor;
+    private _resolveDeferredDone;
+    /**
+     * Resolves once every deferred font has been handed to the browser, so
+     * `ready` still speaks for the whole configuration and the canvas is still
+     * repainted once — and only once — every font is in.
+     */
+    private _deferredDone;
+    private readonly _loadedFontKeys;
     readonly fontFaces: FontFace[];
-    get ready(): Promise<FontFace[]>;
+    get ready(): Promise<undefined>;
+    private readonly _fontKey;
+    /**
+     * The fonts the canvas paints with before anyone has picked anything: the
+     * ones a board is guaranteed to need on its very first frame. Everything
+     * else is a font a document has to ask for, and can arrive a few seconds
+     * later without anyone seeing a fallback.
+     */
+    private readonly _isCriticalCanvasFont;
+    private readonly _scheduleDeferredLoad;
+    private readonly _cancelDeferredLoad;
     load(fonts: FontConfig[]): void;
     mounted(): void;
     unmounted(): void;

package/dist/_pkgs/affine-shared/services/font-loader/font-loader-service.js

@@ -1,3 +1,4 @@
+import { FontFamily, FontStyle, FontWeight } from '../../../affine-model/index.js';
 import { createIdentifier } from '../../../global/di/index.js';
 import { IS_FIREFOX } from '../../../global/env/index.js';
 import { LifeCycleWatcher } from '../../../std/index.js';
@@ -13,29 +14,145 @@ const initFontFace = IS_FIREFOX
 export class FontLoaderService extends LifeCycleWatcher {
     constructor() {
         super(...arguments);
+        this._idleLoadTaskId = null;
+        this._lazyLoadTimeoutId = null;
+        this._deferredFontsQueue = [];
+        this._deferredFontsCursor = 0;
+        this._resolveDeferredDone = null;
+        /**
+         * Resolves once every deferred font has been handed to the browser, so
+         * `ready` still speaks for the whole configuration and the canvas is still
+         * repainted once — and only once — every font is in.
+         */
+        this._deferredDone = Promise.resolve();
+        this._loadedFontKeys = new Set();
         this.fontFaces = [];
+        this._fontKey = ({ font, weight, style, url }) => {
+            return `${font}:${weight}:${style}:${url}`;
+        };
+        /**
+         * The fonts the canvas paints with before anyone has picked anything: the
+         * ones a board is guaranteed to need on its very first frame. Everything
+         * else is a font a document has to ask for, and can arrive a few seconds
+         * later without anyone seeing a fallback.
+         */
+        this._isCriticalCanvasFont = ({ font, weight, style, }) => {
+            if (style !== FontStyle.Normal)
+                return false;
+            if (font === FontFamily.Poppins) {
+                return (weight === FontWeight.Regular ||
+                    weight === FontWeight.Medium ||
+                    weight === FontWeight.SemiBold);
+            }
+            if (font === FontFamily.Inter) {
+                return weight === FontWeight.Regular || weight === FontWeight.SemiBold;
+            }
+            if (font === FontFamily.Kalam) {
+                // Mindmap style four uses bold Kalam text. SemiBold is the strongest
+                // Kalam weight we ship.
+                return weight === FontWeight.SemiBold;
+            }
+            return false;
+        };
+        this._scheduleDeferredLoad = (fonts) => {
+            if (fonts.length === 0 || typeof window === 'undefined') {
+                return;
+            }
+            this._deferredFontsQueue = fonts;
+            this._deferredFontsCursor = 0;
+            this._deferredDone = new Promise(resolve => {
+                this._resolveDeferredDone = resolve;
+            });
+            const win = window;
+            const scheduleBatch = (delayMs) => {
+                this._lazyLoadTimeoutId = window.setTimeout(() => {
+                    this._lazyLoadTimeoutId = null;
+                    const runBatch = () => {
+                        this._idleLoadTaskId = null;
+                        const start = this._deferredFontsCursor;
+                        const end = Math.min(start + FontLoaderService.DEFERRED_LOAD_BATCH_SIZE, this._deferredFontsQueue.length);
+                        this._deferredFontsCursor = end;
+                        this.load(this._deferredFontsQueue.slice(start, end));
+                        if (this._deferredFontsCursor < this._deferredFontsQueue.length) {
+                            scheduleBatch(FontLoaderService.DEFERRED_LOAD_BATCH_INTERVAL_MS);
+                            return;
+                        }
+                        this._resolveDeferredDone?.();
+                        this._resolveDeferredDone = null;
+                    };
+                    if (typeof win.requestIdleCallback === 'function') {
+                        this._idleLoadTaskId = win.requestIdleCallback(runBatch, {
+                            timeout: 2000,
+                        });
+                        return;
+                    }
+                    runBatch();
+                }, delayMs);
+            };
+            scheduleBatch(FontLoaderService.DEFERRED_LOAD_DELAY_MS);
+        };
+        this._cancelDeferredLoad = () => {
+            if (typeof window === 'undefined') {
+                return;
+            }
+            const win = window;
+            if (this._idleLoadTaskId !== null &&
+                typeof win.cancelIdleCallback === 'function') {
+                win.cancelIdleCallback(this._idleLoadTaskId);
+            }
+            this._idleLoadTaskId = null;
+            if (this._lazyLoadTimeoutId !== null) {
+                window.clearTimeout(this._lazyLoadTimeoutId);
+                this._lazyLoadTimeoutId = null;
+            }
+            this._deferredFontsQueue = [];
+            this._deferredFontsCursor = 0;
+            this._resolveDeferredDone?.();
+            this._resolveDeferredDone = null;
+            this._deferredDone = Promise.resolve();
+        };
     }
     static { this.key = 'font-loader'; }
+    static { this.DEFERRED_LOAD_DELAY_MS = 5000; }
+    static { this.DEFERRED_LOAD_BATCH_SIZE = 4; }
+    static { this.DEFERRED_LOAD_BATCH_INTERVAL_MS = 1000; }
     get ready() {
-        return Promise.all(this.fontFaces.map(fontFace => fontFace.loaded));
+        return this._deferredDone.then(() => Promise.all(this.fontFaces.map(fontFace => fontFace.loaded)).then(() => undefined));
     }
     load(fonts) {
-        this.fontFaces.push(...fonts.map(font => {
+        for (const font of fonts) {
+            const key = this._fontKey(font);
+            // The same face registered twice is a second download and a second
+            // entry in `document.fonts`.
+            if (this._loadedFontKeys.has(key)) {
+                continue;
+            }
+            this._loadedFontKeys.add(key);
             const fontFace = initFontFace(font);
             document.fonts.add(fontFace);
             fontFace.load().catch(console.error);
-            return fontFace;
-        }));
+            this.fontFaces.push(fontFace);
+        }
     }
     mounted() {
         const config = this.std.getOptional(FontConfigIdentifier);
-        if (config) {
-            this.load(config);
+        if (!config || config.length === 0) {
+            return;
         }
+        const criticalFonts = config.filter(this._isCriticalCanvasFont);
+        const eagerFonts = criticalFonts.length > 0 ? criticalFonts : config.slice(0, 3);
+        const eagerFontKeySet = new Set(eagerFonts.map(this._fontKey));
+        const deferredFonts = config.filter(font => !eagerFontKeySet.has(this._fontKey(font)));
+        this.load(eagerFonts);
+        this._scheduleDeferredLoad(deferredFonts);
     }
     unmounted() {
-        this.fontFaces.forEach(fontFace => document.fonts.delete(fontFace));
+        this._cancelDeferredLoad();
+        for (const fontFace of this.fontFaces) {
+            document.fonts.delete(fontFace);
+        }
         this.fontFaces.splice(0, this.fontFaces.length);
+        this._loadedFontKeys.clear();
     }
 }
 export const FontConfigIdentifier = createIdentifier('AffineFontConfig');

package/dist/_pkgs/affine-shared/services/index.d.ts

@@ -1,3 +1,4 @@
+export * from './audit-service.js';
 export * from './auto-clear-selection-service.js';
 export * from './block-meta-service.js';
 export * from './citation-service/index.js';
@@ -22,11 +23,15 @@ export * from './notification-service.js';
 export * from './open-doc-config.js';
 export * from './page-viewport-service.js';
 export * from './parse-url-service.js';
+export * from './pivot-materiality-publisher.js';
+export * from './pivot-properties-service.js';
 export * from './quick-search-service.js';
 export * from './sidebar-service.js';
 export * from './telemetry-service/index.js';
 export * from './theme-service.js';
 export * from './toolbar-service/index.js';
+export * from './translation-service/index.js';
+export * from './universe-tag-defs-service.js';
 export * from './user-service/index.js';
 export * from './viewport-element-service.js';
 export * from './virtual-keyboard-service.js';

package/dist/_pkgs/affine-shared/services/index.js

@@ -1,3 +1,4 @@
+export * from './audit-service.js';
 export * from './auto-clear-selection-service.js';
 export * from './block-meta-service.js';
 export * from './citation-service/index.js';
@@ -22,11 +23,15 @@ export * from './notification-service.js';
 export * from './open-doc-config.js';
 export * from './page-viewport-service.js';
 export * from './parse-url-service.js';
+export * from './pivot-materiality-publisher.js';
+export * from './pivot-properties-service.js';
 export * from './quick-search-service.js';
 export * from './sidebar-service.js';
 export * from './telemetry-service/index.js';
 export * from './theme-service.js';
 export * from './toolbar-service/index.js';
+export * from './translation-service/index.js';
+export * from './universe-tag-defs-service.js';
 export * from './user-service/index.js';
 export * from './viewport-element-service.js';
 export * from './virtual-keyboard-service.js';

package/dist/_pkgs/affine-shared/services/pivot-materiality-publisher.d.ts

@@ -0,0 +1,129 @@
+/**
+ * `PivotMaterialityPublisher` — the one place a board occurrence's derived
+ * materialities are announced to the host (MF3 / ADR 0006 § 4).
+ *
+ * When the level-3 qualification of a **bound** element changes, the library
+ * announces it and forgets. It never writes to the pivot record, never awaits
+ * the host, never retries and never observes the result: the element is the
+ * source of truth for the occurrence, the record is the source of truth for
+ * itself, and the channel between them is one-way.
+ *
+ * ## Why a Yjs observer and not the setter, and not the command layer
+ *
+ * Both were rejected for the same concrete reason: **undo**.
+ *
+ * The `@field()` setter runs on a JS assignment only. Undo, redo and every
+ * remote peer's change arrive through the element's `Y.Map` observer and never
+ * touch it. Publishing from the setter — or from the command that calls it —
+ * means: qualify a bound element, press Ctrl+Z, and the element reverts while
+ * the record keeps the derived materiality. A silent, permanent desync on the
+ * very first undo.
+ *
+ * Subscribing to the surface's change stream and gating on `local` fixes it and
+ * costs nothing else:
+ *
+ * | Event                           | `local` | Publishes?                                |
+ * | ------------------------------- | ------- | ----------------------------------------- |
+ * | Author qualifies an element     | `true`  | Yes, on the authoring client only         |
+ * | Author presses Ctrl+Z / Ctrl+Y  | `true`  | Yes — this is what fixes the undo desync  |
+ * | Remote peer receives the change | `false` | No                                        |
+ *
+ * `local` also IS the de-duplication: it partitions the fleet into exactly one
+ * publisher and N−1 silent observers, with no leader election, no lock and no
+ * acknowledgement.
+ *
+ * ## Best-effort, and honest about it
+ *
+ * Patches are full-state and idempotent, so replaying one converges — which is
+ * what makes the unobservable `void` return survivable. If the authoring client
+ * is offline from the host at that moment the patch is lost and the record
+ * stays stale until the next local change to that element. The safety net is
+ * that the element is always authoritative: a host can rebuild every derived
+ * materiality by scanning `collectPivotOccurrences`. Derived materialities are
+ * a cache of the boards, never a second original.
+ */
+import { LifeCycleWatcher } from '../../std/index.js';
+import { type GfxPrimitiveElementModel } from '../../std/gfx/index.js';
+import { type OccurrenceMaterialityPatch } from './pivot-properties-service.js';
+export declare class PivotMaterialityPublisher extends LifeCycleWatcher {
+    static readonly key = "pivot-materiality-publisher";
+    /** Elements whose state is to be re-examined at the end of this microtask. */
+    private readonly _pending;
+    private _flushing;
+    /**
+     * The record each element was last known to be bound to, so that unbinding —
+     * or re-binding — can retract the OLD record's materiality. Without it the
+     * retraction has no `pivotDocId` to name: by the time the change is seen, the
+     * element no longer carries the old one.
+     */
+    private readonly _lastBinding;
+    /**
+     * Last published fingerprint per `(pivotDocId, elementId)`. One user gesture
+     * produces several payloads for one element — the stash/pop path alone emits
+     * one per stashed prop — and a drag emits dozens that change nothing a patch
+     * describes. Publishing the element's CURRENT FULL STATE and dropping it when
+     * it repeats is what keeps that to one patch per real change.
+     */
+    private readonly _published;
+    private _subscriptions;
+    private _disposeSurfaceEffect;
+    mounted(): void;
+    unmounted(): void;
+    private _unsubscribe;
+    private _resubscribe;
+    /**
+     * Record what record an element is bound to, **without publishing anything**.
+     *
+     * ## Who owns a retraction in a collaborative session
+     *
+     * The client whose LOCAL transaction removes the occurrence — deletion,
+     * unbind, or re-bind. That is the same rule as every other emission here
+     * (`local` partitions the fleet into one publisher and N−1 observers), and it
+     * is the only rule that can work: the peer that ORIGINALLY bound the element
+     * sees the deletion as a remote change, so if retraction belonged to the
+     * binder, nobody would emit it at all.
+     *
+     * Owning the retraction requires knowing which record to retract from, and by
+     * the time the deletion is seen the element is gone. Hence this: **tracking
+     * the binding is bookkeeping, not publication.** Every client keeps the map
+     * for everything it can see, whoever wrote it, so that whichever client
+     * eventually performs the removal can name the record. Without it, retraction
+     * only ever worked when one client both created and deleted the occurrence —
+     * the rare case in an open collaborative session, and the host would keep a
+     * materiality attributed to an occurrence that no longer exists.
+     *
+     * A remote peer that CHANGES a binding updates this map silently: it is
+     * publishing its own retraction and its own patch, and a second one from here
+     * would be a duplicate, not a safety net.
+     *
+     * ## …and it invalidates what WE last published
+     *
+     * `_published` remembers the last patch this client sent, so an unchanged
+     * state is not re-announced. A remote change makes that memory a lie: the
+     * peer published its own patch, so the host now holds the peer's state, not
+     * ours. Left stale, the sequence `we publish data` → `peer switches to
+     * practice` → `we go back to data` compares equal to our own last
+     * fingerprint and DROPS the patch — the element says `data`, the host keeps
+     * `practice`, until some third, different value comes along.
+     *
+     * Milder than the retraction gap above (this is host-side cache staleness,
+     * not document data, and it heals on the next real change), but free to
+     * close: every remote touch drops our fingerprint for that occurrence, so
+     * the next local patch is always sent.
+     */
+    private _track;
+    /**
+     * Coalesce per element within one microtask, then publish the element's
+     * CURRENT FULL STATE — never a delta. `_onChange` is also invoked directly on
+     * the stash/pop path, so one gesture legitimately produces several payloads
+     * for the same element.
+     */
+    private _schedule;
+    private _publish;
+    private _emit;
+}
+/**
+ * The full state of one occurrence, as the host stores it. Exported for the
+ * host's own rebuild path and for tests — it is a pure function of the element.
+ */
+export declare function buildOccurrencePatch(element: GfxPrimitiveElementModel, pivotDocId: string): OccurrenceMaterialityPatch;