@lalalic/markcut 3.1.0 → 3.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lalalic/markcut",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Markdown-to-video engine. Describe scenes in markdown, get a rendered video.",
   "bin": {
     "markcut": "bin/markcut"
@@ -65,5 +65,9 @@
     "@types/react-dom": "^19.0.0",
     "typescript": "^5.6.0",
     "vitest": "^2.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lalalic/markcut.git"
   }
 }

package/skills/markcut/SKILL.md

@@ -18,6 +18,13 @@ Everything video is a **stream tree** described with markdown. see [docs/markdow
 
 - Use `scene` nodes to organize your video. Scenes can nest inside other scenes.
 - Use `description`, `scene.instruction`, `script`, `image|video.prompt` to structure your video content.
+- **If a scene has a `script` (or `audio`) plus one primary visual, the visual MUST be `isBackground:true`.** Without it the visual plays only its own duration (3s default for images) while narration continues — the rest of the scene is a black screen. Scene duration follows the audio, not the image.
+
+```md
+## scene-1
+- image prompt:"..." isBackground:true   # fills the whole scene, narration decides duration
+- script "..."
+```
 
 see [docs/markdown-descriptive.md](docs/markdown-descriptive.md) for full details.
 
@@ -71,15 +78,12 @@ npx @lalalic/markcut spots --waypoints "lat,lng;lat,lng" # discover POIs along a
 
 ---
 
-## self verification
-some common issues (photo or video can't be displayed, audio missing), take below actions to verify
-### preview
-- take screenshot for some key frames in player, and understand image to verify intent
-
-### final video
-- screenshot some key frames, and understand image to verify intent
-- stt the final video audio, and verify if vtt result is correct
-
+## review
+use the review contract defined in [./review.md](./review.md) to guide the review process.
+review as early as possible in the video production process to catch issues before they propagate.
+* review md file
+* review compiled.json
+* review the rendered video
 
 ## Reference
 
@@ -89,8 +93,7 @@ some common issues (photo or video can't be displayed, audio missing), take belo
 | Route / vlog map clips (effects, spots, examples) | [docs/map-dynamic-camera.md](docs/map-dynamic-camera.md) |
 | Built-in components & common npm packages | [docs/components.md](docs/components.md) |
 | Sound effects | [docs/sound-effects.md](docs/sound-effects.md) |
-
-
+| Review contract | [./review.md](./review.md) |
 
 ## Built-in Components
 
@@ -98,12 +101,6 @@ Built-in components available via `@lalalic/markcut/components`. See [docs/compo
 
 
 ## Golden rule
-- always check stream start and duration to avoid
-  - audio cut off
-  - video cut off
-  - subtitle mismatch
-  - sync issues between audio, video, and subtitles
-according to the content change. rm `.markcut` will cause all content to be regenerated, which is time consuming and wasteful.
 - put all manual assets in `assets` folder, such as bgm, logo, watermark, etc. don't put them in `.markcut` folder, which is auto generated and will be deleted when `markcut clean` command is run.
 
 ### Don'ts

package/skills/markcut/docs/map-dynamic-camera.md

@@ -16,7 +16,7 @@ Use `map` clips when the video is about **a place and getting around**:
 - city tour: establishing shot → flyover → street level
 - route explainers: commute, road trip, walking tour, "how to get there"
 
-Every map clip can carry a `script` narration next to it (see §6 for the
+Every map clip can carry a `script` narration next to it (see §7 for the
 scene pattern that plays map + narration together).
 
 ---
@@ -101,7 +101,85 @@ Full example:
 
 ---
 
-## 5. Discovering spots along a route — `markcut spots`
+## 5. Per-leg travel modes (flight ✈️ / boat 🚢 / walk 🚶 / drive 🚗)
+
+A route is a sequence of **legs** — one per consecutive waypoint pair. Each
+waypoint can tag the leg that **leaves it** with its own travel mode. The
+parser is smart: a **bare (unquoted) mode word anywhere after lat/lng** is the
+outgoing-leg mode — no empty slots needed. Untagged waypoints fall back to
+the map's `travelMode` (default DRIVING).
+
+```
+[lat,lng,"Label","media",MODE]   # full
+[lat,lng,"Label",MODE]            # mode without media (no empty "") — smart
+[lat,lng,MODE]                     # just a mode
+```
+
+| mode | how it renders |
+|---|---|
+| `DRIVING` (default) | Google Directions road route — solid line, 🚗 marker |
+| `WALKING` | Google Directions pedestrian route — 🚶 marker |
+| `BICYCLING` | Google Directions bike route — 🚲 marker |
+| `TRANSIT` | Google Directions transit route — 🚌 marker |
+| `FLIGHT` | **synthetic great-circle arc** (no road) — dashed yellow line, ✈️ marker |
+| `BOAT` | **synthetic arc across water** — dashed teal line, 🚢 marker |
+
+FLIGHT/BOAT have no Directions route, so they're drawn as curved "as the crow
+flies" arcs and timed by distance at a cruise speed (✈️ ~850 km/h, 🚢 ~40 km/h).
+The traveling marker switches glyph to the current leg's mode as it moves, and
+time is split across legs **proportionally to each leg's duration**.
+
+Rules:
+- A mode word must be **unquoted** — quote it (`"FLIGHT"`) and it's a literal
+  label/media instead. That's the escape hatch if a media file is literally
+  named `FLIGHT`.
+- Quoted-empty `""` slots are still accepted (backward compat).
+- Remaining values map positionally: 1st = label, 2nd = media.
+
+Example — fly in, take a boat, walk, then drive:
+
+```md
+- map view:route duration:12 travelMode:DRIVING
+  waypoints:[37.8199,-122.4783,"SFO",FLIGHT; 33.94,-118.41,"LAX",BOAT; 33.75,-118.28,"Long Beach",WALKING; 33.77,-118.19,"Promenade",DRIVING; 33.94,-118.41,"LAX"]
+```
+
+Legs above: SFO→LAX by ✈️, LAX→Long Beach by 🚢, Long Beach→Promenade by 🚶,
+Promenade→LAX by 🚗 (the last waypoint has no outgoing leg, so its mode is
+ignored).
+
+## 6. Stops & anchored overlays (the vlog pattern)
+
+The typical vlog: the pin moves leg-to-leg, then **stops at a hotspot** while a
+photo/video/narration plays, then continues. Make other streams **children of
+the map** and anchor them with `at:"WaypointLabel"` — the map renders them at
+that waypoint's screen position (projected from the live map), so a photo
+grows out of the pin's location.
+
+```md
+- map view:route duration:16 travelMode:DRIVING
+  waypoints:[37.81,-122.48,"Golden Gate"; 37.77,-122.42,"Civic Center"; 37.62,-122.38,"SFO"]
+  - image src:gg.jpg at:"Golden Gate" duration:3 effects:[zoomIn]
+  - image src:civic.jpg at:"Civic Center" duration:3 effects:[zoomIn]
+```
+
+- `at:"Label"` anchors the child at the waypoint with that label. The renderer
+  projects the waypoint's lat/lng to its screen pixel each frame and centers
+  the child there — combine with `effects:[zoomIn]` for a "grows out of the
+  pin" reveal.
+- Children **without** `at` render full-screen over the map.
+- **Auto-timing (default)** — give the child a `duration` and *no* `start`; at
+  resolve time the map computes each leg's travel time (Directions REST for
+  road modes, cruise speed for `FLIGHT`/`BOAT`) and schedules the child to
+  start **at the pin's arrival** at that waypoint. The pin pauses (dwells)
+  while the child plays, then resumes. Real drive times are used only for
+  *ratios* — the video length stays the map's `duration`, or a default 10s
+  drive budget + dwells when the map has none, so a 40-minute drive still
+  plays as a short clip with the pin timing proportional to each leg.
+- **Manual timing (opt-out)** — set `start` explicitly and the resolver leaves
+  it untouched (it still contributes to the pin's pause window).
+- The map's own `duration`/`end` defines its span; children run inside it.
+
+## 7. Discovering spots along a route — `markcut spots`
 
 Don't hand-pick coordinates for a route video — **discover** interesting stops
 with the spots CLI. It samples points along a route (Directions API) and ranks
@@ -132,7 +210,7 @@ npx @lalalic/markcut spots --waypoints "37.8199,-122.4783;37.6213,-122.3790" \
 
 ---
 
-## 6. Markdown examples (copy-paste)
+## 8. Markdown examples (copy-paste)
 
 ### 6.1 Simple route clip with narration
 
@@ -184,9 +262,15 @@ layout:parallel
 ## A-Quick-Walk
 layout:parallel
 - script "A short stroll down the block."
-- map view:streetview duration:6 streetView:{route:[{lat:37.7793,lng:-122.4193},{lat:37.7785,lng:-122.4185},{lat:37.7777,lng:-122.4178}], radius:50, pov:{heading:tween(0, 40, easeInOut), pitch:-5}}
+- map view:streetview duration:6 streetView:{route:[{lat:37.7785,lng:-122.4185},{lat:37.7777,lng:-122.4178}], radius:50, pov:{heading:tween(0, 40, easeInOut), pitch:-5}}
 ```
 
+> **Walk = snap between covered waypoints.** A `route` walk holds at each
+> waypoint's panorama and jumps between them (not continuous per-frame
+> movement — that would fire hundreds of Street View requests and get
+> rate-limited into black frames). Every waypoint needs imagery; gaps show the
+> last loaded panorama instead of black.
+
 ### 6.4 Full route-vlog recipe (5 scenes)
 
 Combine everything for a complete vlog arc: **establish → route with photos →
@@ -219,12 +303,12 @@ layout:parallel
 ## Street-View-Walk
 layout:parallel
 - script "A quick walk down the block."
-- map view:streetview duration:6 streetView:{route:[{lat:37.7793,lng:-122.4193},{lat:37.7785,lng:-122.4185},{lat:37.7777,lng:-122.4178},{lat:37.7769,lng:-122.4170}], radius:50, pov:{heading:tween(0, 40, easeInOut), pitch:-5}}
+- map view:streetview duration:6 streetView:{route:[{lat:37.7785,lng:-122.4185},{lat:37.7777,lng:-122.4178}], radius:50, pov:{heading:tween(0, 40, easeInOut), pitch:-5}}
 ```
 
 ---
 
-## 7. Recipe — build a route/vlog clip
+## 9. Recipe — build a route/vlog clip
 
 1. **Get the route** — endpoints from the user's media/GPS, or two landmarks.
 2. **Discover spots** — `markcut spots --waypoints "lat,lng;lat,lng" --photos --markdown`; pick 2–5 that tell the story.
@@ -234,10 +318,10 @@ layout:parallel
 
 ---
 
-## 8. Tips & pitfalls
+## 10. Tips & pitfalls
 
 - **Map + narration**: put `- map ...` and `- script "..."` as sibling bullets in a `layout:parallel` scene so they play together. If the scene is `series`, narration plays alone first and the map shows nothing while speaking.
-- **Street View coverage is not universal** — a spot may have no panorama. If a `streetview` scene looks dark/empty, pick a nearby well-covered location or use `view:cinematic` instead.
+- **Street View coverage is not universal** — a spot may have no panorama (Google returns "no imagery here"); interpolating between sparse points also crosses uncovered blocks. Pick waypoints you've verified have imagery (open the coords in Google Maps, drag the pegman), keep a `route` walk's waypoints on the same covered street, and set `radius` (meters) so the panorama search is constrained nearby. If a `streetview` scene still looks dark, use `view:cinematic` instead.
 - **Route maps need ≥2 waypoints**; a single point falls back to a plain marker.
 - **Media assets** — photo thumbnails (`waypoint.media`), images, bgm etc. should live in the md file's folder (e.g. `assets/...`). See the asset-path rules in `markdown-descriptive.md` §14 (verify enforces md-folder-relative paths).
 - **Don't set duration from script length** — the resolver computes it from TTS audio.

package/skills/markcut/docs/markdown-descriptive.md

@@ -705,7 +705,7 @@ tween(#000, #FFF)             — color interpolation
 # Best practices
 - Markcut engine will automatically determine the duration of background streams, video, script audio. Don't set duration for them if no special requirements (e.g., speed up/down on purpose).
 - global streams (BGM, Logo, Lip-sync video,...) should be set on root level, and set `isBackground:true` to let it loop to fill the whole video duration.
-- Set `isBackground:true` for static vision content, such as image, when audio is playing
+- **Set `isBackground:true` for static vision content (image) whenever the scene has audio/script.** Scene duration is driven by the audio (which can be much longer than the image's default 3s); without `isBackground` the image ends early and the scene tail plays over a black screen while narration continues.
 - adjust audio start time with `start` property to avoid audio cut when transition effect is applied on vision scene