@ingcreators/annot-product-docs 0.2.0 → 0.3.0
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/CHANGELOG.md +190 -0
- package/README.md +37 -2
- package/dist/config.d.ts +14 -14
- package/dist/fixture.d.ts +45 -15
- package/dist/index.d.ts +4 -2
- package/dist/index.js +536 -449
- package/dist/mdx-annotations.d.ts +91 -0
- package/dist/playwright-screenshot-hook.d.ts +17 -0
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,195 @@
|
|
|
1
1
|
# @ingcreators/annot-product-docs
|
|
2
2
|
|
|
3
|
+
## 0.3.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 5778902: **MDX resolver moves home + auto-registers into the screenshot
|
|
8
|
+
patch** — Phase 2 of
|
|
9
|
+
`docs/plans/playwright-screenshot-fixture-relayer.md`. The
|
|
10
|
+
MDX-aware annotation pipeline that powers
|
|
11
|
+
`page.screenshot({ annot: { mdx: { id, path } } })` now lives in
|
|
12
|
+
`@ingcreators/annot-product-docs` (the package that already owns
|
|
13
|
+
MDX parsing + the `screen.capture()` fixture). Calls go through
|
|
14
|
+
annot-playwright's generic patch + the new
|
|
15
|
+
`annotSourceResolvers` hook registry, so consumers no longer
|
|
16
|
+
need an Astro peer dep for the dogfood tour pattern:
|
|
17
|
+
|
|
18
|
+
```ts
|
|
19
|
+
// Was: @ingcreators/annot-product-docs-astro/playwright
|
|
20
|
+
import { test } from "@ingcreators/annot-product-docs";
|
|
21
|
+
|
|
22
|
+
test("docs tour", async ({ page }) => {
|
|
23
|
+
await page.goto(APP_URL);
|
|
24
|
+
await page.screenshot({
|
|
25
|
+
path: "shots/app-overview.png",
|
|
26
|
+
annot: {
|
|
27
|
+
mdx: { id: "app-overview", path: "src/content/docs/app/index.mdx" },
|
|
28
|
+
tags: { source: "docs-tour", screen: "app-overview" },
|
|
29
|
+
},
|
|
30
|
+
});
|
|
31
|
+
});
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
The `annot: { mdx }` resolver fires in two stages:
|
|
35
|
+
1. `prepare()` — calls `captureScreen(page, { id, mdxPath })`
|
|
36
|
+
internally, refreshing the MDX's `annot:snapshot` +
|
|
37
|
+
`annot:attributes` blocks against the live page BEFORE the
|
|
38
|
+
raw screenshot is taken.
|
|
39
|
+
2. `resolveAnnotations(dims)` — reads the freshly-written
|
|
40
|
+
`annot:snapshot` block + `<Overlay match>` entries and
|
|
41
|
+
returns page-space `BboxNumberedBadgeAnnotation[]` which
|
|
42
|
+
annot-playwright merges with any caller-supplied
|
|
43
|
+
`annot.overlays` before rebasing onto the clipped image.
|
|
44
|
+
|
|
45
|
+
**New public surface**
|
|
46
|
+
- `resolveMdxAnnotations({ mdxPath, screenId, dims, cwd? })` —
|
|
47
|
+
pure-data resolver used by both the Playwright hook and the
|
|
48
|
+
Astro Image Service (Phase 4 of the relayer plan switches
|
|
49
|
+
product-docs-astro's `renderAnnotatedScreen` to consume it).
|
|
50
|
+
- `parseSnapshotBoxes(yaml)` / `buildBadgeAnnotations(overlays,
|
|
51
|
+
boxed, dims)` — exposed for callers that want to drive
|
|
52
|
+
annotation production from custom snapshot pipelines.
|
|
53
|
+
- `svgFromBboxAnnotations(annotations)` /
|
|
54
|
+
`svgFromBadges(badges)` / `emptyAnnotationsSvg()` — single-root
|
|
55
|
+
`<svg>` wrappers that the headless annotator's `annotationsSvg`
|
|
56
|
+
input expects.
|
|
57
|
+
- `BoxedEntry` type — parsed aria-snapshot YAML entry with
|
|
58
|
+
`[ref=…]` + `[box=…]` markers.
|
|
59
|
+
|
|
60
|
+
**Compatibility**
|
|
61
|
+
- Module augmentation extends annot-playwright's
|
|
62
|
+
`AnnotScreenshotOptions` with the `mdx?: { id, path }` field
|
|
63
|
+
via `declare module "@ingcreators/annot-playwright"`. Imports
|
|
64
|
+
from `@ingcreators/annot-product-docs/fixture` or the package
|
|
65
|
+
root register the resolver via side-effect.
|
|
66
|
+
- The existing
|
|
67
|
+
`@ingcreators/annot-product-docs-astro/playwright` subpath
|
|
68
|
+
continues to work unchanged (it ships its own duplicate
|
|
69
|
+
augmentation + patch — Phase 4 of the plan converts that subpath
|
|
70
|
+
into a deprecated re-export pointing here).
|
|
71
|
+
- `packages/docs-site/tests/docs/annot-app.spec.ts` — the
|
|
72
|
+
dogfood tour spec swaps `import { test } from
|
|
73
|
+
"@ingcreators/annot-product-docs-astro/playwright"` to
|
|
74
|
+
`"@ingcreators/annot-product-docs"`. PNG output stays
|
|
75
|
+
byte-identical (same patch → same composer → same encoder).
|
|
76
|
+
|
|
77
|
+
### Patch Changes
|
|
78
|
+
|
|
79
|
+
- 96e7625: **`screen` fixture → `productDocs`, `capture` method → `sync`** —
|
|
80
|
+
Phase 3 of `docs/plans/playwright-screenshot-fixture-relayer.md`.
|
|
81
|
+
The fixture's old name reads like a Playwright built-in and
|
|
82
|
+
collides with `@testing-library/react`'s `screen`; `capture`
|
|
83
|
+
implies a screenshot but the method actually synchronizes MDX
|
|
84
|
+
comment blocks. The rename aligns with the established
|
|
85
|
+
`annotator` convention from `@ingcreators/annot-annotator`.
|
|
86
|
+
|
|
87
|
+
```ts
|
|
88
|
+
// Was:
|
|
89
|
+
test("login", async ({ page, screen }) => {
|
|
90
|
+
await screen.capture({ id: "login", mdxPath: "..." });
|
|
91
|
+
});
|
|
92
|
+
|
|
93
|
+
// Now:
|
|
94
|
+
test("login", async ({ page, productDocs }) => {
|
|
95
|
+
await productDocs.sync({ id: "login", mdxPath: "..." });
|
|
96
|
+
});
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
**Back-compat — old names keep working**:
|
|
100
|
+
- Fixture: `test.extend({ screen })` is preserved alongside
|
|
101
|
+
`productDocs`. Both expose the same `.sync()` method (the
|
|
102
|
+
deprecated `.capture()` method on `screen` aliases `.sync()`).
|
|
103
|
+
- Standalone helper: `captureScreen` re-exports the new
|
|
104
|
+
`syncProductDocs` implementation. `captureScreen ===
|
|
105
|
+
syncProductDocs` is true — reference-equal so callers that
|
|
106
|
+
identity-check the function across the rename boundary keep
|
|
107
|
+
working.
|
|
108
|
+
- Types: `Screen` aliases `ProductDocs`, `ScreenCaptureOptions`
|
|
109
|
+
aliases `ProductDocsSyncOptions`. Both flagged
|
|
110
|
+
`@deprecated` in JSDoc; deletion is scheduled for the
|
|
111
|
+
deprecation window noted in
|
|
112
|
+
`living-spec-authoring-roadmap.md` OQ-08.
|
|
113
|
+
|
|
114
|
+
**In-tree consumers migrated**:
|
|
115
|
+
- `packages/product-docs/src/cli.ts` — `annot docs sync` /
|
|
116
|
+
`annot docs lint --fix` call `syncProductDocs` directly. The
|
|
117
|
+
`init` scaffold's sample tour uses `productDocs.sync(...)`.
|
|
118
|
+
- `packages/product-docs-astro/src/playwright/fixture.ts` —
|
|
119
|
+
imports `syncProductDocs` (was `captureScreen`).
|
|
120
|
+
- `packages/docs-site/src/content/docs/product-docs/playwright-tour.mdx`
|
|
121
|
+
- `getting-started/product-docs.mdx` +
|
|
122
|
+
`api/product-docs.mdx` + `concepts.mdx` +
|
|
123
|
+
`recipes/living-product-docs.mdx` — all example snippets
|
|
124
|
+
updated to the new names.
|
|
125
|
+
- `packages/product-docs/README.md` — quickstart updated.
|
|
126
|
+
|
|
127
|
+
**Test of the back-compat surface** — a new
|
|
128
|
+
`fixture.test.ts` case asserts `captureScreen === syncProductDocs`
|
|
129
|
+
so the alias contract is enforced by CI; any future refactor
|
|
130
|
+
that breaks the reference equality fails the build.
|
|
131
|
+
|
|
132
|
+
- 85d40e6: **Docs + CLAUDE.md + plan archive** — Phase 5 (final) of
|
|
133
|
+
`docs/plans/_done/playwright-screenshot-fixture-relayer.md`.
|
|
134
|
+
Refreshes the doc surfaces, the operational CLAUDE.md notes,
|
|
135
|
+
and archives the relayer plan into `_done/`.
|
|
136
|
+
|
|
137
|
+
## Doc surface updates
|
|
138
|
+
- `packages/docs-site/src/content/docs/product-docs/playwright-fixture.mdx`
|
|
139
|
+
— recommended import paths updated; new "Choosing your import"
|
|
140
|
+
section covers the `@ingcreators/annot-product-docs` (MDX)
|
|
141
|
+
vs. `@ingcreators/annot-playwright` (no MDX) split; companion
|
|
142
|
+
helpers section now imports from the canonical homes; codegen
|
|
143
|
+
workflow example swapped to `@ingcreators/annot-product-docs`.
|
|
144
|
+
- `packages/docs-site/src/content/docs/api/create-annotator.mdx`
|
|
145
|
+
— "From a Playwright test" example imports from the canonical
|
|
146
|
+
home; mentions the no-MDX alternative.
|
|
147
|
+
- `packages/playwright/README.md` — adds the
|
|
148
|
+
`page.screenshot({ annot: { … } })` (recommended) section
|
|
149
|
+
above the existing `annotator.annotateScreenshot(...)` flow;
|
|
150
|
+
documents the `annotSourceResolvers` extension hook + the
|
|
151
|
+
coordinate-rebase helpers.
|
|
152
|
+
- `packages/product-docs/README.md` — adds a `page.screenshot({
|
|
153
|
+
annot })` Playwright fixture section explaining the
|
|
154
|
+
productDocs.sync + MDX-resolver bundle.
|
|
155
|
+
- `packages/product-docs-astro/README.md` — replaces the
|
|
156
|
+
Playwright fixture section with a Migration note pointing at
|
|
157
|
+
the canonical homes; documents the `0.5.0` removal target.
|
|
158
|
+
|
|
159
|
+
## CLAUDE.md monorepo layout
|
|
160
|
+
- `playwright/` entry now describes the canonical
|
|
161
|
+
`page.screenshot({ annot })` patch + `annotSourceResolvers`
|
|
162
|
+
extension hook. Version bumped to 0.4.0.
|
|
163
|
+
- `product-docs/` entry mentions the `productDocs` fixture
|
|
164
|
+
rename + the MDX-aware resolver registration via the hook
|
|
165
|
+
registry. Version bumped to 0.3.0.
|
|
166
|
+
- `product-docs-astro/` entry calls out the deprecated
|
|
167
|
+
`/playwright` re-export shim + 0.5.0 removal target.
|
|
168
|
+
`@playwright/test` no longer a peer dep. Version bumped to
|
|
169
|
+
0.3.0.
|
|
170
|
+
|
|
171
|
+
## Plan archive
|
|
172
|
+
- `docs/plans/playwright-screenshot-fixture-relayer.md` →
|
|
173
|
+
`docs/plans/_done/playwright-screenshot-fixture-relayer.md`.
|
|
174
|
+
Status header switched to `Done` with the four landing PRs
|
|
175
|
+
enumerated. Internal `./_done/...` link paths updated to
|
|
176
|
+
`./...` (the plan is itself inside `_done/` now).
|
|
177
|
+
- `docs/plans/README.md` — removed the active entry, added a
|
|
178
|
+
"Recently landed plans" row pointing at the archived plan
|
|
179
|
+
with a multi-phase summary covering all four landing PRs.
|
|
180
|
+
- `docs/plans/living-spec-authoring-roadmap.md` — three link
|
|
181
|
+
references updated to point at the archived path; the "How
|
|
182
|
+
this relates" line switched from "Already Draft" to "Landed
|
|
183
|
+
2026-05-22 (PRs #962 / #963 / #964 / #966)".
|
|
184
|
+
|
|
185
|
+
No source code changes; verified via `pnpm -r typecheck`,
|
|
186
|
+
`pnpm test`, `pnpm lint` regardless to confirm the doc/comment
|
|
187
|
+
edits parse cleanly.
|
|
188
|
+
|
|
189
|
+
- Updated dependencies [f979374]
|
|
190
|
+
- Updated dependencies [85d40e6]
|
|
191
|
+
- @ingcreators/annot-playwright@0.4.0
|
|
192
|
+
|
|
3
193
|
## 0.2.0
|
|
4
194
|
|
|
5
195
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -78,15 +78,50 @@ don't. The resolver re-finds each element on every run.
|
|
|
78
78
|
// tests/docs/auth.spec.ts
|
|
79
79
|
import { test } from "@ingcreators/annot-product-docs";
|
|
80
80
|
|
|
81
|
-
test("login flow", async ({ page,
|
|
81
|
+
test("login flow", async ({ page, productDocs }) => {
|
|
82
82
|
await page.goto("/login");
|
|
83
|
-
await
|
|
83
|
+
await productDocs.sync({
|
|
84
84
|
id: "login",
|
|
85
85
|
mdxPath: "docs/books/example/SC-001-login.mdx",
|
|
86
86
|
});
|
|
87
87
|
});
|
|
88
88
|
```
|
|
89
89
|
|
|
90
|
+
## `page.screenshot({ annot })` Playwright fixture
|
|
91
|
+
|
|
92
|
+
The package's `test` extends
|
|
93
|
+
[`@ingcreators/annot-playwright`](../playwright)'s test with the
|
|
94
|
+
`productDocs.sync(...)` fixture above AND registers an MDX-aware
|
|
95
|
+
resolver into the `annotSourceResolvers` registry. Pass
|
|
96
|
+
`annot: { mdx }` on `page.screenshot()` to bundle the
|
|
97
|
+
refresh-snapshot + take-screenshot + bake-overlays + write-PNG
|
|
98
|
+
sequence into one call — the same `<Screen id>` block in the
|
|
99
|
+
target MDX gets re-synced before the screenshot fires, and the
|
|
100
|
+
output PNG is re-editable in Annot Cloud:
|
|
101
|
+
|
|
102
|
+
```ts
|
|
103
|
+
test("app overview", async ({ page }) => {
|
|
104
|
+
await page.goto("https://annot.work/app/");
|
|
105
|
+
await page.screenshot({
|
|
106
|
+
path: "public/app/shots/app-overview.png",
|
|
107
|
+
annot: {
|
|
108
|
+
mdx: { id: "app-overview", path: "src/content/docs/app/index.mdx" },
|
|
109
|
+
tags: { source: "docs-tour", capturedAt: new Date().toISOString() },
|
|
110
|
+
},
|
|
111
|
+
});
|
|
112
|
+
});
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Calls without `annot` (or with `annot: true` / `{}`) fall
|
|
116
|
+
through to vanilla Playwright byte-for-byte — codegen-emitted
|
|
117
|
+
calls keep working unedited. The generic `annot.overlays` /
|
|
118
|
+
`annot.tags` / `annot.editable` fields are handled by
|
|
119
|
+
annot-playwright; this package contributes the MDX-aware
|
|
120
|
+
`annot.mdx` field on top via the hook registry. See
|
|
121
|
+
[`annot.work/docs/product-docs/playwright-fixture/`](https://annot.work/docs/product-docs/playwright-fixture/)
|
|
122
|
+
for the compositional vocabulary, locator screenshot semantics,
|
|
123
|
+
and the codegen→hand-edit workflow.
|
|
124
|
+
|
|
90
125
|
## CLI
|
|
91
126
|
|
|
92
127
|
```sh
|
package/dist/config.d.ts
CHANGED
|
@@ -12,28 +12,28 @@ export declare const annotFrontmatterSchema: z.ZodObject<{
|
|
|
12
12
|
role: z.ZodOptional<z.ZodEnum<["cover", "history", "list", "screen", "reference"]>>;
|
|
13
13
|
order: z.ZodOptional<z.ZodNumber>;
|
|
14
14
|
}, "strict", z.ZodTypeAny, {
|
|
15
|
-
role?: "cover" | "history" | "list" | "screen" | "reference" | undefined;
|
|
16
15
|
book?: string | undefined;
|
|
17
16
|
sheet?: string | undefined;
|
|
18
17
|
sheets?: Record<string, string> | undefined;
|
|
18
|
+
role?: "screen" | "cover" | "history" | "list" | "reference" | undefined;
|
|
19
19
|
order?: number | undefined;
|
|
20
20
|
}, {
|
|
21
|
-
role?: "cover" | "history" | "list" | "screen" | "reference" | undefined;
|
|
22
21
|
book?: string | undefined;
|
|
23
22
|
sheet?: string | undefined;
|
|
24
23
|
sheets?: Record<string, string> | undefined;
|
|
24
|
+
role?: "screen" | "cover" | "history" | "list" | "reference" | undefined;
|
|
25
25
|
order?: number | undefined;
|
|
26
26
|
}>, {
|
|
27
|
-
role?: "cover" | "history" | "list" | "screen" | "reference" | undefined;
|
|
28
27
|
book?: string | undefined;
|
|
29
28
|
sheet?: string | undefined;
|
|
30
29
|
sheets?: Record<string, string> | undefined;
|
|
30
|
+
role?: "screen" | "cover" | "history" | "list" | "reference" | undefined;
|
|
31
31
|
order?: number | undefined;
|
|
32
32
|
}, {
|
|
33
|
-
role?: "cover" | "history" | "list" | "screen" | "reference" | undefined;
|
|
34
33
|
book?: string | undefined;
|
|
35
34
|
sheet?: string | undefined;
|
|
36
35
|
sheets?: Record<string, string> | undefined;
|
|
36
|
+
role?: "screen" | "cover" | "history" | "list" | "reference" | undefined;
|
|
37
37
|
order?: number | undefined;
|
|
38
38
|
}>>;
|
|
39
39
|
}, "strict", z.ZodTypeAny, {
|
|
@@ -42,10 +42,10 @@ export declare const annotFrontmatterSchema: z.ZodObject<{
|
|
|
42
42
|
purpose?: string | undefined;
|
|
43
43
|
meta?: Record<string, unknown> | undefined;
|
|
44
44
|
xlsx?: {
|
|
45
|
-
role?: "cover" | "history" | "list" | "screen" | "reference" | undefined;
|
|
46
45
|
book?: string | undefined;
|
|
47
46
|
sheet?: string | undefined;
|
|
48
47
|
sheets?: Record<string, string> | undefined;
|
|
48
|
+
role?: "screen" | "cover" | "history" | "list" | "reference" | undefined;
|
|
49
49
|
order?: number | undefined;
|
|
50
50
|
} | undefined;
|
|
51
51
|
}, {
|
|
@@ -54,10 +54,10 @@ export declare const annotFrontmatterSchema: z.ZodObject<{
|
|
|
54
54
|
purpose?: string | undefined;
|
|
55
55
|
meta?: Record<string, unknown> | undefined;
|
|
56
56
|
xlsx?: {
|
|
57
|
-
role?: "cover" | "history" | "list" | "screen" | "reference" | undefined;
|
|
58
57
|
book?: string | undefined;
|
|
59
58
|
sheet?: string | undefined;
|
|
60
59
|
sheets?: Record<string, string> | undefined;
|
|
60
|
+
role?: "screen" | "cover" | "history" | "list" | "reference" | undefined;
|
|
61
61
|
order?: number | undefined;
|
|
62
62
|
} | undefined;
|
|
63
63
|
}>;
|
|
@@ -74,34 +74,34 @@ export declare const annotDocsConfigSchema: z.ZodObject<{
|
|
|
74
74
|
screen: z.ZodOptional<z.ZodString>;
|
|
75
75
|
reference: z.ZodOptional<z.ZodString>;
|
|
76
76
|
}, "strict", z.ZodTypeAny, {
|
|
77
|
+
screen?: string | undefined;
|
|
77
78
|
cover?: string | undefined;
|
|
78
79
|
history?: string | undefined;
|
|
79
80
|
list?: string | undefined;
|
|
80
|
-
screen?: string | undefined;
|
|
81
81
|
reference?: string | undefined;
|
|
82
82
|
}, {
|
|
83
|
+
screen?: string | undefined;
|
|
83
84
|
cover?: string | undefined;
|
|
84
85
|
history?: string | undefined;
|
|
85
86
|
list?: string | undefined;
|
|
86
|
-
screen?: string | undefined;
|
|
87
87
|
reference?: string | undefined;
|
|
88
88
|
}>>;
|
|
89
89
|
}, "strict", z.ZodTypeAny, {
|
|
90
90
|
template?: string | undefined;
|
|
91
91
|
templateSheets?: {
|
|
92
|
+
screen?: string | undefined;
|
|
92
93
|
cover?: string | undefined;
|
|
93
94
|
history?: string | undefined;
|
|
94
95
|
list?: string | undefined;
|
|
95
|
-
screen?: string | undefined;
|
|
96
96
|
reference?: string | undefined;
|
|
97
97
|
} | undefined;
|
|
98
98
|
}, {
|
|
99
99
|
template?: string | undefined;
|
|
100
100
|
templateSheets?: {
|
|
101
|
+
screen?: string | undefined;
|
|
101
102
|
cover?: string | undefined;
|
|
102
103
|
history?: string | undefined;
|
|
103
104
|
list?: string | undefined;
|
|
104
|
-
screen?: string | undefined;
|
|
105
105
|
reference?: string | undefined;
|
|
106
106
|
} | undefined;
|
|
107
107
|
}>>>;
|
|
@@ -110,10 +110,10 @@ export declare const annotDocsConfigSchema: z.ZodObject<{
|
|
|
110
110
|
books?: Record<string, {
|
|
111
111
|
template?: string | undefined;
|
|
112
112
|
templateSheets?: {
|
|
113
|
+
screen?: string | undefined;
|
|
113
114
|
cover?: string | undefined;
|
|
114
115
|
history?: string | undefined;
|
|
115
116
|
list?: string | undefined;
|
|
116
|
-
screen?: string | undefined;
|
|
117
117
|
reference?: string | undefined;
|
|
118
118
|
} | undefined;
|
|
119
119
|
}> | undefined;
|
|
@@ -122,10 +122,10 @@ export declare const annotDocsConfigSchema: z.ZodObject<{
|
|
|
122
122
|
books?: Record<string, {
|
|
123
123
|
template?: string | undefined;
|
|
124
124
|
templateSheets?: {
|
|
125
|
+
screen?: string | undefined;
|
|
125
126
|
cover?: string | undefined;
|
|
126
127
|
history?: string | undefined;
|
|
127
128
|
list?: string | undefined;
|
|
128
|
-
screen?: string | undefined;
|
|
129
129
|
reference?: string | undefined;
|
|
130
130
|
} | undefined;
|
|
131
131
|
}> | undefined;
|
|
@@ -137,10 +137,10 @@ export declare const annotDocsConfigSchema: z.ZodObject<{
|
|
|
137
137
|
books?: Record<string, {
|
|
138
138
|
template?: string | undefined;
|
|
139
139
|
templateSheets?: {
|
|
140
|
+
screen?: string | undefined;
|
|
140
141
|
cover?: string | undefined;
|
|
141
142
|
history?: string | undefined;
|
|
142
143
|
list?: string | undefined;
|
|
143
|
-
screen?: string | undefined;
|
|
144
144
|
reference?: string | undefined;
|
|
145
145
|
} | undefined;
|
|
146
146
|
}> | undefined;
|
|
@@ -152,10 +152,10 @@ export declare const annotDocsConfigSchema: z.ZodObject<{
|
|
|
152
152
|
books?: Record<string, {
|
|
153
153
|
template?: string | undefined;
|
|
154
154
|
templateSheets?: {
|
|
155
|
+
screen?: string | undefined;
|
|
155
156
|
cover?: string | undefined;
|
|
156
157
|
history?: string | undefined;
|
|
157
158
|
list?: string | undefined;
|
|
158
|
-
screen?: string | undefined;
|
|
159
159
|
reference?: string | undefined;
|
|
160
160
|
} | undefined;
|
|
161
161
|
}> | undefined;
|
package/dist/fixture.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { Locator, Page } from '@playwright/test';
|
|
2
2
|
import { OverlaySpec } from './types.js';
|
|
3
|
-
export interface
|
|
3
|
+
export interface ProductDocsSyncOptions {
|
|
4
4
|
/** Must match a `<Screen id="...">` JSX block in the MDX file. */
|
|
5
5
|
id: string;
|
|
6
6
|
/** Absolute or cwd-relative path to the `.mdx` file. */
|
|
@@ -18,9 +18,25 @@ export interface ScreenCaptureOptions {
|
|
|
18
18
|
*/
|
|
19
19
|
attributeWhitelist?: readonly string[];
|
|
20
20
|
}
|
|
21
|
-
|
|
22
|
-
|
|
21
|
+
/**
|
|
22
|
+
* @deprecated Renamed to {@link ProductDocsSyncOptions} in Phase 3
|
|
23
|
+
* of `docs/plans/playwright-screenshot-fixture-relayer.md` for
|
|
24
|
+
* naming clarity (the helper synchronizes the MDX comment blocks
|
|
25
|
+
* with the live UI — it does not take a screenshot). The old name
|
|
26
|
+
* keeps working but new code should use `ProductDocsSyncOptions`.
|
|
27
|
+
*/
|
|
28
|
+
export type ScreenCaptureOptions = ProductDocsSyncOptions;
|
|
29
|
+
export interface ProductDocs {
|
|
30
|
+
sync(opts: ProductDocsSyncOptions): Promise<void>;
|
|
23
31
|
}
|
|
32
|
+
/**
|
|
33
|
+
* @deprecated Renamed to {@link ProductDocs} in Phase 3 of
|
|
34
|
+
* `docs/plans/playwright-screenshot-fixture-relayer.md`. The old
|
|
35
|
+
* `Screen` name is ambiguous (collides with `@testing-library/react`'s
|
|
36
|
+
* `screen` + reads like a Playwright built-in). New code should
|
|
37
|
+
* use `ProductDocs`.
|
|
38
|
+
*/
|
|
39
|
+
export type Screen = ProductDocs;
|
|
24
40
|
/**
|
|
25
41
|
* HTML attributes captured into the `annot:attributes` block by
|
|
26
42
|
* default. Focused on form-control + accessibility shape — the
|
|
@@ -30,41 +46,55 @@ export interface Screen {
|
|
|
30
46
|
*/
|
|
31
47
|
export declare const DEFAULT_ATTR_WHITELIST: readonly string[];
|
|
32
48
|
/**
|
|
33
|
-
* `test = annotatorTest.extend({
|
|
34
|
-
* `@playwright/test`'s `test` plus a `
|
|
35
|
-
* docs flow. Tour files (`tests/docs/*.spec.ts`) import this
|
|
49
|
+
* `test = annotatorTest.extend({ productDocs })` — drop-in for
|
|
50
|
+
* `@playwright/test`'s `test` plus a `productDocs` fixture for
|
|
51
|
+
* the docs flow. Tour files (`tests/docs/*.spec.ts`) import this
|
|
36
52
|
* `test` instead of `@playwright/test`:
|
|
37
53
|
*
|
|
38
54
|
* ```ts
|
|
39
55
|
* import { test } from "@ingcreators/annot-product-docs";
|
|
40
56
|
*
|
|
41
|
-
* test("login flow", async ({ page,
|
|
57
|
+
* test("login flow", async ({ page, productDocs }) => {
|
|
42
58
|
* await page.goto("/login");
|
|
43
|
-
* await
|
|
59
|
+
* await productDocs.sync({
|
|
44
60
|
* id: "login",
|
|
45
61
|
* mdxPath: "docs/books/screen-spec/screens/SC-001-login.mdx",
|
|
46
62
|
* });
|
|
47
63
|
* });
|
|
48
64
|
* ```
|
|
65
|
+
*
|
|
66
|
+
* For back-compat the same fixture is also exposed as `screen`
|
|
67
|
+
* with a `.capture()` method (deprecated since Phase 3 of the
|
|
68
|
+
* relayer plan; remove after the documented deprecation window).
|
|
49
69
|
*/
|
|
50
70
|
export declare const test: import('@playwright/test').TestType<import('@playwright/test').PlaywrightTestArgs & import('@playwright/test').PlaywrightTestOptions & {
|
|
51
71
|
annotator: import('@ingcreators/annot-playwright').PlaywrightAnnotator;
|
|
52
72
|
} & {
|
|
53
|
-
|
|
73
|
+
productDocs: ProductDocs;
|
|
74
|
+
screen: ProductDocs;
|
|
54
75
|
}, import('@playwright/test').PlaywrightWorkerArgs & import('@playwright/test').PlaywrightWorkerOptions>;
|
|
55
76
|
/**
|
|
56
|
-
* Standalone
|
|
57
|
-
* `
|
|
58
|
-
* so callers who build their own Playwright fixture
|
|
59
|
-
* composing additional fixtures on top) can still drive
|
|
60
|
-
* docs-sync flow.
|
|
77
|
+
* Standalone sync helper — same behaviour as
|
|
78
|
+
* `productDocs.sync(...)` but takes the `Page` directly.
|
|
79
|
+
* Exported so callers who build their own Playwright fixture
|
|
80
|
+
* (e.g. composing additional fixtures on top) can still drive
|
|
81
|
+
* the docs-sync flow.
|
|
61
82
|
*
|
|
62
83
|
* Idempotent: if `mdxPath` already has `annot:snapshot` /
|
|
63
84
|
* `annot:attributes` blocks, they're replaced in place; if not,
|
|
64
85
|
* they're appended. Files without `annot:` frontmatter throw —
|
|
65
86
|
* the fixture refuses to touch non-annot MDX.
|
|
66
87
|
*/
|
|
67
|
-
export declare function
|
|
88
|
+
export declare function syncProductDocs(page: Page, opts: ProductDocsSyncOptions): Promise<void>;
|
|
89
|
+
/**
|
|
90
|
+
* @deprecated Renamed to {@link syncProductDocs} in Phase 3 of
|
|
91
|
+
* `docs/plans/playwright-screenshot-fixture-relayer.md`. The old
|
|
92
|
+
* name reads as if a screenshot is captured; the function
|
|
93
|
+
* actually synchronizes MDX comment blocks. The deprecated alias
|
|
94
|
+
* is a reference-equality re-export of the new implementation so
|
|
95
|
+
* `===` checks across the rename boundary keep working.
|
|
96
|
+
*/
|
|
97
|
+
export declare const captureScreen: typeof syncProductDocs;
|
|
68
98
|
/**
|
|
69
99
|
* Walk the overlays in a `<Screen>`, resolve each one's `match`
|
|
70
100
|
* against the live page, and emit a YAML block of the form:
|
package/dist/index.d.ts
CHANGED
|
@@ -2,10 +2,12 @@ export { filterAnnotMdxFiles, main, walkMdx, } from './cli.js';
|
|
|
2
2
|
export { annotDocsConfigSchema, annotFrontmatterSchema, defineConfig, isScreenRole, } from './config.js';
|
|
3
3
|
export type { DetectDriftOptions, DriftFinding, DriftKind, DriftSeverity, } from './drift.js';
|
|
4
4
|
export { detectDrift, detectDriftFromYaml, isLintableScreen, lintableScreens, summariseDrift, } from './drift.js';
|
|
5
|
-
export type { Screen, ScreenCaptureOptions } from './fixture.js';
|
|
6
|
-
export { captureScreen, collectAttributesYaml, DEFAULT_ATTR_WHITELIST, test, } from './fixture.js';
|
|
5
|
+
export type { ProductDocs, ProductDocsSyncOptions, Screen, ScreenCaptureOptions, } from './fixture.js';
|
|
6
|
+
export { captureScreen, collectAttributesYaml, DEFAULT_ATTR_WHITELIST, syncProductDocs, test, } from './fixture.js';
|
|
7
7
|
export type { ParseMdxOptions } from './mdx.js';
|
|
8
8
|
export { parseMdx, parseMdxFile, updateCommentBlocks } from './mdx.js';
|
|
9
|
+
export type { BoxedEntry } from './mdx-annotations.js';
|
|
10
|
+
export { buildBadgeAnnotations, emptyAnnotationsSvg, parseSnapshotBoxes, resolveMdxAnnotations, svgFromBadges, svgFromBboxAnnotations, } from './mdx-annotations.js';
|
|
9
11
|
export type { ResolveFailureKind, ResolveResult, SnapshotEntry, } from './resolver.js';
|
|
10
12
|
export { parseSnapshot, resolveMatch, resolveOverlays, } from './resolver.js';
|
|
11
13
|
export type { AnnotCommentBlocks, AnnotFrontmatter, AnnotFrontmatterRole, AnnotMeta, AnnotXlsxConfig, HistoryEntrySpec, MatchKey, OverlayIntent, OverlaySpec, ParsedMdx, ScreenListSpec, ScreenSpec, TransitionSpec, } from './types.js';
|