slidev-addon-counter 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 inaku
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# slidev-addon-counter
+
+LaTeX-like multi-level counters for Slidev.
+
+## Usage
+
+Install the addon:
+
+```bash
+pnpm add -D slidev-addon-counter
+```
+
+For prerelease versions, install the matching dist-tag:
+
+```bash
+pnpm add -D slidev-addon-counter@alpha
+```
+
+Enable the addon in your Slidev deck:
+
+```md
+---
+addons:
+  - slidev-addon-counter
+---
+```
+
+Define counters in `slidev-addon-counter.config.ts` next to your deck entry:
+
+```ts
+import { defineCounterConfig } from "slidev-addon-counter/config";
+
+export default defineCounterConfig({
+  counters: {
+    section: {
+      levels: [
+        {
+          level: 1,
+          alias: "chapter",
+          style: "decimal",
+          format: "第 %{:value} 章",
+        },
+        {
+          level: 2,
+          alias: "section",
+          style: "decimal",
+          format: "%{@-1:full}.%{:value}",
+        },
+      ],
+    },
+  },
+});
+```
+
+Use counters in slides:
+
+```md
+<Counter id="section" level="chapter" />
+
+<Counter id="section" level="section" />
+
+<CounterIncrement id="theorem" level="theorem" />
+<CounterDisplay id="theorem" level="theorem" />
+```
+
+`action="step"` increments and displays, `action="increment"` only increments,
+and `action="display"` only displays the current value.
+
+`<Counter>` renders plain text, not an HTML wrapper element. To style a counter,
+wrap it yourself:
+
+```md
+<span class="text-red-500">
+  <Counter id="section" level="section" />
+</span>
+```
+
+Formats use `%{ref:kind}` placeholders. The `ref` may be empty for the
+current level, so `%{:value}` is equivalent to `%{@0:value}`. Use relative
+refs such as `%{@-1:full}` for parent levels, numeric refs such as
+`%{2:value}`, and aliases such as `%{chapter:raw}`.
+
+The first version supports `value`, `raw`, and `full`. A `full` placeholder may
+only reference a shallower level.
+
+## Development
+
+```bash
+source ~/.nvm/nvm.sh
+nvm use
+pnpm install
+pnpm check
+```
+
+Preview the local addon:
+
+```bash
+pnpm dev
+```

package/components/Counter.vue

@@ -0,0 +1,29 @@
+<script setup lang="ts">
+import { computed } from "vue";
+
+import { snapshots } from "virtual:slidev-addon-counter/snapshots";
+
+const props = withDefaults(
+  defineProps<{
+    action?: "step" | "increment" | "display";
+    id?: string;
+    level: number | string;
+    op?: string;
+  }>(),
+  {
+    action: "step",
+    id: "default",
+    op: "",
+  },
+);
+
+const displayText = computed(() => {
+  if (props.action === "increment") {
+    return "";
+  }
+
+  return props.op ? (snapshots[props.op]?.display ?? "") : "";
+});
+</script>
+
+<template>{{ displayText }}</template>

package/components/CounterDisplay.vue

@@ -0,0 +1,11 @@
+<script setup lang="ts">
+defineProps<{
+  id?: string;
+  level: number | string;
+  op?: string;
+}>();
+</script>
+
+<template>
+  <Counter :id="id" :level="level" :op="op" action="display" />
+</template>

package/components/CounterIncrement.vue

@@ -0,0 +1,11 @@
+<script setup lang="ts">
+defineProps<{
+  id?: string;
+  level: number | string;
+  op?: string;
+}>();
+</script>
+
+<template>
+  <Counter :id="id" :level="level" :op="op" action="increment" />
+</template>

package/components/CounterStep.vue

@@ -0,0 +1,11 @@
+<script setup lang="ts">
+defineProps<{
+  id?: string;
+  level: number | string;
+  op?: string;
+}>();
+</script>
+
+<template>
+  <Counter :id="id" :level="level" :op="op" action="step" />
+</template>

package/config.ts

@@ -0,0 +1,9 @@
+export type {
+  CounterConfig,
+  CounterDefinition,
+  CounterLevelConfig,
+  CounterReset,
+  CounterStyle,
+} from "./src/counter";
+
+export { defineCounterConfig } from "./src/counter";

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "slidev-addon-counter",
+  "version": "0.1.0-alpha.0",
+  "description": "LaTeX-like multi-level counters for Slidev.",
+  "type": "module",
+  "private": false,
+  "license": "MIT",
+  "packageManager": "pnpm@11.5.3",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "slidev-addon",
+    "slidev",
+    "counter",
+    "toc"
+  ],
+  "homepage": "https://github.com/inaku-Gyan/slidev-addon-counter#readme",
+  "bugs": {
+    "url": "https://github.com/inaku-Gyan/slidev-addon-counter/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/inaku-Gyan/slidev-addon-counter.git"
+  },
+  "engines": {
+    "node": ">=24.18.0",
+    "slidev": ">=52.0.0"
+  },
+  "files": [
+    "components",
+    "config.ts",
+    "src/counter.ts",
+    "setup",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    "./config": "./config.ts",
+    "./src/counter": "./src/counter.ts"
+  },
+  "scripts": {
+    "dev": "slidev demo/slides.md --open",
+    "build": "slidev build demo/slides.md",
+    "typecheck": "vue-tsc --noEmit",
+    "test": "vitest run",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "fmt": "prettier --write .",
+    "fmt:check": "prettier --check .",
+    "check": "pnpm typecheck && pnpm lint && pnpm fmt:check && pnpm test && pnpm build"
+  },
+  "peerDependencies": {
+    "vue": "^3.5.0"
+  },
+  "dependencies": {
+    "@slidev/client": "^52.16.0",
+    "htmlparser2": "^12.0.0",
+    "jiti": "^2.7.0",
+    "markdown-it": "^14.2.0"
+  },
+  "devDependencies": {
+    "@slidev/cli": "^52.16.0",
+    "@slidev/theme-default": "^0.25.0",
+    "@types/markdown-it": "^14.1.2",
+    "@types/node": "^26.0.0",
+    "oxlint": "^1.71.0",
+    "prettier": "^3.8.4",
+    "prettier-plugin-slidev": "^1.0.5",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9",
+    "vue": "^3.5.38",
+    "vue-tsc": "^3.3.5"
+  }
+}

package/setup/transformers.ts

@@ -0,0 +1,22 @@
+import { injectCounterOperationIds } from "../src/counter";
+
+export default function counterTransformers() {
+  return {
+    pre: [
+      (ctx: {
+        s: {
+          appendLeft: (index: number, content: string) => void;
+          original?: string;
+          toString: () => string;
+        };
+        slide?: { index?: number };
+      }) => {
+        const slideNo = (ctx.slide?.index ?? 0) + 1;
+        const content = ctx.s.original ?? ctx.s.toString();
+        for (const edit of injectCounterOperationIds(content, slideNo)) {
+          ctx.s.appendLeft(edit.index, edit.value);
+        }
+      },
+    ],
+  };
+}

package/setup/vite-plugins.ts

@@ -0,0 +1,241 @@
+import { existsSync } from "node:fs";
+import { join, normalize } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { createJiti } from "jiti";
+
+import {
+  buildCounterTimeline,
+  extractCounterOperations,
+  normalizeCounterConfig,
+  type CounterConfig,
+} from "../src/counter";
+
+const CONFIG_FILE = "slidev-addon-counter.config.ts";
+const VIRTUAL_ID = "virtual:slidev-addon-counter/snapshots";
+const RESOLVED_VIRTUAL_ID = "\0virtual:slidev-addon-counter/snapshots";
+const DIRECT_VIRTUAL_PATHS = [
+  "/virtual:slidev-addon-counter/snapshots",
+  "/@slidev-addon-counter/snapshots",
+];
+
+interface CounterPluginOptions {
+  userRoot: string;
+  data: {
+    slides: SlideSource[];
+  };
+}
+
+interface SlideSource {
+  index: number;
+  title?: string;
+  source: {
+    content: string;
+    filepath: string;
+  };
+}
+
+interface ViteDevServerLike {
+  middlewares: {
+    use: (
+      handler: (
+        req: { url?: string },
+        res: {
+          end: (chunk?: string) => void;
+          setHeader: (name: string, value: string) => void;
+          statusCode: number;
+        },
+        next: (error?: unknown) => void,
+      ) => void,
+    ) => void;
+  };
+  moduleGraph: {
+    getModuleById: (id: string) => unknown;
+    getModuleByUrl?: (url: string) => Promise<unknown>;
+    invalidateModule: (module: unknown) => void;
+  };
+  watcher: {
+    add: (path: string | string[]) => void;
+  };
+  ws: {
+    send: (payload: {
+      path?: string;
+      timestamp?: number;
+      type: string;
+    }) => void;
+  };
+}
+
+export default function counterVitePlugins(
+  options: CounterPluginOptions,
+): unknown[] {
+  return [
+    {
+      name: "slidev-addon-counter",
+      async buildStart(this: { addWatchFile: (id: string) => void }) {
+        const configPath = getConfigPath(options.userRoot);
+        if (configPath) {
+          this.addWatchFile(configPath);
+        }
+        for (const slide of options.data.slides) {
+          this.addWatchFile(slide.source.filepath);
+        }
+      },
+      resolveId(id: string) {
+        return id === VIRTUAL_ID ? RESOLVED_VIRTUAL_ID : undefined;
+      },
+      configureServer(server: ViteDevServerLike) {
+        watchCounterDependencies(server, options);
+
+        server.middlewares.use((req, res, next) => {
+          if (!isDirectVirtualRequest(req.url)) {
+            next();
+            return;
+          }
+
+          createSnapshotModule(options)
+            .then((code) => {
+              res.statusCode = 200;
+              res.setHeader("Content-Type", "text/javascript");
+              res.end(code);
+            })
+            .catch(next);
+        });
+      },
+      async load(id: string) {
+        if (id !== RESOLVED_VIRTUAL_ID) {
+          return undefined;
+        }
+
+        return createSnapshotModule(options);
+      },
+      async handleHotUpdate(ctx: { file: string; server: ViteDevServerLike }) {
+        if (!isCounterDependency(ctx.file, options)) {
+          return undefined;
+        }
+
+        await invalidateSnapshotModule(ctx.server);
+        queueFullReload(ctx.server);
+
+        return undefined;
+      },
+    },
+  ];
+}
+
+async function createSnapshotModule(
+  options: CounterPluginOptions,
+): Promise<string> {
+  const rawConfig = await loadUserConfig(options.userRoot);
+  const config = normalizeCounterConfig(rawConfig);
+  const operations = options.data.slides.flatMap((slide) =>
+    extractCounterOperations(
+      slide.source.content,
+      slide.index + 1,
+      slide.title,
+    ),
+  );
+  const timeline = buildCounterTimeline(operations, config);
+
+  return [
+    `export const snapshots = ${JSON.stringify(timeline.snapshots, null, 2)}`,
+    `export const operations = ${JSON.stringify(timeline.operations, null, 2)}`,
+  ].join("\n");
+}
+
+function watchCounterDependencies(
+  server: ViteDevServerLike,
+  options: CounterPluginOptions,
+): void {
+  const configPath = getConfigPath(options.userRoot);
+  const paths = [
+    ...(configPath ? [configPath] : []),
+    ...options.data.slides.map((slide) => slide.source.filepath),
+  ];
+
+  server.watcher.add([...new Set(paths)]);
+}
+
+async function invalidateSnapshotModule(
+  server: ViteDevServerLike,
+): Promise<void> {
+  const modules = [
+    server.moduleGraph.getModuleById(RESOLVED_VIRTUAL_ID),
+    server.moduleGraph.getModuleById(VIRTUAL_ID),
+    ...(await Promise.all(
+      DIRECT_VIRTUAL_PATHS.map((path) =>
+        server.moduleGraph.getModuleByUrl?.(path),
+      ),
+    )),
+  ].filter((module): module is object => Boolean(module));
+
+  for (const module of modules) {
+    server.moduleGraph.invalidateModule(module);
+  }
+}
+
+async function loadUserConfig(
+  userRoot: string,
+): Promise<CounterConfig | undefined> {
+  const configPath = getConfigPath(userRoot);
+  if (!configPath) {
+    return undefined;
+  }
+
+  const jiti = createJiti(import.meta.url, { moduleCache: false });
+  const configModule = await jiti.import<{ default?: CounterConfig }>(
+    pathToFileURL(configPath).href,
+  );
+  return configModule.default;
+}
+
+function getConfigPath(userRoot: string): string | undefined {
+  const configPath = join(userRoot, CONFIG_FILE);
+  return existsSync(configPath) ? configPath : undefined;
+}
+
+function isDirectVirtualRequest(url: string | undefined): boolean {
+  if (!url) {
+    return false;
+  }
+
+  const pathname = url.split("?", 1)[0];
+  return DIRECT_VIRTUAL_PATHS.includes(pathname);
+}
+
+function isCounterDependency(
+  file: string,
+  options: CounterPluginOptions,
+): boolean {
+  const normalizedFile = normalize(file);
+  if (isCounterConfigFile(normalizedFile, options)) {
+    return true;
+  }
+
+  return options.data.slides.some(
+    (slide) => normalize(slide.source.filepath) === normalizedFile,
+  );
+}
+
+function isCounterConfigFile(
+  file: string,
+  options: CounterPluginOptions,
+): boolean {
+  const normalizedFile = normalize(file);
+  const configPath = getConfigPath(options.userRoot);
+  if (configPath && normalize(configPath) === normalizedFile) {
+    return true;
+  }
+
+  return false;
+}
+
+function queueFullReload(server: ViteDevServerLike): void {
+  setTimeout(() => {
+    server.ws.send({
+      type: "full-reload",
+      path: "*",
+      timestamp: Date.now(),
+    });
+  }, 50);
+}

package/src/counter.ts

@@ -0,0 +1,763 @@
+import { parseDocument } from "htmlparser2";
+import MarkdownIt from "markdown-it";
+
+export type CounterStyle =
+  | "decimal"
+  | "zero"
+  | "lower-alpha"
+  | "upper-alpha"
+  | "lower-roman"
+  | "upper-roman"
+  | "cjk";
+
+export type CounterReset = "lower" | "none";
+export type CounterAction = "step" | "increment" | "display";
+export type LevelRef = number | string;
+
+export interface CounterLevelConfig {
+  level: number;
+  alias?: string;
+  style?: CounterStyle;
+  format?: string;
+  reset?: CounterReset;
+}
+
+export interface CounterDefinition {
+  levels?: CounterLevelConfig[];
+}
+
+export interface CounterConfig {
+  counters?: Record<string, CounterDefinition>;
+}
+
+export interface NormalizedCounterLevel {
+  level: number;
+  alias?: string;
+  style: CounterStyle;
+  format: string;
+  reset: CounterReset;
+}
+
+export interface NormalizedCounterDefinition {
+  id: string;
+  levels: Map<number, NormalizedCounterLevel>;
+  aliases: Map<string, number>;
+}
+
+export interface NormalizedCounterConfig {
+  counters: Map<string, NormalizedCounterDefinition>;
+}
+
+export interface CounterOperation {
+  id: string;
+  counter: string;
+  level: LevelRef;
+  action: CounterAction;
+  slideNo: number;
+  order: number;
+  title?: string;
+}
+
+export interface CounterSnapshot {
+  id: string;
+  counter: string;
+  level: number;
+  action: CounterAction;
+  counts: number[];
+  display: string;
+}
+
+export interface CounterTimeline {
+  snapshots: Record<string, CounterSnapshot>;
+  operations: CounterOperation[];
+}
+
+interface RenderContext {
+  counts: readonly number[];
+  counter: NormalizedCounterDefinition;
+  currentLevel: number;
+  stack: number[];
+}
+
+interface CounterTagMatch {
+  component: string;
+  attrs: Record<string, string>;
+  index: number;
+}
+
+interface HtmlNode {
+  type?: string;
+  name?: string;
+  attribs?: Record<string, string>;
+  children?: HtmlNode[];
+  startIndex?: number | null;
+}
+
+const BUILTIN_STYLES = new Set<CounterStyle>([
+  "decimal",
+  "zero",
+  "lower-alpha",
+  "upper-alpha",
+  "lower-roman",
+  "upper-roman",
+  "cjk",
+]);
+
+const BUILTIN_RESETS = new Set<CounterReset>(["lower", "none"]);
+const BUILTIN_PLACEHOLDER_KINDS = new Set(["value", "raw", "full"]);
+const PLACEHOLDER_RE = /%\{([^}]*)\}/g;
+const COUNTER_COMPONENTS = new Set([
+  "Counter",
+  "CounterStep",
+  "CounterIncrement",
+  "CounterDisplay",
+]);
+const markdownIt = new MarkdownIt({ html: true });
+
+export function defineCounterConfig<T extends CounterConfig>(config: T): T {
+  return config;
+}
+
+export function normalizeCounterConfig(
+  config: CounterConfig | undefined,
+): NormalizedCounterConfig {
+  const inputCounters = config?.counters ?? { default: {} };
+  const counters = new Map<string, NormalizedCounterDefinition>();
+
+  for (const [id, definition] of Object.entries(inputCounters)) {
+    if (!id) {
+      throw new Error("counters contains an empty counter id.");
+    }
+
+    const levels = new Map<number, NormalizedCounterLevel>();
+    const aliases = new Map<string, number>();
+
+    for (const [index, levelConfig] of (definition.levels ?? []).entries()) {
+      const path = `counters.${id}.levels[${index}]`;
+
+      if (!Number.isInteger(levelConfig.level) || levelConfig.level < 1) {
+        throw new Error(`${path}.level must be a positive integer.`);
+      }
+
+      if (levels.has(levelConfig.level)) {
+        throw new Error(`${path}.level duplicates level ${levelConfig.level}.`);
+      }
+
+      if (levelConfig.alias != null) {
+        validateAlias(levelConfig.alias, `${path}.alias`);
+        if (aliases.has(levelConfig.alias)) {
+          throw new Error(
+            `${path}.alias duplicates alias "${levelConfig.alias}".`,
+          );
+        }
+        aliases.set(levelConfig.alias, levelConfig.level);
+      }
+
+      const style = levelConfig.style ?? "decimal";
+      if (!BUILTIN_STYLES.has(style)) {
+        throw new Error(`${path}.style "${style}" is not supported.`);
+      }
+
+      const reset = levelConfig.reset ?? "lower";
+      if (!BUILTIN_RESETS.has(reset)) {
+        throw new Error(`${path}.reset "${reset}" is not supported.`);
+      }
+
+      levels.set(levelConfig.level, {
+        level: levelConfig.level,
+        alias: levelConfig.alias,
+        style,
+        format: levelConfig.format ?? getDefaultFormat(levelConfig.level),
+        reset,
+      });
+    }
+
+    counters.set(id, { id, levels, aliases });
+  }
+
+  if (counters.size === 0) {
+    counters.set("default", {
+      id: "default",
+      levels: new Map(),
+      aliases: new Map(),
+    });
+  }
+
+  return { counters };
+}
+
+export function getCounterDefinition(
+  config: NormalizedCounterConfig,
+  counterId: string,
+): NormalizedCounterDefinition {
+  const definition = config.counters.get(counterId);
+  if (definition) {
+    return definition;
+  }
+
+  throw new Error(`Counter "${counterId}" is not defined.`);
+}
+
+export function getLevelConfig(
+  counter: NormalizedCounterDefinition,
+  level: number,
+): NormalizedCounterLevel {
+  return (
+    counter.levels.get(level) ?? {
+      level,
+      style: "decimal",
+      format: getDefaultFormat(level),
+      reset: "lower",
+    }
+  );
+}
+
+export function resolveLevelRef(
+  counter: NormalizedCounterDefinition,
+  ref: LevelRef | undefined,
+  currentLevel: number,
+): number {
+  if (ref == null || ref === "") {
+    return currentLevel;
+  }
+
+  if (typeof ref === "number") {
+    validateLevel(ref, `level reference "${ref}"`);
+    return ref;
+  }
+
+  if (/^@[+-]?\d+$/.test(ref)) {
+    const level = currentLevel + Number(ref.slice(1));
+    validateLevel(level, `relative level reference "${ref}"`);
+    return level;
+  }
+
+  if (ref.startsWith("@")) {
+    throw new Error(`Relative level reference "${ref}" is not valid.`);
+  }
+
+  if (/^\d+$/.test(ref)) {
+    const level = Number(ref);
+    validateLevel(level, `level reference "${ref}"`);
+    return level;
+  }
+
+  const aliasLevel = counter.aliases.get(ref);
+  if (aliasLevel != null) {
+    return aliasLevel;
+  }
+
+  throw new Error(
+    `format reference "${ref}" references unknown level "${ref}" in counter "${counter.id}".`,
+  );
+}
+
+export function formatCounterValue(
+  value: number,
+  style: CounterStyle = "decimal",
+): string {
+  if (style === "zero") {
+    return String(value).padStart(2, "0");
+  }
+
+  if (style === "lower-alpha" || style === "upper-alpha") {
+    const alphabetic = toAlphabetic(value);
+    return style === "upper-alpha" ? alphabetic.toUpperCase() : alphabetic;
+  }
+
+  if (style === "lower-roman" || style === "upper-roman") {
+    const roman = toRoman(value);
+    return style === "upper-roman" ? roman.toUpperCase() : roman;
+  }
+
+  if (style === "cjk") {
+    return toCjk(value);
+  }
+
+  return String(value);
+}
+
+export function renderCounterFormat(
+  counter: NormalizedCounterDefinition,
+  counts: readonly number[],
+  targetLevel: number,
+): string {
+  validateLevel(targetLevel, `target level "${targetLevel}"`);
+
+  return renderFullLevel({
+    counts,
+    counter,
+    currentLevel: targetLevel,
+    stack: [],
+  });
+}
+
+export function buildCounterTimeline(
+  operations: readonly CounterOperation[],
+  config: CounterConfig | NormalizedCounterConfig | undefined,
+): CounterTimeline {
+  const normalized = isNormalizedCounterConfig(config)
+    ? config
+    : normalizeCounterConfig(config);
+
+  const sorted = [...operations].sort((a, b) => {
+    return a.slideNo - b.slideNo || a.order - b.order;
+  });
+
+  const states = new Map<string, number[]>();
+  const snapshots: Record<string, CounterSnapshot> = {};
+
+  for (const operation of sorted) {
+    const counter = getCounterDefinition(normalized, operation.counter);
+    const level = resolveLevelRef(counter, operation.level, 1);
+    const counts = states.get(operation.counter) ?? [];
+
+    if (operation.action === "step" || operation.action === "increment") {
+      for (let i = 0; i < level - 1; i += 1) {
+        counts[i] ??= 0;
+      }
+
+      counts[level - 1] = (counts[level - 1] ?? 0) + 1;
+
+      if (getLevelConfig(counter, level).reset === "lower") {
+        counts.length = level;
+      }
+
+      states.set(operation.counter, counts);
+    }
+
+    const snapshotCounts = [...counts];
+    snapshots[operation.id] = {
+      id: operation.id,
+      counter: operation.counter,
+      level,
+      action: operation.action,
+      counts: snapshotCounts,
+      display: renderCounterFormat(counter, snapshotCounts, level),
+    };
+  }
+
+  return {
+    snapshots,
+    operations: sorted,
+  };
+}
+
+function isNormalizedCounterConfig(
+  config: CounterConfig | NormalizedCounterConfig | undefined,
+): config is NormalizedCounterConfig {
+  return config?.counters instanceof Map;
+}
+
+export function extractCounterOperations(
+  content: string,
+  slideNo: number,
+  title?: string,
+): CounterOperation[] {
+  const operations: CounterOperation[] = [];
+
+  for (const match of findCounterTags(content)) {
+    const { component, attrs } = match;
+    const id =
+      readStringAttribute(attrs, "op") ??
+      getCounterOperationId(slideNo, operations.length);
+    const counter = readStringAttribute(attrs, "id") ?? "default";
+    const level = readLevelAttribute(attrs);
+    const action = getAction(component, readStringAttribute(attrs, "action"));
+
+    if (level == null) {
+      throw new Error(
+        `<${component}> on slide ${slideNo} is missing required prop "level".`,
+      );
+    }
+
+    operations.push({
+      id,
+      counter,
+      level,
+      action,
+      slideNo,
+      order: operations.length,
+      title,
+    });
+  }
+
+  return operations;
+}
+
+export function getCounterOperationId(slideNo: number, order: number): string {
+  return `counter-s${slideNo}-o${order}`;
+}
+
+export function injectCounterOperationIds(
+  content: string,
+  slideNo: number,
+): Array<{ index: number; value: string }> {
+  const edits: Array<{ index: number; value: string }> = [];
+  let order = 0;
+
+  for (const match of findCounterTags(content)) {
+    if (readStringAttribute(match.attrs, "op") != null) {
+      order += 1;
+      continue;
+    }
+
+    edits.push({
+      index: match.index + 1 + match.component.length,
+      value: ` op="${getCounterOperationId(slideNo, order)}"`,
+    });
+    order += 1;
+  }
+
+  return edits;
+}
+
+function findCounterTags(content: string): CounterTagMatch[] {
+  const lineOffsets = getLineOffsets(content);
+  const tags: CounterTagMatch[] = [];
+
+  for (const token of markdownIt.parse(content, {})) {
+    if (token.type === "html_block" && token.map) {
+      const baseIndex = lineOffsets[token.map[0]] ?? 0;
+      tags.push(...parseCounterTagsFromHtml(token.content, baseIndex));
+      continue;
+    }
+
+    if (token.type === "inline" && token.map && token.children) {
+      const segmentStart = lineOffsets[token.map[0]] ?? 0;
+      const segmentEnd = lineOffsets[token.map[1]] ?? content.length;
+      const segment = content.slice(segmentStart, segmentEnd);
+      let cursor = 0;
+
+      for (const child of token.children) {
+        if (child.type !== "html_inline") {
+          continue;
+        }
+
+        const relativeIndex = segment.indexOf(child.content, cursor);
+        if (relativeIndex < 0) {
+          continue;
+        }
+
+        tags.push(
+          ...parseCounterTagsFromHtml(
+            child.content,
+            segmentStart + relativeIndex,
+          ),
+        );
+        cursor = relativeIndex + child.content.length;
+      }
+    }
+  }
+
+  return tags.sort((a, b) => a.index - b.index);
+}
+
+function parseCounterTagsFromHtml(
+  html: string,
+  baseIndex: number,
+): CounterTagMatch[] {
+  const document = parseDocument(html, {
+    lowerCaseAttributeNames: false,
+    lowerCaseTags: false,
+    withStartIndices: true,
+  });
+  const tags: CounterTagMatch[] = [];
+
+  walkHtmlNodes(document.children as HtmlNode[], (node) => {
+    if (
+      node.type !== "tag" ||
+      !node.name ||
+      !COUNTER_COMPONENTS.has(node.name) ||
+      node.startIndex == null
+    ) {
+      return;
+    }
+
+    tags.push({
+      component: node.name,
+      attrs: node.attribs ?? {},
+      index: baseIndex + node.startIndex,
+    });
+  });
+
+  return tags;
+}
+
+function walkHtmlNodes(
+  nodes: readonly HtmlNode[],
+  visit: (node: HtmlNode) => void,
+): void {
+  for (const node of nodes) {
+    visit(node);
+    if (node.children) {
+      walkHtmlNodes(node.children, visit);
+    }
+  }
+}
+
+function getLineOffsets(content: string): number[] {
+  const offsets = [0];
+  for (let i = 0; i < content.length; i += 1) {
+    if (content[i] === "\n") {
+      offsets.push(i + 1);
+    }
+  }
+  return offsets;
+}
+
+function renderFullLevel(context: RenderContext): string {
+  const { counter, currentLevel, stack } = context;
+  if (stack.includes(currentLevel)) {
+    throw new Error(
+      `format for counter "${counter.id}" level ${currentLevel} recursively references itself.`,
+    );
+  }
+
+  const levelConfig = getLevelConfig(counter, currentLevel);
+  const nextContext = {
+    ...context,
+    stack: [...stack, currentLevel],
+  };
+
+  return levelConfig.format.replace(
+    PLACEHOLDER_RE,
+    (placeholder: string, body: string) => {
+      const { ref, kind } = parsePlaceholder(
+        placeholder,
+        body,
+        levelConfig.format,
+      );
+
+      if (kind === "value") {
+        return renderLevelValue(nextContext, ref);
+      }
+
+      if (kind === "raw") {
+        const level = resolveLevelRef(counter, ref, currentLevel);
+        return String(context.counts[level - 1] ?? 0);
+      }
+
+      if (kind === "full") {
+        return renderRefFull(nextContext, ref);
+      }
+
+      throw new Error(`Unknown counter format placeholder "${placeholder}".`);
+    },
+  );
+}
+
+function renderLevelValue(context: RenderContext, ref: string): string {
+  const level = resolveLevelRef(context.counter, ref, context.currentLevel);
+  const levelConfig = getLevelConfig(context.counter, level);
+  return formatCounterValue(context.counts[level - 1] ?? 0, levelConfig.style);
+}
+
+function renderRefFull(context: RenderContext, ref: string): string {
+  const level = resolveLevelRef(context.counter, ref, context.currentLevel);
+  if (level === context.currentLevel) {
+    throw new Error(
+      `format for counter "${context.counter.id}" level ${context.currentLevel} recursively references itself.`,
+    );
+  }
+
+  if (level > context.currentLevel) {
+    throw new Error(
+      `format for counter "${context.counter.id}" level ${context.currentLevel} cannot use full reference to deeper level ${level}.`,
+    );
+  }
+
+  return renderFullLevel({
+    ...context,
+    currentLevel: level,
+  });
+}
+
+function getDefaultFormat(level: number): string {
+  validateLevel(level, `level "${level}"`);
+  return level === 1 ? "%{:value}" : "%{@-1:full}.%{:value}";
+}
+
+function validateLevel(level: number, label: string): void {
+  if (!Number.isInteger(level) || level < 1) {
+    throw new Error(`${label} must be a positive integer.`);
+  }
+}
+
+function validateAlias(alias: string, path: string): void {
+  if (!/^[A-Za-z_][\w-]*$/.test(alias)) {
+    throw new Error(`${path} must be an identifier-like string.`);
+  }
+
+  if (/^\d+$/.test(alias) || alias.startsWith("@") || alias.includes(":")) {
+    throw new Error(`${path} "${alias}" is reserved.`);
+  }
+}
+
+function parsePlaceholder(
+  placeholder: string,
+  body: string,
+  format: string,
+): { ref: string; kind: string } {
+  const parts = body.split(":");
+  if (parts.length !== 2) {
+    throw new Error(
+      `format "${format}" uses placeholder "${placeholder}" without required ref:kind syntax.`,
+    );
+  }
+
+  const [ref, kind] = parts;
+  if (!BUILTIN_PLACEHOLDER_KINDS.has(kind)) {
+    throw new Error(`Unknown counter format placeholder "${placeholder}".`);
+  }
+
+  return { ref, kind };
+}
+
+function toAlphabetic(value: number): string {
+  if (!Number.isInteger(value) || value < 1) {
+    throw new RangeError(
+      `Alphabetic counter value must be a positive integer, got ${value}.`,
+    );
+  }
+
+  let remaining = value;
+  let result = "";
+
+  while (remaining > 0) {
+    remaining -= 1;
+    result = String.fromCharCode(97 + (remaining % 26)) + result;
+    remaining = Math.floor(remaining / 26);
+  }
+
+  return result;
+}
+
+function toRoman(value: number): string {
+  if (!Number.isInteger(value) || value < 1 || value > 3999) {
+    throw new RangeError(
+      `Roman counter value must be an integer between 1 and 3999, got ${value}.`,
+    );
+  }
+
+  const parts: Array<[number, string]> = [
+    [1000, "m"],
+    [900, "cm"],
+    [500, "d"],
+    [400, "cd"],
+    [100, "c"],
+    [90, "xc"],
+    [50, "l"],
+    [40, "xl"],
+    [10, "x"],
+    [9, "ix"],
+    [5, "v"],
+    [4, "iv"],
+    [1, "i"],
+  ];
+
+  let remaining = value;
+  let result = "";
+
+  for (const [amount, numeral] of parts) {
+    while (remaining >= amount) {
+      result += numeral;
+      remaining -= amount;
+    }
+  }
+
+  return result;
+}
+
+function toCjk(value: number): string {
+  if (!Number.isInteger(value) || value < 0 || value > 9999) {
+    throw new RangeError(
+      `CJK counter value must be an integer between 0 and 9999, got ${value}.`,
+    );
+  }
+
+  const digits = ["零", "一", "二", "三", "四", "五", "六", "七", "八", "九"];
+  if (value < 10) {
+    return digits[value];
+  }
+
+  const units = ["", "十", "百", "千"];
+  const chars = String(value).split("").map(Number).reverse();
+
+  let result = "";
+  let pendingZero = false;
+
+  chars.forEach((digit, index) => {
+    if (digit === 0) {
+      pendingZero = result.length > 0;
+      return;
+    }
+
+    const part = `${digits[digit]}${units[index]}`;
+    result = pendingZero ? `${part}零${result}` : `${part}${result}`;
+    pendingZero = false;
+  });
+
+  return result.replace(/^一十/, "十");
+}
+
+function readStringAttribute(
+  attrs: Record<string, string>,
+  name: string,
+): string | undefined {
+  return attrs[name];
+}
+
+function readLevelAttribute(
+  attrs: Record<string, string>,
+): LevelRef | undefined {
+  const staticLevel = readStringAttribute(attrs, "level");
+  if (staticLevel != null) {
+    return /^\d+$/.test(staticLevel) ? Number(staticLevel) : staticLevel;
+  }
+
+  const boundLevel = readStringAttribute(attrs, ":level");
+  if (boundLevel == null) {
+    return undefined;
+  }
+
+  if (/^\d+$/.test(boundLevel.trim())) {
+    return Number(boundLevel.trim());
+  }
+
+  const stringLiteral = boundLevel.trim().match(/^['"]([^'"]+)['"]$/)?.[1];
+  if (stringLiteral != null) {
+    return /^\d+$/.test(stringLiteral) ? Number(stringLiteral) : stringLiteral;
+  }
+
+  throw new Error(
+    `Counter level binding ":level=\\"${boundLevel}\\"" must be a string or number literal.`,
+  );
+}
+
+function getAction(
+  component: string,
+  actionAttribute: string | undefined,
+): CounterAction {
+  if (actionAttribute != null) {
+    if (
+      actionAttribute === "step" ||
+      actionAttribute === "increment" ||
+      actionAttribute === "display"
+    ) {
+      return actionAttribute;
+    }
+
+    throw new Error(`Counter action "${actionAttribute}" is not supported.`);
+  }
+
+  if (component === "CounterIncrement") {
+    return "increment";
+  }
+
+  if (component === "CounterDisplay") {
+    return "display";
+  }
+
+  return "step";
+}