cozyclay 1.2.0 → 1.3.0

package/src/scene-assets.js

@@ -0,0 +1,288 @@
+/**
+ * Scene assets: the bytes an object points at.
+ *
+ * A cutout carries an `assetId`, never its picture. The scene document is one
+ * JSON string in localStorage (`cozyclay.scenes.v2`), and a single base64 PNG
+ * is bigger than the whole budget that string gets — so images live in
+ * IndexedDB, keyed by an id the scene can hold on to.
+ *
+ * The id is derived from the bytes themselves (SHA-256), which buys three
+ * things for free: the same picture imported twice is stored once, a
+ * duplicated scene shares its originals instead of copying them, and an id is
+ * meaningful across a reload, an export and another machine.
+ *
+ * Everything above the storage adapter is pure and testable in node; the
+ * adapter is the only part that needs a browser.
+ */
+
+/** Content-addressed, so the same bytes always land on the same id. */
+export const ASSET_ID_PREFIX = "img-";
+/** 128 bits of a SHA-256 digest: collision-proof for a project's worth of
+ * pictures, and short enough to read in a scene file. */
+const ASSET_ID_HEX = 32;
+
+export const ASSET_DB_NAME = "cozyclay.assets";
+export const ASSET_DB_VERSION = 1;
+export const ASSET_STORE_NAME = "images";
+
+/** What an import will accept. SVG is excluded on purpose: it is a document
+ * that can carry script, and a set piece is not worth that. */
+export const ASSET_IMAGE_TYPES = Object.freeze(["image/png", "image/webp", "image/jpeg", "image/gif"]);
+/** Source-file ceiling. A 40 MP phone photo is fine as an INPUT — it gets
+ * decoded and downscaled before anything is stored — but the file itself has
+ * to be readable in one bite first. */
+export const ASSET_MAX_SOURCE_BYTES = 32 * 1024 * 1024;
+/** Longest edge kept. A card is a staging surface, not a texture for a hero
+ * render, and 2048 is the size every WebGL implementation can hold. */
+export const ASSET_MAX_DIMENSION = 2048;
+
+export function isSupportedImageType(type) {
+	return typeof type === "string" && ASSET_IMAGE_TYPES.includes(type.toLowerCase());
+}
+
+/** An id from a hex digest, tolerant of the caller's case and length. */
+export function assetIdFromDigest(hex) {
+	if (typeof hex !== "string") return null;
+	const clean = hex.trim().toLowerCase();
+	if (!/^[0-9a-f]+$/.test(clean) || clean.length < ASSET_ID_HEX) return null;
+	return `${ASSET_ID_PREFIX}${clean.slice(0, ASSET_ID_HEX)}`;
+}
+
+export function isAssetId(value) {
+	return typeof value === "string" && new RegExp(`^${ASSET_ID_PREFIX}[0-9a-f]{${ASSET_ID_HEX}}$`).test(value);
+}
+
+/**
+ * The id these bytes will be stored under. `subtle` is injectable so the node
+ * tests can hand in `crypto.webcrypto.subtle`; in the browser it is the page's
+ * own SubtleCrypto, which needs a secure context (localhost counts).
+ */
+export async function assetIdForBytes(bytes, subtle = globalThis.crypto?.subtle) {
+	if (!subtle?.digest) throw new Error("SubtleCrypto is unavailable — a secure context is required to import images");
+	const buffer = bytes instanceof ArrayBuffer ? bytes : bytes?.buffer ? bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) : null;
+	if (!buffer) throw new TypeError("assetIdForBytes needs an ArrayBuffer or a typed array");
+	const digest = await subtle.digest("SHA-256", buffer);
+	const hex = Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+	return assetIdFromDigest(hex);
+}
+
+/**
+ * The stored size for a decoded image: the longest edge capped, aspect kept,
+ * and never enlarged. Returns the source size unchanged (`scaled: false`) when
+ * it already fits, so a small picture is stored exactly as it arrived.
+ */
+export function downscaleTarget(width, height, max = ASSET_MAX_DIMENSION) {
+	const w = Math.max(0, Math.round(Number(width) || 0));
+	const h = Math.max(0, Math.round(Number(height) || 0));
+	if (!w || !h) return null;
+	const longest = Math.max(w, h);
+	if (longest <= max) return { width: w, height: h, scaled: false };
+	const factor = max / longest;
+	// Round to at least 1: a 4096 x 3 strip must not become 2048 x 0.
+	return { width: Math.max(1, Math.round(w * factor)), height: Math.max(1, Math.round(h * factor)), scaled: true };
+}
+
+/** The card's width / height, from the picture the card wears. */
+export function assetAspect(asset) {
+	const width = Number(asset?.width);
+	const height = Number(asset?.height);
+	if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) return null;
+	return width / height;
+}
+
+/**
+ * Repair one stored asset record, or return null to drop it. Storage is never
+ * trusted here either: a record without usable bytes or a usable size cannot
+ * be drawn, and a card pointing at it is better shown as missing than as a
+ * blank quad of the wrong shape.
+ */
+export function normalizeAsset(record) {
+	if (!record || typeof record !== "object" || Array.isArray(record)) return null;
+	if (!isAssetId(record.id)) return null;
+	if (!isSupportedImageType(record.type)) return null;
+	const width = Math.round(Number(record.width));
+	const height = Math.round(Number(record.height));
+	if (!Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0) return null;
+	const bytes = record.bytes instanceof ArrayBuffer ? record.bytes : null;
+	if (!bytes || !bytes.byteLength) return null;
+	return { id: record.id, type: record.type.toLowerCase(), width, height, bytes, name: typeof record.name === "string" ? record.name : "" };
+}
+
+/**
+ * The image files in a drop (or a paste), in the order they were dropped.
+ *
+ * Two quirks make this worth a function rather than a filter inline. A file
+ * dragged from some applications arrives with an EMPTY type — the browser has
+ * a name and bytes but no sniffed MIME — so the extension is the fallback, not
+ * a shortcut. And a drag can carry directories and text as well as files, which
+ * `files` reports as entries with no type and no extension; those are dropped
+ * rather than handed to a decoder that will fail on them.
+ */
+export function imageFilesFrom(transfer) {
+	const files = Array.from(transfer?.files ?? []);
+	return files.filter((file) => {
+		if (!file) return false;
+		if (isSupportedImageType(file.type)) return true;
+		if (file.type) return false;
+		const extension = String(file.name ?? "").toLowerCase().match(/\.([a-z0-9]+)$/)?.[1];
+		return ["png", "webp", "jpg", "jpeg", "gif"].includes(extension);
+	});
+}
+
+/* ------------------------------------------------------------- import ---- */
+
+/** Scaling a picture re-encodes it, and the encoder has to be one that can
+ * still carry alpha — a cutout IS its transparency. JPEG has none to lose, so
+ * a photo stays a photo instead of tripling in size as a PNG. */
+function storedTypeFor(sourceType) {
+	return sourceType === "image/jpeg" ? "image/jpeg" : "image/png";
+}
+
+function defaultCanvas(width, height) {
+	if (typeof OffscreenCanvas === "function") return new OffscreenCanvas(width, height);
+	throw new Error("this browser cannot resize images — OffscreenCanvas is unavailable");
+}
+
+/**
+ * One imported file as a storable asset record: decoded, capped to
+ * ASSET_MAX_DIMENSION, and identified by the bytes that will actually be
+ * stored (so two imports of the same photo dedupe even after a resize).
+ *
+ * Every browser API it needs is injectable, which is what lets the node tests
+ * drive the whole path with stubs. Failures throw with a sentence fit to show
+ * in a toast — the caller has no way to explain "NotReadableError" to anyone.
+ */
+export async function importImageFile(file, {
+	subtle = globalThis.crypto?.subtle,
+	createBitmap = globalThis.createImageBitmap,
+	makeCanvas = defaultCanvas,
+	maxDimension = ASSET_MAX_DIMENSION,
+	maxSourceBytes = ASSET_MAX_SOURCE_BYTES,
+} = {}) {
+	if (!file || typeof file.arrayBuffer !== "function") throw new TypeError("importImageFile needs a File or Blob");
+	const sourceType = typeof file.type === "string" ? file.type.toLowerCase() : "";
+	if (!isSupportedImageType(sourceType)) throw new Error("that file is not an image CozyClay can import (PNG, WebP, JPEG or GIF)");
+	if (Number(file.size) > maxSourceBytes) throw new Error(`that image is larger than ${Math.round(maxSourceBytes / (1024 * 1024))} MB`);
+	if (typeof createBitmap !== "function") throw new Error("this browser cannot decode images — createImageBitmap is unavailable");
+
+	const bitmap = await createBitmap(file);
+	try {
+		const target = downscaleTarget(bitmap.width, bitmap.height, maxDimension);
+		if (!target) throw new Error("that image has no usable size");
+		let type = sourceType;
+		let bytes;
+		if (target.scaled) {
+			const canvas = makeCanvas(target.width, target.height);
+			const context = canvas.getContext("2d");
+			if (!context) throw new Error("this browser cannot resize images — no 2D context");
+			context.drawImage(bitmap, 0, 0, target.width, target.height);
+			type = storedTypeFor(sourceType);
+			const blob = await canvas.convertToBlob({ type });
+			bytes = await blob.arrayBuffer();
+		} else {
+			// Unscaled, the original bytes are stored verbatim: no re-encode means
+			// no generation loss, and an untouched PNG keeps its exact alpha.
+			bytes = await file.arrayBuffer();
+		}
+		const asset = normalizeAsset({
+			id: await assetIdForBytes(bytes, subtle),
+			type,
+			width: target.width,
+			height: target.height,
+			bytes,
+			name: typeof file.name === "string" ? file.name : "",
+		});
+		if (!asset) throw new Error("that image could not be prepared for the set");
+		return asset;
+	} finally {
+		bitmap?.close?.();
+	}
+}
+
+/* ------------------------------------------------------- reachability ---- */
+
+/**
+ * Every asset id the scenes still point at. Assets outlive the object that
+ * imported them — undo brings a deleted cutout back, and two scenes can wear
+ * the same picture — so nothing is deleted on the strength of one object
+ * going away. This is the reachable set; `unreachableAssetIds` is the sweep.
+ */
+export function referencedAssetIds(scenes) {
+	const ids = new Set();
+	for (const scene of Array.isArray(scenes) ? scenes : []) {
+		for (const object of Array.isArray(scene?.objects) ? scene.objects : []) {
+			if (isAssetId(object?.assetId)) ids.add(object.assetId);
+		}
+	}
+	return ids;
+}
+
+/** Stored ids that nothing points at any more, ready to be swept. */
+export function unreachableAssetIds(storedIds, scenes) {
+	const reachable = referencedAssetIds(scenes);
+	return (Array.isArray(storedIds) ? storedIds : []).filter((id) => isAssetId(id) && !reachable.has(id));
+}
+
+/* ------------------------------------------------------------ storage ---- */
+
+const request = (req) =>
+	new Promise((resolve, reject) => {
+		req.onsuccess = () => resolve(req.result);
+		req.onerror = () => reject(req.error);
+	});
+
+/** Open (and create) the asset database. Injectable factory so a test or a
+ * non-browser host can hand in its own IndexedDB implementation. */
+export function openAssetDb(factory = globalThis.indexedDB) {
+	if (!factory) return Promise.reject(new Error("IndexedDB is unavailable"));
+	return new Promise((resolve, reject) => {
+		const open = factory.open(ASSET_DB_NAME, ASSET_DB_VERSION);
+		open.onupgradeneeded = () => {
+			if (!open.result.objectStoreNames.contains(ASSET_STORE_NAME)) {
+				open.result.createObjectStore(ASSET_STORE_NAME, { keyPath: "id" });
+			}
+		};
+		open.onsuccess = () => resolve(open.result);
+		open.onerror = () => reject(open.error);
+		open.onblocked = () => reject(new Error("the asset database is blocked by another tab"));
+	});
+}
+
+/** Store a record. Content-addressed ids make this idempotent: re-importing
+ * the same picture overwrites it with identical bytes. */
+export async function putAsset(db, record) {
+	const asset = normalizeAsset(record);
+	if (!asset) throw new TypeError("putAsset needs a normalizable asset record");
+	const tx = db.transaction(ASSET_STORE_NAME, "readwrite");
+	tx.objectStore(ASSET_STORE_NAME).put(asset);
+	await new Promise((resolve, reject) => {
+		tx.oncomplete = resolve;
+		tx.onerror = () => reject(tx.error);
+		tx.onabort = () => reject(tx.error);
+	});
+	return asset;
+}
+
+export async function getAsset(db, id) {
+	if (!isAssetId(id)) return null;
+	const tx = db.transaction(ASSET_STORE_NAME, "readonly");
+	return normalizeAsset(await request(tx.objectStore(ASSET_STORE_NAME).get(id)));
+}
+
+export async function listAssetIds(db) {
+	const tx = db.transaction(ASSET_STORE_NAME, "readonly");
+	const keys = await request(tx.objectStore(ASSET_STORE_NAME).getAllKeys());
+	return (keys ?? []).filter(isAssetId);
+}
+
+export async function deleteAsset(db, id) {
+	if (!isAssetId(id)) return false;
+	const tx = db.transaction(ASSET_STORE_NAME, "readwrite");
+	tx.objectStore(ASSET_STORE_NAME).delete(id);
+	await new Promise((resolve, reject) => {
+		tx.oncomplete = resolve;
+		tx.onerror = () => reject(tx.error);
+		tx.onabort = () => reject(tx.error);
+	});
+	return true;
+}

package/src/scene-objects.js

@@ -31,9 +31,14 @@ export const SCENE_VERSION = 1;
 const EULER_ORDER = "XYZ";
 const DEG = Math.PI / 180;
 
-/** Room half-extent; matches the plan board's ROOM_LIMIT. */
-const ROOM_LIMIT = 11;
-const CEILING = 6;
+/** Stage half-extent; matches the plan board's ROOM_LIMIT. The set is an
+ * open 500 m deck now, so the clamp is a guard against runaway coordinates,
+ * not a wall — it stops just inside the floor's edge. */
+const ROOM_LIMIT = 240;
+// Headroom, not a ceiling: the walls (and the 6.2 m room they implied) are
+// gone, so this only stops a runaway coordinate. A rocket, a crane or a
+// skyline piece all have to fit under it.
+const CEILING = 240;
 const SCALE_MIN = 0.1;
 const SCALE_MAX = 100;
 
@@ -72,10 +77,57 @@ export const OBJECT_LIBRARY = [
  * inspector. */
 export const OBJECT_COLORS = ["#e2e5e6", GREY_BOX, "#9aa1a5", "#767d81", "#d9b18c", "#8fae9b"];
 
+/**
+ * A cutout is a standee: an imported image standing on a card. Its size is NOT
+ * library data — the height is measured by the user and the width follows the
+ * picture's own aspect — so the record carries `assetId`, `aspect` and
+ * `height`, and the footprint is DERIVED from them. Deriving rather than
+ * storing is what stops a card persisting a width its picture disagrees with.
+ */
+export const CUTOUT_KIND = "cutout";
+/** Card thickness in metres: thin enough to read as flat, thick enough that
+ * the plan board and dropToSurfacePatch still have a rectangle to work on. */
+export const CUTOUT_THICKNESS = 0.02;
+/** A fresh cutout stands as tall as the figure it blocks against
+ * (SUBJECT_HEIGHT_M), so the first thing you see is honest scale. */
+export const CUTOUT_DEFAULT_HEIGHT = 1.8;
+/** A card can be as tall as anything else on the deck: the walls are gone and
+ * a skyline piece or a building facade is a legitimate cutout. Exported so the
+ * inspector's field and the tests take the limit from here rather than
+ * repeating a number that has already changed once. */
+export const CUTOUT_MAX_HEIGHT = CEILING;
+const CUTOUT_HEIGHT_MIN = 0.05;
+const CUTOUT_ASPECT_MIN = 0.02;
+const CUTOUT_ASPECT_MAX = 50;
+/** Cutouts carry their own colour: unlike a primitive, the card IS the thing
+ * it depicts, so it is tinted white and multiplies the image untouched. */
+const CUTOUT_TINT = "#ffffff";
+const CUTOUT_ENTRY = {
+	kind: CUTOUT_KIND,
+	label: "Cutout",
+	group: "Images",
+	footprint: { width: 1, depth: CUTOUT_THICKNESS },
+	height: CUTOUT_DEFAULT_HEIGHT,
+	color: CUTOUT_TINT,
+};
+
+/** Every kind that can exist in a scene: the catalogue you can create from,
+ * plus the kinds that arrive by import and so are deliberately absent from the
+ * "Add object" menu (a cutout without an image has nothing to draw). */
 function objectLibraryEntry(kind) {
+	if (kind === CUTOUT_KIND) return CUTOUT_ENTRY;
 	return OBJECT_LIBRARY.find((entry) => entry.kind === kind) ?? null;
 }
 
+const cutoutHeight = (value) => clamp(value, CUTOUT_HEIGHT_MIN, CUTOUT_MAX_HEIGHT);
+const cutoutAspect = (value) => clamp(value, CUTOUT_ASPECT_MIN, CUTOUT_ASPECT_MAX);
+
+/** The plan-board rectangle a card of this height and picture aspect occupies.
+ * `aspect` is the image's width / height. */
+export function cutoutFootprint(height, aspect) {
+	return { width: cutoutHeight(height) * cutoutAspect(aspect), depth: CUTOUT_THICKNESS };
+}
+
 export function sceneObjectHierarchyId(id) {
 	return `object:${id}`;
 }
@@ -90,6 +142,9 @@ export function sceneObjectIdFromHierarchy(hierarchyId) {
  * camera); everything else starts neutral so the first drag is predictable.
  */
 export function createSceneObject(kind, existing = [], placement = {}) {
+	// Cutouts come from an import, never from the catalogue: without an asset
+	// id the record has nothing to draw. `createCutoutObject` is their door.
+	if (kind === CUTOUT_KIND) return null;
 	const entry = objectLibraryEntry(kind);
 	if (!entry) return null;
 	const names = new Set(existing.map((object) => object.name));
@@ -112,11 +167,61 @@ export function createSceneObject(kind, existing = [], placement = {}) {
 		scaleY: 1,
 		scaleZ: 1,
 		color: entry.color,
+		parent: null,
 		footprint: { ...entry.footprint },
 		height: entry.height,
 	};
 }
 
+/**
+ * A fresh cutout for an imported image. `assetId` addresses the picture in the
+ * asset store — the record never carries the bytes, which is what keeps a
+ * scene small enough to live in localStorage — and `aspect` is the image's
+ * width / height so the card can be sized by height alone.
+ *
+ * `name` seeds the display name (the file's own name is the obvious caller
+ * choice); everything else starts neutral, exactly like a catalogue object.
+ */
+export function createCutoutObject({ assetId, aspect = 1, height = CUTOUT_DEFAULT_HEIGHT, name = "" } = {}, existing = [], placement = {}) {
+	if (typeof assetId !== "string" || !assetId) return null;
+	const pictureAspect = cutoutAspect(Number(aspect));
+	const cardHeight = cutoutHeight(Number(height));
+	if (!Number.isFinite(pictureAspect) || !Number.isFinite(cardHeight)) return null;
+	const base = typeof name === "string" && name.trim() ? name.trim() : CUTOUT_ENTRY.label;
+	const names = new Set(existing.map((object) => object.name));
+	let displayName = base;
+	for (let n = 2; names.has(displayName); n += 1) displayName = `${base} ${n}`;
+	const ids = new Set(existing.map((object) => object.id));
+	let id = CUTOUT_KIND;
+	for (let n = 2; ids.has(id); n += 1) id = `${CUTOUT_KIND}-${n}`;
+	return {
+		id,
+		name: displayName,
+		renderer: CUTOUT_KIND,
+		x: clamp(Number(placement.x) || 0, -ROOM_LIMIT, ROOM_LIMIT),
+		y: 0,
+		z: clamp(Number(placement.z) || 0, -ROOM_LIMIT, ROOM_LIMIT),
+		rot: wrapAngle(Number(placement.rot) || 0),
+		rotX: 0,
+		rotZ: 0,
+		scaleX: 1,
+		scaleY: 1,
+		scaleZ: 1,
+		color: CUTOUT_TINT,
+		parent: null,
+		// Key order matches what `normalizeSceneObject` writes, so a record
+		// survives a storage round trip byte-for-byte.
+		assetId,
+		// A picture nobody has cut is its own original, with no purple on it.
+		sourceAssetId: assetId,
+		matteAssetId: "",
+		matteScale: 1,
+		aspect: pictureAspect,
+		footprint: cutoutFootprint(cardHeight, pictureAspect),
+		height: cardHeight,
+	};
+}
+
 /** Every writable transform channel and the rule that keeps it in the room. */
 const TRANSFORM_LIMITS = {
 	x: (value) => clamp(value, -ROOM_LIMIT, ROOM_LIMIT),
@@ -130,10 +235,60 @@ const TRANSFORM_LIMITS = {
 	scaleZ: (value) => clamp(value, SCALE_MIN, SCALE_MAX),
 };
 
+/** Every object that hangs off `id`, at any depth. A cycle cannot form because
+ * setParent refuses one, but the seen-set keeps this total even if data is
+ * hand-edited into a loop. */
+export function descendantsOf(objects, id) {
+	const out = [];
+	const seen = new Set([id]);
+	let frontier = [id];
+	while (frontier.length) {
+		const next = [];
+		for (const object of objects) {
+			if (object.parent && frontier.includes(object.parent) && !seen.has(object.id)) {
+				seen.add(object.id);
+				out.push(object);
+				next.push(object.id);
+			}
+		}
+		frontier = next;
+	}
+	return out;
+}
+
 export function updateSceneObject(objects, id, patch) {
 	let changed = false;
+	const target = objects.find((object) => object.id === id);
+	// A parent carries its children: the group is dragged, nudged and dropped as
+	// one body. Only translation rides along — rotating or scaling a group would
+	// have to orbit and rescale every child about the parent's origin, which is a
+	// different feature and is deliberately not pretended at here.
+	const carried = target ? descendantsOf(objects, id) : [];
+	const delta = { x: 0, y: 0, z: 0 };
+	if (target) {
+		for (const axis of ["x", "y", "z"]) {
+			if (patch[axis] === undefined) continue;
+			const value = Number(patch[axis]);
+			if (!Number.isFinite(value)) continue;
+			delta[axis] = TRANSFORM_LIMITS[axis](value) - target[axis];
+		}
+	}
+	const moving = new Set(carried.map((object) => object.id));
+	const shifts = delta.x || delta.y || delta.z;
+
 	const next = objects.map((object) => {
-		if (object.id !== id) return object;
+		if (object.id !== id) {
+			if (!shifts || !moving.has(object.id)) return object;
+			const update = {};
+			for (const axis of ["x", "y", "z"]) {
+				if (!delta[axis]) continue;
+				const bounded = TRANSFORM_LIMITS[axis](object[axis] + delta[axis]);
+				if (bounded !== object[axis]) update[axis] = bounded;
+			}
+			if (!Object.keys(update).length) return object;
+			changed = true;
+			return { ...object, ...update };
+		}
 		const update = {};
 		for (const [key, limit] of Object.entries(TRANSFORM_LIMITS)) {
 			if (patch[key] === undefined) continue;
@@ -147,6 +302,41 @@ export function updateSceneObject(objects, id, patch) {
 			if (typeof patch[key] !== "string" || !patch[key] || patch[key] === object[key]) continue;
 			update[key] = patch[key];
 		}
+		// A cutout is sized in metres — you measure something in the picture and
+		// type its height — so `height` and `aspect` are writable where every
+		// other kind takes them from the library. The footprint is DERIVED here
+		// and never patched: one owner for the card's width is what keeps it
+		// from disagreeing with its own image.
+		if (object.renderer === CUTOUT_KIND) {
+			// The picture itself is writable: cutting the background out stores a
+			// NEW asset (different bytes, different id) and points the card at it,
+			// which is what makes the cut undoable — the original stays addressed
+			// by the history entry before it.
+			// Three ids, because a cut card is not one picture: `assetId` is what
+			// the set renders, `sourceAssetId` is the photograph it came from and
+			// keeps being edited from, and `matteAssetId` is the purple itself.
+			// Keeping all three is what makes the cut re-editable instead of
+			// destructive — the original is never replaced, only masked.
+			for (const key of ["assetId", "sourceAssetId", "matteAssetId"]) {
+				if (typeof patch[key] === "string" && patch[key] && patch[key] !== object[key]) update[key] = patch[key];
+			}
+			// How much of the original frame the trimmed card is. Stored so a
+			// second edit can work out the height the card would have at full
+			// frame instead of compounding one trim onto the last.
+			if (Number.isFinite(Number(patch.matteScale))) {
+				const scale = clamp(Number(patch.matteScale), 0.01, 1);
+				if (scale !== object.matteScale) update.matteScale = scale;
+			}
+			const patchedHeight = patch.height === undefined ? NaN : cutoutHeight(Number(patch.height));
+			const patchedAspect = patch.aspect === undefined ? NaN : cutoutAspect(Number(patch.aspect));
+			const height = Number.isFinite(patchedHeight) ? patchedHeight : object.height;
+			const aspect = Number.isFinite(patchedAspect) ? patchedAspect : object.aspect;
+			if (height !== object.height || aspect !== object.aspect) {
+				update.height = height;
+				update.aspect = aspect;
+				update.footprint = cutoutFootprint(height, aspect);
+			}
+		}
 		if (!Object.keys(update).length) return object;
 		changed = true;
 		return { ...object, ...update };
@@ -154,9 +344,33 @@ export function updateSceneObject(objects, id, patch) {
 	return changed ? next : objects;
 }
 
+/**
+ * Attach `id` to `parentId` (or detach with null). Refuses the two shapes that
+ * would corrupt the tree: an object parented to itself, and a cycle formed by
+ * parenting an object to one of its own descendants.
+ */
+export function setSceneObjectParent(objects, id, parentId) {
+	if (id === parentId) return objects;
+	if (parentId !== null && !objects.some((object) => object.id === parentId)) return objects;
+	if (parentId !== null && descendantsOf(objects, id).some((object) => object.id === parentId)) return objects;
+	let changed = false;
+	const next = objects.map((object) => {
+		if (object.id !== id) return object;
+		const parent = parentId ?? null;
+		if ((object.parent ?? null) === parent) return object;
+		changed = true;
+		return { ...object, parent };
+	});
+	return changed ? next : objects;
+}
+
 export function removeSceneObject(objects, id) {
 	const next = objects.filter((object) => object.id !== id);
-	return next.length === objects.length ? objects : next;
+	if (next.length === objects.length) return objects;
+	// Deleting a parent must not leave its children pointing at a ghost: they
+	// are promoted to top level rather than vanishing with it, because a group
+	// is an editing convenience and never an owner of the parts.
+	return next.map((object) => (object.parent === id ? { ...object, parent: null } : object));
 }
 /* -------------------------------------------------- persistence ---- */
 
@@ -173,6 +387,11 @@ export function normalizeSceneObject(record) {
 	const entry = objectLibraryEntry(record.renderer);
 	if (!entry) return null;
 	if (typeof record.id !== "string" || !record.id) return null;
+	// A cutout addresses its picture by id. A record without one has nothing to
+	// draw, so it is dropped rather than restored as a blank card — the same
+	// rule an unknown renderer already gets.
+	const isCutout = entry.kind === CUTOUT_KIND;
+	if (isCutout && (typeof record.assetId !== "string" || !record.assetId)) return null;
 	// Defensive import fallback, not a migration: hand-authored or external
 	// payloads may carry one `scale` (the pre-split record shape). It fans
 	// out to all three axes only when no axis is present — an explicit
@@ -198,8 +417,27 @@ export function normalizeSceneObject(record) {
 		scaleY: TRANSFORM_LIMITS.scaleY(pick(record.scaleY, scaleFallback)),
 		scaleZ: TRANSFORM_LIMITS.scaleZ(pick(record.scaleZ, scaleFallback)),
 		color: typeof record.color === "string" && record.color ? record.color : entry.color,
-		footprint: { ...entry.footprint },
-		height: entry.height,
+		// Group membership. null is a top-level object; the id of another object
+		// makes this one ride along when that object moves.
+		parent: typeof record.parent === "string" && record.parent ? record.parent : null,
+		// Library kinds take their size from the library — a stored footprint is
+		// stale data, not a fact. A cutout is the exception: its size IS
+		// per-instance, so height and aspect are repaired from the record and
+		// the footprint is rebuilt from the pair.
+		...(isCutout
+			? {
+					assetId: record.assetId,
+					// An older record (or a hand-authored one) has no source: the
+					// picture it points at IS the original, because nothing has
+					// been cut from it yet.
+					sourceAssetId: typeof record.sourceAssetId === "string" && record.sourceAssetId ? record.sourceAssetId : record.assetId,
+					matteAssetId: typeof record.matteAssetId === "string" ? record.matteAssetId : "",
+					matteScale: clamp(pick(record.matteScale, 1), 0.01, 1),
+					aspect: cutoutAspect(pick(record.aspect, 1)),
+					footprint: cutoutFootprint(pick(record.height, CUTOUT_DEFAULT_HEIGHT), pick(record.aspect, 1)),
+					height: cutoutHeight(pick(record.height, CUTOUT_DEFAULT_HEIGHT)),
+				}
+			: { footprint: { ...entry.footprint }, height: entry.height }),
 	};
 }