Creating actors

1. Choose the owner

Three repositories, and the choice is not negotiable by convenience:

Keep the actor, view, renderer and feature exports colocated. Do not create a family folder in the runtime repo to work around a missing library abstraction — that is the abstraction asking to be written.

2. Implement the actor

Use the primitives intentionally. The Reactivity section has the full decision table; the short version:

import { LayoutActor, group, layoutGroup, signal } from "@motionactor/core";

export class Image extends LayoutActor {
  layout = layoutGroup({
    width: 320,
    height: 180,
  });

  content = group({
    src: signal(""),
    objectFit: signal<"cover" | "contain">("cover"),
  });
}

Rules

• Authored durations are seconds, never frames.
• Keep actor state semantic and renderer-agnostic. isHighlighted, not borderColor.
• Prefer object parameters for commands with more than one scalar argument.
• Prefer semantic commands over direct signal tweening as the main authoring surface — card.reveal({ duration }) reads better than three tweens at every call site, and it keeps the motion in one place when it changes.
• LayoutActor already declares layout, transform, appearance, flexItem and gridItem. Override layout = layoutGroup({...}) to change defaults rather than redeclaring the group.

Layout authoring

• layout is authored input; localLayout and worldLayout are resolved output.
• layout.x, layout.y, layout.width and layout.height accept numbers, pct(n), or percentage strings like "50%".
• Root actors resolve percentages against the scene viewport. Nested positioned actors resolve against their containing block — usually the nearest positioned ancestor's local box.
• Resolved boxes are always numeric, even when the authored value was a percentage.
• Renderers size their element, SVG, canvas or backend surface from resolved localLayout.

3. Give it a render path

Every visual actor needs one:

• an actor render(...) method — preferred for React-first visual actors, or
• a defineActorRenderer(...) renderer — valid for migration, specialization and renderer overrides, or
• both, when a renderer overrides a default.

When both exist they share one render-time model: actor is resolved frame state, slots is rendered child placement, targets is the render-facing target projection.

Nonvisual actors need behavioral examples instead of a visual demo.

View rules

• Keep className static.
• Compute dynamic visual values into local variables and pass them through style.
• Do not use generic signal-reader helpers or string-key probing when the actor type is known.
• Do the geometry in derived on the actor, not in the view. The view should read finished numbers — see the Desktop example.

4. Wire the exports

• Feature barrel: <family>/src/<feature>/index.ts
• Family package root: <family>/src/index.ts
• Primitive package root: packages/primitives/src/index.ts

5. Demonstrate it

Visual actors get a showcase composition in the owning library, built with defineSceneComposition(...). Nonvisual actors get a behavioral test instead — see Testing.