@cyberart-io/engine 0.0.11 → 0.0.12

package/docs/job-orchestration.md

@@ -8,6 +8,7 @@ Related: [Events and router](events.md) (CYB-59 contracts), [Replay inspector](r
 
 ```bash
 pnpm exec vitest run packages/engine/src/canvas/cyb-80-job-orchestration.repro.spec.ts
+pnpm exec vitest run packages/engine/src/canvas/cyb-112-job-payload-validation.repro.spec.ts
 ```
 
 ## When to use
@@ -20,7 +21,7 @@ pnpm exec vitest run packages/engine/src/canvas/cyb-80-job-orchestration.repro.s
 ## Contract
 
 1. **Definitions** are versioned: request schema, result kind, retry/lease/timeout, declared fallback.
-2. **Submit** with a stable idempotency key and a correlation id for the initiating player intent. Duplicate keys return the same job.
+2. **Submit** with a stable idempotency key and a correlation id for the initiating player intent. The `request` payload is validated against the definition's `requestSchema` before any coordinator mutation — missing required fields and undeclared keys fail closed unless `requestSchema.additionalProperties` is `true`. Duplicate keys return the same job only after a prior valid submission persisted.
 3. **States:** queued → claimed → awaiting-evaluation → ready → applied, plus retry-scheduled, failed, canceled, superseded.
 4. **Results** are refs (`uri` + `kind`), not embedded media/world payloads.
 5. **Evaluator** may accept, reject, or request a bounded revision.

package/docs/loading-indicator.md

@@ -0,0 +1,95 @@
+# Loading indicator
+
+Host-facing contract for deterministic, parameterized loading carts. Presentation-only: seeded visual variation without inventing progress or mutating authoritative host/game state.
+
+Related: [Presentation cue](presentation-cue.md) (frame stepping), [Visual layers](visual-layers.md) (reduced motion), [Events and router](events.md). Back to the [package README](../README.md).
+
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-111-loading-indicator.repro.spec.ts
+```
+
+## When to use
+
+| Surface | Import | Use |
+|---|---|---|
+| Production host | `createLoadingIndicatorController` from `@cyberart-io/engine` | Mount locally registered loader carts; persist `snapshot()` in envelope `hostState`. |
+| Vitest / jsdom | same, or `@cyberart-io/engine/headless` | Identical controller; reference cart in `fixtures/loadingPulseCart.ts`. |
+
+## Contract
+
+1. **Params JSON** — validated before any live mutation: `schemaVersion`, stable `seed`, `mode: "indeterminate" \| "determinate"`, host `statusText`, optional `progress` (determinate only, 0..1), `stage`, `context`, bounded `presentation`, optional `cartId`.
+2. **Lifecycle** — `start → update → complete | fail | cancel`. Presentation-only; never advances gameplay or accepts job results.
+3. **Determinate honesty** — displays only host-supplied `progress`. Indeterminate mode keeps `progress: null`; frame stepping never synthesizes a percentage.
+4. **Seeded variation** — `variant` (hue, motif, intensity, palette) is derived deterministically from `seed` and bounded presentation params.
+5. **Reduced motion** — host flag yields static or low-motion `pulsePhase` (motif `static` or `setReducedMotion(true)`).
+6. **Accessibility** — `statusText` is host-controlled and exposed on `inspect().view` independently of the visual cart.
+7. **Fallback** — unknown or failing cart init falls back immediately to the built-in indicator (`usingFallback: true`, `fallbackReason` set) with a diagnostic. Intentional `cartId: "builtin"` (or omitting `cartId`) uses the built-in cart without setting `usingFallback`.
+8. **Restore** — versioned `snapshot()` / `restore()` validates JSON and schema version before mutate; tampered input returns `{ ok: false }` and leaves state unchanged.
+9. **Budgets** — optional `maxStepFrames`, `maxIntensity`, `maxVariant`; violations emit `loading.indicator.diagnostic` with code `budget-exceeded`.
+
+```ts
+import {
+  createLoadingIndicatorController,
+  LOADING_INDICATOR_STARTED_EVENT,
+} from '@cyberart-io/engine';
+import { createLoadingPulseCartFactory } from '@cyberart-io/engine/dist/…'; // or local fixture in tests
+
+const loading = createLoadingIndicatorController({
+  carts: { pulse: createLoadingPulseCartFactory() },
+  reducedMotion: hostPrefersReducedMotion,
+});
+
+loading.start({
+  seed: travelSeed,
+  mode: 'indeterminate',
+  statusText: 'Traveling to the grove',
+  context: 'travel',
+  cartId: 'pulse',
+  presentation: { motif: 'pulse', intensity: 0.7 },
+});
+
+loading.step(framesElapsed);
+loading.update({ stage: 'route', statusText: 'Finding the path' });
+loading.complete();
+```
+
+## Params
+
+| Field | Required | Notes |
+|---|---|---|
+| `schemaVersion` | yes | Must be `1`. |
+| `seed` | yes | Stable deterministic identity for variant selection. |
+| `mode` | yes | `indeterminate` or `determinate`. |
+| `statusText` | yes | Host-owned a11y string; not generated by the cart. |
+| `progress` | determinate only | 0..1; forbidden in indeterminate mode. |
+| `stage` | no | Semantic stage label; may change animation without implying numeric completion. |
+| `context` | no | `travel`, `worldgen`, `content`, `audio`, or host string. |
+| `presentation` | no | Bounded: `#RRGGBB` palette, intensity 0..1, motif enum, variant 0..7. |
+| `cartId` | no | Registered local cart; omitted or `"builtin"` → built-in cart (`usingFallback` stays false). |
+
+## Lifecycle events
+
+| `type` | When |
+|---|---|
+| `loading.indicator.started` | `start()` accepted |
+| `loading.indicator.updated` | `update()` accepted |
+| `loading.indicator.completed` | `complete()` |
+| `loading.indicator.failed` | `fail(reasonCode?)` |
+| `loading.indicator.canceled` | `cancel()` |
+| `loading.indicator.diagnostic` | Validation, fallback, budget, restore errors |
+
+Register contracts with `loadingIndicatorEventContracts()` on the event router ([Events](events.md)).
+
+## Snapshot
+
+`schemaVersion: 1` sidecar: `{ frame, reducedMotion, phase, params, variant, usingFallback, fallbackReason, cartId, events, diagnostics }`. Store in envelope `hostState` (for example `{ loadingIndicator: snapshot }`).
+
+## Reference cart
+
+`packages/engine/src/canvas/fixtures/loadingPulseCart.ts` — `createLoadingPulseCart()` and `createLoadingPulseCartFactory()` demonstrate seeded hue/motif variation, determinate progress labels, and reduced-motion static rendering.
+
+## Exports
+
+`LOADING_INDICATOR_*` constants, `createLoadingIndicatorController`, `parseLoadingIndicatorParams`, `parseLoadingIndicatorSnapshot`, `loadingIndicatorEventContracts`, `isLoadingIndicatorEventType`, `isLoadingIndicatorMode`, and related types from `@cyberart-io/engine` and `@cyberart-io/engine/headless`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyberart-io/engine",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "CyberArt host engine: mount carts, events, capability manifests, geometry, runtime groups, and a Node/jsdom headless entry.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",