@atom.io/spa 0.0.4 → 0.0.5

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 (117) hide show
  1. package/README.md +125 -105
  2. package/README.mdx +51 -20
  3. package/dist/astro-application.d.ts +1 -1
  4. package/dist/astro-client.d.ts +3 -2
  5. package/dist/astro-client.d.ts.map +1 -1
  6. package/dist/astro-client.js +9 -8
  7. package/dist/astro-client.js.map +1 -1
  8. package/dist/astro-resumability-client.d.ts +10 -0
  9. package/dist/astro-resumability-client.d.ts.map +1 -0
  10. package/dist/astro-resumability-client.js +29 -0
  11. package/dist/astro-resumability-client.js.map +1 -0
  12. package/dist/astro-resumability-server.d.ts +3 -0
  13. package/dist/astro-resumability-server.d.ts.map +1 -0
  14. package/dist/astro-resumability-server.js +7 -0
  15. package/dist/astro-resumability-server.js.map +1 -0
  16. package/dist/astro-server.d.ts +3 -2
  17. package/dist/astro-server.d.ts.map +1 -1
  18. package/dist/astro-server.js +28 -9
  19. package/dist/astro-server.js.map +1 -1
  20. package/dist/{astro-shared-BT45auwR.js → astro-shared-83hxw7-M.js} +4 -2
  21. package/dist/astro-shared-83hxw7-M.js.map +1 -0
  22. package/dist/{astro-shared-CYSRrRr8.d.ts → astro-shared-DHIpjNIG.d.ts} +2 -2
  23. package/dist/{astro-shared-CYSRrRr8.d.ts.map → astro-shared-DHIpjNIG.d.ts.map} +1 -1
  24. package/dist/astro.d.ts +1 -1
  25. package/dist/astro.js +5 -7
  26. package/dist/astro.js.map +1 -1
  27. package/dist/{capabilities-D3HObAIy.d.ts → capabilities-BCtBG-ni.d.ts} +8 -5
  28. package/dist/capabilities-BCtBG-ni.d.ts.map +1 -0
  29. package/dist/client.min.js +1 -1
  30. package/dist/{core-Bl1Ec1hY.js → core-DjFJ0aIJ.js} +4 -2
  31. package/dist/core-DjFJ0aIJ.js.map +1 -0
  32. package/dist/development/astro-client.js +9 -8
  33. package/dist/development/astro-client.js.map +1 -1
  34. package/dist/development/astro-resumability-client.js +29 -0
  35. package/dist/development/astro-resumability-client.js.map +1 -0
  36. package/dist/development/astro-resumability-server.js +7 -0
  37. package/dist/development/astro-resumability-server.js.map +1 -0
  38. package/dist/development/astro-server.js +28 -9
  39. package/dist/development/astro-server.js.map +1 -1
  40. package/dist/development/{astro-shared-BT45auwR.js → astro-shared-83hxw7-M.js} +4 -2
  41. package/dist/development/astro-shared-83hxw7-M.js.map +1 -0
  42. package/dist/development/astro.js +5 -7
  43. package/dist/development/astro.js.map +1 -1
  44. package/dist/development/{core-DZFaOyTO.js → core-DxPiKryn.js} +4 -2
  45. package/dist/development/core-DxPiKryn.js.map +1 -0
  46. package/dist/development/{dom-Dwa2SFTn.js → dom-BytVV6Rp.js} +44 -12
  47. package/dist/development/dom-BytVV6Rp.js.map +1 -0
  48. package/dist/development/index.js +3 -3
  49. package/dist/development/jsx-runtime.js.map +1 -1
  50. package/dist/development/konva.js +1 -1
  51. package/dist/development/konva.js.map +1 -1
  52. package/dist/development/motion.js +1 -1
  53. package/dist/development/renderer.js +1 -1
  54. package/dist/development/renderer.js.map +1 -1
  55. package/dist/development/server-renderer-CUQXh9oF.js +90 -0
  56. package/dist/development/server-renderer-CUQXh9oF.js.map +1 -0
  57. package/dist/development/server.js +2 -83
  58. package/dist/development/server.js.map +1 -1
  59. package/dist/{src-DvkUMuNW.js → development/src-WSHJxR9b.js} +2 -2
  60. package/dist/development/{src-BUtG4BgX.js.map → src-WSHJxR9b.js.map} +1 -1
  61. package/dist/development/three.js +1 -1
  62. package/dist/development/three.js.map +1 -1
  63. package/dist/{dom-Cfj3GtQK.js → dom-B5OxgHkr.js} +44 -12
  64. package/dist/dom-B5OxgHkr.js.map +1 -0
  65. package/dist/{index-YRZ79lN5.d.ts → index-DufwkB6W.d.ts} +5 -5
  66. package/dist/{index-YRZ79lN5.d.ts.map → index-DufwkB6W.d.ts.map} +1 -1
  67. package/dist/index.d.ts +4 -4
  68. package/dist/index.js +3 -3
  69. package/dist/{jsx-runtime-Q-UBV97Y.d.ts → jsx-runtime-DMDVr7A5.d.ts} +7 -7
  70. package/dist/{jsx-runtime-Q-UBV97Y.d.ts.map → jsx-runtime-DMDVr7A5.d.ts.map} +1 -1
  71. package/dist/jsx-runtime.d.ts +1 -1
  72. package/dist/jsx-runtime.js.map +1 -1
  73. package/dist/konva.d.ts +16 -16
  74. package/dist/konva.js +1 -1
  75. package/dist/konva.js.map +1 -1
  76. package/dist/motion.d.ts +1 -1
  77. package/dist/motion.js +1 -1
  78. package/dist/renderer.d.ts +4 -4
  79. package/dist/renderer.d.ts.map +1 -1
  80. package/dist/renderer.js +1 -1
  81. package/dist/renderer.js.map +1 -1
  82. package/dist/server-renderer-DcU55e6s.js +90 -0
  83. package/dist/server-renderer-DcU55e6s.js.map +1 -0
  84. package/dist/server.d.ts +2 -2
  85. package/dist/server.d.ts.map +1 -1
  86. package/dist/server.js +2 -83
  87. package/dist/server.js.map +1 -1
  88. package/dist/size.json +16 -16
  89. package/dist/{development/src-BUtG4BgX.js → src-DWIqXCiz.js} +2 -2
  90. package/dist/{src-DvkUMuNW.js.map → src-DWIqXCiz.js.map} +1 -1
  91. package/dist/three.d.ts +17 -17
  92. package/dist/three.js +1 -1
  93. package/dist/three.js.map +1 -1
  94. package/package.json +27 -11
  95. package/src/astro-client.ts +17 -4
  96. package/src/astro-resumability-client.ts +40 -0
  97. package/src/astro-resumability-server.ts +7 -0
  98. package/src/astro-server.ts +58 -19
  99. package/src/astro-shared.ts +5 -2
  100. package/src/astro.ts +11 -3
  101. package/src/core.ts +15 -10
  102. package/src/dom.ts +73 -39
  103. package/src/index.ts +2 -2
  104. package/src/jsx-runtime.ts +7 -6
  105. package/src/jsx-types.d.ts +2 -2
  106. package/src/konva.ts +3 -3
  107. package/src/renderer.ts +24 -18
  108. package/src/server-renderer.ts +162 -0
  109. package/src/server.ts +4 -153
  110. package/src/three.ts +4 -4
  111. package/dist/astro-shared-BT45auwR.js.map +0 -1
  112. package/dist/capabilities-D3HObAIy.d.ts.map +0 -1
  113. package/dist/core-Bl1Ec1hY.js.map +0 -1
  114. package/dist/development/astro-shared-BT45auwR.js.map +0 -1
  115. package/dist/development/core-DZFaOyTO.js.map +0 -1
  116. package/dist/development/dom-Dwa2SFTn.js.map +0 -1
  117. package/dist/dom-Cfj3GtQK.js.map +0 -1
package/README.md CHANGED
@@ -6,32 +6,38 @@ An experimental JSX framework whose state engine is atom.io. Components run once
6
6
 
7
7
  The npm package is named @atom.io/spa. Its browser runtime, Vite compiler, server renderer, and Astro integration are implemented here. It has no independent state primitive, effect API, React hook dispatcher, or compatibility layer.
8
8
 
9
+ ## Start with the Astro template
10
+
11
+ Use the [SPA + Astro SSR template](https://github.com/jeremybanka/atom.io/tree/main/templates/spa-astro-ssr) for a ready-to-run application with Astro islands, resumable initial data, SQLite, and tRPC:
12
+
13
+ ```sh
14
+ npm create atom.io@latest my-spa -- --templateName=spa-astro-ssr --packageManager=npm
15
+ cd my-spa
16
+ npm run dev
17
+
18
+ ```
19
+
20
+ For manual setup, see the [Astro](https://atom.io.fyi/docs/spa/astro) and [Vite](https://atom.io.fyi/docs/spa/vite) integration guides on atom.io.fyi.
21
+
9
22
  ## A point, not two signals
10
23
 
11
24
  ```tsx
12
- import type { VNode } from "@atom.io/spa"
13
- import { useGetter, useId, useRef, useSetter } from "@atom.io/spa"
25
+ import type { SpaElement } from "@atom.io/spa"
26
+ import { useGetter, useSetter } from "@atom.io/spa"
14
27
  import { atom } from "atom.io"
15
28
 
16
29
  const pointAtom = atom<{ x: number; y: number }>({
17
30
  key: `point`,
18
31
  default: { x: 20, y: 20 },
19
32
  })
20
- const circleAtom = atom<SVGCircleElement | null>({
21
- key: `circle`,
22
- default: null,
23
- })
24
-
25
- export function PointEditor(): VNode {
33
+ export function PointEditor(): SpaElement {
26
34
  const getPoint = useGetter(pointAtom)
27
35
  const setPoint = useSetter(pointAtom)
28
- const circle = useRef(circleAtom)
29
- const id = useId()
30
36
  return (
31
- <section aria-labelledby={id}>
32
- <h2 id={id}>Point</h2>
37
+ <section>
38
+ <h2>Point</h2>
33
39
  <svg viewBox="0 0 100 100">
34
- <circle ref={circle} cx={getPoint().x} cy={getPoint().y} r="3" />
40
+ <circle cx={getPoint().x} cy={getPoint().y} r="3" />
35
41
  </svg>
36
42
  <output>
37
43
  {getPoint().x}, {getPoint().y}
@@ -51,6 +57,58 @@ export function PointEditor(): VNode {
51
57
 
52
58
  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
59
 
60
+ ## Astro
61
+
62
+ Register the Astro integration, which compiles .tsx and .jsx components by default:
63
+
64
+ ```ts
65
+ import spa from "@atom.io/spa/astro"
66
+ import { defineConfig } from "astro/config"
67
+
68
+ export default defineConfig({ integrations: [spa()] })
69
+
70
+ ```
71
+
72
+ Create a counter component:
73
+
74
+ ```tsx
75
+ import type { SpaElement } from "@atom.io/spa"
76
+ import { useGetter, useSetter } from "@atom.io/spa"
77
+ import { atom } from "atom.io"
78
+
79
+ const countAtom = atom<number>({ key: `count`, default: 0 })
80
+
81
+ export default function Counter(): SpaElement {
82
+ const getCount = useGetter(countAtom)
83
+ const setCount = useSetter(countAtom)
84
+ return (
85
+ <button
86
+ onClick={() => {
87
+ setCount((count) => count + 1)
88
+ }}
89
+ >
90
+ Count: {getCount()}
91
+ </button>
92
+ )
93
+ }
94
+
95
+ ```
96
+
97
+ Import it into an Astro page and use client:load to make it interactive. Astro handles server rendering and browser hydration:
98
+
99
+ ```astro
100
+ ---
101
+ import Counter from "./Counter.tsx"
102
+ ---
103
+ <html lang="en">
104
+ <head><title>SPA counter</title></head>
105
+ <body>
106
+ <Counter client:load />
107
+ </body>
108
+ </html>
109
+
110
+ ```
111
+
54
112
  ## Vite
55
113
 
56
114
  Add @atom.io/spa and atom.io to the application's dependencies. The spa plugin is required: the ordinary TypeScript JSX transform cannot preserve live expressions. It compiles expressions into lazy child computations and property getters; it also preserves spread precedence and live component props.
@@ -77,20 +135,32 @@ export default defineConfig({ plugins: [spa()] })
77
135
 
78
136
  ```
79
137
 
138
+ Add a host element in index.html, then mount the same counter from main.tsx:
139
+
140
+ ```html
141
+ <!doctype html>
142
+ <html lang="en">
143
+ <head><title>SPA counter</title></head>
144
+ <body>
145
+ <div id="app"></div>
146
+ <script type="module" src="/main.tsx"></script>
147
+ </body>
148
+ </html>
149
+
150
+ ```
151
+
80
152
  ```tsx
81
153
  import { render } from "@atom.io/spa"
82
154
 
83
- import { PointEditor } from "./point.tsx"
155
+ import Counter from "./Counter.tsx"
84
156
 
85
- const root = render(() => <PointEditor />, document.getElementById(`app`)!)
86
- // Call root.dispose() when the application shell removes this root.
87
- import.meta.hot?.dispose(root.dispose)
157
+ render(() => <Counter />, document.getElementById(`app`)!)
88
158
 
89
159
  ```
90
160
 
91
161
  The development plugin keeps SPA and atom.io outside dependency prebundling so renderer entrypoints, component hooks, and stores share one runtime, including Astro adapter environments. It uses full page reloads. Components and render computations are synchronous. Modern browsers with ES2022 and DOM Range support are the target.
92
162
 
93
- ## Component API
163
+ ## Hooks
94
164
 
95
165
  | API | Contract |
96
166
  | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
@@ -110,7 +180,7 @@ Call setup helpers synchronously during component setup or owned mount callbacks
110
180
  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
181
 
112
182
  ```tsx
113
- import type { VNode } from "@atom.io/spa"
183
+ import type { SpaElement } from "@atom.io/spa"
114
184
  import { useGetter, useTimeline, useTransaction } from "@atom.io/spa"
115
185
  import { atom, timeline, transaction } from "atom.io"
116
186
 
@@ -123,7 +193,7 @@ const incrementTransaction = transaction<() => void>({
123
193
  },
124
194
  })
125
195
 
126
- export function TimelineExample(): VNode {
196
+ export function TimelineExample(): SpaElement {
127
197
  const getCount = useGetter(countAtom)
128
198
  const increment = useTransaction(incrementTransaction)
129
199
  const history = useTimeline(historyTimeline)
@@ -167,14 +237,14 @@ HTML and SVG tags have element-specific attribute, event, and ref types. Event h
167
237
  useStore returns the current root's atom.io RootStore directly. It is the same object supplied to render or hydrate, the selected Astro island store, or the implicit atom.io store when no store was supplied. Server rendering exposes the store selected for that render.
168
238
 
169
239
  ```tsx
170
- import type { VNode } from "@atom.io/spa"
240
+ import type { SpaElement } from "@atom.io/spa"
171
241
  import { useStore } from "@atom.io/spa"
172
242
  import { atom } from "atom.io"
173
243
  import { getFromStore } from "atom.io/internal"
174
244
 
175
245
  const countAtom = atom<number>({ key: `count`, default: 0 })
176
246
 
177
- export function InspectCount(): VNode {
247
+ export function InspectCount(): SpaElement {
178
248
  const store = useStore()
179
249
  return (
180
250
  <button
@@ -196,7 +266,7 @@ Capture the store during component setup or an owned onMount callback, then pass
196
266
  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.
197
267
 
198
268
  ```tsx
199
- import type { VNode } from "@atom.io/spa"
269
+ import type { SpaElement } from "@atom.io/spa"
200
270
  import { useGetter, useRef, useSetter, useTimeline } from "@atom.io/spa"
201
271
  import { atomFamily, scopeFamily, timelineFamily } from "atom.io"
202
272
 
@@ -210,7 +280,7 @@ const historyTimelines = timelineFamily<string>({
210
280
  scope: [scopeFamily(countAtoms, { timelineKey: (id) => id })],
211
281
  })
212
282
 
213
- export function FamilyCounter(props: { id: string }): VNode {
283
+ export function FamilyCounter(props: { id: string }): SpaElement {
214
284
  const getCount = useGetter(countAtoms, props.id)
215
285
  const setCount = useSetter(countAtoms, props.id)
216
286
  const ref = useRef(buttonAtoms, props.id)
@@ -239,7 +309,7 @@ The family and key are captured during setup and stay fixed for that component i
239
309
  ## Async state
240
310
 
241
311
  ```tsx
242
- import type { VNode } from "@atom.io/spa"
312
+ import type { SpaElement } from "@atom.io/spa"
243
313
  import { useLoadable, useSetter } from "@atom.io/spa"
244
314
  import type { Loadable } from "atom.io"
245
315
  import { atom } from "atom.io"
@@ -250,7 +320,7 @@ const greetingAtom = atom<Loadable<string>, Error>({
250
320
  catch: [Error],
251
321
  })
252
322
 
253
- export function Greeting(): VNode {
323
+ export function Greeting(): SpaElement {
254
324
  const greeting = useLoadable(greetingAtom, `Loading…`)
255
325
  const setGreeting = useSetter(greetingAtom)
256
326
  return (
@@ -280,36 +350,32 @@ Atom.io owns promise settlement and subscriptions. SPA adds no fetching, retries
280
350
 
281
351
  The client exports render and hydrate. Both accept a setup callback, a host Element, and optional store, idPrefix, and onError options, and return dispose and flush methods. Updates coalesce in a microtask; flush drains them synchronously. Dispose is idempotent and removes only owned nodes. Cleanup continues after individual cleanup failures and aggregates errors. A failed computation disposes its root; asynchronous update failures reach onError, while explicit flush failures throw.
282
352
 
283
- The separate server entrypoint exports renderToString with the same setup callback and store/ID options. Supply a request-specific store for SSR. Server rendering retains no subscriptions and runs owner cleanup. Hydration reuses matching server nodes and IDs, attaches events, and recreates subscriptions. It requires the same initial state, component structure, and valid HTML on both sides; mismatches throw rather than silently remounting. Use explicit tbody elements in tables. Controlled form properties are applied during hydration.
353
+ The separate server entrypoint exports renderToString with the same setup callback and store/ID options. Supply a request-specific store for SSR. Server rendering retains no subscriptions and runs owner cleanup. Hydration reuses matching server nodes and IDs, attaches events, and recreates subscriptions. Match initial state, component structure, and valid HTML on both sides. A hydration mismatch produces one human-readable console warning per root in development and production, identifying the host and expected/found nodes. SPA repairs mismatched nodes, inserts missing nodes, and removes unexpected leftovers during the same hydration pass. Component setup and mount hooks run once, subscriptions remain active, and matching nodes are reused. Replaced nodes can lose focus, selection, or unsaved browser input; unaffected roots continue running. An explicit client idPrefix takes precedence when repairing mismatched root markers. Use explicit tbody elements in tables. Controlled form properties are applied during hydration.
284
354
 
285
- The production build omits development diagnostics and invalid-input checks; the development export condition enables them. Pure render computations must not write state. Promise children, async components, portals, suspense, error boundaries, style objects, and automatic token-as-child bindings are outside this first implementation. Applications handle asynchronous data through atom.io state and synchronous conditional JSX.
355
+ The production build omits development-only diagnostics and invalid-input checks; the development export condition enables them. Hydration recovery warnings remain available in all builds. Pure render computations must not write state. Promise children, async components, portals, suspense, error boundaries, style objects, and automatic token-as-child bindings are outside this first implementation. Applications handle asynchronous data through atom.io state and synchronous conditional JSX.
286
356
 
287
- ## Astro
357
+ ## Astro state and data
288
358
 
289
- The integration transforms .spa.tsx and .spa.jsx files by default, so another JSX renderer can coexist. Configure include to change this filter. Top-level functions containing JSX are branded by the compiler for renderer detection.
359
+ The integration compiles .tsx and .jsx files by default. Use the include option to limit compilation to SPA component directories when another JSX renderer is present. Top-level functions containing JSX are branded by the compiler for renderer detection.
290
360
 
291
- ```ts
292
- import spa from "@atom.io/spa/astro"
293
- import { defineConfig } from "astro/config"
294
-
295
- export default defineConfig({ integrations: [spa()] })
361
+ Default islands share the normal implicit atom.io store in the browser. Module-scoped tokens, SPA hooks, and ordinary getState/setState calls all address the same graph. SSR shares a separate store within each request; concurrent requests never share values. Definitions imported after an earlier island started are installed into that request's store before the next island prepares. Server reads and writes must use the selected store (through SPA hooks or store-aware atom.io operations); free getState/setState calls still target the process-global implicit store.
296
362
 
297
- ```
363
+ The integration starts observing browser state before island preparation. Untouched initial islands hydrate their matching server DOM. Once application state changes or a shared client:only island starts, delayed islands mount fresh against the live graph. Astro ClientRouter navigation also makes newly introduced islands mount fresh, preserving existing browser values instead of replaying the incoming server snapshot. Mounted and persisted roots keep their subscriptions and DOM. This decision is conservative across the application: even an unrelated state change disables hydration for later roots. Ordinary defaults should still produce matching initial values. DOM mismatch recovery keeps a view interactive; it does not reconstruct missing server data or resolve nondeterministic application logic.
298
364
 
299
- Default islands share the normal implicit atom.io store in the browser. Module-scoped tokens, SPA hooks, and ordinary getState/setState calls all address the same graph. SSR shares a separate store within each request; concurrent requests never share values. Definitions imported after an earlier island started are installed into that request's store before the next island prepares. Server reads and writes must use the selected store (through SPA hooks or store-aware atom.io operations); free getState/setState calls still target the process-global implicit store.
365
+ With resumability/astro installed alongside SPA, resumability owns Astro's request collection, page sidecars, and browser scope. SPA awaits async state used by JSX and uses the host's renderer adapter to attach seeds to islands. Ordinary atom defaults use the host without changing the store's evaluator; private stores bind a separate scope so lazy work ends with the island. Define resumable defaults at module scope and render ordinary Astro islands. Components need no Resumption wrapper, prepareStore callback, or preload list. The same host supports plain Astro constants without atom.io. See the [resumability guide](https://atom.io.fyi/docs/spa/astro#resumability) and the inventory starter for a complete example. Resumability is an optional peer, loaded only by this adapter.
300
366
 
301
- The integration starts observing browser state before island preparation. Untouched initial islands hydrate their matching server DOM. Once application state changes or a shared client:only island starts, delayed islands mount fresh against the live graph. Astro ClientRouter navigation also makes newly introduced islands mount fresh, preserving existing browser values instead of replaying the incoming server snapshot. Mounted and persisted roots keep their subscriptions and DOM. This decision is conservative across the application: even an unrelated state change disables hydration for later roots. Ordinary defaults must still produce matching initial values; SPA does not serialize stores or repair nondeterministic renders.
367
+ Server-rendered views record the state tokens they read so the browser can check readiness before hydration. If an ordinary async default is still pending without a synchronous seed, SPA mounts a fresh view with its loading state; seeded values continue to hydrate existing DOM. This also handles cached server reads and mixed ordinary/resumable state. Private server preparation and rendering are cancelled with their request, releasing cleanup resources even when a producer ignores its abort signal.
302
368
 
303
369
  Set a component's isolate property to true to opt into a private store copied from registered definitions. An optional createStore(props, context) factory supplies a custom RootStore or promise and retains a private preparation lifetime. Custom factories that return the same store are responsible for coordinating their hydration and cleanup. Keep atom definitions at module scope in either mode.
304
370
 
305
- An optional prepareStore(store, props, context) callback initializes the selected store and may return a promise. SPA awaits it before component setup on the server and browser. Existing one-argument synchronous factories still work. Use serialized props or an independent transport such as resumability for server-produced initial data. Shared preparation must be safe to call for multiple islands; use context.application.get(key, initialize) to create an application resource once.
371
+ An optional prepareStore(store, props, context) callback initializes the selected store and may return a promise. SPA awaits it before component setup on the server and browser. Existing one-argument synchronous factories still work. Shared preparation must be safe to call for multiple islands; use context.application.get(key, initialize) to create an application resource once.
306
372
 
307
373
  The context provides element (the browser astro-island host, undefined on the server), signal, and onCleanup for the individual island. Its application provides get, signal, onCleanup, and canResume for the shared lifetime. Browser application resources survive island removal and ClientRouter navigation; they end on a full page exit, with back/forward-cache suspension preserved. SSR application resources end after the response stream finishes or is cancelled. Private islands' application resources end with the island. Use application cleanup and cancellation for shared fetches or resumption scopes; use the outer context for resources owned by one island.
308
374
 
309
375
  Register cleanup as resources are acquired, before awaiting work that might fail. Cleanup callbacks run in reverse order and all run even if one throws; callbacks registered after cancellation run immediately. Cancelling an island stops its wait and prevents a stale mount without cancelling shared application work. Producers must honor their owner's signal to stop I/O. The example below explicitly isolates its per-island data preparation:
310
376
 
311
377
  ```tsx
312
- import type { VNode } from "@atom.io/spa"
378
+ import type { SpaElement } from "@atom.io/spa"
313
379
  import { useLoadable } from "@atom.io/spa"
314
380
  import type { AstroStorePreparation } from "@atom.io/spa/astro"
315
381
  import type { Loadable } from "atom.io"
@@ -321,7 +387,7 @@ const greetingAtom = atom<Loadable<string>>({
321
387
  default: ``,
322
388
  })
323
389
 
324
- export default function Greeting(): VNode {
390
+ export default function Greeting(): SpaElement {
325
391
  const greeting = useLoadable(greetingAtom, ``)
326
392
  return <p>{greeting().value}</p>
327
393
  }
@@ -346,52 +412,6 @@ Greeting.prepareStore = prepare
346
412
 
347
413
  AstroApplicationContext, AstroStoreContext, AstroStoreFactory, AstroStorePreparation, and Island types are exported from @atom.io/spa/astro. Preparation runs before component setup, so use the context's cleanup registrar there; use SPA's onCleanup inside components. Preparation failures reject the Astro render or hydration operation, retaining cleanup errors alongside the original failure. The factory and preparation callback are awaited per render; component setup and the standalone renderToString API remain synchronous.
348
414
 
349
- ```tsx
350
- import type { Child, VNode } from "@atom.io/spa"
351
- import { onCleanup, useGetter, useId, useSetter } from "@atom.io/spa"
352
- import { atom, Silo } from "atom.io"
353
- import { IMPLICIT } from "atom.io/internal"
354
-
355
- const countAtom = atom<number>({ key: `count`, default: 0 })
356
- export default function Counter(props: {
357
- initial: number
358
- children?: Child
359
- slots?: Record<string, Child>
360
- }): VNode {
361
- const getCount = useGetter(countAtom)
362
- const setCount = useSetter(countAtom)
363
- const id = useId()
364
- onCleanup(() => {
365
- /* Release imperative resources owned by this instance here. */
366
- })
367
- return (
368
- <section aria-labelledby={id}>
369
- <h2 id={id}>Counter</h2>
370
- {props.slots?.[`heading`]}
371
- {props.children}
372
- <button
373
- onClick={() => {
374
- setCount((value) => value + 1)
375
- }}
376
- >
377
- {getCount()}
378
- </button>
379
- </section>
380
- )
381
- }
382
-
383
- // Astro calls this on the server and in the browser with the same serialized props.
384
- Counter.createStore = (props: { initial: number }) => {
385
- const silo = new Silo(
386
- { name: `counter-island`, lifespan: `ephemeral`, isProduction: true },
387
- IMPLICIT.STORE,
388
- )
389
- silo.setState(countAtom, props.initial)
390
- return silo.store
391
- }
392
-
393
- ```
394
-
395
415
  Astro client:load, client:idle, client:visible, client:media, and client:only use Astro's scheduling. The integration hydrates eligible initial server markup or renders fresh content and releases the root on astro:unmount. Default slot content arrives as children and named content through slots. Reserved astro-slot wrappers contain Astro's already-rendered HTML; never use their innerHTML escape hatch for untrusted strings.
396
416
 
397
417
  Persisted islands receive live prop and slot updates without rerunning component setup or recreating their store. Repeated hydration calls during preparation share one factory and preparation invocation. New client mounts use the latest props and slots; hydration attaches to the original server tree first, then applies any changes received while preparing. The factory receives the initial props and runs only when an island is first mounted; put changing values in props rather than relying on the factory to run again.
@@ -402,7 +422,7 @@ The checked Astro fixture demonstrates default/named slots and custom independen
402
422
 
403
423
  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.
404
424
 
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.
425
+ 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.
406
426
 
407
427
  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.
408
428
 
@@ -434,11 +454,11 @@ Sizes are exact minified and level-9 gzip JavaScript byte counts. Declarations,
434
454
 
435
455
  | Recipe | Entry | Minified JS | Gzip JS |
436
456
  | -------------------------------- | --------------------------------- | ----------: | -------: |
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 |
457
+ | Family app with refs and history | `tonnage-recipes/family-app.ts` | 64,020 B | 19,088 B |
458
+ | Async interactive client app | `tonnage-recipes/async-app.ts` | 42,445 B | 13,332 B |
459
+ | Interactive client app | `tonnage-recipes/client-app.ts` | 42,108 B | 13,178 B |
460
+ | Hydrated interactive app | `tonnage-recipes/hydrated-app.ts` | 42,109 B | 13,176 B |
461
+ | Interactive Astro island | `tonnage-recipes/astro-island.ts` | 48,624 B | 15,226 B |
442
462
 
443
463
  Report maintained with [tonnage](https://github.com/jeremybanka/tonnage).
444
464
 
@@ -455,7 +475,7 @@ SPA includes Konva, Three.js, and Motion integrations behind separate entrypoint
455
475
  Import Stage, Layer, Group, Rect, Circle, Ellipse, Line, Text, Image, Path, Star, and Transformer from @atom.io/spa/konva. Stage renders a DOM container and creates its native stage after browser mounting. Compiled atom reads update native attributes; keyed children preserve node identity. Native configuration attributes and onClick, onPointerDown, onDragMove, and onDragEnd handlers are supported. Refs receive native nodes and null on cleanup. Removal destroys owned nodes and listeners.
456
476
 
457
477
  ```tsx
458
- import type { VNode } from "@atom.io/spa"
478
+ import type { SpaElement } from "@atom.io/spa"
459
479
  import { useGetter, useSetter } from "@atom.io/spa"
460
480
  import { Circle, Layer, Stage } from "@atom.io/spa/konva"
461
481
  import { atom } from "atom.io"
@@ -464,7 +484,7 @@ const pointAtom = atom<{ x: number; y: number }>({
464
484
  key: `point`,
465
485
  default: { x: 100, y: 100 },
466
486
  })
467
- export function Editor(): VNode {
487
+ export function Editor(): SpaElement {
468
488
  const getPoint = useGetter(pointAtom)
469
489
  const setPoint = useSetter(pointAtom)
470
490
  return (
@@ -494,7 +514,7 @@ Konva owns hit testing, dragging, and draw batching. Write drag results back int
494
514
  Import Canvas, Group, Mesh, PerspectiveCamera, AmbientLight, DirectionalLight, BoxGeometry, SphereGeometry, PlaneGeometry, MeshStandardMaterial, MeshBasicMaterial, and MeshNormalMaterial from @atom.io/spa/three. Canvas creates a WebGL renderer after browser mounting. Geometry and material children attach to their Mesh, with one of each supported. Position and rotation accept three-number tuples; scale also accepts a scalar.
495
515
 
496
516
  ```tsx
497
- import type { VNode } from "@atom.io/spa"
517
+ import type { SpaElement } from "@atom.io/spa"
498
518
  import { useGetter } from "@atom.io/spa"
499
519
  import {
500
520
  AmbientLight,
@@ -507,7 +527,7 @@ import {
507
527
  import { atom } from "atom.io"
508
528
 
509
529
  const colorAtom = atom<string>({ key: `color`, default: `coral` })
510
- export function Scene(): VNode {
530
+ export function Scene(): SpaElement {
511
531
  const getColor = useGetter(colorAtom)
512
532
  return (
513
533
  <Canvas width={800} height={600}>
@@ -545,7 +565,7 @@ Import motionCapability from @atom.io/spa/motion and register it explicitly in r
545
565
  import { render } from "@atom.io/spa"
546
566
  import { motionCapability } from "@atom.io/spa/motion"
547
567
 
548
- import { MotionPanel } from "./motion.spa.tsx"
568
+ import { MotionPanel } from "./motion.tsx"
549
569
 
550
570
  render(() => <MotionPanel />, document.getElementById(`app`)!, {
551
571
  capabilities: [motionCapability()],
@@ -556,12 +576,12 @@ render(() => <MotionPanel />, document.getElementById(`app`)!, {
556
576
  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.
557
577
 
558
578
  ```tsx
559
- import type { VNode } from "@atom.io/spa"
579
+ import type { SpaElement } from "@atom.io/spa"
560
580
  import { useGetter, useSetter } from "@atom.io/spa"
561
581
  import { atom } from "atom.io"
562
582
 
563
583
  const targetXAtom = atom<number>({ key: `targetX`, default: 0 })
564
- export function MotionPanel(): VNode {
584
+ export function MotionPanel(): SpaElement {
565
585
  const getTargetX = useGetter(targetXAtom)
566
586
  const setTargetX = useSetter(targetXAtom)
567
587
  return (
@@ -596,7 +616,7 @@ Motion respects the user's reduced-motion preference by default, including chang
596
616
  The same attributes animate numeric Konva properties and colors, or Three.js position, rotation, scale, light/material color, opacity, and intensity. Three.js rotation uses Euler components, not quaternion interpolation. DOM hover and tap use Motion's gesture handling; Konva gestures use native pointer events. Three.js gestures use the same raycast event layer as ordinary scene pointer handlers.
597
617
 
598
618
  ```tsx
599
- import type { VNode } from "@atom.io/spa"
619
+ import type { SpaElement } from "@atom.io/spa"
600
620
  import { useGetter } from "@atom.io/spa"
601
621
  import {
602
622
  BoxGeometry,
@@ -611,7 +631,7 @@ const targetXAtom = atom<number>({
611
631
  default: 1,
612
632
  })
613
633
  // Mount under a root with capabilities: [motionCapability()].
614
- export function SpringCube(): VNode {
634
+ export function SpringCube(): SpaElement {
615
635
  const getTargetX = useGetter(targetXAtom)
616
636
  return (
617
637
  <Canvas>
@@ -634,19 +654,19 @@ export function SpringCube(): VNode {
634
654
 
635
655
  ```
636
656
 
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.
657
+ 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.
638
658
 
639
659
  ### Exit animations and re-entry
640
660
 
641
661
  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
662
 
643
663
  ```tsx
644
- import type { VNode } from "@atom.io/spa"
664
+ import type { SpaElement } from "@atom.io/spa"
645
665
  import { useGetter, useSetter } from "@atom.io/spa"
646
666
  import { atom } from "atom.io"
647
667
 
648
668
  const visibleAtom = atom<boolean>({ key: `visible`, default: true })
649
- export function DismissiblePanel(): VNode {
669
+ export function DismissiblePanel(): SpaElement {
650
670
  const getVisible = useGetter(visibleAtom)
651
671
  const setVisible = useSetter(visibleAtom)
652
672
  return (
package/README.mdx CHANGED
@@ -9,15 +9,20 @@ import ViteConfig from "./exhibits/vite.config.ts" with { type: "code" };
9
9
  import Main from "./exhibits/main.tsx" with { type: "code" };
10
10
  import Types from "./exhibits/tsconfig.json" with { type: "code" };
11
11
  import AstroConfig from "./exhibits/astro.config.ts" with { type: "code" };
12
- import AsyncAstro from "./exhibits/async-astro.spa.tsx" with { type: "code" };
13
- import Counter from "./exhibits/Counter.spa.tsx" with { type: "code" };
12
+ import AsyncAstro from "./exhibits/async-astro.tsx" with { type: "code" };
13
+ import Counter from "./exhibits/Counter.tsx" with { type: "code" };
14
+ import CounterPage from "./exhibits/counter-page.astro" with { type: "code" };
15
+ import VitePage from "./exhibits/index.html" with { type: "code" };
16
+ import CreateAstroTemplate from "./exhibits/create-astro-template.sh" with {
17
+ type: "code",
18
+ };
14
19
  import Verify from "./exhibits/verify.sh" with { type: "code" };
15
- import KonvaExample from "./exhibits/konva.spa.tsx" with { type: "code" };
16
- import ThreeExample from "./exhibits/three.spa.tsx" with { type: "code" };
17
- import MotionPanel from "./exhibits/motion.spa.tsx" with { type: "code" };
20
+ import KonvaExample from "./exhibits/konva.tsx" with { type: "code" };
21
+ import ThreeExample from "./exhibits/three.tsx" with { type: "code" };
22
+ import MotionPanel from "./exhibits/motion.tsx" with { type: "code" };
18
23
  import MotionMain from "./exhibits/motion-main.tsx" with { type: "code" };
19
- import MotionExit from "./exhibits/motion-exit.spa.tsx" with { type: "code" };
20
- import MotionThree from "./exhibits/motion-three.spa.tsx" with { type: "code" };
24
+ import MotionExit from "./exhibits/motion-exit.tsx" with { type: "code" };
25
+ import MotionThree from "./exhibits/motion-three.tsx" with { type: "code" };
21
26
 
22
27
  <p align="center">
23
28
  <img src="https://raw.githubusercontent.com/jeremybanka/atom.io/main/apps/atom.io.fyi/public/spa/icon-512.png" alt="SPA logo" width="160" height="160" />
@@ -29,12 +34,34 @@ An experimental JSX framework whose state engine is atom.io. Components run once
29
34
 
30
35
  The npm package is named @atom.io/spa. Its browser runtime, Vite compiler, server renderer, and Astro integration are implemented here. It has no independent state primitive, effect API, React hook dispatcher, or compatibility layer.
31
36
 
37
+ ## Start with the Astro template
38
+
39
+ Use the [SPA + Astro SSR template](https://github.com/jeremybanka/atom.io/tree/main/templates/spa-astro-ssr) for a ready-to-run application with Astro islands, resumable initial data, SQLite, and tRPC:
40
+
41
+ <CreateAstroTemplate />
42
+
43
+ For manual setup, see the [Astro](https://atom.io.fyi/docs/spa/astro) and [Vite](https://atom.io.fyi/docs/spa/vite) integration guides on atom.io.fyi.
44
+
32
45
  ## A point, not two signals
33
46
 
34
47
  <Point />
35
48
 
36
49
  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.
37
50
 
51
+ ## Astro
52
+
53
+ Register the Astro integration, which compiles .tsx and .jsx components by default:
54
+
55
+ <AstroConfig />
56
+
57
+ Create a counter component:
58
+
59
+ <Counter />
60
+
61
+ Import it into an Astro page and use client:load to make it interactive. Astro handles server rendering and browser hydration:
62
+
63
+ <CounterPage />
64
+
38
65
  ## Vite
39
66
 
40
67
  Add @atom.io/spa and atom.io to the application's dependencies. The spa plugin is required: the ordinary TypeScript JSX transform cannot preserve live expressions. It compiles expressions into lazy child computations and property getters; it also preserves spread precedence and live component props.
@@ -43,11 +70,15 @@ Add @atom.io/spa and atom.io to the application's dependencies. The spa plugin i
43
70
 
44
71
  <Types />
45
72
 
73
+ Add a host element in index.html, then mount the same counter from main.tsx:
74
+
75
+ <VitePage />
76
+
46
77
  <Main />
47
78
 
48
79
  The development plugin keeps SPA and atom.io outside dependency prebundling so renderer entrypoints, component hooks, and stores share one runtime, including Astro adapter environments. It uses full page reloads. Components and render computations are synchronous. Modern browsers with ES2022 and DOM Range support are the target.
49
80
 
50
- ## Component API
81
+ ## Hooks
51
82
 
52
83
  | API | Contract |
53
84
  | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
@@ -104,23 +135,25 @@ Atom.io owns promise settlement and subscriptions. SPA adds no fetching, retries
104
135
 
105
136
  The client exports render and hydrate. Both accept a setup callback, a host Element, and optional store, idPrefix, and onError options, and return dispose and flush methods. Updates coalesce in a microtask; flush drains them synchronously. Dispose is idempotent and removes only owned nodes. Cleanup continues after individual cleanup failures and aggregates errors. A failed computation disposes its root; asynchronous update failures reach onError, while explicit flush failures throw.
106
137
 
107
- The separate server entrypoint exports renderToString with the same setup callback and store/ID options. Supply a request-specific store for SSR. Server rendering retains no subscriptions and runs owner cleanup. Hydration reuses matching server nodes and IDs, attaches events, and recreates subscriptions. It requires the same initial state, component structure, and valid HTML on both sides; mismatches throw rather than silently remounting. Use explicit tbody elements in tables. Controlled form properties are applied during hydration.
138
+ The separate server entrypoint exports renderToString with the same setup callback and store/ID options. Supply a request-specific store for SSR. Server rendering retains no subscriptions and runs owner cleanup. Hydration reuses matching server nodes and IDs, attaches events, and recreates subscriptions. Match initial state, component structure, and valid HTML on both sides. A hydration mismatch produces one human-readable console warning per root in development and production, identifying the host and expected/found nodes. SPA repairs mismatched nodes, inserts missing nodes, and removes unexpected leftovers during the same hydration pass. Component setup and mount hooks run once, subscriptions remain active, and matching nodes are reused. Replaced nodes can lose focus, selection, or unsaved browser input; unaffected roots continue running. An explicit client idPrefix takes precedence when repairing mismatched root markers. Use explicit tbody elements in tables. Controlled form properties are applied during hydration.
108
139
 
109
- The production build omits development diagnostics and invalid-input checks; the development export condition enables them. Pure render computations must not write state. Promise children, async components, portals, suspense, error boundaries, style objects, and automatic token-as-child bindings are outside this first implementation. Applications handle asynchronous data through atom.io state and synchronous conditional JSX.
140
+ The production build omits development-only diagnostics and invalid-input checks; the development export condition enables them. Hydration recovery warnings remain available in all builds. Pure render computations must not write state. Promise children, async components, portals, suspense, error boundaries, style objects, and automatic token-as-child bindings are outside this first implementation. Applications handle asynchronous data through atom.io state and synchronous conditional JSX.
110
141
 
111
- ## Astro
142
+ ## Astro state and data
112
143
 
113
- The integration transforms .spa.tsx and .spa.jsx files by default, so another JSX renderer can coexist. Configure include to change this filter. Top-level functions containing JSX are branded by the compiler for renderer detection.
114
-
115
- <AstroConfig />
144
+ The integration compiles .tsx and .jsx files by default. Use the include option to limit compilation to SPA component directories when another JSX renderer is present. Top-level functions containing JSX are branded by the compiler for renderer detection.
116
145
 
117
146
  Default islands share the normal implicit atom.io store in the browser. Module-scoped tokens, SPA hooks, and ordinary getState/setState calls all address the same graph. SSR shares a separate store within each request; concurrent requests never share values. Definitions imported after an earlier island started are installed into that request's store before the next island prepares. Server reads and writes must use the selected store (through SPA hooks or store-aware atom.io operations); free getState/setState calls still target the process-global implicit store.
118
147
 
119
- The integration starts observing browser state before island preparation. Untouched initial islands hydrate their matching server DOM. Once application state changes or a shared client:only island starts, delayed islands mount fresh against the live graph. Astro ClientRouter navigation also makes newly introduced islands mount fresh, preserving existing browser values instead of replaying the incoming server snapshot. Mounted and persisted roots keep their subscriptions and DOM. This decision is conservative across the application: even an unrelated state change disables hydration for later roots. Ordinary defaults must still produce matching initial values; SPA does not serialize stores or repair nondeterministic renders.
148
+ The integration starts observing browser state before island preparation. Untouched initial islands hydrate their matching server DOM. Once application state changes or a shared client:only island starts, delayed islands mount fresh against the live graph. Astro ClientRouter navigation also makes newly introduced islands mount fresh, preserving existing browser values instead of replaying the incoming server snapshot. Mounted and persisted roots keep their subscriptions and DOM. This decision is conservative across the application: even an unrelated state change disables hydration for later roots. Ordinary defaults should still produce matching initial values. DOM mismatch recovery keeps a view interactive; it does not reconstruct missing server data or resolve nondeterministic application logic.
149
+
150
+ With resumability/astro installed alongside SPA, resumability owns Astro's request collection, page sidecars, and browser scope. SPA awaits async state used by JSX and uses the host's renderer adapter to attach seeds to islands. Ordinary atom defaults use the host without changing the store's evaluator; private stores bind a separate scope so lazy work ends with the island. Define resumable defaults at module scope and render ordinary Astro islands. Components need no Resumption wrapper, prepareStore callback, or preload list. The same host supports plain Astro constants without atom.io. See the [resumability guide](https://atom.io.fyi/docs/spa/astro#resumability) and the inventory starter for a complete example. Resumability is an optional peer, loaded only by this adapter.
151
+
152
+ Server-rendered views record the state tokens they read so the browser can check readiness before hydration. If an ordinary async default is still pending without a synchronous seed, SPA mounts a fresh view with its loading state; seeded values continue to hydrate existing DOM. This also handles cached server reads and mixed ordinary/resumable state. Private server preparation and rendering are cancelled with their request, releasing cleanup resources even when a producer ignores its abort signal.
120
153
 
121
154
  Set a component's isolate property to true to opt into a private store copied from registered definitions. An optional createStore(props, context) factory supplies a custom RootStore or promise and retains a private preparation lifetime. Custom factories that return the same store are responsible for coordinating their hydration and cleanup. Keep atom definitions at module scope in either mode.
122
155
 
123
- An optional prepareStore(store, props, context) callback initializes the selected store and may return a promise. SPA awaits it before component setup on the server and browser. Existing one-argument synchronous factories still work. Use serialized props or an independent transport such as resumability for server-produced initial data. Shared preparation must be safe to call for multiple islands; use context.application.get(key, initialize) to create an application resource once.
156
+ An optional prepareStore(store, props, context) callback initializes the selected store and may return a promise. SPA awaits it before component setup on the server and browser. Existing one-argument synchronous factories still work. Shared preparation must be safe to call for multiple islands; use context.application.get(key, initialize) to create an application resource once.
124
157
 
125
158
  The context provides element (the browser astro-island host, undefined on the server), signal, and onCleanup for the individual island. Its application provides get, signal, onCleanup, and canResume for the shared lifetime. Browser application resources survive island removal and ClientRouter navigation; they end on a full page exit, with back/forward-cache suspension preserved. SSR application resources end after the response stream finishes or is cancelled. Private islands' application resources end with the island. Use application cleanup and cancellation for shared fetches or resumption scopes; use the outer context for resources owned by one island.
126
159
 
@@ -130,8 +163,6 @@ Register cleanup as resources are acquired, before awaiting work that might fail
130
163
 
131
164
  AstroApplicationContext, AstroStoreContext, AstroStoreFactory, AstroStorePreparation, and Island types are exported from @atom.io/spa/astro. Preparation runs before component setup, so use the context's cleanup registrar there; use SPA's onCleanup inside components. Preparation failures reject the Astro render or hydration operation, retaining cleanup errors alongside the original failure. The factory and preparation callback are awaited per render; component setup and the standalone renderToString API remain synchronous.
132
165
 
133
- <Counter />
134
-
135
166
  Astro client:load, client:idle, client:visible, client:media, and client:only use Astro's scheduling. The integration hydrates eligible initial server markup or renders fresh content and releases the root on astro:unmount. Default slot content arrives as children and named content through slots. Reserved astro-slot wrappers contain Astro's already-rendered HTML; never use their innerHTML escape hatch for untrusted strings.
136
167
 
137
168
  Persisted islands receive live prop and slot updates without rerunning component setup or recreating their store. Repeated hydration calls during preparation share one factory and preparation invocation. New client mounts use the latest props and slots; hydration attaches to the original server tree first, then applies any changes received while preparing. The factory receives the initial props and runs only when an island is first mounted; put changing values in props rather than relying on the factory to run again.
@@ -142,7 +173,7 @@ The checked Astro fixture demonstrates default/named slots and custom independen
142
173
 
143
174
  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.
144
175
 
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.
176
+ 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.
146
177
 
147
178
  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.
148
179
 
@@ -210,7 +241,7 @@ The same attributes animate numeric Konva properties and colors, or Three.js pos
210
241
 
211
242
  <MotionThree />
212
243
 
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.
244
+ 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.
214
245
 
215
246
  ### Exit animations and re-entry
216
247
 
@@ -1,4 +1,4 @@
1
- import { t as AstroApplicationContext } from "./astro-shared-CYSRrRr8.js";
1
+ import { t as AstroApplicationContext } from "./astro-shared-DHIpjNIG.js";
2
2
  type Lifetime = {
3
3
  signal: AbortSignal;
4
4
  onCleanup(cleanup: () => void): () => void;