refactor: extract public-types.ts from public.ts (interfaces and options)

Moved ImhotepUi, ImhotepExpect, CompatibilityCheck, CompatibilityReport,
ComponentOptions, StoryOptions, FixtureOptions, PropertyRunHandle,
PropertyRunReportOptions, FixturePropertyRunHandle, ComponentPropertyRunHandle
into dedicated public-types.ts module. public.ts re-exports everything for
backward compatibility.

packages/imhotep-playwright/src/public-types.ts

@@ -0,0 +1,175 @@
+/**
+ * Public API types for imhotep-playwright.
+ *
+ * These interfaces define the contract for the Imhotep UI handle,
+ * entry-point options, property-run handles, and compatibility reporting.
+ * They are extracted from public.ts to reduce the file's size and make
+ * the public contract independently reviewable.
+ */
+
+import type { Page } from 'playwright'
+import type { FluentAssertion, FluentRelation, FluentQuantifier } from 'imhotep-dsl'
+import type { ImhotepPage, ImhotepPageOptions, StateMaterializationNote, MaterializeStateOptions } from './page.js'
+import type { ImhotepRuntime } from './runtime.js'
+import type { SubjectReference, ExecutionContext, ImhotepDiagnostic, ImhotepResult, ClauseResult, NormalizedContract } from 'imhotep-core'
+import type { EnvironmentCase } from './environment.js'
+import type { RendererDescriptor } from './renderers.js'
+import type { FastCheckAdapter } from './fast-check-adapter.js'
+import type { InputDomain } from 'imhotep-core/property-contracts'
+import type { EnumeratedRunResult, SampledRunResult } from 'imhotep-core/property-results'
+
+// ---------------------------------------------------------------------------
+// Core Public Interfaces
+// ---------------------------------------------------------------------------
+
+export interface ImhotepUi {
+  /** Fluent assertion builder bound to this page context. */
+  expect: ImhotepExpect
+
+  /** Add dense string-contract assertions to this check batch. */
+  spec(source: string): ImhotepUi
+
+  /** Add a fluent FOL quantifier assertion to this check batch. */
+  quantifier(q: FluentQuantifier): ImhotepUi
+
+  /** Parse all accumulated assertions and report syntax/validation errors without browser extraction. */
+  validate(): Array<{ type: string; line?: number; message: string; code?: string; suggestedFix?: { action: string; value?: string; rationale: string } }>
+
+  /** Evaluate all accumulated assertions and return results. */
+  checkAll(options?: { format?: 'default'; includeNormalized?: boolean }): Promise<ImhotepResult>
+  checkAll(options: { format: 'llm' }): Promise<string>
+  checkAll(options?: { format?: 'default' | 'llm'; includeNormalized?: boolean }): Promise<ImhotepResult | string>
+
+  /** Access the underlying Imhotep page wrapper. */
+  page: ImhotepPage
+
+  /** Access the underlying Playwright page. */
+  playwrightPage: Page
+
+  /** Clear the geometry snapshot cache for this session. */
+  clearCache(): void
+
+  /** Extract geometry data for elements matching the selector or subject reference. */
+  extract(subject: string | SubjectReference): Promise<unknown>
+
+  /** Materialize a UI state snapshot on the given selector. */
+  materializeState(selector: string, state: string, options?: MaterializeStateOptions): Promise<StateMaterializationNote>
+
+  /**
+   * Apply an environment case to the page.
+   *
+   * Supported axes:
+   *   - viewport:        required — { width: number; height: number }
+   *   - colorScheme:     optional — 'light' | 'dark' | 'no-preference'
+   *   - pointerType:     optional — 'mouse' | 'touch' | 'fine' | 'coarse'
+   *   - reducedMotion:   optional — 'reduce' | 'no-preference'
+   *   - deviceScaleFactor: optional — number
+   *   - locale:          optional — string (e.g. 'en-US')
+   */
+  applyEnvironment(env: EnvironmentCase): Promise<void>
+
+  /** Resolve a subject by ARIA role (and optional accessible name). */
+  getByRole(role: string, options?: { name?: string }): SubjectReference
+
+  /** Resolve a subject by visible text content. */
+  getByText(text: string): SubjectReference
+
+  /** Resolve a subject by associated label text. */
+  getByLabelText(label: string): SubjectReference
+
+  /** Resolve a subject by data-testid attribute. */
+  getByTestId(testId: string): SubjectReference
+
+  /** Resolve a subject by explicit CSS selector (fallback). */
+  locator(selector: string): SubjectReference
+
+  /** Execution context controlling ids, clocks, and rng for this session. */
+  context: ExecutionContext
+
+  /** Runtime capability checks for version-skew diagnosis. */
+  compatibilityReport(): CompatibilityReport
+}
+
+export interface ImhotepExpect {
+  (subject: string | SubjectReference): FluentAssertion
+  all(subject: string | SubjectReference): FluentAssertion
+  any(subject: string | SubjectReference): FluentAssertion
+  none(subject: string | SubjectReference): FluentAssertion
+}
+
+export interface CompatibilityCheck {
+  id: string
+  ok: boolean
+  details: string
+}
+
+export interface CompatibilityReport {
+  ok: boolean
+  generatedAt: string
+  checks: CompatibilityCheck[]
+  packageFingerprints: Array<{ name: string; version: string; resolvedFrom: string }>
+}
+
+// ---------------------------------------------------------------------------
+// Entry-Point Options
+// ---------------------------------------------------------------------------
+
+export interface ComponentOptions {
+  renderer: RendererDescriptor
+  props?: unknown
+  env?: ImhotepPageOptions
+  fc?: FastCheckAdapter
+}
+
+export interface StoryOptions {
+  storybookUrl: string
+  args?: unknown
+  env?: ImhotepPageOptions
+  fc?: FastCheckAdapter
+}
+
+export interface FixtureOptions {
+  env?: ImhotepPageOptions
+  fc?: FastCheckAdapter
+  /** Directory to resolve fixture IDs against. */
+  fixturesDir?: string
+}
+
+// ---------------------------------------------------------------------------
+// Property Run Handles
+// ---------------------------------------------------------------------------
+
+/** @deprecated Use FixturePropertyRunHandle or ComponentPropertyRunHandle instead. */
+export type PropertyRunHandle = FixturePropertyRunHandle
+
+export interface PropertyRunReportOptions {
+  reportMode?: 'compact' | 'verbose'
+}
+
+export interface FixturePropertyRunHandle {
+  /** Run assertions exhaustively over all enumerated input combinations. */
+  exhaustivelyForAllInputs(
+    runtime: Page | ImhotepRuntime,
+    domain: InputDomain,
+    runner: (scene: ImhotepUi, ctx: { caseId: string; input: unknown }) => Promise<void> | void,
+    options?: PropertyRunReportOptions
+  ): Promise<EnumeratedRunResult>
+
+  /** Run assertions over all generated input combinations (sampled). */
+  forAllInputs(
+    runtime: Page | ImhotepRuntime,
+    domain: InputDomain,
+    runner: (scene: ImhotepUi, ctx: { caseId: string; input: unknown }) => Promise<void> | void,
+    options?: PropertyRunReportOptions
+  ): Promise<SampledRunResult>
+}
+
+export interface ComponentPropertyRunHandle {
+  /** Run assertions over all generated prop combinations (sampled). */
+  forAllProps(
+    runtime: Page | ImhotepRuntime,
+    domain: InputDomain,
+    runner: (scene: ImhotepUi, ctx: { caseId: string; input: unknown }) => Promise<void> | void,
+    options?: PropertyRunReportOptions
+  ): Promise<SampledRunResult>
+}

packages/imhotep-playwright/src/public.ts

@@ -68,101 +68,36 @@ import {
   getDefaultCacheDir,
 } from 'imhotep-core'
 import type { EnvironmentCase } from './environment.js'
+import type {
+  ImhotepUi,
+  ImhotepExpect,
+  CompatibilityCheck,
+  CompatibilityReport,
+  ComponentOptions,
+  StoryOptions,
+  FixtureOptions,
+  PropertyRunHandle,
+  PropertyRunReportOptions,
+  FixturePropertyRunHandle,
+  ComponentPropertyRunHandle,
+} from './public-types.js'
 
-export interface ImhotepUi {
+export type {
-  /** Fluent assertion builder bound to this page context. */
+  ImhotepUi,
-  expect: ImhotepExpect
+  ImhotepExpect,
-
+  CompatibilityCheck,
-  /** Add dense string-contract assertions to this check batch. */
+  CompatibilityReport,
-  spec(source: string): ImhotepUi
+  ComponentOptions,
-
+  StoryOptions,
-  /** Add a fluent FOL quantifier assertion to this check batch. */
+  FixtureOptions,
-  quantifier(q: FluentQuantifier): ImhotepUi
+  PropertyRunHandle,
-
+  PropertyRunReportOptions,
-  /** Parse all accumulated assertions and report syntax/validation errors without browser extraction. */
+  FixturePropertyRunHandle,
-  validate(): Array<{ type: string; line?: number; message: string; code?: string; suggestedFix?: { action: string; value?: string; rationale: string } }>
+  ComponentPropertyRunHandle,
-
-  /** Evaluate all accumulated assertions and return results. */
-  checkAll(options?: { format?: 'default'; includeNormalized?: boolean }): Promise<ImhotepResult>
-  checkAll(options: { format: 'llm' }): Promise<string>
-  checkAll(options?: { format?: 'default' | 'llm'; includeNormalized?: boolean }): Promise<ImhotepResult | string>
-
-  /** Access the underlying Imhotep page wrapper. */
-  page: ImhotepPage
-
-  /** Access the underlying Playwright page. */
-  playwrightPage: Page
-
-  /** Clear the geometry snapshot cache for this session. */
-  clearCache(): void
-
-  /** Extract geometry data for elements matching the selector or subject reference. */
-  extract(subject: string | SubjectReference): Promise<unknown>
-
-  /** Materialize a UI state snapshot on the given selector. */
-  materializeState(selector: string, state: string, options?: MaterializeStateOptions): Promise<StateMaterializationNote>
-
-  /**
-   * Apply an environment case to the page.
-   *
-   * Supported axes:
-   *   - viewport:        required — { width: number; height: number }
-   *   - colorScheme:     optional — 'light' | 'dark' | 'no-preference'
-   *   - pointerType:     optional — 'mouse' | 'touch' | 'fine' | 'coarse'
-   *   - reducedMotion:   optional — 'reduce' | 'no-preference'
-   *   - deviceScaleFactor: optional — number
-   *   - locale:          optional — string (e.g. 'en-US')
-   */
-  applyEnvironment(env: EnvironmentCase): Promise<void>
-
-  // ---------------------------------------------------------------------------
-  // Semantic Subject Resolution (Stream 7)
-  // ---------------------------------------------------------------------------
-
-  /** Resolve a subject by ARIA role (and optional accessible name). */
-  getByRole(role: string, options?: { name?: string }): SubjectReference
-
-  /** Resolve a subject by visible text content. */
-  getByText(text: string): SubjectReference
-
-  /** Resolve a subject by associated label text. */
-  getByLabelText(label: string): SubjectReference
-
-  /** Resolve a subject by data-testid attribute. */
-  getByTestId(testId: string): SubjectReference
-
-  /** Resolve a subject by explicit CSS selector (fallback). */
-  locator(selector: string): SubjectReference
-
-  /** Execution context controlling ids, clocks, and rng for this session. */
-  context: ExecutionContext
-
-  /** Runtime capability checks for version-skew diagnosis. */
-  compatibilityReport(): CompatibilityReport
-}
-
-export interface CompatibilityCheck {
-  id: string
-  ok: boolean
-  details: string
-}
-
-export interface CompatibilityReport {
-  ok: boolean
-  generatedAt: string
-  checks: CompatibilityCheck[]
-  packageFingerprints: Array<{ name: string; version: string; resolvedFrom: string }>
 }
 
 const cjsRequire = createRequire(import.meta.url)
 
-export interface ImhotepExpect {
-  (subject: string | SubjectReference): FluentAssertion
-  all(subject: string | SubjectReference): FluentAssertion
-  any(subject: string | SubjectReference): FluentAssertion
-  none(subject: string | SubjectReference): FluentAssertion
-}
-
 // Internal assertion accumulator per UI handle
 const assertionStore = new WeakMap<ImhotepUi, (FluentRelation | FluentAssertion | FluentQuantifier)[]>()
 const specStore = new WeakMap<ImhotepUi, string[]>()
@@ -200,70 +135,6 @@ function maybeInstallExtractionStatsHook(): void {
   })
 }
 
-// ---------------------------------------------------------------------------
-// Component / Story / Fixture Entry Point Options
-// ---------------------------------------------------------------------------
-
-export interface ComponentOptions {
-  renderer: RendererDescriptor
-  props?: unknown
-  env?: ImhotepPageOptions
-  fc?: FastCheckAdapter
-}
-
-export interface StoryOptions {
-  storybookUrl: string
-  args?: unknown
-  env?: ImhotepPageOptions
-  fc?: FastCheckAdapter
-}
-
-export interface FixtureOptions {
-  env?: ImhotepPageOptions
-  fc?: FastCheckAdapter
-  /** Directory to resolve fixture IDs against. */
-  fixturesDir?: string
-}
-
-// ---------------------------------------------------------------------------
-// Property Run Handles
-// ---------------------------------------------------------------------------
-
-/** @deprecated Use FixturePropertyRunHandle or ComponentPropertyRunHandle instead. */
-export type PropertyRunHandle = FixturePropertyRunHandle
-
-export interface PropertyRunReportOptions {
-  reportMode?: 'compact' | 'verbose'
-}
-
-export interface FixturePropertyRunHandle {
-  /** Run assertions exhaustively over all enumerated input combinations. */
-  exhaustivelyForAllInputs(
-    runtime: Page | ImhotepRuntime,
-    domain: InputDomain,
-    runner: (scene: ImhotepUi, ctx: { caseId: string; input: unknown }) => Promise<void> | void,
-    options?: PropertyRunReportOptions
-  ): Promise<EnumeratedRunResult>
-
-  /** Run assertions over all generated input combinations (sampled). */
-  forAllInputs(
-    runtime: Page | ImhotepRuntime,
-    domain: InputDomain,
-    runner: (scene: ImhotepUi, ctx: { caseId: string; input: unknown }) => Promise<void> | void,
-    options?: PropertyRunReportOptions
-  ): Promise<SampledRunResult>
-}
-
-export interface ComponentPropertyRunHandle {
-  /** Run assertions over all generated prop combinations (sampled). */
-  forAllProps(
-    runtime: Page | ImhotepRuntime,
-    domain: InputDomain,
-    runner: (scene: ImhotepUi, ctx: { caseId: string; input: unknown }) => Promise<void> | void,
-    options?: PropertyRunReportOptions
-  ): Promise<SampledRunResult>
-}
-
 // ---------------------------------------------------------------------------
 // Runtime normalization helper (accepts Page for backward compat)
 // ---------------------------------------------------------------------------