@formicoidea/labre-core 0.31.0 → 0.32.0

package/dist/_pkgs/affine-shared/services/universe-tag-defs-service.d.ts

@@ -0,0 +1,155 @@
+import type { BlockStdScope, FrameworkId } from '../../std/index.js';
+import type { RoleDefs, RoleId } from '../../std/gfx/index.js';
+import type { ExtensionType } from '../../store/index.js';
+/**
+ * `'<framework>:<local>'` — e.g. `'wardley:component'`, `'wardley:nature'`.
+ *
+ * A **seed-time** validation aid only. Persisted values are plain `string`s and
+ * are never narrowed to this, because a document may legitimately carry an id
+ * whose def was removed, renamed or never seeded in this deployment — and it
+ * must still open.
+ */
+export type QualifiedId = `${string}:${string}`;
+/** `'<tagId>/<local>'` — e.g. `'wardley:nature/data'`. */
+export type TagValueId = string;
+export type TagValueDef = {
+    /** `'<tagId>/<local>'`, e.g. `'wardley:nature/data'`. */
+    id: TagValueId;
+    /** Display label, already localized by the host. */
+    label: string;
+    description?: string;
+    /** Advisory colour token. The library may ignore it; it never affects layout. */
+    color?: string;
+    /** Hidden from pickers; still displayed when already present on an element. */
+    deprecated?: boolean;
+};
+export type TagDef = {
+    /** `'<framework>:<local>'`, e.g. `'wardley:nature'`. */
+    id: QualifiedId;
+    label: string;
+    description?: string;
+    /** How many values an element may carry for this tag. */
+    cardinality: 'single' | 'multi';
+    /** A closed list, or `'open'` for free-text values. */
+    values: TagValueDef[] | 'open';
+    /**
+     * Role ids this tag qualifies. `'*'` = every role of this framework.
+     * Specialisation applies: a tag on `'wardley:component'` also applies to
+     * every role whose `parent` chain reaches it — resolved with `roleIsA`
+     * against the framework's own `RoleDefs`, which the CALLER supplies.
+     */
+    appliesTo: RoleId[] | '*';
+    /**
+     * Advisory only. A missing "required" tag is reported by the rules engine; it
+     * NEVER blocks a gesture, a save, or a document load.
+     */
+    required?: boolean;
+    /** Ascending display order. Ties broken by seed order, then by id. */
+    order?: number;
+    deprecated?: boolean;
+};
+/**
+ * One pack of tag definitions. Plain data — no functions, no classes, no
+ * `Symbol` — so the TS type IS the JSON schema and a pack can ship as a `.json`
+ * asset.
+ *
+ * `roles` is deliberately absent: roles are lib-side data modules shipped by
+ * the framework that renders them (`WARDLEY_ROLES`), not app-seeded, and never
+ * pass through this registry (ADR 0007 § 2bis).
+ */
+export type UniverseTagDefs = {
+    /** Bumped only on a breaking change to THIS format. Currently 1. */
+    formatVersion: 1;
+    /**
+     * Unique id of this *pack*, not of the framework: several packs may extend
+     * the same framework (a base Wardley pack + a client's private extension).
+     * Doubles as the DI variant.
+     */
+    packId: string;
+    framework: FrameworkId;
+    label: string;
+    tags: TagDef[];
+};
+/** A seed-time problem, for a host diagnostics panel. Never thrown. */
+export type UniverseDefIssue = {
+    severity: 'warning' | 'error';
+    code: 'invalid-id' | 'cross-framework-id' | 'duplicate-conflict' | 'unsupported-format-version';
+    id?: string;
+    message: string;
+};
+/**
+ * Merged, validated, read-only view over the registered packs. **TAGS ONLY.**
+ */
+export interface UniverseRegistry {
+    frameworks(): FrameworkId[];
+    /**
+     * Tags applying to a role, ordered. Role specialisation is resolved with
+     * `roleIsA` against the framework's own `RoleDefs`, which the caller supplies
+     * — the registry holds no role vocabulary of its own.
+     */
+    tagsForRole(roleId: RoleId, defs: RoleDefs): TagDef[];
+    tag(id: string): TagDef | undefined;
+    /** Every merged tag, ordered. */
+    tags(): TagDef[];
+    /** Seed-time problems. Never thrown. */
+    issues(): UniverseDefIssue[];
+}
+/**
+ * Variant-parameterized: **one registration per pack, keyed by `packId`** —
+ * the same mechanism as `SpotlightHostExtension(elementType)` and
+ * `ExternalGroupByConfigProvider(config.name)`.
+ */
+export declare const UniverseTagDefsProvider: import("../../global/di/types.js").ServiceIdentifier<UniverseTagDefs> & (<U extends UniverseTagDefs = UniverseTagDefs>(variant: import("../../global/di/types.js").ServiceVariant) => import("../../global/di/types.js").ServiceIdentifier<U>);
+/**
+ * Seed one or more packs.
+ *
+ * `di.override`, **not** `di.addImpl`: `addImpl` throws
+ * `DuplicateServiceDefinitionError` when the same `[scope, identifier, variant]`
+ * is registered twice, while `override` works whether or not a prior
+ * registration exists. That is exactly the idempotency this needs — **distinct
+ * `packId`s accumulate, identical `packId`s replace** — so a host that
+ * re-registers on every render never throws and never grows the registry.
+ *
+ * Order stability is load-bearing and non-obvious: `getAll` returns a
+ * `Map<ServiceVariant, T>`, and `Map.set` on an EXISTING key keeps that key's
+ * original insertion position. Re-seeding a pack therefore updates it in place
+ * rather than moving it to the end, so a re-registration cannot silently flip
+ * which pack wins a cosmetic field.
+ *
+ * **All packs MUST be registered in the same DI scope.** `getAllRaw` falls back
+ * to the parent scope only when the current scope has no registration for the
+ * identifier AT ALL; it never merges across scopes. Seeding one pack from a
+ * `StoreExtension` and another from a `ViewExtension` would silently hide the
+ * first behind the second. The library cannot enforce this, so it is stated
+ * here and belongs in the host integration checklist.
+ */
+export declare function UniverseTagDefsExtension(defs: UniverseTagDefs | UniverseTagDefs[]): ExtensionType;
+/**
+ * Merge every registered pack into one read-only view.
+ *
+ * Pure, so it is testable with literals and no container. The merge rules, in
+ * full:
+ *
+ * - **Union by id.** Several packs may extend the same universe.
+ * - **Additive fields merge:** `values` are unioned by value id, `appliesTo`
+ *   arrays are unioned, and `'*'` absorbs any list.
+ * - **Cosmetic fields — last pack wins:** `label`, `description`, `color`,
+ *   `order`, `required`, `deprecated`.
+ * - **Structural fields — first pack wins, conflict recorded:** `cardinality`,
+ *   and `values: 'open'` vs a closed list. The conflict becomes a
+ *   `duplicate-conflict` error issue and does NOT throw. A host that needs a
+ *   deterministic winner should not define the same structural field twice; the
+ *   registry reports the collision rather than guessing.
+ * - **Idempotent by value.** Activating a universe twice yields the same
+ *   registry.
+ */
+export declare function buildUniverseRegistry(packs: readonly UniverseTagDefs[]): UniverseRegistry;
+/**
+ * Whether a tag qualifies a role, following specialisation: a tag declared on
+ * `'wardley:component'` also applies to `'wardley:market'`, which specialises
+ * it. `'*'` matches every role of the tag's own framework and nothing else —
+ * a wildcard that crossed framework boundaries would make two taxonomies
+ * qualify each other's elements.
+ */
+export declare function tagAppliesToRole(def: TagDef, roleId: RoleId | undefined, defs: RoleDefs): boolean;
+export declare function getUniverseRegistry(std: BlockStdScope): UniverseRegistry;

package/dist/_pkgs/affine-shared/services/universe-tag-defs-service.js

@@ -0,0 +1,254 @@
+/**
+ * Per-universe tag definitions — the format, the seeding mechanism and the
+ * merged read-only view over them (MF3 / ADR 0007 §§ 2 and 3).
+ *
+ * The **application seeds** the definitions per universe; the **library fixes
+ * their format**. That split is the whole point: a new business universe
+ * (cynefin, TOGAF, a client's private taxonomy) must be addable without
+ * shipping library code. The library ships exactly one pack of its own —
+ * Wardley's four natures — as a worked example, on the same mechanism a host
+ * would use.
+ *
+ * Three rules govern everything below, and they are not negotiable:
+ *
+ * - **Nothing throws, ever.** An invalid id, a cross-framework id, an
+ *   unrecognised `formatVersion` — each drops the offending def and records an
+ *   issue. A malformed seed must never prevent a document from opening. That is
+ *   the hard boundary between "the app misconfigured a pack" and "the user lost
+ *   their board".
+ * - **Defs are runtime configuration and are NEVER persisted.** The document
+ *   stores ids only. A value whose def has vanished still loads and is shown as
+ *   its raw id, marked unknown.
+ * - **Ids are forever.** A def is never removed, only `deprecated`.
+ */
+import { createIdentifier } from '../../global/di/index.js';
+import { FRAMEWORK_IDS } from '../../std/index.js';
+import { roleIsA } from '../../std/gfx/index.js';
+/**
+ * Lower-kebab, case-sensitive, no unicode, no dots. Hyphenated framework ids
+ * are legal, so `cynefin-estuarine:domain` is well formed.
+ */
+const ID_PATTERN = /^[a-z0-9][a-z0-9-]*:[a-z0-9][a-z0-9-]*(\/[a-z0-9][a-z0-9-]*)?$/;
+/**
+ * Variant-parameterized: **one registration per pack, keyed by `packId`** —
+ * the same mechanism as `SpotlightHostExtension(elementType)` and
+ * `ExternalGroupByConfigProvider(config.name)`.
+ */
+export const UniverseTagDefsProvider = createIdentifier('LabreUniverseTagDefs');
+/**
+ * Seed one or more packs.
+ *
+ * `di.override`, **not** `di.addImpl`: `addImpl` throws
+ * `DuplicateServiceDefinitionError` when the same `[scope, identifier, variant]`
+ * is registered twice, while `override` works whether or not a prior
+ * registration exists. That is exactly the idempotency this needs — **distinct
+ * `packId`s accumulate, identical `packId`s replace** — so a host that
+ * re-registers on every render never throws and never grows the registry.
+ *
+ * Order stability is load-bearing and non-obvious: `getAll` returns a
+ * `Map<ServiceVariant, T>`, and `Map.set` on an EXISTING key keeps that key's
+ * original insertion position. Re-seeding a pack therefore updates it in place
+ * rather than moving it to the end, so a re-registration cannot silently flip
+ * which pack wins a cosmetic field.
+ *
+ * **All packs MUST be registered in the same DI scope.** `getAllRaw` falls back
+ * to the parent scope only when the current scope has no registration for the
+ * identifier AT ALL; it never merges across scopes. Seeding one pack from a
+ * `StoreExtension` and another from a `ViewExtension` would silently hide the
+ * first behind the second. The library cannot enforce this, so it is stated
+ * here and belongs in the host integration checklist.
+ */
+export function UniverseTagDefsExtension(defs) {
+    return {
+        setup: di => {
+            for (const pack of Array.isArray(defs) ? defs : [defs]) {
+                di.override(UniverseTagDefsProvider(pack.packId), () => pack);
+            }
+        },
+    };
+}
+/** `'wardley:nature'` → `'wardley'`. */
+const namespaceOf = (id) => id.split(':')[0] ?? '';
+/** `'wardley:nature/data'` → `'wardley:nature'`. */
+const tagOfValue = (valueId) => valueId.split('/')[0] ?? '';
+/**
+ * Merge every registered pack into one read-only view.
+ *
+ * Pure, so it is testable with literals and no container. The merge rules, in
+ * full:
+ *
+ * - **Union by id.** Several packs may extend the same universe.
+ * - **Additive fields merge:** `values` are unioned by value id, `appliesTo`
+ *   arrays are unioned, and `'*'` absorbs any list.
+ * - **Cosmetic fields — last pack wins:** `label`, `description`, `color`,
+ *   `order`, `required`, `deprecated`.
+ * - **Structural fields — first pack wins, conflict recorded:** `cardinality`,
+ *   and `values: 'open'` vs a closed list. The conflict becomes a
+ *   `duplicate-conflict` error issue and does NOT throw. A host that needs a
+ *   deterministic winner should not define the same structural field twice; the
+ *   registry reports the collision rather than guessing.
+ * - **Idempotent by value.** Activating a universe twice yields the same
+ *   registry.
+ */
+export function buildUniverseRegistry(packs) {
+    const issues = [];
+    const drafts = new Map();
+    const frameworks = [];
+    let rank = 0;
+    const issue = (severity, code, message, id) => issues.push(id === undefined ? { severity, code, message } : { severity, code, id, message });
+    for (const pack of packs) {
+        if (pack?.formatVersion !== 1) {
+            // The WHOLE pack is dropped: a format we do not understand may mean
+            // anything. Documents still open; the tooling is simply unavailable.
+            issue('error', 'unsupported-format-version', `Pack "${pack?.packId ?? '<unnamed>'}" declares formatVersion ${String(pack?.formatVersion)}; this build understands 1. The pack is ignored.`, pack?.packId);
+            continue;
+        }
+        if (!FRAMEWORK_IDS.includes(pack.framework)) {
+            issue('warning', 'cross-framework-id', `Pack "${pack.packId}" declares the unknown framework "${pack.framework}".`, pack.packId);
+        }
+        if (!frameworks.includes(pack.framework))
+            frameworks.push(pack.framework);
+        for (const def of pack.tags ?? []) {
+            if (typeof def?.id !== 'string' || !ID_PATTERN.test(def.id)) {
+                issue('error', 'invalid-id', `Tag id "${String(def?.id)}" in pack "${pack.packId}" is not a well-formed '<framework>:<local>' id.`, typeof def?.id === 'string' ? def.id : undefined);
+                continue;
+            }
+            // The `<framework>` segment of every id in a pack MUST equal the pack's
+            // own framework. A cross-framework id is how one taxonomy would quietly
+            // start answering for another's roles.
+            if (namespaceOf(def.id) !== pack.framework) {
+                issue('error', 'cross-framework-id', `Tag "${def.id}" is namespaced "${namespaceOf(def.id)}" but pack "${pack.packId}" declares framework "${pack.framework}".`, def.id);
+                continue;
+            }
+            mergeTagDef(drafts, def, pack, issue, rank++);
+        }
+    }
+    const merged = [...drafts.values()]
+        .map(draft => finishDraft(draft))
+        .sort((a, b) => (a.order ?? 0) - (b.order ?? 0) ||
+        (drafts.get(a.id).rank - drafts.get(b.id).rank) ||
+        a.id.localeCompare(b.id));
+    // Keyed by plain `string`, not by `QualifiedId`: a lookup comes from a
+    // DOCUMENT, which may carry any id at all, and the template-literal type is a
+    // seed-time aid rather than a claim about what is persisted.
+    const byId = new Map(merged.map(def => [def.id, def]));
+    return {
+        frameworks: () => [...frameworks],
+        tags: () => [...merged],
+        tag: id => byId.get(id),
+        tagsForRole: (roleId, defs) => merged.filter(def => tagAppliesToRole(def, roleId, defs)),
+        issues: () => [...issues],
+    };
+}
+function mergeTagDef(drafts, def, pack, issue, rank) {
+    const existing = drafts.get(def.id);
+    if (!existing) {
+        drafts.set(def.id, {
+            def: { ...def },
+            values: valueMapOf(def, pack, issue),
+            appliesTo: appliesToOf(def),
+            rank,
+        });
+        return;
+    }
+    // Cosmetic: last pack wins. Absent stays absent rather than blanking what an
+    // earlier pack said.
+    const draft = existing.def;
+    if (def.label !== undefined)
+        draft.label = def.label;
+    if (def.description !== undefined)
+        draft.description = def.description;
+    if (def.order !== undefined)
+        draft.order = def.order;
+    if (def.required !== undefined)
+        draft.required = def.required;
+    if (def.deprecated !== undefined)
+        draft.deprecated = def.deprecated;
+    // Structural: first pack wins, and the collision is REPORTED rather than
+    // guessed at.
+    if (def.cardinality !== draft.cardinality) {
+        issue('error', 'duplicate-conflict', `Tag "${def.id}": pack "${pack.packId}" declares cardinality "${def.cardinality}" but "${draft.cardinality}" was declared first and stands.`, def.id);
+    }
+    const incomingOpen = def.values === 'open';
+    const existingOpen = existing.values === 'open';
+    if (incomingOpen !== existingOpen) {
+        issue('error', 'duplicate-conflict', `Tag "${def.id}": pack "${pack.packId}" declares ${incomingOpen ? "an open value list" : 'a closed value list'} but the opposite was declared first and stands.`, def.id);
+    }
+    else if (existing.values !== 'open') {
+        // Additive: values union by value id, last cosmetic wins.
+        for (const [valueId, value] of valueMapOf(def, pack, issue)) {
+            const current = existing.values.get(valueId);
+            existing.values.set(valueId, current ? { ...current, ...value } : value);
+        }
+    }
+    // Additive: `'*'` absorbs any list, in either direction.
+    const incomingRoles = appliesToOf(def);
+    if (existing.appliesTo !== '*') {
+        if (incomingRoles === '*')
+            existing.appliesTo = '*';
+        else
+            for (const role of incomingRoles)
+                existing.appliesTo.add(role);
+    }
+}
+function valueMapOf(def, pack, issue) {
+    if (def.values === 'open')
+        return 'open';
+    const values = new Map();
+    for (const value of def.values ?? []) {
+        if (typeof value?.id !== 'string' || !ID_PATTERN.test(value.id)) {
+            issue('error', 'invalid-id', `Value id "${String(value?.id)}" of tag "${def.id}" in pack "${pack.packId}" is not a well-formed '<tagId>/<local>' id.`, typeof value?.id === 'string' ? value.id : undefined);
+            continue;
+        }
+        // A value belongs to its tag, spelled out in the id itself. Anything else
+        // would let a pack file a value under a tag it does not own.
+        if (tagOfValue(value.id) !== def.id) {
+            issue('error', 'invalid-id', `Value "${value.id}" is not a value of tag "${def.id}".`, value.id);
+            continue;
+        }
+        values.set(value.id, { ...value });
+    }
+    return values;
+}
+const appliesToOf = (def) => def.appliesTo === '*' ? '*' : new Set(def.appliesTo ?? []);
+function finishDraft(draft) {
+    return {
+        ...draft.def,
+        values: draft.values === 'open' ? 'open' : [...draft.values.values()],
+        appliesTo: draft.appliesTo === '*' ? '*' : [...draft.appliesTo],
+    };
+}
+/**
+ * Whether a tag qualifies a role, following specialisation: a tag declared on
+ * `'wardley:component'` also applies to `'wardley:market'`, which specialises
+ * it. `'*'` matches every role of the tag's own framework and nothing else —
+ * a wildcard that crossed framework boundaries would make two taxonomies
+ * qualify each other's elements.
+ */
+export function tagAppliesToRole(def, roleId, defs) {
+    if (!roleId)
+        return false;
+    if (def.appliesTo === '*')
+        return namespaceOf(roleId) === namespaceOf(def.id);
+    return def.appliesTo.some(ancestor => roleIsA(roleId, ancestor, defs));
+}
+/**
+ * The merged registry for this editor assembly.
+ *
+ * Memoized per `BlockStdScope`: the merge is pure and the packs are fixed at
+ * assembly time, while callers (a toolbar section rebuilt on every selection
+ * change) ask for it often. A host that re-seeds a pack after the first read
+ * therefore needs a new scope — which is what re-creating the editor already
+ * does, and the only cost of not re-validating a static configuration on every
+ * keystroke.
+ */
+const REGISTRY_CACHE = new WeakMap();
+export function getUniverseRegistry(std) {
+    const cached = REGISTRY_CACHE.get(std);
+    if (cached)
+        return cached;
+    const packs = [...std.provider.getAll(UniverseTagDefsProvider).values()];
+    const registry = buildUniverseRegistry(packs);
+    REGISTRY_CACHE.set(std, registry);
+    return registry;
+}

package/dist/_pkgs/affine-shared/utils/dom/point-to-range.d.ts

@@ -13,4 +13,8 @@ declare global {
 export declare function caretRangeFromPoint(clientX: number, clientY: number): Range | null;
 export declare function resetNativeSelection(range: Range | null): void;
 export declare function getCurrentNativeRange(selection?: Selection | null): Range | null;
+export declare const api: {
+    caretRangeFromPoint: typeof caretRangeFromPoint;
+    resetNativeSelection: typeof resetNativeSelection;
+};
 export declare function handleNativeRangeAtPoint(x: number, y: number): void;

package/dist/_pkgs/affine-shared/utils/dom/point-to-range.js

@@ -63,11 +63,67 @@ export function getCurrentNativeRange(selection = window.getSelection()) {
     }
     return selection.getRangeAt(0);
 }
+// Indirection so that unit tests can mock these two browser-bound functions.
+export const api = {
+    caretRangeFromPoint,
+    resetNativeSelection,
+};
 export function handleNativeRangeAtPoint(x, y) {
-    const range = caretRangeFromPoint(x, y);
+    const range = api.caretRangeFromPoint(x, y);
+    if (range) {
+        normalizeCaretRange(range);
+    }
     const startContainer = range?.startContainer;
     // click on rich text
     if (startContainer instanceof Node) {
-        resetNativeSelection(range);
+        api.resetNativeSelection(range);
+    }
+}
+function lastMeaningfulTextNode(node) {
+    const walker = document.createTreeWalker(node, NodeFilter.SHOW_TEXT, {
+        acceptNode(node) {
+            return node.textContent && node.textContent.trim().length > 0
+                ? NodeFilter.FILTER_ACCEPT
+                : NodeFilter.FILTER_REJECT;
+        },
+    });
+    let last = null;
+    while (walker.nextNode()) {
+        last = walker.currentNode;
+    }
+    return last;
+}
+/**
+ * Clicking past the end of a line gives back a caret anchored on an *element*
+ * rather than on a text node. Such a range paints a caret for a frame and then
+ * loses it, because the editor only tracks carets that live inside text. Move
+ * the caret to the nearest meaningful text node so that it survives.
+ */
+function normalizeCaretRange(range) {
+    const { startContainer, startOffset } = range;
+    if (startContainer.nodeType === Node.TEXT_NODE)
+        return;
+    // Try to find text in the element at `startOffset`
+    const offsetEl = startOffset > 0
+        ? startContainer.childNodes[startOffset - 1]
+        : startContainer.childNodes[0];
+    if (offsetEl) {
+        if (offsetEl.nodeType === Node.TEXT_NODE) {
+            range.setStart(offsetEl, startOffset > 0 ? (offsetEl.textContent?.length ?? 0) : 0);
+            range.collapse(true);
+            return;
+        }
+        const text = lastMeaningfulTextNode(offsetEl);
+        if (text) {
+            range.setStart(text, text.textContent?.length ?? 0);
+            range.collapse(true);
+            return;
+        }
+    }
+    // Fallback, try to find text in startContainer
+    const text = lastMeaningfulTextNode(startContainer);
+    if (text) {
+        range.setStart(text, text.textContent?.length ?? 0);
+        range.collapse(true);
     }
 }

package/dist/_pkgs/affine-shared/utils/dom/viewport.d.ts

@@ -11,3 +11,63 @@ import type { EditorHost } from '../../../std/index.js';
  * ```
  */
 export declare function getViewportElement(editorHost: EditorHost): HTMLElement | null;
+/**
+ * Where a model point lands, in CSS pixels, for an overlay drawn *inside* the
+ * edgeless container: the selection rectangle, the resize handles, the remote
+ * cursors, the text editors mounted over an element.
+ *
+ * `Viewport.toViewCoord` answers in real screen pixels, so it multiplies by
+ * `viewScale` — the CSS scale an outer container puts on the whole editor,
+ * which is not 1 in a nested editor such as an embedded synced edgeless doc.
+ * An overlay lives *inside* that container, so its placement has to be stated
+ * in the container's already scaled space, exactly the way
+ * `GfxBlockComponent.getCSSTransform` states a block's. Positioning an overlay
+ * from `toViewCoord` lets the container apply its scale a second time, and the
+ * overlay drifts away from the element it decorates as soon as
+ * `viewScale !== 1`.
+ */
+export declare function toOverlayCoord(viewport: {
+    viewportX: number;
+    viewportY: number;
+    zoom: number;
+    viewScale: number;
+}, modelX: number, modelY: number): [number, number];
+/**
+ * The scale an overlay drawn inside the edgeless container has to wear so that
+ * it ends up painted at the viewport zoom. Counterpart of
+ * {@link toOverlayCoord}; same reasoning about `viewScale`.
+ */
+export declare function overlayScale(viewport: {
+    zoom: number;
+    viewScale: number;
+}): number;
+/**
+ * How wide and tall the visible viewport is *in the same units as*
+ * {@link toOverlayCoord}, so an overlay can tell whether it is about to run off
+ * the edge.
+ *
+ * `Viewport.width` / `Viewport.height` are the bounding client rect, i.e. real
+ * screen pixels. Comparing an overlay coordinate against them mixes two spaces
+ * and the flip or the clamp fires at the wrong moment under a scaled host.
+ */
+export declare function overlayViewportSize(viewport: {
+    width: number;
+    height: number;
+    viewScale: number;
+}): [number, number];
+/**
+ * Where a model point lands in *client* coordinates — what
+ * `document.caretRangeFromPoint`, `elementFromPoint` and a `PointerEvent`'s
+ * `clientX`/`clientY` speak.
+ *
+ * `Viewport.toViewCoord` answers relative to the viewport element's own top
+ * left corner, so handing its result to a client-coordinate API drops the
+ * viewport's offset in the window: the caret lands elsewhere as soon as the
+ * editor is not flush against the window origin — a sidebar, a header, or the
+ * editor embedded in a panel. Inverse of `Viewport.toViewCoordFromClientCoord`.
+ */
+export declare function toClientCoord(viewport: {
+    left: number;
+    top: number;
+    toViewCoord: (modelX: number, modelY: number) => number[];
+}, modelX: number, modelY: number): [number, number];

package/dist/_pkgs/affine-shared/utils/dom/viewport.js

@@ -13,3 +13,61 @@ export function getViewportElement(editorHost) {
     return (editorHost.closest('.affine-page-viewport') ??
         editorHost.closest('.affine-edgeless-viewport'));
 }
+/**
+ * Where a model point lands, in CSS pixels, for an overlay drawn *inside* the
+ * edgeless container: the selection rectangle, the resize handles, the remote
+ * cursors, the text editors mounted over an element.
+ *
+ * `Viewport.toViewCoord` answers in real screen pixels, so it multiplies by
+ * `viewScale` — the CSS scale an outer container puts on the whole editor,
+ * which is not 1 in a nested editor such as an embedded synced edgeless doc.
+ * An overlay lives *inside* that container, so its placement has to be stated
+ * in the container's already scaled space, exactly the way
+ * `GfxBlockComponent.getCSSTransform` states a block's. Positioning an overlay
+ * from `toViewCoord` lets the container apply its scale a second time, and the
+ * overlay drifts away from the element it decorates as soon as
+ * `viewScale !== 1`.
+ */
+export function toOverlayCoord(viewport, modelX, modelY) {
+    const { viewportX, viewportY, zoom, viewScale } = viewport;
+    return [
+        ((modelX - viewportX) * zoom) / viewScale,
+        ((modelY - viewportY) * zoom) / viewScale,
+    ];
+}
+/**
+ * The scale an overlay drawn inside the edgeless container has to wear so that
+ * it ends up painted at the viewport zoom. Counterpart of
+ * {@link toOverlayCoord}; same reasoning about `viewScale`.
+ */
+export function overlayScale(viewport) {
+    return viewport.zoom / viewport.viewScale;
+}
+/**
+ * How wide and tall the visible viewport is *in the same units as*
+ * {@link toOverlayCoord}, so an overlay can tell whether it is about to run off
+ * the edge.
+ *
+ * `Viewport.width` / `Viewport.height` are the bounding client rect, i.e. real
+ * screen pixels. Comparing an overlay coordinate against them mixes two spaces
+ * and the flip or the clamp fires at the wrong moment under a scaled host.
+ */
+export function overlayViewportSize(viewport) {
+    const { width, height, viewScale } = viewport;
+    return [width / viewScale, height / viewScale];
+}
+/**
+ * Where a model point lands in *client* coordinates — what
+ * `document.caretRangeFromPoint`, `elementFromPoint` and a `PointerEvent`'s
+ * `clientX`/`clientY` speak.
+ *
+ * `Viewport.toViewCoord` answers relative to the viewport element's own top
+ * left corner, so handing its result to a client-coordinate API drops the
+ * viewport's offset in the window: the caret lands elsewhere as soon as the
+ * editor is not flush against the window origin — a sidebar, a header, or the
+ * editor embedded in a panel. Inverse of `Viewport.toViewCoordFromClientCoord`.
+ */
+export function toClientCoord(viewport, modelX, modelY) {
+    const [x, y] = viewport.toViewCoord(modelX, modelY);
+    return [x + viewport.left, y + viewport.top];
+}

package/dist/_pkgs/affine-shared/utils/print-to-pdf.d.ts

@@ -1,3 +1,24 @@
+/**
+ * Styles injected into the print iframe.
+ *
+ * The printed document is always rendered on white paper, so the whole
+ * palette is pinned to a light one: a document read in the dark theme would
+ * otherwise print light text on a background the printer leaves white, and
+ * every one of those elements would come out invisible.
+ *
+ * Exported so the print-fidelity rules can be asserted in unit tests.
+ */
+export declare const printToPdfStyles = "@media print {\n              html, body {\n                height: initial !important;\n                overflow: initial !important;\n                print-color-adjust: exact;\n                -webkit-print-color-adjust: exact;\n                color: #000 !important;\n                background: #fff !important;\n                color-scheme: light !important;\n              }\n              ::-webkit-scrollbar {\n                display: none;\n              }\n              :root, body {\n                --affine-text-primary: #000 !important;\n                --affine-text-secondary: #111 !important;\n                --affine-text-tertiary: #333 !important;\n                --affine-background-primary: #fff !important;\n                --affine-background-secondary: #fff !important;\n                --affine-background-tertiary: #fff !important;\n                --affine-background-code-block: #f5f5f5 !important;\n                --affine-quote-color: #e3e3e3 !important;\n                --affine-border-color: #e3e3e3 !important;\n              }\n              body, [data-theme='dark'] {\n                color: #000 !important;\n                background: #fff !important;\n              }\n              body * {\n                color: #000 !important;\n                -webkit-text-fill-color: #000 !important;\n              }\n              :root {\n                --affine-note-shadow-box: none !important;\n                --affine-note-shadow-sticker: none !important;\n              }\n            }";
+/**
+ * Waits until every image inside `container` — shadow roots included — has
+ * either decoded or given up.
+ *
+ * A print dialog opened while images are still in flight prints their empty
+ * frames, so this is awaited before handing the document to the printer. An
+ * image that fails to load resolves too: a broken picture must not hang the
+ * print for ever.
+ */
+export declare function waitForImages(container: HTMLElement): Promise<void>;
 export declare function printToPdf(rootElement?: HTMLElement | null, options?: {
     /**
      * Callback that is called when ready to print.