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

@t09tanaka/stoneage 0.2.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 (5) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,13 @@
 # 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

package/README.md CHANGED Viewed

@@ -270,6 +270,36 @@ 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 })`.

package/dist/core.d.ts CHANGED Viewed

@@ -303,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

package/dist/core.js CHANGED Viewed

@@ -617,11 +617,18 @@ async function resolveStaticAssetReferences(assets) {
         }
         return hashedPath;
     };
-    const stylesheets = await Promise.all((assets.stylesheets ?? []).map(async (stylesheet) => resolveStylesheetAsset(stylesheet, resolveImmutablePublicAsset, collectFontPreloads)));
+    // 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: {
@@ -634,25 +641,73 @@ async function resolveStaticAssetReferences(assets) {
         fontPreloads,
     };
 }
-async function resolveStylesheetAsset(stylesheet, resolveImmutablePublicAsset, onFontPreload) {
+// 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 inline = stylesheet.inline === true;
+    const explicitInline = stylesheet.inline;
     if ("source" in stylesheet) {
-        if (inline) {
-            // Embed the CSS directly: no hashed public file and no `_headers` entry.
-            return { inline: await readFile(stylesheet.source, "utf8") };
-        }
-        if (stylesheet.immutable === false) {
+        // `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);
         }
-        return resolveImmutablePublicAsset({ source: stylesheet.source }, stylesheet.href);
+        // 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.
-    if (!inline && stylesheet.immutable === false) {
+    // 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);
@@ -663,7 +718,9 @@ async function resolveStylesheetAsset(stylesheet, resolveImmutablePublicAsset, o
         }
     }
     // The woff2 files are always vendored above; only the CSS is inlined.
-    return inline ? { inline: css } : resolveImmutablePublicAsset({ content: css }, stylesheet.href);
+    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
@@ -689,13 +746,17 @@ function selectFontPreloads(fontPaths, preload) {
     }
     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
@@ -987,6 +1048,12 @@ export async function buildSite(config) {
     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,

package/package.json CHANGED Viewed

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