@suzumiyaaoba/mdxr 0.1.0

package/src/hydrate/runtime-module.ts

@@ -0,0 +1,145 @@
+/**
+ * The virtual `@suzumiyaaoba/mdxr`(/components) module used inside hydration
+ * bundles.
+ * A fresh module is generated per importer containing only the re-exports
+ * that importer requests: esbuild eagerly resolves every
+ * `export { x } from "m"` target, and the leaf modules' top-level
+ * `defineComponent(...)` calls count as side effects — so a module exporting
+ * the whole catalog would drag the whole catalog into the bundle.
+ */
+
+import path from "node:path";
+
+import type { Plugin } from "esbuild";
+import * as valibot from "valibot";
+
+import { srcDir } from "../paths.js";
+import type { ExportIndex } from "./export-index.js";
+import { scanMdxrImports } from "./import-scan.js";
+import type { MdxrImports } from "./import-scan.js";
+
+/**
+ * Names that live outside the leaf map: `builtinComponents` is defined in the
+ * catalog barrel itself (pulling it is intentional — the whole catalog is the
+ * value) and `defineConfig` is part of the `@suzumiyaaoba/mdxr` API surface.
+ * They resolve
+ * only when a module actually imports them.
+ */
+export const EXTRA_MODULES: Record<string, string> = {
+  builtinComponents: path.join(srcDir, "ui/index.js"),
+  defineConfig: path.join(srcDir, "config.js"),
+  mountDocument: path.join(srcDir, "hydrate-runtime.js"),
+};
+
+/**
+ * The virtual module's `v` export. `export * as v` would materialize the
+ * entire valibot namespace — a plain object built from named imports ships
+ * only the schemas actually written. Unknown `v.x` accesses stay absent,
+ * matching `undefined` semantics. The `surface` gate keeps
+ * `@suzumiyaaoba/mdxr/components` honest: that specifier has no `v` export,
+ * so shipping one would diverge from SSR.
+ */
+const vExportLines = (imports: MdxrImports, surface: Set<string>): string[] => {
+  if (!surface.has("v") || imports.vProps === null) {
+    return [];
+  }
+  if (imports.vProps === "all" || imports.names === "all") {
+    return ['export * as v from "valibot";'];
+  }
+  const props: string[] = [];
+  for (const p of imports.vProps) {
+    if (p in valibot) {
+      props.push(p);
+    }
+  }
+  return [
+    props.length > 0
+      ? `import { ${props.join(", ")} } from "valibot";\nexport const v = { ${props.join(", ")} };`
+      : "export const v = {};",
+  ];
+};
+
+/**
+ * Virtual stand-in for `@suzumiyaaoba/mdxr`(/components) inside the bundle.
+ */
+// Exported for tests — pure codegen, so the emitted export list is easy to
+// assert without running esbuild.
+export const runtimeModuleContents = (
+  map: Map<string, string>,
+  imports: MdxrImports,
+  surface: Set<string>
+): string => {
+  const lines = [
+    `export { defineComponent, textOf } from ${JSON.stringify(path.join(srcDir, "define.js"))};`,
+    ...vExportLines(imports, surface),
+  ];
+  // "all" (namespace/default/dynamic imports) exports exactly the specifier's
+  // real surface — leaf internals and EXTRA names like `mountDocument` stay
+  // hidden, matching what the actual package would hand SSR. Named imports
+  // beyond the surface are skipped: SSR's link error is then mirrored by an
+  // esbuild "no matching export" failure instead of a silent divergence.
+  const wanted = imports.names === "all" ? [...surface] : [...imports.names];
+  const byModule = new Map<string, string[]>();
+  for (const name of wanted) {
+    if (!surface.has(name)) {
+      continue;
+    }
+    const mod = map.get(name) ?? EXTRA_MODULES[name];
+    if (mod === undefined) {
+      continue;
+    }
+    const list = byModule.get(mod) ?? [];
+    list.push(name);
+    byModule.set(mod, list);
+  }
+  for (const [mod, mods] of byModule) {
+    lines.push(`export { ${mods.join(", ")} } from ${JSON.stringify(mod)};`);
+  }
+  return lines.join("\n");
+};
+
+/* oxlint-disable require-unicode-regexp -- esbuild onResolve/onLoad filters forbid `u` */
+export const runtimeModule = (index: ExportIndex): Plugin => ({
+  name: "mdxr:runtime",
+  setup(b) {
+    const importers = new Map<
+      string,
+      { importer: string; surface: Set<string> }
+    >();
+    let seq = 0;
+    b.onResolve(
+      { filter: /^@suzumiyaaoba\/mdxr(?:\/components)?$/ },
+      (args) => {
+        const virtual = `mdxr:runtime:${seq}`;
+        seq += 1;
+        importers.set(virtual, {
+          importer: args.importer,
+          // Each specifier gets its own real surface — the root entry (config
+          // API) and `/components` (the catalog) are deliberately different
+          // sets.
+          surface:
+            args.path === "@suzumiyaaoba/mdxr"
+              ? index.surfaces.mdxr
+              : index.surfaces.components,
+        });
+        return { namespace: "mdxr-runtime", path: virtual };
+      }
+    );
+    b.onLoad(
+      { filter: /^mdxr:runtime:/, namespace: "mdxr-runtime" },
+      async (args) => {
+        const v = importers.get(args.path);
+        return {
+          contents: runtimeModuleContents(
+            index.map,
+            await scanMdxrImports(v?.importer ?? ""),
+            v?.surface ?? index.surfaces.components
+          ),
+          loader: "js",
+          resolveDir: srcDir,
+        };
+      }
+    );
+  },
+});
+/* oxlint-enable require-unicode-regexp */

package/src/hydrate-runtime.ts

@@ -0,0 +1,67 @@
+/**
+ * Client-side mount for hydrated documents. Bundled into the generated
+ * hydration entry by `buildHydrateScript` — keeping this as a real module
+ * means TypeScript checks the vnode wiring and the component-merge rules are
+ * literally shared with the SSR path (component-map.ts).
+ */
+
+import { createElement, Fragment } from "react";
+import { hydrateRoot } from "react-dom/client";
+
+import { mergeUserComponents } from "./component-map.js";
+import type { AnyComponent, ComponentMap } from "./define.js";
+import { DocContext } from "./doc-context.js";
+
+export interface MountSpec {
+  /** Catalog components assembled by the generated entry. */
+  components: ComponentMap;
+  /** The compiled MDX module's default export. */
+  doc: AnyComponent;
+  /** `fileLink(rel, line)` results recorded during SSR (`rel\0line` → url). */
+  fileLinks: Record<string, string>;
+  /** PlanHeader props, present iff the document header was rendered. */
+  headerProps?: Record<string, string | undefined>;
+  /** SSR render timestamp (ISO) — replayed into `DocContext.now`. */
+  now?: string;
+  /** The PlanHeader component — only bound when `headerProps` is set. */
+  planHeader?: AnyComponent;
+  /** The user's components module namespace, when configured. */
+  userModule?: Record<string, unknown>;
+}
+
+/**
+ * Rebuild the exact vnode tree SSR produced — `DocContext.Provider` wrapping
+ * the Plan header + the compiled MDX module — and `hydrateRoot` it onto
+ * `<main id="mdxr-root">`. `fileLink` is replayed from the recorded SSR
+ * answers, so components see identical data without filesystem access.
+ */
+export const mountDocument = (spec: MountSpec): void => {
+  if (spec.userModule !== undefined) {
+    mergeUserComponents(spec.userModule, spec.components);
+  }
+  const root = document.querySelector("#mdxr-root");
+  if (root === null) {
+    return;
+  }
+  hydrateRoot(
+    root,
+    createElement(
+      DocContext.Provider,
+      {
+        value: {
+          fileLink: (rel: string, line?: string) =>
+            spec.fileLinks[`${rel}\0${line ?? ""}`],
+          now: spec.now === undefined ? undefined : new Date(spec.now),
+        },
+      },
+      createElement(
+        Fragment,
+        null,
+        spec.headerProps === undefined || spec.planHeader === undefined
+          ? null
+          : createElement(spec.planHeader, spec.headerProps),
+        createElement(spec.doc, { components: spec.components })
+      )
+    )
+  );
+};

package/src/hydrate.ts

@@ -0,0 +1,147 @@
+/**
+ * Hydration bundle assembly: generates the inlined client script that
+ * rebuilds the exact vnode tree SSR produced and `hydrateRoot`s it onto
+ * `<main id="mdxr-root">`. Implementation details live in `src/hydrate/`:
+ * `export-index` (export surface scanning), `import-scan` (user-module
+ * import analysis), `runtime-module` (virtual package module codegen), and
+ * `plugins` (esbuild plugins for shared packages, the doc module, icons).
+ */
+
+import { build } from "esbuild";
+
+import { exportIndex } from "./hydrate/export-index.js";
+import { docModule, iconSets, pinShared } from "./hydrate/plugins.js";
+import { EXTRA_MODULES, runtimeModule } from "./hydrate/runtime-module.js";
+import { pkgRoot } from "./paths.js";
+import { builtinComponents } from "./ui/index.js";
+
+export { exportIndex } from "./hydrate/export-index.js";
+export { runtimeModuleContents } from "./hydrate/runtime-module.js";
+
+export interface HydrateSpec {
+  /** Compiled MDX module source (`program` format; default export = content). */
+  code: string;
+  /** Resolved entry of the user's components module, when configured. */
+  componentsPath?: string;
+  /** `fileLink(rel, line)` results recorded during SSR (`rel\0line` → url). */
+  fileLinks: Record<string, string>;
+  /** PlanHeader props, present iff the document header was rendered. */
+  header?: Record<string, string | undefined>;
+  /** SSR render timestamp (ISO) — replayed into `DocContext.now`. */
+  now?: string;
+  /** Catalog keys the document referenced — only these get imported. */
+  usedComponents: string[];
+  /** Iconify names (`prefix:name`) resolved during SSR. */
+  usedIcons: string[];
+}
+
+/**
+ * Build the inlined client script: it rebuilds the exact vnode tree SSR
+ * produced — `DocContext.Provider` wrapping the Plan header + the compiled
+ * MDX module — and `hydrateRoot`s it onto `<main id="mdxr-root">`.
+ * `fileLink` is replayed from the recorded SSR answers, so components see
+ * identical data without filesystem access.
+ */
+export const buildHydrateScript = async (
+  spec: HydrateSpec
+): Promise<string> => {
+  const index = await exportIndex();
+  const { map } = index;
+  const imports: string[] = [];
+  const entries: string[] = [];
+  let seq = 0;
+  // One aliased named import per leaf module keeps the generated code simple
+  // and collision-free; esbuild dedupes repeated module loads.
+  const bind = (exported: string): string => {
+    const mod = map.get(exported) ?? EXTRA_MODULES[exported];
+    if (mod === undefined) {
+      throw new Error(
+        `hydration: no module provides catalog export "${exported}"`
+      );
+    }
+    const local = `__mdxr_c${seq}`;
+    seq += 1;
+    imports.push(
+      `import { ${exported} as ${local} } from ${JSON.stringify(mod)};`
+    );
+    return local;
+  };
+
+  const mountDocument = bind("mountDocument");
+  // PlanHeader is only needed when a frontmatter header was rendered —
+  // binding it unconditionally would drag Meta/Due/StatusBadge into every
+  // bundle.
+  const planHeader =
+    spec.header === undefined ? "undefined" : bind("PlanHeader");
+
+  for (const name of spec.usedComponents) {
+    // User components merge via their namespace below; the `hasOwn` check must
+    // be own-property only — `in` alone treats `constructor` etc. as catalog
+    // names. `pre` (the markdown override) is exported as `Pre`.
+    if (!Object.hasOwn(builtinComponents, name)) {
+      continue;
+    }
+    const exported = name === "pre" ? "Pre" : name;
+    entries.push(`${JSON.stringify(name)}: ${bind(exported)}`);
+  }
+
+  const userImport =
+    spec.componentsPath === undefined
+      ? ""
+      : `import * as __mdxrUser from ${JSON.stringify(spec.componentsPath)};`;
+
+  // Mount/merge details live in hydrate-runtime (a real, type-checked module
+  // bundled by esbuild); the generated entry only binds names and data.
+  const entry = `${imports.join("\n")}
+${userImport}
+import __mdxrDoc from "mdxr:doc";
+${mountDocument}({
+  components: { ${entries.join(", ")} },
+  doc: __mdxrDoc,
+  fileLinks: ${JSON.stringify(spec.fileLinks)},
+  headerProps: ${JSON.stringify(spec.header)},
+  now: ${JSON.stringify(spec.now)},
+  planHeader: ${planHeader},
+  userModule: ${spec.componentsPath === undefined ? "undefined" : "__mdxrUser"},
+});
+`;
+
+  const result = await build({
+    absWorkingDir: pkgRoot,
+    bundle: true,
+    define: { "process.env.NODE_ENV": '"production"' },
+    format: "iife",
+    jsx: "automatic",
+    jsxImportSource: "react",
+    logLevel: "silent",
+    metafile: true,
+    minify: true,
+    platform: "browser",
+    plugins: [
+      pinShared,
+      docModule(spec.code),
+      runtimeModule(index),
+      iconSets(spec.usedIcons),
+    ],
+    stdin: {
+      contents: entry,
+      loader: "js",
+      resolveDir: pkgRoot,
+      sourcefile: "mdxr-hydrate.js",
+    },
+    target: "es2022",
+    write: false,
+  });
+  // `MDXR_BUNDLE_METAFILE=<path>` dumps the esbuild metafile for size work.
+  if (process.env.MDXR_BUNDLE_METAFILE !== undefined) {
+    const { writeFile } = await import("node:fs/promises");
+    await writeFile(
+      process.env.MDXR_BUNDLE_METAFILE,
+      JSON.stringify(result.metafile)
+    );
+    await writeFile(`${process.env.MDXR_BUNDLE_METAFILE}.entry.js`, entry);
+  }
+  // htmlDocument applies `inlineScript` escaping at embed time — return the
+  // raw bundle here.
+  return result.outputFiles[0]?.text ?? "";
+};

package/src/index.ts

@@ -0,0 +1,16 @@
+// Public entry: `@suzumiyaaoba/mdxr`
+// API surface for mdxr.config.ts and custom component modules.
+export { defineConfig, type MdxrConfig } from "./config.js";
+export {
+  defineComponent,
+  textOf,
+  type ComponentMeta,
+  type MdxrComponent,
+} from "./define.js";
+export { DocContext } from "./doc-context.js";
+// Also part of the root surface: config modules may want the catalog
+// without importing `@suzumiyaaoba/mdxr/components`. The hydration bundle
+// mirrors each
+// specifier's real surface, so the two entries stay distinct.
+export { builtinComponents } from "./ui/index.js";
+export * as v from "valibot";

package/src/init.ts

@@ -0,0 +1,57 @@
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { own } from "./guards.js";
+import { pkgRoot } from "./paths.js";
+
+const SKILL_DIRS: Record<string, { global: string; local: string }> = {
+  agents: { global: ".agents/skills/mdxr", local: ".agents/skills/mdxr" },
+  claude: { global: ".claude/skills/mdxr", local: ".claude/skills/mdxr" },
+  devin: { global: ".config/devin/skills/mdxr", local: ".devin/skills/mdxr" },
+};
+
+export interface InitOptions {
+  tool?: string;
+  global?: boolean;
+  force?: boolean;
+}
+
+export const installSkill = async (opts: InitOptions): Promise<string[]> => {
+  const tool = opts.tool ?? "agents";
+  const global = opts.global === true;
+  const base = global ? os.homedir() : process.cwd();
+
+  const tools = tool === "all" ? Object.keys(SKILL_DIRS) : [tool];
+  // `own`: `--tool toString` would otherwise pull a function off the
+  // prototype and crash on `path.join(base, undefined)`.
+  const dests = tools.map((t) => {
+    const dirs = own(SKILL_DIRS, t);
+    if (dirs === undefined) {
+      throw new Error(`unknown tool: ${t} (expected agents|claude|devin|all)`);
+    }
+    return path.join(base, global ? dirs.global : dirs.local);
+  });
+  for (const dest of dests) {
+    if (fs.existsSync(dest) && opts.force !== true) {
+      throw new Error(`${dest} already exists (use --force to overwrite)`);
+    }
+  }
+
+  return await Promise.all(
+    dests.map(async (dest) => {
+      await fsp.mkdir(path.dirname(dest), { recursive: true });
+      if (opts.force === true) {
+        // fs.cp only overwrites same-named files — files deleted or renamed
+        // upstream would linger in dest. A force install replaces wholesale.
+        await fsp.rm(dest, { force: true, recursive: true });
+      }
+      await fsp.cp(path.join(pkgRoot, "skill"), dest, {
+        force: true,
+        recursive: true,
+      });
+      return dest;
+    })
+  );
+};

package/src/langs.ts

@@ -0,0 +1,148 @@
+import { own } from "./guards.js";
+
+/**
+ * Fence-language sets shared by the rehype highlighter and the `Terminal`
+ * component. `Terminal` renders these as transcripts; shiki must skip them.
+ */
+
+/** Session/transcript fence languages rendered by the `Terminal` component. */
+export const TERMINAL_LANGS: ReadonlySet<string> = new Set([
+  "console",
+  "shell-session",
+  "shellsession",
+  "terminal",
+]);
+
+/** Languages with no grammar — left as plain `<pre>` text. */
+export const PLAIN_LANGS: ReadonlySet<string> = new Set([
+  "plain",
+  "plaintext",
+  "text",
+  "txt",
+]);
+
+/** Fences the shiki highlighter skips entirely (terminal + mermaid + plain). */
+export const SKIP_LANGS: ReadonlySet<string> = new Set([
+  ...TERMINAL_LANGS,
+  ...PLAIN_LANGS,
+  "mermaid",
+]);
+
+/** Exact basenames (lowercased) → shiki language id, for files with no
+ * meaningful extension. */
+const FILE_LANGS: Record<string, string> = {
+  ".babelrc": "json",
+  ".editorconfig": "ini",
+  ".eslintrc": "json",
+  ".gitignore": "ini",
+  ".npmrc": "ini",
+  ".prettierrc": "json",
+  brewfile: "ruby",
+  "cmakelists.txt": "cmake",
+  containerfile: "dockerfile",
+  dockerfile: "dockerfile",
+  gemfile: "ruby",
+  gnumakefile: "makefile",
+  guardfile: "ruby",
+  jenkinsfile: "groovy",
+  makefile: "makefile",
+  podfile: "ruby",
+  rakefile: "ruby",
+  vagrantfile: "ruby",
+};
+
+/** Extensions (lowercase, no dot) → shiki language id. Unknown ids are safe:
+ * the highlighter's lazy loader rejects names outside shiki's bundle and the
+ * caller falls back to unhighlighted rows. */
+const EXT_LANGS: Record<string, string> = {
+  astro: "astro",
+  bash: "bash",
+  c: "c",
+  cc: "cpp",
+  cfg: "ini",
+  cjs: "javascript",
+  clj: "clojure",
+  cljs: "clojure",
+  cmake: "cmake",
+  cpp: "cpp",
+  cs: "csharp",
+  css: "css",
+  cts: "typescript",
+  cxx: "cpp",
+  dart: "dart",
+  dockerfile: "dockerfile",
+  ex: "elixir",
+  exs: "elixir",
+  fish: "fish",
+  fs: "fsharp",
+  fsx: "fsharp",
+  gql: "graphql",
+  graphql: "graphql",
+  h: "c",
+  hh: "cpp",
+  hpp: "cpp",
+  hs: "haskell",
+  htm: "html",
+  html: "html",
+  hxx: "cpp",
+  ini: "ini",
+  java: "java",
+  jl: "julia",
+  js: "javascript",
+  json: "json",
+  json5: "json5",
+  jsonc: "jsonc",
+  jsx: "jsx",
+  kt: "kotlin",
+  kts: "kotlin",
+  less: "less",
+  lua: "lua",
+  md: "markdown",
+  mdx: "markdown",
+  mjs: "javascript",
+  ml: "ocaml",
+  mts: "typescript",
+  php: "php",
+  pl: "perl",
+  pm: "perl",
+  prisma: "prisma",
+  proto: "proto",
+  ps1: "powershell",
+  py: "python",
+  pyi: "python",
+  r: "r",
+  rb: "ruby",
+  rs: "rust",
+  sc: "scala",
+  scala: "scala",
+  scss: "scss",
+  sh: "bash",
+  sql: "sql",
+  svelte: "svelte",
+  svg: "xml",
+  swift: "swift",
+  tf: "terraform",
+  toml: "toml",
+  ts: "typescript",
+  tsx: "tsx",
+  txt: "text",
+  vb: "vb",
+  vue: "vue",
+  xml: "xml",
+  yaml: "yaml",
+  yml: "yaml",
+  zig: "zig",
+  zsh: "zsh",
+};
+
+/** Best-guess shiki language for a file path — basename first, then the
+ * extension. `x.d.ts` keeps `ts` (the declaration grammar is the same). */
+export const langForPath = (path: string): string | undefined => {
+  const base = path.split(/[\\/]/u).at(-1)?.toLowerCase() ?? "";
+  const named = own(FILE_LANGS, base);
+  if (named !== undefined) {
+    return named;
+  }
+  const ext = /\.(?<e>[^.]+)$/u.exec(base)?.groups?.e;
+  return ext === undefined ? undefined : own(EXT_LANGS, ext);
+};

package/src/lines.ts

@@ -0,0 +1,53 @@
+/** The shared `path:lines` grammar (`src/x.ts:40-52`, `…:40`, `…:40-`). */
+
+/** "`src/a.ts:40-52`" → `{ path: "src/a.ts", lines: "40-52" }`. */
+export const splitPathLines = (
+  value: string
+): { lines?: string; path: string } => {
+  const m = /^(?<p>.+):(?<ls>\d+(?:-\d*)?)$/u.exec(value);
+  return m?.groups === undefined
+    ? { path: value }
+    : { lines: m.groups.ls, path: m.groups.p };
+};
+
+/**
+ * `lines="40-52"`, `lines="40"`, `lines="40-"` → 1-based inclusive range
+ * (`end` undefined means "to EOF"). Invalid specs return undefined.
+ */
+export const parseLineRange = (
+  spec: string
+): { end: number | undefined; start: number } | undefined => {
+  const m = /^(?<start>\d+)(?:-(?<end>\d*))?$/u.exec(spec.trim());
+  if (m?.groups === undefined) {
+    return undefined;
+  }
+  const start = Number(m.groups.start);
+  let end: number | undefined;
+  if (m.groups.end === undefined) {
+    end = start;
+  } else if (m.groups.end !== "") {
+    end = Number(m.groups.end);
+  }
+  if (start < 1 || (end !== undefined && end < start)) {
+    return undefined;
+  }
+  return { end, start };
+};
+
+/** "40-52" → "40" — the first line of a range spec, used for link targets. */
+export const firstLine = (lines: string | undefined): string | undefined =>
+  /^(?<n>\d+)/u.exec(lines ?? "")?.groups?.n;
+
+/**
+ * `title="x.ts"` / `filename='x.ts'` / `title=x.ts` inside a code-fence meta
+ * string → the filename. Boundary-anchored: `data-title="x"` must not yield a
+ * filename. Shared by `Pre`'s header and the diff highlighter's lang guess.
+ */
+export const fenceFilename = (meta: string): string | undefined =>
+  /(?:^|\s)(?:title|filename)="(?<name>[^"]+)"/u.exec(meta)?.groups?.name ??
+  /(?:^|\s)(?:title|filename)='(?<sq>[^']+)'/u.exec(meta)?.groups?.sq ??
+  /(?:^|\s)(?:title|filename)=(?<name>[^\s"']+)/u.exec(meta)?.groups?.name;
+
+/** `lang=ts` inside a fence meta string → the explicit language override. */
+export const fenceLang = (meta: string): string | undefined =>
+  /(?:^|\s)lang=(?<l>[\w+.#-]+)/u.exec(meta)?.groups?.l;