gutterpress 0.10.7 → 0.10.8-beta.1

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

@@ -39,6 +39,76 @@ export interface GutterpressPluginMetadata {
     author?: string;
     keywords?: string[];
 }
+/**
+ * A declared marker's structural-element label (#240) — a real child element
+ * injected as the container's first child, the same "structural element
+ * carrying the data as both text content and an attribute" shape
+ * `markers.js`'s own `.chapter-opener` uses for `@chapter`.
+ */
+export interface GutterpressMarkerLabel {
+    /** Class on the injected label element. */
+    class: string;
+    /**
+     * Where the label text comes from. Only `"attr:<name>"` is supported today
+     * (the marker's own attribute of that name) — see `markers.js`'s
+     * `resolveContainerShape` for why the format leaves room to grow later
+     * instead of silently doing nothing for an unsupported value now.
+     */
+    from: string;
+    /** HTML tag for the injected label element. Defaults to `"div"`. */
+    tag?: string;
+}
+/**
+ * One entry in a plugin's declared `markers` table (#240 — "declarative
+ * container components in core"). Exactly one of three shapes:
+ *
+ *   - a CONTAINER: `tag`/`class`/`variants`/`label`/`autoCloseAt`, any/all
+ *     optional (a bare `{}` is a valid, if pointless, `<div>` wrapper);
+ *   - an ALIAS: `alias` (another declared name) + optional `preset`;
+ *   - a DEPRECATION: `deprecated` (a human-readable retirement message) —
+ *     wins over every other field on the same entry, per
+ *     `markers.js`'s `resolveMarkerDeclaration`.
+ *
+ * See `markers.js`'s header comment for a worked example and
+ * `buildDeclaredMarkerRegistry` for the full validation/resolution contract
+ * (collision rules, alias indirection, the auto-derived `@end-<name>`
+ * closer). This type exists so a plugin AUTHOR importing it type-only
+ * (CLAUDE.md §5) has a real shape to write against; core's own consumption
+ * of the data is plain, duck-typed JS, matching every other markdown-it
+ * plugin input.
+ */
+export interface GutterpressMarkerDeclaration {
+    /** Wrapper element tag. Defaults to `"div"`. */
+    tag?: string;
+    /** Base class(es) on the wrapper, e.g. `"dc-alert"`. */
+    class?: string;
+    /**
+     * Extra class(es) keyed by the marker's own bare name/argument (its
+     * "variant" — `@callout warning` selects `variants.warning`), appended
+     * after `class`.
+     */
+    variants?: Record<string, string>;
+    label?: GutterpressMarkerLabel;
+    /**
+     * Boundaries at which an unclosed instance of this marker auto-closes
+     * WITHOUT a warning. `"eof"` is the only value implemented today — an
+     * unclosed container always auto-closes at end-of-document regardless
+     * (required for well-formed HTML across concatenated chapter files); this
+     * only controls whether that forced close is silent (declare it here) or
+     * warns (the default — most likely a forgotten `@end-<name>`).
+     */
+    autoCloseAt?: Array<"eof">;
+    /** This marker is sugar for another declared marker (must name a non-alias, non-deprecated entry). */
+    alias?: string;
+    /** With `alias`: defaults applied when the invocation line supplies none. */
+    preset?: {
+        variant?: string;
+    };
+    /** This marker is retired: using it (or its `@end-` form) warns with this message and is otherwise a no-op. */
+    deprecated?: string;
+}
+/** A plugin's full declared marker table — see {@link GutterpressMarkerDeclaration}. */
+export type GutterpressMarkerTable = Record<string, GutterpressMarkerDeclaration>;
 /**
  * Full shape a plugin module may export. Only `default` is required.
  *
@@ -48,6 +118,7 @@ export interface GutterpressPluginMetadata {
  * export const metadata: GutterpressPluginMetadata = { name: 'my-plugin', version: '1.0.0' };
  * export const css = `.my-class { color: red; }`;
  * export const styles = ["./styles/components.css", "./styles/callouts.css"];
+ * export const markers: GutterpressMarkerTable = { callout: { tag: 'div', class: 'dc-alert' } };
  * ```
  */
 export interface GutterpressPluginExport {
@@ -66,6 +137,12 @@ export interface GutterpressPluginExport {
      * before the project's own stylesheets.
      */
     styles?: string[];
+    /**
+     * Declarative container components (#240) — data interpreted by CORE's
+     * marker parser (`markers.js`), the same relationship `css`/`styles`
+     * already have to the loader. See {@link GutterpressMarkerDeclaration}.
+     */
+    markers?: GutterpressMarkerTable;
 }
 /** Internal representation of a loaded plugin, ready for `md.use()`. */
 export interface LoadedPlugin {
@@ -80,6 +157,12 @@ export interface LoadedPlugin {
      * declared order. `undefined`/`[]` for a plugin that declares none.
      */
     styles?: string[];
+    /** #240 — the plugin's raw, as-authored `markers` export, unresolved (see
+     * {@link GutterpressPluginExport.markers}). `createMarkdownRenderer` merges
+     * every loaded plugin's table via `buildDeclaredMarkerRegistry` before
+     * `gutterpressMarkers` ever runs — this field is untouched by the loader,
+     * mirroring how `css` is carried through as an opaque string. */
+    markers?: GutterpressMarkerTable;
     options: Record<string, unknown>;
 }
 /**
@@ -135,6 +218,22 @@ export declare const BUILTIN_OPTIONAL_PLUGINS: Record<string, GutterpressPlugin>
  * primitive. A project using neither plugin still renders `> [!NOTE]` as a
  * literal blockquote, unchanged — this feature is opt-in, not a default.
  *
+ * #240 — before `gutterpressMarkers` is applied, every loaded plugin's
+ * declared `markers` table (if any) is merged into ONE registry via
+ * `buildDeclaredMarkerRegistry` (markers.js) — validating collisions against
+ * core's own reserved names and against each other, resolving alias/preset
+ * indirection — and handed to the marker plugin as
+ * `{ declaredMarkers }`. This is WHY the merge happens here rather than in
+ * the loader (`plugins.ts`): `createMarkdownRenderer` is the one place that
+ * already sees every loaded plugin together, and merging before
+ * `md.use(gutterpressMarkers, ...)` is what lets `@callout`/`@end-callout`
+ * be recognized by the SAME block-level grammar as `@section` from the very
+ * first parse, rather than needing a second pass. A plugin's own hand-
+ * written block rule (for authors who need more than the declarative table)
+ * is still registered later, in the customPlugins loop below, exactly as
+ * before #240 — declaring `markers` and writing a plain markdown-it plugin
+ * function are not mutually exclusive.
+ *
  * @param customPlugins - Optional array of custom plugins to load
  */
 export declare function createMarkdownRenderer(customPlugins?: LoadedPlugin[]): MarkdownIt;

package/dist/lib/snippets.d.ts

@@ -1,13 +1,47 @@
 /** Folder (relative to the project root) snippets live in. */
 export declare const SNIPPETS_DIR = "snippets";
+/**
+ * Where a merged-list entry came from (#242).
+ *
+ * `{ kind: "project" }` — the author's own snippet, from `<projectDir>/
+ * snippets/`. This is the ONLY provenance `saveSnippet`/`deleteSnippet` ever
+ * produce or touch, and therefore the ONLY provenance the picker may offer to
+ * edit or delete — a `source` this shape is the single flag the UI needs to
+ * gate those actions, so "can this be deleted" never drifts out of sync with
+ * "where did this come from" (one field, not two that could disagree).
+ *
+ * `{ kind: "plugin" | "theme", ref, name }` — a READ-ONLY snippet merged in
+ * from an installed, currently-ACTIVE extension (see
+ * {@link listInstalledExtensions} for exactly which extensions qualify).
+ * `name` is the extension's display name — the picker's group label, so an
+ * author always sees WHICH extension a snippet came from, never just "not
+ * mine". `ref` is the same stable identifier {@link listProjectPlugins} (a
+ * plugin's manifest `path`) or {@link getActiveTheme} (a theme's project id)
+ * already hand out; it is round-tripped back into {@link readExtensionSnippet}
+ * so that function can re-derive the extension's folder itself from a small,
+ * validated identifier instead of trusting a filesystem path a caller could
+ * construct.
+ */
+export type SnippetSource = {
+    kind: "project";
+} | {
+    kind: "plugin" | "theme";
+    ref: string;
+    name: string;
+};
 /** One snippet's metadata for the picker (no body — read lazily). */
 export interface SnippetEntry {
     /** Display name (derived from the `.md` filename stem, prettified). */
     name: string;
-    /** The on-disk filename, e.g. `callout.md`. Stable id for read/delete. */
+    /** The on-disk filename, e.g. `callout.md`. Stable id for read/delete
+     *  WITHIN its own source — an extension entry's `fileName` is only ever
+     *  resolved back to a file via {@link readExtensionSnippet} (which also
+     *  needs `source`), never via the project-only {@link readSnippet}. */
     fileName: string;
     /** Distinct `{{variable}}` names parsed from the body, in first-seen order. */
     variables: string[];
+    /** Provenance (#242) — see {@link SnippetSource}. */
+    source: SnippetSource;
 }
 /**
  * Parse the distinct `{{variable}}` placeholder names from a template, in the
@@ -22,18 +56,100 @@ export declare function extractVariables(template: string): string[];
  */
 export declare function substituteVariables(template: string, values: Record<string, string>): string;
 /**
- * List the project's snippets (newest filesystem order is not guaranteed; sort
- * for the picker). Returns `[]` when the `snippets/` folder doesn't exist.
+ * List the project's OWN snippets only — `<projectDir>/snippets/`, exactly as
+ * before #242. The picker itself now calls {@link listMergedSnippets} (which
+ * calls this as its first step); this stays exported and unchanged in
+ * behavior because it is independently useful (and independently tested) as
+ * "just the author's own snippets", with no extension-discovery cost paid by
+ * a caller that doesn't need it.
  */
 export declare function listSnippets(projectDir: string): Promise<SnippetEntry[]>;
-/** Read one snippet's raw body. Refuses path traversal. */
+/** Read one snippet's raw body. Refuses path traversal. Project snippets
+ *  only — see {@link readExtensionSnippet} for the merged-list counterpart
+ *  that reads an extension-provided entry instead. */
 export declare function readSnippet(projectDir: string, fileName: string): Promise<string>;
 /**
  * Save a snippet body under `snippets/<slug(name)>.md`, creating the folder when
  * absent. Returns the stored entry (with its filename + parsed variables). The
  * returned `name` echoes the author-supplied name, while `fileName` is the
  * slugified storage name.
+ *
+ * #242: always writes to (and returns a `source` naming) the PROJECT's own
+ * folder — "Save selection as snippet" keeps writing to the project even
+ * when the picker is currently showing a merged list that includes
+ * extension-provided entries (the issue's suggested shape, point 4). There is
+ * no parameter that could redirect this into an extension's folder.
  */
 export declare function saveSnippet(projectDir: string, name: string, body: string): Promise<SnippetEntry>;
-/** Delete a snippet by filename. Refuses path traversal. */
+/**
+ * Delete a snippet by filename. Refuses path traversal.
+ *
+ * #242: project snippets ONLY — `resolveSnippetPath` hard-scopes every path
+ * to `<projectDir>/snippets/`, so this function is structurally incapable of
+ * reaching into an installed extension's folder no matter what `fileName` a
+ * caller passes (there is no argument that names an extension at all). An
+ * extension's own snippet files are therefore never at risk from the
+ * picker's delete button — the safety is in the function signature, not in
+ * a check the picker has to remember to make.
+ */
 export declare function deleteSnippet(projectDir: string, fileName: string): Promise<void>;
+/**
+ * The project's own snippets, merged with every installed-and-active
+ * extension's (#242) — this is "the snippet host" the picker actually calls;
+ * `listSnippets` above is now just its first ingredient.
+ *
+ * PRECEDENCE / collision (issue's suggested shape, point 2): when an
+ * extension snippet's FILENAME — the slugified identity `saveSnippet` itself
+ * derives a name into, so two different-cased spellings of the same name
+ * collide exactly as they would on a real re-save — matches a project
+ * snippet's, the project one wins outright and the extension's copy is
+ * dropped from this call's result. It is not renamed, not kept reachable
+ * under a second key, and nothing on disk is touched: the comparison and the
+ * drop happen freshly on every call, so the instant the author renames (or
+ * deletes) their colliding snippet, the extension's becomes visible again
+ * with no separate "restore" step. Rationale: the moment an author saves
+ * their own snippet under a name an extension already used, the natural
+ * reading is "I'm overriding this one for my project" — a picker entry that
+ * silently stays inserted from the extension forever after would contradict
+ * that, and a picker entry that just isn't there is a far smaller surprise
+ * than two identically-named rows the author has to guess between.
+ *
+ * This precedence rule is PROJECT-vs-EXTENSION only. Two different
+ * extensions that each happen to ship a same-named snippet are NOT
+ * deduplicated against each other — both survive, each under its own group
+ * header (see GROUPING below), because there is no ambiguity to resolve:
+ * unlike the project-vs-extension case, neither copy could be mistaken for
+ * "the author's own", so there is nothing here for one to silently win over.
+ *
+ * GROUPING: the result is ordered project-first (`listSnippets`'s own
+ * alphabetical order), then one contiguous run per extension — extensions
+ * alphabetical by display name, each run alphabetical by snippet name. The
+ * picker groups purely by noticing `source` change between consecutive
+ * entries; there is no separate grouped/tree shape to keep in sync with this
+ * flat list.
+ */
+export declare function listMergedSnippets(projectDir: string): Promise<SnippetEntry[]>;
+/**
+ * Read one extension-provided snippet's raw body (#242) — the read-only
+ * counterpart to `readSnippet` for entries `listMergedSnippets` tagged with
+ * an extension `source`.
+ *
+ * Deliberately NOT a raw-path read: `source` carries only the same small,
+ * stable `{ kind, ref }` pair `listMergedSnippets` already handed back (see
+ * {@link SnippetSource}), and this function re-runs the EXACT SAME discovery
+ * {@link listMergedSnippets} used ({@link listInstalledExtensions}) to find
+ * the matching extension's folder again, rather than trusting any path a
+ * caller could construct directly — the same defense-in-depth stance
+ * `resolveSnippetPath` already takes for the project's own snippets, now
+ * extended to a second, per-extension root instead of a single project one.
+ *
+ * Throws when `source` no longer resolves to an installed, active extension
+ * (it was disabled, uninstalled, or the theme was switched since the list
+ * was fetched — the picker's existing `error` display already handles a
+ * thrown read the same way a vanished project snippet would) or when
+ * `fileName` escapes that extension's snippets folder.
+ */
+export declare function readExtensionSnippet(projectDir: string, source: {
+    kind: "plugin" | "theme";
+    ref: string;
+}, fileName: string): Promise<string>;

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

@@ -40,11 +40,15 @@ export declare function classifyThemeCssFindings(findings: PrintSafeWarning[]):
 };
 /**
  * From a theme folder's relative file paths, return the ones that are neither
- * `theme.css`/`theme.json` nor a recognized bundled asset (font/image/css).
- * These trigger a non-fatal "unexpected extra files" warning — the import
- * still copies the whole folder.
+ * `theme.css`/`theme.json`/`gutterpress.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
+ * suppresses everything under it, not just the exact entry). These trigger a
+ * non-fatal "unexpected extra files" warning — the import still copies the
+ * whole folder.
  */
-export declare function unexpectedThemeFiles(relPaths: string[]): string[];
+export declare function unexpectedThemeFiles(relPaths: string[], declaredExtras?: string[]): string[];
 /**
  * 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

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

@@ -1,44 +1,20 @@
+import { type ExtensionMetadata, assertExtensionContained, extensionEngineStyleList } from "./extension-manifest.ts";
 /** Folder (relative to the project root) themes are copied into on apply/import. */
 export declare const THEMES_DIR = "themes";
 /** The built-in themes shipped as embedded assets (ids are folder names). */
 export declare const BUILT_IN_THEME_IDS: readonly ["clean-book", "zine", "technical-doc"];
 export type BuiltInThemeId = (typeof BUILT_IN_THEME_IDS)[number];
-/** Parsed `theme.json` metadata (every field optional in the file). */
-export interface ThemeMetadata {
-    name?: string;
-    author?: string;
-    description?: string;
-    /** Optional preview image path (relative to the theme folder). */
-    preview?: string | null;
-    /**
-     * #239 — ordered stylesheets, relative to the theme folder. A theme is no
-     * longer capped at one file: this is what lets a real component library
-     * (tokens/base/components/templates/rules as separate layered sheets) be a
-     * theme. Absent/empty defaults to `["theme.css"]` — every theme published
-     * before this field existed keeps working, byte-for-byte, untouched. Globs
-     * are NOT supported, matching the manifest's own `styles:` list (§0 — one
-     * authoring convention, not two).
-     */
-    styles?: string[];
-    /**
-     * #239 — engine-conditional sheets, relative to the theme folder. Applying
-     * the theme appends these to the manifest's `engineStyles.native` list
-     * (loaded last, so furniture wins — see manifest.ts's resolveWithPreset).
-     */
-    engineStyles?: {
-        native?: string[];
-    };
-    /**
-     * #239 — which declared sheet (a path from `styles`, or `theme.css` when
-     * `styles` is absent) carries the author-facing `:root` token surface. Lets
-     * a rich multi-sheet theme tell the Design panel's guided token editor
-     * where to look instead of it guessing at the single active stylesheet.
-     * Purely advisory metadata — nothing in this module enforces it. Absent
-     * here means "no override"; {@link ThemeInfo.tokensFile} is where the
-     * default (the theme's primary/only sheet) gets filled in.
-     */
-    tokensFile?: string;
-}
+/**
+ * Parsed theme metadata (every field optional in the file) — #241: a theme is
+ * the degenerate "styles only" case of {@link ExtensionMetadata}, so this is
+ * now a plain alias rather than a separate type. A `theme.json` file only
+ * ever populates the fields this comment used to document in full
+ * (`name`/`author`/`description`/`preview`/`styles`/`engineStyles`/
+ * `tokensFile`, #239); the three newer fields (`markdown`/`components`/
+ * `snippets`) are only reachable via a `gutterpress.json` — see
+ * `extension-manifest.ts` for the complete, current field-by-field doc.
+ */
+export type ThemeMetadata = ExtensionMetadata;
 /** Author-friendly metadata for one theme (built-in or project). */
 export interface ThemeInfo {
     /** Stable id (a built-in id, or a slug for imported/applied themes). */
@@ -70,6 +46,26 @@ export interface ThemeInfo {
      * fallback.
      */
     tokensFile: string;
+    /**
+     * #241 — declared-relative path to a markdown-it entry, when this theme's
+     * `gutterpress.json` names one (never possible via the legacy `theme.json`
+     * shape). Informational only: the theme verbs (list/apply/import/revert/
+     * remove) do not load or wire it — a full extension carrying both styles
+     * AND markdown installs via `gutterpress plugin add <folder>` instead (see
+     * `plugins.ts`'s `loadExtensionFromDir`), which resolves and applies this
+     * SAME field. Surfaced here so a theme card can at least show "this
+     * extension also has a plugin half" rather than staying silent about it.
+     */
+    markdown?: string;
+    /** #241 — declared-relative path to a component catalog file, informational
+     *  only (same rationale as {@link markdown}); no catalog reader consumes
+     *  this yet. */
+    components?: string;
+    /** #241 — declared-relative path to a snippets folder, informational only
+     *  on THIS type (same rationale as {@link markdown} — the theme verbs
+     *  don't load it). The active theme's copy of this field IS consumed,
+     *  by `snippets.ts`'s `listMergedSnippets` (#242) via `getActiveTheme`. */
+    snippets?: string;
 }
 /** A built-in theme resolved to disk (extracted from the embedded assets). */
 export interface ResolvedTheme {
@@ -94,10 +90,17 @@ export type ApplyThemeTarget = {
  * satisfies, so nothing needs migrating. Exported for `theme-import.ts`,
  * which validates every one of these (existence + print-safety) at import
  * time, the same way it always validated the lone `theme.css`.
+ *
+ * #241: layers that theme-only default on top of `extension-manifest.ts`'s
+ * {@link extensionStyleList}, which does NOT apply it (a markdown-only
+ * extension has no reason to require a `theme.css` it never declared) — one
+ * shared "read the declared list" body, two defaulting rules.
  */
 export declare function themeStyleList(meta: ThemeMetadata): string[];
 /**
- * Every declared sheet must live INSIDE the theme folder. A theme is
+ * Every declared sheet (styles/engineStyles — #241: now also `markdown`/
+ * `components`/`snippets`/`tokensFile`, since a `gutterpress.json`-formatted
+ * theme can declare them too) must live INSIDE the theme folder. A theme is
  * self-contained by contract (apply copies the whole folder), and an imported
  * package is untrusted input: a `../` or absolute entry would make apply read
  * a file from anywhere on disk into the book.
@@ -109,16 +112,26 @@ export declare function themeStyleList(meta: ThemeMetadata): string[];
  * `getPreviousTheme`, `readThemeCss`) also call: one hand-edited theme.json
  * must not take down listing every theme, the same reason `readThemeMeta`
  * returns `{}` for an unparseable file instead of throwing.
+ *
+ * #241 — a straight re-export of the extension-generic
+ * {@link assertExtensionContained}: a theme's containment rule is not a
+ * separate implementation, it IS the extension rule, applied to a metadata
+ * object that (for a `theme.json`-only folder) never has the three newer
+ * fields populated in the first place.
  */
-export declare function assertThemeSheetsContained(meta: ThemeMetadata): void;
+export declare const assertThemeSheetsContained: typeof assertExtensionContained;
 /**
  * A theme's declared engine-conditional sheets, relative to its folder
  * (#239). `Array.isArray` guards a malformed `engineStyles.native` (authored
  * as something other than a list) — treated as "none declared" rather than a
  * hard crash on a JSON author's typo. Exported for `theme-import.ts`'s import
  * validation, same reuse rationale as {@link themeStyleList}.
+ *
+ * #241 — a straight alias: `engineStyles.native` never had a theme-specific
+ * default to layer on, so this is byte-identical to
+ * {@link extensionEngineStyleList}.
  */
-export declare function themeEngineStyleList(meta: ThemeMetadata): string[];
+export declare const themeEngineStyleList: typeof extensionEngineStyleList;
 /** List the built-in themes (metadata read from the extracted embedded assets). */
 export declare function listBuiltInThemes(): Promise<ThemeInfo[]>;
 /** Resolve a built-in theme to its extracted `theme.css` + parsed metadata. */

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

@@ -14,6 +14,18 @@ export interface ValidationExecutionArgs {
     phase?: string;
     /** Publish-target ids (CSV) to validate against, overriding the manifest's `targets:` for this run. */
     target?: string;
+    /**
+     * Pre-loaded, absolute plugin `styles` file paths (#262) — supplied by the
+     * build pipeline's preValidate gate (`build-runner.ts`'s
+     * `runQualityGates`, via `loadBuildPlugins`) so this run does not load
+     * plugins itself when the build already has. `undefined` (the default —
+     * every standalone `validate`/`preflight`/`audit` invocation, and the
+     * desktop Problems panel) makes {@link executeValidation} load plugins
+     * itself, degrade-and-report, exactly like `gutterpress lint`
+     * (lint-runner.ts). An explicit `[]` is honored as-is, not treated as
+     * "unset".
+     */
+    pluginStylePaths?: string[];
 }
 export interface ValidationExecutionResult {
     config: ResolvedConfig;

package/dist/{lint-mpz7vfc8.js → lint-9xhz0bsw.js}

@@ -1,16 +1,16 @@
 import {
   MANIFEST_FILENAMES,
   runLint
-} from "./cli-kzf64c2g.js";
+} from "./cli-wvw2msvn.js";
 import {
   log
-} from "./cli-pvk2s9d7.js";
+} from "./cli-pw6z15yv.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-h8ejbtyr.js";
-import"./cli-s8q42x3r.js";
+} from "./cli-v1ma3v2s.js";
+import"./cli-4vtgt2ng.js";
 import"./cli-c41yr7he.js";
 import {
   EXIT_CODES

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

@@ -88,8 +88,8 @@
               "path": {
                 "type": "string",
                 "minLength": 1,
-                "description": "Path to a local plugin module, relative to the manifest directory.",
-                "examples": ["plugins/dimm-city-plugin.js", "../shared/plugins/callouts.js"]
+                "description": "Path to a local plugin module OR an extension folder (a gutterpress.json package, optionally carrying styles/engineStyles alongside its markdown entry), relative to the manifest directory.",
+                "examples": ["plugins/dimm-city-plugin.js", "../shared/plugins/callouts.js", "./extensions/dc-components"]
               },
               "name": {
                 "type": "string",

package/dist/{new-nbrpsw7t.js → new-5drcm5am.js}

@@ -1,20 +1,22 @@
 import {
   BUILT_IN_TEMPLATE_IDS,
+  EXTENSION_KINDS,
   PRESETS,
   PRESET_IDS,
   TARGETS,
   TARGET_IDS,
+  scaffoldExtension,
   scaffoldProject
-} from "./cli-kzf64c2g.js";
+} from "./cli-wvw2msvn.js";
 import {
   resolveGhostscript
-} from "./cli-pvk2s9d7.js";
+} from "./cli-pw6z15yv.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-h8ejbtyr.js";
-import"./cli-s8q42x3r.js";
+} from "./cli-v1ma3v2s.js";
+import"./cli-4vtgt2ng.js";
 import {
   isToolAvailable
 } from "./cli-c41yr7he.js";
@@ -31,9 +33,21 @@ import { resolve } from "node:path";
 var newArgs = {
   name: {
     type: "positional",
-    description: "Project name (becomes the title and folder name)",
+    description: "Name (becomes the title/package name and the folder name)",
     required: true
   },
+  kind: {
+    type: "string",
+    description: `What to create: book (default), ${EXTENSION_KINDS.join(", ")}`
+  },
+  prefix: {
+    type: "string",
+    description: 'Class/custom-property prefix an extension claims (default: its slug, e.g. "field-notes-"); --kind plugin|theme only'
+  },
+  description: {
+    type: "string",
+    description: "One-line description recorded in the extension's metadata; --kind plugin|theme only"
+  },
   preset: {
     type: "string",
     description: `Vendor preset the book is designed for: ${PRESET_IDS.join(", ")} (required; custom also needs --page-width/--page-height)`
@@ -76,6 +90,41 @@ var newArgs = {
     default: true
   }
 };
+function flagsPassed(rawArgs) {
+  const seen = new Set;
+  for (const token of rawArgs) {
+    if (token === "--")
+      break;
+    if (!token.startsWith("--") || token.length <= 2)
+      continue;
+    const equalsAt = token.indexOf("=");
+    let name = equalsAt === -1 ? token.slice(2) : token.slice(2, equalsAt);
+    name = name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+    if (name.startsWith("no-"))
+      name = name.slice(3);
+    seen.add(name);
+  }
+  return seen;
+}
+var BOOK_ONLY_FLAGS = [
+  "preset",
+  "targets",
+  "template",
+  "page-width",
+  "page-height",
+  "page-tolerance",
+  "git"
+];
+var EXTENSION_ONLY_FLAGS = ["prefix", "description"];
+function rejectFlagsForKind(rawArgs, kind) {
+  const passed = flagsPassed(rawArgs);
+  const inapplicable = (kind === "book" ? EXTENSION_ONLY_FLAGS : BOOK_ONLY_FLAGS).filter((f) => passed.has(f));
+  if (inapplicable.length === 0)
+    return;
+  const list = inapplicable.map((f) => `--${f}`).join(", ");
+  console.error(kind === "book" ? `${list} ${inapplicable.length > 1 ? "are" : "is"} only meaningful for an extension. ` + `Add --kind ${EXTENSION_KINDS.join(" or --kind ")}, or drop ${inapplicable.length > 1 ? "them" : "it"}.` : `${list} ${inapplicable.length > 1 ? "describe a book, not" : "describes a book, not"} a ${kind}. ` + `A ${kind} has no trim size, publish target or starter template — drop ${inapplicable.length > 1 ? "them" : "it"}.`);
+  process.exit(EXIT_CODES.USAGE);
+}
 function parsePoints(raw, flag) {
   if (typeof raw !== "string" || raw === "")
     return;
@@ -86,10 +135,55 @@ function parsePoints(raw, flag) {
   }
   return value;
 }
+function optionalString(value) {
+  return typeof value === "string" && value ? value : undefined;
+}
+async function runExtensionScaffold(kind, name, parentDir, args) {
+  try {
+    const result = await scaffoldExtension({
+      name,
+      kind,
+      parentDir,
+      folderName: optionalString(args.folder),
+      prefix: optionalString(args.prefix),
+      author: optionalString(args.author),
+      description: optionalString(args.description)
+    });
+    console.log(`Created ${kind}: ${result.extensionDir}`);
+    console.log(`  metadata: ${result.manifestPath}`);
+    console.log(`  class prefix: ${result.prefix}`);
+    console.log(`  files: ${result.files.length}`);
+    console.log(`  start editing in: ${result.openFile}`);
+    console.log("");
+    if (kind === "plugin") {
+      console.log("Next: check it still works —");
+      console.log(`  cd ${result.slug} && bun install && bun test`);
+      console.log("");
+      console.log("      then load it from a book's manifest.yaml:");
+      console.log("        plugins:");
+      console.log(`          - path: plugins/${result.slug}`);
+      console.log("");
+      console.log("      (point `path` at the FOLDER, not plugin.js — that is what makes");
+      console.log("       Gutterpress read gutterpress.json and pick up the stylesheet too.)");
+    } else {
+      console.log("Next: install it into a book —");
+      console.log(`  gutterpress theme import ${result.extensionDir} <book>`);
+      console.log(`  gutterpress theme apply ${result.slug} <book>`);
+      console.log("");
+      console.log("      Each stylesheet opens with the OWNS / MUST NOT CONTAIN header that");
+      console.log("      says which rules belong in it. Start with styles/tokens.css.");
+    }
+  } catch (e) {
+    const err = e;
+    const code = err && typeof err.code === "string" ? err.code : "scaffold-io";
+    console.error(`Could not create ${kind}: ${err?.message ?? String(e)}`);
+    process.exit(code === "scaffold-io" ? EXIT_CODES.PIPELINE : EXIT_CODES.USAGE);
+  }
+}
 var new_default = defineCommand({
   meta: {
     name: "new",
-    description: "Create a new Gutterpress project from a starter template"
+    description: "Create a new Gutterpress book, plugin or theme from a starter template"
   },
   args: newArgs,
   async run({ args, rawArgs }) {
@@ -105,6 +199,17 @@ var new_default = defineCommand({
     }
     const name = String(args.name);
     const parentDir = resolve(typeof args.dir === "string" && args.dir ? args.dir : process.cwd());
+    const rawKind = typeof args.kind === "string" && args.kind ? args.kind : "book";
+    if (rawKind !== "book" && !EXTENSION_KINDS.includes(rawKind)) {
+      console.error(`Unknown kind "${rawKind}". Choose one of: book, ${EXTENSION_KINDS.join(", ")}.`);
+      process.exit(EXIT_CODES.USAGE);
+    }
+    const kind = rawKind;
+    rejectFlagsForKind(rawArgs, kind);
+    if (kind !== "book") {
+      await runExtensionScaffold(kind, name, parentDir, args);
+      return;
+    }
     let template;
     if (typeof args.template === "string" && args.template) {
       if (!BUILT_IN_TEMPLATE_IDS.includes(args.template)) {