@kortix/ui 0.0.0-stage → 0.14.4

package/dist/session/composer/editor/mention-node.d.ts

@@ -0,0 +1,51 @@
+import { Editor, Node } from '@tiptap/core';
+import type { ChipKind } from '../types.js';
+export interface MentionAttrs {
+    kind: ChipKind;
+    label: string;
+    value: string;
+}
+export { chipAriaLabel, chipClass, chipPrefix, chipText } from '../../thread/mention-chip.js';
+/**
+ * An indivisible inline badge — an `@` mention or a `/` command.
+ *
+ * `atom: true` is the entire point: the caret can never land inside the badge,
+ * one backspace removes it whole, and every occurrence is a distinct node. The
+ * string model it replaces could do none of these — `text.indexOf(needle)`
+ * found only the FIRST match, so a second `@README.md` rendered as plain text.
+ *
+ * The node is named `mention` for both kinds rather than split into a second
+ * node type. One atom means one schema entry, one `parseHTML` contract, one
+ * serializer walk (`serialize.ts`), and — the reason that matters here — one
+ * set of atom semantics: a command chip gets whole-node backspace, drag-safe
+ * boundaries, and survives the `getDocument`/`setDocument` round trip that
+ * failed-send recovery and the question lock depend on, for free. What
+ * separates the two kinds is `kind`, read at render and at serialize time.
+ */
+export declare const MentionNode: Node<any, any>;
+/**
+ * Turn a picked menu item into a node in the document. This is the only
+ * place that knows the insertion shape (chip node + trailing space so the
+ * user can keep typing without first pressing space themselves) — the menus
+ * that call it only need to know kind/label/value.
+ */
+export declare function insertMention(editor: Editor, attrs: MentionAttrs): void;
+/**
+ * Insert a `/` command as an inline chip.
+ *
+ * This is the whole of the "commands behave like mentions" change. The command
+ * used to leave the document entirely and become shell state
+ * (`composer.tsx`'s `stagedCommand`), which forced the `/` menu to be fed an
+ * empty command list for as long as it was staged — so `/` visibly stopped
+ * working after the first pick. As a chip it stays in the document: the menu
+ * is never suppressed, `/` opens as many times as you press it, backspace
+ * removes the chip whole, and the args are simply whatever text sits around
+ * it.
+ *
+ * `value` carries the command NAME, not the `Command` object. Node attributes
+ * have to survive a JSON round trip (`getDocument`/`setDocument`, used by
+ * failed-send recovery and the question lock), and the resolved `Command` is
+ * looked back up from the live list at submit time — so a chip can never go
+ * stale against a command list that changed underneath it.
+ */
+export declare function insertCommandChip(editor: Editor, name: string): void;

package/dist/session/composer/editor/mention-node.js

@@ -0,0 +1,125 @@
+import { Node, mergeAttributes } from '@tiptap/core';
+import { chipAriaLabel, chipClass, chipText } from '../../thread/mention-chip.js';
+// `chipPrefix` / `chipText` / `chipClass` / `chipAriaLabel` used to live here.
+// They moved to `packages/ui/src/session/thread/mention-chip.tsx` so the SENT message can
+// draw the identical chip — see that module's header for what was broken
+// while this file was their only home. Re-exported because this node is the
+// composer's canonical entry point for them.
+export { chipAriaLabel, chipClass, chipPrefix, chipText } from '../../thread/mention-chip.js';
+/**
+ * An indivisible inline badge — an `@` mention or a `/` command.
+ *
+ * `atom: true` is the entire point: the caret can never land inside the badge,
+ * one backspace removes it whole, and every occurrence is a distinct node. The
+ * string model it replaces could do none of these — `text.indexOf(needle)`
+ * found only the FIRST match, so a second `@README.md` rendered as plain text.
+ *
+ * The node is named `mention` for both kinds rather than split into a second
+ * node type. One atom means one schema entry, one `parseHTML` contract, one
+ * serializer walk (`serialize.ts`), and — the reason that matters here — one
+ * set of atom semantics: a command chip gets whole-node backspace, drag-safe
+ * boundaries, and survives the `getDocument`/`setDocument` round trip that
+ * failed-send recovery and the question lock depend on, for free. What
+ * separates the two kinds is `kind`, read at render and at serialize time.
+ */
+export const MentionNode = Node.create({
+    name: 'mention',
+    group: 'inline',
+    inline: true,
+    atom: true,
+    selectable: true,
+    draggable: false,
+    // Each attribute renders to (and parses back from) its own `data-*`
+    // attribute. Without this, TipTap's default per-attribute fallback would
+    // still round-trip `kind`/`label`/`value` as bare, non-namespaced HTML
+    // attributes (`kind="file"`) — which happens to work but collides with
+    // `value`'s real HTML meaning on form elements and isn't the documented
+    // wire shape. Explicit `data-mention-*` names are what `parseHTML()`'s
+    // `span[data-mention]` selector below is actually meant to read back.
+    addAttributes() {
+        return {
+            kind: {
+                default: 'file',
+                parseHTML: (element) => element.getAttribute('data-mention'),
+                renderHTML: (attrs) => ({ 'data-mention': attrs.kind }),
+            },
+            label: {
+                default: '',
+                parseHTML: (element) => element.getAttribute('data-mention-label'),
+                renderHTML: (attrs) => ({ 'data-mention-label': attrs.label }),
+            },
+            value: {
+                default: '',
+                parseHTML: (element) => element.getAttribute('data-mention-value'),
+                renderHTML: (attrs) => ({ 'data-mention-value': attrs.value }),
+            },
+        };
+    },
+    parseHTML() {
+        return [{ tag: 'span[data-mention]' }];
+    },
+    renderHTML({ HTMLAttributes, node }) {
+        const label = String(node.attrs.label ?? '');
+        const kind = String(node.attrs.kind ?? 'file');
+        return [
+            'span',
+            mergeAttributes(HTMLAttributes, {
+                'aria-label': chipAriaLabel(kind, label),
+                class: chipClass(kind),
+            }),
+            chipText(kind, label),
+        ];
+    },
+    /**
+     * Feeds TipTap's own `editor.getText()` helper only — `serialize.ts`'s
+     * `textBetween` passes an explicit `leafText` callback, which ProseMirror
+     * prioritises over `spec.toText` (what this compiles to). The two are kept
+     * deliberately identical, INCLUDING the command case: a command chip
+     * contributes NOTHING to the message text on either path, because it is not
+     * body text — it leaves the composer through `onCommand(command, args)`,
+     * and the text that remains IS the args. Returning `/name` here would
+     * silently prepend the command name to its own arguments.
+     */
+    renderText({ node }) {
+        if (node.attrs.kind === 'command')
+            return '';
+        return `@${node.attrs.label}`;
+    },
+});
+/**
+ * Turn a picked menu item into a node in the document. This is the only
+ * place that knows the insertion shape (chip node + trailing space so the
+ * user can keep typing without first pressing space themselves) — the menus
+ * that call it only need to know kind/label/value.
+ */
+export function insertMention(editor, attrs) {
+    editor
+        .chain()
+        .focus()
+        .insertContent([
+        { type: MentionNode.name, attrs },
+        { type: 'text', text: ' ' },
+    ])
+        .run();
+}
+/**
+ * Insert a `/` command as an inline chip.
+ *
+ * This is the whole of the "commands behave like mentions" change. The command
+ * used to leave the document entirely and become shell state
+ * (`composer.tsx`'s `stagedCommand`), which forced the `/` menu to be fed an
+ * empty command list for as long as it was staged — so `/` visibly stopped
+ * working after the first pick. As a chip it stays in the document: the menu
+ * is never suppressed, `/` opens as many times as you press it, backspace
+ * removes the chip whole, and the args are simply whatever text sits around
+ * it.
+ *
+ * `value` carries the command NAME, not the `Command` object. Node attributes
+ * have to survive a JSON round trip (`getDocument`/`setDocument`, used by
+ * failed-send recovery and the question lock), and the resolved `Command` is
+ * looked back up from the live list at submit time — so a chip can never go
+ * stale against a command list that changed underneath it.
+ */
+export function insertCommandChip(editor, name) {
+    insertMention(editor, { kind: 'command', label: name, value: name });
+}

package/dist/session/composer/editor/serialize.d.ts

@@ -0,0 +1,69 @@
+import type { Node as ProseMirrorNode } from '@tiptap/pm/model';
+import type { TrackedMention } from '../types.js';
+/**
+ * The shape `collectMentions` needs — kept structural so it is testable
+ * without constructing a real ProseMirror document.
+ */
+export interface SerializableNode {
+    type: string;
+    text?: string;
+    attrs?: {
+        kind?: string;
+        label?: string;
+        value?: string;
+    };
+}
+/**
+ * Walk a flattened node list and pull out every mention as a
+ * `TrackedMention`, in document order, one entry per occurrence.
+ *
+ * This is the fix for the bug the whole node model exists to kill: the old
+ * string-based composer resolved mentions with `text.indexOf(needle)`, which
+ * finds only the FIRST match, so two `@README.md` mentions collapsed into
+ * one tracked mention. Each mention is its own atom node here, so this just
+ * pushes one entry per node — duplicates cannot merge or drop.
+ */
+export declare function collectMentions(nodes: SerializableNode[]): TrackedMention[];
+/**
+ * The name of the FIRST `/` command chip in the document, or `undefined`.
+ *
+ * First, not last, and not a list: a message runs at most one command, and the
+ * first chip is the one the user picked to lead the message. A second chip is
+ * left in the text as a no-op rather than silently changing which command
+ * runs — inserting one is a deliberate keystroke, and reordering the user's
+ * intent behind their back is worse than ignoring the extra.
+ */
+export declare function collectCommandName(nodes: SerializableNode[]): string | undefined;
+/** Flatten a ProseMirror document into the structural node list above. */
+export declare function flattenDocument(doc: ProseMirrorNode): SerializableNode[];
+export declare function serializeDocument(doc: ProseMirrorNode): {
+    text: string;
+    mentions: TrackedMention[];
+    /**
+     * The `/` command chip leading this message, if there is one. Structured,
+     * exactly like `mentions` — and for the same reason: `text` is the
+     * human-readable body, and a command is not body. What `text` holds when
+     * this is set IS the command's arguments, with no stripping needed at the
+     * call site.
+     */
+    commandName?: string;
+    /**
+     * `text`, split at the point the chip actually sat.
+     *
+     * The chip contributes no characters, so without this its POSITION is lost
+     * the moment the document is serialized — and "lost" meant "silently moved
+     * to the front". Type `explain /webapp to me` and the sent message came back
+     * as `/webapp explain to me`, because every consumer downstream rebuilt the
+     * display as `/name` + args with nothing to say otherwise.
+     *
+     * Display only. `text` is unchanged and remains exactly what the server
+     * receives as `$ARGUMENTS` — where the chip sat in the sentence is a fact
+     * about how the user wrote it, not about what the command should run on.
+     * Both halves are trimmed, so re-joining them with a single space
+     * reconstructs `text` for a chip that sat between words.
+     */
+    commandSplit?: {
+        before: string;
+        after: string;
+    };
+};

package/dist/session/composer/editor/serialize.js

@@ -0,0 +1,175 @@
+/**
+ * Walk a flattened node list and pull out every mention as a
+ * `TrackedMention`, in document order, one entry per occurrence.
+ *
+ * This is the fix for the bug the whole node model exists to kill: the old
+ * string-based composer resolved mentions with `text.indexOf(needle)`, which
+ * finds only the FIRST match, so two `@README.md` mentions collapsed into
+ * one tracked mention. Each mention is its own atom node here, so this just
+ * pushes one entry per node — duplicates cannot merge or drop.
+ */
+export function collectMentions(nodes) {
+    const mentions = [];
+    for (const node of nodes) {
+        if (node.type !== 'mention')
+            continue;
+        // `command` chips share the `mention` atom node (see mention-node.ts) but
+        // are NOT references: they leave the composer as `onCommand(command,
+        // args)`, never as a `<file_ref>`/`<agent_ref>`/`<session_ref>` block. If
+        // they fell through here they would reach `buildFileRefsBlock` as a file
+        // named after the command and the agent would be asked to read a path
+        // that does not exist.
+        if (node.attrs?.kind === 'command')
+            continue;
+        const kind = (node.attrs?.kind ?? 'file');
+        const label = node.attrs?.label ?? '';
+        // Only sessions round-trip an id — files and agents are addressed by
+        // label, matching TrackedMention's existing shape (types.ts) and what
+        // session-chat.tsx's send path already expects.
+        mentions.push(kind === 'session' ? { kind, label, value: node.attrs?.value ?? '' } : { kind, label });
+    }
+    return mentions;
+}
+/**
+ * The name of the FIRST `/` command chip in the document, or `undefined`.
+ *
+ * First, not last, and not a list: a message runs at most one command, and the
+ * first chip is the one the user picked to lead the message. A second chip is
+ * left in the text as a no-op rather than silently changing which command
+ * runs — inserting one is a deliberate keystroke, and reordering the user's
+ * intent behind their back is worse than ignoring the extra.
+ */
+export function collectCommandName(nodes) {
+    for (const node of nodes) {
+        if (node.type !== 'mention')
+            continue;
+        if (node.attrs?.kind !== 'command')
+            continue;
+        const label = node.attrs?.label ?? '';
+        if (label)
+            return label;
+    }
+    return undefined;
+}
+/** Flatten a ProseMirror document into the structural node list above. */
+export function flattenDocument(doc) {
+    const nodes = [];
+    doc.descendants((node) => {
+        if (node.type.name === 'mention') {
+            nodes.push({ type: 'mention', attrs: node.attrs });
+            return false;
+        }
+        if (node.isText)
+            nodes.push({ type: 'text', text: node.text ?? '' });
+        return true;
+    });
+    return nodes;
+}
+/**
+ * Turn the live editor document into the `{ text, mentions }` pair the send
+ * path already consumes (`session-chat.tsx`'s `handleSend(rawText, files,
+ * mentions)`).
+ *
+ * `text` keeps every mention inline as `@<label>` — this is the
+ * human-readable body a user typed/sees, not a wire-protocol token: the
+ * three receiving parsers this task must not drift from
+ * (`parseFileMentionReferences`, `parseAgentMentionReferences`,
+ * `parseSessionReferences` in `message-parsing.tsx`) do NOT match `@label`
+ * substrings at all. They match `<file_ref>`/`<agent_ref>`/`<session_ref>`
+ * XML blocks that `session-chat.tsx`'s `handleSend` appends AFTER this text,
+ * built from the separate `mentions` array via `buildFileRefsBlock` /
+ * `buildAgentRefsBlock` (`packages/ui/src/internal/lib/project-preamble.ts`) and its own inline
+ * `<session_ref>` construction. `mentions` is therefore the half of this
+ * return value those parsers actually depend on; `text` only has to stay
+ * human-readable and round-trip through `HighlightMentions`-style `@`
+ * detection, which this format already satisfies.
+ *
+ * The `leafText` callback passed to `textBetween` is the ONLY thing that
+ * governs a mention node's text here — ProseMirror's `Node.textBetween`
+ * prioritises an explicit `leafText` argument over `node.type.spec.leafText`
+ * (see prosemirror-model's `Fragment.textBetween`), and TipTap's
+ * `renderText()` (mention-node.ts) compiles to `spec.toText`, a distinct
+ * field `textBetween` never reads. So `renderText()` is inert on this path;
+ * it exists only for TipTap's own `editor.getText()` helper, which walks the
+ * doc separately. Both are kept literally identical (`@${label}`) so the two
+ * paths can never disagree if something starts calling `getText()` later.
+ */
+/**
+ * The ProseMirror position of the FIRST `/` command chip, or null.
+ *
+ * `collectCommandName` already finds that chip, but a flattened list has no
+ * positions, and a position is what the split below needs. Same "first, not
+ * last" rule and the same reason — see `collectCommandName`.
+ */
+function findCommandPos(doc) {
+    let found = null;
+    doc.descendants((node, pos) => {
+        if (found !== null)
+            return false;
+        if (node.type.name === 'mention' && node.attrs.kind === 'command') {
+            found = pos;
+            return false;
+        }
+        return true;
+    });
+    return found;
+}
+export function serializeDocument(doc) {
+    const flat = flattenDocument(doc);
+    const leafText = (node) => {
+        // A command chip contributes no text — see `MentionNode.renderText`'s
+        // doc comment. The remainder of the paragraph is the args verbatim.
+        if (node.type.name === 'mention' && node.attrs.kind === 'command')
+            return '';
+        if (node.type.name === 'mention')
+            return `@${node.attrs.label}`;
+        // Shift+Enter (and Mod+Enter) insert a `hardBreak` inline leaf —
+        // `@tiptap/extension-hard-break`'s keymap, and the node
+        // `insertTextAtCursor` builds for an embedded `\n`. It MUST serialize to
+        // a newline. Returning '' here dropped the break entirely and glued the
+        // lines together on the wire: "line one" + Shift+Enter + "line two" was
+        // sent as "line oneline two" (matrix row 10). Two things make this a
+        // silent failure rather than an obvious one. First, an explicit
+        // `leafText` FUNCTION argument makes `textBetween` ignore
+        // `node.type.spec.leafText` for every inline leaf, and `hardBreak` has
+        // no `spec.leafText` of its own anyway — so the fallback that would
+        // otherwise cover this does not exist. Second, `blockSeparator` (the
+        // '\n' above) applies only at block boundaries, so multi-PARAGRAPH text
+        // serialized correctly and hid the single-paragraph case. TipTap's own
+        // `editor.getText()` walks the doc by a different route and still
+        // reported "line one\nline two", which is why the pre-existing
+        // `getText()`-based assertions could not see this.
+        if (node.type.name === 'hardBreak')
+            return '\n';
+        return '';
+    };
+    const rawText = doc.textBetween(0, doc.content.size, '\n', leafText);
+    // Split BEFORE trimming: `rawText` and this prefix are produced by the same
+    // walk with the same `leafText`, so the prefix is a genuine prefix of
+    // `rawText` and `slice` is exact. Trimming first would shift every offset by
+    // however much leading whitespace the draft happened to have.
+    const commandPos = findCommandPos(doc);
+    const commandSplit = commandPos === null
+        ? undefined
+        : (() => {
+            const before = doc.textBetween(0, commandPos, '\n', leafText);
+            return { before: before.trim(), after: rawText.slice(before.length).trim() };
+        })();
+    return {
+        // For a command draft the args are the two halves rejoined with ONE space,
+        // not `rawText`. Removing a chip from between two spaced words leaves both
+        // spaces behind, so `explain /webapp to me` serialized to `explain  to me`
+        // — a double space on the wire, and worse, a value that disagreed with the
+        // same function's own `commandSplit`. Two representations of one thing that
+        // do not match is how the next bug gets written; deriving one from the
+        // other makes them agree by construction. Non-command drafts keep
+        // `rawText` untouched — collapsing whitespace in ordinary prose is not
+        // this function's business.
+        text: commandSplit
+            ? [commandSplit.before, commandSplit.after].filter(Boolean).join(' ')
+            : rawText.trim(),
+        mentions: collectMentions(flat),
+        commandName: collectCommandName(flat),
+        commandSplit,
+    };
+}

package/dist/session/composer/editor/suggestion.d.ts

@@ -0,0 +1,87 @@
+import { Extension } from '@tiptap/core';
+import type { PluginKey } from '@tiptap/pm/state';
+import type { SuggestionKeyDownProps, SuggestionOptions, SuggestionProps } from '@tiptap/suggestion';
+/**
+ * The render-callback shape both the `@` mention menu and the `/` slash menu
+ * implement. This is the one `@tiptap/suggestion` code path both triggers go
+ * through — `createMentionSuggestion` (`../menus/mention-controller.ts`) and
+ * `createSlashSuggestion` (`../menus/slash-controller.ts`) each build a
+ * `MenuController` and hand it to `baseSuggestion` below.
+ *
+ * `onKeyDown` only receives `{view, event, range}` — NOT the full
+ * `SuggestionProps` (verified against the installed
+ * `@tiptap/suggestion@3.27.1`'s `plugin/props.ts`: the plugin's own
+ * `handleKeyDown` calls `renderer.onKeyDown({view, event, range})`, nothing
+ * richer). A controller therefore has to remember its own latest
+ * `SuggestionProps` (for `.command`, to actually run a selection from the
+ * keyboard) and its own latest flat row list (for what Enter/Tab should
+ * select, and for how far ↑/↓ may wrap) in plain closure state across calls —
+ * this is what keeps the selection index a DERIVED value instead of React
+ * state, per Task 6's `moveSelection`/`clampSelection` design: there is no
+ * React component above a controller for state to live in until the popup
+ * actually mounts, and even then the popup is fed `selectedIndex` as a prop,
+ * never owns it.
+ *
+ * Escape is not handled here on purpose: `@tiptap/suggestion`'s own
+ * `handleKeyDown` intercepts `Escape`/`Esc` before calling into a renderer at
+ * all, and unconditionally dispatches an exit transaction afterward (see
+ * `createSuggestionProps` in the installed package) — every keyboard-driven
+ * dismiss already reaches `onExit` without a controller doing anything.
+ */
+export interface MenuController<TSelected> {
+    onStart(props: SuggestionProps<never, TSelected>): void;
+    onUpdate(props: SuggestionProps<never, TSelected>): void;
+    onKeyDown(props: SuggestionKeyDownProps): boolean;
+    onExit(props: SuggestionProps<never, TSelected>): void;
+}
+/**
+ * `allowedPrefixes: [' ', '\n']` reproduces the old rule — a trigger only
+ * fires at the start of input or after whitespace, so `user@example.com` is
+ * not a mention — without the backwards character walk at
+ * session-chat-input.tsx:1011-1032.
+ *
+ * `startOfLine: false` is the fix for `/` being stuck at position 0. The old
+ * regex was `/^\/(\S*)$/`, which made a slash command after a newline
+ * impossible.
+ *
+ * `minQueryLength: Infinity` — neither menu uses the plugin's own
+ * `items()`/`loading` machinery at all (both `items: () => []` above and
+ * `command`/`onUpdate` computing rows themselves), but the plugin runs it
+ * regardless of what `items()` returns: with the default `minQueryLength: 0`,
+ * `exceedsMinQueryLength` is always true, so every keystroke transition takes
+ * the async-fetch branch and dispatches the renderer TWICE (`loading: true`,
+ * then `loading: false` once the — trivially resolved — promise settles),
+ * on top of the ONE dispatch `onStart` already gets for free. Verified line
+ * by line against the installed `@tiptap/suggestion@3.27.1`'s
+ * `dist/index.js` (compiled from `src/plugin/view.ts`):
+ * `dispatchStateUpdate("started", ...)` at line 588, the `if (!willFetch)`
+ * branch point at line 591, a duplicate `dispatchStateUpdate("updated", ...)`
+ * at line 597 (fired unconditionally before the fetch even starts), and a
+ * FINAL `dispatchStateUpdate("updated", ...)` at line 624 once the fetch
+ * settles — three renders for the opening keystroke, two for every keystroke
+ * after. `state.query.length >= Infinity` is never true, so
+ * `exceedsMinQueryLength` is always false, which takes the cheap synchronous
+ * branch (lines 592-593) and skips both extra dispatches — exactly one
+ * render per keystroke, matching how many times the query actually changed.
+ * `minQueryLength` is consumed only by `createSuggestionView`
+ * (`view.ts:124-127`) — it never reaches `createSuggestionState` (which owns
+ * `char`/`allowedPrefixes`/`startOfLine`/`findSuggestionMatch`, i.e. the
+ * trigger-matching this task exists to fix) or `createSuggestionProps`
+ * (which owns `handleKeyDown`/decorations), so this is scoped purely to the
+ * redundant fetch/render cycle and touches neither.
+ */
+export declare function baseSuggestion<TSelected>(char: string, pluginKey: PluginKey, controller: MenuController<TSelected>, 
+/**
+ * Where the plugin appends the menu element. Omitted (the default) means
+ * `document.body` — a floating menu anchored to the caret, which is what
+ * `@` wants. A CSS selector docks it into that element instead, which is
+ * what `/` wants; see `menus/mount.ts`'s `mountDockedMenu` for why the two
+ * triggers differ and why this is a selector rather than an element.
+ */
+container?: string): Omit<SuggestionOptions<never, TSelected>, 'editor'>;
+/**
+ * Wraps a fully-built `SuggestionOptions` (minus `editor`, which only exists
+ * once the extension is attached) as a standalone TipTap extension.
+ * `composer-editor.tsx` registers one of these per trigger char.
+ */
+export declare function createSuggestionExtension<TSelected>(name: string, options: Omit<SuggestionOptions<never, TSelected>, 'editor'>): Extension<any, any>;

package/dist/session/composer/editor/suggestion.js

@@ -0,0 +1,76 @@
+import { Extension } from '@tiptap/core';
+import Suggestion from '@tiptap/suggestion';
+/**
+ * `allowedPrefixes: [' ', '\n']` reproduces the old rule — a trigger only
+ * fires at the start of input or after whitespace, so `user@example.com` is
+ * not a mention — without the backwards character walk at
+ * session-chat-input.tsx:1011-1032.
+ *
+ * `startOfLine: false` is the fix for `/` being stuck at position 0. The old
+ * regex was `/^\/(\S*)$/`, which made a slash command after a newline
+ * impossible.
+ *
+ * `minQueryLength: Infinity` — neither menu uses the plugin's own
+ * `items()`/`loading` machinery at all (both `items: () => []` above and
+ * `command`/`onUpdate` computing rows themselves), but the plugin runs it
+ * regardless of what `items()` returns: with the default `minQueryLength: 0`,
+ * `exceedsMinQueryLength` is always true, so every keystroke transition takes
+ * the async-fetch branch and dispatches the renderer TWICE (`loading: true`,
+ * then `loading: false` once the — trivially resolved — promise settles),
+ * on top of the ONE dispatch `onStart` already gets for free. Verified line
+ * by line against the installed `@tiptap/suggestion@3.27.1`'s
+ * `dist/index.js` (compiled from `src/plugin/view.ts`):
+ * `dispatchStateUpdate("started", ...)` at line 588, the `if (!willFetch)`
+ * branch point at line 591, a duplicate `dispatchStateUpdate("updated", ...)`
+ * at line 597 (fired unconditionally before the fetch even starts), and a
+ * FINAL `dispatchStateUpdate("updated", ...)` at line 624 once the fetch
+ * settles — three renders for the opening keystroke, two for every keystroke
+ * after. `state.query.length >= Infinity` is never true, so
+ * `exceedsMinQueryLength` is always false, which takes the cheap synchronous
+ * branch (lines 592-593) and skips both extra dispatches — exactly one
+ * render per keystroke, matching how many times the query actually changed.
+ * `minQueryLength` is consumed only by `createSuggestionView`
+ * (`view.ts:124-127`) — it never reaches `createSuggestionState` (which owns
+ * `char`/`allowedPrefixes`/`startOfLine`/`findSuggestionMatch`, i.e. the
+ * trigger-matching this task exists to fix) or `createSuggestionProps`
+ * (which owns `handleKeyDown`/decorations), so this is scoped purely to the
+ * redundant fetch/render cycle and touches neither.
+ */
+export function baseSuggestion(char, pluginKey, controller, 
+/**
+ * Where the plugin appends the menu element. Omitted (the default) means
+ * `document.body` — a floating menu anchored to the caret, which is what
+ * `@` wants. A CSS selector docks it into that element instead, which is
+ * what `/` wants; see `menus/mount.ts`'s `mountDockedMenu` for why the two
+ * triggers differ and why this is a selector rather than an element.
+ */
+container) {
+    return {
+        char,
+        pluginKey,
+        startOfLine: false,
+        allowedPrefixes: [' ', '\n'],
+        items: () => [],
+        minQueryLength: Infinity,
+        container,
+        render: () => ({
+            onStart: (props) => controller.onStart(props),
+            onUpdate: (props) => controller.onUpdate(props),
+            onKeyDown: (props) => controller.onKeyDown(props),
+            onExit: (props) => controller.onExit(props),
+        }),
+    };
+}
+/**
+ * Wraps a fully-built `SuggestionOptions` (minus `editor`, which only exists
+ * once the extension is attached) as a standalone TipTap extension.
+ * `composer-editor.tsx` registers one of these per trigger char.
+ */
+export function createSuggestionExtension(name, options) {
+    return Extension.create({
+        name,
+        addProseMirrorPlugins() {
+            return [Suggestion({ editor: this.editor, ...options })];
+        },
+    });
+}

package/dist/session/composer/entitlements-pending.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Is an entitlement input still loading — asked in a way that cannot go stale.
+ *
+ * ## The incident this replaces
+ *
+ * Dev, 2026-09-17: a project MEMBER opened the composer model picker and got a
+ * spinner that never resolved, while the UI's own `/model-picker` calls had
+ * already returned HTTP 200 with a populated catalog. The models were in the
+ * browser; the gate never let them render.
+ *
+ * `useModelConnectionGate` used to answer this by restating every query's
+ * `enabled` condition inline:
+ *
+ *     const entitlementsPending =
+ *       (!!projectId && projectDetailQuery.isPending) ||
+ *       (!!projectId && llmGatewayEnabled && secretsQuery.isPending) ||
+ *       accountStatePending;
+ *
+ * It had to, because a DISABLED react-query never leaves `status: 'pending'` —
+ * with no fetch to settle it, `isPending` stays true forever. The restatement
+ * is the only thing standing between that and an indefinite spinner, and it is
+ * maintained by hand.
+ *
+ * It went stale the first time someone changed an `enabled` without changing
+ * its copy. `secretsQuery` gained `&& canReadSecrets`; this expression did not.
+ * `project.secret.read` is manager-tier, so for a member the query never ran,
+ * the middle clause was permanently true, and the picker spun for everyone
+ * below manager. The third clause never had a guard at all, and
+ * `useAccountState` disables itself whenever the billing-account context is
+ * unresolved.
+ *
+ * ## The rule
+ *
+ * Do not restate `enabled`. Ask what the query is actually DOING.
+ * `fetchStatus` is the enabled-aware half of react-query's state and answers
+ * directly: a query holds this gate only while it is genuinely fetching a first
+ * answer.
+ *
+ *   - `isPending` + `fetching` → loading. Hold.
+ *   - `isPending` + `idle`     → DISABLED. It is not coming. Release.
+ *   - `isPending` + `paused`   → offline. The catalog is already in the
+ *                                browser; a list beats an endless spinner.
+ *   - settled                  → release, including during a background
+ *                                refetch, which must not re-open the gate.
+ *
+ * That is exactly how query-core derives `isLoading`
+ * (`isPending && isFetching`, queryObserver.js:310 in v5.101.2). Spelled out
+ * here rather than read off `isLoading` so the disabled case is legible at the
+ * call site — it is the one that caused an incident — and so this stays
+ * provable in `apps/web`'s test harness, which cannot render the hook.
+ *
+ * Adding a fourth entitlement input now costs one array entry and carries no
+ * condition to keep in sync.
+ */
+/** The slice of a react-query result this rule reads. */
+export interface GateQuery {
+    isPending: boolean;
+    fetchStatus: 'fetching' | 'paused' | 'idle';
+}
+export declare function resolveEntitlementsPending(queries: readonly GateQuery[]): boolean;