cozyclay 1.2.0 → 1.3.0

package/src/project.js

@@ -0,0 +1,289 @@
+/**
+ * CozyClay project files — game-engine style.
+ *
+ * A project is ONE file (`.cclayproject`, JSON) holding the full authoring
+ * state: the scene document (scenes + cast + animation layers), the
+ * workspace layout, and the custom pose library. Editor preferences
+ * (theme, locale) deliberately stay OUT — they belong to the operator, not
+ * the project.
+ *
+ * Files are read/written with the File System Access API when available,
+ * with a plain download/upload fallback. The last-used handle is kept in
+ * IndexedDB so a refresh can re-open the same project when the browser
+ * still grants access.
+ */
+
+import { SCENES_VERSION } from "./scenes.js";
+
+export const PROJECT_VERSION = 1;
+export const PROJECT_EXTENSION = ".cclayproject";
+const IDB_NAME = "cozyclay.project-handle.v1";
+const IDB_STORE = "kv";
+const IDB_KEY = "lastProjectHandle";
+
+/* ------------------------------- envelope ------------------------------- */
+
+export function createProjectDocument({ scenesDocument, workspaceLayout, customPoses, name }) {
+	return {
+		app: "cozyclay",
+		kind: "project",
+		version: PROJECT_VERSION,
+		name: typeof name === "string" && name.trim() ? name.trim() : "Untitled",
+		scenes: scenesDocument,
+		workspace: workspaceLayout ?? null,
+		poseLibrary: Array.isArray(customPoses) ? customPoses : [],
+	};
+}
+
+/** Parse + validate a project file. Returns { ok, reason?, project? }. */
+export function readProjectDocument(raw) {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return { ok: false, reason: "corrupt" };
+	}
+	if (!parsed || typeof parsed !== "object") return { ok: false, reason: "corrupt" };
+	if (parsed.app !== "cozyclay" || parsed.kind !== "project") return { ok: false, reason: "not-a-project" };
+	if (typeof parsed.version !== "number") return { ok: false, reason: "corrupt" };
+	if (parsed.version > PROJECT_VERSION) return { ok: false, reason: "future" };
+	const scenes = parsed.scenes;
+	if (!scenes || typeof scenes !== "object" || scenes.version > SCENES_VERSION || !Array.isArray(scenes.scenes)) {
+		return { ok: false, reason: "scenes-invalid" };
+	}
+	return {
+		ok: true,
+		project: {
+			name: typeof parsed.name === "string" && parsed.name.trim() ? parsed.name.trim() : "Untitled",
+			scenesDocument: { version: scenes.version, activeSceneId: scenes.activeSceneId ?? null, scenes: scenes.scenes },
+			workspaceLayout: parsed.workspace && typeof parsed.workspace === "object" ? parsed.workspace : null,
+			customPoses: Array.isArray(parsed.poseLibrary)
+				? parsed.poseLibrary.filter((p) => p && typeof p === "object" && typeof p.id === "string" && p.bones && typeof p.bones === "object")
+				: [],
+		},
+	};
+}
+
+/* ------------------------- file system access --------------------------- */
+
+export function hasFileSystemAccess() {
+	return typeof window !== "undefined" && typeof window.showSaveFilePicker === "function" && typeof window.showOpenFilePicker === "function";
+}
+
+const PICKER_TYPES = [
+	{
+		description: "CozyClay Project",
+		accept: { "application/json": [PROJECT_EXTENSION, ".json"] },
+	},
+];
+
+export async function pickProjectFileForSave(suggestedName) {
+	const handle = await window.showSaveFilePicker({
+		suggestedName: `${suggestedName || "Untitled"}${PROJECT_EXTENSION}`,
+		types: PICKER_TYPES,
+	});
+	return handle;
+}
+
+export async function pickProjectFileForOpen() {
+	const [handle] = await window.showOpenFilePicker({ types: PICKER_TYPES, multiple: false });
+	return handle;
+}
+
+export async function writeProjectFile(handle, serialized) {
+	const writable = await handle.createWritable();
+	await writable.write(serialized);
+	await writable.close();
+}
+
+export async function readProjectFile(handle) {
+	const file = await handle.getFile();
+	return { name: file.name.replace(/\.cclayproject$|\.json$/i, ""), text: await file.text() };
+}
+
+/* --------------------------- fallback (no FS API) ------------------------ */
+
+export function downloadProjectFallback(serialized, name) {
+	const blob = new Blob([serialized], { type: "application/json" });
+	const url = URL.createObjectURL(blob);
+	const anchor = document.createElement("a");
+	anchor.href = url;
+	anchor.download = `${name || "Untitled"}${PROJECT_EXTENSION}`;
+	anchor.click();
+	setTimeout(() => URL.revokeObjectURL(url), 1000);
+}
+
+export function openProjectFallback() {
+	return new Promise((resolve) => {
+		const input = document.createElement("input");
+		input.type = "file";
+		input.accept = `${PROJECT_EXTENSION},.json,application/json`;
+		input.onchange = async () => {
+			const file = input.files?.[0];
+			if (!file) return resolve(null);
+			resolve({ name: file.name.replace(/\.cclayproject$|\.json$/i, ""), text: await file.text() });
+		};
+		input.oncancel = () => resolve(null);
+		input.click();
+	});
+}
+
+/* ------------------------------- IDB handle ------------------------------ */
+
+function openIdb() {
+	return new Promise((resolve, reject) => {
+		const request = indexedDB.open(IDB_NAME, 1);
+		request.onupgradeneeded = () => request.result.createObjectStore(IDB_STORE);
+		request.onsuccess = () => resolve(request.result);
+		request.onerror = () => reject(request.error);
+	});
+}
+
+export async function storeProjectHandle(handle, name) {
+	try {
+		const db = await openIdb();
+		await new Promise((resolve, reject) => {
+			const tx = db.transaction(IDB_STORE, "readwrite");
+			tx.objectStore(IDB_STORE).put({ handle, name }, IDB_KEY);
+			tx.oncomplete = resolve;
+			tx.onerror = () => reject(tx.error);
+		});
+		db.close();
+	} catch {
+		/* private mode etc.: the session just won't remember the handle */
+	}
+}
+
+export async function loadStoredProjectHandle() {
+	try {
+		const db = await openIdb();
+		const record = await new Promise((resolve, reject) => {
+			const tx = db.transaction(IDB_STORE, "readonly");
+			const request = tx.objectStore(IDB_STORE).get(IDB_KEY);
+			request.onsuccess = () => resolve(request.result ?? null);
+			request.onerror = () => reject(request.error);
+		});
+		db.close();
+		return record;
+	} catch {
+		return null;
+	}
+}
+
+export async function clearStoredProjectHandle() {
+	try {
+		const db = await openIdb();
+		await new Promise((resolve, reject) => {
+			const tx = db.transaction(IDB_STORE, "readwrite");
+			tx.objectStore(IDB_STORE).delete(IDB_KEY);
+			tx.oncomplete = resolve;
+			tx.onerror = () => reject(tx.error);
+		});
+	db.close();
+	} catch {
+		/* ignore */
+	}
+}
+
+/* --------------------- recent projects + projects folder ---------------------
+ * The browser (game-engine style project picker) needs two things the File
+ * System Access API cannot give for free: a HISTORY of what was opened
+ * (stored here), and an optional directory handle it can enumerate. */
+
+const RECENTS_KEY = "recentProjects";
+const FOLDER_KEY = "projectsDirectory";
+const RECENTS_MAX = 8;
+
+async function idbSet(key, value) {
+	try {
+		const db = await openIdb();
+		await new Promise((resolve, reject) => {
+			const tx = db.transaction(IDB_STORE, "readwrite");
+			tx.objectStore(IDB_STORE).put(value, key);
+			tx.oncomplete = resolve;
+			tx.onerror = () => reject(tx.error);
+		});
+		db.close();
+	} catch {
+		/* private mode etc. */
+	}
+}
+
+async function idbGet(key) {
+	try {
+		const db = await openIdb();
+		const record = await new Promise((resolve, reject) => {
+			const tx = db.transaction(IDB_STORE, "readonly");
+			const request = tx.objectStore(IDB_STORE).get(key);
+			request.onsuccess = () => resolve(request.result ?? null);
+			request.onerror = () => reject(request.error);
+		});
+	db.close();
+		return record;
+	} catch {
+		return null;
+	}
+}
+
+/** Record a project open/save in the recents list (most recent first). */
+export async function rememberRecentProject(handle, name) {
+	const list = (await idbGet(RECENTS_KEY)) ?? [];
+	const next = [
+		{ handle, name, openedAt: Date.now() },
+		...list.filter((entry) => entry.name !== name),
+	].slice(0, RECENTS_MAX);
+	await idbSet(RECENTS_KEY, next);
+	await storeProjectHandle(handle, name);
+}
+
+export async function loadRecentProjects() {
+	return (await idbGet(RECENTS_KEY)) ?? [];
+}
+
+export async function removeRecentProject(name) {
+	const list = (await idbGet(RECENTS_KEY)) ?? [];
+	await idbSet(RECENTS_KEY, list.filter((entry) => entry.name !== name));
+}
+
+/* Projects directory: optional; when set, the browser can LIST the folder. */
+
+export function hasDirectoryPicker() {
+	return typeof window !== "undefined" && typeof window.showDirectoryPicker === "function";
+}
+
+export async function pickProjectsDirectory() {
+	return window.showDirectoryPicker({ mode: "readwrite" });
+}
+
+export async function storeProjectsDirectory(handle) {
+	await idbSet(FOLDER_KEY, { handle });
+}
+
+export async function loadProjectsDirectory() {
+	const record = await idbGet(FOLDER_KEY);
+	return record?.handle ?? null;
+}
+
+/** Enumerate `.cclayproject` files in a directory handle, newest first. */
+export async function listProjectsInDirectory(dirHandle) {
+	const out = [];
+	try {
+		for await (const [name, handle] of dirHandle.entries()) {
+			if (handle.kind !== "file" || !name.endsWith(PROJECT_EXTENSION)) continue;
+			const file = await handle.getFile();
+			out.push({ name: name.slice(0, -PROJECT_EXTENSION.length), handle, lastModified: file.lastModified });
+		}
+	} catch {
+		return [];
+	}
+	return out.sort((a, b) => b.lastModified - a.lastModified);
+}
+
+/** "granted" | "prompt" | "denied" — never throws. */
+export async function queryHandlePermission(handle) {
+	try {
+		return await handle.queryPermission({ mode: "readwrite" });
+	} catch {
+		return "denied";
+	}
+}

package/src/props.jsx

@@ -9,9 +9,11 @@
  * the 1.8 m figure keeps honest scale.
  */
 
-import { useEffect, useMemo } from "react";
+import { useEffect, useMemo, useState } from "react";
 import * as THREE from "three";
 import { GIZMO_LAYER } from "./dualview.jsx";
+import { CUTOUT_KIND } from "./scene-objects.js";
+import { subscribeToAssetTexture } from "./scene-asset-cache.js";
 
 const CLAY_CAR = "#d98770";
 const CLAY_CAR_TOP = "#e49a84";
@@ -230,9 +232,73 @@ function Primitive({ kind, color }) {
 	);
 }
 
+/** The texture behind an `assetId`, or null while it loads (or forever, if the
+ * picture is gone). Subscribing rather than loading here means the same
+ * picture on two cards is one decode. */
+function useAssetTexture(assetId) {
+	const [texture, setTexture] = useState(null);
+	useEffect(() => {
+		setTexture(null);
+		if (!assetId) return undefined;
+		return subscribeToAssetTexture(assetId, setTexture);
+	}, [assetId]);
+	return texture;
+}
+
+/** The placeholder tint for a card whose picture has not arrived (or has gone
+ * missing): blockout grey, because that is exactly what it is again. */
+const MISSING_CUTOUT = "#c2c6c8";
+
+/**
+ * A cutout: an imported picture standing on a card, the standee a blockout
+ * gets instead of a modelled prop.
+ *
+ * The card is built base-on-the-floor like every primitive, and sized in
+ * metres by the record — `footprint.width` is already derived from the
+ * measured height and the picture's aspect, so the geometry never has to do
+ * that arithmetic again.
+ *
+ * Alpha-CUT, not blended: `alphaTest` keeps the card writing depth, which is
+ * what lets the ink pass, the shadows and the grey boxes all agree about what
+ * is in front of what. A blended card would sort by object and swim through
+ * the set.
+ *
+ * But a bare alpha test is a decision per pixel, so the silhouette comes out
+ * as a staircase — and the matte's own soft edge is thrown away at the
+ * threshold. `alphaToCoverage` spends the MSAA samples the canvas already has
+ * on that edge instead: partial alpha becomes partial coverage, so the outline
+ * is resolved by the same antialiasing that smooths every other edge in the
+ * frame, and depth is still written. The test then only has to reject what is
+ * genuinely nothing (0.15), rather than choosing a side for every half-lit
+ * pixel — which is also what keeps a thin structure alive as the card recedes
+ * and its alpha is averaged down by the mip chain.
+ */
+function Cutout({ object }) {
+	const texture = useAssetTexture(object.assetId);
+	const width = object.footprint?.width ?? 1;
+	const height = object.height ?? 1;
+	return (
+		<mesh position={[0, height / 2, 0]} castShadow receiveShadow userData={{ cutoutTexture: texture ?? null }}>
+			<planeGeometry args={[width, height]} />
+			<meshStandardMaterial
+				map={texture ?? null}
+				color={texture ? object.color : MISSING_CUTOUT}
+				// A card seen edge-on is a card, not a hole: both faces draw.
+				side={THREE.DoubleSide}
+				alphaTest={texture ? 0.15 : 0}
+				alphaToCoverage={!!texture}
+				roughness={0.92}
+				metalness={0}
+			/>
+		</mesh>
+	);
+}
+
 const PRIMITIVE_KINDS = new Set(["cube", "sphere", "capsule", "cylinder", "cone", "plane"]);
 
-function SceneObjectContent({ renderer, color }) {
+function SceneObjectContent({ object }) {
+	const { renderer, color } = object;
+	if (renderer === CUTOUT_KIND) return <Cutout object={object} />;
 	if (renderer === "car") return <Car color={color} />;
 	if (renderer === "small-plane") return <SmallPlane />;
 	if (renderer === "chair") return <Chair />;
@@ -284,7 +350,7 @@ function SceneObject({ object, selected }) {
 			// the viewport picker walks up from a hit mesh to find this id
 			userData={{ sceneObjectId: object.id }}
 		>
-			<SceneObjectContent renderer={object.renderer} color={object.color} />
+			<SceneObjectContent object={object} />
 			{selected && <SelectionBox object={object} />}
 		</group>
 	);

package/src/room.jsx

@@ -1,51 +1,30 @@
 /**
- * The blocking set: an open room corner.
+ * The blocking set: an open stage floor.
  *
- * A blocking frame needs walls far more than it needs a pretty floor. An
- * infinite grid gives an AI model no sense of enclosure, so depth, headroom and
- * the horizon line all read as ambiguous. Two perpendicular walls and a floor
- * preserve that context without enclosing the camera in a box.
+ * The set used to be a two-walled room corner, which kept AI blocking frames
+ * enclosed but boxed the camera and capped how far a run or a chase could be
+ * staged. The walls are gone: the stage is now a near-infinite open deck —
+ * large enough that no ordinary blocking ever meets its edge — and enclosure,
+ * when a shot needs it, comes from placed set pieces instead of the stage.
  *
- * Dimensions are metres and stage-sized (24 x 24) so a 1.8 m figure has room
- * to walk real paths while the corner still reads as an enclosure.
+ * Dimensions are metres. The floor is deliberately finite (a plane, not a
+ * shader-infinite grid) so exports keep a clean horizon and the framing math
+ * never meets an unbounded surface.
  */
 
-const FLOOR = "#e7e1d7";
-const BACK_WALL = "#eef1ed";
-const SIDE_WALL = "#e4ecec";
-const SKIRTING = "#bdcccc";
+// Bright enough to sit clearly above the grid lines: the deck reads as a lit
+// surface with lines drawn ON it, not as a dark line-texture tiling to the fog.
+const FLOOR = "#f4f0e8";
 
-const SIZE = 24;
-const HEIGHT = 6.2;
-const BACK_Z = -10;
-function Skirting({ position, rotation }) {
-	return (
-		<mesh position={position} rotation={rotation}>
-			<boxGeometry args={[SIZE, 0.16, 0.06]} />
-			<meshBasicMaterial color={SKIRTING} />
-		</mesh>
-	);
-}
+export const STAGE_SIZE = 500;
 
 export function Room() {
 	return (
 		<group>
 			<mesh rotation={[-Math.PI / 2, 0, 0]} position={[0, 0, 0]}>
-				<planeGeometry args={[SIZE, SIZE]} />
+				<planeGeometry args={[STAGE_SIZE, STAGE_SIZE]} />
 				<meshBasicMaterial color={FLOOR} />
 			</mesh>
-
-			<mesh position={[0, HEIGHT / 2, BACK_Z]}>
-				<planeGeometry args={[SIZE, HEIGHT]} />
-				<meshBasicMaterial color={BACK_WALL} />
-			</mesh>
-			<mesh position={[-SIZE / 2, HEIGHT / 2, 0]} rotation={[0, Math.PI / 2, 0]}>
-				<planeGeometry args={[SIZE, HEIGHT]} />
-				<meshBasicMaterial color={SIDE_WALL} />
-			</mesh>
-
-			<Skirting position={[0, 0.08, BACK_Z + 0.03]} rotation={[0, 0, 0]} />
-			<Skirting position={[-SIZE / 2 + 0.03, 0.08, 0]} rotation={[0, Math.PI / 2, 0]} />
 		</group>
 	);
 }

package/src/scene-asset-cache.js

@@ -0,0 +1,125 @@
+/**
+ * The bridge between stored asset bytes and a texture the set can wear.
+ *
+ * A cutout record holds an `assetId` and nothing else, so something has to
+ * turn that id into a THREE.Texture exactly once per session: the same picture
+ * on two cards, or on cards in two scenes, is one decode and one upload.
+ *
+ * Loading is async and the renderer is not, so `useAssetTexture` (props.jsx)
+ * subscribes and re-renders when the texture lands. A card with no texture yet
+ * draws as a blank placeholder rather than popping into existence — the
+ * geometry is already correct, and that is what blocking needs first.
+ */
+
+import * as THREE from "three";
+import { getAsset, openAssetDb, putAsset } from "./scene-assets.js";
+
+/** id → { texture, promise, listeners } */
+const entries = new Map();
+let dbPromise = null;
+
+function db() {
+	if (!dbPromise) dbPromise = openAssetDb();
+	return dbPromise;
+}
+
+function entryFor(id) {
+	let entry = entries.get(id);
+	if (!entry) {
+		entry = { texture: null, record: null, promise: null, listeners: new Set() };
+		entries.set(id, entry);
+	}
+	return entry;
+}
+
+function announce(entry) {
+	for (const listener of entry.listeners) listener(entry.texture);
+}
+
+/**
+ * A texture from asset bytes. ImageBitmap ignores `Texture.flipY`, so the flip
+ * is asked of the decoder instead — without it every cutout hangs upside down.
+ */
+async function textureFromAsset(asset) {
+	const bitmap = await createImageBitmap(new Blob([asset.bytes], { type: asset.type }), { imageOrientation: "flipY" });
+	const texture = new THREE.Texture(bitmap);
+	texture.flipY = false;
+	texture.colorSpace = THREE.SRGBColorSpace;
+	texture.generateMipmaps = true;
+	texture.minFilter = THREE.LinearMipmapLinearFilter;
+	texture.magFilter = THREE.LinearFilter;
+	// A card is nearly always seen at an angle; without anisotropy the picture
+	// smears the moment the camera is off its normal.
+	texture.anisotropy = 4;
+	texture.needsUpdate = true;
+	texture.userData.assetId = asset.id;
+	return texture;
+}
+
+/** The texture for this id, decoded once and shared. Null when the asset is
+ * gone — a scene can outlive its pictures (another browser, cleared storage),
+ * and a missing picture must not take the studio down with it. */
+export function loadAssetTexture(id) {
+	if (typeof id !== "string" || !id) return Promise.resolve(null);
+	const entry = entryFor(id);
+	if (entry.texture) return Promise.resolve(entry.texture);
+	if (!entry.promise) {
+		entry.promise = (async () => {
+			const asset = entry.record ?? (await getAsset(await db(), id));
+			if (!asset) return null;
+			entry.record = asset;
+			entry.texture = await textureFromAsset(asset);
+			announce(entry);
+			return entry.texture;
+		})().catch((error) => {
+			console.warn(`[cozyclay] could not load image asset ${id}`, error);
+			return null;
+		});
+	}
+	return entry.promise;
+}
+
+/** The stored record behind an id — the bytes, not the texture. Editing a
+ * picture (cutting its background out) needs the source it started from. */
+export async function assetRecord(id) {
+	if (typeof id !== "string" || !id) return null;
+	const entry = entryFor(id);
+	if (entry.record) return entry.record;
+	entry.record = await getAsset(await db(), id);
+	return entry.record;
+}
+
+/** Warm the cache with an asset that is already in hand. An import has the
+ * decoded bytes right there; going back to IndexedDB for them would decode the
+ * same picture twice and delay the card by a frame or two. */
+export async function rememberAsset(asset) {
+	const stored = await putAsset(await db(), asset);
+	const entry = entryFor(stored.id);
+	entry.record = stored;
+	entry.texture?.dispose();
+	entry.texture = await textureFromAsset(stored);
+	entry.promise = Promise.resolve(entry.texture);
+	announce(entry);
+	return stored;
+}
+
+/** Subscribe to one id; returns an unsubscribe. The listener fires
+ * immediately when the texture is already cached, so a mount never waits a
+ * frame for something that is in memory. */
+export function subscribeToAssetTexture(id, listener) {
+	if (typeof id !== "string" || !id) return () => {};
+	const entry = entryFor(id);
+	entry.listeners.add(listener);
+	if (entry.texture) listener(entry.texture);
+	else loadAssetTexture(id);
+	return () => entry.listeners.delete(listener);
+}
+
+/** Drop everything (a test harness, or a hard document reload). */
+export function clearAssetTextures() {
+	for (const entry of entries.values()) {
+		entry.texture?.image?.close?.();
+		entry.texture?.dispose();
+	}
+	entries.clear();
+}