@stacksjs/defaults 0.74.43 → 0.74.46

package/ai/skills/stacks-auto-imports/SKILL.md

@@ -66,7 +66,7 @@ globalThis.toggleDark = toggleDark
 - **Custom Functions**: From `resources/functions/` (counter, dark mode, GPX, geo utilities)
 
 ### Server Auto-Imports (100+)
-- **All ORM Models**: User, Post, Author, Product, Order, Payment, Customer, etc. (102 models)
+- **All ORM Models**: User, Post, Author, Product, Order, Payment, Customer, etc. (103 models)
 - **Request Models**: UserRequest, PostRequest, OrderRequest, etc.
 - **Actions**: Action types and helpers
 - **Schema**: validation schema builder

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

@@ -8,54 +8,56 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 # Stacks Composables
 
-154 reactive composables for STX templates. **27 of them are auto-imported**;
-the rest need an explicit import from `@stacksjs/composables`.
-
-`storage/framework/browser-auto-imports.json` is the authority, and it declares
-83 names in total, 27 of which are `use*`. This page said "All are auto-imported
-in STX templates", which is the same mistake `AGENTS.md` carries a scar about
-under "200+ composables": an agent reaching for a name on that authority writes
-a template that does not run, and reads the failure as a framework bug.
-
-## The 27 you can write bare in a template
-
-Everything else on this page needs an explicit import, and that is most of what
-the sections below list - `useCounter`, `useLocalStorage`, `useMouse`,
-`useScroll`, `useIntersectionObserver` and `usePreferredReducedMotion` among
-them, which are exactly the names `AGENTS.md` calls out for having been wrongly
-listed as free.
-
-No count of how many fall on each side, deliberately. That number is
-maintained by hand and moves whenever a name is added to any section on this
-page - it was wrong within one edit of being written. The list below is the
-whole of the free side; anything not on it is on the other.
-
-<!-- auto-imported:begin - checked against browser-auto-imports.json by
-     core/server/tests/composables-skill-auto-imports.test.ts. Both directions:
-     every name here must be in the manifest, and every `use*` in the manifest
-     must be here. Edit the manifest, not this list. -->
-
-`useAbs`, `useAuth`, `useAverage`, `useCeil`, `useClamp`, `useDark`,
-`useDateFormat`, `useFetch`, `useFloor`, `useForm`, `useGitStore`, `useMax`,
-`useMin`, `useNow`, `useOnline`, `usePaymentStore`, `usePrecision`,
-`usePreferredDark`, `useQueueStore`, `useRound`, `useScrollLock`, `useStorage`,
-`useSum`, `useTimeoutFn`, `useToggle`, `useTrunc`, `useUserStore`.
+154 reactive composables for STX templates. **A fixed set of them is available
+bare**, listed below; everything else needs an explicit import from
+`@stacksjs/composables`.
+
+The stx runtime decides this, not `browser-auto-imports.json`. That manifest
+feeds an ambient `.d.ts` and nothing reads it at build time, so it says what the
+compiler accepts and not what the browser has; the two disagree in both
+directions (stacksjs/stacks#2585).
+
+This page said "All are auto-imported in STX templates", which is the mistake
+`AGENTS.md` carries a scar about under "200+ composables": an agent reaching for
+a name on that authority writes a template that does not run, and reads the
+failure as a framework bug.
+
+## What you can write bare in a template
+
+<!-- auto-imported:begin - checked against the stx runtime by
+     core/composables/tests/skill-runtime-globals.test.ts. These are the names
+     `getCachedSignalsRuntime()` attaches to `window`, which is what decides
+     whether a bare call resolves in a template. Do not derive this list from
+     `browser-auto-imports.json`: that manifest is compile-time only, and 22 of
+     the 27 `use*` it declares are absent from the runtime. -->
+
+`useAsync`, `useClickOutside`, `useColorMode`, `useCounter`, `useDark`,
+`useDebounce`, `useDebouncedValue`, `useEventListener`, `useFetch`, `useFocus`,
+`useHead`, `useInterval`, `useLocalStorage`, `useMutation`, `useQuery`,
+`useRef`, `useRoute`, `useSearchParams`, `useSeoMeta`, `useSessionStorage`,
+`useStore`, `useThrottle`, `useTimeout`, `useToggle`, `useWebSocket`.
 
 <!-- auto-imported:end -->
 
-A name not on that list is imported:
+Everything else needs an explicit import, and that is most of what the sections
+below list:
 
 ```ts
-import { useCounter } from '@stacksjs/composables'
+import { useStorage } from '@stacksjs/composables'
 ```
 
-**And the 27 are free only in the STX script entry.** The injection does not
-reach a TypeScript module that entry imports - bindings there do not leak into
-bundled module scope - so a `.ts` file beside your template imports every one
-of these explicitly, same as any other name. `AGENTS.md` states the same limit
-under Auto-imports. Referencing an uninjected name is a ReferenceError thrown
-before any binding applies, which takes the whole page down rather than
-degrading the one call.
+**`buddy typecheck` will not tell you which is which, and currently disagrees
+with the browser in both directions** (stacksjs/stacks#2585).
+`storage/framework/browser-auto-imports.json` feeds an ambient `.d.ts`, so the
+compiler accepts every name it declares - and only five of its 27 `use*` are in
+the runtime. `useStorage`, `useNow`, `useDateFormat`, `useForm` and the `use*Store`
+composables typecheck and then throw a ReferenceError during setup, which takes
+the page down rather than failing the one call. In the other direction
+`useLocalStorage`, `useColorMode`, `useCounter` and `useMediaQuery` all work in
+a template and `tsc` rejects them.
+
+The list above is the runtime's, so it is the one that predicts whether the page
+loads.
 
 ## Key Path
 - Core package: `storage/framework/core/composables/src/`
@@ -200,9 +202,11 @@ isRef(val)           // type guard
 - `and`, `or`, `logicNot`, `logicOr`
 
 ## Gotchas
-- Only 27 of the 154 composables are auto-imported in STX templates. Check
-  `storage/framework/browser-auto-imports.json` before relying on a bare name;
-  everything else needs `import { … } from '@stacksjs/composables'`
+- Only the names listed above are available bare in an STX template, and they
+  come from the stx runtime, not from `browser-auto-imports.json` - that
+  manifest is compile-time only and disagrees with the runtime in both
+  directions (stacksjs/stacks#2585). Everything else needs
+  `import { … } from '@stacksjs/composables'`
 - NEVER use vanilla JS (`var`, `document.*`, `window.*`) in STX `<script>` tags
 - Only use stx-compatible code: signals, composables, directives
 - Auto-imports defined in `storage/framework/browser-auto-imports.json`

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-models
-description: Use when working with data models in Stacks - the defineModel() API, model attributes with validation and factories, relationships (hasOne/hasMany/belongsTo/belongsToMany), traits (useAuth, useUuid, useTimestamps, useSearch, useApi, billable, taggable, categorizable, commentable, likeable, observe), computed properties (get/set), model generation, and the 102 built-in framework models. Covers model definitions and storage/framework/defaults/app/Models/.
+description: Use when working with data models in Stacks - the defineModel() API, model attributes with validation and factories, relationships (hasOne/hasMany/belongsTo/belongsToMany), traits (useAuth, useUuid, useTimestamps, useSearch, useApi, billable, taggable, categorizable, commentable, likeable, observe), computed properties (get/set), model generation, and the 103 built-in framework models. Covers model definitions and storage/framework/defaults/app/Models/.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript, SQLite >= 3.47.2
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -265,7 +265,7 @@ pass `--allow-protected` to override.
 ## Built-in models by category
 
 The ones below are worth knowing by name. They are a selection, not the set:
-`storage/framework/defaults/app/Models/` holds 102, and that directory is the
+`storage/framework/defaults/app/Models/` holds 103, and that directory is the
 authority. This section said "All 62 built-in models by category" while
 listing fewer than that against 102 on disk, so an agent reading to the end
 had no way to tell it was short.

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-orm
-description: Use when working with the Stacks ORM - defining models with defineModel(), model relationships (hasOne, hasMany, belongsTo, belongsToMany, morphOne, hasManyThrough), attributes, traits, factories, computed properties, query building, transactions, or the 102 built-in models. Covers @stacksjs/orm, storage/framework/orm/, and storage/framework/defaults/app/Models/.
+description: Use when working with the Stacks ORM - defining models with defineModel(), model relationships (hasOne, hasMany, belongsTo, belongsToMany, morphOne, hasManyThrough), attributes, traits, factories, computed properties, query building, transactions, or the 103 built-in models. Covers @stacksjs/orm, storage/framework/orm/, and storage/framework/defaults/app/Models/.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript, SQLite >= 3.47.2
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -11,7 +11,7 @@ allowed-tools: Read Edit Write Bash Grep Glob
 ## Key Paths
 - Core ORM package: `storage/framework/core/orm/src/`
 - ORM implementation: `storage/framework/orm/`
-- Model definitions: `storage/framework/defaults/app/Models/` (102 models)
+- Model definitions: `storage/framework/defaults/app/Models/` (103 models)
 - Application models: `app/Models/`
 - Default model templates: `storage/framework/defaults/app/Models/`
 - ORM type globals: `storage/framework/types/orm-globals.d.ts`

package/app/Models/Content/Categorizable.ts

@@ -0,0 +1,55 @@
+import { defineModel } from '@stacksjs/orm'
+import { schema } from '@stacksjs/validation'
+
+// The CMS catalogue already exists in categorizables. Commerce's Category
+// model owns a different table and its IDs cannot be used by this pivot.
+export default defineModel({
+  name: 'Categorizable',
+  table: 'categorizables',
+  primaryKey: 'id',
+  autoIncrement: true,
+  ownership: false,
+  traits: { useTimestamps: true },
+  indexes: [
+    { name: 'categorizables_type_slug_unique', columns: ['categorizable_type', 'slug'], unique: true },
+    { name: 'categorizables_owner_slug_unique', columns: ['categorizable_type', 'categorizable_id', 'slug'], unique: true },
+  ],
+  attributes: {
+    name: {
+      required: true,
+      fillable: true,
+      validation: { rule: schema.string() },
+    },
+    slug: {
+      required: true,
+      fillable: true,
+      validation: { rule: schema.string() },
+    },
+    description: {
+      required: false,
+      nullable: true,
+      fillable: true,
+      validation: { rule: schema.string() },
+    },
+    isActive: {
+      required: true,
+      fillable: true,
+      default: true,
+      validation: { rule: schema.boolean() },
+    },
+    categorizableId: {
+      // Runtime trait-table setup adds this column to older catalogues.
+      // Zero denotes a catalogue entry with no individual owner.
+      type: 'integer',
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: { rule: schema.number().integer().min(0) },
+    },
+    categorizableType: {
+      required: true,
+      fillable: true,
+      validation: { rule: schema.string() },
+    },
+  },
+} as const)

package/app/Models/Content/Post.ts

@@ -44,7 +44,7 @@ export default defineModel({
   belongsTo: ['Author', 'Site'],
   belongsToMany: {
     categories: {
-      model: 'Category',
+      model: 'Categorizable',
       table: 'categorizable_models',
       foreignKey: 'categorizable_id',
       relatedKey: 'category_id',

package/ide/vscode/package.json

@@ -2,7 +2,7 @@
   "publisher": "Stacks",
   "name": "vscode-stacks",
   "displayName": "Stacks",
-  "version": "0.74.43",
+  "version": "0.74.46",
   "description": "A modern Stacks development environment.",
   "license": "MIT",
   "funding": "https://github.com/sponsors/chrisbbreuer",

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/defaults",
   "type": "module",
   "sideEffects": false,
-  "version": "0.74.43",
+  "version": "0.74.46",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/stacksjs/stacks.git",
@@ -55,7 +55,7 @@
   "dependencies": {
     "@iconify-json/f7": "^1.2.2",
     "@iconify-json/hugeicons": "^1.2.27",
-    "@stacksjs/mobile": "^0.74.43",
+    "@stacksjs/mobile": "^0.74.46",
     "@stacksjs/sanitizer": "^0.2.113",
     "ts-qr-codes": "^0.1.8"
   }