@tessera-editor/react 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tessera-editor/react",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Tessera React binding with the full default UI",
   "license": "MIT",
   "type": "module",
@@ -30,8 +30,8 @@
     "@tiptap/react": "^3.31.3",
     "@tiptap/starter-kit": "^3.31.3",
     "@tiptap/suggestion": "^3.31.3",
-    "@tessera-editor/ai": "0.1.0",
-    "@tessera-editor/core": "0.1.0"
+    "@tessera-editor/ai": "0.1.1",
+    "@tessera-editor/core": "0.2.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",

package/src/EmptyLineToolbar.tsx

@@ -1,7 +1,7 @@
 import { useCallback, useContext, useEffect, useLayoutEffect, useRef, useState } from 'react'
 import type { CSSProperties } from 'react'
 import { createPortal } from 'react-dom'
-import { defaultSlashItems } from '@tessera-editor/core'
+import { defaultSlashItems, filterSlashItems } from '@tessera-editor/core'
 import type { SlashMenuItem, TesseraTranslator } from '@tessera-editor/core'
 import { aiSlashItems } from '@tessera-editor/ai'
 import type { Editor } from '@tiptap/react'
@@ -17,18 +17,15 @@ import { useTesseraPortalRoot } from './portal'
  * hide, nor move the toolbar (M0 spike finding).
  */
 
-function buildItems(editor: Editor, t: TesseraTranslator, hasAi: boolean): SlashMenuItem[] {
-  const base = defaultSlashItems(t)
-  if (!hasAi) {
-    return base
-  }
-  // AI items need a runtime; context provides it — reconstructed here via
-  // context injection from the parent (see useItems below).
-  return base
+/** The expanded panel mirrors the slash menu, minus host-excluded blocks. */
+function buildItems(editor: Editor, t: TesseraTranslator): SlashMenuItem[] {
+  const slash = editor.extensionManager.extensions.find(ext => ext.name === 'tesseraSlashMenu')
+  const excluded = (slash?.options as { excludeItems?: string[] } | undefined)?.excludeItems
+  return filterSlashItems(defaultSlashItems(t), excluded)
 }
 
 export function EmptyLineToolbar() {
-  const { editor, t, ai } = useContext(TesseraContext)!
+  const { editor, t } = useContext(TesseraContext)!
   const [style, setStyle] = useState<CSSProperties | null>(null)
   const [expanded, setExpanded] = useState(false)
   const [panelPlacement, setPanelPlacement] = useState<'bottom' | 'top'>('bottom')
@@ -147,7 +144,7 @@ export function EmptyLineToolbar() {
     return null
   }
 
-  const items = buildItems(editor, t, !!ai)
+  const items = buildItems(editor, t)
 
   const runItem = (item: SlashMenuItem) => {
     const { $from } = editor.state.selection

package/src/ImageNodeView.tsx

@@ -12,7 +12,6 @@ import { TesseraContext } from './context'
  */
 
 function AiImageNodeView({ node, updateAttributes, selected, decorations }: NodeViewProps) {
-  console.log('[imgview] decorations:', Array.isArray(decorations), decorations?.length)
   const galleryAttrs = (() => {
     for (const deco of decorations ?? []) {
       const attrs = (deco as unknown as { type?: { attrs?: Record<string, string> } }).type?.attrs
@@ -25,14 +24,31 @@ function AiImageNodeView({ node, updateAttributes, selected, decorations }: Node
   const { t } = useContext(TesseraContext)!
   const imgRef = useRef<HTMLImageElement>(null)
   const [preview, setPreview] = useState<string | null>(null)
+  const [zoom, setZoom] = useState(1)
+  const clampZoom = (z: number) => Math.min(8, Math.max(0.2, z))
 
   useEffect(() => {
     if (!preview) return
+    setZoom(1)
     const close = (e: KeyboardEvent) => {
       if (e.key === 'Escape') setPreview(null)
+      else if (e.key === '+' || e.key === '=') setZoom(z => clampZoom(z * 1.25))
+      else if (e.key === '-') setZoom(z => clampZoom(z / 1.25))
+      else if (e.key === '0') setZoom(1)
+    }
+    // ctrl+wheel needs a non-passive listener so preventDefault can
+    // suppress the browser's own page zoom
+    const onWheel = (e: WheelEvent) => {
+      if (!e.ctrlKey) return
+      e.preventDefault()
+      setZoom(z => clampZoom(z * (e.deltaY < 0 ? 1.15 : 1 / 1.15)))
     }
     window.addEventListener('keydown', close)
-    return () => window.removeEventListener('keydown', close)
+    window.addEventListener('wheel', onWheel, { passive: false })
+    return () => {
+      window.removeEventListener('keydown', close)
+      window.removeEventListener('wheel', onWheel)
+    }
   }, [preview])
   const { src, alt, width, align } = node.attrs as {
     src: string
@@ -92,7 +108,26 @@ function AiImageNodeView({ node, updateAttributes, selected, decorations }: Node
       {preview
         ? createPortal(
             <div className="tessera-lightbox" onClick={() => setPreview(null)}>
-              <img src={preview} alt={alt ?? ''} />
+              <img
+                src={preview}
+                alt={alt ?? ''}
+                style={{ transform: `scale(${zoom})` }}
+                onClick={e => e.stopPropagation()}
+                onDoubleClick={() => setZoom(1)}
+              />
+              <div className="tessera-lightbox-bar" onClick={e => e.stopPropagation()}>
+                <button type="button" title={t('imageZoomOut')} onClick={() => setZoom(z => clampZoom(z / 1.25))}>
+                  −
+                </button>
+                <span className="tessera-lightbox-scale">{Math.round(zoom * 100)}%</span>
+                <button type="button" title={t('imageZoomIn')} onClick={() => setZoom(z => clampZoom(z * 1.25))}>
+                  +
+                </button>
+                <button type="button" title={t('imageZoomReset')} onClick={() => setZoom(1)}>
+                  1:1
+                </button>
+                <span className="tessera-lightbox-hint">{t('imageZoomHint')}</span>
+              </div>
             </div>,
             document.body,
           )

package/src/LinkEditor.tsx

@@ -0,0 +1,121 @@
+import { useContext, useEffect, useRef, useState } from 'react'
+import type { CSSProperties } from 'react'
+import { createPortal } from 'react-dom'
+import { findLinkRange, removeLinkRange, saveLinkRange } from '@tessera-editor/core'
+import type { TesseraLinkRange } from '@tessera-editor/core'
+import { TesseraContext } from './context'
+import { useTesseraPortalRoot } from './portal'
+
+/**
+ * Click-to-edit link panel: clicking a link in the document opens a compact
+ * editor for its display text and href; 移除链接 degrades it back to plain
+ * text. Doc semantics live in core (linkedit.ts) so both bindings match.
+ */
+
+export function LinkEditor() {
+  const { editor, t } = useContext(TesseraContext)!
+  const portalRoot = useTesseraPortalRoot(editor)
+  const [range, setRange] = useState<TesseraLinkRange | null>(null)
+  const [text, setText] = useState('')
+  const [href, setHref] = useState('')
+  const [style, setStyle] = useState<CSSProperties>({})
+  const panelRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    const onClick = (e: MouseEvent) => {
+      const target = e.target as HTMLElement
+      const anchor = target.closest('a[href]')
+      if (!anchor || !editor.view.dom.contains(target)) {
+        setRange(null)
+        return
+      }
+      // read-only: a link click opens the target instead of the editor panel
+      if (!editor.isEditable) {
+        const href = anchor.getAttribute('href')
+        if (href) {
+          window.open(href, '_blank', 'noopener,noreferrer')
+        }
+        return
+      }
+      const found = findLinkRange(editor, editor.view.posAtDOM(anchor, 0))
+      if (found) openPanel(found)
+    }
+    const dom = editor.view.dom
+    dom.addEventListener('click', onClick)
+    return () => dom.removeEventListener('click', onClick)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [editor])
+
+  // any mousedown outside the panel dismisses it; a click on another link
+  // re-opens with that link via the handler above
+  useEffect(() => {
+    if (!range) return
+    const onDown = (e: MouseEvent) => {
+      if (!panelRef.current?.contains(e.target as Node)) setRange(null)
+    }
+    window.addEventListener('mousedown', onDown)
+    return () => window.removeEventListener('mousedown', onDown)
+  }, [range])
+
+  function openPanel(found: TesseraLinkRange) {
+    setRange(found)
+    setText(found.text)
+    setHref(found.href)
+    const a = editor.view.coordsAtPos(found.from)
+    const b = editor.view.coordsAtPos(found.to)
+    const left = Math.min(Math.max(8, (a.left + b.left) / 2 - 160), window.innerWidth - 328)
+    const bottom = Math.max(a.bottom, b.bottom)
+    const panelMax = 170
+    const flip = bottom + 8 + panelMax > window.innerHeight && a.top - 8 - panelMax >= 0
+    setStyle(
+      flip
+        ? { left: `${left}px`, bottom: `${window.innerHeight - Math.min(a.top, b.top) + 8}px` }
+        : { left: `${left}px`, top: `${bottom + 8}px` },
+    )
+  }
+
+  function save() {
+    if (!range || !text.trim()) return
+    saveLinkRange(editor, range, { text, href })
+    setRange(null)
+  }
+
+  function remove() {
+    if (!range) return
+    removeLinkRange(editor, range)
+    setRange(null)
+  }
+
+  function onInputKeyDown(e: React.KeyboardEvent) {
+    if (e.key === 'Enter') save()
+    if (e.key === 'Escape') setRange(null)
+  }
+
+  if (!range || !portalRoot) return null
+  return createPortal(
+    <div ref={panelRef} className="tessera-link-editor" style={style} onMouseDown={e => e.stopPropagation()}>
+      <input
+        autoFocus
+        value={text}
+        placeholder={t('linkTextPlaceholder')}
+        onChange={e => setText(e.target.value)}
+        onKeyDown={onInputKeyDown}
+      />
+      <input
+        value={href}
+        placeholder={t('linkPlaceholder')}
+        onChange={e => setHref(e.target.value)}
+        onKeyDown={onInputKeyDown}
+      />
+      <div className="tessera-link-editor-row">
+        <button type="button" disabled={!text.trim()} onClick={save}>
+          {t('linkSave')}
+        </button>
+        <button type="button" className="tessera-danger" onClick={remove}>
+          {t('linkRemove')}
+        </button>
+      </div>
+    </div>,
+    portalRoot,
+  )
+}

package/src/SelectionToolbar.tsx

@@ -68,12 +68,17 @@ function FlipPopover({
 }
 
 export function SelectionToolbar({ onSession }: { onSession: (session: SuggestionSession | null) => void }) {
-  const { editor, t, ai } = useContext(TesseraContext)!
+  const { editor, t, ai, extraSelectionItems } = useContext(TesseraContext)!
   const [style, setStyle] = useState<CSSProperties | null>(null)
   const [popover, setPopover] = useState<PopoverKind>(null)
   const [linkValue, setLinkValue] = useState('')
   const composingRef = useRef(false)
   const portalRoot = useTesseraPortalRoot(editor)
+  // Capability-gated buttons: comments need a CommentStore, the collapsible
+  // button needs the collapsible node (hosts may exclude it).
+  const services = (editor.storage as unknown as Record<string, Record<string, unknown>>).tesseraServices
+  const hasComments = !!services?.comments
+  const hasCollapsible = editor.extensionManager.extensions.some(ext => ext.name === 'collapsible')
 
   const reposition = useCallback(() => {
     if (composingRef.current || !editor.isFocused) {
@@ -185,19 +190,24 @@ export function SelectionToolbar({ onSession }: { onSession: (session: Suggestio
       <TbBtn title={t('tooltipLink')} active={editor.isActive('link')} onClick={() => setPopover(p => (p === 'link' ? null : 'link'))}>
         🔗
       </TbBtn>
-      <TbBtn
-        title={t('tooltipCommentV11')}
-        active={editor.isActive('comment')}
-        onClick={() => setPopover(p => (p === 'comment' ? null : 'comment'))}
-      >
-        💬
-      </TbBtn>
-      <TbBtn title={t('tooltipTurnCollapsible')} onClick={() => chain().insertCollapsible().run()}>
-        ▸
-      </TbBtn>
+      {hasComments ? (
+        <TbBtn
+          title={t('tooltipCommentV11')}
+          active={editor.isActive('comment')}
+          onClick={() => setPopover(p => (p === 'comment' ? null : 'comment'))}
+        >
+          💬
+        </TbBtn>
+      ) : null}
+      {hasCollapsible ? (
+        <TbBtn title={t('tooltipTurnCollapsible')} onClick={() => chain().insertCollapsible().run()}>
+          ▸
+        </TbBtn>
+      ) : null}
       <TbBtn title={t('tooltipMore')} onClick={() => setPopover(p => (p === 'more' ? null : 'more'))}>
         ⋯
       </TbBtn>
+      {typeof extraSelectionItems === 'function' ? extraSelectionItems({ editor, t }) : extraSelectionItems}
 
       {popover === 'color' ? (
         <FlipPopover posKey={style}>

package/src/SlashMenu.tsx

@@ -79,7 +79,7 @@ export const SlashMenuView = forwardRef<{ onKeyDown: (props: SuggestionKeyDownPr
       : { position: 'fixed', left: -9999, top: -9999 }
 
     return (
-      <div className="tessera-slash-menu" style={style} data-testid="slash-menu">
+      <div ref={listRef} className="tessera-slash-menu" style={style} data-testid="slash-menu">
         {Array.from(groups.entries()).map(([group, groupItems]) => (
           <div key={group} className="tessera-slash-group">
             <div className="tessera-slash-group-title">

package/src/TableNodeViews.tsx

@@ -1,4 +1,6 @@
-import { useContext, useState } from 'react'
+import { useContext, useEffect, useRef, useState } from 'react'
+import type { CSSProperties } from 'react'
+import { createPortal } from 'react-dom'
 import { NodeViewWrapper, NodeViewContent, ReactNodeViewRenderer } from '@tiptap/react'
 import type { NodeViewProps } from '@tiptap/react'
 import {
@@ -9,6 +11,7 @@ import {
 } from '@tessera-editor/core'
 import type { TableColumnKind } from '@tessera-editor/core'
 import { TesseraContext } from './context'
+import { useTesseraPortalRoot } from './portal'
 
 /**
  * Table NodeViews (v1.1):
@@ -53,10 +56,49 @@ function columnIndex(props: NodeViewProps): number {
 /** Header cell with the column menu. */
 function AiTableHeaderView(props: NodeViewProps) {
   const { editor, t } = useContext(TesseraContext)!
+  const portalRoot = useTesseraPortalRoot(editor)
   const [open, setOpen] = useState(false)
+  const [style, setStyle] = useState<CSSProperties>({})
+  const thRef = useRef<HTMLDivElement>(null)
+  const menuRef = useRef<HTMLDivElement>(null)
   const index = columnIndex(props)
 
+  // the table has overflow:hidden (corner rounding), so an inline dropdown
+  // would be clipped away — the menu portals out of the table and anchors
+  // to the header cell with fixed positioning, flipping near the viewport
+  // bottom like every other popover
+  const toggle = () => {
+    const th = thRef.current
+    if (th) {
+      const r = th.getBoundingClientRect()
+      const flip = window.innerHeight - r.bottom < 340 && r.top > 340
+      const left = Math.min(Math.max(8, r.left), window.innerWidth - 198)
+      setStyle(
+        flip
+          ? { left: `${left}px`, top: 'auto', bottom: `${window.innerHeight - r.top + 6}px` }
+          : { left: `${left}px`, top: `${r.bottom + 6}px`, bottom: 'auto' },
+      )
+    }
+    setOpen(v => !v)
+  }
+
+  useEffect(() => {
+    if (!open) return
+    const onDown = (e: MouseEvent) => {
+      const target = e.target as HTMLElement
+      if (menuRef.current?.contains(target) || target.closest('.tessera-col-menu-btn')) return
+      setOpen(false)
+    }
+    window.addEventListener('mousedown', onDown)
+    return () => window.removeEventListener('mousedown', onDown)
+  }, [open])
+
   const run = (fn: () => unknown) => {
+    // read-only docs must not mutate, however the menu was triggered
+    if (!editor.isEditable) {
+      setOpen(false)
+      return
+    }
     setOpen(false)
     // re-select into this cell so table commands locate the table
     const pos = props.getPos()
@@ -67,7 +109,7 @@ function AiTableHeaderView(props: NodeViewProps) {
   }
 
   return (
-    <NodeViewWrapper as="th" className="tessera-th" data-index={index}>
+    <NodeViewWrapper ref={thRef} as="th" className="tessera-th" data-index={index}>
       <NodeViewContent className="tessera-th-content" />
       <button
         type="button"
@@ -75,12 +117,19 @@ function AiTableHeaderView(props: NodeViewProps) {
         contentEditable={false}
         title={t('colMenuTitle')}
         onMouseDown={e => e.preventDefault()}
-        onClick={() => setOpen(v => !v)}
+        onClick={toggle}
       >
         ⌄
       </button>
-      {open ? (
-        <div className="tessera-popover tessera-col-menu" contentEditable={false} onMouseDown={e => e.preventDefault()}>
+      {open && portalRoot
+        ? createPortal(
+            <div
+              ref={menuRef}
+              className="tessera-popover tessera-col-menu"
+              style={{ position: 'fixed', ...style }}
+              contentEditable={false}
+              onMouseDown={e => e.preventDefault()}
+            >
           <div className="tessera-menu-section">
             {TABLE_COLUMN_KINDS.map(kind => (
               <button key={kind} type="button" onClick={() => run(() => editor.commands.setColumnType(index, kind))}>
@@ -125,8 +174,9 @@ function AiTableHeaderView(props: NodeViewProps) {
           <button type="button" className="tessera-danger" onClick={() => run(() => editor.commands.deleteTable())}>
             {t('tableDelete')}
           </button>
-        </div>
-      ) : null}
+            </div>,
+            portalRoot,
+          ) : null}
     </NodeViewWrapper>
   )
 }
@@ -161,7 +211,7 @@ function AiTableCellView(props: NodeViewProps) {
 
   if (kind === 'text') {
     return (
-      <NodeViewWrapper as="td" className="tessera-td">
+      <NodeViewWrapper as="td" className="tessera-td" data-index={columnIndex(props)}>
         <NodeViewContent />
       </NodeViewWrapper>
     )
@@ -170,7 +220,7 @@ function AiTableCellView(props: NodeViewProps) {
   const setValue = (next: unknown) => props.updateAttributes({ value: next })
 
   return (
-    <NodeViewWrapper as="td" className={`tessera-td tessera-td--${kind}`}>
+    <NodeViewWrapper as="td" className={`tessera-td tessera-td--${kind}`} data-index={columnIndex(props)}>
       <NodeViewContent className="tessera-td-hidden" />
       {kind === 'checkbox' ? (
         <input

package/src/Tessera.tsx

@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import type { CSSProperties } from 'react'
+import type { CSSProperties, ReactNode } from 'react'
 import { EditorContent, useEditor } from '@tiptap/react'
 import type { Editor } from '@tiptap/react'
 import type { Content, EditorOptions } from '@tiptap/core'
@@ -10,8 +10,9 @@ import {
 } from '@tessera-editor/core'
 import type {
   TesseraLocale,
+  TesseraMessageOverrides,
+  TesseraTranslator,
   UploadService,
-  StorageService,
   CommentStore,
   IdentityService,
 } from '@tessera-editor/core'
@@ -23,9 +24,9 @@ import { EmbedBlockView, TocBlockView } from './EmbedTocViews'
 import { createSlashRenderer } from './SlashMenu'
 import { createEmojiRenderer } from './EmojiMenu'
 import { EmptyLineToolbar } from './EmptyLineToolbar'
+import { LinkEditor } from './LinkEditor'
 import { SelectionToolbar } from './SelectionToolbar'
 import { FindReplacePanel, AskPanel, SuggestionBar } from './Panels'
-import { HistoryPanel } from './HistoryPanel'
 import { CommentPanel } from './CommentPanel'
 import { BlockContextMenuUI } from './BlockMenu'
 import { TesseraContext } from './context'
@@ -35,20 +36,33 @@ export interface TesseraProps {
   /** Initial document (JSON / HTML / markdown string). Host owns persistence. */
   content?: Content
   locale?: TesseraLocale
+  /** Empty-paragraph placeholder text (default: the i18n `placeholderEmpty` string). */
+  placeholder?: string
+  /** Per-key overrides of the built-in UI dictionary (slash items, tooltips…). */
+  messages?: TesseraMessageOverrides
+  /** Render the editor read-only (default: editable). */
+  editable?: boolean
+  /**
+   * Host block policy: top-level block types to exclude entirely (see
+   * `TesseraPresetOptions.excludeBlocks`). Read once at editor creation.
+   */
+  excludeBlocks?: string[]
   /** Injected image upload capability (ADR-0001 family). */
   upload?: UploadService
-  /** v1.1: version-history snapshot storage. */
-  storage?: StorageService
   /** v1.1: inline comment persistence. */
   comments?: CommentStore
   /** v1.1: current user (comment authorship). */
   identity?: IdentityService
   /** Injected model runtime; presence enables all AI surfaces. */
   ai?: AIRuntime
-  /** v1.1: idle window for history auto-capture (playground uses short ones) */
-  historyIdleMs?: number
   /** v1.1: document column max-width in px (Slite-style centered column). */
   docWidth?: number
+  /**
+   * Host buttons appended to the selection toolbar (e.g. custom AI actions).
+   * A render function receives the live editor + translator, so a host button
+   * like 「让 AI 改写此段」 can read the current selection on click.
+   */
+  extraSelectionItems?: ReactNode | ((ctx: { editor: Editor; t: TesseraTranslator }) => ReactNode)
   onUpdate?: (editor: Editor) => void
   onCreate?: (editor: Editor) => void
 }
@@ -68,17 +82,19 @@ const DRAG_HANDLE_POSITION_CONFIG = { placement: 'left', strategy: 'absolute' }
 export function Tessera({
   content,
   locale = 'zh-CN',
+  placeholder,
+  messages,
+  editable = true,
+  excludeBlocks,
   upload,
-  storage,
   comments,
   identity,
   ai: runtime,
-  historyIdleMs,
   docWidth,
+  extraSelectionItems,
   onUpdate,
   onCreate,
 }: TesseraProps) {
-  const t = useMemo(() => createTesseraT(locale), [locale])
   const [session, setSession] = useState<SuggestionSession | null>(null)
   const fileInputRef = useRef<HTMLInputElement>(null)
   type DragNodeData = {
@@ -96,19 +112,35 @@ export function Tessera({
   // destroys and recreates ALL plugin views. A recreated suggestion view
   // starts from an already-active state with no "started" transition, so
   // renderer.onStart never fires and the slash menu UI never mounts.
-  // Latest prop values are therefore read through refs instead.
+  // Latest prop values are therefore read through refs instead — this also
+  // applies to `messages`/`placeholder`/`excludeBlocks`, which hosts may pass
+  // as inline literals. Config is read once at editor creation; later changes
+  // require remounting the component.
   const onUpdateRef = useRef(onUpdate)
   onUpdateRef.current = onUpdate
   const onCreateRef = useRef(onCreate)
   onCreateRef.current = onCreate
   const runtimeRef = useRef(runtime)
   runtimeRef.current = runtime
+  const placeholderRef = useRef(placeholder)
+  placeholderRef.current = placeholder
+  const messagesRef = useRef(messages)
+  messagesRef.current = messages
+  const excludeBlocksRef = useRef(excludeBlocks)
+  excludeBlocksRef.current = excludeBlocks
   const initialContentRef = useRef(content)
   const editorRef = useRef<Editor | null>(null)
 
+  const t = useMemo(() => createTesseraT(locale, messagesRef.current), [locale])
+
   const extensions = useMemo(
     () =>
-      createTesseraExtensions({ locale, historyIdleMs }).map(ext => {
+      createTesseraExtensions({
+        locale,
+        placeholder: placeholderRef.current,
+        messages: messagesRef.current,
+        excludeBlocks: excludeBlocksRef.current,
+      }).map(ext => {
         if (ext.name === 'tesseraSlashMenu') {
           return ext.configure({
             render: createSlashRenderer(t),
@@ -141,7 +173,7 @@ export function Tessera({
     // runtime is read through runtimeRef on purpose: rebuilding the extension
     // list after mount cannot apply anyway (extensions are only read when the
     // editor is created) and would only trigger the setOptions churn above
-    [locale, t, historyIdleMs],
+    [locale, t],
   )
 
   async function uploadAndInsert(file: File) {
@@ -195,11 +227,16 @@ export function Tessera({
   )
 
   const handleUpdate = useCallback(({ editor: e }: { editor: Editor }) => onUpdateRef.current?.(e), [])
-  const handleCreate = useCallback(({ editor: e }: { editor: Editor }) => onCreateRef.current?.(e), [])
+  const handleCreate = useCallback(({ editor: e }: { editor: Editor }) => {
+    // legacy docs may carry stray hidden text in typed cells
+    e.commands.normalizeTypedCells()
+    onCreateRef.current?.(e)
+  }, [])
 
   const editor = useEditor({
     extensions,
     content: initialContentRef.current,
+    editable,
     onUpdate: handleUpdate,
     onCreate: handleCreate,
     editorProps,
@@ -214,12 +251,18 @@ export function Tessera({
       ;(editor.storage as unknown as Record<string, Record<string, unknown>>).tesseraServices = {
         ...bag,
         upload,
-        storage,
         comments,
         identity,
       }
     }
-  }, [editor, upload, storage, comments, identity])
+  }, [editor, upload, comments, identity])
+
+  // read-only is a live toggle, not just an initial option
+  useEffect(() => {
+    if (editor) {
+      editor.setEditable(editable)
+    }
+  }, [editor, editable])
 
   // editor events → UI (image picker, sessions from slash AI items)
   useEffect(() => {
@@ -246,9 +289,10 @@ export function Tessera({
   }
 
   return (
-    <TesseraContext.Provider value={{ editor, locale, t, ai }}>
+    <TesseraContext.Provider value={{ editor, locale, t, ai, extraSelectionItems }}>
       <div
         className="tessera-root"
+        data-readonly={editable ? undefined : 'true'}
         style={{ '--te-doc-max-width': docWidth ? `${docWidth}px` : undefined } as CSSProperties}
       >
         <EditorContent editor={editor} />
@@ -290,9 +334,9 @@ export function Tessera({
         </DragHandle>
         <EmptyLineToolbar />
         <SelectionToolbar onSession={setSession} />
+        <LinkEditor />
         <FindReplacePanel />
         <AskPanel />
-        <HistoryPanel />
         <CommentPanel />
         <BlockContextMenuUI />
         <SuggestionBar session={session} onClear={() => setSession(null)} />