@atom.io/spa 0.0.2 → 0.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (94) hide show
  1. package/README.md +144 -47
  2. package/README.mdx +37 -11
  3. package/dist/astro-application.d.ts +1 -1
  4. package/dist/astro-application.js +2 -2
  5. package/dist/astro-application.js.map +1 -1
  6. package/dist/astro-client.d.ts +1 -1
  7. package/dist/astro-client.js +4 -4
  8. package/dist/astro-client.js.map +1 -1
  9. package/dist/{astro-shared-DyzbUi6c.d.ts → astro-shared-CYSRrRr8.d.ts} +2 -2
  10. package/dist/{astro-shared-DyzbUi6c.d.ts.map → astro-shared-CYSRrRr8.d.ts.map} +1 -1
  11. package/dist/astro.d.ts +1 -1
  12. package/dist/capabilities-BkQ2i0vV.js +63 -0
  13. package/dist/capabilities-BkQ2i0vV.js.map +1 -0
  14. package/dist/{capabilities-yC9TsHDI.d.ts → capabilities-D3HObAIy.d.ts} +66 -11
  15. package/dist/capabilities-D3HObAIy.d.ts.map +1 -0
  16. package/dist/client.min.js +1 -1
  17. package/dist/{capabilities-BuZUQpiD.js → core-Bl1Ec1hY.js} +42 -79
  18. package/dist/core-Bl1Ec1hY.js.map +1 -0
  19. package/dist/development/astro-application.js +2 -2
  20. package/dist/development/astro-application.js.map +1 -1
  21. package/dist/development/astro-client.js +4 -4
  22. package/dist/development/astro-client.js.map +1 -1
  23. package/dist/development/capabilities-BkQ2i0vV.js +63 -0
  24. package/dist/development/capabilities-BkQ2i0vV.js.map +1 -0
  25. package/dist/development/{capabilities-DhOJmeoJ.js → core-DZFaOyTO.js} +42 -79
  26. package/dist/development/core-DZFaOyTO.js.map +1 -0
  27. package/dist/development/{dom-BKc6V_Kz.js → dom-Dwa2SFTn.js} +16 -7
  28. package/dist/development/dom-Dwa2SFTn.js.map +1 -0
  29. package/dist/development/index.js +4 -4
  30. package/dist/development/konva.js +25 -3
  31. package/dist/development/konva.js.map +1 -1
  32. package/dist/development/motion.js +392 -8
  33. package/dist/development/motion.js.map +1 -1
  34. package/dist/development/renderer.js +23 -10
  35. package/dist/development/renderer.js.map +1 -1
  36. package/dist/development/server.js +2 -1
  37. package/dist/development/server.js.map +1 -1
  38. package/dist/development/{src-Dh-d6w4y.js → src-BUtG4BgX.js} +4 -4
  39. package/dist/development/src-BUtG4BgX.js.map +1 -0
  40. package/dist/development/three.js +24 -10
  41. package/dist/development/three.js.map +1 -1
  42. package/dist/{dom-B2rm8o2L.js → dom-Cfj3GtQK.js} +16 -7
  43. package/dist/dom-Cfj3GtQK.js.map +1 -0
  44. package/dist/{index-BdwxmSKg.d.ts → index-YRZ79lN5.d.ts} +3 -3
  45. package/dist/{index-BdwxmSKg.d.ts.map → index-YRZ79lN5.d.ts.map} +1 -1
  46. package/dist/index.d.ts +4 -4
  47. package/dist/index.js +4 -4
  48. package/dist/{jsx-runtime-CZU7F8Qz.d.ts → jsx-runtime-Q-UBV97Y.d.ts} +2 -2
  49. package/dist/{jsx-runtime-CZU7F8Qz.d.ts.map → jsx-runtime-Q-UBV97Y.d.ts.map} +1 -1
  50. package/dist/jsx-runtime.d.ts +1 -1
  51. package/dist/konva.d.ts +3 -3
  52. package/dist/konva.d.ts.map +1 -1
  53. package/dist/konva.js +25 -3
  54. package/dist/konva.js.map +1 -1
  55. package/dist/motion.d.ts +2 -1
  56. package/dist/motion.d.ts.map +1 -1
  57. package/dist/motion.js +392 -8
  58. package/dist/motion.js.map +1 -1
  59. package/dist/renderer.d.ts +3 -3
  60. package/dist/renderer.d.ts.map +1 -1
  61. package/dist/renderer.js +23 -10
  62. package/dist/renderer.js.map +1 -1
  63. package/dist/server.d.ts +1 -1
  64. package/dist/server.js +2 -1
  65. package/dist/server.js.map +1 -1
  66. package/dist/size.json +12 -12
  67. package/dist/{src-BZxX4xbU.js → src-DvkUMuNW.js} +4 -4
  68. package/dist/src-DvkUMuNW.js.map +1 -0
  69. package/dist/three.d.ts +3 -3
  70. package/dist/three.d.ts.map +1 -1
  71. package/dist/three.js +24 -10
  72. package/dist/three.js.map +1 -1
  73. package/package.json +9 -7
  74. package/src/astro-application.ts +2 -2
  75. package/src/astro-client.ts +3 -3
  76. package/src/capabilities.ts +21 -2
  77. package/src/core.ts +66 -41
  78. package/src/dom.ts +35 -4
  79. package/src/index.ts +2 -2
  80. package/src/konva.ts +41 -14
  81. package/src/motion-tween.ts +106 -0
  82. package/src/motion.ts +122 -9
  83. package/src/presence.ts +324 -0
  84. package/src/renderer.ts +51 -14
  85. package/src/three-events.ts +13 -1
  86. package/src/three.ts +38 -15
  87. package/src/use-loadable.ts +3 -3
  88. package/dist/capabilities-BuZUQpiD.js.map +0 -1
  89. package/dist/capabilities-yC9TsHDI.d.ts.map +0 -1
  90. package/dist/development/capabilities-DhOJmeoJ.js.map +0 -1
  91. package/dist/development/dom-BKc6V_Kz.js.map +0 -1
  92. package/dist/development/src-Dh-d6w4y.js.map +0 -1
  93. package/dist/dom-B2rm8o2L.js.map +0 -1
  94. package/dist/src-BZxX4xbU.js.map +0 -1
package/README.md CHANGED
@@ -10,7 +10,7 @@ The npm package is named @atom.io/spa. Its browser runtime, Vite compiler, serve
10
10
 
11
11
  ```tsx
12
12
  import type { VNode } from "@atom.io/spa"
13
- import { useId, useRef, useSetter, useValue } from "@atom.io/spa"
13
+ import { useGetter, useId, useRef, useSetter } from "@atom.io/spa"
14
14
  import { atom } from "atom.io"
15
15
 
16
16
  const pointAtom = atom<{ x: number; y: number }>({
@@ -23,7 +23,7 @@ const circleAtom = atom<SVGCircleElement | null>({
23
23
  })
24
24
 
25
25
  export function PointEditor(): VNode {
26
- const point = useValue(pointAtom)
26
+ const getPoint = useGetter(pointAtom)
27
27
  const setPoint = useSetter(pointAtom)
28
28
  const circle = useRef(circleAtom)
29
29
  const id = useId()
@@ -31,10 +31,10 @@ export function PointEditor(): VNode {
31
31
  <section aria-labelledby={id}>
32
32
  <h2 id={id}>Point</h2>
33
33
  <svg viewBox="0 0 100 100">
34
- <circle ref={circle} cx={point().x} cy={point().y} r="3" />
34
+ <circle ref={circle} cx={getPoint().x} cy={getPoint().y} r="3" />
35
35
  </svg>
36
36
  <output>
37
- {point().x}, {point().y}
37
+ {getPoint().x}, {getPoint().y}
38
38
  </output>
39
39
  <button
40
40
  onClick={() => {
@@ -49,7 +49,7 @@ export function PointEditor(): VNode {
49
49
 
50
50
  ```
51
51
 
52
- The point accessor returns the current object. Each JSX attribute reads its coordinate when evaluated. Both bindings depend on the point atom, and unchanged primitive results skip DOM writes. Reads during setup are snapshots; reads in event handlers are current and untracked. Shared derived state belongs in atom.io selectors.
52
+ Name the getter and setter after the atom: pointAtom uses getPoint and setPoint. The getPoint getter returns the current object. Each JSX attribute reads its coordinate when evaluated. Both bindings depend on the point atom, and unchanged primitive results skip DOM writes. Reads during setup are snapshots; reads in event handlers are current and untracked. Shared derived state belongs in atom.io selectors.
53
53
 
54
54
  ## Vite
55
55
 
@@ -95,9 +95,9 @@ The development plugin keeps SPA and atom.io outside dependency prebundling so r
95
95
  | API | Contract |
96
96
  | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
97
97
  | useLoadable(token, fallback?) | Return a tracked accessor for loading, last-observed values, and handled errors. |
98
- | useValue(token) | Return a live accessor for an atom or selector, bound to this instance's store. |
98
+ | useGetter(token) | Return a live accessor for an atom or selector, bound to this instance's store. |
99
99
  | useSetter(token) | Return a stable atom.io writer. |
100
- | useTimeline(token) | Return an accessor for at, length, undo, redo, clear, and available grouped transaction controls. |
100
+ | useTimeline(token) | Return a stable object with getCursor/getLength readers, undo/redo/clear commands, and transaction-group controls. |
101
101
  | useTransaction(token) | Bind an atom.io transaction, preserving its arguments and result. |
102
102
  | useRef(token) | Return an attachment callback for a nullable element atom. Clear it only while this attachment still owns the reference. |
103
103
  | useId() | Allocate an instance-stable ID using the root's prefix. |
@@ -107,6 +107,55 @@ The development plugin keeps SPA and atom.io outside dependency prebundling so r
107
107
 
108
108
  Call setup helpers synchronously during component setup or owned mount callbacks. Capture their results for event handlers. Tokens are fixed for an instance; use an application key in a reactive child expression to replace a component when its token changes. Component props stay live when read through the props object; destructuring during setup takes a snapshot.
109
109
 
110
+ useTimeline returns a TimelineControls object whose methods can be destructured during setup. getCursor and getLength read the current cursor position and recorded checkpoint count; calls inside JSX subscribe the computation, while calls during setup or in event handlers are untracked. undo, redo, and clear are stable commands. history.getTransaction() is a tracked reader that returns an object with optional undo and redo callbacks for the adjacent transaction groups. At a cursor between transactions, both callbacks may be present and target different groups. A missing callback means no transaction group is available in that direction; the reader returns an empty object when neither is available. Calling a returned callback travels its captured group across participating timelines where it remains at the relevant history head, leaving diverged timelines unchanged. Use history.getTransaction().undo?.() or history.getTransaction().redo?.() to retrieve and invoke the current action together.
111
+
112
+ ```tsx
113
+ import type { VNode } from "@atom.io/spa"
114
+ import { useGetter, useTimeline, useTransaction } from "@atom.io/spa"
115
+ import { atom, timeline, transaction } from "atom.io"
116
+
117
+ const countAtom = atom<number>({ key: `count`, default: 0 })
118
+ const historyTimeline = timeline({ key: `history`, scope: [countAtom] })
119
+ const incrementTransaction = transaction<() => void>({
120
+ key: `increment`,
121
+ do: ({ get, set }) => {
122
+ set(countAtom, get(countAtom) + 1)
123
+ },
124
+ })
125
+
126
+ export function TimelineExample(): VNode {
127
+ const getCount = useGetter(countAtom)
128
+ const increment = useTransaction(incrementTransaction)
129
+ const history = useTimeline(historyTimeline)
130
+ return (
131
+ <section>
132
+ <output>
133
+ Count: {getCount()} (history: {history.getCursor()}/{history.getLength()}
134
+ )
135
+ </output>
136
+ <button onClick={increment}>Increment</button>
137
+ <button
138
+ disabled={history.getTransaction().undo === undefined}
139
+ onClick={() => {
140
+ history.getTransaction().undo?.()
141
+ }}
142
+ >
143
+ Undo transaction
144
+ </button>
145
+ <button
146
+ disabled={history.getTransaction().redo === undefined}
147
+ onClick={() => {
148
+ history.getTransaction().redo?.()
149
+ }}
150
+ >
151
+ Redo transaction
152
+ </button>
153
+ </section>
154
+ )
155
+ }
156
+
157
+ ```
158
+
110
159
  Arrays support keyed components and elements. Reordering preserves instances and nodes; removed ranges release subscriptions, events, refs, and cleanup callbacks. Application keys must be unique among siblings. Explicit keys are compared as strings; unkeyed positions occupy a separate namespace. Unkeyed arrays use positions. A key identifies a row in a reactive child collection; it is not an independent reactive binding.
111
160
 
112
161
  HTML and SVG use native DOM properties and attributes, plus className/htmlFor aliases. Events use onClick/onInput-style names, with Capture suffixes and onDoubleClick support. Styles are CSS strings. Mutable atom values still invalidate their consumers; project primitive fields for precise DOM writes. Refs attach once per element instance.
@@ -140,15 +189,15 @@ export function InspectCount(): VNode {
140
189
 
141
190
  ```
142
191
 
143
- Capture the store during component setup or an owned onMount callback, then pass it to store-aware atom.io operations or integrations. Getting the store creates no subscription. Direct reads such as getFromStore do not participate in SPA's dependency tracking; useValue and useLoadable provide tracked reads. The returned object is a store, not a Silo or a new wrapper.
192
+ Capture the store during component setup or an owned onMount callback, then pass it to store-aware atom.io operations or integrations. Getting the store creates no subscription. Direct reads such as getFromStore do not participate in SPA's dependency tracking; useGetter and useLoadable provide tracked reads. The returned object is a store, not a Silo or a new wrapper.
144
193
 
145
194
  ## Families
146
195
 
147
- useValue, useSetter, useRef, and useTimeline accept a family token followed by its key. useLoadable accepts a family, key, and optional fallback. Keys retain their declared types, including tuples, numbers, booleans, and null. Members resolve in the component's store, so isolated roots can use the same family tokens independently.
196
+ useGetter, useSetter, useRef, and useTimeline accept a family token followed by its key. useLoadable accepts a family, key, and optional fallback. Keys retain their declared types, including tuples, numbers, booleans, and null. Members resolve in the component's store, so isolated roots can use the same family tokens independently.
148
197
 
149
198
  ```tsx
150
199
  import type { VNode } from "@atom.io/spa"
151
- import { useRef, useSetter, useTimeline, useValue } from "@atom.io/spa"
200
+ import { useGetter, useRef, useSetter, useTimeline } from "@atom.io/spa"
152
201
  import { atomFamily, scopeFamily, timelineFamily } from "atom.io"
153
202
 
154
203
  const countAtoms = atomFamily<number, string>({ key: `count`, default: 0 })
@@ -162,7 +211,7 @@ const historyTimelines = timelineFamily<string>({
162
211
  })
163
212
 
164
213
  export function FamilyCounter(props: { id: string }): VNode {
165
- const count = useValue(countAtoms, props.id)
214
+ const getCount = useGetter(countAtoms, props.id)
166
215
  const setCount = useSetter(countAtoms, props.id)
167
216
  const ref = useRef(buttonAtoms, props.id)
168
217
  const history = useTimeline(historyTimelines, props.id)
@@ -174,14 +223,9 @@ export function FamilyCounter(props: { id: string }): VNode {
174
223
  setCount((value) => value + 1)
175
224
  }}
176
225
  >
177
- {count()}
226
+ {getCount()}
178
227
  </button>
179
- <button
180
- disabled={history().at === 0}
181
- onClick={() => {
182
- history().undo()
183
- }}
184
- >
228
+ <button disabled={history.getCursor() === 0} onClick={history.undo}>
185
229
  Undo
186
230
  </button>
187
231
  </section>
@@ -304,7 +348,7 @@ AstroApplicationContext, AstroStoreContext, AstroStoreFactory, AstroStorePrepara
304
348
 
305
349
  ```tsx
306
350
  import type { Child, VNode } from "@atom.io/spa"
307
- import { onCleanup, useId, useSetter, useValue } from "@atom.io/spa"
351
+ import { onCleanup, useGetter, useId, useSetter } from "@atom.io/spa"
308
352
  import { atom, Silo } from "atom.io"
309
353
  import { IMPLICIT } from "atom.io/internal"
310
354
 
@@ -314,7 +358,7 @@ export default function Counter(props: {
314
358
  children?: Child
315
359
  slots?: Record<string, Child>
316
360
  }): VNode {
317
- const count = useValue(countAtom)
361
+ const getCount = useGetter(countAtom)
318
362
  const setCount = useSetter(countAtom)
319
363
  const id = useId()
320
364
  onCleanup(() => {
@@ -330,7 +374,7 @@ export default function Counter(props: {
330
374
  setCount((value) => value + 1)
331
375
  }}
332
376
  >
333
- {count()}
377
+ {getCount()}
334
378
  </button>
335
379
  </section>
336
380
  )
@@ -358,7 +402,7 @@ The checked Astro fixture demonstrates default/named slots and custom independen
358
402
 
359
403
  The build audits every browser export, including the JSX runtime, from the built JavaScript. Atom.io is an external peer in the incremental measurement. Compiler, server, and integration code have separate entrypoints. The report also includes the complete client plus atom.io, the Astro client entrypoint, and the installed Preact version under the same bundling/minification settings. These are full exported surfaces, not equivalent application benchmarks.
360
404
 
361
- The hard budget is under 3,800 bytes of ordinary level-9 gzip for the complete client export surface. Tsdown builds the package JavaScript and declarations, with separate production and development outputs that each share their runtime across entrypoints. The size audit then bundles the built exports with esbuild, minifies with Oxc, and measures compression using Node's gzip and Brotli implementations. The complete client export surface measures approximately 3.7 kB with gzip; dist/size.json records the exact build measurements. Actual application bundles add atom.io and compiler-generated application code.
405
+ The hard budget is under 4,100 bytes of ordinary level-9 gzip for the complete client export surface. Tsdown builds the package JavaScript and declarations, with separate production and development outputs that each share their runtime across entrypoints. The size audit then bundles the built exports with esbuild, minifies with Oxc, and measures compression using Node's gzip and Brotli implementations. The complete client export surface measures approximately 4.0 kB with gzip; dist/size.json records the exact build measurements. Actual application bundles add atom.io and compiler-generated application code.
362
406
 
363
407
  Build output includes the minified audit entrypoint and machine-readable dist/size.json. These audit files are a bundled measurement; use the package exports in applications so the bundler preserves one runtime instance across entrypoints. Source tests exercise development behavior; the production test executes the audited minified artifact. Chromium checks exercise the actual Astro build, island isolation, hydration, keyed identity, focus/selection, SVG namespaces, and teardown. A fresh-cache Astro development check also covers mount hooks, shared state, and ClientRouter navigation.
364
408
 
@@ -380,7 +424,7 @@ pnpm --filter @atom.io/spa readme:check
380
424
 
381
425
  Breakage exercises the packed package in isolated, locked peer environments, including the coordinated atom.io workspace candidate. Until the first published release, Breakage reports a first-release baseline; these checks establish compatibility with the declared peers rather than a previous spa release. Coverage gates require 100% of statements, branches, functions, and lines across the package source.
382
426
 
383
- Tonnage measures combined browser bundles containing SPA and atom.io, with shared modules counted once and unused exports removed. The synchronous recipes include atom creation, useValue, useSetter, and JSX; the client recipe adds render, the hydration recipe adds hydrate, and the Astro recipe adds the browser island adapter. The async recipe uses useLoadable with render and useSetter. The family recipe includes keyed state, refs, and timeline controls, plus atomFamily, timelineFamily, and scopeFamily. SPA declares atom.io as a peer dependency; these consumer-app measurements include it in every total. Application components, Astro scheduling code, CSS, declarations, and source maps are excluded. The full-client gzip budget above remains a separate, SPA-only audit.
427
+ Tonnage measures combined browser bundles containing SPA and atom.io, with shared modules counted once and unused exports removed. The synchronous recipes include atom creation, useGetter, useSetter, and JSX; the client recipe adds render, the hydration recipe adds hydrate, and the Astro recipe adds the browser island adapter. The async recipe uses useLoadable with render and useSetter. The family recipe includes keyed state, refs, and timeline controls, plus atomFamily, timelineFamily, and scopeFamily. SPA declares atom.io as a peer dependency; these consumer-app measurements include it in every total. Application components, Astro scheduling code, CSS, declarations, and source maps are excluded. The full-client gzip budget above remains a separate, SPA-only audit.
384
428
 
385
429
  ## Browser serving sizes including atom.io
386
430
 
@@ -390,11 +434,11 @@ Sizes are exact minified and level-9 gzip JavaScript byte counts. Declarations,
390
434
 
391
435
  | Recipe | Entry | Minified JS | Gzip JS |
392
436
  | -------------------------------- | --------------------------------- | ----------: | -------: |
393
- | Family app with refs and history | `tonnage-recipes/family-app.ts` | 62,395 B | 18,504 B |
394
- | Async interactive client app | `tonnage-recipes/async-app.ts` | 40,808 B | 12,714 B |
395
- | Interactive client app | `tonnage-recipes/client-app.ts` | 40,470 B | 12,559 B |
396
- | Hydrated interactive app | `tonnage-recipes/hydrated-app.ts` | 40,471 B | 12,560 B |
397
- | Interactive Astro island | `tonnage-recipes/astro-island.ts` | 46,849 B | 14,513 B |
437
+ | Family app with refs and history | `tonnage-recipes/family-app.ts` | 63,696 B | 18,887 B |
438
+ | Async interactive client app | `tonnage-recipes/async-app.ts` | 42,121 B | 13,142 B |
439
+ | Interactive client app | `tonnage-recipes/client-app.ts` | 41,784 B | 12,981 B |
440
+ | Hydrated interactive app | `tonnage-recipes/hydrated-app.ts` | 41,785 B | 12,981 B |
441
+ | Interactive Astro island | `tonnage-recipes/astro-island.ts` | 48,153 B | 14,977 B |
398
442
 
399
443
  Report maintained with [tonnage](https://github.com/jeremybanka/tonnage).
400
444
 
@@ -412,7 +456,7 @@ Import Stage, Layer, Group, Rect, Circle, Ellipse, Line, Text, Image, Path, Star
412
456
 
413
457
  ```tsx
414
458
  import type { VNode } from "@atom.io/spa"
415
- import { useSetter, useValue } from "@atom.io/spa"
459
+ import { useGetter, useSetter } from "@atom.io/spa"
416
460
  import { Circle, Layer, Stage } from "@atom.io/spa/konva"
417
461
  import { atom } from "atom.io"
418
462
 
@@ -421,14 +465,14 @@ const pointAtom = atom<{ x: number; y: number }>({
421
465
  default: { x: 100, y: 100 },
422
466
  })
423
467
  export function Editor(): VNode {
424
- const point = useValue(pointAtom)
468
+ const getPoint = useGetter(pointAtom)
425
469
  const setPoint = useSetter(pointAtom)
426
470
  return (
427
471
  <Stage width={800} height={600}>
428
472
  <Layer>
429
473
  <Circle
430
- x={point().x}
431
- y={point().y}
474
+ x={getPoint().x}
475
+ y={getPoint().y}
432
476
  radius={25}
433
477
  fill="coral"
434
478
  draggable
@@ -451,7 +495,7 @@ Import Canvas, Group, Mesh, PerspectiveCamera, AmbientLight, DirectionalLight, B
451
495
 
452
496
  ```tsx
453
497
  import type { VNode } from "@atom.io/spa"
454
- import { useValue } from "@atom.io/spa"
498
+ import { useGetter } from "@atom.io/spa"
455
499
  import {
456
500
  AmbientLight,
457
501
  BoxGeometry,
@@ -464,14 +508,14 @@ import { atom } from "atom.io"
464
508
 
465
509
  const colorAtom = atom<string>({ key: `color`, default: `coral` })
466
510
  export function Scene(): VNode {
467
- const color = useValue(colorAtom)
511
+ const getColor = useGetter(colorAtom)
468
512
  return (
469
513
  <Canvas width={800} height={600}>
470
514
  <AmbientLight intensity={0.5} />
471
515
  <DirectionalLight position={[3, 3, 3]} />
472
516
  <Mesh rotation={[0.3, 0.5, 0]}>
473
517
  <BoxGeometry args={[1, 1, 1]} />
474
- <MeshStandardMaterial color={color()} />
518
+ <MeshStandardMaterial color={getColor()} />
475
519
  </Mesh>
476
520
  </Canvas>
477
521
  )
@@ -509,22 +553,22 @@ render(() => <MotionPanel />, document.getElementById(`app`)!, {
509
553
 
510
554
  ```
511
555
 
512
- Use motion:initial, motion:animate, motion:transition, motion:whileHover, and motion:whileTap directly on native elements or custom tags. These are framework properties, separate from native attributes: they never become HTML attributes. An unregistered namespace or unsupported motion property produces an error. Standard XML, XMLNS, and XLink attribute namespaces retain their normal behavior.
556
+ Use motion:initial, motion:animate, motion:exit, motion:transition, motion:whileHover, and motion:whileTap directly on native elements or custom tags. These are framework properties, separate from native attributes: they never become HTML attributes. An unregistered namespace or unsupported motion property produces an error. Standard XML, XMLNS, and XLink attribute namespaces retain their normal behavior.
513
557
 
514
558
  ```tsx
515
559
  import type { VNode } from "@atom.io/spa"
516
- import { useSetter, useValue } from "@atom.io/spa"
560
+ import { useGetter, useSetter } from "@atom.io/spa"
517
561
  import { atom } from "atom.io"
518
562
 
519
563
  const targetXAtom = atom<number>({ key: `targetX`, default: 0 })
520
564
  export function MotionPanel(): VNode {
521
- const x = useValue(targetXAtom)
522
- const setX = useSetter(targetXAtom)
565
+ const getTargetX = useGetter(targetXAtom)
566
+ const setTargetX = useSetter(targetXAtom)
523
567
  return (
524
568
  <section>
525
569
  <button
526
570
  onClick={() => {
527
- setX((value) => (value === 0 ? 200 : 0))
571
+ setTargetX((value) => (value === 0 ? 200 : 0))
528
572
  }}
529
573
  >
530
574
  Move
@@ -532,7 +576,7 @@ export function MotionPanel(): VNode {
532
576
  <sliding-panel
533
577
  style="display: block; width: 120px; padding: 16px; background: coral"
534
578
  motion:initial={{ opacity: 0, x: -100 }}
535
- motion:animate={{ opacity: 1, x: x() }}
579
+ motion:animate={{ opacity: 1, x: getTargetX() }}
536
580
  motion:transition={{ type: `spring`, stiffness: 180, damping: 22 }}
537
581
  motion:whileHover={{ scale: 1.05 }}
538
582
  motion:whileTap={{ scale: 0.95 }}
@@ -545,7 +589,7 @@ export function MotionPanel(): VNode {
545
589
 
546
590
  ```
547
591
 
548
- Motion targets update reactively without rerunning component setup. The target stays in atom.io; intermediate values and velocity remain in Motion. Spring transitions preserve motion-value continuity when retargeted. Duration-based tween transitions are also supported. Set initial to false to begin at the first animate target. DOM targets accept scalar CSS values and independent transforms, including custom CSS properties. Keyframe sequences, layout animation, exit/presence retention, and variant propagation are outside this initial API.
592
+ Motion targets update reactively without rerunning component setup. The target stays in atom.io; intermediate values and velocity remain in Motion. Spring transitions preserve motion-value continuity when retargeted. Duration-based tween transitions are also supported. Set initial to false to begin at the first animate target. DOM targets accept scalar CSS values and independent transforms, including custom CSS properties. Keyframe sequences, layout animation, and variant propagation are outside this initial API.
549
593
 
550
594
  Motion respects the user's reduced-motion preference by default, including changes while mounted. The capability's reducedMotion option can be user, always, or never. Owner cleanup stops animations and releases effects, gesture handlers, and media-query listeners. Removing the capability properties releases that node's binding. Avoid assigning the same property through both native attributes/styles and motion targets: motion owns the properties it animates.
551
595
 
@@ -553,7 +597,7 @@ The same attributes animate numeric Konva properties and colors, or Three.js pos
553
597
 
554
598
  ```tsx
555
599
  import type { VNode } from "@atom.io/spa"
556
- import { useValue } from "@atom.io/spa"
600
+ import { useGetter } from "@atom.io/spa"
557
601
  import {
558
602
  BoxGeometry,
559
603
  Canvas,
@@ -568,12 +612,12 @@ const targetXAtom = atom<number>({
568
612
  })
569
613
  // Mount under a root with capabilities: [motionCapability()].
570
614
  export function SpringCube(): VNode {
571
- const x = useValue(targetXAtom)
615
+ const getTargetX = useGetter(targetXAtom)
572
616
  return (
573
617
  <Canvas>
574
618
  <Mesh
575
619
  motion:initial={{ position: [-1, 0, 0], scale: 0 }}
576
- motion:animate={{ position: [x(), 0, 0], scale: 1 }}
620
+ motion:animate={{ position: [getTargetX(), 0, 0], scale: 1 }}
577
621
  motion:transition={{ type: `spring`, stiffness: 180, damping: 22 }}
578
622
  motion:whileHover={{ scale: 1.2 }}
579
623
  motion:whileTap={{ scale: 0.8 }}
@@ -590,8 +634,61 @@ export function SpringCube(): VNode {
590
634
 
591
635
  ```
592
636
 
593
- When the motion capability is installed, Canvas draws in Motion's render phase after animated scene values update. Without it, Canvas uses requestAnimationFrame. Both drawing subscriptions and animations end with their owners. The base runtime imports no motion engine; its capability dispatch adds approximately 350 bytes of gzip to the previous complete client surface.
637
+ When the motion capability is installed, Canvas draws in Motion's render phase after animated scene values update. Without it, Canvas uses requestAnimationFrame. Both drawing subscriptions and animations end with their owners. The base runtime imports no motion engine or retention coordinator. Presence hooks add approximately 300 bytes of gzip to the released 3.7 kB client surface; the optional Motion entrypoint owns the retention machinery. The full client budget is 4,100 bytes.
638
+
639
+ ### Exit animations and re-entry
640
+
641
+ Declare motion:exit on an element, custom tag, Konva node, or Three.js scene node. Conditional or keyed removal starts that target from its current Motion values. No presence wrapper is required. Register motionCapability as above.
642
+
643
+ ```tsx
644
+ import type { VNode } from "@atom.io/spa"
645
+ import { useGetter, useSetter } from "@atom.io/spa"
646
+ import { atom } from "atom.io"
647
+
648
+ const visibleAtom = atom<boolean>({ key: `visible`, default: true })
649
+ export function DismissiblePanel(): VNode {
650
+ const getVisible = useGetter(visibleAtom)
651
+ const setVisible = useSetter(visibleAtom)
652
+ return (
653
+ <section>
654
+ <button
655
+ onClick={() => {
656
+ setVisible((value) => !value)
657
+ }}
658
+ >
659
+ Toggle panel
660
+ </button>
661
+ {getVisible() && (
662
+ <sliding-panel
663
+ key="panel"
664
+ motion:initial={{ opacity: 0, y: 12 }}
665
+ motion:animate={{ opacity: 1, y: 0 }}
666
+ motion:exit={{ opacity: 0, y: -12 }}
667
+ motion:transition={{ type: `spring`, stiffness: 180, damping: 22 }}
668
+ >
669
+ The same instance returns if toggled before its exit completes.
670
+ </sliding-panel>
671
+ )}
672
+ </section>
673
+ )
674
+ }
675
+
676
+ ```
677
+
678
+ In the repository, the runnable source lives in [examples/motion](https://github.com/jeremybanka/atom.io/tree/main/packages/spa/examples/motion), including its standalone Vite entrypoint and visual recorder. Run the package’s example:motion script to start it locally.
679
+
680
+ Try the [motion sandbox](https://atom.io.fyi/spa-motion-lab) to interrupt a 2s tween at adjustable speeds, inspect rendered positions and velocities, scrub the captured sequence, or export PNG and JSON evidence.
681
+
682
+ SPA retains the entire removed subtree until all its exit targets finish, including independently exiting descendants adopted by an exiting ancestor. Native nodes, scene attachments, refs, subscriptions, renderers, geometries, and materials remain owned until final disposal. When keyed Mesh resources are replaced, the incoming geometry and material attach immediately; outgoing resources remain owned through their exits without occupying those attachment slots. Removing a resource without a replacement keeps it attached until its exit finishes. Replacing resources does not render a crossfade between them. Siblings keep their instances; retained ranges keep their previous position. A target without an exit is removed immediately unless another exit retains its enclosing subtree.
683
+
684
+ Returning the same key and component or element type before disposal cancels the exit and resumes the original instance against the latest props and state. Setup, mount callbacks, and refs do not run again. Motion keeps the current animated values and spring velocity. Moving numeric tweens also preserve velocity, including matching CSS units and scene tuple components: the first 20% of the new duration brakes to rest, then the remaining 80% returns smoothly to the latest animate target. Interrupted tweens begin immediately and use this return curve instead of restarting their authored delay or easing. Fresh tweens keep their authored timing, and zero-duration or reduced-motion updates remain immediate. Discrete and nonnumeric styles retain Motion’s native interpolation. Reusing a key with an incompatible type creates a separate instance; the old generation finishes independently. Keys have meaning within their original child collection. Reordering or reparenting into another collection does not transfer ownership.
685
+
686
+ During exit, reactive attributes, child reconciliation, user events, gestures, and user onSceneFrame/onFrame callbacks pause. Renderer frame infrastructure continues drawing animated scenes. DOM nodes become inert, aria-hidden, and unavailable to pointer input; owned focus is blurred and is not automatically restored on return. Konva nodes stop listening and cancel both pending and active drags, including descendant drags when an ancestor exits. Re-entry restores the authored draggable settings; a fresh press is required to start dragging again. Three.js objects leave picking and release active pointer interaction state. Re-entry restores their prior interaction settings and handlers.
687
+
688
+ Exit props and transition settings are read at logical removal; later state changes do not retarget an exiting subtree. Exits use the same transition as animate, defaulting to a spring. Explicit durations, visualDuration, and delays must be finite and nonnegative; velocity must be finite, bounce must be in the range \[0, 1), and stiffness, damping, mass, restDelta, and restSpeed must be finite and positive so exits can settle. Reduced motion skips retention; enabling it during an exit completes that exit. Server rendering omits capability attributes and never starts exits; hydration attaches them for later removals.
689
+
690
+ Root disposal and fatal errors bypass exits, stop active work, and release resources immediately. Stale animation completions cannot dispose a revived instance. This API covers exit retention and cancellation; layout/pop-layout animation, variants, presence wrappers, and automatic reparenting remain outside its scope.
594
691
 
595
692
  ### Renderer extensions
596
693
 
597
- The renderer entrypoint exposes createSceneRenderer, sceneComponent, bindScene, and onSceneFrame for imperative scene adapters. A host supplies creation, property updates, ordered child attachment, and destruction. An optional target adapter exposes native property access and events to capabilities. The shared renderer supplies reactive bindings, keyed identity, refs, and cleanup. Use mount inside an owned component or mount callback to inherit its store, capabilities, and lifetime, or render with an explicit parent and optional root options to create a standalone scene root. Scene targets must be dedicated to their renderer's children. Scene subtrees do not support text nodes or hydration; their DOM boundaries defer graphics creation until browser mount. Server rendering validates and omits capability attributes without starting animations.
694
+ The renderer entrypoint exposes createSceneRenderer, sceneComponent, bindScene, and onSceneFrame for imperative scene adapters. A host supplies creation, property updates, ordered child attachment, and destruction. Its children callback receives the parent, all owned children including retained exits, and the active children in that collection. Single resource slots can use active children for replacement while retaining ownership of outgoing resources. Children of an exiting parent keep their attachments until disposal. An optional target adapter exposes native property access and events to capabilities. The shared renderer supplies reactive bindings, keyed identity, refs, and cleanup. Use mount inside an owned component or mount callback to inherit its store, capabilities, and lifetime, or render with an explicit parent and optional root options to create a standalone scene root. Scene targets must be dedicated to their renderer's children. Scene subtrees do not support text nodes or hydration; their DOM boundaries defer graphics creation until browser mount. Server rendering validates and omits capability attributes without starting animations.
package/README.mdx CHANGED
@@ -2,6 +2,7 @@ import { Tonnage } from "tonnage";
2
2
  import config from "./tonnage.config.ts";
3
3
  import StoreExample from "./exhibits/store.tsx" with { type: "code" };
4
4
  import Families from "./exhibits/families.tsx" with { type: "code" };
5
+ import TimelineExample from "./exhibits/timeline.tsx" with { type: "code" };
5
6
  import LoadableExample from "./exhibits/loadable.tsx" with { type: "code" };
6
7
  import Point from "./exhibits/point.tsx" with { type: "code" };
7
8
  import ViteConfig from "./exhibits/vite.config.ts" with { type: "code" };
@@ -15,6 +16,7 @@ import KonvaExample from "./exhibits/konva.spa.tsx" with { type: "code" };
15
16
  import ThreeExample from "./exhibits/three.spa.tsx" with { type: "code" };
16
17
  import MotionPanel from "./exhibits/motion.spa.tsx" with { type: "code" };
17
18
  import MotionMain from "./exhibits/motion-main.tsx" with { type: "code" };
19
+ import MotionExit from "./exhibits/motion-exit.spa.tsx" with { type: "code" };
18
20
  import MotionThree from "./exhibits/motion-three.spa.tsx" with { type: "code" };
19
21
 
20
22
  <p align="center">
@@ -31,7 +33,7 @@ The npm package is named @atom.io/spa. Its browser runtime, Vite compiler, serve
31
33
 
32
34
  <Point />
33
35
 
34
- The point accessor returns the current object. Each JSX attribute reads its coordinate when evaluated. Both bindings depend on the point atom, and unchanged primitive results skip DOM writes. Reads during setup are snapshots; reads in event handlers are current and untracked. Shared derived state belongs in atom.io selectors.
36
+ Name the getter and setter after the atom: pointAtom uses getPoint and setPoint. The getPoint getter returns the current object. Each JSX attribute reads its coordinate when evaluated. Both bindings depend on the point atom, and unchanged primitive results skip DOM writes. Reads during setup are snapshots; reads in event handlers are current and untracked. Shared derived state belongs in atom.io selectors.
35
37
 
36
38
  ## Vite
37
39
 
@@ -50,9 +52,9 @@ The development plugin keeps SPA and atom.io outside dependency prebundling so r
50
52
  | API | Contract |
51
53
  | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
52
54
  | useLoadable(token, fallback?) | Return a tracked accessor for loading, last-observed values, and handled errors. |
53
- | useValue(token) | Return a live accessor for an atom or selector, bound to this instance's store. |
55
+ | useGetter(token) | Return a live accessor for an atom or selector, bound to this instance's store. |
54
56
  | useSetter(token) | Return a stable atom.io writer. |
55
- | useTimeline(token) | Return an accessor for at, length, undo, redo, clear, and available grouped transaction controls. |
57
+ | useTimeline(token) | Return a stable object with getCursor/getLength readers, undo/redo/clear commands, and transaction-group controls. |
56
58
  | useTransaction(token) | Bind an atom.io transaction, preserving its arguments and result. |
57
59
  | useRef(token) | Return an attachment callback for a nullable element atom. Clear it only while this attachment still owns the reference. |
58
60
  | useId() | Allocate an instance-stable ID using the root's prefix. |
@@ -62,6 +64,10 @@ The development plugin keeps SPA and atom.io outside dependency prebundling so r
62
64
 
63
65
  Call setup helpers synchronously during component setup or owned mount callbacks. Capture their results for event handlers. Tokens are fixed for an instance; use an application key in a reactive child expression to replace a component when its token changes. Component props stay live when read through the props object; destructuring during setup takes a snapshot.
64
66
 
67
+ useTimeline returns a TimelineControls object whose methods can be destructured during setup. getCursor and getLength read the current cursor position and recorded checkpoint count; calls inside JSX subscribe the computation, while calls during setup or in event handlers are untracked. undo, redo, and clear are stable commands. history.getTransaction() is a tracked reader that returns an object with optional undo and redo callbacks for the adjacent transaction groups. At a cursor between transactions, both callbacks may be present and target different groups. A missing callback means no transaction group is available in that direction; the reader returns an empty object when neither is available. Calling a returned callback travels its captured group across participating timelines where it remains at the relevant history head, leaving diverged timelines unchanged. Use history.getTransaction().undo?.() or history.getTransaction().redo?.() to retrieve and invoke the current action together.
68
+
69
+ <TimelineExample />
70
+
65
71
  Arrays support keyed components and elements. Reordering preserves instances and nodes; removed ranges release subscriptions, events, refs, and cleanup callbacks. Application keys must be unique among siblings. Explicit keys are compared as strings; unkeyed positions occupy a separate namespace. Unkeyed arrays use positions. A key identifies a row in a reactive child collection; it is not an independent reactive binding.
66
72
 
67
73
  HTML and SVG use native DOM properties and attributes, plus className/htmlFor aliases. Events use onClick/onInput-style names, with Capture suffixes and onDoubleClick support. Styles are CSS strings. Mutable atom values still invalidate their consumers; project primitive fields for precise DOM writes. Refs attach once per element instance.
@@ -74,11 +80,11 @@ useStore returns the current root's atom.io RootStore directly. It is the same o
74
80
 
75
81
  <StoreExample />
76
82
 
77
- Capture the store during component setup or an owned onMount callback, then pass it to store-aware atom.io operations or integrations. Getting the store creates no subscription. Direct reads such as getFromStore do not participate in SPA's dependency tracking; useValue and useLoadable provide tracked reads. The returned object is a store, not a Silo or a new wrapper.
83
+ Capture the store during component setup or an owned onMount callback, then pass it to store-aware atom.io operations or integrations. Getting the store creates no subscription. Direct reads such as getFromStore do not participate in SPA's dependency tracking; useGetter and useLoadable provide tracked reads. The returned object is a store, not a Silo or a new wrapper.
78
84
 
79
85
  ## Families
80
86
 
81
- useValue, useSetter, useRef, and useTimeline accept a family token followed by its key. useLoadable accepts a family, key, and optional fallback. Keys retain their declared types, including tuples, numbers, booleans, and null. Members resolve in the component's store, so isolated roots can use the same family tokens independently.
87
+ useGetter, useSetter, useRef, and useTimeline accept a family token followed by its key. useLoadable accepts a family, key, and optional fallback. Keys retain their declared types, including tuples, numbers, booleans, and null. Members resolve in the component's store, so isolated roots can use the same family tokens independently.
82
88
 
83
89
  <Families />
84
90
 
@@ -136,7 +142,7 @@ The checked Astro fixture demonstrates default/named slots and custom independen
136
142
 
137
143
  The build audits every browser export, including the JSX runtime, from the built JavaScript. Atom.io is an external peer in the incremental measurement. Compiler, server, and integration code have separate entrypoints. The report also includes the complete client plus atom.io, the Astro client entrypoint, and the installed Preact version under the same bundling/minification settings. These are full exported surfaces, not equivalent application benchmarks.
138
144
 
139
- The hard budget is under 3,800 bytes of ordinary level-9 gzip for the complete client export surface. Tsdown builds the package JavaScript and declarations, with separate production and development outputs that each share their runtime across entrypoints. The size audit then bundles the built exports with esbuild, minifies with Oxc, and measures compression using Node's gzip and Brotli implementations. The complete client export surface measures approximately 3.7 kB with gzip; dist/size.json records the exact build measurements. Actual application bundles add atom.io and compiler-generated application code.
145
+ The hard budget is under 4,100 bytes of ordinary level-9 gzip for the complete client export surface. Tsdown builds the package JavaScript and declarations, with separate production and development outputs that each share their runtime across entrypoints. The size audit then bundles the built exports with esbuild, minifies with Oxc, and measures compression using Node's gzip and Brotli implementations. The complete client export surface measures approximately 4.0 kB with gzip; dist/size.json records the exact build measurements. Actual application bundles add atom.io and compiler-generated application code.
140
146
 
141
147
  Build output includes the minified audit entrypoint and machine-readable dist/size.json. These audit files are a bundled measurement; use the package exports in applications so the bundler preserves one runtime instance across entrypoints. Source tests exercise development behavior; the production test executes the audited minified artifact. Chromium checks exercise the actual Astro build, island isolation, hydration, keyed identity, focus/selection, SVG namespaces, and teardown. A fresh-cache Astro development check also covers mount hooks, shared state, and ClientRouter navigation.
142
148
 
@@ -146,7 +152,7 @@ Build output includes the minified audit entrypoint and machine-readable dist/si
146
152
 
147
153
  Breakage exercises the packed package in isolated, locked peer environments, including the coordinated atom.io workspace candidate. Until the first published release, Breakage reports a first-release baseline; these checks establish compatibility with the declared peers rather than a previous spa release. Coverage gates require 100% of statements, branches, functions, and lines across the package source.
148
154
 
149
- Tonnage measures combined browser bundles containing SPA and atom.io, with shared modules counted once and unused exports removed. The synchronous recipes include atom creation, useValue, useSetter, and JSX; the client recipe adds render, the hydration recipe adds hydrate, and the Astro recipe adds the browser island adapter. The async recipe uses useLoadable with render and useSetter. The family recipe includes keyed state, refs, and timeline controls, plus atomFamily, timelineFamily, and scopeFamily. SPA declares atom.io as a peer dependency; these consumer-app measurements include it in every total. Application components, Astro scheduling code, CSS, declarations, and source maps are excluded. The full-client gzip budget above remains a separate, SPA-only audit.
155
+ Tonnage measures combined browser bundles containing SPA and atom.io, with shared modules counted once and unused exports removed. The synchronous recipes include atom creation, useGetter, useSetter, and JSX; the client recipe adds render, the hydration recipe adds hydrate, and the Astro recipe adds the browser island adapter. The async recipe uses useLoadable with render and useSetter. The family recipe includes keyed state, refs, and timeline controls, plus atomFamily, timelineFamily, and scopeFamily. SPA declares atom.io as a peer dependency; these consumer-app measurements include it in every total. Application components, Astro scheduling code, CSS, declarations, and source maps are excluded. The full-client gzip budget above remains a separate, SPA-only audit.
150
156
 
151
157
  <Tonnage config={config} />
152
158
 
@@ -192,11 +198,11 @@ Import motionCapability from @atom.io/spa/motion and register it explicitly in r
192
198
 
193
199
  <MotionMain />
194
200
 
195
- Use motion:initial, motion:animate, motion:transition, motion:whileHover, and motion:whileTap directly on native elements or custom tags. These are framework properties, separate from native attributes: they never become HTML attributes. An unregistered namespace or unsupported motion property produces an error. Standard XML, XMLNS, and XLink attribute namespaces retain their normal behavior.
201
+ Use motion:initial, motion:animate, motion:exit, motion:transition, motion:whileHover, and motion:whileTap directly on native elements or custom tags. These are framework properties, separate from native attributes: they never become HTML attributes. An unregistered namespace or unsupported motion property produces an error. Standard XML, XMLNS, and XLink attribute namespaces retain their normal behavior.
196
202
 
197
203
  <MotionPanel />
198
204
 
199
- Motion targets update reactively without rerunning component setup. The target stays in atom.io; intermediate values and velocity remain in Motion. Spring transitions preserve motion-value continuity when retargeted. Duration-based tween transitions are also supported. Set initial to false to begin at the first animate target. DOM targets accept scalar CSS values and independent transforms, including custom CSS properties. Keyframe sequences, layout animation, exit/presence retention, and variant propagation are outside this initial API.
205
+ Motion targets update reactively without rerunning component setup. The target stays in atom.io; intermediate values and velocity remain in Motion. Spring transitions preserve motion-value continuity when retargeted. Duration-based tween transitions are also supported. Set initial to false to begin at the first animate target. DOM targets accept scalar CSS values and independent transforms, including custom CSS properties. Keyframe sequences, layout animation, and variant propagation are outside this initial API.
200
206
 
201
207
  Motion respects the user's reduced-motion preference by default, including changes while mounted. The capability's reducedMotion option can be user, always, or never. Owner cleanup stops animations and releases effects, gesture handlers, and media-query listeners. Removing the capability properties releases that node's binding. Avoid assigning the same property through both native attributes/styles and motion targets: motion owns the properties it animates.
202
208
 
@@ -204,8 +210,28 @@ The same attributes animate numeric Konva properties and colors, or Three.js pos
204
210
 
205
211
  <MotionThree />
206
212
 
207
- When the motion capability is installed, Canvas draws in Motion's render phase after animated scene values update. Without it, Canvas uses requestAnimationFrame. Both drawing subscriptions and animations end with their owners. The base runtime imports no motion engine; its capability dispatch adds approximately 350 bytes of gzip to the previous complete client surface.
213
+ When the motion capability is installed, Canvas draws in Motion's render phase after animated scene values update. Without it, Canvas uses requestAnimationFrame. Both drawing subscriptions and animations end with their owners. The base runtime imports no motion engine or retention coordinator. Presence hooks add approximately 300 bytes of gzip to the released 3.7 kB client surface; the optional Motion entrypoint owns the retention machinery. The full client budget is 4,100 bytes.
214
+
215
+ ### Exit animations and re-entry
216
+
217
+ Declare motion:exit on an element, custom tag, Konva node, or Three.js scene node. Conditional or keyed removal starts that target from its current Motion values. No presence wrapper is required. Register motionCapability as above.
218
+
219
+ <MotionExit />
220
+
221
+ In the repository, the runnable source lives in [examples/motion](https://github.com/jeremybanka/atom.io/tree/main/packages/spa/examples/motion), including its standalone Vite entrypoint and visual recorder. Run the package’s example:motion script to start it locally.
222
+
223
+ Try the [motion sandbox](https://atom.io.fyi/spa-motion-lab) to interrupt a 2s tween at adjustable speeds, inspect rendered positions and velocities, scrub the captured sequence, or export PNG and JSON evidence.
224
+
225
+ SPA retains the entire removed subtree until all its exit targets finish, including independently exiting descendants adopted by an exiting ancestor. Native nodes, scene attachments, refs, subscriptions, renderers, geometries, and materials remain owned until final disposal. When keyed Mesh resources are replaced, the incoming geometry and material attach immediately; outgoing resources remain owned through their exits without occupying those attachment slots. Removing a resource without a replacement keeps it attached until its exit finishes. Replacing resources does not render a crossfade between them. Siblings keep their instances; retained ranges keep their previous position. A target without an exit is removed immediately unless another exit retains its enclosing subtree.
226
+
227
+ Returning the same key and component or element type before disposal cancels the exit and resumes the original instance against the latest props and state. Setup, mount callbacks, and refs do not run again. Motion keeps the current animated values and spring velocity. Moving numeric tweens also preserve velocity, including matching CSS units and scene tuple components: the first 20% of the new duration brakes to rest, then the remaining 80% returns smoothly to the latest animate target. Interrupted tweens begin immediately and use this return curve instead of restarting their authored delay or easing. Fresh tweens keep their authored timing, and zero-duration or reduced-motion updates remain immediate. Discrete and nonnumeric styles retain Motion’s native interpolation. Reusing a key with an incompatible type creates a separate instance; the old generation finishes independently. Keys have meaning within their original child collection. Reordering or reparenting into another collection does not transfer ownership.
228
+
229
+ During exit, reactive attributes, child reconciliation, user events, gestures, and user onSceneFrame/onFrame callbacks pause. Renderer frame infrastructure continues drawing animated scenes. DOM nodes become inert, aria-hidden, and unavailable to pointer input; owned focus is blurred and is not automatically restored on return. Konva nodes stop listening and cancel both pending and active drags, including descendant drags when an ancestor exits. Re-entry restores the authored draggable settings; a fresh press is required to start dragging again. Three.js objects leave picking and release active pointer interaction state. Re-entry restores their prior interaction settings and handlers.
230
+
231
+ Exit props and transition settings are read at logical removal; later state changes do not retarget an exiting subtree. Exits use the same transition as animate, defaulting to a spring. Explicit durations, visualDuration, and delays must be finite and nonnegative; velocity must be finite, bounce must be in the range [0, 1), and stiffness, damping, mass, restDelta, and restSpeed must be finite and positive so exits can settle. Reduced motion skips retention; enabling it during an exit completes that exit. Server rendering omits capability attributes and never starts exits; hydration attaches them for later removals.
232
+
233
+ Root disposal and fatal errors bypass exits, stop active work, and release resources immediately. Stale animation completions cannot dispose a revived instance. This API covers exit retention and cancellation; layout/pop-layout animation, variants, presence wrappers, and automatic reparenting remain outside its scope.
208
234
 
209
235
  ### Renderer extensions
210
236
 
211
- The renderer entrypoint exposes createSceneRenderer, sceneComponent, bindScene, and onSceneFrame for imperative scene adapters. A host supplies creation, property updates, ordered child attachment, and destruction. An optional target adapter exposes native property access and events to capabilities. The shared renderer supplies reactive bindings, keyed identity, refs, and cleanup. Use mount inside an owned component or mount callback to inherit its store, capabilities, and lifetime, or render with an explicit parent and optional root options to create a standalone scene root. Scene targets must be dedicated to their renderer's children. Scene subtrees do not support text nodes or hydration; their DOM boundaries defer graphics creation until browser mount. Server rendering validates and omits capability attributes without starting animations.
237
+ The renderer entrypoint exposes createSceneRenderer, sceneComponent, bindScene, and onSceneFrame for imperative scene adapters. A host supplies creation, property updates, ordered child attachment, and destruction. Its children callback receives the parent, all owned children including retained exits, and the active children in that collection. Single resource slots can use active children for replacement while retaining ownership of outgoing resources. Children of an exiting parent keep their attachments until disposal. An optional target adapter exposes native property access and events to capabilities. The shared renderer supplies reactive bindings, keyed identity, refs, and cleanup. Use mount inside an owned component or mount callback to inherit its store, capabilities, and lifetime, or render with an explicit parent and optional root options to create a standalone scene root. Scene targets must be dedicated to their renderer's children. Scene subtrees do not support text nodes or hydration; their DOM boundaries defer graphics creation until browser mount. Server rendering validates and omits capability attributes without starting animations.
@@ -1,4 +1,4 @@
1
- import { t as AstroApplicationContext } from "./astro-shared-DyzbUi6c.js";
1
+ import { t as AstroApplicationContext } from "./astro-shared-CYSRrRr8.js";
2
2
  type Lifetime = {
3
3
  signal: AbortSignal;
4
4
  onCleanup(cleanup: () => void): () => void;
@@ -1,5 +1,5 @@
1
1
  import { t as applicationContext } from "./astro-context-OdlexHR4.js";
2
- import { IMPLICIT, withdraw } from "atom.io/internal";
2
+ import { IMPLICIT, subscribeToStateSubject, withdraw } from "atom.io/internal";
3
3
  // src/astro-application.ts
4
4
  const applications = /* @__PURE__ */ new WeakMap();
5
5
  /** Called by the integration's early page script, before island preparation. */
@@ -21,7 +21,7 @@ function browserApplication(document) {
21
21
  if (store.valueMap.has(token.key)) changed();
22
22
  subscriptions.get(token.key)?.();
23
23
  const state = withdraw(store, token);
24
- subscriptions.set(token.key, state.subject.subscribe(`spa:bootstrap`, changed));
24
+ subscriptions.set(token.key, subscribeToStateSubject(state, `spa:bootstrap`, changed));
25
25
  };
26
26
  for (const state of [
27
27
  ...store.atoms.values(),
@@ -1 +1 @@
1
- {"version":3,"file":"astro-application.js","names":[],"sources":["../src/astro-application.ts"],"sourcesContent":["import type { ReadableToken } from \"atom.io\"\nimport { IMPLICIT, withdraw } from \"atom.io/internal\"\n\nimport { applicationContext } from \"./astro-context.ts\"\n\nconst applications = new WeakMap<\n\tDocument,\n\tReturnType<typeof applicationContext>\n>()\n\n/** Called by the integration's early page script, before island preparation. */\nexport function browserApplication(\n\tdocument: Document,\n): ReturnType<typeof applicationContext> {\n\tlet application = applications.get(document)\n\tif (application) return application\n\tapplication = applicationContext()\n\tconst app = application\n\tconst store = IMPLICIT.STORE\n\tconst originalDefault = store.runDefault\n\tapplications.set(document, app)\n\tconst changed = () => {\n\t\tapp.canResume = false\n\t}\n\tconst internal = (key: string) => key.startsWith(`🔍 spa islands`)\n\tconst subscriptions = new Map<string, () => void>()\n\tconst watch = (token: ReadableToken<unknown, any, any>) => {\n\t\tif (internal(token.key)) return\n\t\tif (store.valueMap.has(token.key)) changed()\n\t\tsubscriptions.get(token.key)?.()\n\t\tconst state = withdraw(store, token)\n\t\tsubscriptions.set(\n\t\t\ttoken.key,\n\t\t\tstate.subject.subscribe(`spa:bootstrap`, changed),\n\t\t)\n\t}\n\tfor (const state of [\n\t\t...store.atoms.values(),\n\t\t...store.readonlySelectors.values(),\n\t\t...store.writableSelectors.values(),\n\t])\n\t\twatch(state)\n\tconst removed = (token: ReadableToken<unknown, any, any>) => {\n\t\tif (!internal(token.key)) {\n\t\t\tchanged()\n\t\t\tsubscriptions.get(token.key)?.()\n\t\t\tsubscriptions.delete(token.key)\n\t\t}\n\t}\n\tconst events = [\n\t\tstore.on.atomCreation.subscribe(`spa:bootstrap`, watch),\n\t\tstore.on.selectorCreation.subscribe(`spa:bootstrap`, watch),\n\t\tstore.on.atomDisposal.subscribe(`spa:bootstrap`, removed),\n\t\tstore.on.selectorDisposal.subscribe(`spa:bootstrap`, removed),\n\t\tstore.on.transactionCommit.subscribe(`spa:bootstrap`, changed),\n\t]\n\tdocument.addEventListener(`astro:before-swap`, changed)\n\tconst pagehide = (event: PageTransitionEvent) => {\n\t\tif (!event.persisted) app.dispose()\n\t}\n\tdocument.defaultView?.addEventListener(`pagehide`, pagehide)\n\tapp.onCleanup(() => {\n\t\tfor (const unsubscribe of subscriptions.values()) unsubscribe()\n\t\tfor (const unsubscribe of events) unsubscribe()\n\t\tdocument.removeEventListener(`astro:before-swap`, changed)\n\t\tdocument.defaultView?.removeEventListener(`pagehide`, pagehide)\n\t\tstore.runDefault = originalDefault\n\t\tapplications.delete(document)\n\t})\n\treturn app\n}\n"],"mappings":";;;AAKA,MAAM,+BAAe,IAAI,QAGvB;;AAGF,SAAgB,mBACf,UACwC;CACxC,IAAI,cAAc,aAAa,IAAI,QAAQ;CAC3C,IAAI,aAAa,OAAO;CACxB,cAAc,mBAAmB;CACjC,MAAM,MAAM;CACZ,MAAM,QAAQ,SAAS;CACvB,MAAM,kBAAkB,MAAM;CAC9B,aAAa,IAAI,UAAU,GAAG;CAC9B,MAAM,gBAAgB;EACrB,IAAI,YAAY;CACjB;CACA,MAAM,YAAY,QAAgB,IAAI,WAAW,gBAAgB;CACjE,MAAM,gCAAgB,IAAI,IAAwB;CAClD,MAAM,SAAS,UAA4C;EAC1D,IAAI,SAAS,MAAM,GAAG,GAAG;EACzB,IAAI,MAAM,SAAS,IAAI,MAAM,GAAG,GAAG,QAAQ;EAC3C,cAAc,IAAI,MAAM,GAAG,CAAC,GAAG;EAC/B,MAAM,QAAQ,SAAS,OAAO,KAAK;EACnC,cAAc,IACb,MAAM,KACN,MAAM,QAAQ,UAAU,iBAAiB,OAAO,CACjD;CACD;CACA,KAAK,MAAM,SAAS;EACnB,GAAG,MAAM,MAAM,OAAO;EACtB,GAAG,MAAM,kBAAkB,OAAO;EAClC,GAAG,MAAM,kBAAkB,OAAO;CACnC,GACC,MAAM,KAAK;CACZ,MAAM,WAAW,UAA4C;EAC5D,IAAI,CAAC,SAAS,MAAM,GAAG,GAAG;GACzB,QAAQ;GACR,cAAc,IAAI,MAAM,GAAG,CAAC,GAAG;GAC/B,cAAc,OAAO,MAAM,GAAG;EAC/B;CACD;CACA,MAAM,SAAS;EACd,MAAM,GAAG,aAAa,UAAU,iBAAiB,KAAK;EACtD,MAAM,GAAG,iBAAiB,UAAU,iBAAiB,KAAK;EAC1D,MAAM,GAAG,aAAa,UAAU,iBAAiB,OAAO;EACxD,MAAM,GAAG,iBAAiB,UAAU,iBAAiB,OAAO;EAC5D,MAAM,GAAG,kBAAkB,UAAU,iBAAiB,OAAO;CAC9D;CACA,SAAS,iBAAiB,qBAAqB,OAAO;CACtD,MAAM,YAAY,UAA+B;EAChD,IAAI,CAAC,MAAM,WAAW,IAAI,QAAQ;CACnC;CACA,SAAS,aAAa,iBAAiB,YAAY,QAAQ;CAC3D,IAAI,gBAAgB;EACnB,KAAK,MAAM,eAAe,cAAc,OAAO,GAAG,YAAY;EAC9D,KAAK,MAAM,eAAe,QAAQ,YAAY;EAC9C,SAAS,oBAAoB,qBAAqB,OAAO;EACzD,SAAS,aAAa,oBAAoB,YAAY,QAAQ;EAC9D,MAAM,aAAa;EACnB,aAAa,OAAO,QAAQ;CAC7B,CAAC;CACD,OAAO;AACR"}
1
+ {"version":3,"file":"astro-application.js","names":[],"sources":["../src/astro-application.ts"],"sourcesContent":["import type { ReadableToken } from \"atom.io\"\nimport { IMPLICIT, subscribeToStateSubject, withdraw } from \"atom.io/internal\"\n\nimport { applicationContext } from \"./astro-context.ts\"\n\nconst applications = new WeakMap<\n\tDocument,\n\tReturnType<typeof applicationContext>\n>()\n\n/** Called by the integration's early page script, before island preparation. */\nexport function browserApplication(\n\tdocument: Document,\n): ReturnType<typeof applicationContext> {\n\tlet application = applications.get(document)\n\tif (application) return application\n\tapplication = applicationContext()\n\tconst app = application\n\tconst store = IMPLICIT.STORE\n\tconst originalDefault = store.runDefault\n\tapplications.set(document, app)\n\tconst changed = () => {\n\t\tapp.canResume = false\n\t}\n\tconst internal = (key: string) => key.startsWith(`🔍 spa islands`)\n\tconst subscriptions = new Map<string, () => void>()\n\tconst watch = (token: ReadableToken<unknown, any, any>) => {\n\t\tif (internal(token.key)) return\n\t\tif (store.valueMap.has(token.key)) changed()\n\t\tsubscriptions.get(token.key)?.()\n\t\tconst state = withdraw(store, token)\n\t\tsubscriptions.set(\n\t\t\ttoken.key,\n\t\t\tsubscribeToStateSubject(state, `spa:bootstrap`, changed),\n\t\t)\n\t}\n\tfor (const state of [\n\t\t...store.atoms.values(),\n\t\t...store.readonlySelectors.values(),\n\t\t...store.writableSelectors.values(),\n\t])\n\t\twatch(state)\n\tconst removed = (token: ReadableToken<unknown, any, any>) => {\n\t\tif (!internal(token.key)) {\n\t\t\tchanged()\n\t\t\tsubscriptions.get(token.key)?.()\n\t\t\tsubscriptions.delete(token.key)\n\t\t}\n\t}\n\tconst events = [\n\t\tstore.on.atomCreation.subscribe(`spa:bootstrap`, watch),\n\t\tstore.on.selectorCreation.subscribe(`spa:bootstrap`, watch),\n\t\tstore.on.atomDisposal.subscribe(`spa:bootstrap`, removed),\n\t\tstore.on.selectorDisposal.subscribe(`spa:bootstrap`, removed),\n\t\tstore.on.transactionCommit.subscribe(`spa:bootstrap`, changed),\n\t]\n\tdocument.addEventListener(`astro:before-swap`, changed)\n\tconst pagehide = (event: PageTransitionEvent) => {\n\t\tif (!event.persisted) app.dispose()\n\t}\n\tdocument.defaultView?.addEventListener(`pagehide`, pagehide)\n\tapp.onCleanup(() => {\n\t\tfor (const unsubscribe of subscriptions.values()) unsubscribe()\n\t\tfor (const unsubscribe of events) unsubscribe()\n\t\tdocument.removeEventListener(`astro:before-swap`, changed)\n\t\tdocument.defaultView?.removeEventListener(`pagehide`, pagehide)\n\t\tstore.runDefault = originalDefault\n\t\tapplications.delete(document)\n\t})\n\treturn app\n}\n"],"mappings":";;;AAKA,MAAM,+BAAe,IAAI,QAGvB;;AAGF,SAAgB,mBACf,UACwC;CACxC,IAAI,cAAc,aAAa,IAAI,QAAQ;CAC3C,IAAI,aAAa,OAAO;CACxB,cAAc,mBAAmB;CACjC,MAAM,MAAM;CACZ,MAAM,QAAQ,SAAS;CACvB,MAAM,kBAAkB,MAAM;CAC9B,aAAa,IAAI,UAAU,GAAG;CAC9B,MAAM,gBAAgB;EACrB,IAAI,YAAY;CACjB;CACA,MAAM,YAAY,QAAgB,IAAI,WAAW,gBAAgB;CACjE,MAAM,gCAAgB,IAAI,IAAwB;CAClD,MAAM,SAAS,UAA4C;EAC1D,IAAI,SAAS,MAAM,GAAG,GAAG;EACzB,IAAI,MAAM,SAAS,IAAI,MAAM,GAAG,GAAG,QAAQ;EAC3C,cAAc,IAAI,MAAM,GAAG,CAAC,GAAG;EAC/B,MAAM,QAAQ,SAAS,OAAO,KAAK;EACnC,cAAc,IACb,MAAM,KACN,wBAAwB,OAAO,iBAAiB,OAAO,CACxD;CACD;CACA,KAAK,MAAM,SAAS;EACnB,GAAG,MAAM,MAAM,OAAO;EACtB,GAAG,MAAM,kBAAkB,OAAO;EAClC,GAAG,MAAM,kBAAkB,OAAO;CACnC,GACC,MAAM,KAAK;CACZ,MAAM,WAAW,UAA4C;EAC5D,IAAI,CAAC,SAAS,MAAM,GAAG,GAAG;GACzB,QAAQ;GACR,cAAc,IAAI,MAAM,GAAG,CAAC,GAAG;GAC/B,cAAc,OAAO,MAAM,GAAG;EAC/B;CACD;CACA,MAAM,SAAS;EACd,MAAM,GAAG,aAAa,UAAU,iBAAiB,KAAK;EACtD,MAAM,GAAG,iBAAiB,UAAU,iBAAiB,KAAK;EAC1D,MAAM,GAAG,aAAa,UAAU,iBAAiB,OAAO;EACxD,MAAM,GAAG,iBAAiB,UAAU,iBAAiB,OAAO;EAC5D,MAAM,GAAG,kBAAkB,UAAU,iBAAiB,OAAO;CAC9D;CACA,SAAS,iBAAiB,qBAAqB,OAAO;CACtD,MAAM,YAAY,UAA+B;EAChD,IAAI,CAAC,MAAM,WAAW,IAAI,QAAQ;CACnC;CACA,SAAS,aAAa,iBAAiB,YAAY,QAAQ;CAC3D,IAAI,gBAAgB;EACnB,KAAK,MAAM,eAAe,cAAc,OAAO,GAAG,YAAY;EAC9D,KAAK,MAAM,eAAe,QAAQ,YAAY;EAC9C,SAAS,oBAAoB,qBAAqB,OAAO;EACzD,SAAS,aAAa,oBAAoB,YAAY,QAAQ;EAC9D,MAAM,aAAa;EACnB,aAAa,OAAO,QAAQ;CAC7B,CAAC;CACD,OAAO;AACR"}
@@ -1,4 +1,4 @@
1
- import { a as Island } from "./astro-shared-DyzbUi6c.js";
1
+ import { a as Island } from "./astro-shared-CYSRrRr8.js";
2
2
  type Props = Record<string, any>;
3
3
  type Slots = Record<string, string>;
4
4
  type Hydrator = (component: Island, props: Props, slots: Slots, metadata: {