grand unification of time

docs/architecture.md

@@ -52,10 +52,10 @@ overrides and kept-frame sets are all in clip-frame space, so a clip slides on
 the timeline without a single stored number changing. Exposure and lead are
 transforms *within* clip space:
 
-Detection retains every source frame. A chosen picture fps samples the frozen
-roto in clip time; it changes neither source-frame count nor the audio clock.
-The set of source frames an artist uses as cel tracing references is another
-selection, independent of the picture fps.
+Detection retains every source frame. Symbols carry their native fps; project
+fps selects the output grid without changing source data or audio speed.
+See [Time selection](time.md) for boundary sampling and frame units.
+Tracing references remain an independent selection.
 
 ```clojure
 (defn pose-frame [clip cf]
@@ -90,8 +90,8 @@ it a name is most of the work: `state` in `app.js` is a clip with its analysis
 inlined and its palette global.
 
 Cel keys select where drawings begin and how long they hold. The source frames
-shown beneath a cel while tracing are chosen independently, and picture fps
-only controls which analyzed pose the finished roto displays at a given time.
+shown beneath a cel while tracing are chosen independently. Project fps controls
+which native frames can appear on the output grid.
 
 ### Two things called "track"
 

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.

docs/timing-model.md

@@ -1,5 +1,7 @@
 # Timing model
 
+[Time selection](time.md) defines the current frame-rate representation.
+
 [The Lane Model](lane-model.md) defines the revised target for occurrence timing,
 source playback, sampling scope, and inverse editing. It supersedes conflicting
 proposals here; the sections below describe earlier implementation decisions.