@t09tanaka/stoneage 0.1.0

package/README.md

@@ -0,0 +1,768 @@
+# StoneAge
+
+StoneAge is a data-site static site generator for publishing large, structured
+datasets as fast, plain HTML.
+
+It is not intended to be a general-purpose web application framework. The core
+use case is a site with tens of thousands of generated pages, normalized data
+exports, stable URLs, rich metadata, and a build pipeline that can regenerate
+only the pages affected by changed inputs.
+
+## Start Here
+
+- Build a new site: start with [Getting Started](docs/getting-started.md), then
+  use [Site Build Guide](docs/site-build.md) for route families, artifacts,
+  metadata, assets, validation, and publishing.
+- Define reusable templates: read [Components](docs/components.md) for TSX,
+  `html()`, `renderToString()`, static components, and opt-in islands.
+- Migrate an existing SvelteKit static site: run the audit command and follow
+  [Migration Guide](docs/migration.md). StoneAge migration is not an adapter;
+  it converts routes, data, endpoints, and layouts into explicit static build
+  inputs.
+- Understand the data pipeline: read [Data Flow](docs/data-flow.md) for
+  normalized data, public artifacts, view models, and dependency tracking.
+
+## Goals
+
+- Generate plain HTML as the default output.
+- Avoid required runtime hydration payloads for page rendering.
+- Keep data normalization separate from HTML rendering.
+- Generate JSON, XML, CSV, and other non-HTML artifacts through explicit
+  artifact routes that share dependency caching without becoming page payloads.
+- Regenerate pages incrementally from input hashes and dependency metadata.
+- Remove stale page and artifact outputs from previous full builds when they
+  disappear from the current manifest.
+- Provide typed route definitions for large page families.
+- Reject duplicate page paths, duplicate artifact paths, and page/artifact
+  output file collisions before rendering starts.
+- Split large listing pages with pagination helpers and stable first-page URLs.
+- Configure trailing slash behavior for canonical URLs, sitemap entries, link
+  validation, and output file paths.
+- Split large sitemaps into a sitemap index plus `sitemap-N.xml` URL set files
+  when a site wants bounded sitemap file sizes.
+- Add page-level prefetch links for likely next navigations without requiring a
+  Service Worker. Sites can also opt into a tiny Service Worker prefetch layer
+  that only warms URLs declared by the current page, and can disable duplicate
+  native prefetch links when the Service Worker is the intended strategy.
+- Generate metadata such as titles, descriptions, canonical URLs, language,
+  favicon links, Open Graph tags, Twitter card tags, noindex robots tags,
+  structured custom head tags, and sitemaps during HTML generation. Open Graph
+  output can be disabled at the site level and re-enabled for high-value pages.
+- Write publishing manifests such as `robots.txt` and generic
+  `redirects.json` files from the same build configuration.
+- Keep assets small and explicit: shared CSS, page-type CSS when needed, and
+  hand-authored JavaScript only for interactive islands.
+- Optimize local raster images into responsive variants when optional `sharp`
+  support is available, while keeping builds functional when it is not.
+- Allow component-style HTML composition, including optional TSX components,
+  without adding a client hydration runtime.
+- Ship validation commands for generated page counts, missing links, exports,
+  public JSON/CSV syntax, sitemap integrity, missing asset references, and large
+  HTML outputs.
+
+## Non-Goals
+
+- StoneAge is not a React, Vue, or Svelte application framework.
+- StoneAge does not require client-side hydration to display generated pages.
+- StoneAge does not mix public data exports with HTML-only view models.
+- StoneAge does not bundle source or normalized data into the published site by
+  default.
+- StoneAge does not assume every generated page should be rebuilt on every run.
+
+## Architecture
+
+StoneAge is a TypeScript framework with Vite integration where it is useful for
+asset bundling and development ergonomics.
+
+The build pipeline is organized around three separate stages:
+
+1. Normalize source data into internal JSON, CSV, or API snapshots.
+2. Derive public data artifacts and HTML view models from those normalized
+   snapshots.
+3. Render HTML pages, metadata, sitemaps, assets, and validation reports from
+   the view models.
+
+The incremental build cache records source hashes, page dependencies, output
+paths, generated links, and metadata. A changed member record, session record, or
+conversation record only invalidates pages that depend on that input.
+View models with record-level dependencies avoid inheriting a broad public data
+artifact hash, while view models without record dependencies fall back to the
+artifact hash for correctness.
+StoneAge also fingerprints route family metadata defaults, page metadata,
+canonical URLs, site-level head settings, title templates, structured custom
+head tags, stylesheet references, and page-local asset/island declarations so
+metadata-only changes do not leave stale HTML head output behind.
+For very large sites that already compute a complete input hash, pass
+`buildFingerprint` to skip route enumeration entirely when the hash matches the
+previous build report. Pass `renderFingerprint` for source templates, CSS
+inputs, and artifact renderers; when it changes, StoneAge invalidates cached
+page and artifact outputs even if their data dependencies are unchanged.
+Full builds remove manifest-managed page and artifact outputs that no longer
+exist in the current route plan. Partial builds preserve omitted outputs because
+they intentionally describe only a subset of the site.
+
+## Example Route Families
+
+StoneAge supports route families such as:
+
+```text
+/members/:id/:year/
+/conversations/:id/
+/sessions/:id/
+/bills/:id/
+```
+
+Route implementations should be typed generation functions, not ad hoc string
+concatenation spread through project code.
+
+Use typed route helpers to bind a pattern and its required params in one place:
+
+```ts
+import {
+  defineRouteFamily,
+  pathForRedirect,
+  patternParamMatcher,
+} from "@t09tanaka/stoneage";
+
+const members = defineRouteFamily({
+  name: "members",
+  pattern: "/members/:id/:year/",
+  paramMatchers: {
+    year: patternParamMatcher(/^\d{4}$/),
+  },
+  metadata: {
+    description: "A generated member page",
+    ogType: "profile",
+  },
+  entries: () => [
+    {
+      params: { id: "m1", year: 2026 },
+      dependencies: ["member:member-001"],
+      metadata: {
+        title: "Member profile",
+      },
+      render: () =>
+        `<main><a href="${members.path({ id: "m1", year: 2026 })}">Profile</a></main>`,
+    },
+  ],
+});
+
+const legacyMemberUrl = pathForRedirect("/members/:id/", { id: "m1" });
+```
+
+## Project Status
+
+This repository contains the release-candidate implementation of the data-site SSG core:
+typed route and artifact families, incremental dependency caching, metadata and
+sitemap generation, client asset and image helpers, validation commands,
+deployment manifest generation, a large benchmark example, and package audit
+checks. The migration audit also covers SvelteKit route entries, layout chains,
+page actions, static endpoint methods, and reset route files so a large static
+site can be moved without introducing an adapter layer.
+
+## Example Site And Performance Work
+
+The example site is part of the product, not a throwaway demo. It contains
+enough generated data to expose real scaling problems: many records, many route
+families, large index pages, metadata-heavy detail pages, exports, and sitemap
+generation.
+
+The framework measures the example site quantitatively and optimizes from
+those measurements. Useful metrics include build time, incremental build time,
+generated page count, total output size, largest HTML files, CSS and JavaScript
+payloads, image output size, image optimization results, route-family write
+counts, link-check time, sitemap size, and Lighthouse results for selected
+pages.
+
+The large example benchmark disables Open Graph tags by default to keep repeated
+detail pages small while preserving title, description, canonical, and sitemap
+metadata.
+
+The example keeps internal record IDs separate from public URL slugs. Dependency
+tracking and optional exports keep stable source IDs, while generated HTML,
+links, and sitemap entries use shorter stable route slugs to reduce repeated
+payload.
+
+Tailwind CSS may be used as the default styling pipeline, but generated CSS must
+remain small and predictable. StoneAge can build Tailwind output from explicit
+route/component class candidates, which avoids scanning generated HTML at large
+page counts. Existing Vite, PostCSS, or Tailwind pipelines can also stay outside
+the HTML generator: build CSS as a normal asset, read the Vite manifest when
+needed, and attach the resulting stylesheet paths through page metadata or the
+client asset registry.
+
+Client JavaScript is opt-in per page. Declare small assets or islands once, then
+attach their ids from page metadata:
+
+```ts
+import { defineClientAssets, island, stylesheet } from "@t09tanaka/stoneage/assets";
+import { html, islandMount, renderToString } from "@t09tanaka/stoneage/html";
+
+const client = defineClientAssets({
+  search: [
+    stylesheet("/assets/search.css", { source: "asset-build/search.css" }),
+    island("/assets/search.js", {
+      source: "asset-build/search.js",
+      attributes: { "data-island": "search" },
+    }),
+  ],
+});
+
+await buildSite({
+  outDir: "dist",
+  site,
+  publishing: { headers: true },
+  assets: {
+    client,
+  },
+  routes: [
+    {
+      name: "search",
+      pattern: "/search/",
+      entries: async () => [
+        {
+          params: {},
+          metadata: {
+            title: "Search",
+            description: "Search the archive",
+            islands: ["search"],
+          },
+          render: () =>
+            renderToString(
+              html(
+                "main",
+                null,
+                islandMount("search", {
+                  key: "site-search",
+                  props: { index: "/search.json" },
+                }),
+              ),
+            ),
+        },
+      ],
+    },
+  ],
+});
+```
+
+Assets declared with a `source` file are copied with a content hash in the
+filename, their HTML references are rewritten, and `publishing.headers` adds an
+immutable cache-control entry. Plain string paths and `assets.public` entries
+continue to use fixed filenames.
+
+For Google Fonts CSS2 subsets, use `googleFontsStylesheet("/assets/fonts.css",
+{ families: ["Zen Maru Gothic:wght@700;900", "Outfit:wght@700;900"], text:
+subsetText })`. StoneAge fetches the CSS and WOFF2 files at build time, rewrites
+`@font-face` URLs to local content-hashed assets, and emits immutable cache
+headers for the generated CSS and font files.
+
+For Vite builds, `loadViteBuildAssetsFromManifest("dist/.vite/manifest.json", {
+sourceDir: "dist", base: "/", entriesOnly: true })` reads a Vite manifest and
+returns both `assets.client` and `assets.public` inputs. That lets a separate
+Vite, PostCSS, or Tailwind pipeline produce hashed CSS, JS, and imported static
+assets while StoneAge handles page injection and output-directory sync. Imported
+chunk CSS is emitted before entry CSS, duplicate stylesheet paths are removed,
+and `{ entriesOnly: true }` can keep non-entry chunks out of the client asset
+registry while still copying emitted public files. Use `assetsFromViteManifest()`
+or `publicAssetsFromViteManifest()` when a build script already has the manifest
+object in memory and only needs one side of the mapping.
+
+Use `copyPublicAssets()` when those external pipelines write assets outside the
+StoneAge output directory. It copies files into stable public paths, rejects
+paths that would escape the output directory or collide with another configured
+asset, and skips unchanged files so asset sync does not force unrelated page
+rewrites. Full builds remove managed public assets that were listed in the
+previous report but are no longer configured; partial builds preserve them.
+Pages still render as plain HTML and no hydration payload is generated by
+default. `islandMount()` emits a root `data-island` element and only writes an
+adjacent JSON props script when a page explicitly passes props for that island.
+
+Deferred fragments can move supplemental HTML out of the initial page while
+keeping the output static. Use `defineFragmentFamily()` for fragment outputs and
+`deferredFragment()` from `@t09tanaka/stoneage/fragment` for the placeholder.
+Fragments are emitted under `/_fragments/` as `.html` artifacts with
+`text/html; charset=utf-8` and `x-robots-tag: noindex`; they are not pages, do
+not receive metadata or canonical URLs, and are not added to sitemaps. Keep a
+custom fallback link when you want the no-JavaScript path to use a canonical
+page instead of the default fragment self-link. Pass `fallback: null` only when
+the deferred content can be omitted without JavaScript. When fragments are
+configured, StoneAge emits and wires the built-in client controller
+automatically; pass `fragments: { families, client: false }` to keep manual
+wiring. The controller supports `visible`, `details-open`, `idle`, and `manual`
+triggers.
+
+The package entrypoints are explicit. Import core build APIs from
+`@t09tanaka/stoneage`, client asset helpers from `@t09tanaka/stoneage/assets`,
+data-flow helpers from `@t09tanaka/stoneage/data`, deploy artifact helpers from
+`@t09tanaka/stoneage/deploy`, TSX helpers from `@t09tanaka/stoneage/html`,
+deferred fragment helpers from `@t09tanaka/stoneage/fragment`,
+image helpers from `@t09tanaka/stoneage/images`, SvelteKit migration audit
+helpers from `@t09tanaka/stoneage/migration`, optimization helpers from
+`@t09tanaka/stoneage/optimize`, pagination helpers from
+`@t09tanaka/stoneage/pagination`, and optional search-index helpers from
+`@t09tanaka/stoneage/search`.
+
+Data is injected at build time to prebuild the static site. Public JSON or CSV
+exports are optional publishing features, not required page payloads.
+Normalized snapshots can live outside `outDir` or under an internal
+`.stoneage/normalized` path; they are not published unless you expose them
+through artifact routes.
+
+Large data producers can pass a complete `contentFingerprint` plus
+`cacheManifestPath` to `writeNormalizedJsonData()` or
+`writeNormalizedCsvData()`. When the fingerprint and manifest entry match an
+existing snapshot, StoneAge reuses the snapshot metadata without rendering the
+JSON/CSV string or reading the existing snapshot body:
+
+```ts
+await writeNormalizedJsonData({
+  key: "public:members",
+  path: ".stoneage/normalized/members.json",
+  data: members,
+  contentFingerprint: { hash: membersContentHash },
+  cacheManifestPath: ".stoneage/normalized-manifest.json",
+});
+```
+
+The fingerprint must cover the full rendered snapshot content. This fast path
+is for pipelines that already hash normalized records or shards before HTML
+rendering.
+
+Non-HTML outputs use artifact routes. They are cached and reported alongside
+HTML pages, but they do not receive HTML metadata and are not added to the
+sitemap:
+
+```ts
+import {
+  artifactEntriesFromPublicData,
+  definePublicDataJsonArtifacts,
+  renderCsvArtifact,
+  writeNormalizedJsonData,
+} from "@t09tanaka/stoneage/data";
+
+const publicMembers = await writeNormalizedJsonData({
+  key: "public:members",
+  path: "data/normalized/members.json",
+  data: members,
+  sourceDependencies: [{ key: "source:members", file: "data/source/members.csv" }],
+});
+
+await buildSite({
+  outDir: "dist",
+  site,
+  routes,
+  artifacts: [
+    {
+      name: "csvExports",
+      pattern: "/exports/:name.csv",
+      entries: () =>
+        artifactEntriesFromPublicData([publicMembers], {
+          params: () => ({ name: "members" }),
+          render: (artifact) =>
+            renderCsvArtifact(artifact.data, [
+              { header: "id", value: (member) => member.id },
+              { header: "name", value: (member) => member.name },
+            ]),
+        }),
+    },
+    definePublicDataJsonArtifacts([publicMembers], {
+      path: (artifact) => `/data/${artifact.key.replace("public:", "")}.json`,
+    }),
+  ],
+});
+```
+
+`artifactEntriesFromPublicData()` can turn normalized public data artifacts into
+artifact route entries while preserving their source dependencies. This is the
+intended migration path for endpoint-style outputs such as `site-data.json`,
+`search-index.json`, public CSV exports, and other SvelteKit `+server.ts`
+equivalents. `renderJsonArtifact()` and `renderCsvArtifact()` provide small,
+framework-independent renderers for those public exports. When a migrated
+SvelteKit `+server.ts` endpoint needs response-style metadata, return
+`jsonArtifact()`, `csvArtifact()`, `xmlArtifact()`, `textArtifact()`, or
+`artifactResponse()` from `@t09tanaka/stoneage`; StoneAge writes the static body and records
+`contentType`, `status`, and `headers` in the generated manifest.
+When `publishing` is enabled, artifact `contentType` and headers are also
+collected into a host-neutral `headers.json` manifest unless
+`publishing.headers` is set to `false`. Deployment tooling can translate that
+manifest to provider-specific header rules without mixing endpoint metadata into
+page renderers.
+`definePublicDataJsonArtifacts()` can publish split JSON data files plus a
+small `site-data.json` manifest that lists their public paths. The manifest
+depends on the list of exported files, while each data file keeps its own source
+and public-data dependencies.
+
+Optimized image variants can be consumed as structured attributes or rendered
+directly as compact HTML:
+
+```ts
+import { optimizeImages, pictureHtmlFor } from "@t09tanaka/stoneage/images";
+
+const result = await optimizeImages({
+  outDir: "dist",
+  images: [{ source: "assets/member.jpg", publicPath: "/images/member.jpg" }],
+  widths: [320, 640, 960],
+  formats: ["avif", "webp", "jpeg"],
+});
+
+const picture = pictureHtmlFor(result.generated, {
+  src: "/images/member.jpg",
+  width: 960,
+  height: 640,
+  alt: "Member portrait",
+  sizes: "(min-width: 48rem) 33vw, 100vw",
+  loading: "lazy",
+  decoding: "async",
+  fallbackFormat: "jpeg",
+});
+```
+
+Paginated index routes can keep navigation data outside templates:
+
+```ts
+import { paginationLinks } from "@t09tanaka/stoneage/pagination";
+
+const nav = paginationLinks(page.page, conversations.length, {
+  pageSize: 50,
+  pathForPage: (pageNumber) =>
+    pageNumber === 1 ? "/conversations/" : `/conversations/page/${pageNumber}/`,
+});
+```
+
+The helper returns `previous`, `next`, and a stable page list. It does not render
+HTML, so components can decide whether to expose links, metadata head tags, or
+prefetch hints.
+
+Search indexes are just optional artifacts. `defineSearchIndexArtifact()` can
+publish a stable `search-index.json` for client-side search without making that
+JSON required for ordinary page rendering:
+
+```ts
+import { defineSearchIndexArtifact } from "@t09tanaka/stoneage/search";
+
+await buildSite({
+  outDir: "dist",
+  site,
+  routes,
+  artifacts: [
+    defineSearchIndexArtifact({
+      records: members,
+      dependencies: members.map((member) => ({
+        key: `member:${member.id}`,
+        value: member,
+      })),
+      document: (member) => ({
+        id: member.id,
+        title: member.name,
+        url: `/members/${member.slug}/${member.year}/`,
+        tags: ["member", member.district],
+      }),
+    }),
+  ],
+});
+```
+
+Route URLs use trailing slashes by default and write directory-style output such
+as `members/m1/2026/index.html`. Sites that need extension-style output can set
+`trailingSlash: "never"`:
+
+```ts
+await buildSite({
+  outDir: "dist",
+  trailingSlash: "never",
+  site,
+  routes,
+});
+```
+
+This normalizes generated paths, canonical URLs, sitemap entries, internal link
+validation, and page-local prefetch hints. Route renderers still own their HTML
+body links, so projects should emit body hrefs that match their chosen URL
+style.
+
+For large route families, entries may declare their internal body links with
+`links`. When present, StoneAge records those normalized links directly instead
+of scanning the rendered HTML for anchors:
+
+```ts
+{
+  params: { id: member.slug },
+  links: conversations.map((conversation) => `/conversations/${conversation.slug}/`),
+  render: () => renderMember(member, conversations),
+}
+```
+
+Large sites can split sitemap output while keeping `sitemap.xml` as the public
+entry point:
+
+```ts
+await buildSite({
+  outDir: "dist",
+  site,
+  sitemap: {
+    maxUrlsPerFile: 10_000,
+  },
+  routes,
+});
+```
+
+When the indexable page count exceeds the limit, StoneAge writes `sitemap.xml`
+as a sitemap index and writes child URL sets such as `sitemap-1.xml` and
+`sitemap-2.xml`. `validate` follows the index and compares the combined child
+URLs against the generated manifest. It also reports sitemap index entries that
+point at missing child sitemap files.
+
+Useful commands:
+
+```sh
+npm run benchmark
+npm run benchmark -- --trailing-slash never
+npm run benchmark -- --public-data-exports
+npm run benchmark:large
+npm run benchmark:large:compare
+npm run check:publish
+npm run optimize
+npm run deploy -- --provider netlify
+npm run dev -- --out-dir example/dist --watch src --watch docs --build-command "npm run benchmark"
+npm run audit:sveltekit -- --routes-dir ../example-sveltekit/src/routes --params-dir ../example-sveltekit/src/params --json --report migration/sveltekit-audit.json
+npm run audit:sveltekit -- --routes-dir ../example-sveltekit/src/routes --params-dir ../example-sveltekit/src/params --migration-plan --json --report migration/sveltekit-plan.json
+npm run audit:sveltekit -- --routes-dir ../example-sveltekit/src/routes --params-dir ../example-sveltekit/src/params --emit-stubs migration/stubs
+npm run inspect -- --dependency member:member-001
+npm run --silent inspect -- --dependency member:member-001 --json
+npm run validate
+npm run validate -- --max-html-bytes 25000 --max-css-bytes 50000 --max-js-bytes 10000 --max-public-file-bytes 2000000 --max-total-public-bytes 50000000 --max-image-bytes 10000000 --max-dependency-fanout 500
+npm run validate -- --validation-config validation.json
+npm run validate -- --write-validation-config validation.json
+npm run --silent validate -- --json --report example/dist/.stoneage/validation-summary.json
+npm run check:package
+npx @t09tanaka/stoneage --help
+```
+
+`inspect --dependency <key>` reads the generated manifest and lists the pages and
+artifacts that currently depend on that key. Use `--json` for scripts that plan
+partial rebuilds or audit the dependency graph.
+
+`dev` serves the generated output directory and injects a small Server-Sent
+Events reload client into HTML responses. Use `--build-command <command>` with
+one or more `--watch <path>` options to rebuild on source changes; browsers
+reload only after the build command succeeds. StoneAge ignores the output
+directory, `.git`, and `node_modules` while watching to avoid rebuild loops.
+
+`benchmark --compare-to <file>` compares the current `.stoneage/benchmark.json`
+metrics with a previous benchmark report and fails the command when size metrics
+grow beyond `--max-size-regression-percent` (default `0`). The comparison is
+limited to deterministic payload metrics such as total/public output bytes,
+HTML/CSS/JS/image/data bytes, HTML averages, and p95 HTML size. Build times are
+reported but not used as pass/fail gates because they are environment-dependent.
+Use `--comparison-report <file>` when CI
+should persist the pass/fail result, compared metric count, baseline path,
+current report path, and individual regressions as JSON.
+Use `npm run benchmark:large:compare` for CI baseline comparisons against the
+committed `baselines/benchmark-large.json` report. Use `npm run check:publish`
+when a publish gate should run that benchmark comparison and validate the output
+with `validation.json`. Runtime compression is expected to be handled by the
+serving layer, such as CloudFront, so routine benchmark and publish checks do not
+precompress or compare Brotli/Gzip transfer estimates.
+
+`validate` reads the generated `.stoneage/report.json`, split data-flow reports
+(`.stoneage/data-flow-summary.json` and
+`.stoneage/data-flow-dependencies.json`), and sitemap output, then reports page counts,
+artifact counts, managed public asset counts and copy/skip counts, missing links, required metadata issues, duplicate or missing
+canonical URLs, sitemap drift, dependency fanout, route/artifact data-flow
+summaries, public JSON/CSV exports, sitemap URL count, sitemap file count,
+duplicate sitemap URLs, invalid sitemap URL values, missing child sitemap files,
+JSON parse failures, basic CSV structural failures,
+missing title/description/canonical tags in generated HTML, generated canonical
+URL duplicates, canonical paths that do not match the manifest,
+framework hydration payload markers or runtime `__data.json` page data
+references,
+missing CSS/JS/image/icon/OGP/Twitter image/video poster references from generated HTML, missing or
+size-mismatched manifest outputs, duplicate manifest output paths, stale or
+mismatched `headers.json` entries for artifact response metadata, invalid or
+stale `redirects.json` entries, invalid or missing sitemap references in
+`robots.txt`, stale Netlify `_redirects` or `_headers` deploy artifacts, public
+HTML files that are not listed in the manifest, missing local prefetch targets,
+budget failures, public output file bytes by type, precompressed transfer
+sidecar coverage when explicitly requested, referenced stylesheet asset bytes, public CSS and JavaScript
+asset bytes, image asset bytes, the largest HTML files, the largest generated
+artifacts, the largest public output files, the largest referenced stylesheets,
+the largest public CSS and JavaScript files, and the largest public image files.
+The optional HTML, CSS, JavaScript, public-file, total-public, image, Brotli,
+and Gzip budgets are byte limits for generated output. Use public-file budgets
+to catch a single oversized sitemap, image, or export, total-public budgets to
+catch whole-site payload growth, image budgets to catch image optimization
+regressions, and route family page budgets and artifact family output budgets
+catch accidental output growth inside high-cardinality route groups or export
+families before the whole site budget is exceeded. Brotli/Gzip sidecars remain
+available through `optimize` for hosts that need precompressed files, but the
+default publish gate leaves runtime compression to the serving layer.
+Page, artifact, route family, artifact family, HTML, and dependency fanout
+budgets are also available in `buildSite({ validation })`, so the generated
+`.stoneage/report.json` records publish-gate failures even before the standalone
+`validate` command runs.
+The optional dependency fanout budget limits
+how many generated pages and artifacts a single data dependency can invalidate;
+it is available both in build validation and in the `validate` command.
+Use `--validation-config <file>` to load stable CI validation settings from a
+JSON file. CLI budget flags override values from the file, and
+`--require-precompressed` is available only for deployments that intentionally
+ship precompressed sidecars:
+
+```json
+{
+  "budgets": {
+    "maxPages": 22172,
+    "maxRouteFamilyPages": {
+      "categoryIndexes": 1,
+      "yearIndexes": 1,
+      "members": 250,
+      "sessions": 120,
+      "conversationIndexes": 1000,
+      "conversations": 20000,
+      "bills": 800
+    },
+    "maxHtmlBytes": 1810,
+    "maxPublicFileBytes": 738738,
+    "maxCssBytes": 376,
+    "maxJsBytes": 518,
+    "maxTotalPublicBytes": 16780313,
+    "maxImageBytes": 17000,
+    "maxDependencyFanout": 2
+  }
+}
+```
+Unknown top-level or budget keys are rejected so configuration typos do not
+silently weaken publish checks. JSON validation summaries and report files
+include the effective validation options, config path, and config SHA-256 hash
+when one was used, so CI artifacts can show which publish gate was applied.
+Build scripts can share the same file for build-time validation:
+
+```ts
+import { buildSite, loadValidationConfig } from "@t09tanaka/stoneage";
+
+await buildSite({
+  outDir: "dist",
+  site,
+  validation: await loadValidationConfig("validation.json"),
+  routes,
+});
+```
+
+`loadValidationConfig()` returns the build-time `requiredMetadata` and `budgets`
+settings, plus the source config path and SHA-256 hash that are copied into the
+generated build validation report. The CLI-only `requirePrecompressed` flag is
+still validated so one shared file can be used by both build scripts and
+`stoneage validate`.
+Use `--write-validation-config <file>` after measuring a representative output
+to write an exact baseline config from the current page count, artifact count,
+largest HTML file, largest public file, largest public CSS and JavaScript files,
+total public bytes, image bytes, and largest
+dependency fanout. The generated file is intentionally strict; edit it when a
+site wants explicit growth headroom.
+Public JSON/CSV export validation covers both `data/` exports and generated
+artifact routes such as `/exports/*.csv` or `/search-index.json`.
+
+Use `--json` when CI or another tool should consume the validation summary from
+stdout. Use `--report <path>` to write the same summary to a JSON file.
+`check:package` builds the package, audits the packed file list and public
+subpath imports, installs the tarball into a temporary project, and runs the
+installed `stoneage --help` bin.
+
+`audit-sveltekit` statically scans a SvelteKit route tree and reports candidate
+StoneAge page routes, artifact routes, dynamic params, param matchers, endpoint
+content kinds, universal `+page.ts` / `+page.js` and `+layout.ts` /
+`+layout.js` load modules, and migration warnings. Warnings include
+optional/rest params, missing matcher files, sibling dynamic routes, route-group
+page duplicates, page/artifact same-path outputs, and static paths shadowed by
+bare dynamic routes. It is not an adapter and does not execute SvelteKit code.
+Use it to build a route migration checklist before replacing `+page.server.ts`,
+universal load modules, and `+server.ts` files with normalized data producers,
+typed route families, and artifact routes. Add `--migration-plan` to include
+deterministic route family and artifact family names, StoneAge patterns, matcher
+wiring, renderer hints for endpoint artifacts, universal load flags, and
+collision-test candidates in the JSON report. Add
+`--emit-stubs <dir>` to also generate migration scaffolding from that plan; it
+implies `--migration-plan` and writes `data.ts`, `routes.ts`, `artifacts.ts`,
+`param-matchers.ts`, `build.ts`, and `collision-tests.md` under the target
+directory. The stubs are intentionally non-adapter code: they import StoneAge
+helpers, include TODOs for normalized data entries, render bodies, and build
+wiring, and do not import SvelteKit modules. Stub emission is no-overwrite by
+default so existing migration files are not silently replaced; the programmatic
+`emitSvelteKitMigrationStubs(plan, dir, { overwrite: true })` API is available
+when regeneration is intentional.
+
+Publishing manifests are opt-in:
+
+```ts
+import { redirectToRoute, redirectsFromRecords } from "@t09tanaka/stoneage";
+
+await buildSite({
+  outDir: "dist",
+  site,
+  publishing: {
+    robots: {
+      rules: [{ userAgent: "*", allow: ["/"], disallow: ["/drafts/"] }],
+    },
+    redirects: [
+      redirectToRoute({
+        from: "/old-members/:id/",
+        fromParams: { id: "m1" },
+        to: "/members/:id/:year/",
+        toParams: { id: "m1", year: 2026 },
+        status: 301,
+      }),
+      ...redirectsFromRecords(memberRecords, {
+        from: "/members/:id/",
+        fromParams: (member) => ({ id: member.slug }),
+        to: "/members/:id/:year/",
+        toParams: (member) => ({ id: member.slug, year: member.canonicalYear }),
+      }),
+    ],
+  },
+  routes,
+});
+```
+
+StoneAge writes `robots.txt` with a default `Sitemap` line and writes
+`redirects.json` and `headers.json` as host-neutral manifests that deployment
+tooling can translate to provider-specific formats. Redirects are not pages and
+are not added to the sitemap; the canonical HTML page should own metadata and
+sitemap membership. `headers.json` is derived from artifact response metadata
+plus managed immutable public assets such as content-hashed CSS, JS, and fonts.
+Run `deploy --provider netlify` after validation to translate those host-neutral
+manifests into Netlify `_redirects` and `_headers` files without adding provider
+syntax to route or artifact definitions. Sites that publish `buildSite` output
+directly to Netlify or Cloudflare Pages can instead set
+`publishing.nativeRedirects: "netlify"` to write `_redirects` during the build;
+when publishing headers are enabled, the same build also writes `_headers` while
+keeping `headers.json` available. Set `publishing.redirectHtml: true` to
+additionally emit a static `<meta http-equiv="refresh">` HTML page at each
+internal redirect's `from` path, so redirects also work on plain static hosts
+that do not interpret `redirects.json` or `_redirects`. A `from` that collides
+with a real page, artifact, or public asset is skipped (the existing file is
+never overwritten), and non-internal sources are left to the manifest. Like
+`redirects.json` itself, these stubs are not swept on incremental builds, so
+clear `dist/` for a clean rebuild after removing redirect rules.
+
+`benchmark` measures generated output sizes without precompressing public files;
+runtime Brotli/Gzip compression is expected to be handled by the serving layer.
+The benchmark command accepts `--trailing-slash always` or
+`--trailing-slash never` so the example site can be measured with either URL
+style. `optimize` writes `.br` and `.gz` sidecars for public
+HTML, CSS, JavaScript, XML, JSON, CSV, text, and SVG files while leaving the
+internal `.stoneage` cache untouched. `validate` reports how many compressible
+public files have Brotli and Gzip sidecars and lists missing sidecars in the
+JSON summary when precompressed sidecar validation is explicitly requested. Pass
+`--require-precompressed` only for deployment targets that require missing
+sidecars to become validation issues.
+
+## Documentation
+
+- [Getting Started](docs/getting-started.md)
+- [Site Build Guide](docs/site-build.md)
+- [Components](docs/components.md)
+- [Testing Components](docs/testing.md)
+- [Migration Guide](docs/migration.md)
+- [Architecture](docs/architecture.md)
+- [Data Flow](docs/data-flow.md)
+- [Performance](docs/performance.md)