@janga/norna 0.7.2 → 0.7.4

package/docs/design/command-organization.md

@@ -1,10 +1,10 @@
 # Command Organization
 
-This document defines the naming principles for commands in `norna`,
-gallery site repositories, and GitHub projects that embed a gallery.
+This document defines the naming principles for commands in `norna`, site
+repositories, and GitHub projects that embed a Norna site.
 
 The goal is that command names reveal both the action and the scope they affect.
-This matters because the same repository can contain a gallery, an app, tests,
+This matters because the same repository can contain a Norna site, an app, tests,
 and a publishing workflow that should not accidentally share ambiguous command
 names.
 
@@ -12,10 +12,10 @@ names.
 
 `norna` commands must be understandable in three situations:
 
-- Pure gallery project: the repository exists only to publish one
+- Standalone site project: the repository exists only to publish one
   `norna` site.
-- Mixed gallery project: the repository contains another project, such as an
-  app or library, and includes a `norna` presentation as one part of its
+- Mixed project: the repository contains another project, such as an app or
+  library, and includes a Norna site as one part of its
   GitHub Pages output.
 - Engine development: the repository is `norna` itself.
 
@@ -27,7 +27,7 @@ Use these namespaces consistently.
 
 Use `norna:*` npm scripts in repositories that consume `norna`.
 
-These scripts operate on a selected gallery source directory. In a pure gallery
+These scripts operate on a selected site source directory. In a standalone site
 project that directory is normally `site/`. In a mixed project it may be a more
 specific directory such as `presentation/`, with the script setting
 `NORNA_SITE_DIR` or passing `norna --site-dir`.
@@ -41,19 +41,19 @@ npm run norna:sync
 npm run norna:build
 ```
 
-Mixed projects must use `norna:*` for gallery work so names such as `build`,
+Mixed projects must use `norna:*` for Norna work so names such as `build`,
 `test`, and `deploy` can remain under the containing project's control.
 
-Pure gallery projects should also use `norna:*` as the primary documented
+Standalone site projects should also use `norna:*` as the primary documented
 interface. They may provide unprefixed aliases when the alias means the same
 thing for the whole repository, for example `npm run build` as an alias for
 `npm run norna:build`.
 
-### Project Commands That Call Gallery Commands
+### Project Commands That Call Norna Commands
 
 `norna` does not define a consuming project's unprefixed commands. Names
 such as `build`, `test`, and `deploy` belong to the project that consumes the
-gallery engine.
+Norna engine.
 
 Examples:
 
@@ -63,18 +63,18 @@ npm run test
 npm run deploy
 ```
 
-When those project commands need the gallery, they should call `norna:*`
+When those project commands need the Norna site, they should call `norna:*`
 scripts instead of calling `norna` directly. That keeps the selected
-gallery source directory and other project-specific wrapper behavior in one
+site source directory and other project-specific wrapper behavior in one
 place.
 
 In a mixed project, if `npm run build` exists, it should build the project's
-complete publishable artifact, not only the gallery. If the project publishes a
-GitHub Pages artifact containing both a gallery and an app, `build` should
+complete publishable artifact, not only the Norna site. If the project publishes a
+GitHub Pages artifact containing both a Norna site and an app, `build` should
 produce that full artifact and may call `npm run norna:build` internally.
 
-In a pure gallery project, project commands may be aliases to `norna:*`
-commands because the gallery is the whole project.
+In a standalone site project, project commands may be aliases to `norna:*`
+commands because the Norna site is the whole project.
 
 ### `release:*`
 
@@ -114,19 +114,19 @@ can set the correct site directory for the repository.
 
 ## Functional Groups
 
-### Install Gallery Software
+### Install Norna Software
 
-Creating a new pure gallery project starts outside the target project because
+Creating a new standalone site project starts outside the target project because
 the target does not have a `package.json` yet:
 
 ```sh
-npx @janga/norna@latest init my-gallery
-cd my-gallery
+npx @janga/norna@latest init my-site
+cd my-site
 npm install
 ```
 
 A mixed project already has its own repository and may have its own
-`package.json`. In that situation the gallery dependency should be installed as
+`package.json`. In that situation the Norna dependency should be installed as
 part of the existing project setup:
 
 ```sh
@@ -134,7 +134,7 @@ npm install --save-exact @janga/norna
 ```
 
 The mixed project should then add `norna:*` scripts that point at the chosen
-gallery source directory.
+site source directory.
 
 Engine development uses ordinary package installation in the engine repository:
 
@@ -142,9 +142,9 @@ Engine development uses ordinary package installation in the engine repository:
 npm install
 ```
 
-### Upgrade Or Inspect Gallery Software
+### Upgrade Or Inspect Norna Software
 
-In a consuming repository, upgrading or inspecting the installed gallery engine
+In a consuming repository, upgrading or inspecting the installed Norna engine
 is norna maintenance, so the preferred namespace is `norna:*`:
 
 ```sh
@@ -162,13 +162,13 @@ In the engine repository, version changes belong to `release:*`:
 npm run release:minor
 ```
 
-### Initialize A Gallery Project Directory
+### Initialize A Site Project Directory
 
 Initialization is a direct CLI operation because it usually happens before a
 project has npm scripts:
 
 ```sh
-npx @janga/norna@latest init my-gallery
+npx @janga/norna@latest init my-site
 ```
 
 The initializer should support two setup modes that share the same `norna:*`
@@ -176,25 +176,25 @@ command vocabulary.
 
 #### Pure Setup
 
-Pure setup creates a new project where the gallery is the whole repository:
+Pure setup creates a new project where the Norna site is the whole repository:
 
 ```sh
-npx @janga/norna@latest init my-gallery --type pure
+npx @janga/norna@latest init my-site --type pure
 ```
 
 This should be the default when the target is a new or empty directory.
 
 Pure setup should create:
 
-- a normal gallery source directory, normally `site/`;
+- a normal site source directory, normally `site/`;
 - a `package.json` with `norna:*` scripts;
 - unprefixed convenience aliases only when they mean the same thing as the
   whole project, for example `build` as an alias for `norna:build`;
-- the standard GitHub Pages workflow for publishing the gallery.
+- the standard GitHub Pages workflow for publishing the site.
 
 #### Embedded Setup
 
-Embedded setup adds a gallery to an existing project without taking ownership
+Embedded setup adds a Norna site to an existing project without taking ownership
 of that project's root commands:
 
 ```sh
@@ -204,9 +204,9 @@ npx @janga/norna@latest init . --type embedded --site-dir presentation
 Embedded setup should be selected explicitly, or suggested when the target
 already contains a `package.json`.
 
-Embedded setup should create or update only the gallery-owned parts:
+Embedded setup should create or update only the Norna-owned parts:
 
-- the chosen gallery source directory, for example `presentation/`;
+- the chosen site source directory, for example `presentation/`;
 - `@janga/norna` as a project dependency;
 - `norna:*` scripts that set the selected site directory;
 - no unprefixed aliases such as `build`, `test`, `dev`, or `deploy`;
@@ -263,11 +263,11 @@ npm run test
 
 If a mixed project defines `test`, that command should cover the whole project.
 It may call `norna:check`, but it should not be a hidden synonym for only
-gallery validation.
+Norna validation.
 
-### Inspect Gallery Presentation
+### Inspect Site Presentation
 
-Commands that inspect gallery presentation without changing source files use
+Commands that inspect site presentation without changing source files use
 `norna:*` in consuming repositories:
 
 ```sh
@@ -275,13 +275,14 @@ npm run norna:typography:presets
 npm run norna:typography:show
 ```
 
-`norna:typography:presets` shows the built-in typography presets from the
-installed engine. `norna:typography:show` shows the effective typography for
-the selected gallery after presets and overrides have been applied.
+`norna:typography:presets` shows the built-in typography presets and rhythms
+from the installed engine. `norna:typography:show` shows the effective
+typography for the selected site after presets, rhythms, and overrides have
+been applied.
 
 ### Correct Content And Configuration
 
-Commands that modify gallery-owned source files use `norna:*`:
+Commands that modify Norna-owned source files use `norna:*`:
 
 ```sh
 npm run norna:sync
@@ -293,7 +294,7 @@ npm run norna:images
 Messages emitted by the engine should mention the direct CLI command and the
 starter-style npm wrapper when suggesting a fix.
 
-Configuration edits are normally manual edits to the selected gallery
+Configuration edits are normally manual edits to the selected site
 `config.mjs`, followed by:
 
 ```sh
@@ -302,7 +303,7 @@ npm run norna:config:check
 
 ### Build
 
-In a pure gallery project:
+In a standalone site project:
 
 ```sh
 npm run norna:build
@@ -311,7 +312,7 @@ npm run build
 ```
 
 `norna:build:local` builds and restarts the local dev server. `build` may
-alias `norna:build` because the gallery is the whole project.
+alias `norna:build` because the Norna site is the whole project.
 
 In a mixed project:
 
@@ -321,10 +322,10 @@ npm run norna:build:local
 npm run build
 ```
 
-`norna:build` builds only the gallery. `norna:build:local` builds the
-gallery and restarts the local gallery dev server. If the mixed project defines
+`norna:build` builds only the Norna site. `norna:build:local` builds the
+site and restarts the local Norna dev server. If the mixed project defines
 `build`, that project command should build the complete publishable artifact,
-such as a GitHub Pages output that combines the gallery with an app. It may call
+such as a GitHub Pages output that combines the Norna site with an app. It may call
 `norna:build` internally.
 
 In the engine repository:
@@ -347,8 +348,8 @@ npm run norna:deploy
 npm run norna:deploy:commit
 ```
 
-Use these only when the gallery is the deployable site or when the containing
-project deliberately delegates deployment to the gallery engine.
+Use these only when the Norna site is the deployable site or when the containing
+project deliberately delegates deployment to the Norna engine.
 
 Mixed projects may instead have project-owned deploy commands:
 
@@ -357,7 +358,7 @@ npm run deploy
 ```
 
 Those commands should publish the complete project artifact. If they need the
-gallery, they should call `norna:*` scripts internally.
+Norna site, they should call `norna:*` scripts internally.
 
 Engine publishing uses `release:*`, not `norna:*`:
 
@@ -369,14 +370,14 @@ npm run release:major
 
 ### Monitor Publishing
 
-Gallery Pages monitoring belongs under:
+GitHub Pages monitoring for a Norna site belongs under:
 
 ```sh
 npm run norna:deploy:watch
 ```
 
 Mixed projects may provide a project-owned monitoring command when monitoring
-is not specific to the gallery:
+is not specific to the Norna site:
 
 ```sh
 npm run deploy:watch
@@ -388,19 +389,19 @@ norna-specific deploy settings, it should call `norna:deploy:watch`.
 ## Naming Rules
 
 - Use `norna:*` for every npm script in a consuming repository whose direct
-  object is the gallery, its source files, its generated images, its dev server,
+  object is the Norna site, its source files, its generated images, its dev server,
   or its engine dependency.
 - `norna` does not define unprefixed project commands such as `build`,
   `test`, and `deploy` in consuming repositories.
-- If project commands need gallery behavior, they should call `norna:*`
+- If project commands need Norna behavior, they should call `norna:*`
   scripts.
-- In pure gallery projects, unprefixed project commands may alias `norna:*`
+- In standalone site projects, unprefixed project commands may alias `norna:*`
   commands.
 - In mixed projects, unprefixed project commands must not be aliases for only
-  the gallery unless the command name makes that scope explicit.
+  the Norna site unless the command name makes that scope explicit.
 - Use `release:*` only for publishing the reusable engine package.
 - Prefer direct `norna ...` commands in engine docs and diagnostics;
   prefer npm scripts in site-repository docs.
 - Do not create separate namespaces for every internal concept. If a command is
-  about maintaining the gallery dependency in a consuming repository, keep it
+  about maintaining the Norna dependency in a consuming repository, keep it
   under `norna:*`.

package/docs/design/site-examples-structure.md

@@ -26,8 +26,8 @@ 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, galleries, image carousels, inline styles, and site-specific
-configuration choices.
+typography presets, typography rhythms, galleries, image carousels, inline
+styles, and site-specific configuration choices.
 
 ### Documentation Site
 
@@ -70,9 +70,10 @@ they demonstrate a distinct feature or workflow.
 
 - `dog-gallery/`: current local visual demo, manual inspection site, and
   navigation diagnostic target.
-- `routes-demo/`: focused route/navigation example if dog-gallery becomes too
-  broad.
-- `typography-demo/`: focused typography preset and override example if needed.
+- `routes-demo/`: focused route/navigation example if the dog example becomes
+  too broad.
+- `typography-demo/`: focused typography preset, rhythm, and override example
+  if needed.
 
 The repository-local `site/` directory is reserved for the documentation site.
 `docs/` should remain for reference documentation. It should link to the

package/docs/engine-development.md

@@ -14,13 +14,13 @@ This document is for work on the reusable `norna` package itself.
 - `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, gallery, and
-  layout.
+- `src/components/` and `src/layouts/`: rendered page, navigation, image rows,
+  and layout.
 - `tests/`: Playwright navigation diagnostics.
 - `fixtures/basic/site/`: minimal site used for engine checks.
 - `starters/basic/`: copyable site starter.
-- `examples/dog-gallery/site/`: visual dog-gallery demo used by demo builds
-  and navigation diagnostics.
+- `examples/dog-gallery/site/`: visual dog example used by demo builds and
+  navigation diagnostics.
 
 The repository-local `site/` directory is reserved for a local documentation
 site. It is useful for dogfooding `norna` documentation, but it is not the
@@ -48,7 +48,7 @@ npm run dev:local
 npm run build
 ```
 
-The dog gallery remains the visual demo and navigation diagnostic target:
+The dog example remains the visual demo and navigation diagnostic target:
 
 ```sh
 cd examples/dog-gallery/site

package/docs/getting-started.md

@@ -23,10 +23,10 @@ new site directory:
 
 ```sh
 cd path/to/your/projects
-npx @janga/norna@latest init my-gallery
-cd my-gallery
+npx @janga/norna@latest init my-site
+cd my-site
 npm install
-npm run norna:dev
+npm run dev
 ```
 
 After `npm install`, the project's npm scripts use the project-local `norna`
@@ -45,7 +45,7 @@ engine repository. For example:
 ```text
 Projects/
   norna/
-  my-gallery/
+  my-site/
 ```
 
 The starter contains:
@@ -62,12 +62,13 @@ Commit the generated `package-lock.json` after the first install.
 
 ## First Edits
 
-1. Edit `site/config.mjs` for the site's URL, layout, font, language labels,
-   GitHub repository, footer, and deploy settings.
-2. Edit `site/theme.md` for site-wide colors, typography preset, inline styles,
-   and frame colors, or omit it to use engine defaults.
+1. Edit `site/config.mjs` for the site's URL, language labels, GitHub
+   repository, footer, and deploy settings.
+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,
-   gallery rows, page/section presentation overrides, alt text, and captions.
+   image rows, 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`.
@@ -113,20 +114,13 @@ 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.
 
-To change the site's maximum page width, set `layout.pageWidth` in
-`site/config.mjs`. To change side margins, set `layout.gutter`. To change the
-maximum gallery width inside that page area, set `gallery.width`. To keep
-images within a comfortable viewport height, set
-`gallery.maxAvailableHeightPercent`. See [Configuration](configuration.md) for
-the accepted formats and default values.
-
-To change the site's font, set `typography.fontFamily` in `site/config.mjs`.
-See [`typography.fontFamily`](configuration.md#typographyfontfamily) for the
-accepted format and default value.
-
-To change the site-wide typography preset, edit `site/theme.md`. To change one
-page or section, add a focused `presentation.typography` override in
-`site/content.md`. See [Typography](typography.md). Use
-`npm run norna:typography:presets` to inspect the installed preset values and
-`npm run norna:typography:show` to inspect the resolved typography for the
-selected site.
+To change the site's maximum page width, side gutters, layout density,
+typography rhythm, image width, image height limits, font, colors, or
+site-wide typography preset, edit `site/theme.md`. See [Theme](theme.md) for
+the accepted shape.
+
+To change one page or section, add a focused `presentation.typography`
+override in `site/content.md`. See [Typography](typography.md). Use
+`norna typography presets` to inspect the installed preset and rhythm values and
+`norna typography show` to inspect the resolved typography for the selected
+site.

package/docs/images-and-metadata.md

@@ -15,7 +15,7 @@ Supported source extensions:
 - `.png`
 
 Image filenames must be globally unique under `site/images/`. The content and
-image scripts reject duplicate filenames because gallery rows identify images by
+image scripts reject duplicate filenames because image rows identify images by
 filename only.
 
 ## Generated Variants

package/docs/local-development.md

@@ -5,7 +5,7 @@ Use the local preview commands when editing a site or the engine demo.
 ## Start Preview
 
 ```sh
-npm run norna:dev
+npm run dev
 ```
 
 The wrapper:
@@ -28,7 +28,7 @@ To stop any process that is blocking the standard port before starting, pass
 `--kill`:
 
 ```sh
-npm run norna:dev -- --kill
+npm run dev -- --kill
 ```
 
 For the pure starter's `dev` alias, use:

package/docs/publishing.md

@@ -79,7 +79,7 @@ npm run norna:deploy:commit -- "Commit message"
 
 It builds, stages only allowed site changes, commits, pushes, and checks Pages.
 The allowlist is implemented in `scripts/deploy-site.mjs` and includes the
-site content file, selected config/static files, expected gallery images,
+site content file, selected config/static files, expected generated images,
 generated image manifest, package files, `tsconfig.json`, `astro.config.mjs`,
 and `src/` changes.
 

package/docs/routes.md

@@ -4,7 +4,7 @@
 under `site/routes/<route-folder>/route-content.md` and build to first-level
 URLs.
 
-Routes use the same page frontmatter, section frontmatter, gallery rows, and
+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.
 
@@ -21,7 +21,7 @@ Minimal route page:
 ```md
 ---
 title: About
-description: About this gallery.
+description: About this site.
 navigation:
   label: About
   order: 20

package/docs/site-structure.md

@@ -30,18 +30,19 @@ site directory. Without an explicit site directory, commands first accept the
 current directory when it contains both `config.mjs` and `content.md`.
 Otherwise, commands started from a subdirectory walk upward until they find the
 default `site/` directory containing those files.
-`theme.md` is optional; omit it to use the engine's built-in presentation
-defaults.
+`theme.md` is optional; omit it to use the engine's built-in visual defaults.
 
 ## Versioned Source Files
 
 Version these files in a site repository:
 
 - `site/config.mjs`: technical site configuration.
-- `site/theme.md`: optional site-wide visual theme, inline styles, typography
-  defaults, and frame colors. See [Theme](theme.md).
+- `site/theme.md`: optional site-wide visual theme, including layout, spacing,
+  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, gallery rows, alt text, and captions. See [Content](content.md).
+  definitions, image rows, 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.
   See [Routes](routes.md).
@@ -83,6 +84,6 @@ In this repository:
 - `starters/basic/` is copied by `norna init <target-dir>` to create a
   site repository.
 - `fixtures/basic/site/` is used by engine regression tests.
-- `examples/dog-gallery/site/` is the local visual dog-gallery demo used by
-  demo builds and navigation diagnostics.
+- `examples/dog-gallery/site/` is the local visual dog example used by demo
+  builds and navigation diagnostics.
 - `site/` is reserved for the local documentation site.