Document observed (external) state and how it differs from authoritative and derived state #3

New issue

Open

opened 2026-10-18 06:43:41 +00:00 by orchestrator · 0 comments

orchestrator commented

2026-10-18 06:43:41 +00:00

Member

We settled on a continuum for application state and agreed not to add a library primitive. The guidance should live in Gooey's documentation rather than only in the demos.

The continuum

Authoritative — application- or user-provided data; anyone may write it; recorded/replayed by state history when it has an id.
Observed — environment-provided data (DOM measurements, the clock, window/media queries, network); writable only by the source that observes it; read like any field; never recorded or replayed.
Derived — computed from other state (calc/view); nobody may write it; never recorded.

Write access narrows along the continuum, and the value's origin shifts from application-provided to environment-provided to computed.

Pattern (no primitive)

Observed state is an anonymous field with a scoped writer. The app-level helper:

function observed(init, source) {
    const inner = field(init);
    const stop = source((value) => inner.set(value));
    return { get: () => inner.get(), subscribe: inner.subscribe, stop: () => stop?.() };
}

Rules:

The field must stay anonymous. Anonymous fields never register, so state history never sees them. Giving it an id makes it authoritative, shareable, and recordable — exactly what it must not be.
Only the source gets the writer; consumers get get/subscribe (it is still a Dynamic).
Start and stop the source with its owner; a ResizeObserver or interval left running is a leak.
Fields compare strictly: keep observed values primitive or compare before setting.
Never copy an observation into recorded state. A recorded measurement restored into the environment that produced it is a feedback loop.
If an observation must be replayed, copy it into authoritative state deliberately.

Reference cases

Circle Drawer viewport — measured by ResizeObserver, kept anonymous. If recorded, every scrub restores a stale measurement and records a new one.
Timer — duration/running are authoritative; the clock is observed; elapsed is derived. Recording ticks is neither useful nor replayable.
Other interval-driven demos (intrinsic-observer, teleportation, svg) — timer-driven toggles/ticks should be observed, not authoritative.

Part of the state-history spike (PR #1). The demos are being adjusted to follow this pattern; the docs should describe it once the API settles.

We settled on a continuum for application state and agreed not to add a library primitive. The guidance should live in Gooey's documentation rather than only in the demos. ## The continuum - **Authoritative** — application- or user-provided data; anyone may write it; recorded/replayed by state history when it has an id. - **Observed** — environment-provided data (DOM measurements, the clock, window/media queries, network); writable only by the source that observes it; read like any field; **never recorded or replayed**. - **Derived** — computed from other state (`calc`/view); nobody may write it; never recorded. Write access narrows along the continuum, and the value's origin shifts from application-provided to environment-provided to computed. ## Pattern (no primitive) Observed state is an anonymous `field` with a scoped writer. The app-level helper: ```ts function observed(init, source) { const inner = field(init); const stop = source((value) => inner.set(value)); return { get: () => inner.get(), subscribe: inner.subscribe, stop: () => stop?.() }; } ``` Rules: - The field must stay anonymous. Anonymous fields never register, so state history never sees them. Giving it an id makes it authoritative, shareable, and recordable — exactly what it must not be. - Only the source gets the writer; consumers get `get`/`subscribe` (it is still a `Dynamic`). - Start and stop the source with its owner; a `ResizeObserver` or interval left running is a leak. - Fields compare strictly: keep observed values primitive or compare before setting. - Never copy an observation into recorded state. A recorded measurement restored into the environment that produced it is a feedback loop. - If an observation must be replayed, copy it into authoritative state deliberately. ## Reference cases - **Circle Drawer viewport** — measured by `ResizeObserver`, kept anonymous. If recorded, every scrub restores a stale measurement and records a new one. - **Timer** — duration/running are authoritative; the clock is observed; elapsed is derived. Recording ticks is neither useful nor replayable. - **Other interval-driven demos** (`intrinsic-observer`, `teleportation`, `svg`) — timer-driven toggles/ticks should be observed, not authoritative. Part of the state-history spike (PR #1). The demos are being adjusted to follow this pattern; the docs should describe it once the API settles.

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

legend/gooey#3

No description provided.

Rows
Columns