gutterpress 0.10.9 → 0.10.10-alpha.1

package/README.md

@@ -147,7 +147,7 @@ Scaffold a new book, plugin or theme from an embedded starter template — the f
 
 `--kind book` is the default. Every new book picks the vendor preset it's designed for: `dtrpg` (DriveThruRPG print-on-demand), `book` (neutral 6x9in trade book), or `custom` (you supply the trim size in points).
 
-`--kind plugin` and `--kind theme` scaffold an **extension package** instead — a folder with a `gutterpress.json` a book can load. The plugin starter carries a declarative marker table, a hand-written markdown-it rule, component CSS and a `bun test` fixture suite; the theme starter carries the six-file layered CSS architecture (tokens / base / components / page-templates / page-rules / book), each sheet opening with its own OWNS / MUST NOT CONTAIN contract header. Both include a README explaining which conventions are load-bearing. An extension needs no preset, trim size or publish target, so the book-only flags below are rejected rather than ignored when `--kind` names one — and `--prefix`/`--description` are likewise rejected for a book.
+`--kind plugin` and `--kind theme` scaffold an **extension package** instead — a folder with a `package.json` a book can load. The plugin starter carries a declarative marker table, a hand-written markdown-it rule, component CSS and a `bun test` fixture suite; the theme starter carries the six-file layered CSS architecture (tokens / base / components / page-templates / page-rules / book), each sheet opening with its own OWNS / MUST NOT CONTAIN contract header. Both include a README explaining which conventions are load-bearing. An extension needs no preset, trim size or publish target, so the book-only flags below are rejected rather than ignored when `--kind` names one — and `--prefix`/`--description` are likewise rejected for a book.
 
 ```sh
 gutterpress new <name> [--kind <id>] [options]
@@ -194,7 +194,7 @@ gutterpress preview [input-dir] [options]
   --icc <path>            Path to ICC profile (required for --format pdfx)
   --manifest <path>       Path to manifest.yaml                          (pdf|pdfx only)
   --strip-annotations     Strip PDF annotations for PDF/X compliance    (pdfx only)
-  --skip-lint             Skip CSS linting                              (pdf|pdfx only)
+  --skip-lint             Skip the CSS print-safety check               (pdf|pdfx only)
   --skip-pre-validate     Skip pre-build validation                     (pdf|pdfx only)
   --skip-post-validate    Skip post-build PDF/X validation              (pdfx only)
   --allow-shrink          Build anyway when content is wider than the page content box (pdf|pdfx only)
@@ -202,7 +202,7 @@ gutterpress preview [input-dir] [options]
 
 ### `gutterpress build`
 
-Build a PDF (default) or HTML output. Pipeline: `lint → validate:pre → convert → assets → build → validate:post`.
+Build a PDF (default) or HTML output. Pipeline: `validate:pre → convert → assets → build → validate:post`. The CSS print-safety check (remote urls, risky print effects, page-containment) runs once, inside `validate:pre`, as the `source.stylelint` check — there is no separate lint phase.
 
 ```sh
 gutterpress build [input-dir] [options]
@@ -214,12 +214,27 @@ gutterpress build [input-dir] [options]
   --icc <path>            Path to ICC profile (required for --format pdfx)
   --manifest <path>       Path to manifest.yaml
   --strip-annotations     Strip PDF annotations for PDF/X compliance
-  --skip-lint             Skip the CSS print-safety pass (default: lint runs for pdf/pdfx)
+  --skip-lint             Skip the CSS print-safety check (default: it runs for pdf/pdfx)
   --skip-pre-validate     Skip pre-build validation
   --skip-post-validate    Skip post-build PDF/X validation
   --allow-shrink          Build anyway when content is wider than the page content box. Chromium then scales the WHOLE book down to fit it — the build reports that whole-document scale (e.g. "about 0.72x its declared size") plus every offender, as warnings.
 ```
 
+A `--out <dir>` is shared between formats safely: each build delivers only
+what its own format produces, so it never disturbs another format's output
+already sitting in that folder. `--format html` writes `book.html` (with the
+viewer bundle), `index.html`, and referenced assets. `--format pdf`/`pdfx`
+writes only its own PDF (e.g. `my-book-pdf.pdf`). This is what makes the
+two-command sequence below safe:
+
+```sh
+gutterpress build --format html --out ./_site
+gutterpress build --format pdf --out ./_site
+```
+
+`./_site` ends up with the paginating `book.html` from the first command
+plus the PDF from the second — the pdf build never overwrites `book.html`.
+
 ### `gutterpress publish`
 
 Push a built PDF/HTML artifact to a publishing platform (itch.io, DriveThruRPG, Amazon KDP, Azure Static Web Apps, Shopify, Google Drive), headlessly and CI-safely. Credentials live in a 0600 user-config store (never in the project); provider env vars override it for CI. Most providers connect with a pasted API key; Google Drive connects through your browser instead (`--connect` opens the sign-in page — nothing to paste).
@@ -346,7 +361,7 @@ terminal is the same entry the GUI shows.
 ```sh
 gutterpress ext
 
-  --help    Show ext subcommands (list, add, remove, enable, disable)
+  --help    Show ext subcommands (list, add, remove, enable, disable, search)
 ```
 
 Every subcommand takes the project directory as an optional trailing
@@ -426,6 +441,32 @@ gutterpress ext disable markdown-it-mark ./my-book
 gutterpress ext enable markdown-it-mark ./my-book
 ```
 
+#### `gutterpress ext search`
+
+Search **npm** for extensions — the same list the desktop app's Features view
+shows under "Find more on npm." Not project-scoped (no `dir` argument): it
+queries the registry for packages tagged `gutterpress` (Gutterpress
+extensions: plugins, looks, component libraries) or `markdown-it-plugin` (the
+markdown-it ecosystem's own tag — those work in Gutterpress unchanged), and
+prints each match's `name@version`, which kind it is, and its description,
+ending with the `ext add` command to install it.
+
+```sh
+gutterpress ext search [query]
+```
+
+```sh
+gutterpress ext search
+gutterpress ext search footnote
+```
+
+An empty or omitted `query` lists the most relevant tagged packages. To
+publish an extension, `npm publish` it with `"gutterpress"` in its
+`keywords` — there is no index to be added to and nothing to register. Set
+`GUTTERPRESS_NPM_REGISTRY` to point at a different registry (http/https only)
+— useful for a private mirror, or for testing; the installer uses the same
+setting, and only accepts tarballs from that registry's own origin.
+
 ## Exit codes
 
 Every command follows the same exit-code contract, so CI can branch on the result without parsing output:
@@ -462,6 +503,26 @@ extensions:
     enabled: false               # keep the entry, skip loading it
 ```
 
+An extension folder (or npm package) describes itself in its **`package.json`** — there is no second, Gutterpress-specific manifest file. npm's own fields are read as-is, and everything Gutterpress needs sits under one optional `"gutterpress"` key:
+
+```json
+{
+  "name": "field-notes",
+  "description": "Margin notes and term boxes",
+  "author": "You",
+  "keywords": ["gutterpress", "markdown-it-plugin"],
+  "main": "plugin.js",
+  "gutterpress": {
+    "styles": ["styles/plugin.css"],
+    "snippets": "snippets",
+    "components": "components.yaml",
+    "tokensFile": "styles/tokens.css"
+  }
+}
+```
+
+`main` is the markdown-it plugin — npm's own convention — so a plain markdown-it plugin package needs nothing else at all. A look needs only `gutterpress.styles` (an ordered list, relative to the folder); a component library carries both. `gutterpress.markdown` exists for the one case `main` can't express: a package whose `main` is not the plugin. Folders still carrying the removed `gutterpress.json` or `theme.json` fail to load with a message showing the package.json that replaces them.
+
 Order is load order: a later entry's markdown runs after earlier entries' (and sees their output) and its CSS wins ties; the project's own `styles:` always load after every extension. There is no `priority` and no `path:`/`name:` wrapper — a manifest still carrying `plugins:` fails with a message that prints the same entries rewritten as `extensions:`. The `engine:` and `engineStyles:` keys are gone too (there is one engine; move any `engineStyles` entries to the end of `styles:`).
 
 Pinned npm packages and their runtime dependencies live under `plugins/npm/`,

package/dist/{README-jntqyj1z.md → README-3zk4tgnj.md}

@@ -7,12 +7,12 @@ CSS and insertable snippets to a book.
 
 ```
 {{SLUG}}/
-├── gutterpress.json     what this package declares to Gutterpress
+├── package.json         what this package declares: `main` is the plugin,
+│                        the `gutterpress` block names the styles and snippets
 ├── plugin.js            the markdown-it plugin (declarative + bespoke halves)
 ├── styles/plugin.css    component CSS, with public tokens at :root
 ├── snippets/            insertable recipes, one per component
-├── test/                fixture.md → expected.html, runnable with `bun test`
-└── package.json         only needed for `bun test` and publishing to npm
+└── test/                fixture.md → expected.html, runnable with `bun test`
 ```
 
 ## Try it
@@ -32,7 +32,7 @@ extensions:
 `gutterpress ext add ./plugins/{{SLUG}} <book>` writes that line for you (the
 book directory is the second positional argument). Either way the entry names
 the FOLDER, not `plugin.js`. That is what makes Gutterpress read
-`gutterpress.json` and pick up the stylesheet and snippets alongside the
+`package.json` and pick up the stylesheet and snippets alongside the
 markdown behaviour — point it at the `.js` file and you get the markdown and
 nothing else. The folder is referenced in place, never copied: keep editing it
 and the book follows.

package/dist/{README-6c7fda1s.md → README-7x5akcns.md}

@@ -8,7 +8,8 @@ arrangement of the files is the part worth keeping.
 
 ```
 {{SLUG}}/
-├── gutterpress.json          what this package declares to Gutterpress
+├── package.json              what this package declares: the `gutterpress`
+│                             block names the sheets, catalog and snippets
 ├── components.yaml           the catalog: what an author can opt into
 ├── snippets/                 insertable recipes for the components
 └── styles/
@@ -129,9 +130,9 @@ That asymmetry is the whole difference between the two kinds of package.
 ```
 
 Each sheet then puts everything it owns inside its layer. The cascade is
-settled by that one line rather than by which sheet `gutterpress.json`'s
-`styles` lists last, so splitting a sheet or reordering that list can no
-longer silently flip who wins.
+settled by that one line rather than by which sheet `package.json`'s
+`gutterpress.styles` lists last, so splitting a sheet or reordering that list
+can no longer silently flip who wins.
 
 The trap, and it catches everyone once: a rule left OUTSIDE all the layers is
 fully unlayered, and unlayered CSS beats layered CSS at any specificity. So

package/dist/api/index.d.ts

@@ -39,15 +39,18 @@ export { BUNDLED_EXTENSIONS, isBundledExtension, isPathSpecifier, parseExtension
 export type { ParsedExtensionSpecifier } from "../lib/extension-specifier.ts";
 export { importExtensionFromFile, importExtensionFromUrl } from "../lib/extension-import.ts";
 export type { ExtensionImportResult, ExtensionImportWarning } from "../lib/extension-import.ts";
-export { EXTENSION_MANIFEST_FILENAME, LEGACY_THEME_MANIFEST_FILENAME, readExtensionMeta, extensionStyleList, extensionStyleListWithDefault, extensionCarries, assertExtensionContained, pathEscapesFolder, resolveExtension, } from "../lib/extension-manifest.ts";
+export { MAX_SEARCH_BYTES, SEARCH_KEYWORDS, searchNpmExtensions, } from "../lib/extension-search.ts";
+export type { ExtensionSearchKind, NpmExtensionMatch, NpmExtensionSearchResult, SearchNpmExtensionsOptions, } from "../lib/extension-search.ts";
+export { DEFAULT_NPM_REGISTRY, npmRegistryUrl } from "../lib/npm-registry.ts";
+export { EXTENSION_MANIFEST_FILENAME, readExtensionMeta, extensionStyleList, extensionEntry, extensionCarries, assertExtensionContained, pathEscapesFolder, resolveExtension, } from "../lib/extension-manifest.ts";
 export type { ExtensionMetadata, ResolvedExtension, ExtensionCarries, } from "../lib/extension-manifest.ts";
 export { listProjectStyles, resolveActiveStyles } from "../lib/style-resolver.ts";
 export type { ProjectStyle } from "../lib/style-resolver.ts";
 export { readManifestFields, setManifestFields, setActiveStyles, } from "../lib/manifest-config.ts";
 export type { ProjectConfigFields } from "../lib/manifest-config.ts";
-export { providerFor, restoreVersionWithBackup, isNoChangesError, AUTO_SNAPSHOT_MESSAGE, RESTORE_BACKUP_MESSAGE, HISTORY_PAGE_LIMIT, } from "../lib/source-provider.ts";
-export type { ListHistoryOptions, HistoryPage, } from "../lib/source-provider.ts";
-export { autoSnapshotDelayMs, autoSyncDelayMs, isGitInternalPath, AUTO_SNAPSHOT_MIN_MINUTES, AUTO_SNAPSHOT_MAX_MINUTES, AUTO_SNAPSHOT_DEFAULT_MINUTES, AUTO_SYNC_MIN_MINUTES, AUTO_SYNC_MAX_MINUTES, AUTO_SYNC_DEFAULT_MINUTES, AUTO_SYNC_PUSH_INTERVAL_MINUTES, } from "../lib/host-policy.ts";
+export { providerFor, restoreVersionWithBackup, isNoChangesError, AUTO_SNAPSHOT_MESSAGE, RESTORE_BACKUP_MESSAGE, HISTORY_PAGE_LIMIT, listLocalBranches, switchBranch, SWITCH_BRANCH_SNAPSHOT_MESSAGE, } from "../lib/source-provider.ts";
+export type { ListHistoryOptions, HistoryPage, LocalBranches, SwitchBranchOptions, SwitchBranchResult, } from "../lib/source-provider.ts";
+export { autoSnapshotDelayMs, autoSyncDelayMs, isGitInternalPath, AUTO_SNAPSHOT_DEFAULT_MINUTES, AUTO_SYNC_MIN_MINUTES, AUTO_SYNC_MAX_MINUTES, AUTO_SYNC_DEFAULT_MINUTES, AUTO_SYNC_PUSH_INTERVAL_MINUTES, } from "../lib/host-policy.ts";
 export type { AutoSnapshotPolicy, AutoSyncPolicy, } from "../lib/host-policy.ts";
 export { FileTokenStore, defaultConfigDir, extractUrlCredential, } from "../lib/remote-auth/token-store.ts";
 export type { HostCredential, TokenStore, UrlCredentialExtraction, } from "../lib/remote-auth/token-store.ts";

package/dist/api/index.js

@@ -1,7 +1,5 @@
 import {
   AUTO_SNAPSHOT_DEFAULT_MINUTES,
-  AUTO_SNAPSHOT_MAX_MINUTES,
-  AUTO_SNAPSHOT_MIN_MINUTES,
   AUTO_SYNC_DEFAULT_MINUTES,
   AUTO_SYNC_MAX_MINUTES,
   AUTO_SYNC_MIN_MINUTES,
@@ -9,6 +7,7 @@ import {
   BUILT_IN_STYLE_SET_IDS,
   BUILT_IN_TEMPLATE_IDS,
   BUNDLED_EXTENSIONS,
+  DEFAULT_NPM_REGISTRY,
   EXTENSIONS_DIR,
   EXTENSION_KINDS,
   EXTENSION_MANIFEST_FILENAME,
@@ -18,14 +17,15 @@ import {
   GOOGLE_NOT_CONFIGURED_MESSAGE,
   GitHubAuthProvider,
   GoogleAuthProvider,
-  LEGACY_THEME_MANIFEST_FILENAME,
   MANIFEST_FILENAMES,
+  MAX_SEARCH_BYTES,
   PLUGINS_DIR,
   PRESETS,
   PRESET_IDS,
   PublishSelectionsStore,
   RECOMMENDED_EXTENSIONS,
   RESERVED_PREFIX,
+  SEARCH_KEYWORDS,
   SNIPPETS_DIR,
   SYNC_SNAPSHOT_MESSAGE,
   TARGETS,
@@ -47,8 +47,8 @@ import {
   disconnectPublishCredential,
   escapeYamlScalar,
   extensionCarries,
+  extensionEntry,
   extensionStyleList,
-  extensionStyleListWithDefault,
   extractUrlCredential,
   extractVariables,
   forgeKindForHost,
@@ -75,6 +75,7 @@ import {
   listRepoBooks,
   listSnippets,
   loadManifestWithPath,
+  npmRegistryUrl,
   parseExtensionSpecifier,
   parseRemoteOrigin,
   pathEscapesFolder,
@@ -110,6 +111,7 @@ import {
   saveSnippet,
   scaffoldExtension,
   scaffoldProject,
+  searchNpmExtensions,
   setActiveStyles,
   setExtensionEnabled,
   setManifestFields,
@@ -121,21 +123,24 @@ import {
   syncProject,
   testRemoteAccess,
   validateProjectExtensions
-} from "../index-mey5vraz.js";
+} from "../index-d4wrww4b.js";
 import {
   BuildError,
   DEFAULT_PRINT_OPTS,
   readyProbeExpr
-} from "../index-zwcv1njy.js";
+} from "../index-5dgxeevv.js";
 import {
   AUTO_SNAPSHOT_MESSAGE,
   HISTORY_PAGE_LIMIT,
   RESTORE_BACKUP_MESSAGE,
+  SWITCH_BRANCH_SNAPSHOT_MESSAGE,
   isNoChangesError,
+  listLocalBranches,
   providerFor,
   resolveLogger,
-  restoreVersionWithBackup
-} from "../index-dtrftayr.js";
+  restoreVersionWithBackup,
+  switchBranch
+} from "../index-f833dtg9.js";
 import {
   capabilitiesFor,
   detectProjectSource,
@@ -148,6 +153,7 @@ export {
   validateProjectExtensions,
   testRemoteAccess,
   syncProject,
+  switchBranch,
   substituteVariables,
   startPreviewServer,
   splitOutPath,
@@ -156,6 +162,7 @@ export {
   setManifestFields,
   setExtensionEnabled,
   setActiveStyles,
+  searchNpmExtensions,
   scaffoldProject,
   scaffoldExtension,
   saveSnippet,
@@ -197,6 +204,7 @@ export {
   pathEscapesFolder,
   parseRemoteOrigin,
   parseExtensionSpecifier,
+  npmRegistryUrl,
   loadManifestWithPath,
   listSnippets,
   listRepoBooks,
@@ -205,6 +213,7 @@ export {
   listProjectStyles,
   listProjectExtensions,
   listMergedSnippets,
+  listLocalBranches,
   listGitHubRepositories,
   listGitHubBranches,
   listCustomTemplates,
@@ -225,8 +234,8 @@ export {
   findEnclosingRepoDir,
   extractVariables,
   extractUrlCredential,
-  extensionStyleListWithDefault,
   extensionStyleList,
+  extensionEntry,
   extensionCarries,
   escapeYamlScalar,
   disconnectPublishCredential,
@@ -249,7 +258,9 @@ export {
   TARGET_IDS,
   TARGETS,
   SYNC_SNAPSHOT_MESSAGE,
+  SWITCH_BRANCH_SNAPSHOT_MESSAGE,
   SNIPPETS_DIR,
+  SEARCH_KEYWORDS,
   RESTORE_BACKUP_MESSAGE,
   RESERVED_PREFIX,
   RECOMMENDED_EXTENSIONS,
@@ -257,8 +268,8 @@ export {
   PRESET_IDS,
   PRESETS,
   PLUGINS_DIR,
+  MAX_SEARCH_BYTES,
   MANIFEST_FILENAMES,
-  LEGACY_THEME_MANIFEST_FILENAME,
   HISTORY_PAGE_LIMIT,
   GoogleAuthProvider,
   GitHubAuthProvider,
@@ -270,6 +281,7 @@ export {
   EXTENSION_KINDS,
   EXTENSIONS_DIR,
   DEFAULT_PRINT_OPTS,
+  DEFAULT_NPM_REGISTRY,
   BuildError,
   BUNDLED_EXTENSIONS,
   BUILT_IN_TEMPLATE_IDS,
@@ -278,8 +290,6 @@ export {
   AUTO_SYNC_MIN_MINUTES,
   AUTO_SYNC_MAX_MINUTES,
   AUTO_SYNC_DEFAULT_MINUTES,
-  AUTO_SNAPSHOT_MIN_MINUTES,
   AUTO_SNAPSHOT_MESSAGE,
-  AUTO_SNAPSHOT_MAX_MINUTES,
   AUTO_SNAPSHOT_DEFAULT_MINUTES
 };

package/dist/{audit-fq7s1gsz.js → audit-ek36tf4q.js}

@@ -1,20 +1,20 @@
 import {
   executeAndReport
-} from "./cli-8pg731p5.js";
+} from "./cli-5fqr02je.js";
 import {
   log
-} from "./cli-ypfvnhag.js";
+} from "./cli-12epgrva.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-rh05byck.js";
-import"./cli-bx950tb4.js";
+} from "./cli-tvpq2ht9.js";
+import"./cli-k8f9eb12.js";
 import"./cli-c41yr7he.js";
 import {
   EXIT_CODES
 } from "./cli-46ycxe6r.js";
-import"./cli-w692g6dx.js";
+import"./cli-vje8g3w8.js";
 import"./cli-v5mp7a6q.js";
 import"./cli-37x76zdn.js";
 

package/dist/{build-dyat3fqd.js → build-bxavfz3j.js}

@@ -1,23 +1,23 @@
 import {
   runBuild,
   splitOutPath
-} from "./cli-8pg731p5.js";
+} from "./cli-5fqr02je.js";
 import {
   log
-} from "./cli-ypfvnhag.js";
+} from "./cli-12epgrva.js";
 import {
   UsageError,
   parseFormat,
   parsePdfxFlavor,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-rh05byck.js";
-import"./cli-bx950tb4.js";
+} from "./cli-tvpq2ht9.js";
+import"./cli-k8f9eb12.js";
 import"./cli-c41yr7he.js";
 import {
   BuildError
 } from "./cli-46ycxe6r.js";
-import"./cli-w692g6dx.js";
+import"./cli-vje8g3w8.js";
 import"./cli-v5mp7a6q.js";
 import"./cli-37x76zdn.js";
 
@@ -33,7 +33,7 @@ var commandArgs = {
   icc: { type: "string", description: "Path to ICC profile (required for --format pdfx)" },
   manifest: { type: "string", description: "Path to manifest.yaml" },
   "strip-annotations": { type: "boolean", description: "Strip PDF annotations for PDF/X compliance" },
-  "skip-lint": { type: "boolean", description: "Skip CSS linting (default: lint runs for pdf/pdfx)" },
+  "skip-lint": { type: "boolean", description: "Skip the CSS print-safety check (default: it runs for pdf/pdfx)" },
   "skip-pre-validate": { type: "boolean", description: "Skip pre-build validation" },
   "skip-post-validate": { type: "boolean", description: "Skip post-build PDF/X validation" },
   "allow-shrink": { type: "boolean", description: "Build anyway when content is wider than the page content box, instead of failing. Chromium then scales the WHOLE book down to fit; each offender is reported as a warning." }

package/dist/{cli-ypfvnhag.js → cli-12epgrva.js}

@@ -1,6 +1,6 @@
 import {
   package_default
-} from "./cli-rh05byck.js";
+} from "./cli-tvpq2ht9.js";
 import {
   execCapture,
   findTool,