@janga/norna 0.7.17 → 0.7.18

package/README.md

@@ -52,15 +52,21 @@ site/
 |-- config.yaml
 |-- theme.yaml
 |-- sitewide-content.yaml
-|-- content.md
-|-- images/
 |-- pages/
+|   |-- 000-home/
+|   |   |-- content.md
+|   |   `-- images/
+|   `-- 010-guide/
+|       |-- content.md
+|       `-- pages/
+|           `-- 010-installation/
 `-- public/
 ```
 
-- `content.md` holds the homepage title, introduction, and sections.
-- `images/` holds the homepage's managed source images.
-- `pages/` adds pages, each with content and optional local images and theme.
+- `pages/000-home/content.md` is the required homepage at `/`.
+- Other top-level directories under `pages/` are global navigation roots.
+- A page may contain local images, limited presentation settings, and nested
+  child pages under its own `pages/` directory.
 - `theme.yaml` normally selects one complete visual preset.
 - `sitewide-content.yaml` holds shared logo display settings, banners, and footer content.
 - `config.yaml` holds the public URL and optional language and scroll behavior.
@@ -89,7 +95,10 @@ documentation.
 | --- | --- | --- |
 | Dog shelter, single page | [Open demo](https://janga.github.io/norna/examples/complete-sites/dog-shelter-single-page/) | [View files](examples/complete-sites/dog-shelter-single-page/) |
 | Dog shelter, multi-page | [Open demo](https://janga.github.io/norna/examples/complete-sites/dog-shelter-multi-page/) | [View files](examples/complete-sites/dog-shelter-multi-page/) |
-| Theme presets | [Open demo](https://janga.github.io/norna/examples/feature-demos/theme-presets/) | [View files](examples/feature-demos/theme-presets/) |
+| Portfolio preset | [Open demo](https://janga.github.io/norna/examples/feature-demos/theme-preset-portfolio/) | [View files](examples/feature-demos/theme-preset-portfolio/) |
+| Documentation preset | [Open demo](https://janga.github.io/norna/examples/feature-demos/theme-preset-documentation/) | [View files](examples/feature-demos/theme-preset-documentation/) |
+| Project preset | [Open demo](https://janga.github.io/norna/examples/feature-demos/theme-preset-project/) | [View files](examples/feature-demos/theme-preset-project/) |
+| Statement preset | [Open demo](https://janga.github.io/norna/examples/feature-demos/theme-preset-statement/) | [View files](examples/feature-demos/theme-preset-statement/) |
 | Media and surfaces | [Open demo](https://janga.github.io/norna/examples/feature-demos/media-and-surfaces/) | [View files](examples/feature-demos/media-and-surfaces/) |
 | Sitewide content | [Open demo](https://janga.github.io/norna/examples/feature-demos/sitewide-content/) | [View files](examples/feature-demos/sitewide-content/) |
 

package/bin/norna-cli.mjs

@@ -16,7 +16,7 @@ Commands:
   dev:stop               Stop local dev server
   check                  Validate configuration and content
   config:check           Validate site/config.yaml
-  content:check          Validate site/content.md and image references
+  content:check          Validate page content and managed image references
   content:sync           Move misplaced Norna-managed images and refresh generated images
   theme:presets          List available theme presets and their intended uses
   theme:export           Export a commented theme preset reference

package/docs/README.md

@@ -27,9 +27,12 @@ site/
 |-- config.yaml
 |-- theme.yaml
 |-- sitewide-content.yaml
-|-- content.md
-|-- images/
 |-- pages/
+|   |-- 000-home/
+|   |   |-- content.md
+|   |   `-- images/
+|   `-- 010-guide/
+|       `-- content.md
 `-- public/
 ```
 
@@ -39,12 +42,11 @@ site/
   overrides.
 - [`sitewide-content.yaml`](sitewide-content.md): shared logo display settings,
   banners, and footer.
-- [`content.md`](content.md): Markdown page title, optional metadata, sections,
-  prose, notes, and Norna blocks.
-- [`images/`](images-and-metadata.md): managed source formats, variants, sync,
-  and generated image state.
-- [`pages/`](pages.md): additional pages, ordering, URLs, page themes, and
-  page-local images.
+- [`pages/`](pages.md): Home, top-level areas, nested pages, ordering, and URLs.
+- [`content.md`](content.md): the content file inside every page directory,
+  containing its title, optional metadata, sections, prose, notes, and blocks.
+- [`images/`](images-and-metadata.md): managed images kept inside the page that
+  references them, plus variants, sync, and generated image state.
 - [`public/`](public-files.md): navigation logos, favicons, and other static
   files copied without managed-image processing.
 - [Generated files](site-files.md#generated-files): `site/.norna/public/`,
@@ -82,7 +84,7 @@ required, optional, convention-discovered, versioned, or generated.
 
 - [Choose a complete theme preset](theme.md#theme-presets)
 - [Inspect and override a preset](theme.md#overrides)
-- [Give a page a different theme](theme.md#page-themes)
+- [Adjust limited presentation for a page subtree](theme.md#page-themes)
 - [Adjust typography](typography.md)
 
 ### Check, Build, And Publish

package/docs/configuration.md

@@ -13,7 +13,7 @@ url: https://example.com/
 Norna deliberately keeps this file small. Visual choices belong in
 [`theme.yaml`](theme.md), shared editorial content belongs in
 [`sitewide-content.yaml`](sitewide-content.md), and page content belongs in
-[`content.md`](content.md).
+[`pages/*/content.md`](content.md).
 
 ## `url`
 
@@ -58,6 +58,26 @@ would be misleading.
 Interface labels are part of the engine and are not configured individually.
 Editorial text remains in page content and `sitewide-content.yaml`.
 
+## `navigation`
+
+`navigation.mode` selects the site-wide navigation model:
+
+- `automatic`: choose from the discovered page and heading structure. This is
+  the default.
+- `sections`: navigate headings on a single page.
+- `top`: use the sticky top navigation for a shallow multi-page site.
+- `tree`: combine global top-level navigation with a local page hierarchy.
+
+```yaml
+url: https://example.com/
+navigation:
+  mode: automatic
+```
+
+Navigation behavior is technical and site-wide. It cannot be configured in
+`theme.yaml` or in an individual page. See [Pages](pages.md#navigation) for the
+relationship between Home, top-level pages, child pages, and headings.
+
 ## `scrollBehavior`
 
 - Purpose: select native same-page anchor movement.
@@ -80,6 +100,8 @@ requests reduced motion always get immediate anchor movement.
 ```yaml
 url: https://example.com/
 language: en-GB
+navigation:
+  mode: automatic
 scrollBehavior: instant
 ```
 
@@ -110,7 +132,8 @@ norna --site-dir presentation build
 
 If `NORNA_SITE_DIR` is set to an empty value, commands fail. Relative site
 directories are resolved by walking upward from the invocation directory until
-the selected directory contains `config.yaml` and `content.md`.
+the selected directory contains `config.yaml` and
+`pages/000-home/content.md`.
 
 Without an explicit selection, the current directory itself can be the site
 directory when it contains those two files. Otherwise Norna walks upward for a

package/docs/content.md

@@ -1,11 +1,10 @@
 # Content
 
-`site/content.md` is the homepage file for a Norna site. Its Markdown H1 is
+`site/pages/000-home/content.md` is the homepage file for a Norna site. Its Markdown H1 is
 the page title. Optional page metadata can be added in YAML frontmatter.
 
-Additional pages use the same page model in
-`site/pages/<NNN-page-id>/content.md`. See [Pages](pages.md) for the
-page-specific rules.
+Additional and nested pages use the same page model in a page directory under
+`site/pages/`. See [Pages](pages.md) for the directory and nesting rules.
 
 Site-wide visual defaults belong in [Theme](theme.md). Typography profiles and
 overrides are described in [Typography](typography.md). Technical site settings
@@ -79,15 +78,25 @@ Markdown level 2 headings define the page sections and their order:
 ...
 ```
 
-Every section heading must have an explicit id:
+Norna derives a stable lowercase id from the heading text when no explicit id
+is present:
+
+```md
+## Work
+```
+
+Add an explicit id when a public anchor must remain stable even if the heading
+text changes:
 
 ```md
 ## Work {#work}
 ```
 
-The id must match `^[a-z0-9-]+$`. It is used for anchors and section
-navigation. The visible section navigation label comes from the Markdown
-heading text.
+Explicit ids must match `^[a-z0-9-]+$`. Derived and explicit ids are used for
+anchors and section navigation; the visible label still comes from the heading
+text. H3 headings use the same derivation for deeper local navigation. If two
+headings on one page resolve to the same id, `content:check` reports the page
+and both headings instead of guessing.
 
 Markdown section content starts at the level 2 heading and continues until the
 next level 2 heading. `###` and `####` headings are body subheadings within the
@@ -207,13 +216,13 @@ sizing is less predictable.
 Homepage images live under:
 
 ```text
-site/images/
+site/pages/000-home/images/
 ```
 
-Page images live under:
+Images for any page live directly under that page directory. For example:
 
 ```text
-site/pages/<NNN-page-id>/images/
+site/pages/010-guide/pages/020-installation/images/
 ```
 
 Image references in Norna managed image blocks use only the filename:
@@ -225,7 +234,7 @@ Image references in Norna managed image blocks use only the filename:
 ````
 
 If `portrait.jpg` is referenced anywhere on the homepage, its expected
-location is `site/images/portrait.jpg`. The same file may be referenced from
+location is `site/pages/000-home/images/portrait.jpg`. The same file may be referenced from
 more than one section on that page.
 
 Filenames must be unique within one page's image directory, but do not have to

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

@@ -26,7 +26,7 @@ information architecture.
 
 ## Order Of Work
 
-### 1. Stabilize The Page Tree
+### 1. Stabilize The Page Tree - Complete
 
 Finish and test nested page discovery independently of final navigation
 presentation. Establish deterministic rules for:
@@ -39,30 +39,79 @@ presentation. Establish deterministic rules for:
 
 Commit this foundation separately before broad theme or preset changes.
 
-### 2. Define The Navigation Contract
+The page tree now supports nested pages with deterministic directory parsing,
+URLs, ordering, ancestry, breadcrumbs, inherited page resources, and collision
+diagnostics.
 
-The intended information architecture is:
+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;
-- a separate `On this page` list for headings on the current page;
 - breadcrumbs for location and ancestry;
-- one unified mobile navigation containing the whole page hierarchy, with the
-  current branch expanded and current page marked.
-
-The exact contract is potentially difficult to evaluate at an abstract level.
-The maintainer therefore expects this phase to use executable test sites,
-focused automated tests, or clear illustrative examples. These artifacts
-should demonstrate short single-page sites, ordinary two-level sites, and
-deeper documentation-style hierarchies on both desktop and mobile before the
-contract is considered stable.
+- 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.
 
-### 3. Implement Navigation In Layers
+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:
 
@@ -72,10 +121,10 @@ Implement and verify the navigation model in this order:
 4. keyboard, focus, current-page, and progressive-enhancement behavior;
 5. visual evaluation at representative viewport sizes.
 
-Keep real links as the foundation. Client-side JavaScript should only enhance
-interaction that cannot be expressed adequately with HTML and CSS.
+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
+### 4. Refine Theme And Preset Responsibilities - Proof Of Concept
 
 Presets should control visual presentation, including:
 
@@ -94,6 +143,27 @@ 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
@@ -111,5 +181,6 @@ separate commits where practical.
 
 ## Immediate Checkpoint
 
-The current nested-page implementation should be reviewed, tested, and secured
-before work continues on the final navigation contract or preset model.
+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/site-examples-structure.md

@@ -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/
 ```
@@ -79,8 +82,9 @@ together in a realistic project:
 
 `feature-demos/` contains focused visual test benches:
 
-- `theme-presets/`: one page 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 logo handling, navigation, banner stacks,

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 pages from
-`site/pages/<NNN-page-id>/content.md`.
-
-Navigation has two separate levels:
-
-- Site navigation moves between the homepage and additional pages. It uses
-  normal page URLs and browser history.
-- Section 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 navigation support matures. For now,
-single-page sites should rely on section navigation only; small multi-page sites
-may combine site navigation and section 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
-section-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,7 +69,7 @@ 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
 ---
@@ -91,8 +91,8 @@ 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.
-Its explicit `{#section-id}` gives the section a stable identity and is
-required by Norna.
+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
 

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/
+site/pages/000-home/images/
 ```
 
-Page source images live under:
+Images for any page, including nested pages, live directly under that page:
 
 ```text
-site/pages/<NNN-page-id>/images/
+site/pages/<NNN-page-id>/pages/<NNN-page-id>/images/
 ```
 
+The number of nested `pages/` segments follows the page hierarchy.
+
 Supported source extensions:
 
 - `.jpg`
@@ -140,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`, page 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