{"id":47664385,"url":"https://github.com/routevn/routevn-creator-model","last_synced_at":"2026-05-16T09:19:09.472Z","repository":{"id":345018185,"uuid":"1183010442","full_name":"RouteVN/routevn-creator-model","owner":"RouteVN","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-11T08:58:35.000Z","size":349,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-11T10:29:44.330Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RouteVN.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-16T07:19:29.000Z","updated_at":"2026-04-11T08:57:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/RouteVN/routevn-creator-model","commit_stats":null,"previous_names":["routevn/routevn-creator-model"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/RouteVN/routevn-creator-model","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RouteVN%2Froutevn-creator-model","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RouteVN%2Froutevn-creator-model/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RouteVN%2Froutevn-creator-model/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RouteVN%2Froutevn-creator-model/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RouteVN","download_url":"https://codeload.github.com/RouteVN/routevn-creator-model/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RouteVN%2Froutevn-creator-model/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31870516,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"online","status_checked_at":"2026-04-16T02:00:06.042Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-02T11:50:52.433Z","updated_at":"2026-05-16T09:19:09.465Z","avatar_url":"https://github.com/RouteVN.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RouteVN Creator Model\n\nShared RouteVN domain model package.\n\nRepo rules and contribution expectations are in\n[GUIDELINES.md](./GUIDELINES.md).\n\nSchema compatibility maintenance rules are in\n[docs/schema-compatibility.md](./docs/schema-compatibility.md).\n\nThis repo is intended to be the single source of truth for:\n\n- state validation\n- command payload validation\n- state-aware command preconditions\n- command-to-state reduction\n\nIt is intentionally **not** responsible for:\n\n- Insieme transport\n- Insieme storage\n- partition routing\n- actors, tokens, client timestamps\n\nThose stay in the client and server repos.\n\n## Public API\n\n```js\nSCHEMA_VERSION;\n\nvalidateState({ state });\n\nvalidatePayload({ type, payload });\n\nvalidateAgainstState({\n  state,\n  command: { type, payload },\n});\n\nprocessCommand({\n  state,\n  command: { type, payload },\n});\n\nreplayCommands({\n  state,\n  commands: [{ type, payload }],\n});\n```\n\n`SCHEMA_VERSION` is the exported schema version constant for persisted command\ncompatibility.\n\nValidation functions return:\n\n```js\n{\n  valid: true;\n}\n```\n\nor:\n\n```js\n{\n  valid: false,\n  error: {\n    kind: \"state\" | \"payload\" | \"precondition\" | \"invariant\",\n    code: \"payload_validation_failed\",\n    message: \"payload.data.foo is not allowed\",\n    path: \"payload.data.foo\", // only when available\n    details: {}, // only when available\n  },\n}\n```\n\n`processCommand()` returns:\n\n```js\n{ valid: true, state: nextState }\n```\n\n`replayCommands()` returns the same result shape while applying a trusted\ncommand tape against a single working state clone. It is intended for batch\nhistory reconstruction paths such as offline repository boot/import replay,\nwhere validating the full state before and after every individual command is\nneedlessly expensive.\n\nDesign rules:\n\n- no classes\n- pure functions whenever possible\n- command payload shape is validated separately from state-aware preconditions\n- `SCHEMA_VERSION` is the source of truth for persisted command schema versioning\n- `SCHEMA_VERSION` must stay aligned with the minor version from `package.json`\n- patch releases must not change persisted schema compatibility\n- `bun run test:compat` is the required compatibility gate for model changes\n- `processCommand()` is the authoritative state transition\n- `replayCommands()` is the fast batch replay path for trusted command tapes\n- model state should contain project-owned runtime data only\n- app-owned metadata like project id, name, and description should stay out of\n  this package\n- `project` may start empty; fields like `resolution` are optional until the\n  model starts owning them\n- random ids across RouteVN should use `nanoid` with the RouteVN base58 variant;\n  deterministic derived tokens such as partition hashes are a separate case\n\n## File Structure\n\n```text\nsrc/\n  index.js\n  errors.js\n  helpers.js\n  model.js\ntests/\n  model-api.test.js\n  command-direct-coverage.test.js\n  project.create.spec.yaml\n  story-and-scenes.spec.yaml\n  scenes-advanced.spec.yaml\n  sections-and-lines.spec.yaml\n  images.spec.yaml\n  sounds-and-videos.spec.yaml\n  animations.spec.yaml\n  fonts-and-colors.spec.yaml\n  transforms-variables-textstyles.spec.yaml\n  characters-and-layouts.spec.yaml\n  state-validation.spec.yaml\n  animations-drift.test.js\n  command-sequences.test.js\n```\n\n## How This Maps To The Current Client Repo\n\nCurrent RouteVN files:\n\n- `src/internal/project/commands.js`\n- `src/internal/project/state.js`\n\nshould map into this package like this:\n\n- `src/errors.js`\n  - internal domain error factories\n- `src/helpers.js`\n  - tiny pure shared helpers\n- `src/model.js`\n  - state validation\n  - invariants\n  - command definitions\n  - payload validation\n  - state-aware validation\n  - reduction\n- `src/index.js`\n  - public exports only\n\n`projection.js` should stay in the app repos for now. It is downstream of the\ndomain model and is still tied to current app/repository needs.\n\n## Intended Usage\n\nClient:\n\n1. validate payload before submit when useful\n2. optionally run `processCommand()` for optimistic apply\n3. send to Insieme transport\n\nServer:\n\n1. validate payload at submit boundary\n2. validate against current state before commit\n3. commit event to storage\n4. use `processCommand()` for authoritative projection\n\n## Testing\n\nThis repo uses Bun + Vitest + Puty.\n\n- runner: `bunx vitest run`\n- package script: `bun run test`\n- benchmark script: `bun run bench`\n- YAML specs live in `tests/**/*.spec.yaml`\n- JS sequence tests live in `tests/**/*.test.js`\n\nThere are 2 test styles:\n\n1. Command contract specs\n   - treat commands as pure functions\n   - validate one call at a time\n   - assert exact input/output or expected invalid result\n   - include a direct command coverage matrix for the full public registry\n   - examples:\n     - [tests/command-direct-coverage.test.js](./tests/command-direct-coverage.test.js)\n     - [tests/project.create.spec.yaml](./tests/project.create.spec.yaml)\n     - [tests/story-and-scenes.spec.yaml](./tests/story-and-scenes.spec.yaml)\n     - [tests/state-validation.spec.yaml](./tests/state-validation.spec.yaml)\n\n2. Command sequence tests\n   - apply a sequence of commands\n   - assert the full state after each step\n   - also assert the previous state was not mutated\n   - use these for reducer flows that are easier to reason about as a tape\n   - example:\n     - [tests/command-sequences.test.js](./tests/command-sequences.test.js)\n\nYAML Puty specs use [tests/support/putyApi.js](./tests/support/putyApi.js) as a\nsmall adapter so the declarative `throws:` assertions can stay concise while the\nreal public API returns `{ valid: ... }` result objects.\n\nCompatibility fixtures live under `tests/compat/schema-\u003cn\u003e/`.\n\n- `payloads/` fixtures are frozen command payload shapes for that schema version\n- `states/` fixtures are frozen persisted-state snapshots for that schema version\n- `streams/` fixtures are frozen command sequences for that schema version\n- current tests must continue to validate/replay every archived compatibility\n  fixture from the same or older schema versions\n- current schema payload coverage must include `minimal.yaml` and `full.yaml` for\n  every public command type\n\nSee also:\n\n- [docs/schema-compatibility.md](./docs/schema-compatibility.md)\n\nCurrent animation update tween properties support either:\n\n- `keyframes`\n- `auto: { duration, easing }`\n\n## Current Scope\n\nCurrently implemented command types:\n\n- `project.create`\n- `story.update`\n- `scene.create`\n- `scene.update`\n- `scene.delete`\n- `scene.move`\n- `section.create`\n- `section.update`\n- `section.delete`\n- `section.move`\n- `line.create`\n- `line.update_actions`\n- `line.delete`\n- `line.move`\n- `image.create`\n- `image.update`\n- `image.delete`\n- `image.move`\n- `spritesheet.create`\n- `spritesheet.update`\n- `spritesheet.delete`\n- `spritesheet.move`\n- `sound.create`\n- `sound.update`\n- `sound.delete`\n- `sound.move`\n- `video.create`\n- `video.update`\n- `video.delete`\n- `video.move`\n- `animation.create`\n- `animation.update`\n- `animation.delete`\n- `animation.move`\n- `font.create`\n- `font.update`\n- `font.delete`\n- `font.move`\n- `color.create`\n- `color.update`\n- `color.delete`\n- `color.move`\n- `transform.create`\n- `transform.update`\n- `transform.delete`\n- `transform.move`\n- `variable.create`\n- `variable.update`\n- `variable.delete`\n- `variable.move`\n- `textStyle.create`\n- `textStyle.update`\n- `textStyle.delete`\n- `textStyle.move`\n- `character.create`\n- `character.update`\n- `character.delete`\n- `character.move`\n- `layout.create`\n- `layout.update`\n- `layout.delete`\n- `layout.move`\n- `layout.schema.upgrade`\n- `character.sprite.create`\n- `character.sprite.update`\n- `character.sprite.delete`\n- `character.sprite.move`\n- `layout.element.create`\n- `layout.element.update`\n- `layout.element.delete`\n- `layout.element.move`\n- `control.create`\n- `control.update`\n- `control.delete`\n- `control.move`\n- `control.element.create`\n- `control.element.update`\n- `control.element.delete`\n- `control.element.move`\n\nThe rest of the future command surface should be added only when full\nvalidation, preconditions, reducer behavior, and tests are added together.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froutevn%2Froutevn-creator-model","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froutevn%2Froutevn-creator-model","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froutevn%2Froutevn-creator-model/lists"}