gutterpress 0.10.7-beta.1 → 0.10.8-beta.1

package/README.md

@@ -143,12 +143,19 @@ source.
 
 ### `gutterpress new`
 
-Scaffold a new project from an embedded starter template — the fastest way to start writing (see [Quick start](#quick-start)). Every new book picks the vendor preset it's designed for: `dtrpg` (DriveThruRPG print-on-demand), `book` (neutral 6x9in trade book), or `custom` (you supply the trim size in points).
+Scaffold a new book, plugin or theme from an embedded starter template — the fastest way to start (see [Quick start](#quick-start)).
+
+`--kind book` is the default. Every new book picks the vendor preset it's designed for: `dtrpg` (DriveThruRPG print-on-demand), `book` (neutral 6x9in trade book), or `custom` (you supply the trim size in points).
+
+`--kind plugin` and `--kind theme` scaffold an **extension package** instead — a folder with a `gutterpress.json` a book can load. The plugin starter carries a declarative marker table, a hand-written markdown-it rule, component CSS and a `bun test` fixture suite; the theme starter carries the six-file layered CSS architecture (tokens / base / components / page-templates / page-rules / book), each sheet opening with its own OWNS / MUST NOT CONTAIN contract header. Both include a README explaining which conventions are load-bearing. An extension needs no preset, trim size or publish target, so the book-only flags below are rejected rather than ignored when `--kind` names one — and `--prefix`/`--description` are likewise rejected for a book.
 
 ```sh
-gutterpress new <name> --preset <id> [options]
+gutterpress new <name> [--kind <id>] [options]
 
-  --preset <id>            Vendor preset the book is designed for: dtrpg, book, custom (required)
+  --kind <id>              What to create: book (default), plugin, theme
+  --prefix <str>           Class/custom-property prefix an extension claims (default: its slug, e.g. "field-notes-"); --kind plugin|theme only
+  --description <text>     One-line description recorded in the extension's metadata; --kind plugin|theme only
+  --preset <id>            Vendor preset the book is designed for: dtrpg, book, custom (required for a book)
   --author <name>          Author name to record in the project
   --dir <path>             Parent directory to create the project in (default: current directory)
   --folder <name>          Folder name to create (default: a slug of the project name)

package/dist/README-aaqapam1.md

@@ -0,0 +1,186 @@
+# {{NAME}}
+
+> {{DESCRIPTION}}
+
+A Gutterpress **theme** — a layered CSS architecture, not a look. The colours
+and the typeface are placeholders you will replace in an afternoon; the
+arrangement of the files is the part worth keeping.
+
+```
+{{SLUG}}/
+├── gutterpress.json          what this package declares to Gutterpress
+├── components.yaml           the catalog: what an author can opt into
+├── snippets/                 insertable recipes for the components
+└── styles/
+    ├── tokens.css            :root only. Palette, type, spacing.
+    ├── base.css              element baseline. Bare p/h2/table/code.
+    ├── components.css        named components + their public tokens.
+    ├── page-templates.css    .page.* layouts — arrangement WITHIN a page.
+    ├── page-rules.css        @page geometry, margin boxes, running heads.
+    └── book.css              this book's overrides. Loads last.
+```
+
+Every file opens with an **OWNS / MUST NOT CONTAIN** header. Those headers are
+the actual contract — they live in the files precisely so they travel with the
+code instead of sitting in a document nobody opens at the moment they are
+about to add a rule to the wrong sheet.
+
+## Try it
+
+```sh
+gutterpress theme import ./{{SLUG}} ../my-book
+gutterpress theme apply {{SLUG}} ../my-book
+gutterpress preview ../my-book
+```
+
+Both theme commands take the book directory as their second POSITIONAL
+argument, not a `--dir` flag.
+
+Then in a chapter:
+
+```markdown
+@section .{{PREFIX}}callout
+### Before you start
+Everything in here stays together on one page.
+@end-section
+```
+
+## Why six files
+
+Gutterpress ships three built-in themes of about sixty lines each. They style
+bare elements and stop, which is the right size for a plain book and is not an
+architecture. The first book that needs components outgrows one in a week, and
+then re-derives this arrangement from scratch — badly, usually twice.
+
+The split is by OWNERSHIP, and the value is that it answers one question
+instantly: **where does this rule go?**
+
+| I want to change… | File |
+|---|---|
+| the brand — a colour, a typeface, the type scale | `tokens.css` |
+| what a plain paragraph or table looks like | `base.css` |
+| a named thing an author opts into | `components.css` |
+| how one page arranges its content | `page-templates.css` |
+| margins, folios, running heads | `page-rules.css` |
+| one chapter of one book | `book.css` |
+
+If a rule seems to belong in two of them, it is usually two rules.
+
+## The token pattern
+
+This is the mechanism the whole architecture rests on, demonstrated end to end
+by the callout component:
+
+```css
+/* tokens.css — the brand */
+:root { --{{PREFIX}}accent: #2f5d8a; }
+
+/* components.css — the component's own public token, then bare consumption */
+:root { --{{PREFIX}}callout-accent: var(--{{PREFIX}}accent); }
+.{{PREFIX}}callout { border-inline-start: 3px solid var(--{{PREFIX}}callout-accent); }
+
+/* book.css — one chapter wants a different one */
+#ch-appendix { --{{PREFIX}}callout-accent: var(--{{PREFIX}}accent-warm); }
+```
+
+Three properties make it work, and losing any one of them collapses it:
+
+1. **The default lives at `:root`, exactly once.** So the component looks
+   right in any book with no setup, and there is one place to change it.
+
+2. **Components consume `var(--x)`, never `var(--x, fallback)`.** An inline
+   fallback is a second copy of the default. It will drift from the `:root`
+   one, and when it does the component will look correct everywhere except
+   the one place somebody overrode the token.
+
+3. **Overrides only ever RESET a token.** Never
+   `#ch-appendix .{{PREFIX}}callout { border-color: … }`. The token is the
+   seam between "what the component is" and "what this book wants"; writing
+   past it welds them together, and the next change to the component breaks
+   the book.
+
+A variant is the same move made inside the package:
+`.{{PREFIX}}callout-warning` resets one token and inherits everything else.
+
+## The conventions that are load-bearing
+
+### 1. One prefix, and it is yours
+
+Every component class, page-template class and custom property here starts
+with `{{PREFIX}}`. A book loads core, this theme and any number of plugins
+into one flat CSS namespace; nothing scopes them for you.
+
+`gp-` is reserved for Gutterpress core — taking it silently overrides core's
+own vocabulary.
+
+`base.css` is the deliberate exception: styling bare `p` and `table` is
+exactly a theme's job, because a theme IS the book's look. A PLUGIN doing the
+same thing would be leaking its opinions into every book that installed it.
+That asymmetry is the whole difference between the two kinds of package.
+
+### 2. Declare the layer order once, and adopt it per whole sheet
+
+`tokens.css` opens with:
+
+```css
+@layer tokens, base, components, templates, pages, book;
+```
+
+Each sheet then puts everything it owns inside its layer. The cascade is
+settled by that one line rather than by which file `styles:` lists last, so
+splitting a sheet or reordering the manifest can no longer silently flip who
+wins.
+
+The trap, and it catches everyone once: a rule left OUTSIDE all the layers is
+fully unlayered, and unlayered CSS beats layered CSS at any specificity. So
+one stray rule at the bottom of `components.css` will out-rank every rule in
+`book.css`. Adopt the convention for a whole sheet at a time.
+
+These layers are unlayered relative to Gutterpress core (which uses
+`gp.marker` and `gp.vocab`), so every rule here still beats core exactly as it
+did before layers existed.
+
+### 3. Authors write semantic markdown
+
+The author's entire styling vocabulary is the component name:
+`@section .{{PREFIX}}callout`. Not `{.blue}` on a paragraph, not `{.compact}`
+on a table, not a `<div>`.
+
+The reason is maintenance, not purity: a variant expressed as a class the
+author retypes must be found and replaced across every chapter when it
+changes. A variant expressed as a component name plus a CSS rule changes in
+one place, and chapters written afterwards get it for free.
+
+### 4. `@page { size }` is not optional, and it must match the manifest
+
+`page-rules.css` opens by declaring the trim:
+
+```css
+@page { size: 6in 9in; }
+```
+
+That line is load-bearing in the most literal sense. With no `size:` anywhere
+in the book's CSS, Chromium falls back to US Letter and prints the whole book
+at the wrong trim, with no error — this is the one failure in the stack that
+costs money rather than time.
+
+The manifest's `preset:`/`page:` remains the source of truth: it is what
+`gutterpress validate` measures the produced PDF against, and what the publish
+targets check. The CSS line is the instruction that satisfies it. Change one,
+change the other — and let validate catch you when you forget.
+
+### 5. Keep the catalog honest
+
+`components.yaml` enumerates what an author can opt into and which tokens are
+public. Anything not listed there is internal and may change.
+
+Nothing in core reads the entries yet, so it is a discipline rather than a
+check — which is exactly why adding the entry at the same moment you add the
+component is worth the habit.
+
+## Further reading
+
+- `docs/contextual-cascade-principle.md` — the pattern these files implement,
+  with more worked examples.
+- `docs/native-engine-styling-guide.md` — cascade layers, `@page`, GCPM, and
+  what the engine does with them.

package/dist/README-mdq34cmb.md

@@ -0,0 +1,155 @@
+# {{NAME}}
+
+> {{DESCRIPTION}}
+
+A Gutterpress **plugin** — a folder that adds markdown behaviour, component
+CSS and insertable snippets to a book.
+
+```
+{{SLUG}}/
+├── gutterpress.json     what this package declares to Gutterpress
+├── plugin.js            the markdown-it plugin (declarative + bespoke halves)
+├── styles/plugin.css    component CSS, with public tokens at :root
+├── snippets/            insertable recipes, one per component
+├── test/                fixture.md → expected.html, runnable with `bun test`
+└── package.json         only needed for `bun test` and publishing to npm
+```
+
+## Try it
+
+```sh
+bun install     # once — pulls markdown-it, the suite's only dependency
+bun test
+```
+
+Then wire it into a book. In the book's `manifest.yaml`:
+
+```yaml
+plugins:
+  - path: plugins/{{SLUG}}
+```
+
+`path:` names the FOLDER, not `plugin.js`. That is what makes Gutterpress read
+`gutterpress.json` and pick up the stylesheet and snippets alongside the
+markdown behaviour — point it at the `.js` file and you get the markdown and
+nothing else.
+
+Now `gutterpress preview` the book and write:
+
+```markdown
+@term-box warning label="Read this first"
+The rule of three applies here, and [[initiative]] is defined inline.
+@end-term-box
+```
+
+## The conventions that are load-bearing
+
+Most of what is in this folder is a suggestion. These five are not — each one
+is something Gutterpress does not check for you, and each one fails silently
+in somebody else's book when you get it wrong.
+
+### 1. One prefix, and it is yours
+
+Every class, every CSS custom property and every marker name this package
+emits starts with `{{PREFIX}}`.
+
+A book loads core, a theme and any number of plugins into a single flat CSS
+namespace and a single flat marker namespace. Nothing scopes them. Without a
+prefix, your `.callout` and somebody else's `.callout` are the same selector,
+and the one that loads second wins — in their book, not yours, with no error.
+
+`gp-` is reserved for Gutterpress core. Taking it does not conflict; it
+overrides, which is worse.
+
+`test/plugin.test.js` enforces both halves of this.
+
+### 2. Never import from `gutterpress`
+
+Not at runtime. Gutterpress ships as a single compiled binary with no
+`node_modules` for plugin code to resolve against, so the import that works on
+your machine throws on a reader's.
+
+If you need a helper from core, inline a copy of it.
+
+TYPE-only imports are the exception, because they are erased before the code
+ever runs:
+
+```js
+/** @param {import("gutterpress").GutterpressPlugin} _ */
+```
+
+```ts
+import type { GutterpressPlugin, GutterpressMarkerTable } from "gutterpress";
+```
+
+### 3. A plugin is a plain markdown-it plugin
+
+`export default function (md, options) {}` and nothing else. No base class, no
+registration call, no context object handed to you by the host. This is why
+any markdown-it plugin on npm works in Gutterpress unchanged — and the price
+of that is that your plugin has to be one too.
+
+`markers`, `styles`, `css` and `metadata` are additional exports the loader
+READS. They are data, not an API.
+
+### 4. Declarative markers for containers, a rule for everything else
+
+`export const markers` describes a wrapper element and Gutterpress's own
+marker parser does the rest — same grammar, same class merging, same warnings
+as core's `@section`. Use it whenever "wrap a block in an element with a
+class" is the whole job.
+
+Write a markdown-it rule by hand when it is not: inline syntax, token
+rewriting, custom renderers. `plugin.js` has one of each so you can see the
+line.
+
+Marker names are global across every plugin a book loads. Two plugins
+declaring `@callout` is a hard load error naming both — which is a good
+outcome, and another reason to prefix.
+
+### 5. Put your CSS in your own cascade layer
+
+`styles/plugin.css` wraps everything in `@layer {{SLUG}}`.
+
+Plugin CSS is injected before the book's own stylesheets, and in CSS an
+unlayered rule beats a layered one at any specificity. So an unlayered plugin
+sheet outranks every rule in a book that uses the recommended
+`@layer tokens, base, components, templates, pages, book;` convention — the
+author edits their CSS and nothing happens.
+
+Because this sheet loads first, its layer sorts first, which makes it the
+weakest thing in the book. That is the right place for a plugin to sit.
+
+Adopt it for the whole file: a rule left outside the layer is unlayered and
+beats everything inside it, including your own.
+
+## Theming: the token pattern
+
+Every look this package ships is driven by a custom property declared once at
+`:root`, and consumed bare:
+
+```css
+:root { --{{PREFIX}}term-box-accent: #2f5d8a; }
+
+.{{PREFIX}}term-box { border-left: 3px solid var(--{{PREFIX}}term-box-accent); }
+```
+
+`var(--x)`, not `var(--x, #2f5d8a)` — the default lives at `:root` exactly
+once, so there is one place to look and no second copy to drift.
+
+A book retunes it without touching this package, globally or per chapter:
+
+```css
+#ch-appendix { --{{PREFIX}}term-box-accent: #7a1f1f; }
+```
+
+A variant does the same thing internally: it only ever resets tokens, never
+restates the component's rules.
+
+## Publishing
+
+Anything a book can reach works. Committing the folder into the book's
+`plugins/` directory is the simplest and needs no registry at all.
+
+To publish to npm, `npm publish` this folder and have readers install it with
+`gutterpress plugin add {{SLUG}}`.

package/dist/api/index.d.ts

@@ -23,20 +23,24 @@ export { detectProjectSource, capabilitiesFor, findEnclosingRepoDir, repoSubPath
 export type { ProjectSource, ProjectCapabilities, } from "../lib/project-source";
 export { scaffoldProject, adoptFolder, slugifyProjectName, escapeYamlScalar, } from "../lib/project-scaffold.ts";
 export type { ProjectTemplateId, ProjectVersionHistoryMode, CreateProjectOptions, CustomPageOptions, AdoptFolderOptions, CreateProjectResult, CreateProjectErrorCode, CreateProjectError, } from "../lib/project-scaffold.ts";
+export { scaffoldExtension, resolveExtensionPrefix, EXTENSION_KINDS, RESERVED_PREFIX, } from "../lib/extension-scaffold.ts";
+export type { ExtensionKind, ScaffoldExtensionOptions, ScaffoldExtensionResult, } from "../lib/extension-scaffold.ts";
 export { PRESET_IDS, PRESETS } from "../lib/presets.ts";
 export type { PresetId, VendorPreset } from "../lib/presets.ts";
 export { TARGETS, TARGET_IDS, publishTargetFor } from "../lib/targets.ts";
 export type { PublishTarget, TargetOverlay } from "../lib/targets.ts";
 export { listBuiltInTemplates, listCustomTemplates, saveProjectAsTemplate, importTemplateFromFolder, BUILT_IN_TEMPLATE_IDS, } from "../lib/project-templates.ts";
 export type { TemplateInfo, SaveProjectAsTemplateOptions, } from "../lib/project-templates.ts";
-export { extractVariables, substituteVariables, listSnippets, readSnippet, saveSnippet, deleteSnippet, SNIPPETS_DIR, } from "../lib/snippets.ts";
-export type { SnippetEntry } from "../lib/snippets.ts";
+export { extractVariables, substituteVariables, listSnippets, readSnippet, saveSnippet, deleteSnippet, listMergedSnippets, readExtensionSnippet, SNIPPETS_DIR, } from "../lib/snippets.ts";
+export type { SnippetEntry, SnippetSource } from "../lib/snippets.ts";
 export { listProjectPlugins, setPluginEnabled, addLocalPlugin, addNpmPlugin, validateProjectPlugins, RECOMMENDED_PLUGINS, PLUGINS_DIR, } from "../lib/plugin-manager.ts";
 export type { ProjectPluginEntry, PluginValidationResult, RecommendedPlugin, PluginKind, } from "../lib/plugin-manager.ts";
 export { listBuiltInThemes, resolveBuiltInTheme, listProjectThemes, getActiveTheme, applyTheme, importThemeFromFolder, importThemeFromUrl, readThemeCss, removeProjectTheme, getPreviousTheme, revertTheme, detectLegacyForkedTheme, BUILT_IN_THEME_IDS, THEMES_DIR, } from "../lib/theme-manager.ts";
 export type { ThemeInfo, ThemeMetadata, ResolvedTheme, ApplyThemeTarget, BuiltInThemeId, } from "../lib/theme-manager.ts";
 export { importThemeFromFile } from "../lib/theme-import.ts";
 export type { ThemeImportResult, ThemeImportWarning } from "../lib/theme-import.ts";
+export { EXTENSION_MANIFEST_FILENAME, LEGACY_THEME_MANIFEST_FILENAME, readExtensionMeta, extensionStyleList, extensionEngineStyleList, assertExtensionContained, pathEscapesFolder, resolveExtension, } from "../lib/extension-manifest.ts";
+export type { ExtensionMetadata, ResolvedExtension } from "../lib/extension-manifest.ts";
 export { listProjectStyles, resolveActiveStyles } from "../lib/style-resolver.ts";
 export type { ProjectStyle } from "../lib/style-resolver.ts";
 export { readManifestFields, setManifestFields, setActiveStyles, } from "../lib/manifest-config.ts";

package/dist/api/index.js

@@ -8,18 +8,22 @@ import {
   AUTO_SYNC_PUSH_INTERVAL_MINUTES,
   BUILT_IN_TEMPLATE_IDS,
   BUILT_IN_THEME_IDS,
+  EXTENSION_KINDS,
+  EXTENSION_MANIFEST_FILENAME,
   FileTokenStore,
   GDRIVE_HOST,
   GITHUB_HOST,
   GOOGLE_NOT_CONFIGURED_MESSAGE,
   GitHubAuthProvider,
   GoogleAuthProvider,
+  LEGACY_THEME_MANIFEST_FILENAME,
   MANIFEST_FILENAMES,
   PLUGINS_DIR,
   PRESETS,
   PRESET_IDS,
   PublishSelectionsStore,
   RECOMMENDED_PLUGINS,
+  RESERVED_PREFIX,
   SNIPPETS_DIR,
   SYNC_SNAPSHOT_MESSAGE,
   TARGETS,
@@ -29,6 +33,7 @@ import {
   addNpmPlugin,
   adoptFolder,
   applyTheme,
+  assertExtensionContained,
   autoSnapshotDelayMs,
   autoSyncDelayMs,
   cloneRepository,
@@ -41,6 +46,8 @@ import {
   diagnoseProjectRemote,
   disconnectPublishCredential,
   escapeYamlScalar,
+  extensionEngineStyleList,
+  extensionStyleList,
   extractUrlCredential,
   extractVariables,
   forgeKindForHost,
@@ -60,6 +67,7 @@ import {
   listCustomTemplates,
   listGitHubBranches,
   listGitHubRepositories,
+  listMergedSnippets,
   listProjectPlugins,
   listProjectStyles,
   listProjectThemes,
@@ -69,11 +77,14 @@ import {
   listSnippets,
   loadManifestWithPath,
   parseRemoteOrigin,
+  pathEscapesFolder,
   pkceChallengeFromVerifier,
   publishConnectionStatus,
   publishCredentialKey,
   publishProviderFor,
   publishTargetFor,
+  readExtensionMeta,
+  readExtensionSnippet,
   readManifestFields,
   readPublishSettings,
   readSnippet,
@@ -83,6 +94,8 @@ import {
   resolveActiveStyles,
   resolveBuiltInTheme,
   resolveConfig,
+  resolveExtension,
+  resolveExtensionPrefix,
   resolveGitHubClientId,
   resolveGoogleClientId,
   resolveGoogleClientSecret,
@@ -95,6 +108,7 @@ import {
   sanitizeCloneFolderName,
   saveProjectAsTemplate,
   saveSnippet,
+  scaffoldExtension,
   scaffoldProject,
   setActiveStyles,
   setManifestFields,
@@ -107,12 +121,12 @@ import {
   syncProject,
   testRemoteAccess,
   validateProjectPlugins
-} from "../index-9zf8mtk7.js";
+} from "../index-m00n6sz4.js";
 import {
   BuildError,
   DEFAULT_PRINT_OPTS,
   readyProbeExpr
-} from "../index-837htyjy.js";
+} from "../index-9pbaznww.js";
 import {
   AUTO_SNAPSHOT_MESSAGE,
   HISTORY_PAGE_LIMIT,
@@ -143,6 +157,7 @@ export {
   setManifestFields,
   setActiveStyles,
   scaffoldProject,
+  scaffoldExtension,
   saveSnippet,
   saveProjectAsTemplate,
   sanitizeCloneFolderName,
@@ -157,6 +172,8 @@ export {
   resolveGoogleClientSecret,
   resolveGoogleClientId,
   resolveGitHubClientId,
+  resolveExtensionPrefix,
+  resolveExtension,
   resolveConfig,
   resolveBuiltInTheme,
   resolveActiveStyles,
@@ -169,12 +186,15 @@ export {
   readSnippet,
   readPublishSettings,
   readManifestFields,
+  readExtensionSnippet,
+  readExtensionMeta,
   publishTargetFor,
   publishProviderFor,
   publishCredentialKey,
   publishConnectionStatus,
   providerFor,
   pkceChallengeFromVerifier,
+  pathEscapesFolder,
   parseRemoteOrigin,
   loadManifestWithPath,
   listSnippets,
@@ -184,6 +204,7 @@ export {
   listProjectThemes,
   listProjectStyles,
   listProjectPlugins,
+  listMergedSnippets,
   listGitHubRepositories,
   listGitHubBranches,
   listCustomTemplates,
@@ -205,6 +226,8 @@ export {
   findEnclosingRepoDir,
   extractVariables,
   extractUrlCredential,
+  extensionStyleList,
+  extensionEngineStyleList,
   escapeYamlScalar,
   disconnectPublishCredential,
   diagnoseProjectRemote,
@@ -219,6 +242,7 @@ export {
   capabilitiesFor,
   autoSyncDelayMs,
   autoSnapshotDelayMs,
+  assertExtensionContained,
   applyTheme,
   adoptFolder,
   addNpmPlugin,
@@ -229,12 +253,14 @@ export {
   SYNC_SNAPSHOT_MESSAGE,
   SNIPPETS_DIR,
   RESTORE_BACKUP_MESSAGE,
+  RESERVED_PREFIX,
   RECOMMENDED_PLUGINS,
   PublishSelectionsStore,
   PRESET_IDS,
   PRESETS,
   PLUGINS_DIR,
   MANIFEST_FILENAMES,
+  LEGACY_THEME_MANIFEST_FILENAME,
   HISTORY_PAGE_LIMIT,
   GoogleAuthProvider,
   GitHubAuthProvider,
@@ -242,6 +268,8 @@ export {
   GITHUB_HOST,
   GDRIVE_HOST,
   FileTokenStore,
+  EXTENSION_MANIFEST_FILENAME,
+  EXTENSION_KINDS,
   DEFAULT_PRINT_OPTS,
   BuildError,
   BUILT_IN_THEME_IDS,

package/dist/{audit-82jr4qhw.js → audit-ckbmgzpk.js}

@@ -1,15 +1,15 @@
 import {
   executeAndReport
-} from "./cli-w6h5zegm.js";
+} from "./cli-wvw2msvn.js";
 import {
   log
-} from "./cli-mk1s46mx.js";
+} from "./cli-pw6z15yv.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-08psmhr5.js";
-import"./cli-s8q42x3r.js";
+} from "./cli-v1ma3v2s.js";
+import"./cli-4vtgt2ng.js";
 import"./cli-c41yr7he.js";
 import {
   EXIT_CODES