Storage

The two tiers an environment keeps state in: the session it holds while it is open, and the interaction store that outlives the visit.

@internote/canvas-sdk24 exports

On this page

An environment declares the state it keeps in its definition's storage field (CanvasStorageDeclaration), in one of two tiers:

Session state lasts while the document is open. It survives the reader scrolling away and back, and is never saved. An environment written with continue: in a later scene takes it over.
Database state, with tiers: 'session+db', is saved per reader, for environments that record a reader's answers.

storage: {
    tiers: 'session',
    initState: () => ({ waves: 0 }),
},

Inside the environment, ctx.storage is the CanvasStorage the host assembled: session for the first tier and db for the second. In a surface, read the session with useEnvironmentSession from @internote/canvas-sdk/react.

One slot in the session tier belongs to a whole scene rather than an environment: its parameters, and whether its footer is open. A control may be written inside any environment or in the scene's own detail, and the parameter it declares is read by everything in the scene, so the state cannot sit in one environment's slot without that environment owning the others' sliders. SessionStore's forScene is that view, keyed by SceneIdentity; an environment reads it through ctx.parameters rather than reaching for the store. It is not carried by continue:, which hands one environment's state to another.

Keep in session state anything the reader changed that a picture of the environment should show — a switch thrown, a view panned — as plain data: numbers, strings, booleans, arrays and plain objects. An exported figure is a second host started from SessionStore's snapshot() of the first, and a snapshot takes only plain data: a slot holding a Map, a Set or a class instance is left out, and that environment starts the figure fresh. State held in a React ref or useState is not in the session at all, and never reaches the figure.

For a reading rather than state, such as where the cursor is or a scale bar, use a transient channel: createTransientValue for one reading per environment, or createTransientCollection for one per mark.

#Functions

createCanvasStorage

Assembles an environment's storage surface from its declaration and the host's backends, seeding the session state when the slot is empty.

createTransientCollection

Creates a channel carrying one reading per mark per environment, such as a legend row for each heatmap.

createTransientValue

Creates a channel carrying one reading per environment.

Returns the session-store key for an environment: its three ids joined by spaces.

keyValueFromInteractionStore

Adapts an InteractionStore into a KeyValueStorage scoped to one element hash.

prefixedKeyValueStorage

Returns a view of a key-value store that prefixes every key, so an environment's keys cannot collide with another's.

Returns the session-store key for a scene: its two ids, and a third field no environment can have.

#Classes

The session store one canvas host owns: every environment's and every scene's reading-session state, with per-slot subscribers.

#Constants

noopInteractionStore

An InteractionStore that keeps nothing: reads return null and saves resolve without storing.

noopKeyValueStorage

A KeyValueStorage that keeps nothing: get resolves to null and writes resolve without storing.

#Interfaces

The storage an environment sees as ctx.storage, assembled by the host from its declaration.

CanvasStorageDeclaration

The storage an environment asks for, in its definition's storage field.

EnvironmentIdentity

Where one canvas environment sits: the internote, the scene and the environment within it.

EnvironmentSessionState

A scoped view over the session store: one environment's state, or one scene's.

InteractionStore

Where elements keep a reader's interaction state, one value per element, keyed by the element's content hash.

KeyValueStorage

A durable key-value store, which an environment declaring tiers: 'session+db' receives as ctx.storage.db.

Where one scene sits: the internote and the scene within it.

TransientCollection

Several readings per environment, one per publishing mark.

One reading per environment: a cursor position, a scale bar, a focused mark.

#Types

How a publisher says which environment it is speaking for: the environment's context, its identity, or its store key.

Reads what one element stored, or null when it stored nothing.

SaveInteraction

Stores what one element wants kept, replacing whatever it stored before, and resolves once saved.

Which storage an environment asks for: 'session' for state that lasts while the page is open, or 'session+db' to also save each reader's work.

Decides whether a new reading says anything the old one did not, so subscribers are woken only for a real change.

Last updated 26 September 2026