@janga/norna 0.7.6 → 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

@@ -4,9 +4,9 @@
 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
 
@@ -61,8 +61,6 @@ title: About
 description: About this site.
 navigation:
   label: About
-sections:
-  - id: intro
 ---
 
 ## Intro {#intro}
@@ -99,14 +97,13 @@ Route images live under the physical route directory:
 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

@@ -41,8 +41,9 @@ 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/<NNN-route-id>/route-content.md`: optional route page files.
   See [Routes](routes.md).
@@ -50,7 +51,7 @@ Version these files in a site repository:
   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

@@ -4,7 +4,7 @@ description: A small norna example with free dog images.
 navigation:
   label: Dog site!
 sections:
-  - id: black-dogs
+  black-dogs:
     presentation:
       typography:
         preset: statement
@@ -12,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"
@@ -29,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:
@@ -55,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}
@@ -104,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
@@ -126,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.
@@ -141,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.
@@ -152,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/010-dog-care/route-content.md

@@ -4,15 +4,13 @@ description: A small route for testing multi-page norna navigation.
 navigation:
   label: Dog care
 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}