@daltonr/pathwrite-svelte 0.10.0 → 0.11.0

package/README.md

@@ -1,547 +1,158 @@
 # @daltonr/pathwrite-svelte
 
-Svelte 5 adapter for [@daltonr/pathwrite-core](../core) — reactive stores with lifecycle hooks, guards, and optional `<PathShell>` default UI.
+Svelte 5 adapter for `@daltonr/pathwrite-core` — runes-based reactive state with an optional `<PathShell>` UI component.
 
 ## Installation
 
 ```bash
-npm install @daltonr/pathwrite-svelte
+npm install @daltonr/pathwrite-core @daltonr/pathwrite-svelte
 ```
 
-> **Requires Svelte 5.** This adapter uses runes (`$props`, `$derived`, `$state`) and snippets (`{#snippet}`, `{@render}`).
+Peer dependencies: Svelte 5+.
 
-## Quick Start
+> Uses Svelte 5 runes (`$state`, `$derived`, `$props`) and snippets (`{#snippet}`, `{@render}`). Not compatible with Svelte 4.
 
-### Option 1: Use `usePath()` with custom UI
+## Quick start
 
 ```svelte
+<!-- JobApplicationFlow.svelte -->
 <script lang="ts">
-  import { onMount } from 'svelte';
-  import { usePath } from '@daltonr/pathwrite-svelte';
-  
-  const { snapshot, start, next, previous, setData } = usePath();
-  
-  const myPath = {
-    id: 'signup',
-    steps: [
-      { id: 'details', title: 'Your Details' },
-      { id: 'review', title: 'Review' }
-    ]
-  };
-  
-  onMount(() => {
-    start(myPath, { name: '', email: '' });
-  });
-  
-  let snap = $derived($snapshot);
-</script>
-
-{#if snap}
-  <h2>{snap.steps[snap.stepIndex].title}</h2>
-  
-  {#if snap.stepId === 'details'}
-    <input
-      type="text"
-      value={snap.data.name || ''}
-      oninput={(e) => setData('name', e.currentTarget.value)}
-      placeholder="Name"
-    />
-    <input
-      type="email"
-      value={snap.data.email || ''}
-      oninput={(e) => setData('email', e.currentTarget.value)}
-      placeholder="Email"
-    />
-  {:else if snap.stepId === 'review'}
-    <p>Name: {snap.data.name}</p>
-    <p>Email: {snap.data.email}</p>
-  {/if}
-  
-  <button onclick={previous} disabled={snap.isFirstStep || snap.isNavigating}>
-    Previous
-  </button>
-  <button onclick={next} disabled={!snap.canMoveNext || snap.isNavigating}>
-    {snap.isLastStep ? 'Complete' : 'Next'}
-  </button>
-{/if}
-```
+  import { PathShell } from "@daltonr/pathwrite-svelte";
+  import "@daltonr/pathwrite-svelte/styles.css";
+  import { applicationPath } from "./application-path";
+  import DetailsStep from "./DetailsStep.svelte";
+  import CoverNoteStep from "./CoverNoteStep.svelte";
 
-### Option 2: Use `<PathShell>` with snippets
-
-```svelte
-<script lang="ts">
-  import { PathShell } from '@daltonr/pathwrite-svelte';
-  import '@daltonr/pathwrite-svelte/styles.css';
-  
-  import DetailsForm from './DetailsForm.svelte';
-  import ReviewPanel from './ReviewPanel.svelte';
-  
-  const signupPath = {
-    id: 'signup',
-    steps: [
-      { id: 'details', title: 'Your Details' },
-      { id: 'review', title: 'Review' }
-    ]
-  };
-  
   function handleComplete(data) {
-    console.log('Completed!', data);
+    console.log("Submitted:", data);
   }
 </script>
 
 <PathShell
-  path={signupPath}
-  initialData={{ name: '', email: '' }}
+  path={applicationPath}
+  initialData={{ name: "", email: "", coverNote: "" }}
   oncomplete={handleComplete}
 >
   {#snippet details()}
-    <DetailsForm />
-  {/snippet}
-  {#snippet review()}
-    <ReviewPanel />
+    <DetailsStep />
   {/snippet}
-</PathShell>
-```
-
-Each step is a **Svelte 5 snippet** whose name matches the step ID. PathShell collects them automatically and renders the active one.
-
-> **⚠️ Important: Snippet Names Must Match Step IDs**
->
-> When passing step content to `<PathShell>`, each snippet's name **must exactly match** the corresponding step's `id`:
->
-> ```typescript
-> const myPath = {
->   id: 'signup',
->   steps: [
->     { id: 'details' },  // ← Step ID
->     { id: 'review' }    // ← Step ID
->   ]
-> };
-> ```
->
-> ```svelte
-> <PathShell path={myPath}>
->   {#snippet details()}  <!-- ✅ Matches "details" step -->
->     <DetailsForm />
->   {/snippet}
->   {#snippet review()}   <!-- ✅ Matches "review" step -->
->     <ReviewPanel />
->   {/snippet}
->   {#snippet foo()}      <!-- ❌ No step with id "foo" -->
->     <FooPanel />
->   {/snippet}
-> </PathShell>
-> ```
->
-> If a snippet name doesn't match any step ID, PathShell will render:  
-> **`No content for step "foo"`**
->
-> **💡 Tip:** Use your IDE's "Go to Definition" on the step ID in your path definition, then copy-paste the exact string when creating the snippet. This ensures perfect matching and avoids typos.
-
----
-
-## Simple vs Persisted
-
-PathShell supports two modes. Pick the one that fits your use case:
-
-### Simple — PathShell manages the engine
-
-Pass `path` and `initialData`. PathShell creates and starts the engine for you:
 
-```svelte
-<PathShell
-  path={signupPath}
-  initialData={{ name: '' }}
-  oncomplete={handleComplete}
->
-  {#snippet details()}
-    <DetailsForm />
+  <!-- Step ID is "cover-note"; PathShell resolves the camelCase snippet automatically -->
+  {#snippet coverNote()}
+    <CoverNoteStep />
   {/snippet}
 </PathShell>
 ```
 
-**Use this when:** you don't need persistence, restoration, or custom observers. Quick prototypes, simple forms, one-off wizards.
-
-### Persisted — you create the engine
-
-Create the engine yourself with `restoreOrStart()` and pass it via `engine`. PathShell subscribes to it but does not start or own it:
-
-```svelte
-<script>
-  import { HttpStore, restoreOrStart, persistence } from '@daltonr/pathwrite-store';
-
-  let engine = $state(null);
-
-  onMount(async () => {
-    const result = await restoreOrStart({
-      store: new HttpStore({ baseUrl: '/api/wizard' }),
-      key: 'user:onboarding',
-      path: signupPath,
-      initialData: { name: '' },
-      observers: [
-        persistence({ store, key: 'user:onboarding', strategy: 'onNext' })
-      ]
-    });
-    engine = result.engine;
-  });
-</script>
-
-{#if engine}
-  <PathShell {engine} oncomplete={handleComplete}>
-    {#snippet details()}
-      <DetailsForm />
-    {/snippet}
-  </PathShell>
-{/if}
-```
-
-**Use this when:** you need auto-persistence, restore-on-reload, or custom observers. Production apps, checkout flows, anything where losing progress matters.
-
-> **Don't pass both.** `path` and `engine` are mutually exclusive. If you pass `engine`, PathShell will not call `start()` — it assumes the engine is already running.
-
----
-
-## ⚠️ Step Components Must Use `getPathContext()`
-
-Step components rendered inside `<PathShell>` access the path engine via `getPathContext()` — **not** Svelte's raw `getContext()`.
-
 ```svelte
+<!-- DetailsStep.svelte — step component uses usePathContext -->
 <script lang="ts">
-  // ✅ Correct — always use getPathContext()
-  import { getPathContext } from '@daltonr/pathwrite-svelte';
-  const { snapshot, setData } = getPathContext();
+  import { usePathContext } from "@daltonr/pathwrite-svelte";
 
-  // ❌ Wrong — this will silently return undefined
-  // import { getContext } from 'svelte';
-  // const { snapshot, setData } = getContext('pathContext');
+  const ctx = usePathContext();
 </script>
 
-{#if $snapshot}
+{#if ctx.snapshot}
   <input
-    value={$snapshot.data.name || ''}
-    oninput={(e) => setData('name', e.currentTarget.value)}
+    value={ctx.snapshot.data.name ?? ""}
+    oninput={(e) => ctx.setData("name", e.currentTarget.value)}
+    placeholder="Name"
   />
+  <button onclick={ctx.next}>Next</button>
 {/if}
 ```
 
-`getPathContext()` uses a `Symbol` key internally and throws a clear error if called outside a `<PathShell>`. Using `getContext()` with a string key will fail silently.
+## usePath
 
----
-
-## API
+`usePath<TData>(options?)` creates an isolated path engine instance with runes-based reactive state. The engine is unsubscribed automatically when the component is destroyed.
 
-### `usePath<TData>(options?)`
+> Do not destructure `snapshot` — it is a reactive getter backed by `$state`. Destructuring captures the value once and loses reactivity. Access it as `path.snapshot` throughout the template.
 
-Create a Pathwrite engine with Svelte store bindings. Returns reactive stores and action methods.
-
-```typescript
-const {
-  snapshot,    // Readable<PathSnapshot | null>
-  start,       // (path, initialData?) => Promise<void>
-  next,        // () => Promise<void>
-  previous,    // () => Promise<void>
-  cancel,      // () => Promise<void>
-  setData,     // (key, value) => Promise<void>
-  // ... more actions
-} = usePath();
-```
+| Return value | Type | Description |
+|---|---|---|
+| `snapshot` | `PathSnapshot \| null` | Reactive getter. `null` when no path is active. |
+| `start(definition, data?)` | `Promise<void>` | Start or restart a path. |
+| `restart(definition, data?)` | `Promise<void>` | Tear down any active path and start fresh. |
+| `next()` | `Promise<void>` | Advance one step. Completes on the last step. |
+| `previous()` | `Promise<void>` | Go back one step. No-op on the first step of a top-level path. |
+| `cancel()` | `Promise<void>` | Cancel the active path (or sub-path). |
+| `goToStep(stepId)` | `Promise<void>` | Jump to a step by ID. Calls `onLeave`/`onEnter`; bypasses guards. |
+| `goToStepChecked(stepId)` | `Promise<void>` | Jump to a step by ID, checking the current step's guard first. |
+| `setData(key, value)` | `Promise<void>` | Update a single data field. Type-safe when `TData` is specified. |
+| `startSubPath(definition, data?, meta?)` | `Promise<void>` | Push a sub-path. `meta` is returned to `onSubPathComplete`/`onSubPathCancel`. |
 
-#### Options
+**Options:**
 
 | Option | Type | Description |
-|--------|------|-------------|
-| `engine` | `PathEngine` | External engine (e.g., from `restoreOrStart()`) |
-| `onEvent` | `(event) => void` | Called for every engine event |
+|---|---|---|
+| `engine` | `PathEngine` | Externally-managed engine (e.g. from `restoreOrStart()`). `usePath` subscribes to it; the caller owns the lifecycle. |
+| `onEvent` | `(event: PathEvent) => void` | Called for every engine event. |
 
-#### Returns
+## PathShell props
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `snapshot` | `Readable<PathSnapshot \| null>` | Current path state (reactive store) |
-| `start` | `function` | Start a path |
-| `startSubPath` | `function` | Launch a sub-path |
-| `next` | `function` | Go to next step |
-| `previous` | `function` | Go to previous step |
-| `cancel` | `function` | Cancel the path |
-| `goToStep` | `function` | Jump to step by ID |
-| `goToStepChecked` | `function` | Jump with guard checks |
-| `setData` | `function` | Update data |
-| `restart` | `function` | Restart the path |
-
-### `<PathShell>`
-
-Default UI shell with progress indicator and navigation buttons.
-
-#### Props
+Step content is supplied as Svelte 5 snippets whose names match each step's `id`. For hyphenated step IDs (e.g. `"cover-letter"`), pass the snippet as the camelCase prop (`coverLetter={...}`) — PathShell resolves it automatically. A `console.warn` fires in development if no snippet is found under either the exact ID or the camelCase form.
 
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `path` | `PathDefinition` | — | Path definition (for self-managed engine) |
-| `engine` | `PathEngine` | — | External engine (for persistence — see below) |
-| `initialData` | `PathData` | `{}` | Initial data |
-| `autoStart` | `boolean` | `true` | Auto-start on mount |
-| `backLabel` | `string` | `"Previous"` | Previous button label |
-| `nextLabel` | `string` | `"Next"` | Next button label |
-| `completeLabel` | `string` | `"Complete"` | Complete button label |
-| `cancelLabel` | `string` | `"Cancel"` | Cancel button label |
-| `hideCancel` | `boolean` | `false` | Hide cancel button |
-| `hideProgress` | `boolean` | `false` | Hide progress indicator. Also hidden automatically for single-step top-level paths. |
-| `footerLayout` | `"wizard" \| "form" \| "auto"` | `"auto"` | Footer button layout. `"auto"` uses `"form"` for single-step top-level paths, `"wizard"` otherwise. `"wizard"`: Back on left, Cancel+Submit on right. `"form"`: Cancel on left, Submit on right, no Back button. |
-
-> **`path` vs `engine`:** Pass `path` for simple wizards where PathShell manages the engine. Pass `engine` when you create the engine yourself (e.g., via `restoreOrStart()` for persistence). These are mutually exclusive — don't pass both.
-
-#### Callbacks
-
-| Callback | Type | Description |
-|----------|------|-------------|
-| `oncomplete` | `(data) => void` | Called when path completes |
-| `oncancel` | `(data) => void` | Called when path is cancelled |
-| `onevent` | `(event) => void` | Called for every event |
-
-#### Snippets
-
-Step content is provided as Svelte 5 snippets. The snippet name must match the step ID:
-
-```svelte
-<PathShell path={myPath}>
-  {#snippet details()}
-    <DetailsStep />
-  {/snippet}
-  {#snippet review()}
-    <ReviewStep />
-  {/snippet}
-</PathShell>
-```
-
-You can also override the header and footer:
+|---|---|---|---|
+| `path` | `PathDefinition` | — | Path to run. Mutually exclusive with `engine`. |
+| `engine` | `PathEngine` | — | Externally-managed engine (e.g. from `restoreOrStart()`). Mutually exclusive with `path`. |
+| `initialData` | `PathData` | `{}` | Initial data passed to `engine.start()`. |
+| `autoStart` | `boolean` | `true` | Start on mount. Ignored when `engine` is provided. |
+| `footerLayout` | `"wizard" \| "form" \| "auto"` | `"auto"` | `"wizard"`: Back on left, Cancel+Submit on right. `"form"`: Cancel on left, Submit on right, no Back. `"auto"` picks `"form"` for single-step paths. |
+| `hideProgress` | `boolean` | `false` | Hide the progress indicator. Also hidden automatically for single-step paths. |
+| `backLabel` | `string` | `"Previous"` | Previous button label. |
+| `nextLabel` | `string` | `"Next"` | Next button label. |
+| `completeLabel` | `string` | `"Complete"` | Complete button label (last step). |
+| `cancelLabel` | `string` | `"Cancel"` | Cancel button label. |
+| `hideCancel` | `boolean` | `false` | Hide the Cancel button. |
+| `oncomplete` | `(data: PathData) => void` | — | Called when the path finishes naturally. |
+| `oncancel` | `(data: PathData) => void` | — | Called when the path is cancelled. |
+| `onevent` | `(event: PathEvent) => void` | — | Called for every engine event. |
+
+You can also replace the built-in header and footer with custom snippets:
 
 ```svelte
 <PathShell path={myPath}>
   {#snippet header(snap)}
-    <h2>Step {snap.stepIndex + 1} of {snap.stepCount}</h2>
+    <p>Step {snap.stepIndex + 1} of {snap.stepCount}</p>
   {/snippet}
 
-  {#snippet details()}
-    <DetailsStep />
-  {/snippet}
+  {#snippet details()}<DetailsStep />{/snippet}
 
   {#snippet footer(snap, actions)}
-    <button onclick={actions.previous} disabled={snap.isFirstStep}>
-      ← Back
-    </button>
+    <button onclick={actions.previous} disabled={snap.isFirstStep}>Back</button>
     <button onclick={actions.next} disabled={!snap.canMoveNext}>
-      {snap.isLastStep ? 'Finish' : 'Continue →'}
+      {snap.isLastStep ? "Submit" : "Continue"}
     </button>
   {/snippet}
 </PathShell>
 ```
 
-#### Resetting the path
-
-There are two ways to reset `<PathShell>` to step 1.
-
-**Option 1 — Toggle mount** (simplest, always correct)
-
-Toggle a `$state` rune to destroy and recreate the shell:
-
-```svelte
-<script>
-  let isActive = $state(true);
-</script>
-
-{#if isActive}
-  <PathShell path={myPath} oncomplete={() => (isActive = false)}>
-    {#snippet details()}<DetailsStep />{/snippet}
-  </PathShell>
-{:else}
-  <button onclick={() => (isActive = true)}>Try Again</button>
-{/if}
-```
-
-**Option 2 — Call `restart()` on the shell ref** (in-place, no unmount)
-
-Use `bind:this` to get a reference to the shell instance, then call `restart()`:
-
-```svelte
-<script>
-  let shellRef;
-</script>
-
-<PathShell bind:this={shellRef} path={myPath} oncomplete={onDone}>
-  {#snippet details()}<DetailsStep />{/snippet}
-</PathShell>
-
-<button onclick={() => shellRef.restart()}>Try Again</button>
-```
-
-`restart()` resets the path engine to step 1 with the original `initialData` without unmounting the component. Use this when you need to keep the shell mounted — for example, to preserve scroll position or drive a CSS transition.
-
-### `getPathContext<TData>()`
+## usePathContext
 
-Get the path context from a parent `<PathShell>`. Use this inside step components.
+`usePathContext<TData>()` is the preferred way for step components rendered inside `<PathShell>` to access the path engine. `<PathShell>` calls `setContext()` internally with a private `Symbol` key; `usePathContext()` calls the matching `getContext()` and returns the same interface as `usePath`. It throws a clear error if called outside a `<PathShell>` — do not use Svelte's raw `getContext()` directly, as the key is a private `Symbol` and will silently return `undefined`.
 
 ```svelte
 <script lang="ts">
-  import { getPathContext } from '@daltonr/pathwrite-svelte';
-  
-  const { snapshot, next, setData } = getPathContext();
+  import { usePathContext } from "@daltonr/pathwrite-svelte";
+
+  const ctx = usePathContext<ApplicationData>();
 </script>
 
-{#if $snapshot}
+{#if ctx.snapshot}
   <input
-    value={$snapshot.data.name || ''}
-    oninput={(e) => setData('name', e.currentTarget.value)}
+    value={ctx.snapshot.data.name ?? ""}
+    oninput={(e) => ctx.setData("name", e.currentTarget.value)}
   />
-  <button onclick={next}>Next</button>
 {/if}
 ```
 
-### `bindData(snapshot, setData, key)`
-
-Helper to create a two-way binding store.
-
-```svelte
-<script lang="ts">
-  import { usePath, bindData } from '@daltonr/pathwrite-svelte';
-  
-  const { snapshot, setData } = usePath();
-  const name = bindData(snapshot, setData, 'name');
-</script>
-
-<input bind:value={$name} />
-```
-
-## PathSnapshot
-
-The `snapshot` store contains the current path state:
-
-```typescript
-interface PathSnapshot {
-  pathId: string;
-  stepId: string;
-  stepIndex: number;
-  stepCount: number;
-  data: PathData;
-  nestingLevel: number;
-  isFirstStep: boolean;
-  isLastStep: boolean;
-  canMoveNext: boolean;
-  canMovePrevious: boolean;
-  isNavigating: boolean;
-  progress: number;  // 0-1
-  steps: Array<{ id: string; title?: string; status: 'completed' | 'current' | 'upcoming' }>;
-  validationMessages: string[];
-}
-```
-
-Access it via the store: `$snapshot`
-
-## Guards and Hooks
-
-Define validation and lifecycle logic in your path definition:
-
-```typescript
-const myPath = {
-  id: 'signup',
-  steps: [
-    {
-      id: 'details',
-      canMoveNext: (ctx) => ctx.data.name && ctx.data.email,
-      validationMessages: (ctx) => {
-        const errors = [];
-        if (!ctx.data.name) errors.push('Name is required');
-        if (!ctx.data.email) errors.push('Email is required');
-        return errors;
-      },
-      onEnter: (ctx) => {
-        console.log('Entered details step');
-      },
-      onLeave: (ctx) => {
-        console.log('Leaving details step');
-      }
-    },
-    { id: 'review' }
-  ]
-};
-```
-
-## Persistence
-
-Use with [@daltonr/pathwrite-store](../store) for automatic state persistence:
-
-```svelte
-<script lang="ts">
-  import { onMount } from 'svelte';
-  import { PathShell } from '@daltonr/pathwrite-svelte';
-  import { HttpStore, restoreOrStart, persistence } from '@daltonr/pathwrite-store';
-  import DetailsForm from './DetailsForm.svelte';
-  import ReviewPanel from './ReviewPanel.svelte';
-  
-  const store = new HttpStore({ baseUrl: '/api/wizard' });
-  const key = 'user:123:signup';
-  
-  let engine = $state(null);
-  let restored = $state(false);
-  
-  onMount(async () => {
-    const result = await restoreOrStart({
-      store,
-      key,
-      path: signupPath,
-      initialData: { name: '', email: '' },
-      observers: [
-        persistence({ store, key, strategy: 'onNext' })
-      ]
-    });
-    engine = result.engine;
-    restored = result.restored;
-  });
-</script>
-
-{#if engine}
-  <PathShell {engine} oncomplete={(data) => console.log('Done!', data)}>
-    {#snippet details()}
-      <DetailsForm />
-    {/snippet}
-    {#snippet review()}
-      <ReviewPanel />
-    {/snippet}
-  </PathShell>
-{/if}
-```
-
-## TypeScript
-
-Type your path data for full type safety:
-
-```typescript
-interface SignupData {
-  name: string;
-  email: string;
-  age: number;
-}
-
-const { snapshot, setData } = usePath<SignupData>();
-
-// ✅ Type-checked
-setData('name', 'John');
-
-// ❌ Type error
-setData('invalid', 'value');
-```
-
-## License
-
-MIT — © 2026 Devjoy Ltd.
-
-## See Also
-
-- [@daltonr/pathwrite-core](../core) - Core engine
-- [@daltonr/pathwrite-store](../store) - HTTP persistence
-- [Documentation](../../docs/guides/DEVELOPER_GUIDE.md)
+## Further reading
 
+- [Svelte getting started guide](../../docs/getting-started/frameworks/svelte.md)
+- [Navigation & guards](../../docs/guides/navigation.md)
+- [Full documentation](../../docs/README.md)
 
 ---
 
-© 2026 Devjoy Ltd. MIT License.
-
+MIT — © 2026 Devjoy Ltd.

package/dist/PathShell.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
   import { onMount } from 'svelte';
-  import { usePath, setPathContext, formatFieldKey, errorPhaseMessage } from './index.svelte.js';
+  import { usePath, setPathContext, formatFieldKey, errorPhaseMessage, stepIdToCamelCase } from './index.svelte.js';
   import type { PathDefinition, PathData, PathEngine, PathSnapshot, ProgressLayout } from './index.svelte.js';
   import type { Snippet, Component } from 'svelte';
 
@@ -17,6 +17,10 @@
     cancelLabel?: string;
     hideCancel?: boolean;
     hideProgress?: boolean;
+    /** If true, hide the footer (navigation buttons). The error panel is still shown on async failure regardless of this prop. */
+    hideFooter?: boolean;
+    /** When true, calls `validate()` on the engine so all steps show inline errors simultaneously. Useful when this shell is nested inside a step of an outer shell: bind to the outer snapshot's `hasAttemptedNext`. */
+    validateWhen?: boolean;
     /**
      * Footer layout mode:
      * - "auto" (default): Uses "form" for single-step top-level paths, "wizard" otherwise.
@@ -67,6 +71,8 @@
     cancelLabel = 'Cancel',
     hideCancel = false,
     hideProgress = false,
+    hideFooter = false,
+    validateWhen = false,
     footerLayout = 'auto',
     validationDisplay = 'summary',
     progressLayout = 'merged',
@@ -115,6 +121,18 @@
     }
   });
 
+  $effect(() => {
+    if (validateWhen) pathReturn.validate();
+  });
+
+  function warnMissingStep(stepId: string): void {
+    const camel = stepIdToCamelCase(stepId);
+    const hint = camel !== stepId
+      ? ` No snippet found for "${stepId}" or its camelCase form "${camel}". If your step ID contains hyphens, pass the snippet as a camelCase prop: ${camel}={YourComponent}.`
+      : ` No snippet found for "${stepId}".`;
+    console.warn(`[PathShell]${hint}`);
+  }
+
   let snap = $derived(pathReturn.snapshot);
   let actions = $derived({ next, previous, cancel, goToStep, goToStepChecked, setData, restart: () => restartFn(path, initialData), retry, suspend });
 
@@ -194,7 +212,10 @@
 
     <!-- Body: current step rendered via named snippet.
          Prefer formId (inner step id of a StepChoice) so consumers can
-         register snippets by inner step ids directly. -->
+         register snippets by inner step ids directly.
+         Hyphenated step IDs (e.g. "cover-letter") are normalised to camelCase
+         ("coverLetter") as a fallback, since Svelte props must be valid JS
+         identifiers. -->
     <div class="pw-shell__body">
       {#if snap.formId && stepSnippets[snap.formId]}
         {@const StepComponent = stepSnippets[snap.formId]}
@@ -202,13 +223,17 @@
       {:else if stepSnippets[snap.stepId]}
         {@const StepComponent = stepSnippets[snap.stepId]}
         <StepComponent />
+      {:else if stepSnippets[stepIdToCamelCase(snap.formId ?? snap.stepId)]}
+        {@const StepComponent = stepSnippets[stepIdToCamelCase(snap.formId ?? snap.stepId)]}
+        <StepComponent />
       {:else}
+        {warnMissingStep(snap.stepId)}
         <p>No content for step "{snap.stepId}"</p>
       {/if}
     </div>
 
     <!-- Validation messages — suppressed when validationDisplay="inline" -->
-    {#if validationDisplay !== 'inline' && snap.hasAttemptedNext && Object.keys(snap.fieldErrors).length > 0}
+    {#if validationDisplay !== 'inline' && (snap.hasAttemptedNext || snap.hasValidated) && Object.keys(snap.fieldErrors).length > 0}
       <ul class="pw-shell__validation">
         {#each Object.entries(snap.fieldErrors) as [key, msg]}
           <li class="pw-shell__validation-item">
@@ -230,7 +255,7 @@
     {/if}
 
     <!-- Blocking error — guard returned { allowed: false, reason } -->
-    {#if validationDisplay !== 'inline' && snap.hasAttemptedNext && snap.blockingError}
+    {#if validationDisplay !== 'inline' && (snap.hasAttemptedNext || snap.hasValidated) && snap.blockingError}
       <p class="pw-shell__blocking-error">{snap.blockingError}</p>
     {/if}
 
@@ -258,9 +283,9 @@
         </div>
       </div>
     <!-- Footer: navigation buttons (overridable via footer snippet) -->
-    {:else if footer}
+    {:else if !hideFooter && footer}
       {@render footer(snap, actions)}
-    {:else}
+    {:else if !hideFooter}
       <div class="pw-shell__footer">
         <div class="pw-shell__footer-left">
           {#if resolvedFooterLayout === 'form' && !hideCancel}

package/dist/PathShell.svelte.d.ts

@@ -12,6 +12,10 @@ interface Props {
     cancelLabel?: string;
     hideCancel?: boolean;
     hideProgress?: boolean;
+    /** If true, hide the footer (navigation buttons). The error panel is still shown on async failure regardless of this prop. */
+    hideFooter?: boolean;
+    /** When true, calls `validate()` on the engine so all steps show inline errors simultaneously. Useful when this shell is nested inside a step of an outer shell: bind to the outer snapshot's `hasAttemptedNext`. */
+    validateWhen?: boolean;
     /**
      * Footer layout mode:
      * - "auto" (default): Uses "form" for single-step top-level paths, "wizard" otherwise.

package/dist/PathShell.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PathShell.svelte.d.ts","sourceRoot":"","sources":["../src/PathShell.svelte.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAC5G,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAI/C,UAAU,KAAK;IACb,IAAI,CAAC,EAAE,cAAc,CAAC,GAAG,CAAC,CAAC;IAC3B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,WAAW,CAAC,EAAE,QAAQ,CAAC;IACvB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;IAC1C;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;IAClD;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAC;IACtC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAC;IACpC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;IAE/B,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACtC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IAE9C,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;CACrC;AAmPH,QAAA,MAAM,SAAS;mBA5JQ,QAAQ,IAAI,CAAC;MA4JmB,CAAC;AACxD,KAAK,SAAS,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;AAC9C,eAAe,SAAS,CAAC"}
+{"version":3,"file":"PathShell.svelte.d.ts","sourceRoot":"","sources":["../src/PathShell.svelte.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAC5G,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAI/C,UAAU,KAAK;IACb,IAAI,CAAC,EAAE,cAAc,CAAC,GAAG,CAAC,CAAC;IAC3B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,WAAW,CAAC,EAAE,QAAQ,CAAC;IACvB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,8HAA8H;IAC9H,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,qNAAqN;IACrN,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;IAC1C;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;IAClD;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAC;IACtC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAC;IACpC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;IAE/B,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACtC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IAE9C,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;CACrC;AAqQH,QAAA,MAAM,SAAS;mBAhKQ,QAAQ,IAAI,CAAC;MAgKmB,CAAC;AACxD,KAAK,SAAS,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;AAC9C,eAAe,SAAS,CAAC"}

package/dist/index.svelte.d.ts

@@ -52,6 +52,8 @@ export interface UsePathReturn<TData extends PathData = PathData> {
     retry: () => Promise<void>;
     /** Pauses the path with intent to return. Emits `suspended`. All state is preserved. */
     suspend: () => Promise<void>;
+    /** Trigger inline validation on all steps without navigating. Sets `snapshot.hasValidated`. */
+    validate: () => void;
 }
 /**
  * Create a Pathwrite engine with Svelte 5 runes-based reactivity.
@@ -178,5 +180,12 @@ export declare function bindData<TData extends PathData, K extends string & keyo
     readonly value: TData[K];
     set: (value: TData[K]) => void;
 };
+/**
+ * Converts a hyphenated step ID to camelCase.
+ * Used internally by PathShell to resolve step snippets when a step ID contains
+ * hyphens (e.g. "cover-letter" → "coverLetter"), since Svelte prop names must
+ * be valid JavaScript identifiers.
+ */
+export declare function stepIdToCamelCase(id: string): string;
 export { default as PathShell } from "./PathShell.svelte";
 //# sourceMappingURL=index.svelte.d.ts.map

package/dist/index.svelte.d.ts.map

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

package/dist/index.svelte.js

@@ -87,6 +87,7 @@ export function usePath(options) {
     const restart = () => engine.restart();
     const retry = () => engine.retry();
     const suspend = () => engine.suspend();
+    const validate = () => engine.validate();
     return {
         get snapshot() { return _snapshot; },
         start,
@@ -100,7 +101,8 @@ export function usePath(options) {
         resetStep,
         restart,
         retry,
-        suspend
+        suspend,
+        validate
     };
 }
 // ---------------------------------------------------------------------------
@@ -175,5 +177,14 @@ export function bindData(getSnapshot, setData, key) {
         }
     };
 }
+/**
+ * Converts a hyphenated step ID to camelCase.
+ * Used internally by PathShell to resolve step snippets when a step ID contains
+ * hyphens (e.g. "cover-letter" → "coverLetter"), since Svelte prop names must
+ * be valid JavaScript identifiers.
+ */
+export function stepIdToCamelCase(id) {
+    return id.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
 // Export PathShell component
 export { default as PathShell } from "./PathShell.svelte";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daltonr/pathwrite-svelte",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
   "license": "MIT",
   "description": "Svelte 5 adapter for @daltonr/pathwrite-core — runes-based reactive bindings and optional PathShell component.",
@@ -52,7 +52,7 @@
     "svelte": ">=5.0.0"
   },
   "dependencies": {
-    "@daltonr/pathwrite-core": "^0.10.0"
+    "@daltonr/pathwrite-core": "^0.11.0"
   },
   "devDependencies": {
     "@sveltejs/package": "^2.5.7",

package/src/PathShell.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
   import { onMount } from 'svelte';
-  import { usePath, setPathContext, formatFieldKey, errorPhaseMessage } from './index.svelte.js';
+  import { usePath, setPathContext, formatFieldKey, errorPhaseMessage, stepIdToCamelCase } from './index.svelte.js';
   import type { PathDefinition, PathData, PathEngine, PathSnapshot, ProgressLayout } from './index.svelte.js';
   import type { Snippet, Component } from 'svelte';
 
@@ -17,6 +17,10 @@
     cancelLabel?: string;
     hideCancel?: boolean;
     hideProgress?: boolean;
+    /** If true, hide the footer (navigation buttons). The error panel is still shown on async failure regardless of this prop. */
+    hideFooter?: boolean;
+    /** When true, calls `validate()` on the engine so all steps show inline errors simultaneously. Useful when this shell is nested inside a step of an outer shell: bind to the outer snapshot's `hasAttemptedNext`. */
+    validateWhen?: boolean;
     /**
      * Footer layout mode:
      * - "auto" (default): Uses "form" for single-step top-level paths, "wizard" otherwise.
@@ -67,6 +71,8 @@
     cancelLabel = 'Cancel',
     hideCancel = false,
     hideProgress = false,
+    hideFooter = false,
+    validateWhen = false,
     footerLayout = 'auto',
     validationDisplay = 'summary',
     progressLayout = 'merged',
@@ -115,6 +121,18 @@
     }
   });
 
+  $effect(() => {
+    if (validateWhen) pathReturn.validate();
+  });
+
+  function warnMissingStep(stepId: string): void {
+    const camel = stepIdToCamelCase(stepId);
+    const hint = camel !== stepId
+      ? ` No snippet found for "${stepId}" or its camelCase form "${camel}". If your step ID contains hyphens, pass the snippet as a camelCase prop: ${camel}={YourComponent}.`
+      : ` No snippet found for "${stepId}".`;
+    console.warn(`[PathShell]${hint}`);
+  }
+
   let snap = $derived(pathReturn.snapshot);
   let actions = $derived({ next, previous, cancel, goToStep, goToStepChecked, setData, restart: () => restartFn(path, initialData), retry, suspend });
 
@@ -194,7 +212,10 @@
 
     <!-- Body: current step rendered via named snippet.
          Prefer formId (inner step id of a StepChoice) so consumers can
-         register snippets by inner step ids directly. -->
+         register snippets by inner step ids directly.
+         Hyphenated step IDs (e.g. "cover-letter") are normalised to camelCase
+         ("coverLetter") as a fallback, since Svelte props must be valid JS
+         identifiers. -->
     <div class="pw-shell__body">
       {#if snap.formId && stepSnippets[snap.formId]}
         {@const StepComponent = stepSnippets[snap.formId]}
@@ -202,13 +223,17 @@
       {:else if stepSnippets[snap.stepId]}
         {@const StepComponent = stepSnippets[snap.stepId]}
         <StepComponent />
+      {:else if stepSnippets[stepIdToCamelCase(snap.formId ?? snap.stepId)]}
+        {@const StepComponent = stepSnippets[stepIdToCamelCase(snap.formId ?? snap.stepId)]}
+        <StepComponent />
       {:else}
+        {warnMissingStep(snap.stepId)}
         <p>No content for step "{snap.stepId}"</p>
       {/if}
     </div>
 
     <!-- Validation messages — suppressed when validationDisplay="inline" -->
-    {#if validationDisplay !== 'inline' && snap.hasAttemptedNext && Object.keys(snap.fieldErrors).length > 0}
+    {#if validationDisplay !== 'inline' && (snap.hasAttemptedNext || snap.hasValidated) && Object.keys(snap.fieldErrors).length > 0}
       <ul class="pw-shell__validation">
         {#each Object.entries(snap.fieldErrors) as [key, msg]}
           <li class="pw-shell__validation-item">
@@ -230,7 +255,7 @@
     {/if}
 
     <!-- Blocking error — guard returned { allowed: false, reason } -->
-    {#if validationDisplay !== 'inline' && snap.hasAttemptedNext && snap.blockingError}
+    {#if validationDisplay !== 'inline' && (snap.hasAttemptedNext || snap.hasValidated) && snap.blockingError}
       <p class="pw-shell__blocking-error">{snap.blockingError}</p>
     {/if}
 
@@ -258,9 +283,9 @@
         </div>
       </div>
     <!-- Footer: navigation buttons (overridable via footer snippet) -->
-    {:else if footer}
+    {:else if !hideFooter && footer}
       {@render footer(snap, actions)}
-    {:else}
+    {:else if !hideFooter}
       <div class="pw-shell__footer">
         <div class="pw-shell__footer-left">
           {#if resolvedFooterLayout === 'form' && !hideCancel}

package/src/index.svelte.ts

@@ -80,6 +80,8 @@ export interface UsePathReturn<TData extends PathData = PathData> {
   retry: () => Promise<void>;
   /** Pauses the path with intent to return. Emits `suspended`. All state is preserved. */
   suspend: () => Promise<void>;
+  /** Trigger inline validation on all steps without navigating. Sets `snapshot.hasValidated`. */
+  validate: () => void;
 }
 
 // ---------------------------------------------------------------------------
@@ -188,6 +190,8 @@ export function usePath<TData extends PathData = PathData>(
   const retry = (): Promise<void> => engine.retry();
   const suspend = (): Promise<void> => engine.suspend();
 
+  const validate = (): void => engine.validate();
+
   return {
     get snapshot() { return _snapshot; },
     start,
@@ -201,7 +205,8 @@ export function usePath<TData extends PathData = PathData>(
     resetStep,
     restart,
     retry,
-    suspend
+    suspend,
+    validate
   };
 }
 
@@ -310,6 +315,16 @@ export function bindData<TData extends PathData, K extends string & keyof TData>
   };
 }
 
+/**
+ * Converts a hyphenated step ID to camelCase.
+ * Used internally by PathShell to resolve step snippets when a step ID contains
+ * hyphens (e.g. "cover-letter" → "coverLetter"), since Svelte prop names must
+ * be valid JavaScript identifiers.
+ */
+export function stepIdToCamelCase(id: string): string {
+  return id.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
 // Export PathShell component
 export { default as PathShell } from "./PathShell.svelte";