@laplace.live/persona-sdk 0.3.0 → 0.5.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;
@@ -232,6 +235,13 @@ export interface SceneCamera {
     fov: number;
 }
 export type SceneLightType = 'directional' | 'point' | 'ambient';
+/**
+ * Per-light shadow tier. `off` is the old `castShadow: false`; the rest raise
+ * shadow-map resolution. A point light pays 6 cube faces for the same tier a
+ * directional light covers with one map, so it gets the smaller of the pair.
+ */
+export declare const SHADOW_QUALITY_LEVELS: readonly ["off", "low", "medium", "high", "extra"];
+export type ShadowQuality = (typeof SHADOW_QUALITY_LEVELS)[number];
 /**
  * One scene light. Angles are degrees. Directional lights aim with
  * azimuth/elevation and sit at x/y/z (which moves their handle and shadow
@@ -250,7 +260,7 @@ export interface SceneLight {
     z: number;
     range: number;
     /** Ambient light is directionless, so it never casts whatever this says. */
-    castShadow: boolean;
+    shadowQuality: ShadowQuality;
     /** Penumbra width in shadow-map texels — a stylistic dial; the filter widens the edge uniformly. */
     shadowRadius: number;
 }
@@ -308,17 +318,39 @@ export interface SceneDepthOfField {
     bokehScale: number;
     focusRange: number;
 }
-/** Overlay/stylization gimmicks, each independently switchable. */
-export interface SceneStylize {
-    pixelate: {
-        enabled: boolean;
-        granularity: number;
-    };
-    glitch: {
-        enabled: boolean;
-    };
+/** Broadcast-style glitch bursts: slice tears, RGB split, block corruption, analog noise. */
+export interface SceneGlitch {
+    enabled: boolean;
+    /** Overall strength (0 to 2). */
+    intensity: number;
+    /** How fast the glitch pattern mutates. 1 re-rolls the tear 24 times per second. */
+    speed: number;
+    /** Seconds between bursts. 0 keeps the glitch running constantly. */
+    interval: number;
+    /** How long each burst lasts, in seconds. */
+    duration: number;
+    /** Horizontal slices the tear snaps to. Lower is chunkier. */
+    slices: number;
+    /** How far torn slices shift sideways, in output pixels. */
+    shift: number;
+    /** Chromatic RGB split during bursts, in output pixels. */
+    rgbShift: number;
+    /** Amount of corrupted block artifacts during bursts (0 to 1). */
+    blocks: number;
+    /** Analog noise and scanline flicker during bursts (0 to 1). */
+    noise: number;
+}
+/** Mosaic over the frame. `granularity` is pixels per block. */
+export interface ScenePixelate {
+    enabled: boolean;
+    granularity: number;
 }
-/** Post-processing over the rendered 3D frame. Everything off skips the effect chain entirely. */
+/**
+ * Post-processing over the rendered 3D frame. Everything off skips the effect
+ * chain entirely. Deliberately flat: every toggle-plus-numbers effect sits at
+ * the top level so tooling (defaults, healing, editors) can walk the effect
+ * registry generically. Grouping is a panel concern, not a data one.
+ */
 export interface SceneEffects {
     toneMapping: SceneToneMapping;
     /** Scene brightness multiplied in before the tone curve; 1 is neutral. Works in every mode, including `none`. */
@@ -330,7 +362,8 @@ export interface SceneEffects {
     grain: SceneFilmGrain;
     lut: SceneLut;
     dof: SceneDepthOfField;
-    stylize: SceneStylize;
+    pixelate: ScenePixelate;
+    glitch: SceneGlitch;
 }
 /**
  * Image-based lighting for the 3D stage: an environment map, whether to show it
@@ -405,11 +438,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/dist/types.js

@@ -1,6 +1,12 @@
 // The API's data model: the entity shapes that requests, responses, and events
 // carry. Structural mirrors of the app's scene/settings models, minus anything
 // filesystem-shaped — model refs are sanitized to ids, never directories.
+/**
+ * Per-light shadow tier. `off` is the old `castShadow: false`; the rest raise
+ * shadow-map resolution. A point light pays 6 cube faces for the same tier a
+ * directional light covers with one map, so it gets the smaller of the pair.
+ */
+export const SHADOW_QUALITY_LEVELS = ['off', 'low', 'medium', 'high', 'extra'];
 export const EFFECTS_QUALITY_LEVELS = ['low', 'medium', 'high'];
 /**
  * Accepted values for `performance.fpsLimit`; 0 = unlimited. Anything else is snapped

package/package.json

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