feat(web): enable rich text composer by default#12160

@@ -1,2137 +1,17 @@
-import { ContextChipPopover } from "./contextChipParts";
-import { Button } from "./ui/button";
-import { LexicalComposer, type InitialConfigType } from "@lexical/react/LexicalComposer";
-import { useLexicalComposerContext } from "@lexical/react/LexicalComposerContext";
-import { ContentEditable } from "@lexical/react/LexicalContentEditable";
-import { LexicalErrorBoundary } from "@lexical/react/LexicalErrorBoundary";
-import { HistoryPlugin } from "@lexical/react/LexicalHistoryPlugin";
-import { OnChangePlugin } from "@lexical/react/LexicalOnChangePlugin";
-import { PlainTextPlugin } from "@lexical/react/LexicalPlainTextPlugin";
-import {
-  type ComposerContextClipboardFragment,
-  type ServerProviderSkill,
-} from "@t3tools/contracts";
-import {
-  COMPOSER_CONTEXT_CLIPBOARD_MIME,
-  encodeComposerContextClipboardHtml,
-} from "@t3tools/shared/composerContextClipboard";
-import { serializeComposerFileLink } from "@t3tools/shared/composerTrigger";
-import {
-  $applyNodeReplacement,
-  $createRangeSelectionFromDom,
-  $createRangeSelection,
-  $getSelection,
-  $setSelection,
-  $isElementNode,
-  $isLineBreakNode,
-  $isRangeSelection,
-  $isTextNode,
-  $createLineBreakNode,
-  $createParagraphNode,
-  $createTextNode,
-  KEY_ARROW_DOWN_COMMAND,
-  KEY_ARROW_LEFT_COMMAND,
-  KEY_ARROW_RIGHT_COMMAND,
-  KEY_ARROW_UP_COMMAND,
-  KEY_DOWN_COMMAND,
-  KEY_ENTER_COMMAND,
-  KEY_TAB_COMMAND,
-  COMMAND_PRIORITY_HIGH,
-  COPY_COMMAND,
-  CUT_COMMAND,
-  COMMAND_PRIORITY_LOW,
-  KEY_BACKSPACE_COMMAND,
-  BLUR_COMMAND,
-  FOCUS_COMMAND,
-  $getRoot,
-  $getNodeByKey,
-  HISTORY_MERGE_TAG,
-  HISTORY_PUSH_TAG,
-  SKIP_DOM_SELECTION_TAG,
-  DecoratorNode,
-  type ElementNode,
-  type LexicalNode,
-  type SerializedLexicalNode,
-  type EditorState,
-  type NodeKey,
-  type Spread,
-} from "lexical";
-import {
-  createContext,
-  use,
-  useCallback,
-  useEffect,
-  useEffectEvent,
-  useImperativeHandle,
-  useLayoutEffect,
-  useMemo,
-  useRef,
-  useState,
-} from "react";
+import { ComposerPromptEditorTiptap } from "./ComposerPromptEditorTiptap";
+import type { ComposerPromptEditorProps } from "./ComposerPromptEditorTiptap";
 
-import {
-  clampCollapsedComposerCursor,
-  collapseExpandedComposerCursor,
-  expandCollapsedComposerCursor,
-  isCollapsedCursorAdjacentToInlineToken,
-} from "~/composer-logic";
-import {
-  selectionTouchesMentionBoundary,
-  splitPromptIntoComposerSegments,
-} from "~/composer-editor-mentions";
-import { collectInlineContextIds } from "~/lib/composerContextReferences";
-import { cn, isMacPlatform } from "~/lib/utils";
-import { basenameOfPath } from "~/pierre-icons";
-import {
-  COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME,
-  COMPOSER_INLINE_CHIP_ICON_CLASS_NAME,
-  COMPOSER_INLINE_CHIP_LABEL_CLASS_NAME,
-  COMPOSER_INLINE_SKILL_CHIP_CLASS_NAME,
-  SKILL_CHIP_ICON_SVG,
-} from "./composerInlineChip";
-import { FILE_TAG_CHIP_CLASS_NAME, FileTagChipContent } from "./chat/FileTagChip";
-import { getTimelinePageScrollKey } from "./chat/pageScrollController";
-import {
-  $createComposerContextReferenceNode,
-  ComposerContextReferenceNode,
-} from "./ComposerContextReferenceNode";
-import {
-  ComposerContextActionsContext,
-  ComposerContextRecordsContext,
-  type ComposerDraftContextRecords,
-} from "./composerContextPresentation";
-import { formatProviderSkillDisplayName } from "@t3tools/client-runtime/providerSkills";
-import { Tooltip, TooltipPopup, TooltipTrigger } from "./ui/tooltip";
-import { registerComposerInlineTokenPaste } from "./composerInlineTokenPaste";
-import { didComposerSelectionChangeVisibly } from "./composerSelection";
-import {
-  $consumeComposerCitationCommentRequest,
-  $createComposerCitationNode,
-  ComposerCitationCommentContext,
-  ComposerCitationNode,
-  type ComposerCitationCommentRequest,
-  type ComposerCitationCommentTarget,
-} from "./ComposerCitationNode";
-
-const COMPOSER_EDITOR_HMR_KEY = `composer-editor-${Math.random().toString(36).slice(2)}`;
-const SURROUND_SYMBOLS: [string, string][] = [
-  ["(", ")"],
-  ["[", "]"],
-  ["{", "}"],
-  ["'", "'"],
-  ['"', '"'],
-  ["“", "”"],
-  ["`", "`"],
-  ["<", ">"],
-  ["«", "»"],
-  ["*", "*"],
-  ["_", "_"],
-];
-const SURROUND_SYMBOLS_MAP = new Map<string, string>(SURROUND_SYMBOLS);
-const BACKTICK_SURROUND_CLOSE_SYMBOL = SURROUND_SYMBOLS_MAP.get("`") ?? null;
-
-type SerializedComposerMentionNode = Spread<
-  {
-    path: string;
-    source?: string;
-    type: "composer-mention";
-    version: 1;
-  },
-  SerializedLexicalNode
->;
-
-type SerializedComposerSkillNode = Spread<
-  {
-    skillName: string;
-    skillLabel?: string;
-    skillDescription?: string;
-    type: "composer-skill";
-    version: 1;
-  },
-  SerializedLexicalNode
->;
-
-function ComposerMentionDecorator(props: { path: string }) {
-  const actions = use(ComposerContextActionsContext);
-  const theme = resolvedThemeFromDocument();
-  const chip = (
-    <button
-      type="button"
-      onClick={() => actions.openMention(props.path)}
-      aria-label={`Preview ${props.path}`}
-      className={`${FILE_TAG_CHIP_CLASS_NAME} cursor-pointer focus-visible:outline-2`}
-      contentEditable={false}
-      spellCheck={false}
-      data-composer-mention-chip="true"
-    >
-      <FileTagChipContent path={props.path} label={basenameOfPath(props.path)} theme={theme} />
-    </button>
-  );
-
-  return (
-    <Tooltip>
-      <TooltipTrigger render={chip} />
-      <TooltipPopup side="top" className="max-w-120 whitespace-normal leading-tight wrap-anywhere">
-        {props.path}
-      </TooltipPopup>
-    </Tooltip>
-  );
-}
-
-class ComposerMentionNode extends DecoratorNode<React.ReactElement> {
-  __path: string;
-  __source: string;
-
-  static override getType(): string {
-    return "composer-mention";
-  }
-
-  static override clone(node: ComposerMentionNode): ComposerMentionNode {
-    return new ComposerMentionNode(node.__path, node.__source, node.__key);
-  }
-
-  static override importJSON(serializedNode: SerializedComposerMentionNode): ComposerMentionNode {
-    return $createComposerMentionNode(serializedNode.path, serializedNode.source).updateFromJSON(
-      serializedNode,
-    );
-  }
-
-  constructor(path: string, source = serializeComposerFileLink(path), key?: NodeKey) {
-    super(key);
-    this.__path = path;
-    this.__source = source;
-  }
-
-  override exportJSON(): SerializedComposerMentionNode {
-    return {
-      ...super.exportJSON(),
-      path: this.__path,
-      source: this.__source,
-      type: "composer-mention",
-      version: 1,
-    };
-  }
-
-  override createDOM(): HTMLElement {
-    const dom = document.createElement("span");
-    dom.className = COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME;
-    return dom;
-  }
-
-  override updateDOM(): false {
-    return false;
-  }
-
-  override getTextContent(): string {
-    return this.__source;
-  }
-
-  override isInline(): true {
-    return true;
-  }
-
-  override decorate(): React.ReactElement {
-    return <ComposerMentionDecorator path={this.__path} />;
-  }
-}
-
-function $createComposerMentionNode(path: string, source?: string): ComposerMentionNode {
-  return $applyNodeReplacement(new ComposerMentionNode(path, source));
-}
-
-function resolveSkillDescription(
-  skill: Pick<ServerProviderSkill, "shortDescription" | "description">,
-): string | null {
-  const shortDescription = skill.shortDescription?.trim();
-  if (shortDescription) {
-    return shortDescription;
-  }
-  const description = skill.description?.trim();
-  return description || null;
-}
-
-type ComposerSkillMetadata = {
-  label: string;
-  description: string | null;
-};
-
-function skillMetadataByName(
-  skills: ReadonlyArray<ServerProviderSkill>,
-): ReadonlyMap<string, ComposerSkillMetadata> {
-  return new Map(
-    skills.map((skill) => [
-      skill.name,
-      {
-        label: formatProviderSkillDisplayName(skill),
-        description: resolveSkillDescription(skill),
-      },
-    ]),
-  );
-}
-
-const ComposerSkillsContext = createContext<ReadonlyArray<ServerProviderSkill>>([]);
-
-function ComposerSkillDecorator(props: {
-  skillName: string;
-  skillLabel: string;
-  skillDescription: string | null;
-}) {
-  const actions = use(ComposerContextActionsContext);
-  const skill = use(ComposerSkillsContext).find((candidate) => candidate.name === props.skillName);
-  return (
-    <ContextChipPopover
-      accessibleLabel={`Skill ${props.skillLabel}`}
-      triggerClassName={COMPOSER_INLINE_SKILL_CHIP_CLASS_NAME}
-      chip={
-        <>
-          <span
-            aria-hidden="true"
-            className={COMPOSER_INLINE_CHIP_ICON_CLASS_NAME}
-            dangerouslySetInnerHTML={{ __html: SKILL_CHIP_ICON_SVG }}
-          />
-          <span className={COMPOSER_INLINE_CHIP_LABEL_CLASS_NAME}>{props.skillLabel}</span>
-        </>
-      }
-    >
-      <div className="space-y-3 p-2 text-sm">
-        <p className="font-medium">{props.skillLabel}</p>
-        <p>
-          {skill?.description ??
-            props.skillDescription ??
-            "No description is available for this skill."}
-        </p>
-        {skill?.path ? (
-          <Button variant="outline" size="sm" onClick={() => actions.openMention(skill.path)}>
-            View instructions
-          </Button>
-        ) : null}
-      </div>
-    </ContextChipPopover>
-  );
-}
-
-class ComposerSkillNode extends DecoratorNode<React.ReactElement> {
-  __skillName: string;
-  __skillLabel: string;
-  __skillDescription: string | null;
-
-  static override getType(): string {
-    return "composer-skill";
-  }
-
-  static override clone(node: ComposerSkillNode): ComposerSkillNode {
-    return new ComposerSkillNode(
-      node.__skillName,
-      node.__skillLabel,
-      node.__skillDescription,
-      node.__key,
-    );
-  }
-
-  static override importJSON(serializedNode: SerializedComposerSkillNode): ComposerSkillNode {
-    return $createComposerSkillNode(
-      serializedNode.skillName,
-      serializedNode.skillLabel ?? serializedNode.skillName,
-      serializedNode.skillDescription ?? null,
-    ).updateFromJSON(serializedNode);
-  }
-
-  constructor(
-    skillName: string,
-    skillLabel: string,
-    skillDescription: string | null,
-    key?: NodeKey,
-  ) {
-    super(key);
-    const normalizedSkillName = skillName.startsWith("$") ? skillName.slice(1) : skillName;
-    this.__skillName = normalizedSkillName;
-    this.__skillLabel = skillLabel;
-    this.__skillDescription = skillDescription;
-  }
-
-  override exportJSON(): SerializedComposerSkillNode {
-    return {
-      ...super.exportJSON(),
-      skillName: this.__skillName,
-      skillLabel: this.__skillLabel,
-      ...(this.__skillDescription ? { skillDescription: this.__skillDescription } : {}),
-      type: "composer-skill",
-      version: 1,
-    };
-  }
-
-  override createDOM(): HTMLElement {
-    const dom = document.createElement("span");
-    dom.className = COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME;
-    return dom;
-  }
-
-  override updateDOM(): false {
-    return false;
-  }
-
-  override getTextContent(): string {
-    return `$${this.__skillName}`;
-  }
-
-  override isInline(): true {
-    return true;
-  }
-
-  override decorate(): React.ReactElement {
-    return (
-      <ComposerSkillDecorator
-        skillName={this.__skillName}
-        skillLabel={this.__skillLabel}
-        skillDescription={this.__skillDescription}
-      />
-    );
-  }
-}
-
-function $createComposerSkillNode(
-  skillName: string,
-  skillLabel: string,
-  skillDescription: string | null,
-): ComposerSkillNode {
-  return $applyNodeReplacement(new ComposerSkillNode(skillName, skillLabel, skillDescription));
-}
-
-type ComposerInlineTokenNode =
-  | ComposerMentionNode
-  | ComposerSkillNode
-  | ComposerCitationNode
-  | ComposerContextReferenceNode;
-
-function isComposerInlineTokenNode(candidate: unknown): candidate is ComposerInlineTokenNode {
-  return (
-    candidate instanceof ComposerMentionNode ||
-    candidate instanceof ComposerSkillNode ||
-    candidate instanceof ComposerCitationNode ||
-    candidate instanceof ComposerContextReferenceNode
-  );
-}
-
-function resolvedThemeFromDocument(): "light" | "dark" {
-  return document.documentElement.classList.contains("dark") ? "dark" : "light";
-}
-
-function skillSignature(skills: ReadonlyArray<ServerProviderSkill>): string {
-  return skills
-    .map((skill) =>
-      [
-        skill.name,
-        skill.displayName ?? "",
-        skill.shortDescription ?? "",
-        skill.description ?? "",
-        skill.path,
-        skill.scope ?? "",
-        skill.enabled ? "1" : "0",
-      ].join("\u001f"),
-    )
-    .join("\u001e");
-}
-
-function clampExpandedCursor(value: string, cursor: number): number {
-  if (!Number.isFinite(cursor)) return value.length;
-  return Math.max(0, Math.min(value.length, Math.floor(cursor)));
-}
-
-function getComposerInlineTokenTextLength(_node: ComposerInlineTokenNode): 1 {
-  return 1;
-}
-
-function getComposerInlineTokenExpandedTextLength(node: ComposerInlineTokenNode): number {
-  return node.getTextContentSize();
-}
-
-function getAbsoluteOffsetForInlineTokenPoint(
-  node: ComposerInlineTokenNode,
-  absoluteOffset: number,
-  pointOffset: number,
-): number {
-  return absoluteOffset + (pointOffset > 0 ? getComposerInlineTokenTextLength(node) : 0);
-}
-
-function getExpandedAbsoluteOffsetForInlineTokenPoint(
-  node: ComposerInlineTokenNode,
-  absoluteOffset: number,
-  pointOffset: number,
-): number {
-  return absoluteOffset + (pointOffset > 0 ? getComposerInlineTokenExpandedTextLength(node) : 0);
-}
-
-function findSelectionPointForInlineToken(
-  node: ComposerInlineTokenNode,
-  remainingRef: { value: number },
-): { key: string; offset: number; type: "element" } | null {
-  const parent = node.getParent();
-  if (!parent || !$isElementNode(parent)) return null;
-  const index = node.getIndexWithinParent();
-  if (remainingRef.value === 0) {
-    return {
-      key: parent.getKey(),
-      offset: index,
-      type: "element",
-    };
-  }
-  if (remainingRef.value === getComposerInlineTokenTextLength(node)) {
-    return {
-      key: parent.getKey(),
-      offset: index + 1,
-      type: "element",
-    };
-  }
-  remainingRef.value -= getComposerInlineTokenTextLength(node);
-  return null;
-}
-
-function getComposerNodeTextLength(node: LexicalNode): number {
-  if (isComposerInlineTokenNode(node)) {
-    return getComposerInlineTokenTextLength(node);
-  }
-  if ($isTextNode(node)) {
-    return node.getTextContentSize();
-  }
-  if ($isLineBreakNode(node)) {
-    return 1;
-  }
-  if ($isElementNode(node)) {
-    return node.getChildren().reduce((total, child) => total + getComposerNodeTextLength(child), 0);
-  }
-  return 0;
-}
-
-function getComposerNodeExpandedTextLength(node: LexicalNode): number {
-  if (isComposerInlineTokenNode(node)) {
-    return getComposerInlineTokenExpandedTextLength(node);
-  }
-  if ($isTextNode(node)) {
-    return node.getTextContentSize();
-  }
-  if ($isLineBreakNode(node)) {
-    return 1;
-  }
-  if ($isElementNode(node)) {
-    return node
-      .getChildren()
-      .reduce((total, child) => total + getComposerNodeExpandedTextLength(child), 0);
-  }
-  return 0;
-}
-
-function getAbsoluteOffsetForPoint(node: LexicalNode, pointOffset: number): number {
-  let offset = 0;
-  let current: LexicalNode | null = node;
-
-  while (current) {
-    const nextParent = current.getParent() as LexicalNode | null;
-    if (!nextParent || !$isElementNode(nextParent)) {
-      break;
-    }
-    const siblings = nextParent.getChildren();
-    const index = current.getIndexWithinParent();
-    for (let i = 0; i < index; i += 1) {
-      const sibling = siblings[i];
-      if (!sibling) continue;
-      offset += getComposerNodeTextLength(sibling);
-    }
-    current = nextParent;
-  }
-
-  if ($isTextNode(node)) {
-    return offset + Math.min(pointOffset, node.getTextContentSize());
-  }
-  if (isComposerInlineTokenNode(node)) {
-    return getAbsoluteOffsetForInlineTokenPoint(node, offset, pointOffset);
-  }
-
-  if ($isLineBreakNode(node)) {
-    return offset + Math.min(pointOffset, 1);
-  }
-
-  if ($isElementNode(node)) {
-    const children = node.getChildren();
-    const clampedOffset = Math.max(0, Math.min(pointOffset, children.length));
-    for (let i = 0; i < clampedOffset; i += 1) {
-      const child = children[i];
-      if (!child) continue;
-      offset += getComposerNodeTextLength(child);
-    }
-    return offset;
-  }
-
-  return offset;
-}
-
-function getExpandedAbsoluteOffsetForPoint(node: LexicalNode, pointOffset: number): number {
-  let offset = 0;
-  let current: LexicalNode | null = node;
-
-  while (current) {
-    const nextParent = current.getParent() as LexicalNode | null;
-    if (!nextParent || !$isElementNode(nextParent)) {
-      break;
-    }
-    const siblings = nextParent.getChildren();
-    const index = current.getIndexWithinParent();
-    for (let i = 0; i < index; i += 1) {
-      const sibling = siblings[i];
-      if (!sibling) continue;
-      offset += getComposerNodeExpandedTextLength(sibling);
-    }
-    current = nextParent;
-  }
-
-  if ($isTextNode(node)) {
-    return offset + Math.min(pointOffset, node.getTextContentSize());
-  }
-  if (isComposerInlineTokenNode(node)) {
-    return getExpandedAbsoluteOffsetForInlineTokenPoint(node, offset, pointOffset);
-  }
-
-  if ($isLineBreakNode(node)) {
-    return offset + Math.min(pointOffset, 1);
-  }
-
-  if ($isElementNode(node)) {
-    const children = node.getChildren();
-    const clampedOffset = Math.max(0, Math.min(pointOffset, children.length));
-    for (let i = 0; i < clampedOffset; i += 1) {
-      const child = children[i];
-      if (!child) continue;
-      offset += getComposerNodeExpandedTextLength(child);
-    }
-    return offset;
-  }
-
-  return offset;
-}
-
-function findSelectionPointAtOffset(
-  node: LexicalNode,
-  remainingRef: { value: number },
-): { key: string; offset: number; type: "text" | "element" } | null {
-  if (isComposerInlineTokenNode(node)) {
-    return findSelectionPointForInlineToken(node, remainingRef);
-  }
-
-  if ($isTextNode(node)) {
-    const size = node.getTextContentSize();
-    if (remainingRef.value <= size) {
-      return {
-        key: node.getKey(),
-        offset: remainingRef.value,
-        type: "text",
-      };
-    }
-    remainingRef.value -= size;
-    return null;
-  }
-
-  if ($isLineBreakNode(node)) {
-    const parent = node.getParent();
-    if (!parent) return null;
-    const index = node.getIndexWithinParent();
-    if (remainingRef.value === 0) {
-      return {
-        key: parent.getKey(),
-        offset: index,
-        type: "element",
-      };
-    }
-    if (remainingRef.value === 1) {
-      return {
-        key: parent.getKey(),
-        offset: index + 1,
-        type: "element",
-      };
-    }
-    remainingRef.value -= 1;
-    return null;
-  }
-
-  if ($isElementNode(node)) {
-    const children = node.getChildren();
-    for (const child of children) {
-      const point = findSelectionPointAtOffset(child, remainingRef);
-      if (point) {
-        return point;
-      }
-    }
-    if (remainingRef.value === 0) {
-      return {
-        key: node.getKey(),
-        offset: children.length,
-        type: "element",
-      };
-    }
-  }
-
-  return null;
-}
-
-function $getComposerRootLength(): number {
-  const root = $getRoot();
-  const children = root.getChildren();
-  return children.reduce((sum, child) => sum + getComposerNodeTextLength(child), 0);
-}
-
-function $setSelectionAtComposerOffset(nextOffset: number): void {
-  const root = $getRoot();
-  const composerLength = $getComposerRootLength();
-  const boundedOffset = Math.max(0, Math.min(nextOffset, composerLength));
-  const remainingRef = { value: boundedOffset };
-  const point = findSelectionPointAtOffset(root, remainingRef) ?? {
-    key: root.getKey(),
-    offset: root.getChildren().length,
-    type: "element" as const,
-  };
-  const selection = $createRangeSelection();
-  selection.anchor.set(point.key, point.offset, point.type);
-  selection.focus.set(point.key, point.offset, point.type);
-  $setSelection(selection);
-}
-
-function $setSelectionRangeAtComposerOffsets(startOffset: number, endOffset: number): void {
-  const root = $getRoot();
-  const composerLength = $getComposerRootLength();
-  const boundedStart = Math.max(0, Math.min(startOffset, composerLength));
-  const boundedEnd = Math.max(0, Math.min(endOffset, composerLength));
-  const anchorRemainingRef = { value: boundedStart };
-  const focusRemainingRef = { value: boundedEnd };
-  const anchorPoint = findSelectionPointAtOffset(root, anchorRemainingRef) ?? {
-    key: root.getKey(),
-    offset: root.getChildren().length,
-    type: "element" as const,
-  };
-  const focusPoint = findSelectionPointAtOffset(root, focusRemainingRef) ?? {
-    key: root.getKey(),
-    offset: root.getChildren().length,
-    type: "element" as const,
-  };
-  const selection = $createRangeSelection();
-  selection.anchor.set(anchorPoint.key, anchorPoint.offset, anchorPoint.type);
-  selection.focus.set(focusPoint.key, focusPoint.offset, focusPoint.type);
-  $setSelection(selection);
-}
-
-function getSelectionRangeForExpandedComposerOffsets(selection: ReturnType<typeof $getSelection>): {
-  start: number;
-  end: number;
-} | null {
-  if (!$isRangeSelection(selection)) {
-    return null;
-  }
-  const anchorNode = selection.anchor.getNode();
-  const focusNode = selection.focus.getNode();
-  const anchorOffset = getExpandedAbsoluteOffsetForPoint(anchorNode, selection.anchor.offset);
-  const focusOffset = getExpandedAbsoluteOffsetForPoint(focusNode, selection.focus.offset);
-  return {
-    start: Math.min(anchorOffset, focusOffset),
-    end: Math.max(anchorOffset, focusOffset),
-  };
-}
-
-function $selectionTouchesInlineToken(selection: ReturnType<typeof $getSelection>): boolean {
-  if (!$isRangeSelection(selection)) {
-    return false;
-  }
-  return selection.getNodes().some((node) => isComposerInlineTokenNode(node));
-}
-
-function $readSelectionOffsetFromEditorState(fallback: number): number {
-  const selection = $getSelection();
-  if (!$isRangeSelection(selection) || !selection.isCollapsed()) {
-    return fallback;
-  }
-  const anchorNode = selection.anchor.getNode();
-  const offset = getAbsoluteOffsetForPoint(anchorNode, selection.anchor.offset);
-  const composerLength = $getComposerRootLength();
-  return Math.max(0, Math.min(offset, composerLength));
-}
-
-function $readExpandedSelectionOffsetFromEditorState(fallback: number): number {
-  const selection = $getSelection();
-  if (!$isRangeSelection(selection) || !selection.isCollapsed()) {
-    return fallback;
-  }
-  const anchorNode = selection.anchor.getNode();
-  const offset = getExpandedAbsoluteOffsetForPoint(anchorNode, selection.anchor.offset);
-  const expandedLength = $getRoot().getTextContent().length;
-  return Math.max(0, Math.min(offset, expandedLength));
-}
-
-function $appendTextWithLineBreaks(parent: ElementNode, text: string): void {
-  const lines = text.split("\n");
-  for (let index = 0; index < lines.length; index += 1) {
-    const line = lines[index] ?? "";
-    if (line.length > 0) {
-      parent.append($createTextNode(line));
-    }
-    if (index < lines.length - 1) {
-      parent.append($createLineBreakNode());
-    }
-  }
-}
-
-function $setComposerEditorPrompt(
-  prompt: string,
-  skillMetadata: ReadonlyMap<string, ComposerSkillMetadata>,
-): void {
-  const root = $getRoot();
-  root.clear();
-  const paragraph = $createParagraphNode();
-  root.append(paragraph);
-
-  const segments = splitPromptIntoComposerSegments(prompt);
-  for (const segment of segments) {
-    if (segment.type === "citation") {
-      paragraph.append($createComposerCitationNode(segment.citation, segment.source));
-      continue;
-    }
-    if (segment.type === "mention") {
-      paragraph.append($createComposerMentionNode(segment.path, segment.source));
-      continue;
-    }
-    if (segment.type === "skill") {
-      const metadata = skillMetadata.get(segment.name);
-      paragraph.append(
-        $createComposerSkillNode(
-          segment.name,
-          metadata?.label ?? formatProviderSkillDisplayName({ name: segment.name }),
-          metadata?.description ?? null,
-        ),
-      );
-      continue;
-    }
-    if (segment.type === "context-reference") {
-      paragraph.append(
-        $createComposerContextReferenceNode({
-          kind: segment.kind,
-          contextId: segment.contextId,
-          label: segment.label,
-        }),
-      );
-      continue;
-    }
-    $appendTextWithLineBreaks(paragraph, segment.text);
-  }
-}
-
-function collectContextIdOccurrences(node: LexicalNode): string[] {
-  if (node instanceof ComposerContextReferenceNode) {
-    return [node.__contextId];
-  }
-  if ($isElementNode(node)) {
-    return node.getChildren().flatMap((child) => collectContextIdOccurrences(child));
-  }
-  return [];
-}
-
-/** Payload ids referenced by the document, once each in first-occurrence order. */
-function collectContextIds(node: LexicalNode): string[] {
-  return Array.from(new Set(collectContextIdOccurrences(node)));
-}
-
-export interface ComposerPromptEditorHandle {
-  focus: () => void;
-  focusAt: (cursor: number) => void;
-  focusAtEnd: () => void;
-  readSelectionRange: () => { start: number; end: number };
-  requestCitationComment: (request: ComposerCitationCommentRequest) => void;
-  readSnapshot: () => {
-    value: string;
-    cursor: number;
-    expandedCursor: number;
-    contextIds: string[];
-  };
-  /**
-   * True when a collapsed caret sits on the first ("start") or last ("end")
-   * visual line, counting soft wraps. Prompt history only claims ArrowUp and
-   * ArrowDown at these edges so arrows still move the caret inside multiline
-   * text.
-   */
-  isCaretOnVisualEdge: (edge: "start" | "end") => boolean;
-}
-
-interface ComposerPromptEditorProps {
-  value: string;
-  cursor: number;
-  /** Draft records behind the prompt's context references, keyed by context id. */
-  contextRecords: ComposerDraftContextRecords;
-  /** Structured clipboard payload for the given referenced ids, or null to skip. */
-  buildContextClipboardFragment?:
-    | ((contextIds: ReadonlyArray<string>) => string | null)
-    | undefined;
-  /** Imports a structured paste's records; returns ids that changed. */
-  importContextFragment?:
-    | ((fragment: ComposerContextClipboardFragment) => ReadonlyMap<string, string>)
-    | undefined;
-  skills: ReadonlyArray<ServerProviderSkill>;
-  disabled: boolean;
-  placeholder: string;
-  containerClassName?: string;
-  className?: string;
-  placeholderClassName?: string;
-  onChange: (
-    nextValue: string,
-    nextCursor: number,
-    expandedCursor: number,
-    cursorAdjacentToMention: boolean,
-    contextIds: string[],
-  ) => void;
-  onVisibleSelectionChange?: () => void;
-  onCommandKeyDown?: (
-    key: "ArrowDown" | "ArrowUp" | "Enter" | "Tab",
-    event: KeyboardEvent,
-  ) => boolean;
-  onPageScrollKeyDown?: (key: "PageUp" | "PageDown") => void;
-  onPageScrollKeyUp?: (key: string) => void;
-  onPageScrollRelease?: () => void;
-  onCitationSubmitAndSend?: () => void;
-  onPaste: React.ClipboardEventHandler<HTMLElement>;
-  editorRef: React.RefObject<ComposerPromptEditorHandle | null>;
-}
+export type {
+  ComposerCitationCommentRequest,
+  ComposerPromptEditorHandle,
+  ComposerPromptEditorProps,
+} from "./ComposerPromptEditorTiptap";
 
 /**
- * Client rect of the line the collapsed caret is on, as seen from `edge`.
- * A caret at a soft-wrap boundary belongs to two visual lines and the
- * range reports a rect for each, so take the one farthest from the edge
- * under test: an ambiguous caret then never claims the key and the arrow
- * moves the caret as usual. A collapsed range reports zero-height rects at
- * some positions, so probe the adjacent character on the same side. When
- * the range container is the paragraph itself (an empty line, or a caret
- * beside an inline chip) measure the child next to the caret before
- * falling back to the paragraph.
+ * The composer editor. Tiptap in both modes: the `richTextEnabled` setting
+ * toggles Markdown styling, never the engine. Plain mode renders every
+ * marker as a literal character and serializes byte-identically.
  */
-function caretLineRect(range: Range, edge: "start" | "end"): DOMRect | null {
-  const collapsedRects = Array.from(range.getClientRects()).filter((rect) => rect.height > 0);
-  const collapsedRect = edge === "start" ? collapsedRects.at(-1) : collapsedRects[0];
-  if (collapsedRect) return collapsedRect;
-
-  const container = range.startContainer;
-  if (container.nodeType === Node.TEXT_NODE) {
-    const textNode = container as Text;
-    if (textNode.data.length === 0) return null;
-    const probeStart = Math.max(
-      0,
-      Math.min(
-        edge === "start" ? range.startOffset : range.startOffset - 1,
-        textNode.data.length - 1,
-      ),
-    );
-    const probeRange = document.createRange();
-    probeRange.setStart(textNode, probeStart);
-    probeRange.setEnd(textNode, probeStart + 1);
-    const probeRect = Array.from(probeRange.getClientRects()).find((rect) => rect.height > 0);
-    if (probeRect) return probeRect;
-    const boundingRect = probeRange.getBoundingClientRect();
-    return boundingRect.height > 0 ? boundingRect : null;
-  }
-
-  if (!(container instanceof HTMLElement)) return null;
-  // The caret sits between the paragraph's children, which is where Lexical
-  // puts it next to an inline chip. Measure the neighbouring child.
-  const neighbour =
-    container.childNodes[Math.max(0, range.startOffset - 1)] ??
-    container.childNodes[range.startOffset];
-  if (neighbour instanceof HTMLElement) {
-    const neighbourRect = neighbour.getBoundingClientRect();
-    if (neighbourRect.height > 0) return neighbourRect;
-  } else if (neighbour instanceof Text && neighbour.data.length > 0) {
-    // Probe the character on the caret's side. A soft-wrapped text node's
-    // first rect is its first visual line, which may not be the caret's.
-    const isBeforeCaret = neighbour === container.childNodes[range.startOffset - 1];
-    const probeStart = isBeforeCaret ? neighbour.data.length - 1 : 0;
-    const probeRange = document.createRange();
-    probeRange.setStart(neighbour, probeStart);
-    probeRange.setEnd(neighbour, probeStart + 1);
-    const probeRect = Array.from(probeRange.getClientRects()).find((rect) => rect.height > 0);
-    if (probeRect) return probeRect;
-  }
-  const containerRect = container.getBoundingClientRect();
-  return containerRect.height > 0 ? containerRect : null;
-}
-
-function ComposerCommandKeyPlugin(props: {
-  onCommandKeyDown?: (
-    key: "ArrowDown" | "ArrowUp" | "Enter" | "Tab",
-    event: KeyboardEvent,
-  ) => boolean;
-}) {
-  const [editor] = useLexicalComposerContext();
-
-  useEffect(() => {
-    const handleCommand = (
-      key: "ArrowDown" | "ArrowUp" | "Enter" | "Tab",
-      event: KeyboardEvent | null,
-    ): boolean => {
-      if (!props.onCommandKeyDown || !event) {
-        return false;
-      }
-
-      if (key === "Enter" && (event.isComposing || event.keyCode === 229)) {
-        event.stopPropagation();
-        return true;
-      }
-
-      const handled = props.onCommandKeyDown(key, event);
-      if (handled) {
-        event.preventDefault();
-        event.stopPropagation();
-      }
-      return handled;
-    };
-
-    const unregisterArrowDown = editor.registerCommand(
-      KEY_ARROW_DOWN_COMMAND,
-      (event) => handleCommand("ArrowDown", event),
-      COMMAND_PRIORITY_HIGH,
-    );
-    const unregisterArrowUp = editor.registerCommand(
-      KEY_ARROW_UP_COMMAND,
-      (event) => handleCommand("ArrowUp", event),
-      COMMAND_PRIORITY_HIGH,
-    );
-    const unregisterEnter = editor.registerCommand(
-      KEY_ENTER_COMMAND,
-      (event) => handleCommand("Enter", event),
-      COMMAND_PRIORITY_HIGH,
-    );
-    const unregisterTab = editor.registerCommand(
-      KEY_TAB_COMMAND,
-      (event) => handleCommand("Tab", event),
-      COMMAND_PRIORITY_HIGH,
-    );
-
-    return () => {
-      unregisterArrowDown();
-      unregisterArrowUp();
-      unregisterEnter();
-      unregisterTab();
-    };
-  }, [editor, props]);
-
-  return null;
-}
-
-function ComposerInlineTokenArrowPlugin() {
-  const [editor] = useLexicalComposerContext();
-
-  useEffect(() => {
-    const unregisterLeft = editor.registerCommand(
-      KEY_ARROW_LEFT_COMMAND,
-      (event) => {
-        let nextOffset: number | null = null;
-        editor.getEditorState().read(() => {
-          const selection = $getSelection();
-          if (!$isRangeSelection(selection) || !selection.isCollapsed()) return;
-          const currentOffset = $readSelectionOffsetFromEditorState(0);
-          if (currentOffset <= 0) return;
-          const promptValue = $getRoot().getTextContent();
-          if (!isCollapsedCursorAdjacentToInlineToken(promptValue, currentOffset, "left")) {
-            return;
-          }
-          nextOffset = currentOffset - 1;
-        });
-        if (nextOffset === null) return false;
-        const selectionOffset = nextOffset;
-        event?.preventDefault();
-        event?.stopPropagation();
-        editor.update(() => {
-          $setSelectionAtComposerOffset(selectionOffset);
-        });
-        return true;
-      },
-      COMMAND_PRIORITY_HIGH,
-    );
-    const unregisterRight = editor.registerCommand(
-      KEY_ARROW_RIGHT_COMMAND,
-      (event) => {
-        let nextOffset: number | null = null;
-        editor.getEditorState().read(() => {
-          const selection = $getSelection();
-          if (!$isRangeSelection(selection) || !selection.isCollapsed()) return;
-          const currentOffset = $readSelectionOffsetFromEditorState(0);
-          const composerLength = $getComposerRootLength();
-          if (currentOffset >= composerLength) return;
-          const promptValue = $getRoot().getTextContent();
-          if (!isCollapsedCursorAdjacentToInlineToken(promptValue, currentOffset, "right")) {
-            return;
-          }
-          nextOffset = currentOffset + 1;
-        });
-        if (nextOffset === null) return false;
-        const selectionOffset = nextOffset;
-        event?.preventDefault();
-        event?.stopPropagation();
-        editor.update(() => {
-          $setSelectionAtComposerOffset(selectionOffset);
-        });
-        return true;
-      },
-      COMMAND_PRIORITY_HIGH,
-    );
-    return () => {
-      unregisterLeft();
-      unregisterRight();
-    };
-  }, [editor]);
-
-  return null;
-}
-
-function ComposerHomeEndKeyPlugin() {
-  const [editor] = useLexicalComposerContext();
-
-  useEffect(() => {
-    return editor.registerCommand(
-      KEY_DOWN_COMMAND,
-      (event) => {
-        if (!isMacPlatform(navigator.platform)) {
-          return false;
-        }
-        if (event.key !== "Home" && event.key !== "End") {
-          return false;
-        }
-        if (event.altKey || event.metaKey || event.ctrlKey || event.isComposing) {
-          return false;
-        }
-
-        const rootElement = editor.getRootElement();
-        const selection = window.getSelection();
-        const anchorNode = selection?.anchorNode;
-        if (!rootElement || !selection || !anchorNode || !rootElement.contains(anchorNode)) {
-          return false;
-        }
-        if (selection.rangeCount === 0 || typeof selection.modify !== "function") {
-          return false;
-        }
-
-        event.preventDefault();
-        event.stopPropagation();
-
-        selection.modify(
-          event.shiftKey ? "extend" : "move",
-          event.key === "Home" ? "backward" : "forward",
-          "lineboundary",
-        );
-        editor.update(() => {
-          $setSelection($createRangeSelectionFromDom(selection, editor));
-        });
-        return true;
-      },
-      COMMAND_PRIORITY_HIGH,
-    );
-  }, [editor]);
-
-  return null;
-}
-
-function ComposerInlineTokenSelectionNormalizePlugin() {
-  const [editor] = useLexicalComposerContext();
-
-  useEffect(() => {
-    return editor.registerUpdateListener(({ editorState }) => {
-      let afterOffset: number | null = null;
-      editorState.read(() => {
-        const selection = $getSelection();
-        if (!$isRangeSelection(selection) || !selection.isCollapsed()) return;
-        const anchorNode = selection.anchor.getNode();
-        if (!isComposerInlineTokenNode(anchorNode)) return;
-        if (selection.anchor.offset === 0) return;
-        const beforeOffset = getAbsoluteOffsetForPoint(anchorNode, 0);
-        afterOffset = beforeOffset + 1;
-      });
-      if (afterOffset !== null) {
-        queueMicrotask(() => {
-          editor.update(() => {
-            $setSelectionAtComposerOffset(afterOffset!);
-          });
-        });
-      }
-    });
-  }, [editor]);
-
-  return null;
-}
-
-function ComposerInlineTokenBackspacePlugin() {
-  const [editor] = useLexicalComposerContext();
-
-  useEffect(() => {
-    return editor.registerCommand(
-      KEY_BACKSPACE_COMMAND,
-      (event) => {
-        const selection = $getSelection();
-        if (!$isRangeSelection(selection) || !selection.isCollapsed()) {
-          return false;
-        }
-
-        const anchorNode = selection.anchor.getNode();
-        const removeInlineTokenNode = (candidate: unknown): boolean => {
-          if (!isComposerInlineTokenNode(candidate)) {
-            return false;
-          }
-          const tokenStart = getAbsoluteOffsetForPoint(candidate, 0);
-          candidate.remove();
-          $setSelectionAtComposerOffset(tokenStart);
-          event?.preventDefault();
-          return true;
-        };
-        if (removeInlineTokenNode(anchorNode)) {
-          return true;
-        }
-
-        if ($isTextNode(anchorNode)) {
-          if (selection.anchor.offset > 0) {
-            return false;
-          }
-          if (removeInlineTokenNode(anchorNode.getPreviousSibling())) {
-            return true;
-          }
-          const parent = anchorNode.getParent();
-          if ($isElementNode(parent)) {
-            const index = anchorNode.getIndexWithinParent();
-            if (index > 0 && removeInlineTokenNode(parent.getChildAtIndex(index - 1))) {
-              return true;
-            }
-          }
-          return false;
-        }
-
-        if ($isElementNode(anchorNode)) {
-          const childIndex = selection.anchor.offset - 1;
-          if (childIndex >= 0 && removeInlineTokenNode(anchorNode.getChildAtIndex(childIndex))) {
-            return true;
-          }
-        }
-
-        return false;
-      },
-      COMMAND_PRIORITY_HIGH,
-    );
-  }, [editor]);
-
-  return null;
-}
-
-/**
- * Chips render as non-editable decorators, so the browser never paints the
- * native text selection over them; without help, a selection spanning chips
- * is only visible in the slivers between them. Mirror the selection onto the
- * chips with a data attribute the stylesheet turns into a highlight overlay.
- */
-function ComposerChipSelectionPlugin() {
-  const [editor] = useLexicalComposerContext();
-
-  useEffect(() => {
-    let selectedKeys = new Set<string>();
-    // Lexical keeps the range selection on blur without emitting an update,
-    // so focus is tracked separately; while blurred the native highlight is
-    // gone and the mirrored one has to go with it.
-    let hasFocus = editor.getRootElement() === document.activeElement;
-
-    const applyKeys = (nextKeys: Set<string>) => {
-      for (const key of selectedKeys) {
-        if (!nextKeys.has(key)) {
-          editor.getElementByKey(key)?.removeAttribute("data-composer-chip-selected");
-        }
-      }
-      for (const key of nextKeys) {
-        editor.getElementByKey(key)?.setAttribute("data-composer-chip-selected", "true");
-      }
-      selectedKeys = nextKeys;
-    };
-
-    const readSelectedKeys = () => {
-      const nextKeys = new Set<string>();
-      editor.getEditorState().read(() => {
-        const selection = $getSelection();
-        if ($isRangeSelection(selection) && !selection.isCollapsed()) {
-          for (const node of selection.getNodes()) {
-            if (node instanceof DecoratorNode) {
-              nextKeys.add(node.getKey());
-            }
-          }
-        }
-      });
-      return nextKeys;
-    };
-
-    const unregisterUpdate = editor.registerUpdateListener(() => {
-      applyKeys(hasFocus ? readSelectedKeys() : new Set());
-    });
-    const unregisterFocus = editor.registerCommand(
-      FOCUS_COMMAND,
-      () => {
-        hasFocus = true;
-        applyKeys(readSelectedKeys());
-        return false;
-      },
-      COMMAND_PRIORITY_LOW,
-    );
-    const unregisterBlur = editor.registerCommand(
-      BLUR_COMMAND,
-      () => {
-        hasFocus = false;
-        applyKeys(new Set());
-        return false;
-      },
-      COMMAND_PRIORITY_LOW,
-    );
-    return () => {
-      unregisterUpdate();
-      unregisterFocus();
-      unregisterBlur();
-    };
-  }, [editor]);
-
-  return null;
-}
-
-function ComposerInlineTokenPastePlugin(props: {
-  importContextFragment?: ComposerPromptEditorProps["importContextFragment"];
-}) {
-  const [editor] = useLexicalComposerContext();
-  const importContextFragment = props.importContextFragment;
-
-  useEffect(
-    () =>
-      registerComposerInlineTokenPaste(editor, {
-        createMentionNode: $createComposerMentionNode,
-        createCitationNode: $createComposerCitationNode,
-        createContextReferenceNode: $createComposerContextReferenceNode,
-        getExpandedAbsoluteOffsetForPoint,
-        ...(importContextFragment ? { importContextFragment } : {}),
-      }),
-    [editor, importContextFragment],
-  );
-
-  return null;
-}
-
-/**
- * Copying chips must carry their payloads: the default copy writes the canonical links as
- * text, and this adds the structured fragment for the referenced records beside it.
- */
-function ComposerContextClipboardPlugin(props: {
-  buildContextClipboardFragment?: ComposerPromptEditorProps["buildContextClipboardFragment"];
-}) {
-  const [editor] = useLexicalComposerContext();
-  const build = props.buildContextClipboardFragment;
-
-  useEffect(() => {
-    if (!build) return;
-    const listener = (event: ClipboardEvent | KeyboardEvent | null, cut: boolean) => {
-      if (!event || !("clipboardData" in event) || !event.clipboardData) return false;
-      const selection = $getSelection();
-      if (!$isRangeSelection(selection) || selection.isCollapsed()) return false;
-      const text = selection.getTextContent();
-      const contextIds = collectInlineContextIds(text);
-      if (contextIds.length === 0) return false;
-      const fragment = build(contextIds);
-      if (!fragment) return false;
-      event.preventDefault();
-      event.clipboardData.setData("text/plain", text);
-      event.clipboardData.setData(COMPOSER_CONTEXT_CLIPBOARD_MIME, fragment);
-      event.clipboardData.setData("text/html", encodeComposerContextClipboardHtml(text, fragment));
-      if (cut) selection.removeText();
-      return true;
-    };
-    const unregisterCopy = editor.registerCommand(
-      COPY_COMMAND,
-      (event) => listener(event, false),
-      COMMAND_PRIORITY_HIGH,
-    );
-    const unregisterCut = editor.registerCommand(
-      CUT_COMMAND,
-      (event) => listener(event, true),
-      COMMAND_PRIORITY_HIGH,
-    );
-    return () => {
-      unregisterCopy();
-      unregisterCut();
-    };
-  }, [build, editor]);
-
-  return null;
-}
-
-function ComposerSurroundSelectionPlugin(props: { skills: ReadonlyArray<ServerProviderSkill> }) {
-  const [editor] = useLexicalComposerContext();
-  const skillMetadataRef = useRef(skillMetadataByName(props.skills));
-  const pendingSurroundSelectionRef = useRef<{
-    value: string;
-    expandedStart: number;
-    expandedEnd: number;
-  } | null>(null);
-  const pendingDeadKeySelectionRef = useRef<{
-    value: string;
-    expandedStart: number;
-    expandedEnd: number;
-  } | null>(null);
-
-  useEffect(() => {
-    skillMetadataRef.current = skillMetadataByName(props.skills);
-  }, [props.skills]);
-
-  const applySurroundInsertion = useEffectEvent((inputData: string): boolean => {
-    const surroundCloseSymbol = SURROUND_SYMBOLS_MAP.get(inputData);
-    const pendingSurroundSelection = pendingSurroundSelectionRef.current;
-    if (!surroundCloseSymbol) {
-      pendingSurroundSelectionRef.current = null;
-      return false;
-    }
-
-    let handled = false;
-    editor.update(() => {
-      const selectionSnapshot =
-        pendingSurroundSelection ??
-        (() => {
-          const selection = $getSelection();
-          if (!$isRangeSelection(selection) || selection.isCollapsed()) {
-            return null;
-          }
-          if ($selectionTouchesInlineToken(selection)) {
-            return null;
-          }
-          const range = getSelectionRangeForExpandedComposerOffsets(selection);
-          if (!range || range.start === range.end) {
-            return null;
-          }
-          const value = $getRoot().getTextContent();
-          if (selectionTouchesMentionBoundary(value, range.start, range.end)) {
-            return null;
-          }
-          return {
-            value,
-            expandedStart: range.start,
-            expandedEnd: range.end,
-          };
-        })();
-
-      if (!selectionSnapshot || !surroundCloseSymbol) {
-        return;
-      }
-
-      const selectedText = selectionSnapshot.value.slice(
-        selectionSnapshot.expandedStart,
-        selectionSnapshot.expandedEnd,
-      );
-      const nextValue = `${selectionSnapshot.value.slice(0, selectionSnapshot.expandedStart)}${inputData}${selectedText}${surroundCloseSymbol}${selectionSnapshot.value.slice(selectionSnapshot.expandedEnd)}`;
-      $setComposerEditorPrompt(nextValue, skillMetadataRef.current);
-      const selectionStart = collapseExpandedComposerCursor(
-        nextValue,
-        selectionSnapshot.expandedStart,
-      );
-      $setSelectionRangeAtComposerOffsets(
-        selectionStart + inputData.length,
-        selectionStart + inputData.length + selectedText.length,
-      );
-      handled = true;
-      pendingSurroundSelectionRef.current = null;
-    });
-
-    return handled;
-  });
-
-  useEffect(() => {
-    const onKeyDown = (event: KeyboardEvent) => {
-      if (pendingDeadKeySelectionRef.current) {
-        if (event.key === "Dead" || event.key === " " || event.code === "Space") {
-          return;
-        }
-        pendingDeadKeySelectionRef.current = null;
-      }
-
-      if (event.defaultPrevented || event.isComposing || event.metaKey || event.ctrlKey) {
-        pendingSurroundSelectionRef.current = null;
-        pendingDeadKeySelectionRef.current = null;
-        return;
-      }
-
-      editor.getEditorState().read(() => {
-        const selection = $getSelection();
-        if (!$isRangeSelection(selection) || selection.isCollapsed()) {
-          pendingSurroundSelectionRef.current = null;
-          pendingDeadKeySelectionRef.current = null;
-          return;
-        }
-        if ($selectionTouchesInlineToken(selection)) {
-          pendingSurroundSelectionRef.current = null;
-          pendingDeadKeySelectionRef.current = null;
-          return;
-        }
-        const range = getSelectionRangeForExpandedComposerOffsets(selection);
-        if (!range || range.start === range.end) {
-          pendingSurroundSelectionRef.current = null;
-          pendingDeadKeySelectionRef.current = null;
-          return;
-        }
-        const value = $getRoot().getTextContent();
-        if (selectionTouchesMentionBoundary(value, range.start, range.end)) {
-          pendingSurroundSelectionRef.current = null;
-          pendingDeadKeySelectionRef.current = null;
-          return;
-        }
-        const snapshot = {
-          value,
-          expandedStart: range.start,
-          expandedEnd: range.end,
-        };
-        pendingSurroundSelectionRef.current = snapshot;
-        pendingDeadKeySelectionRef.current = null;
-      });
-    };
-
-    const onBeforeInput = (event: InputEvent) => {
-      if (
-        event.inputType === "insertCompositionText" &&
-        event.data === "`" &&
-        BACKTICK_SURROUND_CLOSE_SYMBOL !== null &&
-        pendingSurroundSelectionRef.current
-      ) {
-        pendingDeadKeySelectionRef.current = pendingSurroundSelectionRef.current;
-        return;
-      }
-
-      if (pendingDeadKeySelectionRef.current) {
-        return;
-      }
-
-      if (event.inputType === "insertCompositionText") {
-        return;
-      }
-
-      if (typeof event.data !== "string") {
-        pendingSurroundSelectionRef.current = null;
-        return;
-      }
-      const inputData = event.inputType === "insertText" ? event.data : null;
-      if (!inputData || inputData.length !== 1) {
-        pendingSurroundSelectionRef.current = null;
-        return;
-      }
-      if (!applySurroundInsertion(inputData)) {
-        return;
-      }
-
-      event.preventDefault();
-      event.stopPropagation();
-      event.stopImmediatePropagation();
-    };
-
-    const tryApplyDeadKeyBacktickSurround = (options?: { finalAttempt?: boolean }) => {
-      queueMicrotask(() => {
-        editor.update(
-          () => {
-            const pendingDeadKeySelection = pendingDeadKeySelectionRef.current;
-            if (!pendingDeadKeySelection) {
-              return;
-            }
-
-            const currentValue = $getRoot().getTextContent();
-            const backtickCloseSymbol = BACKTICK_SURROUND_CLOSE_SYMBOL;
-            if (backtickCloseSymbol === null) {
-              pendingDeadKeySelectionRef.current = null;
-              return;
-            }
-
-            const expectedResolvedValue = `${pendingDeadKeySelection.value.slice(0, pendingDeadKeySelection.expandedStart)}\`${pendingDeadKeySelection.value.slice(pendingDeadKeySelection.expandedEnd)}`;
-            if (currentValue !== expectedResolvedValue) {
-              if (options?.finalAttempt) {
-                pendingSurroundSelectionRef.current = null;
-                pendingDeadKeySelectionRef.current = null;
-              }
-              return;
-            }
-
-            const selectedText = pendingDeadKeySelection.value.slice(
-              pendingDeadKeySelection.expandedStart,
-              pendingDeadKeySelection.expandedEnd,
-            );
-            const replacementStart = collapseExpandedComposerCursor(
-              currentValue,
-              pendingDeadKeySelection.expandedStart,
-            );
-            $setSelectionRangeAtComposerOffsets(replacementStart, replacementStart + 1);
-            const replacementSelection = $getSelection();
-            if (!$isRangeSelection(replacementSelection)) {
-              pendingSurroundSelectionRef.current = null;
-              pendingDeadKeySelectionRef.current = null;
-              return;
-            }
-            replacementSelection.insertText(`\`${selectedText}${backtickCloseSymbol}`);
-            $setSelectionRangeAtComposerOffsets(
-              replacementStart + 1,
-              replacementStart + 1 + selectedText.length,
-            );
-            pendingSurroundSelectionRef.current = null;
-            pendingDeadKeySelectionRef.current = null;
-          },
-          { tag: HISTORY_MERGE_TAG },
-        );
-      });
-    };
-
-    const onInput = (event: Event) => {
-      const inputEvent = event as InputEvent;
-      if (
-        inputEvent.inputType === "insertText" ||
-        inputEvent.inputType === "insertCompositionText"
-      ) {
-        tryApplyDeadKeyBacktickSurround();
-      }
-    };
-
-    const onCompositionEnd = () => {
-      tryApplyDeadKeyBacktickSurround({ finalAttempt: true });
-    };
-
-    let activeRootElement: HTMLElement | null = null;
-    const unregisterRootListener = editor.registerRootListener((rootElement, prevRootElement) => {
-      prevRootElement?.removeEventListener("keydown", onKeyDown);
-      prevRootElement?.removeEventListener("beforeinput", onBeforeInput, true);
-      prevRootElement?.removeEventListener("input", onInput);
-      prevRootElement?.removeEventListener("compositionend", onCompositionEnd);
-      rootElement?.addEventListener("keydown", onKeyDown);
-      rootElement?.addEventListener("beforeinput", onBeforeInput, true);
-      rootElement?.addEventListener("input", onInput);
-      rootElement?.addEventListener("compositionend", onCompositionEnd);
-      activeRootElement = rootElement;
-    });
-
-    return () => {
-      if (activeRootElement) {
-        activeRootElement.removeEventListener("keydown", onKeyDown);
-        activeRootElement.removeEventListener("beforeinput", onBeforeInput, true);
-        activeRootElement.removeEventListener("input", onInput);
-        activeRootElement.removeEventListener("compositionend", onCompositionEnd);
-      }
-      unregisterRootListener();
-    };
-  }, [editor]);
-
-  return null;
-}
-
-function ComposerPromptEditorInner({
-  value,
-  cursor,
-  contextRecords,
-  buildContextClipboardFragment,
-  importContextFragment,
-  skills,
-  disabled,
-  placeholder,
-  containerClassName,
-  className,
-  placeholderClassName,
-  onChange,
-  onVisibleSelectionChange,
-  onCommandKeyDown,
-  onPageScrollKeyDown,
-  onPageScrollKeyUp,
-  onPageScrollRelease,
-  onCitationSubmitAndSend,
-  onPaste,
-  editorRef,
-}: ComposerPromptEditorProps) {
-  const [editor] = useLexicalComposerContext();
-  const onChangeRef = useRef(onChange);
-  const onVisibleSelectionChangeRef = useRef(onVisibleSelectionChange);
-  const initialCursor = clampCollapsedComposerCursor(value, cursor);
-  const initialExpandedCursor = expandCollapsedComposerCursor(value, initialCursor);
-  const skillsSignature = skillSignature(skills);
-  const skillsSignatureRef = useRef(skillsSignature);
-  const skillMetadataRef = useRef(skillMetadataByName(skills));
-  const snapshotRef = useRef({
-    value,
-    cursor: initialCursor,
-    expandedCursor: initialExpandedCursor,
-    contextIds: collectInlineContextIds(value),
-  });
-  const selectionRangeRef = useRef({ start: initialExpandedCursor, end: initialExpandedCursor });
-  const isApplyingControlledUpdateRef = useRef(false);
-  // Latest controlled value, readable from editor listeners that fire before the layout
-  // effect has rewritten the editor to match it.
-  const latestValueRef = useRef(value);
-  useLayoutEffect(() => {
-    latestValueRef.current = value;
-  }, [value]);
-  const citationCommentRequestRef = useRef<ComposerCitationCommentRequest | null>(null);
-  const [openCitationComment, setOpenCitationComment] =
-    useState<ComposerCitationCommentTarget | null>(null);
-  const citationCommentActions = useMemo(
-    () => ({
-      openComment: openCitationComment,
-      onOpenChange: (nodeKey: NodeKey, open: boolean) => {
-        setOpenCitationComment((current) =>
-          open ? { nodeKey } : current?.nodeKey === nodeKey ? null : current,
-        );
-      },
-      onSubmitAndSend: onCitationSubmitAndSend ?? (() => {}),
-    }),
-    [onCitationSubmitAndSend, openCitationComment],
-  );
-
-  useEffect(() => {
-    onChangeRef.current = onChange;
-  }, [onChange]);
-
-  useEffect(() => {
-    onVisibleSelectionChangeRef.current = onVisibleSelectionChange;
-  }, [onVisibleSelectionChange]);
-
-  useLayoutEffect(() => {
-    skillMetadataRef.current = skillMetadataByName(skills);
-  }, [skills]);
-
-  useEffect(() => {
-    editor.setEditable(!disabled);
-  }, [disabled, editor]);
-
-  useEffect(() => {
-    const openCitationNodeKey = openCitationComment?.nodeKey;
-    if (!openCitationNodeKey) return;
-    return editor.registerUpdateListener(({ editorState }) => {
-      const isAttached = editorState.read(() => {
-        const node = $getNodeByKey(openCitationNodeKey);
-        return node instanceof ComposerCitationNode && node.isAttached();
-      });
-      if (!isAttached) {
-        setOpenCitationComment((current) =>
-          current?.nodeKey === openCitationNodeKey ? null : current,
-        );
-      }
-    });
-  }, [editor, openCitationComment?.nodeKey]);
-
-  useLayoutEffect(() => {
-    const normalizedCursor = clampCollapsedComposerCursor(value, cursor);
-    const previousSnapshot = snapshotRef.current;
-    const skillsChanged = skillsSignatureRef.current !== skillsSignature;
-    if (
-      previousSnapshot.value === value &&
-      previousSnapshot.cursor === normalizedCursor &&
-      !skillsChanged
-    ) {
-      return;
-    }
-
-    const normalizedExpandedCursor = expandCollapsedComposerCursor(value, normalizedCursor);
-    snapshotRef.current = {
-      value,
-      cursor: normalizedCursor,
-      expandedCursor: normalizedExpandedCursor,
-      contextIds: collectInlineContextIds(value),
-    };
-    selectionRangeRef.current = {
-      start: normalizedExpandedCursor,
-      end: normalizedExpandedCursor,
-    };
-    skillsSignatureRef.current = skillsSignature;
-
-    const rootElement = editor.getRootElement();
-    const isFocused = Boolean(rootElement && document.activeElement === rootElement);
-    if (previousSnapshot.value === value && !skillsChanged && !isFocused) {
-      return;
-    }
-
-    isApplyingControlledUpdateRef.current = true;
-    const isCiteInsertion = citationCommentRequestRef.current?.value === value;
-    let citationToOpen: ComposerCitationCommentTarget | null = null;
-    editor.update(
-      () => {
-        const shouldRewriteEditorState = previousSnapshot.value !== value || skillsChanged;
-        if (shouldRewriteEditorState) {
-          $setComposerEditorPrompt(value, skillMetadataRef.current);
-        }
-        if (shouldRewriteEditorState || isFocused) {
-          $setSelectionAtComposerOffset(normalizedCursor);
-        }
-        citationToOpen = $consumeComposerCitationCommentRequest(citationCommentRequestRef);
-      },
-      {
-        ...(isCiteInsertion ? { tag: [HISTORY_PUSH_TAG, SKIP_DOM_SELECTION_TAG] } : {}),
-        onUpdate: () => {
-          if (citationToOpen) setOpenCitationComment(citationToOpen);
-        },
-      },
-    );
-    queueMicrotask(() => {
-      isApplyingControlledUpdateRef.current = false;
-    });
-  }, [cursor, editor, skillsSignature, value]);
-
-  const focusAt = useCallback(
-    (nextCursor: number) => {
-      const rootElement = editor.getRootElement();
-      if (!rootElement) return;
-      rootElement.focus({ preventScroll: true });
-      // A newer prompt is waiting to be applied (a chip was just inserted through the store).
-      // Reporting the editor's stale text now would overwrite that prompt; the pending rewrite
-      // places the caret from the store's cursor instead.
-      if (snapshotRef.current.value !== latestValueRef.current) return;
-      const boundedCursor = clampCollapsedComposerCursor(snapshotRef.current.value, nextCursor);
-      editor.update(() => {
-        $setSelectionAtComposerOffset(boundedCursor);
-      });
-      if (boundedCursor === snapshotRef.current.cursor) return;
-      snapshotRef.current = {
-        value: snapshotRef.current.value,
-        cursor: boundedCursor,
-        expandedCursor: expandCollapsedComposerCursor(snapshotRef.current.value, boundedCursor),
-        contextIds: snapshotRef.current.contextIds,
-      };
-      selectionRangeRef.current = {
-        start: snapshotRef.current.expandedCursor,
-        end: snapshotRef.current.expandedCursor,
-      };
-      onChangeRef.current(
-        snapshotRef.current.value,
-        boundedCursor,
-        snapshotRef.current.expandedCursor,
-        false,
-        snapshotRef.current.contextIds,
-      );
-    },
-    [editor],
-  );
-
-  const readSnapshot = useCallback((): {
-    value: string;
-    cursor: number;
-    expandedCursor: number;
-    contextIds: string[];
-  } => {
-    let snapshot = snapshotRef.current;
-    editor.getEditorState().read(() => {
-      const nextValue = $getRoot().getTextContent();
-      const fallbackCursor = clampCollapsedComposerCursor(nextValue, snapshotRef.current.cursor);
-      const nextCursor = clampCollapsedComposerCursor(
-        nextValue,
-        $readSelectionOffsetFromEditorState(fallbackCursor),
-      );
-      const fallbackExpandedCursor = clampExpandedCursor(
-        nextValue,
-        snapshotRef.current.expandedCursor,
-      );
-      const nextExpandedCursor = clampExpandedCursor(
-        nextValue,
-        $readExpandedSelectionOffsetFromEditorState(fallbackExpandedCursor),
-      );
-      const selectionRange = getSelectionRangeForExpandedComposerOffsets($getSelection());
-      const contextIds = collectContextIds($getRoot());
-      snapshot = {
-        value: nextValue,
-        cursor: nextCursor,
-        expandedCursor: nextExpandedCursor,
-        contextIds,
-      };
-      selectionRangeRef.current = selectionRange ?? {
-        start: nextExpandedCursor,
-        end: nextExpandedCursor,
-      };
-    });
-    snapshotRef.current = snapshot;
-    return snapshot;
-  }, [editor]);
-
-  useImperativeHandle(
-    editorRef,
-    () => ({
-      focus: () => {
-        focusAt(snapshotRef.current.cursor);
-      },
-      focusAt,
-      focusAtEnd: () => {
-        focusAt(
-          collapseExpandedComposerCursor(
-            snapshotRef.current.value,
-            snapshotRef.current.value.length,
-          ),
-        );
-      },
-      readSelectionRange: () => {
-        readSnapshot();
-        return selectionRangeRef.current;
-      },
-      requestCitationComment: (request) => {
-        citationCommentRequestRef.current = request;
-        const target = editor
-          .getEditorState()
-          .read(() => $consumeComposerCitationCommentRequest(citationCommentRequestRef));
-        if (target) setOpenCitationComment(target);
-      },
-      readSnapshot,
-      isCaretOnVisualEdge: (edge) => {
-        const snapshot = readSnapshot();
-        if (snapshot.value.length === 0) return true;
-        const beforeCaret = snapshot.value.slice(0, snapshot.expandedCursor);
-        const afterCaret = snapshot.value.slice(snapshot.expandedCursor);
-        if (edge === "start" ? beforeCaret.includes("\n") : afterCaret.includes("\n")) {
-          return false;
-        }
-        const rootElement = editor.getRootElement();
-        const selection = window.getSelection();
-        if (
-          !rootElement ||
-          !selection ||
-          !selection.isCollapsed ||
-          selection.rangeCount === 0 ||
-          !selection.anchorNode ||
-          !rootElement.contains(selection.anchorNode)
-        ) {
-          return false;
-        }
-        const caretRect = caretLineRect(selection.getRangeAt(0), edge);
-        if (!caretRect) return false;
-        const edgeElement =
-          edge === "start" ? rootElement.firstElementChild : rootElement.lastElementChild;
-        const edgeRect = (edgeElement ?? rootElement).getBoundingClientRect();
-        const threshold = caretRect.height / 2;
-        return edge === "start"
-          ? caretRect.top - edgeRect.top < threshold
-          : edgeRect.bottom - caretRect.bottom < threshold;
-      },
-    }),
-    [editor, focusAt, readSnapshot],
-  );
-
-  const handleEditorChange = useCallback((editorState: EditorState) => {
-    editorState.read(() => {
-      const nextValue = $getRoot().getTextContent();
-      const fallbackCursor = clampCollapsedComposerCursor(nextValue, snapshotRef.current.cursor);
-      const nextCursor = clampCollapsedComposerCursor(
-        nextValue,
-        $readSelectionOffsetFromEditorState(fallbackCursor),
-      );
-      const fallbackExpandedCursor = clampExpandedCursor(
-        nextValue,
-        snapshotRef.current.expandedCursor,
-      );
-      const nextExpandedCursor = clampExpandedCursor(
-        nextValue,
-        $readExpandedSelectionOffsetFromEditorState(fallbackExpandedCursor),
-      );
-      const nextSelectionRange = getSelectionRangeForExpandedComposerOffsets($getSelection());
-      const previousSelectionRange = selectionRangeRef.current;
-      selectionRangeRef.current = nextSelectionRange ?? {
-        start: nextExpandedCursor,
-        end: nextExpandedCursor,
-      };
-      const contextIds = collectContextIds($getRoot());
-      const previousSnapshot = snapshotRef.current;
-      const snapshotChanged = !(
-        previousSnapshot.value === nextValue &&
-        previousSnapshot.cursor === nextCursor &&
-        previousSnapshot.expandedCursor === nextExpandedCursor &&
-        previousSnapshot.contextIds.length === contextIds.length &&
-        previousSnapshot.contextIds.every((id, index) => id === contextIds[index])
-      );
-      if (isApplyingControlledUpdateRef.current) {
-        return;
-      }
-      if (!snapshotChanged) {
-        if (didComposerSelectionChangeVisibly(previousSelectionRange, nextSelectionRange)) {
-          onVisibleSelectionChangeRef.current?.();
-        }
-        return;
-      }
-      // A selection-only update while a newer prompt waits to be applied (an attachment
-      // chip was just inserted through the store) would report stale text and stale
-      // context ids, clobbering the prompt and dropping the record. Let the rewrite land.
-      if (previousSnapshot.value === nextValue && nextValue !== latestValueRef.current) {
-        return;
-      }
-      snapshotRef.current = {
-        value: nextValue,
-        cursor: nextCursor,
-        expandedCursor: nextExpandedCursor,
-        contextIds,
-      };
-      const cursorAdjacentToMention =
-        isCollapsedCursorAdjacentToInlineToken(nextValue, nextCursor, "left") ||
-        isCollapsedCursorAdjacentToInlineToken(nextValue, nextCursor, "right");
-      onChangeRef.current(
-        nextValue,
-        nextCursor,
-        nextExpandedCursor,
-        cursorAdjacentToMention,
-        contextIds,
-      );
-    });
-  }, []);
-
-  return (
-    <ComposerContextRecordsContext value={contextRecords}>
-      <ComposerCitationCommentContext value={citationCommentActions}>
-        <div
-          className={cn(
-            "relative [font-family:var(--font-composer,var(--font-sans))] [font-size:var(--font-size-prompt,0.875rem)] [@media(max-width:39.999rem)_and_(pointer:coarse)]:[font-size:max(var(--font-size-prompt,1rem),16px)]",
-            containerClassName,
-          )}
-        >
-          <PlainTextPlugin
-            contentEditable={
-              <ContentEditable
-                className={cn(
-                  // The wrapper owns the appearance preference; keep everything else here.
-                  "block max-h-50 min-h-17.5 w-full overflow-y-auto whitespace-pre-wrap wrap-break-word bg-transparent leading-relaxed text-foreground focus:outline-none",
-                  className,
-                )}
-                data-testid="composer-editor"
-                aria-placeholder={placeholder}
-                placeholder={<span />}
-                onKeyDown={(event) => {
-                  if (
-                    event.key === "Control" ||
-                    event.key === "Meta" ||
-                    event.key === "Alt" ||
-                    event.key === "Shift"
-                  ) {
-                    onPageScrollRelease?.();
-                  }
-
-                  if (event.key !== "PageUp" && event.key !== "PageDown") {
-                    return;
-                  }
-
-                  const pageScrollKey = getTimelinePageScrollKey({
-                    altKey: event.altKey,
-                    clientHeight: event.currentTarget.clientHeight,
-                    ctrlKey: event.ctrlKey,
-                    defaultPrevented: event.defaultPrevented,
-                    isComposing: event.nativeEvent.isComposing,
-                    key: event.key,
-                    keyCode: event.keyCode,
-                    metaKey: event.metaKey,
-                    scrollHeight: event.currentTarget.scrollHeight,
-                    scrollTop: event.currentTarget.scrollTop,
-                    shiftKey: event.shiftKey,
-                  });
-                  if (!pageScrollKey) {
-                    onPageScrollRelease?.();
-                    return;
-                  }
-                  if (!onPageScrollKeyDown) {
-                    return;
-                  }
-
-                  event.preventDefault();
-                  onPageScrollKeyDown(pageScrollKey);
-                }}
-                onKeyUp={(event) => onPageScrollKeyUp?.(event.key)}
-                onBlur={onPageScrollRelease}
-                onPasteCapture={onPaste}
-              />
-            }
-            placeholder={
-              contextRecords.size > 0 ? null : (
-                <div
-                  className={cn(
-                    "pointer-events-none absolute inset-0 leading-relaxed text-placeholder/75",
-                    placeholderClassName,
-                  )}
-                >
-                  {placeholder}
-                </div>
-              )
-            }
-            ErrorBoundary={LexicalErrorBoundary}
-          />
-          <OnChangePlugin onChange={handleEditorChange} />
-          <ComposerCommandKeyPlugin {...(onCommandKeyDown ? { onCommandKeyDown } : {})} />
-          <ComposerSurroundSelectionPlugin skills={skills} />
-          <ComposerHomeEndKeyPlugin />
-          <ComposerInlineTokenArrowPlugin />
-          <ComposerInlineTokenSelectionNormalizePlugin />
-          <ComposerInlineTokenBackspacePlugin />
-          <ComposerInlineTokenPastePlugin importContextFragment={importContextFragment} />
-          <ComposerContextClipboardPlugin
-            buildContextClipboardFragment={buildContextClipboardFragment}
-          />
-          <ComposerChipSelectionPlugin />
-          <HistoryPlugin />
-        </div>
-      </ComposerCitationCommentContext>
-    </ComposerContextRecordsContext>
-  );
-}
-
-export function ComposerPromptEditor({
-  value,
-  cursor,
-  contextRecords,
-  buildContextClipboardFragment,
-  importContextFragment,
-  skills,
-  disabled,
-  placeholder,
-  containerClassName,
-  className,
-  placeholderClassName,
-  onChange,
-  onVisibleSelectionChange,
-  onCommandKeyDown,
-  onPageScrollKeyDown,
-  onPageScrollKeyUp,
-  onPageScrollRelease,
-  onCitationSubmitAndSend,
-  onPaste,
-  editorRef,
-}: ComposerPromptEditorProps) {
-  const initialValueRef = useRef(value);
-  const initialSkillMetadataRef = useRef(skillMetadataByName(skills));
-  const initialConfig = useMemo<InitialConfigType>(
-    () => ({
-      namespace: "t3tools-composer-editor",
-      editable: true,
-      nodes: [
-        ComposerMentionNode,
-        ComposerSkillNode,
-        ComposerCitationNode,
-        ComposerContextReferenceNode,
-      ],
-      editorState: () => {
-        $setComposerEditorPrompt(initialValueRef.current, initialSkillMetadataRef.current);
-      },
-      onError: (error) => {
-        throw error;
-      },
-    }),
-    [],
-  );
-
-  return (
-    <ComposerSkillsContext value={skills}>
-      <LexicalComposer key={COMPOSER_EDITOR_HMR_KEY} initialConfig={initialConfig}>
-        <ComposerPromptEditorInner
-          value={value}
-          cursor={cursor}
-          contextRecords={contextRecords}
-          buildContextClipboardFragment={buildContextClipboardFragment}
-          importContextFragment={importContextFragment}
-          skills={skills}
-          disabled={disabled}
-          placeholder={placeholder}
-          {...(containerClassName ? { containerClassName } : {})}
-          onChange={onChange}
-          {...(onVisibleSelectionChange ? { onVisibleSelectionChange } : {})}
-          onPaste={onPaste}
-          {...(onCitationSubmitAndSend ? { onCitationSubmitAndSend } : {})}
-          editorRef={editorRef}
-          {...(onCommandKeyDown ? { onCommandKeyDown } : {})}
-          {...(onPageScrollKeyDown ? { onPageScrollKeyDown } : {})}
-          {...(onPageScrollKeyUp ? { onPageScrollKeyUp } : {})}
-          {...(onPageScrollRelease ? { onPageScrollRelease } : {})}
-          {...(className ? { className } : {})}
-          {...(placeholderClassName ? { placeholderClassName } : {})}
-        />
-      </LexicalComposer>
-    </ComposerSkillsContext>
-  );
+export function ComposerPromptEditor(props: ComposerPromptEditorProps) {
+  return <ComposerPromptEditorTiptap {...props} />;

@@ -3970,6 +3975,31 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
       submitComposer(undefined, submissionIntent);
       return true;
     }
+    // List continuation and indentation run as store replacements so both
+    // composer modes behave (and serialize) identically.
+    if (key === "Enter" || (key === "Tab" && !event.shiftKey)) {

@@ -0,0 +1,1379 @@
+import { Extension, Node, wrappingInputRule, type JSONContent } from "@tiptap/core";
+import { TaskList } from "@tiptap/extension-task-list";
+import { ReactNodeViewRenderer, NodeViewWrapper, type NodeViewProps } from "@tiptap/react";
+import StarterKit from "@tiptap/starter-kit";
+import { type Node as ProseMirrorNode } from "@tiptap/pm/model";
+import { splitBlockKeepMarks } from "@tiptap/pm/commands";
+import { Plugin, PluginKey, TextSelection } from "@tiptap/pm/state";
+import { Decoration, DecorationSet } from "@tiptap/pm/view";
+import type {
+  AssistantCitation,
+  ComposerContextClipboardFragment,
+  ServerProviderSkill,
+} from "@t3tools/contracts";
+import {
+  serializeAssistantCitation,
+  withAssistantCitationComment,
+} from "@t3tools/shared/assistantCitations";
+import {
+  COMPOSER_CONTEXT_CLIPBOARD_MIME,
+  encodeComposerContextClipboardHtml,
+} from "@t3tools/shared/composerContextClipboard";
+import {
+  createContext,
+  use,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { EditorContent, useEditor } from "@tiptap/react";
+
+import {
+  clampCollapsedComposerCursor,
+  collapseExpandedComposerCursor,
+  expandCollapsedComposerCursor,
+  isCollapsedCursorAdjacentToInlineToken,
+} from "~/composer-logic";
+import {
+  collectComposerPromptInlineTokens,
+  selectionTouchesMentionBoundary,
+} from "~/composer-editor-mentions";
+import {
+  buildDocJson,
+  buildTiptapContent,
+  collapsedToFlat,
+  ComposerTaskItemExtension,
+  flatToCollapsed,
+  flatToMarkdown,
+  flatToPm,
+  pmToFlat,
+  serializeEditorDoc,
+  type SkillMeta,
+} from "~/composer-rich-text-doc";
+import { collectInlineContextIds } from "~/lib/composerContextReferences";
+import { cn, isMacPlatform } from "~/lib/utils";
+import { basenameOfPath } from "~/pierre-icons";
+import {
+  COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME,
+  COMPOSER_INLINE_CHIP_ICON_CLASS_NAME,
+  COMPOSER_INLINE_CHIP_LABEL_CLASS_NAME,
+  COMPOSER_INLINE_SKILL_CHIP_CLASS_NAME,
+  SKILL_CHIP_ICON_SVG,
+} from "./composerInlineChip";
+import { FILE_TAG_CHIP_CLASS_NAME, FileTagChipContent } from "./chat/FileTagChip";
+import { AssistantCitationChip } from "./chat/AssistantCitationChip";
+import { getTimelinePageScrollKey } from "./chat/pageScrollController";
+import { ContextChipPopover } from "./contextChipParts";
+import { Button } from "./ui/button";
+import {
+  ComposerContextActionsContext,
+  ComposerContextReferenceChip,
+  ComposerContextRecordsContext,
+} from "./composerContextPresentation";
+import type { AssistantCitationSourceAnchor } from "~/lib/assistantTextSelection";
+import { formatProviderSkillDisplayName } from "@t3tools/client-runtime/providerSkills";
+import { Tooltip, TooltipPopup, TooltipTrigger } from "./ui/tooltip";
+import { importPastedComposerText } from "./composerInlineTokenPaste";
+import { didComposerSelectionChangeVisibly } from "./composerSelection";
+import type { ComposerDraftContextRecords } from "./composerContextPresentation";
+
+export interface ComposerPromptEditorHandle {
+  focus: () => void;
+  focusAt: (cursor: number) => void;
+  focusAtEnd: () => void;
+  readSelectionRange: () => { start: number; end: number };
+  requestCitationComment: (request: ComposerCitationCommentRequest) => void;
+  readSnapshot: () => {
+    value: string;
+    cursor: number;
+    expandedCursor: number;
+    contextIds: string[];
+  };
+  /**
+   * True when a collapsed caret sits on the first ("start") or last ("end")
+   * visual line, counting soft wraps. Prompt history only claims ArrowUp and
+   * ArrowDown at these edges so arrows still move the caret inside multiline
+   * text.
+   */
+  isCaretOnVisualEdge: (edge: "start" | "end") => boolean;
+}
+
+export interface ComposerPromptEditorProps {
+  value: string;
+  cursor: number;
+  /**
+   * Render Markdown styling (bold, italic, code, strike, task checkboxes).
+   * Off renders the same Tiptap engine as plain text: every marker stays a
+   * literal character.
+   */
+  richTextEnabled?: boolean;
+  /** Draft records behind the prompt's context references, keyed by context id. */
+  contextRecords: ComposerDraftContextRecords;
+  /** Structured clipboard payload for the given referenced ids, or null to skip. */
+  buildContextClipboardFragment?:
+    | ((contextIds: ReadonlyArray<string>) => string | null)
+    | undefined;
+  /** Imports a structured paste's records; returns ids that changed. */
+  importContextFragment?:
+    | ((fragment: ComposerContextClipboardFragment) => ReadonlyMap<string, string>)
+    | undefined;
+  skills: ReadonlyArray<ServerProviderSkill>;
+  disabled: boolean;
+  placeholder: string;
+  containerClassName?: string;
+  className?: string;
+  placeholderClassName?: string;
+  onChange: (
+    nextValue: string,
+    nextCursor: number,
+    expandedCursor: number,
+    cursorAdjacentToMention: boolean,
+    contextIds: string[],
+  ) => void;
+  onVisibleSelectionChange?: () => void;
+  onCommandKeyDown?: (
+    key: "ArrowDown" | "ArrowUp" | "Enter" | "Tab",
+    event: KeyboardEvent,
+    isTaskItem?: boolean,
+  ) => boolean;
+  onPageScrollKeyDown?: (key: "PageUp" | "PageDown") => void;
+  onPageScrollKeyUp?: (key: string) => void;
+  onPageScrollRelease?: () => void;
+  onCitationSubmitAndSend?: () => void;
+  onPaste: React.ClipboardEventHandler<HTMLElement>;
+  editorRef: React.RefObject<ComposerPromptEditorHandle | null>;
+}
+
+export type ComposerCitationCommentRequest = {
+  previousValue: string;
+  value: string;
+  citationStart: number;
+  sourceAnchor: AssistantCitationSourceAnchor;
+};
+
+type OpenCitationComment = {
+  key: string;
+  sourceAnchor?: AssistantCitationSourceAnchor;
+  removeOnCancel?: boolean;
+};
+
+const ComposerCitationCommentContext = createContext<{
+  openComment: OpenCitationComment | null;
+  onOpenChange: (citeKey: string, open: boolean) => void;
+  onSubmitAndSend: () => void;
+}>({ openComment: null, onOpenChange: () => {}, onSubmitAndSend: () => {} });
+
+const RichComposerSkillsContext = createContext<ReadonlyArray<ServerProviderSkill>>([]);
+
+const SURROUND_CLOSE: Record<string, string> = {
+  "(": ")",
+  "[": "]",
+  "{": "}",
+  "'": "'",
+  '"': '"',
+  "“": "”",
+  "`": "`",
+  "<": ">",
+  "«": "»",
+  "*": "*",
+  _: "_",
+};
+
+function resolvedThemeFromDocument(): "light" | "dark" {
+  return document.documentElement.classList.contains("dark") ? "dark" : "light";
+}
+
+// ── Inline atom nodes (chips) ─────────────────────────────────────────────
+
+const ComposerMentionExtension = Node.create({
+  name: "composer-mention",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      path: { default: "" },
+      source: { default: "" },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-mention]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-mention": "", ...HTMLAttributes }];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerMentionNodeView);
+  },
+});
+
+function ComposerMentionNodeView({ node }: NodeViewProps) {
+  const actions = use(ComposerContextActionsContext);
+  const path = (node.attrs.path as string) ?? "";
+  const chip = (
+    <button

@@ -0,0 +1,1155 @@
+import { Extension, Node, type JSONContent } from "@tiptap/core";
+import { TaskList } from "@tiptap/extension-task-list";
+import { ReactNodeViewRenderer, NodeViewWrapper, type NodeViewProps } from "@tiptap/react";
+import StarterKit from "@tiptap/starter-kit";
+import { type Node as ProseMirrorNode } from "@tiptap/pm/model";
+import { splitBlockKeepMarks } from "@tiptap/pm/commands";
+import { Plugin, PluginKey, TextSelection } from "@tiptap/pm/state";
+import { Decoration, DecorationSet } from "@tiptap/pm/view";
+import type { AssistantCitation, ServerProviderSkill } from "@t3tools/contracts";
+import {
+  serializeAssistantCitation,
+  withAssistantCitationComment,
+} from "@t3tools/shared/assistantCitations";
+import {
+  COMPOSER_CONTEXT_CLIPBOARD_MIME,
+  encodeComposerContextClipboardHtml,
+} from "@t3tools/shared/composerContextClipboard";
+import {
+  createContext,
+  use,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { EditorContent, useEditor } from "@tiptap/react";
+
+import {
+  clampCollapsedComposerCursor,
+  collapseExpandedComposerCursor,
+  expandCollapsedComposerCursor,
+  isCollapsedCursorAdjacentToInlineToken,
+} from "~/composer-logic";
+import { selectionTouchesMentionBoundary } from "~/composer-editor-mentions";
+import { RICH_TEXT_DELIMITERS, type RichTextMark } from "~/composer-rich-text";
+import {
+  buildDocJson,
+  buildTiptapContent,
+  collapsedToFlat,
+  ComposerTaskItemExtension,
+  flatToCollapsed,
+  flatToMarkdown,
+  flatToPm,
+  MARK_NESTING_ORDER,
+  pmToFlat,
+  serializeEditorDoc,
+  TIPTAP_TO_MARK,
+  type SkillMeta,
+} from "~/composer-rich-text-doc";
+import { collectInlineContextIds } from "~/lib/composerContextReferences";
+import { cn } from "~/lib/utils";
+import { basenameOfPath } from "~/pierre-icons";
+import {
+  COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME,
+  COMPOSER_INLINE_CHIP_ICON_CLASS_NAME,
+  COMPOSER_INLINE_CHIP_LABEL_CLASS_NAME,
+  COMPOSER_INLINE_SKILL_CHIP_CLASS_NAME,
+  SKILL_CHIP_ICON_SVG,
+} from "./composerInlineChip";
+import { FILE_TAG_CHIP_CLASS_NAME, FileTagChipContent } from "./chat/FileTagChip";
+import { AssistantCitationChip } from "./chat/AssistantCitationChip";
+import { getTimelinePageScrollKey } from "./chat/pageScrollController";
+import { ContextChipPopover } from "./contextChipParts";
+import { Button } from "./ui/button";
+import {
+  ComposerContextActionsContext,
+  ComposerContextReferenceChip,
+  ComposerContextRecordsContext,
+} from "./composerContextPresentation";
+import {
+  ComposerCitationCommentContext,
+  type ComposerCitationCommentTarget,
+} from "./ComposerCitationNode";
+import type { AssistantCitationSourceAnchor } from "~/lib/assistantTextSelection";
+import { formatProviderSkillDisplayName } from "@t3tools/client-runtime/providerSkills";
+import { Tooltip, TooltipPopup, TooltipTrigger } from "./ui/tooltip";
+import { importPastedComposerText } from "./composerInlineTokenPaste";
+import { didComposerSelectionChangeVisibly } from "./composerSelection";
+import type {
+  ComposerPromptEditorHandle,
+  ComposerPromptEditorProps as LexicalComposerPromptEditorProps,
+} from "./ComposerPromptEditor";
+
+export type ComposerPromptEditorProps = LexicalComposerPromptEditorProps;
+
+type ComposerCitationCommentRequest = {
+  previousValue: string;
+  value: string;
+  citationStart: number;
+  sourceAnchor: AssistantCitationSourceAnchor;
+};
+
+type OpenCitationComment = {
+  key: string;
+  sourceAnchor?: AssistantCitationSourceAnchor;
+  removeOnCancel?: boolean;
+};
+
+const RichComposerSkillsContext = createContext<ReadonlyArray<ServerProviderSkill>>([]);
+
+const SURROUND_CLOSE: Record<string, string> = {
+  "(": ")",
+  "[": "]",
+  "{": "}",
+  "'": "'",
+  '"': '"',
+  "“": "”",
+  "`": "`",
+  "<": ">",
+  "«": "»",
+  "*": "*",
+  _: "_",
+};
+
+function resolvedThemeFromDocument(): "light" | "dark" {
+  return document.documentElement.classList.contains("dark") ? "dark" : "light";
+}
+
+// ── Inline atom nodes (chips) ─────────────────────────────────────────────
+
+const ComposerMentionExtension = Node.create({
+  name: "composer-mention",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      path: { default: "" },
+      source: { default: "" },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-mention]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-mention": "", ...HTMLAttributes }, 0];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerMentionNodeView);
+  },
+});
+
+function ComposerMentionNodeView({ node }: NodeViewProps) {
+  const actions = use(ComposerContextActionsContext);
+  const path = (node.attrs.path as string) ?? "";
+  const chip = (
+    <button
+      type="button"
+      onClick={() => actions.openMention(path)}
+      aria-label={`Preview ${path}`}
+      className={`${FILE_TAG_CHIP_CLASS_NAME} cursor-pointer focus-visible:outline-2`}
+      contentEditable={false}
+      spellCheck={false}
+      data-composer-mention-chip="true"
+    >
+      <FileTagChipContent
+        path={path}
+        label={basenameOfPath(path)}
+        theme={resolvedThemeFromDocument()}
+      />
+    </button>
+  );
+  return (
+    <NodeViewWrapper as="span" className={COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME}>
+      <Tooltip>
+        <TooltipTrigger render={chip} />
+        <TooltipPopup
+          side="top"
+          className="max-w-120 whitespace-normal leading-tight wrap-anywhere"
+        >
+          {path}
+        </TooltipPopup>
+      </Tooltip>
+    </NodeViewWrapper>
+  );
+}
+
+const ComposerSkillExtension = Node.create({
+  name: "composer-skill",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      skillName: { default: "" },
+      skillLabel: { default: "" },
+      skillDescription: { default: null },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-skill]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-skill": "", ...HTMLAttributes }, 0];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerSkillNodeView);
+  },
+});
+
+function ComposerSkillNodeView({ node }: NodeViewProps) {
+  const actions = use(ComposerContextActionsContext);
+  const skills = use(RichComposerSkillsContext);
+  const skillName = (node.attrs.skillName as string) ?? "";
+  const skillLabel = (node.attrs.skillLabel as string) || skillName;
+  const skillDescription = (node.attrs.skillDescription as string | null) ?? null;
+  const skill = skills.find((candidate) => candidate.name === skillName);
+  return (
+    <NodeViewWrapper as="span" className={COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME}>
+      <ContextChipPopover
+        accessibleLabel={`Skill ${skillLabel}`}
+        triggerClassName={COMPOSER_INLINE_SKILL_CHIP_CLASS_NAME}
+        chip={
+          <>
+            <span
+              aria-hidden="true"
+              className={COMPOSER_INLINE_CHIP_ICON_CLASS_NAME}
+              dangerouslySetInnerHTML={{ __html: SKILL_CHIP_ICON_SVG }}
+            />
+            <span className={COMPOSER_INLINE_CHIP_LABEL_CLASS_NAME}>{skillLabel}</span>
+          </>
+        }
+      >
+        <div className="space-y-3 p-2 text-sm">
+          <p className="font-medium">{skillLabel}</p>
+          <p>
+            {skill?.description ??
+              skillDescription ??
+              "No description is available for this skill."}
+          </p>
+          {skill?.path ? (
+            <Button variant="outline" size="sm" onClick={() => actions.openMention(skill.path)}>
+              View instructions
+            </Button>
+          ) : null}
+        </div>
+      </ContextChipPopover>
+    </NodeViewWrapper>
+  );
+}
+
+const ComposerCitationExtension = Node.create({
+  name: "composer-citation",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      citation: { default: null },
+      source: { default: "" },
+      citeKey: { default: "" },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-citation]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-citation": "", ...HTMLAttributes }, 0];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerCitationNodeView);
+  },
+});
+
+function ComposerCitationNodeView({ node, editor, getPos }: NodeViewProps) {
+  const commentContext = use(ComposerCitationCommentContext);
+  const citation = node.attrs.citation as AssistantCitation;
+  const citeKey = node.attrs.citeKey as string;
+  const commentTarget =
+    commentContext.openComment !== null &&
+    typeof commentContext.openComment === "object" &&
+    "key" in (commentContext.openComment as Record<string, unknown>) &&
+    (commentContext.openComment as unknown as OpenCitationComment).key === citeKey
+      ? (commentContext.openComment as unknown as OpenCitationComment)
+      : null;
+
+  const nodePos = useCallback(() => {
+    const pos = typeof getPos === "function" ? getPos() : null;
+    return typeof pos === "number" ? pos : null;
+  }, [getPos]);
+
+  const onSaveComment = useCallback(
+    (comment: string): boolean => {
+      if (!editor.isEditable) return false;
+      const pos = nodePos();
+      if (pos === null) return false;
+      const current = editor.state.doc.nodeAt(pos);
+      if (!current || current.type.name !== "composer-citation") return false;
+      const currentCitation = current.attrs.citation as AssistantCitation;
+      const next = withAssistantCitationComment(currentCitation, comment);
+      const tr = editor.state.tr.setNodeMarkup(pos, undefined, {
+        ...current.attrs,
+        citation: next,
+        source: serializeAssistantCitation(next),
+      });
+      editor.view.dispatch(tr);
+      return true;
+    },
+    [editor, nodePos],
+  );
+
+  const onRemove = useCallback(() => {
+    if (!editor.isEditable) return;
+    const pos = nodePos();
+    if (pos === null) return;
+    const current = editor.state.doc.nodeAt(pos);
+    if (!current) return;
+    editor
+      .chain()
+      .focus()
+      .deleteRange({ from: pos, to: pos + current.nodeSize })
+      .run();
+  }, [editor, nodePos]);
+
+  return (
+    <NodeViewWrapper
+      as="span"
+      className="inline-flex min-w-0 max-w-full"
+      contentEditable={false}
+      spellCheck={false}
+      data-composer-citation-chip="true"
+    >
+      <AssistantCitationChip
+        citation={citation}
+        composer
+        commentEditor={{
+          open: commentTarget !== null,
+          sourceAnchor: commentTarget?.sourceAnchor,
+          onOpenChange: (open) => {
+            if (open && !editor.isEditable) return;
+            commentContext.onOpenChange(citeKey, open);
+          },
+          ...(commentTarget?.removeOnCancel ? { onCancel: onRemove } : {}),
+          onSave: onSaveComment,
+          onSaveAndSend: (comment) => {
+            if (!onSaveComment(comment)) return false;
+            commentContext.onSubmitAndSend();
+            return true;
+          },
+        }}
+      />
+    </NodeViewWrapper>
+  );
+}
+
+const ComposerContextReferenceExtension = Node.create({
+  name: "composer-context-reference",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      kind: { default: "" },
+      contextId: { default: "" },
+      label: { default: "" },
+      source: { default: "" },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-context-reference]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-context-reference": "", ...HTMLAttributes }, 0];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerContextReferenceNodeView);
+  },
+});
+
+function ComposerContextReferenceNodeView({ node }: NodeViewProps) {
+  return (
+    <NodeViewWrapper as="span" className={COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME}>
+      <ComposerContextReferenceChip
+        kind={(node.attrs.kind as string) ?? ""}
+        contextId={(node.attrs.contextId as string) ?? ""}
+        label={(node.attrs.label as string) ?? ""}
+      />
+    </NodeViewWrapper>
+  );
+}
+
+// ── Marker reveal (show ** when the cursor is on styled text) ──────────────
+
+type StyledRange = {
+  from: number;
+  to: number;
+  delimiter: string;
+};
+
+function collectStyledRanges(doc: ProseMirrorNode): StyledRange[] {
+  const ranges: StyledRange[] = [];
+  doc.descendants((node, pos) => {
+    if (!node.isText || !node.text) return true;
+    const marks = (node.marks ?? [])
+      .map((mark) => TIPTAP_TO_MARK[mark.type.name])
+      .filter((mark): mark is RichTextMark => Boolean(mark));
+    if (marks.length === 0) return false;
+    const ordered = [...marks].sort(
+      (a, b) => MARK_NESTING_ORDER.indexOf(a) - MARK_NESTING_ORDER.indexOf(b),
+    );
+    const delimiter = ordered.map((mark) => RICH_TEXT_DELIMITERS[mark]).join("");
+    const last = ranges[ranges.length - 1];
+    if (last && last.to === pos && last.delimiter === delimiter) {
+      last.to = pos + (node.text?.length ?? 0);
+    } else {
+      ranges.push({ from: pos, to: pos + (node.text?.length ?? 0), delimiter });
+    }
+    return false;
+  });
+  return ranges;
+}
+
+const MarkerPluginKey = new PluginKey("composer-rich-markers");
+
+const ComposerMarkerPlugin = new Plugin({
+  key: MarkerPluginKey,
+  state: {
+    init: (_, state) => decorationsForSelection(state.doc, state.selection),
+    apply: (tr, old) =>
+      tr.docChanged || tr.selectionSet ? decorationsForSelection(tr.doc, tr.selection) : old,
+  },
+  props: {
+    decorations(state) {
+      return MarkerPluginKey.getState(state);
+    },
+  },
+});
+
+function decorationsForSelection(
+  doc: ProseMirrorNode,
+  selection: { from: number; to: number; empty: boolean },
+): DecorationSet {
+  const decorations: Decoration[] = [];
+  for (const range of collectStyledRanges(doc)) {
+    const active = selection.empty
+      ? selection.from >= range.from && selection.from <= range.to
+      : selection.from < range.to && selection.to > range.from;
+    if (!active) continue;
+    for (const [at, side] of [
+      [range.from, -1],
+      [range.to, 1],
+    ] as const) {
+      const marker = document.createElement("span");
+      marker.className = "composer-rich-marker";
+      marker.textContent = range.delimiter;
+      marker.setAttribute("aria-hidden", "true");
+      decorations.push(Decoration.widget(at, marker, { side, key: `marker-${at}-${side}` }));
+    }
+  }
+  return DecorationSet.create(doc, decorations);
+}
+
+const ComposerMarkersExtension = Extension.create({
+  name: "composer-rich-markers",
+  addProseMirrorPlugins() {
+    return [ComposerMarkerPlugin];
+  },
+});
+
+// Document model (markdown ⇄ ProseMirror) lives in ~/composer-rich-text-doc so
+// unit tests can round-trip it without a browser.
+// ── Editor component ───────────────────────────────────────────────────────
+
+type TiptapEditor = NonNullable<ReturnType<typeof useEditor>>;
+
+export function ComposerPromptEditorTiptap(props: ComposerPromptEditorProps) {
+  const {
+    value,
+    cursor,
+    contextRecords,
+    buildContextClipboardFragment,
+    importContextFragment,
+    skills,
+    disabled,
+    placeholder,
+    containerClassName,
+    className,
+    placeholderClassName,
+    onChange,
+    onVisibleSelectionChange,
+    onCommandKeyDown,
+    onPageScrollKeyDown,
+    onPageScrollKeyUp,
+    onPageScrollRelease,
+    onCitationSubmitAndSend,
+    onPaste,
+    editorRef,
+  } = props;
+
+  const onChangeRef = useRef(onChange);
+  const onVisibleSelectionChangeRef = useRef(onVisibleSelectionChange);
+  const onCommandKeyDownRef = useRef(onCommandKeyDown);
+  const buildFragmentRef = useRef(buildContextClipboardFragment);
+  const importFragmentRef = useRef(importContextFragment);
+  const skillsRef = useRef(skills);
+  const latestValueRef = useRef(value);
+  // The editor instance for callbacks created before it exists (paste).
+  // Effects flush before any user interaction, so this is always set.
+  const editorHolder = useRef<TiptapEditor | null>(null);
+
+  useEffect(() => {
+    onChangeRef.current = onChange;
+  }, [onChange]);
+  useEffect(() => {
+    onVisibleSelectionChangeRef.current = onVisibleSelectionChange;
+  }, [onVisibleSelectionChange]);
+  useEffect(() => {
+    onCommandKeyDownRef.current = onCommandKeyDown;
+  }, [onCommandKeyDown]);
+  useEffect(() => {
+    buildFragmentRef.current = buildContextClipboardFragment;
+  }, [buildContextClipboardFragment]);
+  useEffect(() => {
+    importFragmentRef.current = importContextFragment;
+  }, [importContextFragment]);
+  useEffect(() => {
+    skillsRef.current = skills;
+  }, [skills]);
+  useLayoutEffect(() => {
+    latestValueRef.current = value;
+  }, [value]);
+
+  const skillLabelFor = useCallback((name: string): SkillMeta => {
+    const normalized = name.startsWith("$") ? name.slice(1) : name;
+    const skill = skillsRef.current.find((candidate) => candidate.name === normalized);
+    if (!skill) {
+      return { label: formatProviderSkillDisplayName({ name: normalized }), description: null };
+    }
+    const shortDescription = skill.shortDescription?.trim();
+    return {
+      label: formatProviderSkillDisplayName(skill),
+      description: shortDescription || skill.description?.trim() || null,
+    };
+  }, []);
+
+  const initialCursor = clampCollapsedComposerCursor(value, cursor);
+  const initialExpandedCursor = expandCollapsedComposerCursor(value, initialCursor);
+  const snapshotRef = useRef({
+    value,
+    cursor: initialCursor,
+    expandedCursor: initialExpandedCursor,
+    contextIds: collectInlineContextIds(value),
+  });
+  const selectionRangeRef = useRef({ start: initialExpandedCursor, end: initialExpandedCursor });
+  const isApplyingControlledUpdateRef = useRef(false);
+  const citationRequestRef = useRef<ComposerCitationCommentRequest | null>(null);
+  const [openCitation, setOpenCitation] = useState<OpenCitationComment | null>(null);
+  const [isEmpty, setIsEmpty] = useState(value.length === 0);
+
+  const citationCommentActions = useMemo(
+    () => ({
+      openComment: (openCitation ?? null) as unknown as ComposerCitationCommentTarget | null,
+      onOpenChange: (nodeKey: string, open: boolean) => {
+        setOpenCitation((current) => {
+          if (open) {
+            if (current?.key === nodeKey) return current;
+            return { key: nodeKey };
+          }
+          return current?.key === nodeKey ? null : current;
+        });
+      },
+      onSubmitAndSend: onCitationSubmitAndSend ?? (() => {}),
+    }),
+    [onCitationSubmitAndSend, openCitation],
+  );
+
+  const handleEditorChange = useCallback((updated: TiptapEditor) => {
+    const map = serializeEditorDoc(updated.state.doc);
+    const { from, to } = updated.state.selection;
+    const fromFlat = pmToFlat(map, from);
+    const toFlat = pmToFlat(map, to);
+    const nextValue = map.value;
+    const nextCursor = clampCollapsedComposerCursor(map.value, flatToCollapsed(map, fromFlat));
+    const nextExpandedCursor = Math.max(
+      0,
+      Math.min(map.value.length, flatToMarkdown(map, fromFlat)),
+    );
+    const nextSelectionRange = {
+      start: Math.min(nextExpandedCursor, flatToMarkdown(map, toFlat)),
+      end: Math.max(nextExpandedCursor, flatToMarkdown(map, toFlat)),
+    };
+    const previousSelectionRange = selectionRangeRef.current;
+    selectionRangeRef.current = nextSelectionRange;
+    setIsEmpty(nextValue.length === 0);
+    const previousSnapshot = snapshotRef.current;
+    const snapshotChanged = !(
+      previousSnapshot.value === nextValue &&
+      previousSnapshot.cursor === nextCursor &&
+      previousSnapshot.expandedCursor === nextExpandedCursor &&
+      previousSnapshot.contextIds.length === map.contextIds.length &&
+      previousSnapshot.contextIds.every((id, index) => id === map.contextIds[index])
+    );
+    if (isApplyingControlledUpdateRef.current) return;
+    if (!snapshotChanged) {
+      if (didComposerSelectionChangeVisibly(previousSelectionRange, nextSelectionRange)) {
+        onVisibleSelectionChangeRef.current?.();
+      }
+      return;
+    }
+    // A selection-only update while a newer prompt waits to be applied (a chip
+    // was just inserted through the store) would report stale text and clobber
+    // the prompt. Let the controlled rewrite land instead.
+    if (previousSnapshot.value === nextValue && nextValue !== latestValueRef.current) {
+      return;
+    }
+    snapshotRef.current = {
+      value: nextValue,
+      cursor: nextCursor,
+      expandedCursor: nextExpandedCursor,
+      contextIds: map.contextIds,
+    };
+    const cursorAdjacentToMention =
+      isCollapsedCursorAdjacentToInlineToken(nextValue, nextCursor, "left") ||
+      isCollapsedCursorAdjacentToInlineToken(nextValue, nextCursor, "right");
+    onChangeRef.current(
+      nextValue,
+      nextCursor,
+      nextExpandedCursor,
+      cursorAdjacentToMention,
+      map.contextIds,
+    );
+  }, []);
+
+  const editor = useEditor(
+    {
+      extensions: [
+        StarterKit.configure({
+          blockquote: false,
+          bulletList: false,
+          codeBlock: false,
+          heading: false,
+          horizontalRule: false,
+          listItem: false,
+          orderedList: false,
+          dropcursor: false,
+          gapcursor: false,
+          trailingNode: false,
+        }),
+        ComposerMentionExtension,
+        ComposerSkillExtension,
+        ComposerCitationExtension,
+        ComposerContextReferenceExtension,
+        TaskList,
+        ComposerTaskItemExtension,
+        ComposerMarkersExtension,
+      ],
+      content: buildDocJson(value, (name) => {
+        const normalized = name.startsWith("$") ? name.slice(1) : name;
+        const found = skills.find((candidate) => candidate.name === normalized);
+        if (!found) {
+          return { label: formatProviderSkillDisplayName({ name: normalized }), description: null };
+        }
+        const shortDescription = found.shortDescription?.trim();
+        return {
+          label: formatProviderSkillDisplayName(found),
+          description: shortDescription || found.description?.trim() || null,
+        };
+      }),
+      editable: !disabled,
+      editorProps: {
+        attributes: {
+          class: cn(
+            "composer-tiptap block max-h-50 min-h-17.5 w-full overflow-y-auto whitespace-pre-wrap wrap-break-word bg-transparent leading-relaxed text-foreground focus:outline-none",
+            className,
+          ),
+          "data-testid": "composer-editor",
+          "aria-placeholder": placeholder,
+        },
+        handleKeyDown: (view, event) => {
+          if (event.key === "Enter" && (event.isComposing || event.keyCode === 229)) {
+            event.stopPropagation();
+            return true;
+          }
+          // Enter on a focused task checkbox must not send the prompt (or
+          // split anything): Space toggles it, Enter does nothing.
+          if (event.key === "Enter" && event.target instanceof HTMLInputElement) {
+            event.preventDefault();
+            return true;
+          }
+          const handler = onCommandKeyDownRef.current;
+          if (event.key === "Enter") {
+            const handled = handler?.("Enter", event) ?? false;
+            if (handled) {
+              event.preventDefault();
+              event.stopPropagation();
+              return true;
+            }
+            // A newline the parent declined (Shift+Enter, or Enter while the
+            // shortcut says otherwise) must be one visible line. Letting it
+            // fall through inserts a native trailing `<br>`, which renders
+            // no visible line, so the caret looks stuck until a second press.
+            // Splitting the paragraph matches the Lexical surface: one press,
+            // one line. Enter on a list line never gets here — the parent
+            // claims it for continuation — so Tiptap's list splitting stays
+            // shadowed and both surfaces serialize identically.
+            event.preventDefault();
+            return splitBlockKeepMarks(view.state, (tr) => {
+              // The split is programmatic, so the browser won't follow the
+              // caret into view on its own.
+              view.dispatch(tr.scrollIntoView());
+            });
+          }
+          if (!handler) return false;
+          const key =
+            event.key === "Tab"
+              ? ("Tab" as const)
+              : event.key === "ArrowDown"
+                ? ("ArrowDown" as const)
+                : event.key === "ArrowUp"
+                  ? ("ArrowUp" as const)
+                  : null;
+          if (!key) return false;
+          const handled = handler(key, event);
+          if (handled) {
+            event.preventDefault();
+            event.stopPropagation();
+          }
+          return handled;
+        },
+        handleTextInput: (view, from, to, text) => {
+          const closer = SURROUND_CLOSE[text];
+          if (!closer || from === to) return false;
+          // Never wrap chips or other atoms, and never wrap styled text: the
+          // default replace keeps marks intact, wrapping would drop them.
+          let touchesSpecial = false;
+          view.state.doc.nodesBetween(from, to, (node) => {
+            if ((node.isAtom && node.isInline) || (node.isText && node.marks.length > 0)) {
+              touchesSpecial = true;
+              return false;
+            }
+            return true;
+          });
+          if (touchesSpecial) return false;
+          const map = serializeEditorDoc(view.state.doc);
+          const startMd = flatToMarkdown(map, pmToFlat(map, from));
+          const endMd = flatToMarkdown(map, pmToFlat(map, to));
+          if (selectionTouchesMentionBoundary(map.value, startMd, endMd)) return false;
+          const tr = view.state.tr.insertText(closer, to).insertText(text, from);
+          tr.setSelection(TextSelection.create(tr.doc, from + text.length, to + text.length));
+          view.dispatch(tr);
+          return true;
+        },
+        handlePaste: (view, event) => {
+          const clipboardData = event.clipboardData;
+          if (!clipboardData || clipboardData.files.length > 0) return false;
+          const pastedText = clipboardData.getData("text/plain");
+          if (!pastedText) return false;
+          event.preventDefault();
+          const importFragment = importFragmentRef.current;
+          const text = importFragment
+            ? importPastedComposerText(clipboardData, importFragment)
+            : pastedText;
+          const editorInstance = editorHolder.current;
+          if (editorInstance) {
+            insertMarkdownParagraphs(text, skillLabelFor, (content) => {
+              editorInstance.commands.insertContent(content);
+            });
+            scrollTiptapCaretIntoView(editorInstance);
+          }
+          return true;
+        },
+      },
+      onUpdate: ({ editor: updated }) => {
+        handleEditorChange(updated);
+      },
+      onSelectionUpdate: ({ editor: updated }) => {
+        handleEditorChange(updated);
+      },
+    },
+    [],
+  );
+
+  useEffect(() => {
+    editor?.setEditable(!disabled);
+  }, [disabled, editor]);
+
+  useEffect(() => {
+    editorHolder.current = editor;
+  }, [editor]);
+
+  const readSnapshot = useCallback(() => {
+    const snapshot = snapshotRef.current;
+    if (!editor) return snapshot;
+    const map = serializeEditorDoc(editor.state.doc);
+    const { from, to } = editor.state.selection;
+    const fromFlat = pmToFlat(map, from);
+    const next: typeof snapshot = {
+      value: map.value,
+      cursor: clampCollapsedComposerCursor(map.value, flatToCollapsed(map, fromFlat)),
+      expandedCursor: Math.max(0, Math.min(map.value.length, flatToMarkdown(map, fromFlat))),
+      contextIds: map.contextIds,
+    };
+    const toFlat = pmToFlat(map, to);
+    selectionRangeRef.current = {
+      start: Math.min(next.expandedCursor, flatToMarkdown(map, toFlat)),
+      end: Math.max(next.expandedCursor, flatToMarkdown(map, toFlat)),
+    };
+    snapshotRef.current = next;
+    return next;
+  }, [editor]);
+
+  // Controlled value/cursor from the store (history recall, chip insertion…).
+  useLayoutEffect(() => {
+    if (!editor) return;
+    const normalizedCursor = clampCollapsedComposerCursor(value, cursor);
+    const previousSnapshot = snapshotRef.current;
+    if (previousSnapshot.value === value && previousSnapshot.cursor === normalizedCursor) {
+      return;
+    }
+    const normalizedExpandedCursor = expandCollapsedComposerCursor(value, normalizedCursor);
+    snapshotRef.current = {
+      value,
+      cursor: normalizedCursor,
+      expandedCursor: normalizedExpandedCursor,
+      contextIds: collectInlineContextIds(value),
+    };
+    selectionRangeRef.current = {
+      start: normalizedExpandedCursor,
+      end: normalizedExpandedCursor,
+    };
+    setIsEmpty(value.length === 0);
+    const rootElement = editor.view.dom;
+    const isFocused = Boolean(rootElement && document.activeElement === rootElement);
+    if (previousSnapshot.value === value && !isFocused) return;
+
+    isApplyingControlledUpdateRef.current = true;
+    const pendingCitation =
+      citationRequestRef.current?.value === value ? citationRequestRef.current : null;
+    editor.commands.setContent(buildDocJson(value, skillLabelFor), { emitUpdate: false });
+    const map = serializeEditorDoc(editor.state.doc);
+    const flat = collapsedToFlat(map, normalizedCursor);
+    editor.commands.setTextSelection(flatToPm(map, flat));
+    if (isFocused) scrollTiptapCaretIntoView(editor);
+    if (pendingCitation) {
+      citationRequestRef.current = null;
+      const target = map.runs.find(
+        (run) =>
+          run.kind === "token" &&
+          run.nodeName === "composer-citation" &&
+          run.mdStart === pendingCitation.citationStart,
+      );
+      if (target) {
+        const node = editor.state.doc.nodeAt(target.pmPos);
+        const citeKey = (node?.attrs as { citeKey?: string } | undefined)?.citeKey;
+        if (citeKey) {
+          setOpenCitation({
+            key: citeKey,
+            sourceAnchor: pendingCitation.sourceAnchor,
+            removeOnCancel: true,
+          });
+        }
+      }
+    }
+    queueMicrotask(() => {
+      isApplyingControlledUpdateRef.current = false;
+    });
+  }, [cursor, editor, skillLabelFor, value]);
+
+  const focusAt = useCallback(
+    (nextCursor: number) => {
+      if (!editor) return;
+      editor.view.dom.focus({ preventScroll: true });
+      // A newer prompt is waiting to be applied (a chip was just inserted
+      // through the store). Reporting the editor's stale text now would
+      // overwrite that prompt; the pending rewrite places the caret instead.
+      if (snapshotRef.current.value !== latestValueRef.current) return;
+      const boundedCursor = clampCollapsedComposerCursor(snapshotRef.current.value, nextCursor);
+      const map = serializeEditorDoc(editor.state.doc);
+      const flat = collapsedToFlat(map, boundedCursor);
+      editor.commands.setTextSelection(flatToPm(map, flat));
+      scrollTiptapCaretIntoView(editor);
+      if (boundedCursor === snapshotRef.current.cursor) return;
+      snapshotRef.current = {
+        value: snapshotRef.current.value,
+        cursor: boundedCursor,
+        expandedCursor: expandCollapsedComposerCursor(snapshotRef.current.value, boundedCursor),
+        contextIds: snapshotRef.current.contextIds,
+      };
+      selectionRangeRef.current = {
+        start: snapshotRef.current.expandedCursor,
+        end: snapshotRef.current.expandedCursor,
+      };
+      onChangeRef.current(
+        snapshotRef.current.value,
+        boundedCursor,
+        snapshotRef.current.expandedCursor,
+        false,
+        snapshotRef.current.contextIds,
+      );
+    },
+    [editor],
+  );
+
+  useImperativeHandle(
+    editorRef,
+    () => ({
+      focus: () => {
+        focusAt(snapshotRef.current.cursor);
+      },
+      focusAt,
+      focusAtEnd: () => {
+        focusAt(
+          collapseExpandedComposerCursor(
+            snapshotRef.current.value,
+            snapshotRef.current.value.length,
+          ),
+        );
+      },
+      readSelectionRange: () => {
+        readSnapshot();
+        return selectionRangeRef.current;
+      },
+      requestCitationComment: (request) => {

@@ -0,0 +1,586 @@
+import type { Node as ProseMirrorNode } from "@tiptap/pm/model";
+import { TaskItem } from "@tiptap/extension-task-item";
+
+import { splitPromptIntoComposerSegments } from "~/composer-editor-mentions";
+import { parseInlineMarkdown, RICH_TEXT_DELIMITERS, type RichTextMark } from "~/composer-rich-text";
+import { collectInlineContextIds } from "~/lib/composerContextReferences";
+
+/**
+ * Pure document model for the rich text (Tiptap) composer.
+ *
+ * The stored prompt stays markdown (`**bold**`, `@file` chips as canonical
+ * links). The Tiptap document holds styled text plus inline atom chips, so
+ * this module translates both ways and maps cursor offsets between the three
+ * coordinate spaces the composer speaks:
+ *
+ * - flat document offsets (styled markers excluded, chips count 1),
+ * - collapsed cursor offsets (markers literal, chips count 1 — the coordinate
+ *   the draft store and mention detection use),
+ * - markdown offsets (markers literal, chips expand to their source).
+ *
+ * DOM-free on purpose: unit tests build a real ProseMirror document from the
+ * JSON this produces and assert the round trip without a browser.
+ */
+
+export type SkillMeta = { label: string; description: string | null };
+
+/** Outermost mark first, so closers mirror openers when nested. */
+export const MARK_NESTING_ORDER: RichTextMark[] = ["strike", "bold", "italic", "code"];
+
+export const MARK_TO_TIPTAP: Record<RichTextMark, string> = {
+  bold: "bold",
+  italic: "italic",
+  strike: "strike",
+  code: "code",
+};
+
+export const TIPTAP_TO_MARK: Record<string, RichTextMark> = {
+  bold: "bold",
+  italic: "italic",
+  strike: "strike",
+  code: "code",
+};
+
+/**
+ * Task list items keep their exact source indent in an attribute so nesting
+ * round-trips byte-identically. Checkbox case (`[X]`) normalizes to `[x]` —
+ * the same fixed-point deal as `__bold__` becoming `**bold**`.
+ */
+export const ComposerTaskItemExtension = TaskItem.extend({
+  addAttributes() {
+    return {
+      ...this.parent?.(),
+      indent: { default: "" },
+    };
+  },
+}).configure({ nested: true });
+
+export function randomNodeKey(): string {
+  return `tiptap-${Math.random().toString(36).slice(2)}`;
+}
+
+interface TaskLinePrefix {
+  indent: string;
+  checked: boolean;
+}
+
+function parseTaskPrefix(head: string): { prefix: TaskLinePrefix; markerLength: number } | null {
+  const match = head.match(/^([ \t]*)-[ \t]+\[([ xX])\]/);
+  if (!match) return null;
+  const after = head.slice(match[0].length);
+  if (after.length > 0 && after[0] !== " " && after[0] !== "\t") return null;
+  return {
+    prefix: {
+      indent: match[1] ?? "",
+      checked: (match[2] ?? " ").toLowerCase() === "x",
+    },
+    markerLength: match[0].length,
+  };
+}
+
+type InlineJson = Record<string, unknown>;
+
+interface DocLine {
+  task: TaskLinePrefix | null;
+  inline: InlineJson[];
+}
+
+function atomJsonForSegment(
+  segment: Exclude<ReturnType<typeof splitPromptIntoComposerSegments>[number], { type: "text" }>,
+  skillLabelFor: (name: string) => SkillMeta,
+): InlineJson {
+  if (segment.type === "mention") {
+    return {
+      type: "composer-mention",
+      attrs: { path: segment.path, source: segment.source },
+    };
+  }
+  if (segment.type === "skill") {
+    const meta = skillLabelFor(segment.name);
+    return {
+      type: "composer-skill",
+      attrs: {
+        skillName: segment.name,
+        skillLabel: meta.label,
+        skillDescription: meta.description,
+      },
+    };
+  }
+  if (segment.type === "citation") {
+    return {
+      type: "composer-citation",
+      attrs: { citation: segment.citation, source: segment.source, citeKey: randomNodeKey() },
+    };
+  }
+  return {
+    type: "composer-context-reference",
+    attrs: {
+      kind: segment.kind,
+      contextId: segment.contextId,
+      label: segment.label,
+      source: segment.source,
+    },
+  };
+}
+
+function pushSpans(inline: InlineJson[], text: string): void {
+  for (const span of parseInlineMarkdown(text)) {
+    inline.push(textJsonForSpan(span.text, span.marks));
+  }
+}
+
+interface PendingTaskItem {
+  checked: boolean;
+  indent: string;
+  content: InlineJson[];
+  children: PendingTaskItem[];
+}
+
+function taskListJson(items: PendingTaskItem[]): InlineJson {
+  return {
+    type: "taskList",
+    content: items.map((item) => ({
+      type: "taskItem",
+      attrs: { checked: item.checked, indent: item.indent },
+      content: [
+        { type: "paragraph", content: item.content },
+        ...(item.children.length > 0 ? [taskListJson(item.children)] : []),
+      ],
+    })),
+  };
+}
+
+function textJsonForSpan(text: string, marks: RichTextMark[]): Record<string, unknown> {
+  const json: Record<string, unknown> = { type: "text", text };
+  if (marks.length > 0) {
+    json.marks = [...marks]
+      .sort((a, b) => MARK_NESTING_ORDER.indexOf(a) - MARK_NESTING_ORDER.indexOf(b))
+      .map((mark) => ({ type: MARK_TO_TIPTAP[mark] }));
+  }
+  return json;
+}
+
+export function buildTiptapContent(
+  value: string,
+  skillLabelFor: (name: string) => SkillMeta,
+): Record<string, unknown>[] {
+  // Pass 1: the segment stream becomes lines. A line is a task line only
+  // when its leading text — before any chip — is a complete `- [ ]` marker;
+  // the marker is decided at a chip, a newline, or the end of input so a
+  // partial marker (`- [ ]` + `foo`) can never commit early.
+  const lines: DocLine[] = [{ task: null, inline: [] }];
+  let head: string | null = "";
+  const currentLine = () => lines[lines.length - 1]!;
+  const endLine = () => {
+    const line = currentLine();
+    if (head !== null) {
+      const parsed = parseTaskPrefix(head);
+      if (parsed) {
+        line.task = parsed.prefix;
+        pushSpans(line.inline, head.slice(parsed.markerLength).replace(/^[ \t]*/, ""));
+      } else {
+        pushSpans(line.inline, head);
+      }
+    }
+    lines.push({ task: null, inline: [] });
+    head = "";
+  };
+  const appendTextPiece = (piece: string) => {
+    if (head !== null) {
+      head += piece;
+      return;
+    }
+    pushSpans(currentLine().inline, piece);
+  };
+
+  for (const segment of splitPromptIntoComposerSegments(value)) {
+    if (segment.type === "text") {
+      const parts = segment.text.split("\n");
+      parts.forEach((part, index) => {
+        if (index > 0) endLine();
+        appendTextPiece(part);
+      });
+    } else {
+      if (head !== null) {
+        const line = currentLine();
+        const parsed = parseTaskPrefix(head);
+        if (parsed) {
+          line.task = parsed.prefix;
+          pushSpans(line.inline, head.slice(parsed.markerLength).replace(/^[ \t]*/, ""));
+        } else {
+          pushSpans(line.inline, head);
+        }
+        head = null;
+      }
+      currentLine().inline.push(atomJsonForSegment(segment, skillLabelFor));
+    }
+  }
+  // Decide the final line. A trailing newline leaves a fresh empty line,
+  // which endLine already pushed — drop the spare blank it would add.
+  if (head !== null) {
+    const line = currentLine();
+    const parsed = parseTaskPrefix(head);
+    if (parsed) {
+      line.task = parsed.prefix;
+      pushSpans(line.inline, head.slice(parsed.markerLength).replace(/^[ \t]*/, ""));
+    } else {
+      pushSpans(line.inline, head);
+    }
+  } else if (lines.length > 1) {
+    const last = lines[lines.length - 1]!;
+    if (!last.task && last.inline.length === 0) lines.pop();
+  }
+
+  // Pass 2: consecutive task lines group into (possibly nested) task lists
+  // by indent prefix; everything else stays a paragraph.
+  const blocks: Record<string, unknown>[] = [];
+  let stack: { indent: string; items: PendingTaskItem[] }[] = [];
+  const flushTasks = () => {
+    if (stack.length > 0) {
+      blocks.push(taskListJson(stack[0]!.items));
+      stack = [];
+    }
+  };
+  for (const line of lines) {
+    if (!line.task) {
+      flushTasks();
+      blocks.push({ type: "paragraph", content: line.inline });
+      continue;
+    }
+    const item: PendingTaskItem = {
+      checked: line.task.checked,
+      indent: line.task.indent,
+      content: line.inline,
+      children: [],
+    };
+    for (;;) {
+      const top = stack[stack.length - 1];
+      if (!top) {
+        // A leading indented item with no parent flattens but keeps indent.
+        stack.push({ indent: "", items: [] });
+        continue;
+      }
+      if (top.indent === item.indent) {
+        top.items.push(item);
+        break;
+      }
+      if (top.indent !== "" && !item.indent.startsWith(top.indent)) {
+        stack.pop();
+        continue;
+      }
+      const parent = top.items[top.items.length - 1];
+      if (!parent) {
+        top.items.push(item);
+        break;
+      }
+      parent.children.push(item);
+      stack.push({ indent: item.indent, items: parent.children });
+      break;
+    }
+  }
+  flushTasks();
+  return blocks;
+}
+
+export function buildDocJson(value: string, skillLabelFor: (name: string) => SkillMeta) {
+  return { type: "doc", content: buildTiptapContent(value, skillLabelFor) };
+}
+
+export interface RichRun {
+  kind: "text" | "token" | "break" | "prefix";
+  /** Flat document offset (atoms count 1, markers excluded). */
+  flatStart: number;
+  docLen: number;
+  /** Collapsed cursor length (markers literal, tokens count 1). */
+  collapsedLen: number;
+  /** Markdown length (tokens expand to their source). */
+  mdLen: number;
+  /** Marker layout inside text runs. */
+  openLen: number;
+  closeLen: number;
+  /** ProseMirror position of the run start. */
+  pmPos: number;
+  mdStart: number;
+  collapsedStart: number;
+  nodeName?: string;
+}
+
+export interface RichDocMap {
+  value: string;
+  runs: RichRun[];
+  docLength: number;
+  contextIds: string[];
+}
+
+function textRunDelimiters(marks: RichTextMark[]): { open: string; close: string } {
+  let open = "";
+  let close = "";
+  for (const mark of [...marks].sort(
+    (a, b) => MARK_NESTING_ORDER.indexOf(a) - MARK_NESTING_ORDER.indexOf(b),
+  )) {
+    const delimiter = RICH_TEXT_DELIMITERS[mark];
+    open = open + delimiter;
+    close = delimiter + close;
+  }
+  return { open, close };
+}
+
+function readAtomSource(node: ProseMirrorNode): string {
+  const attrs = node.attrs as Record<string, unknown>;
+  switch (node.type.name) {
+    case "composer-mention":
+    case "composer-citation":
+    case "composer-context-reference":
+      return typeof attrs.source === "string" ? attrs.source : "";
+    case "composer-skill": {
+      const name = typeof attrs.skillName === "string" ? attrs.skillName : "";
+      return name ? `$${name}` : "";
+    }
+    default:
+      return "";
+  }
+}
+
+interface RichAccumulator {
+  runs: RichRun[];
+  value: string;
+  flat: number;
+  collapsed: number;
+  md: number;
+}
+
+function pushBreakRun(acc: RichAccumulator, pmPos: number): void {
+  // Block boundary: one newline in every coordinate space.
+  acc.runs.push({
+    kind: "break",
+    flatStart: acc.flat,
+    docLen: 1,
+    collapsedLen: 1,
+    mdLen: 1,
+    openLen: 0,
+    closeLen: 0,
+    pmPos,
+    mdStart: acc.md,
+    collapsedStart: acc.collapsed,
+  });
+  acc.value += "\n";
+  acc.flat += 1;
+  acc.collapsed += 1;
+  acc.md += 1;
+}
+
+function appendInlineRuns(
+  container: ProseMirrorNode,
+  contentStart: number,
+  acc: RichAccumulator,
+): void {
+  let inlineOffset = 0;
+  container.content.forEach((child) => {
+    const pmPos = contentStart + inlineOffset;
+    if (child.isText && child.text) {
+      const marks = (child.marks ?? [])
+        .map((mark) => TIPTAP_TO_MARK[mark.type.name])
+        .filter((mark): mark is RichTextMark => Boolean(mark));
+      const { open, close } = textRunDelimiters(marks);
+      const mdText = `${open}${child.text}${close}`;
+      acc.runs.push({
+        kind: "text",
+        flatStart: acc.flat,
+        docLen: child.text.length,
+        collapsedLen: mdText.length,
+        mdLen: mdText.length,
+        openLen: open.length,
+        closeLen: close.length,
+        pmPos,
+        mdStart: acc.md,
+        collapsedStart: acc.collapsed,
+      });
+      acc.value += mdText;
+      acc.flat += child.text.length;
+      acc.collapsed += mdText.length;
+      acc.md += mdText.length;
+      inlineOffset += child.nodeSize;
+    } else if (child.type.name === "hardBreak") {
+      pushBreakRun(acc, pmPos);
+      inlineOffset += child.nodeSize;
+    } else if (child.isAtom || child.isInline) {
+      const source = readAtomSource(child);
+      acc.runs.push({
+        kind: "token",
+        flatStart: acc.flat,
+        docLen: 1,
+        collapsedLen: 1,
+        mdLen: source.length,
+        openLen: 0,
+        closeLen: 0,
+        pmPos,
+        mdStart: acc.md,
+        collapsedStart: acc.collapsed,
+        nodeName: child.type.name,
+      });
+      acc.value += source;
+      acc.flat += 1;
+      acc.collapsed += 1;
+      acc.md += source.length;
+      inlineOffset += child.nodeSize;
+    } else {
+      inlineOffset += child.nodeSize;
+    }
+  });
+}
+
+function walkTaskList(list: ProseMirrorNode, listStart: number, acc: RichAccumulator): void {
+  let itemPos = listStart + 1;
+  let firstItem = true;
+  list.content.forEach((item) => {
+    // Sibling items are separated by one newline in every coordinate space.
+    if (!firstItem) pushBreakRun(acc, itemPos - 1);
+    firstItem = false;
+    const itemContentStart = itemPos + 1;
+    const first = item.firstChild;
+    const empty =
+      item.childCount === 1 && first?.type.name === "paragraph" && first.content.childCount === 0;
+    const attrs = item.attrs as { checked?: unknown; indent?: unknown };
+    const indent = typeof attrs.indent === "string" ? attrs.indent : "";
+    const prefix = `${indent}- [${attrs.checked === true ? "x" : " "}]${empty ? "" : " "}`;

@@ -0,0 +1,599 @@
+import type { Node as ProseMirrorNode } from "@tiptap/pm/model";
+import { TaskItem } from "@tiptap/extension-task-item";
+
+import { splitPromptIntoComposerSegments } from "~/composer-editor-mentions";
+import { parseInlineMarkdown, RICH_TEXT_DELIMITERS, type RichTextMark } from "~/composer-rich-text";
+import { collectInlineContextIds } from "~/lib/composerContextReferences";
+
+/**
+ * Pure document model for the rich text (Tiptap) composer.
+ *
+ * The stored prompt stays markdown (`**bold**`, `@file` chips as canonical
+ * links). The Tiptap document holds styled text plus inline atom chips, so
+ * this module translates both ways and maps cursor offsets between the three
+ * coordinate spaces the composer speaks:
+ *
+ * - flat document offsets (styled markers excluded, chips count 1),
+ * - collapsed cursor offsets (markers literal, chips count 1 — the coordinate
+ *   the draft store and mention detection use),
+ * - markdown offsets (markers literal, chips expand to their source).
+ *
+ * DOM-free on purpose: unit tests build a real ProseMirror document from the
+ * JSON this produces and assert the round trip without a browser.
+ */
+
+export type SkillMeta = { label: string; description: string | null };
+
+/** Outermost mark first, so closers mirror openers when nested. */
+const MARK_NESTING_ORDER: RichTextMark[] = ["strike", "bold", "italic", "code"];
+
+const MARK_TO_TIPTAP: Record<RichTextMark, string> = {
+  bold: "bold",
+  italic: "italic",
+  strike: "strike",
+  code: "code",
+};
+
+const TIPTAP_TO_MARK: Record<string, RichTextMark> = {
+  bold: "bold",
+  italic: "italic",
+  strike: "strike",
+  code: "code",
+};
+
+/**
+ * Task list items keep their exact source indent in an attribute so nesting
+ * round-trips byte-identically. Checkbox case (`[X]`) normalizes to `[x]` —
+ * the same fixed-point deal as `__bold__` becoming `**bold**`.
+ */
+export const ComposerTaskItemExtension = TaskItem.extend({
+  addAttributes() {
+    return {
+      ...this.parent?.(),
+      indent: { default: "" },
+      markerSpace: { default: " " },
+      contentSpace: { default: null },
+    };
+  },
+}).configure({ nested: true });
+
+function randomNodeKey(): string {
+  return `tiptap-${Math.random().toString(36).slice(2)}`;
+}
+
+interface TaskLinePrefix {
+  indent: string;
+  checked: boolean;
+  markerSpace: string;
+  contentSpace: string;
+}
+
+function parseTaskPrefix(head: string): { prefix: TaskLinePrefix; markerLength: number } | null {
+  const match = head.match(/^([ \t]*)-([ \t]+)\[([ xX])\]([ \t]*)/);
+  if (!match) return null;
+  const after = head.slice(match[0].length);
+  if (after.length > 0 && !match[4]) return null;
+  return {
+    prefix: {
+      indent: match[1] ?? "",
+      checked: (match[3] ?? " ").toLowerCase() === "x",
+      markerSpace: match[2]!,
+      contentSpace: match[4]!,
+    },
+    markerLength: match[0].length,
+  };
+}
+
+type InlineJson = Record<string, unknown>;
+
+interface DocLine {
+  task: TaskLinePrefix | null;
+  inline: InlineJson[];
+}
+
+function atomJsonForSegment(
+  segment: Exclude<ReturnType<typeof splitPromptIntoComposerSegments>[number], { type: "text" }>,
+  skillLabelFor: (name: string) => SkillMeta,
+): InlineJson {
+  if (segment.type === "mention") {
+    return {
+      type: "composer-mention",
+      attrs: { path: segment.path, source: segment.source },
+    };
+  }
+  if (segment.type === "skill") {
+    const meta = skillLabelFor(segment.name);
+    return {
+      type: "composer-skill",
+      attrs: {
+        skillName: segment.name,
+        skillLabel: meta.label,
+        skillDescription: meta.description,
+      },
+    };
+  }
+  if (segment.type === "citation") {
+    return {
+      type: "composer-citation",
+      attrs: { citation: segment.citation, source: segment.source, citeKey: randomNodeKey() },
+    };
+  }
+  return {
+    type: "composer-context-reference",
+    attrs: {
+      kind: segment.kind,
+      contextId: segment.contextId,
+      label: segment.label,
+      source: segment.source,
+    },
+  };
+}
+
+interface PendingTaskItem extends TaskLinePrefix {
+  content: InlineJson[];
+  children: PendingTaskItem[];
+}
+
+function taskListJson(items: PendingTaskItem[]): InlineJson {
+  return {
+    type: "taskList",
+    content: items.map((item) => ({
+      type: "taskItem",
+      attrs: {
+        checked: item.checked,
+        indent: item.indent,
+        markerSpace: item.markerSpace,
+        contentSpace: item.contentSpace,
+      },
+      content: [
+        { type: "paragraph", content: item.content },
+        ...(item.children.length > 0 ? [taskListJson(item.children)] : []),
+      ],
+    })),
+  };
+}
+
+function textJsonForSpan(text: string, marks: RichTextMark[]): Record<string, unknown> {
+  const json: Record<string, unknown> = { type: "text", text };
+  if (marks.length > 0) {
+    json.marks = [...marks]
+      .sort((a, b) => MARK_NESTING_ORDER.indexOf(a) - MARK_NESTING_ORDER.indexOf(b))
+      .map((mark) => ({ type: MARK_TO_TIPTAP[mark] }));
+  }
+  return json;
+}
+
+export function buildTiptapContent(
+  value: string,
+  skillLabelFor: (name: string) => SkillMeta,
+  options?: { styling?: boolean },
+): Record<string, unknown>[] {
+  const styling = options?.styling ?? true;
+  // Hide token source from the markdown parser, then restore the atoms with
+  // the marks of their surrounding text. Choose a sentinel absent from input.
+  let sentinel = "\uFFFC";
+  for (let codePoint = 0xe000; value.includes(sentinel); codePoint += 1) {
+    sentinel = String.fromCodePoint(codePoint);
+  }
+  const atoms: InlineJson[] = [];
+  const text = splitPromptIntoComposerSegments(value)
+    .map((segment) => {
+      if (segment.type === "text") return segment.text;
+      atoms.push(atomJsonForSegment(segment, skillLabelFor));
+      return sentinel;
+    })
+    .join("");
+  let atomIndex = 0;
+  const lines: DocLine[] = text.split("\n").map((line) => {
+    const parsed = styling ? parseTaskPrefix(line) : null;
+    const content = parsed ? line.slice(parsed.markerLength) : line;
+    const spans = styling ? parseInlineMarkdown(content) : [{ text: content, marks: [] }];
+    const inline: InlineJson[] = [];
+    for (const span of spans) {
+      span.text.split(sentinel).forEach((piece, index) => {
+        if (index > 0) {
+          const atom = atoms[atomIndex++]!;
+          inline.push({ ...atom, marks: textJsonForSpan("", span.marks).marks });
+        }
+        if (piece) inline.push(textJsonForSpan(piece, span.marks));
+      });
+    }
+    return { task: parsed?.prefix ?? null, inline };
+  });
+
+  // Pass 2: consecutive task lines group into (possibly nested) task lists
+  // by indent prefix; everything else stays a paragraph.
+  const blocks: Record<string, unknown>[] = [];
+  let stack: { indent: string; items: PendingTaskItem[] }[] = [];
+  const flushTasks = () => {
+    if (stack.length > 0) {
+      blocks.push(taskListJson(stack[0]!.items));
+      stack = [];
+    }
+  };
+  for (const line of lines) {
+    if (!line.task) {
+      flushTasks();
+      blocks.push({ type: "paragraph", content: line.inline });
+      continue;
+    }
+    const item: PendingTaskItem = {
+      ...line.task,
+      content: line.inline,
+      children: [],
+    };
+    for (;;) {
+      const top = stack[stack.length - 1];
+      if (!top) {
+        // A leading indented item with no parent flattens but keeps indent.
+        stack.push({ indent: item.indent, items: [] });
+        continue;
+      }
+      if (top.indent === item.indent) {
+        top.items.push(item);
+        break;
+      }
+      if (top.indent !== "" && !item.indent.startsWith(top.indent)) {
+        if (stack.length > 1) {
+          stack.pop();
+          continue;
+        }
+        top.indent = item.indent;
+        top.items.push(item);
+        break;
+      }
+      const parent = top.items[top.items.length - 1];
+      if (!parent) {
+        top.items.push(item);
+        break;
+      }
+      parent.children.push(item);
+      stack.push({ indent: item.indent, items: parent.children });
+      break;
+    }
+  }
+  flushTasks();
+  return blocks;
+}
+
+export function buildDocJson(
+  value: string,
+  skillLabelFor: (name: string) => SkillMeta,
+  options?: { styling?: boolean },
+) {
+  return { type: "doc", content: buildTiptapContent(value, skillLabelFor, options) };
+}
+
+export interface RichRun {
+  kind: "text" | "token" | "break" | "prefix";
+  /** Flat document offset (atoms count 1, markers excluded). */
+  flatStart: number;
+  docLen: number;
+  /** Collapsed cursor length (markers literal, tokens count 1). */
+  collapsedLen: number;
+  /** Markdown length (tokens expand to their source). */
+  mdLen: number;
+  /** Marker layout inside text runs. */
+  openLen: number;
+  closeLen: number;
+  /** ProseMirror position of the run start. */
+  pmPos: number;
+  mdStart: number;
+  collapsedStart: number;
+  nodeName?: string;
+}
+
+export interface RichDocMap {
+  value: string;
+  runs: RichRun[];
+  docLength: number;
+  contextIds: string[];
+}
+
+function readAtomSource(node: ProseMirrorNode): string {
+  const attrs = node.attrs as Record<string, unknown>;
+  switch (node.type.name) {
+    case "composer-mention":
+    case "composer-citation":
+    case "composer-context-reference":
+      return typeof attrs.source === "string" ? attrs.source : "";
+    case "composer-skill": {
+      const name = typeof attrs.skillName === "string" ? attrs.skillName : "";
+      return name ? `$${name}` : "";
+    }
+    default:
+      return "";
+  }
+}
+
+interface RichAccumulator {
+  runs: RichRun[];
+  value: string;
+  flat: number;
+  collapsed: number;
+  md: number;
+}
+
+function pushBreakRun(acc: RichAccumulator, position?: number): void {
+  const previous = acc.runs[acc.runs.length - 1];
+  const pmPos = position ?? (previous ? previous.pmPos + previous.docLen : 1);
+  // Block boundary: one newline in every coordinate space.
+  acc.runs.push({
+    kind: "break",
+    flatStart: acc.flat,
+    docLen: 1,
+    collapsedLen: 1,
+    mdLen: 1,
+    openLen: 0,
+    closeLen: 0,
+    pmPos,
+    mdStart: acc.md,
+    collapsedStart: acc.collapsed,
+  });
+  acc.value += "\n";
+  acc.flat += 1;
+  acc.collapsed += 1;
+  acc.md += 1;
+}
+
+function appendInlineRuns(
+  container: ProseMirrorNode,
+  contentStart: number,
+  acc: RichAccumulator,
+): void {
+  const children: ProseMirrorNode[] = [];
+  container.forEach((child) => children.push(child));
+  // Longer shared marks surround shorter ones. This keeps both nested
+  // formatting and formatting across chips inside a single delimiter pair.
+  const markEnds = new Map<RichTextMark, number>();
+  const orderedMarks: RichTextMark[][] = [];
+  for (let index = children.length - 1; index >= 0; index -= 1) {
+    const child = children[index]!;
+    const marks =
+      child.type.name === "hardBreak"
+        ? []
+        : child.marks
+            .map((mark) => TIPTAP_TO_MARK[mark.type.name])
+            .filter((mark): mark is RichTextMark => Boolean(mark));
+    for (const mark of MARK_NESTING_ORDER) {
+      if (!marks.includes(mark)) markEnds.delete(mark);
+      else if (!markEnds.has(mark)) markEnds.set(mark, index);
+    }
+    orderedMarks[index] = marks.sort(
+      (a, b) =>
+        markEnds.get(b)! - markEnds.get(a)! ||
+        MARK_NESTING_ORDER.indexOf(a) - MARK_NESTING_ORDER.indexOf(b),
+    );
+  }
+  for (let index = 1; index < orderedMarks.length; index += 1) {
+    const marks = orderedMarks[index]!;
+    const retained: RichTextMark[] = [];
+    for (const mark of orderedMarks[index - 1]!) {
+      if (!marks.includes(mark)) break;
+      retained.push(mark);
+    }
+    orderedMarks[index] = [...retained, ...marks.filter((mark) => !retained.includes(mark))];

@@ -0,0 +1,1379 @@
+import { Extension, Node, wrappingInputRule, type JSONContent } from "@tiptap/core";
+import { TaskList } from "@tiptap/extension-task-list";
+import { ReactNodeViewRenderer, NodeViewWrapper, type NodeViewProps } from "@tiptap/react";
+import StarterKit from "@tiptap/starter-kit";
+import { type Node as ProseMirrorNode } from "@tiptap/pm/model";
+import { splitBlockKeepMarks } from "@tiptap/pm/commands";
+import { Plugin, PluginKey, TextSelection } from "@tiptap/pm/state";
+import { Decoration, DecorationSet } from "@tiptap/pm/view";
+import type {
+  AssistantCitation,
+  ComposerContextClipboardFragment,
+  ServerProviderSkill,
+} from "@t3tools/contracts";
+import {
+  serializeAssistantCitation,
+  withAssistantCitationComment,
+} from "@t3tools/shared/assistantCitations";
+import {
+  COMPOSER_CONTEXT_CLIPBOARD_MIME,
+  encodeComposerContextClipboardHtml,
+} from "@t3tools/shared/composerContextClipboard";
+import {
+  createContext,
+  use,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { EditorContent, useEditor } from "@tiptap/react";
+
+import {
+  clampCollapsedComposerCursor,
+  collapseExpandedComposerCursor,
+  expandCollapsedComposerCursor,
+  isCollapsedCursorAdjacentToInlineToken,
+} from "~/composer-logic";
+import {
+  collectComposerPromptInlineTokens,
+  selectionTouchesMentionBoundary,
+} from "~/composer-editor-mentions";
+import {
+  buildDocJson,
+  buildTiptapContent,
+  collapsedToFlat,
+  ComposerTaskItemExtension,
+  flatToCollapsed,
+  flatToMarkdown,
+  flatToPm,
+  pmToFlat,
+  serializeEditorDoc,
+  type SkillMeta,
+} from "~/composer-rich-text-doc";
+import { collectInlineContextIds } from "~/lib/composerContextReferences";
+import { cn, isMacPlatform } from "~/lib/utils";
+import { basenameOfPath } from "~/pierre-icons";
+import {
+  COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME,
+  COMPOSER_INLINE_CHIP_ICON_CLASS_NAME,
+  COMPOSER_INLINE_CHIP_LABEL_CLASS_NAME,
+  COMPOSER_INLINE_SKILL_CHIP_CLASS_NAME,
+  SKILL_CHIP_ICON_SVG,
+} from "./composerInlineChip";
+import { FILE_TAG_CHIP_CLASS_NAME, FileTagChipContent } from "./chat/FileTagChip";
+import { AssistantCitationChip } from "./chat/AssistantCitationChip";
+import { getTimelinePageScrollKey } from "./chat/pageScrollController";
+import { ContextChipPopover } from "./contextChipParts";
+import { Button } from "./ui/button";
+import {
+  ComposerContextActionsContext,
+  ComposerContextReferenceChip,
+  ComposerContextRecordsContext,
+} from "./composerContextPresentation";
+import type { AssistantCitationSourceAnchor } from "~/lib/assistantTextSelection";
+import { formatProviderSkillDisplayName } from "@t3tools/client-runtime/providerSkills";
+import { Tooltip, TooltipPopup, TooltipTrigger } from "./ui/tooltip";
+import { importPastedComposerText } from "./composerInlineTokenPaste";
+import { didComposerSelectionChangeVisibly } from "./composerSelection";
+import type { ComposerDraftContextRecords } from "./composerContextPresentation";
+
+export interface ComposerPromptEditorHandle {
+  focus: () => void;
+  focusAt: (cursor: number) => void;
+  focusAtEnd: () => void;
+  readSelectionRange: () => { start: number; end: number };
+  requestCitationComment: (request: ComposerCitationCommentRequest) => void;
+  readSnapshot: () => {
+    value: string;
+    cursor: number;
+    expandedCursor: number;
+    contextIds: string[];
+  };
+  /**
+   * True when a collapsed caret sits on the first ("start") or last ("end")
+   * visual line, counting soft wraps. Prompt history only claims ArrowUp and
+   * ArrowDown at these edges so arrows still move the caret inside multiline
+   * text.
+   */
+  isCaretOnVisualEdge: (edge: "start" | "end") => boolean;
+}
+
+export interface ComposerPromptEditorProps {
+  value: string;
+  cursor: number;
+  /**
+   * Render Markdown styling (bold, italic, code, strike, task checkboxes).
+   * Off renders the same Tiptap engine as plain text: every marker stays a
+   * literal character.
+   */
+  richTextEnabled?: boolean;
+  /** Draft records behind the prompt's context references, keyed by context id. */
+  contextRecords: ComposerDraftContextRecords;
+  /** Structured clipboard payload for the given referenced ids, or null to skip. */
+  buildContextClipboardFragment?:
+    | ((contextIds: ReadonlyArray<string>) => string | null)
+    | undefined;
+  /** Imports a structured paste's records; returns ids that changed. */
+  importContextFragment?:
+    | ((fragment: ComposerContextClipboardFragment) => ReadonlyMap<string, string>)
+    | undefined;
+  skills: ReadonlyArray<ServerProviderSkill>;
+  disabled: boolean;
+  placeholder: string;
+  containerClassName?: string;
+  className?: string;
+  placeholderClassName?: string;
+  onChange: (
+    nextValue: string,
+    nextCursor: number,
+    expandedCursor: number,
+    cursorAdjacentToMention: boolean,
+    contextIds: string[],
+  ) => void;
+  onVisibleSelectionChange?: () => void;
+  onCommandKeyDown?: (
+    key: "ArrowDown" | "ArrowUp" | "Enter" | "Tab",
+    event: KeyboardEvent,
+    isTaskItem?: boolean,
+  ) => boolean;
+  onPageScrollKeyDown?: (key: "PageUp" | "PageDown") => void;
+  onPageScrollKeyUp?: (key: string) => void;
+  onPageScrollRelease?: () => void;
+  onCitationSubmitAndSend?: () => void;
+  onPaste: React.ClipboardEventHandler<HTMLElement>;
+  editorRef: React.RefObject<ComposerPromptEditorHandle | null>;
+}
+
+export type ComposerCitationCommentRequest = {
+  previousValue: string;
+  value: string;
+  citationStart: number;
+  sourceAnchor: AssistantCitationSourceAnchor;
+};
+
+type OpenCitationComment = {
+  key: string;
+  sourceAnchor?: AssistantCitationSourceAnchor;
+  removeOnCancel?: boolean;
+};
+
+const ComposerCitationCommentContext = createContext<{
+  openComment: OpenCitationComment | null;
+  onOpenChange: (citeKey: string, open: boolean) => void;
+  onSubmitAndSend: () => void;
+}>({ openComment: null, onOpenChange: () => {}, onSubmitAndSend: () => {} });
+
+const RichComposerSkillsContext = createContext<ReadonlyArray<ServerProviderSkill>>([]);
+
+const SURROUND_CLOSE: Record<string, string> = {
+  "(": ")",
+  "[": "]",
+  "{": "}",
+  "'": "'",
+  '"': '"',
+  "“": "”",
+  "`": "`",
+  "<": ">",
+  "«": "»",
+  "*": "*",
+  _: "_",
+};
+
+function resolvedThemeFromDocument(): "light" | "dark" {
+  return document.documentElement.classList.contains("dark") ? "dark" : "light";
+}
+
+// ── Inline atom nodes (chips) ─────────────────────────────────────────────
+
+const ComposerMentionExtension = Node.create({
+  name: "composer-mention",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      path: { default: "" },
+      source: { default: "" },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-mention]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-mention": "", ...HTMLAttributes }];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerMentionNodeView);
+  },
+});
+
+function ComposerMentionNodeView({ node }: NodeViewProps) {
+  const actions = use(ComposerContextActionsContext);
+  const path = (node.attrs.path as string) ?? "";
+  const chip = (
+    <button
+      type="button"
+      onClick={() => actions.openMention(path)}
+      aria-label={`Preview ${path}`}
+      className={`${FILE_TAG_CHIP_CLASS_NAME} cursor-pointer focus-visible:outline-2`}
+      contentEditable={false}
+      spellCheck={false}
+      data-composer-mention-chip="true"
+    >
+      <FileTagChipContent
+        path={path}
+        label={basenameOfPath(path)}
+        theme={resolvedThemeFromDocument()}
+      />
+    </button>
+  );
+  return (
+    <NodeViewWrapper as="span" className={COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME}>
+      <Tooltip>
+        <TooltipTrigger render={chip} />
+        <TooltipPopup
+          side="top"
+          className="max-w-120 whitespace-normal leading-tight wrap-anywhere"
+        >
+          {path}
+        </TooltipPopup>
+      </Tooltip>
+    </NodeViewWrapper>
+  );
+}
+
+const ComposerSkillExtension = Node.create({
+  name: "composer-skill",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      skillName: { default: "" },
+      skillLabel: { default: "" },
+      skillDescription: { default: null },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-skill]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-skill": "", ...HTMLAttributes }];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerSkillNodeView);
+  },
+});
+
+function ComposerSkillNodeView({ node }: NodeViewProps) {
+  const actions = use(ComposerContextActionsContext);
+  const skills = use(RichComposerSkillsContext);
+  const skillName = (node.attrs.skillName as string) ?? "";
+  const skillLabel = (node.attrs.skillLabel as string) || skillName;
+  const skillDescription = (node.attrs.skillDescription as string | null) ?? null;
+  const skill = skills.find((candidate) => candidate.name === skillName);
+  return (
+    <NodeViewWrapper as="span" className={COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME}>
+      <ContextChipPopover
+        accessibleLabel={`Skill ${skillLabel}`}
+        triggerClassName={COMPOSER_INLINE_SKILL_CHIP_CLASS_NAME}
+        chip={
+          <>
+            <span
+              aria-hidden="true"
+              className={COMPOSER_INLINE_CHIP_ICON_CLASS_NAME}
+              dangerouslySetInnerHTML={{ __html: SKILL_CHIP_ICON_SVG }}
+            />
+            <span className={COMPOSER_INLINE_CHIP_LABEL_CLASS_NAME}>{skillLabel}</span>
+          </>
+        }
+      >
+        <div className="space-y-3 p-2 text-sm">
+          <p className="font-medium">{skillLabel}</p>
+          <p>
+            {skill?.description ??
+              skillDescription ??
+              "No description is available for this skill."}
+          </p>
+          {skill?.path ? (
+            <Button variant="outline" size="sm" onClick={() => actions.openMention(skill.path)}>
+              View instructions
+            </Button>
+          ) : null}
+        </div>
+      </ContextChipPopover>
+    </NodeViewWrapper>
+  );
+}
+
+const ComposerCitationExtension = Node.create({
+  name: "composer-citation",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      citation: { default: null },
+      source: { default: "" },
+      citeKey: { default: "" },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-citation]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-citation": "", ...HTMLAttributes }];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerCitationNodeView);
+  },
+});
+
+function ComposerCitationNodeView({ node, editor, getPos }: NodeViewProps) {
+  const commentContext = use(ComposerCitationCommentContext);
+  const citation = node.attrs.citation as AssistantCitation;
+  const citeKey = node.attrs.citeKey as string;
+  const commentTarget =
+    commentContext.openComment?.key === citeKey ? commentContext.openComment : null;
+
+  const nodePos = useCallback(() => {
+    const pos = typeof getPos === "function" ? getPos() : null;
+    return typeof pos === "number" ? pos : null;
+  }, [getPos]);
+
+  const onSaveComment = useCallback(
+    (comment: string): boolean => {
+      if (!editor.isEditable) return false;
+      const pos = nodePos();
+      if (pos === null) return false;
+      const current = editor.state.doc.nodeAt(pos);
+      if (!current || current.type.name !== "composer-citation") return false;
+      const currentCitation = current.attrs.citation as AssistantCitation;
+      const next = withAssistantCitationComment(currentCitation, comment);
+      const tr = editor.state.tr.setNodeMarkup(pos, undefined, {
+        ...current.attrs,
+        citation: next,
+        source: serializeAssistantCitation(next),
+      });
+      editor.view.dispatch(tr);
+      return true;
+    },
+    [editor, nodePos],
+  );
+
+  const onRemove = useCallback(() => {
+    if (!editor.isEditable) return;
+    const pos = nodePos();
+    if (pos === null) return;
+    const current = editor.state.doc.nodeAt(pos);
+    if (!current) return;
+    editor
+      .chain()
+      .focus()
+      .deleteRange({ from: pos, to: pos + current.nodeSize })
+      .run();
+  }, [editor, nodePos]);
+
+  return (
+    <NodeViewWrapper
+      as="span"
+      className="inline-flex min-w-0 max-w-full"
+      contentEditable={false}
+      spellCheck={false}
+      data-composer-citation-chip="true"
+    >
+      <AssistantCitationChip
+        citation={citation}
+        composer
+        commentEditor={{
+          open: commentTarget !== null,
+          sourceAnchor: commentTarget?.sourceAnchor,
+          onOpenChange: (open) => {
+            if (open && !editor.isEditable) return;
+            commentContext.onOpenChange(citeKey, open);
+          },
+          ...(commentTarget?.removeOnCancel ? { onCancel: onRemove } : {}),
+          onSave: onSaveComment,
+          onSaveAndSend: (comment) => {
+            if (!onSaveComment(comment)) return false;
+            commentContext.onSubmitAndSend();
+            return true;
+          },
+        }}
+      />
+    </NodeViewWrapper>
+  );
+}
+
+const ComposerContextReferenceExtension = Node.create({
+  name: "composer-context-reference",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      kind: { default: "" },
+      contextId: { default: "" },
+      label: { default: "" },
+      source: { default: "" },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-context-reference]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-context-reference": "", ...HTMLAttributes }];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerContextReferenceNodeView);
+  },
+});
+
+function ComposerContextReferenceNodeView({ node }: NodeViewProps) {
+  return (
+    <NodeViewWrapper as="span" className={COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME}>
+      <ComposerContextReferenceChip
+        kind={(node.attrs.kind as string) ?? ""}
+        contextId={(node.attrs.contextId as string) ?? ""}
+        label={(node.attrs.label as string) ?? ""}
+      />
+    </NodeViewWrapper>
+  );
+}
+
+// ── Marker reveal (show ** when the cursor is on styled text) ──────────────
+
+type StyledRange = {
+  from: number;
+  to: number;
+  markers: { at: number; side: number; text: string }[];
+};
+
+function collectStyledRanges(doc: ProseMirrorNode): StyledRange[] {
+  const ranges: StyledRange[] = [];
+  const map = serializeEditorDoc(doc);
+  let range: StyledRange | null = null;
+  let openLength = 0;
+  for (const run of map.runs) {
+    if (run.openLen > 0) {
+      range ??= { from: run.pmPos, to: run.pmPos, markers: [] };
+      range.markers.push({
+        at: run.pmPos,
+        side: -1,
+        text: map.value.slice(run.mdStart, run.mdStart + run.openLen),
+      });
+    }
+    if (range === null) continue;
+    range.to = run.pmPos + run.docLen;
+    if (run.closeLen > 0) {
+      const end = run.mdStart + run.mdLen;
+      range.markers.push({
+        at: range.to,
+        side: -2,
+        text: map.value.slice(end - run.closeLen, end),
+      });
+    }
+    openLength += run.openLen - run.closeLen;
+    if (openLength === 0) {
+      ranges.push(range);
+      range = null;
+    }
+  }
+  return ranges;
+}
+
+const MarkerPluginKey = new PluginKey("composer-rich-markers");
+
+const ComposerMarkerPlugin = new Plugin({
+  key: MarkerPluginKey,
+  state: {
+    init: (_, state) => decorationsForSelection(state.doc, state.selection),
+    apply: (tr, old) =>
+      tr.docChanged || tr.selectionSet ? decorationsForSelection(tr.doc, tr.selection) : old,
+  },
+  props: {
+    decorations(state) {
+      return MarkerPluginKey.getState(state);
+    },
+  },
+});
+
+function decorationsForSelection(
+  doc: ProseMirrorNode,
+  selection: { from: number; to: number; empty: boolean },
+): DecorationSet {
+  const decorations: Decoration[] = [];
+  if (!selection.empty) {
+    doc.nodesBetween(selection.from, selection.to, (node, pos) => {
+      if (node.type.name.startsWith("composer-")) {
+        decorations.push(
+          Decoration.node(pos, pos + node.nodeSize, { class: "composer-chip-range-selected" }),
+        );
+        return false;
+      }
+      return true;
+    });
+  }
+  for (const range of collectStyledRanges(doc)) {
+    const active = selection.empty
+      ? selection.from >= range.from && selection.from <= range.to
+      : selection.from < range.to && selection.to > range.from;
+    if (!active) continue;
+    for (const { at, side, text } of range.markers) {
+      const marker = document.createElement("span");
+      marker.className = "composer-rich-marker";
+      marker.textContent = text;
+      marker.setAttribute("aria-hidden", "true");
+      decorations.push(
+        Decoration.widget(at, marker, { side, key: `marker-${at}-${side}-${marker.textContent}` }),
+      );
+    }
+  }
+  return DecorationSet.create(doc, decorations);
+}
+
+const ComposerMarkersExtension = Extension.create({
+  name: "composer-rich-markers",
+  addProseMirrorPlugins() {
+    return [ComposerMarkerPlugin];
+  },
+});
+
+// Document model (markdown ⇄ ProseMirror) lives in ~/composer-rich-text-doc so
+// unit tests can round-trip it without a browser.
+// ── Editor component ───────────────────────────────────────────────────────
+
+type TiptapEditor = NonNullable<ReturnType<typeof useEditor>>;
+
+export function ComposerPromptEditorTiptap(props: ComposerPromptEditorProps) {
+  // Extensions are creation-time: flipping the setting remounts the editor.
+  // Both halves initialize from the controlled Markdown value, so the draft
+  // survives the flip.
+  return (
+    <ComposerPromptEditorTiptapInner key={props.richTextEnabled ? "rich" : "plain"} {...props} />
+  );
+}
+
+function ComposerPromptEditorTiptapInner(props: ComposerPromptEditorProps) {
+  const {
+    value,
+    cursor,
+    richTextEnabled,
+    contextRecords,
+    buildContextClipboardFragment,
+    importContextFragment,
+    skills,
+    disabled,
+    placeholder,
+    containerClassName,
+    className,
+    placeholderClassName,
+    onChange,
+    onVisibleSelectionChange,
+    onCommandKeyDown,
+    onPageScrollKeyDown,
+    onPageScrollKeyUp,
+    onPageScrollRelease,
+    onCitationSubmitAndSend,
+    onPaste,
+    editorRef,
+  } = props;
+  // The setting toggles styling, not the engine: both modes are Tiptap.
+  // Plain mode disables the mark extensions, so markers stay literal text.
+  const richText = richTextEnabled ?? false;
+
+  const onChangeRef = useRef(onChange);
+  const onVisibleSelectionChangeRef = useRef(onVisibleSelectionChange);
+  const onCommandKeyDownRef = useRef(onCommandKeyDown);
+  const buildFragmentRef = useRef(buildContextClipboardFragment);
+  const importFragmentRef = useRef(importContextFragment);
+  const skillsRef = useRef(skills);
+  const latestValueRef = useRef(value);
+  // The editor instance for callbacks created before it exists (paste).
+  // Effects flush before any user interaction, so this is always set.
+  const editorHolder = useRef<TiptapEditor | null>(null);
+
+  useEffect(() => {
+    onChangeRef.current = onChange;
+  }, [onChange]);
+  useEffect(() => {
+    onVisibleSelectionChangeRef.current = onVisibleSelectionChange;
+  }, [onVisibleSelectionChange]);
+  useEffect(() => {
+    onCommandKeyDownRef.current = onCommandKeyDown;
+  }, [onCommandKeyDown]);
+  useEffect(() => {
+    buildFragmentRef.current = buildContextClipboardFragment;
+  }, [buildContextClipboardFragment]);
+  useEffect(() => {
+    importFragmentRef.current = importContextFragment;
+  }, [importContextFragment]);
+  useEffect(() => {
+    skillsRef.current = skills;
+  }, [skills]);
+  useLayoutEffect(() => {
+    latestValueRef.current = value;
+  }, [value]);
+
+  const skillLabelFor = useCallback((name: string): SkillMeta => {
+    const normalized = name.startsWith("$") ? name.slice(1) : name;
+    const skill = skillsRef.current.find((candidate) => candidate.name === normalized);
+    if (!skill) {
+      return { label: formatProviderSkillDisplayName({ name: normalized }), description: null };
+    }
+    const shortDescription = skill.shortDescription?.trim();
+    return {
+      label: formatProviderSkillDisplayName(skill),
+      description: shortDescription || skill.description?.trim() || null,
+    };
+  }, []);
+
+  const initialCursor = clampCollapsedComposerCursor(value, cursor);
+  const initialExpandedCursor = expandCollapsedComposerCursor(value, initialCursor);
+  const snapshotRef = useRef({
+    value,
+    cursor: initialCursor,
+    expandedCursor: initialExpandedCursor,
+    contextIds: collectInlineContextIds(value),
+  });
+  const selectionRangeRef = useRef({ start: initialExpandedCursor, end: initialExpandedCursor });
+  const isApplyingControlledUpdateRef = useRef(false);
+  const hasAppliedControlledSelectionRef = useRef(false);
+  const citationRequestRef = useRef<ComposerCitationCommentRequest | null>(null);
+  const [openCitation, setOpenCitation] = useState<OpenCitationComment | null>(null);
+  const [isEmpty, setIsEmpty] = useState(value.length === 0);
+
+  const citationCommentActions = useMemo(
+    () => ({
+      openComment: openCitation,
+      onOpenChange: (nodeKey: string, open: boolean) => {
+        setOpenCitation((current) => {
+          if (open) {
+            if (current?.key === nodeKey) return current;
+            return { key: nodeKey };
+          }
+          return current?.key === nodeKey ? null : current;
+        });
+      },
+      onSubmitAndSend: onCitationSubmitAndSend ?? (() => {}),
+    }),
+    [onCitationSubmitAndSend, openCitation],
+  );
+
+  const handleEditorChange = useCallback((updated: TiptapEditor) => {
+    const map = serializeEditorDoc(updated.state.doc);
+    const { from, to } = updated.state.selection;
+    const fromFlat = pmToFlat(map, from);
+    const toFlat = pmToFlat(map, to);
+    const nextValue = map.value;
+    const nextCursor = clampCollapsedComposerCursor(map.value, flatToCollapsed(map, fromFlat));
+    const nextExpandedCursor = Math.max(
+      0,
+      Math.min(map.value.length, flatToMarkdown(map, fromFlat)),
+    );
+    const nextSelectionRange = {
+      start: Math.min(nextExpandedCursor, flatToMarkdown(map, toFlat)),
+      end: Math.max(nextExpandedCursor, flatToMarkdown(map, toFlat)),
+    };
+    const previousSelectionRange = selectionRangeRef.current;
+    selectionRangeRef.current = nextSelectionRange;
+    setIsEmpty(nextValue.length === 0);
+    const previousSnapshot = snapshotRef.current;
+    const snapshotChanged = !(
+      previousSnapshot.value === nextValue &&
+      previousSnapshot.cursor === nextCursor &&
+      previousSnapshot.expandedCursor === nextExpandedCursor &&
+      previousSnapshot.contextIds.length === map.contextIds.length &&
+      previousSnapshot.contextIds.every((id, index) => id === map.contextIds[index])
+    );
+    if (isApplyingControlledUpdateRef.current) return;
+    if (!snapshotChanged) {
+      if (didComposerSelectionChangeVisibly(previousSelectionRange, nextSelectionRange)) {
+        onVisibleSelectionChangeRef.current?.();
+      }
+      return;
+    }
+    // A selection-only update while a newer prompt waits to be applied (a chip
+    // was just inserted through the store) would report stale text and clobber
+    // the prompt. Let the controlled rewrite land instead.
+    if (previousSnapshot.value === nextValue && nextValue !== latestValueRef.current) {
+      return;
+    }
+    snapshotRef.current = {
+      value: nextValue,
+      cursor: nextCursor,
+      expandedCursor: nextExpandedCursor,
+      contextIds: map.contextIds,
+    };
+    const cursorAdjacentToMention =
+      isCollapsedCursorAdjacentToInlineToken(nextValue, nextCursor, "left") ||
+      isCollapsedCursorAdjacentToInlineToken(nextValue, nextCursor, "right");
+    onChangeRef.current(
+      nextValue,
+      nextCursor,
+      nextExpandedCursor,
+      cursorAdjacentToMention,
+      map.contextIds,
+    );
+  }, []);
+
+  const editor = useEditor(
+    {
+      extensions: [
+        StarterKit.configure({
+          blockquote: false,
+          bulletList: false,
+          codeBlock: false,
+          heading: false,
+          horizontalRule: false,
+          listItem: false,
+          link: false,
+          orderedList: false,
+          underline: false,
+          dropcursor: false,
+          gapcursor: false,
+          trailingNode: false,
+          // Plain mode has no marks: typed markers stay literal characters.
+          ...(richText ? {} : { bold: false, italic: false, strike: false, code: false }),
+        }),
+        ComposerMentionExtension,
+        ComposerSkillExtension,
+        ComposerCitationExtension,
+        ComposerContextReferenceExtension,
+        ComposerMarkersExtension,
+        ...(richText
+          ? [
+              TaskList,
+              ComposerTaskItemExtension.extend({
+                addInputRules() {
+                  return [
+                    wrappingInputRule({
+                      find: /^- \[([ xX])\] $/,
+                      type: this.type,
+                      getAttributes: (match) => ({ checked: match[1]?.toLowerCase() === "x" }),
+                    }),
+                  ];
+                },
+              }),
+            ]
+          : []),
+      ],
+      content: buildDocJson(
+        value,
+        (name) => {
+          const normalized = name.startsWith("$") ? name.slice(1) : name;
+          const found = skills.find((candidate) => candidate.name === normalized);
+          if (!found) {
+            return {
+              label: formatProviderSkillDisplayName({ name: normalized }),
+              description: null,
+            };
+          }
+          const shortDescription = found.shortDescription?.trim();
+          return {
+            label: formatProviderSkillDisplayName(found),
+            description: shortDescription || found.description?.trim() || null,
+          };
+        },
+        { styling: richText },
+      ),
+      editable: !disabled,
+      editorProps: {
+        attributes: {
+          class: cn(
+            "composer-tiptap block max-h-50 min-h-17.5 w-full overflow-y-auto whitespace-pre-wrap wrap-break-word bg-transparent leading-relaxed text-foreground focus:outline-none",
+            className,
+          ),
+          "data-testid": "composer-editor",
+          "data-composer-rich-text": richText ? "true" : "false",
+          "aria-placeholder": placeholder,
+        },
+        handleKeyDown: (view, event) => {
+          if (
+            isMacPlatform(navigator.platform) &&
+            (event.key === "Home" || event.key === "End") &&
+            !event.altKey &&
+            !event.metaKey &&
+            !event.ctrlKey &&
+            !event.isComposing
+          ) {
+            const selection = window.getSelection();
+            if (
+              selection?.anchorNode &&
+              view.dom.contains(selection.anchorNode) &&
+              typeof selection.modify === "function"
+            ) {
+              event.preventDefault();
+              event.stopPropagation();
+              selection.modify(
+                event.shiftKey ? "extend" : "move",
+                event.key === "Home" ? "backward" : "forward",
+                "lineboundary",
+              );
+              if (selection.anchorNode && selection.focusNode) {
+                view.dispatch(
+                  view.state.tr
+                    .setSelection(
+                      TextSelection.create(
+                        view.state.doc,
+                        view.posAtDOM(selection.anchorNode, selection.anchorOffset),
+                        view.posAtDOM(selection.focusNode, selection.focusOffset),
+                      ),
+                    )
+                    .scrollIntoView(),
+                );
+              }
+              return true;
+            }
+          }
+          if (
+            (event.key === "ArrowLeft" || event.key === "ArrowRight") &&
+            !event.shiftKey &&
+            !event.altKey &&
+            !event.metaKey &&
+            !event.ctrlKey &&
+            !event.isComposing &&
+            view.state.selection.empty
+          ) {
+            const { $from } = view.state.selection;
+            const direction = event.key === "ArrowLeft" ? -1 : 1;
+            const adjacent = direction === -1 ? $from.nodeBefore : $from.nodeAfter;
+            if (adjacent?.type.name.startsWith("composer-")) {
+              event.preventDefault();
+              event.stopPropagation();
+              view.dispatch(
+                view.state.tr
+                  .setSelection(
+                    TextSelection.create(view.state.doc, $from.pos + direction * adjacent.nodeSize),
+                  )
+                  .scrollIntoView(),
+              );
+              return true;
+            }
+          }
+          if (event.key === "Enter" && (event.isComposing || event.keyCode === 229)) {
+            event.stopPropagation();
+            return true;
+          }
+          // Enter on a focused task checkbox must not send the prompt (or
+          // split anything): Space toggles it, Enter does nothing.
+          if (event.key === "Enter" && event.target instanceof HTMLInputElement) {
+            event.preventDefault();
+            return true;
+          }
+          const handler = onCommandKeyDownRef.current;
+          if (event.key === "Enter") {
+            const instance = editorHolder.current;
+            const isTaskItem = richText && (instance?.isActive("taskItem") ?? false);
+            const handled = handler?.("Enter", event, isTaskItem) ?? false;
+            if (handled) {
+              event.preventDefault();
+              event.stopPropagation();
+              return true;
+            }
+            event.preventDefault();
+            if (
+              isTaskItem &&
+              instance &&
+              (instance.commands.splitListItem("taskItem", { checked: false }) ||
+                (view.state.selection.$from.parent.content.size === 0 &&
+                  instance.commands.liftListItem("taskItem")))
+            ) {
+              return true;
+            }
+            // Split the paragraph so a single newline visibly advances the caret.
+            return splitBlockKeepMarks(view.state, (tr) => {
+              // The split is programmatic, so the browser won't follow the
+              // caret into view on its own.
+              view.dispatch(tr.scrollIntoView());
+            });
+          }
+          if (!handler) return false;
+          const key =
+            event.key === "Tab"
+              ? ("Tab" as const)
+              : event.key === "ArrowDown"
+                ? ("ArrowDown" as const)
+                : event.key === "ArrowUp"
+                  ? ("ArrowUp" as const)
+                  : null;
+          if (!key) return false;
+          const handled = handler(key, event);
+          if (handled) {
+            event.preventDefault();
+            event.stopPropagation();
+          }
+          return handled;
+        },
+        handleTextInput: (view, from, to, text) => {
+          if (text.length !== 1) return false;
+          const closer = SURROUND_CLOSE[text];
+          if (!closer || from === to) return false;
+          // Never wrap chips or other atoms, and never wrap styled text: the
+          // default replace keeps marks intact, wrapping would drop them.
+          let touchesSpecial = false;
+          view.state.doc.nodesBetween(from, to, (node) => {
+            if (
+              (node.isAtom && node.isInline && !node.isText) ||
+              (node.isText && node.marks.length > 0)
+            ) {
+              touchesSpecial = true;
+              return false;
+            }
+            return true;
+          });
+          if (touchesSpecial) return false;
+          const map = serializeEditorDoc(view.state.doc);
+          const startMd = flatToMarkdown(map, pmToFlat(map, from));
+          const endMd = flatToMarkdown(map, pmToFlat(map, to));
+          if (selectionTouchesMentionBoundary(map.value, startMd, endMd)) return false;
+          const tr = view.state.tr.insertText(closer, to).insertText(text, from);
+          tr.setSelection(TextSelection.create(tr.doc, from + text.length, to + text.length));
+          view.dispatch(tr);

@@ -0,0 +1,586 @@
+import type { Node as ProseMirrorNode } from "@tiptap/pm/model";
+import { TaskItem } from "@tiptap/extension-task-item";
+
+import { splitPromptIntoComposerSegments } from "~/composer-editor-mentions";
+import { parseInlineMarkdown, RICH_TEXT_DELIMITERS, type RichTextMark } from "~/composer-rich-text";
+import { collectInlineContextIds } from "~/lib/composerContextReferences";
+
+/**
+ * Pure document model for the rich text (Tiptap) composer.
+ *
+ * The stored prompt stays markdown (`**bold**`, `@file` chips as canonical
+ * links). The Tiptap document holds styled text plus inline atom chips, so
+ * this module translates both ways and maps cursor offsets between the three
+ * coordinate spaces the composer speaks:
+ *
+ * - flat document offsets (styled markers excluded, chips count 1),
+ * - collapsed cursor offsets (markers literal, chips count 1 — the coordinate
+ *   the draft store and mention detection use),
+ * - markdown offsets (markers literal, chips expand to their source).
+ *
+ * DOM-free on purpose: unit tests build a real ProseMirror document from the
+ * JSON this produces and assert the round trip without a browser.
+ */
+
+export type SkillMeta = { label: string; description: string | null };
+
+/** Outermost mark first, so closers mirror openers when nested. */
+export const MARK_NESTING_ORDER: RichTextMark[] = ["strike", "bold", "italic", "code"];
+
+export const MARK_TO_TIPTAP: Record<RichTextMark, string> = {

@@ -0,0 +1,114 @@
+/**
+ * Inline markdown styling for the rich text composer.
+ *
+ * The composer's stored prompt stays plain markdown (`**bold**`), while the
+ * Tiptap surface renders styled text. These helpers translate between the two:
+ * parsing markdown into marked spans for the document, serializing marked
+ * spans back to markdown in the document serializer.
+ *
+ * Deliberately small: bold, italic, strikethrough, and inline code only.
+ * Unmatched markers stay literal text so nothing the user typed is ever lost.
+ */
+
+export type RichTextMark = "bold" | "italic" | "strike" | "code";
+
+interface RichTextSpan {
+  text: string;
+  marks: RichTextMark[];
+}
+
+export const RICH_TEXT_DELIMITERS: Record<RichTextMark, string> = {
+  bold: "**",
+  italic: "*",
+  strike: "~~",
+  code: "`",
+};
+
+function pushSpan(spans: RichTextSpan[], text: string, marks: RichTextMark[]): void {
+  if (!text) return;
+  const last = spans[spans.length - 1];
+  if (
+    last &&
+    last.marks.length === marks.length &&
+    last.marks.every((mark, index) => mark === marks[index])
+  ) {
+    last.text += text;
+  } else {
+    spans.push({ text, marks });
+  }
+}
+
+/** Parse the supported inline styles, leaving unmatched and escaped markers literal. */
+export function parseInlineMarkdown(text: string): RichTextSpan[] {
+  const root: RichTextSpan[] = [];
+  const stack: { delimiter: string; mark: RichTextMark; spans: RichTextSpan[] }[] = [];
+  const current = () => stack.at(-1)?.spans ?? root;
+  let index = 0;
+  while (index < text.length) {
+    const char = text[index]!;
+    if (char === "\\") {
+      pushSpan(current(), text.slice(index, index + 2), []);
+      index += 2;
+      continue;
+    }
+    if (char === "`") {
+      // Multi-backtick code stays literal; a single-backtick span owns its contents.
+      const run = text.slice(index).match(/^`+/)![0];
+      const close = text.indexOf(run, index + run.length);
+      if (
+        run.length === 1 &&
+        close > index + 1 &&
+        !text.slice(index, close).includes("\n") &&
+        text[close + 1] !== "`"
+      ) {
+        pushSpan(current(), text.slice(index + 1, close), ["code"]);
+        index = close + 1;
+      } else {
+        pushSpan(current(), run, []);
+        index += run.length;
+      }
+      continue;
+    }
+    if (char !== "*" && char !== "_" && char !== "~") {
+      pushSpan(current(), char, []);
+      index += 1;
+      continue;
+    }
+    let end = index;
+    while (text[end] === char) end += 1;
+    const before = text[index - 1] ?? "";
+    const after = text[end] ?? "";
+    const canClose = before !== "" && !/\s/.test(before) && (char !== "_" || !/\w/.test(after));
+    const canOpen = after !== "" && !/\s/.test(after) && (char !== "_" || !/\w/.test(before));
+    while (index < end) {
+      const top = stack.at(-1);
+      if (
+        canClose &&
+        top &&
+        text.startsWith(top.delimiter, index) &&
+        index + top.delimiter.length <= end
+      ) {
+        stack.pop();
+        for (const span of top.spans) pushSpan(current(), span.text, [top.mark, ...span.marks]);
+        index += top.delimiter.length;
+      } else if (canOpen && (char !== "~" || end - index >= 2)) {

@@ -0,0 +1,1241 @@
+import { Extension, Node, type JSONContent } from "@tiptap/core";
+import { TaskList } from "@tiptap/extension-task-list";
+import { ReactNodeViewRenderer, NodeViewWrapper, type NodeViewProps } from "@tiptap/react";
+import StarterKit from "@tiptap/starter-kit";
+import { type Node as ProseMirrorNode } from "@tiptap/pm/model";
+import { splitBlockKeepMarks } from "@tiptap/pm/commands";
+import { Plugin, PluginKey, TextSelection } from "@tiptap/pm/state";
+import { Decoration, DecorationSet } from "@tiptap/pm/view";
+import type {
+  AssistantCitation,
+  ComposerContextClipboardFragment,
+  ServerProviderSkill,
+} from "@t3tools/contracts";
+import {
+  serializeAssistantCitation,
+  withAssistantCitationComment,
+} from "@t3tools/shared/assistantCitations";
+import {
+  COMPOSER_CONTEXT_CLIPBOARD_MIME,
+  encodeComposerContextClipboardHtml,
+} from "@t3tools/shared/composerContextClipboard";
+import {
+  createContext,
+  use,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { EditorContent, useEditor } from "@tiptap/react";
+
+import {
+  clampCollapsedComposerCursor,
+  collapseExpandedComposerCursor,
+  expandCollapsedComposerCursor,
+  isCollapsedCursorAdjacentToInlineToken,
+} from "~/composer-logic";
+import { selectionTouchesMentionBoundary } from "~/composer-editor-mentions";
+import { RICH_TEXT_DELIMITERS, type RichTextMark } from "~/composer-rich-text";
+import {
+  buildDocJson,
+  buildTiptapContent,
+  collapsedToFlat,
+  ComposerTaskItemExtension,
+  flatToCollapsed,
+  flatToMarkdown,
+  flatToPm,
+  MARK_NESTING_ORDER,
+  pmToFlat,
+  serializeEditorDoc,
+  TIPTAP_TO_MARK,
+  type SkillMeta,
+} from "~/composer-rich-text-doc";
+import { collectInlineContextIds } from "~/lib/composerContextReferences";
+import { cn } from "~/lib/utils";
+import { basenameOfPath } from "~/pierre-icons";
+import {
+  COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME,
+  COMPOSER_INLINE_CHIP_ICON_CLASS_NAME,
+  COMPOSER_INLINE_CHIP_LABEL_CLASS_NAME,
+  COMPOSER_INLINE_SKILL_CHIP_CLASS_NAME,
+  SKILL_CHIP_ICON_SVG,
+} from "./composerInlineChip";
+import { FILE_TAG_CHIP_CLASS_NAME, FileTagChipContent } from "./chat/FileTagChip";
+import { AssistantCitationChip } from "./chat/AssistantCitationChip";
+import { getTimelinePageScrollKey } from "./chat/pageScrollController";
+import { ContextChipPopover } from "./contextChipParts";
+import { Button } from "./ui/button";
+import {
+  ComposerContextActionsContext,
+  ComposerContextReferenceChip,
+  ComposerContextRecordsContext,
+} from "./composerContextPresentation";
+import type { AssistantCitationSourceAnchor } from "~/lib/assistantTextSelection";
+import { formatProviderSkillDisplayName } from "@t3tools/client-runtime/providerSkills";
+import { Tooltip, TooltipPopup, TooltipTrigger } from "./ui/tooltip";
+import { importPastedComposerText } from "./composerInlineTokenPaste";
+import { didComposerSelectionChangeVisibly } from "./composerSelection";
+import type { ComposerDraftContextRecords } from "./composerContextPresentation";
+
+export interface ComposerPromptEditorHandle {
+  focus: () => void;
+  focusAt: (cursor: number) => void;
+  focusAtEnd: () => void;
+  readSelectionRange: () => { start: number; end: number };
+  requestCitationComment: (request: ComposerCitationCommentRequest) => void;
+  readSnapshot: () => {
+    value: string;
+    cursor: number;
+    expandedCursor: number;
+    contextIds: string[];
+  };
+  /**
+   * True when a collapsed caret sits on the first ("start") or last ("end")
+   * visual line, counting soft wraps. Prompt history only claims ArrowUp and
+   * ArrowDown at these edges so arrows still move the caret inside multiline
+   * text.
+   */
+  isCaretOnVisualEdge: (edge: "start" | "end") => boolean;
+}
+
+export interface ComposerPromptEditorProps {
+  value: string;
+  cursor: number;
+  /**
+   * Render Markdown styling (bold, italic, code, strike, task checkboxes).
+   * Off renders the same Tiptap engine as plain text: every marker stays a
+   * literal character.
+   */
+  richTextEnabled?: boolean;
+  /** Draft records behind the prompt's context references, keyed by context id. */
+  contextRecords: ComposerDraftContextRecords;
+  /** Structured clipboard payload for the given referenced ids, or null to skip. */
+  buildContextClipboardFragment?:
+    | ((contextIds: ReadonlyArray<string>) => string | null)
+    | undefined;
+  /** Imports a structured paste's records; returns ids that changed. */
+  importContextFragment?:
+    | ((fragment: ComposerContextClipboardFragment) => ReadonlyMap<string, string>)
+    | undefined;
+  skills: ReadonlyArray<ServerProviderSkill>;
+  disabled: boolean;
+  placeholder: string;
+  containerClassName?: string;
+  className?: string;
+  placeholderClassName?: string;
+  onChange: (
+    nextValue: string,
+    nextCursor: number,
+    expandedCursor: number,
+    cursorAdjacentToMention: boolean,
+    contextIds: string[],
+  ) => void;
+  onVisibleSelectionChange?: () => void;
+  onCommandKeyDown?: (
+    key: "ArrowDown" | "ArrowUp" | "Enter" | "Tab",
+    event: KeyboardEvent,
+  ) => boolean;
+  onPageScrollKeyDown?: (key: "PageUp" | "PageDown") => void;
+  onPageScrollKeyUp?: (key: string) => void;
+  onPageScrollRelease?: () => void;
+  onCitationSubmitAndSend?: () => void;
+  onPaste: React.ClipboardEventHandler<HTMLElement>;
+  editorRef: React.RefObject<ComposerPromptEditorHandle | null>;
+}
+
+export type ComposerCitationCommentRequest = {
+  previousValue: string;
+  value: string;
+  citationStart: number;
+  sourceAnchor: AssistantCitationSourceAnchor;
+};
+
+type OpenCitationComment = {
+  key: string;
+  sourceAnchor?: AssistantCitationSourceAnchor;
+  removeOnCancel?: boolean;
+};
+
+const ComposerCitationCommentContext = createContext<{
+  openComment: OpenCitationComment | null;
+  onOpenChange: (citeKey: string, open: boolean) => void;
+  onSubmitAndSend: () => void;
+}>({ openComment: null, onOpenChange: () => {}, onSubmitAndSend: () => {} });
+
+const RichComposerSkillsContext = createContext<ReadonlyArray<ServerProviderSkill>>([]);
+
+const SURROUND_CLOSE: Record<string, string> = {
+  "(": ")",
+  "[": "]",
+  "{": "}",
+  "'": "'",
+  '"': '"',
+  "“": "”",
+  "`": "`",
+  "<": ">",
+  "«": "»",
+  "*": "*",
+  _: "_",
+};
+
+function resolvedThemeFromDocument(): "light" | "dark" {
+  return document.documentElement.classList.contains("dark") ? "dark" : "light";
+}
+
+// ── Inline atom nodes (chips) ─────────────────────────────────────────────
+
+const ComposerMentionExtension = Node.create({
+  name: "composer-mention",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      path: { default: "" },
+      source: { default: "" },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-mention]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-mention": "", ...HTMLAttributes }, 0];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerMentionNodeView);
+  },
+});
+
+function ComposerMentionNodeView({ node }: NodeViewProps) {
+  const actions = use(ComposerContextActionsContext);
+  const path = (node.attrs.path as string) ?? "";
+  const chip = (
+    <button
+      type="button"
+      onClick={() => actions.openMention(path)}
+      aria-label={`Preview ${path}`}
+      className={`${FILE_TAG_CHIP_CLASS_NAME} cursor-pointer focus-visible:outline-2`}
+      contentEditable={false}
+      spellCheck={false}
+      data-composer-mention-chip="true"
+    >
+      <FileTagChipContent
+        path={path}
+        label={basenameOfPath(path)}
+        theme={resolvedThemeFromDocument()}
+      />
+    </button>
+  );
+  return (
+    <NodeViewWrapper as="span" className={COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME}>
+      <Tooltip>
+        <TooltipTrigger render={chip} />
+        <TooltipPopup
+          side="top"
+          className="max-w-120 whitespace-normal leading-tight wrap-anywhere"
+        >
+          {path}
+        </TooltipPopup>
+      </Tooltip>
+    </NodeViewWrapper>
+  );
+}
+
+const ComposerSkillExtension = Node.create({
+  name: "composer-skill",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      skillName: { default: "" },
+      skillLabel: { default: "" },
+      skillDescription: { default: null },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-skill]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-skill": "", ...HTMLAttributes }, 0];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerSkillNodeView);
+  },
+});
+
+function ComposerSkillNodeView({ node }: NodeViewProps) {
+  const actions = use(ComposerContextActionsContext);
+  const skills = use(RichComposerSkillsContext);
+  const skillName = (node.attrs.skillName as string) ?? "";
+  const skillLabel = (node.attrs.skillLabel as string) || skillName;
+  const skillDescription = (node.attrs.skillDescription as string | null) ?? null;
+  const skill = skills.find((candidate) => candidate.name === skillName);
+  return (
+    <NodeViewWrapper as="span" className={COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME}>
+      <ContextChipPopover
+        accessibleLabel={`Skill ${skillLabel}`}
+        triggerClassName={COMPOSER_INLINE_SKILL_CHIP_CLASS_NAME}
+        chip={
+          <>
+            <span
+              aria-hidden="true"
+              className={COMPOSER_INLINE_CHIP_ICON_CLASS_NAME}
+              dangerouslySetInnerHTML={{ __html: SKILL_CHIP_ICON_SVG }}
+            />
+            <span className={COMPOSER_INLINE_CHIP_LABEL_CLASS_NAME}>{skillLabel}</span>
+          </>
+        }
+      >
+        <div className="space-y-3 p-2 text-sm">
+          <p className="font-medium">{skillLabel}</p>
+          <p>
+            {skill?.description ??
+              skillDescription ??
+              "No description is available for this skill."}
+          </p>
+          {skill?.path ? (
+            <Button variant="outline" size="sm" onClick={() => actions.openMention(skill.path)}>
+              View instructions
+            </Button>
+          ) : null}
+        </div>
+      </ContextChipPopover>
+    </NodeViewWrapper>
+  );
+}
+
+const ComposerCitationExtension = Node.create({
+  name: "composer-citation",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      citation: { default: null },
+      source: { default: "" },
+      citeKey: { default: "" },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-citation]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-citation": "", ...HTMLAttributes }, 0];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerCitationNodeView);
+  },
+});
+
+function ComposerCitationNodeView({ node, editor, getPos }: NodeViewProps) {
+  const commentContext = use(ComposerCitationCommentContext);
+  const citation = node.attrs.citation as AssistantCitation;
+  const citeKey = node.attrs.citeKey as string;
+  const commentTarget =
+    commentContext.openComment?.key === citeKey ? commentContext.openComment : null;
+
+  const nodePos = useCallback(() => {
+    const pos = typeof getPos === "function" ? getPos() : null;
+    return typeof pos === "number" ? pos : null;
+  }, [getPos]);
+
+  const onSaveComment = useCallback(
+    (comment: string): boolean => {
+      if (!editor.isEditable) return false;
+      const pos = nodePos();
+      if (pos === null) return false;
+      const current = editor.state.doc.nodeAt(pos);
+      if (!current || current.type.name !== "composer-citation") return false;
+      const currentCitation = current.attrs.citation as AssistantCitation;
+      const next = withAssistantCitationComment(currentCitation, comment);
+      const tr = editor.state.tr.setNodeMarkup(pos, undefined, {
+        ...current.attrs,
+        citation: next,
+        source: serializeAssistantCitation(next),
+      });
+      editor.view.dispatch(tr);
+      return true;
+    },
+    [editor, nodePos],
+  );
+
+  const onRemove = useCallback(() => {
+    if (!editor.isEditable) return;
+    const pos = nodePos();
+    if (pos === null) return;
+    const current = editor.state.doc.nodeAt(pos);
+    if (!current) return;
+    editor
+      .chain()
+      .focus()
+      .deleteRange({ from: pos, to: pos + current.nodeSize })
+      .run();
+  }, [editor, nodePos]);
+
+  return (
+    <NodeViewWrapper
+      as="span"
+      className="inline-flex min-w-0 max-w-full"
+      contentEditable={false}
+      spellCheck={false}
+      data-composer-citation-chip="true"
+    >
+      <AssistantCitationChip
+        citation={citation}
+        composer
+        commentEditor={{
+          open: commentTarget !== null,
+          sourceAnchor: commentTarget?.sourceAnchor,
+          onOpenChange: (open) => {
+            if (open && !editor.isEditable) return;
+            commentContext.onOpenChange(citeKey, open);
+          },
+          ...(commentTarget?.removeOnCancel ? { onCancel: onRemove } : {}),
+          onSave: onSaveComment,
+          onSaveAndSend: (comment) => {
+            if (!onSaveComment(comment)) return false;
+            commentContext.onSubmitAndSend();
+            return true;
+          },
+        }}
+      />
+    </NodeViewWrapper>
+  );
+}
+
+const ComposerContextReferenceExtension = Node.create({
+  name: "composer-context-reference",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      kind: { default: "" },
+      contextId: { default: "" },
+      label: { default: "" },
+      source: { default: "" },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-context-reference]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-context-reference": "", ...HTMLAttributes }, 0];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerContextReferenceNodeView);
+  },
+});
+
+function ComposerContextReferenceNodeView({ node }: NodeViewProps) {
+  return (
+    <NodeViewWrapper as="span" className={COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME}>
+      <ComposerContextReferenceChip
+        kind={(node.attrs.kind as string) ?? ""}
+        contextId={(node.attrs.contextId as string) ?? ""}
+        label={(node.attrs.label as string) ?? ""}
+      />
+    </NodeViewWrapper>
+  );
+}
+
+// ── Marker reveal (show ** when the cursor is on styled text) ──────────────
+
+type StyledRange = {
+  from: number;
+  to: number;
+  delimiter: string;
+};
+
+function collectStyledRanges(doc: ProseMirrorNode): StyledRange[] {
+  const ranges: StyledRange[] = [];
+  doc.descendants((node, pos) => {
+    if (!node.isText || !node.text) return true;
+    const marks = (node.marks ?? [])
+      .map((mark) => TIPTAP_TO_MARK[mark.type.name])
+      .filter((mark): mark is RichTextMark => Boolean(mark));
+    if (marks.length === 0) return false;
+    const ordered = [...marks].sort(
+      (a, b) => MARK_NESTING_ORDER.indexOf(a) - MARK_NESTING_ORDER.indexOf(b),
+    );
+    const delimiter = ordered.map((mark) => RICH_TEXT_DELIMITERS[mark]).join("");
+    const last = ranges[ranges.length - 1];
+    if (last && last.to === pos && last.delimiter === delimiter) {
+      last.to = pos + (node.text?.length ?? 0);
+    } else {
+      ranges.push({ from: pos, to: pos + (node.text?.length ?? 0), delimiter });
+    }
+    return false;
+  });
+  return ranges;
+}
+
+const MarkerPluginKey = new PluginKey("composer-rich-markers");
+
+const ComposerMarkerPlugin = new Plugin({
+  key: MarkerPluginKey,
+  state: {
+    init: (_, state) => decorationsForSelection(state.doc, state.selection),
+    apply: (tr, old) =>
+      tr.docChanged || tr.selectionSet ? decorationsForSelection(tr.doc, tr.selection) : old,
+  },
+  props: {
+    decorations(state) {
+      return MarkerPluginKey.getState(state);
+    },
+  },
+});
+
+function decorationsForSelection(
+  doc: ProseMirrorNode,
+  selection: { from: number; to: number; empty: boolean },
+): DecorationSet {
+  const decorations: Decoration[] = [];
+  for (const range of collectStyledRanges(doc)) {
+    const active = selection.empty
+      ? selection.from >= range.from && selection.from <= range.to
+      : selection.from < range.to && selection.to > range.from;
+    if (!active) continue;
+    for (const [at, side] of [
+      [range.from, -1],
+      [range.to, 1],
+    ] as const) {
+      const marker = document.createElement("span");
+      marker.className = "composer-rich-marker";
+      marker.textContent = range.delimiter;
+      marker.setAttribute("aria-hidden", "true");
+      decorations.push(Decoration.widget(at, marker, { side, key: `marker-${at}-${side}` }));
+    }
+  }
+  return DecorationSet.create(doc, decorations);
+}
+
+const ComposerMarkersExtension = Extension.create({
+  name: "composer-rich-markers",
+  addProseMirrorPlugins() {
+    return [ComposerMarkerPlugin];
+  },
+});
+
+// Document model (markdown ⇄ ProseMirror) lives in ~/composer-rich-text-doc so
+// unit tests can round-trip it without a browser.
+// ── Editor component ───────────────────────────────────────────────────────
+
+type TiptapEditor = NonNullable<ReturnType<typeof useEditor>>;
+
+export function ComposerPromptEditorTiptap(props: ComposerPromptEditorProps) {
+  // Extensions are creation-time: flipping the setting remounts the editor.
+  // Both halves initialize from the controlled Markdown value, so the draft
+  // survives the flip.
+  return (
+    <ComposerPromptEditorTiptapInner key={props.richTextEnabled ? "rich" : "plain"} {...props} />
+  );
+}
+
+function ComposerPromptEditorTiptapInner(props: ComposerPromptEditorProps) {
+  const {
+    value,
+    cursor,
+    richTextEnabled,
+    contextRecords,
+    buildContextClipboardFragment,
+    importContextFragment,
+    skills,
+    disabled,
+    placeholder,
+    containerClassName,
+    className,
+    placeholderClassName,
+    onChange,
+    onVisibleSelectionChange,
+    onCommandKeyDown,
+    onPageScrollKeyDown,
+    onPageScrollKeyUp,
+    onPageScrollRelease,
+    onCitationSubmitAndSend,
+    onPaste,
+    editorRef,
+  } = props;
+  // The setting toggles styling, not the engine: both modes are Tiptap.
+  // Plain mode disables the mark extensions, so markers stay literal text.
+  const richText = richTextEnabled ?? false;
+
+  const onChangeRef = useRef(onChange);
+  const onVisibleSelectionChangeRef = useRef(onVisibleSelectionChange);
+  const onCommandKeyDownRef = useRef(onCommandKeyDown);
+  const buildFragmentRef = useRef(buildContextClipboardFragment);
+  const importFragmentRef = useRef(importContextFragment);
+  const skillsRef = useRef(skills);
+  const latestValueRef = useRef(value);
+  // The editor instance for callbacks created before it exists (paste).
+  // Effects flush before any user interaction, so this is always set.
+  const editorHolder = useRef<TiptapEditor | null>(null);
+
+  useEffect(() => {
+    onChangeRef.current = onChange;
+  }, [onChange]);
+  useEffect(() => {
+    onVisibleSelectionChangeRef.current = onVisibleSelectionChange;
+  }, [onVisibleSelectionChange]);
+  useEffect(() => {
+    onCommandKeyDownRef.current = onCommandKeyDown;
+  }, [onCommandKeyDown]);
+  useEffect(() => {
+    buildFragmentRef.current = buildContextClipboardFragment;
+  }, [buildContextClipboardFragment]);
+  useEffect(() => {
+    importFragmentRef.current = importContextFragment;
+  }, [importContextFragment]);
+  useEffect(() => {
+    skillsRef.current = skills;
+  }, [skills]);
+  useLayoutEffect(() => {
+    latestValueRef.current = value;
+  }, [value]);
+
+  const skillLabelFor = useCallback((name: string): SkillMeta => {
+    const normalized = name.startsWith("$") ? name.slice(1) : name;
+    const skill = skillsRef.current.find((candidate) => candidate.name === normalized);
+    if (!skill) {
+      return { label: formatProviderSkillDisplayName({ name: normalized }), description: null };
+    }
+    const shortDescription = skill.shortDescription?.trim();
+    return {
+      label: formatProviderSkillDisplayName(skill),
+      description: shortDescription || skill.description?.trim() || null,
+    };
+  }, []);
+
+  const initialCursor = clampCollapsedComposerCursor(value, cursor);
+  const initialExpandedCursor = expandCollapsedComposerCursor(value, initialCursor);
+  const snapshotRef = useRef({
+    value,
+    cursor: initialCursor,
+    expandedCursor: initialExpandedCursor,
+    contextIds: collectInlineContextIds(value),
+  });
+  const selectionRangeRef = useRef({ start: initialExpandedCursor, end: initialExpandedCursor });
+  const isApplyingControlledUpdateRef = useRef(false);
+  const citationRequestRef = useRef<ComposerCitationCommentRequest | null>(null);
+  const [openCitation, setOpenCitation] = useState<OpenCitationComment | null>(null);
+  const [isEmpty, setIsEmpty] = useState(value.length === 0);
+
+  const citationCommentActions = useMemo(
+    () => ({
+      openComment: openCitation,
+      onOpenChange: (nodeKey: string, open: boolean) => {
+        setOpenCitation((current) => {
+          if (open) {
+            if (current?.key === nodeKey) return current;
+            return { key: nodeKey };
+          }
+          return current?.key === nodeKey ? null : current;
+        });
+      },
+      onSubmitAndSend: onCitationSubmitAndSend ?? (() => {}),
+    }),
+    [onCitationSubmitAndSend, openCitation],
+  );
+
+  const handleEditorChange = useCallback((updated: TiptapEditor) => {
+    const map = serializeEditorDoc(updated.state.doc);
+    const { from, to } = updated.state.selection;
+    const fromFlat = pmToFlat(map, from);
+    const toFlat = pmToFlat(map, to);
+    const nextValue = map.value;
+    const nextCursor = clampCollapsedComposerCursor(map.value, flatToCollapsed(map, fromFlat));
+    const nextExpandedCursor = Math.max(
+      0,
+      Math.min(map.value.length, flatToMarkdown(map, fromFlat)),
+    );
+    const nextSelectionRange = {
+      start: Math.min(nextExpandedCursor, flatToMarkdown(map, toFlat)),
+      end: Math.max(nextExpandedCursor, flatToMarkdown(map, toFlat)),
+    };
+    const previousSelectionRange = selectionRangeRef.current;
+    selectionRangeRef.current = nextSelectionRange;
+    setIsEmpty(nextValue.length === 0);
+    const previousSnapshot = snapshotRef.current;
+    const snapshotChanged = !(
+      previousSnapshot.value === nextValue &&
+      previousSnapshot.cursor === nextCursor &&
+      previousSnapshot.expandedCursor === nextExpandedCursor &&
+      previousSnapshot.contextIds.length === map.contextIds.length &&
+      previousSnapshot.contextIds.every((id, index) => id === map.contextIds[index])
+    );
+    if (isApplyingControlledUpdateRef.current) return;
+    if (!snapshotChanged) {
+      if (didComposerSelectionChangeVisibly(previousSelectionRange, nextSelectionRange)) {
+        onVisibleSelectionChangeRef.current?.();
+      }
+      return;
+    }
+    // A selection-only update while a newer prompt waits to be applied (a chip
+    // was just inserted through the store) would report stale text and clobber
+    // the prompt. Let the controlled rewrite land instead.
+    if (previousSnapshot.value === nextValue && nextValue !== latestValueRef.current) {
+      return;
+    }
+    snapshotRef.current = {
+      value: nextValue,
+      cursor: nextCursor,
+      expandedCursor: nextExpandedCursor,
+      contextIds: map.contextIds,
+    };
+    const cursorAdjacentToMention =
+      isCollapsedCursorAdjacentToInlineToken(nextValue, nextCursor, "left") ||
+      isCollapsedCursorAdjacentToInlineToken(nextValue, nextCursor, "right");
+    onChangeRef.current(
+      nextValue,
+      nextCursor,
+      nextExpandedCursor,
+      cursorAdjacentToMention,
+      map.contextIds,
+    );
+  }, []);
+
+  const editor = useEditor(
+    {
+      extensions: [
+        StarterKit.configure({
+          blockquote: false,
+          bulletList: false,
+          codeBlock: false,
+          heading: false,
+          horizontalRule: false,
+          listItem: false,
+          orderedList: false,
+          dropcursor: false,
+          gapcursor: false,
+          trailingNode: false,
+          // Plain mode has no marks: typed markers stay literal characters.
+          ...(richText ? {} : { bold: false, italic: false, strike: false, code: false }),
+        }),
+        ComposerMentionExtension,
+        ComposerSkillExtension,
+        ComposerCitationExtension,
+        ComposerContextReferenceExtension,
+        TaskList,
+        ComposerTaskItemExtension,
+        ComposerMarkersExtension,
+      ],
+      content: buildDocJson(
+        value,
+        (name) => {
+          const normalized = name.startsWith("$") ? name.slice(1) : name;
+          const found = skills.find((candidate) => candidate.name === normalized);
+          if (!found) {
+            return {
+              label: formatProviderSkillDisplayName({ name: normalized }),
+              description: null,
+            };
+          }
+          const shortDescription = found.shortDescription?.trim();
+          return {
+            label: formatProviderSkillDisplayName(found),
+            description: shortDescription || found.description?.trim() || null,
+          };
+        },
+        { styling: richText },
+      ),
+      editable: !disabled,
+      editorProps: {
+        attributes: {
+          class: cn(
+            "composer-tiptap block max-h-50 min-h-17.5 w-full overflow-y-auto whitespace-pre-wrap wrap-break-word bg-transparent leading-relaxed text-foreground focus:outline-none",
+            className,
+          ),
+          "data-testid": "composer-editor",
+          "data-composer-rich-text": richText ? "true" : "false",
+          "aria-placeholder": placeholder,
+        },
+        handleKeyDown: (view, event) => {
+          if (event.key === "Enter" && (event.isComposing || event.keyCode === 229)) {
+            event.stopPropagation();
+            return true;
+          }
+          // Enter on a focused task checkbox must not send the prompt (or
+          // split anything): Space toggles it, Enter does nothing.
+          if (event.key === "Enter" && event.target instanceof HTMLInputElement) {
+            event.preventDefault();
+            return true;
+          }
+          const handler = onCommandKeyDownRef.current;
+          if (event.key === "Enter") {
+            const handled = handler?.("Enter", event) ?? false;
+            if (handled) {
+              event.preventDefault();
+              event.stopPropagation();
+              return true;
+            }
+            // A newline the parent declined (Shift+Enter, or Enter while the
+            // shortcut says otherwise) must be one visible line. Letting it
+            // fall through inserts a native trailing `<br>`, which renders
+            // no visible line, so the caret looks stuck until a second press.
+            // Splitting the paragraph gives one press, one visible line:
+            // letting it fall through would insert a native trailing `<br>`,
+            // which renders no visible line. Enter on a list line never gets
+            // here — the parent claims it for continuation — so Tiptap's
+            // list splitting stays shadowed.
+            event.preventDefault();
+            return splitBlockKeepMarks(view.state, (tr) => {
+              // The split is programmatic, so the browser won't follow the
+              // caret into view on its own.
+              view.dispatch(tr.scrollIntoView());
+            });
+          }
+          if (!handler) return false;

@@ -0,0 +1,237 @@
+/**
+ * Inline markdown styling for the rich text composer.
+ *
+ * The composer's stored prompt stays plain markdown (`**bold**`), while the
+ * Tiptap surface renders styled text. These helpers translate between the two:
+ * parsing markdown into marked spans for the document, serializing marked
+ * spans back to markdown, and mapping cursor offsets between document
+ * coordinates (markers excluded) and markdown coordinates (markers included).
+ *
+ * Deliberately small: bold, italic, strikethrough, and inline code only.
+ * Unmatched markers stay literal text so nothing the user typed is ever lost.
+ */
+
+export type RichTextMark = "bold" | "italic" | "strike" | "code";
+
+export interface RichTextSpan {
+  text: string;
+  marks: RichTextMark[];
+}
+
+export interface RichMarkRange {
+  /** Document-text coordinates (markers excluded), end-exclusive. */
+  start: number;
+  end: number;
+  marks: RichTextMark[];
+}
+
+export const RICH_TEXT_DELIMITERS: Record<RichTextMark, string> = {
+  bold: "**",
+  italic: "*",
+  strike: "~~",
+  code: "`",
+};
+
+/** Nesting order, outermost first, used when several marks share a span. */
+const MARK_ORDER: RichTextMark[] = ["strike", "bold", "italic", "code"];
+
+function sortMarks(marks: RichTextMark[]): RichTextMark[] {
+  return [...marks].sort((a, b) => MARK_ORDER.indexOf(a) - MARK_ORDER.indexOf(b));
+}
+
+function pushSpan(spans: RichTextSpan[], text: string, marks: RichTextMark[]): void {
+  if (!text) return;
+  const sorted = sortMarks(marks);
+  const last = spans[spans.length - 1];
+  if (
+    last &&
+    last.marks.length === sorted.length &&
+    last.marks.every((mark, index) => mark === sorted[index])
+  ) {
+    last.text += text;
+    return;
+  }
+  spans.push({ text, marks: sorted });
+}
+
+function matchAt(pattern: RegExp, text: string, index: number): RegExpMatchArray | null {
+  pattern.lastIndex = index;
+  const match = pattern.exec(text);
+  return match && match.index === index ? match : null;
+}
+
+// Code spans are parsed first so `**` inside backticks stays literal.
+const CODE_PATTERN = /`([^`\n]+?)`/gy;
+const BOLD_PATTERN = /(\*\*(?=[^\s*])(.+?)(?<=[^\s*])\*\*|__(?=[^\s_])(.+?)(?<=[^\s_])__)/gy;
+const STRIKE_PATTERN = /~~(?=[^\s~])(.+?)(?<=[^\s~])~~/gy;
+// Single `*` emphasis. Bold is consumed before this runs, so a leftover `*`
+// pair is italic. Underscore emphasis requires non-word boundaries on both
+// sides so snake_case identifiers keep their underscores.
+const ITALIC_STAR_PATTERN = /\*(?=[^\s*])(.+?)(?<=[^\s*])\*/gy;
+const ITALIC_UNDERSCORE_PATTERN = /(?<=^|[^\w])_(?=[^\s_])(.+?)(?<=[^\s_])_(?=$|[^\w])/gy;
+
+function parseNonCodeSpans(text: string, spans: RichTextSpan[], outer: RichTextMark[]): void {
+  let index = 0;
+  let literalStart = 0;
+  const flushLiteral = (end: number) => {
+    if (end > literalStart) pushSpan(spans, text.slice(literalStart, end), outer);
+    literalStart = end;
+  };
+
+  while (index < text.length) {
+    const bold = matchAt(BOLD_PATTERN, text, index);
+    if (bold) {
+      flushLiteral(index);
+      const inner = bold[2] ?? bold[3] ?? "";
+      // Recurse so `**a *b* c**` keeps the italic on `b`.
+      parseNonCodeSpans(inner, spans, [...outer, "bold"]);
+      index += bold[0].length;
+      literalStart = index;
+      continue;
+    }
+    const strike = matchAt(STRIKE_PATTERN, text, index);
+    if (strike) {
+      flushLiteral(index);
+      parseNonCodeSpans(strike[1] ?? "", spans, [...outer, "strike"]);

@@ -0,0 +1,586 @@
+import type { Node as ProseMirrorNode } from "@tiptap/pm/model";
+import { TaskItem } from "@tiptap/extension-task-item";
+
+import { splitPromptIntoComposerSegments } from "~/composer-editor-mentions";
+import { parseInlineMarkdown, RICH_TEXT_DELIMITERS, type RichTextMark } from "~/composer-rich-text";
+import { collectInlineContextIds } from "~/lib/composerContextReferences";
+
+/**
+ * Pure document model for the rich text (Tiptap) composer.
+ *
+ * The stored prompt stays markdown (`**bold**`, `@file` chips as canonical
+ * links). The Tiptap document holds styled text plus inline atom chips, so
+ * this module translates both ways and maps cursor offsets between the three
+ * coordinate spaces the composer speaks:
+ *
+ * - flat document offsets (styled markers excluded, chips count 1),
+ * - collapsed cursor offsets (markers literal, chips count 1 — the coordinate
+ *   the draft store and mention detection use),
+ * - markdown offsets (markers literal, chips expand to their source).
+ *
+ * DOM-free on purpose: unit tests build a real ProseMirror document from the
+ * JSON this produces and assert the round trip without a browser.
+ */
+
+export type SkillMeta = { label: string; description: string | null };
+
+/** Outermost mark first, so closers mirror openers when nested. */
+export const MARK_NESTING_ORDER: RichTextMark[] = ["strike", "bold", "italic", "code"];
+
+export const MARK_TO_TIPTAP: Record<RichTextMark, string> = {
+  bold: "bold",
+  italic: "italic",
+  strike: "strike",
+  code: "code",
+};
+
+export const TIPTAP_TO_MARK: Record<string, RichTextMark> = {
+  bold: "bold",
+  italic: "italic",
+  strike: "strike",
+  code: "code",
+};
+
+/**
+ * Task list items keep their exact source indent in an attribute so nesting
+ * round-trips byte-identically. Checkbox case (`[X]`) normalizes to `[x]` —
+ * the same fixed-point deal as `__bold__` becoming `**bold**`.
+ */
+export const ComposerTaskItemExtension = TaskItem.extend({
+  addAttributes() {
+    return {
+      ...this.parent?.(),
+      indent: { default: "" },
+    };
+  },
+}).configure({ nested: true });
+
+export function randomNodeKey(): string {
+  return `tiptap-${Math.random().toString(36).slice(2)}`;
+}
+
+interface TaskLinePrefix {
+  indent: string;
+  checked: boolean;
+}
+
+function parseTaskPrefix(head: string): { prefix: TaskLinePrefix; markerLength: number } | null {
+  const match = head.match(/^([ \t]*)-[ \t]+\[([ xX])\]/);
+  if (!match) return null;
+  const after = head.slice(match[0].length);
+  if (after.length > 0 && after[0] !== " " && after[0] !== "\t") return null;
+  return {
+    prefix: {
+      indent: match[1] ?? "",
+      checked: (match[2] ?? " ").toLowerCase() === "x",
+    },
+    markerLength: match[0].length,
+  };
+}
+
+type InlineJson = Record<string, unknown>;
+
+interface DocLine {
+  task: TaskLinePrefix | null;
+  inline: InlineJson[];
+}
+
+function atomJsonForSegment(
+  segment: Exclude<ReturnType<typeof splitPromptIntoComposerSegments>[number], { type: "text" }>,
+  skillLabelFor: (name: string) => SkillMeta,
+): InlineJson {
+  if (segment.type === "mention") {
+    return {
+      type: "composer-mention",
+      attrs: { path: segment.path, source: segment.source },
+    };
+  }
+  if (segment.type === "skill") {
+    const meta = skillLabelFor(segment.name);
+    return {
+      type: "composer-skill",
+      attrs: {
+        skillName: segment.name,
+        skillLabel: meta.label,
+        skillDescription: meta.description,
+      },
+    };
+  }
+  if (segment.type === "citation") {
+    return {
+      type: "composer-citation",
+      attrs: { citation: segment.citation, source: segment.source, citeKey: randomNodeKey() },
+    };
+  }
+  return {
+    type: "composer-context-reference",
+    attrs: {
+      kind: segment.kind,
+      contextId: segment.contextId,
+      label: segment.label,
+      source: segment.source,
+    },
+  };
+}
+
+function pushSpans(inline: InlineJson[], text: string): void {
+  for (const span of parseInlineMarkdown(text)) {
+    inline.push(textJsonForSpan(span.text, span.marks));
+  }
+}
+
+interface PendingTaskItem {
+  checked: boolean;
+  indent: string;
+  content: InlineJson[];
+  children: PendingTaskItem[];
+}
+
+function taskListJson(items: PendingTaskItem[]): InlineJson {
+  return {
+    type: "taskList",
+    content: items.map((item) => ({
+      type: "taskItem",
+      attrs: { checked: item.checked, indent: item.indent },
+      content: [
+        { type: "paragraph", content: item.content },
+        ...(item.children.length > 0 ? [taskListJson(item.children)] : []),
+      ],
+    })),
+  };
+}
+
+function textJsonForSpan(text: string, marks: RichTextMark[]): Record<string, unknown> {
+  const json: Record<string, unknown> = { type: "text", text };
+  if (marks.length > 0) {
+    json.marks = [...marks]
+      .sort((a, b) => MARK_NESTING_ORDER.indexOf(a) - MARK_NESTING_ORDER.indexOf(b))
+      .map((mark) => ({ type: MARK_TO_TIPTAP[mark] }));
+  }
+  return json;
+}
+
+export function buildTiptapContent(
+  value: string,
+  skillLabelFor: (name: string) => SkillMeta,
+): Record<string, unknown>[] {
+  // Pass 1: the segment stream becomes lines. A line is a task line only
+  // when its leading text — before any chip — is a complete `- [ ]` marker;
+  // the marker is decided at a chip, a newline, or the end of input so a
+  // partial marker (`- [ ]` + `foo`) can never commit early.
+  const lines: DocLine[] = [{ task: null, inline: [] }];
+  let head: string | null = "";
+  const currentLine = () => lines[lines.length - 1]!;
+  const endLine = () => {
+    const line = currentLine();
+    if (head !== null) {
+      const parsed = parseTaskPrefix(head);
+      if (parsed) {
+        line.task = parsed.prefix;
+        pushSpans(line.inline, head.slice(parsed.markerLength).replace(/^[ \t]*/, ""));
+      } else {
+        pushSpans(line.inline, head);
+      }
+    }
+    lines.push({ task: null, inline: [] });
+    head = "";
+  };
+  const appendTextPiece = (piece: string) => {
+    if (head !== null) {
+      head += piece;
+      return;
+    }
+    pushSpans(currentLine().inline, piece);
+  };
+
+  for (const segment of splitPromptIntoComposerSegments(value)) {
+    if (segment.type === "text") {
+      const parts = segment.text.split("\n");
+      parts.forEach((part, index) => {
+        if (index > 0) endLine();
+        appendTextPiece(part);
+      });
+    } else {
+      if (head !== null) {
+        const line = currentLine();
+        const parsed = parseTaskPrefix(head);
+        if (parsed) {
+          line.task = parsed.prefix;
+          pushSpans(line.inline, head.slice(parsed.markerLength).replace(/^[ \t]*/, ""));
+        } else {
+          pushSpans(line.inline, head);
+        }
+        head = null;
+      }
+      currentLine().inline.push(atomJsonForSegment(segment, skillLabelFor));
+    }
+  }
+  // Decide the final line. A trailing newline leaves a fresh empty line,
+  // which endLine already pushed — drop the spare blank it would add.
+  if (head !== null) {
+    const line = currentLine();
+    const parsed = parseTaskPrefix(head);
+    if (parsed) {
+      line.task = parsed.prefix;
+      pushSpans(line.inline, head.slice(parsed.markerLength).replace(/^[ \t]*/, ""));
+    } else {
+      pushSpans(line.inline, head);
+    }
+  } else if (lines.length > 1) {
+    const last = lines[lines.length - 1]!;
+    if (!last.task && last.inline.length === 0) lines.pop();
+  }
+
+  // Pass 2: consecutive task lines group into (possibly nested) task lists
+  // by indent prefix; everything else stays a paragraph.
+  const blocks: Record<string, unknown>[] = [];
+  let stack: { indent: string; items: PendingTaskItem[] }[] = [];
+  const flushTasks = () => {
+    if (stack.length > 0) {
+      blocks.push(taskListJson(stack[0]!.items));
+      stack = [];
+    }
+  };
+  for (const line of lines) {
+    if (!line.task) {
+      flushTasks();
+      blocks.push({ type: "paragraph", content: line.inline });
+      continue;
+    }
+    const item: PendingTaskItem = {
+      checked: line.task.checked,
+      indent: line.task.indent,
+      content: line.inline,
+      children: [],
+    };
+    for (;;) {
+      const top = stack[stack.length - 1];
+      if (!top) {
+        // A leading indented item with no parent flattens but keeps indent.
+        stack.push({ indent: "", items: [] });
+        continue;
+      }
+      if (top.indent === item.indent) {
+        top.items.push(item);
+        break;
+      }
+      if (top.indent !== "" && !item.indent.startsWith(top.indent)) {
+        stack.pop();
+        continue;
+      }
+      const parent = top.items[top.items.length - 1];
+      if (!parent) {
+        top.items.push(item);
+        break;
+      }
+      parent.children.push(item);
+      stack.push({ indent: item.indent, items: parent.children });
+      break;
+    }
+  }
+  flushTasks();
+  return blocks;
+}
+
+export function buildDocJson(value: string, skillLabelFor: (name: string) => SkillMeta) {
+  return { type: "doc", content: buildTiptapContent(value, skillLabelFor) };
+}
+
+export interface RichRun {
+  kind: "text" | "token" | "break" | "prefix";
+  /** Flat document offset (atoms count 1, markers excluded). */
+  flatStart: number;
+  docLen: number;
+  /** Collapsed cursor length (markers literal, tokens count 1). */
+  collapsedLen: number;
+  /** Markdown length (tokens expand to their source). */
+  mdLen: number;
+  /** Marker layout inside text runs. */
+  openLen: number;
+  closeLen: number;
+  /** ProseMirror position of the run start. */
+  pmPos: number;
+  mdStart: number;
+  collapsedStart: number;
+  nodeName?: string;
+}
+
+export interface RichDocMap {
+  value: string;
+  runs: RichRun[];
+  docLength: number;
+  contextIds: string[];
+}
+
+function textRunDelimiters(marks: RichTextMark[]): { open: string; close: string } {
+  let open = "";
+  let close = "";
+  for (const mark of [...marks].sort(
+    (a, b) => MARK_NESTING_ORDER.indexOf(a) - MARK_NESTING_ORDER.indexOf(b),
+  )) {
+    const delimiter = RICH_TEXT_DELIMITERS[mark];
+    open = open + delimiter;
+    close = delimiter + close;
+  }
+  return { open, close };
+}
+
+function readAtomSource(node: ProseMirrorNode): string {
+  const attrs = node.attrs as Record<string, unknown>;
+  switch (node.type.name) {
+    case "composer-mention":
+    case "composer-citation":
+    case "composer-context-reference":
+      return typeof attrs.source === "string" ? attrs.source : "";
+    case "composer-skill": {
+      const name = typeof attrs.skillName === "string" ? attrs.skillName : "";
+      return name ? `$${name}` : "";
+    }
+    default:
+      return "";
+  }
+}
+
+interface RichAccumulator {
+  runs: RichRun[];
+  value: string;
+  flat: number;
+  collapsed: number;
+  md: number;
+}
+
+function pushBreakRun(acc: RichAccumulator, pmPos: number): void {
+  // Block boundary: one newline in every coordinate space.
+  acc.runs.push({
+    kind: "break",
+    flatStart: acc.flat,
+    docLen: 1,
+    collapsedLen: 1,
+    mdLen: 1,
+    openLen: 0,
+    closeLen: 0,
+    pmPos,
+    mdStart: acc.md,
+    collapsedStart: acc.collapsed,
+  });
+  acc.value += "\n";
+  acc.flat += 1;
+  acc.collapsed += 1;
+  acc.md += 1;
+}
+
+function appendInlineRuns(
+  container: ProseMirrorNode,
+  contentStart: number,
+  acc: RichAccumulator,
+): void {
+  let inlineOffset = 0;
+  container.content.forEach((child) => {
+    const pmPos = contentStart + inlineOffset;
+    if (child.isText && child.text) {
+      const marks = (child.marks ?? [])
+        .map((mark) => TIPTAP_TO_MARK[mark.type.name])
+        .filter((mark): mark is RichTextMark => Boolean(mark));
+      const { open, close } = textRunDelimiters(marks);
+      const mdText = `${open}${child.text}${close}`;
+      acc.runs.push({
+        kind: "text",
+        flatStart: acc.flat,
+        docLen: child.text.length,
+        collapsedLen: mdText.length,
+        mdLen: mdText.length,
+        openLen: open.length,
+        closeLen: close.length,
+        pmPos,
+        mdStart: acc.md,
+        collapsedStart: acc.collapsed,
+      });
+      acc.value += mdText;
+      acc.flat += child.text.length;
+      acc.collapsed += mdText.length;
+      acc.md += mdText.length;
+      inlineOffset += child.nodeSize;
+    } else if (child.type.name === "hardBreak") {
+      pushBreakRun(acc, pmPos);
+      inlineOffset += child.nodeSize;
+    } else if (child.isAtom || child.isInline) {
+      const source = readAtomSource(child);
+      acc.runs.push({
+        kind: "token",
+        flatStart: acc.flat,
+        docLen: 1,
+        collapsedLen: 1,
+        mdLen: source.length,
+        openLen: 0,
+        closeLen: 0,
+        pmPos,
+        mdStart: acc.md,
+        collapsedStart: acc.collapsed,
+        nodeName: child.type.name,
+      });
+      acc.value += source;
+      acc.flat += 1;
+      acc.collapsed += 1;
+      acc.md += source.length;
+      inlineOffset += child.nodeSize;
+    } else {
+      inlineOffset += child.nodeSize;
+    }
+  });
+}
+
+function walkTaskList(list: ProseMirrorNode, listStart: number, acc: RichAccumulator): void {
+  let itemPos = listStart + 1;
+  let firstItem = true;
+  list.content.forEach((item) => {
+    // Sibling items are separated by one newline in every coordinate space.
+    if (!firstItem) pushBreakRun(acc, itemPos - 1);

@@ -0,0 +1,586 @@
+import type { Node as ProseMirrorNode } from "@tiptap/pm/model";
+import { TaskItem } from "@tiptap/extension-task-item";
+
+import { splitPromptIntoComposerSegments } from "~/composer-editor-mentions";
+import { parseInlineMarkdown, RICH_TEXT_DELIMITERS, type RichTextMark } from "~/composer-rich-text";
+import { collectInlineContextIds } from "~/lib/composerContextReferences";
+
+/**
+ * Pure document model for the rich text (Tiptap) composer.
+ *
+ * The stored prompt stays markdown (`**bold**`, `@file` chips as canonical
+ * links). The Tiptap document holds styled text plus inline atom chips, so
+ * this module translates both ways and maps cursor offsets between the three
+ * coordinate spaces the composer speaks:
+ *
+ * - flat document offsets (styled markers excluded, chips count 1),
+ * - collapsed cursor offsets (markers literal, chips count 1 — the coordinate
+ *   the draft store and mention detection use),
+ * - markdown offsets (markers literal, chips expand to their source).
+ *
+ * DOM-free on purpose: unit tests build a real ProseMirror document from the
+ * JSON this produces and assert the round trip without a browser.
+ */
+
+export type SkillMeta = { label: string; description: string | null };
+
+/** Outermost mark first, so closers mirror openers when nested. */
+export const MARK_NESTING_ORDER: RichTextMark[] = ["strike", "bold", "italic", "code"];
+
+export const MARK_TO_TIPTAP: Record<RichTextMark, string> = {
+  bold: "bold",
+  italic: "italic",
+  strike: "strike",
+  code: "code",
+};
+
+export const TIPTAP_TO_MARK: Record<string, RichTextMark> = {
+  bold: "bold",
+  italic: "italic",
+  strike: "strike",
+  code: "code",
+};
+
+/**
+ * Task list items keep their exact source indent in an attribute so nesting
+ * round-trips byte-identically. Checkbox case (`[X]`) normalizes to `[x]` —
+ * the same fixed-point deal as `__bold__` becoming `**bold**`.
+ */
+export const ComposerTaskItemExtension = TaskItem.extend({
+  addAttributes() {
+    return {
+      ...this.parent?.(),
+      indent: { default: "" },
+    };
+  },
+}).configure({ nested: true });
+
+export function randomNodeKey(): string {
+  return `tiptap-${Math.random().toString(36).slice(2)}`;
+}
+
+interface TaskLinePrefix {
+  indent: string;
+  checked: boolean;
+}
+
+function parseTaskPrefix(head: string): { prefix: TaskLinePrefix; markerLength: number } | null {
+  const match = head.match(/^([ \t]*)-[ \t]+\[([ xX])\]/);
+  if (!match) return null;
+  const after = head.slice(match[0].length);
+  if (after.length > 0 && after[0] !== " " && after[0] !== "\t") return null;
+  return {
+    prefix: {
+      indent: match[1] ?? "",
+      checked: (match[2] ?? " ").toLowerCase() === "x",
+    },
+    markerLength: match[0].length,
+  };
+}
+
+type InlineJson = Record<string, unknown>;
+
+interface DocLine {
+  task: TaskLinePrefix | null;
+  inline: InlineJson[];
+}
+
+function atomJsonForSegment(
+  segment: Exclude<ReturnType<typeof splitPromptIntoComposerSegments>[number], { type: "text" }>,
+  skillLabelFor: (name: string) => SkillMeta,
+): InlineJson {
+  if (segment.type === "mention") {
+    return {
+      type: "composer-mention",
+      attrs: { path: segment.path, source: segment.source },
+    };
+  }
+  if (segment.type === "skill") {
+    const meta = skillLabelFor(segment.name);
+    return {
+      type: "composer-skill",
+      attrs: {
+        skillName: segment.name,
+        skillLabel: meta.label,
+        skillDescription: meta.description,
+      },
+    };
+  }
+  if (segment.type === "citation") {
+    return {
+      type: "composer-citation",
+      attrs: { citation: segment.citation, source: segment.source, citeKey: randomNodeKey() },
+    };
+  }
+  return {
+    type: "composer-context-reference",
+    attrs: {
+      kind: segment.kind,
+      contextId: segment.contextId,
+      label: segment.label,
+      source: segment.source,
+    },
+  };
+}
+
+function pushSpans(inline: InlineJson[], text: string): void {
+  for (const span of parseInlineMarkdown(text)) {
+    inline.push(textJsonForSpan(span.text, span.marks));
+  }
+}
+
+interface PendingTaskItem {
+  checked: boolean;
+  indent: string;
+  content: InlineJson[];
+  children: PendingTaskItem[];
+}
+
+function taskListJson(items: PendingTaskItem[]): InlineJson {
+  return {
+    type: "taskList",
+    content: items.map((item) => ({
+      type: "taskItem",
+      attrs: { checked: item.checked, indent: item.indent },
+      content: [
+        { type: "paragraph", content: item.content },
+        ...(item.children.length > 0 ? [taskListJson(item.children)] : []),
+      ],
+    })),
+  };
+}
+
+function textJsonForSpan(text: string, marks: RichTextMark[]): Record<string, unknown> {
+  const json: Record<string, unknown> = { type: "text", text };
+  if (marks.length > 0) {
+    json.marks = [...marks]
+      .sort((a, b) => MARK_NESTING_ORDER.indexOf(a) - MARK_NESTING_ORDER.indexOf(b))
+      .map((mark) => ({ type: MARK_TO_TIPTAP[mark] }));
+  }
+  return json;
+}
+
+export function buildTiptapContent(
+  value: string,
+  skillLabelFor: (name: string) => SkillMeta,
+): Record<string, unknown>[] {
+  // Pass 1: the segment stream becomes lines. A line is a task line only
+  // when its leading text — before any chip — is a complete `- [ ]` marker;
+  // the marker is decided at a chip, a newline, or the end of input so a
+  // partial marker (`- [ ]` + `foo`) can never commit early.
+  const lines: DocLine[] = [{ task: null, inline: [] }];
+  let head: string | null = "";
+  const currentLine = () => lines[lines.length - 1]!;
+  const endLine = () => {
+    const line = currentLine();
+    if (head !== null) {
+      const parsed = parseTaskPrefix(head);
+      if (parsed) {
+        line.task = parsed.prefix;
+        pushSpans(line.inline, head.slice(parsed.markerLength).replace(/^[ \t]*/, ""));
+      } else {
+        pushSpans(line.inline, head);
+      }
+    }
+    lines.push({ task: null, inline: [] });
+    head = "";
+  };
+  const appendTextPiece = (piece: string) => {
+    if (head !== null) {
+      head += piece;
+      return;
+    }
+    pushSpans(currentLine().inline, piece);
+  };
+
+  for (const segment of splitPromptIntoComposerSegments(value)) {
+    if (segment.type === "text") {
+      const parts = segment.text.split("\n");
+      parts.forEach((part, index) => {
+        if (index > 0) endLine();
+        appendTextPiece(part);
+      });
+    } else {
+      if (head !== null) {
+        const line = currentLine();
+        const parsed = parseTaskPrefix(head);
+        if (parsed) {
+          line.task = parsed.prefix;
+          pushSpans(line.inline, head.slice(parsed.markerLength).replace(/^[ \t]*/, ""));
+        } else {
+          pushSpans(line.inline, head);

@@ -0,0 +1,137 @@
+import { splitPromptIntoComposerSegments } from "./composer-editor-mentions";
+
+/**
+ * List continuation and indentation for the composer.
+ *
+ * Implemented once at the ChatComposer level (store replacement), so the
+ * Lexical and Tiptap surfaces behave identically and serialize identically:
+ * Shift+Enter on a list item continues it, Enter on an empty item exits the
+ * list, and Tab indents the item. Plain Markdown markers only — no real list
+ * nodes anywhere.
+ */
+
+export interface ComposerListEdit {
+  /** Expanded (plain string) offsets into the prompt. */
+  start: number;
+  end: number;
+  replacement: string;
+}
+
+type ListMarker =
+  | { kind: "ordered"; indent: string; numberText: string; delimiter: "." | ")"; space: string }
+  | { kind: "task"; indent: string; space: string }
+  | { kind: "bullet"; indent: string; bullet: string; space: string };
+
+function parseListMarker(line: string): { marker: ListMarker; markerEnd: number } | null {
+  const indent = line.match(/^[ \t]*/)?.[0] ?? "";
+  const rest = line.slice(indent.length);
+  const ordered = rest.match(/^(\d+)([.)])((?:[ \t]+)|\s*$)/);
+  if (ordered && ordered[1] !== undefined && ordered[2] !== undefined) {
+    return {
+      marker: {
+        kind: "ordered",
+        indent,
+        numberText: ordered[1],
+        delimiter: ordered[2] === ")" ? ")" : ".",
+        space: ordered[3] ?? "",
+      },
+      markerEnd: indent.length + ordered[0].length,
+    };
+  }
+  const task = rest.match(/^-\s\[[ xX]\]((?:[ \t]+)|\s*$)/);
+  if (task) {
+    return {
+      marker: { kind: "task", indent, space: task[1] ?? "" },
+      markerEnd: indent.length + task[0].length,
+    };
+  }
+  const bullet = rest.match(/^([-*+])((?:[ \t]+)|\s*$)/);
+  if (bullet && bullet[1] !== undefined) {
+    return {
+      marker: { kind: "bullet", indent, bullet: bullet[1], space: bullet[2] ?? "" },
+      markerEnd: indent.length + bullet[0].length,
+    };
+  }
+  return null;
+}
+
+function nextMarkerText(marker: ListMarker): string {
+  if (marker.kind === "ordered") {
+    const number = Number.parseInt(marker.numberText, 10);
+    const next = Number.isSafeInteger(number)
+      ? String(number + 1).padStart(marker.numberText.length, "0")
+      : marker.numberText;
+    return `${marker.indent}${next}${marker.delimiter} `;
+  }
+  if (marker.kind === "task") {
+    return `${marker.indent}- [ ] `;
+  }
+  return `${marker.indent}${marker.bullet} `;
+}
+
+function segmentSource(
+  segment: ReturnType<typeof splitPromptIntoComposerSegments>[number],
+): string {
+  if (segment.type === "text") return segment.text;
+  if (segment.type === "skill") return `$${segment.name}`;
+  return segment.source;
+}
+
+/** True when splitting at the caret would cut an inline chip in two. */
+function isInsideInlineToken(value: string, cursor: number): boolean {
+  let offset = 0;
+  for (const segment of splitPromptIntoComposerSegments(value)) {
+    const end = offset + segmentSource(segment).length;
+    if (segment.type !== "text" && cursor > offset && cursor < end) return true;
+    offset = end;
+  }
+  return false;
+}
+
+function currentLine(value: string, cursor: number): { start: number; end: number; text: string } {
+  const start = value.lastIndexOf("\n", cursor - 1) + 1;
+  const endIndex = value.indexOf("\n", cursor);
+  const end = endIndex === -1 ? value.length : endIndex;
+  return { start, end, text: value.slice(start, end) };
+}
+
+/**
+ * Enter on a list item line: continue the list, or exit it when the item is
+ * empty. Returns null for non-list lines, carets inside the marker, and
+ * carets inside an inline chip — all fall through to a plain newline.
+ */
+export function listContinuationForEnter(value: string, cursor: number): ComposerListEdit | null {
+  if (!Number.isInteger(cursor) || cursor < 0 || cursor > value.length) return null;
+  const line = currentLine(value, cursor);
+  const parsed = parseListMarker(line.text);
+  if (!parsed) return null;
+  const markerEnd = line.start + parsed.markerEnd;
+  if (cursor < markerEnd) return null;
+  if (isInsideInlineToken(value, cursor)) return null;
+  if (value.slice(markerEnd, line.end).trim() === "") {
+    // Empty item: Enter exits the list by removing the marker.
+    return { start: line.start, end: Math.max(cursor, markerEnd), replacement: "" };
+  }
+  return {
+    start: cursor,
+    end: cursor,
+    replacement: `\n${nextMarkerText(parsed.marker)}`,
+  };
+}
+
+/**
+ * Tab on a list item line: indent by two spaces. Ranged selections, non-list
+ * lines, and carets inside an inline chip fall through (Shift+Tab stays the
+ * plan-mode toggle and is handled before this is consulted).
+ */
+export function listIndentForTab(
+  value: string,
+  start: number,
+  end: number,
+): ComposerListEdit | null {
+  if (!Number.isInteger(start) || start !== end || start < 0 || start > value.length) return null;
+  const line = currentLine(value, start);
+  if (!parseListMarker(line.text)) return null;
+  if (isInsideInlineToken(value, start)) return null;
+  return { start: line.start, end: line.start, replacement: "  " };
+}

@@ -0,0 +1,586 @@
+import type { Node as ProseMirrorNode } from "@tiptap/pm/model";
+import { TaskItem } from "@tiptap/extension-task-item";
+
+import { splitPromptIntoComposerSegments } from "~/composer-editor-mentions";
+import { parseInlineMarkdown, RICH_TEXT_DELIMITERS, type RichTextMark } from "~/composer-rich-text";
+import { collectInlineContextIds } from "~/lib/composerContextReferences";
+
+/**
+ * Pure document model for the rich text (Tiptap) composer.
+ *
+ * The stored prompt stays markdown (`**bold**`, `@file` chips as canonical
+ * links). The Tiptap document holds styled text plus inline atom chips, so
+ * this module translates both ways and maps cursor offsets between the three
+ * coordinate spaces the composer speaks:
+ *
+ * - flat document offsets (styled markers excluded, chips count 1),
+ * - collapsed cursor offsets (markers literal, chips count 1 — the coordinate
+ *   the draft store and mention detection use),
+ * - markdown offsets (markers literal, chips expand to their source).
+ *
+ * DOM-free on purpose: unit tests build a real ProseMirror document from the
+ * JSON this produces and assert the round trip without a browser.
+ */
+
+export type SkillMeta = { label: string; description: string | null };
+
+/** Outermost mark first, so closers mirror openers when nested. */
+export const MARK_NESTING_ORDER: RichTextMark[] = ["strike", "bold", "italic", "code"];
+
+export const MARK_TO_TIPTAP: Record<RichTextMark, string> = {
+  bold: "bold",
+  italic: "italic",
+  strike: "strike",
+  code: "code",
+};
+
+export const TIPTAP_TO_MARK: Record<string, RichTextMark> = {
+  bold: "bold",
+  italic: "italic",
+  strike: "strike",
+  code: "code",
+};
+
+/**
+ * Task list items keep their exact source indent in an attribute so nesting
+ * round-trips byte-identically. Checkbox case (`[X]`) normalizes to `[x]` —
+ * the same fixed-point deal as `__bold__` becoming `**bold**`.
+ */
+export const ComposerTaskItemExtension = TaskItem.extend({
+  addAttributes() {
+    return {
+      ...this.parent?.(),
+      indent: { default: "" },
+    };
+  },
+}).configure({ nested: true });
+
+export function randomNodeKey(): string {
+  return `tiptap-${Math.random().toString(36).slice(2)}`;
+}
+
+interface TaskLinePrefix {
+  indent: string;
+  checked: boolean;
+}
+
+function parseTaskPrefix(head: string): { prefix: TaskLinePrefix; markerLength: number } | null {
+  const match = head.match(/^([ \t]*)-[ \t]+\[([ xX])\]/);
+  if (!match) return null;
+  const after = head.slice(match[0].length);
+  if (after.length > 0 && after[0] !== " " && after[0] !== "\t") return null;
+  return {
+    prefix: {
+      indent: match[1] ?? "",
+      checked: (match[2] ?? " ").toLowerCase() === "x",
+    },
+    markerLength: match[0].length,
+  };
+}
+
+type InlineJson = Record<string, unknown>;
+
+interface DocLine {
+  task: TaskLinePrefix | null;
+  inline: InlineJson[];
+}
+
+function atomJsonForSegment(
+  segment: Exclude<ReturnType<typeof splitPromptIntoComposerSegments>[number], { type: "text" }>,
+  skillLabelFor: (name: string) => SkillMeta,
+): InlineJson {
+  if (segment.type === "mention") {
+    return {
+      type: "composer-mention",
+      attrs: { path: segment.path, source: segment.source },
+    };
+  }
+  if (segment.type === "skill") {
+    const meta = skillLabelFor(segment.name);
+    return {
+      type: "composer-skill",
+      attrs: {
+        skillName: segment.name,
+        skillLabel: meta.label,
+        skillDescription: meta.description,
+      },
+    };
+  }
+  if (segment.type === "citation") {
+    return {
+      type: "composer-citation",
+      attrs: { citation: segment.citation, source: segment.source, citeKey: randomNodeKey() },
+    };
+  }
+  return {
+    type: "composer-context-reference",
+    attrs: {
+      kind: segment.kind,
+      contextId: segment.contextId,
+      label: segment.label,
+      source: segment.source,
+    },
+  };
+}
+
+function pushSpans(inline: InlineJson[], text: string): void {
+  for (const span of parseInlineMarkdown(text)) {
+    inline.push(textJsonForSpan(span.text, span.marks));
+  }
+}
+
+interface PendingTaskItem {
+  checked: boolean;
+  indent: string;
+  content: InlineJson[];
+  children: PendingTaskItem[];
+}
+
+function taskListJson(items: PendingTaskItem[]): InlineJson {
+  return {
+    type: "taskList",
+    content: items.map((item) => ({
+      type: "taskItem",
+      attrs: { checked: item.checked, indent: item.indent },
+      content: [
+        { type: "paragraph", content: item.content },
+        ...(item.children.length > 0 ? [taskListJson(item.children)] : []),
+      ],
+    })),
+  };
+}
+
+function textJsonForSpan(text: string, marks: RichTextMark[]): Record<string, unknown> {
+  const json: Record<string, unknown> = { type: "text", text };
+  if (marks.length > 0) {
+    json.marks = [...marks]
+      .sort((a, b) => MARK_NESTING_ORDER.indexOf(a) - MARK_NESTING_ORDER.indexOf(b))
+      .map((mark) => ({ type: MARK_TO_TIPTAP[mark] }));
+  }
+  return json;
+}
+
+export function buildTiptapContent(
+  value: string,
+  skillLabelFor: (name: string) => SkillMeta,
+): Record<string, unknown>[] {
+  // Pass 1: the segment stream becomes lines. A line is a task line only
+  // when its leading text — before any chip — is a complete `- [ ]` marker;
+  // the marker is decided at a chip, a newline, or the end of input so a
+  // partial marker (`- [ ]` + `foo`) can never commit early.
+  const lines: DocLine[] = [{ task: null, inline: [] }];
+  let head: string | null = "";
+  const currentLine = () => lines[lines.length - 1]!;
+  const endLine = () => {
+    const line = currentLine();
+    if (head !== null) {
+      const parsed = parseTaskPrefix(head);
+      if (parsed) {
+        line.task = parsed.prefix;
+        pushSpans(line.inline, head.slice(parsed.markerLength).replace(/^[ \t]*/, ""));
+      } else {
+        pushSpans(line.inline, head);
+      }
+    }
+    lines.push({ task: null, inline: [] });
+    head = "";
+  };
+  const appendTextPiece = (piece: string) => {
+    if (head !== null) {
+      head += piece;
+      return;
+    }
+    pushSpans(currentLine().inline, piece);
+  };
+
+  for (const segment of splitPromptIntoComposerSegments(value)) {
+    if (segment.type === "text") {
+      const parts = segment.text.split("\n");
+      parts.forEach((part, index) => {
+        if (index > 0) endLine();
+        appendTextPiece(part);
+      });
+    } else {
+      if (head !== null) {
+        const line = currentLine();
+        const parsed = parseTaskPrefix(head);
+        if (parsed) {
+          line.task = parsed.prefix;
+          pushSpans(line.inline, head.slice(parsed.markerLength).replace(/^[ \t]*/, ""));
+        } else {
+          pushSpans(line.inline, head);
+        }
+        head = null;
+      }
+      currentLine().inline.push(atomJsonForSegment(segment, skillLabelFor));
+    }
+  }
+  // Decide the final line. A trailing newline leaves a fresh empty line,
+  // which endLine already pushed — drop the spare blank it would add.
+  if (head !== null) {
+    const line = currentLine();
+    const parsed = parseTaskPrefix(head);
+    if (parsed) {
+      line.task = parsed.prefix;
+      pushSpans(line.inline, head.slice(parsed.markerLength).replace(/^[ \t]*/, ""));
+    } else {
+      pushSpans(line.inline, head);
+    }
+  } else if (lines.length > 1) {
+    const last = lines[lines.length - 1]!;
+    if (!last.task && last.inline.length === 0) lines.pop();
+  }
+
+  // Pass 2: consecutive task lines group into (possibly nested) task lists
+  // by indent prefix; everything else stays a paragraph.
+  const blocks: Record<string, unknown>[] = [];
+  let stack: { indent: string; items: PendingTaskItem[] }[] = [];
+  const flushTasks = () => {
+    if (stack.length > 0) {
+      blocks.push(taskListJson(stack[0]!.items));
+      stack = [];
+    }
+  };
+  for (const line of lines) {
+    if (!line.task) {
+      flushTasks();
+      blocks.push({ type: "paragraph", content: line.inline });
+      continue;
+    }
+    const item: PendingTaskItem = {
+      checked: line.task.checked,
+      indent: line.task.indent,
+      content: line.inline,
+      children: [],
+    };
+    for (;;) {
+      const top = stack[stack.length - 1];
+      if (!top) {
+        // A leading indented item with no parent flattens but keeps indent.
+        stack.push({ indent: "", items: [] });
+        continue;
+      }
+      if (top.indent === item.indent) {
+        top.items.push(item);
+        break;
+      }
+      if (top.indent !== "" && !item.indent.startsWith(top.indent)) {
+        stack.pop();
+        continue;
+      }
+      const parent = top.items[top.items.length - 1];
+      if (!parent) {
+        top.items.push(item);
+        break;
+      }
+      parent.children.push(item);

@@ -0,0 +1,1368 @@
+import { Extension, Node, wrappingInputRule, type JSONContent } from "@tiptap/core";
+import { TaskList } from "@tiptap/extension-task-list";
+import { ReactNodeViewRenderer, NodeViewWrapper, type NodeViewProps } from "@tiptap/react";
+import StarterKit from "@tiptap/starter-kit";
+import { type Node as ProseMirrorNode } from "@tiptap/pm/model";
+import { splitBlockKeepMarks } from "@tiptap/pm/commands";
+import { Plugin, PluginKey, TextSelection } from "@tiptap/pm/state";
+import { Decoration, DecorationSet } from "@tiptap/pm/view";
+import type {
+  AssistantCitation,
+  ComposerContextClipboardFragment,
+  ServerProviderSkill,
+} from "@t3tools/contracts";
+import {
+  serializeAssistantCitation,
+  withAssistantCitationComment,
+} from "@t3tools/shared/assistantCitations";
+import {
+  COMPOSER_CONTEXT_CLIPBOARD_MIME,
+  encodeComposerContextClipboardHtml,
+} from "@t3tools/shared/composerContextClipboard";
+import {
+  createContext,
+  use,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { EditorContent, useEditor } from "@tiptap/react";
+
+import {
+  clampCollapsedComposerCursor,
+  collapseExpandedComposerCursor,
+  expandCollapsedComposerCursor,
+  isCollapsedCursorAdjacentToInlineToken,
+} from "~/composer-logic";
+import {
+  collectComposerPromptInlineTokens,
+  selectionTouchesMentionBoundary,
+} from "~/composer-editor-mentions";
+import {
+  buildDocJson,
+  buildTiptapContent,
+  collapsedToFlat,
+  ComposerTaskItemExtension,
+  flatToCollapsed,
+  flatToMarkdown,
+  flatToPm,
+  pmToFlat,
+  serializeEditorDoc,
+  type SkillMeta,
+} from "~/composer-rich-text-doc";
+import { collectInlineContextIds } from "~/lib/composerContextReferences";
+import { cn, isMacPlatform } from "~/lib/utils";
+import { basenameOfPath } from "~/pierre-icons";
+import {
+  COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME,
+  COMPOSER_INLINE_CHIP_ICON_CLASS_NAME,
+  COMPOSER_INLINE_CHIP_LABEL_CLASS_NAME,
+  COMPOSER_INLINE_SKILL_CHIP_CLASS_NAME,
+  SKILL_CHIP_ICON_SVG,
+} from "./composerInlineChip";
+import { FILE_TAG_CHIP_CLASS_NAME, FileTagChipContent } from "./chat/FileTagChip";
+import { AssistantCitationChip } from "./chat/AssistantCitationChip";
+import { getTimelinePageScrollKey } from "./chat/pageScrollController";
+import { ContextChipPopover } from "./contextChipParts";
+import { Button } from "./ui/button";
+import {
+  ComposerContextActionsContext,
+  ComposerContextReferenceChip,
+  ComposerContextRecordsContext,
+} from "./composerContextPresentation";
+import type { AssistantCitationSourceAnchor } from "~/lib/assistantTextSelection";
+import { formatProviderSkillDisplayName } from "@t3tools/client-runtime/providerSkills";
+import { Tooltip, TooltipPopup, TooltipTrigger } from "./ui/tooltip";
+import { importPastedComposerText } from "./composerInlineTokenPaste";
+import { didComposerSelectionChangeVisibly } from "./composerSelection";
+import type { ComposerDraftContextRecords } from "./composerContextPresentation";
+
+export interface ComposerPromptEditorHandle {
+  focus: () => void;
+  focusAt: (cursor: number) => void;
+  focusAtEnd: () => void;
+  readSelectionRange: () => { start: number; end: number };
+  requestCitationComment: (request: ComposerCitationCommentRequest) => void;
+  readSnapshot: () => {
+    value: string;
+    cursor: number;
+    expandedCursor: number;
+    contextIds: string[];
+  };
+  /**
+   * True when a collapsed caret sits on the first ("start") or last ("end")
+   * visual line, counting soft wraps. Prompt history only claims ArrowUp and
+   * ArrowDown at these edges so arrows still move the caret inside multiline
+   * text.
+   */
+  isCaretOnVisualEdge: (edge: "start" | "end") => boolean;
+}
+
+export interface ComposerPromptEditorProps {
+  value: string;
+  cursor: number;
+  /**
+   * Render Markdown styling (bold, italic, code, strike, task checkboxes).
+   * Off renders the same Tiptap engine as plain text: every marker stays a
+   * literal character.
+   */
+  richTextEnabled?: boolean;
+  /** Draft records behind the prompt's context references, keyed by context id. */
+  contextRecords: ComposerDraftContextRecords;
+  /** Structured clipboard payload for the given referenced ids, or null to skip. */
+  buildContextClipboardFragment?:
+    | ((contextIds: ReadonlyArray<string>) => string | null)
+    | undefined;
+  /** Imports a structured paste's records; returns ids that changed. */
+  importContextFragment?:
+    | ((fragment: ComposerContextClipboardFragment) => ReadonlyMap<string, string>)
+    | undefined;
+  skills: ReadonlyArray<ServerProviderSkill>;
+  disabled: boolean;
+  placeholder: string;
+  containerClassName?: string;
+  className?: string;
+  placeholderClassName?: string;
+  onChange: (
+    nextValue: string,
+    nextCursor: number,
+    expandedCursor: number,
+    cursorAdjacentToMention: boolean,
+    contextIds: string[],
+  ) => void;
+  onVisibleSelectionChange?: () => void;
+  onCommandKeyDown?: (
+    key: "ArrowDown" | "ArrowUp" | "Enter" | "Tab",
+    event: KeyboardEvent,
+    isTaskItem?: boolean,
+  ) => boolean;
+  onPageScrollKeyDown?: (key: "PageUp" | "PageDown") => void;
+  onPageScrollKeyUp?: (key: string) => void;
+  onPageScrollRelease?: () => void;
+  onCitationSubmitAndSend?: () => void;
+  onPaste: React.ClipboardEventHandler<HTMLElement>;
+  editorRef: React.RefObject<ComposerPromptEditorHandle | null>;
+}
+
+export type ComposerCitationCommentRequest = {
+  previousValue: string;
+  value: string;
+  citationStart: number;
+  sourceAnchor: AssistantCitationSourceAnchor;
+};
+
+type OpenCitationComment = {
+  key: string;
+  sourceAnchor?: AssistantCitationSourceAnchor;
+  removeOnCancel?: boolean;
+};
+
+const ComposerCitationCommentContext = createContext<{
+  openComment: OpenCitationComment | null;
+  onOpenChange: (citeKey: string, open: boolean) => void;
+  onSubmitAndSend: () => void;
+}>({ openComment: null, onOpenChange: () => {}, onSubmitAndSend: () => {} });
+
+const RichComposerSkillsContext = createContext<ReadonlyArray<ServerProviderSkill>>([]);
+
+const SURROUND_CLOSE: Record<string, string> = {
+  "(": ")",
+  "[": "]",
+  "{": "}",
+  "'": "'",
+  '"': '"',
+  "“": "”",
+  "`": "`",
+  "<": ">",
+  "«": "»",
+  "*": "*",
+  _: "_",
+};
+
+function resolvedThemeFromDocument(): "light" | "dark" {
+  return document.documentElement.classList.contains("dark") ? "dark" : "light";
+}
+
+// ── Inline atom nodes (chips) ─────────────────────────────────────────────
+
+const ComposerMentionExtension = Node.create({
+  name: "composer-mention",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      path: { default: "" },
+      source: { default: "" },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-mention]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-mention": "", ...HTMLAttributes }];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerMentionNodeView);
+  },
+});
+
+function ComposerMentionNodeView({ node }: NodeViewProps) {
+  const actions = use(ComposerContextActionsContext);
+  const path = (node.attrs.path as string) ?? "";
+  const chip = (
+    <button
+      type="button"
+      onClick={() => actions.openMention(path)}
+      aria-label={`Preview ${path}`}
+      className={`${FILE_TAG_CHIP_CLASS_NAME} cursor-pointer focus-visible:outline-2`}
+      contentEditable={false}
+      spellCheck={false}
+      data-composer-mention-chip="true"
+    >
+      <FileTagChipContent
+        path={path}
+        label={basenameOfPath(path)}
+        theme={resolvedThemeFromDocument()}
+      />
+    </button>
+  );
+  return (
+    <NodeViewWrapper as="span" className={COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME}>
+      <Tooltip>
+        <TooltipTrigger render={chip} />
+        <TooltipPopup
+          side="top"
+          className="max-w-120 whitespace-normal leading-tight wrap-anywhere"
+        >
+          {path}
+        </TooltipPopup>
+      </Tooltip>
+    </NodeViewWrapper>
+  );
+}
+
+const ComposerSkillExtension = Node.create({
+  name: "composer-skill",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      skillName: { default: "" },
+      skillLabel: { default: "" },
+      skillDescription: { default: null },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-skill]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-skill": "", ...HTMLAttributes }];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerSkillNodeView);
+  },
+});
+
+function ComposerSkillNodeView({ node }: NodeViewProps) {
+  const actions = use(ComposerContextActionsContext);
+  const skills = use(RichComposerSkillsContext);
+  const skillName = (node.attrs.skillName as string) ?? "";
+  const skillLabel = (node.attrs.skillLabel as string) || skillName;
+  const skillDescription = (node.attrs.skillDescription as string | null) ?? null;
+  const skill = skills.find((candidate) => candidate.name === skillName);
+  return (
+    <NodeViewWrapper as="span" className={COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME}>
+      <ContextChipPopover
+        accessibleLabel={`Skill ${skillLabel}`}
+        triggerClassName={COMPOSER_INLINE_SKILL_CHIP_CLASS_NAME}
+        chip={
+          <>
+            <span
+              aria-hidden="true"
+              className={COMPOSER_INLINE_CHIP_ICON_CLASS_NAME}
+              dangerouslySetInnerHTML={{ __html: SKILL_CHIP_ICON_SVG }}
+            />
+            <span className={COMPOSER_INLINE_CHIP_LABEL_CLASS_NAME}>{skillLabel}</span>
+          </>
+        }
+      >
+        <div className="space-y-3 p-2 text-sm">
+          <p className="font-medium">{skillLabel}</p>
+          <p>
+            {skill?.description ??
+              skillDescription ??
+              "No description is available for this skill."}
+          </p>
+          {skill?.path ? (
+            <Button variant="outline" size="sm" onClick={() => actions.openMention(skill.path)}>
+              View instructions
+            </Button>
+          ) : null}
+        </div>
+      </ContextChipPopover>
+    </NodeViewWrapper>
+  );
+}
+
+const ComposerCitationExtension = Node.create({
+  name: "composer-citation",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      citation: { default: null },
+      source: { default: "" },
+      citeKey: { default: "" },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-citation]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-citation": "", ...HTMLAttributes }];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerCitationNodeView);
+  },
+});
+
+function ComposerCitationNodeView({ node, editor, getPos }: NodeViewProps) {
+  const commentContext = use(ComposerCitationCommentContext);
+  const citation = node.attrs.citation as AssistantCitation;
+  const citeKey = node.attrs.citeKey as string;
+  const commentTarget =
+    commentContext.openComment?.key === citeKey ? commentContext.openComment : null;
+
+  const nodePos = useCallback(() => {
+    const pos = typeof getPos === "function" ? getPos() : null;
+    return typeof pos === "number" ? pos : null;
+  }, [getPos]);
+
+  const onSaveComment = useCallback(
+    (comment: string): boolean => {
+      if (!editor.isEditable) return false;
+      const pos = nodePos();
+      if (pos === null) return false;
+      const current = editor.state.doc.nodeAt(pos);
+      if (!current || current.type.name !== "composer-citation") return false;
+      const currentCitation = current.attrs.citation as AssistantCitation;
+      const next = withAssistantCitationComment(currentCitation, comment);
+      const tr = editor.state.tr.setNodeMarkup(pos, undefined, {
+        ...current.attrs,
+        citation: next,
+        source: serializeAssistantCitation(next),
+      });
+      editor.view.dispatch(tr);
+      return true;
+    },
+    [editor, nodePos],
+  );
+
+  const onRemove = useCallback(() => {
+    if (!editor.isEditable) return;
+    const pos = nodePos();
+    if (pos === null) return;
+    const current = editor.state.doc.nodeAt(pos);
+    if (!current) return;
+    editor
+      .chain()
+      .focus()
+      .deleteRange({ from: pos, to: pos + current.nodeSize })
+      .run();
+  }, [editor, nodePos]);
+
+  return (
+    <NodeViewWrapper
+      as="span"
+      className="inline-flex min-w-0 max-w-full"
+      contentEditable={false}
+      spellCheck={false}
+      data-composer-citation-chip="true"
+    >
+      <AssistantCitationChip
+        citation={citation}
+        composer
+        commentEditor={{
+          open: commentTarget !== null,
+          sourceAnchor: commentTarget?.sourceAnchor,
+          onOpenChange: (open) => {
+            if (open && !editor.isEditable) return;
+            commentContext.onOpenChange(citeKey, open);
+          },
+          ...(commentTarget?.removeOnCancel ? { onCancel: onRemove } : {}),
+          onSave: onSaveComment,
+          onSaveAndSend: (comment) => {
+            if (!onSaveComment(comment)) return false;
+            commentContext.onSubmitAndSend();
+            return true;
+          },
+        }}
+      />
+    </NodeViewWrapper>
+  );
+}
+
+const ComposerContextReferenceExtension = Node.create({
+  name: "composer-context-reference",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      kind: { default: "" },
+      contextId: { default: "" },
+      label: { default: "" },
+      source: { default: "" },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-context-reference]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-context-reference": "", ...HTMLAttributes }];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerContextReferenceNodeView);
+  },
+});
+
+function ComposerContextReferenceNodeView({ node }: NodeViewProps) {
+  return (
+    <NodeViewWrapper as="span" className={COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME}>
+      <ComposerContextReferenceChip
+        kind={(node.attrs.kind as string) ?? ""}
+        contextId={(node.attrs.contextId as string) ?? ""}
+        label={(node.attrs.label as string) ?? ""}
+      />
+    </NodeViewWrapper>
+  );
+}
+
+// ── Marker reveal (show ** when the cursor is on styled text) ──────────────
+
+type StyledRange = {
+  from: number;
+  to: number;
+  markers: { at: number; side: number; text: string }[];
+};
+
+function collectStyledRanges(doc: ProseMirrorNode): StyledRange[] {
+  const ranges: StyledRange[] = [];
+  const map = serializeEditorDoc(doc);
+  let range: StyledRange | null = null;
+  let openLength = 0;
+  for (const run of map.runs) {
+    if (run.openLen > 0) {
+      range ??= { from: run.pmPos, to: run.pmPos, markers: [] };
+      range.markers.push({
+        at: run.pmPos,
+        side: -1,
+        text: map.value.slice(run.mdStart, run.mdStart + run.openLen),
+      });
+    }
+    if (range === null) continue;
+    range.to = run.pmPos + run.docLen;
+    if (run.closeLen > 0) {
+      const end = run.mdStart + run.mdLen;
+      range.markers.push({
+        at: range.to,
+        side: -2,
+        text: map.value.slice(end - run.closeLen, end),
+      });
+    }
+    openLength += run.openLen - run.closeLen;
+    if (openLength === 0) {
+      ranges.push(range);
+      range = null;
+    }
+  }
+  return ranges;
+}
+
+const MarkerPluginKey = new PluginKey("composer-rich-markers");
+
+const ComposerMarkerPlugin = new Plugin({
+  key: MarkerPluginKey,
+  state: {
+    init: (_, state) => decorationsForSelection(state.doc, state.selection),
+    apply: (tr, old) =>
+      tr.docChanged || tr.selectionSet ? decorationsForSelection(tr.doc, tr.selection) : old,
+  },
+  props: {
+    decorations(state) {
+      return MarkerPluginKey.getState(state);
+    },
+  },
+});
+
+function decorationsForSelection(
+  doc: ProseMirrorNode,
+  selection: { from: number; to: number; empty: boolean },
+): DecorationSet {
+  const decorations: Decoration[] = [];
+  if (!selection.empty) {
+    doc.nodesBetween(selection.from, selection.to, (node, pos) => {
+      if (node.type.name.startsWith("composer-")) {
+        decorations.push(
+          Decoration.node(pos, pos + node.nodeSize, { class: "composer-chip-range-selected" }),
+        );
+        return false;
+      }
+      return true;
+    });
+  }
+  for (const range of collectStyledRanges(doc)) {
+    const active = selection.empty
+      ? selection.from >= range.from && selection.from <= range.to
+      : selection.from < range.to && selection.to > range.from;
+    if (!active) continue;
+    for (const { at, side, text } of range.markers) {
+      const marker = document.createElement("span");
+      marker.className = "composer-rich-marker";
+      marker.textContent = text;
+      marker.setAttribute("aria-hidden", "true");
+      decorations.push(
+        Decoration.widget(at, marker, { side, key: `marker-${at}-${side}-${marker.textContent}` }),
+      );
+    }
+  }
+  return DecorationSet.create(doc, decorations);
+}
+
+const ComposerMarkersExtension = Extension.create({
+  name: "composer-rich-markers",
+  addProseMirrorPlugins() {
+    return [ComposerMarkerPlugin];
+  },
+});
+
+// Document model (markdown ⇄ ProseMirror) lives in ~/composer-rich-text-doc so
+// unit tests can round-trip it without a browser.
+// ── Editor component ───────────────────────────────────────────────────────
+
+type TiptapEditor = NonNullable<ReturnType<typeof useEditor>>;
+
+export function ComposerPromptEditorTiptap(props: ComposerPromptEditorProps) {
+  // Extensions are creation-time: flipping the setting remounts the editor.
+  // Both halves initialize from the controlled Markdown value, so the draft
+  // survives the flip.
+  return (
+    <ComposerPromptEditorTiptapInner key={props.richTextEnabled ? "rich" : "plain"} {...props} />
+  );
+}
+
+function ComposerPromptEditorTiptapInner(props: ComposerPromptEditorProps) {
+  const {
+    value,
+    cursor,
+    richTextEnabled,
+    contextRecords,
+    buildContextClipboardFragment,
+    importContextFragment,
+    skills,
+    disabled,
+    placeholder,
+    containerClassName,
+    className,
+    placeholderClassName,
+    onChange,
+    onVisibleSelectionChange,
+    onCommandKeyDown,
+    onPageScrollKeyDown,
+    onPageScrollKeyUp,
+    onPageScrollRelease,
+    onCitationSubmitAndSend,
+    onPaste,
+    editorRef,
+  } = props;
+  // The setting toggles styling, not the engine: both modes are Tiptap.
+  // Plain mode disables the mark extensions, so markers stay literal text.
+  const richText = richTextEnabled ?? false;
+
+  const onChangeRef = useRef(onChange);
+  const onVisibleSelectionChangeRef = useRef(onVisibleSelectionChange);
+  const onCommandKeyDownRef = useRef(onCommandKeyDown);
+  const buildFragmentRef = useRef(buildContextClipboardFragment);
+  const importFragmentRef = useRef(importContextFragment);
+  const skillsRef = useRef(skills);
+  const latestValueRef = useRef(value);
+  // The editor instance for callbacks created before it exists (paste).
+  // Effects flush before any user interaction, so this is always set.
+  const editorHolder = useRef<TiptapEditor | null>(null);
+
+  useEffect(() => {
+    onChangeRef.current = onChange;
+  }, [onChange]);
+  useEffect(() => {
+    onVisibleSelectionChangeRef.current = onVisibleSelectionChange;
+  }, [onVisibleSelectionChange]);
+  useEffect(() => {
+    onCommandKeyDownRef.current = onCommandKeyDown;
+  }, [onCommandKeyDown]);
+  useEffect(() => {
+    buildFragmentRef.current = buildContextClipboardFragment;
+  }, [buildContextClipboardFragment]);
+  useEffect(() => {
+    importFragmentRef.current = importContextFragment;
+  }, [importContextFragment]);
+  useEffect(() => {
+    skillsRef.current = skills;
+  }, [skills]);
+  useLayoutEffect(() => {
+    latestValueRef.current = value;
+  }, [value]);
+
+  const skillLabelFor = useCallback((name: string): SkillMeta => {
+    const normalized = name.startsWith("$") ? name.slice(1) : name;
+    const skill = skillsRef.current.find((candidate) => candidate.name === normalized);
+    if (!skill) {
+      return { label: formatProviderSkillDisplayName({ name: normalized }), description: null };
+    }
+    const shortDescription = skill.shortDescription?.trim();
+    return {
+      label: formatProviderSkillDisplayName(skill),
+      description: shortDescription || skill.description?.trim() || null,
+    };
+  }, []);
+
+  const initialCursor = clampCollapsedComposerCursor(value, cursor);
+  const initialExpandedCursor = expandCollapsedComposerCursor(value, initialCursor);
+  const snapshotRef = useRef({
+    value,
+    cursor: initialCursor,
+    expandedCursor: initialExpandedCursor,
+    contextIds: collectInlineContextIds(value),
+  });
+  const selectionRangeRef = useRef({ start: initialExpandedCursor, end: initialExpandedCursor });
+  const isApplyingControlledUpdateRef = useRef(false);
+  const citationRequestRef = useRef<ComposerCitationCommentRequest | null>(null);
+  const [openCitation, setOpenCitation] = useState<OpenCitationComment | null>(null);
+  const [isEmpty, setIsEmpty] = useState(value.length === 0);
+
+  const citationCommentActions = useMemo(
+    () => ({
+      openComment: openCitation,
+      onOpenChange: (nodeKey: string, open: boolean) => {
+        setOpenCitation((current) => {
+          if (open) {
+            if (current?.key === nodeKey) return current;
+            return { key: nodeKey };
+          }
+          return current?.key === nodeKey ? null : current;
+        });
+      },
+      onSubmitAndSend: onCitationSubmitAndSend ?? (() => {}),
+    }),
+    [onCitationSubmitAndSend, openCitation],
+  );
+
+  const handleEditorChange = useCallback((updated: TiptapEditor) => {
+    const map = serializeEditorDoc(updated.state.doc);
+    const { from, to } = updated.state.selection;
+    const fromFlat = pmToFlat(map, from);
+    const toFlat = pmToFlat(map, to);
+    const nextValue = map.value;
+    const nextCursor = clampCollapsedComposerCursor(map.value, flatToCollapsed(map, fromFlat));
+    const nextExpandedCursor = Math.max(
+      0,
+      Math.min(map.value.length, flatToMarkdown(map, fromFlat)),
+    );
+    const nextSelectionRange = {
+      start: Math.min(nextExpandedCursor, flatToMarkdown(map, toFlat)),
+      end: Math.max(nextExpandedCursor, flatToMarkdown(map, toFlat)),
+    };
+    const previousSelectionRange = selectionRangeRef.current;
+    selectionRangeRef.current = nextSelectionRange;
+    setIsEmpty(nextValue.length === 0);
+    const previousSnapshot = snapshotRef.current;
+    const snapshotChanged = !(
+      previousSnapshot.value === nextValue &&
+      previousSnapshot.cursor === nextCursor &&
+      previousSnapshot.expandedCursor === nextExpandedCursor &&
+      previousSnapshot.contextIds.length === map.contextIds.length &&
+      previousSnapshot.contextIds.every((id, index) => id === map.contextIds[index])
+    );
+    if (isApplyingControlledUpdateRef.current) return;
+    if (!snapshotChanged) {
+      if (didComposerSelectionChangeVisibly(previousSelectionRange, nextSelectionRange)) {
+        onVisibleSelectionChangeRef.current?.();
+      }
+      return;
+    }
+    // A selection-only update while a newer prompt waits to be applied (a chip
+    // was just inserted through the store) would report stale text and clobber
+    // the prompt. Let the controlled rewrite land instead.
+    if (previousSnapshot.value === nextValue && nextValue !== latestValueRef.current) {
+      return;
+    }
+    snapshotRef.current = {
+      value: nextValue,
+      cursor: nextCursor,
+      expandedCursor: nextExpandedCursor,
+      contextIds: map.contextIds,
+    };
+    const cursorAdjacentToMention =
+      isCollapsedCursorAdjacentToInlineToken(nextValue, nextCursor, "left") ||
+      isCollapsedCursorAdjacentToInlineToken(nextValue, nextCursor, "right");
+    onChangeRef.current(
+      nextValue,
+      nextCursor,
+      nextExpandedCursor,
+      cursorAdjacentToMention,
+      map.contextIds,
+    );
+  }, []);
+
+  const editor = useEditor(
+    {
+      extensions: [
+        StarterKit.configure({
+          blockquote: false,
+          bulletList: false,
+          codeBlock: false,
+          heading: false,
+          horizontalRule: false,
+          listItem: false,
+          link: false,
+          orderedList: false,
+          underline: false,
+          dropcursor: false,
+          gapcursor: false,
+          trailingNode: false,
+          // Plain mode has no marks: typed markers stay literal characters.
+          ...(richText ? {} : { bold: false, italic: false, strike: false, code: false }),
+        }),
+        ComposerMentionExtension,
+        ComposerSkillExtension,
+        ComposerCitationExtension,
+        ComposerContextReferenceExtension,
+        ComposerMarkersExtension,
+        ...(richText
+          ? [
+              TaskList,
+              ComposerTaskItemExtension.extend({
+                addInputRules() {
+                  return [
+                    wrappingInputRule({
+                      find: /^- \[([ xX])\] $/,
+                      type: this.type,
+                      getAttributes: (match) => ({ checked: match[1]?.toLowerCase() === "x" }),
+                    }),
+                  ];
+                },
+              }),
+            ]
+          : []),
+      ],
+      content: buildDocJson(
+        value,
+        (name) => {
+          const normalized = name.startsWith("$") ? name.slice(1) : name;
+          const found = skills.find((candidate) => candidate.name === normalized);
+          if (!found) {
+            return {
+              label: formatProviderSkillDisplayName({ name: normalized }),
+              description: null,
+            };
+          }
+          const shortDescription = found.shortDescription?.trim();
+          return {
+            label: formatProviderSkillDisplayName(found),
+            description: shortDescription || found.description?.trim() || null,
+          };
+        },
+        { styling: richText },
+      ),
+      editable: !disabled,
+      editorProps: {
+        attributes: {
+          class: cn(
+            "composer-tiptap block max-h-50 min-h-17.5 w-full overflow-y-auto whitespace-pre-wrap wrap-break-word bg-transparent leading-relaxed text-foreground focus:outline-none",
+            className,
+          ),
+          "data-testid": "composer-editor",
+          "data-composer-rich-text": richText ? "true" : "false",
+          "aria-placeholder": placeholder,
+        },
+        handleKeyDown: (view, event) => {
+          if (
+            isMacPlatform(navigator.platform) &&
+            (event.key === "Home" || event.key === "End") &&
+            !event.altKey &&
+            !event.metaKey &&
+            !event.ctrlKey &&
+            !event.isComposing
+          ) {
+            const selection = window.getSelection();
+            if (
+              selection?.anchorNode &&
+              view.dom.contains(selection.anchorNode) &&
+              typeof selection.modify === "function"
+            ) {
+              event.preventDefault();
+              event.stopPropagation();
+              selection.modify(
+                event.shiftKey ? "extend" : "move",
+                event.key === "Home" ? "backward" : "forward",
+                "lineboundary",
+              );
+              if (selection.anchorNode && selection.focusNode) {
+                view.dispatch(
+                  view.state.tr
+                    .setSelection(
+                      TextSelection.create(
+                        view.state.doc,
+                        view.posAtDOM(selection.anchorNode, selection.anchorOffset),
+                        view.posAtDOM(selection.focusNode, selection.focusOffset),
+                      ),
+                    )
+                    .scrollIntoView(),
+                );
+              }
+              return true;
+            }
+          }
+          if (
+            (event.key === "ArrowLeft" || event.key === "ArrowRight") &&
+            !event.shiftKey &&
+            !event.altKey &&
+            !event.metaKey &&
+            !event.ctrlKey &&
+            !event.isComposing &&
+            view.state.selection.empty
+          ) {
+            const { $from } = view.state.selection;
+            const direction = event.key === "ArrowLeft" ? -1 : 1;
+            const adjacent = direction === -1 ? $from.nodeBefore : $from.nodeAfter;
+            if (adjacent?.type.name.startsWith("composer-")) {
+              event.preventDefault();
+              event.stopPropagation();
+              view.dispatch(
+                view.state.tr
+                  .setSelection(
+                    TextSelection.create(view.state.doc, $from.pos + direction * adjacent.nodeSize),
+                  )
+                  .scrollIntoView(),
+              );
+              return true;
+            }
+          }
+          if (event.key === "Enter" && (event.isComposing || event.keyCode === 229)) {
+            event.stopPropagation();
+            return true;
+          }
+          // Enter on a focused task checkbox must not send the prompt (or
+          // split anything): Space toggles it, Enter does nothing.
+          if (event.key === "Enter" && event.target instanceof HTMLInputElement) {
+            event.preventDefault();
+            return true;
+          }
+          const handler = onCommandKeyDownRef.current;
+          if (event.key === "Enter") {
+            const instance = editorHolder.current;
+            const isTaskItem = richText && (instance?.isActive("taskItem") ?? false);
+            const handled = handler?.("Enter", event, isTaskItem) ?? false;
+            if (handled) {
+              event.preventDefault();
+              event.stopPropagation();
+              return true;
+            }
+            event.preventDefault();
+            if (
+              isTaskItem &&
+              instance &&
+              (instance.commands.splitListItem("taskItem", { checked: false }) ||
+                (view.state.selection.$from.parent.content.size === 0 &&
+                  instance.commands.liftListItem("taskItem")))
+            ) {
+              return true;
+            }
+            // Split the paragraph so a single newline visibly advances the caret.
+            return splitBlockKeepMarks(view.state, (tr) => {
+              // The split is programmatic, so the browser won't follow the
+              // caret into view on its own.
+              view.dispatch(tr.scrollIntoView());
+            });
+          }
+          if (!handler) return false;
+          const key =
+            event.key === "Tab"
+              ? ("Tab" as const)
+              : event.key === "ArrowDown"
+                ? ("ArrowDown" as const)
+                : event.key === "ArrowUp"
+                  ? ("ArrowUp" as const)
+                  : null;
+          if (!key) return false;
+          const handled = handler(key, event);
+          if (handled) {
+            event.preventDefault();
+            event.stopPropagation();
+          }
+          return handled;
+        },
+        handleTextInput: (view, from, to, text) => {
+          const closer = SURROUND_CLOSE[text];
+          if (!closer || from === to) return false;
+          // Never wrap chips or other atoms, and never wrap styled text: the
+          // default replace keeps marks intact, wrapping would drop them.
+          let touchesSpecial = false;
+          view.state.doc.nodesBetween(from, to, (node) => {
+            if ((node.isAtom && node.isInline) || (node.isText && node.marks.length > 0)) {
+              touchesSpecial = true;
+              return false;
+            }
+            return true;
+          });
+          if (touchesSpecial) return false;
+          const map = serializeEditorDoc(view.state.doc);
+          const startMd = flatToMarkdown(map, pmToFlat(map, from));
+          const endMd = flatToMarkdown(map, pmToFlat(map, to));
+          if (selectionTouchesMentionBoundary(map.value, startMd, endMd)) return false;
+          const tr = view.state.tr.insertText(closer, to).insertText(text, from);
+          tr.setSelection(TextSelection.create(tr.doc, from + text.length, to + text.length));
+          view.dispatch(tr);
+          return true;
+        },
+        handlePaste: (view, event) => {
+          const clipboardData = event.clipboardData;
+          if (!clipboardData || clipboardData.files.length > 0) return false;
+          const pastedText = clipboardData.getData("text/plain");
+          if (!pastedText) return false;
+          event.preventDefault();
+          const importFragment = importFragmentRef.current;
+          let text = importFragment
+            ? importPastedComposerText(clipboardData, importFragment)
+            : pastedText;
+          // Complete chips at paste boundaries just as autocomplete does.
+          const tokens = collectComposerPromptInlineTokens(`${text}\n`);
+          const lastToken = tokens.at(-1);
+          if (
+            (lastToken?.type === "mention" || lastToken?.type === "skill") &&
+            lastToken.end === text.length
+          ) {
+            text += " ";
+          }
+          if (
+            (tokens[0]?.type === "mention" || tokens[0]?.type === "skill") &&
+            tokens[0].start === 0
+          ) {
+            const map = serializeEditorDoc(view.state.doc);
+            const offset = flatToMarkdown(map, pmToFlat(map, view.state.selection.from));
+            if (offset > 0 && !/\s/.test(map.value[offset - 1]!)) text = ` ${text}`;
+          }
+          const editorInstance = editorHolder.current;
+          if (editorInstance) {
+            insertMarkdownParagraphs(text, skillLabelFor, { styling: richText }, (content) => {
+              editorInstance.commands.insertContent(content);
+            });
+            scrollTiptapCaretIntoView(editorInstance);
+          }
+          return true;
+        },
+      },
+      onUpdate: ({ editor: updated }) => {
+        handleEditorChange(updated);
+      },
+      onSelectionUpdate: ({ editor: updated }) => {
+        handleEditorChange(updated);
+      },
+    },
+    [],
+  );
+
+  useEffect(() => {
+    editor?.setEditable(!disabled);
+  }, [disabled, editor]);
+
+  useEffect(() => {
+    editorHolder.current = editor;
+  }, [editor]);
+
+  const readSnapshot = useCallback(() => {
+    const snapshot = snapshotRef.current;
+    if (!editor) return snapshot;
+    const map = serializeEditorDoc(editor.state.doc);
+    const { from, to } = editor.state.selection;
+    const fromFlat = pmToFlat(map, from);
+    const next: typeof snapshot = {
+      value: map.value,
+      cursor: clampCollapsedComposerCursor(map.value, flatToCollapsed(map, fromFlat)),
+      expandedCursor: Math.max(0, Math.min(map.value.length, flatToMarkdown(map, fromFlat))),
+      contextIds: map.contextIds,
+    };
+    const toFlat = pmToFlat(map, to);
+    selectionRangeRef.current = {
+      start: Math.min(next.expandedCursor, flatToMarkdown(map, toFlat)),
+      end: Math.max(next.expandedCursor, flatToMarkdown(map, toFlat)),
+    };
+    snapshotRef.current = next;
+    return next;
+  }, [editor]);
+
+  // Controlled value/cursor from the store (history recall, chip insertion…).
+  useLayoutEffect(() => {
+    if (!editor) return;
+    const normalizedCursor = clampCollapsedComposerCursor(value, cursor);
+    const previousSnapshot = snapshotRef.current;
+    if (previousSnapshot.value === value && previousSnapshot.cursor === normalizedCursor) {

@@ -0,0 +1,597 @@
+import type { Node as ProseMirrorNode } from "@tiptap/pm/model";
+import { TaskItem } from "@tiptap/extension-task-item";
+
+import { splitPromptIntoComposerSegments } from "~/composer-editor-mentions";
+import { parseInlineMarkdown, RICH_TEXT_DELIMITERS, type RichTextMark } from "~/composer-rich-text";
+import { collectInlineContextIds } from "~/lib/composerContextReferences";
+
+/**
+ * Pure document model for the rich text (Tiptap) composer.
+ *
+ * The stored prompt stays markdown (`**bold**`, `@file` chips as canonical
+ * links). The Tiptap document holds styled text plus inline atom chips, so
+ * this module translates both ways and maps cursor offsets between the three
+ * coordinate spaces the composer speaks:
+ *
+ * - flat document offsets (styled markers excluded, chips count 1),
+ * - collapsed cursor offsets (markers literal, chips count 1 — the coordinate
+ *   the draft store and mention detection use),
+ * - markdown offsets (markers literal, chips expand to their source).
+ *
+ * DOM-free on purpose: unit tests build a real ProseMirror document from the
+ * JSON this produces and assert the round trip without a browser.
+ */
+
+export type SkillMeta = { label: string; description: string | null };
+
+/** Outermost mark first, so closers mirror openers when nested. */
+export const MARK_NESTING_ORDER: RichTextMark[] = ["strike", "bold", "italic", "code"];
+
+export const MARK_TO_TIPTAP: Record<RichTextMark, string> = {
+  bold: "bold",
+  italic: "italic",
+  strike: "strike",
+  code: "code",
+};
+
+export const TIPTAP_TO_MARK: Record<string, RichTextMark> = {
+  bold: "bold",
+  italic: "italic",
+  strike: "strike",
+  code: "code",
+};
+
+/**
+ * Task list items keep their exact source indent in an attribute so nesting
+ * round-trips byte-identically. Checkbox case (`[X]`) normalizes to `[x]` —
+ * the same fixed-point deal as `__bold__` becoming `**bold**`.
+ */
+export const ComposerTaskItemExtension = TaskItem.extend({
+  addAttributes() {
+    return {
+      ...this.parent?.(),
+      indent: { default: "" },
+    };
+  },
+}).configure({ nested: true });
+
+export function randomNodeKey(): string {
+  return `tiptap-${Math.random().toString(36).slice(2)}`;
+}
+
+interface TaskLinePrefix {
+  indent: string;
+  checked: boolean;
+}
+
+function parseTaskPrefix(head: string): { prefix: TaskLinePrefix; markerLength: number } | null {
+  const match = head.match(/^([ \t]*)-[ \t]+\[([ xX])\]/);
+  if (!match) return null;
+  const after = head.slice(match[0].length);
+  if (after.length > 0 && after[0] !== " " && after[0] !== "\t") return null;
+  return {
+    prefix: {
+      indent: match[1] ?? "",
+      checked: (match[2] ?? " ").toLowerCase() === "x",
+    },
+    markerLength: match[0].length,
+  };
+}
+
+type InlineJson = Record<string, unknown>;
+
+interface DocLine {
+  task: TaskLinePrefix | null;
+  inline: InlineJson[];
+}
+
+function atomJsonForSegment(
+  segment: Exclude<ReturnType<typeof splitPromptIntoComposerSegments>[number], { type: "text" }>,
+  skillLabelFor: (name: string) => SkillMeta,
+): InlineJson {
+  if (segment.type === "mention") {
+    return {
+      type: "composer-mention",
+      attrs: { path: segment.path, source: segment.source },
+    };
+  }
+  if (segment.type === "skill") {
+    const meta = skillLabelFor(segment.name);
+    return {
+      type: "composer-skill",
+      attrs: {
+        skillName: segment.name,
+        skillLabel: meta.label,
+        skillDescription: meta.description,
+      },
+    };
+  }
+  if (segment.type === "citation") {
+    return {
+      type: "composer-citation",
+      attrs: { citation: segment.citation, source: segment.source, citeKey: randomNodeKey() },
+    };
+  }
+  return {
+    type: "composer-context-reference",
+    attrs: {
+      kind: segment.kind,
+      contextId: segment.contextId,
+      label: segment.label,
+      source: segment.source,
+    },
+  };
+}
+
+function pushSpans(inline: InlineJson[], text: string, styling: boolean): void {
+  if (!styling) {
+    // Plain-text mode: markers stay literal characters, no marks anywhere.
+    if (text) inline.push({ type: "text", text });
+    return;
+  }
+  for (const span of parseInlineMarkdown(text)) {
+    inline.push(textJsonForSpan(span.text, span.marks));
+  }
+}
+
+interface PendingTaskItem {
+  checked: boolean;
+  indent: string;
+  content: InlineJson[];
+  children: PendingTaskItem[];
+}
+
+function taskListJson(items: PendingTaskItem[]): InlineJson {
+  return {
+    type: "taskList",
+    content: items.map((item) => ({
+      type: "taskItem",
+      attrs: { checked: item.checked, indent: item.indent },
+      content: [
+        { type: "paragraph", content: item.content },
+        ...(item.children.length > 0 ? [taskListJson(item.children)] : []),
+      ],
+    })),
+  };
+}
+
+function textJsonForSpan(text: string, marks: RichTextMark[]): Record<string, unknown> {
+  const json: Record<string, unknown> = { type: "text", text };
+  if (marks.length > 0) {
+    json.marks = [...marks]
+      .sort((a, b) => MARK_NESTING_ORDER.indexOf(a) - MARK_NESTING_ORDER.indexOf(b))
+      .map((mark) => ({ type: MARK_TO_TIPTAP[mark] }));
+  }
+  return json;
+}
+
+export function buildTiptapContent(
+  value: string,
+  skillLabelFor: (name: string) => SkillMeta,
+  options?: { styling?: boolean },
+): Record<string, unknown>[] {
+  const styling = options?.styling ?? true;
+  // Pass 1: the segment stream becomes lines. A line is a task line only
+  // when its leading text — before any chip — is a complete `- [ ]` marker;
+  // the marker is decided at a chip, a newline, or the end of input so a
+  // partial marker (`- [ ]` + `foo`) can never commit early.
+  const lines: DocLine[] = [{ task: null, inline: [] }];
+  let head: string | null = "";
+  const currentLine = () => lines[lines.length - 1]!;
+  const endLine = () => {
+    const line = currentLine();
+    if (head !== null) {
+      const parsed = styling ? parseTaskPrefix(head) : null;
+      if (parsed) {
+        line.task = parsed.prefix;
+        pushSpans(line.inline, head.slice(parsed.markerLength).replace(/^[ \t]*/, ""), styling);
+      } else {
+        pushSpans(line.inline, head, styling);
+      }
+    }
+    lines.push({ task: null, inline: [] });
+    head = "";
+  };
+  const appendTextPiece = (piece: string) => {
+    if (head !== null) {
+      head += piece;
+      return;
+    }
+    pushSpans(currentLine().inline, piece, styling);
+  };
+
+  for (const segment of splitPromptIntoComposerSegments(value)) {
+    if (segment.type === "text") {
+      const parts = segment.text.split("\n");
+      parts.forEach((part, index) => {
+        if (index > 0) endLine();
+        appendTextPiece(part);
+      });
+    } else {
+      if (head !== null) {
+        const line = currentLine();
+        const parsed = styling ? parseTaskPrefix(head) : null;
+        if (parsed) {
+          line.task = parsed.prefix;
+          pushSpans(line.inline, head.slice(parsed.markerLength).replace(/^[ \t]*/, ""), styling);
+        } else {
+          pushSpans(line.inline, head, styling);
+        }
+        head = null;
+      }
+      currentLine().inline.push(atomJsonForSegment(segment, skillLabelFor));
+    }
+  }
+  // Decide the final line. A trailing newline leaves a fresh empty line,
+  // which endLine already pushed — drop the spare blank it would add.
+  if (head !== null) {
+    const line = currentLine();
+    const parsed = styling ? parseTaskPrefix(head) : null;
+    if (parsed) {
+      line.task = parsed.prefix;
+      pushSpans(line.inline, head.slice(parsed.markerLength).replace(/^[ \t]*/, ""), styling);
+    } else {
+      pushSpans(line.inline, head, styling);
+    }
+  } else if (lines.length > 1) {
+    const last = lines[lines.length - 1]!;
+    if (!last.task && last.inline.length === 0) lines.pop();
+  }
+
+  // Pass 2: consecutive task lines group into (possibly nested) task lists
+  // by indent prefix; everything else stays a paragraph.
+  const blocks: Record<string, unknown>[] = [];
+  let stack: { indent: string; items: PendingTaskItem[] }[] = [];
+  const flushTasks = () => {
+    if (stack.length > 0) {
+      blocks.push(taskListJson(stack[0]!.items));
+      stack = [];
+    }
+  };
+  for (const line of lines) {
+    if (!line.task) {
+      flushTasks();
+      blocks.push({ type: "paragraph", content: line.inline });
+      continue;
+    }
+    const item: PendingTaskItem = {
+      checked: line.task.checked,
+      indent: line.task.indent,
+      content: line.inline,
+      children: [],
+    };
+    for (;;) {
+      const top = stack[stack.length - 1];
+      if (!top) {
+        // A leading indented item with no parent flattens but keeps indent.
+        stack.push({ indent: "", items: [] });
+        continue;
+      }
+      if (top.indent === item.indent) {
+        top.items.push(item);
+        break;
+      }
+      if (top.indent !== "" && !item.indent.startsWith(top.indent)) {
+        stack.pop();
+        continue;
+      }
+      const parent = top.items[top.items.length - 1];
+      if (!parent) {
+        top.items.push(item);
+        break;
+      }
+      parent.children.push(item);
+      stack.push({ indent: item.indent, items: parent.children });
+      break;
+    }
+  }
+  flushTasks();
+  return blocks;
+}
+
+export function buildDocJson(
+  value: string,
+  skillLabelFor: (name: string) => SkillMeta,
+  options?: { styling?: boolean },
+) {
+  return { type: "doc", content: buildTiptapContent(value, skillLabelFor, options) };
+}
+
+export interface RichRun {
+  kind: "text" | "token" | "break" | "prefix";
+  /** Flat document offset (atoms count 1, markers excluded). */
+  flatStart: number;
+  docLen: number;
+  /** Collapsed cursor length (markers literal, tokens count 1). */
+  collapsedLen: number;
+  /** Markdown length (tokens expand to their source). */
+  mdLen: number;
+  /** Marker layout inside text runs. */
+  openLen: number;
+  closeLen: number;
+  /** ProseMirror position of the run start. */
+  pmPos: number;
+  mdStart: number;
+  collapsedStart: number;
+  nodeName?: string;
+}
+
+export interface RichDocMap {
+  value: string;
+  runs: RichRun[];
+  docLength: number;
+  contextIds: string[];
+}
+
+function textRunDelimiters(marks: RichTextMark[]): { open: string; close: string } {
+  let open = "";
+  let close = "";
+  for (const mark of [...marks].sort(
+    (a, b) => MARK_NESTING_ORDER.indexOf(a) - MARK_NESTING_ORDER.indexOf(b),
+  )) {
+    const delimiter = RICH_TEXT_DELIMITERS[mark];
+    open = open + delimiter;
+    close = delimiter + close;
+  }
+  return { open, close };
+}
+
+function readAtomSource(node: ProseMirrorNode): string {
+  const attrs = node.attrs as Record<string, unknown>;
+  switch (node.type.name) {
+    case "composer-mention":
+    case "composer-citation":
+    case "composer-context-reference":
+      return typeof attrs.source === "string" ? attrs.source : "";
+    case "composer-skill": {
+      const name = typeof attrs.skillName === "string" ? attrs.skillName : "";
+      return name ? `$${name}` : "";
+    }
+    default:
+      return "";
+  }
+}
+
+interface RichAccumulator {
+  runs: RichRun[];
+  value: string;
+  flat: number;
+  collapsed: number;
+  md: number;
+}
+
+function pushBreakRun(acc: RichAccumulator, pmPos: number): void {
+  // Block boundary: one newline in every coordinate space.
+  acc.runs.push({
+    kind: "break",
+    flatStart: acc.flat,
+    docLen: 1,
+    collapsedLen: 1,
+    mdLen: 1,
+    openLen: 0,
+    closeLen: 0,
+    pmPos,
+    mdStart: acc.md,
+    collapsedStart: acc.collapsed,
+  });
+  acc.value += "\n";
+  acc.flat += 1;
+  acc.collapsed += 1;
+  acc.md += 1;
+}
+
+function appendInlineRuns(
+  container: ProseMirrorNode,
+  contentStart: number,
+  acc: RichAccumulator,
+): void {
+  let inlineOffset = 0;
+  container.content.forEach((child) => {
+    const pmPos = contentStart + inlineOffset;
+    if (child.isText && child.text) {
+      const marks = (child.marks ?? [])
+        .map((mark) => TIPTAP_TO_MARK[mark.type.name])
+        .filter((mark): mark is RichTextMark => Boolean(mark));
+      const { open, close } = textRunDelimiters(marks);
+      const mdText = `${open}${child.text}${close}`;
+      acc.runs.push({
+        kind: "text",
+        flatStart: acc.flat,
+        docLen: child.text.length,
+        collapsedLen: mdText.length,
+        mdLen: mdText.length,
+        openLen: open.length,
+        closeLen: close.length,
+        pmPos,
+        mdStart: acc.md,
+        collapsedStart: acc.collapsed,
+      });
+      acc.value += mdText;
+      acc.flat += child.text.length;
+      acc.collapsed += mdText.length;
+      acc.md += mdText.length;
+      inlineOffset += child.nodeSize;
+    } else if (child.type.name === "hardBreak") {
+      pushBreakRun(acc, pmPos);
+      inlineOffset += child.nodeSize;
+    } else if (child.isAtom || child.isInline) {
+      const source = readAtomSource(child);
+      acc.runs.push({
+        kind: "token",
+        flatStart: acc.flat,
+        docLen: 1,
+        collapsedLen: 1,
+        mdLen: source.length,
+        openLen: 0,
+        closeLen: 0,
+        pmPos,
+        mdStart: acc.md,
+        collapsedStart: acc.collapsed,
+        nodeName: child.type.name,
+      });
+      acc.value += source;
+      acc.flat += 1;
+      acc.collapsed += 1;
+      acc.md += source.length;
+      inlineOffset += child.nodeSize;
+    } else {
+      inlineOffset += child.nodeSize;
+    }
+  });
+}
+
+function walkTaskList(list: ProseMirrorNode, listStart: number, acc: RichAccumulator): void {
+  let itemPos = listStart + 1;
+  let firstItem = true;
+  list.content.forEach((item) => {
+    // Sibling items are separated by one newline in every coordinate space.
+    if (!firstItem) pushBreakRun(acc, itemPos - 1);
+    firstItem = false;
+    const itemContentStart = itemPos + 1;
+    const first = item.firstChild;
+    const empty =
+      item.childCount === 1 && first?.type.name === "paragraph" && first.content.childCount === 0;
+    const attrs = item.attrs as { checked?: unknown; indent?: unknown };
+    const indent = typeof attrs.indent === "string" ? attrs.indent : "";
+    const prefix = `${indent}- [${attrs.checked === true ? "x" : " "}]${empty ? "" : " "}`;
+    // The checkbox owns no document characters; every prefix offset clamps
+    // to the start of the item text, exactly like style markers.
+    acc.runs.push({
+      kind: "prefix",
+      flatStart: acc.flat,
+      docLen: 0,
+      collapsedLen: prefix.length,
+      mdLen: prefix.length,
+      openLen: 0,
+      closeLen: 0,
+      pmPos: itemContentStart + 1,
+      mdStart: acc.md,
+      collapsedStart: acc.collapsed,
+    });
+    acc.value += prefix;
+    acc.collapsed += prefix.length;
+    acc.md += prefix.length;
+    let childPos = itemContentStart;
+    let firstBlock = true;
+    item.content.forEach((child) => {
+      if (!firstBlock) pushBreakRun(acc, childPos - 1);
+      firstBlock = false;
+      if (child.type.name === "taskList") {
+        walkTaskList(child, childPos, acc);
+      } else if (child.type.name === "paragraph") {
+        appendInlineRuns(child, childPos + 1, acc);
+      }
+      childPos += child.nodeSize;
+    });
+    itemPos += item.nodeSize;
+  });
+}
+
+export function serializeEditorDoc(doc: ProseMirrorNode): RichDocMap {
+  const acc: RichAccumulator = { runs: [], value: "", flat: 0, collapsed: 0, md: 0 };
+  const blocks: ProseMirrorNode[] = [];
+  doc.content.forEach((node) => {
+    blocks.push(node);
+  });
+
+  let pmBlockStart = 0;
+  blocks.forEach((block, blockIndex) => {
+    if (blockIndex > 0) pushBreakRun(acc, pmBlockStart - 1);
+    if (block.type.name === "taskList") {
+      walkTaskList(block, pmBlockStart, acc);
+    } else if (block.type.name === "paragraph") {
+      appendInlineRuns(block, pmBlockStart + 1, acc);
+    }
+    pmBlockStart += block.nodeSize;
+  });
+
+  return {
+    value: acc.value,
+    runs: acc.runs,
+    docLength: acc.flat,
+    contextIds: Array.from(new Set(collectInlineContextIds(acc.value))),
+  };
+}
+
+function lastRunEnd(map: RichDocMap, space: "collapsed" | "md"): number {
+  const last = map.runs[map.runs.length - 1];
+  if (!last) return 0;
+  return space === "collapsed"
+    ? last.collapsedStart + last.collapsedLen
+    : last.mdStart + last.mdLen;
+}
+
+export function flatToCollapsed(map: RichDocMap, flatOffset: number): number {
+  const bounded = Math.max(0, Math.min(flatOffset, map.docLength));
+  for (const run of map.runs) {
+    if (bounded < run.flatStart + run.docLen) {
+      if (run.kind === "text") {
+        return run.collapsedStart + run.openLen + (bounded - run.flatStart);
+      }
+      return run.collapsedStart + (bounded - run.flatStart);
+    }
+  }
+  return lastRunEnd(map, "collapsed");
+}
+
+export function flatToMarkdown(map: RichDocMap, flatOffset: number): number {
+  const bounded = Math.max(0, Math.min(flatOffset, map.docLength));
+  for (const run of map.runs) {
+    if (bounded < run.flatStart + run.docLen) {
+      if (run.kind === "text") {
+        return run.mdStart + run.openLen + (bounded - run.flatStart);
+      }
+      return run.mdStart + (bounded - run.flatStart);
+    }
+  }
+  return lastRunEnd(map, "md");
+}
+
+export function collapsedToFlat(map: RichDocMap, collapsedOffset: number): number {
+  for (const run of map.runs) {
+    if (collapsedOffset < run.collapsedStart + run.collapsedLen) {
+      // Checkbox prefixes and style markers are shown, never edited: every
+      // offset inside them clamps to the adjacent document position.
+      if (run.kind === "prefix") return run.flatStart;
+      if (run.kind === "text") {
+        const within = collapsedOffset - run.collapsedStart;
+        // Marker characters clamp to the styled edge: they are shown, never edited.
+        if (within <= run.openLen) return run.flatStart;
+        if (within >= run.openLen + run.docLen) return run.flatStart + run.docLen;
+        return run.flatStart + (within - run.openLen);
+      }
+      return run.flatStart + (collapsedOffset - run.collapsedStart);
+    }
+  }
+  return map.docLength;
+}
+
+export function flatToPm(map: RichDocMap, flatOffset: number): number {
+  const bounded = Math.max(0, Math.min(flatOffset, map.docLength));
+  for (const run of map.runs) {
+    if (bounded < run.flatStart + run.docLen) {
+      return run.pmPos + (bounded - run.flatStart);
+    }
+  }
+  const last = map.runs[map.runs.length - 1];
+  if (!last) return 0;
+  return last.pmPos + last.docLen;

@@ -0,0 +1,1155 @@
+import { Extension, Node, type JSONContent } from "@tiptap/core";
+import { TaskList } from "@tiptap/extension-task-list";
+import { ReactNodeViewRenderer, NodeViewWrapper, type NodeViewProps } from "@tiptap/react";
+import StarterKit from "@tiptap/starter-kit";
+import { type Node as ProseMirrorNode } from "@tiptap/pm/model";
+import { splitBlockKeepMarks } from "@tiptap/pm/commands";
+import { Plugin, PluginKey, TextSelection } from "@tiptap/pm/state";
+import { Decoration, DecorationSet } from "@tiptap/pm/view";
+import type { AssistantCitation, ServerProviderSkill } from "@t3tools/contracts";
+import {
+  serializeAssistantCitation,
+  withAssistantCitationComment,
+} from "@t3tools/shared/assistantCitations";
+import {
+  COMPOSER_CONTEXT_CLIPBOARD_MIME,
+  encodeComposerContextClipboardHtml,
+} from "@t3tools/shared/composerContextClipboard";
+import {
+  createContext,
+  use,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { EditorContent, useEditor } from "@tiptap/react";
+
+import {
+  clampCollapsedComposerCursor,
+  collapseExpandedComposerCursor,
+  expandCollapsedComposerCursor,
+  isCollapsedCursorAdjacentToInlineToken,
+} from "~/composer-logic";
+import { selectionTouchesMentionBoundary } from "~/composer-editor-mentions";
+import { RICH_TEXT_DELIMITERS, type RichTextMark } from "~/composer-rich-text";
+import {
+  buildDocJson,
+  buildTiptapContent,
+  collapsedToFlat,
+  ComposerTaskItemExtension,
+  flatToCollapsed,
+  flatToMarkdown,
+  flatToPm,
+  MARK_NESTING_ORDER,
+  pmToFlat,
+  serializeEditorDoc,
+  TIPTAP_TO_MARK,
+  type SkillMeta,
+} from "~/composer-rich-text-doc";
+import { collectInlineContextIds } from "~/lib/composerContextReferences";
+import { cn } from "~/lib/utils";
+import { basenameOfPath } from "~/pierre-icons";
+import {
+  COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME,
+  COMPOSER_INLINE_CHIP_ICON_CLASS_NAME,
+  COMPOSER_INLINE_CHIP_LABEL_CLASS_NAME,
+  COMPOSER_INLINE_SKILL_CHIP_CLASS_NAME,
+  SKILL_CHIP_ICON_SVG,
+} from "./composerInlineChip";
+import { FILE_TAG_CHIP_CLASS_NAME, FileTagChipContent } from "./chat/FileTagChip";
+import { AssistantCitationChip } from "./chat/AssistantCitationChip";
+import { getTimelinePageScrollKey } from "./chat/pageScrollController";
+import { ContextChipPopover } from "./contextChipParts";
+import { Button } from "./ui/button";
+import {
+  ComposerContextActionsContext,
+  ComposerContextReferenceChip,
+  ComposerContextRecordsContext,
+} from "./composerContextPresentation";
+import {
+  ComposerCitationCommentContext,
+  type ComposerCitationCommentTarget,
+} from "./ComposerCitationNode";
+import type { AssistantCitationSourceAnchor } from "~/lib/assistantTextSelection";
+import { formatProviderSkillDisplayName } from "@t3tools/client-runtime/providerSkills";
+import { Tooltip, TooltipPopup, TooltipTrigger } from "./ui/tooltip";
+import { importPastedComposerText } from "./composerInlineTokenPaste";
+import { didComposerSelectionChangeVisibly } from "./composerSelection";
+import type {
+  ComposerPromptEditorHandle,
+  ComposerPromptEditorProps as LexicalComposerPromptEditorProps,
+} from "./ComposerPromptEditor";
+
+export type ComposerPromptEditorProps = LexicalComposerPromptEditorProps;
+
+type ComposerCitationCommentRequest = {
+  previousValue: string;
+  value: string;
+  citationStart: number;
+  sourceAnchor: AssistantCitationSourceAnchor;
+};
+
+type OpenCitationComment = {
+  key: string;
+  sourceAnchor?: AssistantCitationSourceAnchor;
+  removeOnCancel?: boolean;
+};
+
+const RichComposerSkillsContext = createContext<ReadonlyArray<ServerProviderSkill>>([]);
+
+const SURROUND_CLOSE: Record<string, string> = {
+  "(": ")",
+  "[": "]",
+  "{": "}",
+  "'": "'",
+  '"': '"',
+  "“": "”",
+  "`": "`",
+  "<": ">",
+  "«": "»",
+  "*": "*",
+  _: "_",
+};
+
+function resolvedThemeFromDocument(): "light" | "dark" {
+  return document.documentElement.classList.contains("dark") ? "dark" : "light";
+}
+
+// ── Inline atom nodes (chips) ─────────────────────────────────────────────
+
+const ComposerMentionExtension = Node.create({
+  name: "composer-mention",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      path: { default: "" },
+      source: { default: "" },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-mention]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-mention": "", ...HTMLAttributes }, 0];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerMentionNodeView);
+  },
+});
+
+function ComposerMentionNodeView({ node }: NodeViewProps) {
+  const actions = use(ComposerContextActionsContext);
+  const path = (node.attrs.path as string) ?? "";
+  const chip = (
+    <button
+      type="button"
+      onClick={() => actions.openMention(path)}
+      aria-label={`Preview ${path}`}
+      className={`${FILE_TAG_CHIP_CLASS_NAME} cursor-pointer focus-visible:outline-2`}
+      contentEditable={false}
+      spellCheck={false}
+      data-composer-mention-chip="true"
+    >
+      <FileTagChipContent
+        path={path}
+        label={basenameOfPath(path)}
+        theme={resolvedThemeFromDocument()}
+      />
+    </button>
+  );
+  return (
+    <NodeViewWrapper as="span" className={COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME}>
+      <Tooltip>
+        <TooltipTrigger render={chip} />
+        <TooltipPopup
+          side="top"
+          className="max-w-120 whitespace-normal leading-tight wrap-anywhere"
+        >
+          {path}
+        </TooltipPopup>
+      </Tooltip>
+    </NodeViewWrapper>
+  );
+}
+
+const ComposerSkillExtension = Node.create({
+  name: "composer-skill",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      skillName: { default: "" },
+      skillLabel: { default: "" },
+      skillDescription: { default: null },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-skill]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-skill": "", ...HTMLAttributes }, 0];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerSkillNodeView);
+  },
+});
+
+function ComposerSkillNodeView({ node }: NodeViewProps) {
+  const actions = use(ComposerContextActionsContext);
+  const skills = use(RichComposerSkillsContext);
+  const skillName = (node.attrs.skillName as string) ?? "";
+  const skillLabel = (node.attrs.skillLabel as string) || skillName;
+  const skillDescription = (node.attrs.skillDescription as string | null) ?? null;
+  const skill = skills.find((candidate) => candidate.name === skillName);
+  return (
+    <NodeViewWrapper as="span" className={COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME}>
+      <ContextChipPopover
+        accessibleLabel={`Skill ${skillLabel}`}
+        triggerClassName={COMPOSER_INLINE_SKILL_CHIP_CLASS_NAME}
+        chip={
+          <>
+            <span
+              aria-hidden="true"
+              className={COMPOSER_INLINE_CHIP_ICON_CLASS_NAME}
+              dangerouslySetInnerHTML={{ __html: SKILL_CHIP_ICON_SVG }}
+            />
+            <span className={COMPOSER_INLINE_CHIP_LABEL_CLASS_NAME}>{skillLabel}</span>
+          </>
+        }
+      >
+        <div className="space-y-3 p-2 text-sm">
+          <p className="font-medium">{skillLabel}</p>
+          <p>
+            {skill?.description ??
+              skillDescription ??
+              "No description is available for this skill."}
+          </p>
+          {skill?.path ? (
+            <Button variant="outline" size="sm" onClick={() => actions.openMention(skill.path)}>
+              View instructions
+            </Button>
+          ) : null}
+        </div>
+      </ContextChipPopover>
+    </NodeViewWrapper>
+  );
+}
+
+const ComposerCitationExtension = Node.create({
+  name: "composer-citation",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      citation: { default: null },
+      source: { default: "" },
+      citeKey: { default: "" },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-citation]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-citation": "", ...HTMLAttributes }, 0];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerCitationNodeView);
+  },
+});
+
+function ComposerCitationNodeView({ node, editor, getPos }: NodeViewProps) {
+  const commentContext = use(ComposerCitationCommentContext);
+  const citation = node.attrs.citation as AssistantCitation;
+  const citeKey = node.attrs.citeKey as string;
+  const commentTarget =
+    commentContext.openComment !== null &&
+    typeof commentContext.openComment === "object" &&
+    "key" in (commentContext.openComment as Record<string, unknown>) &&
+    (commentContext.openComment as unknown as OpenCitationComment).key === citeKey
+      ? (commentContext.openComment as unknown as OpenCitationComment)
+      : null;
+
+  const nodePos = useCallback(() => {
+    const pos = typeof getPos === "function" ? getPos() : null;
+    return typeof pos === "number" ? pos : null;
+  }, [getPos]);
+
+  const onSaveComment = useCallback(
+    (comment: string): boolean => {
+      if (!editor.isEditable) return false;
+      const pos = nodePos();
+      if (pos === null) return false;
+      const current = editor.state.doc.nodeAt(pos);
+      if (!current || current.type.name !== "composer-citation") return false;
+      const currentCitation = current.attrs.citation as AssistantCitation;
+      const next = withAssistantCitationComment(currentCitation, comment);
+      const tr = editor.state.tr.setNodeMarkup(pos, undefined, {
+        ...current.attrs,
+        citation: next,
+        source: serializeAssistantCitation(next),
+      });
+      editor.view.dispatch(tr);
+      return true;
+    },
+    [editor, nodePos],
+  );
+
+  const onRemove = useCallback(() => {
+    if (!editor.isEditable) return;
+    const pos = nodePos();
+    if (pos === null) return;
+    const current = editor.state.doc.nodeAt(pos);
+    if (!current) return;
+    editor
+      .chain()
+      .focus()
+      .deleteRange({ from: pos, to: pos + current.nodeSize })
+      .run();
+  }, [editor, nodePos]);
+
+  return (
+    <NodeViewWrapper
+      as="span"
+      className="inline-flex min-w-0 max-w-full"
+      contentEditable={false}
+      spellCheck={false}
+      data-composer-citation-chip="true"
+    >
+      <AssistantCitationChip
+        citation={citation}
+        composer
+        commentEditor={{
+          open: commentTarget !== null,
+          sourceAnchor: commentTarget?.sourceAnchor,
+          onOpenChange: (open) => {
+            if (open && !editor.isEditable) return;
+            commentContext.onOpenChange(citeKey, open);
+          },
+          ...(commentTarget?.removeOnCancel ? { onCancel: onRemove } : {}),
+          onSave: onSaveComment,
+          onSaveAndSend: (comment) => {
+            if (!onSaveComment(comment)) return false;
+            commentContext.onSubmitAndSend();
+            return true;
+          },
+        }}
+      />
+    </NodeViewWrapper>
+  );
+}
+
+const ComposerContextReferenceExtension = Node.create({
+  name: "composer-context-reference",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      kind: { default: "" },
+      contextId: { default: "" },
+      label: { default: "" },
+      source: { default: "" },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-context-reference]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-context-reference": "", ...HTMLAttributes }, 0];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerContextReferenceNodeView);
+  },
+});
+
+function ComposerContextReferenceNodeView({ node }: NodeViewProps) {
+  return (
+    <NodeViewWrapper as="span" className={COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME}>
+      <ComposerContextReferenceChip
+        kind={(node.attrs.kind as string) ?? ""}
+        contextId={(node.attrs.contextId as string) ?? ""}
+        label={(node.attrs.label as string) ?? ""}
+      />
+    </NodeViewWrapper>
+  );
+}
+
+// ── Marker reveal (show ** when the cursor is on styled text) ──────────────
+
+type StyledRange = {
+  from: number;
+  to: number;
+  delimiter: string;
+};
+
+function collectStyledRanges(doc: ProseMirrorNode): StyledRange[] {
+  const ranges: StyledRange[] = [];
+  doc.descendants((node, pos) => {
+    if (!node.isText || !node.text) return true;
+    const marks = (node.marks ?? [])
+      .map((mark) => TIPTAP_TO_MARK[mark.type.name])
+      .filter((mark): mark is RichTextMark => Boolean(mark));
+    if (marks.length === 0) return false;
+    const ordered = [...marks].sort(
+      (a, b) => MARK_NESTING_ORDER.indexOf(a) - MARK_NESTING_ORDER.indexOf(b),
+    );
+    const delimiter = ordered.map((mark) => RICH_TEXT_DELIMITERS[mark]).join("");
+    const last = ranges[ranges.length - 1];
+    if (last && last.to === pos && last.delimiter === delimiter) {
+      last.to = pos + (node.text?.length ?? 0);
+    } else {
+      ranges.push({ from: pos, to: pos + (node.text?.length ?? 0), delimiter });
+    }
+    return false;
+  });
+  return ranges;
+}
+
+const MarkerPluginKey = new PluginKey("composer-rich-markers");
+
+const ComposerMarkerPlugin = new Plugin({
+  key: MarkerPluginKey,
+  state: {
+    init: (_, state) => decorationsForSelection(state.doc, state.selection),
+    apply: (tr, old) =>
+      tr.docChanged || tr.selectionSet ? decorationsForSelection(tr.doc, tr.selection) : old,
+  },
+  props: {
+    decorations(state) {
+      return MarkerPluginKey.getState(state);
+    },
+  },
+});
+
+function decorationsForSelection(
+  doc: ProseMirrorNode,
+  selection: { from: number; to: number; empty: boolean },
+): DecorationSet {
+  const decorations: Decoration[] = [];
+  for (const range of collectStyledRanges(doc)) {
+    const active = selection.empty
+      ? selection.from >= range.from && selection.from <= range.to
+      : selection.from < range.to && selection.to > range.from;
+    if (!active) continue;
+    for (const [at, side] of [
+      [range.from, -1],
+      [range.to, 1],
+    ] as const) {
+      const marker = document.createElement("span");
+      marker.className = "composer-rich-marker";
+      marker.textContent = range.delimiter;
+      marker.setAttribute("aria-hidden", "true");
+      decorations.push(Decoration.widget(at, marker, { side, key: `marker-${at}-${side}` }));
+    }
+  }
+  return DecorationSet.create(doc, decorations);
+}
+
+const ComposerMarkersExtension = Extension.create({
+  name: "composer-rich-markers",
+  addProseMirrorPlugins() {
+    return [ComposerMarkerPlugin];
+  },
+});
+
+// Document model (markdown ⇄ ProseMirror) lives in ~/composer-rich-text-doc so
+// unit tests can round-trip it without a browser.
+// ── Editor component ───────────────────────────────────────────────────────
+
+type TiptapEditor = NonNullable<ReturnType<typeof useEditor>>;
+
+export function ComposerPromptEditorTiptap(props: ComposerPromptEditorProps) {
+  const {
+    value,
+    cursor,
+    contextRecords,
+    buildContextClipboardFragment,
+    importContextFragment,
+    skills,
+    disabled,
+    placeholder,
+    containerClassName,
+    className,
+    placeholderClassName,
+    onChange,
+    onVisibleSelectionChange,
+    onCommandKeyDown,
+    onPageScrollKeyDown,
+    onPageScrollKeyUp,
+    onPageScrollRelease,
+    onCitationSubmitAndSend,
+    onPaste,
+    editorRef,
+  } = props;
+
+  const onChangeRef = useRef(onChange);
+  const onVisibleSelectionChangeRef = useRef(onVisibleSelectionChange);
+  const onCommandKeyDownRef = useRef(onCommandKeyDown);
+  const buildFragmentRef = useRef(buildContextClipboardFragment);
+  const importFragmentRef = useRef(importContextFragment);
+  const skillsRef = useRef(skills);
+  const latestValueRef = useRef(value);
+  // The editor instance for callbacks created before it exists (paste).
+  // Effects flush before any user interaction, so this is always set.
+  const editorHolder = useRef<TiptapEditor | null>(null);
+
+  useEffect(() => {
+    onChangeRef.current = onChange;
+  }, [onChange]);
+  useEffect(() => {
+    onVisibleSelectionChangeRef.current = onVisibleSelectionChange;
+  }, [onVisibleSelectionChange]);
+  useEffect(() => {
+    onCommandKeyDownRef.current = onCommandKeyDown;
+  }, [onCommandKeyDown]);
+  useEffect(() => {
+    buildFragmentRef.current = buildContextClipboardFragment;
+  }, [buildContextClipboardFragment]);
+  useEffect(() => {
+    importFragmentRef.current = importContextFragment;
+  }, [importContextFragment]);
+  useEffect(() => {
+    skillsRef.current = skills;
+  }, [skills]);
+  useLayoutEffect(() => {
+    latestValueRef.current = value;
+  }, [value]);
+
+  const skillLabelFor = useCallback((name: string): SkillMeta => {
+    const normalized = name.startsWith("$") ? name.slice(1) : name;
+    const skill = skillsRef.current.find((candidate) => candidate.name === normalized);
+    if (!skill) {
+      return { label: formatProviderSkillDisplayName({ name: normalized }), description: null };
+    }
+    const shortDescription = skill.shortDescription?.trim();
+    return {
+      label: formatProviderSkillDisplayName(skill),
+      description: shortDescription || skill.description?.trim() || null,
+    };
+  }, []);
+
+  const initialCursor = clampCollapsedComposerCursor(value, cursor);
+  const initialExpandedCursor = expandCollapsedComposerCursor(value, initialCursor);
+  const snapshotRef = useRef({
+    value,
+    cursor: initialCursor,
+    expandedCursor: initialExpandedCursor,
+    contextIds: collectInlineContextIds(value),
+  });
+  const selectionRangeRef = useRef({ start: initialExpandedCursor, end: initialExpandedCursor });
+  const isApplyingControlledUpdateRef = useRef(false);
+  const citationRequestRef = useRef<ComposerCitationCommentRequest | null>(null);
+  const [openCitation, setOpenCitation] = useState<OpenCitationComment | null>(null);
+  const [isEmpty, setIsEmpty] = useState(value.length === 0);
+
+  const citationCommentActions = useMemo(
+    () => ({
+      openComment: (openCitation ?? null) as unknown as ComposerCitationCommentTarget | null,
+      onOpenChange: (nodeKey: string, open: boolean) => {
+        setOpenCitation((current) => {
+          if (open) {
+            if (current?.key === nodeKey) return current;
+            return { key: nodeKey };
+          }
+          return current?.key === nodeKey ? null : current;
+        });
+      },
+      onSubmitAndSend: onCitationSubmitAndSend ?? (() => {}),
+    }),
+    [onCitationSubmitAndSend, openCitation],
+  );
+
+  const handleEditorChange = useCallback((updated: TiptapEditor) => {
+    const map = serializeEditorDoc(updated.state.doc);
+    const { from, to } = updated.state.selection;
+    const fromFlat = pmToFlat(map, from);
+    const toFlat = pmToFlat(map, to);
+    const nextValue = map.value;
+    const nextCursor = clampCollapsedComposerCursor(map.value, flatToCollapsed(map, fromFlat));
+    const nextExpandedCursor = Math.max(
+      0,
+      Math.min(map.value.length, flatToMarkdown(map, fromFlat)),
+    );
+    const nextSelectionRange = {
+      start: Math.min(nextExpandedCursor, flatToMarkdown(map, toFlat)),
+      end: Math.max(nextExpandedCursor, flatToMarkdown(map, toFlat)),
+    };
+    const previousSelectionRange = selectionRangeRef.current;
+    selectionRangeRef.current = nextSelectionRange;
+    setIsEmpty(nextValue.length === 0);
+    const previousSnapshot = snapshotRef.current;
+    const snapshotChanged = !(
+      previousSnapshot.value === nextValue &&
+      previousSnapshot.cursor === nextCursor &&
+      previousSnapshot.expandedCursor === nextExpandedCursor &&
+      previousSnapshot.contextIds.length === map.contextIds.length &&
+      previousSnapshot.contextIds.every((id, index) => id === map.contextIds[index])
+    );
+    if (isApplyingControlledUpdateRef.current) return;
+    if (!snapshotChanged) {
+      if (didComposerSelectionChangeVisibly(previousSelectionRange, nextSelectionRange)) {
+        onVisibleSelectionChangeRef.current?.();
+      }
+      return;
+    }
+    // A selection-only update while a newer prompt waits to be applied (a chip
+    // was just inserted through the store) would report stale text and clobber
+    // the prompt. Let the controlled rewrite land instead.
+    if (previousSnapshot.value === nextValue && nextValue !== latestValueRef.current) {
+      return;
+    }
+    snapshotRef.current = {
+      value: nextValue,
+      cursor: nextCursor,
+      expandedCursor: nextExpandedCursor,
+      contextIds: map.contextIds,
+    };
+    const cursorAdjacentToMention =
+      isCollapsedCursorAdjacentToInlineToken(nextValue, nextCursor, "left") ||
+      isCollapsedCursorAdjacentToInlineToken(nextValue, nextCursor, "right");
+    onChangeRef.current(
+      nextValue,
+      nextCursor,
+      nextExpandedCursor,
+      cursorAdjacentToMention,
+      map.contextIds,
+    );
+  }, []);
+
+  const editor = useEditor(
+    {
+      extensions: [
+        StarterKit.configure({
+          blockquote: false,
+          bulletList: false,
+          codeBlock: false,
+          heading: false,
+          horizontalRule: false,
+          listItem: false,
+          orderedList: false,
+          dropcursor: false,
+          gapcursor: false,
+          trailingNode: false,
+        }),
+        ComposerMentionExtension,
+        ComposerSkillExtension,
+        ComposerCitationExtension,
+        ComposerContextReferenceExtension,
+        TaskList,
+        ComposerTaskItemExtension,
+        ComposerMarkersExtension,
+      ],
+      content: buildDocJson(value, (name) => {
+        const normalized = name.startsWith("$") ? name.slice(1) : name;
+        const found = skills.find((candidate) => candidate.name === normalized);
+        if (!found) {
+          return { label: formatProviderSkillDisplayName({ name: normalized }), description: null };
+        }
+        const shortDescription = found.shortDescription?.trim();
+        return {
+          label: formatProviderSkillDisplayName(found),
+          description: shortDescription || found.description?.trim() || null,
+        };
+      }),
+      editable: !disabled,
+      editorProps: {
+        attributes: {
+          class: cn(
+            "composer-tiptap block max-h-50 min-h-17.5 w-full overflow-y-auto whitespace-pre-wrap wrap-break-word bg-transparent leading-relaxed text-foreground focus:outline-none",
+            className,
+          ),
+          "data-testid": "composer-editor",
+          "aria-placeholder": placeholder,
+        },
+        handleKeyDown: (view, event) => {
+          if (event.key === "Enter" && (event.isComposing || event.keyCode === 229)) {
+            event.stopPropagation();
+            return true;
+          }
+          // Enter on a focused task checkbox must not send the prompt (or
+          // split anything): Space toggles it, Enter does nothing.
+          if (event.key === "Enter" && event.target instanceof HTMLInputElement) {
+            event.preventDefault();
+            return true;
+          }
+          const handler = onCommandKeyDownRef.current;
+          if (event.key === "Enter") {
+            const handled = handler?.("Enter", event) ?? false;
+            if (handled) {
+              event.preventDefault();
+              event.stopPropagation();
+              return true;
+            }
+            // A newline the parent declined (Shift+Enter, or Enter while the
+            // shortcut says otherwise) must be one visible line. Letting it
+            // fall through inserts a native trailing `<br>`, which renders
+            // no visible line, so the caret looks stuck until a second press.
+            // Splitting the paragraph matches the Lexical surface: one press,
+            // one line. Enter on a list line never gets here — the parent
+            // claims it for continuation — so Tiptap's list splitting stays
+            // shadowed and both surfaces serialize identically.
+            event.preventDefault();
+            return splitBlockKeepMarks(view.state, (tr) => {
+              // The split is programmatic, so the browser won't follow the
+              // caret into view on its own.
+              view.dispatch(tr.scrollIntoView());
+            });
+          }
+          if (!handler) return false;
+          const key =
+            event.key === "Tab"
+              ? ("Tab" as const)
+              : event.key === "ArrowDown"
+                ? ("ArrowDown" as const)
+                : event.key === "ArrowUp"
+                  ? ("ArrowUp" as const)
+                  : null;
+          if (!key) return false;
+          const handled = handler(key, event);
+          if (handled) {
+            event.preventDefault();
+            event.stopPropagation();
+          }
+          return handled;
+        },
+        handleTextInput: (view, from, to, text) => {
+          const closer = SURROUND_CLOSE[text];
+          if (!closer || from === to) return false;
+          // Never wrap chips or other atoms, and never wrap styled text: the
+          // default replace keeps marks intact, wrapping would drop them.
+          let touchesSpecial = false;
+          view.state.doc.nodesBetween(from, to, (node) => {
+            if ((node.isAtom && node.isInline) || (node.isText && node.marks.length > 0)) {
+              touchesSpecial = true;
+              return false;
+            }
+            return true;
+          });
+          if (touchesSpecial) return false;
+          const map = serializeEditorDoc(view.state.doc);
+          const startMd = flatToMarkdown(map, pmToFlat(map, from));
+          const endMd = flatToMarkdown(map, pmToFlat(map, to));
+          if (selectionTouchesMentionBoundary(map.value, startMd, endMd)) return false;
+          const tr = view.state.tr.insertText(closer, to).insertText(text, from);
+          tr.setSelection(TextSelection.create(tr.doc, from + text.length, to + text.length));
+          view.dispatch(tr);
+          return true;
+        },
+        handlePaste: (view, event) => {
+          const clipboardData = event.clipboardData;
+          if (!clipboardData || clipboardData.files.length > 0) return false;
+          const pastedText = clipboardData.getData("text/plain");
+          if (!pastedText) return false;
+          event.preventDefault();
+          const importFragment = importFragmentRef.current;
+          const text = importFragment
+            ? importPastedComposerText(clipboardData, importFragment)
+            : pastedText;
+          const editorInstance = editorHolder.current;
+          if (editorInstance) {
+            insertMarkdownParagraphs(text, skillLabelFor, (content) => {

@@ -0,0 +1,1155 @@
+import { Extension, Node, type JSONContent } from "@tiptap/core";
+import { TaskList } from "@tiptap/extension-task-list";
+import { ReactNodeViewRenderer, NodeViewWrapper, type NodeViewProps } from "@tiptap/react";
+import StarterKit from "@tiptap/starter-kit";
+import { type Node as ProseMirrorNode } from "@tiptap/pm/model";
+import { splitBlockKeepMarks } from "@tiptap/pm/commands";
+import { Plugin, PluginKey, TextSelection } from "@tiptap/pm/state";
+import { Decoration, DecorationSet } from "@tiptap/pm/view";
+import type { AssistantCitation, ServerProviderSkill } from "@t3tools/contracts";
+import {
+  serializeAssistantCitation,
+  withAssistantCitationComment,
+} from "@t3tools/shared/assistantCitations";
+import {
+  COMPOSER_CONTEXT_CLIPBOARD_MIME,
+  encodeComposerContextClipboardHtml,
+} from "@t3tools/shared/composerContextClipboard";
+import {
+  createContext,
+  use,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { EditorContent, useEditor } from "@tiptap/react";
+
+import {
+  clampCollapsedComposerCursor,
+  collapseExpandedComposerCursor,
+  expandCollapsedComposerCursor,
+  isCollapsedCursorAdjacentToInlineToken,
+} from "~/composer-logic";
+import { selectionTouchesMentionBoundary } from "~/composer-editor-mentions";
+import { RICH_TEXT_DELIMITERS, type RichTextMark } from "~/composer-rich-text";
+import {
+  buildDocJson,
+  buildTiptapContent,
+  collapsedToFlat,
+  ComposerTaskItemExtension,
+  flatToCollapsed,
+  flatToMarkdown,
+  flatToPm,
+  MARK_NESTING_ORDER,
+  pmToFlat,
+  serializeEditorDoc,
+  TIPTAP_TO_MARK,
+  type SkillMeta,
+} from "~/composer-rich-text-doc";
+import { collectInlineContextIds } from "~/lib/composerContextReferences";
+import { cn } from "~/lib/utils";
+import { basenameOfPath } from "~/pierre-icons";
+import {
+  COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME,
+  COMPOSER_INLINE_CHIP_ICON_CLASS_NAME,
+  COMPOSER_INLINE_CHIP_LABEL_CLASS_NAME,
+  COMPOSER_INLINE_SKILL_CHIP_CLASS_NAME,
+  SKILL_CHIP_ICON_SVG,
+} from "./composerInlineChip";
+import { FILE_TAG_CHIP_CLASS_NAME, FileTagChipContent } from "./chat/FileTagChip";
+import { AssistantCitationChip } from "./chat/AssistantCitationChip";
+import { getTimelinePageScrollKey } from "./chat/pageScrollController";
+import { ContextChipPopover } from "./contextChipParts";
+import { Button } from "./ui/button";
+import {
+  ComposerContextActionsContext,
+  ComposerContextReferenceChip,
+  ComposerContextRecordsContext,
+} from "./composerContextPresentation";
+import {
+  ComposerCitationCommentContext,
+  type ComposerCitationCommentTarget,
+} from "./ComposerCitationNode";
+import type { AssistantCitationSourceAnchor } from "~/lib/assistantTextSelection";
+import { formatProviderSkillDisplayName } from "@t3tools/client-runtime/providerSkills";
+import { Tooltip, TooltipPopup, TooltipTrigger } from "./ui/tooltip";
+import { importPastedComposerText } from "./composerInlineTokenPaste";
+import { didComposerSelectionChangeVisibly } from "./composerSelection";
+import type {
+  ComposerPromptEditorHandle,
+  ComposerPromptEditorProps as LexicalComposerPromptEditorProps,
+} from "./ComposerPromptEditor";
+
+export type ComposerPromptEditorProps = LexicalComposerPromptEditorProps;
+
+type ComposerCitationCommentRequest = {
+  previousValue: string;
+  value: string;
+  citationStart: number;
+  sourceAnchor: AssistantCitationSourceAnchor;
+};
+
+type OpenCitationComment = {
+  key: string;
+  sourceAnchor?: AssistantCitationSourceAnchor;
+  removeOnCancel?: boolean;
+};
+
+const RichComposerSkillsContext = createContext<ReadonlyArray<ServerProviderSkill>>([]);
+
+const SURROUND_CLOSE: Record<string, string> = {
+  "(": ")",
+  "[": "]",
+  "{": "}",
+  "'": "'",
+  '"': '"',
+  "“": "”",
+  "`": "`",
+  "<": ">",
+  "«": "»",
+  "*": "*",
+  _: "_",
+};
+
+function resolvedThemeFromDocument(): "light" | "dark" {
+  return document.documentElement.classList.contains("dark") ? "dark" : "light";
+}
+
+// ── Inline atom nodes (chips) ─────────────────────────────────────────────
+
+const ComposerMentionExtension = Node.create({
+  name: "composer-mention",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      path: { default: "" },
+      source: { default: "" },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-mention]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-mention": "", ...HTMLAttributes }, 0];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerMentionNodeView);
+  },
+});
+
+function ComposerMentionNodeView({ node }: NodeViewProps) {
+  const actions = use(ComposerContextActionsContext);
+  const path = (node.attrs.path as string) ?? "";
+  const chip = (
+    <button
+      type="button"
+      onClick={() => actions.openMention(path)}
+      aria-label={`Preview ${path}`}
+      className={`${FILE_TAG_CHIP_CLASS_NAME} cursor-pointer focus-visible:outline-2`}
+      contentEditable={false}
+      spellCheck={false}
+      data-composer-mention-chip="true"
+    >
+      <FileTagChipContent
+        path={path}
+        label={basenameOfPath(path)}
+        theme={resolvedThemeFromDocument()}
+      />
+    </button>
+  );
+  return (
+    <NodeViewWrapper as="span" className={COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME}>
+      <Tooltip>
+        <TooltipTrigger render={chip} />
+        <TooltipPopup
+          side="top"
+          className="max-w-120 whitespace-normal leading-tight wrap-anywhere"
+        >
+          {path}
+        </TooltipPopup>
+      </Tooltip>
+    </NodeViewWrapper>
+  );
+}
+
+const ComposerSkillExtension = Node.create({
+  name: "composer-skill",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      skillName: { default: "" },
+      skillLabel: { default: "" },
+      skillDescription: { default: null },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-skill]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-skill": "", ...HTMLAttributes }, 0];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerSkillNodeView);
+  },
+});
+
+function ComposerSkillNodeView({ node }: NodeViewProps) {
+  const actions = use(ComposerContextActionsContext);
+  const skills = use(RichComposerSkillsContext);
+  const skillName = (node.attrs.skillName as string) ?? "";
+  const skillLabel = (node.attrs.skillLabel as string) || skillName;
+  const skillDescription = (node.attrs.skillDescription as string | null) ?? null;
+  const skill = skills.find((candidate) => candidate.name === skillName);
+  return (
+    <NodeViewWrapper as="span" className={COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME}>
+      <ContextChipPopover
+        accessibleLabel={`Skill ${skillLabel}`}
+        triggerClassName={COMPOSER_INLINE_SKILL_CHIP_CLASS_NAME}
+        chip={
+          <>
+            <span
+              aria-hidden="true"
+              className={COMPOSER_INLINE_CHIP_ICON_CLASS_NAME}
+              dangerouslySetInnerHTML={{ __html: SKILL_CHIP_ICON_SVG }}
+            />
+            <span className={COMPOSER_INLINE_CHIP_LABEL_CLASS_NAME}>{skillLabel}</span>
+          </>
+        }
+      >
+        <div className="space-y-3 p-2 text-sm">
+          <p className="font-medium">{skillLabel}</p>
+          <p>
+            {skill?.description ??
+              skillDescription ??
+              "No description is available for this skill."}
+          </p>
+          {skill?.path ? (
+            <Button variant="outline" size="sm" onClick={() => actions.openMention(skill.path)}>
+              View instructions
+            </Button>
+          ) : null}
+        </div>
+      </ContextChipPopover>
+    </NodeViewWrapper>
+  );
+}
+
+const ComposerCitationExtension = Node.create({
+  name: "composer-citation",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      citation: { default: null },
+      source: { default: "" },
+      citeKey: { default: "" },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-citation]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-citation": "", ...HTMLAttributes }, 0];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerCitationNodeView);
+  },
+});
+
+function ComposerCitationNodeView({ node, editor, getPos }: NodeViewProps) {
+  const commentContext = use(ComposerCitationCommentContext);
+  const citation = node.attrs.citation as AssistantCitation;
+  const citeKey = node.attrs.citeKey as string;
+  const commentTarget =
+    commentContext.openComment !== null &&
+    typeof commentContext.openComment === "object" &&
+    "key" in (commentContext.openComment as Record<string, unknown>) &&
+    (commentContext.openComment as unknown as OpenCitationComment).key === citeKey
+      ? (commentContext.openComment as unknown as OpenCitationComment)
+      : null;
+
+  const nodePos = useCallback(() => {
+    const pos = typeof getPos === "function" ? getPos() : null;
+    return typeof pos === "number" ? pos : null;
+  }, [getPos]);
+
+  const onSaveComment = useCallback(
+    (comment: string): boolean => {
+      if (!editor.isEditable) return false;
+      const pos = nodePos();
+      if (pos === null) return false;
+      const current = editor.state.doc.nodeAt(pos);
+      if (!current || current.type.name !== "composer-citation") return false;
+      const currentCitation = current.attrs.citation as AssistantCitation;
+      const next = withAssistantCitationComment(currentCitation, comment);
+      const tr = editor.state.tr.setNodeMarkup(pos, undefined, {
+        ...current.attrs,
+        citation: next,
+        source: serializeAssistantCitation(next),
+      });
+      editor.view.dispatch(tr);
+      return true;
+    },
+    [editor, nodePos],
+  );
+
+  const onRemove = useCallback(() => {
+    if (!editor.isEditable) return;
+    const pos = nodePos();
+    if (pos === null) return;
+    const current = editor.state.doc.nodeAt(pos);
+    if (!current) return;
+    editor
+      .chain()
+      .focus()
+      .deleteRange({ from: pos, to: pos + current.nodeSize })
+      .run();
+  }, [editor, nodePos]);
+
+  return (
+    <NodeViewWrapper
+      as="span"
+      className="inline-flex min-w-0 max-w-full"
+      contentEditable={false}
+      spellCheck={false}
+      data-composer-citation-chip="true"
+    >
+      <AssistantCitationChip
+        citation={citation}
+        composer
+        commentEditor={{
+          open: commentTarget !== null,
+          sourceAnchor: commentTarget?.sourceAnchor,
+          onOpenChange: (open) => {
+            if (open && !editor.isEditable) return;
+            commentContext.onOpenChange(citeKey, open);
+          },
+          ...(commentTarget?.removeOnCancel ? { onCancel: onRemove } : {}),
+          onSave: onSaveComment,
+          onSaveAndSend: (comment) => {
+            if (!onSaveComment(comment)) return false;
+            commentContext.onSubmitAndSend();
+            return true;
+          },
+        }}
+      />
+    </NodeViewWrapper>
+  );
+}
+
+const ComposerContextReferenceExtension = Node.create({
+  name: "composer-context-reference",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      kind: { default: "" },
+      contextId: { default: "" },
+      label: { default: "" },
+      source: { default: "" },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-context-reference]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-context-reference": "", ...HTMLAttributes }, 0];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerContextReferenceNodeView);
+  },
+});
+
+function ComposerContextReferenceNodeView({ node }: NodeViewProps) {
+  return (
+    <NodeViewWrapper as="span" className={COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME}>
+      <ComposerContextReferenceChip
+        kind={(node.attrs.kind as string) ?? ""}
+        contextId={(node.attrs.contextId as string) ?? ""}
+        label={(node.attrs.label as string) ?? ""}
+      />
+    </NodeViewWrapper>
+  );
+}
+
+// ── Marker reveal (show ** when the cursor is on styled text) ──────────────
+
+type StyledRange = {
+  from: number;
+  to: number;
+  delimiter: string;
+};
+
+function collectStyledRanges(doc: ProseMirrorNode): StyledRange[] {
+  const ranges: StyledRange[] = [];
+  doc.descendants((node, pos) => {
+    if (!node.isText || !node.text) return true;
+    const marks = (node.marks ?? [])
+      .map((mark) => TIPTAP_TO_MARK[mark.type.name])
+      .filter((mark): mark is RichTextMark => Boolean(mark));
+    if (marks.length === 0) return false;
+    const ordered = [...marks].sort(
+      (a, b) => MARK_NESTING_ORDER.indexOf(a) - MARK_NESTING_ORDER.indexOf(b),
+    );
+    const delimiter = ordered.map((mark) => RICH_TEXT_DELIMITERS[mark]).join("");

@@ -0,0 +1,237 @@
+/**
+ * Inline markdown styling for the rich text composer.
+ *
+ * The composer's stored prompt stays plain markdown (`**bold**`), while the
+ * Tiptap surface renders styled text. These helpers translate between the two:
+ * parsing markdown into marked spans for the document, serializing marked
+ * spans back to markdown, and mapping cursor offsets between document
+ * coordinates (markers excluded) and markdown coordinates (markers included).
+ *
+ * Deliberately small: bold, italic, strikethrough, and inline code only.
+ * Unmatched markers stay literal text so nothing the user typed is ever lost.
+ */
+
+export type RichTextMark = "bold" | "italic" | "strike" | "code";
+
+export interface RichTextSpan {
+  text: string;
+  marks: RichTextMark[];
+}
+
+export interface RichMarkRange {
+  /** Document-text coordinates (markers excluded), end-exclusive. */
+  start: number;
+  end: number;
+  marks: RichTextMark[];
+}
+
+export const RICH_TEXT_DELIMITERS: Record<RichTextMark, string> = {
+  bold: "**",
+  italic: "*",
+  strike: "~~",
+  code: "`",
+};
+
+/** Nesting order, outermost first, used when several marks share a span. */
+const MARK_ORDER: RichTextMark[] = ["strike", "bold", "italic", "code"];
+
+function sortMarks(marks: RichTextMark[]): RichTextMark[] {
+  return [...marks].sort((a, b) => MARK_ORDER.indexOf(a) - MARK_ORDER.indexOf(b));
+}
+
+function pushSpan(spans: RichTextSpan[], text: string, marks: RichTextMark[]): void {
+  if (!text) return;
+  const sorted = sortMarks(marks);
+  const last = spans[spans.length - 1];
+  if (
+    last &&
+    last.marks.length === sorted.length &&
+    last.marks.every((mark, index) => mark === sorted[index])
+  ) {
+    last.text += text;
+    return;
+  }
+  spans.push({ text, marks: sorted });
+}
+
+function matchAt(pattern: RegExp, text: string, index: number): RegExpMatchArray | null {
+  pattern.lastIndex = index;
+  const match = pattern.exec(text);
+  return match && match.index === index ? match : null;
+}
+
+// Code spans are parsed first so `**` inside backticks stays literal.
+const CODE_PATTERN = /`([^`\n]+?)`/gy;
+const BOLD_PATTERN = /(\*\*(?=[^\s*])(.+?)(?<=[^\s*])\*\*|__(?=[^\s_])(.+?)(?<=[^\s_])__)/gy;
+const STRIKE_PATTERN = /~~(?=[^\s~])(.+?)(?<=[^\s~])~~/gy;
+// Single `*` emphasis. Bold is consumed before this runs, so a leftover `*`
+// pair is italic. Underscore emphasis requires non-word boundaries on both
+// sides so snake_case identifiers keep their underscores.
+const ITALIC_STAR_PATTERN = /\*(?=[^\s*])(.+?)(?<=[^\s*])\*/gy;

@@ -0,0 +1,1155 @@
+import { Extension, Node, type JSONContent } from "@tiptap/core";
+import { TaskList } from "@tiptap/extension-task-list";
+import { ReactNodeViewRenderer, NodeViewWrapper, type NodeViewProps } from "@tiptap/react";
+import StarterKit from "@tiptap/starter-kit";
+import { type Node as ProseMirrorNode } from "@tiptap/pm/model";
+import { splitBlockKeepMarks } from "@tiptap/pm/commands";
+import { Plugin, PluginKey, TextSelection } from "@tiptap/pm/state";
+import { Decoration, DecorationSet } from "@tiptap/pm/view";
+import type { AssistantCitation, ServerProviderSkill } from "@t3tools/contracts";
+import {
+  serializeAssistantCitation,
+  withAssistantCitationComment,
+} from "@t3tools/shared/assistantCitations";
+import {
+  COMPOSER_CONTEXT_CLIPBOARD_MIME,
+  encodeComposerContextClipboardHtml,
+} from "@t3tools/shared/composerContextClipboard";
+import {
+  createContext,
+  use,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { EditorContent, useEditor } from "@tiptap/react";
+
+import {
+  clampCollapsedComposerCursor,
+  collapseExpandedComposerCursor,
+  expandCollapsedComposerCursor,
+  isCollapsedCursorAdjacentToInlineToken,
+} from "~/composer-logic";
+import { selectionTouchesMentionBoundary } from "~/composer-editor-mentions";
+import { RICH_TEXT_DELIMITERS, type RichTextMark } from "~/composer-rich-text";
+import {
+  buildDocJson,
+  buildTiptapContent,
+  collapsedToFlat,
+  ComposerTaskItemExtension,
+  flatToCollapsed,
+  flatToMarkdown,
+  flatToPm,
+  MARK_NESTING_ORDER,
+  pmToFlat,
+  serializeEditorDoc,
+  TIPTAP_TO_MARK,
+  type SkillMeta,
+} from "~/composer-rich-text-doc";
+import { collectInlineContextIds } from "~/lib/composerContextReferences";
+import { cn } from "~/lib/utils";
+import { basenameOfPath } from "~/pierre-icons";
+import {
+  COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME,
+  COMPOSER_INLINE_CHIP_ICON_CLASS_NAME,
+  COMPOSER_INLINE_CHIP_LABEL_CLASS_NAME,
+  COMPOSER_INLINE_SKILL_CHIP_CLASS_NAME,
+  SKILL_CHIP_ICON_SVG,
+} from "./composerInlineChip";
+import { FILE_TAG_CHIP_CLASS_NAME, FileTagChipContent } from "./chat/FileTagChip";
+import { AssistantCitationChip } from "./chat/AssistantCitationChip";
+import { getTimelinePageScrollKey } from "./chat/pageScrollController";
+import { ContextChipPopover } from "./contextChipParts";
+import { Button } from "./ui/button";
+import {
+  ComposerContextActionsContext,
+  ComposerContextReferenceChip,
+  ComposerContextRecordsContext,
+} from "./composerContextPresentation";
+import {
+  ComposerCitationCommentContext,
+  type ComposerCitationCommentTarget,
+} from "./ComposerCitationNode";
+import type { AssistantCitationSourceAnchor } from "~/lib/assistantTextSelection";
+import { formatProviderSkillDisplayName } from "@t3tools/client-runtime/providerSkills";
+import { Tooltip, TooltipPopup, TooltipTrigger } from "./ui/tooltip";
+import { importPastedComposerText } from "./composerInlineTokenPaste";
+import { didComposerSelectionChangeVisibly } from "./composerSelection";
+import type {
+  ComposerPromptEditorHandle,
+  ComposerPromptEditorProps as LexicalComposerPromptEditorProps,
+} from "./ComposerPromptEditor";
+
+export type ComposerPromptEditorProps = LexicalComposerPromptEditorProps;
+
+type ComposerCitationCommentRequest = {
+  previousValue: string;
+  value: string;
+  citationStart: number;
+  sourceAnchor: AssistantCitationSourceAnchor;
+};
+
+type OpenCitationComment = {
+  key: string;
+  sourceAnchor?: AssistantCitationSourceAnchor;
+  removeOnCancel?: boolean;
+};
+
+const RichComposerSkillsContext = createContext<ReadonlyArray<ServerProviderSkill>>([]);
+
+const SURROUND_CLOSE: Record<string, string> = {
+  "(": ")",
+  "[": "]",
+  "{": "}",
+  "'": "'",
+  '"': '"',
+  "“": "”",
+  "`": "`",
+  "<": ">",
+  "«": "»",
+  "*": "*",
+  _: "_",
+};
+
+function resolvedThemeFromDocument(): "light" | "dark" {
+  return document.documentElement.classList.contains("dark") ? "dark" : "light";
+}
+
+// ── Inline atom nodes (chips) ─────────────────────────────────────────────
+
+const ComposerMentionExtension = Node.create({
+  name: "composer-mention",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      path: { default: "" },
+      source: { default: "" },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-mention]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-mention": "", ...HTMLAttributes }, 0];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerMentionNodeView);
+  },
+});
+
+function ComposerMentionNodeView({ node }: NodeViewProps) {
+  const actions = use(ComposerContextActionsContext);
+  const path = (node.attrs.path as string) ?? "";
+  const chip = (
+    <button
+      type="button"
+      onClick={() => actions.openMention(path)}
+      aria-label={`Preview ${path}`}
+      className={`${FILE_TAG_CHIP_CLASS_NAME} cursor-pointer focus-visible:outline-2`}
+      contentEditable={false}
+      spellCheck={false}
+      data-composer-mention-chip="true"
+    >
+      <FileTagChipContent
+        path={path}
+        label={basenameOfPath(path)}
+        theme={resolvedThemeFromDocument()}
+      />
+    </button>
+  );
+  return (
+    <NodeViewWrapper as="span" className={COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME}>
+      <Tooltip>
+        <TooltipTrigger render={chip} />
+        <TooltipPopup
+          side="top"
+          className="max-w-120 whitespace-normal leading-tight wrap-anywhere"
+        >
+          {path}
+        </TooltipPopup>
+      </Tooltip>
+    </NodeViewWrapper>
+  );
+}
+
+const ComposerSkillExtension = Node.create({
+  name: "composer-skill",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      skillName: { default: "" },
+      skillLabel: { default: "" },
+      skillDescription: { default: null },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-skill]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-skill": "", ...HTMLAttributes }, 0];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerSkillNodeView);
+  },
+});
+
+function ComposerSkillNodeView({ node }: NodeViewProps) {
+  const actions = use(ComposerContextActionsContext);
+  const skills = use(RichComposerSkillsContext);
+  const skillName = (node.attrs.skillName as string) ?? "";
+  const skillLabel = (node.attrs.skillLabel as string) || skillName;
+  const skillDescription = (node.attrs.skillDescription as string | null) ?? null;
+  const skill = skills.find((candidate) => candidate.name === skillName);
+  return (
+    <NodeViewWrapper as="span" className={COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME}>
+      <ContextChipPopover
+        accessibleLabel={`Skill ${skillLabel}`}
+        triggerClassName={COMPOSER_INLINE_SKILL_CHIP_CLASS_NAME}
+        chip={
+          <>
+            <span
+              aria-hidden="true"
+              className={COMPOSER_INLINE_CHIP_ICON_CLASS_NAME}
+              dangerouslySetInnerHTML={{ __html: SKILL_CHIP_ICON_SVG }}
+            />
+            <span className={COMPOSER_INLINE_CHIP_LABEL_CLASS_NAME}>{skillLabel}</span>
+          </>
+        }
+      >
+        <div className="space-y-3 p-2 text-sm">
+          <p className="font-medium">{skillLabel}</p>
+          <p>
+            {skill?.description ??
+              skillDescription ??
+              "No description is available for this skill."}
+          </p>
+          {skill?.path ? (
+            <Button variant="outline" size="sm" onClick={() => actions.openMention(skill.path)}>
+              View instructions
+            </Button>
+          ) : null}
+        </div>
+      </ContextChipPopover>
+    </NodeViewWrapper>
+  );
+}
+
+const ComposerCitationExtension = Node.create({
+  name: "composer-citation",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      citation: { default: null },
+      source: { default: "" },
+      citeKey: { default: "" },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-citation]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-citation": "", ...HTMLAttributes }, 0];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerCitationNodeView);
+  },
+});
+
+function ComposerCitationNodeView({ node, editor, getPos }: NodeViewProps) {
+  const commentContext = use(ComposerCitationCommentContext);
+  const citation = node.attrs.citation as AssistantCitation;
+  const citeKey = node.attrs.citeKey as string;
+  const commentTarget =
+    commentContext.openComment !== null &&
+    typeof commentContext.openComment === "object" &&
+    "key" in (commentContext.openComment as Record<string, unknown>) &&
+    (commentContext.openComment as unknown as OpenCitationComment).key === citeKey
+      ? (commentContext.openComment as unknown as OpenCitationComment)
+      : null;
+
+  const nodePos = useCallback(() => {
+    const pos = typeof getPos === "function" ? getPos() : null;
+    return typeof pos === "number" ? pos : null;
+  }, [getPos]);
+
+  const onSaveComment = useCallback(
+    (comment: string): boolean => {
+      if (!editor.isEditable) return false;
+      const pos = nodePos();
+      if (pos === null) return false;
+      const current = editor.state.doc.nodeAt(pos);
+      if (!current || current.type.name !== "composer-citation") return false;
+      const currentCitation = current.attrs.citation as AssistantCitation;
+      const next = withAssistantCitationComment(currentCitation, comment);
+      const tr = editor.state.tr.setNodeMarkup(pos, undefined, {
+        ...current.attrs,
+        citation: next,
+        source: serializeAssistantCitation(next),
+      });
+      editor.view.dispatch(tr);
+      return true;
+    },
+    [editor, nodePos],
+  );
+
+  const onRemove = useCallback(() => {
+    if (!editor.isEditable) return;
+    const pos = nodePos();
+    if (pos === null) return;
+    const current = editor.state.doc.nodeAt(pos);
+    if (!current) return;
+    editor
+      .chain()
+      .focus()
+      .deleteRange({ from: pos, to: pos + current.nodeSize })
+      .run();
+  }, [editor, nodePos]);
+
+  return (
+    <NodeViewWrapper
+      as="span"
+      className="inline-flex min-w-0 max-w-full"
+      contentEditable={false}
+      spellCheck={false}
+      data-composer-citation-chip="true"
+    >
+      <AssistantCitationChip
+        citation={citation}
+        composer
+        commentEditor={{
+          open: commentTarget !== null,
+          sourceAnchor: commentTarget?.sourceAnchor,
+          onOpenChange: (open) => {
+            if (open && !editor.isEditable) return;
+            commentContext.onOpenChange(citeKey, open);
+          },
+          ...(commentTarget?.removeOnCancel ? { onCancel: onRemove } : {}),
+          onSave: onSaveComment,
+          onSaveAndSend: (comment) => {
+            if (!onSaveComment(comment)) return false;
+            commentContext.onSubmitAndSend();
+            return true;
+          },
+        }}
+      />
+    </NodeViewWrapper>
+  );
+}
+
+const ComposerContextReferenceExtension = Node.create({
+  name: "composer-context-reference",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      kind: { default: "" },
+      contextId: { default: "" },
+      label: { default: "" },
+      source: { default: "" },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-context-reference]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-context-reference": "", ...HTMLAttributes }, 0];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerContextReferenceNodeView);
+  },
+});
+
+function ComposerContextReferenceNodeView({ node }: NodeViewProps) {
+  return (
+    <NodeViewWrapper as="span" className={COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME}>
+      <ComposerContextReferenceChip
+        kind={(node.attrs.kind as string) ?? ""}
+        contextId={(node.attrs.contextId as string) ?? ""}
+        label={(node.attrs.label as string) ?? ""}
+      />
+    </NodeViewWrapper>
+  );
+}
+
+// ── Marker reveal (show ** when the cursor is on styled text) ──────────────
+
+type StyledRange = {
+  from: number;
+  to: number;
+  delimiter: string;
+};
+
+function collectStyledRanges(doc: ProseMirrorNode): StyledRange[] {
+  const ranges: StyledRange[] = [];
+  doc.descendants((node, pos) => {
+    if (!node.isText || !node.text) return true;
+    const marks = (node.marks ?? [])
+      .map((mark) => TIPTAP_TO_MARK[mark.type.name])
+      .filter((mark): mark is RichTextMark => Boolean(mark));
+    if (marks.length === 0) return false;
+    const ordered = [...marks].sort(
+      (a, b) => MARK_NESTING_ORDER.indexOf(a) - MARK_NESTING_ORDER.indexOf(b),
+    );
+    const delimiter = ordered.map((mark) => RICH_TEXT_DELIMITERS[mark]).join("");
+    const last = ranges[ranges.length - 1];
+    if (last && last.to === pos && last.delimiter === delimiter) {
+      last.to = pos + (node.text?.length ?? 0);
+    } else {
+      ranges.push({ from: pos, to: pos + (node.text?.length ?? 0), delimiter });
+    }
+    return false;
+  });
+  return ranges;
+}
+
+const MarkerPluginKey = new PluginKey("composer-rich-markers");
+
+const ComposerMarkerPlugin = new Plugin({
+  key: MarkerPluginKey,
+  state: {
+    init: (_, state) => decorationsForSelection(state.doc, state.selection),
+    apply: (tr, old) =>
+      tr.docChanged || tr.selectionSet ? decorationsForSelection(tr.doc, tr.selection) : old,
+  },
+  props: {
+    decorations(state) {
+      return MarkerPluginKey.getState(state);
+    },
+  },
+});
+
+function decorationsForSelection(
+  doc: ProseMirrorNode,
+  selection: { from: number; to: number; empty: boolean },
+): DecorationSet {
+  const decorations: Decoration[] = [];
+  for (const range of collectStyledRanges(doc)) {
+    const active = selection.empty
+      ? selection.from >= range.from && selection.from <= range.to
+      : selection.from < range.to && selection.to > range.from;
+    if (!active) continue;
+    for (const [at, side] of [
+      [range.from, -1],
+      [range.to, 1],
+    ] as const) {
+      const marker = document.createElement("span");
+      marker.className = "composer-rich-marker";
+      marker.textContent = range.delimiter;
+      marker.setAttribute("aria-hidden", "true");
+      decorations.push(Decoration.widget(at, marker, { side, key: `marker-${at}-${side}` }));
+    }
+  }
+  return DecorationSet.create(doc, decorations);
+}
+
+const ComposerMarkersExtension = Extension.create({
+  name: "composer-rich-markers",
+  addProseMirrorPlugins() {
+    return [ComposerMarkerPlugin];
+  },
+});
+
+// Document model (markdown ⇄ ProseMirror) lives in ~/composer-rich-text-doc so
+// unit tests can round-trip it without a browser.
+// ── Editor component ───────────────────────────────────────────────────────
+
+type TiptapEditor = NonNullable<ReturnType<typeof useEditor>>;
+
+export function ComposerPromptEditorTiptap(props: ComposerPromptEditorProps) {
+  const {
+    value,
+    cursor,
+    contextRecords,
+    buildContextClipboardFragment,
+    importContextFragment,
+    skills,
+    disabled,
+    placeholder,
+    containerClassName,
+    className,
+    placeholderClassName,
+    onChange,
+    onVisibleSelectionChange,
+    onCommandKeyDown,
+    onPageScrollKeyDown,
+    onPageScrollKeyUp,
+    onPageScrollRelease,
+    onCitationSubmitAndSend,
+    onPaste,
+    editorRef,
+  } = props;
+
+  const onChangeRef = useRef(onChange);
+  const onVisibleSelectionChangeRef = useRef(onVisibleSelectionChange);
+  const onCommandKeyDownRef = useRef(onCommandKeyDown);
+  const buildFragmentRef = useRef(buildContextClipboardFragment);
+  const importFragmentRef = useRef(importContextFragment);
+  const skillsRef = useRef(skills);
+  const latestValueRef = useRef(value);
+  // The editor instance for callbacks created before it exists (paste).
+  // Effects flush before any user interaction, so this is always set.
+  const editorHolder = useRef<TiptapEditor | null>(null);
+
+  useEffect(() => {
+    onChangeRef.current = onChange;
+  }, [onChange]);
+  useEffect(() => {
+    onVisibleSelectionChangeRef.current = onVisibleSelectionChange;
+  }, [onVisibleSelectionChange]);
+  useEffect(() => {
+    onCommandKeyDownRef.current = onCommandKeyDown;
+  }, [onCommandKeyDown]);
+  useEffect(() => {
+    buildFragmentRef.current = buildContextClipboardFragment;
+  }, [buildContextClipboardFragment]);
+  useEffect(() => {
+    importFragmentRef.current = importContextFragment;
+  }, [importContextFragment]);
+  useEffect(() => {
+    skillsRef.current = skills;
+  }, [skills]);
+  useLayoutEffect(() => {
+    latestValueRef.current = value;
+  }, [value]);
+
+  const skillLabelFor = useCallback((name: string): SkillMeta => {
+    const normalized = name.startsWith("$") ? name.slice(1) : name;
+    const skill = skillsRef.current.find((candidate) => candidate.name === normalized);
+    if (!skill) {
+      return { label: formatProviderSkillDisplayName({ name: normalized }), description: null };
+    }
+    const shortDescription = skill.shortDescription?.trim();
+    return {
+      label: formatProviderSkillDisplayName(skill),
+      description: shortDescription || skill.description?.trim() || null,
+    };
+  }, []);
+
+  const initialCursor = clampCollapsedComposerCursor(value, cursor);
+  const initialExpandedCursor = expandCollapsedComposerCursor(value, initialCursor);
+  const snapshotRef = useRef({
+    value,
+    cursor: initialCursor,
+    expandedCursor: initialExpandedCursor,
+    contextIds: collectInlineContextIds(value),
+  });
+  const selectionRangeRef = useRef({ start: initialExpandedCursor, end: initialExpandedCursor });
+  const isApplyingControlledUpdateRef = useRef(false);
+  const citationRequestRef = useRef<ComposerCitationCommentRequest | null>(null);
+  const [openCitation, setOpenCitation] = useState<OpenCitationComment | null>(null);
+  const [isEmpty, setIsEmpty] = useState(value.length === 0);
+
+  const citationCommentActions = useMemo(
+    () => ({
+      openComment: (openCitation ?? null) as unknown as ComposerCitationCommentTarget | null,
+      onOpenChange: (nodeKey: string, open: boolean) => {
+        setOpenCitation((current) => {
+          if (open) {
+            if (current?.key === nodeKey) return current;
+            return { key: nodeKey };
+          }
+          return current?.key === nodeKey ? null : current;
+        });
+      },
+      onSubmitAndSend: onCitationSubmitAndSend ?? (() => {}),
+    }),
+    [onCitationSubmitAndSend, openCitation],
+  );
+
+  const handleEditorChange = useCallback((updated: TiptapEditor) => {
+    const map = serializeEditorDoc(updated.state.doc);
+    const { from, to } = updated.state.selection;
+    const fromFlat = pmToFlat(map, from);
+    const toFlat = pmToFlat(map, to);
+    const nextValue = map.value;
+    const nextCursor = clampCollapsedComposerCursor(map.value, flatToCollapsed(map, fromFlat));
+    const nextExpandedCursor = Math.max(
+      0,
+      Math.min(map.value.length, flatToMarkdown(map, fromFlat)),
+    );
+    const nextSelectionRange = {
+      start: Math.min(nextExpandedCursor, flatToMarkdown(map, toFlat)),
+      end: Math.max(nextExpandedCursor, flatToMarkdown(map, toFlat)),
+    };
+    const previousSelectionRange = selectionRangeRef.current;
+    selectionRangeRef.current = nextSelectionRange;
+    setIsEmpty(nextValue.length === 0);
+    const previousSnapshot = snapshotRef.current;
+    const snapshotChanged = !(
+      previousSnapshot.value === nextValue &&
+      previousSnapshot.cursor === nextCursor &&
+      previousSnapshot.expandedCursor === nextExpandedCursor &&
+      previousSnapshot.contextIds.length === map.contextIds.length &&
+      previousSnapshot.contextIds.every((id, index) => id === map.contextIds[index])
+    );
+    if (isApplyingControlledUpdateRef.current) return;
+    if (!snapshotChanged) {
+      if (didComposerSelectionChangeVisibly(previousSelectionRange, nextSelectionRange)) {
+        onVisibleSelectionChangeRef.current?.();
+      }
+      return;
+    }
+    // A selection-only update while a newer prompt waits to be applied (a chip
+    // was just inserted through the store) would report stale text and clobber
+    // the prompt. Let the controlled rewrite land instead.
+    if (previousSnapshot.value === nextValue && nextValue !== latestValueRef.current) {
+      return;
+    }
+    snapshotRef.current = {
+      value: nextValue,
+      cursor: nextCursor,
+      expandedCursor: nextExpandedCursor,
+      contextIds: map.contextIds,
+    };
+    const cursorAdjacentToMention =
+      isCollapsedCursorAdjacentToInlineToken(nextValue, nextCursor, "left") ||
+      isCollapsedCursorAdjacentToInlineToken(nextValue, nextCursor, "right");
+    onChangeRef.current(
+      nextValue,
+      nextCursor,
+      nextExpandedCursor,
+      cursorAdjacentToMention,
+      map.contextIds,
+    );
+  }, []);
+
+  const editor = useEditor(
+    {
+      extensions: [
+        StarterKit.configure({
+          blockquote: false,
+          bulletList: false,
+          codeBlock: false,
+          heading: false,
+          horizontalRule: false,
+          listItem: false,
+          orderedList: false,
+          dropcursor: false,
+          gapcursor: false,
+          trailingNode: false,
+        }),
+        ComposerMentionExtension,
+        ComposerSkillExtension,
+        ComposerCitationExtension,
+        ComposerContextReferenceExtension,
+        TaskList,
+        ComposerTaskItemExtension,
+        ComposerMarkersExtension,
+      ],
+      content: buildDocJson(value, (name) => {
+        const normalized = name.startsWith("$") ? name.slice(1) : name;
+        const found = skills.find((candidate) => candidate.name === normalized);
+        if (!found) {
+          return { label: formatProviderSkillDisplayName({ name: normalized }), description: null };
+        }
+        const shortDescription = found.shortDescription?.trim();
+        return {
+          label: formatProviderSkillDisplayName(found),
+          description: shortDescription || found.description?.trim() || null,
+        };
+      }),
+      editable: !disabled,
+      editorProps: {
+        attributes: {
+          class: cn(
+            "composer-tiptap block max-h-50 min-h-17.5 w-full overflow-y-auto whitespace-pre-wrap wrap-break-word bg-transparent leading-relaxed text-foreground focus:outline-none",
+            className,
+          ),
+          "data-testid": "composer-editor",
+          "aria-placeholder": placeholder,
+        },
+        handleKeyDown: (view, event) => {
+          if (event.key === "Enter" && (event.isComposing || event.keyCode === 229)) {
+            event.stopPropagation();
+            return true;
+          }
+          // Enter on a focused task checkbox must not send the prompt (or
+          // split anything): Space toggles it, Enter does nothing.
+          if (event.key === "Enter" && event.target instanceof HTMLInputElement) {
+            event.preventDefault();
+            return true;
+          }
+          const handler = onCommandKeyDownRef.current;
+          if (event.key === "Enter") {
+            const handled = handler?.("Enter", event) ?? false;
+            if (handled) {
+              event.preventDefault();
+              event.stopPropagation();
+              return true;
+            }
+            // A newline the parent declined (Shift+Enter, or Enter while the
+            // shortcut says otherwise) must be one visible line. Letting it
+            // fall through inserts a native trailing `<br>`, which renders
+            // no visible line, so the caret looks stuck until a second press.
+            // Splitting the paragraph matches the Lexical surface: one press,
+            // one line. Enter on a list line never gets here — the parent
+            // claims it for continuation — so Tiptap's list splitting stays
+            // shadowed and both surfaces serialize identically.
+            event.preventDefault();
+            return splitBlockKeepMarks(view.state, (tr) => {
+              // The split is programmatic, so the browser won't follow the
+              // caret into view on its own.
+              view.dispatch(tr.scrollIntoView());
+            });
+          }
+          if (!handler) return false;
+          const key =
+            event.key === "Tab"
+              ? ("Tab" as const)
+              : event.key === "ArrowDown"
+                ? ("ArrowDown" as const)
+                : event.key === "ArrowUp"
+                  ? ("ArrowUp" as const)
+                  : null;
+          if (!key) return false;
+          const handled = handler(key, event);
+          if (handled) {
+            event.preventDefault();
+            event.stopPropagation();
+          }
+          return handled;
+        },
+        handleTextInput: (view, from, to, text) => {
+          const closer = SURROUND_CLOSE[text];
+          if (!closer || from === to) return false;
+          // Never wrap chips or other atoms, and never wrap styled text: the
+          // default replace keeps marks intact, wrapping would drop them.
+          let touchesSpecial = false;
+          view.state.doc.nodesBetween(from, to, (node) => {
+            if ((node.isAtom && node.isInline) || (node.isText && node.marks.length > 0)) {
+              touchesSpecial = true;
+              return false;
+            }
+            return true;
+          });
+          if (touchesSpecial) return false;
+          const map = serializeEditorDoc(view.state.doc);
+          const startMd = flatToMarkdown(map, pmToFlat(map, from));
+          const endMd = flatToMarkdown(map, pmToFlat(map, to));
+          if (selectionTouchesMentionBoundary(map.value, startMd, endMd)) return false;
+          const tr = view.state.tr.insertText(closer, to).insertText(text, from);
+          tr.setSelection(TextSelection.create(tr.doc, from + text.length, to + text.length));
+          view.dispatch(tr);
+          return true;
+        },
+        handlePaste: (view, event) => {
+          const clipboardData = event.clipboardData;
+          if (!clipboardData || clipboardData.files.length > 0) return false;
+          const pastedText = clipboardData.getData("text/plain");
+          if (!pastedText) return false;
+          event.preventDefault();
+          const importFragment = importFragmentRef.current;
+          const text = importFragment
+            ? importPastedComposerText(clipboardData, importFragment)
+            : pastedText;
+          const editorInstance = editorHolder.current;
+          if (editorInstance) {
+            insertMarkdownParagraphs(text, skillLabelFor, (content) => {

@@ -2120,3 +2120,89 @@ code {
     visibility: visible;
   }
 }
+
+/* Rich text composer (Tiptap). The stored prompt stays markdown; only the
+   surface renders styled text. Markers (** * ` ~~) appear as non-editable
+   widgets while the caret is on styled text. */
+.composer-tiptap {
+  position: relative;
+}
+
+.composer-tiptap p {
+  margin: 0;
+}
+
+.composer-tiptap:focus,
+.composer-tiptap .ProseMirror:focus {
+  outline: none;
+}
+
+.composer-tiptap code {
+  font-family: var(--font-mono);
+  font-size: 0.92em;
+  background: color-mix(in oklab, var(--muted-foreground) 12%, transparent);
+  border-radius: 0.3em;
+  padding: 0.05em 0.25em;
+}
+
+.composer-rich-marker {
+  color: var(--muted-foreground);
+  opacity: 0.75;
+  font-weight: 400;
+  font-style: normal;
+  text-decoration: none;
+  user-select: none;
+  pointer-events: none;
+}
+
+/* Selected chips (node selection from arrowing into or clicking a chip). */
+.composer-tiptap .ProseMirror-selectednode {
+  outline: 2px solid var(--ring);
+  outline-offset: 1px;
+  border-radius: 6px;
+}
+
+/* Rich-text task lists render as real checkboxes. Tiptap's TaskItem NodeView
+   builds the <li> imperatively with only a data-checked attribute (no
+   data-type), so items are targeted that way. Indentation comes from list
+   nesting (two spaces per level from Tab), matching the stored Markdown. */
+.composer-tiptap ul[data-type="taskList"] {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.composer-tiptap ul[data-type="taskList"] ul[data-type="taskList"] {
+  padding-left: 1.375rem;
+}
+
+.composer-tiptap li[data-checked] {
+  display: flex;
+  align-items: center;

@@ -0,0 +1,1379 @@
+import { Extension, Node, wrappingInputRule, type JSONContent } from "@tiptap/core";
+import { TaskList } from "@tiptap/extension-task-list";
+import { ReactNodeViewRenderer, NodeViewWrapper, type NodeViewProps } from "@tiptap/react";
+import StarterKit from "@tiptap/starter-kit";
+import { type Node as ProseMirrorNode } from "@tiptap/pm/model";
+import { splitBlockKeepMarks } from "@tiptap/pm/commands";
+import { Plugin, PluginKey, TextSelection } from "@tiptap/pm/state";
+import { Decoration, DecorationSet } from "@tiptap/pm/view";
+import type {
+  AssistantCitation,
+  ComposerContextClipboardFragment,
+  ServerProviderSkill,
+} from "@t3tools/contracts";
+import {
+  serializeAssistantCitation,
+  withAssistantCitationComment,
+} from "@t3tools/shared/assistantCitations";
+import {
+  COMPOSER_CONTEXT_CLIPBOARD_MIME,
+  encodeComposerContextClipboardHtml,
+} from "@t3tools/shared/composerContextClipboard";
+import {
+  createContext,
+  use,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { EditorContent, useEditor } from "@tiptap/react";
+
+import {
+  clampCollapsedComposerCursor,
+  collapseExpandedComposerCursor,
+  expandCollapsedComposerCursor,
+  isCollapsedCursorAdjacentToInlineToken,
+} from "~/composer-logic";
+import {
+  collectComposerPromptInlineTokens,
+  selectionTouchesMentionBoundary,
+} from "~/composer-editor-mentions";
+import {
+  buildDocJson,
+  buildTiptapContent,
+  collapsedToFlat,
+  ComposerTaskItemExtension,
+  flatToCollapsed,
+  flatToMarkdown,
+  flatToPm,
+  pmToFlat,
+  serializeEditorDoc,
+  type SkillMeta,
+} from "~/composer-rich-text-doc";
+import { collectInlineContextIds } from "~/lib/composerContextReferences";
+import { cn, isMacPlatform } from "~/lib/utils";
+import { basenameOfPath } from "~/pierre-icons";
+import {
+  COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME,
+  COMPOSER_INLINE_CHIP_ICON_CLASS_NAME,
+  COMPOSER_INLINE_CHIP_LABEL_CLASS_NAME,
+  COMPOSER_INLINE_SKILL_CHIP_CLASS_NAME,
+  SKILL_CHIP_ICON_SVG,
+} from "./composerInlineChip";
+import { FILE_TAG_CHIP_CLASS_NAME, FileTagChipContent } from "./chat/FileTagChip";
+import { AssistantCitationChip } from "./chat/AssistantCitationChip";
+import { getTimelinePageScrollKey } from "./chat/pageScrollController";
+import { ContextChipPopover } from "./contextChipParts";
+import { Button } from "./ui/button";
+import {
+  ComposerContextActionsContext,
+  ComposerContextReferenceChip,
+  ComposerContextRecordsContext,
+} from "./composerContextPresentation";
+import type { AssistantCitationSourceAnchor } from "~/lib/assistantTextSelection";
+import { formatProviderSkillDisplayName } from "@t3tools/client-runtime/providerSkills";
+import { Tooltip, TooltipPopup, TooltipTrigger } from "./ui/tooltip";
+import { importPastedComposerText } from "./composerInlineTokenPaste";
+import { didComposerSelectionChangeVisibly } from "./composerSelection";
+import type { ComposerDraftContextRecords } from "./composerContextPresentation";
+
+export interface ComposerPromptEditorHandle {
+  focus: () => void;
+  focusAt: (cursor: number) => void;
+  focusAtEnd: () => void;
+  readSelectionRange: () => { start: number; end: number };
+  requestCitationComment: (request: ComposerCitationCommentRequest) => void;
+  readSnapshot: () => {
+    value: string;
+    cursor: number;
+    expandedCursor: number;
+    contextIds: string[];
+  };
+  /**
+   * True when a collapsed caret sits on the first ("start") or last ("end")
+   * visual line, counting soft wraps. Prompt history only claims ArrowUp and
+   * ArrowDown at these edges so arrows still move the caret inside multiline
+   * text.
+   */
+  isCaretOnVisualEdge: (edge: "start" | "end") => boolean;
+}
+
+export interface ComposerPromptEditorProps {
+  value: string;
+  cursor: number;
+  /**
+   * Render Markdown styling (bold, italic, code, strike, task checkboxes).
+   * Off renders the same Tiptap engine as plain text: every marker stays a
+   * literal character.
+   */
+  richTextEnabled?: boolean;
+  /** Draft records behind the prompt's context references, keyed by context id. */
+  contextRecords: ComposerDraftContextRecords;
+  /** Structured clipboard payload for the given referenced ids, or null to skip. */
+  buildContextClipboardFragment?:
+    | ((contextIds: ReadonlyArray<string>) => string | null)
+    | undefined;
+  /** Imports a structured paste's records; returns ids that changed. */
+  importContextFragment?:
+    | ((fragment: ComposerContextClipboardFragment) => ReadonlyMap<string, string>)
+    | undefined;
+  skills: ReadonlyArray<ServerProviderSkill>;
+  disabled: boolean;
+  placeholder: string;
+  containerClassName?: string;
+  className?: string;
+  placeholderClassName?: string;
+  onChange: (
+    nextValue: string,
+    nextCursor: number,
+    expandedCursor: number,
+    cursorAdjacentToMention: boolean,
+    contextIds: string[],
+  ) => void;
+  onVisibleSelectionChange?: () => void;
+  onCommandKeyDown?: (
+    key: "ArrowDown" | "ArrowUp" | "Enter" | "Tab",
+    event: KeyboardEvent,
+    isTaskItem?: boolean,
+  ) => boolean;
+  onPageScrollKeyDown?: (key: "PageUp" | "PageDown") => void;
+  onPageScrollKeyUp?: (key: string) => void;
+  onPageScrollRelease?: () => void;
+  onCitationSubmitAndSend?: () => void;
+  onPaste: React.ClipboardEventHandler<HTMLElement>;
+  editorRef: React.RefObject<ComposerPromptEditorHandle | null>;
+}
+
+export type ComposerCitationCommentRequest = {
+  previousValue: string;
+  value: string;
+  citationStart: number;
+  sourceAnchor: AssistantCitationSourceAnchor;
+};
+
+type OpenCitationComment = {
+  key: string;
+  sourceAnchor?: AssistantCitationSourceAnchor;
+  removeOnCancel?: boolean;
+};
+
+const ComposerCitationCommentContext = createContext<{
+  openComment: OpenCitationComment | null;
+  onOpenChange: (citeKey: string, open: boolean) => void;
+  onSubmitAndSend: () => void;
+}>({ openComment: null, onOpenChange: () => {}, onSubmitAndSend: () => {} });
+
+const RichComposerSkillsContext = createContext<ReadonlyArray<ServerProviderSkill>>([]);
+
+const SURROUND_CLOSE: Record<string, string> = {
+  "(": ")",
+  "[": "]",
+  "{": "}",
+  "'": "'",
+  '"': '"',
+  "“": "”",
+  "`": "`",
+  "<": ">",
+  "«": "»",
+  "*": "*",
+  _: "_",
+};
+
+function resolvedThemeFromDocument(): "light" | "dark" {
+  return document.documentElement.classList.contains("dark") ? "dark" : "light";
+}
+
+// ── Inline atom nodes (chips) ─────────────────────────────────────────────
+
+const ComposerMentionExtension = Node.create({
+  name: "composer-mention",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      path: { default: "" },
+      source: { default: "" },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-mention]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-mention": "", ...HTMLAttributes }];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerMentionNodeView);
+  },
+});
+
+function ComposerMentionNodeView({ node }: NodeViewProps) {
+  const actions = use(ComposerContextActionsContext);
+  const path = (node.attrs.path as string) ?? "";
+  const chip = (
+    <button
+      type="button"
+      onClick={() => actions.openMention(path)}
+      aria-label={`Preview ${path}`}
+      className={`${FILE_TAG_CHIP_CLASS_NAME} cursor-pointer focus-visible:outline-2`}
+      contentEditable={false}
+      spellCheck={false}
+      data-composer-mention-chip="true"
+    >
+      <FileTagChipContent
+        path={path}
+        label={basenameOfPath(path)}
+        theme={resolvedThemeFromDocument()}
+      />
+    </button>
+  );
+  return (
+    <NodeViewWrapper as="span" className={COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME}>
+      <Tooltip>
+        <TooltipTrigger render={chip} />
+        <TooltipPopup
+          side="top"
+          className="max-w-120 whitespace-normal leading-tight wrap-anywhere"
+        >
+          {path}
+        </TooltipPopup>
+      </Tooltip>
+    </NodeViewWrapper>
+  );
+}
+
+const ComposerSkillExtension = Node.create({
+  name: "composer-skill",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      skillName: { default: "" },
+      skillLabel: { default: "" },
+      skillDescription: { default: null },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-skill]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-skill": "", ...HTMLAttributes }];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerSkillNodeView);
+  },
+});
+
+function ComposerSkillNodeView({ node }: NodeViewProps) {
+  const actions = use(ComposerContextActionsContext);
+  const skills = use(RichComposerSkillsContext);
+  const skillName = (node.attrs.skillName as string) ?? "";
+  const skillLabel = (node.attrs.skillLabel as string) || skillName;
+  const skillDescription = (node.attrs.skillDescription as string | null) ?? null;
+  const skill = skills.find((candidate) => candidate.name === skillName);
+  return (
+    <NodeViewWrapper as="span" className={COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME}>
+      <ContextChipPopover
+        accessibleLabel={`Skill ${skillLabel}`}
+        triggerClassName={COMPOSER_INLINE_SKILL_CHIP_CLASS_NAME}
+        chip={
+          <>
+            <span
+              aria-hidden="true"
+              className={COMPOSER_INLINE_CHIP_ICON_CLASS_NAME}
+              dangerouslySetInnerHTML={{ __html: SKILL_CHIP_ICON_SVG }}
+            />
+            <span className={COMPOSER_INLINE_CHIP_LABEL_CLASS_NAME}>{skillLabel}</span>
+          </>
+        }
+      >
+        <div className="space-y-3 p-2 text-sm">
+          <p className="font-medium">{skillLabel}</p>
+          <p>
+            {skill?.description ??
+              skillDescription ??
+              "No description is available for this skill."}
+          </p>
+          {skill?.path ? (
+            <Button variant="outline" size="sm" onClick={() => actions.openMention(skill.path)}>
+              View instructions
+            </Button>
+          ) : null}
+        </div>
+      </ContextChipPopover>
+    </NodeViewWrapper>
+  );
+}
+
+const ComposerCitationExtension = Node.create({
+  name: "composer-citation",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      citation: { default: null },
+      source: { default: "" },
+      citeKey: { default: "" },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-citation]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-citation": "", ...HTMLAttributes }];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerCitationNodeView);
+  },
+});
+
+function ComposerCitationNodeView({ node, editor, getPos }: NodeViewProps) {
+  const commentContext = use(ComposerCitationCommentContext);
+  const citation = node.attrs.citation as AssistantCitation;
+  const citeKey = node.attrs.citeKey as string;
+  const commentTarget =
+    commentContext.openComment?.key === citeKey ? commentContext.openComment : null;
+
+  const nodePos = useCallback(() => {
+    const pos = typeof getPos === "function" ? getPos() : null;
+    return typeof pos === "number" ? pos : null;
+  }, [getPos]);
+
+  const onSaveComment = useCallback(
+    (comment: string): boolean => {
+      if (!editor.isEditable) return false;
+      const pos = nodePos();
+      if (pos === null) return false;
+      const current = editor.state.doc.nodeAt(pos);
+      if (!current || current.type.name !== "composer-citation") return false;
+      const currentCitation = current.attrs.citation as AssistantCitation;
+      const next = withAssistantCitationComment(currentCitation, comment);
+      const tr = editor.state.tr.setNodeMarkup(pos, undefined, {
+        ...current.attrs,
+        citation: next,
+        source: serializeAssistantCitation(next),
+      });
+      editor.view.dispatch(tr);
+      return true;
+    },
+    [editor, nodePos],
+  );
+
+  const onRemove = useCallback(() => {
+    if (!editor.isEditable) return;
+    const pos = nodePos();
+    if (pos === null) return;
+    const current = editor.state.doc.nodeAt(pos);
+    if (!current) return;
+    editor
+      .chain()
+      .focus()
+      .deleteRange({ from: pos, to: pos + current.nodeSize })
+      .run();
+  }, [editor, nodePos]);
+
+  return (
+    <NodeViewWrapper
+      as="span"
+      className="inline-flex min-w-0 max-w-full"
+      contentEditable={false}
+      spellCheck={false}
+      data-composer-citation-chip="true"
+    >
+      <AssistantCitationChip
+        citation={citation}
+        composer
+        commentEditor={{
+          open: commentTarget !== null,
+          sourceAnchor: commentTarget?.sourceAnchor,
+          onOpenChange: (open) => {
+            if (open && !editor.isEditable) return;
+            commentContext.onOpenChange(citeKey, open);
+          },
+          ...(commentTarget?.removeOnCancel ? { onCancel: onRemove } : {}),
+          onSave: onSaveComment,
+          onSaveAndSend: (comment) => {
+            if (!onSaveComment(comment)) return false;
+            commentContext.onSubmitAndSend();
+            return true;
+          },
+        }}
+      />
+    </NodeViewWrapper>
+  );
+}
+
+const ComposerContextReferenceExtension = Node.create({
+  name: "composer-context-reference",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  addAttributes() {
+    return {
+      kind: { default: "" },
+      contextId: { default: "" },
+      label: { default: "" },
+      source: { default: "" },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-composer-context-reference]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-composer-context-reference": "", ...HTMLAttributes }];
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(ComposerContextReferenceNodeView);
+  },
+});
+
+function ComposerContextReferenceNodeView({ node }: NodeViewProps) {
+  return (
+    <NodeViewWrapper as="span" className={COMPOSER_INLINE_CHIP_DECORATOR_CLASS_NAME}>
+      <ComposerContextReferenceChip
+        kind={(node.attrs.kind as string) ?? ""}
+        contextId={(node.attrs.contextId as string) ?? ""}
+        label={(node.attrs.label as string) ?? ""}
+      />
+    </NodeViewWrapper>
+  );
+}
+
+// ── Marker reveal (show ** when the cursor is on styled text) ──────────────
+
+type StyledRange = {
+  from: number;
+  to: number;
+  markers: { at: number; side: number; text: string }[];
+};
+
+function collectStyledRanges(doc: ProseMirrorNode): StyledRange[] {
+  const ranges: StyledRange[] = [];
+  const map = serializeEditorDoc(doc);
+  let range: StyledRange | null = null;
+  let openLength = 0;
+  for (const run of map.runs) {
+    if (run.openLen > 0) {
+      range ??= { from: run.pmPos, to: run.pmPos, markers: [] };
+      range.markers.push({
+        at: run.pmPos,
+        side: -1,
+        text: map.value.slice(run.mdStart, run.mdStart + run.openLen),
+      });
+    }
+    if (range === null) continue;
+    range.to = run.pmPos + run.docLen;
+    if (run.closeLen > 0) {
+      const end = run.mdStart + run.mdLen;
+      range.markers.push({
+        at: range.to,
+        side: -2,
+        text: map.value.slice(end - run.closeLen, end),
+      });
+    }
+    openLength += run.openLen - run.closeLen;
+    if (openLength === 0) {
+      ranges.push(range);
+      range = null;
+    }
+  }
+  return ranges;
+}
+
+const MarkerPluginKey = new PluginKey("composer-rich-markers");
+
+const ComposerMarkerPlugin = new Plugin({
+  key: MarkerPluginKey,
+  state: {
+    init: (_, state) => decorationsForSelection(state.doc, state.selection),
+    apply: (tr, old) =>
+      tr.docChanged || tr.selectionSet ? decorationsForSelection(tr.doc, tr.selection) : old,
+  },
+  props: {
+    decorations(state) {
+      return MarkerPluginKey.getState(state);
+    },
+  },
+});
+
+function decorationsForSelection(
+  doc: ProseMirrorNode,
+  selection: { from: number; to: number; empty: boolean },
+): DecorationSet {
+  const decorations: Decoration[] = [];
+  if (!selection.empty) {
+    doc.nodesBetween(selection.from, selection.to, (node, pos) => {
+      if (node.type.name.startsWith("composer-")) {
+        decorations.push(
+          Decoration.node(pos, pos + node.nodeSize, { class: "composer-chip-range-selected" }),
+        );
+        return false;
+      }
+      return true;
+    });
+  }
+  for (const range of collectStyledRanges(doc)) {
+    const active = selection.empty
+      ? selection.from >= range.from && selection.from <= range.to
+      : selection.from < range.to && selection.to > range.from;
+    if (!active) continue;
+    for (const { at, side, text } of range.markers) {
+      const marker = document.createElement("span");
+      marker.className = "composer-rich-marker";
+      marker.textContent = text;
+      marker.setAttribute("aria-hidden", "true");
+      decorations.push(
+        Decoration.widget(at, marker, { side, key: `marker-${at}-${side}-${marker.textContent}` }),
+      );
+    }
+  }
+  return DecorationSet.create(doc, decorations);
+}
+
+const ComposerMarkersExtension = Extension.create({
+  name: "composer-rich-markers",
+  addProseMirrorPlugins() {
+    return [ComposerMarkerPlugin];
+  },
+});
+
+// Document model (markdown ⇄ ProseMirror) lives in ~/composer-rich-text-doc so
+// unit tests can round-trip it without a browser.
+// ── Editor component ───────────────────────────────────────────────────────
+
+type TiptapEditor = NonNullable<ReturnType<typeof useEditor>>;
+
+export function ComposerPromptEditorTiptap(props: ComposerPromptEditorProps) {
+  // Extensions are creation-time: flipping the setting remounts the editor.
+  // Both halves initialize from the controlled Markdown value, so the draft
+  // survives the flip.
+  return (
+    <ComposerPromptEditorTiptapInner key={props.richTextEnabled ? "rich" : "plain"} {...props} />
+  );
+}
+
+function ComposerPromptEditorTiptapInner(props: ComposerPromptEditorProps) {
+  const {
+    value,
+    cursor,
+    richTextEnabled,
+    contextRecords,
+    buildContextClipboardFragment,
+    importContextFragment,
+    skills,
+    disabled,
+    placeholder,
+    containerClassName,
+    className,
+    placeholderClassName,
+    onChange,
+    onVisibleSelectionChange,
+    onCommandKeyDown,
+    onPageScrollKeyDown,
+    onPageScrollKeyUp,
+    onPageScrollRelease,
+    onCitationSubmitAndSend,
+    onPaste,
+    editorRef,
+  } = props;
+  // The setting toggles styling, not the engine: both modes are Tiptap.
+  // Plain mode disables the mark extensions, so markers stay literal text.
+  const richText = richTextEnabled ?? false;
+
+  const onChangeRef = useRef(onChange);
+  const onVisibleSelectionChangeRef = useRef(onVisibleSelectionChange);
+  const onCommandKeyDownRef = useRef(onCommandKeyDown);
+  const buildFragmentRef = useRef(buildContextClipboardFragment);
+  const importFragmentRef = useRef(importContextFragment);
+  const skillsRef = useRef(skills);
+  const latestValueRef = useRef(value);
+  // The editor instance for callbacks created before it exists (paste).
+  // Effects flush before any user interaction, so this is always set.
+  const editorHolder = useRef<TiptapEditor | null>(null);
+
+  useEffect(() => {
+    onChangeRef.current = onChange;
+  }, [onChange]);
+  useEffect(() => {
+    onVisibleSelectionChangeRef.current = onVisibleSelectionChange;
+  }, [onVisibleSelectionChange]);
+  useEffect(() => {
+    onCommandKeyDownRef.current = onCommandKeyDown;
+  }, [onCommandKeyDown]);
+  useEffect(() => {
+    buildFragmentRef.current = buildContextClipboardFragment;
+  }, [buildContextClipboardFragment]);
+  useEffect(() => {
+    importFragmentRef.current = importContextFragment;
+  }, [importContextFragment]);
+  useEffect(() => {
+    skillsRef.current = skills;
+  }, [skills]);
+  useLayoutEffect(() => {
+    latestValueRef.current = value;
+  }, [value]);
+
+  const skillLabelFor = useCallback((name: string): SkillMeta => {
+    const normalized = name.startsWith("$") ? name.slice(1) : name;
+    const skill = skillsRef.current.find((candidate) => candidate.name === normalized);
+    if (!skill) {
+      return { label: formatProviderSkillDisplayName({ name: normalized }), description: null };
+    }
+    const shortDescription = skill.shortDescription?.trim();
+    return {
+      label: formatProviderSkillDisplayName(skill),
+      description: shortDescription || skill.description?.trim() || null,
+    };
+  }, []);
+
+  const initialCursor = clampCollapsedComposerCursor(value, cursor);
+  const initialExpandedCursor = expandCollapsedComposerCursor(value, initialCursor);
+  const snapshotRef = useRef({
+    value,
+    cursor: initialCursor,
+    expandedCursor: initialExpandedCursor,
+    contextIds: collectInlineContextIds(value),
+  });
+  const selectionRangeRef = useRef({ start: initialExpandedCursor, end: initialExpandedCursor });
+  const isApplyingControlledUpdateRef = useRef(false);
+  const hasAppliedControlledSelectionRef = useRef(false);
+  const citationRequestRef = useRef<ComposerCitationCommentRequest | null>(null);
+  const [openCitation, setOpenCitation] = useState<OpenCitationComment | null>(null);
+  const [isEmpty, setIsEmpty] = useState(value.length === 0);
+
+  const citationCommentActions = useMemo(
+    () => ({
+      openComment: openCitation,
+      onOpenChange: (nodeKey: string, open: boolean) => {
+        setOpenCitation((current) => {
+          if (open) {
+            if (current?.key === nodeKey) return current;
+            return { key: nodeKey };
+          }
+          return current?.key === nodeKey ? null : current;
+        });
+      },
+      onSubmitAndSend: onCitationSubmitAndSend ?? (() => {}),
+    }),
+    [onCitationSubmitAndSend, openCitation],
+  );
+
+  const handleEditorChange = useCallback((updated: TiptapEditor) => {
+    const map = serializeEditorDoc(updated.state.doc);
+    const { from, to } = updated.state.selection;
+    const fromFlat = pmToFlat(map, from);
+    const toFlat = pmToFlat(map, to);
+    const nextValue = map.value;
+    const nextCursor = clampCollapsedComposerCursor(map.value, flatToCollapsed(map, fromFlat));
+    const nextExpandedCursor = Math.max(
+      0,
+      Math.min(map.value.length, flatToMarkdown(map, fromFlat)),
+    );
+    const nextSelectionRange = {
+      start: Math.min(nextExpandedCursor, flatToMarkdown(map, toFlat)),
+      end: Math.max(nextExpandedCursor, flatToMarkdown(map, toFlat)),
+    };
+    const previousSelectionRange = selectionRangeRef.current;
+    selectionRangeRef.current = nextSelectionRange;
+    setIsEmpty(nextValue.length === 0);
+    const previousSnapshot = snapshotRef.current;
+    const snapshotChanged = !(
+      previousSnapshot.value === nextValue &&
+      previousSnapshot.cursor === nextCursor &&
+      previousSnapshot.expandedCursor === nextExpandedCursor &&
+      previousSnapshot.contextIds.length === map.contextIds.length &&
+      previousSnapshot.contextIds.every((id, index) => id === map.contextIds[index])
+    );
+    if (isApplyingControlledUpdateRef.current) return;
+    if (!snapshotChanged) {
+      if (didComposerSelectionChangeVisibly(previousSelectionRange, nextSelectionRange)) {
+        onVisibleSelectionChangeRef.current?.();
+      }
+      return;
+    }
+    // A selection-only update while a newer prompt waits to be applied (a chip
+    // was just inserted through the store) would report stale text and clobber
+    // the prompt. Let the controlled rewrite land instead.
+    if (previousSnapshot.value === nextValue && nextValue !== latestValueRef.current) {
+      return;
+    }
+    snapshotRef.current = {
+      value: nextValue,
+      cursor: nextCursor,
+      expandedCursor: nextExpandedCursor,
+      contextIds: map.contextIds,
+    };
+    const cursorAdjacentToMention =
+      isCollapsedCursorAdjacentToInlineToken(nextValue, nextCursor, "left") ||
+      isCollapsedCursorAdjacentToInlineToken(nextValue, nextCursor, "right");
+    onChangeRef.current(
+      nextValue,
+      nextCursor,
+      nextExpandedCursor,
+      cursorAdjacentToMention,
+      map.contextIds,
+    );
+  }, []);
+
+  const editor = useEditor(
+    {
+      extensions: [
+        StarterKit.configure({
+          blockquote: false,
+          bulletList: false,
+          codeBlock: false,
+          heading: false,
+          horizontalRule: false,
+          listItem: false,
+          link: false,
+          orderedList: false,
+          underline: false,
+          dropcursor: false,
+          gapcursor: false,
+          trailingNode: false,
+          // Plain mode has no marks: typed markers stay literal characters.
+          ...(richText ? {} : { bold: false, italic: false, strike: false, code: false }),
+        }),
+        ComposerMentionExtension,
+        ComposerSkillExtension,
+        ComposerCitationExtension,
+        ComposerContextReferenceExtension,
+        ComposerMarkersExtension,
+        ...(richText
+          ? [
+              TaskList,
+              ComposerTaskItemExtension.extend({
+                addInputRules() {
+                  return [
+                    wrappingInputRule({
+                      find: /^- \[([ xX])\] $/,
+                      type: this.type,
+                      getAttributes: (match) => ({ checked: match[1]?.toLowerCase() === "x" }),
+                    }),
+                  ];
+                },
+              }),
+            ]
+          : []),
+      ],
+      content: buildDocJson(
+        value,
+        (name) => {
+          const normalized = name.startsWith("$") ? name.slice(1) : name;
+          const found = skills.find((candidate) => candidate.name === normalized);
+          if (!found) {
+            return {
+              label: formatProviderSkillDisplayName({ name: normalized }),
+              description: null,
+            };
+          }
+          const shortDescription = found.shortDescription?.trim();
+          return {
+            label: formatProviderSkillDisplayName(found),
+            description: shortDescription || found.description?.trim() || null,
+          };
+        },
+        { styling: richText },
+      ),
+      editable: !disabled,
+      editorProps: {
+        attributes: {
+          class: cn(
+            "composer-tiptap block max-h-50 min-h-17.5 w-full overflow-y-auto whitespace-pre-wrap wrap-break-word bg-transparent leading-relaxed text-foreground focus:outline-none",
+            className,
+          ),
+          "data-testid": "composer-editor",
+          "data-composer-rich-text": richText ? "true" : "false",
+          "aria-placeholder": placeholder,
+        },
+        handleKeyDown: (view, event) => {
+          if (
+            isMacPlatform(navigator.platform) &&
+            (event.key === "Home" || event.key === "End") &&
+            !event.altKey &&
+            !event.metaKey &&
+            !event.ctrlKey &&
+            !event.isComposing
+          ) {
+            const selection = window.getSelection();
+            if (
+              selection?.anchorNode &&
+              view.dom.contains(selection.anchorNode) &&
+              typeof selection.modify === "function"
+            ) {
+              event.preventDefault();
+              event.stopPropagation();
+              selection.modify(
+                event.shiftKey ? "extend" : "move",
+                event.key === "Home" ? "backward" : "forward",
+                "lineboundary",
+              );
+              if (selection.anchorNode && selection.focusNode) {
+                view.dispatch(
+                  view.state.tr
+                    .setSelection(
+                      TextSelection.create(
+                        view.state.doc,
+                        view.posAtDOM(selection.anchorNode, selection.anchorOffset),
+                        view.posAtDOM(selection.focusNode, selection.focusOffset),
+                      ),
+                    )
+                    .scrollIntoView(),
+                );
+              }
+              return true;
+            }
+          }
+          if (
+            (event.key === "ArrowLeft" || event.key === "ArrowRight") &&
+            !event.shiftKey &&
+            !event.altKey &&
+            !event.metaKey &&
+            !event.ctrlKey &&
+            !event.isComposing &&
+            view.state.selection.empty
+          ) {
+            const { $from } = view.state.selection;
+            const direction = event.key === "ArrowLeft" ? -1 : 1;
+            const adjacent = direction === -1 ? $from.nodeBefore : $from.nodeAfter;
+            if (adjacent?.type.name.startsWith("composer-")) {
+              event.preventDefault();
+              event.stopPropagation();
+              view.dispatch(
+                view.state.tr
+                  .setSelection(
+                    TextSelection.create(view.state.doc, $from.pos + direction * adjacent.nodeSize),
+                  )
+                  .scrollIntoView(),
+              );
+              return true;
+            }
+          }
+          if (event.key === "Enter" && (event.isComposing || event.keyCode === 229)) {
+            event.stopPropagation();
+            return true;
+          }
+          // Enter on a focused task checkbox must not send the prompt (or
+          // split anything): Space toggles it, Enter does nothing.
+          if (event.key === "Enter" && event.target instanceof HTMLInputElement) {
+            event.preventDefault();
+            return true;
+          }
+          const handler = onCommandKeyDownRef.current;
+          if (event.key === "Enter") {
+            const instance = editorHolder.current;
+            const isTaskItem = richText && (instance?.isActive("taskItem") ?? false);
+            const handled = handler?.("Enter", event, isTaskItem) ?? false;