gutterpress 0.10.6 → 0.10.7-beta.1

package/dist/{index-eyzv51dw.js → index-a0xpm188.js}

@@ -4,7 +4,7 @@ import {
   launchChromium,
   marginBoxAlign,
   marginBoxRectPt
-} from "./index-k5hcp8wj.js";
+} from "./index-837htyjy.js";
 
 // src/engine/compiler/build.ts
 import { readFile } from "node:fs/promises";

package/dist/index.js

@@ -39,6 +39,7 @@ import {
   connectPublishProvider,
   defaultConfigDir,
   deleteSnippet,
+  detectLegacyForkedTheme,
   diagnoseProjectRemote,
   disconnectPublishCredential,
   escapeYamlScalar,
@@ -124,15 +125,15 @@ import {
   syncProject,
   testRemoteAccess,
   validateProjectPlugins
-} from "./index-1rcfsx67.js";
+} from "./index-9zf8mtk7.js";
 import {
   BUILD_DIAGNOSTIC_CODES
-} from "./index-eyzv51dw.js";
+} from "./index-a0xpm188.js";
 import {
   BuildError,
   DEFAULT_PRINT_OPTS,
   readyProbeExpr
-} from "./index-k5hcp8wj.js";
+} from "./index-837htyjy.js";
 import {
   AUTO_SNAPSHOT_MESSAGE,
   HISTORY_PAGE_LIMIT,
@@ -245,6 +246,7 @@ export {
   disconnectPublishCredential,
   diagnoseProjectRemote,
   detectProjectSource,
+  detectLegacyForkedTheme,
   deleteSnippet,
   defaultConfigDir,
   connectPublishProvider,

package/dist/lib/cli-args.d.ts

@@ -50,3 +50,12 @@ export declare function parsePdfxFlavor(raw: unknown, format: BuildFormat): Pdfx
 export declare function parseEngine(raw: unknown): "paged" | "native" | undefined;
 /** Parse `--port`, defaulting to {@link NETWORK.DEFAULT_PORT} (0 = OS-assigned). */
 export declare function resolvePort(raw: unknown): number;
+/**
+ * THE command-boundary handler for a {@link UsageError}: print the message and
+ * exit with the error's own code. Every subcommand-dispatching command
+ * (`plugin`, `theme`) catches its parse errors here, so the usage-error→exit
+ * mapping has one definition rather than one per command.
+ */
+export declare function exitForUsage(error: unknown): never;
+/** Resolve a `--dir` argument to an absolute path, defaulting to the cwd. */
+export declare function resolveProjectDir(dir: unknown): string;

package/dist/lib/manifest-doc.d.ts

@@ -9,8 +9,14 @@ export declare function loadManifestDoc(projectDir: string): Promise<{
 }>;
 /** Atomically write the doc back, creating the project dir if needed. */
 export declare function writeManifestDoc(file: string, doc: Document.Parsed): Promise<void>;
-/** The named sequence node, creating (and attaching) an empty one if missing. */
-export declare function ensureSeq(doc: Document.Parsed, key: string): YAMLSeq;
+/**
+ * The named sequence node, creating (and attaching) an empty one if missing.
+ * `key` is a single top-level key (the original, still-exact behavior) OR a
+ * path for a nested key (e.g. `["engineStyles", "native"]`, #239) — the
+ * `getIn`/`setIn` branch auto-vivifies any missing intermediate map, exactly
+ * like a hand-written `engineStyles: { native: [...] }` would parse.
+ */
+export declare function ensureSeq(doc: Document.Parsed, key: string | readonly string[]): YAMLSeq;
 /**
  * Unwrap a yaml seq item (or `getIn`-style Pair) to its string value: `null`
  * when the item isn't a string. Handles both a bare Scalar/Pair-shaped node

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

@@ -23,6 +23,16 @@ export interface LayoutWarning {
     message: string;
     marker?: unknown;
 }
+/**
+ * The Chromium milestone that paints a `@page { background: url() }` image
+ * with no other reference to it (spec gap #152). Measured 2026-09-03: Chrome
+ * for Testing 152.0.7977.54 and the CI runner's Chrome stable both paint it;
+ * Chrome 151.0.7922.75 dropped it (docs/known-limitations.md §3). The
+ * `preloadImages` shim below expires when the engine's floor
+ * (`REQUIRED_MILESTONE`, engine/shared/cdp.ts) reaches this — the canary in
+ * engine/compiler/page-background-chromium-bug.canary.test.ts enforces that.
+ */
+export declare const PAGE_BACKGROUND_FIXED_MILESTONE = 152;
 export interface AssembleBookHtmlOptions {
     /** Ordered list of project-root-relative `.md` files to concatenate. */
     files: string[];
@@ -42,9 +52,10 @@ export interface AssembleBookHtmlOptions {
      */
     projectCss?: string;
     /**
-     * SHIM — spec gap #152. Output-relative hrefs of the images the project's
-     * stylesheets staged (`inlineStyles`'s copy plan, verbatim), each emitted as
-     * one `<link rel="preload" as="image">`.
+     * SHIM — spec gap #152, fixed upstream in Chromium
+     * {@link PAGE_BACKGROUND_FIXED_MILESTONE}. Output-relative hrefs of the
+     * images the project's stylesheets staged (`inlineStyles`'s copy plan,
+     * verbatim), each emitted as one `<link rel="preload" as="image">`.
      *
      * Chromium reaches an `@page`-only `url()` lazily, during the print, and the
      * print path CDP drives never waits for a pending resource — so the sheet
@@ -64,10 +75,16 @@ export interface AssembleBookHtmlOptions {
      * either document order) — which is why `asset-inline.ts` content-addresses
      * every CSS image so no element can name one.
      *
-     * WHAT PROVES IT IS STILL NEEDED: the expiry canary,
-     * `engine/compiler/page-background-chromium-bug.canary.test.ts`. The day it
-     * goes red, Chromium has fixed the bug — delete this option, the `.map()`
-     * that feeds it in `markdown/index.ts`, and the canary.
+     * WHEN IT GOES: Chromium fixed the bug in milestone
+     * {@link PAGE_BACKGROUND_FIXED_MILESTONE} (measured 2026-09-03: Chrome 152
+     * paints the sole-referenced image, 151 dropped it). The preload changes
+     * nothing on a fixed Chromium, and it still protects every Chromium the
+     * engine accepts below that (`REQUIRED_MILESTONE` in `engine/shared/cdp.ts`,
+     * 148 — what Electron 42 ships), so it stays until the floor reaches the
+     * fix. The expiry canary,
+     * `engine/compiler/page-background-chromium-bug.canary.test.ts`, goes red
+     * the day the floor is raised that far — delete this option, the `.map()`
+     * that feeds it in `markdown/index.ts`, the constant, and the canary.
      *
      * The copy plan is the source, NOT a scan of the assembled CSS: `pluginCss`
      * never passes through `inlineStyles`, so a `url()` inside it is never

package/dist/lib/markdown/gfm-alerts.d.ts

@@ -0,0 +1,7 @@
+import type MarkdownIt from "markdown-it";
+/**
+ * The plugin export — a plain `(md) => void` markdown-it plugin (CLAUDE.md
+ * §5), registered by name from `BUILTIN_OPTIONAL_PLUGINS` when a project
+ * lists `gutterpress-gfm-alerts` in its manifest.
+ */
+export default function gfmAlerts(md: MarkdownIt): void;

package/dist/lib/markdown/gutterpress-css.d.ts

@@ -136,7 +136,7 @@
  * carrying gp-left could start shifting; that is standards-tracking per
  * CLAUDE.md ("Chrome wins once it ships"), not a bug in the author's book.
  */
-export declare const GUTTERPRESS_CSS = "\n/* gp-* author image/block vocabulary. One vocabulary, gp-* only \u2014 the\n   pre-vocabulary utility names (.center/.float-left/.float-right/\n   .full-width/.full-bleed) were REMOVED when gp-* shipped; books rename\n   the classes in their markdown (see the migration note). Source ORDER is\n   the contract \u2014 see the doctrine comment above. */\n\n/* flow positions */\n.gp-left {\n  float: left;\n  margin: 0 var(--gp-gap, 1em) var(--gp-gap, 1em) 0;\n  max-width: 50%;\n}\n.gp-right {\n  float: right;\n  margin: 0 0 var(--gp-gap, 1em) var(--gp-gap, 1em);\n  max-width: 50%;\n}\n.gp-center {\n  display: block;\n  float: none;\n  margin-left: auto;\n  margin-right: auto;\n  max-width: 100%;\n}\n.gp-full {\n  display: block;\n  float: none;\n  width: 100%;\n  max-width: 100%;\n}\n@page gp-full-bleed { margin-left: 0; margin-right: 0; }\n.gp-bleed {\n  display: block;\n  float: none;\n  break-before: page;\n  page: gp-full-bleed;\n  max-width: none;\n  width: 100%;\n  margin-left: 0;\n  margin-right: 0;\n}\n\n/* sizes \u2014 AFTER the flow positions so max-width:100% lifts the floats' 50%\n   cap at equal specificity */\n.gp-small { width: 25%; max-width: 100%; }\n.gp-medium { width: 50%; max-width: 100%; }\n.gp-large { width: 75%; max-width: 100%; }\n\n/* float clearance presets \u2014 consumed by var(--gp-gap) in the float rules\n   above and by .gp-shape's shape-margin below; --gp-gap itself is\n   author-settable CSS */\n.gp-tight { --gp-gap: 0.5em; }\n.gp-loose { --gp-gap: 2em; }\n\n/* column runs \u2014 plain CSS Multi-column, exposed as author vocabulary so\n   \"put this in two columns\" does not require borrowing a styled container\n   from the book's own component layer. That borrowing is what this exists\n   to prevent: a book whose theme paints .section chrome by default gives\n   every author who opens a section just to start a column run a panel they\n   did not ask for, and the book then needs a reset rule to take it back.\n   With a neutral primitive the author opts into columns and nothing else.\n\n   Permanent vocabulary, not a shim: Chromium implements multicol natively\n   and these rules are the standard properties verbatim, so there is no\n   spec gap here to remove later. Deliberately minimal \u2014 column-fill is\n   NOT set, because the correct value depends on whether the run fragments\n   across pages (auto packs each page's columns; the CSS initial balance is\n   right for a run that fits on one page) and only the author knows which.\n   --gp-column-gap is author-settable. */\n.gp-columns-2 { columns: 2; column-gap: var(--gp-column-gap, 1.5em); }\n.gp-columns-3 { columns: 3; column-gap: var(--gp-column-gap, 1.5em); }\n\n/* the per-shape decisions the paragraph above deliberately leaves to the\n   author, named instead of left as raw CSS every book was reinventing\n   (2026-09-01 CSS architecture review, findings C1/C7 \u2014 CLAUDE.md \u00A70:\n   \"behavior broadly useful to non-technical authors belongs in core\").\n   Permanent vocabulary, standard properties verbatim \u2014 same rationale as\n   the column/grid runs above. One name each, no aliases:\n     .gp-columns-all       column-span: all      a heading or block that\n                                                  spans every column in the\n                                                  run it sits inside.\n     .gp-columns-flow      column-fill: auto     a run that FRAGMENTS across\n                                                  pages \u2014 every page's\n                                                  columns fill instead of\n                                                  only the last one\n                                                  balancing (the dead-column\n                                                  collapse the build's\n                                                  engine.multicol.dead-column\n                                                  warning names this fix\n                                                  for).\n     .gp-columns-balanced  column-fill: balance  a run that fits on ONE\n                                                  page (the CSS initial\n                                                  value \u2014 ragged columns\n                                                  would be wrong here). */\n.gp-columns-all { column-span: all; }\n.gp-columns-flow { column-fill: auto; }\n.gp-columns-balanced { column-fill: balance; }\n\n/* grid runs \u2014 the SLOTTED counterpart to the column runs above. Grid places\n   each child into the next cell, across then down (deterministic slots: card\n   layouts, stat blocks, image-plus-caption pairs); columns FLOW one text run\n   down then across. Same neutral-primitive rationale as .gp-columns-*, and\n   permanent vocabulary for the same reason: standard CSS Grid verbatim, no\n   spec gap to remove later. MEASURED (Chromium 151, gp-grid evidence pack):\n   grid rows fragment across sheets with EXACT print/viewer parity \u2014 2- and\n   3-col, unequal item heights, mid-row cuts, multi-sheet overflow,\n   break-inside:avoid, gap geometry \u2014 so a grid taller than the page is safe,\n   no fit-one-page constraint. Two things to know, not fix:\n     - on a min-height page root (MARKER_CSS), default align-content\n       stretches rows apart to fill the page \u2014 identically in both engines.\n       Authors wanting packed rows set align-content: start.\n     - a @page-break / @column-break marker DIRECTLY inside a grid container\n       becomes a grid item and corrupts placement (the one measured parity\n       break); markers.js diagnoses it (break_inside_grid).\n   --gp-grid-gap is author-settable. */\n.gp-grid-2 { display: grid; grid-template-columns: repeat(2, 1fr); gap: var(--gp-grid-gap, 1.5em); }\n.gp-grid-3 { display: grid; grid-template-columns: repeat(3, 1fr); gap: var(--gp-grid-gap, 1.5em); }\n\n/* fragmentation controls \u2014 generic pagination utilities for any element,\n   independent of the column/grid vocabulary above (a book reached for\n   these just as often outside a multicol run: keeping a card whole,\n   forcing a section to start a fresh page). Standard properties only \u2014\n   this project is Chromium-only (CLAUDE.md), so there are no legacy\n   page-break-* twins to also emit. One name each. */\n.gp-no-break { break-inside: avoid; }\n.gp-break-before { break-before: page; }\n\n/* shape wrap \u2014 text follows the image's alpha silhouette instead of its\n   rectangular box. shape-outside only applies to floats, so this is inert\n   without .gp-left/.gp-right (and under .gp-pin, which un-floats). The\n   shape URL cannot be written in CSS (url() contexts can't read attr()),\n   so the image renderer rule (images.ts) mirrors the src into an inline\n   --gp-shape:url(...) custom property whenever it sees this class --\n   authors only ever type the class. threshold 0.2 ignores near-transparent\n   anti-aliasing halos; shape-margin shares the float-gap vocabulary. */\nimg.gp-shape {\n  shape-outside: var(--gp-shape);\n  shape-image-threshold: 0.2;\n  shape-margin: var(--gp-gap, 1em);\n}\n\n/* pin \u2014 within the nearest positioned ancestor (.page/.spread, rule above).\n   inset:0 and the explicit centers are load-bearing; see doctrine comment. */\n.gp-pin {\n  position: absolute;\n  inset: 0;\n  align-self: center;\n  justify-self: center;\n  margin: 0;\n  max-width: 100%;\n}\n\n/* pin edge modifiers \u2014 AFTER .gp-pin to beat its center defaults;\n   justify-self is inert on in-flow floats, so gp-left/gp-right safely do\n   double duty as flow float + pin edge */\n.gp-top { align-self: start; }\n.gp-bottom { align-self: end; }\n.gp-left { justify-self: start; }\n.gp-right { justify-self: end; }\n\n/* wrapper-margin neutralization (same pattern and rationale as the\n   .gp-bleed paragraph-margin note in the doctrine comment; for pin, the\n   emptied paragraph would otherwise leave a phantom margin gap in flow) */\n:where(p:has(> img.gp-bleed:only-child)) { margin: 0; }\n:where(p:has(> img.gp-pin:only-child)) { margin: 0; }\n\n/* depth \u2014 a named ladder for z-index, so books stop hand-tuning bare\n   integers. A real book measured 21 z-index declarations using only four\n   distinct values (-1, 0, 1, 2), each written literally at its use site.\n   The custom properties are the author-settable surface (a book needing a\n   deeper stack raises them once); the classes are the shorthand.\n\n   NOT named \"layer\": CSS Paged Media 3 \u00A73.1 already defines \"page layers\"\n   (page background, canvas, borders, contents, margin boxes) and those are\n   parts of the PAGE BOX, not a z-ladder for content. Reusing the word for a\n   different concept would collide with the spec vocabulary this project\n   tracks. The pin EDGE modifiers already own .gp-top/.gp-bottom, so the\n   ladder avoids those words too.\n\n   .gp-behind is the one that earns its place: it puts a pinned image UNDER\n   the page's text, which is otherwise impossible to express without a bare\n   negative z-index. \"Above\" needs no class \u2014 an out-of-flow pin already\n   paints above in-flow content.\n\n   Two things silently defeat .gp-behind, neither visible at the use site:\n     - a stacking context on the .page/.spread ancestor (z-index, isolation,\n       opacity, filter, transform on it traps the negative layer inside).\n       Core keeps .page/.spread at 'position: relative; z-index: auto'\n       precisely so they are not stacking contexts.\n     - a clipping ancestor (overflow other than visible) \u2014 but only where\n       the art actually overhangs that ancestor's clip box on a clipped\n       axis: the overhang is cut off, the same mechanism that clips a\n       .gp-bleed plate back to the wrapper's width. Clipping never reorders\n       layers \u2014 within-bounds art under a clipping .page prints whole and\n       still behind (measured; see the build audit's comment in\n       engine/compiler/build.ts), and a static wrapper's overflow never\n       binds an abspos .gp-pin at all.\n   The build-time engine.layer.trapped audit reports both against the live\n   ancestor chain. printsafe/page-containment is only an early source hint for\n   declarations written directly on .page/.spread. */\n:root {\n  --gp-z-behind: -1;\n  --gp-z-base: 0;\n  --gp-z-raised: 1;\n  --gp-z-front: 2;\n}\n.gp-behind { z-index: var(--gp-z-behind); }\n.gp-base   { z-index: var(--gp-z-base); }\n.gp-raised { z-index: var(--gp-z-raised); }\n.gp-front  { z-index: var(--gp-z-front); }\n";
+export declare const GUTTERPRESS_CSS = "\n/* gp-* author image/block vocabulary. One vocabulary, gp-* only \u2014 the\n   pre-vocabulary utility names (.center/.float-left/.float-right/\n   .full-width/.full-bleed) were REMOVED when gp-* shipped; books rename\n   the classes in their markdown (see the migration note). Source ORDER is\n   the contract \u2014 see the doctrine comment above. */\n\n/* flow positions */\n.gp-left {\n  float: left;\n  margin: 0 var(--gp-gap, 1em) var(--gp-gap, 1em) 0;\n  max-width: 50%;\n}\n.gp-right {\n  float: right;\n  margin: 0 0 var(--gp-gap, 1em) var(--gp-gap, 1em);\n  max-width: 50%;\n}\n.gp-center {\n  display: block;\n  float: none;\n  margin-left: auto;\n  margin-right: auto;\n  max-width: 100%;\n}\n.gp-full {\n  display: block;\n  float: none;\n  width: 100%;\n  max-width: 100%;\n}\n@page gp-full-bleed { margin-left: 0; margin-right: 0; }\n.gp-bleed {\n  display: block;\n  float: none;\n  break-before: page;\n  page: gp-full-bleed;\n  max-width: none;\n  width: 100%;\n  margin-left: 0;\n  margin-right: 0;\n}\n\n/* sizes \u2014 AFTER the flow positions so max-width:100% lifts the floats' 50%\n   cap at equal specificity */\n.gp-small { width: 25%; max-width: 100%; }\n.gp-medium { width: 50%; max-width: 100%; }\n.gp-large { width: 75%; max-width: 100%; }\n\n/* float clearance presets \u2014 consumed by var(--gp-gap) in the float rules\n   above and by .gp-shape's shape-margin below; --gp-gap itself is\n   author-settable CSS */\n.gp-tight { --gp-gap: 0.5em; }\n.gp-loose { --gp-gap: 2em; }\n\n/* column runs \u2014 plain CSS Multi-column, exposed as author vocabulary so\n   \"put this in two columns\" does not require borrowing a styled container\n   from the book's own component layer. That borrowing is what this exists\n   to prevent: a book whose theme paints .section chrome by default gives\n   every author who opens a section just to start a column run a panel they\n   did not ask for, and the book then needs a reset rule to take it back.\n   With a neutral primitive the author opts into columns and nothing else.\n\n   Permanent vocabulary, not a shim: Chromium implements multicol natively\n   and these rules are the standard properties verbatim, so there is no\n   spec gap here to remove later. Deliberately minimal \u2014 column-fill is\n   NOT set, because the correct value depends on whether the run fragments\n   across pages (auto packs each page's columns; the CSS initial balance is\n   right for a run that fits on one page) and only the author knows which.\n   --gp-column-gap is author-settable. */\n.gp-columns-2 { columns: 2; column-gap: var(--gp-column-gap, 1.5em); }\n.gp-columns-3 { columns: 3; column-gap: var(--gp-column-gap, 1.5em); }\n\n/* the per-shape decisions the paragraph above deliberately leaves to the\n   author, named instead of left as raw CSS every book was reinventing\n   (2026-09-01 CSS architecture review, findings C1/C7 \u2014 CLAUDE.md \u00A70:\n   \"behavior broadly useful to non-technical authors belongs in core\").\n   Permanent vocabulary, standard properties verbatim \u2014 same rationale as\n   the column/grid runs above. One name each, no aliases:\n     .gp-columns-all       column-span: all      a heading or block that\n                                                  spans every column in the\n                                                  run it sits inside.\n     .gp-columns-flow      column-fill: auto     a run that FRAGMENTS across\n                                                  pages \u2014 every page's\n                                                  columns fill instead of\n                                                  only the last one\n                                                  balancing (the dead-column\n                                                  collapse the build's\n                                                  engine.multicol.dead-column\n                                                  warning names this fix\n                                                  for).\n     .gp-columns-balanced  column-fill: balance  a run that fits on ONE\n                                                  page (the CSS initial\n                                                  value \u2014 ragged columns\n                                                  would be wrong here). */\n.gp-columns-all { column-span: all; }\n.gp-columns-flow { column-fill: auto; }\n.gp-columns-balanced { column-fill: balance; }\n\n/* grid runs \u2014 the SLOTTED counterpart to the column runs above. Grid places\n   each child into the next cell, across then down (deterministic slots: card\n   layouts, stat blocks, image-plus-caption pairs); columns FLOW one text run\n   down then across. Same neutral-primitive rationale as .gp-columns-*, and\n   permanent vocabulary for the same reason: standard CSS Grid verbatim, no\n   spec gap to remove later. MEASURED (Chromium 151, gp-grid evidence pack):\n   grid rows fragment across sheets with EXACT print/viewer parity \u2014 2- and\n   3-col, unequal item heights, mid-row cuts, multi-sheet overflow,\n   break-inside:avoid, gap geometry \u2014 so a grid taller than the page is safe,\n   no fit-one-page constraint. Two things to know, not fix:\n     - on a min-height page root (MARKER_CSS), default align-content\n       stretches rows apart to fill the page \u2014 identically in both engines.\n       Authors wanting packed rows set align-content: start.\n     - a @page-break / @column-break marker DIRECTLY inside a grid container\n       becomes a grid item and corrupts placement (the one measured parity\n       break); markers.js diagnoses it (break_inside_grid).\n   --gp-grid-gap is author-settable. */\n.gp-grid-2 { display: grid; grid-template-columns: repeat(2, 1fr); gap: var(--gp-grid-gap, 1.5em); }\n.gp-grid-3 { display: grid; grid-template-columns: repeat(3, 1fr); gap: var(--gp-grid-gap, 1.5em); }\n\n/* fragmentation controls \u2014 generic pagination utilities for any element,\n   independent of the column/grid vocabulary above (a book reached for\n   these just as often outside a multicol run: keeping a card whole,\n   forcing a section to start a fresh page). Standard properties only \u2014\n   this project is Chromium-only (CLAUDE.md), so there are no legacy\n   page-break-* twins to also emit. One name each. */\n.gp-no-break { break-inside: avoid; }\n.gp-break-before { break-before: page; }\n\n/* shape wrap \u2014 text follows the image's alpha silhouette instead of its\n   rectangular box. shape-outside only applies to floats, so this is inert\n   without .gp-left/.gp-right (and under .gp-pin, which un-floats). The\n   shape URL cannot be written in CSS (url() contexts can't read attr()),\n   so the image renderer rule (images.ts) mirrors the src into an inline\n   --gp-shape:url(...) custom property whenever it sees this class --\n   authors only ever type the class. threshold 0.2 ignores near-transparent\n   anti-aliasing halos; shape-margin shares the float-gap vocabulary. */\nimg.gp-shape {\n  shape-outside: var(--gp-shape);\n  shape-image-threshold: 0.2;\n  shape-margin: var(--gp-gap, 1em);\n}\n\n/* pin \u2014 within the nearest positioned ancestor (.page/.spread, rule above).\n   inset:0 and the explicit centers are load-bearing; see doctrine comment. */\n.gp-pin {\n  position: absolute;\n  inset: 0;\n  align-self: center;\n  justify-self: center;\n  margin: 0;\n  max-width: 100%;\n}\n\n/* pin edge modifiers \u2014 AFTER .gp-pin to beat its center defaults;\n   justify-self is inert on in-flow floats, so gp-left/gp-right safely do\n   double duty as flow float + pin edge */\n.gp-top { align-self: start; }\n.gp-bottom { align-self: end; }\n.gp-left { justify-self: start; }\n.gp-right { justify-self: end; }\n\n/* wrapper-margin neutralization (same pattern and rationale as the\n   .gp-bleed paragraph-margin note in the doctrine comment; for pin, the\n   emptied paragraph would otherwise leave a phantom margin gap in flow) */\n:where(p:has(> img.gp-bleed:only-child)) { margin: 0; }\n:where(p:has(> img.gp-pin:only-child)) { margin: 0; }\n\n/* depth \u2014 a named ladder for z-index, so books stop hand-tuning bare\n   integers. A real book measured 21 z-index declarations using only four\n   distinct values (-1, 0, 1, 2), each written literally at its use site.\n   The custom properties are the author-settable surface (a book needing a\n   deeper stack raises them once); the classes are the shorthand.\n\n   NOT named \"layer\": CSS Paged Media 3 \u00A73.1 already defines \"page layers\"\n   (page background, canvas, borders, contents, margin boxes) and those are\n   parts of the PAGE BOX, not a z-ladder for content. Reusing the word for a\n   different concept would collide with the spec vocabulary this project\n   tracks. The pin EDGE modifiers already own .gp-top/.gp-bottom, so the\n   ladder avoids those words too.\n\n   .gp-behind is the one that earns its place: it puts a pinned image UNDER\n   the page's text, which is otherwise impossible to express without a bare\n   negative z-index. \"Above\" needs no class \u2014 an out-of-flow pin already\n   paints above in-flow content.\n\n   Two things silently defeat .gp-behind, neither visible at the use site:\n     - a stacking context on the .page/.spread ancestor (z-index, isolation,\n       opacity, filter, transform on it traps the negative layer inside).\n       Core keeps .page/.spread at 'position: relative; z-index: auto'\n       precisely so they are not stacking contexts.\n     - a clipping ancestor (overflow other than visible) \u2014 but only where\n       the art actually overhangs that ancestor's clip box on a clipped\n       axis: the overhang is cut off, the same mechanism that clips a\n       .gp-bleed plate back to the wrapper's width. Clipping never reorders\n       layers \u2014 within-bounds art under a clipping .page prints whole and\n       still behind (measured; see the build audit's comment in\n       engine/compiler/build.ts), and a static wrapper's overflow never\n       binds an abspos .gp-pin at all.\n   The build-time engine.layer.trapped audit reports both against the live\n   ancestor chain. printsafe/page-containment is only an early source hint for\n   declarations written directly on .page/.spread. */\n:root {\n  --gp-z-behind: -1;\n  --gp-z-base: 0;\n  --gp-z-raised: 1;\n  --gp-z-front: 2;\n}\n.gp-behind { z-index: var(--gp-z-behind); }\n.gp-base   { z-index: var(--gp-z-base); }\n.gp-raised { z-index: var(--gp-z-raised); }\n.gp-front  { z-index: var(--gp-z-front); }\n\n/* GFM-style alert/callout boxes (#237) \u2014 the DOM gfm-alerts.ts emits from\n   \"> [!TYPE]\" blockquote syntax when a project opts into the bundled\n   gutterpress-gfm-alerts feature (BUILTIN_OPTIONAL_PLUGINS, renderer.ts).\n   The plugin is optional and inert by default; these rules are equally\n   inert wherever the classes never appear, exactly like every other\n   utility above, so shipping them costs nothing to a book that has not\n   turned the feature on.\n\n   This is authored-COMPONENT vocabulary, not the @marker structural family\n   (markers.js/MARKER_CSS) \u2014 CLAUDE.md \u00A76 splits the two core CSS blocks by\n   ROLE, and an author-facing box an author invokes via inline syntax is the\n   same role as every other gp-* utility here, not page/chapter/section DOM.\n\n   Deliberately minimal (CLAUDE.md \"thin over capable\" / the issue's own\n   \"a rule and a label\"): a left border plus a bold label, :where()'d to\n   zero specificity so a theme's own (unlayered) rule for any of these\n   classes wins outright regardless of selector weight \u2014 see the\n   cascade-layers note atop this file. Five semantic accent colors (the same\n   NOTE/TIP/IMPORTANT/WARNING/CAUTION hues GitHub's own alerts use \u2014 a\n   long-established, non-proprietary convention, not DC branding) are\n   exposed as :root custom properties, the same author-settable-surface\n   pattern as the --gp-z-* ladder above: a book retints every alert of one\n   type by overriding a single property, no specificity fight required.\n   --gp-alert-color cascades from the type modifier down to .gp-alert-title\n   through ordinary CSS inheritance (the title is always a DOM descendant of\n   the box), so it is set in exactly five places, not ten. */\n:root {\n  --gp-alert-note-color: #0969da;\n  --gp-alert-tip-color: #1a7f37;\n  --gp-alert-important-color: #8250df;\n  --gp-alert-warning-color: #9a6700;\n  --gp-alert-caution-color: #cf222e;\n}\n:where(.gp-alert) {\n  margin: 1em 0;\n  padding: 0.5em 1em;\n  border-left: 0.25em solid var(--gp-alert-color, currentColor);\n}\n:where(.gp-alert-title) {\n  margin: 0 0 0.5em;\n  font-weight: bold;\n  color: var(--gp-alert-color, inherit);\n}\n:where(.gp-alert-note)      { --gp-alert-color: var(--gp-alert-note-color); }\n:where(.gp-alert-tip)       { --gp-alert-color: var(--gp-alert-tip-color); }\n:where(.gp-alert-important) { --gp-alert-color: var(--gp-alert-important-color); }\n:where(.gp-alert-warning)   { --gp-alert-color: var(--gp-alert-warning-color); }\n:where(.gp-alert-caution)   { --gp-alert-color: var(--gp-alert-caution-color); }\n";
 /**
  * GP_CLASSES — every class an author may legitimately write with a `gp-`
  * prefix: the `.gp-*` selectors in `GUTTERPRESS_CSS` above, the two

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

@@ -37,6 +37,20 @@ export declare function renderChapters(inputDir: string, opts?: {
     files?: string[] | null;
     plugins?: LoadedPlugin[];
     pluginCss?: string;
+    /**
+     * #238 — absolute paths of plugin-declared `styles` files, in plugin load
+     * order (`loadPluginsWithCss`'s `pluginStylePaths`). Inlined through the
+     * SAME pipeline the project's own stylesheets get (`inlineStyles`: fonts/
+     * images embedded, local `@import` followed, print-safety lintable) and
+     * placed in the SAME cascade position the legacy `pluginCss` string
+     * already holds — after core, before the project's own stylesheets.
+     * Absolute paths pass through `inlineStyles` unchanged (`path.resolve` is
+     * a no-op on an already-absolute input), so a plugin's stylesheet
+     * location is independent of `inputDir`. Omitting this (existing
+     * string-only-`css` plugins, or none at all) is a zero-cost, byte-
+     * identical no-op — see the test asserting exactly that.
+     */
+    pluginStylePaths?: string[];
     /** Wrap each source file for incremental preview pagination. */
     wrapChapters?: boolean;
     /** Add source-file ids to source-mapped preview blocks without wrappers. */
@@ -70,6 +84,8 @@ export declare function renderChaptersToFile(inputDir: string, outDir: string, o
     files?: string[] | null;
     plugins?: LoadedPlugin[];
     pluginCss?: string;
+    /** #238 — see {@link renderChapters}'s option of the same name. */
+    pluginStylePaths?: string[];
     /** ARCH finding #4 — see {@link renderChapters}'s option of the same name. */
     onChapterWarnings?: (file: string, warnings: LayoutWarning[]) => void;
     /** See {@link renderChapters}'s options of the same names. */

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

@@ -1,23 +1,12 @@
 import type { ResolvedPluginConfig } from "../../schema/manifest.types";
 import type { LoadedPlugin } from "./renderer";
 export type { GutterpressPlugin, GutterpressPluginMetadata, GutterpressPluginExport, LoadedPlugin, } from "./renderer";
-export { applyPlugins, collectPluginCss } from "./renderer";
+export { applyPlugins, collectPluginCss, collectPluginStylePaths } from "./renderer";
 /** Test-only mutation seam between snapshot completion and snapshot verification. */
 export declare function __setVendorSnapshotHookForTests(hook?: (sourceRoot: string, snapshotRoot: string) => void | Promise<void>): void;
 export declare function clearVendoredPluginResolver(baseDir: string, packageName: string, version: string): void;
 /** Test-only: reset the path-plugin cache between test cases. */
 export declare function __resetPathPluginCacheForTests(): void;
-/**
- * Load a single plugin from a file path or npm package.
- *
- * Throws if the plugin cannot be resolved, imported, or doesn't export a
- * valid plugin function. The error message identifies which manifest entry
- * failed so users can find it.
- *
- * Path plugins always go through the mtime cache (see the call below): it is
- * correct in both a one-shot CLI build and the long-lived Electron host that
- * runs `runBuild` in-process, so no caller-selected cache mode is needed.
- */
 export declare function loadPlugin(config: ResolvedPluginConfig, baseDir: string): Promise<LoadedPlugin>;
 /**
  * Load all plugins from the resolved configuration.
@@ -50,6 +39,13 @@ export interface LoadedPluginsWithCss {
      * straight through without an `?? []` at every call site. */
     plugins: LoadedPlugin[] | undefined;
     pluginCss: string;
+    /**
+     * #238 — absolute paths of every plugin-declared `styles` file, flattened
+     * in plugin load order. `[]` when no loaded plugin declares any (including
+     * when `configs` was empty), so callers can pass this straight through to
+     * `renderChapters`'s `pluginStylePaths` without an `?? []` guard.
+     */
+    pluginStylePaths: string[];
 }
 /**
  * Shared "load plugins -> collect their CSS" preamble (ARCH finding #53).

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

@@ -47,6 +47,7 @@ export interface GutterpressPluginMetadata {
  * export default plugin;
  * export const metadata: GutterpressPluginMetadata = { name: 'my-plugin', version: '1.0.0' };
  * export const css = `.my-class { color: red; }`;
+ * export const styles = ["./styles/components.css", "./styles/callouts.css"];
  * ```
  */
 export interface GutterpressPluginExport {
@@ -54,6 +55,17 @@ export interface GutterpressPluginExport {
     metadata?: GutterpressPluginMetadata;
     /** CSS injected into <head> after user stylesheets. Use sparingly — has equal cascade specificity. */
     css?: string;
+    /**
+     * File-based plugin CSS (#238), as paths RELATIVE TO THIS MODULE — resolved
+     * by the node-coupled loader (`plugins.ts`), never by this pure module. Each
+     * file enters the SAME pipeline a manifest `styles:` entry does: asset-
+     * inlined (fonts/images embedded, local `@import` followed) and print-safety
+     * lintable — unlike `css`, which is an opaque string no other subsystem can
+     * see. Kept alongside `css` (not a replacement) for one-liners that don't
+     * warrant a separate file. Cascade position matches `css`'s: after core,
+     * before the project's own stylesheets.
+     */
+    styles?: string[];
 }
 /** Internal representation of a loaded plugin, ready for `md.use()`. */
 export interface LoadedPlugin {
@@ -61,6 +73,13 @@ export interface LoadedPlugin {
     plugin: GutterpressPlugin;
     metadata?: GutterpressPluginMetadata;
     css?: string;
+    /**
+     * #238 — UNLIKE `GutterpressPluginExport.styles` (author-declared, relative
+     * to the plugin module), this is already resolved to ABSOLUTE filesystem
+     * paths by the loader (`plugins.ts`'s `loadPlugin`), in the plugin's own
+     * declared order. `undefined`/`[]` for a plugin that declares none.
+     */
+    styles?: string[];
     options: Record<string, unknown>;
 }
 /**
@@ -72,6 +91,14 @@ export interface LoadedPlugin {
  * non-technical author gets the feature instantly instead of a "not installed"
  * error. (attrs/footnote/deflist are NOT here — they are always-on defaults
  * applied unconditionally below.)
+ *
+ * `gutterpress-gfm-alerts` (#237) is keyed differently from its four
+ * siblings: it is not a real npm package, it is Gutterpress's OWN code
+ * (gfm-alerts.ts) registered under a name that reads like one, matching the
+ * shape "keyed by npm name" is written for. There is nothing to install
+ * either way — the lookup below always wins before any npm resolution is
+ * attempted (`plugins.ts`'s `loadPlugin`) — so a real npm package never
+ * existing under this exact name costs nothing.
  */
 export declare const BUILTIN_OPTIONAL_PLUGINS: Record<string, GutterpressPlugin>;
 /**
@@ -97,7 +124,16 @@ export declare const BUILTIN_OPTIONAL_PLUGINS: Record<string, GutterpressPlugin>
  *
  * GFM-style `> [!NOTE]` alerts were also moved into the DC plugin on the
  * same date because the emitted classes (dc-alert, dc-vibe-callout, etc.)
- * are DC-branded. Core should not leak DC identifiers.
+ * were DC-branded — core should not leak DC identifiers. #237 (0.10.7)
+ * restored a core-owned, unbranded equivalent as an OPT-IN bundled feature —
+ * `gfm-alerts.ts`, registered below as `gutterpress-gfm-alerts` — emitting
+ * only the standard GitHub five (NOTE/TIP/IMPORTANT/WARNING/CAUTION) as
+ * neutral `gp-alert`/`gp-alert-<type>` structure (see that file's header).
+ * This does not re-converge with the DC plugin: DC's branded extra types
+ * (`[!DM]`/`[!VIBE]`/`[!ORIGIN]`, etc.) and its own class names stay exactly
+ * where they were moved to, layered on top of (or independent from) this
+ * primitive. A project using neither plugin still renders `> [!NOTE]` as a
+ * literal blockquote, unchanged — this feature is opt-in, not a default.
  *
  * @param customPlugins - Optional array of custom plugins to load
  */
@@ -114,3 +150,14 @@ export declare function applyPlugins(md: MarkdownIt, plugins: LoadedPlugin[]): v
  * Collect CSS from all loaded plugins, concatenated in load order.
  */
 export declare function collectPluginCss(plugins: LoadedPlugin[]): string;
+/**
+ * Collect every plugin-declared stylesheet PATH (#238), flattened in plugin
+ * load order (a plugin's own files keep their declared order). These are
+ * already-resolved ABSOLUTE filesystem paths — `plugins.ts`'s loader resolves
+ * them before a `LoadedPlugin` exists, so this stays a pure list operation
+ * with no `node:*` needed, matching {@link collectPluginCss}. The caller feeds
+ * the result through the SAME asset-inline pipeline a manifest `styles:` list
+ * gets (see `lib/markdown/index.ts`'s `renderChapters`), which is where the
+ * files are actually read.
+ */
+export declare function collectPluginStylePaths(plugins: LoadedPlugin[]): string[];

package/dist/lib/style-declarations.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Resolve a declared stylesheet list to absolute, existence-checked paths, in
+ * declared order. `undefined`/`[]` returns `undefined` — a plugin/theme that
+ * declares no `styles` pays zero cost here, the exact contract #238
+ * established and #239 now shares. Any entry that doesn't resolve to a real
+ * file THROWS immediately: a final artifact must never silently drop an
+ * author-declared stylesheet from the cascade (CLAUDE.md §5's fail-fast
+ * doctrine) — this is the load-time check, matching a plugin's own
+ * missing-file error, not a render-time warning.
+ *
+ * `baseDir` is never resolved by this function — whether a plugin/theme even
+ * HAS a usable base directory (e.g. a plugin loaded via a bare npm specifier
+ * with no on-disk path) is a caller-specific question the caller answers
+ * before calling this; by the time `baseDir` reaches here it names a real
+ * directory to resolve `rawStyles` against.
+ *
+ * @param subject Names the declaring thing for the error message, e.g.
+ *   `Plugin "my-plugin"` or `Theme "dc-design"`.
+ */
+export declare function resolveDeclaredStyles(rawStyles: string[] | undefined, baseDir: string, subject: string): string[] | undefined;

package/dist/lib/style-resolver.d.ts

@@ -7,6 +7,8 @@ export interface ProjectStyle {
     /** True when this stylesheet is in the manifest `styles:` list (the active set). */
     active: boolean;
 }
+/** Project-relative, forward-slash display path for an absolute css path. */
+export declare function relDisplay(projectDir: string, absPath: string): string;
 /**
  * THE canonical "which stylesheet does this project use?" resolver — consumed by
  * BOTH the renderer (to `<link>` them) and the editor (to edit them), so they

package/dist/lib/theme-manager.d.ts

@@ -10,6 +10,34 @@ export interface ThemeMetadata {
     description?: string;
     /** Optional preview image path (relative to the theme folder). */
     preview?: string | null;
+    /**
+     * #239 — ordered stylesheets, relative to the theme folder. A theme is no
+     * longer capped at one file: this is what lets a real component library
+     * (tokens/base/components/templates/rules as separate layered sheets) be a
+     * theme. Absent/empty defaults to `["theme.css"]` — every theme published
+     * before this field existed keeps working, byte-for-byte, untouched. Globs
+     * are NOT supported, matching the manifest's own `styles:` list (§0 — one
+     * authoring convention, not two).
+     */
+    styles?: string[];
+    /**
+     * #239 — engine-conditional sheets, relative to the theme folder. Applying
+     * the theme appends these to the manifest's `engineStyles.native` list
+     * (loaded last, so furniture wins — see manifest.ts's resolveWithPreset).
+     */
+    engineStyles?: {
+        native?: string[];
+    };
+    /**
+     * #239 — which declared sheet (a path from `styles`, or `theme.css` when
+     * `styles` is absent) carries the author-facing `:root` token surface. Lets
+     * a rich multi-sheet theme tell the Design panel's guided token editor
+     * where to look instead of it guessing at the single active stylesheet.
+     * Purely advisory metadata — nothing in this module enforces it. Absent
+     * here means "no override"; {@link ThemeInfo.tokensFile} is where the
+     * default (the theme's primary/only sheet) gets filled in.
+     */
+    tokensFile?: string;
 }
 /** Author-friendly metadata for one theme (built-in or project). */
 export interface ThemeInfo {
@@ -25,6 +53,23 @@ export interface ThemeInfo {
     kind: "builtin" | "project";
     /** Optional preview image path relative to the theme folder. */
     preview?: string | null;
+    /**
+     * #239 — the theme's declared stylesheets, relative to the theme folder, in
+     * cascade order. Always populated (defaults to `["theme.css"]` when the
+     * theme declares no `styles`), so a caller never needs to re-derive the
+     * default itself.
+     */
+    styles: string[];
+    /**
+     * #239 — which declared sheet (relative to the theme folder) carries the
+     * `:root` token surface — see {@link ThemeMetadata.tokensFile}. ALWAYS
+     * populated: an explicit `theme.json` declaration wins, otherwise this
+     * defaults to the theme's primary sheet (`styles[0]`) — `"theme.css"` for
+     * every legacy single-sheet theme, exactly as `styles` itself defaults.
+     * A caller (the Design panel) never needs its own "guess the token sheet"
+     * fallback.
+     */
+    tokensFile: string;
 }
 /** A built-in theme resolved to disk (extracted from the embedded assets). */
 export interface ResolvedTheme {
@@ -42,19 +87,54 @@ export type ApplyThemeTarget = {
     kind: "project";
     id: string;
 };
+/**
+ * A theme's declared stylesheets, relative to its folder, in cascade order
+ * (#239). An absent OR empty `styles` defaults to `["theme.css"]` — the
+ * single-file format every theme published before this field existed already
+ * satisfies, so nothing needs migrating. Exported for `theme-import.ts`,
+ * which validates every one of these (existence + print-safety) at import
+ * time, the same way it always validated the lone `theme.css`.
+ */
+export declare function themeStyleList(meta: ThemeMetadata): string[];
+/**
+ * Every declared sheet must live INSIDE the theme folder. A theme is
+ * self-contained by contract (apply copies the whole folder), and an imported
+ * package is untrusted input: a `../` or absolute entry would make apply read
+ * a file from anywhere on disk into the book.
+ *
+ * This is a WRITE-BOUNDARY guard — `applyTheme`, `importThemeFromFolder` and
+ * `theme-import.ts`'s package validation call it before copying anything or
+ * wiring a manifest. It deliberately does NOT live in {@link themeStyleList},
+ * which the read paths (`listProjectThemes`, `getActiveTheme`,
+ * `getPreviousTheme`, `readThemeCss`) also call: one hand-edited theme.json
+ * must not take down listing every theme, the same reason `readThemeMeta`
+ * returns `{}` for an unparseable file instead of throwing.
+ */
+export declare function assertThemeSheetsContained(meta: ThemeMetadata): void;
+/**
+ * A theme's declared engine-conditional sheets, relative to its folder
+ * (#239). `Array.isArray` guards a malformed `engineStyles.native` (authored
+ * as something other than a list) — treated as "none declared" rather than a
+ * hard crash on a JSON author's typo. Exported for `theme-import.ts`'s import
+ * validation, same reuse rationale as {@link themeStyleList}.
+ */
+export declare function themeEngineStyleList(meta: ThemeMetadata): string[];
 /** List the built-in themes (metadata read from the extracted embedded assets). */
 export declare function listBuiltInThemes(): Promise<ThemeInfo[]>;
 /** Resolve a built-in theme to its extracted `theme.css` + parsed metadata. */
 export declare function resolveBuiltInTheme(id: string): Promise<ResolvedTheme>;
 /**
  * List the themes that live inside the project under `themes/<id>/` (each a
- * folder with a `theme.css`). Returns `[]` when there is no `themes/` folder.
+ * folder whose PRIMARY declared sheet exists — `theme.css` by default, or
+ * `theme.json`'s `styles[0]` for a multi-sheet theme, #239). Returns `[]`
+ * when there is no `themes/` folder.
  */
 export declare function listProjectThemes(projectDir: string): Promise<ThemeInfo[]>;
 /**
- * Read the project's currently active theme (the theme whose `theme.css` is in
- * the manifest `styles:` list AND whose folder exists under `themes/`). Returns
- * `null` when no theme is applied.
+ * Read the project's currently active theme (the theme with an entry under
+ * `themes/<id>/…` in the manifest `styles:` list AND whose folder's PRIMARY
+ * declared sheet still exists on disk, #239). Returns `null` when no theme is
+ * applied.
  */
 export declare function getActiveTheme(projectDir: string): Promise<ThemeInfo | null>;
 /**
@@ -92,8 +172,10 @@ export declare function revertTheme(projectDir: string): Promise<ThemeInfo>;
 export declare function applyTheme(projectDir: string, target: ApplyThemeTarget): Promise<ThemeInfo>;
 /**
  * Import a theme from a local folder by copying it into the project's
- * `themes/<id>/`. The folder MUST contain a `theme.css`. Metadata comes from
- * its `theme.json` (synthesised from the folder name when absent). The imported
+ * `themes/<id>/`. The folder MUST contain its PRIMARY declared stylesheet —
+ * `theme.css` by default, or `theme.json`'s `styles[0]` for a multi-sheet
+ * theme (#239) that ships no `theme.css` at all. Metadata comes from its
+ * `theme.json` (synthesised from the folder name when absent). The imported
  * theme becomes available to {@link applyTheme}; importing does NOT auto-apply.
  */
 export declare function importThemeFromFolder(projectDir: string, sourceDir: string): Promise<ThemeInfo>;
@@ -114,8 +196,11 @@ export declare function importThemeFromFolder(projectDir: string, sourceDir: str
 export declare function importThemeFromUrl(projectDir: string, url: string): Promise<ThemeInfo>;
 /**
  * Read a theme's CSS for previewing. Built-in themes read from the embedded
- * assets; project themes read from `themes/<id>/theme.css`. Used by the host to
- * feed the renderer a sample-render thumbnail (the renderer never touches fs).
+ * assets; project themes read and concatenate EVERY sheet `theme.json`
+ * declares (#239 — `theme.css` alone when it declares none), in cascade
+ * order. Used by the host to feed the renderer a sample-render thumbnail (the
+ * renderer never touches fs) — a read-only preview, so concatenation is fine
+ * even though it wouldn't be for an editable surface.
  */
 export declare function readThemeCss(projectDir: string | null, source: {
     kind: "builtin" | "project";
@@ -123,6 +208,22 @@ export declare function readThemeCss(projectDir: string | null, source: {
 }): Promise<string>;
 /**
  * Remove an imported/applied project theme folder. If it was the active theme,
- * its `styles:` entry is dropped too. Never touches built-in (embedded) themes.
+ * its ENTIRE block is dropped too — every `styles:` entry AND every
+ * `engineStyles.native` entry under `themes/<id>/…` (#239), not just a single
+ * `theme.css` href. Never touches built-in (embedded) themes.
  */
 export declare function removeProjectTheme(projectDir: string, id: string): Promise<void>;
+/**
+ * #236 follow-through: detect a project whose `styles/book.css` is
+ * byte-identical to a built-in theme's `theme.css` while NO theme is tracked
+ * as active. That shape is exactly what a pre-0.10.7 `gutterpress new` (or
+ * "set up as a book") produced — a real, working stylesheet that is simply
+ * invisible to this command and to the desktop's Theme panel, and which will
+ * keep loading AFTER (so silently override) whatever theme is applied next.
+ * Read-only: this never modifies the project — it only surfaces a note so the
+ * author can decide whether to run `theme apply` themselves.
+ */
+export declare function detectLegacyForkedTheme(projectDir: string, active: ThemeInfo | null): Promise<{
+    id: string;
+    name: string;
+} | null>;

package/dist/{lint-nm57gn26.js → lint-zbymjr1z.js}

@@ -1,16 +1,16 @@
 import {
   MANIFEST_FILENAMES,
   runLint
-} from "./cli-kwt5ftvc.js";
+} from "./cli-w6h5zegm.js";
 import {
   log
-} from "./cli-m99hj80k.js";
+} from "./cli-mk1s46mx.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-he23vgjj.js";
-import"./cli-bwbs3qm4.js";
+} from "./cli-08psmhr5.js";
+import"./cli-s8q42x3r.js";
 import"./cli-c41yr7he.js";
 import {
   EXIT_CODES

package/dist/{manifest.schema-hn6ac0ae.json → manifest.schema-kwnrwv8b.json}

@@ -38,13 +38,8 @@
     },
     "engineStyles": {
       "type": "object",
-      "description": "Engine-conditional stylesheets, appended AFTER `styles`. `.native` is the only list that still applies; `.paged` is accepted-but-ignored (a warning fires if it has entries).",
+      "description": "Engine-conditional stylesheets, appended AFTER `styles`. `.native` is the only list — the native engine is the only engine, so there is nothing else to condition on. A manifest from the dual-engine era may still carry `.paged`; it keeps loading (with a one-line warning) but is no longer part of this schema.",
       "properties": {
-        "paged": {
-          "type": "array",
-          "description": "Accepted for backward-compatible manifest parsing only; entries here are ignored with a warning.",
-          "items": { "type": "string" }
-        },
         "native": { "type": "array", "items": { "type": "string" } }
       },
       "additionalProperties": false,
@@ -58,7 +53,7 @@
     },
     "styles": {
       "type": "array",
-      "description": "Project-relative CSS files to <link> into the rendered book, applied in order. If omitted, Gutterpress discovers one: styles/book.css, else css/print.css, css/index.css, css/style.css, css/main.css, else the first discovered .css, else none.",
+      "description": "Project-relative CSS files to <link> into the rendered book, applied in order. If omitted, Gutterpress discovers one: styles/book.css (what `gutterpress new` scaffolds), else four legacy names kept only for pre-existing projects — css/print.css, css/index.css, css/style.css, css/main.css — else the first discovered .css, else none. New projects should set this explicitly or use styles/book.css.",
       "items": {
         "type": "string",
         "minLength": 1,
@@ -115,7 +110,7 @@
               },
               "priority": {
                 "type": "integer",
-                "description": "Load order. Higher priority loads first.",
+                "description": "Advanced, rarely needed. Load order: higher loads first. If one of your plugins needs to see tokens another one of your plugins produces, give it the LOWER number of the two, so it loads (and runs) after.",
                 "default": 100,
                 "examples": [100, 200]
               },
@@ -322,6 +317,14 @@
                 { "type": "boolean", "const": false }
               ]
             },
+            "cssOwnership": {
+              "description": "Path to a CSS ownership contract (default discovery: .gutterpress/css-contract.yaml), or false to disable the source.css-ownership check. Optional — absent means no contract, so the check reports nothing.",
+              "default": null,
+              "oneOf": [
+                { "type": "string", "minLength": 1 },
+                { "type": "boolean", "const": false }
+              ]
+            },
             "allowedCallouts": {
               "type": "array",
               "deprecated": true,