@immense/vue-pom-generator 1.0.53 → 1.0.54

package/README.md

@@ -74,7 +74,7 @@ The generator does not use one naming trick. It layers several signals.
 - **Router links / `:to` bindings** can contribute route-based naming and typed navigation return types when the target can be resolved.
 - **Wrapper components** can be explicit (`nativeWrappers`) or inferred from simple local SFC templates.
 - **Fallback naming exists, but it is intentionally conservative.** That is why `generation.nameCollisionBehavior` exists.
-- **You can opt into stricter wrapper-action generation.** `errorBehavior: "error"` blocks button-like wrapper `:handler` expressions that the generator cannot turn into a semantic action name.
+- **Wrapper-action generation fails fast by default.** The generator blocks button-like wrapper `:handler` expressions that it cannot turn into a semantic action name; set `errorBehavior: "ignore"` if you explicitly want the old permissive fallback.
 
 Important limit: wrapper inference is helpful, not magical. The current implementation recursively inspects simple local SFC templates for the first inferable primitive (`input`, `textarea`, `select`, `button`, `vselect`, radio/checkbox inputs). It also recognizes some naming patterns like `*Button`. For anything more complex, configure `nativeWrappers` explicitly.
 
@@ -617,6 +617,7 @@ What it gives you:
 - lower-camel-case fixtures for component classes too
 - `pomFactory.create(Ctor)` for ad-hoc page-object construction inside tests
 - an `animation` option that wires the generated runtime's pointer settings
+- per-page `renderers` overrides so you can keep the simple default callout or swap in a custom pointer / callout overlay implementation such as the bundled `floating-ui-callout.ts` renderer
 
 Current caveats:
 
@@ -625,6 +626,12 @@ Current caveats:
 - component fixtures are skipped when their lower-camel-case name would collide with reserved Playwright fixture names such as `page`, `context`, `browser`, or `request`
 - an override class still needs a `new (page)`-compatible constructor because that is what fixtures call
 
+By default the runtime uses a simple red fallback bubble. The example below uses the optional floating-ui renderer so the callout can auto-place around nearby UI and point back to the target with an arrow.
+
+Example floating-ui callout sequence captured from the Playwright fixture coverage:
+
+![Pointer callout sequence](./docs/assets/pointer-callout-sequence.gif)
+
 ## TypeScript vs C# output
 
 ### TypeScript output
@@ -846,12 +853,12 @@ The sections below follow the actual `VuePomGeneratorPluginOptions` shape from `
 
 - **What it does:** Controls strict/error behavior for generator checks.
 - **Why it exists:** complex inline handlers can otherwise fall through to generic naming, which makes generated APIs harder to discover and review.
-- **Benefit:** `"error"` lets you opt into fail-fast behavior globally, while the object form lets you turn on only the checks you care about.
-- **Without it:** the default is `"ignore"`, so existing permissive fallback behavior remains in place.
+- **Benefit:** fail-fast behavior is the default, while `"ignore"` or the object form let you opt back into only the permissive checks you want.
+- **Without it:** the default is `"error"`, so unsupported button-wrapper handlers stop generation instead of silently falling back.
 - **Accepted values:**
   - `"ignore"` — keep permissive defaults for all supported checks
-  - `"error"` — enable error-on-failure behavior for all supported checks
-  - `{ missingSemanticNameBehavior: "error" }` — enable only the button-wrapper semantic-name check
+  - `"error"` — enable error-on-failure behavior for all supported checks (default)
+  - `{ missingSemanticNameBehavior: "ignore" }` — opt out only of the button-wrapper semantic-name check
 - **Current scope:** this first pass is intentionally narrow. The object form currently supports `missingSemanticNameBehavior`, which targets button-like wrappers with `:handler`; value/model-driven wrappers still use their existing naming flow.
 
 ### `injection`

package/RELEASE_NOTES.md

@@ -1,63 +1,54 @@
-● # Release Notes: v1.0.53
-
-  ## Highlights
-
-  - **Nuxt auto-detection**: Framework mode is now automatically detected—no manual configuration
-  required
-  - **Simplified configuration**: Removed `scanDirs` option in favor of automatic discovery
-  - **Improved dev-mode reliability**: Multiple fixes for Nuxt app-root POM generation and
-  snapshot preservation
-  - **Cleaner codebase**: Removed unused generation-metrics feature
+● ## Highlights
+
+  - **Zero runtime dependencies**: Eliminated all runtime dependencies for smaller bundle size and
+   reduced version conflicts
+  - **Pluggable callout renderer architecture**: Extracted floating-ui implementation into
+  swappable renderer system
+  - **Stricter semantic naming**: Unnameable wrapper handlers now fail fast by default instead of
+  silently succeeding
+  - **Streamlined callout placement pipeline**: Refactored pointer callout rendering for improved
+  maintainability
+  - **Removed peer dependencies**: No longer requires `vue`, `vitest`, or `@vue/shared` as peer
+  dependencies
 
   ## Changes
 
-  ### Configuration & Auto-detection
-  - Auto-detect Nuxt mode without requiring explicit `mode` config
-  - Remove `scanDirs` configuration option (replaced by automatic discovery)
+  ### Dependencies
+  - Eliminated all runtime dependencies
+  ([#9](https://github.com/immense/vue-pom-generator/pull/9))
+  - Removed `vue`, `vitest`, and `@vue/shared` peer dependencies
+  - Updated package structure for zero external runtime requirements
+
+  ### Callout Rendering
+  - Extracted floating-ui callout renderer into separate module (`floating-ui-callout.ts`)
+  - Introduced pluggable pointer callout renderer system
+  - Streamlined callout placement pipeline for better performance
+  - Refactored pointer rendering logic for extensibility
 
-  ### Bug Fixes
-  - Resolve Nuxt app-root dev POM clobber issue
-  - Preserve richer dev POM snapshots during generation
-  - Confirm incomplete dev snapshots to prevent silent failures
+  ### Error Handling
+  - Semantic-name validation failures now default to throwing errors instead of warnings
+  - Improved fail-fast behavior for unnameable wrapper handlers
 
-  ### Internal
-  - Add dedicated Nuxt discovery module (`plugin/nuxt-discovery.ts`)
-  - Remove generation-metrics feature and associated code
-  - Refactor path utilities and plugin creation logic
+  ### Testing
+  - Aligned dev plugin options across test suite
+  - Added pointer callout sequence documentation (GIF)
+  - Enhanced test coverage for pointer rendering
 
   ## Breaking Changes
 
-  - **Removed `scanDirs` config option**: The plugin now uses automatic directory discovery.
-  Remove any `scanDirs` configuration from your setup.
-  - **Removed generation-metrics**: The generation metrics tracking feature has been removed along
-   with `plugin/support/generation-metrics.ts`.
+  - **Peer dependencies removed**: `vue`, `vitest`, and `@vue/shared` are no longer peer
+  dependencies. Ensure your build still works if you relied on these being present.
+  - **Semantic naming errors**: Invalid semantic names now throw by default instead of warning.
+  Handlers that cannot be named semantically will cause build failures unless explicitly
+  configured otherwise.
 
   ## Pull Requests Included
 
-  - #15 [fix: resolve Nuxt app-root dev POM
-  clobber](https://github.com/immense/vue-pom-generator/pull/15) (@dkattan)
-  - #13 [Relax Vite peer dependency range](https://github.com/immense/vue-pom-generator/pull/13)
-  (@Copilot)
-  - #12 [feat: add split Playwright POM output for
-  discoverability](https://github.com/immense/vue-pom-generator/pull/12) (@dkattan)
-  - #11 [feat: fail fast on unnameable wrapper
-  handlers](https://github.com/immense/vue-pom-generator/pull/11) (@dkattan)
-  - #8 [chore: bump version to 1.0.43](https://github.com/immense/vue-pom-generator/pull/8)
-  (@mayfieldiv)
-  - #7 [test: add build–serve parity regression
-  tests](https://github.com/immense/vue-pom-generator/pull/7) (@mayfieldiv)
-  - #6 [fix: fail fast on dev snapshot generation
-  errors](https://github.com/immense/vue-pom-generator/pull/6) (@dkattan)
-  - #5 [fix: dev-mode POM generation parity with build
-  mode](https://github.com/immense/vue-pom-generator/pull/5) (@mayfieldiv)
-  - #4 [Fix keyed POM dedupe and C# navigation
-  returns](https://github.com/immense/vue-pom-generator/pull/4) (@dkattan)
-  - #1 [Add PR release-notes preview
-  comments](https://github.com/immense/vue-pom-generator/pull/1) (@dkattan)
+  - [#9](https://github.com/immense/vue-pom-generator/pull/9) - refactor(deps): eliminate all
+  runtime dependencies
 
   ## Testing
 
-  Added `tests/nuxt-discovery.test.ts` for new Nuxt auto-detection. Significantly expanded
-  `tests/build-serve-parity.test.ts` (+210 lines) and updated multiple test suites for
-  configuration and dev-plugin changes.
+  Comprehensive test updates included to validate dependency removal, plugin option alignment, and
+   pointer callout rendering behavior.
 

package/class-generation/base-page.ts

@@ -2,8 +2,8 @@ import type { PwLocator, PwPage } from "./playwright-types";
 import { TESTID_CLICK_EVENT_NAME, TESTID_CLICK_EVENT_STRICT_FLAG } from "../click-instrumentation";
 import type { TestIdClickEventDetail } from "../click-instrumentation";
 import { Callout } from "./callout";
-import { Pointer } from "./pointer";
-import type { AfterPointerClick, AfterPointerClickInfo } from "./pointer";
+import type { CalloutRenderer } from "./callout";
+import { Pointer, type AfterPointerClick, type AfterPointerClickInfo, type PointerRenderer } from "./pointer";
 
 // Click instrumentation is optional for generated POMs.
 //
@@ -55,6 +55,14 @@ export type Fluent<T extends object> = DeepFluent<T, T> & PromiseLike<T>;
 
 export type ValueFluent<T> = DeepValueFluent<T> & PromiseLike<T>;
 
+export interface BasePageOptions {
+  renderers?: {
+    callout?: CalloutRenderer;
+    pointer?: PointerRenderer;
+  };
+  testIdAttribute?: string;
+}
+
 export class ObjectId {
   private readonly raw: string;
 
@@ -99,11 +107,15 @@ export class BasePage {
   /**
    * @param {Page} page - Playwright page object
    */
-  constructor(protected page: PwPage, options?: { testIdAttribute?: string }) {
+  public constructor(protected page: PwPage, options?: BasePageOptions) {
     this.testIdAttribute = (options?.testIdAttribute || "data-testid").trim() || "data-testid";
 
-    this.callout = new Callout(this.page);
-    this.pointer = new Pointer(this.page, this.testIdAttribute, this.callout);
+    const pointerRenderer = options?.renderers?.pointer;
+    this.callout = new Callout(this.page, {
+      extraOverlayIds: pointerRenderer?.overlayIds,
+      renderer: options?.renderers?.callout,
+    });
+    this.pointer = new Pointer(this.page, this.testIdAttribute, this.callout, pointerRenderer);
   }
 
   private async waitForTestIdClickEventAfter(testId: string, options?: { timeoutMs?: number }): Promise<void> {
@@ -237,7 +249,7 @@ export class BasePage {
   }
 
   /**
-   * Animates the cursor to an element.
+   * Animates the pointer to an element.
    */
   protected async animateCursorToElement(
     target: string | PwLocator,