@daltonr/pathwrite-core 0.4.0 → 0.6.0

package/README.md

@@ -63,16 +63,22 @@ const path: PathDefinition<CourseData> = {
 | `PathStep<TData>` | A single step: guards, lifecycle hooks. |
 | `PathStepContext<TData>` | Passed to every hook and guard. `data` is a **readonly snapshot copy** — return a patch to update state. |
 | `PathSnapshot<TData>` | Point-in-time read of the engine: step ID, index, count, flags, and a copy of data. |
-| `PathEvent` | Union of `stateChanged`, `completed`, `cancelled`, and `resumed`. |
+| `PathEvent` | Union of `stateChanged` (includes `cause`), `completed`, `cancelled`, and `resumed`. |
+| `StateChangeCause` | Identifies the method that triggered a `stateChanged` event: `"start"` \| `"next"` \| `"previous"` \| `"goToStep"` \| `"goToStepChecked"` \| `"setData"` \| `"cancel"` \| `"restart"`. |
+| `PathObserver` | `(event: PathEvent, engine: PathEngine) => void` — a function registered at construction time that receives every event for the engine's lifetime. |
+| `PathEngineOptions` | `{ observers?: PathObserver[] }` — options accepted by the `PathEngine` constructor and `PathEngine.fromState()`. |
+| `ObserverStrategy` | Union type for the five built-in trigger strategies: `"onEveryChange" \| "onNext" \| "onSubPathComplete" \| "onComplete" \| "manual"`. Import and use in your own observer factories. |
+| `matchesStrategy` | `(strategy: ObserverStrategy, event: PathEvent) => boolean` — returns `true` when an event should trigger an observer under the given strategy. Shared by every observer so none re-implement the same "when do I fire?" logic. |
 
 ## PathEngine API
 
 ```typescript
-const engine = new PathEngine();
+// Observers are wired before the first event fires
+const engine = new PathEngine({ observers: [myObserver, anotherObserver] });
 
 engine.start(definition, initialData?);    // start or re-start a path
 engine.restart(definition, initialData?);  // tear down stack and start fresh (no hooks, no cancelled event)
-engine.startSubPath(definition, data?);    // push sub-path onto the stack (requires active path)
+engine.startSubPath(definition, data?, meta?); // push sub-path onto the stack (requires active path)
 engine.next();
 engine.previous();
 engine.cancel();
@@ -83,13 +89,56 @@ engine.snapshot();                         // returns PathSnapshot | null
 
 // Serialization API (for persistence)
 const state = engine.exportState();        // returns SerializedPathState | null
-const restoredEngine = PathEngine.fromState(state, pathDefinitions);
+const restoredEngine = PathEngine.fromState(state, pathDefinitions, { observers: [...] });
 
+// Removable one-off listener (use subscribe when you need to unsubscribe)
 const unsubscribe = engine.subscribe((event) => { ... });
-unsubscribe(); // remove the listener
+unsubscribe();
 ```
 
-## Lifecycle hooks
+## Observers
+
+Observers are functions registered at construction time. They receive every event for the engine's lifetime and cannot be removed — for removable listeners use `subscribe()`.
+
+```typescript
+// A logger observer
+const logger: PathObserver = (event) =>
+  console.log(`[${event.type}]`, 'cause' in event ? event.cause : '');
+
+// A persistence observer using matchesStrategy from core
+import { matchesStrategy } from "@daltonr/pathwrite-core";
+
+const persist: PathObserver = (event, engine) => {
+  if (matchesStrategy("onNext", event)) {
+    myStore.save(engine.exportState());
+  }
+};
+
+const engine = new PathEngine({ observers: [logger, persist] });
+
+// Observers are also passed through fromState — so restored engines are fully observed
+const restoredEngine = PathEngine.fromState(saved, pathDefs, { observers: [logger, persist] });
+```
+
+The second argument to each observer is the engine itself, which lets observers call `engine.exportState()`, `engine.snapshot()`, etc. without needing a separate reference.
+
+### Building your own observer factory
+
+`ObserverStrategy` and `matchesStrategy` are exported from core so any observer — not just HTTP persistence — can share the same strategy logic without reimplementing it:
+
+```typescript
+import { type ObserverStrategy, matchesStrategy, type PathObserver } from "@daltonr/pathwrite-core";
+
+function myObserver(strategy: ObserverStrategy): PathObserver {
+  return (event, engine) => {
+    if (matchesStrategy(strategy, event)) {
+      // react — save to MongoDB, write to a log, fire analytics, etc.
+    }
+  };
+}
+```
+
+
 
 All hooks are optional. Hooks that want to update data **return a partial patch** — the engine applies it automatically. Direct mutation of `ctx.data` is a no-op; the context receives a copy.
 
@@ -416,7 +465,7 @@ Sub-paths can themselves start sub-paths (unlimited nesting). Use `snapshot.nest
 ```typescript
 engine.subscribe((event) => {
   switch (event.type) {
-    case "stateChanged": // event.snapshot
+    case "stateChanged": // event.cause ("start" | "next" | "previous" | ...), event.snapshot
     case "completed":    // event.pathId, event.data
     case "cancelled":    // event.pathId, event.data
     case "resumed":      // event.resumedPathId, event.fromSubPathId, event.snapshot
@@ -424,6 +473,8 @@ engine.subscribe((event) => {
 });
 ```
 
+Every `stateChanged` event includes a `cause` field (`StateChangeCause`) identifying which public method triggered it. Use this to react to specific operations — for example, the `store-http` package uses `event.cause === "next"` to implement the `onNext` persistence strategy.
+
 ## State Persistence
 
 The engine supports exporting and restoring state for persistence scenarios (e.g., saving wizard progress to a server or localStorage).

package/dist/index.d.ts

@@ -1,4 +1,14 @@
 export type PathData = Record<string, unknown>;
+/**
+ * The return type of a `fieldMessages` hook. Each key is a field ID; the value
+ * is an error string, or `undefined` / omitted to indicate no error for that field.
+ *
+ * Use `"_"` as a key for form-level errors that don't belong to a specific field:
+ * ```typescript
+ * { _: "You must accept the terms and conditions." }
+ * ```
+ */
+export type FieldErrors = Record<string, string | undefined>;
 export interface SerializedPathState {
     version: 1;
     pathId: string;
@@ -15,6 +25,19 @@ export interface SerializedPathState {
     }>;
     _isNavigating: boolean;
 }
+/**
+ * The interface every path state store must implement.
+ *
+ * `HttpStore` from `@daltonr/pathwrite-store-http` is the reference
+ * implementation. Any backend — MongoDB, Redis, localStorage, etc. —
+ * implements this interface and works with `httpPersistence` and
+ * `restoreOrStart` without any other changes.
+ */
+export interface PathStore {
+    save(key: string, state: SerializedPathState): Promise<void>;
+    load(key: string): Promise<SerializedPathState | null>;
+    delete(key: string): Promise<void>;
+}
 export interface PathStepContext<TData extends PathData = PathData> {
     readonly pathId: string;
     readonly stepId: string;
@@ -36,12 +59,26 @@ export interface PathStep<TData extends PathData = PathData> {
     canMoveNext?: (ctx: PathStepContext<TData>) => boolean | Promise<boolean>;
     canMovePrevious?: (ctx: PathStepContext<TData>) => boolean | Promise<boolean>;
     /**
-     * Returns a list of human-readable messages explaining why the step is not
-     * yet valid. The shell displays these messages below the step content so
-     * consumers do not need to duplicate guard logic in the template.
-     * Evaluated synchronously on every snapshot; async functions default to `[]`.
+     * Returns a map of field ID → error message explaining why the step is not
+     * yet valid. The shell displays these messages below the step content (labeled
+     * by field name) so consumers do not need to duplicate validation logic in
+     * the template. Return `undefined` for a field to indicate no error.
+     *
+     * When `fieldMessages` is provided and `canMoveNext` is **not**, the engine
+     * automatically derives `canMoveNext` as `true` when all values are `undefined`
+     * (i.e. no messages), eliminating the need to express the same logic twice.
+     *
+     * Evaluated synchronously on every snapshot; async functions default to `{}`.
+     *
+     * @example
+     * ```typescript
+     * fieldMessages: ({ data }) => ({
+     *   name:  !data.name?.trim()        ? "Required."             : undefined,
+     *   email: !isValidEmail(data.email) ? "Invalid email address." : undefined,
+     * })
+     * ```
      */
-    validationMessages?: (ctx: PathStepContext<TData>) => string[] | Promise<string[]>;
+    fieldMessages?: (ctx: PathStepContext<TData>) => FieldErrors;
     onEnter?: (ctx: PathStepContext<TData>) => Partial<TData> | void | Promise<Partial<TData> | void>;
     onLeave?: (ctx: PathStepContext<TData>) => Partial<TData> | void | Promise<Partial<TData> | void>;
     /**
@@ -87,16 +124,44 @@ export interface PathSnapshot<TData extends PathData = PathData> {
     nestingLevel: number;
     /** True while an async guard or hook is executing. Use to disable navigation controls. */
     isNavigating: boolean;
-    /** Whether the current step's `canMoveNext` guard allows advancing. Async guards default to `true`. */
+    /** Whether the current step's `canMoveNext` guard allows advancing. Async guards default to `true`. Auto-derived as `true` when `fieldMessages` is defined and returns no messages, and `canMoveNext` is not explicitly defined. */
     canMoveNext: boolean;
     /** Whether the current step's `canMovePrevious` guard allows going back. Async guards default to `true`. */
     canMovePrevious: boolean;
-    /** Messages from the current step's `validationMessages` hook. Empty array when there are none. */
-    validationMessages: string[];
+    /**
+     * True after the user has clicked Next / Submit on this step at least once,
+     * regardless of whether navigation succeeded. Resets to `false` when entering
+     * a new step.
+     *
+     * Use this to gate inline field-error display so errors are hidden on first
+     * render and only appear after the user has attempted to proceed:
+     *
+     * ```svelte
+     * {#if snapshot.hasAttemptedNext && snapshot.fieldMessages.email}
+     *   <span class="error">{snapshot.fieldMessages.email}</span>
+     * {/if}
+     * ```
+     *
+     * The shell itself uses this flag to gate its own automatic `fieldMessages`
+     * summary rendering — errors are never shown before the first Next attempt.
+     */
+    hasAttemptedNext: boolean;
+    /**
+     * Field-keyed validation messages for the current step. Empty object when there are none.
+     * Use in step templates to render inline per-field errors: `snapshot.fieldMessages['email']`.
+     * The shell also renders these automatically in a labeled summary box.
+     * Use `"_"` as a key for form-level (non-field-specific) errors.
+     */
+    fieldMessages: Record<string, string>;
     data: TData;
 }
+/**
+ * Identifies the public method that triggered a `stateChanged` event.
+ */
+export type StateChangeCause = "start" | "next" | "previous" | "goToStep" | "goToStepChecked" | "setData" | "cancel" | "restart";
 export type PathEvent = {
     type: "stateChanged";
+    cause: StateChangeCause;
     snapshot: PathSnapshot;
 } | {
     type: "completed";
@@ -112,11 +177,65 @@ export type PathEvent = {
     fromSubPathId: string;
     snapshot: PathSnapshot;
 };
+/**
+ * A function called on every engine event. Observers are registered at
+ * construction time and receive every event for the lifetime of the engine.
+ *
+ * The second argument is the engine itself — useful when the observer needs to
+ * read current state (e.g. calling `engine.exportState()` for persistence).
+ *
+ * ```typescript
+ * const logger: PathObserver = (event) => console.log(event.type);
+ * const persist: PathObserver = (event, engine) => { ... };
+ * ```
+ */
+export type PathObserver = (event: PathEvent, engine: PathEngine) => void;
+/**
+ * Determines which engine events an observer should react to.
+ *
+ * | Strategy            | Triggers when                                              |
+ * |---------------------|------------------------------------------------------------|
+ * | `"onEveryChange"`   | Any settled `stateChanged` or `resumed`                    |
+ * | `"onNext"`          | `next()` completes navigation *(default)*                  |
+ * | `"onSubPathComplete"` | Sub-path finishes and the parent resumes                 |
+ * | `"onComplete"`      | The entire path completes                                  |
+ * | `"manual"`          | Never — caller decides when to act                        |
+ */
+export type ObserverStrategy = "onEveryChange" | "onNext" | "onSubPathComplete" | "onComplete" | "manual";
+/**
+ * Returns `true` when `event` matches the trigger condition for `strategy`.
+ *
+ * Use this in any `PathObserver` factory to centralise the
+ * "which events should I react to?" decision so every observer
+ * (HTTP, MongoDB, logger, analytics…) shares the same semantics.
+ *
+ * ```typescript
+ * const observer: PathObserver = (event, engine) => {
+ *   if (matchesStrategy(strategy, event)) doWork(engine);
+ * };
+ * ```
+ */
+export declare function matchesStrategy(strategy: ObserverStrategy, event: PathEvent): boolean;
+/**
+ * Options accepted by the `PathEngine` constructor and `PathEngine.fromState()`.
+ */
+export interface PathEngineOptions {
+    /**
+     * Zero or more observers to register before the first event fires.
+     * Each observer is called synchronously on every engine event for the
+     * lifetime of the engine. Observers cannot be removed; for removable
+     * listeners use `engine.subscribe()`.
+     */
+    observers?: PathObserver[];
+}
 export declare class PathEngine {
     private activePath;
     private readonly pathStack;
     private readonly listeners;
     private _isNavigating;
+    /** True after the user has called next() on the current step at least once. Resets on step entry. */
+    private _hasAttemptedNext;
+    constructor(options?: PathEngineOptions);
     /**
      * Restores a PathEngine from previously exported state.
      *
@@ -131,7 +250,7 @@ export declare class PathEngine {
      * @throws If `state` references a path ID not present in `pathDefinitions`,
      *         or if the state format is invalid.
      */
-    static fromState(state: SerializedPathState, pathDefinitions: Record<string, PathDefinition>): PathEngine;
+    static fromState(state: SerializedPathState, pathDefinitions: Record<string, PathDefinition>, options?: PathEngineOptions): PathEngine;
     subscribe(listener: (event: PathEvent) => void): () => void;
     start(path: PathDefinition<any>, initialData?: PathData): Promise<void>;
     /**
@@ -227,15 +346,20 @@ export declare class PathEngine {
      */
     private evaluateGuardSync;
     /**
-     * Evaluates a validationMessages function synchronously for inclusion in the snapshot.
-     * If the hook is absent, returns `[]`.
-     * If the hook returns a `Promise`, returns `[]` (async hooks are not supported in snapshots).
+     * Evaluates `canMoveNext` synchronously for inclusion in the snapshot.
+     * When `canMoveNext` is defined, delegates to `evaluateGuardSync`.
+     * When absent but `fieldMessages` is defined, auto-derives: `true` iff no messages.
+     * When neither is defined, returns `true`.
+     */
+    private evaluateCanMoveNextSync;
+    /**
+     * Evaluates a fieldMessages function synchronously for inclusion in the snapshot.
+     * If the hook is absent, returns `{}`.
+     * If the hook returns a `Promise`, returns `{}` (async hooks are not supported in snapshots).
+     * `undefined` values are stripped from the result — only fields with a defined message are included.
      *
-     * **Note:** Like guards, `validationMessages` is evaluated before `onEnter` runs on first
+     * **Note:** Like guards, `fieldMessages` is evaluated before `onEnter` runs on first
      * entry. Write it defensively so it does not throw when fields are absent.
-     *
-     * If the function throws, the error is caught, a `console.warn` is emitted, and `[]`
-     * is returned so validation messages do not block the UI unexpectedly.
      */
-    private evaluateValidationMessagesSync;
+    private evaluateFieldMessagesSync;
 }

package/dist/index.js

@@ -1,8 +1,50 @@
+/**
+ * Returns `true` when `event` matches the trigger condition for `strategy`.
+ *
+ * Use this in any `PathObserver` factory to centralise the
+ * "which events should I react to?" decision so every observer
+ * (HTTP, MongoDB, logger, analytics…) shares the same semantics.
+ *
+ * ```typescript
+ * const observer: PathObserver = (event, engine) => {
+ *   if (matchesStrategy(strategy, event)) doWork(engine);
+ * };
+ * ```
+ */
+export function matchesStrategy(strategy, event) {
+    switch (strategy) {
+        case "onEveryChange":
+            // Only react once navigation has settled — stateChanged fires twice per
+            // navigation (isNavigating:true then false).
+            return (event.type === "stateChanged" && !event.snapshot.isNavigating)
+                || event.type === "resumed";
+        case "onNext":
+            return event.type === "stateChanged"
+                && event.cause === "next"
+                && !event.snapshot.isNavigating;
+        case "onSubPathComplete":
+            return event.type === "resumed";
+        case "onComplete":
+            return event.type === "completed";
+        case "manual":
+            return false;
+    }
+}
 export class PathEngine {
     activePath = null;
     pathStack = [];
     listeners = new Set();
     _isNavigating = false;
+    /** True after the user has called next() on the current step at least once. Resets on step entry. */
+    _hasAttemptedNext = false;
+    constructor(options) {
+        if (options?.observers) {
+            for (const observer of options.observers) {
+                // Wrap so observer receives the engine instance as the second argument
+                this.listeners.add((event) => observer(event, this));
+            }
+        }
+    }
     /**
      * Restores a PathEngine from previously exported state.
      *
@@ -17,11 +59,11 @@ export class PathEngine {
      * @throws If `state` references a path ID not present in `pathDefinitions`,
      *         or if the state format is invalid.
      */
-    static fromState(state, pathDefinitions) {
+    static fromState(state, pathDefinitions, options) {
         if (state.version !== 1) {
             throw new Error(`Unsupported SerializedPathState version: ${state.version}`);
         }
-        const engine = new PathEngine();
+        const engine = new PathEngine(options);
         // Restore the path stack (sub-paths)
         for (const stackItem of state.pathStack) {
             const definition = pathDefinitions[stackItem.pathId];
@@ -130,7 +172,7 @@ export class PathEngine {
     setData(key, value) {
         const active = this.requireActivePath();
         active.data[key] = value;
-        this.emitStateChanged();
+        this.emitStateChanged("setData");
         return Promise.resolve();
     }
     /** Jumps directly to the step with the given ID. Does not check guards or shouldSkip. */
@@ -191,9 +233,10 @@ export class PathEngine {
                 this.pathStack.length === 0,
             nestingLevel: this.pathStack.length,
             isNavigating: this._isNavigating,
-            canMoveNext: this.evaluateGuardSync(step.canMoveNext, active),
+            hasAttemptedNext: this._hasAttemptedNext,
+            canMoveNext: this.evaluateCanMoveNextSync(step, active),
             canMovePrevious: this.evaluateGuardSync(step.canMovePrevious, active),
-            validationMessages: this.evaluateValidationMessagesSync(step.validationMessages, active),
+            fieldMessages: this.evaluateFieldMessagesSync(step.fieldMessages, active),
             data: { ...active.data }
         };
     }
@@ -257,23 +300,26 @@ export class PathEngine {
             await this.finishActivePath();
             return;
         }
-        this.emitStateChanged();
+        this.emitStateChanged("start");
         try {
             this.applyPatch(await this.enterCurrentStep());
             this._isNavigating = false;
-            this.emitStateChanged();
+            this.emitStateChanged("start");
         }
         catch (err) {
             this._isNavigating = false;
-            this.emitStateChanged();
+            this.emitStateChanged("start");
             throw err;
         }
     }
     async _nextAsync(active) {
         if (this._isNavigating)
             return;
+        // Record that the user has attempted to advance — used by shells and step
+        // templates to gate error display ("punish late, reward early").
+        this._hasAttemptedNext = true;
         this._isNavigating = true;
-        this.emitStateChanged();
+        this.emitStateChanged("next");
         try {
             const step = this.getCurrentStep(active);
             if (await this.canMoveNext(active, step)) {
@@ -288,11 +334,11 @@ export class PathEngine {
                 this.applyPatch(await this.enterCurrentStep());
             }
             this._isNavigating = false;
-            this.emitStateChanged();
+            this.emitStateChanged("next");
         }
         catch (err) {
             this._isNavigating = false;
-            this.emitStateChanged();
+            this.emitStateChanged("next");
             throw err;
         }
     }
@@ -305,7 +351,7 @@ export class PathEngine {
         if (active.currentStepIndex === 0 && this.pathStack.length === 0)
             return;
         this._isNavigating = true;
-        this.emitStateChanged();
+        this.emitStateChanged("previous");
         try {
             const step = this.getCurrentStep(active);
             if (await this.canMovePrevious(active, step)) {
@@ -320,11 +366,11 @@ export class PathEngine {
                 this.applyPatch(await this.enterCurrentStep());
             }
             this._isNavigating = false;
-            this.emitStateChanged();
+            this.emitStateChanged("previous");
         }
         catch (err) {
             this._isNavigating = false;
-            this.emitStateChanged();
+            this.emitStateChanged("previous");
             throw err;
         }
     }
@@ -332,18 +378,18 @@ export class PathEngine {
         if (this._isNavigating)
             return;
         this._isNavigating = true;
-        this.emitStateChanged();
+        this.emitStateChanged("goToStep");
         try {
             const currentStep = this.getCurrentStep(active);
             this.applyPatch(await this.leaveCurrentStep(active, currentStep));
             active.currentStepIndex = targetIndex;
             this.applyPatch(await this.enterCurrentStep());
             this._isNavigating = false;
-            this.emitStateChanged();
+            this.emitStateChanged("goToStep");
         }
         catch (err) {
             this._isNavigating = false;
-            this.emitStateChanged();
+            this.emitStateChanged("goToStep");
             throw err;
         }
     }
@@ -351,7 +397,7 @@ export class PathEngine {
         if (this._isNavigating)
             return;
         this._isNavigating = true;
-        this.emitStateChanged();
+        this.emitStateChanged("goToStepChecked");
         try {
             const currentStep = this.getCurrentStep(active);
             const goingForward = targetIndex > active.currentStepIndex;
@@ -364,11 +410,11 @@ export class PathEngine {
                 this.applyPatch(await this.enterCurrentStep());
             }
             this._isNavigating = false;
-            this.emitStateChanged();
+            this.emitStateChanged("goToStepChecked");
         }
         catch (err) {
             this._isNavigating = false;
-            this.emitStateChanged();
+            this.emitStateChanged("goToStepChecked");
             throw err;
         }
     }
@@ -378,7 +424,7 @@ export class PathEngine {
         // sub-path (which may have currentStepIndex = -1).
         this.activePath = this.pathStack.pop() ?? null;
         this._isNavigating = true;
-        this.emitStateChanged();
+        this.emitStateChanged("cancel");
         try {
             const parent = this.activePath;
             if (parent) {
@@ -394,11 +440,11 @@ export class PathEngine {
                 }
             }
             this._isNavigating = false;
-            this.emitStateChanged();
+            this.emitStateChanged("cancel");
         }
         catch (err) {
             this._isNavigating = false;
-            this.emitStateChanged();
+            this.emitStateChanged("cancel");
             throw err;
         }
     }
@@ -452,8 +498,8 @@ export class PathEngine {
             listener(event);
         }
     }
-    emitStateChanged() {
-        this.emit({ type: "stateChanged", snapshot: this.snapshot() });
+    emitStateChanged(cause) {
+        this.emit({ type: "stateChanged", cause, snapshot: this.snapshot() });
     }
     getCurrentStep(active) {
         return active.definition.steps[active.currentStepIndex];
@@ -488,6 +534,8 @@ export class PathEngine {
         }
     }
     async enterCurrentStep() {
+        // Each step starts fresh — errors are not shown until the user attempts to proceed.
+        this._hasAttemptedNext = false;
         const active = this.activePath;
         if (!active)
             return;
@@ -518,15 +566,19 @@ export class PathEngine {
         return step.onLeave(ctx);
     }
     async canMoveNext(active, step) {
-        if (!step.canMoveNext)
-            return true;
-        const ctx = {
-            pathId: active.definition.id,
-            stepId: step.id,
-            data: { ...active.data },
-            isFirstEntry: !active.visitedStepIds.has(step.id)
-        };
-        return step.canMoveNext(ctx);
+        if (step.canMoveNext) {
+            const ctx = {
+                pathId: active.definition.id,
+                stepId: step.id,
+                data: { ...active.data },
+                isFirstEntry: !active.visitedStepIds.has(step.id)
+            };
+            return step.canMoveNext(ctx);
+        }
+        if (step.fieldMessages) {
+            return Object.keys(this.evaluateFieldMessagesSync(step.fieldMessages, active)).length === 0;
+        }
+        return true;
     }
     async canMovePrevious(active, step) {
         if (!step.canMovePrevious)
@@ -585,19 +637,31 @@ export class PathEngine {
         }
     }
     /**
-     * Evaluates a validationMessages function synchronously for inclusion in the snapshot.
-     * If the hook is absent, returns `[]`.
-     * If the hook returns a `Promise`, returns `[]` (async hooks are not supported in snapshots).
+     * Evaluates `canMoveNext` synchronously for inclusion in the snapshot.
+     * When `canMoveNext` is defined, delegates to `evaluateGuardSync`.
+     * When absent but `fieldMessages` is defined, auto-derives: `true` iff no messages.
+     * When neither is defined, returns `true`.
+     */
+    evaluateCanMoveNextSync(step, active) {
+        if (step.canMoveNext)
+            return this.evaluateGuardSync(step.canMoveNext, active);
+        if (step.fieldMessages) {
+            return Object.keys(this.evaluateFieldMessagesSync(step.fieldMessages, active)).length === 0;
+        }
+        return true;
+    }
+    /**
+     * Evaluates a fieldMessages function synchronously for inclusion in the snapshot.
+     * If the hook is absent, returns `{}`.
+     * If the hook returns a `Promise`, returns `{}` (async hooks are not supported in snapshots).
+     * `undefined` values are stripped from the result — only fields with a defined message are included.
      *
-     * **Note:** Like guards, `validationMessages` is evaluated before `onEnter` runs on first
+     * **Note:** Like guards, `fieldMessages` is evaluated before `onEnter` runs on first
      * entry. Write it defensively so it does not throw when fields are absent.
-     *
-     * If the function throws, the error is caught, a `console.warn` is emitted, and `[]`
-     * is returned so validation messages do not block the UI unexpectedly.
      */
-    evaluateValidationMessagesSync(fn, active) {
+    evaluateFieldMessagesSync(fn, active) {
         if (!fn)
-            return [];
+            return {};
         const step = this.getCurrentStep(active);
         const ctx = {
             pathId: active.definition.id,
@@ -607,23 +671,28 @@ export class PathEngine {
         };
         try {
             const result = fn(ctx);
-            if (Array.isArray(result))
-                return result;
-            // Async validationMessages detected - warn and return empty array
+            if (result && typeof result === "object" && typeof result.then !== "function") {
+                const filtered = {};
+                for (const [key, val] of Object.entries(result)) {
+                    if (val !== undefined && val !== null && val !== "") {
+                        filtered[key] = val;
+                    }
+                }
+                return filtered;
+            }
             if (result && typeof result.then === "function") {
-                console.warn(`[pathwrite] Async validationMessages detected on step "${step.id}". ` +
-                    `validationMessages in snapshots must be synchronous. ` +
-                    `Returning [] as default. ` +
+                console.warn(`[pathwrite] Async fieldMessages detected on step "${step.id}". ` +
+                    `fieldMessages must be synchronous. Returning {} as default. ` +
                     `Use synchronous validation or move async checks to canMoveNext.`);
             }
-            return [];
+            return {};
         }
         catch (err) {
-            console.warn(`[pathwrite] validationMessages on step "${step.id}" threw an error during snapshot evaluation. ` +
-                `Returning [] as a safe default. ` +
-                `Note: validationMessages is evaluated before onEnter runs on first entry — ` +
+            console.warn(`[pathwrite] fieldMessages on step "${step.id}" threw an error during snapshot evaluation. ` +
+                `Returning {} as a safe default. ` +
+                `Note: fieldMessages is evaluated before onEnter runs on first entry — ` +
                 `ensure it handles missing/undefined data gracefully.`, err);
-            return [];
+            return {};
         }
     }
 }

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daltonr/pathwrite-core",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "type": "module",
   "license": "MIT",
   "description": "Headless path engine — deterministic state machine with stack-based sub-path orchestration. Zero dependencies.",

package/src/index.ts

@@ -1,5 +1,16 @@
 export type PathData = Record<string, unknown>;
 
+/**
+ * The return type of a `fieldMessages` hook. Each key is a field ID; the value
+ * is an error string, or `undefined` / omitted to indicate no error for that field.
+ *
+ * Use `"_"` as a key for form-level errors that don't belong to a specific field:
+ * ```typescript
+ * { _: "You must accept the terms and conditions." }
+ * ```
+ */
+export type FieldErrors = Record<string, string | undefined>;
+
 export interface SerializedPathState {
   version: 1;
   pathId: string;
@@ -17,6 +28,20 @@ export interface SerializedPathState {
   _isNavigating: boolean;
 }
 
+/**
+ * The interface every path state store must implement.
+ *
+ * `HttpStore` from `@daltonr/pathwrite-store-http` is the reference
+ * implementation. Any backend — MongoDB, Redis, localStorage, etc. —
+ * implements this interface and works with `httpPersistence` and
+ * `restoreOrStart` without any other changes.
+ */
+export interface PathStore {
+  save(key: string, state: SerializedPathState): Promise<void>;
+  load(key: string): Promise<SerializedPathState | null>;
+  delete(key: string): Promise<void>;
+}
+
 export interface PathStepContext<TData extends PathData = PathData> {
   readonly pathId: string;
   readonly stepId: string;
@@ -39,12 +64,26 @@ export interface PathStep<TData extends PathData = PathData> {
   canMoveNext?: (ctx: PathStepContext<TData>) => boolean | Promise<boolean>;
   canMovePrevious?: (ctx: PathStepContext<TData>) => boolean | Promise<boolean>;
   /**
-   * Returns a list of human-readable messages explaining why the step is not
-   * yet valid. The shell displays these messages below the step content so
-   * consumers do not need to duplicate guard logic in the template.
-   * Evaluated synchronously on every snapshot; async functions default to `[]`.
+   * Returns a map of field ID → error message explaining why the step is not
+   * yet valid. The shell displays these messages below the step content (labeled
+   * by field name) so consumers do not need to duplicate validation logic in
+   * the template. Return `undefined` for a field to indicate no error.
+   *
+   * When `fieldMessages` is provided and `canMoveNext` is **not**, the engine
+   * automatically derives `canMoveNext` as `true` when all values are `undefined`
+   * (i.e. no messages), eliminating the need to express the same logic twice.
+   *
+   * Evaluated synchronously on every snapshot; async functions default to `{}`.
+   *
+   * @example
+   * ```typescript
+   * fieldMessages: ({ data }) => ({
+   *   name:  !data.name?.trim()        ? "Required."             : undefined,
+   *   email: !isValidEmail(data.email) ? "Invalid email address." : undefined,
+   * })
+   * ```
    */
-  validationMessages?: (ctx: PathStepContext<TData>) => string[] | Promise<string[]>;
+  fieldMessages?: (ctx: PathStepContext<TData>) => FieldErrors;
   onEnter?: (ctx: PathStepContext<TData>) => Partial<TData> | void | Promise<Partial<TData> | void>;
   onLeave?: (ctx: PathStepContext<TData>) => Partial<TData> | void | Promise<Partial<TData> | void>;
   /**
@@ -104,17 +143,53 @@ export interface PathSnapshot<TData extends PathData = PathData> {
   nestingLevel: number;
   /** True while an async guard or hook is executing. Use to disable navigation controls. */
   isNavigating: boolean;
-  /** Whether the current step's `canMoveNext` guard allows advancing. Async guards default to `true`. */
+  /** Whether the current step's `canMoveNext` guard allows advancing. Async guards default to `true`. Auto-derived as `true` when `fieldMessages` is defined and returns no messages, and `canMoveNext` is not explicitly defined. */
   canMoveNext: boolean;
   /** Whether the current step's `canMovePrevious` guard allows going back. Async guards default to `true`. */
   canMovePrevious: boolean;
-  /** Messages from the current step's `validationMessages` hook. Empty array when there are none. */
-  validationMessages: string[];
+  /**
+   * True after the user has clicked Next / Submit on this step at least once,
+   * regardless of whether navigation succeeded. Resets to `false` when entering
+   * a new step.
+   *
+   * Use this to gate inline field-error display so errors are hidden on first
+   * render and only appear after the user has attempted to proceed:
+   *
+   * ```svelte
+   * {#if snapshot.hasAttemptedNext && snapshot.fieldMessages.email}
+   *   <span class="error">{snapshot.fieldMessages.email}</span>
+   * {/if}
+   * ```
+   *
+   * The shell itself uses this flag to gate its own automatic `fieldMessages`
+   * summary rendering — errors are never shown before the first Next attempt.
+   */
+  hasAttemptedNext: boolean;
+  /**
+   * Field-keyed validation messages for the current step. Empty object when there are none.
+   * Use in step templates to render inline per-field errors: `snapshot.fieldMessages['email']`.
+   * The shell also renders these automatically in a labeled summary box.
+   * Use `"_"` as a key for form-level (non-field-specific) errors.
+   */
+  fieldMessages: Record<string, string>;
   data: TData;
 }
 
+/**
+ * Identifies the public method that triggered a `stateChanged` event.
+ */
+export type StateChangeCause =
+  | "start"
+  | "next"
+  | "previous"
+  | "goToStep"
+  | "goToStepChecked"
+  | "setData"
+  | "cancel"
+  | "restart";
+
 export type PathEvent =
-  | { type: "stateChanged"; snapshot: PathSnapshot }
+  | { type: "stateChanged"; cause: StateChangeCause; snapshot: PathSnapshot }
   | { type: "completed"; pathId: string; data: PathData }
   | { type: "cancelled"; pathId: string; data: PathData }
   | {
@@ -124,6 +199,84 @@ export type PathEvent =
       snapshot: PathSnapshot;
     };
 
+/**
+ * A function called on every engine event. Observers are registered at
+ * construction time and receive every event for the lifetime of the engine.
+ *
+ * The second argument is the engine itself — useful when the observer needs to
+ * read current state (e.g. calling `engine.exportState()` for persistence).
+ *
+ * ```typescript
+ * const logger: PathObserver = (event) => console.log(event.type);
+ * const persist: PathObserver = (event, engine) => { ... };
+ * ```
+ */
+export type PathObserver = (event: PathEvent, engine: PathEngine) => void;
+
+/**
+ * Determines which engine events an observer should react to.
+ *
+ * | Strategy            | Triggers when                                              |
+ * |---------------------|------------------------------------------------------------|
+ * | `"onEveryChange"`   | Any settled `stateChanged` or `resumed`                    |
+ * | `"onNext"`          | `next()` completes navigation *(default)*                  |
+ * | `"onSubPathComplete"` | Sub-path finishes and the parent resumes                 |
+ * | `"onComplete"`      | The entire path completes                                  |
+ * | `"manual"`          | Never — caller decides when to act                        |
+ */
+export type ObserverStrategy =
+  | "onEveryChange"
+  | "onNext"
+  | "onSubPathComplete"
+  | "onComplete"
+  | "manual";
+
+/**
+ * Returns `true` when `event` matches the trigger condition for `strategy`.
+ *
+ * Use this in any `PathObserver` factory to centralise the
+ * "which events should I react to?" decision so every observer
+ * (HTTP, MongoDB, logger, analytics…) shares the same semantics.
+ *
+ * ```typescript
+ * const observer: PathObserver = (event, engine) => {
+ *   if (matchesStrategy(strategy, event)) doWork(engine);
+ * };
+ * ```
+ */
+export function matchesStrategy(strategy: ObserverStrategy, event: PathEvent): boolean {
+  switch (strategy) {
+    case "onEveryChange":
+      // Only react once navigation has settled — stateChanged fires twice per
+      // navigation (isNavigating:true then false).
+      return (event.type === "stateChanged" && !event.snapshot.isNavigating)
+        || event.type === "resumed";
+    case "onNext":
+      return event.type === "stateChanged"
+        && event.cause === "next"
+        && !event.snapshot.isNavigating;
+    case "onSubPathComplete":
+      return event.type === "resumed";
+    case "onComplete":
+      return event.type === "completed";
+    case "manual":
+      return false;
+  }
+}
+
+/**
+ * Options accepted by the `PathEngine` constructor and `PathEngine.fromState()`.
+ */
+export interface PathEngineOptions {
+  /**
+   * Zero or more observers to register before the first event fires.
+   * Each observer is called synchronously on every engine event for the
+   * lifetime of the engine. Observers cannot be removed; for removable
+   * listeners use `engine.subscribe()`.
+   */
+  observers?: PathObserver[];
+}
+
 interface ActivePath {
   definition: PathDefinition;
   currentStepIndex: number;
@@ -137,6 +290,17 @@ export class PathEngine {
   private readonly pathStack: ActivePath[] = [];
   private readonly listeners = new Set<(event: PathEvent) => void>();
   private _isNavigating = false;
+  /** True after the user has called next() on the current step at least once. Resets on step entry. */
+  private _hasAttemptedNext = false;
+
+  constructor(options?: PathEngineOptions) {
+    if (options?.observers) {
+      for (const observer of options.observers) {
+        // Wrap so observer receives the engine instance as the second argument
+        this.listeners.add((event) => observer(event, this));
+      }
+    }
+  }
 
   /**
    * Restores a PathEngine from previously exported state.
@@ -154,13 +318,14 @@ export class PathEngine {
    */
   public static fromState(
     state: SerializedPathState,
-    pathDefinitions: Record<string, PathDefinition>
+    pathDefinitions: Record<string, PathDefinition>,
+    options?: PathEngineOptions
   ): PathEngine {
     if (state.version !== 1) {
       throw new Error(`Unsupported SerializedPathState version: ${state.version}`);
     }
 
-    const engine = new PathEngine();
+    const engine = new PathEngine(options);
 
     // Restore the path stack (sub-paths)
     for (const stackItem of state.pathStack) {
@@ -289,7 +454,7 @@ export class PathEngine {
   public setData(key: string, value: unknown): Promise<void> {
     const active = this.requireActivePath();
     active.data[key] = value;
-    this.emitStateChanged();
+    this.emitStateChanged("setData");
     return Promise.resolve();
   }
 
@@ -355,9 +520,10 @@ export class PathEngine {
         this.pathStack.length === 0,
       nestingLevel: this.pathStack.length,
       isNavigating: this._isNavigating,
-      canMoveNext: this.evaluateGuardSync(step.canMoveNext, active),
+      hasAttemptedNext: this._hasAttemptedNext,
+      canMoveNext: this.evaluateCanMoveNextSync(step, active),
       canMovePrevious: this.evaluateGuardSync(step.canMovePrevious, active),
-      validationMessages: this.evaluateValidationMessagesSync(step.validationMessages, active),
+      fieldMessages: this.evaluateFieldMessagesSync(step.fieldMessages, active),
       data: { ...active.data }
     };
   }
@@ -431,15 +597,15 @@ export class PathEngine {
       return;
     }
 
-    this.emitStateChanged();
+    this.emitStateChanged("start");
 
     try {
       this.applyPatch(await this.enterCurrentStep());
       this._isNavigating = false;
-      this.emitStateChanged();
+      this.emitStateChanged("start");
     } catch (err) {
       this._isNavigating = false;
-      this.emitStateChanged();
+      this.emitStateChanged("start");
       throw err;
     }
   }
@@ -447,8 +613,11 @@ export class PathEngine {
   private async _nextAsync(active: ActivePath): Promise<void> {
     if (this._isNavigating) return;
 
+    // Record that the user has attempted to advance — used by shells and step
+    // templates to gate error display ("punish late, reward early").
+    this._hasAttemptedNext = true;
     this._isNavigating = true;
-    this.emitStateChanged();
+    this.emitStateChanged("next");
 
     try {
       const step = this.getCurrentStep(active);
@@ -468,10 +637,10 @@ export class PathEngine {
       }
 
       this._isNavigating = false;
-      this.emitStateChanged();
+      this.emitStateChanged("next");
     } catch (err) {
       this._isNavigating = false;
-      this.emitStateChanged();
+      this.emitStateChanged("next");
       throw err;
     }
   }
@@ -485,7 +654,7 @@ export class PathEngine {
     if (active.currentStepIndex === 0 && this.pathStack.length === 0) return;
 
     this._isNavigating = true;
-    this.emitStateChanged();
+    this.emitStateChanged("previous");
 
     try {
       const step = this.getCurrentStep(active);
@@ -505,10 +674,10 @@ export class PathEngine {
       }
 
       this._isNavigating = false;
-      this.emitStateChanged();
+      this.emitStateChanged("previous");
     } catch (err) {
       this._isNavigating = false;
-      this.emitStateChanged();
+      this.emitStateChanged("previous");
       throw err;
     }
   }
@@ -517,7 +686,7 @@ export class PathEngine {
     if (this._isNavigating) return;
 
     this._isNavigating = true;
-    this.emitStateChanged();
+    this.emitStateChanged("goToStep");
 
     try {
       const currentStep = this.getCurrentStep(active);
@@ -527,10 +696,10 @@ export class PathEngine {
 
       this.applyPatch(await this.enterCurrentStep());
       this._isNavigating = false;
-      this.emitStateChanged();
+      this.emitStateChanged("goToStep");
     } catch (err) {
       this._isNavigating = false;
-      this.emitStateChanged();
+      this.emitStateChanged("goToStep");
       throw err;
     }
   }
@@ -539,7 +708,7 @@ export class PathEngine {
     if (this._isNavigating) return;
 
     this._isNavigating = true;
-    this.emitStateChanged();
+    this.emitStateChanged("goToStepChecked");
 
     try {
       const currentStep = this.getCurrentStep(active);
@@ -555,10 +724,10 @@ export class PathEngine {
       }
 
       this._isNavigating = false;
-      this.emitStateChanged();
+      this.emitStateChanged("goToStepChecked");
     } catch (err) {
       this._isNavigating = false;
-      this.emitStateChanged();
+      this.emitStateChanged("goToStepChecked");
       throw err;
     }
   }
@@ -574,7 +743,7 @@ export class PathEngine {
     this.activePath = this.pathStack.pop() ?? null;
 
     this._isNavigating = true;
-    this.emitStateChanged();
+    this.emitStateChanged("cancel");
 
     try {
       const parent = this.activePath;
@@ -595,10 +764,10 @@ export class PathEngine {
       }
 
       this._isNavigating = false;
-      this.emitStateChanged();
+      this.emitStateChanged("cancel");
     } catch (err) {
       this._isNavigating = false;
-      this.emitStateChanged();
+      this.emitStateChanged("cancel");
       throw err;
     }
   }
@@ -662,8 +831,8 @@ export class PathEngine {
     }
   }
 
-  private emitStateChanged(): void {
-    this.emit({ type: "stateChanged", snapshot: this.snapshot()! });
+  private emitStateChanged(cause: StateChangeCause): void {
+    this.emit({ type: "stateChanged", cause, snapshot: this.snapshot()! });
   }
 
   private getCurrentStep(active: ActivePath): PathStep {
@@ -702,6 +871,8 @@ export class PathEngine {
   }
 
   private async enterCurrentStep(): Promise<Partial<PathData> | void> {
+    // Each step starts fresh — errors are not shown until the user attempts to proceed.
+    this._hasAttemptedNext = false;
     const active = this.activePath;
     if (!active) return;
     const step = this.getCurrentStep(active);
@@ -737,14 +908,19 @@ export class PathEngine {
     active: ActivePath,
     step: PathStep
   ): Promise<boolean> {
-    if (!step.canMoveNext) return true;
-    const ctx: PathStepContext = {
-      pathId: active.definition.id,
-      stepId: step.id,
-      data: { ...active.data },
-      isFirstEntry: !active.visitedStepIds.has(step.id)
-    };
-    return step.canMoveNext(ctx);
+    if (step.canMoveNext) {
+      const ctx: PathStepContext = {
+        pathId: active.definition.id,
+        stepId: step.id,
+        data: { ...active.data },
+        isFirstEntry: !active.visitedStepIds.has(step.id)
+      };
+      return step.canMoveNext(ctx);
+    }
+    if (step.fieldMessages) {
+      return Object.keys(this.evaluateFieldMessagesSync(step.fieldMessages, active)).length === 0;
+    }
+    return true;
   }
 
   private async canMovePrevious(
@@ -813,21 +989,33 @@ export class PathEngine {
   }
 
   /**
-   * Evaluates a validationMessages function synchronously for inclusion in the snapshot.
-   * If the hook is absent, returns `[]`.
-   * If the hook returns a `Promise`, returns `[]` (async hooks are not supported in snapshots).
+   * Evaluates `canMoveNext` synchronously for inclusion in the snapshot.
+   * When `canMoveNext` is defined, delegates to `evaluateGuardSync`.
+   * When absent but `fieldMessages` is defined, auto-derives: `true` iff no messages.
+   * When neither is defined, returns `true`.
+   */
+  private evaluateCanMoveNextSync(step: PathStep, active: ActivePath): boolean {
+    if (step.canMoveNext) return this.evaluateGuardSync(step.canMoveNext, active);
+    if (step.fieldMessages) {
+      return Object.keys(this.evaluateFieldMessagesSync(step.fieldMessages, active)).length === 0;
+    }
+    return true;
+  }
+
+  /**
+   * Evaluates a fieldMessages function synchronously for inclusion in the snapshot.
+   * If the hook is absent, returns `{}`.
+   * If the hook returns a `Promise`, returns `{}` (async hooks are not supported in snapshots).
+   * `undefined` values are stripped from the result — only fields with a defined message are included.
    *
-   * **Note:** Like guards, `validationMessages` is evaluated before `onEnter` runs on first
+   * **Note:** Like guards, `fieldMessages` is evaluated before `onEnter` runs on first
    * entry. Write it defensively so it does not throw when fields are absent.
-   *
-   * If the function throws, the error is caught, a `console.warn` is emitted, and `[]`
-   * is returned so validation messages do not block the UI unexpectedly.
    */
-  private evaluateValidationMessagesSync(
-    fn: ((ctx: PathStepContext) => string[] | Promise<string[]>) | undefined,
+  private evaluateFieldMessagesSync(
+    fn: ((ctx: PathStepContext) => FieldErrors) | undefined,
     active: ActivePath
-  ): string[] {
-    if (!fn) return [];
+  ): Record<string, string> {
+    if (!fn) return {};
     const step = this.getCurrentStep(active);
     const ctx: PathStepContext = {
       pathId: active.definition.id,
@@ -837,26 +1025,32 @@ export class PathEngine {
     };
     try {
       const result = fn(ctx);
-      if (Array.isArray(result)) return result;
-      // Async validationMessages detected - warn and return empty array
-      if (result && typeof result.then === "function") {
+      if (result && typeof result === "object" && typeof (result as unknown as { then?: unknown }).then !== "function") {
+        const filtered: Record<string, string> = {};
+        for (const [key, val] of Object.entries(result)) {
+          if (val !== undefined && val !== null && val !== "") {
+            filtered[key] = val;
+          }
+        }
+        return filtered;
+      }
+      if (result && typeof (result as unknown as { then?: unknown }).then === "function") {
         console.warn(
-          `[pathwrite] Async validationMessages detected on step "${step.id}". ` +
-          `validationMessages in snapshots must be synchronous. ` +
-          `Returning [] as default. ` +
+          `[pathwrite] Async fieldMessages detected on step "${step.id}". ` +
+          `fieldMessages must be synchronous. Returning {} as default. ` +
           `Use synchronous validation or move async checks to canMoveNext.`
         );
       }
-      return [];
+      return {};
     } catch (err) {
       console.warn(
-        `[pathwrite] validationMessages on step "${step.id}" threw an error during snapshot evaluation. ` +
-        `Returning [] as a safe default. ` +
-        `Note: validationMessages is evaluated before onEnter runs on first entry — ` +
+        `[pathwrite] fieldMessages on step "${step.id}" threw an error during snapshot evaluation. ` +
+        `Returning {} as a safe default. ` +
+        `Note: fieldMessages is evaluated before onEnter runs on first entry — ` +
         `ensure it handles missing/undefined data gracefully.`,
         err
       );
-      return [];
+      return {};
     }
   }
 }