gutterpress 0.11.23-alpha.1 → 0.11.23-alpha.3

package/README.md

@@ -143,19 +143,19 @@ source.
 
 ### `gutterpress new`
 
-Scaffold a new book, plugin or theme from an embedded starter template — the fastest way to start (see [Quick start](#quick-start)).
+Scaffold a new book, plugin or look 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 book` is the default. Every new book has the preset it's designed for, the template's unless you choose: `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 `package.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.
+`--kind plugin` and `--kind look` scaffold an **extension package** instead — a folder with a `package.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 look 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> [--kind <id>] [options]
 
-  --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)
+  --kind <id>              What to create: book (default), plugin, look
+  --prefix <str>           Class/custom-property prefix an extension claims (default: its slug, e.g. "field-notes-"); --kind plugin|look only
+  --description <text>     One-line description recorded in the extension's metadata; --kind plugin|look only
+  --preset <id>            Preset the book is designed for: dtrpg, book, custom (default: the template's)
   --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)
@@ -363,7 +363,7 @@ List, add, remove, enable, or disable the project's extensions. Markdown-it
 plugins, looks (stylesheets) and component libraries are all extensions — one
 `extensions:` list in `manifest.yaml`, in load order (see
 [Extensions](#extensions) below). These are the same shared-lib functions the
-desktop app's Look and Features views call, so an extension added from the
+desktop app's Extensions tab calls, so an extension added from the
 terminal is the same entry the GUI shows.
 
 ```sh
@@ -392,32 +392,32 @@ Add an extension. What `SOURCE` is decides what happens:
 
 - an **npm package** (`name` or `name@version`) is downloaded straight from
   the registry along with its runtime dependencies, hash-verified, vendored
-  into the project under `plugins/npm/`, load-tested, and written back pinned
+  into the project under `extensions/npm/`, load-tested, and written back pinned
   as `name@<exact version>`. This does not invoke npm, Bun, Node.js tooling,
   or package install scripts;
-- a **bundled feature** (`markdown-it-mark`, `markdown-it-sub`,
-  `markdown-it-sup`, `markdown-it-abbr`, `gutterpress-gfm-alerts`,
-  `gutterpress-math`) is simply listed — nothing to install, works offline;
+- a **bundled name** — a markdown feature (`markdown-it-mark`,
+  `markdown-it-sub`, `markdown-it-sup`, `markdown-it-abbr`,
+  `gutterpress-gfm-alerts`, `gutterpress-math`) or a built-in look
+  (`clean-book`, `zine`, `technical-doc`, `academic`) — is simply listed:
+  nothing to install, works offline;
 - a **folder or plugin-file path** is load-tested and listed as a
   manifest-relative path, referenced in place — never copied;
 - a **`.zip` or `.css` file**, or an **http(s) URL**, is validated (every
   declared sheet must exist and parse; print-safety findings are warnings)
-  and landed in `extensions/<id>/`, then listed as `./extensions/<id>`;
-- with `--look`, `SOURCE` is a built-in look id, copied into
-  `extensions/<id>/` as the author's own editable files and listed.
+  and landed in `extensions/<id>/`, then listed as `./extensions/<id>`.
 
 Adding something already listed re-pins or updates that entry instead of
 adding a second one.
 
-An npm install also makes sure the book's `.gitignore` ignores `plugins/npm/`
-(append-only; an author's own `!plugins/npm/` re-include is respected and the
+An npm install also makes sure the book's `.gitignore` ignores `extensions/npm/`
+(append-only; an author's own `!extensions/npm/` re-include is respected and the
 install warns that downloaded extensions shouldn't be committed). The manifest
 pin is what travels with the book; the downloaded copy does not.
 
 ##### Restoring pinned extensions
 
 A fresh clone has `manifest.yaml`'s `name@version` pins but not the downloaded
-copies under `plugins/npm/`. `build`, `validate`, `preflight` and `preview`
+copies under `extensions/npm/`. `build`, `validate`, `preflight` and `preview`
 download any missing (or incomplete) pinned version before they load plugins —
 exactly the pinned version, through the same registry-resolved, hash-verified,
 load-tested install as `ext add`, without touching the manifest. Builds and
@@ -429,7 +429,7 @@ paths and bundled features are never touched. The plugin loader itself stays
 offline. The desktop app does the same when it opens a book.
 
 Once a package's pinned version is installed (by `ext add` or a restore), its
-other downloaded versions under `plugins/npm/<name>/` are deleted — a cache
+other downloaded versions under `extensions/npm/<name>/` are deleted — a cache
 that a pulled pin or branch switch would otherwise leave to pile up — except a
 version another enabled manifest entry still pins. A failed install removes the
 folders it created and nothing else.
@@ -438,7 +438,6 @@ folders it created and nothing else.
 gutterpress ext add <source> [dir] [options]
 
   --export <name>    Named module export to use as the plugin function (npm and path extensions only)
-  --look             Treat SOURCE as a built-in look id (clean-book, zine, technical-doc, academic): copy it into extensions/ and add it
 ```
 
 ```sh
@@ -447,7 +446,7 @@ gutterpress ext add markdown-it-highlightjs@4.3.0 ./my-book
 gutterpress ext add markdown-it-emoji@3.0.0 ./my-book --export full
 gutterpress ext add markdown-it-mark ./my-book
 gutterpress ext add ./plugins/field-notes ./my-book
-gutterpress ext add zine ./my-book --look
+gutterpress ext add zine ./my-book
 gutterpress ext add ./parchment.zip ./my-book
 gutterpress ext add https://example.com/looks/cool/ ./my-book
 ```
@@ -456,12 +455,12 @@ gutterpress ext add https://example.com/looks/cool/ ./my-book
 
 Remove an extension from the manifest, by the specifier as written there (for
 an npm package the bare name is enough). An npm extension's vendored copy
-under `plugins/npm/` is deleted too; a path extension's folder is yours and is
+under `extensions/npm/` is deleted too; a path extension's folder is yours and is
 never touched.
 
 ```sh
 gutterpress ext remove markdown-it-highlightjs ./my-book
-gutterpress ext remove ./extensions/zine ./my-book
+gutterpress ext remove zine ./my-book
 ```
 
 #### `gutterpress ext enable` / `gutterpress ext disable`
@@ -476,8 +475,8 @@ gutterpress ext enable markdown-it-mark ./my-book
 
 #### `gutterpress ext search`
 
-Search **npm** for extensions — the same list the desktop app's Features view
-shows under "Find more on npm." Not project-scoped (no `dir` argument): it
+Search **npm** for extensions — the same list the desktop app's Extensions tab
+shows under *Search*. Not project-scoped (no `dir` argument): it
 queries the registry for packages tagged `gutterpress` (Gutterpress
 extensions: plugins, looks, component libraries) or `markdown-it-plugin` (the
 markdown-it ecosystem's own tag — those work in Gutterpress unchanged), and
@@ -522,7 +521,7 @@ extensions:
   # a feature bundled with Gutterpress — nothing to install, works offline
   - markdown-it-mark
   # a folder or plugin file, relative to manifest.yaml — referenced in place
-  - ./extensions/clean-book
+  - ./extensions/house-look
   - ./plugins/my-custom-plugin.js
   # an npm package, pinned to the exact version `gutterpress ext add` installed
   - markdown-it-highlightjs@4.3.0
@@ -548,8 +547,7 @@ An extension folder (or npm package) describes itself in its **`package.json`**
   "gutterpress": {
     "styles": ["styles/plugin.css"],
     "snippets": "snippets",
-    "components": "components.yaml",
-    "tokensFile": "styles/tokens.css"
+    "components": "components.yaml"
   }
 }
 ```
@@ -558,7 +556,7 @@ An extension folder (or npm package) describes itself in its **`package.json`**
 
 Order is load order: a later entry's markdown runs after earlier entries' (and sees their output) and its CSS wins ties — each extension's stylesheets are wrapped in their own cascade layer (`@layer ext.<name>`), declared in list order, so this holds however an extension writes its CSS; the project's own `styles:` stay unlayered and load after every extension, beating all of them at any specificity. There is no `priority` and no `path:`/`name:` wrapper — a manifest still carrying `plugins:` fails with a message that prints the same entries rewritten as `extensions:`. The `engine:` and `engineStyles:` keys are gone too (there is one engine; move any `engineStyles` entries to the end of `styles:`).
 
-Pinned npm packages and their runtime dependencies live under `plugins/npm/`
+Pinned npm packages and their runtime dependencies live under `extensions/npm/`
 as a plain nested `node_modules` tree, which Node's own module resolution loads.
 The pin travels with the project; the downloaded copy is gitignored, and
 `build`, `validate`, `preflight` and `preview` download a missing pinned version first

package/dist/{README-8ef336pp.md → README-8db7btxb.md}

@@ -17,7 +17,7 @@ arrangement of the files is the part worth keeping.
     ├── 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.
+    ├── page-rules.css        @page margin boxes, running heads, named pages.
     └── book.css              this book's overrides. Loads last.
 ```
 
@@ -64,7 +64,7 @@ instantly: **where does this rule go?**
 | 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` |
+| folios, running heads, named pages | `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.
@@ -156,23 +156,17 @@ 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.
+### 4. The page size and margins are the book's, not the look's
+
+A look never declares `@page { size }` or `@page { margin }`. The book's
+manifest records both (`preset:`, `page: width / height / margin`, which the
+app edits under Setup > Details), and the build writes them as the `@page`
+rule after every stylesheet, so a `size` in a look is ignored and reported by
+the print-safety check, and a `margin` holds only until the author sets
+margins in the app. `page-rules.css` owns what IS a look's: the margin boxes
+(folios, running heads) and the named pages. Design them to sit in whatever
+margin the book gives them — a folio at `@bottom-right` needs no particular
+margin to work.
 
 ### 5. Keep the catalog honest
 

package/dist/api/index.d.ts

@@ -34,10 +34,10 @@ export { listBuiltInTemplates, listCustomTemplates, saveProjectAsTemplate, impor
 export type { TemplateInfo, SaveProjectAsTemplateOptions, } from "../lib/project-templates.ts";
 export { extractVariables, substituteVariables, listSnippets, saveSnippet, deleteSnippet, listMergedSnippets, listMarkerComponents, listLocationVariants, SNIPPETS_DIR, } from "../lib/snippets.ts";
 export type { LocationVariant, MarkerComponent, SnippetEntry, SnippetSource } from "../lib/snippets.ts";
-export { listProjectExtensions, describeExtension, addExtension, checkExtensionUpdates, listNpmVersions, updateExtensions, removeExtension, setExtensionEnabled, reorderExtensions, validateProjectExtensions, readExtensionCss, listBuiltInStyleSets, addBuiltInStyleSet, sameExtension, RECOMMENDED_EXTENSIONS, BUILT_IN_STYLE_SET_IDS, EXTENSIONS_DIR, PLUGINS_DIR, } from "../lib/extension-manager.ts";
-export type { ProjectExtensionEntry, ExtensionValidationResult, RecommendedExtension, ExtensionSourceKind, BuiltInStyleSet, BuiltInStyleSetId, AddExtensionOptions, ExtensionUpdateCheck, ExtensionUpdateResult, CheckExtensionUpdatesOptions, UpdateExtensionsOptions, } from "../lib/extension-manager.ts";
-export { BUNDLED_EXTENSIONS, isBundledExtension, isPathSpecifier, parseExtensionSpecifier, } from "../lib/extension-specifier.ts";
-export type { ParsedExtensionSpecifier } from "../lib/extension-specifier.ts";
+export { listProjectExtensions, describeExtension, addExtension, checkExtensionUpdates, listNpmVersions, updateExtensions, removeExtension, setExtensionEnabled, reorderExtensions, validateProjectExtensions, readExtensionCss, listBundledExtensions, sameExtension, EXTENSIONS_DIR, } from "../lib/extension-manager.ts";
+export type { ProjectExtensionEntry, ExtensionValidationResult, BundledExtensionInfo, ExtensionSourceKind, AddExtensionOptions, ExtensionUpdateCheck, ExtensionUpdateResult, CheckExtensionUpdatesOptions, UpdateExtensionsOptions, } from "../lib/extension-manager.ts";
+export { BUNDLED_EXTENSIONS, bundledExtension, isBundledExtension, isPathSpecifier, parseExtensionSpecifier, } from "../lib/extension-specifier.ts";
+export type { BundledExtension, ParsedExtensionSpecifier } from "../lib/extension-specifier.ts";
 export { restorePinnedExtensions, restoreFailureMessage } from "../lib/extension-restore.ts";
 export type { RestorePinnedOptions, RestoreResult, RestoreFailure, RestoreProgress } from "../lib/extension-restore.ts";
 export { importExtensionFromFile, importExtensionFromUrl } from "../lib/extension-import.ts";
@@ -52,7 +52,7 @@ export type { ProjectStyle } from "../lib/style-resolver.ts";
 export { readManifestFields, setManifestFields, setActiveStyles, } from "../lib/manifest-config.ts";
 export type { ProjectConfigFields } from "../lib/manifest-config.ts";
 export { readPageSetup, setPageSetup } from "../lib/page-size.ts";
-export type { PageSetup, PageSizeChoice, PageSizePoints } from "../lib/page-size.ts";
+export type { PageMargin, PageSetup, PageSetupChange, PageSizeChoice, PageSizePoints } from "../lib/page-size.ts";
 export { providerFor, restoreVersionWithBackup, isNoChangesError, countUnversionedChanges, whenGitIdle, AUTO_SNAPSHOT_MESSAGE, RESTORE_BACKUP_MESSAGE, HISTORY_PAGE_LIMIT, listLocalBranches, switchBranch, SWITCH_BRANCH_SNAPSHOT_MESSAGE, } from "../lib/source-provider.ts";
 export type { ListHistoryOptions, HistoryPage, UnversionedChanges, LocalBranches, SwitchBranchOptions, SwitchBranchResult, } from "../lib/source-provider.ts";
 export { describeVersions, listOnlineVersions, compareVersionFile, exportVersionTree, VERSION_CHANGES_SHOWN, } from "../lib/version-changes.ts";

package/dist/api/index.js

@@ -101,32 +101,24 @@ import {
   substituteVariables,
   syncProject,
   testRemoteAccess
-} from "../index-zrhyb967.js";
+} from "../index-prqvz3xm.js";
 import {
-  BUILT_IN_STYLE_SET_IDS,
-  BUNDLED_EXTENSIONS,
   DEFAULT_NPM_REGISTRY,
-  EXTENSIONS_DIR,
   MANIFEST_FILENAMES,
   PRESETS,
   PRESET_IDS,
-  RECOMMENDED_EXTENSIONS,
   TARGETS,
   TARGET_IDS,
-  addBuiltInStyleSet,
   addExtension,
   checkExtensionUpdates,
   describeExtension,
   ensureProjectGitignore,
   hasProjectManifest,
-  isBundledExtension,
-  isPathSpecifier,
-  listBuiltInStyleSets,
+  listBundledExtensions,
   listNpmVersions,
   listProjectExtensions,
   loadManifestWithPath,
   npmRegistryUrl,
-  parseExtensionSpecifier,
   publishTargetFor,
   readExtensionCss,
   removeExtension,
@@ -138,22 +130,27 @@ import {
   setExtensionEnabled,
   updateExtensions,
   validateProjectExtensions
-} from "../index-m4hhzg3c.js";
+} from "../index-7pck1q9c.js";
 import {
+  BUNDLED_EXTENSIONS,
   EXTENSION_MANIFEST_FILENAME,
   assertExtensionContained,
+  bundledExtension,
   extensionCarries,
   extensionEntry,
   extensionStyleList,
+  isBundledExtension,
+  isPathSpecifier,
+  parseExtensionSpecifier,
   pathEscapesFolder,
   readExtensionMeta,
   resolveExtension
-} from "../index-2jpk25en.js";
+} from "../index-0wee4408.js";
 import"../index-ht1bcqdd.js";
-import"../index-apc8w9w8.js";
+import"../index-nedd07bk.js";
 import {
   BuildError
-} from "../index-dsvk7q6s.js";
+} from "../index-46ycxe6r.js";
 import"../index-2ppw6q9v.js";
 import {
   DEFAULT_PRINT_OPTS,
@@ -173,10 +170,10 @@ import {
   restoreVersionWithBackup,
   switchBranch,
   whenGitIdle
-} from "../index-93pqkvty.js";
+} from "../index-h6yk5tjx.js";
 import {
-  PLUGINS_DIR
-} from "../index-r7jcsk6h.js";
+  EXTENSIONS_DIR
+} from "../index-5x42amh8.js";
 import {
   capabilitiesFor,
   detectProjectSource,
@@ -266,8 +263,8 @@ export {
   listGitHubRepositories,
   listGitHubBranches,
   listCustomTemplates,
+  listBundledExtensions,
   listBuiltInTemplates,
-  listBuiltInStyleSets,
   listBookPublishProviders,
   knownForgeTokenUrl,
   isValidRepositoryName,
@@ -307,13 +304,13 @@ export {
   checkRemoteUpdates,
   checkExtensionUpdates,
   capabilitiesFor,
+  bundledExtension,
   autoSyncDelayMs,
   autoSnapshotDelayMs,
   assertMilestone,
   assertExtensionContained,
   adoptFolder,
   addExtension,
-  addBuiltInStyleSet,
   VERSION_CHANGES_SHOWN,
   TARGET_IDS,
   TARGETS,
@@ -324,11 +321,9 @@ export {
   RESTORE_BACKUP_MESSAGE,
   RESERVED_PREFIX,
   REPAIR_SNAPSHOT_MESSAGE,
-  RECOMMENDED_EXTENSIONS,
   PublishSelectionsStore,
   PRESET_IDS,
   PRESETS,
-  PLUGINS_DIR,
   MAX_SEARCH_BYTES,
   MANIFEST_FILENAMES,
   HISTORY_PAGE_LIMIT,
@@ -346,7 +341,6 @@ export {
   BuildError,
   BUNDLED_EXTENSIONS,
   BUILT_IN_TEMPLATE_IDS,
-  BUILT_IN_STYLE_SET_IDS,
   AUTO_SYNC_PUSH_INTERVAL_MINUTES,
   AUTO_SYNC_MIN_MINUTES,
   AUTO_SYNC_MAX_MINUTES,

package/dist/{build-09cd1n7s.js → build-m78jcpf7.js}

@@ -1,20 +1,20 @@
 import {
   runBuild,
   splitOutPath
-} from "./cli-5hkmp2wy.js";
-import"./cli-ccp7sxz3.js";
+} from "./cli-1h17ktsg.js";
+import"./cli-n2tsxqpn.js";
 import"./cli-ht1bcqdd.js";
-import"./cli-dtckwda1.js";
+import"./cli-xsrffqzt.js";
 import"./cli-2ppw6q9v.js";
 import"./cli-eyyggect.js";
 import"./cli-asap4t1z.js";
-import"./cli-habkc5ng.js";
+import"./cli-a35w7wzg.js";
 import"./cli-v5mp7a6q.js";
-import"./cli-dd115fa8.js";
-import"./cli-h17e3mtz.js";
+import"./cli-h4x81x97.js";
+import"./cli-t8be9yeb.js";
 import {
   log
-} from "./cli-b0vyjvmt.js";
+} from "./cli-s6djx4ma.js";
 import {
   UsageError,
   parseFormat,
@@ -22,12 +22,11 @@ import {
   rejectExtraPositionals,
   rejectUnknownFlags
 } from "./cli-d8xjns66.js";
-import"./cli-nr6j6300.js";
-import"./cli-fe43evmf.js";
+import"./cli-5jzyw06s.js";
 import {
   BuildError
 } from "./cli-46ycxe6r.js";
-import"./cli-h3phdstf.js";
+import"./cli-y28j019d.js";
 import"./cli-37x76zdn.js";
 
 // src/commands/build.ts