@janga/norna 0.7.5 → 0.7.7

package/README.md

@@ -25,15 +25,15 @@ A `norna` site is file-driven:
    base path, in `site/config.mjs`.
 3. The site keeps site-wide visual theme defaults, including layout, image
    sizing, font, typography, colors, and frame colors, in `site/theme.md`.
-4. The site keeps homepage content, section order, image rows, alt text, and
-   captions in `site/content.md`.
+4. The site keeps homepage content, Markdown section order, image blocks, alt
+   text, captions, and optional section metadata in `site/content.md`.
 5. Optional route pages live under
    `site/routes/<route-folder>/route-content.md`.
 6. Source images live under `site/images/<section-id>/` for the homepage, or
    under `site/routes/<route-folder>/images/<section-id>/` for a route.
 7. Static public files live under `site/public/`.
-8. `norna` validates the files, generates WebP variants, builds static
-   Astro pages, and can help publish the committed branch through GitHub Pages.
+8. `norna` validates the files, prepares managed images, builds static Astro
+   pages, and can help publish the committed branch through GitHub Pages.
 
 The default site directory is `site/`. Commands can also use another directory
 with `NORNA_SITE_DIR` or `norna --site-dir <path>`. Without an explicit site
@@ -75,7 +75,7 @@ Actions use the same engine version.
 
 - Create a site: [Getting Started](docs/getting-started.md)
 - Understand required site files: [Site Structure](docs/site-structure.md)
-- Edit sections and image rows: [Content](docs/content.md)
+- Edit sections and image blocks: [Content](docs/content.md)
 - Configure a site: [Configuration](docs/configuration.md)
 - Publish under a GitHub Pages project path:
   [`site.basePath`](docs/configuration.md#sitebasepath)

package/astro.config.mjs

@@ -1,14 +1,87 @@
 // @ts-check
+import { execFile } from 'node:child_process';
 import path from 'node:path';
+import { promisify } from 'node:util';
 import { defineConfig } from 'astro/config';
 import {
 	astroCacheDir,
 	astroDistDir,
 	astroPublicDir,
 	engineRoot,
+	generatedImagesManifestPath,
+	siteContentPath,
+	siteImagesDir,
+	siteProjectRoot,
+	siteRoutesDir,
 } from './scripts/lib/site-paths.mjs';
 import projectConfig from './scripts/lib/project-config.mjs';
 
+const execFileAsync = promisify(execFile);
+
+const isWithinDirectory = (parentDirectory, filePath) => {
+	const relativePath = path.relative(parentDirectory, filePath);
+	return relativePath === '' || (!relativePath.startsWith('..') && !path.isAbsolute(relativePath));
+};
+
+const runGenerateImages = () => execFileAsync(process.execPath, [path.join(engineRoot, 'scripts', 'generate-images.mjs')], {
+	cwd: siteProjectRoot,
+	maxBuffer: 1024 * 1024 * 10,
+});
+
+const nornaGeneratedImagesWatcher = () => ({
+	name: 'norna-generated-images-watcher',
+	configureServer(server) {
+		const manifestPath = path.resolve(generatedImagesManifestPath);
+		const watchedSourcePaths = [
+			siteContentPath,
+			siteImagesDir,
+			siteRoutesDir,
+		].map((watchedPath) => path.resolve(watchedPath));
+		let refreshTimer;
+		let refreshPromise = Promise.resolve();
+
+		const isRelevantSourcePath = (changedPath) => {
+			const resolvedPath = path.resolve(changedPath);
+			return watchedSourcePaths.some((watchedPath) => (
+				resolvedPath === watchedPath || isWithinDirectory(watchedPath, resolvedPath)
+			));
+		};
+
+		const refreshImages = () => {
+			refreshPromise = refreshPromise
+				.catch(() => {})
+				.then(async () => {
+					try {
+						await runGenerateImages();
+					} catch (error) {
+						const message = error instanceof Error ? error.message : String(error);
+						server.config.logger.error(`Norna image refresh failed:\n${message}`);
+					}
+				});
+		};
+
+		const scheduleRefreshImages = (changedPath) => {
+			if (!isRelevantSourcePath(changedPath)) return;
+
+			clearTimeout(refreshTimer);
+			refreshTimer = setTimeout(refreshImages, 250);
+		};
+
+		server.watcher.add(manifestPath);
+		server.watcher.add(watchedSourcePaths);
+		server.watcher.on('change', (changedPath) => {
+			if (path.resolve(changedPath) !== manifestPath) return;
+
+			server.ws.send({ type: 'full-reload' });
+		});
+		server.watcher.on('add', scheduleRefreshImages);
+		server.watcher.on('change', scheduleRefreshImages);
+		server.watcher.on('unlink', scheduleRefreshImages);
+		server.watcher.on('addDir', scheduleRefreshImages);
+		server.watcher.on('unlinkDir', scheduleRefreshImages);
+	},
+});
+
 // https://astro.build/config
 export default defineConfig({
 	base: projectConfig.site.basePath,
@@ -16,4 +89,7 @@ export default defineConfig({
 	outDir: astroDistDir,
 	publicDir: astroPublicDir,
 	srcDir: path.join(engineRoot, 'src'),
+	vite: {
+		plugins: [nornaGeneratedImagesWatcher()],
+	},
 });

package/bin/norna-cli.mjs

@@ -16,7 +16,7 @@ Commands:
   dev:stop               Stop local dev server
   config:check           Validate site/config.mjs
   content:check          Validate site/content.md and image references
-  content:sync           Rewrite section order and move misplaced images
+  content:sync           Move misplaced Norna-managed images and refresh generated images
   typography presets     Show built-in typography preset values
   typography show        Show resolved typography for the selected site
   site:public            Sync site/public/ to public/
@@ -128,9 +128,9 @@ try {
 		await runScript('scripts/check-config.mjs', rest);
 	} else if (command === 'content:check') {
 		await runScript('scripts/sync-content-sections.mjs', ['--check', ...rest]);
-		await runAstroInherit(['sync']);
 	} else if (command === 'content:sync') {
 		await runScript('scripts/sync-content-sections.mjs', ['--write', ...rest]);
+		await runScript('scripts/generate-images.mjs', rest);
 	} else if (command === 'typography:presets' || (command === 'typography' && subcommand === 'presets')) {
 		const scriptArgs = command === 'typography' ? subcommandRest : rest;
 		await runScript('scripts/show-typography.mjs', ['presets', ...scriptArgs]);

package/docs/README.md

@@ -38,9 +38,9 @@ For a quick reference:
 - [Configuration](configuration.md) describes technical `site/config.mjs`
   fields such as URL, base path, locale labels, footer, GitHub, and deploy
   settings.
-- [Content](content.md) describes page frontmatter, section frontmatter,
-  image rows, carousels, temporary sections, Markdown section matching, and
-  content validation.
+- [Content](content.md) describes page frontmatter, Markdown-authored
+  sections, optional section metadata, image stacks, carousels, temporary
+  sections, and content validation.
 - [Theme](theme.md) describes site-wide layout, layout density, image sizing,
   font, typography rhythm, presentation colors, frame colors, and inline styles.
 - [Typography](typography.md) describes presets, rhythms, roles, overrides,

package/docs/commands.md

@@ -101,10 +101,10 @@ should normally mean the repository's complete publishable artifact, while
   cache path.
 - `config:check`: validates `site/config.mjs` against the runtime config
   reader.
-- `content:check`: validates section structure and image references, then
-  runs `astro sync`.
-- `content:sync` / `norna:sync`: rewrites Markdown section order and moves misplaced referenced
-  image files after confirmation.
+- `content:check`: validates section structure, image references, inline
+  styles, and common content mistakes.
+- `content:sync` / `norna:sync`: moves misplaced referenced image files after
+  confirmation.
 - `typography presets`: prints the exact built-in values for typography
   presets and rhythms.
 - `typography show`: prints the selected site's resolved typography for the
@@ -112,8 +112,8 @@ should normally mean the repository's complete publishable artifact, while
   and inherited page or section values are marked with `inherited: true`.
 - `site:public`: copies `site/public/` into `site/.norna/public/` and
   removes stale copied static files.
-- `images`: generates WebP variants and writes
-  `site/.norna/generated-images.json`.
+- `images`: generates WebP variants for raster images, copies managed SVG
+  images, and writes `site/.norna/generated-images.json`.
 - `engine:update [version|latest]`: updates the site repository's
   `@janga/norna` dependency with `npm install --save-exact`, normalizes
   `package-lock.json` for the pinned GitHub Actions Linux/npm environment, and

package/docs/configuration.md

@@ -39,7 +39,7 @@ site: {
   `?`, `#`, or `//`.
 - Consequence: use `/` for a root site or custom domain. Use
   `/repository-name/` for a GitHub Pages project site without a custom domain.
-  Source Markdown can still use root-relative paths such as `/workflow.svg` or
+  Source Markdown can still use root-relative paths such as `/favicon.svg` or
   `/getting-started/`; Norna prefixes them during rendering.
 
 Examples:
@@ -141,7 +141,8 @@ Fields:
   `Sections`.
 - `locale.labels.menu`: mobile menu summary text, default `Menu`.
 - `locale.labels.closeMenu`: reserved close-menu label, default `Close menu`.
-- `locale.labels.gallery`: image row ARIA label prefix, default `Images`.
+- `locale.labels.gallery`: Norna image block ARIA label prefix, default
+  `Images`.
 
 Example:
 

package/docs/content.md

@@ -1,11 +1,10 @@
 # Content
 
-`site/content.md` is the homepage page file for a `norna` site. It defines the
-page metadata, section order, section ids, image rows, and Markdown text for
-the homepage.
+`site/content.md` is the homepage page file for a Norna site. It contains page
+metadata in frontmatter and the homepage content in Markdown.
 
-Route pages use the same page and section model in
-`site/routes/<route-folder>/route-content.md`. See [Routes](routes.md) for the
+Route pages use the same page model in
+`site/routes/<NNN-route-id>/route-content.md`. See [Routes](routes.md) for the
 route-specific rules.
 
 Site-wide visual defaults belong in [Theme](theme.md). Typography presets and
@@ -18,14 +17,11 @@ The Astro content schema validates these top-level fields in page files:
 
 - `title`: required string. Rendered as the document title.
 - `description`: required string. Rendered as the meta description.
-- `slug`: optional route URL slug. It is ignored on the homepage. If omitted on
-  a route page, the route folder name is used.
 - `navigation`: optional page navigation metadata. See [Routes](routes.md).
 - `presentation`: optional page-level presentation overrides. See
   [Theme](theme.md) and [Typography](typography.md).
 - `frame`: optional page-level frame color source. See [Theme](theme.md).
-- `sections`: required non-empty array. Defines section order, ids,
-  presentation overrides, and image rows.
+- `sections`: optional section metadata keyed by section id.
 
 Minimal homepage:
 
@@ -33,8 +29,6 @@ Minimal homepage:
 ---
 title: My Site
 description: A small Norna site.
-sections:
-  - id: intro
 ---
 
 ## Intro {#intro}
@@ -44,99 +38,181 @@ Text...
 
 ## Sections
 
-Each `sections[]` item has:
+Markdown level 2 headings define the page sections and their order:
 
-- `id`: required string matching `^[a-z0-9-]+$`. Used for anchors, navigation,
-  image directories, and Markdown heading ids.
-- `visible`: optional date window that controls whether the section is rendered.
-- `presentation`: optional section-level visual overrides.
-- `gallery`: optional array, defaulting to `[]`.
+```md
+## About {#about}
 
-Example:
+...
 
-```yaml
-sections:
-  - id: work
-    gallery:
-      - image: work.jpg
-        alt: "A woven artwork on a white wall."
-        caption: "Work in progress."
+## Work {#work}
+
+...
+
+## Contact {#contact}
+
+...
 ```
 
-Every frontmatter section must have a matching level 2 Markdown heading with an
-explicit id:
+Every section heading must have an explicit id:
 
 ```md
 ## Work {#work}
+```
+
+The id must match `^[a-z0-9-]+$`. It is used for anchors, navigation, image
+directories, and optional section metadata. The visible section navigation
+label comes from the Markdown heading text.
+
+Markdown section content starts at the level 2 heading and continues until the
+next level 2 heading. `###` and `####` headings are body subheadings within the
+current section, not new sections.
 
-Introductory text.
+## Section Metadata
+
+Use `sections` only when a section needs structured metadata that is not
+naturally expressed by Markdown, such as visibility or presentation overrides.
+
+```yaml
+sections:
+  work:
+    presentation:
+      typography:
+        preset: statement
 ```
 
-Keep these values aligned:
+Each `sections.<section-id>` key must match a Markdown heading id in the same
+page file:
 
-- the frontmatter `sections[].id`
-- the Markdown heading id
-- the source image directory `site/images/<section-id>/`
+```md
+## Work {#work}
+```
 
-The visible section navigation label comes from the Markdown heading text, not
-from the frontmatter id.
+Do not list sections in frontmatter just to define order. Section order comes
+from the Markdown heading order.
 
-## Image Rows
+## Image Blocks
 
-Each image row can contain a single image:
+Norna-managed local images are written in Markdown fenced blocks at the point
+where they should appear in the section.
 
-```yaml
-gallery:
-  - image: work.jpg
-    alt: "A woven artwork on a white wall."
-    caption: "Work in progress."
+Use `norna-image-stack` for one or more stacked images:
+
+````md
+```norna-image-stack
+- image: work.jpg
+  alt: A woven artwork on a white wall.
+  caption: Work in progress.
+```
+````
+
+Use `norna-image-carousel` for a carousel:
+
+````md
+```norna-image-carousel
+- image: first.jpg
+  alt: First image.
+  caption: First caption.
+- image: second.jpg
+  alt: Second image.
+  caption: Second caption.
 ```
+````
 
-Image rows support:
+Each image entry supports:
 
-- `image`: required filename matching `^[a-z0-9][a-z0-9.-]*\.(jpe?g|png)$`.
+- `image`: required filename matching
+  `^[a-z0-9][a-z0-9.-]*\.(jpe?g|png|svg)$`.
   It must be a filename, not a path.
-- `alt`: required string.
-- `caption`: optional string.
+- `alt`: optional alt text. If omitted, Norna renders an empty alt attribute.
+- `caption`: optional caption.
 
-Source image filenames must be unique across the selected page's image tree.
-The homepage reads images from `site/images/<section-id>/`. Route pages read
-images from `site/routes/<route-folder>/images/<section-id>/`.
+Start every image entry with `- image: filename.jpg`. Optional fields use two
+spaces of indentation:
 
-## Carousels
+````md
+```norna-image-stack
+- image: filename.jpg
+  alt: Optional alt text.
+  caption: Optional caption.
+```
+````
 
-An image row can contain a carousel instead of a single image:
+Use three or more matching backticks or tildes for fenced blocks. If you need
+to document a Norna image block inside another Markdown code sample, make the
+outer fence longer than the inner fence:
 
-```yaml
-gallery:
-  - carousel:
-      - image: first.jpg
-        alt: "First image."
-        caption: "First caption."
-      - image: second.jpg
-        alt: "Second image."
-        caption: "Second caption."
+````md
+````
+```norna-image-stack
+- image: filename.jpg
 ```
-
-Each carousel item has the same `image`, `alt`, and `caption` fields as a
-single image row.
+````
+````
 
 `content:check` warns when carousel images have different aspect ratios. Exact
 matching proportions are recommended because mixed proportions can make the
 layout move while the user changes slides.
 
+SVG files are allowed in image stacks and carousels. When an SVG has a
+`viewBox` or numeric `width` and `height`, Norna uses that ratio in the same
+layout logic as raster images. SVG files without an intrinsic aspect ratio are
+rendered directly, but carousel usage produces a warning because stable slide
+sizing is less predictable.
+
+## Image Files
+
+Homepage images live under:
+
+```text
+site/images/<section-id>/
+```
+
+Route images live under:
+
+```text
+site/routes/<NNN-route-id>/images/<section-id>/
+```
+
+Image references in Norna image blocks use only the filename:
+
+````md
+```norna-image-stack
+- image: portrait.jpg
+```
+````
+
+If `portrait.jpg` is referenced from `## Team {#team}`, the expected homepage
+location is `site/images/team/portrait.jpg`.
+
+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.
+
+## Markdown Images
+
+Markdown image syntax is allowed for external images and public static 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. Use `norna-image-stack` or `norna-image-carousel` for local
+site images that should be validated, processed and synced.
+
 ## Temporary Sections
 
-Use `sections[].visible` for sections that should be rendered only during a
-date window:
+Use `sections.<section-id>.visible` for sections that should be rendered only
+during a date window:
 
 ```yaml
 sections:
-  - id: exhibition
+  exhibition:
     visible:
       from: "2026-08-01"
       until: "2026-09-16"
-    gallery: []
 ```
 
 `from` is inclusive. `until` is exclusive. With the example above, the section
@@ -158,17 +234,6 @@ NORNA_TODAY=2026-08-15 npm run norna:build
 
 ## Markdown Text
 
-Section Markdown starts at the matching level 2 heading and continues until the
-next level 2 heading.
-
-```md
-## Intro {#intro}
-
-Paragraph text.
-
-Another paragraph.
-```
-
 Inline styles use this Markdown form:
 
 ```md
@@ -186,16 +251,17 @@ Run:
 npm run norna:content:check
 ```
 
-This checks section order and heading ids, duplicate image names, missing image
-files, misplaced referenced images, duplicate image references, invalid image
-references, unreferenced images, undefined inline styles, and common
-frontmatter indentation and structure mistakes.
+This checks section heading ids, section metadata, duplicate image names,
+missing image files, misplaced referenced images, duplicate image references,
+invalid image blocks, unreferenced images, undefined inline styles, Markdown
+image references to unmanaged local files, and common frontmatter indentation
+and structure mistakes.
 
 Frontmatter uses YAML indentation. Use ordinary spaces, not tabs or
 non-breaking spaces. `content:check` reports a focused error when indentation is
 invalid, when a key is indented under a line that already has a value, or when a
-known nested key such as `gallery` or section-specific `typography` appears at
-the top level:
+known nested key such as section-specific `typography` appears at the top
+level:
 
 ```yaml
 presentation:
@@ -206,15 +272,8 @@ presentation:
         paragraphSpacing: 0.8em
 ```
 
-Top-level page frontmatter may contain only `title`, `description`, `slug`,
-`navigation`, `presentation`, `frame`, and `sections`. A `gallery` key belongs
-under one `sections[]` item:
-
-```yaml
-sections:
-  - id: work
-    gallery: []
-```
+Top-level page frontmatter may contain only `title`, `description`,
+`navigation`, `presentation`, `frame`, and `sections`.
 
 Run:
 
@@ -222,6 +281,6 @@ Run:
 npm run norna:sync
 ```
 
-This rewrites Markdown sections into frontmatter order and moves referenced
-image files into the directory matching their section. It prompts before
-writing unless `--yes` is passed.
+This moves referenced image files into the section directory shown by the
+Markdown placement. It prompts before writing unless `--yes` is passed. Sync is
+currently page- or route-local: it does not move images across routes.

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,
-typography presets, typography rhythms, galleries, image carousels, inline
+typography presets, typography rhythms, image stacks, image carousels, inline
 styles, and site-specific configuration choices.
 
 ### Documentation Site

package/docs/engine-development.md

@@ -9,13 +9,13 @@ This document is for work on the reusable `norna` package itself.
 - `scripts/lib/site-paths.mjs`: engine/site path resolution.
 - `scripts/lib/project-config.mjs`: `site/config.mjs` validation and defaults.
 - `scripts/sync-content-sections.mjs`: content validation and sync behavior.
-- `scripts/generate-images.mjs`: WebP image pipeline and manifest.
+- `scripts/generate-images.mjs`: managed image pipeline and manifest.
 - `scripts/sync-site-public.mjs`: static public file sync.
 - `scripts/deploy-site.mjs`: deploy and deploy:commit behavior.
 - `scripts/watch-pages-deploy.mjs`: GitHub Pages workflow monitor.
 - `src/content.config.ts`: Astro content schema.
-- `src/components/` and `src/layouts/`: rendered page, navigation, image rows,
-  and layout.
+- `src/components/` and `src/layouts/`: rendered page, navigation, image
+  blocks, and layout.
 - `tests/`: Playwright navigation diagnostics.
 - `fixtures/basic/site/`: minimal site used for engine checks.
 - `starters/basic/`: copyable site starter.
@@ -160,7 +160,7 @@ and commit their updated `package-lock.json`.
 ## Rendering Notes
 
 The renderer builds the homepage at `/` and optional first-level routes from
-`site/routes/<route-folder>/route-content.md`.
+`site/routes/<NNN-route-id>/route-content.md`.
 
 Navigation has two separate levels:
 

package/docs/getting-started.md

@@ -67,11 +67,13 @@ 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.
+3. Edit `site/content.md` for homepage title, description, Markdown sections,
+   text, Norna image blocks, page/section presentation overrides, alt text, and
+   captions.
 4. Put source images under `site/images/<section-id>/`.
 5. Add optional route pages under
-   `site/routes/<route-folder>/route-content.md`.
+   `site/routes/<NNN-route-id>/route-content.md`, for example
+   `site/routes/010-about/route-content.md`.
 6. Put static files such as `robots.txt`, `CNAME`, and favicons under
    `site/public/`.
 7. Run:
@@ -103,7 +105,7 @@ 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`.