@janga/norna 0.7.18 → 0.7.23

package/src/styles/responsive.css

@@ -0,0 +1,525 @@
+/* Responsive and forced-colors adaptations, kept last in the cascade. */
+
+@media (max-width: 700px) {
+	:root {
+		--space-nav-to-first-section: var(--space-nav-to-first-section-mobile);
+		--space-content-block-gap: var(--space-content-block-gap-mobile);
+		--space-heading-to-block: var(--space-heading-to-block-mobile);
+		--space-image-item: var(--space-image-item-mobile);
+		--space-section-to-section: var(--space-section-to-section-mobile);
+		--space-page-title-to-first-section: var(--space-page-title-to-first-section-mobile);
+		--space-final-section-bottom: var(--space-final-section-bottom-mobile);
+		--content-gutter: var(--content-gutter-mobile);
+		--image-max-available-width: var(--image-max-available-width-mobile);
+		--image-max-height: var(--image-max-height-mobile);
+		--site-top-anchor-offset: 6.25rem;
+	}
+
+	.image-carousel {
+		--image-carousel-width-from-height: var(--image-carousel-width-from-height-mobile, var(--image-layout-width));
+	}
+
+	.site-nav-row {
+		width: min(calc(100% - (var(--content-gutter) * 2)), var(--page-width));
+		padding: 0.75rem 0;
+	}
+
+	.site-nav-row-mobile-only {
+		display: flex;
+	}
+
+	.site-brand {
+		max-width: min(70vw, 26rem);
+		font-size: 0.76rem;
+		overflow-wrap: anywhere;
+	}
+
+	.site-brand-logo {
+		height: min(var(--site-brand-logo-height, 2.6rem), 2.15rem);
+		max-width: min(48vw, 13rem);
+	}
+
+	.site-nav {
+		display: none;
+	}
+
+	.display-settings {
+		position: static;
+	}
+
+	.display-settings-panel {
+		top: calc(100% + 0.35rem);
+		right: max(var(--content-gutter), env(safe-area-inset-right, 0px));
+		left: max(var(--content-gutter), env(safe-area-inset-left, 0px));
+		width: auto;
+		max-height: calc(
+			100dvh - 100% - max(var(--content-gutter), env(safe-area-inset-bottom, 0px)) - 0.35rem
+		);
+	}
+
+	.mobile-nav-menu {
+		display: block;
+		position: relative;
+		flex: 0 0 auto;
+		margin-left: auto;
+	}
+
+	.page-nav {
+		display: none;
+	}
+
+	.page-nav.page-nav-title-only {
+		display: block;
+	}
+
+	.mobile-nav-menu > summary {
+		display: flex;
+		align-items: center;
+		gap: 0.5rem;
+		min-height: 2.75rem;
+		border: 1px solid currentColor;
+		padding: 0.55rem 0.75rem;
+		font-size: 0.72rem;
+		font-weight: 700;
+		letter-spacing: 0.1em;
+		line-height: 1;
+		list-style: none;
+		color: var(--site-top-text-color, var(--color-primary-text));
+		text-transform: uppercase;
+	}
+
+	.mobile-nav-menu > summary::after {
+		content: "☰";
+		font-size: 1rem;
+		line-height: 1;
+		opacity: 0.86;
+	}
+
+	.mobile-nav-menu[open] > summary::after {
+		content: "×";
+		font-size: 1.25rem;
+	}
+
+	.mobile-nav-menu > summary::-webkit-details-marker {
+		display: none;
+	}
+
+	.mobile-nav-panel {
+		position: fixed;
+		top: var(--site-top-anchor-offset);
+		right: 0;
+		bottom: 0;
+		left: 0;
+		width: 100%;
+		max-height: none;
+		border-top: 1px solid color-mix(in srgb, currentColor 24%, transparent);
+		padding: clamp(1.25rem, 5vw, 2rem) var(--content-gutter) max(1.5rem, env(safe-area-inset-bottom));
+		background: var(--site-top-background-color, var(--color-page));
+		box-shadow: 0 1.5rem 3.5rem rgb(0 0 0 / 0.32);
+		color: var(--site-top-text-color, var(--color-text));
+		overflow-y: auto;
+		overscroll-behavior: contain;
+	}
+
+	.mobile-site-nav {
+		width: min(100%, 32rem);
+		margin: 0 auto;
+	}
+
+	.mobile-nav-panel h2 {
+		margin: 0 0 1.25rem;
+		font-size: clamp(1.25rem, 5vw, 1.55rem);
+		font-weight: 650;
+		letter-spacing: 0;
+		line-height: 1.2;
+		text-transform: none;
+	}
+
+	.mobile-nav-panel :is(ul, ol) {
+		display: grid;
+		gap: 0;
+		margin: 0;
+		padding: 0;
+		list-style: none;
+	}
+
+	.navigation-page-tree-mobile > .navigation-page-node {
+		border-top: 1px solid color-mix(in srgb, currentColor 14%, transparent);
+	}
+
+	.navigation-page-tree-mobile > .navigation-page-node:first-child {
+		border-top: 0;
+	}
+
+	.navigation-page-tree-mobile .navigation-page-link {
+		display: flex;
+		align-items: center;
+		width: 100%;
+		min-height: 3.25rem;
+		padding: 0.75rem 2.5rem 0.75rem 0;
+		color: var(--color-secondary-text);
+		font-size: 0.94rem;
+		letter-spacing: 0;
+		line-height: 1.35;
+		text-decoration: none;
+		text-transform: none;
+	}
+
+	.navigation-page-tree-mobile .navigation-page-disclosure > .navigation-page-summary {
+		position: static;
+		display: flex;
+		align-items: center;
+		justify-content: space-between;
+		width: 100%;
+		height: auto;
+		min-height: 3.25rem;
+		padding: 0.75rem 0;
+		font-size: 0.94rem;
+		line-height: 1.35;
+		color: var(--color-secondary-text);
+	}
+
+	.navigation-page-tree-mobile .navigation-page-disclosure > .navigation-page-open-link {
+		display: none;
+		align-items: center;
+		min-height: 3.25rem;
+		width: calc(100% - 2.5rem);
+		padding: 0.75rem 0;
+		font-size: 0.94rem;
+		line-height: 1.35;
+		color: var(--color-secondary-text);
+		overflow-wrap: anywhere;
+	}
+
+	.navigation-page-tree-mobile .navigation-page-disclosure[open] > .navigation-page-open-link {
+		display: flex;
+	}
+
+	.navigation-page-tree-mobile .navigation-page-disclosure > .navigation-page-summary:hover,
+	.navigation-page-tree-mobile .navigation-page-disclosure > .navigation-page-summary:focus-visible,
+	.navigation-page-node-current > .navigation-page-disclosure > .navigation-page-summary {
+		background: transparent;
+		color: var(--color-primary-text);
+	}
+
+	.navigation-page-tree-mobile .navigation-page-disclosure > .navigation-page-summary:hover > :first-child,
+	.navigation-page-tree-mobile .navigation-page-disclosure > .navigation-page-summary:focus-visible > :first-child,
+	.navigation-page-node-current > .navigation-page-disclosure > .navigation-page-summary > :first-child {
+		text-decoration: underline;
+		text-decoration-thickness: 1px;
+		text-underline-offset: 0.3em;
+	}
+
+	.navigation-page-chevron::before {
+		display: block;
+		content: "›";
+		font-size: 1.25rem;
+		line-height: 1;
+		transition: transform 140ms ease;
+	}
+
+	.navigation-page-disclosure[open] > .navigation-page-summary .navigation-page-chevron::before {
+		transform: rotate(90deg);
+	}
+
+	.navigation-page-tree-mobile .navigation-page-disclosure > .navigation-page-summary > [aria-hidden='true']::before,
+	.navigation-page-tree-mobile .navigation-page-disclosure[open] > .navigation-page-summary > [aria-hidden='true']::before {
+		content: "›";
+	}
+
+	.navigation-page-tree-mobile .navigation-page-branch-content {
+		margin-left: 0.35rem;
+		border-left: 1px solid color-mix(in srgb, currentColor 20%, transparent);
+		padding-left: 1rem;
+	}
+
+	.navigation-page-tree-mobile .navigation-page-sections {
+		margin: 0 0 0.45rem;
+	}
+
+	.navigation-page-branch-content > .navigation-page-tree-mobile > .navigation-page-node {
+		border-top: 1px solid color-mix(in srgb, currentColor 10%, transparent);
+	}
+
+	.navigation-page-tree-mobile .navigation-page-link:hover,
+	.navigation-page-tree-mobile .navigation-page-link:focus-visible,
+	.navigation-page-tree-mobile .navigation-page-link[aria-current='page'] {
+		color: var(--color-primary-text);
+		text-decoration: underline;
+		text-decoration-thickness: 1px;
+		text-underline-offset: 0.3em;
+	}
+
+	.page-contents-links-mobile {
+		margin-top: 0.25rem;
+	}
+
+	.page-contents-links-mobile > li {
+		border-bottom: 1px solid color-mix(in srgb, currentColor 12%, transparent);
+	}
+
+	.page-contents-links-mobile li + li {
+		margin-top: 0;
+	}
+
+	.page-contents-links-mobile ol {
+		border-left: 1px solid color-mix(in srgb, currentColor 16%, transparent);
+		padding-left: 1rem;
+	}
+
+	.page-contents-links-mobile a {
+		min-height: 3.2rem;
+		padding: 0.85rem 0;
+		font-size: 0.92rem;
+		color: var(--color-secondary-text);
+	}
+
+	.mobile-nav-panel a {
+		font-family: inherit;
+		font-size: 0.94rem;
+		letter-spacing: 0;
+		line-height: 1.35;
+		text-transform: none;
+	}
+
+	.mobile-nav-view + .mobile-nav-view {
+		margin-top: 2rem;
+	}
+
+	.mobile-nav-sections {
+		border-top: 1px solid color-mix(in srgb, currentColor 16%, transparent);
+	}
+
+	.mobile-nav-sections li {
+		border-bottom: 1px solid color-mix(in srgb, currentColor 12%, transparent);
+	}
+
+	.mobile-nav-sections a {
+		min-height: 3.2rem;
+		padding: 0.85rem 0;
+		font-size: 0.92rem;
+		color: var(--color-secondary-text);
+	}
+
+	.mobile-nav-sections .mobile-nav-page-top {
+		font-weight: 650;
+	}
+
+	.mobile-nav-sections li:not(.mobile-nav-page-top-item) a {
+		padding-left: 1rem;
+	}
+
+	.mobile-nav-sections a:hover,
+	.mobile-nav-sections a:focus-visible,
+	.mobile-nav-sections a[aria-current='location'] {
+		color: var(--color-primary-text);
+		text-decoration: underline;
+		text-decoration-thickness: 1px;
+		text-underline-offset: 0.25em;
+	}
+
+	.mobile-navigation-open {
+		overflow: hidden;
+	}
+
+	.site-content {
+		width: min(calc(100% - (var(--content-gutter) * 2)), var(--page-width));
+	}
+
+	.site-page-layout-tree {
+		display: block;
+		width: 100%;
+	}
+
+	.site-page-layout-tree > .site-content {
+		width: min(calc(100% - (var(--content-gutter) * 2)), var(--page-width));
+	}
+
+	.site-page-layout-tree .site-section::before {
+		left: calc(50% - 50vw);
+		right: calc(50% - 50vw);
+	}
+
+	.tree-local-navigation {
+		display: none;
+	}
+
+	.page-contents-navigation {
+		display: none;
+	}
+
+	.site-banners {
+		width: min(calc(100% - 2rem), var(--page-width));
+		padding-top: 0.75rem;
+	}
+
+	.site-footer {
+		width: min(calc(100% - 2rem), 34rem);
+	}
+
+	.site-section + .site-section {
+		margin-top: 0;
+	}
+
+	.section-body {
+		width: 100%;
+		line-height: 1.72;
+	}
+
+	.section-header h1,
+	.section-header h2 {
+		font-size: var(
+			--section-heading-font-size-mobile,
+			var(--section-heading-font-size-desktop, clamp(1.3rem, 1.05rem + 1.35vw, 1.75rem))
+		);
+	}
+
+	.section-header {
+		width: min(
+			100%,
+			var(
+				--reader-text-width,
+				var(--section-heading-width-mobile, var(--section-heading-width-desktop, 760px))
+			)
+		);
+		text-align: var(--section-heading-align-mobile, var(--section-heading-align-desktop, center));
+	}
+
+	.section-markdown {
+		width: min(
+			100%,
+			var(--reader-text-width, var(--section-body-width-mobile, var(--section-body-width-desktop, var(--text-width))))
+		);
+		font-size: var(
+			--section-body-font-size-mobile,
+			var(--section-body-font-size-desktop, clamp(0.96rem, 0.94rem + 0.08vw, 1rem))
+		);
+		text-align: var(--section-body-align-mobile, var(--section-body-align-desktop, left));
+	}
+
+	.image-meta {
+		font-size: var(--section-caption-font-size-mobile, var(--section-caption-font-size-desktop, 0.95rem));
+		text-align: var(--section-caption-align-mobile, var(--section-caption-align-desktop, center));
+	}
+
+	.image-details {
+		justify-content: var(--section-caption-justify-mobile, var(--section-caption-justify-desktop, center));
+	}
+
+	.section-markdown h3 {
+		font-size: var(--section-markdown-h3-font-size-mobile, var(--section-markdown-h3-font-size-desktop, 0.82rem));
+		text-align: var(--section-markdown-h3-align-mobile, var(--section-markdown-h3-align-desktop, left));
+	}
+
+	.section-markdown h4 {
+		font-size: var(--section-markdown-h4-font-size-mobile, var(--section-markdown-h4-font-size-desktop, clamp(0.96rem, 0.94rem + 0.08vw, 1rem)));
+		text-align: var(--section-markdown-h4-align-mobile, var(--section-markdown-h4-align-desktop, left));
+	}
+
+	.card-list-layout-image-left .card-list-item-has-image,
+	.card-list-layout-image-right .card-list-item-has-image,
+	.card-list-layout-image-left .card-list-item-has-image .card-list-link,
+	.card-list-layout-image-right .card-list-item-has-image .card-list-link {
+		grid-template-columns: 1fr;
+	}
+
+	.card-list-layout-image-right .card-list-image-frame {
+		order: 0;
+	}
+
+	.section-markdown ul,
+	.section-markdown ol {
+		display: block;
+	}
+
+	.managed-image-item img {
+		max-height: var(--image-max-height);
+	}
+
+	.image-carousel-position {
+		position: absolute;
+		right: 0.5rem;
+		bottom: 0.5rem;
+		min-width: 3rem;
+		min-height: 1.75rem;
+		padding: 0.3rem 0.55rem;
+		font-size: 0.75rem;
+	}
+
+	:is(.image-stack, .managed-images) {
+		gap: var(--space-image-item);
+	}
+
+	.image-details {
+		padding: 0 0.25rem;
+		font-size: 1rem;
+	}
+}
+
+@media (forced-colors: active) {
+	:root,
+	:root[data-appearance='dark'],
+	:root[data-appearance='system'] {
+		--color-page: Canvas;
+		--color-primary-text: CanvasText;
+		--color-secondary-text: CanvasText;
+		--color-link-text: LinkText;
+		--color-text: CanvasText;
+		--color-muted: CanvasText;
+		--color-accent: LinkText;
+		--color-surface: Canvas;
+		--color-soft: CanvasText;
+		--color-border: CanvasText;
+		--color-nav-separator: CanvasText;
+		--color-frame-background: Canvas;
+		--color-frame-text: CanvasText;
+		--color-surface-base-background: Canvas;
+		--color-surface-base-text: CanvasText;
+		--color-surface-base-secondary-text: CanvasText;
+		--color-surface-soft-background: Canvas;
+		--color-surface-soft-text: CanvasText;
+		--color-surface-soft-secondary-text: CanvasText;
+		--color-surface-emphasis-background: Canvas;
+		--color-surface-emphasis-text: CanvasText;
+		--color-surface-emphasis-secondary-text: CanvasText;
+		--color-focus-ring: Highlight;
+		--color-focus-ring-contrast: Canvas;
+		--color-selection-background: Highlight;
+		--color-selection-text: HighlightText;
+		--color-control-background: ButtonFace;
+		--color-control-background-active: Highlight;
+		--color-control-text: ButtonText;
+		--color-code-background: Canvas;
+		--color-code-text: CanvasText;
+		--color-warning-accent: Highlight;
+		--color-warning-surface: Canvas;
+		--color-warning-text: CanvasText;
+		--color-error-accent: Highlight;
+		--color-error-surface: Canvas;
+		--color-error-text: CanvasText;
+		--color-success-accent: Highlight;
+		--color-success-surface: Canvas;
+		--color-success-text: CanvasText;
+	}
+
+	.display-settings-panel,
+	.mobile-nav-panel,
+	.site-nav-submenu > nav,
+	.card-list-item,
+	.image-carousel-button,
+	.image-carousel-position {
+		border: 1px solid CanvasText;
+		box-shadow: none;
+	}
+
+	:is(.display-settings button, .display-settings-segmented span, .mobile-nav-menu > summary, .site-banner-dismiss) {
+		border-color: ButtonText;
+		background: ButtonFace;
+		color: ButtonText;
+	}
+
+	:is(.display-settings-segmented input:checked + span, .image-carousel-button:hover:not(:disabled)) {
+		background: Highlight;
+		color: HighlightText;
+	}
+}

package/starters/basic/README.md

@@ -12,7 +12,7 @@ npm run norna:dev
 If the standard local port is blocked, start with:
 
 ```sh
-npm run norna:dev -- --kill
+npm run norna:dev
 ```
 
 Edit shared logo settings, banners, and footer in
@@ -34,7 +34,7 @@ Norna derives `/repository-name/` as the base path. Use a root URL such as
 
 In GitHub repository settings, configure Pages to build from GitHub Actions.
 
-Page width, side gutters, content spacing, image sizing, palette, shape, and
+Page width, side gutters, content spacing, image sizing, palette, corners, and
 site-wide typography are configured in `site/theme.yaml`. A page may use a
 limited `theme.yaml` for local text width, content spacing, managed-image
 sizing, and section background pattern.
@@ -65,7 +65,7 @@ Use `npm run norna:engine:version` to inspect the installed engine and
 
 Generic documentation lives in the `norna` repository:
 
-- `docs/getting-started.md`
+- `docs/README.md`
 - `docs/site-files.md`
 - `docs/public-files.md`
 - `docs/content.md`

package/docs/README.md

@@ -1,137 +0,0 @@
-# Norna Documentation
-
-The [Norna introduction site](https://janga.github.io/norna/) explains what the
-tool is for. These Markdown files are the authoritative tutorial, workflow
-guides, and reference.
-
-## Start Here
-
-1. [Build your first Norna site](getting-started.md) follows one short path from
-   an empty directory to a checked build.
-2. [Site Files](site-files.md) is the canonical map of every source file,
-   convention-based directory, and generated location.
-3. [Requirements and limitations](requirements.md) lists required software and
-   current product boundaries.
-4. [Examples](../examples/README.md) pairs complete and focused source projects
-   with rendered sites.
-
-Do not read the reference from beginning to end before trying Norna. Complete
-the tutorial, then open the reference for the file or workflow you are changing.
-
-## Site File Reference
-
-Norna expects this top-level source model:
-
-```text
-site/
-|-- config.yaml
-|-- theme.yaml
-|-- sitewide-content.yaml
-|-- pages/
-|   |-- 000-home/
-|   |   |-- content.md
-|   |   `-- images/
-|   `-- 010-guide/
-|       `-- content.md
-`-- public/
-```
-
-- [`config.yaml`](configuration.md): public URL, language, and native browser
-  scroll behavior.
-- [`theme.yaml`](theme.md): complete visual presets and focused presentation
-  overrides.
-- [`sitewide-content.yaml`](sitewide-content.md): shared logo display settings,
-  banners, and footer.
-- [`pages/`](pages.md): Home, top-level areas, nested pages, ordering, and URLs.
-- [`content.md`](content.md): the content file inside every page directory,
-  containing its title, optional metadata, sections, prose, notes, and blocks.
-- [`images/`](images-and-metadata.md): managed images kept inside the page that
-  references them, plus variants, sync, and generated image state.
-- [`public/`](public-files.md): navigation logos, favicons, and other static
-  files copied without managed-image processing.
-- [Generated files](site-files.md#generated-files): `site/.norna/public/`,
-  `dist/`, and `.astro/`.
-
-The [complete Site Files reference](site-files.md) explains which paths are
-required, optional, convention-discovered, versioned, or generated.
-
-## Common Workflows
-
-### Create And Run A Site
-
-- [Create a standalone site](getting-started.md#1-create-and-run-the-site)
-- [Add Norna to an existing Node project](how-to/embedded-site.md)
-- [Start and manage local preview](local-development.md)
-- [Inspect or update the installed engine](commands.md#command-summary)
-
-### Write Content
-
-- [Write page sections](content.md#sections)
-- [Use image stacks, carousels, and cards](content.md#norna-blocks)
-- [Add notes to prose](content.md#markdown-text)
-- [Add another page](pages.md)
-- [Add shared banners or footer content](sitewide-content.md)
-
-### Work With Images And Public Assets
-
-- [Add managed source images](images-and-metadata.md#managed-source-images)
-- [Check and sync moved image references](content.md#validation-and-sync)
-- [Add a navigation logo](public-files.md#navigation-logo)
-- [Add browser icons](public-files.md#browser-icons)
-- [Add other static files](public-files.md#other-static-files)
-
-### Change Presentation
-
-- [Choose a complete theme preset](theme.md#theme-presets)
-- [Inspect and override a preset](theme.md#overrides)
-- [Adjust limited presentation for a page subtree](theme.md#page-themes)
-- [Adjust typography](typography.md)
-
-### Check, Build, And Publish
-
-- [Run configuration and content checks](commands.md#starter-npm-scripts)
-- [Build and inspect generated output](site-files.md#generated-files)
-- [Publish through GitHub Pages](publishing.md#github-pages-workflow)
-- [Monitor or troubleshoot deployment](publishing.md)
-
-## Concepts And Explanation
-
-- [Norna's site model](https://janga.github.io/norna/concepts/) explains how
-  files, sections, images, and pages become a website.
-- [Images and Metadata](images-and-metadata.md) explains managed variants and
-  published URLs.
-- [Command Organization](design/command-organization.md) explains standalone,
-  embedded, and engine-development command models.
-- [Site Examples Structure](design/site-examples-structure.md) distinguishes
-  starters, examples, documentation sites, and fixtures.
-
-## Command And Platform Reference
-
-- [Commands](commands.md): CLI commands, npm scripts, and options.
-- [Requirements and limitations](requirements.md): runtime dependencies,
-  optional tools, and current boundaries.
-- [Publishing](publishing.md): GitHub Pages workflow and deploy helpers.
-
-## Troubleshooting
-
-- [Common first problems](getting-started.md#common-first-problems)
-- [Manage and restart local preview](local-development.md#manage-preview)
-- [Rebuild a stale preview](local-development.md#rebuild-stale-preview)
-- [Validate and sync content](content.md#validation-and-sync)
-- [Inspect publishing failures](publishing.md)
-- [Report a reproducible problem](https://github.com/janga/norna/issues)
-
-## Engine Contributors
-
-Start with [Engine Development](engine-development.md). Design documents live
-under [`docs/design/`](design/), and planned work is tracked in
-[BACKLOG.md](../BACKLOG.md).
-
-## AI-Readable Access
-
-The documentation source is Markdown and can be read directly from this
-repository. The published site also exposes
-[`llms.txt`](https://janga.github.io/norna/llms.txt), which links AI tools to
-the authoritative Markdown entry points rather than duplicating them.
-
-Norna is licensed under [GNU GPL v3](../LICENSE).