MotionScript

@motion-script/core


@motion-script/core / Text

Class: Text

Defined in: nodes/text/text-node.ts:59

Base class for all scene-graph nodes.

Every visible or structural element in a scene extends Node. It wires together three orthogonal systems:

Reactive properties — fields declared with @property() are backed by Signals. Reading them inside a reactive context (e.g. a render pass) creates a subscription; writing them propagates the change automatically. Use set to update one or more props imperatively, or pass a callback () => expr to bind the prop to a derived value.

Tweening*to(props, duration, ease?) is a generator that animates one or more props to target values over the given duration (in seconds). Numeric props are interpolated; props that register a custom tween fn (via @property({ tween })) can animate any value type. The convenience helpers moveTo, moveX, moveY, fadeTo, rotateTo, and scaleTo wrap to for the most common single-property animations.

Layoutmeasure() is called top-down to resolve sizes, then layout() places the node in its allocated BoxBounds. Children are measured and laid out by the parent; the base class just stores the rect.

Built-in visual props

propdefaultunit / notes
x0horizontal offset in scene pixels
y0vertical offset (positive = up)
width'fill'SizeInput: px, 'fill', 'auto'
height'fill'same
sizesugar: sets width and height together
scale1uniform scale factor
rotate0degrees, clockwise
opacity10–1
blend'pass-through'layer blend mode (NodeBlendMode)
effects[]post-process / blend effects
padding0inner spacing, all four edges

Extends

Extended by

Constructors

Constructor

new Text(props): Text

Defined in: nodes/text/text-node.ts:77

Parameters

props

NodeConfig<Text, TextProps>

Returns

Text

Overrides

ShapeNode.constructor

Properties

__mappers?

optional __mappers?: Map<string, (ext, prev?) => any>

Defined in: nodes/base/node.ts:345

Maps external prop value → internal cell value for fields that need it.

Inherited from

ShapeNode.__mappers


__signals?

optional __signals?: Map<string, Signal<any>>

Defined in: nodes/base/node.ts:341

Inherited from

ShapeNode.__signals


__tweens?

optional __tweens?: Map<string, TweenFn<any>>

Defined in: nodes/base/node.ts:343

Inherited from

ShapeNode.__tweens


__upgraders?

optional __upgraders?: Map<string, () => Signal<any>>

Defined in: nodes/base/node.ts:342

Inherited from

ShapeNode.__upgraders


_children

protected _children: Node<NodeProps>[] = []

Defined in: nodes/base/node.ts:475

Inherited from

ShapeNode._children


_lastScope?

optional _lastScope?: MeasureScope

Defined in: nodes/base/node.ts:431

The MeasureScope threaded through the last measure pass, retained so off-tree work (e.g. the animated child-insert in node-lifecycle.ts) can measure a not-yet-attached child in isolation — measuring its natural size without adding it to this node's layout flow, so siblings don't shift for a frame. Undefined until this node is first measured. @internal.

Inherited from

ShapeNode._lastScope


_props?

protected optional _props?: NodeConfig<any, TextProps>

Defined in: nodes/base/node.ts:318

The raw props this node was constructed with, retained past construction so a provider's provideContext can see which keys the author explicitly passed on every bind walk (e.g. DefaultTextStyle contributes only the style keys it was given). Authored identity — deliberately kept through dispose so a reused instance re-derives context from the next walk.

Inherited from

ShapeNode._props


_stateStack

_stateStack: Map<string, SignalSnapshot<any>>[] = []

Defined in: nodes/base/node.ts:1027

Internal

LIFO stack of save() snapshot layers. Underscore-internal so the reactive companion can read it; not authoring surface.

Inherited from

ShapeNode._stateStack


blend

blend: "color" | "multiply" | "screen" | "overlay" | "darken" | "lighten" | "color-dodge" | "color-burn" | "hard-light" | "soft-light" | "difference" | "exclusion" | "hue" | "saturation" | "luminosity" | "normal" | "pass-through"

Defined in: nodes/base/node.ts:356

Inherited from

ShapeNode.blend


childPositioning

childPositioning: ChildPositioning

Defined in: nodes/base/node.ts:372

Frame of reference this node's children are placed in. See NodeProps.childPositioning.

Inherited from

ShapeNode.childPositioning


clip

clip: boolean

Defined in: nodes/base/node.ts:364

When true, content drawn by this node's children is clipped to its outline (see clipSelf).

Inherited from

ShapeNode.clip


colSpan

colSpan: number

Defined in: nodes/base/node.ts:389

Inherited from

ShapeNode.colSpan


column

column: number | undefined

Defined in: nodes/base/node.ts:387

Inherited from

ShapeNode.column


constraints

protected constraints: SizeConstraints

Defined in: nodes/base/node.ts:393

Inherited from

ShapeNode.constraints


effects

effects: Effect

Defined in: nodes/base/node.ts:357

Inherited from

ShapeNode.effects


end

end: number

Defined in: nodes/geometry/shape-node.ts:82

Inherited from

ShapeNode.end


fill

fill: Fill

Defined in: nodes/geometry/shape-node.ts:65

Inherited from

ShapeNode.fill


flex

flex: number

Defined in: nodes/base/node.ts:376

Inherited from

ShapeNode.flex


fontFamily

readonly fontFamily: string

Defined in: nodes/text/text-node.ts:64


fontSize

readonly fontSize: number | "autofit"

Defined in: nodes/text/text-node.ts:65


fontStyle

readonly fontStyle: FontStyle

Defined in: nodes/text/text-node.ts:67


fontWeight

readonly fontWeight: number

Defined in: nodes/text/text-node.ts:66


gapScale

gapScale: number

Defined in: nodes/base/node.ts:386

Per-child weight for the flex gap this node contributes to its parent's main axis, in [0, 1]. Default 1 = a full gap on each side (normal layout). Driven 0 → 1 (insert) / 1 → 0 (remove) by the animated addChildAt/removeChildAt overloads so the surrounding gap opens/closes in lockstep with the child's box instead of popping — see addChildAtAnimated. Read only by flex containers off their children; authors have no reason to set it directly. @internal.

Inherited from

ShapeNode.gapScale


height

height: SizeInput

Defined in: nodes/base/node.ts:352

Inherited from

ShapeNode.height


id

readonly id: string

Defined in: nodes/base/node.ts:339

Inherited from

ShapeNode.id


isTimeInvariant

protected readonly isTimeInvariant: boolean = false

Defined in: nodes/base/node.ts:461

Whether this node's drawing is a pure function of its own cells and its children — and therefore whether the render walk may skip it when none of those changed.

Opt-in, and it has to be. A node can perfectly well be a function of things that are not signals: this._clock.elapsed (a plain field advanced by advanceClock), the velocity sampleMotion writes into _renderState each frame (motion blur reads it), a random draw, or anything at all inside a user's renderSelf. None of that marks a cell, so none of it can be detected — a default of true would make every third-party node silently stop updating, which is the worst failure this change could have.

Set it on a class only after checking it reads nothing outside its own props and children.

Inherited from

ShapeNode.isTimeInvariant


letterSpacing

readonly letterSpacing: number

Defined in: nodes/text/text-node.ts:68


lineHeight

readonly lineHeight: number

Defined in: nodes/text/text-node.ts:69


minFontSize

readonly minFontSize: number

Defined in: nodes/text/text-node.ts:72


opacity

opacity: number

Defined in: nodes/base/node.ts:355

Inherited from

ShapeNode.opacity


overlay

overlay: Fill

Defined in: nodes/geometry/shape-node.ts:70

Inherited from

ShapeNode.overlay


padding

padding: Insets

Defined in: nodes/base/node.ts:358

Inherited from

ShapeNode.padding


path

readonly path: PathData | null

Defined in: nodes/text/text-node.ts:75


pivot

readonly pivot: Anchor

Defined in: nodes/base/node.ts:361

Inherited from

ShapeNode.pivot


random

readonly random: Random

Defined in: nodes/base/node.ts:337

Per-node seeded randomness, available to every subclass without threading a Random in from the stage. Defaults to seed 0; set the origin via the NodeProps.seed prop, or re-seed in the constructor with this.random.reset(seed) / this.random.seed = seed.

Draws are reproducible across scrub/precomp/HMR out of the box: the runtime rebuilds a fresh node (and thus a fresh source at its constructor-set seed) on every playback pass rather than reusing a source that has advanced — so a draw taken during construction always starts from the seed head, no per-pass rewind needed.

Inherited from

ShapeNode.random


relativeToParent

relativeToParent: RelativeToParent

Defined in: nodes/base/node.ts:374

This node's override of its parent's childPositioning. See NodeProps.relativeToParent.

Inherited from

ShapeNode.relativeToParent


rotation

rotation: number

Defined in: nodes/base/node.ts:354

Inherited from

ShapeNode.rotation


row

row: number | undefined

Defined in: nodes/base/node.ts:388

Inherited from

ShapeNode.row


rowSpan

rowSpan: number

Defined in: nodes/base/node.ts:390

Inherited from

ShapeNode.rowSpan


scale

scale: number

Defined in: nodes/base/node.ts:353

Inherited from

ShapeNode.scale


shadow

shadow: Shadow

Defined in: nodes/geometry/shape-node.ts:76

Inherited from

ShapeNode.shadow


start

start: number

Defined in: nodes/geometry/shape-node.ts:79

Inherited from

ShapeNode.start


stroke

stroke: Stroke

Defined in: nodes/geometry/shape-node.ts:73

Inherited from

ShapeNode.stroke


text

readonly text: string

Defined in: nodes/text/text-node.ts:63


textAlign

readonly textAlign: TextAlign

Defined in: nodes/text/text-node.ts:70


variant?

readonly optional variant?: string

Defined in: nodes/text/text-node.ts:73


width

width: SizeInput

Defined in: nodes/base/node.ts:351

Inherited from

ShapeNode.width


wrap

readonly wrap: boolean

Defined in: nodes/text/text-node.ts:71


x

x: number

Defined in: nodes/base/node.ts:349

Inherited from

ShapeNode.x


y

y: number

Defined in: nodes/base/node.ts:350

Inherited from

ShapeNode.y

Accessors

assets

Get Signature

get assets(): AssetCatalog

Defined in: nodes/base/node.ts:294

Returns

AssetCatalog

Inherited from

ShapeNode.assets


bottomCenter

Get Signature

get bottomCenter(): Vector2

Defined in: nodes/base/node.ts:1397

Returns

Vector2

Inherited from

ShapeNode.bottomCenter


bottomLeft

Get Signature

get bottomLeft(): Vector2

Defined in: nodes/base/node.ts:1382

Returns

Vector2

Inherited from

ShapeNode.bottomLeft


bottomRight

Get Signature

get bottomRight(): Vector2

Defined in: nodes/base/node.ts:1387

Returns

Vector2

Inherited from

ShapeNode.bottomRight


center

Get Signature

get center(): Vector2

Defined in: nodes/base/node.ts:1368

Center of the node — equivalent to its x/y position (0,0 is the center of the layout cell).

Returns

Vector2

Inherited from

ShapeNode.center


centerLeft

Get Signature

get centerLeft(): Vector2

Defined in: nodes/base/node.ts:1402

Returns

Vector2

Inherited from

ShapeNode.centerLeft


centerRight

Get Signature

get centerRight(): Vector2

Defined in: nodes/base/node.ts:1407

Returns

Vector2

Inherited from

ShapeNode.centerRight


children

Get Signature

get children(): Node<NodeProps>[]

Defined in: nodes/base/node.ts:1508

Returns

Node<NodeProps>[]

Inherited from

ShapeNode.children


clock

Get Signature

get clock(): Readonly<NodeClock>

Defined in: nodes/base/node.ts:1087

Internal timing state.

Returns

Readonly<NodeClock>

Inherited from

ShapeNode.clock


dirtyGeneration

Get Signature

get dirtyGeneration(): number

Defined in: nodes/base/node.ts:421

This node's current generation; a cache built at this value is current.

Returns

number

Inherited from

ShapeNode.dirtyGeneration


global

Get Signature

get global(): WorldTransform

Defined in: nodes/base/node.ts:1472

Resolved world-space transform — the same anchor points and metrics as the local getters (center, topRight, rotation, …) but folded through the full ancestor chain, so values are absolute scene coordinates rather than parent-relative ones. See WorldTransform. Every field is reactive.

Examples
// Read another node's absolute corner, regardless of its parent:
const p = other.global.topRight;   // world-space {x, y}

### Reading vs. placing
`global` is for *reading* world coordinates. `x`/`y` (and the anchor props)
are **parent-relative**, so assigning a world value to them does not by
itself place this node in world space — it offsets it from this node's own
parent. To land exactly on another node regardless of either parent,
subtract this node's parent's world contribution:
// Place this node's origin exactly on `other`, any parent:
new Rect({
  x: () => other.global.x - (myParent.global.x),
  y: () => other.global.y - (myParent.global.y),
});

When both nodes share the same parent origin (e.g. both at the scene root),
`x: () => other.global.x` already lands on target with no compensation.
Returns

WorldTransform

Inherited from

ShapeNode.global


layoutRect

Get Signature

get protected layoutRect(): BoxBounds

Defined in: nodes/base/node.ts:464

The allocated bounding box from the last layout pass. Reactive — reads inside callbacks are tracked.

Returns

BoxBounds

Inherited from

ShapeNode.layoutRect


measuredHeight

Get Signature

get measuredHeight(): number

Defined in: nodes/base/node.ts:1354

Returns

number

Inherited from

ShapeNode.measuredHeight


measuredRect

Get Signature

get measuredRect(): BoxBounds

Defined in: nodes/base/node.ts:473

Internal

Returns

BoxBounds

Inherited from

ShapeNode.measuredRect


measuredWidth

Get Signature

get measuredWidth(): number

Defined in: nodes/base/node.ts:1350

Returns

number

Inherited from

ShapeNode.measuredWidth


name

Get Signature

get name(): string

Defined in: nodes/base/node.ts:701

Returns

string

Inherited from

ShapeNode.name


parent

Get Signature

get parent(): Node<NodeProps> | null

Defined in: nodes/base/node.ts:290

Returns

Node<NodeProps> | null

Inherited from

ShapeNode.parent


positioning

Get Signature

get positioning(): ChildPositioning

Defined in: nodes/base/node.ts:1981

How this node is placed inside its parent, with 'inherit' resolved: 'relative' (the parent lays it out) or 'absolute' (it is pinned to the stage). A root node has no parent to be absolute against, so it is always 'relative'.

Returns

ChildPositioning

Inherited from

ShapeNode.positioning


properties

Get Signature

get properties(): P

Defined in: nodes/base/node.ts:697

Returns

P

Inherited from

ShapeNode.properties


topCenter

Get Signature

get topCenter(): Vector2

Defined in: nodes/base/node.ts:1392

Returns

Vector2

Inherited from

ShapeNode.topCenter


topLeft

Get Signature

get topLeft(): Vector2

Defined in: nodes/base/node.ts:1372

Returns

Vector2

Inherited from

ShapeNode.topLeft


topRight

Get Signature

get topRight(): Vector2

Defined in: nodes/base/node.ts:1377

Returns

Vector2

Inherited from

ShapeNode.topRight

Methods

_cameraScope()

_cameraScope(): CameraScope | null

Defined in: nodes/base/node.ts:1727

Internal

Returns

CameraScope | null

Inherited from

ShapeNode._cameraScope


_confinesChildren()

_confinesChildren(): boolean

Defined in: nodes/base/node.ts:1739

Internal

Returns

boolean

Inherited from

ShapeNode._confinesChildren


_hitTestSelf()

_hitTestSelf(local, tolerance): boolean

Defined in: nodes/base/node.ts:1794

Internal

Dispatch seam so node-picking.ts can reach the protected override.

Parameters

local

Vector2

tolerance

number

Returns

boolean

Inherited from

ShapeNode._hitTestSelf


_localBounds()

_localBounds(): BoxBounds

Defined in: nodes/base/node.ts:1789

Internal

Returns

BoxBounds

Inherited from

ShapeNode._localBounds


_localMatrix()

_localMatrix(): Matrix2D

Defined in: nodes/base/node.ts:1426

Internal

Composed with the camera scopes in between by runtime/node-picking.ts.

Returns

Matrix2D

Inherited from

ShapeNode._localMatrix


_prepareStep()

_prepareStep(to, duration, easing?): TweenStepper

Defined in: nodes/base/node.ts:734

Resolve a single to() step into a flat TweenStepper — all the per-key setup (anchor handling, mapper, numeric-vs-custom routing) happens once here, then advance(dt) is allocation-free. Used by both the generator path (_toGen) and the batched parallel path.

Parameters

to

Partial<P>

duration

number

easing?

EasingFunction

Returns

TweenStepper

Inherited from

ShapeNode._prepareStep


_registerSelection()

_registerSelection(selection): void

Defined in: nodes/text/text-node.ts:159

Internal

Called by TextSelection on construction.

Parameters

selection

TextSelection

Returns

void


_sampleMotion()

protected _sampleMotion(): void

Defined in: nodes/base/node.ts:1647

Compute this frame's motion (velocity/direction/speed/angular/scale) into _renderState as a backward difference against the previous frame, and roll the history forward. Velocity is 0/{0,0} when no trustworthy delta exists — the first frame, or after a non-monotonic time jump (only 0 < dt <= MAX is trusted, so a scrub that resets the clock reads as "unknown" rather than a spurious huge velocity). The world position matches applyTransform (layoutRect + x, layoutRect - y, y-down). Called via sample every frame; layout-dependent fields (rects/elapsed) are filled in by beforeRender at draw time.

Returns

void

Inherited from

ShapeNode._sampleMotion


_spaceRects()

protected _spaceRects(): SpaceRects

Defined in: nodes/base/node.ts:1910

Reference rects for fills with space:'parent', expressed in this node's local space (origin = this node's positioned centre, y-down to match the canvas). The viewport (space:'global') is resolved by the renderer, which knows the surface size. Rotation/scale of this node are not folded in — the rect is the axis-aligned parent box, which is what gradients expect.

Returns

SpaceRects

Inherited from

ShapeNode._spaceRects


_textState()

_textState(): Partial<TextState>

Defined in: nodes/text/text-node.ts:322

Internal

Returns

Partial<TextState>


_toGen()

_toGen(to, duration, easing?): FrameGenerator

Defined in: nodes/base/node.ts:814

Parameters

to

Partial<P>

duration

number

easing?

EasingFunction

Returns

FrameGenerator

Inherited from

ShapeNode._toGen


_writeProp()

_writeProp(field, value): void

Defined in: nodes/base/node.ts:684

Internal

Hot-path prop write (mapper- and binding-aware). Public-but-underscored like _toGen/_prepareStep so reactive companions in this directory can call it; not part of the authoring surface.

Parameters

field

string

value

unknown

Returns

void

Inherited from

ShapeNode._writeProp


add()

add(child): void

Defined in: nodes/base/node.ts:1531

Compose this node's internal children — the constructor-friendly entry point a custom composite calls to build its own subtree (a single node or an array, JSX included). Sugar over addChild/addChildren: it works the same before the node is linked into the tree (in the constructor) as after, so a composite builds its structure from props right in its constructor — no init-style hook, no idempotency guard, since the constructor runs once.

Accepts the same shape as the children prop — a single node, or an arbitrarily-nested array (.flat(Infinity)), with non-Node entries (false/null/undefined from cond && <Node/>) filtered out — so this.add(items.map(...)) or this.add(cond && <Text/>) work directly.

Parameters

child

NodeChildren

Returns

void

Example

constructor(props?) {
  super(props);
  this.add(<Rect ref={this.rowRef} flow="horizontal">{…}</Rect>);
}

Inherited from

ShapeNode.add


addChild()

addChild(child): void

Defined in: nodes/base/node.ts:1541

Parameters

child

Node

Returns

void

Inherited from

ShapeNode.addChild


addChildAt()

Call Signature

addChildAt(child, index): void

Defined in: nodes/base/node.ts:1570

Parameters
child

Node

index

number

Returns

void

Inherited from

ShapeNode.addChildAt

Call Signature

addChildAt(child, index, duration, easing?): FrameGenerator

Defined in: nodes/base/node.ts:1571

Parameters
child

Node

index

number

duration

number

easing?

EasingFunction

Returns

FrameGenerator

Inherited from

ShapeNode.addChildAt


addChildren()

addChildren(children): void

Defined in: nodes/base/node.ts:1557

Parameters

children

Node<NodeProps>[]

Returns

void

Inherited from

ShapeNode.addChildren


adoptDetached()

protected adoptDetached(node): void

Defined in: nodes/base/node.ts:1238

Adopt a detached node for binding only — its asset catalog, inherited context and clock — without making it a child.

Tree membership supplies three things a node cannot work without: the asset catalog (a webfont never shapes and an <Image> never loads without it), the resolved context map (theme tokens), and a ticking clock. Layout and painting are not among them. So a node used purely as a source of pixels — a Tex.surface(...) subtree rasterized onto 3D geometry — can be bound by whatever consumes it and laid out on demand, instead of having to sit in a particular place in the tree.

Safe to call every frame: bindAssets short-circuits on an unchanged catalog, resolveContext is fired only on the adoptee's first bind, and ellapse is idempotent for a repeated time.

Parameters

node

Node

Returns

void

Inherited from

ShapeNode.adoptDetached


afterRender()

afterRender(ctx): void

Defined in: nodes/base/node.ts:1914

Parameters

ctx

RenderContext

Returns

void

Inherited from

ShapeNode.afterRender


append()

append(text, duration, easing?): FrameGenerator

Defined in: nodes/text/text-node.ts:145

Parameters

text

string

duration

number

easing?

EasingFunction

Returns

FrameGenerator


applyClip()

protected applyClip(ctx): boolean

Defined in: nodes/base/node.ts:1814

Open clipSelf()'s outline as a clip scope, confining whatever is drawn until the matching ctx.endClip() to the shape. Returns true when a clip was actually opened (so the caller knows to close it) and false when the node has no outline (the default).

Parameters

ctx

RenderContext

Returns

boolean

Inherited from

ShapeNode.applyClip


applyDefaultSize()

protected applyDefaultSize(props?): void

Defined in: nodes/text/text-node.ts:94

Figma-style smart default for width/height: hug-to-content when the node is given children, fill-the-parent when it's empty — so a plain new Rect({ children: [...] }) shrink-wraps like a Figma auto-layout frame, while an empty one behaves like a background/spacer. Called once from the constructor (skipped when flex is set, since that already implies 'fill'), so it's the baseline every Node gets for free.

Subclasses with their own sizing convention (Text hugs single-line text but fills when wrapping/autofit; Path/RichText always hug; FlexNode always hugs) override this — typically a one-line replacement — instead of duplicating the children-check in their constructor.

"Given children" means children in this node's flow: a container holding nothing but stage-pinned children has no content of its own to shrink-wrap, so it defaults like an empty one.

Parameters

props?

NodeConfig<Text, TextProps>

Returns

void

Overrides

ShapeNode.applyDefaultSize


applyProp()

protected applyProp<Ext, Int>(field, initial, options?): void

Defined in: nodes/base/node.ts:675

Declare a reactive prop on this node. Creates a Signal-backed accessor for field, applies an initial value (callback → reactive binding; otherwise constant), and registers optional tween/mapper metadata used by set() and to().

Subsequent calls for the same field reuse the existing cell and act as a value assignment, so subclasses can override a parent's default by calling applyProp again without losing the cell or its bindings.

Type Parameters

Ext

Ext

Int

Int = Ext

Parameters

field

string

initial

Ext | (() => Ext) | undefined

options?

PropOptions<Ext, Int>

Returns

void

Inherited from

ShapeNode.applyProp


applyTransform()

protected applyTransform(ctx): void

Defined in: nodes/base/node.ts:1657

Push this node's transform (position, scale, rotate, opacity, effects).

Parameters

ctx

RenderContext

Returns

void

Inherited from

ShapeNode.applyTransform


beforeRender()

beforeRender(ctx): void

Defined in: nodes/base/node.ts:1890

Parameters

ctx

RenderContext

Returns

void

Inherited from

ShapeNode.beforeRender


bindAssets()

bindAssets(context): void

Defined in: nodes/base/node.ts:1128

Parameters

context

AssetCatalog

Returns

void

Inherited from

ShapeNode.bindAssets


bindContext()

bindContext(parent, runResolve): void

Defined in: nodes/base/node.ts:1191

Push inherited context down this subtree, mirroring bindAssets.

runResolve separates the two responsibilities the walk has:

  • true (first bind of this instance / a freshly-added child): also invoke resolveContext, which applies inherited context values to the already-built structure. It runs once per instance (the runtime rebuilds rather than replaying), so it must not depend on being re-fired.
  • false (per-frame structural re-push): only refresh _context so subtrees added this frame inherit it — must not re-fire resolveContext, which would clobber an in-flight tween's value every frame.

Parameters

parent

ContextMap

runResolve

boolean

Returns

void

Inherited from

ShapeNode.bindContext


clearChildren()

clearChildren(): void

Defined in: nodes/base/node.ts:1565

Returns

void

Inherited from

ShapeNode.clearChildren


clipPathSelf()

protected clipPathSelf(): Clip | null

Defined in: nodes/base/node.ts:1806

An optional clip path that cuts through this node's own content and its children — unlike clip, which only confines children to the node's outline and leaves the node's own fill/stroke untouched. Returning null (the default) applies no such cut. Media nodes (Image, Video) expose this as an author-facing clipPath prop so a path can carve the painted frame and everything stacked on it as one.

Returns

Clip | null

Inherited from

ShapeNode.clipPathSelf


clipSelf()

protected clipSelf(): Clip | null

Defined in: nodes/base/node.ts:1713

This node's outline as a Clip command list — the single source of truth for every clip the node needs: its clip boundary (when clip is true) and the silhouette its backdrop effects (backdrop-flagged filters, magnify) are confined to. Returning null (the default) means the node has no clip outline, so its children render unclipped and it gets no backdrop effects. Nodes with a definite box (shapes via ShapeNode, layout containers like FlexNode) override this to describe their geometry — and so behave the same way for clip and effect area.

Returns

Clip | null

Inherited from

ShapeNode.clipSelf


dispose()

dispose(): void

Defined in: nodes/base/node.ts:2206

Returns

void

Inherited from

ShapeNode.dispose


ellapse()

ellapse(totalTime): void

Defined in: nodes/base/node.ts:1091

Parameters

totalTime

number

Returns

void

Inherited from

ShapeNode.ellapse


fadeTo()

fadeTo(opacity, duration, ease?): FrameGenerator

Defined in: nodes/base/node.ts:864

Animate opacity to the target value.

Parameters

opacity

number

Target opacity in the range [0, 1].

duration

number

ease?

EasingFunction

Returns

FrameGenerator

Example

yield* node.fadeTo(0, 0.3);   // fade out
yield* node.fadeTo(1, 0.3);   // fade in

Inherited from

ShapeNode.fadeTo


fillTo()

fillTo(to, duration, options?): FrameGenerator

Defined in: nodes/geometry/shape-node.ts:239

Parameters

to

Fill

duration

number

options?

TweenOptions<FillResolved[]>

Returns

FrameGenerator

Inherited from

ShapeNode.fillTo


filter()

filter(predicate): TextSelection

Defined in: nodes/text/text-node.ts:227

Select characters for which predicate returns true; adjacent hits merge.

Parameters

predicate

(char, index) => boolean

Returns

TextSelection


find()

find(text, opts?): TextSelection

Defined in: nodes/text/text-node.ts:169

Select an occurrence of text. By default the first occurrence; pass { index } to target the nth (0-based).

Parameters

text

string

opts?
index?

number

Returns

TextSelection

Example

yield* title().find("hello").to({ opacity: 0.5 }, 1);

flowChildren()

flowChildren(): Node<NodeProps>[]

Defined in: nodes/base/node.ts:1998

The children this node lays out itself — everything except the stage-pinned ones. Every measure and layout pass in a container iterates this, not children: an absolute child consumes no gap, takes no flex share, and never contributes to a hug size.

Returns the live array untouched in the common case (nothing absolute), so an ordinary tree allocates nothing per pass.

Public so the shared FlowLayout engine can read it through the FlowHost interface, the same way Rect.effectivePadding is.

Returns

Node<NodeProps>[]

Inherited from

ShapeNode.flowChildren


hitTestSelf()

protected hitTestSelf(local, tolerance): boolean

Defined in: nodes/geometry/shape-node.ts:233

Shapes hit on their outline, not their box: a click in the empty corner of a star's bounding box should fall through to whatever is behind it. The outline is the very one this node already declares for clipping (Node.clipSelf), so what is grabbable and what is drawn can never drift. Shapes that declare no outline (Text, RichText, Path) keep the base box test, which is what selection should do for them anyway.

Parameters

local

Vector2

tolerance

number

Returns

boolean

Inherited from

ShapeNode.hitTestSelf


isAutoSize()

isAutoSize(axis): boolean

Defined in: nodes/base/node.ts:1498

Parameters

axis

"width" | "height"

Returns

boolean

Inherited from

ShapeNode.isAutoSize


layout()

layout(rect, scope): void

Defined in: nodes/base/node.ts:2099

Default layout: record rect, then freeform-layout children (see layoutChildren). This is what makes a plain Node — and any ShapeNode leaf (Ellipse, Polygon, …) that doesn't override layout — able to nest children out of the box, the same way Image (via Rect) does, just with simple centered stacking instead of flex/freeform. Subclasses with their own child-layout (Rect, MaskGroup, Camera, BooleanGroup) override this and call setLayoutRect instead, so children aren't laid out twice — and call layoutAbsoluteChildren themselves.

Parameters

rect

BoxBounds

scope

MeasureScope

Returns

void

Inherited from

ShapeNode.layout


layoutAbsoluteChildren()

layoutAbsoluteChildren(scope): void

Defined in: nodes/base/node.ts:2030

Measure and place this node's stage-pinned children (see NodeProps.childPositioning).

Each one is measured against the stage's content box — so 'fill' means the whole scene, not this node — and given a layout cell whose origin is the stage origin expressed in this node's own child space. Its x/y then read as plain scene coordinates: x: 100 is 100px right of stage centre no matter how deeply it is nested.

The child stays inside this node's render scope, so ancestor opacity, blend, clip, effects, rotation and scale still compose onto it — what changes is where its box is anchored, not who draws it.

Every container calls this from its own layout, after its flow pass — including the shared FlowLayout engine through the FlowHost interface, which is why this is public rather than protected.

Parameters

scope

MeasureScope

Returns

void

Inherited from

ShapeNode.layoutAbsoluteChildren


layoutChildren()

protected layoutChildren(rect, scope): void

Defined in: nodes/base/node.ts:2114

Freeform-layout this node's flow children, centered within rect's content area: each child is measured against the padded inner box and given a BoxBounds centered on it (sized to its own measured size, capped to the content area), offsetting from center via its own x/y. Called by the default layout; nodes that run their own child-layout (Rect's flex/freeform, Camera's viewport, …) override layout instead and don't call this.

Parameters

rect

BoxBounds

scope

MeasureScope

Returns

void

Inherited from

ShapeNode.layoutChildren


line()

line(n): TextSelection

Defined in: nodes/text/text-node.ts:199

Select the nth \n-delimited line (0-based), excluding the newline.

Parameters

n

number

Returns

TextSelection


markDirty()

markDirty(): void

Defined in: nodes/base/node.ts:441

One of this node's cells went stale. Implements SignalOwner.

O(1), and deliberately does not propagate: nothing above this node caches anything derived from it. A parent's own Graphics is built from the parent's own props, and children are drawn by walking to them — which happens every frame regardless, because the renderer is immediate-mode.

Returns

void

Inherited from

ShapeNode.markDirty


match()

match(regex): TextSelection

Defined in: nodes/text/text-node.ts:186

Select every match of regex. A non-global regex matches once.

Parameters

regex

RegExp

Returns

TextSelection


measure()

measure(constraints, scope): Partial<Size2D>

Defined in: nodes/text/text-node.ts:100

Default measure: resolve width/height, hugging children stack-style on any "hug" axis. A "hug" axis shrink-wraps to the largest child extent on that axis (children overlap and are centered — they don't sum), plus this node's padding — the same content size layoutChildren lays them out in. A fixed or "fill" axis resolves as before.

This is what lets a plain Node — and any ShapeNode leaf (Ellipse, Polygon, Camera, …) that doesn't override measure — hug its children out of the box, matching how Rect's "freeform" mode measures rather than collapsing to 0 (which resolving "hug" against a content size of 0 used to do, so a hugging non-Rect container rendered nothing).

Only flow children are measured: a stage-pinned child is sized against the stage, so hugging it would shrink-wrap a box this node never contains.

Parameters

constraints

SizeConstraints

scope

MeasureScope

Returns

Partial<Size2D>

Overrides

ShapeNode.measure


moveTo()

moveTo(x, y, duration, ease?): FrameGenerator

Defined in: nodes/base/node.ts:832

Animate both x and y to the given position.

Parameters

x

number

y

number

duration

number

ease?

EasingFunction

Returns

FrameGenerator

Example

yield* node.moveTo(200, 100, 0.5, ease.outCubic);

Inherited from

ShapeNode.moveTo


moveX()

moveX(x, duration, ease?): FrameGenerator

Defined in: nodes/base/node.ts:842

Animate only the horizontal position (x).

Parameters

x

number

duration

number

ease?

EasingFunction

Returns

FrameGenerator

Example

yield* node.moveX(300, 0.4);

Inherited from

ShapeNode.moveX


moveY()

moveY(y, duration, ease?): FrameGenerator

Defined in: nodes/base/node.ts:852

Animate only the vertical position (y).

Parameters

y

number

duration

number

ease?

EasingFunction

Returns

FrameGenerator

Example

yield* node.moveY(-50, 0.4);

Inherited from

ShapeNode.moveY


onRender()

onRender(ctx): void

Defined in: nodes/base/node.ts:1864

Parameters

ctx

RenderContext

Returns

void

Inherited from

ShapeNode.onRender


overlayTo()

overlayTo(to, duration, options?): FrameGenerator

Defined in: nodes/geometry/shape-node.ts:250

Parameters

to

Fill

duration

number

options?

TweenOptions<FillResolved[]>

Returns

FrameGenerator

Inherited from

ShapeNode.overlayTo


prepareAudio()

prepareAudio(_tracker): void

Defined in: nodes/base/node.ts:1330

Register this node's audio scheduling needs on the timeline — the one asset concern that's neither drawable (like images/video/paint, inferred via TrackRenderContext) nor a simple async load (see prepareLayout): a playing clip has to be declared into the frame-ranged timeline AssetManager/AudioDevice use to keep audio in sync while scrubbing. No-op by default; Video overrides it.

Parameters

_tracker

AssetTracker

Returns

void

Inherited from

ShapeNode.prepareAudio


prepareAudioAssets()

prepareAudioAssets(tracker, path?): void

Defined in: nodes/base/node.ts:1340

Walk the subtree registering each node's audio requests (see prepareAudio). Stamps the owning node's structural path onto any audio requests emitted, so the timeline can draw each clip on its own bar — purely for display, playback ignores ownerPath.

Parameters

tracker

AssetTracker

path?

string = ""

Returns

void

Inherited from

ShapeNode.prepareAudioAssets


prepareLayout()

prepareLayout(): void | Promise<void | Disposer>

Defined in: nodes/base/node.ts:1263

Opaque async setup needed before layout — e.g. Code's syntax grammar, which tokenization/measurement depends on. Runs in the precomp pass ahead of layout, so the node cannot read its layoutRect here (it hasn't been laid out yet). Image/video/paint and font requests are no longer declared here — they're inferred automatically from the same render()/layout() calls a node already makes (see TrackRenderContext/TrackMeasureScope). No-op by default.

The framework does not await the returned promise inline (precomp stays fully synchronous) — it's fired once per frame and, when nothing changed, should return synchronously (void). Memoize like Video's syncVideo() does: key off whatever prop drives the async work and skip re-running when the key is unchanged. When the promise resolves to a Disposer, it replaces (and disposes) any previous one for this node+phase, and runs when this node is disposed.

Returns

void | Promise<void | Disposer>

Inherited from

ShapeNode.prepareLayout


prepareLayoutAssets()

prepareLayoutAssets(): void

Defined in: nodes/base/node.ts:1287

Walk the subtree firing each node's pre-layout async setup (see prepareLayout). Fire-and-forget: does not block precomp's synchronous per-frame pass.

Returns

void

Inherited from

ShapeNode.prepareLayoutAssets


prepareRender()

prepareRender(): void | Promise<void | Disposer>

Defined in: nodes/base/node.ts:1274

Opaque async setup needed before render, with the node's layoutRect available (runs after layout). No-op by default — no built-in node currently needs this timing, but it's kept symmetric with prepareLayout for custom nodes whose async setup depends on knowing their rendered size. See prepareLayout for the contract.

Returns

void | Promise<void | Disposer>

Inherited from

ShapeNode.prepareRender


prepareRenderAssets()

prepareRenderAssets(): void

Defined in: nodes/base/node.ts:1307

Walk the subtree firing each node's pre-render async setup (see prepareRender). Fire-and-forget: does not block precomp's synchronous per-frame pass.

Returns

void

Inherited from

ShapeNode.prepareRenderAssets


prepend()

prepend(text, duration, easing?): FrameGenerator

Defined in: nodes/text/text-node.ts:149

Parameters

text

string

duration

number

easing?

EasingFunction

Returns

FrameGenerator


provideContext()

protected provideContext(parent): ContextMap

Defined in: nodes/base/node.ts:1175

Providers override this to attach their token(s) to the ContextMap handed to descendants. Base passes the parent's map through unchanged.

Parameters

parent

ContextMap

Returns

ContextMap

Inherited from

ShapeNode.provideContext


reinit()

reinit(force?): void

Defined in: nodes/base/node.ts:661

Public entry point to reinitProps. A Scene owns its root node by composition (it no longer is a node), so it can't reach the protected reinitProps directly — it calls this on its root before a rebuild to restore default-baseline signals after a prior dispose, and with force to also reset live-but-tweened props back to their defaults.

Parameters

force?

boolean = false

Returns

void

Inherited from

ShapeNode.reinit


reinitProps()

protected reinitProps(force?): void

Defined in: nodes/base/node.ts:649

Re-create this node's reactive signals from their

Parameters

force?

boolean = false

Returns

void

Inherited from

ShapeNode.reinitProps


removeChild()

removeChild(child): Node<NodeProps> | null

Defined in: nodes/base/node.ts:1549

Parameters

child

Node

Returns

Node<NodeProps> | null

Inherited from

ShapeNode.removeChild


removeChildAt()

Call Signature

removeChildAt(index): Node<NodeProps> | null

Defined in: nodes/base/node.ts:1584

Parameters
index

number

Returns

Node<NodeProps> | null

Inherited from

ShapeNode.removeChildAt

Call Signature

removeChildAt(index, duration, easing?): FrameGenerator

Defined in: nodes/base/node.ts:1585

Parameters
index

number

duration

number

easing?

EasingFunction

Returns

FrameGenerator

Inherited from

ShapeNode.removeChildAt


render()

render(ctx): void

Defined in: nodes/base/node.ts:1918

Parameters

ctx

RenderContext

Returns

void

Inherited from

ShapeNode.render


renderChildren()

renderChildren(ctx): void

Defined in: nodes/base/node.ts:1886

Parameters

ctx

RenderContext

Returns

void

Inherited from

ShapeNode.renderChildren


renderContentWithEffects()

protected renderContentWithEffects(ctx, body): void

Defined in: nodes/base/node.ts:1859

Run body (this node's own painting + children) inside the node's effect and clip-path scopes — the shared content-rendering envelope every node uses so effects behave identically regardless of how a node draws. The caller is expected to have already pushed the node's transform (applyTransform). The envelope, outermost-first:

  1. applyBackdropEffects — filters/warps the backdrop beneath the node, confined to its clipSelf silhouette.
  2. A foreground effect scope (posterize wrapping bulge) capturing everything body paints, so those shader effects warp/band the lot.
  3. A clipPathSelf clip cutting through both the node's own paint and its children.

Nodes with a bespoke onRender (boolean, mask, …) call this with their custom body to gain the same effect support as a standard shape, instead of duplicating the scope bookkeeping.

Parameters

ctx

RenderContext

body

() => void

Returns

void

Inherited from

ShapeNode.renderContentWithEffects


renderOverlay()

protected renderOverlay(ctx): void

Defined in: nodes/text/text-node.ts:369

Paint the node's overlay layer — over its own fill and its children, but under the stroke — clipped to the node's silhouette. Called from onRender after children render and before renderStroke. No-op by default; ShapeNode paints the resolved overlay as a fill of its silhouette so a texture (e.g. VHS grain) sits over the whole subtree.

Parameters

ctx

RenderContext

Returns

void

Overrides

ShapeNode.renderOverlay


renderSelf()

protected renderSelf(ctx): void

Defined in: nodes/text/text-node.ts:353

Shadow + fill of the node's own silhouette.

Hoisted here from the eight geometry subclasses that each had this exact body, so the memo has one place to live rather than eight. A subclass whose paint differs (Path, Image, Video) still overrides it.

Parameters

ctx

RenderContext

Returns

void

Overrides

ShapeNode.renderSelf


renderStroke()

protected renderStroke(ctx): void

Defined in: nodes/text/text-node.ts:377

Paint the node's stroke last — over its fill, children, and overlay. Deferred out of renderSelf (which now draws only shadow+fill) so the stroke frames the whole subtree and sits above any overlay. Called from onRender after renderOverlay. No-op by default; ShapeNode strokes its silhouette.

Parameters

ctx

RenderContext

Returns

void

Overrides

ShapeNode.renderStroke


reparent()

Call Signature

reparent(newParent): void

Defined in: nodes/base/node.ts:2180

Parameters
newParent

Node

Returns

void

Inherited from

ShapeNode.reparent

Call Signature

reparent(newParent, duration, easing?): FrameGenerator

Defined in: nodes/base/node.ts:2181

Parameters
newParent

Node

duration

number

easing?

EasingFunction

Returns

FrameGenerator

Inherited from

ShapeNode.reparent


resolveContext()

protected resolveContext(_ctx): void

Defined in: nodes/text/text-node.ts:86

Hook for applying inherited context values to this node, once, after the node is linked into the tree and the context walk has resolved its ancestors' providers — the first moment useContext returns real values (the constructor runs before the node is linked, so it can't read context).

Runs exactly once per node instance: the runtime rebuilds the subtree on every reset/scrub/precomp rather than replaying this hook, so there is no "each pass" re-entry to guard against — never call clearChildren or write idempotency ceremony here.

Composition rule

Structure (which children exist, and how many) is built in the constructor via add from props — never here, and never from context. This hook applies context-derived values only: read the resolved value from ctx (or useContext) and write it onto the already-built structure, typically through refs captured in the constructor.

Parameters

_ctx

ContextMap

Returns

void

Example

// constructor: this.add(<Rect ref={this.accent} … />)   // structure from props
protected override resolveContext(ctx: ContextMap): void {
  this.accent().set({ fill: ctx.get(ThemeToken).accent }); // value from context
}

Overrides

ShapeNode.resolveContext


resolveSizeInput()

resolveSizeInput(sizeInput, availableSize, childrenSize): number

Defined in: nodes/base/node.ts:1502

Parameters

sizeInput

SizeInput

availableSize

number

childrenSize

number

Returns

number

Inherited from

ShapeNode.resolveSizeInput


restore()

Call Signature

restore(): void

Defined in: nodes/base/node.ts:1062

Pop the most recent save snapshot and roll this node back to it.

Called with no duration (or 0), every prop is reapplied instantly — plain values are set, reactive bindings are re-bound. Called with a positive duration, the numeric props (and any with a custom tween) animate toward their saved values over that many seconds; once the tween finishes the full snapshot is reapplied, which re-binds any reactive props and snaps non-tweenable props (e.g. strings) to their saved values.

A no-op (returns immediately) if there is nothing on the stack.

Returns

void

Inherited from

ShapeNode.restore

Call Signature

restore(duration, easing?): FrameGenerator

Defined in: nodes/base/node.ts:1063

Pop the most recent save snapshot and roll this node back to it.

Called with no duration (or 0), every prop is reapplied instantly — plain values are set, reactive bindings are re-bound. Called with a positive duration, the numeric props (and any with a custom tween) animate toward their saved values over that many seconds; once the tween finishes the full snapshot is reapplied, which re-binds any reactive props and snaps non-tweenable props (e.g. strings) to their saved values.

A no-op (returns immediately) if there is nothing on the stack.

Parameters
duration

number

Seconds to animate the rollback over. Omit for an instant restore.

easing?

EasingFunction

Optional easing for the animated restore.

Returns

FrameGenerator

Inherited from

ShapeNode.restore


rotateTo()

rotateTo(rotation, duration, ease?): FrameGenerator

Defined in: nodes/base/node.ts:874

Animate rotate to the target angle (degrees, clockwise).

Parameters

rotation

number

duration

number

ease?

EasingFunction

Returns

FrameGenerator

Example

yield* node.rotateTo(180, 0.6, ease.inOutQuad);

Inherited from

ShapeNode.rotateTo


sample()

sample(): void

Defined in: nodes/base/node.ts:1116

Per-frame sampling of derived render state (currently motion). Recurses to children so the whole subtree is sampled in one pass. Called from ellapse every frame; kept as a named seam so the priming path can seed the same state without a full ellapse (see StateEvaluator.resetSlot).

Returns

void

Inherited from

ShapeNode.sample


save()

save(): void

Defined in: nodes/base/node.ts:1043

Push a snapshot of this node's current state onto its save stack.

Every reactive prop (x, y, scale, opacity, fill, …) is captured, preserving reactive bindings — a prop bound to () => other().x is saved as the binding, not just its resolved value, so restore re-binds it rather than freezing the value. Calls stack: each save() pushes a new layer, and each restore pops the most recent one.

Returns

void

Example

node.save();
yield* node.moveTo(200, 0, 1);
yield* node.restore(1);   // animate back to where it was saved

Inherited from

ShapeNode.save


scaleTo()

scaleTo(scale, duration, ease?): FrameGenerator

Defined in: nodes/base/node.ts:885

Animate scale to the target factor.

Parameters

scale

number

duration

number

ease?

EasingFunction

Returns

FrameGenerator

Example

yield* node.scaleTo(1.5, 0.4);   // grow
yield* node.scaleTo(0,   0.3);   // shrink to nothing

Inherited from

ShapeNode.scaleTo


set()

set(props): void

Defined in: nodes/base/node.ts:705

Parameters

props
blend?

"color" | "multiply" | "screen" | "overlay" | "darken" | "lighten" | "color-dodge" | "color-burn" | "hard-light" | "soft-light" | "difference" | "exclusion" | "hue" | "saturation" | "luminosity" | "normal" | "pass-through" | (() => "color" | "multiply" | "screen" | "overlay" | "darken" | "lighten" | "color-dodge" | "color-burn" | "hard-light" | "soft-light" | "difference" | "exclusion" | "hue" | "saturation" | "luminosity" | "normal" | "pass-through")

Layer blend mode. 'pass-through' (default) does not isolate the node — its opacity scales each child/fill while they blend against the backdrop. Any other mode isolates the node and blends its flattened result against the backdrop.

bottomCenter?

Vector2 | (() => Vector2) | (() => Vector2 | (() => Vector2))

bottomLeft?

Vector2 | (() => Vector2) | (() => Vector2 | (() => Vector2))

bottomRight?

Vector2 | (() => Vector2) | (() => Vector2 | (() => Vector2))

center?

Vector2 | (() => Vector2) | (() => Vector2 | (() => Vector2))

centerLeft?

Vector2 | (() => Vector2) | (() => Vector2 | (() => Vector2))

centerRight?

Vector2 | (() => Vector2) | (() => Vector2 | (() => Vector2))

childPositioning?

ChildPositioning | (() => ChildPositioning)

Frame of reference this node lays its children out in. 'relative' (default) positions them inside this node's own content box; 'absolute' pins them to the stage instead, so their x/y are scene-root coordinates and this node's flow/gap/padding no longer place them. Overridden per child by relativeToParent.

children?

NodeChildren | (() => NodeChildren)

Child nodes. A single Node, or an arbitrarily-nested array of them — the constructor flattens nesting (.flat(Infinity)), so .map() results can be dropped in directly as a child without spreading, like React.

clip?

boolean | (() => boolean)

When true, content drawn outside this node's outline is clipped away (see Node.clipSelf).

colSpan?

number | (() => number)

How many grid columns this child spans. Default 1.

column?

number | (() => number)

1-based column index for explicit grid placement. Undefined = auto-placed.

effects?

Effect | (() => Effect)

end?

number | (() => number | undefined)

fill?

Fill | (() => Fill | undefined)

Fill layer(s). Each item can be:

  • A plain CSS color string → treated as a solid fill
  • A fill prop object (SolidFillProp, LinearGradientFillProp, …)
  • An already-resolved fill object
  • A FillChain from the Fills builder (e.g. Fills.color('red'))
flex?

number | (() => number)

Proportional share of the free space along the parent's main axis, relative to sibling fill children (like Flutter's Expanded(flex:)). Only meaningful when this node fills the main axis — in a row that's width:'fill', in a column height:'fill'. Two siblings with flex 2 and 1 split the free space 2:1. Defaults to 1. Specifying flex without an explicit width/height defaults both to 'fill'.

fontFamily?

string | (() => string)

fontSize?

number | "autofit" | (() => number | "autofit")

fontStyle?

FontStyle | (() => FontStyle)

fontWeight?

number | (() => number)

height?

SizeInput | (() => SizeInput)

letterSpacing?

number | (() => number)

lineHeight?

number | (() => number)

minFontSize?

number | (() => number)

opacity?

number | (() => number)

overlay?

Fill | (() => Fill | undefined)

Overlay layer(s) — the same loose values as fill, but painted over this node's fill and its children (clipped to the node's silhouette) while still sitting under the stroke. Use for textures laid across the whole subtree, e.g. a VHS-grain image or video.

padding?

Insets | (() => Insets)

Inner spacing between this node's edges and its content/children.

path?

PathData | PathBuilder | (() => PathData | PathBuilder)

Wrap the text around a path (text-on-path). Accepts the same value shapes as the Path node's d: an SVG path string, a PathCommand[], or a PathBuilder. When set, wrap and multi-line (\n) are ignored (single line), and text selections are not applied.

pivot?

Anchor | (() => Anchor)

Pivot point for rotation and scale. Either a named anchor ('center', 'topRight', 'bottomLeft', … — the node align vocabulary) or an explicit Vector2: (0,0)=center, (-1,1)=top-left, (1,-1)=bottom-right. Set automatically when an anchor positioning prop is used.

relativeToParent?

RelativeToParent | (() => RelativeToParent)

This node's own override of its parent's childPositioning. 'inherit' (default) takes whatever the parent declared; 'relative' and 'absolute' opt this one node in or out regardless.

rotation?

number | (() => number)

row?

number | (() => number)

1-based row index for explicit grid placement. Undefined = auto-placed.

rowSpan?

number | (() => number)

How many grid rows this child spans. Default 1.

scale?

number | (() => number)

seed?

string | number | (() => string | number)

Origin seed for this node's Node.random source. Defaults to 0. Set it to give the node a reproducible-but-distinct random stream without re-seeding by hand. The constructor adopts it as random's origin, and the runtime rebuilds the node each playback pass, so draws stay reproducible across scrub/precomp/HMR.

shadow?

Shadow | (() => Shadow | undefined)

Shadow layer(s): a single ShadowProp, an array of them, or an already-resolved shadow. fill inside each shadow accepts the same loose values as the top-level fill prop.

size?

SizeInput | (() => SizeInput)

Sets width and height to the same value in one go. Pure sugar: at construction time, an author-facing size is expanded into width/ height before either is applied. Explicit width or height takes precedence over size (mirroring padding's side-vs-shorthand rule), so { size: 200, width: 100 } yields width: 100, height: 200. Reactive bindings and to()/set() targets both work the same as width/heightsize: 'fill', size: () => ..., or node.to({ size: 300 }, 0.5) are all valid.

start?

number | (() => number | undefined)

stroke?

Stroke | (() => Stroke | undefined)

Stroke layer(s): a single StrokeProp, an array of them, or an already-resolved stroke. fill inside each stroke accepts the same loose values as the top-level fill prop.

text?

string | (() => string)

textAlign?

TextAlign | (() => TextAlign)

topCenter?

Vector2 | (() => Vector2) | (() => Vector2 | (() => Vector2))

topLeft?

Vector2 | (() => Vector2) | (() => Vector2 | (() => Vector2))

topRight?

Vector2 | (() => Vector2) | (() => Vector2 | (() => Vector2))

variant?

string | (() => string)

Name of a typography preset from theme.typography (e.g. "header"). Supplies any text-style prop (fontSize, fontWeight, …) not set explicitly here. An explicit prop always wins over the preset; the preset wins over an inherited <DefaultTextStyle>.

width?

SizeInput | (() => SizeInput)

wrap?

boolean | (() => boolean)

x?

number | (() => number)

y?

number | (() => number)

Returns

void

Inherited from

ShapeNode.set


setLayoutRect()

protected setLayoutRect(rect): void

Defined in: nodes/base/node.ts:1950

Record this node's allocated bounds without touching children. Used by subclasses that run their own child-layout pass (e.g. Rect's flex/freeform) and so skip layoutChildren.

Compared field by field first, because Signal.set's own Object.is guard can never fire here: every caller builds a fresh object literal (layout/flow-layout.ts, flow-engine.ts, layoutFlex, flex-node.ts, grid-node.ts, line-grid-node.ts, root-node.ts), so identity always differs — including on every frame of a node that is simply sitting still. Without this guard every node reports a changed layout on every frame, and no amount of dirty-tracking above can ever conclude otherwise.

Parameters

rect

BoxBounds

Returns

void

Inherited from

ShapeNode.setLayoutRect


shadowTo()

shadowTo(to, duration, options?): FrameGenerator

Defined in: nodes/geometry/shape-node.ts:272

Parameters

to

Shadow

duration

number

options?

TweenOptions<ShadowResolved[]>

Returns

FrameGenerator

Inherited from

ShapeNode.shadowTo


shapeGraphics()

protected shapeGraphics(): Graphics | null

Defined in: nodes/geometry/shape-node.ts:107

The node's bare silhouette as a Graphics with no paint ops. renderSelf appends shadow + fill; renderOverlay appends the overlay fill; renderStroke appends the stroke. Sharing one builder keeps each shape's geometry defined in a single place.

Returns null for nodes that have no single fillable silhouette (text, boolean groups, grids) — those override the paint hooks themselves or opt out of the generic overlay/stroke passes.

Returns

Graphics | null

Inherited from

ShapeNode.shapeGraphics


slice()

slice(start, end): TextSelection

Defined in: nodes/text/text-node.ts:222

Select the raw character range [start, end).

Parameters

start

number

end

number

Returns

TextSelection


strokeTo()

strokeTo(to, duration, options?): FrameGenerator

Defined in: nodes/geometry/shape-node.ts:261

Parameters

to

Stroke

duration

number

options?

TweenOptions<StrokeResolved[]>

Returns

FrameGenerator

Inherited from

ShapeNode.strokeTo


tick()

tick(_globalTime): void

Defined in: nodes/base/node.ts:1082

Parameters

_globalTime

number

Returns

void

Inherited from

ShapeNode.tick


to()

to(to, duration, easing?): AnimationBuilder<TextProps>

Defined in: nodes/base/node.ts:724

Parameters

to

Partial<P>

duration

number

easing?

EasingFunction

Returns

AnimationBuilder<TextProps>

Inherited from

ShapeNode.to


tryAssets()

protected tryAssets(): AssetCatalog | null

Defined in: nodes/base/node.ts:300

Returns the bound asset catalog, or null if this node hasn't been bound yet.

Returns

AssetCatalog | null

Inherited from

ShapeNode.tryAssets


useContext()

useContext<T>(ctx): T

Defined in: nodes/base/node.ts:321

Read the nearest ancestor provider's value for ctx (or its default).

Type Parameters

T

T

Parameters

ctx

Context<T>

Returns

T

Inherited from

ShapeNode.useContext


wiggle()

wiggle(amplitudes, duration, options?): FrameGenerator

Defined in: nodes/base/node.ts:948

Continuously jitter one or more numeric props around their current values for duration seconds, then settle them back exactly where they started.

The target reads like to — an object of prop → amplitude rather than prop → target — so you name props as typed object keys, never string arguments, and can jitter several at once: wiggle({ x: 8, rotation: 2 }, 0.6). Each value is the peak offset from that prop's base, in the prop's own units. Call-wide shaping (frequency, settle) goes in the trailing WiggleOptions bag, mirroring how TweenOptions bundles its knobs.

Unlike to(), which drives a prop to a target, wiggle adds an organic offset on top of a fixed base — each prop's value at the moment the generator starts. Offsets are drawn from this node's seeded random noise field, so they are correlated over time (nearby frames get nearby offsets) rather than the jagged jumps independent draws would give — the difference that makes it read as hand-held shake / drift rather than static. Because the source is seeded per node, the motion is reproducible across scrub / precomp / HMR out of the box.

The offset rides on each prop's stored numeric value, so raw props (x, rotation, …) and mapped props that resolve to a plain number both wiggle correctly. A prop whose stored value isn't a number — width: 'fill', or a per-corner cornerRadius object — has no scalar to offset, so it's skipped with a dev-time warning rather than producing NaN.

The bases are captured once, so wiggle composes: run it inside parallel alongside a to() on other props, or give sibling nodes distinct seeds (via the NodeProps.seed prop) so a crowd wiggles out of phase. Every prop's offset eases to zero over the final settle fraction so it lands back on its base without a visible snap.

Parameters

amplitudes

Map of prop → peak offset from its base, in the prop's own units. Same key shape as to's target ({ x, y, rotation, … }).

blend?

number

Layer blend mode. 'pass-through' (default) does not isolate the node — its opacity scales each child/fill while they blend against the backdrop. Any other mode isolates the node and blends its flattened result against the backdrop.

bottomCenter?

number

bottomLeft?

number

bottomRight?

number

center?

number

centerLeft?

number

centerRight?

number

childPositioning?

number

Frame of reference this node lays its children out in. 'relative' (default) positions them inside this node's own content box; 'absolute' pins them to the stage instead, so their x/y are scene-root coordinates and this node's flow/gap/padding no longer place them. Overridden per child by relativeToParent.

children?

number

Child nodes. A single Node, or an arbitrarily-nested array of them — the constructor flattens nesting (.flat(Infinity)), so .map() results can be dropped in directly as a child without spreading, like React.

clip?

number

When true, content drawn outside this node's outline is clipped away (see Node.clipSelf).

colSpan?

number

How many grid columns this child spans. Default 1.

column?

number

1-based column index for explicit grid placement. Undefined = auto-placed.

effects?

number

end?

number

fill?

number

Fill layer(s). Each item can be:

  • A plain CSS color string → treated as a solid fill
  • A fill prop object (SolidFillProp, LinearGradientFillProp, …)
  • An already-resolved fill object
  • A FillChain from the Fills builder (e.g. Fills.color('red'))
flex?

number

Proportional share of the free space along the parent's main axis, relative to sibling fill children (like Flutter's Expanded(flex:)). Only meaningful when this node fills the main axis — in a row that's width:'fill', in a column height:'fill'. Two siblings with flex 2 and 1 split the free space 2:1. Defaults to 1. Specifying flex without an explicit width/height defaults both to 'fill'.

fontFamily?

number

fontSize?

number

fontStyle?

number

fontWeight?

number

height?

number

letterSpacing?

number

lineHeight?

number

minFontSize?

number

opacity?

number

overlay?

number

Overlay layer(s) — the same loose values as fill, but painted over this node's fill and its children (clipped to the node's silhouette) while still sitting under the stroke. Use for textures laid across the whole subtree, e.g. a VHS-grain image or video.

padding?

number

Inner spacing between this node's edges and its content/children.

path?

number

Wrap the text around a path (text-on-path). Accepts the same value shapes as the Path node's d: an SVG path string, a PathCommand[], or a PathBuilder. When set, wrap and multi-line (\n) are ignored (single line), and text selections are not applied.

pivot?

number

Pivot point for rotation and scale. Either a named anchor ('center', 'topRight', 'bottomLeft', … — the node align vocabulary) or an explicit Vector2: (0,0)=center, (-1,1)=top-left, (1,-1)=bottom-right. Set automatically when an anchor positioning prop is used.

relativeToParent?

number

This node's own override of its parent's childPositioning. 'inherit' (default) takes whatever the parent declared; 'relative' and 'absolute' opt this one node in or out regardless.

rotation?

number

row?

number

1-based row index for explicit grid placement. Undefined = auto-placed.

rowSpan?

number

How many grid rows this child spans. Default 1.

scale?

number

seed?

number

Origin seed for this node's Node.random source. Defaults to 0. Set it to give the node a reproducible-but-distinct random stream without re-seeding by hand. The constructor adopts it as random's origin, and the runtime rebuilds the node each playback pass, so draws stay reproducible across scrub/precomp/HMR.

shadow?

number

Shadow layer(s): a single ShadowProp, an array of them, or an already-resolved shadow. fill inside each shadow accepts the same loose values as the top-level fill prop.

size?

number

Sets width and height to the same value in one go. Pure sugar: at construction time, an author-facing size is expanded into width/ height before either is applied. Explicit width or height takes precedence over size (mirroring padding's side-vs-shorthand rule), so { size: 200, width: 100 } yields width: 100, height: 200. Reactive bindings and to()/set() targets both work the same as width/heightsize: 'fill', size: () => ..., or node.to({ size: 300 }, 0.5) are all valid.

start?

number

stroke?

number

Stroke layer(s): a single StrokeProp, an array of them, or an already-resolved stroke. fill inside each stroke accepts the same loose values as the top-level fill prop.

text?

number

textAlign?

number

topCenter?

number

topLeft?

number

topRight?

number

variant?

number

Name of a typography preset from theme.typography (e.g. "header"). Supplies any text-style prop (fontSize, fontWeight, …) not set explicitly here. An explicit prop always wins over the preset; the preset wins over an inherited <DefaultTextStyle>.

width?

number

wrap?

number

x?

number

y?

number

duration

number

Seconds to wiggle for. Pass Infinity inside a parallel for an endless jitter bounded by its siblings (no settle is applied to an infinite wiggle).

options?

WiggleOptions

Call-wide WiggleOptions: frequency (default 4) and settle. frequency applies to every prop; for a per-prop rate, use a second wiggle in the same parallel.

Returns

FrameGenerator

Examples

// Shake horizontally for a beat, then rest exactly where it began:
yield* node.wiggle({ x: 8 }, 0.6);
// A faster shake with a hard cut (no ease-out) at the end:
yield* node.wiggle({ x: 12, y: 12 }, 1, { frequency: 8, settle: 0 });
// Hand-held drift while it moves across (offset composes with the move):
yield* parallel(
  node.moveX(400, 2),
  node.wiggle({ y: 6, rotation: 2 }, 2, { frequency: 3 }),
);

Inherited from

ShapeNode.wiggle


word()

word(n): TextSelection

Defined in: nodes/text/text-node.ts:216

Select the nth whitespace-delimited word (0-based).

Parameters

n

number

Returns

TextSelection


words()

words(): TextSelection

Defined in: nodes/text/text-node.ts:211

Select every whitespace-delimited word.

Returns

TextSelection


worldMatrix()

protected worldMatrix(): Matrix2D

Defined in: nodes/base/node.ts:1439

This node's full transform in canvas (y-down) world space — the product of every ancestor's local matrix from the root down to this node. Reactive: walks the live parent chain and reads each node's transform signals.

Returns

Matrix2D

Inherited from

ShapeNode.worldMatrix


flattenChildrenProp()

protected static flattenChildrenProp(props): Node<NodeProps>[]

Defined in: nodes/base/node.ts:555

Flatten a constructor's raw children prop into the Node instances it contains, without mutating or adding them — the same normalisation the constructor applies before addChildren, exposed standalone so applyDefaultSize overrides can inspect children's own resolved width/height before they're attached (JSX children are constructed, defaults and all, before being passed in as props).

Parameters

props

{ children?: unknown; } | undefined

Returns

Node<NodeProps>[]

Inherited from

ShapeNode.flattenChildrenProp


flowChildrenProp()

protected static flowChildrenProp(props): Node<NodeProps>[]

Defined in: nodes/base/node.ts:573

flattenChildrenProp, narrowed to the children this node will actually lay out — a stage-pinned child (see NodeProps.childPositioning) is neither measured against this box nor placed in its flow, so it can't inform the size defaults either.

Reads the raw childPositioning off props rather than this, because applyDefaultSize runs from the constructor before the prop cells are applied. Each child's own relativeToParent is already resolved — JSX children are fully constructed before they arrive here.

Parameters

props

{ childPositioning?: unknown; children?: unknown; } | undefined

Returns

Node<NodeProps>[]

Inherited from

ShapeNode.flowChildrenProp


hasFillChild()

protected static hasFillChild(children, axis): boolean

Defined in: nodes/base/node.ts:589

True if any of children requests "fill" on axis — the signal a container's applyDefaultSize override uses to decide whether its own hug default on that axis would strand the child with no space to fill into (see Rect/FlexNode overrides).

Parameters

children

Node<NodeProps>[]

axis

"width" | "height"

Returns

boolean

Inherited from

ShapeNode.hasFillChild


memoizeDrawing()

static memoizeDrawing(ctor): void

Defined in: nodes/geometry/shape-node.ts:163

Internal

Parameters

ctor

Function

Returns

void

Inherited from

ShapeNode.memoizeDrawing