@fias/arche-sdk 1.6.0 → 1.8.0

package/dist/index.mjs

@@ -353,6 +353,36 @@ function useBridge() {
   }
   return bridge;
 }
+var PERSIST_DEBOUNCE_WAIT_MS = 250;
+var PERSIST_DEBOUNCE_MAX_WAIT_MS = 1e3;
+function createDebouncedWriter(bridge) {
+  let pending = null;
+  function flush() {
+    if (!pending) return;
+    const { path, content, timerId } = pending;
+    if (timerId !== null) clearTimeout(timerId);
+    pending = null;
+    bridge.request("storage_write", { path, content }).catch(() => {
+    });
+  }
+  function schedule(path, content) {
+    const now = Date.now();
+    if (pending && pending.path !== path) {
+      flush();
+    }
+    if (!pending) {
+      pending = { path, content, timerId: null, firstScheduledAt: now };
+    } else {
+      pending.content = content;
+    }
+    if (pending.timerId !== null) clearTimeout(pending.timerId);
+    const elapsed = now - pending.firstScheduledAt;
+    const remainingMax = Math.max(0, PERSIST_DEBOUNCE_MAX_WAIT_MS - elapsed);
+    const delay = Math.min(PERSIST_DEBOUNCE_WAIT_MS, remainingMax);
+    pending.timerId = setTimeout(flush, delay);
+  }
+  return { schedule, flush };
+}
 function useFiasUser() {
   const bridge = useBridge();
   const [user, setUser] = useState2(null);
@@ -482,41 +512,87 @@ function usePersistentState(key, initialValue) {
   const bridge = useBridge();
   const [value, setValueInternal] = useState2(initialValue);
   const initializedRef = useRef(false);
+  const valueRef = useRef(initialValue);
+  const writer = useMemo2(() => createDebouncedWriter(bridge), [bridge]);
   useEffect2(() => {
     bridge.request("storage_read", { path: `__state/${key}` }).then((result) => {
       if (result.exists && result.content !== null) {
         try {
-          setValueInternal(JSON.parse(result.content));
+          const parsed = JSON.parse(result.content);
+          valueRef.current = parsed;
+          setValueInternal(parsed);
         } catch {
         }
       }
       initializedRef.current = true;
     });
-  }, [bridge, key]);
+    return () => {
+      writer.flush();
+    };
+  }, [bridge, key, writer]);
   const setValue = useCallback(
     (next) => {
-      setValueInternal((prev) => {
-        const resolved = typeof next === "function" ? next(prev) : next;
-        bridge.request("storage_write", {
-          path: `__state/${key}`,
-          content: JSON.stringify(resolved)
-        }).catch(() => {
-        });
-        return resolved;
-      });
+      const resolved = typeof next === "function" ? next(valueRef.current) : next;
+      valueRef.current = resolved;
+      setValueInternal(resolved);
+      writer.schedule(`__state/${key}`, JSON.stringify(resolved));
     },
-    [bridge, key]
+    [key, writer]
   );
   return [value, setValue];
 }
-function useStepNavigation(initialStep) {
+function useStepNavigation(initialStep, options) {
   const bridge = useBridge();
-  const [currentStep, setCurrentStep] = useState2(initialStep ?? null);
+  const persistKey = options?.persistKey;
+  const [currentStep, setCurrentStepInternal] = useState2(initialStep ?? null);
+  const initializedRef = useRef(false);
+  const writer = useMemo2(() => createDebouncedWriter(bridge), [bridge]);
+  useEffect2(() => {
+    if (!persistKey) {
+      initializedRef.current = true;
+      return;
+    }
+    let cancelled = false;
+    bridge.request("storage_read", {
+      path: `__state/${persistKey}`
+    }).then((result) => {
+      if (cancelled || initializedRef.current) return;
+      if (result.exists && result.content !== null) {
+        try {
+          const parsed = JSON.parse(result.content);
+          if (typeof parsed === "string" || parsed === null) {
+            setCurrentStepInternal(parsed);
+          }
+        } catch {
+        }
+      }
+      initializedRef.current = true;
+    }).catch(() => {
+      initializedRef.current = true;
+    });
+    return () => {
+      cancelled = true;
+      writer.flush();
+    };
+  }, [bridge, persistKey, writer]);
   useEffect2(() => {
     return bridge.onStepNavigationUpdate((nodeId) => {
-      setCurrentStep(nodeId);
+      setCurrentStepInternal(nodeId);
+      if (persistKey) {
+        writer.schedule(`__state/${persistKey}`, JSON.stringify(nodeId));
+      }
     });
-  }, [bridge]);
+  }, [bridge, persistKey, writer]);
+  const setCurrentStep = useCallback(
+    (nodeId) => {
+      initializedRef.current = true;
+      setCurrentStepInternal(nodeId);
+      if (persistKey) {
+        writer.schedule(`__state/${persistKey}`, JSON.stringify(nodeId));
+      }
+    },
+    [persistKey, writer]
+  );
   return { currentStep, setCurrentStep };
 }
 function useFiasDataStore() {

package/dist/types.d.ts

@@ -81,7 +81,11 @@ export interface EntityInvocationApi {
     isLoading: boolean;
     result: EntityInvocationResult | null;
     error: Error | null;
-    /** Partial text received so far during a streaming invocation. */
+    /**
+     * Tokens accumulated during a streaming invocation. Persists after the
+     * call completes (not reset to ''), so render either `streamingText` OR
+     * `result.output` — never both, or you'll show the response twice.
+     */
     streamingText: string;
 }
 export interface EntityInvocationParams {
@@ -152,6 +156,21 @@ export interface StepNavigationApi {
     currentStep: string | null;
     setCurrentStep: (step: string | null) => void;
 }
+/**
+ * Options for useStepNavigation().
+ */
+export interface StepNavigationOptions {
+    /**
+     * When set, persists currentStep to bridge storage under `__state/<persistKey>`.
+     * The persisted value is read on mount (overriding initialStep if present) and
+     * written on every setCurrentStep call and incoming host step_navigate message.
+     *
+     * Use this instead of wrapping currentStep in usePersistentState separately —
+     * two independent step-state sources cause a bidirectional useEffect sync loop
+     * that spams storage and flashes the UI.
+     */
+    persistKey?: string;
+}
 /**
  * Message types sent from the parent frame to the plugin iframe.
  */

package/dist/types.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fias/arche-sdk",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "SDK for building FIAS platform plugin arches",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/templates/default/AGENTS.md

@@ -2,7 +2,7 @@
 
 This project is a FIAS platform plugin — a React application that runs in a sandboxed iframe within the FIAS marketplace. This file provides the context AI coding assistants need to build, test, and submit plugins effectively.
 
-For other AI tool instruction files, see `AGENTS.md` (identical content).
+For other AI tool instruction files, see `CLAUDE.md` (identical content).
 
 ## Project Structure
 
@@ -183,13 +183,17 @@ function AISummarizer() {
     });
   }
 
+  // streamingText holds the accumulated tokens during the call AND continues to
+  // hold the full text after the call completes — it is NOT cleared. result.output
+  // also contains the full text once invoke() resolves. Render ONE slot only —
+  // streamingText while loading, result.output afterwards. Showing both renders
+  // the response twice.
   return (
     <div>
       <button onClick={() => summarize('...')} disabled={isLoading}>
         Summarize
       </button>
-      {isLoading && <p>{streamingText}</p>}
-      {result && <p>{result.output}</p>}
+      <p>{isLoading ? streamingText : result?.output}</p>
       {error && <p>Error: {error.message}</p>}
     </div>
   );
@@ -249,12 +253,22 @@ navigateTo('/settings');
 
 **Returns:** `StepNavigationApi`
 
+Call **once** in the top-level App component. Share `currentStep` and `setCurrentStep` with step components via React context — do not call `useStepNavigation` from step components (each call creates an independent state).
+
 ```tsx
 import { useStepNavigation } from '@fias/arche-sdk';
 
+// Without persistence — currentStep resets on preview rebuild
 const { currentStep, setCurrentStep } = useStepNavigation('step-1');
+
+// With persistence — currentStep survives preview rebuilds (SDK ≥ 1.7.0)
+const { currentStep, setCurrentStep } = useStepNavigation('step-1', {
+  persistKey: 'currentStep',
+});
 ```
 
+**Do NOT wrap `currentStep` in `usePersistentState`.** Two independent step-state sources create a bidirectional `useEffect` sync loop that spams `storage_write` and flashes the UI between steps. `persistKey` is the only correct way to persist the current step.
+
 ### `usePersistentState()` — Auto-saving state
 
 **Permission:** `storage:sandbox`
@@ -268,6 +282,12 @@ const [count, setCount] = usePersistentState<number>('counter', 0);
 // Automatically persists to storage on change
 ```
 
+Use for domain data (form inputs, selections, AI results). **Do not use for `currentStep`** — use `useStepNavigation({ persistKey })` instead.
+
+**Writes are debounced (SDK ≥ 1.8.0).** The in-memory value updates synchronously on every setter call, but the underlying `storage_write` is coalesced with a 250 ms trailing-edge debounce and a 1 s max-wait, and flushed on unmount. This makes the hook safe to call from `requestAnimationFrame`, `mousemove`, and other high-frequency handlers — bursts no longer trip the `storage_write` rate limit.
+
+Trade-off: reading the same key via `useFiasStorage().readFile('__state/foo')` immediately after a `setValue` can see a stale value for up to ~250 ms. Read through the hook instead of bypassing it.
+
 ### `fias` — Imperative utilities
 
 ```tsx
@@ -338,6 +358,8 @@ These are hard limits enforced by the platform. Code that violates these will fa
 - `storage_read`: 300/minute
 - `storage_list`, `storage_delete`: 60/minute
 
+A separate **runaway-loop detector** also fires if any method is called >50 times in 5 s and blocks that method for 10 s. Errors include the target for diagnostics, e.g. `Runaway loop detected: "storage_write" (path: __state/gameState) called 51 times in 5s.` — if you see this, look at the identified path and debounce the updates at the source.
+
 ### Security Rules (enforced during review)
 
 - No `eval()`, `Function()`, `innerHTML`, or dynamic code execution
@@ -418,6 +440,84 @@ npm run submit
 # First listing: 5000 credits ($50). Re-submissions: 100 credits ($1).
 ```
 
+## Common Pitfalls
+
+These are real bugs that have shipped from AI-generated plugins. Avoid them.
+
+### Don't navigate from a `useEffect` that watches derived state
+
+If a step component derives a value from context state and uses `useEffect` to redirect when that derived value is missing, the redirect can fire mid-update and yank the user away from a working screen. Common shape:
+
+```tsx
+// ❌ BUG: redirects whenever conversations changes between renders
+const currentConversation = conversations.find((c) => c.id === currentConversationId);
+
+useEffect(() => {
+  if (!currentConversation) {
+    setCurrentStep('list');
+  }
+}, [currentConversation, setCurrentStep]); // fires on every conversations change
+```
+
+`currentConversation` is a _derived_ value — its reference changes every time `conversations` changes. The effect re-runs and may redirect during a state transition (e.g., right after the user sends a message and the component is mid-update). The user reports "I sent a message and got bounced back" or "the response never showed up".
+
+```tsx
+// ✅ FIX: gate on the *id* (which is durable) and render a loading state when
+// the conversation can't be found yet — let the user navigate back manually
+// instead of forcing it.
+useEffect(() => {
+  if (!currentConversationId) setCurrentStep('list');
+}, [currentConversationId, setCurrentStep]);
+
+if (!currentConversation) return <div>Loading conversation…</div>;
+```
+
+### Use functional updaters when an `await` sits between reads and writes
+
+When you read state, `await` something, then write back, the closure captures the _stale_ state. Use the functional form so the setter receives the latest value at the time of the update:
+
+```tsx
+// ❌ BUG: `messages` here is the snapshot from before await
+const messages = currentConversation.messages;
+const response = await invoke({ entityId, input });
+setConversations(
+  conversations.map((c) => (c.id === id ? { ...c, messages: [...messages, response] } : c)),
+);
+
+// ✅ FIX: functional updater reads fresh state at update time
+await invoke({ entityId, input });
+setConversations((prev) =>
+  prev.map((c) => (c.id === id ? { ...c, messages: [...c.messages, response] } : c)),
+);
+```
+
+This matters most for `usePersistentState` on lists: the user can fire many updates quickly, and lost-update bugs are common with snapshot-style updates.
+
+### Render `streamingText` OR `result.output` — never both
+
+Already covered in the `useEntityInvocation` section above, but worth repeating: `streamingText` is _not_ cleared after the call completes — it keeps holding the full final text. Showing `{streamingText && ...}` AND `{result && ...}` in separate JSX nodes prints the response twice as soon as `result` arrives. Use one slot: `{isLoading ? streamingText : result?.output}`.
+
+### Verify visually when the user reports a UI bug
+
+If a user says "I don't see the response" or "the layout's broken", don't rely solely on `console.log` and `useFiasStorage` reads. Inspect the actual rendered output. The platform exposes `get_preview_screenshot` to AI builders for exactly this reason.
+
+### Don't persist per-frame state
+
+For state that updates every frame (game position, drag coordinates, animated values), use plain `useState` — not `usePersistentState`. Persisting every ball-position tick writes unbounded data to durable storage and doesn't survive reloads in any useful way anyway (the ball will be somewhere different when the player resumes).
+
+Hook-level debouncing (SDK ≥ 1.8.0) makes `usePersistentState` safe under bursts, but you still shouldn't persist what you'll discard on reload. Keep ephemeral state in `useState` and persist only meaningful checkpoints (final score, selected difficulty, high-score list).
+
+```tsx
+// ❌ Persisting ball position every frame — meaningless on reload
+const [gameState, setGameState] = usePersistentState<GameState>('gameState', initial);
+requestAnimationFrame(() => setGameState(advance(gameState)));
+
+// ✅ Ephemeral for live gameplay, persisted for results
+const [gameState, setGameState] = useState<GameState>(initial);
+const [highScores, setHighScores] = usePersistentState<Score[]>('highScores', []);
+// persist highScores only when a run completes
+```
+
 ## Common Patterns
 
 ### Theme-Aware Card Component

package/templates/default/CLAUDE.md

@@ -183,13 +183,17 @@ function AISummarizer() {
     });
   }
 
+  // streamingText holds the accumulated tokens during the call AND continues to
+  // hold the full text after the call completes — it is NOT cleared. result.output
+  // also contains the full text once invoke() resolves. Render ONE slot only —
+  // streamingText while loading, result.output afterwards. Showing both renders
+  // the response twice.
   return (
     <div>
       <button onClick={() => summarize('...')} disabled={isLoading}>
         Summarize
       </button>
-      {isLoading && <p>{streamingText}</p>}
-      {result && <p>{result.output}</p>}
+      <p>{isLoading ? streamingText : result?.output}</p>
       {error && <p>Error: {error.message}</p>}
     </div>
   );
@@ -249,12 +253,22 @@ navigateTo('/settings');
 
 **Returns:** `StepNavigationApi`
 
+Call **once** in the top-level App component. Share `currentStep` and `setCurrentStep` with step components via React context — do not call `useStepNavigation` from step components (each call creates an independent state).
+
 ```tsx
 import { useStepNavigation } from '@fias/arche-sdk';
 
+// Without persistence — currentStep resets on preview rebuild
 const { currentStep, setCurrentStep } = useStepNavigation('step-1');
+
+// With persistence — currentStep survives preview rebuilds (SDK ≥ 1.7.0)
+const { currentStep, setCurrentStep } = useStepNavigation('step-1', {
+  persistKey: 'currentStep',
+});
 ```
 
+**Do NOT wrap `currentStep` in `usePersistentState`.** Two independent step-state sources create a bidirectional `useEffect` sync loop that spams `storage_write` and flashes the UI between steps. `persistKey` is the only correct way to persist the current step.
+
 ### `usePersistentState()` — Auto-saving state
 
 **Permission:** `storage:sandbox`
@@ -268,6 +282,12 @@ const [count, setCount] = usePersistentState<number>('counter', 0);
 // Automatically persists to storage on change
 ```
 
+Use for domain data (form inputs, selections, AI results). **Do not use for `currentStep`** — use `useStepNavigation({ persistKey })` instead.
+
+**Writes are debounced (SDK ≥ 1.8.0).** The in-memory value updates synchronously on every setter call, but the underlying `storage_write` is coalesced with a 250 ms trailing-edge debounce and a 1 s max-wait, and flushed on unmount. This makes the hook safe to call from `requestAnimationFrame`, `mousemove`, and other high-frequency handlers — bursts no longer trip the `storage_write` rate limit.
+
+Trade-off: reading the same key via `useFiasStorage().readFile('__state/foo')` immediately after a `setValue` can see a stale value for up to ~250 ms. Read through the hook instead of bypassing it.
+
 ### `fias` — Imperative utilities
 
 ```tsx
@@ -338,6 +358,8 @@ These are hard limits enforced by the platform. Code that violates these will fa
 - `storage_read`: 300/minute
 - `storage_list`, `storage_delete`: 60/minute
 
+A separate **runaway-loop detector** also fires if any method is called >50 times in 5 s and blocks that method for 10 s. Errors include the target for diagnostics, e.g. `Runaway loop detected: "storage_write" (path: __state/gameState) called 51 times in 5s.` — if you see this, look at the identified path and debounce the updates at the source.
+
 ### Security Rules (enforced during review)
 
 - No `eval()`, `Function()`, `innerHTML`, or dynamic code execution
@@ -418,6 +440,84 @@ npm run submit
 # First listing: 5000 credits ($50). Re-submissions: 100 credits ($1).
 ```
 
+## Common Pitfalls
+
+These are real bugs that have shipped from AI-generated plugins. Avoid them.
+
+### Don't navigate from a `useEffect` that watches derived state
+
+If a step component derives a value from context state and uses `useEffect` to redirect when that derived value is missing, the redirect can fire mid-update and yank the user away from a working screen. Common shape:
+
+```tsx
+// ❌ BUG: redirects whenever conversations changes between renders
+const currentConversation = conversations.find((c) => c.id === currentConversationId);
+
+useEffect(() => {
+  if (!currentConversation) {
+    setCurrentStep('list');
+  }
+}, [currentConversation, setCurrentStep]); // fires on every conversations change
+```
+
+`currentConversation` is a _derived_ value — its reference changes every time `conversations` changes. The effect re-runs and may redirect during a state transition (e.g., right after the user sends a message and the component is mid-update). The user reports "I sent a message and got bounced back" or "the response never showed up".
+
+```tsx
+// ✅ FIX: gate on the *id* (which is durable) and render a loading state when
+// the conversation can't be found yet — let the user navigate back manually
+// instead of forcing it.
+useEffect(() => {
+  if (!currentConversationId) setCurrentStep('list');
+}, [currentConversationId, setCurrentStep]);
+
+if (!currentConversation) return <div>Loading conversation…</div>;
+```
+
+### Use functional updaters when an `await` sits between reads and writes
+
+When you read state, `await` something, then write back, the closure captures the _stale_ state. Use the functional form so the setter receives the latest value at the time of the update:
+
+```tsx
+// ❌ BUG: `messages` here is the snapshot from before await
+const messages = currentConversation.messages;
+const response = await invoke({ entityId, input });
+setConversations(
+  conversations.map((c) => (c.id === id ? { ...c, messages: [...messages, response] } : c)),
+);
+
+// ✅ FIX: functional updater reads fresh state at update time
+await invoke({ entityId, input });
+setConversations((prev) =>
+  prev.map((c) => (c.id === id ? { ...c, messages: [...c.messages, response] } : c)),
+);
+```
+
+This matters most for `usePersistentState` on lists: the user can fire many updates quickly, and lost-update bugs are common with snapshot-style updates.
+
+### Render `streamingText` OR `result.output` — never both
+
+Already covered in the `useEntityInvocation` section above, but worth repeating: `streamingText` is _not_ cleared after the call completes — it keeps holding the full final text. Showing `{streamingText && ...}` AND `{result && ...}` in separate JSX nodes prints the response twice as soon as `result` arrives. Use one slot: `{isLoading ? streamingText : result?.output}`.
+
+### Verify visually when the user reports a UI bug
+
+If a user says "I don't see the response" or "the layout's broken", don't rely solely on `console.log` and `useFiasStorage` reads. Inspect the actual rendered output. The platform exposes `get_preview_screenshot` to AI builders for exactly this reason.
+
+### Don't persist per-frame state
+
+For state that updates every frame (game position, drag coordinates, animated values), use plain `useState` — not `usePersistentState`. Persisting every ball-position tick writes unbounded data to durable storage and doesn't survive reloads in any useful way anyway (the ball will be somewhere different when the player resumes).
+
+Hook-level debouncing (SDK ≥ 1.8.0) makes `usePersistentState` safe under bursts, but you still shouldn't persist what you'll discard on reload. Keep ephemeral state in `useState` and persist only meaningful checkpoints (final score, selected difficulty, high-score list).
+
+```tsx
+// ❌ Persisting ball position every frame — meaningless on reload
+const [gameState, setGameState] = usePersistentState<GameState>('gameState', initial);
+requestAnimationFrame(() => setGameState(advance(gameState)));
+
+// ✅ Ephemeral for live gameplay, persisted for results
+const [gameState, setGameState] = useState<GameState>(initial);
+const [highScores, setHighScores] = usePersistentState<Score[]>('highScores', []);
+// persist highScores only when a run completes
+```
+
 ## Common Patterns
 
 ### Theme-Aware Card Component

package/templates/multi-step/README.md

@@ -0,0 +1,13 @@
+# Multi-Step FIAS Plugin Template
+
+Canonical pattern for multi-step plugins. The important bits live in:
+
+- `src/App.tsx` — calls `useStepNavigation('step-one', { persistKey: 'currentStep' })` **once**. Single source of truth for the current step.
+- `src/context/AppContext.tsx` — exposes `currentStep` and `setCurrentStep` to step components, plus any domain data via `usePersistentState`.
+- `src/steps/<step-id>/<StepName>.tsx` — step components read/write via context. They do not call `useStepNavigation` themselves.
+
+## Why not `usePersistentState('currentStep', ...)`?
+
+That used to look tempting, but it creates two independent step-state sources (one from `useStepNavigation`, one from `usePersistentState`). Any `useEffect` that syncs them turns into a bidirectional ping-pong loop that spams `storage_write` and flashes the UI between steps.
+
+Since SDK 1.7.0, `useStepNavigation` handles persistence directly via `{ persistKey }`. That is the only correct way to persist step state. Domain data (form inputs, AI-generated content, user selections) can still use `usePersistentState` — just not `currentStep`.

package/templates/multi-step/fias-plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "{{name}}",
+  "version": "1.0.0",
+  "description": "A multi-step FIAS plugin arche",
+  "main": "src/index.tsx",
+  "archeType": "tool",
+  "tags": [],
+  "pricing": { "model": "free", "currency": "usd" },
+  "permissions": ["theme:read", "storage:sandbox"],
+  "sdk": "^1.7.0"
+}

package/templates/multi-step/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>FIAS Plugin</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/index.tsx"></script>
+  </body>
+</html>

package/templates/multi-step/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "{{name}}",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "start": "vite & sleep 2 && fias-dev",
+    "dev": "vite",
+    "build": "vite build",
+    "validate": "tsc --noEmit",
+    "dev:harness": "fias-dev",
+    "submit": "fias-dev submit"
+  },
+  "dependencies": {
+    "@fias/arche-sdk": "^1.7.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@fias/plugin-dev-harness": "^1.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.0.0",
+    "typescript": "^5.3.3",
+    "vite": "^6.0.0"
+  }
+}

package/templates/multi-step/src/App.tsx

@@ -0,0 +1,38 @@
+import { useFiasTheme, useStepNavigation } from '@fias/arche-sdk';
+import { AppProvider } from './context/AppContext';
+import { StepOne } from './steps/step-one/StepOne';
+import { StepTwo } from './steps/step-two/StepTwo';
+
+function AppContent() {
+  const theme = useFiasTheme();
+
+  // Single source of truth for step navigation.
+  // persistKey makes currentStep survive preview rebuilds via bridge storage.
+  // Do NOT also wrap currentStep in usePersistentState — two sources create
+  // a bidirectional useEffect sync loop that spams storage and flashes the UI.
+  const { currentStep, setCurrentStep } = useStepNavigation('step-one', {
+    persistKey: 'currentStep',
+  });
+
+  if (!theme) return null;
+
+  return (
+    <AppProvider currentStep={currentStep} setCurrentStep={setCurrentStep}>
+      <div
+        style={{
+          minHeight: '100vh',
+          backgroundColor: theme.colors.background,
+          color: theme.colors.text,
+          fontFamily: theme.fonts.body,
+          padding: theme.spacing.lg,
+        }}
+      >
+        {currentStep === 'step-two' ? <StepTwo /> : <StepOne />}
+      </div>
+    </AppProvider>
+  );
+}
+
+export function App() {
+  return <AppContent />;
+}