lumiverse-spindle-types 0.5.11 → 0.5.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lumiverse-spindle-types",
-  "version": "0.5.11",
+  "version": "0.5.13",
   "types": "./src/index.ts",
   "keywords": [
     "lumiverse",

package/src/dom.ts

@@ -1,11 +1,48 @@
 import type { RequestInitDTO } from "./api";
 import type { SpindleComponentsHelper } from "./components";
 
+/** A chat-message DOM element paired with its stable message id. */
+export interface SpindleMessageElement {
+  /** Stable message id (matches the message's id in the host's data store). */
+  messageId: string;
+  /** Currently-mounted bubble root element for that message. */
+  element: Element;
+}
+
 /** DOM helper API provided to frontend extension modules. */
 export interface SpindleDOMHelper {
-  /** Inject sanitized HTML into the host document at the given target. */
+  /**
+   * Inject sanitized HTML into the host document at the given target and
+   * return the wrapper element containing the parsed content.
+   *
+   * **Element identity is preserved across chat-list virtualization.**
+   * When the injection lands inside a chat-message bubble, the host
+   * registers the wrapper and *moves* (not recreates) it back into place
+   * when the bubble next mounts. That means form-control state, event
+   * listeners bound to the wrapper subtree, and any refs the extension is
+   * holding all survive scroll-away/scroll-back cycles. Extensions can
+   * cache the returned Element and trust it indefinitely until they
+   * explicitly retire it via `uninject()` or `cleanup()`.
+   *
+   * To deliberately remove an injection, call `uninject(wrapper)` — NOT
+   * `wrapper.remove()`. The latter detaches the wrapper but leaves the
+   * registry record in place, so the host will resurrect the wrapper on
+   * the next bubble remount.
+   *
+   * Injections outside any chat-message bubble (sidebar, modals, toolbar)
+   * are unaffected by virtualization and don't go through replay — they
+   * stay attached wherever the extension put them.
+   */
   inject(target: string | Element, html: string, position?: InsertPosition): Element;
 
+  /**
+   * Retire an injection previously returned by `inject()`. Removes the
+   * wrapper from the DOM and drops its replay registration so the host
+   * won't restore it on future bubble remounts. No-op if the element
+   * isn't a recognised Spindle injection wrapper.
+   */
+  uninject(element: Element): void;
+
   /** Create a style element in the host document. Returns a removal function. */
   addStyle(css: string): () => void;
 
@@ -24,6 +61,52 @@ export interface SpindleDOMHelper {
   /** Query all matches inside the extension-owned host DOM. */
   queryAll(selector: string): Element[];
 
+  /**
+   * Resolve the chat message that contains the given DOM element. Walks
+   * up the DOM tree from `target` looking for the host's message-bubble
+   * anchor and returns the stable message id of the containing message,
+   * or `null` when `target` isn't inside any chat message (e.g. it's in
+   * the sidebar, a modal, or a floating widget).
+   *
+   * Prefer this over reading host-private DOM attributes directly — the
+   * underlying attribute name is an implementation detail of the host
+   * and may change; this method is the stable public contract.
+   *
+   * Typical use: an extension injects content into a message bubble and
+   * needs the stable id to persist per-message state, key event
+   * handlers on the message id, or call `ctx.messages.renderWidget()`
+   * with the right id.
+   */
+  getMessageId(target: Element): string | null;
+
+  /**
+   * Find the chat-message bubble element currently mounted in the DOM
+   * for the given stable message id. Returns `null` when the message
+   * isn't currently rendered — the chat message list is virtualized, so
+   * only bubbles near the viewport (plus a small overscan window) have
+   * DOM at any moment.
+   *
+   * Typical use: extension wants to attach content to a specific known
+   * message id. If `null` comes back, the bubble isn't currently
+   * mounted. Injections previously made via `dom.inject()` against a
+   * bubble element are auto-replayed by the host (with the original
+   * Element identity preserved — see `inject()` for the full contract)
+   * when that bubble next mounts, so extensions don't need to re-inject
+   * on scroll themselves.
+   */
+  findMessageElement(messageId: string): Element | null;
+
+  /**
+   * Enumerate every chat message bubble currently mounted in the DOM,
+   * paired with its stable message id. The returned list reflects only
+   * what the virtualizer has rendered (typically the viewport plus a
+   * small overscan window), so it changes as the user scrolls.
+   *
+   * Typical use: extension sweeps every visible message on setup or in
+   * response to a chat-changed event to apply per-message decoration.
+   */
+  listMessageElements(): SpindleMessageElement[];
+
   /** Remove all DOM created by the extension helper. */
   cleanup(): void;
 }
@@ -652,6 +735,38 @@ export interface SpindleFrontendContext {
     ): () => void;
     /** Remove a previously rendered message widget. */
     removeWidget(messageId: string, widgetId: string): void;
+    /**
+     * Get the latest (most recent) message id in the active chat, or
+     * `null` if the chat is empty / no chat is active. Reflects the
+     * full chat history — works even when the latest bubble is
+     * currently scrolled off-screen (the chat list is virtualized, so
+     * the DOM might not contain the bubble even though the message
+     * exists logically).
+     *
+     * Typical use: extensions that decorate or react to the most recent
+     * message (trackers, summarizers, "show last response details"
+     * widgets) call this on setup + on each new-message event to find
+     * the id they should target, then pair with `dom.findMessageElement`
+     * or `dom.inject()` to attach DOM content. Injections registered
+     * via `dom.inject()` auto-replay when the bubble next mounts so the
+     * extension doesn't have to re-attach on scroll itself.
+     */
+    getLatestMessageId(): string | null;
+    /**
+     * Get the message id at the given chronological index in the
+     * active chat (0 = oldest, length-1 = newest). Negative indices
+     * count from the end Python-style: -1 = latest, -2 = second-
+     * latest. Returns `null` if the index is out of range or no chat
+     * is active.
+     */
+    getMessageIdAtIndex(index: number): string | null;
+    /**
+     * Enumerate every message id in the active chat in chronological
+     * order (oldest first, newest last). Reflects the full chat
+     * history, not just messages currently mounted in the DOM. See
+     * `dom.listMessageElements()` for the mounted-only DOM view.
+     */
+    listMessageIds(): string[];
   };
   characters: {
     /** Read a character through the host app's authenticated API. */