@janga/norna 0.7.0

package/docs/content.md

@@ -0,0 +1,384 @@
+# Content
+
+`site/content.md` is the editable page file for the homepage of a
+`norna` site. Optional route pages use
+`site/routes/<route-folder>/route-content.md` with the same page frontmatter and
+Markdown section model.
+
+Site-wide visual defaults may live in `site/theme.md`. Technical site
+configuration lives in `site/config.mjs`.
+
+## Frontmatter Schema
+
+The Astro content schema validates these top-level fields in page files:
+
+- `title`: required string. Rendered as the document title.
+- `description`: required string. Rendered as the meta description.
+- `slug`: optional route URL slug. It is ignored on the homepage. If omitted on
+  a route page, the route folder name is used.
+- `navigation`: optional page navigation metadata.
+- `presentation`: optional page-level presentation overrides.
+- `frame`: optional page-level frame color source.
+- `sections`: required non-empty array. Defines section order, ids,
+  presentation overrides, and gallery rows.
+
+`navigation` may contain:
+
+- `include`: optional boolean. Defaults to `true`.
+- `label`: optional string. Defaults to `title`.
+- `order`: optional integer. Defaults to `0` for the homepage and `100` for
+  route pages.
+
+Each `sections[]` item has:
+
+- `id`: required string matching `^[a-z0-9-]+$`. Used for anchors, navigation,
+  image directories, and Markdown heading ids.
+- `visible`: optional date window that controls whether the section is rendered.
+- `presentation`: optional object with `backgroundColor`, `textColor`, and/or
+  `typography` overrides.
+- `gallery`: optional array, defaulting to `[]`.
+
+Each gallery row has:
+
+- `image`: required filename matching `^[a-z0-9][a-z0-9.-]*\.(jpe?g|png)$`.
+  It must be a filename, not a path.
+- `alt`: required string.
+- `caption`: optional string.
+
+## Routes
+
+The homepage is always `site/content.md` and builds to `/`.
+
+Add a first-level route by creating:
+
+```text
+site/routes/about/route-content.md
+```
+
+Minimal route page:
+
+```md
+---
+title: About
+description: About this gallery.
+navigation:
+  label: About
+  order: 20
+sections:
+  - id: intro
+---
+
+## Intro {#intro}
+
+Text...
+```
+
+The example above builds to `/about/`. If `slug` is omitted, the route folder
+name is used. If `slug` is set, it must use lowercase letters, numbers, and
+hyphens. Keep the route folder and `slug` aligned unless you intentionally need
+a different URL.
+
+Route images live under the route:
+
+```text
+site/routes/about/images/intro/image.jpg
+```
+
+Image references in route frontmatter still use only the filename.
+
+### Navigation Scope
+
+Current route navigation is intended for small sites. This guidance may change
+as route support matures, but the present model is:
+
+- A single-page site should normally use only page navigation between sections.
+- A small multi-page site may use site navigation between routes plus page
+  navigation between sections on the current page.
+- If a site needs many routes, deeply nested routes, or several navigation
+  levels, it has probably outgrown the current sticky-navigation model and may
+  need a different site structure or navigation system.
+
+## Site Theme
+
+`site/theme.md` optionally defines site-wide visual defaults. It uses
+frontmatter and does not need a Markdown body. If the file is missing, built-in
+engine defaults are used.
+
+Starter sites include a marked comment block such as
+`norna:start theme-help` / `norna:end theme-help`. The block is
+only explorable help text; YAML comments do not affect rendering. The active
+configuration is the uncommented YAML below it.
+
+```yaml
+---
+# norna:start theme-help
+# Site-wide visual defaults. Remove a value to use the engine default.
+# norna:end theme-help
+
+presentation:
+  backgroundColor: "#000000"
+  textColor: "#f7f4ee"
+  inlineStyles:
+    highlight:
+      color: "#ffd84d"
+  typography:
+    preset: quiet-gallery
+frame:
+  colors: presentation
+---
+```
+
+`presentation.backgroundColor` and `presentation.textColor` are optional quoted
+hex colors in `#rgb`, `#rrggbb`, or `#rrggbbaa` form.
+
+`presentation.inlineStyles` defines named inline text styles that can be used
+from Markdown. Inline style names must match `^[a-z][a-z0-9-]*$`. Each style
+currently supports a required `color` field using the same quoted hex color
+format as `textColor`.
+
+`frame.colors` controls the sticky navigation and footer colors:
+
+- `presentation`: use the resolved presentation colors for this level.
+- `theme`: use the site theme frame colors. This is useful in page-level
+  frontmatter.
+- explicit colors:
+
+```yaml
+frame:
+  colors:
+    backgroundColor: "#111111"
+    textColor: "#eeeeee"
+```
+
+## Temporary Sections
+
+Use `sections[].visible` for sections that should be rendered only during a
+date window:
+
+```yaml
+sections:
+  - id: exhibition
+    visible:
+      from: "2026-08-01"
+      until: "2026-09-16"
+    gallery: []
+```
+
+`from` is inclusive. `until` is exclusive. With the example above, the section
+is visible from 2026-08-01 through 2026-09-15 and hidden again on 2026-09-16.
+
+Both `from` and `until` use `YYYY-MM-DD`. Either value may be omitted, but a
+`visible` object must contain at least one of them.
+
+Hidden sections are omitted from the rendered HTML and sticky navigation. They
+remain in `content.md`, and `content:check` still validates their matching
+Markdown headings and gallery image references.
+
+The current date is evaluated at dev/build time. Set `NORNA_TODAY` to
+preview or test a specific date:
+
+```sh
+NORNA_TODAY=2026-08-15 npm run norna:build
+```
+
+## Presentation
+
+Site-wide presentation belongs in `site/theme.md`. Page-level presentation in
+`site/content.md` is always an override on top of the theme. Section-specific
+presentation belongs under `sections[].presentation`.
+
+If a page omits `presentation`, it uses the theme presentation unchanged. If a
+section omits `presentation`, it uses the resolved page presentation.
+
+```yaml
+presentation:
+  typography:
+    overrides:
+      body:
+        paragraphSpacing: 1em
+```
+
+### Typography Presets
+
+Typographic presentation is configured through presets with optional overrides:
+
+```yaml
+presentation:
+  typography:
+    preset: quiet-gallery
+    overrides:
+      body:
+        paragraphSpacing: 0.8em
+```
+
+Available presets:
+
+- `quiet-gallery`: the default for image-led art and portfolio sites. Text is
+  restrained and supports the images without dominating the page.
+- `compact-gallery`: tighter typography for many sections, many images, or
+  short information blocks.
+- `text-forward`: more generous body text for pages where longer text carries
+  more of the experience.
+- `statement`: stronger type for introductions, first sections, and short
+  programmatic statements. Use it sparingly, usually as a section override.
+
+The normal place to choose a site-wide preset is `site/theme.md`. If theme
+typography is omitted, `quiet-gallery` is used. A page-level
+`presentation.typography.preset` changes the typographic base for the page. A
+section-level `sections[].presentation.typography.preset` changes the
+typographic base for that section.
+
+Use this command to inspect the exact preset values shipped with the installed
+engine:
+
+```sh
+norna typography:presets
+```
+
+Use this command to inspect the effective values for the selected site after
+presets and overrides have been applied:
+
+```sh
+norna typography:show
+```
+
+The typographic roles are:
+
+- `heading`: section headings.
+- `body`: Markdown body text inside sections.
+- `caption`: gallery captions.
+
+Allowed alignment values are `left`, `center`, and `right`. Alignment can be
+responsive:
+
+```yaml
+align:
+  desktop: left
+  mobile: center
+```
+
+Allowed size values are `small`, `medium`, `large`, and `xlarge`.
+`lineHeight` is a unitless number from `1` through `3`. `spacing` and
+`paragraphSpacing` are CSS lengths such as `0`, `0.8em`, `1rem`, or `12px`.
+
+Supported override fields:
+
+- `heading.align`, `heading.size`, `heading.lineHeight`, `heading.spacing`
+- `body.align`, `body.size`, `body.lineHeight`, `body.paragraphSpacing`
+- `caption.align`, `caption.size`, `caption.lineHeight`, `caption.spacing`
+
+Use `site/theme.md` `presentation.inlineStyles` for named inline text styles
+that can be applied inside Markdown:
+
+```yaml
+presentation:
+  inlineStyles:
+    highlight:
+      color: "#ffd84d"
+```
+
+Apply an inline style in Markdown with `[text]{.style-name}`:
+
+```md
+This sentence contains [highlighted text]{.highlight}.
+```
+
+`content:check` fails if Markdown uses an inline style that is not defined in
+`site/theme.md` `presentation.inlineStyles`.
+
+`sections[].presentation` contains only section-specific differences:
+
+```yaml
+sections:
+  - id: intro
+    presentation:
+      backgroundColor: "#161616"
+      textColor: "#ffffff"
+      typography:
+        preset: statement
+        overrides:
+          body:
+            paragraphSpacing: 0.7em
+```
+
+If a section sets `typography.preset`, that section starts from that preset. If
+a section only sets `typography.overrides`, it keeps the resolved page preset
+and changes only the specified values.
+
+Centered text uses narrower text widths. Left- or right-aligned heading and body
+text use the calculated gallery layout width so text edges line up with gallery
+images after layout gutters and gallery limits are applied.
+Configured section backgrounds render as full-width horizontal bands while the
+section content keeps the normal page and gallery widths. The top spacing
+before the first heading, the spacing between sections, and the spacing after
+the final section are part of the section background. The sticky section
+navigation row and footer use the resolved frame colors, not section-specific
+presentation.
+Configured section text colors apply to section headings, Markdown text,
+Markdown subheadings, and gallery captions. Links keep the global accent color.
+
+## Markdown Sections
+
+Every frontmatter section must have a matching level 2 Markdown heading with an
+explicit id:
+
+```md
+## Work {#work}
+
+Introductory text.
+```
+
+Keep these values aligned:
+
+- the frontmatter `sections[].id`
+- the Markdown heading id
+- the source image directory `site/images/<section-id>/`
+
+The visible navigation label comes from the Markdown heading text, not from the
+frontmatter id.
+
+## Validation And Sync
+
+Run:
+
+```sh
+npm run norna:content:check
+```
+
+This checks section order and heading ids, duplicate image names, missing image
+files, misplaced referenced images, duplicate gallery references, invalid image
+references, unreferenced images, undefined inline styles, and common
+frontmatter indentation and structure mistakes.
+
+Frontmatter uses YAML indentation. Use ordinary spaces, not tabs or
+non-breaking spaces. `content:check` reports a focused error when indentation is
+invalid, when a key is indented under a line that already has a value, or when
+a known nested key such as `gallery` appears at the top level:
+
+```yaml
+typography:
+  preset: quiet-gallery
+  overrides:
+    body:
+      paragraphSpacing: 0.8em
+```
+
+Top-level page frontmatter may contain only `title`, `description`,
+`presentation`, `frame`, and `sections`. A `gallery` key belongs under one
+`sections[]` item:
+
+```yaml
+sections:
+  - id: work
+    gallery: []
+```
+
+Run:
+
+```sh
+npm run norna:sync
+```
+
+This rewrites Markdown sections into frontmatter order and moves referenced
+image files into the directory matching their section. It prompts before
+writing unless `--yes` is passed.

package/docs/engine-development.md

@@ -0,0 +1,164 @@
+# Engine Development
+
+This document is for work on the reusable `norna` package itself.
+
+## Main Areas
+
+- `bin/norna.mjs`: public CLI dispatcher.
+- `scripts/lib/site-paths.mjs`: engine/site path resolution.
+- `scripts/lib/project-config.mjs`: `site/config.mjs` validation and defaults.
+- `scripts/sync-content-sections.mjs`: content validation and sync behavior.
+- `scripts/generate-images.mjs`: WebP image pipeline and manifest.
+- `scripts/sync-site-public.mjs`: static public file sync.
+- `scripts/deploy-site.mjs`: deploy and deploy:commit behavior.
+- `scripts/watch-pages-deploy.mjs`: GitHub Pages workflow monitor.
+- `src/content.config.ts`: Astro content schema.
+- `src/components/` and `src/layouts/`: rendered page, navigation, gallery, and
+  layout.
+- `tests/`: Playwright navigation diagnostics.
+- `fixtures/basic/site/`: minimal site used for engine checks.
+- `starters/basic/`: copyable site starter.
+
+The repository-local `site/` directory is a dog-gallery demo. It is useful for
+manual engine checks, but it is not a published site.
+
+## Common Checks
+
+Run focused checks while developing:
+
+```sh
+npm run test:content-check
+npm run test:site-public
+npm run test:fixture:build
+npm run demo:build
+npm run package:check
+```
+
+`npm run test` runs the same set in sequence.
+
+Navigation diagnostics are separate because they use Playwright:
+
+```sh
+npm run test:navigation
+npm run test:navigation:stress
+npm run test:navigation:preview
+```
+
+If Chromium is missing:
+
+```sh
+npx playwright install chromium
+```
+
+## Package Check
+
+`npm run package:check` packs this repository, extracts the package, copies the
+packaged starter into a temporary site project, installs dependencies, runs
+`norna doctor` from a site subdirectory, runs config/content checks,
+builds the installed site, and verifies selected rendered output and validation
+failures.
+
+It needs network access when npm dependencies are not already cached.
+The check uses a reusable npm cache at
+`node_modules/.cache/norna-package-check-npm` and runs npm with
+`--prefer-offline` so repeat runs do not redownload dependencies. Set
+`NORNA_PACKAGE_CHECK_CACHE=/path/to/cache` to use another cache.
+
+## CI Lockfiles
+
+Site repositories are developed on different operating systems but deployed on
+GitHub Actions Linux. `engine:update` therefore normalizes `package-lock.json`
+with npm 11.16.0 for Linux x64 glibc and verifies a clean install before it runs
+the site checks. The starter workflow pins Node 24.18.0, which provides the
+same npm version.
+
+`npm run test:ci-lockfile` recreates and repairs the optional npm peer-dependency
+case that previously caused GitHub Actions `npm ci` failures.
+
+## Test The Package In A Site Repository
+
+> **Warning:** `npm link` is not supported for `norna`. Astro resolves
+> renderer modules and runtime dependencies differently when the package is a
+> symlink, so a linked site can fail to start even though the published package
+> works. Do not use `npm link @janga/norna` to test a site.
+
+Use `npm run package:check` to test the package before release. To test a
+specific published engine version in a real site, update it with:
+
+```sh
+npm run norna:engine:update -- <version>
+```
+
+Commit the resulting `package.json` and `package-lock.json` changes in the
+site repository after the site's normal checks pass.
+
+## npm Release
+
+The npm package is published under the `@janga` scope. Choose the release type
+when starting a release; the command requires a clean working tree, verifies npm
+registry authentication for the same registry/cache used by `release:publish`,
+runs `npm test`, requires a clean working tree after the checks, updates
+`package.json` and `package-lock.json`, creates the release commit and Git tag,
+publishes to npm, then pushes the commit and tag.
+
+```sh
+npm run release:patch
+```
+
+Use `patch` for backwards-compatible fixes and maintenance changes. Use `minor`
+for backwards-compatible features and `major` for incompatible changes:
+
+```sh
+npm run release:minor
+npm run release:major
+```
+
+The release command deliberately does not run GitHub Pages deployment monitoring.
+If npm publication fails, it stops before pushing; the local version commit and
+tag remain available for inspection or recovery.
+
+If the npm authentication preflight fails, no version commit or tag has been
+created yet. Run the printed login command:
+
+```sh
+npm login --registry=https://registry.npmjs.org/ --auth-type=web --cache /private/tmp/norna-npm-cache
+```
+
+Then start the release command again.
+
+After publication, update site repositories to the exact published npm version
+and commit their updated `package-lock.json`.
+
+## Rendering Notes
+
+The renderer builds the homepage at `/` and optional first-level routes from
+`site/routes/<route-folder>/route-content.md`.
+
+Navigation has two separate levels:
+
+- Site navigation moves between pages and routes. It uses normal page URLs and
+  browser history.
+- Page navigation moves between sections on the current page. It uses real
+  `href="#section-id"` links so anchors work without JavaScript.
+
+The current navigation model is deliberately scoped to single-page and small
+multi-page sites. That scope may change as route support matures. For now,
+single-page sites should rely on page navigation only; small route-based sites
+may combine site navigation and page navigation; larger information
+architectures should not be forced into the sticky-navigation model without a
+separate design decision.
+
+The JavaScript enhancement keeps the URL hash as the source of truth for active
+page-navigation state. A section-link click pushes one hash entry into browser
+history, back/forward moves between hash entries, and returning to the same page
+without a hash restores the first section as active. The enhancement does not
+derive active section state from free manual scrolling.
+
+The sticky navigation updates root scroll offset variables so direct hash links
+and clicked links land below the fixed header. Hash targets may be corrected
+again after layout shifts such as image loading, but that correction must not
+add history entries or change the active section independently of the URL hash.
+
+The shared layout reads UI language and labels from `site/config.mjs`
+`locale`. Keep editorial content in page Markdown and non-editorial engine UI
+labels in config.

package/docs/getting-started.md

@@ -0,0 +1,96 @@
+# Getting Started
+
+This guide creates a new site repository from the included starter. It describes
+the generic `norna` setup; site-specific content belongs in the new site
+repository.
+
+## Requirements
+
+- Node.js `>=22.12.0`
+- ImageMagick for image generation
+- GitHub CLI (`gh`) for deploy checks and deploy monitoring
+
+Install Playwright Chromium only when you plan to run navigation diagnostics:
+
+```sh
+npx playwright install chromium
+```
+
+## Create A Site Repository
+
+Create the site from the starter first, then install dependencies inside the
+new site directory:
+
+```sh
+cd path/to/your/projects
+npx @janga/norna@latest init my-gallery
+cd my-gallery
+npm install
+npm run norna:dev
+```
+
+A freshly created empty directory is not a `norna` site yet. It becomes a
+site when `init` copies the starter files, including `package.json`. If you run
+`npm install` in an empty directory, npm may walk up to a parent directory and
+install dependencies for another project instead.
+
+For normal site work, keep site repositories as siblings of the `norna`
+engine repository. For example:
+
+```text
+Projects/
+  norna/
+  my-gallery/
+```
+
+The starter contains:
+
+- `package.json` with npm scripts that call `norna`
+- `.github/workflows/deploy.yml` for GitHub Pages
+- `site/config.mjs`
+- `site/theme.md`
+- `site/content.md`
+- `site/images/work/.gitkeep`
+- `site/public/robots.txt`
+
+Commit the generated `package-lock.json` after the first install.
+
+## First Edits
+
+1. Edit `site/config.mjs` for the site's URL, layout, font, language labels,
+   GitHub repository, footer, and deploy settings.
+2. Edit `site/theme.md` for site-wide colors, typography preset, inline styles,
+   and frame colors, or omit it to use engine defaults.
+3. Edit `site/content.md` for homepage title, description, sections, text,
+   gallery rows, page/section presentation overrides, alt text, and captions.
+4. Put source images under `site/images/<section-id>/`.
+5. Add optional route pages under
+   `site/routes/<route-folder>/route-content.md`.
+6. Put static files such as `robots.txt`, `CNAME`, and favicons under
+   `site/public/`.
+7. Run:
+
+```sh
+npm run norna:check
+npm run build
+```
+
+Read [Site Structure](site-structure.md), [Content](content.md), and
+[Configuration](configuration.md) before publishing a real site.
+
+To change the site's maximum page width, set `layout.pageWidth` in
+`site/config.mjs`. To change side margins, set `layout.gutter`. To change the
+maximum gallery width inside that page area, set `gallery.width`. To keep
+images within a comfortable viewport height, set
+`gallery.maxAvailableHeightPercent`. See [Configuration](configuration.md) for
+the accepted formats and default values.
+
+To change the site's font, set `typography.fontFamily` in `site/config.mjs`.
+See [`typography.fontFamily`](configuration.md#typographyfontfamily) for the
+accepted format and default value.
+
+To change the site-wide typography preset, edit `site/theme.md`. To change one
+page or section, add a focused `presentation.typography` override in
+`site/content.md`. Use `npm run norna:typography:presets` to inspect the
+installed preset values and `npm run norna:typography:show` to inspect the
+resolved typography for the selected site.