@laplace.live/persona-sdk 0.18.0 → 1.0.0

package/dist/effects.js

@@ -1,6 +0,0 @@
-// The custom-effect authoring contract: what an effect module receives, what it
-// returns, and (re-exported) the manifest shape naming its params. Everything
-// touching three is type-only — the desktop hands the runtime to the module's
-// factory, because a module loaded from `persona://` can import nothing.
-// Typechecking against this entry needs `@types/three` (optional peer).
-export * from "./values/custom-effect.js";

package/dist/values/custom-effect.d.ts

@@ -1,44 +0,0 @@
-/** How wide a manifest may open a slider; keeps a typo'd range from making one unusable. */
-export declare const CUSTOM_EFFECT_PARAM_LIMIT = 1000000;
-/** Enabled custom effects one scene may compose — each costs a full-frame RTT. Disabled entries are uncapped. */
-export declare const CUSTOM_EFFECTS_MAX = 8;
-/** Params per effect. Past this the panel section stops being navigable. */
-export declare const CUSTOM_EFFECT_PARAM_MAX = 32;
-export type CustomEffectParamKind = 'number' | 'boolean' | 'color';
-/** One author-declared control. `kind` picks the panel widget and the healing rule. */
-export interface CustomEffectParam {
-    kind: CustomEffectParamKind;
-    /** Slider/field label. Author-supplied, so never translated. */
-    label: string;
-    /** Numbers: the clamp range and readout. Booleans and colors ignore these. */
-    default: number | boolean | string;
-    min?: number;
-    max?: number;
-    step?: number;
-    digits?: number;
-    unit?: string;
-}
-/** A validated `manifest.json`. */
-export interface CustomEffectManifest {
-    name: string;
-    /** Author-declared, shown in the panel's detail row. */
-    version?: string;
-    author?: string;
-    description?: string;
-    params: Record<string, CustomEffectParam>;
-}
-export declare function isCustomEffectSlug(v: unknown): v is string;
-/**
- * Validate a parsed `manifest.json`. Null when it carries no usable name —
- * everything else degrades (a bad param is dropped, not fatal), because a
- * half-typed manifest should still show the author what already works.
- */
-export declare function parseCustomEffectManifest(raw: unknown): CustomEffectManifest | null;
-/** Every declared param at its default — the params half of a fresh scene entry. */
-export declare function defaultCustomEffectParams(manifest: CustomEffectManifest): Record<string, number | boolean | string>;
-/**
- * Clamp saved params to the manifest that is installed now. Unknown keys are
- * kept: an author mid-edit who renames a param back should not find the value
- * gone, and a param costs nothing until the module reads it.
- */
-export declare function healCustomEffectParams(raw: unknown, manifest: CustomEffectManifest | null): Record<string, number | boolean | string>;

package/dist/values/custom-effect.js

@@ -1,136 +0,0 @@
-// User-authored effects: the manifest contract and its validator.
-//
-// An effect folder holds `manifest.json` (plain data — this file's shape) and
-// `effect.js` (a TSL builder the stage worker evaluates). The split is what lets
-// main heal a scene's saved params without ever running author code: only the
-// worker imports the module, and it is the sole place third-party JS runs.
-//
-// Params mirror EffectParamSpec so the panel renders both kinds of effect with
-// the same sliders — but these arrive at runtime from disk, so everything here
-// validates rather than trusting the type.
-import { finiteOr, isFiniteNumber, isRecord, nonEmptyString } from "./guards.js";
-import { hexColorOr } from "./limits.js";
-/** How wide a manifest may open a slider; keeps a typo'd range from making one unusable. */
-export const CUSTOM_EFFECT_PARAM_LIMIT = 1e6;
-/** Enabled custom effects one scene may compose — each costs a full-frame RTT. Disabled entries are uncapped. */
-export const CUSTOM_EFFECTS_MAX = 8;
-/** Params per effect. Past this the panel section stops being navigable. */
-export const CUSTOM_EFFECT_PARAM_MAX = 32;
-/** Folder-name rule: lowercase, dash-separated. Also the on-disk path segment, so no dots or slashes. */
-const SLUG_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
-export function isCustomEffectSlug(v) {
-    return typeof v === 'string' && SLUG_RE.test(v);
-}
-function bounded(v) {
-    return Math.min(CUSTOM_EFFECT_PARAM_LIMIT, Math.max(-CUSTOM_EFFECT_PARAM_LIMIT, v));
-}
-function parseParam(raw) {
-    if (!isRecord(raw))
-        return null;
-    const label = nonEmptyString(raw.label);
-    if (label === null)
-        return null;
-    if (raw.kind === 'boolean')
-        return { kind: 'boolean', label, default: raw.default === true };
-    if (raw.kind === 'color')
-        return { kind: 'color', label, default: hexColorOr(raw.default, '#ffffff') };
-    // Numbers are the default kind: an omitted or unknown `kind` is far more often
-    // a slider the author forgot to tag than a control they meant to drop.
-    // Both ends clamp into ±LIMIT before ordering, or a range wholly past the
-    // limit would keep one end beyond it.
-    const lo = bounded(finiteOr(raw.min, 0));
-    const hi = bounded(finiteOr(raw.max, 1));
-    // An inverted or empty range would leave a slider that cannot move; widen to the default's own value.
-    const min = Math.min(lo, hi);
-    const max = Math.max(lo, hi);
-    const def = Math.min(max, Math.max(min, finiteOr(raw.default, min)));
-    const step = Math.min(max - min || 1, Math.abs(finiteOr(raw.step, 0.01)) || 0.01);
-    return {
-        kind: 'number',
-        label,
-        default: def,
-        min,
-        max,
-        step,
-        ...(isFiniteNumber(raw.digits) && { digits: Math.min(6, Math.max(0, Math.trunc(raw.digits))) }),
-        ...(typeof raw.unit === 'string' && raw.unit !== '' && { unit: raw.unit.slice(0, 8) }),
-    };
-}
-/**
- * Validate a parsed `manifest.json`. Null when it carries no usable name —
- * everything else degrades (a bad param is dropped, not fatal), because a
- * half-typed manifest should still show the author what already works.
- */
-export function parseCustomEffectManifest(raw) {
-    if (!isRecord(raw))
-        return null;
-    const name = nonEmptyString(raw.name);
-    if (name === null)
-        return null;
-    const params = {};
-    if (isRecord(raw.params)) {
-        for (const [key, value] of Object.entries(raw.params)) {
-            if (Object.keys(params).length >= CUSTOM_EFFECT_PARAM_MAX)
-                break;
-            // The key is a JS identifier on the uniforms object the module builds; a
-            // key it cannot name would silently never receive its value.
-            if (!/^[A-Za-z_$][\w$]*$/.test(key))
-                continue;
-            const param = parseParam(value);
-            if (param)
-                params[key] = param;
-        }
-    }
-    return {
-        name: name.slice(0, 64),
-        params,
-        ...(typeof raw.version === 'string' && raw.version !== '' && { version: raw.version.slice(0, 32) }),
-        ...(typeof raw.author === 'string' && raw.author !== '' && { author: raw.author.slice(0, 64) }),
-        ...(typeof raw.description === 'string' &&
-            raw.description !== '' && { description: raw.description.slice(0, 280) }),
-    };
-}
-/** Every declared param at its default — the params half of a fresh scene entry. */
-export function defaultCustomEffectParams(manifest) {
-    const out = {};
-    for (const [key, param] of Object.entries(manifest.params))
-        out[key] = param.default;
-    return out;
-}
-/** A primitive a saved param may hold; non-finite numbers are junk, not tuning. */
-function isParamValue(v) {
-    return isFiniteNumber(v) || typeof v === 'boolean' || typeof v === 'string';
-}
-/**
- * Clamp saved params to the manifest that is installed now. Unknown keys are
- * kept: an author mid-edit who renames a param back should not find the value
- * gone, and a param costs nothing until the module reads it.
- */
-export function healCustomEffectParams(raw, manifest) {
-    const src = isRecord(raw) ? raw : {};
-    const out = {};
-    for (const [key, value] of Object.entries(src)) {
-        const spec = manifest?.params[key];
-        if (!spec) {
-            // No spec to clamp against — an unknown key, or no manifest at all (effect
-            // not installed on this machine); keeping primitives is what lets a
-            // reinstall restore the user's tuning.
-            if (isParamValue(value))
-                out[key] = value;
-            continue;
-        }
-        if (spec.kind === 'boolean')
-            out[key] = typeof value === 'boolean' ? value : spec.default === true;
-        else if (spec.kind === 'color')
-            out[key] = hexColorOr(value, String(spec.default));
-        else {
-            const lo = spec.min ?? 0;
-            const hi = spec.max ?? 1;
-            out[key] = Math.min(hi, Math.max(lo, finiteOr(value, Number(spec.default))));
-        }
-    }
-    if (manifest)
-        for (const [key, spec] of Object.entries(manifest.params))
-            out[key] ??= spec.default;
-    return out;
-}