@fias/create-fias-plugin 1.2.1 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fias/create-fias-plugin",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "publishConfig": {
     "access": "public"
   },

package/templates/default/AGENTS.md

@@ -63,6 +63,55 @@ function MyComponent() {
 - `fonts`: `{ body, heading, mono }` (font-family strings)
 - `components`: `{ borderRadius, buttonRadius, cardRadius, inputRadius, shadowSm, shadowMd, shadowLg, borderWidth }`
 
+### `useFiasFonts()` — Platform font catalog
+
+**Permission:** none
+**Returns:** `{ fonts, ensureFontLoaded }`
+
+The platform vendors a catalog of fonts and injects every family's
+`@font-face` into your plugin iframe automatically (the `.woff2` bytes
+load lazily, only when a glyph is actually painted). So you can use any
+catalog `family` name directly in CSS — no `<link>`, no `@import`, no
+bundled font files, and **no Google Fonts** (those are blocked by the
+plugin CSP). Build a font picker from `fonts`:
+
+```tsx
+import { useFiasFonts } from '@fias/arche-sdk';
+
+function FontPicker({ value, onChange }: { value: string; onChange: (f: string) => void }) {
+  const { fonts } = useFiasFonts();
+  return (
+    <select value={value} onChange={(e) => onChange(e.target.value)} style={{ fontFamily: value }}>
+      {fonts.map((f) => (
+        <option key={f.family} value={f.family} style={{ fontFamily: f.family }}>
+          {f.displayName}
+        </option>
+      ))}
+    </select>
+  );
+}
+```
+
+- `fonts`: `FontCatalogEntry[]` — `{ family, displayName, category, system }`.
+  `category` is one of `sans | serif | display | mono | handwriting | system`;
+  `system: true` marks OS fonts (always available, no web font needed).
+- `ensureFontLoaded(family, sizePx?)`: `Promise<void>` — **canvas / PDF only.**
+  Normal DOM text needs nothing (the browser fetches the face when it
+  paints). But `<canvas>` (incl. Konva / Fabric) and PDF exporters measure
+  glyph metrics synchronously, so they rasterize the fallback face if the
+  bytes aren't in yet. Call and `await` this before drawing. It never
+  rejects, resolves instantly for already-loaded / system fonts, and
+  resolves after a 3s timeout if the CDN is unreachable.
+
+```tsx
+const { ensureFontLoaded } = useFiasFonts();
+await ensureFontLoaded(selectedFamily); // then draw to the canvas
+```
+
+`FONT_CATALOG` and `ensureFontLoaded` are also exported standalone for use
+outside React (e.g. an export routine). For curated heading/body theme
+pairings instead of the flat catalog, see `FONT_PAIRINGS`.
+
 ### `useFiasUser()` — Current user profile
 
 **Permission:** `user:profile:read`
@@ -175,7 +224,7 @@ function AISummarizer() {
 
   async function summarize(text: string) {
     await invoke({
-      entityId: 'ent_fias_ai', // the AI model capability
+      entityId: { capability: 'text-standard' }, // a platform text capability — see "Choosing a text model" below
       input: text, // what to process
       systemPrompt: 'You are a concise summarizer. Return a 2-3 sentence summary.',
     });
@@ -198,7 +247,44 @@ function AISummarizer() {
 }
 ```
 
-The `entityId` references a published model entity. Browse available models with `npx fias-dev entities`. The `systemPrompt` tells the AI how to behave — this is where your plugin's intelligence lives.
+The `systemPrompt` tells the AI how to behave — this is where your plugin's intelligence lives.
+
+#### Choosing a text model
+
+The `entityId` parameter accepts three forms. **Prefer the capability selector** over a hardcoded model id: the platform's models evolve and get retired, and a capability lets your plugin pick up the current best model automatically without a code edit. When the platform retires the model behind a capability, it re-points the capability — your plugin keeps working.
+
+```tsx
+// 1. By capability (recommended) — resolved to the platform's current model
+//    for that tier, and re-pointed automatically if that model is retired.
+await invoke({
+  entityId: { capability: 'text-standard' }, // 'text-fast' | 'text-standard' | 'text-advanced'
+  input,
+  systemPrompt: '...',
+});
+
+// 2. AI router — let the platform pick a model per request based on the
+//    query's complexity. Optionally bias the tier with routingPreference.
+await invoke({
+  entityId: 'ent_fias_ai',
+  input,
+  systemPrompt: '...',
+  routingPreference: 'cost', // 'auto' (default) | 'speed' | 'cost' | 'balanced' | 'performance'
+});
+
+// 3. A specific model id (back-compat) — pins one model. It will stop working
+//    if that model is retired; use a capability for retirement resilience.
+await invoke({ entityId: 'ent_modeldef_haiku_45', input, systemPrompt: '...' });
+```
+
+The text capabilities:
+
+| Capability      | Use it for                                                                   |
+| --------------- | ---------------------------------------------------------------------------- |
+| `text-fast`     | Cheapest, fastest — classification, extraction, short responses, high volume |
+| `text-standard` | Balanced, general-purpose text generation (the sensible default)             |
+| `text-advanced` | Most capable — complex reasoning, nuanced writing, long-form output          |
+
+Browse specific models with `npx fias-dev entities`.
 
 ### `useImageGeneration()` — Generate images via AI models
 

package/templates/default/CLAUDE.md

@@ -63,6 +63,55 @@ function MyComponent() {
 - `fonts`: `{ body, heading, mono }` (font-family strings)
 - `components`: `{ borderRadius, buttonRadius, cardRadius, inputRadius, shadowSm, shadowMd, shadowLg, borderWidth }`
 
+### `useFiasFonts()` — Platform font catalog
+
+**Permission:** none
+**Returns:** `{ fonts, ensureFontLoaded }`
+
+The platform vendors a catalog of fonts and injects every family's
+`@font-face` into your plugin iframe automatically (the `.woff2` bytes
+load lazily, only when a glyph is actually painted). So you can use any
+catalog `family` name directly in CSS — no `<link>`, no `@import`, no
+bundled font files, and **no Google Fonts** (those are blocked by the
+plugin CSP). Build a font picker from `fonts`:
+
+```tsx
+import { useFiasFonts } from '@fias/arche-sdk';
+
+function FontPicker({ value, onChange }: { value: string; onChange: (f: string) => void }) {
+  const { fonts } = useFiasFonts();
+  return (
+    <select value={value} onChange={(e) => onChange(e.target.value)} style={{ fontFamily: value }}>
+      {fonts.map((f) => (
+        <option key={f.family} value={f.family} style={{ fontFamily: f.family }}>
+          {f.displayName}
+        </option>
+      ))}
+    </select>
+  );
+}
+```
+
+- `fonts`: `FontCatalogEntry[]` — `{ family, displayName, category, system }`.
+  `category` is one of `sans | serif | display | mono | handwriting | system`;
+  `system: true` marks OS fonts (always available, no web font needed).
+- `ensureFontLoaded(family, sizePx?)`: `Promise<void>` — **canvas / PDF only.**
+  Normal DOM text needs nothing (the browser fetches the face when it
+  paints). But `<canvas>` (incl. Konva / Fabric) and PDF exporters measure
+  glyph metrics synchronously, so they rasterize the fallback face if the
+  bytes aren't in yet. Call and `await` this before drawing. It never
+  rejects, resolves instantly for already-loaded / system fonts, and
+  resolves after a 3s timeout if the CDN is unreachable.
+
+```tsx
+const { ensureFontLoaded } = useFiasFonts();
+await ensureFontLoaded(selectedFamily); // then draw to the canvas
+```
+
+`FONT_CATALOG` and `ensureFontLoaded` are also exported standalone for use
+outside React (e.g. an export routine). For curated heading/body theme
+pairings instead of the flat catalog, see `FONT_PAIRINGS`.
+
 ### `useFiasUser()` — Current user profile
 
 **Permission:** `user:profile:read`
@@ -175,7 +224,7 @@ function AISummarizer() {
 
   async function summarize(text: string) {
     await invoke({
-      entityId: 'ent_fias_ai', // the AI model capability
+      entityId: { capability: 'text-standard' }, // a platform text capability — see "Choosing a text model" below
       input: text, // what to process
       systemPrompt: 'You are a concise summarizer. Return a 2-3 sentence summary.',
     });
@@ -198,7 +247,44 @@ function AISummarizer() {
 }
 ```
 
-The `entityId` references a published model entity. Browse available models with `npx fias-dev entities`. The `systemPrompt` tells the AI how to behave — this is where your plugin's intelligence lives.
+The `systemPrompt` tells the AI how to behave — this is where your plugin's intelligence lives.
+
+#### Choosing a text model
+
+The `entityId` parameter accepts three forms. **Prefer the capability selector** over a hardcoded model id: the platform's models evolve and get retired, and a capability lets your plugin pick up the current best model automatically without a code edit. When the platform retires the model behind a capability, it re-points the capability — your plugin keeps working.
+
+```tsx
+// 1. By capability (recommended) — resolved to the platform's current model
+//    for that tier, and re-pointed automatically if that model is retired.
+await invoke({
+  entityId: { capability: 'text-standard' }, // 'text-fast' | 'text-standard' | 'text-advanced'
+  input,
+  systemPrompt: '...',
+});
+
+// 2. AI router — let the platform pick a model per request based on the
+//    query's complexity. Optionally bias the tier with routingPreference.
+await invoke({
+  entityId: 'ent_fias_ai',
+  input,
+  systemPrompt: '...',
+  routingPreference: 'cost', // 'auto' (default) | 'speed' | 'cost' | 'balanced' | 'performance'
+});
+
+// 3. A specific model id (back-compat) — pins one model. It will stop working
+//    if that model is retired; use a capability for retirement resilience.
+await invoke({ entityId: 'ent_modeldef_haiku_45', input, systemPrompt: '...' });
+```
+
+The text capabilities:
+
+| Capability      | Use it for                                                                   |
+| --------------- | ---------------------------------------------------------------------------- |
+| `text-fast`     | Cheapest, fastest — classification, extraction, short responses, high volume |
+| `text-standard` | Balanced, general-purpose text generation (the sensible default)             |
+| `text-advanced` | Most capable — complex reasoning, nuanced writing, long-form output          |
+
+Browse specific models with `npx fias-dev entities`.
 
 ### `useImageGeneration()` — Generate images via AI models