@half-built/astro 0.1.0 → 0.3.0

package/README.md

@@ -14,3 +14,68 @@ is the design record for this package.
 
 Default icon glyphs are derived from Lucide (https://lucide.dev), ISC
 license. See `ICONS-LICENSE`.
+
+## EditorNote
+
+`content/EditorNote.astro` is a reminder block for content that must
+not ship: by default it renders only when the consuming build runs in
+dev mode, and a deploy build emits nothing for it. A consumer with a
+wider preview concept (the blog's SHOW_DRAFTS builds, for example)
+passes its own gate through the `shown` prop; the component reads no
+consumer config itself.
+
+## Live code colors
+
+`shiki/code-theme` bakes its amber values into every highlighted span
+at build time. `shiki/code-vars` is a Shiki transformer that rewrites
+those baked values to the css package's `--code-token-*` and
+`--code-*` custom properties, so highlighted code follows a runtime
+palette override. The variables resolve to the same hexes the theme
+bakes, so adopting the transformer changes no rendered pixel on its
+own. Pass it beside the theme: the `transformers` prop of
+`astro:components`' `Code`, or `markdown.shikiConfig.transformers` in
+an Astro config.
+
+## Palette token entries
+
+A `content/Palette.astro` entry may carry `token` (a custom property
+name) instead of `hex`: the swatch then paints `var(token)` and
+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
+TypeScript's bundler mode: `@half-built/astro/lib/slug.ts` and
+`@half-built/astro/components/Shell.astro`, not extensionless forms.
+Vite resolves either; `tsc --noEmit` only accepts the explicit one.
+
+The `Masthead.astro` export is an alias for `SiteHeader.astro`, the
+same component under its public name.

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@half-built/astro",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Astro components, islands, and pure helpers for the half-built design system.",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/curthenrichs/half-built-ui.git",
+    "directory": "packages/astro"
+  },
   "type": "module",
   "files": ["src", "ICONS-LICENSE"],
   "exports": {
@@ -11,7 +16,8 @@
     "./content/*": "./src/components/content/*",
     "./scripts/*": "./src/scripts/*",
     "./lib/*": "./src/lib/*",
-    "./shiki/code-theme": "./src/shiki/code-theme.mjs"
+    "./shiki/code-theme": "./src/shiki/code-theme.mjs",
+    "./shiki/code-vars": "./src/shiki/code-vars.mjs"
   },
   "peerDependencies": { "astro": "^5.0.0" },
   "publishConfig": { "access": "public" }

package/src/components/Footer.astro

@@ -62,7 +62,7 @@ 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 ? (

package/src/components/PostCard.astro

@@ -90,12 +90,18 @@ const heroStyle = heroPosition ? `object-position: ${heroPosition}` : undefined;
     z-index: 2;
     font-size: var(--font-size-xl);
   }
-  /* Chip look comes from the .chip pattern; only placement is contextual. */
+  /* Chip look comes from the .chip pattern; only placement is
+     contextual. display: flex, not a plain block: a block wrapper
+     gives the inline-flex chip a text line box whose descender gap
+     floats it off the true bottom, so this chip and the corner badges
+     (already a flex container) sat at different offsets (owner catch
+     2026-09-06). */
   .read-time-comment {
     position: absolute;
     bottom: 10px;
     left: 10px;
     z-index: 1;
+    display: flex;
   }
   .post-item-content { padding: 15px 0 0; padding-top: 10px; }
   .entry-cat .post-categories {

package/src/components/content/EditorNote.astro

@@ -0,0 +1,57 @@
+---
+/* Editor note: a reminder in content that renders on the dev server
+   and stays out of deploy builds. Moved up from the blog's
+   content/EditorNote.astro (owner call 2026-09-06: it is generic and
+   should have crossed in the 11.3 extraction; the blog swaps onto this
+   copy at its next pin bump). The blog's gate read its own SHOW_DRAFTS
+   config, which a package component must not do, so visibility is the
+   `shown` prop instead: the default is the consumer build's dev mode,
+   and a consumer with a preview concept passes its own wider gate.
+   Anatomy follows Callout (box, label straddling the top rule), but the
+   rule is dashed and amber: nothing else in the system is dashed, so a
+   note cannot be mistaken for content or for a callout. */
+
+/* The label always reads "Editor's Note", with the title after a colon
+   when one is given (owner call 2026-08-27). */
+interface Props { title?: string; shown?: boolean; class?: string }
+const { title, shown = import.meta.env.MODE === "development", class: className } = Astro.props;
+const label = title ? `Editor's Note: ${title}` : "Editor's Note";
+---
+{shown && (
+  <div class:list={["editor-note", "rule-box", className]} role="note">
+    <strong class="editor-note-label boxed-label">{label}</strong>
+    <div class="editor-note-body"><slot /></div>
+  </div>
+)}
+
+<style>
+  /* Box from .rule-box; the dashed amber stroke and the margin are here. */
+  .editor-note {
+    position: relative;
+    border-style: dashed;
+    border-color: var(--accent-1);
+    margin: 30px 0;
+  }
+  .editor-note-label {
+    position: absolute;
+    top: 0;
+    left: 20px;
+    /* Center the label on the 2px top rule, not on the padding-box edge. */
+    transform: translateY(calc(-50% - 2px));
+    padding: 4px 10px;
+    font-size: var(--font-size-xs);
+    font-weight: 700;
+    text-transform: uppercase;
+    letter-spacing: 0.5px;
+    line-height: 1;
+    color: var(--accent-1-ink);
+    border-color: var(--accent-1);
+  }
+  /* Reads as an annotation, not a paragraph: a step smaller than prose. */
+  .editor-note-body {
+    position: relative;
+    font-size: var(--font-size-sm);
+    color: var(--accent-1-ink);
+  }
+  .editor-note-body > :global(:last-child) { margin-bottom: 0; }
+</style>

package/src/components/content/Palette.astro

@@ -3,8 +3,13 @@
    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. */
-interface Entry { role: string; hex: string; note?: string }
+   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 }
 const { entries, class: className } = Astro.props;
 ---
@@ -21,9 +26,9 @@ const { entries, class: className } = Astro.props;
     <tbody>
       {entries.map((e) => (
         <tr>
-          <td><span class="palette-chip" aria-hidden="true" style={`background-color:${e.hex}`}></span></td>
+          <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><code>{e.hex}</code></td>
+          <td>{e.token ? <code data-token-hex={e.token}></code> : <code>{e.hex}</code>}</td>
           <td>{e.note}</td>
         </tr>
       ))}

package/src/scripts/ecosystem.ts

@@ -0,0 +1,273 @@
+/* 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
+   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,
+   non-empty document that contains the site's own key. Every other
+   path leaves the baseline standing, so a reader with JavaScript off,
+   a dead endpoint or a malformed payload sees a slightly stale footer
+   rather than a blank one.
+
+   The endpoint is a parameter. This package hardcodes no consumer URL. */
+
+export interface EcosystemDocEntry {
+  key: string;
+  label: string;
+  /* null: the property exists but is not deployed. Renders unlinked. */
+  href: string | null;
+  /* Ascending rank, 0 highest. */
+  priority: number;
+  family: string;
+}
+
+export interface EcosystemDocument {
+  version: number;
+  entries: EcosystemDocEntry[];
+}
+
+const SCHEMA_VERSION = 1;
+
+function isEntry(value: unknown): value is EcosystemDocEntry {
+  if (typeof value !== "object" || value === null) return false;
+  const entry = value as Record<string, unknown>;
+  return (
+    typeof entry.key === "string" && entry.key !== "" &&
+    typeof entry.label === "string" && entry.label !== "" &&
+    /* 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 !== ""
+  );
+}
+
+/** The document, or null when anything about it is unusable. */
+export function validateDocument(raw: unknown): EcosystemDocument | null {
+  if (typeof raw !== "object" || raw === null) return null;
+  const doc = raw as Record<string, unknown>;
+  if (doc.version !== SCHEMA_VERSION) return null;
+  if (!Array.isArray(doc.entries) || doc.entries.length === 0) return null;
+  /* filter, not every: a type predicate narrows the array through
+     filter and does not through every, so this is the form that hands
+     back EcosystemDocEntry[] instead of any[]. Comparing lengths is
+     what makes it a refusal rather than a silent drop of bad rows. */
+  const entries = doc.entries.filter(isEntry);
+  if (entries.length !== doc.entries.length) return null;
+  return { version: SCHEMA_VERSION, entries };
+}
+
+/** 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. */
+export function sortEntries(
+  entries: EcosystemDocEntry[],
+  selfKey: string,
+  limit: number,
+): EcosystemDocEntry[] | null {
+  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 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;
+}
+
+function entryNode(doc: Document, entry: EcosystemDocEntry, selfKey: string): HTMLElement {
+  if (entry.key === selfKey) {
+    const self = doc.createElement("span");
+    self.className = "footer-sitemap-self";
+    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 fragment = root.createDocumentFragment();
+  for (const entry of entries) {
+    const item = root.createElement("li");
+    item.append(entryNode(root, entry, selfKey));
+    fragment.append(item);
+  }
+  list.replaceChildren(fragment);
+}

package/src/shiki/code-vars.mjs

@@ -0,0 +1,33 @@
+// Shiki transformer: rewrite the code theme's baked hex values to the
+// css package's custom properties, so highlighted code follows a live
+// palette override (spec 2026-09-06, live code colors). Shiki inlines
+// literal colors on every span at build; with this transformer the
+// build emits var() instead, and the variables resolve to the exact
+// same hexes until something overrides them, so adopting it changes
+// no rendered pixel. Pass it wherever shiki options go: the transformers
+// prop of astro:components' Code, or markdown.shikiConfig.transformers
+// in a consumer's astro config.
+const HEX_TO_VAR = {
+  "#ffaa3c": "var(--code-token-keyword)",
+  "#ffd18a": "var(--code-token-function)",
+  "#e07c14": "var(--code-token-string)",
+  "#8a7a63": "var(--code-token-comment)",
+  "#e8d9c3": "var(--code-fg)",
+  "#1b140c": "var(--code-bg)",
+};
+
+function swap(node) {
+  const style = node.properties?.style;
+  if (typeof style !== "string") return;
+  node.properties.style = style.replace(/#[0-9a-fA-F]{6}/g, (hex) => HEX_TO_VAR[hex.toLowerCase()] ?? hex);
+}
+
+export default {
+  name: "half-built-code-vars",
+  pre(node) {
+    swap(node);
+  },
+  span(node) {
+    swap(node);
+  },
+};