@formicoidea/labre-core 0.43.1 → 0.46.0

package/dist/_pkgs/std/gfx/model/surface/user-layers.d.ts

@@ -0,0 +1,68 @@
+import type { Store } from '../../../../store/index.js';
+import type { GfxModel } from '../model.js';
+import type { SurfaceBlockModel } from './surface-model.js';
+/**
+ * The layer every element belongs to while it names none (ADR 0031 §2, §3).
+ * A `@` cannot appear in a nanoid, so it never collides with a real layer id;
+ * it has no record while the surface has no `layers`, and is written as
+ * `undefined` on an element, never as this string.
+ */
+export declare const DEFAULT_LAYER_ID = "@default";
+/** One user layer, stored on the surface under its id (ADR 0031 §2). */
+export type SurfaceLayerRecord = {
+    /** Seeded through the translation seam at creation; content from then on. */
+    name: string;
+    /** Fractional key, bottom → top; the same alphabet as an element's `index`. */
+    index: string;
+    /** "Hide for everyone" on the whole layer. Absent = visible. */
+    hidden?: true;
+};
+/**
+ * What a model names as its own layer: an element's `layer` field, a gfx
+ * block's `layer` prop. `undefined` = the default layer.
+ */
+export declare function ownLayerOf(model: unknown): string | undefined;
+/**
+ * The model whose `layer` decides `model`'s (ADR 0031 §5): its outermost
+ * group-like ELEMENT ancestor (a group, a mindmap), else `model` itself. A
+ * group lives in one layer, stored once on its outermost group, so this is
+ * what {@link SurfaceUserLayers.effectiveLayerOf} reads and what a "move to
+ * layer" writes on. Frames are blocks and do not count. `groups` walks the
+ * model's surface, which throws on a detached model: that one carries itself.
+ */
+export declare function layerCarrierOf(model: GfxModel): GfxModel;
+/**
+ * The user layers of one surface, resolved for the comparator (ADR 0031 §4).
+ *
+ * Two caches, both thrown away by a revision bump rather than kept in step:
+ *
+ * - the rank of every layer id (its record's `index`), rebuilt when the
+ *   `layers` prop changes — `null` while the surface has no layer, which is
+ *   the fast path: `compare` then never asks for an effective layer at all;
+ * - each model's EFFECTIVE layer, rebuilt when anything that decides it
+ *   changes: a `layer` write, a regroup, an element added or removed.
+ *
+ * The effective layer is the `layer` of the model's outermost group-like
+ * ELEMENT ancestor (a group, a mindmap), else its own; a dangling id or none
+ * is {@link DEFAULT_LAYER_ID}. Frames are not counted: a frame is a slide,
+ * and a background layer under a content layer inside one frame is the point
+ * of layers. Nothing here writes: a dangling id is read as the default and
+ * left as it is.
+ */
+export declare class SurfaceUserLayers {
+    private readonly _surface;
+    private _ranks;
+    private _revision;
+    private readonly _effective;
+    constructor(_surface: SurfaceBlockModel);
+    /** Every layer id with its rank key, or `null` when there is no layer. */
+    get ranks(): ReadonlyMap<string, string> | null;
+    /** The `layers` record changed: ranks and effective layers are stale. */
+    invalidateRanks(): void;
+    /** Something that decides an effective layer changed. */
+    invalidateMembership(): void;
+    /** The layer `model` stacks and shows with. */
+    effectiveLayerOf(model: GfxModel): string;
+}
+export declare function registerSurfaceOfStore(store: Store, surface: SurfaceBlockModel): void;
+export declare function userLayersOf(model: unknown): SurfaceUserLayers | null;

package/dist/_pkgs/std/gfx/model/surface/user-layers.js

@@ -0,0 +1,127 @@
+import { GfxPrimitiveElementModel } from './element-model.js';
+/**
+ * The layer every element belongs to while it names none (ADR 0031 §2, §3).
+ * A `@` cannot appear in a nanoid, so it never collides with a real layer id;
+ * it has no record while the surface has no `layers`, and is written as
+ * `undefined` on an element, never as this string.
+ */
+export const DEFAULT_LAYER_ID = '@default';
+/**
+ * What a model names as its own layer: an element's `layer` field, a gfx
+ * block's `layer` prop. `undefined` = the default layer.
+ */
+export function ownLayerOf(model) {
+    if (model instanceof GfxPrimitiveElementModel)
+        return model.layer;
+    try {
+        const props = model.props;
+        return typeof props?.layer === 'string' ? props.layer : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The model whose `layer` decides `model`'s (ADR 0031 §5): its outermost
+ * group-like ELEMENT ancestor (a group, a mindmap), else `model` itself. A
+ * group lives in one layer, stored once on its outermost group, so this is
+ * what {@link SurfaceUserLayers.effectiveLayerOf} reads and what a "move to
+ * layer" writes on. Frames are blocks and do not count. `groups` walks the
+ * model's surface, which throws on a detached model: that one carries itself.
+ */
+export function layerCarrierOf(model) {
+    let groups = [];
+    try {
+        groups = model.groups ?? [];
+    }
+    catch {
+        groups = [];
+    }
+    for (let i = groups.length - 1; i >= 0; i--) {
+        if (groups[i] instanceof GfxPrimitiveElementModel) {
+            return groups[i];
+        }
+    }
+    return model;
+}
+/**
+ * The user layers of one surface, resolved for the comparator (ADR 0031 §4).
+ *
+ * Two caches, both thrown away by a revision bump rather than kept in step:
+ *
+ * - the rank of every layer id (its record's `index`), rebuilt when the
+ *   `layers` prop changes — `null` while the surface has no layer, which is
+ *   the fast path: `compare` then never asks for an effective layer at all;
+ * - each model's EFFECTIVE layer, rebuilt when anything that decides it
+ *   changes: a `layer` write, a regroup, an element added or removed.
+ *
+ * The effective layer is the `layer` of the model's outermost group-like
+ * ELEMENT ancestor (a group, a mindmap), else its own; a dangling id or none
+ * is {@link DEFAULT_LAYER_ID}. Frames are not counted: a frame is a slide,
+ * and a background layer under a content layer inside one frame is the point
+ * of layers. Nothing here writes: a dangling id is read as the default and
+ * left as it is.
+ */
+export class SurfaceUserLayers {
+    constructor(_surface) {
+        this._surface = _surface;
+        this._ranks = undefined;
+        this._revision = 0;
+        this._effective = new WeakMap();
+    }
+    /** Every layer id with its rank key, or `null` when there is no layer. */
+    get ranks() {
+        if (this._ranks === undefined) {
+            const layers = this._surface.props.layers;
+            if (!layers || Object.keys(layers).length === 0) {
+                this._ranks = null;
+            }
+            else {
+                const ranks = new Map();
+                for (const [id, record] of Object.entries(layers)) {
+                    if (record && typeof record.index === 'string') {
+                        ranks.set(id, record.index);
+                    }
+                }
+                this._ranks = ranks.size ? ranks : null;
+            }
+        }
+        return this._ranks;
+    }
+    /** The `layers` record changed: ranks and effective layers are stale. */
+    invalidateRanks() {
+        this._ranks = undefined;
+        this._revision++;
+    }
+    /** Something that decides an effective layer changed. */
+    invalidateMembership() {
+        this._revision++;
+    }
+    /** The layer `model` stacks and shows with. */
+    effectiveLayerOf(model) {
+        const cached = this._effective.get(model);
+        if (cached && cached.revision === this._revision)
+            return cached.layer;
+        const named = ownLayerOf(layerCarrierOf(model));
+        const ranks = this.ranks;
+        const layer = named !== undefined && ranks?.has(named) ? named : DEFAULT_LAYER_ID;
+        this._effective.set(model, { revision: this._revision, layer });
+        return layer;
+    }
+}
+/**
+ * Which surface a model's layers are read from. An element knows its
+ * surface; a gfx block knows its store, and the surface registers itself for
+ * its store when it initialises, so the comparator never queries the store.
+ */
+const SURFACE_OF_STORE = new WeakMap();
+export function registerSurfaceOfStore(store, surface) {
+    SURFACE_OF_STORE.set(store, surface);
+}
+export function userLayersOf(model) {
+    if (model instanceof GfxPrimitiveElementModel) {
+        return model.surface?.userLayers ?? null;
+    }
+    const store = model.store;
+    return store ? (SURFACE_OF_STORE.get(store)?.userLayers ?? null) : null;
+}

package/dist/_pkgs/std/scope/std-scope.d.ts

@@ -18,7 +18,7 @@ export interface BlockStdOptions {
     extensions: ExtensionType[];
 }
 export declare class BlockStdScope {
-    static internalExtensions: (typeof ViewStore | typeof UIEventDispatcher | typeof RangeManager | typeof CommandManager | typeof GridManager | typeof LayerManager | typeof ServiceManager | typeof ElementHighlightManager | typeof GfxSelectionManager | typeof SurfaceMiddlewareExtension | typeof ViewManager)[];
+    static internalExtensions: (typeof ViewStore | typeof UIEventDispatcher | typeof RangeManager | typeof CommandManager | typeof ElementHighlightManager | typeof GridManager | typeof GfxSelectionManager | typeof SurfaceMiddlewareExtension | typeof ViewManager | typeof LayerManager | typeof ServiceManager)[];
     readonly container: Container;
     readonly store: Store;
     readonly provider: ServiceProvider;

package/dist/_pkgs/std/utils/layer.d.ts

@@ -8,6 +8,16 @@ export declare function getLayerEndZIndex(layers: Layer[], layerIndex: number):
 export declare function updateLayersZIndex(layers: Layer[], startIdx: number): void;
 export declare function getElementIndex(indexable: GfxModel): string;
 export declare function ungroupIndex(index: string): string;
+/**
+ * Insert `element` after every element that sorts before it or ties with it.
+ *
+ * The array is kept sorted by `compare`, so that predicate holds on a prefix
+ * and the position is found by bisection. The linear scan it replaces asked
+ * `compare` (which walks both elements' group chains) of every element on
+ * every insert: a paste of N elements was N² comparisons. Where an index is
+ * shared by two unrelated subtrees `compare` is not transitive and both pick
+ * a tied position, not always the same one (layer-ordered-insert.unit.spec).
+ */
 export declare function insertToOrderedArray(array: GfxModel[], element: GfxModel): void;
 export declare function removeFromOrderedArray(array: GfxModel[], element: GfxModel): void;
 export declare enum SortOrder {

package/dist/_pkgs/std/utils/layer.js

@@ -1,6 +1,7 @@
 import { isGfxGroupCompatibleModel, } from '../gfx/model/base.js';
 import {} from '../gfx/model/gfx-block-model.js';
 import { GfxLocalElementModel } from '../gfx/model/surface/local-element-model.js';
+import { userLayersOf } from '../gfx/model/surface/user-layers.js';
 export function getLayerEndZIndex(layers, layerIndex) {
     const layer = layers[layerIndex];
     return layer ? layer.zIndex + layer.elements.length - 1 : 0;
@@ -28,13 +29,29 @@ export function getElementIndex(indexable) {
 export function ungroupIndex(index) {
     return index.split('-')[0];
 }
+/**
+ * Insert `element` after every element that sorts before it or ties with it.
+ *
+ * The array is kept sorted by `compare`, so that predicate holds on a prefix
+ * and the position is found by bisection. The linear scan it replaces asked
+ * `compare` (which walks both elements' group chains) of every element on
+ * every insert: a paste of N elements was N² comparisons. Where an index is
+ * shared by two unrelated subtrees `compare` is not transitive and both pick
+ * a tied position, not always the same one (layer-ordered-insert.unit.spec).
+ */
 export function insertToOrderedArray(array, element) {
-    let idx = 0;
-    while (idx < array.length &&
-        [SortOrder.BEFORE, SortOrder.SAME].includes(compare(array[idx], element))) {
-        ++idx;
+    let low = 0;
+    let high = array.length;
+    while (low < high) {
+        const mid = (low + high) >>> 1;
+        if (compare(array[mid], element) === SortOrder.AFTER) {
+            high = mid;
+        }
+        else {
+            low = mid + 1;
+        }
     }
-    array.splice(idx, 0, element);
+    array.splice(low, 0, element);
 }
 export function removeFromOrderedArray(array, element) {
     const idx = array.indexOf(element);
@@ -74,10 +91,40 @@ function compareLocal(a, b) {
     if (isALocal && isBLocal && a.creator && a.creator === b.creator) {
         return compareIndex(a.index, b.index);
     }
-    return {
-        a: isALocal && a.creator ? a.creator : a,
-        b: isBLocal && b.creator ? b.creator : b,
-    };
+    const left = isALocal && a.creator ? a.creator : a;
+    const right = isBLocal && b.creator ? b.creator : b;
+    // ADR 0031 §4: user layer rank first, then everything below unchanged.
+    const byLayer = compareUserLayer(left, right);
+    if (byLayer !== SortOrder.SAME)
+        return byLayer;
+    return { a: left, b: right };
+}
+/**
+ * The first step of {@link compare} (ADR 0031 §4): two models in different
+ * user layers stack by their layers' `index`; anything else is `SAME`, and
+ * today's comparator decides.
+ *
+ * The fast path is the first `return`: a surface with no `layers` answers
+ * `null` ranks after one cached read, so a document without user layers
+ * sorts with exactly the code that sorted it before layers existed. A local
+ * element without a creator has no layer and keeps today's order — above the
+ * content, as overlays always were.
+ */
+function compareUserLayer(a, b) {
+    if (a instanceof GfxLocalElementModel || b instanceof GfxLocalElementModel) {
+        return SortOrder.SAME;
+    }
+    const layers = userLayersOf(a);
+    const ranks = layers?.ranks;
+    if (!layers || !ranks)
+        return SortOrder.SAME;
+    const aLayer = layers.effectiveLayerOf(a);
+    const bLayer = layers.effectiveLayerOf(b);
+    if (aLayer === bLayer)
+        return SortOrder.SAME;
+    // A default layer with no record (the loser of a first-layer race, ADR
+    // 0031 open point 6) stacks at the bottom: `''` precedes every key.
+    return compareIndex(ranks.get(aLayer) ?? '', ranks.get(bLayer) ?? '');
 }
 /**
  * A comparator function for sorting elements in the surface.
@@ -91,15 +138,19 @@ export function compare(a, b) {
     }
     a = result.a;
     b = result.b;
-    if (isGfxGroupCompatibleModel(a) && b.groups.includes(a)) {
+    // Each `groups` read walks the group chain through `getGroup`, a scan of
+    // every container on the surface: read each side once.
+    const aGroups = a.groups;
+    const bGroups = b.groups;
+    if (isGfxGroupCompatibleModel(a) &&
+        bGroups.includes(a)) {
         return SortOrder.BEFORE;
     }
-    else if (isGfxGroupCompatibleModel(b) && a.groups.includes(b)) {
+    else if (isGfxGroupCompatibleModel(b) &&
+        aGroups.includes(b)) {
         return SortOrder.AFTER;
     }
     else {
-        const aGroups = a.groups;
-        const bGroups = b.groups;
         let i = 1;
         let aGroup = aGroups.at(-i);
         let bGroup = bGroups.at(-i);

package/dist/_pkgs/std/view/element/gfx-block-component.js

@@ -1,7 +1,7 @@
 var _a;
 import { BlockSuiteError, ErrorCode } from '../../../global/exceptions/index.js';
 import { Bound } from '../../../global/gfx/index.js';
-import { computed, effect, signal } from '@preact/signals-core';
+import { computed, effect, signal, untracked } from '@preact/signals-core';
 import { nothing } from 'lit';
 import { GfxControllerIdentifier } from '../../gfx/identifiers.js';
 import { SurfaceSelection } from '../../selection/index.js';
@@ -25,7 +25,10 @@ function updateZIndex(element) {
     }
 }
 function updateBlockVisibility(view) {
-    if (view.transformState$.value === 'active') {
+    // Read inside the effect below, so a local hide or show repaints the block
+    // without a transform change (ADR 0031 §8).
+    const hiddenLocally = view.gfx.localVisibility.isHidden(view.model);
+    if (view.transformState$.value === 'active' && !hiddenLocally) {
         view.style.visibility = 'visible';
         view.style.pointerEvents = 'auto';
         view.classList.remove('block-idle');
@@ -47,12 +50,17 @@ function handleGfxConnection(instance) {
         if (id === instance.model.id && type === 'update') {
             updateTransform(instance);
             updateZIndex(instance);
+            // A move to another user layer may hide or show it (ADR 0031 §7).
+            untracked(() => updateBlockVisibility(instance));
         }
     }));
     // A reorder changes no property of this block, only the layer it sits in,
     // so the stacking has to be read back from the layer manager.
     instance.disposables.add(instance.gfx.layer.slots.layerUpdated.subscribe(() => {
         updateZIndex(instance);
+        // So may a regroup, or a change of the layer list (a layer hidden for
+        // everyone is one record write, not a write on this block).
+        untracked(() => updateBlockVisibility(instance));
     }));
     instance.disposables.add(effect(() => {
         updateBlockVisibility(instance);

package/dist/commands.js

@@ -1,5 +1,6 @@
+import { frameCommands } from './_pkgs/affine-block-frame/index.js';
 import { copyLinkCommands, coreCommands, pivotCommands, readingCommands, tagCommands, } from './_pkgs/affine-block-root/index.js';
-import { auditCommands, exportSvgCommands, mapQualityCommands, } from './_pkgs/affine-block-surface/index.js';
+import { auditCommands, canvasGridCommands, exportSvgCommands, mapQualityCommands, selectionPaneCommands, userLayerCommands, } from './_pkgs/affine-block-surface/index.js';
 import { edgeDirectionCommands } from './_pkgs/affine-gfx-connector/index.js';
 import { shapeCommands } from './_pkgs/affine-gfx-shape/index.js';
 import { toCommandManifestEntry, } from './_pkgs/std/index.js';
@@ -54,6 +55,10 @@ export function getCommands(flags) {
         ...shapeCommands,
         ...mapQualityCommands,
         ...exportSvgCommands,
+        ...selectionPaneCommands,
+        ...frameCommands,
+        ...canvasGridCommands,
+        ...userLayerCommands,
         ...edgeDirectionCommands,
         ...(isCapabilityEnabled(flags, 'ai-audit') ? auditCommands : []),
     ], FRAMEWORK_COMMAND_GROUPS, flags);

package/dist/host-panels.d.ts

@@ -0,0 +1,90 @@
+import { type FramePreview } from './_pkgs/affine-fragment-frame-panel/index.js';
+import type { FrameBlockModel } from './_pkgs/affine-model/index.js';
+import type { BlockStdScope } from './_pkgs/std/index.js';
+/**
+ * `@labre/affine/host-panels` — the verbs a host's own panel calls (ADR 0034
+ * §4, docs/integrate/08-host-panels.md).
+ *
+ * A host that draws its own artefact catalogue, selection pane or slide list
+ * needs a handful of editor verbs: list a framework's artefacts, arm one, run
+ * a command, read the canvas stack, list the frames in presentation order,
+ * select a model, frame it in the viewport. They existed before this module,
+ * spread over four packages and three levels of abstraction (`armArtefact` in
+ * the edgeless toolbar widget, `selectionPaneTree` in the surface block, the
+ * command registry in `std`, the frame order in the frame block), and no page
+ * named them together. This module gathers them, so a host imports one entry
+ * and never a widget package.
+ *
+ * **Why a façade and not a seam.** A seam is the editor asking the host for
+ * something (show a panel, open a document); its absence needs a degraded
+ * behaviour and a row in the seams table. Here the direction is the other way:
+ * the host calls the editor, and nothing degrades — a host that draws no panel
+ * simply calls nothing. So: plain named functions over an `std`, no class, no
+ * object holding state, no registration. The library's own panels and a
+ * host's call the same functions and the same commands, which is what keeps
+ * their behaviour the same; every WRITE goes through a core command run by
+ * `runCommand` (`canvas.frame.reorder`, `canvas.element.reorder`, …), so the
+ * read-only refusal, the no-op check, the single undo step and the telemetry
+ * happen once whoever draws the pixels.
+ *
+ * **No Lit type is named here.** `lit` is only a dev dependency of
+ * `@labre/affine`, and a host that draws its panel in React must be able to
+ * type its calls without it (`host-panels-signature.unit.spec.ts` reads this
+ * file). `getCommandIcon` still returns what the icon tables hold; a host
+ * renders it with Lit's `render` or uses its own icons.
+ *
+ * **This module only widens.** A function, a parameter or a return type a
+ * host calls keeps its 0.46 shape in every minor: a new parameter is optional,
+ * a return never gains `null` (`host-panels-signature.unit.spec.ts`, which
+ * `yarn build` typechecks; docs/lessons.md 33). A verb a host panel needs and
+ * cannot find here is a gap in this module, not a reason to import a widget
+ * package.
+ *
+ * ponytail: `frameList` is a plain read, not a signal of the frame list; a
+ * host follows reorders through `std.store.slots.blockUpdated` (08 says how).
+ * A signal of the frame list is the upgrade path if two hosts ask.
+ */
+export { type AnyCommandDescriptor, type CommandInvocation, type CommandOwner, type CommandSurface, getCommandIcon, getCommandsForSurface, getRegisteredCommands, runCommand, } from './_pkgs/std/index.js';
+export { armArtefact } from './_pkgs/affine-widget-edgeless-toolbar/index.js';
+export { type SelectionPaneNode, selectionPaneTree, } from './_pkgs/affine-block-surface/index.js';
+export { frameCommands, type ReorderFramesParams, reorderFramesParams, } from './_pkgs/affine-block-frame/index.js';
+/**
+ * The document's frames in presentation order, first slide first — the order
+ * `canvas.frame.reorder` writes and the presentation walks. Works in page mode
+ * too: the frame manager is registered with the frame block in both.
+ */
+export declare function frameList(std: BlockStdScope): FrameBlockModel[];
+/**
+ * Select `ids` on the canvas, the way a click on a panel row does: the
+ * selection replaces the current one and nothing enters text editing. Edgeless
+ * only — page mode shows no canvas selection.
+ */
+export declare function selectModels(std: BlockStdScope, ids: readonly string[]): void;
+/**
+ * Move the viewport, smoothly, so model `id` fills it within `padding`
+ * (top, right, bottom, left, in screen pixels) — the frame panel's "fit to
+ * frame". `false` when no canvas model has that id; nothing moves then.
+ *
+ * It never switches the editor's mode: the host knows which mode it shows, and
+ * a host in page mode switches first (`DocModeProvider`).
+ */
+export declare function fitToModel(std: BlockStdScope, id: string, padding?: [number, number, number, number]): boolean;
+/**
+ * The live preview of a frame the library's own frame panel draws on each
+ * card: a read-only mini editor clipped to the frame's bounds, repainted as
+ * the frame's content changes. Not a picture — a host that wants a static
+ * thumbnail renders one through `ExportManager` instead.
+ *
+ * Returns the element ready to be appended; `width` and `height` are the
+ * preview box in CSS pixels (the panel's card is 280 × 166), `fillScreen`
+ * covers the box instead of containing the frame. One mini editor per
+ * preview: mount only the cards on screen. The element is defined by the
+ * frame panel's view extension, so it renders nothing in an assembly where the
+ * `frame` flag is off (ADR 0009) — the same assembly where there is no frame
+ * to preview.
+ */
+export declare function createFramePreview(std: BlockStdScope, frame: FrameBlockModel, options?: {
+    width?: number;
+    height?: number;
+    fillScreen?: boolean;
+}): FramePreview;

package/dist/host-panels.js

@@ -0,0 +1,111 @@
+import { EdgelessFrameManagerIdentifier } from './_pkgs/affine-block-frame/index.js';
+import { AFFINE_FRAME_PREVIEW, } from './_pkgs/affine-fragment-frame-panel/index.js';
+import { GfxControllerIdentifier } from './_pkgs/std/gfx/index.js';
+/**
+ * `@labre/affine/host-panels` — the verbs a host's own panel calls (ADR 0034
+ * §4, docs/integrate/08-host-panels.md).
+ *
+ * A host that draws its own artefact catalogue, selection pane or slide list
+ * needs a handful of editor verbs: list a framework's artefacts, arm one, run
+ * a command, read the canvas stack, list the frames in presentation order,
+ * select a model, frame it in the viewport. They existed before this module,
+ * spread over four packages and three levels of abstraction (`armArtefact` in
+ * the edgeless toolbar widget, `selectionPaneTree` in the surface block, the
+ * command registry in `std`, the frame order in the frame block), and no page
+ * named them together. This module gathers them, so a host imports one entry
+ * and never a widget package.
+ *
+ * **Why a façade and not a seam.** A seam is the editor asking the host for
+ * something (show a panel, open a document); its absence needs a degraded
+ * behaviour and a row in the seams table. Here the direction is the other way:
+ * the host calls the editor, and nothing degrades — a host that draws no panel
+ * simply calls nothing. So: plain named functions over an `std`, no class, no
+ * object holding state, no registration. The library's own panels and a
+ * host's call the same functions and the same commands, which is what keeps
+ * their behaviour the same; every WRITE goes through a core command run by
+ * `runCommand` (`canvas.frame.reorder`, `canvas.element.reorder`, …), so the
+ * read-only refusal, the no-op check, the single undo step and the telemetry
+ * happen once whoever draws the pixels.
+ *
+ * **No Lit type is named here.** `lit` is only a dev dependency of
+ * `@labre/affine`, and a host that draws its panel in React must be able to
+ * type its calls without it (`host-panels-signature.unit.spec.ts` reads this
+ * file). `getCommandIcon` still returns what the icon tables hold; a host
+ * renders it with Lit's `render` or uses its own icons.
+ *
+ * **This module only widens.** A function, a parameter or a return type a
+ * host calls keeps its 0.46 shape in every minor: a new parameter is optional,
+ * a return never gains `null` (`host-panels-signature.unit.spec.ts`, which
+ * `yarn build` typechecks; docs/lessons.md 33). A verb a host panel needs and
+ * cannot find here is a gap in this module, not a reason to import a widget
+ * package.
+ *
+ * ponytail: `frameList` is a plain read, not a signal of the frame list; a
+ * host follows reorders through `std.store.slots.blockUpdated` (08 says how).
+ * A signal of the frame list is the upgrade path if two hosts ask.
+ */
+export { getCommandIcon, getCommandsForSurface, getRegisteredCommands, runCommand, } from './_pkgs/std/index.js';
+export { armArtefact } from './_pkgs/affine-widget-edgeless-toolbar/index.js';
+export { selectionPaneTree, } from './_pkgs/affine-block-surface/index.js';
+export { frameCommands, reorderFramesParams, } from './_pkgs/affine-block-frame/index.js';
+/**
+ * The document's frames in presentation order, first slide first — the order
+ * `canvas.frame.reorder` writes and the presentation walks. Works in page mode
+ * too: the frame manager is registered with the frame block in both.
+ */
+export function frameList(std) {
+    return std.get(EdgelessFrameManagerIdentifier).frames;
+}
+/**
+ * Select `ids` on the canvas, the way a click on a panel row does: the
+ * selection replaces the current one and nothing enters text editing. Edgeless
+ * only — page mode shows no canvas selection.
+ */
+export function selectModels(std, ids) {
+    std.get(GfxControllerIdentifier).selection.set({
+        elements: [...ids],
+        editing: false,
+    });
+}
+/**
+ * Move the viewport, smoothly, so model `id` fills it within `padding`
+ * (top, right, bottom, left, in screen pixels) — the frame panel's "fit to
+ * frame". `false` when no canvas model has that id; nothing moves then.
+ *
+ * It never switches the editor's mode: the host knows which mode it shows, and
+ * a host in page mode switches first (`DocModeProvider`).
+ */
+export function fitToModel(std, id, padding = [0, 0, 0, 0]) {
+    const gfx = std.get(GfxControllerIdentifier);
+    const model = gfx.getElementById(id);
+    if (!model?.elementBound)
+        return false;
+    gfx.viewport.setViewportByBound(model.elementBound, padding, true);
+    return true;
+}
+/**
+ * The live preview of a frame the library's own frame panel draws on each
+ * card: a read-only mini editor clipped to the frame's bounds, repainted as
+ * the frame's content changes. Not a picture — a host that wants a static
+ * thumbnail renders one through `ExportManager` instead.
+ *
+ * Returns the element ready to be appended; `width` and `height` are the
+ * preview box in CSS pixels (the panel's card is 280 × 166), `fillScreen`
+ * covers the box instead of containing the frame. One mini editor per
+ * preview: mount only the cards on screen. The element is defined by the
+ * frame panel's view extension, so it renders nothing in an assembly where the
+ * `frame` flag is off (ADR 0009) — the same assembly where there is no frame
+ * to preview.
+ */
+export function createFramePreview(std, frame, options = {}) {
+    const preview = document.createElement(AFFINE_FRAME_PREVIEW);
+    preview.std = std;
+    preview.frame = frame;
+    if (options.width !== undefined)
+        preview.surfaceWidth = options.width;
+    if (options.height !== undefined)
+        preview.surfaceHeight = options.height;
+    if (options.fillScreen !== undefined)
+        preview.fillScreen = options.fillScreen;
+    return preview;
+}

package/dist/translations.js

@@ -4,7 +4,7 @@ import { EMBED_WORDINGS } from './_pkgs/affine-block-embed/translations.js';
 import { EMBED_DOC_WORDINGS } from './_pkgs/affine-block-embed-doc/translations.js';
 import { FRAME_CHROME_WORDINGS, FRAME_WORDINGS, } from './_pkgs/affine-block-frame/translations.js';
 import { IMAGE_WORDINGS } from './_pkgs/affine-block-image/translations.js';
-import { EXEMPTION_FALLBACK, PROVENANCE_FALLBACK, SEVERITY_FALLBACK, SVG_SKETCH_WORDINGS, } from './_pkgs/affine-block-surface/index.js';
+import { EXEMPTION_FALLBACK, EXPORT_SVG_WORDINGS, PROVENANCE_FALLBACK, READING_FRAME_WORDINGS, SEVERITY_FALLBACK, SVG_SKETCH_WORDINGS, USER_LAYER_SEED_WORDINGS, } from './_pkgs/affine-block-surface/index.js';
 import { SURFACE_REF_CHROME_WORDINGS, SURFACE_REF_WORDINGS, } from './_pkgs/affine-block-surface-ref/translations.js';
 import { ADAPTER_PANEL_WORDINGS } from './_pkgs/affine-fragment-adapter-panel/translations.js';
 import { DOC_TITLE_WORDINGS } from './_pkgs/affine-fragment-doc-title/translations.js';
@@ -158,7 +158,11 @@ const CHROME_KEYS = [
     ['com.labre.reading.field.nature', 'Nature'],
     ['com.labre.reading.field.relations', 'Parent-child relations'],
     ['com.labre.reading.field.value-flow', 'Value flow'],
-    ['com.labre.reading.field.phase', 'Evolution phase'],
+    // `com.labre.reading.field.phase` and `com.labre.reading.phase.none` are the
+    // reading engine's DEFAULT frame wording, declared beside it in the surface
+    // package (`READING_FRAME_WORDINGS`) and walked from `PACKAGE_WORDINGS`: a
+    // profile that names no frame wording — Wardley's, a 0.43 host's — reads
+    // with them, whether or not a framework bundle is installed.
     ['com.labre.reading.field.naming', 'Naming convention'],
     ['com.labre.reading.field.record', 'Record'],
     ['com.labre.reading.field.drift', 'Drift'],
@@ -182,10 +186,7 @@ const CHROME_KEYS = [
     ['com.labre.reading.value-flow', 'Value flows up from'],
     ['com.labre.reading.value-flow.to', 'to'],
     ['com.labre.reading.phase.band', 'In the zone of punctuated equilibrium'],
-    [
-        'com.labre.reading.phase.none',
-        'Not on a framework background — no phase to read.',
-    ],
+    ['com.labre.reading.zone.unnamed', 'Unnamed'],
     [
         'com.labre.reading.naming.conforms',
         'The name follows the convention of its nature.',
@@ -303,6 +304,8 @@ const PACKAGE_WORDINGS = [
     POINTER_WORDINGS,
     ROOT_CHROME_WORDINGS,
     SVG_SKETCH_WORDINGS,
+    EXPORT_SVG_WORDINGS,
+    READING_FRAME_WORDINGS,
     STD_WORDINGS,
     ATTACHMENT_WORDINGS,
     BOOKMARK_WORDINGS,
@@ -331,6 +334,7 @@ const PACKAGE_SEED_WORDINGS = [
     SURFACE_REF_WORDINGS,
     TEMPLATE_SEED_WORDINGS,
     ROOT_SEED_WORDINGS,
+    USER_LAYER_SEED_WORDINGS,
 ];
 /**
  * Every i18n key THIS package can ask the host for, with its English fallback