@half-built/astro 0.9.0 → 0.11.0

package/src/components/ThemeToggle.astro

@@ -23,7 +23,6 @@ const {
     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>

package/src/components/TwoColumn.astro

@@ -1,12 +1,14 @@
 ---
 interface Props {
   class?: string;
+  mainTag?: "main" | "div";
 }
 
-const { class: className } = Astro.props;
+const { class: className, mainTag = "main" } = Astro.props;
+const Main = mainTag;
 ---
 
 <div class:list={["two-column", className]}>
-  <main class="site-main"><slot /></main>
+  <Main class="site-main"><slot /></Main>
   <slot name="aside" />
 </div>

package/src/components/content/BlogImage.astro

@@ -68,7 +68,6 @@ const {
   .blog-image :global(img) { max-width: 100%; height: auto; display: block; margin-inline: auto; }
   .blog-image-narrow :global(.lightbox-link) { max-width: min(495px, 100%); }
 
-  /* Type from the .caption pattern. Fidelity pass (handoff 5.5): live
-     figcaptions are centered. */
+  /* Type from the .caption pattern; figcaptions are centered. */
   figcaption { margin-top: 5px; text-align: center; }
 </style>

package/src/components/content/PostLink.astro

@@ -1,15 +1,22 @@
 ---
-import { resolvePostHref, type Linkable } from "../../lib/drafts";
+import { postLinkHref, type Linkable } from "../../lib/drafts";
 
 interface Props {
   slug: string;
   posts: Linkable[];
+  showDrafts?: boolean;
   tip?: string;
   class?: string;
 }
 
-const { slug, posts, tip, class: className } = Astro.props;
-const href = resolvePostHref(slug, posts);
+const { slug, posts, showDrafts = false, tip, class: className } = Astro.props;
+const href = postLinkHref(slug, posts, showDrafts);
 ---
 
-<a href={href} data-tooltip={tip} class={className}><slot /></a>
+{href ? (
+  <a href={href} data-tooltip={tip} class={className}>
+    <slot />
+  </a>
+) : (
+  <slot />
+)}

package/src/components/content/WhenPublished.astro

@@ -11,4 +11,4 @@ const { slug, posts, showDrafts = false } = Astro.props;
 const visible = forwardLinkVisible(slug, posts, showDrafts);
 ---
 
-{visible && <slot />}
+{visible ? <slot /> : <slot name="fallback" />}

package/src/components/models.ts

@@ -32,12 +32,13 @@ export interface LinkListItem {
 }
 
 /* Chrome view-models (step 9.5, 2026-08-31): the header renders site
-   identity it is handed, never the blog's config. NavItem is the shape
-   config.ts's NAV already had; it moved here so the component and the
-   site share one definition without the component importing site code.
-   SocialItem carries its icon as inline SVG markup: the site's registry
-   (social-icons.ts, including the Henry portfolio glyph that stays out
-   of the package) is a lookup the caller performs, not the component. */
+   identity it is handed, never a consumer's own config. NavItem is the
+   shape a consumer's own site navigation config already used; it moved
+   here so the component and the site share one definition without the
+   component importing site code. SocialItem carries its icon as inline
+   SVG markup: a site's own icon registry (including any site-specific
+   brand glyphs that stay out of the package) is a lookup the caller
+   performs, not the component. */
 export interface NavItem {
   label: string;
   href: string;
@@ -51,10 +52,10 @@ export interface SocialItem {
   icon: string;
 }
 
-/* Footer view-models (step 9.5). These are the interfaces config.ts's
-   footer-sitemap comment always called "the future component-library
-   schema"; this is that move. The blog's data (FOOTER_SITEMAP,
-   ECOSYSTEM) stays in config.ts. */
+/* Footer view-models (step 9.5). These are the interfaces a consumer's
+   own footer-sitemap comment called "the future component-library
+   schema"; this is that move. A consumer's own footer data stays in its
+   own config, not here. */
 export interface SitemapLink {
   label: string;
   href: string;

package/src/lib/drafts.ts

@@ -43,17 +43,21 @@ export function forwardLinkVisible(
 /* Post links by slug. A hand-typed post URL bakes in the target's date,
    so a re-dated draft silently breaks every earlier link to it. The
    PostLink content component resolves the slug through postPath() at
-   build time instead. It resolves drafts too, and must: Astro renders
-   MDX slot children eagerly, so a PostLink inside a hidden WhenPublished
-   still runs (learned the hard way 2026-08-24). The deploy-build guard
-   against a bare link to a draft is therefore a test, not a throw here:
-   test/post-link.test.ts asserts no draft slug appears in any built
-   page. Unknown slugs throw for the same reason forwardLinkVisible's do. */
+   build time instead. postLinkHref() is its policy: a visible target
+   gets its href, a hidden one gets null and the component renders its
+   text with no link (owner decision 2026-09-26), so a draft's name can
+   sit in published prose and becomes a link on its own when the draft
+   ships. resolvePostHref() still resolves drafts: consumers use it for
+   lookups keyed by href, and Astro renders MDX slot children eagerly,
+   so a PostLink inside a hidden WhenPublished still runs. The
+   deploy-build guard against a link to a draft stays a consumer test
+   (no draft slug in any built page). Unknown slugs throw for the same
+   reason forwardLinkVisible's do. */
 
 import { postPath } from "./slug";
 
 export interface Linkable {
-  data: { slug: string; date: Date };
+  data: { slug: string; date: Date; draft?: boolean };
 }
 
 export function resolvePostHref(slug: string, posts: Linkable[]): string {
@@ -61,3 +65,14 @@ export function resolvePostHref(slug: string, posts: Linkable[]): string {
   if (!target) throw new Error(`PostLink: no post has slug "${slug}"`);
   return postPath(target);
 }
+
+export function postLinkHref(
+  slug: string,
+  posts: Linkable[],
+  showDrafts: boolean,
+): string | null {
+  const target = posts.find((p) => p.data.slug === slug);
+  if (!target) throw new Error(`PostLink: no post has slug "${slug}"`);
+  if (target.data.draft && !showDrafts) return null;
+  return resolvePostHref(slug, posts);
+}

package/src/lib/excerpt.ts

@@ -1,6 +1,6 @@
 /* Card text derived from a post body (owner call 2026-09-13; the rule
-   is recorded in the blog's docs/superpowers/specs/2026-09-13-derived-excerpts-design.md
-   and summarized in this package's README, "Derived excerpts"). The
+   was settled at the blog and is summarized in this package's README,
+   "Derived excerpts"). The
    card is the opening prose, consecutive paragraphs joined, cut at a
    word boundary within EXCERPT_LIMIT and always ended with an
    ellipsis, so every listing samples the post's own opening and the

package/src/lib/format-date.ts

@@ -1,7 +1,7 @@
 /* Package lib (step 11.2): the post date formatter, split from
-   post-display.ts so the package's formatDate never drags the Henry
-   placeholder along. Locale parameterized for N sites; en-US is the
-   house default. */
+   post-display.ts so the package's formatDate never drags a
+   site-specific placeholder along. Locale parameterized for N sites;
+   en-US is the house default. */
 export function formatPostDate(d: Date, locale = "en-US"): string {
   return d.toLocaleDateString(locale, {
     year: "numeric",

package/src/lib/header-date.ts

@@ -1,6 +1,6 @@
 /* The masthead date box: "25, Aug 2026", the live theme's format. Rendered
    at build time as the no-JS fallback (SiteHeader.astro) and refreshed on
-   load by Base.astro's script, from this one definition. */
+   load by the consumer's layout script, from this one definition. */
 export function formatHeaderDate(now: Date): string {
   return `${now.getDate()}, ${now.toLocaleDateString("en-US", { month: "short" })} ${now.getFullYear()}`;
 }

package/src/lib/ordering.ts

@@ -1,9 +1,10 @@
 /* Publication-time ordering, pure and framework-free so it is unit-testable.
    Single source of truth for a post's publication instant: `date` is the
-   date-only permalink field; `published` carries the full WP timestamp when
-   the migrator knew it. Every consumer (sorting, feeds, display) must go
-   through these instead of picking fields ad hoc: hand-picked fields are how
-   the same-day ordering bug shipped twice (audit A1/A2). */
+   date-only permalink field; `published` carries the full source timestamp
+   when a consumer's import knew it. Every consumer (sorting, feeds,
+   display) must go through these instead of picking fields ad hoc:
+   hand-picked fields are how the same-day ordering bug shipped twice
+   (audit A1/A2). */
 
 export interface Publishable {
   data: { date: Date; published?: Date };

package/src/scripts/code-island.ts

@@ -3,8 +3,8 @@ import { docOf } from "./core/dom";
 
 /* Code island decorator: builds the header bar (filename/language label +
    copy button) above every fenced block in article content. Runs client-side
-   from Base.astro; extracted to a module so the DOM behavior is testable
-   under jsdom (a phase-1 carry-over closed 2026-07-28). */
+   from the consumer's layout; extracted to a module so the DOM behavior is
+   testable under jsdom (a phase-1 carry-over closed 2026-07-28). */
 /* Island contract (step 9): mount(root, options?) returns a destroy handle;
    claim() makes a second mount over the same pre a no-op. */
 export interface CodeIslandOptions {
@@ -25,18 +25,22 @@ export const mountCodeIslands: Island<CodeIslandOptions> = (
 
   const doc = docOf(root);
 
-  /* resetTimer holds the copy-reset setTimeout id, one live per button at
-     most (a second click before the first reset overwrites it, dropping
-     the earlier timer's reference so it can no longer be cleared, which
-     is why doCopy clears the box before replacing it). A plain mutable
-     box, not a field on the mounted entry, so both doCopy and destroy()
-     close over the same cell. */
+  /* timers holds the two pending setTimeout ids per button: the queued
+     status announcement and the label reset, one live each at most (a
+     second click before either fires overwrites its id, dropping the
+     earlier reference so it can no longer be cleared, which is why doCopy
+     clears each before replacing it). A plain mutable box, not a field on
+     the mounted entry, so both doCopy and destroy() close over the same
+     cells and destroy() can cancel both. */
   const mounted: {
     pre: Element;
     bar: HTMLDivElement;
     btn: HTMLButtonElement;
     onClick: () => void;
-    resetTimer: { id: ReturnType<typeof setTimeout> | undefined };
+    timers: {
+      announce: ReturnType<typeof setTimeout> | undefined;
+      reset: ReturnType<typeof setTimeout> | undefined;
+    };
   }[] = [];
 
   for (const pre of root.querySelectorAll(selector)) {
@@ -45,6 +49,13 @@ export const mountCodeIslands: Island<CodeIslandOptions> = (
     bar.className = "code-island-bar";
     const label = doc.createElement("span");
 
+    /* Visually the button's own text already shows the outcome, but a
+       screen reader is not sat watching the button: role="status" gets
+       the outcome announced as a live region without moving focus. */
+    const status = doc.createElement("span");
+    status.className = "screen-reader-text";
+    status.setAttribute("role", "status");
+
     const file = pre
       .closest("[data-code-filename]")
       ?.getAttribute("data-code-filename");
@@ -56,22 +67,41 @@ export const mountCodeIslands: Island<CodeIslandOptions> = (
     btn.type = "button";
     btn.textContent = copy.copy;
 
-    const resetTimer: { id: ReturnType<typeof setTimeout> | undefined } = {
-      id: undefined,
-    };
+    const timers: {
+      announce: ReturnType<typeof setTimeout> | undefined;
+      reset: ReturnType<typeof setTimeout> | undefined;
+    } = { announce: undefined, reset: undefined };
 
     const doCopy = async (): Promise<void> => {
+      /* Cleared synchronously, before the outcome is known, so a repeat
+         copy inside the reset window is a real DOM change rather than
+         the same string written over itself. Setting the outcome text
+         itself waits one tick (below) so the clear is its own observable
+         step; a live region that never changes never gets announced. */
+      status.textContent = "";
+
+      let outcome: string;
+
       try {
         await navigator.clipboard.writeText(pre.textContent);
         btn.textContent = copy.copied;
+        outcome = copy.copied;
       } catch {
         btn.textContent = copy.failed;
+        outcome = copy.failed;
       }
 
-      clearTimeout(resetTimer.id);
+      clearTimeout(timers.announce);
+
+      timers.announce = setTimeout(() => {
+        status.textContent = outcome;
+      }, 0);
+
+      clearTimeout(timers.reset);
 
-      resetTimer.id = setTimeout(() => {
+      timers.reset = setTimeout(() => {
         btn.textContent = copy.copy;
+        status.textContent = "";
       }, resetMs);
     };
 
@@ -80,16 +110,17 @@ export const mountCodeIslands: Island<CodeIslandOptions> = (
     };
 
     btn.addEventListener("click", onClick);
-    bar.append(label, btn);
+    bar.append(label, btn, status);
     pre.before(bar);
-    mounted.push({ pre, bar, btn, onClick, resetTimer });
+    mounted.push({ pre, bar, btn, onClick, timers });
   }
 
   return {
     destroy(): void {
-      for (const { pre, bar, btn, onClick, resetTimer } of mounted) {
+      for (const { pre, bar, btn, onClick, timers } of mounted) {
         btn.removeEventListener("click", onClick);
-        clearTimeout(resetTimer.id);
+        clearTimeout(timers.announce);
+        clearTimeout(timers.reset);
         bar.remove();
         release(pre, "code");
       }

package/src/scripts/core/frame-loop.ts

@@ -1,10 +1,15 @@
-/* The rAF loop with dt clamp (step 10), one home for the pattern
-   henry-loose.ts and path-player.ts each carried. now is the rAF
+/* The rAF loop with dt clamp (step 10), one home for a pattern that
+   used to be scattered across the site's own scripts and path-player.ts.
+   now is the rAF
    timestamp: monotonic in a real browser, unlike Date.now(), which a
    wall-clock adjustment can move backward; the max(0, ...) floor is
    cheap belt-and-suspenders against that case feeding an integrator a
    negative dt. stop() resets the clock so a stop/start gap (a hidden
-   tab, a closed dialog) never arrives as one giant dt. */
+   tab, a closed dialog) never arrives as one giant dt. A stop, a
+   start, or both called reentrantly from inside cb keep exactly one
+   scheduled chain: each generation is stamped at schedule time, and a
+   tick from a stale generation is dropped instead of rescheduling
+   itself alongside the newer chain. */
 export interface FrameLoop {
   start(): void;
   stop(): void;
@@ -20,21 +25,25 @@ export function createFrameLoop(
   let handle = 0;
   let last = 0;
   let live = false;
+  let gen = 0;
 
-  function tick(now: number): void {
-    if (!live) return;
+  function tick(now: number, mine: number): void {
+    if (!live || mine !== gen) return;
 
     const elapsed = Math.max(0, (now - last) / 1000);
     const dt = last === 0 ? firstDt : Math.min(clamp, elapsed);
 
     last = now;
     cb(dt);
-    // cb may have called stop() reentrantly; a fresh function body reads live without stale narrowing.
-    scheduleNext();
-  }
 
-  function scheduleNext(): void {
-    if (live) handle = win.requestAnimationFrame(tick);
+    // cb may have called stop() and/or start() reentrantly; gen moves
+    // on either call, so mine still matching gen here already means
+    // this chain is still the live one.
+    if (mine === gen) {
+      handle = win.requestAnimationFrame((now2) => {
+        tick(now2, mine);
+      });
+    }
   }
 
   return {
@@ -42,11 +51,17 @@ export function createFrameLoop(
       if (live) return;
       live = true;
       last = 0;
-      handle = win.requestAnimationFrame(tick);
+      gen++;
+      const mine = gen;
+
+      handle = win.requestAnimationFrame((now) => {
+        tick(now, mine);
+      });
     },
     stop(): void {
       if (!live) return;
       live = false;
+      gen++;
       win.cancelAnimationFrame(handle);
       last = 0;
     },

package/src/scripts/core/icons.ts

@@ -1,7 +1,7 @@
 /* Inline icon markup, vendored from Lucide (https://lucide.dev, ISC
    license), replacing the Unicode glyphs whose rendering varied by
    platform font. Same line style as the site's existing inline SVGs
-   (the to-top chevron in Base.astro). Buttons carry their own
+   (the to-top chevron in the consumer's layout). Buttons carry their own
    aria-labels; the svg itself is decorative and aria-hidden.
    Home: the js package's core (owner decision 1, 2026-08-31); Lucide,
    ISC license, attribution retained. */
@@ -98,7 +98,6 @@ export function iconMarkup(
 
 export const ICON_X = iconMarkup("x");
 export const ICON_PLAY = iconMarkup("play");
-export const ICON_SPARKLES = iconMarkup("sparkles");
 export const ICON_PAUSE = iconMarkup("pause");
 export const ICON_ROTATE_CCW = iconMarkup("rotate-ccw");
 export const ICON_CHEVRON_LEFT = iconMarkup("chevron-left");

package/src/scripts/core/placement.ts

@@ -0,0 +1,67 @@
+/* Pure placement shared by the measured islands (link-tip, popout;
+   spec docs/superpowers/specs/2026-09-26-popout-design.md moved it
+   here from link-tip.ts). Measure then place, never predict. */
+
+const GAP = 1; /* px between anchor and tip; the old bottom: calc(100% + 1px) */
+const INSET = 2; /* px of horizontal lead-out past the anchor edge */
+
+export const EDGE = 12; /* px of breathing room against either viewport edge */
+
+export type TipPlace = "above" | "below";
+export type TipAlign = "start" | "end";
+export interface AnchorRect {
+  left: number;
+  right: number;
+  top: number;
+  bottom: number;
+}
+export interface TipSize {
+  width: number;
+  height: number;
+}
+export interface ViewportSize {
+  width: number;
+  height: number;
+}
+export interface TipPosition {
+  x: number;
+  y: number;
+  place: TipPlace;
+}
+
+/* Pure placement for the singleton tip: start/end alignment against
+   the anchor, horizontal clamp into [edge, vw - edge] with the left
+   edge winning when both bind, and a vertical flip when the preferred
+   side would leave the viewport. All measured values; no prediction. */
+export function placeTip(
+  anchor: AnchorRect,
+  tip: TipSize,
+  viewport: ViewportSize,
+  place: TipPlace = "above",
+  align: TipAlign = "start",
+  edge: number = EDGE,
+): TipPosition {
+  const startX = anchor.left - INSET;
+  const endX = anchor.right + INSET - tip.width;
+  let x = align === "start" ? startX : endX;
+
+  const overRight = x + tip.width - (viewport.width - edge);
+  if (overRight > 0) x -= overRight;
+  if (x < edge) x = edge;
+  let finalPlace = place;
+
+  if (place === "above" && anchor.top - GAP - tip.height < 0) {
+    finalPlace = "below";
+  }
+
+  if (place === "below" && anchor.bottom + GAP + tip.height > viewport.height) {
+    finalPlace = "above";
+  }
+
+  const y =
+    finalPlace === "above"
+      ? anchor.top - GAP - tip.height
+      : anchor.bottom + GAP;
+
+  return { x: Math.round(x), y: Math.round(y), place: finalPlace };
+}

package/src/scripts/core/storage.ts

@@ -1,5 +1,6 @@
 /* The localStorage read/validate/write codec (step 10), one home for
-   the pattern henry-loose.ts and stasis-state.ts each carried: parse is
+   a pattern that used to be scattered across the site's own scripts:
+   parse is
    the validator (junk parses to null and read() then removes the key),
    and every storage touch sits inside try/catch so private mode or
    disabled storage degrades to in-page-only state, never a thrown

package/src/scripts/ecosystem.ts

@@ -68,7 +68,12 @@ export function validateDocument(raw: unknown): EcosystemDocument | null {
 
 /** The self entry's family first, each group by ascending priority and
     then label, capped at limit. Null when selfKey is absent, which is
-    the refusal that keeps a site out of a list missing itself. */
+    the refusal that keeps a site out of a list missing itself.
+
+    The self entry always survives the cap: a footer that would render
+    the cap without the site's own entry is worse than one that swaps
+    out its lowest-priority stranger, so the self entry takes the last
+    slot when sorting alone would have dropped it past the limit. */
 export function sortEntries(
   entries: EcosystemDocEntry[],
   selfKey: string,
@@ -77,15 +82,18 @@ export function sortEntries(
   const self = entries.find((entry) => entry.key === selfKey);
   if (!self) return null;
   const own = self.family;
-  return [...entries]
-    .sort((a, b) => {
-      const aOwn = a.family === own ? 0 : 1;
-      const bOwn = b.family === own ? 0 : 1;
-      if (aOwn !== bOwn) return aOwn - bOwn;
-      if (a.priority !== b.priority) return a.priority - b.priority;
-      return a.label.localeCompare(b.label);
-    })
-    .slice(0, limit);
+
+  const sorted = [...entries].sort((a, b) => {
+    const aOwn = a.family === own ? 0 : 1;
+    const bOwn = b.family === own ? 0 : 1;
+    if (aOwn !== bOwn) return aOwn - bOwn;
+    if (a.priority !== b.priority) return a.priority - b.priority;
+    return a.label.localeCompare(b.label);
+  });
+
+  const capped = sorted.slice(0, limit);
+  if (limit > 0 && !capped.includes(self)) capped[capped.length - 1] = self;
+  return capped;
 }
 
 const CACHE_KEY = "half-built-ecosystem";

package/src/scripts/focus-mode.ts

@@ -15,11 +15,41 @@ export interface FocusModeOptions {
   target?: EventTarget;
 }
 
+/* Text entry is not navigation: a reader who clicked into a field and
+   types keeps the click highlight. Tab always means keyboard. */
+function isTextEntry(t: EventTarget | null): boolean {
+  if (!(t instanceof HTMLElement)) return false;
+
+  if (
+    t.isContentEditable ||
+    t instanceof HTMLTextAreaElement ||
+    t instanceof HTMLSelectElement
+  ) {
+    return true;
+  }
+
+  if (!(t instanceof HTMLInputElement)) return false;
+
+  return ![
+    "checkbox",
+    "radio",
+    "button",
+    "submit",
+    "reset",
+    "range",
+    "color",
+    "file",
+    "image",
+  ].includes(t.type);
+}
+
 export const mountFocusMode: Island<FocusModeOptions> = (
   root,
   options = {},
 ): IslandHandle => {
-  const el = root as HTMLElement;
+  const el =
+    root instanceof Document ? root.documentElement : (root as HTMLElement);
+
   const target = options.target ?? window;
 
   if (!claim(el, "focus-mode")) {
@@ -31,7 +61,9 @@ export const mountFocusMode: Island<FocusModeOptions> = (
     };
   }
 
-  const onKeydown = (): void => {
+  const onKeydown = (ev: Event): void => {
+    if (!(ev instanceof KeyboardEvent)) return;
+    if (ev.key !== "Tab" && isTextEntry(ev.target)) return;
     el.dataset.focus = "keyboard";
   };