Timeline destination: the same-spot photo strip (#162)

.agents/skills/ask-matt/PHASE-BOUNDARIES.md

@@ -0,0 +1,55 @@
+# Phase boundaries
+
+A **phase** is a chunk of work inside a session — the grilling, the implementation, the QA. The definition is fuzzy on purpose: a phase ends when you think *"ok, we're done with that"*.
+
+The **phase boundary** is the gap between two phases, and it is the only place this decision belongs. Mid-phase there is no decision to make — continue, or split the work that's left into subagents. Compacting mid-phase makes the agent lose the thread.
+
+## The five options
+
+| Option       | What it does                                                    |
+| ------------ | --------------------------------------------------------------- |
+| **Continue** | Stay in the session. No context switch at all.                    |
+| **`/clear`** | Empty the context window and start from nothing.                  |
+| **`/handoff`** | Write a portable markdown file and seed a session anywhere with it. |
+| **Subagent** | Send the task to its own context window and get a report back.     |
+| **`/compact`** | Compress this context and seed a fresh session with the summary.  |
+
+## The tree
+
+Work top to bottom at the boundary. The first **yes** wins.
+
+**1. Can you continue in this session?** Two things make the answer yes: the next phase needs this phase as a **primary source**, or you have enough [smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone) left (~150k tokens) for the next phase to fit. Grilling → implementation is the standard yes: the implementation wants the reasoning verbatim, not a summary of it. Continue costs nothing and loses nothing, so rule it out before anything else.
+
+**2. Is the context irrelevant to what comes next?** Is everything in this session — the exploration, the decisions, the dead ends — disposable? If so, **`/clear`**. It is the cheapest move on the board: it takes no time and hands back the whole window. `/clear` also isn't terminal — the old session stays resumable.
+
+The cost of getting this wrong is one-way. Clear a *relevant* context and you lose the **why** behind what you built, and no amount of reading the diff back gets it returned.
+
+**3. Do you need to hand off?** `/handoff` is narrow. You need it only when you are:
+
+- swapping to a **new harness** (Claude → Codex),
+- moving to a **new directory** or repo,
+- sending the work to a **colleague**,
+- or forking a side task you found **mid-phase** without derailing what you're doing.
+
+That list is the whole clause. What `/handoff` buys is **portability** — a file that travels. If nothing is travelling, you don't need it.
+
+**4. Can the task be done AFK?** Is it scoped tightly enough to run with you away from the keyboard, no steering? Then send it to a **subagent** and leave this session untouched. Automated review is the standard case: the agent reads the diff and reports, and you aren't needed while it does.
+
+**5. Otherwise, `/compact`.** Relevant context, same harness, same directory, and you need to stay in the loop — this is where the tree lands, and it lands here often. Pass it an instruction (`/compact we're going to QA this area`) so the summary keeps what the next phase needs.
+
+`/compact` is the **default, not the first reach**. It sits at the bottom because the four questions above it are all cheaper or more precise. The failure mode when people start here is a fresh session that is confidently wrong about a decision the summary flattened.
+
+## Primary and secondary sources
+
+Every move except **Continue** turns a **primary source** into a **secondary source** — the session as it happened, replaced by a summary of it. The trade is always the same shape:
+
+| Source                            | Information | Noise | Room to move |
+| --------------------------------- | ----------- | ----- | ------------ |
+| Primary (Continue)                | Full        | Lots  | Little       |
+| Secondary (`/compact`, `/handoff`) | Lossy       | Less  | Lots         |
+
+This is why question 1 comes first. You only pay the lossiness when staying costs more than it saves.
+
+## These are judgement calls
+
+The questions are not objective — each has taste in it, and the same boundary can go two ways on two days. The value is in asking them **in order**, at the boundary rather than in the middle of the work.

app/globals.css

@@ -2760,6 +2760,64 @@ footer {
   cursor: default;
 }
 
+.timeline-frames {
+  list-style: none;
+  margin: 0.9rem 0 0;
+  padding: 0;
+  display: flex;
+  gap: 0.6rem;
+  overflow-x: auto;
+}
+
+.timeline-frame {
+  flex: 0 0 auto;
+  width: 8.5rem;
+  display: grid;
+  gap: 0.35rem;
+  border: 1px solid var(--line);
+  border-radius: 6px;
+  padding: 0.45rem;
+  background: var(--surface-raised);
+}
+
+.timeline-frame-photo {
+  width: 100%;
+  height: 6rem;
+  object-fit: cover;
+  border-radius: 4px;
+}
+
+.timeline-frame-placeholder {
+  display: grid;
+  place-items: center;
+  height: 6rem;
+  border-radius: 4px;
+  background: rgba(138, 109, 31, 0.25);
+  color: var(--muted);
+  font-size: 0.7rem;
+  overflow: hidden;
+  padding: 0 0.3rem;
+  text-align: center;
+}
+
+.timeline-frame-meta {
+  display: flex;
+  justify-content: space-between;
+  font-family: var(--font-mono);
+  font-size: 0.7rem;
+  color: var(--muted);
+}
+
+.timeline-frame-remove {
+  border: 1px solid var(--line-strong);
+  border-radius: 4px;
+  background: transparent;
+  color: var(--ink);
+  font-size: 0.72rem;
+  padding: 0.3rem 0.4rem;
+  cursor: pointer;
+}
+
 .journal-gps-dot {
   width: 16px;
   height: 16px;

components/map-journal.tsx

@@ -19,11 +19,24 @@ import {
 } from "@/lib/offline-region/download-copy";
 import {
   addCaptureMarkerLayers,
+  addTimelineSpotLayers,
   CLUSTER_LAYER,
   MARKER_LAYER,
+  TIMELINE_SPOT_LAYER,
   updateCaptureMarkers,
+  updateTimelineSpots,
 } from "@/lib/map-journal/map-layers";
 import { captureMarkers } from "@/lib/map-journal/markers";
+import {
+  removedFrameCaptureIds,
+  removeFrame,
+} from "@/lib/map-journal/timeline-removals";
+import {
+  timelineSpotMarkers,
+  timelineSpots,
+  type TimelineSpot,
+} from "@/lib/map-journal/timeline-spots";
+import { TimelineStrip } from "@/components/timeline-strip";
 import {
   resolveJournalRegion,
   resolveRegionBaseUrl,
@@ -62,8 +75,11 @@ export type MapJournalHook = {
   /** Which pack renders: installed ("local"), streamed ("remote"), or null. */
   source: "local" | "remote" | null;
   markerCount: number;
+  /** Same-spot Timeline strips currently on the map (docs/desk.md, D2). */
+  timelineSpotCount: number;
   gps: GpsState;
   selectedCaptureId: string | null;
+  openTimelineSpotId: string | null;
   refreshMarkers: () => Promise<void>;
 };
 
@@ -86,8 +102,11 @@ export function MapJournal() {
     typeof navigator === "undefined" ? true : navigator.onLine,
   );
   const [context, setContext] = useState<ThreadContext | null>(null);
+  const [spot, setSpot] = useState<TimelineSpot | null>(null);
   const [error, setError] = useState<string | null>(null);
   const [markerCount, setMarkerCount] = useState(0);
+  const [spotCount, setSpotCount] = useState(0);
+  const spotsRef = useRef<TimelineSpot[]>([]);
 
   const containerRef = useRef<HTMLDivElement | null>(null);
   const mapRef = useRef<import("maplibre-gl").Map | null>(null);
@@ -134,22 +153,56 @@ export function MapJournal() {
     source: null as "local" | "remote" | null,
     gps,
     markerCount,
+    spotCount,
     selected: null as string | null,
+    openSpot: null as string | null,
   });
 
+  // Same-spot strips cluster from whatever the store holds right now — no
+  // manual setup, routing a photo Thread to the Timeline is the only input.
+  const loadTimelineSpots = useCallback(async () => {
+    const store = getCaptureStore();
+    const [captures, threads] = await Promise.all([
+      store.list(),
+      store.listRecentThreads(),
+    ]);
+    const spots = timelineSpots(threads, captures, removedFrameCaptureIds());
+    spotsRef.current = spots;
+    setSpotCount(spots.length);
+    return spots;
+  }, []);
+
   const refreshMarkers = useCallback(async () => {
     const captures = await getCaptureStore().list();
     const markers = captureMarkers(captures);
     setMarkerCount(markers.features.length);
-    if (mapRef.current) updateCaptureMarkers(mapRef.current, markers);
-  }, []);
+    const spots = await loadTimelineSpots();
+    if (mapRef.current) {
+      updateCaptureMarkers(mapRef.current, markers);
+      updateTimelineSpots(mapRef.current, timelineSpotMarkers(spots));
+    }
+    // Keep an open strip current — same spot if it still holds any of its
+    // frames (its founding Capture may have been removed), gone otherwise.
+    setSpot((current) => {
+      if (!current) return current;
+      const captureIds = new Set(
+        current.frames.map((frame) => frame.captureId),
+      );
+      return (
+        spots.find((candidate) =>
+          candidate.frames.some((frame) => captureIds.has(frame.captureId)),
+        ) ?? null
+      );
+    });
+  }, [loadTimelineSpots]);
 
   const openCapture = useCallback(async (captureId: string) => {
     const store = getCaptureStore();
     const captures = await store.list();
     const capture = captures.find((item) => item.id === captureId);
     if (!capture) return;
 
+    setSpot(null);
     if (!capture.threadId) {
       setContext({ capture, thread: null, captures: [capture], enrichments: [] });
       return;
@@ -159,16 +212,33 @@ export function MapJournal() {
     setContext({ capture, ...view, enrichments });
   }, []);
 
+  const openSpot = useCallback((spotId: string) => {
+    const found = spotsRef.current.find((candidate) => candidate.id === spotId);
+    if (!found) return;
+    setContext(null);
+    setSpot(found);
+  }, []);
+
+  const removeSpotFrame = useCallback(
+    (captureId: string) => {
+      removeFrame(captureId);
+      void refreshMarkers();
+    },
+    [refreshMarkers],
+  );
+
   // Expose the journal to the Playwright seam.
   useEffect(() => {
     hookRef.current = {
       state: state.phase,
       source: state.phase === "ready" ? state.source : null,
       gps,
       markerCount,
+      spotCount,
       selected: context?.capture.id ?? null,
+      openSpot: spot?.id ?? null,
     };
-  }, [state, gps, markerCount, context]);
+  }, [state, gps, markerCount, spotCount, context, spot]);
 
   useEffect(() => {
     window.__WT_MAP_JOURNAL__ = {
@@ -181,12 +251,18 @@ export function MapJournal() {
       get markerCount() {
         return hookRef.current.markerCount;
       },
+      get timelineSpotCount() {
+        return hookRef.current.spotCount;
+      },
       get gps() {
         return hookRef.current.gps;
       },
       get selectedCaptureId() {
         return hookRef.current.selected;
       },
+      get openTimelineSpotId() {
+        return hookRef.current.openSpot;
+      },
       refreshMarkers,
     };
   }, [refreshMarkers]);
@@ -297,14 +373,27 @@ export function MapJournal() {
       const captures = await getCaptureStore().list();
       const markers = captureMarkers(captures);
       setMarkerCount(markers.features.length);
+      const spots = await loadTimelineSpots();
 
       const attach = () => {
         addCaptureMarkerLayers(map, markers);
+        addTimelineSpotLayers(map, timelineSpotMarkers(spots));
         map.on("click", MARKER_LAYER, (event) => {
+          // The spot ring draws above the Capture markers; when a tap lands
+          // on both, the strip is what the walker aimed for.
+          const spotsHit = map.queryRenderedFeatures(event.point, {
+            layers: [TIMELINE_SPOT_LAYER],
+          });
+          if (spotsHit.length > 0) return;
           const feature = event.features?.[0];
           const captureId = feature?.properties?.captureId as string | undefined;
           if (captureId) void openCapture(captureId);
         });
+        map.on("click", TIMELINE_SPOT_LAYER, (event) => {
+          const feature = event.features?.[0];
+          const spotId = feature?.properties?.spotId as string | undefined;
+          if (spotId) openSpot(spotId);
+        });
         map.on("click", CLUSTER_LAYER, (event) => {
           const feature = event.features?.[0];
           if (!feature) return;
@@ -314,7 +403,7 @@ export function MapJournal() {
             zoom: Math.min(map.getZoom() + 2, 17),
           });
         });
-        for (const layer of [MARKER_LAYER, CLUSTER_LAYER]) {
+        for (const layer of [MARKER_LAYER, CLUSTER_LAYER, TIMELINE_SPOT_LAYER]) {
           map.on("mouseenter", layer, () => {
             map.getCanvas().style.cursor = "pointer";
           });
@@ -339,7 +428,7 @@ export function MapJournal() {
       mapRef.current = null;
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps -- readySource flips remote→local without a remount
-  }, [readyManifest, baseUrl, region, openCapture, placeGpsPin]);
+  }, [readyManifest, baseUrl, region, openCapture, openSpot, loadTimelineSpots, placeGpsPin]);
 
   // Live GPS from the moment the surface opens — including while a pack
   // downloads — so the permission prompt and first fix land before the map
@@ -424,7 +513,7 @@ export function MapJournal() {
         : "GPS starting…";
 
   return (
-    <div className="journal" data-selected={context ? "true" : "false"}>
+    <div className="journal" data-selected={context || spot ? "true" : "false"}>
       <SyncRuntime />
       <header className="journal-topbar">
         <Link className="brand" href="/" aria-label="Walking Thoughts home">
@@ -548,9 +637,15 @@ export function MapJournal() {
           <aside
             className="journal-panel"
             aria-label="Thread context"
-            hidden={!context}
+            hidden={!context && !spot}
           >
-            {context?.thread ? (
+            {spot ? (
+              <TimelineStrip
+                spot={spot}
+                onRemoveFrame={removeSpotFrame}
+                onClose={() => setSpot(null)}
+              />
+            ) : context?.thread ? (
               <ThreadChat
                 threadId={context.thread.id}
                 embedded