@fias/create-fias-plugin 1.3.0 → 1.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fias/create-fias-plugin",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "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`
@@ -783,8 +832,8 @@ You can choose between **Staging** and **Production** environments using the dro
 You can also authenticate via the command line:
 
 ```bash
-npx fias-dev login                    # Authenticate with staging (default)
-npx fias-dev login --env production   # Authenticate with production
+npx fias-dev login                    # Authenticate with prod (default)
+npx fias-dev login --env staging      # Authenticate with staging (internal)
 ```
 
 ### Browsing Available Entities
@@ -820,7 +869,7 @@ happened either way).
 
 ### Managing the asset library (for `useArcheAssets`)
 
-`useArcheAssets()` reads a contributor-curated set of images pinned to the arche's published version. Populate that library with the `assets` subcommands. Each command accepts `--env <staging|prod|local>` (default `staging`) and `--arche-id <id>` (auto-resolved from the manifest when omitted).
+`useArcheAssets()` reads a contributor-curated set of images pinned to the arche's published version. Populate that library with the `assets` subcommands. Each command accepts `--env <prod|staging|local>` (default `prod`) and `--arche-id <id>` (auto-resolved from the manifest when omitted).
 
 ```bash
 npx fias-dev assets enable                  # Turn on the asset library for this arche
@@ -848,7 +897,7 @@ npx fias-dev collaborators set <identifier> \              # Change role and/or
 npx fias-dev collaborators remove <identifier>             # Revoke a collaborator
 ```
 
-All commands accept `--env <staging|production|local>` (default `staging`).
+All commands accept `--env <prod|staging|local>` (default `prod`).
 
 ### Other CLI diagnostics
 

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`
@@ -783,8 +832,8 @@ You can choose between **Staging** and **Production** environments using the dro
 You can also authenticate via the command line:
 
 ```bash
-npx fias-dev login                    # Authenticate with staging (default)
-npx fias-dev login --env production   # Authenticate with production
+npx fias-dev login                    # Authenticate with prod (default)
+npx fias-dev login --env staging      # Authenticate with staging (internal)
 ```
 
 ### Browsing Available Entities
@@ -820,7 +869,7 @@ happened either way).
 
 ### Managing the asset library (for `useArcheAssets`)
 
-`useArcheAssets()` reads a contributor-curated set of images pinned to the arche's published version. Populate that library with the `assets` subcommands. Each command accepts `--env <staging|prod|local>` (default `staging`) and `--arche-id <id>` (auto-resolved from the manifest when omitted).
+`useArcheAssets()` reads a contributor-curated set of images pinned to the arche's published version. Populate that library with the `assets` subcommands. Each command accepts `--env <prod|staging|local>` (default `prod`) and `--arche-id <id>` (auto-resolved from the manifest when omitted).
 
 ```bash
 npx fias-dev assets enable                  # Turn on the asset library for this arche
@@ -848,7 +897,7 @@ npx fias-dev collaborators set <identifier> \              # Change role and/or
 npx fias-dev collaborators remove <identifier>             # Revoke a collaborator
 ```
 
-All commands accept `--env <staging|production|local>` (default `staging`).
+All commands accept `--env <prod|staging|local>` (default `prod`).
 
 ### Other CLI diagnostics