@multiplatform.one/rich-text 6.1.0 → 6.3.0

package/src/RichEditor.stories.tsx

@@ -31,6 +31,10 @@ const meta: Meta<typeof RichTextEditor> = {
     showBubbleToolbar: { control: "boolean" },
     compact: { control: "boolean" },
     skeleton: { control: "boolean" },
+    defaultFullscreen: { control: "boolean" },
+    fullscreen: { control: false },
+    onFullscreenChange: { control: false },
+    inlineEditing: { control: "boolean" },
     size: { control: "select", options: ["$2", "$3", "$4"] },
     minHeight: { control: "number" },
     maxHeight: { control: "number" },
@@ -322,3 +326,157 @@ export const Skeleton: Story = {
     minHeight: 200,
   },
 };
+
+// ---------------------------------------------------------------------------
+// Fullscreen
+// ---------------------------------------------------------------------------
+
+export const Fullscreen: Story = {
+  args: {
+    label: "Fullscreen",
+    defaultFullscreen: false,
+    defaultValue:
+      "<p>Use the expand button at the toolbar's right end to fill the viewport. Press Escape (or the button again) to exit.</p>",
+    minHeight: 200,
+    helperText: "Toggle fullscreen from the toolbar; Escape exits",
+  },
+};
+
+// ---------------------------------------------------------------------------
+// InlineEmbedded (native escape hatch; web renders the normal inline editor)
+// ---------------------------------------------------------------------------
+
+export const InlineEmbedded: Story = {
+  args: {
+    label: "Inline (embedded)",
+    inlineEditing: true,
+    defaultValue: "<p>Native: edits inline without the fullscreen modal (escape hatch).</p>",
+    minHeight: 160,
+    helperText: "inlineEditing keeps the old embedded editor on native",
+  },
+};
+
+// ---------------------------------------------------------------------------
+// WithMentions (@ suggestion popup wired to a demo directory)
+// ---------------------------------------------------------------------------
+
+const MENTION_DIRECTORY = [
+  { id: "ada", display: "Ada Lovelace", description: "Analyst" },
+  { id: "alan", display: "Alan Turing", description: "Computer science" },
+  { id: "grace", display: "Grace Hopper", description: "Compilers" },
+  { id: "linus", display: "Linus Torvalds", description: "Kernels" },
+  { id: "margaret", display: "Margaret Hamilton", description: "Flight software" },
+];
+
+export const WithMentions: Story = {
+  args: {
+    label: "With Mentions",
+    placeholder: "Type @ to mention someone...",
+    minHeight: 200,
+    helperText: "The @ popup shares the slash-menu chrome (LC-16)",
+    mentions: {
+      items: (query: string) =>
+        MENTION_DIRECTORY.filter((item) =>
+          item.display.toLowerCase().includes(query.toLowerCase()),
+        ),
+    },
+  },
+};
+
+// ---------------------------------------------------------------------------
+// WithEmoji (`:` shortname autocomplete — lazy dataset)
+// ---------------------------------------------------------------------------
+
+export const WithEmoji: Story = {
+  args: {
+    label: "Emoji Autocomplete",
+    placeholder: "Type : followed by a name, e.g. :tada",
+    minHeight: 160,
+    helperText:
+      "The : popup shares the slash/mention chrome (LC-16); the dataset lazy-loads on first trigger and inserts plain unicode",
+  },
+};
+
+// ---------------------------------------------------------------------------
+// WithMermaid (fenced diagram code with live preview)
+// ---------------------------------------------------------------------------
+
+export const WithMermaid: Story = {
+  args: {
+    label: "Mermaid Diagram",
+    showBubbleToolbar: true,
+    minHeight: 320,
+    helperText:
+      "The diagram engine lazy-loads on the first mermaid block; edits re-render debounced; invalid syntax shows the parse error",
+    defaultValue:
+      "<p>Flow below — edit the code to see the live preview update.</p>" +
+      '<pre><code class="language-mermaid">graph TD\n  A[Draft] --> B{Review}\n  B -->|approve| C[Merge]\n  B -->|reject| A</code></pre>',
+  },
+};
+
+// ---------------------------------------------------------------------------
+// WithMath (inline $...$ + $$ block via lazy KaTeX, incl. error state)
+// ---------------------------------------------------------------------------
+
+export const WithMath: Story = {
+  args: {
+    label: "Math (KaTeX)",
+    showBubbleToolbar: true,
+    minHeight: 320,
+    helperText:
+      "KaTeX lazy-loads on the first math node; select an inline formula to edit it; bad TeX shows the parse error",
+    defaultValue:
+      '<p>Inline: <span data-type="inline-math" data-latex="E=mc^2">E=mc^2</span> flows with text.</p>' +
+      '<pre><code class="language-math">\\sum_{i=0}^{n} i = \\frac{n(n+1)}{2}</code></pre>' +
+      '<p>Error state: <span data-type="inline-math" data-latex="\\nope{">\\nope{</span> keeps the source visible.</p>',
+  },
+};
+
+// ---------------------------------------------------------------------------
+// WithDetails (collapsible <details> sections)
+// ---------------------------------------------------------------------------
+
+export const WithDetails: Story = {
+  args: {
+    label: "Collapsible Section",
+    minHeight: 240,
+    helperText:
+      "GitLab-style <details>: toggle collapses content; markdown keeps it as raw HTML (lossless)",
+    defaultValue:
+      "<details open><summary>Deployment checklist</summary>" +
+      '<div data-type="detailsContent"><ul><li><p>Run the migration</p></li>' +
+      "<li><p>Flip the feature flag</p></li></ul></div></details>" +
+      "<p>Content after the section.</p>",
+  },
+};
+
+// ---------------------------------------------------------------------------
+// WithUploadHooks (prop-driven image/file upload)
+// ---------------------------------------------------------------------------
+
+export const WithUploadHooks: Story = {
+  args: {
+    label: "With Upload Hooks",
+    placeholder: "Paste or drop an image or file...",
+    minHeight: 200,
+    helperText: "onImageUpload / onFileUpload resolve fake URLs after a short delay",
+    onImageUpload: async (file: File) =>
+      new Promise<string>((resolve) =>
+        setTimeout(
+          () => resolve(`https://example.com/uploads/${encodeURIComponent(file.name)}`),
+          150,
+        ),
+      ),
+    onFileUpload: async (file: File) =>
+      new Promise<{ url: string; name?: string }>((resolve) =>
+        setTimeout(
+          () =>
+            resolve({
+              url: `https://example.com/files/${encodeURIComponent(file.name)}`,
+              name: file.name,
+            }),
+          150,
+        ),
+      ),
+  },
+};

package/src/RichEditor.tsx

@@ -15,6 +15,7 @@
 import {
   forwardRef,
   useCallback,
+  useEffect,
   useImperativeHandle,
   useMemo,
   useRef,
@@ -60,6 +61,18 @@ export interface RichEditorCombinedProps extends RichEditorProps {
   resizable?: boolean;
   /** Show word/character count status bar (default: true) */
   showStatusBar?: boolean;
+  /** Controlled fullscreen state (uncontrolled when omitted) */
+  fullscreen?: boolean;
+  /** Initial fullscreen state when uncontrolled (default: false) */
+  defaultFullscreen?: boolean;
+  /** Called when the fullscreen state changes */
+  onFullscreenChange?: (fullscreen: boolean) => void;
+  /**
+   * Native only: render the embedded inline editor instead of the
+   * preview + fullscreen edit modal. Ignored on web (the web editor is
+   * always inline; fullscreen is the toolbar toggle).
+   */
+  inlineEditing?: boolean;
 }
 
 // ===========================================================================
@@ -79,6 +92,10 @@ const RichEditorImpl = forwardRef<RichEditorRef, RichEditorCombinedProps>(
       hasError,
       editable = true,
       onStateChange,
+      fullscreen: fullscreenProp,
+      defaultFullscreen = false,
+      onFullscreenChange,
+      inlineEditing: _inlineEditing,
       ...editorProps
     },
     ref,
@@ -87,6 +104,10 @@ const RichEditorImpl = forwardRef<RichEditorRef, RichEditorCombinedProps>(
     const frameRef = useRef<HTMLElement>(null);
     const [editorState, setEditorState] = useState<EditorState>(defaultEditorState);
     const [editorMode, setEditorMode] = useState<EditorMode>("richtext");
+    const [internalFullscreen, setInternalFullscreen] = useState(defaultFullscreen);
+    const [linkDialogOpen, setLinkDialogOpen] = useState(false);
+
+    const fullscreen = fullscreenProp ?? internalFullscreen;
 
     const { knobProps } = useResolvedKnobs({
       component: "RichEditor",
@@ -102,7 +123,94 @@ const RichEditorImpl = forwardRef<RichEditorRef, RichEditorCombinedProps>(
       [onStateChange],
     );
 
-    useImperativeHandle(ref, () => internalRef.current!, []);
+    const handleFullscreenChange = useCallback(
+      (next: boolean) => {
+        setInternalFullscreen(next);
+        onFullscreenChange?.(next);
+      },
+      [onFullscreenChange],
+    );
+
+    // Escape exits fullscreen -- but open menus/dialogs get Escape first:
+    // popover content is still mounted while it dismisses on the same
+    // keydown (React unmounts async), so the presence check skips this
+    // handler until the next Escape. The slash menu stops propagation when
+    // it consumes Escape, so it never reaches here. defaultPrevented is NOT
+    // a usable signal -- ProseMirror preventDefaults Escape unconditionally
+    // whenever focus is inside the editor.
+    useEffect(() => {
+      if (!fullscreen || typeof document === "undefined") return undefined;
+      const handleKeyDown = (event: KeyboardEvent) => {
+        if (event.key !== "Escape") return;
+        const openOverlay = Array.from(
+          document.querySelectorAll<HTMLElement>(
+            '[role="dialog"], [role="menu"], [role="listbox"]',
+          ),
+        ).some((el) => el.getClientRects().length > 0);
+        if (openOverlay) return;
+        handleFullscreenChange(false);
+      };
+      document.addEventListener("keydown", handleKeyDown);
+      return () => document.removeEventListener("keydown", handleKeyDown);
+    }, [fullscreen, handleFullscreenChange]);
+
+    // Lock page scroll while fullscreen and clear any drag-resize inline
+    // height (ResizeHandle writes style.height, which would beat inset 0)
+    useEffect(() => {
+      if (!fullscreen || typeof document === "undefined") return undefined;
+      const frame = frameRef.current;
+      const prevHeight = frame?.style.height ?? "";
+      if (frame) frame.style.height = "";
+      const prevBodyOverflow = document.body.style.overflow;
+      const prevHtmlOverflow = document.documentElement.style.overflow;
+      // scrollbar-gutter: stable shrinks the initial containing block, which
+      // would leave a gutter-wide strip beside the fixed inset-0 frame
+      const prevGutter = document.documentElement.style.scrollbarGutter;
+      document.body.style.overflow = "hidden";
+      document.documentElement.style.overflow = "hidden";
+      document.documentElement.style.scrollbarGutter = "auto";
+      return () => {
+        document.body.style.overflow = prevBodyOverflow;
+        document.documentElement.style.overflow = prevHtmlOverflow;
+        document.documentElement.style.scrollbarGutter = prevGutter;
+        if (frame) frame.style.height = prevHeight;
+      };
+    }, [fullscreen]);
+
+    // Mod+K opens the link dialog (GitLab parity). Scoped to the editor
+    // frame so multiple editors on a page do not fight over the shortcut.
+    const showToolbarNow = showToolbar && editable && editorMode === "richtext";
+    useEffect(() => {
+      const frame = frameRef.current;
+      if (!frame || !showToolbarNow || typeof document === "undefined") return undefined;
+      const handleKeyDown = (event: KeyboardEvent) => {
+        if (!(event.metaKey || event.ctrlKey)) return;
+        if (event.altKey || event.shiftKey) return;
+        if (event.key.toLowerCase() !== "k") return;
+        event.preventDefault();
+        setLinkDialogOpen(true);
+      };
+      frame.addEventListener("keydown", handleKeyDown);
+      return () => frame.removeEventListener("keydown", handleKeyDown);
+    }, [showToolbarNow]);
+
+    // Delegate per call — a frozen `internalRef.current` snapshot would bind
+    // the first render's methods, where the Tiptap editor is still null
+    // (immediatelyRender: false), leaving every host-facing method a no-op.
+    useImperativeHandle(
+      ref,
+      () => ({
+        executeCommand: (command, payload) => internalRef.current?.executeCommand(command, payload),
+        getState: () => internalRef.current?.getState() ?? defaultEditorState,
+        getHTML: () => internalRef.current?.getHTML() ?? "",
+        getJSON: () => internalRef.current?.getJSON() ?? null,
+        setHTML: (html) => internalRef.current?.setHTML(html),
+        setJSON: (json) => internalRef.current?.setJSON(json),
+        focus: () => internalRef.current?.focus(),
+        blur: () => internalRef.current?.blur(),
+      }),
+      [],
+    );
 
     const cappedRadius = clampRadiusForLargeComponent(knobProps.borderRadius.borderRadius, 4);
 
@@ -130,19 +238,24 @@ const RichEditorImpl = forwardRef<RichEditorRef, RichEditorCombinedProps>(
         <EditorFrame
           ref={frameRef as any}
           hasError={hasError}
-          borderRadius={cappedRadius}
-          borderWidth={knobProps.borderRadius.borderWidth}
+          borderRadius={fullscreen ? 0 : cappedRadius}
+          borderWidth={fullscreen ? 0 : knobProps.borderRadius.borderWidth}
           borderColor={hasError ? "$red10" : "$color6"}
-          backgroundColor={knobProps.inputBackground ?? "$color2"}
+          backgroundColor={fullscreen ? "$background" : (knobProps.inputBackground ?? "$color2")}
           disabled={disabled}
-          position="relative"
+          position={fullscreen ? ("fixed" as any) : "relative"}
+          {...(fullscreen && { top: 0, left: 0, right: 0, bottom: 0, zIndex: 100000 })}
         >
-          {showToolbar && !disabled && editorMode === "richtext" && (
+          {showToolbarNow && (
             <FixedToolbar
               editorRef={internalRef}
               state={editorState}
               sections={sections}
               hasError={hasError}
+              fullscreen={fullscreen}
+              onFullscreenToggle={() => handleFullscreenChange(!fullscreen)}
+              linkDialogOpen={linkDialogOpen}
+              onLinkDialogOpenChange={setLinkDialogOpen}
             />
           )}
           <TiptapEditor
@@ -155,11 +268,12 @@ const RichEditorImpl = forwardRef<RichEditorRef, RichEditorCombinedProps>(
             bodyFontFamily={bodyFontFamily}
             headingFontFamily={headingFontFamily}
             editorMode={editorMode}
+            fullscreen={fullscreen}
           />
           {showStatusBar && (
             <StatusBar state={editorState} mode={editorMode} onModeChange={setEditorMode} />
           )}
-          {resizable && !disabled && (
+          {resizable && !disabled && !fullscreen && (
             <ResizeHandle
               containerRef={frameRef as RefObject<HTMLElement>}
               minHeight={editorProps.minHeight ?? 150}

package/src/RichTextEditor/index.tsx

@@ -27,9 +27,9 @@ import {
   type FieldComponentProps,
   type Validator,
 } from "@multiplatform.one/forms";
-import type { ToolbarSection } from "../types";
-import type { RichEditorRef } from "../types";
+import type { RichEditorRef, RichTextMentionOptions, ToolbarSection } from "../types";
 import { RichEditor } from "../RichEditor";
+import { t } from "../shared/t";
 
 // ---------------------------------------------------------------------------
 // Custom empty check for rich text
@@ -86,6 +86,29 @@ export type RichTextEditorProps<
     sections?: ToolbarSection[];
     /** When true, renders a skeleton placeholder instead of the editor */
     skeleton?: boolean;
+    /** Controlled fullscreen state (web; uncontrolled when omitted) */
+    fullscreen?: boolean;
+    /** Initial fullscreen state when uncontrolled (default: false) */
+    defaultFullscreen?: boolean;
+    /** Called when the fullscreen state changes */
+    onFullscreenChange?: (fullscreen: boolean) => void;
+    /**
+     * Native only: render the embedded inline editor instead of the
+     * preview + fullscreen edit modal (ignored on web)
+     */
+    inlineEditing?: boolean;
+    /**
+     * Uploads a pasted/dropped image and resolves its URL (web). Without it,
+     * images are inlined as base64 data URIs.
+     */
+    onImageUpload?: (file: File) => Promise<string>;
+    /**
+     * Uploads a pasted/dropped non-image file and resolves its URL (web).
+     * Inserts an attachment chip link; without it, non-image files are ignored.
+     */
+    onFileUpload?: (file: File) => Promise<{ url: string; name?: string }>;
+    /** Enables the @ mention suggestion popup (web) */
+    mentions?: RichTextMentionOptions;
   };
 
 // ---------------------------------------------------------------------------
@@ -102,7 +125,7 @@ export function RichTextEditor<
   const {
     defaultValue = "",
     form,
-    placeholder = "Write something...",
+    placeholder: placeholderProp,
     disabled,
     readOnly,
     minHeight = 150,
@@ -125,9 +148,17 @@ export function RichTextEditor<
     showBubbleToolbar = false,
     sections,
     skeleton,
+    fullscreen,
+    defaultFullscreen,
+    onFullscreenChange,
+    inlineEditing,
+    onImageUpload,
+    onFileUpload,
+    mentions,
     ..._restProps
   } = props;
 
+  const placeholder = placeholderProp ?? t("Write something...");
   const { resolvedForm, knobProps, id } = useFormField({ form });
   const resolvedValidators = useResolvedValidators(
     required,
@@ -182,6 +213,13 @@ export function RichTextEditor<
         hasError={hasError}
         size={size}
         compact={compact}
+        fullscreen={fullscreen}
+        defaultFullscreen={defaultFullscreen}
+        onFullscreenChange={onFullscreenChange}
+        inlineEditing={inlineEditing}
+        onImageUpload={onImageUpload}
+        onFileUpload={onFileUpload}
+        mentions={mentions}
       />
     );
   };

package/src/RichTextEditor/richTextEditor.spec.tsx

@@ -4,8 +4,9 @@ import { describe, it, expect, vi } from "vitest";
 // Mocks -- must come before imports
 // ---------------------------------------------------------------------------
 
-vi.mock("@multiplatform.one/forms", () => {
+vi.mock("@multiplatform.one/forms", async (importOriginal) => {
   return {
+    ...(await importOriginal<Record<string, unknown>>()),
     Field: ({ children, ...props }: any) => {
       const field = {
         state: { value: props.defaultValue ?? "", meta: { errors: [] } },
@@ -57,7 +58,7 @@ vi.mock("@multiplatform.one/forms", () => {
       isEmpty?: (v: unknown) => boolean,
     ) => {
       if (!required) return validators;
-      const check = isEmpty || ((v: unknown) => v == null || v === "");
+      const check = isEmpty || ((v: unknown) => v === null || v === undefined || v === "");
       const requiredValidator = ({ value }: { value: unknown }) =>
         check(value)
           ? `${typeof label === "string" ? label : name || "Field"} is required`
@@ -84,11 +85,13 @@ vi.mock("@multiplatform.one/forms", () => {
   };
 });
 
-vi.mock("@multiplatform.one/components", () => ({
+vi.mock("@multiplatform.one/components", async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
   Tooltip: ({ children }: any) => children,
 }));
 
-vi.mock("@multiplatform.one/theme", () => ({
+vi.mock("@multiplatform.one/theme", async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
   useResolvedKnobs: () => ({
     knobProps: {
       body: {},
@@ -132,6 +135,10 @@ const mockEditor = {
     blur: vi.fn(),
   },
   setEditable: vi.fn(),
+  storage: {
+    mediaUpload: { handlers: {} },
+    suggestionChrome: { value: null },
+  },
 };
 
 vi.mock("@tiptap/react", () => ({

package/src/constants.ts

@@ -5,40 +5,102 @@
 import type { NativeCapability } from "./types";
 
 // ===========================================================================
-// Color Palettes
+// Color Palettes (Axiom 5 ONE SOURCE: theme ramp tokens, never fixed hexes)
 // ===========================================================================
 
 export interface ColorEntry {
   /** Display name for the color */
   name: string;
-  /** Hex color value, or null for default/none */
+  /** CSS color value (theme custom property on web), or null for default/none */
   value: string | null;
 }
 
-export const TEXT_COLORS: ColorEntry[] = [
-  { name: "Default", value: null },
-  { name: "Black", value: "#000000" },
-  { name: "Dark Gray", value: "#4a4a4a" },
-  { name: "Gray", value: "#9b9b9b" },
-  { name: "Red", value: "#e53935" },
-  { name: "Orange", value: "#fb8c00" },
-  { name: "Yellow", value: "#fdd835" },
-  { name: "Green", value: "#43a047" },
-  { name: "Blue", value: "#1e88e5" },
-  { name: "Purple", value: "#8e24aa" },
-  { name: "Pink", value: "#d81b60" },
+/** A palette entry backed by a theme token instead of a literal color */
+export interface ColorTokenEntry {
+  /** Display name for the color */
+  name: string;
+  /** Theme token key (e.g. "red11"), or null for default/none */
+  token: string | null;
+}
+
+/**
+ * Hue swatches ride the radix step-11 text ramps: legible (>=4.5:1) on the
+ * step-1/2 editor surface in BOTH schemes, so the same token list serves
+ * light and dark. `color12` is the house strong ink (near-black in light,
+ * near-white in dark).
+ */
+const TEXT_COLOR_HUES: ColorTokenEntry[] = [
+  { name: "Gray", token: "gray11" },
+  { name: "Red", token: "red11" },
+  { name: "Orange", token: "orange11" },
+  { name: "Yellow", token: "yellow11" },
+  { name: "Green", token: "green11" },
+  { name: "Blue", token: "blue11" },
+  { name: "Purple", token: "purple11" },
+  { name: "Pink", token: "pink11" },
+];
+
+export const TEXT_COLOR_TOKENS: ColorTokenEntry[] = [
+  { name: "Default", token: null },
+  // color12 resolves near-black in light schemes; the label states what renders
+  { name: "Black", token: "color12" },
+  ...TEXT_COLOR_HUES,
+];
+
+/**
+ * Dark-scheme display names for the same tokens: the values are identical
+ * (theme vars re-resolve per scheme) — only the neutral ink's honest label
+ * flips (color12 renders near-white in dark).
+ */
+export const TEXT_COLOR_TOKENS_DARK: ColorTokenEntry[] = [
+  { name: "Default", token: null },
+  { name: "White", token: "color12" },
+  ...TEXT_COLOR_HUES,
+];
+
+/**
+ * Highlight washes ride the radix step-5 component backgrounds: pastel in
+ * light, deep-dim in dark — the scheme's own ink (color12, inherited by the
+ * mark) stays legible on them in both schemes.
+ */
+export const HIGHLIGHT_COLOR_TOKENS: ColorTokenEntry[] = [
+  { name: "None", token: null },
+  { name: "Yellow", token: "yellow5" },
+  { name: "Green", token: "green5" },
+  { name: "Blue", token: "blue5" },
+  { name: "Pink", token: "pink5" },
+  { name: "Purple", token: "purple5" },
+  { name: "Orange", token: "orange5" },
+  { name: "Red", token: "red5" },
+  { name: "Cyan", token: "cyan5" },
 ];
 
-export const HIGHLIGHT_COLORS: ColorEntry[] = [
-  { name: "None", value: null },
-  { name: "Yellow", value: "#fff59d" },
-  { name: "Green", value: "#c8e6c9" },
-  { name: "Blue", value: "#bbdefb" },
-  { name: "Pink", value: "#f8bbd9" },
-  { name: "Purple", value: "#e1bee7" },
-  { name: "Orange", value: "#ffe0b2" },
-  { name: "Red", value: "#ffcdd2" },
-  { name: "Cyan", value: "#b2ebf2" },
+/**
+ * Web palette values are CSS custom properties: applied color marks re-resolve
+ * live from the ambient theme, so content authored in one scheme stays legible
+ * when the scheme flips. Native pickers resolve the same tokens via useTheme()
+ * (see ColorPicker.native), and TentapEditor injects the resolved vars into
+ * the 10Tap webview so cross-authored content renders there too.
+ */
+const toCssVarEntry = ({ name, token }: ColorTokenEntry): ColorEntry => ({
+  name,
+  value: token ? `var(--${token})` : null,
+});
+
+export const TEXT_COLORS: ColorEntry[] = TEXT_COLOR_TOKENS.map(toCssVarEntry);
+export const TEXT_COLORS_DARK: ColorEntry[] = TEXT_COLOR_TOKENS_DARK.map(toCssVarEntry);
+export const HIGHLIGHT_COLORS: ColorEntry[] = HIGHLIGHT_COLOR_TOKENS.map(toCssVarEntry);
+
+/**
+ * Every theme token the palettes reference — the single list used to inject
+ * resolved CSS custom properties into the native 10Tap webview.
+ */
+export const PALETTE_THEME_TOKENS: string[] = [
+  ...new Set(
+    [...TEXT_COLOR_TOKENS, ...HIGHLIGHT_COLOR_TOKENS]
+      .map((entry) => entry.token)
+      .filter((token): token is string => token !== null),
+  ),
 ];
 
 // ===========================================================================

package/src/editor/BlockDragHandle.ts

@@ -8,13 +8,38 @@ import { Extension } from "@tiptap/core";
 import { Plugin, PluginKey, NodeSelection } from "@tiptap/pm/state";
 
 const HANDLE_WIDTH = 20;
-const HANDLE_HTML = `<svg width="14" height="14" viewBox="0 0 14 14" fill="currentColor" opacity="0.35"><circle cx="4" cy="3" r="1.2"/><circle cx="10" cy="3" r="1.2"/><circle cx="4" cy="7" r="1.2"/><circle cx="10" cy="7" r="1.2"/><circle cx="4" cy="11" r="1.2"/><circle cx="10" cy="11" r="1.2"/></svg>`;
+const SVG_NS = "http://www.w3.org/2000/svg";
+const GRIP_DOTS: Array<[number, number]> = [
+  [4, 3],
+  [10, 3],
+  [4, 7],
+  [10, 7],
+  [4, 11],
+  [10, 11],
+];
+
+function createGripIcon(): SVGSVGElement {
+  const svg = document.createElementNS(SVG_NS, "svg");
+  svg.setAttribute("width", "14");
+  svg.setAttribute("height", "14");
+  svg.setAttribute("viewBox", "0 0 14 14");
+  svg.setAttribute("fill", "currentColor");
+  svg.setAttribute("opacity", "0.35");
+  for (const [cx, cy] of GRIP_DOTS) {
+    const circle = document.createElementNS(SVG_NS, "circle");
+    circle.setAttribute("cx", String(cx));
+    circle.setAttribute("cy", String(cy));
+    circle.setAttribute("r", "1.2");
+    svg.appendChild(circle);
+  }
+  return svg;
+}
 
 function createHandleElement(): HTMLDivElement {
   const el = document.createElement("div");
   el.className = "block-drag-handle";
   el.draggable = true;
-  el.innerHTML = HANDLE_HTML;
+  el.appendChild(createGripIcon());
   Object.assign(el.style, {
     position: "absolute",
     width: `${HANDLE_WIDTH}px`,
@@ -25,7 +50,8 @@ function createHandleElement(): HTMLDivElement {
     cursor: "grab",
     borderRadius: "4px",
     opacity: "0",
-    transition: "opacity 0.15s",
+    // decorative fade lives in editorStyles CSS, driven by the motion knob
+    // (animation none silences it); direct drag stays instant either way
     zIndex: "10",
     userSelect: "none",
   });
@@ -36,7 +62,6 @@ export const BlockDragHandle = Extension.create({
   name: "blockDragHandle",
 
   addProseMirrorPlugins() {
-    const { editor } = this;
     let handle: HTMLDivElement | null = null;
     let currentBlockPos: number | null = null;
 
@@ -104,7 +129,7 @@ export const BlockDragHandle = Extension.create({
           };
 
           const onDragStart = (event: DragEvent) => {
-            if (currentBlockPos == null) return;
+            if (currentBlockPos === null) return;
             const node = editorView.state.doc.nodeAt(currentBlockPos);
             if (!node) return;