@laplace.live/persona-sdk 0.3.0 → 0.4.0

package/dist/types.d.ts

@@ -1,45 +1,48 @@
 export type ModelFormat = 'live2d' | 'vrm';
-export type ModelKind = 'bundled' | 'user';
 /** Where an item came from: shipped with the app, or added by the user. */
 export type ContentOrigin = 'bundled' | 'user';
-/** A model as the registry lists it. Paths deliberately never cross the wire. */
-export interface ModelRef {
-    /** Stable slug, unique per installed model. */
+/** How a registered file is labelled. Wider than an object's content kinds: `.hdr` is only ever an environment map. */
+export type AssetKind = 'image' | 'video' | 'prop' | 'ibl' | 'lut' | 'animation';
+/** Every content kind the Inventory can list. `pngtuber` is schema-ready before any producer exists. */
+export type InventoryKind = ModelFormat | 'pngtuber' | AssetKind;
+/**
+ * What every registry entry carries, model or asset alike. `kind` is always *what
+ * the thing is* and `origin` always *where it came from* — the two were once
+ * `format`/`kind` on models and `kind`/`origin` on assets, which made `kind` mean
+ * opposite things on the two types.
+ *
+ * Paths deliberately never cross the wire; the registries keep those private.
+ */
+export interface ContentRef {
+    /** Stable slug, unique per installed item. Scene refs key off it. */
     id: string;
     name: string;
-    kind: ModelKind;
-    format: ModelFormat;
+    kind: InventoryKind;
+    origin: ContentOrigin;
     /** Creator credit, for attribution in pickers. */
     author?: string;
     /** Creator or content homepage (https). */
     url?: string;
 }
-/** How a registered file is labelled. Wider than an object's content kinds: `.hdr` is only ever an environment map. */
-export type AssetKind = 'image' | 'video' | 'prop' | 'ibl' | 'lut';
+/** A model as the registry lists it. */
+export interface ModelRef extends ContentRef {
+    kind: ModelFormat;
+}
 /** A registered object-source file. `exists` is false once the file is gone from disk. */
-export interface AssetRef {
-    id: string;
-    name: string;
+export interface AssetRef extends ContentRef {
     /** What the extension makes it — an object created from it starts on this kind. */
     kind: AssetKind;
-    origin: ContentOrigin;
     exists: boolean;
-    /** Creator credit, for attribution in pickers. */
-    author?: string;
-    /** Creator or content homepage (https). */
-    url?: string;
 }
-/** Every content kind the Inventory can list. `pngtuber` is schema-ready before any producer exists. */
-export type InventoryKind = 'live2d' | 'vrm' | 'pngtuber' | 'image' | 'video' | 'prop';
 /**
  * Content metadata decoupled from any on-disk file — local registry entries and
  * remote catalog rows both map into it. `id` is stable forever: scene refs key
  * off it, and it must survive a ship-in-app → download-from-CDN migration.
+ *
+ * A {@link ContentRef} minus `origin`, which a remote row has no answer for until
+ * it is installed, plus what only a catalog knows (thumbnail, payload, revision).
  */
-export interface CatalogItem {
-    id: string;
-    kind: InventoryKind;
-    name: string;
+export interface CatalogItem extends Omit<ContentRef, 'origin'> {
     /** `persona://` for local items; CDN https for metadata-only rows. */
     thumbnailUrl?: string;
     /** Payload location + integrity when not on disk; absent = already local. */
@@ -209,11 +212,11 @@ export interface SceneObjectItem {
 /** Anything the stage renders. Array order in {@link Scene.items} is z-order within each space. */
 export type SceneItem = SceneModelItem | SceneObjectItem;
 export type BackgroundMode = 'transparent' | 'color' | 'image';
-/** `imagePath` is accepted but survives only when the app has allowlisted it via its own picker. */
+/** `imageAssetId` names a registered asset; an id this app cannot resolve renders transparent. */
 export interface SceneBackground {
     mode: BackgroundMode;
     color: string;
-    imagePath: string | null;
+    imageAssetId: string | null;
 }
 export interface SceneBehavior {
     lookAtCursor: boolean;
@@ -405,11 +408,15 @@ export interface AnchorOption {
     anchor: AttachAnchor;
     label: string;
 }
-/** Panel-style model info block. Format-specific fields mirror the app's `ModelInfo`. */
+/**
+ * Panel-style model info block. Format-specific fields mirror the app's `ModelInfo`.
+ * `format` stays the union's discriminant here — this is a runtime diagnostic, not
+ * content metadata, so it does not follow {@link ContentRef}'s `kind`.
+ */
 export interface ModelInfo {
     format: ModelFormat;
     name: string;
-    kind: ModelKind;
+    origin: ContentOrigin;
     file: string;
     loadMs: number;
     /** Format-specific details (canvas/params/textures for Live2D, spec/bones for VRM). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laplace.live/persona-sdk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "TypeScript SDK and wire schema for the LAPLACE Persona plugin API",
   "license": "MIT",
   "type": "module",