@atom.io/spa 0.0.6 → 0.0.7

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 (78) hide show
  1. package/README.md +282 -10
  2. package/README.mdx +65 -5
  3. package/dist/astro-application.d.ts +1 -1
  4. package/dist/astro-client.d.ts +1 -1
  5. package/dist/astro-client.js +2 -2
  6. package/dist/astro-resumability-client.d.ts +1 -1
  7. package/dist/astro-server.js +1 -1
  8. package/dist/{astro-shared-B9wvGIkk.d.ts → astro-shared-DZp1x8RQ.d.ts} +2 -2
  9. package/dist/{astro-shared-B9wvGIkk.d.ts.map → astro-shared-DZp1x8RQ.d.ts.map} +1 -1
  10. package/dist/astro.d.ts +1 -1
  11. package/dist/{capabilities-_zOwNJ-2.d.ts → capabilities-DNcnGRv_.d.ts} +7 -3
  12. package/dist/capabilities-DNcnGRv_.d.ts.map +1 -0
  13. package/dist/capabilities-nOIitQ-_.js.map +1 -1
  14. package/dist/client.min.js +1 -1
  15. package/dist/{core-DjFJ0aIJ.js → core-B4rJ0xdc.js} +22 -12
  16. package/dist/core-B4rJ0xdc.js.map +1 -0
  17. package/dist/development/astro-client.js +2 -2
  18. package/dist/development/astro-server.js +1 -1
  19. package/dist/development/capabilities-nOIitQ-_.js.map +1 -1
  20. package/dist/development/{core-DxPiKryn.js → core-BHA7I1nf.js} +24 -14
  21. package/dist/development/core-BHA7I1nf.js.map +1 -0
  22. package/dist/development/{dom-BWy4dDss.js → dom-DQ0M3rLL.js} +2 -2
  23. package/dist/development/{dom-BWy4dDss.js.map → dom-DQ0M3rLL.js.map} +1 -1
  24. package/dist/development/floating.js +1 -1
  25. package/dist/development/index.js +4 -4
  26. package/dist/development/konva.js +1 -1
  27. package/dist/development/motion.js +413 -24
  28. package/dist/development/motion.js.map +1 -1
  29. package/dist/development/renderer.js +1 -1
  30. package/dist/development/{server-renderer-C7lGVhpo.js → server-renderer-DCLoMdOX.js} +2 -2
  31. package/dist/development/{server-renderer-C7lGVhpo.js.map → server-renderer-DCLoMdOX.js.map} +1 -1
  32. package/dist/development/server.js +1 -1
  33. package/dist/development/{src-WSHJxR9b.js → src-DoQgCX-O.js} +2 -2
  34. package/dist/development/{src-WSHJxR9b.js.map → src-DoQgCX-O.js.map} +1 -1
  35. package/dist/development/three.js +76 -23
  36. package/dist/development/three.js.map +1 -1
  37. package/dist/{dom-BrPrxO97.js → dom-D8g3roX9.js} +2 -2
  38. package/dist/{dom-BrPrxO97.js.map → dom-D8g3roX9.js.map} +1 -1
  39. package/dist/floating.d.ts +1 -1
  40. package/dist/floating.js +1 -1
  41. package/dist/{index-BFIjI7gF.d.ts → index-BFnXIfOj.d.ts} +3 -3
  42. package/dist/{index-BFIjI7gF.d.ts.map → index-BFnXIfOj.d.ts.map} +1 -1
  43. package/dist/index.d.ts +4 -4
  44. package/dist/index.js +4 -4
  45. package/dist/{jsx-runtime-BhiCZOYZ.d.ts → jsx-runtime-DQnpyT_g.d.ts} +2 -2
  46. package/dist/{jsx-runtime-BhiCZOYZ.d.ts.map → jsx-runtime-DQnpyT_g.d.ts.map} +1 -1
  47. package/dist/jsx-runtime.d.ts +1 -1
  48. package/dist/konva.d.ts +3 -3
  49. package/dist/konva.js +1 -1
  50. package/dist/motion.d.ts +39 -16
  51. package/dist/motion.d.ts.map +1 -1
  52. package/dist/motion.js +413 -24
  53. package/dist/motion.js.map +1 -1
  54. package/dist/renderer.d.ts +1 -1
  55. package/dist/renderer.js +1 -1
  56. package/dist/{server-renderer-D-uRg04V.js → server-renderer-D0rsFL_-.js} +2 -2
  57. package/dist/{server-renderer-D-uRg04V.js.map → server-renderer-D0rsFL_-.js.map} +1 -1
  58. package/dist/server.d.ts +1 -1
  59. package/dist/server.js +1 -1
  60. package/dist/size.json +12 -12
  61. package/dist/{src-DWIqXCiz.js → src-Bme1kz2b.js} +2 -2
  62. package/dist/{src-DWIqXCiz.js.map → src-Bme1kz2b.js.map} +1 -1
  63. package/dist/three.d.ts +27 -8
  64. package/dist/three.d.ts.map +1 -1
  65. package/dist/three.js +76 -23
  66. package/dist/three.js.map +1 -1
  67. package/package.json +6 -5
  68. package/src/capabilities.ts +2 -0
  69. package/src/core.ts +26 -12
  70. package/src/index.ts +1 -0
  71. package/src/motion-layout.ts +363 -0
  72. package/src/motion-transition.ts +92 -0
  73. package/src/motion-tween.ts +19 -2
  74. package/src/motion.ts +204 -76
  75. package/src/three.ts +134 -39
  76. package/dist/capabilities-_zOwNJ-2.d.ts.map +0 -1
  77. package/dist/core-DjFJ0aIJ.js.map +0 -1
  78. package/dist/development/core-DxPiKryn.js.map +0 -1
package/README.md CHANGED
@@ -168,6 +168,7 @@ The development plugin keeps SPA and atom.io outside dependency prebundling so r
168
168
  | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
169
169
  | useLoadable(token, fallback?) | Return a tracked accessor for loading, last-observed values, and handled errors. |
170
170
  | useGetter(token) | Return a live accessor for an atom or selector, bound to this instance's store. |
171
+ | useDisposal() | Return atom.io state disposal bound to the current root's store. |
171
172
  | useSetter(token) | Return a stable atom.io writer. |
172
173
  | useTimeline(token) | Return a stable object with getCursor/getLength readers, undo/redo/clear commands, and transaction-group controls. |
173
174
  | useTransaction(token) | Bind an atom.io transaction, preserving its arguments and result. |
@@ -261,7 +262,7 @@ export function InspectCount(): SpaElement {
261
262
 
262
263
  ```
263
264
 
264
- 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.
265
+ For family-member disposal, useDisposal() captures this store and returns a bound disposal command; see [ambient UI state](#ambient-ui-state-and-ownership). Capture the store during component setup or an owned onMount callback, then pass it to other 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.
265
266
 
266
267
  ## Families
267
268
 
@@ -308,6 +309,127 @@ export function FamilyCounter(props: { id: string }): SpaElement {
308
309
 
309
310
  The family and key are captured during setup and stay fixed for that component instance. To switch members, replace the component in a reactive child collection with a new application key. Ref ownership and subscription cleanup follow the member just as they do for individual tokens. useTransaction takes a transaction token; atom.io has no transaction-family token.
310
311
 
312
+ ### Ambient UI state and ownership
313
+
314
+ Ambient state is useful for ephemeral UI flags that several components need to read or change, such as whether a popover is open. Define the family at module scope and give each popover an application identity. Its trigger and panel can bind to the same boolean without passing the value and setter through their parent.
315
+
316
+ This exhibit gives each toolbar its own formatting and keyboard-shortcut help popovers. Hiding formatting help removes its keyed instance and disposes its visibility state. Showing it again starts closed; the shortcuts popover and other toolbars keep their state:
317
+
318
+ ```tsx
319
+ import type { SpaElement } from "@atom.io/spa"
320
+ import {
321
+ onCleanup,
322
+ useDisposal,
323
+ useGetter,
324
+ useId,
325
+ useSetter,
326
+ } from "@atom.io/spa"
327
+ import { atomFamily } from "atom.io"
328
+
329
+ type HelpTopic = `formatting` | `shortcuts`
330
+ type PopoverIdentity = readonly [toolbar: string, topic: HelpTopic]
331
+
332
+ export const popoverOpenAtoms = atomFamily<boolean, PopoverIdentity>({
333
+ key: `popoverOpen`,
334
+ default: false,
335
+ })
336
+ export const formattingHelpVisibleAtoms = atomFamily<boolean, string>({
337
+ key: `formattingHelpVisible`,
338
+ default: true,
339
+ })
340
+
341
+ function HelpTrigger(props: {
342
+ identity: PopoverIdentity
343
+ panelId: string
344
+ }): SpaElement {
345
+ const getOpen = useGetter(popoverOpenAtoms, props.identity)
346
+ const setOpen = useSetter(popoverOpenAtoms, props.identity)
347
+ return (
348
+ <button
349
+ aria-controls={props.panelId}
350
+ aria-expanded={getOpen()}
351
+ aria-haspopup="dialog"
352
+ onClick={() => {
353
+ setOpen((open) => !open)
354
+ }}
355
+ >
356
+ {props.identity[1]} help
357
+ </button>
358
+ )
359
+ }
360
+
361
+ function HelpPanel(props: {
362
+ identity: PopoverIdentity
363
+ panelId: string
364
+ }): SpaElement {
365
+ const getOpen = useGetter(popoverOpenAtoms, props.identity)
366
+ return (
367
+ <div
368
+ id={props.panelId}
369
+ role="dialog"
370
+ aria-label={`${props.identity[1]} help`}
371
+ hidden={!getOpen()}
372
+ >
373
+ {props.identity[1] === `formatting`
374
+ ? `Select text, then choose bold or italic from the toolbar.`
375
+ : `Use Ctrl+Z to undo and Ctrl+Shift+Z to redo.`}
376
+ </div>
377
+ )
378
+ }
379
+
380
+ function HelpPopover(props: { identity: PopoverIdentity }): SpaElement {
381
+ const identity = props.identity
382
+ const panelId = useId()
383
+ const dispose = useDisposal()
384
+ // This owner outlives both consumers of the ambient visibility state.
385
+ onCleanup(() => {
386
+ dispose(popoverOpenAtoms, identity)
387
+ })
388
+ return (
389
+ <section data-help={`${identity[0]}/${identity[1]}`}>
390
+ <HelpTrigger identity={identity} panelId={panelId} />
391
+ <HelpPanel identity={identity} panelId={panelId} />
392
+ </section>
393
+ )
394
+ }
395
+
396
+ export function HelpToolbar(props: { id: string }): SpaElement {
397
+ const toolbar = props.id
398
+ const getFormattingHelpVisible = useGetter(formattingHelpVisibleAtoms, toolbar)
399
+ const setFormattingHelpVisible = useSetter(formattingHelpVisibleAtoms, toolbar)
400
+ const dispose = useDisposal()
401
+ onCleanup(() => {
402
+ dispose(formattingHelpVisibleAtoms, toolbar)
403
+ })
404
+ return (
405
+ <nav aria-label={`${toolbar} help`}>
406
+ {(getFormattingHelpVisible()
407
+ ? ([`formatting`, `shortcuts`] as const)
408
+ : ([`shortcuts`] as const)
409
+ ).map((topic) => (
410
+ <HelpPopover key={topic} identity={[toolbar, topic]} />
411
+ ))}
412
+ <button
413
+ onClick={() => {
414
+ setFormattingHelpVisible((visible) => !visible)
415
+ }}
416
+ >
417
+ {getFormattingHelpVisible() ? `Hide` : `Show`} formatting help
418
+ </button>
419
+ </nav>
420
+ )
421
+ }
422
+
423
+ ```
424
+
425
+ The reconciliation key identifies a component among siblings. The family key identifies application state across the whole store: the tuple includes both the toolbar ID and help topic so separate toolbars do not share visibility by accident. The toolbar ID must be unique within that store. The renderer consumes key; pass the state identity as an ordinary prop.
426
+
427
+ Call useDisposal() without arguments during setup. It captures the current root's store and returns atom.io disposal, accepting either a family and key or an existing member token. Invoke it from an event handler or register it with onCleanup. It works with the implicit store, render/hydrate options.store, and isolated Astro stores without passing a disposal callback through props. Custom stores still need the module-scope definitions installed through Silo.install.
428
+
429
+ HelpPopover owns the visibility member shared by its trigger and panel, so it disposes that member after both consumers are removed. A single consumer must not dispose state that other live consumers still need. Shared session or application state belongs to the owner that knows when every consumer has finished. Standalone atoms persist for their store's lifetime; disposal removes family members, not standalone atoms.
430
+
431
+ Getter and setter bindings capture their family key during setup. Replacing a keyed instance changes its binding; changing an identity prop on an existing instance does not rebind it. Disposing a family member removes its stored value and resources; a later read recreates it from its default. Keep user-authored content in state whose owner matches its intended persistence, rather than treating it like a popover's transient visibility.
432
+
311
433
  ## Async state
312
434
 
313
435
  ```tsx
@@ -424,7 +546,7 @@ The checked Astro fixture demonstrates default/named slots and custom independen
424
546
 
425
547
  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.
426
548
 
427
- The hard budget is under 4,300 bytes of ordinary level-9 gzip for the complete client export surface, including hydration recovery and its production diagnostics. 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.2 kB with gzip; dist/size.json records the exact build measurements. Actual application bundles add atom.io and compiler-generated application code.
549
+ The hard budget is under 4,400 bytes of ordinary level-9 gzip for the complete client export surface, including hydration recovery and its production diagnostics. 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.3 kB with gzip; dist/size.json records the exact build measurements. Actual application bundles add atom.io and compiler-generated application code.
428
550
 
429
551
  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.
430
552
 
@@ -456,11 +578,11 @@ Sizes are exact minified and level-9 gzip JavaScript byte counts. Declarations,
456
578
 
457
579
  | Recipe | Entry | Minified JS | Gzip JS |
458
580
  | -------------------------------- | --------------------------------- | ----------: | -------: |
459
- | Family app with refs and history | `tonnage-recipes/family-app.ts` | 64,161 B | 19,153 B |
460
- | Async interactive client app | `tonnage-recipes/async-app.ts` | 42,586 B | 13,386 B |
461
- | Interactive client app | `tonnage-recipes/client-app.ts` | 42,249 B | 13,236 B |
462
- | Hydrated interactive app | `tonnage-recipes/hydrated-app.ts` | 42,250 B | 13,234 B |
463
- | Interactive Astro island | `tonnage-recipes/astro-island.ts` | 48,765 B | 15,286 B |
581
+ | Family app with refs and history | `tonnage-recipes/family-app.ts` | 64,279 B | 19,205 B |
582
+ | Async interactive client app | `tonnage-recipes/async-app.ts` | 42,722 B | 13,443 B |
583
+ | Interactive client app | `tonnage-recipes/client-app.ts` | 42,385 B | 13,297 B |
584
+ | Hydrated interactive app | `tonnage-recipes/hydrated-app.ts` | 42,386 B | 13,295 B |
585
+ | Interactive Astro island | `tonnage-recipes/astro-island.ts` | 48,901 B | 15,328 B |
464
586
 
465
587
  Report maintained with [tonnage](https://github.com/jeremybanka/tonnage).
466
588
 
@@ -545,8 +667,42 @@ export function Scene(): SpaElement {
545
667
 
546
668
  ```
547
669
 
670
+ Mesh accepts optional constructor args typed from Three.js, including custom BufferGeometry and a Material or material array. Resources supplied in args are borrowed: their application owner disposes them after all consumers finish. JSX geometry/material children and implicit Mesh defaults remain renderer-owned. Constructor args are fixed for the mounted instance; use a new reconciliation key to replace them.
671
+
548
672
  Constructor args are fixed for an instance. To change them, replace the resource with a new key in a reactive child collection. Refs expose native objects. Owned geometries and materials are disposed on removal; textures passed through material properties remain borrowed. Canvas stops drawing and disposes its renderer on removal. The exported threeRenderer renders into a borrowed parent dedicated to its children without creating a WebGL renderer.
549
673
 
674
+ Canvas accepts rendererOptions for constructor-time settings such as alpha and powerPreference, or createRenderer to construct the renderer with the supplied canvas. Both paths are exclusively owned by Canvas: it disposes the renderer on removal or setup failure, and the factory must return a renderer using that canvas. Shared/borrowed renderers are not supported by this boundary; use threeRenderer for a separately owned renderer. Options and the factory are captured at mount; replace the keyed Canvas to reconstruct its context.
675
+
676
+ Use onCreated to configure tone mapping, output color space, scene background, or controls after the scene mounts and sizes, before the first draw. Return a cleanup callback for controls or other acquired resources. Numeric dpr selects a fixed positive ratio; a min/max tuple clamps devicePixelRatio and follows window resize events. The default remains 1. Width and height remain reactive positive CSS-pixel dimensions. Canvas updates its default perspective camera projection; supplied cameras are borrowed and retain their own projection. Use onResize to update an external perspective/orthographic camera explicitly. onFrame and pointer routing always use the current camera prop, with one frame loop using the installed Motion clock or requestAnimationFrame.
677
+
678
+ ```tsx
679
+ import type { SpaElement } from "@atom.io/spa"
680
+ import { BoxGeometry, Canvas, Mesh, MeshBasicMaterial } from "@atom.io/spa/three"
681
+ import { ACESFilmicToneMapping, SRGBColorSpace } from "three"
682
+
683
+ export function BoardCanvas(): SpaElement {
684
+ return (
685
+ <Canvas
686
+ width={800}
687
+ height={600}
688
+ dpr={[1, 2]}
689
+ rendererOptions={{ alpha: true, powerPreference: `high-performance` }}
690
+ onCreated={({ renderer, scene }) => {
691
+ renderer.toneMapping = ACESFilmicToneMapping
692
+ renderer.outputColorSpace = SRGBColorSpace
693
+ scene.background = null
694
+ }}
695
+ >
696
+ <Mesh>
697
+ <BoxGeometry />
698
+ <MeshBasicMaterial color="orange" />
699
+ </Mesh>
700
+ </Canvas>
701
+ )
702
+ }
703
+
704
+ ```
705
+
550
706
  Canvas defaults to a perspective camera at z = 5. Its optional camera prop borrows an external camera; a PerspectiveCamera child does not automatically become active. Width and height update the renderer and default camera. Canvas renders continuously and accepts an onFrame callback with scene, camera, renderer, delta seconds, and timestamp seconds. Controls, asset loading, and drawing on demand are outside this initial API.
551
707
 
552
708
  ### Three.js pointer events
@@ -611,7 +767,7 @@ export function MotionPanel(): SpaElement {
611
767
 
612
768
  ```
613
769
 
614
- 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.
770
+ 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 start at the animate target’s final value. DOM targets accept scalar CSS values and independent transforms, including custom CSS properties. DOM keyframe sequences and property-specific timing are supported as described below. Use motion:layout for layout changes and motion:layoutId for shared element transitions.
615
771
 
616
772
  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.
617
773
 
@@ -656,7 +812,7 @@ export function SpringCube(): SpaElement {
656
812
 
657
813
  ```
658
814
 
659
- 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,300 bytes.
815
+ 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,400 bytes.
660
816
 
661
817
  ### Exit animations and re-entry
662
818
 
@@ -709,7 +865,90 @@ During exit, reactive attributes, child reconciliation, user events, gestures, a
709
865
 
710
866
  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.
711
867
 
712
- 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.
868
+ 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; pop-layout positioning, variants, presence wrappers, and automatic reparenting remain outside its scope.
869
+
870
+ ### Layout and shared identity
871
+
872
+ Register motionCapability from @atom.io/spa/motion once to enable animated properties, exits, HTML layout changes, and shared element transitions. All use the optional Motion peer; the base SPA runtime stays independent of Motion:
873
+
874
+ ```tsx
875
+ import { render } from "@atom.io/spa"
876
+ import { motionCapability } from "@atom.io/spa/motion"
877
+
878
+ import { ReadinessBoard } from "./layout.tsx"
879
+
880
+ const host = document.querySelector(`#app`)!
881
+ const root = render(() => <ReadinessBoard />, host, {
882
+ capabilities: [
883
+ motionCapability({ layoutTransition: { duration: 0.3, ease: `easeInOut` } }),
884
+ ],
885
+ })
886
+
887
+ export const disposeBoard = root.dispose
888
+
889
+ ```
890
+
891
+ ```tsx
892
+ import type { SpaElement } from "@atom.io/spa"
893
+ import { useGetter, useSetter } from "@atom.io/spa"
894
+ import type {} from "@atom.io/spa/motion"
895
+ import { atom } from "atom.io"
896
+
897
+ const players = [`Ada`, `Grace`] as const
898
+ const readyPlayersAtom = atom<string[]>({ key: `readyPlayers`, default: [] })
899
+
900
+ function ReadinessGroup(props: { ready: boolean; match: string }): SpaElement {
901
+ const getReadyPlayers = useGetter(readyPlayersAtom)
902
+ const setReadyPlayers = useSetter(readyPlayersAtom)
903
+ return (
904
+ <section
905
+ motion:layout
906
+ style={`width:${getReadyPlayers().length ? 260 : 180}px;min-height:80px`}
907
+ >
908
+ <h2>{props.ready ? `Ready` : `Waiting`}</h2>
909
+ {players
910
+ .filter((player) => getReadyPlayers().includes(player) === props.ready)
911
+ .map((player) => (
912
+ <button
913
+ key={player}
914
+ motion:layout="position"
915
+ motion:layoutId={player}
916
+ motion:layoutGroup={props.match}
917
+ motion:exit={{ opacity: 0 }}
918
+ motion:transition={{ duration: 0.2 }}
919
+ onClick={() => {
920
+ setReadyPlayers((ready) =>
921
+ ready.includes(player)
922
+ ? ready.filter((name) => name !== player)
923
+ : [...ready, player],
924
+ )
925
+ }}
926
+ >
927
+ {player}
928
+ </button>
929
+ ))}
930
+ </section>
931
+ )
932
+ }
933
+
934
+ export function ReadinessBoard(): SpaElement {
935
+ return (
936
+ <>
937
+ <ReadinessGroup ready={false} match="match-1" />
938
+ <ReadinessGroup ready={true} match="match-1" />
939
+ </>
940
+ )
941
+ }
942
+
943
+ ```
944
+
945
+ motion:layout enables position and size projection; position or size restricts the animated dimensions. motion:layoutId enables layout animation implicitly and carries a visual identity between outgoing/incoming nodes, while reconciliation keys continue to own component instances. Shared identities are isolated by root and by an explicit motion:layoutGroup on each shared node; group is not inherited. Use distinct group values for separate boards in one root. Reusing an ID within a group coordinates a shared transition, with the latest mounted member leading.
946
+
947
+ SPA snapshots registered targets before each synchronous update batch and projects after the DOM commits. Per-target ResizeObserver subscriptions also handle external size changes; no document-wide mutation observer or consumer measurement loop is needed. Mark scrolling layout ancestors with motion:layoutScroll. Nested projections preserve authored transforms and transform origins; Floating UI retains its independent translate positioning. Avoid multiple layout/projection owners or direct writes to a projected element's transform while the capability is active.
948
+
949
+ The default transition is a 0.3-second tween; the capability option layoutTransition sets defaults and motion:layoutTransition replaces them for a target. Use finite duration/delay values or settling spring parameters. Retargeting uses the current projection. Outgoing nodes remain available for shared handoff until replacements mount in the same batch. With Motion exits, layout follows the retained node's lifetime; keyed re-entry resumes the existing instance. Shared identity transfers appearance, not component state or DOM ownership, and nodes are not automatically reparented.
950
+
951
+ Reduced motion follows the user's preference by default; always and never options override it. Enabling reduced motion finishes projections immediately. Removal, fatal errors, and root disposal cancel projection work, disconnect observers/listeners, and restore owned attributes/styles. Server rendering emits no layout attributes or animation work. Layout is limited to owned HTML nodes; scene objects, SVG projection, pop-layout positioning, and cross-document handoff are unsupported.
713
952
 
714
953
  ### Floating overlays with Motion
715
954
 
@@ -811,3 +1050,36 @@ Position updates continue during Motion's retained exits, until physical disposa
811
1050
  ### Renderer extensions
812
1051
 
813
1052
  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.
1053
+
1054
+ ## Motion keyframes and property transitions
1055
+
1056
+ DOM motion targets accept scalar values or keyframe sequences of at least two values. A null first frame starts from the current animated value, which is useful when retargeting an interrupted sequence. Initial DOM targets remain scalar. Three position, rotation, and scale tuples retain their vector meaning; Konva and other scene targets remain scalar. Keyframe sequences use tweens by default; explicit springs support at most two frames. Reduced motion and initial:false resolve to the final frame.
1057
+
1058
+ Transition times are normalized, ordered values from 0 to 1 and must match the keyframe count. ease accepts a single named easing/cubic-bezier tuple or one easing for each interval. Top-level options are overridden by default options, then by properties\[propertyName], with missing fields inherited in that order. This allows independent timing per property and per element. Times and easing lengths must match the effective sequence, including exit targets; invalid combinations report a spa/motion diagnostic. Sequences share the existing interruption, gesture, keyed exit/re-entry, and disposal ownership.
1059
+
1060
+ ```tsx
1061
+ import type { SpaElement } from "@atom.io/spa"
1062
+ import type {} from "@atom.io/spa/motion"
1063
+
1064
+ export function TurnBanner(): SpaElement {
1065
+ return (
1066
+ <aside
1067
+ motion:animate={{
1068
+ x: [`-1500%`, `2%`, `4%`, `1500%`],
1069
+ skewX: [`-50deg`, `-5deg`, `-5deg`, `-50deg`],
1070
+ width: [`20vw`, `90vw`, `90vw`, `10vw`],
1071
+ opacity: [0, 1, 1, 0],
1072
+ }}
1073
+ motion:transition={{
1074
+ duration: 3,
1075
+ times: [0, 0.1, 0.77, 1],
1076
+ ease: [`circOut`, `linear`, `easeIn`],
1077
+ properties: { opacity: { times: [0, 0.2, 0.8, 1], ease: `linear` } },
1078
+ }}
1079
+ >
1080
+ Next turn
1081
+ </aside>
1082
+ )
1083
+ }
1084
+
1085
+ ```
package/README.mdx CHANGED
@@ -1,3 +1,12 @@
1
+ import StateLifetimes from "./exhibits/state-lifetimes.tsx" with {
2
+ type: "code",
3
+ };
4
+ import MotionKeyframes from "./exhibits/motion-keyframes.tsx" with {
5
+ type: "code",
6
+ };
7
+ import ConfigurableCanvas from "./exhibits/configurable-canvas.tsx" with {
8
+ type: "code",
9
+ };
1
10
  import { Tonnage } from "tonnage";
2
11
  import config from "./tonnage.config.ts";
3
12
  import StoreExample from "./exhibits/store.tsx" with { type: "code" };
@@ -26,6 +35,8 @@ import MotionThree from "./exhibits/motion-three.tsx" with { type: "code" };
26
35
  import InstallFloating from "./exhibits/install-floating.sh" with {
27
36
  type: "code",
28
37
  };
38
+ import LayoutExample from "./exhibits/layout.tsx" with { type: "code" };
39
+ import LayoutMain from "./exhibits/layout-main.tsx" with { type: "code" };
29
40
  import FloatingMain from "./exhibits/floating-main.tsx" with { type: "code" };
30
41
  import FloatingExample from "./exhibits/floating.tsx" with { type: "code" };
31
42
 
@@ -91,6 +102,7 @@ The development plugin keeps SPA and atom.io outside dependency prebundling so r
91
102
  | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
92
103
  | useLoadable(token, fallback?) | Return a tracked accessor for loading, last-observed values, and handled errors. |
93
104
  | useGetter(token) | Return a live accessor for an atom or selector, bound to this instance's store. |
105
+ | useDisposal() | Return atom.io state disposal bound to the current root's store. |
94
106
  | useSetter(token) | Return a stable atom.io writer. |
95
107
  | useTimeline(token) | Return a stable object with getCursor/getLength readers, undo/redo/clear commands, and transaction-group controls. |
96
108
  | useTransaction(token) | Bind an atom.io transaction, preserving its arguments and result. |
@@ -118,7 +130,7 @@ useStore returns the current root's atom.io RootStore directly. It is the same o
118
130
 
119
131
  <StoreExample />
120
132
 
121
- 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.
133
+ For family-member disposal, useDisposal() captures this store and returns a bound disposal command; see [ambient UI state](#ambient-ui-state-and-ownership). Capture the store during component setup or an owned onMount callback, then pass it to other 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.
122
134
 
123
135
  ## Families
124
136
 
@@ -128,6 +140,22 @@ useGetter, useSetter, useRef, and useTimeline accept a family token followed by
128
140
 
129
141
  The family and key are captured during setup and stay fixed for that component instance. To switch members, replace the component in a reactive child collection with a new application key. Ref ownership and subscription cleanup follow the member just as they do for individual tokens. useTransaction takes a transaction token; atom.io has no transaction-family token.
130
142
 
143
+ ### Ambient UI state and ownership
144
+
145
+ Ambient state is useful for ephemeral UI flags that several components need to read or change, such as whether a popover is open. Define the family at module scope and give each popover an application identity. Its trigger and panel can bind to the same boolean without passing the value and setter through their parent.
146
+
147
+ This exhibit gives each toolbar its own formatting and keyboard-shortcut help popovers. Hiding formatting help removes its keyed instance and disposes its visibility state. Showing it again starts closed; the shortcuts popover and other toolbars keep their state:
148
+
149
+ <StateLifetimes />
150
+
151
+ The reconciliation key identifies a component among siblings. The family key identifies application state across the whole store: the tuple includes both the toolbar ID and help topic so separate toolbars do not share visibility by accident. The toolbar ID must be unique within that store. The renderer consumes key; pass the state identity as an ordinary prop.
152
+
153
+ Call useDisposal() without arguments during setup. It captures the current root's store and returns atom.io disposal, accepting either a family and key or an existing member token. Invoke it from an event handler or register it with onCleanup. It works with the implicit store, render/hydrate options.store, and isolated Astro stores without passing a disposal callback through props. Custom stores still need the module-scope definitions installed through Silo.install.
154
+
155
+ HelpPopover owns the visibility member shared by its trigger and panel, so it disposes that member after both consumers are removed. A single consumer must not dispose state that other live consumers still need. Shared session or application state belongs to the owner that knows when every consumer has finished. Standalone atoms persist for their store's lifetime; disposal removes family members, not standalone atoms.
156
+
157
+ Getter and setter bindings capture their family key during setup. Replacing a keyed instance changes its binding; changing an identity prop on an existing instance does not rebind it. Disposing a family member removes its stored value and resources; a later read recreates it from its default. Keep user-authored content in state whose owner matches its intended persistence, rather than treating it like a popover's transient visibility.
158
+
131
159
  ## Async state
132
160
 
133
161
  <LoadableExample />
@@ -180,7 +208,7 @@ The checked Astro fixture demonstrates default/named slots and custom independen
180
208
 
181
209
  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.
182
210
 
183
- The hard budget is under 4,300 bytes of ordinary level-9 gzip for the complete client export surface, including hydration recovery and its production diagnostics. 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.2 kB with gzip; dist/size.json records the exact build measurements. Actual application bundles add atom.io and compiler-generated application code.
211
+ The hard budget is under 4,400 bytes of ordinary level-9 gzip for the complete client export surface, including hydration recovery and its production diagnostics. 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.3 kB with gzip; dist/size.json records the exact build measurements. Actual application bundles add atom.io and compiler-generated application code.
184
212
 
185
213
  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.
186
214
 
@@ -216,8 +244,16 @@ Import Canvas, Group, Mesh, PerspectiveCamera, AmbientLight, DirectionalLight, B
216
244
 
217
245
  <ThreeExample />
218
246
 
247
+ Mesh accepts optional constructor args typed from Three.js, including custom BufferGeometry and a Material or material array. Resources supplied in args are borrowed: their application owner disposes them after all consumers finish. JSX geometry/material children and implicit Mesh defaults remain renderer-owned. Constructor args are fixed for the mounted instance; use a new reconciliation key to replace them.
248
+
219
249
  Constructor args are fixed for an instance. To change them, replace the resource with a new key in a reactive child collection. Refs expose native objects. Owned geometries and materials are disposed on removal; textures passed through material properties remain borrowed. Canvas stops drawing and disposes its renderer on removal. The exported threeRenderer renders into a borrowed parent dedicated to its children without creating a WebGL renderer.
220
250
 
251
+ Canvas accepts rendererOptions for constructor-time settings such as alpha and powerPreference, or createRenderer to construct the renderer with the supplied canvas. Both paths are exclusively owned by Canvas: it disposes the renderer on removal or setup failure, and the factory must return a renderer using that canvas. Shared/borrowed renderers are not supported by this boundary; use threeRenderer for a separately owned renderer. Options and the factory are captured at mount; replace the keyed Canvas to reconstruct its context.
252
+
253
+ Use onCreated to configure tone mapping, output color space, scene background, or controls after the scene mounts and sizes, before the first draw. Return a cleanup callback for controls or other acquired resources. Numeric dpr selects a fixed positive ratio; a min/max tuple clamps devicePixelRatio and follows window resize events. The default remains 1. Width and height remain reactive positive CSS-pixel dimensions. Canvas updates its default perspective camera projection; supplied cameras are borrowed and retain their own projection. Use onResize to update an external perspective/orthographic camera explicitly. onFrame and pointer routing always use the current camera prop, with one frame loop using the installed Motion clock or requestAnimationFrame.
254
+
255
+ <ConfigurableCanvas />
256
+
221
257
  Canvas defaults to a perspective camera at z = 5. Its optional camera prop borrows an external camera; a PerspectiveCamera child does not automatically become active. Width and height update the renderer and default camera. Canvas renders continuously and accepts an onFrame callback with scene, camera, renderer, delta seconds, and timestamp seconds. Controls, asset loading, and drawing on demand are outside this initial API.
222
258
 
223
259
  ### Three.js pointer events
@@ -240,7 +276,7 @@ Use motion:initial, motion:animate, motion:exit, motion:transition, motion:while
240
276
 
241
277
  <MotionPanel />
242
278
 
243
- 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.
279
+ 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 start at the animate target’s final value. DOM targets accept scalar CSS values and independent transforms, including custom CSS properties. DOM keyframe sequences and property-specific timing are supported as described below. Use motion:layout for layout changes and motion:layoutId for shared element transitions.
244
280
 
245
281
  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.
246
282
 
@@ -248,7 +284,7 @@ The same attributes animate numeric Konva properties and colors, or Three.js pos
248
284
 
249
285
  <MotionThree />
250
286
 
251
- 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,300 bytes.
287
+ 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,400 bytes.
252
288
 
253
289
  ### Exit animations and re-entry
254
290
 
@@ -268,7 +304,23 @@ During exit, reactive attributes, child reconciliation, user events, gestures, a
268
304
 
269
305
  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.
270
306
 
271
- 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.
307
+ 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; pop-layout positioning, variants, presence wrappers, and automatic reparenting remain outside its scope.
308
+
309
+ ### Layout and shared identity
310
+
311
+ Register motionCapability from @atom.io/spa/motion once to enable animated properties, exits, HTML layout changes, and shared element transitions. All use the optional Motion peer; the base SPA runtime stays independent of Motion:
312
+
313
+ <LayoutMain />
314
+
315
+ <LayoutExample />
316
+
317
+ motion:layout enables position and size projection; position or size restricts the animated dimensions. motion:layoutId enables layout animation implicitly and carries a visual identity between outgoing/incoming nodes, while reconciliation keys continue to own component instances. Shared identities are isolated by root and by an explicit motion:layoutGroup on each shared node; group is not inherited. Use distinct group values for separate boards in one root. Reusing an ID within a group coordinates a shared transition, with the latest mounted member leading.
318
+
319
+ SPA snapshots registered targets before each synchronous update batch and projects after the DOM commits. Per-target ResizeObserver subscriptions also handle external size changes; no document-wide mutation observer or consumer measurement loop is needed. Mark scrolling layout ancestors with motion:layoutScroll. Nested projections preserve authored transforms and transform origins; Floating UI retains its independent translate positioning. Avoid multiple layout/projection owners or direct writes to a projected element's transform while the capability is active.
320
+
321
+ The default transition is a 0.3-second tween; the capability option layoutTransition sets defaults and motion:layoutTransition replaces them for a target. Use finite duration/delay values or settling spring parameters. Retargeting uses the current projection. Outgoing nodes remain available for shared handoff until replacements mount in the same batch. With Motion exits, layout follows the retained node's lifetime; keyed re-entry resumes the existing instance. Shared identity transfers appearance, not component state or DOM ownership, and nodes are not automatically reparented.
322
+
323
+ Reduced motion follows the user's preference by default; always and never options override it. Enabling reduced motion finishes projections immediately. Removal, fatal errors, and root disposal cancel projection work, disconnect observers/listeners, and restore owned attributes/styles. Server rendering emits no layout attributes or animation work. Layout is limited to owned HTML nodes; scene objects, SVG projection, pop-layout positioning, and cross-document handoff are unsupported.
272
324
 
273
325
  ### Floating overlays with Motion
274
326
 
@@ -302,3 +354,11 @@ Position updates continue during Motion's retained exits, until physical disposa
302
354
  ### Renderer extensions
303
355
 
304
356
  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.
357
+
358
+ ## Motion keyframes and property transitions
359
+
360
+ DOM motion targets accept scalar values or keyframe sequences of at least two values. A null first frame starts from the current animated value, which is useful when retargeting an interrupted sequence. Initial DOM targets remain scalar. Three position, rotation, and scale tuples retain their vector meaning; Konva and other scene targets remain scalar. Keyframe sequences use tweens by default; explicit springs support at most two frames. Reduced motion and initial:false resolve to the final frame.
361
+
362
+ Transition times are normalized, ordered values from 0 to 1 and must match the keyframe count. ease accepts a single named easing/cubic-bezier tuple or one easing for each interval. Top-level options are overridden by default options, then by properties[propertyName], with missing fields inherited in that order. This allows independent timing per property and per element. Times and easing lengths must match the effective sequence, including exit targets; invalid combinations report a spa/motion diagnostic. Sequences share the existing interruption, gesture, keyed exit/re-entry, and disposal ownership.
363
+
364
+ <MotionKeyframes />
@@ -1,4 +1,4 @@
1
- import { t as AstroApplicationContext } from "./astro-shared-B9wvGIkk.js";
1
+ import { t as AstroApplicationContext } from "./astro-shared-DZp1x8RQ.js";
2
2
  type Lifetime = {
3
3
  signal: AbortSignal;
4
4
  onCleanup(cleanup: () => void): () => void;
@@ -1,4 +1,4 @@
1
- import { a as Island, i as AstroStorePreparation } from "./astro-shared-B9wvGIkk.js";
1
+ import { a as Island, i as AstroStorePreparation } from "./astro-shared-DZp1x8RQ.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: {
@@ -1,8 +1,8 @@
1
1
  import { browserApplication } from "./astro-application.js";
2
2
  import { n as failPreparation, r as storeContext } from "./astro-context-OdlexHR4.js";
3
3
  import { n as islandStore, t as island } from "./astro-shared-83hxw7-M.js";
4
- import { c as onCleanup, m as useGetter } from "./core-DjFJ0aIJ.js";
5
- import { n as render, t as hydrate } from "./dom-BrPrxO97.js";
4
+ import { c as onCleanup, h as useGetter } from "./core-B4rJ0xdc.js";
5
+ import { n as render, t as hydrate } from "./dom-D8g3roX9.js";
6
6
  import { IMPLICIT, createRegularAtomFamily, disposeFromStore, findInStore, getFromStore, setIntoStore } from "atom.io/internal";
7
7
  // src/astro-client.ts
8
8
  const roots = /* @__PURE__ */ new WeakMap();
@@ -1,4 +1,4 @@
1
- import { a as Island } from "./astro-shared-B9wvGIkk.js";
1
+ import { a as Island } from "./astro-shared-DZp1x8RQ.js";
2
2
  declare const _default: (element: HTMLElement) => (component: Island, props: {
3
3
  [x: string]: any;
4
4
  }, slots: {
@@ -1,7 +1,7 @@
1
1
  import { n as failPreparation, r as storeContext } from "./astro-context-OdlexHR4.js";
2
2
  import { t as requestApplication } from "./astro-request-DRKvDjsO.js";
3
3
  import { n as islandStore, t as island } from "./astro-shared-83hxw7-M.js";
4
- import { t as renderToStringWithReads } from "./server-renderer-D-uRg04V.js";
4
+ import { t as renderToStringWithReads } from "./server-renderer-D0rsFL_-.js";
5
5
  // src/astro-server.ts
6
6
  const createRenderer = (awaitState = false) => ({
7
7
  name: `spa`,
@@ -1,4 +1,4 @@
1
- import { o as Component, t as Capability } from "./capabilities-_zOwNJ-2.js";
1
+ import { o as Component, t as Capability } from "./capabilities-DNcnGRv_.js";
2
2
  import { RootStore } from "atom.io/internal";
3
3
  interface AstroApplicationContext {
4
4
  /** Whether the application still represents its initial server snapshot. */
@@ -30,4 +30,4 @@ type Island<P = any> = Component<P> & {
30
30
  prepareStore?: AstroStorePreparation<P>;
31
31
  };
32
32
  export { Island as a, AstroStorePreparation as i, AstroStoreContext as n, AstroStoreFactory as r, AstroApplicationContext as t };
33
- //# sourceMappingURL=astro-shared-B9wvGIkk.d.ts.map
33
+ //# sourceMappingURL=astro-shared-DZp1x8RQ.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"astro-shared-B9wvGIkk.d.ts","names":[],"sources":["../src/astro-shared.ts"],"mappings":";;UAOiB;;WAEP;WACA,QAAQ;EACjB,UAAU;;EAEV,IAAI,GAAG,cAAc,kBAAkB,IAAI;;UAE3B;;EAEhB,aAAa;;EAEb,SAAS;;EAET,QAAQ;;EAER,UAAU;;KAEC,kBAAkB,IAAI,wBACjC,OAAO,GACP,SAAS,sBACL,YAAY,QAAQ;KACb,sBAAsB,IAAI,wBACrC,OAAO,WACP,OAAO,GACP,SAAS,6BACE;KACA,OAAO,WAAW,UAAU;EACvC;;EAEA,wBAAwB;;EAExB;EACA,cAAc,kBAAkB;EAChC,eAAe,sBAAsB"}
1
+ {"version":3,"file":"astro-shared-DZp1x8RQ.d.ts","names":[],"sources":["../src/astro-shared.ts"],"mappings":";;UAOiB;;WAEP;WACA,QAAQ;EACjB,UAAU;;EAEV,IAAI,GAAG,cAAc,kBAAkB,IAAI;;UAE3B;;EAEhB,aAAa;;EAEb,SAAS;;EAET,QAAQ;;EAER,UAAU;;KAEC,kBAAkB,IAAI,wBACjC,OAAO,GACP,SAAS,sBACL,YAAY,QAAQ;KACb,sBAAsB,IAAI,wBACrC,OAAO,WACP,OAAO,GACP,SAAS,6BACE;KACA,OAAO,WAAW,UAAU;EACvC;;EAEA,wBAAwB;;EAExB;EACA,cAAc,kBAAkB;EAChC,eAAe,sBAAsB"}
package/dist/astro.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { SpaPluginOptions } from "./vite.js";
2
- import { a as Island, i as AstroStorePreparation, n as AstroStoreContext, r as AstroStoreFactory, t as AstroApplicationContext } from "./astro-shared-B9wvGIkk.js";
2
+ import { a as Island, i as AstroStorePreparation, n as AstroStoreContext, r as AstroStoreFactory, t as AstroApplicationContext } from "./astro-shared-DZp1x8RQ.js";
3
3
  import { AstroIntegration } from "astro";
4
4
  export default function integration(options?: SpaPluginOptions): AstroIntegration;
5
5
  export type { AstroApplicationContext, AstroStoreContext, AstroStoreFactory, AstroStorePreparation, Island };
@@ -1,5 +1,5 @@
1
1
  import { RootStore } from "atom.io/internal";
2
- import { ReadableFamilyToken, ReadableToken, RegularAtomFamilyToken, RegularAtomToken, Setter, TimelineFamilyToken, TimelineManageable, TimelineToken, TransactionToken, ViewOf, WritableFamilyToken, WritableToken } from "atom.io";
2
+ import { ReadableFamilyToken, ReadableToken, RegularAtomFamilyToken, RegularAtomToken, Setter, TimelineFamilyToken, TimelineManageable, TimelineToken, TransactionToken, ViewOf, WritableFamilyToken, WritableToken, disposeState } from "atom.io";
3
3
  import { Canonical } from "atom.io/foundations/canonical";
4
4
  interface ExitHandle {
5
5
  finished: Promise<void>;
@@ -71,6 +71,8 @@ interface Root extends Scope {
71
71
  }
72
72
  /** Return the atom.io store selected by the current root. */
73
73
  declare function useStore(): RootStore;
74
+ /** Return atom.io disposal bound to the current root's store. */
75
+ declare function useDisposal(): typeof disposeState;
74
76
  declare function onCleanup(cleanup: Cleanup): void;
75
77
  declare function onMount(run: Cleanup): void;
76
78
  declare function useId(): string;
@@ -113,10 +115,12 @@ interface CapabilityBinding {
113
115
  }
114
116
  interface Capability {
115
117
  namespace: string;
118
+ /** Prepare a synchronous update batch and return its commit callback. */
119
+ beforeUpdate?(root: Root): Cleanup;
116
120
  presence?(root: Root): PresenceCoordinator;
117
121
  scheduleFrame?(callback: (time: number) => void): Cleanup;
118
122
  /** SPA supplies ownership for integrations that measure after mount or report async errors. */
119
123
  attach(target: CapabilityTarget, scope?: Scope): CapabilityBinding;
120
124
  }
121
- export { useTimeline as _, Children as a, SpaElement as c, onMount as d, useGetter as f, useStore as g, useSetter as h, Accessor as i, TimelineControls as l, useRef as m, CapabilityBinding as n, Component as o, useId as p, CapabilityTarget as r, RootOptions as s, Capability as t, onCleanup as u, useTransaction as v };
122
- //# sourceMappingURL=capabilities-_zOwNJ-2.d.ts.map
125
+ export { useStore as _, Children as a, SpaElement as c, onMount as d, useDisposal as f, useSetter as g, useRef as h, Accessor as i, TimelineControls as l, useId as m, CapabilityBinding as n, Component as o, useGetter as p, CapabilityTarget as r, RootOptions as s, Capability as t, onCleanup as u, useTimeline as v, useTransaction as y };
126
+ //# sourceMappingURL=capabilities-DNcnGRv_.d.ts.map