@routevn/creator-model 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yuusoft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,263 @@
+# RouteVN Creator Model
+
+Shared RouteVN domain model package.
+
+Repo rules and contribution expectations are in
+[GUIDELINES.md](./GUIDELINES.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
+
+```js
+SCHEMA_VERSION;
+
+validateState({ state });
+
+validatePayload({ type, payload });
+
+validateAgainstState({
+  state,
+  command: { type, payload },
+});
+
+processCommand({
+  state,
+  command: { type, payload },
+});
+```
+
+`SCHEMA_VERSION` is the exported schema version constant for persisted command
+compatibility.
+
+Validation functions return:
+
+```js
+{
+  valid: true;
+}
+```
+
+or:
+
+```js
+{
+  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:
+
+```js
+{ valid: true, state: nextState }
+```
+
+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
+- `processCommand()` is the authoritative state transition
+- 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
+
+## File Structure
+
+```text
+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
+  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/command-direct-coverage.test.js)
+     - [tests/project.create.spec.yaml](./tests/project.create.spec.yaml)
+     - [tests/story-and-scenes.spec.yaml](./tests/story-and-scenes.spec.yaml)
+     - [tests/state-validation.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](./tests/command-sequences.test.js)
+
+YAML Puty specs use [tests/support/putyApi.js](./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.
+
+## 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`
+- `sound.create`
+- `sound.update`
+- `sound.delete`
+- `sound.move`
+- `video.create`
+- `video.update`
+- `video.delete`
+- `video.move`
+- `animation.create`
+- `animation.update`
+- `animation.delete`
+- `animation.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`
+- `character.sprite.create`
+- `character.sprite.update`
+- `character.sprite.delete`
+- `character.sprite.move`
+- `layout.element.create`
+- `layout.element.update`
+- `layout.element.delete`
+- `layout.element.move`
+
+The rest of the future command surface should be added only when full
+validation, preconditions, reducer behavior, and tests are added together.

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@routevn/creator-model",
+  "version": "1.0.0",
+  "private": false,
+  "type": "module",
+  "license": "MIT",
+  "description": "Shared RouteVN domain model, validators, and reducer",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RouteVN/routevn-creator-model.git"
+  },
+  "bugs": {
+    "url": "https://github.com/RouteVN/routevn-creator-model/issues"
+  },
+  "homepage": "https://github.com/RouteVN/routevn-creator-model#readme",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "test": "bunx vitest run",
+    "test:watch": "bunx vitest",
+    "bench": "bun scripts/benchmark-process-command.js"
+  },
+  "devDependencies": {
+    "puty": "0.1.2",
+    "vitest": "^3.2.1"
+  }
+}

package/src/errors.js

@@ -0,0 +1,39 @@
+const createDomainError = ({ name, code, message, details = {} }) => {
+  const error = new Error(message);
+  error.name = name;
+  error.code = code;
+  error.details = details;
+  return error;
+};
+
+export const createPayloadValidationError = (message, details) =>
+  createDomainError({
+    name: "PayloadValidationError",
+    code: "payload_validation_failed",
+    message,
+    details,
+  });
+
+export const createPreconditionValidationError = (message, details) =>
+  createDomainError({
+    name: "PreconditionValidationError",
+    code: "precondition_validation_failed",
+    message,
+    details,
+  });
+
+export const createStateValidationError = (message, details) =>
+  createDomainError({
+    name: "StateValidationError",
+    code: "state_validation_failed",
+    message,
+    details,
+  });
+
+export const createInvariantValidationError = (message, details) =>
+  createDomainError({
+    name: "InvariantValidationError",
+    code: "invariant_validation_failed",
+    message,
+    details,
+  });

package/src/helpers.js

@@ -0,0 +1,235 @@
+export const isPlainObject = (value) =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+export const isNonEmptyString = (value) =>
+  typeof value === "string" && value.trim().length > 0;
+
+export const isFiniteNumber = (value) =>
+  typeof value === "number" && Number.isFinite(value);
+
+export const findTreeNode = ({ nodes, nodeId }) => {
+  if (!Array.isArray(nodes)) {
+    return undefined;
+  }
+
+  for (const node of nodes) {
+    if (!node || typeof node !== "object") {
+      continue;
+    }
+
+    if (node.id === nodeId) {
+      return node;
+    }
+
+    const nestedNode = findTreeNode({
+      nodes: node.children,
+      nodeId,
+    });
+
+    if (nestedNode) {
+      return nestedNode;
+    }
+  }
+
+  return undefined;
+};
+
+export const findTreeParentId = ({ nodes, nodeId, parentId = null }) => {
+  if (!Array.isArray(nodes)) {
+    return undefined;
+  }
+
+  for (const node of nodes) {
+    if (!node || typeof node !== "object") {
+      continue;
+    }
+
+    if (node.id === nodeId) {
+      return parentId;
+    }
+
+    const nestedParentId = findTreeParentId({
+      nodes: node.children,
+      nodeId,
+      parentId: node.id,
+    });
+
+    if (nestedParentId !== undefined) {
+      return nestedParentId;
+    }
+  }
+
+  return undefined;
+};
+
+const getSiblingNodes = ({ tree, parentId }) => {
+  if (parentId === null || parentId === undefined) {
+    return tree;
+  }
+
+  const parentNode = findTreeNode({
+    nodes: tree,
+    nodeId: parentId,
+  });
+
+  if (!Array.isArray(parentNode.children)) {
+    parentNode.children = [];
+  }
+
+  return parentNode.children;
+};
+
+const resolveInsertIndex = ({ siblings, index, position, positionTargetId }) => {
+  if (Number.isInteger(index)) {
+    return Math.max(0, Math.min(index, siblings.length));
+  }
+
+  if (position === "first") {
+    return 0;
+  }
+
+  if (position === "before" && isNonEmptyString(positionTargetId)) {
+    return Math.max(0, siblings.findIndex((entry) => entry.id === positionTargetId));
+  }
+
+  if (position === "after" && isNonEmptyString(positionTargetId)) {
+    const targetIndex = siblings.findIndex((entry) => entry.id === positionTargetId);
+    return targetIndex >= 0 ? targetIndex + 1 : siblings.length;
+  }
+
+  return siblings.length;
+};
+
+export const insertTreeNode = ({
+  tree,
+  node,
+  parentId = null,
+  index,
+  position,
+  positionTargetId,
+}) => {
+  const siblings = getSiblingNodes({
+    tree,
+    parentId,
+  });
+
+  const insertIndex = resolveInsertIndex({
+    siblings,
+    index,
+    position,
+    positionTargetId,
+  });
+
+  siblings.splice(insertIndex, 0, node);
+};
+
+export const insertScopedTreeNode = ({
+  tree,
+  node,
+  parentId = null,
+  index,
+  position,
+  positionTargetId,
+  isSibling,
+}) => {
+  const siblings = getSiblingNodes({
+    tree,
+    parentId,
+  });
+
+  const matchingIndexes = siblings
+    .map((entry, entryIndex) => (isSibling(entry) ? entryIndex : -1))
+    .filter((entryIndex) => entryIndex >= 0);
+
+  let insertIndex = siblings.length;
+
+  if (Number.isInteger(index)) {
+    if (matchingIndexes.length === 0) {
+      insertIndex = Math.max(0, Math.min(index, siblings.length));
+    } else if (index <= 0) {
+      insertIndex = matchingIndexes[0];
+    } else if (index >= matchingIndexes.length) {
+      insertIndex = matchingIndexes[matchingIndexes.length - 1] + 1;
+    } else {
+      insertIndex = matchingIndexes[index];
+    }
+  } else if (position === "first") {
+    insertIndex = matchingIndexes[0] ?? siblings.length;
+  } else if (position === "before" && isNonEmptyString(positionTargetId)) {
+    const targetIndex = siblings.findIndex((entry) => entry.id === positionTargetId);
+    insertIndex = targetIndex >= 0 ? targetIndex : siblings.length;
+  } else if (position === "after" && isNonEmptyString(positionTargetId)) {
+    const targetIndex = siblings.findIndex((entry) => entry.id === positionTargetId);
+    insertIndex = targetIndex >= 0 ? targetIndex + 1 : siblings.length;
+  } else if (matchingIndexes.length > 0) {
+    insertIndex = matchingIndexes[matchingIndexes.length - 1] + 1;
+  }
+
+  siblings.splice(insertIndex, 0, node);
+};
+
+export const removeTreeNode = ({ nodes, nodeId }) => {
+  if (!Array.isArray(nodes)) {
+    return undefined;
+  }
+
+  for (let index = 0; index < nodes.length; index += 1) {
+    const node = nodes[index];
+    if (!node || typeof node !== "object") {
+      continue;
+    }
+
+    if (node.id === nodeId) {
+      return nodes.splice(index, 1)[0];
+    }
+
+    const removedNode = removeTreeNode({
+      nodes: node.children,
+      nodeId,
+    });
+
+    if (removedNode) {
+      return removedNode;
+    }
+  }
+
+  return undefined;
+};
+
+const walkTree = ({ nodes, visit }) => {
+  if (!Array.isArray(nodes)) {
+    return;
+  }
+
+  for (const node of nodes) {
+    if (!node || typeof node !== "object") {
+      continue;
+    }
+
+    visit(node);
+    walkTree({
+      nodes: node.children,
+      visit,
+    });
+  }
+};
+
+export const collectTreeDescendantIds = ({ node, includeRoot = true }) => {
+  const ids = [];
+
+  if (!node || typeof node !== "object") {
+    return ids;
+  }
+
+  walkTree({
+    nodes: [node],
+    visit: (entry) => {
+      if (entry === node && includeRoot === false) {
+        return;
+      }
+      ids.push(entry.id);
+    },
+  });
+
+  return ids;
+};

package/src/index.js

@@ -0,0 +1,7 @@
+export {
+  SCHEMA_VERSION,
+  processCommand,
+  validateAgainstState,
+  validatePayload,
+  validateState,
+} from "./model.js";