astroidjs 0.1.1 → 0.2.0

package/src/components/Editable.astro

@@ -11,9 +11,18 @@
 //   • PAGE field  — pass `collection` + `key` + `field`; emits
 //                   `data-louise-field="<collection>:<key>:<field>"` (saved as a
 //                   versioned draft when the page is mounted with `versionedPageId`).
-//   • SECTION field — pass `sfield` (the `<index>.<path>` into the section's data,
-//                   ADR 0003 §5); emits `data-louise-sfield` (+ `data-louise-multiline`),
-//                   for the structured `<Section>` editor.
+//   • SECTION field — pass `base` (this item's path, e.g. `"2"` or `"2.blocks.0"`)
+//                   plus `field`; emits `data-louise-sfield="<base>.<field>"`
+//                   (+ `data-louise-multiline`) for the on-canvas section editor.
+//                   `sfield` stays as the escape hatch for a path you build
+//                   yourself — an array entry: sfield={`${base}.items.${i}.title`}.
+//
+// The `base` form is what ADR 0005 §2 asks for: "a site author writes `<Editable
+// field="heading">` and never hand-stamps the deeper path". `<Section>` supplies
+// `base`, so the SAME component renders correctly whether it sits at the top level
+// (`"2.heading"`) or inside a block (`"2.blocks.0.heading"`) — the depth never
+// appears in the component's source, which is what makes a section component
+// reusable as a block component.
 //
 // Polymorphic via `as` (default `div`) with a typed `...rest` over the div's
 // attributes; edit mode is read from context (`Astro.locals.editMode`) unless the
@@ -27,9 +36,14 @@ interface Props extends HTMLAttributes<"div"> {
   collection?: string;
   /** PAGE-field mode: the row key/id the field is on. */
   key?: string | number;
-  /** PAGE-field mode: the field name (e.g. `"title"`, `"body"`). */
+  /** PAGE-field mode: the field name (e.g. `"title"`, `"body"`). Also the field
+   *  name in SECTION mode, where it's joined onto `base`. */
   field?: string;
-  /** SECTION-field mode: the `<index>.<path>` marker for the section editor. */
+  /** SECTION-field mode: this item's path prefix (`"2"`, `"2.blocks.0"`),
+   *  supplied by `<Section>`. Combined with `field` to build the marker. */
+  base?: string;
+  /** SECTION-field mode, explicit: the full `<index>.<path>` marker. Overrides
+   *  `base`+`field`, for paths a component builds itself (array entries). */
   sfield?: string;
   /** Rich text (ProseKit) vs a single-line contenteditable. Default `"text"`. */
   type?: "text" | "richtext";
@@ -44,6 +58,7 @@ const {
   collection,
   key,
   field,
+  base,
   sfield,
   type = "text",
   multiline = false,
@@ -51,16 +66,25 @@ const {
   ...rest
 } = Astro.props;
 
+// An explicit `sfield` wins; otherwise `base` + `field` compose one. Both absent
+// means this isn't a section field at all, and the page-field branch below runs.
+const sectionPath = sfield ?? (base !== undefined && field ? `${base}.${field}` : undefined);
+
 const editing = edit ?? (Astro.locals as { editMode?: boolean }).editMode ?? false;
-const richText = type === "richtext" ? { "data-louise-type": "richtext" } : {};
+// Annotated rather than inferred: without it the ternary widens to a union of
+// two object shapes, one of which carries `"data-louise-type"?: undefined`, and
+// spreading that into `Record<string, string>` is a type error.
+const richText: Record<string, string> =
+  type === "richtext" ? { "data-louise-type": "richtext" } : {};
+const multilineMarker: Record<string, string> = multiline ? { "data-louise-multiline": "" } : {};
 
 let markers: Record<string, string> = {};
 if (editing) {
-  if (sfield) {
+  if (sectionPath) {
     markers = {
-      "data-louise-sfield": sfield,
+      "data-louise-sfield": sectionPath,
       ...richText,
-      ...(multiline ? { "data-louise-multiline": "" } : {}),
+      ...multilineMarker,
     };
   } else if (collection && key !== undefined && field) {
     markers = { "data-louise-field": `${collection}:${key}:${field}`, ...richText };

package/src/components/JustifiedGallery.astro

@@ -0,0 +1,254 @@
+---
+// `<JustifiedGallery>` — Flickr-style row-balanced photo grid (#257).
+//
+// Images keep their aspect ratios, rows fill the container exactly, and row
+// heights land near a target. CSS alone can't do it: `grid` wants uniform
+// tracks, and `columns` gives a masonry *column* flow where reading order runs
+// down the page instead of across it — wrong for a portfolio, and wrong for
+// keyboard/screen-reader order.
+//
+// Two layers, so it never depends on JavaScript to be usable:
+//
+//   1. SSR emits a flex-wrap floor. Each tile carries its declared aspect ratio
+//      (from the media library's recorded dimensions) as `flex-grow`/`flex-basis`,
+//      which already produces a justified, gap-correct grid with no layout shift
+//      — that's what someone with JS blocked, or on the first paint before the
+//      bundle lands, sees.
+//   2. On the client, once the images decode and their TRUE dimensions are known,
+//      `justifyRows` recomputes exact rows and pins each tile's box. This is the
+//      pass that fixes the common case where the media row's dimensions are
+//      missing, stale, or transposed.
+//
+// The refinement is deliberately a no-op when the declared ratios were already
+// right, so the correction isn't visible as a jump on a well-populated library.
+//
+// CSP: the layout script is a normal (bundled) `<script>`, so Astro hashes it
+// into `script-src` — no `is:inline`, no `unsafe-inline`. Per-tile sizing is
+// written as inline `style`, which is what the `style-src` rewrite in #253
+// exists for.
+import { DEFAULT_ASPECT, type GalleryItem } from "./justify.js";
+import MediaSlot from "./MediaSlot.astro";
+
+interface Props {
+  items: GalleryItem[];
+  /** Row height to aim for, in px. Default 260. */
+  targetHeight?: number;
+  /** Gap between tiles, in px. Default 8. */
+  gap?: number;
+  /** Fade/rise tiles in as they scroll into view. Default true; automatically
+   *  inert under `prefers-reduced-motion`. */
+  reveal?: boolean;
+  class?: string;
+}
+
+const { items, targetHeight = 260, gap = 8, reveal = true, class: className } = Astro.props;
+
+const aspectOf = (item: GalleryItem) =>
+  item.width && item.height && item.height > 0 ? item.width / item.height : DEFAULT_ASPECT;
+---
+
+<div
+  class:list={["astroid-gallery", reveal && "astroid-gallery--reveal", className]}
+  data-astroid-gallery
+  data-target-height={targetHeight}
+  data-gap={gap}
+  style={`--astroid-gallery-gap:${gap}px;--astroid-gallery-row:${targetHeight}px`}
+>
+  {items.map((item) => {
+    const aspect = aspectOf(item);
+    const media = (
+      <MediaSlot
+        src={item.src}
+        alt={item.alt}
+        width={Math.round(targetHeight * aspect * 2)}
+        sizes={`${Math.round(targetHeight * aspect)}px`}
+        loading="lazy"
+      />
+    );
+    return (
+      <figure
+        class="astroid-gallery__tile"
+        data-aspect={aspect}
+        style={`flex-grow:${aspect};flex-basis:${Math.round(aspect * targetHeight)}px`}
+      >
+        {/* Always a <figure>, with the link INSIDE it: <figcaption> is only
+            valid as a child of <figure>, so wrapping the whole tile in an <a>
+            would emit invalid markup whenever a linked tile has a caption. */}
+        {item.href ? (
+          <a
+            href={item.href}
+            class="astroid-gallery__link"
+            {...(item.alt ? {} : { "aria-label": item.caption ?? "View image" })}
+          >
+            {media}
+          </a>
+        ) : (
+          media
+        )}
+        {item.caption && <figcaption class="astroid-gallery__caption">{item.caption}</figcaption>}
+      </figure>
+    );
+  })}
+</div>
+
+<style>
+  .astroid-gallery {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--astroid-gallery-gap, 8px);
+  }
+  .astroid-gallery__tile {
+    display: block;
+    position: relative;
+    /* The floor: height fixed to the target row, width proportional to aspect.
+       flex-grow then stretches each row to fill. Once the script takes over it
+       writes explicit width/height and these stop mattering. */
+    height: var(--astroid-gallery-row, 260px);
+    overflow: hidden;
+    text-decoration: none;
+    margin: 0;
+  }
+  .astroid-gallery__link {
+    display: block;
+    width: 100%;
+    height: 100%;
+  }
+  .astroid-gallery__tile :global(.astroid-media),
+  .astroid-gallery__tile :global(.astroid-media > img) {
+    width: 100%;
+    height: 100%;
+  }
+  .astroid-gallery__caption {
+    position: absolute;
+    inset-inline: 0;
+    bottom: 0;
+    padding: 0.5rem 0.75rem;
+    font-size: 0.8125rem;
+    color: #fff;
+    background: linear-gradient(transparent, rgb(0 0 0 / 0.6));
+  }
+
+  /* Reveal-on-scroll. The visible state is the DEFAULT so that a browser with
+     no IntersectionObserver — or no JS at all — shows every tile; the script
+     opts tiles into the hidden state only once it can guarantee it will undo it. */
+  .astroid-gallery--reveal .astroid-gallery__tile[data-reveal="pending"] {
+    opacity: 0;
+    transform: translateY(12px);
+  }
+  .astroid-gallery--reveal .astroid-gallery__tile {
+    transition:
+      opacity 400ms ease,
+      transform 400ms ease;
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .astroid-gallery--reveal .astroid-gallery__tile {
+      transition: none;
+    }
+    .astroid-gallery--reveal .astroid-gallery__tile[data-reveal="pending"] {
+      opacity: 1;
+      transform: none;
+    }
+  }
+</style>
+
+<script>
+  import { justifyRows } from "./justify.js";
+
+  /**
+   * Lay out one gallery precisely, using whatever dimensions are known right
+   * now. Called on mount, after each image decodes, and on resize.
+   */
+  function layout(root: HTMLElement) {
+    const tiles = [...root.querySelectorAll<HTMLElement>(".astroid-gallery__tile")];
+    if (tiles.length === 0) return;
+
+    const targetHeight = Number(root.dataset.targetHeight) || 260;
+    const gap = Number(root.dataset.gap) || 8;
+    // clientWidth excludes the scrollbar, which offsetWidth does not — using the
+    // wrong one overflows the row by the scrollbar width on Windows.
+    const containerWidth = root.clientWidth;
+
+    const rows = justifyRows(
+      tiles.map((tile) => ({ aspect: Number(tile.dataset.aspect) || 0 })),
+      { containerWidth, targetHeight, gap },
+    );
+    // No measurable width yet (hidden tab, display:none ancestor). Leave the CSS
+    // floor in place rather than writing zero-size boxes over it.
+    if (rows.length === 0) return;
+
+    for (const row of rows) {
+      for (const box of row.boxes) {
+        const tile = tiles[box.index];
+        tile.style.flex = "0 0 auto";
+        tile.style.width = `${box.width}px`;
+        tile.style.height = `${box.height}px`;
+      }
+    }
+  }
+
+  /** Correct a tile's aspect ratio from the decoded image, then re-lay out. */
+  function refineFromDecode(root: HTMLElement) {
+    const images = [...root.querySelectorAll<HTMLImageElement>(".astroid-gallery__tile img")];
+    let pending = images.length;
+    if (pending === 0) return;
+
+    const settle = (img: HTMLImageElement) => {
+      const tile = img.closest<HTMLElement>(".astroid-gallery__tile");
+      if (tile && img.naturalWidth > 0 && img.naturalHeight > 0) {
+        tile.dataset.aspect = String(img.naturalWidth / img.naturalHeight);
+      }
+      // Re-lay out once the batch settles rather than per image: a 60-image
+      // gallery would otherwise run 60 full layouts during load.
+      if (--pending === 0) layout(root);
+    };
+
+    for (const img of images) {
+      if (img.complete) settle(img);
+      else {
+        img.addEventListener("load", () => settle(img), { once: true });
+        // A broken image still has to release the counter, or the refinement
+        // pass never runs and the gallery keeps its declared ratios forever.
+        img.addEventListener("error", () => settle(img), { once: true });
+      }
+    }
+  }
+
+  function revealOnScroll(root: HTMLElement) {
+    if (!root.classList.contains("astroid-gallery--reveal")) return;
+    if (typeof IntersectionObserver === "undefined") return;
+    if (window.matchMedia?.("(prefers-reduced-motion: reduce)").matches) return;
+
+    const tiles = [...root.querySelectorAll<HTMLElement>(".astroid-gallery__tile")];
+    // Only hide tiles now that an observer is guaranteed to reveal them.
+    for (const tile of tiles) tile.dataset.reveal = "pending";
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (!entry.isIntersecting) continue;
+          (entry.target as HTMLElement).dataset.reveal = "shown";
+          observer.unobserve(entry.target);
+        }
+      },
+      { rootMargin: "64px" },
+    );
+    for (const tile of tiles) observer.observe(tile);
+  }
+
+  for (const root of document.querySelectorAll<HTMLElement>("[data-astroid-gallery]")) {
+    layout(root);
+    refineFromDecode(root);
+    revealOnScroll(root);
+
+    if (typeof ResizeObserver !== "undefined") {
+      let frame = 0;
+      // Coalesce to one layout per animation frame — a drag-resize fires this
+      // continuously, and each run touches every tile's style.
+      const observer = new ResizeObserver(() => {
+        cancelAnimationFrame(frame);
+        frame = requestAnimationFrame(() => layout(root));
+      });
+      observer.observe(root);
+    }
+  }
+</script>

package/src/components/MediaSlot.astro

@@ -0,0 +1,178 @@
+---
+// `<MediaSlot>` — the responsive-image primitive (#257).
+//
+// One place that knows how to put a media-library image on a page correctly:
+// a width-descriptor `srcset` over Cloudflare Image Resizing, a `sizes` hint so
+// the browser picks the right derivative *before* layout, a reserved aspect-ratio
+// box so the image can't shift the page as it loads, and lazy/async decoding by
+// default.
+//
+// The math is not new — `louise-toolkit/media` already ships `cfImageSrcset`
+// (width descriptors, ratio-derived heights, cover-crop gravity, `format=auto`)
+// and `circleImage`. What every consuming site rebuilt by hand was the *component*
+// around it: the ratio box, the `sizes` string, the focal-point crop, and
+// remembering that `loading="lazy"` on an above-the-fold hero is a Largest
+// Contentful Paint regression. That's what this owns.
+//
+// CSP: the focal/zoom knobs emit a data-driven inline `style` attribute. That is
+// exactly the case astroid's middleware rewrites `style-src` for (#253) — scripts
+// stay hash-pinned with no `unsafe-inline`.
+import { cfImageSrcset, circleImage } from "louise-toolkit/media";
+import type { HTMLAttributes } from "astro/types";
+
+interface Props extends Omit<HTMLAttributes<"img">, "src" | "srcset" | "sizes" | "width" | "height"> {
+  /** Image URL — a media-library asset, or any URL on a resizing-enabled zone. */
+  src: string;
+  /**
+   * Alternative text. REQUIRED, and `""` is a legitimate value: an image that
+   * carries no information the surrounding copy doesn't already give (a
+   * decorative texture, a repeated brand mark) should be `alt=""` so screen
+   * readers skip it. What must never happen is the attribute going missing,
+   * which makes assistive tech read the filename aloud.
+   */
+  alt: string;
+  /**
+   * The largest width, in CSS px, this image is displayed at on a 1× screen.
+   * Drives the srcset ladder — not a hard render width.
+   */
+  width?: number;
+  /**
+   * The `sizes` attribute: how wide the image renders at each breakpoint, e.g.
+   * `"(max-width: 640px) 100vw, 33vw"`. Without it the browser assumes `100vw`
+   * and over-fetches on every multi-column layout, which is the single most
+   * common way a "responsive" image ends up slower than a fixed one.
+   */
+  sizes?: string;
+  /** Aspect ratio as `"w/h"` (e.g. `"16/9"`). Reserves the box and derives each
+   *  derivative's height so the crop matches what's shown — no wasted pixels. */
+  ratio?: string;
+  /** `rect` (default) or `circle`. A circle uses a square focal crop + 2× retina. */
+  shape?: "rect" | "circle";
+  /** Rendered diameter in px when `shape="circle"`. Default 96. */
+  size?: number;
+  /** Resize behaviour. Default `cover`. */
+  fit?: "cover" | "contain" | "scale-down" | "crop" | "pad";
+  /** Focal point for cover-crops. Default `auto` (Cloudflare picks the subject). */
+  gravity?: "auto" | "center" | "left" | "right" | "top" | "bottom";
+  /** Encode quality, 1–100. Default 82. */
+  quality?: number;
+  /**
+   * Focal point as percentages, for when `gravity: auto` picks wrong — a portrait
+   * where the subject sits high, say. Applied as `object-position`, so it's a
+   * render-time framing choice and the same derivative is reused.
+   */
+  focal?: { x: number; y: number };
+  /** Scale factor inside the box, for a punch-in crop. Default 1. */
+  zoom?: number;
+  /**
+   * `lazy` (default) or `eager`. Set `eager` — and `priority` — for anything
+   * above the fold: lazy-loading the LCP image delays it by a full network
+   * round-trip after layout.
+   */
+  loading?: "lazy" | "eager";
+  /** Hint this as the LCP candidate (sets `fetchpriority="high"`). */
+  priority?: boolean;
+  /** Optional caption; renders a `<figure>`/`<figcaption>` instead of a bare img. */
+  caption?: string;
+  /** Extra classes on the wrapper. */
+  class?: string;
+}
+
+const {
+  src,
+  alt,
+  width = 1200,
+  sizes,
+  ratio,
+  shape = "rect",
+  size = 96,
+  fit = "cover",
+  gravity = "auto",
+  quality = 82,
+  focal,
+  zoom = 1,
+  loading = "lazy",
+  priority = false,
+  caption,
+  class: className,
+  ...rest
+} = Astro.props;
+
+const circle = shape === "circle";
+const derived = circle
+  ? circleImage(src, size)
+  : cfImageSrcset(src, { width, ratio, fit, gravity, quality });
+
+// Without a `sizes` hint the browser assumes the image fills the viewport and
+// picks the largest candidate. A circle's rendered width is known exactly, so
+// state it; a rect defaults to its 1× width, which is right for a fixed-width
+// placement and should be overridden for a fluid one.
+const sizesAttr = sizes ?? (circle ? `${size}px` : `${width}px`);
+
+// Framing lives on the <img>: `object-position` moves the visible window of a
+// cover-crop, `scale` punches in. Both are per-placement, so they must NOT go
+// through the CDN — that would mint a second derivative of the same source.
+const frame = [
+  focal ? `object-position:${focal.x}% ${focal.y}%` : "",
+  zoom !== 1 ? `transform:scale(${zoom})` : "",
+]
+  .filter(Boolean)
+  .join(";");
+
+// Reserve the box before the bytes arrive. Skipping this is what makes a gallery
+// jump as it loads (Cumulative Layout Shift); `aspect-ratio` costs nothing and
+// fixes it outright.
+const boxStyle = circle
+  ? `width:${size}px;height:${size}px`
+  : ratio
+    ? `aspect-ratio:${ratio.replace("/", " / ")}`
+    : "";
+
+const img = {
+  src: derived.src,
+  srcset: derived.srcset,
+  // A circle's srcset uses DPR descriptors (`1x`/`2x`), which `sizes` does not
+  // apply to — supplying it there would be ignored at best and confusing at worst.
+  ...(circle ? {} : { sizes: sizesAttr }),
+  alt,
+  loading,
+  decoding: "async" as const,
+  ...(priority ? { fetchpriority: "high" as const } : {}),
+  ...(frame ? { style: frame } : {}),
+};
+---
+
+{caption ? (
+  <figure class:list={["astroid-media", circle && "astroid-media--circle", className]} style={boxStyle} {...rest}>
+    <img {...img} />
+    <figcaption>{caption}</figcaption>
+  </figure>
+) : (
+  <div class:list={["astroid-media", circle && "astroid-media--circle", className]} style={boxStyle} {...rest}>
+    <img {...img} />
+  </div>
+)}
+
+<style>
+  .astroid-media {
+    display: block;
+    overflow: hidden;
+    margin: 0;
+  }
+  .astroid-media > img {
+    display: block;
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+  }
+  /* The mask lives on the wrapper, not the image, so `transform: scale()` from
+     `zoom` is clipped by the circle instead of escaping it. */
+  .astroid-media--circle {
+    border-radius: 9999px;
+  }
+  .astroid-media > figcaption {
+    margin-top: 0.5rem;
+    font-size: 0.875rem;
+    opacity: 0.7;
+  }
+</style>

package/src/components/PortalShell.astro

@@ -0,0 +1,80 @@
+---
+// `<PortalShell>` — the account-area chrome: a sidebar of nav items and a main
+// column, collapsing to a burger on small screens.
+//
+// Theme-tokened, never brand-styled. Every colour here is a daisyUI token
+// (`base-100`, `base-content`, `primary`), so it inherits whatever theme the
+// project's `theme.colors` generated and a site can restyle it by changing the
+// theme rather than forking the component.
+//
+// The burger is a `<details>` element, not a Solid island: the portal's chrome
+// shouldn't ship or await JavaScript to open a menu, and `<details>` gets
+// keyboard behaviour, focus handling, and Escape from the browser for free.
+import type { PortalNav } from "astroidjs";
+
+interface Props {
+  nav: PortalNav;
+  /** The signed-in user's role — decides which nav items are visible. */
+  role?: string | null;
+  /** Current path, for the active highlight. Defaults to the rendered URL. */
+  path?: string;
+  /** Heading above the nav, e.g. the account holder's name. */
+  title?: string;
+}
+
+const { nav, role, path, title } = Astro.props;
+const current = path ?? Astro.url.pathname;
+
+// Filtered by role BEFORE render: an item the viewer can't reach is never
+// drawn, rather than drawn and then 403'd — which reads as a broken link.
+const items = nav.forRole(role);
+const active = nav.activeFor(current);
+---
+
+<div class="flex min-h-screen flex-col md:flex-row">
+  {/* Mobile: a disclosure. No island, no hydration wait. */}
+  <details class="md:hidden border-b border-base-300 bg-base-200">
+    <summary class="cursor-pointer list-none px-4 py-3 font-medium">
+      <span aria-hidden="true">☰</span>
+      <span class="ml-2">{active?.label ?? title ?? "Menu"}</span>
+    </summary>
+    <nav aria-label="Portal" class="px-2 pb-3">
+      <ul class="menu w-full">
+        {
+          items.map((item) => (
+            <li>
+              <a href={item.href} aria-current={item === active ? "page" : undefined}>
+                {item.label}
+              </a>
+            </li>
+          ))
+        }
+      </ul>
+    </nav>
+  </details>
+
+  <aside class="hidden md:flex md:w-64 md:shrink-0 md:flex-col border-r border-base-300 bg-base-200">
+    {title && <p class="px-4 pt-5 pb-2 text-sm font-semibold opacity-70">{title}</p>}
+    <nav aria-label="Portal" class="p-2">
+      <ul class="menu w-full gap-1">
+        {
+          items.map((item) => (
+            <li>
+              <a
+                href={item.href}
+                class={item === active ? "menu-active font-medium" : undefined}
+                aria-current={item === active ? "page" : undefined}
+              >
+                {item.label}
+              </a>
+            </li>
+          ))
+        }
+      </ul>
+    </nav>
+  </aside>
+
+  <main class="min-w-0 flex-1 bg-base-100 px-4 py-6 md:px-8 md:py-10">
+    <slot />
+  </main>
+</div>

package/src/components/RegisterSW.astro

@@ -0,0 +1,45 @@
+---
+// `<RegisterSW>` — registers the PWA service worker.
+//
+// A bundled `<script>`, never an inline one: Astro hashes it into `script-src`,
+// so this works under the strict CSP without `unsafe-inline`. That's also why
+// the scope rides on a `data-` attribute rather than being interpolated into
+// the script — `define:vars` forces `is:inline`, whose content varies per
+// render and therefore can't be hashed.
+//
+// Registration is best-effort by design. A service worker is an enhancement:
+// if it fails, or the browser has none, the app must still work. The one thing
+// worth being loud about is a worker that fails to *install* while claiming to
+// be there, which is why the catch logs rather than swallowing silently.
+interface Props {
+  /**
+   * URL prefix this worker controls. Must match the `scope` the manifest and
+   * the generated worker were built with.
+   *
+   * A scope narrower than the script's own location needs no
+   * `Service-Worker-Allowed` header; a broader one does. With `sw.js` served
+   * from the root, every scope is narrower, so no header is required.
+   */
+  scope?: string;
+  /** Path to the worker. Default `/sw.js`. */
+  src?: string;
+}
+
+const { scope = "/", src = "/sw.js" } = Astro.props;
+---
+
+<div data-astroid-sw hidden data-scope={scope} data-src={src}></div>
+
+<script>
+  const el = document.querySelector<HTMLElement>("[data-astroid-sw]");
+  if (el && "serviceWorker" in navigator) {
+    navigator.serviceWorker
+      .register(el.dataset.src ?? "/sw.js", { scope: el.dataset.scope ?? "/" })
+      .catch((error) => {
+        // Not fatal — the app works without it. Logged rather than swallowed so
+        // a scope/MIME misconfiguration is findable instead of just "the PWA
+        // doesn't install and nobody knows why".
+        console.warn("[astroid] service worker registration failed", error);
+      });
+  }
+</script>