@cloudhal/cli 0.3.7 → 0.3.8

package/dist/assets/starters/blog/README.md

@@ -22,7 +22,9 @@ Everything but `.gitignore`'s list. `cloudhal.json` holds the project's settings
 - `search.json.ts` — the search modal's answers (RFC-0029), where the deployment answers searches (`cloudhal dev`, the Cloudflare Site Worker). `components/SearchDialog.astro` is the modal's markup and words; Cloudhal's `/_cloudhal/search.1.js` wires it, and without it the header form opens `/search`.
 
 ## Styles (`src/styles`)
-`global.css` (imported by `layouts/Base.astro`) loads Tailwind, `fonts.css` and one file per feature from `styles/features/` (`tokens.css` with `@theme`, `prose.css`, `surfaces.css`, `motion.css`, `chrome.css`, `carousel.css` …) in cascade order. The rules are unlayered and later files override earlier ones, so keep the order; add a feature as a new file and import it from `global.css`. `source("..")` on the Tailwind import is relative to `global.css`, so that import stays there.
+`global.css` (imported by `layouts/Base.astro`) loads Tailwind, `fonts.css`, `font-fallbacks.css` and one file per feature from `styles/features/` (`tokens.css` with `@theme`, `prose.css`, `surfaces.css`, `motion.css`, `chrome.css`, `carousel.css` …) in cascade order. The rules are unlayered and later files override earlier ones, so keep the order; add a feature as a new file and import it from `global.css`. `source("..")` on the Tailwind import is relative to `global.css`, so that import stays there.
+
+Fonts are self-hosted under `public/fonts/v1/` and cached for a year (`public/_headers`): files never change under a path, so a new font set goes in `public/fonts/v2/`. Each web font in the pairing stacks (`tokens.css`) is followed by a metric-matched fallback from `font-fallbacks.css` (a system font scaled to the web font's width, ascent and descent), so the swap when the web font arrives does not move the text. That file is generated: after changing a font, run `pnpm fonts:fallbacks` in the monorepo.
 
 ## Theme settings (`src/theme.ts`)
 - `ARCHIVE_PAGE_SIZE` — posts per archive page (20).

package/dist/assets/starters/blog/package.json

@@ -14,18 +14,18 @@
     "astro": "astro"
   },
   "dependencies": {
-    "@cloudhal/astro-renderer": "0.3.7",
-    "@cloudhal/core-ts": "0.3.7",
+    "@cloudhal/astro-renderer": "0.3.8",
+    "@cloudhal/core-ts": "0.3.8",
     "@tailwindcss/vite": "^4.3.3",
     "astro": "7.3.6",
     "better-sqlite3": "13.0.3",
     "tailwindcss": "^4.3.3",
     "@astrojs/cloudflare": "14.3.4",
-    "@cloudhal/cli": "0.3.7"
+    "@cloudhal/cli": "0.3.8"
   },
   "devDependencies": {
     "wrangler": "^4.148.0",
-    "@cloudhal/cloudflare": "0.3.7"
+    "@cloudhal/cloudflare": "0.3.8"
   },
   "trustedDependencies": [
     "better-sqlite3",

package/dist/assets/starters/blog/public/_headers

@@ -0,0 +1,5 @@
+# Font files never change under a path: a new font set gets a new directory (/fonts/v2/…).
+# Cached for a year, the browser uses them on every reload without asking the server, so the
+# text is drawn in its font from the first paint instead of swapping in later.
+/fonts/v1/*
+  Cache-Control: public, max-age=31536000, immutable

package/dist/assets/starters/blog/src/fonts.ts

@@ -4,12 +4,28 @@
  * (Turkish and other accented letters) load on demand through fonts.css's unicode ranges.
  */
 export const PAIRING_PRELOADS: Readonly<Record<string, readonly string[]>> = {
-  editorial: ["/fonts/fraunces-latin-wght-normal.woff2", "/fonts/inter-latin-wght-normal.woff2"],
-  modern: ["/fonts/space-grotesk-latin-wght-normal.woff2", "/fonts/inter-latin-wght-normal.woff2"],
-  humanist: ["/fonts/source-sans-3-latin-wght-normal.woff2"],
+  editorial: [
+    "/fonts/v1/fraunces-latin-wght-normal.woff2",
+    "/fonts/v1/inter-latin-wght-normal.woff2",
+  ],
+  modern: [
+    "/fonts/v1/space-grotesk-latin-wght-normal.woff2",
+    "/fonts/v1/inter-latin-wght-normal.woff2",
+  ],
+  humanist: ["/fonts/v1/source-sans-3-latin-wght-normal.woff2"],
   technical: [
-    "/fonts/jetbrains-mono-latin-wght-normal.woff2",
-    "/fonts/inter-latin-wght-normal.woff2",
+    "/fonts/v1/jetbrains-mono-latin-wght-normal.woff2",
+    "/fonts/v1/inter-latin-wght-normal.woff2",
   ],
-  classic: ["/fonts/source-serif-4-latin-wght-normal.woff2"],
+  classic: ["/fonts/v1/source-serif-4-latin-wght-normal.woff2"],
 };
+
+/**
+ * The same preloads as a `Link` response header. On a Cloudflare zone with Early Hints on, the
+ * edge sends it as a 103 before the page, so the fonts load while the Worker is still rendering.
+ */
+export function fontLinkHeader(hrefs: readonly string[]): string {
+  return hrefs
+    .map((h) => `<${h}>; rel=preload; as=font; type="font/woff2"; crossorigin`)
+    .join(", ");
+}

package/dist/assets/starters/blog/src/pages/[...path].astro

@@ -51,6 +51,7 @@ import {
   relatedEntries,
   termAncestors,
 } from "@cloudhal/astro-renderer/taxonomy";
+import { themeVariables } from "@cloudhal/astro-renderer/theme-settings";
 import type { ContentEntry } from "@cloudhal/core-contracts";
 /**
  * One route for the whole graph (RFC-0002 §7 order): a Page answers at its `path`; an article at
@@ -73,8 +74,10 @@ import NotFound from "../components/NotFound.astro";
 import PostTerms from "../components/PostTerms.astro";
 import RelatedPosts from "../components/RelatedPosts.astro";
 import Search from "../components/Search.astro";
+import { fontLinkHeader, PAIRING_PRELOADS } from "../fonts.ts";
 import { iconSet } from "../icons.ts";
 import Base from "../layouts/Base.astro";
+import { themeSettings } from "../settings.ts";
 import {
   ARCHIVE_PAGE_SIZE,
   blocks,
@@ -354,6 +357,10 @@ const localized = localizeHead(head, site, {
 });
 const meta = fallback || notFound ? { ...localized, robots: "noindex,follow" } : localized;
 Astro.response.headers.set("content-language", shownIn);
+// The pairing's fonts as a Link header too (Early Hints), not only as <link rel=preload> in <head>.
+const pairing = themeVariables(site, themeSettings).attributes["data-ch-type-pairing"];
+const preloads = PAIRING_PRELOADS[pairing ?? ""] ?? [];
+if (preloads.length) Astro.response.headers.set("link", fontLinkHeader(preloads));
 // The reader's notice (RFC-0033 §4): machine output until a person reviews it (or always, when
 // the site asks), a page shown in its original language, each with a link to the original.
 const original = alternates.find((a) => a.original && !a.current);

package/dist/assets/starters/blog/src/styles/features/tokens.css

@@ -55,29 +55,41 @@
   font-family: ui-monospace, "Cascadia Code", "Source Code Pro", Menlo, Consolas, monospace;
 }
 /*
- * Font pairings (RFC-0023 §2): the families come from fonts.css and load only when used. They win
+ * Font pairings (RFC-0023 §2): the families come from fonts.css and load only when used; each is
+ * followed by its metric-matched fallback (font-fallbacks.css), so the swap does not move the
+ * text. They win
  * over the older typeface setting; `system` keeps it.
  */
 [data-ch-type-pairing="editorial"] {
-  --ch-font-display: "Fraunces Variable", ui-serif, Georgia, serif;
-  --ch-font-text: "Inter Variable", ui-sans-serif, system-ui, sans-serif;
+  --ch-font-display: "Fraunces Variable", "Fraunces Variable Fallback", ui-serif, Georgia, serif;
+  --ch-font-text: "Inter Variable", "Inter Variable Fallback", ui-sans-serif, system-ui, sans-serif;
 }
 [data-ch-type-pairing="modern"] {
-  --ch-font-display: "Space Grotesk Variable", ui-sans-serif, system-ui, sans-serif;
-  --ch-font-text: "Inter Variable", ui-sans-serif, system-ui, sans-serif;
+  --ch-font-display:
+    "Space Grotesk Variable", "Space Grotesk Variable Fallback", ui-sans-serif, system-ui,
+    sans-serif;
+  --ch-font-text: "Inter Variable", "Inter Variable Fallback", ui-sans-serif, system-ui, sans-serif;
 }
 [data-ch-type-pairing="humanist"] {
-  --ch-font-display: "Source Sans 3 Variable", ui-sans-serif, system-ui, sans-serif;
-  --ch-font-text: "Source Sans 3 Variable", ui-sans-serif, system-ui, sans-serif;
+  --ch-font-display:
+    "Source Sans 3 Variable", "Source Sans 3 Variable Fallback", ui-sans-serif, system-ui,
+    sans-serif;
+  --ch-font-text:
+    "Source Sans 3 Variable", "Source Sans 3 Variable Fallback", ui-sans-serif, system-ui,
+    sans-serif;
 }
 [data-ch-type-pairing="technical"] {
-  --ch-font-display: "JetBrains Mono Variable", ui-monospace, monospace;
-  --ch-font-text: "Inter Variable", ui-sans-serif, system-ui, sans-serif;
-  --ch-font-code: "JetBrains Mono Variable", ui-monospace, monospace;
+  --ch-font-display:
+    "JetBrains Mono Variable", "JetBrains Mono Variable Fallback", ui-monospace, monospace;
+  --ch-font-text: "Inter Variable", "Inter Variable Fallback", ui-sans-serif, system-ui, sans-serif;
+  --ch-font-code:
+    "JetBrains Mono Variable", "JetBrains Mono Variable Fallback", ui-monospace, monospace;
 }
 [data-ch-type-pairing="classic"] {
-  --ch-font-display: "Source Serif 4 Variable", ui-serif, Georgia, serif;
-  --ch-font-text: "Source Serif 4 Variable", ui-serif, Georgia, serif;
+  --ch-font-display:
+    "Source Serif 4 Variable", "Source Serif 4 Variable Fallback", ui-serif, Georgia, serif;
+  --ch-font-text:
+    "Source Serif 4 Variable", "Source Serif 4 Variable Fallback", ui-serif, Georgia, serif;
 }
 [data-ch-type-pairing]:not([data-ch-type-pairing="system"]) .ch-body {
   font-family: var(--ch-font-text);

package/dist/assets/starters/blog/src/styles/font-fallbacks.css

@@ -0,0 +1,53 @@
+/*
+ * Generated by scripts/font-fallbacks.ts: do not edit. Metric-matched fallback faces for the
+ * pairings' web fonts (tokens.css lists each right after its web font), so the swap to the web
+ * font does not move the text.
+ */
+@font-face {
+  font-family: "Fraunces Variable Fallback";
+  src: local("Times New Roman"), local("TimesNewRomanPSMT");
+  size-adjust: 113.62%;
+  ascent-override: 86.08%;
+  descent-override: 22.44%;
+  line-gap-override: 0.00%;
+}
+@font-face {
+  font-family: "Inter Variable Fallback";
+  src: local("Arial"), local("ArialMT");
+  size-adjust: 107.12%;
+  ascent-override: 90.44%;
+  descent-override: 22.52%;
+  line-gap-override: 0.00%;
+}
+@font-face {
+  font-family: "Space Grotesk Variable Fallback";
+  src: local("Arial"), local("ArialMT");
+  size-adjust: 109.47%;
+  ascent-override: 89.89%;
+  descent-override: 26.67%;
+  line-gap-override: 0.00%;
+}
+@font-face {
+  font-family: "Source Sans 3 Variable Fallback";
+  src: local("Arial"), local("ArialMT");
+  size-adjust: 92.42%;
+  ascent-override: 110.80%;
+  descent-override: 43.28%;
+  line-gap-override: 0.00%;
+}
+@font-face {
+  font-family: "Source Serif 4 Variable Fallback";
+  src: local("Times New Roman"), local("TimesNewRomanPSMT");
+  size-adjust: 117.91%;
+  ascent-override: 87.87%;
+  descent-override: 28.41%;
+  line-gap-override: 0.00%;
+}
+@font-face {
+  font-family: "JetBrains Mono Variable Fallback";
+  src: local("Courier New"), local("CourierNewPSMT");
+  size-adjust: 99.98%;
+  ascent-override: 102.02%;
+  descent-override: 30.00%;
+  line-gap-override: 0.00%;
+}

package/dist/assets/starters/blog/src/styles/fonts.css

@@ -8,7 +8,7 @@
   font-style: normal;
   font-display: swap;
   font-weight: 100 900;
-  src: url(/fonts/fraunces-latin-ext-wght-normal.woff2) format("woff2-variations");
+  src: url(/fonts/v1/fraunces-latin-ext-wght-normal.woff2) format("woff2-variations");
   unicode-range:
     U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
 }
@@ -17,7 +17,7 @@
   font-style: normal;
   font-display: swap;
   font-weight: 100 900;
-  src: url(/fonts/fraunces-latin-wght-normal.woff2) format("woff2-variations");
+  src: url(/fonts/v1/fraunces-latin-wght-normal.woff2) format("woff2-variations");
   unicode-range:
     U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
 }
@@ -26,7 +26,7 @@
   font-style: normal;
   font-display: swap;
   font-weight: 100 900;
-  src: url(/fonts/inter-latin-ext-wght-normal.woff2) format("woff2-variations");
+  src: url(/fonts/v1/inter-latin-ext-wght-normal.woff2) format("woff2-variations");
   unicode-range:
     U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
 }
@@ -35,7 +35,7 @@
   font-style: normal;
   font-display: swap;
   font-weight: 100 900;
-  src: url(/fonts/inter-latin-wght-normal.woff2) format("woff2-variations");
+  src: url(/fonts/v1/inter-latin-wght-normal.woff2) format("woff2-variations");
   unicode-range:
     U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
 }
@@ -44,7 +44,7 @@
   font-style: normal;
   font-display: swap;
   font-weight: 100 800;
-  src: url(/fonts/jetbrains-mono-latin-ext-wght-normal.woff2) format("woff2-variations");
+  src: url(/fonts/v1/jetbrains-mono-latin-ext-wght-normal.woff2) format("woff2-variations");
   unicode-range:
     U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
 }
@@ -53,7 +53,7 @@
   font-style: normal;
   font-display: swap;
   font-weight: 100 800;
-  src: url(/fonts/jetbrains-mono-latin-wght-normal.woff2) format("woff2-variations");
+  src: url(/fonts/v1/jetbrains-mono-latin-wght-normal.woff2) format("woff2-variations");
   unicode-range:
     U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
 }
@@ -62,7 +62,7 @@
   font-style: normal;
   font-display: swap;
   font-weight: 200 900;
-  src: url(/fonts/source-sans-3-latin-ext-wght-normal.woff2) format("woff2-variations");
+  src: url(/fonts/v1/source-sans-3-latin-ext-wght-normal.woff2) format("woff2-variations");
   unicode-range:
     U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C4, U+2113, U+2C60-2C7F, U+A720-A7FF;
 }
@@ -71,7 +71,7 @@
   font-style: normal;
   font-display: swap;
   font-weight: 200 900;
-  src: url(/fonts/source-sans-3-latin-wght-normal.woff2) format("woff2-variations");
+  src: url(/fonts/v1/source-sans-3-latin-wght-normal.woff2) format("woff2-variations");
   unicode-range:
     U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
 }
@@ -80,7 +80,7 @@
   font-style: normal;
   font-display: swap;
   font-weight: 200 900;
-  src: url(/fonts/source-serif-4-latin-ext-wght-normal.woff2) format("woff2-variations");
+  src: url(/fonts/v1/source-serif-4-latin-ext-wght-normal.woff2) format("woff2-variations");
   unicode-range:
     U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C4, U+2113, U+2C60-2C7F, U+A720-A7FF;
 }
@@ -89,7 +89,7 @@
   font-style: normal;
   font-display: swap;
   font-weight: 200 900;
-  src: url(/fonts/source-serif-4-latin-wght-normal.woff2) format("woff2-variations");
+  src: url(/fonts/v1/source-serif-4-latin-wght-normal.woff2) format("woff2-variations");
   unicode-range:
     U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
 }
@@ -98,7 +98,7 @@
   font-style: normal;
   font-display: swap;
   font-weight: 300 700;
-  src: url(/fonts/space-grotesk-latin-ext-wght-normal.woff2) format("woff2-variations");
+  src: url(/fonts/v1/space-grotesk-latin-ext-wght-normal.woff2) format("woff2-variations");
   unicode-range:
     U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
 }
@@ -107,7 +107,7 @@
   font-style: normal;
   font-display: swap;
   font-weight: 300 700;
-  src: url(/fonts/space-grotesk-latin-wght-normal.woff2) format("woff2-variations");
+  src: url(/fonts/v1/space-grotesk-latin-wght-normal.woff2) format("woff2-variations");
   unicode-range:
     U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
 }

package/dist/assets/starters/blog/src/styles/global.css

@@ -1,6 +1,7 @@
 /* Scan `src/` only: automatic detection may walk up the file system (docs/design/starter-references.md §6). */
 @import "tailwindcss" source("..");
 @import "./fonts.css";
+@import "./font-fallbacks.css";
 
 /*
  * One file per feature (docs/engineering/code-structure.md §8), in cascade order. Unlayered on

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudhal/cli",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "description": "cloudhal — create, run and build Cloudhal sites locally",
   "license": "Apache-2.0",
   "homepage": "https://cloudhal.dev",
@@ -27,16 +27,16 @@
     "README.md"
   ],
   "dependencies": {
-    "@cloudhal/agent-runtime": "0.3.7",
-    "@cloudhal/analytics": "0.3.7",
-    "@cloudhal/api": "0.3.7",
-    "@cloudhal/cloudflare": "0.3.7",
-    "@cloudhal/comments": "0.3.7",
-    "@cloudhal/core-contracts": "0.3.7",
-    "@cloudhal/core-ts": "0.3.7",
-    "@cloudhal/mcp-server": "0.3.7",
-    "@cloudhal/schedules": "0.3.7",
-    "@cloudhal/storage": "0.3.7",
+    "@cloudhal/agent-runtime": "0.3.8",
+    "@cloudhal/analytics": "0.3.8",
+    "@cloudhal/api": "0.3.8",
+    "@cloudhal/cloudflare": "0.3.8",
+    "@cloudhal/comments": "0.3.8",
+    "@cloudhal/core-contracts": "0.3.8",
+    "@cloudhal/core-ts": "0.3.8",
+    "@cloudhal/mcp-server": "0.3.8",
+    "@cloudhal/schedules": "0.3.8",
+    "@cloudhal/storage": "0.3.8",
     "@hono/node-server": "^2.1.4",
     "better-sqlite3": "13.0.3"
   },