npm - @t09tanaka/stoneage - Versions diffs - 0.1.0 → 0.3.0 - Mend

@t09tanaka/stoneage 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,36 @@
 # Changelog
+## 0.3.0 - 2026-06-30
+- Added global stylesheet auto-inlining via `assets.inlineStylesheets` (inline
+  every generated stylesheet) and `assets.inlineStylesheetMaxBytes` (inline only
+  bundles whose built CSS is within the byte threshold). A per-stylesheet
+  `inline` flag still wins; when both options are set the byte threshold gates
+  inlining. Google Fonts WOFF2 stay vendored and preload hints are unchanged.
+## 0.2.0 - 2026-06-30
+- Added immutable `Cache-Control: public, max-age=31536000, immutable` coverage
+  for content-hashed, `/_assets/`, and `/_stoneage/` artifacts that previously
+  lacked it, including the deferred fragment client.
+- Added opt-in `publishing.htmlCacheControl` to emit a host-wide `/*` HTML
+  revalidate default, overridden by more specific immutable asset rules.
+- Added opt-in `publishing.securityHeaders` (HSTS, `X-Content-Type-Options`,
+  `X-Frame-Options`, `Referrer-Policy`, and an `extra` map) emitted as a `/*`
+  rule.
+- Added `publishing.publishManifests` (default `true`) to drop the intermediate
+  `headers.json` / `redirects.json` from published output once host-native
+  `_headers` / `_redirects` are written.
+- Added an `s3` deploy provider that emits a host-neutral `s3-deploy.json`
+  descriptor (with per-rule content-type and Cache-Control) and a
+  `cloudfront-function.js` for pretty-URL and 403/404 -> `/404.html` routing on
+  S3 + CloudFront, without an AWS SDK dependency.
+- Added opt-in critical CSS inlining via stylesheet `inline`, emitting a
+  `<style>` element instead of a render-blocking `<link rel="stylesheet">`.
+- Added self-hosted subset font preloading via `preload` (all or the first N
+  fonts) and ensured `font-display: swap`.
+- Changed the published package to exclude `docs/`.
 ## 0.1.0 - 2026-06-29
 - Added the initial StoneAge data-site SSG release.

package/README.md CHANGED Viewed

@@ -254,7 +254,61 @@ 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.
+headers for the generated CSS and font files. The fetched CSS keeps Google's
+`font-display: swap` (the request defaults to `display=swap`), so fonts never
+block first paint with invisible text.
+To cut render-blocking requests, small critical stylesheets can be inlined into
+the document `<head>` as a `<style>` element instead of a `<link
+rel="stylesheet">`. Opt in per stylesheet with `inline: true` — for `source`
+stylesheets `{ href, source, inline: true }`, and for Google Fonts
+`googleFontsStylesheet("/assets/fonts.css", { families, text, inline: true })`.
+Inlined CSS becomes part of the HTML, so it gets no hashed public file and no
+`_headers` entry; for Google Fonts only the CSS is inlined while the WOFF2 files
+are still vendored as immutable, cacheable assets. Inlining is best for small
+files; an inlined `<style>` is subject to the page's Content-Security-Policy
+`style-src` directive, so keep the external link if you serve a strict CSP
+without `'unsafe-inline'` (or a matching hash/nonce).
+To inline without flagging each stylesheet, set a global policy on `assets`.
+`assets.inlineStylesheets: true` inlines every generated stylesheet (top-level
+and per-page client ones), and `assets.inlineStylesheetMaxBytes: <n>` inlines
+only bundles whose built CSS is at most `n` bytes (UTF-8) — handy for inlining a
+small critical bundle while larger ones stay external. A per-stylesheet `inline`
+flag always wins over the global policy: `inline: false` opts a sheet out and
+`inline: true` opts one in regardless of the threshold. When both options are
+set, `inlineStylesheetMaxBytes` acts as a gate — a bundle over the limit stays
+external even with `inlineStylesheets: true` (a non-positive or non-finite limit
+inlines nothing). The hyogo critical-path setup combines this with font preload
+— inline the small site and fonts CSS while still preloading the primary WOFF2:
+```ts
+assets: {
+  inlineStylesheetMaxBytes: 16_384, // inline bundles ≤ 16 KB
+  stylesheets: [
+    { href: "/assets/site.css", source: "dist/site.css" },
+    googleFontsStylesheet("/assets/fonts.css", {
+      families: ["Zen Maru Gothic:wght@700;900", "Outfit:wght@700;900"],
+      text: subsetText,
+      preload: 2, // keep the primary WOFF2 off the critical chain
+    }),
+  ],
+}
+```
+Both stylesheets inline as `<style>` (when within the threshold), the WOFF2
+files are still vendored as immutable assets, and the preload hints render ahead
+of the inlined CSS so fonts are discovered without waiting on CSS.
+To pull self-hosted fonts off the critical request chain (HTML → CSS → WOFF2),
+emit `<link rel="preload" as="font" type="font/woff2" crossorigin>` hints with
+`googleFontsStylesheet("/assets/fonts.css", { families, text, preload: true })`.
+`preload: true` preloads every WOFF2 the stylesheet resolves; pass a number
+(`preload: 1`) to preload only the first N fonts in CSS source order and avoid
+over-preloading subset ranges the page may not use. Preload hints render before
+the stylesheet and are only honored on top-level `assets.stylesheets`; fonts
+declared in per-page client assets are not preloaded so a hint is never forced
+onto every page.
 For Vite builds, `loadViteBuildAssetsFromManifest("dist/.vite/manifest.json", {
 sourceDir: "dist", base: "/", entriesOnly: true })` reads a Vite manifest and
@@ -744,6 +798,24 @@ 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.
+Run `deploy --provider s3` to target AWS S3 + CloudFront. Instead of Netlify
+files it writes two host-agnostic artifacts next to the output: `s3-deploy.json`
+and `cloudfront-function.js`. `s3-deploy.json` is a provider-neutral deploy
+descriptor derived from the same `redirects.json`/`headers.json` manifests: each
+header rule carries the `contentType` and `cacheControl` to apply when uploading
+the matching objects (so content-hashed assets keep
+`public, max-age=31536000, immutable` and re-syncs do not drop it), a
+`defaults.cacheControl` short-revalidation value covers files no rule matches,
+`redirects` preserves the abstract redirect list, and `errorResponses` maps
+CloudFront 403/404 origin errors to `/404.html`. `cloudfront-function.js` is a
+viewer-request CloudFront Function that resolves pretty URLs to the object the
+build actually wrote. Pass `--trailing-slash always` (default) for sites whose
+pages live at `dir/index.html` (resolves `/dir/` and `/dir`), or
+`--trailing-slash never` for `trailing-slash never` builds whose pages live at
+`name.html` (resolves `/about` to `/about.html`); the chosen style is recorded
+in `s3-deploy.json`. The command does not upload to AWS; it emits the metadata
+and routing logic an upload step or infrastructure template consumes.
 `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

package/dist/agent-skill.d.ts CHANGED Viewed

	@@ -1 +1 @@
1	- export declare const stoneAgeAgentSkill = "---\nname: stoneage\ndescription: Use when working on a StoneAge static data-site, adding routes or artifacts, debugging generated output, validating publish readiness, or helping an agent use StoneAge in a project.\n---\n\n# StoneAge\n\nUse this skill when a project uses StoneAge or asks to generate, validate, inspect, optimize, or serve a StoneAge static data-site.\n\n## Project Direction\n\nStoneAge is a TypeScript static site generator for large data sites. Optimize for plain HTML output, explicit data flow, typed route generation, incremental generation from dependency hashes, publish validation, and small assets. Do not turn StoneAge into a general web application framework.\n\n## Minimal Example\n\nUse these real API names and import paths; do not invent others. Core build: `buildSite`. HTML pages: `defineRouteFamily`. Public data outputs: `defineArtifactFamily` with `jsonArtifact` / `csvArtifact`. Deferred HTML fragments: `defineFragmentFamily` plus `deferredFragment` from the `/fragment` subpath. HTML rendering: `html` / `renderToString` from the `/html` subpath.\n\n```ts\nimport {\n buildSite,\n defineRouteFamily,\n defineArtifactFamily,\n defineFragmentFamily,\n jsonArtifact,\n csvArtifact,\n type SiteConfig,\n} from \"@t09tanaka/stoneage\";\nimport { deferredFragment } from \"@t09tanaka/stoneage/fragment\";\nimport { html, renderToString } from \"@t09tanaka/stoneage/html\";\n\nconst members = [{ id: \"m1\", slug: \"ada\", name: \"Ada\", district: \"Central\" }];\n\nconst site: SiteConfig = {\n baseUrl: \"https://example.com\",\n title: \"Example\",\n description: \"A generated data-site.\",\n};\n\nconst memberDetails = defineFragmentFamily({\n name: \"memberDetails\",\n pattern: \"members/:slug/details\",\n entries: () =>\n members.map((member) => ({\n params: { slug: member.slug },\n dependencies: [\"member:\" + member.id],\n render: () => renderToString(html(\"section\", null, member.name + \" details\")),\n })),\n});\n\nconst memberPages = defineRouteFamily({\n name: \"members\",\n pattern: \"/members/:slug/\",\n entries: () =>\n members.map((member) => ({\n params: { slug: member.slug },\n dependencies: [\"member:\" + member.id],\n metadata: { title: member.name, description: member.name + \" (\" + member.district + \")\" },\n render: () =>\n renderToString(\n html(\n \"main\",\n null,\n html(\"h1\", null, member.name),\n deferredFragment({\n src: memberDetails.path({ slug: member.slug }),\n fallback: html(\"a\", { href: \"/members/\" + member.slug + \"/\" }, \"Read details\"),\n }),\n ),\n ),\n })),\n});\n\nconst memberData = defineArtifactFamily({\n name: \"memberData\",\n pattern: \"/data/members.json\",\n entries: () => [\n {\n params: {},\n dependencies: members.map((member) => \"member:\" + member.id),\n render: () => jsonArtifact(members),\n },\n ],\n});\n\nawait buildSite({\n outDir: \"dist\",\n site,\n routes: [memberPages],\n artifacts: [memberData],\n fragments: [memberDetails],\n});\n```\n\n`render` must return a string (wrap TSX or nodes with `renderToString`). Use `csvArtifact(text)` for CSV outputs. `dependencies` is a `Dependency[]`: a plain `\"key\"` string, or `{ key, hash }` / `{ key, value }` / `{ key, file }` when the site computes its own fingerprints.\n\n## Before Editing\n\n- Search existing buildSite usage before changing a site.\n- Read the local site build entrypoint, route families, artifact families, data normalization modules, and validation config.\n- Keep public data artifacts separate from HTML-only view models.\n- Prefer structured data models and parsers over ad hoc string manipulation.\n- If changing shared types, route patterns, artifact patterns, or build config contracts, inspect references and run TypeScript diagnostics.\n\n## Implementation Rules\n\n- Use route families for HTML pages and artifact families for public JSON, CSV, XML, text, or endpoint-style outputs.\n- Use fragment families for supplemental HTML that may load after the initial page. `deferredFragment()` provides a fragment self-link fallback by default; override it with a canonical page link when one exists, or pass `fallback: null` only when no-JS omission is acceptable. Do not defer the only copy of primary page content.\n- Attach dependencies to generated pages and artifacts so incremental rebuilds can skip unchanged output.\n- Use stable hashes for normalized data or source fingerprints when the site already computes them.\n- Keep rendering functions focused on HTML; keep normalization outside rendering.\n- Add metadata, sitemap, assets, redirects, headers, and validation settings explicitly in the build config.\n- Avoid browser runtime assumptions in core rendering code.\n\n## Useful Commands\n\n- `stoneage dev --out-dir <dir> --watch <path> --build-command \"<command>\"`: serve generated output with hot reload after successful rebuilds.\n- `stoneage validate --out-dir <dir>`: validate generated output before publishing.\n- `stoneage inspect --out-dir <dir> --dependency <key>`: list generated outputs depending on one dependency key.\n- `stoneage plan --out-dir <dir> --dependency <key>`: plan outputs affected by dependency keys.\n- `stoneage optimize --out-dir <dir>`: write precompressed public output sidecars.\n- `stoneage deploy --out-dir <dir> --provider netlify`: emit deploy artifacts.\n\n## Verification\n\n- Run the project's build command after route, artifact, or data-flow changes.\n- Run `stoneage validate` for publish-facing output changes.\n- Run targeted tests for changed data, routes, artifacts, CLI behavior, or validation logic.\n- For package changes in the StoneAge repository, run `npm run typecheck`, relevant `npm test -- <files>`, and `npm run check:package`.\n\n## Avoid\n\n- Do not mix public data exports into HTML-only view models.\n- Do not hide metadata or sitemap decisions inside templates.\n- Do not add compatibility layers, runtime hydration, or app-framework abstractions unless the user explicitly asks.\n- Do not rewrite generated output paths, route contracts, or dependency keys without checking existing manifests and callers.\n\n## References\n\nWhen a detail is not covered here, read the package docs instead of guessing the API: `getting-started.md` (minimal site), `site-build.md` (route families, artifact families, metadata, assets, validation, publishing), `fragments.md` (deferred fragments and triggers), `components.md` (`html()`, `renderToString()`, TSX, islands), `data-flow.md` (normalized data, dependencies, incremental rebuilds), and `migration.md` (SvelteKit). The public API is exported from `@t09tanaka/stoneage`, `@t09tanaka/stoneage/html`, and `@t09tanaka/stoneage/fragment`.\n";
1	+ export declare const stoneAgeAgentSkill = "---\nname: stoneage\ndescription: Use when working on a StoneAge static data-site, adding routes or artifacts, debugging generated output, validating publish readiness, or helping an agent use StoneAge in a project.\n---\n\n# StoneAge\n\nUse this skill when a project uses StoneAge or asks to generate, validate, inspect, optimize, or serve a StoneAge static data-site.\n\n## Project Direction\n\nStoneAge is a TypeScript static site generator for large data sites. Optimize for plain HTML output, explicit data flow, typed route generation, incremental generation from dependency hashes, publish validation, and small assets. Do not turn StoneAge into a general web application framework.\n\n## Minimal Example\n\nUse these real API names and import paths; do not invent others. Core build: `buildSite`. HTML pages: `defineRouteFamily`. Public data outputs: `defineArtifactFamily` with `jsonArtifact` / `csvArtifact`. Deferred HTML fragments: `defineFragmentFamily` plus `deferredFragment` from the `/fragment` subpath. HTML rendering: `html` / `renderToString` from the `/html` subpath.\n\n```ts\nimport {\n buildSite,\n defineRouteFamily,\n defineArtifactFamily,\n defineFragmentFamily,\n jsonArtifact,\n csvArtifact,\n type SiteConfig,\n} from \"@t09tanaka/stoneage\";\nimport { deferredFragment } from \"@t09tanaka/stoneage/fragment\";\nimport { html, renderToString } from \"@t09tanaka/stoneage/html\";\n\nconst members = [{ id: \"m1\", slug: \"ada\", name: \"Ada\", district: \"Central\" }];\n\nconst site: SiteConfig = {\n baseUrl: \"https://example.com\",\n title: \"Example\",\n description: \"A generated data-site.\",\n};\n\nconst memberDetails = defineFragmentFamily({\n name: \"memberDetails\",\n pattern: \"members/:slug/details\",\n entries: () =>\n members.map((member) => ({\n params: { slug: member.slug },\n dependencies: [\"member:\" + member.id],\n render: () => renderToString(html(\"section\", null, member.name + \" details\")),\n })),\n});\n\nconst memberPages = defineRouteFamily({\n name: \"members\",\n pattern: \"/members/:slug/\",\n entries: () =>\n members.map((member) => ({\n params: { slug: member.slug },\n dependencies: [\"member:\" + member.id],\n metadata: { title: member.name, description: member.name + \" (\" + member.district + \")\" },\n render: () =>\n renderToString(\n html(\n \"main\",\n null,\n html(\"h1\", null, member.name),\n deferredFragment({\n src: memberDetails.path({ slug: member.slug }),\n fallback: html(\"a\", { href: \"/members/\" + member.slug + \"/\" }, \"Read details\"),\n }),\n ),\n ),\n })),\n});\n\nconst memberData = defineArtifactFamily({\n name: \"memberData\",\n pattern: \"/data/members.json\",\n entries: () => [\n {\n params: {},\n dependencies: members.map((member) => \"member:\" + member.id),\n render: () => jsonArtifact(members),\n },\n ],\n});\n\nawait buildSite({\n outDir: \"dist\",\n site,\n routes: [memberPages],\n artifacts: [memberData],\n fragments: [memberDetails],\n});\n```\n\n`render` must return a string (wrap TSX or nodes with `renderToString`). Use `csvArtifact(text)` for CSV outputs. `dependencies` is a `Dependency[]`: a plain `\"key\"` string, or `{ key, hash }` / `{ key, value }` / `{ key, file }` when the site computes its own fingerprints.\n\n## Before Editing\n\n- Search existing buildSite usage before changing a site.\n- Read the local site build entrypoint, route families, artifact families, data normalization modules, and validation config.\n- Keep public data artifacts separate from HTML-only view models.\n- Prefer structured data models and parsers over ad hoc string manipulation.\n- If changing shared types, route patterns, artifact patterns, or build config contracts, inspect references and run TypeScript diagnostics.\n\n## Implementation Rules\n\n- Use route families for HTML pages and artifact families for public JSON, CSV, XML, text, or endpoint-style outputs.\n- Use fragment families for supplemental HTML that may load after the initial page. `deferredFragment()` provides a fragment self-link fallback by default; override it with a canonical page link when one exists, or pass `fallback: null` only when no-JS omission is acceptable. Do not defer the only copy of primary page content.\n- Attach dependencies to generated pages and artifacts so incremental rebuilds can skip unchanged output.\n- Use stable hashes for normalized data or source fingerprints when the site already computes them.\n- Keep rendering functions focused on HTML; keep normalization outside rendering.\n- Add metadata, sitemap, assets, redirects, headers, and validation settings explicitly in the build config.\n- Avoid browser runtime assumptions in core rendering code.\n\n## Useful Commands\n\n- `stoneage dev --out-dir <dir> --watch <path> --build-command \"<command>\"`: serve generated output with hot reload after successful rebuilds.\n- `stoneage validate --out-dir <dir>`: validate generated output before publishing.\n- `stoneage inspect --out-dir <dir> --dependency <key>`: list generated outputs depending on one dependency key.\n- `stoneage plan --out-dir <dir> --dependency <key>`: plan outputs affected by dependency keys.\n- `stoneage optimize --out-dir <dir>`: write precompressed public output sidecars.\n- `stoneage deploy --out-dir <dir> --provider <netlify\|github-pages\|s3>`: emit provider-specific deploy artifacts (s3 writes s3-deploy.json + cloudfront-function.js).\n\n## Verification\n\n- Run the project's build command after route, artifact, or data-flow changes.\n- Run `stoneage validate` for publish-facing output changes.\n- Run targeted tests for changed data, routes, artifacts, CLI behavior, or validation logic.\n- For package changes in the StoneAge repository, run `npm run typecheck`, relevant `npm test -- <files>`, and `npm run check:package`.\n\n## Avoid\n\n- Do not mix public data exports into HTML-only view models.\n- Do not hide metadata or sitemap decisions inside templates.\n- Do not add compatibility layers, runtime hydration, or app-framework abstractions unless the user explicitly asks.\n- Do not rewrite generated output paths, route contracts, or dependency keys without checking existing manifests and callers.\n\n## References\n\nWhen a detail is not covered here, read the package docs instead of guessing the API: `getting-started.md` (minimal site), `site-build.md` (route families, artifact families, metadata, assets, validation, publishing), `fragments.md` (deferred fragments and triggers), `components.md` (`html()`, `renderToString()`, TSX, islands), `data-flow.md` (normalized data, dependencies, incremental rebuilds), and `migration.md` (SvelteKit). The public API is exported from `@t09tanaka/stoneage`, `@t09tanaka/stoneage/html`, and `@t09tanaka/stoneage/fragment`.\n";

package/dist/agent-skill.js CHANGED Viewed

@@ -118,7 +118,7 @@ await buildSite({
 - \`stoneage inspect --out-dir <dir> --dependency <key>\`: list generated outputs depending on one dependency key.
 - \`stoneage plan --out-dir <dir> --dependency <key>\`: plan outputs affected by dependency keys.
 - \`stoneage optimize --out-dir <dir>\`: write precompressed public output sidecars.
-- \`stoneage deploy --out-dir <dir> --provider netlify\`: emit deploy artifacts.
+- \`stoneage deploy --out-dir <dir> --provider <netlify|github-pages|s3>\`: emit provider-specific deploy artifacts (s3 writes s3-deploy.json + cloudfront-function.js).
 ## Verification

package/dist/assets.d.ts CHANGED Viewed

@@ -16,15 +16,51 @@ export type GoogleFontsStylesheetOptions = {
     fontBasePath?: string;
     userAgent?: string;
     fetch?: AssetFetch;
+    /**
+     * Emit `<link rel="preload" as="font" type="font/woff2" crossorigin>` hints for
+     * the vendored woff2 files so they leave the critical request chain (HTML →
+     * CSS → woff2). `true` preloads every woff2 the stylesheet resolves; a number
+     * preloads only the first N in CSS source order, so you can limit hints to the
+     * primary fonts and avoid over-preloading subset ranges the page may not use.
+     * Defaults to no preloads. Preload is only honored on top-level
+     * `assets.stylesheets`; fonts declared in per-page client assets are ignored.
+     */
+    preload?: boolean | number;
 };
-export type ClientStylesheetAsset = string | {
+/**
+ * Resolved representation of a stylesheet whose CSS is embedded directly in the
+ * document `<head>` as a `<style>` element (see `inline` below). It carries the
+ * final CSS text rather than a public href. Note: an inlined `<style>` is
+ * subject to the page's Content-Security-Policy `style-src` directive; sites
+ * that send a strict CSP without `'unsafe-inline'` (or a matching hash/nonce)
+ * should keep the stylesheet as an external link instead.
+ */
+export type InlineStylesheetAsset = {
+    inline: string;
+};
+export type ClientStylesheetAsset = string | InlineStylesheetAsset | {
     href: string;
     source: string;
     immutable?: boolean;
+    /**
+     * Inline the CSS into the document `<head>` as a `<style>` element instead
+     * of emitting a render-blocking `<link rel="stylesheet">`. The CSS is then
+     * part of the HTML, so no hashed public file or `_headers` entry is written
+     * for it. Best for small, critical CSS; see {@link InlineStylesheetAsset}
+     * for the CSP caveat.
+     */
+    inline?: boolean;
 } | {
     href: string;
     googleFonts: GoogleFontsStylesheetOptions;
     immutable?: boolean;
+    /**
+     * Inline the resolved Google Fonts CSS into the document `<head>`. The
+     * woff2 files are still vendored as immutable, cacheable assets; only the
+     * small CSS is embedded. See {@link InlineStylesheetAsset} for the CSP
+     * caveat.
+     */
+    inline?: boolean;
 };
 export type ClientScriptAsset = {
     src: string;
@@ -91,9 +127,12 @@ export declare function defineClientAssets<T extends ClientAssetRegistry>(assets
 export type StylesheetAssetOptions = {
     source: string;
     immutable?: boolean;
+    inline?: boolean;
 };
 export declare function stylesheet(href: string, options?: StylesheetAssetOptions): ClientAssetDeclaration;
-export declare function googleFontsStylesheet(href: string, options: GoogleFontsStylesheetOptions): ClientStylesheetAsset;
+export declare function googleFontsStylesheet(href: string, options: GoogleFontsStylesheetOptions & {
+    inline?: boolean;
+}): ClientStylesheetAsset;
 export declare function script(src: string, options?: Omit<ClientScriptAsset, "src">): ClientAssetDeclaration;
 export declare function island(src: string, options?: Omit<ClientScriptAsset, "src" | "module">): ClientAssetDeclaration;
 export declare function resolveClientAssets(registry: ClientAssetRegistry, ids: string[]): ResolvedClientAssets;

package/dist/assets.js CHANGED Viewed

@@ -10,9 +10,11 @@ export function stylesheet(href, options) {
     };
 }
 export function googleFontsStylesheet(href, options) {
+    const { inline, ...googleFonts } = options;
     return {
         href,
-        googleFonts: options,
+        googleFonts,
+        ...(inline ? { inline: true } : {}),
     };
 }
 export function script(src, options = {}) {
@@ -271,26 +273,35 @@ async function bytesEqual(left, rightPath) {
     return left.equals(right);
 }
 function stableStylesheetKey(stylesheet) {
-    return typeof stylesheet === "string"
-        ? stylesheet
-        : "source" in stylesheet
-            ? JSON.stringify({
-                href: stylesheet.href,
-                source: stylesheet.source,
-                immutable: stylesheet.immutable !== false,
-            })
-            : JSON.stringify({
-                href: stylesheet.href,
-                googleFonts: {
-                    families: stylesheet.googleFonts.families,
-                    text: stylesheet.googleFonts.text,
-                    display: stylesheet.googleFonts.display,
-                    endpoint: stylesheet.googleFonts.endpoint,
-                    fontBasePath: stylesheet.googleFonts.fontBasePath,
-                    userAgent: stylesheet.googleFonts.userAgent,
-                },
-                immutable: stylesheet.immutable !== false,
-            });
+    if (typeof stylesheet === "string") {
+        return stylesheet;
+    }
+    // The resolved inline form carries CSS text (a string); input forms only carry
+    // a boolean `inline` flag, so the string check identifies an inlined stylesheet.
+    if (typeof stylesheet.inline === "string") {
+        return JSON.stringify({ inline: stylesheet.inline });
+    }
+    return "source" in stylesheet
+        ? JSON.stringify({
+            href: stylesheet.href,
+            source: stylesheet.source,
+            immutable: stylesheet.immutable !== false,
+            inline: stylesheet.inline === true,
+        })
+        : JSON.stringify({
+            href: stylesheet.href,
+            googleFonts: {
+                families: stylesheet.googleFonts.families,
+                text: stylesheet.googleFonts.text,
+                display: stylesheet.googleFonts.display,
+                endpoint: stylesheet.googleFonts.endpoint,
+                fontBasePath: stylesheet.googleFonts.fontBasePath,
+                userAgent: stylesheet.googleFonts.userAgent,
+                preload: stylesheet.googleFonts.preload ?? false,
+            },
+            immutable: stylesheet.immutable !== false,
+            inline: stylesheet.inline === true,
+        });
 }
 function stableScriptKey(script) {
     return JSON.stringify({

package/dist/cli.d.ts CHANGED Viewed

@@ -48,6 +48,7 @@ export type CliCommand = {
     outDir: string;
     provider: DeployProvider;
     cname?: string;
+    trailingSlash?: BuildConfig["trailingSlash"];
 } | {
     command: "dev";
     outDir: string;

package/dist/cli.js CHANGED Viewed

@@ -97,7 +97,7 @@ export function parseArgs(args) {
             outDir = readValue(option, remaining);
             continue;
         }
-        if (command === "benchmark" && option === "--trailing-slash") {
+        if ((command === "benchmark" || command === "deploy") && option === "--trailing-slash") {
             trailingSlash = readTrailingSlash(option, remaining);
             continue;
         }
@@ -297,11 +297,15 @@ export function parseArgs(args) {
         if (cname !== undefined && provider !== "github-pages") {
             throw new Error("--cname is only supported with --provider github-pages");
         }
+        if (trailingSlash !== undefined && provider !== "s3") {
+            throw new Error("--trailing-slash is only supported with --provider s3");
+        }
         return {
             command,
             outDir,
             provider,
             ...(cname !== undefined ? { cname } : {}),
+            ...(trailingSlash === undefined ? {} : { trailingSlash }),
         };
     }
     if (command === "dev") {
@@ -512,6 +516,7 @@ export async function runCli(args = process.argv.slice(2)) {
             outDir: command.outDir,
             provider: command.provider,
             ...(command.cname !== undefined ? { cname: command.cname } : {}),
+            ...(command.trailingSlash !== undefined ? { trailingSlash: command.trailingSlash } : {}),
         });
         console.log("StoneAge deploy artifacts complete");
         console.log(`Provider: ${result.provider}`);
@@ -519,6 +524,11 @@ export async function runCli(args = process.argv.slice(2)) {
         if (result.provider === "github-pages") {
             console.log(`Artifacts: ${result.files.length > 0 ? result.files.join(", ") : "none"}`);
         }
+        else if (result.provider === "s3") {
+            console.log(`Artifacts: ${result.files.join(", ")}`);
+            console.log(`Redirects: ${result.redirects}`);
+            console.log(`Rules: ${result.headers}`);
+        }
         else {
             console.log(`Redirects: ${result.redirects}`);
             console.log(`Headers: ${result.headers}`);
@@ -760,8 +770,11 @@ async function readValidationOptionsConfig(path) {
         throw new Error(`Validation config requirePrecompressed must be a boolean: ${path}`);
     }
     const provider = value.provider;
-    if (provider !== undefined && provider !== "netlify" && provider !== "github-pages") {
-        throw new Error(`Validation config provider must be netlify or github-pages: ${path}`);
+    if (provider !== undefined &&
+        provider !== "netlify" &&
+        provider !== "github-pages" &&
+        provider !== "s3") {
+        throw new Error(`Validation config provider must be netlify, github-pages, or s3: ${path}`);
     }
     return {
         configHash: createHash("sha256").update(raw).digest("hex"),
@@ -987,7 +1000,7 @@ export async function validateOutput(outDir, options = {}) {
     const publicDataExportTargets = await collectPublicDataExportTargets(outDir, manifest);
     const publicDataExportIssues = await validatePublicDataExports(outDir, publicDataExportTargets);
     const headersManifestIssues = manifest
-        ? await validateHeadersManifest(outDir, manifest, report.publicAssets ?? [])
+        ? await validateHeadersManifest(outDir, manifest, report.publicAssets ?? [], report.publishingHeaders ?? [])
         : [];
     const redirectManifestIssues = manifest ? await validateRedirectManifest(outDir, manifest) : [];
     const robotsTxtIssues = await validateRobotsTxt(outDir);
@@ -1397,7 +1410,7 @@ async function validateOrphanHtmlOutputs(outDir, manifest) {
         message: `${file} is an HTML file in the public output directory but is not listed in the manifest.`,
     }));
 }
-async function validateHeadersManifest(outDir, manifest, publicAssets = []) {
+async function validateHeadersManifest(outDir, manifest, publicAssets = [], globalHeaders = []) {
     const raw = await readOptionalText(join(outDir, "headers.json"));
     if (!raw) {
         return [];
@@ -1426,6 +1439,12 @@ async function validateHeadersManifest(outDir, manifest, publicAssets = []) {
     }
     const issues = [];
     const expected = expectedHeadersManifestEntries(manifest);
+    // Host-wide `/*` rules (HTML Cache-Control / security headers) are not tied to
+    // a file artifact; the build persists them in the report so they count as
+    // expected entries here instead of tripping the "unexpected path" check.
+    for (const entry of globalHeaders) {
+        expected.set(entry.path, entry.headers);
+    }
     const managedPublicAssets = new Set(publicAssets);
     const actual = new Map();
     const duplicatePaths = new Set();
@@ -1656,9 +1675,10 @@ function isGeneratedSitemapFile(path) {
     return path === "sitemap.xml" || /^sitemap-\d+\.xml$/.test(path);
 }
 async function validateDeployArtifacts(outDir, provider = "netlify") {
-    // GitHub Pages relies on redirect HTML stubs and CNAME, not Netlify
-    // _redirects/_headers, so skip the Netlify-specific artifact checks.
-    if (provider === "github-pages") {
+    // GitHub Pages relies on redirect HTML stubs and CNAME, and S3 ships a
+    // descriptor plus CloudFront Function rather than Netlify _redirects/_headers,
+    // so skip the Netlify-specific artifact checks for both.
+    if (provider === "github-pages" || provider === "s3") {
         return [];
     }
     const issues = [];
@@ -2921,8 +2941,8 @@ function readTrailingSlash(option, args) {
 }
 function readDeployProvider(option, args) {
     const value = readValue(option, args);
-    if (value !== "netlify" && value !== "github-pages") {
-        throw new Error(`Expected netlify or github-pages for ${option}`);
+    if (value !== "netlify" && value !== "github-pages" && value !== "s3") {
+        throw new Error(`Expected netlify, github-pages, or s3 for ${option}`);
     }
     return value;
 }
@@ -2971,7 +2991,7 @@ function helpText() {
         "  --validation-config <file>             Load metadata, budget, and publish gate settings",
         "  --write-validation-config <file>       Write a validation baseline from current output",
         "  --require-precompressed                Fail when Brotli or Gzip sidecars are missing",
-        "  --provider <netlify|github-pages>      Validate deploy artifacts for the given provider",
+        "  --provider <netlify|github-pages|s3>   Validate deploy artifacts for the given provider",
         "  --report <file>                        Write the validation summary JSON",
         "",
         "SvelteKit audit options:",
@@ -2988,8 +3008,10 @@ function helpText() {
         "                                         Requires the optional 'sharp' dependency (npm install sharp)",
         "",
         "Deploy options:",
-        "  --provider <netlify|github-pages>      Write provider-specific deploy artifacts",
+        "  --provider <netlify|github-pages|s3>   Write provider-specific deploy artifacts",
         "  --cname <domain>                       Custom domain for github-pages (writes CNAME)",
+        "  --trailing-slash <always|never>        URL style for the s3 CloudFront Function (default always)",
+        "                                         s3 emits s3-deploy.json + cloudfront-function.js",
         "",
         "Dev options:",
         "  --host <host>                          Hostname to bind, default 127.0.0.1",

package/dist/core.d.ts CHANGED Viewed

@@ -114,6 +114,46 @@ export type PublishingConfig = {
      */
     nativeRedirects?: "netlify" | false;
     headers?: boolean;
+    /**
+     * When `false`, the build-intermediate publishing manifests (`headers.json`
+     * and `redirects.json`) are removed from the output directory after the
+     * host-native artifacts (`_headers` / `_redirects`) have been written, so the
+     * large JSON forms are not served. Intended for use together with
+     * `nativeRedirects`, since the standalone `deploy` command reads those
+     * manifests. Defaults to `true`, preserving the existing behaviour of leaving
+     * the manifests in the output.
+     */
+    publishManifests?: boolean;
+    /**
+     * `Cache-Control` applied to generated HTML documents via a `/*` rule in
+     * `_headers` / `headers.json`. Content-hashed assets keep their own
+     * `immutable` rule because their more specific paths take precedence. Off by
+     * default; set e.g. `"public, max-age=0, must-revalidate"` to opt in.
+     */
+    htmlCacheControl?: string;
+    /**
+     * Opt-in security response headers emitted as a `/*` rule in `_headers` /
+     * `headers.json`. Nothing is emitted unless this is set.
+     */
+    securityHeaders?: SecurityHeadersConfig;
+};
+export type SecurityHeadersConfig = {
+    /** Path the headers apply to. Defaults to `/*`. */
+    path?: string;
+    /**
+     * `Strict-Transport-Security`. `true` emits a sensible default
+     * (`max-age=63072000; includeSubDomains; preload`); a string sets a custom
+     * value. HTTPS-only, so off unless explicitly enabled.
+     */
+    hsts?: boolean | string;
+    /** `X-Content-Type-Options: nosniff` when `true`. */
+    contentTypeOptions?: boolean;
+    /** `X-Frame-Options`. `true` emits `DENY`; a string sets a custom value. */
+    frameOptions?: boolean | string;
+    /** `Referrer-Policy` value, emitted verbatim when set. */
+    referrerPolicy?: string;
+    /** Additional headers merged verbatim (names are lower-cased). */
+    extra?: Record<string, string>;
 };
 export type SitemapConfig = {
     maxUrlsPerFile?: number;
@@ -156,6 +196,10 @@ export type RouteFamily = {
 };
 export type ArtifactBody = string | Buffer | Uint8Array;
 export type ArtifactHeaders = Record<string, string>;
+export type PublishingHeaderEntry = {
+    path: string;
+    headers: ArtifactHeaders;
+};
 export type ArtifactResponse = {
     body: ArtifactBody;
     contentType?: string;
@@ -259,6 +303,29 @@ export type BuildConfig = {
     assets?: {
         stylesheets?: ClientStylesheetAsset[];
         client?: ClientAssetRegistry;
+        /**
+         * Inline every generated stylesheet's CSS into each document `<head>` as a
+         * `<style>` element instead of emitting render-blocking
+         * `<link rel="stylesheet">`s. Applies to both `assets.stylesheets` and the
+         * stylesheets resolved from per-page `assets.client` registries (inlining a
+         * client stylesheet turns it into a `<style>` on the pages that use it). A
+         * per-stylesheet `inline` flag always wins: `inline: false` opts a sheet out
+         * even when this is true, and `inline: true` opts one in. When
+         * {@link inlineStylesheetMaxBytes} is also set, the byte threshold gates this:
+         * a bundle larger than the threshold stays external even with this enabled.
+         * Defaults to the existing external-link behavior. Inlined CSS is subject to
+         * the page's CSP `style-src`; see {@link InlineStylesheetAsset} for the caveat.
+         */
+        inlineStylesheets?: boolean;
+        /**
+         * Auto-inline a generated stylesheet only when its built CSS is at most this
+         * many bytes (UTF-8), measured after Google Fonts CSS resolution. Lets small,
+         * critical bundles inline while larger ones stay external. A per-stylesheet
+         * `inline` flag still wins over this gate. When {@link inlineStylesheets} is
+         * also true, this acts as the gate: bundles over the threshold are not
+         * inlined. A non-positive or non-finite value inlines nothing.
+         */
+        inlineStylesheetMaxBytes?: number;
         public?: PublicAssetInput[];
         /**
          * Directory whose tree is copied verbatim onto the output root. Each file
@@ -371,6 +438,12 @@ export type BuildReport = {
         bytes: number;
     }>;
     validation: BuildValidationReport;
+    /**
+     * Host-wide `/*` header rules (HTML `Cache-Control` / security headers) that
+     * are emitted to `headers.json` / `_headers` but are not tied to a file
+     * artifact. Persisted so `validate` can treat them as expected entries.
+     */
+    publishingHeaders?: PublishingHeaderEntry[];
 };
 export type DataFlowFamilySummary = {
     name: string;

package/dist/core.js CHANGED Viewed

@@ -497,16 +497,108 @@ function fragmentClientArtifact(publicPath) {
     };
 }
 const immutableStaticAssetCacheControl = "public, max-age=31536000, immutable";
+// Content-hashed filenames (e.g. `site.<16 hex>.css`) plus the StoneAge-managed
+// `/_assets/` and `/_stoneage/` namespaces are immutable: their bytes never
+// change for a given path, so they can carry a long-lived `immutable` rule.
+const contentHashedAssetPathPattern = /\.[0-9a-f]{16,}\.[A-Za-z0-9]+$/;
+function isImmutableAssetPath(path) {
+    return (path.startsWith("/_assets/") ||
+        path.startsWith("/_stoneage/") ||
+        contentHashedAssetPathPattern.test(path));
+}
+function hasHeaderNamed(headers, name) {
+    if (!headers) {
+        return false;
+    }
+    const lower = name.toLowerCase();
+    return Object.keys(headers).some((key) => key.toLowerCase() === lower);
+}
+// Adds the immutable `Cache-Control` to content-hashed / `_assets` / `_stoneage`
+// artifacts that do not already declare one (e.g. the fragment client at
+// `/_stoneage/*`). Mutates `artifacts` so the headers persist in the manifest,
+// keeping `validate` consistent because it reconstructs expectations from the
+// same manifest.
+function applyImmutableAssetHeaders(artifacts) {
+    for (const artifact of artifacts) {
+        if (!isImmutableAssetPath(artifact.path)) {
+            continue;
+        }
+        if (hasHeaderNamed(artifact.headers, "cache-control")) {
+            continue;
+        }
+        artifact.headers = {
+            ...(artifact.headers ?? {}),
+            "cache-control": immutableStaticAssetCacheControl,
+        };
+    }
+}
+const defaultHstsValue = "max-age=63072000; includeSubDomains; preload";
+// Resolves the host-wide `/*` header rule(s) (HTML `Cache-Control` and security
+// headers). These are not tied to a file artifact, so they are persisted in the
+// build report and re-applied by `validate` from there.
+function resolveGlobalPublishingHeaders(publishing) {
+    if (publishing.headers === false) {
+        return [];
+    }
+    const headersByPath = new Map();
+    const headersFor = (path) => {
+        const existing = headersByPath.get(path);
+        if (existing) {
+            return existing;
+        }
+        const created = {};
+        headersByPath.set(path, created);
+        return created;
+    };
+    if (publishing.htmlCacheControl !== undefined) {
+        headersFor("/*")["cache-control"] = publishing.htmlCacheControl;
+    }
+    const security = publishing.securityHeaders;
+    if (security) {
+        const target = headersFor(security.path ?? "/*");
+        if (security.hsts) {
+            target["strict-transport-security"] =
+                security.hsts === true ? defaultHstsValue : security.hsts;
+        }
+        if (security.contentTypeOptions) {
+            target["x-content-type-options"] = "nosniff";
+        }
+        if (security.frameOptions) {
+            target["x-frame-options"] =
+                security.frameOptions === true ? "DENY" : security.frameOptions;
+        }
+        if (security.referrerPolicy) {
+            target["referrer-policy"] = security.referrerPolicy;
+        }
+        for (const [name, value] of Object.entries(security.extra ?? {})) {
+            target[name.toLowerCase()] = value;
+        }
+    }
+    return [...headersByPath.entries()]
+        .filter(([, headers]) => Object.keys(headers).length > 0)
+        .map(([path, headers]) => ({ path, headers }));
+}
 async function resolveStaticAssetReferences(assets) {
     if (!assets) {
         return {
             assets,
             publicAssets: [],
             headers: [],
+            fontPreloads: [],
         };
     }
     const publicAssetsByPath = new Map();
     const headersByPath = new Map();
+    const fontPreloads = [];
+    const seenFontPreloads = new Set();
+    const collectFontPreloads = (paths) => {
+        for (const path of paths) {
+            if (!seenFontPreloads.has(path)) {
+                seenFontPreloads.add(path);
+                fontPreloads.push(path);
+            }
+        }
+    };
     const resolveImmutablePublicAsset = async (asset, publicPath) => {
         const bytes = await immutableAssetBytes(asset);
         const hashedPath = contentHashedPublicPath(publicPath, contentHash(bytes));
@@ -525,9 +617,18 @@ async function resolveStaticAssetReferences(assets) {
         }
         return hashedPath;
     };
-    const stylesheets = await Promise.all((assets.stylesheets ?? []).map(async (stylesheet) => resolveStylesheetAsset(stylesheet, resolveImmutablePublicAsset)));
+    // Global auto-inline policy, applied to any stylesheet that does not set its
+    // own `inline` flag. Threaded through both top-level and per-page client
+    // stylesheet resolution so the behavior is consistent everywhere.
+    const inlinePolicy = {
+        inlineStylesheets: assets.inlineStylesheets,
+        inlineStylesheetMaxBytes: assets.inlineStylesheetMaxBytes,
+    };
+    const stylesheets = await Promise.all((assets.stylesheets ?? []).map(async (stylesheet) => resolveStylesheetAsset(stylesheet, resolveImmutablePublicAsset, collectFontPreloads, inlinePolicy)));
+    // Per-page client stylesheets are resolved without a preload collector: a
+    // page-scoped font must not become a global preload hint on every page.
     const client = assets.client
-        ? await resolveClientAssetRegistry(assets.client, resolveImmutablePublicAsset)
+        ? await resolveClientAssetRegistry(assets.client, resolveImmutablePublicAsset, inlinePolicy)
         : undefined;
     return {
         assets: {
@@ -537,24 +638,125 @@ async function resolveStaticAssetReferences(assets) {
         },
         publicAssets: [...publicAssetsByPath.values()],
         headers: [...headersByPath.values()],
+        fontPreloads,
     };
 }
-async function resolveStylesheetAsset(stylesheet, resolveImmutablePublicAsset) {
-    if (typeof stylesheet === "string" || stylesheet.immutable === false) {
+// Decide whether a stylesheet's built CSS should be inlined. A per-stylesheet
+// `inline` flag always wins; otherwise the global policy applies, with
+// `inlineStylesheetMaxBytes` acting as a byte-size gate over `inlineStylesheets`.
+function shouldInlineStylesheet(explicitInline, css, policy) {
+    if (explicitInline !== undefined) {
+        return explicitInline;
+    }
+    if (!policy) {
+        return false;
+    }
+    const { inlineStylesheets, inlineStylesheetMaxBytes } = policy;
+    if (inlineStylesheetMaxBytes !== undefined) {
+        // The threshold gates inlining (even when `inlineStylesheets` is true): a
+        // non-positive/non-finite limit inlines nothing, otherwise the built CSS
+        // must fit within it.
+        if (!Number.isFinite(inlineStylesheetMaxBytes) || inlineStylesheetMaxBytes <= 0) {
+            return false;
+        }
+        return Buffer.byteLength(css, "utf8") <= inlineStylesheetMaxBytes;
+    }
+    return inlineStylesheets === true;
+}
+// Whether a global policy could ever inline an `inline`-unspecified stylesheet.
+// Lets the resolver skip reading a source file (and keep the byte-identical
+// external path) when inlining is impossible regardless of CSS size.
+function policyMightInline(policy) {
+    if (!policy) {
+        return false;
+    }
+    const { inlineStylesheets, inlineStylesheetMaxBytes } = policy;
+    if (inlineStylesheetMaxBytes !== undefined) {
+        return Number.isFinite(inlineStylesheetMaxBytes) && inlineStylesheetMaxBytes > 0;
+    }
+    return inlineStylesheets === true;
+}
+async function resolveStylesheetAsset(stylesheet, resolveImmutablePublicAsset, onFontPreload, inlinePolicy) {
+    // Plain href strings and already-inlined CSS pass through untouched.
+    if (typeof stylesheet === "string" || isResolvedInlineStylesheet(stylesheet)) {
         return stylesheet;
     }
+    const explicitInline = stylesheet.inline;
     if ("source" in stylesheet) {
-        return resolveImmutablePublicAsset({ source: stylesheet.source }, stylesheet.href);
+        // `immutable: false` is a deliberate "serve this href as-is" opt-out, so the
+        // global inline policy does not touch it; only an explicit `inline: true`
+        // can still inline such a sheet.
+        if (explicitInline !== true && stylesheet.immutable === false) {
+            return stripStylesheetBuildHints(stylesheet);
+        }
+        // When inlining is impossible (explicit opt-out, or no policy that could
+        // inline an unspecified sheet), keep the original source-backed external
+        // path so its hashed output stays byte-identical to before.
+        if (explicitInline === false || (explicitInline === undefined && !policyMightInline(inlinePolicy))) {
+            return resolveImmutablePublicAsset({ source: stylesheet.source }, stylesheet.href);
+        }
+        // Read the CSS once and reuse it for both the size check and inlining so the
+        // file is never read twice.
+        const css = await readFile(stylesheet.source, "utf8");
+        if (shouldInlineStylesheet(explicitInline, css, inlinePolicy)) {
+            // Embed the CSS directly: no hashed public file and no `_headers` entry.
+            return { inline: css };
+        }
+        return resolveImmutablePublicAsset({ content: css }, stylesheet.href);
+    }
+    // Google Fonts: an `immutable: false` reference is not vendored (legacy
+    // behavior), so there are no woff2 to preload or CSS to inline. As above, the
+    // global policy leaves this opt-out alone unless `inline: true` is explicit.
+    if (explicitInline !== true && stylesheet.immutable === false) {
+        return stripStylesheetBuildHints(stylesheet);
+    }
+    const { css, fontPaths } = await resolveGoogleFontsStylesheet(stylesheet.href, stylesheet.googleFonts, resolveImmutablePublicAsset);
+    if (onFontPreload) {
+        const selected = selectFontPreloads(fontPaths, stylesheet.googleFonts.preload);
+        if (selected.length > 0) {
+            onFontPreload(selected);
+        }
+    }
+    // The woff2 files are always vendored above; only the CSS is inlined.
+    return shouldInlineStylesheet(explicitInline, css, inlinePolicy)
+        ? { inline: css }
+        : resolveImmutablePublicAsset({ content: css }, stylesheet.href);
+}
+function isResolvedInlineStylesheet(stylesheet) {
+    // The resolved inline form carries the CSS text as a string; the input forms
+    // only ever carry a boolean `inline` flag, so the string check disambiguates.
+    return typeof stylesheet === "object" && typeof stylesheet.inline === "string";
+}
+// Drop the build-time `inline` flag from a non-vendored stylesheet so the
+// rendered form is a clean external reference and never carries a stray boolean
+// `inline` that the renderer might mistake for inlined CSS.
+function stripStylesheetBuildHints(stylesheet) {
+    const { inline: _inline, ...rest } = stylesheet;
+    return rest;
+}
+function selectFontPreloads(fontPaths, preload) {
+    if (preload === undefined || preload === false) {
+        return [];
+    }
+    if (preload === true) {
+        return fontPaths;
     }
-    return resolveGoogleFontsStylesheet(stylesheet.href, stylesheet.googleFonts, resolveImmutablePublicAsset);
+    if (!Number.isFinite(preload) || preload <= 0) {
+        return [];
+    }
+    return fontPaths.slice(0, Math.floor(preload));
 }
-async function resolveClientAssetRegistry(registry, resolveImmutablePublicAsset) {
+async function resolveClientAssetRegistry(registry, resolveImmutablePublicAsset, inlinePolicy) {
     const entries = await Promise.all(Object.entries(registry).map(async ([id, declarations]) => [
         id,
         await Promise.all((Array.isArray(declarations) ? declarations : [declarations]).map(async (declaration) => ({
             ...(declaration.stylesheets
                 ? {
-                    stylesheets: await Promise.all(declaration.stylesheets.map((stylesheet) => resolveStylesheetAsset(stylesheet, resolveImmutablePublicAsset))),
+                    stylesheets: await Promise.all(declaration.stylesheets.map((stylesheet) =>
+                    // No preload collector here: a page-scoped client font must
+                    // not become a global hint. The global inline policy still
+                    // applies so client CSS inlines consistently.
+                    resolveStylesheetAsset(stylesheet, resolveImmutablePublicAsset, undefined, inlinePolicy))),
                 }
                 : {}),
             ...(declaration.scripts
@@ -584,6 +786,12 @@ async function immutableAssetBytes(asset) {
 const defaultGoogleFontsCssEndpoint = "https://fonts.googleapis.com/css2";
 const defaultGoogleFontsUserAgent = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 " +
     "(KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36";
+/**
+ * Vendor the Google Fonts subset (CSS + woff2) and return the rewritten CSS
+ * together with the hashed woff2 public paths in CSS source order. The caller
+ * decides whether to write the CSS as a hashed file or inline it, and which
+ * fonts to preload.
+ */
 async function resolveGoogleFontsStylesheet(href, options, resolveImmutablePublicAsset) {
     const fetchAsset = options.fetch ?? defaultAssetFetch;
     const requestHeaders = {
@@ -610,7 +818,7 @@ async function resolveGoogleFontsStylesheet(href, options, resolveImmutablePubli
         fontPathsByUrl.set(font.url, await resolveImmutablePublicAsset({ content: bytes }, fontPublicPath));
     }
     const rewrittenCss = rewriteCssUrls(css, fontPathsByUrl);
-    return resolveImmutablePublicAsset({ content: rewrittenCss }, href);
+    return { css: rewrittenCss, fontPaths: [...fontPathsByUrl.values()] };
 }
 const defaultAssetFetch = async (url, init) => {
     return fetch(url, init);
@@ -836,9 +1044,17 @@ export async function buildSite(config) {
         };
     });
     validateOutputPlan(plannedPages, plannedArtifacts, config.notFound !== undefined);
+    const fontPreloads = staticAssets.fontPreloads;
     const sharedPageFingerprintHash = hashValue({
         site: config.site,
         stylesheets: assets?.stylesheets ?? [],
+        // The global inline policy can flip a stylesheet between external and
+        // inlined; including the options invalidates every page when the policy
+        // changes, even for pages whose CSS lives only in `assets.client` (whose
+        // resolved forms are not part of this shared hash).
+        inlineStylesheets: assets?.inlineStylesheets ?? false,
+        inlineStylesheetMaxBytes: assets?.inlineStylesheetMaxBytes ?? null,
+        fontPreloads,
         prefetch: config.prefetch ?? {},
         trailingSlash,
         renderFingerprint: config.renderFingerprint,
@@ -866,7 +1082,7 @@ export async function buildSite(config) {
             };
         }
         const body = await withDeferredFragmentDefaults({ defaultFallbackText: fragmentDefaultFallbackText }, () => task.entry.render());
-        const html = renderDocument(config.site, task.metadata, canonical, body, assets, config.prefetch, trailingSlash, fragmentClientScripts);
+        const html = renderDocument(config.site, task.metadata, canonical, body, assets, config.prefetch, trailingSlash, fragmentClientScripts, fontPreloads);
         await writeText(absoluteOutputPath, html, {
             compareExisting: compareExistingGeneratedOutput,
         });
@@ -936,7 +1152,7 @@ export async function buildSite(config) {
     });
     const notFoundResults = config.notFound
         ? [
-            await buildNotFoundPage(config, config.notFound, trailingSlash, previousPages, sharedPageFingerprintHash, compareExistingGeneratedOutput, fragmentDefaultFallbackText, fragmentClientScripts, assets),
+            await buildNotFoundPage(config, config.notFound, trailingSlash, previousPages, sharedPageFingerprintHash, compareExistingGeneratedOutput, fragmentDefaultFallbackText, fragmentClientScripts, assets, fontPreloads),
         ]
         : [];
     const allPageResults = [...pageResults, ...notFoundResults];
@@ -1043,6 +1259,16 @@ export async function buildSite(config) {
         pages,
         artifacts,
     };
+    // Bake the immutable `Cache-Control` into content-hashed / `_assets` /
+    // `_stoneage` artifacts before the manifest is compared, persisted, and
+    // published, so `headers.json`, `_headers`, and `validate` all stay in sync.
+    const publishesHeaders = config.publishing !== undefined && config.publishing.headers !== false;
+    if (publishesHeaders) {
+        applyImmutableAssetHeaders(manifest.artifacts);
+    }
+    const globalPublishingHeaders = config.publishing !== undefined
+        ? resolveGlobalPublishingHeaders(config.publishing)
+        : [];
     const staleOutputsRemoved = config.partial
         ? 0
         : (await removeStaleGeneratedOutputs(config.outDir, previousManifest, manifest)) +
@@ -1072,6 +1298,14 @@ export async function buildSite(config) {
             artifactWrites,
         })
         : createReport(manifest, pagesWritten, artifactsWritten, publicAssetsCopied, publicAssetsSkipped, publicAssets, staleOutputsRemoved, sitemapRendered, sitemapFiles, routeWrites, artifactWrites, allPageResults.map((result) => result.validationPage), config.validation, config.buildFingerprint, config.renderFingerprint, fragmentDefaultFallbackText, fragmentClientPublicPath);
+    // Persist the host-wide `/*` header rules so `validate` can reconstruct them
+    // (they are not tied to a file artifact). Always set the fresh value, even on
+    // the report-reuse path, and force a report rewrite when it changes so the
+    // persisted report never lags the regenerated `headers.json`.
+    report.publishingHeaders =
+        globalPublishingHeaders.length > 0 ? globalPublishingHeaders : undefined;
+    const publishingHeadersChanged = stableJson(previousReport?.publishingHeaders ?? []) !==
+        stableJson(globalPublishingHeaders);
     const missingPreviousManifest = previousManifest.pages.length === 0 && previousManifest.artifacts.length === 0;
     const missingBuildReport = previousReport === undefined;
     const dataFlowSummaryReportPath = join(config.outDir, ".stoneage/data-flow-summary.json");
@@ -1087,6 +1321,7 @@ export async function buildSite(config) {
         staleOutputsRemoved > 0 ||
         missingPreviousManifest ||
         missingBuildReport ||
+        publishingHeadersChanged ||
         shouldWriteSitemaps;
     const validationReportChanged = !shouldWriteBuildReportsWithoutComparisons &&
         !canReusePreviousReport &&
@@ -1131,7 +1366,7 @@ export async function buildSite(config) {
         await rm(legacyDataFlowReportPath, { force: true });
     }
     if (config.publishing) {
-        await writePublishingManifests(config.outDir, config.publishing, config.site.baseUrl, trailingSlash, manifest, redirectHtmlFiles, staticAssets.headers);
+        await writePublishingManifests(config.outDir, config.publishing, config.site.baseUrl, trailingSlash, manifest, redirectHtmlFiles, staticAssets.headers, globalPublishingHeaders);
     }
     return {
         pagesWritten,
@@ -1142,7 +1377,7 @@ export async function buildSite(config) {
         report,
     };
 }
-async function buildNotFoundPage(config, notFound, trailingSlash, previousPages, sharedPageFingerprintHash, compareExistingGeneratedOutput, fragmentDefaultFallbackText, fragmentClientScripts, assets) {
+async function buildNotFoundPage(config, notFound, trailingSlash, previousPages, sharedPageFingerprintHash, compareExistingGeneratedOutput, fragmentDefaultFallbackText, fragmentClientScripts, assets, fontPreloads) {
     const metadata = {
         ...resolvePageMetadata(undefined, undefined, notFound.metadata),
         // A 404 page must never be indexed or advertised in the sitemap.
@@ -1168,7 +1403,7 @@ async function buildNotFoundPage(config, notFound, trailingSlash, previousPages,
         };
     }
     const body = await withDeferredFragmentDefaults({ defaultFallbackText: fragmentDefaultFallbackText }, () => notFound.render());
-    const html = renderDocument(config.site, metadata, canonical, body, assets, config.prefetch, trailingSlash, fragmentClientScripts);
+    const html = renderDocument(config.site, metadata, canonical, body, assets, config.prefetch, trailingSlash, fragmentClientScripts, fontPreloads);
     await writeText(absoluteOutputPath, html, {
         compareExisting: compareExistingGeneratedOutput,
     });
@@ -1843,7 +2078,7 @@ function sameDependencies(left, right) {
     }
     return leftCount === rightCount;
 }
-function renderDocument(site, metadata, canonical, body, assets, prefetch, trailingSlash = "always", extraClientScripts = []) {
+function renderDocument(site, metadata, canonical, body, assets, prefetch, trailingSlash = "always", extraClientScripts = [], fontPreloads = []) {
     const title = renderTitle(metadata.title, site);
     const description = metadata.description || site.description;
     const ogTitle = metadata.ogTitle ?? metadata.title;
@@ -1884,9 +2119,16 @@ function renderDocument(site, metadata, canonical, body, assets, prefetch, trail
     const twitterMeta = renderTwitterMetadata(site.twitter, metadata.twitter);
     const customHead = [...(site.head ?? []), ...(metadata.head ?? [])].map(renderHeadTag).join("");
     const pageClientAssets = resolvePageClientAssets(assets, metadata);
+    // Preload hints go before the stylesheet links so fonts leave the critical
+    // request chain (HTML → CSS → woff2).
+    const fontPreloadLinks = fontPreloads
+        .map((href) => `<link rel="preload" href="${escapeAttribute(href)}" as="font" type="font/woff2" crossorigin>`)
+        .join("");
     const stylesheetLinks = (assets?.stylesheets ?? [])
         .concat(pageClientAssets.stylesheets)
-        .map((stylesheet) => `<link rel="stylesheet" href="${escapeAttribute(stylesheetHref(stylesheet))}">`)
+        .map((stylesheet) => isResolvedInlineStylesheet(stylesheet)
+        ? `<style>${escapeInlineStyleContent(stylesheet.inline)}</style>`
+        : `<link rel="stylesheet" href="${escapeAttribute(stylesheetHref(stylesheet))}">`)
         .join("");
     const clientScripts = renderClientScripts([
         ...extraClientScripts,
@@ -1901,7 +2143,7 @@ function renderDocument(site, metadata, canonical, body, assets, prefetch, trail
     const serviceWorkerPrefetch = prefetch?.serviceWorker
         ? renderServiceWorkerPrefetch(prefetchUrls, prefetch)
         : "";
-    return `<!doctype html><html lang="${escapeAttribute(site.lang ?? "en")}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${escapeHtml(title)}</title><meta name="description" content="${escapeAttribute(description)}"><link rel="canonical" href="${escapeAttribute(canonical)}">${robots}${favicon}${ogTitleMeta}${ogDescriptionMeta}${ogUrl}${ogSiteName}${ogType}${ogImage}${ogImageWidthMeta}${ogImageHeightMeta}${twitterMeta}${customHead}${stylesheetLinks}${clientScripts}${prefetchLinks}${serviceWorkerPrefetch}<body>${body}`;
+    return `<!doctype html><html lang="${escapeAttribute(site.lang ?? "en")}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${escapeHtml(title)}</title><meta name="description" content="${escapeAttribute(description)}"><link rel="canonical" href="${escapeAttribute(canonical)}">${robots}${favicon}${ogTitleMeta}${ogDescriptionMeta}${ogUrl}${ogSiteName}${ogType}${ogImage}${ogImageWidthMeta}${ogImageHeightMeta}${twitterMeta}${customHead}${fontPreloadLinks}${stylesheetLinks}${clientScripts}${prefetchLinks}${serviceWorkerPrefetch}<body>${body}`;
 }
 function renderTitle(pageTitle, site) {
     return site.titleTemplate
@@ -1953,7 +2195,20 @@ function resolvePageClientAssets(assets, metadata) {
     return resolveClientAssets(assets?.client ?? {}, ids);
 }
 function stylesheetHref(stylesheet) {
-    return typeof stylesheet === "string" ? stylesheet : stylesheet.href;
+    if (typeof stylesheet === "string") {
+        return stylesheet;
+    }
+    // Inlined stylesheets are rendered as <style> and never reach this helper.
+    return "href" in stylesheet ? stylesheet.href : "";
+}
+// The body of a <style> element is HTML "raw text": a literal `</style` token
+// (which can validly appear inside a CSS comment or a `content:` string) would
+// close the element early and corrupt the page. A backslash is a valid CSS
+// escape, so `<\/style` is byte-for-byte equivalent to `</style` in the only
+// places it can legitimately occur, while no longer matching the raw-text end
+// token the HTML parser scans for.
+function escapeInlineStyleContent(css) {
+    return css.replace(/<\/(style)/gi, "<\\/$1");
 }
 function renderClientScripts(scripts) {
     return scripts.map((script) => `<script${renderScriptAttributes(script)}></script>`).join("");
@@ -2005,7 +2260,7 @@ function renderPrefetchScript(workerPath) {
 function renderPrefetchWorker(cacheName) {
     return `const CACHE_NAME="${escapeJavaScriptString(cacheName)}";self.addEventListener("message",(event)=>{const data=event.data;if(!data||data.type!=="STONEAGE_PREFETCH"||!Array.isArray(data.urls))return;event.waitUntil(caches.open(CACHE_NAME).then((cache)=>Promise.all(data.urls.filter((url)=>typeof url==="string"&&url.startsWith("/")).map((url)=>cache.add(url).catch(()=>undefined)))));});`;
 }
-async function writePublishingManifests(outDir, publishing, baseUrl, trailingSlash, manifest, redirectHtmlFiles, staticAssetHeaders = []) {
+async function writePublishingManifests(outDir, publishing, baseUrl, trailingSlash, manifest, redirectHtmlFiles, staticAssetHeaders = [], globalHeaders = []) {
     const redirects = normalizePublishingRedirects(publishing.redirects ?? [], trailingSlash);
     if (publishing.robots !== undefined && publishing.robots !== false) {
         await writeText(join(outDir, "robots.txt"), renderRobotsTxt(publishing.robots, baseUrl, trailingSlash));
@@ -2023,12 +2278,23 @@ async function writePublishingManifests(outDir, publishing, baseUrl, trailingSla
         await rm(join(outDir, "headers.json"), { force: true });
     }
     else {
-        headers = await writeArtifactHeadersManifest(outDir, manifest, staticAssetHeaders);
+        headers = await writeArtifactHeadersManifest(outDir, manifest, staticAssetHeaders, globalHeaders);
     }
     await writeNativePublishingArtifacts(outDir, publishing, redirects, headers);
+    // SR-4: drop the build-intermediate manifests from the published output once
+    // the host-native artifacts have been written from the in-memory data above.
+    if (publishing.publishManifests === false) {
+        await Promise.all([
+            rm(join(outDir, "headers.json"), { force: true }),
+            rm(join(outDir, "redirects.json"), { force: true }),
+        ]);
+    }
 }
-async function writeArtifactHeadersManifest(outDir, manifest, staticAssetHeaders = []) {
+async function writeArtifactHeadersManifest(outDir, manifest, staticAssetHeaders = [], globalHeaders = []) {
     const headers = [
+        // Host-wide `/*` rules come first so more specific artifact / asset rules
+        // (e.g. immutable `Cache-Control`) take precedence in `_headers`.
+        ...globalHeaders,
         ...manifest.artifacts
             .map((artifact) => {
             const artifactHeaders = artifactPublishingHeaders(artifact);

package/dist/deploy.d.ts CHANGED Viewed

@@ -1,4 +1,4 @@
-export type DeployProvider = "netlify" | "github-pages";
+export type DeployProvider = "netlify" | "github-pages" | "s3";
 export type DeployArtifactsOptions = {
     outDir: string;
     provider: DeployProvider;
@@ -7,6 +7,14 @@ export type DeployArtifactsOptions = {
      * (protocol and path are stripped). Ignored by other providers.
      */
     cname?: string;
+    /**
+     * URL style the site was built with. Only the "s3" provider uses it, to
+     * emit a CloudFront Function that resolves pretty URLs to the matching
+     * object layout ("always" -> dir/index.html, "never" -> name.html).
+     * Defaults to "always" to match the build default. Ignored by other
+     * providers.
+     */
+    trailingSlash?: "always" | "never";
 };
 export type DeployArtifactsResult = {
     provider: DeployProvider;

package/dist/deploy.js CHANGED Viewed

@@ -4,6 +4,9 @@ export async function writeDeployArtifacts(options) {
     if (options.provider === "github-pages") {
         return writeGitHubPagesArtifacts(options);
     }
+    if (options.provider === "s3") {
+        return writeS3Artifacts(options);
+    }
     if (options.provider !== "netlify") {
         throw new Error(`Unsupported deploy provider: ${options.provider}`);
     }
@@ -49,6 +52,109 @@ async function writeGitHubPagesArtifacts(options) {
         headers: 0,
     };
 }
+// Default Cache-Control for files not matched by a header rule (e.g. HTML).
+// Mutable documents get a short revalidation window; hash-named immutable
+// assets carry their own long-lived rule from the headers manifest.
+const s3DefaultCacheControl = "public, max-age=300";
+// Map S3/CloudFront origin errors to the generated 404 page so pretty-URL
+// misses surface the site's own not-found document instead of an XML error.
+const s3ErrorResponses = [
+    { errorCode: 403, responseCode: 404, responsePath: "/404.html" },
+    { errorCode: 404, responseCode: 404, responsePath: "/404.html" },
+];
+// Viewer-request CloudFront Function source. It resolves directory-style and
+// extensionless requests to the object the build actually wrote, so pretty
+// URLs work without hand-written routing rules. The mapping depends on the
+// build's trailingSlash mode, so a source is emitted per mode. Both are
+// ES5-safe (no endsWith/slice) to stay within the CloudFront Functions
+// runtime. Written verbatim so callers can attach it to a distribution.
+//
+// "always": pages live at dir/index.html, so /dir/ and /dir both resolve to
+// /dir/index.html and / resolves to /index.html.
+const cloudFrontFunctionSourceAlways = [
+    "function handler(event) {",
+    "  var request = event.request;",
+    "  var uri = request.uri;",
+    '  var lastSegment = uri.substring(uri.lastIndexOf("/") + 1);',
+    '  if (lastSegment === "") {',
+    '    request.uri = uri + "index.html";',
+    '  } else if (lastSegment.indexOf(".") === -1) {',
+    '    request.uri = uri + "/index.html";',
+    "  }",
+    "  return request;",
+    "}",
+    "",
+].join("\n");
+// "never": pages live at name.html, so /about resolves to /about.html, a
+// trailing slash is dropped first, and the root still resolves to /index.html.
+const cloudFrontFunctionSourceNever = [
+    "function handler(event) {",
+    "  var request = event.request;",
+    "  var uri = request.uri;",
+    '  if (uri === "/") {',
+    '    request.uri = "/index.html";',
+    "    return request;",
+    "  }",
+    '  if (uri.charAt(uri.length - 1) === "/") {',
+    "    uri = uri.substring(0, uri.length - 1);",
+    "  }",
+    '  var lastSegment = uri.substring(uri.lastIndexOf("/") + 1);',
+    '  if (lastSegment.indexOf(".") === -1) {',
+    '    uri = uri + ".html";',
+    "  }",
+    "  request.uri = uri;",
+    "  return request;",
+    "}",
+    "",
+].join("\n");
+function cloudFrontFunctionSource(trailingSlash) {
+    return trailingSlash === "never"
+        ? cloudFrontFunctionSourceNever
+        : cloudFrontFunctionSourceAlways;
+}
+async function writeS3Artifacts(options) {
+    const redirects = await readRedirectsManifest(join(options.outDir, "redirects.json"));
+    const headers = await readHeadersManifest(join(options.outDir, "headers.json"));
+    const trailingSlash = options.trailingSlash ?? "always";
+    const rules = headers.headers.map(toS3Rule);
+    const descriptor = {
+        provider: "s3",
+        trailingSlash,
+        indexDocument: "index.html",
+        errorDocument: "404.html",
+        defaults: { cacheControl: s3DefaultCacheControl },
+        rules,
+        redirects: redirects.redirects,
+        errorResponses: s3ErrorResponses.map((entry) => ({ ...entry })),
+        cloudFrontFunction: "cloudfront-function.js",
+    };
+    await writeIfChanged(join(options.outDir, "s3-deploy.json"), `${JSON.stringify(descriptor, null, 2)}\n`);
+    await writeIfChanged(join(options.outDir, "cloudfront-function.js"), cloudFrontFunctionSource(trailingSlash));
+    return {
+        provider: options.provider,
+        files: ["s3-deploy.json", "cloudfront-function.js"],
+        redirects: redirects.redirects.length,
+        headers: rules.length,
+    };
+}
+function toS3Rule(entry) {
+    const contentType = findHeaderValue(entry.headers, "content-type");
+    const cacheControl = findHeaderValue(entry.headers, "cache-control");
+    return {
+        path: entry.path,
+        ...(contentType !== undefined ? { contentType } : {}),
+        ...(cacheControl !== undefined ? { cacheControl } : {}),
+    };
+}
+function findHeaderValue(headers, name) {
+    const target = name.toLowerCase();
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === target) {
+            return value;
+        }
+    }
+    return undefined;
+}
 export function normalizeCname(cname) {
     if (cname === undefined) {
         return undefined;

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@t09tanaka/stoneage",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "A data-site static site generator for fast plain HTML output.",
   "keywords": [