iris is the framework alone; the app is one crate in app-rust/

Iris: "the organization of the rust rewrite is a mess right now... there
shouldn't be anything related to the app inside of iris. Iris is supposed
to be the UI framework alone." And, on the crate count: "I'm confused why
the app only code needs more than one crate though."

Nine cargo workspaces become three, and the port's project code -- which
sat in five places, four of them inside the framework -- becomes one crate,
`ai-app`, in `app-rust/`:

  client-core                -> app-rust/src/client
  iris/transcript-ui         -> app-rust/src/ui
  iris/transcript-fixture    -> app-rust/src/ui/fixture.rs + tests/ + touch/
  iris/desktop-app           -> app-rust/src/desktop + src/bin_desktop.rs
  iris/android-app           -> app-rust/src/android + android-project/
  android-shell              -> app-rust/src/shell

iris/ keeps core, macro, the iris crate, tabs-ui and rig-input, and now
mentions no session, transcript, setup or server anywhere.

Only two of the old splits had a reason that survived reading. event-model
stays a crate at the repo root because server/ depends on it too, so a
crate is what makes the backend and the app agree by construction. The two
Android .so names looked like a hard constraint -- a package produces one
library artifact -- until P2 turned out to already plan merging those two
Android apps into one; both faces now come out of libai_app.so, picked
apart by features so `--no-default-features --features shell` keeps wgpu,
parley and iris out of the Compose app's APK. docs/RUST.md's "One app
crate" has the rest, including what each remaining feature is for.

DECISIONS.md and SUBAGENTS.md move into docs/ with everything else.

Verified: ./run-tests.sh and `cd iris && cargo test` green, clippy and fmt
clean in all five workspaces, `cargo ndk -t x86_64` links libai_app.so,
build-apk.sh produces an APK that installs and launches on this checkout's
emulator (Gl ... virgl, as expected), and the phone-sized headless
screenshot renders the transcript unchanged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

benches/velocity_reference.py

@@ -0,0 +1,298 @@
+#!/usr/bin/env python3
+"""Compose's touch velocity tracker, transcribed independently of the Rust port.
+
+Same reason `fling_spline_reference.py` exists: the numbers checked into
+`sense.rs`'s velocity tests must not be numbers the Rust produced. The old
+estimator -- total motion over the sample span, an average -- passed every test
+it had, because every one of those tests asserted the average's own definition
+back at it. An average cannot tell an accelerating flick from a steady drag, and
+that is exactly what Iris reported from the phone on 2026-09-07: "flinging now
+actually works but is slower than Compose's immediately after releasing the
+flick".
+
+Transcribed by hand from, and only from, the `-sources.jar` of
+**androidx.compose.ui:ui-android:1.12.0** and
+**androidx.compose.foundation:foundation-android:1.12.0**
+(dl.google.com/dl/android/maven2), read 2026-09-07:
+
+  * `androidx/compose/ui/input/pointer/util/VelocityTracker.kt` --
+    `VelocityTracker1D.calculateVelocity`, `polyFitLeastSquares`,
+    `calculateImpulseVelocity`, `kineticEnergyToVelocity`, and the constants
+    `HistorySize = 20`, `HorizonMilliseconds = 100`,
+    `AssumePointerMoveStoppedMilliseconds = 40`.
+  * `androidx/compose/ui/input/pointer/util/PlatformVelocityTracker.kt` --
+    `Lsq2VelocityTracker`, which is what the 2D `VelocityTracker` delegates to.
+  * `androidx/compose/ui/input/pointer/util/PlatformVelocityTracker.android.kt`
+    -- the `AndroidComposeUiFlags.isFrameworkVelocityTrackerEnabled` fork.
+  * `androidx/compose/ui/AndroidComposeUiFlags.android.kt` -- that flag's
+    default, which is `false`.
+  * `androidx/compose/foundation/gestures/Draggable.kt` -- `sendDragStart` /
+    `sendDragEvent` / `sendDragStopped`, i.e. *which* samples a touch drag
+    feeds the tracker and where the maximum-velocity clamp is applied.
+  * `androidx/compose/foundation/gestures/DifferentialVelocityTracker.kt` and
+    `NonTouchScrollingLogic.kt` -- the Impulse strategy's only caller.
+  * `androidx/compose/foundation/gestures/Scrollable.kt` --
+    `DefaultFlingBehavior.performFling`, for the minimum-velocity question.
+
+**Which strategy a touch fling actually uses, since this was the surprise.**
+`Strategy.Impulse` is *not* it. `scrollable`/`draggable` release through
+`DragGestureNode.sendDragStopped`, which calls the 2D `VelocityTracker`; on
+Android that is `Lsq2VelocityTracker` (the framework-tracker flag defaults to
+false), which is two `VelocityTracker1D(strategy = Lsq2)` -- a degree-2
+least-squares fit over **absolute positions**, whose velocity is the fitted
+polynomial's derivative at the newest sample. Impulse is reached only through
+`DifferentialVelocityTracker`, whose sole caller is `NonTouchScrollingLogic`:
+mouse wheel and trackpad, never a finger. So this script transcribes Lsq2 and
+iris ports Lsq2. `calculate_impulse_velocity` is here anyway, unused by the
+printed points, because ruling it out by reading is cheaper than ruling it out
+again next time somebody remembers "Compose uses impulse".
+
+**Which samples a touch drag feeds it.** `sendDragStart` adds the DOWN change;
+every subsequent MOVE, historical samples included, is added by `sendDragEvent`.
+The **UP position is never added**: `Lsq2VelocityTracker.addPointerInputChange`
+wraps its two `addPosition` calls in `if (!event.changedToUpIgnoreConsumed())`,
+and all the UP branch does is reset the tracker when more than 40ms have passed
+since the last MOVE (b/238654963). So a finger that stops before lifting reads
+as a stop, not as a decelerating tail. Positions are the raw event positions,
+so the touch slop is inside the motion the tracker sees even though the list
+never scrolled by it.
+
+Two of Compose's samples iris does *not* reproduce, both noted rather than
+copied: pre-slop MOVEs (iris's `DragArbiter` is `Undecided` then too, so it
+feeds none either -- these agree), and the single MOVE that *crosses* the slop,
+which Compose drops because `sendDragStart` adds only the DOWN. iris feeds that
+one, since it is a real measured position and dropping it would be copying a
+quirk of where Compose happens to split its state machine.
+
+**The clamps.** Maximum: `sendDragStopped` passes
+`LocalViewConfiguration.maximumFlingVelocity`, which on Android is
+`ViewConfiguration.getScaledMaximumFlingVelocity()` -- 8000 dp/s. Minimum:
+there is **none** on this path. `ViewConfiguration.minimumFlingVelocity`
+exists in Compose's `ViewConfiguration` interface but its only use in either
+artifact is `NestedScrollInteropConnection`, for View interop.
+`DefaultFlingBehavior.performFling` guards with `abs(initialVelocity) > 1f`
+and says why in its own comment: "we need it since spline curve gives us
+NaNs". 1 px/s, not 50 dp/s.
+
+Run it with no arguments; it prints the sample sets and the velocities the
+Rust tests assert on.
+"""
+
+import math
+
+HISTORY_SIZE = 20
+HORIZON_MILLISECONDS = 100.0
+ASSUME_POINTER_MOVE_STOPPED_MILLISECONDS = 40.0
+MIN_SAMPLE_SIZE_LSQ2 = 3
+
+# ViewConfiguration.getScaledMaximumFlingVelocity(), in dp/s.
+MAXIMUM_FLING_VELOCITY_DP_S = 8000.0
+# DefaultFlingBehavior.performFling's own threshold, in the units of the
+# positions fed to the tracker -- pixels per second here.
+FLING_MINIMUM_PX_S = 1.0
+
+
+def poly_fit_least_squares(x, y, sample_count, degree):
+    """`polyFitLeastSquares`: Gram-Schmidt QR, coefficients low order first."""
+    if degree < 1:
+        raise ValueError("The degree must be at positive integer")
+    if sample_count == 0:
+        raise ValueError("At least one point must be provided")
+
+    truncated_degree = sample_count - 1 if degree >= sample_count else degree
+    m = sample_count
+    n = truncated_degree + 1
+
+    # a[i][h] = x[h]**i, pre-multiplied by the (always 1.0) weight.
+    a = [[0.0] * m for _ in range(n)]
+    for h in range(m):
+        a[0][h] = 1.0
+        for i in range(1, n):
+            a[i][h] = a[i - 1][h] * x[h]
+
+    q = [[0.0] * m for _ in range(n)]
+    r = [[0.0] * n for _ in range(n)]
+    for j in range(n):
+        w = q[j]
+        w[:] = a[j][:m]
+        for i in range(j):
+            z = q[i]
+            dot = sum(w[h] * z[h] for h in range(m))
+            for h in range(m):
+                w[h] -= dot * z[h]
+        norm = math.sqrt(sum(v * v for v in w))
+        inverse_norm = 1.0 / max(norm, 1e-6)
+        for h in range(m):
+            w[h] *= inverse_norm
+        for i in range(n):
+            r[j][i] = 0.0 if i < j else sum(w[h] * a[i][h] for h in range(m))
+
+    coefficients = [0.0] * n
+    for i in range(n - 1, -1, -1):
+        c = sum(q[i][h] * y[h] for h in range(m))
+        for j in range(n - 1, i, -1):
+            c -= r[i][j] * coefficients[j]
+        coefficients[i] = c / r[i][i]
+    return coefficients
+
+
+def kinetic_energy_to_velocity(kinetic_energy):
+    sign = 0.0 if kinetic_energy == 0.0 else math.copysign(1.0, kinetic_energy)
+    return sign * math.sqrt(2 * abs(kinetic_energy))
+
+
+def calculate_impulse_velocity(data_points, time, sample_count, is_data_differential):
+    """`calculateImpulseVelocity` -- not on the touch path; see the module doc."""
+    work = 0.0
+    start = sample_count - 1
+    next_time = time[start]
+    for i in range(start, 0, -1):
+        current_time = next_time
+        next_time = time[i - 1]
+        if current_time == next_time:
+            continue
+        if is_data_differential:
+            delta = -data_points[i - 1]
+        else:
+            delta = data_points[i] - data_points[i - 1]
+        v_curr = delta / (current_time - next_time)
+        v_prev = kinetic_energy_to_velocity(work)
+        work += (v_curr - v_prev) * abs(v_curr)
+        if i == start:
+            work = work * 0.5
+    return kinetic_energy_to_velocity(work)
+
+
+def calculate_velocity(samples):
+    """`VelocityTracker1D.calculateVelocity` with `Strategy.Lsq2`.
+
+    `samples` is `(time_millis, position)` oldest first, at most the last
+    `HISTORY_SIZE` of which the circular buffer would still be holding.
+    Returns units per second.
+    """
+    held = samples[-HISTORY_SIZE:]
+    if not held:
+        return 0.0
+
+    data_points = []
+    time = []
+    newest_time, _ = held[-1]
+    previous_time = newest_time
+    for sample_time, sample_position in reversed(held):
+        age = float(newest_time - sample_time)
+        delta = abs(float(sample_time - previous_time))
+        # Lsq2 walks back sample to sample; only the non-differential
+        # Impulse branch compares every sample against the newest one.
+        previous_time = sample_time
+        if age > HORIZON_MILLISECONDS or delta > ASSUME_POINTER_MOVE_STOPPED_MILLISECONDS:
+            break
+        data_points.append(sample_position)
+        time.append(-age)
+        if len(data_points) == HISTORY_SIZE:
+            break
+
+    if len(data_points) < MIN_SAMPLE_SIZE_LSQ2:
+        return 0.0
+    try:
+        coefficients = poly_fit_least_squares(time, data_points, len(data_points), 2)
+    except ValueError:
+        return 0.0
+    # The 2nd coefficient is the fitted polynomial's derivative at x = 0,
+    # which is the newest sample's timestamp. units/ms -> units/s.
+    return coefficients[1] * 1000.0
+
+
+def clamped(velocity, maximum):
+    """`VelocityTracker1D.calculateVelocity(maximumVelocity)`."""
+    if velocity == 0.0 or math.isnan(velocity):
+        return 0.0
+    return min(velocity, maximum) if velocity > 0 else max(velocity, -maximum)
+
+
+def average(samples):
+    """The estimator being replaced: total motion over the span."""
+    if len(samples) < 2:
+        return 0.0
+    span = (samples[-1][0] - samples[0][0]) / 1000.0
+    if span <= 0.0:
+        return 0.0
+    return (samples[-1][1] - samples[0][1]) / span
+
+
+# --- The three recorded sample sets the Rust tests assert on. ----------------
+
+# 1. `transcript-fixture/touch/flick-120hz.touch`, as `DragGesture` feeds it:
+#    the DOWN position, then one position per MOVE. The UP at t=20 adds no
+#    sample (see the module doc), which is why the finger sitting still for its
+#    last 4ms does not drag the estimate down. y only; the flick is vertical.
+FLICK_120HZ = [(0, 1000.0), (4, 1040.0), (8, 1086.0), (12, 1138.0), (16, 1196.0)]
+
+# 2. A steady drag: 5px every 10ms for 100ms. A constant-velocity fit and an
+#    average must agree here -- this is the case that cannot tell the two
+#    estimators apart, which is why it is not the only one.
+STEADY_DRAG = [(i * 10, float(i * 5)) for i in range(11)]
+
+# 3. A flick that accelerates into the release: 10ms apart, deltas doubling.
+#    This is the case the average gets wrong, and the negative control for
+#    the port -- reverting to the average must fail this test and only this
+#    kind of test.
+ACCELERATING_FLICK = [(0, 0.0), (10, 2.0), (20, 6.0), (30, 14.0), (40, 30.0), (50, 54.0)]
+
+# 4. The two edges of the sample walk, checked here so the Rust asserts
+#    Compose's answer rather than iris's own reading of the rule.
+#    (a) An old, fast burst outside the 100ms horizon, then a slow steady
+#        drag: the burst must not leak into the estimate.
+OLD_BURST_THEN_STEADY = [(0, 0.0)] + [(10 + i * 10, 1000.0 + i) for i in range(11)]
+#    (b) The finger stops for 48ms and then lifts. The gap exceeds
+#        AssumePointerMoveStopped, so the walk breaks after one sample and
+#        there is no fling -- what stops a "park it and let go" from
+#        flinging at whatever speed the finger arrived with.
+STOPPED_BEFORE_RELEASE = [(0, 0.0), (4, 40.0), (8, 90.0), (12, 150.0), (60, 152.0)]
+
+# 5. `sense.rs`'s own `drag_gesture_tests`: what `DragGesture` feeds for a
+#    press and two move frames, which is the fewest a fit can use.
+TWO_MOVE_FRAMES = [(0, 0.0), (8, 100.0), (16, 220.0)]
+#    ... and one move frame, which Compose cannot fit either.
+ONE_MOVE_FRAME = [(0, 0.0), (8, 100.0)]
+
+# The phone: 1080x2424 at content_scale 2.55.
+PHONE_DENSITY = 2.55
+
+
+def report(name, samples):
+    v = calculate_velocity(samples)
+    print(f"{name}:")
+    print(f"  samples (t_ms, position): {samples}")
+    print(f"  Lsq2 (Compose's touch path):    {v:.4f} px/s")
+    print(f"  average (the old estimator):    {average(samples):.4f} px/s")
+    print(f"  impulse (non-touch, for ref):   ", end="")
+    held = list(reversed(samples[-HISTORY_SIZE:]))
+    newest = held[0][0]
+    print(
+        f"{calculate_impulse_velocity([p for _, p in held], [-(newest - t) for t, _ in held], len(held), False) * 1000.0:.4f} px/s"
+    )
+    print()
+
+
+if __name__ == "__main__":
+    print("Compose 1.12.0 touch velocity: VelocityTracker1D, Strategy.Lsq2,")
+    print("non-differential (positions), HistorySize=20, Horizon=100ms,")
+    print("AssumePointerMoveStopped=40ms, minSampleSize=3.\n")
+    report("flick-120hz.touch", FLICK_120HZ)
+    report("steady drag (5px/10ms)", STEADY_DRAG)
+    report("accelerating flick (deltas 2,4,8,16,24 per 10ms)", ACCELERATING_FLICK)
+
+    report("old burst then steady 1px/10ms", OLD_BURST_THEN_STEADY)
+    report("stopped 48ms before release", STOPPED_BEFORE_RELEASE)
+    report("press and two move frames", TWO_MOVE_FRAMES)
+    report("press and one move frame", ONE_MOVE_FRAME)
+
+    print("Clamps:")
+    print(f"  maximum: {MAXIMUM_FLING_VELOCITY_DP_S} dp/s")
+    print(
+        f"           = {MAXIMUM_FLING_VELOCITY_DP_S * PHONE_DENSITY:.1f} px/s at the phone's density {PHONE_DENSITY}"
+    )
+    print(f"  minimum: none on the fling path; DefaultFlingBehavior skips |v| <= {FLING_MINIMUM_PX_S} px/s")
+    print()
+    print("Two samples only (a press and one move, the phone's 120Hz worst case):")
+    print(f"  Lsq2 needs 3 and answers {calculate_velocity(FLICK_120HZ[:2]):.4f} px/s")