@half-built/astro 0.2.0 → 0.3.1

package/README.md

@@ -44,6 +44,32 @@ follows the live cascade with no script, and the hex cell renders
 empty with a `data-token-hex` attribute for a consumer script to fill
 from computed styles. Entries with `hex` render exactly as before.
 
+## Ecosystem island
+
+`scripts/ecosystem` fills the Footer's Ecosystem column from a shared
+JSON document, so adding a property to a family of sites does not mean
+rebuilding every one of them.
+
+```js
+import { mountEcosystem } from "@half-built/astro/scripts/ecosystem";
+
+void mountEcosystem(document, {
+  endpoint: "https://example.com/ecosystem.json",
+  selfKey: "ui",
+});
+```
+
+The endpoint is a parameter and the package ships no default. `Footer`
+keeps taking `ecosystem` and `ecosystemSelf` as typed props, and those
+props are the static baseline the island replaces. Every failure path
+leaves that baseline standing: no JavaScript, a dead endpoint, a
+malformed payload, or a document that does not contain `selfKey`.
+
+The document is `{ version: 1, entries: [...] }` where each entry has
+`key`, `label`, `href` (null renders unlinked), `priority` (ascending,
+0 highest) and `family`. Entries are sorted with the self entry's own
+family first, then by priority, and capped at `limit`, default 6.
+
 ## Import notes
 
 Wildcard subpath imports need explicit file extensions under

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@half-built/astro",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Astro components, islands, and pure helpers for the half-built design system.",
   "license": "MIT",
   "repository": {

package/src/components/Footer.astro

@@ -62,11 +62,11 @@ const year = new Date().getFullYear();
         )}
         <details class="footer-sitemap-group footer-sitemap-collapsible" open>
           <summary><h2>{ecosystemTitle}</h2></summary>
-          <ul>
+          <ul data-ecosystem>
             {ecosystem.map((entry) => (
               <li>
                 {entry.key === ecosystemSelf ? (
-                  <span class="footer-sitemap-self">{entry.label}</span>
+                  <span class="footer-sitemap-self" aria-current="page">{entry.label}</span>
                 ) : entry.href !== null ? (
                   <a href={entry.href}>{entry.label}</a>
                 ) : (

package/src/scripts/ecosystem.ts

@@ -1,7 +1,8 @@
 /* The ecosystem island: the footer's Ecosystem column, fetched at
    runtime from a shared document so adding a property to the family
    never means rebuilding every site (design record
-   2026-09-06-ecosystem-endpoint-design.md in this repo's docs).
+   docs/superpowers/specs/2026-09-06-ecosystem-endpoint-design.md in
+   this repo).
 
    The component keeps rendering its typed props, which are the static
    baseline. This island replaces that list only on a validated,
@@ -35,7 +36,12 @@ function isEntry(value: unknown): value is EcosystemDocEntry {
   return (
     typeof entry.key === "string" && entry.key !== "" &&
     typeof entry.label === "string" && entry.label !== "" &&
-    (entry.href === null || typeof entry.href === "string") &&
+    /* href is checked by scheme, not just type, because it is assigned
+       straight to link.href below. The document and the cached copy
+       are both untrusted input, and a javascript: or data: URL there
+       would run on the consumer's origin when clicked. */
+    (entry.href === null ||
+      (typeof entry.href === "string" && /^https?:\/\//i.test(entry.href))) &&
     typeof entry.priority === "number" && Number.isFinite(entry.priority) &&
     typeof entry.family === "string" && entry.family !== ""
   );
@@ -77,3 +83,218 @@ export function sortEntries(
     })
     .slice(0, limit);
 }
+
+const CACHE_KEY = "half-built-ecosystem";
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const ATTEMPT_TIMEOUT_MS = 3000;
+const RETRY_DELAYS_MS = [400, 1200];
+const JITTER_MS = 250;
+
+/* A transport failure can differ on a second attempt. A content
+   failure cannot, so it is reported separately and never retried. */
+type Attempt =
+  | { kind: "body"; body: unknown }
+  | { kind: "transport"; status: number | null }
+  | { kind: "content" };
+
+function retryable(status: number | null): boolean {
+  if (status === null) return true;
+  if (status === 429) return true;
+  return status >= 500 && status <= 599;
+}
+
+function sleep(ms: number): Promise<void> {
+  const jitter = ms === 0 ? 0 : Math.random() * JITTER_MS;
+  return new Promise((resolve) => setTimeout(resolve, ms + jitter));
+}
+
+async function attemptFetch(endpoint: string): Promise<Attempt> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => { controller.abort(); }, ATTEMPT_TIMEOUT_MS);
+  /* The timer is cleared once in this single finally, which covers the
+     header fetch and the body read alike: the 3 second budget bounds
+     the whole attempt, not just the response headers, so a stalled
+     body read still aborts instead of leaving the promise pending
+     forever. */
+  try {
+    let response: Response;
+    try {
+      response = await fetch(endpoint, { signal: controller.signal, credentials: "omit" });
+    } catch {
+      return { kind: "transport", status: null };
+    }
+    if (!response.ok) return { kind: "transport", status: response.status };
+    let text: string;
+    try {
+      text = await response.text();
+    } catch {
+      return { kind: "transport", status: null };
+    }
+    try {
+      return { kind: "body", body: JSON.parse(text) as unknown };
+    } catch {
+      /* Parsed nothing usable. The same bytes come back next time. */
+      return { kind: "content" };
+    }
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function readCache(storage: Storage | null, cacheKey: string, now: number): EcosystemDocument | null {
+  if (!storage) return null;
+  try {
+    const raw = storage.getItem(cacheKey);
+    if (raw === null) return null;
+    const parsed: unknown = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null) return null;
+    const record = parsed as Record<string, unknown>;
+    if (typeof record.fetchedAt !== "number") return null;
+    if (now - record.fetchedAt > CACHE_TTL_MS) return null;
+    /* Storage is untrusted input, so it runs the same gate as a fetch. */
+    return validateDocument(record.document);
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(storage: Storage | null, cacheKey: string, now: number, document: EcosystemDocument): void {
+  if (!storage) return;
+  try {
+    storage.setItem(cacheKey, JSON.stringify({ fetchedAt: now, document }));
+  } catch {
+    /* A private window or blocked site data. The fetch still stands. */
+  }
+}
+
+/** Fetch with retry, falling back to the last known good copy. Null
+    when neither yields a usable document. */
+export async function loadDocument(
+  endpoint: string,
+  storage: Storage | null,
+  now: number,
+  retryDelaysMs: number[] = RETRY_DELAYS_MS,
+  cacheKey: string = CACHE_KEY,
+): Promise<EcosystemDocument | null> {
+  /* One attempt up front, then one per configured delay. Iterating the
+     delays rather than indexing them keeps this free of the array
+     index access that reads as possibly undefined under the strict
+     project and as definitely defined under the lint project. */
+  for (const delay of [0, ...retryDelaysMs]) {
+    await sleep(delay);
+    const result = await attemptFetch(endpoint);
+    if (result.kind === "body") {
+      const document = validateDocument(result.body);
+      if (document) {
+        writeCache(storage, cacheKey, now, document);
+        return document;
+      }
+      break;
+    }
+    if (result.kind === "content") break;
+    if (!retryable(result.status)) break;
+  }
+  return readCache(storage, cacheKey, now);
+}
+
+const DEFAULT_LIMIT = 6;
+
+export interface EcosystemOptions {
+  /* The document's URL. This package ships no default: a consumer
+     passes its own, so the package reads no consumer configuration. */
+  endpoint: string;
+  /* The entry this site renders as itself, unlinked and bold. */
+  selfKey: string;
+  limit?: number;
+  retryDelaysMs?: number[];
+  /* The storage key is a mount option, not a package literal (same
+     convention as theme-toggle.ts's storageKey), so a consumer can
+     namespace the cache. Defaults to the current literal, which keeps
+     behavior identical and lets two sites on one origin share the
+     cached document, which is reasonable since it is not site-specific. */
+  cacheKey?: string;
+}
+
+/* Astro compiles a component's scoped rules to `.cls[data-astro-cid-x]`,
+   and it stamps that attribute at build time on markup it renders. An
+   element built here with createElement never gets stamped, so it
+   matches none of Footer.astro's scoped rules: the self entry loses its
+   bold, a pending entry loses its dimming, and every link falls back to
+   the browser's default underline. The server-rendered list is stamped,
+   so the fix is to read the attribute off it and carry it onto whatever
+   we create. Read rather than hardcoded, because the hash changes
+   whenever the component's styles change. Consumers who render the
+   footer unscoped simply have nothing to copy, and the loop is a no-op. */
+function scopeOf(list: Element): string | null {
+  for (const { name } of list.attributes) {
+    if (name.startsWith("data-astro-cid-")) return name;
+  }
+  return null;
+}
+
+function entryNode(doc: Document, entry: EcosystemDocEntry, selfKey: string): HTMLElement {
+  if (entry.key === selfKey) {
+    const self = doc.createElement("span");
+    self.className = "footer-sitemap-self";
+    /* The bold is the visual "you are here"; this is the same statement
+       for a screen reader, which cannot see weight. Without it the self
+       entry is announced exactly like an undeployed one. */
+    self.setAttribute("aria-current", "page");
+    self.textContent = entry.label;
+    return self;
+  }
+  if (entry.href !== null) {
+    const link = doc.createElement("a");
+    link.href = entry.href;
+    link.textContent = entry.label;
+    return link;
+  }
+  const pending = doc.createElement("span");
+  pending.className = "footer-sitemap-pending";
+  pending.textContent = entry.label;
+  return pending;
+}
+
+function safeStorage(view: Window | null): Storage | null {
+  try {
+    return view?.localStorage ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Replace the footer's ecosystem list with the shared document's, or
+    leave the server-rendered baseline exactly as it is.
+
+    This deliberately does not follow the package's Island<O> contract
+    from core/island.ts: it is async and returns no destroy handle,
+    because there is nothing here to tear down. One consequence is that
+    it has no claim() guard, so a caller that mounts it twice on the
+    same document runs the fetch and the swap twice; every known
+    caller mounts it once. */
+export async function mountEcosystem(root: Document, opts: EcosystemOptions): Promise<void> {
+  const { endpoint, selfKey, limit = DEFAULT_LIMIT, retryDelaysMs, cacheKey = CACHE_KEY } = opts;
+  const list = root.querySelector<HTMLElement>("[data-ecosystem]");
+  if (!list) return;
+
+  const storage = safeStorage(root.defaultView);
+  const document_ = await loadDocument(endpoint, storage, Date.now(), retryDelaysMs, cacheKey);
+  if (!document_) return;
+
+  const entries = sortEntries(document_.entries, selfKey, limit);
+  if (!entries || entries.length === 0) return;
+
+  const scope = scopeOf(list);
+  const fragment = root.createDocumentFragment();
+  for (const entry of entries) {
+    const item = root.createElement("li");
+    const node = entryNode(root, entry, selfKey);
+    if (scope !== null) {
+      item.setAttribute(scope, "");
+      node.setAttribute(scope, "");
+    }
+    item.append(node);
+    fragment.append(item);
+  }
+  list.replaceChildren(fragment);
+}