@sigx/lynx-markdown 0.4.7 → 0.4.9

package/dist/editor/plugin.d.ts

@@ -0,0 +1,118 @@
+/**
+ * The `MarkdownEditor` plugin contract — the P3 pluggability layer. Another
+ * project adds e.g. mention support without touching this package:
+ *
+ * - `inline` teaches the **parser** the syntax (a {@link ParserInlineExtension}),
+ *   the **editor field** how to model it (`docMapping`: AST node → editor span)
+ *   and how to write it back out (`serialize`: span → markdown), and optionally
+ *   the **preview** how to render it (`component`).
+ * - `trigger` opens a suggestion session on a trigger char (`@`, `:`), feeds it
+ *   query results, and inserts the selection.
+ * - `toolbar` contributes {@link ToolbarItem}s to the built-in toolbar.
+ *
+ * Every part is optional and independent — a plugin can be toolbar-only, or
+ * trigger-only (e.g. a slash-command menu that inserts plain markdown).
+ */
+import type { JSXElement } from '@sigx/lynx';
+import type { InlineSpan } from '@sigx/lynx-richtext';
+import type { InlineExtension } from '../ast.js';
+import type { ParserInlineExtension } from '../parser/extensions.js';
+import type { ExtensionProps, MarkdownChild } from '../render/components.js';
+import type { ToolbarItem } from './toolbar/items.js';
+import type { MarkdownEditorController } from './MarkdownEditor.js';
+export interface MarkdownEditorPlugin {
+    /** Stable plugin name (diagnostics; trigger sessions report it). */
+    name: string;
+    inline?: InlinePluginSpec;
+    trigger?: TriggerSpec;
+    /** Extra toolbar items, appended after the editor's base item set. */
+    toolbar?: ToolbarItem[];
+}
+export interface InlinePluginSpec {
+    /** The parser extension that recognizes this construct in markdown source. */
+    syntax: ParserInlineExtension;
+    /**
+     * Preview renderer (the `components.extension[syntax.name]` slot). Optional —
+     * without it, `MarkdownView` falls back to the node's `raw` source as text.
+     */
+    component?: (props: ExtensionProps) => MarkdownChild;
+    /**
+     * doc → markdown: serialize one plugin-owned span back to markdown source.
+     * Receives the span and the text it covers in the editor field. Emitted
+     * atomically in place of the covered text (e.g. a mention span covering
+     * `Andy` serializes to `@[Andy](u1)`).
+     */
+    serialize(span: InlineSpan, text: string): string;
+    /** The AST ↔ editor-span bridge for the editable field. */
+    docMapping: {
+        /**
+         * The span type this plugin owns in the editor document. Must be one of
+         * the codec-allowed {@link InlineSpan} types (`mention` is reserved for
+         * exactly this) — unknown types are dropped by the native codec.
+         */
+        spanType: InlineSpan['type'];
+        /**
+         * markdown → doc: map a parsed extension node to the text the field
+         * should display plus the span carrying its data. Return `null` to keep
+         * the surrounding block as a raw (source-edited) block instead.
+         */
+        toSpan(node: InlineExtension): {
+            text: string;
+            span: Omit<InlineSpan, 'start' | 'end'>;
+        } | null;
+    };
+}
+/** One entry in a trigger session's result list. */
+export interface TriggerItem {
+    id: string;
+    label: string;
+    [key: string]: unknown;
+}
+interface TriggerSpecBase {
+    /** Debounce between `onQuery` calls in ms. `0`/omitted = immediate. */
+    debounce?: number;
+    /**
+     * Resolve suggestions for the current query (the text typed after the
+     * trigger). May be async — stale results (a newer query has since been
+     * issued, or the session closed) are discarded.
+     */
+    onQuery(query: string): TriggerItem[] | Promise<TriggerItem[]>;
+    /** Re-skin a suggestion row (the popup's neutral default renders `label`). */
+    renderItem?(item: TriggerItem, active: boolean): JSXElement;
+    /** A suggestion was picked. Typically calls `api.replaceQuery(...)`. */
+    onSelect(item: TriggerItem, api: TriggerSelectApi): void;
+}
+/** Exactly one of `char`/`pattern` — enforced by the union. */
+export type TriggerSpec = (TriggerSpecBase & {
+    /** Single trigger character (`'@'`). */
+    char: string;
+    pattern?: undefined;
+}) | (TriggerSpecBase & {
+    char?: undefined;
+    /**
+     * Multi-char trigger: matched against the run of non-whitespace text
+     * between the last boundary and the caret; must match at its start
+     * (e.g. `/^::/`). The match length is the trigger length; what
+     * follows is the query.
+     */
+    pattern: RegExp;
+});
+/** What `onSelect` receives to act on the editor. */
+export interface TriggerSelectApi {
+    /**
+     * Replace the whole trigger run (trigger char/prefix + query) with `text`,
+     * leaving the caret after it.
+     *
+     * Sessions are re-derived from `(doc.text, caret)`, so end the replacement
+     * with a boundary (usually a trailing space) — otherwise text that still
+     * forms a trigger run at the caret immediately re-opens the session.
+     */
+    replaceQuery(text: string): void;
+    /** The `[start, end)` range of the trigger run in the document text. */
+    range: {
+        start: number;
+        end: number;
+    };
+    controller: MarkdownEditorController;
+}
+export {};

package/dist/editor/plugin.js

@@ -0,0 +1,16 @@
+/**
+ * The `MarkdownEditor` plugin contract — the P3 pluggability layer. Another
+ * project adds e.g. mention support without touching this package:
+ *
+ * - `inline` teaches the **parser** the syntax (a {@link ParserInlineExtension}),
+ *   the **editor field** how to model it (`docMapping`: AST node → editor span)
+ *   and how to write it back out (`serialize`: span → markdown), and optionally
+ *   the **preview** how to render it (`component`).
+ * - `trigger` opens a suggestion session on a trigger char (`@`, `:`), feeds it
+ *   query results, and inserts the selection.
+ * - `toolbar` contributes {@link ToolbarItem}s to the built-in toolbar.
+ *
+ * Every part is optional and independent — a plugin can be toolbar-only, or
+ * trigger-only (e.g. a slash-command menu that inserts plain markdown).
+ */
+export {};

package/dist/editor/toolbar/Toolbar.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `<EditorToolbar>` — the neutral formatting toolbar for `MarkdownEditor`,
+ * mirroring the renderer's override pattern: the *items* are data
+ * ({@link ToolbarItem}), the *rendering* is replaceable per item via
+ * `renderItem` (that's all a design-system skin is — see
+ * `@sigx/lynx-daisyui`'s `EditorToolbar`).
+ *
+ * Ships with `ignore-focus` on the root: toolbar taps must never blur the
+ * editor — on iOS, Lynx dispatches `endEditing:` on any touch-down whose
+ * target doesn't ignore focus, folding the keyboard before the tapped
+ * command could run.
+ *
+ * Usable two ways:
+ * - **Built in**: `<MarkdownEditor toolbar />` (or `toolbar="top"`), which
+ *   wires `controller`/`selection` internally.
+ * - **Standalone**: place it anywhere (e.g. a `KeyboardStickyView` send bar)
+ *   and pass `controller` + `selection` yourself.
+ */
+import { type Define, type JSXElement } from '@sigx/lynx';
+import type { SelectionState } from '@sigx/lynx-richtext';
+import type { MarkdownEditorController } from '../MarkdownEditor.js';
+import type { ToolbarItem } from './items.js';
+export type ToolbarRenderItem = (item: ToolbarItem, active: boolean, run: () => void) => JSXElement;
+export type EditorToolbarProps = Define.Prop<'controller', MarkdownEditorController | null, false> & Define.Prop<'selection', SelectionState | null, false> & Define.Prop<'items', ToolbarItem[], false> & Define.Prop<'renderItem', ToolbarRenderItem, false> & Define.Prop<'class', string, false>;
+export declare const EditorToolbar: import("@sigx/runtime-core").ComponentFactory<EditorToolbarProps, void, {}>;

package/dist/editor/toolbar/Toolbar.js

@@ -0,0 +1,51 @@
+import { jsx as _jsx } from "@sigx/lynx/jsx-runtime";
+/**
+ * `<EditorToolbar>` — the neutral formatting toolbar for `MarkdownEditor`,
+ * mirroring the renderer's override pattern: the *items* are data
+ * ({@link ToolbarItem}), the *rendering* is replaceable per item via
+ * `renderItem` (that's all a design-system skin is — see
+ * `@sigx/lynx-daisyui`'s `EditorToolbar`).
+ *
+ * Ships with `ignore-focus` on the root: toolbar taps must never blur the
+ * editor — on iOS, Lynx dispatches `endEditing:` on any touch-down whose
+ * target doesn't ignore focus, folding the keyboard before the tapped
+ * command could run.
+ *
+ * Usable two ways:
+ * - **Built in**: `<MarkdownEditor toolbar />` (or `toolbar="top"`), which
+ *   wires `controller`/`selection` internally.
+ * - **Standalone**: place it anywhere (e.g. a `KeyboardStickyView` send bar)
+ *   and pass `controller` + `selection` yourself.
+ */
+import { component } from '@sigx/lynx';
+import { defaultToolbarItems } from './items.js';
+/** Neutral, theme-agnostic item chrome (mid-gray works on light + dark). */
+const ITEM_STYLE = {
+    paddingLeft: '10px',
+    paddingRight: '10px',
+    paddingTop: '6px',
+    paddingBottom: '6px',
+    borderRadius: '6px',
+};
+const ACTIVE_BG = 'rgba(128,128,128,0.25)';
+export const EditorToolbar = component(({ props }) => {
+    const run = (item) => {
+        const controller = props.controller;
+        if (controller)
+            item.run({ controller });
+    };
+    const defaultRenderItem = (item, active, runItem) => (_jsx("view", { style: { ...ITEM_STYLE, ...(active ? { backgroundColor: ACTIVE_BG } : {}) }, bindtap: runItem, "accessibility-element": true, "accessibility-label": item.label ?? item.id, "accessibility-trait": "button", "accessibility-status": active ? 'selected' : undefined, children: _jsx("text", { style: active ? { fontWeight: 'bold' } : undefined, children: item.label ?? item.id }) }, item.id));
+    return () => {
+        const items = props.items ?? defaultToolbarItems;
+        const sel = props.selection ?? null;
+        const renderItem = props.renderItem ?? defaultRenderItem;
+        return (_jsx("view", { "ignore-focus": true, class: props.class, style: {
+                display: 'flex',
+                flexDirection: 'row',
+                flexWrap: 'wrap',
+                alignItems: 'center',
+                columnGap: '4px',
+                rowGap: '4px',
+            }, children: items.map((item) => renderItem(item, item.isActive?.(sel) ?? false, () => run(item))) }));
+    };
+});

package/dist/editor/toolbar/items.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The toolbar item contract — the editor analogue of the renderer's
+ * `MarkdownComponents` map. A toolbar is just an array of these; design
+ * systems re-skin the *rendering* (see `@sigx/lynx-daisyui`'s
+ * `EditorToolbar`) while the items stay shared, and P3 plugins contribute
+ * additional items through the same shape.
+ */
+import type { SelectionState } from '@sigx/lynx-richtext';
+import type { MarkdownEditorController } from '../MarkdownEditor.js';
+/** What an item's `run` receives — the editor's imperative surface. */
+export interface ToolbarContext {
+    controller: MarkdownEditorController;
+}
+export interface ToolbarItem {
+    /** Stable identifier (also the default `key`). */
+    id: string;
+    /**
+     * Short text rendering (`B`, `H1`, …). The neutral toolbar renders this
+     * (falling back to `id` when omitted); skins may render `icon` instead.
+     * Optional so icon-only items/skins don't need a dummy label.
+     */
+    label?: string;
+    /** Optional icon hint for skins (e.g. an icon-set name). Never required. */
+    icon?: string;
+    /** Items with the same group render adjacent (skins may add separators). */
+    group?: string;
+    /** Highlighted state, derived from the last selection event. */
+    isActive?(sel: SelectionState | null): boolean;
+    run(ctx: ToolbarContext): void;
+}
+/**
+ * The neutral default item set: every command the v1 controller exposes.
+ * (Lists / quote / link items arrive with the block-WYSIWYG work — #153.)
+ */
+export declare const defaultToolbarItems: ToolbarItem[];

package/dist/editor/toolbar/items.js

@@ -0,0 +1,29 @@
+/**
+ * The toolbar item contract — the editor analogue of the renderer's
+ * `MarkdownComponents` map. A toolbar is just an array of these; design
+ * systems re-skin the *rendering* (see `@sigx/lynx-daisyui`'s
+ * `EditorToolbar`) while the items stay shared, and P3 plugins contribute
+ * additional items through the same shape.
+ */
+const formatActive = (format) => (sel) => !!sel && sel.activeFormats.includes(format);
+const headingActive = (level) => (sel) => sel?.activeBlock === 'heading' && sel.headingLevel === level;
+/**
+ * The neutral default item set: every command the v1 controller exposes.
+ * (Lists / quote / link items arrive with the block-WYSIWYG work — #153.)
+ */
+export const defaultToolbarItems = [
+    { id: 'bold', label: 'B', icon: 'bold', group: 'inline', isActive: formatActive('bold'), run: ({ controller }) => controller.toggleBold() },
+    { id: 'italic', label: 'I', icon: 'italic', group: 'inline', isActive: formatActive('italic'), run: ({ controller }) => controller.toggleItalic() },
+    { id: 'strike', label: 'S', icon: 'strikethrough', group: 'inline', isActive: formatActive('strike'), run: ({ controller }) => controller.toggleStrike() },
+    { id: 'code', label: '</>', icon: 'code', group: 'inline', isActive: formatActive('code'), run: ({ controller }) => controller.toggleCode() },
+    { id: 'h1', label: 'H1', icon: 'heading-1', group: 'block', isActive: headingActive(1), run: ({ controller }) => controller.setHeading(1) },
+    { id: 'h2', label: 'H2', icon: 'heading-2', group: 'block', isActive: headingActive(2), run: ({ controller }) => controller.setHeading(2) },
+    {
+        id: 'paragraph',
+        label: '¶',
+        icon: 'pilcrow',
+        group: 'block',
+        isActive: (sel) => (sel ? sel.activeBlock === 'paragraph' : false),
+        run: ({ controller }) => controller.setHeading(0),
+    },
+];

package/dist/editor/trigger/SuggestionPopup.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `<SuggestionPopup>` — the neutral suggestion list for trigger sessions,
+ * mirroring the toolbar's override pattern: items are data
+ * ({@link TriggerItem}), row rendering is replaceable via `renderItem`
+ * (a plugin's `trigger.renderItem`).
+ *
+ * Anchored by the caret rect from `bindselection`, placed above the caret by
+ * default and flipped below when there's no room, and clamped so it never
+ * extends under the keyboard — see `position.ts` for the math. The keyboard
+ * inset comes from `@sigx/lynx-keyboard`'s `useKeyboard()`, which requires a
+ * `<SafeAreaProvider>` ancestor; without one it reads 0 and the keyboard
+ * clamp is effectively disabled. The page-absolute frame of the relative
+ * container it's positioned in arrives via `containerFrame` (the editor
+ * measures it with `bindlayoutchange`).
+ *
+ * Ships with `ignore-focus` on the root: tapping a suggestion must never
+ * blur the editor (same iOS `endEditing:` rule the toolbar handles).
+ */
+import { type Define, type ElementLayout, type JSXElement } from '@sigx/lynx';
+import type { TriggerItem } from '../plugin.js';
+import { type CaretRect } from './position.js';
+export type SuggestionRenderItem = (item: TriggerItem, active: boolean) => JSXElement;
+export type SuggestionPopupProps = Define.Prop<'items', TriggerItem[], false> & Define.Prop<'caretRect', CaretRect | null, false>
+/** Page-absolute frame of the relative container (from `bindlayoutchange`). */
+ & Define.Prop<'containerFrame', ElementLayout | null, false> & Define.Prop<'renderItem', SuggestionRenderItem, false> & Define.Prop<'onSelect', (item: TriggerItem) => void, false>
+/** Highlighted row index (e.g. hardware-keyboard navigation); `-1`/omitted = none. */
+ & Define.Prop<'activeIndex', number, false> & Define.Prop<'maxHeight', number, false> & Define.Prop<'width', number, false> & Define.Prop<'class', string, false>;
+export declare const SuggestionPopup: import("@sigx/runtime-core").ComponentFactory<SuggestionPopupProps, void, {}>;

package/dist/editor/trigger/SuggestionPopup.js

@@ -0,0 +1,77 @@
+import { jsx as _jsx } from "@sigx/lynx/jsx-runtime";
+/**
+ * `<SuggestionPopup>` — the neutral suggestion list for trigger sessions,
+ * mirroring the toolbar's override pattern: items are data
+ * ({@link TriggerItem}), row rendering is replaceable via `renderItem`
+ * (a plugin's `trigger.renderItem`).
+ *
+ * Anchored by the caret rect from `bindselection`, placed above the caret by
+ * default and flipped below when there's no room, and clamped so it never
+ * extends under the keyboard — see `position.ts` for the math. The keyboard
+ * inset comes from `@sigx/lynx-keyboard`'s `useKeyboard()`, which requires a
+ * `<SafeAreaProvider>` ancestor; without one it reads 0 and the keyboard
+ * clamp is effectively disabled. The page-absolute frame of the relative
+ * container it's positioned in arrives via `containerFrame` (the editor
+ * measures it with `bindlayoutchange`).
+ *
+ * Ships with `ignore-focus` on the root: tapping a suggestion must never
+ * blur the editor (same iOS `endEditing:` rule the toolbar handles).
+ */
+import { component } from '@sigx/lynx';
+import { useKeyboard } from '@sigx/lynx-keyboard';
+import { placeSuggestionPopup, screenHeightDp } from './position.js';
+const DEFAULT_WIDTH = 240;
+const DEFAULT_MAX_HEIGHT = 220;
+const BORDER = 'rgba(127, 127, 127, 0.32)';
+/** Opaque neutral surface — the popup floats over editor text. */
+const SURFACE = '#f4f4f5';
+const ACTIVE_BG = 'rgba(128,128,128,0.25)';
+export const SuggestionPopup = component(({ props }) => {
+    const keyboard = useKeyboard();
+    const defaultRenderItem = (item, active) => (_jsx("view", { style: {
+            paddingLeft: '12px',
+            paddingRight: '12px',
+            paddingTop: '8px',
+            paddingBottom: '8px',
+            ...(active ? { backgroundColor: ACTIVE_BG } : {}),
+        }, children: _jsx("text", { style: { fontSize: 15 }, children: item.label }) }));
+    return () => {
+        const items = props.items ?? [];
+        const caretRect = props.caretRect ?? null;
+        const frame = props.containerFrame ?? null;
+        // Both anchors are required for meaningful placement — render nothing
+        // until they exist rather than flashing at a bogus top-left position.
+        if (!caretRect || !frame)
+            return null;
+        // Clamp to the container so the popup can never overflow to the right
+        // in narrow layouts (placement clamps left to 0).
+        const width = Math.min(props.width ?? DEFAULT_WIDTH, frame.width);
+        const renderItem = props.renderItem ?? defaultRenderItem;
+        const pos = placeSuggestionPopup({
+            caretRect,
+            containerTop: frame.top,
+            containerWidth: frame.width,
+            containerHeight: frame.height,
+            screenHeight: screenHeightDp(),
+            keyboardHeight: keyboard.value.height,
+            popupWidth: width,
+            maxPopupHeight: props.maxHeight ?? DEFAULT_MAX_HEIGHT,
+        });
+        return (_jsx("view", { "ignore-focus": true, class: props.class, style: {
+                position: 'absolute',
+                left: pos.left,
+                ...(pos.top !== undefined ? { top: pos.top } : {}),
+                ...(pos.bottom !== undefined ? { bottom: pos.bottom } : {}),
+                width,
+                zIndex: 20,
+                borderRadius: '10px',
+                borderWidth: '1px',
+                borderColor: BORDER,
+                backgroundColor: SURFACE,
+                overflow: 'hidden',
+            }, children: _jsx("scroll-view", { "scroll-orientation": "vertical", style: { maxHeight: pos.maxHeight }, children: items.map((item, index) => {
+                    const active = index === (props.activeIndex ?? -1);
+                    return (_jsx("view", { bindtap: () => props.onSelect?.(item), "accessibility-element": true, "accessibility-label": item.label, "accessibility-trait": "button", "accessibility-status": active ? 'selected' : undefined, children: renderItem(item, active) }, item.id));
+                }) }) }));
+    };
+});

package/dist/editor/trigger/position.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Pure placement math for the suggestion popup.
+ *
+ * Inputs are deliberately primitive so this is unit-testable without a
+ * renderer: the element-local caret rect (from `bindselection`), the
+ * positioning container's page-absolute frame (from `bindlayoutchange`),
+ * the screen height and the keyboard height (`@sigx/lynx-keyboard`).
+ *
+ * Placement: **above the caret by default** — the editor usually sits in a
+ * bottom-docked composer, so above is where the room is — flipping below
+ * when there isn't enough space above. Either way the popup is clamped so it
+ * never extends under the keyboard, and the list scrolls internally when the
+ * clamp bites.
+ */
+export interface CaretRect {
+    x: number;
+    y: number;
+    height: number;
+}
+/** Absolute-position style for the popup within its relative container. */
+export interface PopupPlacement {
+    placement: 'above' | 'below';
+    left: number;
+    /** Set for `below`: container-local top edge. */
+    top?: number;
+    /** Set for `above`: container-local bottom anchor (no height knowledge needed). */
+    bottom?: number;
+    /** Clamp for the scrollable list. */
+    maxHeight: number;
+}
+export declare function placeSuggestionPopup(opts: {
+    caretRect: CaretRect;
+    /** Page-absolute top of the positioning container (0 until measured). */
+    containerTop: number;
+    containerWidth: number;
+    containerHeight: number;
+    screenHeight: number;
+    keyboardHeight: number;
+    popupWidth: number;
+    maxPopupHeight: number;
+}): PopupPlacement;
+/**
+ * Logical screen height in dp from `lynx.SystemInfo` (same pattern as
+ * `@sigx/lynx-navigation`'s screen-width module). Falls back to a typical
+ * phone height in tests / non-Lynx hosts.
+ */
+export declare function screenHeightDp(fallback?: number): number;

package/dist/editor/trigger/position.js

@@ -0,0 +1,62 @@
+/**
+ * Pure placement math for the suggestion popup.
+ *
+ * Inputs are deliberately primitive so this is unit-testable without a
+ * renderer: the element-local caret rect (from `bindselection`), the
+ * positioning container's page-absolute frame (from `bindlayoutchange`),
+ * the screen height and the keyboard height (`@sigx/lynx-keyboard`).
+ *
+ * Placement: **above the caret by default** — the editor usually sits in a
+ * bottom-docked composer, so above is where the room is — flipping below
+ * when there isn't enough space above. Either way the popup is clamped so it
+ * never extends under the keyboard, and the list scrolls internally when the
+ * clamp bites.
+ */
+const GAP = 4;
+/** Roughly one suggestion row — below this, flip rather than squeeze. */
+const MIN_USEFUL_HEIGHT = 44;
+export function placeSuggestionPopup(opts) {
+    const caretTopAbs = opts.containerTop + opts.caretRect.y;
+    const caretBottomAbs = caretTopAbs + opts.caretRect.height;
+    const keyboardTop = opts.screenHeight - opts.keyboardHeight;
+    const spaceAbove = caretTopAbs - GAP;
+    const spaceBelow = keyboardTop - caretBottomAbs - GAP;
+    const fitsAbove = spaceAbove >= Math.min(opts.maxPopupHeight, MIN_USEFUL_HEIGHT);
+    const placement = fitsAbove || spaceAbove >= spaceBelow ? 'above' : 'below';
+    const left = Math.max(0, Math.min(opts.caretRect.x, opts.containerWidth - opts.popupWidth));
+    // Never exceed the actual available space — the clamp guarantee wins over
+    // a comfortable minimum height (the list scrolls inside whatever fits).
+    if (placement === 'above') {
+        return {
+            placement,
+            left,
+            bottom: opts.containerHeight - opts.caretRect.y + GAP,
+            maxHeight: Math.max(0, Math.min(opts.maxPopupHeight, spaceAbove)),
+        };
+    }
+    return {
+        placement,
+        left,
+        top: opts.caretRect.y + opts.caretRect.height + GAP,
+        maxHeight: Math.max(0, Math.min(opts.maxPopupHeight, spaceBelow)),
+    };
+}
+/**
+ * Logical screen height in dp from `lynx.SystemInfo` (same pattern as
+ * `@sigx/lynx-navigation`'s screen-width module). Falls back to a typical
+ * phone height in tests / non-Lynx hosts.
+ */
+export function screenHeightDp(fallback = 800) {
+    try {
+        const info = typeof lynx !== 'undefined' ? lynx?.SystemInfo : undefined;
+        const px = info?.pixelHeight;
+        const pr = info?.pixelRatio || 1;
+        if (typeof px === 'number' && px > 0) {
+            return Math.round(px / pr);
+        }
+    }
+    catch {
+        // Lynx globals not present (test env / SSR) — use fallback.
+    }
+    return fallback;
+}

package/dist/editor/trigger/session.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Trigger sessions — the state machine behind the suggestion popup.
+ *
+ * The element exposes no keystrokes, so the session is a pure function of the
+ * editor's two event streams: document text (`bindchange`) and the collapsed
+ * caret offset (`bindselection`). On every sync we look at the **run** — the
+ * non-whitespace text between the last boundary and the caret. A run starting
+ * with a trigger (`@` / a pattern match) means an active session whose query
+ * is the rest of the run; anything else means no session. Whitespace, caret
+ * exits, blur and selection all close it for free, because they all change
+ * the run.
+ *
+ * `onQuery` may be async: results are tagged with an epoch and discarded when
+ * a newer query (or a close) supersedes them. An optional per-trigger
+ * `debounce` batches fast typing.
+ */
+import type { TriggerItem, TriggerSpec } from '../plugin.js';
+export interface TriggerSession {
+    /** Owning plugin's name. */
+    plugin: string;
+    /** Offset of the trigger char (run start) in the document text. */
+    anchor: number;
+    /** Text typed after the trigger prefix. */
+    query: string;
+    /** Caret offset (exclusive end of the run). */
+    caret: number;
+    /** Latest resolved suggestions ([] while loading or empty). */
+    items: TriggerItem[];
+    /** True while an async `onQuery` for the current query is in flight. */
+    loading: boolean;
+}
+export interface TriggerSessionManager {
+    /** Feed the latest document text (from `bindchange`). */
+    syncText(text: string): void;
+    /** Feed the collapsed caret offset (from `bindselection`); `-1` = no collapsed caret. */
+    syncCaret(caret: number): void;
+    /** Close the active session (blur, selection made, escape). */
+    close(): void;
+    readonly session: TriggerSession | null;
+}
+export interface TriggerSessionManagerOptions {
+    triggers: ReadonlyArray<{
+        plugin: string;
+        spec: TriggerSpec;
+    }>;
+    /** Fired whenever the session opens, updates (query/items), or closes. */
+    onUpdate(session: TriggerSession | null): void;
+}
+export declare function createTriggerSessionManager(opts: TriggerSessionManagerOptions): TriggerSessionManager;