fix: smoother Cesium globe (on-demand render) + Polaroid-framed photo pins

- 3D globe: enable requestRenderMode (+MSAA, camera inertia) to fix choppy
rendering when idle; journey flythrough toggles continuous render while it runs.
- 3D globe: replace bare square billboards + caption labels with larger
Polaroid-framed photo pins (white frame, soft shadow) composed on a canvas.
- 2D map: ease-in-out camera easing on journey flyTo/fitBounds for smoother travel.
- docs: add product-overview video script.

docs/video_script.md

@@ -0,0 +1,225 @@
+# Sozai — Product Overview Video
+
+A walkthrough script and narrative guide for a short product overview of Sozai.
+
+**Format:** ~2.5–3 minutes. Mostly **voiceover** over screen recordings and a few
+PowerPoint-style slides. **Two narrators (A and B) taking turns** — conversational,
+warm, informative. Not a dramatized film; think "two people who built this giving
+you the tour." Keep it relaxed and clear.
+
+---
+
+## The one-sentence pitch
+
+> Sozai turns the photos buried in your camera roll into watercolour memories you develop with your companions: like a shared, modern darkroom.
+
+**What the name means:** 素材 (*sozai*) is Japanese for "raw material / ingredients."
+Your snapshots are the raw material; the memory is what you make from them. Worth
+saying once in the video — it frames everything.
+
+**The core metaphor** the whole product runs on: **analog film photography.** You
+don't "post," you *develop*. There's a real darkroom, chemical trays, prints on a
+line, and you shake each one to reveal it. That metaphor is the brand — lean on it.
+
+---
+
+## The two narrators
+
+- **A** — frames the "why" and the feeling (the camera-roll problem, the togetherness).
+- **B** — drives the "how" and the features (rooms, develop, views, the AI parts).
+
+They trade off naturally. Lines are written to be read plainly, not performed.
+
+---
+
+## The script
+
+Each beat = **[slide or screen cue]** + the spoken lines. Screen names match the
+real app so you can record straight from it.
+
+### 1. Open — the problem (slide)
+
+**[SLIDE: a dense grid of phone photo thumbnails, greyed out. Sozai bird logo in corner.]**
+
+> **A:** Most of us take hundreds of photos on a trip — and then never look at them
+> again. They just sit in the camera roll.
+
+> **B:** That's the problem we kept running into. So we built Sozai — a place to
+> actually *do something* with those photos, with the people you took them with.
+
+**[SLIDE: the word "素材 — raw material" fades in under the Sozai logo.]**
+
+> **A:** "Sozai" means "raw material." Your photos are the raw material. The memory
+> is what you make out of them.
+
+### 2. Getting in — rooms (screen: landing page)
+
+**[SCREEN: the Sozai landing page — bird, map lines, "build memories together".]**
+
+> **B:** When you open Sozai, you can start a room and invite someone, join a room
+> with a short code, or just go solo.
+
+**[SCREEN: click "make a room" → a short share code appears. Cut to a second
+window: someone types the code into "enter room code" and clicks join. Two named
+cursors now move on the same screen.]**
+
+> **A:** Here's the part we love — it's live. Two people, two cities, same room.
+> You can see each other's cursors and edits as they happen.
+
+> **B:** Or pick "continue without a room" and it's just you. Same app, no invite
+> needed.
+
+### 3. Adding photos + captions (screen: Develop Photos)
+
+**[SCREEN: the "Develop Photos" page — photo stack on the left, Title / Caption /
+When & Where on the right.]**
+
+> **B:** You drop in your photos — up to eight at a time — and give them a title
+> and a caption.
+
+**[SCREEN: click the mic icon on the caption field; speak; text appears.]**
+
+> **A:** You can type, or just talk. The mic transcribes what you say, so captioning
+> a photo feels more like telling someone about it.
+
+**[SCREEN: click "Auto-generate"; the stages tick by: "Reading the light… Finding
+the words…"; a caption fills in.]**
+
+> **B:** Or let the AI take a look and suggest one. It's actually looking at the
+> photo — so the title, caption, and tags match what's really in the picture.
+
+### 4. Choosing how it renders (screen: Views grid)
+
+**[SCREEN: the "Views" picker — 2D Map, 3D Globe, Canvas, Scrapbook, Gallery,
+Timeline.]**
+
+> **A:** Before you develop, you choose how your memories will be laid out — on a
+> map, a spinning globe, a scrapbook, a gallery, or a timeline.
+
+> **B:** And this isn't a one-time choice — you can switch any time. Hold that
+> thought, because it's the part we care about most.
+
+### 5. The darkroom — the heart (screen: Darkroom)
+
+**[SCREEN: click "Develop Photos →". The Darkroom: four glowing trays —
+Developer, Stop Bath, Fixer, Wash. Status line: "giving your photos an acid rinse…"]**
+
+> **B:** When you hit develop, your photos go through a darkroom. This is where each
+> one is painted into a watercolour.
+
+**[SCREEN: the prints hang on a line. Status: "shake each print to reveal it." A
+blank print reads "developed — shake me"; it's shaken and the watercolour appears.]**
+
+> **A:** And then you reveal them — you literally shake each print until the picture
+> comes through. It's a small thing, but it makes you slow down and actually *look*.
+
+**[SCREEN: optional — show one original photo next to its finished watercolour.]**
+
+> **B:** Same photo, now a painting. That's the "develop."
+
+### 6. The payoff — one memory, many ways (screen: 2D Map, then cycle)
+
+*This is the most important beat in the video. The core feature isn't any single
+view — it's that the **same memories can be reimagined in many ways**, interactively.
+Anchor on the **2D Map** (it's the most stable to record), then briefly cycle the rest.*
+
+**[SCREEN: developed watercolours pinned on the 2D Map — the stable hero shot.
+Pan and zoom around the pins; drag a polaroid to reposition it.]**
+
+> **A:** Once they're developed, your memories land in the view you picked. Here
+> they're pinned on the map, right where you took them — and you can move them
+> around, zoom in, make it yours.
+
+**[SCREEN: switch views and briefly cycle — 3D Globe → Scrapbook scroll → Timeline
+→ Gallery — the same photos re-laid-out each time, a beat on each.]**
+
+> **B:** And this is really the heart of Sozai: the *same* memories, reimagined as
+> many ways as you like. Spin them on a globe, scroll them as a scrapbook, walk them
+> down a timeline, browse them as a gallery — one click each.
+
+> **A:** Nothing's locked in. You keep rearranging until it feels like yours.
+
+### 7. Together + close
+
+**[SCREEN: the share code is sent to a third person; a new named cursor joins the room.]**
+
+> **A:** And because it's a room, you can hand the code to someone else and keep
+> building it together — even after the trip's over.
+
+**[SLIDE: Sozai logo + "develop your memories together" + "素材 — the raw material of memory".]**
+
+> **B:** That's Sozai. Bring a few photos back to life — together.
+
+---
+
+## Optional add-ons (for a longer / more technical cut)
+
+- **Under the hood slide.** One slide for a technical audience: photos are painted
+  by FLUX.2-klein with a watercolour style, captions come from the MiniCPM-V vision
+  model, voice is transcribed by NVIDIA NeMo, and every uploaded photo passes a
+  safety check first.
+- **LLM Trace panel.** Sozai has a built-in trace view (Phoenix) showing every model
+  call, its latency, and tokens — good for a "yes, it's real and observable" beat.
+- **The hidden pet.** A little sprite that follows your cursor around the scrapbook —
+  a nice "did you catch that?" detail if the tone allows.
+
+---
+
+## Who it's for (personas — for framing, not necessarily on screen)
+
+- **Two friends after a trip** *(the hero use case; our sample photos are a Toronto
+  trip).* They develop the trip together from two cities.
+- **Family across distance.** One shared album spanning continents — the globe view
+  shines here.
+- **The solo journaler.** "Continue without a room" — a quiet afternoon turning last
+  month's photos into a watercolour scrapbook.
+
+---
+
+## High-leverage copy recommendations
+
+Small wording changes that tighten the story. Each is **current → suggested**.
+Listed by impact. (Not yet applied — review first.)
+
+1. **Add a one-line "what is this" under the landing tagline.** Today the landing
+   shows only `Sozai / build memories together` with no explanation.
+   → add: **"Turn your camera roll into watercolour memories — together."**
+
+2. **Make "develop" the single signature verb.** The app already lives on it
+   (Develop Photos, The Darkroom, developing…). Consider the tagline:
+   `build memories together` → **"develop your memories together"** (*develop* = both
+   *film* and *grow*).
+
+3. **Pay off the name once, in-app.** Most people don't know 素材.
+   → add somewhere quiet: **"Sozai (素材) — the raw material of memory."**
+
+4. **Sharpen the reveal line.** `developed — shake me`
+   → **"still wet — give it a shake."**
+
+5. **Warm up the empty state.** Wherever a room/scrapbook starts empty:
+   → **"Nothing developed yet. Drop in a few photos and let's bring them back."**
+
+6. **Keep the verb on the solo path.** `CONTINUE WITHOUT A ROOM →`
+   → **"develop on your own →."**
+
+7. **Give the full view a closing line.** On the globe/scrapbook once populated:
+   → **"Every pin is a place you've been."**
+
+> Leave the existing playful copy as-is — *"giving your photos an acid rinse,"*
+> *"Reading the light… / Letting it soak… / Finding the words…"*, and the tray
+> names. That voice is the brand; the changes above just extend it.
+
+---
+
+## Maps
+
+**Decided:** the **2D Map is the anchor** for the §6 payoff (most stable to record).
+The 3D Globe and the other views are shown as a quick cycle right after, to make the
+point that the same memories can be reimagined many ways — the interactivity is the
+core feature, not any single view.
+
+Still to finalize when map footage arrives:
+
+- the recording pace of the cycle (how long to hold each view),
+- whether the pin-drop / drag-a-polaroid-on-the-map interaction gets its own spoken
+  line or just plays under A's "make it yours" line.

index.html

@@ -4485,10 +4485,13 @@
         } catch (e) {}
 
         const spd = (TRANSPORTS.find((t) => t.id === transport) || TRANSPORTS[0]).speed;
+        // gentle ease-in-out so every camera move accelerates and settles
+        // smoothly instead of starting/stopping abruptly (smoother travel).
+        const ease = (t) => (t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2);
         // start at the first stop
         setFlyIdx(0);
         setTransportAt(flyStops[0].lon, flyStops[0].lat);
-        map.flyTo({ center: [flyStops[0].lon, flyStops[0].lat], zoom: 15, pitch: 50, duration: 1400, essential: true });
+        map.flyTo({ center: [flyStops[0].lon, flyStops[0].lat], zoom: 15, pitch: 50, duration: 1600, curve: 1.42, easing: ease, essential: true });
         await new Promise((r) => setTimeout(r, 1500));
         if (!token.stop) await new Promise((r) => setTimeout(r, 1200)); // dwell on first photo
 
@@ -4514,13 +4517,13 @@
           });
           if (token.stop) break;
           setFlyIdx(i);
-          map.flyTo({ center: [b.lon, b.lat], zoom: 15.5, pitch: 55, duration: 1100, essential: true });
-          await new Promise((r) => setTimeout(r, 1300)); // dwell to show the photo
+          map.flyTo({ center: [b.lon, b.lat], zoom: 15.5, pitch: 55, duration: 1300, curve: 1.42, easing: ease, essential: true });
+          await new Promise((r) => setTimeout(r, 1400)); // dwell to show the photo
         }
 
         if (!token.stop && flyStops.length > 1) {
           const lons = flyStops.map((s) => s.lon), lats = flyStops.map((s) => s.lat);
-          try { map.fitBounds([[Math.min(...lons), Math.min(...lats)], [Math.max(...lons), Math.max(...lats)]], { padding: 90, pitch: 0, bearing: 0, duration: 2000 }); } catch (e) {}
+          try { map.fitBounds([[Math.min(...lons), Math.min(...lats)], [Math.max(...lons), Math.max(...lats)]], { padding: 90, pitch: 0, bearing: 0, duration: 2200, easing: ease }); } catch (e) {}
           await new Promise((r) => setTimeout(r, 2100));
         }
         // tidy up
@@ -4800,6 +4803,59 @@
     // Pinned album photos appear as billboards and the same timestamp-ordered
     // flythrough plays here too. Requires a Cesium ion token (server-provided).
     // ----------------------------------------------------------------- //
+
+    // Compose a photo into a small Polaroid-style card on a <canvas> so it can
+    // be used directly as a Cesium billboard image: white frame, a heavier
+    // bottom margin (the classic Polaroid look), and a soft drop shadow. No
+    // caption text - just the framed photo. Returns a Promise<HTMLCanvasElement>.
+    function makePolaroidCanvas(src, opts) {
+      opts = opts || {};
+      const photo = opts.photo || 168;     // inner photo square (device px)
+      const pad = opts.pad || 14;          // white border on top/left/right
+      const bottom = opts.bottom || 40;    // heavier bottom border
+      const margin = opts.margin || 12;    // breathing room for the shadow
+      return new Promise((resolve, reject) => {
+        const img = new Image();
+        img.crossOrigin = "anonymous";
+        img.onload = () => {
+          try {
+            const w = photo + pad * 2, h = photo + pad + bottom;
+            const cw = w + margin * 2, ch = h + margin * 2;
+            const cv = document.createElement("canvas");
+            cv.width = cw; cv.height = ch;
+            const ctx = cv.getContext("2d");
+            // soft shadow under the card
+            ctx.save();
+            ctx.shadowColor = "rgba(0,0,0,0.38)";
+            ctx.shadowBlur = 9; ctx.shadowOffsetY = 5;
+            ctx.fillStyle = "#fdfdf7";            // warm white card
+            const rx = margin, ry = margin, rr = 4;
+            ctx.beginPath();
+            ctx.moveTo(rx + rr, ry);
+            ctx.arcTo(rx + w, ry, rx + w, ry + h, rr);
+            ctx.arcTo(rx + w, ry + h, rx, ry + h, rr);
+            ctx.arcTo(rx, ry + h, rx, ry, rr);
+            ctx.arcTo(rx, ry, rx + w, ry, rr);
+            ctx.closePath(); ctx.fill();
+            ctx.restore();
+            // photo, object-fit: cover into the photo square
+            const dx = margin + pad, dy = margin + pad;
+            const ir = img.width / img.height, dr = 1; // square target
+            let sw, sh, sx, sy;
+            if (ir > dr) { sh = img.height; sw = sh * dr; sx = (img.width - sw) / 2; sy = 0; }
+            else { sw = img.width; sh = sw / dr; sx = 0; sy = (img.height - sh) / 2; }
+            ctx.drawImage(img, sx, sy, sw, sh, dx, dy, photo, photo);
+            // thin inner edge around the photo
+            ctx.strokeStyle = "rgba(0,0,0,0.10)"; ctx.lineWidth = 1;
+            ctx.strokeRect(dx + 0.5, dy + 0.5, photo - 1, photo - 1);
+            resolve(cv);
+          } catch (e) { reject(e); }
+        };
+        img.onerror = reject;
+        img.src = src;
+      });
+    }
+
     function buildCesiumStyle(Cesium, kind, colorway) {
       if (kind === "realistic") {
         // Solid, light buildings (no transparency) so sun lighting can model
@@ -4959,9 +5015,23 @@
               baseLayerPicker: false, geocoder: false, homeButton: false,
               sceneModePicker: false, navigationHelpButton: false, animation: false,
               timeline: false, fullscreenButton: false, infoBox: false, selectionIndicator: false,
+              // Render on demand instead of every single frame: the globe only
+              // redraws when something actually changes (camera move, tile load,
+              // a pin edit). This removes the constant-repaint jank when the view
+              // is idle. The journey flythrough flips this off while it runs (see
+              // playFly), since it animates the clock every frame.
+              requestRenderMode: true, maximumRenderTimeChange: Infinity,
             });
             viewerRef.current = viewer;
             try { viewer.clock.shouldAnimate = false; } catch (e) {}
+            // Smoother edges (anti-aliasing) on buildings + polaroids, and gentle
+            // camera inertia so panning/zooming glides to a stop instead of
+            // snapping. Wrapped in try/catch as these vary across Cesium builds.
+            try { viewer.scene.msaaSamples = 4; } catch (e) {}
+            try {
+              const ctl = viewer.scene.screenSpaceCameraController;
+              ctl.inertiaSpin = 0.85; ctl.inertiaTranslate = 0.85; ctl.inertiaZoom = 0.85;
+            } catch (e) {}
             viewer.scene.camera.setView({
               destination: Cesium.Cartesian3.fromDegrees(-123.1207, 49.2827, 1200),
               orientation: { heading: Cesium.Math.toRadians(10), pitch: Cesium.Math.toRadians(-25) },
@@ -5006,6 +5076,9 @@
               tilesetRef.current = tileset;
               tileset.style = buildCesiumStyle(Cesium, "watercolor", colorway);
             } catch (e) { console.warn("[cesium] OSM buildings failed", e); }
+            // In requestRenderMode the scene paints on demand, so force one
+            // render now that imagery + buildings + post-process are all set up.
+            try { viewer.scene.requestRender(); } catch (e) {}
             if (!cancelled) setStatus("ready");
           } catch (e) {
             if (!cancelled) { setStatus("error"); setErrMsg(e.message || "Cesium failed to load."); }
@@ -5058,38 +5131,45 @@
           })();
         }
         prevStyleRef.current = style;
+        // on-demand render so style/colour/imagery swaps show without a nudge
+        try { viewer.scene.requestRender(); } catch (e) {}
       }, [style, colorway, status]);
 
-      // render pinned photos as billboards + labels
+      // render pinned photos as larger Polaroid-framed billboards (no caption
+      // text). Each photo is composed onto a white Polaroid card on a canvas
+      // first, so the globe shows framed prints instead of bare squares.
       useEffect(() => {
         const viewer = viewerRef.current;
         if (!viewer || !window.Cesium || status !== "ready") return;
         const Cesium = window.Cesium;
+        let cancelled = false;
         entitiesRef.current.forEach((e) => { try { viewer.entities.remove(e); } catch (_) {} });
         entitiesRef.current = [];
-        pinnedStore.forEach((p) => {
-          const ent = viewer.entities.add({
-            id: "sozai-" + p.id,
-            position: Cesium.Cartesian3.fromDegrees(p.lon, p.lat, 40),
-            billboard: {
-              image: p.src, width: 86, height: 86,
-              verticalOrigin: Cesium.VerticalOrigin.BOTTOM,
-              heightReference: Cesium.HeightReference.NONE,
-              disableDepthTestDistance: Number.POSITIVE_INFINITY,
-            },
-            label: {
-              text: (p.caption || p.title || ""),
-              font: "13px sans-serif", fillColor: Cesium.Color.WHITE,
-              showBackground: true, backgroundColor: new Cesium.Color(0.15, 0.15, 0.13, 0.85),
-              pixelOffset: new Cesium.Cartesian2(0, 14),
-              verticalOrigin: Cesium.VerticalOrigin.TOP,
-              disableDepthTestDistance: Number.POSITIVE_INFINITY,
-              scale: 0.85,
-            },
-          });
-          entitiesRef.current.push(ent);
-        });
-      }, [pinnedStore.map((p) => p.id + ":" + p.lon + "," + p.lat + ":" + p.caption).join("|"), status]);
+        (async () => {
+          for (const p of pinnedStore) {
+            let image = p.src, aspect = 0.86;
+            try {
+              const cv = await makePolaroidCanvas(p.src);
+              image = cv; aspect = cv.width / cv.height;
+            } catch (_) { /* fall back to the raw photo */ }
+            if (cancelled || !viewerRef.current) return;
+            const W = 132;                       // on-screen width (was 86, square)
+            const ent = viewer.entities.add({
+              id: "sozai-" + p.id,
+              position: Cesium.Cartesian3.fromDegrees(p.lon, p.lat, 40),
+              billboard: {
+                image, width: W, height: Math.round(W / aspect),
+                verticalOrigin: Cesium.VerticalOrigin.BOTTOM,
+                heightReference: Cesium.HeightReference.NONE,
+                disableDepthTestDistance: Number.POSITIVE_INFINITY,
+              },
+            });
+            entitiesRef.current.push(ent);
+          }
+          try { viewer.scene.requestRender(); } catch (_) {}
+        })();
+        return () => { cancelled = true; };
+      }, [pinnedStore.map((p) => p.id + ":" + p.lon + "," + p.lat).join("|"), status]);
 
       // tap-to-pin + drag-to-move on the globe.
       const armedRef = useRef(null);
@@ -5116,7 +5196,7 @@
         handler.setInputAction((movement) => {
           if (!dragId) return;
           const cart = viewer.camera.pickEllipsoid(movement.endPosition, viewer.scene.globe.ellipsoid);
-          if (cart) { const { lon, lat } = toLngLat(cart); const ent = viewer.entities.getById("sozai-" + dragId); if (ent) ent.position = Cesium.Cartesian3.fromDegrees(lon, lat, 40); }
+          if (cart) { const { lon, lat } = toLngLat(cart); const ent = viewer.entities.getById("sozai-" + dragId); if (ent) ent.position = Cesium.Cartesian3.fromDegrees(lon, lat, 40); try { viewer.scene.requestRender(); } catch (_) {} }
         }, Cesium.ScreenSpaceEventType.MOUSE_MOVE);
         // LEFT_UP: commit a drag, OR pin an armed photo at the click point
         handler.setInputAction((click) => {
@@ -5167,6 +5247,8 @@
           try { viewer.clock.shouldAnimate = false; } catch (e) {}
           if (clockTickRef.current) { try { clockTickRef.current(); } catch (e) {} clockTickRef.current = null; }
           try { if (viewer.entities.getById("sozai-route")) viewer.entities.removeById("sozai-route"); } catch (e) {}
+          // restore on-demand rendering after an interrupted journey
+          try { viewer.scene.requestRenderMode = true; viewer.scene.requestRender(); } catch (e) {}
         }
         removeVehicle();
       }
@@ -5177,6 +5259,9 @@
         flyAbortRef.current = { stop: false };
         const token = flyAbortRef.current;
         setFlying(true);
+        // the journey animates the clock every frame, so render continuously
+        // while it plays (restored to on-demand in stopFly / at the end).
+        try { viewer.scene.requestRenderMode = false; } catch (e) {}
 
         const tdef = CS_TRANSPORTS.find((t) => t.id === transport) || CS_TRANSPORTS[0];
         const isPlane = tdef.id === "plane";
@@ -5301,6 +5386,8 @@
         }
         removeVehicle();
         try { if (viewer.entities.getById("sozai-route")) viewer.entities.removeById("sozai-route"); } catch (e) {}
+        // back to on-demand rendering now that the journey is over
+        try { viewer.scene.requestRenderMode = true; viewer.scene.requestRender(); } catch (e) {}
         setFlying(false); setFlyIdx(-1);
       }