From 7dfb8183693563c9add680b26a6b3ae6e23025b5 Mon Sep 17 00:00:00 2001
From: important-new <important-new@hotmail.com>
Date: Mon, 20 Jul 2026 16:01:46 +0800
Subject: [PATCH 01/12] feat(shared-ui): add RadioCardGroup card-style
 single-select primitive

---
 .../shared-ui/src/RadioCardGroup.test.tsx     |  61 +++++++++
 packages/shared-ui/src/RadioCardGroup.tsx     | 123 ++++++++++++++++++
 packages/shared-ui/src/index.ts               |   1 +
 3 files changed, 185 insertions(+)
 create mode 100644 packages/shared-ui/src/RadioCardGroup.test.tsx
 create mode 100644 packages/shared-ui/src/RadioCardGroup.tsx

diff --git a/packages/shared-ui/src/RadioCardGroup.test.tsx b/packages/shared-ui/src/RadioCardGroup.test.tsx
new file mode 100644
index 00000000..88f18d02
--- /dev/null
+++ b/packages/shared-ui/src/RadioCardGroup.test.tsx
@@ -0,0 +1,61 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { render, cleanup, fireEvent, screen } from "@testing-library/react";
+import { RadioCardGroup } from "./RadioCardGroup";
+
+afterEach(cleanup);
+
+const OPTS = [
+  { value: "own", title: "Bring your own", description: "You pay rates directly." },
+  { value: "shared", title: "Managed shared", description: "No setup.", badge: "included" },
+  { value: "dedicated", title: "Managed dedicated", description: "Your own number." },
+];
+
+describe("RadioCardGroup", () => {
+  it("renders every option title, description and badge", () => {
+    render(<RadioCardGroup name="m" value="own" onChange={() => {}} options={OPTS} />);
+    expect(screen.getByText("Bring your own")).toBeTruthy();
+    expect(screen.getByText("You pay rates directly.")).toBeTruthy();
+    expect(screen.getByText("included")).toBeTruthy();
+  });
+
+  it("checks the option matching value and exposes radiogroup semantics", () => {
+    render(<RadioCardGroup name="m" value="shared" onChange={() => {}} options={OPTS} legend="Delivery" />);
+    expect(screen.getByRole("radiogroup")).toBeTruthy();
+    const radios = screen.getAllByRole("radio") as HTMLInputElement[];
+    expect(radios[0].checked).toBe(false);
+    expect(radios[1].checked).toBe(true);
+    // Selected card carries the canonical active token.
+    const selectedCard = radios[1].closest("label")!;
+    expect(selectedCard.className).toContain("border-ih-primary");
+    expect(selectedCard.className).toContain("bg-ih-primary/5");
+  });
+
+  it("calls onChange with the value when a card is selected", () => {
+    const onChange = vi.fn();
+    render(<RadioCardGroup name="m" value="own" onChange={onChange} options={OPTS} />);
+    fireEvent.click(screen.getByText("Managed dedicated"));
+    expect(onChange).toHaveBeenCalledWith("dedicated");
+  });
+
+  it("moves selection with arrow keys", () => {
+    const onChange = vi.fn();
+    render(<RadioCardGroup name="m" value="own" onChange={onChange} options={OPTS} />);
+    const radios = screen.getAllByRole("radio");
+    fireEvent.keyDown(radios[0], { key: "ArrowDown" });
+    expect(onChange).toHaveBeenLastCalledWith("shared");
+  });
+
+  it("does not select a disabled option", () => {
+    const onChange = vi.fn();
+    const opts = [OPTS[0], { ...OPTS[1], disabled: true }];
+    render(<RadioCardGroup name="m" value="own" onChange={onChange} options={opts} />);
+    const radios = screen.getAllByRole("radio") as HTMLInputElement[];
+    expect(radios[1].disabled).toBe(true);
+  });
+
+  it("renders error over hint when both are present", () => {
+    render(<RadioCardGroup name="m" value="own" onChange={() => {}} options={OPTS} error="Required" hint="Pick one" />);
+    expect(screen.getByText("Required")).toBeTruthy();
+    expect(screen.queryByText("Pick one")).toBeNull();
+  });
+});
diff --git a/packages/shared-ui/src/RadioCardGroup.tsx b/packages/shared-ui/src/RadioCardGroup.tsx
new file mode 100644
index 00000000..e440b09c
--- /dev/null
+++ b/packages/shared-ui/src/RadioCardGroup.tsx
@@ -0,0 +1,123 @@
+import React from "react";
+import { cn } from "./cn";
+
+export interface RadioCardOption {
+  value: string;
+  title: React.ReactNode;
+  description?: React.ReactNode;
+  badge?: React.ReactNode;
+  disabled?: boolean;
+}
+
+interface RadioCardGroupProps {
+  name: string;
+  value: string;
+  onChange: (value: string) => void;
+  options: RadioCardOption[];
+  legend?: React.ReactNode;
+  error?: string;
+  hint?: string;
+  className?: string;
+}
+
+/**
+ * Design System card-style single-select. A vertical stack of bordered cards,
+ * each a native <label>/<input type="radio"> for form association + a11y, with
+ * a title, optional description, and optional badge. The selected card lifts to
+ * `border-ih-primary bg-ih-primary/5`. Use when each option needs a description
+ * or badge; for short bare labels use SegmentedControl or RadioGroup.
+ *
+ * Keyboard: Arrow/Home/End move selection (WAI-ARIA radiogroup), skipping
+ * disabled options.
+ */
+export function RadioCardGroup({
+  name,
+  value,
+  onChange,
+  options,
+  legend,
+  error,
+  hint,
+  className = "",
+}: RadioCardGroupProps) {
+  const inputRefs = React.useRef<(HTMLInputElement | null)[]>([]);
+
+  function selectFrom(index: number, dir: 1 | -1) {
+    const n = options.length;
+    for (let step = 1; step <= n; step++) {
+      const i = (((index + dir * step) % n) + n) % n;
+      if (!options[i].disabled) {
+        onChange(options[i].value);
+        inputRefs.current[i]?.focus();
+        return;
+      }
+    }
+  }
+
+  function onKeyDown(e: React.KeyboardEvent<HTMLInputElement>, index: number) {
+    switch (e.key) {
+      case "ArrowDown":
+      case "ArrowRight":
+        e.preventDefault();
+        selectFrom(index, 1);
+        break;
+      case "ArrowUp":
+      case "ArrowLeft":
+        e.preventDefault();
+        selectFrom(index, -1);
+        break;
+    }
+  }
+
+  return (
+    <fieldset role="radiogroup" className={cn("flex flex-col gap-2", className)}>
+      {legend && (
+        <legend className="block text-[10px] font-bold uppercase tracking-[0.2em] text-ih-fg-3 mb-1">
+          {legend}
+        </legend>
+      )}
+      {options.map((o, i) => {
+        const active = o.value === value;
+        return (
+          <label
+            key={o.value}
+            className={cn(
+              "flex items-start gap-3 p-3 rounded-md border cursor-pointer transition-colors",
+              active
+                ? "border-ih-primary bg-ih-primary/5"
+                : "border-ih-border bg-ih-bg-card hover:border-ih-primary/40",
+              o.disabled && "opacity-60 cursor-not-allowed",
+            )}
+          >
+            <input
+              ref={(el) => {
+                inputRefs.current[i] = el;
+              }}
+              type="radio"
+              name={name}
+              value={o.value}
+              checked={active}
+              disabled={o.disabled}
+              onChange={() => onChange(o.value)}
+              onKeyDown={(e) => onKeyDown(e, i)}
+              className="mt-0.5 h-4 w-4 accent-ih-primary shrink-0 focus:outline-none focus:shadow-ih-focus"
+            />
+            <span className="flex-1 min-w-0">
+              <span className="block text-[13px] font-bold text-ih-fg-1">
+                {o.title}
+                {o.badge != null && (
+                  <span className="font-normal text-ih-ok-fg"> {o.badge}</span>
+                )}
+              </span>
+              {o.description != null && (
+                <span className="block text-[11px] text-ih-fg-3 mt-0.5">{o.description}</span>
+              )}
+            </span>
+          </label>
+        );
+      })}
+      {error && <p className="text-[11px] text-ih-bad-fg mt-1">{error}</p>}
+      {!error && hint && <p className="text-[11px] text-ih-fg-4 mt-1">{hint}</p>}
+    </fieldset>
+  );
+}
diff --git a/packages/shared-ui/src/index.ts b/packages/shared-ui/src/index.ts
index d288b1b2..09bed0fb 100644
--- a/packages/shared-ui/src/index.ts
+++ b/packages/shared-ui/src/index.ts
@@ -11,6 +11,7 @@ export { Select, type SelectOption } from "./Select";
 export { Textarea } from "./Textarea";
 export { Checkbox } from "./Checkbox";
 export { Radio, RadioGroup, type RadioOption } from "./Radio";
+export { RadioCardGroup, type RadioCardOption } from "./RadioCardGroup";
 export { EmptyState } from "./EmptyState";
 export { Skeleton } from "./Skeleton";
 export { Card } from "./Card";

From 5f34752da805642e1cc094bcf2803a79ca794bed Mon Sep 17 00:00:00 2001
From: important-new <important-new@hotmail.com>
Date: Mon, 20 Jul 2026 16:07:32 +0800
Subject: [PATCH 02/12] feat: add useScrollSpy hook for settings section-nav

---
 app/hooks/useScrollSpy.test.tsx | 40 ++++++++++++++++++++++++++++++
 app/hooks/useScrollSpy.ts       | 44 +++++++++++++++++++++++++++++++++
 2 files changed, 84 insertions(+)
 create mode 100644 app/hooks/useScrollSpy.test.tsx
 create mode 100644 app/hooks/useScrollSpy.ts

diff --git a/app/hooks/useScrollSpy.test.tsx b/app/hooks/useScrollSpy.test.tsx
new file mode 100644
index 00000000..535d9809
--- /dev/null
+++ b/app/hooks/useScrollSpy.test.tsx
@@ -0,0 +1,40 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { render, cleanup, act } from "@testing-library/react";
+import { useScrollSpy } from "./useScrollSpy";
+
+afterEach(cleanup);
+
+function Harness({ ids, tops }: { ids: string[]; tops: Record<string, number> }) {
+  const rootRef = { current: document.body as HTMLElement };
+  // Stub getBoundingClientRect per section id so the hook math is deterministic.
+  ids.forEach((id) => {
+    let el = document.getElementById(id);
+    if (!el) {
+      el = document.createElement("div");
+      el.id = id;
+      document.body.appendChild(el);
+    }
+    el.getBoundingClientRect = () =>
+      ({ top: tops[id], bottom: tops[id] + 10, height: 10 }) as DOMRect;
+  });
+  const active = useScrollSpy(ids, { getRoot: () => rootRef.current, topOffset: 60 });
+  return <span data-testid="active">{active ?? "none"}</span>;
+}
+
+describe("useScrollSpy", () => {
+  it("returns the last section whose top is at or above the offset line", () => {
+    // a is above the 60px line (top=10), b is below (top=200) -> active is a.
+    const { getByTestId } = render(
+      <Harness ids={["a", "b", "c"]} tops={{ a: 10, b: 200, c: 400 }} />,
+    );
+    act(() => {
+      document.body.dispatchEvent(new Event("scroll"));
+    });
+    expect(getByTestId("active").textContent).toBe("a");
+  });
+
+  it("returns null for an empty id list", () => {
+    const { getByTestId } = render(<Harness ids={[]} tops={{}} />);
+    expect(getByTestId("active").textContent).toBe("none");
+  });
+});
diff --git a/app/hooks/useScrollSpy.ts b/app/hooks/useScrollSpy.ts
new file mode 100644
index 00000000..1f121fed
--- /dev/null
+++ b/app/hooks/useScrollSpy.ts
@@ -0,0 +1,44 @@
+import { useEffect, useState } from "react";
+
+/**
+ * Tracks which section id is "current" within a scroll container. A section is
+ * current when its top has scrolled at or above `topOffset` px from the root's
+ * top; the current section is the last such one. Uses a passive scroll
+ * listener on the resolved root (falls back to window). Returns the first id
+ * until a scroll settles, or null when there are no ids.
+ */
+export function useScrollSpy(
+  ids: string[],
+  opts: { getRoot: () => HTMLElement | null; topOffset: number },
+): string | null {
+  const { getRoot, topOffset } = opts;
+  const [active, setActive] = useState<string | null>(ids[0] ?? null);
+  const key = ids.join("|");
+
+  useEffect(() => {
+    if (ids.length === 0) {
+      setActive(null);
+      return;
+    }
+    const root = getRoot();
+    const scroller: HTMLElement | Window = root ?? window;
+    const rootTop = root ? root.getBoundingClientRect().top : 0;
+
+    function compute() {
+      let current = ids[0];
+      for (const id of ids) {
+        const el = document.getElementById(id);
+        if (!el) continue;
+        const relTop = el.getBoundingClientRect().top - rootTop;
+        if (relTop <= topOffset) current = id;
+      }
+      setActive(current);
+    }
+
+    compute();
+    scroller.addEventListener("scroll", compute, { passive: true });
+    return () => scroller.removeEventListener("scroll", compute);
+  }, [key, getRoot, topOffset]);
+
+  return active;
+}

From 0ca70d295355feefdfddc8e7f39933deed977e9b Mon Sep 17 00:00:00 2001
From: important-new <important-new@hotmail.com>
Date: Mon, 20 Jul 2026 16:11:44 +0800
Subject: [PATCH 03/12] feat: add SectionNav sticky scroll-spy nav for settings
 pages

---
 app/components/settings/SectionNav.test.tsx | 59 ++++++++++++++++++++
 app/components/settings/SectionNav.tsx      | 62 +++++++++++++++++++++
 2 files changed, 121 insertions(+)
 create mode 100644 app/components/settings/SectionNav.test.tsx
 create mode 100644 app/components/settings/SectionNav.tsx

diff --git a/app/components/settings/SectionNav.test.tsx b/app/components/settings/SectionNav.test.tsx
new file mode 100644
index 00000000..933a3e39
--- /dev/null
+++ b/app/components/settings/SectionNav.test.tsx
@@ -0,0 +1,59 @@
+import { describe, it, expect, vi, afterEach, beforeEach } from "vitest";
+import { render, cleanup, fireEvent, screen } from "@testing-library/react";
+import { SectionNav } from "./SectionNav";
+
+afterEach(cleanup);
+beforeEach(() => {
+  // happy-dom lacks real scroll methods; stub them so spies/calls don't throw.
+  Element.prototype.scrollTo = vi.fn() as unknown as typeof Element.prototype.scrollTo;
+  Element.prototype.scrollIntoView = vi.fn() as unknown as typeof Element.prototype.scrollIntoView;
+});
+
+describe("SectionNav", () => {
+  it("renders nothing when fewer than 3 sections are visible", () => {
+    const { container } = render(
+      <SectionNav
+        sections={[
+          { id: "a", label: "A" },
+          { id: "b", label: "B", visible: false },
+          { id: "c", label: "C", visible: false },
+        ]}
+      />,
+    );
+    expect(container.firstChild).toBeNull();
+  });
+
+  it("renders a tab per visible section", () => {
+    render(
+      <SectionNav
+        sections={[
+          { id: "a", label: "Alpha" },
+          { id: "b", label: "Bravo" },
+          { id: "c", label: "Charlie", visible: false },
+          { id: "d", label: "Delta" },
+        ]}
+      />,
+    );
+    expect(screen.getByText("Alpha")).toBeTruthy();
+    expect(screen.getByText("Bravo")).toBeTruthy();
+    expect(screen.getByText("Delta")).toBeTruthy();
+    expect(screen.queryByText("Charlie")).toBeNull();
+  });
+
+  it("scrolls the target section into the scroll container on tab click", () => {
+    const target = document.createElement("div");
+    target.id = "b";
+    document.body.appendChild(target);
+    render(
+      <SectionNav
+        sections={[
+          { id: "a", label: "Alpha" },
+          { id: "b", label: "Bravo" },
+          { id: "d", label: "Delta" },
+        ]}
+      />,
+    );
+    fireEvent.click(screen.getByText("Bravo"));
+    expect(target.scrollIntoView).toHaveBeenCalled();
+  });
+});
diff --git a/app/components/settings/SectionNav.tsx b/app/components/settings/SectionNav.tsx
new file mode 100644
index 00000000..a063a14d
--- /dev/null
+++ b/app/components/settings/SectionNav.tsx
@@ -0,0 +1,62 @@
+import React from "react";
+import { TabStrip } from "@core/shared-ui";
+import { useScrollSpy } from "~/hooks/useScrollSpy";
+
+export interface NavSection {
+  id: string;
+  label: string;
+  visible?: boolean;
+}
+
+/** Height (px) of the sticky bar; consumers set matching `scroll-mt` on sections. */
+export const SECTION_NAV_BAR_HEIGHT = 52;
+
+function nearestScrollParent(el: HTMLElement | null): HTMLElement | null {
+  let node = el?.parentElement ?? null;
+  while (node) {
+    const oy = getComputedStyle(node).overflowY;
+    if (oy === "auto" || oy === "scroll") return node;
+    node = node.parentElement;
+  }
+  return null;
+}
+
+export function SectionNav({
+  sections,
+  className = "",
+}: {
+  sections: NavSection[];
+  className?: string;
+}): JSX.Element | null {
+  const rootRef = React.useRef<HTMLDivElement | null>(null);
+  const visible = sections.filter((s) => s.visible !== false);
+  const ids = visible.map((s) => s.id);
+
+  const getRoot = React.useCallback(() => nearestScrollParent(rootRef.current), []);
+  const activeId = useScrollSpy(ids, { getRoot, topOffset: SECTION_NAV_BAR_HEIGHT }) ?? ids[0];
+
+  // Hooks must run unconditionally; bail out on render only.
+  if (visible.length < 3) return null;
+
+  function onChange(id: string) {
+    const el = document.getElementById(id);
+    if (!el) return;
+    const reduce =
+      typeof window !== "undefined" &&
+      window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
+    el.scrollIntoView({ behavior: reduce ? "auto" : "smooth", block: "start" });
+  }
+
+  return (
+    <div
+      ref={rootRef}
+      className={`sticky top-0 z-20 -mx-1 px-1 bg-ih-bg-app ${className}`}
+    >
+      <TabStrip
+        tabs={visible.map((s) => ({ id: s.id, label: s.label }))}
+        activeId={activeId}
+        onChange={onChange}
+      />
+    </div>
+  );
+}

From 5eebe56ad690d1f1ae218f6e2ebfb6f8d7431981 Mon Sep 17 00:00:00 2001
From: important-new <important-new@hotmail.com>
Date: Mon, 20 Jul 2026 18:19:15 +0800
Subject: [PATCH 04/12] feat(settings): sticky section-nav on communication
 page (closes #250)

- SectionNav wired into settings-communication with 6 anchored sections
  (conditional email-secrets / managed-compliance drop out of the nav).
- Fix shared app shell: remove overflow-y-auto from auth-layout <main>. It
  grew to content height and never scrolled, so it was a non-scrolling
  scroll-container that broke position:sticky (bar scrolled away) and stopped
  the scroll-spy listener from firing. The window is the real scroller.
- useScrollSpy listens on window with capture:true so it fires regardless of
  which element scrolls (scroll events don't bubble).
- E2E: renders, click-jump + scroll-spy highlight, sticky-pinned.
---
 app/components/settings/SectionNav.test.tsx  |   1 +
 app/components/settings/SectionNav.tsx       |  14 +-
 app/hooks/useScrollSpy.ts                    |  14 +-
 app/routes/auth-layout.tsx                   |   2 +-
 app/routes/settings-communication.tsx        | 178 +++++++++++--------
 messages/en/settings-integrations.json       |   2 +
 playwright.config.ts                         |   2 +
 scripts/file-size-baseline.json              |   2 +-
 tests/e2e/settings-communication-nav.spec.ts |  67 +++++++
 9 files changed, 197 insertions(+), 85 deletions(-)
 create mode 100644 tests/e2e/settings-communication-nav.spec.ts

diff --git a/app/components/settings/SectionNav.test.tsx b/app/components/settings/SectionNav.test.tsx
index 933a3e39..06b2c0f0 100644
--- a/app/components/settings/SectionNav.test.tsx
+++ b/app/components/settings/SectionNav.test.tsx
@@ -34,6 +34,7 @@ describe("SectionNav", () => {
         ]}
       />,
     );
+    expect(screen.getByRole("navigation", { name: "Section navigation" })).toBeTruthy();
     expect(screen.getByText("Alpha")).toBeTruthy();
     expect(screen.getByText("Bravo")).toBeTruthy();
     expect(screen.getByText("Delta")).toBeTruthy();
diff --git a/app/components/settings/SectionNav.tsx b/app/components/settings/SectionNav.tsx
index a063a14d..ebb6b43a 100644
--- a/app/components/settings/SectionNav.tsx
+++ b/app/components/settings/SectionNav.tsx
@@ -8,8 +8,14 @@ export interface NavSection {
   visible?: boolean;
 }
 
-/** Height (px) of the sticky bar; consumers set matching `scroll-mt` on sections. */
-export const SECTION_NAV_BAR_HEIGHT = 52;
+/**
+ * Scroll-spy activation line (px from viewport top). A section becomes "current"
+ * once its top scrolls above this line. Sits comfortably below the 48px anchor
+ * offset (`scroll-mt-12`, which every consumer section must set so its heading
+ * clears the sticky bar on jump) so a jumped-to section — which lands at 48px —
+ * is unambiguously current, with no sub-pixel boundary flicker.
+ */
+const SPY_ACTIVATION_OFFSET = 80;
 
 function nearestScrollParent(el: HTMLElement | null): HTMLElement | null {
   let node = el?.parentElement ?? null;
@@ -33,7 +39,7 @@ export function SectionNav({
   const ids = visible.map((s) => s.id);
 
   const getRoot = React.useCallback(() => nearestScrollParent(rootRef.current), []);
-  const activeId = useScrollSpy(ids, { getRoot, topOffset: SECTION_NAV_BAR_HEIGHT }) ?? ids[0];
+  const activeId = useScrollSpy(ids, { getRoot, topOffset: SPY_ACTIVATION_OFFSET }) ?? ids[0];
 
   // Hooks must run unconditionally; bail out on render only.
   if (visible.length < 3) return null;
@@ -50,6 +56,8 @@ export function SectionNav({
   return (
     <div
       ref={rootRef}
+      role="navigation"
+      aria-label="Section navigation"
       className={`sticky top-0 z-20 -mx-1 px-1 bg-ih-bg-app ${className}`}
     >
       <TabStrip
diff --git a/app/hooks/useScrollSpy.ts b/app/hooks/useScrollSpy.ts
index 1f121fed..2e14f071 100644
--- a/app/hooks/useScrollSpy.ts
+++ b/app/hooks/useScrollSpy.ts
@@ -3,9 +3,11 @@ import { useEffect, useState } from "react";
 /**
  * Tracks which section id is "current" within a scroll container. A section is
  * current when its top has scrolled at or above `topOffset` px from the root's
- * top; the current section is the last such one. Uses a passive scroll
- * listener on the resolved root (falls back to window). Returns the first id
- * until a scroll settles, or null when there are no ids.
+ * top; the current section is the last such one. `getRoot` only sets the offset
+ * reference (viewport when it returns null); the scroll listener is always a
+ * capture-phase window listener so it fires regardless of which element scrolls
+ * (scroll events don't bubble). Returns the first id until a scroll settles, or
+ * null when there are no ids.
  */
 export function useScrollSpy(
   ids: string[],
@@ -21,7 +23,6 @@ export function useScrollSpy(
       return;
     }
     const root = getRoot();
-    const scroller: HTMLElement | Window = root ?? window;
     const rootTop = root ? root.getBoundingClientRect().top : 0;
 
     function compute() {
@@ -36,8 +37,9 @@ export function useScrollSpy(
     }
 
     compute();
-    scroller.addEventListener("scroll", compute, { passive: true });
-    return () => scroller.removeEventListener("scroll", compute);
+    // capture:true catches scroll from any scroller (events don't bubble).
+    window.addEventListener("scroll", compute, { passive: true, capture: true });
+    return () => window.removeEventListener("scroll", compute, { capture: true } as EventListenerOptions);
   }, [key, getRoot, topOffset]);
 
   return active;
diff --git a/app/routes/auth-layout.tsx b/app/routes/auth-layout.tsx
index d14da924..d940a1af 100644
--- a/app/routes/auth-layout.tsx
+++ b/app/routes/auth-layout.tsx
@@ -79,7 +79,7 @@ export default function AuthLayout() {
       <MobileHeader />
       <div className="flex min-h-screen">
         <Sidebar />
-        <main className="flex-1 w-full bg-ih-bg-app overflow-y-auto">
+        <main className="flex-1 w-full bg-ih-bg-app">
           {/* ds-allow: page bottom gutter (60px), bespoke page-shell spacing with no token */}
           <div className="max-w-[1080px] mx-auto pt-5 pb-[60px] px-9">
             {showSkeleton ? (
diff --git a/app/routes/settings-communication.tsx b/app/routes/settings-communication.tsx
index edd755cc..0697cde1 100644
--- a/app/routes/settings-communication.tsx
+++ b/app/routes/settings-communication.tsx
@@ -19,6 +19,7 @@ import { EmailSecretsPanel } from "~/components/settings/EmailSecretsPanel";
 import { SmsDeliveryPanel, type SmsModeValue } from "~/components/settings/SmsDeliveryPanel";
 import { GoogleCalendarPanel } from "~/components/settings/GoogleCalendarPanel";
 import { ManagedComplianceWizard, type ManagedComplianceData } from "~/components/settings/ManagedComplianceWizard";
+import { SectionNav } from "~/components/settings/SectionNav";
 import { parseTestResults } from "~/lib/connection-test";
 import { m } from "~/paraglide/messages";
 
@@ -605,6 +606,19 @@ export default function SettingsCommunication() {
 
   if (denied) return <AccessDenied />;
 
+  const navSections = [
+    { id: "email-delivery", label: m.settings_emaildelivery_heading() },
+    { id: "email-secrets", label: m.settings_emailsecrets_heading(), visible: !isSaas || mode === "own" },
+    { id: "sms-delivery", label: m.settings_smsdelivery_heading() },
+    {
+      id: "managed-compliance",
+      label: m.settings_comms_nav_managed(),
+      visible: isSaas && (smsMode === "managed_dedicated" || smsMode === "managed_shared"),
+    },
+    { id: "email-templates", label: m.settings_comms_email_templates_heading() },
+    { id: "google-calendar", label: m.settings_comms_nav_calendar() },
+  ];
+
   return (
     <div className="space-y-ih-list">
       <SettingsCrumb items={[{ label: m.settings_crumb_root(), href: "/settings" }, { label: m.settings_comms_crumb() }]} />
@@ -619,41 +633,49 @@ export default function SettingsCommunication() {
         </div>
       )}
 
+      {/* In-page section navigation (sticky; scroll-spy). Shows only when ≥3 sections visible. */}
+      <SectionNav sections={navSections} />
+
       {/* Email delivery config */}
-      <EmailDeliveryPanel
-        config={config}
-        isSaas={isSaas}
-        emailByoProvider={emailByoProvider}
-        ownProviderConfigured={ownProviderConfigured}
-        mode={mode}
-        setMode={setMode}
-        overrideName={overrideName}
-        setOverrideName={setOverrideName}
-        poc={poc}
-        setPoc={setPoc}
-        emailForm={emailForm}
-        emailFields={emailFields}
-        secretFormError={secretFormError}
-      />
+      <div id="email-delivery" className="scroll-mt-12">
+        <EmailDeliveryPanel
+          config={config}
+          isSaas={isSaas}
+          emailByoProvider={emailByoProvider}
+          ownProviderConfigured={ownProviderConfigured}
+          mode={mode}
+          setMode={setMode}
+          overrideName={overrideName}
+          setOverrideName={setOverrideName}
+          poc={poc}
+          setPoc={setPoc}
+          emailForm={emailForm}
+          emailFields={emailFields}
+          secretFormError={secretFormError}
+        />
+      </div>
 
       {/* Email API keys — BYO only (hidden when SaaS platform email is selected) */}
       {(!isSaas || mode === "own") && (
-        <EmailSecretsPanel
-          secrets={secrets}
-          secretFieldError={secretFieldError}
-          secretFormError={secretFormError}
-          savingEmailSecrets={savingEmailSecrets}
-          resendTestFetcher={resendTestFetcher}
-          resendTest={resendTest}
-          emailValidateFetcher={emailValidateFetcher}
-          initialProvider={emailByoProvider}
-          webhookBaseUrl={typeof window !== "undefined" ? window.location.origin : ""}
-          tenantSlug={tenantSlug}
-          testResults={testResults}
-        />
+        <div id="email-secrets" className="scroll-mt-12">
+          <EmailSecretsPanel
+            secrets={secrets}
+            secretFieldError={secretFieldError}
+            secretFormError={secretFormError}
+            savingEmailSecrets={savingEmailSecrets}
+            resendTestFetcher={resendTestFetcher}
+            resendTest={resendTest}
+            emailValidateFetcher={emailValidateFetcher}
+            initialProvider={emailByoProvider}
+            webhookBaseUrl={typeof window !== "undefined" ? window.location.origin : ""}
+            tenantSlug={tenantSlug}
+            testResults={testResults}
+          />
+        </div>
       )}
 
       {/* SMS delivery (Track L) */}
+      <div id="sms-delivery" className="scroll-mt-12">
       <SmsDeliveryPanel
         isSaas={isSaas}
         smsMode={smsMode}
@@ -672,47 +694,53 @@ export default function SettingsCommunication() {
         byoProvider={byoProvider}
         testResults={testResults}
       />
+      </div>
+
+      {/* Managed compliance (SaaS only) — dedicated wizard or shared-pool note */}
+      {isSaas && (smsMode === "managed_dedicated" || smsMode === "managed_shared") && (
+        <div id="managed-compliance" className="scroll-mt-12">
+          {/* Managed dedicated — onboarding wizard + status timeline */}
+          {smsMode === "managed_dedicated" && (
+            <section className="bg-ih-bg-card border border-ih-border rounded-lg p-5 space-y-4">
+              <h3 className="text-[13px] font-bold uppercase tracking-[0.15em] text-ih-fg-3">{m.settings_comms_dedicated_heading()}</h3>
+              <p className="text-[13px] text-ih-fg-3">
+                {m.settings_comms_dedicated_desc()}
+              </p>
+              <ManagedComplianceWizard
+                compliance={compliance}
+                managedProvider={managedProvider}
+                savingManagedProvider={savingManagedProvider}
+                actionError={
+                  actionData &&
+                  "intent" in actionData &&
+                  (actionData.intent === "sms-compliance-provision" || actionData.intent === "sms-compliance-resubmit") &&
+                  "ok" in actionData &&
+                  !actionData.ok
+                    ? actionData.error ?? null
+                    : null
+                }
+                saving={savingCompliance}
+              />
+            </section>
+          )}
 
-      {/* Managed dedicated — onboarding wizard + status timeline (SaaS only) */}
-      {isSaas && smsMode === "managed_dedicated" && (
-        <section className="bg-ih-bg-card border border-ih-border rounded-lg p-5 space-y-4">
-          <h3 className="text-[13px] font-bold uppercase tracking-[0.15em] text-ih-fg-3">{m.settings_comms_dedicated_heading()}</h3>
-          <p className="text-[13px] text-ih-fg-3">
-            {m.settings_comms_dedicated_desc()}
-          </p>
-          <ManagedComplianceWizard
-            compliance={compliance}
-            managedProvider={managedProvider}
-            savingManagedProvider={savingManagedProvider}
-            actionError={
-              actionData &&
-              "intent" in actionData &&
-              (actionData.intent === "sms-compliance-provision" || actionData.intent === "sms-compliance-resubmit") &&
-              "ok" in actionData &&
-              !actionData.ok
-                ? actionData.error ?? null
-                : null
-            }
-            saving={savingCompliance}
-          />
-        </section>
-      )}
-
-      {/* Managed shared — minimal status note (SaaS only, no per-tenant form) */}
-      {isSaas && smsMode === "managed_shared" && (
-        <section className="bg-ih-bg-card border border-ih-border rounded-lg p-5">
-          <h3 className="text-[13px] font-bold uppercase tracking-[0.15em] text-ih-fg-3 mb-2">{m.settings_comms_shared_pool_heading()}</h3>
-          <p className="text-[13px] text-ih-fg-3">
-            {m.settings_comms_shared_pool_desc()}
-          </p>
-          {compliance.complianceStatus === "approved" && (
-            <p className="text-[12px] text-ih-ok-fg font-medium mt-2">{m.settings_comms_shared_pool_active()}</p>
+          {/* Managed shared — minimal status note (no per-tenant form) */}
+          {smsMode === "managed_shared" && (
+            <section className="bg-ih-bg-card border border-ih-border rounded-lg p-5">
+              <h3 className="text-[13px] font-bold uppercase tracking-[0.15em] text-ih-fg-3 mb-2">{m.settings_comms_shared_pool_heading()}</h3>
+              <p className="text-[13px] text-ih-fg-3">
+                {m.settings_comms_shared_pool_desc()}
+              </p>
+              {compliance.complianceStatus === "approved" && (
+                <p className="text-[12px] text-ih-ok-fg font-medium mt-2">{m.settings_comms_shared_pool_active()}</p>
+              )}
+            </section>
           )}
-        </section>
+        </div>
       )}
 
       {/* Email templates */}
-      <section className="space-y-4">
+      <section id="email-templates" className="space-y-4 scroll-mt-12">
         <div className="flex items-baseline justify-between">
           <h3 className="text-[13px] font-bold uppercase tracking-[0.15em] text-ih-fg-3">{m.settings_comms_email_templates_heading()}</h3>
           <div className="flex items-center gap-3">
@@ -730,16 +758,18 @@ export default function SettingsCommunication() {
       </section>
 
       {/* Company-level Google OAuth app configuration */}
-      <GoogleCalendarPanel
-        isSaas={isSaas}
-        googleOAuthConfigured={googleOAuthConfigured}
-        googleOAuthMode={googleOAuthMode}
-        secrets={secrets}
-        secretFieldError={secretFieldError}
-        secretFormError={secretFormError}
-        savingCalendarSecrets={savingCalendarSecrets}
-        savingOAuthMode={savingGoogleOAuthMode}
-      />
+      <div id="google-calendar" className="scroll-mt-12">
+        <GoogleCalendarPanel
+          isSaas={isSaas}
+          googleOAuthConfigured={googleOAuthConfigured}
+          googleOAuthMode={googleOAuthMode}
+          secrets={secrets}
+          secretFieldError={secretFieldError}
+          secretFormError={secretFormError}
+          savingCalendarSecrets={savingCalendarSecrets}
+          savingOAuthMode={savingGoogleOAuthMode}
+        />
+      </div>
     </div>
   );
 }
diff --git a/messages/en/settings-integrations.json b/messages/en/settings-integrations.json
index 891528d9..a9095885 100644
--- a/messages/en/settings-integrations.json
+++ b/messages/en/settings-integrations.json
@@ -14,6 +14,8 @@
   "settings_error_generic": "An error occurred.",
   "settings_comms_meta_title": "Communication - Settings - OpenInspection",
   "settings_comms_intro": "Configure email delivery, templates, and calendar sync.",
+  "settings_comms_nav_managed": "Managed SMS",
+  "settings_comms_nav_calendar": "Google Calendar",
   "settings_comms_email_save_error": "Failed to save email settings.",
   "settings_comms_provider_save_error": "Failed to save provider selection.",
   "settings_comms_email_secrets_save_error": "Failed to save email secrets.",
diff --git a/playwright.config.ts b/playwright.config.ts
index 87e2e93c..8ecfecc7 100644
--- a/playwright.config.ts
+++ b/playwright.config.ts
@@ -206,6 +206,8 @@ export default defineConfig({
         // the shared admin + a real inspection id (the `api` project it in
         // turn depends on already seeds the 8 default role profiles).
         { name: 'people-role-profiles', testMatch: 'people-role-profiles.spec.ts', dependencies: ['editor-seed'] },
+        // Issue #250 — settings-communication sticky section-nav (scroll-spy).
+        { name: 'settings-communication-nav', testMatch: 'settings-communication-nav.spec.ts', dependencies: ['editor-seed'] },
         // Spec 2 Task 8 — role-aware report sending (final task of the
         // role-aware-sending plan). Seeds its own template + inspection (does
         // NOT reuse the shared editor-seed fixture — it flips that
diff --git a/scripts/file-size-baseline.json b/scripts/file-size-baseline.json
index b69056bf..20767473 100644
--- a/scripts/file-size-baseline.json
+++ b/scripts/file-size-baseline.json
@@ -9,9 +9,9 @@
   "server/lib/collab/results-doc.ts": 874,
   "server/index.ts": 867,
   "server/api/sms.ts": 824,
+  "app/routes/settings-communication.tsx": 776,
   "app/components/portal/sections/ReportView.tsx": 770,
   "server/services/inspection.service.ts": 747,
-  "app/routes/settings-communication.tsx": 746,
   "app/routes/settings-communication-templates.tsx": 724,
   "app/routes/template-edit.tsx": 701,
   "app/components/media-studio/PhotoAnnotator.tsx": 692,
diff --git a/tests/e2e/settings-communication-nav.spec.ts b/tests/e2e/settings-communication-nav.spec.ts
new file mode 100644
index 00000000..6eb77761
--- /dev/null
+++ b/tests/e2e/settings-communication-nav.spec.ts
@@ -0,0 +1,67 @@
+/**
+ * Settings → Communication sticky section-nav (issue #250).
+ *
+ * Verifies the SectionNav: it renders (>=3 sections visible in standalone),
+ * clicking a tab jumps to its section AND scroll-spy highlights it, and the bar
+ * stays pinned to the viewport while scrolling. Uses the shared editor-seed
+ * admin for login. Reduced-motion is emulated so the tab-jump scroll is instant
+ * (deterministic) rather than a smooth animation.
+ */
+import { test, expect } from '@playwright/test';
+import { readEditorSeed } from './helpers/editor-seed';
+
+let adminEmail = '';
+let adminPassword = '';
+
+test.describe.serial('Settings → Communication sticky section-nav (#250)', () => {
+  test.beforeAll(() => {
+    const seed = readEditorSeed();
+    test.skip(!seed, 'editor-seed handoff missing — run with the editor-seed setup project.');
+    adminEmail = seed!.email;
+    adminPassword = seed!.password;
+  });
+
+  test.beforeEach(async ({ page }) => {
+    await page.emulateMedia({ reducedMotion: 'reduce' });
+    await page.goto('/login');
+    await page.fill('input[name=email]', adminEmail);
+    await page.fill('input[name=password]', adminPassword);
+    await page.click('button[type=submit]');
+    await page.waitForURL('**/inspections');
+    await page.goto('/settings/communication');
+  });
+
+  test('renders a labeled nav with a tab per visible section', async ({ page }) => {
+    const nav = page.getByRole('navigation', { name: 'Section navigation' });
+    await expect(nav).toBeVisible();
+    await expect(nav.getByRole('button', { name: 'Email delivery', exact: true })).toBeVisible();
+    await expect(nav.getByRole('button', { name: 'SMS delivery', exact: true })).toBeVisible();
+    await expect(nav.getByRole('button', { name: 'Google Calendar', exact: true })).toBeVisible();
+  });
+
+  test('clicking a tab jumps to its section and scroll-spy highlights it', async ({ page }) => {
+    const smsTab = page.getByRole('navigation', { name: 'Section navigation' })
+      .getByRole('button', { name: 'SMS delivery', exact: true });
+
+    // On load the first section's tab is the active one.
+    await expect(
+      page.getByRole('navigation', { name: 'Section navigation' })
+        .getByRole('button', { name: 'Email delivery', exact: true }),
+    ).toHaveClass(/text-ih-primary/);
+
+    // Click SMS delivery: its section jumps under the bar and its tab activates.
+    await smsTab.click();
+    await expect(page.locator('#sms-delivery')).toBeInViewport({ ratio: 0.2 });
+    await expect(smsTab).toHaveClass(/text-ih-primary/);
+  });
+
+  test('sticky bar stays pinned to the viewport while scrolling', async ({ page }) => {
+    await page.evaluate(() => window.scrollTo(0, 1200));
+    const navTop = await page
+      .getByRole('navigation', { name: 'Section navigation' })
+      .evaluate((el) => Math.round(el.getBoundingClientRect().top));
+    // The sticky bar must remain within the top band of the viewport.
+    expect(navTop).toBeGreaterThanOrEqual(0);
+    expect(navTop).toBeLessThan(60);
+  });
+});

From e9a7d6f4315a2c43597c42d8dba2132b071641a7 Mon Sep 17 00:00:00 2001
From: important-new <important-new@hotmail.com>
Date: Mon, 20 Jul 2026 18:32:48 +0800
Subject: [PATCH 05/12] feat(settings): sticky section-nav on 6 more long
 settings pages
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Wire SectionNav into workspace (7), security (7), schedule (6), booking (5),
advanced (4), profile (4). Each section gets a stable id + scroll-mt-12 anchor;
labels reuse existing panel/section heading messages. Conditional sections
(schedule availability-heatmap) carry a visible flag so they drop out of the nav
when absent. Billing deferred — its sections are small/conditional and rarely
reach the >=3 threshold that shows the bar.
---
 app/routes/settings-advanced.tsx  | 65 ++++++++++++++++----------
 app/routes/settings-booking.tsx   | 62 +++++++++++++++++--------
 app/routes/settings-profile.tsx   | 19 ++++++--
 app/routes/settings-schedule.tsx  | 77 ++++++++++++++++++++-----------
 app/routes/settings-security.tsx  | 60 ++++++++++++++++--------
 app/routes/settings-workspace.tsx | 27 ++++++++---
 scripts/file-size-baseline.json   |  6 +--
 7 files changed, 213 insertions(+), 103 deletions(-)

diff --git a/app/routes/settings-advanced.tsx b/app/routes/settings-advanced.tsx
index 92288d55..b6d302e7 100644
--- a/app/routes/settings-advanced.tsx
+++ b/app/routes/settings-advanced.tsx
@@ -12,6 +12,7 @@ import { AccessDenied } from "~/components/AccessDenied";
 import { StripeConnectPanel } from "~/components/settings/advanced/StripeConnectPanel";
 import { AiFeaturesPanel } from "~/components/settings/advanced/AiFeaturesPanel";
 import { IntegrationKeysPanel } from "~/components/settings/advanced/IntegrationKeysPanel";
+import { SectionNav } from "~/components/settings/SectionNav";
 import { parseTestResults } from "~/lib/connection-test";
 import { m } from "~/paraglide/messages";
 
@@ -223,6 +224,13 @@ export default function SettingsAdvancedPage() {
     return undefined;
   };
 
+  const navSections = [
+    { id: "stripe-connect", label: m.settings_stripeconnect_heading() },
+    { id: "ai-features", label: m.settings_ai_heading() },
+    { id: "integration-keys", label: m.settings_intkeys_heading() },
+    { id: "data", label: m.settings_advanced_data_heading() },
+  ];
+
   return (
     <div className="space-y-ih-list max-w-3xl">
       <SettingsCrumb items={[{ label: m.settings_crumb_root(), href: "/settings" }, { label: m.settings_advanced_crumb() }]} />
@@ -244,37 +252,46 @@ export default function SettingsAdvancedPage() {
         </div>
       ) : null}
 
+      {/* In-page section navigation (sticky; scroll-spy). Shows only when ≥3 sections visible. */}
+      <SectionNav sections={navSections} />
+
       {/* Stripe Connect */}
-      <StripeConnectPanel
-        stripeConnected={config.stripeConnected}
-        stripeAccountId={config.stripeAccountId}
-        stripeForm={stripeForm}
-        stripeFields={stripeFields}
-      />
+      <div id="stripe-connect" className="scroll-mt-12">
+        <StripeConnectPanel
+          stripeConnected={config.stripeConnected}
+          stripeAccountId={config.stripeAccountId}
+          stripeForm={stripeForm}
+          stripeFields={stripeFields}
+        />
+      </div>
 
       {/* AI features */}
-      <AiFeaturesPanel
-        geminiConfigured={config.geminiConfigured}
-        value={secrets.GEMINI_API_KEY}
-        fieldError={secretFieldError}
-        saving={savingAi}
-        geminiTestFetcher={geminiTestFetcher}
-        testResults={testResults}
-      />
+      <div id="ai-features" className="scroll-mt-12">
+        <AiFeaturesPanel
+          geminiConfigured={config.geminiConfigured}
+          value={secrets.GEMINI_API_KEY}
+          fieldError={secretFieldError}
+          saving={savingAi}
+          geminiTestFetcher={geminiTestFetcher}
+          testResults={testResults}
+        />
+      </div>
 
       {/* Integration API keys */}
-      <IntegrationKeysPanel
-        secrets={{
-          GOOGLE_PLACES_API_KEY: secrets.GOOGLE_PLACES_API_KEY,
-          ESTATED_API_KEY: secrets.ESTATED_API_KEY,
-          APP_BASE_URL: secrets.APP_BASE_URL,
-        }}
-        fieldError={secretFieldError}
-        saving={savingAdvanced}
-      />
+      <div id="integration-keys" className="scroll-mt-12">
+        <IntegrationKeysPanel
+          secrets={{
+            GOOGLE_PLACES_API_KEY: secrets.GOOGLE_PLACES_API_KEY,
+            ESTATED_API_KEY: secrets.ESTATED_API_KEY,
+            APP_BASE_URL: secrets.APP_BASE_URL,
+          }}
+          fieldError={secretFieldError}
+          saving={savingAdvanced}
+        />
+      </div>
 
       {/* Data import/export */}
-      <section className="bg-ih-bg-card rounded-lg border border-ih-border p-6 space-y-5">
+      <section id="data" className="bg-ih-bg-card rounded-lg border border-ih-border p-6 space-y-5 scroll-mt-12">
         <h3 className="text-[11px] font-bold text-ih-fg-2 uppercase tracking-[0.2em]">{m.settings_advanced_data_heading()}</h3>
         <p className="text-[13px] text-ih-fg-3">
           {m.settings_advanced_data_desc()}
diff --git a/app/routes/settings-booking.tsx b/app/routes/settings-booking.tsx
index dc9b0a7e..9ec0213e 100644
--- a/app/routes/settings-booking.tsx
+++ b/app/routes/settings-booking.tsx
@@ -9,6 +9,7 @@ import { BookingPoliciesPanel } from "~/components/settings/BookingPoliciesPanel
 import { EmbedWidgetPanel } from "~/components/settings/EmbedWidgetPanel";
 import { ManageTeamSchedulesBar } from "~/components/settings/ManageTeamSchedulesBar";
 import { CompanyBookingLinksPanel } from "~/components/settings/CompanyBookingLinksPanel";
+import { SectionNav } from "~/components/settings/SectionNav";
 import {
   BookingSlotRulesPanel,
   type BookingSlotIntervalMin,
@@ -243,6 +244,14 @@ export default function SettingsBookingPage() {
     (SCHEDULING_ROLES as readonly string[]).includes(m.role),
   );
 
+  const navSections = [
+    { id: "booking-links", label: m.settings_companylink_heading() },
+    { id: "booking-policies", label: m.settings_policies_heading() },
+    { id: "holidays", label: m.settings_holiday_panel_heading() },
+    { id: "slot-rules", label: m.settings_slotrules_heading() },
+    { id: "embed-widget", label: m.settings_embed_heading() },
+  ];
+
   return (
     <div className="space-y-ih-list">
       <SettingsCrumb items={[{ label: m.settings_crumb_settings(), href: "/settings" }, { label: m.settings_booking_crumb() }]} />
@@ -250,29 +259,42 @@ export default function SettingsBookingPage() {
         {m.settings_booking_intro()}
       </p>
 
+      {/* In-page section navigation (sticky; scroll-spy). Shows only when ≥3 sections visible. */}
+      <SectionNav sections={navSections} />
+
       <ManageTeamSchedulesBar
         members={schedulingMembers.map((m) => ({ id: m.id, email: m.email }))}
       />
-      <CompanyBookingLinksPanel tenant={tenant} />
-      <BookingPoliciesPanel initialConfig={data.config} />
-      <HolidayClosedPanel
-        initialConfig={{
-          holidayRegion: data.config.holidayRegion,
-          holidayPublicPolicy: data.config.holidayPublicPolicy,
-          holidayInternalPolicy: data.config.holidayInternalPolicy,
-          conciergeReviewRequired: data.config.conciergeReviewRequired,
-        }}
-        initialCustomHolidays={data.customHolidays}
-        dataMaxYear={data.holidayDataMaxYear}
-        currentYear={data.currentYear}
-      />
-      <BookingSlotRulesPanel
-        initial={{
-          bookingSlotMode: data.config.bookingSlotMode,
-          bookingSlotIntervalMin: data.config.bookingSlotIntervalMin,
-        }}
-      />
-      <EmbedWidgetPanel tenant={tenant} />
+      <div id="booking-links" className="scroll-mt-12">
+        <CompanyBookingLinksPanel tenant={tenant} />
+      </div>
+      <div id="booking-policies" className="scroll-mt-12">
+        <BookingPoliciesPanel initialConfig={data.config} />
+      </div>
+      <div id="holidays" className="scroll-mt-12">
+        <HolidayClosedPanel
+          initialConfig={{
+            holidayRegion: data.config.holidayRegion,
+            holidayPublicPolicy: data.config.holidayPublicPolicy,
+            holidayInternalPolicy: data.config.holidayInternalPolicy,
+            conciergeReviewRequired: data.config.conciergeReviewRequired,
+          }}
+          initialCustomHolidays={data.customHolidays}
+          dataMaxYear={data.holidayDataMaxYear}
+          currentYear={data.currentYear}
+        />
+      </div>
+      <div id="slot-rules" className="scroll-mt-12">
+        <BookingSlotRulesPanel
+          initial={{
+            bookingSlotMode: data.config.bookingSlotMode,
+            bookingSlotIntervalMin: data.config.bookingSlotIntervalMin,
+          }}
+        />
+      </div>
+      <div id="embed-widget" className="scroll-mt-12">
+        <EmbedWidgetPanel tenant={tenant} />
+      </div>
     </div>
   );
 }
diff --git a/app/routes/settings-profile.tsx b/app/routes/settings-profile.tsx
index fbfc3161..e3ff7b29 100644
--- a/app/routes/settings-profile.tsx
+++ b/app/routes/settings-profile.tsx
@@ -15,6 +15,7 @@ import { makeProfileSchema } from "~/lib/forms/settings.schema";
 import { Select } from "@core/shared-ui";
 import { TIMEZONE_SELECT_OPTIONS } from "~/lib/timezones";
 import { LOCALE_OPTIONS } from "~/lib/locales";
+import { SectionNav } from "~/components/settings/SectionNav";
 import { m } from "~/paraglide/messages";
 
 /* ------------------------------------------------------------------ */
@@ -183,11 +184,21 @@ export default function SettingsProfilePage() {
     && "intent" in sigFetcher.data && sigFetcher.data.intent === "save-signature"
     ? (sigFetcher.data.error as string) : null;
 
+  const navSections = [
+    { id: "profile-details", label: m.settings_profile_crumb() },
+    { id: "photo", label: m.settings_profile_photo_heading() },
+    { id: "signature", label: m.settings_profile_signature_heading() },
+    { id: "saved-signature", label: m.settings_profile_saved_signature_heading() },
+  ];
+
   return (
     <div className="space-y-ih-list">
       <SettingsCrumb items={[{ label: m.settings_crumb_settings(), href: "/settings" }, { label: m.settings_profile_crumb() }]} />
       <p className="text-[13px] text-ih-fg-3">{m.settings_profile_subtitle()}</p>
 
+      {/* In-page section navigation (sticky; scroll-spy). Shows only when ≥3 sections visible. */}
+      <SectionNav sections={navSections} />
+
       {/* Flash */}
       {flashSuccess && (
         <div className="px-4 py-2.5 rounded-md bg-ih-ok-bg border border-ih-ok-fg/20 text-[13px] text-ih-ok-fg font-medium">
@@ -208,7 +219,7 @@ export default function SettingsProfilePage() {
         className="space-y-5"
       >
         {/* Identity fields */}
-        <section className="bg-ih-bg-card rounded-lg border border-ih-border p-6 space-y-6">
+        <section id="profile-details" className="bg-ih-bg-card rounded-lg border border-ih-border p-6 space-y-6 scroll-mt-12">
           <div className="grid grid-cols-1 md:grid-cols-3 gap-5">
             <div className="space-y-2">
               <label htmlFor={fields.name.id} className="block text-[11px] font-bold text-ih-fg-2 uppercase tracking-[0.2em]">{m.settings_profile_name_label()}</label>
@@ -288,7 +299,7 @@ export default function SettingsProfilePage() {
             now lives in Settings → Booking ("Your links"). */}
 
         {/* Photo placeholder */}
-        <section className="bg-ih-bg-card rounded-lg border border-ih-border p-6 space-y-5">
+        <section id="photo" className="bg-ih-bg-card rounded-lg border border-ih-border p-6 space-y-5 scroll-mt-12">
           <header className="space-y-1">
             <h3 className="text-[11px] font-bold text-ih-fg-2 uppercase tracking-[0.2em]">{m.settings_profile_photo_heading()}</h3>
             <p className="text-[12px] text-ih-fg-3">{m.settings_profile_photo_subtitle()}</p>
@@ -324,7 +335,7 @@ export default function SettingsProfilePage() {
         </section>
 
         {/* Email signature (business-card footer) — independent of Point of Contact */}
-        <section className="bg-ih-bg-card rounded-lg border border-ih-border p-6 space-y-4">
+        <section id="signature" className="bg-ih-bg-card rounded-lg border border-ih-border p-6 space-y-4 scroll-mt-12">
           <header className="space-y-1">
             <h3 className="text-[11px] font-bold text-ih-fg-2 uppercase tracking-[0.2em]">{m.settings_profile_signature_heading()}</h3>
             <p className="text-[12px] text-ih-fg-3">
@@ -359,7 +370,7 @@ export default function SettingsProfilePage() {
       </Form>
 
       {/* Saved signature */}
-      <section className="bg-ih-bg-card rounded-lg border border-ih-border p-6 space-y-5">
+      <section id="saved-signature" className="bg-ih-bg-card rounded-lg border border-ih-border p-6 space-y-5 scroll-mt-12">
         <header className="space-y-1">
           <h3 className="text-[11px] font-bold text-ih-fg-2 uppercase tracking-[0.2em]">{m.settings_profile_saved_signature_heading()}</h3>
           <p className="text-[12px] text-ih-fg-3">
diff --git a/app/routes/settings-schedule.tsx b/app/routes/settings-schedule.tsx
index 3f2f218e..0438fc89 100644
--- a/app/routes/settings-schedule.tsx
+++ b/app/routes/settings-schedule.tsx
@@ -24,6 +24,7 @@ import {
 } from "~/components/settings/CalendarConnectPanel";
 import type { CalendarPickerData } from "~/components/settings/CalendarReadSetPicker";
 import { ScheduleLinksPanel } from "~/components/settings/ScheduleLinksPanel";
+import { SectionNav } from "~/components/settings/SectionNav";
 import { m } from "~/paraglide/messages";
 
 interface AvailabilitySlot {
@@ -330,6 +331,15 @@ export default function SettingsSchedulePage() {
     ? data.members.filter((m) => (SCHEDULING_ROLES as readonly string[]).includes(m.role))
     : [];
 
+  const navSections = [
+    { id: "calendar-connect", label: m.settings_calconnect_heading() },
+    { id: "weekly-schedule", label: m.settings_weekly_heading() },
+    { id: "availability-heatmap", label: m.schedule_heatmap_heading(), visible: data.weekSummary.length > 0 },
+    { id: "time-off", label: m.settings_timeoff_heading() },
+    { id: "date-overrides", label: m.settings_dateoverrides_heading() },
+    { id: "schedule-links", label: m.settings_schedlinks_heading() },
+  ];
+
   return (
     <div className="space-y-ih-list">
       <SettingsCrumb items={[{ label: m.settings_crumb_settings(), href: "/settings" }, { label: m.settings_schedule_crumb() }]} />
@@ -341,23 +351,32 @@ export default function SettingsSchedulePage() {
         <ManageOthersPicker members={pickerMembers} managedInspectorId={data.managedInspectorId} />
       )}
 
-      <CalendarConnectPanel
-        connected={data.calendar.connected}
-        capability={data.calendar.capability}
-        oauthConfigured={data.calendar.oauthConfigured}
-        disabled={data.managedInspectorId !== null}
-        picker={data.calendar.picker}
-      />
-      <WeeklySchedulePanel
-        key={data.managedInspectorId ?? "self"}
-        initialSlots={data.slots}
-        inspectorId={data.managedInspectorId}
-      />
+      {/* In-page section navigation (sticky; scroll-spy). Shows only when ≥3 sections visible. */}
+      <SectionNav sections={navSections} />
+
+      <div id="calendar-connect" className="scroll-mt-12">
+        <CalendarConnectPanel
+          connected={data.calendar.connected}
+          capability={data.calendar.capability}
+          oauthConfigured={data.calendar.oauthConfigured}
+          disabled={data.managedInspectorId !== null}
+          picker={data.calendar.picker}
+        />
+      </div>
+      <div id="weekly-schedule" className="scroll-mt-12">
+        <WeeklySchedulePanel
+          key={data.managedInspectorId ?? "self"}
+          initialSlots={data.slots}
+          inspectorId={data.managedInspectorId}
+        />
+      </div>
       {data.weekSummary.length > 0 && (
-        <section className="bg-ih-bg-card border border-ih-border rounded-lg p-5 space-y-3">
-          <h3 className="text-[13px] font-bold text-ih-fg-1">{m.schedule_heatmap_heading()}</h3>
-          <AvailabilityHeatmapWeek days={data.weekSummary} locale={locale} />
-        </section>
+        <div id="availability-heatmap" className="scroll-mt-12">
+          <section className="bg-ih-bg-card border border-ih-border rounded-lg p-5 space-y-3">
+            <h3 className="text-[13px] font-bold text-ih-fg-1">{m.schedule_heatmap_heading()}</h3>
+            <AvailabilityHeatmapWeek days={data.weekSummary} locale={locale} />
+          </section>
+        </div>
       )}
       {data.companyClosed && (
         <CompanyClosedStrip
@@ -366,16 +385,22 @@ export default function SettingsSchedulePage() {
           upcomingClosed={data.companyClosed.upcomingClosed}
         />
       )}
-      <TimeOffListPanel
-        key={`time-off-${data.managedInspectorId ?? "self"}`}
-        blocks={data.timeOffBlocks}
-      />
-      <DateOverridesPanel
-        key={`overrides-${data.managedInspectorId ?? "self"}`}
-        initialOverrides={data.overrides}
-        inspectorId={data.managedInspectorId}
-      />
-      <ScheduleLinksPanel tenant={tenant} slug={slug} />
+      <div id="time-off" className="scroll-mt-12">
+        <TimeOffListPanel
+          key={`time-off-${data.managedInspectorId ?? "self"}`}
+          blocks={data.timeOffBlocks}
+        />
+      </div>
+      <div id="date-overrides" className="scroll-mt-12">
+        <DateOverridesPanel
+          key={`overrides-${data.managedInspectorId ?? "self"}`}
+          initialOverrides={data.overrides}
+          inspectorId={data.managedInspectorId}
+        />
+      </div>
+      <div id="schedule-links" className="scroll-mt-12">
+        <ScheduleLinksPanel tenant={tenant} slug={slug} />
+      </div>
     </div>
   );
 }
diff --git a/app/routes/settings-security.tsx b/app/routes/settings-security.tsx
index 358eada4..aaa2e382 100644
--- a/app/routes/settings-security.tsx
+++ b/app/routes/settings-security.tsx
@@ -12,6 +12,7 @@ import { ChangePasswordPanel } from "~/components/settings/security/ChangePasswo
 import { TwoFactorPanel } from "~/components/settings/security/TwoFactorPanel";
 import { TurnstilePanel } from "~/components/settings/security/TurnstilePanel";
 import { DataExportPanel } from "~/components/settings/security/DataExportPanel";
+import { SectionNav } from "~/components/settings/SectionNav";
 import { m } from "~/paraglide/messages";
 
 /* ------------------------------------------------------------------ */
@@ -198,11 +199,24 @@ export default function SettingsSecurityPage() {
     shouldRevalidate: "onInput",
   });
 
+  const navSections = [
+    { id: "account-details", label: m.settings_security_account_details_heading() },
+    { id: "change-password", label: m.settings_pw_heading() },
+    { id: "two-factor", label: m.settings_2fa_heading() },
+    { id: "turnstile", label: m.settings_turnstile_heading() },
+    { id: "sessions", label: m.settings_security_sessions_heading() },
+    { id: "data-export", label: m.settings_dataexport_heading() },
+    { id: "danger", label: m.settings_security_danger_heading() },
+  ];
+
   return (
     <div className="space-y-ih-list max-w-3xl">
       <SettingsCrumb items={[{ label: m.settings_crumb_settings(), href: "/settings" }, { label: m.settings_security_crumb() }]} />
       <p className="text-[13px] text-ih-fg-3">{m.settings_security_subtitle()}</p>
 
+      {/* In-page section navigation (sticky; scroll-spy). Shows only when ≥3 sections visible. */}
+      <SectionNav sections={navSections} />
+
       {/* Flash */}
       {flashVisible && actionData && "success" in actionData && actionData.success && (
         <div className="px-4 py-2.5 rounded-md bg-ih-ok-bg border border-ih-ok-fg/20 text-[13px] text-ih-ok-fg font-medium">
@@ -220,7 +234,7 @@ export default function SettingsSecurityPage() {
       ) : null}
 
       {/* Account info */}
-      <section className="bg-ih-bg-card rounded-lg border border-ih-border p-6 space-y-4">
+      <section id="account-details" className="bg-ih-bg-card rounded-lg border border-ih-border p-6 space-y-4 scroll-mt-12">
         <h3 className="text-[11px] font-bold text-ih-fg-2 uppercase tracking-[0.2em]">{m.settings_security_account_details_heading()}</h3>
         <div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
           <div>
@@ -235,28 +249,34 @@ export default function SettingsSecurityPage() {
       </section>
 
       {/* Change password */}
-      <ChangePasswordPanel
-        pwForm={pwForm}
-        pwFields={pwFields}
-        showPassword={showPassword}
-        setShowPassword={setShowPassword}
-      />
+      <div id="change-password" className="scroll-mt-12">
+        <ChangePasswordPanel
+          pwForm={pwForm}
+          pwFields={pwFields}
+          showPassword={showPassword}
+          setShowPassword={setShowPassword}
+        />
+      </div>
 
       {/* 2FA status */}
-      <TwoFactorPanel
-        totpEnabled={user.totpEnabled}
-        recoveryCodesRemaining={user.recoveryCodesRemaining}
-      />
+      <div id="two-factor" className="scroll-mt-12">
+        <TwoFactorPanel
+          totpEnabled={user.totpEnabled}
+          recoveryCodesRemaining={user.recoveryCodesRemaining}
+        />
+      </div>
 
       {/* Turnstile bot protection */}
-      <TurnstilePanel
-        value={secrets.TURNSTILE_SECRET_KEY}
-        fieldError={turnstileFieldError}
-        saving={savingTurnstile}
-      />
+      <div id="turnstile" className="scroll-mt-12">
+        <TurnstilePanel
+          value={secrets.TURNSTILE_SECRET_KEY}
+          fieldError={turnstileFieldError}
+          saving={savingTurnstile}
+        />
+      </div>
 
       {/* Active sessions placeholder */}
-      <section className="bg-ih-bg-card rounded-lg border border-ih-border p-6 space-y-4">
+      <section id="sessions" className="bg-ih-bg-card rounded-lg border border-ih-border p-6 space-y-4 scroll-mt-12">
         <h3 className="text-[11px] font-bold text-ih-fg-2 uppercase tracking-[0.2em]">{m.settings_security_sessions_heading()}</h3>
         <div className="flex items-center gap-3 p-3 rounded-md bg-ih-bg-muted border border-ih-border">
           <div className="w-8 h-8 rounded-full bg-ih-primary-tint text-ih-primary flex items-center justify-center">
@@ -273,10 +293,12 @@ export default function SettingsSecurityPage() {
       </section>
 
       {/* Data export */}
-      <DataExportPanel />
+      <div id="data-export" className="scroll-mt-12">
+        <DataExportPanel />
+      </div>
 
       {/* Danger zone */}
-      <section className="bg-ih-bg-card rounded-lg border border-ih-bad p-6 space-y-4">
+      <section id="danger" className="bg-ih-bg-card rounded-lg border border-ih-bad p-6 space-y-4 scroll-mt-12">
         <h3 className="text-[11px] font-bold text-ih-bad-fg uppercase tracking-[0.2em]">{m.settings_security_danger_heading()}</h3>
         <div className="p-4 rounded-md bg-ih-bad-bg border border-ih-bad">
           <p className="text-[13px] font-bold text-ih-bad-fg mb-1">{m.settings_security_delete_title()}</p>
diff --git a/app/routes/settings-workspace.tsx b/app/routes/settings-workspace.tsx
index 9479dffc..1d9fa659 100644
--- a/app/routes/settings-workspace.tsx
+++ b/app/routes/settings-workspace.tsx
@@ -9,6 +9,7 @@ import { requireToken } from "~/lib/session.server";
 import { createApi } from "~/lib/api-client.server";
 import { LogoUploader } from "~/components/media-studio/LogoUploader";
 import { SettingsSaveBar } from "~/components/settings/SettingsSaveBar";
+import { SectionNav } from "~/components/settings/SectionNav";
 import { makeWorkspaceSchema } from "~/lib/forms/settings.schema";
 import { requireAdminLoader } from "~/lib/access.server";
 import { AccessDenied } from "~/components/AccessDenied";
@@ -199,11 +200,23 @@ export default function SettingsWorkspacePage() {
 
   if ("forbidden" in data) return <AccessDenied />;
 
+  const navSections = [
+    { id: "branding", label: m.settings_workspace_branding_heading() },
+    { id: "timezone", label: m.settings_workspace_timezone_heading() },
+    { id: "locale-currency", label: m.settings_workspace_locale_currency_heading() },
+    { id: "report-theme", label: m.settings_workspace_report_theme_heading() },
+    { id: "referral", label: m.settings_workspace_referral_heading() },
+    { id: "report-features", label: m.settings_workspace_report_features_heading() },
+    { id: "report-pdf", label: m.settings_workspace_report_pdf_heading() },
+  ];
+
   return (
     <div className="space-y-ih-list">
       <SettingsCrumb items={[{ label: m.settings_crumb_settings(), href: "/settings" }, { label: m.settings_workspace_crumb() }]} />
       <p className="text-[13px] text-ih-fg-3">{m.settings_workspace_subtitle()}</p>
 
+      <SectionNav sections={navSections} />
+
       {/* Flash */}
       {actionData && "success" in actionData && actionData.success && (
         <div className="px-4 py-2.5 rounded-md bg-ih-ok-bg border border-ih-ok-fg/20 text-[13px] text-ih-ok-fg font-medium">
@@ -219,7 +232,7 @@ export default function SettingsWorkspacePage() {
         className="space-y-5"
       >
         {/* Branding */}
-        <section className="bg-ih-bg-card rounded-lg border border-ih-border p-6 space-y-6">
+        <section id="branding" className="bg-ih-bg-card rounded-lg border border-ih-border p-6 space-y-6 scroll-mt-12">
           <h3 className="text-[11px] font-bold text-ih-fg-2 uppercase tracking-[0.2em]">{m.settings_workspace_branding_heading()}</h3>
           <div className="grid grid-cols-1 md:grid-cols-2 gap-5">
             <div className="space-y-2">
@@ -263,7 +276,7 @@ export default function SettingsWorkspacePage() {
         </section>
 
         {/* Timezone */}
-        <section className="bg-ih-bg-card rounded-lg border border-ih-border p-6 space-y-4">
+        <section id="timezone" className="bg-ih-bg-card rounded-lg border border-ih-border p-6 space-y-4 scroll-mt-12">
           <h3 className="text-[11px] font-bold text-ih-fg-2 uppercase tracking-[0.2em]">{m.settings_workspace_timezone_heading()}</h3>
           <p className="text-[12px] text-ih-fg-3">
             {m.settings_workspace_timezone_subtitle()}
@@ -290,7 +303,7 @@ export default function SettingsWorkspacePage() {
         </section>
 
         {/* Locale & Currency */}
-        <section className="bg-ih-bg-card rounded-lg border border-ih-border p-6 space-y-4">
+        <section id="locale-currency" className="bg-ih-bg-card rounded-lg border border-ih-border p-6 space-y-4 scroll-mt-12">
           <h3 className="text-[11px] font-bold text-ih-fg-2 uppercase tracking-[0.2em]">{m.settings_workspace_locale_currency_heading()}</h3>
           <p className="text-[12px] text-ih-fg-3">
             {m.settings_workspace_locale_currency_subtitle()}
@@ -312,7 +325,7 @@ export default function SettingsWorkspacePage() {
         </section>
 
         {/* Report theme */}
-        <section className="bg-ih-bg-card rounded-lg border border-ih-border p-6 space-y-5">
+        <section id="report-theme" className="bg-ih-bg-card rounded-lg border border-ih-border p-6 space-y-5 scroll-mt-12">
           <h3 className="text-[11px] font-bold text-ih-fg-2 uppercase tracking-[0.2em]">{m.settings_workspace_report_theme_heading()}</h3>
           <p className="text-[12px] text-ih-fg-3">{m.settings_workspace_report_theme_subtitle()}</p>
           <div className="grid grid-cols-1 sm:grid-cols-3 gap-3">
@@ -330,7 +343,7 @@ export default function SettingsWorkspacePage() {
         </section>
 
         {/* Referral sources */}
-        <section className="bg-ih-bg-card rounded-lg border border-ih-border p-6 space-y-5">
+        <section id="referral" className="bg-ih-bg-card rounded-lg border border-ih-border p-6 space-y-5 scroll-mt-12">
           <h3 className="text-[11px] font-bold text-ih-fg-2 uppercase tracking-[0.2em]">{m.settings_workspace_referral_heading()}</h3>
           <div className="space-y-3">
             <div className="text-[11px] font-bold uppercase tracking-[0.2em] text-ih-fg-2">{m.settings_workspace_referral_builtin_label()}</div>
@@ -351,7 +364,7 @@ export default function SettingsWorkspacePage() {
         </section>
 
         {/* Report features */}
-        <section className="bg-ih-bg-card rounded-lg border border-ih-border p-6 space-y-5">
+        <section id="report-features" className="bg-ih-bg-card rounded-lg border border-ih-border p-6 space-y-5 scroll-mt-12">
           <h3 className="text-[11px] font-bold text-ih-fg-2 uppercase tracking-[0.2em]">{m.settings_workspace_report_features_heading()}</h3>
 
           <label className="flex items-start gap-3 cursor-pointer select-none">
@@ -388,7 +401,7 @@ export default function SettingsWorkspacePage() {
         </section>
 
         {/* Report PDF */}
-        <section className="bg-ih-bg-card rounded-lg border border-ih-border p-6 space-y-5">
+        <section id="report-pdf" className="bg-ih-bg-card rounded-lg border border-ih-border p-6 space-y-5 scroll-mt-12">
           <h3 className="text-[11px] font-bold text-ih-fg-2 uppercase tracking-[0.2em]">{m.settings_workspace_report_pdf_heading()}</h3>
           <p className="text-[12px] text-ih-fg-3">{m.settings_workspace_report_pdf_subtitle()}</p>
 
diff --git a/scripts/file-size-baseline.json b/scripts/file-size-baseline.json
index 20767473..da0bd2b8 100644
--- a/scripts/file-size-baseline.json
+++ b/scripts/file-size-baseline.json
@@ -42,25 +42,25 @@
   "server/services/inspection-request.service.ts": 501,
   "server/services/report-export-consumer.ts": 499,
   "server/api/repair-builder.ts": 496,
+  "app/routes/settings-workspace.tsx": 482,
   "app/components/collab/VersionHistoryPanel.tsx": 478,
   "server/api/bookings.ts": 477,
   "server/api/bookings/agreement.ts": 475,
   "server/api/admin/admin-config.ts": 472,
   "server/portal/integration.routes.ts": 472,
-  "app/routes/settings-workspace.tsx": 469,
   "server/api/inspections/media.ts": 468,
   "app/routes/inspection-edit/action.server.ts": 457,
   "app/components/editor/CostItemsPanel.tsx": 449,
   "server/lib/email-templates/registry.ts": 439,
   "app/components/editor/InspectionSettingsSheet.tsx": 437,
+  "app/routes/settings-schedule.tsx": 437,
   "app/lib/collab/results-doc-connection.ts": 435,
   "app/components/media-studio/VideoCapture.tsx": 433,
+  "app/routes/settings-profile.tsx": 432,
   "server/api/inspections/results.ts": 430,
   "server/api/inspections/hierarchy.ts": 428,
   "app/hooks/useStructureEdit.ts": 424,
-  "app/routes/settings-profile.tsx": 421,
   "server/lib/middleware/di.ts": 421,
-  "app/routes/settings-schedule.tsx": 412,
   "app/routes/templates.tsx": 411,
   "app/routes/calendar.tsx": 402,
   "server/api/secrets.ts": 401

From 0fa47cfcc5603cc9548da26a1a51586c7bb7d5a6 Mon Sep 17 00:00:00 2001
From: important-new <important-new@hotmail.com>
Date: Mon, 20 Jul 2026 18:50:43 +0800
Subject: [PATCH 06/12] refactor(settings): unify communication selection
 controls onto DS

- SMS delivery mode: hand-rolled radio-cards -> RadioCardGroup (hidden smsMode
  input still carries the value into the form POST).
- Email delivery mode: hand-rolled solid-purple segmented toggle -> DS
  SegmentedControl + hidden input (buttons don't post, so the hidden input
  carries emailMode).
- Point of contact: bare native radios -> RadioCardGroup (real named radios
  post natively). Controlled value initialises from config, preserving behavior.
---
 .../settings/EmailDeliveryPanel.tsx           | 46 ++++++-------
 app/components/settings/SmsDeliveryPanel.tsx  | 67 +++++++------------
 2 files changed, 46 insertions(+), 67 deletions(-)

diff --git a/app/components/settings/EmailDeliveryPanel.tsx b/app/components/settings/EmailDeliveryPanel.tsx
index d471a598..00b8abe7 100644
--- a/app/components/settings/EmailDeliveryPanel.tsx
+++ b/app/components/settings/EmailDeliveryPanel.tsx
@@ -1,4 +1,5 @@
 import { Link, Form } from "react-router";
+import { SegmentedControl, RadioCardGroup } from "@core/shared-ui";
 import type { useForm } from "@conform-to/react";
 import { m } from "~/paraglide/messages";
 
@@ -113,19 +114,18 @@ export function EmailDeliveryPanel({
               mode is forced to `own` (hidden input below) and the toggle hides. */}
           {isSaas ? (
             <>
-              <div className="inline-flex rounded-md border border-ih-border overflow-hidden">
-                {(["platform", "own"] as const).map((optMode) => (
-                  <label key={optMode} className={`px-3 h-8 flex items-center text-[12px] font-bold cursor-pointer ${mode === optMode ? "bg-ih-primary text-white" : "bg-ih-bg-card text-ih-fg-2"}`}>
-                    <input
-                      type="radio" name={emailFields.emailMode.name} value={optMode}
-                      defaultChecked={config.emailMode === optMode}
-                      onChange={() => setMode(optMode)}
-                      className="sr-only"
-                    />
-                    {optMode === "platform" ? m.settings_emaildelivery_mode_platform() : m.settings_emaildelivery_mode_own()}
-                  </label>
-                ))}
-              </div>
+              <SegmentedControl
+                ariaLabel={m.settings_emaildelivery_heading()}
+                value={mode}
+                onChange={(v) => setMode(v as "platform" | "own")}
+                options={[
+                  { value: "platform", label: m.settings_emaildelivery_mode_platform() },
+                  { value: "own", label: m.settings_emaildelivery_mode_own() },
+                ]}
+              />
+              {/* SegmentedControl renders buttons, not a form field — carry the
+                  value into the native form POST via a hidden input. */}
+              <input type="hidden" name={emailFields.emailMode.name} value={mode} />
               <p className="text-[11px] text-ih-fg-4">
                 {mode === "platform"
                   ? m.settings_emaildelivery_mode_platform_desc()
@@ -223,17 +223,15 @@ export function EmailDeliveryPanel({
 
           <div className="space-y-1">
             <p className="text-[10px] font-bold uppercase tracking-[0.2em] text-ih-fg-3">{m.settings_emaildelivery_poc_label()}</p>
-            {(["company", "inspector"] as const).map((p) => (
-              <label key={p} className="flex items-center gap-2 text-[13px] text-ih-fg-2 cursor-pointer">
-                <input
-                  type="radio" name={emailFields.pointOfContact.name} value={p}
-                  defaultChecked={config.pointOfContact === p}
-                  onChange={() => setPoc(p)}
-                  className="h-4 w-4 border-ih-border"
-                />
-                {p === "company" ? m.settings_emaildelivery_poc_company() : m.settings_emaildelivery_poc_inspector()}
-              </label>
-            ))}
+            <RadioCardGroup
+              name={emailFields.pointOfContact.name}
+              value={poc}
+              onChange={(v) => setPoc(v as "company" | "inspector")}
+              options={[
+                { value: "company", title: m.settings_emaildelivery_poc_company() },
+                { value: "inspector", title: m.settings_emaildelivery_poc_inspector() },
+              ]}
+            />
             <p className="text-[11px] text-ih-fg-4 pt-1">
               {m.settings_emaildelivery_send_as()}{" "}
               <strong>
diff --git a/app/components/settings/SmsDeliveryPanel.tsx b/app/components/settings/SmsDeliveryPanel.tsx
index 2ab8eb16..7fb5bcb8 100644
--- a/app/components/settings/SmsDeliveryPanel.tsx
+++ b/app/components/settings/SmsDeliveryPanel.tsx
@@ -1,4 +1,5 @@
 import { Form } from "react-router";
+import { RadioCardGroup } from "@core/shared-ui";
 import type { useFetcher } from "react-router";
 import { SmsSecretsPanel } from "~/components/settings/SmsSecretsPanel";
 import type { action } from "~/routes/settings-communication";
@@ -113,49 +114,29 @@ export function SmsDeliveryPanel({
               is hidden. "platform" is a first-party-only value that is never
               presented as a tenant option. */}
           {isSaas && (
-            <div className="space-y-2">
-              <div className="flex flex-col gap-2">
-                {/* BYO */}
-                <label className={`flex items-start gap-3 p-3 rounded-md border cursor-pointer transition-colors ${smsMode === "own" ? "border-ih-primary bg-ih-primary/5" : "border-ih-border bg-ih-bg-card hover:border-ih-primary/40"}`}>
-                  <input
-                    type="radio" name="_smsModeRadio" value="own"
-                    checked={smsMode === "own"}
-                    onChange={() => setSmsMode("own")}
-                    className="mt-0.5 accent-ih-primary"
-                  />
-                  <span className="flex-1 min-w-0">
-                    <span className="block text-[13px] font-bold text-ih-fg-1">{m.settings_smsdelivery_byo_label()}</span>
-                    <span className="block text-[11px] text-ih-fg-3 mt-0.5">{m.settings_smsdelivery_byo_desc()}</span>
-                  </span>
-                </label>
-                {/* Managed shared */}
-                <label className={`flex items-start gap-3 p-3 rounded-md border cursor-pointer transition-colors ${smsMode === "managed_shared" ? "border-ih-primary bg-ih-primary/5" : "border-ih-border bg-ih-bg-card hover:border-ih-primary/40"}`}>
-                  <input
-                    type="radio" name="_smsModeRadio" value="managed_shared"
-                    checked={smsMode === "managed_shared"}
-                    onChange={() => setSmsMode("managed_shared")}
-                    className="mt-0.5 accent-ih-primary"
-                  />
-                  <span className="flex-1 min-w-0">
-                    <span className="block text-[13px] font-bold text-ih-fg-1">{m.settings_smsdelivery_shared_label()} <span className="font-normal text-ih-ok-fg">{m.settings_smsdelivery_included()}</span></span>
-                    <span className="block text-[11px] text-ih-fg-3 mt-0.5">{m.settings_smsdelivery_shared_desc()}</span>
-                  </span>
-                </label>
-                {/* Managed dedicated — selectable; provisioning wizard renders below */}
-                <label className={`flex items-start gap-3 p-3 rounded-md border cursor-pointer transition-colors ${smsMode === "managed_dedicated" ? "border-ih-primary bg-ih-primary/5" : "border-ih-border bg-ih-bg-card hover:border-ih-primary/40"}`}>
-                  <input
-                    type="radio" name="_smsModeRadio" value="managed_dedicated"
-                    checked={smsMode === "managed_dedicated"}
-                    onChange={() => setSmsMode("managed_dedicated")}
-                    className="mt-0.5 accent-ih-primary"
-                  />
-                  <span className="flex-1 min-w-0">
-                    <span className="block text-[13px] font-bold text-ih-fg-1">{m.settings_smsdelivery_dedicated_label()}</span>
-                    <span className="block text-[11px] text-ih-fg-3 mt-0.5">{m.settings_smsdelivery_dedicated_desc()}</span>
-                  </span>
-                </label>
-              </div>
-            </div>
+            <RadioCardGroup
+              name="_smsModeRadio"
+              value={smsMode}
+              onChange={(v) => setSmsMode(v as SmsModeValue)}
+              options={[
+                {
+                  value: "own",
+                  title: m.settings_smsdelivery_byo_label(),
+                  description: m.settings_smsdelivery_byo_desc(),
+                },
+                {
+                  value: "managed_shared",
+                  title: m.settings_smsdelivery_shared_label(),
+                  badge: m.settings_smsdelivery_included(),
+                  description: m.settings_smsdelivery_shared_desc(),
+                },
+                {
+                  value: "managed_dedicated",
+                  title: m.settings_smsdelivery_dedicated_label(),
+                  description: m.settings_smsdelivery_dedicated_desc(),
+                },
+              ]}
+            />
           )}
           {!isSaas && (
             <p className="text-[13px] text-ih-fg-3 bg-ih-bg-muted border border-ih-border rounded-md p-3">

From 3fdc847bfa75584eda748d4f6f3eb4e11549de95 Mon Sep 17 00:00:00 2001
From: important-new <important-new@hotmail.com>
Date: Mon, 20 Jul 2026 19:10:57 +0800
Subject: [PATCH 07/12] refactor(settings): migrate remaining selection
 controls to DS primitives
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Email/SMS secrets provider pickers -> RadioCardGroup (existing hidden
  provider inputs stay authoritative; DS radios named _*Radio to avoid POST
  collision).
- Google Calendar OAuth mode -> SegmentedControl (controlled-only; existing
  hidden googleOAuthMode input carries the value).
- Calendar capability picker -> RadioCardGroup (URL-query driven, no form).
- Inspection prefs (clone / auto-advance / required fields) -> RadioGroup.
Left intentionally as-is: ManagedComplianceWizard (button+aria-pressed test
contract), HolidayPolicyCards (aria-checked/testid test contract), workspace
report-theme swatch grid — all already DS-token-compliant.
---
 .../settings/CalendarConnectPanel.tsx         | 38 ++++-----
 app/components/settings/EmailSecretsPanel.tsx | 26 +++---
 .../settings/GoogleCalendarPanel.tsx          | 33 +++-----
 app/components/settings/SmsSecretsPanel.tsx   | 44 ++++-------
 app/routes/settings-inspection.tsx            | 79 ++++++++-----------
 5 files changed, 88 insertions(+), 132 deletions(-)

diff --git a/app/components/settings/CalendarConnectPanel.tsx b/app/components/settings/CalendarConnectPanel.tsx
index 1f1dc18b..704ef10b 100644
--- a/app/components/settings/CalendarConnectPanel.tsx
+++ b/app/components/settings/CalendarConnectPanel.tsx
@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import { useFetcher, useRevalidator, useSearchParams } from "react-router";
+import { RadioCardGroup } from "@core/shared-ui";
 import { GoogleSignInButton } from "~/components/GoogleSignInButton";
 import { CalendarGlyph } from "~/components/settings/CalendarGlyph";
 import { calendarOAuthErrorToast } from "~/lib/calendar-oauth-errors";
@@ -194,28 +195,21 @@ export function CalendarConnectPanel({
       ) : (
         <div className="space-y-3">
           <p className="text-[12px] text-ih-fg-3">{m.settings_calconnect_choose_access()}</p>
-          <div className="grid grid-cols-1 sm:grid-cols-2 gap-2">
-            {(["availability_read", "events_read_write"] as const).map((option) => (
-              <label
-                key={option}
-                className={`flex items-center gap-2 p-3 rounded-md border cursor-pointer text-[12px] ${
-                  capability === option
-                    ? "border-ih-primary bg-ih-primary-tint text-ih-fg-1"
-                    : "border-ih-border text-ih-fg-2"
-                }`}
-              >
-                <input
-                  type="radio"
-                  name="calendarCapability"
-                  value={option}
-                  checked={capability === option}
-                  onChange={() => setCapability(option)}
-                  className="h-3.5 w-3.5"
-                />
-                {CAPABILITY_LABELS[option]}
-              </label>
-            ))}
-          </div>
+          <RadioCardGroup
+            name="calendarCapability"
+            value={capability}
+            onChange={(v) => setCapability(v as CalendarCapability)}
+            options={[
+              {
+                value: "availability_read",
+                title: CAPABILITY_LABELS.availability_read,
+              },
+              {
+                value: "events_read_write",
+                title: CAPABILITY_LABELS.events_read_write,
+              },
+            ]}
+          />
           <GoogleSignInButton
             onClick={handleConnect}
             label={connecting ? m.settings_calconnect_connecting() : m.settings_calconnect_continue_google()}
diff --git a/app/components/settings/EmailSecretsPanel.tsx b/app/components/settings/EmailSecretsPanel.tsx
index c1dedca4..c83fa876 100644
--- a/app/components/settings/EmailSecretsPanel.tsx
+++ b/app/components/settings/EmailSecretsPanel.tsx
@@ -1,5 +1,6 @@
 import { useState } from "react";
 import { Form } from "react-router";
+import { RadioCardGroup } from "@core/shared-ui";
 import type { useFetcher } from "react-router";
 import { SecretField } from "~/components/SecretField";
 import { TestConnectionButton } from "~/components/settings/TestConnectionButton";
@@ -119,22 +120,15 @@ export function EmailSecretsPanel({
         {/* Provider choice */}
         <div className="space-y-1.5">
           <p className="text-[10px] font-bold uppercase tracking-[0.2em] text-ih-fg-3">{m.settings_emailsecrets_provider_label()}</p>
-          <div className="flex gap-2">
-            {(["resend", "sendgrid", "postmark", "mailgun"] as const).map((p) => (
-              <button
-                key={p}
-                type="button"
-                onClick={() => setProvider(p)}
-                className={`flex-1 h-9 rounded-md border text-[13px] font-bold transition-colors ${
-                  provider === p
-                    ? "border-ih-primary bg-ih-primary/5 text-ih-primary"
-                    : "border-ih-border bg-ih-bg-card text-ih-fg-2 hover:border-ih-primary/40"
-                }`}
-              >
-                {PROVIDER_LABELS[p]}
-              </button>
-            ))}
-          </div>
+          <RadioCardGroup
+            name="_emailProviderRadio"
+            value={provider}
+            onChange={(v) => setProvider(v as EmailByoProvider)}
+            options={(["resend", "sendgrid", "postmark", "mailgun"] as const).map((p) => ({
+              value: p,
+              title: PROVIDER_LABELS[p],
+            }))}
+          />
         </div>
 
         {/* Resend credential fields */}
diff --git a/app/components/settings/GoogleCalendarPanel.tsx b/app/components/settings/GoogleCalendarPanel.tsx
index ff6a1c81..9d789d52 100644
--- a/app/components/settings/GoogleCalendarPanel.tsx
+++ b/app/components/settings/GoogleCalendarPanel.tsx
@@ -1,5 +1,6 @@
 import { useState } from "react";
 import { Form, Link } from "react-router";
+import { SegmentedControl } from "@core/shared-ui";
 import { SecretField } from "~/components/SecretField";
 import { m } from "~/paraglide/messages";
 
@@ -45,26 +46,18 @@ export function GoogleCalendarPanel({
 
       {isSaas ? (
         <div className="space-y-2">
-          <div className="inline-flex rounded-md border border-ih-border overflow-hidden">
-            {(["platform", "own"] as const).map((mode) => (
-              <label
-                key={mode}
-                className={`px-3 h-8 flex items-center text-[12px] font-bold cursor-pointer ${
-                  oauthMode === mode ? "bg-ih-primary text-white" : "bg-ih-bg-card text-ih-fg-2"
-                }`}
-              >
-                <input
-                  type="radio"
-                  name="_googleOAuthModeRadio"
-                  value={mode}
-                  checked={oauthMode === mode}
-                  onChange={() => setOauthMode(mode)}
-                  className="sr-only"
-                />
-                {mode === "platform" ? m.settings_gcal_mode_platform() : m.settings_gcal_mode_own()}
-              </label>
-            ))}
-          </div>
+          <SegmentedControl
+            ariaLabel={m.settings_gcal_heading()}
+            value={oauthMode}
+            onChange={(v) => setOauthMode(v as GoogleOAuthMode)}
+            options={[
+              { value: "platform", label: m.settings_gcal_mode_platform() },
+              { value: "own", label: m.settings_gcal_mode_own() },
+            ]}
+          />
+          {/* No hidden input here: the toggle radios were never inside the
+              form. The save Form below carries the value via its own
+              hidden `googleOAuthMode` input. */}
           <p className="text-[11px] text-ih-fg-4">
             {oauthMode === "platform"
               ? m.settings_gcal_mode_platform_desc()
diff --git a/app/components/settings/SmsSecretsPanel.tsx b/app/components/settings/SmsSecretsPanel.tsx
index 39a290ea..08db9e4c 100644
--- a/app/components/settings/SmsSecretsPanel.tsx
+++ b/app/components/settings/SmsSecretsPanel.tsx
@@ -1,5 +1,6 @@
 import { useState } from "react";
 import { Form } from "react-router";
+import { RadioCardGroup } from "@core/shared-ui";
 import type { useFetcher } from "react-router";
 import { SecretField } from "~/components/SecretField";
 import { ConnectionTestStatus, type ConnectionTestResult } from "~/components/settings/ConnectionTestStatus";
@@ -60,33 +61,22 @@ export function SmsSecretsPanel({
           <input type="hidden" name="sms_byo_provider" value={provider} />
 
           {/* Provider choice */}
-          <div className="space-y-1.5">
-            <p className="text-[10px] font-bold uppercase tracking-[0.2em] text-ih-fg-3">{m.settings_smssecrets_provider_label()}</p>
-            <div className="flex gap-2">
-              <button
-                type="button"
-                onClick={() => setProvider("twilio")}
-                className={`flex-1 h-9 rounded-md border text-[13px] font-bold transition-colors ${
-                  provider === "twilio"
-                    ? "border-ih-primary bg-ih-primary/5 text-ih-primary"
-                    : "border-ih-border bg-ih-bg-card text-ih-fg-2 hover:border-ih-primary/40"
-                }`}
-              >
-                {m.settings_sms_provider_twilio()}
-              </button>
-              <button
-                type="button"
-                onClick={() => setProvider("telnyx")}
-                className={`flex-1 h-9 rounded-md border text-[13px] font-bold transition-colors ${
-                  provider === "telnyx"
-                    ? "border-ih-primary bg-ih-primary/5 text-ih-primary"
-                    : "border-ih-border bg-ih-bg-card text-ih-fg-2 hover:border-ih-primary/40"
-                }`}
-              >
-                {m.settings_sms_provider_telnyx()}
-              </button>
-            </div>
-          </div>
+          <RadioCardGroup
+            name="_smsByoProviderRadio"
+            legend={m.settings_smssecrets_provider_label()}
+            value={provider}
+            onChange={(v) => setProvider(v as ByoProvider)}
+            options={[
+              {
+                value: "twilio",
+                title: m.settings_sms_provider_twilio(),
+              },
+              {
+                value: "telnyx",
+                title: m.settings_sms_provider_telnyx(),
+              },
+            ]}
+          />
 
           {/* Twilio credential fields */}
           {provider === "twilio" && (
diff --git a/app/routes/settings-inspection.tsx b/app/routes/settings-inspection.tsx
index dc5c2668..85b07865 100644
--- a/app/routes/settings-inspection.tsx
+++ b/app/routes/settings-inspection.tsx
@@ -1,5 +1,5 @@
 import { useLoaderData } from 'react-router';
-import { Icon } from "@core/shared-ui";
+import { Icon, RadioGroup } from "@core/shared-ui";
 import { SettingsCrumb } from '~/components/SettingsCrumb';
 import type { Route } from './+types/settings-inspection';
 import { requireToken } from '~/lib/session.server';
@@ -40,40 +40,30 @@ export default function SettingsInspectionPage() {
 
             <section>
                 <h2 className="text-[13px] font-bold uppercase tracking-[0.1em] text-ih-fg-4 mb-3">{m.settings_inspection_clone_heading()}</h2>
-                {(['rating', 'rating_notes', 'all'] as const).map(scope => (
-                    <label key={scope} className="flex items-center gap-2 py-1.5 cursor-pointer">
-                        <input
-                            type="radio"
-                            checked={prefs.cloneDefault === scope}
-                            onChange={() => patch({ cloneDefault: scope })}
-                            className="w-4 h-4"
-                        />
-                        <span className="text-[13px]">{({
-                            rating:       m.settings_inspection_clone_rating(),
-                            rating_notes: m.settings_inspection_clone_rating_notes(),
-                            all:          m.settings_inspection_clone_all(),
-                        } as Record<typeof scope, string>)[scope]}</span>
-                    </label>
-                ))}
+                <RadioGroup
+                    name="cloneDefault"
+                    value={prefs.cloneDefault}
+                    onChange={v => patch({ cloneDefault: v as 'rating' | 'rating_notes' | 'all' })}
+                    options={[
+                        { value: 'rating', label: m.settings_inspection_clone_rating() },
+                        { value: 'rating_notes', label: m.settings_inspection_clone_rating_notes() },
+                        { value: 'all', label: m.settings_inspection_clone_all() },
+                    ]}
+                />
             </section>
 
             <section>
                 <h2 className="text-[13px] font-bold uppercase tracking-[0.1em] text-ih-fg-4 mb-3">{m.settings_inspection_autoadvance_heading()}</h2>
-                {(['keyboard', 'always', 'off'] as const).map(mode => (
-                    <label key={mode} className="flex items-center gap-2 py-1 cursor-pointer">
-                        <input
-                            type="radio"
-                            checked={prefs.autoAdvance === mode}
-                            onChange={() => patch({ autoAdvance: mode })}
-                            className="w-4 h-4"
-                        />
-                        <span className="text-[13px]">{({
-                            keyboard: m.settings_inspection_autoadvance_keyboard(),
-                            always:   m.settings_inspection_autoadvance_always(),
-                            off:      m.settings_inspection_autoadvance_off(),
-                        } as Record<typeof mode, string>)[mode]}</span>
-                    </label>
-                ))}
+                <RadioGroup
+                    name="autoAdvance"
+                    value={prefs.autoAdvance}
+                    onChange={v => patch({ autoAdvance: v as 'keyboard' | 'always' | 'off' })}
+                    options={[
+                        { value: 'keyboard', label: m.settings_inspection_autoadvance_keyboard() },
+                        { value: 'always', label: m.settings_inspection_autoadvance_always() },
+                        { value: 'off', label: m.settings_inspection_autoadvance_off() },
+                    ]}
+                />
                 <p className="text-[12px] text-ih-fg-3 mt-1">{m.settings_inspection_autoadvance_note()}</p>
                 <div className="flex items-center gap-3 mt-3">
                     <input
@@ -93,22 +83,17 @@ export default function SettingsInspectionPage() {
             <section>
                 <h2 className="text-[13px] font-bold uppercase tracking-[0.1em] text-ih-fg-4 mb-3">{m.settings_inspection_required_heading()}</h2>
                 <p className="text-[12px] text-ih-fg-3 mb-2">{m.settings_inspection_required_help()}</p>
-                {(['none', 'location', 'trade', 'both'] as const).map(req => (
-                    <label key={req} className="flex items-center gap-2 py-1 cursor-pointer">
-                        <input
-                            type="radio"
-                            checked={prefs.requireDefectFields === req}
-                            onChange={() => patch({ requireDefectFields: req })}
-                            className="w-4 h-4"
-                        />
-                        <span className="text-[13px]">{({
-                            none:     m.settings_inspection_required_none(),
-                            location: m.settings_inspection_required_location(),
-                            trade:    m.settings_inspection_required_trade(),
-                            both:     m.settings_inspection_required_both(),
-                        } as Record<typeof req, string>)[req]}</span>
-                    </label>
-                ))}
+                <RadioGroup
+                    name="requireDefectFields"
+                    value={prefs.requireDefectFields}
+                    onChange={v => patch({ requireDefectFields: v as 'none' | 'location' | 'trade' | 'both' })}
+                    options={[
+                        { value: 'none', label: m.settings_inspection_required_none() },
+                        { value: 'location', label: m.settings_inspection_required_location() },
+                        { value: 'trade', label: m.settings_inspection_required_trade() },
+                        { value: 'both', label: m.settings_inspection_required_both() },
+                    ]}
+                />
             </section>
 
             <section>

From 418ac96452c388b3ce768c3cf94c165ed45c10ba Mon Sep 17 00:00:00 2001
From: important-new <important-new@hotmail.com>
Date: Mon, 20 Jul 2026 20:03:40 +0800
Subject: [PATCH 08/12] feat(places): address-autocomplete BFF, GoogleMap, and
 Maps-key plumbing (#198)

Frontend foundation for Google Places address autocomplete over the existing
/api/places/* backend:

- resources/places: token-relay BFF loader (q -> suggestions, placeId ->
  structured AddressSelection); degrades to empty when the upstream key is
  unset so the address input stays usable as free text.
- AddressAutocomplete: debounced, keyboard-navigable combobox with a
  per-typing-session Google billing token.
- GoogleMap: interactive marker map, fail-closed when the browser Maps key or
  coordinates are absent; key surfaced via the root loader
  (useRouteLoaderData) rather than a new global.
- AppEnv gains GOOGLE_MAPS_JS_API_KEY; CSP allows maps.googleapis.com /
  maps.gstatic.com (documented CDN exception).
- @googlemaps/js-api-loader dependency (SDK loaded from Google's CDN).

Co-located tests for the loader, autocomplete flow, and map fail-closed contract.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MkL3cCs9TmQd7zueiAnJ8s
---
 .../address/AddressAutocomplete.test.tsx      |  73 ++++++++
 .../address/AddressAutocomplete.tsx           | 158 ++++++++++++++++++
 app/components/address/GoogleMap.test.tsx     |  42 +++++
 app/components/address/GoogleMap.tsx          | 100 +++++++++++
 app/root.tsx                                  |  20 ++-
 app/routes.ts                                 |   2 +
 app/routes/resources/places.test.ts           |  93 +++++++++++
 app/routes/resources/places.tsx               |  76 +++++++++
 package-lock.json                             |   7 +
 package.json                                  |   1 +
 server/lib/middleware/security-headers.ts     |  11 +-
 server/types/hono.ts                          |   8 +
 12 files changed, 586 insertions(+), 5 deletions(-)
 create mode 100644 app/components/address/AddressAutocomplete.test.tsx
 create mode 100644 app/components/address/AddressAutocomplete.tsx
 create mode 100644 app/components/address/GoogleMap.test.tsx
 create mode 100644 app/components/address/GoogleMap.tsx
 create mode 100644 app/routes/resources/places.test.ts
 create mode 100644 app/routes/resources/places.tsx

diff --git a/app/components/address/AddressAutocomplete.test.tsx b/app/components/address/AddressAutocomplete.test.tsx
new file mode 100644
index 00000000..162a924e
--- /dev/null
+++ b/app/components/address/AddressAutocomplete.test.tsx
@@ -0,0 +1,73 @@
+import { describe, it, expect, vi } from "vitest";
+import { useState } from "react";
+import { render, screen, fireEvent, waitFor } from "@testing-library/react";
+import { createRoutesStub } from "react-router";
+import { AddressAutocomplete } from "./AddressAutocomplete";
+import type { AddressSelection } from "~/routes/resources/places";
+
+const SAMPLE: AddressSelection = {
+  placeId: "p1",
+  formatted: "123 Main St, Austin, TX 78701",
+  street: "123 Main St",
+  city: "Austin",
+  state: "TX",
+  zip: "78701",
+  county: "Travis",
+  lat: 30.26,
+  lng: -97.74,
+};
+
+function mountWith(onSelect: (s: AddressSelection) => void) {
+  const Stub = createRoutesStub([
+    {
+      path: "/",
+      Component: () => {
+        const [val, setVal] = useState("");
+        return <AddressAutocomplete value={val} onValueChange={setVal} onSelect={onSelect} />;
+      },
+    },
+    {
+      path: "/resources/places",
+      loader: ({ request }) => {
+        const url = new URL(request.url);
+        if (url.searchParams.get("placeId")) {
+          return { suggestions: [], address: SAMPLE };
+        }
+        return {
+          suggestions: [
+            { placeId: "p1", description: "123 Main St, Austin, TX", mainText: "123 Main St", secondaryText: "Austin, TX" },
+          ],
+          address: null,
+        };
+      },
+    },
+  ]);
+  return render(<Stub />);
+}
+
+describe("AddressAutocomplete", () => {
+  it("shows suggestions while typing and emits a structured selection on click", async () => {
+    const onSelect = vi.fn();
+    mountWith(onSelect);
+
+    fireEvent.change(screen.getByRole("combobox"), { target: { value: "123 Main" } });
+
+    const option = await waitFor(() => screen.getByText("123 Main St"));
+    fireEvent.mouseDown(option);
+
+    await waitFor(() =>
+      expect(onSelect).toHaveBeenCalledWith(
+        expect.objectContaining({ placeId: "p1", lat: expect.any(Number), lng: expect.any(Number) }),
+      ),
+    );
+  });
+
+  it("does not query for inputs shorter than 2 characters", async () => {
+    const onSelect = vi.fn();
+    mountWith(onSelect);
+    fireEvent.change(screen.getByRole("combobox"), { target: { value: "1" } });
+    // Give any (incorrectly scheduled) debounce time to fire.
+    await new Promise((r) => setTimeout(r, 300));
+    expect(screen.queryByRole("listbox")).toBeNull();
+  });
+});
diff --git a/app/components/address/AddressAutocomplete.tsx b/app/components/address/AddressAutocomplete.tsx
new file mode 100644
index 00000000..71828a85
--- /dev/null
+++ b/app/components/address/AddressAutocomplete.tsx
@@ -0,0 +1,158 @@
+import { useEffect, useRef, useState } from "react";
+import { useFetcher } from "react-router";
+import type { AddressSelection, PlaceSuggestion } from "~/routes/resources/places";
+import { m } from "~/paraglide/messages";
+
+/**
+ * Address autocomplete input (Spec 5D B4, #198). Debounced suggestions from the
+ * `/resources/places` BFF, keyboard-navigable listbox, and a per-typing-session
+ * token so Google bills the whole autocomplete→details sequence once.
+ *
+ * Controlled: `value`/`onValueChange` own the free-text address (so a user can
+ * still type a free-form address the API can't match and submit it). `onSelect`
+ * fires only when a suggestion is resolved to a structured `AddressSelection`.
+ *
+ * Fail-soft: when GOOGLE_PLACES_API_KEY is unset the BFF returns no suggestions,
+ * so the dropdown simply never opens and this behaves as a plain text input.
+ */
+export function AddressAutocomplete({
+  value,
+  onValueChange,
+  onSelect,
+  id = "property-address",
+  placeholder,
+}: {
+  value: string;
+  onValueChange: (v: string) => void;
+  onSelect: (sel: AddressSelection) => void;
+  id?: string;
+  placeholder?: string;
+}) {
+  const suggestFetcher = useFetcher<{ suggestions: PlaceSuggestion[] }>();
+  const detailsFetcher = useFetcher<{ address: AddressSelection | null }>();
+
+  const [open, setOpen] = useState(false);
+  const [active, setActive] = useState(-1);
+  const sessionRef = useRef<string>("");
+  const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  // Set the moment a suggestion is clicked; the details effect below consumes it
+  // so onSelect fires exactly once per resolved place (not on every re-render).
+  const pendingSelectRef = useRef(false);
+
+  const suggestions = suggestFetcher.data?.suggestions ?? [];
+
+  function ensureSession(): string {
+    if (!sessionRef.current) sessionRef.current = crypto.randomUUID();
+    return sessionRef.current;
+  }
+
+  function handleChange(next: string) {
+    onValueChange(next);
+    setActive(-1);
+    if (debounceRef.current) clearTimeout(debounceRef.current);
+    if (next.trim().length < 2) {
+      setOpen(false);
+      return;
+    }
+    const session = ensureSession();
+    debounceRef.current = setTimeout(() => {
+      suggestFetcher.load(
+        `/resources/places?q=${encodeURIComponent(next.trim())}&session=${encodeURIComponent(session)}`,
+      );
+      setOpen(true);
+    }, 250);
+  }
+
+  function choose(s: PlaceSuggestion) {
+    onValueChange(s.description);
+    setOpen(false);
+    setActive(-1);
+    pendingSelectRef.current = true;
+    const session = ensureSession();
+    detailsFetcher.load(
+      `/resources/places?placeId=${encodeURIComponent(s.placeId)}&session=${encodeURIComponent(session)}`,
+    );
+  }
+
+  // When the details load settles, emit the structured selection once and start
+  // a fresh billing session for the next lookup.
+  useEffect(() => {
+    if (detailsFetcher.state !== "idle") return;
+    if (!pendingSelectRef.current) return;
+    const address = detailsFetcher.data?.address;
+    if (address) {
+      pendingSelectRef.current = false;
+      sessionRef.current = ""; // terminate the Google session token
+      onSelect(address);
+    }
+    // onSelect is a stable-enough callback from the caller; excluding it keeps
+    // this from re-firing on unrelated parent renders (RR fetcher convention).
+  }, [detailsFetcher.state, detailsFetcher.data]);
+
+  function onKeyDown(e: React.KeyboardEvent<HTMLInputElement>) {
+    if (!open || suggestions.length === 0) return;
+    if (e.key === "ArrowDown") {
+      e.preventDefault();
+      setActive((i) => (i + 1) % suggestions.length);
+    } else if (e.key === "ArrowUp") {
+      e.preventDefault();
+      setActive((i) => (i <= 0 ? suggestions.length - 1 : i - 1));
+    } else if (e.key === "Enter" && active >= 0) {
+      e.preventDefault();
+      choose(suggestions[active]);
+    } else if (e.key === "Escape") {
+      setOpen(false);
+      setActive(-1);
+    }
+  }
+
+  const listboxId = `${id}-listbox`;
+
+  return (
+    <div className="relative">
+      <input
+        id={id}
+        role="combobox"
+        aria-expanded={open && suggestions.length > 0}
+        aria-controls={listboxId}
+        aria-autocomplete="list"
+        autoComplete="off"
+        value={value}
+        placeholder={placeholder}
+        onChange={(e) => handleChange(e.target.value)}
+        onKeyDown={onKeyDown}
+        onFocus={() => value.trim().length >= 2 && suggestions.length > 0 && setOpen(true)}
+        onBlur={() => setTimeout(() => setOpen(false), 120)}
+        className="w-full h-9 px-3 rounded-md border border-ih-border bg-ih-bg-card text-[13px] focus:shadow-ih-focus outline-none"
+      />
+      {open && suggestions.length > 0 && (
+        <ul
+          id={listboxId}
+          role="listbox"
+          className="absolute z-30 mt-1 w-full max-h-64 overflow-y-auto rounded-md border border-ih-border bg-ih-bg-card shadow-ih-popover py-1"
+        >
+          {suggestions.map((s, i) => (
+            <li
+              key={s.placeId}
+              role="option"
+              aria-selected={i === active}
+              // onMouseDown (not onClick) so it fires before the input's onBlur.
+              onMouseDown={(e) => {
+                e.preventDefault();
+                choose(s);
+              }}
+              onMouseEnter={() => setActive(i)}
+              className={`px-3 py-2 cursor-pointer text-[13px] ${i === active ? "bg-ih-primary-tint text-ih-primary" : "text-ih-fg-2"}`}
+            >
+              <span className="font-medium">{s.mainText}</span>
+              {s.secondaryText && <span className="text-ih-fg-4"> {s.secondaryText}</span>}
+            </li>
+          ))}
+        </ul>
+      )}
+      {detailsFetcher.state === "loading" && (
+        <p className="mt-1 text-[11px] text-ih-fg-4">{m.common_loading()}</p>
+      )}
+    </div>
+  );
+}
diff --git a/app/components/address/GoogleMap.test.tsx b/app/components/address/GoogleMap.test.tsx
new file mode 100644
index 00000000..ffd1cb1d
--- /dev/null
+++ b/app/components/address/GoogleMap.test.tsx
@@ -0,0 +1,42 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render } from "@testing-library/react";
+
+// Prevent the real SDK loader from injecting a <script> / touching the network:
+// importLibrary never resolves, so the component only ever renders its
+// placeholder div (which is all these tests assert).
+vi.mock("@googlemaps/js-api-loader", () => ({
+  Loader: class {
+    importLibrary() {
+      return new Promise(() => {});
+    }
+  },
+}));
+
+vi.mock("react-router", () => ({ useRouteLoaderData: vi.fn() }));
+
+import { GoogleMap } from "./GoogleMap";
+import { useRouteLoaderData } from "react-router";
+
+const mockRootData = vi.mocked(useRouteLoaderData);
+
+describe("GoogleMap (fail-closed)", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it("renders nothing when the Maps key is unset", () => {
+    mockRootData.mockReturnValue({ mapsApiKey: null });
+    const { container } = render(<GoogleMap lat={30.26} lng={-97.74} />);
+    expect(container.querySelector("[data-map]")).toBeNull();
+  });
+
+  it("renders nothing when coordinates are missing even with a key", () => {
+    mockRootData.mockReturnValue({ mapsApiKey: "k" });
+    const { container } = render(<GoogleMap />);
+    expect(container.querySelector("[data-map]")).toBeNull();
+  });
+
+  it("renders the map container when a key and coordinates are present", () => {
+    mockRootData.mockReturnValue({ mapsApiKey: "k" });
+    const { container } = render(<GoogleMap lat={30.26} lng={-97.74} />);
+    expect(container.querySelector("[data-map]")).not.toBeNull();
+  });
+});
diff --git a/app/components/address/GoogleMap.tsx b/app/components/address/GoogleMap.tsx
new file mode 100644
index 00000000..544ce72a
--- /dev/null
+++ b/app/components/address/GoogleMap.tsx
@@ -0,0 +1,100 @@
+import { useEffect, useRef } from "react";
+import { useRouteLoaderData } from "react-router";
+import { Loader } from "@googlemaps/js-api-loader";
+
+/**
+ * Interactive Google Maps marker (Spec 5D B4, #198). Fail-closed: renders
+ * nothing when the browser-side Maps key is unset (root loader → null) or when
+ * no coordinates are available, so address entry works with or without a map.
+ *
+ * The key is read from the root loader via useRouteLoaderData("root") — the same
+ * pattern Sidebar/useTheme use — rather than a global, avoiding prop-drilling
+ * through the wizard and editor trees.
+ *
+ * The Maps JS SDK is a deliberate CDN exception (see security-headers CSP); it
+ * cannot be self-hosted. We keep it off the `google.maps` global types (the app
+ * tsconfig restricts @types) by describing only the slice we use structurally.
+ */
+
+interface LatLng {
+  lat: number;
+  lng: number;
+}
+interface MapsMap {
+  setCenter(pos: LatLng): void;
+}
+interface MapsLibrarySlice {
+  Map: new (el: HTMLElement, opts: Record<string, unknown>) => MapsMap;
+}
+interface MarkerLibrarySlice {
+  AdvancedMarkerElement: new (opts: { map: MapsMap; position: LatLng }) => unknown;
+}
+
+export function GoogleMap({
+  lat,
+  lng,
+  className,
+}: {
+  lat?: number | null;
+  lng?: number | null;
+  className?: string;
+}) {
+  const root = useRouteLoaderData("root") as { mapsApiKey?: string | null } | undefined;
+  const apiKey = root?.mapsApiKey ?? null;
+  const ref = useRef<HTMLDivElement>(null);
+  const mapRef = useRef<MapsMap | null>(null);
+
+  const hasCoords = typeof lat === "number" && typeof lng === "number";
+
+  useEffect(() => {
+    if (!apiKey || !hasCoords || !ref.current) return;
+    const position: LatLng = { lat: lat as number, lng: lng as number };
+
+    // If the map is already created, just recenter it (address changed).
+    if (mapRef.current) {
+      mapRef.current.setCenter(position);
+      return;
+    }
+
+    let cancelled = false;
+    // Local structural typing isolates us from the google.maps global namespace.
+    const loader = new Loader({ apiKey, version: "weekly" }) as unknown as {
+      importLibrary(name: "maps"): Promise<MapsLibrarySlice>;
+      importLibrary(name: "marker"): Promise<MarkerLibrarySlice>;
+    };
+
+    void Promise.all([loader.importLibrary("maps"), loader.importLibrary("marker")])
+      .then(([maps, markerLib]) => {
+        if (cancelled || !ref.current) return;
+        const map = new maps.Map(ref.current, {
+          center: position,
+          zoom: 17,
+          // DEMO_MAP_ID lets AdvancedMarkerElement render with any platform key
+          // without a cloud-configured map style.
+          mapId: "DEMO_MAP_ID",
+          disableDefaultUI: true,
+          gestureHandling: "cooperative",
+        });
+        mapRef.current = map;
+        new markerLib.AdvancedMarkerElement({ map, position });
+      })
+      .catch(() => {
+        // Network/SDK failure — leave the placeholder div; address entry is
+        // unaffected.
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [apiKey, hasCoords, lat, lng]);
+
+  if (!apiKey || !hasCoords) return null;
+
+  return (
+    <div
+      ref={ref}
+      data-map
+      className={className ?? "w-full h-48 rounded-md border border-ih-border bg-ih-bg-muted overflow-hidden"}
+    />
+  );
+}
diff --git a/app/root.tsx b/app/root.tsx
index 69c278a7..8054010f 100644
--- a/app/root.tsx
+++ b/app/root.tsx
@@ -32,11 +32,27 @@ import { ToastPortal } from "~/components/Toast";
 // returns from the ALS store with no side effect.
 import { getLocale } from "~/paraglide/runtime";
 
-export function loader({ request }: Route.LoaderArgs): UiPrefs & { locale: string } {
+export function loader({
+  request,
+  context,
+}: Route.LoaderArgs): UiPrefs & { locale: string; mapsApiKey: string | null } {
   // getLocale() here runs on the server inside the paraglide ALS scope
   // (workers/app.ts wraps the whole RR render), so it resolves the request's
   // locale and returns without the client-side setLocale() self-init side effect.
-  return { ...parseUiPrefs(request.headers.get("Cookie")), locale: getLocale() };
+  //
+  // mapsApiKey (Spec 5D B4): the Google Maps JS key is browser-side by design
+  // (the SDK runs in the browser), so it is surfaced here for GoogleMap to read
+  // via useRouteLoaderData("root"). It is an HTTP-referrer-restricted platform
+  // key; null when unset → the map fails closed and renders nothing.
+  // GOOGLE_MAPS_JS_API_KEY is an optional runtime var not present in the
+  // wrangler-generated `Env` type, so read it through a narrow cast (the same
+  // approach oauth/authorize.tsx uses for its env subset).
+  const env = context.cloudflare.env as unknown as { GOOGLE_MAPS_JS_API_KEY?: string };
+  return {
+    ...parseUiPrefs(request.headers.get("Cookie")),
+    locale: getLocale(),
+    mapsApiKey: env.GOOGLE_MAPS_JS_API_KEY ?? null,
+  };
 }
 
 export function meta(_args: Route.MetaArgs) {
diff --git a/app/routes.ts b/app/routes.ts
index 2287de2f..a0b8d353 100644
--- a/app/routes.ts
+++ b/app/routes.ts
@@ -111,6 +111,8 @@ export default [
     route("resources/schedule-conflicts", "routes/resources/schedule-conflicts.ts"),
     route("resources/holiday-check", "routes/resources/holiday-check.ts"),
     route("resources/week-summary", "routes/resources/week-summary.ts"),
+    // #198 — Google Places autocomplete/details BFF (token-relay proxy).
+    route("resources/places", "routes/resources/places.tsx"),
     // Inspections workspace — the primary list/stats/wizard surface (formerly
     // /dashboard). The thin status-grouped list was retired; this is the one
     // canonical inspections route.
diff --git a/app/routes/resources/places.test.ts b/app/routes/resources/places.test.ts
new file mode 100644
index 00000000..c0f46e6c
--- /dev/null
+++ b/app/routes/resources/places.test.ts
@@ -0,0 +1,93 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+vi.mock("~/lib/session.server", () => ({ getToken: vi.fn() }));
+vi.mock("~/lib/api-client.server", () => ({ createApi: vi.fn() }));
+
+import { loader } from "./places";
+import { getToken } from "~/lib/session.server";
+import { createApi } from "~/lib/api-client.server";
+
+const mockGetToken = vi.mocked(getToken);
+const mockCreateApi = vi.mocked(createApi);
+
+type Args = Parameters<typeof loader>[0];
+const ctx = {} as Args["context"];
+
+function call(url: string): Promise<{ suggestions: unknown[]; address: unknown }> {
+  return loader({ request: new Request(url), context: ctx, params: {} } as Args) as Promise<{
+    suggestions: unknown[];
+    address: unknown;
+  }>;
+}
+
+function apiWith(autocomplete: unknown, details: unknown) {
+  return {
+    places: {
+      autocomplete: { $get: vi.fn().mockResolvedValue(autocomplete) },
+      details: { $get: vi.fn().mockResolvedValue(details) },
+    },
+  } as unknown as ReturnType<typeof createApi>;
+}
+
+describe("resources.places loader", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it("returns empty when unauthenticated", async () => {
+    mockGetToken.mockResolvedValue(null);
+    const out = await call("http://x/resources/places?q=123&session=12345678");
+    expect(out.suggestions).toEqual([]);
+    expect(out.address).toBeNull();
+    expect(mockCreateApi).not.toHaveBeenCalled();
+  });
+
+  it("returns suggestions for ?q=", async () => {
+    mockGetToken.mockResolvedValue("tok");
+    mockCreateApi.mockReturnValue(
+      apiWith(
+        {
+          ok: true,
+          json: async () => ({
+            data: [
+              { placeId: "p1", description: "123 Main St, Austin", mainText: "123 Main St", secondaryText: "Austin, TX" },
+              { placeId: "p2", description: "123 Main Ave", mainText: "123 Main Ave", secondaryText: "Dallas, TX" },
+            ],
+          }),
+        },
+        null,
+      ),
+    );
+    const out = await call("http://x/resources/places?q=123%20Main&session=12345678");
+    expect(out.suggestions).toHaveLength(2);
+    expect(out.address).toBeNull();
+  });
+
+  it("returns a structured address for ?placeId=", async () => {
+    mockGetToken.mockResolvedValue("tok");
+    mockCreateApi.mockReturnValue(
+      apiWith(null, {
+        ok: true,
+        json: async () => ({
+          data: { placeId: "p1", formatted: "123 Main St", street: "123 Main St", city: "Austin", state: "TX", zip: "78701", county: "Travis", lat: 30.26, lng: -97.74 },
+        }),
+      }),
+    );
+    const out = await call("http://x/resources/places?placeId=p1&session=12345678");
+    expect((out.address as { placeId: string }).placeId).toBe("p1");
+    expect((out.address as { lat: number }).lat).toBeCloseTo(30.26);
+  });
+
+  it("degrades to empty when the upstream call is not ok (e.g. no API key -> 400)", async () => {
+    mockGetToken.mockResolvedValue("tok");
+    mockCreateApi.mockReturnValue(apiWith({ ok: false }, null));
+    const out = await call("http://x/resources/places?q=123&session=12345678");
+    expect(out.suggestions).toEqual([]);
+  });
+
+  it("rejects a too-short session token without hitting the API", async () => {
+    mockGetToken.mockResolvedValue("tok");
+    const api = apiWith({ ok: true, json: async () => ({ data: [] }) }, null);
+    mockCreateApi.mockReturnValue(api);
+    const out = await call("http://x/resources/places?q=123&session=short");
+    expect(out.suggestions).toEqual([]);
+  });
+});
diff --git a/app/routes/resources/places.tsx b/app/routes/resources/places.tsx
new file mode 100644
index 00000000..82db2fe4
--- /dev/null
+++ b/app/routes/resources/places.tsx
@@ -0,0 +1,76 @@
+import type { Route } from "./+types/places";
+import { getToken } from "~/lib/session.server";
+import { createApi } from "~/lib/api-client.server";
+
+/**
+ * BFF resource route for Google Places (Spec 5D B4, #198).
+ *
+ * The browser must never call `/api/places/*` directly — those endpoints require
+ * the session JWT and would 401 (feedback_core_bff_no_client_fetch). This loader
+ * holds the token relay and proxies to the in-process API:
+ *   - `?q=<text>&session=<tok>`      → `{ suggestions: PlaceSuggestion[] }`
+ *   - `?placeId=<id>&session=<tok>`  → `{ address: AddressSelection | null }`
+ *
+ * The `session` token is a per-typing-session UUID minted client-side; it flows
+ * autocomplete → details unchanged so Google bills the whole sequence as ONE
+ * Autocomplete session. The upstream `/api/places/*` handlers throw HTTP 400
+ * when GOOGLE_PLACES_API_KEY is unset, so we degrade to an empty result (the
+ * address input stays usable as free text).
+ */
+
+export type PlaceSuggestion = {
+  placeId: string;
+  description: string;
+  mainText: string;
+  secondaryText: string;
+};
+
+/** Normalized address emitted when a suggestion is resolved to its details. */
+export type AddressSelection = {
+  placeId: string;
+  formatted: string;
+  street: string | null;
+  city: string | null;
+  state: string | null;
+  zip: string | null;
+  county: string | null;
+  lat: number;
+  lng: number;
+};
+
+const RELAY = { headers: { "x-token-relay": "1" } } as const;
+
+export async function loader({ request, context }: Route.LoaderArgs) {
+  const token = await getToken(context, request);
+  if (!token) return { suggestions: [] as PlaceSuggestion[], address: null };
+
+  const url = new URL(request.url);
+  const q = url.searchParams.get("q") ?? "";
+  const placeId = url.searchParams.get("placeId") ?? "";
+  const session = url.searchParams.get("session") ?? "";
+
+  // A valid session token is required by the upstream schema (min 8 chars).
+  if (session.length < 8) return { suggestions: [] as PlaceSuggestion[], address: null };
+
+  const api = createApi(context, { token });
+
+  // Details branch — resolve a chosen suggestion to a structured address.
+  if (placeId) {
+    const res = await api.places.details
+      .$get({ query: { placeId, session } }, RELAY)
+      .catch(() => null);
+    if (!res?.ok) return { suggestions: [] as PlaceSuggestion[], address: null };
+    const body = (await res.json()) as { data?: AddressSelection };
+    return { suggestions: [] as PlaceSuggestion[], address: body.data ?? null };
+  }
+
+  // Autocomplete branch — needs at least 2 chars (upstream min(2)).
+  if (q.trim().length < 2) return { suggestions: [] as PlaceSuggestion[], address: null };
+
+  const res = await api.places.autocomplete
+    .$get({ query: { q, session } }, RELAY)
+    .catch(() => null);
+  if (!res?.ok) return { suggestions: [] as PlaceSuggestion[], address: null };
+  const body = (await res.json()) as { data?: PlaceSuggestion[] };
+  return { suggestions: body.data ?? [], address: null };
+}
diff --git a/package-lock.json b/package-lock.json
index c77b12a0..b603b52c 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -11,6 +11,7 @@
         "@cloudflare/workers-oauth-provider": "^0.8.1",
         "@conform-to/react": "^1.19.4",
         "@conform-to/zod": "^1.19.4",
+        "@googlemaps/js-api-loader": "^1.16.10",
         "@inlang/paraglide-js": "2.22.0",
         "@modelcontextprotocol/sdk": "^1.29.0",
         "@stripe/react-stripe-js": "^6.5.0",
@@ -2002,6 +2003,12 @@
         "url": "https://github.com/sponsors/ayuhito"
       }
     },
+    "node_modules/@googlemaps/js-api-loader": {
+      "version": "1.16.10",
+      "resolved": "https://registry.npmmirror.com/@googlemaps/js-api-loader/-/js-api-loader-1.16.10.tgz",
+      "integrity": "sha512-c2erv2k7P2ilYzMmtYcMgAR21AULosQuUHJbStnrvRk2dG93k5cqptDrh9A8p+ZNlyhiqEOgHW7N9PAizdUM7Q==",
+      "license": "Apache-2.0"
+    },
     "node_modules/@hono/node-server": {
       "version": "1.19.14",
       "resolved": "https://registry.npmmirror.com/@hono/node-server/-/node-server-1.19.14.tgz",
diff --git a/package.json b/package.json
index a97d3814..38411eb1 100644
--- a/package.json
+++ b/package.json
@@ -87,6 +87,7 @@
     "@cloudflare/workers-oauth-provider": "^0.8.1",
     "@conform-to/react": "^1.19.4",
     "@conform-to/zod": "^1.19.4",
+    "@googlemaps/js-api-loader": "^1.16.10",
     "@inlang/paraglide-js": "2.22.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@stripe/react-stripe-js": "^6.5.0",
diff --git a/server/lib/middleware/security-headers.ts b/server/lib/middleware/security-headers.ts
index 3bc8e096..f22f3d74 100644
--- a/server/lib/middleware/security-headers.ts
+++ b/server/lib/middleware/security-headers.ts
@@ -29,11 +29,16 @@ export const securityHeaders: MiddlewareHandler<HonoConfig> = async (c, next) =>
         'Content-Security-Policy',
         [
             "default-src 'self'",
-            "script-src 'self' 'unsafe-inline' https://challenges.cloudflare.com",
+            // maps.googleapis.com: the Google Maps JavaScript SDK (address
+            // autocomplete map, Spec 5D B4) — a deliberate CDN exception to the
+            // "no CDN except GA + Turnstile" rule; the SDK cannot be self-hosted.
+            "script-src 'self' 'unsafe-inline' https://challenges.cloudflare.com https://maps.googleapis.com",
             "style-src 'self' 'unsafe-inline'",
             "font-src 'self' data:",
-            "img-src 'self' data: blob:",
-            "connect-src 'self' https://challenges.cloudflare.com",
+            // maps.gstatic.com / maps.googleapis.com: map tiles + marker sprites.
+            "img-src 'self' data: blob: https://maps.gstatic.com https://maps.googleapis.com",
+            // maps.googleapis.com: the Maps SDK's own XHR/fetch for tile metadata.
+            "connect-src 'self' https://challenges.cloudflare.com https://maps.googleapis.com",
             // 'self' required so the Settings → Embed Widget page can iframe
             // its own /book?embed=1 preview. Without it the live preview is blank.
             "frame-src 'self' https://challenges.cloudflare.com",
diff --git a/server/types/hono.ts b/server/types/hono.ts
index b0952e50..0fba1f98 100644
--- a/server/types/hono.ts
+++ b/server/types/hono.ts
@@ -202,6 +202,14 @@ export interface AppEnv {
     // back to a free-text address input (no autocomplete dropdown).
     GOOGLE_PLACES_API_KEY?: string;
 
+    // Spec 5D (B4) — Google Maps JavaScript API key for the browser-side
+    // interactive marker map. Unlike GOOGLE_PLACES_API_KEY this one IS exposed
+    // to the client (surfaced via the root loader → `useRouteLoaderData("root")`)
+    // because the Maps JS SDK runs in the browser. It MUST be an HTTP-referrer-
+    // restricted platform key. Optional/fail-closed: when absent, GoogleMap
+    // renders nothing and address entry still works (autocomplete + free text).
+    GOOGLE_MAPS_JS_API_KEY?: string;
+
     // Sprint 3 S3-1 — Estated.io public-records API. Server-side proxy holds
     // the key so it never leaks to the client. Optional: when absent the
     // /api/inspections/:id/property-facts/autofill endpoint returns

From 0408cab9bcb35fe65095cc0d379292998837c0b3 Mon Sep 17 00:00:00 2001
From: important-new <important-new@hotmail.com>
Date: Mon, 20 Jul 2026 20:18:06 +0800
Subject: [PATCH 09/12] feat(places): wire address autocomplete + map into the
 new-inspection wizard (#198)

The wizard's Property step now uses AddressAutocomplete + GoogleMap. Picking a
suggestion captures a structured, geocoded AddressSelection; editing the text by
hand clears it so stale coordinates are never persisted. handleSubmit forwards
the structured fields, and buildCreateInspectionJson maps them into the create
payload (the server already accepts them and stamps addressGeocodedAt).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MkL3cCs9TmQd7zueiAnJ8s
---
 app/components/NewInspectionWizard.test.tsx   |  8 +++-
 app/components/NewInspectionWizard.tsx        | 33 ++++++++++++++-
 .../new-inspection/PropertyStep.tsx           | 24 ++++++++++-
 app/lib/inspection-create.test.ts             | 40 +++++++++++++++++++
 app/lib/inspection-create.ts                  | 33 +++++++++++++++
 scripts/file-size-baseline.json               |  2 +-
 6 files changed, 134 insertions(+), 6 deletions(-)

diff --git a/app/components/NewInspectionWizard.test.tsx b/app/components/NewInspectionWizard.test.tsx
index 8bee3c25..ecd03bf8 100644
--- a/app/components/NewInspectionWizard.test.tsx
+++ b/app/components/NewInspectionWizard.test.tsx
@@ -167,8 +167,12 @@ describe('NewInspectionWizard — guard test for client + buyer-agent payload',
         const addressInput = getByPlaceholderText(/123 Main|St.*City/i) as HTMLInputElement;
         fireEvent.change(addressInput, { target: { value: '123 Main Street' } });
 
-        const selects = getAllByRole('combobox') as HTMLSelectElement[];
-        fireEvent.change(selects[0], { target: { value: 'tpl-1' } });
+        // Two comboboxes now exist on the property step: the address
+        // autocomplete <input role="combobox"> (#198) and the template <select>.
+        // Target the native <select> specifically.
+        const combos = getAllByRole('combobox') as HTMLElement[];
+        const templateSelect = combos.find((el) => el.tagName === 'SELECT') as HTMLSelectElement;
+        fireEvent.change(templateSelect, { target: { value: 'tpl-1' } });
 
         let buttons = getAllByRole('button') as HTMLButtonElement[];
         let nextBtn = buttons.find((btn) => btn.textContent?.includes('Next'));
diff --git a/app/components/NewInspectionWizard.tsx b/app/components/NewInspectionWizard.tsx
index 9734e6b2..eaeae9bc 100644
--- a/app/components/NewInspectionWizard.tsx
+++ b/app/components/NewInspectionWizard.tsx
@@ -7,6 +7,7 @@ import { ServicesStep } from "./new-inspection/ServicesStep";
 import { ScheduleStep } from "./new-inspection/ScheduleStep";
 import { TeamStep } from "./new-inspection/TeamStep";
 import { QuotaExceededPanel } from "./new-inspection/QuotaExceededPanel";
+import type { AddressSelection } from "~/routes/resources/places";
 import { m } from "~/paraglide/messages";
 
 function stepLabel(id: WizardStepId): string {
@@ -94,6 +95,10 @@ export function NewInspectionWizard({
   const [stepIdx, setStepIdx] = useState(0);
   const [propertyType, setPropertyType] = useState("single_family");
   const [address, setAddress] = useState("");
+  // #198 — structured, geocoded address captured when the inspector picks a
+  // Places suggestion. Cleared when they edit the text back to free-form, so we
+  // never persist stale coordinates against a hand-typed address.
+  const [addressSel, setAddressSel] = useState<AddressSelection | null>(null);
   const [templateId, setTemplateId] = useState("");
   // Stores selected service IDs (matched against the tenant's services table).
   const [services, setServices] = useState<Set<string>>(new Set());
@@ -172,6 +177,7 @@ export function NewInspectionWizard({
       setStepIdx(0);
       setPropertyType("single_family");
       setAddress("");
+      setAddressSel(null);
       setTemplateId("");
       setTemplateQuery("");
       setServices(new Set());
@@ -292,6 +298,17 @@ export function NewInspectionWizard({
     setAgentDropdownOpen(false);
   }
 
+  // #198 — editing the address text by hand invalidates any previously picked
+  // Places suggestion (its coordinates no longer describe what's typed).
+  function handleAddressChange(v: string) {
+    setAddress(v);
+    if (addressSel) setAddressSel(null);
+  }
+  function handleAddressSelect(sel: AddressSelection) {
+    setAddressSel(sel);
+    setAddress(sel.formatted);
+  }
+
   if (!open) return null;
 
   const toggleService = (id: string) => {
@@ -368,6 +385,17 @@ export function NewInspectionWizard({
         intent: "create",
         propertyType,
         address,
+        // #198 — structured geocoded address (empty strings when the inspector
+        // typed a free-form address the API couldn't match; the server stamps
+        // addressGeocodedAt itself).
+        addressPlaceId: addressSel?.placeId ?? "",
+        addressStreet: addressSel?.street ?? "",
+        addressCity: addressSel?.city ?? "",
+        addressState: addressSel?.state ?? "",
+        addressZip: addressSel?.zip ?? "",
+        addressCounty: addressSel?.county ?? "",
+        addressLat: addressSel?.lat != null ? String(addressSel.lat) : "",
+        addressLng: addressSel?.lng != null ? String(addressSel.lng) : "",
         templateId,
         serviceIds: [...services].join(","),
         serviceSelectionsJson,
@@ -420,7 +448,10 @@ export function NewInspectionWizard({
               propertyType={propertyType}
               setPropertyType={setPropertyType}
               address={address}
-              setAddress={setAddress}
+              setAddress={handleAddressChange}
+              onAddressSelect={handleAddressSelect}
+              addressLat={addressSel?.lat}
+              addressLng={addressSel?.lng}
               templates={templates}
               templateId={templateId}
               setTemplateId={setTemplateId}
diff --git a/app/components/new-inspection/PropertyStep.tsx b/app/components/new-inspection/PropertyStep.tsx
index 32262cc1..99d2f279 100644
--- a/app/components/new-inspection/PropertyStep.tsx
+++ b/app/components/new-inspection/PropertyStep.tsx
@@ -1,4 +1,7 @@
 import type { WizardTemplate } from "../NewInspectionWizard";
+import { AddressAutocomplete } from "../address/AddressAutocomplete";
+import { GoogleMap } from "../address/GoogleMap";
+import type { AddressSelection } from "~/routes/resources/places";
 import { m } from "~/paraglide/messages";
 
 // `label` is a thunk so each type name resolves at render inside the paraglide
@@ -14,6 +17,9 @@ export function PropertyStep({
   setPropertyType,
   address,
   setAddress,
+  onAddressSelect,
+  addressLat,
+  addressLng,
   templates,
   templateId,
   setTemplateId,
@@ -26,6 +32,10 @@ export function PropertyStep({
   setPropertyType: (v: string) => void;
   address: string;
   setAddress: (v: string) => void;
+  /** Fires when a suggestion resolves to a structured, geocoded address. */
+  onAddressSelect: (sel: AddressSelection) => void;
+  addressLat?: number | null;
+  addressLng?: number | null;
   templates: WizardTemplate[];
   templateId: string;
   setTemplateId: (v: string) => void;
@@ -47,8 +57,18 @@ export function PropertyStep({
         </div>
       </div>
       <div>
-        <label className="block text-[12px] font-bold text-ih-fg-3 mb-1.5">{m.newinsp_property_address_label()}</label>
-        <input value={address} onChange={(e) => setAddress(e.target.value)} placeholder={m.newinsp_property_address_ph()} className="w-full h-9 px-3 rounded-md border border-ih-border bg-ih-bg-card text-[13px] focus:shadow-ih-focus outline-none" />
+        <label htmlFor="property-address" className="block text-[12px] font-bold text-ih-fg-3 mb-1.5">{m.newinsp_property_address_label()}</label>
+        <AddressAutocomplete
+          value={address}
+          onValueChange={setAddress}
+          onSelect={onAddressSelect}
+          placeholder={m.newinsp_property_address_ph()}
+        />
+        {typeof addressLat === "number" && typeof addressLng === "number" && (
+          <div className="mt-2">
+            <GoogleMap lat={addressLat} lng={addressLng} className="w-full h-40 rounded-md border border-ih-border bg-ih-bg-muted overflow-hidden" />
+          </div>
+        )}
       </div>
       <div>
         <label className="block text-[12px] font-bold text-ih-fg-3 mb-1.5">{m.newinsp_property_template_label()}</label>
diff --git a/app/lib/inspection-create.test.ts b/app/lib/inspection-create.test.ts
index 49235c75..620c8a79 100644
--- a/app/lib/inspection-create.test.ts
+++ b/app/lib/inspection-create.test.ts
@@ -149,6 +149,46 @@ describe("buildCreateInspectionJson", () => {
         expect("serviceIds" in json).toBe(false);
         expect("serviceSelections" in json).toBe(false);
     });
+
+    // #198 structured-address forwarding
+    it("forwards structured address fields (with numeric lat/lng) when a Places suggestion was picked", () => {
+        const json = buildCreateInspectionJson(fd({
+            address: "123 Main St, Austin, TX 78701",
+            templateId: "t",
+            addressPlaceId: "ChIJabc",
+            addressStreet: "123 Main St",
+            addressCity: "Austin",
+            addressState: "TX",
+            addressZip: "78701",
+            addressCounty: "Travis",
+            addressLat: "30.2672",
+            addressLng: "-97.7431",
+        }));
+        expect(json.addressPlaceId).toBe("ChIJabc");
+        expect(json.addressStreet).toBe("123 Main St");
+        expect(json.addressCity).toBe("Austin");
+        expect(json.addressState).toBe("TX");
+        expect(json.addressZip).toBe("78701");
+        expect(json.addressCounty).toBe("Travis");
+        expect(json.addressLat).toBeCloseTo(30.2672);
+        expect(json.addressLng).toBeCloseTo(-97.7431);
+    });
+
+    it("omits all structured address fields for a hand-typed free-form address", () => {
+        const json = buildCreateInspectionJson(fd({ address: "Grandma's cabin by the lake", templateId: "t" }));
+        expect("addressPlaceId" in json).toBe(false);
+        expect("addressLat" in json).toBe(false);
+        expect("addressLng" in json).toBe(false);
+    });
+
+    it("drops non-finite lat/lng rather than forwarding NaN", () => {
+        const json = buildCreateInspectionJson(fd({
+            address: "1 A St", templateId: "t",
+            addressLat: "not-a-number", addressLng: "",
+        }));
+        expect("addressLat" in json).toBe(false);
+        expect("addressLng" in json).toBe(false);
+    });
 });
 
 describe("dollarsToCents", () => {
diff --git a/app/lib/inspection-create.ts b/app/lib/inspection-create.ts
index 9491ac48..24d13a30 100644
--- a/app/lib/inspection-create.ts
+++ b/app/lib/inspection-create.ts
@@ -42,6 +42,17 @@ interface ServiceSelection {
 export interface CreateInspectionJson {
   propertyAddress: string;
   templateId: string;
+  // #198 — structured, geocoded address from Places autocomplete. All optional;
+  // omitted for hand-typed free-form addresses. The server stamps
+  // addressGeocodedAt when addressPlaceId is present.
+  addressPlaceId?: string;
+  addressStreet?: string;
+  addressCity?: string;
+  addressState?: string;
+  addressZip?: string;
+  addressCounty?: string;
+  addressLat?: number;
+  addressLng?: number;
   date?: string;
   inspectorId?: string;
   /** Legacy flat list — kept for backward compat. */
@@ -69,6 +80,20 @@ export function dollarsToCents(value: string | number | null | undefined): numbe
 export function buildCreateInspectionJson(formData: FormData): CreateInspectionJson {
   const address = String(formData.get("address") || "");
   const templateId = String(formData.get("templateId") || "");
+
+  // #198 — structured address fields (present only when a Places suggestion was
+  // picked). Empty strings collapse to omitted; lat/lng parse to finite numbers.
+  const addressPlaceId = String(formData.get("addressPlaceId") || "").trim();
+  const addressStreet = String(formData.get("addressStreet") || "").trim();
+  const addressCity = String(formData.get("addressCity") || "").trim();
+  const addressState = String(formData.get("addressState") || "").trim();
+  const addressZip = String(formData.get("addressZip") || "").trim();
+  const addressCounty = String(formData.get("addressCounty") || "").trim();
+  const latRaw = String(formData.get("addressLat") || "").trim();
+  const lngRaw = String(formData.get("addressLng") || "").trim();
+  const addressLat = latRaw ? Number(latRaw) : undefined;
+  const addressLng = lngRaw ? Number(lngRaw) : undefined;
+
   const dateStr = String(formData.get("date") || "");
   const time = String(formData.get("time") || "") || "09:00";
   const inspectorId = String(formData.get("inspectorId") || "");
@@ -131,6 +156,14 @@ export function buildCreateInspectionJson(formData: FormData): CreateInspectionJ
   return {
     propertyAddress: address,
     templateId,
+    ...(addressPlaceId ? { addressPlaceId } : {}),
+    ...(addressStreet ? { addressStreet } : {}),
+    ...(addressCity ? { addressCity } : {}),
+    ...(addressState ? { addressState } : {}),
+    ...(addressZip ? { addressZip } : {}),
+    ...(addressCounty ? { addressCounty } : {}),
+    ...(addressLat != null && Number.isFinite(addressLat) ? { addressLat } : {}),
+    ...(addressLng != null && Number.isFinite(addressLng) ? { addressLng } : {}),
     ...(dateStr ? { date: `${dateStr}T${time}:00Z` } : {}),
     ...(inspectorId && UUID_RE.test(inspectorId) ? { inspectorId } : {}),
     ...(serviceIds ? { serviceIds } : {}),
diff --git a/scripts/file-size-baseline.json b/scripts/file-size-baseline.json
index da0bd2b8..71249c47 100644
--- a/scripts/file-size-baseline.json
+++ b/scripts/file-size-baseline.json
@@ -29,6 +29,7 @@
   "server/api/auth.ts": 564,
   "app/lib/collab/results-binding.ts": 560,
   "server/api/calendar.ts": 547,
+  "app/components/NewInspectionWizard.tsx": 545,
   "server/api/inspections/core.ts": 541,
   "server/api/portal.ts": 539,
   "server/services/inspection/inspection-publish.service.ts": 536,
@@ -37,7 +38,6 @@
   "server/services/inspection/inspection-photo.service.ts": 531,
   "server/api/inspections/media-studio.ts": 529,
   "server/api/public-report.ts": 522,
-  "app/components/NewInspectionWizard.tsx": 514,
   "app/components/settings/ManagedComplianceWizard.tsx": 514,
   "server/services/inspection-request.service.ts": 501,
   "server/services/report-export-consumer.ts": 499,

From a7bcbc299894f7b00fffc061562aeef937ea932b Mon Sep 17 00:00:00 2001
From: important-new <important-new@hotmail.com>
Date: Mon, 20 Jul 2026 20:34:10 +0800
Subject: [PATCH 10/12] feat(places): 'Fetch property details' autofill button
 in the editor (#200)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PropertyInfoForm gains a public-records lookup: the button relays the address to
the Estated proxy via the editor BFF action (autofill-property-facts intent),
then fills ONLY the property-fact fields the inspector hasn't set — a lookup
never clobbers manual work — and commits the merged snapshot through the
existing save-property-facts path. Surfaces which fields were filled, and
degrades with a clear message when the provider key is unset or the address
isn't found.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MkL3cCs9TmQd7zueiAnJ8s
---
 .../editor/PropertyInfoForm.test.tsx          | 62 +++++++++++++
 app/components/editor/PropertyInfoForm.tsx    | 86 ++++++++++++++++++-
 app/routes/inspection-edit/action.server.ts   | 25 ++++++
 messages/en/editor-2.json                     |  7 ++
 scripts/file-size-baseline.json               |  2 +-
 5 files changed, 177 insertions(+), 5 deletions(-)
 create mode 100644 app/components/editor/PropertyInfoForm.test.tsx

diff --git a/app/components/editor/PropertyInfoForm.test.tsx b/app/components/editor/PropertyInfoForm.test.tsx
new file mode 100644
index 00000000..b1b0bbee
--- /dev/null
+++ b/app/components/editor/PropertyInfoForm.test.tsx
@@ -0,0 +1,62 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, screen, fireEvent, waitFor } from "@testing-library/react";
+import { createRoutesStub } from "react-router";
+import { PropertyInfoForm } from "./PropertyInfoForm";
+
+function mount(
+  actionResult: unknown,
+  handlers: { onSave?: (id: string, v: unknown) => void; onCommit?: (f: Record<string, unknown>) => void },
+) {
+  const inspection: Record<string, unknown> = {
+    propertyType: "single_family",
+    propertyAddress: "123 Main St, Austin, TX 78701",
+    bedrooms: "4", // already set — must NOT be overwritten
+    // yearBuilt / sqft / etc. absent = empty = fillable
+  };
+  const Stub = createRoutesStub([
+    {
+      path: "/",
+      Component: () => (
+        <PropertyInfoForm inspection={inspection} onSave={handlers.onSave} onCommit={handlers.onCommit} />
+      ),
+      action: () => actionResult,
+    },
+  ]);
+  return render(<Stub />);
+}
+
+describe("PropertyInfoForm — Fetch property details (#200)", () => {
+  it("fills only empty fields and never clobbers a value the inspector already set", async () => {
+    const onSave = vi.fn();
+    const onCommit = vi.fn();
+    mount(
+      { intent: "autofill-property-facts", facts: { yearBuilt: 1990, bedrooms: 3 }, reason: null },
+      { onSave, onCommit },
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: /fetch property details/i }));
+
+    // The empty yearBuilt gets filled...
+    await waitFor(() => expect(onSave).toHaveBeenCalledWith("yearBuilt", 1990));
+    // ...but the already-set bedrooms is left alone.
+    expect(onSave).not.toHaveBeenCalledWith("bedrooms", 3);
+    // The durable commit is a full snapshot: filled yearBuilt + preserved bedrooms.
+    expect(onCommit).toHaveBeenCalledWith(expect.objectContaining({ yearBuilt: 1990, bedrooms: 4 }));
+    // A summary of what was filled is surfaced.
+    await waitFor(() => expect(screen.getByText(/filled 1 field/i)).toBeTruthy());
+  });
+
+  it("shows an 'unconfigured' message and commits nothing when the provider key is unset", async () => {
+    const onSave = vi.fn();
+    const onCommit = vi.fn();
+    mount(
+      { intent: "autofill-property-facts", facts: null, reason: "NO_API_KEY" },
+      { onSave, onCommit },
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: /fetch property details/i }));
+
+    await waitFor(() => expect(screen.getByText(/isn.t configured/i)).toBeTruthy());
+    expect(onCommit).not.toHaveBeenCalled();
+  });
+});
diff --git a/app/components/editor/PropertyInfoForm.tsx b/app/components/editor/PropertyInfoForm.tsx
index d97c0fa4..81d8ef56 100644
--- a/app/components/editor/PropertyInfoForm.tsx
+++ b/app/components/editor/PropertyInfoForm.tsx
@@ -1,4 +1,5 @@
-import { useMemo, useCallback } from "react";
+import { useMemo, useCallback, useEffect, useState } from "react";
+import { useFetcher } from "react-router";
 import { isDedicatedFactKey } from "~/lib/property-facts-keys";
 import { m } from "~/paraglide/messages";
 
@@ -124,6 +125,72 @@ export function PropertyInfoForm({ inspection, templateFields, propertyAddress,
     onCommit?.(Object.keys(metadata).length ? { ...dedicated, metadata } : dedicated);
   }
 
+  // #200 — "Fetch property details": pull public-records facts for the address
+  // and fill ONLY the fields the inspector hasn't already entered, so a lookup
+  // never clobbers manual work. Rides the editor BFF action (autofill-property-
+  // facts intent) via its own fetcher, then commits the merged snapshot through
+  // the same save-property-facts path as manual edits.
+  const autofillFetcher = useFetcher<{
+    intent?: string;
+    facts?: Record<string, unknown> | null;
+    reason?: string | null;
+  }>();
+  const [autofillMsg, setAutofillMsg] = useState<string | null>(null);
+  const addressString = (propertyAddress || (inspection.propertyAddress as string) || "").trim();
+  const autofilling = autofillFetcher.state !== "idle";
+
+  useEffect(() => {
+    if (autofillFetcher.state !== "idle" || !autofillFetcher.data) return;
+    const data = autofillFetcher.data;
+    if (data.intent !== "autofill-property-facts") return;
+
+    const facts = data.facts;
+    if (!facts) {
+      setAutofillMsg(
+        data.reason === "NO_API_KEY"
+          ? m.editor_property_autofill_unconfigured()
+          : data.reason === "NOT_FOUND"
+            ? m.editor_property_autofill_not_found()
+            : m.editor_property_autofill_failed(),
+      );
+      return;
+    }
+
+    const dedicated: Record<string, unknown> = {};
+    const metadata: Record<string, unknown> = {};
+    const filledLabels: string[] = [];
+    for (const f of metaFields) {
+      const current = inspection[f.id];
+      const isEmpty = current === "" || current === null || current === undefined;
+      const factVal = facts[f.id];
+      let raw = current;
+      if (isEmpty && factVal != null && factVal !== "") {
+        raw = factVal;
+        filledLabels.push(f.label);
+        onSave?.(f.id, factVal); // optimistic — keep the controlled input in sync
+      }
+      const value = coerce(f, raw);
+      if (isDedicatedFactKey(f.id)) dedicated[f.id] = value;
+      else metadata[f.id] = value;
+    }
+
+    if (filledLabels.length) {
+      onCommit?.(Object.keys(metadata).length ? { ...dedicated, metadata } : dedicated);
+      setAutofillMsg(
+        m.editor_property_autofill_filled({ count: filledLabels.length, fields: filledLabels.join(", ") }),
+      );
+    } else {
+      setAutofillMsg(m.editor_property_autofill_none());
+    }
+    // Fires once per settled autofill response; metaFields/inspection/callbacks
+    // are intentionally read fresh at fire time (RR fetcher-effect convention).
+  }, [autofillFetcher.state, autofillFetcher.data]);
+
+  function runAutofill() {
+    setAutofillMsg(null);
+    autofillFetcher.submit({ intent: "autofill-property-facts", addressString }, { method: "post" });
+  }
+
   return (
     <div className="px-6 py-6 max-w-5xl" data-testid="property-info-form">
       <header className="mb-6">
@@ -137,9 +204,20 @@ export function PropertyInfoForm({ inspection, templateFields, propertyAddress,
             </span>
           )}
         </div>
-        <h2 className="text-2xl font-bold tracking-tight text-ih-fg-1">
-          {(propertyAddress || inspection.propertyAddress as string) || m.editor_property_fallback()}
-        </h2>
+        <div className="flex flex-wrap items-center justify-between gap-3">
+          <h2 className="text-2xl font-bold tracking-tight text-ih-fg-1">
+            {(propertyAddress || inspection.propertyAddress as string) || m.editor_property_fallback()}
+          </h2>
+          <button
+            type="button"
+            onClick={runAutofill}
+            disabled={addressString.length < 5 || autofilling}
+            className="h-8 px-3 rounded-md border border-ih-border text-[12px] font-bold text-ih-primary hover:bg-ih-primary-tint disabled:opacity-50 disabled:cursor-not-allowed"
+          >
+            {autofilling ? m.editor_property_autofill_loading() : m.editor_property_autofill_button()}
+          </button>
+        </div>
+        {autofillMsg && <p className="mt-2 text-[12px] text-ih-fg-3">{autofillMsg}</p>}
       </header>
 
       {groups.map((g) => (
diff --git a/app/routes/inspection-edit/action.server.ts b/app/routes/inspection-edit/action.server.ts
index 9df5e2ce..18dec810 100644
--- a/app/routes/inspection-edit/action.server.ts
+++ b/app/routes/inspection-edit/action.server.ts
@@ -91,6 +91,31 @@ export async function action({ request, params, context }: Route.ActionArgs) {
  return { ok: res.ok, intent: "save-property-facts" };
  }
 
+ // #200 — "Fetch property details": look up public-records property facts for
+ // the inspection's address via the Estated proxy. Rides the BFF relay (no raw
+ // client fetch — feedback_core_bff_no_client_fetch). Read-only: it does NOT
+ // persist; the client fills empty fields and commits via save-property-facts.
+ if (intent === "autofill-property-facts") {
+ const addressString = String(formData.get("addressString") ?? "").trim();
+ if (addressString.length < 5) {
+ return { ok: false as const, intent: "autofill-property-facts", facts: null, reason: "BAD_ADDRESS" as const };
+ }
+ const res = await api.inspections[":id"]["property-facts"].autofill.$post({
+ param: { id: params.id },
+ json: { addressString },
+ });
+ if (!res.ok) {
+ return { ok: false as const, intent: "autofill-property-facts", facts: null, reason: "REQUEST_FAILED" as const };
+ }
+ const body = (await res.json()) as { data?: { facts?: Record<string, unknown> | null; reason?: string } };
+ return {
+ ok: true as const,
+ intent: "autofill-property-facts",
+ facts: body.data?.facts ?? null,
+ reason: body.data?.reason ?? null,
+ };
+ }
+
  // Commercial PCA Phase U (Batch C2b) — per-unit editor mutations + lazy scope
  // read. All ride the BFF relay (no bare client fetch to /api/...): the action
  // holds the authed tenant context that the unit routes' requireRole guard
diff --git a/messages/en/editor-2.json b/messages/en/editor-2.json
index 7ccbc1d9..9fbd9e9a 100644
--- a/messages/en/editor-2.json
+++ b/messages/en/editor-2.json
@@ -158,6 +158,13 @@
   "editor_property_complete": "Complete",
   "editor_property_fallback": "Property Info",
   "editor_property_prefilled": "Prefilled",
+  "editor_property_autofill_button": "Fetch property details",
+  "editor_property_autofill_loading": "Fetching…",
+  "editor_property_autofill_filled": "Filled {count} field(s) from public records: {fields}",
+  "editor_property_autofill_none": "No new fields to fill — the details already look complete.",
+  "editor_property_autofill_not_found": "No public records found for this address.",
+  "editor_property_autofill_unconfigured": "Property auto-fill isn't configured on this workspace.",
+  "editor_property_autofill_failed": "Couldn't fetch property details. Please try again.",
   "editor_gate_missing": "Missing: ",
   "editor_gate_none": "(none)",
   "editor_gate_unresolved": " · Unresolved tokens: ",
diff --git a/scripts/file-size-baseline.json b/scripts/file-size-baseline.json
index 71249c47..8d3b80ba 100644
--- a/scripts/file-size-baseline.json
+++ b/scripts/file-size-baseline.json
@@ -42,6 +42,7 @@
   "server/services/inspection-request.service.ts": 501,
   "server/services/report-export-consumer.ts": 499,
   "server/api/repair-builder.ts": 496,
+  "app/routes/inspection-edit/action.server.ts": 482,
   "app/routes/settings-workspace.tsx": 482,
   "app/components/collab/VersionHistoryPanel.tsx": 478,
   "server/api/bookings.ts": 477,
@@ -49,7 +50,6 @@
   "server/api/admin/admin-config.ts": 472,
   "server/portal/integration.routes.ts": 472,
   "server/api/inspections/media.ts": 468,
-  "app/routes/inspection-edit/action.server.ts": 457,
   "app/components/editor/CostItemsPanel.tsx": 449,
   "server/lib/email-templates/registry.ts": 439,
   "app/components/editor/InspectionSettingsSheet.tsx": 437,

From f98831c148febc571b86ad5cd4780e5551ba78a8 Mon Sep 17 00:00:00 2001
From: important-new <important-new@hotmail.com>
Date: Mon, 20 Jul 2026 20:44:25 +0800
Subject: [PATCH 11/12] test(places): E2E for address autocomplete + property
 autofill wiring/degradation (#198/#200)

Real-browser Playwright coverage: the wizard renders the address combobox and
accepts free text with no suggestion dropdown when GOOGLE_PLACES_API_KEY is
unset; the editor 'Fetch property details' button relays the lookup and surfaces
the not-configured notice when ESTATED_API_KEY is unset. Verifies mount +
hydration + graceful degradation (the self-hoster default). Happy-path lookup
logic is covered by the co-located unit tests.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MkL3cCs9TmQd7zueiAnJ8s
---
 playwright.config.ts               |  4 ++
 tests/e2e/address-autofill.spec.ts | 66 ++++++++++++++++++++++++++++++
 2 files changed, 70 insertions(+)
 create mode 100644 tests/e2e/address-autofill.spec.ts

diff --git a/playwright.config.ts b/playwright.config.ts
index 8ecfecc7..54b7cdbd 100644
--- a/playwright.config.ts
+++ b/playwright.config.ts
@@ -219,5 +219,9 @@ export default defineConfig({
         // unregistered agent recipient) and a global agent account — depends
         // on `api` for the shared admin + the 8 seeded default role profiles.
         { name: 'agent-unified-link', testMatch: 'agent-unified-link.spec.ts', dependencies: ['api'] },
+        // #198/#200 — Google Places address autocomplete + property auto-fill.
+        // Verifies real-browser wiring + graceful degradation (no external keys
+        // locally). Uses the shared editor-seed admin + inspection.
+        { name: 'address-autofill', testMatch: 'address-autofill.spec.ts', dependencies: ['editor-seed'] },
     ],
 });
diff --git a/tests/e2e/address-autofill.spec.ts b/tests/e2e/address-autofill.spec.ts
new file mode 100644
index 00000000..1565aafb
--- /dev/null
+++ b/tests/e2e/address-autofill.spec.ts
@@ -0,0 +1,66 @@
+/**
+ * Google Places address autocomplete + property auto-fill (#198 / #200).
+ *
+ * Verifies the real-browser wiring and graceful degradation. The local/CI worker
+ * has no GOOGLE_PLACES_API_KEY / GOOGLE_MAPS_JS_API_KEY / ESTATED_API_KEY, so the
+ * feature runs its self-hoster default path: the address field is a usable
+ * free-text combobox (no suggestion dropdown, no map), and the editor's "Fetch
+ * property details" button surfaces a clear "not configured" notice. The
+ * happy-path lookup logic is covered by the co-located unit tests
+ * (resources/places, AddressAutocomplete, PropertyInfoForm, inspection-create).
+ *
+ * Uses the shared editor-seed admin + its editable inspection.
+ */
+import { test, expect } from '@playwright/test';
+import { readEditorSeed } from './helpers/editor-seed';
+
+let email = '';
+let password = '';
+let inspectionId = '';
+
+test.describe.serial('Address autocomplete + property auto-fill (#198/#200)', () => {
+  test.beforeAll(() => {
+    const seed = readEditorSeed();
+    test.skip(!seed, 'editor-seed handoff missing — run with the editor-seed setup project.');
+    email = seed!.email;
+    password = seed!.password;
+    inspectionId = seed!.inspectionId;
+  });
+
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/login');
+    await page.fill('input[name=email]', email);
+    await page.fill('input[name=password]', password);
+    await page.click('button[type=submit]');
+    await page.waitForURL('**/inspections');
+  });
+
+  test('wizard renders the address autocomplete combobox and accepts free text (no Places key -> no dropdown)', async ({ page }) => {
+    await page.goto('/inspections/new');
+
+    const address = page.locator('#property-address');
+    await expect(address).toBeVisible();
+    await expect(address).toHaveAttribute('role', 'combobox');
+
+    await address.fill('123 Free Form Ranch Rd, Nowhere');
+    await expect(address).toHaveValue('123 Free Form Ranch Rd, Nowhere');
+
+    // Without a Places key the BFF returns no suggestions, so no listbox opens.
+    await expect(page.getByRole('listbox')).toHaveCount(0);
+  });
+
+  test('editor "Fetch property details" degrades to a not-configured notice (no Estated key)', async ({ page }) => {
+    await page.goto(`/inspections/${inspectionId}/edit`);
+
+    // Switch the editor to the Property Info view.
+    await page.getByTestId('inspection-details-entry').click();
+    await expect(page.getByTestId('property-info-form')).toBeVisible();
+
+    const btn = page.getByRole('button', { name: /fetch property details/i });
+    await expect(btn).toBeVisible();
+    await expect(btn).toBeEnabled();
+    await btn.click();
+
+    await expect(page.getByText(/isn.t configured/i)).toBeVisible();
+  });
+});

From 7ff810994da9a62cb95984dda0a0565d2ebb4132 Mon Sep 17 00:00:00 2001
From: important-new <important-new@hotmail.com>
Date: Mon, 20 Jul 2026 21:08:04 +0800
Subject: [PATCH 12/12] test(places): fix + consolidate PropertyInfoForm tests
 under a stub router (#200)

The #200 useFetcher addition made PropertyInfoForm require a data-router context,
breaking the pre-existing property-info-form.test.tsx (which rendered it bare).
Wrap all renders in a createRoutesStub router, fold the autofill-button tests
into the same file, and drop the temporary duplicate PropertyInfoForm.test.tsx.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MkL3cCs9TmQd7zueiAnJ8s
---
 .../editor/PropertyInfoForm.test.tsx          | 62 ------------
 .../editor/property-info-form.test.tsx        | 94 +++++++++++++++----
 2 files changed, 75 insertions(+), 81 deletions(-)
 delete mode 100644 app/components/editor/PropertyInfoForm.test.tsx

diff --git a/app/components/editor/PropertyInfoForm.test.tsx b/app/components/editor/PropertyInfoForm.test.tsx
deleted file mode 100644
index b1b0bbee..00000000
--- a/app/components/editor/PropertyInfoForm.test.tsx
+++ /dev/null
@@ -1,62 +0,0 @@
-import { describe, it, expect, vi } from "vitest";
-import { render, screen, fireEvent, waitFor } from "@testing-library/react";
-import { createRoutesStub } from "react-router";
-import { PropertyInfoForm } from "./PropertyInfoForm";
-
-function mount(
-  actionResult: unknown,
-  handlers: { onSave?: (id: string, v: unknown) => void; onCommit?: (f: Record<string, unknown>) => void },
-) {
-  const inspection: Record<string, unknown> = {
-    propertyType: "single_family",
-    propertyAddress: "123 Main St, Austin, TX 78701",
-    bedrooms: "4", // already set — must NOT be overwritten
-    // yearBuilt / sqft / etc. absent = empty = fillable
-  };
-  const Stub = createRoutesStub([
-    {
-      path: "/",
-      Component: () => (
-        <PropertyInfoForm inspection={inspection} onSave={handlers.onSave} onCommit={handlers.onCommit} />
-      ),
-      action: () => actionResult,
-    },
-  ]);
-  return render(<Stub />);
-}
-
-describe("PropertyInfoForm — Fetch property details (#200)", () => {
-  it("fills only empty fields and never clobbers a value the inspector already set", async () => {
-    const onSave = vi.fn();
-    const onCommit = vi.fn();
-    mount(
-      { intent: "autofill-property-facts", facts: { yearBuilt: 1990, bedrooms: 3 }, reason: null },
-      { onSave, onCommit },
-    );
-
-    fireEvent.click(screen.getByRole("button", { name: /fetch property details/i }));
-
-    // The empty yearBuilt gets filled...
-    await waitFor(() => expect(onSave).toHaveBeenCalledWith("yearBuilt", 1990));
-    // ...but the already-set bedrooms is left alone.
-    expect(onSave).not.toHaveBeenCalledWith("bedrooms", 3);
-    // The durable commit is a full snapshot: filled yearBuilt + preserved bedrooms.
-    expect(onCommit).toHaveBeenCalledWith(expect.objectContaining({ yearBuilt: 1990, bedrooms: 4 }));
-    // A summary of what was filled is surfaced.
-    await waitFor(() => expect(screen.getByText(/filled 1 field/i)).toBeTruthy());
-  });
-
-  it("shows an 'unconfigured' message and commits nothing when the provider key is unset", async () => {
-    const onSave = vi.fn();
-    const onCommit = vi.fn();
-    mount(
-      { intent: "autofill-property-facts", facts: null, reason: "NO_API_KEY" },
-      { onSave, onCommit },
-    );
-
-    fireEvent.click(screen.getByRole("button", { name: /fetch property details/i }));
-
-    await waitFor(() => expect(screen.getByText(/isn.t configured/i)).toBeTruthy());
-    expect(onCommit).not.toHaveBeenCalled();
-  });
-});
diff --git a/app/components/editor/property-info-form.test.tsx b/app/components/editor/property-info-form.test.tsx
index ce782cfa..24caf134 100644
--- a/app/components/editor/property-info-form.test.tsx
+++ b/app/components/editor/property-info-form.test.tsx
@@ -1,12 +1,20 @@
 import { useState } from "react";
-import { render, fireEvent } from "@testing-library/react";
+import { render, fireEvent, screen, waitFor } from "@testing-library/react";
+import { createRoutesStub } from "react-router";
 import { PropertyInfoForm } from "~/components/editor/PropertyInfoForm";
 
-// PropertyInfoForm takes plain callback props (onSave/onCommit) and no
-// fetcher, so it renders directly without a router (unlike CompliancePanel).
+// PropertyInfoForm now uses useFetcher (the #200 "Fetch property details"
+// button), so it must render inside a data-router context. `renderPF` wraps any
+// element in a minimal stub router; an optional `action` powers the autofill
+// fetcher for the tests that click the button. The field/commit tests below
+// never click it, so their fetcher stays idle and no action is needed.
 // `onSave` fires optimistically on every change with the RAW value typed;
 // `onCommit` fires the durable save with a FULL coerced snapshot of every field
 // — on blur for text/number/date, on change for select/boolean.
+function renderPF(ui: React.ReactElement, action?: () => unknown) {
+  const Stub = createRoutesStub([{ path: "/", Component: () => ui, action }]);
+  return render(<Stub />);
+}
 
 function labelInput(container: HTMLElement, labelText: string): HTMLInputElement | null {
   const spans = Array.from(container.querySelectorAll("label span span")) as HTMLElement[];
@@ -33,7 +41,7 @@ function Harness({ initial, onCommit }: { initial: Record<string, unknown>; onCo
 
 describe("PropertyInfoForm field sets", () => {
   it("renders bedrooms/bathrooms plus unit + county for a residential inspection", () => {
-    const { getByText } = render(
+    const { getByText } = renderPF(
       <PropertyInfoForm inspection={{ propertyType: "residential" }} />,
     );
     expect(getByText("Bedrooms")).toBeTruthy();
@@ -45,7 +53,7 @@ describe("PropertyInfoForm field sets", () => {
   });
 
   it("omits bedrooms/bathrooms + unit but shows Building Area and County for a commercial inspection", () => {
-    const { queryByText, getByText } = render(
+    const { queryByText, getByText } = renderPF(
       <PropertyInfoForm inspection={{ propertyType: "commercial" }} />,
     );
     expect(queryByText("Bedrooms")).toBeNull();
@@ -59,7 +67,7 @@ describe("PropertyInfoForm field sets", () => {
   });
 
   it("renders lotSize (Lot Size)", () => {
-    const { getByText } = render(
+    const { getByText } = renderPF(
       <PropertyInfoForm inspection={{ propertyType: "residential" }} />,
     );
     expect(getByText("Lot Size")).toBeTruthy();
@@ -69,7 +77,7 @@ describe("PropertyInfoForm field sets", () => {
 describe("PropertyInfoForm raw-string typing (Finding 4)", () => {
   it("keeps a fractional Bathrooms value ('2.5') verbatim — onChange is the raw string, not coerced to 2", () => {
     const onSave = vi.fn();
-    const { container } = render(
+    const { container } = renderPF(
       <PropertyInfoForm inspection={{ propertyType: "residential" }} onSave={onSave} />,
     );
     const input = labelInput(container, "Bathrooms")!;
@@ -81,7 +89,7 @@ describe("PropertyInfoForm raw-string typing (Finding 4)", () => {
 
   it("does not clear the input on the transient mid-decimal '2.' keystroke", () => {
     const onCommit = vi.fn();
-    const { container } = render(<Harness initial={{ propertyType: "residential" }} onCommit={onCommit} />);
+    const { container } = renderPF(<Harness initial={{ propertyType: "residential" }} onCommit={onCommit} />);
     const input = labelInput(container, "Bathrooms")!;
     fireEvent.change(input, { target: { value: "2." } });
     // Controlled value retains "2." — a coerce here would snap it to "2" or "".
@@ -94,7 +102,7 @@ describe("PropertyInfoForm raw-string typing (Finding 4)", () => {
 describe("PropertyInfoForm full-snapshot commit (Finding 1)", () => {
   it("commits the WHOLE facts object on blur with the changed field coerced and empty fields → null", () => {
     const onCommit = vi.fn();
-    const { container } = render(<Harness initial={{ propertyType: "residential" }} onCommit={onCommit} />);
+    const { container } = renderPF(<Harness initial={{ propertyType: "residential" }} onCommit={onCommit} />);
     const input = labelInput(container, "Year Built")!;
     fireEvent.change(input, { target: { value: "1990" } });
     // onChange must NOT commit (no keystroke persistence).
@@ -115,7 +123,7 @@ describe("PropertyInfoForm full-snapshot commit (Finding 1)", () => {
 
   it("commits a fractional bathrooms value coerced to a Number within the full object", () => {
     const onCommit = vi.fn();
-    const { container } = render(<Harness initial={{ propertyType: "residential" }} onCommit={onCommit} />);
+    const { container } = renderPF(<Harness initial={{ propertyType: "residential" }} onCommit={onCommit} />);
     const input = labelInput(container, "Bathrooms")!;
     fireEvent.change(input, { target: { value: "2.5" } });
     fireEvent.blur(input);
@@ -125,7 +133,7 @@ describe("PropertyInfoForm full-snapshot commit (Finding 1)", () => {
 
   it("preserves already-entered sibling fields when a second field commits (superset PATCH)", () => {
     const onCommit = vi.fn();
-    const { container } = render(<Harness initial={{ propertyType: "residential" }} onCommit={onCommit} />);
+    const { container } = renderPF(<Harness initial={{ propertyType: "residential" }} onCommit={onCommit} />);
     const year = labelInput(container, "Year Built")!;
     fireEvent.change(year, { target: { value: "1990" } });
     fireEvent.blur(year);
@@ -140,7 +148,7 @@ describe("PropertyInfoForm full-snapshot commit (Finding 1)", () => {
 
   it("commits null when a number field is cleared to empty on blur", () => {
     const onCommit = vi.fn();
-    const { container } = render(<Harness initial={{ propertyType: "residential", yearBuilt: 1990 }} onCommit={onCommit} />);
+    const { container } = renderPF(<Harness initial={{ propertyType: "residential", yearBuilt: 1990 }} onCommit={onCommit} />);
     const input = labelInput(container, "Year Built")!;
     fireEvent.change(input, { target: { value: "" } });
     fireEvent.blur(input);
@@ -150,7 +158,7 @@ describe("PropertyInfoForm full-snapshot commit (Finding 1)", () => {
 
   it("commits null when a text field (lotSize) is blurred empty", () => {
     const onCommit = vi.fn();
-    const { container } = render(<Harness initial={{ propertyType: "residential", lotSize: "old" }} onCommit={onCommit} />);
+    const { container } = renderPF(<Harness initial={{ propertyType: "residential", lotSize: "old" }} onCommit={onCommit} />);
     const input = labelInput(container, "Lot Size")!;
     expect(input).toBeTruthy();
     fireEvent.change(input, { target: { value: "" } });
@@ -161,7 +169,7 @@ describe("PropertyInfoForm full-snapshot commit (Finding 1)", () => {
 
   it("commits a text field (lotSize) value on blur", () => {
     const onCommit = vi.fn();
-    const { container } = render(<Harness initial={{ propertyType: "residential" }} onCommit={onCommit} />);
+    const { container } = renderPF(<Harness initial={{ propertyType: "residential" }} onCommit={onCommit} />);
     const input = labelInput(container, "Lot Size")!;
     fireEvent.change(input, { target: { value: "0.25 acres" } });
     fireEvent.blur(input);
@@ -171,7 +179,7 @@ describe("PropertyInfoForm full-snapshot commit (Finding 1)", () => {
 
   it("still fires onSave optimistically on change with the raw string", () => {
     const onSave = vi.fn();
-    const { container } = render(
+    const { container } = renderPF(
       <PropertyInfoForm inspection={{ propertyType: "residential" }} onSave={onSave} />,
     );
     const input = labelInput(container, "Year Built")!;
@@ -193,7 +201,7 @@ describe("PropertyInfoForm commercial preset metadata split", () => {
   ];
 
   it("renders subtype-preset fields passed via templateFields", () => {
-    const { getByText } = render(
+    const { getByText } = renderPF(
       <PropertyInfoForm inspection={{ propertyType: "commercial" }} templateFields={officePreset} />,
     );
     expect(getByText("Net rentable area")).toBeTruthy();
@@ -202,7 +210,7 @@ describe("PropertyInfoForm commercial preset metadata split", () => {
 
   it("splits non-dedicated preset fields into a metadata envelope on commit", () => {
     const onCommit = vi.fn();
-    const { container } = render(
+    const { container } = renderPF(
       <PropertyInfoForm
         inspection={{ propertyType: "commercial", yearBuilt: 1998, nra: 42000 }}
         templateFields={officePreset}
@@ -221,7 +229,7 @@ describe("PropertyInfoForm commercial preset metadata split", () => {
       { id: "yearBuilt", label: "Year built", type: "number" as const, group: "Identity" },
       { id: "sqft", label: "Building area", type: "number" as const, group: "Physical" },
     ];
-    const { container } = render(
+    const { container } = renderPF(
       <PropertyInfoForm
         inspection={{ propertyType: "commercial", yearBuilt: 2001 }}
         templateFields={dedicatedOnly}
@@ -238,7 +246,7 @@ describe("PropertyInfoForm commercial preset metadata split", () => {
 describe("PropertyInfoForm select commit", () => {
   it("commits foundationType on change (discrete select) with the full facts object", () => {
     const onCommit = vi.fn();
-    const { container } = render(
+    const { container } = renderPF(
       <PropertyInfoForm inspection={{ propertyType: "residential" }} onCommit={onCommit} />,
     );
     const select = container.querySelector("select") as HTMLSelectElement;
@@ -256,3 +264,51 @@ describe("PropertyInfoForm select commit", () => {
     });
   });
 });
+
+// #200 — "Fetch property details" autofill button. Relays the address to the
+// editor BFF action; fills ONLY empty fields (never clobbers manual entry) and
+// commits the merged snapshot; degrades with a clear message when unconfigured.
+describe("PropertyInfoForm — Fetch property details (#200)", () => {
+  function mountAutofill(
+    actionResult: unknown,
+    handlers: { onSave?: (id: string, v: unknown) => void; onCommit?: (f: Record<string, unknown>) => void },
+  ) {
+    const inspection: Record<string, unknown> = {
+      propertyType: "single_family",
+      propertyAddress: "123 Main St, Austin, TX 78701",
+      bedrooms: "4", // already set — must NOT be overwritten
+      // yearBuilt / sqft / etc. absent = empty = fillable
+    };
+    return renderPF(
+      <PropertyInfoForm inspection={inspection} onSave={handlers.onSave} onCommit={handlers.onCommit} />,
+      () => actionResult,
+    );
+  }
+
+  it("fills only empty fields and never clobbers a value the inspector already set", async () => {
+    const onSave = vi.fn();
+    const onCommit = vi.fn();
+    mountAutofill(
+      { intent: "autofill-property-facts", facts: { yearBuilt: 1990, bedrooms: 3 }, reason: null },
+      { onSave, onCommit },
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: /fetch property details/i }));
+
+    await waitFor(() => expect(onSave).toHaveBeenCalledWith("yearBuilt", 1990));
+    expect(onSave).not.toHaveBeenCalledWith("bedrooms", 3);
+    expect(onCommit).toHaveBeenCalledWith(expect.objectContaining({ yearBuilt: 1990, bedrooms: 4 }));
+    await waitFor(() => expect(screen.getByText(/filled 1 field/i)).toBeTruthy());
+  });
+
+  it("shows an 'unconfigured' message and commits nothing when the provider key is unset", async () => {
+    const onSave = vi.fn();
+    const onCommit = vi.fn();
+    mountAutofill({ intent: "autofill-property-facts", facts: null, reason: "NO_API_KEY" }, { onSave, onCommit });
+
+    fireEvent.click(screen.getByRole("button", { name: /fetch property details/i }));
+
+    await waitFor(() => expect(screen.getByText(/isn.t configured/i)).toBeTruthy());
+    expect(onCommit).not.toHaveBeenCalled();
+  });
+});