gutterpress 0.10.9 → 0.10.10-alpha.2

package/dist/lib/extension-import.d.ts

@@ -40,7 +40,7 @@ export declare function classifyThemeCssFindings(findings: PrintSafeWarning[]):
 };
 /**
  * From a theme folder's relative file paths, return the ones that are neither
- * `theme.css`/`theme.json`/`gutterpress.json`, a recognized bundled asset
+ * `theme.css`/`package.json`, a recognized bundled asset
  * (font/image/css), nor one the metadata itself declared (#241 —
  * `declaredExtras`: the extension's `markdown`/`components`/`snippets`
  * entries, when present, passed as relative paths; a `snippets` folder
@@ -59,8 +59,8 @@ export declare function unexpectedThemeFiles(relPaths: string[], declaredExtras?
 export declare function importExtensionFromZip(projectDir: string, archive: Uint8Array): Promise<ExtensionImportResult>;
 /**
  * Import a theme from a bare `.css` file by wrapping it into a one-file theme
- * folder (`theme.css` + a synthesized `theme.json` naming it). REJECTS a CSS
- * that fails to parse.
+ * folder (`theme.css` + a synthesized `package.json` naming it and declaring
+ * it). REJECTS a CSS that fails to parse.
  */
 export declare function importExtensionFromCssText(projectDir: string, css: string, name: string): Promise<ExtensionImportResult>;
 /**
@@ -73,7 +73,7 @@ export declare function importExtensionFromFile(projectDir: string, filePath: st
  * Import a look from a URL using the global `fetch` (bundle-safe — no node
  * http client). Two shapes: a `.css` URL is the look's `theme.css`, with
  * metadata synthesised from the URL; a base URL (no `.css`) fetches
- * `<base>/theme.json` (optional) and `<base>/theme.css` (required). Bundled
+ * `<base>/package.json` (optional) and `<base>/theme.css` (required). Bundled
  * fonts are not followed — authors wanting bundled assets use a folder or a
  * `.zip`. The fetched files go through the same validation as a `.zip`.
  */

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

@@ -29,10 +29,10 @@ export interface ProjectExtensionEntry {
     /** Preview image path relative to the extension folder, when declared. */
     preview?: string | null;
     /** The sheet carrying the `:root` token surface, relative to the folder,
-     *  when declared (`gutterpress.json`'s `tokensFile`). */
+     *  when declared (package.json's `gutterpress.tokensFile`). */
     tokensFile?: string;
-    /** Declared stylesheets relative to the folder, in cascade order (`theme.css`
-     *  by default for a metadata-less look). Absent when there is no folder. */
+    /** Declared stylesheets relative to the folder, in cascade order
+     *  (`gutterpress.styles`). Absent when the folder declares none. */
     styles?: string[];
     /** What the extension declares — the desktop shows styles-carrying entries
      *  in its Look view and markdown-carrying ones in Features; one list. */

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

@@ -1,92 +1,100 @@
-/** The unified package's metadata filename — checked before the legacy
- *  theme-only filename by {@link readExtensionMeta}. */
-export declare const EXTENSION_MANIFEST_FILENAME = "gutterpress.json";
-/** The pre-#241 theme-only metadata filename. Still fully supported: a folder
- *  with only this file (no `gutterpress.json`) is a theme, i.e. "an extension
- *  with only styles" — see {@link readExtensionMeta}. */
-export declare const LEGACY_THEME_MANIFEST_FILENAME = "theme.json";
+/** The one file an extension describes itself in — npm's own manifest. */
+export declare const EXTENSION_MANIFEST_FILENAME = "package.json";
 /**
- * Parsed extension metadata — a superset of the pre-#241 theme metadata
- * shape. Every field is optional, and a folder declaring only the theme-era
- * fields (`name`/`author`/`description`/`preview`/`styles`/`tokensFile`) IS
- * a valid extension: "theme ≡ extension with only styles."
- * Symmetrically, a bare `.js` plugin file (no metadata file at all) never
- * constructs one of these — "plugin ≡ extension with only markdown" needs no
- * metadata file until it wants more than a function (see `plugins.ts`'s
- * `loadExtensionFromDir`, which only reaches this type for a `path` that
- * names a folder).
+ * Parsed extension metadata — npm's standard fields plus the `gutterpress`
+ * block's, flattened into the one shape every consumer reads. Every field is
+ * optional: a folder declaring only `gutterpress.styles` IS a valid extension
+ * ("a look ≡ an extension with only styles"), and a package.json whose `main`
+ * is a plain markdown-it plugin with no `gutterpress` key at all is one too
+ * ("a plugin ≡ an extension with only markdown"). A bare `.js` plugin file
+ * (no package.json beside it) never constructs one of these — see
+ * `plugins.ts`'s `loadExtensionFromDir`, which only reaches this type for a
+ * `path` that names a folder.
  */
 export interface ExtensionMetadata {
+    /** npm `name`. */
     name?: string;
+    /** npm `author`, as a string or the object form's `name`. */
     author?: string;
+    /** npm `description`. */
     description?: string;
-    /** Optional preview image path (relative to the extension folder). */
+    /**
+     * npm `keywords` — informational. `gutterpress` marks a Gutterpress
+     * extension and `markdown-it-plugin` a markdown-it plugin, the two tags
+     * `gutterpress ext search` finds packages by; nothing here requires either.
+     */
+    keywords?: string[];
+    /**
+     * npm `main` — the markdown-it plugin module of a FOLDER extension, by
+     * npm's own convention. See {@link extensionEntry} for the entry rule
+     * (`gutterpress.markdown` wins when present). NOT used for an npm-installed
+     * package: the installer resolves that entry with full `exports` semantics
+     * (`npm-plugin-installer.ts`'s `resolvePackageEntry`), and it is never
+     * re-derived from `main` here.
+     */
+    main?: string;
+    /** `gutterpress.preview` — an optional preview image path, relative to the
+     *  extension folder. */
     preview?: string | null;
     /**
-     * Ordered stylesheets, relative to the extension folder. Absent/empty means
-     * "no styles declared" here — {@link extensionStyleList} does NOT default
-     * to `["theme.css"]`; that default is {@link extensionStyleListWithDefault}'s, layered on
-     * top for its theme-shaped callers (a plain markdown-only extension folder
-     * has no reason to require a `theme.css` it never declared).
+     * `gutterpress.styles` — ordered stylesheets, relative to the extension
+     * folder. Absent/empty means exactly "no styles declared": a look declares
+     * its sheets, it does not get an implicit `theme.css`.
      */
     styles?: string[];
-    /** Which declared sheet (a path from `styles`) carries the author-facing
-     *  `:root` token surface for the Design panel's guided editor. Purely
-     *  advisory — nothing in this module enforces or existence-checks it,
-     *  matching the pre-#241 theme behavior it generalizes. */
+    /** `gutterpress.tokensFile` — which declared sheet (a path from `styles`)
+     *  carries the author-facing `:root` token surface for the Design panel's
+     *  guided editor. Purely advisory — nothing in this module enforces or
+     *  existence-checks it. */
     tokensFile?: string;
     /**
-     * Markdown-it entry, relative to the extension folder — a path to a JS
-     * module exporting a plugin function exactly like a bare-file plugin
-     * (`export default function (md, options) { ... }`, optionally `metadata`/
-     * `css`/`styles`, #238). Absent means "no markdown behavior" — the
-     * degenerate case that makes a styles-only folder indistinguishable from a
-     * theme. CLAUDE.md §5 is unaffected: this field is DATA a loader resolves
-     * to a file, then loads through the exact same plain-markdown-it-plugin
-     * contract every other plugin module does — no new plugin API is
-     * introduced.
+     * `gutterpress.markdown` — an EXPLICIT markdown-it entry, relative to the
+     * extension folder, for the one case npm's `main` can't express: a package
+     * whose `main` is not the plugin. Absent is the normal case ({@link
+     * extensionEntry} falls back to `main`). CLAUDE.md §5 is unaffected: this
+     * field is DATA a loader resolves to a file, then loads through the exact
+     * same plain-markdown-it-plugin contract every other plugin module does —
+     * no new plugin API is introduced.
      */
     markdown?: string;
     /**
-     * Component catalog file, relative to the extension folder (the CSS
-     * architecture review's `components.yaml`, #242). Parsed for existence/
-     * containment only by this module — the catalog SCHEMA and the registry
-     * that reads it are #242's scope, not this one's.
+     * `gutterpress.components` — component catalog file, relative to the
+     * extension folder (the CSS architecture review's `components.yaml`, #242).
+     * Parsed for existence/containment only by this module.
      */
     components?: string;
     /**
-     * Snippets folder, relative to the extension folder, merged into the
-     * project's snippet picker under the extension's name (#240). Parsed for
-     * existence/containment only by this module — the merge itself is #240's
-     * scope, not this one's.
+     * `gutterpress.snippets` — snippets folder, relative to the extension
+     * folder, merged into the project's snippet picker under the extension's
+     * name. Parsed for existence/containment only by this module; `snippets.ts`
+     * does the merge.
      */
     snippets?: string;
+    /**
+     * The removed `engineStyles` field (#266), carried through from the
+     * `gutterpress` block ONLY so {@link assertExtensionContained} can reject it
+     * by name at a write boundary. Never read as a declaration.
+     */
+    engineStyles?: unknown;
 }
 /**
- * Read an extension folder's metadata: `gutterpress.json` when present,
- * otherwise the legacy `theme.json` — ONE reader for both filenames, which is
- * what makes "the theme verbs keep working on the extension format" true
- * everywhere a real on-disk extension/theme folder is read (project themes,
- * apply, import, revert). `gutterpress.json` wins outright when present (no
- * silent merge with a sibling `theme.json` — a package declares itself
- * through exactly one file), matching {@link readJsonMetaFile}'s tolerant
- * contract when that one file is missing or broken.
+ * Read an extension folder's `package.json`. Tolerant: a missing or
+ * unparseable file, or one that is not an object, reads as `{}` — one bad or
+ * absent manifest must never take down listing/reading every extension.
  */
 export declare function readExtensionMeta(dir: string): Promise<ExtensionMetadata>;
 /**
  * An extension's declared stylesheets, relative to its folder, in cascade
- * order. UNLIKE {@link extensionStyleListWithDefault} (which layers a
- * `["theme.css"]` default on top of this for its theme-shaped callers), an
- * absent/empty `styles` here means exactly "none declared" — a markdown-only
- * extension folder must not be forced to carry a `theme.css` it never wanted.
+ * order. Absent/empty `gutterpress.styles` means exactly "none declared".
  */
 export declare function extensionStyleList(meta: ExtensionMetadata): string[];
 /**
- * `styles`, with the theme-era default (#265): a folder that declares none
- * but holds a `theme.css` IS a one-sheet look — every theme published before
- * `styles` existed. A folder with neither still declares nothing.
+ * The markdown-it entry of a FOLDER extension: an explicit
+ * `gutterpress.markdown` when the package's `main` is not the plugin,
+ * otherwise npm's own `main`. `undefined` for a folder that carries no
+ * markdown behaviour at all (a look).
  */
-export declare function extensionStyleListWithDefault(meta: ExtensionMetadata, dir: string): string[];
+export declare function extensionEntry(meta: ExtensionMetadata): string | undefined;
 /** What an extension declares, by field — the desktop's one-list filter. */
 export interface ExtensionCarries {
     markdown: boolean;
@@ -94,7 +102,7 @@ export interface ExtensionCarries {
     snippets: boolean;
     components: boolean;
 }
-export declare function extensionCarries(meta: ExtensionMetadata, dir: string): ExtensionCarries;
+export declare function extensionCarries(meta: ExtensionMetadata): ExtensionCarries;
 /**
  * True when a declared relative path escapes its own folder (absolute, or a
  * `..` segment) — the traversal shape every containment check in this
@@ -116,39 +124,30 @@ export declare function pathEscapesFolder(rel: string): boolean;
  * extension is self-contained by contract (apply/install copies the whole
  * folder), and an imported/vendored package is untrusted input: a `../` or
  * absolute entry would make apply/load read a file from anywhere on disk.
- *
- * Generalizes the pre-#241 theme-only `assertThemeSheetsContained` (still
- * once exported under that name from the theme manager, now this
- * function) to the three new fields: a `gutterpress.json`-formatted theme
- * folder can declare `markdown`/`components`/`snippets` too, so the SAME
- * write-boundary guard must cover them, not just `styles`.
  * `tokensFile` is included even though it is advisory/unenforced elsewhere —
  * defense in depth against a future consumer reading it unchecked.
  *
- * A WRITE-BOUNDARY guard, not a read-path check (mirrors the theme-only
- * predecessor): callers invoke this before copying anything or wiring a
- * manifest, never from a plain listing/read path, so one hand-edited
- * metadata file cannot take down listing every extension. The removed
- * `engineStyles` field (#266) is rejected here for the same reason: the
- * error names the replacement, and it fires only where something would be
- * copied or wired, never while listing.
+ * A WRITE-BOUNDARY guard, not a read-path check: callers invoke this before
+ * copying anything or wiring a manifest, never from a plain listing/read
+ * path, so one hand-edited manifest cannot take down listing every extension.
+ * The removed `engineStyles` field (#266) is rejected here for the same
+ * reason: the error names the replacement, and it fires only where something
+ * would be copied or wired, never while listing.
  */
 export declare function assertExtensionContained(meta: ExtensionMetadata): void;
 /**
  * An extension's declared paths, resolved to absolute, existence-checked
  * filesystem paths — every list/single-path field goes through the SAME
- * {@link resolveDeclaredStyles} a plugin's `styles` export and a theme's
- * `styles` already resolve through, so a broken
- * declaration (a missing file) throws HERE, at load/apply time, instead of
- * failing silently deep in the render pipeline (or never, for `components`/
- * `snippets`, which nothing yet reads — #240/#242).
+ * {@link resolveDeclaredStyles} a plugin's `styles` export and a look's
+ * `styles` already resolve through, so a broken declaration (a missing file)
+ * throws HERE, at load/apply time, instead of failing silently deep in the
+ * render pipeline (or never, for `components`, which nothing yet reads).
  *
  * `tokensFile` is the one exception, kept as declared (relative, not
- * existence-checked) — it stays purely advisory, matching
- * `ThemeInfo.tokensFile`'s pre-#241 contract.
+ * existence-checked) — it stays purely advisory.
  */
 export interface ResolvedExtension {
-    /** Absolute path to the markdown-it entry module, when declared. */
+    /** Absolute path to the markdown-it entry module, when the folder has one. */
     markdown?: string;
     /** Absolute paths, in cascade order, when any are declared. */
     styles?: string[];
@@ -156,17 +155,22 @@ export interface ResolvedExtension {
     tokensFile?: string;
     /** Absolute path to the component catalog file, when declared (#242). */
     components?: string;
-    /** Absolute path to the snippets folder, when declared (#240). */
+    /** Absolute path to the snippets folder, when declared. */
     snippets?: string;
 }
 /**
  * Resolve every path {@link ExtensionMetadata} declares, relative to `dir`
  * (the extension's own folder). `subject` names the declaring thing for a
  * resolution error, e.g. `Plugin "my-extension"` — passed straight through to
- * `resolveDeclaredStyles`, so a broken `markdown`/`components`/`snippets`
- * entry throws the same "declares stylesheet ... but no file exists" shape a
- * broken `styles` entry always has (the wording says "stylesheet" for every
- * field — a small, accepted cost of resolving all of them through one
- * function rather than inventing per-field messages).
+ * `resolveDeclaredStyles`, so a broken entry throws the same "declares
+ * stylesheet ... but no file exists" shape a broken `styles` entry always has
+ * (the wording says "stylesheet" for every field — a small, accepted cost of
+ * resolving all of them through one function rather than inventing per-field
+ * messages).
+ *
+ * `markdown` resolves {@link extensionEntry} — the FOLDER rule. An
+ * npm-installed package's entry is whatever the installer resolved with full
+ * `exports` semantics, so `plugins.ts` calls this without `main` for that
+ * path; see its npm branch.
  */
 export declare function resolveExtension(dir: string, meta: ExtensionMetadata, subject: string): ResolvedExtension;

package/dist/lib/extension-scaffold.d.ts

@@ -34,7 +34,7 @@ export interface ScaffoldExtensionOptions {
 export interface ScaffoldExtensionResult {
     /** Absolute path of the created folder. */
     extensionDir: string;
-    /** Absolute path of its `gutterpress.json`. */
+    /** Absolute path of its `package.json`. */
     manifestPath: string;
     kind: ExtensionKind;
     /** Folder name / package name that was used. */

package/dist/lib/extension-search.d.ts

@@ -0,0 +1,46 @@
+/** Reject a response larger than this before parsing. */
+export declare const MAX_SEARCH_BYTES: number;
+/** What a match was found BY — the two conventions, in precedence order. */
+export declare const SEARCH_KEYWORDS: readonly ["gutterpress", "markdown-it-plugin"];
+export type ExtensionSearchKind = "gutterpress" | "markdown-it";
+/** One npm package a book could install. */
+export interface NpmExtensionMatch {
+    name: string;
+    version: string;
+    description?: string;
+    /** `gutterpress` when the package tags itself as an extension; otherwise a
+     *  plain markdown-it plugin found by the ecosystem keyword. */
+    kind: ExtensionSearchKind;
+    keywords: string[];
+    homepage?: string;
+    /** The package's page on the registry's website, when it published one. */
+    npmUrl?: string;
+    /** Last publish date, as the registry reported it. */
+    date?: string;
+}
+export interface NpmExtensionSearchResult {
+    matches: NpmExtensionMatch[];
+    /** What the registry said it had, summed over both keyword queries — the
+     *  "showing N of M" denominator, not a count of `matches`. */
+    total: number;
+}
+export interface SearchNpmExtensionsOptions {
+    /** Dependency injection for tests; production uses global fetch. */
+    fetch?: typeof globalThis.fetch;
+    /** How many matches to return, and the `size` of each registry query. */
+    limit?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Search npm for installable extensions.
+ *
+ * One request per keyword (`gutterpress`, then `markdown-it-plugin`), merged
+ * and de-duplicated by package name — a package carrying BOTH keywords is one
+ * row, reported as a Gutterpress extension. Ordering puts Gutterpress-tagged
+ * packages first (they are the ones built for this tool), then the registry's
+ * own relevance score.
+ *
+ * Throws a friendly, author-facing error on any failure (offline, timeout, bad
+ * HTTP status, oversize body, malformed JSON, or a shape that doesn't match).
+ */
+export declare function searchNpmExtensions(query: string, options?: SearchNpmExtensionsOptions): Promise<NpmExtensionSearchResult>;

package/dist/lib/host-policy.d.ts

@@ -16,13 +16,9 @@
 export interface AutoSnapshotPolicy {
     /** Master switch — automatic snapshots default ON. */
     autoSnapshot: boolean;
-    /** Minutes of quiet after the last edit before a snapshot fires. */
-    autoSnapshotMinutes: number;
 }
-/** Cadence bounds: never below 5 minutes (commit-per-keystroke guard), never
- * above a day (a longer value means the user effectively wants it off). */
-export declare const AUTO_SNAPSHOT_MIN_MINUTES = 5;
-export declare const AUTO_SNAPSHOT_MAX_MINUTES: number;
+/** Quiet period before a snapshot fires. Fixed (#274) — no longer a settings
+ * knob, so there is nothing left to clamp. */
 export declare const AUTO_SNAPSHOT_DEFAULT_MINUTES = 10;
 /** User-facing auto-sync policy (mirrors the desktop's settings group). */
 export interface AutoSyncPolicy {
@@ -32,10 +28,10 @@ export interface AutoSyncPolicy {
     autoSyncMinutes: number;
 }
 /**
- * Cadence bounds for the periodic safety sync. The floor (1 min) is lower than
- * the snapshot floor because a network round-trip is cheaper than a full tree
- * walk, and the transparent-sync plan targets ~2 min as the default cadence.
- * The ceiling matches the snapshot ceiling (one day = effectively paused).
+ * Cadence bounds for the periodic safety sync. The floor (1 min) is low
+ * because a network round-trip is cheaper than a full tree walk, and the
+ * transparent-sync plan targets ~2 min as the default cadence. The ceiling
+ * (one day) means "effectively paused" for an absurdly large configured value.
  */
 export declare const AUTO_SYNC_MIN_MINUTES = 1;
 export declare const AUTO_SYNC_MAX_MINUTES: number;
@@ -56,9 +52,11 @@ export declare const AUTO_SYNC_PUSH_INTERVAL_MINUTES = 15;
  * `null` when automatic snapshots are disabled. Pure — the testable core of
  * the trigger policy (the timer itself lives in the Electron main process).
  *
+ * The quiet period is fixed at `AUTO_SNAPSHOT_DEFAULT_MINUTES` (#274 — the
+ * minutes field this used to clamp was deleted from the settings schema, so
+ * there is nothing left to resolve here beyond the master switch).
  * Defensive about persisted settings: a missing policy means "defaults"
- * (enabled, 10 min); a non-finite/absurd minutes value falls back to the
- * default and is then clamped into [5, 1440].
+ * (enabled, 10 min).
  */
 export declare function autoSnapshotDelayMs(policy: Partial<AutoSnapshotPolicy> | undefined): number | null;
 /**

package/dist/lib/lint-runner.d.ts

@@ -2,21 +2,28 @@ export interface LintRunnerOptions {
     files?: string;
     manifest?: string;
     /**
-     * Pre-loaded, absolute plugin `styles` file paths (#262) — supplied by the
-     * build pipeline (`build-runner.ts`'s `runQualityGates`, via
-     * `loadBuildPlugins`) so this call does not load plugins a second time in
-     * the same build. `undefined` (the default — every standalone
-     * `gutterpress lint` invocation) makes this function load plugins itself,
-     * exactly as before, with the same degrade-and-report (warn-and-skip)
-     * behavior for a plugin that fails to load. An explicit `[]` from a caller
-     * that already knows there is nothing to add is honored as-is, not treated
-     * as "unset".
+     * Pre-loaded, absolute plugin `styles` file paths (#262). `undefined` (the
+     * default — every standalone `gutterpress lint` invocation, which is now
+     * this function's only production caller since #272 removed the build
+     * pipeline's own separate lint gate) makes this function load plugins
+     * itself, degrade-and-report (warn-and-skip) for a plugin that fails to
+     * load. An explicit `[]` or a pre-loaded list from a caller that already
+     * knows the resolved plugin styles for this manifest is honored as-is, not
+     * treated as "unset".
      */
     pluginStylePaths?: string[];
 }
 export interface LintRunnerResult {
     ok: boolean;
+    /** Count of `printsafe/no-risky-print-effects` findings across every linted file. */
     riskyCount: number;
+    /**
+     * Count of `printsafe/page-containment` findings across every linted file
+     * (#272). Kept separate from {@link riskyCount} rather than folded into it,
+     * so a consumer can tell the two finding kinds apart without re-parsing
+     * printed text.
+     */
+    containmentCount: number;
     filesLinted: number;
 }
 export declare function runLint(opts?: LintRunnerOptions): Promise<LintRunnerResult>;

package/dist/lib/npm-registry.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The npm registry Gutterpress talks to (#246) — ONE resolver for the two
+ * places that reach it: the installer (`npm-plugin-installer.ts`: metadata,
+ * tarballs, and the tarball-origin check) and extension search
+ * (`extension-search.ts`).
+ *
+ * `GUTTERPRESS_NPM_REGISTRY` points both at a private mirror, and is what the
+ * CLI's own tests serve a fake registry at. It is validated the same way every
+ * other author-supplied URL in this package is — http(s) only — because a
+ * `file:`/`data:` registry would turn "install a package" into "read an
+ * arbitrary path".
+ *
+ * Bundle-safe (CLAUDE.md §1/§3): pure string work over `process.env`, no deps.
+ */
+/** The public registry, used when nothing overrides it. */
+export declare const DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org";
+/**
+ * The configured registry's base URL, without a trailing slash (every caller
+ * builds `${registry}/<path>` and a doubled slash breaks path-sensitive
+ * mirrors). Throws on an override that is not an http(s) URL.
+ */
+export declare function npmRegistryUrl(): string;

package/dist/lib/source-provider.d.ts

@@ -239,4 +239,75 @@ export declare const AUTO_SNAPSHOT_MESSAGE = "Automatic snapshot";
  * folder has no version history.
  */
 export declare function restoreVersionWithBackup(options: RestoreVersionOptions): Promise<RestoreVersionResult>;
+/** The project's copies (git branches) and which one is currently open. */
+export interface LocalBranches {
+    /** Name of the branch HEAD points to, or `null` on a detached/unborn HEAD. */
+    current: string | null;
+    /**
+     * Every copy the project can switch to, sorted: local branches
+     * (`refs/heads/*`) plus copies that so far exist only on a remote.
+     */
+    branches: string[];
+    /**
+     * The subset of {@link branches} with no local ref yet. Switching to one of
+     * these creates the local copy from the remote and tracks it; the UI uses
+     * this only to say so before it happens.
+     */
+    remoteOnly: string[];
+}
+/** Inputs for {@link switchBranch}. */
+export interface SwitchBranchOptions {
+    projectDir: string;
+    /** Branch name to check out — local, or one that so far exists only on a remote. */
+    branch: string;
+    /** Identity recorded on the automatic pre-switch safety snapshot, if one is taken. */
+    authorName?: string;
+    authorEmail?: string;
+}
+/** Result of a successful {@link switchBranch}. */
+export interface SwitchBranchResult {
+    /** The branch now checked out (equals `options.branch`). */
+    current: string;
+    /**
+     * Absolute paths of every file the checkout added, removed, or changed the
+     * content of (a diff of the old HEAD's tree against the new branch's tree,
+     * computed before the checkout runs). The host uses this to drop crash-
+     * recovery drafts for these paths — see recovery.ts's header: a draft taken
+     * on the copy just left behind must never be offered over a DIFFERENT copy's
+     * version of the same file.
+     */
+    changedFiles: string[];
+}
+/** Snapshot message for the safety snapshot {@link switchBranch} takes before checking out, when the working tree has changes. */
+export declare const SWITCH_BRANCH_SNAPSHOT_MESSAGE = "Saved before switching copy";
+/**
+ * List the project's copies (git branches) and which one is open, for a
+ * `local-git-folder` project. Returns `null` for any other source type —
+ * there is nothing to switch between, and the caller (the Saving settings row)
+ * hides the whole control on `null` rather than showing an error.
+ *
+ * Copies that exist only on a remote are included: they are as real to the
+ * author as the local ones, and {@link switchBranch} creates the local branch
+ * on the way in.
+ */
+export declare function listLocalBranches(dir: string): Promise<LocalBranches | null>;
+/**
+ * Switch the project's working tree to another local copy (git branch).
+ *
+ * Safety, in order (see the issue's "what the switch has to take care of"):
+ *  1. If the working tree has uncommitted changes, snapshot them first (so
+ *     nothing the author typed is lost) and tolerate the expected
+ *     "no changes" rejection when it doesn't.
+ *  2. Check out the target branch WITHOUT `force` — isomorphic-git then
+ *     refuses (CheckoutConflictError) rather than silently overwriting a
+ *     working-tree file that moved after the snapshot above, which is
+ *     reported as a friendly error instead of a forced checkout.
+ *  3. Report every path the checkout touched so the host can drop stale
+ *     crash-recovery drafts for them (see {@link SwitchBranchResult}).
+ *
+ * Pause/resume of the auto-snapshot/auto-sync host timers around the
+ * checkout, and refreshing the open editor/file-tree/preview afterwards, are
+ * host (desktop) responsibilities — this function only does the git work.
+ */
+export declare function switchBranch(options: SwitchBranchOptions): Promise<SwitchBranchResult>;
 export {};

package/dist/lib/validation-exec.d.ts

@@ -26,6 +26,17 @@ export interface ValidationExecutionArgs {
      * "unset".
      */
     pluginStylePaths?: string[];
+    /**
+     * Disable the `source.stylelint` check (CSS print-safety) for this run
+     * only, without touching the manifest's `validate.source.stylelint`
+     * setting on disk (#272 — one CSS gate, not two). Set by the build
+     * pipeline's `runQualityGates` (build-runner.ts) from `--skip-lint` /
+     * `config.lint.enabled: false`, so that flag disables just the one check
+     * it always meant to gate rather than a whole separate lint pass. Every
+     * other caller (`gutterpress validate`/`preflight`/`audit`, the desktop
+     * Problems panel) leaves this unset and gets the manifest's own setting.
+     */
+    skipStylelint?: boolean;
 }
 export interface ValidationExecutionResult {
     config: ResolvedConfig;

package/dist/{lint-enasqbqx.js → lint-ejzmx14j.js}

@@ -1,21 +1,21 @@
 import {
   MANIFEST_FILENAMES,
   runLint
-} from "./cli-8pg731p5.js";
+} from "./cli-n0vgey6x.js";
 import {
   log
-} from "./cli-ypfvnhag.js";
+} from "./cli-2rswy18t.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-rh05byck.js";
-import"./cli-bx950tb4.js";
+} from "./cli-scqp638v.js";
+import"./cli-k8f9eb12.js";
 import"./cli-c41yr7he.js";
 import {
   EXIT_CODES
 } from "./cli-46ycxe6r.js";
-import"./cli-w692g6dx.js";
+import"./cli-4mtf9ajw.js";
 import"./cli-v5mp7a6q.js";
 import"./cli-37x76zdn.js";
 

package/dist/{new-r9c99wsn.js → new-g3q3h4s5.js}

@@ -7,23 +7,23 @@ import {
   TARGET_IDS,
   scaffoldExtension,
   scaffoldProject
-} from "./cli-8pg731p5.js";
+} from "./cli-n0vgey6x.js";
 import {
   resolveGhostscript
-} from "./cli-ypfvnhag.js";
+} from "./cli-2rswy18t.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-rh05byck.js";
-import"./cli-bx950tb4.js";
+} from "./cli-scqp638v.js";
+import"./cli-k8f9eb12.js";
 import {
   isToolAvailable
 } from "./cli-c41yr7he.js";
 import {
   EXIT_CODES
 } from "./cli-46ycxe6r.js";
-import"./cli-w692g6dx.js";
+import"./cli-4mtf9ajw.js";
 import"./cli-v5mp7a6q.js";
 import"./cli-37x76zdn.js";
 
@@ -163,7 +163,7 @@ async function runExtensionScaffold(kind, name, parentDir, args) {
       console.log(`        gutterpress ext add ./${result.slug} <book>`);
       console.log("");
       console.log("      (that lists the FOLDER under `extensions:` in the book's manifest —");
-      console.log("       not plugin.js — which is what makes Gutterpress read gutterpress.json");
+      console.log("       not plugin.js — which is what makes Gutterpress read package.json");
       console.log("       and pick up the stylesheet too.)");
     } else {
       console.log("Next: add it to a book —");

package/dist/package-97gm31sg.json

@@ -0,0 +1,10 @@
+{
+  "name": "clean-book",
+  "description": "A calm, classic book look: serif body, generous margins, restrained accents.",
+  "author": "gutterpress",
+  "keywords": ["gutterpress", "gutterpress-look"],
+  "gutterpress": {
+    "styles": ["theme.css"],
+    "preview": null
+  }
+}