Environments
The definition itself — what defineEnvironment takes, what the registry does with it, and the helpers a definition reads its own node tree with.
@internote/canvas-sdk#Functions
attrOf
One attribute's raw value, or undefined when the node does not write it.
(node: NodeLike, identifier: string): unknownattrsOf
A node's attributes as a plain map.
(node: NodeLike): Record<string, unknown>The RAW values, as the document carries them — a keyframe track arrives here as a track. For the momentary value at this point on the timeline, ask the runtime (ctx.animation.attrValuesOf), which resolves tracks against the step position first.
attrValues
Every value an attribute passes through across its choreography: a keyframe track's base and then each frame's value, in source order, or the one value of an attribute that does not move.
(value: unknown): unknown[]buildCanvasLibrary
Fold every registered environment into a copy of the base library: declares the
canvas.<name> environment nodes and their vocabularies, admits the environment nodes into the scene detail, and widens the cue family's child policies to the registered vocabularies (cues wrap the elements they animate).(base: ChalkLibrary): ChalkLibrarybuildInternoteLibrary
The internote vocabulary, composed with every environment registered AT CALL TIME — the
canvas.<name> nodes, their vocabularies, and the widened scene-detail and cue-family child policies.(): ChalkLibrarycanvasAttrInfo
The declared type and animatability of an attribute on an environment node or a vocabulary child.
(nodeIdentifier: string, attrIdentifier: string): CanvasAttrInfo | nullNull when the node is not canvas-registered or does not declare the attribute. Includes the universal continue, with its targets resolved against the registry. Drives post-compile refinement and animatability decisions.
canvasNodeAttributes
Every attribute a canvas environment node or vocabulary child declares, canonical name → spec.
(nodeIdentifier: string): Record<string, CanvasAttrSpec> | nullcanvasNodeIdentifier
Returns the node identifier authors write for an environment, so
graph gives canvas.graph; the inverse of environmentNameOf.(environmentName: string): stringcanvasUniversalAttributes
The universal specs, with
continue:'s targets resolved against the registry — they are the registered environment nodes, so they cannot be written down ahead of registration.(): Record<string, AttrSpec>canvasVocabulary
The child elements an environment admits, in declaration order.
(environmentName: string): string[]childNodes
A node's body as the child elements it holds.
<N extends NodeLike = CompiledNode>(content: unknown): N[]Not Array.isArray alone: a typed body (D33) may be an array of plain values — !sizes{1, 2, 3} is [1.0, 2.0, 3.0] — which is not a list of nodes and must not be walked as if it were. An element is what carries an identifier.
containsCueMicronode
Whether an attribute value contains
!cue.to or !cue.zoom keyframes, a quick text check made before the slower splitCueChain.(value: unknown): value is stringcontainsNode
Whether a node the match names is anywhere in the root's
body or detail, at any depth — inside a cue, a scene, another environment.<N extends NodeLike>(root: N | readonly N[], match: NodeMatch<N>): booleandefineEnvironment
Returns an environment definition unchanged, checked against its type at authoring time.
(def: EnvironmentDefinition): EnvironmentDefinitionexport default defineEnvironment({
name: 'graph',
vocabulary: { … },
Surface: GraphSurface,
});descendantNodes
Every element below the root — through
body and detail both, at any depth, cues and marks and nested environments alike — in document order, parents before their children.<N extends NodeLike>(root: N | readonly N[]): N[]environmentNameOf
Returns the environment name from a node identifier, so
canvas.graph gives graph, or null if the identifier is not an environment's.(identifier: string): string | nullenvironmentRefinerFor
The parser an environment registered for a declared value type, or
undefined where none did and ../refine's own table answers instead.(typeName: string): AttrRefiner | undefinedfindDescendant
The first element below the root that the match names, looking through
body and detail at any depth.<N extends NodeLike>(root: N | readonly N[], match: NodeMatch<N>): N | undefinedfirstCueToken
Returns whichever of
!cue.to and !cue.zoom appears first in a value, for error messages that name it, or null if neither does.(value: string): string | nullfirstNodeOf
The first mark the match names, cue wrappers unwrapped.
<N extends NodeLike>(children: readonly N[], match: NodeMatch<N>): N | undefinedflatNodes
Every mark in the body, cue wrappers unwrapped — what anything that needs to see the whole picture reads, whether or not a given mark is on screen yet: the frame deciding its domains, the footer listing what is there, the walk that collects an environment's free letters.
<N extends NodeLike>(children: readonly N[]): N[]getEnvironment
The registered spec for a bare environment name (
graph, not canvas.graph).(name: string): EnvironmentSpec | undefinedhasAttr
Whether the node writes the attribute at all, whatever its value.
(node: NodeLike, identifier: string): booleanhasNodeOf
Whether any mark is one the match names, cue wrappers unwrapped.
<N extends NodeLike>(children: readonly N[], match: NodeMatch<N>): booleanidsOf
The
#ids of the marks the match names, cue wrappers unwrapped.<N extends NodeLike>(children: readonly N[], match: NodeMatch<N>): Set<string>isAttentionCue
Whether a node is a cue that only changes how its content is looked at.
(node: NodeLike): booleanisCanvasNodeIdentifier
Whether a node identifier names an environment, by its
canvas. prefix; registration is not checked.(identifier: string): booleanisCanvasVocabularyIdentifier
Whether an identifier is a registered environment node or vocabulary child.
(identifier: string): booleanisCue
Whether a node is any cue form — a wrapper a walk unwraps rather than a mark.
(node: NodeLike): booleanisKeyframeTrack
Whether an attribute value is a
KeyframeTrack rather than a still value.(value: unknown): value is KeyframeTrackisPresenceCue
Whether a node is a cue that gates presence (
cue, cue.draw).(node: NodeLike): booleanlistEnvironments
Every registered spec, in registration order.
(): EnvironmentSpec[]matchesNode
Whether a node is one the match names.
<N extends NodeLike>(node: N, match: NodeMatch<N>): booleannodeById
The mark with this
#id, cue wrappers unwrapped, optionally only among the kinds the match names.<N extends NodeLike>(
children: readonly N[],
id: string,
match?: NodeMatch<N>,
): N | undefinednodeId
A node's author-declared
#id, or null when it has none — the test every addressable lookup starts with.(node: NodeLike): string | nullnodeKey
A stable key for a node among its siblings: its
instance_id, or the fallback when it has none (a node synthesised at render time, a test's).(node: NodeLike, fallback: string | number): stringnodesByIdentifier
The marks grouped by identifier, cue wrappers unwrapped — one walk where a surface would otherwise flatten its children once per kind it draws.
<N extends NodeLike>(children: readonly N[]): Map<string, N[]>nodesOf
Every mark the match names, cue wrappers unwrapped, in source order.
<N extends NodeLike>(children: readonly N[], match: NodeMatch<N>): N[]numberAttr
An attribute as a number, or the fallback when it is absent or anything else — a string, a binding, an unresolved track.
(
attrs: Readonly<Record<string, unknown>>,
identifier: string,
fallback: number,
): number
(
attrs: Readonly<Record<string, unknown>>,
identifier: string,
): number | undefinedregisterEnvironment
Register an environment's compile spec.
(spec: EnvironmentSpec): voidresolveAttrTypeSpec
Resolve an attribute's declared type to its underlying spec, across the base library AND every registered environment.
(type: unknown): { base: string; values?: string[]; } | nullsceneEnvironments
The environments of one kind in a compiled document — every node with this identifier in the detail of a top-level
scene, which is where an environment is written.<N extends NodeLike = NodeLike>(document: unknown, identifier: string): N[]splitCueChain
Split an attribute value into base text + raw keyframes.
(input: string): SplitCueResultstringAttr
An attribute as a string, or the fallback when it is absent or anything else.
(
attrs: Readonly<Record<string, unknown>>,
identifier: string,
fallback: string,
): string
(
attrs: Readonly<Record<string, unknown>>,
identifier: string,
): string | undefinedtoEnvironmentSpec
Returns the part of an
EnvironmentDefinition the compiler needs, as an EnvironmentSpec.(def: EnvironmentDefinition): EnvironmentSpecunregisterEnvironment
Remove a registration (test hosts tear down between cases).
(name: string): voidvisibleNodes
The marks a reader can see right now —
flatNodes, except that a presence cue which has not fired (or has been cued back out) takes its contents with it.<N extends NodeLike>(
children: readonly N[],
nodeVisible: (node: N) => boolean,
): N[]Anything that puts a CONTROL in front of the reader has to ask this rather than flatNodes, or a parameter written inside a cue hands out its slider from the first step while the mark it drives is still off the surface. The attention cues leave presence alone, so their contents are always here.
nodeVisible is the runtime's — ctx.animation.nodeVisible — so the answer is the one the anchors give and not a second reading of them.
#Classes
EnvironmentRegistrationError
Thrown by
registerEnvironment when a spec is invalid or conflicts with one already registered.typeof EnvironmentRegistrationErrorCauses: a malformed name, a second spec under a taken name, redeclaring or tagging the universal continue, an implicit naming an undeclared attribute, or a child element another environment declares differently.
#Constants
CANVAS_NODE_PREFIX
The prefix every environment node's identifier carries:
canvas.graph.stringCANVAS_UNIVERSAL_ATTRIBUTE_NAMES
Attributes every canvas node carries, whatever its type.
readonly ["continue"]CUE_ATTENTION
The cue forms that leave presence alone and only change how their content is being looked at.
ReadonlySet<string>The partition matters more than either half. Every environment that walks its own body has to make it, and until 21 September 2026 each one made it privately from a hand-copied list of identifiers — so a sixth cue form would have been added here and silently not unwrapped by any of them.
CUE_FAMILY
The identifiers of the cue nodes that animate an environment's contents; every environment accepts them inside its body.
readonly ["cue", "cue.draw", "cue.trace", "cue.highlight", "cue.spotlight"]CUE_HIGHLIGHT_SEQUENCE
How much longer a
cue.highlight runs than the duration: it was given.numberduration: is how long ONE ring takes, and the rings are staggered: the next sets off while the last is still on its way out, so the gesture as a whole outlasts a single ring. Shared because two places have to agree on it — the surface that draws the rings, and the host that measures how long the step's choreography runs so the transport knows when it is over.
CUE_PRESENCE
The cue forms that decide whether their content is THERE: unwrapping one means asking its anchors first.
ReadonlySet<string>CUE_TO_TOKEN
The source text that opens a
!cue.to keyframe in an attribute value.stringCUE_ZOOM_TOKEN
The source text that opens a
!cue.zoom keyframe in an attribute value.stringEnvironmentRegistry
The one registration surface for canvas environments, first-party and plugin alike.
EnvironmentRegistryClassRegistering a definition serves both sides at once: the render-side definition becomes resolvable for hosts, and its compile-side slice is fed to the registry in @internote/canvas-sdk, where the library builder, the refiners and the semantic pass read it. A plugin arrives here through loadEnvironmentFromManifest.
STEP_IDENTIFIERS
The identifiers of the nodes that divide a scene into steps; currently only
step.readonly ["step"]#Interfaces
CanvasAttrInfo
The parts of an attribute's declaration that refinement and animation need.
animatableHow the value interpolates under
!cue.to; absent when it cannot be animated.InterpolationKindtypeThe declared type the refiners parse the value (and each keyframe target) through.
TypeRefSpecCanvasAttrSpec
An attribute in an environment's vocabulary.
aliasesOther names source may write the attribute under; the compiled node carries the canonical name.
string[]animatableHow the value interpolates under
!cue.to; absent means the attribute cannot be animated.InterpolationKinddefaultParsed through
type; arrays/numbers/booleans are stringified first. Defaults for inline/record/reference types are written in SOURCE syntax as strings (e.g. '!(x: 1)').unknownrequiredOptionality is
required, and nothing else — no type means "or nothing".booleantypeREQUIRED — there is no implicit
string. A default of the most permissive type is what an unconsidered attribute receives by accident, making it indistinguishable from a deliberately textual one. The rule governs the EFFECTIVE merged attribute, so refining a primitive's attribute need not restate its type.TypeRefSpecCanvasNodeSpec
A child element in an environment's vocabulary.
aliasesOther identifiers source may write the node under.
string[]attributesThe element's attributes, keyed by canonical name.
Record<string, CanvasAttrSpec>bodyThe content policy of the node's body.
PolicySpecDefault
allclassesThe document classes the node may appear in; every class when omitted.
string[]delimiterFixed line-start delimiter (D11), e.g.
---.stringderivedRead-only computed attributes, keyed by name (§4).
Record<string, DerivedSpec>detailThe content policy of the node's detail.
PolicySpecDefault
nonedynamicPer-instance switches (D38).
SwitchSpec[]implicitThe attribute the head
:value slot supplies (D37) — a canonical name or an alias, stored canonical. WITHOUT it the construct has no : slot and image:photo.jpg is a parse error naming the (href: …) spelling. It must name a settable, non-derived attribute that no dynamic case withdraws. On a merge the tag is kept unless restated; null removes a primitive's.string | nullCueBox
A
!cue.zoom keyframe's box — the rectangle drawn around the smaller of the two windows before the frame moves.colourA palette name — the box is drawn in it.
stringdrawMsHow long the outline takes to draw itself around the region.
numberholdMsThe pause between the box closing and the frame starting to move.
numberCueKeyframe
One refined keyframe of an attribute track.
atWhen the transition starts: a step, or a scene time.
CueAnchorbox!cue.zoom: the move is announced by a box.CueBoxdelayMsHow long the value waits after its anchor fires before it starts moving. A
!cue.zoom spends it drawing its box; nothing else uses it, and an absent delay is the ordinary keyframe that leaves immediately.numbereasingThe transition's curve; baked in by the refiners like
overMs.linearsmoothoverMsTransition duration in ms. The refiners always bake the language default (dcInternoteLib's
cueToDefaults) into refined frames; optional only for hand-built trees.numbervalueThe target value, refined through the attribute's own type.
unknownEnvironmentAnimation
An environment's animation handlers: the engine calls in, the environment never owns a timeline.
nodeAnimationMsHow long one of this environment's own nodes takes to act on the anchor named by
anchorAttr (in, out, at), in ms — for a verb whose window is not something the author wrote down but something derived from its own content.(node: CompiledNode, anchorAttr: string) => number | nullThe host measures the shared cue family off its attributes: a fade is in-duration:, a verb's move is duration:. A type verb whose window is its content's own size has no such attribute to read, and measured that way it comes out as the fallback — cue.type types for as long as its text takes at speed: characters a second, and a transport measuring attributes alone called a ten-second typing finished in a fraction of a second. Return null to leave the generic rule standing.
Read from the compiled node, like timeAnimationMs: the host asks once, before any environment has mounted, so there is no session and no runtime.
onStepCalled on every step transition of the scene's timeline.
(index: number, ctx: EnvironmentContext) => voidtimeAnimationMsHow long this environment's own time-driven animation runs, in ms — 0 or absent when it has none.
(node: CompiledNode) => numberThe scene's clock is what the host's transport drives, and its length is otherwise measured only from time-anchored cues. A type whose content moves through time for its own reasons declares it here, so the reader gets the SAME play control rather than a second one beside it. Read from the compiled node: no session, no datasets, because the host asks before any environment has mounted.
verbsType verbs beyond the cue family, keyed by vocabulary identifier.
Record<string, VerbHandler<EnvironmentContext>>EnvironmentContext
The context an environment's hooks, toolbar and footer receive.
animationThis environment's animation engine (attr tracks, presence, step queries).
EnvironmentAnimationRuntime<EnvironmentContext>assetsThe internote's uploaded image assets, file name → public URL — what a environment drawing an uploaded picture (
canvas.diagram:cell.jpg) resolves its name against. Binary files never arrive as content; a URL is all a surface needs.Record<string, string> | nullnull means the manifest has not arrived yet, which a type must be able to tell from {} — one is a wait, the other an absence.
datasetsThe document's
@data datasets, by id — what a vocabulary attribute binding a column (values: #gdp.gdppc) resolves against. Blank-canvas content already receives these; environments read them here.Record<string, ChalkDataset>environmentNameThe bare type name (
graph, not canvas.graph).stringfilesThe internote's uploaded text files by name — a boundary
.geojson, a .part.chalk include. Attached CSVs are already folded into datasets and are not read from here; this is for attachments whose shape is not a table, which the type that understands them parses itself.Record<string, string> | nullnull means the manifest has not arrived yet, which a type must be able to tell from {} — one is a wait, the other an absence.
footerThe scene's one footer: whether its panel is open, and the ability to ask for it. Shared by every environment in the scene, because the footer is.
FooterAccessidentityWhich internote, scene and environment this is — the key its session state is stored under.
EnvironmentIdentityisFocusedSingle-focused-environment management: host-owned, two instruments never share the keyboard.
booleanisPresentingPresentation drive mode.
booleannodeThe compiled
canvas.<name> node.CompiledNoderunnerHost-injected code execution service — absent when the host runs nothing.
CodeRunnerstepThe current step index on the scene's timeline, which every environment in the scene shares.
numberstepAnimationRemainingMsHow long the current step's choreography has left to run, in ms — 0 once it has finished (or when the step animates nothing). The same reckoning the transport uses to offer a replay: the step's span measured from its entry, frozen while paused, and restarted by a replay.
numberstepCountHow many steps the scene has.
numberstepsThe scene's step controller — read/subscribe; drive modes own writes.
StepControllerstorageThe declared storage tiers, assembled by the host.
CanvasStorageEnvironmentDefinition
One canvas environment, spanning both sides of the system: what authors may write inside it and how it draws.
The compile side (environment attributes and child vocabulary, validated by the compiler and the semantic pass) and the render side (surface, animation handlers, toolbar, footer, storage) live in the one definition. First-party environments and plugins author the identical shape; only how the definition reaches the EnvironmentRegistry differs.
An environment never reaches around the APIs: JSX enters exactly twice (Surface, and the two bands of footer), the toolbar is data, animation handlers react to the engine, and storage goes through the declared tiers. Build one with defineEnvironment.
animationAnimation handlers — the engine calls in, types never own timelines.
EnvironmentAnimationattributesEnvironment-node attributes beyond the universal
id/continue.Record<string, CanvasAttrSpec>bodyEnvironment body policy override (defaults: vocabulary + cue family, or none).
PolicySpeccompileA pre-built compile spec, used instead of the inline fields below.
EnvironmentSpecFirst-party environments keep theirs React-free so server compiles see them; passing the same object here makes registration idempotent across both sides.
displayNameHuman-readable label (plugin marketplace / debugging).
stringfooterWhat this environment puts in the scene's footer: what it REPORTS, and what the reader OPERATES.
{
Bar: ComponentType<EnvironmentContext>;
Panel?: ComponentType<EnvironmentContext>;
present?: (ctx: EnvironmentContext) => boolean;
hasPanel?: (ctx: EnvironmentContext) => boolean;
}Content only — the frame, the rule between the bands, the chevron and the drag handle are the host's, and there is one set of them for the scene however many environments contribute. Two components rather than one because only the panel animates, and the bar's contents are needed without mounting the panel's.
Either may render nothing; a footer with nothing in either band collapses altogether.
interpolationsInterpolators for value shapes this environment INVENTED, keyed by the interpolation kind its attributes declare.
Record<string, Interpolator>An environment could already declare an attribute's animatable kind but had no way to say how two of that kind blend, so a new shape had nowhere to go but the SDK's built-in registry — which is how the graph's plane transform came to be a default here, cited by filename in a package that is supposed to know nothing about graphs. The registry always documented itself as "the whole extension point for new value shapes"; this is the door.
Registering a kind the SDK already defines replaces it for every environment in the host, so an environment names its own kinds.
nameBare type name: 'graph' → authors write
canvas.graph.stringstorageStorage tiers the type uses. Defaults to session-only with no init.
CanvasStorageDeclarationSurfaceThe environment surface. Rendered inside the host's stable frame; hooks are fine.
ComponentType<SurfaceProps>toolbarDECLARATIVE toolbar contribution — data only, no JSX (host renders).
(ctx: EnvironmentContext) => ToolbarItem[]vocabularyChild element vocabulary → compiler validation + semantic pass.
Record<string, CanvasNodeSpec>EnvironmentSpec
What an environment tells the compiler: its name, the attributes and child elements it accepts, its own value types and its validation rules.
attributesEnvironment-node attributes beyond the universal
continue.Record<string, CanvasAttrSpec>bodyBody policy for the environment node itself. Defaults to a children policy of the vocabulary plus the cue family, or
none when there is no vocabulary.PolicySpecdynamicPer-instance switches on the environment node itself (D38) — a graph withdrawing the other planes' axis attributes, and narrowing its body to the marks its plane draws. A case's attributes are sanitised like the static ones; its
body replaces the vocabulary policy wholesale.SwitchSpec[]implicitThe attribute the head
:value slot supplies (D37) — canvas.code:python tags language. An environment that omits it has no : slot. It may never be the universal continue, which is a reference to another environment and not this one's subject.stringnameThe bare type name, lower case with hyphens; must be unique across registrations.
stringtypesRefiners for the value types above, keyed by type name.
Record<string, AttrRefiner>validateDocument-level rules this environment's own content must satisfy, beyond what its attribute types can express.
voidvalueTypesThe value types this environment INVENTED, declared for the compiler and folded into the emitted library's
types table exactly as EnvironmentSpec.vocabulary is folded into its nodes.Record<string, TypeSpec>vocabularyChild element vocabulary, keyed by (flat) chalk identifier.
Record<string, CanvasNodeSpec>KeyframeTrack
The refined value of an animatable attribute that carries keyframes.
baseThe refined base (initial) value.
unknownframesKeyframes in source order.
CueKeyframe[]kindTells a track apart from a plain attribute value.
'keyframes'NodeLike
The fields of a compiled chalk node that the node helpers read, so the same helpers work on render-time nodes and compile-time
ChalkElements.attributesThe node's attributes, each with its canonical name and compiled value.
ReadonlyArray<{ identifier: string; value: unknown }>bodyThe compiled contents of the node's
{…} section: child nodes, inline content or a typed value.unknowndetailThe compiled contents of the node's
[…] section: child nodes or inline content.unknownidThe
#id the author gave the node, if any; read it with nodeId.unknownidentifierThe node's type as written, such as
canvas.graph, point or cue.stringinstance_idThe id the system gives every node, kept across edits; unlike
id, an author cannot write or reference it.unknownRawCueFrame
A syntactically split keyframe, values still raw text.
atThe
at: anchor as written; required, so the splitter fails a frame without one.stringcolour!cue.zoom only: the palette colour the box is drawn in (color: is an alias).stringdraw!cue.zoom only: how long the box takes to draw, as written.stringeasingThe
easing: curve as written.stringhold!cue.zoom only: the pause before the frame moves, as written (pause: is an alias).stringkindThe micronode that wrote it —
zoom frames carry the box attributes.tozoomoverThe
over: transition duration as written.stringvalueThe
{…} body — the target value's source text.stringSemanticContext
What an environment's
EnvironmentSpec.validate is handed: somewhere to report to, and the document facts a rule needs that the node itself does not carry.datasetsThe document's
@data datasets by id — what a data: #id binding resolves against.Record<string, unknown>reportRecord a diagnostic. An
error fails the compile; a warning rides along with it.voidstepCountHow many steps the enclosing scene has, for anchor-range rules.
numberSurfaceProps
Props of a type's Surface component — the ONE place JSX enters via the Environment API.
ctxEverything the environment knows: its compiled node, step, storage and animation runtime.
EnvironmentContextrevisionRe-render tick the host bumps on step/track changes.
number#Types
AttrRefiner
A post-compile parser for one attribute value: the refined value, or why it was refused.
(input: string) => { ok: true; data: unknown } | { ok: false; error: string }CueAnchor
When a keyframe fires, parsed from its
at:: at a numbered step, optionally with a delay after it, or at a time in the scene.{
kind: "step";
value: number;
offsetMs?: number;
} | {
kind: "time";
value: number;
}CueMicronode
Which keyframe micronode wrote a keyframe:
'to' for !cue.to, 'zoom' for !cue.zoom.tozoomNodeMatch
Which nodes a question is about: an identifier, several, or a test of the node itself.
string | ReadonlySet<string> | readonly string[] | ((node: N) => boolean)SemanticSeverity
How much a diagnostic weighs: an
error fails the compilation, a warning rides along with a successful one.errorwarningSplitCueResult
The outcome of
splitCueChain: the base value's text and its raw keyframes, or why the chain is malformed.{
ok: true;
base: string;
frames: RawCueFrame[];
} | {
ok: false;
error: string;
}