@godxjp/markdown 31.26.2 → 31.28.0

package/README.md

@@ -53,6 +53,69 @@ Images: wrap the body in `<Prose imagePreview>` and every body image opens the k
 through the others — no `img` override needed. Images in table cells keep min(natural width, 20rem),
 so a narrow table scrolls instead of squashing them.
 
+## Grammar v1 and the codec (`@godxjp/markdown/codec`)
+
+The renderer (`RENDERER_VERSION` 4), the codec and `@godxjp/block-editor` read one syntax, from one
+set of parsers, so a body means the same thing in the editor, on a server and on the page.
+
+### Syntax
+
+- **GFM** — tables, task lists, strikethrough, autolinks, footnotes.
+- **CJK-friendly emphasis** — `の**「強調」**です` is strong. CommonMark's flanking rules leave
+  literal asterisks next to 、。「」（）; the codec, the renderer and the editor all use the
+  CJK-friendly extension.
+- **Callout** — a GitHub alert: `> [!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, `[!CAUTION]`
+  (kind case-insensitive on input, written uppercase), optional plain-text title on the same line
+  (`> [!WARNING] Title`); the rest of the quote is the body. A fold marker (`[!NOTE]-` / `+`) or an
+  unknown kind is NOT a callout: it stays an ordinary blockquote, marker verbatim.
+- **Toggle** — `:::toggle[Summary *inline*]` … `:::`. Body is any blocks; toggles nest, and sit
+  inside callouts and columns. Open state is not stored.
+- **Columns** — 2–4 columns, each with an optional `width` (integer percent 1–100; columns without
+  one share the remainder equally). Columns never nest.
+
+  ```md
+  ::::columns
+  :::column{width=40}
+  Left
+  :::
+
+  :::column
+  Right
+  :::
+  ::::
+  ```
+
+  Only container directives exist: the fence of a directive is one colon longer than the deepest
+  directive inside it, so the innermost fence is always `:::`. There are no text (`:name`) or leaf
+  (`::name`) directives — `10:30` is prose.
+
+- **Wikilinks and embeds, verbatim** — `[[target]]`, `[[target#heading]]`, `[[target|label]]`,
+  `![[embed]]` (a block when alone on its line; the inner text is kept verbatim — `![[B#見出し]]`, `![[img.png|300]]`). Marks around them survive (`**[[x]]**`). Inside a table cell write `[[x\|label]]`.
+- **`asset:` images** — `![alt](asset:id)` round-trips as written (the renderer resolves it through
+  `resolveUrl`).
+- **Raw blocks** — anything the document does not model (raw HTML, footnote definitions, link
+  reference definitions, an unknown or malformed directive, a fence with a meta string) is kept as
+  Markdown that parses back to the same thing. Mermaid is an ordinary ` ```mermaid ` fence.
+
+### Codec
+
+```ts
+import { CODEC_ID, normalize, parse, serialize } from "@godxjp/markdown/codec";
+
+CODEC_ID; // "kit-md@1" — bumped whenever serialize would write a body differently
+const doc = parse(markdown); // plain JSON, ProseMirror/Tiptap shape
+const md = serialize(doc); // canonical Markdown
+normalize(markdown) === serialize(parse(markdown)); // what the editor saves
+normalize(normalize(x)) === normalize(x); // idempotent, for every fixture
+```
+
+Pure: no React, no DOM, no editor — it runs on a server and in a Cloudflare Worker.
+
+**Canonical form** (what `serialize` writes): ATX headings; `-` bullets; `1.` ordered lists;
+`*em*`; `**strong**`; ` ``` ` fences (an indented code block becomes fenced); `---` rules;
+`- [ ]` / `- [x]` todos; GFM tables with padded cells and an alignment row; a callout's body after a
+`>` blank line; one blank line between blocks; LF; a trailing newline; an empty document is `""`.
+
 ## Stored versions
 
 Record `MARKDOWN_FORMAT` (`"md"`) and `RENDERER_VERSION` on every saved version.

package/dist/codec/index.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The codec's document: plain JSON in the ProseMirror/Tiptap shape (`type` / `attrs` / `content` /
+ * `text` / `marks`), so `@godxjp/block-editor` loads it with `setContent` and hands back what
+ * `getJSON()` returns. No DOM, no editor instance — this module runs in a Worker (gh#1156).
+ *
+ * Node names follow Tiptap's StarterKit / Table / Details extensions where one exists:
+ *   doc · paragraph · heading{level} · blockquote · codeBlock{language} · horizontalRule ·
+ *   bulletList{tight} · orderedList{start,tight} · listItem · taskList{tight} · taskItem{checked} ·
+ *   table · tableRow · tableHeader{align} · tableCell{align} · image{src,alt,title} · hardBreak
+ * and the kit's own:
+ *   callout{kind,title} · details · detailsSummary · detailsContent · columns · column{width} ·
+ *   embed{target} (block `![[x]]`) · wikilink{target,heading,label} · embedInline{target} ·
+ *   rawBlock{source} · rawInline{source} · frontmatter{source} (YAML, first block only)
+ * Marks: bold · italic · strike · code · link{href,title}.
+ */
+type Mark = {
+    type: "bold" | "italic" | "strike" | "code";
+} | {
+    type: "link";
+    attrs: {
+        href: string;
+        title: string | null;
+    };
+};
+type DocNode = {
+    type: string;
+    attrs?: Record<string, unknown>;
+    content?: DocNode[];
+    text?: string;
+    marks?: Mark[];
+};
+type Doc = DocNode & {
+    type: "doc";
+    content: DocNode[];
+};
+/** GitHub alert kinds, the only callouts v1 knows. Serialized uppercase. */
+declare const CALLOUT_KINDS: readonly ["note", "tip", "important", "warning", "caution"];
+type CalloutKind = (typeof CALLOUT_KINDS)[number];
+/** Columns per `:::columns` block (grammar v1). */
+declare const COLUMNS_MIN = 2;
+declare const COLUMNS_MAX = 4;
+
+/** Markdown → document (plain JSON, ProseMirror/Tiptap shape). Pure: no DOM. */
+declare function parse(markdown: string): Doc;
+
+type OutlineEntry = {
+    depth: number;
+    text: string;
+    id: string;
+};
+/**
+ * The body's headings with the ids `<Markdown>` gives them — GitHub slugs, de-duplicated in
+ * document order, the renderer's default rule — for a table of contents (the kit's `Anchor`). Pure.
+ * A host that passes its own `headingId` resolver to `<Markdown>` must use that same resolver here.
+ */
+declare function outline(markdown: string): OutlineEntry[];
+/** The body's YAML front matter, verbatim (without the `---` fences), or null. Parse it with your YAML library. */
+declare function frontmatterOf(markdown: string): string | null;
+
+/** Document → canonical Markdown. Pure: no DOM. */
+declare function serialize(doc: Doc | DocNode): string;
+
+/**
+ * Identifies the serializer's output. Bumped whenever `serialize` would write a stored body
+ * differently, so a host can tell which normalization a saved `normalized_body` came from.
+ */
+declare const CODEC_ID = "kit-md@1";
+/** `serialize(parse(markdown))` — the canonical form of a body, exactly what the editor saves. */
+declare function normalize(markdown: string): string;
+
+export { CALLOUT_KINDS, CODEC_ID, COLUMNS_MAX, COLUMNS_MIN, type CalloutKind, type Doc, type DocNode, type Mark, type OutlineEntry, frontmatterOf, normalize, outline, parse, serialize };

package/dist/codec/index.js

@@ -0,0 +1,611 @@
+// src/codec/parse.ts
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { toMarkdown } from "mdast-util-to-markdown";
+
+// src/codec/model.ts
+var CALLOUT_KINDS = ["note", "tip", "important", "warning", "caution"];
+var COLUMNS_MIN = 2;
+var COLUMNS_MAX = 4;
+
+// src/codec/readers.ts
+var CALLOUT = /^\[!([A-Za-z]+)\](?:[ \t]+([^\n]*))?$/;
+function readCallout(node) {
+  const [first, ...rest] = node.children;
+  if (first?.type !== "paragraph") return null;
+  const [head, ...tail] = first.children;
+  if (head?.type !== "text") return null;
+  const newline = head.value.indexOf("\n");
+  if (newline === -1 && tail.length > 0) return null;
+  const line = newline === -1 ? head.value : head.value.slice(0, newline);
+  const match = CALLOUT.exec(line);
+  const kind = match?.[1]?.toLowerCase();
+  if (!match || !kind || !CALLOUT_KINDS.includes(kind)) return null;
+  const remainder = [
+    ...newline === -1 ? [] : [{ ...head, value: head.value.slice(newline + 1) }],
+    ...tail
+  ].filter((n) => !(n.type === "text" && n.value === ""));
+  return {
+    kind,
+    title: match[2]?.trim() || null,
+    body: [
+      ...remainder.length ? [{ type: "paragraph", children: remainder }] : [],
+      ...rest
+    ]
+  };
+}
+function labelOf(node) {
+  const first = node.children[0];
+  return first?.type === "paragraph" && first.data?.directiveLabel ? first : null;
+}
+function readToggle(node) {
+  if (node.name !== "toggle" || Object.keys(node.attributes ?? {}).length > 0) return null;
+  const label = labelOf(node);
+  return {
+    summary: label?.children ?? [],
+    body: label ? node.children.slice(1) : node.children
+  };
+}
+function readColumns(node, nested) {
+  if (node.name !== "columns" || nested || labelOf(node) || Object.keys(node.attributes ?? {}).length) {
+    return null;
+  }
+  const columns = node.children;
+  if (columns.length < COLUMNS_MIN || columns.length > COLUMNS_MAX) return null;
+  const parts = [];
+  for (const column of columns) {
+    if (column.type !== "containerDirective" || column.name !== "column" || labelOf(column))
+      return null;
+    const attributes = Object.entries(column.attributes ?? {});
+    if (attributes.length > 1) return null;
+    let width = null;
+    if (attributes.length === 1) {
+      const [key, value] = attributes[0];
+      if (key !== "width" || typeof value !== "string" || !/^(?:[1-9]\d?|100)$/.test(value))
+        return null;
+      width = Number(value);
+    }
+    parts.push({ width, body: column.children });
+  }
+  return parts;
+}
+
+// src/codec/syntax.ts
+import { directive } from "micromark-extension-directive";
+import { gfm } from "micromark-extension-gfm";
+import { cjkFriendlyExtension } from "micromark-extension-cjk-friendly";
+import { frontmatter } from "micromark-extension-frontmatter";
+import { frontmatterFromMarkdown, frontmatterToMarkdown } from "mdast-util-frontmatter";
+import { directiveFromMarkdown } from "mdast-util-directive";
+import { gfmFromMarkdown, gfmToMarkdown } from "mdast-util-gfm";
+function micromarkExtensions() {
+  const [container] = directive().flow[58];
+  const containerOnly = { flow: { 58: container } };
+  return [gfm(), cjkFriendlyExtension(), frontmatter(["yaml"]), containerOnly];
+}
+function fromMarkdownExtensions() {
+  return [gfmFromMarkdown(), directiveFromMarkdown(), frontmatterFromMarkdown(["yaml"])];
+}
+var WIDE = /[\u1100-\u115F\u2E80-\u303E\u3041-\u33FF\u3400-\u4DBF\u4E00-\u9FFF\uA000-\uA4CF\uAC00-\uD7A3\uF900-\uFAFF\uFE30-\uFE4F\uFF00-\uFF60\uFFE0-\uFFE6\u{1F300}-\u{1F64F}\u{1F900}-\u{1F9FF}\u{20000}-\u{3FFFD}]/u;
+function displayWidth(value) {
+  let width = 0;
+  for (const char of value) width += WIDE.test(char) ? 2 : 1;
+  return width;
+}
+function toMarkdownGfm() {
+  return gfmToMarkdown({ stringLength: displayWidth });
+}
+function toMarkdownFrontmatter() {
+  return frontmatterToMarkdown(["yaml"]);
+}
+
+// src/codec/options.ts
+function containerDirective(node, _, state, info) {
+  const tracker = state.createTracker(info);
+  const [first, ...rest] = node.children;
+  const hasLabel = first?.type === "paragraph" && first.data?.directiveLabel;
+  const label = hasLabel ? `[${state.containerPhrasing(first, { ...tracker.current(), before: "[", after: "]" })}]` : "";
+  const attributes = Object.entries(node.attributes ?? {}).map(
+    ([key, value]) => value === "" || value == null ? key : `${key}=${/^[\w.-]+$/.test(String(value)) ? value : JSON.stringify(value)}`
+  ).join(" ");
+  const opening = `${node.name}${label}${attributes ? `{${attributes}}` : ""}`;
+  const body = state.containerFlow(
+    { type: "root", children: hasLabel ? rest : node.children },
+    tracker.current()
+  );
+  const longest = Math.max(2, ...[...body.matchAll(/^[ \t>]*(:{3,})/gm)].map((m) => m[1].length));
+  const fence = ":".repeat(longest + 1);
+  return body ? `${fence}${opening}
+${body}
+${fence}` : `${fence}${opening}
+${fence}`;
+}
+function toMarkdownOptions() {
+  return {
+    bullet: "-",
+    bulletOther: "*",
+    emphasis: "*",
+    strong: "*",
+    fence: "`",
+    fences: true,
+    rule: "-",
+    listItemIndent: "one",
+    incrementListMarker: true,
+    setext: false,
+    closeAtx: false,
+    resourceLink: false,
+    extensions: [
+      toMarkdownGfm(),
+      toMarkdownFrontmatter(),
+      { handlers: { containerDirective } }
+    ]
+  };
+}
+
+// src/codec/parse.ts
+var WIKILINK = /!\[\[([^[\]\n]+)\]\]|\[\[([^[\]\n|#]+)(?:#([^[\]\n|]+))?(?:\|([^[\]\n]+))?\]\]/g;
+function parseMdast(markdown) {
+  return fromMarkdown(markdown, {
+    extensions: micromarkExtensions(),
+    mdastExtensions: fromMarkdownExtensions()
+  });
+}
+function raw(node, inline2) {
+  const source = node.type === "html" ? node.value : toMarkdown(node, toMarkdownOptions()).replace(/\n+$/, "");
+  return { type: inline2 ? "rawInline" : "rawBlock", attrs: { source } };
+}
+function withMark(marks, mark) {
+  return [...marks, mark];
+}
+function text(value, marks) {
+  const out = [];
+  let last = 0;
+  for (const match of value.matchAll(WIKILINK)) {
+    const at = match.index;
+    if (at > last) out.push(leafText(value.slice(last, at), marks));
+    const [, embed, target, heading, label] = match;
+    out.push(
+      withMarks(
+        embed !== void 0 ? { type: "embedInline", attrs: { target: embed } } : {
+          type: "wikilink",
+          attrs: {
+            target: target.trim(),
+            heading: heading?.trim() ?? null,
+            label: label ?? null
+          }
+        },
+        marks
+      )
+    );
+    last = at + match[0].length;
+  }
+  if (last < value.length) out.push(leafText(value.slice(last), marks));
+  return out;
+}
+function withMarks(node, marks) {
+  return marks.length ? { ...node, marks } : node;
+}
+function leafText(value, marks) {
+  return marks.length ? { type: "text", text: value, marks } : { type: "text", text: value };
+}
+function inline(nodes, marks = []) {
+  return nodes.flatMap((node) => {
+    switch (node.type) {
+      case "text":
+        return text(node.value, marks);
+      case "emphasis":
+        return inline(node.children, withMark(marks, { type: "italic" }));
+      case "strong":
+        return inline(node.children, withMark(marks, { type: "bold" }));
+      case "delete":
+        return inline(node.children, withMark(marks, { type: "strike" }));
+      case "inlineCode":
+        return [leafText(node.value, withMark(marks, { type: "code" }))];
+      case "link":
+        return inline(
+          node.children,
+          withMark(marks, { type: "link", attrs: { href: node.url, title: node.title ?? null } })
+        );
+      case "image":
+        return [
+          withMarks(
+            {
+              type: "image",
+              attrs: { src: node.url, alt: node.alt ?? "", title: node.title ?? null }
+            },
+            marks
+          )
+        ];
+      case "break":
+        return [withMarks({ type: "hardBreak" }, marks)];
+      default:
+        return [withMarks(raw(node, true), marks)];
+    }
+  });
+}
+function paragraph(node) {
+  const content2 = inline(node.children);
+  if (content2.length === 1 && content2[0].type === "embedInline" && !content2[0].marks) {
+    return [{ type: "embed", attrs: { ...content2[0].attrs } }];
+  }
+  return [content2.length ? { type: "paragraph", content: content2 } : { type: "paragraph" }];
+}
+function blocks(nodes, depth) {
+  return nodes.flatMap((node) => block(node, depth));
+}
+function callout(node, depth) {
+  const parts = readCallout(node);
+  if (!parts) return null;
+  return {
+    type: "callout",
+    attrs: { kind: parts.kind, title: parts.title },
+    content: blocks(parts.body, depth)
+  };
+}
+var MARKER = /^\[![A-Za-z]+\][+-]?/;
+function keepMarker(children) {
+  const [first, ...rest] = children;
+  if (first?.type !== "paragraph") return children;
+  const [head, ...tail] = first.children;
+  const marker = head?.type === "text" ? MARKER.exec(head.value)?.[0] : void 0;
+  if (!marker || head?.type !== "text") return children;
+  const remainder = head.value.slice(marker.length);
+  return [
+    {
+      ...first,
+      children: [
+        { type: "html", value: marker },
+        ...remainder ? [{ ...head, value: remainder }] : [],
+        ...tail
+      ]
+    },
+    ...rest
+  ];
+}
+function directiveBlock(node, depth) {
+  const toggle = readToggle(node);
+  if (toggle) {
+    const summary = inline(toggle.summary);
+    return {
+      type: "details",
+      content: [
+        summary.length ? { type: "detailsSummary", content: summary } : { type: "detailsSummary" },
+        { type: "detailsContent", content: nonEmpty(blocks(toggle.body, depth)) }
+      ]
+    };
+  }
+  const columns = readColumns(node, depth.columns);
+  if (columns) {
+    return {
+      type: "columns",
+      content: columns.map((column) => ({
+        type: "column",
+        attrs: { width: column.width },
+        content: nonEmpty(blocks(column.body, { columns: true }))
+      }))
+    };
+  }
+  return raw(node, false);
+}
+function nonEmpty(content2) {
+  return content2.length ? content2 : [{ type: "paragraph" }];
+}
+function block(node, depth) {
+  switch (node.type) {
+    case "paragraph":
+      return paragraph(node);
+    case "heading": {
+      const content2 = inline(node.children);
+      return [
+        { type: "heading", attrs: { level: node.depth }, ...content2.length ? { content: content2 } : {} }
+      ];
+    }
+    case "thematicBreak":
+      return [{ type: "horizontalRule" }];
+    case "code":
+      if (node.meta) return [raw(node, false)];
+      return [
+        {
+          type: "codeBlock",
+          attrs: { language: node.lang ?? null },
+          ...node.value ? { content: [{ type: "text", text: node.value }] } : {}
+        }
+      ];
+    case "blockquote":
+      return [
+        callout(node, depth) ?? {
+          type: "blockquote",
+          content: nonEmpty(blocks(keepMarker(node.children), depth))
+        }
+      ];
+    case "list": {
+      const tasks = node.children.map((item) => typeof item.checked === "boolean");
+      if (tasks.some(Boolean) && !tasks.every(Boolean)) return [raw(node, false)];
+      const isTask = tasks.length > 0 && tasks.every(Boolean);
+      const tight = !node.spread && node.children.every((item) => !item.spread);
+      const items = node.children.map((item) => ({
+        type: isTask ? "taskItem" : "listItem",
+        ...isTask ? { attrs: { checked: item.checked === true } } : {},
+        content: nonEmpty(blocks(item.children, depth))
+      }));
+      if (isTask) return [{ type: "taskList", attrs: { tight }, content: items }];
+      return node.ordered ? [{ type: "orderedList", attrs: { start: node.start ?? 1, tight }, content: items }] : [{ type: "bulletList", attrs: { tight }, content: items }];
+    }
+    case "table": {
+      const width = node.children[0]?.children.length ?? 0;
+      return [
+        {
+          type: "table",
+          content: node.children.map((row, r) => ({
+            type: "tableRow",
+            content: row.children.slice(0, width).map((cell, c) => {
+              const content2 = inline(cell.children);
+              return {
+                type: r === 0 ? "tableHeader" : "tableCell",
+                attrs: { align: node.align?.[c] ?? null },
+                content: [content2.length ? { type: "paragraph", content: content2 } : { type: "paragraph" }]
+              };
+            })
+          }))
+        }
+      ];
+    }
+    case "containerDirective":
+      return [directiveBlock(node, depth)];
+    case "yaml":
+      return [{ type: "frontmatter", attrs: { source: node.value } }];
+    default:
+      return [raw(node, false)];
+  }
+}
+function parse(markdown) {
+  const content2 = blocks(parseMdast(markdown.replace(/\r\n?/g, "\n")).children, { columns: false });
+  return { type: "doc", content: content2.length ? content2 : [{ type: "paragraph" }] };
+}
+
+// src/codec/serialize.ts
+import { toMarkdown as toMarkdown2 } from "mdast-util-to-markdown";
+var MARK_RANK = ["link", "bold", "italic", "strike"];
+var hasMark = (node, type) => node.marks?.some((m) => m.type === type) ?? false;
+var linkOf = (node) => node.marks?.find((m) => m.type === "link");
+var sameLink = (a, b) => linkOf(a)?.attrs.href === linkOf(b)?.attrs.href && linkOf(a)?.attrs.title === linkOf(b)?.attrs.title;
+function wikilinkSource(node, inTable) {
+  const a = node.attrs;
+  const pipe = inTable ? "\\|" : "|";
+  return `[[${a.target}${a.heading ? `#${a.heading}` : ""}${a.label ? `${pipe}${a.label}` : ""}]]`;
+}
+function leaf(node, inTable) {
+  switch (node.type) {
+    case "text":
+      return hasMark(node, "code") ? [{ type: "inlineCode", value: node.text ?? "" }] : [{ type: "text", value: node.text ?? "" }];
+    case "hardBreak":
+      return [{ type: "break" }];
+    case "image": {
+      const a = node.attrs;
+      return [{ type: "image", url: a.src, alt: a.alt ?? "", title: a.title ?? null }];
+    }
+    case "wikilink":
+      return [{ type: "html", value: wikilinkSource(node, inTable) }];
+    case "embedInline":
+      return [{ type: "html", value: `![[${node.attrs.target}]]` }];
+    case "rawInline":
+      return [{ type: "html", value: String(node.attrs.source) }];
+    default:
+      return [];
+  }
+}
+function phrasing(nodes, inTable = false, rank = 0) {
+  if (rank === MARK_RANK.length) return nodes.flatMap((n) => leaf(n, inTable));
+  const mark = MARK_RANK[rank];
+  const out = [];
+  let i = 0;
+  while (i < nodes.length) {
+    const start = nodes[i];
+    const marked = hasMark(start, mark);
+    let j = i + 1;
+    while (j < nodes.length && hasMark(nodes[j], mark) === marked && (!marked || mark !== "link" || sameLink(start, nodes[j]))) {
+      j++;
+    }
+    const inner = phrasing(nodes.slice(i, j), inTable, rank + 1);
+    if (!marked) out.push(...inner);
+    else if (mark === "link") {
+      const { href, title } = linkOf(start).attrs;
+      out.push({ type: "link", url: href, title, children: inner });
+    } else if (mark === "bold") out.push({ type: "strong", children: inner });
+    else if (mark === "italic") out.push({ type: "emphasis", children: inner });
+    else out.push({ type: "delete", children: inner });
+    i = j;
+  }
+  return out;
+}
+var content = (node) => node.content ?? [];
+function paragraphOf(node) {
+  return { type: "paragraph", children: phrasing(content(node)) };
+}
+function flow(nodes) {
+  return nodes.flatMap(block2);
+}
+function block2(node) {
+  const attrs = node.attrs ?? {};
+  switch (node.type) {
+    case "paragraph":
+      return [paragraphOf(node)];
+    case "heading":
+      return [
+        {
+          type: "heading",
+          depth: Math.min(6, Math.max(1, Number(attrs.level) || 1)),
+          children: phrasing(content(node))
+        }
+      ];
+    case "horizontalRule":
+      return [{ type: "thematicBreak" }];
+    case "codeBlock":
+      return [
+        {
+          type: "code",
+          lang: attrs.language ?? null,
+          meta: null,
+          value: content(node).map((t) => t.text ?? "").join("")
+        }
+      ];
+    case "blockquote":
+      return [{ type: "blockquote", children: flow(content(node)) }];
+    case "callout": {
+      const marker = `[!${String(attrs.kind).toUpperCase()}]`;
+      const head = {
+        type: "paragraph",
+        children: [
+          { type: "html", value: marker },
+          ...attrs.title ? [{ type: "text", value: ` ${String(attrs.title)}` }] : []
+        ]
+      };
+      return [{ type: "blockquote", children: [head, ...flow(content(node))] }];
+    }
+    case "bulletList":
+    case "orderedList":
+    case "taskList": {
+      const tight = attrs.tight !== false;
+      return [
+        {
+          type: "list",
+          ordered: node.type === "orderedList",
+          start: node.type === "orderedList" ? Number(attrs.start ?? 1) : null,
+          spread: !tight,
+          children: content(node).map((item) => ({
+            type: "listItem",
+            spread: !tight,
+            checked: node.type === "taskList" ? item.attrs?.checked === true : null,
+            children: flow(content(item))
+          }))
+        }
+      ];
+    }
+    case "table": {
+      const rows = content(node);
+      const align = content(rows[0] ?? { type: "tableRow" }).map(
+        (cell) => cell.attrs?.align ?? null
+      );
+      return [
+        {
+          type: "table",
+          align,
+          children: rows.map((row) => ({
+            type: "tableRow",
+            children: content(row).map((cell) => ({
+              type: "tableCell",
+              children: phrasing(
+                content(cell).flatMap((p) => content(p)),
+                true
+              )
+            }))
+          }))
+        }
+      ];
+    }
+    case "details": {
+      const [summary, body] = [
+        content(node).find((n) => n.type === "detailsSummary"),
+        content(node).find((n) => n.type === "detailsContent")
+      ];
+      const label = summary && content(summary).length ? [
+        {
+          type: "paragraph",
+          data: { directiveLabel: true },
+          children: phrasing(content(summary))
+        }
+      ] : [];
+      return [
+        {
+          type: "containerDirective",
+          name: "toggle",
+          attributes: {},
+          children: [
+            ...label,
+            ...flow(content(body ?? { type: "detailsContent" }))
+          ]
+        }
+      ];
+    }
+    case "columns":
+      return [
+        {
+          type: "containerDirective",
+          name: "columns",
+          attributes: {},
+          children: content(node).map((column) => ({
+            type: "containerDirective",
+            name: "column",
+            attributes: column.attrs?.width != null ? { width: String(column.attrs.width) } : {},
+            children: flow(content(column))
+          }))
+        }
+      ];
+    case "embed":
+      return [{ type: "html", value: `![[${String(attrs.target)}]]` }];
+    case "rawBlock":
+      return [{ type: "html", value: String(attrs.source) }];
+    case "frontmatter":
+      return [{ type: "yaml", value: String(attrs.source) }];
+    default:
+      return [];
+  }
+}
+function decodeAttentionReferences(markdown) {
+  const references = [...markdown.matchAll(/&#x([0-9A-F]+);/g)];
+  if (references.length === 0) return markdown;
+  const target = JSON.stringify(parse(markdown));
+  let out = markdown;
+  for (const reference of references.reverse()) {
+    const at = reference.index;
+    const candidate = out.slice(0, at) + String.fromCodePoint(Number.parseInt(reference[1], 16)) + out.slice(at + reference[0].length);
+    if (JSON.stringify(parse(candidate)) === target) out = candidate;
+  }
+  return out;
+}
+function serialize(doc) {
+  const root = { type: "root", children: flow(doc.content ?? []) };
+  const markdown = toMarkdown2(root, toMarkdownOptions());
+  if (markdown.trim() === "") return "";
+  const tidy = markdown.replace(/\n{3,}/g, "\n\n").replace(/^\n+/, "").replace(/\n+$/, "\n");
+  return decodeAttentionReferences(tidy);
+}
+
+// src/codec/outline.ts
+import GithubSlugger from "github-slugger";
+import { visit } from "unist-util-visit";
+function textOf(node) {
+  if (node.type === "text" || node.type === "inlineCode" || node.type === "html") return node.value;
+  if (node.type === "image" || node.type === "imageReference") return "";
+  if ("children" in node) return node.children.map(textOf).join("");
+  return "";
+}
+function outline(markdown) {
+  const slugger = new GithubSlugger();
+  const entries = [];
+  visit(parseMdast(markdown.replace(/\r\n?/g, "\n")), "heading", (node) => {
+    const text2 = textOf(node);
+    entries.push({ depth: node.depth, text: text2, id: slugger.slug(text2) });
+  });
+  return entries;
+}
+function frontmatterOf(markdown) {
+  const first = parseMdast(markdown.replace(/\r\n?/g, "\n")).children[0];
+  return first?.type === "yaml" ? first.value : null;
+}
+
+// src/codec/index.ts
+var CODEC_ID = "kit-md@1";
+function normalize(markdown) {
+  return serialize(parse(markdown));
+}
+export {
+  CALLOUT_KINDS,
+  CODEC_ID,
+  COLUMNS_MAX,
+  COLUMNS_MIN,
+  frontmatterOf,
+  normalize,
+  outline,
+  parse,
+  serialize
+};

package/dist/index.d.ts

@@ -65,6 +65,10 @@ declare function extendSchema(extension?: SchemaExtension): Options;
  */
 declare function safeUrl(url: string, key: string): string;
 
+/** GitHub alert kinds, the only callouts v1 knows. Serialized uppercase. */
+declare const CALLOUT_KINDS: readonly ["note", "tip", "important", "warning", "caution"];
+type CalloutKind = (typeof CALLOUT_KINDS)[number];
+
 type PluggableList = NonNullable<Options$1["remarkPlugins"]>;
 /**
  * The stored body's format, and the renderer generation that produced its output. A consumer
@@ -73,7 +77,7 @@ type PluggableList = NonNullable<Options$1["remarkPlugins"]>;
  * differently — a schema change, a new default plugin — not on every release.
  */
 declare const MARKDOWN_FORMAT = "md";
-declare const RENDERER_VERSION = 3;
+declare const RENDERER_VERSION = 4;
 type MarkdownProps = {
     /** The Markdown source. */
     children: string;
@@ -124,6 +128,24 @@ type MarkdownProps = {
      * Characters are user-perceived (grapheme clusters). Default 24; `false` stamps nothing.
      */
     shortCellLength?: number | false;
+    /**
+     * Visible callout titles per kind when a callout has none of its own (`> [!WARNING]`). English by
+     * default — this package carries no i18n; a host passes its localized strings.
+     */
+    calloutTitles?: Partial<Record<CalloutKind, string>>;
+    /**
+     * Where an EXTERNAL link opens. An external link is an absolute http(s) URL whose origin differs
+     * from `origin`. `"new-tab"` gives it `target="_blank"` and `rel="noopener noreferrer"`. Relative
+     * links, `#anchors`, wikilinks resolved to a path, and `mailto:` stay in the tab. The default,
+     * `"same-tab"`, changes nothing. Markdown has no syntax for `target`, so this is a renderer policy.
+     */
+    externalLinks?: "same-tab" | "new-tab";
+    /**
+     * The page origin that `externalLinks` compares against. Defaults to `location.origin`. Pass it
+     * when rendering on the server, or every absolute link counts as external there and hydration
+     * disagrees on same-origin ones.
+     */
+    origin?: string;
 };
 /**
  * THE ONE RENDERER (gh#1108). GFM — tables, task lists, fenced code, autolinks, footnotes,
@@ -135,7 +157,7 @@ type MarkdownProps = {
  * Renders bare elements; the host wraps it (`<Prose>` from `@godxjp/ui/data-display`), so this
  * package carries no UI-kit dependency.
  */
-declare function Markdown({ children, remarkPlugins, rehypePlugins, schema, components, resolveUrl, headingId, mermaid, allowedElements, disallowedElements, allowElement, unwrapDisallowed, shortCellLength, }: MarkdownProps): React.JSX.Element;
+declare function Markdown({ children, remarkPlugins, rehypePlugins, schema, components, resolveUrl, headingId, mermaid, allowedElements, disallowedElements, allowElement, unwrapDisallowed, shortCellLength, calloutTitles, externalLinks, origin, }: MarkdownProps): React.JSX.Element;
 
 type MermaidSvgCheck = {
     ok: true;

package/dist/index.js

@@ -86,14 +86,14 @@ function checkMermaidSvg(svg) {
   const root = doc.documentElement;
   if (root.localName.toLowerCase() !== "svg") return { ok: false, reason: "root" };
   const elements = [root, ...Array.from(root.getElementsByTagName("*"))];
-  for (const element of elements) {
-    const name = element.localName.toLowerCase();
+  for (const element2 of elements) {
+    const name = element2.localName.toLowerCase();
     if (!ALLOWED_ELEMENTS.has(name)) return { ok: false, reason: `element ${name}` };
     if (name === "style") {
-      const css = element.textContent ?? "";
+      const css = element2.textContent ?? "";
       if (CSS_HAZARD.test(css) || !urlsAreLocal(css)) return { ok: false, reason: "style" };
     }
-    for (const attribute of Array.from(element.attributes)) {
+    for (const attribute of Array.from(element2.attributes)) {
       const attr = attribute.localName.toLowerCase();
       const value = attribute.value;
       if (attr.startsWith("on")) return { ok: false, reason: `handler ${attr}` };
@@ -203,7 +203,28 @@ var markdownSchema = {
     h3: [...defaultSchema.attributes?.h3 ?? [], "id"],
     h4: [...defaultSchema.attributes?.h4 ?? [], "id"],
     h5: [...defaultSchema.attributes?.h5 ?? [], "id"],
-    h6: [...defaultSchema.attributes?.h6 ?? [], "id"]
+    h6: [...defaultSchema.attributes?.h6 ?? [], "id"],
+    // Grammar v1 (gh#1156): the renderer's own callout / toggle / column markup. Every value is
+    // pinned — a body cannot mint any other class, kind, role or inline style through these.
+    div: [
+      ...defaultSchema.attributes?.div ?? [],
+      [
+        "className",
+        "ui-prose-callout",
+        "ui-prose-columns",
+        "ui-prose-column",
+        "ui-prose-directive"
+      ],
+      ["dataKind", "note", "tip", "important", "warning", "caution"],
+      ["role", "note"],
+      ["style", /^--prose-column-grow:\d+(?:\.\d+)?$/]
+    ],
+    p: [...defaultSchema.attributes?.p ?? [], ["className", "ui-prose-callout-title"]],
+    details: [...defaultSchema.attributes?.details ?? [], ["className", "ui-prose-toggle"]],
+    summary: [
+      ...defaultSchema.attributes?.summary ?? [],
+      ["className", "ui-prose-toggle-summary"]
+    ]
   }
 };
 var ruleName = (rule) => Array.isArray(rule) ? rule[0] : rule;
@@ -241,10 +262,177 @@ function safeUrl(url, key) {
   return SAFE_HREF.test(probe) ? value : "";
 }
 
+// src/codec/model.ts
+var CALLOUT_KINDS = ["note", "tip", "important", "warning", "caution"];
+var COLUMNS_MIN = 2;
+var COLUMNS_MAX = 4;
+
+// src/codec/readers.ts
+var CALLOUT = /^\[!([A-Za-z]+)\](?:[ \t]+([^\n]*))?$/;
+function readCallout(node) {
+  const [first, ...rest] = node.children;
+  if (first?.type !== "paragraph") return null;
+  const [head, ...tail] = first.children;
+  if (head?.type !== "text") return null;
+  const newline = head.value.indexOf("\n");
+  if (newline === -1 && tail.length > 0) return null;
+  const line = newline === -1 ? head.value : head.value.slice(0, newline);
+  const match = CALLOUT.exec(line);
+  const kind = match?.[1]?.toLowerCase();
+  if (!match || !kind || !CALLOUT_KINDS.includes(kind)) return null;
+  const remainder = [
+    ...newline === -1 ? [] : [{ ...head, value: head.value.slice(newline + 1) }],
+    ...tail
+  ].filter((n) => !(n.type === "text" && n.value === ""));
+  return {
+    kind,
+    title: match[2]?.trim() || null,
+    body: [
+      ...remainder.length ? [{ type: "paragraph", children: remainder }] : [],
+      ...rest
+    ]
+  };
+}
+function labelOf(node) {
+  const first = node.children[0];
+  return first?.type === "paragraph" && first.data?.directiveLabel ? first : null;
+}
+function readToggle(node) {
+  if (node.name !== "toggle" || Object.keys(node.attributes ?? {}).length > 0) return null;
+  const label = labelOf(node);
+  return {
+    summary: label?.children ?? [],
+    body: label ? node.children.slice(1) : node.children
+  };
+}
+function readColumns(node, nested) {
+  if (node.name !== "columns" || nested || labelOf(node) || Object.keys(node.attributes ?? {}).length) {
+    return null;
+  }
+  const columns = node.children;
+  if (columns.length < COLUMNS_MIN || columns.length > COLUMNS_MAX) return null;
+  const parts = [];
+  for (const column of columns) {
+    if (column.type !== "containerDirective" || column.name !== "column" || labelOf(column))
+      return null;
+    const attributes = Object.entries(column.attributes ?? {});
+    if (attributes.length > 1) return null;
+    let width = null;
+    if (attributes.length === 1) {
+      const [key, value] = attributes[0];
+      if (key !== "width" || typeof value !== "string" || !/^(?:[1-9]\d?|100)$/.test(value))
+        return null;
+      width = Number(value);
+    }
+    parts.push({ width, body: column.children });
+  }
+  return parts;
+}
+function columnShares(columns) {
+  const explicit = columns.reduce((sum, c) => sum + (c.width ?? 0), 0);
+  const open = columns.filter((c) => c.width == null).length;
+  const each = open ? Math.max(1, (100 - explicit) / open) : 0;
+  return columns.map((c) => c.width ?? Math.round(each * 100) / 100);
+}
+
+// src/codec/syntax.ts
+import { directive } from "micromark-extension-directive";
+import { gfm } from "micromark-extension-gfm";
+import { cjkFriendlyExtension } from "micromark-extension-cjk-friendly";
+import { frontmatter } from "micromark-extension-frontmatter";
+import { frontmatterFromMarkdown, frontmatterToMarkdown } from "mdast-util-frontmatter";
+import { directiveFromMarkdown } from "mdast-util-directive";
+import { gfmFromMarkdown, gfmToMarkdown } from "mdast-util-gfm";
+function micromarkExtensions() {
+  const [container] = directive().flow[58];
+  const containerOnly = { flow: { 58: container } };
+  return [gfm(), cjkFriendlyExtension(), frontmatter(["yaml"]), containerOnly];
+}
+function fromMarkdownExtensions() {
+  return [gfmFromMarkdown(), directiveFromMarkdown(), frontmatterFromMarkdown(["yaml"])];
+}
+
+// src/directives.ts
+var DEFAULT_CALLOUT_TITLES = {
+  note: "Note",
+  tip: "Tip",
+  important: "Important",
+  warning: "Warning",
+  caution: "Caution"
+};
+var element = (hName, hProperties = {}) => ({
+  hName,
+  hProperties
+});
+function remarkKitSyntax(options = {}) {
+  const titles = { ...DEFAULT_CALLOUT_TITLES, ...options.calloutTitles };
+  return function() {
+    const data = this.data();
+    (data.micromarkExtensions ??= []).push(...micromarkExtensions().slice(1));
+    (data.fromMarkdownExtensions ??= []).push(...fromMarkdownExtensions().slice(1));
+    const walk = (node, inColumn) => {
+      if (node.type === "blockquote") callout(node, titles);
+      else if (node.type === "containerDirective") directive2(node, inColumn);
+      if (!("children" in node)) return;
+      const isColumn = node.type === "containerDirective" && node.name === "column";
+      for (const child of node.children) walk(child, inColumn || isColumn);
+    };
+    return (tree) => {
+      tree.children = tree.children.filter((node) => node.type !== "yaml");
+      walk(tree, false);
+    };
+  };
+}
+function callout(node, titles) {
+  const parts = readCallout(node);
+  if (!parts) return;
+  const title = {
+    type: "paragraph",
+    data: element("p", { className: ["ui-prose-callout-title"] }),
+    children: [{ type: "text", value: parts.title ?? titles[parts.kind] }]
+  };
+  node.data = element("div", {
+    className: ["ui-prose-callout"],
+    dataKind: parts.kind,
+    role: "note"
+  });
+  node.children = [title, ...parts.body];
+}
+function directive2(node, nested) {
+  const toggle = readToggle(node);
+  if (toggle) {
+    const summary = {
+      type: "paragraph",
+      data: element("summary", { className: ["ui-prose-toggle-summary"] }),
+      children: toggle.summary
+    };
+    node.data = element("details", { className: ["ui-prose-toggle"] });
+    node.children = [summary, ...toggle.body];
+    return;
+  }
+  const columns = readColumns(node, nested);
+  if (columns) {
+    const shares = columnShares(columns);
+    node.data = element("div", { className: ["ui-prose-columns"] });
+    node.children = columns.map((column, i) => ({
+      type: "containerDirective",
+      name: "column",
+      attributes: {},
+      data: element("div", {
+        className: ["ui-prose-column"],
+        style: `--prose-column-grow:${shares[i]}`
+      }),
+      children: column.body
+    }));
+    return;
+  }
+  if (!node.data?.hName) node.data = element("div", { className: ["ui-prose-directive"] });
+}
+
 // src/markdown.tsx
 import { jsx as jsx3 } from "react/jsx-runtime";
 var MARKDOWN_FORMAT = "md";
-var RENDERER_VERSION = 3;
+var RENDERER_VERSION = 4;
 var URL_ATTRIBUTES = {
   a: "href",
   img: "src",
@@ -287,6 +475,25 @@ function rehypeShortCells(options) {
     });
   };
 }
+function rehypeExternalLinks(options) {
+  return (tree) => {
+    if (options.policy !== "new-tab") return;
+    const origin = options.origin ?? globalThis.location?.origin;
+    visit2(tree, "element", (node) => {
+      if (node.tagName !== "a") return;
+      const href = node.properties?.href;
+      if (typeof href !== "string" || !/^https?:\/\//i.test(href)) return;
+      let target;
+      try {
+        target = new URL(href);
+      } catch {
+        return;
+      }
+      if (origin && target.origin === origin) return;
+      node.properties = { ...node.properties, target: "_blank", rel: ["noopener", "noreferrer"] };
+    });
+  };
+}
 function omitNode(props) {
   const { node: _node, ...rest } = props;
   return rest;
@@ -312,9 +519,13 @@ function Markdown({
   disallowedElements,
   allowElement,
   unwrapDisallowed,
-  shortCellLength = 24
+  shortCellLength = 24,
+  calloutTitles,
+  externalLinks = "same-tab",
+  origin
 }) {
   const sanitizeSchema = React3.useMemo(() => extendSchema(schema), [schema]);
+  const kitSyntax = React3.useMemo(() => remarkKitSyntax({ calloutTitles }), [calloutTitles]);
   const merged = React3.useMemo(() => {
     const HostTable = components?.table;
     const table = (props) => /* @__PURE__ */ jsx3(TableScroll, { children: HostTable ? typeof HostTable === "string" ? React3.createElement(HostTable, props) : /* @__PURE__ */ jsx3(HostTable, { ...props }) : /* @__PURE__ */ jsx3("table", { ...omitNode(props) }) });
@@ -333,12 +544,13 @@ function Markdown({
   return /* @__PURE__ */ jsx3(
     ReactMarkdown,
     {
-      remarkPlugins: [remarkGfm, ...remarkPlugins],
+      remarkPlugins: [remarkGfm, kitSyntax, ...remarkPlugins],
       rehypePlugins: [
         [rehypeResolveUrls, { resolve: resolveUrl }],
         [rehypeHeadingIds, { resolve: headingId }],
         [rehypeSanitize, sanitizeSchema],
         [rehypeShortCells, { max: shortCellLength }],
+        [rehypeExternalLinks, { policy: externalLinks, origin }],
         ...rehypePlugins
       ],
       urlTransform: safeUrl,
@@ -440,6 +652,37 @@ var MARKDOWN_FIXTURES = [
     markdown: "![x](data:image/svg+xml;base64,PHN2Zz4=) ![y](javascript:alert(1))",
     html: '<p><img alt="x"/> <img alt="y"/></p>',
     forbidden: ["data:", "javascript:"]
+  },
+  // Grammar v1 (gh#1156, renderer v4): the constructs the codec and @godxjp/block-editor model.
+  {
+    name: "CJK-friendly emphasis next to \u3001\u3002\u300C\u300D\uFF08\uFF09",
+    markdown: "\u306E**\u300C\u5F37\u8ABF\u300D**\u3067\u3059\u3002\uFF08*\u6CE8*\uFF09\u300C[\u30EA\u30F3\u30AF](https://example.com/)\u300D\u3001**\u592A\u5B57**\u3002",
+    html: '<p>\u306E<strong>\u300C\u5F37\u8ABF\u300D</strong>\u3067\u3059\u3002\uFF08<em>\u6CE8</em>\uFF09\u300C<a href="https://example.com/">\u30EA\u30F3\u30AF</a>\u300D\u3001<strong>\u592A\u5B57</strong>\u3002</p>'
+  },
+  {
+    name: "callout with a title, and one without",
+    markdown: "> [!WARNING] Careful\n> Body\n\n> [!tip]\n> No title",
+    html: '<div class="ui-prose-callout" data-kind="warning" role="note">\n<p class="ui-prose-callout-title">Careful</p>\n<p>Body</p>\n</div>\n<div class="ui-prose-callout" data-kind="tip" role="note">\n<p class="ui-prose-callout-title">Tip</p>\n<p>No title</p>\n</div>'
+  },
+  {
+    name: "a fold marker or unknown kind stays a quote",
+    markdown: "> [!NOTE]- folded\n\n> [!INFO] unknown",
+    html: "<blockquote>\n<p>[!NOTE]- folded</p>\n</blockquote>\n<blockquote>\n<p>[!INFO] unknown</p>\n</blockquote>"
+  },
+  {
+    name: "toggle with an inline summary",
+    markdown: ":::toggle[Read *more*]\nBody\n:::",
+    html: '<details class="ui-prose-toggle"><summary class="ui-prose-toggle-summary">Read <em>more</em></summary><p>Body</p></details>'
+  },
+  {
+    name: "columns with a width and an equal share",
+    markdown: "::::columns\n:::column{width=40}\nLeft\n:::\n\n:::column\nRight\n:::\n::::",
+    html: '<div class="ui-prose-columns"><div class="ui-prose-column" style="--prose-column-grow:40"><p>Left</p></div><div class="ui-prose-column" style="--prose-column-grow:60"><p>Right</p></div></div>'
+  },
+  {
+    name: "wikilinks, embeds and times stay text",
+    markdown: "See [[Page#Intro|intro]] at 10:30.\n\n![[Diagram]]",
+    html: "<p>See [[Page#Intro|intro]] at 10:30.</p>\n<p>![[Diagram]]</p>"
   }
 ];
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@godxjp/markdown",
-  "version": "31.26.2",
+  "version": "31.28.0",
   "description": "The one Markdown renderer for GoDX apps: GFM + heading anchors, one sanitiser schema, a shared fixture corpus, and Mermaid drawn only after its SVG passes a fail-closed gate.",
   "type": "module",
   "main": "./dist/index.js",
@@ -11,6 +11,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./codec": {
+      "types": "./dist/codec/index.d.ts",
+      "import": "./dist/codec/index.js"
+    },
     "./package.json": "./package.json"
   },
   "sideEffects": false,
@@ -30,6 +34,16 @@
   "license": "Apache-2.0",
   "dependencies": {
     "github-slugger": "^2.0.0",
+    "mdast-util-directive": "^3.1.1",
+    "mdast-util-from-markdown": "^2.1.0",
+    "mdast-util-frontmatter": "^2.0.1",
+    "mdast-util-gfm": "^3.1.0",
+    "mdast-util-to-markdown": "^2.2.0",
+    "micromark-extension-cjk-friendly": "^2.0.2",
+    "micromark-extension-directive": "^4.0.0",
+    "micromark-extension-frontmatter": "^2.0.0",
+    "micromark-extension-gfm": "^3.0.0",
+    "micromark-util-types": "^2.0.2",
     "react-markdown": "^10.1.0",
     "rehype-sanitize": "^6.0.0",
     "remark-gfm": "^4.0.1",