@janga/norna 0.7.18 → 0.7.22

package/docs/design/norna-diagram-design.md

@@ -1,159 +0,0 @@
-# Norna Diagram Design
-
-This document defines a repository-local workflow for creating technical and
-pedagogical diagrams for Norna.
-
-It is intentionally not a vendored copy of any external skill, MCP server, or
-diagram tool. The first experiment should use hand-authored SVG assets managed
-by Norna's existing image model.
-
-## Goal
-
-Norna diagrams should help a new reader understand the site model faster than
-text alone.
-
-A diagram should explain one idea clearly, not show every related feature. If a
-topic needs several ideas, split it into several diagrams.
-
-## Current Scope
-
-Use this workflow for diagrams in the Norna documentation site under `site/`.
-
-Do not add diagram generation to the Norna build pipeline yet. Diagram creation
-is an authoring workflow for now, not product functionality.
-
-Do not require Excalidraw, MCP servers, browser plugins, or external layout
-tools for the first experiment.
-
-## Diagram Brief
-
-Before creating or replacing a diagram, write a short brief:
-
-```md
-Purpose:
-Audience:
-Main message:
-Concepts to show:
-Concepts to avoid:
-Norna features that must not be implied:
-Suggested layout:
-Mobile/readability requirement:
-Where the SVG will live:
-Markdown block and alt text:
-```
-
-The brief can live in the discussion, in a source-only Markdown comment near
-the image, or in `docs/design/` when it is useful for future maintenance.
-
-## Design Principles
-
-- Show one primary flow or relationship.
-- Prefer two to five main objects.
-- Use short labels.
-- Use one clear visual hierarchy.
-- Keep arrows few and directional.
-- Avoid diagrams where every object connects to every other object.
-- Prefer multiple simple diagrams over one dense diagram.
-- Make page order, URL slugs, section ids, image folders, source files, and
-  generated output visually distinct when those ideas matter.
-- Do not show templates, components, custom rendering logic, page-level
-  technical configuration, or hosting integrations that Norna does not support.
-- Do not show page layouts that Norna cannot actually render unless the diagram
-  is clearly abstract and not a product capability example.
-
-## Norna-Specific Accuracy
-
-Diagrams must match the current Norna model:
-
-- A Norna site is described with site files, not arbitrary project structure.
-- `content.md` is the homepage content file.
-- `sitewide-content.yaml` contains shared logo settings, banners, and footer
-  content.
-- Additional pages are page directories with `content.md`.
-- Page folder prefixes control navigation order.
-- Page ids become URL segments.
-- Images belong under the image root for their page, usually grouped by
-  section id.
-- Markdown remains the primary writing format.
-- Norna blocks cover fixed site patterns such as image stacks,
-  carousels, and card lists.
-- `theme.yaml` controls visual presentation.
-- `config.yaml` controls the public URL and optional language and smooth
-  scrolling.
-- `dist/` is generated static output.
-- GitHub Pages is the integrated publishing target today.
-
-## SVG Requirements
-
-Use hand-authored SVG for the first experiment.
-
-SVG assets should:
-
-- have a `viewBox`;
-- include `<title>` and `<desc>`;
-- use real text, not outlined text;
-- avoid external fonts and external image files;
-- remain readable at the size used on the site;
-- work when scaled down on a phone;
-- use restrained colors that fit the surrounding page;
-- avoid decorative effects that compete with the explanation;
-- keep text inside boxes with visible margins;
-- be maintainable by editing the SVG source.
-
-If a diagram is too wide for mobile, prefer splitting it into smaller diagrams
-over relying on horizontal scrolling.
-
-## Source Placement
-
-Store diagram SVG files as normal Norna managed image assets:
-
-```text
-site/pages/<NNN-page-id>/images/<diagram-name>.svg
-```
-
-Reference them with a Norna image block:
-
-````md
-<!-- norna-image-provenance:
-image: diagram-name.svg
-source: hand-authored
-Short maintenance note explaining why the diagram exists.
--->
-
-```norna-image-stack
-- image: diagram-name.svg
-  alt: Concise explanation of what the diagram shows.
-```
-````
-
-## Review Checklist
-
-Before accepting a diagram:
-
-- The main message is obvious without reading the surrounding section.
-- The diagram does not imply unsupported Norna functionality.
-- URL, page, section, image, theme, config, and output terminology is
-  consistent with documentation.
-- Text fits inside boxes at desktop and mobile widths.
-- Arrows clarify the relationship instead of adding noise.
-- The SVG has title, description, and useful alt text in Markdown.
-- `norna content:check` passes.
-- A desktop and mobile visual check has been done when layout changed.
-
-## Relationship To Excalidraw
-
-Excalidraw can be useful as a sketching style or inspiration for box-and-arrow
-clarity, but the first Norna experiment should not depend on Excalidraw files,
-exports, or MCP tooling.
-
-If future experiments show that diagram generation should be automated, evaluate
-that as a separate authoring tool or CLI. Do not make it part of the site build
-engine unless there is a clear product reason.
-
-## Future Questions
-
-- Should diagram briefs become tracked files next to SVG assets?
-- Should Norna have a separate authoring helper for diagrams?
-- Should generated diagrams store both a source format and exported SVG?
-- Should a later tool create Excalidraw-compatible files, plain SVG, or both?
-- What review rules are needed before diagrams are used in starters or examples?

package/docs/design/site-examples-structure.md

@@ -1,119 +0,0 @@
-# Site Examples Structure
-
-This document defines the repository vocabulary for starter files, example
-sites, fixtures, and documentation sites.
-
-## Goal
-
-`norna` should make it easy to find runnable examples and understand which
-files are product documentation, which files are examples, and which files are
-test fixtures.
-
-The repository grew from one local demo, one starter, and a set of tests. The
-current structure keeps those roles distinct while allowing runnable examples
-to serve as documentation and realistic integration tests.
-
-## Terms
-
-### Starter
-
-A starter is a template copied by `norna init`.
-
-It should be small, conservative, and suitable as the first commit in a real
-site repository. It should not be a showcase for every feature.
-
-### Example Site
-
-An example site is a runnable site that demonstrates one or more features.
-
-Examples can be richer than the starter. They may show pages, navigation,
-complete theme presets, image stacks, image carousels, cards, notes, surfaces,
-and site-specific configuration choices.
-
-### Documentation Site
-
-A documentation site is a runnable `norna` site that explains the product
-visually.
-
-It can use images, diagrams, screenshots, and additional pages to explain concepts
-such as file structure, presentation inheritance, site navigation, and image
-handling.
-
-### Reference Documentation
-
-Reference documentation is GitHub-readable Markdown for exact interfaces and
-workflows.
-
-It belongs in `docs/` and should remain useful without building a site. It is
-the right home for command reference, configuration reference, content schema,
-publishing workflows, and engine development notes.
-
-### Fixture
-
-A fixture is test data.
-
-It should be minimal, stable, and optimized for regression tests rather than
-for human reading or visual appeal.
-
-## Repository Structure
-
-Runnable site examples are collected under `examples/`:
-
-```text
-examples/
-  complete-sites/
-    dog-shelter-single-page/
-    dog-shelter-multi-page/
-  feature-demos/
-    theme-preset-portfolio/
-    theme-preset-documentation/
-    theme-preset-project/
-    theme-preset-statement/
-    media-and-surfaces/
-    sitewide-content/
-```
-
-`complete-sites/` contains coherent sites that show how Norna files work
-together in a realistic project:
-
-- `dog-shelter-single-page/`: sections and managed images without additional pages.
-- `dog-shelter-multi-page/`: ordered pages with page-local content and
-  images.
-
-`feature-demos/` contains focused visual test benches:
-
-- `theme-preset-*/`: one independent site per complete built-in preset, without
-  overrides. Presets are site-wide, so comparing them must not rely on
-  page-local preset changes.
-- `media-and-surfaces/`: image and card blocks, notes, palettes and section
-  surfaces. This is also the broad demo-build and navigation-test target.
-- `sitewide-content/`: convention-based logo handling, navigation, banner stacks,
-  dismissal and footer content shared across pages.
-
-The repository Pages workflow builds all examples and publishes them
-under `/norna/examples/`. The HTML documentation links to those rendered sites
-from its Examples page.
-
-The repository-local `site/` directory is reserved for the documentation site.
-`docs/` should remain for reference documentation. It should link to the
-documentation site when visual explanation is more useful than reference text.
-
-`starters/basic/` stays separate from examples because it is copied by
-`norna init`. It should stay small and conservative.
-
-Fixtures stay under `fixtures/`. They are intentionally smaller and more stable
-than examples and should not be confused with user-facing sites.
-
-## Constraints
-
-- Do not remove the starter concept; it has a different purpose from examples.
-- Do not make the documentation site the only documentation.
-- Do not let examples become required input for production site repositories.
-- Keep `norna init` deterministic and easy to test.
-- Use examples for build, navigation and visual integration tests where the
-  user-facing site is the behavior being protected.
-- Use fixtures for isolated edge cases, invalid input and narrowly scoped
-  engine regressions.
-
-The repository-local `site/` remains the product documentation site and is not
-an example or fixture.

package/docs/engine-development.md

@@ -1,215 +0,0 @@
-# Engine Development
-
-This document is for work on the reusable `norna` package itself.
-
-## Main Areas
-
-- `bin/norna.mjs`: public CLI launcher and local-version resolver.
-- `bin/norna-cli.mjs`: public CLI command dispatcher.
-- `scripts/lib/site-paths.mjs`: engine/site path resolution.
-- `scripts/lib/project-config.mjs`: plain YAML `site/config.yaml`
-  validation, defaults and derived URL path.
-- `scripts/sync-content-sections.mjs`: content validation and sync behavior.
-- `scripts/generate-images.mjs`: managed 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, image
-  blocks, and layout.
-- `tests/`: Playwright navigation diagnostics.
-- `fixtures/basic/site/`: minimal site used for engine checks.
-- `starters/basic/`: copyable site starter.
-- `examples/feature-demos/media-and-surfaces/site/`: broad visual example used
-  by demo builds and navigation diagnostics.
-
-The repository-local `site/` directory is reserved for a local documentation
-site. It is useful for dogfooding `norna` documentation, but it is not the
-primary visual regression demo.
-
-## Common Checks
-
-Run focused checks while developing:
-
-```sh
-npm run test:content-check
-npm run test:site-public
-npm run test:documentation
-npm run test:fixture:build
-npm run test:examples
-npm run demo:build
-npm run package:check
-```
-
-`npm run test:examples` builds every complete site and feature demo under
-`examples/`. `npm run test` includes those builds in the standard check
-sequence.
-
-`npm run test:documentation` extracts the file examples from the five-minute
-tutorial, applies them to a freshly initialized temporary site, runs the
-configuration and content checks, builds the result, and checks local Markdown
-links plus the `llms.txt` source targets.
-
-`npm run build:pages` is specific to this repository. It builds the
-documentation site and assembles rendered examples under `dist/examples/` for
-the shared GitHub Pages artifact. It is not a generic Norna site command.
-
-The root `site/` directory is the documentation site. Use the ordinary local
-commands for it:
-
-```sh
-npm run dev:local
-npm run build
-```
-
-Inside the engine repository, use npm scripts or explicitly run
-`node bin/norna.mjs ...`. Do not rely on a bare `norna ...` command there: a
-globally installed launcher deliberately does not delegate to another package
-whose own name is `@janga/norna`, so it may continue with the published global
-implementation instead of the working tree.
-
-The media-and-surfaces feature demo is the broad visual and navigation
-diagnostic target:
-
-```sh
-node bin/norna.mjs --site-dir examples/feature-demos/media-and-surfaces/site dev:local
-npm run demo:build
-```
-
-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.
-
-The installed `norna` command is created from the package `bin` field. The
-launcher first looks for the nearest project `package.json`. If that project
-declares `@janga/norna` and Node can resolve an installed copy from that project
-root, the launcher delegates to that local entrypoint. The engine repository
-itself is excluded from delegation to prevent recursion; its working tree is
-selected explicitly through npm scripts or `node bin/norna.mjs`.
-
-## 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 the publish step,
-updates `package.json` and `package-lock.json` without creating a commit, and
-regenerates schemas with documentation links pinned to the new `v<version>` Git
-tag. It then runs `npm test`, verifies that only release files changed, creates
-the release commit and Git tag, publishes to npm, and 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 version preparation, schema generation, or testing fails before the release
-commit, the script restores the previous package version and generated schemas.
-
-If npm publication fails, it stops before pushing; the local version commit and
-tag remain available for inspection or recovery. Retry publication with
-`npm run release:publish`, then push the existing commit and tag with
-`git push --follow-tags`. Do not start a new version bump merely to retry these
-steps.
-
-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 discovers a required homepage at
-`site/pages/000-home/content.md`, top-level navigation roots beside Home, and
-nested child pages under each non-home page's `pages/` directory.
-
-Navigation has two related levels:
-
-- Global navigation moves between Home and top-level page areas.
-- Local navigation follows nested pages and headings within the active area.
-  Section links use real `href="#section-id"` anchors so they work without
-  JavaScript.
-
-Automatic navigation selects section navigation for one-page sites, top
-navigation for shallow page structures, and tree navigation for deeper page or
-heading hierarchies. `config.yaml` may choose a mode explicitly. Home is a
-standalone front door and cannot contain child pages.
-
-The optional JavaScript enhancement manages menu interaction and active local
-navigation while retaining normal links and browser history. The rendered page
-tree and anchor navigation remain usable without client-side JavaScript.
-
-The sticky navigation updates a root scroll-offset variable so direct hash
-links and clicked links remain visible below the fixed header. The browser owns
-anchor movement; Norna does not run a separate scroll animation or retry anchor
-positions after later layout shifts.
-
-The shared layout selects Norna's built-in UI labels from the optional
-`language` in `site/config.yaml`. Keep editorial content in page Markdown and
-non-editorial engine UI labels in the engine language packs.

package/docs/getting-started.md

@@ -1,206 +0,0 @@
-# Build Your First Norna Site
-
-This tutorial takes the shortest path from an empty directory to a running,
-edited, and verified Norna site. Follow the steps in order. Installation time
-depends on your npm connection, but the site work itself should take about five
-minutes.
-
-At the end you will have:
-
-- a standalone site project with a pinned Norna version,
-- a homepage with your own content and navigation,
-- a complete visual preset,
-- validated source files and a static build in `dist/`.
-
-## Before You Start
-
-You need:
-
-- Node.js `22.12` or later,
-- npm, which is included with Node.js,
-- a terminal and a text editor.
-
-ImageMagick is needed when you add raster images that Norna should process. It
-is not needed to make the text-only first edit in this tutorial. GitHub CLI and
-Playwright are not required.
-
-See [Requirements and limitations](requirements.md) for platform details and
-the current product boundaries.
-
-## 1. Create And Run The Site
-
-Run these commands from the directory where you keep projects:
-
-```sh
-npx @janga/norna@latest init my-site
-cd my-site
-npm install
-npm run norna:dev
-```
-
-`init` creates the project before `npm install` runs. The generated
-`package.json` pins the Norna engine version so this project keeps using the
-same version until you update it deliberately.
-
-The tutorial uses the `norna:*` npm scripts because they work in both
-standalone and embedded projects. A standalone project also includes the
-shorter `npm run dev` and `npm run build` aliases.
-
-### Optional: Shorter CLI Commands
-
-Install the Norna launcher globally when you prefer direct commands:
-
-```sh
-npm install --global @janga/norna@latest
-```
-
-You can then run `norna dev`, `norna check`, and `norna build`. Inside a
-project, the launcher automatically delegates to that project's locally
-installed and pinned Norna version. The global installation is only the
-launcher; keep the local dependency and lockfile.
-
-### Checkpoint: The Starter Is Visible
-
-Open the URL printed by the development server. It is normally
-`http://localhost:4321/`, but Norna uses another available port when necessary.
-You should see the starter homepage and its section navigation.
-
-Leave the development server running while you complete the next steps.
-
-## 2. Replace The Homepage Content
-
-Replace `site/pages/000-home/content.md` with:
-
-```md
----
-page:
-  description: A website built from plain files.
----
-
-# My first Norna site
-
-This page is written in Markdown. Norna provides its layout and navigation.
-
-## Welcome {#welcome}
-
-This is the first section.
-
-## Next {#next}
-
-Edit this file while the development server is running and the browser updates.
-```
-
-The single `#` heading is the page title. Each `##` heading is a page section.
-Norna derives section anchors from heading text. The explicit ids in this
-example keep those public anchors stable if the visible headings are renamed.
-
-### Checkpoint: Content And Navigation Update
-
-Return to the browser. The page should now contain `Welcome` and `Next`, and
-the section navigation should link to those two sections. You should not
-need to restart the server.
-
-## 3. Set Shared Content
-
-Replace `site/sitewide-content.yaml` with:
-
-```yaml
-footer:
-  copyrightMessage: My first Norna site.
-```
-
-The footer is site-wide content rather than a page section. If you add pages
-later, they share it. The homepage H1 you set in the previous step already
-names the homepage in navigation and becomes the alternative text if you add a
-conventional navigation logo.
-
-### Checkpoint: The Footer Is Shared
-
-The navigation should use `My first Norna site` from `content.md`. The footer
-should show the new message.
-
-## 4. Choose A Complete Theme
-
-Replace `site/theme.yaml` with:
-
-```yaml
-preset: project
-```
-
-The preset supplies coordinated layout, typography, spacing, image sizing,
-palette, and section surfaces. Add overrides only when a real site needs to
-differ from the preset.
-
-### Checkpoint: The Preset Is Active
-
-The browser should refresh with the `project` presentation. Your content files
-remain unchanged because presentation belongs in `theme.yaml`.
-
-## 5. Check And Build
-
-Open another terminal in `my-site` and run:
-
-```sh
-npm run norna:check
-npm run norna:build
-```
-
-The check should complete without errors. The build should create:
-
-```text
-dist/
-```
-
-`dist/` is generated output. Continue editing the files under `site/`; do not
-edit the built HTML as the source of the website.
-
-### Checkpoint: The Source Produces A Clean Build
-
-Confirm that both commands exit successfully and that `dist/index.html`
-exists. You now have a complete local Norna workflow: edit, preview, check, and
-build.
-
-## What To Do Next
-
-- [Add and manage images](content.md#norna-blocks)
-- [Add another page](pages.md)
-- [Inspect and adjust the theme](theme.md)
-- [Configure the public URL](configuration.md)
-- [Publish with GitHub Pages](publishing.md)
-- [Browse complete and focused examples](../examples/README.md)
-
-To add Norna inside an existing Node project instead of creating a standalone
-site, see [Add an embedded site](how-to/embedded-site.md).
-
-The [documentation map](README.md) separates task guides, explanation, and
-reference so you can continue from the kind of question you have.
-
-## Common First Problems
-
-### The Default Port Is Occupied
-
-Start the development server with:
-
-```sh
-npm run norna:dev -- --kill
-```
-
-This tells Norna to stop the process occupying its standard port before
-starting. The separator `--` is required so npm forwards `--kill` to Norna.
-
-### Images Fail During Checking Or Building
-
-Install ImageMagick and confirm that either `magick` or the older `identify`
-and `convert` commands are available. Then rerun the failed command.
-
-### The Page Reports Invalid Content
-
-Run:
-
-```sh
-npm run norna:content:check
-```
-
-Read all reported issues before editing. Norna reports file and line context
-for invalid sections and managed content blocks. See [Content](content.md) for
-the accepted Markdown forms.