@atom.io/spa 0.0.7 → 0.0.9
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.
- package/README.md +169 -25
- package/README.mdx +62 -15
- package/dist/astro-application.d.ts +1 -1
- package/dist/astro-client.d.ts +1 -1
- package/dist/astro-client.d.ts.map +1 -1
- package/dist/astro-client.js +5 -4
- package/dist/astro-client.js.map +1 -1
- package/dist/astro-resumability-client.d.ts +1 -1
- package/dist/astro-server.js +4 -4
- package/dist/astro-server.js.map +1 -1
- package/dist/{astro-shared-83hxw7-M.js → astro-shared-DBwINQav.js} +2 -2
- package/dist/{astro-shared-83hxw7-M.js.map → astro-shared-DBwINQav.js.map} +1 -1
- package/dist/{astro-shared-DZp1x8RQ.d.ts → astro-shared-KxK9OUSj.d.ts} +2 -2
- package/dist/{astro-shared-DZp1x8RQ.d.ts.map → astro-shared-KxK9OUSj.d.ts.map} +1 -1
- package/dist/astro.d.ts +1 -1
- package/dist/astro.js +1 -1
- package/dist/{capabilities-DNcnGRv_.d.ts → capabilities-ChgSs6bp.d.ts} +34 -6
- package/dist/capabilities-ChgSs6bp.d.ts.map +1 -0
- package/dist/client.min.js +1 -1
- package/dist/core-DD2giR6E.js +451 -0
- package/dist/core-DD2giR6E.js.map +1 -0
- package/dist/development/astro-client.js +5 -4
- package/dist/development/astro-client.js.map +1 -1
- package/dist/development/astro-server.js +4 -4
- package/dist/development/astro-server.js.map +1 -1
- package/dist/development/{astro-shared-83hxw7-M.js → astro-shared-DBwINQav.js} +2 -2
- package/dist/development/{astro-shared-83hxw7-M.js.map → astro-shared-DBwINQav.js.map} +1 -1
- package/dist/development/astro.js +1 -1
- package/dist/development/core-DrUd8x25.js +465 -0
- package/dist/development/core-DrUd8x25.js.map +1 -0
- package/dist/development/{dom-DQ0M3rLL.js → dom-BRFv7FP_.js} +150 -35
- package/dist/development/dom-BRFv7FP_.js.map +1 -0
- package/dist/development/floating.js +2 -6
- package/dist/development/floating.js.map +1 -1
- package/dist/development/hot.js +164 -0
- package/dist/development/hot.js.map +1 -0
- package/dist/development/identity-DwB8MTM1.js +121 -0
- package/dist/development/identity-DwB8MTM1.js.map +1 -0
- package/dist/development/index.js +5 -5
- package/dist/development/jsx-runtime-BGDPK50B.js +49 -0
- package/dist/development/jsx-runtime-BGDPK50B.js.map +1 -0
- package/dist/development/jsx-runtime.js +1 -25
- package/dist/development/konva.js +12 -5
- package/dist/development/konva.js.map +1 -1
- package/dist/development/motion.js +4 -21
- package/dist/development/motion.js.map +1 -1
- package/dist/development/renderer.js +41 -40
- package/dist/development/renderer.js.map +1 -1
- package/dist/development/{server-renderer-DCLoMdOX.js → server-renderer-u1-c5PGd.js} +8 -18
- package/dist/development/server-renderer-u1-c5PGd.js.map +1 -0
- package/dist/development/server.js +1 -1
- package/dist/{src-Bme1kz2b.js → development/src-CB7ruwRs.js} +3 -3
- package/dist/development/src-CB7ruwRs.js.map +1 -0
- package/dist/development/three.js +20 -19
- package/dist/development/three.js.map +1 -1
- package/dist/development/vite-WUiz1ju6.js +545 -0
- package/dist/development/vite-WUiz1ju6.js.map +1 -0
- package/dist/development/vite.js +1 -1
- package/dist/{dom-D8g3roX9.js → dom--HZvmgqd.js} +139 -32
- package/dist/dom--HZvmgqd.js.map +1 -0
- package/dist/floating.d.ts +1 -1
- package/dist/floating.d.ts.map +1 -1
- package/dist/floating.js +2 -6
- package/dist/floating.js.map +1 -1
- package/dist/hot.d.ts +15 -0
- package/dist/hot.d.ts.map +1 -0
- package/dist/hot.js +19 -0
- package/dist/hot.js.map +1 -0
- package/dist/identity-oFU5p-Qj.js +121 -0
- package/dist/identity-oFU5p-Qj.js.map +1 -0
- package/dist/{index-BFnXIfOj.d.ts → index-DdA39aMv.d.ts} +4 -4
- package/dist/{index-BFnXIfOj.d.ts.map → index-DdA39aMv.d.ts.map} +1 -1
- package/dist/index.d.ts +4 -4
- package/dist/index.js +5 -5
- package/dist/jsx-runtime-BGDPK50B.js +49 -0
- package/dist/jsx-runtime-BGDPK50B.js.map +1 -0
- package/dist/{jsx-runtime-DQnpyT_g.d.ts → jsx-runtime-CCvcEosg.d.ts} +14 -9
- package/dist/jsx-runtime-CCvcEosg.d.ts.map +1 -0
- package/dist/jsx-runtime.d.ts +1 -1
- package/dist/jsx-runtime.js +1 -25
- package/dist/konva.d.ts +46 -9
- package/dist/konva.d.ts.map +1 -1
- package/dist/konva.js +12 -5
- package/dist/konva.js.map +1 -1
- package/dist/motion.d.ts +1 -1
- package/dist/motion.js +4 -21
- package/dist/motion.js.map +1 -1
- package/dist/renderer.d.ts +1 -1
- package/dist/renderer.d.ts.map +1 -1
- package/dist/renderer.js +39 -40
- package/dist/renderer.js.map +1 -1
- package/dist/{server-renderer-D0rsFL_-.js → server-renderer-BYFDmqnM.js} +8 -18
- package/dist/server-renderer-BYFDmqnM.js.map +1 -0
- package/dist/server.d.ts +1 -1
- package/dist/server.js +1 -1
- package/dist/size.json +12 -12
- package/dist/{development/src-DoQgCX-O.js → src-B2W_TA_X.js} +3 -3
- package/dist/src-B2W_TA_X.js.map +1 -0
- package/dist/three.d.ts +3 -3
- package/dist/three.d.ts.map +1 -1
- package/dist/three.js +20 -19
- package/dist/three.js.map +1 -1
- package/dist/vite-WUiz1ju6.js +545 -0
- package/dist/vite-WUiz1ju6.js.map +1 -0
- package/dist/vite.d.ts.map +1 -1
- package/dist/vite.js +1 -1
- package/package.json +16 -9
- package/src/astro-client.ts +3 -2
- package/src/astro-server.ts +2 -2
- package/src/capabilities.ts +48 -21
- package/src/compiler-hmr.ts +297 -0
- package/src/compiler.ts +127 -25
- package/src/core.ts +282 -33
- package/src/dom-forms.ts +127 -0
- package/src/dom.ts +116 -52
- package/src/floating.ts +2 -6
- package/src/hot.ts +190 -0
- package/src/identity.ts +39 -0
- package/src/index.ts +2 -0
- package/src/jsx-runtime.ts +6 -26
- package/src/jsx-types.d.ts +8 -3
- package/src/konva.ts +66 -10
- package/src/motion.ts +3 -1
- package/src/presence.ts +11 -23
- package/src/props.ts +55 -0
- package/src/renderer.ts +91 -71
- package/src/server-renderer.ts +18 -13
- package/src/three.ts +23 -24
- package/src/use-loadable.ts +2 -2
- package/src/vite.ts +44 -4
- package/dist/capabilities-DNcnGRv_.d.ts.map +0 -1
- package/dist/capabilities-nOIitQ-_.js +0 -65
- package/dist/capabilities-nOIitQ-_.js.map +0 -1
- package/dist/core-B4rJ0xdc.js +0 -268
- package/dist/core-B4rJ0xdc.js.map +0 -1
- package/dist/development/capabilities-nOIitQ-_.js +0 -65
- package/dist/development/capabilities-nOIitQ-_.js.map +0 -1
- package/dist/development/core-BHA7I1nf.js +0 -271
- package/dist/development/core-BHA7I1nf.js.map +0 -1
- package/dist/development/dom-DQ0M3rLL.js.map +0 -1
- package/dist/development/jsx-runtime.js.map +0 -1
- package/dist/development/server-renderer-DCLoMdOX.js.map +0 -1
- package/dist/development/src-DoQgCX-O.js.map +0 -1
- package/dist/development/vite-Bmyb6P5w.js +0 -265
- package/dist/development/vite-Bmyb6P5w.js.map +0 -1
- package/dist/dom-D8g3roX9.js.map +0 -1
- package/dist/jsx-runtime-DQnpyT_g.d.ts.map +0 -1
- package/dist/jsx-runtime.js.map +0 -1
- package/dist/server-renderer-D0rsFL_-.js.map +0 -1
- package/dist/src-Bme1kz2b.js.map +0 -1
- package/dist/vite-Bmyb6P5w.js +0 -265
- package/dist/vite-Bmyb6P5w.js.map +0 -1
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
An experimental JSX framework whose state engine is atom.io. Components run once per mounted instance. Calls to accessors inside compiled JSX subscribe the affected DOM computations; atom.io updates those computations without rerunning component setup.
|
|
6
6
|
|
|
7
|
-
The npm package is named @atom.io/spa. Its browser runtime, Vite compiler, server renderer, and Astro integration are implemented here.
|
|
7
|
+
The npm package is named @atom.io/spa. Its browser runtime, Vite compiler, server renderer, and Astro integration are implemented here. State and general reactions belong to atom.io.
|
|
8
8
|
|
|
9
9
|
## Start with the Astro template
|
|
10
10
|
|
|
@@ -160,7 +160,44 @@ render(() => <Counter />, document.getElementById(`app`)!)
|
|
|
160
160
|
|
|
161
161
|
```
|
|
162
162
|
|
|
163
|
-
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.
|
|
163
|
+
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. Component-only JSX modules refresh affected roots against their existing atom.io stores; production builds omit hot registration. Components and render computations are synchronous. Modern browsers with ES2022 and DOM Range support are the target.
|
|
164
|
+
|
|
165
|
+
Hot updates rerun affected roots, including scene roots and independent Astro islands, with the same store and props source. Old scopes release subscriptions, listeners, refs, and onCleanup callbacks before replacement. Atoms, persistent family members, and timeline history remain; DOM-local values and component-owned family members disposed by cleanup reset. A failed hot setup displays an error while keeping its store available for the next edit.
|
|
166
|
+
|
|
167
|
+
Keep state definitions and Astro store factories in separate modules from component-only views. State declarations, mixed runtime exports, re-exports, changed export boundaries, and top-level side effects use full reloads. Type-only exports are allowed. The first implementation refreshes complete roots rather than replacing individual component instances.
|
|
168
|
+
|
|
169
|
+
Define persistent tokens in their own state module:
|
|
170
|
+
|
|
171
|
+
```ts
|
|
172
|
+
import { atom } from "atom.io"
|
|
173
|
+
|
|
174
|
+
export const editCountAtom = atom<number>({ key: `editCount`, default: 0 })
|
|
175
|
+
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
Import the token from a component-only view. Editing this view's JSX or handler preserves the counter value:
|
|
179
|
+
|
|
180
|
+
```tsx
|
|
181
|
+
import type { SpaElement } from "@atom.io/spa"
|
|
182
|
+
import { useGetter, useSetter } from "@atom.io/spa"
|
|
183
|
+
|
|
184
|
+
import { editCountAtom } from "./hmr-state.ts"
|
|
185
|
+
|
|
186
|
+
export function HotCounter(): SpaElement {
|
|
187
|
+
const getEditCount = useGetter(editCountAtom)
|
|
188
|
+
const setEditCount = useSetter(editCountAtom)
|
|
189
|
+
return (
|
|
190
|
+
<button
|
|
191
|
+
onClick={() => {
|
|
192
|
+
setEditCount((value) => value + 1)
|
|
193
|
+
}}
|
|
194
|
+
>
|
|
195
|
+
{getEditCount()}
|
|
196
|
+
</button>
|
|
197
|
+
)
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
```
|
|
164
201
|
|
|
165
202
|
## Hooks
|
|
166
203
|
|
|
@@ -168,17 +205,59 @@ The development plugin keeps SPA and atom.io outside dependency prebundling so r
|
|
|
168
205
|
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
169
206
|
| useLoadable(token, fallback?) | Return a tracked accessor for loading, last-observed values, and handled errors. |
|
|
170
207
|
| 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
|
|
208
|
+
| useDisposal() | Return atom.io state disposal bound to the current store. |
|
|
172
209
|
| useSetter(token) | Return a stable atom.io writer. |
|
|
173
210
|
| useTimeline(token) | Return a stable object with getCursor/getLength readers, undo/redo/clear commands, and transaction-group controls. |
|
|
174
211
|
| useTransaction(token) | Bind an atom.io transaction, preserving its arguments and result. |
|
|
175
212
|
| useRef(token) | Return an attachment callback for a nullable element atom. Clear it only while this attachment still owns the reference. |
|
|
176
|
-
| useId() | Allocate an instance-stable ID using the root's
|
|
213
|
+
| useId() | Allocate an instance-stable ID using the current prefix and the root's shared sequence. |
|
|
177
214
|
| onCleanup(callback) | Register synchronous teardown with the current owner. |
|
|
178
215
|
| onMount(callback) | Run once after attachment and ref publication; omitted during server rendering. |
|
|
179
|
-
|
|
|
216
|
+
| onCommit(read, apply) | Track a value and apply changes after renderer writes, within the same flush. |
|
|
217
|
+
| useStore() | Return the current atom.io store without creating a store or subscribing. |
|
|
218
|
+
|
|
219
|
+
Call setup helpers synchronously during component setup or owned mount callbacks. Capture their results for event handlers. Tokens are fixed for an instance. Change the component's key when it needs to bind a different token. Read data props through the props object in JSX or a tracked binding to get updates. Destructuring data props during setup takes a snapshot.
|
|
180
220
|
|
|
181
|
-
|
|
221
|
+
### onCommit
|
|
222
|
+
|
|
223
|
+
Use onCommit to measure a ref after the root finishes its DOM writes.
|
|
224
|
+
|
|
225
|
+
```tsx
|
|
226
|
+
import type { SpaElement } from "@atom.io/spa"
|
|
227
|
+
import { onCommit, useGetter, useSetter } from "@atom.io/spa"
|
|
228
|
+
import { atom } from "atom.io"
|
|
229
|
+
|
|
230
|
+
export const captionAtom = atom<string>({ key: `caption`, default: `Hello` })
|
|
231
|
+
export const captionHeightAtom = atom<number>({
|
|
232
|
+
key: `captionHeight`,
|
|
233
|
+
default: 0,
|
|
234
|
+
})
|
|
235
|
+
|
|
236
|
+
export function Caption(): SpaElement {
|
|
237
|
+
const getCaption = useGetter(captionAtom)
|
|
238
|
+
const setCaptionHeight = useSetter(captionHeightAtom)
|
|
239
|
+
let caption: HTMLParagraphElement | null = null
|
|
240
|
+
|
|
241
|
+
onCommit(getCaption, () => {
|
|
242
|
+
setCaptionHeight(caption!.getBoundingClientRect().height)
|
|
243
|
+
})
|
|
244
|
+
|
|
245
|
+
return (
|
|
246
|
+
<p
|
|
247
|
+
ref={(element) => {
|
|
248
|
+
caption = element
|
|
249
|
+
}}
|
|
250
|
+
>
|
|
251
|
+
{getCaption()}
|
|
252
|
+
</p>
|
|
253
|
+
)
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
Call onCommit during setup. Its read function tracks state and compares the result with the last applied value using Object.is. The untracked apply callback receives the value and the previous applied value, which is undefined on mount. It runs after ref publication, mount callbacks, controlled form restoration, and capability commits. A flush inside a controlled form handler defers apply until restoration can finish. Children run before parents, with sibling callbacks in setup order.
|
|
259
|
+
|
|
260
|
+
A cleanup returned by apply runs before the next apply and when the owner is disposed. State writes from apply drain in another round of the same flush. Development detects feedback loops and reports the callback's registration stack. Scene callbacks run after host updates. Server rendering skips both callbacks, and scopes retained for exit skip apply while absent.
|
|
182
261
|
|
|
183
262
|
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.
|
|
184
263
|
|
|
@@ -229,15 +308,23 @@ export function TimelineExample(): SpaElement {
|
|
|
229
308
|
|
|
230
309
|
```
|
|
231
310
|
|
|
232
|
-
Arrays support keyed components and elements. Reordering preserves instances and nodes; removed ranges release subscriptions, events, refs, and cleanup callbacks. Application keys must be unique among siblings. Explicit keys are compared as strings; unkeyed positions occupy a separate namespace. Unkeyed arrays use positions. A key identifies a row in a reactive child collection; it is not an independent reactive binding.
|
|
233
|
-
|
|
234
311
|
HTML and SVG use native DOM properties and attributes, plus className/htmlFor aliases. Events use onClick/onInput-style names, with Capture suffixes and onDoubleClick support. Styles are CSS strings. Mutable atom values still invalidate their consumers; project primitive fields for precise DOM writes. Refs attach once per element instance.
|
|
235
312
|
|
|
236
313
|
HTML and SVG tags have element-specific attribute, event, and ref types. Event handlers receive native events with currentTarget typed as the attached element; target remains EventTarget because events can bubble from descendants. Ref callbacks receive the element on attachment and null on cleanup. Hyphenated custom tags use generic HTML attributes and HTMLElement refs and event targets. SVG presentation attributes use their literal markup spellings. Shared HTML/SVG tag names use HTML types because JSX cannot infer a namespace from parent elements.
|
|
237
314
|
|
|
315
|
+
Non-null value and checked props control form state: rejected edits are restored after native handlers run, and select values are reapplied after option updates. Use defaultValue/defaultChecked for uncontrolled fields. onChange follows native input events for text, number, range inputs and textareas; selects, checkboxes, radios, and file inputs use native change events. Handlers still receive native events. onFocus/onBlur bubble through focusin/focusout, including Capture variants; explicit onFocusIn/onFocusOut names remain available. autoFocus focuses newly mounted elements. Null or undefined reflected attributes are removed.
|
|
316
|
+
|
|
317
|
+
## Component identity
|
|
318
|
+
|
|
319
|
+
Keys accept the same Canonical values as atom.io families, including nested tuples, booleans, and null. Sibling keys must be unique by canonical serialization. A fresh tuple with the same contents preserves the instance, and a number and its string representation identify separate instances. Only undefined uses positional identity. Reordering preserves keyed instances and nodes. Changing a key replaces the instance in both DOM and scene trees, including when the element stands alone.
|
|
320
|
+
|
|
321
|
+
A component can declare a required, narrowed key in its props. The instance receives the original key by reference and can read props.key during setup, rendering, mount, and cleanup. Spreading the props forwards the key to an inner component or element. A spread follows normal JSX precedence, so forwarding the same key to multiple siblings reports a duplicate key.
|
|
322
|
+
|
|
323
|
+
Direct DOM component and root output opt into key tracking when they first mount. Include the key property initially when a direct spread needs later identity changes. An explicit key attribute or a spread containing key with an initial undefined value enables that tracking. Keyless spreads keep their data props live as the instance updates.
|
|
324
|
+
|
|
238
325
|
## Store access
|
|
239
326
|
|
|
240
|
-
useStore returns the
|
|
327
|
+
useStore returns the nearest Root boundary's atom.io store. When no boundary supplies one, it returns the store supplied to the renderer, the Astro island store, or the implicit atom.io store.
|
|
241
328
|
|
|
242
329
|
```tsx
|
|
243
330
|
import type { SpaElement } from "@atom.io/spa"
|
|
@@ -264,6 +351,53 @@ export function InspectCount(): SpaElement {
|
|
|
264
351
|
|
|
265
352
|
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.
|
|
266
353
|
|
|
354
|
+
### Subtree root options
|
|
355
|
+
|
|
356
|
+
Render a Root boundary around each editor to give it a separate store with the document token installed in both stores.
|
|
357
|
+
|
|
358
|
+
```tsx
|
|
359
|
+
import type { SpaElement } from "@atom.io/spa"
|
|
360
|
+
import { Root, useGetter, useSetter } from "@atom.io/spa"
|
|
361
|
+
import { atom } from "atom.io"
|
|
362
|
+
import type { RootStore } from "atom.io/internal"
|
|
363
|
+
|
|
364
|
+
export const textAtom = atom<string>({ key: `text`, default: `` })
|
|
365
|
+
|
|
366
|
+
function Editor() {
|
|
367
|
+
const getText = useGetter(textAtom)
|
|
368
|
+
const setText = useSetter(textAtom)
|
|
369
|
+
return (
|
|
370
|
+
<textarea
|
|
371
|
+
value={getText()}
|
|
372
|
+
onInput={(event) => {
|
|
373
|
+
setText(event.currentTarget.value)
|
|
374
|
+
}}
|
|
375
|
+
/>
|
|
376
|
+
)
|
|
377
|
+
}
|
|
378
|
+
|
|
379
|
+
export function Documents(props: {
|
|
380
|
+
left: RootStore
|
|
381
|
+
right: RootStore
|
|
382
|
+
}): SpaElement {
|
|
383
|
+
return (
|
|
384
|
+
<>
|
|
385
|
+
<Root store={props.left}>
|
|
386
|
+
<Editor />
|
|
387
|
+
</Root>
|
|
388
|
+
<Root store={props.right}>
|
|
389
|
+
<Editor />
|
|
390
|
+
</Root>
|
|
391
|
+
</>
|
|
392
|
+
)
|
|
393
|
+
}
|
|
394
|
+
|
|
395
|
+
```
|
|
396
|
+
|
|
397
|
+
Root shares its parent's scheduler and uses normal child markers and adds no DOM element. Components passed as children bind their hooks to the store where they mount. The boundary captures options at setup, so give it a new key to replace its store. Removing the boundary releases owned subscriptions and refs. The borrowed store remains available.
|
|
398
|
+
|
|
399
|
+
Omitted options inherit from the parent. An idPrefix override uses the root's shared ID sequence. A capabilities list replaces the inherited list within the subtree and shares the root's update and presence coordination. An onError override receives asynchronous errors from the subtree under the usual root failure policy. Scene mounts inherit these options. For SSR and hydration, supply equivalent boundary options and store state on both sides.
|
|
400
|
+
|
|
267
401
|
## Families
|
|
268
402
|
|
|
269
403
|
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.
|
|
@@ -283,11 +417,11 @@ const historyTimelines = timelineFamily<string>({
|
|
|
283
417
|
scope: [scopeFamily(countAtoms, { timelineKey: (id) => id })],
|
|
284
418
|
})
|
|
285
419
|
|
|
286
|
-
|
|
287
|
-
const getCount = useGetter(countAtoms, props.
|
|
288
|
-
const setCount = useSetter(countAtoms, props.
|
|
289
|
-
const ref = useRef(buttonAtoms, props.
|
|
290
|
-
const history = useTimeline(historyTimelines, props.
|
|
420
|
+
function FamilyCounter(props: { key: string }): SpaElement {
|
|
421
|
+
const getCount = useGetter(countAtoms, props.key)
|
|
422
|
+
const setCount = useSetter(countAtoms, props.key)
|
|
423
|
+
const ref = useRef(buttonAtoms, props.key)
|
|
424
|
+
const history = useTimeline(historyTimelines, props.key)
|
|
291
425
|
return (
|
|
292
426
|
<section>
|
|
293
427
|
<button
|
|
@@ -305,9 +439,19 @@ export function FamilyCounter(props: { id: string }): SpaElement {
|
|
|
305
439
|
)
|
|
306
440
|
}
|
|
307
441
|
|
|
442
|
+
export function Counters(props: { ids: readonly string[] }): SpaElement {
|
|
443
|
+
return (
|
|
444
|
+
<section>
|
|
445
|
+
{props.ids.map((id) => (
|
|
446
|
+
<FamilyCounter key={id} />
|
|
447
|
+
))}
|
|
448
|
+
</section>
|
|
449
|
+
)
|
|
450
|
+
}
|
|
451
|
+
|
|
308
452
|
```
|
|
309
453
|
|
|
310
|
-
|
|
454
|
+
Use props.key as the family key to keep the binding and the component's identity in sync. When the key changes, the new instance binds to the new member during setup. A tuple can include a family key alongside a discriminator when the same member appears more than once among siblings. Ref ownership and subscription cleanup follow the member just as they do for individual tokens. useTransaction takes an individual transaction token.
|
|
311
455
|
|
|
312
456
|
### Ambient UI state and ownership
|
|
313
457
|
|
|
@@ -480,7 +624,7 @@ The production build omits development-only diagnostics and invalid-input checks
|
|
|
480
624
|
|
|
481
625
|
## Astro state and data
|
|
482
626
|
|
|
483
|
-
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.
|
|
627
|
+
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. Lazy JSX attributes preserve this from their enclosing function, including through nested arrows and receiver tags. Nested normal functions and methods retain their own receiver. Direct await and yield expressions in lazy attributes are compile errors naming the attribute; nested async and generator functions remain supported.
|
|
484
628
|
|
|
485
629
|
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.
|
|
486
630
|
|
|
@@ -546,7 +690,7 @@ The checked Astro fixture demonstrates default/named slots and custom independen
|
|
|
546
690
|
|
|
547
691
|
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.
|
|
548
692
|
|
|
549
|
-
The hard budget is under
|
|
693
|
+
The hard budget is under 6,250 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 6.2 kB with gzip. The exact measurements appear in dist/size.json. Actual application bundles add atom.io and compiler-generated application code.
|
|
550
694
|
|
|
551
695
|
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.
|
|
552
696
|
|
|
@@ -578,11 +722,11 @@ Sizes are exact minified and level-9 gzip JavaScript byte counts. Declarations,
|
|
|
578
722
|
|
|
579
723
|
| Recipe | Entry | Minified JS | Gzip JS |
|
|
580
724
|
| -------------------------------- | --------------------------------- | ----------: | -------: |
|
|
581
|
-
| Family app with refs and history | `tonnage-recipes/family-app.ts` |
|
|
582
|
-
| Async interactive client app | `tonnage-recipes/async-app.ts` |
|
|
583
|
-
| Interactive client app | `tonnage-recipes/client-app.ts` |
|
|
584
|
-
| Hydrated interactive app | `tonnage-recipes/hydrated-app.ts` |
|
|
585
|
-
| Interactive Astro island | `tonnage-recipes/astro-island.ts` |
|
|
725
|
+
| Family app with refs and history | `tonnage-recipes/family-app.ts` | 68,795 B | 20,876 B |
|
|
726
|
+
| Async interactive client app | `tonnage-recipes/async-app.ts` | 47,231 B | 15,111 B |
|
|
727
|
+
| Interactive client app | `tonnage-recipes/client-app.ts` | 46,904 B | 14,961 B |
|
|
728
|
+
| Hydrated interactive app | `tonnage-recipes/hydrated-app.ts` | 46,905 B | 14,959 B |
|
|
729
|
+
| Interactive Astro island | `tonnage-recipes/astro-island.ts` | 53,443 B | 17,026 B |
|
|
586
730
|
|
|
587
731
|
Report maintained with [tonnage](https://github.com/jeremybanka/tonnage).
|
|
588
732
|
|
|
@@ -596,7 +740,7 @@ SPA includes Konva, Three.js, and Motion integrations behind separate entrypoint
|
|
|
596
740
|
|
|
597
741
|
### Konva
|
|
598
742
|
|
|
599
|
-
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
|
|
743
|
+
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 mouse, pointer, touch, wheel, context-menu, drag, and transform handlers are supported with typed native Konva events and node-specific currentTarget values. Use onDblClick/onDblTap for double clicks/taps. Both onGotPointerCapture and onLostPointerCapture expose PointerEvent values. onTransformEnd may receive an undefined evt when stopTransform() ends a transform programmatically; check evt before reading native event fields. Handler names and configuration fields are checked for misspellings. Refs receive native nodes and null on cleanup. Removal destroys owned nodes and listeners.
|
|
600
744
|
|
|
601
745
|
```tsx
|
|
602
746
|
import type { SpaElement } from "@atom.io/spa"
|
|
@@ -669,7 +813,7 @@ export function Scene(): SpaElement {
|
|
|
669
813
|
|
|
670
814
|
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
815
|
|
|
672
|
-
Constructor args are fixed for an instance.
|
|
816
|
+
Constructor args are fixed for an instance. Change the resource's key to replace it with new constructor args. 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.
|
|
673
817
|
|
|
674
818
|
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
819
|
|
|
@@ -812,7 +956,7 @@ export function SpringCube(): SpaElement {
|
|
|
812
956
|
|
|
813
957
|
```
|
|
814
958
|
|
|
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.
|
|
959
|
+
When the motion capability is installed, Canvas draws in Motion's post-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. The optional Motion entrypoint owns the retention machinery. The client budget includes controlled form restoration and native event normalization. The full client budget is 5,500 bytes.
|
|
816
960
|
|
|
817
961
|
### Exit animations and re-entry
|
|
818
962
|
|
package/README.mdx
CHANGED
|
@@ -10,7 +10,13 @@ import ConfigurableCanvas from "./exhibits/configurable-canvas.tsx" with {
|
|
|
10
10
|
import { Tonnage } from "tonnage";
|
|
11
11
|
import config from "./tonnage.config.ts";
|
|
12
12
|
import StoreExample from "./exhibits/store.tsx" with { type: "code" };
|
|
13
|
+
import RootBoundaryExample from "./exhibits/root-boundary.tsx" with {
|
|
14
|
+
type: "code",
|
|
15
|
+
};
|
|
16
|
+
import CommitExample from "./exhibits/hooks/on-commit.tsx" with { type: "code" };
|
|
13
17
|
import Families from "./exhibits/families.tsx" with { type: "code" };
|
|
18
|
+
import HotState from "./exhibits/hmr-state.ts" with { type: "code" };
|
|
19
|
+
import HotView from "./exhibits/hmr-view.tsx" with { type: "code" };
|
|
14
20
|
import TimelineExample from "./exhibits/timeline.tsx" with { type: "code" };
|
|
15
21
|
import LoadableExample from "./exhibits/loadable.tsx" with { type: "code" };
|
|
16
22
|
import Point from "./exhibits/point.tsx" with { type: "code" };
|
|
@@ -48,7 +54,7 @@ import FloatingExample from "./exhibits/floating.tsx" with { type: "code" };
|
|
|
48
54
|
|
|
49
55
|
An experimental JSX framework whose state engine is atom.io. Components run once per mounted instance. Calls to accessors inside compiled JSX subscribe the affected DOM computations; atom.io updates those computations without rerunning component setup.
|
|
50
56
|
|
|
51
|
-
The npm package is named @atom.io/spa. Its browser runtime, Vite compiler, server renderer, and Astro integration are implemented here.
|
|
57
|
+
The npm package is named @atom.io/spa. Its browser runtime, Vite compiler, server renderer, and Astro integration are implemented here. State and general reactions belong to atom.io.
|
|
52
58
|
|
|
53
59
|
## Start with the Astro template
|
|
54
60
|
|
|
@@ -94,7 +100,19 @@ Add a host element in index.html, then mount the same counter from main.tsx:
|
|
|
94
100
|
|
|
95
101
|
<Main />
|
|
96
102
|
|
|
97
|
-
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.
|
|
103
|
+
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. Component-only JSX modules refresh affected roots against their existing atom.io stores; production builds omit hot registration. Components and render computations are synchronous. Modern browsers with ES2022 and DOM Range support are the target.
|
|
104
|
+
|
|
105
|
+
Hot updates rerun affected roots, including scene roots and independent Astro islands, with the same store and props source. Old scopes release subscriptions, listeners, refs, and onCleanup callbacks before replacement. Atoms, persistent family members, and timeline history remain; DOM-local values and component-owned family members disposed by cleanup reset. A failed hot setup displays an error while keeping its store available for the next edit.
|
|
106
|
+
|
|
107
|
+
Keep state definitions and Astro store factories in separate modules from component-only views. State declarations, mixed runtime exports, re-exports, changed export boundaries, and top-level side effects use full reloads. Type-only exports are allowed. The first implementation refreshes complete roots rather than replacing individual component instances.
|
|
108
|
+
|
|
109
|
+
Define persistent tokens in their own state module:
|
|
110
|
+
|
|
111
|
+
<HotState />
|
|
112
|
+
|
|
113
|
+
Import the token from a component-only view. Editing this view's JSX or handler preserves the counter value:
|
|
114
|
+
|
|
115
|
+
<HotView />
|
|
98
116
|
|
|
99
117
|
## Hooks
|
|
100
118
|
|
|
@@ -102,43 +120,72 @@ The development plugin keeps SPA and atom.io outside dependency prebundling so r
|
|
|
102
120
|
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
103
121
|
| useLoadable(token, fallback?) | Return a tracked accessor for loading, last-observed values, and handled errors. |
|
|
104
122
|
| 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
|
|
123
|
+
| useDisposal() | Return atom.io state disposal bound to the current store. |
|
|
106
124
|
| useSetter(token) | Return a stable atom.io writer. |
|
|
107
125
|
| useTimeline(token) | Return a stable object with getCursor/getLength readers, undo/redo/clear commands, and transaction-group controls. |
|
|
108
126
|
| useTransaction(token) | Bind an atom.io transaction, preserving its arguments and result. |
|
|
109
127
|
| useRef(token) | Return an attachment callback for a nullable element atom. Clear it only while this attachment still owns the reference. |
|
|
110
|
-
| useId() | Allocate an instance-stable ID using the root's
|
|
128
|
+
| useId() | Allocate an instance-stable ID using the current prefix and the root's shared sequence. |
|
|
111
129
|
| onCleanup(callback) | Register synchronous teardown with the current owner. |
|
|
112
130
|
| onMount(callback) | Run once after attachment and ref publication; omitted during server rendering. |
|
|
113
|
-
|
|
|
131
|
+
| onCommit(read, apply) | Track a value and apply changes after renderer writes, within the same flush. |
|
|
132
|
+
| useStore() | Return the current atom.io store without creating a store or subscribing. |
|
|
133
|
+
|
|
134
|
+
Call setup helpers synchronously during component setup or owned mount callbacks. Capture their results for event handlers. Tokens are fixed for an instance. Change the component's key when it needs to bind a different token. Read data props through the props object in JSX or a tracked binding to get updates. Destructuring data props during setup takes a snapshot.
|
|
135
|
+
|
|
136
|
+
### onCommit
|
|
137
|
+
|
|
138
|
+
Use onCommit to measure a ref after the root finishes its DOM writes.
|
|
139
|
+
|
|
140
|
+
<CommitExample />
|
|
114
141
|
|
|
115
|
-
Call setup
|
|
142
|
+
Call onCommit during setup. Its read function tracks state and compares the result with the last applied value using Object.is. The untracked apply callback receives the value and the previous applied value, which is undefined on mount. It runs after ref publication, mount callbacks, controlled form restoration, and capability commits. A flush inside a controlled form handler defers apply until restoration can finish. Children run before parents, with sibling callbacks in setup order.
|
|
143
|
+
|
|
144
|
+
A cleanup returned by apply runs before the next apply and when the owner is disposed. State writes from apply drain in another round of the same flush. Development detects feedback loops and reports the callback's registration stack. Scene callbacks run after host updates. Server rendering skips both callbacks, and scopes retained for exit skip apply while absent.
|
|
116
145
|
|
|
117
146
|
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.
|
|
118
147
|
|
|
119
148
|
<TimelineExample />
|
|
120
149
|
|
|
121
|
-
Arrays support keyed components and elements. Reordering preserves instances and nodes; removed ranges release subscriptions, events, refs, and cleanup callbacks. Application keys must be unique among siblings. Explicit keys are compared as strings; unkeyed positions occupy a separate namespace. Unkeyed arrays use positions. A key identifies a row in a reactive child collection; it is not an independent reactive binding.
|
|
122
|
-
|
|
123
150
|
HTML and SVG use native DOM properties and attributes, plus className/htmlFor aliases. Events use onClick/onInput-style names, with Capture suffixes and onDoubleClick support. Styles are CSS strings. Mutable atom values still invalidate their consumers; project primitive fields for precise DOM writes. Refs attach once per element instance.
|
|
124
151
|
|
|
125
152
|
HTML and SVG tags have element-specific attribute, event, and ref types. Event handlers receive native events with currentTarget typed as the attached element; target remains EventTarget because events can bubble from descendants. Ref callbacks receive the element on attachment and null on cleanup. Hyphenated custom tags use generic HTML attributes and HTMLElement refs and event targets. SVG presentation attributes use their literal markup spellings. Shared HTML/SVG tag names use HTML types because JSX cannot infer a namespace from parent elements.
|
|
126
153
|
|
|
154
|
+
Non-null value and checked props control form state: rejected edits are restored after native handlers run, and select values are reapplied after option updates. Use defaultValue/defaultChecked for uncontrolled fields. onChange follows native input events for text, number, range inputs and textareas; selects, checkboxes, radios, and file inputs use native change events. Handlers still receive native events. onFocus/onBlur bubble through focusin/focusout, including Capture variants; explicit onFocusIn/onFocusOut names remain available. autoFocus focuses newly mounted elements. Null or undefined reflected attributes are removed.
|
|
155
|
+
|
|
156
|
+
## Component identity
|
|
157
|
+
|
|
158
|
+
Keys accept the same Canonical values as atom.io families, including nested tuples, booleans, and null. Sibling keys must be unique by canonical serialization. A fresh tuple with the same contents preserves the instance, and a number and its string representation identify separate instances. Only undefined uses positional identity. Reordering preserves keyed instances and nodes. Changing a key replaces the instance in both DOM and scene trees, including when the element stands alone.
|
|
159
|
+
|
|
160
|
+
A component can declare a required, narrowed key in its props. The instance receives the original key by reference and can read props.key during setup, rendering, mount, and cleanup. Spreading the props forwards the key to an inner component or element. A spread follows normal JSX precedence, so forwarding the same key to multiple siblings reports a duplicate key.
|
|
161
|
+
|
|
162
|
+
Direct DOM component and root output opt into key tracking when they first mount. Include the key property initially when a direct spread needs later identity changes. An explicit key attribute or a spread containing key with an initial undefined value enables that tracking. Keyless spreads keep their data props live as the instance updates.
|
|
163
|
+
|
|
127
164
|
## Store access
|
|
128
165
|
|
|
129
|
-
useStore returns the
|
|
166
|
+
useStore returns the nearest Root boundary's atom.io store. When no boundary supplies one, it returns the store supplied to the renderer, the Astro island store, or the implicit atom.io store.
|
|
130
167
|
|
|
131
168
|
<StoreExample />
|
|
132
169
|
|
|
133
170
|
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.
|
|
134
171
|
|
|
172
|
+
### Subtree root options
|
|
173
|
+
|
|
174
|
+
Render a Root boundary around each editor to give it a separate store with the document token installed in both stores.
|
|
175
|
+
|
|
176
|
+
<RootBoundaryExample />
|
|
177
|
+
|
|
178
|
+
Root shares its parent's scheduler and uses normal child markers and adds no DOM element. Components passed as children bind their hooks to the store where they mount. The boundary captures options at setup, so give it a new key to replace its store. Removing the boundary releases owned subscriptions and refs. The borrowed store remains available.
|
|
179
|
+
|
|
180
|
+
Omitted options inherit from the parent. An idPrefix override uses the root's shared ID sequence. A capabilities list replaces the inherited list within the subtree and shares the root's update and presence coordination. An onError override receives asynchronous errors from the subtree under the usual root failure policy. Scene mounts inherit these options. For SSR and hydration, supply equivalent boundary options and store state on both sides.
|
|
181
|
+
|
|
135
182
|
## Families
|
|
136
183
|
|
|
137
184
|
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.
|
|
138
185
|
|
|
139
186
|
<Families />
|
|
140
187
|
|
|
141
|
-
|
|
188
|
+
Use props.key as the family key to keep the binding and the component's identity in sync. When the key changes, the new instance binds to the new member during setup. A tuple can include a family key alongside a discriminator when the same member appears more than once among siblings. Ref ownership and subscription cleanup follow the member just as they do for individual tokens. useTransaction takes an individual transaction token.
|
|
142
189
|
|
|
143
190
|
### Ambient UI state and ownership
|
|
144
191
|
|
|
@@ -176,7 +223,7 @@ The production build omits development-only diagnostics and invalid-input checks
|
|
|
176
223
|
|
|
177
224
|
## Astro state and data
|
|
178
225
|
|
|
179
|
-
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.
|
|
226
|
+
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. Lazy JSX attributes preserve this from their enclosing function, including through nested arrows and receiver tags. Nested normal functions and methods retain their own receiver. Direct await and yield expressions in lazy attributes are compile errors naming the attribute; nested async and generator functions remain supported.
|
|
180
227
|
|
|
181
228
|
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.
|
|
182
229
|
|
|
@@ -208,7 +255,7 @@ The checked Astro fixture demonstrates default/named slots and custom independen
|
|
|
208
255
|
|
|
209
256
|
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.
|
|
210
257
|
|
|
211
|
-
The hard budget is under
|
|
258
|
+
The hard budget is under 6,250 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 6.2 kB with gzip. The exact measurements appear in dist/size.json. Actual application bundles add atom.io and compiler-generated application code.
|
|
212
259
|
|
|
213
260
|
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.
|
|
214
261
|
|
|
@@ -232,7 +279,7 @@ SPA includes Konva, Three.js, and Motion integrations behind separate entrypoint
|
|
|
232
279
|
|
|
233
280
|
### Konva
|
|
234
281
|
|
|
235
|
-
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
|
|
282
|
+
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 mouse, pointer, touch, wheel, context-menu, drag, and transform handlers are supported with typed native Konva events and node-specific currentTarget values. Use onDblClick/onDblTap for double clicks/taps. Both onGotPointerCapture and onLostPointerCapture expose PointerEvent values. onTransformEnd may receive an undefined evt when stopTransform() ends a transform programmatically; check evt before reading native event fields. Handler names and configuration fields are checked for misspellings. Refs receive native nodes and null on cleanup. Removal destroys owned nodes and listeners.
|
|
236
283
|
|
|
237
284
|
<KonvaExample />
|
|
238
285
|
|
|
@@ -246,7 +293,7 @@ Import Canvas, Group, Mesh, PerspectiveCamera, AmbientLight, DirectionalLight, B
|
|
|
246
293
|
|
|
247
294
|
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
295
|
|
|
249
|
-
Constructor args are fixed for an instance.
|
|
296
|
+
Constructor args are fixed for an instance. Change the resource's key to replace it with new constructor args. 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.
|
|
250
297
|
|
|
251
298
|
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
299
|
|
|
@@ -284,7 +331,7 @@ The same attributes animate numeric Konva properties and colors, or Three.js pos
|
|
|
284
331
|
|
|
285
332
|
<MotionThree />
|
|
286
333
|
|
|
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.
|
|
334
|
+
When the motion capability is installed, Canvas draws in Motion's post-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. The optional Motion entrypoint owns the retention machinery. The client budget includes controlled form restoration and native event normalization. The full client budget is 5,500 bytes.
|
|
288
335
|
|
|
289
336
|
### Exit animations and re-entry
|
|
290
337
|
|
package/dist/astro-client.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { a as Island, i as AstroStorePreparation } from "./astro-shared-
|
|
1
|
+
import { a as Island, i as AstroStorePreparation } from "./astro-shared-KxK9OUSj.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 +1 @@
|
|
|
1
|
-
{"version":3,"file":"astro-client.d.ts","names":[],"sources":["../src/astro-client.ts"],"mappings":";
|
|
1
|
+
{"version":3,"file":"astro-client.d.ts","names":[],"sources":["../src/astro-client.ts"],"mappings":";KAmBK,QAAQ;KACR,QAAQ;KACR,YACJ,WAAW,QACX,OAAO,OACP,OAAO,OACP;EAAY;MACR;qBAcQ,iBAAc,UACf,2BAAqB,SACtB,gBAAc;cAAd,WAAA,SAAA,gBAAc"}
|
package/dist/astro-client.js
CHANGED
|
@@ -1,8 +1,9 @@
|
|
|
1
1
|
import { browserApplication } from "./astro-application.js";
|
|
2
2
|
import { n as failPreparation, r as storeContext } from "./astro-context-OdlexHR4.js";
|
|
3
|
-
import { n as islandStore, t as island } from "./astro-shared-
|
|
4
|
-
import {
|
|
5
|
-
import { n as render, t as hydrate } from "./dom
|
|
3
|
+
import { n as islandStore, t as island } from "./astro-shared-DBwINQav.js";
|
|
4
|
+
import { b as useGetter } from "./core-DD2giR6E.js";
|
|
5
|
+
import { n as render, t as hydrate } from "./dom--HZvmgqd.js";
|
|
6
|
+
import { onRootDispose } from "./hot.js";
|
|
6
7
|
import { IMPLICIT, createRegularAtomFamily, disposeFromStore, findInStore, getFromStore, setIntoStore } from "atom.io/internal";
|
|
7
8
|
// src/astro-client.ts
|
|
8
9
|
const roots = /* @__PURE__ */ new WeakMap();
|
|
@@ -60,7 +61,7 @@ const createHydrator = (prepare) => (element) => async (component, props, slots,
|
|
|
60
61
|
disposeFromStore(store, state);
|
|
61
62
|
});
|
|
62
63
|
const mount = () => {
|
|
63
|
-
|
|
64
|
+
onRootDispose(dispose);
|
|
64
65
|
const getState = useGetter(state);
|
|
65
66
|
return () => island(component, getState().props, getState().slots);
|
|
66
67
|
};
|
package/dist/astro-client.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"astro-client.js","names":[],"sources":["../src/astro-client.ts"],"sourcesContent":["import type { ReadableToken, RegularAtomFamilyToken } from \"atom.io\"\nimport type { RootStore } from \"atom.io/internal\"\nimport {\n\tcreateRegularAtomFamily,\n\tdisposeFromStore,\n\tfindInStore,\n\tgetFromStore,\n\tIMPLICIT,\n\tsetIntoStore,\n} from \"atom.io/internal\"\n\nimport { browserApplication } from \"./astro-application.ts\"\nimport { failPreparation, storeContext } from \"./astro-context.ts\"\nimport type { AstroStorePreparation, Island } from \"./astro-shared.ts\"\nimport { island, islandStore } from \"./astro-shared.ts\"\nimport {
|
|
1
|
+
{"version":3,"file":"astro-client.js","names":[],"sources":["../src/astro-client.ts"],"sourcesContent":["import type { ReadableToken, RegularAtomFamilyToken } from \"atom.io\"\nimport type { RootStore } from \"atom.io/internal\"\nimport {\n\tcreateRegularAtomFamily,\n\tdisposeFromStore,\n\tfindInStore,\n\tgetFromStore,\n\tIMPLICIT,\n\tsetIntoStore,\n} from \"atom.io/internal\"\n\nimport { browserApplication } from \"./astro-application.ts\"\nimport { failPreparation, storeContext } from \"./astro-context.ts\"\nimport type { AstroStorePreparation, Island } from \"./astro-shared.ts\"\nimport { island, islandStore } from \"./astro-shared.ts\"\nimport { useGetter } from \"./core.ts\"\nimport { hydrate, render } from \"./dom.ts\"\nimport { onRootDispose } from \"./hot.ts\"\n\ntype Props = Record<string, any>\ntype Slots = Record<string, string>\ntype Hydrator = (\n\tcomponent: Island,\n\tprops: Props,\n\tslots: Slots,\n\tmetadata: { client: string },\n) => Promise<void>\nconst roots = new WeakMap<\n\tElement,\n\t{\n\t\tcomponent: Island\n\t\tready: Promise<void>\n\t\tupdate(props: Props, slots: Slots): void\n\t\tdispose(): void\n\t}\n>()\ntype State = { props: Props; slots: Slots }\nconst states = new WeakMap<RootStore, RegularAtomFamilyToken<State, number>>()\nlet serial = 0\n\nexport const createHydrator =\n\t(prepare?: AstroStorePreparation) =>\n\t(element: HTMLElement): Hydrator =>\n\tasync (component, props, slots, { client }) => {\n\t\tconst previous = roots.get(element)\n\t\tif (previous?.component === component) {\n\t\t\tprevious.update(props, slots)\n\t\t\treturn previous.ready\n\t\t}\n\t\tprevious?.dispose()\n\t\tconst shared = !component.createStore && !component.isolate\n\t\tconst application = shared\n\t\t\t? browserApplication(element.ownerDocument)\n\t\t\t: undefined\n\t\tif (application && client === `only`) application.canResume = false\n\t\tconst lifetime = storeContext(element, application)\n\t\tconst initial = { props, slots }\n\t\tlet current = initial\n\t\tlet update: ((value: State) => void) | undefined\n\t\tlet disposed = false\n\t\tconst dispose = () => {\n\t\t\tif (disposed) return\n\t\t\tdisposed = true\n\t\t\telement.removeEventListener(`astro:unmount`, dispose)\n\t\t\troots.delete(element)\n\t\t\tlifetime.dispose()\n\t\t}\n\t\t// Publish the pending owner before invoking user code. Repeated hydration\n\t\t// calls update its props and share its preparation rather than racing stores.\n\t\tconst ready = Promise.resolve().then(async () => {\n\t\t\tif (lifetime.context.signal.aborted) return\n\t\t\tlet mounting = false\n\t\t\ttry {\n\t\t\t\tconst store = await Promise.race([\n\t\t\t\t\tislandStore(\n\t\t\t\t\t\tcomponent,\n\t\t\t\t\t\tprops,\n\t\t\t\t\t\tlifetime.context,\n\t\t\t\t\t\tshared ? IMPLICIT.STORE : undefined,\n\t\t\t\t\t\tprepare,\n\t\t\t\t\t),\n\t\t\t\t\tlifetime.cancelled,\n\t\t\t\t])\n\t\t\t\tif (lifetime.context.signal.aborted) return\n\t\t\t\tmounting = true\n\t\t\t\tconst replace =\n\t\t\t\t\tclient === `only` ||\n\t\t\t\t\tprevious !== undefined ||\n\t\t\t\t\tapplication?.canResume === false ||\n\t\t\t\t\t// Server-settled state without a synchronous browser seed needs a\n\t\t\t\t\t// fresh view, whose loading state can differ from the SSR markup.\n\t\t\t\t\t(\n\t\t\t\t\t\tJSON.parse(\n\t\t\t\t\t\t\telement.getAttribute(`data-spa-reads`) ?? `[]`,\n\t\t\t\t\t\t) as ReadableToken<unknown>[]\n\t\t\t\t\t).some((token) => getFromStore(store!, token) instanceof Promise)\n\t\t\t\t// Astro leaves this sentinel on islands inserted by ClientRouter.\n\t\t\t\tconst sentinel = element.lastChild\n\t\t\t\tif (sentinel?.nodeType === 8 && sentinel.nodeValue === `astro:end`)\n\t\t\t\t\tsentinel.remove()\n\t\t\t\tlet family = states.get(store!)\n\t\t\t\tif (!family) {\n\t\t\t\t\tfamily = createRegularAtomFamily<State, number, never>(store!, {\n\t\t\t\t\t\tkey: `🔍 spa islands`,\n\t\t\t\t\t\tdefault: { props: {}, slots: {} },\n\t\t\t\t\t})\n\t\t\t\t\tstates.set(store!, family)\n\t\t\t\t}\n\t\t\t\tconst state = findInStore(store!, family, serial++)\n\t\t\t\tsetIntoStore(store!, state, replace ? current : initial)\n\t\t\t\tlifetime.context.onCleanup(() => {\n\t\t\t\t\tdisposeFromStore(store!, state)\n\t\t\t\t})\n\t\t\t\tconst mount = () => {\n\t\t\t\t\tonRootDispose(dispose)\n\t\t\t\t\tconst getState = useGetter(state)\n\t\t\t\t\treturn () => island(component, getState().props, getState().slots)\n\t\t\t\t}\n\t\t\t\tif (replace) element.replaceChildren()\n\t\t\t\tconst root = (replace ? render : hydrate)(mount, element, {\n\t\t\t\t\tstore: store!,\n\t\t\t\t\tcapabilities: component.capabilities ?? [],\n\t\t\t\t})\n\t\t\t\tlifetime.context.onCleanup(root.dispose)\n\t\t\t\tupdate = (next) => {\n\t\t\t\t\tsetIntoStore(store!, state, next)\n\t\t\t\t\troot.flush()\n\t\t\t\t}\n\t\t\t\t// Match the existing SSR tree before applying a structural prop update\n\t\t\t\t// that arrived while its store was still being prepared.\n\t\t\t\tif (!replace && current !== initial) update(current)\n\t\t\t} catch (error) {\n\t\t\t\tif (lifetime.context.signal.aborted && !mounting) return\n\t\t\t\tfailPreparation(error, dispose)\n\t\t\t}\n\t\t})\n\t\troots.set(element, {\n\t\t\tcomponent,\n\t\t\tready,\n\t\t\tupdate(nextProps, nextSlots) {\n\t\t\t\tcurrent = { props: nextProps, slots: nextSlots }\n\t\t\t\tupdate?.(current)\n\t\t\t},\n\t\t\tdispose,\n\t\t})\n\t\telement.addEventListener(`astro:unmount`, dispose, { once: true })\n\t\tlifetime.context.onCleanup(dispose)\n\t\treturn ready\n\t}\n\nexport default createHydrator()\n"],"mappings":";;;;;;;;AA2BA,MAAM,wBAAQ,IAAI,QAQhB;AAEF,MAAM,yBAAS,IAAI,QAA0D;AAC7E,IAAI,SAAS;AAEb,MAAa,kBACX,aACA,YACD,OAAO,WAAW,OAAO,OAAO,EAAE,aAAa;CAC9C,MAAM,WAAW,MAAM,IAAI,OAAO;CAClC,IAAI,UAAU,cAAc,WAAW;EACtC,SAAS,OAAO,OAAO,KAAK;EAC5B,OAAO,SAAS;CACjB;CACA,UAAU,QAAQ;CAClB,MAAM,SAAS,CAAC,UAAU,eAAe,CAAC,UAAU;CACpD,MAAM,cAAc,SACjB,mBAAmB,QAAQ,aAAa,IACxC,KAAA;CACH,IAAI,eAAe,WAAW,QAAQ,YAAY,YAAY;CAC9D,MAAM,WAAW,aAAa,SAAS,WAAW;CAClD,MAAM,UAAU;EAAE;EAAO;CAAM;CAC/B,IAAI,UAAU;CACd,IAAI;CACJ,IAAI,WAAW;CACf,MAAM,gBAAgB;EACrB,IAAI,UAAU;EACd,WAAW;EACX,QAAQ,oBAAoB,iBAAiB,OAAO;EACpD,MAAM,OAAO,OAAO;EACpB,SAAS,QAAQ;CAClB;CAGA,MAAM,QAAQ,QAAQ,QAAQ,CAAC,CAAC,KAAK,YAAY;EAChD,IAAI,SAAS,QAAQ,OAAO,SAAS;EACrC,IAAI,WAAW;EACf,IAAI;GACH,MAAM,QAAQ,MAAM,QAAQ,KAAK,CAChC,YACC,WACA,OACA,SAAS,SACT,SAAS,SAAS,QAAQ,KAAA,GAC1B,OACD,GACA,SAAS,SACV,CAAC;GACD,IAAI,SAAS,QAAQ,OAAO,SAAS;GACrC,WAAW;GACX,MAAM,UACL,WAAW,UACX,aAAa,KAAA,KACb,aAAa,cAAc,SAI1B,KAAK,MACJ,QAAQ,aAAa,gBAAgB,KAAK,IAC3C,CAAC,CACA,MAAM,UAAU,aAAa,OAAQ,KAAK,aAAa,OAAO;GAEjE,MAAM,WAAW,QAAQ;GACzB,IAAI,UAAU,aAAa,KAAK,SAAS,cAAc,aACtD,SAAS,OAAO;GACjB,IAAI,SAAS,OAAO,IAAI,KAAM;GAC9B,IAAI,CAAC,QAAQ;IACZ,SAAS,wBAA8C,OAAQ;KAC9D,KAAK;KACL,SAAS;MAAE,OAAO,CAAC;MAAG,OAAO,CAAC;KAAE;IACjC,CAAC;IACD,OAAO,IAAI,OAAQ,MAAM;GAC1B;GACA,MAAM,QAAQ,YAAY,OAAQ,QAAQ,QAAQ;GAClD,aAAa,OAAQ,OAAO,UAAU,UAAU,OAAO;GACvD,SAAS,QAAQ,gBAAgB;IAChC,iBAAiB,OAAQ,KAAK;GAC/B,CAAC;GACD,MAAM,cAAc;IACnB,cAAc,OAAO;IACrB,MAAM,WAAW,UAAU,KAAK;IAChC,aAAa,OAAO,WAAW,SAAS,CAAC,CAAC,OAAO,SAAS,CAAC,CAAC,KAAK;GAClE;GACA,IAAI,SAAS,QAAQ,gBAAgB;GACrC,MAAM,QAAQ,UAAU,SAAS,QAAA,CAAS,OAAO,SAAS;IAClD;IACP,cAAc,UAAU,gBAAgB,CAAC;GAC1C,CAAC;GACD,SAAS,QAAQ,UAAU,KAAK,OAAO;GACvC,UAAU,SAAS;IAClB,aAAa,OAAQ,OAAO,IAAI;IAChC,KAAK,MAAM;GACZ;GAGA,IAAI,CAAC,WAAW,YAAY,SAAS,OAAO,OAAO;EACpD,SAAS,OAAO;GACf,IAAI,SAAS,QAAQ,OAAO,WAAW,CAAC,UAAU;GAClD,gBAAgB,OAAO,OAAO;EAC/B;CACD,CAAC;CACD,MAAM,IAAI,SAAS;EAClB;EACA;EACA,OAAO,WAAW,WAAW;GAC5B,UAAU;IAAE,OAAO;IAAW,OAAO;GAAU;GAC/C,SAAS,OAAO;EACjB;EACA;CACD,CAAC;CACD,QAAQ,iBAAiB,iBAAiB,SAAS,EAAE,MAAM,KAAK,CAAC;CACjE,SAAS,QAAQ,UAAU,OAAO;CAClC,OAAO;AACR;AAED,IAAA,uBAAe,eAAe"}
|