Increase complexity of test demo

packages/core-v2/API.md

@@ -305,10 +305,37 @@ again and leaves the current entry active.
 
 `OriginNavigationActionOptions.placement` defaults to `"under"`.
 
+### `replace(target, choreography?, options?)`
+
+Creates a new target while removing the current history entry:
+
+```ts
+const confirmOrder = () =>
+  replace(
+    originView(OrderConfirmationView, { orderId: "NVO-2048" }),
+    slideLeft,
+  );
+```
+
+The target inherits the origin's `previousNodeKey`, so a later back skips the
+replaced entry. The origin remains mounted while the operation is interactive
+or settling and is unmounted only after commit. Cancelling removes the proposed
+target and restores the origin without changing history.
+
+Without choreography, `replace(target)` creates an intent suitable for a
+gesture builder:
+
+```ts
+.navigate(() => replace(originView(OrderConfirmationView)))
+.animate(slideLeft)
+```
+
+`OriginNavigationActionOptions.placement` defaults to `"above"`.
+
 ### `originAction(target, choreography, options?)`
 
-Constructs a complete low-level `OriginAction`. Prefer `forward()` and `back()`
-when expressing retained navigation.
+Constructs a complete low-level `OriginAction`. Prefer `forward()`, `replace()`,
+and `back()` when expressing retained navigation.
 
 ```ts
 const action = originAction(profile, slideLeft, {
@@ -352,10 +379,11 @@ Omitting choreography returns a navigation intent for a gesture builder.
 
 History is a linked chain of mounted scene nodes.
 
-| Mode     | Commit behavior                                                |
-| -------- | -------------------------------------------------------------- |
-| `"push"` | Park and retain the origin; activate the new target            |
-| `"back"` | Reuse the retained previous target; pop and unmount the origin |
+| Mode        | Commit behavior                                                |
+| ----------- | -------------------------------------------------------------- |
+| `"push"`    | Park and retain the origin; activate the new target            |
+| `"replace"` | Create a new target, inherit prior history, unmount the origin |
+| `"back"`    | Reuse the retained previous target; pop and unmount the origin |
 
 Parked entries are `inert`, `aria-hidden`, invisible, and excluded from pointer
 input. They remain mounted until back pops them or the scene is destroyed.
@@ -476,6 +504,34 @@ const scaleIn = defineOriginChoreography({
 The function returns the same object. Its value is type checking and a clear
 construction point.
 
+Set `persistAtRest: true` when progress `1` should remain as a connected visual
+relationship after a committed push:
+
+```ts
+const openPartialDrawer = defineOriginChoreography({
+  name: "partial-drawer-open",
+  persistAtRest: true,
+  effects: ({ progress }) => ({
+    source: {
+      transform: `translateX(${progress * 66.6667}%)`,
+    },
+    target: {
+      transform: `translateX(${(progress - 1) * 66.6667}%)`,
+    },
+  }),
+});
+```
+
+This leaves the retained source mounted, visible, and inert instead of parking
+it. The target remains the active history entry. Beginning back suspends the
+resting relationship so a reciprocal close choreography can take over;
+cancelling back restores it exactly.
+
+Connected resting effects are supported only by retained-history push actions.
+They are designed for partial drawers, inspectors, and other presentations
+where both mounted views remain visible after commit. They do not appear in
+`scene.operations`, which reports live interactive/settling edges only.
+
 `effects()` may return:
 
 | Effect   | Applied to                                                 |
@@ -566,9 +622,9 @@ exists.
 
 ### `scene.begin(originKey, action)`
 
-For forward, mounts a new target and waits one Vue tick for measurement. For
-back, reveals and measures the retained previous node. It then returns an
-`OriginOperationHandle`.
+For forward or replace, mounts a new target and waits one Vue tick for
+measurement. For back, reveals and measures the retained previous node. It
+then returns an `OriginOperationHandle`.
 
 ```ts
 const handle = await scene.begin(nodeKey, action);
@@ -624,9 +680,9 @@ A choreography, placement, history mode, and—except for back—target recipe.
 ### `OriginNavigationIntent`
 
 An animation-free target, placement, and history mutation returned by
-`forward()`, `back()`, `above()`, or `under()` when choreography is omitted.
-Gesture `.animate()` combines it with choreography to create the internal
-action.
+`forward()`, `replace()`, `back()`, `above()`, or `under()` when choreography
+is omitted. Gesture `.animate()` combines it with choreography to create the
+internal action.
 
 ### Gesture definition types
 
@@ -688,7 +744,7 @@ Rect values are viewport CSS pixels.
 
 - `OriginSceneNode`: mounted identity, retained previous key, state, recipe,
   history, and incoming edge.
-- `OriginSceneNodeState`: `active`, `transitioning`, or `parked`.
+- `OriginSceneNodeState`: `active`, `transitioning`, `exposed`, or `parked`.
 - `OriginOperation`: read-only live edge state.
 - `OriginOperationPhase`: operation lifecycle phase.
 - `OriginOperationIntent`: selected operation outcome.
@@ -705,7 +761,8 @@ implementation types. They are exported by the current barrel but marked
 - `useOrigin()` and `useOriginGesture()` must run inside a component mounted by
   `OriginScene`.
 - An origin can own only one outgoing operation at a time.
-- Parked history entries cannot originate operations until back reveals them.
+- Parked or exposed retained entries are inert and cannot originate operations.
+  The active connected target owns interactions until back reveals its source.
 - A target can originate its own operation as soon as its incoming operation's
   intent becomes commit.
 - The included recognizer follows one primary pointer and one axis.