Want Fix

Tracking list of real (but non-critical) bugs and gaps found while writing hand-authored AI-reference docs (public/packages/<pkg>/ai-reference.txt) for each package. Compiled 2026-09-11 from the first 10 packages' gotcha lists.

Process (established after responsive-media + vue-state-machine)

When analyzing a package's real source to write its AI reference:

1. Real critical bugs (broken published build, wrong/empty shipped types, a documented-as-supported usage path that hard-crashes or silently does the opposite of what the types promise) → stop, flag to the user, and — if approved — fix immediately in the package's own repo (branch + PR, per that repo's branch-protection rules), before finishing the reference. Already-fixed bugs get a note in the reference's prose itself, not here.
2. Minor/low-risk bugs (safe, small, non-breaking fixes; real inconsistencies; dev-mode-only warnings worth adding) → note in the reference's own gotcha list (documenting current behavior for AI agents) and add an entry here, so they don't get lost.
3. Intentional design trade-offs / behavior that's merely non-obvious-but-correct → gotcha list only, not tracked here.

Each entry below cites its package's ai-reference.txt gotcha-list item number for full context/rationale — read that first before fixing.

---

inview

• Nuxt module doesn't register <InView> or viewportDefaults — the Nuxt module auto-imports composables/utilities/core engines and registers v-reveal, but not Vue's <InView> component or the setViewportDefaults/viewportDefaults pair. Looks like an oversight rather than a deliberate omission (everything else Vue-specific is wired). (gotcha 6)
  • Repo: C:\work\NPM\inview

rest-pipeline-js

• useRestClientVue caches by structural config equality; useRestClientReact doesn't — React creates a fully independent client per config object reference, no sharing. Worth confirming whether this is intentional (React's own memoization idioms differ from Vue's) or a straight port gap before changing anything — not a one-line fix, needs a design decision first. (gotcha 4)
• A WebSocket stage's pass/fail is decided only by close.wasClean, never by onError firing alone — worth double-checking this is actually the intended contract; a step could report success even after a visible onError, which is a surprising trap for a "did this step fail" question. (gotcha 6)
  • Repo: C:\work\NPM\rest-pipeline-js

vue-feature-toggles

• FlagSource type has no 'live' value despite live-pushed (SSE/WebSocket) updates being a real, documented source — either add 'live' to the type or document explicitly why live updates report as whatever the async loader's source was. Small, type-accuracy-only fix. (gotcha 5)
• <Feature> with neither name nor group silently renders nothing/fallback, no warning — add a dev-mode console.warn, matching the pattern already used elsewhere in this package family (e.g. vue-image-kit's missing-alt warning). Safe, additive, low-risk. (gotcha 7)
• Nuxt module doesn't auto-import the composables and doesn't accept loader/rules in its own config at all — a real completeness gap; Nuxt users can't configure the feature loader without manually calling composables themselves. (gotcha 9)
  • Repo: C:\work\NPM\vue-feature-toggles

vue-form-schema

• @macrulez/nuxt-vue-form-schema is not published to npm — administrative, not code: either publish it for real or remove/adjust every reference to it (README, site docs) to stop implying it's installable. (gotcha 1)
• An async options() function runs on every value change across the whole form, not just when its own optionsDeps change — only the optionsDeps-triggered results are used, but side effects from the extra calls still fire. Real inefficiency/correctness issue; fix requires narrowing the watchEffect dependency tracking — moderate effort, not a one-liner. (gotcha 2)
• isValid can read true while an async validator is still pending — only submit() reliably waits. Worth deciding whether isValid should track pending-async state itself (semantics change, needs a decision) or just stays documented as-is. (gotcha 3)
• Default persistKey is a plain comma-joined field-name list, not a hash — two unrelated forms with identically-named/ordered fields silently share persisted storage. Real footgun; consider hashing the default key (or including a form id) instead. (gotcha 4)
• useFieldArray's remove/move/swap don't renumber form.errors/form.touched, which are keyed by array position — real bug, produces stale/misattributed error state on affected rows after a reorder/removal. Worth prioritizing — this is actual incorrect behavior, not just a surprising design choice. (gotcha 6)
• Vue DevTools panel needs a manual installFormDevtools(app) call, unlike sibling packages in this ecosystem that wire their DevTools automatically via their plugin/Nuxt module — consistency gap, low-risk to fix (call it from the existing plugin's install()). (gotcha 11)
  • Repo: C:\work\NPM\vue-form-schema

vue-image-kit

• v-lazy-img creates its own dedicated IntersectionObserver per element instead of using the shared pool every other lazy-loading path (useLazyLoad/useImage/<VImage>/useBackgroundImage) uses — real inconsistency, worth routing it through observer-pool.ts too. (gotcha 1)
• layout unset behaves like 'responsive' visually but without its auto-sizes heuristic — since it's otherwise identical to 'responsive', this looks like an oversight rather than a deliberate difference; consider extending the heuristic to the unset case too. Low-risk consistency fix. (gotcha 5)
• Blurhash and a LQIP/thumbhash placeholder are independent v-if branches that can both mount simultaneously if both props are supplied — likely unintentional double-rendering; should probably follow the same either/or precedence the rest of the placeholder priority chain already documents. (gotcha 12)
  • Repo: C:\work\NPM\vue-image-kit

vue-storage-kit

• HIGH PRIORITY — useStorage() for an already-live key+target silently ignores every option a second caller passes — the reference itself calls this "the single biggest gotcha" in the package. At minimum, add a dev-mode warning when a second caller's options differ from the first's; ideally reconsider the sharing model. (gotcha 1)
• throttle silently wins over debounce when both are set on the same call — add a dev-mode warning; cheap, no behavior change. (gotcha 2)
• httpOnly on the base (client-only) useCookie() is a silent no-op — only the Nuxt SSR replacement can actually set it, but the base composable's type happily accepts the option. Add a dev-mode warning when httpOnly is set outside the Nuxt context. (gotcha 5)
• compress() degrades silently to pass-through when unsupported, but encrypt()/sign() fail loudly — real inconsistency in error visibility between three conceptually-similar transform options; worth aligning compress() to also surface a warning/error state. (gotcha 9)
• React's useStorage doesn't react to key/target changing across re-renders — captured once at first render only; likely a real gap versus whatever the Vue version does reactively. (gotcha 12)
  • Repo: C:\work\NPM\vue-storage-kit

vue-error-boundary-kit

• <AsyncBoundary> is not auto-registered as a global component by the Nuxt module (only <ErrorBoundary> is) — safe additive fix, register it too. (gotcha 6)
• createHttpReporter's pagehide listener is registered permanently with no way to remove it — no stop()/cleanup returned. Low-risk additive fix (return a cleanup function). (gotcha 8)
• Nuxt module's autoImports list is incomplete — only 3 of the package's many composables/factories are auto-imported (useRouterErrorBoundary, useQueryErrorReset, createBackoffRetry, createErrorHistory, every adapter factory are all missing). Bundle with the <AsyncBoundary> fix above as one "Nuxt module completeness" pass. (gotcha 14)
  • Repo: C:\work\NPM\vue-error-boundary-kit

vue-worker-kit

• createWorkerPool/useWorkerPool's run()/map() silently discard ctx.reportProgress()/ctx.reportChunk() from the worker handler — no progress/chunks exists anywhere on WorkerPool, and the exact same handler file loses this capability only when run through a pool, with zero warning. Worth wiring progress/chunks through WorkerClient.send() in pool.ts's dispatch(), or at least warning when a handler tries to use them under a pool. (gotcha 2)
• useWorker's public API has no terminate() method at all — only reachable via idle timer, hardCancelOnAbort, or effect-scope disposal. Calling useWorker() outside an active effect scope (a Pinia store, a plain factory) means the worker is never auto-terminated. Add an explicit terminate() to the returned object — safe, additive. (gotcha 3)
• A worker crash (Worker.onerror) doesn't null out/recreate the worker on useWorker's side — unlike the idle-timeout/ hardCancelOnAbort/scope-dispose paths, which do. The next run() reuses the same broken instance. Real bug — worth nulling worker/ client on crash too, so the next call transparently creates a fresh one. (gotcha 6)
• With streaming: false (default), a handler that calls ctx.reportChunk() has every chunk silently dropped — add a dev-mode warning. (gotcha 9)
• The "nuxt" package.json keyword is stale — no Nuxt module exists in the current source (one was added and fully reverted before any release). Trivial, zero-risk fix: remove the keyword. (gotcha 10)
• WorkerComputedResult's fields are typed readonly but the actual return value is a plain reactive() wrapper — result.value = x would actually succeed at runtime. Consider wrapping with Vue's readonly() to actually enforce it. (gotcha 11)
• RetryStrategyOptions/StreamingOptions (exported from the root barrel) aren't used as the actual parameter type anywhere — UseWorkerOptions/UseSharedWorkerOptions redeclare the same fields inline instead of extending them. Minor cleanup: either wire them in properly or stop exporting them. (gotcha 12)
  • Repo: C:\work\NPM\vue-worker-kit

vue-state-machine

• MachineStore.register() has zero collision detection — a duplicate id (from defineMachine, useSharedMachine, or an explicit WizardOptions.id) silently overwrites the prior entry, in any mode. Worth at least a dev-mode warning on overwrite. (gotcha 7)
• useMachine() never auto-unregisters from the MachineStore/ DevTools registry when its owning component unmounts — no onUnmounted cleanup anywhere in the package; the registry only grows for an app that mounts/unmounts many distinct-id machines. (gotcha 6)
• useSharedMachine(config, options)'s options only apply on the very first call for a given id — every later caller's options (including persist) are silently ignored, with no indication in the type signature. Worth at least a dev-mode warning when a later call's options actually differ from what's already active. (gotcha 8)
  • Repo: C:\work\NPM\vue-state-machine
  • Note: the two critical bugs found in this package (empty published .d.ts; dev-diagnostics dead-code-eliminated in production) were already fixed live, via PR #14 + PR #15, shipped in 0.2.5 — not tracked here, see the reference's own section 10 for details.

responsive-media

• isAbove(key) has no bounds guard for an unrecognized key, unlike isBelow/between — a typo'd key makes isAbove return true whenever any breakpoint is active (since indexOf returns -1, and any real index is > -1), while the sibling methods correctly guard curIdx !== -1 && and return false. Same fix pattern exists right there in the same class — one-line, safe, no API change. (gotcha 2, BaseResponsiveState, exists in both vue-responsive.ts's and react-responsive.ts's own re-implementations of the same logic too — check all three spots)
• Two different isSSR() implementations exist in the same package — utils.ts's is just typeof window === 'undefined'; media-query.ts's private one also checks typeof window.matchMedia === 'function'. In an environment with window but no matchMedia, syncCSSVars()/emitDOMEvents() would proceed while subscribeMediaQuery() bails — worth unifying on the stricter check. (gotcha 6)
• useBreakpoints() (Vue) ignores inject()/DI entirely, while useResponsive() honors it — real inconsistency between two composables that should behave the same way re: a manually-provided custom state. (gotcha 8)
• Vue's useMediaQuery() can leak its matchMedia listener if called outside an active component instance — onUnmounted(off) is only wired when getCurrentInstance() is truthy, and off is never exposed to the caller otherwise. Consider always returning off (or a stop function) from the composable. (gotcha 9)
• React's useContainerState() sets up its ResizeObserver exactly once via useEffect(..., []) — if ref.current is null when the effect runs (element behind a later-mounted conditional/ portal), the observer is never created for that component instance's lifetime. Vue's watchEffect-based equivalent correctly re-runs. (gotcha 10)
• hydrate(initialState) silently drops any key not already present in the live state — no error/warning, e.g. after a setConfig() narrowed the active keyset. (gotcha 12)
• Neither the Vue nor the React adapter has any automated test coverage — the whole 1495-line test suite only exercises the framework-agnostic core. Every composable/hook above (including the other gotchas in this section) is unverified by CI. (gotcha 11)
  • Repo: C:\work\NPM\responsive-media
  • Note: the critical bug found in this package (main entry unconditionally importing @vue/runtime-core, breaking non-Vue consumers despite vue being an optional peer) was already fixed live via PR #20 (new /vue subpath), shipped in 2.0.0 — not tracked here.

vue-command-palette

• PaletteOptions.bindShortcuts only binds top-level commands' shortcut as real global hotkeys — a shortcut on a subCommand is silently never bound, because the underlying watch only observes store.state.commands, which never contains nested subCommands. (gotcha 4)
• The bindShortcuts fallback executor (runFallback, only used when no <CommandPalette> is mounted) mishandles a page-only command — it checks only subCommands?.length, so a command with page but no subCommands falls through and calls perform() directly instead of opening the page. Same fallback is also missing confirm handling and frecency/recent tracking entirely — a real, materially weaker reimplementation of executeCommand. (gotcha 5)
• CommandItem's description-highlighting is a second, independent, non-diacritic-aware substring implementation, inconsistent with the real (diacritic-aware) scorer in FuzzySearch.ts — a description containing café won't visually highlight for a query of cafe, even though the underlying match actually succeeded. Should reuse getMatchRanges instead of its own inline .indexOf(). (gotcha 10)
• Nuxt module registers zero components (addComponent is never called — <CommandPalette> and friends need a manual import even under Nuxt) and auto-imports only 3 of the package's many composables/factories (fuzzySearch, highlightMatches, getMatchRanges, createCommandStore, createKeyboardManager, resolvePaletteContext, createCommandPalette/installPalette are all missing from addImports). (gotcha 17)
• isLoading is one shared boolean across three independent async search pipelines (group/global, page, mode) in CommandPalette.vue — concurrent in-flight requests across pipelines can clear the spinner prematurely while another is still pending. Needs ref-counting instead of a single boolean. (gotcha 14)
• Async result merging is "first-registered wins" on id collision (displayResults, and the no-query async-group merge) — a slower-arriving async result with a strictly better score than an already-merged sync result of the same id is dropped, never used to replace it. (gotcha 13)
• PaletteProvider (testing.ts component) only provides PALETTE_INJECT_KEY, not PALETTE_REGISTRY_KEY — named-instance lookups (useCommandPalette('name')) fail under it even though the lower-level createPaletteContext function it wraps does build a registry. Easy fix: also provide(PALETTE_REGISTRY_KEY, registry) in the component. (gotcha 16)
• The global hotkey toggle (installPalette) and useCommandPalette()'s own toggle()/open()/close() are two separate, independent implementations of open/close semantics — e.g. the hotkey path doesn't clear history on close the way close() does. Worth unifying onto one implementation to remove the duplicate-maintenance risk. (gotcha 15)
• Nuxt module config (vCommandPalette in nuxt.config.ts) is written straight into runtimeConfig.public, which Nuxt serializes to the client — function-valued options (onOpen, onError, search, onSearch, etc.) are typed fields of PaletteOptions (and thus ModuleOptions) but won't realistically survive that boundary. Worth either narrowing ModuleOptions to the serializable subset (breaking-ish, needs a decision) or at minimum documenting it loudly. (gotcha 18)
  • Repo: C:\work\NPM\vue-command-palette

os-detect

• detectIsiOS() (deprecated alias) calls console.warn on every invocation, not just once — the underlying cached boolean result is deduped, but the deprecation warning itself isn't. Easy, safe fix: gate it behind a module-level "already warned" flag. (gotcha 10)
• useIsWindows11() has no unmount guard in either the Vue or React binding — detectIsWindows11()'s promise can resolve after the component unmounts and still call the setter/assign the ref. Safe fix: track a mounted/cancelled flag in both os-detect/vue and os-detect/react. (gotcha 11)
• detectIsWindows11() is the only detector never memoized — every call re-runs full detection, including a real Client Hints round-trip in the browser. Consider caching its resolved promise the same way memoizeBoolean caches every other detector (with a resetDetectionCache()-compatible reset hook). Lower priority — correctness isn't at stake, just repeated work on repeated calls. (gotcha 5)
• package-lock.json's root "version" field (2.1.4) is stale relative to package.json's 2.2.0 — cosmetic lockfile-hygiene mismatch, not a runtime bug; would resolve itself on the next npm install.
  • Repo: C:\work\NPM\os-detect

color-value-tools

(6 live bugs found in this package were serious enough to fix immediately, not deferred here — see PR https://github.com/macrulezru/color-value-tools/pull/17: fabricated colors for currentcolor/inherit/initial/unset, toNearestNamedColor() collapsing onto "transparent", colorShades/monochromatic producing "#NaNNaNNaN" at steps===1, getColorType() missing 8-digit hex, rgbaStringToRgba() not clamping, and color(srgb-linear ...) missing gamma correction — see the AI reference's own section 11 for details. One more, found afterward while writing the reference, is below.)

• isReadableOnBackground()'s returned wcagLevel field ignores the actual background argument for the 'semi-transparent'/ 'gradient' BackgroundSpec shapes — it's always computed against a hardcoded '#ffffff', while minContrastRatio/ readable are correctly computed from the real composited/ worst-case color. The three returned fields can disagree with each other for those two shapes. Fix: compute wcagLevel from the same effective background color (or worst-case stop) the ratio itself used.
  • Repo: C:\work\NPM\color-value-tools

css-magic-gradient

(6 live bugs + a README example found in this package were serious enough to fix immediately, not deferred here — see PR https://github.com/macrulezru/css-magic-gradient/pull/22: getContext() Web Worker ReferenceError crash, gradientToDataURL() OffscreenCanvasTypeError crash, angle: 0 silently ignored in 4 linear-gradient functions, createConicGradient({steps:1}) NaN-absorption bug, 5 harmony generators bypassing resolveBaseColor() and silently defaulting to black instead of this package's own fallback-color convention, and a dead weightByArea option removed from bestGradientTextColor() — see the AI reference's own section 13 for details. One more, found afterward while writing the reference, is below.)

• No useMonochromaticGradient/useHueWheelGradient reactive hook in either css-magic-gradient/vue or css-magic-gradient/react — both hook files export the exact same 15 use* functions, covering every other generator in presets.ts/linear-gradient.ts/ radial-gradient.ts/conic-gradient.ts/accessibility.ts 1:1, but these two create*Gradient functions have no reactive wrapper in either framework binding. Looks like an oversight (both generators predate neither hook file, nothing about them is structurally different from the other 8 dynamic generators that do have hooks) rather than a deliberate omission. (ai-reference gotcha 6)
  • Repo: C:\work\NPM\css-magic-gradient