@half-built/astro 0.4.2 → 0.6.0

package/src/components/content/Palette.astro

@@ -1,25 +1,31 @@
 ---
-/* Color-chip palette table, the treatment lifted from the BEADZ brand
-   page: bordered swatch, role, hex. Hand-authored-page component (the
-   migrator never emits it). Chip color is per-entry data, so it rides an
-   inline background-color, which the html-validate gate whitelists for
-   exactly this dynamic-value case.
-   An entry may carry `token` instead of `hex` (owner ask 2026-09-06,
-   the reference site's live token sheet): the chip then paints
-   var(token), following the live cascade with no script, and the hex
-   cell renders empty with data-token-hex for a consumer script to
-   fill from computed styles; the component itself stays inert. */
-interface Entry { role: string; hex?: string; token?: string; note?: string }
-interface Props { entries: Entry[]; class?: string; label?: string }
+interface Entry {
+  role: string;
+  hex?: string;
+  token?: string;
+  note?: string;
+}
+
+interface Props {
+  entries: Entry[];
+  class?: string;
+  label?: string;
+}
+
 const { entries, class: className, label = "Palette" } = Astro.props;
 ---
+
 {/* The scroll box is a tab stop with a name: below the column's width
     the table scrolls sideways, and a scrolling region a keyboard cannot
     reach fails WCAG 2.1.1 (axe scrollable-region-focusable). A named
     <section> is the region landmark natively; a div with role=region
     fails html-validate's prefer-native-element (the blog's gate caught
     it at the 0.4.0 pin bump). */}
-<section class:list={["table-scroll", className]} tabindex="0" aria-label={label}>
+<section
+  class:list={["table-scroll", className]}
+  tabindex="0"
+  aria-label={label}
+>
   <table class="palette">
     <thead>
       <tr>
@@ -30,14 +36,24 @@ const { entries, class: className, label = "Palette" } = Astro.props;
       </tr>
     </thead>
     <tbody>
-      {entries.map((e) => (
-        <tr>
-          <td><span class="palette-chip" aria-hidden="true" style={`background-color:${e.token ? `var(${e.token})` : e.hex}`}></span></td>
-          <td>{e.role}</td>
-          <td>{e.token ? <code data-token-hex={e.token}></code> : <code>{e.hex}</code>}</td>
-          <td>{e.note}</td>
-        </tr>
-      ))}
+      {entries.map((e) => <tr>
+        <td>
+          <span
+            class="palette-chip"
+            aria-hidden="true"
+            style={`background-color:${e.token ? `var(${e.token})` : e.hex}`}
+          ></span>
+        </td>
+        <td>{e.role}</td>
+        <td>
+          {e.token ? (
+            <code data-token-hex={e.token}></code>
+          ) : (
+            <code>{e.hex}</code>
+          )}
+        </td>
+        <td>{e.note}</td>
+      </tr>)}
     </tbody>
   </table>
 </section>

package/src/components/content/PostLink.astro

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

package/src/components/content/Quote.astro

@@ -1,18 +1,19 @@
 ---
-/* Attributed quote (spec 2026-08-14-quote-attribution-design.md).
-   Renders a plain blockquote so the boxed treatment in prose.css applies
-   unchanged; the provenance line is opt-in and most quotes should not
-   carry one (Nomenclature callouts and quotes already introduced by the
-   surrounding prose stay bare markdown). The tilde prefix stands in for
-   the traditional em dash, which is banned house-wide; the tilde is
-   already the site's separator (post titles). */
-interface Props { by?: string; when?: string; class?: string }
+interface Props {
+  by?: string;
+  when?: string;
+  class?: string;
+}
+
 const { by, when, class: className } = Astro.props;
 const attribution = [by, when].filter(Boolean).join(", ");
 ---
+
 <blockquote class:list={[className]}>
   <slot />
-  {attribution && <footer class="quote-attribution caption">~ {attribution}</footer>}
+  {attribution && <footer class="quote-attribution caption">
+    ~ {attribution}
+  </footer>}
 </blockquote>
 
 <style>

package/src/components/content/Spacer.astro

@@ -1,5 +1,14 @@
 ---
-interface Props { size?: number; class?: string }
+interface Props {
+  size?: number;
+  class?: string;
+}
+
 const { size = 40, class: className } = Astro.props;
 ---
-<div aria-hidden="true" style={`height:${size}px`} class:list={["spacer", className]}></div>
+
+<div
+  aria-hidden="true"
+  style={`height:${size}px`}
+  class:list={["spacer", className]}
+></div>

package/src/components/content/Step.astro

@@ -3,36 +3,49 @@ import type { ImageMetadata } from "astro";
 import SmartImage from "../SmartImage.astro";
 import LightboxLink from "../LightboxLink.astro";
 
-/* One row of a Walkthrough (spec
-   docs/superpowers/specs/2026-08-15-walkthrough-steps-design.md): photo(s)
-   on the left at a fixed 200px per photo, the author's prose beside at body
-   size. The prose is the step's text, not a caption; alt feeds the lightbox
-   caption. Below 600px the row stacks, photo centered above the prose. */
-interface Photo { src: ImageMetadata; alt?: string }
-/* Exactly one of `src` (with `alt`) or `images`: the union says so to
-   typed callers; the runtime check below says so to MDX. */
-type Props = ({ src: ImageMetadata; images?: never } | { src?: never; images: Photo[] }) & {
+interface Photo {
+  src: ImageMetadata;
+  alt?: string;
+}
+
+type Props = (
+  { src: ImageMetadata; images?: never } | { src?: never; images: Photo[] }
+) & {
   alt?: string;
   class?: string;
 };
+
 const { src, alt = "", images, class: className } = Astro.props;
 
 const hasSingle = src !== undefined;
 const hasMany = images !== undefined && images.length > 0;
+
 if (hasSingle === hasMany) {
-  throw new Error("Step: pass exactly one of `src` (with `alt`) or a non-empty `images` array");
+  throw new Error(
+    "Step: pass exactly one of `src` (with `alt`) or a non-empty `images` array",
+  );
 }
+
 const photos: Photo[] = hasMany ? images : [{ src: src as ImageMetadata, alt }];
 ---
+
 <li class:list={["step", className]}>
   <div class="step-media">
     {photos.map((p) => {
       const a = p.alt ?? "";
-      return (
-        <LightboxLink href={p.src.src} w={p.src.width} h={p.src.height} caption={a}>
-          <SmartImage src={p.src} alt={a} widths={[200, Math.min(p.src.width, 400)]} sizes="200px" />
-        </LightboxLink>
-      );
+      return <LightboxLink
+        href={p.src.src}
+        w={p.src.width}
+        h={p.src.height}
+        caption={a}
+      >
+        <SmartImage
+          src={p.src}
+          alt={a}
+          widths={[200, Math.min(p.src.width, 400)]}
+          sizes="200px"
+        />
+      </LightboxLink>;
     })}
   </div>
   <div class="step-body"><slot /></div>
@@ -44,11 +57,13 @@ const photos: Photo[] = hasMany ? images : [{ src: src as ImageMetadata, alt }];
     grid-template-columns: auto 1fr;
     gap: 20px;
     align-items: start;
+
     /* prose.css pads every .prose li; rows space themselves via
        the Walkthrough gap instead. */
     padding: 0;
     counter-increment: walkthrough-step;
   }
+
   /* Photos sit in a row, one 200px track each, so a two-photo step's cell
      is 410px and its prose starts further right (owner pick M3). The row
      does not wrap, so two photos is the practical cap for the 990px
@@ -61,8 +76,10 @@ const photos: Photo[] = hasMany ? images : [{ src: src as ImageMetadata, alt }];
     gap: 10px;
     line-height: 0;
   }
+
   /* The 2px outline comes from .prose img in prose.css. */
   .step-media :global(img) { width: 100%; height: auto; }
+
   /* The body is 1fr of the layout's column; nothing here narrows it. */
   .step-body { min-width: 0; }
   .step-body :global(p:last-child) { margin-bottom: 0; }
@@ -78,6 +95,7 @@ const photos: Photo[] = hasMany ? images : [{ src: src as ImageMetadata, alt }];
   /* stylelint-disable-next-line no-duplicate-selectors -- split from the
      grid rule above so the contract stays grouped with its own comment. */
   .step-media { margin: var(--step-media-margin, 0); }
+
   .step-media::before {
     content: counter(walkthrough-step);
     display: var(--step-chip-display, none);
@@ -115,6 +133,7 @@ const photos: Photo[] = hasMany ? images : [{ src: src as ImageMetadata, alt }];
      of a multi-photo step stacking too. Same breakpoint as MediaText. */
   @media (max-width: 600px) {
     .step { grid-template-columns: 1fr; gap: 10px; }
+
     .step-media {
       grid-auto-flow: row;
       grid-auto-columns: auto;

package/src/components/content/Walkthrough.astro

@@ -1,18 +1,22 @@
 ---
-/* Step-by-step photo walkthrough (spec
-   docs/superpowers/specs/2026-08-15-walkthrough-steps-design.md): an ordered
-   list of Step rows. Every photo inside forms one lightbox set; lightbox.ts
-   setFor() keys on the .walkthrough class, so keep it on the <ol>. */
-interface Props { numbered?: boolean; class?: string }
+interface Props {
+  numbered?: boolean;
+  class?: string;
+}
+
 const { numbered = false, class: className } = Astro.props;
 ---
+
 {/* list-style: none drops the implicit list role in Safari/VoiceOver, so
    role="list" restores it. html-validate's no-redundant-role and
    prefer-native-element both flag that as unnecessary on a native <ol>,
    which is true generically but wrong for this specific case; disabled
    surgically for this element only. */}
 <!-- [html-validate-disable-next no-redundant-role, prefer-native-element] -->
-<ol class:list={["walkthrough", numbered && "walkthrough-numbered", className]} role="list">
+<ol
+  class:list={["walkthrough", numbered && "walkthrough-numbered", className]}
+  role="list"
+>
   <slot />
 </ol>
 

package/src/components/content/WhenPublished.astro

@@ -0,0 +1,14 @@
+---
+import { forwardLinkVisible, type ForwardLinkable } from "../../lib/drafts";
+
+interface Props {
+  slug: string;
+  posts: ForwardLinkable[];
+  showDrafts?: boolean;
+}
+
+const { slug, posts, showDrafts = false } = Astro.props;
+const visible = forwardLinkVisible(slug, posts, showDrafts);
+---
+
+{visible && <slot />}

package/src/components/models.ts

@@ -4,6 +4,7 @@
    CollectionEntry mapping that produces them is src/lib/view-models.ts,
    which stays site-side. */
 import type { ImageMetadata } from "astro";
+import type { Badge } from "../scripts/core/badges";
 
 export interface PostCardModel {
   href: string;
@@ -15,8 +16,7 @@ export interface PostCardModel {
   hero: ImageMetadata;
   heroPosition?: string;
   draft?: boolean;
-  genai?: boolean;
-  demo?: boolean;
+  badges?: Badge[];
   categories: { name: string; href: string }[];
 }
 

package/src/lib/archive.ts

@@ -1,28 +1,42 @@
 import { slugifyCategory } from "./slug";
 
-interface PostLike { data: { date: Date; categories: string[] } }
+interface PostLike {
+  data: { date: Date; categories: string[] };
+}
 
 export function groupByMonth(posts: PostLike[], locale = "en-US") {
   const map = new Map<string, number>();
+
   for (const p of posts) {
     const d = p.data.date;
     const key = `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, "0")}`;
     map.set(key, (map.get(key) ?? 0) + 1);
   }
+
   return [...map.entries()]
     .sort((a, b) => (a[0] < b[0] ? 1 : -1))
     .map(([key, count]) => {
       const [year, month] = key.split("-");
-      const label = new Date(Date.UTC(Number(year), Number(month) - 1)).toLocaleDateString(locale, {
-        month: "long", year: "numeric", timeZone: "UTC",
+
+      const label = new Date(
+        Date.UTC(Number(year), Number(month) - 1),
+      ).toLocaleDateString(locale, {
+        month: "long",
+        year: "numeric",
+        timeZone: "UTC",
       });
+
       return { year, month, label, count };
     });
 }
 
 export function countByCategory(posts: PostLike[]) {
   const map = new Map<string, number>();
-  for (const p of posts) for (const c of p.data.categories) map.set(c, (map.get(c) ?? 0) + 1);
+
+  for (const p of posts) {
+    for (const c of p.data.categories) map.set(c, (map.get(c) ?? 0) + 1);
+  }
+
   return [...map.entries()]
     .sort((a, b) => a[0].localeCompare(b[0]))
     .map(([name, count]) => ({ name, slug: slugifyCategory(name), count }));

package/src/lib/drafts.ts

@@ -6,9 +6,14 @@
    this filter; a call site reaching for getCollection("posts") directly
    would leak drafts into whatever it renders. */
 
-export interface Draftable { data: { draft?: boolean } }
+export interface Draftable {
+  data: { draft?: boolean };
+}
 
-export function visiblePosts<T extends Draftable>(posts: T[], showDrafts: boolean): T[] {
+export function visiblePosts<T extends Draftable>(
+  posts: T[],
+  showDrafts: boolean,
+): T[] {
   return showDrafts ? posts : posts.filter((p) => !p.data.draft);
 }
 
@@ -21,10 +26,14 @@ export function visiblePosts<T extends Draftable>(posts: T[], showDrafts: boolea
    a build error rather than a silently hidden paragraph: a typo must not
    look like "still a draft". */
 
-export interface ForwardLinkable extends Draftable { data: { draft?: boolean; slug: string } }
+export interface ForwardLinkable extends Draftable {
+  data: { draft?: boolean; slug: string };
+}
 
 export function forwardLinkVisible(
-  slug: string, posts: ForwardLinkable[], showDrafts: boolean,
+  slug: string,
+  posts: ForwardLinkable[],
+  showDrafts: boolean,
 ): boolean {
   const target = posts.find((p) => p.data.slug === slug);
   if (!target) throw new Error(`WhenPublished: no post has slug "${slug}"`);
@@ -43,7 +52,9 @@ export function forwardLinkVisible(
 
 import { postPath } from "./slug";
 
-export interface Linkable { data: { slug: string; date: Date } }
+export interface Linkable {
+  data: { slug: string; date: Date };
+}
 
 export function resolvePostHref(slug: string, posts: Linkable[]): string {
   const target = posts.find((p) => p.data.slug === slug);

package/src/lib/format-date.ts

@@ -4,6 +4,9 @@
    house default. */
 export function formatPostDate(d: Date, locale = "en-US"): string {
   return d.toLocaleDateString(locale, {
-    year: "numeric", month: "long", day: "numeric", timeZone: "UTC",
+    year: "numeric",
+    month: "long",
+    day: "numeric",
+    timeZone: "UTC",
   });
 }

package/src/lib/ordering.ts

@@ -5,7 +5,9 @@
    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 } }
+export interface Publishable {
+  data: { date: Date; published?: Date };
+}
 
 export function publishedAt(p: Publishable): Date {
   return p.data.published ?? p.data.date;

package/src/lib/paginate.ts

@@ -1,7 +1,11 @@
 export function paginatePosts<T>(items: T[], size: number): T[][] {
   if (items.length === 0) return [[]];
   const pages: T[][] = [];
-  for (let i = 0; i < items.length; i += size) pages.push(items.slice(i, i + size));
+
+  for (let i = 0; i < items.length; i += size) {
+    pages.push(items.slice(i, i + size));
+  }
+
   return pages;
 }
 

package/src/lib/slug.ts

@@ -1,5 +1,8 @@
 export function slugifyCategory(name: string): string {
-  return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
 }
 
 /* The WP-compatible date permalink is the library's documented opinion
@@ -22,8 +25,12 @@ export function categoryPath(name: string, base = "/category"): string {
 /* Canonical href for a static page. One level of nesting exists today
    (children of policies); parent chains deeper than one are not modeled
    anywhere, so this stays flat on purpose. */
-export function pagePath(p: { data: { slug: string; parent?: string } }): string {
-  return p.data.parent ? `/${p.data.parent}/${p.data.slug}/` : `/${p.data.slug}/`;
+export function pagePath(p: {
+  data: { slug: string; parent?: string };
+}): string {
+  return p.data.parent
+    ? `/${p.data.parent}/${p.data.slug}/`
+    : `/${p.data.slug}/`;
 }
 
 /* Canonical lookup key for an internal href: root-relative, fragment
@@ -31,14 +38,19 @@ export function pagePath(p: { data: { slug: string; parent?: string } }): string
    site's own origins reduces to its path; anything else external is
    null, as is a file-ish path (a dot in the last segment, /feed.xml),
    which names a document with no page title to reveal. */
-export function internalHrefKey(href: string, origins: readonly string[] = []): string | null {
+export function internalHrefKey(
+  href: string,
+  origins: readonly string[] = [],
+): string | null {
   let h = href;
+
   for (const o of origins) {
     if (h === o || h.startsWith(`${o}/`)) {
       h = h.slice(o.length) || "/";
       break;
     }
   }
+
   if (!h.startsWith("/") || h.startsWith("//")) return null;
   h = h.replace(/[#?].*$/, "");
   if (h === "") return "/";
@@ -50,7 +62,12 @@ export function internalHrefKey(href: string, origins: readonly string[] = []):
 /* Top-level path segments owned by real routes. A page slugged one of these
    (or a bare year) would shadow the archive, pagination, category, or search
    trees under the [...slug] catch-all without any build error. */
-export const RESERVED_PAGE_SLUGS = new Set(["page", "category", "search", "404"]);
+export const RESERVED_PAGE_SLUGS = new Set([
+  "page",
+  "category",
+  "search",
+  "404",
+]);
 
 /* Build-time guard for the [...slug] catch-all: rejects reserved top-level
    slugs and parent references that resolve to nothing (a typo'd parent would
@@ -67,7 +84,13 @@ export function assertPageRoutable(
       `Page "${p.data.slug}" declares parent "${p.data.parent}", which matches no page slug`,
     );
   }
-  if (!p.data.parent && (reserved.has(p.data.slug) || /^\d{4}$/.test(p.data.slug))) {
-    throw new Error(`Page slug "${p.data.slug}" collides with a reserved route`);
+
+  if (
+    !p.data.parent &&
+    (reserved.has(p.data.slug) || /^\d{4}$/.test(p.data.slug))
+  ) {
+    throw new Error(
+      `Page slug "${p.data.slug}" collides with a reserved route`,
+    );
   }
 }

package/src/scripts/code-island.ts

@@ -13,34 +13,53 @@ export interface CodeIslandOptions {
   resetMs?: number;
 }
 
-export const mountCodeIslands: Island<CodeIslandOptions> = (root, options = {}): IslandHandle => {
+export const mountCodeIslands: Island<CodeIslandOptions> = (
+  root,
+  options = {},
+): IslandHandle => {
   const {
     selector = ".prose pre.astro-code",
     copy = { copy: "COPY", copied: "COPIED", failed: "FAILED" },
     resetMs = 1500,
   } = options;
+
   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. */
-  const mounted: { pre: Element; bar: HTMLDivElement; btn: HTMLButtonElement; onClick: () => void; resetTimer: { id: ReturnType<typeof setTimeout> | undefined } }[] = [];
+  const mounted: {
+    pre: Element;
+    bar: HTMLDivElement;
+    btn: HTMLButtonElement;
+    onClick: () => void;
+    resetTimer: { id: ReturnType<typeof setTimeout> | undefined };
+  }[] = [];
 
   for (const pre of root.querySelectorAll(selector)) {
     if (!claim(pre, "code")) continue;
     const bar = doc.createElement("div");
     bar.className = "code-island-bar";
     const label = doc.createElement("span");
-    const file = pre.closest("[data-code-filename]")?.getAttribute("data-code-filename");
+
+    const file = pre
+      .closest("[data-code-filename]")
+      ?.getAttribute("data-code-filename");
+
     const lang = pre.getAttribute("data-language") ?? "";
     label.textContent = [file, lang].filter(Boolean).join(" · ");
     const btn = doc.createElement("button");
     btn.className = "code-copy";
     btn.type = "button";
     btn.textContent = copy.copy;
-    const resetTimer: { id: ReturnType<typeof setTimeout> | undefined } = { id: undefined };
+
+    const resetTimer: { id: ReturnType<typeof setTimeout> | undefined } = {
+      id: undefined,
+    };
+
     const doCopy = async (): Promise<void> => {
       try {
         await navigator.clipboard.writeText(pre.textContent);
@@ -48,14 +67,18 @@ export const mountCodeIslands: Island<CodeIslandOptions> = (root, options = {}):
       } catch {
         btn.textContent = copy.failed;
       }
+
       clearTimeout(resetTimer.id);
+
       resetTimer.id = setTimeout(() => {
         btn.textContent = copy.copy;
       }, resetMs);
     };
+
     const onClick = (): void => {
       void doCopy();
     };
+
     btn.addEventListener("click", onClick);
     bar.append(label, btn);
     pre.before(bar);

package/src/scripts/core/badges.ts

@@ -0,0 +1,28 @@
+/* A corner badge is data the caller hands to CornerBadges.astro: a key
+   (which becomes the chip's badge-<key> class, the styling hook), the
+   label, and a glyph from the icon registry. No lookup table in the
+   package (owner call 2026-09-10): a site's view-model lists the
+   badges a post carries, in the order it wants them, and can invent one
+   without a package release. The two house conventions ship as
+   constants so every site spells them the same way. */
+import type { IconName } from "./icons";
+
+export interface Badge {
+  key: string;
+  label: string;
+  icon: IconName;
+}
+
+/* The pixels were generated (a hero, a content image). */
+export const GENAI_BADGE: Badge = {
+  key: "genai",
+  label: "AI Art",
+  icon: "sparkles",
+};
+
+/* The post carries an interactive demo. */
+export const DEMO_BADGE: Badge = {
+  key: "demo",
+  label: "Demo",
+  icon: "play",
+};

package/src/scripts/core/dom.ts

@@ -14,7 +14,12 @@ export function el<K extends keyof HTMLElementTagNameMap>(
   return node;
 }
 
-export function iconButton(doc: Document, className: string, label: string, svg: string): HTMLButtonElement {
+export function iconButton(
+  doc: Document,
+  className: string,
+  label: string,
+  svg: string,
+): HTMLButtonElement {
   const btn = doc.createElement("button");
   btn.type = "button";
   btn.className = className;

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

@@ -23,7 +23,10 @@ export function createFrameLoop(
 
   function tick(now: number): void {
     if (!live) return;
-    const dt = last === 0 ? firstDt : Math.min(clamp, Math.max(0, (now - last) / 1000));
+
+    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.