gutterpress 0.10.9 → 0.10.10-alpha.1

package/dist/{index-dtrftayr.js → index-f833dtg9.js}

@@ -508,5 +508,92 @@ async function restoreVersionWithBackup(options) {
     return { restoredId: id, backupId };
   });
 }
+var SWITCH_BRANCH_SNAPSHOT_MESSAGE = "Saved before switching copy";
+async function listLocalBranches(dir) {
+  const source = await detectProjectSource(dir);
+  if (source.type !== "local-git-folder")
+    return null;
+  const repoDir = gitScopeFor(source);
+  const [branches, current] = await Promise.all([
+    git.listBranches({ fs: gitFs, dir: repoDir }),
+    git.currentBranch({ fs: gitFs, dir: repoDir, fullname: false }).catch(() => {
+      return;
+    })
+  ]);
+  return { current: current ?? null, branches };
+}
+function isCheckoutConflictError(e) {
+  return e?.code === "CheckoutConflictError";
+}
+async function diffCommitPaths(dir, fromOid, toOid, cache) {
+  const changed = [];
+  await git.walk({
+    fs: gitFs,
+    dir,
+    cache,
+    trees: [git.TREE({ ref: fromOid }), git.TREE({ ref: toOid })],
+    map: async (filepath, [from, to]) => {
+      if (filepath === ".")
+        return;
+      const [fType, tType] = await Promise.all([
+        from ? from.type() : Promise.resolve(undefined),
+        to ? to.type() : Promise.resolve(undefined)
+      ]);
+      if (fType === "tree" || tType === "tree")
+        return;
+      if (!fType && !tType)
+        return;
+      if (!fType || !tType) {
+        changed.push(filepath);
+        return;
+      }
+      const [fOid, tOid] = await Promise.all([from.oid(), to.oid()]);
+      if (fOid !== tOid)
+        changed.push(filepath);
+    }
+  });
+  return changed;
+}
+async function switchBranch(options) {
+  const { projectDir, branch, authorName, authorEmail } = options;
+  const source = await detectProjectSource(projectDir);
+  if (source.type !== "local-git-folder") {
+    throw new Error("This project has no version history yet. Enable version history first.");
+  }
+  const repoDir = gitScopeFor(source);
+  return withRepoLock(repoDir, async () => {
+    const cache = {};
+    try {
+      await snapshotWorkingTreeUnlocked({
+        projectDir,
+        repoRoot: repoDir,
+        message: SWITCH_BRANCH_SNAPSHOT_MESSAGE,
+        authorName,
+        authorEmail,
+        cache
+      });
+    } catch (e) {
+      if (!isNoChangesError(e))
+        throw e;
+    }
+    const fromOid = await git.resolveRef({ fs: gitFs, dir: repoDir, ref: "HEAD" }).catch(() => {
+      return;
+    });
+    const toOid = await git.resolveRef({ fs: gitFs, dir: repoDir, ref: branch });
+    try {
+      await git.checkout({ fs: gitFs, dir: repoDir, cache, ref: branch, force: false });
+    } catch (e) {
+      if (isCheckoutConflictError(e)) {
+        throw new Error("Couldn't switch copies — some files changed on disk right as the switch " + "started. Try again.", { cause: e });
+      }
+      throw e;
+    }
+    const changedPaths = fromOid && fromOid !== toOid ? await diffCommitPaths(repoDir, fromOid, toOid, cache) : [];
+    return {
+      current: branch,
+      changedFiles: changedPaths.map((p) => path2.join(repoDir, p))
+    };
+  });
+}
 
-export { gitFs, resolveLogger, gitScopeFor, HISTORY_PAGE_LIMIT, withRepoLock, __repoLockQueueSizeForTests, resolveGitAuthor, listWorkdirChanges, stageChanges, hasPendingChanges, hasUncommittedChanges, snapshotWorkingTreeUnlocked, isNoChangesError, providerFor, gitDirFor, snapshotStagingMarkerPath, RESTORE_BACKUP_MESSAGE, AUTO_SNAPSHOT_MESSAGE, restoreVersionWithBackup };
+export { gitFs, resolveLogger, gitScopeFor, HISTORY_PAGE_LIMIT, withRepoLock, __repoLockQueueSizeForTests, resolveGitAuthor, listWorkdirChanges, stageChanges, hasPendingChanges, hasUncommittedChanges, snapshotWorkingTreeUnlocked, isNoChangesError, providerFor, gitDirFor, snapshotStagingMarkerPath, RESTORE_BACKUP_MESSAGE, AUTO_SNAPSHOT_MESSAGE, restoreVersionWithBackup, SWITCH_BRANCH_SNAPSHOT_MESSAGE, listLocalBranches, switchBranch };

package/dist/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,
@@ -51,8 +51,8 @@ import {
   executeAndReport,
   executeValidation,
   extensionCarries,
+  extensionEntry,
   extensionStyleList,
-  extensionStyleListWithDefault,
   extractUrlCredential,
   extractVariables,
   forgeKindForHost,
@@ -84,7 +84,9 @@ import {
   listSnippets,
   loadManifest,
   loadManifestWithPath,
+  loadPluginsWithCss,
   log,
+  npmRegistryUrl,
   openPath,
   parseExtensionSpecifier,
   parseRemoteOrigin,
@@ -115,12 +117,12 @@ import {
   resolvePublishFormat,
   resolvePublishRequest,
   revokeGoogleCredential,
+  rulePageContainment,
   ruleRemoteUrls,
   ruleRiskyProps,
   ruleSyntax,
   runBuild,
   runChecks,
-  runLint,
   runPublish,
   sameExtension,
   sanitizeCloneFolderName,
@@ -128,6 +130,7 @@ import {
   saveSnippet,
   scaffoldExtension,
   scaffoldProject,
+  searchNpmExtensions,
   setActiveStyles,
   setExtensionEnabled,
   setManifestFields,
@@ -139,24 +142,27 @@ import {
   syncProject,
   testRemoteAccess,
   validateProjectExtensions
-} from "./index-mey5vraz.js";
+} from "./index-d4wrww4b.js";
 import {
   BUILD_DIAGNOSTIC_CODES
-} from "./index-dhgzkhs7.js";
+} from "./index-a0e2253t.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,
@@ -164,11 +170,88 @@ import {
   repoRootForSource,
   repoSubPath
 } from "./index-v5mp7a6q.js";
-import"./index-37x76zdn.js";
+import {
+  __require
+} from "./index-37x76zdn.js";
+// src/lib/lint-runner.ts
+import { resolve } from "node:path";
+import { readFile } from "node:fs/promises";
+async function runLint(opts = {}) {
+  const { glob } = await import("glob");
+  const { manifest, manifestDir } = await loadManifestWithPath(opts.manifest, {
+    explicit: opts.manifest !== undefined
+  });
+  const resolved = resolveConfig({}, manifest);
+  let files;
+  if (opts.files) {
+    files = await glob([opts.files], { nodir: true, ignore: ["**/*.min.css"] });
+  } else {
+    const relStyles = await resolveActiveStyles(manifestDir, resolved.styles);
+    const projectFiles = relStyles.map((rel) => resolve(manifestDir, rel));
+    let pluginStylePaths = opts.pluginStylePaths;
+    if (pluginStylePaths === undefined) {
+      ({ pluginStylePaths } = await loadPluginsWithCss(resolved.extensions, manifestDir, (ref, err) => log.warn(`Skipping plugin "${ref}" for lint — ${err.message}`)));
+    }
+    files = [...projectFiles, ...pluginStylePaths].filter((f) => !f.endsWith(".min.css"));
+  }
+  if (files.length === 0) {
+    log.warn("No CSS files found to lint");
+    return { ok: true, riskyCount: 0, containmentCount: 0, filesLinted: 0 };
+  }
+  log.info(`Linting ${files.length} CSS file(s)`);
+  let errorCount = 0;
+  let riskyCount = 0;
+  let containmentCount = 0;
+  let linted = 0;
+  for (const file of files) {
+    let css;
+    try {
+      css = await readFile(file, "utf8");
+    } catch (err) {
+      log.error(`  ${file}`);
+      log.error(`    cannot read stylesheet: ${err instanceof Error ? err.message : String(err)}`);
+      errorCount++;
+      continue;
+    }
+    linted++;
+    const warnings = checkCss(css, file);
+    const errors = warnings.filter((w) => w.severity === "error");
+    const risky = warnings.filter((w) => w.rule === ruleRiskyProps);
+    const containment = warnings.filter((w) => w.rule === rulePageContainment);
+    riskyCount += risky.length;
+    containmentCount += containment.length;
+    if (errors.length > 0) {
+      log.error(`  ${file}`);
+      for (const w of errors) {
+        log.error(`    ${w.line}:${w.column}  ${w.message}  (${w.rule})`);
+      }
+      errorCount += errors.length;
+    }
+    const nonErrorWarnings = [...risky, ...containment].sort((a, b) => a.line - b.line);
+    if (nonErrorWarnings.length > 0) {
+      log.warn(`  ${file}`);
+      for (const w of nonErrorWarnings) {
+        log.warn(`    ${w.line}:${w.column}  ${w.message}  (${w.rule})`);
+      }
+    }
+  }
+  if (errorCount > 0) {
+    log.error("CSS lint errors found");
+    return { ok: false, riskyCount, containmentCount, filesLinted: linted };
+  }
+  const totalWarnings = riskyCount + containmentCount;
+  if (totalWarnings > 0) {
+    log.warn(`${totalWarnings} print-safety warning(s): ${riskyCount} risky effect(s), ${containmentCount} page-containment`);
+  } else {
+    log.success("CSS lint passed");
+  }
+  return { ok: true, riskyCount, containmentCount, filesLinted: linted };
+}
 export {
   validateProjectExtensions,
   testRemoteAccess,
   syncProject,
+  switchBranch,
   substituteVariables,
   startPreviewServer,
   splitOutPath,
@@ -177,6 +260,7 @@ export {
   setManifestFields,
   setExtensionEnabled,
   setActiveStyles,
+  searchNpmExtensions,
   scaffoldProject,
   scaffoldExtension,
   saveSnippet,
@@ -226,6 +310,7 @@ export {
   parseRemoteOrigin,
   parseExtensionSpecifier,
   openPath,
+  npmRegistryUrl,
   log,
   loadManifestWithPath,
   loadManifest,
@@ -236,6 +321,7 @@ export {
   listProjectStyles,
   listProjectExtensions,
   listMergedSnippets,
+  listLocalBranches,
   listGitHubRepositories,
   listGitHubBranches,
   listCustomTemplates,
@@ -260,8 +346,8 @@ export {
   findEnclosingRepoDir,
   extractVariables,
   extractUrlCredential,
-  extensionStyleListWithDefault,
   extensionStyleList,
+  extensionEntry,
   extensionCarries,
   executeValidation,
   executeAndReport,
@@ -288,7 +374,9 @@ export {
   TARGET_IDS,
   TARGETS,
   SYNC_SNAPSHOT_MESSAGE,
+  SWITCH_BRANCH_SNAPSHOT_MESSAGE,
   SNIPPETS_DIR,
+  SEARCH_KEYWORDS,
   RESTORE_BACKUP_MESSAGE,
   RESERVED_PREFIX,
   RECOMMENDED_EXTENSIONS,
@@ -296,8 +384,8 @@ export {
   PRESET_IDS,
   PRESETS,
   PLUGINS_DIR,
+  MAX_SEARCH_BYTES,
   MANIFEST_FILENAMES,
-  LEGACY_THEME_MANIFEST_FILENAME,
   HISTORY_PAGE_LIMIT,
   GoogleAuthProvider,
   GitHubAuthProvider,
@@ -309,6 +397,7 @@ export {
   EXTENSION_KINDS,
   EXTENSIONS_DIR,
   DEFAULT_PRINT_OPTS,
+  DEFAULT_NPM_REGISTRY,
   BuildError,
   BUNDLED_EXTENSIONS,
   BUILT_IN_TEMPLATE_IDS,
@@ -318,8 +407,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/lib/build-error.d.ts

@@ -9,11 +9,12 @@
  *                  failures (validate/preflight/audit findings, a build's
  *                  quality-gate rejection). The invocation itself was fine;
  *                  the content wasn't. Standalone `gutterpress lint` uses this
- *                  code for CSS lint failures too, but the `build` pipeline's
- *                  own CSS-lint gate is a documented historical exception
- *                  that exits 2 instead (see build-runner.ts's
- *                  runQualityGates) — not a bug, just an inconsistency kept
- *                  for back-compat.
+ *                  code for CSS lint failures too. `gutterpress build`'s CSS
+ *                  print-safety check (`source.stylelint`) now runs as one
+ *                  of pre-build validation's checks (#272 — one CSS gate,
+ *                  not two) and fails the build through this same code; the
+ *                  `build` pipeline's former separate CSS-lint gate, and its
+ *                  own exit code 2, are gone.
  *   2  USAGE     — the invocation itself was wrong: a bad flag, positional,
  *                  preset, or value. See {@link UsageError} in ./cli-args.ts.
  *   3  PIPELINE  — the build/render/export pipeline failed for a reason

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

@@ -58,7 +58,17 @@ export declare function preflightBuildTools(format: BuildFormat, opts: {
  */
 export declare function verifyNativeChromiumMilestone(): Promise<void>;
 export interface Gates {
-    lint: boolean;
+    /**
+     * Disable the `source.stylelint` check (CSS print-safety: remote urls,
+     * risky print effects, page-containment) for this run, without touching
+     * `preValidate` itself (#272 — one CSS gate, not two: this used to be a
+     * whole second gate, `runLint`, that duplicated `source.stylelint`'s own
+     * `checkCss` pass one phase later). `true` when `--skip-lint` was passed or
+     * `config.lint.enabled === false`; consulted only when `preValidate` is
+     * also true — with `preValidate` off, no pre-build check (CSS included)
+     * runs at all, `--skip-lint` or not.
+     */
+    skipStylelint: boolean;
     preValidate: boolean;
     postValidate: boolean;
 }

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

@@ -20,6 +20,14 @@ export interface BuildRunnerOptions {
     iccPath?: string;
     manifestPath?: string;
     stripAnnotations?: boolean;
+    /**
+     * Skip the CSS print-safety check (#272 — one CSS gate, not two). This used
+     * to gate a separate `runLint` pass; it now disables just the
+     * `source.stylelint` check inside pre-build validation (see
+     * {@link computeGates}'s `skipStylelint`). Has no effect when
+     * `skipPreValidate` is also set — pre-build validation, CSS check
+     * included, does not run at all in that case.
+     */
     skipLint?: boolean;
     skipPreValidate?: boolean;
     skipPostValidate?: boolean;
@@ -54,10 +62,12 @@ export interface BuildRunnerOptions {
 export interface BuildRunnerResult {
     outDir: string;
     /**
-     * The published `book.html`, or `null` for a one-file delivery (`--out x.pdf`,
-     * a desktop export) where only the PDF is delivered and everything else is
-     * discarded with the work dir. Returning a work-dir path here would hand the
-     * caller a filename that is already deleted by the time they see it.
+     * The published `book.html`, or `null` when only the PDF is delivered and
+     * everything else is discarded with the work dir — a one-file delivery
+     * (`--out x.pdf`, a desktop export), or a `pdf`/`pdfx` build into a
+     * `--out <dir>` (#270, #271; see {@link PublishTarget}'s `directory` case).
+     * Returning a work-dir path here would hand the caller a filename that is
+     * already deleted by the time they see it.
      */
     htmlPath: string | null;
     pdfPath: string | null;
@@ -102,7 +112,15 @@ type PublishTarget =
     kind: "project";
     dir: string;
 }
-/** `--out <dir>`: the user's directory. Files are added; nothing is removed. */
+/**
+ * `--out <dir>`: the user's directory. Files are added; nothing is removed.
+ * An `html` build delivers its whole bundle (book.html + viewer, index.html,
+ * assets, fingerprint) here. A `pdf`/`pdfx` build delivers ONLY its own PDF
+ * — never book.html/index.html/assets — so building both formats into one
+ * shared directory (the documented `--out ./_site` sequence) cannot let the
+ * pdf build's staged, viewer-less, link-stripped `book.html` clobber the
+ * html build's published one (#270, #271).
+ */
  | {
     kind: "directory";
     dir: string;
@@ -161,10 +179,10 @@ export interface BuildContext {
     prevalidatedLayoutWarningKeys: Set<string>;
     /**
      * The build's ONE plugin load (#262). `null` until {@link loadBuildPlugins}
-     * runs; every stage that needs plugins (the lint gate and preValidate gate
-     * in {@link runQualityGates}, and {@link renderBook}) calls that function
-     * and gets the SAME resolved `{ plugins, pluginCss, pluginStylePaths }`
-     * back, whichever of them runs first.
+     * runs; every stage that needs plugins (the preValidate gate in
+     * {@link runQualityGates}, and {@link renderBook}) calls that function and
+     * gets the SAME resolved `{ plugins, pluginCss, pluginStylePaths }` back,
+     * whichever of them runs first.
      *
      * Before this, `runQualityGates`'s lint gate and `renderBook` each called
      * `loadPluginsWithCss` independently for the identical manifest. For an
@@ -192,13 +210,13 @@ export interface BuildContext {
 export declare function resolveBuildContext(opts: BuildRunnerOptions): Promise<BuildContext>;
 /**
  * Load every plugin the manifest configures, exactly once for the whole
- * build (#262). Memoized on `ctx.plugins`: the lint gate, the preValidate
- * gate (both in {@link runQualityGates}), and {@link renderBook} each call
- * this instead of `loadPluginsWithCss` directly, and only the first caller
- * does real work — the rest get the cached result back, however the gates
- * are configured and whichever stage happens to run first (a test calling
- * {@link renderBook} directly, without going through `runQualityGates`, gets
- * a fresh load here exactly as it would have before this existed).
+ * build (#262). Memoized on `ctx.plugins`: the preValidate gate (in
+ * {@link runQualityGates}) and {@link renderBook} each call this instead of
+ * `loadPluginsWithCss` directly, and only the first caller does real work —
+ * the other gets the cached result back, whichever stage happens to run
+ * first (a test calling {@link renderBook} directly, without going through
+ * `runQualityGates`, gets a fresh load here exactly as it would have before
+ * this existed).
  *
  * Fail-fast (no `onError`), matching `renderBook`'s pre-existing behavior:
  * a build/export must never silently omit author-configured formatting (see
@@ -241,6 +259,21 @@ export declare function renderBook(ctx: BuildContext): Promise<string>;
  * copy shipped in the binary. Throws BuildError(exitCode 2) if nothing resolves.
  */
 export declare function resolveIccProfile(icc: string, manifestDir: string, explicitIccPath: string | undefined): Promise<string>;
+/**
+ * Publish a completed work dir into a `--out <dir>` target: the pure copy
+ * decision behind {@link PublishTarget}'s `directory` case, pulled out of
+ * {@link publishBuild} so it is unit-testable without a full
+ * {@link BuildContext}.
+ *
+ * `html` delivers the whole bundle (book.html + viewer, index.html, assets,
+ * fingerprint) — files are added, never removed. `pdf`/`pdfx` delivers ONLY
+ * its own PDF: its staged `book.html` has no viewer script
+ * (`HtmlOutput.finish` never runs for these formats) and, since #263, no
+ * relative hrefs either, so copying the whole work dir would silently
+ * clobber an html build's published book.html/index.html/assets in the same
+ * `--out` directory (#270, #271).
+ */
+export declare function publishToDirectory(workDir: string, targetDir: string, format: BuildFormat, artifactName: string | null): Promise<void>;
 /**
  * Orchestrate a build: resolve the context, mkdir the output, preflight tools
  * (non-html), pre-warm the browser when this build will render in Chromium,

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. */