lumiverse-spindle-types 0.5.11 → 0.5.12

package/package.json

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

package/src/dom.ts

@@ -1,6 +1,14 @@
 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. */
@@ -24,6 +32,50 @@ 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 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 +704,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. */