@enhance-eng/sdk 0.1.0-dev.sha-d9190c779d58 → 0.1.160

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Enhance SDK
2
2
 
3
- Publish editable customer journeys from tests to an existing Enhance canvas. Captures use the same browser snapshot kernel and editable-screen compiler as the product.
3
+ Publish editable customer journeys from tests to Enhance. Each execution can create its own review canvas; existing integrations can still update a fixed canvas. Captures use the same browser snapshot kernel and editable-screen compiler as the product.
4
4
 
5
5
  Requires Node.js 24 or later. The Playwright entry points require `@playwright/test` 1.62 or later (before 2.0). Install one package:
6
6
 
@@ -51,14 +51,18 @@ export default defineConfig({
51
51
  reporter: [
52
52
  ['list'],
53
53
  ['@enhance-eng/sdk/playwright/reporter', {
54
- canvas: 'YOUR_CANVAS_UUID',
54
+ destination: { organisationId: 'YOUR_TEAM_UUID' }, // {} for your personal space
55
55
  source: 'storefront',
56
+ runKey: process.env.CAPTURE_EXECUTION_ID, // Unique execution; shared by its shards
57
+ revision: process.env.CAPTURE_REVISION,
58
+ context: { key: 'pr:142', label: 'PR 142', sequence: Number(process.env.CAPTURE_EXECUTION_NUMBER) },
59
+ compareTo: { reference: 'main' },
56
60
  }],
57
61
  ],
58
62
  });
59
63
  ```
60
64
 
61
- Create an agent token in **Settings → Agent tokens** in the destination environment and store it as the `ENHANCE_TOKEN` secret in your CI runner (or environment variable locally). Its owner must be able to edit the destination canvas. Use the canvas UUID from its `/c/<uuid>` URL. Credentials stay in the Node process, outside captured pages and artifacts. Reporter options `environment`, `apiUrl`, and `token` override their corresponding environment variables.
65
+ Create an agent token in **Settings → Agent tokens** in the destination environment and store it as the `ENHANCE_TOKEN` secret in your CI runner (or environment variable locally). Its owner must belong to the destination team. For a fixed canvas, specify `canvas` instead of `destination` and use the UUID from its `/c/<uuid>` URL; its owner must be able to edit that canvas. Credentials stay in the Node process, outside captured pages and artifacts. Reporter options `environment`, `apiUrl`, and `token` override their corresponding environment variables.
62
66
 
63
67
  ```ts
64
68
  import { test } from '@playwright/test';
@@ -73,16 +77,17 @@ test('checkout', async ({ page }) => {
73
77
  });
74
78
  ```
75
79
 
76
- Wait for the state you intend to capture before calling `capture`. The adapter checks that the DOM and preview settle together. A moving page or unavailable required resource fails capture instead of publishing a partial mock.
80
+ Wait for the state you intend to capture before calling `capture`. The adapter waits briefly for the DOM and preview to settle together. A page that keeps moving is captured as it last looked, and a resource that cannot be fetched is left out; the screen is always published so you can see it and fix what is off.
77
81
 
78
82
  ## Identity and updates
79
83
 
80
- `source`, `journey`, `step` and `variant` identify a frame. Use stable keys; labels may be friendlier. The default variant is the Playwright project name. `order` is optional within one test; use explicit unique orders when several tests contribute to the same journey.
84
+ `source`, `journey`, `step` and `variant` identify a frame. Use stable keys; labels may be friendlier. The default variant is the Playwright project name. `order` is optional; when several captures share a position, they are ordered by test file, then by the test's line, then by call order. Capturing the same step twice in one test publishes both, the second as "cart (2)"; a step that several tests capture is published once per test, named "cart · <test title>". Names longer than 160 characters are shortened the same way on every run.
81
85
 
82
86
  ```ts
83
87
  await enhance.capture(page, {
84
88
  journey: 'checkout',
85
89
  journeyLabel: 'Customer checkout',
90
+ page: 'Shopping',
86
91
  step: 'payment',
87
92
  label: 'Choose payment method',
88
93
  variant: 'mobile',
@@ -94,7 +99,9 @@ await enhance.capture(page, {
94
99
 
95
100
  Blocked elements are excluded from the editable snapshot and masked in its preview. Capture test accounts and fixtures appropriate for sharing with everyone who can read the destination canvas. The adapter retains resource bytes; it does not upload authentication headers or a live browser session.
96
101
 
97
- The reporter reserves a run before tests capture anything. It publishes only after the whole run passes, selecting the final successful attempt for each test. Failed, skipped and interrupted attempts contribute no frames. Missing steps stay on the canvas. New steps append without overlapping other frames. Updates keep frame identity and human positioning/naming; changed editable content or locks cause a conflict instead of overwriting the designer's work.
102
+ Every step of a journey/variant uses the same optional `page`. Journeys with the same page name share that page. Unspecified pages share the default page. Page names, labels and order are layout metadata; they do not change screen identity.
103
+
104
+ The reporter reserves a run before tests capture anything. When the test run ends, it publishes every test's screens from that test's last attempt that captured anything, whether the test passed or failed: a failing test's screens show what went wrong. A problem with one screen never stops the others from publishing. A new run canvas contains the captures from that execution. For a fixed destination canvas, missing steps stay on the canvas and new steps append without overlapping other frames. Updates keep frame identity and human positioning/naming. A frame a person edited or locked is kept as it is, and the new capture is added beside it; later runs update the new frame. A frame a person deleted comes back on the next run; take the capture out of the test to stop it.
98
105
 
99
106
  Each publication is atomic. An identical capture compiled by the same server release leaves the document unchanged. A changed capture retains the previous and current source previews for the frame's **Compare with previous capture** action.
100
107
 
@@ -120,18 +127,79 @@ const receipt = await enhance.captures.publishManifest('./saved-capture/manifest
120
127
  console.log(receipt.canvasUrl);
121
128
  ```
122
129
 
123
- After a timeout or connection loss, repeat `publishManifest` with the **same manifest**. The server returns the original receipt if the run already committed. Do not create a fresh run to upload an old capture: its canvas baseline is no longer current. Runs expire after 24 hours; expired or cancelled runs require fresh captures. An unfinished run also requires fresh captures if the server compiler release changes. Recovery uses the same agent token that reserved the run.
130
+ After a timeout or connection loss, repeat `publishManifest` with the **same manifest**. The server returns the original receipt if the run already committed. Do not create a fresh run to upload an old capture: its canvas baseline is no longer current. A run expires 24 hours after its last upload or seal; expired or cancelled runs require fresh captures. A deploy of Enhance during a test run does not affect it. Every request is retried after a dropped connection, a timeout, a server error or "too many requests", up to three attempts. If publishing takes longer than the wait, the SDK prints the run and canvas it is still publishing to, and does not fail the test run. Recovery uses the same agent token that reserved the run.
124
131
 
125
132
  `run.cancel()` returns `null` when the run is cancelled, or its receipt if publication already committed. It never undoes committed canvas changes.
126
133
 
127
134
  Node producers may call `enhance.captures.begin({ canvas, source, runKey })`, then `run.add({ artifact, blobs })` and `run.publish()`. The artifact schema and checksum rules are exported from the root entry point. Producers supply frozen source, preview and resource bytes; they never map browser elements into canvas primitives.
128
135
 
129
- Multi-participant runs require a descriptor with every expected participant reserved before execution. Reporters can stage one participant with `run`, `participant` and `publish: false`. Publication refuses incomplete manifests. Automatic shard collection and additional framework adapters are not included in this release.
136
+ ## Review runs and baselines
137
+
138
+ A `destination` creates one ordinary canvas per `source` and `runKey`. Repeating the reservation with the same token, metadata and participants returns the same run. Give a new execution a new key, including a CI rerun attempt. A `title` is optional. The default title includes the source, context label and execution key so concurrent work remains distinguishable in the existing canvas list.
139
+
140
+ `context.key` groups successive executions of the same change, for example a PR or deployment. `sequence` orders executions within that context; `attempt` orders reruns of that sequence and defaults to zero. Supply the pipeline's increasing execution number, not a PR number for every execution. Older jobs finishing late cannot displace a newer published run. `revision` identifies the version actually captured, including a synthetic merge revision when that is what the tests run.
141
+
142
+ `compareTo: { reference: 'main' }` pins that reference when the run begins. `compareTo: { reference: 'main', revision: baseRevision }` selects a previously promoted capture of that revision. `compareTo: { runId }` selects a particular published run. Baselines must belong to the same destination and source. A missing unversioned reference starts without a before; an explicitly requested revision must exist. Matching uses source, journey, step and variant. Later promotions do not change existing pairs.
143
+
144
+ The canvas Review tab lists changed/new screens and offers all captured screens for flow context. A changed screen opens the existing before/after viewer. The change index compares decoded image pixels, dimensions and pixel ratio; labels, PNG compression, timestamps and compiler changes do not count as visual changes. Unavailable image evidence stays unclassified. There is no pixel threshold or automatic approval.
145
+
146
+ Choose **Approved** or **Changes requested** for the whole canvas. Comments, ordinary frame editing/duplication and MCP work as on any other canvas. Share an alternative with an engineer or agent; the next test execution creates a fresh review. Older comments and alternatives remain on the older canvas.
147
+
148
+ ```ts
149
+ const review = await enhance.captures.review(receipt.canvasId);
150
+ if (review?.latest.id !== receipt.runId) throw new Error('A newer run replaced this review');
151
+ if (review.current.verdict !== 'approved') throw new Error('Product review is not approved');
152
+ ```
153
+
154
+ Your pipeline decides when to read that verdict and what it gates. For example, a CI job can wait/poll for a decision or a later deployment job can check it. Enhance does not install branch rules or merge/deploy on your behalf. The API is the same for GitHub Actions, another CI provider, and local scripts.
155
+
156
+ After the corresponding version merges or deploys successfully, promote its captured run explicitly:
157
+
158
+ ```ts
159
+ // Read and retain this version before the pipeline step that changes the reference.
160
+ const previous = await enhance.captures.reference(receipt.canvasId, 'main');
161
+ // After that merge/deployment succeeds:
162
+ await enhance.captures.promote({
163
+ canvasId: receipt.canvasId,
164
+ name: 'main',
165
+ expectedVersion: previous?.version ?? 0,
166
+ revision: landedRevision,
167
+ });
168
+ ```
169
+
170
+ `revision` on promotion records which accepted version this existing capture represents; it does not rewrite the captured revision. A stale `expectedVersion` refuses promotion. Inspect the pipeline's actual merge/deployment ordering before retrying with a newer version. Repeating a successful promotion is idempotent. Approval alone never promotes a baseline. No extra production Playwright run is required to promote existing evidence; if a different combined version needs evidence, schedule another test run in your pipeline.
171
+
172
+ ## Shards
173
+
174
+ For native Playwright sharding, the reporter reserves all `shard-1` through `shard-N` participants automatically. Every shard needs the same explicit `runKey` and metadata. Upload each reporter output directory as a CI artifact. In a final job, download the directories and call:
175
+
176
+ ```ts
177
+ const receipt = await enhance.captures.publishManifests([
178
+ './shard-1/manifest.json',
179
+ './shard-2/manifest.json',
180
+ ]);
181
+ ```
182
+
183
+ This combines manifests and reads their existing blobs through the same publisher. It publishes the shards it is given, whatever their result; a shard whose manifest is missing contributes nothing, and a shard given twice counts once (the first copy). It refuses manifests from different runs. Retry `publishManifests` with the same paths after a connection loss; it returns the durable receipt without publishing twice. Custom worker systems can reserve `participants` up front and supply the shared `run` descriptor plus the reporter's `participant`.
184
+
185
+
186
+ ## What a run reports
187
+
188
+ A run never reports a degraded capture as a whole one. The receipt carries the run's capture issues, each with a code and a message, and the SDK prints one line per issue under the canvas address, each starting with `Enhance:`:
189
+
190
+ ```text
191
+ Enhance: https://app.enhancelabs.ai/c/…
192
+ Enhance: file-not-copied: 2 files could not be copied.
193
+ Enhance: capture-left-out: Checkout › Payment: none of its files arrived
194
+ Enhance: file-not-uploaded: https://cdn.example.com/hero.webp: Enhance's storage refused it
195
+ ```
196
+
197
+ The codes are `capture-left-out`, `page-not-settled`, `file-not-copied`, `file-missing`, `file-mismatched`, `preview-used`, `preview-uncompared`, `screen-degraded`, `unsupported-surface` and `frame-not-frozen`. A file that the SDK gave up on gets its own line with its address and the reason: it could not be read on this machine, or storage refused it for good. A storage outage is retried; it is never reported as a missing file. When the run's own reservation had expired, the first line names the run that published its captures instead.
130
198
 
131
199
  ## Limits
132
200
 
133
- Publication accepts at most 30,000 live canvas nodes in total, including existing artwork. A run accepts at most 64 selected steps and 256 MiB of distinct blobs. Each blob is at most 16 MiB; each PNG preview is at most 16 million pixels. Preview dimensions must match the captured CSS extent at the declared pixel ratio. Split very large journeys or capture a viewport instead of an unlimited full page.
201
+ Preview dimensions must match the captured CSS extent at the declared pixel ratio. Journeys, pages, runs and captured content have no new product ceilings. Existing transport upload batches are chunking, not a limit on a run's number of resources.
134
202
 
135
- Automatic placement uses axis-aligned outer layout boxes. A transformed journey, detached-frame ancestor or placement obstacle returns a layout conflict; reset its outer transform or use another canvas. Transforms inside captured screens are supported.
203
+ Automatic placement uses axis-aligned outer layout boxes. When a person locked or transformed a journey's row so it cannot take frames, the frames go in a row beside it. Transforms inside captured screens are supported.
136
204
 
137
- This release publishes editable frames and a source before/after comparison. It does not add pixel-diff scoring, approval workflows or pull-request gating.
205
+ This release retains original evidence and uses the shared editable-screen compiler. Existing preview fallback still applies when a screen cannot be compiled. Redlines, pixel heatmaps and diff scores can be added to the comparison UI without replacing the run or canvas model.