chore: initial website stopping point

Author: Spelkington

.mcp.json

@@ -2,7 +2,12 @@
   "mcpServers": {
     "chrome-devtools": {
       "command": "npx",
-      "args": ["-y", "chrome-devtools-mcp@latest"]
+      "args": [
+        "-y",
+        "chrome-devtools-mcp@latest",
+        "--executablePath",
+        "/usr/bin/chromium"
+      ]
     }
   }
 }

src/website/astro.config.mjs

@@ -1,4 +1,6 @@
 // @ts-check
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import { defineConfig } from "astro/config";
 import starlight from "@astrojs/starlight";
 
@@ -12,6 +14,17 @@ import starlight from "@astrojs/starlight";
 // lives nested at src/content/docs/docs/*. That subtree is populated at build
 // time by `scripts/ingest-docs.mjs`, which ingests the canonical `docs/`
 // directory at the repo root. See scripts/ingest-docs.mjs for the contract.
+
+// Custom Shiki theme aligned to the Notebook tokenizer used by the marketing
+// homepage's CodeBlock component. Loaded as a JSON file so it can be edited
+// without touching this config.
+const notebookTheme = JSON.parse(
+  readFileSync(
+    fileURLToPath(new URL("./src/styles/shiki-notebook.json", import.meta.url)),
+    "utf8",
+  ),
+);
+
 export default defineConfig({
   site: "https://chaoticgoodcomputing.github.io",
   base: "/flowthru",
@@ -29,6 +42,34 @@ export default defineConfig({
         github: "https://github.com/chaoticgoodcomputing/flowthru",
       },
       customCss: ["./src/styles/flowthru.css"],
+      // Starlight renders fenced code blocks via expressive-code (a Shiki
+      // wrapper). Configure its theme here, not via markdown.shikiConfig —
+      // expressive-code ignores the latter. Single theme = light-only,
+      // matching the site's design direction.
+      expressiveCode: {
+        themes: [notebookTheme],
+        useDarkModeMediaQuery: false,
+        // The Notebook palette was hand-tuned against the paper background
+        // already; let it through unmodified instead of having expressive-
+        // code's contrast adjuster nudge our purples and ambers around.
+        minSyntaxHighlightingColorContrast: 0,
+        styleOverrides: {
+          frames: {
+            frameBoxShadowCssValue: "none",
+          },
+        },
+      },
+      // Site is light-only.
+      //   ThemeProvider — replaced with a version that hard-pins
+      //     `data-theme="light"` instead of consulting prefers-color-scheme.
+      //     Without this, users on dark-mode OSes see Starlight's dark theme.
+      //   ThemeSelect   — replaced with a no-op so users aren't presented with
+      //     a control that does nothing useful.
+      components: {
+        ThemeProvider:
+          "./src/components/starlight/LightThemeProvider.astro",
+        ThemeSelect: "./src/components/starlight/EmptyThemeSelect.astro",
+      },
       sidebar: [
         {
           label: "Tutorials",

src/website/src/components/starlight/EmptyThemeSelect.astro

@@ -0,0 +1,7 @@
+---
+// Empty replacement for Starlight's <ThemeSelect />. Wired in astro.config.mjs
+// via the starlight() integration's `components` override, which renders this
+// in place of the built-in toggle. The site is light-only for now; a
+// coordinated dark variant is planned for a future pass that retheme both
+// the marketing surface and the docs together.
+---

src/website/src/components/starlight/LightThemeProvider.astro

@@ -0,0 +1,20 @@
+---
+// Replacement for Starlight's <ThemeProvider />.
+//
+// Starlight's default ThemeProvider runs a synchronous inline script that
+// sets `data-theme="dark"` when the user's OS prefers a dark color scheme.
+// The site is light-only for now (a coordinated dark variant is planned for
+// a future pass that retheme both the marketing surface and the docs
+// together), so we hard-pin `data-theme="light"` regardless of OS prefs.
+//
+// The script is inlined and `is:inline` to avoid a flash of mis-themed
+// content (FOUC) — same pattern Starlight uses.
+---
+
+<script is:inline>
+  document.documentElement.dataset.theme = "light";
+  // Starlight's components reference window.StarlightThemeProvider; provide
+  // a stub so anything calling .updatePickers() doesn't blow up. The actual
+  // theme picker is replaced by EmptyThemeSelect.astro.
+  window.StarlightThemeProvider = { updatePickers() {} };
+</script>

src/website/src/middleware.ts

@@ -0,0 +1,52 @@
+// Astro middleware — server-side response transform.
+//
+// Starlight's Page.astro hardcodes `<html data-theme="dark">` as the static
+// default attribute (it expects a client-side script to flip it to "light"
+// when the user prefers light mode). Since Flowthru's site is light-only
+// while we work out the base design language, we rewrite the attribute
+// before the response leaves the server.
+//
+// Doing this in middleware instead of via a client-side script means:
+//   - the static HTML ships with `data-theme="light"` from the start,
+//     so Starlight's `[data-theme="light"]` component rules apply
+//     consistently from the first paint;
+//   - there is no FOUC race between the inline theme script and the
+//     cascade resolution;
+//   - the `LightThemeProvider` stub (also in this project) is kept as a
+//     belt-and-suspenders safety net for any client-side state mutation,
+//     but is no longer load-bearing.
+//
+// When dark mode is eventually added (a coordinated v2 covering both the
+// marketing surface and the docs), this middleware comes out and the
+// runtime theme picker comes back.
+
+import { defineMiddleware } from "astro:middleware";
+
+const HTML_OPEN_TAG = /<html\b[^>]*>/i;
+const DARK_THEME_ATTR = /data-theme="dark"/g;
+
+export const onRequest = defineMiddleware(async (_context, next) => {
+  const response = await next();
+
+  const contentType = response.headers.get("content-type") ?? "";
+  if (!contentType.includes("text/html")) {
+    return response;
+  }
+
+  const html = await response.text();
+  const rewritten = html.replace(HTML_OPEN_TAG, (tag) =>
+    tag.replace(DARK_THEME_ATTR, 'data-theme="light"'),
+  );
+
+  // Preserve the original headers (status, content-type, etc.) but emit
+  // the rewritten body. Drop content-length since the body length changes;
+  // the server will recompute it.
+  const headers = new Headers(response.headers);
+  headers.delete("content-length");
+
+  return new Response(rewritten, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+});