@janga/norna 0.7.16 → 0.7.18

package/docs/design/navigation-and-theme-plan.md

@@ -0,0 +1,186 @@
+# Navigation And Theme Plan
+
+This document records the intended order of work for page hierarchy,
+navigation, and theme presets. It is an implementation plan, not a description
+of released behavior.
+
+## Goal
+
+Norna should support sites with limited global navigation and a larger local
+page hierarchy without making mobile navigation harder to understand. Theme
+presets should provide a coherent visual system without changing the site's
+information architecture.
+
+## Working Principles
+
+- The file structure defines the page hierarchy and presentation order.
+- Navigation behavior and navigation styling are separate concerns.
+- Global site navigation, local page navigation, and headings on the current
+  page have distinct roles.
+- Changing a theme preset must not change which pages are available or how the
+  page hierarchy is interpreted.
+- Site-wide visual identity should remain coherent while individual pages may
+  vary where that does not disrupt navigation or orientation.
+- Documentation and broad example migration should follow implementation and
+  manual evaluation, not precede them.
+
+## Order Of Work
+
+### 1. Stabilize The Page Tree - Complete
+
+Finish and test nested page discovery independently of final navigation
+presentation. Establish deterministic rules for:
+
+- directory parsing, page ids, URL paths, and presentation order;
+- parent and ancestor relationships;
+- collisions and invalid nesting;
+- page-local content, images, and themes;
+- breadcrumbs and current-branch discovery.
+
+Commit this foundation separately before broad theme or preset changes.
+
+The page tree now supports nested pages with deterministic directory parsing,
+URLs, ordering, ancestry, breadcrumbs, inherited page resources, and collision
+diagnostics.
+
+The current breaking page-container proof of concept removes the special root
+page. Every page now uses the same physical model:
+
+```text
+site/pages/NNN-page-id/
+  content.md
+  theme.yaml       # optional page-local presentation
+  images/          # optional managed page images
+  pages/           # optional child pages
+```
+
+`site/pages/000-home/content.md` is required and maps to `/`. The `000` prefix
+is reserved for this page. Other top-level page directories are its siblings,
+not its children. The homepage cannot contain a `pages/` hierarchy; place each
+top-level area beside `000-home` and nest further pages below that area.
+
+The root `site/` directory now contains only site-wide files and the page
+container. Removed root-level page and image locations produce a migration
+error instead of being interpreted as a second page model.
+
+### 2. Define The Navigation Contract - Complete
+
+The accepted information architecture is:
+
+- a small global navigation for the site's top-level areas;
+- a larger local page tree for the selected area;
+- breadcrumbs for location and ancestry;
+- headings for the current page integrated below that page in the local tree;
+- one unified mobile navigation containing the whole page hierarchy and the
+  current page headings.
+
+Navigation modes follow the site structure:
+
+- a single-page site uses section navigation;
+- an ordinary shallow multi-page site uses top navigation;
+- a deeper documentation-style hierarchy uses tree navigation.
+
+The tree contract is:
+
+- top-level areas remain available in the sticky global navigation;
+- the selected top-level area supplies the desktop local tree;
+- breadcrumbs show page ancestry without changing the vertical position of
+  the page heading;
+- a closed expandable page title expands the node without navigating;
+- an open expandable page title links to that page, while its chevron can
+  collapse the node;
+- a page without headings or child pages is always a direct link;
+- headings on the current page appear under its page node rather than in a
+  separate `On this page` region;
+- opening one branch does not implicitly close another branch;
+- long desktop trees scroll independently of short page content;
+- mobile uses one drawer for the complete hierarchy instead of requiring a
+  separate page-selection and section-selection sequence.
+
+Real links and native disclosure elements provide the fallback. JavaScript
+preserves explicitly opened branches, restores navigation scroll position,
+enhances focus handling, and keeps measured sticky offsets stable. Without
+JavaScript, navigation remains usable but manually opened branches are not
+preserved across page loads.
+
+The contract should also define the fallback and override behavior for the
+supported navigation modes. Structural behavior belongs to site-level engine
+configuration or deterministic automatic selection, not to presentation
+presets.
+
+The contract was evaluated with the nested-pages fixture and focused desktop,
+mobile, no-JavaScript, spatial-stability, and long-navigation tests.
+
+### 3. Implement Navigation In Layers - Complete
+
+Implement and verify the navigation model in this order:
+
+1. page-tree data and validation;
+2. desktop global navigation, local tree, breadcrumbs, and `On this page`;
+3. unified mobile navigation;
+4. keyboard, focus, current-page, and progressive-enhancement behavior;
+5. visual evaluation at representative viewport sizes.
+
+Real links remain the foundation. Client-side JavaScript is limited to
+interaction and state that cannot be retained adequately with HTML and CSS.
+
+### 4. Refine Theme And Preset Responsibilities - Proof Of Concept
+
+Presets should control visual presentation, including:
+
+- color system;
+- typography;
+- spacing and density;
+- page and content widths;
+- the visual treatment of global navigation, local navigation, breadcrumbs,
+  and `On this page`.
+
+Presets must not determine page hierarchy, link membership, or semantic
+navigation structure. Those must remain stable when a preset changes.
+
+Site-wide color, typography, and navigation treatment should normally remain
+consistent. Page-local theme variation should be limited to properties such as
+content width, density, and media presentation when variation does not weaken
+site identity or navigation clarity.
+
+The proof-of-concept contract is:
+
+- `config.yaml` owns the site-wide navigation mode;
+- the root `theme.yaml` owns presets, palette, shape, typography, the page
+  frame, global spacing primitives, and default page presentation;
+- a page-local `theme.yaml` may set only `layout.textWidth`,
+  `layout.contentSpacing`, managed-image sizing, and
+  `sections.backgroundPattern`;
+- page-local values are inherited by descendant pages and merged field by
+  field, while global visual identity is never replaced;
+- `layout.contentSpacing` replaces the ambiguous `layout.density` name;
+- `sections.backgroundPattern` replaces the low-level `sectionSurfaces` list
+  with `uniform`, `alternating`, and `cycling` choices;
+- custom presets and custom font definitions are deferred until the built-in
+  contract has been tested in real sites.
+
+The nested-pages fixture is the current proof of concept. The engine-owned
+basic init starter follows the new page contract so newly created sites remain
+valid. Documentation, other starters, and broad examples should be migrated
+only after manual approval.
+
+### 5. Migrate After Evaluation
+
+After the page tree, navigation contract, and preset boundaries have been
+manually evaluated:
+
+- migrate fixtures and examples;
+- update schemas and editor assistance;
+- update Markdown reference documentation;
+- update the rendered documentation site;
+- remove obsolete navigation and preset behavior rather than retaining
+  compatibility layers.
+
+Keep foundation, navigation, preset, migration, and documentation changes in
+separate commits where practical.
+
+## Immediate Checkpoint
+
+The nested navigation contract has been evaluated and committed. The unified
+page-container and theme-scope proof of concepts are now ready for manual
+evaluation against the nested-pages fixture before broad migration begins.

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

@@ -54,9 +54,9 @@ the image, or in `docs/design/` when it is useful for future maintenance.
 - Keep arrows few and directional.
 - Avoid diagrams where every object connects to every other object.
 - Prefer multiple simple diagrams over one dense diagram.
-- Make route order, URL slugs, section ids, image folders, source files, and
+- 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, route-level
+- 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.
@@ -67,12 +67,12 @@ 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 site identity, banners, and footer
+- `sitewide-content.yaml` contains shared logo settings, banners, and footer
   content.
-- Additional pages are route directories with `content.md`.
-- Route folder prefixes control route presentation order.
-- Route ids become default URL slugs.
-- Images belong under the image root for the page or route, usually grouped by
+- 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,
@@ -108,7 +108,7 @@ over relying on horizontal scrolling.
 Store diagram SVG files as normal Norna managed image assets:
 
 ```text
-site/routes/<NNN-route-id>/images/<section-id>/<diagram-name>.svg
+site/pages/<NNN-page-id>/images/<diagram-name>.svg
 ```
 
 Reference them with a Norna image block:
@@ -132,7 +132,7 @@ Before accepting a diagram:
 
 - The main message is obvious without reading the surrounding section.
 - The diagram does not imply unsupported Norna functionality.
-- URL, route, section, image, theme, config, and output terminology is
+- 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.

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

@@ -26,7 +26,7 @@ site repository. It should not be a showcase for every feature.
 
 An example site is a runnable site that demonstrates one or more features.
 
-Examples can be richer than the starter. They may show routes, navigation,
+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.
 
@@ -35,8 +35,8 @@ and site-specific configuration choices.
 A documentation site is a runnable `norna` site that explains the product
 visually.
 
-It can use images, diagrams, screenshots, and route pages to explain concepts
-such as file structure, presentation inheritance, route navigation, and image
+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
@@ -65,7 +65,10 @@ examples/
     dog-shelter-single-page/
     dog-shelter-multi-page/
   feature-demos/
-    theme-presets/
+    theme-preset-portfolio/
+    theme-preset-documentation/
+    theme-preset-project/
+    theme-preset-statement/
     media-and-surfaces/
     sitewide-content/
 ```
@@ -73,22 +76,23 @@ examples/
 `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 routes.
-- `dog-shelter-multi-page/`: ordered routes with route-local content and
+- `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-presets/`: one route per complete built-in theme preset, without
-  overrides.
+- `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 identity, navigation, banner stacks,
-  dismissal and footer content shared across routes.
+- `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 route.
+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

package/docs/engine-development.md

@@ -185,28 +185,25 @@ and commit their updated `package-lock.json`.
 
 ## Rendering Notes
 
-The renderer builds the homepage at `/` and optional first-level routes from
-`site/routes/<NNN-route-id>/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 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

package/docs/getting-started.md

@@ -69,50 +69,55 @@ Leave the development server running while you complete the next steps.
 
 ## 2. Replace The Homepage Content
 
-Replace `site/content.md` with:
+Replace `site/pages/000-home/content.md` with:
 
 ```md
 ---
-title: My first Norna site
-description: A website built from plain files.
+page:
+  description: A website built from plain files.
 ---
 
-## Welcome {#welcome}
+# 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.
 ```
 
-Each `##` heading is a page section. Its explicit `{#section-id}` gives the
-section a stable identity and is required by Norna.
+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 single-page navigation should link to those two sections. You should not
+the section navigation should link to those two sections. You should not
 need to restart the server.
 
-## 3. Set The Shared Identity
+## 3. Set Shared Content
 
 Replace `site/sitewide-content.yaml` with:
 
 ```yaml
-navigation:
-  label: My first Norna site
 footer:
   copyrightMessage: My first Norna site.
 ```
 
-The navigation label and footer are site-wide content rather than page
-sections. If you add routes later, they inherit these values.
+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 Identity Is Shared
+### Checkpoint: The Footer Is Shared
 
-The navigation should now display `My first Norna site`. The footer should show
-the new message.
+The navigation should use `My first Norna site` from `content.md`. The footer
+should show the new message.
 
 ## 4. Choose A Complete Theme
 
@@ -158,7 +163,7 @@ build.
 ## What To Do Next
 
 - [Add and manage images](content.md#norna-blocks)
-- [Add another page](routes.md)
+- [Add another page](pages.md)
 - [Inspect and adjust the theme](theme.md)
 - [Configure the public URL](configuration.md)
 - [Publish with GitHub Pages](publishing.md)

package/docs/images-and-metadata.md

@@ -12,15 +12,17 @@ Norna-managed local images are referenced from Markdown with
 Homepage source images live under:
 
 ```text
-site/images/<section-id>/
+site/pages/000-home/images/
 ```
 
-Route source images live under:
+Images for any page, including nested pages, live directly under that page:
 
 ```text
-site/routes/<NNN-route-id>/images/<section-id>/
+site/pages/<NNN-page-id>/pages/<NNN-page-id>/images/
 ```
 
+The number of nested `pages/` segments follows the page hierarchy.
+
 Supported source extensions:
 
 - `.jpg`
@@ -52,11 +54,12 @@ prompt: Short prompt or editing note.
 -->
 ```
 
-Filenames do not have to be globally unique for the site to be valid.
-Automatic sync only moves misplaced files when the filename identifies exactly
-one source candidate across the site's page and route image roots, and when the
-move will not break another reference. If the move crosses page or route image
-roots, `content:sync` requires a clean Git working tree before writing.
+Each filename identifies one managed source image within its page. The same
+filename may be used by another page. Automatic sync only moves misplaced
+files when the filename identifies exactly one source candidate across all
+page image roots, and when the move will not break another reference. If the
+move crosses page image roots, `content:sync` requires a clean Git working tree
+before writing.
 
 ## Markdown Images
 
@@ -139,7 +142,7 @@ copyright metadata.
 Generated WebP files are created with ImageMagick using `-strip`, so embedded
 metadata is not a publication mechanism for generated variants. Keep licensing,
 credits, copyright notices, alt text, and captions in site-owned files such as
-`site/content.md`, route content files, `COPYRIGHT.md`, or other site
+`site/pages/000-home/content.md`, page content files, `COPYRIGHT.md`, or other site
 documentation.
 
 If a site wants embedded metadata in original source files, that process is

package/docs/pages.md

@@ -0,0 +1,190 @@
+# Pages
+
+Every Norna page is a directory under `site/pages/` with its own `content.md`.
+The same model is used for the homepage, top-level areas, and nested pages.
+
+```text
+site/pages/
+|-- 000-home/
+|   `-- content.md
+|-- 010-guides/
+|   |-- content.md
+|   `-- pages/
+|       `-- 010-installation/
+|           `-- content.md
+`-- 020-reference/
+    `-- content.md
+```
+
+Pages use the same Markdown H1, optional metadata, sections, Norna blocks, and
+managed-image model. See [Content](content.md) for what belongs inside
+`content.md`.
+
+## Homepage And Top-Level Pages
+
+The homepage is required at:
+
+```text
+site/pages/000-home/content.md
+```
+
+It builds to `/`. The `000` prefix is reserved for `000-home`, and Home cannot
+contain a nested `pages/` directory. Home is the site's front door, not the
+parent of every page.
+
+Other directories directly under `site/pages/` are top-level navigation roots.
+For example, `site/pages/010-guides/content.md` builds to `/guides/`. Place
+further pages under the nearest meaningful non-home page.
+
+## Nested Pages
+
+A page may contain a `pages/` directory:
+
+```text
+site/pages/010-guides/
+|-- content.md
+`-- pages/
+    `-- 020-workflows/
+        |-- content.md
+        `-- pages/
+            `-- 010-local/
+                `-- content.md
+```
+
+This produces:
+
+```text
+/guides/
+/guides/workflows/
+/guides/workflows/local/
+```
+
+Each directory in the chain is a real page and therefore needs its own
+`content.md`. Empty grouping directories are not part of the page model.
+
+## Directory Names, Order, And URLs
+
+Page directories use:
+
+```text
+NNN-page-id
+```
+
+`NNN` is a three-digit sibling presentation order. `page-id` becomes that
+page's URL segment. Valid ordinary page names include:
+
+```text
+010-getting-started
+020-concepts
+120-api-reference
+```
+
+Invalid names include:
+
+```text
+10-about
+000-about
+010_About
+010-About
+010-about-
+010-about--team
+```
+
+The page id may contain only lowercase `a-z`, numbers, and single hyphens
+between alphanumeric groups. The numeric prefix is not part of the URL.
+Renaming `030-contact/` to `015-contact/` changes its order among siblings but
+keeps the URL segment `contact`.
+
+Sibling page ids and numeric orders must be unique. Reusing the same id below a
+different parent is valid because the complete URL remains different.
+
+## Page Content
+
+A minimal page is ordinary Markdown:
+
+```md
+---
+page:
+  description: Installation instructions.
+---
+
+# Installation
+
+Introductory text.
+
+## Requirements {#requirements}
+
+Text...
+```
+
+The H1 supplies the visible page title, document title, and navigation label.
+`page.description` is optional metadata and is not rendered. H2 and H3 headings
+provide page-local navigation according to the selected navigation model.
+
+## Navigation
+
+Home and listed top-level pages appear in global navigation. Child pages appear
+in the local hierarchy for their top-level area. Breadcrumbs show actual parent
+pages; Home is not added as an artificial ancestor.
+
+The numeric prefix controls order among siblings. Set `navigation.listed` to
+`false` in a non-home page's frontmatter when the page should remain public but
+not appear in generated navigation:
+
+```yaml
+navigation:
+  listed: false
+```
+
+Home is always listed. By default, Norna chooses navigation from the site
+structure:
+
+- one listed page uses section navigation;
+- a shallow hierarchy uses top navigation;
+- deeper page or heading hierarchies use tree navigation.
+
+The site-wide `navigation.mode` in `config.yaml` can explicitly select
+`automatic`, `sections`, `top`, or `tree`. See
+[Configuration](configuration.md#navigation).
+
+## Page Images
+
+Managed images belong directly to the page that references them:
+
+```text
+site/pages/010-guides/pages/020-workflows/images/diagram.svg
+```
+
+The Markdown block still uses only the filename:
+
+````md
+```norna-image-stack
+- image: diagram.svg
+  alt: The local workflow.
+```
+````
+
+Run `norna content:check` to find missing or misplaced images and
+`norna content:sync` to move unambiguous files into the expected page image
+root. Cross-page writes require a clean Git working tree and never guess when a
+filename has multiple possible sources.
+
+## Page Themes
+
+The root `site/theme.yaml` owns the site's visual identity: preset, palette,
+shape, typography, page frame, and navigation presentation.
+
+An optional page-local `theme.yaml` may adjust only:
+
+- `layout.textWidth`
+- `layout.contentSpacing`
+- managed-image sizing under `images`
+- `sections.backgroundPattern`
+
+These values are inherited by descendant pages and merged with more local page
+settings. Page themes cannot select presets or change site colors, fonts,
+shape, page width, gutters, or navigation. See [Theme](theme.md#page-themes).
+
+Page directories also cannot contain `config.yaml` or
+`sitewide-content.yaml`; technical configuration and shared editorial content
+remain at the selected site's top level.