@stacksjs/defaults 0.70.352 → 0.70.354

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

@@ -298,11 +298,34 @@ const wrappedHandler = withEvents('emails', originalHandler)
 ```
 
 ### OnQueueEvent Decorator
+Subscribes an **instance method** on `new`, with `this` bound to that instance.
+Declaring the class subscribes nothing, so the class has to be constructed — and
+the instance has to stay referenced, because the global emitter holds listeners
+weakly (a collected listener stops receiving events).
+
 ```typescript
 class MyHandler {
   @OnQueueEvent('job:failed')
   handleFailed(payload: QueueEventPayload) { ... }
 }
+
+// Required: subscription happens here, and this binding keeps it alive.
+export const myHandler = new MyHandler()
+
+// Deterministic teardown (otherwise it lasts as long as the instance does)
+getQueueEvents().unsubscribeListener(myHandler)
+```
+
+Rejected with a `TypeError` at class-definition time: static methods, fields,
+accessors and whole classes (no instance to bind to — use `onQueueEvent(...)`),
+and legacy `experimentalDecorators` decoration (no construction-time hook).
+
+### Listener Introspection
+```typescript
+const events = getQueueEvents()
+events.subscribeListener(obj, 'job:failed', fn)  // weak, `this` === obj
+events.unsubscribeListener(obj)                  // → count removed
+events.listenerCount('job:failed')               // live handlers ('*' for wildcards)
 ```
 
 ### QueueMetrics

package/app/Actions/Dashboard/Commerce/tax-rate-records.ts

@@ -19,6 +19,10 @@ export interface TaxRateRecord {
   region: TaxRateRegion
   status: 'active' | 'inactive'
   isDefault: boolean
+  /** Stable identifier application code matches on, independent of `name`. */
+  code: string
+  /** Whether a qualifying exemption stops this component being charged. */
+  exemptible: boolean
   createdAt: string
 }
 
@@ -50,6 +54,11 @@ export function normalizeTaxRateRecord(record: any): TaxRateRecord {
     ]),
     status: commerceEnum(commerceValue(record, 'status'), source, 'status', ['active', 'inactive']),
     isDefault: commerceBoolean(commerceValue(record, 'is_default', 'isDefault'), source, 'is_default'),
+    // Optional, both of them: a rate created before these columns existed has
+    // neither, and a dashboard that throws on an older row is worse than one
+    // that shows it without a badge.
+    code: String(commerceValue(record, 'code') ?? ''),
+    exemptible: Boolean(commerceValue(record, 'exemptible') ?? false),
     createdAt: commerceTimestamp(commerceValue(record, 'created_at', 'createdAt'), source),
   }
 }

package/app/Models/commerce/TaxRate.ts

@@ -111,6 +111,54 @@ export default defineModel({
       },
       factory: () => false,
     },
+
+    /**
+     * A stable name for this component, for code to reference.
+     *
+     * `name` is what an operator reads and edits in the dashboard, so it is
+     * the wrong thing for an application to branch on — renaming "State sales
+     * tax" to "Sales tax (CA)" should not change what gets charged. A code is
+     * the identifier that survives the rename.
+     *
+     * Free-form on purpose. What counts as a component differs by
+     * jurisdiction: `vat`, `gst`, `excise`, `city`, `eco-fee`.
+     */
+    code: {
+      order: 8,
+      fillable: true,
+      default: '',
+      validation: {
+        rule: schema.string().max(64),
+        message: {
+          max: 'Code must have a maximum of 64 characters',
+        },
+      },
+      factory: faker => faker.helpers.arrayElement(['vat', 'gst', 'sales', 'excise', 'city']),
+    },
+
+    /**
+     * Whether a qualifying exemption removes this component.
+     *
+     * Most places tax in parts, and an exemption usually lifts some of them
+     * and not others: groceries escape VAT but not a deposit levy, and a
+     * Californian medical cannabis patient is exempt from sales tax while
+     * still paying excise and the city's business tax. Modelling tax as one
+     * blended number cannot say that, so an app either over-charges the
+     * exempt customer or under-collects tax it owes.
+     *
+     * What *qualifies* is the application's business — a card, a resale
+     * certificate, a charity registration. This only records that the
+     * component is the kind that can be lifted.
+     */
+    exemptible: {
+      order: 9,
+      fillable: true,
+      default: false,
+      validation: {
+        rule: schema.boolean(),
+      },
+      factory: () => false,
+    },
   },
 
   dashboard: {

package/ide/vscode/package.json

@@ -2,7 +2,7 @@
   "publisher": "Stacks",
   "name": "vscode-stacks",
   "displayName": "Stacks",
-  "version": "0.70.352",
+  "version": "0.70.354",
   "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.70.352",
+  "version": "0.70.354",
   "description": "The complete managed Stacks application scaffold, including runtime defaults, AI guidance, editor metadata, and npm-backed project support files.",
   "author": "Chris Breuer",
   "license": "MIT",

package/resources/components/Dashboard/Commerce/CommerceTaxDialog.stx

@@ -15,6 +15,8 @@ const country = state('')
 const region = state('North America')
 const status = state<'active' | 'inactive'>('active')
 const isDefault = state(false)
+const code = state('')
+const exemptible = state(false)
 let hydrationKey = ''
 
 const regions = ['North America', 'South America', 'Europe', 'Asia', 'Africa', 'Oceania', 'Antarctica'] as const
@@ -36,6 +38,8 @@ effect(() => {
   region.set(current?.region || 'North America')
   status.set(current?.status || 'active')
   isDefault.set(current?.isDefault || false)
+  code.set(current?.code || '')
+  exemptible.set(current?.exemptible || false)
 })
 
 function submit(): void {
@@ -49,6 +53,8 @@ function submit(): void {
     region: region(),
     status: status(),
     isDefault: isDefault(),
+    code: code().trim(),
+    exemptible: exemptible(),
   })
 }
 
@@ -105,6 +111,11 @@ function errorMessages(): string[] {
               </select>
             </label>
           </div>
+          <label class="block">
+            <span class="font-medium text-gray-700 text-sm dark:text-neutral-200">Code</span>
+            <input x-model="code" type="text" placeholder="sales" class="mt-1 px-3 py-2 w-full font-mono text-gray-900 text-sm dark:text-white bg-white dark:bg-neutral-900 border border-gray-300 rounded-md dark:border-neutral-700" />
+            <span class="block mt-1 text-gray-500 text-xs dark:text-neutral-400">What the application matches on. Renaming the rate above does not change what is charged; changing this can.</span>
+          </label>
           <label class="flex gap-3 items-start p-3 border border-gray-200 rounded-lg dark:border-neutral-700">
             <input x-model="isDefault" type="checkbox" class="mt-0.5 h-4 w-4 text-blue-600 border-gray-300 rounded" />
             <span>
@@ -112,6 +123,18 @@ function errorMessages(): string[] {
               <span class="block mt-0.5 text-gray-500 text-xs dark:text-neutral-400">Selecting this clears the default flag from every other rate.</span>
             </span>
           </label>
+          {{--
+            Spelled out rather than labelled "exempt", because the two read
+            alike and mean opposite things: this marks the component as one an
+            exemption can lift, not one that is currently unpaid.
+          --}}
+          <label class="flex gap-3 items-start p-3 border border-gray-200 rounded-lg dark:border-neutral-700">
+            <input x-model="exemptible" type="checkbox" class="mt-0.5 h-4 w-4 text-blue-600 border-gray-300 rounded" />
+            <span>
+              <span class="block font-medium text-gray-700 text-sm dark:text-neutral-200">Can be exempted</span>
+              <span class="block mt-0.5 text-gray-500 text-xs dark:text-neutral-400">Customers who qualify for an exemption are not charged this component. Leave off for anything owed regardless — an excise or a city levy is usually still due.</span>
+            </span>
+          </label>
         </div>
       </div>
       <footer class="flex gap-2 justify-end px-6 py-4 bg-gray-50 dark:bg-neutral-900/50 border-gray-200 border-t dark:border-neutral-700">

package/resources/components/Dashboard/Commerce/CommerceTaxesDashboard.stx

@@ -16,6 +16,8 @@ interface TaxRateWritePayload {
   region: string
   status: 'active' | 'inactive'
   isDefault: boolean
+  code: string
+  exemptible: boolean
 }
 
 const emptySummary: TaxRateSummary = { total: 0, active: 0, countries: 0, averageRate: 0, defaultConflicts: 0 }
@@ -136,6 +138,8 @@ async function saveTax(payload: TaxRateWritePayload): Promise<void> {
     region: payload.region,
     status: payload.status,
     isDefault: payload.isDefault,
+    code: payload.code,
+    exemptible: payload.exemptible,
   }
 
   saving.set(true)

package/resources/components/Dashboard/Commerce/CommerceTaxesTable.stx

@@ -39,9 +39,17 @@ function formatDate(value: string): string {
         <template :for="record in records()" :key="record.id">
           <tr class="align-top">
             <td class="px-4 py-4">
-              <div class="flex gap-2 items-center">
+              <div class="flex flex-wrap gap-2 items-center">
                 <p class="font-medium text-gray-900 text-sm dark:text-white">{{ record.name }}</p>
                 <span :if="record.isDefault" class="px-2 py-0.5 font-medium text-blue-700 text-xs dark:text-blue-300 bg-blue-50 dark:bg-blue-950/40 rounded-full">Default</span>
+                {{--
+                  Both badges change what a customer is charged, so they sit
+                  next to the name rather than in a column someone has to
+                  scroll to. The code is what application code matches on;
+                  renaming the rate must not change the bill.
+                --}}
+                <span :if="record.code" class="px-2 py-0.5 font-mono text-gray-600 text-xs dark:text-neutral-300 bg-gray-100 dark:bg-neutral-700 rounded-full">{{ record.code }}</span>
+                <span :if="record.exemptible" class="px-2 py-0.5 font-medium text-amber-700 text-xs dark:text-amber-300 bg-amber-50 dark:bg-amber-950/40 rounded-full" title="Not charged to a customer who qualifies for an exemption">Exemptible</span>
               </div>
               <p class="mt-1 text-gray-500 text-xs dark:text-neutral-400">{{ record.type }}</p>
             </td>

package/resources/plugins/preloader.ts

@@ -128,6 +128,81 @@ if (!isRepl && !isPostinstall) {
 // eslint-disable-next-line antfu/no-top-level-await
 // await import('bun-plugin-stx')
 
+/**
+ * Whether a bare `@stacksjs/*` specifier resolves to something belonging to
+ * THIS project, and is therefore safe to import.
+ *
+ * A bare specifier resolves through node_modules, and when that is missing or
+ * half-installed bun falls back to its GLOBAL install cache. So a project with
+ * a broken install did not fail. It silently booted against whatever published
+ * version happened to be sitting in ~/.bun/install/cache, which is worse than
+ * loading nothing and completely invisible.
+ *
+ * It also hung, and that is how it was found. On Linux the first such
+ * cache-resolved import never settles: no rejection, no active handles, the
+ * process simply stops, so every stage of the preloader after it is silently
+ * unreachable. Both callers wrap their import in a `catch` that assumes a bad
+ * specifier fails FAST. That holds for one that cannot be resolved at all. It
+ * does not hold for one that resolves to a stale copy.
+ *
+ * ## Why this is a directory probe and not `Bun.resolveSync`
+ *
+ * The first version of this guard asked `Bun.resolveSync`, which answers the
+ * question exactly but pays full module resolution to do it. Measured on a
+ * Linux CI runner, a specifier that is NOT in `node_modules` cost **0.9 to 2.0
+ * seconds per call**, because bun walks the entire tree and then scans a global
+ * cache the install had just filled with 600+ packages. Twenty of those is 20
+ * to 40 seconds, so the guard turned a hang into a crawl and the preloader test
+ * kept timing out, intermittently, depending on how loaded the runner was.
+ *
+ * Locating the `node_modules/@stacksjs` directory once and then asking
+ * `existsSync` per package is the same question answered with stat calls:
+ * microseconds, and it never touches the global cache. The walk is memoised
+ * because the answer cannot change within a process.
+ *
+ * Accepted: a package present in this project's `@stacksjs` scope directory,
+ * which covers a real install and a vendored checkout alike (the framework's
+ * own core packages are symlinked into it). Anchored on `import.meta.dir`
+ * rather than the cwd, so running a command from a subdirectory does not change
+ * what loads.
+ */
+let stacksScopeDir: string | null | undefined
+
+async function findStacksScopeDir(): Promise<string | null> {
+  if (stacksScopeDir !== undefined)
+    return stacksScopeDir
+
+  const { existsSync } = await import('node:fs')
+  const { dirname, join } = await import('node:path')
+
+  let dir = import.meta.dir
+  for (;;) {
+    const candidate = join(dir, 'node_modules', '@stacksjs')
+    if (existsSync(candidate)) {
+      stacksScopeDir = candidate
+      return candidate
+    }
+    const parent = dirname(dir)
+    if (parent === dir)
+      break
+    dir = parent
+  }
+
+  stacksScopeDir = null
+  return null
+}
+
+async function belongsToThisProject(specifier: string): Promise<boolean> {
+  const scopeDir = await findStacksScopeDir()
+  if (!scopeDir)
+    return false
+
+  const { existsSync } = await import('node:fs')
+  const { join } = await import('node:path')
+
+  return existsSync(join(scopeDir, specifier.slice('@stacksjs/'.length)))
+}
+
 // Auto-import ALL Stacks framework modules into globalThis
 // This allows using Action, response, Activity, etc. without ANY imports.
 // Exported so server entrypoints (e.g. `dev/api.ts`) can opt back in
@@ -190,6 +265,12 @@ export async function loadAutoImports() {
   ]
 
   for (const pkg of stacksPackages) {
+    // See `belongsToThisProject`. Skipping is what the `catch` below always
+    // meant to do; it just never got the chance for a specifier that resolves
+    // to a stale copy instead of failing.
+    if (!(await belongsToThisProject(pkg)))
+      continue
+
     try {
       const module = await import(pkg)
       for (const [name, value] of Object.entries(module)) {
@@ -347,12 +428,14 @@ if (!skipAutoImports) {
   await loadAutoImports()
 
   // Run package auto-discovery after all imports are loaded
-  try {
-    const actionsPackage = '@stacksjs/' + 'actions'
-    const { discoverPackages } = await import(actionsPackage)
-    await discoverPackages()
-  }
-  catch {
-    // Discovery may fail during early bootstrap — not critical
+  const actionsPackage = '@stacksjs/' + 'actions'
+  if (await belongsToThisProject(actionsPackage)) {
+    try {
+      const { discoverPackages } = await import(actionsPackage)
+      await discoverPackages()
+    }
+    catch {
+      // Discovery may fail during early bootstrap — not critical
+    }
   }
 }

package/views/dashboard/layouts/default.stx

@@ -620,9 +620,9 @@ onDestroy(() => {
     theme="macos"
     width="250"
     placement="fixed"
-    persist-key="stacks-dashboard-sidebar"
-    shell-selector="[data-stx-content]"
-    :follow-system-appearance="false"
+    persistKey="stacks-dashboard-sidebar"
+    shellSelector="[data-stx-content]"
+    :followSystemAppearance="false"
     @itemClick="handleSidebarItemClick($event)"
   >
     <template #header>
@@ -630,7 +630,7 @@ onDestroy(() => {
           titlebarHidden), so this reserves their space and acts as the window
           drag region; in a plain browser it is the same empty strip macOS
           sidebars carry above their first row. -->
-      <SidebarHeader :show-window-controls="false" />
+      <SidebarHeader :showWindowControls="false" />
     </template>
   </Sidebar>
 </div>