@stacksjs/defaults 0.75.109 → 0.75.111

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

@@ -73,10 +73,10 @@ Database.fromEnv()                  // From env vars (DB_CONNECTION, DB_DATABASE
 
 ## Global `db` Instance (utils.ts)
 
-The `db` export is a **lazy Proxy** that auto-initializes on first property access:
-1. At module load: reads env vars via `@stacksjs/env`, calls `setConfig()` on bun-query-builder
-2. Background: attempts `import('@stacksjs/config')` to override with app config
-3. On first property access: calls `createQueryBuilder()` from bun-query-builder
+The db export is a lazy runtime facade. It initializes the query builder on use
+and resolves application configuration through ensureDatabaseConfigLoaded.
+Use @stacksjs/database/runtime for the narrow query/transaction entry; the
+package root additionally exports migrations, seeders and driver tooling.
 
 ```typescript
 import { db } from '@stacksjs/database'
@@ -161,73 +161,74 @@ interface PostgresConfig { name: string, host?: string, port?: number, username?
 interface DynamoDbConfig { key: string, secret: string, region?: string, prefix?: string, endpoint?: string, tableName?: string, singleTable?: { enabled?, pkAttribute?, skAttribute?, entityTypeAttribute?, keyDelimiter?, gsiCount? } }
 ```
 
-## Migrations (migrations.ts)
-
-### Migration Functions
-- `runDatabaseMigration(): Promise<Result<string, Error>>` -- ensures DB exists (postgres/mysql), configures QB, preprocesses SQLite migrations, then calls `qbExecuteMigration()`
-- `resetDatabase(): Promise<Result<string, Error>>` -- drops framework tables (OAuth, passkeys, jobs, etc.) then calls `qbResetDatabase()`
-- `generateMigrations(): Promise<Result<string, Error>>` -- compares models to DB state, generates `.sql` diff files
-- `generateMigrations2(): Promise<Result<string, Error>>` -- full regeneration ignoring previous state (`{ full: true }`)
-
-### SQLite Migration Preprocessing
-Before running migrations on SQLite, `preprocessSqliteMigrations()`:
-1. Rewrites `ALTER TABLE ADD CONSTRAINT` to no-ops (SQLite does not support this)
-2. Rewrites `CREATE UNIQUE INDEX` to no-ops (redundant when table already has inline UNIQUE)
-3. Filters out `DROP COLUMN` for non-existent columns (checks via `PRAGMA table_info`)
-
-### Framework Tables Dropped on Reset
-`oauth_refresh_tokens`, `oauth_access_tokens`, `oauth_clients`, `passkeys`, `failed_jobs`, `jobs`, `notifications`, `password_reset_tokens`
-
-## Seeding (seeder.ts)
-
-### Seed Functions
-- `seed(config?: SeederConfig): Promise<SeedSummary>` -- loads models from both `storage/framework/defaults/app/Models/` (recursive) and `app/Models/` (flat), user models override defaults by name
-- `seedModel$(modelName, options?): Promise<SeedResult>` -- seed one model by name
-- `freshSeed(config?): Promise<SeedSummary>` -- calls `seed({ ...config, fresh: true })` (truncates before seeding)
-- `listSeedableModels(): Promise<Array<{ name, table, count, source: 'default' | 'user' }>>` -- list without seeding
-- `runApplicationSeeders(config?): Promise<ApplicationSeederSummary>` -- runs `database/seeders` classes in deterministic relative-path order
-- `Seeder` -- abstract base class for idempotent application bootstrap seeders
-
-### SeederConfig
-```typescript
-interface SeederConfig {
-  modelsDir?: string     // defaults to path.userModelsPath()
-  defaultCount?: number  // default 10
-  verbose?: boolean      // default true
-  fresh?: boolean        // truncate tables first
-  only?: string[]        // specific models to seed
-  except?: string[]      // models to exclude
-}
-```
-
-### Seeding Behavior
-- Models must have `traits.useSeeder` (or `traits.seedable`) set to `true` or `{ count: N }`
-- Attributes with `factory: (faker) => ...` generate fake data via `@stacksjs/faker`
-- Password fields are auto-detected (by name pattern or `hidden: true` + name includes "pass") and hashed with bcrypt
-- Field names are converted from camelCase to snake_case for DB columns
-- Records inserted in batches of 100
-- Models sorted by dependency: User (0), Team (1), Project (2), everything else (10)
-- Missing tables are skipped gracefully
-- `buddy seed` and `buddy migrate:fresh --seed` also run application seeders after model factories
-- Application seeder modules must default-export a class extending `Seeder` and implement `run()`
-- Application seeders are for idempotent bootstrap work that does not belong in model factories, such as an initial workspace or role assignment
-
-```typescript
-// database/seeders/OwnerSeeder.ts
+## Model-driven migrations
+
+Change the model, generate migrations, review the resulting SQL, then migrate.
+The native runner loads application config, selects the dialect corpus, handles
+feature-gated migration resources, and acquires the migration lock. It returns
+a Result; inspect failures rather than treating a resolved call as success.
+RunDatabaseMigration, generateMigrations and resetDatabase are exported tooling,
+but their CLI actions supply the application's operation policy and environment.
+
+Read stacks-migrations before using full regeneration, snapshot recovery,
+preprocessing or destructive fresh/reset commands. SQLite preprocessing and
+provider-specific DDL rules are implemented in core/database/src/migrations.ts;
+installed package sources are copied before their SQL is rewritten.
+The migration ledger and snapshot are different state, not interchangeable
+proof that a table exists.
+
+## Model factories and application seeders
+
+Models opt into the factory pass with traits.useSeeder/seedable. Attribute
+factories receive faker and the attributes generated so far; column names are
+converted to snake_case, and password fields are hashed by the seeder's bcrypt
+path. The source defines factory fallback behavior: a failed factory can use
+its attribute default, so inspect the summary and warnings as well as row count.
+
+seed(options?) returns a SeedSummary; seedModel$(name, options?) targets one
+model; freshSeed truncates before generation; listSeedableModels inspects the
+available definitions; makeModelRecords produces factory data without insertion.
+These are public exports from @stacksjs/database.
+
+When app/Models has user models, the default seed pass uses those definitions.
+includeDefaults explicitly merges framework defaults; an app with no user models
+uses defaults as fallback. User identity overrides a default even when the app
+model opts out of seeding. The current model-seeder app scan is flat, unlike
+recursive model resolution elsewhere; verify nested models at this seam.
+
+Options also include only/except, defaultCount, fresh, append, allowProtected,
+attachAccounts and includeDefaults. Default non-empty tables are skipped;
+append is explicit. Protected auth/OAuth data and attachment to existing accounts
+have their own guards because fixture generation can alter live credentials or
+associate invented records with real people. Read buddy seed --help and inspect
+the target connection before requesting a destructive or bypassing mode.
+
+Application seeders default-export a class extending the native Seeder:
+
+~~~ts
 import { Seeder } from '@stacksjs/database'
 
-export default class OwnerSeeder extends Seeder {
+export default class WorkspaceSeeder extends Seeder {
+  static override order = 10
+  static override tags = ['deploy']
+
   async run(): Promise<void> {
-    // Resolve existing records first, then create only what is missing.
+    // Find the application's existing workspace before creating missing state.
   }
 }
-```
+~~~
 
-### SeedResult / SeedSummary
-```typescript
-interface SeedResult { model: string, table: string, count: number, success: boolean, error?: string, duration: number }
-interface SeedSummary { total: number, successful: number, failed: number, results: SeedResult[], duration: number }
-```
+runApplicationSeeders applies order (lower first), then relative path for ties.
+Tag/only/except selection lets deploy bootstrap remain separate from a large demo
+corpus. Buddy seed and migrate:fresh --seed run the model and application passes;
+model dependencies determine parent-first generation rather than a hard-coded
+User/Team/Project order. fresh empties in reverse dependency order.
+
+Source: storage/framework/core/database/src/seeder.ts and
+core/buddy/src/commands/seed.ts. Retained seeder tests cover override opt-out,
+dependency order, protected models and non-empty/append behavior. See
+stacks-models for fixtures/factory declarations and stacks-testing for factories
+that produce test records.
 
 ## Validator Type Guards (validators.ts)
 `isStringValidator`, `isNumberValidator`, `enumValidator`, `isBooleanValidator`, `isDateValidator`, `isUnixValidator`, `isFloatValidator`, `isDatetimeValidator`, `isTimestampValidator`, `isTimestampTzValidator`, `isDecimalValidator`, `isSmallintValidator`, `isIntegerValidator`, `isBigintValidator`, `isBinaryValidator`, `isBlobValidator`, `isJsonValidator`
@@ -280,7 +281,7 @@ SQLite's SQL on a Turso or `sqld` server. Configure `TURSO_DATABASE_URL`
 ## config/database.ts Shape
 ```typescript
 {
-  default: env.DB_CONNECTION || 'mysql',
+  default: env.DB_CONNECTION || 'sqlite',
   connections: { sqlite, turso, mysql, singlestore, vitess, postgres, dynamodb },
   migrations: 'migrations',
   migrationLocks: 'migration_locks',
@@ -326,8 +327,8 @@ SQLite's SQL on a Turso or `sqld` server. Configure `TURSO_DATABASE_URL`
 ```
 
 ## Gotchas
-- The actual default driver in `config/database.ts` is `'mysql'` (not `'sqlite'`), but `utils.ts` and `driver-config.ts` fall back to `'sqlite'` when `DB_CONNECTION` is unset
-- The `db` export is a lazy Proxy -- it auto-initializes on first property access, which means errors are deferred until first use
+- Default connection is SQLite in the shipped config; inspect application config and DB_CONNECTION before choosing a driver
+- The db facade initializes lazily; invalid connection configuration may surface at first query use
 - Query builder config lives in `config/query-builder.ts`, and reads `DB_CONNECTION` / `DB_*` from the env - it is not a second copy of `config/database.ts`
 - The `.qb/` directory at project root stores query builder state for migration diffing
 - `resetDatabase()` drops ALL tables including framework tables (OAuth, passkeys, jobs, etc.) -- only use in development
@@ -343,3 +344,32 @@ SQLite's SQL on a Turso or `sqld` server. Configure `TURSO_DATABASE_URL`
   and generated `useApi` routes apply the trait-aware scope themselves.
 - Transaction defaults: 2 retries, `read committed` isolation, with exponential backoff + jitter
 - The ORM lives in TWO locations: `storage/framework/core/orm/` (package) and `storage/framework/orm/` (implementation)
+
+
+## Driver conformance and topology
+
+Read `storage/framework/core/config/src/capabilities.ts` before selecting a
+driver. SQLite, MySQL and PostgreSQL have retained supported contracts. MySQL
+and PostgreSQL need migrations generated for their dialect: the shipped SQLite
+SQL corpus is not a portable migration bundle. SingleStore, Vitess and Turso
+are experimental with explicit service/topology limits. DynamoDB helpers are a
+separate entity API and cannot be selected as the SQL/ORM default.
+
+Turso's libsql alias shares SQLite rendering, but uses remote Hrana transport.
+Transactions must write through the tx handle; no embedded replicas or native
+file backup are provided. Scheduler locks remain per host. Read the registry's
+provider versions and retained evidence rather than equating an available adapter
+with an unrestricted supported service.
+
+
+## SQL fragments and temporal values
+
+Parameterized sql fragments are compiled through the query builder; do not
+extract .sql/.parameters and feed question marks directly to PostgreSQL unsafe.
+whereRaw does not accept bound-value fragments on that path. Use typed where
+or dialect-aware raw helpers. sql.as validates an alias; raw text remains a
+trusted-code operation. sqlDateTime/parseSqlDateTime provide the canonical
+application timestamp representation. Mixing SQLite datetime text with
+application ISO text in raw comparisons can give wrong expiry boundaries.
+Source: core/database/src/types.ts and sql-helpers.ts; see stacks-query-builder
+for typed tables, raw binding, transaction handles and replica routing.

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

@@ -25,9 +25,9 @@ export { format as dateFormat } from './format'  // convenience alias
 ```
 
 Three source files:
-- `now.ts` — `DateTime` class and `now()` helper
-- `format.ts` — standalone `format()` function with token-based formatting and timezone support
-- `parse.ts` — standalone `parse()` function with token-based parsing
+- `now.ts` - `DateTime` class and `now()` helper
+- `format.ts` - standalone `format()` function with token-based formatting and timezone support
+- `parse.ts` - standalone `parse()` function with token-based parsing
 
 ## DateTime Class (`now.ts`)
 
@@ -122,6 +122,9 @@ Implementation details:
 - `addSeconds/Minutes/Hours` use millisecond arithmetic on timestamp
 - `addDays` uses `Date.setDate()` (handles month boundaries correctly)
 - `addMonths` uses `Date.setMonth()` (handles year boundaries)
+- Month/year arithmetic inherits native overflow behavior. For a business
+  calendar month that must clamp January 31 to February's last day, use the
+  exported `addCalendarMonths(date, count, { utc? })` helper instead.
 - `addYears` uses `Date.setFullYear()`
 - All `sub*` methods delegate to `add*(-n)`
 
@@ -229,7 +232,9 @@ parse('2024-06-15 10:30 +0530', 'YYYY-MM-DD HH:mm Z') // Date with timezone offs
 **Without format string**:
 - Date-only ISO strings (YYYY-MM-DD) are parsed as LOCAL time, not UTC -- this is a deliberate fix for the native Date behavior where `new Date('2024-06-15')` treats it as UTC causing day shifts
 - All other strings use native `new Date()` parsing
-- Throws on invalid dates
+- Rejects unparseable native dates. Calendar fields can normalize through native
+  Date, so use validation for strict rejection of impossible dates such as
+  February 31 rather than treating this parser as a validation boundary.
 
 **With format string**:
 - Builds a regex from the format tokens and extracts named groups
@@ -240,7 +245,18 @@ parse('2024-06-15 10:30 +0530', 'YYYY-MM-DD HH:mm Z') // Date with timezone offs
 - Z token: parses +HHMM offset, constructs UTC time and adjusts
 - Throws if the format doesn't match the input string
 
-## `now()` Helper
+## Named-zone instants and calendar months
+
+The root additionally exports `zoneOffsetMinutes(instant, timeZone)`,
+`zonedTimeToUtc(wallClock, timeZone)`, `isoInZone(instant, timeZone)` and
+`addCalendarMonths(date, count, { utc? })`. A wall-clock string has no supplied
+offset; the named IANA zone converts it into an instant. `isoInZone` retains
+that zone's offset in serialized output rather than merely displaying a date.
+Review `zone.ts` and its DST behavior when ambiguous/gap local times matter.
+`addCalendarMonths` clones and clamps the day; ordinary `DateTime.addMonths`
+preserves native Date overflow instead. Do not interchange those contracts.
+
+## Current-time helper example
 
 ```typescript
 import { now } from '@stacksjs/datetime'

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-deploy
-description: Use when deploying a Stacks application - picking a deploy target (AWS, Hetzner, or a host you own over SSH), the deployment workflow (build → deploy), pre/post deploy hooks, server vs serverless mode selection, first-time deployment setup, rollback, deployment troubleshooting, or the buddy deploy command. For cloud infrastructure details (EC2, Lambda, CloudFormation, Route53, IAM, rpx, systemd), see stacks-cloud.
+description: Use when deploying a Stacks application - picking a deploy target (AWS, Hetzner, or a host you own over SSH), the deployment workflow (build → deploy), pre/post deploy hooks, server vs serverless mode selection, first-time deployment setup, rollback, deployment troubleshooting, or the buddy deploy command. For cloud infrastructure details (EC2, Lambda, CloudFormation, Route53, IAM, rpx, systemd), see stacks-cloud. Covers buddy deploy, config/cloud.ts, provider previews, release and rollback.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript, AWS / Hetzner / any 64-bit Debian or Ubuntu host over SSH
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -214,3 +214,19 @@ buddy cloud:cleanup           # clean retained resources
 - A failover replica bucket (`infrastructure.storage.<name>.failover`) lives outside the stack, so
   `buddy cloud:remove` leaves it, and its data, behind on purpose
 - For infrastructure details, see the `stacks-cloud` skill
+
+
+## Evidence and infrastructure contract
+
+`core/config/src/capabilities.ts` marks the Hetzner and adopted SSH targets
+experimental: their retained SSH-target tests do not prove live rollback/provider
+conformance. AWS and Fly have runtime paths outside that registry's retained
+deploy matrix; do not infer either supported or unsupported from their absence.
+Read the actual deploy branch, preview and provider tests before claiming parity.
+
+`config/cloud.ts` distinguishes the named tsCloud object (provider,
+infrastructure, environments, sites) from the default Stacks wrapper. Follow the
+installed file's shape rather than moving tsCloud settings into an unrelated
+flat object. A cloud SQS queue definition does not implement QUEUE_DRIVER=sqs
+in the Stacks queue package. Previews, destructive removal, secret writes and
+provider mutations need the user's existing task authorization.

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

@@ -53,7 +53,7 @@ Typography is the primary structural and decorative infrastructure. Imagery is s
 ## 4. Color System
 The color architecture is uncompromising. Gradients, soft drop shadows, and modern translucency are strictly prohibited. Colors simulate physical media or primitive emissive displays.
 
-**CRITICAL: Choose ONE substrate palette per project and use it consistently. Never mix light and dark substrates within the same interface.** Expose these as Crosswind theme tokens in `config/ui.ts`.
+**CRITICAL: Choose ONE substrate palette per project and use it consistently. Never mix light and dark substrates within the same interface.** Expose these as Crosswind theme tokens in `config/css.ts`.
 
 ### If Swiss Industrial Print (Light)
 - **Background:** `#F4F4F0` or `#EAE8E3` (matte, unbleached documentation paper).

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

@@ -43,7 +43,7 @@ Color is a scarce resource, used only for semantic meaning or subtle accents.
   - Pale Green: `#EDF3EC` (Text: `#346538`)
   - Pale Yellow: `#FBF3DB` (Text: `#956400`)
 
-Expose these as Crosswind theme tokens or CSS custom properties in `config/ui.ts` so dark mode (`dark:` + `useColorMode()` / `useDark()`) stays consistent.
+Expose these as Crosswind theme tokens or CSS custom properties in `config/css.ts` so dark mode (`dark:` + `useColorMode()` / `useDark()`) stays consistent.
 
 ## 5. Component Specifications
 - Bento Box Feature Grids:
@@ -94,11 +94,25 @@ Motion should feel invisible: present but never distracting. Quiet sophisticatio
 <script client>
   const block = useRef('block')
   const shown = state(false)
-  useIntersectionObserver(block, (e) => { if (e[0].isIntersecting) shown.set(true) }, { threshold: 0.2 })
+  const reduce = usePreferredReducedMotion()
+  let stopObserving: (() => void) | undefined
+  onMount(() => {
+    if (reduce()) {
+      shown.set(true)
+      return
+    }
+    const observer = useIntersectionObserver(
+      () => block.current,
+      entry => { if (entry.isIntersecting) shown.set(true) },
+      { threshold: 0.2, once: true },
+    )
+    stopObserving = () => observer.stop()
+  })
+  onDestroy(() => stopObserving?.())
 </script>
 
 <section ref="block"
-         :class="shown() ? 'translate-y-0 opacity-100' : 'translate-y-3 opacity-0'"
+         :class="shown() || reduce() ? 'translate-y-0 opacity-100' : 'translate-y-3 opacity-0'"
          class="duration-[600ms] ease-[cubic-bezier(0.16,1,0.3,1)] transition-all">
   <slot />
 </section>

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

@@ -113,13 +113,25 @@ Stacks ships no animation library. Do NOT import `motion/react`, `gsap`, or `fra
 <script client>
   const card = useRef('reveal')
   const shown = state(false)
-  useIntersectionObserver(card, (entries) => {
-    if (entries[0].isIntersecting) shown.set(true)
-  }, { threshold: 0.2 })
+  const reduce = usePreferredReducedMotion()
+  let stopObserving: (() => void) | undefined
+  onMount(() => {
+    if (reduce()) {
+      shown.set(true)
+      return
+    }
+    const observer = useIntersectionObserver(
+      () => card.current,
+      entry => { if (entry.isIntersecting) shown.set(true) },
+      { threshold: 0.2, once: true },
+    )
+    stopObserving = () => observer.stop()
+  })
+  onDestroy(() => stopObserving?.())
 </script>
 
 <div ref="reveal"
-     :class="shown() ? 'translate-y-0 blur-0 opacity-100' : 'translate-y-16 blur-md opacity-0'"
+     :class="shown() || reduce() ? 'translate-y-0 blur-0 opacity-100' : 'translate-y-16 blur-md opacity-0'"
      class="duration-[800ms] ease-[cubic-bezier(0.32,0.72,0,1)] transition-all">
   <slot />
 </div>

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

@@ -94,7 +94,7 @@ The React skill's "reach for Fluent / Carbon / Material / shadcn" advice does **
 
 | Layer | What to use | Notes |
 |---|---|---|
-| Components | **Stacks UI** (`@stacksjs/ui`) | Headless primitives (Combobox, Dialog/Modal, Menu, Tabs, Switch, RadioGroup, Popover, Disclosure, Transition) plus **Craft native components** (`craft-button`, `craft-text-input`, `craft-textarea`, `craft-checkbox`, `craft-select`, `craft-modal`). See [stacks-ui](../stacks-ui). |
+| Components | **Stacks UI** (`@stacksjs/ui/components`) | Typed component exports backed by `@stacksjs/components`; STX tags resolve through the configured component plugin. Native applications use the mobile/desktop bridges and components appropriate to their host. See [stacks-ui](../stacks-ui). |
 | Styling | **Crosswind** utilities | Tailwind-compatible syntax, `dark:` variant, arbitrary values. See [stacks-crosswind](../stacks-crosswind). |
 | Icons | **Iconify** `i-{collection}-{name}` | hugeicons default. See Section 3.C. |
 | Templating | **stx** SFC | `<script>` / `<template>` / `<style>`. See [stacks-stx](../stacks-stx). |
@@ -137,7 +137,7 @@ Unless the design read pulls in an aesthetic-specific companion, these are the d
 ### 3.B State & Reactivity
 * Local reactive state uses signals: `state(initial)` (read `count()`, write `count.set(v)` / `count.update(n => n + 1)`), `derived(() => ...)` for computed, `effect(() => ...)` for side effects. Element refs use `useRef('name')`.
 * Translation from React if you are porting: `useState` -> `state`, `useMemo` -> `derived`, `useEffect` -> `effect`, `useRef` -> `useRef`.
-* **NEVER drive continuous values (mouse position, scroll progress, pointer physics, magnetic hover) through a signal you re-read every frame.** Writing signal state on every pointer or scroll frame re-runs reactive effects and collapses on mobile. Instead drive a **CSS custom property** from inside an `effect` (Section 5.D) or let CSS scroll-driven animations do the work with no script at all.
+* **NEVER drive continuous values (mouse position, scroll progress, pointer physics, magnetic hover) through a signal you re-read every frame.** Writing signal state on every pointer or scroll frame re-runs reactive effects and collapses on mobile. Instead drive a **CSS custom property** from in its subscription callback (Section 5.D) or let CSS scroll-driven animations do the work with no script at all.
 
 ### 3.C Icons
 * **Use Iconify utility classes.** stx ships 200K+ Iconify icons as classes: `<i class="i-hugeicons-{name}"></i>`, or any collection `i-{collection}-{name}` (`i-ph-arrow-right`, `i-tabler-check`). Size and color with Crosswind: `class="h-6 w-6 text-gray-500 i-hugeicons-book-open"`.
@@ -335,11 +335,11 @@ These are tools, not defaults. Use them when the design read calls for them. **N
 
 **Stacks ships NO motion library.** There is no `motion/react`, no `framer-motion`, no `gsap`. All motion is built from three sources only:
 1. **Crosswind transitions + CSS keyframes** in a `<style>` block (hover, micro-interactions, load-ins). Animate ONLY `transform` and `opacity`.
-2. **stx composables** for observing state (`useIntersectionObserver`, `useElementVisibility`, `useMouse`, `useMediaQuery`, `useResizeObserver`, `useWindow`, `useDeviceOrientation`) - toggle a Crosswind class or set a CSS custom property.
+2. **stx composables** for observing state (`useIntersectionObserver`, `useElementVisibility`, `useMouse`, `useMediaQuery`, `useResizeObserver`, `useWindowSize`, `useDeviceOrientation`) - toggle a Crosswind class or set a CSS custom property.
 3. **CSS scroll-driven animations** (`animation-timeline: view()` / `scroll()`) for pinned, stacked, and horizontal-pan effects - no script needed.
 
 * **Glassmorphism:** Appropriate for premium consumer, Apple-adjacent, luxury, or media-overlay vibes. Inappropriate for dashboards, public-sector, "boring B2B." When used, go beyond `backdrop-blur`: add a 1px inner border (`border-white/10`) and a subtle inner shadow for physical edge refraction. Provide a solid-fill fallback under `prefers-reduced-transparency` (Appendix C).
-* **Magnetic Micro-physics:** Use when `MOTION_INTENSITY > 5` AND the brief reads premium / playful / agency. Implement by driving a **CSS custom property** from `useMouse()` inside an `effect` (Section 5.D). Never through per-frame signal state. See Section 3.B.
+* **Magnetic Micro-physics:** Use when `MOTION_INTENSITY > 5` AND the brief reads premium / playful / agency. Implement by driving a **CSS custom property** from `useMouse()` in its subscription callback (Section 5.D). Never through per-frame signal state. See Section 3.B.
 * **Perpetual Micro-Interactions** (Pulse, Typewriter, Float, Shimmer, Carousel): Use when `MOTION_INTENSITY > 5` AND the section actively benefits from motion (status indicators, live feeds). **Not every card needs an infinite loop.** If a section is informational, leave it still. Prefer spring-like `cubic-bezier` easing over linear.
 * **"Motion claimed, motion shown."** If `MOTION_INTENSITY > 4`, the page must actually move: entry transitions on hero, scroll-reveal on key sections, hover feedback on CTAs, at minimum. A static page that claims `MOTION_INTENSITY: 7` is broken. Conversely, if you cannot ship working motion in scope, drop the dial to 3 and ship a clean static page. Never half-build motion that breaks (jumpy enters, missing observer cleanups).
 * **MOTION MUST BE MOTIVATED (mandatory).** Before adding any animation, ask: "what does this communicate?" Valid answers: hierarchy, storytelling (sequenced reveal matching a narrative), feedback (acknowledging an action), state transition. Invalid answer: "it looked cool." Each scroll-driven section, each marquee, each pinned section needs a reason. If you cannot articulate it in one sentence, drop the animation.
@@ -444,14 +444,23 @@ For simple "items appear as they enter viewport" (no pinning), use `useIntersect
   const listRef = useRef('reveal-list')
   const reduce = useMediaQuery('(prefers-reduced-motion: reduce)')
 
-  // reveal each child when the container enters the viewport
-  const { isVisible } = useIntersectionObserver(listRef, { threshold: 0.3 })
-
-  // toggle the class once, on enter (never write signal state per scroll frame)
-  effect(() => {
-    if (reduce() || isVisible())
-      listRef.value?.classList.add('is-revealed')
+  let stopObserving: (() => void) | undefined
+  onMount(() => {
+    if (reduce()) {
+      listRef.current?.classList.add('is-revealed')
+      return
+    }
+    const observer = useIntersectionObserver(
+      () => listRef.current,
+      entry => {
+        if (entry.isIntersecting)
+          listRef.current?.classList.add('is-revealed')
+      },
+      { threshold: 0.3, once: true },
+    )
+    stopObserving = () => observer.stop()
   })
+  onDestroy(() => stopObserving?.())
 </script>
 
 <template>
@@ -485,28 +494,36 @@ For simple "items appear as they enter viewport" (no pinning), use `useIntersect
 
 Use this for: feature lists, testimonial grids, logo walls, anything that just needs "enter on scroll." The observer flips ONE class; the stagger is pure CSS via `--i`. Under reduced motion items are visible immediately.
 
-### 5.D Pointer / Magnetic - Canonical Skeleton (useMouse -> CSS custom property inside an effect)
+### 5.D Pointer / Magnetic - Canonical Skeleton (useMouse subscription -> CSS custom property)
 
-Track the pointer with `useMouse()` and write the offset to a **CSS custom property** inside an `effect`. The property drives a `transform` in CSS. Signal state is read, never written per frame; the reactive tree does not re-run on every pointer move.
+The STX demand-delivered `useMouse()` returns get/subscribe/stop, not callable
+x/y signals. Subscribe to pointer state and write a CSS custom property. CSS
+applies the transform; the template reactive tree does not rerun on each move.
 
 ```html
 <!-- resources/components/magnetic.stx -->
 <script client>
   const btnRef = useRef('magnet')
-  const { x, y } = useMouse()
   const reduce = useMediaQuery('(prefers-reduced-motion: reduce)')
+  let stopTracking: (() => void) | undefined
 
-  effect(() => {
-    const el = btnRef.value
-    if (!el || reduce())
+  onMount(() => {
+    if (reduce())
       return
-    const r = el.getBoundingClientRect()
-    // pull toward cursor, damped; write to a CSS var, do NOT set signal state
-    const dx = (x() - (r.left + r.width / 2)) * 0.2
-    const dy = (y() - (r.top + r.height / 2)) * 0.2
-    el.style.setProperty('--mx', `${dx}px`)
-    el.style.setProperty('--my', `${dy}px`)
+    const mouse = useMouse()
+    const unsubscribe = mouse.subscribe(({ x, y }) => {
+      const el = btnRef.current
+      if (!el || reduce())
+        return
+      const rect = el.getBoundingClientRect()
+      const dx = (x - (rect.left + rect.width / 2)) * 0.2
+      const dy = (y - (rect.top + rect.height / 2)) * 0.2
+      el.style.setProperty('--mx', `${dx}px`)
+      el.style.setProperty('--my', `${dy}px`)
+    })
+    stopTracking = () => { unsubscribe(); mouse.stop() }
   })
+  onDestroy(() => stopTracking?.())
 </script>
 
 <template>
@@ -527,14 +544,17 @@ Track the pointer with `useMouse()` and write the offset to a **CSS custom prope
 </style>
 ```
 
-Critical points: `useMouse()` values are read inside `effect`, the effect sets a CSS custom property, and CSS applies the `transform`. No per-frame signal writes, no `window` listeners, no `requestAnimationFrame` loop touching state.
+Critical points: subscribe to the delivered mouse contract, update CSS custom
+properties, and clean up the tracker. Imported `@stacksjs/composables` mouse
+helpers have a different Ref contract; read stacks-composables/BROWSER.md before
+substituting one. No per-frame template signal writes or global listeners.
 
 ### 5.E Forbidden Animation Patterns
 
 * **`window.addEventListener('scroll', ...)`** is banned. It runs on every scroll frame, jank-prone, no batching. Use `useIntersectionObserver` / `useElementVisibility`, or CSS scroll-driven animations (`animation-timeline: view()` / `scroll()`).
-* **Any bare `window.*` or `document.*` access in an stx `<script>`** is banned (CLAUDE.md rule). Use composables (`useEventListener`, `useWindow`, `useResizeObserver`, `useMouse`) instead. Also banned: `var`.
-* **Custom scroll-progress calculations written into signal state.** Re-runs reactive effects on every frame. Drive a CSS custom property inside an `effect` (Section 5.D) or use a CSS `scroll()` timeline instead.
-* **`requestAnimationFrame` loops that write signal state.** Same reason. Prefer CSS-driven animation or a single CSS custom property write per frame from within an `effect`.
+* **Any bare `window.*` or `document.*` access in an stx `<script>`** is banned (CLAUDE.md rule). Use composables (`useEventListener`, `useWindowSize`, `useResizeObserver`, `useMouse`) instead. Also banned: `var`.
+* **Custom scroll-progress calculations written into signal state.** Re-runs reactive effects on every frame. Drive a CSS custom property in its subscription callback (Section 5.D) or use a CSS `scroll()` timeline instead.
+* **`requestAnimationFrame` loops that write signal state.** Same reason. Prefer CSS-driven animation or a single CSS custom property write per frame from within its subscription callback.
 * **Staggered orchestration:** use the CSS cascade (`transition-delay: calc(var(--i) * 60ms)` / `animation-delay`) for reveal sequence, as in Section 5.C. Do not spin up a JS timer per item.
 
 ---
@@ -669,7 +689,7 @@ These patterns came out of real LLM-generated landing-page tests. Treat them as
 * **NO decorative colored status dots on every list/nav/badge.** A colored dot before "ONE Q4 SLOT OPEN" or before every nav link is banned by default. Acceptable only when the dot conveys actual semantic state (server status, availability flag) and is used sparingly.
 
 **Em-dashes & typography flourishes**
-* **NO em-dash (`—`) as a design element OR anywhere else.** See Section 9.G below for the complete, non-negotiable ban. The em-dash character is forbidden in headlines, eyebrows, pills, body copy, quotes, attribution, captions, button text, and alt text. Use the regular hyphen (`-`).
+* **NO em-dash (`-`) as a design element OR anywhere else.** See Section 9.G below for the complete, non-negotiable ban. The em-dash character is forbidden in headlines, eyebrows, pills, body copy, quotes, attribution, captions, button text, and alt text. Use the regular hyphen (`-`).
 * **NO `<br>`-broken-and-italicized headlines** as a default "design move." Headlines should read naturally first, get clever only when the brief demands it.
 * **NO vertical rotated text** ("INDEX OF WORK" rotated 90 degrees). Agency-portfolio cliche. Use it only when the brief is explicitly agency / Awwwards / experimental AND it serves a real composition purpose.
 * **NO crosshair / hairline grid lines as decoration.** Vertical and horizontal lines drawn just to make the page "feel designed" are banned. Use them only when they organize real content.
@@ -707,19 +727,19 @@ These patterns came out of real LLM-generated landing-page tests. Treat them as
 
 ### 9.G EM-DASH BAN (the single most-violated Tell)
 
-**Em-dash (`—`) is COMPLETELY banned.** It is the LLM's signature stylistic crutch and the #1 visual Tell in production tests. There is no "limited use" allowance, no "natural language frequency" allowance, no "in body copy is fine" allowance. None.
+**Em-dash (`-`) is COMPLETELY banned.** It is the LLM's signature stylistic crutch and the #1 visual Tell in production tests. There is no "limited use" allowance, no "natural language frequency" allowance, no "in body copy is fine" allowance. None.
 
 * **Banned in headlines.** Use a period or a comma.
 * **Banned in eyebrows / labels / pills / button text / image captions / nav items.** Replace with line breaks, columns, or hairlines.
 * **Banned in body copy.** Restructure the sentence: two sentences with a period, OR a comma, OR parentheses, OR a colon.
 * **Banned in quote attribution.** Use a normal hyphen with spaces (`-`) or a line break + smaller-weight name.
-* **Banned in en-dash form too (`–`) when used as a separator.** Date ranges (`2018-2026`) use a hyphen. Number ranges (`40-80k`) use a hyphen.
+* **Banned in en-dash form too (`-`) when used as a separator.** Date ranges (`2018-2026`) use a hyphen. Number ranges (`40-80k`) use a hyphen.
 
 The ONLY permitted dash characters on the page are:
 * Regular hyphen `-` (for compound words, ranges, line dividers in markup)
 * Minus sign in math (`-5C`)
 
-If your output contains a single `—` or `–` anywhere visible to the user, the output fails the Pre-Flight Check and must be rewritten.
+If your output contains a single `-` or `-` anywhere visible to the user, the output fails the Pre-Flight Check and must be rewritten.
 
 This rule is non-negotiable. The agent has historically ignored em-dash limits when phrased as "use sparingly." The phrasing here is binary: zero em-dashes.
 
@@ -773,7 +793,7 @@ This is a vocabulary. Know these pattern names to communicate about them and rea
 * **Crosswind transitions + CSS keyframes** - default for hover, micro-interactions, load-ins.
 * **`useIntersectionObserver` / `useElementVisibility`** - enter-on-scroll, toggle a class (Section 5.C).
 * **CSS scroll-driven animations** (`animation-timeline: view()` / `scroll()`) - pinned, stacked, horizontal-pan (Sections 5.A, 5.B).
-* **`useMouse()` -> CSS custom property in an `effect`** - pointer / magnetic / tilt (Section 5.D).
+* **`useMouse()` -> CSS custom property in its subscription callback** - pointer / magnetic / tilt (Section 5.D).
 * **NEVER import `motion/react`, `framer-motion`, or `gsap`.** Stacks ships none of them, and per-frame signal state fights the reactive system.
 
 ---
@@ -863,7 +883,7 @@ Run this matrix before outputting code. This is the last filter.
 - [ ] **Dial values** explicit and reasoned from the brief, not silently using baseline?
 - [ ] **Foundation** is the Stacks stack (Stacks UI + Crosswind + Iconify), no `npm install` of an external design system or icon package?
 - [ ] **Redesign mode** detected and audit performed (if applicable, Section 11)?
-- [ ] **ZERO em-dashes (`—`) anywhere on the page.** Headlines, eyebrows, pills, body, quotes, attribution, captions, buttons, alt text. Zero. (Section 9.G - non-negotiable.)
+- [ ] **ZERO em-dashes (`-`) anywhere on the page.** Headlines, eyebrows, pills, body, quotes, attribution, captions, buttons, alt text. Zero. (Section 9.G - non-negotiable.)
 - [ ] **No `var`, no bare `document.*` / `window.*`** in any stx `<script>` block?
 - [ ] **Page Theme Lock**: ONE theme (light, dark, or auto) for the whole page, no section flips mid-page (Section 4.11)?
 - [ ] **Color Consistency Lock**: one accent color used identically across all sections (Section 4.2)?
@@ -911,7 +931,7 @@ Run this matrix before outputting code. This is the last filter.
 - [ ] **Motion claimed = motion shown**: if `MOTION_INTENSITY > 4`, page actually animates?
 - [ ] **Sticky-stack / horizontal-pan** implemented per Section 5.A / 5.B (`position: sticky; top: 0` pin + CSS `view()` / `scroll()` timeline, reduced-motion gated)?
 - [ ] **No `window.addEventListener('scroll')`**, no per-frame signal-state scroll math - using `useIntersectionObserver` / CSS scroll-driven animations only (Section 5.E)?
-- [ ] **Pointer / magnetic** effects drive a CSS custom property from `useMouse()` inside an `effect`, never per-frame signal state (Section 5.D)?
+- [ ] **Pointer / magnetic** effects drive a CSS custom property from `useMouse()` in its subscription callback, never per-frame signal state (Section 5.D)?
 - [ ] **Reduced motion** gated for everything `MOTION_INTENSITY > 3` (CSS media block AND/OR `useMediaQuery('(prefers-reduced-motion: reduce)')`)?
 - [ ] **Dark mode** tokens defined and tested in both modes (Crosswind `dark:` or CSS vars + `useColorMode()`)?
 - [ ] **Mobile collapse** explicit (`w-full`, `px-4`, `max-w-7xl mx-auto`) for high-variance layouts?
@@ -935,7 +955,7 @@ If a single checkbox cannot be honestly ticked, the page is not done. Fix it bef
 
 There is no external-design-system install matrix for a Stacks app. The foundation is already in the project:
 
-* **Components:** `@stacksjs/ui` (Stacks UI). Headless primitives + Craft native components + `Transition`. See [stacks-ui](../stacks-ui).
+* **Components:** `@stacksjs/ui/components` and plugin-resolved STX tags. Check the installed exports and native host capabilities. See [stacks-ui](../stacks-ui).
 * **Styling:** Crosswind utilities + `dark:` variant. See [stacks-crosswind](../stacks-crosswind).
 * **Icons:** Iconify `i-{collection}-{name}` classes (hugeicons default). No install needed.
 * **Templating / reactivity / motion composables:** stx (see [stacks-stx](../stacks-stx)) and [stacks-composables](../stacks-composables).

package/ai/skills/stacks-design-taste-codex/SKILL.md

@@ -156,7 +156,7 @@ Motion must be motivated (flagship Section: hierarchy, storytelling, feedback, o
 
 **Card stacking:** cards overlap and stack from the bottom as the user scrolls - a real sticky-stack, not a sequential reveal list (Section 5.A).
 
-The full canonical skeletons live in the flagship: **sticky-stack (Section 5.A), horizontal-pan (Section 5.B), scroll-reveal stagger with `useIntersectionObserver` (Section 5.C), pointer/magnetic via `useMouse()` -> CSS custom property inside an `effect` (Section 5.D), and Forbidden Animation Patterns (Section 5.E)**. Use them as written. This variant only adds the extra deterministic paradigms below.
+The full canonical skeletons live in the flagship: **sticky-stack (Section 5.A), horizontal-pan (Section 5.B), scroll-reveal stagger with `useIntersectionObserver` (Section 5.C), pointer/magnetic via `useMouse()` -> CSS custom property in its subscription callback (Section 5.D), and Forbidden Animation Patterns (Section 5.E)**. Use them as written. This variant only adds the extra deterministic paradigms below.
 
 ### 5.A Scale-and-fade on scroll - canonical skeleton (pure CSS `view()` timeline)
 
@@ -221,16 +221,16 @@ Split the paragraph into word `<span>`s (via a `@foreach` over pre-split words i
 
 Critical points: the words are split server-side, the reveal is a pure CSS `view()` timeline staggered by `--i`, and reduced motion shows all words immediately. No library, no scroll listener.
 
-For pointer / magnetic physics, drive a CSS custom property from `useMouse()` inside an `effect` exactly as the flagship Section 5.D skeleton shows. Never write signal state per pointer or scroll frame.
+For pointer / magnetic physics, drive a CSS custom property from `useMouse()` in its subscription callback exactly as the flagship Section 5.D skeleton shows. Never write signal state per pointer or scroll frame.
 
 ### 5.C Forbidden (hard bans, same as flagship 5.E)
 
 * `window.addEventListener('scroll', ...)` - banned. Use CSS scroll-driven animations or `useIntersectionObserver` / `useElementVisibility`.
-* Bare `window.*` / `document.*` / `var` in any stx `<script>` - banned. Use composables (`useEventListener`, `useWindow`, `useResizeObserver`, `useMouse`, `useScroll`, `useParallax`, `usePreferredReducedMotion`).
-* `requestAnimationFrame` loops that write signal state on every frame - banned. Drive one CSS custom property per frame from inside an `effect`, or let a CSS timeline do it.
+* Bare `window.*` / `document.*` / `var` in any stx `<script>` - banned. Use composables (`useEventListener`, `useWindowSize`, `useResizeObserver`, `useMouse`, `useScroll`, `useParallax`, `usePreferredReducedMotion`).
+* `requestAnimationFrame` loops that write signal state on every frame - banned. Drive one CSS custom property per frame from in its subscription callback, or let a CSS timeline do it.
 * Custom scroll-progress math written into signal state - banned. Use a `scroll()` timeline, or `useScroll()` reading into a CSS var.
 
-Allowed composables are the flagship's list PLUS `useScroll` (scroll progress), `useParallax` (parallax offset), and `usePreferredReducedMotion` (reduced-motion signal, the composable form of `useMediaQuery('(prefers-reduced-motion: reduce)')`). Do NOT invent any others; if you need something else, use plain CSS / a standard web API through a composable and defer to [stacks-composables](../stacks-composables).
+Allowed composables are the flagship's list PLUS `useScroll` (scroll state), `useParallax` (device-orientation parallax), and `usePreferredReducedMotion` (reduced-motion signal, the composable form of `useMediaQuery('(prefers-reduced-motion: reduce)')`). Do NOT invent any others; if you need something else, use plain CSS / a standard web API through a composable and defer to [stacks-composables](../stacks-composables).
 
 ---