Add brewery discovery & detail pages with location-based search (#253)

2026-10-15 10:04:44 +00:00 · 2026-08-29 00:44:33 -04:00
parent 92a30b11db
commit a580314583
90 changed files with 3874 additions and 187 deletions
--- a/web/frontend/app/features/breweries/BREWERY_HANDOFF.md
+++ b/web/frontend/app/features/breweries/BREWERY_HANDOFF.md
@@ -0,0 +1,101 @@
+# Brewery feature: data requirements
+
+Covers `/breweries` (`routes/breweries.tsx`) and `/breweries/:id`
+(`routes/brewery-detail.tsx`). Both routes are built and live. This document
+lists what's real vs. filler, and what backend work closes each gap.
+
+## Status legend
+
+- ✅ **Available**: real data, wired up.
+- ⚠️ **Partial**: endpoint exists but is missing a field the design needs.
+- ❌ **Missing**: no backend support; page shows filler or local-only state.
+
+## Breweries index (`/breweries`)
+
+### Featured brewery
+
+| Field                                | Status | Source                            | Gap                                                                                                    |
+| ------------------------------------ | ------ | --------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| Name, description, address, location | ✅     | `GET /api/brewery` (`BreweryDto`) |                                                                                                        |
+| "Editorially featured" selection     | ❌     | none (defaults to newest brewery) | No `IsFeatured` flag or rotation concept. Needs a field + admin toggle, or a scheduled rotation query. |
+| Founded year                         | ❌     | none                              | No founding-date column (distinct from `CreatedAt`, which is post-creation time).                      |
+| Beers listed count                   | ❌     | none                              | Blocked on the Beers gap below.                                                                        |
+| House style                          | ❌     | none                              | No style/tag field, and no aggregate over a brewery's beers' styles.                                   |
+
+### Breweries near you
+
+| Field                                                   | Status | Source                                                                                  | Gap                                                                                                            |
+| ------------------------------------------------------- | ------ | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| Nearby breweries by coordinates + radius                | ✅     | `GET /api/brewery/locations/nearby?latitude&longitude&rangeInMetres`                    |                                                                                                                |
+| Distance from search center                             | ✅     | `SimplifiedBreweryDto.DistanceMetres`, computed server-side via `geography::STDistance` |                                                                                                                |
+| One-line note per brewery                               | ❌     | none                                                                                    | `SimplifiedBreweryDto` has no description-like field. Needs a tagline field, or a truncated `Description`.     |
+| User's current location                                 | ✅     | Browser Geolocation API                                                                 |                                                                                                                |
+| Fallback region (before permission granted / on denial) | ⚠️     | Falls back to the featured brewery's coordinates                                        | Works, but isn't a deliberate default. A real deployment wants a configured default (e.g. per-tenant HQ city). |
+| Manual location entry ("Change location")               | ❌     | Re-requests browser geolocation only                                                    | No geocoding/place-search endpoint to resolve a typed address to coordinates.                                  |
+| Search radius                                           | ✅     | Client-side state (10–150 km slider), passed as `rangeInMetres`                         |                                                                                                                |
+
+### Recently added
+
+✅ Fully real: `GET /api/brewery`, already sorted newest-first. No gaps.
+
+### Directory CTA
+
+| Field                                   | Status | Source                | Gap                                                                                                                            |
+| --------------------------------------- | ------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| Total partner brewery count             | ❌     | Filler number (`128`) | No count endpoint. Needs `GET /api/brewery/count` rather than fetching the full list to measure it.                            |
+| Filter by country / region / beer style | ❌     | Copy only             | Describes the future directory page's capability, not a data need of this page. Implies the directory will need filter params. |
+
+## Brewery detail (`/breweries/:id`)
+
+### Header, location, dates
+
+| Field                                   | Status | Source                                                                               |
+| --------------------------------------- | ------ | ------------------------------------------------------------------------------------ |
+| Name, description, address, coordinates | ✅     | `GET /api/brewery/{id}` (`BreweryDto`)                                               |
+| Created / updated dates                 | ✅     | `BreweryDto`                                                                         |
+| Founded year, brewery type, website     | ❌     | `FILLER_BREWERY_META`: `BreweryPost` has no `FoundedAt`, `Type`, or `Website` column |
+
+### Beers, style breakdown
+
+| Field                        | Status | Source                                  | Gap                                                                           |
+| ---------------------------- | ------ | --------------------------------------- | ----------------------------------------------------------------------------- |
+| Beers belonging to a brewery | ❌     | `FILLER_BEERS`                          | See "Beers feature is empty" below.                                           |
+| Beer style breakdown         | ❌     | Derived client-side from `FILLER_BEERS` | Blocked on the same gap; otherwise an aggregate query over a brewery's beers. |
+
+### Likes, ratings, comments
+
+| Field                       | Status | Source                         | Gap                                                                                                                                                                             |
+| --------------------------- | ------ | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Brewery like/unlike + count | ❌     | Local component state          | No like concept in the schema. Needs a join table (composite `BreweryPostId`/`UserAccountId`, like `UserFollow`).                                                               |
+| Your rating (1–5) + average | ❌     | Local component state          | No brewery rating table/endpoint.                                                                                                                                               |
+| Comments (list + post)      | ❌     | `FILLER_COMMENTS`, local state | No `BreweryPostComment` table. `BeerPostComment` is a close precedent (comment + 1–5 `CHECK`-constrained rating + FKs) but is unused and targets `BeerPost`, not `BreweryPost`. |
+| Per-comment like toggle     | ❌     | Local component state          | No "like a comment" concept; needs a join table alongside a new `BreweryPostComment` table.                                                                                     |
+
+## Cross-cutting: the Beers feature is empty
+
+`Features.Beers` (backend) has a `.csproj` and nothing else: no query
+handlers, no controller, no DTOs. `BeerPost` exists as a domain entity (with
+`BrewedById` linking to `BreweryPost`) but nothing exposes it over the API.
+This blocks:
+
+- "Beers listed" count and "House style" on the index page's featured card.
+- The beer list and style breakdown on the detail page.
+- Any future beer-style filter on the directory.
+
+## Summary of backend work
+
+1. `IsFeatured` flag (or rotation query) on `BreweryPost`.
+2. `FoundedAt`/`FoundedYear`, `Type`, `Website` columns on `BreweryPost` (+ `BreweryDto`).
+3. A tagline/note field on `BreweryPost`, surfaced through `SimplifiedBreweryDto`.
+4. Stand up `Features.Beers`: a query + controller route for a brewery's beers, following the `Features.Breweries` vertical-slice pattern. Unblocks beer counts, style breakdown, and style filters.
+5. `GET /api/brewery/count`.
+6. A geocoding/place-search endpoint for manual location entry.
+7. `BreweryPostLike` join table + command/query/controller (toggle, read count/liked-by-current-user); public GET, JWT-required toggle, mirroring `BreweryController`'s `[AllowAnonymous]`-on-reads pattern.
+8. `BreweryPostRating` table (1–5, `CHECK`-constrained like `BeerPostComment.Rating`) + aggregate query for average/count.
+9. `BreweryPostComment` table (mirroring `BeerPostComment.sql`, FK'd to `BreweryPost`) + `BreweryPostCommentLike` join table, plus command/query/controller for both.
+10. (Product decision, not code) a configured default region to fall back to instead of the featured brewery's coordinates.
+
+Once these land, swap `FILLER_BEERS` / `FILLER_COMMENTS` / `FILLER_BREWERY_META`
+(`utils/filler-brewery-detail.ts`) and the local `useState` in
+`brewery-detail.tsx` for loader data and `authorizedRequest`-based mutations
+(see `auth.server.ts`).
--- a/web/frontend/app/features/breweries/breweries.server.ts
+++ b/web/frontend/app/features/breweries/breweries.server.ts
@@ -7,13 +7,24 @@ interface ApiResponse<T> {
    payload: T;
 }

+export interface BreweryCoordinates {
+    latitude: number;
+    longitude: number;
+}
+
 export interface BreweryLocation {
    breweryPostLocationId: string;
    breweryPostId: string;
    cityId: string;
+    cityName: string;
+    stateProvinceName: string;
+    stateProvinceCode: string;
+    countryName: string;
+    countryCode: string;
    addressLine1: string;
    addressLine2: string | null;
    postalCode: string;
+    coordinates: BreweryCoordinates | null;
 }

 export interface Brewery {
@@ -26,6 +37,13 @@ export interface Brewery {
    location: BreweryLocation | null;
 }

+export interface SimplifiedBrewery {
+    breweryPostId: string;
+    breweryName: string;
+    location: BreweryLocation | null;
+    distanceMetres: number | null;
+}
+
 const fetchApi = async (path: string): Promise<Response> => {
    try {
        return await fetch(`${API_BASE_URL}${path}`);
@@ -55,6 +73,44 @@ export const getBreweries = async (limit?: number, offset?: number): Promise<Bre
    return body.payload;
 };

+export const getBreweryLocations = async (): Promise<SimplifiedBrewery[]> => {
+    const res = await fetchApi('/api/brewery/locations');
+
+    if (!res.ok) {
+        throw data(`Failed to load brewery locations (${res.status}).`, {
+            status: res.status,
+            statusText: res.statusText,
+        });
+    }
+
+    const body: ApiResponse<SimplifiedBrewery[]> = await res.json();
+    return body.payload;
+};
+
+export const getBreweryLocationsNearby = async (
+    latitude: number,
+    longitude: number,
+    rangeInMetres: number,
+): Promise<SimplifiedBrewery[]> => {
+    const params = new URLSearchParams({
+        latitude: String(latitude),
+        longitude: String(longitude),
+        rangeInMetres: String(rangeInMetres),
+    });
+
+    const res = await fetchApi(`/api/brewery/locations/nearby?${params}`);
+
+    if (!res.ok) {
+        throw data(`Failed to load nearby breweries (${res.status}).`, {
+            status: res.status,
+            statusText: res.statusText,
+        });
+    }
+
+    const body: ApiResponse<SimplifiedBrewery[]> = await res.json();
+    return body.payload;
+};
+
 export const getBreweryById = async (id: string): Promise<Brewery | null> => {
    const res = await fetchApi(`/api/brewery/${encodeURIComponent(id)}`);

--- a/web/frontend/app/features/breweries/components/BreweryCard.tsx
+++ b/web/frontend/app/features/breweries/components/BreweryCard.tsx
@@ -1,26 +0,0 @@
-import { Link } from 'react-router';
-import type { Brewery } from '../breweries.server';
-
-interface BreweryCardProps {
-    brewery: Brewery;
-}
-
-const BreweryCard = ({ brewery }: BreweryCardProps) => (
-    <Link
-        to={`/breweries/${brewery.breweryPostId}`}
-        className="card bg-base-100 shadow hover:shadow-lg transition-shadow"
-    >
-        <div className="card-body">
-            <h2 className="card-title">{brewery.breweryName}</h2>
-            <p className="text-base-content/70 line-clamp-3">{brewery.description}</p>
-            {brewery.location && (
-                <p className="text-sm text-base-content/50 mt-2">
-                    {brewery.location.addressLine1}
-                    {brewery.location.addressLine2 ? `, ${brewery.location.addressLine2}` : ''}
-                </p>
-            )}
-        </div>
-    </Link>
-);
-
-export default BreweryCard;
--- a/web/frontend/app/features/breweries/components/detail/BeerListCard.stories.tsx
+++ b/web/frontend/app/features/breweries/components/detail/BeerListCard.stories.tsx
@@ -0,0 +1,47 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, within } from 'storybook/test';
+import BeerListCard from './BeerListCard';
+import { FILLER_BEERS } from '../../utils/filler-brewery-detail';
+
+const beerListCardDescription = `A brewery's beer list on the detail page: name/description, style badge, ABV, and star rating per row. Currently filler pending a beers-by-brewery endpoint — see BREWERY_HANDOFF.md.`;
+
+const meta = {
+    title: 'Breweries/BeerListCard',
+    component: BeerListCard,
+    tags: ['autodocs'],
+    args: {
+        beers: FILLER_BEERS,
+    },
+    parameters: {
+        layout: 'padded',
+        docs: {
+            description: {
+                component: beerListCardDescription,
+            },
+        },
+    },
+} satisfies Meta<typeof BeerListCard>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await expect(canvas.getByRole('heading', { name: 'Beers (9)' })).toBeInTheDocument();
+        await expect(canvas.getByRole('link', { name: /view all beers/i })).toHaveAttribute(
+            'href',
+            '/beers',
+        );
+        await expect(canvas.getByText('Switchyard IPA')).toBeInTheDocument();
+        await expect(canvas.getByText('6.8% ABV')).toBeInTheDocument();
+    },
+};
+
+export const SingleBeer: Story = {
+    args: { beers: FILLER_BEERS.slice(0, 1) },
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await expect(canvas.getByRole('heading', { name: 'Beers (1)' })).toBeInTheDocument();
+    },
+};
--- a/web/frontend/app/features/breweries/components/detail/BeerListCard.tsx
+++ b/web/frontend/app/features/breweries/components/detail/BeerListCard.tsx
@@ -0,0 +1,42 @@
+import { Link } from 'react-router';
+import StarRating from '../shared/StarRating';
+import type { FillerBeer } from '../../utils/filler-brewery-detail';
+
+interface BeerListCardProps {
+    beers: FillerBeer[];
+}
+
+const BeerListCard = ({ beers }: BeerListCardProps) => (
+    <div className="card bg-base-100 shadow">
+        <div className="card-body gap-3 p-6">
+            <div className="flex items-baseline justify-between gap-4">
+                <h3 className="text-xl m-0">Beers ({beers.length})</h3>
+                <Link to="/beers" className="link link-primary text-sm">
+                    View all beers
+                </Link>
+            </div>
+            <div className="flex flex-col">
+                {beers.map((beer) => (
+                    <div
+                        key={beer.id}
+                        className="grid grid-cols-[1fr_auto_auto_auto] items-center gap-3 py-2.5 border-t border-base-content/10 first:border-t-0"
+                    >
+                        <div className="flex flex-col gap-0.5 min-w-0">
+                            <span className="font-bold text-sm">{beer.name}</span>
+                            <span className="text-xs text-base-content/60">{beer.description}</span>
+                        </div>
+                        <span className="badge badge-ghost bg-base-300 text-xs font-semibold whitespace-nowrap">
+                            {beer.style}
+                        </span>
+                        <span className="text-xs text-base-content/60 tabular-nums whitespace-nowrap">
+                            {beer.abv.toFixed(1)}% ABV
+                        </span>
+                        <StarRating value={beer.rating} size="xs" />
+                    </div>
+                ))}
+            </div>
+        </div>
+    </div>
+);
+
+export default BeerListCard;
--- a/web/frontend/app/features/breweries/components/detail/BeerStyleBreakdownCard.stories.tsx
+++ b/web/frontend/app/features/breweries/components/detail/BeerStyleBreakdownCard.stories.tsx
@@ -0,0 +1,46 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, within } from 'storybook/test';
+import BeerStyleBreakdownCard from './BeerStyleBreakdownCard';
+import { FILLER_BEERS } from '../../utils/filler-brewery-detail';
+
+const beerStyleBreakdownCardDescription = `Sidebar "Beer styles" card: per-style progress bars, sorted by count descending, derived client-side from a brewery's beer list.`;
+
+const meta = {
+    title: 'Breweries/BeerStyleBreakdownCard',
+    component: BeerStyleBreakdownCard,
+    tags: ['autodocs'],
+    args: {
+        beers: FILLER_BEERS,
+    },
+    parameters: {
+        layout: 'padded',
+        docs: {
+            description: {
+                component: beerStyleBreakdownCardDescription,
+            },
+        },
+    },
+} satisfies Meta<typeof BeerStyleBreakdownCard>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await expect(canvas.getByText('Beer styles')).toBeInTheDocument();
+        await expect(canvas.getByText('IPA')).toBeInTheDocument();
+        await expect(canvas.getByText('Sour')).toBeInTheDocument();
+    },
+};
+
+export const SingleStyle: Story = {
+    args: {
+        beers: FILLER_BEERS.filter((beer) => beer.style === 'IPA'),
+    },
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await expect(canvas.getByText('IPA')).toBeInTheDocument();
+        await expect(canvas.queryByText('Sour')).not.toBeInTheDocument();
+    },
+};
--- a/web/frontend/app/features/breweries/components/detail/BeerStyleBreakdownCard.tsx
+++ b/web/frontend/app/features/breweries/components/detail/BeerStyleBreakdownCard.tsx
@@ -0,0 +1,33 @@
+import SidebarCard from '../shared/SidebarCard';
+import type { FillerBeer } from '../../utils/filler-brewery-detail';
+
+interface BeerStyleBreakdownCardProps {
+    beers: FillerBeer[];
+}
+
+const BeerStyleBreakdownCard = ({ beers }: BeerStyleBreakdownCardProps) => {
+    const counts = new Map<string, number>();
+    beers.forEach((beer) => counts.set(beer.style, (counts.get(beer.style) ?? 0) + 1));
+    const maxCount = Math.max(...counts.values());
+    const styles = [...counts.entries()].sort((a, b) => b[1] - a[1]);
+
+    return (
+        <SidebarCard title="Beer styles">
+            {styles.map(([style, count]) => (
+                <div key={style} className="flex flex-col gap-1">
+                    <div className="flex items-baseline justify-between gap-2">
+                        <span className="text-sm font-semibold">{style}</span>
+                        <span className="text-xs text-base-content/60 tabular-nums">{count}</span>
+                    </div>
+                    <progress
+                        className="progress progress-primary h-1.5"
+                        value={count}
+                        max={maxCount}
+                    />
+                </div>
+            ))}
+        </SidebarCard>
+    );
+};
+
+export default BeerStyleBreakdownCard;
--- a/web/frontend/app/features/breweries/components/detail/BreweryDetailsCard.stories.tsx
+++ b/web/frontend/app/features/breweries/components/detail/BreweryDetailsCard.stories.tsx
@@ -0,0 +1,37 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, within } from 'storybook/test';
+import BreweryDetailsCard from './BreweryDetailsCard';
+
+const breweryDetailsCardDescription = `Sidebar "Details" card on the brewery detail page: founded year, brewery type, and beer count. Founded year and type are currently filler pending backend support — see BREWERY_HANDOFF.md.`;
+
+const meta = {
+    title: 'Breweries/BreweryDetailsCard',
+    component: BreweryDetailsCard,
+    tags: ['autodocs'],
+    args: {
+        foundedYear: 2014,
+        type: 'Microbrewery',
+        beerCount: 9,
+    },
+    parameters: {
+        layout: 'padded',
+        docs: {
+            description: {
+                component: breweryDetailsCardDescription,
+            },
+        },
+    },
+} satisfies Meta<typeof BreweryDetailsCard>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await expect(canvas.getByText('Founded')).toBeInTheDocument();
+        await expect(canvas.getByText('2014')).toBeInTheDocument();
+        await expect(canvas.getByText('Microbrewery')).toBeInTheDocument();
+        await expect(canvas.getByText('9')).toBeInTheDocument();
+    },
+};
--- a/web/frontend/app/features/breweries/components/detail/BreweryDetailsCard.tsx
+++ b/web/frontend/app/features/breweries/components/detail/BreweryDetailsCard.tsx
@@ -0,0 +1,24 @@
+import SidebarCard from '../shared/SidebarCard';
+
+interface BreweryDetailsCardProps {
+    foundedYear: number;
+    type: string;
+    beerCount: number;
+}
+
+const DetailRow = ({ label, value }: { label: string; value: string | number }) => (
+    <div className="flex items-center justify-between gap-2 text-sm">
+        <span className="text-base-content/60">{label}</span>
+        <span className="font-semibold">{value}</span>
+    </div>
+);
+
+const BreweryDetailsCard = ({ foundedYear, type, beerCount }: BreweryDetailsCardProps) => (
+    <SidebarCard title="Details">
+        <DetailRow label="Founded" value={foundedYear} />
+        <DetailRow label="Type" value={type} />
+        <DetailRow label="Beers listed" value={beerCount} />
+    </SidebarCard>
+);
+
+export default BreweryDetailsCard;
--- a/web/frontend/app/features/breweries/components/detail/BreweryHeaderCard.stories.tsx
+++ b/web/frontend/app/features/breweries/components/detail/BreweryHeaderCard.stories.tsx
@@ -0,0 +1,77 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, fn, userEvent, within } from 'storybook/test';
+import BreweryHeaderCard from './BreweryHeaderCard';
+import type { Brewery, BreweryLocation } from '../../breweries.server';
+
+const breweryHeaderCardDescription = `Top card on the brewery detail page: eyebrow + "Est." badge, name, address, like button, average rating, and description. Founded year and average rating are currently filler pending backend support — see BREWERY_HANDOFF.md.`;
+
+const portlandLocation: BreweryLocation = {
+    breweryPostLocationId: 'loc-1',
+    breweryPostId: 'brewery-1',
+    cityId: 'city-1',
+    cityName: 'Portland',
+    stateProvinceName: 'Oregon',
+    stateProvinceCode: 'OR',
+    countryName: 'United States',
+    countryCode: 'US',
+    addressLine1: '123 Hop Street',
+    addressLine2: null,
+    postalCode: '97201',
+    coordinates: { latitude: 45.5152, longitude: -122.6784 },
+};
+
+const brewery: Brewery = {
+    breweryPostId: 'brewery-1',
+    postedById: 'user-1',
+    breweryName: 'Cascade Hollow Brewing',
+    description:
+        'A small-batch brewery known for hazy IPAs and barrel-aged sours, tucked into an old warehouse district.',
+    createdAt: '2024-03-01T12:00:00.000Z',
+    updatedAt: null,
+    location: portlandLocation,
+};
+
+const meta = {
+    title: 'Breweries/BreweryHeaderCard',
+    component: BreweryHeaderCard,
+    tags: ['autodocs'],
+    args: {
+        brewery,
+        foundedYear: 2014,
+        avgRating: 4,
+        ratingsCount: 76,
+        onToggleLike: fn(),
+    },
+    parameters: {
+        layout: 'padded',
+        docs: {
+            description: {
+                component: breweryHeaderCardDescription,
+            },
+        },
+    },
+} satisfies Meta<typeof BreweryHeaderCard>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Unliked: Story = {
+    args: { liked: false, likeCount: 127 },
+    play: async ({ args, canvasElement }) => {
+        const canvas = within(canvasElement);
+        await expect(
+            canvas.getByRole('heading', { name: 'Cascade Hollow Brewing', level: 1 }),
+        ).toBeInTheDocument();
+        const likeButton = canvas.getByRole('button', { name: /like · 127/i });
+        await userEvent.click(likeButton);
+        await expect(args.onToggleLike).toHaveBeenCalledOnce();
+    },
+};
+
+export const Liked: Story = {
+    args: { liked: true, likeCount: 128 },
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await expect(canvas.getByRole('button', { name: /liked · 128/i })).toBeInTheDocument();
+    },
+};
--- a/web/frontend/app/features/breweries/components/detail/BreweryHeaderCard.tsx
+++ b/web/frontend/app/features/breweries/components/detail/BreweryHeaderCard.tsx
@@ -0,0 +1,70 @@
+import { Heart, HeartSolid, MapPin } from 'iconoir-react';
+import StarRating from '../shared/StarRating';
+import { formatBreweryAddress } from '../../utils/format-address';
+import type { Brewery } from '../../breweries.server';
+
+interface BreweryHeaderCardProps {
+    brewery: Brewery;
+    foundedYear: number;
+    liked: boolean;
+    likeCount: number;
+    avgRating: number;
+    ratingsCount: number;
+    onToggleLike: () => void;
+}
+
+const BreweryHeaderCard = ({
+    brewery,
+    foundedYear,
+    liked,
+    likeCount,
+    avgRating,
+    ratingsCount,
+    onToggleLike,
+}: BreweryHeaderCardProps) => (
+    <div className="card bg-base-100 shadow">
+        <div className="card-body gap-4 p-7">
+            <div className="flex flex-col gap-1">
+                <div className="flex items-center gap-2 flex-wrap">
+                    <span className="text-xs font-bold uppercase tracking-widest text-base-content/50">
+                        Brewery
+                    </span>
+                    <span className="badge bg-[var(--color-highlight)] text-[var(--color-highlight-content)]">
+                        Est. {foundedYear}
+                    </span>
+                </div>
+                <h1 className="text-4xl leading-tight m-0">{brewery.breweryName}</h1>
+                {brewery.location && (
+                    <p className="text-sm text-base-content/60 flex items-center gap-1 m-0">
+                        <MapPin className="size-4" aria-hidden="true" />
+                        {formatBreweryAddress(brewery.location)}
+                    </p>
+                )}
+            </div>
+            <div className="flex items-center gap-3 flex-wrap">
+                <button
+                    type="button"
+                    onClick={onToggleLike}
+                    className={`btn btn-sm ${liked ? 'btn-primary' : 'btn-outline'}`}
+                >
+                    {liked ? (
+                        <HeartSolid className="size-4" aria-hidden="true" />
+                    ) : (
+                        <Heart className="size-4" aria-hidden="true" />
+                    )}
+                    {liked ? 'Liked' : 'Like'} · {likeCount}
+                </button>
+                <div className="flex items-baseline gap-1.5">
+                    <StarRating value={avgRating} size="sm" />
+                    <span className="font-bold">{avgRating.toFixed(1)}</span>
+                    <span className="text-sm text-base-content/60">({ratingsCount} ratings)</span>
+                </div>
+            </div>
+            <p className="text-base-content/70 leading-relaxed text-pretty m-0">
+                {brewery.description}
+            </p>
+        </div>
+    </div>
+);
+
+export default BreweryHeaderCard;
--- a/web/frontend/app/features/breweries/components/detail/BreweryLocationMap.stories.tsx
+++ b/web/frontend/app/features/breweries/components/detail/BreweryLocationMap.stories.tsx
@@ -0,0 +1,28 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import BreweryLocationMap from './BreweryLocationMap';
+
+const breweryLocationMapDescription = `Small fixed single-pin Leaflet map used by the brewery detail page's Location sidebar card. Smoke-render only - this hits the real OpenStreetMap tile server in the browser test run.`;
+
+const meta = {
+    title: 'Breweries/BreweryLocationMap',
+    component: BreweryLocationMap,
+    parameters: {
+        layout: 'padded',
+        docs: {
+            description: {
+                component: breweryLocationMapDescription,
+            },
+        },
+    },
+} satisfies Meta<typeof BreweryLocationMap>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+    args: {
+        latitude: 45.5152,
+        longitude: -122.6784,
+        label: 'Cascade Hollow Brewing — 123 Hop Street',
+    },
+};
--- a/web/frontend/app/features/breweries/components/detail/BreweryLocationMap.tsx
+++ b/web/frontend/app/features/breweries/components/detail/BreweryLocationMap.tsx
@@ -0,0 +1,41 @@
+import { MapContainer, TileLayer, Marker, Popup } from 'react-leaflet';
+import L, { type LatLngTuple } from 'leaflet';
+import iconRetinaUrl from 'leaflet/dist/images/marker-icon-2x.png';
+import iconUrl from 'leaflet/dist/images/marker-icon.png';
+import shadowUrl from 'leaflet/dist/images/marker-shadow.png';
+import 'leaflet/dist/leaflet.css';
+
+delete (L.Icon.Default.prototype as unknown as { _getIconUrl?: unknown })._getIconUrl;
+L.Icon.Default.mergeOptions({ iconRetinaUrl, iconUrl, shadowUrl });
+
+interface BreweryLocationMapProps {
+    latitude: number;
+    longitude: number;
+    label: string;
+}
+
+const ZOOM = 15;
+
+const BreweryLocationMap = ({ latitude, longitude, label }: BreweryLocationMapProps) => {
+    const position: LatLngTuple = [latitude, longitude];
+
+    return (
+        <MapContainer
+            center={position}
+            zoom={ZOOM}
+            scrollWheelZoom={false}
+            className="h-45 w-full rounded-field relative z-0"
+        >
+            <TileLayer
+                attribution='&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
+                url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"
+                noWrap
+            />
+            <Marker position={position}>
+                <Popup>{label}</Popup>
+            </Marker>
+        </MapContainer>
+    );
+};
+
+export default BreweryLocationMap;
--- a/web/frontend/app/features/breweries/components/detail/CommunityStatsCard.stories.tsx
+++ b/web/frontend/app/features/breweries/components/detail/CommunityStatsCard.stories.tsx
@@ -0,0 +1,37 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, within } from 'storybook/test';
+import CommunityStatsCard from './CommunityStatsCard';
+
+const communityStatsCardDescription = `Sidebar "Community" card: live likes/ratings/comments counts, kept in sync with the header, your-rating, and comments cards on the brewery detail page.`;
+
+const meta = {
+    title: 'Breweries/CommunityStatsCard',
+    component: CommunityStatsCard,
+    tags: ['autodocs'],
+    args: {
+        likeCount: 127,
+        ratingsCount: 76,
+        commentCount: 3,
+    },
+    parameters: {
+        layout: 'padded',
+        docs: {
+            description: {
+                component: communityStatsCardDescription,
+            },
+        },
+    },
+} satisfies Meta<typeof CommunityStatsCard>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await expect(canvas.getByText('Likes')).toBeInTheDocument();
+        await expect(canvas.getByText('127')).toBeInTheDocument();
+        await expect(canvas.getByText('76')).toBeInTheDocument();
+        await expect(canvas.getByText('3')).toBeInTheDocument();
+    },
+};
--- a/web/frontend/app/features/breweries/components/detail/CommunityStatsCard.tsx
+++ b/web/frontend/app/features/breweries/components/detail/CommunityStatsCard.tsx
@@ -0,0 +1,24 @@
+import SidebarCard from '../shared/SidebarCard';
+
+interface CommunityStatsCardProps {
+    likeCount: number;
+    ratingsCount: number;
+    commentCount: number;
+}
+
+const StatRow = ({ label, value }: { label: string; value: number }) => (
+    <div className="flex items-center justify-between gap-2 text-sm">
+        <span className="text-base-content/60">{label}</span>
+        <span className="font-semibold tabular-nums">{value}</span>
+    </div>
+);
+
+const CommunityStatsCard = ({ likeCount, ratingsCount, commentCount }: CommunityStatsCardProps) => (
+    <SidebarCard title="Community">
+        <StatRow label="Likes" value={likeCount} />
+        <StatRow label="Ratings" value={ratingsCount} />
+        <StatRow label="Comments" value={commentCount} />
+    </SidebarCard>
+);
+
+export default CommunityStatsCard;
--- a/web/frontend/app/features/breweries/components/detail/LocationCard.stories.tsx
+++ b/web/frontend/app/features/breweries/components/detail/LocationCard.stories.tsx
@@ -0,0 +1,64 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, within } from 'storybook/test';
+import LocationCard from './LocationCard';
+import type { BreweryLocation } from '../../breweries.server';
+
+const locationCardDescription = `Sidebar "Location" card: an interactive single-pin map (when coordinates are available), address, and website link. Smoke-render only for the map portion - this hits the real OpenStreetMap tile server in the browser test run.`;
+
+const portlandLocation: BreweryLocation = {
+    breweryPostLocationId: 'loc-1',
+    breweryPostId: 'brewery-1',
+    cityId: 'city-1',
+    cityName: 'Portland',
+    stateProvinceName: 'Oregon',
+    stateProvinceCode: 'OR',
+    countryName: 'United States',
+    countryCode: 'US',
+    addressLine1: '123 Hop Street',
+    addressLine2: null,
+    postalCode: '97201',
+    coordinates: { latitude: 45.5152, longitude: -122.6784 },
+};
+
+const meta = {
+    title: 'Breweries/LocationCard',
+    component: LocationCard,
+    tags: ['autodocs'],
+    args: {
+        breweryName: 'Cascade Hollow Brewing',
+        website: 'cascadehollow.example',
+    },
+    parameters: {
+        layout: 'padded',
+        docs: {
+            description: {
+                component: locationCardDescription,
+            },
+        },
+    },
+} satisfies Meta<typeof LocationCard>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const WithCoordinates: Story = {
+    args: { location: portlandLocation },
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await expect(canvas.getByText('Location')).toBeInTheDocument();
+        await expect(canvas.getByRole('link', { name: 'cascadehollow.example' })).toHaveAttribute(
+            'href',
+            'https://cascadehollow.example',
+        );
+    },
+};
+
+export const WithoutCoordinates: Story = {
+    args: { location: { ...portlandLocation, coordinates: null } },
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await expect(
+            canvas.getByText('123 Hop Street, Portland, OR 97201, United States'),
+        ).toBeInTheDocument();
+    },
+};
--- a/web/frontend/app/features/breweries/components/detail/LocationCard.tsx
+++ b/web/frontend/app/features/breweries/components/detail/LocationCard.tsx
@@ -0,0 +1,46 @@
+import { lazy, Suspense } from 'react';
+import ClientOnly from '../../../../components/ClientOnly';
+import SidebarCard from '../shared/SidebarCard';
+import { formatBreweryAddress } from '../../utils/format-address';
+import type { BreweryLocation } from '../../breweries.server';
+
+const BreweryLocationMap = lazy(() => import('./BreweryLocationMap'));
+
+interface LocationCardProps {
+    breweryName: string;
+    location: BreweryLocation;
+    website: string;
+}
+
+const MAP_PLACEHOLDER_CLASS = 'skeleton h-45 w-full rounded-field';
+
+const LocationCard = ({ breweryName, location, website }: LocationCardProps) => (
+    <SidebarCard title="Location">
+        {location.coordinates && (
+            <ClientOnly fallback={<div className={MAP_PLACEHOLDER_CLASS} />}>
+                {() => (
+                    <Suspense fallback={<div className={MAP_PLACEHOLDER_CLASS} />}>
+                        <BreweryLocationMap
+                            latitude={location.coordinates!.latitude}
+                            longitude={location.coordinates!.longitude}
+                            label={`${breweryName} — ${location.addressLine1}`}
+                        />
+                    </Suspense>
+                )}
+            </ClientOnly>
+        )}
+        <p className="text-sm leading-relaxed m-0">{formatBreweryAddress(location)}</p>
+        <p className="text-sm m-0">
+            <a
+                href={`https://${website}`}
+                className="link link-primary"
+                target="_blank"
+                rel="noreferrer"
+            >
+                {website}
+            </a>
+        </p>
+    </SidebarCard>
+);
+
+export default LocationCard;
--- a/web/frontend/app/features/breweries/components/detail/YourRatingCard.stories.tsx
+++ b/web/frontend/app/features/breweries/components/detail/YourRatingCard.stories.tsx
@@ -0,0 +1,45 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, fn, userEvent, within } from 'storybook/test';
+import YourRatingCard from './YourRatingCard';
+
+const yourRatingCardDescription = `Interactive 1-5 star rating control on the brewery detail page. The hint text switches once a rating is set, and clicking the selected star again clears it.`;
+
+const meta = {
+    title: 'Breweries/YourRatingCard',
+    component: YourRatingCard,
+    tags: ['autodocs'],
+    args: {
+        onChange: fn(),
+    },
+    parameters: {
+        layout: 'padded',
+        docs: {
+            description: {
+                component: yourRatingCardDescription,
+            },
+        },
+    },
+} satisfies Meta<typeof YourRatingCard>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Unrated: Story = {
+    args: { value: 0 },
+    play: async ({ args, canvasElement }) => {
+        const canvas = within(canvasElement);
+        await expect(canvas.getByText('Tap a star to rate this brewery.')).toBeInTheDocument();
+        await userEvent.click(canvas.getByRole('radio', { name: 'Rate 4 of 5' }));
+        await expect(args.onChange).toHaveBeenCalledWith(4);
+    },
+};
+
+export const Rated: Story = {
+    args: { value: 4 },
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await expect(
+            canvas.getByText('You rated this 4 of 5. Tap the same star to clear.'),
+        ).toBeInTheDocument();
+    },
+};
--- a/web/frontend/app/features/breweries/components/detail/YourRatingCard.tsx
+++ b/web/frontend/app/features/breweries/components/detail/YourRatingCard.tsx
@@ -0,0 +1,24 @@
+import StarRating from '../shared/StarRating';
+
+interface YourRatingCardProps {
+    value: number;
+    onChange: (value: number) => void;
+}
+
+const YourRatingCard = ({ value, onChange }: YourRatingCardProps) => (
+    <div className="card bg-base-100 shadow">
+        <div className="card-body flex-row flex-wrap items-center justify-between gap-4 p-6">
+            <div className="flex flex-col gap-0.5">
+                <h3 className="text-xl m-0">Your rating</h3>
+                <p className="text-sm text-base-content/60 m-0">
+                    {value
+                        ? `You rated this ${value} of 5. Tap the same star to clear.`
+                        : 'Tap a star to rate this brewery.'}
+                </p>
+            </div>
+            <StarRating value={value} onChange={onChange} size="lg" />
+        </div>
+    </div>
+);
+
+export default YourRatingCard;
--- a/web/frontend/app/features/breweries/components/detail/comments/CommentItem.stories.tsx
+++ b/web/frontend/app/features/breweries/components/detail/comments/CommentItem.stories.tsx
@@ -0,0 +1,56 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, fn, userEvent, within } from 'storybook/test';
+import CommentItem from './CommentItem';
+import type { FillerComment } from '../../../utils/filler-brewery-detail';
+
+const commentItemDescription = `A single comment row on the brewery detail page: avatar initials, username/star/timestamp, body, and a per-comment like toggle.`;
+
+const comment: FillerComment = {
+    id: '1',
+    user: 'malt_kettle',
+    initials: 'MK',
+    rating: 5,
+    time: '2 days ago',
+    text: 'The barrel-aged flanders red is worth the trip alone.',
+    likes: 12,
+    liked: false,
+};
+
+const meta = {
+    title: 'Breweries/CommentItem',
+    component: CommentItem,
+    tags: ['autodocs'],
+    args: {
+        onToggleLike: fn(),
+    },
+    parameters: {
+        layout: 'padded',
+        docs: {
+            description: {
+                component: commentItemDescription,
+            },
+        },
+    },
+} satisfies Meta<typeof CommentItem>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Unliked: Story = {
+    args: { comment },
+    play: async ({ args, canvasElement }) => {
+        const canvas = within(canvasElement);
+        await expect(canvas.getByText('malt_kettle')).toBeInTheDocument();
+        const likeButton = canvas.getByRole('button', { name: /12 likes/i });
+        await userEvent.click(likeButton);
+        await expect(args.onToggleLike).toHaveBeenCalledWith('1');
+    },
+};
+
+export const Liked: Story = {
+    args: { comment: { ...comment, liked: true } },
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await expect(canvas.getByRole('button', { name: /13 likes/i })).toBeInTheDocument();
+    },
+};
--- a/web/frontend/app/features/breweries/components/detail/comments/CommentItem.tsx
+++ b/web/frontend/app/features/breweries/components/detail/comments/CommentItem.tsx
@@ -0,0 +1,46 @@
+import { Heart, HeartSolid } from 'iconoir-react';
+import StarRating from '../../shared/StarRating';
+import type { FillerComment } from '../../../utils/filler-brewery-detail';
+
+interface CommentItemProps {
+    comment: FillerComment;
+    onToggleLike: (id: string) => void;
+}
+
+const CommentItem = ({ comment, onToggleLike }: CommentItemProps) => {
+    const likeCount = comment.likes + (comment.liked ? 1 : 0);
+
+    return (
+        <div className="flex gap-3 items-start border-t border-base-content/10 pt-4">
+            <div className="avatar avatar-placeholder shrink-0">
+                <div className="bg-secondary text-secondary-content w-9 rounded-full">
+                    <span className="text-sm font-bold">{comment.initials}</span>
+                </div>
+            </div>
+            <div className="flex-1 flex flex-col gap-1 min-w-0">
+                <div className="flex items-baseline gap-2 flex-wrap">
+                    <span className="font-bold text-sm">{comment.user}</span>
+                    <StarRating value={comment.rating} size="xs" />
+                    <span className="text-xs text-base-content/60">{comment.time}</span>
+                </div>
+                <p className="text-sm leading-relaxed m-0">{comment.text}</p>
+                <button
+                    type="button"
+                    onClick={() => onToggleLike(comment.id)}
+                    className={`self-start inline-flex items-center gap-1 text-xs font-semibold ${
+                        comment.liked ? 'text-primary' : 'text-base-content/60'
+                    }`}
+                >
+                    {comment.liked ? (
+                        <HeartSolid className="size-3.5" aria-hidden="true" />
+                    ) : (
+                        <Heart className="size-3.5" aria-hidden="true" />
+                    )}
+                    {likeCount} {likeCount === 1 ? 'like' : 'likes'}
+                </button>
+            </div>
+        </div>
+    );
+};
+
+export default CommentItem;
--- a/web/frontend/app/features/breweries/components/detail/comments/CommentsCard.stories.tsx
+++ b/web/frontend/app/features/breweries/components/detail/comments/CommentsCard.stories.tsx
@@ -0,0 +1,59 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, fn, userEvent, within } from 'storybook/test';
+import CommentsCard from './CommentsCard';
+import { FILLER_COMMENTS } from '../../../utils/filler-brewery-detail';
+
+const commentsCardDescription = `Comments section on the brewery detail page: a post form (logged in) or a sign-in alert (logged out), followed by the comment list. Posting is disabled until the textarea has non-whitespace content.`;
+
+const meta = {
+    title: 'Breweries/CommentsCard',
+    component: CommentsCard,
+    tags: ['autodocs'],
+    args: {
+        comments: FILLER_COMMENTS,
+        currentUserInitials: 'JD',
+        onAddComment: fn(),
+        onToggleCommentLike: fn(),
+    },
+    parameters: {
+        layout: 'padded',
+        docs: {
+            description: {
+                component: commentsCardDescription,
+            },
+        },
+    },
+} satisfies Meta<typeof CommentsCard>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const LoggedIn: Story = {
+    args: { loggedIn: true },
+    play: async ({ args, canvasElement }) => {
+        const canvas = within(canvasElement);
+        const postButton = canvas.getByRole('button', { name: /post comment/i });
+        await expect(postButton).toBeDisabled();
+
+        await userEvent.type(
+            canvas.getByPlaceholderText('Share your thoughts on this brewery'),
+            'Great taproom!',
+        );
+        await expect(postButton).toBeEnabled();
+        await userEvent.click(postButton);
+        await expect(args.onAddComment).toHaveBeenCalledWith('Great taproom!');
+    },
+};
+
+export const LoggedOut: Story = {
+    args: { loggedIn: false },
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await expect(
+            canvas.getByText('Sign in to like, rate, and comment on breweries.'),
+        ).toBeInTheDocument();
+        await expect(
+            canvas.queryByPlaceholderText('Share your thoughts on this brewery'),
+        ).not.toBeInTheDocument();
+    },
+};
--- a/web/frontend/app/features/breweries/components/detail/comments/CommentsCard.tsx
+++ b/web/frontend/app/features/breweries/components/detail/comments/CommentsCard.tsx
@@ -0,0 +1,79 @@
+import { useState } from 'react';
+import CommentItem from './CommentItem';
+import type { FillerComment } from '../../../utils/filler-brewery-detail';
+
+interface CommentsCardProps {
+    comments: FillerComment[];
+    loggedIn: boolean;
+    currentUserInitials: string;
+    onAddComment: (text: string) => void;
+    onToggleCommentLike: (id: string) => void;
+}
+
+const CommentsCard = ({
+    comments,
+    loggedIn,
+    currentUserInitials,
+    onAddComment,
+    onToggleCommentLike,
+}: CommentsCardProps) => {
+    const [commentText, setCommentText] = useState('');
+
+    const handleSubmit = () => {
+        const text = commentText.trim();
+        if (!text) return;
+        onAddComment(text);
+        setCommentText('');
+    };
+
+    return (
+        <div className="card bg-base-100 shadow">
+            <div className="card-body gap-5 p-6">
+                <h3 className="text-xl m-0">Comments ({comments.length})</h3>
+
+                {loggedIn ? (
+                    <div className="flex gap-3 items-start">
+                        <div className="avatar avatar-placeholder shrink-0">
+                            <div className="bg-secondary text-secondary-content w-9 rounded-full">
+                                <span className="text-sm font-bold">{currentUserInitials}</span>
+                            </div>
+                        </div>
+                        <div className="flex-1 flex flex-col gap-2">
+                            <textarea
+                                rows={3}
+                                placeholder="Share your thoughts on this brewery"
+                                value={commentText}
+                                onChange={(e) => setCommentText(e.target.value)}
+                                className="textarea w-full"
+                            />
+                            <button
+                                type="button"
+                                onClick={handleSubmit}
+                                disabled={!commentText.trim()}
+                                className="btn btn-sm btn-primary self-end"
+                            >
+                                Post comment
+                            </button>
+                        </div>
+                    </div>
+                ) : (
+                    <div role="alert" className="alert alert-info alert-soft">
+                        Sign in to like, rate, and comment on breweries.
+                    </div>
+                )}
+
+                <div className="flex flex-col gap-4">
+                    {comments.map((comment) => (
+                        <CommentItem
+                            key={comment.id}
+                            comment={comment}
+                            onToggleLike={onToggleCommentLike}
+                        />
+                    ))}
+                </div>
+            </div>
+        </div>
+    );
+};
+
+export default CommentsCard;
--- a/web/frontend/app/features/breweries/components/directory/BreweryCard.stories.tsx
+++ b/web/frontend/app/features/breweries/components/directory/BreweryCard.stories.tsx
@@ -0,0 +1,102 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, within } from 'storybook/test';
+import BreweryCard from './BreweryCard';
+import type { Brewery, BreweryLocation } from '../../breweries.server';
+import { formatBreweryAddress } from '../../utils/format-address';
+
+const breweryCardDescription = `Link-card for a brewery shown in listing grids. These stories cover a brewery with a full mapped location, one whose location has no coordinates (no "View on map" link), and one with no location at all.`;
+
+const portlandLocation: BreweryLocation = {
+    breweryPostLocationId: 'loc-1',
+    breweryPostId: 'brewery-1',
+    cityId: 'city-1',
+    cityName: 'Portland',
+    stateProvinceName: 'Oregon',
+    stateProvinceCode: 'OR',
+    countryName: 'United States',
+    countryCode: 'US',
+    addressLine1: '123 Hop Street',
+    addressLine2: null,
+    postalCode: '97201',
+    coordinates: { latitude: 45.5152, longitude: -122.6784 },
+};
+
+const breweryWithLocation: Brewery = {
+    breweryPostId: 'brewery-1',
+    postedById: 'user-1',
+    breweryName: 'Cascade Hollow Brewing',
+    description:
+        'A small-batch brewery known for hazy IPAs and barrel-aged sours, tucked into an old warehouse district.',
+    createdAt: '2024-03-01T12:00:00.000Z',
+    updatedAt: null,
+    location: portlandLocation,
+};
+
+const breweryWithoutCoordinates: Brewery = {
+    ...breweryWithLocation,
+    breweryPostId: 'brewery-2',
+    breweryName: 'Foggy Bottom Brewhouse',
+    location: { ...portlandLocation, coordinates: null },
+};
+
+const breweryWithoutLocation: Brewery = {
+    ...breweryWithLocation,
+    breweryPostId: 'brewery-3',
+    breweryName: 'Unmapped Ales',
+    location: null,
+};
+
+const meta = {
+    title: 'Breweries/BreweryCard',
+    component: BreweryCard,
+    tags: ['autodocs'],
+    parameters: {
+        layout: 'padded',
+        docs: {
+            description: {
+                component: breweryCardDescription,
+            },
+        },
+    },
+} satisfies Meta<typeof BreweryCard>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const WithLocation: Story = {
+    args: { brewery: breweryWithLocation },
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await expect(
+            canvas.getByRole('heading', { name: 'Cascade Hollow Brewing' }),
+        ).toBeInTheDocument();
+        await expect(canvas.getByText('Portland, OR')).toBeInTheDocument();
+        await expect(canvas.getByText(formatBreweryAddress(portlandLocation))).toBeInTheDocument();
+
+        const cardLink = canvas.getByRole('link', { name: /cascade hollow brewing/i });
+        await expect(cardLink).toHaveAttribute('href', '/breweries/brewery-1');
+
+        const mapLink = canvas.getByRole('link', { name: 'View on map →' });
+        await expect(mapLink).toHaveAttribute('href', expect.stringContaining('mlat=45.5152'));
+        await expect(mapLink).toHaveAttribute('target', '_blank');
+    },
+};
+
+export const WithoutCoordinates: Story = {
+    args: { brewery: breweryWithoutCoordinates },
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await expect(canvas.getByText('Portland, OR')).toBeInTheDocument();
+        await expect(canvas.queryByRole('link', { name: /view on map/i })).not.toBeInTheDocument();
+    },
+};
+
+export const WithoutLocation: Story = {
+    args: { brewery: breweryWithoutLocation },
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await expect(canvas.getByRole('heading', { name: 'Unmapped Ales' })).toBeInTheDocument();
+        await expect(canvas.queryByText('Portland, OR')).not.toBeInTheDocument();
+        await expect(canvas.queryByRole('link', { name: /view on map/i })).not.toBeInTheDocument();
+    },
+};
--- a/web/frontend/app/features/breweries/components/directory/BreweryCard.tsx
+++ b/web/frontend/app/features/breweries/components/directory/BreweryCard.tsx
@@ -0,0 +1,46 @@
+import { Link } from 'react-router';
+import type { Brewery } from '../../breweries.server';
+import { formatBreweryAddress } from '../../utils/format-address';
+
+interface BreweryCardProps {
+    brewery: Brewery;
+}
+
+const BreweryCard = ({ brewery }: BreweryCardProps) => (
+    <Link
+        to={`/breweries/${brewery.breweryPostId}`}
+        className="card bg-base-100 shadow hover:shadow-lg transition-shadow"
+    >
+        <div className="card-body">
+            <h2 className="card-title">{brewery.breweryName}</h2>
+            {brewery.location && (
+                <p className="text-sm font-medium text-base-content/70">
+                    {brewery.location.cityName}, {brewery.location.stateProvinceCode}
+                </p>
+            )}
+            {brewery.description && (
+                <p className="text-sm leading-5 text-base-content/70 line-clamp-2 max-h-10 overflow-hidden">
+                    {brewery.description}
+                </p>
+            )}
+            {brewery.location && (
+                <p className="text-sm text-base-content/50 mt-2">
+                    {formatBreweryAddress(brewery.location)}
+                </p>
+            )}
+            {brewery.location?.coordinates && (
+                <a
+                    href={`https://www.openstreetmap.org/?mlat=${brewery.location.coordinates.latitude}&mlon=${brewery.location.coordinates.longitude}#map=16/${brewery.location.coordinates.latitude}/${brewery.location.coordinates.longitude}`}
+                    target="_blank"
+                    rel="noreferrer"
+                    onClick={(e) => e.stopPropagation()}
+                    className="link link-primary text-sm mt-2 self-start"
+                >
+                    View on map &rarr;
+                </a>
+            )}
+        </div>
+    </Link>
+);
+
+export default BreweryCard;
--- a/web/frontend/app/features/breweries/components/directory/BreweryMap.stories.tsx
+++ b/web/frontend/app/features/breweries/components/directory/BreweryMap.stories.tsx
@@ -0,0 +1,61 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import BreweryMap, { type BreweryMapPin } from './BreweryMap';
+import type { BreweryLocation } from '../../breweries.server';
+
+const breweryMapDescription = `Leaflet map plotting brewery locations, with an optional current-location marker. Smoke-render only - this hits the real OpenStreetMap tile server in the browser test run, and its \`navigator.geolocation\` call is tolerated whether or not it succeeds.`;
+
+const portlandLocation: BreweryLocation = {
+    breweryPostLocationId: 'loc-1',
+    breweryPostId: 'brewery-1',
+    cityId: 'city-1',
+    cityName: 'Portland',
+    stateProvinceName: 'Oregon',
+    stateProvinceCode: 'OR',
+    countryName: 'United States',
+    countryCode: 'US',
+    addressLine1: '123 Hop Street',
+    addressLine2: null,
+    postalCode: '97201',
+    coordinates: { latitude: 45.5152, longitude: -122.6784 },
+};
+
+const pins: BreweryMapPin[] = [
+    {
+        id: 'brewery-1',
+        name: 'Cascade Hollow Brewing',
+        latitude: 45.5152,
+        longitude: -122.6784,
+        location: portlandLocation,
+    },
+    {
+        id: 'brewery-2',
+        name: 'Foggy Bottom Brewhouse',
+        latitude: 44.06,
+        longitude: -121.31,
+        location: null,
+    },
+];
+
+const meta = {
+    title: 'Breweries/BreweryMap',
+    component: BreweryMap,
+    parameters: {
+        layout: 'padded',
+        docs: {
+            description: {
+                component: breweryMapDescription,
+            },
+        },
+    },
+} satisfies Meta<typeof BreweryMap>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+    args: { breweries: pins },
+};
+
+export const NoBreweries: Story = {
+    args: { breweries: [] },
+};
--- a/web/frontend/app/features/breweries/components/directory/BreweryMap.tsx
+++ b/web/frontend/app/features/breweries/components/directory/BreweryMap.tsx
@@ -0,0 +1,124 @@
+import { useEffect, useState } from 'react';
+import { MapContainer, TileLayer, Marker, Popup, useMap } from 'react-leaflet';
+import L, { type LatLngExpression, type LatLngTuple } from 'leaflet';
+import iconRetinaUrl from 'leaflet/dist/images/marker-icon-2x.png';
+import iconUrl from 'leaflet/dist/images/marker-icon.png';
+import shadowUrl from 'leaflet/dist/images/marker-shadow.png';
+import 'leaflet/dist/leaflet.css';
+import useMediaQuery from '../../../../hooks/useMediaQuery';
+import type { BreweryLocation } from '../../breweries.server';
+import { formatBreweryAddress } from '../../utils/format-address';
+
+delete (L.Icon.Default.prototype as unknown as { _getIconUrl?: unknown })._getIconUrl;
+L.Icon.Default.mergeOptions({ iconRetinaUrl, iconUrl, shadowUrl });
+
+export interface BreweryMapPin {
+    id: string;
+    name: string;
+    latitude: number;
+    longitude: number;
+    location: BreweryLocation | null;
+}
+
+interface BreweryMapProps {
+    breweries: BreweryMapPin[];
+}
+
+const FALLBACK_CENTER: LatLngExpression = [20, 0];
+const WORLD_BOUNDS: LatLngTuple[] = [
+    [-90, -180],
+    [90, 180],
+];
+
+const CURRENT_LOCATION_ICON = L.divIcon({
+    className: 'brewery-map-current-location',
+    html: '<span class="block h-3.5 w-3.5 rounded-full bg-primary border-2 border-base-100 shadow-md"></span>',
+    iconSize: [14, 14],
+    iconAnchor: [7, 7],
+});
+
+const useCurrentLocation = () => {
+    const [position, setPosition] = useState<LatLngTuple | null>(null);
+
+    useEffect(() => {
+        if (!navigator.geolocation) return;
+
+        navigator.geolocation.getCurrentPosition(
+            (pos) => setPosition([pos.coords.latitude, pos.coords.longitude]),
+            () => setPosition(null),
+            { enableHighAccuracy: true },
+        );
+    }, []);
+
+    return position;
+};
+
+const CurrentLocationMarker = ({ position }: { position: LatLngTuple }) => (
+    <Marker position={position} icon={CURRENT_LOCATION_ICON}>
+        <Popup>Your location</Popup>
+    </Marker>
+);
+
+const CURRENT_LOCATION_ZOOM = 6;
+
+const RecenterMap = ({
+    bounds,
+    currentLocation,
+}: {
+    bounds: LatLngTuple[];
+    currentLocation: LatLngTuple | null;
+}) => {
+    const map = useMap();
+
+    useEffect(() => {
+        if (currentLocation) {
+            map.setView(currentLocation, CURRENT_LOCATION_ZOOM, { animate: false });
+        } else if (bounds.length > 0) {
+            map.fitBounds(bounds, { padding: [32, 32], maxZoom: 6, animate: false });
+        }
+    }, [map, bounds, currentLocation]);
+
+    return null;
+};
+
+const BreweryMap = ({ breweries }: BreweryMapProps) => {
+    const currentLocation = useCurrentLocation();
+    const bounds: LatLngTuple[] = breweries.map((brewery) => [brewery.latitude, brewery.longitude]);
+
+    return (
+        <MapContainer
+            center={currentLocation ?? bounds[0] ?? FALLBACK_CENTER}
+            zoom={4}
+            scrollWheelZoom={false}
+            maxBounds={WORLD_BOUNDS}
+            maxBoundsViscosity={1.0}
+            worldCopyJump={false}
+            className="h-112 md:h-136 w-full rounded-box relative z-0"
+        >
+            <TileLayer
+                attribution='&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
+                url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"
+                noWrap
+            />
+            <RecenterMap bounds={bounds} currentLocation={currentLocation} />
+            {currentLocation && <CurrentLocationMarker position={currentLocation} />}
+            {breweries.map((brewery) => (
+                <Marker key={brewery.id} position={[brewery.latitude, brewery.longitude]}>
+                    <Popup>
+                        <p className="font-semibold">{brewery.name}</p>
+                        {brewery.location && (
+                            <p className="text-sm text-base-content/70">
+                                {formatBreweryAddress(brewery.location)}
+                            </p>
+                        )}
+                        <a href={`/breweries/${brewery.id}`} className="link link-primary text-sm">
+                            View brewery &rarr;
+                        </a>
+                    </Popup>
+                </Marker>
+            ))}
+        </MapContainer>
+    );
+};
+
+export default BreweryMap;
--- a/web/frontend/app/features/breweries/components/overview/FeaturedBreweryCard.stories.tsx
+++ b/web/frontend/app/features/breweries/components/overview/FeaturedBreweryCard.stories.tsx
@@ -0,0 +1,106 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, fn, userEvent, within } from 'storybook/test';
+import FeaturedBreweryCard from './FeaturedBreweryCard';
+import type { Brewery, BreweryLocation } from '../../breweries.server';
+
+const featuredBreweryCardDescription = `Larger "featured brewery" card shown above the fold on the breweries page. These stories cover a brewery with mappable coordinates (the "Show on map" button is present and wired to \`onShowOnMap\`), one with a location but no coordinates, and one with no location at all.`;
+
+const portlandLocation: BreweryLocation = {
+    breweryPostLocationId: 'loc-1',
+    breweryPostId: 'brewery-1',
+    cityId: 'city-1',
+    cityName: 'Portland',
+    stateProvinceName: 'Oregon',
+    stateProvinceCode: 'OR',
+    countryName: 'United States',
+    countryCode: 'US',
+    addressLine1: '123 Hop Street',
+    addressLine2: null,
+    postalCode: '97201',
+    coordinates: { latitude: 45.5152, longitude: -122.6784 },
+};
+
+const breweryWithLocation: Brewery = {
+    breweryPostId: 'brewery-1',
+    postedById: 'user-1',
+    breweryName: 'Cascade Hollow Brewing',
+    description:
+        'A small-batch brewery known for hazy IPAs and barrel-aged sours, tucked into an old warehouse district.',
+    createdAt: '2024-03-01T12:00:00.000Z',
+    updatedAt: null,
+    location: portlandLocation,
+};
+
+const breweryWithoutCoordinates: Brewery = {
+    ...breweryWithLocation,
+    breweryPostId: 'brewery-2',
+    breweryName: 'Foggy Bottom Brewhouse',
+    location: { ...portlandLocation, coordinates: null },
+};
+
+const breweryWithoutLocation: Brewery = {
+    ...breweryWithLocation,
+    breweryPostId: 'brewery-3',
+    breweryName: 'Unmapped Ales',
+    location: null,
+};
+
+const meta = {
+    title: 'Breweries/FeaturedBreweryCard',
+    component: FeaturedBreweryCard,
+    tags: ['autodocs'],
+    args: {
+        onShowOnMap: fn(),
+    },
+    parameters: {
+        layout: 'padded',
+        docs: {
+            description: {
+                component: featuredBreweryCardDescription,
+            },
+        },
+    },
+} satisfies Meta<typeof FeaturedBreweryCard>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const WithCoordinates: Story = {
+    args: { brewery: breweryWithLocation },
+    play: async ({ args, canvasElement }) => {
+        const canvas = within(canvasElement);
+        await expect(
+            canvas.getByRole('heading', { name: 'Cascade Hollow Brewing', level: 3 }),
+        ).toBeInTheDocument();
+        await expect(canvas.getByText('Founded')).toBeInTheDocument();
+        await expect(canvas.getByText('2014')).toBeInTheDocument();
+        await expect(canvas.getByRole('link', { name: /view brewery/i })).toHaveAttribute(
+            'href',
+            '/breweries/brewery-1',
+        );
+
+        await userEvent.click(canvas.getByRole('button', { name: /show on map/i }));
+        await expect(args.onShowOnMap).toHaveBeenCalledOnce();
+    },
+};
+
+export const WithoutCoordinates: Story = {
+    args: { brewery: breweryWithoutCoordinates },
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await expect(
+            canvas.queryByRole('button', { name: /show on map/i }),
+        ).not.toBeInTheDocument();
+    },
+};
+
+export const WithoutLocation: Story = {
+    args: { brewery: breweryWithoutLocation },
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await expect(canvas.getByRole('heading', { name: 'Unmapped Ales' })).toBeInTheDocument();
+        await expect(
+            canvas.queryByRole('button', { name: /show on map/i }),
+        ).not.toBeInTheDocument();
+    },
+};
--- a/web/frontend/app/features/breweries/components/overview/FeaturedBreweryCard.tsx
+++ b/web/frontend/app/features/breweries/components/overview/FeaturedBreweryCard.tsx
@@ -0,0 +1,59 @@
+import { Link } from 'react-router';
+import type { Brewery } from '../../breweries.server';
+import { formatBreweryAddress } from '../../utils/format-address';
+
+interface FeaturedBreweryCardProps {
+    brewery: Brewery;
+    onShowOnMap: () => void;
+}
+
+// see BREWERY_HANDOFF.md
+const FILLER_STATS = [
+    { label: 'Founded', value: '2014' },
+    { label: 'Beers listed', value: '18' },
+    { label: 'House style', value: 'Seasonal ale' },
+];
+
+const FeaturedBreweryCard = ({ brewery, onShowOnMap }: FeaturedBreweryCardProps) => (
+    <div className="card bg-base-100 shadow-md rounded-box">
+        <div className="card-body gap-3.5 p-8 md:grid md:grid-cols-[1.35fr_1fr] md:gap-10 md:items-start">
+            <div className="flex flex-col gap-3.5">
+                {brewery.location && (
+                    <div className="text-sm font-semibold text-base-content/60">
+                        {brewery.location.cityName}, {brewery.location.stateProvinceCode}
+                    </div>
+                )}
+                <h3 className="font-serif text-4xl leading-tight m-0">{brewery.breweryName}</h3>
+                <p className="text-lg leading-snug text-pretty m-0">{brewery.description}</p>
+                {brewery.location && (
+                    <p className="text-sm text-base-content/60 m-0">
+                        {formatBreweryAddress(brewery.location)}
+                    </p>
+                )}
+                <div className="flex gap-3 pt-2">
+                    <Link to={`/breweries/${brewery.breweryPostId}`} className="btn btn-primary">
+                        View brewery
+                    </Link>
+                    {brewery.location?.coordinates && (
+                        <button type="button" onClick={onShowOnMap} className="btn btn-outline">
+                            Show on map
+                        </button>
+                    )}
+                </div>
+            </div>
+
+            <div className="stats stats-vertical shadow w-full mt-6 md:mt-0">
+                {FILLER_STATS.map((stat) => (
+                    <div key={stat.label} className="stat">
+                        <div className="stat-title text-xs font-bold uppercase tracking-widest">
+                            {stat.label}
+                        </div>
+                        <div className="stat-value font-serif text-2xl">{stat.value}</div>
+                    </div>
+                ))}
+            </div>
+        </div>
+    </div>
+);
+
+export default FeaturedBreweryCard;
--- a/web/frontend/app/features/breweries/components/overview/RecentBreweries.stories.tsx
+++ b/web/frontend/app/features/breweries/components/overview/RecentBreweries.stories.tsx
@@ -0,0 +1,93 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, within } from 'storybook/test';
+import RecentBreweries from './RecentBreweries';
+import type { Brewery, BreweryLocation } from '../../breweries.server';
+
+const recentBreweriesDescription = `Grid of recently-added breweries shown on the breweries index page. Renders nothing when the list is empty.`;
+
+const portlandLocation: BreweryLocation = {
+    breweryPostLocationId: 'loc-1',
+    breweryPostId: 'brewery-1',
+    cityId: 'city-1',
+    cityName: 'Portland',
+    stateProvinceName: 'Oregon',
+    stateProvinceCode: 'OR',
+    countryName: 'United States',
+    countryCode: 'US',
+    addressLine1: '123 Hop Street',
+    addressLine2: null,
+    postalCode: '97201',
+    coordinates: { latitude: 45.5152, longitude: -122.6784 },
+};
+
+const cascadeHollow: Brewery = {
+    breweryPostId: 'brewery-1',
+    postedById: 'user-1',
+    breweryName: 'Cascade Hollow Brewing',
+    description: 'A small-batch brewery known for hazy IPAs and barrel-aged sours.',
+    createdAt: '2024-03-01T12:00:00.000Z',
+    updatedAt: null,
+    location: portlandLocation,
+};
+
+const midrangeMalts: Brewery = {
+    breweryPostId: 'brewery-2',
+    postedById: 'user-2',
+    breweryName: 'Midrange Malts',
+    description: 'A neighborhood taproom pouring approachable session ales year-round.',
+    createdAt: '2024-04-15T09:30:00.000Z',
+    updatedAt: null,
+    location: { ...portlandLocation, breweryPostId: 'brewery-2', cityName: 'Salem' },
+};
+
+const unmappedAles: Brewery = {
+    breweryPostId: 'brewery-3',
+    postedById: 'user-3',
+    breweryName: 'Unmapped Ales',
+    description: 'A pop-up brewery that hasn’t added a storefront location yet.',
+    createdAt: '2024-05-02T18:00:00.000Z',
+    updatedAt: null,
+    location: null,
+};
+
+const meta = {
+    title: 'Breweries/RecentBreweries',
+    component: RecentBreweries,
+    tags: ['autodocs'],
+    parameters: {
+        layout: 'padded',
+        docs: {
+            description: {
+                component: recentBreweriesDescription,
+            },
+        },
+    },
+} satisfies Meta<typeof RecentBreweries>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const WithBreweries: Story = {
+    args: { breweries: [cascadeHollow, midrangeMalts, unmappedAles] },
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await expect(canvas.getByRole('heading', { name: 'Recently added' })).toBeInTheDocument();
+        await expect(
+            canvas.getByRole('heading', { name: 'Cascade Hollow Brewing' }),
+        ).toBeInTheDocument();
+
+        const links = canvas.getAllByRole('link', { name: /view brewery/i });
+        await expect(links).toHaveLength(3);
+        await expect(links[0]).toHaveAttribute('href', '/breweries/brewery-1');
+    },
+};
+
+export const Empty: Story = {
+    args: { breweries: [] },
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await expect(
+            canvas.queryByRole('heading', { name: 'Recently added' }),
+        ).not.toBeInTheDocument();
+    },
+};
--- a/web/frontend/app/features/breweries/components/overview/RecentBreweries.tsx
+++ b/web/frontend/app/features/breweries/components/overview/RecentBreweries.tsx
@@ -0,0 +1,42 @@
+import { Link } from 'react-router';
+import type { Brewery } from '../../breweries.server';
+
+interface RecentBreweriesProps {
+    breweries: Brewery[];
+}
+
+const RecentBreweries = ({ breweries }: RecentBreweriesProps) => {
+    if (breweries.length === 0) return null;
+
+    return (
+        <section className="max-w-7xl mx-auto px-5 pt-11">
+            <h2 className="font-serif text-2xl mb-3.5">Recently added</h2>
+            <div className="grid gap-5 grid-cols-[repeat(auto-fit,minmax(15rem,1fr))]">
+                {breweries.map((brewery) => (
+                    <div key={brewery.breweryPostId} className="card bg-base-100 shadow">
+                        <div className="card-body gap-1.5">
+                            <h3 className="card-title font-serif text-xl">{brewery.breweryName}</h3>
+                            {brewery.location && (
+                                <div className="text-sm text-base-content/60">
+                                    {brewery.location.cityName},{' '}
+                                    {brewery.location.stateProvinceCode}
+                                </div>
+                            )}
+                            <p className="text-sm leading-snug mt-1 line-clamp-2">
+                                {brewery.description}
+                            </p>
+                            <Link
+                                to={`/breweries/${brewery.breweryPostId}`}
+                                className="link link-hover text-sm font-semibold text-secondary hover:text-primary mt-2"
+                            >
+                                View brewery &rarr;
+                            </Link>
+                        </div>
+                    </div>
+                ))}
+            </div>
+        </section>
+    );
+};
+
+export default RecentBreweries;
--- a/web/frontend/app/features/breweries/components/overview/nearby/NearbyBreweriesSection.stories.tsx
+++ b/web/frontend/app/features/breweries/components/overview/nearby/NearbyBreweriesSection.stories.tsx
@@ -0,0 +1,180 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useState } from 'react';
+import { createMemoryRouter, RouterProvider } from 'react-router';
+import { expect, fireEvent, waitFor, within } from 'storybook/test';
+import NearbyBreweriesSection from './NearbyBreweriesSection';
+import type { BreweryLocation, SimplifiedBrewery } from '../../../breweries.server';
+
+const nearbyBreweriesSectionDescription = `Requests geolocation (falling back to \`fallbackCenter\` when it's unavailable or denied, as it reliably is in headless browser tests), then loads nearby breweries via \`useFetcher().load()\` against the \`/breweries/nearby\` route, re-fetching whenever the debounced search radius changes. This harness runs the real component behind a \`createMemoryRouter\` with a fake loader for that route, keyed by the requested radius, so the \`Default\` story's play function can prove both the initial load and that rapid radius changes are debounced into a single re-fetch rather than one per step. The lazily-loaded Leaflet map mounts for real here (Storybook's client-only render means \`ClientOnly\` reports "mounted" immediately) and will issue real tile requests - the play function doesn't assert anything about it.`;
+
+const portlandLocation: BreweryLocation = {
+    breweryPostLocationId: 'loc-close',
+    breweryPostId: 'brewery-close',
+    cityId: 'city-1',
+    cityName: 'Portland',
+    stateProvinceName: 'Oregon',
+    stateProvinceCode: 'OR',
+    countryName: 'United States',
+    countryCode: 'US',
+    addressLine1: '123 Hop Street',
+    addressLine2: null,
+    postalCode: '97201',
+    coordinates: { latitude: 45.52, longitude: -122.68 },
+};
+
+const closeQuarters: SimplifiedBrewery = {
+    breweryPostId: 'brewery-close',
+    breweryName: 'Close Quarters Brewing',
+    location: portlandLocation,
+    distanceMetres: 4800,
+};
+
+const midrangeMalts: SimplifiedBrewery = {
+    breweryPostId: 'brewery-mid',
+    breweryName: 'Midrange Malts',
+    location: {
+        ...portlandLocation,
+        breweryPostLocationId: 'loc-mid',
+        breweryPostId: 'brewery-mid',
+        cityName: 'Salem',
+        coordinates: { latitude: 44.94, longitude: -123.03 },
+    },
+    distanceMetres: 52000,
+};
+
+const farFlungFermentery: SimplifiedBrewery = {
+    breweryPostId: 'brewery-far',
+    breweryName: 'Far Flung Fermentery',
+    location: {
+        ...portlandLocation,
+        breweryPostLocationId: 'loc-far',
+        breweryPostId: 'brewery-far',
+        cityName: 'Bend',
+        coordinates: { latitude: 44.06, longitude: -121.31 },
+    },
+    distanceMetres: 138000,
+};
+
+const FALLBACK_CENTER = { latitude: 45.5152, longitude: -122.6784, label: 'Portland, OR' };
+
+// Keyed by rangeInMetres so the play function can prove the radius slider
+// drives refetches. DEFAULT_RADIUS_KM=120 -> 120000; MAX_RADIUS_KM=150 -> 150000.
+const NEARBY_FIXTURES: Record<number, SimplifiedBrewery[]> = {
+    30000: [closeQuarters],
+    60000: [closeQuarters],
+    90000: [closeQuarters, midrangeMalts],
+    120000: [closeQuarters, midrangeMalts],
+    150000: [closeQuarters, midrangeMalts, farFlungFermentery],
+};
+
+let fetchedRanges: number[] = [];
+
+const NearbyBreweriesRoute = () => {
+    const [selectedId, setSelectedId] = useState<string | null>(null);
+    return (
+        <NearbyBreweriesSection
+            featured={null}
+            fallbackCenter={FALLBACK_CENTER}
+            selectedId={selectedId}
+            onSelect={setSelectedId}
+        />
+    );
+};
+
+const NearbyBreweriesHarness = () => {
+    const [router] = useState(() => {
+        fetchedRanges = [];
+        return createMemoryRouter([
+            { path: '/', element: <NearbyBreweriesRoute /> },
+            {
+                path: '/breweries/nearby',
+                loader: async ({ request }) => {
+                    const rangeInMetres = Number(
+                        new URL(request.url).searchParams.get('rangeInMetres'),
+                    );
+                    fetchedRanges.push(rangeInMetres);
+                    return { breweries: NEARBY_FIXTURES[rangeInMetres] ?? [] };
+                },
+            },
+        ]);
+    });
+
+    return <RouterProvider router={router} />;
+};
+
+const NearbyBreweriesEmptyHarness = () => {
+    const [router] = useState(() =>
+        createMemoryRouter([
+            { path: '/', element: <NearbyBreweriesRoute /> },
+            {
+                path: '/breweries/nearby',
+                loader: async () => ({ breweries: [] as SimplifiedBrewery[] }),
+            },
+        ]),
+    );
+
+    return <RouterProvider router={router} />;
+};
+
+const meta = {
+    title: 'Breweries/NearbyBreweriesSection',
+    component: NearbyBreweriesHarness,
+    tags: ['autodocs'],
+    parameters: {
+        layout: 'fullscreen',
+        usesDataRouter: true,
+        docs: {
+            description: {
+                component: nearbyBreweriesSectionDescription,
+            },
+        },
+    },
+} satisfies Meta<typeof NearbyBreweriesHarness>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+
+        // Initial (undebounced) fetch at the default radius (120km -> 120000m).
+        await waitFor(
+            () => expect(canvas.getByText('Close Quarters Brewing')).toBeInTheDocument(),
+            { timeout: 3000 },
+        );
+        await expect(canvas.getByText('Midrange Malts')).toBeInTheDocument();
+        await expect(fetchedRanges).toEqual([120000]);
+
+        // Simulate a fast drag through several intermediate values with no
+        // waits in between.
+        const radiusSlider = canvas.getByRole('slider', { name: /search radius/i });
+        fireEvent.change(radiusSlider, { target: { value: '30' } });
+        fireEvent.change(radiusSlider, { target: { value: '60' } });
+        fireEvent.change(radiusSlider, { target: { value: '90' } });
+        fireEvent.change(radiusSlider, { target: { value: '150' } });
+
+        // The radius label updates immediately (it isn't debounced)...
+        await expect(canvas.getByText('150 km')).toBeInTheDocument();
+        // ...but no new fetch has fired yet - the 300ms debounce window hasn't elapsed.
+        await expect(fetchedRanges).toEqual([120000]);
+
+        // After the debounce window, exactly one more fetch happens, for the
+        // final radius only - not one per intermediate step.
+        await waitFor(() => expect(canvas.getByText('Far Flung Fermentery')).toBeInTheDocument(), {
+            timeout: 3000,
+        });
+        await expect(fetchedRanges).toEqual([120000, 150000]);
+    },
+};
+
+export const NoBreweriesWithinRadius: Story = {
+    render: () => <NearbyBreweriesEmptyHarness />,
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await waitFor(
+            () => expect(canvas.getByText(/no partner breweries within/i)).toBeInTheDocument(),
+            { timeout: 3000 },
+        );
+    },
+};
--- a/web/frontend/app/features/breweries/components/overview/nearby/NearbyBreweriesSection.tsx
+++ b/web/frontend/app/features/breweries/components/overview/nearby/NearbyBreweriesSection.tsx
@@ -0,0 +1,173 @@
+import { lazy, Suspense, useEffect, useState } from 'react';
+import { useFetcher } from 'react-router';
+import type { LatLngTuple } from 'leaflet';
+import useDebouncedValue from '../../../../../hooks/useDebouncedValue';
+import type { SimplifiedBrewery } from '../../../breweries.server';
+import type { loader as nearbyLoader } from '../../../routes/resources/breweries-nearby';
+import type { DistanceUnit } from '../../../utils/distance';
+import ChangeLocationButton from './controls/ChangeLocationButton';
+import RadiusUnitControls from './controls/RadiusUnitControls';
+import NearbyBreweriesHeader from './header/NearbyBreweriesHeader';
+import NearbyBreweryList from './list/NearbyBreweryList';
+import ClientOnlyMap, { MAP_PLACEHOLDER_CLASS } from './map/ClientOnlyMap';
+import type { NearbyMapPin } from './map/NearbyBreweryMap';
+
+const NearbyBreweryMap = lazy(() => import('./map/NearbyBreweryMap'));
+
+const DEFAULT_RADIUS_KM = 120;
+const RADIUS_DEBOUNCE_MS = 300;
+
+export interface FeaturedPin {
+    id: string;
+    name: string;
+    latitude: number;
+    longitude: number;
+}
+
+interface FallbackCenter {
+    latitude: number;
+    longitude: number;
+    label: string;
+}
+
+interface NearbyBreweriesSectionProps {
+    featured: FeaturedPin | null;
+    fallbackCenter: FallbackCenter | null;
+    selectedId: string | null;
+    onSelect: (id: string) => void;
+}
+
+const NearbyBreweriesSection = ({
+    featured,
+    fallbackCenter,
+    selectedId,
+    onSelect,
+}: NearbyBreweriesSectionProps) => {
+    const [userLocation, setUserLocation] = useState<LatLngTuple | null>(null);
+    const [locationLabel, setLocationLabel] = useState('your location');
+    const [geoAttempted, setGeoAttempted] = useState(false);
+    const [radiusKm, setRadiusKm] = useState(DEFAULT_RADIUS_KM);
+    const debouncedRadiusKm = useDebouncedValue(radiusKm, RADIUS_DEBOUNCE_MS);
+    const [unit, setUnit] = useState<DistanceUnit>('km');
+    const fetcher = useFetcher<typeof nearbyLoader>();
+
+    const requestGeolocation = () => {
+        if (!navigator.geolocation) {
+            Promise.resolve().then(() => setGeoAttempted(true));
+            return;
+        }
+        navigator.geolocation.getCurrentPosition(
+            (pos) => {
+                setUserLocation([pos.coords.latitude, pos.coords.longitude]);
+                setLocationLabel('your location');
+                setGeoAttempted(true);
+            },
+            () => setGeoAttempted(true),
+            { enableHighAccuracy: true },
+        );
+    };
+
+    useEffect(() => {
+        requestGeolocation();
+    }, []);
+
+    const center: LatLngTuple | null =
+        userLocation ??
+        (geoAttempted && fallbackCenter
+            ? [fallbackCenter.latitude, fallbackCenter.longitude]
+            : null);
+    const centerLabel = userLocation ? locationLabel : (fallbackCenter?.label ?? locationLabel);
+
+    useEffect(() => {
+        if (!center) return;
+        fetcher.load(
+            `/breweries/nearby?latitude=${center[0]}&longitude=${center[1]}&rangeInMetres=${debouncedRadiusKm * 1000}`,
+        );
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [center?.[0], center?.[1], debouncedRadiusKm]);
+
+    const nearby: SimplifiedBrewery[] = fetcher.data?.breweries ?? [];
+    const withDistance = center
+        ? nearby
+              .filter((b) => b.location?.coordinates && b.distanceMetres !== null)
+              .map((b) => ({
+                  brewery: b,
+                  distanceMetres: b.distanceMetres as number,
+              }))
+              .sort((a, b) => a.distanceMetres - b.distanceMetres)
+        : [];
+
+    const pins: NearbyMapPin[] = withDistance.map(({ brewery }) => ({
+        id: brewery.breweryPostId,
+        name: brewery.breweryName,
+        cityLabel: brewery.location
+            ? `${brewery.location.cityName}, ${brewery.location.stateProvinceCode}`
+            : null,
+        latitude: brewery.location!.coordinates!.latitude,
+        longitude: brewery.location!.coordinates!.longitude,
+    }));
+    if (featured && !pins.some((p) => p.id === featured.id)) {
+        pins.push({
+            id: featured.id,
+            name: featured.name,
+            cityLabel: null,
+            latitude: featured.latitude,
+            longitude: featured.longitude,
+        });
+    }
+
+    return (
+        <section id="breweries-near-you" className="max-w-7xl mx-auto px-5 pt-11">
+            <NearbyBreweriesHeader
+                center={center}
+                withDistance={withDistance}
+                radiusKm={radiusKm}
+                unit={unit}
+                centerLabel={centerLabel}
+            />
+
+            <div className="grid gap-5 items-stretch md:grid-cols-[22rem_1fr]">
+                <div className="flex flex-col gap-3 order-2 md:order-1">
+                    <RadiusUnitControls
+                        radiusKm={radiusKm}
+                        unit={unit}
+                        onRadiusChange={(e) => setRadiusKm(Number(e.target.value))}
+                        onSelectKm={() => setUnit('km')}
+                        onSelectMi={() => setUnit('mi')}
+                    />
+                    <NearbyBreweryList
+                        withDistance={withDistance}
+                        center={center}
+                        radiusKm={radiusKm}
+                        unit={unit}
+                        selectedId={selectedId}
+                        onSelect={onSelect}
+                    />
+                    <ChangeLocationButton onClick={requestGeolocation} />
+                </div>
+
+                <div className="order-1 md:order-2">
+                    <ClientOnlyMap
+                        render={() =>
+                            center ? (
+                                <Suspense fallback={<div className={MAP_PLACEHOLDER_CLASS} />}>
+                                    <NearbyBreweryMap
+                                        pins={pins}
+                                        selectedId={selectedId}
+                                        onSelect={onSelect}
+                                        userLocation={userLocation}
+                                        userLocationLabel={centerLabel}
+                                    />
+                                </Suspense>
+                            ) : (
+                                <div className={MAP_PLACEHOLDER_CLASS} />
+                            )
+                        }
+                    />
+                </div>
+            </div>
+        </section>
+    );
+};
+
+export default NearbyBreweriesSection;
--- a/web/frontend/app/features/breweries/components/overview/nearby/controls/ChangeLocationButton.tsx
+++ b/web/frontend/app/features/breweries/components/overview/nearby/controls/ChangeLocationButton.tsx
@@ -0,0 +1,15 @@
+interface ChangeLocationButtonProps {
+    onClick: () => void;
+}
+
+const ChangeLocationButton = ({ onClick }: ChangeLocationButtonProps) => {
+    return (
+        <div className="pt-1">
+            <button type="button" onClick={onClick} className="btn btn-ghost btn-sm">
+                Change location
+            </button>
+        </div>
+    );
+};
+
+export default ChangeLocationButton;
--- a/web/frontend/app/features/breweries/components/overview/nearby/controls/RadiusUnitControls.tsx
+++ b/web/frontend/app/features/breweries/components/overview/nearby/controls/RadiusUnitControls.tsx
@@ -0,0 +1,59 @@
+import { formatDistance, type DistanceUnit } from '../../../../utils/distance';
+
+const MIN_RADIUS_KM = 10;
+const MAX_RADIUS_KM = 300;
+const RADIUS_STEP_KM = 10;
+
+interface RadiusUnitControlsProps {
+    radiusKm: number;
+    unit: DistanceUnit;
+    onRadiusChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
+    onSelectKm: () => void;
+    onSelectMi: () => void;
+}
+
+const RadiusUnitControls = ({
+    radiusKm,
+    unit,
+    onRadiusChange,
+    onSelectKm,
+    onSelectMi,
+}: RadiusUnitControlsProps) => {
+    return (
+        <div className="flex items-center justify-between gap-3">
+            <label className="flex-1 flex flex-col gap-1 text-sm text-base-content/70">
+                <span className="flex justify-between">
+                    <span>Search radius</span>
+                    <span className="font-semibold">{formatDistance(radiusKm * 1000, unit)}</span>
+                </span>
+                <input
+                    type="range"
+                    min={MIN_RADIUS_KM}
+                    max={MAX_RADIUS_KM}
+                    step={RADIUS_STEP_KM}
+                    value={radiusKm}
+                    onChange={onRadiusChange}
+                    className="range range-primary range-sm"
+                />
+            </label>
+            <div className="join self-end">
+                <button
+                    type="button"
+                    onClick={onSelectKm}
+                    className={`btn btn-xs join-item ${unit === 'km' ? 'btn-active' : ''}`}
+                >
+                    km
+                </button>
+                <button
+                    type="button"
+                    onClick={onSelectMi}
+                    className={`btn btn-xs join-item ${unit === 'mi' ? 'btn-active' : ''}`}
+                >
+                    mi
+                </button>
+            </div>
+        </div>
+    );
+};
+
+export default RadiusUnitControls;
--- a/web/frontend/app/features/breweries/components/overview/nearby/header/NearbyBreweriesHeader.tsx
+++ b/web/frontend/app/features/breweries/components/overview/nearby/header/NearbyBreweriesHeader.tsx
@@ -0,0 +1,32 @@
+import type { LatLngTuple } from 'leaflet';
+import { formatDistance, type DistanceUnit } from '../../../../utils/distance';
+import type { BreweryWithDistance } from '../types';
+
+interface NearbyBreweriesHeaderProps {
+    center: LatLngTuple | null;
+    withDistance: BreweryWithDistance[];
+    radiusKm: number;
+    unit: DistanceUnit;
+    centerLabel: string;
+}
+
+const NearbyBreweriesHeader = ({
+    center,
+    centerLabel,
+    radiusKm,
+    unit,
+    withDistance,
+}: NearbyBreweriesHeaderProps) => {
+    return (
+        <div className="flex items-baseline justify-between gap-4 flex-wrap mb-3.5">
+            <h2 className="font-serif text-2xl m-0">Breweries near you</h2>
+            <span className="text-sm text-base-content/60">
+                {center
+                    ? `${withDistance.length} within ${formatDistance(radiusKm * 1000, unit)} of ${centerLabel}`
+                    : 'Finding breweries near you…'}
+            </span>
+        </div>
+    );
+};
+
+export default NearbyBreweriesHeader;
--- a/web/frontend/app/features/breweries/components/overview/nearby/list/NearbyBreweryList.tsx
+++ b/web/frontend/app/features/breweries/components/overview/nearby/list/NearbyBreweryList.tsx
@@ -0,0 +1,44 @@
+import type { LatLngTuple } from 'leaflet';
+import { formatDistance, type DistanceUnit } from '../../../../utils/distance';
+import type { BreweryWithDistance } from '../types';
+import NearbyBreweryListItem from './NearbyBreweryListItem';
+
+interface NearbyBreweryListProps {
+    withDistance: BreweryWithDistance[];
+    center: LatLngTuple | null;
+    radiusKm: number;
+    unit: DistanceUnit;
+    selectedId: string | null;
+    onSelect: (id: string) => void;
+}
+
+const NearbyBreweryList = ({
+    withDistance,
+    center,
+    radiusKm,
+    unit,
+    selectedId,
+    onSelect,
+}: NearbyBreweryListProps) => {
+    return (
+        <>
+            {withDistance.length === 0 && center && (
+                <p className="text-sm text-base-content/60">
+                    No partner breweries within {formatDistance(radiusKm * 1000, unit)}.
+                </p>
+            )}
+            {withDistance.map(({ brewery, distanceMetres }) => (
+                <NearbyBreweryListItem
+                    key={brewery.breweryPostId}
+                    brewery={brewery}
+                    distanceMetres={distanceMetres}
+                    unit={unit}
+                    selected={selectedId === brewery.breweryPostId}
+                    onSelect={onSelect}
+                />
+            ))}
+        </>
+    );
+};
+
+export default NearbyBreweryList;
--- a/web/frontend/app/features/breweries/components/overview/nearby/list/NearbyBreweryListItem.tsx
+++ b/web/frontend/app/features/breweries/components/overview/nearby/list/NearbyBreweryListItem.tsx
@@ -0,0 +1,49 @@
+import type { SimplifiedBrewery } from '../../../../breweries.server';
+import { formatDistance, type DistanceUnit } from '../../../../utils/distance';
+
+// Notes aren't tracked on brewery locations yet - see BREWERY_HANDOFF.md.
+const FILLER_NOTE = 'A stop worth the detour.';
+
+const cardClassName = (selected: boolean) =>
+    `card card-sm card-border bg-base-100 text-left shadow transition-shadow hover:shadow-lg ${
+        selected ? 'border-2 border-primary' : ''
+    }`;
+
+interface NearbyBreweryListItemProps {
+    brewery: SimplifiedBrewery;
+    distanceMetres: number;
+    unit: DistanceUnit;
+    selected: boolean;
+    onSelect: (id: string) => void;
+}
+
+const NearbyBreweryListItem = ({
+    brewery,
+    distanceMetres,
+    unit,
+    selected,
+    onSelect,
+}: NearbyBreweryListItemProps) => (
+    <button
+        type="button"
+        onClick={() => onSelect(brewery.breweryPostId)}
+        className={cardClassName(selected)}
+    >
+        <div className="card-body">
+            <div className="flex justify-between items-baseline gap-3">
+                <h3 className="card-title font-serif text-lg">{brewery.breweryName}</h3>
+                <span className="text-sm font-semibold text-primary whitespace-nowrap">
+                    {formatDistance(distanceMetres, unit)}
+                </span>
+            </div>
+            {brewery.location && (
+                <div className="text-sm text-base-content/60">
+                    {brewery.location.cityName}, {brewery.location.stateProvinceCode}
+                </div>
+            )}
+            <div className="text-sm mt-2">{FILLER_NOTE}</div>
+        </div>
+    </button>
+);
+
+export default NearbyBreweryListItem;
--- a/web/frontend/app/features/breweries/components/overview/nearby/map/ClientOnlyMap.tsx
+++ b/web/frontend/app/features/breweries/components/overview/nearby/map/ClientOnlyMap.tsx
@@ -0,0 +1,14 @@
+import ClientOnly from '../../../../../../components/ClientOnly';
+
+const MAP_PLACEHOLDER_CLASS = 'skeleton min-h-[30rem] h-full w-full rounded-box';
+
+interface ClientOnlyMapProps {
+    render: () => React.JSX.Element;
+}
+
+const ClientOnlyMap = ({ render }: ClientOnlyMapProps) => {
+    return <ClientOnly fallback={<div className={MAP_PLACEHOLDER_CLASS} />}>{render}</ClientOnly>;
+};
+
+export default ClientOnlyMap;
+export { MAP_PLACEHOLDER_CLASS };
--- a/web/frontend/app/features/breweries/components/overview/nearby/map/NearbyBreweryMap.stories.tsx
+++ b/web/frontend/app/features/breweries/components/overview/nearby/map/NearbyBreweryMap.stories.tsx
@@ -0,0 +1,64 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import NearbyBreweryMap, { type NearbyMapPin } from './NearbyBreweryMap';
+
+const nearbyBreweryMapDescription = `Leaflet map of nearby-brewery pins used inside NearbyBreweriesSection. Smoke-render only - this hits the real OpenStreetMap tile server in the browser test run. Wrapped in a fixed-height container here since its \`h-full\` class normally relies on a CSS grid ancestor that this story doesn't provide.`;
+
+const pins: NearbyMapPin[] = [
+    {
+        id: 'brewery-close',
+        name: 'Close Quarters Brewing',
+        cityLabel: 'Portland, OR',
+        latitude: 45.52,
+        longitude: -122.68,
+    },
+    {
+        id: 'brewery-mid',
+        name: 'Midrange Malts',
+        cityLabel: 'Salem, OR',
+        latitude: 44.94,
+        longitude: -123.03,
+    },
+];
+
+const meta = {
+    title: 'Breweries/NearbyBreweryMap',
+    component: NearbyBreweryMap,
+    decorators: [
+        (Story) => (
+            <div className="h-[32rem]">
+                <Story />
+            </div>
+        ),
+    ],
+    parameters: {
+        layout: 'padded',
+        docs: {
+            description: {
+                component: nearbyBreweryMapDescription,
+            },
+        },
+    },
+} satisfies Meta<typeof NearbyBreweryMap>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+    args: {
+        pins,
+        selectedId: null,
+        onSelect: () => undefined,
+        userLocation: [45.5152, -122.6784],
+        userLocationLabel: 'your location',
+    },
+};
+
+export const WithoutUserLocation: Story = {
+    args: {
+        pins,
+        selectedId: null,
+        onSelect: () => undefined,
+        userLocation: null,
+        userLocationLabel: 'your location',
+    },
+};
--- a/web/frontend/app/features/breweries/components/overview/nearby/map/NearbyBreweryMap.tsx
+++ b/web/frontend/app/features/breweries/components/overview/nearby/map/NearbyBreweryMap.tsx
@@ -0,0 +1,159 @@
+import { useEffect, useRef } from 'react';
+import { MapContainer, TileLayer, Marker, Popup, CircleMarker, useMap } from 'react-leaflet';
+import L, { type LatLngTuple } from 'leaflet';
+import 'leaflet/dist/leaflet.css';
+
+const DEFAULT_ZOOM = 11;
+const MIN_ZOOM = 8;
+
+export interface NearbyMapPin {
+    id: string;
+    name: string;
+    cityLabel: string | null;
+    latitude: number;
+    longitude: number;
+}
+
+interface NearbyBreweryMapProps {
+    pins: NearbyMapPin[];
+    selectedId: string | null;
+    onSelect: (id: string) => void;
+    userLocation: LatLngTuple | null;
+    userLocationLabel: string;
+}
+
+// Leaflet paints markers as SVG attributes, which can't reference CSS custom
+// properties the way class names can - resolve the current theme's colors instead.
+const resolveThemeColor = (variable: string, fallback: string) => {
+    if (typeof document === 'undefined') return fallback;
+    const value = getComputedStyle(document.documentElement).getPropertyValue(variable).trim();
+    return value || fallback;
+};
+
+const pinIcon = (active: boolean) =>
+    L.divIcon({
+        className: '',
+        html: `<span class="block h-[18px] w-[18px] rounded-full border-[3px] border-base-100 shadow-[0_1px_4px_rgba(0,0,0,.35)] ${
+            active ? 'bg-secondary scale-125' : 'bg-primary'
+        }"></span>`,
+        iconSize: [18, 18],
+        iconAnchor: [9, 9],
+    });
+
+const FitAndFocus = ({
+    pins,
+    userLocation,
+    selectedId,
+}: {
+    pins: NearbyMapPin[];
+    userLocation: LatLngTuple | null;
+    selectedId: string | null;
+}) => {
+    const map = useMap();
+    const didInitialFit = useRef(false);
+
+    useEffect(() => {
+        if (didInitialFit.current) return;
+        const focus: LatLngTuple | null =
+            userLocation ?? (pins[0] ? [pins[0].latitude, pins[0].longitude] : null);
+        if (focus) {
+            map.setView(focus, DEFAULT_ZOOM, { animate: false });
+            didInitialFit.current = true;
+        }
+        const timeout = setTimeout(() => map.invalidateSize(), 200);
+        return () => clearTimeout(timeout);
+    }, [map, pins, userLocation]);
+
+    useEffect(() => {
+        if (!didInitialFit.current || !selectedId) return;
+        const pin = pins.find((p) => p.id === selectedId);
+        if (!pin) return;
+        map.flyTo([pin.latitude, pin.longitude], Math.max(map.getZoom(), 11), { duration: 0.8 });
+    }, [map, pins, selectedId]);
+
+    return null;
+};
+
+const RecenterButton = ({ userLocation }: { userLocation: LatLngTuple | null }) => {
+    const map = useMap();
+    if (!userLocation) return null;
+    return (
+        <button
+            type="button"
+            onClick={() => map.setView(userLocation, DEFAULT_ZOOM, { animate: true })}
+            className="btn btn-circle btn-sm bg-base-100 absolute top-2.5 right-2.5 z-[1000] shadow"
+            aria-label="Recenter on your location"
+        >
+            <svg
+                xmlns="http://www.w3.org/2000/svg"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                className="h-4 w-4"
+            >
+                <circle cx="12" cy="12" r="3" />
+                <path d="M12 2v3M12 19v3M2 12h3M19 12h3" />
+            </svg>
+        </button>
+    );
+};
+
+const NearbyBreweryMap = ({
+    pins,
+    selectedId,
+    onSelect,
+    userLocation,
+    userLocationLabel,
+}: NearbyBreweryMapProps) => (
+    <MapContainer
+        center={userLocation ?? [pins[0]?.latitude ?? 20, pins[0]?.longitude ?? 0]}
+        zoom={DEFAULT_ZOOM}
+        minZoom={MIN_ZOOM}
+        scrollWheelZoom={false}
+        className="min-h-[30rem] h-full w-full rounded-box relative z-0"
+    >
+        <TileLayer
+            attribution='&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
+            url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"
+        />
+        <FitAndFocus pins={pins} userLocation={userLocation} selectedId={selectedId} />
+        <RecenterButton userLocation={userLocation} />
+        {userLocation && (
+            <CircleMarker
+                center={userLocation}
+                radius={6}
+                pathOptions={{
+                    color: resolveThemeColor('--color-base-100', '#fff'),
+                    weight: 2,
+                    fillColor: resolveThemeColor('--color-primary', '#2b6cb0'),
+                    fillOpacity: 1,
+                }}
+            >
+                <Popup>You are here &mdash; {userLocationLabel}</Popup>
+            </CircleMarker>
+        )}
+        {pins.map((pin) => (
+            <Marker
+                key={pin.id}
+                position={[pin.latitude, pin.longitude]}
+                icon={pinIcon(pin.id === selectedId)}
+                eventHandlers={{ click: () => onSelect(pin.id) }}
+            >
+                <Popup>
+                    <p className="font-semibold font-serif">{pin.name}</p>
+                    {pin.cityLabel && (
+                        <p className="text-sm text-base-content/70">{pin.cityLabel}</p>
+                    )}
+                    <a href={`/breweries/${pin.id}`} className="link link-primary text-sm">
+                        View brewery &rarr;
+                    </a>
+                </Popup>
+            </Marker>
+        ))}
+    </MapContainer>
+);
+
+export default NearbyBreweryMap;
--- a/web/frontend/app/features/breweries/components/overview/nearby/types.ts
+++ b/web/frontend/app/features/breweries/components/overview/nearby/types.ts
@@ -0,0 +1,6 @@
+import type { SimplifiedBrewery } from '../../../breweries.server';
+
+export interface BreweryWithDistance {
+    brewery: SimplifiedBrewery;
+    distanceMetres: number;
+}
--- a/web/frontend/app/features/breweries/components/shared/SidebarCard.stories.tsx
+++ b/web/frontend/app/features/breweries/components/shared/SidebarCard.stories.tsx
@@ -0,0 +1,34 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, within } from 'storybook/test';
+import SidebarCard from './SidebarCard';
+
+const sidebarCardDescription = `Shared card shell used by the brewery detail page's sidebar sections (Location, Details, Beer styles, Community) — an uppercase eyebrow label over arbitrary content.`;
+
+const meta = {
+    title: 'Breweries/SidebarCard',
+    component: SidebarCard,
+    tags: ['autodocs'],
+    parameters: {
+        layout: 'padded',
+        docs: {
+            description: {
+                component: sidebarCardDescription,
+            },
+        },
+    },
+} satisfies Meta<typeof SidebarCard>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+    args: {
+        title: 'Details',
+        children: <p className="text-sm m-0">Founded 2014</p>,
+    },
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await expect(canvas.getByText('Details')).toBeInTheDocument();
+        await expect(canvas.getByText('Founded 2014')).toBeInTheDocument();
+    },
+};
--- a/web/frontend/app/features/breweries/components/shared/SidebarCard.tsx
+++ b/web/frontend/app/features/breweries/components/shared/SidebarCard.tsx
@@ -0,0 +1,19 @@
+import type { ReactNode } from 'react';
+
+interface SidebarCardProps {
+    title: string;
+    children: ReactNode;
+}
+
+const SidebarCard = ({ title, children }: SidebarCardProps) => (
+    <div className="card bg-base-100 shadow">
+        <div className="card-body gap-3 p-6">
+            <p className="text-xs font-bold uppercase tracking-widest text-base-content/50 m-0">
+                {title}
+            </p>
+            {children}
+        </div>
+    </div>
+);
+
+export default SidebarCard;
--- a/web/frontend/app/features/breweries/components/shared/StarRating.stories.tsx
+++ b/web/frontend/app/features/breweries/components/shared/StarRating.stories.tsx
@@ -0,0 +1,49 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, fn, userEvent, within } from 'storybook/test';
+import StarRating from './StarRating';
+
+const starRatingDescription = `Dual-purpose star control built on daisyUI's \`rating\` component. Read-only (no \`onChange\`) when used for an average or a display rating; interactive otherwise — clicking the currently-selected star clears the rating, since daisyUI radios can't do that natively.`;
+
+const meta = {
+    title: 'Breweries/StarRating',
+    component: StarRating,
+    tags: ['autodocs'],
+    parameters: {
+        layout: 'centered',
+        docs: {
+            description: {
+                component: starRatingDescription,
+            },
+        },
+    },
+} satisfies Meta<typeof StarRating>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const ReadOnly: Story = {
+    args: { value: 4, size: 'sm' },
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await expect(canvas.queryByRole('radio')).not.toBeInTheDocument();
+        await expect(canvas.getByLabelText('4 out of 5 stars')).toBeInTheDocument();
+    },
+};
+
+export const Interactive: Story = {
+    args: { value: 0, size: 'lg', onChange: fn() },
+    play: async ({ args, canvasElement }) => {
+        const canvas = within(canvasElement);
+        await userEvent.click(canvas.getByRole('radio', { name: 'Rate 3 of 5' }));
+        await expect(args.onChange).toHaveBeenCalledWith(3);
+    },
+};
+
+export const InteractiveClearsOnRepeatClick: Story = {
+    args: { value: 3, size: 'lg', onChange: fn() },
+    play: async ({ args, canvasElement }) => {
+        const canvas = within(canvasElement);
+        await userEvent.click(canvas.getByRole('radio', { name: 'Rate 3 of 5' }));
+        await expect(args.onChange).toHaveBeenCalledWith(0);
+    },
+};
--- a/web/frontend/app/features/breweries/components/shared/StarRating.tsx
+++ b/web/frontend/app/features/breweries/components/shared/StarRating.tsx
@@ -0,0 +1,71 @@
+import { useId } from 'react';
+
+interface StarRatingProps {
+    value: number;
+    max?: number;
+    size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    onChange?: (value: number) => void;
+    label?: string;
+}
+
+const SIZE_CLASS: Record<NonNullable<StarRatingProps['size']>, string> = {
+    xs: 'rating-xs',
+    sm: 'rating-sm',
+    md: 'rating-md',
+    lg: 'rating-lg',
+    xl: 'rating-xl',
+};
+
+/** Read-only when `onChange` is omitted, interactive otherwise. Clicking the
+ * currently-selected star clears the rating (daisyUI radios can't do this natively). */
+const StarRating = ({ value, max = 5, size = 'sm', onChange, label }: StarRatingProps) => {
+    const name = useId();
+    const stars = Array.from({ length: max }, (_, i) => i + 1);
+
+    if (!onChange) {
+        return (
+            <div
+                className={`rating ${SIZE_CLASS[size]}`}
+                aria-label={label ?? `${value} out of ${max} stars`}
+            >
+                {stars.map((n) => (
+                    <div
+                        key={n}
+                        className="mask mask-star bg-warning"
+                        aria-label={`${n} star`}
+                        aria-current={n === value ? 'true' : undefined}
+                    />
+                ))}
+            </div>
+        );
+    }
+
+    return (
+        <div className={`rating ${SIZE_CLASS[size]}`}>
+            <input
+                type="radio"
+                name={name}
+                className="rating-hidden"
+                checked={value === 0}
+                onChange={() => onChange(0)}
+                aria-label="Clear rating"
+            />
+            {stars.map((n) => (
+                <input
+                    key={n}
+                    type="radio"
+                    name={name}
+                    className="mask mask-star bg-warning"
+                    checked={value === n}
+                    onChange={() => onChange(n)}
+                    onClick={() => {
+                        if (value === n) onChange(0);
+                    }}
+                    aria-label={`Rate ${n} of ${max}`}
+                />
+            ))}
+        </div>
+    );
+};
+
+export default StarRating;
--- a/web/frontend/app/features/breweries/routes/breweries.tsx
+++ b/web/frontend/app/features/breweries/routes/breweries.tsx
@@ -1,38 +1,101 @@
+import { useState } from 'react';
+import { Link } from 'react-router';
 import RouteErrorState from '../../../components/ui/error/RouteErrorState';
-import BreweryCard from '../components/BreweryCard';
+import FeaturedBreweryCard from '../components/overview/FeaturedBreweryCard';
+import NearbyBreweriesSection from '../components/overview/nearby/NearbyBreweriesSection';
+import RecentBreweries from '../components/overview/RecentBreweries';
 import { getBreweries } from '../breweries.server';
 import type { Route } from './+types/breweries';

+// No count endpoint exists yet - see BREWERY_HANDOFF.md.
+const FILLER_TOTAL_BREWERY_COUNT = 128;
+
 export const meta = ({}: Route.MetaArgs) => {
    return [{ title: 'Breweries | The Biergarten App' }];
 };

 export const loader = async () => {
-    const breweries = await getBreweries();
-    return { breweries };
+    // "Featured" is just the most recently posted brewery for now - see BREWERY_HANDOFF.md.
+    const [featured, ...recent] = await getBreweries(4, 0);
+    return { featured: featured ?? null, recent };
 };

 const Breweries = ({ loaderData }: Route.ComponentProps) => {
-    const { breweries } = loaderData;
+    const { featured, recent } = loaderData;
+    const [selectedId, setSelectedId] = useState<string | null>(null);
+
+    const featuredPin = featured?.location?.coordinates
+        ? {
+              id: featured.breweryPostId,
+              name: featured.breweryName,
+              latitude: featured.location.coordinates.latitude,
+              longitude: featured.location.coordinates.longitude,
+          }
+        : null;
+
+    const fallbackCenter = featured?.location?.coordinates
+        ? {
+              latitude: featured.location.coordinates.latitude,
+              longitude: featured.location.coordinates.longitude,
+              label: featured.location.cityName,
+          }
+        : null;

    return (
-        <div className="min-h-screen bg-base-200">
-            <div className="container mx-auto p-4">
-                <h1 className="text-4xl font-bold mb-4">Breweries</h1>
-                <p className="text-base-content/70 mb-6">Discover our partner breweries.</p>
-
-                {breweries.length === 0 ? (
-                    <div className="alert alert-info alert-soft">
-                        <span>No breweries have been posted yet.</span>
-                    </div>
-                ) : (
-                    <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
-                        {breweries.map((brewery) => (
-                            <BreweryCard key={brewery.breweryPostId} brewery={brewery} />
-                        ))}
-                    </div>
-                )}
+        <div className="min-h-screen bg-base-200 text-base-content pb-16">
+            <div className="max-w-7xl mx-auto px-5 pt-10">
+                <h1 className="font-serif text-5xl leading-tight mb-2">Breweries</h1>
+                <p className="text-lg text-base-content/60 max-w-xl m-0">
+                    Discover our partner breweries — start with this week&apos;s feature, then see
+                    what&apos;s pouring near you.
+                </p>
            </div>
+
+            {featured && (
+                <section className="max-w-7xl mx-auto px-5 pt-8">
+                    <div className="flex items-baseline gap-3 mb-3.5">
+                        <h2 className="font-serif text-2xl m-0">Featured brewery</h2>
+                        <span className="badge badge-primary badge-sm uppercase tracking-widest font-bold">
+                            This week
+                        </span>
+                    </div>
+                    <FeaturedBreweryCard
+                        brewery={featured}
+                        onShowOnMap={() => {
+                            setSelectedId(featured.breweryPostId);
+                            document
+                                .getElementById('breweries-near-you')
+                                ?.scrollIntoView({ behavior: 'smooth' });
+                        }}
+                    />
+                </section>
+            )}
+
+            <NearbyBreweriesSection
+                featured={featuredPin}
+                fallbackCenter={fallbackCenter}
+                selectedId={selectedId}
+                onSelect={setSelectedId}
+            />
+
+            <RecentBreweries breweries={recent} />
+
+            <section className="max-w-7xl mx-auto px-5 pt-11">
+                <div className="bg-[var(--color-highlight)] text-[var(--color-highlight-content)] rounded-box p-7 flex items-center justify-between gap-6 flex-wrap">
+                    <div>
+                        <h2 className="font-serif text-2xl mb-1">
+                            Looking for something specific?
+                        </h2>
+                        <p className="m-0">
+                            All {FILLER_TOTAL_BREWERY_COUNT} partner breweries, filterable by
+                            country, region, and beer style.
+                        </p>
+                    </div>
+                    <Link to="/breweries/directory" className="btn btn-primary">
+                        Browse the full directory
+                    </Link>
+                </div>
+            </section>
        </div>
    );
 };
--- a/web/frontend/app/features/breweries/routes/brewery-detail.tsx
+++ b/web/frontend/app/features/breweries/routes/brewery-detail.tsx
@@ -1,55 +1,132 @@
+import { useState } from 'react';
 import { data, Link } from 'react-router';
 import RouteErrorState from '../../../components/ui/error/RouteErrorState';
+import { getOptionalAuth } from '../../auth/auth.server';
 import { getBreweryById } from '../breweries.server';
+import BreweryHeaderCard from '../components/detail/BreweryHeaderCard';
+import YourRatingCard from '../components/detail/YourRatingCard';
+import BeerListCard from '../components/detail/BeerListCard';
+import CommentsCard from '../components/detail/comments/CommentsCard';
+import LocationCard from '../components/detail/LocationCard';
+import BreweryDetailsCard from '../components/detail/BreweryDetailsCard';
+import BeerStyleBreakdownCard from '../components/detail/BeerStyleBreakdownCard';
+import CommunityStatsCard from '../components/detail/CommunityStatsCard';
+import { FILLER_BEERS, FILLER_BREWERY_META, FILLER_COMMENTS } from '../utils/filler-brewery-detail';
 import type { Route } from './+types/brewery-detail';

-export const loader = async ({ params }: Route.LoaderArgs) => {
-    const brewery = await getBreweryById(params.id);
+export const loader = async ({ request, params }: Route.LoaderArgs) => {
+    const [brewery, auth] = await Promise.all([
+        getBreweryById(params.id),
+        getOptionalAuth(request),
+    ]);
+
    if (!brewery) {
        throw data('Brewery not found.', { status: 404, statusText: 'Not Found' });
    }

-    return { brewery };
+    return {
+        brewery,
+        loggedIn: auth !== null,
+        username: auth?.username ?? null,
+    };
 };

+const initials = (username: string) => username.slice(0, 2).toUpperCase();
+
 const BreweryDetail = ({ loaderData }: Route.ComponentProps) => {
-    const { brewery } = loaderData;
+    const { brewery, loggedIn, username } = loaderData;
+
+    const [liked, setLiked] = useState(false);
+    const [likeCount, setLikeCount] = useState(FILLER_BREWERY_META.likeCount);
+    const [yourRating, setYourRating] = useState(0);
+    const [ratingsCount, setRatingsCount] = useState(FILLER_BREWERY_META.ratingsCount);
+    const [comments, setComments] = useState(FILLER_COMMENTS);
+
+    const handleToggleLike = () => {
+        setLiked((prev) => !prev);
+        setLikeCount((prev) => prev + (liked ? -1 : 1));
+    };
+
+    const handleRatingChange = (next: number) => {
+        setRatingsCount((prev) => prev + (next === 0 ? -1 : yourRating === 0 ? 1 : 0));
+        setYourRating(next);
+    };
+
+    const handleAddComment = (text: string) => {
+        setComments((prev) => [
+            {
+                id: crypto.randomUUID(),
+                user: username ?? 'you',
+                initials: username ? initials(username) : 'YO',
+                rating: yourRating,
+                time: 'just now',
+                text,
+                likes: 0,
+                liked: false,
+            },
+            ...prev,
+        ]);
+    };
+
+    const handleToggleCommentLike = (id: string) => {
+        setComments((prev) =>
+            prev.map((comment) =>
+                comment.id === id ? { ...comment, liked: !comment.liked } : comment,
+            ),
+        );
+    };

    return (
        <div className="min-h-screen bg-base-200">
-            <div className="container mx-auto p-4 max-w-2xl">
+            <div className="max-w-4xl mx-auto px-6 pt-8 pb-16">
                <Link
                    to="/breweries"
                    className="link link-hover text-sm text-base-content/60 mb-4 inline-block"
                >
-                    &larr; Back to Breweries
+                    &larr; Back to breweries
                </Link>

-                <div className="card bg-base-100 shadow">
-                    <div className="card-body">
-                        <h1 className="card-title text-3xl">{brewery.breweryName}</h1>
-                        <p className="text-base-content/70 whitespace-pre-line">
-                            {brewery.description}
-                        </p>
+                <div className="grid grid-cols-1 lg:grid-cols-[1fr_19rem] gap-5 items-start">
+                    <div className="flex flex-col gap-5">
+                        <BreweryHeaderCard
+                            brewery={brewery}
+                            foundedYear={FILLER_BREWERY_META.foundedYear}
+                            liked={liked}
+                            likeCount={likeCount}
+                            avgRating={FILLER_BREWERY_META.avgRating}
+                            ratingsCount={ratingsCount}
+                            onToggleLike={handleToggleLike}
+                        />
+                        <YourRatingCard value={yourRating} onChange={handleRatingChange} />
+                        <BeerListCard beers={FILLER_BEERS} />
+                        <CommentsCard
+                            comments={comments}
+                            loggedIn={loggedIn}
+                            currentUserInitials={username ? initials(username) : 'YO'}
+                            onAddComment={handleAddComment}
+                            onToggleCommentLike={handleToggleCommentLike}
+                        />
+                    </div>

+                    <div className="flex flex-col gap-5">
                        {brewery.location && (
-                            <div className="bg-base-200 rounded-box p-4 mt-4">
-                                <p className="text-xs font-semibold uppercase tracking-widest text-base-content/50 mb-2">
-                                    Location
-                                </p>
-                                <p>{brewery.location.addressLine1}</p>
-                                {brewery.location.addressLine2 && (
-                                    <p>{brewery.location.addressLine2}</p>
-                                )}
-                                <p>{brewery.location.postalCode}</p>
-                            </div>
+                            <LocationCard
+                                breweryName={brewery.breweryName}
+                                location={brewery.location}
+                                website={FILLER_BREWERY_META.website}
+                            />
                        )}
-
-                        <p className="text-xs text-base-content/40 mt-4">
-                            Posted {new Date(brewery.createdAt).toLocaleDateString()}
-                            {brewery.updatedAt &&
-                                ` · Updated ${new Date(brewery.updatedAt).toLocaleDateString()}`}
-                        </p>
+                        <BreweryDetailsCard
+                            foundedYear={FILLER_BREWERY_META.foundedYear}
+                            type={FILLER_BREWERY_META.type}
+                            beerCount={FILLER_BEERS.length}
+                        />
+                        <BeerStyleBreakdownCard beers={FILLER_BEERS} />
+                        <CommunityStatsCard
+                            likeCount={likeCount}
+                            ratingsCount={ratingsCount}
+                            commentCount={comments.length}
+                        />
                    </div>
                </div>
            </div>
--- a/web/frontend/app/features/breweries/routes/brewery-directory.tsx
+++ b/web/frontend/app/features/breweries/routes/brewery-directory.tsx
@@ -0,0 +1,121 @@
+import { Link } from 'react-router';
+import RouteErrorState from '../../../components/ui/error/RouteErrorState';
+import ClientOnly from '../../../components/ClientOnly';
+import BreweryCard from '../components/directory/BreweryCard';
+import { getBreweries, getBreweryLocations, type SimplifiedBrewery } from '../breweries.server';
+import type { Route } from './+types/brewery-directory';
+import { lazy, Suspense, useEffect, useRef, useState } from 'react';
+import { useFetcher } from 'react-router';
+import type { BreweryMapPin } from '../components/directory/BreweryMap';
+
+const PAGE_SIZE = 12;
+const MAP_PLACEHOLDER_CLASS = 'skeleton h-[28rem] md:h-[34rem] w-full rounded-box';
+
+export const meta = ({}: Route.MetaArgs) => {
+    return [{ title: 'Brewery Directory | The Biergarten App' }];
+};
+
+export const loader = async ({ request }: Route.LoaderArgs) => {
+    const url = new URL(request.url);
+    const limit = Number(url.searchParams.get('limit')) || PAGE_SIZE;
+    const offset = Number(url.searchParams.get('offset')) || 0;
+    const [breweries, locations] = await Promise.all([
+        getBreweries(limit, offset),
+        getBreweryLocations(),
+    ]);
+    return { breweries, locations, limit, offset };
+};
+
+const BreweryMap = lazy(() => import('../components/directory/BreweryMap'));
+
+const toPins = (breweries: SimplifiedBrewery[]): BreweryMapPin[] =>
+    breweries
+        .filter((brewery) => brewery.location?.coordinates)
+        .map((brewery) => ({
+            id: brewery.breweryPostId,
+            name: brewery.breweryName,
+            latitude: brewery.location!.coordinates!.latitude,
+            longitude: brewery.location!.coordinates!.longitude,
+            location: brewery.location,
+        }));
+
+const Breweries = ({ loaderData }: Route.ComponentProps) => {
+    const [allBreweries, setAllBreweries] = useState(loaderData.breweries);
+    const [offset, setOffset] = useState(loaderData.breweries.length);
+    const [hasMore, setHasMore] = useState(loaderData.breweries.length === loaderData.limit);
+    const [loadedPage, setLoadedPage] = useState<typeof loaderData | undefined>(undefined);
+    const fetcher = useFetcher<typeof loader>();
+    const sentinelRef = useRef<HTMLDivElement>(null);
+
+    if (fetcher.data && fetcher.data !== loadedPage) {
+        setLoadedPage(fetcher.data);
+        setAllBreweries((prev) => [...prev, ...fetcher.data!.breweries]);
+        setOffset((prev) => prev + fetcher.data!.breweries.length);
+        setHasMore(fetcher.data.breweries.length === PAGE_SIZE);
+    }
+
+    useEffect(() => {
+        const sentinel = sentinelRef.current;
+        if (!sentinel || !hasMore) return;
+
+        const observer = new IntersectionObserver((entries) => {
+            if (entries[0]?.isIntersecting && fetcher.state === 'idle') {
+                fetcher.load(`/breweries/directory?limit=${PAGE_SIZE}&offset=${offset}`);
+            }
+        });
+
+        observer.observe(sentinel);
+        return () => observer.disconnect();
+    }, [hasMore, offset, fetcher]);
+
+    const pins = toPins(loaderData.locations);
+
+    return (
+        <div className="min-h-screen bg-base-200">
+            <div className="container mx-auto p-14">
+                <Link
+                    to="/breweries"
+                    className="link link-hover text-sm text-base-content/60 mb-4 inline-block"
+                >
+                    &larr; Back to Breweries
+                </Link>
+                <h1 className="text-4xl font-bold mb-4">Full brewery directory</h1>
+                <p className="text-base-content/70 mb-6">
+                    All of our partner breweries, newest first.
+                </p>
+
+                <ClientOnly fallback={<div className={MAP_PLACEHOLDER_CLASS} />}>
+                    {() => (
+                        <Suspense fallback={<div className={MAP_PLACEHOLDER_CLASS} />}>
+                            <BreweryMap breweries={pins} />
+                        </Suspense>
+                    )}
+                </ClientOnly>
+
+                {allBreweries.length === 0 ? (
+                    <p className="text-center text-base-content/60 mt-12">
+                        No breweries found yet.
+                    </p>
+                ) : (
+                    <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4 mt-8">
+                        {allBreweries.map((brewery) => (
+                            <BreweryCard key={brewery.breweryPostId} brewery={brewery} />
+                        ))}
+                        {fetcher.state !== 'idle' &&
+                            Array.from({ length: PAGE_SIZE }).map((_, index) => (
+                                <div key={index} className="skeleton h-32 w-full rounded-box" />
+                            ))}
+                    </div>
+                )}
+
+                {hasMore && <div ref={sentinelRef} className="h-1" />}
+            </div>
+        </div>
+    );
+};
+
+export default Breweries;
+
+export const ErrorBoundary = ({ error }: Route.ErrorBoundaryProps) => (
+    <RouteErrorState error={error} />
+);
--- a/web/frontend/app/features/breweries/routes/resources/breweries-nearby.ts
+++ b/web/frontend/app/features/breweries/routes/resources/breweries-nearby.ts
@@ -0,0 +1,21 @@
+import { data } from 'react-router';
+import { getBreweryLocationsNearby } from '../../breweries.server';
+import type { Route } from './+types/breweries-nearby';
+
+export const loader = async ({ request }: Route.LoaderArgs) => {
+    const url = new URL(request.url);
+    const latitude = Number(url.searchParams.get('latitude'));
+    const longitude = Number(url.searchParams.get('longitude'));
+    const rangeInMetres = Number(url.searchParams.get('rangeInMetres'));
+
+    if (
+        !Number.isFinite(latitude) ||
+        !Number.isFinite(longitude) ||
+        !Number.isFinite(rangeInMetres)
+    ) {
+        throw data('latitude, longitude, and rangeInMetres are required.', { status: 400 });
+    }
+
+    const breweries = await getBreweryLocationsNearby(latitude, longitude, rangeInMetres);
+    return { breweries };
+};
--- a/web/frontend/app/features/breweries/utils/distance.ts
+++ b/web/frontend/app/features/breweries/utils/distance.ts
@@ -0,0 +1,9 @@
+export type DistanceUnit = 'km' | 'mi';
+
+const METRES_PER_MILE = 1609.344;
+
+export const formatDistance = (metres: number, unit: DistanceUnit = 'km'): string => {
+    const value = unit === 'mi' ? metres / METRES_PER_MILE : metres / 1000;
+    const rounded = value < 10 ? value.toFixed(1) : String(Math.round(value));
+    return `${rounded} ${unit}`;
+};
--- a/web/frontend/app/features/breweries/utils/filler-brewery-detail.ts
+++ b/web/frontend/app/features/breweries/utils/filler-brewery-detail.ts
@@ -0,0 +1,148 @@
+// see BREWERY_HANDOFF.md — filler data pending backend support for
+// beers-by-brewery, likes, ratings, comments, and brewery founded/type/website fields.
+
+export interface FillerBeer {
+    id: string;
+    name: string;
+    description: string;
+    style: string;
+    abv: number;
+    rating: number;
+}
+
+export const FILLER_BEERS: FillerBeer[] = [
+    {
+        id: '1',
+        name: 'Switchyard IPA',
+        description: 'Flagship west coast IPA, pine and grapefruit',
+        style: 'IPA',
+        abv: 6.8,
+        rating: 4,
+    },
+    {
+        id: '2',
+        name: 'Rail Spur DIPA',
+        description: 'Double dry-hopped, citra and mosaic',
+        style: 'IPA',
+        abv: 8.2,
+        rating: 5,
+    },
+    {
+        id: '3',
+        name: 'Kettle Row Hazy',
+        description: 'Soft, juicy, low bitterness',
+        style: 'IPA',
+        abv: 6.4,
+        rating: 4,
+    },
+    {
+        id: '4',
+        name: 'Flanders No. 3',
+        description: 'Barrel-aged flanders red, 18 months in oak',
+        style: 'Sour',
+        abv: 6.0,
+        rating: 5,
+    },
+    {
+        id: '5',
+        name: 'Blackberry Cassis Gose',
+        description: 'Collab with Cassis & Coal, lightly salted',
+        style: 'Sour',
+        abv: 4.6,
+        rating: 4,
+    },
+    {
+        id: '6',
+        name: 'Foudre Kriek',
+        description: 'Whole cherries, second-use barrels',
+        style: 'Sour',
+        abv: 5.4,
+        rating: 4,
+    },
+    {
+        id: '7',
+        name: 'Yard Lamp Lager',
+        description: 'Crisp helles-style lager',
+        style: 'Lager',
+        abv: 4.9,
+        rating: 4,
+    },
+    {
+        id: '8',
+        name: 'Night Shift Stout',
+        description: 'Export stout with roasted barley',
+        style: 'Stout',
+        abv: 7.1,
+        rating: 4,
+    },
+    {
+        id: '9',
+        name: 'Hefeweizen Classic',
+        description: 'Banana and clove, open fermentation',
+        style: 'Weizen',
+        abv: 5.2,
+        rating: 3,
+    },
+];
+
+export interface FillerComment {
+    id: string;
+    user: string;
+    initials: string;
+    rating: number;
+    time: string;
+    text: string;
+    likes: number;
+    liked: boolean;
+}
+
+export const FILLER_COMMENTS: FillerComment[] = [
+    {
+        id: '1',
+        user: 'malt_kettle',
+        initials: 'MK',
+        rating: 5,
+        time: '2 days ago',
+        text: 'The barrel-aged flanders red is worth the trip alone. Staff walked us through the whole sour program on the Saturday tour.',
+        likes: 12,
+        liked: false,
+    },
+    {
+        id: '2',
+        user: 'stoutfan_88',
+        initials: 'SB',
+        rating: 4,
+        time: '1 week ago',
+        text: 'Great IPAs, solid taproom. Gets crowded after 7pm on weekends — go early if you want a seat in the barrel room.',
+        likes: 5,
+        liked: false,
+    },
+    {
+        id: '3',
+        user: 'ale_annie',
+        initials: 'AL',
+        rating: 4,
+        time: '3 weeks ago',
+        text: 'Their cassis gose collab with Cassis & Coal is still on tap. Slightly pricey flights, but generous pours.',
+        likes: 3,
+        liked: false,
+    },
+];
+
+export interface FillerBreweryMeta {
+    foundedYear: number;
+    type: string;
+    website: string;
+    likeCount: number;
+    avgRating: number;
+    ratingsCount: number;
+}
+
+export const FILLER_BREWERY_META: FillerBreweryMeta = {
+    foundedYear: 2014,
+    type: 'Microbrewery',
+    website: 'example.com',
+    likeCount: 127,
+    avgRating: 4,
+    ratingsCount: 76,
+};
--- a/web/frontend/app/features/breweries/utils/format-address.ts
+++ b/web/frontend/app/features/breweries/utils/format-address.ts
@@ -0,0 +1,9 @@
+import type { BreweryLocation } from '../breweries.server';
+
+export const formatBreweryAddress = (location: BreweryLocation): string => {
+    const streetLine = location.addressLine2
+        ? `${location.addressLine1}, ${location.addressLine2}`
+        : location.addressLine1;
+
+    return `${streetLine}, ${location.cityName}, ${location.stateProvinceCode} ${location.postalCode}, ${location.countryName}`;
+};