@getuserfeedback/protocol 3.0.8 → 3.0.10

package/dist/host/index.d.ts

@@ -12,4 +12,5 @@ export { createCommandRequestId } from "./request-id.js";
 export * from "./sdk-types.js";
 export { createUniqueId } from "./unique-id.js";
 export * from "./widget-layout-size-update.js";
+export * from "./widget-layout-transition-plan.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/host/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/host/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kCAAkC,CAAC;AACjD,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzD,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,cAAc,gCAAgC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/host/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kCAAkC,CAAC;AACjD,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzD,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,oCAAoC,CAAC"}

package/dist/host/index.js

@@ -12,3 +12,4 @@ export { createCommandRequestId } from "./request-id.js";
 export * from "./sdk-types.js";
 export { createUniqueId } from "./unique-id.js";
 export * from "./widget-layout-size-update.js";
+export * from "./widget-layout-transition-plan.js";

package/dist/host/widget-layout-size-update.d.ts

@@ -2,14 +2,43 @@ export type WidgetLayoutSize = {
     width: number;
     height: number;
 };
-export type WidgetLayoutSizeTransition = {
+export type WidgetLayoutCubicBezier = readonly [
+    x1: number,
+    y1: number,
+    x2: number,
+    y2: number
+];
+export type WidgetLayoutInstantSizeTransition = {
     kind: "instant";
     durationMs: 0;
 };
+export type WidgetLayoutTimedSizeTransition = {
+    kind: "timed";
+    durationMs: number;
+    easing: {
+        kind: "cubic-bezier";
+        points: WidgetLayoutCubicBezier;
+    };
+};
+export type WidgetLayoutSizeTransition = WidgetLayoutInstantSizeTransition;
 export type WidgetLayoutSizeUpdate = {
     size: WidgetLayoutSize;
     transition: WidgetLayoutSizeTransition;
 };
-export declare const INSTANT_WIDGET_LAYOUT_SIZE_TRANSITION: WidgetLayoutSizeTransition;
+export type WidgetLayoutTimedSizeUpdate = {
+    size: WidgetLayoutSize;
+    transition: WidgetLayoutTimedSizeTransition;
+};
+export declare const INSTANT_WIDGET_LAYOUT_SIZE_TRANSITION: WidgetLayoutInstantSizeTransition;
+export declare function isWidgetLayoutCubicBezier(points: unknown): points is WidgetLayoutCubicBezier;
 export declare function toInstantWidgetLayoutSizeUpdate(size: WidgetLayoutSize): WidgetLayoutSizeUpdate;
+export declare function toTimedWidgetLayoutSizeTransition(input: {
+    durationMs: number;
+    easing: WidgetLayoutCubicBezier;
+}): WidgetLayoutTimedSizeTransition;
+export declare function toTimedWidgetLayoutSizeUpdate(input: {
+    size: WidgetLayoutSize;
+    durationMs: number;
+    easing: WidgetLayoutCubicBezier;
+}): WidgetLayoutTimedSizeUpdate;
 //# sourceMappingURL=widget-layout-size-update.d.ts.map

package/dist/host/widget-layout-size-update.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"widget-layout-size-update.d.ts","sourceRoot":"","sources":["../../src/host/widget-layout-size-update.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACxC,IAAI,EAAE,SAAS,CAAC;IAChB,UAAU,EAAE,CAAC,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACpC,IAAI,EAAE,gBAAgB,CAAC;IACvB,UAAU,EAAE,0BAA0B,CAAC;CACvC,CAAC;AAEF,eAAO,MAAM,qCAAqC,EAAE,0BAIlD,CAAC;AAEH,wBAAgB,+BAA+B,CAC9C,IAAI,EAAE,gBAAgB,GACpB,sBAAsB,CAKxB"}
+{"version":3,"file":"widget-layout-size-update.d.ts","sourceRoot":"","sources":["../../src/host/widget-layout-size-update.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,SAAS;IAC9C,EAAE,EAAE,MAAM;IACV,EAAE,EAAE,MAAM;IACV,EAAE,EAAE,MAAM;IACV,EAAE,EAAE,MAAM;CACV,CAAC;AAEF,MAAM,MAAM,iCAAiC,GAAG;IAC/C,IAAI,EAAE,SAAS,CAAC;IAChB,UAAU,EAAE,CAAC,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,+BAA+B,GAAG;IAC7C,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE;QACP,IAAI,EAAE,cAAc,CAAC;QACrB,MAAM,EAAE,uBAAuB,CAAC;KAChC,CAAC;CACF,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG,iCAAiC,CAAC;AAE3E,MAAM,MAAM,sBAAsB,GAAG;IACpC,IAAI,EAAE,gBAAgB,CAAC;IACvB,UAAU,EAAE,0BAA0B,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACzC,IAAI,EAAE,gBAAgB,CAAC;IACvB,UAAU,EAAE,+BAA+B,CAAC;CAC5C,CAAC;AAEF,eAAO,MAAM,qCAAqC,EAAE,iCAIlD,CAAC;AAKH,wBAAgB,yBAAyB,CACxC,MAAM,EAAE,OAAO,GACb,MAAM,IAAI,uBAAuB,CAenC;AAED,wBAAgB,+BAA+B,CAC9C,IAAI,EAAE,gBAAgB,GACpB,sBAAsB,CAKxB;AAED,wBAAgB,iCAAiC,CAAC,KAAK,EAAE;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,uBAAuB,CAAC;CAChC,GAAG,+BAA+B,CAmBlC;AAED,wBAAgB,6BAA6B,CAAC,KAAK,EAAE;IACpD,IAAI,EAAE,gBAAgB,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,uBAAuB,CAAC;CAChC,GAAG,2BAA2B,CAQ9B"}

package/dist/host/widget-layout-size-update.js

@@ -2,9 +2,49 @@ export const INSTANT_WIDGET_LAYOUT_SIZE_TRANSITION = {
     kind: "instant",
     durationMs: 0,
 };
+const isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+export function isWidgetLayoutCubicBezier(points) {
+    if (!Array.isArray(points) || points.length !== 4) {
+        return false;
+    }
+    const [x1, y1, x2, y2] = points;
+    return (isFiniteNumber(x1) &&
+        x1 >= 0 &&
+        x1 <= 1 &&
+        isFiniteNumber(y1) &&
+        isFiniteNumber(x2) &&
+        x2 >= 0 &&
+        x2 <= 1 &&
+        isFiniteNumber(y2));
+}
 export function toInstantWidgetLayoutSizeUpdate(size) {
     return {
         size: { ...size },
         transition: INSTANT_WIDGET_LAYOUT_SIZE_TRANSITION,
     };
 }
+export function toTimedWidgetLayoutSizeTransition(input) {
+    if (!Number.isFinite(input.durationMs) || input.durationMs <= 0) {
+        throw new RangeError("Timed widget layout transitions require durationMs > 0");
+    }
+    if (!isWidgetLayoutCubicBezier(input.easing)) {
+        throw new RangeError("Timed widget layout transitions require cubic-bezier x control points in [0, 1] and finite y control points");
+    }
+    return {
+        kind: "timed",
+        durationMs: input.durationMs,
+        easing: {
+            kind: "cubic-bezier",
+            points: [...input.easing],
+        },
+    };
+}
+export function toTimedWidgetLayoutSizeUpdate(input) {
+    return {
+        size: { ...input.size },
+        transition: toTimedWidgetLayoutSizeTransition({
+            durationMs: input.durationMs,
+            easing: input.easing,
+        }),
+    };
+}

package/dist/host/widget-layout-transition-plan.d.ts

@@ -0,0 +1,23 @@
+import type { WidgetLayoutSize, WidgetLayoutSizeUpdate, WidgetLayoutTimedSizeUpdate } from "./widget-layout-size-update.js";
+export type WidgetLayoutComparableSizeUpdate = WidgetLayoutSizeUpdate | WidgetLayoutTimedSizeUpdate;
+export type WidgetLayoutUnchangedTransitionPlan = {
+    kind: "unchanged";
+    size: WidgetLayoutSize;
+    update: WidgetLayoutSizeUpdate;
+    observedAtMs: number;
+};
+export type WidgetLayoutInstantTransitionPlan = {
+    kind: "instant";
+    size: WidgetLayoutSize;
+    update: WidgetLayoutSizeUpdate;
+    startedAtMs: number;
+    settledAtMs: number;
+};
+export type WidgetLayoutTransitionPlan = WidgetLayoutUnchangedTransitionPlan | WidgetLayoutInstantTransitionPlan;
+export declare function areWidgetLayoutSizeUpdatesEqual(left: WidgetLayoutComparableSizeUpdate | undefined, right: WidgetLayoutComparableSizeUpdate): boolean;
+export declare function planWidgetLayoutTransition(input: {
+    previous?: WidgetLayoutSizeUpdate;
+    next: WidgetLayoutSizeUpdate;
+    nowMs: number;
+}): WidgetLayoutTransitionPlan;
+//# sourceMappingURL=widget-layout-transition-plan.d.ts.map

package/dist/host/widget-layout-transition-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-layout-transition-plan.d.ts","sourceRoot":"","sources":["../../src/host/widget-layout-transition-plan.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,gBAAgB,EAChB,sBAAsB,EACtB,2BAA2B,EAC3B,MAAM,gCAAgC,CAAC;AAExC,MAAM,MAAM,gCAAgC,GACzC,sBAAsB,GACtB,2BAA2B,CAAC;AAE/B,MAAM,MAAM,mCAAmC,GAAG;IACjD,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,gBAAgB,CAAC;IACvB,MAAM,EAAE,sBAAsB,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,iCAAiC,GAAG;IAC/C,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,gBAAgB,CAAC;IACvB,MAAM,EAAE,sBAAsB,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,0BAA0B,GACnC,mCAAmC,GACnC,iCAAiC,CAAC;AAErC,wBAAgB,+BAA+B,CAC9C,IAAI,EAAE,gCAAgC,GAAG,SAAS,EAClD,KAAK,EAAE,gCAAgC,GACrC,OAAO,CAiCT;AAED,wBAAgB,0BAA0B,CAAC,KAAK,EAAE;IACjD,QAAQ,CAAC,EAAE,sBAAsB,CAAC;IAClC,IAAI,EAAE,sBAAsB,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;CACd,GAAG,0BAA0B,CAyB7B"}

package/dist/host/widget-layout-transition-plan.js

@@ -0,0 +1,52 @@
+export function areWidgetLayoutSizeUpdatesEqual(left, right) {
+    if (left?.size.width !== right.size.width ||
+        left.size.height !== right.size.height ||
+        left.transition.kind !== right.transition.kind ||
+        left.transition.durationMs !== right.transition.durationMs) {
+        return false;
+    }
+    const leftTransition = left.transition;
+    const rightTransition = right.transition;
+    switch (rightTransition.kind) {
+        case "instant":
+            return true;
+        case "timed":
+            if (leftTransition.kind !== "timed") {
+                return false;
+            }
+            return (leftTransition.easing.kind === rightTransition.easing.kind &&
+                leftTransition.easing.points.length ===
+                    rightTransition.easing.points.length &&
+                leftTransition.easing.points.every((point, index) => point === rightTransition.easing.points[index]));
+        default: {
+            const unreachable = rightTransition;
+            throw new Error(`Unsupported widget layout transition: ${JSON.stringify(unreachable)}`);
+        }
+    }
+}
+export function planWidgetLayoutTransition(input) {
+    if (!Number.isFinite(input.nowMs)) {
+        throw new RangeError("Widget layout transition plans require finite nowMs");
+    }
+    if (areWidgetLayoutSizeUpdatesEqual(input.previous, input.next)) {
+        return {
+            kind: "unchanged",
+            size: { ...input.next.size },
+            update: {
+                size: { ...input.next.size },
+                transition: { ...input.next.transition },
+            },
+            observedAtMs: input.nowMs,
+        };
+    }
+    return {
+        kind: "instant",
+        size: { ...input.next.size },
+        update: {
+            size: { ...input.next.size },
+            transition: { ...input.next.transition },
+        },
+        startedAtMs: input.nowMs,
+        settledAtMs: input.nowMs,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@getuserfeedback/protocol",
-	"version": "3.0.8",
+	"version": "3.0.10",
 	"description": "getuserfeedback widget protocol — host surface and (later) wire protocol",
 	"keywords": [
 		"getuserfeedback",

package/src/host/index.ts

@@ -13,3 +13,4 @@ export { createCommandRequestId } from "./request-id.js";
 export * from "./sdk-types.js";
 export { createUniqueId } from "./unique-id.js";
 export * from "./widget-layout-size-update.js";
+export * from "./widget-layout-transition-plan.js";

package/src/host/widget-layout-size-update.test.ts

@@ -1,7 +1,10 @@
 import { describe, expect, test } from "bun:test";
 import {
 	INSTANT_WIDGET_LAYOUT_SIZE_TRANSITION,
+	isWidgetLayoutCubicBezier,
 	toInstantWidgetLayoutSizeUpdate,
+	toTimedWidgetLayoutSizeTransition,
+	toTimedWidgetLayoutSizeUpdate,
 } from "./widget-layout-size-update.js";
 
 describe("widget layout size update", () => {
@@ -22,4 +25,66 @@ describe("widget layout size update", () => {
 			toInstantWidgetLayoutSizeUpdate({ width: 1, height: 1 }).transition,
 		).toBe(INSTANT_WIDGET_LAYOUT_SIZE_TRANSITION);
 	});
+
+	test("keeps the existing size update contract instant-only", () => {
+		const update = toInstantWidgetLayoutSizeUpdate({ width: 320, height: 240 });
+
+		expect(update.transition.kind).toBe("instant");
+	});
+
+	test("wraps a host size in the timed transition contract", () => {
+		expect(
+			toTimedWidgetLayoutSizeUpdate({
+				size: { width: 320, height: 240 },
+				durationMs: 180,
+				easing: [0.2, 0, 0, 1],
+			}),
+		).toEqual({
+			size: { width: 320, height: 240 },
+			transition: {
+				kind: "timed",
+				durationMs: 180,
+				easing: {
+					kind: "cubic-bezier",
+					points: [0.2, 0, 0, 1],
+				},
+			},
+		});
+	});
+
+	test("accepts cubic-bezier y control point overshoot", () => {
+		expect(isWidgetLayoutCubicBezier([0.34, -0.2, 0.64, 1.35])).toBe(true);
+		expect(
+			toTimedWidgetLayoutSizeTransition({
+				durationMs: 220,
+				easing: [0.34, -0.2, 0.64, 1.35],
+			}).easing.points,
+		).toEqual([0.34, -0.2, 0.64, 1.35]);
+	});
+
+	test("fails closed for non-array cubic-bezier input", () => {
+		expect(isWidgetLayoutCubicBezier(null)).toBe(false);
+		expect(isWidgetLayoutCubicBezier({ 0: 0.2, 1: 0, 2: 0, 3: 1 })).toBe(false);
+		expect(isWidgetLayoutCubicBezier("0.2,0,0,1")).toBe(false);
+	});
+
+	test("rejects cubic-bezier x control points outside normalized time", () => {
+		expect(isWidgetLayoutCubicBezier([-0.01, 0, 0.5, 1])).toBe(false);
+		expect(isWidgetLayoutCubicBezier([0.5, 0, 1.01, 1])).toBe(false);
+		expect(() =>
+			toTimedWidgetLayoutSizeTransition({
+				durationMs: 220,
+				easing: [-0.01, 0, 0.5, 1],
+			}),
+		).toThrow(RangeError);
+	});
+
+	test("rejects invalid timed transition duration", () => {
+		expect(() =>
+			toTimedWidgetLayoutSizeTransition({
+				durationMs: 0,
+				easing: [0.2, 0, 0, 1],
+			}),
+		).toThrow(RangeError);
+	});
 });

package/src/host/widget-layout-size-update.ts

@@ -3,22 +3,67 @@ export type WidgetLayoutSize = {
 	height: number;
 };
 
-export type WidgetLayoutSizeTransition = {
+export type WidgetLayoutCubicBezier = readonly [
+	x1: number,
+	y1: number,
+	x2: number,
+	y2: number,
+];
+
+export type WidgetLayoutInstantSizeTransition = {
 	kind: "instant";
 	durationMs: 0;
 };
 
+export type WidgetLayoutTimedSizeTransition = {
+	kind: "timed";
+	durationMs: number;
+	easing: {
+		kind: "cubic-bezier";
+		points: WidgetLayoutCubicBezier;
+	};
+};
+
+export type WidgetLayoutSizeTransition = WidgetLayoutInstantSizeTransition;
+
 export type WidgetLayoutSizeUpdate = {
 	size: WidgetLayoutSize;
 	transition: WidgetLayoutSizeTransition;
 };
 
-export const INSTANT_WIDGET_LAYOUT_SIZE_TRANSITION: WidgetLayoutSizeTransition =
+export type WidgetLayoutTimedSizeUpdate = {
+	size: WidgetLayoutSize;
+	transition: WidgetLayoutTimedSizeTransition;
+};
+
+export const INSTANT_WIDGET_LAYOUT_SIZE_TRANSITION: WidgetLayoutInstantSizeTransition =
 	{
 		kind: "instant",
 		durationMs: 0,
 	};
 
+const isFiniteNumber = (value: unknown): value is number =>
+	typeof value === "number" && Number.isFinite(value);
+
+export function isWidgetLayoutCubicBezier(
+	points: unknown,
+): points is WidgetLayoutCubicBezier {
+	if (!Array.isArray(points) || points.length !== 4) {
+		return false;
+	}
+	const [x1, y1, x2, y2] = points;
+	return (
+		isFiniteNumber(x1) &&
+		x1 >= 0 &&
+		x1 <= 1 &&
+		isFiniteNumber(y1) &&
+		isFiniteNumber(x2) &&
+		x2 >= 0 &&
+		x2 <= 1 &&
+		isFiniteNumber(y2)
+	);
+}
+
 export function toInstantWidgetLayoutSizeUpdate(
 	size: WidgetLayoutSize,
 ): WidgetLayoutSizeUpdate {
@@ -27,3 +72,41 @@ export function toInstantWidgetLayoutSizeUpdate(
 		transition: INSTANT_WIDGET_LAYOUT_SIZE_TRANSITION,
 	};
 }
+
+export function toTimedWidgetLayoutSizeTransition(input: {
+	durationMs: number;
+	easing: WidgetLayoutCubicBezier;
+}): WidgetLayoutTimedSizeTransition {
+	if (!Number.isFinite(input.durationMs) || input.durationMs <= 0) {
+		throw new RangeError(
+			"Timed widget layout transitions require durationMs > 0",
+		);
+	}
+	if (!isWidgetLayoutCubicBezier(input.easing)) {
+		throw new RangeError(
+			"Timed widget layout transitions require cubic-bezier x control points in [0, 1] and finite y control points",
+		);
+	}
+	return {
+		kind: "timed",
+		durationMs: input.durationMs,
+		easing: {
+			kind: "cubic-bezier",
+			points: [...input.easing],
+		},
+	};
+}
+
+export function toTimedWidgetLayoutSizeUpdate(input: {
+	size: WidgetLayoutSize;
+	durationMs: number;
+	easing: WidgetLayoutCubicBezier;
+}): WidgetLayoutTimedSizeUpdate {
+	return {
+		size: { ...input.size },
+		transition: toTimedWidgetLayoutSizeTransition({
+			durationMs: input.durationMs,
+			easing: input.easing,
+		}),
+	};
+}

package/src/host/widget-layout-transition-plan.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, test } from "bun:test";
+import {
+	toInstantWidgetLayoutSizeUpdate,
+	toTimedWidgetLayoutSizeUpdate,
+} from "./widget-layout-size-update.js";
+import {
+	areWidgetLayoutSizeUpdatesEqual,
+	planWidgetLayoutTransition,
+} from "./widget-layout-transition-plan.js";
+
+describe("widget layout transition plan", () => {
+	test("plans the first instant layout update at the requested time", () => {
+		const next = toInstantWidgetLayoutSizeUpdate({ width: 320, height: 240 });
+
+		expect(
+			planWidgetLayoutTransition({
+				next,
+				nowMs: 1_000,
+			}),
+		).toEqual({
+			kind: "instant",
+			size: { width: 320, height: 240 },
+			update: {
+				size: { width: 320, height: 240 },
+				transition: {
+					kind: "instant",
+					durationMs: 0,
+				},
+			},
+			startedAtMs: 1_000,
+			settledAtMs: 1_000,
+		});
+	});
+
+	test("keeps repeated identical instant updates explicit as unchanged", () => {
+		const previous = toInstantWidgetLayoutSizeUpdate({
+			width: 320,
+			height: 240,
+		});
+		const next = toInstantWidgetLayoutSizeUpdate({ width: 320, height: 240 });
+
+		expect(
+			planWidgetLayoutTransition({
+				previous,
+				next,
+				nowMs: 1_250,
+			}),
+		).toMatchObject({
+			kind: "unchanged",
+			observedAtMs: 1_250,
+		});
+		expect(areWidgetLayoutSizeUpdatesEqual(previous, next)).toBe(true);
+	});
+
+	test("compares the full timed transition shape before it is live", () => {
+		const base = {
+			size: { width: 320, height: 240 },
+			durationMs: 180,
+		} as const;
+
+		expect(
+			areWidgetLayoutSizeUpdatesEqual(
+				toTimedWidgetLayoutSizeUpdate({ ...base, easing: [0.2, 0, 0, 1] }),
+				toTimedWidgetLayoutSizeUpdate({ ...base, easing: [0.2, 0, 0, 1] }),
+			),
+		).toBe(true);
+		expect(
+			areWidgetLayoutSizeUpdatesEqual(
+				toTimedWidgetLayoutSizeUpdate({ ...base, easing: [0.2, 0, 0, 1] }),
+				toTimedWidgetLayoutSizeUpdate({ ...base, easing: [0.3, 0, 0, 1] }),
+			),
+		).toBe(false);
+	});
+
+	test("treats size changes as instant while the live protocol is instant-only", () => {
+		const previous = toInstantWidgetLayoutSizeUpdate({
+			width: 320,
+			height: 240,
+		});
+		const next = toInstantWidgetLayoutSizeUpdate({ width: 320, height: 360 });
+
+		expect(
+			planWidgetLayoutTransition({
+				previous,
+				next,
+				nowMs: 1_500,
+			}),
+		).toMatchObject({
+			kind: "instant",
+			size: { width: 320, height: 360 },
+			startedAtMs: 1_500,
+			settledAtMs: 1_500,
+		});
+	});
+
+	test("does not leak mutable references from the next update", () => {
+		const next = {
+			size: { width: 320, height: 240 },
+			transition: { kind: "instant", durationMs: 0 },
+		} as const;
+		const plan = planWidgetLayoutTransition({
+			next,
+			nowMs: 1_000,
+		});
+
+		(next.size as { height: number }).height = 360;
+		(next.transition as { durationMs: number }).durationMs = 1;
+
+		expect(plan.size).toEqual({ width: 320, height: 240 });
+		expect(plan.update.size).toEqual({ width: 320, height: 240 });
+		expect(plan.update.transition.durationMs).toBe(0);
+	});
+
+	test("rejects non-finite plan time", () => {
+		expect(() =>
+			planWidgetLayoutTransition({
+				next: toInstantWidgetLayoutSizeUpdate({ width: 320, height: 240 }),
+				nowMs: Number.NaN,
+			}),
+		).toThrow(RangeError);
+	});
+});

package/src/host/widget-layout-transition-plan.ts

@@ -0,0 +1,97 @@
+import type {
+	WidgetLayoutSize,
+	WidgetLayoutSizeUpdate,
+	WidgetLayoutTimedSizeUpdate,
+} from "./widget-layout-size-update.js";
+
+export type WidgetLayoutComparableSizeUpdate =
+	| WidgetLayoutSizeUpdate
+	| WidgetLayoutTimedSizeUpdate;
+
+export type WidgetLayoutUnchangedTransitionPlan = {
+	kind: "unchanged";
+	size: WidgetLayoutSize;
+	update: WidgetLayoutSizeUpdate;
+	observedAtMs: number;
+};
+
+export type WidgetLayoutInstantTransitionPlan = {
+	kind: "instant";
+	size: WidgetLayoutSize;
+	update: WidgetLayoutSizeUpdate;
+	startedAtMs: number;
+	settledAtMs: number;
+};
+
+export type WidgetLayoutTransitionPlan =
+	| WidgetLayoutUnchangedTransitionPlan
+	| WidgetLayoutInstantTransitionPlan;
+
+export function areWidgetLayoutSizeUpdatesEqual(
+	left: WidgetLayoutComparableSizeUpdate | undefined,
+	right: WidgetLayoutComparableSizeUpdate,
+): boolean {
+	if (
+		left?.size.width !== right.size.width ||
+		left.size.height !== right.size.height ||
+		left.transition.kind !== right.transition.kind ||
+		left.transition.durationMs !== right.transition.durationMs
+	) {
+		return false;
+	}
+	const leftTransition = left.transition;
+	const rightTransition = right.transition;
+	switch (rightTransition.kind) {
+		case "instant":
+			return true;
+		case "timed":
+			if (leftTransition.kind !== "timed") {
+				return false;
+			}
+			return (
+				leftTransition.easing.kind === rightTransition.easing.kind &&
+				leftTransition.easing.points.length ===
+					rightTransition.easing.points.length &&
+				leftTransition.easing.points.every(
+					(point, index) => point === rightTransition.easing.points[index],
+				)
+			);
+		default: {
+			const unreachable: never = rightTransition;
+			throw new Error(
+				`Unsupported widget layout transition: ${JSON.stringify(unreachable)}`,
+			);
+		}
+	}
+}
+
+export function planWidgetLayoutTransition(input: {
+	previous?: WidgetLayoutSizeUpdate;
+	next: WidgetLayoutSizeUpdate;
+	nowMs: number;
+}): WidgetLayoutTransitionPlan {
+	if (!Number.isFinite(input.nowMs)) {
+		throw new RangeError("Widget layout transition plans require finite nowMs");
+	}
+	if (areWidgetLayoutSizeUpdatesEqual(input.previous, input.next)) {
+		return {
+			kind: "unchanged",
+			size: { ...input.next.size },
+			update: {
+				size: { ...input.next.size },
+				transition: { ...input.next.transition },
+			},
+			observedAtMs: input.nowMs,
+		};
+	}
+	return {
+		kind: "instant",
+		size: { ...input.next.size },
+		update: {
+			size: { ...input.next.size },
+			transition: { ...input.next.transition },
+		},
+		startedAtMs: input.nowMs,
+		settledAtMs: input.nowMs,
+	};
+}