gutterpress 0.10.8 → 0.10.9

package/dist/{index-9pbaznww.js → index-zwcv1njy.js}

@@ -593,7 +593,7 @@ import { fileURLToPath } from "node:url";
 var favicon_default = "./favicon-wkbm9cjn.ico";
 
 // src/assets/manifest.schema.json
-var manifest_schema_default = "./manifest.schema-1q35yxs9.json";
+var manifest_schema_default = "./manifest.schema-hsn8rsgr.json";
 
 // src/assets/preview/scripts/preview-interface.js
 var preview_interface_default = "./preview-interface-9rwz21yw.js";
@@ -638,7 +638,7 @@ var gutterpress_default = "./gutterpress-m98e2w2d.json";
 var package_default = "./package-rm9d2tht.json";
 
 // src/assets/extension-templates/plugin/README.md
-var README_default = "./README-mdq34cmb.md";
+var README_default = "./README-jntqyj1z.md";
 
 // src/assets/extension-templates/plugin/plugin.js.tpl
 var plugin_js_default = "./plugin.js-aszz0zgh.tpl";
@@ -656,13 +656,13 @@ var fixture_default = "./fixture-2qnyqgb5.md";
 var expected_default = "./expected-ycmacem8.html";
 
 // src/assets/extension-templates/plugin/test/plugin.test.js.tpl
-var plugin_test_js_default = "./plugin.test.js-mv0ghv5n.tpl";
+var plugin_test_js_default = "./plugin.test.js-npnfhyca.tpl";
 
 // src/assets/extension-templates/theme/gutterpress.json
 var gutterpress_default2 = "./gutterpress-x2ycdsb8.json";
 
 // src/assets/extension-templates/theme/README.md
-var README_default2 = "./README-aaqapam1.md";
+var README_default2 = "./README-6c7fda1s.md";
 
 // src/assets/extension-templates/theme/components.yaml
 var components_default = "./components-0mmswvvm.yaml";
@@ -692,19 +692,19 @@ var book_default = "./book-ted3tzrp.css";
 var theme_default = "./theme-j2bagrfx.css";
 
 // src/assets/themes/clean-book/theme.json
-var theme_default2 = "./theme-xt0hjb1b.json";
+var theme_default2 = "./theme-vktedy8q.json";
 
 // src/assets/themes/zine/theme.css
 var theme_default3 = "./theme-h5recz6c.css";
 
 // src/assets/themes/zine/theme.json
-var theme_default4 = "./theme-cd6efzjw.json";
+var theme_default4 = "./theme-etj4gxck.json";
 
 // src/assets/themes/technical-doc/theme.css
 var theme_default5 = "./theme-nn6d53zy.css";
 
 // src/assets/themes/technical-doc/theme.json
-var theme_default6 = "./theme-tqfypc1w.json";
+var theme_default6 = "./theme-s2rg7xe7.json";
 
 // src/lib/embedded-assets.ts
 var __libdir = dirname(fileURLToPath(import.meta.url));

package/dist/index.js

@@ -6,8 +6,10 @@ import {
   AUTO_SYNC_MAX_MINUTES,
   AUTO_SYNC_MIN_MINUTES,
   AUTO_SYNC_PUSH_INTERVAL_MINUTES,
+  BUILT_IN_STYLE_SET_IDS,
   BUILT_IN_TEMPLATE_IDS,
-  BUILT_IN_THEME_IDS,
+  BUNDLED_EXTENSIONS,
+  EXTENSIONS_DIR,
   EXTENSION_KINDS,
   EXTENSION_MANIFEST_FILENAME,
   FileTokenStore,
@@ -22,17 +24,15 @@ import {
   PRESETS,
   PRESET_IDS,
   PublishSelectionsStore,
-  RECOMMENDED_PLUGINS,
+  RECOMMENDED_EXTENSIONS,
   RESERVED_PREFIX,
   SNIPPETS_DIR,
   SYNC_SNAPSHOT_MESSAGE,
   TARGETS,
   TARGET_IDS,
-  THEMES_DIR,
-  addLocalPlugin,
-  addNpmPlugin,
+  addBuiltInStyleSet,
+  addExtension,
   adoptFolder,
-  applyTheme,
   assertExtensionContained,
   autoSnapshotDelayMs,
   autoSyncDelayMs,
@@ -44,41 +44,40 @@ import {
   connectPublishProvider,
   defaultConfigDir,
   deleteSnippet,
-  detectLegacyForkedTheme,
+  describeExtension,
   diagnoseProjectRemote,
   disconnectPublishCredential,
   escapeYamlScalar,
   executeAndReport,
   executeValidation,
-  extensionEngineStyleList,
+  extensionCarries,
   extensionStyleList,
+  extensionStyleListWithDefault,
   extractUrlCredential,
   extractVariables,
   forgeKindForHost,
   formatReport,
-  getActiveTheme,
   getCheckById,
   getChecks,
-  getPreviousTheme,
   getSystemDiagnostics,
   hasProjectManifest,
+  importExtensionFromFile,
+  importExtensionFromUrl,
   importTemplateFromFolder,
-  importThemeFromFile,
-  importThemeFromFolder,
-  importThemeFromUrl,
   inspectImage,
+  isBundledExtension,
   isGitInternalPath,
+  isPathSpecifier,
   isSshRemoteUrl,
   knownForgeTokenUrl,
+  listBuiltInStyleSets,
   listBuiltInTemplates,
-  listBuiltInThemes,
   listCustomTemplates,
   listGitHubBranches,
   listGitHubRepositories,
   listMergedSnippets,
-  listProjectPlugins,
+  listProjectExtensions,
   listProjectStyles,
-  listProjectThemes,
   listPublishAccounts,
   listPublishProviders,
   listRepoBooks,
@@ -87,6 +86,7 @@ import {
   loadManifestWithPath,
   log,
   openPath,
+  parseExtensionSpecifier,
   parseRemoteOrigin,
   pathEscapesFolder,
   pkceChallengeFromVerifier,
@@ -94,17 +94,17 @@ import {
   publishCredentialKey,
   publishProviderFor,
   publishTargetFor,
+  readExtensionCss,
   readExtensionMeta,
   readExtensionSnippet,
   readManifestFields,
   readPublishSettings,
   readSnippet,
-  readThemeCss,
-  removeProjectTheme,
+  removeExtension,
+  reorderExtensions,
   reportMissingTools,
   requireGoogleClientCredentials,
   resolveActiveStyles,
-  resolveBuiltInTheme,
   resolveCheckSelectors,
   resolveConfig,
   resolveExtension,
@@ -114,7 +114,6 @@ import {
   resolveGoogleClientSecret,
   resolvePublishFormat,
   resolvePublishRequest,
-  revertTheme,
   revokeGoogleCredential,
   ruleRemoteUrls,
   ruleRiskyProps,
@@ -123,14 +122,15 @@ import {
   runChecks,
   runLint,
   runPublish,
+  sameExtension,
   sanitizeCloneFolderName,
   saveProjectAsTemplate,
   saveSnippet,
   scaffoldExtension,
   scaffoldProject,
   setActiveStyles,
+  setExtensionEnabled,
   setManifestFields,
-  setPluginEnabled,
   setPublishProviderConfig,
   slugifyProjectName,
   splitOutPath,
@@ -138,16 +138,16 @@ import {
   substituteVariables,
   syncProject,
   testRemoteAccess,
-  validateProjectPlugins
-} from "./index-dfw8hn8q.js";
+  validateProjectExtensions
+} from "./index-mey5vraz.js";
 import {
   BUILD_DIAGNOSTIC_CODES
-} from "./index-rpt4vtby.js";
+} from "./index-dhgzkhs7.js";
 import {
   BuildError,
   DEFAULT_PRINT_OPTS,
   readyProbeExpr
-} from "./index-9pbaznww.js";
+} from "./index-zwcv1njy.js";
 import {
   AUTO_SNAPSHOT_MESSAGE,
   HISTORY_PAGE_LIMIT,
@@ -166,7 +166,7 @@ import {
 } from "./index-v5mp7a6q.js";
 import"./index-37x76zdn.js";
 export {
-  validateProjectPlugins,
+  validateProjectExtensions,
   testRemoteAccess,
   syncProject,
   substituteVariables,
@@ -174,14 +174,15 @@ export {
   splitOutPath,
   slugifyProjectName,
   setPublishProviderConfig,
-  setPluginEnabled,
   setManifestFields,
+  setExtensionEnabled,
   setActiveStyles,
   scaffoldProject,
   scaffoldExtension,
   saveSnippet,
   saveProjectAsTemplate,
   sanitizeCloneFolderName,
+  sameExtension,
   runPublish,
   runLint,
   runChecks,
@@ -190,7 +191,6 @@ export {
   ruleRiskyProps,
   ruleRemoteUrls,
   revokeGoogleCredential,
-  revertTheme,
   restoreVersionWithBackup,
   resolvePublishRequest,
   resolvePublishFormat,
@@ -202,20 +202,20 @@ export {
   resolveExtension,
   resolveConfig,
   resolveCheckSelectors,
-  resolveBuiltInTheme,
   resolveActiveStyles,
   requireGoogleClientCredentials,
   reportMissingTools,
   repoSubPath,
   repoRootForSource,
-  removeProjectTheme,
+  reorderExtensions,
+  removeExtension,
   readyProbeExpr,
-  readThemeCss,
   readSnippet,
   readPublishSettings,
   readManifestFields,
   readExtensionSnippet,
   readExtensionMeta,
+  readExtensionCss,
   publishTargetFor,
   publishProviderFor,
   publishCredentialKey,
@@ -224,6 +224,7 @@ export {
   pkceChallengeFromVerifier,
   pathEscapesFolder,
   parseRemoteOrigin,
+  parseExtensionSpecifier,
   openPath,
   log,
   loadManifestWithPath,
@@ -232,44 +233,43 @@ export {
   listRepoBooks,
   listPublishProviders,
   listPublishAccounts,
-  listProjectThemes,
   listProjectStyles,
-  listProjectPlugins,
+  listProjectExtensions,
   listMergedSnippets,
   listGitHubRepositories,
   listGitHubBranches,
   listCustomTemplates,
-  listBuiltInThemes,
   listBuiltInTemplates,
+  listBuiltInStyleSets,
   knownForgeTokenUrl,
   isSshRemoteUrl,
+  isPathSpecifier,
   isNoChangesError,
   isGitInternalPath,
+  isBundledExtension,
   inspectImage,
-  importThemeFromUrl,
-  importThemeFromFolder,
-  importThemeFromFile,
   importTemplateFromFolder,
+  importExtensionFromUrl,
+  importExtensionFromFile,
   hasProjectManifest,
   getSystemDiagnostics,
-  getPreviousTheme,
   getChecks,
   getCheckById,
-  getActiveTheme,
   formatReport,
   forgeKindForHost,
   findEnclosingRepoDir,
   extractVariables,
   extractUrlCredential,
+  extensionStyleListWithDefault,
   extensionStyleList,
-  extensionEngineStyleList,
+  extensionCarries,
   executeValidation,
   executeAndReport,
   escapeYamlScalar,
   disconnectPublishCredential,
   diagnoseProjectRemote,
   detectProjectSource,
-  detectLegacyForkedTheme,
+  describeExtension,
   deleteSnippet,
   defaultConfigDir,
   connectPublishProvider,
@@ -282,18 +282,16 @@ export {
   autoSyncDelayMs,
   autoSnapshotDelayMs,
   assertExtensionContained,
-  applyTheme,
   adoptFolder,
-  addNpmPlugin,
-  addLocalPlugin,
-  THEMES_DIR,
+  addExtension,
+  addBuiltInStyleSet,
   TARGET_IDS,
   TARGETS,
   SYNC_SNAPSHOT_MESSAGE,
   SNIPPETS_DIR,
   RESTORE_BACKUP_MESSAGE,
   RESERVED_PREFIX,
-  RECOMMENDED_PLUGINS,
+  RECOMMENDED_EXTENSIONS,
   PublishSelectionsStore,
   PRESET_IDS,
   PRESETS,
@@ -309,10 +307,12 @@ export {
   FileTokenStore,
   EXTENSION_MANIFEST_FILENAME,
   EXTENSION_KINDS,
+  EXTENSIONS_DIR,
   DEFAULT_PRINT_OPTS,
   BuildError,
-  BUILT_IN_THEME_IDS,
+  BUNDLED_EXTENSIONS,
   BUILT_IN_TEMPLATE_IDS,
+  BUILT_IN_STYLE_SET_IDS,
   BUILD_DIAGNOSTIC_CODES,
   AUTO_SYNC_PUSH_INTERVAL_MINUTES,
   AUTO_SYNC_MIN_MINUTES,

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

@@ -39,13 +39,6 @@ export interface BuildRunnerOptions {
      */
     keepBrowserAlive?: boolean;
     rawArgs: Record<string, unknown>;
-    /**
-     * CLI `--engine` override. The native engine is the only engine, so this is
-     * a deprecated no-op accepted for backward compatibility only: `"paged"`
-     * triggers a one-line warning (`manifest.ts`'s resolution) and the build
-     * proceeds natively regardless.
-     */
-    engine?: "paged" | "native";
     /**
      * Optional injected engine-Chromium factory for native builds
      * (`engine.ts`'s `buildNativePdf`). When omitted (the CLI's default), the

package/dist/lib/build-staging.d.ts

@@ -58,7 +58,43 @@ export declare function stageBookAssets(options: {
     cssAssets: AssetCopy[];
     /** Called once with the copy plan; throw here to abort before copying. */
     onPlan?: (plan: StagingPlan) => void;
+    /**
+     * Strip every relative `<a href>` from the staged book — for print
+     * artifacts only, where no relative target can be opened (see
+     * {@link dropRelativeLinkHrefs}). Off by default: `--format html` ships its
+     * images beside `book.html` and keeps every href.
+     */
+    dropRelativeLinks?: boolean;
 }): Promise<StagedAssets>;
+/**
+ * Can a PDF reader follow this href? Only an in-document `#fragment` (a GoTo
+ * destination) or a URL with a scheme other than `file:`. Everything else —
+ * a relative or absolute path, `file:`, and the shapes that name no asset to
+ * copy (empty, `?query`, `//host`) — Chromium resolves against the staged
+ * document's `file://` base URL, which is dead for every reader.
+ */
+export declare function isPrintResolvableHref(href: string): boolean;
+/**
+ * Remove the `href` of every `<a>` that {@link isPrintResolvableHref}
+ * rejects, keeping the element and its text. Print-production tooling
+ * (permanent, not a shim).
+ *
+ * The staged `book.html` is printed from a `file://` URL in a per-build temp
+ * dir (engine/compiler/build.ts navigates `pathToFileURL(input)`), and
+ * Chromium writes the ABSOLUTE resolved URL of every relative `href` into
+ * the PDF's link annotation: `file:///tmp/gutterpress-build-<random>/docs/
+ * constitution.md`. That leaks the build machine's layout, is dead for every
+ * reader, and makes two builds of the same sources differ in bytes (#263).
+ * A PDF has no files beside it, so NO relative target is openable from one —
+ * not a same-book chapter file, not even an image the build copied into the
+ * work dir. The href is therefore dropped rather than rewritten.
+ * `source.links.dangling` tells the author which links this affects before
+ * the build.
+ *
+ * Comments and raw-text / literal-content elements (a `<pre>` showing HTML)
+ * stay untouched — see {@link rewriteActiveHtml}.
+ */
+export declare function dropRelativeLinkHrefs(html: string): string;
 /**
  * Create a unique scratch directory under the OS temp dir. Used only for
  * PDF/X intermediates (`raw.pdf`, Ghostscript work files) — never for staging

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

@@ -41,13 +41,6 @@ export declare function parseFormat(raw: unknown, opts: {
 }): BuildFormat;
 /** Parse `--pdfx-flavor`, which is only valid alongside `--format pdfx`. */
 export declare function parsePdfxFlavor(raw: unknown, format: BuildFormat): PdfxFlavor | undefined;
-/**
- * Parse `--engine`, shared by `build` and `preview`. The native engine is the
- * only engine, so this flag is an accepted-but-ignored no-op: `--engine paged`
- * produces a one-line warning (`manifest.ts`'s resolution) and the build
- * proceeds natively regardless. `undefined` means "not passed".
- */
-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;
 /**

package/dist/lib/{theme-import.d.ts → extension-import.d.ts}

@@ -1,16 +1,16 @@
 import { type PrintSafeWarning } from "./printsafe.ts";
-import { type ThemeInfo } from "./theme-manager.ts";
+import { type ProjectExtensionEntry } from "./extension-manager.ts";
 /** Reject a raw archive larger than this before unzipping (zip-bomb surface). */
 export declare const MAX_THEME_ARCHIVE_BYTES: number;
 /** A non-fatal issue surfaced to the author after a successful import. */
-export interface ThemeImportWarning {
+export interface ExtensionImportWarning {
     code: "print-safety" | "no-theme-json" | "unnamed-theme" | "extra-files";
     message: string;
 }
-/** Outcome of a `.zip` / `.css` import: the imported theme + any warnings. */
-export interface ThemeImportResult {
-    theme: ThemeInfo;
-    warnings: ThemeImportWarning[];
+/** Outcome of a `.zip` / `.css` / URL import: the added entry + any warnings. */
+export interface ExtensionImportResult {
+    entry: ProjectExtensionEntry;
+    warnings: ExtensionImportWarning[];
 }
 /**
  * Is this zip entry name unsafe to extract? Rejects absolute paths (posix or
@@ -53,19 +53,28 @@ export declare function unexpectedThemeFiles(relPaths: string[], declaredExtras?
  * Import a theme from a `.zip` package. Unzips in memory (fflate), rejects
  * unsafe paths and over-cap archives, locates the theme root (at the archive
  * root or one folder down), extracts just that subtree to a temp folder, and
- * finalizes via {@link finalizeThemeImport}. Lands the theme in
+ * finalizes via {@link finalizeExtensionImport}. Lands the theme in
  * `themes/<uniqueId>/` (never overwrites an existing theme).
  */
-export declare function importThemeFromZip(projectDir: string, archive: Uint8Array): Promise<ThemeImportResult>;
+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.
  */
-export declare function importThemeFromCssText(projectDir: string, css: string, name: string): Promise<ThemeImportResult>;
+export declare function importExtensionFromCssText(projectDir: string, css: string, name: string): Promise<ExtensionImportResult>;
 /**
  * Import a theme from a local file path, dispatched by extension: `.zip` →
- * {@link importThemeFromZip}, `.css` → {@link importThemeFromCssText}. The
+ * {@link importExtensionFromZip}, `.css` → {@link importExtensionFromCssText}. The
  * desktop's host reads the path from a native file picker and calls this.
  */
-export declare function importThemeFromFile(projectDir: string, filePath: string): Promise<ThemeImportResult>;
+export declare function importExtensionFromFile(projectDir: string, filePath: string): Promise<ExtensionImportResult>;
+/**
+ * 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
+ * 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`.
+ */
+export declare function importExtensionFromUrl(projectDir: string, url: string): Promise<ExtensionImportResult>;

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

@@ -0,0 +1,170 @@
+import { type NpmPluginInstallOptions } from "./npm-plugin-installer.ts";
+import { type ExtensionCarries } from "./extension-manifest.ts";
+import type { ResolvedExtensionConfig } from "../schema/manifest.types.ts";
+/** Folder (relative to the project root) extensions this module COPIES land in
+ *  (built-in looks, zip/URL imports). Path entries elsewhere are never moved. */
+export declare const EXTENSIONS_DIR = "extensions";
+/** The vendored npm tree stays where 0.10.8 put it. */
+export { PLUGINS_DIR } from "./plugin-vendor.ts";
+/** How an `extensions:` entry resolves — the form of its specifier decides. */
+export type ExtensionSourceKind = "bundled" | "path" | "npm";
+/** One configured extension, as surfaced to the CLI and the desktop. */
+export interface ProjectExtensionEntry {
+    /** The specifier exactly as written in the manifest — the stable ref every
+     *  other call takes (`setExtensionEnabled`, `removeExtension`, …). */
+    use: string;
+    kind: ExtensionSourceKind;
+    /** Package name (bundled, npm) or the path specifier (path). */
+    name: string;
+    /** Exact pinned version, from the specifier, for an npm entry. */
+    version?: string;
+    /** Named module export selected as the plugin function. */
+    export?: string;
+    /** Per-project enable flag. Absent in the manifest defaults to `true`. */
+    enabled: boolean;
+    /** Display name: the metadata's `name`, else the package name / folder name. */
+    label: string;
+    description?: string;
+    author?: string;
+    /** 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`). */
+    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. */
+    styles?: string[];
+    /** What the extension declares — the desktop shows styles-carrying entries
+     *  in its Look view and markdown-carrying ones in Features; one list. */
+    carries: ExtensionCarries;
+    /** Absolute folder its metadata was read from. Absent for a bundled name,
+     *  a bare JS file, an uninstalled npm entry, or a missing path. */
+    dir?: string;
+    /** Non-fatal notices: not installed, not found, unparseable specifier, … */
+    warnings?: string[];
+}
+/** Result of attempting to load one configured extension. */
+export interface ExtensionValidationResult {
+    use: string;
+    kind: ExtensionSourceKind;
+    /** Mirrors the manifest enable flag. Disabled extensions are not load-tested. */
+    enabled: boolean;
+    /** `true` when the extension loaded OK (or is disabled and skipped). */
+    ok: boolean;
+    /** The loader's fail-fast error message when `ok` is `false`. */
+    error?: string;
+}
+/** A curated, bundled markdown feature an author can turn on. */
+export interface RecommendedExtension {
+    /** The bundled name — also the manifest entry "Add" writes. */
+    use: string;
+    /** Short, plain-language feature name shown as the row title. */
+    label: string;
+    /** One-line author-friendly description. */
+    description: string;
+}
+/**
+ * The bundled markdown features (`BUNDLED_EXTENSIONS`): adding one writes the
+ * manifest entry AND the feature works immediately — no terminal, no install,
+ * offline. The always-on defaults (attrs/footnote/deflist, applied
+ * unconditionally in renderer.ts) are deliberately NOT listed: recommending
+ * the author "add" something already active is pure confusion.
+ */
+export declare const RECOMMENDED_EXTENSIONS: RecommendedExtension[];
+/** The built-in looks shipped as embedded assets (ids are folder names). */
+export declare const BUILT_IN_STYLE_SET_IDS: readonly ["clean-book", "zine", "technical-doc"];
+export type BuiltInStyleSetId = (typeof BUILT_IN_STYLE_SET_IDS)[number];
+/** A built-in look, as listed for the desktop's Look view. */
+export interface BuiltInStyleSet {
+    id: BuiltInStyleSetId;
+    name: string;
+    description: string;
+}
+/**
+ * Two specifiers name the same extension when they are equal, or when both
+ * are npm specifiers for the same package (a re-install re-pins the version
+ * in place instead of adding a second entry).
+ */
+export declare function sameExtension(a: string, b: string): boolean;
+/**
+ * List the project's configured extensions, in manifest (= cascade) order,
+ * each described from its metadata. Returns `[]` when there is no manifest
+ * or no `extensions:` list. Tolerant: a missing folder, an uninstalled npm
+ * entry, or an unparseable specifier is reported in `warnings`, never thrown
+ * — one bad entry must not blank the list for every other one.
+ */
+export declare function listProjectExtensions(projectDir: string): Promise<ProjectExtensionEntry[]>;
+/** One configured extension by specifier, or `null`. */
+export declare function describeExtension(projectDir: string, use: string): Promise<ProjectExtensionEntry | null>;
+/** The loader config for a listed entry — what `validate` and `add` load-test. */
+export declare function extensionConfigFor(entry: {
+    use: string;
+    kind: ExtensionSourceKind;
+    name: string;
+    version?: string;
+    export?: string;
+}): ResolvedExtensionConfig;
+/**
+ * Set the per-project enabled flag for the extension `use` names. A bare
+ * string entry becomes the object form to carry `enabled: false`; re-enabling
+ * drops the flag and collapses an object with nothing else left back to the
+ * bare string. Persists to the manifest (preserving comments). Throws when no
+ * entry matches.
+ */
+export declare function setExtensionEnabled(projectDir: string, use: string, enabled: boolean): Promise<void>;
+/**
+ * Rewrite the list in the given order — the author's cascade. `order` must
+ * name every current entry exactly once (by its `use`); anything else is a
+ * stale view and is refused rather than guessed at.
+ */
+export declare function reorderExtensions(projectDir: string, order: string[]): Promise<void>;
+/**
+ * Remove an extension's manifest entry. An npm entry's vendored tree is
+ * deleted too (it is Gutterpress's own private copy); a path entry's folder
+ * is the author's and is never touched. Throws when no entry matches.
+ */
+export declare function removeExtension(projectDir: string, use: string): Promise<void>;
+export interface AddExtensionOptions extends NpmPluginInstallOptions {
+    /** Named module export to use as the plugin function (npm and path only). */
+    exportName?: string;
+    /** @internal fault injection for the installer tests. */
+    __testFailBeforeManifestCommit?: () => void | Promise<void>;
+}
+/**
+ * Add an extension to the project, one way whatever it is:
+ *
+ *   - a bundled name is written as-is;
+ *   - a path (`./x`, `../x`, or absolute) is load-tested and written relative
+ *     to the project, referenced in place;
+ *   - an npm specifier (`name`, `name@version`) is downloaded, verified,
+ *     vendored with a receipt, load-tested, and written back as
+ *     `name@<exact version>`. On any failure the vendor tree is rolled back.
+ *
+ * Idempotent: adding what is already listed re-pins/updates that entry.
+ * Returns the described entry.
+ */
+export declare function addExtension(projectDir: string, specifier: string, options?: AddExtensionOptions): Promise<ProjectExtensionEntry>;
+/** List the built-in looks (metadata read from the embedded assets). */
+export declare function listBuiltInStyleSets(): Promise<BuiltInStyleSet[]>;
+/** A folder name under `extensions/` not yet taken: `<slug>`, `<slug>-2`, … */
+export declare function uniqueExtensionId(projectDir: string, base: string): Promise<string>;
+/**
+ * Copy a built-in look into `extensions/<id>/` and add it to the manifest as
+ * `./extensions/<id>`. The copy is deliberate (see the module doc): the look
+ * becomes the author's own editable files. Idempotent — a folder already
+ * there is kept as it is and only (re-)referenced.
+ */
+export declare function addBuiltInStyleSet(projectDir: string, id: string): Promise<ProjectExtensionEntry>;
+/**
+ * Validate every configured extension by attempting to LOAD it through the
+ * one loader. Disabled entries are reported as disabled and NOT load-tested.
+ * Loader errors are caught and surfaced per entry (never thrown through) so
+ * the desktop can flag an erroring extension with its fix instructions.
+ */
+export declare function validateProjectExtensions(projectDir: string): Promise<ExtensionValidationResult[]>;
+/**
+ * Read an extension's stylesheets, concatenated in cascade order, for a
+ * preview thumbnail (the renderer never touches fs). Read-only, so
+ * concatenation is fine even though it would not be for an editable surface.
+ */
+export declare function readExtensionCss(projectDir: string, use: string): Promise<string>;