@half-built/astro 0.1.0

package/src/components/models.ts

@@ -0,0 +1,77 @@
+/* View-model types for the chrome components (step 6, 2026-08-30).
+   These live with the components, not in lib/: the components are the
+   future @half-built/astro package and must not import site code. The
+   CollectionEntry mapping that produces them is src/lib/view-models.ts,
+   which stays site-side. */
+import type { ImageMetadata } from "astro";
+
+export interface PostCardModel {
+  href: string;
+  title: string;
+  excerpt: string;
+  author: string;
+  dateStr: string;
+  minutes: number;
+  hero: ImageMetadata;
+  heroPosition?: string;
+  draft?: boolean;
+  genai?: boolean;
+  demo?: boolean;
+  categories: { name: string; href: string }[];
+}
+
+export interface PostRef {
+  href: string;
+  title: string;
+}
+
+export interface LinkListItem {
+  label: string;
+  href: string;
+  count?: number;
+}
+
+/* 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. */
+export interface NavItem {
+  label: string;
+  href: string;
+}
+
+export interface SocialItem {
+  /* Screen-reader text for the icon. */
+  label: string;
+  href: string;
+  /* Inline SVG markup, rendered with set:html. */
+  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. */
+export interface SitemapLink {
+  label: string;
+  href: string;
+}
+
+export interface SitemapGroup {
+  title: string;
+  links: SitemapLink[];
+  /* Collapsible on phones (a <details>, always open on wider screens). */
+  collapsible?: boolean;
+  /* A collapsible group starts closed on phones unless this is set. */
+  phoneOpen?: boolean;
+}
+
+export interface EcosystemEntry {
+  key: string;
+  label: string;
+  /* null: property not deployed yet; renders visible but unlinked. */
+  href: string | null;
+}

package/src/lib/archive.ts

@@ -0,0 +1,29 @@
+import { slugifyCategory } from "./slug";
+
+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",
+      });
+      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);
+  return [...map.entries()]
+    .sort((a, b) => a[0].localeCompare(b[0]))
+    .map(([name, count]) => ({ name, slug: slugifyCategory(name), count }));
+}

package/src/lib/drafts.ts

@@ -0,0 +1,52 @@
+/* Draft visibility, pure and framework-free so it is unit-testable.
+   A draft exists in the repo but not in the deploy build; a build run
+   with SHOW_DRAFTS=1 includes it so the final look can be reviewed on
+   a production preview build (never the dev server, per house rules).
+   Every consumer goes through sortedPosts() in posts.ts, which applies
+   this filter; a call site reaching for getCollection("posts") directly
+   would leak drafts into whatever it renders. */
+
+export interface Draftable { data: { draft?: boolean } }
+
+export function visiblePosts<T extends Draftable>(posts: T[], showDrafts: boolean): T[] {
+  return showDrafts ? posts : posts.filter((p) => !p.data.draft);
+}
+
+/* Forward links. A published post may reference a post that is still a
+   draft (the Táltos-oid build post teases its own reflection post, owner
+   request 2026-08-24). The WhenPublished content component wraps that
+   passage and renders it only once the target is visible, so the earlier
+   post never has to be revised when the later one ships, and no link to a
+   draft leaks into a deploy build. A slug that matches no post at all is
+   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 function forwardLinkVisible(
+  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}"`);
+  return showDrafts || !target.data.draft;
+}
+
+/* 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. */
+
+import { postPath } from "./slug";
+
+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);
+  if (!target) throw new Error(`PostLink: no post has slug "${slug}"`);
+  return postPath(target);
+}

package/src/lib/format-date.ts

@@ -0,0 +1,9 @@
+/* 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. */
+export function formatPostDate(d: Date, locale = "en-US"): string {
+  return d.toLocaleDateString(locale, {
+    year: "numeric", month: "long", day: "numeric", timeZone: "UTC",
+  });
+}

package/src/lib/header-date.ts

@@ -0,0 +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. */
+export function formatHeaderDate(now: Date): string {
+  return `${now.getDate()}, ${now.toLocaleDateString("en-US", { month: "short" })} ${now.getFullYear()}`;
+}

package/src/lib/ordering.ts

@@ -0,0 +1,18 @@
+/* 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). */
+
+export interface Publishable { data: { date: Date; published?: Date } }
+
+export function publishedAt(p: Publishable): Date {
+  return p.data.published ?? p.data.date;
+}
+
+/* The one newest-first comparator. Never hand-write a date sort expression
+   at a call site; use this. */
+export function byNewest(a: Publishable, b: Publishable): number {
+  return +publishedAt(b) - +publishedAt(a);
+}

package/src/lib/paginate.ts

@@ -0,0 +1,15 @@
+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));
+  return pages;
+}
+
+/* Canonical href for an archive page: page 1 is the archive root, deeper
+   pages live at /page/N/ (trailing slash, site-wide rule). base is the
+   archive's root without its trailing slash ("" for the site root,
+   "/category/robots" for a category); Pagination.astro and the post
+   back link both call this so the rule exists once. */
+export function archivePagePath(page: number, base = ""): string {
+  return page <= 1 ? `${base}/` : `${base}/page/${page}/`;
+}

package/src/lib/reading-time.ts

@@ -0,0 +1,4 @@
+export function readingTime(text: string): number {
+  const words = text.trim().split(/\s+/).filter(Boolean).length;
+  return Math.max(1, Math.ceil(words / 200));
+}

package/src/lib/slug.ts

@@ -0,0 +1,73 @@
+export function slugifyCategory(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+
+/* The WP-compatible date permalink is the library's documented opinion
+   (owner decision 5, 2026-08-31): migrating sites keep their URLs by
+   default. */
+export function postPath(p: { data: { date: Date; slug: string } }): string {
+  const d = p.data.date;
+  const mm = String(d.getUTCMonth() + 1).padStart(2, "0");
+  const dd = String(d.getUTCDate()).padStart(2, "0");
+  return `/${d.getUTCFullYear()}/${mm}/${dd}/${p.data.slug}/`;
+}
+
+/* Category archive href for a category name. base parameterizes the URL
+   strategy the way postPath does not yet; the default matches this site's
+   current /category/ tree. */
+export function categoryPath(name: string, base = "/category"): string {
+  return `${base}/${slugifyCategory(name)}/`;
+}
+
+/* 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}/`;
+}
+
+/* Canonical lookup key for an internal href: root-relative, fragment
+   and query stripped, slash-terminated. An absolute href on one of the
+   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 {
+  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 "/";
+  const last = h.slice(h.lastIndexOf("/") + 1);
+  if (last.includes(".")) return null;
+  return h.endsWith("/") ? h : `${h}/`;
+}
+
+/* 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"]);
+
+/* 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
+   otherwise silently render the child as a top-level page). reserved is
+   parameterized so a caller with a different URL strategy can supply its
+   own set instead of forking the guard. */
+export function assertPageRoutable(
+  p: { data: { slug: string; parent?: string } },
+  parent: { data: { slug: string } } | undefined,
+  reserved: ReadonlySet<string> = RESERVED_PAGE_SLUGS,
+): void {
+  if (p.data.parent && !parent) {
+    throw new Error(
+      `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`);
+  }
+}

package/src/scripts/code-island.ts

@@ -0,0 +1,75 @@
+import { claim, release, type Island, type IslandHandle } from "./core/island";
+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). */
+/* 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 {
+  selector?: string;
+  copy?: { copy: string; copied: string; failed: string };
+  resetMs?: number;
+}
+
+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 } }[] = [];
+
+  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 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 doCopy = async (): Promise<void> => {
+      try {
+        await navigator.clipboard.writeText(pre.textContent);
+        btn.textContent = copy.copied;
+      } 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);
+    mounted.push({ pre, bar, btn, onClick, resetTimer });
+  }
+
+  return {
+    destroy(): void {
+      for (const { pre, bar, btn, onClick, resetTimer } of mounted) {
+        btn.removeEventListener("click", onClick);
+        clearTimeout(resetTimer.id);
+        bar.remove();
+        release(pre, "code");
+      }
+    },
+  };
+};

package/src/scripts/core/breakpoints.ts

@@ -0,0 +1,4 @@
+/* The system breakpoints' JS mirror (step 11.1). The CSS source of
+   truth is src/styles/tokens/breakpoints.css; test/breakpoints.test.ts
+   pins the two equal, so a retune edits both or fails the suite. */
+export const BP_PHONE_MAX = 768;

package/src/scripts/core/dom.ts

@@ -0,0 +1,31 @@
+/* Small DOM builders shared by the islands (step 9): el() came from the
+   search page's inline script, iconButton() from lightbox.ts. One home,
+   per the review's Islands findings; the deliberately-not-included
+   focus trap stays not included (native <dialog> owns that). */
+export function el<K extends keyof HTMLElementTagNameMap>(
+  doc: Document,
+  tag: K,
+  className?: string,
+  text?: string,
+): HTMLElementTagNameMap[K] {
+  const node = doc.createElement(tag);
+  if (className) node.className = className;
+  if (text !== undefined) node.textContent = text;
+  return node;
+}
+
+export function iconButton(doc: Document, className: string, label: string, svg: string): HTMLButtonElement {
+  const btn = doc.createElement("button");
+  btn.type = "button";
+  btn.className = className;
+  btn.setAttribute("aria-label", label);
+  btn.innerHTML = svg;
+  return btn;
+}
+
+/* Every island's root.ownerDocument ?? (root as Document) fallback, in one
+   place (step 11.2 docOf sweep): a root that is itself a Document (no
+   ownerDocument) resolves to itself. */
+export function docOf(root: ParentNode): Document {
+  return root.ownerDocument ?? (root as Document);
+}

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

@@ -0,0 +1,54 @@
+/* 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
+   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. */
+export interface FrameLoop {
+  start(): void;
+  stop(): void;
+  running(): boolean;
+}
+
+export function createFrameLoop(
+  win: Window,
+  cb: (dt: number) => void,
+  options: { clamp?: number; firstDt?: number } = {},
+): FrameLoop {
+  const { clamp = 0.05, firstDt = 0.016 } = options;
+  let handle = 0;
+  let last = 0;
+  let live = false;
+
+  function tick(now: number): void {
+    if (!live) return;
+    const dt = last === 0 ? firstDt : Math.min(clamp, Math.max(0, (now - last) / 1000));
+    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);
+  }
+
+  return {
+    start(): void {
+      if (live) return;
+      live = true;
+      last = 0;
+      handle = win.requestAnimationFrame(tick);
+    },
+    stop(): void {
+      if (!live) return;
+      live = false;
+      win.cancelAnimationFrame(handle);
+      last = 0;
+    },
+    running(): boolean {
+      return live;
+    },
+  };
+}

package/src/scripts/core/icons.ts

@@ -0,0 +1,30 @@
+/* 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
+   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. */
+
+/* 1em sizing: icons track their button's font size instead of a fixed
+   pixel box. */
+/* pointer-events none: a click on a button must target the button, not
+   the decorative svg. A targeted svg detached by an innerHTML swap
+   mid-bubble made the plate-modal's veil check read a pause click as
+   outside the zone and close the dialog (found 2026-08-23). */
+const icon = (paths: string, fill = "none"): string =>
+  `<svg viewBox="0 0 24 24" width="1em" height="1em" fill="${fill}" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" pointer-events="none" aria-hidden="true">${paths}</svg>`;
+
+export const ICON_X = icon('<path d="M18 6 6 18"/><path d="m6 6 12 12"/>');
+/* Play is the one filled icon: a stroke-only triangle reads as a hollow
+   arrow, not a play control. */
+export const ICON_PLAY = icon('<polygon points="7 4 19 12 7 20 7 4"/>', "currentColor");
+/* The AI Art badge (CornerBadges.astro). */
+export const ICON_SPARKLES = icon('<path d="M9.937 15.5A2 2 0 0 0 8.5 14.063l-6.135-1.582a.5.5 0 0 1 0-.962L8.5 9.936A2 2 0 0 0 9.937 8.5l1.582-6.135a.5.5 0 0 1 .963 0L14.063 8.5A2 2 0 0 0 15.5 9.937l6.135 1.581a.5.5 0 0 1 0 .964L15.5 14.063a2 2 0 0 0-1.437 1.437l-1.582 6.135a.5.5 0 0 1-.963 0z"/><path d="M20 3v4"/><path d="M22 5h-4"/><path d="M4 17v2"/><path d="M5 18H3"/>');
+export const ICON_PAUSE = icon('<line x1="9" x2="9" y1="5" y2="19"/><line x1="15" x2="15" y1="5" y2="19"/>');
+export const ICON_ROTATE_CCW = icon('<path d="M3 12a9 9 0 1 0 9-9 9.75 9.75 0 0 0-6.74 2.74L3 8"/><path d="M3 3v5h5"/>');
+export const ICON_CHEVRON_LEFT = icon('<path d="m15 18-6-6 6-6"/>');
+export const ICON_CHEVRON_RIGHT = icon('<path d="m9 18 6-6-6-6"/>');
+/* Day/night toggle in the header (owner request 2026-08-25). */
+export const ICON_SUN = icon('<circle cx="12" cy="12" r="4"/><path d="M12 2v2"/><path d="M12 20v2"/><path d="m4.93 4.93 1.41 1.41"/><path d="m17.66 17.66 1.41 1.41"/><path d="M2 12h2"/><path d="M20 12h2"/><path d="m6.34 17.66-1.41 1.41"/><path d="m19.07 4.93-1.41 1.41"/>');
+export const ICON_MOON = icon('<path d="M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z"/>');

package/src/scripts/core/island.ts

@@ -0,0 +1,25 @@
+/* The island contract (step 9, spec sequence item 9): every client
+   behavior is mount(root, options?) returning a destroy handle, and
+   mounting twice is a no-op per element via claim(). Options carry the
+   selectors and copy that used to be baked in, defaulting to this
+   site's values, so another consumer overrides without forking. */
+export interface IslandHandle {
+  destroy(): void;
+}
+
+export type Island<O = void> = (root: ParentNode, options?: O) => IslandHandle;
+
+/* One claim per element per island name. A data attribute, not a
+   WeakSet: visible in devtools when debugging a double-mount. */
+export function claim(target: Element, island: string): boolean {
+  const key = `data-island-${island}`;
+  if (target.hasAttribute(key)) return false;
+  target.setAttribute(key, "");
+  return true;
+}
+
+/* Mirror of claim(): destroy() paths call this instead of hardcoding
+   the attribute name (Task 2 review's latent-coupling finding). */
+export function release(target: Element, island: string): void {
+  target.removeAttribute(`data-island-${island}`);
+}

package/src/scripts/core/storage.ts

@@ -0,0 +1,44 @@
+/* The localStorage read/validate/write codec (step 10), one home for
+   the pattern henry-loose.ts and stasis-state.ts each carried: 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
+   error. */
+export interface StoredJson<T> {
+  read(): T | null;
+  write(v: T): void;
+  clear(): void;
+}
+
+export function storedJson<T>(
+  key: string,
+  parse: (raw: string | null) => T | null,
+  serialize: (v: T) => string = JSON.stringify,
+): StoredJson<T> {
+  return {
+    read(): T | null {
+      try {
+        const raw = localStorage.getItem(key);
+        const v = parse(raw);
+        if (v === null && raw !== null) localStorage.removeItem(key);
+        return v;
+      } catch {
+        return null;
+      }
+    },
+    write(v: T): void {
+      try {
+        localStorage.setItem(key, serialize(v));
+      } catch {
+        /* State lives for this page only. */
+      }
+    },
+    clear(): void {
+      try {
+        localStorage.removeItem(key);
+      } catch {
+        /* Nothing to clear. */
+      }
+    },
+  };
+}

package/src/scripts/focus-mode.ts

@@ -0,0 +1,41 @@
+import { claim, release, type Island, type IslandHandle } from "./core/island";
+
+/* How did focus arrive: keyboard or pointer. A text field matches
+   :focus-visible on a mouse click as well as on a Tab, so CSS alone
+   cannot give the joined field its own click highlight while keeping
+   the site-wide keyboard ring (owner rule 2026-08-26). Stamps
+   data-focus="keyboard" | "pointer" on the root; patterns.css reads it.
+   Package-bound (owner decision 2, 2026-08-31): patterns.css keys on
+   the stamp this island writes. */
+
+export interface FocusModeOptions {
+  /* What to listen on, capture: true, as today. Defaults to window so a
+     keydown or pointerdown anywhere in the document is caught before it
+     reaches the target that would otherwise show its own focus ring. */
+  target?: EventTarget;
+}
+
+export const mountFocusMode: Island<FocusModeOptions> = (root, options = {}): IslandHandle => {
+  const el = root as HTMLElement;
+  const target = options.target ?? window;
+  if (!claim(el, "focus-mode")) {
+    return {
+      destroy(): void {
+        /* already claimed elsewhere: nothing here to tear down */
+        return;
+      },
+    };
+  }
+  const onKeydown = (): void => { el.dataset.focus = "keyboard"; };
+  const onPointerdown = (): void => { el.dataset.focus = "pointer"; };
+  target.addEventListener("keydown", onKeydown, true);
+  target.addEventListener("pointerdown", onPointerdown, true);
+
+  return {
+    destroy(): void {
+      target.removeEventListener("keydown", onKeydown, true);
+      target.removeEventListener("pointerdown", onPointerdown, true);
+      release(el, "focus-mode");
+    },
+  };
+};