@stacksjs/defaults 0.70.207 → 0.70.208

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

@@ -0,0 +1,217 @@
+---
+name: stacks-cms
+description: Use when working with the CMS in a Stacks application — posts, authors, pages, categories, tags, comments, blog configuration, RSS feeds, or sitemaps. Covers @stacksjs/cms, CMS models, routes, and actions.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks CMS
+
+## Key Paths
+- Core package: `storage/framework/core/cms/src/`
+- Models: `storage/framework/defaults/app/Models/Content/` (Post, Author, Page)
+- Models: `storage/framework/defaults/app/Models/` (Comment, Tag)
+- Actions: `storage/framework/defaults/app/Actions/Cms/`
+- Routes: `routes/api.ts` (CMS and blog endpoints)
+- Config: `config/blog.ts`
+
+## Source Files
+```
+cms/src/
+├── index.ts              # CmsNamespace — top-level API
+├── posts/
+│   ├── fetch.ts          # fetchById, fetchAll, fetchByStatus, fetchByCategory, fetchByAuthor
+│   ├── store.ts          # store, attach, detach, sync (pivot tables)
+│   ├── update.ts         # update
+│   └── destroy.ts        # destroy, bulkDestroy
+├── authors/
+│   ├── fetch.ts          # fetchAll, fetchById, findByEmail, findByName, findByUserId
+│   ├── store.ts          # store, findOrCreate
+│   ├── update.ts         # update
+│   └── destroy.ts        # destroy
+├── pages/
+│   ├── fetch.ts          # fetchById, fetchAll, fetchByTemplate, fetchByAuthor
+│   └── store.ts          # store
+├── categorizables/       # Categories with polymorphic pivot
+├── taggables/            # Tags with polymorphic pivot
+├── commentables/         # Comments with polymorphic support
+└── build.ts              # Blog static site generation
+```
+
+## CMS Namespace
+
+```typescript
+interface CmsNamespace {
+  posts: PostsModule
+  postCategories: PostCategoriesModule
+  tags: TagsModule
+  comments: CommentsModule
+  authors: AuthorsModule
+  pages: PagesModule
+}
+```
+
+## Models
+
+### Post
+- **Table**: `posts`
+- **Relationships**: `belongsTo(['Author'])`
+- **Traits**: UUID, Timestamps, Search, Seeder (20), Categorizable, Taggable, Commentable, API routes
+
+| Field | Type | Validation | Default |
+|-------|------|------------|---------|
+| title | string | required, 3-255 chars | — |
+| content | string | required, 10-1000 chars | — |
+| excerpt | string | optional, 10-500 chars | — |
+| poster | string | optional, valid URL | — |
+| views | number | — | 0 |
+| publishedAt | timestamp | optional | — |
+| status | enum | published/draft/archived | draft |
+| isFeatured | number | 0 or 1 | — |
+
+### Author
+- **Table**: `authors`, **Relationships**: `hasMany(['Post'])`, `belongsTo(['User'])`
+- **Attributes**: `name` (5-255), `email` (unique, valid email)
+- **Indexes**: Composite on `(email, name)`
+
+### Page
+- **Table**: `pages`, **Relationships**: `belongsTo(['Author'])`
+- **Attributes**: `title`, `template` (enum: default/landing/blog/contact), `views`, `conversions`, `publishedAt`
+
+### Comment
+- **Table**: `comments`, **Relationships**: `belongsTo(['Post', 'User'])`
+- **Attributes**: `authorName`, `authorEmail`, `content` (1-2000), `status` (pending/approved/spam/trash), `ipAddress`, `userAgent`, `isApproved`
+
+### Tag
+- **Table**: `tags`
+- **Attributes**: `name` (unique, 2-50), `slug` (unique), `description`, `postCount`, `color`
+
+## Posts API
+
+```typescript
+// Fetch
+cms.posts.fetchById(id: number): Promise<PostJsonResponse | undefined>
+cms.posts.fetchAll(): Promise<PostJsonResponse[]>
+cms.posts.fetchByStatus(status: 'published' | 'draft' | 'archived'): Promise<PostJsonResponse[]>
+cms.posts.fetchByCategory(category: string): Promise<PostJsonResponse[]>
+cms.posts.fetchByAuthor(author: string): Promise<PostJsonResponse[]>
+cms.posts.fetchByMinViews(minViews: number): Promise<PostJsonResponse[]>
+cms.posts.fetchPublishedAfter(timestamp: number): Promise<PostJsonResponse[]>
+
+// Store with pivot auto-attach
+cms.posts.store(data: NewPost & { body?: string, category?: string }): Promise<PostJsonResponse>
+cms.posts.attach(postId, tableName: 'categorizable_models' | 'taggable_models', ids: number[]): Promise<void>
+cms.posts.detach(postId, tableName, ids?: number[]): Promise<void>
+cms.posts.sync(postId, tableName, ids: number[]): Promise<void>
+
+// Update & Destroy
+cms.posts.update(id: number, data: Partial<PostUpdate>): Promise<PostJsonResponse>
+cms.posts.destroy(id: number): Promise<boolean>
+cms.posts.bulkDestroy(ids: number[]): Promise<number>
+```
+
+## Authors API
+
+```typescript
+cms.authors.findOrCreate(data: AuthorData): Promise<AuthorJsonResponse>
+cms.authors.store(data: NewAuthor): Promise<AuthorJsonResponse>
+cms.authors.findByEmail(email: string): Promise<AuthorJsonResponse | undefined>
+cms.authors.findByName(name: string): Promise<AuthorJsonResponse | undefined>
+cms.authors.findByUserId(userId: number): Promise<AuthorJsonResponse | undefined>
+cms.authors.fetchAll(): Promise<AuthorJsonResponse[]>
+cms.authors.fetchById(id: number): Promise<AuthorJsonResponse | undefined>
+cms.authors.update(id, data): Promise<AuthorJsonResponse>
+cms.authors.destroy(id): Promise<boolean>
+```
+
+## Tags API
+
+```typescript
+cms.tags.findOrCreateMany(names: string[], taggableType: string): Promise<number[]>
+cms.tags.firstOrCreate(name: string, taggableType: string): Promise<TaggableTable>
+cms.tags.fetchTags(): Promise<TaggableTable[]>
+cms.tags.fetchTagById(id: number): Promise<TaggableTable | undefined>
+cms.tags.countTaggedPosts(taggableType: string): Promise<number>
+cms.tags.findMostUsedTag(taggableType?: string): Promise<{ name: string, count: number } | null>
+cms.tags.fetchTagsWithPostCounts(): Promise<Array<{ name: string, postCount: number }>>
+cms.tags.fetchTagDistribution(): Promise<Array<{ name: string, count: number, percentage: number }>>
+```
+
+## Comments API
+
+```typescript
+cms.comments.createComment(data: CreateCommentInput): Promise<CommentablesTable>
+cms.comments.updateComment(id: number, input: UpdateCommentInput): Promise<CommentablesTable>
+cms.comments.approveComment(id: number): Promise<CommentablesTable>
+cms.comments.rejectComment(id: number): Promise<CommentablesTable>
+cms.comments.deleteComment(id: number): Promise<void>
+```
+
+## Routes
+
+### CMS Admin Routes
+| Method | Path | Action |
+|--------|------|--------|
+| GET | `/cms/posts` | PostIndexAction |
+| GET | `/cms/posts/{id}` | PostShowAction |
+| POST | `/cms/posts` | PostStoreAction |
+| PATCH | `/cms/posts/{id}` | PostUpdateAction |
+| DELETE | `/cms/posts/{id}` | PostDestroyAction |
+| PATCH | `/cms/posts/{id}/views` | PostViewsUpdateAction |
+| CRUD | `/cms/authors/*` | Author CRUD |
+| CRUD | `/cms/categories/*` | Categorizable CRUD |
+| CRUD | `/cms/tags/*` | Taggable CRUD |
+| CRUD | `/cms/comments/*` | Comment CRUD |
+| CRUD | `/cms/pages/*` | Page CRUD |
+
+### Public Blog Routes
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/blog/posts` | Public post listing |
+| GET | `/blog/posts/{id}` | Public post detail |
+| GET | `/blog/categories` | Public categories |
+| GET | `/blog/tags` | Public tags |
+| GET | `/blog/feed.xml` | RSS 2.0 feed (20 recent) |
+| GET | `/blog/sitemap.xml` | XML sitemap for SEO |
+
+## Blog Configuration (config/blog.ts)
+
+```typescript
+{
+  subdomain: 'blog',
+  title: 'Stacks Blog',
+  description: 'The official Stacks.js blog',
+  postsPerPage: 10,
+  enableComments: true,
+  enableRss: true,
+  enableSitemap: true,
+  enableSearch: true,
+  social: { twitter: '@stacksjs', github: 'stacksjs/stacks' },
+  theme: { primaryColor: '#3451b2', logo: '/images/logos/logo-transparent.svg' },
+}
+```
+
+## Database Tables
+
+| Table | Purpose |
+|-------|---------|
+| `posts` | Blog posts |
+| `authors` | Content creators |
+| `pages` | Static pages |
+| `comments` | Comments (polymorphic) |
+| `tags` | Tag definitions |
+| `taggable_models` | Polymorphic pivot: tag ↔ model |
+| `categorizables` | Category definitions |
+| `categorizable_models` | Polymorphic pivot: category ↔ model |
+
+## Gotchas
+- **Polymorphic relations** — categories, tags, and comments use `*_type` fields to support multiple model types
+- **Post `content` maps from `body`** — the model attribute is `content` but the DB column mapping comes from `body`
+- **Author uses findOrCreate** — `PostStoreAction` auto-creates authors if they don't exist
+- **Post store auto-attaches** — creating a post with category/tag data automatically calls `attach()` on pivot tables
+- **Post update uses sync** — updating categories/tags uses `sync()` (detaches removed, attaches new)
+- **Views increment is atomic** — `PATCH /cms/posts/{id}/views` increments by 1
+- **RSS returns 20 items** — hardcoded to 20 most recent published posts
+- **Sitemap priorities** — posts 0.8, categories 0.6, blog homepage 0.9
+- **Comment status flow** — starts `pending`, can be approved, rejected (→ spam), or trashed

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

@@ -0,0 +1,82 @@
+---
+name: stacks-collections
+description: Use when working with collection data structures in Stacks — chaining array operations, Laravel-style collection methods, mapping, filtering, reducing, or grouping. Covers @stacksjs/collections which wraps ts-collect.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Collections
+
+## Key Paths
+- Core package: `storage/framework/core/collections/src/`
+- Source: `storage/framework/core/collections/src/index.ts`
+- Package: `@stacksjs/collections`
+
+## API
+
+The package re-exports `collect` from `ts-collect`:
+
+```typescript
+import { collect } from '@stacksjs/collections'
+```
+
+## Usage
+
+```typescript
+import { collect } from '@stacksjs/collections'
+
+// Basic operations
+const result = collect([1, 2, 3, 4, 5])
+  .filter(n => n > 2)
+  .map(n => n * 2)
+  .toArray()
+// [6, 8, 10]
+
+// Aggregation
+collect([10, 20, 30]).sum()     // 60
+collect([10, 20, 30]).avg()     // 20
+collect([10, 20, 30]).min()     // 10
+collect([10, 20, 30]).max()     // 30
+
+// Grouping
+collect(users).groupBy('role')
+// { admin: [...], user: [...] }
+
+// Sorting
+collect(items).sortBy('price').toArray()
+collect(items).sortByDesc('price').toArray()
+
+// Unique
+collect([1, 2, 2, 3, 3]).unique().toArray()  // [1, 2, 3]
+
+// First / Last
+collect([1, 2, 3]).first()     // 1
+collect([1, 2, 3]).last()      // 3
+
+// Chunk
+collect([1, 2, 3, 4, 5]).chunk(2).toArray()
+// [[1, 2], [3, 4], [5]]
+
+// Pluck
+collect(users).pluck('name').toArray()  // ['Alice', 'Bob']
+
+// Contains
+collect([1, 2, 3]).contains(2)  // true
+
+// Reduce
+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:
+
+`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`
+
+## 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

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

@@ -0,0 +1,114 @@
+---
+name: stacks-commerce
+description: Use when building e-commerce features in Stacks — the commerce namespace with 13 sub-modules (products, orders, customers, coupons, payments, shipping, tax, gift cards, waitlists, devices, receipts, restaurant), 20+ commerce models, default commerce functions, or the commerce configuration. Covers @stacksjs/commerce.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Commerce
+
+Comprehensive e-commerce module with 13 sub-modules and 20+ models.
+
+## Key Paths
+- Core package: `storage/framework/core/commerce/src/`
+- Default functions: `storage/framework/defaults/functions/commerce/`
+- Default models: `storage/framework/defaults/app/Models/commerce/`
+
+## Commerce Namespace
+
+```typescript
+import { commerce } from '@stacksjs/commerce'
+
+// 13 sub-modules
+commerce.products      // Product CRUD
+commerce.coupons       // Coupon management
+commerce.customers     // Customer management
+commerce.errors        // Error tracking
+commerce.giftCards     // Gift card management
+commerce.orders        // Order management
+commerce.payments      // Payment processing
+commerce.restaurant    // Restaurant features
+commerce.shippings     // Shipping management
+commerce.tax           // Tax rate management
+commerce.waitlists     // Waitlist management
+commerce.devices       // Print device management
+commerce.receipts      // Receipt management
+```
+
+## Sub-Module Operations
+
+Each sub-module typically provides:
+- `index()` — list all
+- `fetch(id)` — get one
+- `store(data)` — create
+- `update(id, data)` — update
+- `destroy(id)` — delete
+
+### Products Sub-Module
+- Products: items, variants, units
+- Manufacturers
+- Reviews
+- Categories
+- Product waitlists
+
+### Orders Sub-Module
+- Order CRUD
+- Order items
+- Order export
+
+### Shipping Sub-Module
+- Shipping methods
+- Shipping rates (weight-based)
+- Shipping zones
+- Delivery routes
+- Drivers
+- Digital deliveries
+- License keys
+
+## Commerce Models (20+)
+
+| Model | Key Fields | Relationships |
+|-------|-----------|---------------|
+| Product | name, price, inventoryCount, allergens(JSON) | belongsTo: Category, Manufacturer; hasMany: Review, ProductUnit, ProductVariant |
+| ProductVariant | SKU, options, pricing | belongsTo: Product |
+| ProductUnit | unit pricing | belongsTo: Product |
+| Category | name, slug, isActive, displayOrder | hasMany: Product |
+| Cart | status, total, currency(USD), expiresAt | hasMany: CartItem; belongsTo: Customer |
+| CartItem | quantity, unitPrice, totalPrice | belongsTo: Cart |
+| Order | status, totalAmount, orderType, deliveryAddress | hasMany: OrderItem, Payment; belongsTo: Customer |
+| OrderItem | quantity, price | belongsTo: Order, Product |
+| Coupon | code(unique), discountType, discountValue, usageLimit | hasMany: Order |
+| GiftCard | code(unique), initialBalance, currentBalance, isReloadable | belongsTo: Customer |
+| Customer | name, email, totalSpent, status | hasMany: Order, GiftCard, Review, Payment |
+| Manufacturer | manufacturer info | hasMany: Product |
+| Review | rating(1-5), content, isVerifiedPurchase, helpfulVotes | belongsTo: Product, Customer |
+| ShippingRate | weightFrom, weightTo, rate | belongsTo: ShippingMethod, ShippingZone |
+| DeliveryRoute | stops, totalDistance | belongsTo: Driver |
+| TaxRate | name, rate(0-100), type(VAT/GST/Sales Tax) | |
+| LicenseKey | key(XXXX-XXXX-XXXX-XXXX-XXXX), template, status | belongsTo: Customer, Product, Order |
+| DigitalDelivery | downloadLimit, expiryDays, automaticDelivery | |
+| WaitlistProduct | product waitlist tracking | |
+| Receipt | receipt records | |
+
+## Integration with Payments
+Commerce works with `@stacksjs/payments` for Stripe integration:
+```typescript
+import { Payment } from '@stacksjs/payments'
+await Payment.charge(customer, order.totalAmount, paymentMethodId)
+```
+
+## Dashboard Routes
+All commerce models have dashboard views at `/dashboard/commerce/*`.
+
+## Gotchas
+- Commerce models are auto-generated — edit definitions, not generated files
+- Use `buddy make:migration` when changing commerce schemas
+- Order `observe: true` emits events on create/update/delete
+- Products have JSON fields for allergens and nutritionalInfo
+- Cart expiry is tracked via `expiresAt` field
+- Coupon types: `fixed_amount` or `percentage`
+- Gift card codes are unique and auto-generated
+- License keys follow XXXX-XXXX-XXXX-XXXX-XXXX format
+- Product dashboard is highlighted (`dashboard: { highlight: true }`)
+- Default seeder counts: Product(10), Order(20), Review(50), Payment(50)

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

@@ -0,0 +1,161 @@
+---
+name: stacks-composables
+description: Use when creating or using reactive composables in STX templates — 90+ composables for state management, DOM interaction, sensors, animation, browser APIs, async operations, or the complete list of auto-imported composables. Covers @stacksjs/composables.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Composables
+
+90+ reactive composables for STX templates. All are auto-imported in STX templates.
+
+## 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
+```
+
+## 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`
+
+## Gotchas
+- All composables are auto-imported in STX templates — no import needed
+- 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