From 4d5456ac4a094debf731b9b6ffa7118cd083eeac Mon Sep 17 00:00:00 2001
From: John Dvorak <john@johnsdvorak.com>
Date: Thu, 21 May 2026 15:05:35 -0700
Subject: [PATCH] chore: classify barrel exports with @public/@internal JSDoc
 annotations

- Mark core API as @public: runtime, fixtures, fluent entry points,
  semantic subjects, renderers, presets
- Mark internals as @internal: pool classes, page wrapper, environment
  utilities, target resolution
- Reorganize barrel into clear @public / @internal sections
---
 packages/imhotep-playwright/src/index.ts | 83 +++++++++++++-----------
 1 file changed, 46 insertions(+), 37 deletions(-)

diff --git a/packages/imhotep-playwright/src/index.ts b/packages/imhotep-playwright/src/index.ts
index 157a21c..36c32c3 100644
--- a/packages/imhotep-playwright/src/index.ts
+++ b/packages/imhotep-playwright/src/index.ts
@@ -6,39 +6,15 @@
  * and the page wrapper with extraction batching and state materialization.
  */
 
-// Primary public API: attach Imhotep to a Playwright page.
+// ─────────────────────────────────────────────────────────────────────────
+// @public  —  Core API
+// ─────────────────────────────────────────────────────────────────────────
+
+/** @public Attach Imhotep to a Playwright page. */
 export { createRuntime, ImhotepRuntime } from './runtime.js'
 export type { RuntimeOptions } from './runtime.js'
 
-// Pool classes for parallel execution.
-export { ContextPool, ContextPoolOptions } from './context-pool.js'
-export { PagePool, PagePoolOptions } from './page-pool.js'
-export { Semaphore } from './semaphore.js'
-export { DEFAULT_CONCURRENCY_CAP } from './property-runner.js'
-export type { PropertyRunnerOptions } from './property-runner.js'
-
-// Page wrapper and state materialization.
-export { ImhotepPage, wrapPage } from './page.js'
-export type {
-  ImhotepPageOptions,
-  StateSnapshot,
-} from './page.js'
-
-// Environment matrix expansion and application.
-export {
-  applyEnvironment,
-  expandEnvironmentMatrix,
-  deduplicateEnvironmentCases,
-} from './environment.js'
-export type {
-  EnvironmentCase,
-  EnvironmentAxes,
-  ColorScheme,
-  PointerType,
-  ReducedMotion,
-} from './environment.js'
-
-// Playwright test fixtures.
+/** @public Playwright test fixtures. */
 export {
   test,
   expect,
@@ -47,18 +23,15 @@ export {
 } from './fixture.js'
 export type { ImhotepFixtures } from './fixture.js'
 
-// High-level public API: fluent UI handle with assertion accumulation.
+/** @public High-level fluent API: assertion accumulation and checkAll. */
 export { imhotep, imhotepComponent, imhotepStory, imhotepFixture } from './public.js'
 export type { ImhotepUi, ComponentOptions, StoryOptions, FixtureOptions, PropertyRunHandle } from './public.js'
 
-// Semantic subject reference types (Stream 7).
+/** @public Semantic subject references (CSS, role, text, labelText, testId). */
 export type { SubjectReference } from 'imhotep-core'
 export { subjectReferenceToString } from 'imhotep-core'
 
-// Scene target resolution and renderer adapters.
-export { resolveTarget, ensureMountContainer, clearMountContainer } from './targets.js'
-export type { ResolvedTarget, TargetResolverOptions } from './targets.js'
-
+/** @public Renderer adapter registry and factory functions. */
 export {
   createRendererRegistry,
   getDefaultRendererRegistry,
@@ -78,7 +51,7 @@ export type {
   CustomRendererOptions,
 } from './renderers.js'
 
-// Reusable assertion presets.
+/** @public Reusable assertion presets. */
 export {
   touchTarget,
   toolbarAlignment,
@@ -87,3 +60,39 @@ export {
   modalContainment,
 } from './presets.js'
 export type { PresetResult } from './presets.js'
+
+// ─────────────────────────────────────────────────────────────────────────
+// @internal  —  Framework internals (not part of the public contract)
+// ─────────────────────────────────────────────────────────────────────────
+
+/** @internal Pool classes for parallel execution. */
+export { ContextPool, ContextPoolOptions } from './context-pool.js'
+export { PagePool, PagePoolOptions } from './page-pool.js'
+export { Semaphore } from './semaphore.js'
+export { DEFAULT_CONCURRENCY_CAP } from './property-runner.js'
+export type { PropertyRunnerOptions } from './property-runner.js'
+
+/** @internal Page wrapper and state materialization. */
+export { ImhotepPage, wrapPage } from './page.js'
+export type {
+  ImhotepPageOptions,
+  StateSnapshot,
+} from './page.js'
+
+/** @internal Environment matrix expansion and application. */
+export {
+  applyEnvironment,
+  expandEnvironmentMatrix,
+  deduplicateEnvironmentCases,
+} from './environment.js'
+export type {
+  EnvironmentCase,
+  EnvironmentAxes,
+  ColorScheme,
+  PointerType,
+  ReducedMotion,
+} from './environment.js'
+
+/** @internal Scene target resolution and container management. */
+export { resolveTarget, ensureMountContainer, clearMountContainer } from './targets.js'
+export type { ResolvedTarget, TargetResolverOptions } from './targets.js'