@fias/arche-sdk 1.11.0 → 1.13.0

package/templates/default/CLAUDE.md

@@ -207,7 +207,43 @@ The `entityId` references a published model entity. Browse available models with
 **Permission:** `entities:image_generate`
 **Returns:** `ImageGenerationApi`
 
-Generate images using platform image models. Images are saved to the user's Fias file system and a display URL is returned. Use `npx fias-dev entities --detail <entityId>` to check supported sizes, qualities, and styles for each model.
+Generate images using platform image models. Images are saved to the user's Fias file system and a display URL is returned.
+
+#### Choosing an image model
+
+The `entityId` parameter accepts three forms. **Prefer the selector forms** (`platformRecommended` / `providerRecommended`) over hardcoded entity IDs: the platform's recommendations evolve, models get retired, and a selector lets your plugin pick up the current best automatically without a code edit. Hardcoded IDs are still supported for back-compat and for cases where you want a specific model — but if the platform retires that exact entity, your plugin breaks unless the platform has registered a successor.
+
+```tsx
+// 1. Platform's blessed pick for a workflow + optional style (RECOMMENDED).
+//    Asking for `image-to-image` will never return a model that can't do it.
+generate({
+  entityId: { platformRecommended: { mode: 'text-to-image', style: 'illustration' } },
+  prompt: "A child's storybook page of a fox in the forest",
+});
+
+// 2. A specific provider's blessed pick. Use when your plugin's value prop
+//    depends on a particular provider's quirks (e.g., "best OpenAI image model").
+generate({
+  entityId: { providerRecommended: { provider: 'openai', mode: 'image-to-image' } },
+  prompt: 'Make it look like an oil painting',
+  referenceImage: { fileId: previousImage.fileId },
+});
+
+// 3. Explicit entityId — back-compat path. Use only when you want a
+//    specific model. If the entity has been deprecated, the response
+//    includes `deprecation: { requestedEntityId, resolvedEntityId,
+//    deprecatedAt }` and you get the successor.
+generate({
+  entityId: 'ent_modeldef_gpt_image_1_5',
+  prompt: 'A serene mountain landscape at sunset',
+});
+```
+
+Mode values: `'text-to-image'` (the baseline), `'image-to-image'` (requires `referenceImage`), `'vector'` (SVG output). Style values: `'illustration'` (stylized/kids/digital-art) or `'photoreal'`.
+
+Use `npx fias-dev entities --detail <entityId>` to check supported sizes, qualities, and styles for each model.
+
+#### Full example
 
 ```tsx
 import { useImageGeneration } from '@fias/arche-sdk';
@@ -220,9 +256,9 @@ function ImageMaker() {
       <button
         onClick={() =>
           generate({
-            entityId: 'ent_modeldef_gpt_image_1_5',
+            entityId: { platformRecommended: { mode: 'text-to-image' } },
             prompt: 'A serene mountain landscape at sunset',
-            size: '1024x1024',
+            size: '16:9',
             quality: 'high',
           })
         }
@@ -230,13 +266,58 @@ function ImageMaker() {
       >
         {isLoading ? 'Generating...' : 'Generate Image'}
       </button>
-      {result && <img src={result.imageUrl} alt="Generated" />}
+      {result && (
+        <>
+          <img src={result.imageUrl} alt="Generated" />
+          {result.deprecation && (
+            <p style={{ color: 'orange' }}>
+              Note: requested entity "{result.deprecation.requestedEntityId}" is deprecated;
+              auto-substituted "{result.deprecation.resolvedEntityId}". Update your code.
+            </p>
+          )}
+        </>
+      )}
       {error && <p>Error: {error.message}</p>}
     </div>
   );
 }
 ```
 
+### `useImageEntities()` — Discover image models for a picker
+
+**Permission:** `entities:image_generate` (same scope as generation)
+**Returns:** `{ entities, isLoading, error, refetch }`
+
+When you want to let the user pick a model — instead of letting the platform pick — call `useImageEntities(filter)` and render the results.
+
+```tsx
+import { useImageEntities, useImageGeneration } from '@fias/arche-sdk';
+
+function ImageModelPicker() {
+  const { entities, isLoading } = useImageEntities({
+    modes: ['image-to-image'],
+    supportsReferenceImage: true,
+  });
+  const { generate } = useImageGeneration();
+
+  if (isLoading) return <p>Loading models…</p>;
+  return (
+    <ul>
+      {entities.map((e) => (
+        <li key={e.entityId}>
+          <button onClick={() => generate({ entityId: e.entityId, prompt: '…' })}>
+            {e.displayName} ({e.provider})
+            {e.isPlatformRecommended && ' ⭐ platform pick'}
+          </button>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+Filter fields: `provider`, `modes` (OR-match by default; set `requireAllModes: true` for AND), `styles`, `supportsReferenceImage`, `platformRecommendedOnly`, `providerRecommendedOnly`, `includeDeprecated`. Defaults exclude deprecated entities.
+
 ### `useFiasFiles()` — User-files filesystem (SDK ≥ 1.9.0)
 
 **Permissions:** `files:read` for `list`/`read`/`getDownloadUrl`; add `files:write` for `write`/`update`/`delete`
@@ -446,6 +527,18 @@ If newer package versions are available, tell the user and ask if they want to u
 
 If `sync --dry-run` shows pending changes, tell the user and offer to run `npx fias-dev sync` to update AI instruction files and config from the latest SDK templates. This never touches source code or project-specific files (`package.json`, `fias-plugin.json`, `src/`).
 
+#### UI cache after a harness upgrade
+
+The harness pulls its host-page UI (toolbar, mode toggle, sign-in modal) from a CDN and caches it in `~/.fias/harness-cache/`. The cached UI takes priority over the bundled copy that ships in the npm package.
+
+When you upgrade `@fias/plugin-dev-harness` but the CDN hasn't been redeployed yet, the cached UI can be older than the CLI. fias-dev now detects this case automatically and falls back to the bundled UI — look for this line in the startup log:
+
+```
+ℹ Cached harness UI v1.14.3 is older than CLI v1.18.0 — using bundled UI.
+```
+
+That message means everything is fine; the bundled UI exactly matches your CLI version. If you ever see stale behavior persist across an upgrade (and the line above didn't appear), delete `~/.fias/harness-cache/` and restart.
+
 ### Starting Development
 
 ```bash
@@ -482,6 +575,39 @@ npx fias-dev entities --type "model-definition"    # Filter by type
 npx fias-dev entities --detail ent_modeldef_gpt_image_1_5 # Full entity details (capabilities, sizes, pricing)
 ```
 
+### Debugging — Read the Browser's View Directly
+
+The harness mirrors every browser-side event to a per-port log file at `/tmp/fias-dev-<port>.log` (so usually `/tmp/fias-dev-3200.log`). The file path is also printed at startup:
+
+```
+Browser dev-log mirror: /tmp/fias-dev-3200.log
+```
+
+What's captured:
+
+- Every Dev Console entry (`send` / `recv` / `info` / `error` / `toast` / `cost` / `nav`)
+- Every uncaught JS error (`window.error`)
+- Every unhandled promise rejection (`unhandledrejection`)
+- Bridge requests + responses with payload previews
+
+Format is one line per event:
+
+```
+2026-05-24T07:14:33.123Z [ERROR] window.error {"message":"...","file":"...","line":42}
+2026-05-24T07:14:35.456Z [SEND]  image_generate {"entityId":"ent_modeldef_..."}
+2026-05-24T07:14:36.789Z [RECV]  response       {...}
+```
+
+**For AI agents pair-debugging with a developer:** tail this file instead of asking the developer to open DevTools and copy-paste output. Reproduce the failing action in the browser, then read the file — you'll see exactly what the iframe and harness exchanged.
+
+```bash
+tail -f /tmp/fias-dev-3200.log
+```
+
+The file is truncated on every `fias-dev` start, so it always reflects the current session.
+
+The mirror uses `navigator.sendBeacon` (with a `fetch` fallback) so there's a sub-second delay before the most recent events land in the file. If you're chasing a race, give it a beat before reading.
+
 ### Validating the Manifest
 
 ```bash