gutterpress 0.11.17-alpha.6 → 0.11.17-alpha.7

package/dist/{index-2vd5b3vy.js → index-k0k4syyd.js}

@@ -1184,18 +1184,53 @@ var CORE_DECLARED_MARKERS = {
     class: "gp-columns",
     preset: { variant: "2" },
     variants: { 1: "gp-columns-1", 2: "gp-columns-2", 3: "gp-columns-3", 4: "gp-columns-4", 5: "gp-columns-5" }
-  }
+  },
+  page: { variants: { blank: "gp-page-blank", "full-bleed": "gp-page-full-bleed" } }
 };
+var LOCATION_KINDS = ["page", "chapter", "section"];
+var LOCATION_KEYS = ["variants", "label", "snippet"];
+function isLocationDeclaration(name, rawDecl) {
+  return LOCATION_KINDS.includes(name) && rawDecl !== null && typeof rawDecl === "object" && !Array.isArray(rawDecl) && Object.hasOwn(rawDecl, "variants") && Object.keys(rawDecl).every((k) => LOCATION_KEYS.includes(k));
+}
+function addLocationVariants(kind, rawDecl, pluginName, into) {
+  const { variants, label, snippet } = rawDecl;
+  const where = `Plugin "${pluginName}" declares @${kind} variants`;
+  if (variants === null || typeof variants !== "object" || Array.isArray(variants)) {
+    throw new Error(`${where} that are not a plain object of { word: 'class' }.`);
+  }
+  if (label !== undefined && typeof label !== "string")
+    throw new Error(`${where} with a \`label\` that is not a string.`);
+  if (snippet !== undefined && typeof snippet !== "string")
+    throw new Error(`${where} with a \`snippet\` that is not a string.`);
+  for (const [word, cls] of Object.entries(variants)) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(word)) {
+      throw new Error(`${where} with an invalid word "${word}" — use letters, digits, hyphens and underscores.`);
+    }
+    if (typeof cls !== "string" || !cls.trim()) {
+      throw new Error(`${where}: variant "${word}" needs a non-empty class string.`);
+    }
+    const taken = into[kind].get(word);
+    if (taken) {
+      throw new Error(`@${kind} variant "${word}" is declared by both plugin "${taken.owner}" and plugin "${pluginName}". ` + `Variant words must be unique across every loaded plugin — rename one of them.`);
+    }
+    into[kind].set(word, { class: cls.trim(), owner: pluginName, ...label ? { label } : {}, ...snippet ? { snippet } : {} });
+  }
+}
 function buildDeclaredMarkerRegistry(sources) {
   const rawRegistry = new Map;
   const originOf = new Map;
+  const locationVariants = { page: new Map, chapter: new Map, section: new Map };
   for (const { pluginName, markers } of [{ pluginName: CORE_MARKER_OWNER, markers: CORE_DECLARED_MARKERS }, ...sources]) {
     if (!markers)
       continue;
     for (const [name, rawDecl] of Object.entries(markers)) {
       validateDeclaredMarkerName(name, pluginName);
+      if (isLocationDeclaration(name, rawDecl)) {
+        addLocationVariants(name, rawDecl, pluginName, locationVariants);
+        continue;
+      }
       if (KNOWN_KINDS.includes(name) || pluginName !== CORE_MARKER_OWNER && name in CORE_DECLARED_MARKERS) {
-        throw new Error(`Plugin "${pluginName}" declares marker "@${name}", which is a core Gutterpress marker name ` + `(${[...KNOWN_KINDS, ...Object.keys(CORE_DECLARED_MARKERS)].map((k) => `@${k}`).join(", ")}). ` + `Core marker names cannot be shadowed — ` + `rename the plugin's marker.`);
+        throw new Error(`Plugin "${pluginName}" declares marker "@${name}", which is a core Gutterpress marker name ` + `(${[...KNOWN_KINDS, ...Object.keys(CORE_DECLARED_MARKERS).filter((k) => !KNOWN_KINDS.includes(k))].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.`);
@@ -1208,6 +1243,7 @@ function buildDeclaredMarkerRegistry(sources) {
   for (const [name, rawDecl] of rawRegistry) {
     resolved.set(name, resolveMarkerDeclaration(name, rawDecl, rawRegistry, originOf));
   }
+  resolved.locationVariants = locationVariants;
   return resolved;
 }
 function declaredKindWords(declaredMarkers) {
@@ -1263,6 +1299,9 @@ function scanForUnknownDeclaredMarkers(state, declaredMarkers) {
 function variantClassFor(decl, word) {
   return word && decl.variants && Object.hasOwn(decl.variants, word) ? decl.variants[word] : "";
 }
+function nearVariant(word, variants) {
+  return variants.find((v) => v.toLowerCase() === word.toLowerCase()) || (word.length >= 3 ? nearestDeclaredMarkerName(word, variants) : null);
+}
 function warnUnknownVariant(env, meta, decl) {
   const word = meta.name;
   if (!word)
@@ -1270,9 +1309,16 @@ function warnUnknownVariant(env, meta, decl) {
   const variants = Object.keys(decl.variants || {});
   if (variants.includes(word))
     return;
-  const near = variants.find((v) => v.toLowerCase() === word.toLowerCase()) || (word.length >= 3 ? nearestDeclaredMarkerName(word, variants) : null);
+  const near = nearVariant(word, variants);
   warn(env, meta.__line, "unknown_variant", `"${word}" is not a variant of @${meta.kind}, so it adds no styling. ` + (variants.length ? `Variants: ${variants.join(", ")}.` : `@${meta.kind} has no variants.`) + (near ? ` Did you mean "${near}"?` : ""), meta);
 }
+function warnNearMissVariant(env, meta, kind, variants) {
+  const words = [...variants.keys()];
+  const near = nearVariant(meta.name, words);
+  if (!near)
+    return;
+  warn(env, meta.__line, "unknown_variant", `"${meta.name}" is not a variant of @${kind}, so it is only a ${kind} name and adds no styling. ` + `Variants: ${words.join(", ")}. Did you mean "${near}"?`, meta);
+}
 function plugin(md, pluginOptions = {}) {
   const options = {
     preferPagesInSpreads: false,
@@ -1280,6 +1326,7 @@ function plugin(md, pluginOptions = {}) {
   };
   const declaredMarkers = options.declaredMarkers instanceof Map && options.declaredMarkers.size > 0 ? options.declaredMarkers : buildDeclaredMarkerRegistry([]);
   const declaredWords = declaredKindWords(declaredMarkers);
+  const locationVariants = declaredMarkers.locationVariants || buildDeclaredMarkerRegistry([]).locationVariants;
   function markerBlock(state, startLine, endLine, silent) {
     const pos = state.bMarks[startLine] + state.tShift[startLine];
     const max = state.eMarks[startLine];
@@ -1463,14 +1510,16 @@ function plugin(md, pluginOptions = {}) {
     function openChapter(meta) {
       const t = new state.Token("layout_chapter_open", "div", 1);
       t.meta = { line: meta.__line };
-      const classes = meta.attrs?.class || "";
+      const variant = locationVariants.chapter.get(meta.name);
+      const label = variant ? "" : meta.name;
+      const classes = [variant?.class, meta.attrs?.class].filter(Boolean).join(" ");
       addClasses(t, "chapter", classes);
-      attachDataAttrs(t, "chapter", meta.name, meta.attrs || {});
+      attachDataAttrs(t, "chapter", label, meta.attrs || {});
       const explicit = (classes.match(/(?:^|\s)(chapter-\d+)(?=\s|$)/) || [])[1] || "";
       const fromAttr = meta.attrs?.ch ? `chapter-${meta.attrs.ch}` : "";
       stack.open({
         kind: "chapter",
-        label: meta.name || "",
+        label: label || "",
         counterClass: explicit || fromAttr,
         openerEmitted: false
       }, t);
@@ -1494,7 +1543,11 @@ function plugin(md, pluginOptions = {}) {
       const explicit = meta.attrs && meta.attrs.class ? meta.attrs.class : "";
       const counterClass = chapter ? chapter.counterClass : "";
       const tokens = explicit ? explicit.split(/\s+/) : [];
-      const merged = counterClass && !tokens.includes(counterClass) ? explicit ? `${explicit} ${counterClass}` : counterClass : explicit;
+      const withCounter = counterClass && !tokens.includes(counterClass) ? explicit ? `${explicit} ${counterClass}` : counterClass : explicit;
+      const variant = locationVariants.page.get(meta.name);
+      if (!variant && meta.name)
+        warnNearMissVariant(state.env, meta, "page", locationVariants.page);
+      const merged = [variant?.class, withCounter].filter(Boolean).join(" ");
       addClasses(t, "page", merged);
       attachDataAttrs(t, "page", meta.name, meta.attrs || {});
       const label = chapter ? chapter.label : "";
@@ -1533,7 +1586,8 @@ function plugin(md, pluginOptions = {}) {
     function openSection(meta, inColumns = false) {
       const t = new state.Token("layout_section_open", "div", 1);
       const component = meta.__component || null;
-      addClasses(t, "section", meta.attrs && meta.attrs.class ? meta.attrs.class : "");
+      const variant = component ? null : locationVariants.section.get(meta.name);
+      addClasses(t, "section", [variant?.class, meta.attrs && meta.attrs.class].filter(Boolean).join(" "));
       if (component)
         attachDataAttrs(t, component.kind, component.variant, meta.attrs || {});
       else
@@ -1620,6 +1674,9 @@ function plugin(md, pluginOptions = {}) {
         if (spread && spread.noPagesYet) {
           warn(state.env, line, "spread_without_pages", "@section inside a spread without an explicit @page. Allowed (adhoc spread), but explicit @page markers give stronger control.", meta);
         }
+        if (meta.name && !locationVariants.section.has(meta.name)) {
+          warnNearMissVariant(state.env, meta, "section", locationVariants.section);
+        }
         openSection(meta, keep > 0);
         continue;
       }
@@ -1744,6 +1801,25 @@ function plugin(md, pluginOptions = {}) {
   };
   md.renderer.rules.layout_marker = () => "";
 }
+var NO_MARGIN_BOXES = [
+  "top-left-corner",
+  "top-left",
+  "top-center",
+  "top-right",
+  "top-right-corner",
+  "bottom-left-corner",
+  "bottom-left",
+  "bottom-center",
+  "bottom-right",
+  "bottom-right-corner",
+  "left-top",
+  "left-middle",
+  "left-bottom",
+  "right-top",
+  "right-middle",
+  "right-bottom"
+].map((box) => `  @${box} { content: none; }`).join(`
+`);
 var MARKER_CSS = `
 /* The UA default of 8px body margin is a screen affordance with no meaning
    in paged media, and engines disagree about it: a polyfill that treats the
@@ -1778,6 +1854,34 @@ body { margin: 0; }
 :where(p) > :where(img:not([class])) { max-height: calc(var(--gp-content-h) - 4px); object-fit: contain; }
 :where(figure) { break-inside: avoid; }
 
+/* Core page variants — \`@page blank\` and \`@page full-bleed\` (CORE_DECLARED_MARKERS).
+   Each is the \`.page\` the marker already emits plus one class; the class
+   assigns the page to a NAMED page, and the named \`@page\` block below is
+   plain CSS Paged Media. Authors never write these names.
+
+   SPEC GAP FILLED: none. Named pages (\`@page <name>\`, \`page:\`) and margin
+   box \`content: none\` are standard and implemented in Chromium; this is
+   author vocabulary that expands to them (permanent, like @columns), not a
+   shim, so nothing here is deleted when Chrome catches up. Both pages are
+   named \`gp-\`, which the shrink-to-fit audit (engine/compiler/build.ts)
+   leaves out of its per-page limits, so they cannot loosen it for other pages.
+
+   The folio still COUNTS on these pages (only what is drawn is cleared), and
+   a book that assigns \`page:\` to every \`.page\` in its own unlayered CSS
+   overrides the assignment, as any unlayered rule overrides this layer. */
+@page gp-page-blank {
+${NO_MARGIN_BOXES}
+}
+.page.gp-page-blank { page: gp-page-blank; }
+
+/* full-bleed: zero page margin, so the content box IS the sheet. The margin
+   boxes are cleared too — with zero margins they would land on the trim line. */
+@page gp-page-full-bleed {
+  margin: 0;
+${NO_MARGIN_BOXES}
+}
+.page.gp-page-full-bleed { page: gp-page-full-bleed; }
+
 `;
 
 // src/lib/markdown/gutterpress-css.ts
@@ -2021,6 +2125,8 @@ var GP_CLASSES = new Set([
   "gp-columns-3",
   "gp-columns-4",
   "gp-columns-5",
+  "gp-page-blank",
+  "gp-page-full-bleed",
   "gp-no-break",
   "gp-break-before",
   "gp-shape",
@@ -5641,7 +5747,7 @@ import git from "isomorphic-git";
 // package.json
 var package_default = {
   name: "gutterpress",
-  version: "0.11.17-alpha.6",
+  version: "0.11.17-alpha.7",
   description: "Markdown-to-PDF converter for professional print layout using a native Chromium print engine and Ghostscript.",
   author: "itlackey",
   license: "MPL-2.0",
@@ -12594,8 +12700,11 @@ async function collectLibrary(projectDir) {
     loaded.push({ entry, source, folder, snippets: snippets2, markers: await declaredMarkers(entry, projectDir) });
   }
   let registry;
+  let variantRegistry = buildDeclaredMarkerRegistry([]).locationVariants;
   try {
-    registry = buildDeclaredMarkerRegistry(loaded.flatMap((l) => l.markers ? [{ pluginName: l.entry.label, markers: l.markers }] : []));
+    const built = buildDeclaredMarkerRegistry(loaded.flatMap((l) => l.markers ? [{ pluginName: l.entry.label, markers: l.markers }] : []));
+    registry = built;
+    variantRegistry = built.locationVariants;
   } catch {
     registry = undefined;
   }
@@ -12661,7 +12770,23 @@ async function collectLibrary(projectDir) {
       component.snippet = best.body;
   }
   components.sort((a, b) => a.name.localeCompare(b.name));
-  return { snippets, components };
+  const sourceOf = new Map(loaded.map((l) => [l.entry.label, l.source]));
+  const locationVariants = [];
+  for (const kind of ["page", "chapter", "section"]) {
+    for (const [word, v] of variantRegistry[kind]) {
+      const source = sourceOf.get(v.owner) ?? { kind: "core" };
+      locationVariants.push({
+        kind,
+        word,
+        class: v.class,
+        source,
+        ...v.label ? { label: v.label } : {},
+        ...v.snippet ? { snippet: v.snippet } : {}
+      });
+    }
+  }
+  locationVariants.sort((a, b) => a.kind.localeCompare(b.kind) || a.word.localeCompare(b.word));
+  return { snippets, components, locationVariants };
 }
 async function listMergedSnippets(projectDir) {
   return (await collectLibrary(projectDir)).snippets;
@@ -12669,6 +12794,9 @@ async function listMergedSnippets(projectDir) {
 async function listMarkerComponents(projectDir) {
   return (await collectLibrary(projectDir)).components;
 }
+async function listLocationVariants(projectDir) {
+  return (await collectLibrary(projectDir)).locationVariants;
+}
 // src/lib/extension-import.ts
 import { existsSync as existsSync16 } from "node:fs";
 import { cp as cp4, mkdir as mkdir13, mkdtemp as mkdtemp2, readFile as readFile34, rm as rm5, writeFile as writeFile13 } from "node:fs/promises";
@@ -16871,4 +16999,4 @@ async function setPublishProviderConfig(projectDir, providerId, values) {
   await writeManifestDoc(file, doc);
   return settingsFromDoc(doc);
 }
-export { BUNDLED_EXTENSIONS, isBundledExtension, isPathSpecifier, parseExtensionSpecifier, PRESET_IDS, PRESETS, TARGETS, TARGET_IDS, publishTargetFor, MANIFEST_FILENAMES, hasProjectManifest, loadManifest, loadManifestWithPath, resolveConfig, SYNC_SNAPSHOT_MESSAGE, log, resolveActiveStyles, listProjectStyles, EXTENSION_MANIFEST_FILENAME, readExtensionMeta, extensionStyleList, extensionEntry, extensionCarries, pathEscapesFolder, assertExtensionContained, resolveExtension, DEFAULT_NPM_REGISTRY, npmRegistryUrl, ensureProjectGitignore, EXTENSIONS_DIR, RECOMMENDED_EXTENSIONS, BUILT_IN_STYLE_SET_IDS, sameExtension, listProjectExtensions, describeExtension, setExtensionEnabled, reorderExtensions, removeExtension, addExtension, listNpmVersions, checkExtensionUpdates, updateExtensions, listBuiltInStyleSets, addBuiltInStyleSet, validateProjectExtensions, readExtensionCss, restorePinnedExtensions, restoreFailureMessage, getChecks, getCheckById, resolveCheckSelectors, formatReport, ruleRemoteUrls, ruleRiskyProps, ruleSyntax, checkCss, inspectImage, runChecks, checkToolAvailability, reportMissingTools, executeValidation, executeAndReport, splitOutPath, runBuild, openPath, startPreviewServer, defaultConfigDir, FileTokenStore, extractUrlCredential, getSystemDiagnostics, readPageSetup, setPageSetup, slugifyProjectName, escapeYamlScalar, scaffoldProject, adoptFolder, EXTENSION_KINDS, RESERVED_PREFIX, resolveExtensionPrefix, scaffoldExtension, BUILT_IN_TEMPLATE_IDS, listBuiltInTemplates, saveProjectAsTemplate, listCustomTemplates, importTemplateFromFolder, SNIPPETS_DIR, extractVariables, substituteVariables, listSnippets, saveSnippet, deleteSnippet, listMergedSnippets, listMarkerComponents, importExtensionFromFile, importExtensionFromUrl, MAX_SEARCH_BYTES, SEARCH_KEYWORDS, searchNpmExtensions, setManifestFields, readManifestFields, setActiveStyles, AUTO_SNAPSHOT_DEFAULT_MINUTES, AUTO_SYNC_MIN_MINUTES, AUTO_SYNC_MAX_MINUTES, AUTO_SYNC_DEFAULT_MINUTES, AUTO_SYNC_PUSH_INTERVAL_MINUTES, autoSnapshotDelayMs, autoSyncDelayMs, isGitInternalPath, resolveGitHubClientId, GITHUB_HOST, GitHubAuthProvider, GDRIVE_HOST, resolveGoogleClientId, resolveGoogleClientSecret, GOOGLE_NOT_CONFIGURED_MESSAGE, requireGoogleClientCredentials, pkceChallengeFromVerifier, GoogleAuthProvider, revokeGoogleCredential, publishCredentialKey, publishConnectionStatus, listPublishAccounts, connectGoogleDrive, listGitHubRepositories, listRepoBooks, listGitHubBranches, syncProject, refreshRemoteCopies, isValidRepositoryName, setUpOnlineBackup, sanitizeCloneFolderName, cloneRepository, isSshRemoteUrl, testRemoteAccess, knownForgeTokenUrl, connectGenericHost, parseRemoteOrigin, forgeKindForHost, diagnoseProjectRemote, REPAIR_SNAPSHOT_MESSAGE, repairOnlineBackup, scorchedEarth, listPublishProviders, publishProviderFor, resolvePublishFormat, resolvePublishRequest, runPublish, connectPublishProvider, disconnectPublishCredential, PublishSelectionsStore, readPublishSettings, setPublishProviderConfig };
+export { BUNDLED_EXTENSIONS, isBundledExtension, isPathSpecifier, parseExtensionSpecifier, PRESET_IDS, PRESETS, TARGETS, TARGET_IDS, publishTargetFor, MANIFEST_FILENAMES, hasProjectManifest, loadManifest, loadManifestWithPath, resolveConfig, SYNC_SNAPSHOT_MESSAGE, log, resolveActiveStyles, listProjectStyles, EXTENSION_MANIFEST_FILENAME, readExtensionMeta, extensionStyleList, extensionEntry, extensionCarries, pathEscapesFolder, assertExtensionContained, resolveExtension, DEFAULT_NPM_REGISTRY, npmRegistryUrl, ensureProjectGitignore, EXTENSIONS_DIR, RECOMMENDED_EXTENSIONS, BUILT_IN_STYLE_SET_IDS, sameExtension, listProjectExtensions, describeExtension, setExtensionEnabled, reorderExtensions, removeExtension, addExtension, listNpmVersions, checkExtensionUpdates, updateExtensions, listBuiltInStyleSets, addBuiltInStyleSet, validateProjectExtensions, readExtensionCss, restorePinnedExtensions, restoreFailureMessage, getChecks, getCheckById, resolveCheckSelectors, formatReport, ruleRemoteUrls, ruleRiskyProps, ruleSyntax, checkCss, inspectImage, runChecks, checkToolAvailability, reportMissingTools, executeValidation, executeAndReport, splitOutPath, runBuild, openPath, startPreviewServer, defaultConfigDir, FileTokenStore, extractUrlCredential, getSystemDiagnostics, readPageSetup, setPageSetup, slugifyProjectName, escapeYamlScalar, scaffoldProject, adoptFolder, EXTENSION_KINDS, RESERVED_PREFIX, resolveExtensionPrefix, scaffoldExtension, BUILT_IN_TEMPLATE_IDS, listBuiltInTemplates, saveProjectAsTemplate, listCustomTemplates, importTemplateFromFolder, SNIPPETS_DIR, extractVariables, substituteVariables, listSnippets, saveSnippet, deleteSnippet, listMergedSnippets, listMarkerComponents, listLocationVariants, importExtensionFromFile, importExtensionFromUrl, MAX_SEARCH_BYTES, SEARCH_KEYWORDS, searchNpmExtensions, setManifestFields, readManifestFields, setActiveStyles, AUTO_SNAPSHOT_DEFAULT_MINUTES, AUTO_SYNC_MIN_MINUTES, AUTO_SYNC_MAX_MINUTES, AUTO_SYNC_DEFAULT_MINUTES, AUTO_SYNC_PUSH_INTERVAL_MINUTES, autoSnapshotDelayMs, autoSyncDelayMs, isGitInternalPath, resolveGitHubClientId, GITHUB_HOST, GitHubAuthProvider, GDRIVE_HOST, resolveGoogleClientId, resolveGoogleClientSecret, GOOGLE_NOT_CONFIGURED_MESSAGE, requireGoogleClientCredentials, pkceChallengeFromVerifier, GoogleAuthProvider, revokeGoogleCredential, publishCredentialKey, publishConnectionStatus, listPublishAccounts, connectGoogleDrive, listGitHubRepositories, listRepoBooks, listGitHubBranches, syncProject, refreshRemoteCopies, isValidRepositoryName, setUpOnlineBackup, sanitizeCloneFolderName, cloneRepository, isSshRemoteUrl, testRemoteAccess, knownForgeTokenUrl, connectGenericHost, parseRemoteOrigin, forgeKindForHost, diagnoseProjectRemote, REPAIR_SNAPSHOT_MESSAGE, repairOnlineBackup, scorchedEarth, listPublishProviders, publishProviderFor, resolvePublishFormat, resolvePublishRequest, runPublish, connectPublishProvider, disconnectPublishCredential, PublishSelectionsStore, readPublishSettings, setPublishProviderConfig };

package/dist/index.js

@@ -78,6 +78,7 @@ import {
   listCustomTemplates,
   listGitHubBranches,
   listGitHubRepositories,
+  listLocationVariants,
   listMarkerComponents,
   listMergedSnippets,
   listNpmVersions,
@@ -152,7 +153,7 @@ import {
   testRemoteAccess,
   updateExtensions,
   validateProjectExtensions
-} from "./index-2vd5b3vy.js";
+} from "./index-k0k4syyd.js";
 import"./index-ht1bcqdd.js";
 import {
   BUILD_DIAGNOSTIC_CODES
@@ -271,6 +272,7 @@ export {
   listNpmVersions,
   listMergedSnippets,
   listMarkerComponents,
+  listLocationVariants,
   listLocalBranches,
   listGitHubRepositories,
   listGitHubBranches,

package/dist/lib/markdown/assemble.d.ts

@@ -31,7 +31,9 @@ export type ReadText = (relPath: string) => Promise<string>;
  * returned something unusable).
  *
  * `unknown_variant` is emitted for a declared marker (container or
- * `section: true`) whose bare word is not one of its declared `variants`.
+ * `section: true`) whose bare word is not one of its declared `variants`, and
+ * for an `@page` / `@section` word that is a near-miss of a declared page /
+ * section variant (any other word there is a free name and stays silent).
  *
  * There is deliberately no `section_without_page`: a @section with no open
  * @page is valid authoring (17/17 false positives across two real books).

package/dist/lib/markdown/markers.d.ts

@@ -12,172 +12,37 @@
  *   One entry per LOADED plugin that declared a non-empty `markers` export,
  *   in plugin load order. A plugin with no `markers` export is simply
  *   omitted by the caller — this function never sees it.
- * @returns {Map<string, object>} empty when `sources` is empty.
+ * @typedef {{ class: string, owner: string, label?: string, snippet?: string }} LocationVariant
+ * @returns {Map<string, object> & { locationVariants: { page: Map<string, LocationVariant>, chapter: Map<string, LocationVariant>, section: Map<string, LocationVariant> } }}
+ *   the container markers (core's `@columns` always), plus the merged
+ *   `page`/`chapter`/`section` variants as `locationVariants.<kind>: Map<word, { class,
+ *   owner, label?, snippet? }>` (core's own page variants always).
  */
 export function buildDeclaredMarkerRegistry(sources: {
     pluginName: string;
     markers: Record<string, unknown>;
-}[]): Map<string, object>;
+}[]): Map<string, object> & {
+    locationVariants: {
+        page: Map<string, LocationVariant>;
+        chapter: Map<string, LocationVariant>;
+        section: Map<string, LocationVariant>;
+    };
+};
 export default function plugin(md: any, pluginOptions?: {}): void;
+export const MARKER_CSS: string;
 /**
- * The minimal CSS the DOM this module emits requires. Author utility
- * vocabulary lives in gutterpress-css.ts — see the ownership note above.
- *
- * The real contract (#227; a prior version of this paragraph said the
- * opposite and was stale — 2026-09-01 CSS architecture review, C4):
- * consumers inject this FIRST, wrapped in `@layer gp.marker` (assemble.ts
- * declares `@layer gp.marker, gp.vocab;` before both core blocks). Author
- * CSS — plugin CSS, every project stylesheet — stays UNLAYERED, and per
- * the CSS Cascade Layers
- * spec unlayered CSS always wins over layered CSS regardless of selector
- * specificity. That is what makes "author wins" true now, not injection
- * order. The `:where()` wrapping on the break/orphan/sizing rules below is
- * a NARROWER, still-necessary guarantee that survives the layer: it keeps
- * this block from out-specificity-ing whatever ELSE an author writes
- * (their own plain `.section { break-inside: ... }`, say) — a concern
- * `@layer` doesn't touch, since two unlayered rules still settle by
- * ordinary specificity between themselves.
- *
- * `.page`/`.spread` are given `position: relative` so they are the containing
- * block for any abspos descendant: a mispinned `bottom: 0` now fails LOCALLY
- * on its own page instead of resolving against the document canvas and
- * painting on the last page of the book.
- *
- * `min-height: var(--gp-content-h)` is the other half of that contract: a
- * page root that only shrink-wraps its text is a containing block whose
- * `bottom` edge is the end of the PROSE, so `.gp-pin .gp-bottom` (and every
- * hand-written `position: absolute; bottom: 0`) lands under the last
- * paragraph instead of at the page foot. Nothing in a continuous document
- * stretches a page root to the page area on its own, so both renderers
- * publish the page CONTENT height as `--gp-content-h` for the page context
- * the element is in
- * (the viewer on each `.gp-strip`; the compiler on `:root` plus every
- * `page:` assignment selector), and custom properties inherit, so this one
- * rule reaches a page root at any wrapper depth. Undefined var (plain
- * markdown-it use, no engine) falls back to `1px`, which the cushion below
- * takes back to zero — the rule is inert outside the pipeline, leaving the
- * page root shrink-wrapped exactly as it is today.
- *
- * It is `min-height`, not `height`: a `.page` whose content runs past one
- * sheet must still fragment normally. The whole rule is `:where()`, so an
- * author who wants any of it back sets their own value at any specificity.
- *
- * `box-sizing` and `display` are what make a page-sized min-height safe, and
- * both were found by MEASURING a real book (docs/fixtures/css-authoring-spike)
- * print one extra sheet without them:
- *
- *   - `border-box`, because a page root with padding (that fixture's cover
- *     has `padding-top: 2.5in`) would otherwise be one content box PLUS its
- *     padding tall, which is one sheet plus 2.5in — the overflow lands on a
- *     spurious blank sheet.
- *   - `flow-root`, because a child margin collapsing THROUGH the root's edge
- *     survives the forced break and eats into the new sheet: that fixture's
- *     last page opens with an `<h2>` whose 22.4px margin-top pushed a
- *     719px-tall root down 22.4px on a 720px sheet, spilling it. A page root
- *     is a page; containing its children's margins is what a page does. The
- *     viewer already forces `flow-root` on displaced page roots for exactly
- *     this reason (`stabilizeFullHeightPageRoots`, fragment.ts) — declaring
- *     it once in core means both renderers start from the same box. Zero
- *     specificity, so an authored `display: flex`/`grid` page root still
- *     wins, which is the case that function's comment warns about.
- *
- * The `- 1px` is the fragmentation cushion, and it is load-bearing. A box
- * whose bottom edge lands EXACTLY on the fragmentainer's edge costs an empty
- * fragment: MEASURED (Chromium 148, 384x480px sheet, 24px margins, one
- * short page root) `min-height: 432px` prints 2 sheets with the second
- * blank while `431px` prints 1 — and the viewer's multicol strip does the
- * same, which is how it first showed up (an 8pp preview of a 7pp book on
- * the gp-image-positioning fixture). One px at 96dpi is 0.75pt: it moves a
- * pinned foot up by less than a point and absorbs sub-pixel rounding in the
- * published value. Do not "clean it up" — the sheet it costs is silent.
- *
- * The break/orphan rules below (`break-after` on headings, image sizing)
- * are all `:where()` so they carry zero specificity —
- * author CSS at any specificity wins outright, reusing this same
- * after-author injection point.
- *
- * There is deliberately NO `.section > :first-child { break-before: avoid }`
- * "glue". A first child's break-before propagates to its parent's start
- * edge, so it made the break BEFORE every section `avoid`: a section after
- * other content could not move whole to the next page, and Chromium split it
- * instead, ignoring its own `break-inside: avoid`. Measured with and without
- * (marker-css-section-break.test.ts): it never prevented a stranded top edge
- * or heading. Its one useful side effect, a lead-in paragraph travelling with
- * a following @section that wraps a table, is the explicit rule below.
- *
- * `vertical-align: bottom` on a lone image is a print-correctness rule, not
- * cosmetics. An `<img>` in a `<p>` is inline-level, so its line box adds
- * half-leading/descender space UNDER the image: an image sized to exactly the
- * page content box (a book capping art at `page-height - margins`, or art that
- * naturally fills the page) produces a paragraph a few px TALLER than the box
- * it was sized to fit. MEASURED (Chromium 148, field guide chapter 1, 10in
- * content box): a 956px image made a 963.59px paragraph — a 3.6px overflow
- * that pushed the enclosing named-page wrapper's bottom edge onto the NEXT
- * sheet, so Chromium named that sheet after the PREVIOUS page name and the new
- * template's running head and folio silently vanished. `vertical-align:
- * bottom` collapses the line box onto the image, keeping the image inline (so
- * `text-align: center` still centers it — `display: block` would not).
- *
- * #231 — two engine-generic print fixes adopted from a real book's own
- * engine sheet, because both are written entirely in terms of core's own
- * published contract and fix a failure every book with big art or a
- * `<figure>` hits, not a DC-brand-specific one:
- *
- *   - A bare markdown placard (`![Alt](art.jpg)`, no class) taller than the
- *     page content box is monolithic replaced content, and the fragmenter
- *     SLICES it mid-image across the page break instead of moving it whole.
- *     Capping a bare image to `--gp-content-h` (core's own published page
- *     CONTENT height for the page context it is in — see the min-height
- *     rule above) with `object-fit: contain` letterboxes it onto one page
- *     instead. Scoped to `:not([class])` so it never touches a `.gp-full`,
- *     `.gp-bleed`, or any other explicitly sized/classed image — an author
- *     who already sized their own art has already made the call this rule
- *     exists to make for the ones who haven't. `--gp-content-h` is
- *     published by BOTH renderers (the compiler on `:root` plus every
- *     `page:` assignment selector; the viewer on each `.gp-strip`), so this
- *     rule cannot itself split preview from print.
- *
- *     MEASURED on the field guide (295pp, adopted verbatim from its own
- *     native-furniture.css §9, which carried this exact rule for months):
- *     chapter-01's rabbit placard paints 717.0pt tall on the default page
- *     both before and after adoption (core's cap and the book's copy agree
- *     bit-for-bit — the book's copy is now a harmless duplicate of core's,
- *     not a competing rule). Chapter-03's full-sheet plate (an `@page` with
- *     zero margins, so the content box IS the sheet) paints 621.0 x 804.0pt
- *     inside its 621 x 810pt sheet both before and after — the OLD hand-
- *     computed version of this rule (`calc(var(--page-height) - 0.5in -
- *     0.75in - 4px)`, hard-coding the DEFAULT page's margins) over-capped
- *     this named page's art to 553.5 x 717.0pt, a 1.3in band of bare wall
- *     along its foot; reading the cap off `--gp-content-h` instead fixed
- *     that BEFORE core ever adopted the rule, so adoption itself changes
- *     nothing further. Total page count unchanged at 295pp — no
- *     shrink-to-fit side effect from moving the rule into core.
- *
- *   - `figure { break-inside: avoid }` keeps in-flow art (anything an
- *     author or a plugin wraps in a real `<figure>`) from being sliced
- *     across a page break the same way a bare placard would be — the
- *     `:where(p > img:only-child, figure > img)` sizing rule above already
- *     assumes the figure survives as one piece; without this it did not.
- *
- * Design-for-deletion note (CLAUDE.md): neither rule is a Chromium-gap shim
- * with a removal trigger — both are permanent, standards-verbatim defaults
- * in the same category as the min-height/box-sizing/vertical-align rules
- * above (real print-fragmentation behavior, not a spec feature Chrome has
- * yet to ship). They stay `:where()` so an author's own sizing or
- * break-inside rule, at ANY specificity, still wins outright.
- *
- * The companion "spanner + unbreakable box" glue pattern (`column-span: all`
- * followed by a `break-inside: avoid` box) was measured for this same adoption pass and DELIBERATELY NOT
- * adopted: a `:where()`-zero-specificity override can never win against
- * whatever real-specificity rule gave the box its `break-inside: avoid` in
- * the first place (a synthetic 2-column fixture with the candidate
- * `:where(.gp-columns-all) + :where(*) { break-inside: auto }` produced
- * BYTE-IDENTICAL output to the same fixture without it, across every
- * geometry swept), and the field guide's own native-furniture.css §13 shows
- * a context-blind version of the same idea is actively wrong for at least
- * one real, shipped case (a short, non-fragmenting instance that needed its
- * `avoid` restored after a general fragmenting-context rule took it away).
- * Core ships no spanner class: a spanning heading is the end of one @columns run and the start of the next.
- *
+ * Merge every loaded plugin's `markers` export into ONE flat, resolved
+ * registry — `Map<name, ResolvedDecl>` — validating collisions at LOAD TIME
+ * (#240 / P2): a declared name that shadows a core reserved name, or that
+ * two different plugins both declare, throws immediately, naming both
+ * sides, instead of the pre-#240 silent-skip footgun (core claims its
+ * `@`-names during block parsing, before any plugin runs, so a colliding
+ * plugin marker used to never run and never warn — see the header comment
+ * on `KNOWN_KINDS`).
  */
-export const MARKER_CSS: "\n/* The UA default of 8px body margin is a screen affordance with no meaning\n   in paged media, and engines disagree about it: a polyfill that treats the\n   page div as the page box drops it, native print keeps it. Left in place it\n   insets EVERY page's content by 8px per side, and -- measured, 300dpi,\n   6x4in sheet -- it is what stops a full-width block from reaching the\n   paper: it lands at 0.080..5.917in of a 6in sheet instead of\n   0.000..6.000in, because width:100% resolves against the BODY content box,\n   not the page's. Zeroing it here (first in the cascade) makes the two\n   agree. Authors who want a body margin still just declare one. */\nbody { margin: 0; }\n\n.gp-page-break { break-before: page; }\n.page { break-before: page; }\n.spread { break-before: page; }\n:where(.page, .spread) { position: relative; display: flow-root; box-sizing: border-box; min-height: calc(var(--gp-content-h, 1px) - 1px); }\n.gp-column-break { break-after: column; height: 0; font-size: 0; line-height: 0; visibility: hidden; }\n\n:where(h1,h2,h3,h4,h5,h6) { break-after: avoid; }\n/* A lead-in paragraph (\"**ROLL A DIE!**\" above a roll table, \"You will need:\"\n   above a list) stays with the table or list it introduces, the way a heading\n   stays with what follows it -- otherwise the label can end a column or page\n   with its table starting on the next (#370). Standard break-after; the\n   :has() selector is Chromium's own. :where() keeps specificity at zero so an\n   author rule such as p { break-after: auto } wins. Deliberately table/ul/ol only,\n   also when a @section wraps it (the second rule): the lead-in then keeps with\n   the section that opens with the table or list. */\n:where(p):has(+ :where(table, ul, ol)) { break-after: avoid; }\n:where(p):has(+ :where(.section) > :where(table, ul, ol):first-child) { break-after: avoid; }\n:where(img, svg, video) { max-width: 100%; }\n:where(p > img:only-child, figure > img) { width: fit-content; max-width: 100%; height: auto; vertical-align: bottom; }\n:where(p) > :where(img:not([class])) { max-height: calc(var(--gp-content-h) - 4px); object-fit: contain; }\n:where(figure) { break-inside: avoid; }\n\n";
+export type LocationVariant = {
+    class: string;
+    owner: string;
+    label?: string;
+    snippet?: string;
+};

package/dist/lib/markdown/renderer.d.ts

@@ -241,7 +241,16 @@ export type GutterpressComponentProblem = string | {
 };
 /** `validate`'s return value: nothing, one message, or a list of problems. */
 export type GutterpressComponentProblems = GutterpressComponentProblem[] | string | void | null | undefined;
-/** A plugin's full declared marker table — see {@link GutterpressMarkerDeclaration}. */
+/**
+ * A plugin's full declared marker table — see {@link GutterpressMarkerDeclaration}.
+ *
+ * The reserved kinds `page`, `chapter` and `section` may also appear, in a
+ * variants-only form: `{ variants: { 'chapter-start': 'dc-page-chapter-start' },
+ * label?, snippet? }`. `@page chapter-start` then adds that class to the
+ * `.page` (likewise `@chapter`, `@section`), so book CSS styles by location:
+ * `.page.dc-page-chapter-start .section { … }`. Any other key on those names
+ * is a load error.
+ */
 export type GutterpressMarkerTable = Record<string, GutterpressMarkerDeclaration>;
 /**
  * Full shape a plugin module may export. Only `default` is required.

package/dist/lib/snippets.d.ts

@@ -93,8 +93,31 @@ export interface MarkerComponent {
     /** The winning example snippet's body (book, then extension, then core). */
     snippet?: string;
 }
+/**
+ * One `page` / `chapter` / `section` variant the book can use (`@page blank`,
+ * `@section card`): the bare word, the class it adds, and who declares it.
+ * Core's own (`blank`, `full-bleed`) have `source: { kind: "core" }`. `label`
+ * and `snippet` are the declaring plugin's group values for that kind, passed
+ * through as declared (`snippet` is a path relative to the extension, unread).
+ * Data only — what the renderer does with a variant is `markers.js`'s.
+ */
+export interface LocationVariant {
+    kind: "page" | "chapter" | "section";
+    /** The word after the marker: `@page <word>`. */
+    word: string;
+    /** The class it adds to the emitted element. */
+    class: string;
+    source: Extract<SnippetSource, {
+        kind: "extension" | "core";
+    }>;
+    label?: string;
+    snippet?: string;
+}
 /** Every snippet the project can insert, from every level — see {@link collectLibrary}. */
 export declare function listMergedSnippets(projectDir: string): Promise<SnippetEntry[]>;
 /** Every component the project's enabled extensions declare, each with its
  *  winning example snippet (book > extension > core) — see {@link collectLibrary}. */
 export declare function listMarkerComponents(projectDir: string): Promise<MarkerComponent[]>;
+/** Every `page` / `chapter` / `section` variant the project can use — core's
+ *  own plus each enabled extension's — see {@link LocationVariant}. */
+export declare function listLocationVariants(projectDir: string): Promise<LocationVariant[]>;

package/dist/{new-8xwac8nd.js → new-mvtamd8q.js}

@@ -7,15 +7,15 @@ import {
   TARGET_IDS,
   scaffoldExtension,
   scaffoldProject
-} from "./cli-an3pxzzk.js";
+} from "./cli-v3xmpvs8.js";
 import {
   resolveGhostscript
-} from "./cli-0wtnw98y.js";
+} from "./cli-vsgj1n9s.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-jjbeqx94.js";
+} from "./cli-2yvrfr58.js";
 import"./cli-ht1bcqdd.js";
 import"./cli-ycbg7mxk.js";
 import {

package/dist/{preflight-62c2r37w.js → preflight-et7fnz7v.js}

@@ -2,15 +2,15 @@ import {
   executeValidation,
   publishTargetFor,
   reportMissingTools
-} from "./cli-an3pxzzk.js";
+} from "./cli-v3xmpvs8.js";
 import {
   log
-} from "./cli-0wtnw98y.js";
+} from "./cli-vsgj1n9s.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-jjbeqx94.js";
+} from "./cli-2yvrfr58.js";
 import"./cli-ht1bcqdd.js";
 import"./cli-ycbg7mxk.js";
 import {

package/dist/{preview-qdby30fx.js → preview-xzvwzsyz.js}

@@ -7,10 +7,10 @@ import {
   runBuild,
   splitOutPath,
   startPreviewServer
-} from "./cli-an3pxzzk.js";
+} from "./cli-v3xmpvs8.js";
 import {
   log
-} from "./cli-0wtnw98y.js";
+} from "./cli-vsgj1n9s.js";
 import {
   UsageError,
   parseFormat,
@@ -18,7 +18,7 @@ import {
   rejectExtraPositionals,
   rejectUnknownFlags,
   resolvePort
-} from "./cli-jjbeqx94.js";
+} from "./cli-2yvrfr58.js";
 import"./cli-ht1bcqdd.js";
 import"./cli-ycbg7mxk.js";
 import {