@laplace.live/persona-sdk 0.2.0 → 0.4.0

package/README.md

@@ -67,3 +67,16 @@ in Persona). The client reports them via `onWarning` and goes `closed`.
 Treat the token like a password: it grants control of the app, including loading registered
 models and web overlays. The server listens on loopback unless LAN access is enabled in
 Persona's settings.
+
+## Registry and catalog metadata
+
+`model.list` / `asset.list` return refs with provenance and attribution: assets carry
+`origin` (`'bundled'` shipped with the app, `'user'` registered by the user; models carry
+the same as `kind`), and both may carry optional `author` / `url` credits sourced from the
+app's content manifest.
+
+`CatalogItem` is the transport-agnostic content-metadata shape behind pickers: a stable
+`id` (scene refs key off it), an `InventoryKind`, display `name`, and optional
+`thumbnailUrl`, `version`, `author`, `url`, and `download` (payload location + integrity
+for items not yet on disk — Persona will use this to ship bundled content as
+metadata-only rows downloaded from its CDN on demand).

package/dist/methods.d.ts

@@ -59,6 +59,11 @@ export interface InstanceAddRequest {
 export interface InstanceAddResponse {
     instanceId: string;
 }
+export interface InstanceSetModelRequest {
+    instanceId: string;
+    modelId: string;
+}
+export type InstanceSetModelResponse = EmptyResponse;
 export interface InstanceRemoveRequest {
     instanceId: string;
 }
@@ -394,6 +399,11 @@ export interface MethodMap {
         request: InstanceAddRequest;
         response: InstanceAddResponse;
     };
+    /** Swap a model layer's model in place; placement, primary status, and identity carry over. */
+    'instance.setModel': {
+        request: InstanceSetModelRequest;
+        response: InstanceSetModelResponse;
+    };
     /** Removes any scene item — model or object. */
     'instance.remove': {
         request: InstanceRemoveRequest;

package/dist/schemas.d.ts

@@ -64,6 +64,10 @@ export declare const requestSchemas: {
     'instance.add': z.ZodObject<{
         modelId: z.ZodString;
     }, z.core.$strip>;
+    'instance.setModel': z.ZodObject<{
+        instanceId: z.ZodString;
+        modelId: z.ZodString;
+    }, z.core.$strip>;
     'object.add': z.ZodObject<{
         content: z.ZodCustom<ObjectContent, ObjectContent>;
         name: z.ZodOptional<z.ZodString>;

package/dist/schemas.js

@@ -40,6 +40,7 @@ export const requestSchemas = {
     'scene.delete': z.object({ sceneId: nonEmpty }),
     'scene.setShortcut': z.object({ sceneId: nonEmpty, accelerator: nonEmpty.nullable() }),
     'instance.add': z.object({ modelId: nonEmpty }),
+    'instance.setModel': z.object({ instanceId: nonEmpty, modelId: nonEmpty }),
     'object.add': z.object({
         content: z.custom(isRecord, 'content must be an object'),
         name: nonEmpty.optional(),

package/dist/types.d.ts

@@ -1,23 +1,63 @@
 export type ModelFormat = 'live2d' | 'vrm';
-export type ModelKind = 'bundled' | 'user';
-/** A model as the registry lists it. Paths deliberately never cross the wire. */
-export interface ModelRef {
-    /** Stable slug, unique per installed model. */
+/** Where an item came from: shipped with the app, or added by the user. */
+export type ContentOrigin = 'bundled' | 'user';
+/** 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;
+}
+/** A model as the registry lists it. */
+export interface ModelRef extends ContentRef {
+    kind: ModelFormat;
 }
-/** 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 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;
     exists: boolean;
 }
+/**
+ * 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 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. */
+    download?: {
+        url: string;
+        size: number;
+        sha256: string;
+    };
+    /** Content revision, for CDN-side updates of an installed item. */
+    version?: string;
+    /** Creator credit, for attribution in the Inventory row/detail. */
+    author?: string;
+    /** Creator or content homepage (https). */
+    url?: string;
+}
 /** Screen-space placement: pixels from the stage centre, rotation in radians. */
 export interface ScreenPlacement {
     x: number;
@@ -172,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;
@@ -368,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.2.0",
+  "version": "0.4.0",
   "description": "TypeScript SDK and wire schema for the LAPLACE Persona plugin API",
   "license": "MIT",
   "type": "module",