@formicoidea/labre-core 0.51.0 → 0.53.0

package/dist/_pkgs/affine-block-surface/index.d.ts

@@ -4,6 +4,7 @@ export { SurfaceElementModel, SurfaceGroupLikeModel, } from './element-model/bas
 export { CanvasElementType } from './element-model/index.js';
 export { CanvasRenderer } from './renderer/canvas-renderer.js';
 export { DomRenderer } from './renderer/dom-renderer.js';
+export { isPainted } from './renderer/paint-predicate.js';
 export { ElementHighlightOverlay } from './renderer/element-highlight-overlay.js';
 export type { ElementRenderer } from './renderer/elements/index.js';
 export * from './renderer/elements/type.js';

package/dist/_pkgs/affine-block-surface/index.js

@@ -6,6 +6,7 @@ export { SurfaceElementModel, SurfaceGroupLikeModel, } from './element-model/bas
 export { CanvasElementType } from './element-model/index.js';
 export { CanvasRenderer } from './renderer/canvas-renderer.js';
 export { DomRenderer } from './renderer/dom-renderer.js';
+export { isPainted } from './renderer/paint-predicate.js';
 export { ElementHighlightOverlay } from './renderer/element-highlight-overlay.js';
 export * from './renderer/elements/type.js';
 export { Overlay, OverlayIdentifier } from './renderer/overlay.js';

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

@@ -38,6 +38,7 @@ export * from './quick-search-service.js';
 export * from './selection-pane-service.js';
 export * from './telemetry-service/index.js';
 export * from './theme-service.js';
+export * from './thread-marks-service.js';
 export * from './title-band-service.js';
 export * from './toolbar-service/index.js';
 export * from './translation-service/index.js';

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

@@ -38,6 +38,7 @@ export * from './quick-search-service.js';
 export * from './selection-pane-service.js';
 export * from './telemetry-service/index.js';
 export * from './theme-service.js';
+export * from './thread-marks-service.js';
 export * from './title-band-service.js';
 export * from './toolbar-service/index.js';
 export * from './translation-service/index.js';

package/dist/_pkgs/affine-shared/services/thread-marks-service.d.ts

@@ -0,0 +1,100 @@
+import type { ExtensionType } from '../../store/index.js';
+import type { ReadonlySignal } from '@preact/signals-core';
+/**
+ * What a mark sits on (ADR 0038): a block, in either view, or a canvas element
+ * no block backs (a shape, a connector, a group, a framework board). The id is
+ * the one the library already gives it: a block id, an element id.
+ */
+export type ThreadMarkTargetType = 'block' | 'element';
+/**
+ * A run of text inside one block (ADR 0038, amendment of 2026-10-15): two
+ * Yjs relative positions on the block's `Y.Text`, each encoded with
+ * `Y.encodeRelativePosition` then base64. Opaque to the host, which stores
+ * and returns the two strings as they are; only the library reads them.
+ *
+ * A relative position follows the text through local and remote edits and is
+ * computed by reading, never by writing: nothing lands in the document. When
+ * the text it points at is gone, the range no longer resolves and the library
+ * falls back to the block.
+ */
+export interface ThreadTextRange {
+    start: string;
+    end: string;
+}
+/**
+ * One marked target of the mounted document, as the host computes it. Ids and
+ * counters only: the library never learns what the host attaches to a target,
+ * who wrote it or what it says.
+ *
+ * `count` is how many the host has on that target (a mark at `0` or below is
+ * not drawn); `unread` turns the mark to the accent colour.
+ */
+export interface ThreadMark {
+    targetType: ThreadMarkTargetType;
+    targetId: string;
+    count: number;
+    unread: boolean;
+    /**
+     * The text the discussion is anchored to, for a `block` target (ignored on
+     * an `element`). Optional (ADR 0038 amendment): without it only the
+     * block's mark is drawn; with it the run is also highlighted in the page
+     * view, and a click on it opens the discussion. A range that no longer
+     * resolves is not drawn, and the block's mark stays.
+     */
+    range?: ThreadTextRange;
+}
+/**
+ * What the library hands the host when someone clicks a mark or "Discuss"
+ * (`com.labre.thread.discuss`) in a block or element toolbar.
+ *
+ * `excerpt` is computed here because the library knows the content: the
+ * block's text (its descendants' for a container such as a note), a canvas
+ * element's label as the selection pane reads it, else the kind of target;
+ * for a text range, the text it covers.
+ * Whitespace is collapsed and it is cut to at most 280 characters, an
+ * ellipsis included (`THREAD_EXCERPT_MAX`). It is a snapshot for the host to
+ * store beside its anchor; the library keeps no copy.
+ */
+export interface ThreadOpenRequest {
+    docId: string;
+    targetType: ThreadMarkTargetType;
+    targetId: string;
+    excerpt: string;
+    /**
+     * Set when the discussion starts on a text selection, or on a highlighted
+     * range (ADR 0038 amendment): the block is still `targetId` and
+     * `excerpt` is the selected text itself. Absent for a whole block or an
+     * element.
+     */
+    range?: ThreadTextRange;
+}
+/** The longest excerpt `openThread` is ever handed, in code points. */
+export declare const THREAD_EXCERPT_MAX = 280;
+/**
+ * The "has a thread" seam (ADR 0038): the host owns the discussions, the
+ * library marks what the host says is marked and asks the host to open one.
+ *
+ * Nothing is written to the document, ever: no prop, no id in the content, no
+ * write on load. That is why it is not `CommentProvider`, which writes
+ * `block.props.comments` and ignores canvas elements.
+ *
+ * Absent or `null`: no mark is drawn and no toolbar offers "Discuss".
+ */
+export interface ThreadMarksService {
+    /**
+     * The marks of the mounted document. Read reactively: a new array
+     * repaints the marks. An id the editor cannot find (a deleted block, an
+     * element of the other view) is ignored, never an error.
+     */
+    marks$: ReadonlySignal<readonly ThreadMark[]>;
+    /** Open (or start) the discussion on a target. Writes nothing here. */
+    openThread(request: ThreadOpenRequest): void;
+}
+export declare const ThreadMarksProvider: import("../../global/di/types.js").ServiceIdentifier<ThreadMarksService> & (<U extends ThreadMarksService = ThreadMarksService>(variant: import("../../global/di/types.js").ServiceVariant) => import("../../global/di/types.js").ServiceIdentifier<U>);
+/**
+ * Host seam: the host's thread marks, or `null` to say there are none.
+ *
+ * `di.override`, like every panel seam, so a later registration wins and
+ * registering twice never throws at boot.
+ */
+export declare function ThreadMarksExtension(service: ThreadMarksService | null): ExtensionType;

package/dist/_pkgs/affine-shared/services/thread-marks-service.js

@@ -0,0 +1,20 @@
+import { createIdentifier } from '../../global/di/index.js';
+/** The longest excerpt `openThread` is ever handed, in code points. */
+export const THREAD_EXCERPT_MAX = 280;
+export const ThreadMarksProvider = createIdentifier('LabreThreadMarks');
+/**
+ * Host seam: the host's thread marks, or `null` to say there are none.
+ *
+ * `di.override`, like every panel seam, so a later registration wins and
+ * registering twice never throws at boot.
+ */
+export function ThreadMarksExtension(service) {
+    return {
+        setup: di => {
+            // `null` rides through the factory on purpose: `getOptional` then
+            // reports the seam as absent, which is the whole "no mark, no button"
+            // story.
+            di.override(ThreadMarksProvider, () => service);
+        },
+    };
+}

package/dist/_pkgs/affine-widget-thread-marks/effects.d.ts

@@ -0,0 +1 @@
+export declare function effects(): void;

package/dist/_pkgs/affine-widget-thread-marks/effects.js

@@ -0,0 +1,4 @@
+import { AFFINE_THREAD_MARKS_WIDGET, ThreadMarksWidget } from './widget.js';
+export function effects() {
+    customElements.define(AFFINE_THREAD_MARKS_WIDGET, ThreadMarksWidget);
+}

package/dist/_pkgs/affine-widget-thread-marks/excerpt.d.ts

@@ -0,0 +1,23 @@
+import { type ThreadMarkTargetType, type ThreadTextRange } from '../affine-shared/services/index.js';
+import type { BlockStdScope } from '../std/index.js';
+/**
+ * A block or a canvas element, by the id the library gave it, and for a
+ * block optionally a run of its text (ADR 0038, amendment of 2026-10-15).
+ */
+export interface ThreadTarget {
+    targetType: ThreadMarkTargetType;
+    targetId: string;
+    range?: ThreadTextRange;
+}
+/**
+ * Collapse whitespace and cut to {@link THREAD_EXCERPT_MAX} code points, the
+ * ellipsis included. Code points, not UTF-16 units, so an emoji is never cut
+ * in half and a host counting characters (Postgres `char_length`) agrees.
+ */
+export declare function truncateThreadExcerpt(raw: string): string;
+/**
+ * The excerpt handed to `openThread` (ADR 0038): what the target says, as a
+ * reader would recognise it, at most {@link THREAD_EXCERPT_MAX} characters.
+ * Read only: nothing is written, nothing is cached.
+ */
+export declare function threadExcerpt(std: BlockStdScope, target: ThreadTarget): string;

package/dist/_pkgs/affine-widget-thread-marks/excerpt.js

@@ -0,0 +1,76 @@
+import { getSurfaceBlock } from '../affine-block-surface/index.js';
+import { THREAD_EXCERPT_MAX, } from '../affine-shared/services/index.js';
+import { selectionPaneRowLabel, selectionPaneTypeLabel, } from '../affine-widget-edgeless-toolbar/index.js';
+import { GfxBlockElementModel } from '../std/gfx/index.js';
+import { resolveThreadRange } from './text-range.js';
+const ELLIPSIS = '…';
+/**
+ * Collapse whitespace and cut to {@link THREAD_EXCERPT_MAX} code points, the
+ * ellipsis included. Code points, not UTF-16 units, so an emoji is never cut
+ * in half and a host counting characters (Postgres `char_length`) agrees.
+ */
+export function truncateThreadExcerpt(raw) {
+    const text = raw.replace(/\s+/g, ' ').trim();
+    const chars = Array.from(text);
+    if (chars.length <= THREAD_EXCERPT_MAX)
+        return text;
+    return (chars
+        .slice(0, THREAD_EXCERPT_MAX - 1)
+        .join('')
+        .trimEnd() + ELLIPSIS);
+}
+/**
+ * A block's own text, then its descendants' in document order (a note, a
+ * callout, a list item with children), until there is more than an excerpt
+ * can hold.
+ */
+function blockText(model) {
+    const parts = [];
+    let length = 0;
+    const visit = (block) => {
+        if (length > THREAD_EXCERPT_MAX)
+            return;
+        const own = block.text?.toString() ?? '';
+        if (own.trim()) {
+            parts.push(own);
+            length += own.length + 1;
+        }
+        for (const child of block.children)
+            visit(child);
+    };
+    visit(model);
+    return parts.join(' ');
+}
+function rawExcerpt(std, target) {
+    if (target.targetType === 'block') {
+        const model = std.store.getModelById(target.targetId);
+        if (!model)
+            return '';
+        // A run of text reads as itself: the quote a reader selected. A range
+        // that no longer resolves falls back to the block, like its mark.
+        const yText = model.text?.yText;
+        const run = target.range && yText ? resolveThreadRange(yText, target.range) : null;
+        if (yText && run) {
+            return yText.toString().slice(run.index, run.index + run.length);
+        }
+        const text = blockText(model);
+        if (text.trim())
+            return text;
+        // A canvas block with no text reads as the selection pane names it: a
+        // frame by its title, an image or a note by its kind.
+        if (model instanceof GfxBlockElementModel) {
+            return selectionPaneRowLabel(std, model);
+        }
+        return selectionPaneTypeLabel(std, model.flavour);
+    }
+    const element = getSurfaceBlock(std.store)?.getElementById(target.targetId);
+    return element ? selectionPaneRowLabel(std, element) : '';
+}
+/**
+ * The excerpt handed to `openThread` (ADR 0038): what the target says, as a
+ * reader would recognise it, at most {@link THREAD_EXCERPT_MAX} characters.
+ * Read only: nothing is written, nothing is cached.
+ */
+export function threadExcerpt(std, target) {
+    return truncateThreadExcerpt(rawExcerpt(std, target));
+}

package/dist/_pkgs/affine-widget-thread-marks/index.d.ts

@@ -0,0 +1,6 @@
+export * from './excerpt.js';
+export * from './text-range.js';
+export * from './toolbar.js';
+export * from './translations.js';
+export * from './widget.js';
+export declare const threadMarksWidget: import("../store/index.js").ExtensionType;

package/dist/_pkgs/affine-widget-thread-marks/index.js

@@ -0,0 +1,9 @@
+import { WidgetViewExtension } from '../std/index.js';
+import { literal, unsafeStatic } from 'lit/static-html.js';
+import { AFFINE_THREAD_MARKS_WIDGET } from './widget.js';
+export * from './excerpt.js';
+export * from './text-range.js';
+export * from './toolbar.js';
+export * from './translations.js';
+export * from './widget.js';
+export const threadMarksWidget = WidgetViewExtension('affine:page', AFFINE_THREAD_MARKS_WIDGET, literal `${unsafeStatic(AFFINE_THREAD_MARKS_WIDGET)}`);

package/dist/_pkgs/affine-widget-thread-marks/text-range.d.ts

@@ -0,0 +1,26 @@
+import type { ThreadTextRange } from '../affine-shared/services/index.js';
+import * as Y from 'yjs';
+/** Where a range sits in its block's text today, by index. */
+export interface ResolvedThreadRange {
+    index: number;
+    length: number;
+}
+/**
+ * The anchor of `length` characters from `index` in `yText` (ADR 0038,
+ * amendment of 2026-10-15), or `null` for an empty run or one outside the
+ * text.
+ *
+ * `start` sticks to the first selected character (`assoc = 0`) and `end` to
+ * the last one (`assoc = -1`), so typing right after the run does not grow
+ * it. Creating a relative position only reads the item ids: nothing is
+ * written to the document (held by `text-range.unit.spec.ts`).
+ */
+export declare function encodeThreadRange(yText: Y.Text, index: number, length: number): ThreadTextRange | null;
+/**
+ * Where `range` sits in `yText` now, or `null` when it cannot say: the text
+ * is detached, a string is not a position, a position belongs to another
+ * text, or the run collapsed because its text was deleted. Never throws: a
+ * host's stored anchor may be anything, and an unresolvable range simply is
+ * not drawn.
+ */
+export declare function resolveThreadRange(yText: Y.Text, range: ThreadTextRange): ResolvedThreadRange | null;

package/dist/_pkgs/affine-widget-thread-marks/text-range.js

@@ -0,0 +1,59 @@
+import * as Y from 'yjs';
+function toBase64(bytes) {
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+}
+function fromBase64(text) {
+    return Uint8Array.from(atob(text), char => char.charCodeAt(0));
+}
+/**
+ * The anchor of `length` characters from `index` in `yText` (ADR 0038,
+ * amendment of 2026-10-15), or `null` for an empty run or one outside the
+ * text.
+ *
+ * `start` sticks to the first selected character (`assoc = 0`) and `end` to
+ * the last one (`assoc = -1`), so typing right after the run does not grow
+ * it. Creating a relative position only reads the item ids: nothing is
+ * written to the document (held by `text-range.unit.spec.ts`).
+ */
+export function encodeThreadRange(yText, index, length) {
+    if (!(length > 0) || index < 0 || index + length > yText.length) {
+        return null;
+    }
+    const start = Y.createRelativePositionFromTypeIndex(yText, index, 0);
+    const end = Y.createRelativePositionFromTypeIndex(yText, index + length, -1);
+    return {
+        start: toBase64(Y.encodeRelativePosition(start)),
+        end: toBase64(Y.encodeRelativePosition(end)),
+    };
+}
+function absoluteIndex(encoded, yText, doc) {
+    const position = Y.createAbsolutePositionFromRelativePosition(Y.decodeRelativePosition(fromBase64(encoded)), doc);
+    // A position of another text (a host that mixed up two anchors) is not
+    // this block's run.
+    return position && position.type === yText ? position.index : null;
+}
+/**
+ * Where `range` sits in `yText` now, or `null` when it cannot say: the text
+ * is detached, a string is not a position, a position belongs to another
+ * text, or the run collapsed because its text was deleted. Never throws: a
+ * host's stored anchor may be anything, and an unresolvable range simply is
+ * not drawn.
+ */
+export function resolveThreadRange(yText, range) {
+    const doc = yText.doc;
+    if (!doc)
+        return null;
+    try {
+        const start = absoluteIndex(range.start, yText, doc);
+        const end = absoluteIndex(range.end, yText, doc);
+        if (start === null || end === null || end <= start)
+            return null;
+        return { index: start, length: end - start };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/_pkgs/affine-widget-thread-marks/toolbar.d.ts

@@ -0,0 +1,50 @@
+import { type ToolbarContext } from '../affine-shared/services/index.js';
+import { type BlockStdScope } from '../std/index.js';
+import type { ExtensionType } from '../store/index.js';
+import { type ThreadTarget } from './excerpt.js';
+/**
+ * The ONE target a toolbar row speaks for, or `null` when it speaks for
+ * several (a discussion anchors to one block or one element, labre ADR-0048).
+ *
+ * - On the canvas, exactly one selected model: a canvas element (shape,
+ *   connector, group, framework board) is an `element`, a canvas block (note,
+ *   frame, image, embed) a `block`.
+ * - A text selection: the block it starts in, with the selected run of that
+ *   block's text (ADR 0038, amendment of 2026-10-15).
+ * - One selected block, or the block a hover toolbar is drawn for.
+ */
+export declare function threadTargetOf(ctx: ToolbarContext): ThreadTarget | null;
+/**
+ * Ask the host to open the discussion of `target`, with the excerpt the
+ * library computes. Nothing is written: no prop, no id in the document.
+ * Without the seam, nothing happens. `range` is handed over only when there
+ * is one, so a host comparing requests sees the first shape for a whole block.
+ */
+export declare function openThreadOn(std: BlockStdScope, target: ThreadTarget): void;
+export declare const THREAD_DISCUSS_ACTION_ID = "g.thread-discuss";
+/**
+ * "Discuss" in the toolbar of every block and every canvas element (ADR 0038).
+ * Shown only when the host registered the seam and the row speaks for one
+ * target. It is not AFFiNE's `blockCommentToolbarButton`: that one writes the
+ * comment id into the block.
+ */
+export declare const threadDiscussToolbarConfig: {
+    readonly when: (ctx: ToolbarContext) => boolean;
+    readonly actions: [{
+        readonly id: "g.thread-discuss";
+        readonly icon: import("lit-html").TemplateResult<1>;
+        readonly labelWording: import("../affine-shared/services/index.js").ChromeWording;
+        readonly tooltipWording: import("../affine-shared/services/index.js").ChromeWording;
+        readonly run: (ctx: ToolbarContext) => void;
+    }];
+};
+/**
+ * Registered on the two wildcard rows, each under an owner key: the bare
+ * `affine:surface:*` is the root's built-in canvas module, and an owner key
+ * never collides with a bare one. `affine:*` is merged into every row the
+ * toolbar draws; `affine:surface:*` names the canvas rows explicitly, so a
+ * row that stopped merging `affine:*` would still offer it. Where both apply,
+ * the toolbar merges entries by id, so the row shows "Discuss" once. A new
+ * block or framework inherits it by doing nothing.
+ */
+export declare const threadDiscussToolbarExtensions: ExtensionType[];

package/dist/_pkgs/affine-widget-thread-marks/toolbar.js

@@ -0,0 +1,124 @@
+import { CommentIcon } from '@blocksuite/icons/lit';
+import { ToolbarModuleExtension, toolbarModuleKey, ThreadMarksProvider, } from '../affine-shared/services/index.js';
+import { BlockFlavourIdentifier, BlockSelection, TextSelection, } from '../std/index.js';
+import { GfxPrimitiveElementModel } from '../std/gfx/index.js';
+import { threadExcerpt } from './excerpt.js';
+import { encodeThreadRange } from './text-range.js';
+import { THREAD_DISCUSS } from './translations.js';
+/** Containers a discussion never anchors to: the page and the canvas itself. */
+const NOT_A_TARGET = new Set(['affine:page', 'affine:surface']);
+function blockTarget(id, ctx) {
+    if (!id)
+        return null;
+    const model = ctx.store.getModelById(id);
+    if (!model || NOT_A_TARGET.has(model.flavour))
+        return null;
+    return { targetType: 'block', targetId: model.id };
+}
+/**
+ * The block a text selection starts in, with the selected run of it. A
+ * selection over several blocks anchors to the first one, on the part of it
+ * that is selected (ADR 0038, amendment of 2026-10-15). A run that cannot be
+ * encoded (an empty one, a block with no text) leaves the block alone.
+ */
+function textTarget(text, ctx) {
+    const target = blockTarget(text.from.blockId, ctx);
+    if (!target)
+        return null;
+    const yText = ctx.store.getModelById(target.targetId)?.text?.yText;
+    const range = yText
+        ? encodeThreadRange(yText, text.from.index, text.from.length)
+        : null;
+    return range ? { ...target, range } : target;
+}
+/**
+ * The ONE target a toolbar row speaks for, or `null` when it speaks for
+ * several (a discussion anchors to one block or one element, labre ADR-0048).
+ *
+ * - On the canvas, exactly one selected model: a canvas element (shape,
+ *   connector, group, framework board) is an `element`, a canvas block (note,
+ *   frame, image, embed) a `block`.
+ * - A text selection: the block it starts in, with the selected run of that
+ *   block's text (ADR 0038, amendment of 2026-10-15).
+ * - One selected block, or the block a hover toolbar is drawn for.
+ */
+export function threadTargetOf(ctx) {
+    if (ctx.hasSelectedSurfaceModels) {
+        const models = ctx.getSurfaceModels();
+        if (models.length !== 1)
+            return null;
+        const model = models[0];
+        if (!model)
+            return null;
+        return model instanceof GfxPrimitiveElementModel
+            ? { targetType: 'element', targetId: model.id }
+            : blockTarget(model.id, ctx);
+    }
+    const text = ctx.selection.find(TextSelection);
+    if (text)
+        return textTarget(text, ctx);
+    if (ctx.selection.filter(BlockSelection).length > 1)
+        return null;
+    return blockTarget(ctx.getCurrentModelBy(BlockSelection)?.id, ctx);
+}
+/**
+ * Ask the host to open the discussion of `target`, with the excerpt the
+ * library computes. Nothing is written: no prop, no id in the document.
+ * Without the seam, nothing happens. `range` is handed over only when there
+ * is one, so a host comparing requests sees the first shape for a whole block.
+ */
+export function openThreadOn(std, target) {
+    const service = std.getOptional(ThreadMarksProvider);
+    if (!service)
+        return;
+    service.openThread({
+        docId: std.store.id,
+        targetType: target.targetType,
+        targetId: target.targetId,
+        excerpt: threadExcerpt(std, target),
+        ...(target.range ? { range: target.range } : {}),
+    });
+}
+export const THREAD_DISCUSS_ACTION_ID = 'g.thread-discuss';
+/**
+ * "Discuss" in the toolbar of every block and every canvas element (ADR 0038).
+ * Shown only when the host registered the seam and the row speaks for one
+ * target. It is not AFFiNE's `blockCommentToolbarButton`: that one writes the
+ * comment id into the block.
+ */
+export const threadDiscussToolbarConfig = {
+    when: ctx => Boolean(ctx.std.getOptional(ThreadMarksProvider)) &&
+        threadTargetOf(ctx) !== null,
+    actions: [
+        {
+            id: THREAD_DISCUSS_ACTION_ID,
+            icon: CommentIcon(),
+            labelWording: THREAD_DISCUSS,
+            tooltipWording: THREAD_DISCUSS,
+            run: ctx => {
+                const target = threadTargetOf(ctx);
+                if (target)
+                    openThreadOn(ctx.std, target);
+            },
+        },
+    ],
+};
+/**
+ * Registered on the two wildcard rows, each under an owner key: the bare
+ * `affine:surface:*` is the root's built-in canvas module, and an owner key
+ * never collides with a bare one. `affine:*` is merged into every row the
+ * toolbar draws; `affine:surface:*` names the canvas rows explicitly, so a
+ * row that stopped merging `affine:*` would still offer it. Where both apply,
+ * the toolbar merges entries by id, so the row shows "Discuss" once. A new
+ * block or framework inherits it by doing nothing.
+ */
+export const threadDiscussToolbarExtensions = [
+    ToolbarModuleExtension({
+        id: BlockFlavourIdentifier(toolbarModuleKey('affine:*', 'thread')),
+        config: threadDiscussToolbarConfig,
+    }),
+    ToolbarModuleExtension({
+        id: BlockFlavourIdentifier(toolbarModuleKey('affine:surface:*', 'thread')),
+        config: threadDiscussToolbarConfig,
+    }),
+];

package/dist/_pkgs/affine-widget-thread-marks/translations.d.ts

@@ -0,0 +1,9 @@
+import type { ChromeWording } from '../affine-shared/services/index.js';
+/**
+ * "Discuss": the toolbar action that asks the host to open the discussion of
+ * a block or a canvas element, and the accessible name of the mark drawn on
+ * what already has one (ADR 0038).
+ */
+export declare const THREAD_DISCUSS: ChromeWording;
+/** Every wording this package declares, in the order it renders them. */
+export declare const THREAD_MARKS_WORDINGS: readonly ChromeWording[];

package/dist/_pkgs/affine-widget-thread-marks/translations.js

@@ -0,0 +1,11 @@
+/**
+ * "Discuss": the toolbar action that asks the host to open the discussion of
+ * a block or a canvas element, and the accessible name of the mark drawn on
+ * what already has one (ADR 0038).
+ */
+export const THREAD_DISCUSS = [
+    'com.labre.thread.discuss',
+    'Discuss',
+];
+/** Every wording this package declares, in the order it renders them. */
+export const THREAD_MARKS_WORDINGS = [THREAD_DISCUSS];

package/dist/_pkgs/affine-widget-thread-marks/view.d.ts

@@ -0,0 +1,12 @@
+import { type ViewExtensionContext, ViewExtensionProvider } from '../affine-ext-loader/index.js';
+/**
+ * The "has a thread" seam's view side (ADR 0038): the marks widget and the
+ * "Discuss" toolbar module, in both views. Registered unconditionally: the
+ * seam, not a flag, decides whether anything shows (no flag gates a
+ * discussion, labre P5).
+ */
+export declare class ThreadMarksViewExtension extends ViewExtensionProvider {
+    name: string;
+    effect(): void;
+    setup(context: ViewExtensionContext): void;
+}

package/dist/_pkgs/affine-widget-thread-marks/view.js

@@ -0,0 +1,25 @@
+import { ViewExtensionProvider, } from '../affine-ext-loader/index.js';
+import { effects } from './effects.js';
+import { threadMarksWidget } from './index.js';
+import { threadDiscussToolbarExtensions } from './toolbar.js';
+/**
+ * The "has a thread" seam's view side (ADR 0038): the marks widget and the
+ * "Discuss" toolbar module, in both views. Registered unconditionally: the
+ * seam, not a flag, decides whether anything shows (no flag gates a
+ * discussion, labre P5).
+ */
+export class ThreadMarksViewExtension extends ViewExtensionProvider {
+    constructor() {
+        super(...arguments);
+        this.name = 'affine-thread-marks-widget';
+    }
+    effect() {
+        super.effect();
+        effects();
+    }
+    setup(context) {
+        super.setup(context);
+        context.register(threadMarksWidget);
+        context.register(threadDiscussToolbarExtensions);
+    }
+}

package/dist/_pkgs/affine-widget-thread-marks/widget.d.ts

@@ -0,0 +1,80 @@
+import { type SelectionRect } from '../affine-shared/commands/index.js';
+import { type ThreadMark } from '../affine-shared/services/index.js';
+import { WidgetComponent } from '../std/index.js';
+import { nothing } from 'lit';
+export declare const AFFINE_THREAD_MARKS_WIDGET = "affine-thread-marks-widget";
+/**
+ * Where a mark sits, relative to the widget's own origin: beside a block of
+ * the page (`side`, in the right gutter, at the block's top), or on the
+ * top-right corner of a canvas model or of a block inside a canvas note
+ * (`corner`, centred on it).
+ */
+export interface ThreadMarkPlace {
+    x: number;
+    y: number;
+    anchor: 'side' | 'corner';
+}
+export interface PlacedThreadMark extends ThreadMarkPlace {
+    mark: ThreadMark;
+}
+/** Is the point (viewport coordinates) inside one of the rects? */
+export declare function hitsThreadRange(rects: readonly SelectionRect[], x: number, y: number): boolean;
+/**
+ * The marks to draw, from what the host says and where the editor finds each
+ * target. Pure, so the "ignore what is absent" rule is held by a test:
+ *
+ * - a target `locate` cannot find (deleted, of the other view, hidden for this
+ *   viewer) is skipped, never an error: an orphan anchor has no mark;
+ * - a mark at `count <= 0` is not drawn;
+ * - two marks on one target are one mark: counts add up, unread wins.
+ */
+export declare function placeThreadMarks(marks: readonly ThreadMark[], locate: (mark: ThreadMark) => ThreadMarkPlace | null): PlacedThreadMark[];
+/**
+ * The "has a thread" marks (ADR 0038), one widget for both views, mounted on
+ * the root like `remote-selection`: in the page view beside each marked block,
+ * on the canvas on the corner of each marked element or block. A click asks
+ * the host to open the discussion, exactly as "Discuss" does.
+ *
+ * A mark that carries a `range` also highlights that run of its block's text
+ * in the page view (ADR 0038, amendment of 2026-10-15). The run is resolved
+ * from its Yjs relative positions on every render and drawn as the range's
+ * client rects (the technique of `doc-remote-selection`), never as a mark in
+ * the text. The highlight takes no pointer event, so nothing blocks placing
+ * the caret or selecting; a click that lands on it with nothing selected
+ * opens its discussion. A run that no longer resolves is not drawn, and the
+ * block's own mark stays.
+ *
+ * It reads the seam and the layout, and writes nothing. Positions are
+ * client rects taken relative to the widget's own box and recomputed, once a
+ * frame at most, when the marks, the document, the canvas or the window
+ * change. Without the seam it renders nothing.
+ */
+export declare class ThreadMarksWidget extends WidgetComponent {
+    static styles: import("lit").CSSResult;
+    private readonly _refresh;
+    private get _edgeless();
+    connectedCallback(): void;
+    /**
+     * A click on a highlighted run opens its discussion. The click is not
+     * consumed: the caret lands where it was put. A click that ends a drag
+     * (something is selected) is a selection, not a request.
+     */
+    private readonly _onClick;
+    /** Open the discussion of the run under the point, if there is one. */
+    private _openRangeAt;
+    private _resolve;
+    /**
+     * The runs to highlight, in viewport coordinates, page view only: on the
+     * canvas a note's text may sit under a shape, and this overlay would paint
+     * over it. `ponytail:` a run in a canvas note keeps only its block's mark;
+     * drawing it there needs the canvas stacking, if a reader asks for it.
+     */
+    private _ranges;
+    private _locate;
+    render(): import("lit-html").TemplateResult<1> | typeof nothing;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        [AFFINE_THREAD_MARKS_WIDGET]: ThreadMarksWidget;
+    }
+}

package/dist/_pkgs/affine-widget-thread-marks/widget.js

@@ -0,0 +1,325 @@
+import { CommentIcon } from '@blocksuite/icons/lit';
+import { isPainted } from '../affine-block-surface/index.js';
+import { getRangeRects, } from '../affine-shared/commands/index.js';
+import { ThreadMarksProvider, translateKey, } from '../affine-shared/services/index.js';
+import { isInsideEdgelessEditor, requestThrottledConnectedFrame, } from '../affine-shared/utils/index.js';
+import { TextSelection, WidgetComponent } from '../std/index.js';
+import { GfxBlockElementModel, GfxControllerIdentifier, GfxPrimitiveElementModel, } from '../std/gfx/index.js';
+import { effect } from '@preact/signals-core';
+import { cssVarV2 } from '@toeverything/theme/v2';
+import { css, html, nothing, unsafeCSS } from 'lit';
+import { repeat } from 'lit/directives/repeat.js';
+import { styleMap } from 'lit/directives/style-map.js';
+import { resolveThreadRange } from './text-range.js';
+import { openThreadOn } from './toolbar.js';
+import { THREAD_DISCUSS } from './translations.js';
+export const AFFINE_THREAD_MARKS_WIDGET = 'affine-thread-marks-widget';
+/** Is the point (viewport coordinates) inside one of the rects? */
+export function hitsThreadRange(rects, x, y) {
+    return rects.some(rect => x >= rect.left &&
+        x <= rect.left + rect.width &&
+        y >= rect.top &&
+        y <= rect.top + rect.height);
+}
+/**
+ * The marks to draw, from what the host says and where the editor finds each
+ * target. Pure, so the "ignore what is absent" rule is held by a test:
+ *
+ * - a target `locate` cannot find (deleted, of the other view, hidden for this
+ *   viewer) is skipped, never an error: an orphan anchor has no mark;
+ * - a mark at `count <= 0` is not drawn;
+ * - two marks on one target are one mark: counts add up, unread wins.
+ */
+export function placeThreadMarks(marks, locate) {
+    const merged = new Map();
+    for (const mark of marks) {
+        if (!(mark.count > 0))
+            continue;
+        const key = `${mark.targetType}:${mark.targetId}`;
+        const seen = merged.get(key);
+        merged.set(key, seen
+            ? {
+                ...seen,
+                count: seen.count + mark.count,
+                unread: seen.unread || mark.unread,
+            }
+            : mark);
+    }
+    const placed = [];
+    for (const mark of merged.values()) {
+        const place = locate(mark);
+        if (place)
+            placed.push({ ...place, mark });
+    }
+    return placed;
+}
+/**
+ * The "has a thread" marks (ADR 0038), one widget for both views, mounted on
+ * the root like `remote-selection`: in the page view beside each marked block,
+ * on the canvas on the corner of each marked element or block. A click asks
+ * the host to open the discussion, exactly as "Discuss" does.
+ *
+ * A mark that carries a `range` also highlights that run of its block's text
+ * in the page view (ADR 0038, amendment of 2026-10-15). The run is resolved
+ * from its Yjs relative positions on every render and drawn as the range's
+ * client rects (the technique of `doc-remote-selection`), never as a mark in
+ * the text. The highlight takes no pointer event, so nothing blocks placing
+ * the caret or selecting; a click that lands on it with nothing selected
+ * opens its discussion. A run that no longer resolves is not drawn, and the
+ * block's own mark stays.
+ *
+ * It reads the seam and the layout, and writes nothing. Positions are
+ * client rects taken relative to the widget's own box and recomputed, once a
+ * frame at most, when the marks, the document, the canvas or the window
+ * change. Without the seam it renders nothing.
+ */
+export class ThreadMarksWidget extends WidgetComponent {
+    constructor() {
+        super(...arguments);
+        this._refresh = requestThrottledConnectedFrame(() => {
+            this.requestUpdate();
+        }, this);
+        /**
+         * A click on a highlighted run opens its discussion. The click is not
+         * consumed: the caret lands where it was put. A click that ends a drag
+         * (something is selected) is a selection, not a request.
+         */
+        this._onClick = (event) => {
+            if (window.getSelection()?.isCollapsed === false)
+                return;
+            this._openRangeAt(event.clientX, event.clientY);
+        };
+    }
+    static { this.styles = css `
+    :host {
+      position: absolute;
+      top: 0;
+      left: 0;
+      width: 0;
+      height: 0;
+      overflow: visible;
+      pointer-events: none;
+      z-index: 1;
+    }
+
+    .thread-mark {
+      position: absolute;
+      top: 0;
+      left: 0;
+      gap: 2px;
+      padding: 0 6px 0 4px;
+      border-radius: 12px;
+      border: 1px solid ${unsafeCSS(cssVarV2('layer/insideBorder/border'))};
+      background: ${unsafeCSS(cssVarV2('layer/background/overlayPanel'))};
+      box-shadow: var(--affine-shadow-1);
+      color: ${unsafeCSS(cssVarV2('text/secondary'))};
+      pointer-events: auto;
+    }
+
+    .thread-range {
+      position: absolute;
+      top: 0;
+      left: 0;
+      background-color: ${unsafeCSS(cssVarV2('block/comment/highlightDefault'))};
+      border-bottom: 2px solid
+        ${unsafeCSS(cssVarV2('block/comment/highlightUnderline'))};
+      pointer-events: none;
+    }
+
+    .thread-mark[data-unread] {
+      color: ${unsafeCSS(cssVarV2('text/emphasis'))};
+    }
+
+    @media (pointer: coarse) {
+      .thread-mark::after {
+        content: '';
+        position: absolute;
+        inset: -10px;
+      }
+    }
+  `; }
+    get _edgeless() {
+        return isInsideEdgelessEditor(this.std.host);
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        const { _disposables, std } = this;
+        // The seam is fixed for the editor's life: without it, follow nothing,
+        // so a host that has no threads pays nothing on a pan or a keystroke.
+        if (!std.getOptional(ThreadMarksProvider))
+            return;
+        _disposables.add(std.store.slots.blockUpdated.subscribe(this._refresh));
+        // A block mounts after the widget: a mark on it can only be placed then.
+        _disposables.add(std.view.viewUpdated.subscribe(this._refresh));
+        _disposables.addFromEvent(window, 'resize', this._refresh);
+        // Capture: the page view scrolls in a container, not the window.
+        _disposables.addFromEvent(window, 'scroll', this._refresh, true);
+        // A highlighted run moves with every keystroke, local or remote, and a
+        // text edit is no block update: follow the document itself.
+        const doc = std.store.spaceDoc;
+        doc.on('update', this._refresh);
+        _disposables.add(() => doc.off('update', this._refresh));
+        _disposables.addFromEvent(std.host, 'click', this._onClick);
+        const gfx = std.getOptional(GfxControllerIdentifier);
+        if (gfx) {
+            _disposables.add(gfx.viewport.viewportUpdated.subscribe(this._refresh));
+            // The surface may load after the widget connects: follow it.
+            _disposables.add(effect(() => {
+                const surface = gfx.surface$.value;
+                if (!surface)
+                    return;
+                this._refresh();
+                const subscriptions = [
+                    surface.elementAdded.subscribe(this._refresh),
+                    surface.elementRemoved.subscribe(this._refresh),
+                    surface.elementUpdated.subscribe(this._refresh),
+                ];
+                return () => subscriptions.forEach(s => s.unsubscribe());
+            }));
+        }
+    }
+    /** Open the discussion of the run under the point, if there is one. */
+    _openRangeAt(x, y) {
+        const service = this.std.getOptional(ThreadMarksProvider);
+        if (!service)
+            return;
+        const hit = this._ranges(service.marks$.peek()).find(({ rects }) => hitsThreadRange(rects, x, y));
+        if (!hit)
+            return;
+        openThreadOn(this.std, {
+            targetType: 'block',
+            targetId: hit.mark.targetId,
+            range: hit.mark.range,
+        });
+    }
+    _resolve(mark) {
+        if (mark.targetType !== 'block' || !mark.range)
+            return null;
+        const yText = this.std.store.getModelById(mark.targetId)?.text?.yText;
+        return yText ? resolveThreadRange(yText, mark.range) : null;
+    }
+    /**
+     * The runs to highlight, in viewport coordinates, page view only: on the
+     * canvas a note's text may sit under a shape, and this overlay would paint
+     * over it. `ponytail:` a run in a canvas note keeps only its block's mark;
+     * drawing it there needs the canvas stacking, if a reader asks for it.
+     */
+    _ranges(marks) {
+        if (this._edgeless)
+            return [];
+        const drawn = [];
+        for (const mark of marks) {
+            if (!(mark.count > 0))
+                continue;
+            const run = this._resolve(mark);
+            if (!run)
+                continue;
+            let range;
+            try {
+                range = this.std.range.textSelectionToRange(this.std.selection.create(TextSelection, {
+                    from: { blockId: mark.targetId, ...run },
+                    to: null,
+                }));
+            }
+            catch {
+                // The inline editor has not rendered the latest text yet: the next
+                // frame draws it.
+                range = null;
+            }
+            if (!range)
+                continue;
+            const rects = getRangeRects(range, null);
+            if (rects.length > 0)
+                drawn.push({ mark, rects });
+        }
+        return drawn;
+    }
+    _locate(mark, origin) {
+        const edgeless = this._edgeless;
+        if (edgeless) {
+            const gfx = this.std.get(GfxControllerIdentifier);
+            const model = gfx.getElementById(mark.targetId);
+            if (model instanceof GfxPrimitiveElementModel ||
+                model instanceof GfxBlockElementModel) {
+                // What this viewer does not see carries no mark (ADR 0031): the
+                // renderers' own predicate for an element, the local hide for a block.
+                const painted = model instanceof GfxPrimitiveElementModel
+                    ? isPainted(model, gfx.localVisibility)
+                    : !gfx.localVisibility.isHidden(model);
+                if (!painted)
+                    return null;
+                const bound = model.elementBound;
+                const [x, y] = gfx.viewport.toViewCoord(bound.maxX, bound.y);
+                return {
+                    x: x + gfx.viewport.left - origin.left,
+                    y: y + gfx.viewport.top - origin.top,
+                    anchor: 'corner',
+                };
+            }
+        }
+        if (mark.targetType !== 'block')
+            return null;
+        const block = this.std.view.getBlock(mark.targetId);
+        if (!block)
+            return null;
+        const rect = block.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0)
+            return null;
+        return {
+            x: rect.right - origin.left,
+            y: rect.top - origin.top,
+            anchor: edgeless ? 'corner' : 'side',
+        };
+    }
+    render() {
+        const service = this.std.getOptional(ThreadMarksProvider);
+        if (!service)
+            return nothing;
+        const marks = service.marks$.value;
+        if (marks.length === 0)
+            return nothing;
+        const origin = this.getBoundingClientRect();
+        const placed = placeThreadMarks(marks, mark => this._locate(mark, origin));
+        const ranges = this._ranges(marks);
+        if (placed.length === 0 && ranges.length === 0)
+            return nothing;
+        const label = translateKey(this.std, ...THREAD_DISCUSS);
+        const highlights = ranges.flatMap(({ mark, rects }) => rects.map(rect => html `<div
+            class="thread-range"
+            data-testid="thread-range"
+            data-target-id=${mark.targetId}
+            style=${styleMap({
+            width: `${rect.width}px`,
+            height: `${rect.height}px`,
+            transform: `translate(${rect.left - origin.left}px, ${rect.top - origin.top}px)`,
+        })}
+          ></div>`));
+        return html `${highlights}${repeat(placed, ({ mark }) => `${mark.targetType}:${mark.targetId}`, ({ mark, x, y, anchor }) => html `<icon-button
+          class="thread-mark"
+          data-testid="thread-mark"
+          data-target-type=${mark.targetType}
+          data-target-id=${mark.targetId}
+          ?data-unread=${mark.unread}
+          width="auto"
+          height="24px"
+          .active=${mark.unread}
+          .text=${String(mark.count)}
+          aria-label=${label}
+          title=${label}
+          style=${styleMap({
+            transform: anchor === 'side'
+                ? `translate(${x + 8}px, ${y}px)`
+                : `translate(${x}px, ${y}px) translate(-50%, -50%)`,
+        })}
+          @pointerdown=${(event) => event.stopPropagation()}
+          @click=${(event) => {
+            event.stopPropagation();
+            openThreadOn(this.std, {
+                targetType: mark.targetType,
+                targetId: mark.targetId,
+            });
+        }}
+          >${CommentIcon({ width: '16px', height: '16px' })}</icon-button
+        >`)}`;
+    }
+}

package/dist/extensions/view.js

@@ -54,6 +54,7 @@ import { PageDraggingAreaViewExtension } from '../_pkgs/affine-widget-page-dragg
 import { RemoteSelectionViewExtension } from '../_pkgs/affine-widget-remote-selection/view.js';
 import { ScrollAnchoringViewExtension } from '../_pkgs/affine-widget-scroll-anchoring/view.js';
 import { SlashMenuViewExtension } from '../_pkgs/affine-widget-slash-menu/view.js';
+import { ThreadMarksViewExtension } from '../_pkgs/affine-widget-thread-marks/view.js';
 import { ToolbarViewExtension } from '../_pkgs/affine-widget-toolbar/view.js';
 import { ViewportOverlayViewExtension } from '../_pkgs/affine-widget-viewport-overlay/view.js';
 import { isBlockEnabled, isCapabilityEnabled, } from '../flags.js';
@@ -158,6 +159,7 @@ export function getInternalViewExtensions(flags) {
         KeyboardToolbarViewExtension,
         LinkedDocViewExtension,
         RemoteSelectionViewExtension,
+        ThreadMarksViewExtension,
         ScrollAnchoringViewExtension,
         SlashMenuViewExtension,
         ToolbarViewExtension,

package/dist/host-panels.d.ts

@@ -58,6 +58,9 @@ export { type SelectionPaneNode, selectionPaneTree, } from './_pkgs/affine-block
 export { frameCommands, type ReorderFramesParams, reorderFramesParams, } from './_pkgs/affine-block-frame/index.js';
 export { formatPropertyValue, isPropertyValueEmpty, } from './_pkgs/affine-fragment-doc-title/index.js';
 export type { PropertiesPanelRequest, PropertiesPanelService, TitleBandNotShownPage, TitleBandProperty, TitleBandService, TitleBandSheetState, } from './_pkgs/affine-shared/services/index.js';
+export { ThreadMarksExtension } from './_pkgs/affine-shared/services/index.js';
+export type { ThreadMark, ThreadMarksService, ThreadMarkTargetType, ThreadOpenRequest, ThreadTextRange, } from './_pkgs/affine-shared/services/index.js';
+export { type ThreadTarget, threadExcerpt, } from './_pkgs/affine-widget-thread-marks/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

package/dist/host-panels.js

@@ -70,6 +70,18 @@ export { frameCommands, reorderFramesParams, } from './_pkgs/affine-block-frame/
  * value.
  */
 export { formatPropertyValue, isPropertyValueEmpty, } from './_pkgs/affine-fragment-doc-title/index.js';
+/*
+ * The "has a thread" seam (ADR 0038). The editor marks what the host says
+ * has a discussion and asks the host to open one, with an excerpt it
+ * computes; the host registers `ThreadMarksExtension({ marks$, openThread })`
+ * among its editor extensions. Gathered here with its types so a host's
+ * discussion module imports one entry; `threadExcerpt` is the excerpt the
+ * editor hands `openThread`, for a host that starts a discussion from its
+ * own UI. `ThreadTextRange` (amendment of 2026-10-15) is the opaque text
+ * anchor a request may carry and a mark may hand back.
+ */
+export { ThreadMarksExtension } from './_pkgs/affine-shared/services/index.js';
+export { threadExcerpt, } from './_pkgs/affine-widget-thread-marks/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

package/dist/translations.js

@@ -41,6 +41,7 @@ import { EDGELESS_TOOLBAR_WORDINGS } from './_pkgs/affine-widget-edgeless-toolba
 import { ZOOM_TOOLBAR_WORDINGS } from './_pkgs/affine-widget-edgeless-zoom-toolbar/translations.js';
 import { LINKED_DOC_WORDINGS } from './_pkgs/affine-widget-linked-doc/translations.js';
 import { REMOTE_SELECTION_WORDINGS } from './_pkgs/affine-widget-remote-selection/translations.js';
+import { THREAD_MARKS_WORDINGS } from './_pkgs/affine-widget-thread-marks/translations.js';
 import { SLASH_MENU_WORDINGS } from './_pkgs/affine-widget-slash-menu/translations.js';
 import { TOOLBAR_WIDGET_WORDINGS } from './_pkgs/affine-widget-toolbar/translations.js';
 import { collectTranslationKeys, commandCategoryTranslationEntries, commandTranslationEntries, mergeTranslationEntries, } from './_pkgs/std/index.js';
@@ -309,6 +310,7 @@ const PACKAGE_WORDINGS = [
     ZOOM_TOOLBAR_WORDINGS,
     LINKED_DOC_WORDINGS,
     REMOTE_SELECTION_WORDINGS,
+    THREAD_MARKS_WORDINGS,
     TOOLBAR_WIDGET_WORDINGS,
     COMPONENTS_WORDINGS,
     INLINE_LATEX_WORDINGS,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@formicoidea/labre-core",
   "description": "Labre editor — the full BlockSuite-derived editor as one package.",
-  "version": "0.51.0",
+  "version": "0.53.0",
   "type": "module",
   "sideEffects": false,
   "author": "lajola",