@theaiplatform/miniapp-sdk 0.3.3 → 0.4.0

package/README.md

@@ -29,10 +29,90 @@ Start with the [Miniapp SDK documentation](https://docs.theaiplatform.app/miniap
 - `@theaiplatform/miniapp-sdk/config`
 - `@theaiplatform/miniapp-sdk/rspack`
 - `@theaiplatform/miniapp-sdk/testing/rstest`
+- `@theaiplatform/miniapp-sdk/testing/rstest-config`
+- `@theaiplatform/miniapp-sdk/testing/tap.test.schema.json`
 - `@theaiplatform/miniapp-sdk/config-schema.json`
 
 ## In-app E2E testing
 
+Pin the SDK to the exact version named by `manifest.compatibility.tapSdk`.
+Test Lab deliberately rejects ranges, tags, duplicate dependency declarations,
+and a manifest version that differs from the executing CLI:
+
+```json
+{
+  "devDependencies": {
+    "@theaiplatform/miniapp-sdk": "0.4.0"
+  }
+}
+```
+
+Generate or audit the test project with the installed package binary:
+
+```bash
+pnpm exec tap-miniapp-test list
+pnpm exec tap-miniapp-test scaffold
+pnpm exec tap-miniapp-test scaffold --check
+pnpm exec tap-miniapp-test matrix
+pnpm exec tap-miniapp-test doctor
+```
+
+All commands accept `--root`, `--manifest`, `--descriptor`, and `--json`.
+`scaffold` creates only missing files and preserves user-owned files.
+Its smoke test asserts the exact surface-target cell, profile, matrix entry,
+deterministic seed, SDK/host/runner versions, and all host-attested digests
+before exercising the universal surface remount control.
+`migrate --dry-run` previews the deterministic schema-v1 projection;
+`migrate` preserves the exact old document as `tap.test.v1.json` before an
+atomic replacement. Run `doctor` in CI so missing files, unsafe paths, stale
+versions, empty test selections, capability gaps, and surface applicability
+branches fail before Test Lab starts a browser.
+
+The generated `rstest.tap.config.ts` uses the public deterministic helper:
+
+```ts
+import { defineTapRstestConfig } from '@theaiplatform/miniapp-sdk/testing/rstest-config';
+
+export default defineTapRstestConfig();
+```
+
+It fixes Rstest to one worker, serial execution, no retries, no isolation, a
+Node test environment, and an error for empty suites. Safe Rstest options remain
+composable; incompatible overrides fail at config load rather than silently
+making a run nondeterministic.
+
+`tap.test.json` schema v2 describes profiles separately from matrix entries.
+Every manifest-declared surface and target needs exactly one positive matrix
+entry. A positive entry names the capabilities it verifies:
+
+- `action:<permission-action-id>`
+- `effect:<effect-kind>:<resource>`
+- `effect:<effect-kind>:*` when the manifest effect has no resources
+
+Write denied/error matrix entries for every high-risk action and host effect.
+Use `network.request` only for network-effect denial; use the all-denied `*`
+scenario for non-network effects. A waiver may temporarily replace a
+denied/error case only when it explains the gap and has a future `expiresAt`;
+it never replaces positive capability attribution. Put surface applicability
+in each matrix entry's `testMatch`, rather than returning or branching on
+`tap.surfaceId` inside a test shared by multiple surfaces.
+
+The canonical descriptor schema is published at
+`@theaiplatform/miniapp-sdk/testing/tap.test.schema.json`. Profile environment
+fields fix viewport, locale, IANA timezone, theme, reduced motion, and the
+unsigned 32-bit fixture seed. Set optional `fixedNow` to a canonical UTC RFC
+3339 instant such as `2026-01-01T00:00:00Z` when the app derives routes,
+queries, labels, or fixture data from the wall clock. The adapter installs that
+clock before mounting the surface, so tests never need to scrape a
+machine-dependent date and remount. Federated surfaces that create app-owned
+identifiers should use `context.entropy.randomUUID()`: ordinary mounts retain
+cryptographically strong UUIDs, while Test Lab derives a frame-scoped,
+resettable stream from this profile seed. This keeps retained remounts distinct
+and the same test sequence reproducible without test-only globals or query
+parameters. Artifact policy independently controls
+trace and screenshot capture with `off`, `failure-only`, or `always`, plus an
+optional total byte limit.
+
 The `/testing/rstest` entry point extends Rstest's Playwright fixtures with a
 host-provided miniapp surface and exact TAP session provenance. Tests can assert
 both the rendered UI and the package/surface identity selected by the Test Lab:
@@ -44,6 +124,9 @@ test('mounts the miniapp surface', async ({ surface, tap }) => {
   await expect(surface.locator('body')).toBeVisible();
   expect(tap.packageId).toBe('tap_pkg_example_0001');
   expect(tap.surfaceId).toBe('example-surface');
+  expect(tap.environment.seed).toBe(tap.seed);
+  expect(tap.environment.fixedNow).toBe('2026-01-01T00:00:00Z');
+  expect(tap.artifacts.trace).toBe('failure-only');
 });
 ```
 
@@ -61,7 +144,23 @@ requests through host consent instead of browser `fetch`, and
 secrets remain in the host vault and are injected only by the native request
 authority.
 
-## Converted VS Code webviews in 0.3.3
+Custom surface behavior can ask the exact mounted host for its current
+descriptor-declared action decision without executing that action:
+
+```ts
+const { allowed } = await sdk.authorization.check({
+  actionId: 'example.export',
+  autonomy: 'do',
+});
+```
+
+Use this advisory check to disable or explain custom UI before the user invokes
+it; the capability that performs the operation must still enforce authority.
+A declared but currently denied action resolves to `{ allowed: false }`. An
+action omitted from this exact surface's `authorization.allOf` rejects as a
+manifest defect. The check is read-only and never executes the queried action.
+
+## Converted VS Code webviews
 
 The `/vscode-webview` entry point mounts a converted, static VS Code webview in
 a sandboxed iframe while keeping platform authority in the outer federated

package/dist/bin/tap-miniapp-test.d.ts

@@ -0,0 +1 @@
+export { }