@getuserfeedback/protocol 3.0.12 → 3.0.13

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

@@ -1,4 +1,4 @@
-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<Update extends WidgetLayoutComparableSizeUpdate = WidgetLayoutComparableSizeUpdate> = {
     kind: "unchanged";
@@ -23,8 +23,37 @@ export type WidgetLayoutTimedTransitionPlan = {
 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;
@@ -35,4 +64,8 @@ export declare function planWidgetLayoutTransition(input: {
     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,CAC9C,MAAM,SACL,gCAAgC,GAAG,gCAAgC,IACjE;IACH,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,gBAAgB,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,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,+BAA+B,GAAG;IAC7C,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,gBAAgB,CAAC;IACvB,MAAM,EAAE,2BAA2B,CAAC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,qCAAqC,GAC9C,mCAAmC,CAAC,sBAAsB,CAAC,GAC3D,iCAAiC,CAAC;AAErC,MAAM,MAAM,0BAA0B,GAAG,qCAAqC,CAAC;AAE/E,MAAM,MAAM,sCAAsC,GAC/C,mCAAmC,GACnC,iCAAiC,GACjC,+BAA+B,CAAC;AAEnC,wBAAgB,wBAAwB,IAAI,MAAM,CAQjD;AAED,wBAAgB,+BAA+B,CAC9C,IAAI,EAAE,gCAAgC,GAAG,SAAS,EAClD,KAAK,EAAE,gCAAgC,GACrC,OAAO,CAiCT;AAsCD,wBAAgB,0BAA0B,CAAC,KAAK,EAAE;IACjD,QAAQ,CAAC,EAAE,sBAAsB,CAAC;IAClC,IAAI,EAAE,sBAAsB,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;CACd,GAAG,qCAAqC,CAAC;AAC1C,wBAAgB,0BAA0B,CAAC,KAAK,EAAE;IACjD,QAAQ,CAAC,EAAE,gCAAgC,CAAC;IAC5C,IAAI,EAAE,gCAAgC,CAAC;IACvC,KAAK,EAAE,MAAM,CAAC;CACd,GAAG,sCAAsC,CAAC"}
+{"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()
@@ -53,31 +58,54 @@ function cloneWidgetLayoutSizeUpdate(update) {
 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: cloneWidgetLayoutSizeUpdate(input.next),
+            size: { ...next.size },
+            update: cloneWidgetLayoutSizeUpdate(next),
             observedAtMs: input.nowMs,
         };
     }
-    if (isWidgetLayoutTimedSizeUpdate(input.next)) {
+    if (isWidgetLayoutTimedSizeUpdate(next)) {
         return {
             kind: "timed",
-            size: { ...input.next.size },
-            update: cloneWidgetLayoutSizeUpdate(input.next),
+            size: { ...next.size },
+            update: cloneWidgetLayoutSizeUpdate(next),
             startedAtMs: input.nowMs,
-            settledAtMs: input.nowMs + input.next.transition.durationMs,
+            settledAtMs: input.nowMs + next.transition.durationMs,
         };
     }
     return {
         kind: "instant",
-        size: { ...input.next.size },
-        update: cloneWidgetLayoutSizeUpdate(input.next),
+        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.12",
+	"version": "3.0.13",
 	"description": "getuserfeedback widget protocol — host surface and (later) wire protocol",
 	"keywords": [
 		"getuserfeedback",
@@ -132,7 +132,7 @@
 		}
 	},
 	"scripts": {
-		"lint": "ultracite check .",
+		"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",

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

@@ -6,8 +6,10 @@ import {
 import {
 	areWidgetLayoutSizeUpdatesEqual,
 	getWidgetLayoutPlanNowMs,
+	INSTANT_WIDGET_LAYOUT_TRANSITION_POLICY,
 	planWidgetLayoutTransition,
 	type WidgetLayoutInstantOnlyTransitionPlan,
+	type WidgetLayoutTimedCapableTransitionPlan,
 	type WidgetLayoutTransitionPlan,
 } from "./widget-layout-transition-plan.js";
 
@@ -18,6 +20,9 @@ describe("widget layout transition plan", () => {
 	function expectLegacyTransitionPlan(
 		_plan: WidgetLayoutTransitionPlan,
 	): void {}
+	function expectTimedCapablePlan(
+		_plan: WidgetLayoutTimedCapableTransitionPlan,
+	): void {}
 
 	test("uses the browser monotonic clock for layout plan timestamps", () => {
 		const originalPerformanceDescriptor = Object.getOwnPropertyDescriptor(
@@ -134,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 },
@@ -206,6 +249,51 @@ describe("widget layout transition plan", () => {
 		});
 	});
 
+	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 },

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

@@ -1,8 +1,13 @@
 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
@@ -45,6 +50,27 @@ export type WidgetLayoutTimedCapableTransitionPlan =
 	| 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"
@@ -129,45 +155,120 @@ function isWidgetLayoutTimedSizeUpdate(
 	return update.transition.kind === "timed";
 }
 
-export function planWidgetLayoutTransition(input: {
+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;
-}): WidgetLayoutInstantOnlyTransitionPlan;
-export function planWidgetLayoutTransition(input: {
+};
+
+type WidgetLayoutTimedCapableUpdatePlanInput = {
 	previous?: WidgetLayoutComparableSizeUpdate;
 	next: WidgetLayoutComparableSizeUpdate;
 	nowMs: number;
-}): WidgetLayoutTimedCapableTransitionPlan;
+};
+
+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;
+}): WidgetLayoutInstantOnlyTransitionPlan;
 export function planWidgetLayoutTransition(input: {
 	previous?: WidgetLayoutComparableSizeUpdate;
 	next: WidgetLayoutComparableSizeUpdate;
 	nowMs: number;
-}): WidgetLayoutTimedCapableTransitionPlan {
+}): 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: cloneWidgetLayoutSizeUpdate(input.next),
+			size: { ...next.size },
+			update: cloneWidgetLayoutSizeUpdate(next),
 			observedAtMs: input.nowMs,
 		};
 	}
-	if (isWidgetLayoutTimedSizeUpdate(input.next)) {
+	if (isWidgetLayoutTimedSizeUpdate(next)) {
 		return {
 			kind: "timed",
-			size: { ...input.next.size },
-			update: cloneWidgetLayoutSizeUpdate(input.next),
+			size: { ...next.size },
+			update: cloneWidgetLayoutSizeUpdate(next),
 			startedAtMs: input.nowMs,
-			settledAtMs: input.nowMs + input.next.transition.durationMs,
+			settledAtMs: input.nowMs + next.transition.durationMs,
 		};
 	}
 	return {
 		kind: "instant",
-		size: { ...input.next.size },
-		update: cloneWidgetLayoutSizeUpdate(input.next),
+		size: { ...next.size },
+		update: cloneWidgetLayoutSizeUpdate(next),
 		startedAtMs: input.nowMs,
 		settledAtMs: input.nowMs,
 	};