RouteVN Creator Model

Shared RouteVN domain model package.

Repo rules and contribution expectations are in GUIDELINES.md.

Schema compatibility maintenance rules are in docs/schema-compatibility.md.

This repo is intended to be the single source of truth for:

• state validation
• command payload validation
• state-aware command preconditions
• command-to-state reduction

It is intentionally not responsible for:

• Insieme transport
• Insieme storage
• partition routing
• actors, tokens, client timestamps

Those stay in the client and server repos.

Public API

SCHEMA_VERSION;

validateState({ state });

validatePayload({ type, payload });

validateAgainstState({
  state,
  command: { type, payload },
});

processCommand({
  state,
  command: { type, payload },
});

replayCommands({
  state,
  commands: [{ type, payload }],
});

SCHEMA_VERSION is the exported schema version constant for persisted command compatibility.

Validation functions return:

{
  valid: true;
}

or:

{
  valid: false,
  error: {
    kind: "state" | "payload" | "precondition" | "invariant",
    code: "payload_validation_failed",
    message: "payload.data.foo is not allowed",
    path: "payload.data.foo", // only when available
    details: {}, // only when available
  },
}

processCommand() returns:

{ valid: true, state: nextState }

replayCommands() returns the same result shape while applying a trusted command tape against a single working state clone. It is intended for batch history reconstruction paths such as offline repository boot/import replay, where validating the full state before and after every individual command is needlessly expensive.

Design rules:

• no classes
• pure functions whenever possible
• command payload shape is validated separately from state-aware preconditions
• SCHEMA_VERSION is the source of truth for persisted command schema versioning
• SCHEMA_VERSION must stay aligned with the minor version from package.json
• patch releases must not change persisted schema compatibility
• bun run test:compat is the required compatibility gate for model changes
• processCommand() is the authoritative state transition
• replayCommands() is the fast batch replay path for trusted command tapes
• model state should contain project-owned runtime data only
• app-owned metadata like project id, name, and description should stay out of this package
• project may start empty; fields like resolution are optional until the model starts owning them
• random ids across RouteVN should use nanoid with the RouteVN base58 variant; deterministic derived tokens such as partition hashes are a separate case

Font Weight Metadata

Font resources may store extracted weight capabilities in three flat fields:

{
  minWeight: 100,
  defaultWeight: 400,
  maxWeight: 900,
}

The fields are optional for compatibility with existing font resources. When one is present, all three are required and must satisfy 1 <= minWeight <= defaultWeight <= maxWeight <= 1000. Static fonts store the same value in all three fields; variable fonts store their fvar wght axis range and default.

Text Style Font References

textStyle.fontId accepts either one font ID or a non-empty array of unique font IDs. Both forms are persisted as supplied, and every ID must reference an existing non-folder font:

{
  fontId: "font-primary";
}
{
  fontId: ["font-primary", "font-fallback"];
}

Computed Variables

Variables support read-only computed definitions for string, number, boolean, and object results. The presence of computed is the source discriminator; computed variables omit stored scope, default, and value fields:

{
  id: "hpPercent",
  type: "variable",
  variableType: "number",
  name: "HP Percent",
  computed: {
    expr: {
      round: [
        {
          mul: [
            {
              div: [
                { var: "variables.hp" },
                { var: "variables.maxHp" },
              ],
            },
            100,
          ],
        },
      ],
    },
  },
}

Computed definitions may use a simple expr or literal value, or ordered branches with an explicit default. Validation enforces the Route Engine operator grammar, result types, concrete variables.*/runtime.* paths, declared variable references, and an acyclic computed dependency graph.

Computed definitions may also store examples. Example inputs mirror the evaluation context, while calculated results remain derived and are not persisted:

{
  computed: {
    expr: {
      mul: [
        {
          div: [
            { var: "variables.hp" },
            { var: "variables.maxHp" },
          ],
        },
        100,
      ],
    },
    examples: [
      {
        id: "example-low-health",
        name: "Low health",
        input: {
          variables: {
            hp: 40,
            maxHp: 80,
          },
        },
      },
    ],
  },
}

File Structure

src/
  index.js
  errors.js
  helpers.js
  model.js
tests/
  model-api.test.js
  command-direct-coverage.test.js
  project.create.spec.yaml
  story-and-scenes.spec.yaml
  scenes-advanced.spec.yaml
  sections-and-lines.spec.yaml
  images.spec.yaml
  sounds-and-videos.spec.yaml
  animations.spec.yaml
  audio-effects.test.js
  audio-effects-drift.test.js
  fonts-and-colors.spec.yaml
  transforms-variables-textstyles.spec.yaml
  characters-and-layouts.spec.yaml
  state-validation.spec.yaml
  animations-drift.test.js
  command-sequences.test.js

How This Maps To The Current Client Repo

Current RouteVN files:

• src/internal/project/commands.js
• src/internal/project/state.js

should map into this package like this:

• src/errors.js
  • internal domain error factories
• src/helpers.js
  • tiny pure shared helpers
• src/model.js
  • state validation
  • invariants
  • command definitions
  • payload validation
  • state-aware validation
  • reduction
• src/index.js
  • public exports only

projection.js should stay in the app repos for now. It is downstream of the domain model and is still tied to current app/repository needs.

Intended Usage

Client:

1. validate payload before submit when useful
2. optionally run processCommand() for optimistic apply
3. send to Insieme transport

Server:

1. validate payload at submit boundary
2. validate against current state before commit
3. commit event to storage
4. use processCommand() for authoritative projection

Testing

This repo uses Bun + Vitest + Puty.

• runner: bunx vitest run
• package script: bun run test
• benchmark script: bun run bench
• YAML specs live in tests/**/*.spec.yaml
• JS sequence tests live in tests/**/*.test.js

There are 2 test styles:

1. Command contract specs

   • treat commands as pure functions
   • validate one call at a time
   • assert exact input/output or expected invalid result
   • include a direct command coverage matrix for the full public registry
   • examples:
     • tests/command-direct-coverage.test.js
     • tests/project.create.spec.yaml
     • tests/story-and-scenes.spec.yaml
     • tests/state-validation.spec.yaml

2. Command sequence tests

   • apply a sequence of commands
   • assert the full state after each step
   • also assert the previous state was not mutated
   • use these for reducer flows that are easier to reason about as a tape
   • example:
     • tests/command-sequences.test.js

YAML Puty specs use tests/support/putyApi.js as a small adapter so the declarative throws: assertions can stay concise while the real public API returns { valid: ... } result objects.

Compatibility fixtures live under tests/compat/schema-<n>/.

• payloads/ fixtures are frozen command payload shapes for that schema version
• states/ fixtures are frozen persisted-state snapshots for that schema version
• streams/ fixtures are frozen command sequences for that schema version
• current tests must continue to validate/replay every archived compatibility fixture from the same or older schema versions
• current schema payload coverage must include minimal.yaml and full.yaml for every public command type

See also:

• docs/schema-compatibility.md

Current animation update tween properties support either:

• keyframes
• auto: { duration, easing }

Transition animation mask accepts one mask object or a non-empty ordered array. Each mask may define a non-negative safe-integer delay in milliseconds.

Audio effects are foldered resources stored in audioEffects.items and audioEffects.tree. Non-folder items use this wrapper:

{
  id: "crossfade",
  type: "audioEffect",
  name: "Crossfade",
  description: "Fade between two BGM sources",
  tagIds: ["smooth"],
  preview: {
    outgoing: { soundId: "calm-theme" },
    incoming: { soundId: "battle-theme" },
  },
  audioEffect: {
    type: "transition",
    prev: {
      volume: {
        keyframes: [{ value: 0, duration: 600, easing: "easeInOutSine" }],
      },
    },
    next: {
      volume: {
        initialValue: 0,
        keyframes: [{ value: 100, duration: 900, easing: "easeInOutSine" }],
      },
    },
  },
}

The optional editor preview uses outgoing and incoming sound slots for a transition effect, or a single target sound slot for an update effect. Each slot is an object containing a soundId.

audioEffect.type is either transition or update. Transition effects have at least one property under prev or next; update effects place properties under tween. Both support only volume, pan, and playbackRate. Each property has non-empty keyframes and must finish with an absolute numeric keyframe. A final tween or next value becomes the persistent BGM property value after the effect finishes. Absolute volume values are bounded to 0..100, pan to -1..1, and playback rate to >= 0; relative keyframes represent unbounded numeric deltas and cannot be final.

Current Scope

Currently implemented command types:

• project.create
• story.update
• scene.create
• scene.update
• scene.delete
• scene.move
• section.create
• section.update
• section.delete
• section.move
• line.create
• line.update_actions
• line.delete
• line.move
• image.create
• image.update
• image.delete
• image.move
• spritesheet.create
• spritesheet.update
• spritesheet.delete
• spritesheet.move
• sound.create
• sound.update
• sound.delete
• sound.move
• video.create
• video.update
• video.delete
• video.move
• animation.create
• animation.update
• animation.delete
• animation.move
• audioEffect.create
• audioEffect.update
• audioEffect.delete
• audioEffect.move
• font.create
• font.update
• font.delete
• font.move
• color.create
• color.update
• color.delete
• color.move
• transform.create
• transform.update
• transform.delete
• transform.move
• variable.create
• variable.update
• variable.delete
• variable.move
• textStyle.create
• textStyle.update
• textStyle.delete
• textStyle.move
• character.create
• character.update
• character.delete
• character.move
• layout.create
• layout.update
• layout.delete
• layout.move
• layout.schema.upgrade
• character.sprite.create
• character.sprite.update
• character.sprite.delete
• character.sprite.move
• layout.element.create
• layout.element.update
• layout.element.delete
• layout.element.move
• control.create
• control.update
• control.delete
• control.move
• control.element.create
• control.element.update
• control.element.delete
• control.element.move

The rest of the future command surface should be added only when full validation, preconditions, reducer behavior, and tests are added together.