testing updates

README.md

@@ -60,7 +60,8 @@ Archived/reference areas:
 ## Tech stack
 
 - **Backend**: .NET 10, ASP.NET Core, SQL Server 2022, DbUp
-- **Frontend**: React 19, React Router 7, Vite 7, Tailwind CSS 4, DaisyUI 5
+- **Frontend**: React 19, React Router 7, Vite 7, Tailwind CSS 4, DaisyUI 5,
+  Leaflet/React Leaflet (brewery maps)
 - **UI Documentation**: Storybook 10, Vitest browser mode, Playwright
 - **Testing**: xUnit, Reqnroll (BDD), FluentAssertions, Moq
 - **Infrastructure**: Docker, Docker Compose

docs/architecture.md

@@ -309,7 +309,12 @@ it, without an ORM's change-tracking or mapping magic
   through Dapper, with no manual `IDbCommand` parameter binding. The one
   wrinkle is the `GEOGRAPHY` column on `BreweryPostLocation`, which Dapper
   can't deserialize as a UDT: reads select `CONVERT(varbinary(max),
-  Coordinates)` so the value comes back as a plain `byte[]` Dapper can bind
+  Coordinates)` so the value comes back as a plain `byte[]` Dapper can bind.
+  Proximity search (`GET /api/brewery/locations/nearby`) filters and orders
+  rows server-side with `Coordinates.STDistance(@Origin) <= @RangeInMetres`,
+  avoiding a client-side distance calculation over every row. No spatial
+  index backs the query yet; `schema.sql` sketches one, commented out, for
+  when the table grows large enough to need it
 - Referential checks that a stored procedure used to perform (e.g. "does this
   `CityId` exist?") are now explicit `SELECT 1 ...` existence checks in the
   repository method, run inside the same transaction as the write
@@ -335,11 +340,24 @@ enabled.
 ```text
 web/frontend/
 ├── app/
-│   ├── components/      Shared UI such as Navbar, FormField, SubmitButton, ToastProvider
-│   ├── lib/             Auth helpers, schemas, and theme metadata
-│   ├── routes/          Route modules for home, login, register, dashboard, confirm, theme
-│   ├── root.tsx         App shell and global providers
-│   └── app.css          Theme tokens and global styling
+│   ├── components/      Shared UI: Navbar, FormField, SubmitButton, ToastProvider,
+│   │                    RouteErrorState, ClientOnly (defers client-only children,
+│   │                    for example Leaflet maps, past hydration)
+│   ├── features/        One folder per feature slice, each owning its own
+│   │                    routes/, components/, hooks/, schemas, and server-side
+│   │                    loader helpers:
+│   │                      - account    profile/dashboard management
+│   │                      - auth       login, register, confirm, logout
+│   │                      - breweries  index/directory/detail routes, Leaflet
+│   │                                   map components, nearby-search resource
+│   │                                   route, distance/address utils
+│   │                      - catalog    beers, beer styles
+│   │                      - home       landing page
+│   │                      - theme      theme switcher/guide
+│   ├── hooks/            Shared hooks not tied to one feature, for example useMediaQuery
+│   ├── routes.ts         Route table (React Router 7 config-based routing)
+│   ├── root.tsx          App shell and global providers
+│   └── app.css           Theme tokens and global styling
 ├── .storybook/          Storybook config and preview setup
 ├── stories/             Storybook stories for shared UI and themes
 ├── tests/playwright/    Storybook Playwright coverage
@@ -348,9 +366,13 @@ web/frontend/
 
 ### Frontend responsibilities
 
-- Render the auth demo and theme guide routes
+- Render brewery discovery routes (`/breweries` index, `/breweries/directory`,
+  `/breweries/:id`) with Leaflet-powered maps and geolocation-based "nearby"
+  search
+- Render the auth demo, account dashboard, and theme guide routes
 - Manage cookie-backed website session state
-- Call the .NET API for login, registration, token refresh, and confirmation
+- Call the .NET API for login, registration, token refresh, confirmation, and
+  brewery/location data
 - Provide shared UI building blocks for forms, navigation, themes, and toasts
 - Supply Storybook documentation and browser-based component verification
 

docs/website/testing.md

@@ -164,6 +164,8 @@ The default (`headless: true`) is set in `web/frontend/vite.config.ts`.
 **Features.Breweries.Tests**:
 
 - Brewery create/update/delete commands and get-by-id/get-all queries
+- Brewery location queries: all locations, and locations within a given range
+  of a coordinate
 
 **Features.UserManagement.Tests**:
 

package-lock.json

@@ -0,0 +1,6 @@
+{
+  "name": "the-biergarten-app",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {}
+}

web/backend/Database/Database.Migrations/scripts/01-schema/11-BreweryPostLocation.sql

@@ -41,14 +41,10 @@ CREATE
 NONCLUSTERED INDEX IX_BreweryPostLocation_City
     ON BreweryPostLocation(CityID);
 
--- To assess when the time comes:
-
--- This would allow for efficient spatial queries to find breweries within a certain distance of a location, but it adds overhead to insert/update operations.
-
--- CREATE SPATIAL INDEX SIDX_BreweryPostLocation_Coordinates
---     ON BreweryPostLocation(Coordinates)
---     USING GEOGRAPHY_GRID
---     WITH (
---         GRIDS = (LEVEL_1 = MEDIUM, LEVEL_2 = MEDIUM, LEVEL_3 = MEDIUM, LEVEL_4 = MEDIUM),
---         CELLS_PER_OBJECT = 16
---     );
+CREATE SPATIAL INDEX SIDX_BreweryPostLocation_Coordinates
+    ON BreweryPostLocation(Coordinates)
+    USING GEOGRAPHY_GRID
+    WITH (
+        GRIDS = (LEVEL_1 = MEDIUM, LEVEL_2 = MEDIUM, LEVEL_3 = MEDIUM, LEVEL_4 = MEDIUM),
+        CELLS_PER_OBJECT = 16
+    );

web/backend/Domain/Domain.Entities/Entities/BreweryPost.cs

@@ -21,4 +21,7 @@ public sealed class BreweryPost
     // Navigation Properties
     public BreweryPostLocation? Location { get; set; }
     public List<BeerPost> BeerPosts { get; set; } = [];
+
+    // Query-computed
+    public DistanceInformation? Distance { get; set; }
 }

web/backend/Domain/Domain.Entities/Entities/BreweryPostLocation.cs

@@ -2,6 +2,8 @@ namespace Domain.Entities;
 
 public sealed record CoordinateData(double Latitude, double Longitude);
 
+/// <summary>The distance, as computed by the database, from a query's origin point to a brewery.</summary>
+public sealed record DistanceInformation(CoordinateData From, double DistanceMetres);
 
 public sealed class BreweryPostLocation
 {

web/backend/Features/Features.Breweries.Tests/Queries/GetAllBreweryLocationsHandlerTests.cs

@@ -0,0 +1,54 @@
+using Domain.Entities;
+using Features.Breweries.Dtos;
+using Features.Breweries.Queries.GetAllBreweryLocations;
+using Features.Breweries.Repository;
+using FluentAssertions;
+using Moq;
+
+namespace Features.Breweries.Tests.Queries;
+
+public class GetAllBreweryLocationsHandlerTests
+{
+    private readonly GetAllBreweryLocationsHandler _handler;
+    private readonly Mock<IBreweryRepository> _repoMock = new();
+
+    public GetAllBreweryLocationsHandlerTests()
+    {
+        _handler = new GetAllBreweryLocationsHandler(_repoMock.Object);
+    }
+
+    [Fact]
+    public async Task Handle_ReturnsEmpty_WhenNoBreweriesHaveALocation()
+    {
+        _repoMock.Setup(r => r.GetAllLocations()).ReturnsAsync(Array.Empty<BreweryPost>());
+
+        IEnumerable<SimplifiedBreweryDto> result = await _handler.Handle(
+            new GetAllBreweryLocationsQuery(),
+            CancellationToken.None
+        );
+
+        result.Should().BeEmpty();
+        _repoMock.Verify(r => r.GetAllLocations(), Times.Once);
+    }
+
+    [Fact]
+    public async Task Handle_ReturnsAllLocatedBreweries_FromRepository()
+    {
+        BreweryPost[] breweries =
+        [
+            new BreweryPost { BreweryPostId = Guid.NewGuid(), BreweryName = "A" },
+            new BreweryPost { BreweryPostId = Guid.NewGuid(), BreweryName = "B" },
+        ];
+        _repoMock.Setup(r => r.GetAllLocations()).ReturnsAsync(breweries);
+
+        IEnumerable<SimplifiedBreweryDto> result = await _handler.Handle(
+            new GetAllBreweryLocationsQuery(),
+            CancellationToken.None
+        );
+
+        result
+            .Select(b => b.BreweryPostId)
+            .Should()
+            .BeEquivalentTo(breweries.Select(b => b.BreweryPostId));
+    }
+}

web/backend/Features/Features.Breweries.Tests/Queries/GetBreweryLocationsWithinRangeHandlerTests.cs

@@ -0,0 +1,70 @@
+using Domain.Entities;
+using Features.Breweries.Dtos;
+using Features.Breweries.Queries.GetBreweryLocationsWithinRange;
+using Features.Breweries.Repository;
+using FluentAssertions;
+using Moq;
+
+namespace Features.Breweries.Tests.Queries;
+
+public class GetBreweryLocationsWithinRangeHandlerTests
+{
+    private readonly GetBreweryLocationsWithinRangeHandler _handler;
+    private readonly Mock<IBreweryRepository> _repoMock = new();
+
+    public GetBreweryLocationsWithinRangeHandlerTests()
+    {
+        _handler = new GetBreweryLocationsWithinRangeHandler(_repoMock.Object);
+    }
+
+    [Fact]
+    public async Task Handle_PassesCoordinatesAndRange_ToRepository()
+    {
+        _repoMock
+            .Setup(r =>
+                r.GetAllLocationsWithinRange(
+                    It.Is<CoordinateData>(c => c.Latitude == 43.6532 && c.Longitude == -79.3832),
+                    1000
+                )
+            )
+            .ReturnsAsync(Array.Empty<BreweryPost>());
+
+        IEnumerable<SimplifiedBreweryDto> result = await _handler.Handle(
+            new GetBreweryLocationsWithinRangeQuery(43.6532, -79.3832, 1000),
+            CancellationToken.None
+        );
+
+        result.Should().BeEmpty();
+        _repoMock.Verify(
+            r =>
+                r.GetAllLocationsWithinRange(
+                    It.Is<CoordinateData>(c => c.Latitude == 43.6532 && c.Longitude == -79.3832),
+                    1000
+                ),
+            Times.Once
+        );
+    }
+
+    [Fact]
+    public async Task Handle_ReturnsNearbyBreweries_FromRepository()
+    {
+        BreweryPost[] breweries =
+        [
+            new BreweryPost { BreweryPostId = Guid.NewGuid(), BreweryName = "Nearby A" },
+            new BreweryPost { BreweryPostId = Guid.NewGuid(), BreweryName = "Nearby B" },
+        ];
+        _repoMock
+            .Setup(r => r.GetAllLocationsWithinRange(It.IsAny<CoordinateData>(), It.IsAny<double>()))
+            .ReturnsAsync(breweries);
+
+        IEnumerable<SimplifiedBreweryDto> result = await _handler.Handle(
+            new GetBreweryLocationsWithinRangeQuery(43.6532, -79.3832, 1000),
+            CancellationToken.None
+        );
+
+        result
+            .Select(b => b.BreweryPostId)
+            .Should()
+            .BeEquivalentTo(breweries.Select(b => b.BreweryPostId));
+    }
+}

web/backend/Features/Features.Breweries/Controllers/BreweryController.cs

@@ -3,7 +3,9 @@ using Features.Breweries.Commands.DeleteBrewery;
 using Features.Breweries.Commands.UpdateBrewery;
 using Features.Breweries.Dtos;
 using Features.Breweries.Queries.GetAllBreweries;
+using Features.Breweries.Queries.GetAllBreweryLocations;
 using Features.Breweries.Queries.GetBreweryById;
+using Features.Breweries.Queries.GetBreweryLocationsWithinRange;
 using MediatR;
 using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Mvc;
@@ -64,6 +66,49 @@ public class BreweryController(IMediator mediator) : ControllerBase
         );
     }
 
+    /// <summary>Retrieves all brewery posts that have a set location.</summary>
+    /// <remarks>Allows anonymous access.</remarks>
+    [AllowAnonymous]
+    [HttpGet("locations")]
+    public async Task<ActionResult<ResponseBody<IEnumerable<SimplifiedBreweryDto>>>> GetAllLocations()
+    {
+        IEnumerable<SimplifiedBreweryDto> breweries = await mediator.Send(
+            new GetAllBreweryLocationsQuery()
+        );
+        return Ok(
+            new ResponseBody<IEnumerable<SimplifiedBreweryDto>>
+            {
+                Message = "Brewery locations retrieved successfully.",
+                Payload = breweries,
+            }
+        );
+    }
+
+    /// <summary>Retrieves brewery posts with a set location within range of the given coordinates, nearest first.</summary>
+    /// <param name="latitude">The origin latitude, in decimal degrees.</param>
+    /// <param name="longitude">The origin longitude, in decimal degrees.</param>
+    /// <param name="rangeInMetres">The maximum distance, in metres, from the origin coordinates.</param>
+    /// <remarks>Allows anonymous access.</remarks>
+    [AllowAnonymous]
+    [HttpGet("locations/nearby")]
+    public async Task<ActionResult<ResponseBody<IEnumerable<SimplifiedBreweryDto>>>> GetLocationsWithinRange(
+        [FromQuery] double latitude,
+        [FromQuery] double longitude,
+        [FromQuery] double rangeInMetres
+    )
+    {
+        IEnumerable<SimplifiedBreweryDto> breweries = await mediator.Send(
+            new GetBreweryLocationsWithinRangeQuery(latitude, longitude, rangeInMetres)
+        );
+        return Ok(
+            new ResponseBody<IEnumerable<SimplifiedBreweryDto>>
+            {
+                Message = "Brewery locations retrieved successfully.",
+                Payload = breweries,
+            }
+        );
+    }
+
     /// <summary>Creates a new brewery post.</summary>
     /// <returns><c>201 Created</c> with the newly created brewery.</returns>
     [HttpPost]

web/backend/Features/Features.Breweries/Dtos/BreweryDto.cs

@@ -32,3 +32,13 @@ public record BreweryDto(
     byte[]? RowVersion,
     BreweryLocationDto? Location
 );
+/// <param name="DistanceMetres">
+///     The distance, in metres, from a query's origin point, or <see langword="null"/> for queries with no
+///     origin point (e.g. <c>GET /api/brewery/locations</c>).
+/// </param>
+public record SimplifiedBreweryDto(
+    Guid BreweryPostId,
+    string BreweryName,
+    BreweryLocationDto? Location,
+    double? DistanceMetres
+);

web/backend/Features/Features.Breweries/Dtos/BreweryDtoMapper.cs

@@ -40,4 +40,36 @@ public static class BreweryDtoMapper
                 )
         );
     }
+
+    /// <summary>
+    ///     Converts a <see cref="BreweryPost" /> to its simplified DTO representation, used for
+    ///     location-based queries that only need identifying and location details.
+    /// </summary>
+    public static SimplifiedBreweryDto ToSimplifiedDto(this BreweryPost brewery)
+    {
+        return new SimplifiedBreweryDto(
+            BreweryPostId: brewery.BreweryPostId,
+            BreweryName: brewery.BreweryName,
+            Location: brewery.Location is null
+                ? null
+                : new BreweryLocationDto(
+                    BreweryPostLocationId: brewery.Location.BreweryPostLocationId,
+                    CityId: brewery.Location.CityId,
+                    CityName: brewery.Location.City?.CityName ?? string.Empty,
+                    StateProvinceName: brewery.Location.City?.StateProvince?.StateProvinceName
+                        ?? string.Empty,
+                    StateProvinceCode: brewery.Location.City?.StateProvince?.Iso31662
+                        ?? string.Empty,
+                    CountryName: brewery.Location.City?.StateProvince?.Country?.CountryName
+                        ?? string.Empty,
+                    CountryCode: brewery.Location.City?.StateProvince?.Country?.Iso31661
+                        ?? string.Empty,
+                    AddressLine1: brewery.Location.AddressLine1,
+                    AddressLine2: brewery.Location.AddressLine2,
+                    PostalCode: brewery.Location.PostalCode,
+                    Coordinates: brewery.Location.Coordinates
+                ),
+            DistanceMetres: brewery.Distance?.DistanceMetres
+        );
+    }
 }

web/backend/Features/Features.Breweries/Queries/GetAllBreweryLocations/GetAllBreweryLocationsHandler.cs

@@ -0,0 +1,21 @@
+using Domain.Entities;
+using Features.Breweries.Dtos;
+using Features.Breweries.Repository;
+using MediatR;
+
+namespace Features.Breweries.Queries.GetAllBreweryLocations;
+
+/// <summary>Handles <see cref="GetAllBreweryLocationsQuery" /> by retrieving all located brewery posts.</summary>
+public class GetAllBreweryLocationsHandler(IBreweryRepository repository)
+    : IRequestHandler<GetAllBreweryLocationsQuery, IEnumerable<SimplifiedBreweryDto>>
+{
+    /// <summary>Retrieves every brewery post that has a set location.</summary>
+    public async Task<IEnumerable<SimplifiedBreweryDto>> Handle(
+        GetAllBreweryLocationsQuery request,
+        CancellationToken cancellationToken
+    )
+    {
+        IEnumerable<BreweryPost> breweries = await repository.GetAllLocations();
+        return breweries.Select(b => b.ToSimplifiedDto());
+    }
+}

web/backend/Features/Features.Breweries/Queries/GetAllBreweryLocations/GetAllBreweryLocationsQuery.cs

@@ -0,0 +1,10 @@
+using Features.Breweries.Dtos;
+using MediatR;
+
+namespace Features.Breweries.Queries.GetAllBreweryLocations;
+
+/// <summary>
+///     Retrieves all brewery posts that have a set location. Bound directly from
+///     <c>GET /api/brewery/locations</c>.
+/// </summary>
+public record GetAllBreweryLocationsQuery : IRequest<IEnumerable<SimplifiedBreweryDto>>;

web/backend/Features/Features.Breweries/Queries/GetBreweryLocationsWithinRange/GetBreweryLocationsWithinRangeHandler.cs

@@ -0,0 +1,26 @@
+using Domain.Entities;
+using Features.Breweries.Dtos;
+using Features.Breweries.Repository;
+using MediatR;
+
+namespace Features.Breweries.Queries.GetBreweryLocationsWithinRange;
+
+/// <summary>
+///     Handles <see cref="GetBreweryLocationsWithinRangeQuery" /> by retrieving nearby located brewery posts.
+/// </summary>
+public class GetBreweryLocationsWithinRangeHandler(IBreweryRepository repository)
+    : IRequestHandler<GetBreweryLocationsWithinRangeQuery, IEnumerable<SimplifiedBreweryDto>>
+{
+    /// <summary>Retrieves brewery posts within range of the requested coordinates, nearest first.</summary>
+    public async Task<IEnumerable<SimplifiedBreweryDto>> Handle(
+        GetBreweryLocationsWithinRangeQuery request,
+        CancellationToken cancellationToken
+    )
+    {
+        IEnumerable<BreweryPost> breweries = await repository.GetAllLocationsWithinRange(
+            new CoordinateData(request.Latitude, request.Longitude),
+            request.RangeInMetres
+        );
+        return breweries.Select(b => b.ToSimplifiedDto());
+    }
+}

web/backend/Features/Features.Breweries/Queries/GetBreweryLocationsWithinRange/GetBreweryLocationsWithinRangeQuery.cs

@@ -0,0 +1,15 @@
+using Features.Breweries.Dtos;
+using MediatR;
+
+namespace Features.Breweries.Queries.GetBreweryLocationsWithinRange;
+
+/// <summary>
+///     Retrieves brewery posts with a set location within <paramref name="RangeInMetres" /> of the given
+///     coordinates, nearest first. Bound directly from the query string of
+///     <c>GET /api/brewery/locations/nearby</c>.
+/// </summary>
+/// <param name="Latitude">The origin latitude, in decimal degrees.</param>
+/// <param name="Longitude">The origin longitude, in decimal degrees.</param>
+/// <param name="RangeInMetres">The maximum distance, in metres, from the origin coordinates.</param>
+public record GetBreweryLocationsWithinRangeQuery(double Latitude, double Longitude, double RangeInMetres)
+    : IRequest<IEnumerable<SimplifiedBreweryDto>>;

web/backend/Features/Features.Breweries/Queries/GetBreweryLocationsWithinRange/GetBreweryLocationsWithinRangeValidator.cs

@@ -0,0 +1,23 @@
+using FluentValidation;
+
+namespace Features.Breweries.Queries.GetBreweryLocationsWithinRange;
+
+/// <summary>Validates <see cref="GetBreweryLocationsWithinRangeQuery" />.</summary>
+public class GetBreweryLocationsWithinRangeValidator
+    : AbstractValidator<GetBreweryLocationsWithinRangeQuery>
+{
+    public GetBreweryLocationsWithinRangeValidator()
+    {
+        RuleFor(x => x.Latitude)
+            .InclusiveBetween(-90, 90)
+            .WithMessage("Latitude must be between -90 and 90 degrees.");
+
+        RuleFor(x => x.Longitude)
+            .InclusiveBetween(-180, 180)
+            .WithMessage("Longitude must be between -180 and 180 degrees.");
+
+        RuleFor(x => x.RangeInMetres)
+            .GreaterThan(0)
+            .WithMessage("RangeInMetres must be greater than zero.");
+    }
+}

web/backend/Features/Features.Breweries/Repository/BreweryRepository.cs

@@ -124,6 +124,102 @@ public class BreweryRepository(ISqlConnectionFactory connectionFactory)
         );
     }
 
+    /// <inheritdoc/>
+    public async Task<IEnumerable<BreweryPost>> GetAllLocationsWithinRange(CoordinateData coords, double rangeInMetres)
+    {
+        await using DbConnection connection = await CreateConnection();
+        return await connection.QueryAsync<
+        BreweryPost,
+        BreweryPostLocation,
+        City,
+        StateProvince,
+        Country,
+        DistanceRow,
+        BreweryPost
+            > (
+                """
+                DECLARE @Origin geography = geography::Point(@Latitude, @Longitude, 4326);
+
+                SELECT
+                    bp.BreweryPostID,
+                    bp.BreweryName,
+                    bpl.BreweryPostLocationID,
+                    bpl.AddressLine1,
+                    bpl.AddressLine2,
+                    bpl.PostalCode,
+                    CONVERT(varbinary(max), bpl.Coordinates) AS Coordinates,
+                    c.CityID,
+                    c.CityName,
+                    sp.StateProvinceID,
+                    sp.StateProvinceName,
+                    sp.ISO3166_2 AS Iso31662,
+                    co.CountryID,
+                    co.CountryName,
+                    co.ISO3166_1 AS Iso31661,
+                    bpl.Coordinates.STDistance(@Origin) AS DistanceMetres
+                FROM dbo.BreweryPost bp
+                INNER JOIN dbo.BreweryPostLocation bpl ON bp.BreweryPostID = bpl.BreweryPostID
+                LEFT JOIN dbo.City c ON bpl.CityID = c.CityID
+                LEFT JOIN dbo.StateProvince sp ON c.StateProvinceID = sp.StateProvinceID
+                LEFT JOIN dbo.Country co ON sp.CountryID = co.CountryID
+                WHERE bpl.Coordinates IS NOT NULL
+                  AND bpl.Coordinates.STDistance(@Origin) <= @RangeInMetres
+                ORDER BY bpl.Coordinates.STDistance(@Origin) ASC
+                """,
+                (post, location, city, stateProvince, country, distance) =>
+                    MapBreweryRowWithDistance(post, location, city, stateProvince, country, distance, coords),
+                param: new
+                {
+                    coords.Latitude,
+                    coords.Longitude,
+                    RangeInMetres = rangeInMetres
+                },
+                splitOn: "BreweryPostLocationID,CityID,StateProvinceID,CountryID,DistanceMetres"
+            );
+    }
+
+    /// <inheritdoc/>
+    public async Task<IEnumerable<BreweryPost>> GetAllLocations()
+    {
+        await using DbConnection connection = await CreateConnection();
+        return await connection.QueryAsync<
+        BreweryPost,
+        BreweryPostLocation,
+        City,
+        StateProvince,
+        Country,
+        BreweryPost
+            > (
+                """
+                SELECT
+                    bp.BreweryPostID,
+                    bp.BreweryName,
+                    bpl.BreweryPostLocationID,
+                    bpl.AddressLine1,
+                    bpl.AddressLine2,
+                    bpl.PostalCode,
+                    CONVERT(varbinary(max), bpl.Coordinates) AS Coordinates,
+                    c.CityID,
+                    c.CityName,
+                    sp.StateProvinceID,
+                    sp.StateProvinceName,
+                    sp.ISO3166_2 AS Iso31662,
+                    co.CountryID,
+                    co.CountryName,
+                    co.ISO3166_1 AS Iso31661
+                FROM dbo.BreweryPost bp
+                INNER JOIN dbo.BreweryPostLocation bpl ON bp.BreweryPostID = bpl.BreweryPostID
+                LEFT JOIN dbo.City c ON bpl.CityID = c.CityID
+                LEFT JOIN dbo.StateProvince sp ON c.StateProvinceID = sp.StateProvinceID
+                LEFT JOIN dbo.Country co ON sp.CountryID = co.CountryID
+                WHERE bpl.Coordinates IS NOT NULL
+                ORDER BY bp.BreweryPostID ASC
+                """,
+                MapBreweryRow,
+                splitOn: "BreweryPostLocationID,CityID,StateProvinceID,CountryID"
+            );
+    }
+
     /// <inheritdoc/>
     public async Task<BreweryPost> UpdateAsync(BreweryPost brewery)
     {
@@ -134,18 +230,18 @@ public class BreweryRepository(ISqlConnectionFactory connectionFactory)
         {
             bool breweryExists =
                 await connection.ExecuteScalarAsync<int?>(
-                    new CommandDefinition(
-                        """
-                        SELECT 1 FROM
-                            dbo.BreweryPost
-                        WHERE
-                            BreweryPostID = @BreweryPostId
-                        """,
-                        new { brewery.BreweryPostId },
-                        transaction
+                        new CommandDefinition(
+                            """
+                            SELECT 1 FROM
+                                dbo.BreweryPost
+                            WHERE
+                                BreweryPostID = @BreweryPostId
+                            """,
+                            new { brewery.BreweryPostId },
+                            transaction
+                        )
                     )
-                )
-                is not null;
+                    is not null;
 
             if (!breweryExists)
                 throw new NotFoundException("Brewery not found.");
@@ -154,13 +250,13 @@ public class BreweryRepository(ISqlConnectionFactory connectionFactory)
             {
                 bool cityExists =
                     await connection.ExecuteScalarAsync<int?>(
-                        new CommandDefinition(
-                            "SELECT 1 FROM dbo.City WHERE CityID = @CityId",
-                            new { brewery.Location.CityId },
-                            transaction
+                            new CommandDefinition(
+                                "SELECT 1 FROM dbo.City WHERE CityID = @CityId",
+                                new { brewery.Location.CityId },
+                                transaction
+                            )
                         )
-                    )
-                    is not null;
+                        is not null;
 
                 if (!cityExists)
                     throw new NotFoundException("City not found.");
@@ -212,17 +308,17 @@ public class BreweryRepository(ISqlConnectionFactory connectionFactory)
             {
                 bool locationExists =
                     await connection.ExecuteScalarAsync<int?>(
-                        new CommandDefinition(
-                            """
-                            SELECT 1
-                            FROM dbo.BreweryPostLocation
-                            WHERE BreweryPostID = @BreweryPostId
-                            """,
-                            new { brewery.BreweryPostId },
-                            transaction
+                            new CommandDefinition(
+                                """
+                                SELECT 1
+                                FROM dbo.BreweryPostLocation
+                                WHERE BreweryPostID = @BreweryPostId
+                                """,
+                                new { brewery.BreweryPostId },
+                                transaction
+                            )
                         )
-                    )
-                    is not null;
+                        is not null;
 
                 if (locationExists)
                     await connection.ExecuteAsync(
@@ -303,9 +399,9 @@ public class BreweryRepository(ISqlConnectionFactory connectionFactory)
         }
 
         return await GetByIdAsync(brewery.BreweryPostId)
-            ?? throw new InvalidOperationException(
-                $"Brewery '{brewery.BreweryPostId}' was not found after a successful update."
-            );
+               ?? throw new InvalidOperationException(
+                   $"Brewery '{brewery.BreweryPostId}' was not found after a successful update."
+               );
     }
 
     /// <inheritdoc/>
@@ -339,38 +435,38 @@ public class BreweryRepository(ISqlConnectionFactory connectionFactory)
         {
             bool userExists =
                 await connection.ExecuteScalarAsync<int?>(
-                    new CommandDefinition(
-                        """
-                                    SELECT 1
-                                    FROM
-                                        dbo.UserAccount
-                                    WHERE
-                                        UserAccountID = @PostedById
-                        """,
-                        new { brewery.PostedById },
-                        transaction
+                        new CommandDefinition(
+                            """
+                                        SELECT 1
+                                        FROM
+                                            dbo.UserAccount
+                                        WHERE
+                                            UserAccountID = @PostedById
+                            """,
+                            new { brewery.PostedById },
+                            transaction
+                        )
                     )
-                )
-                is not null;
+                    is not null;
 
             if (!userExists)
                 throw new NotFoundException("User not found.");
 
             bool cityExists =
                 await connection.ExecuteScalarAsync<int?>(
-                    new CommandDefinition(
-                        """
-                                    SELECT 1
-                                    FROM
-                                        dbo.City
-                                    WHERE
-                                        CityID = @CityId
-                        """,
-                        new { brewery.Location.CityId },
-                        transaction
+                        new CommandDefinition(
+                            """
+                                        SELECT 1
+                                        FROM
+                                            dbo.City
+                                        WHERE
+                                            CityID = @CityId
+                            """,
+                            new { brewery.Location.CityId },
+                            transaction
+                        )
                     )
-                )
-                is not null;
+                    is not null;
 
             if (!cityExists)
                 throw new NotFoundException("City not found.");
@@ -490,4 +586,29 @@ public class BreweryRepository(ISqlConnectionFactory connectionFactory)
         post.Location = location;
         return post;
     }
-}
+
+    /// <summary>Dapper multi-mapping row for the <c>DistanceMetres</c> column computed by a range query.</summary>
+    private sealed class DistanceRow
+    {
+        public double DistanceMetres { get; set; }
+    }
+
+    /// <summary>
+    ///     Composes a joined row via <see cref="MapBreweryRow" />, then attaches the DB-computed distance
+    ///     from <paramref name="origin" /> as the result's <see cref="BreweryPost.Distance" />.
+    /// </summary>
+    private static BreweryPost MapBreweryRowWithDistance(
+        BreweryPost post,
+        BreweryPostLocation location,
+        City city,
+        StateProvince stateProvince,
+        Country country,
+        DistanceRow distance,
+        CoordinateData origin
+    )
+    {
+        BreweryPost mapped = MapBreweryRow(post, location, city, stateProvince, country);
+        mapped.Distance = new DistanceInformation(origin, distance.DistanceMetres);
+        return mapped;
+    }
+}

web/backend/Features/Features.Breweries/Repository/IBreweryRepository.cs

@@ -21,6 +21,20 @@ public interface IBreweryRepository
     /// <param name="offset">Number of rows to skip. Treated as zero if <see langword="null" />.</param>
     Task<IEnumerable<BreweryPost>> GetAllAsync(int? limit, int? offset);
 
+    /// <summary>
+    ///     Retrieves brewery posts with a set location within <paramref name="rangeInMetres" /> of
+    ///     <paramref name="coords" />, nearest first. Posts without coordinates are excluded.
+    /// </summary>
+    /// <param name="coords">The origin point to measure distance from.</param>
+    /// <param name="rangeInMetres">The maximum distance, in metres, from <paramref name="coords" />.</param>
+    Task<IEnumerable<BreweryPost>> GetAllLocationsWithinRange(CoordinateData coords, double rangeInMetres);
+
+    /// <summary>
+    ///     Retrieves all brewery posts that have a set location, ordered by <c>BreweryPostId</c>. Posts
+    ///     without coordinates are excluded.
+    /// </summary>
+    Task<IEnumerable<BreweryPost>> GetAllLocations();
+
     /// <summary>
     ///     Updates a brewery post's name and description, and upserts or clears its location, enforcing
     ///     optimistic concurrency via <paramref name="brewery" />'s <c>RowVersion</c>: the update is rejected
@@ -48,4 +62,4 @@ public interface IBreweryRepository
     ///     Thrown when <paramref name="brewery" />'s <c>PostedById</c> or <c>Location.CityId</c> does not exist.
     /// </exception>
     Task CreateAsync(BreweryPost brewery);
-}
+}

web/frontend/.storybook/main.ts

@@ -12,6 +12,12 @@ const config: StorybookConfig = {
         '../stories/RegisterForm.stories.tsx',
         '../stories/Navbar.stories.tsx',
         '../stories/Toast.stories.tsx',
+        '../stories/BreweryCard.stories.tsx',
+        '../stories/FeaturedBreweryCard.stories.tsx',
+        '../stories/RecentBreweries.stories.tsx',
+        '../stories/NearbyBreweriesSection.stories.tsx',
+        '../stories/BreweryMap.stories.tsx',
+        '../stories/NearbyBreweryMap.stories.tsx',
         '../stories/Themes.stories.tsx',
     ],
     addons: [

web/frontend/app/components/ClientOnly.tsx

@@ -0,0 +1,21 @@
+import { useSyncExternalStore, type ReactNode } from 'react';
+
+interface ClientOnlyProps {
+    children: () => ReactNode;
+    fallback?: ReactNode;
+}
+
+const noop = () => undefined;
+const emptySubscribe = () => noop;
+
+const ClientOnly = ({ children, fallback = null }: ClientOnlyProps) => {
+    const mounted = useSyncExternalStore(
+        emptySubscribe,
+        () => true,
+        () => false,
+    );
+
+    return mounted ? children() : fallback;
+};
+
+export default ClientOnly;

web/frontend/app/features/account/hooks/useSectionError.ts

@@ -2,7 +2,10 @@ import { useEffect } from 'react';
 import { showErrorToast } from '../../../components/ui/toast/toast';
 import type { ActionResult } from '../types';
 
-export const useSectionError = (result: ActionResult | undefined, intent: ActionResult['intent']) => {
+export const useSectionError = (
+    result: ActionResult | undefined,
+    intent: ActionResult['intent'],
+) => {
     useEffect(() => {
         if (!result || result.intent !== intent) return;
         showErrorToast(result.error);

web/frontend/app/features/breweries/BREWERY_INDEX_HANDOFF.md

@@ -0,0 +1,76 @@
+# Brewery index — data requirements
+
+`/breweries` (`app/features/breweries/routes/breweries.tsx`) is built and live.
+This document inventories every piece of data the page needs, section by
+section: what's already wired to real data, what's filler pending backend work,
+and what the backend would need to add to close each gap.
+
+## Status legend
+
+- ✅ **Available** — real data, already wired up.
+- ⚠️ **Partial** — an endpoint exists but is missing a field the design needs.
+- ❌ **Missing** — no backend support at all; page currently shows filler.
+
+## 1. Page header
+
+Static copy only. No data.
+
+## 2. Featured brewery
+
+| Field                                | Status | Current source                                       | Gap                                                                                                                                                                                    |
+| ------------------------------------ | ------ | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Name, description, address, location | ✅     | `GET /api/brewery` (`BreweryDto`)                    | —                                                                                                                                                                                      |
+| "Editorially featured" selection     | ❌     | none — defaults to the most recently created brewery | No `IsFeatured` flag or rotation concept anywhere in `BreweryPost`. Needs a field + an admin toggle, or a scheduled rotation query, to back the "THIS WEEK" cadence the badge implies. |
+| Founded year                         | ❌     | none                                                 | `BreweryPost` has no founding date. Would need a new column (distinct from `CreatedAt`, which is post-creation time, not the brewery's actual founding).                               |
+| Beers listed count                   | ❌     | none                                                 | No beer-count aggregate exists. Blocked on the beers gap below.                                                                                                                        |
+| House style                          | ❌     | none                                                 | No style/tag field on `BreweryPost`, and no aggregate over its beers' styles either.                                                                                                   |
+
+## 3. Breweries near you
+
+| Field                                                   | Status | Current 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 / tagline per brewery                     | ❌     | none                                                                               | `SimplifiedBreweryDto` (used by both `/locations` and `/locations/nearby`) has no description-like field. List and map-popup text use filler. Needs either a short tagline field or a truncated `Description` added to that DTO. |
+| User's current location                                 | ✅     | Browser Geolocation API                                                            | —                                                                                                                                                                                                                                |
+| Fallback region (before permission granted / on denial) | ⚠️     | Falls back to the featured brewery's own coordinates as a proxy center             | Works, but isn't a deliberate "default region." A real deployment likely wants a configured default (e.g. per-tenant HQ city) rather than borrowing the featured brewery's location.                                             |
+| Manual location entry ("Change location")               | ❌     | Re-requests browser geolocation only                                               | No geocoding/place-search endpoint exists to resolve a typed address or city name to coordinates.                                                                                                                                |
+| Search radius                                           | ✅     | Client-side state (10–150 km slider), passed straight through to `rangeInMetres`   | —                                                                                                                                                                                                                                |
+
+## 4. Recently added
+
+| Field                                   | Status | Current source                                   | Gap |
+| --------------------------------------- | ------ | ------------------------------------------------ | --- |
+| Newest breweries, name/city/description | ✅     | `GET /api/brewery` (already sorted newest-first) | —   |
+
+No gaps — this section is fully real.
+
+## 5. Directory CTA
+
+| Field                                   | Status | Current source              | Gap                                                                                                                                                                                                                              |
+| --------------------------------------- | ------ | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Total partner brewery count             | ❌     | Filler number (`128`)       | No lightweight count endpoint. Needs something like `GET /api/brewery/count` rather than fetching the full unbounded list just to measure it.                                                                                    |
+| Filter by country / region / beer style | ❌     | Copy only — not implemented | This is CTA copy describing the destination directory page's future capability, not a data need of this page itself. Tracked here because it implies the directory page will eventually need country/region/style filter params. |
+
+## 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 on the featured card.
+- "House style" (would likely aggregate from a brewery's beers' `BeerStyle`).
+- Any future beer-style filter on the directory.
+
+## Summary of backend work to fully close the gaps
+
+1. `IsFeatured` flag (or equivalent rotation query) on `BreweryPost`.
+2. `FoundedYear` (or similar) column on `BreweryPost`.
+3. A short tagline/note field on `BreweryPost`, surfaced through
+   `SimplifiedBreweryDto`.
+4. Stand up `Features.Beers` — at minimum a query to count beers per brewery and
+   read their styles.
+5. `GET /api/brewery/count`.
+6. A geocoding/place-search endpoint for manual location entry.
+7. (Product decision, not code) a configured default region to fall back to
+   instead of the featured brewery's coordinates.

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)}`);
 

web/frontend/app/features/breweries/components/BreweryCard.tsx

@@ -1,5 +1,6 @@
 import { Link } from 'react-router';
 import type { Brewery } from '../breweries.server';
+import { formatBreweryAddress } from '../utils/format-address';
 
 interface BreweryCardProps {
     brewery: Brewery;
@@ -12,13 +13,32 @@ const BreweryCard = ({ brewery }: BreweryCardProps) => (
     >
         <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 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">
-                    {brewery.location.addressLine1}
-                    {brewery.location.addressLine2 ? `, ${brewery.location.addressLine2}` : ''}
+                    {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>
 );

web/frontend/app/features/breweries/components/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-blue-500 border-2 border-white 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;

web/frontend/app/features/breweries/components/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_INDEX_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;

web/frontend/app/features/breweries/components/NearbyBreweriesSection.tsx

@@ -0,0 +1,336 @@
+import { lazy, Suspense, useEffect, useState } from 'react';
+import { useFetcher } from 'react-router';
+import type { LatLngTuple } from 'leaflet';
+import ClientOnly from '../../../components/ClientOnly';
+import useDebouncedValue from '../../../hooks/useDebouncedValue';
+import type { SimplifiedBrewery } from '../breweries.server';
+import type { loader as nearbyLoader } from '../routes/breweries-nearby';
+import { formatDistance, type DistanceUnit } from '../utils/distance';
+import type { NearbyMapPin } from './NearbyBreweryMap';
+
+const NearbyBreweryMap = lazy(() => import('./NearbyBreweryMap'));
+
+const MAP_PLACEHOLDER_CLASS = 'min-h-[30rem] h-full w-full rounded-box bg-base-300';
+const DEFAULT_RADIUS_KM = 120;
+const MIN_RADIUS_KM = 10;
+const MAX_RADIUS_KM = 150;
+const RADIUS_STEP_KM = 10;
+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;
+}
+
+// Notes aren't tracked on brewery locations yet - see BREWERY_INDEX_HANDOFF.md.
+const FILLER_NOTE = 'A stop worth the detour.';
+
+const cardClassName = (selected: boolean) =>
+    `text-left rounded-box bg-base-100 shadow p-4 cursor-pointer transition-shadow hover:shadow-lg border-l-4 ${
+        selected ? 'border-l-primary' : 'border-l-transparent'
+    }`;
+
+interface BreweriesNearByHeaderParams {
+    center: LatLngTuple | null;
+    withDistance: { brewery: SimplifiedBrewery; distanceMetres: number }[];
+    radiusKm: number;
+    unit: 'km' | 'mi';
+    centerLabel: string;
+}
+
+const BreweriesNearByHeader = ({
+    center,
+    centerLabel,
+    radiusKm,
+    unit,
+    withDistance,
+}: BreweriesNearByHeaderParams) => {
+    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>
+    );
+};
+
+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>
+    );
+};
+
+interface BreweryWithDistance {
+    brewery: SimplifiedBrewery;
+    distanceMetres: number;
+}
+
+interface NearbyBreweryListProps {
+    withDistance: BreweryWithDistance[];
+    center: LatLngTuple | null;
+    radiusKm: number;
+    unit: DistanceUnit;
+    renderItem: (item: BreweryWithDistance) => React.JSX.Element;
+}
+
+const NearbyBreweryList = ({
+    withDistance,
+    center,
+    radiusKm,
+    unit,
+    renderItem,
+}: 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(renderItem)}
+        </>
+    );
+};
+
+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>
+    );
+};
+
+interface ClientOnlyMapProps {
+    render: () => React.JSX.Element;
+}
+
+const ClientOnlyMap = ({ render }: ClientOnlyMapProps) => {
+    return <ClientOnly fallback={<div className={MAP_PLACEHOLDER_CLASS} />}>{render}</ClientOnly>;
+};
+
+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">
+            <BreweriesNearByHeader
+                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}
+                        renderItem={({ brewery, distanceMetres }) => (
+                            <button
+                                key={brewery.breweryPostId}
+                                type="button"
+                                onClick={() => onSelect(brewery.breweryPostId)}
+                                className={cardClassName(selectedId === brewery.breweryPostId)}
+                            >
+                                <div className="flex justify-between items-baseline gap-3">
+                                    <h3 className="font-serif text-lg m-0">
+                                        {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 mt-1">
+                                        {brewery.location.cityName},{' '}
+                                        {brewery.location.stateProvinceCode}
+                                    </div>
+                                )}
+                                <div className="text-sm mt-2">{FILLER_NOTE}</div>
+                            </button>
+                        )}
+                    />
+                    <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;

web/frontend/app/features/breweries/components/NearbyBreweryMap.tsx

@@ -0,0 +1,114 @@
+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';
+
+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;
+}
+
+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 points: LatLngTuple[] = pins.map((pin) => [pin.latitude, pin.longitude]);
+        if (userLocation) points.push(userLocation);
+        if (points.length > 0) {
+            map.fitBounds(points, { padding: [40, 40], 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 NearbyBreweryMap = ({
+    pins,
+    selectedId,
+    onSelect,
+    userLocation,
+    userLocationLabel,
+}: NearbyBreweryMapProps) => (
+    <MapContainer
+        center={userLocation ?? [pins[0]?.latitude ?? 20, pins[0]?.longitude ?? 0]}
+        zoom={11}
+        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} />
+        {userLocation && (
+            <CircleMarker
+                center={userLocation}
+                radius={6}
+                pathOptions={{ color: '#fff', weight: 2, fillColor: '#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;

web/frontend/app/features/breweries/components/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 p-6 flex flex-col gap-1.5"
+                    >
+                        <h3 className="font-serif text-xl m-0">{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>
+        </section>
+    );
+};
+
+export default RecentBreweries;

web/frontend/app/features/breweries/routes/breweries-nearby.tsx

@@ -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 };
+};

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/FeaturedBreweryCard';
+import NearbyBreweriesSection from '../components/NearbyBreweriesSection';
+import RecentBreweries from '../components/RecentBreweries';
 import { getBreweries } from '../breweries.server';
 import type { Route } from './+types/breweries';
 
+// No count endpoint exists yet - see BREWERY_INDEX_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_INDEX_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>
     );
 };

web/frontend/app/features/breweries/routes/brewery-detail.tsx

@@ -1,6 +1,7 @@
 import { data, Link } from 'react-router';
 import RouteErrorState from '../../../components/ui/error/RouteErrorState';
 import { getBreweryById } from '../breweries.server';
+import { formatBreweryAddress } from '../utils/format-address';
 import type { Route } from './+types/brewery-detail';
 
 export const loader = async ({ params }: Route.LoaderArgs) => {
@@ -37,11 +38,7 @@ const BreweryDetail = ({ loaderData }: Route.ComponentProps) => {
                                 <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>
+                                <p>{formatBreweryAddress(brewery.location)}</p>
                             </div>
                         )}
 

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/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/BreweryMap';
+
+const PAGE_SIZE = 12;
+const MAP_PLACEHOLDER_CLASS = 'h-[28rem] md:h-[34rem] w-full rounded-box bg-base-300';
+
+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/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} />
+);

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}`;
+};

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}`;
+};

web/frontend/app/hooks/useDebouncedValue.ts

@@ -0,0 +1,20 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * Returns a value that only updates after `delayMs` has passed without `value` changing.
+ *
+ * @example
+ *   const debouncedQuery = useDebouncedValue(query, 300);
+ */
+const useDebouncedValue = <T>(value: T, delayMs: number): T => {
+    const [debounced, setDebounced] = useState(value);
+
+    useEffect(() => {
+        const timeout = setTimeout(() => setDebounced(value), delayMs);
+        return () => clearTimeout(timeout);
+    }, [value, delayMs]);
+
+    return debounced;
+};
+
+export default useDebouncedValue;

web/frontend/app/hooks/useMediaQuery.ts

@@ -0,0 +1,22 @@
+import { useSyncExternalStore } from 'react';
+
+const subscribe = (query: string) => (callback: () => void) => {
+    const media = window.matchMedia(query);
+    media.addEventListener('change', callback);
+    return () => media.removeEventListener('change', callback);
+};
+
+/**
+ * Tracks whether a CSS media query currently matches the viewport, updating on change.
+ *
+ * @example
+ *   const isSmallScreen = useMediaQuery('(max-width: 640px)');
+ */
+const useMediaQuery = (query: `(${string})`) =>
+    useSyncExternalStore(
+        subscribe(query),
+        () => window.matchMedia(query).matches,
+        () => false,
+    );
+
+export default useMediaQuery;

web/frontend/app/routes.ts

@@ -11,6 +11,8 @@ export default [
     route('confirm', 'features/auth/routes/confirm.tsx'),
     route('beers', 'features/catalog/routes/beers.tsx'),
     route('breweries', 'features/breweries/routes/breweries.tsx'),
+    route('breweries/directory', 'features/breweries/routes/brewery-directory.tsx'),
+    route('breweries/nearby', 'features/breweries/routes/breweries-nearby.tsx'),
     route('breweries/:id', 'features/breweries/routes/brewery-detail.tsx'),
     route('beer-styles', 'features/catalog/routes/beer-styles.tsx'),
 ] satisfies RouteConfig;

web/frontend/package-lock.json

@@ -15,10 +15,12 @@
                 "@react-router/node": "^8.3.0",
                 "iconoir-react": "^7.11.1",
                 "isbot": "^5.2.1",
+                "leaflet": "^1.9.4",
                 "react": "^19.2.8",
                 "react-dom": "^19.2.8",
                 "react-hook-form": "^7.86.0",
                 "react-hot-toast": "^2.6.0",
+                "react-leaflet": "^5.0.0-rc.2",
                 "react-router": "^8.3.0",
                 "zod": "^4.4.3"
             },
@@ -33,6 +35,7 @@
                 "@storybook/react-vite": "^10.2.19",
                 "@tailwindcss/postcss": "^4.2.1",
                 "@types/express": "^5.0.6",
+                "@types/leaflet": "^1.9.22",
                 "@types/node": "^25.5.2",
                 "@types/react": "^19.2.18",
                 "@types/react-dom": "^19.2.4",
@@ -2301,6 +2304,17 @@
                 "react-dom": "^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1"
             }
         },
+        "node_modules/@react-leaflet/core": {
+            "version": "3.0.0",
+            "resolved": "https://registry.npmjs.org/@react-leaflet/core/-/core-3.0.0.tgz",
+            "integrity": "sha512-3EWmekh4Nz+pGcr+xjf0KNyYfC3U2JjnkWsh0zcqaexYqmmB5ZhH37kz41JXGmKzpaMZCnPofBBm64i+YrEvGQ==",
+            "license": "Hippocratic-2.1",
+            "peerDependencies": {
+                "leaflet": "^1.9.0",
+                "react": "^19.0.0",
+                "react-dom": "^19.0.0"
+            }
+        },
         "node_modules/@react-router/dev": {
             "version": "8.3.0",
             "resolved": "https://registry.npmjs.org/@react-router/dev/-/dev-8.3.0.tgz",
@@ -3558,6 +3572,13 @@
                 "@types/send": "*"
             }
         },
+        "node_modules/@types/geojson": {
+            "version": "7946.0.16",
+            "resolved": "https://registry.npmjs.org/@types/geojson/-/geojson-7946.0.16.tgz",
+            "integrity": "sha512-6C8nqWur3j98U6+lXDfTUWIfgvZU+EumvpHKcYjujKH7woYyLj2sUmff0tRhrqM7BohUw7Pz3ZB1jj2gW9Fvmg==",
+            "dev": true,
+            "license": "MIT"
+        },
         "node_modules/@types/http-errors": {
             "version": "2.0.5",
             "resolved": "https://registry.npmjs.org/@types/http-errors/-/http-errors-2.0.5.tgz",
@@ -3572,6 +3593,16 @@
             "dev": true,
             "license": "MIT"
         },
+        "node_modules/@types/leaflet": {
+            "version": "1.9.22",
+            "resolved": "https://registry.npmjs.org/@types/leaflet/-/leaflet-1.9.22.tgz",
+            "integrity": "sha512-h3lhECYEKDasG7LFHu+GiHqAvsgLuQvlJvVZzJDGONo3sEL+wUOqSFLnwkZlK0qVxnxbuGFW8iBlJNYs5wgndA==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "@types/geojson": "*"
+            }
+        },
         "node_modules/@types/mdx": {
             "version": "2.0.14",
             "resolved": "https://registry.npmjs.org/@types/mdx/-/mdx-2.0.14.tgz",
@@ -7685,6 +7716,12 @@
                 "json-buffer": "3.0.1"
             }
         },
+        "node_modules/leaflet": {
+            "version": "1.9.4",
+            "resolved": "https://registry.npmjs.org/leaflet/-/leaflet-1.9.4.tgz",
+            "integrity": "sha512-nxS1ynzJOmOlHp+iL3FyWqK89GtNL8U8rvlMOsQdTTssxZwCXh8N2NB3GDQOL+YR3XnWyZAxwQixURb+FA74PA==",
+            "license": "BSD-2-Clause"
+        },
         "node_modules/levn": {
             "version": "0.4.1",
             "resolved": "https://registry.npmjs.org/levn/-/levn-0.4.1.tgz",
@@ -9061,6 +9098,20 @@
             "dev": true,
             "license": "MIT"
         },
+        "node_modules/react-leaflet": {
+            "version": "5.0.0-rc.2",
+            "resolved": "https://registry.npmjs.org/react-leaflet/-/react-leaflet-5.0.0-rc.2.tgz",
+            "integrity": "sha512-1xQGYG9mEIW+nfkQhqgHImwUuB1UDlnzYFSzv6PrBFDBeYrFmv0BbpwpNAFdJg/UQ2yz5UZSL7ZwlUxjwb8MZw==",
+            "license": "Hippocratic-2.1",
+            "dependencies": {
+                "@react-leaflet/core": "^3.0.0-rc.2"
+            },
+            "peerDependencies": {
+                "leaflet": "^1.9.0",
+                "react": "^19.0.0",
+                "react-dom": "^19.0.0"
+            }
+        },
         "node_modules/react-refresh": {
             "version": "0.18.0",
             "resolved": "https://registry.npmjs.org/react-refresh/-/react-refresh-0.18.0.tgz",

web/frontend/package.json

@@ -25,10 +25,12 @@
         "@react-router/node": "^8.3.0",
         "iconoir-react": "^7.11.1",
         "isbot": "^5.2.1",
+        "leaflet": "^1.9.4",
         "react": "^19.2.8",
         "react-dom": "^19.2.8",
         "react-hook-form": "^7.86.0",
         "react-hot-toast": "^2.6.0",
+        "react-leaflet": "^5.0.0-rc.2",
         "react-router": "^8.3.0",
         "zod": "^4.4.3"
     },
@@ -43,6 +45,7 @@
         "@storybook/react-vite": "^10.2.19",
         "@tailwindcss/postcss": "^4.2.1",
         "@types/express": "^5.0.6",
+        "@types/leaflet": "^1.9.22",
         "@types/node": "^25.5.2",
         "@types/react": "^19.2.18",
         "@types/react-dom": "^19.2.4",

web/frontend/stories/BreweryCard.stories.tsx

@@ -0,0 +1,102 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, within } from 'storybook/test';
+import BreweryCard from '../app/features/breweries/components/BreweryCard';
+import type { Brewery, BreweryLocation } from '../app/features/breweries/breweries.server';
+import { formatBreweryAddress } from '../app/features/breweries/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 →', exact: true });
+        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();
+    },
+};

web/frontend/stories/BreweryMap.stories.tsx

@@ -0,0 +1,61 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import BreweryMap, { type BreweryMapPin } from '../app/features/breweries/components/BreweryMap';
+import type { BreweryLocation } from '../app/features/breweries/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: [] },
+};

web/frontend/stories/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 '../app/features/breweries/components/FeaturedBreweryCard';
+import type { Brewery, BreweryLocation } from '../app/features/breweries/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();
+    },
+};

web/frontend/stories/NearbyBreweriesSection.stories.tsx

@@ -0,0 +1,183 @@
+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 '../app/features/breweries/components/NearbyBreweriesSection';
+import type {
+    BreweryLocation,
+    SimplifiedBrewery,
+} from '../app/features/breweries/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 },
+        );
+    },
+};

web/frontend/stories/NearbyBreweryMap.stories.tsx

@@ -0,0 +1,66 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import NearbyBreweryMap, {
+    type NearbyMapPin,
+} from '../app/features/breweries/components/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',
+    },
+};

web/frontend/stories/PasswordSection.stories.tsx

@@ -14,7 +14,11 @@ const PasswordSectionRoute = () => {
 
     return (
         <div className="w-full max-w-md">
-            <PasswordSection open={open} onToggle={() => setOpen((value) => !value)} result={result} />
+            <PasswordSection
+                open={open}
+                onToggle={() => setOpen((value) => !value)}
+                result={result}
+            />
         </div>
     );
 };

web/frontend/stories/RecentBreweries.stories.tsx

@@ -0,0 +1,93 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, within } from 'storybook/test';
+import RecentBreweries from '../app/features/breweries/components/RecentBreweries';
+import type { Brewery, BreweryLocation } from '../app/features/breweries/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();
+    },
+};