@happyvertical/smrt-assets 0.55.9 → 0.55.11

package/dist/manifest.json

@@ -2,7 +2,7 @@
   "version": "1.0.0",
   "timestamp": 0,
   "packageName": "@happyvertical/smrt-assets",
-  "packageVersion": "0.55.9",
+  "packageVersion": "0.55.11",
   "objects": {
     "@happyvertical/smrt-assets:AssetAssociation": {
       "name": "assetassociation",
@@ -3151,6 +3151,210 @@
     }
   },
   "moduleType": "smrt",
+  "recipes": [
+    {
+      "id": "assets.attachments",
+      "className": "AssetAttachmentsRecipe",
+      "label": "Attachments",
+      "summary": "Attach authorized files to records and retain their history.",
+      "synonyms": [
+        "file attachments",
+        "record files",
+        "supporting documents"
+      ],
+      "models": [
+        "@happyvertical/smrt-assets:Asset",
+        "@happyvertical/smrt-assets:AssetAssociation"
+      ],
+      "nav": [
+        {
+          "label": "Attachments",
+          "model": "@happyvertical/smrt-assets:Asset",
+          "icon": "fileText",
+          "description": "Supporting files connected to the record you are viewing.",
+          "noun": "attachment"
+        }
+      ],
+      "requires": [
+        "assets.library"
+      ],
+      "group": {
+        "id": "assets",
+        "label": "Files and media",
+        "summary": "Organize files and media, then attach them to the records that need them."
+      },
+      "section": {
+        "id": "assets",
+        "label": "Assets",
+        "icon": "folder",
+        "description": "Files, media and attachments for your work."
+      },
+      "options": {
+        "@happyvertical/smrt-assets:Asset": {
+          "fields": {
+            "name": {
+              "label": "File name",
+              "order": 1
+            },
+            "description": {
+              "label": "Description",
+              "order": 2
+            },
+            "mimeType": {
+              "label": "File type",
+              "order": 3
+            }
+          }
+        },
+        "@happyvertical/smrt-assets:AssetAssociation": {
+          "fields": {
+            "assetId": {
+              "label": "Attachment",
+              "order": 1
+            },
+            "role": {
+              "label": "Role",
+              "order": 2
+            },
+            "sortOrder": {
+              "label": "Display order",
+              "order": 3
+            }
+          }
+        }
+      },
+      "help": {
+        "markdown": "## Overview\n\nAttachments keep authorized supporting files connected to a record without making a public storage link. The application supplies the authorization and upload endpoint; this recipe records the asset and its relationship.\n\n## Tasks\n\n### Describe an attachment\n\n1. Use a clear {field:Asset.name} so people can identify the file.\n2. Add a {field:Asset.description} when the attachment needs context.\n3. Check the {field:Asset.mimeType} before offering the file to a viewer.\n\n### Link an attachment to a record\n\n1. Select the {field:AssetAssociation.assetId} to link.\n2. Set a {field:AssetAssociation.role} when the record uses more than one file.\n3. Adjust {field:AssetAssociation.sortOrder} to control display order.\n",
+        "fieldRefs": [
+          "Asset.description",
+          "Asset.mimeType",
+          "Asset.name",
+          "AssetAssociation.assetId",
+          "AssetAssociation.role",
+          "AssetAssociation.sortOrder"
+        ]
+      },
+      "runtime": "both",
+      "demoSeed": {
+        "export": "@happyvertical/smrt-assets/playground#assetAttachmentMockAttachments"
+      },
+      "demo": {
+        "mode": "server",
+        "reasons": [
+          "Needs a server because its package depends on @happyvertical/smrt-tenancy, which do not build for a browser (#3624)."
+        ]
+      }
+    },
+    {
+      "id": "assets.library",
+      "className": "AssetLibraryRecipe",
+      "label": "Asset Library",
+      "summary": "Organize files and media with folders, types, and statuses.",
+      "synonyms": [
+        "media library",
+        "file library",
+        "digital assets"
+      ],
+      "models": [
+        "@happyvertical/smrt-assets:Asset",
+        "@happyvertical/smrt-assets:Folder",
+        "@happyvertical/smrt-assets:AssetType",
+        "@happyvertical/smrt-assets:AssetStatus",
+        "@happyvertical/smrt-assets:AssetMetafield"
+      ],
+      "nav": [
+        {
+          "label": "Assets",
+          "model": "@happyvertical/smrt-assets:Asset",
+          "icon": "archive",
+          "description": "Files and media you can organize, reuse and share.",
+          "noun": "asset"
+        },
+        {
+          "label": "Folders",
+          "model": "@happyvertical/smrt-assets:Folder",
+          "icon": "folder",
+          "description": "Organize assets into clear, reusable groups.",
+          "noun": "folder"
+        }
+      ],
+      "requires": [],
+      "group": {
+        "id": "assets",
+        "label": "Files and media",
+        "summary": "Organize files and media, then attach them to the records that need them."
+      },
+      "section": {
+        "id": "assets",
+        "label": "Assets",
+        "icon": "folder",
+        "description": "Files, media and attachments for your work."
+      },
+      "options": {
+        "@happyvertical/smrt-assets:Asset": {
+          "fields": {
+            "name": {
+              "label": "Name",
+              "order": 1
+            },
+            "description": {
+              "order": 2
+            },
+            "folderId": {
+              "label": "Folder",
+              "order": 3
+            },
+            "typeSlug": {
+              "label": "Type",
+              "order": 4
+            },
+            "statusSlug": {
+              "label": "Status",
+              "order": 5
+            },
+            "mimeType": {
+              "label": "File type",
+              "order": 6
+            }
+          }
+        },
+        "@happyvertical/smrt-assets:Folder": {
+          "fields": {
+            "name": {
+              "label": "Name",
+              "order": 1
+            },
+            "description": {
+              "order": 2
+            }
+          }
+        }
+      },
+      "help": {
+        "markdown": "## Overview\n\nThe Asset Library keeps files and media in one place. Organize assets into folders, classify them by type and status, and keep a clear description for people who need to find them later.\n\n## Tasks\n\n### Add an asset\n\n1. Give the asset a recognizable {field:Asset.name}.\n2. Add a {field:Asset.description} that explains how the file can be used.\n3. Select its {field:Asset.folderId}, {field:Asset.typeSlug}, and {field:Asset.statusSlug}.\n4. Confirm the {field:Asset.mimeType} matches the file you intend to manage.\n\n### Organize folders\n\n1. Create a folder with a descriptive {field:Folder.name}.\n2. Use the {field:Folder.description} to explain the folder's purpose.\n",
+        "fieldRefs": [
+          "Asset.description",
+          "Asset.folderId",
+          "Asset.mimeType",
+          "Asset.name",
+          "Asset.statusSlug",
+          "Asset.typeSlug",
+          "Folder.description",
+          "Folder.name"
+        ]
+      },
+      "runtime": "both",
+      "demoSeed": {
+        "export": "@happyvertical/smrt-assets/playground#assetGridMockAssets"
+      },
+      "demo": {
+        "mode": "server",
+        "reasons": [
+          "Needs a server because its package depends on @happyvertical/smrt-tenancy, which do not build for a browser (#3624)."
+        ]
+      }
+    }
+  ],
   "smrtDependencies": [
     "@happyvertical/smrt-core",
     "@happyvertical/smrt-tags",

package/dist/playground.d.ts

@@ -1,2 +1,2 @@
-export { default } from './svelte/playground.js';
+export { assetAttachmentMockAttachments, assetGridMockAssets, default, } from './svelte/playground.js';
 //# sourceMappingURL=playground.d.ts.map

package/dist/playground.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"playground.d.ts","sourceRoot":"","sources":["../src/playground.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"playground.d.ts","sourceRoot":"","sources":["../src/playground.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,8BAA8B,EAC9B,mBAAmB,EACnB,OAAO,GACR,MAAM,wBAAwB,CAAC"}

package/dist/playground.js

@@ -1,2 +1,2 @@
-import { t as playground_default } from "./chunks/playground-CGd8_X0M.js";
-export { playground_default as default };
+import { n as assetGridMockAssets, r as playground_default, t as assetAttachmentMockAttachments } from "./chunks/playground-Du1zCQu7.js";
+export { assetAttachmentMockAttachments, assetGridMockAssets, playground_default as default };

package/dist/recipes.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Declared feature recipes for smrt-assets (#3725).
+ *
+ * The recipes describe the package's model-backed asset workflows and their
+ * public UI metadata. Storage remains application-owned, so no provider is
+ * declared here. The package's UI components require host persistence or
+ * record authorization context, so neither recipe declares a standalone
+ * placement.
+ */
+import { SmrtRecipe } from '@happyvertical/smrt-core';
+import { Asset } from './asset.js';
+import { AssetAssociation } from './asset-association.js';
+import { AssetMetafield } from './asset-metafield.js';
+import { AssetStatus } from './asset-status.js';
+import { Folder } from './folder.js';
+/** Organize, classify, and manage a library of files and media. */
+export declare class AssetLibraryRecipe extends SmrtRecipe {
+    static id: string;
+    static help: string;
+    static label: string;
+    static summary: string;
+    static synonyms: string[];
+    static group: {
+        id: string;
+        label: string;
+        summary: string;
+    };
+    static section: {
+        id: string;
+        label: string;
+        icon: string;
+        description: string;
+    };
+    static models: (typeof AssetStatus | typeof AssetMetafield)[];
+    static runtime: "both";
+    static demoSeed: {
+        readonly export: "@happyvertical/smrt-assets/playground#assetGridMockAssets";
+    };
+    static nav: ({
+        label: string;
+        model: typeof Asset;
+        icon: string;
+        description: string;
+        noun: string;
+    } | {
+        label: string;
+        model: typeof Folder;
+        icon: string;
+        description: string;
+        noun: string;
+    })[];
+    static options: {
+        readonly Asset: {
+            readonly fields: {
+                readonly name: {
+                    readonly label: "Name";
+                    readonly order: 1;
+                };
+                readonly description: {
+                    readonly order: 2;
+                };
+                readonly folderId: {
+                    readonly label: "Folder";
+                    readonly order: 3;
+                };
+                readonly typeSlug: {
+                    readonly label: "Type";
+                    readonly order: 4;
+                };
+                readonly statusSlug: {
+                    readonly label: "Status";
+                    readonly order: 5;
+                };
+                readonly mimeType: {
+                    readonly label: "File type";
+                    readonly order: 6;
+                };
+            };
+        };
+        readonly Folder: {
+            readonly fields: {
+                readonly name: {
+                    readonly label: "Name";
+                    readonly order: 1;
+                };
+                readonly description: {
+                    readonly order: 2;
+                };
+            };
+        };
+    };
+}
+/** Attach authorized files to records while retaining their provenance. */
+export declare class AssetAttachmentsRecipe extends SmrtRecipe {
+    static id: string;
+    static help: string;
+    static label: string;
+    static summary: string;
+    static synonyms: string[];
+    static group: {
+        id: string;
+        label: string;
+        summary: string;
+    };
+    static section: {
+        id: string;
+        label: string;
+        icon: string;
+        description: string;
+    };
+    static models: (typeof AssetAssociation | typeof Asset)[];
+    static runtime: "both";
+    static demoSeed: {
+        readonly export: "@happyvertical/smrt-assets/playground#assetAttachmentMockAttachments";
+    };
+    static nav: {
+        label: string;
+        model: typeof Asset;
+        icon: string;
+        description: string;
+        noun: string;
+    }[];
+    static requires: string[];
+    static options: {
+        readonly Asset: {
+            readonly fields: {
+                readonly name: {
+                    readonly label: "File name";
+                    readonly order: 1;
+                };
+                readonly description: {
+                    readonly label: "Description";
+                    readonly order: 2;
+                };
+                readonly mimeType: {
+                    readonly label: "File type";
+                    readonly order: 3;
+                };
+            };
+        };
+        readonly AssetAssociation: {
+            readonly fields: {
+                readonly assetId: {
+                    readonly label: "Attachment";
+                    readonly order: 1;
+                };
+                readonly role: {
+                    readonly label: "Role";
+                    readonly order: 2;
+                };
+                readonly sortOrder: {
+                    readonly label: "Display order";
+                    readonly order: 3;
+                };
+            };
+        };
+    };
+}
+//# sourceMappingURL=recipes.d.ts.map

package/dist/recipes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipes.d.ts","sourceRoot":"","sources":["../src/recipes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,mEAAmE;AACnE,qBAAa,kBAAmB,SAAQ,UAAU;IAChD,MAAM,CAAC,EAAE,SAAoB;IAC7B,MAAM,CAAC,IAAI,SAAgC;IAC3C,MAAM,CAAC,KAAK,SAAmB;IAC/B,MAAM,CAAC,OAAO,SACkD;IAChE,MAAM,CAAC,QAAQ,WAAuD;IACtE,MAAM,CAAC,KAAK;;;;MAKV;IACF,MAAM,CAAC,OAAO;;;;;MAKZ;IACF,MAAM,CAAC,MAAM,iDAA2D;IACxE,MAAM,CAAC,OAAO,EAAG,MAAM,CAAU;IACjC,MAAM,CAAC,QAAQ;;MAEJ;IACX,MAAM,CAAC,GAAG;;;;;;;;;;;;SAeR;IACF,MAAM,CAAC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAiBH;CACZ;AAED,2EAA2E;AAC3E,qBAAa,sBAAuB,SAAQ,UAAU;IACpD,MAAM,CAAC,EAAE,SAAwB;IACjC,MAAM,CAAC,IAAI,SAAoC;IAC/C,MAAM,CAAC,KAAK,SAAiB;IAC7B,MAAM,CAAC,OAAO,SACmD;IACjE,MAAM,CAAC,QAAQ,WAIb;IACF,MAAM,CAAC,KAAK;;;;MAKV;IACF,MAAM,CAAC,OAAO;;;;;MAKZ;IACF,MAAM,CAAC,MAAM,6CAA6B;IAC1C,MAAM,CAAC,OAAO,EAAG,MAAM,CAAU;IACjC,MAAM,CAAC,QAAQ;;MAGJ;IACX,MAAM,CAAC,GAAG;;;;;;QAQR;IACF,MAAM,CAAC,QAAQ,WAAsB;IACrC,MAAM,CAAC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAeH;CACZ"}

package/dist/smrt-knowledge.json

@@ -3,12 +3,12 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-assets",
-  "packageVersion": "0.55.9",
+  "packageVersion": "0.55.11",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "2d6025c8119107f51b2e62c1341969cb364193fdb11c659f98e250a03730d8c4",
-    "packageJson": "8ed942691b4dbf73936fcc84237aac2799c49770f3e04103f828b5c160e0a6c5",
+    "manifest": "5e8849091280bac925285ed65ecdea60bf1c67ace56e94e6e677ba56a61094b3",
+    "packageJson": "76aaf518dc7b815e8e846ec380433cb6b8967e47861bdb277c37e91291816922",
     "agents": "4e84d65324e346f9c6072da7ccee6753289efb95ffb2faf5e999081502189737"
   },
   "exports": [
@@ -4346,6 +4346,210 @@
     "uuidColumns": 40
   },
   "agentDoc": "# @happyvertical/smrt-assets\n\nProvider-agnostic asset management with versioning, type classification, and generic/provenance associations.\n\n## Models\n\n- **Asset** (STI base): versioning via `primaryVersionId` chain + `version` number. `ownerProfileId`, `typeSlug`, `statusSlug`, `mimeType`, `sourceUri`. Derivation chain via `sourceAssetId` (R3-D — was `parentId` before the rename; column `source_asset_id`).\n- **AssetType** / **AssetStatus**: lookup tables for classification and lifecycle.\n- **AssetMetafield**: custom metadata field definitions with JSON validation rules.\n- **Folder**: hierarchical container for assets. Own `SmrtHierarchical` model with its own `folders` table (R3-D — was an STI subclass of Asset before). `Asset.folderId` points to the folder.\n- **AssetAssociation**: generic/provenance polymorphic join — `assetId` + `metaType` + `metaId` + `role` + `sortOrder`. Use it when a relationship is not owned by a base/domain model join table like `content_assets`, `profile_assets`, `event_assets`, `place_assets`, or `product_assets`.\n\n## Key Patterns\n\n- **Versioning**: `createNewVersion()` increments version, chains via `primaryVersionId`. `findVersions()` to retrieve history.\n- **Tag integration**: `addTag()`/`removeTag()` use raw `db.upsert()` on `asset_tags` join table (not a SMRT model).\n- **AssetStore**: abstraction for provider-agnostic file I/O (S3, local, etc.).\n  `planFile(asset, opts)` resolves a recoverable URI before bytes are written;\n  persist it before `preserveFile(asset, bytes, opts)`. Preservation adopts equal\n  existing bytes and rejects changed bytes, changed resolver targets and read\n  failures other than not-found. The caller owns receipt fencing/serialization.\n  `removeFile(asset)` removes only bytes for recovery cleanup, including an\n  already-pruned owner record; `remove(asset)` also deletes the owner record.\n- **Ownership rule**: base/domain-owned asset relationships should live on noun join tables such as `content_assets`, `profile_assets`, `event_assets`, `place_assets`, and `product_assets`; keep `AssetAssociation` for generic/provenance links like image derivation.\n\n## Runtime surface\n\nApps and agents should depend on the public **asset runtime** rather than hand-wiring a collection + store per-package (#1128).\n\n- `createAssetRuntime({ db, storage })` → `AssetRuntime` bundling `AssetCollection`, `AssetAssociationCollection`, and an initialized `AssetStore`.\n- `AssetRuntime.storeSourceAsset(name, data, opts)` — create a new source asset (record + bytes).\n- `AssetRuntime.storeDerivedAsset(source, name, data, opts)` — create a derivative with `sourceAssetId` set and (by default) a provenance `AssetAssociation` under a chosen role.\n- `AssetRuntime.linkDerivation(source, derivative, { role })` — record provenance without touching bytes.\n- `AssetRuntime.setExtractionStatus(asset, status, { error?, extractedAt? })` — write canonical extraction metadata into the asset's description JSON sidecar. Non-destructive: if `description` is free-form prose or non-object JSON, the original value is preserved under the reserved `text` key instead of being overwritten. Existing JSON objects are merged into.\n\nAgents that need asset I/O should accept an `AssetRuntimeLike` in their options rather than asking callers to pass a store + collection separately.\n\n## Serving contract\n\n- `serveAsset({ runtime, asset, tenantId?, disposition?, canAccess?, headers?, remoteMode? })` → standard Web `Response`.\n  - `404` when the id doesn't resolve; `403` when the tenant mismatches or `canAccess` denies; `302` when `remoteMode: 'redirect'` and the asset's `sourceUri` is `http(s)`; `502` when `remoteMode: 'proxy'` and the origin fetch fails; `500` on store read errors or unexpected failures; `200` otherwise with `Content-Type`, `Content-Length`, and `Content-Disposition` set.\n  - Assets whose `sourceUri` is `http(s)` are supported via `remoteMode`: `'proxy'` (default, fetch and return bytes), `'redirect'` (302 to the origin), or `'error'` (treat as misconfiguration). Pass `fetchImpl` to swap the fetch client.\n  - `Content-Disposition` uses an ASCII-safe quoted `filename` fallback and retains the Unicode download name in UTF-8 `filename*` ([RFC 6266](https://www.rfc-editor.org/rfc/rfc6266#section-4.3), [RFC 8187](https://www.rfc-editor.org/rfc/rfc8187#section-3.2.1)). Both names strip C0/DEL/C1 controls and replace `\"` / `\\` / `/` to prevent header injection; isolated UTF-16 surrogates become U+FFFD before encoding, while valid pairs are preserved.\n  - The 500 body is a generic `'Internal error serving asset'`; the underlying error is logged via `console.error` so operators can debug without leaking paths/bucket names to clients.\n  - Works in SvelteKit `+server.ts` endpoints, Hono, and any runtime with a global `Response` (Node 18+). Pass `responseCtor` for older runtimes.\n- `resolveAssetForServing(options)` → `{ asset, data, contentType, filename, size }` when callers want to render their own framework response. Throws `AssetServeError(status)` on the same failure modes.\n\n## Source/derived vocabulary\n\nThe following roles are exported as `ASSET_ROLES` and should be preferred over ad-hoc strings when apps want cross-package tooling (serving, UI pickers) to agree on meaning:\n\n| Role | Use |\n|------|-----|\n| `source_document` | original upstream document (agenda PDF, minutes) |\n| `document_image` | page/extracted image derived from a source document |\n| `thumbnail` | preview rendition of another asset |\n| `proof` | non-canonical evidence asset backing a fact |\n| `derivation_source` | \"came from\" link on generated media |\n| `attachment` | generic owner-join link |\n| `hero` | primary/featured asset on an owner |\n\nCanonical metadata keys are exported as `ASSET_METADATA_KEYS`: `extractionStatus`, `extractionError`, `extractedAt`, `sourceUrl`, `sourceHash`, `pageNumber`. Extraction status values live in `ASSET_EXTRACTION_STATUS` (`pending | running | succeeded | failed`).\n\n## UI Registry\n\nThe `./ui` subpath exports `ASSETS_MODULE_META` and `ASSETS_UI_SLOTS` so registry-driven hosts (smrt-chat, dynamic admin shells) can discover the package's Svelte components without a hard import.\n\n```ts\nimport { ASSETS_MODULE_META, ASSETS_UI_SLOTS } from '@happyvertical/smrt-assets/ui';\nimport '@happyvertical/smrt-assets/svelte'; // side-effect: ModuleUIRegistry.register(...)\nimport { ModuleUIRegistry } from '@happyvertical/smrt-ui/registry';\n\nconst AssetManager = ModuleUIRegistry.get('@happyvertical/smrt-assets', 'asset-manager');\n```\n\nRegistered slots: `asset-manager` (admin), `asset-grid` / `asset-list` (list), `asset-detail` (detail), `asset-toolbar` / `asset-action-bar` (action), `asset-create-modal` (form). Slot IDs are stable contracts — host apps reference them by string.\n\n## Gotchas\n\n- **Files SDK is a lazy boundary (#1979)**: `AssetStore` loads `@happyvertical/files` through `src/files-runtime.ts` (bundler-invisible), because smrt-assets is reachable from provider-neutral consumer graphs via profiles. Node/tsx/vite-dev runtimes resolve it on first file operation; fully-bundled deployments import `@happyvertical/smrt-assets/filesystem` at startup. Never import the files SDK statically from modules reachable from `src/index.ts`.\n- **Version history manual**: `findVersions()` chaining required — no ORM shortcut\n- **Tag management uses raw SQL**: `asset_tags` is a join table, not an SMRT model\n- **Folder tree traversal**: via `SmrtHierarchical` (`getParent`/`getChildren`/`getAncestors`/`getDescendants`/`getHierarchy`/`moveTo`); `FolderCollection.getTree(rootId?)` and `getPath(folderId)` wrap these for convenience\n- **AssetAssociation polymorphic FK**: requires manual `metaType` string matching\n- **Optional tenancy**: assets can be global (tenantId=null) or tenant-scoped\n",
+  "recipes": [
+    {
+      "id": "assets.attachments",
+      "className": "AssetAttachmentsRecipe",
+      "label": "Attachments",
+      "summary": "Attach authorized files to records and retain their history.",
+      "synonyms": [
+        "file attachments",
+        "record files",
+        "supporting documents"
+      ],
+      "models": [
+        "@happyvertical/smrt-assets:Asset",
+        "@happyvertical/smrt-assets:AssetAssociation"
+      ],
+      "nav": [
+        {
+          "label": "Attachments",
+          "model": "@happyvertical/smrt-assets:Asset",
+          "icon": "fileText",
+          "description": "Supporting files connected to the record you are viewing.",
+          "noun": "attachment"
+        }
+      ],
+      "requires": [
+        "assets.library"
+      ],
+      "group": {
+        "id": "assets",
+        "label": "Files and media",
+        "summary": "Organize files and media, then attach them to the records that need them."
+      },
+      "section": {
+        "id": "assets",
+        "label": "Assets",
+        "icon": "folder",
+        "description": "Files, media and attachments for your work."
+      },
+      "options": {
+        "@happyvertical/smrt-assets:Asset": {
+          "fields": {
+            "name": {
+              "label": "File name",
+              "order": 1
+            },
+            "description": {
+              "label": "Description",
+              "order": 2
+            },
+            "mimeType": {
+              "label": "File type",
+              "order": 3
+            }
+          }
+        },
+        "@happyvertical/smrt-assets:AssetAssociation": {
+          "fields": {
+            "assetId": {
+              "label": "Attachment",
+              "order": 1
+            },
+            "role": {
+              "label": "Role",
+              "order": 2
+            },
+            "sortOrder": {
+              "label": "Display order",
+              "order": 3
+            }
+          }
+        }
+      },
+      "help": {
+        "markdown": "## Overview\n\nAttachments keep authorized supporting files connected to a record without making a public storage link. The application supplies the authorization and upload endpoint; this recipe records the asset and its relationship.\n\n## Tasks\n\n### Describe an attachment\n\n1. Use a clear {field:Asset.name} so people can identify the file.\n2. Add a {field:Asset.description} when the attachment needs context.\n3. Check the {field:Asset.mimeType} before offering the file to a viewer.\n\n### Link an attachment to a record\n\n1. Select the {field:AssetAssociation.assetId} to link.\n2. Set a {field:AssetAssociation.role} when the record uses more than one file.\n3. Adjust {field:AssetAssociation.sortOrder} to control display order.\n",
+        "fieldRefs": [
+          "Asset.description",
+          "Asset.mimeType",
+          "Asset.name",
+          "AssetAssociation.assetId",
+          "AssetAssociation.role",
+          "AssetAssociation.sortOrder"
+        ]
+      },
+      "runtime": "both",
+      "demoSeed": {
+        "export": "@happyvertical/smrt-assets/playground#assetAttachmentMockAttachments"
+      },
+      "demo": {
+        "mode": "server",
+        "reasons": [
+          "Needs a server because its package depends on @happyvertical/smrt-tenancy, which do not build for a browser (#3624)."
+        ]
+      }
+    },
+    {
+      "id": "assets.library",
+      "className": "AssetLibraryRecipe",
+      "label": "Asset Library",
+      "summary": "Organize files and media with folders, types, and statuses.",
+      "synonyms": [
+        "media library",
+        "file library",
+        "digital assets"
+      ],
+      "models": [
+        "@happyvertical/smrt-assets:Asset",
+        "@happyvertical/smrt-assets:Folder",
+        "@happyvertical/smrt-assets:AssetType",
+        "@happyvertical/smrt-assets:AssetStatus",
+        "@happyvertical/smrt-assets:AssetMetafield"
+      ],
+      "nav": [
+        {
+          "label": "Assets",
+          "model": "@happyvertical/smrt-assets:Asset",
+          "icon": "archive",
+          "description": "Files and media you can organize, reuse and share.",
+          "noun": "asset"
+        },
+        {
+          "label": "Folders",
+          "model": "@happyvertical/smrt-assets:Folder",
+          "icon": "folder",
+          "description": "Organize assets into clear, reusable groups.",
+          "noun": "folder"
+        }
+      ],
+      "requires": [],
+      "group": {
+        "id": "assets",
+        "label": "Files and media",
+        "summary": "Organize files and media, then attach them to the records that need them."
+      },
+      "section": {
+        "id": "assets",
+        "label": "Assets",
+        "icon": "folder",
+        "description": "Files, media and attachments for your work."
+      },
+      "options": {
+        "@happyvertical/smrt-assets:Asset": {
+          "fields": {
+            "name": {
+              "label": "Name",
+              "order": 1
+            },
+            "description": {
+              "order": 2
+            },
+            "folderId": {
+              "label": "Folder",
+              "order": 3
+            },
+            "typeSlug": {
+              "label": "Type",
+              "order": 4
+            },
+            "statusSlug": {
+              "label": "Status",
+              "order": 5
+            },
+            "mimeType": {
+              "label": "File type",
+              "order": 6
+            }
+          }
+        },
+        "@happyvertical/smrt-assets:Folder": {
+          "fields": {
+            "name": {
+              "label": "Name",
+              "order": 1
+            },
+            "description": {
+              "order": 2
+            }
+          }
+        }
+      },
+      "help": {
+        "markdown": "## Overview\n\nThe Asset Library keeps files and media in one place. Organize assets into folders, classify them by type and status, and keep a clear description for people who need to find them later.\n\n## Tasks\n\n### Add an asset\n\n1. Give the asset a recognizable {field:Asset.name}.\n2. Add a {field:Asset.description} that explains how the file can be used.\n3. Select its {field:Asset.folderId}, {field:Asset.typeSlug}, and {field:Asset.statusSlug}.\n4. Confirm the {field:Asset.mimeType} matches the file you intend to manage.\n\n### Organize folders\n\n1. Create a folder with a descriptive {field:Folder.name}.\n2. Use the {field:Folder.description} to explain the folder's purpose.\n",
+        "fieldRefs": [
+          "Asset.description",
+          "Asset.folderId",
+          "Asset.mimeType",
+          "Asset.name",
+          "Asset.statusSlug",
+          "Asset.typeSlug",
+          "Folder.description",
+          "Folder.name"
+        ]
+      },
+      "runtime": "both",
+      "demoSeed": {
+        "export": "@happyvertical/smrt-assets/playground#assetGridMockAssets"
+      },
+      "demo": {
+        "mode": "server",
+        "reasons": [
+          "Needs a server because its package depends on @happyvertical/smrt-tenancy, which do not build for a browser (#3624)."
+        ]
+      }
+    }
+  ],
   "browser": {
     "status": "server-only",
     "issues": [

package/dist/svelte/playground/AttachmentPanelPreview.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
 import { Checkbox } from '@happyvertical/smrt-ui/forms';
 import AttachmentPanel from '../components/AttachmentPanel.svelte';
+import { assetAttachmentMockAttachments } from '../playground.js';
 
 let canUpload = $state(true);
 let description = $state('Supporting document for review');
@@ -15,7 +16,7 @@ function submit(event: SubmitEvent & { currentTarget: HTMLFormElement }) {
 </script>
 <div class="preview">
   <Checkbox label="May upload attachments" bind:checked={canUpload} />
-  <AttachmentPanel attachments={[{ id: 'document-v2', name: 'Supplier quote.pdf', mimeType: 'application/pdf', version: 2, note: 'Corrected supplier reference', statusLabel: 'Awaiting review', versions: [{ id: 'document-v1', name: 'Supplier quote.pdf', mimeType: 'application/pdf', version: 1, note: 'Original supplied document' }] }]}
+  <AttachmentPanel attachments={assetAttachmentMockAttachments}
     upload={{ action: '', canUpload, description, message, help: 'Preview accepts a local file but never sends it.', hiddenFields: [{ name: 'requestId', value: 'preview-request-retained' }], onsubmit: submit }} />
 </div>
 <style>.preview { display: grid; gap: var(--smrt-spacing-4); }</style>

package/dist/svelte/playground/AttachmentPanelPreview.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AttachmentPanelPreview.svelte.d.ts","sourceRoot":"","sources":["../../../src/svelte/playground/AttachmentPanelPreview.svelte.ts"],"names":[],"mappings":"AA6BA,QAAA,MAAM,sBAAsB,2DAAwC,CAAC;AACrE,KAAK,sBAAsB,GAAG,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACxE,eAAe,sBAAsB,CAAC"}
+{"version":3,"file":"AttachmentPanelPreview.svelte.d.ts","sourceRoot":"","sources":["../../../src/svelte/playground/AttachmentPanelPreview.svelte.ts"],"names":[],"mappings":"AA+BA,QAAA,MAAM,sBAAsB,2DAAwC,CAAC;AACrE,KAAK,sBAAsB,GAAG,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACxE,eAAe,sBAAsB,CAAC"}