@half-built/astro 0.1.0

package/src/scripts/site-header.ts

@@ -0,0 +1,73 @@
+import { claim, release, type Island, type IslandHandle } from "./core/island";
+import { formatHeaderDate } from "../lib/header-date";
+import { docOf } from "./core/dom";
+
+/* The masthead header island (step 9): the date-box refresh and the
+   phone menu toggle, born from SiteHeader.astro's inline script.
+   The two halves are unconditional and independent, mirroring the
+   original: the date box refreshes on every mount regardless of the
+   menu (it is idempotent, same text each time), and the menu wiring
+   claims the button separately so a second mount does not double-bind
+   its click/pointerdown/keydown handlers. */
+
+export interface SiteHeaderOptions {
+  dateId?: string;
+  menuButton?: string;
+  menuId?: string;
+  /* Defaults to formatHeaderDate, the same function Base.astro uses for
+     the server render. Its package-time home (staying in src/lib vs.
+     moving into the library) is an 11.3 decision; this option just
+     gives a second site a seam to override it without forking. */
+  formatDate?: (d: Date) => string;
+}
+
+export const mountSiteHeader: Island<SiteHeaderOptions> = (root, options = {}): IslandHandle => {
+  const { dateId = "header-date", menuButton = ".menu-toggle", menuId = "primary-menu", formatDate = formatHeaderDate } = options;
+  const doc = docOf(root);
+
+  // Header date: live like the WordPress original (build-time text is the
+  // no-JS fallback), same format function as the server render.
+  const dateBox = doc.getElementById(dateId);
+  if (dateBox) dateBox.textContent = formatDate(new Date());
+
+  const btn = root.querySelector<HTMLButtonElement>(menuButton);
+  const menu = doc.getElementById(menuId);
+  let onClick: (() => void) | null = null;
+  let onPointerdown: ((ev: PointerEvent) => void) | null = null;
+  let onKeydown: ((ev: KeyboardEvent) => void) | null = null;
+
+  if (btn && claim(btn, "site-header")) {
+    const isOpen = (): boolean => menu?.classList.contains("open") ?? false;
+    const setOpen = (open: boolean): void => {
+      menu?.classList.toggle("open", open);
+      btn.setAttribute("aria-expanded", String(open));
+    };
+    onClick = () => { setOpen(!isOpen()); };
+    btn.addEventListener("click", onClick);
+    /* A pop-out over the page closes the way the search flyout does: a
+       press anywhere outside it, or Escape (which hands focus back to the
+       button). */
+    onPointerdown = (ev) => {
+      if (!isOpen()) return;
+      const t = ev.target;
+      if (t instanceof Node && (menu?.contains(t) || btn.contains(t))) return;
+      setOpen(false);
+    };
+    onKeydown = (ev) => {
+      if (ev.key !== "Escape" || !isOpen()) return;
+      setOpen(false);
+      btn.focus();
+    };
+    doc.addEventListener("pointerdown", onPointerdown);
+    doc.addEventListener("keydown", onKeydown);
+  }
+
+  return {
+    destroy(): void {
+      if (btn && onClick) btn.removeEventListener("click", onClick);
+      if (onPointerdown) doc.removeEventListener("pointerdown", onPointerdown);
+      if (onKeydown) doc.removeEventListener("keydown", onKeydown);
+      if (btn && onClick) release(btn, "site-header");
+    },
+  };
+};

package/src/scripts/subscribe.ts

@@ -0,0 +1,116 @@
+/* Subscribe form runtime. The form is a real form (method post, action =
+   Buttondown's keyless embed-subscribe endpoint) so it works with no
+   JavaScript at all: the browser posts, Buttondown redirects to the
+   site's /newsletter/subscribed/ page. With JavaScript, this script takes over the
+   submit, posts the same FormData with fetch, and writes the outcome
+   into the status line so the reader stays put. There is no server of
+   ours in the path and no secret involved.
+
+   Buttondown answers a successful post with a 302 to our own origin,
+   carrying Access-Control-Allow-Origin: * on the redirect response itself
+   but not on ours, so a followed fetch cannot read it: the browser throws
+   TypeError: Failed to fetch even though the signup went through. The
+   fetch below asks for redirect: "manual" instead, which turns that 302
+   into a clean opaqueredirect result rather than an error. Any other real
+   response (Buttondown's captcha interstitial for a suspicious client,
+   or an error page) falls back to a native form submit so the reader can
+   finish it on Buttondown's own page. Only a thrown fetch (the network
+   itself failing) writes the couldn't-reach line. Spec:
+   docs/superpowers/specs/2026-08-16-mailing-list-wiring-design.md
+
+   On the island contract (step 9): mount(root, options?) returns a
+   destroy handle, and claim() makes a second mount over an already-wired
+   form a no-op. */
+
+import { claim, release, type Island, type IslandHandle } from "./core/island";
+
+export const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+export const MSG = {
+  invalid: "That doesn't look like an email address.",
+  pending: "Sending...",
+  sent: "Check your inbox. Nothing arrives until you click the confirmation link.",
+  failed: "Couldn't reach the list. Try again in a minute.",
+  /* Composes the failure line when the form names a public sign-up page.
+     A function member so an overridden register controls the whole
+     sentence, joiner included (step 9.5; the generalization review found
+     the joiner was the one baked phrase left in this script). */
+  failedAt: (failed: string, url: string): string => `${failed.replace(/\.$/, "")}, or sign up at ${url}.`,
+};
+
+/* The provider's public sign-up page rides the form's data-public-url
+   (config NEWSLETTER via the component's publicUrl prop), so this script names no provider; without the
+   attribute the message stays generic. */
+export function failedMessage(form: HTMLFormElement, messages: typeof MSG): string {
+  const url = form.dataset.publicUrl;
+  return url ? messages.failedAt(messages.failed, url) : messages.failed;
+}
+
+function setStatus(status: HTMLElement, text: string, isError: boolean): void {
+  status.textContent = text;
+  status.classList.toggle("subscribe-status-err", isError);
+}
+
+async function send(form: HTMLFormElement, input: HTMLInputElement, button: HTMLButtonElement | null, status: HTMLElement, messages: typeof MSG): Promise<void> {
+  if (button) button.disabled = true;
+  setStatus(status, messages.pending, false);
+  try {
+    const res = await fetch(form.action, { method: "POST", body: new FormData(form), redirect: "manual" });
+    if (res.ok || res.type === "opaqueredirect") {
+      setStatus(status, messages.sent, false);
+      input.value = "";
+      if (button) button.disabled = false;
+    } else {
+      /* A real, readable non-OK response: Buttondown's captcha
+         interstitial for a suspicious client, or an error page. A fetch
+         cannot complete the captcha; hand off to a native submit so the
+         reader finishes it on Buttondown's own page, which redirects back
+         to /newsletter/subscribed/. The page is navigating away, so the status line
+         is left alone and the button stays disabled. */
+      form.submit();
+    }
+  } catch {
+    setStatus(status, failedMessage(form, messages), true);
+    if (button) button.disabled = false;
+  }
+}
+
+export interface SubscribeOptions {
+  selector?: string;
+  messages?: Partial<typeof MSG>;
+}
+
+export const mountSubscribe: Island<SubscribeOptions> = (root, options = {}): IslandHandle => {
+  const { selector = ".subscribe-form", messages: messagesOverride = {} } = options;
+  const messages: typeof MSG = { ...MSG, ...messagesOverride };
+  const forms = [...root.querySelectorAll<HTMLFormElement>(selector)].filter((form) => claim(form, "subscribe"));
+
+  const handlers: [HTMLFormElement, (e: Event) => void][] = [];
+  for (const form of forms) {
+    const onSubmit = (e: Event): void => {
+      e.preventDefault();
+      const input = form.querySelector(".subscribe-email");
+      const button = form.querySelector(".subscribe-submit");
+      const status = form.parentElement?.querySelector(".subscribe-status");
+      if (!(input instanceof HTMLInputElement) || !(status instanceof HTMLElement)) return;
+      const value = input.value.trim();
+      input.value = value;
+      if (!EMAIL.test(value)) {
+        setStatus(status, messages.invalid, true);
+        return;
+      }
+      void send(form, input, button instanceof HTMLButtonElement ? button : null, status, messages);
+    };
+    form.addEventListener("submit", onSubmit);
+    handlers.push([form, onSubmit]);
+  }
+
+  return {
+    destroy(): void {
+      for (const [form, onSubmit] of handlers) {
+        form.removeEventListener("submit", onSubmit);
+        release(form, "subscribe");
+      }
+    },
+  };
+};

package/src/scripts/theme-toggle.ts

@@ -0,0 +1,115 @@
+/* Day/night toggle (owner request 2026-08-25): the header button next to
+   the date stamp flips data-theme on <html> between light and dark and
+   remembers the choice. The first paint is handled by the inline stamp in
+   Shell.astro's head, which reads the same storage key (or, with nothing
+   stored, the system preference), so there is no flash of the wrong
+   theme; this island only wires the button. Shape follows the library's
+   mount(root, options?) contract (step 9): idempotent, and it returns a
+   destroy handle. The storage key is a mount option, not a package
+   literal (step 11.2); the blog passes it from lib/theme-key. */
+
+import { type Island, type IslandHandle } from "./core/island";
+import { docOf } from "./core/dom";
+
+export type Theme = "light" | "dark";
+
+const LABEL: Record<Theme, string> = {
+  light: "Switch to dark mode",
+  dark: "Switch to light mode",
+};
+
+/* Storage can be absent or throwing (private mode, blocked site data);
+   every access is guarded and a bad value reads as no choice. With no
+   storageKey there is nowhere to read from, so this reads as no choice
+   too rather than guessing at a key. */
+export function readStored(storage: Storage | null, storageKey?: string): Theme | null {
+  if (!storageKey) return null;
+  try {
+    const v = storage?.getItem(storageKey);
+    return v === "light" || v === "dark" ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+/* With no storageKey, this no-ops: the toggle still flips the theme for
+   the page, it just does not persist the choice. That is a safe
+   degradation for an adopter who forgot to pass one, not a broken
+   toggle. */
+function writeStored(storage: Storage | null, storageKey: string | undefined, theme: Theme): void {
+  if (!storageKey) return;
+  try {
+    storage?.setItem(storageKey, theme);
+  } catch {
+    /* nothing to do: the choice lives for this page only */
+  }
+}
+
+export function current(doc: Document): Theme {
+  return doc.documentElement.dataset.theme === "dark" ? "dark" : "light";
+}
+
+/* Light is the absence of the attribute, so the light theme stays the
+   plain :root definition and the dark file only ever adds. */
+export function apply(doc: Document, theme: Theme): void {
+  if (theme === "dark") doc.documentElement.dataset.theme = "dark";
+  else delete doc.documentElement.dataset.theme;
+}
+
+function reflect(btn: HTMLButtonElement, theme: Theme, labels: Record<Theme, string>): void {
+  btn.setAttribute("aria-pressed", theme === "dark" ? "true" : "false");
+  btn.setAttribute("aria-label", labels[theme]);
+  btn.title = labels[theme];
+}
+
+/* Every mounted button, so a click on one (the top band's, or the
+   phone placement beside the search) updates the state of all. */
+const mounted = new Set<HTMLButtonElement>();
+
+export interface ThemeToggleOptions {
+  selector?: string;
+  doc?: Document;
+  storage?: Storage | null;
+  /* No default: the toggle bakes in no brand's key. Pass the site's
+     key to persist a choice; omit it and the toggle still works for
+     the page, it just forgets on reload. */
+  storageKey?: string;
+  /* Button aria-label/title text per theme, defaulting to the English
+     day/night pair above. */
+  labels?: Record<Theme, string>;
+}
+
+export const mountThemeToggle: Island<ThemeToggleOptions> = (root, options = {}): IslandHandle => {
+  const doc = options.doc ?? docOf(root);
+  const { selector = ".theme-toggle", storage = safeStorage(doc), storageKey, labels = LABEL } = options;
+  const handlers: [HTMLButtonElement, () => void][] = [];
+  for (const btn of root.querySelectorAll<HTMLButtonElement>(selector)) {
+    if (mounted.has(btn)) continue;
+    mounted.add(btn);
+    reflect(btn, current(doc), labels);
+    const onClick = () => {
+      const next: Theme = current(doc) === "dark" ? "light" : "dark";
+      apply(doc, next);
+      writeStored(storage, storageKey, next);
+      for (const b of mounted) reflect(b, next, labels);
+    };
+    btn.addEventListener("click", onClick);
+    handlers.push([btn, onClick]);
+  }
+  return {
+    destroy(): void {
+      for (const [btn, onClick] of handlers) {
+        btn.removeEventListener("click", onClick);
+        mounted.delete(btn);
+      }
+    },
+  };
+};
+
+function safeStorage(doc: Document): Storage | null {
+  try {
+    return doc.defaultView?.localStorage ?? null;
+  } catch {
+    return null;
+  }
+}

package/src/shiki/code-theme.mjs

@@ -0,0 +1,16 @@
+// Custom TextMate theme: amber on the parent theme's dark brown.
+export default {
+  name: "terminal-amber",
+  type: "dark",
+  colors: {
+    "editor.background": "#1b140c",
+    "editor.foreground": "#e8d9c3",
+  },
+  tokenColors: [
+    { scope: ["keyword", "storage", "keyword.control"], settings: { foreground: "#ffaa3c" } },
+    { scope: ["entity.name.function", "support.function", "entity.name.tag"], settings: { foreground: "#ffd18a" } },
+    { scope: ["string", "constant.numeric", "constant.language", "constant.character"], settings: { foreground: "#e07c14" } },
+    { scope: ["comment", "punctuation.definition.comment"], settings: { foreground: "#8a7a63", fontStyle: "italic" } },
+    { scope: ["variable", "support.variable"], settings: { foreground: "#e8d9c3" } },
+  ],
+};