@getuserfeedback/protocol 3.0.11 → 3.0.13

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

@@ -1,9 +1,9 @@
-import type { WidgetLayoutSize, WidgetLayoutSizeUpdate, WidgetLayoutTimedSizeUpdate } from "./widget-layout-size-update.js";
+import type { WidgetLayoutCubicBezier, WidgetLayoutSize, WidgetLayoutSizeUpdate, WidgetLayoutTimedSizeUpdate } from "./widget-layout-size-update.js";
 export type WidgetLayoutComparableSizeUpdate = WidgetLayoutSizeUpdate | WidgetLayoutTimedSizeUpdate;
-export type WidgetLayoutUnchangedTransitionPlan = {
+export type WidgetLayoutUnchangedTransitionPlan<Update extends WidgetLayoutComparableSizeUpdate = WidgetLayoutComparableSizeUpdate> = {
     kind: "unchanged";
     size: WidgetLayoutSize;
-    update: WidgetLayoutSizeUpdate;
+    update: Update;
     observedAtMs: number;
 };
 export type WidgetLayoutInstantTransitionPlan = {
@@ -13,12 +13,59 @@ export type WidgetLayoutInstantTransitionPlan = {
     startedAtMs: number;
     settledAtMs: number;
 };
-export type WidgetLayoutTransitionPlan = WidgetLayoutUnchangedTransitionPlan | WidgetLayoutInstantTransitionPlan;
+export type WidgetLayoutTimedTransitionPlan = {
+    kind: "timed";
+    size: WidgetLayoutSize;
+    update: WidgetLayoutTimedSizeUpdate;
+    startedAtMs: number;
+    settledAtMs: number;
+};
+export type WidgetLayoutInstantOnlyTransitionPlan = WidgetLayoutUnchangedTransitionPlan<WidgetLayoutSizeUpdate> | WidgetLayoutInstantTransitionPlan;
+export type WidgetLayoutTransitionPlan = WidgetLayoutInstantOnlyTransitionPlan;
+export type WidgetLayoutTimedCapableTransitionPlan = WidgetLayoutUnchangedTransitionPlan | WidgetLayoutInstantTransitionPlan | WidgetLayoutTimedTransitionPlan;
+export type WidgetLayoutInstantTransitionPolicy = {
+    kind: "instant";
+    durationMs: 0;
+};
+export type WidgetLayoutTimedTransitionPolicy = {
+    kind: "timed";
+    durationMs: number;
+    easing: WidgetLayoutCubicBezier;
+};
+export type WidgetLayoutTransitionPolicy = WidgetLayoutInstantTransitionPolicy | WidgetLayoutTimedTransitionPolicy;
+export declare const INSTANT_WIDGET_LAYOUT_TRANSITION_POLICY: WidgetLayoutInstantTransitionPolicy;
 export declare function getWidgetLayoutPlanNowMs(): number;
 export declare function areWidgetLayoutSizeUpdatesEqual(left: WidgetLayoutComparableSizeUpdate | undefined, right: WidgetLayoutComparableSizeUpdate): boolean;
+type WidgetLayoutInstantPolicyPlanInput = {
+    previous?: WidgetLayoutComparableSizeUpdate;
+    size: WidgetLayoutSize;
+    nowMs: number;
+    transitionPolicy?: WidgetLayoutInstantTransitionPolicy;
+};
+type WidgetLayoutTimedCapablePolicyPlanInput = {
+    previous?: WidgetLayoutComparableSizeUpdate;
+    size: WidgetLayoutSize;
+    nowMs: number;
+    transitionPolicy: WidgetLayoutTimedTransitionPolicy;
+};
+type WidgetLayoutOptionalPolicyPlanInput = {
+    previous?: WidgetLayoutComparableSizeUpdate;
+    size: WidgetLayoutSize;
+    nowMs: number;
+    transitionPolicy?: WidgetLayoutTransitionPolicy;
+};
 export declare function planWidgetLayoutTransition(input: {
     previous?: WidgetLayoutSizeUpdate;
     next: WidgetLayoutSizeUpdate;
     nowMs: number;
-}): WidgetLayoutTransitionPlan;
+}): WidgetLayoutInstantOnlyTransitionPlan;
+export declare function planWidgetLayoutTransition(input: {
+    previous?: WidgetLayoutComparableSizeUpdate;
+    next: WidgetLayoutComparableSizeUpdate;
+    nowMs: number;
+}): WidgetLayoutTimedCapableTransitionPlan;
+export declare function planWidgetLayoutTransition(input: WidgetLayoutInstantPolicyPlanInput): WidgetLayoutInstantOnlyTransitionPlan;
+export declare function planWidgetLayoutTransition(input: WidgetLayoutTimedCapablePolicyPlanInput): WidgetLayoutTimedCapableTransitionPlan;
+export declare function planWidgetLayoutTransition(input: WidgetLayoutOptionalPolicyPlanInput): WidgetLayoutTimedCapableTransitionPlan;
+export {};
 //# sourceMappingURL=widget-layout-transition-plan.d.ts.map

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

@@ -1 +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,wBAAwB,IAAI,MAAM,CAQjD;AAED,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"}
+{"version":3,"file":"widget-layout-transition-plan.d.ts","sourceRoot":"","sources":["../../src/host/widget-layout-transition-plan.ts"],"names":[],"mappings":"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"}

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

@@ -1,3 +1,8 @@
+import { toInstantWidgetLayoutSizeUpdate, toTimedWidgetLayoutSizeUpdate, } from "./widget-layout-size-update.js";
+export const INSTANT_WIDGET_LAYOUT_TRANSITION_POLICY = {
+    kind: "instant",
+    durationMs: 0,
+};
 export function getWidgetLayoutPlanNowMs() {
     const performanceNow = typeof globalThis.performance?.now === "function"
         ? globalThis.performance.now()
@@ -32,28 +37,75 @@ export function areWidgetLayoutSizeUpdatesEqual(left, right) {
         }
     }
 }
+function cloneWidgetLayoutSizeUpdate(update) {
+    if (update.transition.kind === "timed") {
+        return {
+            size: { ...update.size },
+            transition: {
+                ...update.transition,
+                easing: {
+                    ...update.transition.easing,
+                    points: [...update.transition.easing.points],
+                },
+            },
+        };
+    }
+    return {
+        size: { ...update.size },
+        transition: { ...update.transition },
+    };
+}
+function isWidgetLayoutTimedSizeUpdate(update) {
+    return update.transition.kind === "timed";
+}
+function toWidgetLayoutSizeUpdateForPolicy(input) {
+    const policy = input.policy ?? INSTANT_WIDGET_LAYOUT_TRANSITION_POLICY;
+    switch (policy.kind) {
+        case "instant":
+            return toInstantWidgetLayoutSizeUpdate(input.size);
+        case "timed":
+            return toTimedWidgetLayoutSizeUpdate({
+                size: input.size,
+                durationMs: policy.durationMs,
+                easing: policy.easing,
+            });
+        default: {
+            const unreachable = policy;
+            throw new Error(`Unsupported widget layout transition policy: ${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)) {
+    const next = "next" in input
+        ? input.next
+        : toWidgetLayoutSizeUpdateForPolicy({
+            size: input.size,
+            policy: input.transitionPolicy,
+        });
+    if (areWidgetLayoutSizeUpdatesEqual(input.previous, next)) {
         return {
             kind: "unchanged",
-            size: { ...input.next.size },
-            update: {
-                size: { ...input.next.size },
-                transition: { ...input.next.transition },
-            },
+            size: { ...next.size },
+            update: cloneWidgetLayoutSizeUpdate(next),
             observedAtMs: input.nowMs,
         };
     }
+    if (isWidgetLayoutTimedSizeUpdate(next)) {
+        return {
+            kind: "timed",
+            size: { ...next.size },
+            update: cloneWidgetLayoutSizeUpdate(next),
+            startedAtMs: input.nowMs,
+            settledAtMs: input.nowMs + next.transition.durationMs,
+        };
+    }
     return {
         kind: "instant",
-        size: { ...input.next.size },
-        update: {
-            size: { ...input.next.size },
-            transition: { ...input.next.transition },
-        },
+        size: { ...next.size },
+        update: cloneWidgetLayoutSizeUpdate(next),
         startedAtMs: input.nowMs,
         settledAtMs: input.nowMs,
     };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@getuserfeedback/protocol",
-	"version": "3.0.11",
+	"version": "3.0.13",
 	"description": "getuserfeedback widget protocol — host surface and (later) wire protocol",
 	"keywords": [
 		"getuserfeedback",
@@ -132,8 +132,8 @@
 		}
 	},
 	"scripts": {
-		"lint": "ultracite check .",
-		"build": "bun ../../scripts/clean-build-output.ts dist tsconfig.tsbuildinfo && tsc -b tsconfig.json",
+		"lint": "biome check .",
+		"build": "bun ../../scripts/clean-build-output.ts dist tsconfig.tsbuildinfo && tsc -b tsconfig.json && bun scripts/verify-dist-js.ts",
 		"types": "bun ../../scripts/clean-build-output.ts dist tsconfig.tsbuildinfo && tsc -b tsconfig.json --emitDeclarationOnly",
 		"typecheck": "tsc -b tsconfig.json",
 		"test": "bun test --dots",

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

@@ -6,10 +6,24 @@ import {
 import {
 	areWidgetLayoutSizeUpdatesEqual,
 	getWidgetLayoutPlanNowMs,
+	INSTANT_WIDGET_LAYOUT_TRANSITION_POLICY,
 	planWidgetLayoutTransition,
+	type WidgetLayoutInstantOnlyTransitionPlan,
+	type WidgetLayoutTimedCapableTransitionPlan,
+	type WidgetLayoutTransitionPlan,
 } from "./widget-layout-transition-plan.js";
 
 describe("widget layout transition plan", () => {
+	function expectInstantOnlyPlan(
+		_plan: WidgetLayoutInstantOnlyTransitionPlan,
+	): void {}
+	function expectLegacyTransitionPlan(
+		_plan: WidgetLayoutTransitionPlan,
+	): void {}
+	function expectTimedCapablePlan(
+		_plan: WidgetLayoutTimedCapableTransitionPlan,
+	): void {}
+
 	test("uses the browser monotonic clock for layout plan timestamps", () => {
 		const originalPerformanceDescriptor = Object.getOwnPropertyDescriptor(
 			globalThis,
@@ -72,6 +86,19 @@ describe("widget layout transition plan", () => {
 	test("plans the first instant layout update at the requested time", () => {
 		const next = toInstantWidgetLayoutSizeUpdate({ width: 320, height: 240 });
 
+		expectInstantOnlyPlan(
+			planWidgetLayoutTransition({
+				next,
+				nowMs: 1_000,
+			}),
+		);
+		expectLegacyTransitionPlan(
+			planWidgetLayoutTransition({
+				next,
+				nowMs: 1_000,
+			}),
+		);
+
 		expect(
 			planWidgetLayoutTransition({
 				next,
@@ -112,6 +139,44 @@ describe("widget layout transition plan", () => {
 		expect(areWidgetLayoutSizeUpdatesEqual(previous, next)).toBe(true);
 	});
 
+	test("plans size input as instant by default", () => {
+		const previous = toInstantWidgetLayoutSizeUpdate({
+			width: 320,
+			height: 240,
+		});
+
+		const plan = planWidgetLayoutTransition({
+			previous,
+			size: { width: 320, height: 360 },
+			nowMs: 1_500,
+		});
+		expectInstantOnlyPlan(plan);
+		expect(plan).toEqual({
+			kind: "instant",
+			size: { width: 320, height: 360 },
+			update: {
+				size: { width: 320, height: 360 },
+				transition: {
+					kind: "instant",
+					durationMs: 0,
+				},
+			},
+			startedAtMs: 1_500,
+			settledAtMs: 1_500,
+		});
+	});
+
+	test("keeps explicit instant transition policy instant-only", () => {
+		const plan = planWidgetLayoutTransition({
+			size: { width: 320, height: 360 },
+			nowMs: 1_500,
+			transitionPolicy: INSTANT_WIDGET_LAYOUT_TRANSITION_POLICY,
+		});
+
+		expectInstantOnlyPlan(plan);
+		expect(plan.kind).toBe("instant");
+	});
+
 	test("compares the full timed transition shape before it is live", () => {
 		const base = {
 			size: { width: 320, height: 240 },
@@ -153,6 +218,82 @@ describe("widget layout transition plan", () => {
 		});
 	});
 
+	test("plans explicit timed updates with settled time from duration", () => {
+		const next = toTimedWidgetLayoutSizeUpdate({
+			size: { width: 320, height: 360 },
+			durationMs: 180,
+			easing: [0.2, 0, 0, 1],
+		});
+
+		expect(
+			planWidgetLayoutTransition({
+				next,
+				nowMs: 1_500,
+			}),
+		).toEqual({
+			kind: "timed",
+			size: { width: 320, height: 360 },
+			update: {
+				size: { width: 320, height: 360 },
+				transition: {
+					kind: "timed",
+					durationMs: 180,
+					easing: {
+						kind: "cubic-bezier",
+						points: [0.2, 0, 0, 1],
+					},
+				},
+			},
+			startedAtMs: 1_500,
+			settledAtMs: 1_680,
+		});
+	});
+
+	test("plans timed transition policy from size input", () => {
+		const plan = planWidgetLayoutTransition({
+			size: { width: 320, height: 360 },
+			nowMs: 1_500,
+			transitionPolicy: {
+				kind: "timed",
+				durationMs: 180,
+				easing: [0.2, 0, 0, 1],
+			},
+		});
+		expectTimedCapablePlan(plan);
+
+		expect(plan).toEqual({
+			kind: "timed",
+			size: { width: 320, height: 360 },
+			update: {
+				size: { width: 320, height: 360 },
+				transition: {
+					kind: "timed",
+					durationMs: 180,
+					easing: {
+						kind: "cubic-bezier",
+						points: [0.2, 0, 0, 1],
+					},
+				},
+			},
+			startedAtMs: 1_500,
+			settledAtMs: 1_680,
+		});
+	});
+
+	test("rejects invalid timed transition policy through protocol helpers", () => {
+		expect(() =>
+			planWidgetLayoutTransition({
+				size: { width: 320, height: 360 },
+				nowMs: 1_500,
+				transitionPolicy: {
+					kind: "timed",
+					durationMs: 0,
+					easing: [0.2, 0, 0, 1],
+				},
+			}),
+		).toThrow(RangeError);
+	});
+
 	test("does not leak mutable references from the next update", () => {
 		const next = {
 			size: { width: 320, height: 240 },
@@ -171,6 +312,26 @@ describe("widget layout transition plan", () => {
 		expect(plan.update.transition.durationMs).toBe(0);
 	});
 
+	test("does not leak mutable timed transition points from the next update", () => {
+		const next = toTimedWidgetLayoutSizeUpdate({
+			size: { width: 320, height: 240 },
+			durationMs: 180,
+			easing: [0.2, 0, 0, 1],
+		});
+		const plan = planWidgetLayoutTransition({
+			next,
+			nowMs: 1_000,
+		});
+
+		(next.transition.easing.points as unknown as number[])[0] = 0.4;
+
+		expect(plan.update.transition.kind).toBe("timed");
+		if (plan.update.transition.kind !== "timed") {
+			throw new Error("expected timed transition");
+		}
+		expect(plan.update.transition.easing.points).toEqual([0.2, 0, 0, 1]);
+	});
+
 	test("rejects non-finite plan time", () => {
 		expect(() =>
 			planWidgetLayoutTransition({

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

@@ -1,17 +1,25 @@
 import type {
+	WidgetLayoutCubicBezier,
 	WidgetLayoutSize,
 	WidgetLayoutSizeUpdate,
 	WidgetLayoutTimedSizeUpdate,
 } from "./widget-layout-size-update.js";
+import {
+	toInstantWidgetLayoutSizeUpdate,
+	toTimedWidgetLayoutSizeUpdate,
+} from "./widget-layout-size-update.js";
 
 export type WidgetLayoutComparableSizeUpdate =
 	| WidgetLayoutSizeUpdate
 	| WidgetLayoutTimedSizeUpdate;
 
-export type WidgetLayoutUnchangedTransitionPlan = {
+export type WidgetLayoutUnchangedTransitionPlan<
+	Update extends
+		WidgetLayoutComparableSizeUpdate = WidgetLayoutComparableSizeUpdate,
+> = {
 	kind: "unchanged";
 	size: WidgetLayoutSize;
-	update: WidgetLayoutSizeUpdate;
+	update: Update;
 	observedAtMs: number;
 };
 
@@ -23,10 +31,46 @@ export type WidgetLayoutInstantTransitionPlan = {
 	settledAtMs: number;
 };
 
-export type WidgetLayoutTransitionPlan =
-	| WidgetLayoutUnchangedTransitionPlan
+export type WidgetLayoutTimedTransitionPlan = {
+	kind: "timed";
+	size: WidgetLayoutSize;
+	update: WidgetLayoutTimedSizeUpdate;
+	startedAtMs: number;
+	settledAtMs: number;
+};
+
+export type WidgetLayoutInstantOnlyTransitionPlan =
+	| WidgetLayoutUnchangedTransitionPlan<WidgetLayoutSizeUpdate>
 	| WidgetLayoutInstantTransitionPlan;
 
+export type WidgetLayoutTransitionPlan = WidgetLayoutInstantOnlyTransitionPlan;
+
+export type WidgetLayoutTimedCapableTransitionPlan =
+	| WidgetLayoutUnchangedTransitionPlan
+	| WidgetLayoutInstantTransitionPlan
+	| WidgetLayoutTimedTransitionPlan;
+
+export type WidgetLayoutInstantTransitionPolicy = {
+	kind: "instant";
+	durationMs: 0;
+};
+
+export type WidgetLayoutTimedTransitionPolicy = {
+	kind: "timed";
+	durationMs: number;
+	easing: WidgetLayoutCubicBezier;
+};
+
+export type WidgetLayoutTransitionPolicy =
+	| WidgetLayoutInstantTransitionPolicy
+	| WidgetLayoutTimedTransitionPolicy;
+
+export const INSTANT_WIDGET_LAYOUT_TRANSITION_POLICY: WidgetLayoutInstantTransitionPolicy =
+	{
+		kind: "instant",
+		durationMs: 0,
+	};
+
 export function getWidgetLayoutPlanNowMs(): number {
 	const performanceNow =
 		typeof globalThis.performance?.now === "function"
@@ -75,32 +119,156 @@ export function areWidgetLayoutSizeUpdatesEqual(
 	}
 }
 
+function cloneWidgetLayoutSizeUpdate(
+	update: WidgetLayoutSizeUpdate,
+): WidgetLayoutSizeUpdate;
+function cloneWidgetLayoutSizeUpdate(
+	update: WidgetLayoutTimedSizeUpdate,
+): WidgetLayoutTimedSizeUpdate;
+function cloneWidgetLayoutSizeUpdate(
+	update: WidgetLayoutComparableSizeUpdate,
+): WidgetLayoutComparableSizeUpdate;
+function cloneWidgetLayoutSizeUpdate(
+	update: WidgetLayoutComparableSizeUpdate,
+): WidgetLayoutComparableSizeUpdate {
+	if (update.transition.kind === "timed") {
+		return {
+			size: { ...update.size },
+			transition: {
+				...update.transition,
+				easing: {
+					...update.transition.easing,
+					points: [...update.transition.easing.points],
+				},
+			},
+		};
+	}
+	return {
+		size: { ...update.size },
+		transition: { ...update.transition },
+	};
+}
+
+function isWidgetLayoutTimedSizeUpdate(
+	update: WidgetLayoutComparableSizeUpdate,
+): update is WidgetLayoutTimedSizeUpdate {
+	return update.transition.kind === "timed";
+}
+
+function toWidgetLayoutSizeUpdateForPolicy(input: {
+	policy: WidgetLayoutTransitionPolicy | undefined;
+	size: WidgetLayoutSize;
+}): WidgetLayoutComparableSizeUpdate {
+	const policy = input.policy ?? INSTANT_WIDGET_LAYOUT_TRANSITION_POLICY;
+	switch (policy.kind) {
+		case "instant":
+			return toInstantWidgetLayoutSizeUpdate(input.size);
+		case "timed":
+			return toTimedWidgetLayoutSizeUpdate({
+				size: input.size,
+				durationMs: policy.durationMs,
+				easing: policy.easing,
+			});
+		default: {
+			const unreachable: never = policy;
+			throw new Error(
+				`Unsupported widget layout transition policy: ${JSON.stringify(unreachable)}`,
+			);
+		}
+	}
+}
+
+type WidgetLayoutInstantUpdatePlanInput = {
+	previous?: WidgetLayoutSizeUpdate;
+	next: WidgetLayoutSizeUpdate;
+	nowMs: number;
+};
+
+type WidgetLayoutTimedCapableUpdatePlanInput = {
+	previous?: WidgetLayoutComparableSizeUpdate;
+	next: WidgetLayoutComparableSizeUpdate;
+	nowMs: number;
+};
+
+type WidgetLayoutInstantPolicyPlanInput = {
+	previous?: WidgetLayoutComparableSizeUpdate;
+	size: WidgetLayoutSize;
+	nowMs: number;
+	transitionPolicy?: WidgetLayoutInstantTransitionPolicy;
+};
+
+type WidgetLayoutTimedCapablePolicyPlanInput = {
+	previous?: WidgetLayoutComparableSizeUpdate;
+	size: WidgetLayoutSize;
+	nowMs: number;
+	transitionPolicy: WidgetLayoutTimedTransitionPolicy;
+};
+
+type WidgetLayoutOptionalPolicyPlanInput = {
+	previous?: WidgetLayoutComparableSizeUpdate;
+	size: WidgetLayoutSize;
+	nowMs: number;
+	transitionPolicy?: WidgetLayoutTransitionPolicy;
+};
+
 export function planWidgetLayoutTransition(input: {
 	previous?: WidgetLayoutSizeUpdate;
 	next: WidgetLayoutSizeUpdate;
 	nowMs: number;
-}): WidgetLayoutTransitionPlan {
+}): WidgetLayoutInstantOnlyTransitionPlan;
+export function planWidgetLayoutTransition(input: {
+	previous?: WidgetLayoutComparableSizeUpdate;
+	next: WidgetLayoutComparableSizeUpdate;
+	nowMs: number;
+}): WidgetLayoutTimedCapableTransitionPlan;
+export function planWidgetLayoutTransition(
+	input: WidgetLayoutInstantPolicyPlanInput,
+): WidgetLayoutInstantOnlyTransitionPlan;
+export function planWidgetLayoutTransition(
+	input: WidgetLayoutTimedCapablePolicyPlanInput,
+): WidgetLayoutTimedCapableTransitionPlan;
+export function planWidgetLayoutTransition(
+	input: WidgetLayoutOptionalPolicyPlanInput,
+): WidgetLayoutTimedCapableTransitionPlan;
+export function planWidgetLayoutTransition(
+	input:
+		| WidgetLayoutInstantUpdatePlanInput
+		| WidgetLayoutTimedCapableUpdatePlanInput
+		| WidgetLayoutInstantPolicyPlanInput
+		| WidgetLayoutTimedCapablePolicyPlanInput
+		| WidgetLayoutOptionalPolicyPlanInput,
+): WidgetLayoutTimedCapableTransitionPlan {
 	if (!Number.isFinite(input.nowMs)) {
 		throw new RangeError("Widget layout transition plans require finite nowMs");
 	}
-	if (areWidgetLayoutSizeUpdatesEqual(input.previous, input.next)) {
+	const next =
+		"next" in input
+			? input.next
+			: toWidgetLayoutSizeUpdateForPolicy({
+					size: input.size,
+					policy: input.transitionPolicy,
+				});
+	if (areWidgetLayoutSizeUpdatesEqual(input.previous, next)) {
 		return {
 			kind: "unchanged",
-			size: { ...input.next.size },
-			update: {
-				size: { ...input.next.size },
-				transition: { ...input.next.transition },
-			},
+			size: { ...next.size },
+			update: cloneWidgetLayoutSizeUpdate(next),
 			observedAtMs: input.nowMs,
 		};
 	}
+	if (isWidgetLayoutTimedSizeUpdate(next)) {
+		return {
+			kind: "timed",
+			size: { ...next.size },
+			update: cloneWidgetLayoutSizeUpdate(next),
+			startedAtMs: input.nowMs,
+			settledAtMs: input.nowMs + next.transition.durationMs,
+		};
+	}
 	return {
 		kind: "instant",
-		size: { ...input.next.size },
-		update: {
-			size: { ...input.next.size },
-			transition: { ...input.next.transition },
-		},
+		size: { ...next.size },
+		update: cloneWidgetLayoutSizeUpdate(next),
 		startedAtMs: input.nowMs,
 		settledAtMs: input.nowMs,
 	};