@janga/norna 0.7.6 → 0.7.8

package/docs/getting-started.md

@@ -16,10 +16,13 @@ Install Playwright Chromium only when you plan to run navigation diagnostics:
 npx playwright install chromium
 ```
 
-## Create A Site Repository
+## Create A Site
 
-Create the site from the starter first, then install dependencies inside the
-new site directory:
+### Standalone Site
+
+Use a standalone setup when the website is its own project. Create the site
+from the starter first, then install dependencies inside the new site
+directory:
 
 ```sh
 cd path/to/your/projects
@@ -55,11 +58,33 @@ The starter contains:
 - `site/config.mjs`
 - `site/theme.md`
 - `site/content.md`
-- `site/images/work/.gitkeep`
 - `site/public/robots.txt`
 
 Commit the generated `package-lock.json` after the first install.
 
+### Embedded Site
+
+Use an embedded setup when a Norna site should live inside an existing Node or
+GitHub project:
+
+```sh
+cd existing-project
+npx @janga/norna@latest init . --type embedded --site-dir presentation
+npm install
+npm run norna:dev
+```
+
+The command looks different because the target is different. `.` means "add
+Norna to the current project" instead of creating a new directory.
+`--site-dir presentation` tells Norna to manage `presentation/` as the site
+directory instead of the default `site/`.
+
+Embedded setup keeps the surrounding project structure. It adds namespaced
+`norna:*` scripts so Norna does not take over the project's normal `build`,
+`test`, or deploy scripts.
+
+Relevant documentation: [Commands](commands.md), [Site Structure](site-structure.md).
+
 ## First Edits
 
 1. Edit `site/config.mjs` for the site's URL, language labels, GitHub
@@ -67,9 +92,11 @@ Commit the generated `package-lock.json` after the first install.
 2. Edit `site/theme.md` for site-wide layout, layout density, typography
    rhythm, image sizing, font, typography preset, colors, inline styles, and
    frame colors, or omit it to use engine defaults.
-3. Edit `site/content.md` for homepage title, description, sections, text,
-   image rows, page/section presentation overrides, alt text, and captions.
-4. Put source images under `site/images/<section-id>/`.
+3. Edit `site/content.md` for homepage title, description, Markdown sections,
+   text, Norna managed media blocks, page/section presentation overrides, alt
+   text, and captions.
+4. Put source images under `site/images/<section-id>/`, where `<section-id>`
+   matches a `## Section {#section-id}` heading in `site/content.md`.
 5. Add optional route pages under
    `site/routes/<NNN-route-id>/route-content.md`, for example
    `site/routes/010-about/route-content.md`.
@@ -78,10 +105,23 @@ Commit the generated `package-lock.json` after the first install.
 7. Run:
 
 ```sh
+npm run norna:config:check
+npm run norna:content:check
+npm run norna:sync
 npm run norna:check
 npm run build
 ```
 
+`norna:sync` moves misplaced referenced image files when the intended move is
+unambiguous. It can move images between sections and routes, but cross-route
+writes require a clean Git working tree so the operation is easy to roll back.
+Publishing is normally done by committing the site files and pushing them with
+Git; the starter GitHub Pages workflow runs the required checks before
+publishing.
+
+Relevant documentation: [Content](content.md), [Theme](theme.md),
+[Typography](typography.md), [Routes](routes.md), [Images And Metadata](images-and-metadata.md).
+
 ## Configure The Public URL
 
 For a custom domain or any site published at the web root, use:
@@ -104,13 +144,15 @@ site: {
 ```
 
 After that, content files may still use root-style internal links such as
-`/getting-started/` and `/workflow.svg`. Norna applies `site.basePath` during
+`/getting-started/` and `/favicon.svg`. Norna applies `site.basePath` during
 rendering so the built links work under the GitHub Pages project path.
 
 The starter includes a GitHub Pages workflow in `.github/workflows/deploy.yml`.
 In the GitHub repository settings, configure Pages to build from GitHub
 Actions.
 
+Relevant documentation: [Configuration](configuration.md), [Publishing](publishing.md).
+
 Read [Site Structure](site-structure.md), [Content](content.md),
 [Theme](theme.md), [Typography](typography.md), [Routes](routes.md), and
 [Configuration](configuration.md) before publishing a real site.

package/docs/images-and-metadata.md

@@ -1,26 +1,80 @@
 # 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`, `norna-image-carousel`, or `norna-card-list` blocks. See
+[Content](content.md#managed-media-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`
+
+Managed media block references use only the filename:
+
+````md
+```norna-image-stack
+- image: portrait.jpg
+  alt: Optional alt text.
+  caption: Optional caption.
+```
+````
+
+`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.
+-->
+```
+
+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.
 
-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.
+## Markdown Images
 
-## Generated Variants
+Use ordinary Markdown images for external images or static public assets:
+
+```md
+![External image](https://example.com/image.jpg)
+![Public asset](/favicon.svg)
+```
 
-`npm run norna:images` and `npm run norna:build` generate WebP files in:
+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 +100,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 media 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 +121,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 +139,38 @@ 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.
+```
+````
+
+The same provenance comment style can be used next to a `norna-image-carousel`
+or `norna-card-list` block when generated images are referenced there.
+
+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 +180,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,14 @@
 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 managed
+media blocks, and Markdown section model as the homepage. See
+[Content](content.md) for the page and section model.
+
+Route directories can contain route content, route-local images, and
+route-local presentation overrides in `route-content.md`. They cannot contain
+technical site configuration; technical configuration stays at the selected
+site directory's top-level `config.mjs`.
 
 ## Route Directory Format
 
@@ -61,8 +66,6 @@ title: About
 description: About this site.
 navigation:
   label: About
-sections:
-  - id: intro
 ---
 
 ## Intro {#intro}
@@ -99,14 +102,19 @@ 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.
+If the section id or route folder changes, run `norna content:check` to find
+misplaced images and `norna content:sync` to move unambiguous files into the
+expected section folder. `content:sync` can move images between route image
+roots when the filename is unambiguous across the site and the move will not
+break another reference; these cross-route writes require a clean Git working
+tree.

package/docs/site-structure.md

@@ -41,8 +41,10 @@ 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, managed media 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 +52,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.
 
@@ -81,8 +83,10 @@ In this repository:
 - `bin/norna-cli.mjs` dispatches public CLI commands.
 - `scripts/` contains validation, image, local preview, deploy, and test tools.
 - `src/` contains the Astro renderer, components, styles, and content schema.
-- `starters/basic/` is copied by `norna init <target-dir>` to create a
-  site repository.
+- `starters/basic/` is the default compact starter copied by
+  `norna init <target-dir>`.
+- `starters/project/` is a project-site starter used as a maintained example
+  for small project and developer-tool sites.
 - `fixtures/basic/site/` is used by engine regression tests.
 - `examples/dog-gallery/site/` is the local visual dog example used by demo
   builds and navigation diagnostics.

package/docs/theme.md

@@ -6,7 +6,8 @@ missing, built-in engine defaults are used.
 
 Page-level presentation in `site/content.md` and route page files is always an
 override on top of `site/theme.md`. Section-level presentation is an override
-on top of the resolved page presentation.
+on top of the resolved page presentation. Use those overrides for focused
+exceptions; the normal place for shared visual choices is `site/theme.md`.
 
 ## Minimal Theme
 
@@ -73,9 +74,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
+  managed media blocks. Every spacing value accepts either one CSS length for all
+  viewports or `desktop` / `mobile` values.
 
 Example:
 
@@ -104,8 +105,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 managed media 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 +207,14 @@ presentation:
         paragraphSpacing: 1em
 ```
 
-Section-specific presentation belongs under `sections[].presentation`:
+Section-specific presentation belongs under
+`sections.<section-id>.presentation`. Use it when one section genuinely needs
+different presentation; do not use `sections` to define section order or normal
+Markdown structure.
 
 ```yaml
 sections:
-  - id: intro
+  intro:
     presentation:
       backgroundColor: "#161616"
       textColor: "#ffffff"

package/docs/typography.md

@@ -5,8 +5,8 @@ presets, text rhythm, and optional overrides.
 
 The normal place to choose a site-wide typography preset and rhythm is the
 top-level `typography` block in `site/theme.md`.
-Page and section files may override the theme when a page or section needs a
-different presentation.
+Page and section files may override the theme when a focused exception is
+needed, but the normal workflow is to keep typography in `theme.md`.
 
 ## Presets
 
@@ -18,9 +18,8 @@ Available presets:
   short information blocks.
 - `text-forward`: more generous body text for pages where longer text carries
   more of the experience.
-- `statement`: tighter, more declarative line-height for introductions, first
-  sections, and short programmatic statements. Use it sparingly, usually as a
-  section override.
+- `statement`: tighter, more declarative line-height for short programmatic
+  statements. Use it sparingly, usually as a page or section exception.
 
 If theme typography is omitted, `quiet-gallery` is used.
 
@@ -132,10 +131,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 +144,7 @@ Example section override:
 
 ```yaml
 sections:
-  - id: intro
+  intro:
     presentation:
       typography:
         preset: statement

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

@@ -4,84 +4,10 @@ description: A small norna example with free dog images.
 navigation:
   label: Dog site!
 sections:
-  - id: black-dogs
-    presentation:
-      typography:
-        preset: statement
-        overrides:
-          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"
-    presentation:
-      backgroundColor: "#181818"
-      typography:
-        preset: compact-gallery
-    gallery: []
-  - id: 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
-    presentation:
-      typography:
-        overrides:
-          headings:
-            h2:
-              size: large
-            h3:
-              size: medium
-          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
-    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 +30,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 +61,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.
@@ -134,13 +78,21 @@ Cras justo odio, dapibus ac facilisis in, egestas eget quam.
 
 ### Training note
 
-This section overrides `headings.h2` and `headings.h3`, while keeping the
-site-wide `headings.h4` style.
+This `###` heading follows the site-wide `headings.h3` style.
 
 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 +104,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

@@ -3,16 +3,6 @@ title: Dog care
 description: A small route for testing multi-page norna navigation.
 navigation:
   label: Dog care
-sections:
-  - id: 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}