@enhance-eng/sdk 0.1.0-dev.sha-3f7dd0acb078

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 ADDED
@@ -0,0 +1,111 @@
1
+ # Enhance SDK
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.
4
+
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
+
7
+ ```sh
8
+ npm install --save-dev @enhance-eng/sdk
9
+ ```
10
+
11
+ Development prereleases use the same package: `npm install --save-dev @enhance-eng/sdk@next`.
12
+ To capture into the Enhance development environment, set
13
+ `ENHANCE_API_URL=https://api.enhance3.karunalabs.ai` and use a development agent token and canvas.
14
+ The package version does not select the server environment; `@next` is also public.
15
+
16
+ Configure the reporter in `playwright.config.ts`:
17
+
18
+ ```ts
19
+ import { defineConfig } from '@playwright/test';
20
+
21
+ export default defineConfig({
22
+ reporter: [
23
+ ['list'],
24
+ ['@enhance-eng/sdk/playwright/reporter', {
25
+ canvas: 'YOUR_CANVAS_UUID',
26
+ source: 'storefront',
27
+ }],
28
+ ],
29
+ });
30
+ ```
31
+
32
+ Create an agent token in **Settings → Agent tokens** 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. `ENHANCE_API_URL` defaults to `https://api.enhancelabs.ai`. Credentials stay in the Node process, outside captured pages and artifacts.
33
+
34
+ ```ts
35
+ import { test } from '@playwright/test';
36
+ import { enhance } from '@enhance-eng/sdk/playwright';
37
+
38
+ test('checkout', async ({ page }) => {
39
+ await page.goto('http://localhost:3000/cart');
40
+ await enhance.capture(page, { journey: 'checkout', step: 'cart' });
41
+
42
+ await page.getByRole('button', { name: 'Checkout' }).click();
43
+ await enhance.capture(page, { journey: 'checkout', step: 'payment' });
44
+ });
45
+ ```
46
+
47
+ 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.
48
+
49
+ ## Identity and updates
50
+
51
+ `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.
52
+
53
+ ```ts
54
+ await enhance.capture(page, {
55
+ journey: 'checkout',
56
+ journeyLabel: 'Customer checkout',
57
+ step: 'payment',
58
+ label: 'Choose payment method',
59
+ variant: 'mobile',
60
+ order: 1,
61
+ extent: 'viewport', // or 'full-page'
62
+ blockSelector: '[data-private]',
63
+ });
64
+ ```
65
+
66
+ 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.
67
+
68
+ 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.
69
+
70
+ 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.
71
+
72
+ ## Local artifacts and recovery
73
+
74
+ Every reporter invocation creates a separate directory below `.enhance/captures` (or the configured `directory`). It contains a reserved run descriptor, content-addressed blobs, `manifest.json`, and a receipt after publication. Keep the complete directory when moving artifacts between machines.
75
+
76
+ Set reporter `publish: false` to stage captures without publishing. A valid token is still required to reserve the canvas baseline unless you supply a descriptor reserved earlier.
77
+
78
+ The existing Enhance CLI can publish the same saved manifest with its authenticated credentials:
79
+
80
+ ```sh
81
+ enhance captures publish ./saved-capture/manifest.json
82
+ ```
83
+
84
+ The core Node entry point publishes the same manifest; it has no Playwright dependency:
85
+
86
+ ```ts
87
+ import { createEnhance } from '@enhance-eng/sdk';
88
+
89
+ const enhance = createEnhance({
90
+ apiUrl: process.env.ENHANCE_API_URL ?? 'https://api.enhancelabs.ai',
91
+ token: process.env.ENHANCE_TOKEN ?? '',
92
+ });
93
+ const receipt = await enhance.captures.publishManifest('./saved-capture/manifest.json');
94
+ console.log(receipt.canvasUrl);
95
+ ```
96
+
97
+ 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.
98
+
99
+ `run.cancel()` returns `null` when the run is cancelled, or its receipt if publication already committed. It never undoes committed canvas changes.
100
+
101
+ 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.
102
+
103
+ 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.
104
+
105
+ ## Limits
106
+
107
+ 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.
108
+
109
+ 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.
110
+
111
+ This release publishes editable frames and a source before/after comparison. It does not add pixel-diff scoring, approval workflows or pull-request gating.