gp-dimm-city 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog
+
+All notable changes to gp-dimm-city are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/) and the project uses
+[Semantic Versioning](https://semver.org/). The release workflow refuses to
+cut a version that has no `## [X.Y.Z]` heading below.
+
+## [Unreleased]
+
+## [1.0.0] - unreleased
+
+First release as a standalone package. Extracted from the private
+`dimm-city/dc-op-manual` repository, where it lived at `dc-design-guide/` as a
+folder extension that the Dimm City books referenced by relative path. The
+design guide *book* stays in that repository and now consumes this package
+exactly like any other book.
+
+### Added
+
+- **Installable from npm.** `gutterpress ext add gp-dimm-city` vendors the
+  package under a book's `plugins/npm/` and pins the exact version — no Node
+  packages in the book repo. `"type": "module"` in `package.json`, which the
+  old folder package lacked: Gutterpress's npm loader parses a `.js` entry as
+  CommonJS without it and refuses the plugin.
+- **The brick-wall tile ships.** `dc-native.css` paints the page background
+  from `images/brick-bg-01.png`; the old package's `files` list never included
+  it, so a published copy would have failed every build with a missing asset.
+  `test/package.test.js` now follows every `url()` in every stylesheet into
+  the tarball.
+- **Font licences.** Titillium Web and Tomorrow ship with the OFL 1.1 text
+  from their upstream repositories beside the files; Lixdu ships with its own
+  licence file. Fonts are grouped per family under `fonts/` with readable
+  names instead of export UUIDs (byte-identical; fonts inline at build time,
+  so the rename cannot change a page).
+- **Snippets** for the desktop app's snippet picker: every macro an author
+  reaches for (`@skill`, `@learning-path`, `@specialty`, `@callout`, `@card`,
+  `@gear`, `@block`, `@outcome`, alerts, …) and the three front-matter pages
+  every Dimm City book writes (contents, credits, chapter start).
+- **Tests** (`bun test`): a fixture snapshot of every macro's output, the
+  behavioural tests carried over from the book repo, and package checks —
+  every declared path and every stylesheet asset in the tarball, one licence
+  per font directory, the cascade contract below, and no runtime imports.
+- **CI and release workflows**: tests on every push and PR; a manual release
+  workflow that bumps, tags, publishes to npm with provenance via OIDC
+  trusted publishing, and cuts the GitHub release.
+
+### Changed
+
+- **`css/` is `styles/`**, matching Gutterpress's extension template. Same
+  sixteen sheets in the same cascade order; `tokensFile` now points at
+  `styles/dc-palette.css` (the brand palette) rather than the specialty
+  identity tokens.
+- **The layer statement is `@layer dc.tokens, dc.base, dc.components,
+  dc.templates, dc.pages, book;`** — `dc.guide` is gone. A book's own sheets
+  belong in `@layer book`, the last layer, which outranks every `dc.*` layer;
+  a book that must beat the unlayered `dc-native.css` lists an unlayered sheet
+  after the extension. (`dc.guide` existed for the design guide's own
+  scaffolding; that book now uses `book` like everyone else.)
+- **Front-matter chrome moved in from the books.** The contents-page rows,
+  credits role labels and prose, and chapter-start heading rules that lived
+  in the design guide's sheet (`dg-overrides.css`, layer `dc.guide`) and the
+  credits-page flex layout from the field guide's native sheet are now in
+  `page-templates.css` and `dc-native.css`: every Dimm City book writes these
+  pages. Values are carried as rendered. Two rules that only ever lost to
+  them by layer order were reconciled so nothing changes on the page: the
+  dead magenta TOC-divider rule (`page-templates.css`) is removed, and the
+  credits role-label colour now says `--ink`, which is what it always
+  rendered.
+- **Specialty break control moved in from the field guide**: `.dc-specialty
+  .dc-learning-path { break-before: always }` and the `.dc-allow-split`
+  escape, in `page-templates.css`.
+- Plugin `metadata` no longer carries its own `version` (17.3.0 in the book
+  repo); `package.json` is the only version. Its `name` is now "Dimm City".
+- Stale comments across the stylesheets and plugin that named files from the
+  book repo (`dc-components.css`, `native-furniture.css`, `dc-tokens.css`,
+  `engineStyles`, `fg-overrides.css`, `dg-overrides.css`, `index.css`) now
+  name the package's own files or "the book's own sheet".
+
+### Removed
+
+- `index.css` (an `@import` entry point that reached into the field guide's
+  folder) and `dg-overrides.css` (design-guide-only scaffolding, now that
+  book's own sheet) are not part of the package.
+- The catalog entries `palette-swatch` and `table`, and the `ignore:` block —
+  all design-guide-only.
+- The `dimm-city-components` package name.

package/LICENSE

@@ -0,0 +1,32 @@
+MIT License
+
+Copyright (c) 2026 Dimm City
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This licence covers the plugin code, stylesheets, catalog and documentation in
+this package. It does not cover:
+
+- The fonts under `fonts/`, which carry their own licences beside the font
+  files (`fonts/titillium-web/OFL.txt`, `fonts/tomorrow/OFL.txt`,
+  `fonts/lixdu/LICENSE.txt`).
+- The Dimm City name, logo, artwork and game text, which remain the property
+  of their owners and are not licensed by this package.

package/README.md

@@ -0,0 +1,165 @@
+# gp-dimm-city
+
+The Dimm City design system for [Gutterpress](https://github.com/dimm-city/gutterpress):
+the markdown-it macros, print stylesheets, design tokens, fonts and page
+templates that the Dimm City TTRPG books are set in. Install it into a book
+and write `@skill`, `@specialty`, `@learning-path`, `@callout` and the rest;
+the package renders them and prints them.
+
+## Install
+
+**In the Gutterpress app:** open the book, then Project settings → Features →
+*Find more on npm* (search "dimm city") or *Install from npm* and enter
+`gp-dimm-city`. Confirm the install prompt. The package appears under Features
+with a "+ look" badge, and its sheets and snippets are live in the preview.
+
+**From the command line**, in the folder that holds the book:
+
+```sh
+gutterpress ext add gp-dimm-city my-book
+```
+
+Either way Gutterpress downloads the package from npm, verifies the registry
+hash, writes a copy under `my-book/plugins/npm/`, and pins the exact version
+in the manifest:
+
+```yaml
+extensions:
+  - gp-dimm-city@1.0.0
+```
+
+**Commit `plugins/npm/`.** Builds never fetch from the registry; the vendored
+copy is what builds your book, on every machine and in CI. If your repo
+ignores `node_modules`, add `!**/plugins/npm/**` as the last line of
+`.gitignore` — the vendored tree has a `node_modules` folder inside it — and
+`**/plugins/npm/** -text` to `.gitattributes`, because the copy is verified
+byte for byte on every build.
+
+`gutterpress ext list my-book` shows `gp-dimm-city@1.0.0 [npm; markdown, styles, components, snippets]`.
+
+## What you get
+
+- **Macros**, from `plugin.js`: `@specialty` / `@specialty-intro` /
+  `@specialty-art` / `@specialty-card`, `@learning-path`, `@skill` (with
+  `@continue` for a card that spans a page break), `@outcome`, `@callout`,
+  `@dm-note`, `@sidebar`, `@sidebar-box`, `@block`, `@card`, `@gear`,
+  `@definition`, `@procedure`, `@lede`, `@toc`, `@tape`, `@glossary`, GFM
+  alerts (`> [!NOTE]`, `[!WARNING]`, `[!DM]`, `[!VIBE]`, `[!ORIGIN]`,
+  `[!VISIT]`, `[!GEAR]`, `[!FLAVOR]`, `[!PULLQUOTE]`), and the automatic
+  `ROLL THE DIE!` chip. `docs/macros.md` is the inventory;
+  `docs/components-and-palette-reference.md` maps each to the classes it
+  emits.
+- **Sixteen stylesheets** under `styles/`, listed in `package.json` in
+  cascade order: fonts and the layer statement, the palette and identity
+  tokens, the element baseline, eight component sheets, page templates,
+  paged-media rules, and `dc-native.css` — the engine-specific page chrome
+  (brick-wall background, folios, chapter chips) that must stay last.
+- **Fonts**: Titillium Web, Tomorrow and Lixdu, embedded into the PDF at
+  build time.
+- **Page templates** every Dimm City book writes: `.page-toc`,
+  `.page-credits .dc-credits`, `.page-chapter-start .dc-chapter-start`,
+  `.dc-full-page`, plus the folio/chapter-chip chrome driven by
+  `@chapter #id ch="N"`.
+- **Snippets** for the app's snippet picker (`snippets/`): one per macro and
+  one per front-matter page, with placeholders for the parts you fill in.
+- **`components.yaml`**: the catalog of every component — what you write,
+  what lands in the HTML, which tokens are public, which sheet owns it.
+
+## Quick start
+
+```sh
+gutterpress new "My Book" --preset dtrpg
+gutterpress ext remove ./extensions/clean-book my-book && rm -r my-book/extensions
+gutterpress ext add gp-dimm-city my-book
+gutterpress preview my-book
+```
+
+The second line matters. `gutterpress new` gives every book a starter look
+(`./extensions/clean-book`), and a look's CSS is unlayered, so it beats this
+package's layered rules on anything the look styles — plain prose comes out in
+the starter's serif instead of Titillium Web. This package *is* the look;
+remove the starter before adding it. (In the app: Project settings → Look →
+remove *Clean book*.)
+
+Then insert the *Toc Page*, *Credits Page* and *Chapter Start Page* snippets
+to lay down the front matter, and reach for *Skill*, *Learning Path* and
+*Specialty* as you write. `page-rules.css` sets a Letter page with bleed; keep
+the manifest's `page:` in step with it.
+
+## Your own CSS: the layer convention
+
+List your sheets under `styles:` in the manifest. Extension styles always load
+first, so yours come after. Wrap them in the `book` layer:
+
+```css
+@layer book {
+  #chapter-03 { --dc-section-accent: var(--hud-magenta); }
+}
+```
+
+The package declares `@layer dc.tokens, dc.base, dc.components, dc.templates,
+dc.pages, book;` in its first sheet. `book` is last, so anything you put there
+outranks every `dc.*` rule without a specificity contest. Two things to know:
+
+- `dc-native.css` is deliberately **unlayered** so it beats every layered rule
+  — a book that must override it lists an **unlayered** sheet after the
+  extension; the last unlayered sheet wins.
+- Do not invent layer names. A layer the package's statement does not name is
+  created where it is first used, which puts it *after* `book` and silently
+  above your own overrides.
+
+Never write bare `.dc-*` rules in a book to change a component; that fights
+the package on every update. Reset the component's public tokens on a context
+selector instead:
+
+```css
+@layer book {
+  .chapter-05 .dc-alert { --dc-alert-accent: var(--hud-blue); }
+}
+```
+
+The tokens each component exposes are listed under `tokens:` in
+`components.yaml`, and `styles/dc-component-defaults.css` is where their
+defaults live.
+
+## Versioning
+
+Books pin an exact version, so nothing changes under you. To move a book to a
+new release:
+
+```sh
+gutterpress ext add gp-dimm-city@1.1.0 my-book
+git rm -r my-book/plugins/npm/gp-dimm-city/1.0.0   # ext add leaves the old copy in place
+```
+
+Rebuild and compare before you commit — the Dimm City books gate every bump
+with a render-parity run (text runs, image placement, and a pixel comparison
+of every page). Public API for semver purposes: the macro vocabulary, the
+classes and tokens marked `live` in `components.yaml`, the page templates, and
+the layer names. `CHANGELOG.md` lists what each release changes.
+
+## Licences
+
+Code, stylesheets, catalog and docs: [MIT](LICENSE). Fonts carry their own
+licences beside the files — `fonts/titillium-web/OFL.txt`,
+`fonts/tomorrow/OFL.txt`, `fonts/lixdu/LICENSE.txt`. The Dimm City name, logo,
+artwork and game text are not licensed by this package.
+
+## Development
+
+```sh
+bun install
+bun test                     # snapshot, behaviour, package and convention tests
+bun run test:update-snapshot # only when the plugin's output is meant to change
+bun run pack:check           # what npm would publish
+```
+
+`plugin.js` imports nothing at runtime — `gutterpress/render` is a
+devDependency used only by the tests to run the plugin inside core's markdown
+pipeline. Releases are cut from the *Release* workflow (version in, npm and
+GitHub release out); it refuses a version with no `## [X.Y.Z]` heading in
+`CHANGELOG.md`.
+
+The design guide that documents this system in depth is a book in the
+`dimm-city/dc-op-manual` repository. Issues about the package — a macro, a
+sheet, a token, a font — belong here.