@pagenary/publisher 2026.6.8 → 2026.6.10

package/README.md

@@ -272,6 +272,23 @@ npm run lint:content                 # check trailing whitespace/tabs
 npm run check:seo                    # verify SEO metadata
 npm run check                        # run all checks
 npm test                             # run test suite
+npm run test:browser                 # optional real-browser smoke (see below)
+```
+
+### Browser smoke test (optional)
+
+`npm run test:browser` runs `scripts/smoke-browser.mjs`, a real-browser check for
+things the jest/node suite can't cover: `<base href>` resolution under a subpath
+mount, asset + section loading, the runtime `<title>` brand, and Fortemi
+command-palette search. It builds + serves the `pagenary` tenant and drives a
+headless Chromium, capturing a screenshot for review.
+
+Playwright is **not** a dependency (keeps the install lean); the script skips with
+instructions when it's absent. Enable it once:
+
+```bash
+npm i -D playwright && npx playwright install chromium
+SMOKE_REQUIRE=1 npm run test:browser   # fail (not skip) if Playwright is missing — use in CI
 ```
 
 ---
@@ -363,6 +380,7 @@ The full documentation site is published at **[docs.pagenary.com](https://docs.p
 - [Quick Start Guide](docs/QUICKSTART.md) — step-by-step tenant creation
 - [Publish with GitHub/Gitea Actions](docs/PUBLISHING.md) — make any docs repo Pagenary-ready: copy-paste CI workflows + auto-discovery
 - [Tenant Configuration](docs/TENANT-CONFIG.md) — all config options (branding, theme, SEO)
+- [Theming Recipes](docs/THEMING-RECIPES.md) — copy-paste recipes for colors, fonts, and nav positions, with screenshots
 - [Architecture](docs/ARCHITECTURE.md) — system design
 - [API Reference](docs/API.md) — module documentation
 - [Deployment](docs/DEPLOYMENT.md) — hosting patterns

package/examples/content-base/config.json

@@ -0,0 +1,7 @@
+{
+  "title": "Pagenary Examples",
+  "brandMark": "Pagenary",
+  "brandSub": "Examples",
+  "description": "Shared sample docs used by the Pagenary theming recipe gallery.",
+  "tagline": "One small docs set, many looks — driven entirely by config."
+}

package/examples/content-base/content/buttons.md

@@ -0,0 +1,18 @@
+# Buttons
+
+Buttons trigger actions. Keep labels short and specific — prefer "Save changes"
+over "Submit".
+
+## Variants
+
+- **Primary** — the main action on a view. One per screen.
+- **Ghost** — secondary actions that shouldn't compete for attention.
+- **Danger** — destructive actions; pair with a confirmation step.
+
+## States
+
+Every button has resting, hover, focus, and disabled states. Focus styles are
+not optional — they're how keyboard users navigate.
+
+> Tip: a disabled button should explain *why* it's disabled nearby, or users
+> will assume the page is broken.

package/examples/content-base/content/changelog.md

@@ -0,0 +1,14 @@
+# Changelog
+
+A changelog is documentation too. Keep entries short and write them for the
+reader, not the committer.
+
+## Unreleased
+
+- Added the theming recipe gallery.
+- Introduced `top`, `bottom`, and `hybrid` navigation positions.
+
+## Earlier
+
+- Color presets: `light`, `dark`, `matrix`.
+- Per-tenant fonts and branding via `config.json`.

package/examples/content-base/content/configure.md

@@ -0,0 +1,25 @@
+# Configure
+
+All customization lives in a tenant `config.json`. The keys you'll reach for most:
+
+| Key | What it controls |
+| --- | --- |
+| `accentColor` | The primary accent used across links and highlights |
+| `theme` | A preset (`light`, `dark`, `matrix`) or a custom color object |
+| `fontBody` / `fontMono` | Typography for prose and code |
+| `navPosition` | Where navigation sits: `left`, `right`, `top`, `bottom`, `hybrid` |
+| `brandMark` / `brandSub` | The two-part wordmark in the header |
+
+Change one key, rebuild, and the whole site follows. No template forks, no CSS
+surgery.
+
+## Example
+
+```json
+{
+  "brandMark": "Acme",
+  "brandSub": "Docs",
+  "accentColor": "#2563eb",
+  "navPosition": "top"
+}
+```

package/examples/content-base/content/forms.md

@@ -0,0 +1,16 @@
+# Forms
+
+Forms collect input. The shorter the form, the more people finish it.
+
+## Validation
+
+Validate on submit, not on every keystroke. Show errors next to the field they
+belong to, in plain language:
+
+- Good: "Enter an email address like name@example.com"
+- Bad: "Invalid input (code 422)"
+
+## Submission
+
+Disable the submit button while a request is in flight and restore it on
+completion. Never leave the user guessing whether their click registered.

package/examples/content-base/content/home.md

@@ -0,0 +1,20 @@
+# Welcome
+
+This is a small, deliberately generic documentation set. The **same content**
+is rebuilt into every recipe in the theming gallery (`docs/THEMING-RECIPES.md`)
+— only the tenant `config.json` changes.
+
+Use it to see exactly what a given config does before you point Pagenary at your
+own docs.
+
+## What you're looking at
+
+- A handful of top-level sections so navigation layouts have something to show.
+- Plain Markdown content, converted at build time.
+- Zero per-recipe content edits — the look is **data, not code**.
+
+## Try it
+
+Pick a recipe, copy its config block, and run `npm run build:tenants`. Then serve
+the bundle and compare. Everything here is reproducible from the registry entry
+that built it.

package/examples/content-base/content/install.md

@@ -0,0 +1,22 @@
+# Install
+
+Getting set up takes one command.
+
+```bash
+npm install
+npm run build
+```
+
+That produces a static bundle in `dist/`. Serve it locally to preview:
+
+```bash
+npm run serve
+```
+
+There is no server runtime and no database — the output is plain HTML, CSS, and
+JavaScript you can host anywhere.
+
+## Requirements
+
+- Node.js 18 or newer
+- A static host (any will do)

package/examples/content-base/content/reference.md

@@ -0,0 +1,20 @@
+# Reference
+
+A condensed list of the config keys these recipes exercise. See the
+Tenant Configuration guide (`docs/TENANT-CONFIG.md`) for the complete set.
+
+## Branding
+
+- `title` — document title and default header text
+- `brandMark`, `brandSub` — the two-part wordmark
+- `tagline`, `description` — used in metadata and intros
+
+## Theming
+
+- `theme` — `light` | `dark` | `matrix` | a custom object
+- `accentColor`, `surfaceColor`, `inkColor`, `mutedColor`, `gridLineColor`
+- `fontBody`, `fontMono`
+
+## Layout
+
+- `navPosition` — `left` (default) | `right` | `top` | `bottom` | `hybrid`

package/examples/content-base/manifest.json

@@ -0,0 +1,61 @@
+{
+  "default": "home",
+  "sections": [
+    {
+      "id": "home",
+      "title": "Home",
+      "summary": "Start here — what this sample docs set demonstrates.",
+      "file": "home.md"
+    },
+    {
+      "id": "guides",
+      "title": "Guides",
+      "summary": "Practical, task-focused walkthroughs.",
+      "sections": [
+        {
+          "id": "install",
+          "title": "Install",
+          "summary": "Get the toolkit onto your machine.",
+          "file": "install.md"
+        },
+        {
+          "id": "configure",
+          "title": "Configure",
+          "summary": "Tune behavior with a single config file.",
+          "file": "configure.md"
+        }
+      ]
+    },
+    {
+      "id": "components",
+      "title": "Components",
+      "summary": "The building blocks and how they behave.",
+      "sections": [
+        {
+          "id": "buttons",
+          "title": "Buttons",
+          "summary": "Actions, variants, and states.",
+          "file": "buttons.md"
+        },
+        {
+          "id": "forms",
+          "title": "Forms",
+          "summary": "Inputs, validation, and submission.",
+          "file": "forms.md"
+        }
+      ]
+    },
+    {
+      "id": "reference",
+      "title": "Reference",
+      "summary": "Every option in one place.",
+      "file": "reference.md"
+    },
+    {
+      "id": "changelog",
+      "title": "Changelog",
+      "summary": "What changed, release by release.",
+      "file": "changelog.md"
+    }
+  ]
+}

package/examples/docs-map-corpus/config.json

@@ -0,0 +1,9 @@
+{
+  "title": "Lumen API — Docs Map demo",
+  "brandMark": "Lumen",
+  "brandSub": "API",
+  "description": "A fictional API platform whose richly cross-linked docs power the Pagenary docs-map demo.",
+  "tagline": "Interconnected docs, visualized.",
+  "accentColor": "#2563eb",
+  "docsMap": { "enabled": true, "title": "Docs Map" }
+}

package/examples/docs-map-corpus/content/api-keys.md

@@ -0,0 +1,10 @@
+# API Keys
+
+API keys authorize server-to-server calls. Scope each key narrowly, rotate on a
+schedule, and keep usage under your plan's [Rate Limits](#rate-limits). Keys are
+one of the two mechanisms covered in [Authentication](#authentication).
+
+## Related
+
+- [Authentication](#authentication)
+- [Rate Limits](#rate-limits)

package/examples/docs-map-corpus/content/authentication.md

@@ -0,0 +1,11 @@
+# Authentication
+
+Every request is authorized with either an API key or an OAuth token. Use
+[API Keys](#api-keys) for server-to-server calls and [OAuth](#oauth) when acting
+on behalf of a user. Rejected credentials return the auth [Errors](#errors) shape.
+
+## Related
+
+- [API Keys](#api-keys)
+- [OAuth](#oauth)
+- [Errors](#errors)

package/examples/docs-map-corpus/content/configuration.md

@@ -0,0 +1,16 @@
+# Configuration
+
+Configure environment, base URL, and webhook endpoints once. The CLI reads these
+after [Installation](#installation), and the same values authorize requests per
+[Authentication](#authentication).
+
+```toml
+[lumen]
+env = "production"
+webhook_url = "https://example.com/hooks"
+```
+
+## Related
+
+- [Installation](#installation)
+- [Authentication](#authentication)

package/examples/docs-map-corpus/content/errors.md

@@ -0,0 +1,12 @@
+# Errors
+
+Every error shares one JSON shape: a `code`, a human `message`, and a `request_id`.
+Authorization failures point back to [Authentication](#authentication), quota
+failures to [Rate Limits](#rate-limits), and delivery failures appear in your
+[Webhooks](#webhooks) log.
+
+## Related
+
+- [Authentication](#authentication)
+- [Rate Limits](#rate-limits)
+- [Webhooks](#webhooks)

package/examples/docs-map-corpus/content/events.md

@@ -0,0 +1,10 @@
+# Event Types
+
+A reference of every event Lumen emits over [Webhooks](#webhooks): `widget.created`,
+`widget.updated`, `order.paid`, and more. Subscriptions are scoped by the same
+grants described in [OAuth](#oauth).
+
+## Related
+
+- [Webhooks](#webhooks)
+- [OAuth](#oauth)

package/examples/docs-map-corpus/content/first-request.md

@@ -0,0 +1,15 @@
+# Your First Request
+
+Call a [Resources](#resources) endpoint and inspect the JSON it returns. Requests
+must be signed per [Authentication](#authentication); failures come back in the
+shape described in [Errors](#errors), and list endpoints use [Pagination](#pagination).
+
+```bash
+lumen get /v1/widgets
+```
+
+## Related
+
+- [Authentication](#authentication)
+- [Errors](#errors)
+- [Pagination](#pagination)

package/examples/docs-map-corpus/content/installation.md

@@ -0,0 +1,14 @@
+# Installation
+
+Install the Lumen CLI and language SDKs. Once installed, set your defaults in
+[Configuration](#configuration) and return to the [Quickstart](#quickstart).
+
+```bash
+npm install -g @lumen/cli
+lumen login
+```
+
+## Related
+
+- [Quickstart](#quickstart)
+- [Configuration](#configuration)

package/examples/docs-map-corpus/content/oauth.md

@@ -0,0 +1,12 @@
+# OAuth
+
+OAuth lets third parties act on behalf of a user without sharing credentials.
+Request only the scopes you need (see [Event Types](#events) for what each grant
+unlocks), and fall back to [API Keys](#api-keys) for first-party automation. OAuth
+is part of [Authentication](#authentication).
+
+## Related
+
+- [Authentication](#authentication)
+- [API Keys](#api-keys)
+- [Event Types](#events)

package/examples/docs-map-corpus/content/overview.md

@@ -0,0 +1,16 @@
+# Lumen API
+
+Lumen is a fictional API platform used here to demonstrate the Pagenary
+**docs map** — a relationship view built from how these pages link to each other.
+The more the docs cross-reference, the richer the graph.
+
+Start with the [Quickstart](#quickstart), learn how requests are authorized in
+[Authentication](#authentication), then explore the [Resources](#resources) you
+can read and write and the [Webhooks](#webhooks) that notify you of changes.
+
+## Related
+
+- [Quickstart](#quickstart)
+- [Authentication](#authentication)
+- [Resources](#resources)
+- [Webhooks](#webhooks)

package/examples/docs-map-corpus/content/pagination.md

@@ -0,0 +1,11 @@
+# Pagination
+
+List endpoints return a page of [Resources](#resources) plus a cursor. Follow the
+cursor until it is empty. Oversized pages are rejected with the [Errors](#errors)
+shape, and rapid paging counts against [Rate Limits](#rate-limits).
+
+## Related
+
+- [Resources](#resources)
+- [Errors](#errors)
+- [Rate Limits](#rate-limits)

package/examples/docs-map-corpus/content/quickstart.md

@@ -0,0 +1,14 @@
+# Quickstart
+
+Get a working request in three steps: install the tools, create a key, and call
+an endpoint.
+
+1. Follow [Installation](#installation) to set up the CLI.
+2. Create a key as described in [Authentication](#authentication).
+3. Make [Your First Request](#first-request).
+
+## Related
+
+- [Installation](#installation)
+- [Authentication](#authentication)
+- [Your First Request](#first-request)

package/examples/docs-map-corpus/content/rate-limits.md

@@ -0,0 +1,12 @@
+# Rate Limits
+
+Each plan has a request quota per minute. Exceeding it returns a `429` in the
+[Errors](#errors) shape with a `Retry-After` header. Spread load across
+[API Keys](#api-keys) and respect backoff when receiving [Webhooks](#webhooks)
+retries.
+
+## Related
+
+- [Errors](#errors)
+- [API Keys](#api-keys)
+- [Webhooks](#webhooks)

package/examples/docs-map-corpus/content/resources.md

@@ -0,0 +1,11 @@
+# Resources
+
+Resources are the objects you read and write — widgets, accounts, and orders.
+Collections are returned with [Pagination](#pagination), changes can notify you
+through [Webhooks](#webhooks), and failed reads surface as [Errors](#errors).
+
+## Related
+
+- [Pagination](#pagination)
+- [Webhooks](#webhooks)
+- [Errors](#errors)

package/examples/docs-map-corpus/content/webhooks.md

@@ -0,0 +1,13 @@
+# Webhooks
+
+Webhooks deliver [Event Types](#events) to your endpoint as resources change.
+Delivery failures are retried with backoff (see [Rate Limits](#rate-limits)), and
+non-2xx responses are recorded as [Errors](#errors). Configure endpoints in
+[Configuration](#configuration).
+
+## Related
+
+- [Event Types](#events)
+- [Rate Limits](#rate-limits)
+- [Errors](#errors)
+- [Configuration](#configuration)

package/examples/docs-map-corpus/manifest.json

@@ -0,0 +1,52 @@
+{
+  "default": "overview",
+  "sections": [
+    {
+      "id": "overview",
+      "title": "Overview",
+      "summary": "What Lumen is and how the pieces fit together.",
+      "file": "overview.md"
+    },
+    {
+      "id": "getting-started",
+      "title": "Getting Started",
+      "summary": "From zero to your first API call.",
+      "sections": [
+        { "id": "quickstart", "title": "Quickstart", "summary": "The fastest path to a working request.", "file": "quickstart.md" },
+        { "id": "installation", "title": "Installation", "summary": "Install the CLI and SDKs.", "file": "installation.md" },
+        { "id": "first-request", "title": "Your First Request", "summary": "Call an endpoint and read the response.", "file": "first-request.md" }
+      ]
+    },
+    {
+      "id": "concepts",
+      "title": "Core Concepts",
+      "summary": "The model behind the API.",
+      "sections": [
+        { "id": "resources", "title": "Resources", "summary": "The objects you read and write.", "file": "resources.md" },
+        { "id": "authentication", "title": "Authentication", "summary": "How requests are authorized.", "file": "authentication.md" },
+        { "id": "webhooks", "title": "Webhooks", "summary": "Receive events as they happen.", "file": "webhooks.md" }
+      ]
+    },
+    {
+      "id": "guides",
+      "title": "Guides",
+      "summary": "Task-focused walkthroughs.",
+      "sections": [
+        { "id": "api-keys", "title": "API Keys", "summary": "Create, scope, and rotate keys.", "file": "api-keys.md" },
+        { "id": "oauth", "title": "OAuth", "summary": "Delegated access for third parties.", "file": "oauth.md" },
+        { "id": "pagination", "title": "Pagination", "summary": "Page through large result sets.", "file": "pagination.md" },
+        { "id": "rate-limits", "title": "Rate Limits", "summary": "Quotas and how to stay under them.", "file": "rate-limits.md" },
+        { "id": "errors", "title": "Errors", "summary": "Error shapes and how to handle them.", "file": "errors.md" }
+      ]
+    },
+    {
+      "id": "reference",
+      "title": "Reference",
+      "summary": "Lookup material.",
+      "sections": [
+        { "id": "events", "title": "Event Types", "summary": "Every webhook event Lumen emits.", "file": "events.md" },
+        { "id": "configuration", "title": "Configuration", "summary": "Environment and client options.", "file": "configuration.md" }
+      ]
+    }
+  ]
+}