@vidder/story-engine

Shared types, schemas and JS engine bundle for the Vidder Story Engine. Used by both mobile (Flutter/Dart) and web (Next.js/TypeScript).

Status: v0.0.1 is a POC. Engine logic arrives in v0.1.0+.

Published: npmjs.com/package/@vidder/story-engine

Installation

npm install @vidder/story-engine

Usage (TypeScript)

import type { StoryCard, IntroCard, PlaceCard, JourneyData, EditOp } from '@vidder/story-engine';

Source of truth

All Dart and TypeScript types are GENERATED from JSON Schema files in this package — never hand-written.

Schema version

Each schema file has a top-level $schema_version field. Current: 0.0.1.

Files

| File | Purpose | |------|---------| | story_card.schema.json | All 8 card types + CardBase + TripSummaryData | | journey_data.schema.json | Engine input bundle (Journey + Tracks + Places + ...) | | edit_op.schema.json | 10 EditOp kinds with typed payloads | | upload_state.schema.json | Photo upload state machine enum |

Versioning policy (semver)

| Bump | When | |------|------| | major | Breaking schema change (field removed, type changed, required field added) | | minor | Additive change (new optional field, new card type, new EditOp kind) | | patch | Description/documentation changes only |

Schema version bumps trigger @vidder/story-engine NPM package version bumps with the same semver semantics.

Codegen

Dart (mobile): Types generated via json_serializable from schema definitions. Run dart run build_runner build after schema changes.

TypeScript (web): Types generated via json-schema-to-typescript:

npx json-schema-to-typescript shared-schema/*.schema.json -o web/src/types/

Round-trip test (design note for S-E2)

The S-E2 STOP-gate requires "zero diff" at DB-row level:

SELECT data FROM story_cards WHERE story_id = ?
  -> engine.generate(JourneyData)
  -> serializer.toRow(card) for each card
  -> JSON-equal against original?

This ensures engine output is bit-compatible with legacy _buildCards output. The test operates on the data JSON blob, not on Dart model equality.

Tech debt: rendering hints in data

Several fields in IntroCard/OutroCard/RouteCard data are rendering hints that arguably belong in a separate renderer configuration:

• route_image_overlay / points_image_overlay
• map_style / map_size / map_padding

These are included in v0.0.1 for backward compatibility. Candidate for cleanup to a separate RenderConfig type in a future major version bump.