m038andClaude Opus 5
8202d2a257
Five weeks of undocumented evolution left the docs describing a site that
partly no longer exists, with nothing marking which documents were historical.
The code is treated as the source of truth throughout; every claim below was
verified against code, config or the Makefile rather than inferred.
Two mechanisms, following patterns the repo already used:
- docs/reference/superseded-decisions.md (new) — one authoritative table of all
14 reversals: what was planned, where, what is true now, when, and why. Plus
a short list of decisions that were NOT reversed, since their planning docs
are old enough to look suspect.
- Inline "> **Superseded ...**" notes at each stale claim, so a claim can never
be read un-corrected. This mirrors the existing "> History:" notes in
architecture.md and "> **Changed 2026-07:**" in trip-switching.md.
Scope split by tense: present-tense docs (CLAUDE.md, reference/, guides/,
README.md, CONCEPTS.md) are corrected; past-tense records (plans/, specs/,
milestones/, summary.md, pm-analysis.md) are annotated only, never rewritten —
their staleness is what makes them records.
Present-tense corrections:
- CLAUDE.md asserted css-compiled/ is generated from css/style.css and
css/tokens.css. That source relationship does not exist: css/ is hand-authored
and served directly via assets.addCss in partials/base.html.twig, while
css-compiled/ is esbuild output from the CSS imports inside js/src/*.js.
Highest-severity finding — an always-loaded file inviting a hand-edit of a
generated bundle.
- README.md documented every remote-* target without the -test/-prod suffix
guard-env requires, so its entire server runbook was unrunnable, and listed
7 of ~20 targets while CLAUDE.md designates it authoritative for the full
list. Rewritten with all targets, grouped, and the suffix rule stated.
- README.md told readers to "git clone" into user/, which is a submodule.
- architecture.md: nav is Home + Trips + (authenticated) New Post, not
"Home + Past Trips only"; template tree omitted trips.html.twig,
post-form.html.twig and forms/, and placed base.html.twig at templates/ root
rather than in partials/; entry-actions has three API routes, not just delete;
added the undocumented css-compiled/maplibre-gl.css output and a section on
the /post pin editor as the one sanctioned non-entry-map map.
- design-system.md: documented 13 colour tokens against 19 in tokens.css
(missing --color-error, --color-draft-accent and four glass overlays); claimed
"all 3 map templates"; and described --color-canvas as "white".
- design-system-light.md documented a light palette in present tense. No light
mode exists — tokens.css has a single :root block, no prefers-color-scheme or
data-theme switch, and no light hex appears in css/. Banner added.
- posting.md said photos were optional; they are required, 1-6. It documented
hero_image, which was removed for entries (stories keep it). It had no mention
of the frontend edit flow or photo editor, both shipped 2026-07-08. Photo
files are photo-01..NN, zero-padded.
- working/README.md advertised summary.md as the project's "current state" while
summary.md describes Leaflet, /tracker, /map and /stats. Most misleading line
in the tree.
- CLAUDE.md: recorded js/src/location-map.js as the one sanctioned exception to
the single-map-path rule, and documented that make start/setup fail on a clean
checkout because docker-compose.yml still builds a travel-memories service
whose source moved out in a80b0a9.
Also: 2026-07-23-post-form-location-override.md read "Not started" while merged
in user/ as dd19995; status corrected.
Findings that are not documentation problems — the compose breakage, a
repeatable drift check, the unused shortcode-gallery-plusplus, and demo fixtures
for retired views — are collected in
docs/working/2026-07-25-doc-drift-recommendations.md and deliberately not acted
on. Design and verification method: docs/working/specs/2026-07-25-docs-reconciliation-design.md
The submodule gitlink is deliberately not bumped.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
106 lines
4.1 KiB
Markdown
106 lines
4.1 KiB
Markdown
# Milestone 4 Spec — Mini-Map on Tracker Feed
|
|
|
|
**Goal:** Embed a compact interactive map above the entry feed on the tracker page, showing recent entry positions and the current location, giving readers immediate spatial context.
|
|
|
|
> **Superseded — written 2026-06-21. The idea won; this implementation did not.**
|
|
>
|
|
> A map beside the feed is exactly what the site does now — but not as a separate "mini-map":
|
|
> - **No `/tracker` page** to embed it above (R3). The map sits in a column on the trip page and the
|
|
> home active-trip view.
|
|
> - **No second map implementation.** This spec's `feed-map` variant with its own inline init was
|
|
> deleted; everything goes through the one shared `partials/entry-map.html.twig` +
|
|
> `MapUtils.initEntryMap()` path (R12, consolidated 2026-06-27). Adding a second display map is
|
|
> forbidden by `CLAUDE.md`.
|
|
> - **Leaflet → MapLibre GL JS** (R4), so §4.1's `if (typeof L === 'undefined')` guard is obsolete.
|
|
> - **No "View full map →" link** — there is no full map page to link to (R1).
|
|
>
|
|
> Details: [`../../reference/superseded-decisions.md`](../../reference/superseded-decisions.md).
|
|
|
|
---
|
|
|
|
## User Stories
|
|
|
|
- As a reader landing on the tracker feed, I want to immediately see where Mischa currently is without having to navigate to the full map page.
|
|
- As a reader, I want to click a marker on the mini-map and jump to that entry.
|
|
- As a traveler (Mischa), I want the feed page to feel like a live travel dashboard, not just a blog list.
|
|
|
|
---
|
|
|
|
## Feature Details
|
|
|
|
### 4.1 — Mini-Map Placement
|
|
|
|
**Where:** At the top of `tracker.html.twig`, before the entry card list.
|
|
|
|
**Height:** 240px on mobile, 320px on desktop.
|
|
|
|
**Width:** Full width of content column (max 680px).
|
|
|
|
**Tile layer:** Same OpenStreetMap tiles as Milestone 2.
|
|
|
|
**No duplicate Leaflet load:** Leaflet is already loaded on the map page; on the tracker page, load it only if needed. Check with `if (typeof L === 'undefined')` before initializing. (In practice, the CSS and JS are loaded unconditionally from the same CDN — caching handles it.)
|
|
|
|
---
|
|
|
|
### 4.2 — What's Shown
|
|
|
|
- **All entries with GPS** shown as small markers (not just recent 10 — the map auto-fits to bounds)
|
|
- **Route line** connecting them in chronological order (same style as Milestone 2)
|
|
- **Most recent marker** highlighted (larger, brighter)
|
|
- **No popups by default** — tapping a marker links directly to the entry (no popup intermediary for the mini-map, keeps it fast)
|
|
- Map auto-fits bounds to all markers; if only 1 marker, zoom to 10
|
|
|
|
---
|
|
|
|
### 4.3 — Interaction
|
|
|
|
- Tap/click marker → navigate to entry URL directly
|
|
- Map is pannable and zoomable (same touch handling as M2)
|
|
- "View full map →" link below the mini-map → navigates to `/map`
|
|
|
|
---
|
|
|
|
### 4.4 — Entry Data
|
|
|
|
Same JSON serialization as Milestone 2 (embed `TRACKER_ENTRIES` in the Twig template). This can reuse the same data variable name if both map and tracker pages use the same template pattern.
|
|
|
|
---
|
|
|
|
### 4.5 — Empty State
|
|
|
|
If no entries have GPS coordinates:
|
|
- Mini-map hidden entirely (don't show an empty world map on the feed page)
|
|
- Entry list still shows normally
|
|
|
|
---
|
|
|
|
## Out of Scope (Milestone 4)
|
|
|
|
- Clustering markers at low zoom
|
|
- Filtering by date
|
|
- Satellite/terrain tile layers
|
|
- Search on the mini-map
|
|
|
|
---
|
|
|
|
## Acceptance Criteria
|
|
|
|
1. Mini-map appears above entry cards on the tracker feed page
|
|
2. All entries with valid lat/lng appear as markers on the mini-map
|
|
3. Route line connects markers in date order
|
|
4. Most recent marker is visually distinct
|
|
5. Clicking/tapping a marker navigates directly to that entry
|
|
6. "View full map →" link appears below the mini-map and routes to `/map`
|
|
7. If no entries have GPS, mini-map is hidden and entry list shows normally
|
|
8. Mini-map is pannable and zoomable by touch on mobile
|
|
9. Mini-map does not block page scrolling on mobile (map is fixed height, not full-screen)
|
|
|
|
---
|
|
|
|
## Design Notes
|
|
|
|
- Mini-map border-radius should match the card design (8px)
|
|
- Light 1px border or subtle shadow to separate from content
|
|
- "View full map →" in small muted text, right-aligned
|
|
- Keep the mini-map lightweight: same Leaflet instance, no additional plugins
|