Skip to content

Commit 01be1a3

Browse files
committed
Merge remote-tracking branch 'origin/main' into pr3108-fallow
* origin/main: (36 commits) fix(android): rebind the test IME when its commit went to a stale input session (callstack#3061) feat: release public workspace packages through npm publish (callstack#3252) fix(snapshot): stop a SwiftUI toolbar host from covering the sheet it encloses (callstack#3162) ci(ios): prepare the runner before the fixture E2E so open does not pay its start (callstack#3251) fix(apple-runner): fence prep spawns behind a start-owned admission (callstack#3239) 0.21.22 test(apple): own the simctl settings plan tests in simctl-settings.test.ts (callstack#3244) fix(limrun): report the session device id in iOS settings refusals (callstack#3243) 0.21.21 feat(remote): add a host-allocated macos-app lease backend (callstack#3236) test(android): bound the screenshot write wait by wall time, not event-loop turns (callstack#3250) feat(recording): cap the touch overlay frame rate at the caller's --fps (callstack#3241) fix(ad-script): let .ad scripts carry scroll --until and wait capture flags (callstack#3197) (callstack#3234) feat(provider-webdriver): keyboard enter, dismiss, and status over WebDriver (callstack#3233) feat(selectors): match role= against snapshot kind with a node-scoped alias window (callstack#3232) fix(provider-webdriver): read field values, placeholders, secure fields, and checked state from page source (callstack#3231) feat(replay): accept --test-ime on test and replay so flow-owned Android opens opt into the test IME (callstack#3235) refactor(daemon): route daemon-level diagnostics through one scope helper (callstack#3242) docs(adr): correct ADR 0031 pointer event delivery evidence (callstack#3245) fix(ios): stop a tap's post-gesture lookup from recording an XCTest failure (callstack#3060) (callstack#3237) ...
2 parents ad853d0 + 80c771e commit 01be1a3

356 files changed

Lines changed: 16252 additions & 1871 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ios.yml‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -199,7 +199,6 @@ jobs:
199199
run: |
200200
xcrun simctl install "${{ steps.ios-simulator.outputs.simulator-udid }}" "${{ steps.fixture-app.outputs.app-path }}"
201201
node --experimental-strip-types src/bin.ts test examples/test-app/replays/gesture-pan-duration.ad --udid "${{ steps.ios-simulator.outputs.simulator-udid }}" --timeout 180000 --retries 2 --artifacts-dir test/artifacts/replays-ios-gesture-pan-duration --report-junit test/artifacts/replays-ios-gesture-pan-duration.junit.xml
202-
pnpm clean:daemon
203202
204203
- name: Run fixture-backed iOS simulator E2E smoke
205204
env:

‎.github/workflows/replays-manual.yml‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -156,9 +156,7 @@ jobs:
156156
- name: Prove selector drag reaches its destination on iOS
157157
run: |
158158
xcrun simctl install "${{ steps.ios-simulator.outputs.simulator-udid }}" "${{ steps.fixture-app.outputs.app-path }}"
159-
pnpm clean:daemon
160159
node --experimental-strip-types src/bin.ts replay examples/test-app/replays/drag.ad --platform ios --udid "${{ steps.ios-simulator.outputs.simulator-udid }}" --session nightly-ios-target-drag --json
161-
pnpm clean:daemon
162160
163161
- name: Run full fixture-backed iOS simulator E2E
164162
env:

‎CONTRIBUTING.md‎

Lines changed: 60 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -82,14 +82,70 @@ so name the version the CI lanes install and the published helper matches the CI
8282
`pnpm package:npm` is a release guard, not a routine development command. Use the specific commands
8383
above while iterating.
8484

85+
### Release the core and public workspace packages together
86+
87+
The root `package.json` owns the release version. Every public workspace package uses that version;
88+
private internal packages stay unpublished. There is one Git tag and GitHub release, `v<version>`,
89+
for the whole release. No changeset files or per-package tags are needed.
90+
91+
From a clean release checkout, bump the version once:
92+
93+
```bash
94+
npm version patch
95+
# or npm version minor / npm version 0.22.0
96+
```
97+
98+
The version hook synchronizes all public workspace manifests and MCP metadata, stages them, and
99+
includes them in npm's version commit and `v<version>` tag. Do not bump plugin versions separately.
100+
101+
Publish and push using the normal npm workflow:
102+
103+
```bash
104+
npm publish && git push && git push --tags
105+
```
106+
107+
The publish hooks prepare and validate every public package before uploading the core, then
108+
publish the remaining workspace packages at the same version. Private packages stay unpublished.
109+
After every package succeeds, the hook commits all public manifests and MCP metadata at the next
110+
`-dev` version. Your `git push` includes that commit; the version bump created the single release
111+
tag. Write one GitHub release covering the core and plugins.
112+
113+
After setting the version, preview the full release with `npm publish --dry-run`. It builds and
114+
checks the packages without uploading them, changing versions, or creating commits. The dry-run
115+
publish hook makes no additional registry requests. Dependency installation during preparation
116+
still requires registry access unless the dependencies are cached. Publishing requires npm registry access for
117+
`agent-device` and the `@agent-device` scope.
118+
119+
If core publication succeeds but a later package fails, run `pnpm release:publish` to finish the
120+
release. It skips versions already published and commits the development marker once every package
121+
succeeds. Plain `npm publish` cannot retry an already-published core version.
122+
If every upload succeeds but development-marker synchronization or its Git commit fails, fix the
123+
reported error and run `pnpm release:mark-dev` to finish any interrupted version synchronization, then commit the
124+
changed public manifests and `server.json` before pushing. No package needs republishing.
125+
126+
Use `npm pack` to build and validate a development-version package locally. The normal npm and
127+
pnpm publishers repack the prepared files when uploading; the checks validate package contents,
128+
not the byte identity of the uploaded archive.
129+
130+
A public package owns its `files`, published `exports`, license, repository metadata, README,
131+
and `prepack` build (including any prerequisites). Use `publishConfig.exports` for source-only
132+
workspace test exports; pnpm applies the overrides when packing. Keep plugin SDK imports and
133+
bundled workspace helpers in `devDependencies`. Plugins must not depend on the core at runtime
134+
or through a peer dependency. Their factories receive the host from `agent-device`.
135+
136+
When adding a public package, initialize its version from the root `package.json`; subsequent
137+
`npm version` and `release:mark-dev` runs keep it synchronized automatically. An optional plugin
138+
must have no production import from the core build or production dependency in the root manifest.
139+
Run its packed-install smoke before releasing.
140+
85141
### The version on main never equals a published version
86142

87-
`release:publish` runs `release:mark-dev` right after `npm publish`, moving `package.json` (and the
88-
synchronized `server.json`) to the next patch with a `-dev` prerelease marker (for example
89-
`0.20.11-dev`). Commit that bump as part of the release. The invariant it protects: MCP registry
143+
`postpublish` runs `release:mark-dev` after all packages publish, moving all public manifests
144+
and synchronized `server.json` to the next patch with a `-dev` prerelease marker (for example
145+
`0.20.11-dev`) and committing that bump as part of the release. The invariant it protects: MCP registry
90146
scanners diff the repository's tool surface per version string, so a released number left on `main`
91147
while `main` keeps changing is indistinguishable from a republished ("rug-pull") version.
92-
`release:prepare` enforces the inverse direction and refuses to publish while the `-dev` marker is
148+
`prepublishOnly` and the retry command refuse to publish while the `-dev` marker is
93149
still in place — set the real release version first (for example `npm version patch`, which strips
94150
the prerelease marker), commit, then publish.
95151

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
package com.callstack.agentdevice.snapshothelper;
2+
3+
import android.content.Context;
4+
import android.graphics.Rect;
5+
import android.os.Build;
6+
import android.util.DisplayMetrics;
7+
import android.view.Display;
8+
import android.view.WindowManager;
9+
10+
/**
11+
* The physical display the captured bounds were measured on, in physical pixels, in the current
12+
* rotation (#3182).
13+
*
14+
* Node bounds reach the host through {@code AccessibilityNodeInfo.getBoundsInScreen()}, which is
15+
* absolute screen space across every interactive window, SystemUI's navigation bar included. The
16+
* extent therefore has to be the real display extent rather than {@code Resources.getSystem()}'s
17+
* app display size: the latter excludes a persistent navigation bar, so a nav-bar node's rect would
18+
* land outside the published box. On API 30+ that extent is
19+
* {@code WindowManager.getMaximumWindowMetrics().getBounds()}; below it, {@code
20+
* Display.getRealMetrics}, which likewise carries the full panel and not the app-usable inset.
21+
*
22+
* The caller reads this twice around the tree dump and publishes only what {@link #whenBothAgree}
23+
* returns. A rotation landing inside the dump changes the extent between the reads, and the capture
24+
* then says nothing about its box rather than pairing one rotation's bounds with the other's
25+
* dimensions. A display this process cannot address answers with null. Either way the host publishes
26+
* the absence it reads as unknown, and the host's own guard is what refuses a zero extent.
27+
*/
28+
final class DisplayExtent {
29+
private DisplayExtent() {}
30+
31+
/** The extent one read of the display answered with, in the current rotation. */
32+
static final class Extent {
33+
final int width;
34+
final int height;
35+
36+
Extent(int width, int height) {
37+
this.width = width;
38+
this.height = height;
39+
}
40+
}
41+
42+
/**
43+
* The extent of the display {@code context} is attached to, or null when this process could not
44+
* address it. A zero extent is passed through as read: refusing an unusable box is the host's job,
45+
* and {@code snapshotViewportSizeFrom} already refuses one, so a second refusal here would only
46+
* be a second place that decides what a usable display is.
47+
*/
48+
static Extent read(Context context) {
49+
try {
50+
WindowManager windowManager =
51+
(WindowManager) context.getSystemService(Context.WINDOW_SERVICE);
52+
if (windowManager == null) {
53+
return null;
54+
}
55+
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
56+
Rect bounds = windowManager.getMaximumWindowMetrics().getBounds();
57+
return new Extent(bounds.width(), bounds.height());
58+
}
59+
return legacyExtent(windowManager);
60+
} catch (Throwable error) {
61+
return null;
62+
}
63+
}
64+
65+
@SuppressWarnings("deprecation")
66+
private static Extent legacyExtent(WindowManager windowManager) {
67+
Display display = windowManager.getDefaultDisplay();
68+
DisplayMetrics metrics = new DisplayMetrics();
69+
display.getRealMetrics(metrics);
70+
return new Extent(metrics.widthPixels, metrics.heightPixels);
71+
}
72+
73+
/**
74+
* The extent both reads of one capture agreed on, or null when either read failed or the display
75+
* changed underneath the tree dump. Omitting the viewport on disagreement is what keeps the
76+
* published box a fact about the capture rather than about two different rotations.
77+
*/
78+
static Extent whenBothAgree(Extent before, Extent after) {
79+
if (before == null || after == null) {
80+
return null;
81+
}
82+
if (before.width != after.width || before.height != after.height) {
83+
return null;
84+
}
85+
return before;
86+
}
87+
}

‎android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/SnapshotInstrumentation.java‎

Lines changed: 24 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
import android.content.res.Resources;
66
import android.os.Bundle;
77
import android.util.Base64;
8+
import android.util.DisplayMetrics;
89
import java.io.BufferedReader;
910
import java.io.File;
1011
import java.io.FileOutputStream;
@@ -77,14 +78,17 @@ public void onStart() {
7778
return;
7879
}
7980
long startedAtMs = System.currentTimeMillis();
81+
DisplayExtent.Extent beforeDump = DisplayExtent.read(getContext());
8082
AccessibilityTreeCapture.Result capture =
8183
captureXml(waitForIdleQuietMs, waitForIdleTimeoutMs, timeoutMs, maxDepth, maxNodes);
84+
DisplayExtent.Extent display =
85+
DisplayExtent.whenBothAgree(beforeDump, DisplayExtent.read(getContext()));
8286
writeOutputFile(outputPath, capture.xml);
8387
if (emitChunks) {
8488
emitChunks(capture.xml);
8589
}
8690
result.putString("ok", "true");
87-
putCaptureMetadata(result, capture, System.currentTimeMillis() - startedAtMs);
91+
putCaptureMetadata(result, capture, display, System.currentTimeMillis() - startedAtMs);
8892
finishSafely(0, result);
8993
} catch (Throwable error) {
9094
result.putString("ok", "false");
@@ -114,7 +118,10 @@ private static void putBaseMetadata(
114118
}
115119

116120
private static void putCaptureMetadata(
117-
Bundle result, AccessibilityTreeCapture.Result capture, long elapsedMs) {
121+
Bundle result,
122+
AccessibilityTreeCapture.Result capture,
123+
DisplayExtent.Extent display,
124+
long elapsedMs) {
118125
result.putString("rootPresent", Boolean.toString(capture.rootPresent));
119126
result.putString("captureMode", capture.captureMode);
120127
result.putString("windowCount", Integer.toString(capture.windowCount));
@@ -124,8 +131,17 @@ private static void putCaptureMetadata(
124131
// Physical pixels per dp of the display the bounds above were measured on, from the same
125132
// configuration the framework lays out with (a `wm density` override included), so a host that
126133
// works in dp has the factor beside the pixels instead of a second adb round trip.
127-
result.putString(
128-
"pixelDensity", Float.toString(Resources.getSystem().getDisplayMetrics().density));
134+
DisplayMetrics metrics = Resources.getSystem().getDisplayMetrics();
135+
result.putString("pixelDensity", Float.toString(metrics.density));
136+
// The real extent of the display those bounds are measured in, read around the tree dump and
137+
// published only when both reads agreed, so the host can publish the box the bounds live in
138+
// without reading the tree for it. Published by absence: a display this helper could not
139+
// address, or one that rotated mid-dump, adds no keys, which the host reads as unknown rather
140+
// than as a screen of no size or of another rotation's size (#3182).
141+
if (display != null) {
142+
result.putString("displayWidth", Integer.toString(display.width));
143+
result.putString("displayHeight", Integer.toString(display.height));
144+
}
129145
}
130146

131147
private void runOneShotViewport(Bundle result) {
@@ -232,10 +248,13 @@ private void writeSessionSnapshot(
232248
result.putString("requestId", requestId);
233249
try {
234250
long startedAtMs = System.currentTimeMillis();
251+
DisplayExtent.Extent beforeDump = DisplayExtent.read(getContext());
235252
AccessibilityTreeCapture.Result capture =
236253
captureXml(waitForIdleQuietMs, waitForIdleTimeoutMs, timeoutMs, maxDepth, maxNodes);
254+
DisplayExtent.Extent display =
255+
DisplayExtent.whenBothAgree(beforeDump, DisplayExtent.read(getContext()));
237256
result.putString("ok", "true");
238-
putCaptureMetadata(result, capture, System.currentTimeMillis() - startedAtMs);
257+
putCaptureMetadata(result, capture, display, System.currentTimeMillis() - startedAtMs);
239258
result.putString("byteLength", Integer.toString(capture.xml.getBytes(StandardCharsets.UTF_8).length));
240259
SessionResponseWriter.writeSessionResponse(output, result, capture.xml);
241260
} catch (Throwable error) {
Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
package com.callstack.agentdevice.snapshothelper;
2+
3+
public final class DisplayExtentTest {
4+
private DisplayExtentTest() {}
5+
6+
private static final DisplayExtent.Extent PORTRAIT = new DisplayExtent.Extent(1080, 2400);
7+
private static final DisplayExtent.Extent LANDSCAPE = new DisplayExtent.Extent(2400, 1080);
8+
9+
static void run() {
10+
assertTwoReadsOfTheSameDisplayPublishItsExtent();
11+
assertADisplayThatMovedUnderTheDumpPublishesNothing();
12+
assertAReadThatFailedPublishesNothing();
13+
}
14+
15+
private static void assertTwoReadsOfTheSameDisplayPublishItsExtent() {
16+
// The rotation matters: a landscape capture publishes the box its bounds are actually measured
17+
// in, which is why the extent is read per capture rather than kept across a helper session.
18+
assertExtent(
19+
DisplayExtent.whenBothAgree(PORTRAIT, new DisplayExtent.Extent(1080, 2400)),
20+
1080,
21+
2400,
22+
"both reads of one portrait display");
23+
assertExtent(
24+
DisplayExtent.whenBothAgree(LANDSCAPE, LANDSCAPE),
25+
2400,
26+
1080,
27+
"both reads of one landscape display");
28+
}
29+
30+
private static void assertADisplayThatMovedUnderTheDumpPublishesNothing() {
31+
// A rotation landing inside the tree dump would pair that rotation's node bounds with the other
32+
// rotation's dimensions. The capture then names no box at all rather than a wrong one (#3182).
33+
assertNull(
34+
DisplayExtent.whenBothAgree(PORTRAIT, LANDSCAPE), "display rotated mid-dump");
35+
assertNull(
36+
DisplayExtent.whenBothAgree(
37+
PORTRAIT, new DisplayExtent.Extent(1076, 2400)),
38+
"display resized mid-dump");
39+
}
40+
41+
private static void assertAReadThatFailedPublishesNothing() {
42+
// A read that failed on either side of the dump leaves the box unknown: the surviving read says
43+
// nothing about what the tree between the two was measured against.
44+
assertNull(DisplayExtent.whenBothAgree(null, PORTRAIT), "read before the dump failed");
45+
assertNull(DisplayExtent.whenBothAgree(PORTRAIT, null), "read after the dump failed");
46+
assertNull(DisplayExtent.whenBothAgree(null, null), "both reads failed");
47+
}
48+
49+
private static void assertExtent(
50+
DisplayExtent.Extent extent, int width, int height, String label) {
51+
if (extent == null) {
52+
throw new AssertionError("expected an extent for " + label);
53+
}
54+
if (extent.width != width || extent.height != height) {
55+
throw new AssertionError(
56+
"wrong extent for " + label + ": got " + extent.width + "x" + extent.height);
57+
}
58+
}
59+
60+
private static void assertNull(DisplayExtent.Extent extent, String label) {
61+
if (extent != null) {
62+
throw new AssertionError(
63+
"expected no extent for " + label + " but got " + extent.width + "x" + extent.height);
64+
}
65+
}
66+
}

‎android/snapshot-helper/src/test/java/com/callstack/agentdevice/snapshothelper/SnapshotHelperTestSuite.java‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,5 +8,6 @@ public static void main(String[] args) throws Exception {
88
AccessibilityCaptureStabilizerTest.run();
99
BoundedUiAutomationConnectionTest.run();
1010
GestureViewportReaderTest.run();
11+
DisplayExtentTest.run();
1112
}
1213
}

0 commit comments

Comments
 (0)