@formicoidea/labre-core 0.31.0 → 0.33.0

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

@@ -0,0 +1,312 @@
+/**
+ * `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 { FRAMEWORK_IDS } from '../../std/index.js';
+import { GfxControllerIdentifier, isPivotBound, readElementTags, } from '../../std/gfx/index.js';
+import { effect } from '@preact/signals-core';
+import { PivotPropertiesProvider, publishOccurrenceMaterialities, } from './pivot-properties-service.js';
+/** Props whose change can alter what a patch says. Everything else is noise. */
+const MATERIAL_PROPS = new Set(['tags', 'role', 'pivotDocId']);
+const touchesMateriality = (payload) => Object.keys(payload.props).some(key => MATERIAL_PROPS.has(key)) ||
+    Object.keys(payload.oldValues).some(key => MATERIAL_PROPS.has(key));
+/** `'wardley:component'` → `'wardley'`, when that names a real framework. */
+function frameworkOfRole(role) {
+    const namespace = role?.split(':')[0];
+    return FRAMEWORK_IDS.includes(namespace ?? '')
+        ? namespace
+        : undefined;
+}
+/**
+ * `(pivotDocId, elementId)` — the host's primary key for a derived materiality.
+ *
+ * The pair is JSON-encoded rather than joined on a separator character: both
+ * halves are opaque strings the library does not mint, so any separator we
+ * picked could in principle occur inside one of them and make two distinct
+ * occurrences collide on one cache entry — which would silently suppress a
+ * legitimate patch, the one failure mode this cache must not have.
+ */
+const materialityKey = (pivotDocId, elementId) => JSON.stringify([pivotDocId, elementId]);
+/** A patch reduced to what a host would store, for de-duplication. */
+const patchFingerprint = (patch) => JSON.stringify([
+    patch.present,
+    patch.framework ?? null,
+    patch.role ?? null,
+    // Sorted so that two writes of the same qualification in a different order
+    // are one patch, not two.
+    Object.keys(patch.tags)
+        .sort()
+        .map(tagId => [tagId, patch.tags[tagId]]),
+]);
+export class PivotMaterialityPublisher extends LifeCycleWatcher {
+    constructor() {
+        super(...arguments);
+        /** Elements whose state is to be re-examined at the end of this microtask. */
+        this._pending = new Set();
+        this._flushing = false;
+        /**
+         * 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.
+         */
+        this._lastBinding = new Map();
+        /**
+         * 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.
+         */
+        this._published = new Map();
+        this._subscriptions = [];
+        this._disposeSurfaceEffect = null;
+    }
+    static { this.key = 'pivot-materiality-publisher'; }
+    mounted() {
+        // Degradation, and the reason it is checked once: with no host provider —
+        // the playground, unit tests, a labreapp build that failed to register —
+        // there is nobody to announce to, so nothing is subscribed and the whole
+        // watcher costs one lookup. Binding and qualification keep working: they
+        // are element-local writes and never needed the host.
+        if (!this.std.getOptional(PivotPropertiesProvider)
+            ?.publishOccurrenceMaterialities) {
+            return;
+        }
+        // The surface is a SIGNAL, not a fact: it can legitimately be null at mount
+        // and arrive later, and it is replaced if the surface block is.
+        this._disposeSurfaceEffect = effect(() => {
+            this._resubscribe(this.std.get(GfxControllerIdentifier).surface$.value);
+        });
+    }
+    unmounted() {
+        this._disposeSurfaceEffect?.();
+        this._disposeSurfaceEffect = null;
+        this._unsubscribe();
+        this._pending.clear();
+        this._lastBinding.clear();
+        this._published.clear();
+        super.unmounted();
+    }
+    _unsubscribe() {
+        for (const subscription of this._subscriptions)
+            subscription.unsubscribe();
+        this._subscriptions = [];
+    }
+    _resubscribe(surface) {
+        this._unsubscribe();
+        this._pending.clear();
+        // A new surface is a new document: nothing published about the last one
+        // says anything about this one.
+        this._lastBinding.clear();
+        this._published.clear();
+        if (!surface)
+            return;
+        this._subscriptions.push(surface.elementAdded.subscribe(({ id, local }) => {
+            if (local)
+                this._schedule(surface, id);
+            else
+                this._track(surface, id);
+        }));
+        this._subscriptions.push(surface.elementUpdated.subscribe(payload => {
+            if (!touchesMateriality(payload))
+                return;
+            if (payload.local)
+                this._schedule(surface, payload.id);
+            else
+                this._track(surface, payload.id);
+        }));
+        this._subscriptions.push(surface.elementRemoved.subscribe(({ id, local }) => {
+            if (!local) {
+                // Someone else's deletion is someone else's retraction to emit. Drop
+                // the bookkeeping so a later occurrence reusing this id — an undo on
+                // the peer, a paste — is not silenced by a stale fingerprint.
+                const previous = this._lastBinding.get(id);
+                if (previous !== undefined) {
+                    this._published.delete(materialityKey(previous, id));
+                }
+                this._lastBinding.delete(id);
+                return;
+            }
+            // The element is already gone from the surface, so the flush below
+            // cannot read it — which is exactly right: an absent element retracts.
+            this._schedule(surface, id);
+        }));
+        // Elements already on the surface when this mounts are NOT published. They
+        // are not a local change, and republishing a whole board on every editor
+        // open would flood the host with patches it already holds. The rebuild path
+        // (`collectPivotOccurrences`) is the deliberate way to resynchronise.
+        for (const element of surface.elementModels)
+            this._track(surface, element.id);
+    }
+    /**
+     * 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.
+     */
+    _track(surface, id) {
+        const element = surface.getElementById(id);
+        const previous = this._lastBinding.get(id);
+        if (previous !== undefined) {
+            this._published.delete(materialityKey(previous, id));
+        }
+        if (element && isPivotBound(element)) {
+            this._lastBinding.set(id, element.pivotDocId);
+        }
+        else {
+            this._lastBinding.delete(id);
+        }
+    }
+    /**
+     * 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.
+     */
+    _schedule(surface, id) {
+        this._pending.add(id);
+        if (this._flushing)
+            return;
+        this._flushing = true;
+        queueMicrotask(() => {
+            this._flushing = false;
+            const ids = [...this._pending];
+            this._pending.clear();
+            for (const pending of ids)
+                this._publish(surface, pending);
+        });
+    }
+    _publish(surface, id) {
+        const element = surface.getElementById(id) ?? null;
+        const previous = this._lastBinding.get(id);
+        const current = element && isPivotBound(element) ? element.pivotDocId : undefined;
+        // Retract on the OLD record when the binding is gone or has moved. An
+        // element deleted, unbound, or re-bound elsewhere must not leave the record
+        // holding materialities attributed to an occurrence that no longer exists
+        // there — "the library never deletes host data" would quietly become "the
+        // library leaks host data" (ADR 0006 § 4.3).
+        if (previous !== undefined && previous !== current) {
+            this._emit({
+                pivotDocId: previous,
+                elementId: id,
+                framework: undefined,
+                role: undefined,
+                tags: {},
+                present: false,
+            });
+            this._lastBinding.delete(id);
+            this._published.delete(materialityKey(previous, id));
+        }
+        if (!element || current === undefined)
+            return;
+        this._lastBinding.set(id, current);
+        this._emit(buildOccurrencePatch(element, current));
+    }
+    _emit(patch) {
+        const key = materialityKey(patch.pivotDocId, patch.elementId);
+        const fingerprint = patchFingerprint(patch);
+        if (this._published.get(key) === fingerprint)
+            return;
+        if (patch.present)
+            this._published.set(key, fingerprint);
+        else
+            this._published.delete(key);
+        // Guarded, fire-and-forget: a throwing host is swallowed, because there is
+        // nothing a caller could do with the failure and the element remains the
+        // source of truth either way.
+        publishOccurrenceMaterialities(this.std, patch);
+    }
+}
+/**
+ * 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 function buildOccurrencePatch(element, pivotDocId) {
+    return {
+        pivotDocId,
+        elementId: element.id,
+        framework: frameworkOfRole(element.role),
+        role: element.role,
+        // A flattened snapshot: a transport DTO, not the persisted shape. On the
+        // element the same data is a nested `Y.Map<string[]>` so that concurrent
+        // qualification merges per tag.
+        tags: readElementTags(element),
+        present: true,
+    };
+}

package/dist/_pkgs/affine-shared/services/pivot-properties-service.d.ts

@@ -0,0 +1,217 @@
+import type { BlockStdScope, FrameworkId } from '../../std/index.js';
+import type { ExtensionType } from '../../store/index.js';
+import type { ReadonlySignal } from '@preact/signals-core';
+/**
+ * Typed, render-free property values. No markup, ever — not a `TemplateResult`,
+ * not an HTML string, not a component reference (ADR 0006 § 5).
+ *
+ * Consumers MUST handle this union exhaustively **with a default branch**: an
+ * unknown `kind` renders as nothing and never throws, which is what lets a new
+ * value kind ship without breaking an older host or an older library. Treat the
+ * union as public API — adding a kind is cheap, changing one is a breaking
+ * change for every host.
+ */
+export type PivotPropertyValue = {
+    kind: 'text';
+    value: string;
+} | {
+    kind: 'number';
+    value: number;
+    unit?: string;
+} | {
+    kind: 'boolean';
+    value: boolean;
+} | {
+    kind: 'date';
+    value: string;
+} | {
+    kind: 'tags';
+    value: string[];
+} | {
+    kind: 'user';
+    value: {
+        id: string;
+        name: string;
+    };
+} | {
+    kind: 'ref';
+    value: {
+        docId: string;
+        label?: string;
+    };
+};
+export type PivotProperty = {
+    /** Stable, host-defined key. Used for ordering and diffing, not display. */
+    key: string;
+    /** Display label, already localized by the host. */
+    label: string;
+    value: PivotPropertyValue;
+    /**
+     * Where the value came from. `derived-from-occurrence` marks properties the
+     * host wrote back from a board occurrence (see {@link
+     * OccurrenceMaterialityPatch}); the library renders them distinctly and never
+     * lets the user edit them here.
+     */
+    provenance?: 'authored' | 'derived-from-occurrence';
+};
+export type PivotSnapshot = {
+    docId: string;
+    title: string;
+    /** Host-ordered. The library preserves the order and does not sort. */
+    properties: PivotProperty[];
+};
+export type PivotQueryState = {
+    status: 'loading';
+} | {
+    status: 'ready';
+    snapshot: PivotSnapshot;
+}
+/** The binding is dangling: record deleted, or not visible to this user. */
+ | {
+    status: 'missing';
+} | {
+    status: 'error';
+    reason?: string;
+};
+/** Which properties a consuming surface asks for. */
+export type PivotPropertiesConfig = {
+    /**
+     * Property keys the hover popup displays, in this order. The provider MUST
+     * load and return ONLY these.
+     *
+     * `[]` disables the asynchronous complement entirely while keeping the
+     * provider registered: the library does not call `properties$` **at all** —
+     * not "calls it and ignores the answer". No call, no request, no work. It is
+     * the deliberate opt-out for hosts that want the hover to stay purely local.
+     */
+    hoverFields: readonly string[];
+};
+/**
+ * One occurrence's derived contribution to a pivot record, announced and
+ * forgotten. The library never writes to the pivot record and never observes
+ * the result (ADR 0006 § 4).
+ *
+ * Declared here — ahead of the `PivotMaterialityPublisher` that will emit it,
+ * which waits on the type-3 qualification of ADR 0007 — because ADRs 0005,
+ * 0006 and 0007 freeze ONE contract: a host implementing this interface today
+ * must be able to implement the whole of it, and the optional method must not
+ * change shape when the publisher lands.
+ */
+export type OccurrenceMaterialityPatch = {
+    /** The bound pivot record. */
+    pivotDocId: string;
+    /**
+     * Which occurrence this patch describes. The host's primary key, together
+     * with `pivotDocId` — derived materialities are stored per occurrence, which
+     * is what lets one be retracted precisely when its element disappears while
+     * the record's other occurrences keep theirs (ADR 0006 § 4.3/4.4).
+     */
+    elementId: string;
+    /**
+     * Owning framework, when the occurrence has one — derived from the namespace
+     * of its `role` (`'wardley:component'` → `'wardley'`).
+     *
+     * OPTIONAL, which is a deviation from ADR 0006 § 4's `framework: FrameworkId`,
+     * for exactly the reason ADR 0007 § 7 was already amended on the twin
+     * telemetry field: ADR 0007 § 6 states that no rung of the ladder requires
+     * the previous one, so a plain rectangle bound to a pivot record — no role at
+     * all — is a legal state that belongs to no framework. A required field would
+     * oblige the library to invent an identity, which is the one thing taking
+     * `FrameworkId` from ADR 0008 exists to stop. Absent rather than `'unknown'`,
+     * per the repo convention.
+     */
+    framework?: FrameworkId;
+    /** Role id, e.g. `'wardley:component'`. `undefined` once the role is cleared. */
+    role: string | undefined;
+    /**
+     * Type-3 tags: tag def id -> selected value ids. `{}` = cleared. A plain
+     * object on purpose: this is a transport DTO, not the persisted shape.
+     */
+    tags: Record<string, string[]>;
+    /**
+     * `false` = this occurrence no longer exists (element deleted, or unbound).
+     * The host drops every derived materiality keyed by `(pivotDocId, elementId)`.
+     * When `false`, `role` is `undefined` and `tags` is `{}`.
+     */
+    present: boolean;
+};
+export interface PivotPropertiesService {
+    /**
+     * MUST return synchronously and MUST NOT throw. The returned signal may start
+     * at `loading` and settle later; the library never awaits it. Caching,
+     * deduplication, revalidation and cancellation are the host's business —
+     * `fields` is part of the cache key.
+     *
+     * `fields` is the configured list, passed explicitly on every call. The
+     * provider MUST NOT load, compute, join or return properties outside it.
+     * Unknown or unauthorized keys are **skipped silently**: the provider returns
+     * the subset it can supply, never errors, never returns a placeholder row and
+     * never blocks the rest.
+     *
+     * The `MUST NOT throw` is a contract for hosts, not an assumption the library
+     * is entitled to make — it sits on the hover path, so
+     * {@link queryPivotProperties} guards it anyway.
+     */
+    properties$(pivotDocId: string, opts: {
+        fields: readonly string[];
+    }): ReadonlySignal<PivotQueryState>;
+    /**
+     * Optional zero-cost cache peek, for cases where the library wants to avoid
+     * even a `loading` flash. MUST be O(1) and side-effect free.
+     */
+    peek?(pivotDocId: string, opts: {
+        fields: readonly string[];
+    }): PivotSnapshot | undefined;
+    /**
+     * Fire-and-forget write-back of one occurrence's derived materialities.
+     * Returns `void`, deliberately not a `Promise`: the library cannot await it,
+     * retry it, or observe its failure. The channel is unidirectional and
+     * best-effort — a change on the record never mutates an element.
+     */
+    publishOccurrenceMaterialities?(patch: OccurrenceMaterialityPatch): void;
+}
+export declare const PivotPropertiesProvider: import("../../global/di/types.js").ServiceIdentifier<PivotPropertiesService> & (<U extends PivotPropertiesService = PivotPropertiesService>(variant: import("../../global/di/types.js").ServiceVariant) => import("../../global/di/types.js").ServiceIdentifier<U>);
+export declare const PivotPropertiesConfigIdentifier: import("../../global/di/types.js").ServiceIdentifier<PivotPropertiesConfig> & (<U extends PivotPropertiesConfig = PivotPropertiesConfig>(variant: import("../../global/di/types.js").ServiceVariant) => import("../../global/di/types.js").ServiceIdentifier<U>);
+/**
+ * The ONLY way in. **No noop default is registered**: unlike telemetry — where
+ * a noop keeps the bus uniformly wired — absence here is a *meaningful* state
+ * (standalone playground, unit tests, a labreapp build that failed to
+ * register), and making it the tested default is what keeps the degraded path
+ * honest.
+ */
+export declare function PivotPropertiesExtension(service: PivotPropertiesService, config: PivotPropertiesConfig): ExtensionType;
+/**
+ * The guarded read every in-library consumer uses. Synchronous by construction,
+ * and the one place the provider contract is enforced rather than trusted:
+ *
+ * - **No provider registered** → `undefined`. Not a call, not a state: the
+ *   asynchronous complement does not exist in this assembly. The caller renders
+ *   its local facts only — no spinner, no empty "Properties" section, no error
+ *   — and hides (rather than disables) any affordance whose *only* purpose is
+ *   to reach the record, per the `QuickSearchProvider` precedent.
+ * - **`hoverFields` empty, or no config registered** → `undefined`, and the
+ *   provider is **not called at all**. Absent config with a provider present is
+ *   a host wiring error, not a crash: it degrades to `hoverFields: []`, whose
+ *   observable behaviour is identical to no provider.
+ * - **The provider throws** → `{ status: 'error' }`. A host's broken build must
+ *   not become a crash-on-hover.
+ *
+ * `undefined` is deliberately NOT folded into `{ status: 'missing' }`: `missing`
+ * means "the binding is dangling — the record was deleted, or you cannot see
+ * it", which is a fact worth one discreet line. "This editor has no host data
+ * layer" is not that fact, and rendering it as one would put an error in front
+ * of every standalone user.
+ */
+export declare function queryPivotProperties(std: BlockStdScope, pivotDocId: string): ReadonlySignal<PivotQueryState> | undefined;
+/**
+ * The guarded `peek`. Same rules as {@link queryPivotProperties}, and a throw
+ * is swallowed into `undefined` — a cache peek exists to avoid a flash, so
+ * failing it must cost nothing but the flash.
+ */
+export declare function peekPivotProperties(std: BlockStdScope, pivotDocId: string): PivotSnapshot | undefined;
+/**
+ * The guarded write-back. Fire-and-forget by contract, so a throwing host is
+ * swallowed rather than surfaced: there is nothing a caller could do with the
+ * failure, and the element remains the source of truth either way.
+ */
+export declare function publishOccurrenceMaterialities(std: BlockStdScope, patch: OccurrenceMaterialityPatch): void;

package/dist/_pkgs/affine-shared/services/pivot-properties-service.js

@@ -0,0 +1,114 @@
+/**
+ * `PivotPropertiesProvider` — the injectable `pivotDocId` → properties seam
+ * (MF1, ADR 0006).
+ *
+ * ADR 0005 gives a surface element an optional `pivotDocId` pointing at a
+ * host-owned **pivot record**. This is what turns that string into something a
+ * user can see, without the library ever learning what a pivot record is, and
+ * without the host's data layer getting between the user and their gesture.
+ *
+ * Two properties carry the whole design:
+ *
+ * - `properties$` returns a `ReadonlySignal` **synchronously**. There is no
+ *   `Promise`-returning method on the read path, so no call site can `await`
+ *   one — blocking is structurally impossible, not merely discouraged. Same
+ *   shape as `DocDisplayMetaExtension`, minus the one thing worth not copying:
+ *   the host never hands the library rendered markup.
+ * - The popup's content is host-configured (`hoverFields`), and that is a
+ *   performance contract: a pivot record may carry dozens of properties,
+ *   several of them expensive, and a hover must not pay for what it will not
+ *   draw.
+ */
+import { createIdentifier } from '../../global/di/index.js';
+import { computed } from '@preact/signals-core';
+export const PivotPropertiesProvider = createIdentifier('LabrePivotPropertiesService');
+export const PivotPropertiesConfigIdentifier = createIdentifier('LabrePivotPropertiesConfig');
+/**
+ * The ONLY way in. **No noop default is registered**: unlike telemetry — where
+ * a noop keeps the bus uniformly wired — absence here is a *meaningful* state
+ * (standalone playground, unit tests, a labreapp build that failed to
+ * register), and making it the tested default is what keeps the degraded path
+ * honest.
+ */
+export function PivotPropertiesExtension(service, config) {
+    return {
+        setup: di => {
+            di.override(PivotPropertiesProvider, () => service);
+            di.override(PivotPropertiesConfigIdentifier, () => config);
+        },
+    };
+}
+const errorState = (reason) => computed(() => ({ status: 'error', reason }));
+/**
+ * The guarded read every in-library consumer uses. Synchronous by construction,
+ * and the one place the provider contract is enforced rather than trusted:
+ *
+ * - **No provider registered** → `undefined`. Not a call, not a state: the
+ *   asynchronous complement does not exist in this assembly. The caller renders
+ *   its local facts only — no spinner, no empty "Properties" section, no error
+ *   — and hides (rather than disables) any affordance whose *only* purpose is
+ *   to reach the record, per the `QuickSearchProvider` precedent.
+ * - **`hoverFields` empty, or no config registered** → `undefined`, and the
+ *   provider is **not called at all**. Absent config with a provider present is
+ *   a host wiring error, not a crash: it degrades to `hoverFields: []`, whose
+ *   observable behaviour is identical to no provider.
+ * - **The provider throws** → `{ status: 'error' }`. A host's broken build must
+ *   not become a crash-on-hover.
+ *
+ * `undefined` is deliberately NOT folded into `{ status: 'missing' }`: `missing`
+ * means "the binding is dangling — the record was deleted, or you cannot see
+ * it", which is a fact worth one discreet line. "This editor has no host data
+ * layer" is not that fact, and rendering it as one would put an error in front
+ * of every standalone user.
+ */
+export function queryPivotProperties(std, pivotDocId) {
+    const provider = std.getOptional(PivotPropertiesProvider);
+    if (!provider)
+        return undefined;
+    const fields = std.getOptional(PivotPropertiesConfigIdentifier)?.hoverFields;
+    if (!fields?.length)
+        return undefined;
+    try {
+        return provider.properties$(pivotDocId, { fields });
+    }
+    catch (error) {
+        console.error('PivotPropertiesProvider.properties$ threw', error);
+        return errorState(error instanceof Error ? error.message : String(error));
+    }
+}
+/**
+ * The guarded `peek`. Same rules as {@link queryPivotProperties}, and a throw
+ * is swallowed into `undefined` — a cache peek exists to avoid a flash, so
+ * failing it must cost nothing but the flash.
+ */
+export function peekPivotProperties(std, pivotDocId) {
+    const provider = std.getOptional(PivotPropertiesProvider);
+    if (!provider?.peek)
+        return undefined;
+    const fields = std.getOptional(PivotPropertiesConfigIdentifier)?.hoverFields;
+    if (!fields?.length)
+        return undefined;
+    try {
+        return provider.peek(pivotDocId, { fields });
+    }
+    catch (error) {
+        console.error('PivotPropertiesProvider.peek threw', error);
+        return undefined;
+    }
+}
+/**
+ * The guarded write-back. Fire-and-forget by contract, so a throwing host is
+ * swallowed rather than surfaced: there is nothing a caller could do with the
+ * failure, and the element remains the source of truth either way.
+ */
+export function publishOccurrenceMaterialities(std, patch) {
+    const provider = std.getOptional(PivotPropertiesProvider);
+    if (!provider?.publishOccurrenceMaterialities)
+        return;
+    try {
+        provider.publishOccurrenceMaterialities(patch);
+    }
+    catch (error) {
+        console.error('PivotPropertiesProvider.publishOccurrenceMaterialities threw', error);
+    }
+}

package/dist/_pkgs/affine-shared/services/telemetry-service/code-block.d.ts

@@ -1,3 +1,3 @@
 import type { TelemetryEvent } from './types.js';
-export type CodeBlockEventType = 'codeBlockLanguageSelect' | 'htmlBlockTogglePreview' | 'htmlBlockPreviewFailed';
+export type CodeBlockEventType = 'codeBlockLanguageSelect' | 'codeBlockToggleCollapse' | 'htmlBlockTogglePreview' | 'htmlBlockPreviewFailed';
 export type CodeBlockEvents = Record<CodeBlockEventType, TelemetryEvent>;