grand unification of time

docs/time.md

@@ -0,0 +1,36 @@
+# Time selection
+
+Project `:fps` is the playback and export grid. Each symbol has its own native
+`:fps` and `:frames`; keys, spans, trace choices and corrections stay in that
+native space. A symbol without an explicit rate inherits the document rate;
+changing project fps first records that rate so its existing timing stays put.
+
+An output frame selects the latest native frame at or before its time:
+`floor(output-frame * native-fps / output-fps)`. Thus 30fps content in a 12fps
+project reads source frames 0, 2, 5, 7, 10… and retains its duration. A partial
+last output frame is included. Changing back to 30 restores the original grid.
+Nothing rewrites or discards the dense measurements.
+
+The same boundary selection runs when entering a placed symbol. Placement and
+artistic speed are applied before selection; the stored `:time :rate` and
+`:playback :speed` never contain a frame-rate conversion. The derived maps used
+by timeline rows, picking and editing account for the units of each symbol.
+`clip/frames` is a native length; `clip/output-frames` is a transport/export
+length. Resolver frame queries return native frames for edits.
+
+There is one fps control. The old transient picture-fps control and node
+sample-fps fields are gone. Existing exposure, trace choices and per-instance
+pose tracks remain available: a pose track can hold a chosen closed-mouth frame
+without deleting its neighboring measurements. Those choices stay in native
+frames when output fps changes. Automatic content-aware frame selection is not
+implemented. An event between output frames appears on the next output frame;
+it cannot create an extra frame in a 12fps output.
+
+Audio uses continuous time through the same derived placement maps, without
+picture floors or holds. Frame-rate units cancel before Web Audio playbackRate
+is set, so only deliberate speed changes affect pitch and duration. Export and
+playback use the same output count and resolver.
+
+Earlier imports with frame-rate conversion baked into stored retimes must be
+re-imported. There is no second reader for that representation. Source video
+presentation timestamps are still future work; this model assumes constant fps.