cozyclay 2.0.2 → 2.1.1

package/src/agent-image-client.js

@@ -0,0 +1,94 @@
+// The sidecar's /agent/image request, shared by the Workflow (agent-client.js)
+// and the Studio's Board panel Stylize, so the Studio can generate a picture
+// without pulling the Workflow bundle in. Plain fetch, no React, no imports
+// beyond the locale and the shot prompt.
+
+import { ko } from "./locale.js";
+import { buildShotPrompt } from "./shot-prompt.js";
+
+const SIDECAR_ORIGIN = "";
+
+export function sidecarUrl(path) {
+	return `${SIDECAR_ORIGIN}${path}`;
+}
+
+/** One JSON request to the loopback sidecar. A refusal throws an Error whose
+ * message is the sidecar's own (already sanitized) explanation, with `status`
+ * and the structured error fields (`code`, ...) copied onto it. */
+export async function sidecarRequest(fetchImpl, path, init) {
+	const response = await fetchImpl(sidecarUrl(path), {
+		headers: { "content-type": "application/json" },
+		...init,
+	});
+	if (!response.ok) {
+		let detail = null;
+		try { detail = await response.clone().json(); } catch { /* preserve the status when the server did not send JSON */ }
+		const message = typeof detail?.error === "string" ? detail.error : detail?.error?.message;
+		const error = new Error(message || `${path} responded ${response.status}`);
+		// Keep machine-readable verification evidence alongside the human message.
+		// The Workflow node can show why an H3 take was rejected without exposing
+		// or retaining the rejected video itself.
+		error.status = response.status;
+		if (detail?.error && typeof detail.error === "object") Object.assign(error, detail.error);
+		if (detail?.preservation && typeof detail.preservation === "object") error.preservation = detail.preservation;
+		throw error;
+	}
+	return response.json();
+}
+
+/** The /agent/image body. `references` are the scene's identity / environment
+ * slots (#167), passed through untouched so the sidecar decides how they are
+ * described to the model. */
+export function agentImageBody({ prompt, imageDataUrl, referenceDataUrl, references, composition, quality = "auto", size }) {
+	return {
+		prompt,
+		imageDataUrl,
+		...(referenceDataUrl ? { referenceDataUrl } : {}),
+		...(Array.isArray(references) && references.length ? { references } : {}),
+		...(composition ? { composition } : {}),
+		quality,
+		...(size ? { size } : {}),
+	};
+}
+
+/** POST /agent/image; answers `{ dataUrl, width, height }`. */
+export function requestAgentImage(payload, { fetchImpl = globalThis.fetch?.bind(globalThis), signal } = {}) {
+	return sidecarRequest(fetchImpl, "/agent/image", { method: "POST", body: JSON.stringify(agentImageBody(payload)), signal });
+}
+
+// The clay-frame preamble the sidecar puts in front of a hand-framed picture
+// (bin/agent/agent-routes.mjs FRAME_COMPOSITION_GUIDANCE). The browser cannot
+// import the sidecar, so the words are carried here and a test keeps the two
+// copies equal.
+export const CLAY_FRAME_PREAMBLE = "Use the first image (a clay blocking frame) as the layout: keep its composition and camera angle, and keep the pose but make it look natural. Render it as:";
+
+/** The request that stylizes one storyboard panel: the clay preamble, the
+ * shot's labelled image prompt, then the panel's caption. */
+export function panelStylizeRequest({ meta, caption, imageDataUrl }) {
+	const line = typeof caption === "string" ? caption.trim() : "";
+	const prompt = `${CLAY_FRAME_PREAMBLE}\n${buildShotPrompt(meta, { target: "image" })}${line ? `\n${line}` : ""}`;
+	return { prompt, imageDataUrl, quality: "auto" };
+}
+
+/** What a failed Stylize tells the author: the route's explanation, with the
+ * two refusals an author can act on worded for them. */
+export function stylizeErrorMessage(error) {
+	if (error?.code === "entitlement") return ko("This account cannot generate images.", "이 계정은 이미지를 생성할 수 없어요.");
+	if (error?.status === 401 || error?.code === "auth") return ko("Sign in with ChatGPT in the Agent panel first.", "먼저 Agent 패널에서 ChatGPT로 로그인하세요.");
+	const reason = error?.message || ko("unknown error", "알 수 없는 오류");
+	return ko(`Stylize failed — ${reason}`, `스타일화 실패 — ${reason}`);
+}
+
+/** The generated PNG's bytes, refused past `maxBytes` with a reason. */
+export function stylizedPngBytes(dataUrl, maxBytes) {
+	const match = typeof dataUrl === "string" ? /^data:image\/png;base64,(.*)$/s.exec(dataUrl) : null;
+	if (!match) throw new Error(ko("The image route did not return a PNG.", "이미지 경로가 PNG를 돌려주지 않았어요."));
+	const binary = atob(match[1]);
+	if (binary.length > maxBytes) {
+		const mb = Math.round(maxBytes / (1024 * 1024));
+		throw new Error(ko(`The stylized image is larger than ${mb} MB, so it was not added.`, `스타일화된 이미지가 ${mb} MB보다 커서 추가하지 않았어요.`));
+	}
+	const bytes = new Uint8Array(binary.length);
+	for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index);
+	return bytes;
+}

package/src/analytics.js

@@ -62,6 +62,14 @@ export const EXECUTION_TELEMETRY_VALUES = Object.freeze({
 	outcome: new Set(["succeeded", "failed", "uncertain", "cancelled"]),
 });
 
+// Closed values for the storyboard and capsule-figure events. Counts only: no
+// caption, name, prompt or id ever rides along.
+const PREVIS_PROPERTY_VALUES = Object.freeze({
+	source: new Set(["agent", "manual"]),
+	outcome: new Set(["ok", "error"]),
+	surface: new Set(["assets", "agent", "mcp"]),
+});
+
 const OPT_OUT_KEY = "cozyclay.analyticsOptOut";
 const INTERNAL_QA_KEY = "cozyclay.internalQa";
 const ACTIVATION_KEY = "cozyclay.analyticsActivation";
@@ -79,6 +87,8 @@ export const EDIT_GROUPS = Object.freeze({
 export const EDIT_BUCKET_KEYS = Object.freeze(Object.keys(EDIT_GROUPS).map((group) => `${group}_edit_bucket`));
 export const USE_CASE_VALUES = Object.freeze(["animation", "film", "game", "ad_mv", "personal", "other", "skip"]);
 export const TEAM_VALUES = Object.freeze(["team", "solo", "skip"]);
+// Mirrors PREVIS_MODES in project.js; kept local so analytics stays import-light.
+export const PREVIS_MODE_VALUES = new Set(["storyboard", "animation"]);
 export const UPDATE_STATUS_VALUES = Object.freeze(["latest", "outdated", "unknown"]);
 const DEFAULT_ALLOWED_ORIGINS = Object.freeze([
 	"https://cozyclay.org",
@@ -97,7 +107,10 @@ const EVENT_PROPERTIES = Object.freeze({
 	"hosted:ticket_created": [],
 	"hosted:result_opened": [],
 	"hosted:opened_in_studio": [],
-	"scene:created": ["scene_source"],
+	"scene:created": ["scene_source", "previs_mode"],
+	"storyboard:panel_created": ["source"],
+	"storyboard:panel_stylized": ["outcome"],
+	"cast:proxy_added": ["surface"],
 	"scene:loaded": ["scene_source"],
 	"project:saved": ["object_count_bucket", "shot_count_bucket"],
 	"project:opened": ["age_bucket"],
@@ -128,6 +141,7 @@ const EVENT_PROPERTIES = Object.freeze({
 	"tutorial:step_completed": ["surface", "tutorial_version", "step_kind", "elapsed_bucket"],
 	"tutorial:completed": ["surface", "tutorial_version", "elapsed_bucket"],
 	"tutorial:dismissed": ["surface", "tutorial_version", "step_kind"],
+	"sculpt_run": ["outcome", "rounds", "final_iou", "duration_ms", "had_target"],
 	...EXECUTION_TELEMETRY_PROPERTY_KEYS,
 });
 const FEATURE_NAMES = new Set([
@@ -156,8 +170,8 @@ const MOTION_PROPERTY_VALUES = Object.freeze({
 });
 const EXPORT_FAILURE_CODES = new Set(["unsupported_codec", "encode_failed", "render_failed", "aborted", "unknown"]);
 const EXPORT_PROPERTY_VALUES = Object.freeze({
-	export_kind: new Set(["video", "depth_video", "frame", "keyframe_pack"]),
-	format: new Set(["mp4", "png", "zip"]),
+	export_kind: new Set(["video", "depth_video", "frame", "keyframe_pack", "workflow_send", "animation_project", "contact_sheet", "panel_pack", "animatic"]),
+	format: new Set(["mp4", "png", "zip", "cclayproject"]),
 	surface: new Set(["studio", "workflow", "embed"]),
 	duration_bucket: new Set(["lt1s", "1-3s", "3-10s", "10-30s", "gte30s"]),
 	failure_code: EXPORT_FAILURE_CODES,
@@ -169,6 +183,11 @@ const TUTORIAL_PROPERTY_VALUES = Object.freeze({
 	step_kind: new Set(["fly", "walk", "dolly", "orbit", "shot", "rail", "play"]),
 	elapsed_bucket: new Set(["lt1s", "1-3s", "3-10s", "10-30s", "gte30s"]),
 });
+// Sculpt mode (#739): one sculpt_run per finished run. Numbers only: no
+// reference image, recipe, part name or sculpt id ever rides along.
+export const SCULPT_RUN_OUTCOMES = Object.freeze(["done", "cancelled", "failed"]);
+const SCULPT_RUN_MAX_ROUNDS = 10;
+const SCULPT_RUN_MAX_DURATION_MS = 86_400_000;
 const EXECUTION_FAILURE_CODES = Object.freeze({
 	workflow: new Set(["aborted", "capture_failed", "generation_failed", "unknown"]),
 	agent: new Set(["aborted", "auth", "rate_limited", "tool_failed", "upstream", "unknown"]),
@@ -333,6 +352,17 @@ export function sanitizeProps(event, props) {
 			if (!ERROR_PROPERTY_VALUES[key]?.has(props[key])) continue;
 		}
 		if (event === "device:profile" && !DEVICE_PROPERTY_VALUES[key]?.has(props[key])) continue;
+		if (event === "sculpt_run") {
+			const value = props[key];
+			if (key === "outcome" && SCULPT_RUN_OUTCOMES.includes(value)) sanitized[key] = value;
+			else if (key === "rounds" && Number.isInteger(value) && value >= 0 && value <= SCULPT_RUN_MAX_ROUNDS) sanitized[key] = value;
+			else if (key === "final_iou" && typeof value === "number" && value >= 0 && value <= 1) sanitized[key] = Math.round(value * 100) / 100;
+			else if (key === "duration_ms" && typeof value === "number" && value >= 0 && value <= SCULPT_RUN_MAX_DURATION_MS) sanitized[key] = Math.round(value);
+			else if (key === "had_target" && typeof value === "boolean") sanitized[key] = value;
+			continue;
+		}
+		if (key === "previs_mode" && !PREVIS_MODE_VALUES.has(props[key])) continue;
+		if ((event.startsWith("storyboard:") || event.startsWith("cast:")) && !PREVIS_PROPERTY_VALUES[key]?.has(props[key])) continue;
 		if (event === "survey:use_case") {
 			if (key === "use_case" && !USE_CASE_VALUES.includes(props[key])) continue;
 			if (key === "team" && !TEAM_VALUES.includes(props[key])) continue;
@@ -1066,6 +1096,20 @@ export function track(event, props = {}) {
 	}
 }
 
+/** The sculpt_run payload for a sculpt-run state (src/sculpt-run.js), or null
+ * while the run has not ended. `hadTarget`: the run re-sculpted an existing
+ * sculpt rather than creating one. An unscored run omits final_iou. */
+export function sculptRunTelemetry(state, { hadTarget = false } = {}) {
+	if (!SCULPT_RUN_OUTCOMES.includes(state?.stage)) return null;
+	return {
+		outcome: state.stage,
+		rounds: state.round,
+		...(Number.isFinite(state.iou) ? { final_iou: Math.round(state.iou * 100) / 100 } : {}),
+		duration_ms: Math.round(state.elapsedMs),
+		had_target: Boolean(hadTarget),
+	};
+}
+
 export function trackFeature(name) {
 	if (!initialized || !enabled || !posthog || !FEATURE_NAMES.has(name) || featureNamesSeen.has(name)) return false;
 	featureNamesSeen.add(name);