@formicoidea/labre-core 0.31.0 → 0.33.0

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

@@ -0,0 +1,256 @@
+/**
+ * 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/test-utils/affine-template.js

@@ -1,7 +1,7 @@
 import { CodeBlockSchemaExtension, DatabaseBlockSchemaExtension, ImageBlockSchemaExtension, ListBlockSchemaExtension, NoteBlockSchemaExtension, ParagraphBlockSchemaExtension, RootBlockSchemaExtension, } from '../../affine-model/index.js';
 import { Container } from '../../global/di/index.js';
 import { TextSelection } from '../../std/index.js';
-import { Text, } from '../../store/index.js';
+import { Text } from '../../store/index.js';
 import { TestWorkspace } from '../../store/test/index.js';
 import { createTestHost } from './create-test-host.js';
 const DEFAULT_EXTENSIONS = [

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/edgeless.js

@@ -1,5 +1,5 @@
 import { FrameBlockModel, GroupElementModel } from '../../affine-model/index.js';
-import { deserializeXYWH, getQuadBoundWithRotation, } from '../../global/gfx/index.js';
+import { deserializeXYWH, getQuadBoundWithRotation } from '../../global/gfx/index.js';
 export function getSelectedRect(selected) {
     if (selected.length === 0) {
         return new DOMRect();

package/dist/_pkgs/affine-shared/utils/file/filesys.d.ts

@@ -11,12 +11,46 @@ declare global {
         showOpenFilePicker?: (options?: OpenFilePickerOptions) => Promise<FileSystemFileHandle[]>;
     }
 }
+/**
+ * One filter a file dialog offers: what to call it, and the MIME types it
+ * accepts with the extensions that go with each.
+ *
+ * The table below is the CLOSED list of filters this library ships. It is not
+ * the only source of one: an interchange format declares its own extensions and
+ * mime (`docs/adr/0012`), and a picker built from a registry entry cannot be a
+ * row in a hand-maintained table — the whole point of the registry is that a
+ * framework adds a format without a second file agreeing to it. So the shape is
+ * named and {@link openSingleFileWithSpec} takes it directly; `FileTypes` keeps
+ * naming the filters that are the editor's own.
+ */
+export interface FilePickerSpec {
+    description: string;
+    accept: Record<string, string[]>;
+}
 /**
  * See https://web.dev/patterns/files/open-one-or-multiple-files/
+ *
+ * There is no `'Bpmn'` here any more, and no row for it above. A BPMN document
+ * is not the editor's own kind of file: it is one INTERCHANGE FORMAT among the
+ * several a framework declares (`docs/adr/0012`), and its filter is built from
+ * that declaration by {@link openSingleFileWithSpec}. Keeping a second copy in
+ * this table would be a copy nobody reads and everybody has to keep in step —
+ * the format's `extensions` and `mime` are the one statement of what a `.bpmn`
+ * file is called.
  */
 type AcceptTypes = 'Any' | 'Images' | 'Videos' | 'Audios' | 'Markdown' | 'Html' | 'Zip' | 'MindMap';
 export declare function openFilesWith(acceptType?: AcceptTypes, multiple?: boolean): Promise<File[] | null>;
 export declare function openSingleFileWith(acceptType?: AcceptTypes): Promise<File | null>;
+/**
+ * One file, filtered by a spec the caller built rather than by a name in
+ * {@link FileTypes}.
+ *
+ * What {@link openSingleFileWith} is for the editor's own dialogs, this is for
+ * anything whose filter is DECLARED somewhere else — today the interchange
+ * registry, whose formats each carry their extensions and their mime and are
+ * added by a framework, not by editing the table above.
+ */
+export declare function openSingleFileWithSpec(spec: FilePickerSpec): Promise<File | null>;
 export declare function getImageFilesFromLocal(): Promise<File[]>;
 export declare function downloadBlob(blob: Blob, name: string): void;
 /**

package/dist/_pkgs/affine-shared/utils/file/filesys.js

@@ -79,6 +79,27 @@ const FileTypes = [
     },
 ];
 export async function openFilesWith(acceptType = 'Any', multiple = true) {
+    if (acceptType === 'Any')
+        return openFilesWithSpec(undefined, multiple);
+    const fileType = FileTypes.find(i => i.description === acceptType);
+    if (!fileType) {
+        // Unreachable through the closed `AcceptTypes` union, and reported rather
+        // than thrown for the same reason it always was: the picker branch used to
+        // throw this inside its own try/catch, log it and answer `null`. A caller
+        // asking for a filter that does not exist gets no dialog, not an exception
+        // it never had to handle.
+        console.error(new BlockSuiteError(ErrorCode.DefaultRuntimeError, `Unexpected acceptType "${acceptType}"`));
+        return null;
+    }
+    return openFilesWithSpec(fileType, multiple);
+}
+/**
+ * The picker itself, over a filter rather than over a name in the table.
+ *
+ * `undefined` is "Any": no filter at all, which is what the dialog shows when
+ * nobody narrowed it.
+ */
+async function openFilesWithSpec(spec, multiple) {
     // Feature detection. The API needs to be supported
     // and the app not run in an iframe.
     const supportsFileSystemAccess = 'showOpenFilePicker' in window &&
@@ -93,11 +114,8 @@ export async function openFilesWith(acceptType = 'Any', multiple = true) {
     // If the File System Access API is supported…
     if (supportsFileSystemAccess && window.showOpenFilePicker) {
         try {
-            const fileType = FileTypes.find(i => i.description === acceptType);
-            if (acceptType !== 'Any' && !fileType)
-                throw new BlockSuiteError(ErrorCode.DefaultRuntimeError, `Unexpected acceptType "${acceptType}"`);
             const pickerOpts = {
-                types: fileType ? [fileType] : undefined,
+                types: spec ? [spec] : undefined,
                 multiple,
             };
             // Show the file picker, optionally allowing multiple files.
@@ -117,9 +135,19 @@ export async function openFilesWith(acceptType = 'Any', multiple = true) {
         input.style.display = 'none';
         input.type = 'file';
         input.multiple = multiple;
-        if (acceptType !== 'Any') {
-            // For example, `accept="image/*"` or `accept="video/*,audio/*"`.
-            input.accept = Object.keys(FileTypes.find(i => i.description === acceptType)?.accept ?? '').join(',');
+        if (spec) {
+            // For example, `accept="image/*,.png,.jpg"` or `accept="video/*,.mp4"`.
+            //
+            // The EXTENSIONS as well as the MIME types, and the extensions are the
+            // half that matters for anything the OS has no type for: `.bpmn`, `.mm`
+            // and `.opml` are registered nowhere, so a filter built from
+            // `application/xml` alone greys them out in the native dialog and the
+            // file cannot be picked at all. This is the branch every browser without
+            // the File System Access API takes — Firefox and Safari — and
+            // `showOpenFilePicker` above already reads both halves of the same
+            // filter.
+            const type = spec.accept;
+            input.accept = [...Object.keys(type), ...Object.values(type).flat()].join(',');
         }
         document.body.append(input);
         // The `change` event fires when the user interacts with the dialog.
@@ -143,6 +171,19 @@ export async function openSingleFileWith(acceptType) {
     const files = await openFilesWith(acceptType, false);
     return files?.at(0) ?? null;
 }
+/**
+ * One file, filtered by a spec the caller built rather than by a name in
+ * {@link FileTypes}.
+ *
+ * What {@link openSingleFileWith} is for the editor's own dialogs, this is for
+ * anything whose filter is DECLARED somewhere else — today the interchange
+ * registry, whose formats each carry their extensions and their mime and are
+ * added by a framework, not by editing the table above.
+ */
+export async function openSingleFileWithSpec(spec) {
+    const files = await openFilesWithSpec(spec, false);
+    return files?.at(0) ?? null;
+}
 export async function getImageFilesFromLocal() {
     const files = await openFilesWith('Images');
     return files ?? [];

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.