@agent-native/core 0.101.10 → 0.101.11

package/corpus/templates/content/.agents/skills/document-editing/SKILL.md

@@ -145,6 +145,29 @@ Always run this after any document modification to update the sidebar.
 
 Documents use **markdown** for content. The editor renders markdown in real time.
 
+### Math
+
+Content renders LaTeX with KaTeX while preserving the source in NFM. Use the
+canonical Content delimiters when an agent creates or edits math:
+
+```md
+Inline math: The relationship is $`E = mc^2`$ in this example.
+
+Block math:
+
+$$
+\int_0^1 x^2 dx = \frac{1}{3}
+$$
+```
+
+- Inline math uses ``$`...`$``. Do not substitute ordinary `$...$`; dollar
+  amounts in prose are intentionally not interpreted as equations.
+- Block equations use `$$` on their own lines before and after the LaTeX.
+- Keep the raw LaTeX intact when editing around an equation. Invalid or
+  unsupported expressions remain visible as source so they can be repaired.
+- Markdown exports preserve these delimiters. HTML and PDF-ready exports render
+  the equation.
+
 ## Parent-Child Hierarchy
 
 Documents form a tree via `parent_id`:

package/corpus/templates/content/app/components/editor/MathRenderer.tsx

@@ -0,0 +1,43 @@
+import { renderMathToHtml } from "@shared/math-rendering";
+import { useMemo } from "react";
+
+interface MathRendererProps {
+  latex: string;
+  displayMode: boolean;
+}
+
+export function MathRenderer({ latex, displayMode }: MathRendererProps) {
+  const rendered = useMemo(
+    () => renderMathToHtml(latex, displayMode),
+    [displayMode, latex],
+  );
+
+  if (!rendered.ok) {
+    return (
+      <code
+        className={
+          displayMode
+            ? "content-math-error content-math-error--block"
+            : "content-math-error content-math-error--inline"
+        }
+        title={rendered.error}
+      >
+        {latex || "Empty equation"}
+      </code>
+    );
+  }
+
+  return displayMode ? (
+    <span
+      className="content-math content-math--block"
+      contentEditable={false}
+      dangerouslySetInnerHTML={{ __html: rendered.html }}
+    />
+  ) : (
+    <span
+      className="content-math content-math--inline"
+      contentEditable={false}
+      dangerouslySetInnerHTML={{ __html: rendered.html }}
+    />
+  );
+}

package/corpus/templates/content/app/components/editor/SlashCommandMenu.tsx

@@ -1,8 +1,10 @@
 import { useSendToAgentChat, useT } from "@agent-native/core/client";
 import type { CreateInlineDatabaseResponse } from "@shared/api";
+import { renderMathToHtml } from "@shared/math-rendering";
 import { collapseExactRepeatedNfm, docToNfm } from "@shared/nfm";
 import { serializeRegistryBlockToMdx } from "@shared/nfm-registry";
 import {
+  IconCheck,
   IconTypography,
   IconH1,
   IconH2,
@@ -23,6 +25,8 @@ import {
   IconFileText,
   IconDatabase,
   IconVideo,
+  IconMathFunction,
+  IconSquareRoot2,
 } from "@tabler/icons-react";
 import { Editor } from "@tiptap/react";
 import { useState, useEffect, useCallback, useRef, useMemo } from "react";
@@ -30,6 +34,7 @@ import { useNavigate } from "react-router";
 import { toast } from "sonner";
 
 import { contentBlockRegistry } from "@/blocks/contentBlockRegistry";
+import { Button } from "@/components/ui/button";
 import {
   Popover,
   PopoverContent,
@@ -42,6 +47,7 @@ import { localContentComponents } from "@/local-components";
 
 import { focusMostRecentEmptyToggleSummary } from "./extensions/NotionExtensions";
 import { buildLocalComponentSlashItems } from "./localComponentSlashItems";
+import { MathRenderer } from "./MathRenderer";
 import { buildRegistrySlashItems } from "./registrySlashItems";
 
 interface SlashCommandMenuProps {
@@ -64,6 +70,13 @@ interface EditorMenuPosition {
   left: number;
 }
 
+interface EquationDraft {
+  displayMode: boolean;
+  insertionRange: { from: number; to: number };
+  slashRange: { from: number; to: number };
+  position: EditorMenuPosition;
+}
+
 interface CommandItem {
   title: string;
   description: string;
@@ -178,6 +191,47 @@ export function insertInlineDatabaseBlock(
     : chain.insertContent(content).run();
 }
 
+export function equationNodeContent(latex: string, displayMode: boolean) {
+  return displayMode
+    ? {
+        type: "notionBlockAtom",
+        attrs: { tagName: "equation", attrsJson: "{}", label: latex },
+      }
+    : {
+        type: "notionInlineAtom",
+        attrs: { tagName: "math", attrsJson: "{}", label: latex },
+      };
+}
+
+export function insertEquation(
+  editor: Editor,
+  latex: string,
+  displayMode: boolean,
+  range: { from: number; to: number },
+) {
+  const content = equationNodeContent(latex, displayMode);
+  return editor
+    .chain()
+    .focus()
+    .insertContentAt(
+      range,
+      displayMode ? [content, { type: "paragraph" }] : content,
+    )
+    .run();
+}
+
+export function getEquationInsertionRange(
+  editor: Editor,
+  slashRange: { from: number; to: number },
+  displayMode: boolean,
+) {
+  if (!displayMode) return slashRange;
+  const resolved = editor.state.doc.resolve(slashRange.from);
+  return resolved.parent.isTextblock
+    ? { from: resolved.before(), to: resolved.after() }
+    : slashRange;
+}
+
 const commands: CommandTemplate[] = [
   {
     titleKey: "editor.slash.text",
@@ -460,6 +514,16 @@ export function SlashCommandMenu({
   );
   const generateTextareaRef = useRef<HTMLTextAreaElement>(null);
 
+  const [equationDraft, setEquationDraft] = useState<EquationDraft | null>(
+    null,
+  );
+  const [equationLatex, setEquationLatex] = useState("");
+  const equationInputRef = useRef<HTMLTextAreaElement>(null);
+  const equationResult = useMemo(
+    () => renderMathToHtml(equationLatex, equationDraft?.displayMode ?? false),
+    [equationDraft?.displayMode, equationLatex],
+  );
+
   const submitGeneratePrompt = useCallback(
     (prompt: string) => {
       const trimmed = prompt.trim();
@@ -684,6 +748,80 @@ export function SlashCommandMenu({
     },
   };
 
+  const openEquationComposer = useCallback(
+    (displayMode: boolean, slashRange: { from: number; to: number } | null) => {
+      const menuPosition = position ?? getSelectionMenuPosition();
+      if (!slashRange || !menuPosition) return false;
+      setEquationLatex("");
+      setEquationDraft({
+        displayMode,
+        slashRange,
+        insertionRange: getEquationInsertionRange(
+          editor,
+          slashRange,
+          displayMode,
+        ),
+        position: menuPosition,
+      });
+      setTimeout(() => equationInputRef.current?.focus(), 0);
+      return true;
+    },
+    [editor, getSelectionMenuPosition, position],
+  );
+
+  const cancelEquation = useCallback(() => {
+    const draft = equationDraft;
+    setEquationDraft(null);
+    setEquationLatex("");
+    if (draft) {
+      editor.chain().focus().deleteRange(draft.slashRange).run();
+    }
+  }, [editor, equationDraft]);
+
+  const submitEquation = useCallback(() => {
+    if (!equationDraft || !equationResult.ok) return;
+    const latex = equationLatex.trim();
+    const { displayMode, insertionRange } = equationDraft;
+    setEquationDraft(null);
+    setEquationLatex("");
+    const inserted = insertEquation(editor, latex, displayMode, insertionRange);
+    if (!inserted) {
+      toast.error(t("editor.slash.equationInsertFailed"));
+      return;
+    }
+    void onDraftCommitted?.();
+  }, [
+    editor,
+    equationDraft,
+    equationLatex,
+    equationResult.ok,
+    onDraftCommitted,
+    t,
+  ]);
+
+  const equationCommands: CommandItem[] = isTurnInto
+    ? []
+    : [
+        {
+          title: t("editor.slash.blockEquation"),
+          description: t("editor.slash.blockEquationDescription"),
+          searchText: "latex katex math formula",
+          icon: IconMathFunction,
+          preserveSlashRange: true,
+          action: (_editor, { slashRange }) =>
+            openEquationComposer(true, slashRange),
+        },
+        {
+          title: t("editor.slash.inlineEquation"),
+          description: t("editor.slash.inlineEquationDescription"),
+          searchText: "latex katex math formula",
+          icon: IconSquareRoot2,
+          preserveSlashRange: true,
+          action: (_editor, { slashRange }) =>
+            openEquationComposer(false, slashRange),
+        },
+      ];
+
   // Registry-derived block items (the shared dev-doc / OpenAPI / structured
   // library). Filtered to Notion-compatible specs when the document is linked to
   // a Notion page. "Turn into" only converts the current text block, so these
@@ -713,9 +851,10 @@ export function SlashCommandMenu({
     title: t(cmd.titleKey),
     description: t(cmd.descriptionKey),
   });
-  const blockCommands = (isTurnInto ? turnIntoCommands : commands).map(
-    localizeCommand,
-  );
+  const blockCommands = [
+    ...(isTurnInto ? turnIntoCommands : commands).map(localizeCommand),
+    ...equationCommands,
+  ];
   const pageCommands = isTurnInto ? [] : [pageCommand, databaseCommand];
   const mediaCommands = isTurnInto
     ? []
@@ -1042,7 +1181,7 @@ export function SlashCommandMenu({
             align="start"
             side="bottom"
             className="w-[calc(100vw-2rem)] max-w-80 rounded-xl p-0"
-            onOpenAutoFocus={(e) => {
+            onOpenAutoFocus={(e: Event) => {
               e.preventDefault();
               generateTextareaRef.current?.focus();
             }}
@@ -1086,6 +1225,123 @@ export function SlashCommandMenu({
           </PopoverContent>
         </Popover>
       )}
+
+      {equationDraft && (
+        <Popover
+          open
+          onOpenChange={(open: boolean) => {
+            if (!open) cancelEquation();
+          }}
+        >
+          <PopoverTrigger asChild>
+            <span
+              className="pointer-events-none absolute size-0"
+              style={{
+                top: equationDraft.position.top,
+                left: Math.min(equationDraft.position.left, 16),
+              }}
+            />
+          </PopoverTrigger>
+          <PopoverContent
+            align="start"
+            side="bottom"
+            className="w-[calc(100vw-2rem)] max-w-md rounded-xl p-0"
+            onOpenAutoFocus={(event: Event) => {
+              event.preventDefault();
+              equationInputRef.current?.focus();
+            }}
+          >
+            <div className="p-4">
+              <div className="flex items-center gap-2 text-sm font-semibold">
+                {equationDraft.displayMode ? (
+                  <IconMathFunction
+                    className="text-muted-foreground"
+                    size={16}
+                  />
+                ) : (
+                  <IconSquareRoot2
+                    className="text-muted-foreground"
+                    size={16}
+                  />
+                )}
+                {equationDraft.displayMode
+                  ? t("editor.slash.blockEquation")
+                  : t("editor.slash.inlineEquation")}
+              </div>
+              <textarea
+                ref={equationInputRef}
+                value={equationLatex}
+                onChange={(event) => setEquationLatex(event.target.value)}
+                onKeyDown={(event) => {
+                  if (
+                    event.key === "Enter" &&
+                    (event.metaKey || event.ctrlKey) &&
+                    equationResult.ok
+                  ) {
+                    event.preventDefault();
+                    submitEquation();
+                  }
+                  if (event.key === "Escape") {
+                    event.preventDefault();
+                    cancelEquation();
+                  }
+                }}
+                rows={equationDraft.displayMode ? 3 : 2}
+                placeholder={t("editor.slash.equationPlaceholder")}
+                aria-label={t("editor.slash.equationInputLabel")}
+                aria-invalid={equationLatex.length > 0 && !equationResult.ok}
+                aria-describedby="equation-preview-status"
+                className="mt-3 w-full resize-y rounded-lg border border-input bg-background px-3 py-2 font-mono text-sm outline-none focus-visible:ring-2 focus-visible:ring-ring"
+              />
+              <div className="mt-3 min-h-20 rounded-lg border border-border bg-muted/30 p-3">
+                <div className="mb-2 text-[11px] font-medium uppercase tracking-wide text-muted-foreground">
+                  {t("editor.slash.equationPreview")}
+                </div>
+                <div className="flex min-h-9 items-center justify-center overflow-x-auto text-foreground">
+                  {equationResult.ok ? (
+                    <MathRenderer
+                      latex={equationLatex}
+                      displayMode={equationDraft.displayMode}
+                    />
+                  ) : (
+                    <span className="text-sm text-muted-foreground">
+                      {equationLatex
+                        ? t("editor.slash.equationNeedsRepair")
+                        : t("editor.slash.equationPreviewEmpty")}
+                    </span>
+                  )}
+                </div>
+              </div>
+              <p
+                id="equation-preview-status"
+                className={cn(
+                  "mt-2 min-h-5 text-xs",
+                  equationLatex && !equationResult.ok
+                    ? "text-destructive"
+                    : "text-muted-foreground",
+                )}
+              >
+                {equationLatex && !equationResult.ok
+                  ? equationResult.error
+                  : t("editor.slash.equationSubmitHint")}
+              </p>
+            </div>
+            <div className="flex items-center justify-end gap-2 border-t border-border px-4 py-3">
+              <Button variant="ghost" size="sm" onClick={cancelEquation}>
+                {t("editor.slash.cancelEquation")}
+              </Button>
+              <Button
+                size="sm"
+                onClick={submitEquation}
+                disabled={!equationResult.ok}
+              >
+                <IconCheck />
+                {t("editor.slash.insertEquation")}
+              </Button>
+            </div>
+          </PopoverContent>
+        </Popover>
+      )}
     </>
   );
 }

package/corpus/templates/content/app/components/editor/extensions/NotionExtensions.tsx

@@ -1,3 +1,4 @@
+import { findTrailingPlainInlineMath } from "@shared/inline-math";
 import {
   escapeHtml,
   indentMarkdown,
@@ -10,6 +11,7 @@ import {
   IconExternalLink,
   IconFileText,
 } from "@tabler/icons-react";
+import { InputRule } from "@tiptap/core";
 import type { Fragment, Node as ProseMirrorNode } from "@tiptap/pm/model";
 import {
   Mark,
@@ -21,6 +23,8 @@ import {
   type NodeViewProps,
 } from "@tiptap/react";
 
+import { MathRenderer } from "../MathRenderer";
+
 const BLOCK_ATOM_TAGS = [
   "page",
   "database",
@@ -452,6 +456,17 @@ function BlockAtomView({ node, extension }: NodeViewProps) {
   const canOpenLocalPage = Boolean(pageLink && options.onOpenPageLink);
   const externalUrl = safeExternalPageUrl(attrs.url || attrs.href || null);
 
+  if (tagName === "equation") {
+    return (
+      <NodeViewWrapper
+        className="content-equation"
+        data-latex={label || attrs.latex || ""}
+      >
+        <MathRenderer latex={label || attrs.latex || ""} displayMode={true} />
+      </NodeViewWrapper>
+    );
+  }
+
   if (tagName === "page") {
     const openPage = () => {
       if (pageLink && options.onOpenPageLink) {
@@ -511,6 +526,36 @@ function BlockAtomView({ node, extension }: NodeViewProps) {
   );
 }
 
+function InlineAtomView({ node }: NodeViewProps) {
+  const tagName = (node.attrs.tagName || "mention") as string;
+  const label = (node.attrs.label || "") as string;
+  const attrs = parseAttrsJson(node.attrs.attrsJson as string);
+
+  if (tagName === "math") {
+    const latex = label || attrs.latex || "";
+    return (
+      <NodeViewWrapper
+        as="span"
+        className="content-inline-equation"
+        contentEditable={false}
+        data-latex={latex}
+      >
+        <MathRenderer latex={latex} displayMode={false} />
+      </NodeViewWrapper>
+    );
+  }
+
+  return (
+    <NodeViewWrapper
+      as="span"
+      className="notion-inline-atom"
+      contentEditable={false}
+    >
+      {label || humanizeTag(tagName)}
+    </NodeViewWrapper>
+  );
+}
+
 export const NotionSpanMark = Mark.create({
   name: "notionSpan",
 
@@ -975,6 +1020,35 @@ export const NotionInlineAtom = Node.create({
   atom: true,
   selectable: false,
 
+  addInputRules() {
+    return [
+      new InputRule({
+        find: (text) => {
+          const match = findTrailingPlainInlineMath(text);
+          if (!match) return null;
+          return {
+            index: match.from,
+            text: text.slice(match.from, match.to),
+            data: { latex: match.latex },
+          };
+        },
+        handler: ({ state, range, match }) => {
+          const latex = match.data?.latex;
+          if (typeof latex !== "string") return null;
+
+          const mathNode = state.schema.nodes.notionInlineAtom?.create({
+            tagName: "math",
+            attrsJson: "{}",
+            label: latex,
+          });
+          if (!mathNode) return null;
+
+          state.tr.replaceWith(range.from, range.to, mathNode).scrollIntoView();
+        },
+      }),
+    ];
+  },
+
   addAttributes() {
     return {
       tagName: { default: "mention-user" },
@@ -1023,6 +1097,10 @@ export const NotionInlineAtom = Node.create({
     ];
   },
 
+  addNodeView() {
+    return ReactNodeViewRenderer(InlineAtomView);
+  },
+
   addStorage() {
     return {
       markdown: {

package/corpus/templates/content/app/global.css

@@ -1218,6 +1218,59 @@ div[data-notion-column] > :last-child {
   white-space: nowrap;
 }
 
+.content-inline-equation {
+  display: inline-block;
+  max-width: 100%;
+  margin: 0 0.08em;
+  vertical-align: -0.08em;
+}
+
+.content-equation {
+  display: block;
+  max-width: 100%;
+  margin: 1em 0;
+  overflow-x: auto;
+  padding: 0.25rem 0;
+}
+
+.content-math {
+  color: inherit;
+}
+
+.content-math--inline {
+  display: inline-block;
+}
+
+.content-math--block {
+  display: block;
+  min-width: max-content;
+  text-align: center;
+}
+
+.content-math-error {
+  border: 1px solid hsl(var(--destructive) / 0.3);
+  border-radius: 0.375rem;
+  background: hsl(var(--destructive) / 0.06);
+  color: hsl(var(--foreground));
+  font-family:
+    "JetBrains Mono Variable", ui-monospace, SFMono-Regular, Menlo, Consolas,
+    monospace;
+  white-space: pre-wrap;
+}
+
+.content-math-error--inline {
+  padding: 0.05rem 0.25rem;
+  font-size: 0.9em;
+}
+
+.content-math-error--block {
+  display: block;
+  width: 100%;
+  padding: 0.75rem 0.9rem;
+  overflow-wrap: anywhere;
+  text-align: left;
+}
+
 .notion-editor span[data-notion-span="true"][underline="true"] {
   text-decoration: underline;
   text-underline-offset: 3px;

package/corpus/templates/content/app/i18n/zh-TW.ts

@@ -393,6 +393,8 @@ const messages = {
       audio: "音訊",
       audioDescription: "上傳或嵌入音訊",
       basicBlocks: "基本塊",
+      blockEquation: "區塊公式",
+      blockEquationDescription: "在獨立一行顯示 LaTeX 公式",
       blocks: "積木",
       bulletedList: "專案符號清單",
       bulletedListDescription: "無序清單",
@@ -403,6 +405,7 @@ const messages = {
       collapsibleBlockDescription: "可折疊塊",
       database: "資料庫",
       databaseDescription: "此頁面中的內嵌資料庫",
+      cancelEquation: "取消",
       divider: "分頻器",
       dividerDescription: "水平尺",
       generate: "生成",
@@ -413,6 +416,9 @@ const messages = {
       heading4Description: "副標題",
       image: "圖片",
       imageDescription: "上傳或嵌入圖片",
+      inlineEquation: "行內公式",
+      inlineEquationDescription: "在文字中加入 LaTeX 公式",
+      insertEquation: "插入",
       localComponents: "本機元件",
       media: "媒體",
       numberedList: "編號清單",
@@ -420,6 +426,13 @@ const messages = {
       page: "頁面",
       pageDescription: "建立子頁面",
       pages: "頁面數",
+      equationInputLabel: "LaTeX 公式",
+      equationInsertFailed: "無法插入公式。",
+      equationNeedsRepair: "請修正 LaTeX 以查看預覽。",
+      equationPlaceholder: String.raw`輸入 LaTeX，例如 \frac{a}{b}`,
+      equationPreview: "預覽",
+      equationPreviewEmpty: "公式將顯示於此。",
+      equationSubmitHint: "輸入時會即時更新預覽。按 Cmd/Ctrl+Enter 插入。",
       quote: "報價",
       quoteDescription: "塊報價",
       table: "表",