Skip to content

Commit 1131fb3

Browse files
authored
refactor(contracts): additive capability facts on the gesture family (#2460)
* refactor(contracts): make gesture capability facts additive Additive capability facts on the gesture family (#2443, family 2). gestureRuntimeOperationFacts took one fact per tier, and it had five: plan, directionalFling, multiTouch, targetAuthoredDrag, viewport. The tiers split exactly where an owner's mechanics split — no tier is one every owner serves, and several owners serve none — so every tier is optional now and `unsupported` names the denial an omitted tier reports. The type still refuses a call that names no denial at all: omission is a classified refusal, never an unclassified tier and never an implied success, and an owner cannot leave the family blank. An owner states a tier only to say something the family denial does not. Web refuses every tier with one cell and names only the drag tier whose wording came from a retired closure. Vega names the two tiers whose refusals came from separate closures. Limrun's session-less and iOS branches name one denial each, where each wrote five. The owners that serve gestures keep naming what they serve: the win is the next tier, which an owner can now ignore entirely. Fact values are unchanged: every owner's gesture cells are byte-identical, and the family's own test pins an omitted tier reporting the stated denial verbatim, an owner that names nothing answering with the exhaustive shape, and the freeze. * fix(platform-apple): name the gesture family denial by leaf Review follow-up on the gesture family. Apple refuses gestures for two reasons depending on the leaf: watchOS and visionOS have no gesture surface at all, while every other leaf without a touch kind is the wrong device kind. One constant cannot be truthful for both, and the family denial is what the first unnamed tier will report, so it now follows the leaf. The Limrun gesture call collapsed to one source for the session-less branch, so pin the reason and hint it reports there rather than availability alone, and cover the directional-fling tier the loop had skipped.
1 parent d80b021 commit 1131fb3

14 files changed

Lines changed: 100 additions & 62 deletions

File tree

‎packages/contracts/src/gesture-runtime.test.ts‎

Lines changed: 35 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ const available = { available: true } as const;
1919
const unavailable = { available: false, reason: 'unsupported-platform-leaf' } as const;
2020

2121
const allAvailable = gestureRuntimeOperationFacts({
22+
unsupported: unavailable,
2223
plan: available,
2324
directionalFling: available,
2425
multiTouch: available,
@@ -43,9 +44,10 @@ const plan: GesturePlan = {
4344
],
4445
};
4546

46-
test('builds the exact gesture operation fact catalog', () => {
47+
test('builds the exact gesture operation fact catalog for an owner that names every tier', () => {
4748
expect(
4849
gestureRuntimeOperationFacts({
50+
unsupported: unavailable,
4951
plan: available,
5052
directionalFling: unavailable,
5153
multiTouch: unavailable,
@@ -61,6 +63,37 @@ test('builds the exact gesture operation fact catalog', () => {
6163
});
6264
});
6365

66+
test('a tier the owner never names reports the denial the owner stated for the family, verbatim — omission is a classified refusal, never an unclassified tier and never an implied success', () => {
67+
const denial = {
68+
available: false,
69+
reason: 'unsupported-device-kind',
70+
hint: 'Gestures are supported on HarmonyOS emulators and physical devices.',
71+
} as const;
72+
73+
expect(gestureRuntimeOperationFacts({ unsupported: denial, plan: available })).toEqual({
74+
performGesturePlan: available,
75+
performDirectionalFlingPlan: denial,
76+
performMultiTouchGesturePlan: denial,
77+
performTargetAuthoredDrag: denial,
78+
gestureViewport: denial,
79+
});
80+
});
81+
82+
test('an owner serving no gesture tier names the family denial once and still answers with the exhaustive shape', () => {
83+
const denial = { available: false, reason: 'unsupported-platform-leaf' } as const;
84+
85+
const facts = gestureRuntimeOperationFacts({ unsupported: denial });
86+
87+
expect(facts).toEqual({
88+
performGesturePlan: denial,
89+
performDirectionalFlingPlan: denial,
90+
performMultiTouchGesturePlan: denial,
91+
performTargetAuthoredDrag: denial,
92+
gestureViewport: denial,
93+
});
94+
expect(Object.isFrozen(facts)).toBe(true);
95+
});
96+
6497
test('a local binding executes the plan through the owner interactor', async () => {
6598
const performGesture = vi.fn(async () => ({ backend: 'adb' }));
6699
const resolveInteractor = vi.fn(async () => ({ performGesture }) as unknown as Interactor);
@@ -110,11 +143,9 @@ test('a binding exposes only the tiers its owner facts admitted', () => {
110143
device,
111144
signal: new AbortController().signal,
112145
facts: gestureRuntimeOperationFacts({
146+
unsupported: unavailable,
113147
plan: available,
114-
directionalFling: unavailable,
115-
multiTouch: unavailable,
116148
targetAuthoredDrag: unavailable,
117-
viewport: unavailable,
118149
}),
119150
resolveInteractor: async () => ({ performGesture: async () => ({}) }) as unknown as Interactor,
120151
});

‎packages/contracts/src/gesture-runtime.ts‎

Lines changed: 29 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ import {
88
type ProviderInteractorOperationResolver,
99
} from './interactor-operation-binding.ts';
1010
import type { Interactor, RunnerContext } from './interactor-types.ts';
11-
import type { RuntimeOperationFact } from './platform-runtime.ts';
11+
import type { RuntimeOperationFact, RuntimeOperationUnavailability } from './platform-runtime.ts';
1212
import { invalidRuntimeContract } from './runtime-contract-error.ts';
1313
import type { SnapshotRuntimeExecution } from './snapshot-runtime.ts';
1414

@@ -70,22 +70,38 @@ export type GestureRuntimeOperationFacts = Readonly<{
7070
gestureViewport: RuntimeOperationFact;
7171
}>;
7272

73+
/**
74+
* What an owner declares about the gesture family. Every tier is a per-owner claim — no tier is
75+
* one every owner serves, and several owners serve none — so every tier is optional and
76+
* `unsupported` names the denial an omitted tier reports. The tiers split exactly where an owner's
77+
* mechanics split, so an owner states a tier only to say something the family denial does not.
78+
*
79+
* Omission is a classified denial, never an unclassified tier and never an implied success: the
80+
* type refuses a call that does not carry `unsupported`, so no owner can leave the family blank.
81+
* `unsupported` must refuse the family rather than one tier of it, because whatever the owner
82+
* leaves unnamed reports that cell verbatim.
83+
*/
84+
export type GestureRuntimeOperationFactsInput = Readonly<{
85+
unsupported: RuntimeOperationUnavailability;
86+
plan?: RuntimeOperationFact;
87+
directionalFling?: RuntimeOperationFact;
88+
multiTouch?: RuntimeOperationFact;
89+
targetAuthoredDrag?: RuntimeOperationFact;
90+
viewport?: RuntimeOperationFact;
91+
}>;
92+
7393
/** Builds the exhaustive owner claims for the five gesture requirements. */
7494
export function gestureRuntimeOperationFacts(
75-
input: Readonly<{
76-
plan: RuntimeOperationFact;
77-
directionalFling: RuntimeOperationFact;
78-
multiTouch: RuntimeOperationFact;
79-
targetAuthoredDrag: RuntimeOperationFact;
80-
viewport: RuntimeOperationFact;
81-
}>,
95+
input: GestureRuntimeOperationFactsInput,
8296
): GestureRuntimeOperationFacts {
97+
const declared = (fact: RuntimeOperationFact | undefined): RuntimeOperationFact =>
98+
fact ?? input.unsupported;
8399
return Object.freeze({
84-
performGesturePlan: input.plan,
85-
performDirectionalFlingPlan: input.directionalFling,
86-
performMultiTouchGesturePlan: input.multiTouch,
87-
performTargetAuthoredDrag: input.targetAuthoredDrag,
88-
gestureViewport: input.viewport,
100+
performGesturePlan: declared(input.plan),
101+
performDirectionalFlingPlan: declared(input.directionalFling),
102+
performMultiTouchGesturePlan: declared(input.multiTouch),
103+
performTargetAuthoredDrag: declared(input.targetAuthoredDrag),
104+
gestureViewport: declared(input.viewport),
89105
});
90106
}
91107

‎packages/contracts/src/platform-runtime-unavailable.ts‎

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -224,13 +224,7 @@ export function createUnavailablePlatformRuntimeFacts(
224224
}),
225225
...viewportRuntimeOperationFacts({ setViewport: frozen.viewport }),
226226
...focusRuntimeOperationFacts({ focus: frozen.focus }),
227-
...gestureRuntimeOperationFacts({
228-
plan: frozen.gesture,
229-
directionalFling: frozen.gesture,
230-
multiTouch: frozen.gesture,
231-
targetAuthoredDrag: frozen.gesture,
232-
viewport: frozen.gesture,
233-
}),
227+
...gestureRuntimeOperationFacts({ unsupported: frozen.gesture }),
234228
...scrollRuntimeOperationFacts({ scroll: frozen.scroll }),
235229
...typeTextRuntimeOperationFacts({ type: frozen.typeText }),
236230
...touchRuntimeOperationFacts({

‎packages/platform-android/src/runtime.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -319,6 +319,7 @@ export function createAndroidPlatformRuntime(host: PlatformRuntimeHost): Platfor
319319
...viewportRuntimeOperationFacts({ setViewport: viewportUnavailable }),
320320
...focusRuntimeOperationFacts({ focus: androidTouchFact(device) }),
321321
...gestureRuntimeOperationFacts({
322+
unsupported: gestureKindUnavailable,
322323
plan: androidGestureFact(device),
323324
directionalFling: androidGestureFact(device),
324325
multiTouch: androidTouchTargetFact(device, androidTvMultiTouchUnavailable),

‎packages/platform-apple/src/gesture-facts.ts‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,10 @@ import {
44
TARGET_AUTHORED_DRAG_UNSUPPORTED_HINT,
55
} from '@agent-device/contracts/gesture-admission';
66
import { gestureRuntimeOperationFacts } from '@agent-device/contracts/gesture-runtime';
7-
import type { RuntimeOperationFact } from '@agent-device/contracts/platform-runtime';
7+
import type {
8+
RuntimeOperationFact,
9+
RuntimeOperationUnavailability,
10+
} from '@agent-device/contracts/platform-runtime';
811
import { scrollRuntimeOperationFacts } from '@agent-device/contracts/scroll-runtime';
912
import { resolveDeviceAppleOs, type DeviceInfo } from '@agent-device/kernel/device';
1013

@@ -38,6 +41,7 @@ function unsupportedAppleDeviceKind(hint: string) {
3841
export function appleGestureAndScrollFacts(device: DeviceInfo) {
3942
return {
4043
...gestureRuntimeOperationFacts({
44+
unsupported: appleGestureFamilyUnavailable(device),
4145
plan: appleGesturePlanFact(device),
4246
directionalFling: appleGesturePlanFact(device),
4347
multiTouch: appleMultiTouchGestureFact(device),
@@ -48,6 +52,13 @@ export function appleGestureAndScrollFacts(device: DeviceInfo) {
4852
};
4953
}
5054

55+
/** The reason this leaf refuses gestures it does not name, before any tier is consulted. */
56+
function appleGestureFamilyUnavailable(device: DeviceInfo): RuntimeOperationUnavailability {
57+
return device.appleOs === 'watchos' || device.appleOs === 'visionos'
58+
? gestureLeafUnavailable
59+
: gestureKindUnavailable;
60+
}
61+
5162
function appleGesturePlanFact(device: DeviceInfo): RuntimeOperationFact {
5263
if (device.appleOs === 'watchos' || device.appleOs === 'visionos') return gestureLeafUnavailable;
5364
return appleTouchKind(device) ? available : gestureKindUnavailable;

‎packages/platform-harmonyos/src/runtime.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -252,6 +252,7 @@ export function createHarmonyPlatformRuntime(host: PlatformRuntimeHost): Platfor
252252
// Gestures share focus's HDC-driven kind cell; only the two tiers HDC cannot synthesize
253253
// are refused.
254254
...gestureRuntimeOperationFacts({
255+
unsupported: gestureKindUnavailable,
255256
plan: harmonyGestureFact(device),
256257
directionalFling: harmonyGestureFact(device),
257258
multiTouch: multiTouchUnavailable,

‎packages/platform-linux/src/runtime.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -247,6 +247,7 @@ function linuxFacts(device: DeviceInfo): RuntimeFacts<PlatformRuntimeOperations>
247247
// every cell — a direction-authored fling's speed semantics, two-contact synthesis, and
248248
// target-authored drag timing.
249249
...gestureRuntimeOperationFacts({
250+
unsupported: gestureKindUnavailable,
250251
plan: linuxDesktopFact(device, gestureKindUnavailable),
251252
directionalFling: directionalFlingUnavailable,
252253
multiTouch: multiTouchUnavailable,

‎packages/platform-vega/src/runtime.ts‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -232,11 +232,9 @@ function vegaFacts(device: DeviceInfo): RuntimeFacts<PlatformRuntimeOperations>
232232
// one; the rest had no retired closure and now refuse at admission rather than inside the
233233
// Vega interactor.
234234
...gestureRuntimeOperationFacts({
235-
plan: gestureUnavailable,
236-
directionalFling: gestureUnavailable,
235+
unsupported: gestureUnavailable,
237236
multiTouch: multiTouchUnavailable,
238237
targetAuthoredDrag: targetAuthoredDragUnavailable,
239-
viewport: gestureUnavailable,
240238
}),
241239
},
242240
});

‎packages/platform-web/src/runtime.ts‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -399,11 +399,8 @@ function webRuntimeFacts(
399399
// outright. Drag is the exception it checked FIRST, by naming the phases an adapter needs.
400400
...scrollRuntimeOperationFacts({ scroll: browserDevice }),
401401
...gestureRuntimeOperationFacts({
402-
plan: gestureUnavailable,
403-
directionalFling: gestureUnavailable,
404-
multiTouch: gestureUnavailable,
402+
unsupported: gestureUnavailable,
405403
targetAuthoredDrag: targetAuthoredDragUnavailable,
406-
viewport: gestureUnavailable,
407404
}),
408405
...viewportRuntimeOperationFacts({ setViewport: browserDevice }),
409406
// The web backend has no point-addressed read: `get` answers from the captured DOM tree,

‎packages/provider-limrun/src/app-log-runtime.test.ts‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -481,11 +481,16 @@ test('closes every Limrun gesture and scroll cell without a live session', async
481481
const facts = await owner.inspectFacts(limrunAndroid);
482482
for (const operation of [
483483
'performGesturePlan',
484+
'performDirectionalFlingPlan',
484485
'performMultiTouchGesturePlan',
485486
'performTargetAuthoredDrag',
486487
'gestureViewport',
487488
'scrollDirection',
488489
] as const) {
489-
expect(facts.operations[operation].available).toBe(false);
490+
expect(facts.operations[operation]).toMatchObject({
491+
available: false,
492+
reason: 'owner-capability-missing',
493+
hint: 'Limrun requires a matching live provider session for this device.',
494+
});
490495
}
491496
});

0 commit comments

Comments
 (0)