@fias/arche-sdk 1.6.1 → 1.8.0

package/templates/default/CLAUDE.md

@@ -2,6 +2,8 @@
 
 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).
+
 ## Project Structure
 
 ```
@@ -181,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>
   );
@@ -247,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`
@@ -266,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
@@ -336,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
@@ -416,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
@@ -491,7 +593,3 @@ function Settings() {
   );
 }
 ```
-
-## See also
-
-`AGENTS.md` — equivalent guide for non-Claude AI tools in this project.

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 />;
+}

package/templates/multi-step/src/context/AppContext.tsx

@@ -0,0 +1,36 @@
+import { createContext, useContext, ReactNode } from 'react';
+import { usePersistentState } from '@fias/arche-sdk';
+
+interface AppContextValue {
+  currentStep: string | null;
+  setCurrentStep: (step: string | null) => void;
+  // Domain data — safe to persist with usePersistentState.
+  notes: string;
+  setNotes: (value: string) => void;
+}
+
+const AppContext = createContext<AppContextValue | null>(null);
+
+interface AppProviderProps {
+  children: ReactNode;
+  currentStep: string | null;
+  setCurrentStep: (step: string | null) => void;
+}
+
+export function AppProvider({ children, currentStep, setCurrentStep }: AppProviderProps) {
+  // Step navigation comes in from useStepNavigation (in App.tsx) — the single
+  // source of truth. Only domain data lives in usePersistentState here.
+  const [notes, setNotes] = usePersistentState<string>('notes', '');
+
+  return (
+    <AppContext.Provider value={{ currentStep, setCurrentStep, notes, setNotes }}>
+      {children}
+    </AppContext.Provider>
+  );
+}
+
+export function useAppContext(): AppContextValue {
+  const ctx = useContext(AppContext);
+  if (!ctx) throw new Error('useAppContext must be used within AppProvider');
+  return ctx;
+}

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

@@ -0,0 +1,12 @@
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { FiasProvider } from '@fias/arche-sdk';
+import { App } from './App';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <FiasProvider>
+      <App />
+    </FiasProvider>
+  </React.StrictMode>,
+);

package/templates/multi-step/src/steps/step-one/StepOne.tsx

@@ -0,0 +1,43 @@
+import { useFiasTheme } from '@fias/arche-sdk';
+import { useAppContext } from '../../context/AppContext';
+
+export function StepOne() {
+  const theme = useFiasTheme();
+  const { notes, setNotes, setCurrentStep } = useAppContext();
+
+  if (!theme) return null;
+
+  return (
+    <div>
+      <h1 style={{ fontFamily: theme.fonts.heading }}>Step 1 — Notes</h1>
+      <textarea
+        value={notes}
+        onChange={(e) => setNotes(e.target.value)}
+        rows={6}
+        style={{
+          width: '100%',
+          padding: theme.spacing.sm,
+          backgroundColor: theme.colors.surface,
+          color: theme.colors.text,
+          border: `${theme.components.borderWidth} solid ${theme.colors.border}`,
+          borderRadius: theme.components.inputRadius,
+        }}
+      />
+      <button
+        onClick={() => setCurrentStep('step-two')}
+        disabled={notes.trim().length === 0}
+        style={{
+          marginTop: theme.spacing.md,
+          padding: `${theme.spacing.sm} ${theme.spacing.lg}`,
+          backgroundColor: theme.colors.primary,
+          color: theme.colors.primaryText,
+          border: 'none',
+          borderRadius: theme.components.buttonRadius,
+          cursor: notes.trim().length === 0 ? 'not-allowed' : 'pointer',
+        }}
+      >
+        Next
+      </button>
+    </div>
+  );
+}

package/templates/multi-step/src/steps/step-two/StepTwo.tsx

@@ -0,0 +1,40 @@
+import { useFiasTheme } from '@fias/arche-sdk';
+import { useAppContext } from '../../context/AppContext';
+
+export function StepTwo() {
+  const theme = useFiasTheme();
+  const { notes, setCurrentStep } = useAppContext();
+
+  if (!theme) return null;
+
+  return (
+    <div>
+      <h1 style={{ fontFamily: theme.fonts.heading }}>Step 2 — Review</h1>
+      <pre
+        style={{
+          padding: theme.spacing.md,
+          backgroundColor: theme.colors.surface,
+          color: theme.colors.text,
+          borderRadius: theme.components.cardRadius,
+          whiteSpace: 'pre-wrap',
+        }}
+      >
+        {notes}
+      </pre>
+      <button
+        onClick={() => setCurrentStep('step-one')}
+        style={{
+          marginTop: theme.spacing.md,
+          padding: `${theme.spacing.sm} ${theme.spacing.lg}`,
+          backgroundColor: theme.colors.surface,
+          color: theme.colors.text,
+          border: `${theme.components.borderWidth} solid ${theme.colors.border}`,
+          borderRadius: theme.components.buttonRadius,
+          cursor: 'pointer',
+        }}
+      >
+        Back
+      </button>
+    </div>
+  );
+}

package/templates/multi-step/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true
+  },
+  "include": ["src"]
+}

package/templates/multi-step/vite.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  build: {
+    outDir: 'dist',
+    rollupOptions: {
+      input: 'index.html',
+    },
+  },
+  server: {
+    port: 3100,
+    cors: true,
+    headers: { 'Access-Control-Allow-Origin': '*' },
+    hmr: { host: 'localhost' },
+  },
+});