npm - @half-built/astro - Versions diffs - 0.1.0 - Mend

@half-built/astro 0.1.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 (60) hide show

package/ICONS-LICENSE +43 -0
package/LICENSE +21 -0
package/README.md +16 -0
package/package.json +18 -0
package/src/components/CategoryCard.astro +31 -0
package/src/components/CornerBadges.astro +40 -0
package/src/components/Footer.astro +209 -0
package/src/components/LightboxLink.astro +13 -0
package/src/components/LinkListWidget.astro +19 -0
package/src/components/Pagination.astro +72 -0
package/src/components/PostCard.astro +166 -0
package/src/components/PostNavigation.astro +61 -0
package/src/components/Shell.astro +52 -0
package/src/components/SiteHeader.astro +326 -0
package/src/components/SmartImage.astro +34 -0
package/src/components/Subscribe.astro +117 -0
package/src/components/ThemeToggle.astro +41 -0
package/src/components/TwoColumn.astro +12 -0
package/src/components/Widget.astro +41 -0
package/src/components/content/BlogImage.astro +39 -0
package/src/components/content/Button.astro +57 -0
package/src/components/content/Callout.astro +75 -0
package/src/components/content/CodeBlock.astro +7 -0
package/src/components/content/Gallery.astro +57 -0
package/src/components/content/GalleryImage.astro +35 -0
package/src/components/content/Group.astro +15 -0
package/src/components/content/MediaText.astro +60 -0
package/src/components/content/Palette.astro +42 -0
package/src/components/content/Quote.astro +21 -0
package/src/components/content/Spacer.astro +5 -0
package/src/components/content/Step.astro +126 -0
package/src/components/content/Walkthrough.astro +42 -0
package/src/components/models.ts +77 -0
package/src/lib/archive.ts +29 -0
package/src/lib/drafts.ts +52 -0
package/src/lib/format-date.ts +9 -0
package/src/lib/header-date.ts +6 -0
package/src/lib/ordering.ts +18 -0
package/src/lib/paginate.ts +15 -0
package/src/lib/reading-time.ts +4 -0
package/src/lib/slug.ts +73 -0
package/src/scripts/code-island.ts +75 -0
package/src/scripts/core/breakpoints.ts +4 -0
package/src/scripts/core/dom.ts +31 -0
package/src/scripts/core/frame-loop.ts +54 -0
package/src/scripts/core/icons.ts +30 -0
package/src/scripts/core/island.ts +25 -0
package/src/scripts/core/storage.ts +44 -0
package/src/scripts/focus-mode.ts +41 -0
package/src/scripts/lightbox.ts +446 -0
package/src/scripts/link-tip.ts +154 -0
package/src/scripts/path-player-math.ts +34 -0
package/src/scripts/path-player-paint.ts +154 -0
package/src/scripts/path-player.ts +341 -0
package/src/scripts/plate-modal.ts +91 -0
package/src/scripts/scroll-top.ts +32 -0
package/src/scripts/site-header.ts +73 -0
package/src/scripts/subscribe.ts +116 -0
package/src/scripts/theme-toggle.ts +115 -0
package/src/shiki/code-theme.mjs +16 -0

package/src/components/PostNavigation.astro ADDED Viewed

@@ -0,0 +1,61 @@
+---
+/* Prev/next post links: nav.navigation.post-navigation with
+   nav-previous/nav-next and Previous:/Next: subtitles, in the theme's
+   3px-bordered box. Previous = older post, Next = newer, as WordPress does.
+   Owner divergence from the live markup (2026-07-30): the newer post sits
+   LEFT and the older post RIGHT, matching the newest-first reading order
+   of the archives. Do not restore the WP left/right order for fidelity. */
+import type { PostRef } from "./models";
+interface Props {
+  class?: string;
+  prev?: PostRef;
+  next?: PostRef;
+  labels?: { heading?: string; next?: string; prev?: string; nav?: string };
+}
+const { prev, next, class: className, labels: labelsOverride = {} } = Astro.props;
+const labels = { heading: "Post navigation", next: "Next:", prev: "Previous:", nav: "Posts", ...labelsOverride };
+---
+{(prev || next) && (
+  <nav class:list={["navigation", "post-navigation", className]} aria-label={labels.nav}>
+    <h2 class="screen-reader-text">{labels.heading}</h2>
+    <div class="nav-links">
+      {next && (
+        <div class="nav-next">
+          <a href={next.href} rel="next">
+            <span class="nav-subtitle">{labels.next}</span> <span class="nav-title">{next.title}</span>
+          </a>
+        </div>
+      )}
+      {prev && (
+        <div class="nav-previous">
+          <a href={prev.href} rel="prev">
+            <span class="nav-subtitle">{labels.prev}</span> <span class="nav-title">{prev.title}</span>
+          </a>
+        </div>
+      )}
+    </div>
+  </nav>
+)}
+<style>
+  .post-navigation {
+    margin-top: 30px;
+    padding: 20px;
+    /* 3px is this box's design constant (the live theme's weight),
+       deliberately NOT var(--stroke): it does not scale with the theme
+       stroke. */
+    border: var(--stroke-3) solid var(--rule);
+  }
+  .nav-links {
+    display: flex;
+    justify-content: space-between;
+    gap: 20px;
+    flex-wrap: wrap;
+    font-size: var(--font-size-sm);
+  }
+  .nav-previous { text-align: right; margin-left: auto; }
+  .nav-links a { text-decoration: none; color: var(--ink); }
+  .nav-links a:hover .nav-title,
+  .nav-links a:focus .nav-title { text-decoration: underline; }
+  .nav-subtitle { font-weight: bold; }
+</style>

package/src/components/Shell.astro ADDED Viewed

@@ -0,0 +1,52 @@
+---
+/* The document shell (step 8, 2026-08-30): doctype and head skeleton,
+   first-paint theme stamp, skip link, page frame, scroll-to-top
+   floater. Site-specific head content (meta, OG, title) arrives through
+   the head slot, the chrome through the header and footer slots, so a
+   second site reuses the frame without forking it. No scoped CSS on
+   purpose: the shell's layout rules live once in styles/base/shell.css
+   (pinned by test/base.test.ts). */
+interface Props { lang?: string; skipLabel?: string; scrollTopLabel?: string; themeStorageKey: string }
+const { lang = "en", skipLabel = "Skip to content", scrollTopLabel = "Scroll to top", themeStorageKey } = Astro.props;
+---
+<!doctype html>
+<html lang={lang}>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    {/* Theme stamp, inline and first so the dark ground paints on the
+        first frame: a stored choice wins (scripts/theme-toggle.ts writes
+        it), otherwise the system preference. Light is the absence of the
+        attribute. Kept tiny and dependency-free on purpose.
+        The storage key rides define:vars from the required themeStorageKey
+        prop (step 11.2), so the shell bakes in no brand of its own; the
+        caller (Base.astro) supplies it from lib/theme-key. */}
+    <script is:inline define:vars={{ themeKey: themeStorageKey }}>
+      (function () {
+        var t = null;
+        try { t = localStorage.getItem(themeKey); } catch (e) { /* no storage */ }
+        if (t === "dark" || (t === null && matchMedia("(prefers-color-scheme: dark)").matches)) {
+          document.documentElement.dataset.theme = "dark";
+        }
+      })();
+    </script>
+    <slot name="head" />
+  </head>
+  <body>
+    <div id="page" class="site">
+      <a class="skip-link screen-reader-text" href="#primary-content">{skipLabel}</a>
+      <slot name="header" />
+      <div id="primary-content" class="primary-site-content">
+        <div class="site-content shell">
+          <slot />
+        </div>
+      </div>
+      <slot name="footer" />
+      <a href="#page" id="scroll-to-top" class="scroll-top" aria-label={scrollTopLabel}>
+        <svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><polyline points="4 15 12 7 20 15" /></svg>
+      </a>
+    </div>
+    {/* Site behavior scripts land here, inside the body, where the pre-step-8 markup carried them. */}
+    <slot name="scripts" />
+  </body>
+</html>

package/src/components/SiteHeader.astro ADDED Viewed

@@ -0,0 +1,326 @@
+---
+/* The real half-built-robots.com header, matching the live DOM structure:
+   site-header-wrapper (bracket frame) containing three bands.
+   - masthead-top: date box + social icons, pulled UP to straddle the top rule
+   - masthead-brand: centered site branding (h1 on home, p elsewhere)
+   - masthead-nav: nav boxes + search flyout, pulled DOWN to straddle the bottom rule
+   No logo image in the header: the live site renders text branding only. */
+import ThemeToggle from "./ThemeToggle.astro";
+import type { NavItem, SocialItem } from "./models";
+interface Props {
+  siteName: string;
+  tagline: string;
+  nav: NavItem[];
+  socials: SocialItem[];
+  /* Preformatted date for the top band's box; the caller owns the format
+     (the blog passes lib/header-date's live-theme format). The client
+     refresh takes a formatDate option (step 11.2) defaulting to lib/header-date;
+     only its package-time home remains a step 11.3 decision. */
+  dateStr: string;
+  isHome?: boolean;
+  searchAction?: string;
+  searchParam?: string;
+  searchLabels?: { prompt?: string; placeholder?: string; submit?: string };
+}
+const {
+  siteName,
+  tagline,
+  nav,
+  socials,
+  dateStr,
+  isHome = false,
+  searchAction = "/search/",
+  searchParam = "s",
+  searchLabels = {},
+} = Astro.props;
+const {
+  prompt: searchPrompt = "Search for:",
+  /* The static markup this replaces wrote the placeholder as the HTML
+     entity `Search &hellip;`, which the compiler decodes to this same
+     character at build time for static text. Written here as the
+     decoded character (not the entity spelling) because a prop value
+     goes through Astro's dynamic attribute path, which escapes a
+     literal "&" instead of decoding it, and would otherwise double
+     encode the entity into `&#38;hellip;` in the built output. */
+  placeholder: searchPlaceholder = "Search …",
+  submit: searchSubmit = "Search",
+} = searchLabels;
+const current = Astro.url.pathname;
+/* Home stays the current item on paginated index pages, like WordPress,
+   the component's own documented opinion (not a prop). */
+const isCurrent = (href: string) =>
+  href === "/" ? current === "/" || current.startsWith("/page/") : current === href;
+---
+<header id="masthead" class="site-header">
+  <div class="shell">
+    <div class="site-header-wrapper bracket-frame">
+      <div class="masthead-top">
+        <slot name="band-top"><div class="header-tools">
+          <div class="date boxed-label" id="header-date">{dateStr}</div>
+          <ThemeToggle />
+        </div>
+        <div class="social-icons">
+          {/* Tips drop below and pin to the icon's right edge (scripts/link-tip.ts). */}
+          <ul class="social-links" data-tip-place="below" data-tip-align="end">
+            {socials.map((s) => (
+              <li>
+                <a class="icon-box" href={s.href}>
+                  <span class="screen-reader-text">{s.label}</span>
+                  <Fragment set:html={s.icon} />
+                </a>
+              </li>
+            ))}
+          </ul>
+        </div></slot>
+      </div>
+      <div class="masthead-brand">
+        <slot name="band-brand"><div class="site-branding">
+          <div class="site-identity">
+            {isHome
+              ? <h1 class="site-title"><a href="/" rel="home">{siteName}</a></h1>
+              : <p class="site-title"><a href="/" rel="home">{siteName}</a></p>}
+            <p class="site-description">{tagline}</p>
+          </div>
+        </div></slot>
+      </div>
+      <div class="masthead-nav">
+        <slot name="band-nav"><div class="masthead-nav-inner">
+          <div class="header-nav-search">
+            <div class="header-navigation">
+              <nav id="site-navigation" class="main-navigation" aria-label="Primary">
+                <button type="button" class="menu-toggle" aria-controls="primary-menu" aria-expanded="false">
+                  <span></span><span></span><span></span>
+                  <span class="screen-reader-text">Menu</span>
+                </button>
+                <div class="menu-container">
+                  <ul id="primary-menu" class="menu">
+                    {nav.map((item) => (
+                      <li class={`menu-item${isCurrent(item.href) ? " current-menu-item" : ""}`}>
+                        <a class:list={["press-box", isCurrent(item.href) && "tint-overlay"]} href={item.href} aria-current={isCurrent(item.href) ? "page" : undefined}>{item.label}</a>
+                      </li>
+                    ))}
+                  </ul>
+                </div>
+              </nav>
+            </div>
+            <div class="header-end">
+              {/* Phones lose the top band, so the toggle sits beside the
+                  search there (owner request 2026-08-26). */}
+              <ThemeToggle placement="phone" />
+              <div class="navigation-search">
+                <div class="navigation-search-wrap">
+                  {/* A control that reveals UI is a button, not a link: a
+                      bare-hash anchor navigates (scroll jump + history
+                      entry), audit finding A3. focus-within still opens the
+                      flyout when the button takes focus. */}
+                  <button type="button" title="Search" class="navigation-search-icon icon-box">
+                    <svg viewBox="0 0 512 512" width="14" height="14" fill="currentColor" aria-hidden="true"><path d="M505 442.7L405.3 343c28.4-34.9 45.7-79 45.7-127C451 96.5 354.5 0 235.5 0S20 96.5 20 215.5 116.5 431 235.5 431c48 0 92.1-17.3 127-45.7L462.3 485c5.9 5.9 15.4 5.9 21.3 0l21.4-21.4c5.9-5.9 5.9-15.4 0-20.9zM235.5 371c-85.9 0-155.5-69.6-155.5-155.5S149.6 60 235.5 60 391 129.6 391 215.5 321.4 371 235.5 371z"/></svg>
+                    <span class="screen-reader-text">Search</span>
+                  </button>
+                  <div class="navigation-search-form">
+                    <form role="search" class="search-form field-join" action={searchAction} method="get">
+                      <label>
+                        <span class="screen-reader-text">{searchPrompt}</span>
+                        <input type="search" class="search-field field-join-input" placeholder={searchPlaceholder} name={searchParam} />
+                      </label>
+                      <input type="submit" class="search-submit field-join-button press-box press-box-shaded" value={searchSubmit} />
+                    </form>
+                  </div>
+                </div>
+              </div>
+            </div>
+          </div>
+        </div></slot>
+      </div>
+    </div>
+  </div>
+</header>
+<style>
+  .site-header { margin-block: 30px 10px; }
+  /* Frame comes from the .bracket-frame pattern; only the stacking context
+     is contextual here. */
+  .site-header-wrapper { z-index: 1; }
+  /* Top band straddles the top rule via the negative margin. */
+  .masthead-top {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    margin-top: calc(-30px + (-12px));
+  }
+  .masthead-top .date {
+    padding: 4px 10px;
+    display: grid;
+    place-items: center;
+    font-size: var(--font-size-sm);
+  }
+  /* Date box and the day/night toggle sit together on the left of the
+     top band, spaced like the social icons on the right. */
+  .header-tools { display: flex; align-items: center; gap: 10px; }
+  /* Bottom band's right end: the phone toggle (hidden on desktop) beside
+     the search icon, spaced like the top band's tools. */
+  .header-end { display: flex; align-items: center; gap: 10px; }
+  /* No background on the list itself: the header's top rule must stay
+     visible in the gaps between the boxed icons. */
+  ul.social-links {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+    display: flex;
+    gap: 10px;
+  }
+  .masthead-brand {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding-block: 20px;
+  }
+  .site-branding { padding-block: 10px; text-align: center; width: 100%; }
+  .site-title {
+    font-size: var(--font-size-xl);
+    line-height: 1.1;
+    font-weight: 700;
+    margin: 0;
+  }
+  .site-title a { text-decoration: none; color: var(--ink); }
+  /* The tagline wears the accent box (owner call 2026-09-03): the
+     callout's combination, the same one the press box and the demo
+     launcher wear. Accent line, the accent's legible ink for the text,
+     and the surface tinted 6% with the accent as its ground, in both
+     themes. It replaced bare accent text, which by day was #ffaa3c on
+     white at 1.9:1 (test/a11y.test.ts). Static: no hover, no press. */
+  .site-description {
+    display: inline-block;
+    /* 14 above, 8 below (owner pick 2026-09-03, option B of three):
+       the box sits as its own element between the title and the nav
+       band rather than as a subtitle stuck to the title. */
+    margin: 14px 0 8px;
+    padding: 6px 14px;
+    border: var(--stroke) solid var(--accent-1);
+    color: var(--accent-1-ink);
+    background-color: color-mix(in srgb, var(--accent-1) 6%, var(--surface));
+  }
+  /* Bottom band straddles the bottom rule. */
+  .masthead-nav {
+    position: relative;
+    margin-bottom: calc(-30px + (-17px));
+  }
+  .header-nav-search {
+    width: 100%;
+    display: flex;
+    gap: 20px;
+    align-items: center;
+    justify-content: space-between;
+  }
+  .main-navigation .menu {
+    list-style: none;
+    padding: 0;
+    margin: 0;
+    display: flex;
+    gap: 10px;
+    flex-wrap: wrap;
+    font-size: var(--font-size-sm);
+  }
+  /* Box, ink, and press feedback from .press-box; the nav's own size,
+     case, and hover ring are here. */
+  .main-navigation .menu a {
+    padding: 7px 15px;
+    text-transform: uppercase;
+    font-weight: bold;
+    display: block;
+  }
+  .menu-item { position: relative; }
+  .current-menu-item > a { --tint-opacity: 0.2; }
+  .main-navigation .menu a:hover { outline: var(--stroke) solid var(--rule); }
+  .menu-toggle { display: none; }
+  @media (--bp-sidebar) {
+    .menu-toggle {
+      display: block;
+      width: 35px;
+      height: 35px;
+      position: relative;
+      cursor: pointer;
+      padding: 0;
+      margin: 5px;
+      border: var(--stroke) solid var(--rule);
+      background-color: var(--surface);
+    }
+    .menu-toggle span:not(.screen-reader-text) {
+      display: block;
+      position: absolute;
+      height: 3px;
+      width: calc(100% - 10px);
+      background: var(--ink);
+      border-radius: 3px;
+      left: 50%;
+      transform: translateX(-50%);
+    }
+    .menu-toggle span:nth-child(1) { top: 7px; }
+    .menu-toggle span:nth-child(2) { top: 14px; }
+    .menu-toggle span:nth-child(3) { top: 21px; }
+    /* The open menu is a pop-out under the hamburger, floating over the
+       page like the search flyout (same z tier), not a block that grows
+       the header (owner request 2026-08-27, after launch). The header
+       keeps its height, so the band keeps its desktop straddle of the
+       bottom rule: hamburger, toggle, and magnifier hang off the rule
+       instead of sitting inside the frame. */
+    .main-navigation { position: relative; }
+    .main-navigation .menu {
+      display: none;
+      flex-direction: column;
+      position: absolute;
+      top: calc(100% + 6px);
+      left: 0;
+      min-width: 220px;
+      padding: 10px;
+      z-index: var(--z-search-flyout);
+      background-color: var(--surface);
+      border: var(--stroke) solid var(--rule);
+      box-shadow: var(--shadow);
+    }
+    .main-navigation .menu.open { display: flex; }
+  }
+  /* Phone-width header simplification (owner call 2026-08-20): the
+     date box competes for pixels a phone already spends on its own
+     clock, and the social tray collided with it. Both retire; the
+     socials' job moves to the Contact page, one hamburger tap away. */
+  @media (--bp-phone) {
+    .masthead-top { display: none; }
+  }
+  /* Search flyout: icon on a primary-filled box, form revealed on focus-within
+     (the live theme toggles a .show class with jQuery; focus-within needs no script). */
+  .navigation-search { width: 30px; position: relative; display: inline-block; text-align: center; }
+  .navigation-search-form {
+    position: absolute;
+    right: 0;
+    opacity: 0;
+    visibility: hidden;
+    top: 100%;
+    width: 325px;
+    padding: 14px;
+    z-index: var(--z-search-flyout);
+    background-color: var(--surface);
+    border: var(--stroke) solid var(--rule);
+    transition: var(--transition);
+  }
+  .navigation-search-wrap:focus-within .navigation-search-form {
+    opacity: 1;
+    visibility: visible;
+  }
+  /* Form anatomy comes from the .field-join house pattern (owner request
+     2026-07-30, replacing the live theme's 75/25 split form). Only the
+     label wrapper's sizing is contextual. */
+  .search-form label { flex: 1; }
+  .search-form .search-field { width: 100%; }
+</style>
+<script>
+  import { mountSiteHeader } from "../scripts/site-header";
+  mountSiteHeader(document);
+</script>

package/src/components/SmartImage.astro ADDED Viewed

@@ -0,0 +1,34 @@
+---
+import { Image } from "astro:assets";
+import type { ImageMetadata } from "astro";
+/* The one responsive-image element (step 5, 2026-08-30). GIFs pass
+   through untouched (conversion drops animation) and SVGs need no
+   rasterizing; everything else gets responsive widths + modern formats
+   (audit D5). Callers pick widths/sizes for their column; omitting
+   `widths` renders at intrinsic size (MediaText's natural mode, where a
+   `sizes` attribute would defeat natural-size rendering). No scoped CSS
+   on purpose: styling stays with the caller and the global pattern
+   files, which keep reaching the img because this component adds no
+   scope of its own. */
+interface Props {
+  src: ImageMetadata;
+  alt: string;
+  class?: string;
+  widths?: number[];
+  sizes?: string;
+  loading?: "lazy" | "eager";
+  fetchpriority?: "high";
+  style?: string;
+}
+const { src, alt, class: className, widths, sizes, loading = "lazy", fetchpriority, style } = Astro.props;
+const passthrough = src.format === "gif" || src.format === "svg";
+/* eager is the img element's default; omitting it keeps the passthrough
+   markup byte-compatible with the pre-step-5 sites. */
+const imgLoading = loading === "eager" ? undefined : loading;
+---
+{passthrough
+  ? <img src={src.src} width={src.width} height={src.height} alt={alt} class={className} loading={imgLoading} style={style} fetchpriority={fetchpriority} />
+  : widths
+    ? <Image src={src} widths={widths} sizes={sizes} alt={alt} class={className} loading={loading} style={style} fetchpriority={fetchpriority} />
+    : <Image src={src} width={src.width} alt={alt} class={className} loading={loading} style={style} fetchpriority={fetchpriority} />}

package/src/components/Subscribe.astro ADDED Viewed

@@ -0,0 +1,117 @@
+---
+/* Newsletter CTA, lifted from the BEADZ Subscribe island: the shared amber
+   block that bridges every project back to this blog, meant to read the
+   same everywhere it appears. Rebuilt as a no-React Astro component with
+   the copy in the blog's own voice (the deadpan BEADZ register stays on
+   BEADZ). Three variants: "sidebar" sits above Recent Posts, "post" sits
+   between a post's end and the prev/next navigation, "page" is the block
+   on /newsletter/ itself (the sidebar heading with the post blurb, no
+   outer margins; the page's own prose introduces it).
+   The form posts straight to Buttondown's keyless embed-subscribe
+   endpoint. It is a real form (method + action) so it works with no
+   JavaScript: Buttondown redirects that path to /newsletter/subscribed/.
+   With JavaScript, src/scripts/subscribe.ts takes over the submit and
+   writes the outcome into the status line. Spec:
+   docs/superpowers/specs/2026-08-16-mailing-list-wiring-design.md
+   Copy is overridable (step 9.5): title, blurb, and fine print are named
+   slots whose fallbacks are the blog's register; placeholder and button
+   label are props. Another register (BEADZ) overrides without forking. */
+interface Props {
+  variant?: "sidebar" | "post" | "page";
+  headingLevel?: 2 | 3 | 4;
+  class?: string;
+  /* The provider's form-post endpoint; the blog passes config NEWSLETTER.
+     Required so a caller can never render a form that posts nowhere. */
+  action: string;
+  /* Human sign-up page, named in the failure message (data-public-url). */
+  publicUrl?: string;
+  placeholder?: string;
+  buttonLabel?: string;
+}
+const {
+  variant = "post", headingLevel = 2, class: className,
+  action, publicUrl,
+  placeholder = "you@somewhere.tld", buttonLabel = "Subscribe",
+} = Astro.props;
+/* Annotated, not cast: an `as` cast in the frontmatter can make the Astro
+   compiler drop the Props type (see PostCard.astro). */
+const Heading: "h2" | "h3" | "h4" = `h${headingLevel}`;
+---
+<section class:list={["subscribe", `subscribe-${variant}`, className]}>
+  <Heading class="subscribe-title"><slot name="title">{variant === "post" ? "Plenty more where this came from" : "Join the Mailing List"}</slot></Heading>
+  {variant === "sidebar" ? (
+    <p class="subscribe-blurb"><slot name="blurb">An email when something new goes up.</slot></p>
+  ) : (
+    <p class="subscribe-blurb"><slot name="blurb">If you want to hear when a new post or project goes up, leave an email
+      and I'll send a note. No schedule, no spam.</slot></p>
+  )}
+  <form class="subscribe-form field-join" method="post" action={action} data-public-url={publicUrl} novalidate>
+    <input type="hidden" name="embed" value="1" />
+    <input class="subscribe-email field-join-input" type="email" name="email" placeholder={placeholder} aria-label="Email address" required />
+    <button class="subscribe-submit field-join-button press-box press-box-shaded" type="submit">{buttonLabel}</button>
+  </form>
+  <p class="subscribe-fine"><slot name="fine-print">Double opt-in. Every email has an <a href="/policies/mailing-list/">unsubscribe link</a>.</slot></p>
+  <p class="subscribe-status" role="status"></p>
+</section>
+<script>
+  import { mountSubscribe } from "../scripts/subscribe";
+  mountSubscribe(document);
+</script>
+<style>
+  /* The BEADZ signature double rule (border plus inset outline), at this
+     blog's standard 2px stroke rather than BEADZ's 3px. Every color is a
+     --panel-* role: amber ground with warm-dark rule and button by day,
+     dark ground with amber rule and button by night, so the call to
+     action is the brightest element in the block either way. outline-offset
+     stays -10px; it is a design constant of the double rule. */
+  .subscribe {
+    background: var(--panel-bg);
+    color: var(--panel-ink);
+    border: var(--stroke) solid var(--panel-rule);
+    outline: var(--stroke) solid var(--panel-rule);
+    outline-offset: -10px;
+  }
+  .subscribe-post { padding: 30px; margin-top: 30px; }
+  .subscribe-sidebar { padding: 24px 22px; margin-bottom: 40px; }
+  .subscribe-page { padding: 30px; }
+  .subscribe-title {
+    margin: 0 0 8px;
+    font-family: var(--font-body);
+    line-height: 1.2;
+  }
+  .subscribe-post .subscribe-title,
+  .subscribe-page .subscribe-title { font-size: var(--font-size-md); }
+  .subscribe-sidebar .subscribe-title { font-size: var(--font-size-base); }
+  .subscribe-blurb { margin: 0 0 16px; font-size: var(--font-size-sm); }
+  /* Form anatomy, focus rings, and press feedback all come from the
+     .field-join pattern (patterns.css, house rule 2026-07-30, settled
+     after trying inset and side-by-side variants); this island only sets
+     the pattern's field knobs to its panel roles. The button takes none:
+     it is the house shaded press box, the same on the panel as anywhere. */
+  .subscribe-form {
+    --field-ink: var(--panel-rule);
+    --field-text: var(--panel-ink);
+    /* The email box's click highlight is the panel's own (ink on the
+       amber by day, amber by night); the keyboard ring stays the site's
+       everywhere in the panel (owner rule 2026-08-26). */
+    --field-ring: var(--panel-ring);
+    /* The well is the page surface, so it sits a step below the panel in
+       both themes (white on amber by day, black on the dark panel by night). */
+    --field-well: var(--surface);
+  }
+  .subscribe-post .subscribe-form,
+  .subscribe-page .subscribe-form { max-width: 520px; }
+  /* Fine print sits between form and status so an error line never
+     shoves it around; the link inherits the block's ink. Owner wanted it
+     smaller than the status line (2026-08-16); xs is the scale's floor,
+     so this steps below it off the token rather than hardcoding a size. */
+  .subscribe-fine { margin: 10px 0 0; font-size: calc(var(--font-size-xs) * 0.88); }
+  .subscribe-fine a { color: inherit; }
+  .subscribe-status { margin: 10px 0 0; font-size: var(--font-size-xs); font-weight: 700; }
+  .subscribe-status:empty { display: none; }
+  .subscribe-status-err { color: var(--panel-error); }
+</style>

package/src/components/ThemeToggle.astro ADDED Viewed

@@ -0,0 +1,41 @@
+---
+/* Day/night toggle (owner request 2026-08-25): an .icon-box button that
+   flips the site theme. Both glyphs are in the button; CSS shows the
+   current theme's (sun by day, moon by night, owner call 2026-08-26) and
+   the label names the action. State and storage live in
+   scripts/theme-toggle.ts, which mounts every .theme-toggle on the page
+   and keeps them in step; the first paint is stamped by the inline
+   script in Shell.astro's head.
+   Two placements: "band" sits beside the date stamp in the header's top
+   band; "phone" sits beside the search icon in the bottom band and shows
+   only under 768px, where the top band is hidden (owner call 2026-08-20),
+   so phones keep a toggle (owner request 2026-08-26). */
+import { ICON_SUN, ICON_MOON } from "../scripts/core/icons";
+interface Props { placement?: "band" | "phone"; class?: string; label?: string }
+const { placement = "band", class: className, label = "Switch to dark mode" } = Astro.props;
+---
+<button type="button" class:list={["theme-toggle", "icon-box", placement === "phone" && "theme-toggle-phone", className]} aria-label={label} aria-pressed="false">
+  <span class="theme-toggle-moon"><Fragment set:html={ICON_MOON} /></span>
+  <span class="theme-toggle-sun"><Fragment set:html={ICON_SUN} /></span>
+</button>
+<style>
+  .theme-toggle { font-size: 16px; }
+  .theme-toggle span { display: block; line-height: 0; }
+  /* The glyphs keep their currentColor stroke and take a fill: the moon
+     in the second accent, the sun's disc in the first (owner call
+     2026-08-26). :global because the svg arrives through set:html. */
+  .theme-toggle-moon :global(path) { fill: var(--accent-2); }
+  .theme-toggle-sun :global(circle) { fill: var(--accent-1); }
+  /* Show the glyph of the current theme. Both selectors carry the
+     parent class so they outrank the span rule above. */
+  .theme-toggle .theme-toggle-moon { display: none; }
+  :global(:root[data-theme="dark"]) .theme-toggle .theme-toggle-moon { display: block; }
+  :global(:root[data-theme="dark"]) .theme-toggle .theme-toggle-sun { display: none; }
+  /* The phone placement exists only where the top band does not. */
+  .theme-toggle-phone { display: none; }
+  @media (--bp-phone) {
+    .theme-toggle-phone { display: flex; }
+  }
+</style>

package/src/components/TwoColumn.astro ADDED Viewed

@@ -0,0 +1,12 @@
+---
+/* The two-column page body (step 8, 2026-08-30): content beside the
+   sidebar slot. Column grid, widths, and the collapse live once in
+   styles/base/shell.css; this component is structure only, so it ships
+   no scoped CSS and stamps no cid on the markup. */
+interface Props { class?: string }
+const { class: className } = Astro.props;
+---
+<div class:list={["two-column", className]}>
+  <main class="site-main"><slot /></main>
+  <slot name="aside" />
+</div>