@janga/norna 0.7.5 → 0.7.7

package/docs/images-and-metadata.md

@@ -1,26 +1,78 @@
 # Images And Metadata
 
-This document describes the generic image pipeline. Site repositories own their
+This document describes Norna's image pipeline. Site repositories own their
 source images and any copyright or licensing policy for those images.
 
-## Source Images
+## Managed Source Images
 
-Source images live under `site/images/<section-id>/` and are referenced from
-`site/content.md` by filename only.
+Norna-managed local images are referenced from Markdown with
+`norna-image-stack` or `norna-image-carousel` blocks. See
+[Content](content.md#image-blocks) for the block syntax.
+
+Homepage source images live under:
+
+```text
+site/images/<section-id>/
+```
+
+Route source images live under:
+
+```text
+site/routes/<NNN-route-id>/images/<section-id>/
+```
 
 Supported source extensions:
 
 - `.jpg`
 - `.jpeg`
 - `.png`
+- `.svg`
+
+Image block references use only the filename:
+
+````md
+```norna-image-stack
+- image: portrait.jpg
+  alt: Optional alt text.
+  caption: Optional caption.
+```
+````
 
-Image filenames must be globally unique under `site/images/`. The content and
-image scripts reject duplicate filenames because image rows identify images by
-filename only.
+`alt` and `caption` are optional. If `alt` is omitted, Norna renders an empty
+alt attribute.
+
+For generated or edited images, keep provenance near the image in a source-only
+comment. Norna removes these comments from rendered HTML:
+
+```md
+<!-- norna-image-provenance:
+image: portrait.jpg
+source: generated
+prompt: Short prompt or editing note.
+-->
+```
 
-## Generated Variants
+Filenames do not have to be globally unique for the site to be valid.
+Automatic sync only moves files when the filename identifies exactly one source
+candidate within the current page or route.
 
-`npm run norna:images` and `npm run norna:build` generate WebP files in:
+## Markdown Images
+
+Use ordinary Markdown images for external images or static public assets:
+
+```md
+![External image](https://example.com/image.jpg)
+![Public asset](/favicon.svg)
+```
+
+Relative local Markdown images such as `![Portrait](portrait.jpg)` are not
+managed by Norna. `content:check` warns about them because Norna cannot
+validate, process, or sync those files through the image pipeline.
+
+## Generated Variants And Static SVG
+
+For raster images, `npm run norna:images` and `npm run norna:build` generate
+WebP files in:
 
 ```text
 site/.norna/public/images/generated/
@@ -46,6 +98,19 @@ example-work-1a2b3c4d-1440.webp
 When a source image changes, the generated URL changes too. This avoids stale
 browser, CDN, and GitHub Actions cache entries at the old URL.
 
+SVG files are managed by the same Markdown image blocks, validation and sync
+model, but they are not rasterized and do not get WebP variants. Norna copies
+the SVG source to:
+
+```text
+site/.norna/public/images/original/
+```
+
+The copied SVG filename includes the source hash. If the SVG has a `viewBox` or
+numeric `width` and `height`, Norna stores that ratio in the image manifest so
+the existing image layout can size it like other images. If no intrinsic aspect
+ratio can be read, the SVG is still rendered directly.
+
 ## Manifest
 
 The generated image manifest is:
@@ -54,13 +119,15 @@ The generated image manifest is:
 site/.norna/generated-images.json
 ```
 
-It is versioned site state. It stores source hashes, original dimensions,
-output version, and generated variant paths. The image pipeline reuses generated
-files only when the manifest entry matches the current source hash and output
-version, and all expected variant files exist.
+It is versioned site state. For raster images, it stores source hashes,
+original dimensions, output version, and generated variant paths. For static
+SVG images, it stores the source hash, copied public path, output version, and
+intrinsic dimensions when they can be read. The image pipeline reuses generated
+or copied files only when the manifest entry matches the current source hash
+and output version, and all expected output files exist.
 
-Generated files under `site/.norna/public/` are build-preparation output
-and should not be versioned.
+Generated files under `site/.norna/public/` are build-preparation output and
+should not be versioned.
 
 ## Metadata Behavior
 
@@ -70,10 +137,35 @@ 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`, `COPYRIGHT.md`, or other site documentation.
+`site/content.md`, route content files, `COPYRIGHT.md`, or other site
+documentation.
 
 If a site wants embedded metadata in original source files, that process is
-outside the current `norna` command surface.
+outside the current Norna command surface.
+
+## AI-Generated Images
+
+For AI-generated images, keep provenance and the generation prompt in a
+Markdown comment near the image block. This makes the image maintainable as
+content: future editors can understand where it came from and regenerate or
+revise it without reverse-engineering the asset.
+
+````md
+<!--
+AI image prompt for workflow.png:
+A clean editorial illustration of ordinary project files becoming a small
+static website, restrained colors, readable composition, no text in the image.
+-->
+
+```norna-image-stack
+- image: workflow.png
+  alt: Abstract illustration of project files becoming a website.
+  caption: Generated illustration.
+```
+````
+
+This is a maintenance rule for real editorial images. It is not necessary for
+throwaway test fixtures or examples where the prompt has no practical value.
 
 ## GitHub Actions Cache
 
@@ -83,6 +175,6 @@ The starter workflow caches:
 site/.norna/public/images/generated
 ```
 
-The cache key should include `site/.norna/generated-images.json` so
-unchanged generated variants can be restored during deploy. With a cache miss or
-a changed source hash, variants are rebuilt from source images.
+The cache key should include `site/.norna/generated-images.json` so unchanged
+generated variants can be restored during deploy. With a cache miss or a
+changed source hash, variants are rebuilt from source images.

package/docs/routes.md

@@ -1,19 +1,56 @@
 # Routes
 
 `site/content.md` is the homepage and builds to `/`. Optional route pages live
-under `site/routes/<route-folder>/route-content.md` and build to first-level
+under `site/routes/<NNN-route-id>/route-content.md` and build to first-level
 URLs.
 
-Routes use the same page frontmatter, section frontmatter, image rows, and
-Markdown section model as the homepage. See [Content](content.md) for the page
-and section model.
+Routes use the same page frontmatter, optional section metadata, Norna image
+blocks, and Markdown section model as the homepage. See [Content](content.md)
+for the page and section model.
+
+## Route Directory Format
+
+Route directories must use:
+
+```text
+NNN-route-id
+```
+
+`NNN` is a three-digit presentation order from `001` through `999`.
+`route-id` becomes the route identity and URL segment.
+
+Valid examples:
+
+```text
+010-getting-started
+020-concepts
+120-api-reference
+```
+
+Invalid examples:
+
+```text
+10-about
+000-home
+010_About
+010-About
+010-about-
+010-about--team
+```
+
+The route id may contain only lowercase `a-z`, numbers, and single hyphens
+between alphanumeric groups. The numeric prefix is not part of the route id or
+URL.
+
+Renaming `030-contact/` to `015-contact/` changes navigation order but keeps
+the route id `contact` and URL `/contact/`.
 
 ## Route File
 
 Add a first-level route by creating:
 
 ```text
-site/routes/about/route-content.md
+site/routes/010-about/route-content.md
 ```
 
 Minimal route page:
@@ -24,9 +61,6 @@ title: About
 description: About this site.
 navigation:
   label: About
-  order: 20
-sections:
-  - id: intro
 ---
 
 ## Intro {#intro}
@@ -36,28 +70,14 @@ Text...
 
 The example above builds to `/about/`.
 
-## Slug
-
-If `slug` is omitted, the route folder name is used. If `slug` is set, it must
-use lowercase letters, numbers, and hyphens.
-
-```yaml
-slug: about-the-work
-```
-
-Keep the route folder and `slug` aligned unless you intentionally need a
-different URL.
-
-The homepage ignores `slug`.
-
 ## Navigation
 
 `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.
+
+Route order comes from the directory prefix. The homepage is always first.
 
 Current route navigation is intended for small sites. This guidance may change
 as route support matures, but the present model is:
@@ -71,20 +91,19 @@ as route support matures, but the present model is:
 
 ## Route Images
 
-Route images live under the route:
+Route images live under the physical route directory:
 
 ```text
-site/routes/about/images/intro/image.jpg
+site/routes/010-about/images/intro/image.jpg
 ```
 
-Image references in route frontmatter still use only the filename:
+Image references in route content still use only the filename:
 
-```yaml
-sections:
-  - id: intro
-    gallery:
-      - image: image.jpg
-        alt: "Intro image."
+````md
+```norna-image-stack
+- image: image.jpg
+  alt: Intro image.
 ```
+````
 
 The image directory segment after `images/` should match the section id.

package/docs/site-structure.md

@@ -15,7 +15,7 @@ site/
 |-- images/
 |   `-- <section-id>/
 |-- routes/
-|   `-- <route-folder>/
+|   `-- <NNN-route-id>/
 |       |-- route-content.md
 |       `-- images/
 |           `-- <section-id>/
@@ -41,16 +41,17 @@ Version these files in a site repository:
   image sizing, font, typography defaults, colors, inline styles, and frame
   colors.
   See [Theme](theme.md).
-- `site/content.md`: homepage page file with editable content, section
-  definitions, image rows, alt text, and captions. See [Content](content.md).
+- `site/content.md`: homepage page file with editable content, Markdown
+  sections, optional section metadata, image blocks, alt text, and captions.
+  See [Content](content.md).
 - `site/images/<section-id>/`: original source images.
-- `site/routes/<route-folder>/route-content.md`: optional route page files.
+- `site/routes/<NNN-route-id>/route-content.md`: optional route page files.
   See [Routes](routes.md).
-- `site/routes/<route-folder>/images/<section-id>/`: original source images
+- `site/routes/<NNN-route-id>/images/<section-id>/`: original source images
   for that route page.
 - `site/public/`: site-specific static public files.
 - `site/.norna/generated-images.json`: generated image manifest used to
-  decide whether WebP variants can be reused.
+  decide whether WebP variants and copied managed SVG files can be reused.
 - `.github/workflows/deploy.yml`: site-owned GitHub Pages workflow.
 - `package.json` and `package-lock.json`: scripts and pinned engine dependency.
 

package/docs/theme.md

@@ -73,9 +73,9 @@ navigation:
   `desktop` / `mobile` values.
 - `density`: default structural spacing profile. Allowed values are `compact`,
   `normal`, and `airy`.
-- `spacing`: optional structural spacing overrides for sections and image
-  rows. Every spacing value accepts either one CSS length for all viewports or
-  `desktop` / `mobile` values.
+- `spacing`: optional structural spacing overrides for sections and Norna
+  image blocks. Every spacing value accepts either one CSS length for all
+  viewports or `desktop` / `mobile` values.
 
 Example:
 
@@ -104,8 +104,8 @@ Spacing keys:
 - `firstSectionTop`: space above the first section heading.
 - `sectionGap`: space above each following section.
 - `finalSectionBottom`: space below the final section.
-- `bodyToImages`: space from section body text to image rows.
-- `imageGap`: space between image rows.
+- `bodyToImages`: space from section body text to Norna image blocks.
+- `imageGap`: space between stacked images or carousel blocks.
 
 Text-near spacing, such as spacing after headings, spacing before Markdown
 subheadings, paragraph spacing, and caption spacing, belongs to
@@ -206,11 +206,12 @@ presentation:
         paragraphSpacing: 1em
 ```
 
-Section-specific presentation belongs under `sections[].presentation`:
+Section-specific presentation belongs under
+`sections.<section-id>.presentation`:
 
 ```yaml
 sections:
-  - id: intro
+  intro:
     presentation:
       backgroundColor: "#161616"
       textColor: "#ffffff"

package/docs/typography.md

@@ -132,10 +132,10 @@ typography:
 ```
 
 A page-level `presentation.typography.preset` changes the typographic character
-for that page. A section-level `sections[].presentation.typography.preset`
-changes the typographic character for that section. `rhythm` is inherited
-separately, so changing preset does not change spacing unless `rhythm` is also
-set.
+for that page. A section-level
+`sections.<section-id>.presentation.typography.preset` changes the typographic
+character for that section. `rhythm` is inherited separately, so changing
+preset does not change spacing unless `rhythm` is also set.
 
 If a section sets `typography.rhythm`, that section changes text-near spacing.
 If a section only sets `typography.overrides`, it keeps the resolved page
@@ -145,7 +145,7 @@ Example section override:
 
 ```yaml
 sections:
-  - id: intro
+  intro:
     presentation:
       typography:
         preset: statement

package/examples/dog-gallery/site/content.md

@@ -3,9 +3,8 @@ title: Local Dog Example
 description: A small norna example with free dog images.
 navigation:
   label: Dog site!
-  order: 10
 sections:
-  - id: black-dogs
+  black-dogs:
     presentation:
       typography:
         preset: statement
@@ -13,16 +12,7 @@ sections:
           headings:
             h2:
               size: xlarge
-    gallery:
-      - image: photo-of-a-black-dog.jpg
-        alt: "A black dog sitting outdoors and looking at the camera."
-        caption:
-          "Photo of a dog. ContaDeletada2906, CC0 1.0, via Wikimedia Commons."
-      - image: black-puppy-meadow.png
-        alt:
-          "A black puppy standing in a grassy meadow and looking at the camera."
-        caption: "AI-generated image."
-  - id: summer-dogs
+  summer-dogs:
     visible:
       from: "2026-08-01"
       until: "2026-09-01"
@@ -30,21 +20,11 @@ sections:
       backgroundColor: "#181818"
       typography:
         preset: compact-gallery
-    gallery: []
-  - id: brown-dogs
+  brown-dogs:
     presentation:
       typography:
         preset: text-forward
-    gallery:
-      - image: brown-dog.jpg
-        alt: "A brown dog looking directly at the camera."
-        caption: "DogBrown. Frank-3, CC0 1.0, via Wikimedia Commons."
-      - image: dog-accompanies-master.jpg
-        alt: "A man walks outdoors with a dog at his side."
-        caption:
-          "Dog accompanies his master. Steve Hillebrand, U.S. Fish and Wildlife
-          Service, public domain."
-  - id: golden-dogs
+  golden-dogs:
     presentation:
       typography:
         overrides:
@@ -56,33 +36,12 @@ sections:
           body:
             lineHeight: 1.58
             paragraphSpacing: 1em
-    gallery:
-      - image: golden-retriever.jpg
-        alt: "A golden retriever standing outdoors."
-        caption: "Golden Retriever. Ribo, public domain, via Wikimedia Commons."
-      - image: toller-puppy.jpg
-        alt:
-          "A young Nova Scotia Duck Tolling Retriever puppy sitting on grass."
-        caption:
-          "Nova Scotia Duck Tolling Retriever puppy. RM, public domain, via
-          Wikimedia Commons."
-  - id: white-dogs
+  white-dogs:
     presentation:
       typography:
         overrides:
           caption:
             spacingBefore: 0.35em
-    gallery:
-      - carousel:
-          - image: white-cute-dog.jpg
-            alt: "A white dog looking toward the camera."
-            caption:
-              "White cute dog. Neal Ziring, public domain, via Wikimedia
-              Commons."
-          - image: white-puppy-garden.png
-            alt: "A fluffy white puppy standing on grass in a garden."
-            caption: "AI-generated image."
-  - id: sources
 ---
 
 ## Black Dogs {#black-dogs}
@@ -105,6 +64,15 @@ This `####` heading should follow `typography.headings.h4`.
 Curabitur blandit tempus porttitor. Donec id elit non mi porta gravida at eget
 metus. Praesent commodo cursus magna, vel scelerisque nisl consectetur et.
 
+```norna-image-stack
+- image: photo-of-a-black-dog.jpg
+  alt: A black dog sitting outdoors and looking at the camera.
+  caption: Photo of a dog. ContaDeletada2906, CC0 1.0, via Wikimedia Commons.
+- image: black-puppy-meadow.png
+  alt: A black puppy standing in a grassy meadow and looking at the camera.
+  caption: AI-generated image.
+```
+
 ## Summer Dogs {#summer-dogs}
 
 This temporary section is visible during August 2026. It is here to demonstrate
@@ -127,6 +95,15 @@ Maecenas sed diam eget risus varius blandit sit amet non magna. Morbi leo risus,
 porta ac consectetur ac, vestibulum at eros. Sed posuere consectetur est at
 lobortis.
 
+```norna-image-stack
+- image: brown-dog.jpg
+  alt: A brown dog looking directly at the camera.
+  caption: DogBrown. Frank-3, CC0 1.0, via Wikimedia Commons.
+- image: dog-accompanies-master.jpg
+  alt: A man walks outdoors with a dog at his side.
+  caption: Dog accompanies his master. Steve Hillebrand, U.S. Fish and Wildlife Service, public domain.
+```
+
 ## Golden Dogs {#golden-dogs}
 
 Golden-coated retrievers add a third image section and more scrolling depth.
@@ -142,6 +119,15 @@ Nulla vitae elit libero, a pharetra augue. Integer posuere erat a ante venenatis
 dapibus posuere velit aliquet. Aenean eu leo quam. Pellentesque ornare sem
 lacinia quam venenatis vestibulum.
 
+```norna-image-stack
+- image: golden-retriever.jpg
+  alt: A golden retriever standing outdoors.
+  caption: Golden Retriever. Ribo, public domain, via Wikimedia Commons.
+- image: toller-puppy.jpg
+  alt: A young Nova Scotia Duck Tolling Retriever puppy sitting on grass.
+  caption: Nova Scotia Duck Tolling Retriever puppy. RM, public domain, via Wikimedia Commons.
+```
+
 ## White Dogs {#white-dogs}
 
 A white dog completes the colour-based image sequence.
@@ -153,6 +139,15 @@ Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Lorem ipsum
 dolor sit amet, consectetur adipiscing elit. Donec sed odio dui. Vestibulum id
 ligula porta felis euismod semper.
 
+```norna-image-stack
+- image: white-cute-dog.jpg
+  alt: A white dog looking toward the camera.
+  caption: White cute dog. Neal Ziring, public domain, via Wikimedia Commons.
+- image: white-puppy-garden.png
+  alt: A fluffy white puppy standing on grass in a garden.
+  caption: AI-generated image.
+```
+
 ## Sources {#sources}
 
 Most images are sourced from Wikimedia Commons pages that list CC0 or

package/examples/dog-gallery/site/routes/{dog-care → 010-dog-care}/route-content.md

@@ -3,17 +3,14 @@ title: Dog care
 description: A small route for testing multi-page norna navigation.
 navigation:
   label: Dog care
-  order: 20
 sections:
-  - id: daily-rhythm
+  daily-rhythm:
     presentation:
       typography:
         overrides:
           headings:
             h2:
               size: large
-  - id: calm-training
-  - id: media-notes
 ---
 
 ## Daily rhythm {#daily-rhythm}

package/fixtures/basic/site/content.md

@@ -2,10 +2,8 @@
 title: Fixture Site
 description: Minimal cli-gallery fixture site.
 sections:
-  - id: intro
-    gallery: []
-  - id: work
-    gallery: []
+  intro: {}
+  work: {}
 
 ---
 ## Intro {#intro}