gutterpress 0.10.7 → 0.10.8

package/dist/plugin.test.js-mv0ghv5n.tpl

@@ -0,0 +1,232 @@
+/**
+ * {{NAME}} — the plugin's own test suite.
+ *
+ *   bun install     # once — pulls the single devDependency, markdown-it
+ *   bun test
+ *
+ * Three things are checked, and it is worth knowing which is which.
+ *
+ * 1. RENDER (fixture.md → expected.html). The bespoke inline rule is an
+ *    ordinary markdown-it rule, so a plain markdown-it instance with this
+ *    plugin applied renders it exactly as a book would. This is the test that
+ *    turns "did I break my plugin" into one command.
+ *
+ *    There is deliberately no snapshot auto-update here. After an intentional
+ *    change, open `expected.html`, make the edit you meant to make, and commit
+ *    it — a diff somebody had to read is the point of the file.
+ *
+ * 2. CONTRACT. The exact export shape Gutterpress's loader requires, and the
+ *    existence of every file `gutterpress.json` declares. These catch the
+ *    failures that otherwise surface as a blank page in someone else's book.
+ *
+ * 3. CONVENTIONS. The prefix rules — every class this package emits is its
+ *    own, and none is `gp-`. Nothing in Gutterpress enforces this for you;
+ *    a collision just silently restyles somebody's book. So it is enforced
+ *    here.
+ *
+ * What this suite deliberately does NOT do: render the `@term-box` container.
+ * That container is produced by Gutterpress CORE's marker parser from the
+ * `markers` table below — plain markdown-it knows nothing about it, and this
+ * package cannot import core (see README.md, "Why you cannot import
+ * gutterpress"). So the table's CONTRACT is checked here, and the rendered
+ * container is checked by running `gutterpress preview` on a real book.
+ */
+import { describe, expect, test } from "bun:test";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import MarkdownIt from "markdown-it";
+
+import plugin, { createTermRule, markers, metadata } from "../plugin.js";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const root = path.join(here, "..");
+const read = (rel) => readFileSync(path.join(root, rel), "utf8");
+
+const pkg = JSON.parse(read("gutterpress.json"));
+const css = read("styles/plugin.css");
+/** The stylesheet's RULES — comments stripped, so a name assertion below
+ *  tests what the sheet emits rather than what it talks about. */
+const cssRules = css.replace(/\/\*[\s\S]*?\*\//g, "");
+
+/** The prefix every class and custom property this package emits must carry.
+ *  Written out here rather than imported from plugin.js on purpose: this is
+ *  the independent statement of the convention, so changing the constant in
+ *  plugin.js alone makes these tests fail instead of silently agreeing. */
+const PREFIX = "{{PREFIX}}";
+
+// ── 1. Render ───────────────────────────────────────────────────────────────
+
+describe("render", () => {
+  test("fixture.md renders to expected.html", () => {
+    // The same options Gutterpress builds its own renderer with, so what
+    // passes here behaves the same way in a real book.
+    const md = new MarkdownIt({ html: true, linkify: true, typographer: true });
+    md.use(plugin);
+
+    const actual = md.render(read("test/fixture.md"));
+    expect(actual).toBe(read("test/expected.html"));
+  });
+
+  test("plugin options can override the emitted class", () => {
+    const md = new MarkdownIt();
+    md.use(plugin, { termClass: "custom-term" });
+    expect(md.render("[[x]]")).toContain('class="custom-term"');
+  });
+
+  test("the inline rule honours markdown-it's silent mode", () => {
+    // A rule that emits tokens while `silent` is true corrupts markdown-it's
+    // link/reference probing. Easy to get wrong, invisible until it breaks
+    // somebody's footnote.
+    const rule = createTermRule("x");
+    const pushed = [];
+    const state = {
+      src: "[[term]]",
+      pos: 0,
+      posMax: 8,
+      push: (...args) => {
+        pushed.push(args);
+        return { attrSet() {} };
+      },
+    };
+    expect(rule(state, true)).toBe(true);
+    expect(pushed).toHaveLength(0);
+    expect(state.pos).toBe(8);
+  });
+});
+
+// ── 2. Contract ─────────────────────────────────────────────────────────────
+
+describe("loader contract", () => {
+  test("the default export is a plain (md, options) function", () => {
+    // CLAUDE.md §5: a Gutterpress plugin is a plain markdown-it plugin.
+    // Nothing else is accepted, and nothing else should be.
+    expect(typeof plugin).toBe("function");
+    expect(plugin.length).toBeLessThanOrEqual(2);
+  });
+
+  test("`markers` is a plain object", () => {
+    expect(typeof markers).toBe("object");
+    expect(markers).not.toBeNull();
+    expect(Array.isArray(markers)).toBe(false);
+  });
+
+  test("`metadata` carries a name", () => {
+    expect(typeof metadata?.name).toBe("string");
+    expect(metadata.name.length).toBeGreaterThan(0);
+  });
+
+  test("every path gutterpress.json declares exists", () => {
+    const declared = [
+      pkg.markdown,
+      ...(pkg.styles ?? []),
+      ...(pkg.engineStyles?.native ?? []),
+      pkg.components,
+      pkg.snippets,
+      pkg.tokensFile,
+    ].filter(Boolean);
+
+    expect(declared.length).toBeGreaterThan(0);
+    for (const rel of declared) {
+      // Gutterpress refuses to load an extension that reaches outside its own
+      // folder, so a `../` here would fail at install time, not here.
+      expect(rel.startsWith("/")).toBe(false);
+      expect(rel.split(/[\\/]/)).not.toContain("..");
+      // `existsSync`, not a read: `snippets` names a DIRECTORY.
+      expect(existsSync(path.join(root, rel))).toBe(true);
+    }
+  });
+});
+
+// ── 3. Conventions ──────────────────────────────────────────────────────────
+
+/** Every class name this package declares, from wherever it declares it. */
+function declaredClasses() {
+  const out = new Set();
+  for (const decl of Object.values(markers)) {
+    if (typeof decl?.class === "string") {
+      for (const c of decl.class.split(/\s+/).filter(Boolean)) out.add(c);
+    }
+    for (const variant of Object.values(decl?.variants ?? {})) {
+      for (const c of String(variant).split(/\s+/).filter(Boolean)) out.add(c);
+    }
+    if (typeof decl?.label?.class === "string") out.add(decl.label.class);
+  }
+  return [...out];
+}
+
+describe("conventions", () => {
+  test("every class the markers declare carries this package's prefix", () => {
+    const classes = declaredClasses();
+    expect(classes.length).toBeGreaterThan(0);
+    for (const c of classes) expect(c.startsWith(PREFIX)).toBe(true);
+  });
+
+  test("nothing emits a `gp-` class — that prefix belongs to core", () => {
+    for (const c of declaredClasses()) expect(c.startsWith("gp-")).toBe(false);
+    // Also catch a `gp-` selector added straight to the stylesheet.
+    expect(cssRules).not.toMatch(/\.gp-/);
+    expect(cssRules).not.toMatch(/--gp-/);
+  });
+
+  test("every declared class has a rule in the stylesheet", () => {
+    // A class the plugin emits but never styles is a silent no-op in every
+    // book that installs it.
+    for (const c of declaredClasses()) {
+      expect(cssRules).toContain(`.${c}`);
+    }
+  });
+
+  test("marker names are valid and do not shadow a core marker", () => {
+    // Core's names are claimed during block parsing, before any plugin runs.
+    // Declaring one of them is a hard load error — caught here first.
+    const core = [
+      "chapter", "spread", "page", "section", "continue",
+      "page-break", "column-break", "end-section",
+    ];
+    for (const name of Object.keys(markers)) {
+      expect(name).toMatch(/^[a-z][a-z0-9-]*$/);
+      expect(name.startsWith("end-")).toBe(false);
+      expect(core).not.toContain(name);
+    }
+  });
+
+  test("marker declarations use only supported fields", () => {
+    for (const [name, decl] of Object.entries(markers)) {
+      if (decl.deprecated !== undefined || decl.alias !== undefined) continue;
+      expect(typeof decl.tag === "undefined" || /^[a-z][a-z0-9-]*$/.test(decl.tag)).toBe(true);
+      for (const [variant, cls] of Object.entries(decl.variants ?? {})) {
+        expect(typeof cls).toBe("string");
+        expect(variant).toMatch(/^\S+$/);
+      }
+      if (decl.label) {
+        // "attr:<name>" is the only supported source today.
+        expect(decl.label.from).toMatch(/^attr:[A-Za-z_][A-Za-z0-9_-]*$/);
+        expect(typeof decl.label.class).toBe("string");
+      }
+      for (const at of decl.autoCloseAt ?? []) {
+        expect(at).toBe("eof");
+      }
+      expect(name).toBeTruthy();
+    }
+  });
+
+  test("every public custom property carries the prefix too", () => {
+    // `--x` declared at :root is global. An unprefixed one would collide with
+    // the book's own tokens exactly as an unprefixed class would.
+    const declaredProps = [...cssRules.matchAll(/^\s*(--[a-z0-9-]+)\s*:/gim)].map((m) => m[1]);
+    expect(declaredProps.length).toBeGreaterThan(0);
+    for (const prop of declaredProps) {
+      expect(prop.startsWith(`--${PREFIX}`)).toBe(true);
+    }
+  });
+
+  test("the stylesheet keeps all of its rules inside its own cascade layer", () => {
+    // An unlayered rule beats every layered one, including this package's
+    // own — see the header comment in styles/plugin.css.
+    expect(css).toContain("@layer {{SLUG}} {");
+    const outside = css.replace(/@layer\s+[\w-]+\s*\{[\s\S]*\}/m, "");
+    expect(outside).not.toMatch(/^[^*\/\s][^{}]*\{/m);
+  });
+});

package/dist/{preflight-jnmd4mg2.js → preflight-z6xpty9w.js}

@@ -2,16 +2,16 @@ import {
   executeValidation,
   publishTargetFor,
   reportMissingTools
-} from "./cli-kzf64c2g.js";
+} from "./cli-1hx14cgk.js";
 import {
   log
-} from "./cli-pvk2s9d7.js";
+} from "./cli-vxf151ea.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-h8ejbtyr.js";
-import"./cli-s8q42x3r.js";
+} from "./cli-vcv5ewqj.js";
+import"./cli-4vtgt2ng.js";
 import"./cli-c41yr7he.js";
 import {
   EXIT_CODES

package/dist/{preview-hsr9d12d.js → preview-xa1n7why.js}

@@ -6,10 +6,10 @@ import {
   runBuild,
   splitOutPath,
   startPreviewServer
-} from "./cli-kzf64c2g.js";
+} from "./cli-1hx14cgk.js";
 import {
   log
-} from "./cli-pvk2s9d7.js";
+} from "./cli-vxf151ea.js";
 import {
   UsageError,
   parseEngine,
@@ -18,8 +18,8 @@ import {
   rejectExtraPositionals,
   rejectUnknownFlags,
   resolvePort
-} from "./cli-h8ejbtyr.js";
-import"./cli-s8q42x3r.js";
+} from "./cli-vcv5ewqj.js";
+import"./cli-4vtgt2ng.js";
 import"./cli-c41yr7he.js";
 import {
   BuildError

package/dist/{publish-pcrrn6fd.js → publish-zgmr99kd.js}

@@ -11,17 +11,17 @@ import {
   publishProviderFor,
   resolvePublishFormat,
   runPublish
-} from "./cli-kzf64c2g.js";
+} from "./cli-1hx14cgk.js";
 import {
   FileTokenStore,
   log
-} from "./cli-pvk2s9d7.js";
+} from "./cli-vxf151ea.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-h8ejbtyr.js";
-import"./cli-s8q42x3r.js";
+} from "./cli-vcv5ewqj.js";
+import"./cli-4vtgt2ng.js";
 import"./cli-c41yr7he.js";
 import {
   EXIT_CODES

package/dist/render.js

@@ -50,7 +50,7 @@ function escapeHtml(s) {
 function escapeAttr(s) {
   return String(s).replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
-function parseMarkerLine(line) {
+function parseMarkerLine(line, declaredWords) {
   const trimmed = line.trim();
   if (!trimmed.startsWith("@"))
     return null;
@@ -84,9 +84,9 @@ function parseMarkerLine(line) {
     tokens[i] = unwrapAttrBraces(tokens[i]);
   const head = tokens[0];
   const kind = head.slice(1);
-  if (!KNOWN_KINDS.includes(kind))
+  if (!KNOWN_KINDS.includes(kind) && !(declaredWords && declaredWords.has(kind)))
     return null;
-  if (kind === "page-break" || kind === "column-break" || kind === "end-section" || kind === "continue") {
+  if (kind === "page-break" || kind === "column-break" || kind === "continue" || kind.startsWith("end-")) {
     return { kind, name: null, attrs: {} };
   }
   const body = tokens.slice(1);
@@ -189,12 +189,14 @@ function attachDataAttrs(token, kind, name, attrs) {
   if (name) {
     if (kind === "chapter")
       token.attrSet("data-chapter-label", name);
-    if (kind === "spread")
+    else if (kind === "spread")
       token.attrSet("data-spread", name);
-    if (kind === "page")
+    else if (kind === "page")
       token.attrSet("data-page", name);
-    if (kind === "section")
+    else if (kind === "section")
       token.attrSet("data-section", name);
+    else
+      token.attrSet(`data-${kind}`, name);
   }
   if (attrs.template)
     token.attrSet("data-template", attrs.template);
@@ -210,16 +212,193 @@ function attachDataAttrs(token, kind, name, attrs) {
     token.attrSet(`data-${k}`, v);
   }
 }
+var DECLARED_NAME_RE = /^[a-z][a-z0-9-]*$/;
+function validateDeclaredMarkerName(name, pluginName) {
+  if (!DECLARED_NAME_RE.test(name)) {
+    throw new Error(`Plugin "${pluginName}" declares marker "@${name}" with an invalid name — marker names must be ` + `lower-case letters, digits and hyphens, starting with a letter (like core's own "page-break").`);
+  }
+  if (name.startsWith("end-")) {
+    throw new Error(`Plugin "${pluginName}" declares marker "@${name}", but names starting with "end-" are reserved ` + `for the auto-derived closer of another declared marker (a container named "${name.slice(4)}" ` + `would collide with it). Rename this marker.`);
+  }
+}
+var TAG_NAME_RE = /^[a-z][a-z0-9-]*$/;
+function resolveContainerShape(name, pluginName, decl) {
+  const tag = decl.tag !== undefined ? decl.tag : "div";
+  if (typeof tag !== "string" || !TAG_NAME_RE.test(tag)) {
+    throw new Error(`Plugin "${pluginName}"'s marker "@${name}" has an invalid \`tag\` (${JSON.stringify(decl.tag)}) — ` + `must be a lower-case HTML tag name.`);
+  }
+  const classBase = decl.class !== undefined ? decl.class : "";
+  if (typeof classBase !== "string") {
+    throw new Error(`Plugin "${pluginName}"'s marker "@${name}" has a \`class\` that is not a string.`);
+  }
+  let variants;
+  if (decl.variants !== undefined) {
+    if (typeof decl.variants !== "object" || decl.variants === null || Array.isArray(decl.variants)) {
+      throw new Error(`Plugin "${pluginName}"'s marker "@${name}" has \`variants\` that is not a plain object.`);
+    }
+    variants = {};
+    for (const [variantName, variantClass] of Object.entries(decl.variants)) {
+      if (typeof variantClass !== "string") {
+        throw new Error(`Plugin "${pluginName}"'s marker "@${name}" variant "${variantName}" is not a string.`);
+      }
+      variants[variantName] = variantClass;
+    }
+  }
+  let label;
+  if (decl.label !== undefined) {
+    if (typeof decl.label !== "object" || decl.label === null || Array.isArray(decl.label)) {
+      throw new Error(`Plugin "${pluginName}"'s marker "@${name}" has a \`label\` that is not an object.`);
+    }
+    if (typeof decl.label.class !== "string" || !decl.label.class) {
+      throw new Error(`Plugin "${pluginName}"'s marker "@${name}" has a \`label.class\` that is not a non-empty string.`);
+    }
+    const match = typeof decl.label.from === "string" ? /^attr:([A-Za-z_][A-Za-z0-9_-]*)$/.exec(decl.label.from) : null;
+    if (!match) {
+      throw new Error(`Plugin "${pluginName}"'s marker "@${name}" has a \`label.from\` (${JSON.stringify(decl.label.from)}) that is not "attr:<name>" — that is the only supported form today.`);
+    }
+    const labelTag = decl.label.tag !== undefined ? decl.label.tag : "div";
+    if (typeof labelTag !== "string" || !TAG_NAME_RE.test(labelTag)) {
+      throw new Error(`Plugin "${pluginName}"'s marker "@${name}" has an invalid \`label.tag\` (${JSON.stringify(decl.label.tag)}).`);
+    }
+    label = { class: decl.label.class, attr: match[1], tag: labelTag };
+  }
+  let autoCloseAtEof = false;
+  if (decl.autoCloseAt !== undefined) {
+    if (!Array.isArray(decl.autoCloseAt)) {
+      throw new Error(`Plugin "${pluginName}"'s marker "@${name}" has an \`autoCloseAt\` that is not an array.`);
+    }
+    for (const value of decl.autoCloseAt) {
+      if (value !== "eof") {
+        throw new Error(`Plugin "${pluginName}"'s marker "@${name}" declares an unsupported \`autoCloseAt\` value ` + `${JSON.stringify(value)} — only "eof" is currently supported.`);
+      }
+    }
+    autoCloseAtEof = decl.autoCloseAt.includes("eof");
+  }
+  return { tag, classBase, variants, label, autoCloseAtEof };
+}
+function resolveMarkerDeclaration(name, rawDecl, rawRegistry, originOf) {
+  const pluginName = originOf.get(name);
+  if (typeof rawDecl !== "object" || rawDecl === null || Array.isArray(rawDecl)) {
+    throw new Error(`Plugin "${pluginName}"'s marker "@${name}" is not a plain object.`);
+  }
+  if (rawDecl.deprecated !== undefined) {
+    if (typeof rawDecl.deprecated !== "string" || !rawDecl.deprecated) {
+      throw new Error(`Plugin "${pluginName}"'s marker "@${name}" has a \`deprecated\` value that is not a non-empty string.`);
+    }
+    return { name, deprecated: rawDecl.deprecated };
+  }
+  if (rawDecl.alias !== undefined) {
+    if (typeof rawDecl.alias !== "string" || !rawDecl.alias) {
+      throw new Error(`Plugin "${pluginName}"'s marker "@${name}" has an \`alias\` value that is not a non-empty string.`);
+    }
+    const targetRaw = rawRegistry.get(rawDecl.alias);
+    if (!targetRaw) {
+      throw new Error(`Plugin "${pluginName}"'s marker "@${name}" aliases unknown marker "@${rawDecl.alias}" — no ` + `loaded plugin declares it.`);
+    }
+    if (targetRaw.deprecated !== undefined) {
+      throw new Error(`Plugin "${pluginName}"'s marker "@${name}" aliases "@${rawDecl.alias}", which is deprecated: ` + `${targetRaw.deprecated}`);
+    }
+    if (targetRaw.alias !== undefined) {
+      throw new Error(`Plugin "${pluginName}"'s marker "@${name}" aliases "@${rawDecl.alias}", which is itself an alias. ` + `Chained aliases are not supported — alias the base marker directly.`);
+    }
+    const preset = rawDecl.preset !== undefined ? rawDecl.preset : {};
+    if (typeof preset !== "object" || preset === null || Array.isArray(preset)) {
+      throw new Error(`Plugin "${pluginName}"'s marker "@${name}" has a \`preset\` that is not a plain object.`);
+    }
+    if (preset.variant !== undefined && typeof preset.variant !== "string") {
+      throw new Error(`Plugin "${pluginName}"'s marker "@${name}" has a \`preset.variant\` that is not a string.`);
+    }
+    const container = resolveContainerShape(rawDecl.alias, originOf.get(rawDecl.alias), targetRaw);
+    return { name, baseKind: rawDecl.alias, presetVariant: preset.variant, ...container };
+  }
+  return { name, baseKind: name, ...resolveContainerShape(name, pluginName, rawDecl) };
+}
+function buildDeclaredMarkerRegistry(sources) {
+  const rawRegistry = new Map;
+  const originOf = new Map;
+  for (const { pluginName, markers } of sources) {
+    if (!markers)
+      continue;
+    for (const [name, rawDecl] of Object.entries(markers)) {
+      validateDeclaredMarkerName(name, pluginName);
+      if (KNOWN_KINDS.includes(name)) {
+        throw new Error(`Plugin "${pluginName}" declares marker "@${name}", which is a core Gutterpress marker name ` + `(${KNOWN_KINDS.map((k) => `@${k}`).join(", ")}). Core marker names cannot be shadowed — ` + `rename the plugin's marker.`);
+      }
+      if (rawRegistry.has(name)) {
+        throw new Error(`Marker "@${name}" is declared by both plugin "${originOf.get(name)}" and plugin "${pluginName}". ` + `Declared marker names must be unique across every loaded plugin — rename one of them.`);
+      }
+      rawRegistry.set(name, rawDecl);
+      originOf.set(name, pluginName);
+    }
+  }
+  const resolved = new Map;
+  for (const [name, rawDecl] of rawRegistry) {
+    resolved.set(name, resolveMarkerDeclaration(name, rawDecl, rawRegistry, originOf));
+  }
+  return resolved;
+}
+function declaredKindWords(declaredMarkers) {
+  if (!declaredMarkers)
+    return null;
+  const words = new Set;
+  for (const name of declaredMarkers.keys()) {
+    words.add(name);
+    words.add(`end-${name}`);
+  }
+  return words;
+}
+function nearestDeclaredMarkerName(word, declaredMarkers) {
+  const w = word.toLowerCase();
+  const threshold = Math.max(2, Math.floor(w.length / 3));
+  let best = null;
+  let bestDistance = Infinity;
+  for (const known of declaredMarkers.keys()) {
+    const d = editDistance(w, known);
+    if (d < bestDistance) {
+      bestDistance = d;
+      best = known;
+    }
+  }
+  return best !== null && bestDistance > 0 && bestDistance <= threshold ? best : null;
+}
+function scanForUnknownDeclaredMarkers(state, declaredMarkers) {
+  if (!declaredMarkers)
+    return;
+  for (let tokenIndex = 0;tokenIndex < state.tokens.length; tokenIndex++) {
+    const tok = state.tokens[tokenIndex];
+    if (tok.type !== "inline" || !tok.map)
+      continue;
+    const opener = state.tokens[tokenIndex - 1];
+    if (!opener || opener.type !== "paragraph_open")
+      continue;
+    const lines = tok.content.split(`
+`);
+    for (let i = 0;i < lines.length; i++) {
+      const m = /^@([A-Za-z][A-Za-z0-9-]*)(?=\s|$)/.exec(lines[i].trim());
+      if (!m)
+        continue;
+      const word = m[1];
+      if (KNOWN_KINDS.includes(word) || declaredMarkers.has(word))
+        continue;
+      const suggestion = nearestDeclaredMarkerName(word, declaredMarkers);
+      if (!suggestion)
+        continue;
+      warn(state.env, tok.map[0] + i + 1, "unknown_marker", `Unknown marker "@${word}". Did you mean "@${suggestion}"?`, null);
+    }
+  }
+}
 function plugin(md, pluginOptions = {}) {
   const options = {
     preferPagesInSpreads: false,
     ...pluginOptions
   };
+  const declaredMarkers = options.declaredMarkers instanceof Map && options.declaredMarkers.size > 0 ? options.declaredMarkers : null;
+  const declaredWords = declaredKindWords(declaredMarkers);
   function markerBlock(state, startLine, endLine, silent) {
     const pos = state.bMarks[startLine] + state.tShift[startLine];
     const max = state.eMarks[startLine];
     const line = state.src.slice(pos, max);
-    const parsed = parseMarkerLine(line);
+    const parsed = parseMarkerLine(line, declaredWords);
     if (!parsed)
       return false;
     if (silent)
@@ -276,10 +455,64 @@ function plugin(md, pluginOptions = {}) {
     }
   }
   md.core.ruler.after("block", "layout_transform", function(state) {
+    scanForUnknownDeclaredMarkers(state, declaredMarkers);
     if (!state.env.__layoutMarkersUsed)
       return;
     scanForMistypedMarkers(state);
     const out = [];
+    const declaredFrames = [];
+    function declaredFrameIndex(kind) {
+      for (let i = declaredFrames.length - 1;i >= 0; i--) {
+        if (declaredFrames[i].kind === kind)
+          return i;
+      }
+      return -1;
+    }
+    function closeDeclaredFrame(kind) {
+      const at = declaredFrameIndex(kind);
+      if (at === -1)
+        return false;
+      while (declaredFrames.length > at) {
+        const frame = declaredFrames.pop();
+        out.push(new state.Token("layout_component_close", frame.tag, -1));
+      }
+      return true;
+    }
+    function drainDeclaredFrames() {
+      while (declaredFrames.length) {
+        const frame = declaredFrames.pop();
+        out.push(new state.Token("layout_component_close", frame.tag, -1));
+      }
+    }
+    function drainDeclaredFramesAtEof() {
+      while (declaredFrames.length) {
+        const frame = declaredFrames.pop();
+        if (!frame.decl.autoCloseAtEof) {
+          warn(state.env, frame.line || 0, "declared_marker_eof_close", `An open @${frame.kind} reached end-of-document; closing it automatically. Add ` + `@end-${frame.kind} to close it explicitly, or declare autoCloseAt: ["eof"] on this ` + `marker if running to end-of-document is expected.`, null);
+        }
+        out.push(new state.Token("layout_component_close", frame.tag, -1));
+      }
+    }
+    function openDeclaredMarker(meta, decl) {
+      const t = new state.Token("layout_component_open", decl.tag, 1);
+      t.meta = { line: meta.__line };
+      const variant = meta.name || decl.presetVariant || null;
+      const variantClass = variant && decl.variants && decl.variants[variant] || "";
+      const baseClass = [decl.classBase, variantClass].filter(Boolean).join(" ");
+      addClasses(t, baseClass, meta.attrs && meta.attrs.class ? meta.attrs.class : "");
+      attachDataAttrs(t, decl.baseKind, variant, meta.attrs || {});
+      out.push(t);
+      declaredFrames.push({ kind: decl.baseKind, tag: decl.tag, decl, line: meta.__line });
+      if (decl.label) {
+        const value = meta.attrs && meta.attrs[decl.label.attr];
+        if (value) {
+          const labelToken = new state.Token("html_block", "", 0);
+          labelToken.content = `<${decl.label.tag} class="${escapeAttr(decl.label.class)}">${escapeHtml(value)}</${decl.label.tag}>
+`;
+          out.push(labelToken);
+        }
+      }
+    }
     const stack = {
       frames: [],
       get(kind) {
@@ -429,6 +662,7 @@ function plugin(md, pluginOptions = {}) {
       const kind = meta.kind;
       const line = meta.__line || 0;
       if (kind === "chapter") {
+        drainDeclaredFrames();
         stack.close("chapter");
         openChapter(meta);
         continue;
@@ -437,16 +671,19 @@ function plugin(md, pluginOptions = {}) {
         if (stack.has("spread")) {
           warn(state.env, line, "nested_spread", "@spread encountered while another spread is open; closing the previous spread automatically.", meta);
         }
+        drainDeclaredFrames();
         stack.close("spread");
         openSpread(meta);
         continue;
       }
       if (kind === "page") {
+        drainDeclaredFrames();
         stack.close("page");
         openPage(meta);
         continue;
       }
       if (kind === "section") {
+        drainDeclaredFrames();
         warnIfEmptyDecoratedSection("section", line);
         stack.close("section");
         const spread = stack.get("spread");
@@ -462,6 +699,7 @@ function plugin(md, pluginOptions = {}) {
           warn(state.env, line, "continue_without_section", "@continue used without an open @section; ignoring marker.", meta);
           continue;
         }
+        drainDeclaredFrames();
         const contMeta = {
           name: section.meta.name,
           attrs: { ...section.meta.attrs || {} }
@@ -494,15 +732,42 @@ function plugin(md, pluginOptions = {}) {
         continue;
       }
       if (kind === "end-section") {
+        drainDeclaredFrames();
         warnIfEmptyDecoratedSection("end-section", line);
         stack.close("section");
         continue;
       }
+      if (declaredMarkers) {
+        const openDecl = declaredMarkers.get(kind);
+        if (openDecl) {
+          if (openDecl.deprecated) {
+            warn(state.env, line, "deprecated_marker", `@${kind} is deprecated: ${openDecl.deprecated}`, meta);
+            continue;
+          }
+          closeDeclaredFrame(openDecl.baseKind);
+          openDeclaredMarker(meta, openDecl);
+          continue;
+        }
+        if (kind.startsWith("end-")) {
+          const closeDecl = declaredMarkers.get(kind.slice(4));
+          if (closeDecl) {
+            if (closeDecl.deprecated) {
+              warn(state.env, line, "deprecated_marker", `@${kind} is deprecated: ${closeDecl.deprecated}`, meta);
+              continue;
+            }
+            if (!closeDeclaredFrame(closeDecl.baseKind)) {
+              warn(state.env, line, "declared_marker_close_without_open", `@${kind} used without an open @${closeDecl.baseKind}; ignoring marker.`, meta);
+            }
+            continue;
+          }
+        }
+      }
     }
     const eofSpread = stack.get("spread");
     if (eofSpread && !eofSpread.sawAnyPage) {
       warn(state.env, 0, "spread_eof_close", "An open @spread reached end-of-document; closing it automatically.", null);
     }
+    drainDeclaredFramesAtEof();
     stack.closeAll();
     state.tokens = out;
   });
@@ -1538,7 +1803,9 @@ function createMarkdownRenderer(customPlugins) {
   md.use(unwrapPlugin(markdownItFootnote));
   md.use(unwrapPlugin(markdownItDeflist));
   md.use(unwrapPlugin(markdownItSourceMap));
-  md.use(plugin);
+  const declaredMarkerSources = (customPlugins ?? []).filter((p) => !!p.markers).map((p) => ({ pluginName: p.name, markers: p.markers }));
+  const declaredMarkers = buildDeclaredMarkerRegistry(declaredMarkerSources);
+  md.use(plugin, { declaredMarkers });
   md.use(gpPinScope);
   registerImageRule(md);
   if (customPlugins && customPlugins.length > 0) {