Interactive canvases

A canvas is a small state machine that lives in the mascot's bundle. Each state plays an animation, inputs are values your app sets (booleans, numbers, one-shot triggers), and transitions move between states when their conditions hold, blending poses so nothing snaps. Your code never picks animations directly; it just reports what is happening.

$ claude "fix the flaky auth test"

The ai_agent template, running live. Press a button: the demo sets status 1, 2, 3 or 4 as a build progresses.

How canvases work#

• The canvas starts in its initial state.
• Whenever an input changes, transitions are checked in order; the first one whose from matches the current state (or is *) and whose conditions all hold wins. A transition into the state you are already in is skipped unless it is a trigger.
• Triggers are momentary: fire("greet") is true for that one evaluation, then clears.
• A non-looping state plays its clip once, then moves to its then state with a 0.2 s blend.
• Each transition's blend (0–2 seconds) cross-fades from the pose the mascot was in, so interruptions look intentional.

Templates#

Three ready-made graphs cover the common cases. They only use presets, so they work on every mascot without any custom motion. List them with GET/canvas-templates (no key needed).

Create a canvas#

POST/mascots/{id}/canvases

One of template or graph is required. Canvases are free: no model call, no credits. The response is the canvas with its full graph.

curl -X POST https://lumorig.com/api/v1/mascots/msc_…/canvases -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "assistant", "template": "chatbot" }'
# 201 → { "id": "cnv_…", "object": "canvas", "name": "assistant", "template": "chatbot", "graph": { … } }

Updating and deleting#

Drive it from your app#

Every canvas ships inside the mascot's bundle, keyed by name. Set the canvas attribute on the player, then call setInput and fire as things happen. Listen for statechange if your UI wants to follow along.

const pip = document.querySelector("lumorig-player");
pip.setAttribute("canvas", "assistant");

pip.fire("greet");                                   // waves once, back to idle
input.addEventListener("focus", () => pip.setInput("listening", true));
chat.on("request", () => pip.setInput("thinking", true));
chat.on("token", () => pip.setInput("talking", true));
chat.on("done", () => {
  pip.setInput("thinking", false);
  pip.setInput("talking", false);
  pip.setInput("listening", false);
});

pip.addEventListener("statechange", (e) => console.log(e.detail.state));

<lumorig-player src="…/bundle" canvas="assistant"></lumorig-player>

pip.canvas = "assistant" and pip.setAttribute("canvas", "assistant") are equivalent; the property mirrors the attribute.

AI agents and the terminal#

The ai_agent template takes a single number, status: 0 idle, 1 working, 2 waiting for you, 3 done, 4 failed. That is exactly what the terminal companion sets from Claude Code hooks, and you can set it from any agent loop the same way.

Graph format#

A CanvasGraph is plain JSON. Names (inputs and state ids) are snake_case. This is the onboarding template in full:

{
  "canvasVersion": 1,
  "inputs": [
    {
      "name": "hello",
      "type": "trigger",
      "default": null
    },
    {
      "name": "success",
      "type": "trigger",
      "default": null
    },
    {
      "name": "error",
      "type": "trigger",
      "default": null
    }
  ],
  "states": [
    {
      "id": "idle",
      "animation": "idle",
      "loop": true,
      "then": null
    },
    {
      "id": "hello",
      "animation": "wave",
      "loop": false,
      "then": "idle"
    },
    {
      "id": "success",
      "animation": "celebrate",
      "loop": false,
      "then": "idle"
    },
    {
      "id": "error",
      "animation": "sad",
      "loop": false,
      "then": "idle"
    }
  ],
  "initial": "hello",
  "transitions": [
    {
      "from": "*",
      "to": "hello",
      "when": [
        {
          "input": "hello",
          "op": "fired",
          "value": null
        }
      ],
      "blend": 0.2
    },
    {
      "from": "*",
      "to": "success",
      "when": [
        {
          "input": "success",
          "op": "fired",
          "value": null
        }
      ],
      "blend": 0.15
    },
    {
      "from": "*",
      "to": "error",
      "when": [
        {
          "input": "error",
          "op": "fired",
          "value": null
        }
      ],
      "blend": 0.2
    }
  ]
}

Conditions#

Validation rules#

Graphs are checked when you create or update a canvas. Problems come back as 400 invalid_request with one line per problem in error.details:

• initial must be one of the states.
• Every state's animation must exist on the mascot: a preset id, or the id or name of a saved animation.
• A non-looping state needs then, and then must be a real state.
• Every transition's from (unless *) and to must be real states, and every condition must name a declared input.
• fired needs a trigger input; eq, gt and lt need a number input and a non-null value.