@ingcreators/annot-product-docs 0.2.0 → 0.4.0

package/dist/fixture.d.ts

@@ -1,6 +1,6 @@
 import { Locator, Page } from '@playwright/test';
 import { OverlaySpec } from './types.js';
-export interface ScreenCaptureOptions {
+export interface ProductDocsSyncOptions {
     /** Must match a `<Screen id="...">` JSX block in the MDX file. */
     id: string;
     /** Absolute or cwd-relative path to the `.mdx` file. */
@@ -18,9 +18,25 @@ export interface ScreenCaptureOptions {
      */
     attributeWhitelist?: readonly string[];
 }
-export interface Screen {
-    capture(opts: ScreenCaptureOptions): Promise<void>;
+/**
+ * @deprecated Renamed to {@link ProductDocsSyncOptions} in Phase 3
+ * of `docs/plans/playwright-screenshot-fixture-relayer.md` for
+ * naming clarity (the helper synchronizes the MDX comment blocks
+ * with the live UI — it does not take a screenshot). The old name
+ * keeps working but new code should use `ProductDocsSyncOptions`.
+ */
+export type ScreenCaptureOptions = ProductDocsSyncOptions;
+export interface ProductDocs {
+    sync(opts: ProductDocsSyncOptions): Promise<void>;
 }
+/**
+ * @deprecated Renamed to {@link ProductDocs} in Phase 3 of
+ * `docs/plans/playwright-screenshot-fixture-relayer.md`. The old
+ * `Screen` name is ambiguous (collides with `@testing-library/react`'s
+ * `screen` + reads like a Playwright built-in). New code should
+ * use `ProductDocs`.
+ */
+export type Screen = ProductDocs;
 /**
  * HTML attributes captured into the `annot:attributes` block by
  * default. Focused on form-control + accessibility shape — the
@@ -30,41 +46,55 @@ export interface Screen {
  */
 export declare const DEFAULT_ATTR_WHITELIST: readonly string[];
 /**
- * `test = annotatorTest.extend({ screen })` — drop-in for
- * `@playwright/test`'s `test` plus a `screen` fixture for the
- * docs flow. Tour files (`tests/docs/*.spec.ts`) import this
+ * `test = annotatorTest.extend({ productDocs })` — drop-in for
+ * `@playwright/test`'s `test` plus a `productDocs` fixture for
+ * the docs flow. Tour files (`tests/docs/*.spec.ts`) import this
  * `test` instead of `@playwright/test`:
  *
  * ```ts
  * import { test } from "@ingcreators/annot-product-docs";
  *
- * test("login flow", async ({ page, screen }) => {
+ * test("login flow", async ({ page, productDocs }) => {
  *   await page.goto("/login");
- *   await screen.capture({
+ *   await productDocs.sync({
  *     id: "login",
  *     mdxPath: "docs/books/screen-spec/screens/SC-001-login.mdx",
  *   });
  * });
  * ```
+ *
+ * For back-compat the same fixture is also exposed as `screen`
+ * with a `.capture()` method (deprecated since Phase 3 of the
+ * relayer plan; remove after the documented deprecation window).
  */
 export declare const test: import('@playwright/test').TestType<import('@playwright/test').PlaywrightTestArgs & import('@playwright/test').PlaywrightTestOptions & {
     annotator: import('@ingcreators/annot-playwright').PlaywrightAnnotator;
 } & {
-    screen: Screen;
+    productDocs: ProductDocs;
+    screen: ProductDocs;
 }, import('@playwright/test').PlaywrightWorkerArgs & import('@playwright/test').PlaywrightWorkerOptions>;
 /**
- * Standalone capture helper — same behaviour as
- * `screen.capture(...)` but takes the `Page` directly. Exported
- * so callers who build their own Playwright fixture (e.g.
- * composing additional fixtures on top) can still drive the
- * docs-sync flow.
+ * Standalone sync helper — same behaviour as
+ * `productDocs.sync(...)` but takes the `Page` directly.
+ * Exported so callers who build their own Playwright fixture
+ * (e.g. composing additional fixtures on top) can still drive
+ * the docs-sync flow.
  *
  * Idempotent: if `mdxPath` already has `annot:snapshot` /
  * `annot:attributes` blocks, they're replaced in place; if not,
  * they're appended. Files without `annot:` frontmatter throw —
  * the fixture refuses to touch non-annot MDX.
  */
-export declare function captureScreen(page: Page, opts: ScreenCaptureOptions): Promise<void>;
+export declare function syncProductDocs(page: Page, opts: ProductDocsSyncOptions): Promise<void>;
+/**
+ * @deprecated Renamed to {@link syncProductDocs} in Phase 3 of
+ * `docs/plans/playwright-screenshot-fixture-relayer.md`. The old
+ * name reads as if a screenshot is captured; the function
+ * actually synchronizes MDX comment blocks. The deprecated alias
+ * is a reference-equality re-export of the new implementation so
+ * `===` checks across the rename boundary keep working.
+ */
+export declare const captureScreen: typeof syncProductDocs;
 /**
  * Walk the overlays in a `<Screen>`, resolve each one's `match`
  * against the live page, and emit a YAML block of the form:

package/dist/index.d.ts

@@ -1,12 +1,20 @@
+export type { AnnotationBBox, AnnotationKind, AnnotationPoint, AnnotationSpec, AnnotationStyleFields, AnnotationsFile, ArrowAnnotation, ArrowEndpoint, CalloutAnnotation, CalloutTarget, CircleAnnotation, FocusMaskAnnotation, FocusMaskCutout, FreehandAnnotation, OverlayEntry, RectAnnotation, RedactAnnotation, RedactAnnotationStyle, TextAnchorPosition, TextAnnotation, } from './annotations-yaml.js';
+export { ANNOTATION_KINDS, ANNOTATIONS_YAML_VERSION, AnnotationsYamlError, parseAnnotationsYaml, serializeAnnotationsYaml, } from './annotations-yaml.js';
 export { filterAnnotMdxFiles, main, walkMdx, } from './cli.js';
 export { annotDocsConfigSchema, annotFrontmatterSchema, defineConfig, isScreenRole, } from './config.js';
+export type { LegacyOverlayUsage } from './deprecation.js';
+export { _resetLegacyOverlayDedupForTests, formatLegacyOverlayWarning, warnLegacyOverlay, } from './deprecation.js';
 export type { DetectDriftOptions, DriftFinding, DriftKind, DriftSeverity, } from './drift.js';
-export { detectDrift, detectDriftFromYaml, isLintableScreen, lintableScreens, summariseDrift, } from './drift.js';
-export type { Screen, ScreenCaptureOptions } from './fixture.js';
-export { captureScreen, collectAttributesYaml, DEFAULT_ATTR_WHITELIST, test, } from './fixture.js';
+export { collectMatchKeysFromAnnotation, detectDrift, detectDriftFromElementTree, detectDriftFromYaml, elementTreeToSnapshotEntries, isLintableScreen, lintableScreens, summariseDrift, } from './drift.js';
+export type { ProductDocs, ProductDocsSyncOptions, Screen, ScreenCaptureOptions, } from './fixture.js';
+export { captureScreen, collectAttributesYaml, DEFAULT_ATTR_WHITELIST, syncProductDocs, test, } from './fixture.js';
 export type { ParseMdxOptions } from './mdx.js';
 export { parseMdx, parseMdxFile, updateCommentBlocks } from './mdx.js';
+export type { BoxedEntry } from './mdx-annotations.js';
+export { buildBadgeAnnotations, buildBadgeAnnotationsFromYaml, buildRasterRedactRegionsFromYaml, buildShapeAnnotationsFromYaml, elementTreeToBoxedEntries, emptyAnnotationsSvg, parseSnapshotBoxes, resolveMdxAnnotations, svgFromBadges, svgFromBboxAnnotations, } from './mdx-annotations.js';
+export type { MigrateOverlaysOptions, OverlayMigrationFileResult, ScreenOverlayMigrationResult, } from './migrate-overlays-to-annotations.js';
+export { buildAnnotationsFile, migrateOverlaysToAnnotationsFile, } from './migrate-overlays-to-annotations.js';
 export type { ResolveFailureKind, ResolveResult, SnapshotEntry, } from './resolver.js';
 export { parseSnapshot, resolveMatch, resolveOverlays, } from './resolver.js';
-export type { AnnotCommentBlocks, AnnotFrontmatter, AnnotFrontmatterRole, AnnotMeta, AnnotXlsxConfig, HistoryEntrySpec, MatchKey, OverlayIntent, OverlaySpec, ParsedMdx, ScreenListSpec, ScreenSpec, TransitionSpec, } from './types.js';
-export type { AnnotDocsConfig, BookConfig } from './types-config.js';
+export type { AnnotCalloutSpec, AnnotCommentBlocks, AnnotFrontmatter, AnnotFrontmatterRole, AnnotMeta, AnnotXlsxConfig, HistoryEntrySpec, MatchKey, OverlayIntent, OverlaySpec, ParsedMdx, ScreenListSpec, ScreenSpec, TransitionSpec, } from './types.js';
+export type { AnnotDocsConfig, AnnotEditorConfig, BookConfig } from './types-config.js';