@stacksjs/defaults 0.75.109 → 0.75.111

package/ai/skills/stacks-codebase-design/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/ai/skills/stacks-codebase-design/NOTICE.md

@@ -0,0 +1,10 @@
+# Source and license
+
+The upstream MIT notice is preserved in [LICENSE](LICENSE).
+
+## codebase-design
+
+Source: [skills/engineering/codebase-design/SKILL.md](https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/codebase-design/SKILL.md),
+revision `49dd158d1076134a641b33efb035946536778336`.
+
+Reviewed against the existing Stacks workflow. Stacks API guidance is retained; current workflow changes and supporting references are integrated where applicable.

package/ai/skills/stacks-codebase-design/SKILL.md

@@ -101,6 +101,11 @@ whether a trait wants to be born.
 
 ## Principles
 
+A module may have internal seams used by its own implementation tests as well
+as an external seam used by callers. Keep that distinction explicit: a private
+test seam does not become part of the public interface merely because a test
+uses it. Confirm the intended test surface and preserve public-behavior tests.
+
 - **Depth is a property of the interface, not the implementation.** A deep module
   can be internally composed of small, swappable parts. They just are not part of
   the interface. A module can have **internal seams** (private, used by its own
@@ -175,6 +180,11 @@ per suite. See `stacks-tdd` for where that line sits.
 
 ## Downstream
 
+Current upstream provenance is in [NOTICE.md](NOTICE.md). Read
+[the Stacks adaptation rules](../stacks-flow/ENGINEERING.md) with this workflow.
+Use `stacks-improve-codebase-architecture` to find a concrete deepening
+candidate and `stacks-setup-deep-modules` when enforcing package entrypoints.
+
 > Reach for `stacks-tdd` to write the tests at the seam you chose, and
 > `stacks-domain-modeling` when the module needs a name the project does not
 > have yet.

package/ai/skills/stacks-collections/SKILL.md

@@ -41,7 +41,7 @@ collect([10, 20, 30]).max()     // 30
 
 // Grouping
 collect(users).groupBy('role')
-// { admin: [...], user: [...] }
+// Map<role, CollectionOperations<User>>; use groups.get('admin')?.toArray()
 
 // Sorting
 collect(items).sortBy('price').toArray()
@@ -70,13 +70,30 @@ collect([1, 2, 3]).reduce((sum, n) => sum + n, 0)  // 6
 
 ## Laravel-Style Methods
 
-The `ts-collect` library provides a comprehensive Laravel Collection-compatible API including:
+The API is inspired by Laravel, but the installed TypeScript implementation is
+the authority. Its method names, argument order, return types and mutation
+semantics are not an assertion of complete Laravel compatibility. Use the
+exported `CollectionOperations<T>` type to check a method before using it.
 
-`all`, `avg`, `chunk`, `collapse`, `combine`, `concat`, `contains`, `count`, `countBy`, `crossJoin`, `dd`, `diff`, `diffAssoc`, `diffKeys`, `dump`, `duplicates`, `each`, `every`, `except`, `filter`, `first`, `firstOrFail`, `firstWhere`, `flatMap`, `flatten`, `flip`, `forget`, `forPage`, `get`, `groupBy`, `has`, `implode`, `intersect`, `intersectByKeys`, `isEmpty`, `isNotEmpty`, `join`, `keyBy`, `keys`, `last`, `macro`, `map`, `mapInto`, `mapSpread`, `mapToGroups`, `mapWithKeys`, `max`, `median`, `merge`, `mergeRecursive`, `min`, `mode`, `nth`, `only`, `pad`, `partition`, `pipe`, `pluck`, `pop`, `prepend`, `pull`, `push`, `put`, `random`, `reduce`, `reject`, `replace`, `replaceRecursive`, `reverse`, `search`, `shift`, `shuffle`, `skip`, `skipUntil`, `skipWhile`, `slice`, `sole`, `some`, `sort`, `sortBy`, `sortByDesc`, `sortDesc`, `sortKeys`, `sortKeysDesc`, `splice`, `split`, `sum`, `take`, `takeUntil`, `takeWhile`, `tap`, `times`, `toArray`, `toJson`, `transform`, `union`, `unique`, `uniqueStrict`, `unless`, `unlessEmpty`, `unlessNotEmpty`, `unwrap`, `values`, `when`, `whenEmpty`, `whenNotEmpty`, `where`, `whereBetween`, `whereIn`, `whereInstanceOf`, `whereNotBetween`, `whereNotIn`, `whereNotNull`, `whereNull`, `wrap`, `zip`
+Verified common operations include `map`, `filter`, `reduce`, `flatMap`,
+`chunk`, `groupBy`, `keyBy`, `countBy`, `pluck`, `sortBy`, `sortByDesc`,
+`unique`, `sum`, `avg`, `min`, `max`, `first`, `last`, `partition`,
+`where`, `whereIn`, `intersect`, `union`, and `toArray`. The installed release
+uses `toJSON`, not the assumed `toJson` spelling. `groupBy` returns a Map of
+collections; `keyBy` and `countBy` also return Maps. Read their types when
+serializing or passing them across a package boundary.
+
+The wrapper exports `Collection`, `CollectionOperations`, `CollectionMetrics`,
+`LazyCollectionOperations`, `PaginationResult`, `StandardDeviationResult` and
+`ValidationSchema`. Annotate exported collection values with a named type to
+keep declaration generation from degrading an inferred re-export to unknown.
 
 ## Gotchas
-- **Thin wrapper** — re-exports `collect` from `ts-collect`, no custom additions
-- **Collections are immutable** — operations return new collection instances
-- **For simple array operations** — `@stacksjs/arrays` may be more appropriate
-- **Laravel API compatibility** — method names and behavior match Laravel's Collection class
-- **Not used for ORM results** — ORM queries return plain arrays, not collections. Wrap with `collect()` if needed
+- **Thin wrapper** - re-exports `collect` and collection types from `ts-collect`
+- **Mutation is method-specific** - map/filter return new collections, while
+  pop/shift mutate the collection's shared backing array. Clone input if later
+  operations must not change the caller's array.
+- **For simple array operations** - `@stacksjs/arrays` may be more appropriate
+- **Map results are not JSON objects** - convert them deliberately; JSON.stringify
+  on a Map does not serialize its entries.
+- **Not used for ORM results** - ORM queries return plain arrays, not collections. Wrap with `collect()` if needed

package/ai/skills/stacks-commerce/SKILL.md

@@ -238,7 +238,31 @@ await Payment.charge(customer, { amount: order.totalAmount, currency: 'usd' }, p
 The provider's webhook reaches orders through `POST /webhooks/payments` (see `stacks-payments`).
 
 ## Dashboard Routes
-All commerce models have dashboard views at `/dashboard/commerce/*`.
+Commerce dashboard pages use `/commerce/*` on the dashboard server, for example
+`/commerce/products` and `/commerce/orders`. Their data Actions use
+`/api/dashboard/*`. Verify the actual page registry instead of assuming that
+every commerce model has an automatically generated dashboard view.
+
+## Enable the feature and choose the native seam
+
+Read `config/commerce.ts` and the feature lifecycle before adding a parallel
+cart or checkout library. `buddy commerce:install` enables the feature and
+copies its owned scaffold paths without overwriting existing application work
+by default. The `@stacksjs/features` manifest owns its tables and the migration
+runner gates disabled feature migrations. Changing `enabled` alone does not
+prove that a route bundle or view has been mounted.
+
+The namespace's helpers, model methods and provider APIs are separate seams.
+Use the existing checkout guards, order state transitions, idempotency and
+provider webhook Actions for an order flow; creating a local payment row does
+not establish that a provider collected money. Public storefront data should
+carry the product/customer/site scope chosen at its boundary.
+
+For variant selection, shipping zones/rates, auctions, digital deliveries or
+loyalty rules, inspect the selected submodule's exported operations and its
+tests rather than extrapolating a generic CRUD interface. Native models cover
+more domain features than the short table here lists. Feature-specific routes
+and jobs also need their enabled feature, tables and worker prerequisites.
 
 ## Gotchas
 

package/ai/skills/stacks-composables/BROWSER.md

@@ -0,0 +1,97 @@
+# STX browser delivery and contracts
+
+This reference applies to `<script client>` in the current installed STX.
+The eager runtime, client-script compiler and demand bundler cooperate. The
+ambient browser manifest is a type declaration input, not this delivery map.
+
+## Delivery paths
+
+1. Eager runtime primitives are exposed on `window.stx`; the compiler provides
+   the names a script uses. Some also have explicit bare `window.name` aliases.
+2. STX scans authored calls for supported demand composables and emits their
+   browser code. `useForm`, observers, mouse/parallax and scroll helpers use
+   this path. The deprecated internal name `SERVER_ONLY_COMPOSABLES` is a
+   demand allowlist, not a statement that those helpers cannot run in browsers.
+3. Explicit application-module imports are bundled separately. Their bindings
+   do not leak into another imported module or magically change Ref contracts.
+
+Installed STX 0.2.422 delivers `useForm`, `useIntersectionObserver`,
+`useMouse`, `useParallax`, and `useScroll` on demand. It eagerly supplies
+`useMediaQuery` and `usePreferredReducedMotion` through the runtime/compiler.
+An older installation must be checked against its own runtime and demand
+implementation rather than a newer docs list. Demand legacy helpers commonly
+expose getters, `get()`, `subscribe()`, and `stop()`. Their getters are not
+automatically signal-tracked template values.
+
+## Browser and module contracts differ
+
+| Name | STX client runtime | Explicit @stacksjs/composables |
+|---|---|---|
+| useCounter | numeric count getter, inc/dec/set/reset, subscribe | count Ref, inc/dec/set/reset/get |
+| useFocus | isFocused getter, focus/blur/subscribe | focused Ref, focus/blur |
+| useTimeout | callback then delay, pending getter and start/stop | interval then options, Ref or controls |
+| useLocalStorage | callable signal | object Ref |
+| useForm | schema then initialValues, signal-backed property records | options object, Stacks schema rules, Ref values and field accessors |
+
+## Motion and observers
+
+Prefer CSS transitions or scroll-driven animation. Use the eager reduced-motion
+signal for anything beyond hover. Attach native browser observation in a mount
+hook and clean it up at component destruction:
+
+```html
+<script client>
+const card = useRef('card')
+const visible = state(false)
+const reduceMotion = usePreferredReducedMotion()
+
+onMount(() => {
+  const observer = useIntersectionObserver(
+    () => card.current,
+    entry => visible.set(entry.isIntersecting),
+  )
+  onDestroy(() => observer.stop())
+})
+</script>
+
+<article ref="card" :class="visible() || reduceMotion() ? 'opacity-100' : 'opacity-0'">
+  Content
+</article>
+```
+
+STX `useScroll()` observes window scrolling; `useMouse(options?)` tracks
+mouse state; `useParallax()` tracks device orientation. Read their actual
+`get()/subscribe()/stop()` result before wiring a signal adapter. The explicit
+Stacks versions accept different targets/options and return Refs. Include
+permission-denied and unsupported-device behavior, and avoid doing layout work
+on every event when CSS can perform it.
+
+## Forms
+
+Bare `useForm(schema, initialValues?)` selects STX's form implementation. Its
+schema contains STX Validator objects (the `v` builder is an explicit package
+export, not an eager bare global). `form.values.email`, `form.errors.email`,
+touched/dirty/validating records are signal-backed properties;
+`getFieldState(name)`, `validateField(name)`, `validate()` and
+`handleSubmit(handler)` follow that implementation. The explicit
+`@stacksjs/composables` implementation instead takes
+`{ initialValues, schema, onSubmit }` and Stacks `schema.string()` rules.
+Never paste one implementation's options into the other.
+
+## Data and session scope
+
+STX `useQuery` and `useFetch` use callable state and can consume server
+hydration data. `clearServerData(key?)` invalidates consumed server data after
+a mutation. Persisted account state uses `keptState`, `cachedQuery`, and
+`setKeptScope`; establish the signed-in account scope before creating values,
+flush pending writes when appropriate, and forget that scope on sign-out.
+Ordinary localStorage is not account-scoped automatically.
+
+## Verify the actual delivery
+
+Inspect installed STX `runtime-globals`, `signals`, `client-script`,
+`framework-composables`, and `unresolved-identifiers` modules. The retained
+STX tests `framework-composables.test.ts`,
+`framework-composables-dist-layout.test.ts`,
+`forms/use-form-reactive.test.ts` and `signals/client-api-delivery.test.ts`
+check different delivery paths. Stacks' eager alias test covers one path only.

package/ai/skills/stacks-composables/SKILL.md

@@ -1,28 +1,24 @@
 ---
 name: stacks-composables
-description: Use when creating or using reactive composables in STX templates - 154 composables for state management, DOM interaction, sensors, animation, browser APIs, async operations, or the complete list of auto-imported composables. Covers @stacksjs/composables.
+description: Use when choosing or implementing reactive composables in STX, data queries, forms, consent, browser APIs, motion, or debugging client delivery. Covers @stacksjs/composables, STX eager and demand browser delivery, and the difference between callable signals and module Refs.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
 ---
 
-# Stacks Composables
+# Stacks composables
 
-154 reactive composables for STX templates. **A fixed set of them is available
-bare**, listed below; everything else needs an explicit import from
-`@stacksjs/composables`.
+Choose the execution surface before copying a composable signature. An STX
+client script, an explicitly imported `@stacksjs/composables` module, and a
+server script can expose similarly named functions with different contracts.
+Read [BROWSER.md](BROWSER.md) for template delivery, forms and motion examples.
 
-The stx runtime decides this, not `browser-auto-imports.json`. That manifest
-feeds an ambient `.d.ts` and nothing reads it at build time, so it says what the
-compiler accepts and not what the browser has; the two disagree in both
-directions (stacksjs/stacks#2585).
+## Eager window aliases
 
-This page said "All are auto-imported in STX templates", which is the mistake
-`AGENTS.md` carries a scar about under "200+ composables": an agent reaching for
-a name on that authority writes a template that does not run, and reads the
-failure as a framework bug.
-
-## What you can write bare in a template
+The following markers describe only explicit eager `window.name` aliases in
+`getCachedSignalsRuntime()`. They are checked by
+`core/composables/tests/skill-runtime-globals.test.ts`, and are not the whole
+compiler-delivered client surface.
 
 <!-- auto-imported:begin - checked against the stx runtime by
      core/composables/tests/skill-runtime-globals.test.ts. These are the names
@@ -39,176 +35,86 @@ failure as a framework bug.
 
 <!-- auto-imported:end -->
 
-Everything else needs an explicit import, and that is most of what the sections
-below list:
+Additional STX names are exposed through `window.stx` and compiler
+destructuring, or bundled from STX composables on demand. In current STX,
+`useMediaQuery` and `usePreferredReducedMotion` use the first path;
+`useForm`, `useScroll`, `useMouse`, `useParallax`, and
+`useIntersectionObserver` use the demand path. These client-script names do
+not come from the ambient `browser-auto-imports.json` manifest.
+
+## Explicit module imports
+
+The module surface lives in `core/composables/src/index.ts`. Import every
+binding in a TypeScript module even if a template entry can use it bare.
 
 ```ts
-import { useStorage } from '@stacksjs/composables'
-```
+import { useCounter } from '@stacksjs/composables'
 
-**`buddy typecheck` will not tell you which is which, and currently disagrees
-with the browser in both directions** (stacksjs/stacks#2585).
-`storage/framework/browser-auto-imports.json` feeds an ambient `.d.ts`, so the
-compiler accepts every name it declares - and only five of its 27 `use*` are in
-the runtime. `useStorage`, `useNow`, `useDateFormat`, `useForm` and the `use*Store`
-composables typecheck and then throw a ReferenceError during setup, which takes
-the page down rather than failing the one call. In the other direction
-`useLocalStorage`, `useColorMode`, `useCounter` and `useMediaQuery` all work in
-a template and `tsc` rejects them.
-
-The list above is the runtime's, so it is the one that predicts whether the page
-loads.
-
-## Key Path
-- Core package: `storage/framework/core/composables/src/`
-
-## Core Reactive Primitives
-
-```typescript
-// From _shared.ts
-type MaybeRef<T> = T | Ref<T>
-type MaybeRefOrGetter<T> = T | Ref<T> | (() => T)
-unref(val)           // unwrap Ref
-toValue(val)         // unwrap Ref or getter
-isRef(val)           // type guard
+const counter = useCounter(0, { min: 0, max: 10 })
+counter.inc()
+const value = counter.count.value
 ```
 
-## State & Reactivity
-- `useToggle(initial?)` → `[Ref<boolean>, toggle]`
-- `useCounter(initial?)` → `{ count, increment, decrement, set, reset }`
-- `useStepper(steps, initial?)` → step navigation
-- `usePrevious(value)` → previous value
-- `useCycleList(list)` → cycle through items
-
-## Storage
-- `useStorage(key, defaultValue, storage?)` → persistent Ref
-- `useLocalStorage(key, defaultValue)` → localStorage-backed Ref
-- `useSessionStorage(key, defaultValue)` → sessionStorage-backed Ref
-
-## Time & Date
-- `useNow(options?)` → `Ref<Date>` (auto-updating)
-- `useDateFormat(date, format)` → `Ref<string>`
-- `useTimeAgo(date)` → relative time string
-- `useTimestamp(options?)` → `Ref<number>`
-- `useInterval(fn, ms)` → interval control
-- `useIntervalFn(fn, ms)` → interval with pause/resume
-- `useTimeout(ms)` → timeout control
-- `useTimeoutFn(fn, ms)` → delayed execution
-
-## DOM & Browser
-- `useWindowSize()` → `{ width, height }`
-- `useWindowScroll()` → `{ x, y }`
-- `useWindowFocus()` → `Ref<boolean>`
-- `useDocumentVisibility()` → `Ref<string>`
-- `useFullscreen(el?)` → `{ isFullscreen, enter, exit, toggle }`
-- `useTitle(title)` → document title binding
-- `useFavicon(url)` → favicon binding
-- `useCssVar(prop, el?)` → CSS variable binding
-- `useActiveElement()` → currently focused element
-- `useTextSelection()` → selected text
-- `useTextDirection()` → `Ref<'ltr' | 'rtl'>`
-- `useNavigatorLanguage()` → browser language
-
-## Mouse & Touch
-- `useMouse()` → `{ x, y, sourceType }`
-- `useMouseInElement(el)` → mouse position relative to element
-- `useMousePressed()` → `{ pressed, sourceType }`
-- `usePointer()` → pointer events
-- `useSwipe(el)` → swipe detection
-- `usePointerSwipe(el)` → pointer swipe
-- `useDraggable(el)` → make element draggable
-- `useDropZone(el)` → drop zone detection
-- `onLongPress(el, handler)` → long press detection
-- `onClickOutside(el, handler)` → click outside detection
-
-## Sensors
-- `useGeolocation()` → `{ coords, locatedAt, error }`
-- `useDeviceMotion()` → acceleration & rotation
-- `useDeviceOrientation()` → alpha, beta, gamma
-- `useBattery()` → `{ charging, chargingTime, level }`
-- `useDevicePixelRatio()` → `Ref<number>`
-- `useScreenSafeArea()` → safe area insets
-
-## Observers
-- `useIntersectionObserver(el, callback)` → visibility detection
-- `useResizeObserver(el, callback)` → size changes
-- `useMutationObserver(el, callback)` → DOM mutations
-- `useElementBounding(el)` → `{ top, left, width, height }`
-- `useElementVisibility(el)` → `Ref<boolean>`
-- `useElementHover(el)` → `Ref<boolean>`
-
-## Async
-- `useAsyncState(fn, initial)` → `{ state, isReady, isLoading, error, execute }`
-- `useAsyncQueue(tasks)` → sequential async execution
-- `computedAsync(fn)` → async computed value
-- `computedEager(fn)` → immediately evaluated computed
-
-## Network
-- `useFetch(url, options?)` → fetch wrapper with reactive state
-- `useWebSocket(url)` → WebSocket connection
-- `useEventSource(url)` → SSE connection
-- `useOnline()` → `Ref<boolean>` (network status)
-
-## Input & Focus
-- `useFocus(el)` → `{ focused, focus, blur }`
-- `useFocusWithin(el)` → any child focused
-- `useKeyModifier(key)` → modifier key state
-- `usePermission(name)` → permission state
-- `useShare(options)` → Web Share API
-
-## Utilities
-- `useDebounceFn(fn, ms)` → debounced function
-- `useThrottleFn(fn, ms)` → throttled function
-- `useDebouncedRef(ref, ms)` → debounced ref updates
-- `useThrottledRef(ref, ms)` → throttled ref updates
-- `watchDebounced(source, callback, ms)` → debounced watcher
-- `watchThrottled(source, callback, ms)` → throttled watcher
-- `watchOnce(source, callback)` → one-time watcher
-- `whenever(source, callback)` → watch for truthy
-- `until(source).toBe(value)` → wait for value
-- `syncRef(refA, refB)` → bidirectional sync
-
-## Dark Mode
-- `useDark()` → `Ref<boolean>`
-- `usePreferredDark()` → system preference
-- `usePreferredColorScheme()` → color scheme preference
-
-## Media
-- `useMediaQuery(query)` → `Ref<boolean>`
-- `usePreferredContrast()` → contrast preference
-- `usePreferredLanguages()` → language preferences
-- `usePreferredReducedMotion()` → reduce motion preference
-
-## State Patterns
-- `createEventHook()` → typed event hook
-- `createGlobalState(fn)` → shared state across components
-- `createSharedComposable(fn)` → shared composable instance
-- `refDefault(ref, defaultValue)` → ref with default
-- `refAutoReset(value, ms)` → auto-resetting ref
-- `makeDestructurable(obj, arr)` → support both destructuring styles
-- `useIdle(ms)` → user idle detection
-- `usePageLeave()` → detect page leave
-- `useFps()` → frames per second
-- `useMounted()` → `Ref<boolean>` mount state
-- `tryOnMounted(fn)` → safe onMounted
-- `useObjectUrl(blob)` → object URL with auto-cleanup
-
-## Script & Style Injection
-- `useScriptTag(src, onLoaded?)` → inject `<script>`
-- `useStyleTag(css)` → inject `<style>`
-
-## Math
-- `useAbs`, `useAverage`, `useCeil`, `useClamp`, `useFloor`, `useMax`, `useMin`, `usePrecision`, `useRound`, `useSum`, `useTrunc`
-- `and`, `or`, `logicNot`, `logicOr`
+Module composables use object `Ref` values from STX: read/write `.value`,
+subscribe where provided, and use the exported cleanup/control functions.
+Template signals use `count()`, `.set()`, and `.update()`. Passing a callable
+signal into a module helper expecting a `Ref` is not an implicit conversion.
+
+| Task | Explicit module exports |
+|---|---|
+| State/storage | useCounter, useToggle, useStorage, useLocalStorage, history helpers |
+| Async/data | useFetch, createFetch, useQuery, useMutation, createQueryClient, useAsyncState |
+| Forms/consent | useForm, useCookieConsent |
+| DOM/input | useFocus, useEventListener, onClickOutside, observers, useScroll, useMouse |
+| Timing/watch | useIntervalFn, useTimeoutFn, useTimeoutPoll, watchDebounced, watchPausable |
+| Media/device | useMediaQuery, usePreferredReducedMotion, useGeolocation, useDeviceOrientation |
+| Browser facilities | clipboard, permissions, fullscreen, workers, virtual lists, sharing |
+
+Inspect the barrel and the individual implementation for other exports rather
+than installing a second library for a feature Stacks already has.
+
+## Module query cache
+
+`useQuery({ queryKey, queryFn, staleTime, enabled, client })` provides Ref
+data/error/loading state, in-flight deduplication and `refetch()`.
+`queryFn` receives an AbortSignal. `createQueryClient({ gcTime })` provides
+scoped clients, `get`, `set`, `invalidate`, `gc`, and `clear`.
+Invalidation accepts prefix keys or a predicate matcher. Optional
+`refetchOnFocus` and `refetchOnReconnect` refetch stale data. Use
+`unsubscribe()` when the consumer ends. For template runtime queries read
+the STX contract in [BROWSER.md](BROWSER.md); their signatures differ.
+
+## Module forms and consent
+
+Explicit `useForm({ initialValues, schema, onSubmit, validateOn })` accepts
+Stacks validators, exposes Ref values plus `field(name)` accessors, dirty/touched
+state, accessible `inputProps()`, `submitButtonProps()`, and server-error
+`setErrors()`. Apply a returned 422 map explicitly; fetching an error does
+not automatically attach it to a form. Field arrays and a progressive HTML
+fallback are not established by the primitive alone.
+
+`useCookieConsent({ policyVersion, storageKey, onChange })` stores a versioned
+decision. Necessary consent is always enabled; optional categories default to
+declined. `accept`, `acceptAll`, `declineAll`, and `withdraw` change it;
+`allows(category)` gates loading. A changed policy version asks again, blocked
+storage falls back to no stored decision, and returned visitor consent is
+independent of a signed-in session. Import this helper explicitly.
 
 ## Gotchas
-- Only the names listed above are available bare in an STX template, and they
-  come from the stx runtime, not from `browser-auto-imports.json` - that
-  manifest is compile-time only and disagrees with the runtime in both
-  directions (stacksjs/stacks#2585). Everything else needs
-  `import { … } from '@stacksjs/composables'`
-- NEVER use vanilla JS (`var`, `document.*`, `window.*`) in STX `<script>` tags
-- Only use stx-compatible code: signals, composables, directives
-- Auto-imports defined in `storage/framework/browser-auto-imports.json`
-- Many composables require a browser environment (won't work server-side)
-- `useStorage` persists to localStorage by default
+
+- Browser capability availability and permission denial are runtime states,
+  even when a helper imports successfully during SSR.
+- Client observers/listeners need teardown. Read the selected helper's return
+  shape; `stop`, `remove`, and `unsubscribe` are not interchangeable names.
+- Module `useTimeout(ms)` returns a Ref unless controls are requested; browser
+  runtime `useTimeout(callback, delay)` runs a callback. Module counter methods
+  are `inc`/`dec`, never `increment`/`decrement`.
+- Typechecking an ambient name proves neither its delivery nor its contract.
+  Exercise a rendered template with the installed STX version.
+
+## Source and evidence
+
+`core/composables/src/index.ts`, individual source files, and retained
+`tests/use-query.test.ts`, `tests/use-form.test.ts`,
+`tests/use-cookie-consent.test.ts` and `tests/skill-runtime-globals.test.ts`
+are authoritative (core paths relative to `storage/framework/`).