@melite/formats 0.1.4-alpha → 0.1.5-pre-alpha

package/README.md

@@ -0,0 +1,38 @@
+---
+description: Pure browser-side media codecs and math — NPZ, skins, poses, masks, image metadata — fetch-free by law.
+kind: package-library
+---
+
+# formats
+
+`@melite/formats` holds the browser-side media codecs and math the studios share: motion files, character skins, pose codecs, mask prep, image metadata. Pure transforms by law — no render loops, no server coupling; `three` types appear only where geometry demands.
+
+## Contract
+
+The package root re-exports the leaves; each is also a declared subpath. The manifest also declares the standard `./package.json` re-export.
+
+- Motion — `./npz` (the minimal NPZ reader), `./motionNpz` (the motion card's client-side engine), `./motionEnvelope` (audio-reactive amplitude), `./motionConstraints` (the constraint snapshot core), and `./keyframeExtract` (anchor-frame picks).
+- Skins and rig — `./somaSkin` (neutral SOMA-77 linear-blend skinning), `./glbSkin` (a SOMAX-rigged GLB onto the same substrate), `./poserSkin` (the shared bind-mesh), `./handPose` (SOMA-77 finger presets), and `./glbLoad` (the one DRACO-configured GLTFLoader).
+- Pose — `./poseCodec` (byte codecs and bone topology), `./poseTransforms` (COCO-18 transforms), `./openPoseCanvas` (the stick-figure renderer), `./textToPose` (the poser client), `./bodyPresets` (labeled archetype presets), and `./downloads` (artifact export triggers).
+- Media plumbing — `./pngMeta` and `./pngMetaInfo` (PNG tEXt chunk embed and read), `./b64`, `./extractVideoFrame`, `./captionSplitter`, `./promptTags`, `./renderSnapshot` (the one-frame scene-to-JPEG snapshotter), `./psdExport` (the layered PSD writer), `./maskPrep`, `./cardMutations` (the declarative card-mutation gate), `./readFile` (the one slot-attach read), and `./uploadToEstate` (the one browser-file to estate-path rail).
+
+## Model Experience
+
+### Request context and condition
+
+#### What the model sees
+
+The codecs contribute nothing. `./textToPose` submits a caller's prompt segments to the poser backend for downstream pose generation; `./uploadToEstate` moves bytes the user chose.
+
+#### Token effect
+
+Conditional — only the text-to-pose path sends prompts for downstream generation; the codecs and the upload rail cost nothing.
+
+#### KV Cache effect
+
+Independent — the poser calls are one-shot jobs, not conversation turns.
+
+## Known Limitations and Deferred Work
+
+- **Minimal format coverage by design** — the NPZ reader and the PSD writer cover the estate's own subset (8-bit RGB layers); broader format support lands only when a surface needs it.
+- **No `./invariant` companion** — the codecs are deterministic pure functions over their inputs; there is no cross-package runtime relationship to assert.

package/lib/index.d.ts

@@ -21,6 +21,5 @@ export * from "./motionEnvelope.js";
 export * from "./extractVideoFrame.js";
 export * from "./keyframeExtract.js";
 export * from "./handPose.js";
-export * from "./capabilityCards.js";
 export * from "./cardMutations.js";
 //# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -21,6 +21,5 @@ export * from "./motionEnvelope.js";
 export * from "./extractVideoFrame.js";
 export * from "./keyframeExtract.js";
 export * from "./handPose.js";
-export * from "./capabilityCards.js";
 export * from "./cardMutations.js";
 //# sourceMappingURL=index.js.map

package/lib/poseTransforms.d.ts

@@ -51,13 +51,6 @@ export declare function renderCustomPose(keypoints: Keypoints, opts?: {
     width?: number;
     height?: number;
 }): Promise<Blob>;
-/**
- * Convert a Blob to a base64 data URL — for saving to the asset store
- * (which expects data URLs, not object URLs, for persistence).
- * Delegates to the shared readAsDataURL (@melite/ui SlotSquare — the
- * ONE read path every slot-shaped attach uses).
- */
-export declare function blobToDataUrl(blob: Blob): Promise<string>;
 /**
  * Convert 2D flat COCO-18 keypoints to approximate 3D positions.
  *

package/lib/poseTransforms.js

@@ -2,7 +2,7 @@
  * Pose Studio — keypoint transform utilities.
  *
  * COCO-18 keypoints: 18 joints × (x, y, confidence) = 54 numbers in a flat
- * array. This is the same format DWPose outputs (see media/workflows/utils/dwpose.py)
+ * array. This is the same COCO-18 format an upstream DWPose estimator outputs
  * and the same format the /poser/* backend endpoints accept.
  *
  * The Pose Studio UI lets the user pick a base preset, then tweak it with
@@ -14,7 +14,6 @@
  * have smaller X values than left-side ones).
  */
 import { apiFetch } from "@melite/catalog";
-import { readAsDataURL } from "./readFile.js";
 // ── COCO-18 keypoint indices ─────────────────────────────────────────────
 export const KP = {
     NOSE: 0, NECK: 1,
@@ -165,15 +164,6 @@ export async function renderCustomPose(keypoints, opts = {}) {
     }
     return res.blob();
 }
-/**
- * Convert a Blob to a base64 data URL — for saving to the asset store
- * (which expects data URLs, not object URLs, for persistence).
- * Delegates to the shared readAsDataURL (@melite/ui SlotSquare — the
- * ONE read path every slot-shaped attach uses).
- */
-export function blobToDataUrl(blob) {
-    return readAsDataURL(blob);
-}
 // ── 2D → approximate 3D projection ──────────────────────────────────────────
 /** SOMA coordinate space constants. */
 const SOMA_SCALE = 0.6; // maps 1024px width to ~0.6 SOMA units (hip-to-hip)

package/lib/poserSkin.js

@@ -22,7 +22,11 @@ import { apiFetch } from "@melite/catalog";
 // entry Pose Studio needs, zero network). All shaped meshes share SOMA's
 // 18056-vertex layout; the cache key incorporates identity_model +
 // coeffs + local_changes + custom_targets + preview_pose so identical
-// shapes hit the cache on re-fetch.
+// shapes hit the cache on re-fetch. BOUNDED (the registry-growth law):
+// one entry is a full mesh (megabytes), a slider drag mints a
+// signature per stop, so an unbounded module Map would grow with the
+// session — LRU at MESH_CACHE_CAP, the oldest insertion pruned.
+const MESH_CACHE_CAP = 16;
 const _meshCache = new Map();
 export async function fetchBindMesh(query = {}) {
     const { identityModel, identityCoeffs, localChanges, previewPose, customTargets, } = query;
@@ -51,8 +55,12 @@ export async function fetchBindMesh(query = {}) {
     const poseSig = previewPose && previewPose !== "tpose" ? previewPose : null;
     const cacheKey = [key, coeffsSig, lcEntries, ctEntries, poseSig].filter(Boolean).join("|");
     const cached = _meshCache.get(cacheKey);
-    if (cached)
+    if (cached) {
+        // LRU, not FIFO-of-birth: a re-read refreshes the insertion
+        _meshCache.delete(cacheKey);
+        _meshCache.set(cacheKey, cached);
         return cached;
+    }
     const posePayload = poseSig ? { preview_pose: poseSig } : {};
     let data;
     if (coeffsSig || lcEntries || ctEntries) {
@@ -87,6 +95,13 @@ export async function fetchBindMesh(query = {}) {
             throw new Error(`Failed to fetch mesh (${key}): ${res.status}`);
         data = (await res.json());
     }
+    if (_meshCache.size >= MESH_CACHE_CAP) {
+        // the map is non-empty at cap — take the OLDEST insertion
+        for (const oldest of _meshCache.keys()) {
+            _meshCache.delete(oldest);
+            break;
+        }
+    }
     _meshCache.set(cacheKey, data);
     return data;
 }

package/lib/textToPose.d.ts

@@ -161,7 +161,7 @@ export declare function submitTextToPose(req: TextToPoseRequest): Promise<Submit
 /**
  * Poll job status once. Returns the current status + result if completed.
  */
-export declare function pollJob(jobId: string): Promise<JobStatusResponse>;
+export declare function pollJob(jobId: string, signal?: AbortSignal): Promise<JobStatusResponse>;
 /**
  * Wait for a job to reach a terminal state (completed/failed/cancelled).
  * Polls every `intervalMs` until `timeoutMs`.
@@ -172,6 +172,11 @@ export declare function waitForJob(jobId: string, opts?: {
     intervalMs?: number;
     timeoutMs?: number;
     onUpdate?: (status: JobStatusResponse) => void;
+    
+
+
+
+    signal?: AbortSignal;
 }): Promise<TextToPoseResult>;
 export declare function cancelJob(jobId: string): Promise<void>;
 /**
@@ -182,6 +187,7 @@ export declare function generatePose(req: TextToPoseRequest, opts?: {
     intervalMs?: number;
     timeoutMs?: number;
     onUpdate?: (status: JobStatusResponse) => void;
+    signal?: AbortSignal;
 }): Promise<TextToPoseResult>;
 export declare function listPoseCache(): Promise<CacheListResponse>;
 export declare function deletePoseCacheEntry(hash: string): Promise<void>;

package/lib/textToPose.js

@@ -80,8 +80,8 @@ export async function submitTextToPose(req) {
 /**
  * Poll job status once. Returns the current status + result if completed.
  */
-export async function pollJob(jobId) {
-    const res = await apiFetch(`/poser/text-to-pose/jobs/${jobId}`);
+export async function pollJob(jobId, signal) {
+    const res = await apiFetch(`/poser/text-to-pose/jobs/${jobId}`, { signal });
     if (res.status === 404) {
         throw new Error(`Job ${jobId} not found`);
     }
@@ -106,8 +106,11 @@ export async function waitForJob(jobId, opts = {}) {
     const interval = opts.intervalMs ?? 500;
     const timeout = opts.timeoutMs ?? 120_000; // 2 min default (inference is 15-30s)
     const deadline = Date.now() + timeout;
+    const signal = opts.signal;
     while (Date.now() < deadline) {
-        const status = await pollJob(jobId);
+        if (signal?.aborted)
+            throw new DOMException("Aborted", "AbortError");
+        const status = await pollJob(jobId, signal);
         opts.onUpdate?.(status);
         if (status.status === "completed" && status.result) {
             return status.result;
@@ -118,7 +121,7 @@ export async function waitForJob(jobId, opts = {}) {
         if (status.status === "cancelled") {
             throw new Error("Job was cancelled");
         }
-        await sleep(interval);
+        await sleep(interval, signal);
     }
     throw new Error(`Job ${jobId} timed out after ${timeout}ms`);
 }

package/package.json

@@ -3,9 +3,9 @@
   "license": "SSPL-1.0",
   "type": "module",
   "dependencies": {
-    "@melite/catalog": "0.1.4-alpha",
-    "@melite/contracts": "0.1.4-alpha",
-    "@melite/three-client": "0.1.4-alpha"
+    "@melite/catalog": "0.1.5-pre-alpha",
+    "@melite/contracts": "0.1.5-pre-alpha",
+    "@melite/three-client": "0.1.5-pre-alpha"
   },
   "exports": {
     "./b64": {
@@ -16,10 +16,6 @@
       "types": "./lib/bodyPresets.d.ts",
       "default": "./lib/bodyPresets.js"
     },
-    "./capabilityCards": {
-      "types": "./lib/capabilityCards.d.ts",
-      "default": "./lib/capabilityCards.js"
-    },
     "./captionSplitter": {
       "types": "./lib/captionSplitter.d.ts",
       "default": "./lib/captionSplitter.js"
@@ -37,10 +33,12 @@
       "default": "./lib/extractVideoFrame.js"
     },
     "./glbLoad": {
-      "types": "./lib/glbLoad.d.ts"
+      "types": "./lib/glbLoad.d.ts",
+      "default": "./lib/glbLoad.js"
     },
     "./glbSkin": {
-      "types": "./lib/glbSkin.d.ts"
+      "types": "./lib/glbSkin.d.ts",
+      "default": "./lib/glbSkin.js"
     },
     "./handPose": {
       "types": "./lib/handPose.d.ts",
@@ -63,7 +61,8 @@
       "default": "./lib/motionEnvelope.js"
     },
     "./motionNpz": {
-      "types": "./lib/motionNpz.d.ts"
+      "types": "./lib/motionNpz.d.ts",
+      "default": "./lib/motionNpz.js"
     },
     "./npz": {
       "types": "./lib/npz.d.ts",
@@ -115,17 +114,19 @@
       "default": "./lib/textToPose.js"
     },
     "./renderSnapshot": {
-      "types": "./lib/renderSnapshot.d.ts"
+      "types": "./lib/renderSnapshot.d.ts",
+      "default": "./lib/renderSnapshot.js"
     },
     "./somaSkin": {
       "types": "./lib/somaSkin.d.ts",
       "default": "./lib/somaSkin.js"
     },
     ".": {
-      "types": "./lib/index.d.ts"
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
     }
   },
-  "version": "0.1.4-alpha",
+  "version": "0.1.5-pre-alpha",
   "types": "./src/index.ts",
   "devDependencies": {
     "@types/node": "^22.20.0",

package/lib/capabilityCards.d.ts

@@ -1,54 +0,0 @@
-import { type CapabilityEntry, type CapabilityRoute, type Catalog, type FamilyEntry } from "@melite/catalog";
-import type { CardGenre } from "@melite/contracts";
-/** A card ready to land on the canvas (what onPick hands the store).
- *
- *  ``kind`` is optional — capabilities/families always produce
- *  ``"generation"`` (the default), so the existing helpers don't set it
- *  and the canvas defaults to "generation". The Input / Media Prep tile
- *  sets ``kind: "input"`` so the canvas routes the stage through the
- *  doc-driven input family (POST /v1/flows/start, 1-step inline
- *  doc) — NOT the generation wire. This is rule 4: the shape carries
- *  the kind, so pick → addStage never silently misroutes. */
-export interface PickedCard {
-    service: string;
-    title: string;
-    genre?: CardGenre;
-    params: Record<string, unknown>;
-    kind?: string;
-}
-/**
- * Seed params for a route: the backend-computed defaults + an empty prompt
- * ONLY when the model's form actually serves a prompt field
- * (prompt_in_form — backend-computed from the builder schema) + a null
- * seed for EVERY input slot the model declares (input_slots — multi-slot
- * forms like edit's three images / video's two frames get one null per
- * slot, so the card renders all its squares from the start). Unknown
- * prompt_in_form → seed (old behavior).
- */
-export declare function seededParams(cat: Catalog | null, route: string, base?: Record<string, unknown>): Record<string, unknown>;
-/**
- * Resolve a capability tile (+ optional route override) to a card. The
- * default tile click uses cap.resolved; the tile's model switcher passes a
- * different CapabilityRoute — same capability intent, model switched
- * underneath. The route's params are backend-precomputed (capability
- * default_params as fallback, model's own defaults winning), so switching
- * the model correctly swaps the per-model recipe (steps / cfg / sampler).
- */
-export declare function capabilityToCard(cat: Catalog | null, cap: CapabilityEntry, route: CapabilityRoute): PickedCard;
-/** Resolve a specific family entry (the "All models" list) to a card. */
-export declare function familyEntryToCard(cat: Catalog | null, familyId: string, fam: FamilyEntry): PickedCard;
-export declare const CAPABILITY_DRAG_MIME = "application/tech-noir-capability";
-/** What a capability tile writes to the drag data store. Carries the fully
- *  resolved card (service + title + params + kind) so the drop target can
- *  apply it WITHOUT a catalog lookup — the sidebar already paid that cost
- *  via capabilityToCard. ``capId`` is diagnostics-only (not read by the
- *  drop target; useful for e2e traces). */
-export type CapabilityDropPayload = PickedCard & {
-    capId?: string;
-};
-/** Serialize a picked card onto the drag data store. */
-export declare function capabilityDragPayload(capId: string, card: PickedCard): string;
-/** Parse the capability MIME off a drop event. null = absent or malformed
- *  (the drop target falls through to the asset/file path). */
-export declare function parseCapabilityDrop(raw: string): CapabilityDropPayload | null;
-//# sourceMappingURL=capabilityCards.d.ts.map

package/lib/capabilityCards.js

@@ -1,127 +0,0 @@
-// capabilityCards — the ONE capability→card derivation path.
-//
-// A capability tile (Generate / Edit / Upscale / ...) resolves to a card
-// descriptor: the backend-precomputed default model route + merged params
-// (capabilities.<id>.resolved). This module is the single implementation —
-// the ServicePicker dialog AND the Library's right sidebar (LibrarySidebar)
-// both derive their "what lands on the canvas" from these helpers, so a
-// catalog or schema change cannot make the two surfaces drift.
-//
-
-//   • an empty prompt is seeded ONLY when the model's form actually serves
-//     a prompt field (prompt_in_form — backend-computed from the builder
-//     schema); a prompt-less card (upscale) must never carry one
-//   • a null input slot is seeded when the model's schema has an input
-//     (the card modal renders the attach control for it)
-import { familyGenre, narrowGenre } from "@melite/catalog";
-/**
- * Seed params for a route: the backend-computed defaults + an empty prompt
- * ONLY when the model's form actually serves a prompt field
- * (prompt_in_form — backend-computed from the builder schema) + a null
- * seed for EVERY input slot the model declares (input_slots — multi-slot
- * forms like edit's three images / video's two frames get one null per
- * slot, so the card renders all its squares from the start). Unknown
- * prompt_in_form → seed (old behavior).
- */
-export function seededParams(cat, route, base = {}) {
-    const model = cat?.models[route];
-    const slots = model?.input_slots?.length
-        ? model.input_slots
-        : (model?.input ? [model.input] : []);
-    const hasPrompt = model?.prompt_in_form ?? true; // unknown → seed (old behavior)
-    return {
-        ...base,
-        ...(hasPrompt ? { prompt: "" } : {}),
-        ...(slots.length ? Object.fromEntries(slots.map((k) => [k, null])) : {}),
-    };
-}
-/**
- * Resolve a capability tile (+ optional route override) to a card. The
- * default tile click uses cap.resolved; the tile's model switcher passes a
- * different CapabilityRoute — same capability intent, model switched
- * underneath. The route's params are backend-precomputed (capability
- * default_params as fallback, model's own defaults winning), so switching
- * the model correctly swaps the per-model recipe (steps / cfg / sampler).
- */
-export function capabilityToCard(cat, cap, route) {
-    // Model-less capabilities (kind:"input") carry their params VERBATIM — no
-    // prompt/slot seeding. Those are generation-form concerns (prompt_in_form,
-    // input_slots); input's editor is the fixed-field InputCardEditor, which
-    // owns crop/scale/trim/volume/mask. Seeding a prompt here would give the
-    
-    // regression, generalized). The kind rides through to PickedCard so the
-    // canvas routes the stage through executeInput, not executeGeneration.
-    const isModelLess = cap.kind !== undefined && cap.kind !== "generation";
-    return {
-        service: route.model,
-        title: cap.label,
-        genre: genreForRoute(cat, route.model),
-        params: isModelLess ? { ...route.params } : seededParams(cat, route.model, route.params),
-        ...(isModelLess ? { kind: cap.kind } : {}),
-    };
-}
-/** Resolve a specific family entry (the "All models" list) to a card. */
-export function familyEntryToCard(cat, familyId, fam) {
-    // Route resolution — the SAME chain the backend's capability resolver
-    // and familiesForForm use: the catalog-declared ``default_model`` (when
-    // it is a member), else the member whose key equals the family id, else
-    // the FIRST member. NEVER the bare familyId: mask_studio's family id
-    // and model key differ (mask_studio vs mask-studio), and a family-id
-    // service is a PHANTOM ROUTE — no models[] entry, no familyGenre, and
-    // no studio registry match (the "mask studio does not appear" bug,
-    
-    // card zoomed as a plain form card). The catalog now declares
-    // default_model for every id-divergent family; this chain is the
-    // backstop for the next one.
-    const declared = fam.default_model;
-    const members = Object.entries(cat?.models ?? {})
-        .filter(([, m]) => m.family === familyId)
-        .map(([k]) => k);
-    const route = (declared && members.includes(declared) ? declared : undefined) ??
-        members.find((k) => k === familyId) ??
-        members[0] ??
-        familyId;
-    return {
-        service: route,
-        title: fam.label ?? familyId,
-        genre: narrowGenre(fam.genre) ?? genreForRoute(cat, route),
-        params: seededParams(cat, route, cat?.models[route]?.defaults ?? {}),
-    };
-}
-/** Genre for a model route — the catalog's familyGenre derivation. */
-function genreForRoute(cat, route) {
-    return cat ? familyGenre(route, cat) : undefined;
-}
-
-// A capability tile in the LibrarySidebar is DRAGGABLE onto a card in the
-// canvas — "clicking and dragging from the right sidebar onto the middle
-// part should populate the card". The drop REPURPOSES the target card: its
-// service + params + title become the dragged capability's resolved card
-// (the same shape a click would `addStage`, applied to an EXISTING stage).
-//
-// The MIME is deliberately distinct from `application/tech-noir-asset`
-// (AppSidebar's asset drag) so a card's drop handler can tell "populate
-// this card's identity" (capability) from "attach an asset to a slot"
-// (asset) — one drop target, two contracts, no ambiguity.
-export const CAPABILITY_DRAG_MIME = "application/tech-noir-capability";
-/** Serialize a picked card onto the drag data store. */
-export function capabilityDragPayload(capId, card) {
-    return JSON.stringify({ ...card, capId });
-}
-/** Parse the capability MIME off a drop event. null = absent or malformed
- *  (the drop target falls through to the asset/file path). */
-export function parseCapabilityDrop(raw) {
-    if (!raw)
-        return null;
-    try {
-        const p = JSON.parse(raw);
-        if (typeof p.service === "string" && typeof p.title === "string" && p.params && typeof p.params === "object") {
-            return p;
-        }
-        return null;
-    }
-    catch { /* not our payload — the JSON probe answers absent (row 28) */
-        return null;
-    }
-}
-//# sourceMappingURL=capabilityCards.js.map