@happyvertical/smrt-images 0.55.9 → 0.55.15

package/dist/manifest.json

@@ -2,7 +2,7 @@
   "version": "1.0.0",
   "timestamp": 0,
   "packageName": "@happyvertical/smrt-images",
-  "packageVersion": "0.55.9",
+  "packageVersion": "0.55.15",
   "objects": {
     "@happyvertical/smrt-images:Image": {
       "name": "image",
@@ -39,68 +39,128 @@
         },
         "name": {
           "type": "text",
-          "required": false
+          "required": false,
+          "description": "A recognizable name for this file or media item.",
+          "_meta": {
+            "description": "A recognizable name for this file or media item."
+          }
         },
         "sourceUri": {
           "type": "text",
-          "required": false
+          "required": false,
+          "description": "Where the original file is stored or can be retrieved.",
+          "_meta": {
+            "description": "Where the original file is stored or can be retrieved."
+          }
         },
         "mimeType": {
           "type": "text",
-          "required": false
+          "required": false,
+          "description": "The file format, such as image/jpeg or application/pdf.",
+          "_meta": {
+            "description": "The file format, such as image/jpeg or application/pdf."
+          }
         },
         "description": {
           "type": "text",
-          "required": false
+          "required": false,
+          "description": "Explain what the file contains and when it should be used.",
+          "_meta": {
+            "description": "Explain what the file contains and when it should be used."
+          }
         },
         "metadata": {
           "type": "text",
-          "required": false
+          "required": false,
+          "description": "Additional details recorded while processing this file.",
+          "_meta": {
+            "description": "Additional details recorded while processing this file."
+          }
         },
         "version": {
           "type": "integer",
           "required": true,
-          "default": 1
+          "default": 1,
+          "description": "The revision number of this file in its version history.",
+          "_meta": {
+            "description": "The revision number of this file in its version history."
+          }
         },
         "primaryVersionId": {
           "type": "foreignKey",
           "required": false,
-          "related": "Asset"
+          "related": "Asset",
+          "description": "The first version of this file, linking its revision history.",
+          "_meta": {
+            "description": "The first version of this file, linking its revision history."
+          }
         },
         "typeSlug": {
           "type": "text",
-          "required": false
+          "required": false,
+          "description": "The category of asset, such as an image, video, or document.",
+          "_meta": {
+            "description": "The category of asset, such as an image, video, or document."
+          }
         },
         "statusSlug": {
           "type": "text",
-          "required": false
+          "required": false,
+          "description": "The stage of this asset, such as draft, published, or archived.",
+          "_meta": {
+            "description": "The stage of this asset, such as draft, published, or archived."
+          }
         },
         "ownerProfileId": {
           "type": "crossPackageRef",
           "required": false,
-          "related": "@happyvertical/smrt-profiles:Profile"
+          "related": "@happyvertical/smrt-profiles:Profile",
+          "description": "The person or organization responsible for this asset.",
+          "_meta": {
+            "description": "The person or organization responsible for this asset."
+          }
         },
         "sourceAssetId": {
           "type": "foreignKey",
           "required": false,
-          "related": "Asset"
+          "related": "Asset",
+          "description": "The original asset used to produce this file or variation.",
+          "_meta": {
+            "description": "The original asset used to produce this file or variation."
+          }
         },
         "folderId": {
           "type": "foreignKey",
           "required": false,
-          "related": "Folder"
+          "related": "Folder",
+          "description": "The folder that organizes this file in the asset library.",
+          "_meta": {
+            "description": "The folder that organizes this file in the asset library."
+          }
         },
         "sourceType": {
           "type": "text",
-          "required": false
+          "required": false,
+          "description": "The service or source from which this file was obtained.",
+          "_meta": {
+            "description": "The service or source from which this file was obtained."
+          }
         },
         "externalId": {
           "type": "text",
-          "required": false
+          "required": false,
+          "description": "The reference used to identify this file at its original source.",
+          "_meta": {
+            "description": "The reference used to identify this file at its original source."
+          }
         },
         "externalRefs": {
           "type": "text",
-          "required": false
+          "required": false,
+          "description": "References that connect this file to copies held by other services.",
+          "_meta": {
+            "description": "References that connect this file to copies held by other services."
+          }
         },
         "createdAt": {
           "type": "text",
@@ -916,6 +976,7 @@
   "smrtDependencies": [
     "@happyvertical/smrt-assets",
     "@happyvertical/smrt-core",
+    "@happyvertical/smrt-profiles",
     "@happyvertical/smrt-prompts",
     "@happyvertical/smrt-tenancy"
   ],

package/dist/photo-cutout-coordinate-guide.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Produces a transient grid-overlay copy for a vision request. The source
+ * image remains the asset used by the browser cutout; this guide is never
+ * saved or returned to a client.
+ */
+export declare function createPhotoCutoutCoordinateGuide(sourceDataUrl: string, width: number, height: number): Promise<string>;
+//# sourceMappingURL=photo-cutout-coordinate-guide.d.ts.map

package/dist/photo-cutout-coordinate-guide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"photo-cutout-coordinate-guide.d.ts","sourceRoot":"","sources":["../src/photo-cutout-coordinate-guide.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAsB,gCAAgC,CACpD,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAqCjB"}

package/dist/photo-cutout-profile-store.d.ts

@@ -0,0 +1,76 @@
+import { type PhotoCutoutRig } from '@happyvertical/animation';
+import type { Asset, AssetRuntimeLike } from '@happyvertical/smrt-assets';
+/** Stable rig key resolved by the host to the persisted asset bytes. */
+export declare const PHOTO_CUTOUT_PERSISTED_ASSET_REF = "character_cutout";
+export interface PhotoCutoutProfileOwner {
+    id?: string;
+    tenantId?: string | null;
+    getAssets(relationship?: string): Promise<Asset[]>;
+    addAsset(asset: Asset, relationship?: string, sortOrder?: number): Promise<void>;
+}
+export interface PhotoCutoutProfileStoreAuthorization {
+    actorProfileId: string;
+    profile: PhotoCutoutProfileOwner;
+    tenantId: string | null;
+    operation: 'load' | 'save';
+}
+export interface PhotoCutoutProfileStoreOptions {
+    runtime: AssetRuntimeLike;
+    getProfile(profileId: string): Promise<PhotoCutoutProfileOwner | null>;
+    /** The host verifies its authenticated principal and any app-specific grants. */
+    authorize(request: PhotoCutoutProfileStoreAuthorization): Promise<boolean> | boolean;
+    now?: () => Date;
+}
+export interface SavePhotoCutoutProfileSetupInput {
+    actorProfileId: string;
+    profileId: string;
+    tenantId: string | null;
+    png: Buffer;
+    rig: PhotoCutoutRig;
+    name?: string;
+}
+export interface LoadPhotoCutoutProfileSetupInput {
+    actorProfileId: string;
+    profileId: string;
+    tenantId: string | null;
+    /**
+     * A photo-cutout asset already linked to this profile. Omitting this keeps
+     * the original behavior of loading the most recently saved setup.
+     */
+    assetId?: string;
+}
+export interface PersistedPhotoCutoutSetup {
+    assetId: string;
+    rig: PhotoCutoutRig;
+    png: Buffer;
+    savedAt: string;
+}
+/** Metadata for an authorized saved setup, without reading its PNG bytes. */
+export interface SavedPhotoCutoutProfileSetup {
+    assetId: string;
+    savedAt: string;
+    name?: string;
+}
+/**
+ * Persists one profile-owned photographic character setup using the canonical
+ * AssetRuntime bytes and ProfileAsset link. Authentication stays with the host;
+ * this service refuses cross-profile and cross-tenant calls before it writes.
+ */
+export declare class PhotoCutoutProfileStore {
+    private readonly options;
+    private readonly now;
+    constructor(options: PhotoCutoutProfileStoreOptions);
+    save(input: SavePhotoCutoutProfileSetupInput): Promise<PersistedPhotoCutoutSetup>;
+    load(input: LoadPhotoCutoutProfileSetupInput): Promise<PersistedPhotoCutoutSetup | null>;
+    private loadSelected;
+    /**
+     * Lists valid, profile-linked saved setups without fetching their image
+     * bytes. Authorization deliberately follows `load`: gallery visibility is
+     * the same protected read as selecting a setup.
+     */
+    list(input: LoadPhotoCutoutProfileSetupInput): Promise<SavedPhotoCutoutProfileSetup[]>;
+    private readSaved;
+    private readLinkedCandidates;
+    private requireAuthorizedProfile;
+}
+//# sourceMappingURL=photo-cutout-profile-store.d.ts.map

package/dist/photo-cutout-profile-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"photo-cutout-profile-store.d.ts","sourceRoot":"","sources":["../src/photo-cutout-profile-store.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,cAAc,EAEpB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAK1E,wEAAwE;AACxE,eAAO,MAAM,gCAAgC,qBAAqB,CAAC;AAEnE,MAAM,WAAW,uBAAuB;IACtC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IACnD,QAAQ,CACN,KAAK,EAAE,KAAK,EACZ,YAAY,CAAC,EAAE,MAAM,EACrB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,MAAM,WAAW,oCAAoC;IACnD,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,uBAAuB,CAAC;IACjC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,8BAA8B;IAC7C,OAAO,EAAE,gBAAgB,CAAC;IAC1B,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CAAC;IACvE,iFAAiF;IACjF,SAAS,CACP,OAAO,EAAE,oCAAoC,GAC5C,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAC9B,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,gCAAgC;IAC/C,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,cAAc,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gCAAgC;IAC/C,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,cAAc,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,6EAA6E;AAC7E,MAAM,WAAW,4BAA4B;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAUD;;;;GAIG;AACH,qBAAa,uBAAuB;IAGtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAa;gBAEJ,OAAO,EAAE,8BAA8B;IAI9D,IAAI,CACR,KAAK,EAAE,gCAAgC,GACtC,OAAO,CAAC,yBAAyB,CAAC;IA4D/B,IAAI,CACR,KAAK,EAAE,gCAAgC,GACtC,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC;YAc9B,YAAY;IAe1B;;;;OAIG;IACG,IAAI,CACR,KAAK,EAAE,gCAAgC,GACtC,OAAO,CAAC,4BAA4B,EAAE,CAAC;YAW5B,SAAS;IA0BvB,OAAO,CAAC,oBAAoB;YAmBd,wBAAwB;CAqBvC"}

package/dist/photo-cutout-setup.d.ts

@@ -0,0 +1,48 @@
+import { type PhotoCutoutRig } from '@happyvertical/animation';
+/** A small, server-safe boundary for untrusted vision-model JSON. */
+export interface PhotoCutoutSetupInput {
+    assetId: string;
+    width: number;
+    height: number;
+}
+export interface FaceOutline {
+    points: Array<{
+        x: number;
+        y: number;
+    }>;
+}
+export interface MouthLandmarks {
+    mouthLeft: {
+        x: number;
+        y: number;
+    };
+    mouthRight: {
+        x: number;
+        y: number;
+    };
+    chin: {
+        x: number;
+        y: number;
+    };
+}
+/** Validate a normalized (0..1000) closed face silhouette from the vision pass. */
+export declare function parseFaceOutline(response: string | unknown): FaceOutline;
+/** Build the Canadian horizontal split from real cropped-face landmarks. */
+export declare function assembleCanadianSplitRig(input: {
+    outline: FaceOutline;
+    landmarks: MouthLandmarks;
+    width: number;
+    height: number;
+    assetId: string;
+}): PhotoCutoutRig;
+export declare function faceOutlinePrompt(): string;
+export declare function parseMouthLandmarks(response: string | unknown): MouthLandmarks;
+export declare function mouthLandmarksPrompt(): string;
+/**
+ * Parses a model response and binds every image layer to the authorized source
+ * image. The animation validator is the final geometry and bounds authority.
+ */
+export declare function parsePhotoCutoutSetup(response: string | unknown, source: PhotoCutoutSetupInput): PhotoCutoutRig;
+/** Deliberately specific instructions reduce geometry ambiguity from vision models. */
+export declare function photoCutoutSetupPrompt(source: PhotoCutoutSetupInput): string;
+//# sourceMappingURL=photo-cutout-setup.d.ts.map

package/dist/photo-cutout-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"photo-cutout-setup.d.ts","sourceRoot":"","sources":["../src/photo-cutout-setup.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EAIpB,MAAM,0BAA0B,CAAC;AAElC,qEAAqE;AACrE,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,KAAK,CAAC;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACzC;AACD,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,UAAU,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACrC,IAAI,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAChC;AAED,mFAAmF;AACnF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,GAAG,WAAW,CAgCxE;AAED,4EAA4E;AAC5E,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,OAAO,EAAE,WAAW,CAAC;IACrB,SAAS,EAAE,cAAc,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,cAAc,CAsDjB;AAED,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,GAAG,OAAO,GACzB,cAAc,CAkChB;AAED,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AASD;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,GAAG,OAAO,EAC1B,MAAM,EAAE,qBAAqB,GAC5B,cAAc,CA2ChB;AAED,uFAAuF;AACvF,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,CAI5E"}

package/dist/photo-cutout-setup.js

@@ -0,0 +1,145 @@
+import { PhotoCutoutValidationError, clipPhotoCutoutOutlineBelowLine, validatePhotoCutoutOutline, validatePhotoCutoutRig } from "@happyvertical/animation";
+//#region src/photo-cutout-setup.ts
+function parseFaceOutline(response) {
+	const points = record(typeof response === "string" ? JSON.parse(response) : response).points;
+	if (!Array.isArray(points) || points.length < 5 || points.length > 64) throw new PhotoCutoutValidationError("face outline needs 5-64 points");
+	return { points: validatePhotoCutoutOutline(points.map((point) => {
+		const p = record(point);
+		const x = p.x;
+		const y = p.y;
+		if (typeof x !== "number" || typeof y !== "number" || !Number.isFinite(x) || !Number.isFinite(y) || x < 0 || y < 0 || x > 1e3 || y > 1e3) throw new PhotoCutoutValidationError("face outline point is outside normalized bounds");
+		return {
+			x,
+			y
+		};
+	}), {
+		width: 1e3,
+		height: 1e3,
+		minPoints: 5
+	}) };
+}
+function assembleCanadianSplitRig(input) {
+	const seam = (input.landmarks.mouthLeft.y + input.landmarks.mouthRight.y) / 2;
+	const lower = clipPhotoCutoutOutlineBelowLine(input.outline.points, {
+		width: 1e3,
+		height: 1e3,
+		y: seam,
+		minPoints: 3
+	});
+	const scale = (p) => ({
+		x: p.x / 1e3 * input.width,
+		y: p.y / 1e3 * input.height
+	});
+	const head = input.outline.points.map(scale);
+	const jaw = lower.map(scale);
+	const gap = Math.max(2, Math.round((input.landmarks.chin.y - seam) / 1e3 * input.height * .36));
+	const canvasHeight = input.height + gap;
+	const pivot = scale({
+		x: (input.landmarks.mouthLeft.x + input.landmarks.mouthRight.x) / 2,
+		y: seam
+	});
+	const rig = {
+		rigKind: "photo-cutout",
+		version: 1,
+		id: "portrait",
+		ariaLabel: "Photographic Canadian character",
+		canvas: {
+			width: input.width,
+			height: canvasHeight
+		},
+		layers: [{
+			id: "head",
+			assetId: input.assetId,
+			role: "head",
+			clip: head,
+			imageFrame: {
+				x: 0,
+				y: 0,
+				width: input.width,
+				height: input.height
+			}
+		}, {
+			id: "jaw",
+			assetId: input.assetId,
+			role: "jaw",
+			clip: jaw,
+			imageFrame: {
+				x: 0,
+				y: 0,
+				width: input.width,
+				height: input.height
+			}
+		}],
+		jaw: {
+			layerId: "jaw",
+			pivot,
+			maxOpenDegrees: 0,
+			maxOpenOffset: {
+				x: 0,
+				y: gap
+			}
+		}
+	};
+	validatePhotoCutoutRig(rig);
+	return rig;
+}
+function faceOutlinePrompt() {
+	return "Return JSON only: {\"points\":[{\"x\":number,\"y\":number},...]}. The first image is the original portrait. The second is the same original pixels with a labeled coordinate grid: labels 0..1000 map directly to this response’s x and y coordinates. Use that grid to place every point. Trace the visible head-and-face silhouette tightly in clockwise order, starting at the highest visible hair point. Include an actual point at the outermost left hair/ear edge, outermost right hair/ear edge, and lowest chin point; trace every visible hair, ear, cheek, and chin boundary between them without jumping through background. Exclude background beside hair and ears. Use 24-48 points where needed for curved hair/ear contours. This is an approximate closed silhouette for transparent background removal, not fine-hair matting and never a rectangular crop. No prose or extra keys.";
+}
+function parseMouthLandmarks(response) {
+	const root = record(typeof response === "string" ? JSON.parse(response) : response);
+	const point = (name) => {
+		const p = record(root[name]);
+		const x = p.x;
+		const y = p.y;
+		if (typeof x !== "number" || typeof y !== "number" || !Number.isFinite(x) || !Number.isFinite(y) || x < 0 || x > 1e3 || y < 0 || y > 1e3) throw new PhotoCutoutValidationError(`${name} is outside normalized bounds`);
+		return {
+			x,
+			y
+		};
+	};
+	const mouthLeft = point("mouthLeft");
+	const mouthRight = point("mouthRight");
+	const chin = point("chin");
+	if (mouthLeft.x >= mouthRight.x || chin.y <= Math.max(mouthLeft.y, mouthRight.y)) throw new PhotoCutoutValidationError("mouth and chin landmarks are anatomically invalid");
+	return {
+		mouthLeft,
+		mouthRight,
+		chin
+	};
+}
+function mouthLandmarksPrompt() {
+	return "Return JSON only: {\"mouthLeft\":{\"x\":number,\"y\":number},\"mouthRight\":{\"x\":number,\"y\":number},\"chin\":{\"x\":number,\"y\":number}}. Analyze this transparent cropped face. Coordinates are normalized 0..1000 in this cropped image. mouthLeft and mouthRight are the actual outer lip corners; chin is the center lowest chin point. Do not return polygons, a rig, or prose.";
+}
+function record(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new PhotoCutoutValidationError("setup response must be an object");
+	return value;
+}
+function parsePhotoCutoutSetup(response, source) {
+	const candidate = typeof response === "string" ? JSON.parse(response) : response;
+	const rig = record(candidate).rig ?? candidate;
+	const rigRecord = record(rig);
+	const canvas = record(rigRecord.canvas);
+	if (canvas.width !== source.width || canvas.height !== source.height) throw new PhotoCutoutValidationError("setup canvas does not match source image");
+	const layers = rigRecord.layers;
+	if (!Array.isArray(layers)) throw new PhotoCutoutValidationError("setup layers are required");
+	for (const layer of layers) {
+		const layerRecord = record(layer);
+		if (layerRecord.kind !== "solid" && layerRecord.assetId !== source.assetId) throw new PhotoCutoutValidationError("setup may reference only the authorized source asset");
+	}
+	const jaw = layers.find((layer) => record(layer).role === "jaw");
+	const mouth = layers.find((layer) => record(layer).role === "mouth-interior" && record(layer).kind === "solid");
+	if (!jaw || !mouth) throw new PhotoCutoutValidationError("setup requires jaw and mouth-interior layers");
+	record(mouth).clip = record(jaw).clip;
+	validatePhotoCutoutRig(rig);
+	return rig;
+}
+function photoCutoutSetupPrompt(source) {
+	return `Analyze the supplied portrait and return JSON only with this exact shape:
+{"rig":{"rigKind":"photo-cutout","version":1,"id":"portrait","ariaLabel":"Photographic portrait","canvas":{"width":${source.width},"height":${source.height}},"layers":[{"id":"head","assetId":"${source.assetId}","role":"head","clip":[{"x":10,"y":10},{"x":90,"y":10},{"x":90,"y":110},{"x":10,"y":110}]},{"id":"mouth","kind":"solid","role":"mouth-interior","color":{"r":30,"g":10,"b":10},"clip":[{"x":40,"y":70},{"x":60,"y":70},{"x":50,"y":82}]},{"id":"jaw","assetId":"${source.assetId}","role":"jaw","clip":[{"x":30,"y":65},{"x":70,"y":65},{"x":70,"y":105},{"x":30,"y":105}]}],"jaw":{"layerId":"jaw","pivot":{"x":50,"y":65},"maxOpenDegrees":12}}}
+Use the example only as a schema: scale all numeric coordinates to the actual ${source.width}x${source.height} image. Image layers use assetId "${source.assetId}"; the only solid layer is mouth-interior and uses integer RGB. Create a cutout head polygon, jaw polygon, and visible mouth interior from the photographed face. The jaw must be an inset lower-face polygon: leave at least 2% of head width/height between every jaw or pivot point and the head boundary. Place mouth entirely inside jaw. Every polygon must be simple, have at least three points, remain in the canvas, and the jaw/mouth must be inside the head. Do not include URLs, SVG paths, markup, transforms, prose, or keys not shown.`;
+}
+//#endregion
+export { assembleCanadianSplitRig, faceOutlinePrompt, mouthLandmarksPrompt, parseFaceOutline, parseMouthLandmarks, parsePhotoCutoutSetup, photoCutoutSetupPrompt };
+
+//# sourceMappingURL=photo-cutout-setup.js.map

package/dist/photo-cutout-setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"photo-cutout-setup.js","names":[],"sources":["../src/photo-cutout-setup.ts"],"sourcesContent":["import {\n  clipPhotoCutoutOutlineBelowLine,\n  type PhotoCutoutRig,\n  PhotoCutoutValidationError,\n  validatePhotoCutoutOutline,\n  validatePhotoCutoutRig,\n} from '@happyvertical/animation';\n\n/** A small, server-safe boundary for untrusted vision-model JSON. */\nexport interface PhotoCutoutSetupInput {\n  assetId: string;\n  width: number;\n  height: number;\n}\n\nexport interface FaceOutline {\n  points: Array<{ x: number; y: number }>;\n}\nexport interface MouthLandmarks {\n  mouthLeft: { x: number; y: number };\n  mouthRight: { x: number; y: number };\n  chin: { x: number; y: number };\n}\n\n/** Validate a normalized (0..1000) closed face silhouette from the vision pass. */\nexport function parseFaceOutline(response: string | unknown): FaceOutline {\n  const value = typeof response === 'string' ? JSON.parse(response) : response;\n  const points = record(value).points;\n  if (!Array.isArray(points) || points.length < 5 || points.length > 64) {\n    throw new PhotoCutoutValidationError('face outline needs 5-64 points');\n  }\n  const parsed = points.map((point) => {\n    const p = record(point);\n    const x = p.x;\n    const y = p.y;\n    if (\n      typeof x !== 'number' ||\n      typeof y !== 'number' ||\n      !Number.isFinite(x) ||\n      !Number.isFinite(y) ||\n      x < 0 ||\n      y < 0 ||\n      x > 1000 ||\n      y > 1000\n    )\n      throw new PhotoCutoutValidationError(\n        'face outline point is outside normalized bounds',\n      );\n    return { x, y };\n  });\n  return {\n    points: validatePhotoCutoutOutline(parsed, {\n      width: 1000,\n      height: 1000,\n      minPoints: 5,\n    }),\n  };\n}\n\n/** Build the Canadian horizontal split from real cropped-face landmarks. */\nexport function assembleCanadianSplitRig(input: {\n  outline: FaceOutline;\n  landmarks: MouthLandmarks;\n  width: number;\n  height: number;\n  assetId: string;\n}): PhotoCutoutRig {\n  const seam = (input.landmarks.mouthLeft.y + input.landmarks.mouthRight.y) / 2;\n  const lower = clipPhotoCutoutOutlineBelowLine(input.outline.points, {\n    width: 1000,\n    height: 1000,\n    y: seam,\n    minPoints: 3,\n  });\n  const scale = (p: { x: number; y: number }) => ({\n    x: (p.x / 1000) * input.width,\n    y: (p.y / 1000) * input.height,\n  });\n  const head = input.outline.points.map(scale);\n  const jaw = lower.map(scale);\n  const gap = Math.max(\n    2,\n    Math.round(((input.landmarks.chin.y - seam) / 1000) * input.height * 0.36),\n  );\n  const canvasHeight = input.height + gap;\n  const pivot = scale({\n    x: (input.landmarks.mouthLeft.x + input.landmarks.mouthRight.x) / 2,\n    y: seam,\n  });\n  const rig: PhotoCutoutRig = {\n    rigKind: 'photo-cutout',\n    version: 1,\n    id: 'portrait',\n    ariaLabel: 'Photographic Canadian character',\n    canvas: { width: input.width, height: canvasHeight },\n    layers: [\n      {\n        id: 'head',\n        assetId: input.assetId,\n        role: 'head',\n        clip: head,\n        imageFrame: { x: 0, y: 0, width: input.width, height: input.height },\n      },\n      {\n        id: 'jaw',\n        assetId: input.assetId,\n        role: 'jaw',\n        clip: jaw,\n        imageFrame: { x: 0, y: 0, width: input.width, height: input.height },\n      },\n    ],\n    jaw: {\n      layerId: 'jaw',\n      pivot,\n      maxOpenDegrees: 0,\n      maxOpenOffset: { x: 0, y: gap },\n    },\n  };\n  validatePhotoCutoutRig(rig);\n  return rig;\n}\n\nexport function faceOutlinePrompt(): string {\n  return 'Return JSON only: {\"points\":[{\"x\":number,\"y\":number},...]}. The first image is the original portrait. The second is the same original pixels with a labeled coordinate grid: labels 0..1000 map directly to this response’s x and y coordinates. Use that grid to place every point. Trace the visible head-and-face silhouette tightly in clockwise order, starting at the highest visible hair point. Include an actual point at the outermost left hair/ear edge, outermost right hair/ear edge, and lowest chin point; trace every visible hair, ear, cheek, and chin boundary between them without jumping through background. Exclude background beside hair and ears. Use 24-48 points where needed for curved hair/ear contours. This is an approximate closed silhouette for transparent background removal, not fine-hair matting and never a rectangular crop. No prose or extra keys.';\n}\n\nexport function parseMouthLandmarks(\n  response: string | unknown,\n): MouthLandmarks {\n  const root = record(\n    typeof response === 'string' ? JSON.parse(response) : response,\n  );\n  const point = (name: 'mouthLeft' | 'mouthRight' | 'chin') => {\n    const p = record(root[name]);\n    const x = p.x;\n    const y = p.y;\n    if (\n      typeof x !== 'number' ||\n      typeof y !== 'number' ||\n      !Number.isFinite(x) ||\n      !Number.isFinite(y) ||\n      x < 0 ||\n      x > 1000 ||\n      y < 0 ||\n      y > 1000\n    )\n      throw new PhotoCutoutValidationError(\n        `${name} is outside normalized bounds`,\n      );\n    return { x, y };\n  };\n  const mouthLeft = point('mouthLeft');\n  const mouthRight = point('mouthRight');\n  const chin = point('chin');\n  if (\n    mouthLeft.x >= mouthRight.x ||\n    chin.y <= Math.max(mouthLeft.y, mouthRight.y)\n  )\n    throw new PhotoCutoutValidationError(\n      'mouth and chin landmarks are anatomically invalid',\n    );\n  return { mouthLeft, mouthRight, chin };\n}\n\nexport function mouthLandmarksPrompt(): string {\n  return 'Return JSON only: {\"mouthLeft\":{\"x\":number,\"y\":number},\"mouthRight\":{\"x\":number,\"y\":number},\"chin\":{\"x\":number,\"y\":number}}. Analyze this transparent cropped face. Coordinates are normalized 0..1000 in this cropped image. mouthLeft and mouthRight are the actual outer lip corners; chin is the center lowest chin point. Do not return polygons, a rig, or prose.';\n}\n\nfunction record(value: unknown): Record<string, unknown> {\n  if (!value || typeof value !== 'object' || Array.isArray(value)) {\n    throw new PhotoCutoutValidationError('setup response must be an object');\n  }\n  return value as Record<string, unknown>;\n}\n\n/**\n * Parses a model response and binds every image layer to the authorized source\n * image. The animation validator is the final geometry and bounds authority.\n */\nexport function parsePhotoCutoutSetup(\n  response: string | unknown,\n  source: PhotoCutoutSetupInput,\n): PhotoCutoutRig {\n  const candidate =\n    typeof response === 'string' ? JSON.parse(response) : response;\n  const root = record(candidate);\n  const rig = (root.rig ?? candidate) as unknown;\n  const rigRecord = record(rig);\n  const canvas = record(rigRecord.canvas);\n  if (canvas.width !== source.width || canvas.height !== source.height) {\n    throw new PhotoCutoutValidationError(\n      'setup canvas does not match source image',\n    );\n  }\n  const layers = rigRecord.layers;\n  if (!Array.isArray(layers)) {\n    throw new PhotoCutoutValidationError('setup layers are required');\n  }\n  for (const layer of layers) {\n    const layerRecord = record(layer);\n    if (\n      layerRecord.kind !== 'solid' &&\n      layerRecord.assetId !== source.assetId\n    ) {\n      throw new PhotoCutoutValidationError(\n        'setup may reference only the authorized source asset',\n      );\n    }\n  }\n  // The solid mouth is painted beneath the photographic jaw. Making its clip\n  // identical to the jaw guarantees it cannot appear through a neutral jaw;\n  // the runtime reveals it only as the jaw rotates open.\n  const jaw = layers.find((layer) => record(layer).role === 'jaw');\n  const mouth = layers.find(\n    (layer) =>\n      record(layer).role === 'mouth-interior' && record(layer).kind === 'solid',\n  );\n  if (!jaw || !mouth) {\n    throw new PhotoCutoutValidationError(\n      'setup requires jaw and mouth-interior layers',\n    );\n  }\n  record(mouth).clip = record(jaw).clip;\n  validatePhotoCutoutRig(rig);\n  return rig;\n}\n\n/** Deliberately specific instructions reduce geometry ambiguity from vision models. */\nexport function photoCutoutSetupPrompt(source: PhotoCutoutSetupInput): string {\n  return `Analyze the supplied portrait and return JSON only with this exact shape:\n{\"rig\":{\"rigKind\":\"photo-cutout\",\"version\":1,\"id\":\"portrait\",\"ariaLabel\":\"Photographic portrait\",\"canvas\":{\"width\":${source.width},\"height\":${source.height}},\"layers\":[{\"id\":\"head\",\"assetId\":\"${source.assetId}\",\"role\":\"head\",\"clip\":[{\"x\":10,\"y\":10},{\"x\":90,\"y\":10},{\"x\":90,\"y\":110},{\"x\":10,\"y\":110}]},{\"id\":\"mouth\",\"kind\":\"solid\",\"role\":\"mouth-interior\",\"color\":{\"r\":30,\"g\":10,\"b\":10},\"clip\":[{\"x\":40,\"y\":70},{\"x\":60,\"y\":70},{\"x\":50,\"y\":82}]},{\"id\":\"jaw\",\"assetId\":\"${source.assetId}\",\"role\":\"jaw\",\"clip\":[{\"x\":30,\"y\":65},{\"x\":70,\"y\":65},{\"x\":70,\"y\":105},{\"x\":30,\"y\":105}]}],\"jaw\":{\"layerId\":\"jaw\",\"pivot\":{\"x\":50,\"y\":65},\"maxOpenDegrees\":12}}}\nUse the example only as a schema: scale all numeric coordinates to the actual ${source.width}x${source.height} image. Image layers use assetId \"${source.assetId}\"; the only solid layer is mouth-interior and uses integer RGB. Create a cutout head polygon, jaw polygon, and visible mouth interior from the photographed face. The jaw must be an inset lower-face polygon: leave at least 2% of head width/height between every jaw or pivot point and the head boundary. Place mouth entirely inside jaw. Every polygon must be simple, have at least three points, remain in the canvas, and the jaw/mouth must be inside the head. Do not include URLs, SVG paths, markup, transforms, prose, or keys not shown.`;\n}\n"],"mappings":"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"}

package/dist/smrt-knowledge.json

@@ -3,12 +3,12 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-images",
-  "packageVersion": "0.55.9",
+  "packageVersion": "0.55.15",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "47b386d0695b89fc784749e9d8349a6e2f18c557ce4dc17bb5537609dfa21549",
-    "packageJson": "bdc716cbce40beacb1da905f8a698b446f8cfec6f32a0b5fcb9d6f3d61073a19",
+    "manifest": "e6aa5cd35b14bdfc34077c2caba78899e1f8daf47ff5eb2b95b9ca0e9535a985",
+    "packageJson": "d7707f46ba2840704411112fff5272d98aad2f0f13c39506451bd43bdfc9f251",
     "agents": "82a1905b76f49d9a852bf1e4f591595ae596c5cfa14ec736dc6f8fe32200fd8c"
   },
   "exports": [
@@ -21,6 +21,7 @@
     "./workbench"
   ],
   "dependencies": {
+    "@happyvertical/animation": "0.5.0",
     "@happyvertical/ai": "catalog:",
     "@happyvertical/images": "catalog:",
     "@happyvertical/smrt-assets": "workspace:*",
@@ -33,6 +34,7 @@
     "jimp": "catalog:",
     "sharp": "catalog:",
     "@happyvertical/smrt-playground": "workspace:*",
+    "@happyvertical/smrt-profiles": "workspace:*",
     "@happyvertical/smrt-vitest": "workspace:*",
     "@happyvertical/sql": "catalog:",
     "@sveltejs/kit": "2.69.1",
@@ -49,6 +51,7 @@
     "@happyvertical/smrt-assets",
     "@happyvertical/smrt-core",
     "@happyvertical/smrt-playground",
+    "@happyvertical/smrt-profiles",
     "@happyvertical/smrt-prompts",
     "@happyvertical/smrt-tenancy",
     "@happyvertical/smrt-types",
@@ -107,96 +110,111 @@
           "name": "name",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "A recognizable name for this file or media item."
         },
         {
           "name": "sourceUri",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "Where the original file is stored or can be retrieved."
         },
         {
           "name": "mimeType",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "The file format, such as image/jpeg or application/pdf."
         },
         {
           "name": "description",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "Explain what the file contains and when it should be used."
         },
         {
           "name": "metadata",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "Additional details recorded while processing this file."
         },
         {
           "name": "version",
           "type": "integer",
           "required": true,
           "columnType": "INTEGER",
-          "default": 1
+          "default": 1,
+          "description": "The revision number of this file in its version history."
         },
         {
           "name": "primaryVersionId",
           "type": "foreignKey",
           "required": false,
           "related": "Asset",
-          "columnType": "UUID"
+          "columnType": "UUID",
+          "description": "The first version of this file, linking its revision history."
         },
         {
           "name": "typeSlug",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "The category of asset, such as an image, video, or document."
         },
         {
           "name": "statusSlug",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "The stage of this asset, such as draft, published, or archived."
         },
         {
           "name": "ownerProfileId",
           "type": "crossPackageRef",
           "required": false,
           "related": "@happyvertical/smrt-profiles:Profile",
-          "columnType": "UUID"
+          "columnType": "UUID",
+          "description": "The person or organization responsible for this asset."
         },
         {
           "name": "sourceAssetId",
           "type": "foreignKey",
           "required": false,
           "related": "Asset",
-          "columnType": "UUID"
+          "columnType": "UUID",
+          "description": "The original asset used to produce this file or variation."
         },
         {
           "name": "folderId",
           "type": "foreignKey",
           "required": false,
           "related": "Folder",
-          "columnType": "UUID"
+          "columnType": "UUID",
+          "description": "The folder that organizes this file in the asset library."
         },
         {
           "name": "sourceType",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "The service or source from which this file was obtained."
         },
         {
           "name": "externalId",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "The reference used to identify this file at its original source."
         },
         {
           "name": "externalRefs",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "References that connect this file to copies held by other services."
         },
         {
           "name": "createdAt",