@stacksjs/defaults 0.70.206 → 0.70.208

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

@@ -0,0 +1,129 @@
+---
+name: stacks-testing
+description: Use when writing or running tests in Stacks — test setup, database test utilities (setup, refresh, truncate), DynamoDB testing, feature test patterns, the test CLI commands, test configuration in bunfig.toml, or test environment setup. Covers @stacksjs/testing and tests/.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Testing
+
+Uses Bun's built-in test runner with Stacks-specific test utilities.
+
+## Key Paths
+- Core package: `storage/framework/core/testing/src/`
+- Test directory: `tests/`
+- Test setup: `tests/setup.ts`
+- Package: `@stacksjs/testing`
+
+## Test Setup
+
+```typescript
+import { setupTestEnvironment, setupDatabase, refreshDatabase } from '@stacksjs/testing'
+
+// Set NODE_ENV and APP_ENV to 'test'
+setupTestEnvironment()
+
+// Create testing database (SQLite: database/stacks_testing.sqlite)
+await setupDatabase()
+
+// Refresh database (drop and re-migrate)
+await refreshDatabase()
+
+// Truncate tables
+await truncateSqlite()   // for SQLite
+await truncateMysql()    // for MySQL
+```
+
+## DynamoDB Testing
+
+```typescript
+import { launchServer, createStacksTable, deleteStacksTable, delay } from '@stacksjs/testing'
+
+// Launch DynamoDB Local
+const { server, endpoint } = await launchServer()
+
+// Create test table
+await createStacksTable()
+
+// Cleanup
+await deleteStacksTable()
+
+// Utility
+await delay(1000)  // wait for async operations
+```
+
+## Writing Tests
+
+```typescript
+import { describe, test, it, expect, beforeAll, afterAll, beforeEach } from 'bun:test'
+
+describe('User Model', () => {
+  beforeAll(async () => {
+    await setupDatabase()
+  })
+
+  afterAll(async () => {
+    await refreshDatabase()
+  })
+
+  test('can create a user', async () => {
+    const user = await User.create({ name: 'John', email: 'john@test.com' })
+    expect(user.name).toBe('John')
+  })
+
+  test('validates email uniqueness', async () => {
+    await expect(User.create({ email: 'duplicate@test.com' }))
+      .rejects.toThrow()
+  })
+})
+```
+
+## Queue Testing
+
+```typescript
+import { fake, restore, runTestJob, expectJobToFail } from '@stacksjs/queue'
+
+test('dispatches welcome email job', async () => {
+  const fakeQueue = fake()
+  await SendWelcomeEmail.dispatch({ email: 'test@test.com' })
+  fakeQueue.assertDispatched('SendWelcomeEmail')
+  restore()
+})
+```
+
+## CLI Commands
+
+```bash
+buddy test                    # run all tests
+buddy test --unit             # unit tests only
+buddy test --feature          # feature tests only
+bun run test                  # via npm script
+bun run test:ui               # UI tests
+bun run test:coverage         # with coverage
+bun run test:types            # type tests
+```
+
+## Configuration (bunfig.toml)
+
+```toml
+[test]
+preload = ["./tests/setup.ts"]
+```
+
+## Test File Conventions
+- Test files: `*.test.ts` or `*.spec.ts`
+- Located in `tests/` directory
+- Setup/teardown in `tests/setup.ts`
+- Unit tests in `tests/unit/`
+- Feature tests in `tests/feature/`
+
+## Gotchas
+- Uses Bun's native test runner, NOT Jest or Vitest
+- Test preload runs `tests/setup.ts` before each test file
+- SQLite testing database is at `database/stacks_testing.sqlite`
+- `refreshDatabase()` drops ALL tables — use in test setup only
+- DynamoDB Local must be installed for DynamoDB tests
+- Queue testing uses `fake()`/`restore()` pattern — affects global state
+- `@stacksjs/faker` provides test data generation
+- Coverage reports with `bun run test:coverage`

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

@@ -0,0 +1,125 @@
+---
+name: stacks-tunnel
+description: Use when setting up tunnels in Stacks — local development tunnels for webhook testing, custom cloud tunnel deployment to AWS EC2, tunnel event callbacks (onConnect, onRequest, onResponse, onError), subdomain configuration, or the buddy share command. Covers @stacksjs/tunnel.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Tunnel
+
+Local and cloud-deployed development tunnels for exposing local servers.
+
+## Key Paths
+- Core package: `storage/framework/core/tunnel/src/`
+- External tool: ~/Code/Tools/localtunnels/
+
+## Local Tunnel (Quick)
+
+```typescript
+import { createLocalTunnel } from '@stacksjs/tunnel'
+
+const url = await createLocalTunnel(3000)
+// Returns: 'https://abc123.loca.lt'
+console.log(`Share this URL: ${url}`)
+```
+
+## Advanced Local Tunnel
+
+```typescript
+import { localTunnel } from '@stacksjs/tunnel'
+
+const tunnel = await localTunnel({
+  port: 3000,                          // required
+  server: 'https://localtunnel.me',   // tunnel server
+  subdomain: 'my-app',                // request specific subdomain
+  verbose: true,
+  timeout: 30000,                      // connection timeout (ms)
+  maxReconnectAttempts: 5,
+
+  // Event callbacks
+  onConnect: (url) => {
+    console.log(`Tunnel connected: ${url}`)
+  },
+  onRequest: (info) => {
+    console.log(`Request: ${info.method} ${info.path}`)
+  },
+  onResponse: (info) => {
+    console.log(`Response: ${info.status}`)
+  },
+  onError: (error) => {
+    console.error('Tunnel error:', error)
+  },
+  onReconnecting: (attempt) => {
+    console.log(`Reconnecting... attempt ${attempt}`)
+  }
+})
+
+// Access tunnel info
+console.log(tunnel.url)          // public URL
+console.log(tunnel.subdomain)   // assigned subdomain
+
+// Close tunnel
+tunnel.close()
+```
+
+## Cloud Tunnel Deployment (AWS)
+
+```typescript
+import { deployTunnelServer, destroyTunnelServer } from '@stacksjs/tunnel'
+
+// Deploy custom tunnel server to EC2
+await deployTunnelServer({
+  region: 'us-east-1',
+  instanceType: 't3.micro',
+  domain: 'tunnel.myapp.com'
+})
+
+// Tear down
+await destroyTunnelServer({
+  region: 'us-east-1'
+})
+```
+
+## CLI Command
+
+```bash
+buddy share              # start tunnel for dev server
+```
+
+## TunnelOptions Interface
+
+```typescript
+interface TunnelOptions {
+  port: number                        // local port to tunnel
+  server?: string                     // tunnel relay server URL
+  subdomain?: string                  // requested subdomain
+  verbose?: boolean                   // debug output
+  timeout?: number                    // connection timeout (ms)
+  maxReconnectAttempts?: number       // retry limit
+
+  onConnect?: (url: string) => void
+  onRequest?: (info: RequestInfo) => void
+  onResponse?: (info: ResponseInfo) => void
+  onError?: (error: Error) => void
+  onReconnecting?: (attempt: number) => void
+}
+
+interface LocalTunnel {
+  url: string                         // public tunnel URL
+  subdomain: string                   // assigned subdomain
+  client: TunnelClient               // underlying client
+  close: () => void                   // close tunnel
+}
+```
+
+## Gotchas
+- Tunnels are for development only — not production use
+- `createLocalTunnel()` is the simple version — returns just the URL
+- `localTunnel()` is the full version with callbacks and control
+- Cloud deployment creates an EC2 instance — incurs AWS costs
+- Tunnel URLs are temporary — change between sessions unless subdomain is configured
+- Ensure dev server is running before starting the tunnel
+- `maxReconnectAttempts` prevents infinite reconnection loops
+- The underlying tool is from ~/Code/Tools/localtunnels/
+- `buddy share` wraps `createLocalTunnel()` for the configured dev port

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

@@ -0,0 +1,178 @@
+---
+name: stacks-types
+description: Use when working with TypeScript type definitions in a Stacks application — model types, request types, environment variables, event types, billing types, attribute types, or auto-imported globals. Covers storage/framework/types/ and storage/framework/core/types/src/.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Types
+
+## Key Paths
+- Core types: `storage/framework/core/types/src/`
+- Generated types: `storage/framework/types/`
+- ORM globals: `storage/framework/types/orm-globals.d.ts`
+- Environment: `storage/framework/types/env.d.ts`
+- Actions: `storage/framework/types/actions.d.ts` (generated `ActionPath` union)
+- Model traits: `storage/framework/types/traits.d.ts`
+- Model attributes: `storage/framework/types/attributes.d.ts`
+- Events: `storage/framework/types/events.ts`
+- Attributes: `storage/framework/types/attributes.ts`
+
+## Authentication Types (auth.ts)
+
+```typescript
+interface AuthConfig {
+  default: string
+  guards: { [key: string]: { driver: 'session' | 'token', provider: string } }
+  providers: { [key: string]: { driver: 'database', table: string } }
+  username: string
+  password: string
+  tokenExpiry: number           // 30 days
+  tokenRotation: number         // 7 days
+  defaultAbilities: string[]
+  defaultTokenName: string
+}
+```
+
+## ORM Global Types (orm-globals.d.ts)
+
+```typescript
+// Full database row — model attributes + system fields + FK columns
+type ModelRow<T> = { id: number, uuid: string, created_at: string, updated_at: string } & ModelAttributes<T>
+
+// Insertable data — all fields optional
+type NewModelData<T> = Partial<ModelAttributes<T>>
+
+// Updateable data — all fields optional
+type UpdateModelData<T> = Partial<ModelAttributes<T>>
+
+// Model-aware request — narrows field names to model's attributes
+interface RequestInstance<TModel> {
+  get(key: keyof TModel): any
+  all(): TModel
+  validate(): Promise<void>
+}
+```
+
+## Environment Types (env.d.ts)
+
+```typescript
+// Application
+APP_NAME, APP_ENV: 'local' | 'dev' | 'stage' | 'prod', APP_KEY, APP_URL, PORT, DEBUG
+
+// Database
+DB_CONNECTION: 'mysql' | 'sqlite' | 'postgres' | 'dynamodb'
+DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD
+
+// AWS
+AWS_ACCOUNT_ID, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION
+
+// Mail
+MAIL_MAILER: 'smtp' | 'mailgun' | 'ses' | 'postmark' | 'sendmail' | 'log'
+MAIL_HOST, MAIL_PORT, MAIL_USERNAME, MAIL_PASSWORD, MAIL_FROM_NAME, MAIL_FROM_ADDRESS
+
+// Search
+SEARCH_ENGINE_DRIVER: 'meilisearch' | 'algolia' | 'typesense'
+MEILISEARCH_HOST, MEILISEARCH_KEY
+
+// Frontend
+FRONTEND_APP_ENV: 'development' | 'staging' | 'production', FRONTEND_APP_URL
+```
+
+## Event Types (events.ts)
+
+All model CRUD events: `model:created`, `model:updated`, `model:deleted`
+
+- **Content**: author, post, page
+- **Core**: user, activity, campaign, comment, email-list, notification, social-post, subscription, tag
+- **Commerce (30+ models)**: cart, cart-item, category, coupon, customer, order, order-item, payment, product, product-variant, review, shipping-method, shipping-rate, tax-rate, transaction, gift-card, license-key, and more
+
+All payloads are `Record<string, any>`.
+
+## Billing Types (billing.ts)
+
+```typescript
+interface TransactionHistory {
+  id?, uuid?, name, description?, amount, type, provider_id?, user_id?, paymentmethod_id?, created_at, updated_at?
+}
+
+interface PaymentMethod {
+  id?, uuid?, type, last_four, brand, exp_month, exp_year, is_default?, provider_id?, user_id?
+}
+
+interface Product {
+  id?, uuid?, name, key, unit_price?, status?, image?, provider_id?
+}
+
+interface Subscription {
+  id?, uuid?, type, provider_id, provider_status, provider_type, unit_price?, quantity?, trial_ends_at?, ends_at?, user_id?
+}
+```
+
+## Attribute Types (attributes.ts)
+
+200+ attribute definitions covering all models:
+
+| Category | Fields |
+|----------|--------|
+| Basic | name, slug, description, title, subject, content, body |
+| Dates | created_at, updated_at, published_at, scheduled_at, expires_at |
+| Commerce | unit_price, price, amount, tax_amount, discount_amount, total, currency |
+| User | email, password, phone, avatar, author_name, author_email |
+| Shipping | delivery_address, delivery_fee, region, countries |
+| Loyalty | loyalty_points_earned, loyalty_points_redeemed, points_required |
+| Analytics | views, conversions, clicks, reach, likes, shares |
+
+## Request Types (traits.d.ts)
+
+Auto-generated per model:
+
+```typescript
+interface PasskeysRequestType extends Request {
+  get(key: 'id' | 'cred_public_key' | 'user_id' | 'counter' | ...): any
+}
+
+interface CommentablesRequestType extends Request {
+  get(key: 'title' | 'body' | 'status' | 'commentables_id' | ...): any
+}
+```
+
+## Auto-Imported Globals
+
+### Framework Modules
+`Action`, `response`, `route`, `Router`, `schema`, `validate`, `slug`, `camelCase`, `pascalCase`, `snakeCase`, `kebabCase`, `titleCase`, `path`, `storage`, `log`, `handleError`, `Auth`, `register`
+
+### 60+ ORM Models (globally available)
+User, Team, Post, Page, Author, Comment, Product, Order, Cart, Customer, Coupon, Category, Tag, Payment, Subscription, Driver, ShippingRate, GiftCard, LicenseKey, Job, FailedJob, Error, Log, Notification, and many more.
+
+### stx components
+Components under `resources/components/` are resolved by the stx plugin and used directly in templates (`<Card />`) - no import, no global registration step. Editor metadata is generated into `storage/framework/core/web-types.json` and `custom-elements.json` by `buddy generate:web-types` / `generate:custom-data`. There is no `components.d.ts`.
+
+### Actions Type
+```typescript
+type ActionPath = 'Actions/LogAction' | 'Actions/HealthAction' | 'Actions/ExampleAction' | (string & {})
+```
+
+## CLI Types (cli.ts)
+
+```typescript
+interface CliOptions {
+  verbose?: boolean, silent?: boolean, quiet?: boolean
+  cwd?: string, background?: boolean, timeoutMs?: number, project?: string
+}
+
+interface CleanOptions extends CliOptions {}
+interface CommitOptions extends CliOptions {}
+interface FreshOptions extends CliOptions { dryRun?: boolean }
+```
+
+## Gotchas
+- **Types are auto-generated** — many files in `storage/framework/types/` are generated from model definitions
+- **ORM globals are truly global** — `ModelRow<T>`, `NewModelData<T>` available without imports
+- **RequestInstance is model-aware** — `.get()` and `.all()` narrowed to model's fields when typed
+- **Event payloads are untyped** — all `Record<string, any>`, not strongly typed per-model
+- **Env types augment Bun.env** — `Bun.env.DB_CONNECTION` is typed
+- **Attributes is a shared type** — 200+ fields covering ALL models, not per-model
+- **Router types auto-generated** — 130+ typed route definitions, regenerated when routes change
+- **Components.d.ts has 150+ entries** — globally registered, no imports needed

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

@@ -0,0 +1,246 @@
+---
+name: stacks-ui
+description: Use when working with UI in a Stacks application — components, composables, reactivity (refs/watch/computed), Craft native components, Crosswind CSS, Crosswind utility framework, accessibility, or the STX templating engine. Covers @stacksjs/ui, @stacksjs/stx, and related UI tooling.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks UI
+
+## Design & anti-slop skills
+
+For premium, non-templated UI (layout, typography, color, motion) built on stx + Crosswind, reach for the design-taste skill family:
+- `stacks-design-taste` - flagship anti-slop frontend skill (brief inference, the three dials, layout/type/color discipline, strict pre-flight check)
+- Aesthetic presets: `stacks-design-soft`, `stacks-design-minimalist`, `stacks-design-brutalist`
+- `stacks-redesign` - audit-first upgrade of an existing UI; `stacks-design-output` - full-output enforcement (no placeholder or truncated components)
+- Image-first: `stacks-image-to-code`, plus reference-image generators `stacks-imagegen-web`, `stacks-imagegen-mobile`, `stacks-brandkit`
+
+## Key Paths
+- Core package: `storage/framework/core/ui/src/`
+- Components: `storage/framework/core/ui/src/components/`
+- UI config: `config/ui.ts` (Crosswind)
+- STX config: `config/ui.ts`
+- STX engine: `node_modules/@stacksjs/stx/`
+- Crosswind: `node_modules/@cwcss/crosswind/`
+- Editor metadata: `storage/framework/core/web-types.json`, `storage/framework/core/custom-elements.json`
+
+## Source Files
+```
+ui/src/
+├── index.ts              # Re-exports from @stacksjs/stx
+├── components.ts         # Component re-exports
+└── components/
+    ├── autocomplete.ts   # Combobox, ComboboxInput, ComboboxOption, ComboboxOptions
+    ├── disclosure.ts     # Disclosure, DisclosureButton, DisclosurePanel
+    ├── menu.ts           # Menu, MenuButton, MenuItem, MenuItems
+    ├── modal.ts          # Dialog, DialogDescription, DialogPanel, DialogTitle
+    ├── popover.ts        # Popover, PopoverButton, PopoverPanel
+    ├── radio-group.ts    # RadioGroup, RadioGroupLabel, RadioGroupOption
+    ├── select.ts         # Combobox-based select
+    ├── tabs.ts           # Tab, TabGroup, TabList, TabPanel, TabPanels
+    ├── toggle.ts         # Switch
+    └── transition.ts     # TransitionChild, TransitionRoot
+```
+
+## Headless Components
+
+```typescript
+import { Combobox, ComboboxInput, ComboboxOption, ComboboxOptions } from '@stacksjs/ui'
+import { Dialog, DialogDescription, DialogPanel, DialogTitle } from '@stacksjs/ui'
+import { Menu, MenuButton, MenuItem, MenuItems } from '@stacksjs/ui'
+import { Tab, TabGroup, TabList, TabPanel, TabPanels } from '@stacksjs/ui'
+import { Switch } from '@stacksjs/ui'
+import { TransitionChild, TransitionRoot } from '@stacksjs/ui'
+```
+
+## Craft Native Components
+
+Built-in components with native HTML fallbacks:
+
+| Component | Fallback | Key Props |
+|-----------|----------|-----------|
+| `craft-button` | `<button>` | variant (primary/secondary/outline) |
+| `craft-text-input` | `<input>` | placeholder, value, type, disabled |
+| `craft-textarea` | `<textarea>` | placeholder, value, rows |
+| `craft-checkbox` | `<input type="checkbox">` | checked, disabled, label |
+| `craft-select` | `<select>` | value, options, placeholder |
+| `craft-modal` | `<dialog>` | open, title, closable, size |
+| `craft-tabs` | `<div>` | activeTab, tabs |
+| `craft-table` | `<table>` | columns, rows, sortable, selectable |
+| `craft-card` | `<div>` | title, subtitle, variant |
+| `craft-alert` | `<div>` | variant, title, dismissible |
+| `craft-toast` | `<div>` | variant, duration, position |
+| `craft-tooltip` | `<span>` | content, position |
+| `craft-pagination` | `<nav>` | total, page, pageSize |
+| `craft-code-editor` | `<textarea>` | value, language, theme, lineNumbers |
+| `craft-date-picker` | `<input type="date">` | value, min, max, format |
+| `craft-color-picker` | `<input type="color">` | value, format |
+| `craft-badge` | `<span>` | variant, size |
+| `craft-avatar` | `<div>` | src, alt, size, fallback |
+| `craft-progress` | `<div>` | value, max, variant |
+| `craft-spinner` | `<div>` | size |
+| `craft-accordion` | `<details>` | open, title |
+| `craft-divider` | `<hr>` | orientation, variant |
+| `craft-breadcrumb` | `<nav>` | items, separator |
+| `craft-menu` | `<nav>` | items, orientation |
+| `craft-tree` | `<div>` | nodes, expandable, selectable |
+| `craft-list` | `<ul>` | items, selectable |
+| `craft-slider` | `<input type="range">` | value, min, max, step |
+| `craft-radio` | `<input type="radio">` | checked, name, value, label |
+| `craft-file-browser` | `<div>` | path, showHidden, selectable |
+
+## Reactivity System
+
+```typescript
+import { ref, namedRef, computed, watch } from '@stacksjs/stx'
+
+const count = ref(0)
+count.value = 5
+
+const doubled = computed(() => count.value * 2)
+
+const stop = watch(
+  () => count.value,
+  (newVal, oldVal) => console.log(`${oldVal} → ${newVal}`),
+  { immediate: false }
+)
+stop()  // cleanup
+```
+
+### Types
+```typescript
+interface Ref<T> { value: T | null, readonly current: T | null }
+
+interface ComponentInstance {
+  id: string, element: Element | null
+  mountHooks: LifecycleHook[], destroyHooks: CleanupFn[], updateHooks: LifecycleHook[]
+  refs: Map<string, Ref<any>>, watchers: Array<{ stop: () => void }>
+  isMounted: boolean
+}
+```
+
+## Lifecycle Hooks
+
+```typescript
+import { onMount, onDestroy, onUpdate } from '@stacksjs/stx'
+// Aliases: onMounted, onUnmounted, onUpdated
+
+onMount(() => {
+  console.log('mounted')
+  return () => console.log('cleanup')  // optional
+})
+onDestroy(() => console.log('destroyed'))
+onUpdate(() => console.log('updated'))
+```
+
+## Dependency Injection
+
+```typescript
+import { provide, inject, createInjectionKey, withInjectionScope } from '@stacksjs/stx'
+
+const ThemeKey = createInjectionKey<string>('theme')
+provide(ThemeKey, 'dark')
+const theme = inject(ThemeKey)             // 'dark'
+const theme = inject(ThemeKey, 'light')    // with default
+```
+
+## Browser Composables
+
+```typescript
+import {
+  useLocalStorage, useSessionStorage, useEventListener,
+  useClickOutside, useWindowSize, useMediaQuery,
+  usePrefersDark, useOnline
+} from '@stacksjs/stx'
+
+const { value, remove } = useLocalStorage('key', defaultValue)
+const { width, height } = useWindowSize()
+const isDark = usePrefersDark()
+const isOnline = useOnline()
+const cleanup = useClickOutside(elementRef, handler)
+```
+
+## Crosswind Configuration (config/ui.ts)
+
+```typescript
+export default {
+  content: [
+    './resources/**/*.{html,js,ts,jsx,tsx,stx}',
+    './storage/framework/defaults/**/*.{html,js,ts,jsx,tsx,stx}',
+    './storage/framework/views/**/*.{html,js,ts,jsx,tsx,stx}',
+  ],
+  output: './storage/framework/assets/headwind.css',
+  minify: false,
+} satisfies CrosswindOptions
+```
+
+## STX Configuration (config/ui.ts)
+
+```typescript
+export default {
+  componentsDir: 'resources/components',
+  layoutsDir: 'resources/layouts',
+  partialsDir: 'resources/partials',
+} satisfies StxOptions
+```
+
+### Full StxConfig
+```typescript
+interface StxConfig {
+  enabled: boolean, debug: boolean
+  templatesDir?, componentsDir, partialsDir, layoutsDir?, defaultLayout?
+  ssr?: boolean, cache?: boolean, cachePath: string
+  i18n?: Partial<I18nConfig>
+  webComponents?: Partial<WebComponentConfig>
+  streaming?: Partial<StreamingConfig>
+  hydration?: Partial<HydrationConfig>
+  a11y?: Partial<A11yConfig>
+  seo?: Partial<SeoFeatureConfig>
+  animation?: Partial<AnimationConfig>
+  markdown?: Partial<MarkdownConfig>
+  pwa?: Partial<PwaConfig>
+  strict?: boolean | StrictModeConfig
+}
+```
+
+## Accessibility
+
+```typescript
+import { checkA11y, autoFixA11y, scanA11yIssues } from '@stacksjs/stx'
+
+const violations = await checkA11y(html, filePath)
+const result = autoFixA11y(html, config)
+const issues = await scanA11yIssues('./resources', { recursive: true })
+```
+
+```typescript
+interface A11yConfig {
+  enabled: boolean, addSrOnlyStyles: boolean
+  level: 'AA' | 'AAA', ignoreChecks?: string[], autoFix: boolean
+}
+```
+
+## Crosswind CSS Framework
+
+Utility-first CSS (like Tailwind), built into Stacks:
+
+```typescript
+import { buildCrosswindCSS, extractClassNames, generateCrosswindCSS } from '@stacksjs/stx'
+
+const css = await buildCrosswindCSS(cwd)
+const classNames = extractClassNames(htmlContent)
+```
+
+Features: theme config, 40+ variant modifiers, custom rules, shortcuts, attributify mode, bracket syntax, presets.
+
+## Gotchas
+- **@stacksjs/ui re-exports from @stacksjs/stx** — the UI package is thin, the engine is in STX
+- **Craft components use native fallbacks** — `preferNative: true` renders plain HTML
+- **Refs are not Vue refs** — similar API but custom reactive implementation
+- **Lifecycle hooks require component context** — must be called within `setupComponent()`
+- **Crosswind is not Tailwind** — Stacks' own CSS utility implementation
+- **Crosswind is the utility engine** — handles class extraction, CSS generation, purging
+- **STX is the templating engine** — handles `.stx` files, SSR, streaming, hydration
+- **Two CSS systems coexist** — Crosswind (config) and Crosswind (engine)
+- **150+ globally registered Vue components** — no imports needed