@quazardous/qdadm 2.10.0 → 2.12.0

package/README.md

@@ -2,143 +2,33 @@
 
 **Vue 3 admin framework. PrimeVue. Zero boilerplate.**
 
-Quick start: [README](https://github.com/quazardous/qdadm/blob/main/README.md) (5 min tutorial)
-
-Concepts & patterns: [QDADM_CREDO](https://github.com/quazardous/qdadm/blob/main/packages/qdadm/QDADM_CREDO.md)
-
-Changelog: [CHANGELOG](https://github.com/quazardous/qdadm/blob/main/CHANGELOG.md)
-
 ## Installation
 
 ```bash
-npm install @quazardous/qdadm primevue @primeuix/themes
-```
-
-## Exports
-
-```js
-// Core
-import { Kernel, EntityManager } from '@quazardous/qdadm'
-
-// Storage backends
-import { MockApiStorage, ApiStorage, SdkStorage } from '@quazardous/qdadm'
-
-// Auth
-import { SessionAuthAdapter, LocalStorageSessionAuthAdapter } from '@quazardous/qdadm'
-
-// Security (permissions, roles)
-import { SecurityChecker, PermissionMatcher, PermissionRegistry } from '@quazardous/qdadm/security'
-import { PersistableRoleProvider, createLocalStorageRolesProvider } from '@quazardous/qdadm/security'
-
-// Composables
-import { useBareForm, useListPage } from '@quazardous/qdadm/composables'
-
-// Components
-import { ListPage, PageLayout, AppLayout, FormField, FormActions } from '@quazardous/qdadm/components'
-
-// Module system
-import { KernelContext } from '@quazardous/qdadm/module'
-
-// Styles
-import '@quazardous/qdadm/styles'
-```
-
-## ctx.crud() - Route Helper
-
-Register CRUD routes + navigation in one call:
-
-```js
-class BooksModule extends Module {
-  async connect(ctx) {
-    ctx.entity('books', { ... })
-
-    // Full CRUD with single form
-    ctx.crud('books', {
-      list: () => import('./pages/BookList.vue'),
-      form: () => import('./pages/BookForm.vue')  // create + edit
-    }, {
-      nav: { section: 'Library', icon: 'pi pi-book' }
-    })
-
-    // List only (read-only entity)
-    ctx.crud('settings', {
-      list: () => import('./pages/SettingsPage.vue')
-    }, { nav: { section: 'Config', icon: 'pi pi-cog' } })
-  }
-}
+npm install @quazardous/qdadm primevue @primeuix/themes primeicons vue-router pinia
 ```
 
-Auto-generates: routes, route family, nav item. Use `ctx.routes()` for custom pages.
-
-## SdkStorage
-
-Adapter for generated SDK clients (hey-api, openapi-generator, etc.):
-
-```js
-import { SdkStorage } from '@quazardous/qdadm'
+```ts
+// vite.config.ts — the plugin wires the resolver/optimizer settings
+// qdadm's raw-source packaging needs (npm and file:/workspace installs)
+import { qdadmVitePlugin } from '@quazardous/qdadm/vite'
 
-const storage = new SdkStorage({
-  sdk,
-  methods: {
-    list: 'getApiBooks',
-    get: 'getApiBooksById',
-    create: 'postApiBooks',
-    update: 'patchApiBooksById',
-    delete: 'deleteApiBooksById'
-  }
+export default defineConfig({
+  plugins: [vue(), qdadmVitePlugin()],
 })
 ```
 
-Options: `transformRequest`, `transformResponse`, `responseFormat`, `clientSidePagination`.
-
 ## Documentation
 
-| Doc | Purpose |
-|-----|---------|
-| [QDADM_CREDO](https://github.com/quazardous/qdadm/blob/main/packages/qdadm/QDADM_CREDO.md) | Philosophy, patterns, concepts |
-| [Page compositions](https://github.com/quazardous/qdadm/blob/main/docs/page-compositions.md) | **Start here** — which composition for which need |
-| [CRUD Pages](https://github.com/quazardous/qdadm/blob/main/docs/crud.md) | List / form / show / child pages reference |
-| [Navigation](https://github.com/quazardous/qdadm/blob/main/docs/navigation.md) | Breadcrumb, sibling navlinks, View↔Edit toggle |
-| [Architecture](https://github.com/quazardous/qdadm/blob/main/docs/architecture.md) | PAC pattern, layers |
-| [Extension](https://github.com/quazardous/qdadm/blob/main/docs/extension.md) | Decorators, bundles, multi-storage |
-| [Hooks](https://github.com/quazardous/qdadm/blob/main/docs/hooks.md) | Alter / invoke registry |
-| [Signals](https://github.com/quazardous/qdadm/blob/main/docs/signals.md) | Event bus, SSE bridge |
-| [Zones](https://github.com/quazardous/qdadm/blob/main/docs/zones.md) | Extensible UI blocks |
-| [Security](https://github.com/quazardous/qdadm/blob/main/docs/security.md) | Permissions, roles |
-| [i18n](https://github.com/quazardous/qdadm/blob/main/docs/i18n.md) | Messages, providers, strategies |
-| [Codegen](https://github.com/quazardous/qdadm/blob/main/docs/gen.md) | Generate managers (OpenAPI / manual) |
-| [Deferred](https://github.com/quazardous/qdadm/blob/main/docs/deferred.md) | Deferred values & warmup |
-| [AGENT_GUIDE](https://github.com/quazardous/qdadm/blob/main/docs/AGENT_GUIDE.md) | Quick index for AI agents |
-
-## Peer Dependencies
-
-- vue ^3.3.0
-- vue-router ^4.0.0
-- primevue ^4.0.0
-- pinia ^2.0.0
-
-## Consuming via `file:` link from a sibling monorepo
+Start with the **[step-by-step tutorial](https://github.com/quazardous/qdadm/blob/main/docs/tutorial-mini-admin.md)** — bootstrap, CRUD, auth, navigation, parent-child in ~310 lines.
 
-If you install qdadm with a `file:../path/to/qdadm` link instead of from npm — typically during local development on qdadm itself, or before a release lands — pnpm/npm resolves the symlink into the qdadm-monorepo's hoisted `node_modules`. That can pull a *second* copy of `primevue` (and `vue`, `vue-router`, `@primeuix/themes`) into your host bundle even though qdadm itself only declares them as peers.
+- [Full documentation](https://github.com/quazardous/qdadm/tree/main/docs)
+- [Concepts & patterns (CREDO)](https://github.com/quazardous/qdadm/blob/main/docs/QDADM_CREDO.md)
+- [Changelog](https://github.com/quazardous/qdadm/blob/main/CHANGELOG.md)
 
-Symptom: PrimeVue components render without their Aura preset tokens — component-level CSS variables (`--p-paginator-nav-button-width`, etc.) end up undefined, so paginator buttons collapse to 16×16, datatables lose padding, rounded corners disappear. Plugin singletons rely on a shared runtime registry; two instances split the registry in half.
-
-Fix in the host's bundler config — `dedupe` collapses duplicates back to a single resolved copy:
-
-```ts
-// vite.config.ts
-export default defineConfig({
-  resolve: {
-    dedupe: ['vue', 'vue-router', 'primevue', '@primeuix/themes'],
-  },
-})
-```
-
-This is the canonical Vite/Webpack pattern for Vue plugin singletons. The `file:` link can stay in place — useful for hot-reload during qdadm development — and the dedupe ensures only one instance of each peer ends up in the bundle.
-
-Installing qdadm from npm (`@quazardous/qdadm@^1.19.3`) doesn't have this issue: the published tarball ships no `node_modules/`, so peers always resolve from the host. The trap is specific to `file:` / `workspace:` links onto a package that lives inside another monorepo.
+## Peer Dependencies
 
-One more caveat: qdadm ships TypeScript sources, so with a `file:` link your `vue-tsc` / lint / test counters measure qdadm's **working tree**, not a released version. Any local qdadm edit moves your numbers with zero change on your side — don't calibrate quality ratchets or CI thresholds against a linked checkout; pin them to the published package your CI actually installs.
+vue ^3.3 · vue-router ^4 || ^5 · primevue ^4 · pinia ^2 || ^3 || ^4
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quazardous/qdadm",
-  "version": "2.10.0",
+  "version": "2.12.0",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",
@@ -35,10 +35,14 @@
     "./module": "./src/module/index.ts",
     "./utils": "./src/utils/index.ts",
     "./modules/debug": "./src/modules/debug/index.ts",
-    "./styles": "./src/styles/index.scss",
+    "./styles": {
+      "types": "./src/styles/index.d.ts",
+      "default": "./src/styles/index.scss"
+    },
     "./styles/variables": "./src/styles/_variables.scss",
     "./gen": "./src/gen/index.ts",
     "./gen/vite-plugin": "./src/gen/vite-plugin.ts",
+    "./vite": "./src/vite/qdadmPlugin.ts",
     "./vite-plugin-debug": "./src/vite/qdadmDebugPlugin.ts"
   },
   "files": [
@@ -48,6 +52,7 @@
   ],
   "dependencies": {
     "@quazardous/qdcore": "^1.0.0",
+    "@types/pluralize": "^0.0.33",
     "@quazardous/qddebug": "^1.0.0",
     "@quazardous/quarkernel": "^2.1.0",
     "pluralize": "^8.0.0",

package/src/chain/StackHydrator.ts

@@ -54,7 +54,6 @@ export interface HydratedPayload {
 }
 
 export class StackHydrator implements Hydrator<EntityStackLevel, HydratedLevel> {
-  private _activeStack: ActiveStack
   private _orchestrator: Orchestrator
   private _signalBus: SignalBus | null
   private _levels: HydratedLevel[] = []
@@ -62,11 +61,10 @@ export class StackHydrator implements Hydrator<EntityStackLevel, HydratedLevel>
   private _unsubscribe: (() => void) | null = null
 
   constructor(
-    activeStack: ActiveStack,
+    _activeStack: ActiveStack,
     orchestrator: Orchestrator,
     signalBus: SignalBus | null = null
   ) {
-    this._activeStack = activeStack
     this._orchestrator = orchestrator
     this._signalBus = signalBus
 

package/src/components/dialogs/MultiStepDialog.vue

@@ -269,7 +269,7 @@ const slotActions = computed<SlotActions>(() => ({
         <!-- Step panels -->
         <StepPanels>
           <StepPanel
-            v-for="(stepDef, idx) in steps"
+            v-for="(_, idx) in steps"
             :key="idx"
             :value="idx + 1"
           >

package/src/components/edit/FormInput.vue

@@ -28,18 +28,23 @@ interface SelectOption {
 
 interface FieldConfig {
   name: string
-  type?: InputType
+  /** Known widget types get dedicated rendering; other strings (e.g. from
+   *  ResolvedFieldConfig, #1387) fall back to the text input. */
+  type?: InputType | (string & {})
   placeholder?: string
   disabled?: boolean
   readonly?: boolean
-  options?: SelectOption[]
+  options?: SelectOption[] | unknown[]
   optionLabel?: string
   optionValue?: string
 }
 
 const props = defineProps({
   field: { type: Object as PropType<FieldConfig>, required: true },
-  modelValue: { type: [String, Number, Boolean, Date, Object] as PropType<ModelValue>, default: null },
+  // unknown: v-model over Record<string, unknown> indexes (the documented
+  // generateFields loop) must bind without casts (#1387)
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  modelValue: { type: null as unknown as PropType<any>, default: null },
   hint: { type: String as () => InputType | null, default: null }  // Optional type hint override
 })
 
@@ -48,7 +53,7 @@ const emit = defineEmits<{
 }>()
 
 const value = computed<ModelValue>({
-  get: (): ModelValue => props.modelValue,
+  get: (): ModelValue => (props.modelValue ?? null) as ModelValue,
   set: (v: ModelValue): void => emit('update:modelValue', v)
 })
 
@@ -64,17 +69,17 @@ const numberValue = computed<number | null>({
 })
 
 const booleanValue = computed<boolean>({
-  get: (): boolean => (props.modelValue as boolean) ?? false,
+  get: (): boolean => (props.modelValue as boolean | null | undefined) ?? false,
   set: (v: boolean): void => emit('update:modelValue', v)
 })
 
 // Resolve component type: field.type > hint > 'text'
-const inputType = computed<InputType>(() => props.field?.type || props.hint || 'text')
+const inputType = computed<InputType>(() => (props.field?.type as InputType) || props.hint || 'text')
 
 // Date value with string ↔ Date conversion for DatePicker
 const dateValue = computed<Date | null>({
   get: (): Date | null => {
-    const v = props.modelValue
+    const v = props.modelValue as string | Date | null
     if (!v) return null
     if (v instanceof Date) return v
     // Convert ISO string to Date

package/src/components/layout/AppLayout.vue

@@ -16,6 +16,7 @@ import { ref, watch, onMounted, onUnmounted, computed, inject, provide, useSlots
 import { SIDEBAR_COLLAPSED_KEY } from '../../composables/useSidebarState'
 import { RouterLink, RouterView, useRouter, useRoute } from 'vue-router'
 import { useNavigation, type NavSection } from '../../composables/useNavigation'
+import { prettifyRole } from '../../utils/formatters'
 import { useApp } from '../../composables/useApp'
 import { useAuth } from '../../composables/useAuth'
 import { useGuardDialog } from '../../composables/useGuardStore'
@@ -210,7 +211,9 @@ const userDisplayName = computed<string>(() => {
 
 const userSubtitle = computed<string>(() => {
   const userData = user.value as UserData | null
-  return userData?.email || userData?.role || ''
+  if (userData?.email) return userData.email
+  // raw ROLE_* constants are ugly by default — prettify (#1388)
+  return userData?.role ? prettifyRole(userData.role) : ''
 })
 
 async function handleLogout(): Promise<void> {

package/src/components/layout/defaults/DefaultUserInfo.vue

@@ -9,6 +9,7 @@
  */
 import { computed, type ComputedRef } from 'vue'
 import { useRouter } from 'vue-router'
+import { prettifyRole } from '../../../utils/formatters'
 import { useAuth } from '../../../composables/useAuth'
 import Button from 'primevue/button'
 
@@ -37,7 +38,9 @@ const userDisplayName: ComputedRef<string> = computed(() => {
 })
 
 const userSubtitle: ComputedRef<string> = computed(() => {
-  return userData.value?.email || userData.value?.role || ''
+  if (userData.value?.email) return userData.value.email
+  // raw ROLE_* constants are ugly by default — prettify (#1388)
+  return userData.value?.role ? prettifyRole(userData.value.role) : ''
 })
 
 function handleLogout(): void {

package/src/components/show/ShowDisplay.vue

@@ -62,6 +62,8 @@ interface FieldConfig {
   dateFormat?: string
   currencyCode?: string
   locale?: string
+  /** false → no locale digit grouping for number fields (years, ids) (#1388) */
+  useGrouping?: boolean
   booleanLabels?: { true: string; false: string }
   // Reference options
   reference?: string
@@ -107,7 +109,10 @@ const numberValue = computed(() => {
   if (isEmpty.value) return '-'
   const num = Number(props.value)
   if (isNaN(num)) return String(props.value)
-  return formatNumber(num, {}, props.field.locale)
+  // useGrouping: false → no locale digit grouping (years, ids… "1965",
+  // not "1 965") (#1388)
+  const opts = props.field.useGrouping === false ? { useGrouping: false } : {}
+  return formatNumber(num, opts, props.field.locale)
 })
 
 // Format currency value

package/src/components/show/ShowField.vue

@@ -27,7 +27,9 @@ const props = defineProps({
   // Field config (for auto-display mode)
   field: { type: Object as PropType<FieldConfig | null>, default: null },
   // Value (for auto-display mode)
-  value: { type: [String, Number, Boolean, Date, Object, Array], default: null },
+  // unknown: show.data.value?.[f.name] over the default Record generic (#1387)
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  value: { type: null as unknown as PropType<any>, default: null },
   // Manual props (override field config)
   name: { type: String, default: '' },
   label: { type: String, default: '' },

package/src/composables/useAuth.ts

@@ -61,8 +61,10 @@ export function useAuth(): UseAuthReturn {
     throw new Error('[qdadm] useAuth() must be called within component setup()')
   }
 
-  const auth = inject<AuthAdapter | null>('authAdapter')
-  const features = inject<FeaturesConfig | null>('qdadmFeatures')
+  // null defaults: a no-auth app must not log "injection not found" warnings
+  // on every page (#1388)
+  const auth = inject<AuthAdapter | null>('authAdapter', null)
+  const features = inject<FeaturesConfig | null>('qdadmFeatures', null)
 
   // If auth disabled or not provided, return neutral values
   if (!features?.auth || !auth) {

package/src/composables/useEntityItemFormPage.types.ts

@@ -271,7 +271,7 @@ export interface UseEntityItemFormPageReturn<T extends Record<string, unknown> =
   // Parent chain (from route.meta.parent, supports N-level nesting)
   parentConfig: ComputedRef<ParentConfig | null>
   parentId: ComputedRef<string | number | null>
-  parentData: ComputedRef<unknown | null>
+  parentData: ComputedRef<Record<string, unknown> | null>
   parentChain: Ref<Map<number, unknown>>
   getChainDepth: (config?: ParentConfig | null) => number
 

package/src/composables/useEntityItemPage.ts

@@ -103,8 +103,8 @@ export interface UseEntityItemPageReturn<T = unknown> {
   // Parent chain
   parentConfig: ComputedRef<ParentConfig | null>
   parentId: ComputedRef<string | number | null>
-  parentData: ComputedRef<unknown | null>
-  parentChain: Ref<Map<number, unknown>>
+  parentData: ComputedRef<Record<string, unknown> | null>
+  parentChain: Ref<Map<number, Record<string, unknown>>>
   parentLoading: Ref<boolean>
   loadParent: () => Promise<void>
   loadParentChain: () => Promise<void>
@@ -189,7 +189,7 @@ export function useEntityItemPage<T = unknown>(config: UseEntityItemPageOptions<
    * Loaded parent entities data (Map: level -> data)
    * Level 1 = immediate parent, Level 2 = grandparent, etc.
    */
-  const parentChain = ref<Map<number, unknown>>(new Map())
+  const parentChain = ref<Map<number, Record<string, unknown>>>(new Map())
   const parentLoading = ref(false)
 
   /**
@@ -228,7 +228,7 @@ export function useEntityItemPage<T = unknown>(config: UseEntityItemPageOptions<
     if (!parentConfig.value || !parentId.value) return
 
     parentLoading.value = true
-    const newChain = new Map<number, unknown>()
+    const newChain = new Map<number, Record<string, unknown>>()
 
     try {
       // Calculate total depth to set correct breadcrumb levels
@@ -251,7 +251,7 @@ export function useEntityItemPage<T = unknown>(config: UseEntityItemPageOptions<
 
         const loadedData = await parentManager.get(parentEntityId)
         if (loadedData) {
-          newChain.set(level, loadedData)
+          newChain.set(level, loadedData as Record<string, unknown>)
 
           // Update active stack
           hydrator.setEntityData(currentConfig.entity, loadedData)

package/src/composables/useEntityItemShowPage.ts

@@ -257,7 +257,7 @@ interface ConfirmService {
   }) => void
 }
 
-export function useEntityItemShowPage<T = unknown>(
+export function useEntityItemShowPage<T = Record<string, unknown>>(
   options: UseEntityItemShowPageOptions<T>
 ): UseEntityItemShowPageReturn<T> {
   const { entity, loadOnMount = true, transformLoad, onLoadSuccess, onLoadError } = options

package/src/composables/useNavContext.ts

@@ -409,10 +409,19 @@ export function useNavContext(_options: UseNavContextOptions = {}): UseNavContex
     )
     for (const sibling of siblings) {
       const sibManager = sibling.meta?.entity ? getManager(sibling.meta.entity as string) : null
+      // Only pass the params the sibling path declares — forwarding the full
+      // current params (e.g. the child item id on an edit page) triggers
+      // vue-router's "Discarded invalid param(s)" warning (#1388)
+      const declared = new Set(
+        (String(sibling.path || '').match(/:([A-Za-z0-9_]+)/g) || []).map((m) => m.slice(1))
+      )
+      const params = declared.size
+        ? Object.fromEntries(Object.entries(route.params).filter(([k]) => declared.has(k)))
+        : route.params
       links.push({
         label:
           (sibling.meta?.navLabel as string) || sibManager?.labelPlural || (sibling.name as string),
-        to: { name: sibling.name as string, params: route.params as RouteParamsRawGeneric },
+        to: { name: sibling.name as string, params: params as RouteParamsRawGeneric },
         active: route.name === sibling.name,
       })
     }

package/src/entity/auth/SecurityChecker.ts

@@ -53,6 +53,8 @@ export interface SecurityCheckerConfig {
 export class SecurityChecker {
   protected _rolesProvider: RoleProvider
   readonly getCurrentUser: () => AuthUser | null
+  /** Roles already warned about (warn-once, #1388) */
+  protected _warnedRoles = new Set<string>()
 
   constructor({ rolesProvider, roleHierarchy, rolePermissions, getCurrentUser }: SecurityCheckerOptions) {
     if (rolesProvider) {
@@ -134,6 +136,7 @@ export class SecurityChecker {
         const rolePerms = this._rolesProvider.getPermissions(r)
         rolePerms.forEach((p) => perms.add(p))
       }
+      this._warnUnknownRole(role)
     }
 
     // User-specific permission overrides
@@ -144,6 +147,26 @@ export class SecurityChecker {
     return [...perms]
   }
 
+  /**
+   * A user role that matches NO configured role silently yields zero
+   * permissions (e.g. `admin` instead of `ROLE_ADMIN`) — surface it once
+   * per role so the misconfiguration is debuggable (#1388).
+   */
+  protected _warnUnknownRole(role: string): void {
+    if (this._warnedRoles.has(role)) return
+    const known = this._rolesProvider.getRoles()
+    if (known.includes(role)) return
+    // Hierarchy-only roles (declared in role_hierarchy without own
+    // permissions) still count as known.
+    if (Object.keys(this._rolesProvider.getHierarchy()).includes(role)) return
+    this._warnedRoles.add(role)
+    console.warn(
+      `[qdadm] SecurityChecker: user role "${role}" matches no configured role ` +
+        `(known: ${known.join(', ') || 'none'}) — the user gets NO permissions. ` +
+        `Roles must match role_permissions/role_hierarchy keys exactly.`
+    )
+  }
+
   /**
    * Check if user can assign a role to another user
    */

package/src/entity/storage/MockApiStorage.ts

@@ -13,6 +13,10 @@ export interface MockApiStorageOptions<T extends EntityRecord = EntityRecord> {
   generateId?: () => string
   initialData?: T[] | null
   authCheck?: (() => boolean) | null
+  /** Override the localStorage key (default `mockapi_${entityName}_data`).
+   *  Needed when several apps sharing an origin use the same entity names
+   *  (e.g. multiple demos on one GitHub Pages site) (#1382). */
+  storageKey?: string
 }
 
 /**
@@ -63,6 +67,7 @@ export class MockApiStorage<T extends EntityRecord = EntityRecord> extends IStor
       generateId = defaultGenerateId,
       initialData = null,
       authCheck = null,
+      storageKey = null,
     } = options
 
     if (!entityName) {
@@ -72,7 +77,7 @@ export class MockApiStorage<T extends EntityRecord = EntityRecord> extends IStor
     this.entityName = entityName
     this.idField = idField
     this.generateId = generateId
-    this._storageKey = `mockapi_${entityName}_data`
+    this._storageKey = storageKey || `mockapi_${entityName}_data`
     this._data = new Map()
     this._authCheck = authCheck
 

package/src/kernel/Kernel.registries.ts

@@ -117,6 +117,16 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
 
     if (!security) return
 
+    // security configured but no user source: every isGranted() falls back
+    // to permissive — a newcomer believes gating is on when it isn't (#1388)
+    if (!entityAuthAdapter) {
+      console.warn(
+        '[Kernel] security is configured but entityAuthAdapter is not — entity ' +
+          'permission checks default to PERMISSIVE (no current user to check). ' +
+          'Pass entityAuthAdapter (e.g. `() => authAdapter.getUser()`) to enable gating.'
+      )
+    }
+
     let rolesProvider = security.rolesProvider
     if (!rolesProvider && (security.role_permissions || security.role_hierarchy)) {
       rolesProvider = new StaticRoleProvider({

package/src/kernel/Kernel.types.ts

@@ -21,7 +21,9 @@ export interface AuthAdapter {
   getToken?(): string | null
   logout?(): void
   connectSignals?(signals: SignalBus): () => void
-  [key: string]: unknown
+  // NOTE: no string index signature here — class instances (e.g. a
+  // LocalStorageSessionAuthAdapter subclass, the documented pattern) do not
+  // satisfy implicit index signatures and would stop being assignable (#1387).
 }
 
 /**
@@ -161,7 +163,12 @@ export interface KernelOptions {
   storageResolver?: (config: unknown, entityName: string) => unknown
   managerResolver?: (config: unknown, entityName: string, context: unknown) => EntityManager
   authAdapter?: AuthAdapter | null
-  entityAuthAdapter?: EntityAuthAdapter | string | Record<string, unknown> | null
+  entityAuthAdapter?:
+    | EntityAuthAdapter
+    | string
+    | Record<string, unknown>
+    | (() => Record<string, unknown> | null)
+    | null
   authTypes?: Record<string, unknown>
   pages?: Pages
   homeRoute?: HomeRoute

package/src/kernel/ModuleLoader.ts

@@ -151,7 +151,6 @@ export class ModuleLoadError extends Error {
  */
 class ObjectModuleAdapter implements ModuleLike {
   private _def: ObjectModuleDefinition
-  private _ctx: ModuleContext | null = null
 
   constructor(def: ObjectModuleDefinition) {
     this._def = def
@@ -177,7 +176,6 @@ class ObjectModuleAdapter implements ModuleLike {
   }
 
   async connect(ctx: ModuleContext): Promise<void> {
-    this._ctx = ctx
     if (typeof this._def.connect === 'function') {
       await this._def.connect(ctx)
     }
@@ -187,7 +185,6 @@ class ObjectModuleAdapter implements ModuleLike {
     if (typeof this._def.disconnect === 'function') {
       await this._def.disconnect()
     }
-    this._ctx = null
   }
 }
 
@@ -201,7 +198,6 @@ class ObjectModuleAdapter implements ModuleLike {
 class ClassModuleAdapter implements ModuleLike {
   private _ClassDef: ModuleClassConstructor
   private _instance: ModuleLike
-  private _ctx: ModuleContext | null = null
 
   constructor(ClassDef: ModuleClassConstructor) {
     this._ClassDef = ClassDef
@@ -237,7 +233,6 @@ class ClassModuleAdapter implements ModuleLike {
   }
 
   async connect(ctx: ModuleContext): Promise<void> {
-    this._ctx = ctx
     if (typeof this._instance.connect === 'function') {
       await this._instance.connect(ctx)
     }
@@ -247,7 +242,6 @@ class ClassModuleAdapter implements ModuleLike {
     if (typeof this._instance.disconnect === 'function') {
       await this._instance.disconnect()
     }
-    this._ctx = null
   }
 }
 

package/src/orchestrator/Orchestrator.ts

@@ -434,8 +434,8 @@ export function createOrchestrator(options?: OrchestratorOptions): Orchestrator
 // ============================================================================
 type _AssertManagerLike<T extends EntityManagerLike> = T
 type _AssertOrchestratorLike<T extends OrchestratorLike> = T
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-type _LikeChecks = [
+// (exported so strict consumer typechecks don't flag it unused, #1386)
+export type _LikeChecks = [
   _AssertManagerLike<EntityManager>,
   _AssertOrchestratorLike<Orchestrator>,
 ]

package/src/query/FilterQuery.ts

@@ -107,7 +107,6 @@ export class FilterQuery<T = unknown> {
   toQuery: ((value: unknown) => Record<string, unknown>) | null
 
   private _options: FilterOption[] | null = null
-  private _signals: SignalBusLike | null = null
   private _subscriptions: Array<() => void> = []
 
   constructor(options: FilterQueryOptions<T>) {
@@ -164,8 +163,6 @@ export class FilterQuery<T = unknown> {
     // Clean up existing subscriptions if any
     this._cleanupSubscriptions()
 
-    this._signals = signals
-
     if (!signals) return this
 
     // Subscribe to entity CRUD signals for cache invalidation
@@ -200,7 +197,6 @@ export class FilterQuery<T = unknown> {
    */
   dispose(): void {
     this._cleanupSubscriptions()
-    this._signals = null
     this._options = null
   }
 

package/src/security/EntityRolesProvider.ts

@@ -88,7 +88,6 @@ export class EntityRoleProvider extends RoleProvider {
   private _inheritsField: string
 
   private _cache: RoleCache | null = null
-  private _ctx: RoleProviderContext | null = null
   private _orchestrator: Orchestrator | null = null
   private _signalCleanup: (() => void) | null = null
   private _loading: Promise<void> | null = null
@@ -106,7 +105,6 @@ export class EntityRoleProvider extends RoleProvider {
    * Install adapter (called by Kernel after orchestrator ready)
    */
   install(ctx: RoleProviderContext): void {
-    this._ctx = ctx
     this._orchestrator = ctx.orchestrator as Orchestrator
 
     // Auto-invalidate on role changes
@@ -125,7 +123,6 @@ export class EntityRoleProvider extends RoleProvider {
       this._signalCleanup()
       this._signalCleanup = null
     }
-    this._ctx = null
     this._orchestrator = null
     this._cache = null
     this._loading = null

package/src/styles/index.d.ts

@@ -0,0 +1,5 @@
+// Type companion for the `@quazardous/qdadm/styles` export (#1386).
+// The export resolves to a .scss file, which TypeScript cannot see through
+// the exports map — this empty module makes the side-effect import
+// `import '@quazardous/qdadm/styles'` typecheck in strict consumers.
+export {}

package/src/types/index.ts

@@ -84,6 +84,8 @@ export interface FieldConfig {
   type: FieldType
   label?: string
   required?: boolean
+  /** number fields: false → no locale digit grouping in displays (#1388) */
+  useGrouping?: boolean
   default?: unknown | (() => unknown)
   options?: Array<{ label: string; value: unknown }>
   reference?: {
@@ -108,6 +110,10 @@ export interface FieldConfig {
 export interface ChildConfig {
   entity: string
   endpoint?: string
+  /** FK field on the child pointing at this entity (documented README shape, #1387) */
+  foreignKey?: string
+  /** Label for child navlinks/tabs */
+  label?: string
 }
 
 /**

package/src/utils/formatters.ts

@@ -203,3 +203,17 @@ export function formatPercent(value: number | null | undefined, decimals = 1): s
   if (value === null || value === undefined) return '-'
   return `${(value * 100).toFixed(decimals)}%`
 }
+
+/**
+ * Prettify a role constant for display when no role_labels entry exists:
+ * ROLE_SUPER_USER → "Super User" (#1388).
+ */
+export function prettifyRole(role: string): string {
+  return role
+    .replace(/^ROLE_/, '')
+    .toLowerCase()
+    .split('_')
+    .filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ')
+}

package/src/vite/qdadmPlugin.ts

@@ -0,0 +1,97 @@
+/**
+ * qdadm Vite consumer plugin (#1385)
+ *
+ * qdadm publishes raw TS/.vue sources. Without help, Vite pre-bundles the
+ * host app's `primevue` import into `.vite/deps` while qdadm's raw sources
+ * import `node_modules/primevue/...` directly — two module instances whose
+ * injection symbols don't match, and the app dies at boot with
+ * `Error: No PrimeVue Toast provided!`.
+ *
+ * This plugin applies the required config in one line:
+ *
+ * ```ts
+ * // vite.config.ts
+ * import { qdadmVitePlugin } from '@quazardous/qdadm/vite'
+ *
+ * export default defineConfig({
+ *   plugins: [vue(), qdadmVitePlugin()],
+ * })
+ * ```
+ *
+ * - `resolve.dedupe` collapses duplicate peer copies (also covers the
+ *   `file:`/workspace-link scenario described in the package README).
+ * - `optimizeDeps.exclude` keeps primevue/@primeuix/themes/qdadm out of the
+ *   pre-bundle so BOTH pipelines resolve the same raw modules. Excluding
+ *   qdadm also keeps HMR sane when the package is consumed via a symlink.
+ * - `optimizeDeps.include` pre-bundles qdadm's CJS transitives (currently
+ *   `pluralize`), which cannot be served raw as ESM. The list lives HERE —
+ *   consumers should not have to track qdadm's internal CJS deps (skybot
+ *   feedback on #1389). Both the nested (`@quazardous/qdadm > pluralize`,
+ *   npm installs) and plain (`pluralize`, symlinked installs where the
+ *   nested path can't resolve) forms are declared; the unused one is a
+ *   no-op warning at worst.
+ * - When `node_modules/@quazardous/qdadm` is a symlink (file:/workspace
+ *   link — qdadm's own dev mode against a testbed app), its realpath is
+ *   appended to `server.fs.allow` so qdadm's `?raw` dynamic imports (i18n
+ *   YAML defaults) are servable from outside the consumer's workspace
+ *   root. The workspace root is re-added explicitly because a populated
+ *   `fs.allow` disables Vite's implicit default.
+ *
+ * Returned partial config is deep-merged by Vite (arrays concatenate), so
+ * consumer overrides in their own `defineConfig` still apply.
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { searchForWorkspaceRoot, type Plugin, type UserConfig } from 'vite'
+
+/** qdadm's CJS transitive deps that must be pre-bundled (internal knowledge). */
+const CJS_TRANSITIVES = ['pluralize']
+
+export interface QdadmVitePluginOptions {
+  /**
+   * Extra packages to dedupe on top of the defaults
+   * (vue, vue-router, primevue, pinia).
+   */
+  dedupe?: string[]
+}
+
+export function qdadmVitePlugin(options: QdadmVitePluginOptions = {}): Plugin {
+  return {
+    name: 'qdadm',
+    config: (userConfig: UserConfig = {}) => {
+      const root = path.resolve(userConfig.root ?? process.cwd())
+
+      // Symlinked install (file:/workspace link)? Allow serving from the
+      // link target, which typically lives outside the consumer's root.
+      const fsAllow: string[] = []
+      let symlinked = false
+      try {
+        const pkgDir = path.join(root, 'node_modules', '@quazardous', 'qdadm')
+        const real = fs.realpathSync(pkgDir)
+        if (real !== pkgDir) {
+          symlinked = true
+          fsAllow.push(searchForWorkspaceRoot(root), real)
+        }
+      } catch {
+        // not installed under root node_modules (aliased/hoisted) — nothing to allow
+      }
+
+      return {
+        resolve: {
+          dedupe: ['vue', 'vue-router', 'primevue', 'pinia', ...(options.dedupe ?? [])],
+        },
+        optimizeDeps: {
+          exclude: ['primevue', '@primeuix/themes', '@quazardous/qdadm'],
+          // One form per install mode: the nested path resolves through a
+          // real node_modules chain (npm installs), the plain form through a
+          // symlink realpath — declaring the unused one logs a "Failed to
+          // resolve dependency" warning (skybot testbed, #1389).
+          include: symlinked
+            ? [...CJS_TRANSITIVES]
+            : CJS_TRANSITIVES.map((dep) => `@quazardous/qdadm > ${dep}`),
+        },
+        ...(fsAllow.length > 0 ? { server: { fs: { allow: fsAllow } } } : {}),
+      }
+    },
+  }
+}