@runtypelabs/persona 4.7.0 → 4.9.0

package/dist/context-mentions-inline.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Pure `@`-trigger detection for the composer mention menu.
+ *
+ * No DOM, no contenteditable — a small function over `(value, caret)` mirroring
+ * the Slack/Discord approach. Shared by the core orchestrator's lightweight
+ * "should I open?" pre-check and the lazy-loaded controller's full parse, so the
+ * trigger rule lives in exactly one place.
+ */
+type MentionTriggerMatch = {
+    /** Index of the trigger character in `value`. */
+    triggerIndex: number;
+    /** The text typed after the trigger, up to the caret (no leading trigger). */
+    query: string;
+};
+
+/**
+ * Capability object handed to a `command:"action"` handler. The widget exposes
+ * only composer-local operations; broader actions (clear the transcript, change
+ * theme) are wired by the host via closures over its own controller.
+ */
+type AgentWidgetContextMentionComposerCapability = {
+    /** Current composer text. */
+    getValue: () => string;
+    /** Replace composer text (fires `input`, moves caret to end, refocuses). */
+    setValue: (value: string) => void;
+    /** Submit the composer (same path as pressing send). */
+    submit: () => void;
+};
+/** Reference stored on a sent message for transcript fidelity + chip rendering. */
+type AgentWidgetContextMentionRef = {
+    sourceId: string;
+    itemId: string;
+    label: string;
+    iconName?: string;
+    /** Accent color for the inline token (see `AgentWidgetContextMentionItem.color`). */
+    color?: string;
+};
+
+/**
+ * Pure, DOM-free document model for the inline-mention composer
+ * (`contextMentions.display: "inline"`).
+ *
+ * The canonical composer state is a flat, ordered list of blocks — text runs and
+ * atomic mention tokens — rather than a single string with range markers. Blocks
+ * make insert/remove, duplicate detection, and history round-trip explicit
+ * without parsing HTML. The DOM adapter (`composer-contenteditable.ts`) renders a
+ * document to a contenteditable surface and re-parses it back on input; this
+ * module owns everything that does not touch the DOM, so it is unit-testable in
+ * the Node env exactly like `mention-trigger.ts` and `composer-history.ts`.
+ *
+ * Two text projections exist, each for a distinct purpose:
+ *  - `toDisplayText` — text + `@label` per mention (the human-readable, sent
+ *                      bubble / model-visible prose).
+ *  - `toLogicalText` — text + `` (OBJECT REPLACEMENT CHAR) per mention. An
+ *                      INTERNAL index space only — never shown to the user, never
+ *                      sent to the model — that lets the existing
+ *                      `parseMentionTrigger` run over `(logicalText, caret)` with
+ *                      tokens standing in as single, query-terminating chars.
+ */
+
+/** Stable id for one inline mention instance (DOM `data-mention-id`, history key). */
+type ComposerMentionId = string;
+/** One block in the composer document. Order is significant. */
+type ComposerBlock = {
+    kind: "text";
+    value: string;
+} | {
+    kind: "mention";
+    id: ComposerMentionId;
+    ref: AgentWidgetContextMentionRef;
+};
+/** Canonical inline-composer state. */
+type ComposerDocument = {
+    blocks: ComposerBlock[];
+};
+
+/**
+ * The composer input surface the mention controller drives, abstracted over the
+ * two editing modes:
+ *
+ *  - **chip mode** (`display: "chip"`, default): a plain `<textarea>`. Logical
+ *    text is the raw value and logical caret is `selectionStart`.
+ *  - **inline mode** (`display: "inline"`, Phase 4): a contenteditable surface
+ *    whose atomic mention tokens collapse to a single `` in the logical text
+ *    (see `composer-document.ts`). Its adapter additionally implements the
+ *    optional document/token methods below.
+ *
+ * The controller only ever touches the composer through this capability, so the
+ * same menu/keyboard/search engine serves both surfaces. `ComposerInputCapability`
+ * is a superset of the public `AgentWidgetContextMentionComposerCapability`
+ * (`getValue`/`setValue`/`submit`) — the single source of truth for composer
+ * access — so a client `command:"action"` handler receives the same object.
+ *
+ * IMPORTANT (bundle guard): this module imports the document model TYPE-ONLY, so
+ * the chip chunk (`context-mentions.js`) never pulls `composer-document.ts`
+ * runtime. The contenteditable adapter, which does need it, lives in the separate
+ * inline chunk. Keep it that way — see `context-mentions-bundle.test.ts`.
+ */
+
+interface ComposerInputCapability extends AgentWidgetContextMentionComposerCapability {
+    /** The editable element — ARIA target for the menu, and focus receiver. */
+    readonly element: HTMLElement;
+    /** Text used for trigger parsing. Chip: `=== getValue()`; inline: text + ``. */
+    getLogicalText: () => string;
+    /** Caret/selection in LOGICAL coordinates. */
+    getSelection: () => {
+        start: number;
+        end: number;
+    };
+    /** Move the caret/selection (logical coordinates). */
+    setSelection: (start: number, end?: number) => void;
+    /** Replace the plain text and place the caret. No input event, no focus. */
+    setValueWithCaret: (value: string, caret: number) => void;
+    /** Fire input listeners after a programmatic edit. */
+    dispatchInput: () => void;
+    focus: () => void;
+    /**
+     * INLINE ONLY (contenteditable). Bounding rect (VIEWPORT coordinates) of the
+     * LOGICAL character range `[start, end)`, or `null` when unmeasurable (invalid
+     * range or a zero-size/degenerate rect). Used to trigger-anchor the mention menu
+     * horizontally to the `@` glyph. Chip (textarea) adapters omit it — no cheap
+     * per-glyph rect without a mirror-div hack, so the menu stays composer-anchored
+     * (graceful degradation). Callers treat a missing method exactly like a `null`
+     * result.
+     */
+    getLogicalRangeRect?: (start: number, end: number) => DOMRect | null;
+    /** Canonical document (inline mode). */
+    getDocument?: () => ComposerDocument;
+    /**
+     * INLINE ONLY. Replace the active trigger range (`match`, logical coordinates)
+     * with an atomic mention token and place the caret after it. Returns the new
+     * mention's id (resolve-tracking key), or `null` if the range no longer matches
+     * the document (stale menu). Chip adapters leave this undefined — the controller
+     * then falls back to `stripMentionQuery`.
+     */
+    insertMentionAtTrigger?: (ref: AgentWidgetContextMentionRef, match: MentionTriggerMatch) => ComposerMentionId | null;
+    /**
+     * INLINE ONLY. Insert an atomic mention token at the current caret/selection
+     * (picker path — the affordance button opens with no trigger char to replace).
+     * Returns the new mention's id. Chip adapters leave this undefined.
+     */
+    insertMentionAtSelection?: (ref: AgentWidgetContextMentionRef) => ComposerMentionId;
+    /**
+     * INLINE ONLY. Reflect a mention's resolve status on its live token element —
+     * used to surface resolve errors inline. Toggles the error styling for `"error"`
+     * and clears it otherwise. No-op for an unknown id. Chip adapters omit this.
+     */
+    setMentionStatus?: (id: ComposerMentionId, status: "pending" | "resolved" | "error") => void;
+    /**
+     * INLINE ONLY. Replace the LOGICAL range `[start, end)` with plain `text`,
+     * preserving every mention token that lies outside the range, and place the
+     * caret after the inserted text. This is the token-safe edit the controller
+     * uses for query-strip / slash-completion / prompt-macro rewrites, since a plain
+     * `getValue()` string-slice would misalign against DISPLAY text (`@Label`
+     * expands a token to many chars) and re-rendering as one text block would
+     * destroy every token. Chip adapters omit it — there DISPLAY === LOGICAL, so the
+     * controller string-slices `getValue()` + `setValueWithCaret` instead.
+     */
+    replaceLogicalRange?: (start: number, end: number, text: string) => void;
+}
+
+/**
+ * Inline-mention chunk entry — the HEAVY, DOM-bearing half of inline mode. Loaded
+ * on composer mount when `contextMentions.display === "inline"` and NEVER
+ * statically imported on the core path (the IIFE build marks
+ * `@runtypelabs/persona/context-mentions-inline` external; ESM/CJS mark the same
+ * subpath external via `build:client`). This is the only place the
+ * contenteditable engine + `composer-document` enter the widget at runtime.
+ *
+ * `mountInlineComposer` builds a contenteditable `ComposerInputCapability` that
+ * visually mirrors the live `<textarea>` and migrates its current value + caret.
+ * It does NOT touch the DOM tree or rebind listeners — the caller (`ui.ts`) swaps
+ * the element in place and re-points the composer's event handlers, because those
+ * live in the core and the chunk must stay free of that wiring.
+ */
+
+interface InlineComposerMountContext {
+    /** The live composer textarea to migrate from (value + caret + look). */
+    textarea: HTMLTextAreaElement;
+    /**
+     * Build a token's full element. Supplied by the CORE orchestrator (which owns
+     * `createMentionTokenElement` + the shared icon renderer) so this lazy chunk
+     * never bundles the icon set — it already ships in core. The adapter marks the
+     * returned element `contenteditable="false"` and stamps `data-mention-id`.
+     */
+    renderToken: (ref: AgentWidgetContextMentionRef) => HTMLElement;
+    /**
+     * Fired when a token is deleted from the composer (backspace/cut). The caller
+     * routes this to `engine.untrackMention(id)` so the manager aborts its resolve.
+     */
+    onMentionRemoved?: (id: string) => void;
+}
+interface InlineComposerHandle {
+    /** The contenteditable input surface; hand this to `mountContextMentions`. */
+    input: ComposerInputCapability;
+    /** The contenteditable root element to swap in for the textarea. */
+    element: HTMLElement;
+    /** Detach the adapter's listeners on unmount. */
+    destroy: () => void;
+}
+declare function mountInlineComposer(ctx: InlineComposerMountContext): InlineComposerHandle;
+
+export { type InlineComposerHandle, type InlineComposerMountContext, mountInlineComposer };

package/dist/context-mentions-inline.js

@@ -0,0 +1,4 @@
+var le="@";function W(t){return t.kind==="text"?t.value.length:1}function O(t){let n=[],o=r=>{let l=n[n.length-1];l&&l.kind==="text"?l.value+=r:n.push({kind:"text",value:r})};(t.length===0||t[0].kind!=="text")&&n.push({kind:"text",value:""});for(let r of t){if(r.kind==="text"){o(r.value);continue}let l=n[n.length-1];(!l||l.kind!=="text")&&n.push({kind:"text",value:""}),n.push({kind:"mention",id:r.id,ref:r.ref}),n.push({kind:"text",value:""})}let e=n[n.length-1];return(!e||e.kind!=="text")&&n.push({kind:"text",value:""}),n}function Q(){return{blocks:[{kind:"text",value:""}]}}function H(t){return{blocks:[{kind:"text",value:t}]}}function P(t){return t.blocks.map(n=>n.kind==="text"?n.value:`${le}${n.ref.label}`).join("")}function R(t){return t.blocks.map(n=>n.kind==="text"?n.value:"\uFFFC").join("")}function L(t){return t.blocks.reduce((n,o)=>n+W(o),0)}function ce(t){let n=[];for(let o of t.blocks)o.kind==="mention"&&n.push({id:o.id,ref:o.ref});return n}function I(t,n){let o=[],e=[],r=0;for(let l of t){let u=W(l),p=r+u;if(p<=n)o.push(l);else if(r>=n)e.push(l);else if(l.kind==="text"){let b=n-r;b>0&&o.push({kind:"text",value:l.value.slice(0,b)}),b<u&&e.push({kind:"text",value:l.value.slice(b)})}else e.push(l);r=p}return{left:o,right:e}}function B(t,n,o,e){let r=I(t.blocks,n.start).left,l=I(t.blocks,n.end).right,u=l[0],p=u?.kind==="text"?u.value.charAt(0):"",b=p!==" "&&p!=="	"&&p!==`
+`,g=O([...r,{kind:"mention",id:e,ref:o},...b?[{kind:"text",value:" "}]:[],...l]),C=n.start+1+(p===`
+`?0:1);return{doc:{blocks:g},caret:C}}function X(t,n){let o=0,e=0,r=!1;for(let u of t.blocks)u.kind==="mention"&&u.id===n&&(o=e,r=!0),e+=W(u);return r?{doc:{blocks:O(t.blocks.filter(u=>!(u.kind==="mention"&&u.id===n)))},caret:o}:{doc:t,caret:e}}function S(t,n,o,e){let r=L(t),l=Math.max(0,Math.min(n,o,r)),u=Math.min(r,Math.max(n,o,0)),p=I(t.blocks,l).left,b=I(t.blocks,u).right;return{doc:{blocks:O([...p,{kind:"text",value:e},...b])},caret:l+e.length}}function Y(t){let n=[];for(let o of t.blocks)o.kind==="text"?o.value.length>0&&n.push({kind:"text",text:o.value}):n.push({kind:"mention",ref:o.ref});return{content:P(t),contextMentions:ce(t).map(o=>o.ref),contentSegments:n}}function G(t){t&&(typeof t.requestSubmit=="function"?t.requestSubmit():t.dispatchEvent(new Event("submit",{bubbles:!0,cancelable:!0})))}var ue="persona-mention-token-error",k="data-mention-id",v="data-mention-prev-label",_="data-mention-prev-title",U=`
+`;function y(t){return t.nodeType===1&&t.hasAttribute(k)}function Z(t){return t.nodeType===1&&t.tagName==="BR"}function D(t){return t.nodeType===3?t.data.length:y(t)||Z(t)?1:t.textContent?.length??0}function J(t,n,o){let e=0;for(let r of Array.from(t.childNodes)){if(r===n)return r.nodeType===3?e+o:e+(o>0?D(r):0);if(r.contains(n))return y(r)?e+1:e+ae(r,n,o);e+=D(r)}if(n===t){let r=0,l=Array.from(t.childNodes);for(let u=0;u<Math.min(o,l.length);u++)r+=D(l[u]);return r}return e}function ae(t,n,o){let e=0,r=l=>{if(l===n)return e+=l.nodeType===3?o:0,!0;if(l.nodeType===3)return e+=l.data.length,!1;for(let u of Array.from(l.childNodes))if(r(u))return!0;return!1};return r(t),e}function T(t,n){let o=0,e=Array.from(t.childNodes);for(let r=0;r<e.length;r++){let l=e[r],u=D(l);if(n<=o+u)return l.nodeType===3?{node:l,offset:n-o}:{node:t,offset:n<=o?r:r+1};o+=u}return{node:t,offset:e.length}}function de(t,n){let o=[];for(let e of Array.from(t.childNodes))if(y(e)){let r=e.getAttribute(k),l=n.get(r);l&&o.push({kind:"mention",id:r,ref:l})}else if(Z(e))o.push({kind:"text",value:U});else if(e.nodeType===3)o.push({kind:"text",value:e.data});else{let r=e.textContent??"";r&&o.push({kind:"text",value:r})}return o.length===0&&o.push({kind:"text",value:""}),{blocks:o}}function ee(t){let n=t.renderToken,o=new Map,e=t.element??document.createElement("div");e.setAttribute("contenteditable","true"),e.setAttribute("data-persona-composer-input",""),e.setAttribute("role","textbox"),e.setAttribute("aria-multiline","true"),e.classList.add("persona-composer-contenteditable"),t.placeholder!=null&&e.setAttribute("data-placeholder",t.placeholder);let r=!1,l=0,u=()=>de(e,o),p=c=>{e.replaceChildren();for(let s of c.blocks)if(s.kind==="text")s.value.length>0&&e.appendChild(document.createTextNode(s.value));else{o.set(s.id,s.ref);let i=n(s.ref);i.setAttribute("contenteditable","false"),i.setAttribute(k,s.id),e.appendChild(i)}},b=()=>{let s=e.getRootNode().activeElement;return s===e||s!=null&&e.contains(s)},g=(c,s)=>{if(l=c,!s?.focus&&!b())return;let i=typeof window<"u"?window.getSelection():null;if(!i)return;let d=T(e,c);try{let a=document.createRange();a.setStart(d.node,d.offset),a.collapse(!0),i.removeAllRanges(),i.addRange(a)}catch{}},C=()=>{e.dispatchEvent(new Event("input",{bubbles:!0}))},x=()=>{let c={start:l,end:l},s=typeof window<"u"?window.getSelection():null;if(!s||s.rangeCount===0)return c;let i=s.getRangeAt(0);if(!e.contains(i.startContainer))return c;let d=J(e,i.startContainer,i.startOffset),a=i.collapsed?d:J(e,i.endContainer,i.endOffset);return{start:Math.min(d,a),end:Math.max(d,a)}},A=()=>{let c=new Set;for(let s of Array.from(e.childNodes))y(s)&&c.add(s.getAttribute(k));for(let s of Array.from(o.keys()))c.has(s)||(o.delete(s),t.onMentionRemoved?.(s))},F=()=>{r||o.size!==0&&A()},V=()=>{r=!0},q=()=>{r=!1,A()},j=c=>{c.preventDefault();let s=c.clipboardData?.getData("text/plain")??"";if(typeof document.execCommand=="function")document.execCommand("insertText",!1,s);else{let{start:i,end:d}=x(),a=S(u(),i,d,s);p(a.doc),g(a.caret,{focus:!0}),A()}C()},$=c=>{if(r)return;let s=c.inputType;if(s==="insertParagraph"){c.preventDefault();let{start:M,end:E}=x(),K=S(u(),M,E,U);p(K.doc),g(K.caret,{focus:!0}),o.size>0&&A(),C();return}if(s!=="deleteContentBackward"&&s!=="deleteContentForward"||o.size===0)return;let{start:i,end:d}=x();if(i!==d)return;let a=u(),m=R(a),f=s==="deleteContentBackward"?i-1:i;if(f<0||f>=m.length||m[f]!=="\uFFFC")return;let h=0,N=null;for(let M of a.blocks){let E=M.kind==="text"?M.value.length:1;if(M.kind==="mention"&&f>=h&&f<h+E){N=M.id;break}h+=E}if(!N)return;c.preventDefault();let z=X(a,N);p(z.doc),g(z.caret,{focus:!0}),A(),C()},te=(c,s)=>{p(H(c)),g(s)},ne=(c,s)=>{if(!Number.isFinite(c)||!Number.isFinite(s)||s<=c)return null;try{let i=T(e,c),d=T(e,s),a=document.createRange();a.setStart(i.node,i.offset),a.setEnd(d.node,d.offset);let m=a.getBoundingClientRect();return m.width===0&&m.height===0?null:m}catch{return null}},oe=(c,s,i)=>{let d=S(u(),c,s,i);p(d.doc),g(d.caret,{focus:!0})},re=(c,s)=>{let i=u(),d=R(i),a=s.triggerIndex,m=s.triggerIndex+1+s.query.length;if(a<0||m>d.length||d.slice(a+1,m)!==s.query)return null;let f=t.generateId(),h=B(i,{start:a,end:m},c,f);return p(h.doc),g(h.caret,{focus:!0}),t.onMentionInserted?.(f,c),C(),f},ie=c=>{let s=u(),i=x(),a=typeof window<"u"&&!!window.getSelection()?.rangeCount&&e.contains(window.getSelection().getRangeAt(0).startContainer)?{start:i.start,end:i.end}:{start:L(s),end:L(s)},m=t.generateId(),f=B(s,a,c,m);return p(f.doc),g(f.caret,{focus:!0}),t.onMentionInserted?.(m,c),C(),m},se=(c,s)=>{for(let i of Array.from(e.childNodes))if(y(i)&&i.getAttribute(k)===c){let d=s==="error";if(i.classList.toggle(ue,d),d){i.hasAttribute(v)||(i.setAttribute(v,i.getAttribute("aria-label")??""),i.setAttribute(_,i.getAttribute("title")??""));let a=o.get(c)?.label??"";i.setAttribute("title",`${a}: failed to attach context`),i.setAttribute("aria-label",`${a}, failed to attach context`)}else if(i.hasAttribute(v)){let a=i.getAttribute(v),m=i.getAttribute(_);a?i.setAttribute("aria-label",a):i.removeAttribute("aria-label"),m?i.setAttribute("title",m):i.removeAttribute("title"),i.removeAttribute(v),i.removeAttribute(_)}return}};return e.addEventListener("input",F),e.addEventListener("compositionstart",V),e.addEventListener("compositionend",q),e.addEventListener("paste",j),e.addEventListener("beforeinput",$),p(Q()),{element:e,getValue:()=>P(u()),getLogicalText:()=>R(u()),getDocument:u,getSelection:x,setSelection:(c,s=c)=>{let i=typeof window<"u"?window.getSelection():null;if(i)try{let d=T(e,c),a=T(e,s),m=document.createRange();m.setStart(d.node,d.offset),m.setEnd(a.node,a.offset),i.removeAllRanges(),i.addRange(m)}catch{}},setValueWithCaret:te,getLogicalRangeRect:ne,setValue:c=>{p(H(c)),e.focus(),g(c.length,{focus:!0}),C()},replaceLogicalRange:oe,insertMentionAtTrigger:re,insertMentionAtSelection:ie,setMentionStatus:se,submit:()=>G(e.closest("form")),dispatchInput:C,focus:()=>e.focus(),destroy:()=>{e.removeEventListener("input",F),e.removeEventListener("compositionstart",V),e.removeEventListener("compositionend",q),e.removeEventListener("paste",j),e.removeEventListener("beforeinput",$)}}}var me=0,pe=()=>`pmention-${++me}`;function fe(t,n){n.className=`${t.className} persona-composer-contenteditable`.trim();for(let r=0;r<t.style.length;r++){let l=t.style.item(r);l!=="height"&&n.style.setProperty(l,t.style.getPropertyValue(l),t.style.getPropertyPriority(l))}let o=t.getAttribute("placeholder");o&&(n.setAttribute("data-placeholder",o),n.setAttribute("aria-placeholder",o));let e=t.getAttribute("aria-label")??o;e&&n.setAttribute("aria-label",e)}function ge(t,n,o){Object.defineProperty(t,"value",{configurable:!0,get:()=>n.getValue(),set:e=>{n.setValueWithCaret(e,e.length),n.dispatchInput()}}),Object.defineProperty(t,"placeholder",{configurable:!0,get:()=>t.getAttribute("data-placeholder")??"",set:e=>{e?(t.setAttribute("data-placeholder",e),t.setAttribute("aria-placeholder",e),o||t.setAttribute("aria-label",e)):(t.removeAttribute("data-placeholder"),t.removeAttribute("aria-placeholder"),o||t.removeAttribute("aria-label"))}}),Object.defineProperty(t,"selectionStart",{configurable:!0,get:()=>n.getSelection().start}),Object.defineProperty(t,"selectionEnd",{configurable:!0,get:()=>n.getSelection().end}),t.setSelectionRange=(e,r)=>n.setSelection(e??0,r??e??0)}function be(t){let{textarea:n}=t,o={generateId:pe,renderToken:t.renderToken,onMentionRemoved:t.onMentionRemoved,placeholder:n.getAttribute("placeholder")??void 0},e=ee(o),r=e.element,l=n.getAttribute("aria-label")!=null;fe(n,r),ge(r,e,l),r.getInlineMessageFields=()=>Y(e.getDocument?.()??{blocks:[]});let u=n.selectionStart??n.value.length;return e.setValueWithCaret(n.value,u),{input:e,element:r,destroy:e.destroy}}export{be as mountInlineComposer};