@quazardous/qdadm 2.17.4 → 2.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quazardous/qdadm",
-  "version": "2.17.4",
+  "version": "2.19.0",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",
@@ -54,8 +54,8 @@
     "dist/node"
   ],
   "dependencies": {
-    "@quazardous/qdcore": "^1.1.2",
-    "@quazardous/qddebug": "^1.1.0",
+    "@quazardous/qdcore": "^1.2.0",
+    "@quazardous/qddebug": "^1.2.0",
     "@quazardous/quarkernel": "^2.1.0",
     "yaml": "^2.8.4"
   },
@@ -63,6 +63,7 @@
     "pinia": "^2.0.0 || ^3.0.0 || ^4.0.0",
     "primevue": "^4.0.0",
     "sass-embedded": "^1.0.0",
+    "vanilla-jsoneditor": "^3.13.0",
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0",
     "vue": "^3.3.0",
     "vue-router": "^4.0.0 || ^5.0.0"
@@ -78,12 +79,9 @@
       "optional": true
     },
     "sass-embedded": {
-      "optional": "true"
+      "optional": true
     }
   },
-  "optionalDependencies": {
-    "vanilla-jsoneditor": "^0.23.0"
-  },
   "keywords": [
     "vue",
     "vue3",

package/src/components/editors/VanillaJsonEditor.vue

@@ -15,7 +15,17 @@
  */
 
 import { ref, watch, onMounted, onUnmounted, nextTick } from 'vue'
-import { JSONEditor, type Content, type ContentErrors, type OnChangeStatus, type Mode } from 'vanilla-jsoneditor'
+// vanilla-jsoneditor 3.x (#1901): the `new JSONEditor(...)` constructor is
+// deprecated — `JSONEditor` is now the Svelte component itself, and the
+// instance type is exported as `JsonEditor`.
+import {
+  createJSONEditor,
+  type JsonEditor,
+  type Content,
+  type ContentErrors,
+  type OnChangeStatus,
+  type Mode,
+} from 'vanilla-jsoneditor'
 import { buildJsonValidator, type Validator, type JSONSchema, type JsonValidatorOptions } from './jsonValidator'
 
 type JsonValue = Record<string, unknown> | unknown[] | string | null
@@ -74,8 +84,8 @@ const emit = defineEmits<{
   'error': [errors: ContentErrors]
 }>()
 
-const containerRef = ref<HTMLElement | null>(null)
-let editor: JSONEditor | null = null
+const containerRef = ref<HTMLDivElement | null>(null)
+let editor: JsonEditor | null = null
 // Flag to prevent onChange from firing during programmatic updates (instance-specific)
 const updatingFromProp = ref<boolean>(false)
 
@@ -102,7 +112,7 @@ onMounted(() => {
     json: parseValue(props.modelValue)
   }
 
-  editor = new JSONEditor({
+  editor = createJSONEditor({
     target: containerRef.value,
     props: {
       content,

package/src/composables/useLayoutResolver.ts

@@ -34,6 +34,10 @@ import { useRoute } from 'vue-router'
 export const LAYOUT_TYPES = {
   LIST: 'list',
   FORM: 'form',
+  // `show` was emitted by crud({ show }) long before it existed here (#1922).
+  // The resolver returned it, found no component under that key, and fell
+  // back to `base` — gracefully, which is exactly what made it invisible.
+  SHOW: 'show',
   DASHBOARD: 'dashboard',
   BASE: 'base',
 } as const
@@ -46,6 +50,7 @@ export type LayoutType = (typeof LAYOUT_TYPES)[keyof typeof LAYOUT_TYPES]
 export interface LayoutComponentsMap {
   list?: Component | null
   form?: Component | null
+  show?: Component | null
   dashboard?: Component | null
   base?: Component | null
   [key: string]: Component | null | undefined
@@ -63,6 +68,7 @@ interface PageNamePattern {
 const PAGE_NAME_PATTERNS: PageNamePattern[] = [
   { pattern: /List(Page)?$/i, layout: LAYOUT_TYPES.LIST },
   { pattern: /(Edit|Create|Form)(Page)?$/i, layout: LAYOUT_TYPES.FORM },
+  { pattern: /Show(Page)?$/i, layout: LAYOUT_TYPES.SHOW },
   { pattern: /Dashboard(Page)?$/i, layout: LAYOUT_TYPES.DASHBOARD },
 ]
 
@@ -70,6 +76,10 @@ const PAGE_NAME_PATTERNS: PageNamePattern[] = [
 const ROUTE_NAME_PATTERNS: PageNamePattern[] = [
   { pattern: /-list$/i, layout: LAYOUT_TYPES.LIST },
   { pattern: /-(edit|create)$/i, layout: LAYOUT_TYPES.FORM },
+  // Load-bearing, not decoration: an app that declares its detail route by
+  // hand rather than through crud({ show }) has no meta.layout to go on, and
+  // this is the only path that can reach `show` for it (#1922).
+  { pattern: /-show$/i, layout: LAYOUT_TYPES.SHOW },
   { pattern: /-dashboard$/i, layout: LAYOUT_TYPES.DASHBOARD },
   // Common patterns without suffix
   { pattern: /^dashboard$/i, layout: LAYOUT_TYPES.DASHBOARD },

package/src/composables/useListPage.filters.ts

@@ -44,7 +44,6 @@ export interface UseListFiltersDeps {
   /** Thunks — resolved lazily, the targets are declared later in useListPage. */
   loadItems: () => void
   setSearch: (searchCfg: Partial<SearchConfig>) => void
-  invokeFilterAlterHook: () => Promise<void>
 }
 
 export interface UseListFiltersReturn {
@@ -63,6 +62,8 @@ export interface UseListFiltersReturn {
   loadFilterOptions: () => Promise<void>
   updateCacheBasedFilters: () => Promise<void>
   restoreFilters: () => void
+  /** Push filters, search and the page number into the URL (#2113). */
+  writeStateToUrl: () => void
 }
 
 export function useListFilters(deps: UseListFiltersDeps): UseListFiltersReturn {
@@ -83,13 +84,42 @@ export function useListFilters(deps: UseListFiltersDeps): UseListFiltersReturn {
     entityFilters,
     loadItems,
     setSearch,
-    invokeFilterAlterHook,
   } = deps
 
   const filtersMap = ref<Map<string, FilterConfig>>(new Map())
   const filterValues = ref<Record<string, unknown>>(savedFilters || {})
 
+  /** Names the URL sync already owns — a filter cannot have them (#2113). */
+  const RESERVED_QUERY_KEYS = new Set(['page', 'search'])
+  const warnedReserved = new Set<string>()
+
+  /**
+   * A filter named `page` or `search` silently overwrites the query key of
+   * the same name, and is overwritten back on restore. `search` has behaved
+   * this way since the URL sync existed and nobody ever reported it, which
+   * says how quiet the failure is; `page` joins the reserved set now that the
+   * page number lives in the URL too.
+   *
+   * We name what happens INSTEAD of what was asked, rather than dropping the
+   * filter — renaming someone's filter behind their back would be a worse
+   * surprise than the collision (ADR 0011).
+   */
+  function warnIfReservedName(name: string): void {
+    if (!RESERVED_QUERY_KEYS.has(name)) return
+    if (!syncUrlParams) return
+    if (warnedReserved.has(name)) return
+    warnedReserved.add(name)
+    console.warn(
+      `[qdadm] Filter "${name}" on "${entityName}" collides with the URL ` +
+        `parameter of the same name. With syncUrlParams on, the list's own ` +
+        `${name === 'page' ? 'page number' : 'search query'} wins and this ` +
+        `filter will not survive a reload. Rename the filter, or set ` +
+        `syncUrlParams: false on this list.`
+    )
+  }
+
   function addFilter(name: string, filterConfig: Omit<FilterConfig, 'name'>): void {
+    warnIfReservedName(name)
     filtersMap.value.set(name, {
       name,
       type: 'select',
@@ -115,6 +145,46 @@ export function useListFilters(deps: UseListFiltersDeps): UseListFiltersReturn {
     onFiltersChanged()
   }
 
+  /**
+   * Push the list's own state into the URL (#2113).
+   *
+   * Filters, search AND the page number, each written only when it differs
+   * from the default and removed otherwise, so a pristine list leaves a clean
+   * URL. `router.replace` rather than `push`: paging is not a history step of
+   * its own, but the URL must carry the page at the moment the user leaves
+   * for a detail view, so that coming back restores it.
+   */
+  function writeStateToUrl(): void {
+    if (!syncUrlParams) return
+
+    const query = { ...route.query } as Record<string, string>
+
+    for (const [name, value] of Object.entries(filterValues.value)) {
+      if (value !== null && value !== undefined && value !== '') {
+        query[name] = String(value)
+      } else {
+        delete query[name]
+      }
+    }
+
+    if (searchQuery.value) {
+      query.search = searchQuery.value
+    } else {
+      delete query.search
+    }
+
+    // Page 1 is the default and stays implicit. Reserved keys are written
+    // last so the list's own state wins a collision — the warning in
+    // addFilter() names that consequence at declaration time.
+    if (page.value > 1) {
+      query.page = String(page.value)
+    } else {
+      delete query.page
+    }
+
+    router.replace({ query })
+  }
+
   function onFiltersChanged(): void {
     page.value = 1
     loadItems()
@@ -136,22 +206,7 @@ export function useListFilters(deps: UseListFiltersDeps): UseListFiltersReturn {
       }
       setSessionFilters(filterSessionKey, toPersist)
     }
-    if (syncUrlParams) {
-      const query = { ...route.query } as Record<string, string>
-      for (const [name, value] of Object.entries(filterValues.value)) {
-        if (value !== null && value !== undefined && value !== '') {
-          query[name] = String(value)
-        } else {
-          delete query[name]
-        }
-      }
-      if (searchQuery.value) {
-        query.search = searchQuery.value
-      } else {
-        delete query.search
-      }
-      router.replace({ query })
-    }
+    writeStateToUrl()
   }
 
   function clearFilters(): void {
@@ -164,15 +219,16 @@ export function useListFilters(deps: UseListFiltersDeps): UseListFiltersReturn {
     if (persistFilters) {
       clearSessionFilters(filterSessionKey)
     }
+    page.value = 1
     if (syncUrlParams) {
       const query = { ...route.query } as Record<string, string>
       for (const key of filtersMap.value.keys()) {
         delete query[key]
       }
       delete query.search
+      delete query.page
       router.replace({ query })
     }
-    page.value = 1
     loadItems()
   }
 
@@ -221,12 +277,49 @@ export function useListFilters(deps: UseListFiltersDeps): UseListFiltersReturn {
     }
   }
 
+  /**
+   * Fetch the remote options that populate filter dropdowns (#1934 lot 1).
+   *
+   * The loop used to be sequential: three filters with remote options cost
+   * three round trips in a queue, and the rows waited behind the sum. They
+   * are independent, so they now go together and cost the slowest.
+   *
+   * Deduplicated by `optionsEntity` on purpose. Sequential execution had one
+   * accidental virtue — two filters on the same entity meant one fetch and
+   * one cache hit — and firing them in parallel would turn that into two
+   * concurrent fetches. Trading latency for duplicate requests is not a win,
+   * so filters sharing an entity are still chained behind one another while
+   * different entities run side by side.
+   *
+   * This no longer invokes `filter:alter`: that hook establishes what the
+   * query will ask for, so it belongs with the other query-settling work in
+   * `onMounted`, not behind the network (#1934 lot 2).
+   */
   async function loadFilterOptions(): Promise<void> {
-    // Process filters configured directly via addFilter() (smart filter modes)
-    for (const [filterName, filterDef] of filtersMap.value) {
-      if (filterDef.options && filterDef.options.length > 1) continue
-      if (filterDef.optionsFromCache) continue
+    const pending = Array.from(filtersMap.value).filter(([, filterDef]) => {
+      if (filterDef.options && filterDef.options.length > 1) return false
+      if (filterDef.optionsFromCache) return false
+      return true
+    })
+
+    // One chain per source entity; everything else is a chain of its own.
+    const chains = new Map<string, Promise<void>>()
 
+    await Promise.all(
+      pending.map(([filterName, filterDef]) => {
+        const key = filterDef.optionsEntity ? `entity:${filterDef.optionsEntity}` : `own:${filterName}`
+        const previous = chains.get(key) ?? Promise.resolve()
+        const next = previous.then(() => loadOneFilterOptions(filterName, filterDef))
+        chains.set(key, next)
+        return next
+      })
+    )
+
+    // Trigger Vue reactivity
+    filtersMap.value = new Map(filtersMap.value)
+  }
+
+  async function loadOneFilterOptions(filterName: string, filterDef: FilterConfig): Promise<void> {
       try {
         let rawOptions: Array<{ label: string; value: unknown }> | null = null
 
@@ -299,13 +392,6 @@ export function useListFilters(deps: UseListFiltersDeps): UseListFiltersReturn {
       } catch (error) {
         console.warn(`[qdadm] Failed to load options for filter "${filterName}":`, error)
       }
-    }
-
-    // Invoke filter:alter hooks after all options are loaded
-    await invokeFilterAlterHook()
-
-    // Trigger Vue reactivity
-    filtersMap.value = new Map(filtersMap.value)
   }
 
   async function updateCacheBasedFilters(): Promise<void> {
@@ -399,6 +485,13 @@ export function useListFilters(deps: UseListFiltersDeps): UseListFiltersReturn {
     if (route.query.search) {
       searchQuery.value = route.query.search as string
     }
+    // The page must be restored HERE, before the first loadItems(): restoring
+    // it later would mean a first request for page 1 and a second for the
+    // real one (#2113).
+    const restoredPage = Number(route.query.page)
+    if (Number.isInteger(restoredPage) && restoredPage > 0) {
+      page.value = restoredPage
+    }
   }
 
   return {
@@ -417,5 +510,6 @@ export function useListFilters(deps: UseListFiltersDeps): UseListFiltersReturn {
     loadFilterOptions,
     updateCacheBasedFilters,
     restoreFilters,
+    writeStateToUrl,
   }
 }

package/src/composables/useListPage.ts

@@ -28,7 +28,7 @@ import {
   provide,
   type Ref,
 } from 'vue'
-import { useRouter, useRoute } from 'vue-router'
+import { useRouter, useRoute, type RouteLocationRaw } from 'vue-router'
 import { useConfirm } from 'primevue/useconfirm'
 import { useHooks } from './useHooks.js'
 import { useEntityItemPage, type ParentConfig, type UseEntityItemPageReturn } from './useEntityItemPage.js'
@@ -586,8 +586,8 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
   const cards = computed(() => Array.from(cardsMap.value.values()))
 
   // ============ FILTERS (#1195 — extracted subsystem) ============
-  // invokeFilterAlterHook is a thunk: alterHooks is declared after the
-  // actions section (it needs the action registry) and only runs post-setup.
+  // loadItems and setSearch are passed as thunks: both are declared further
+  // down and only ever run post-setup.
   const listFilters = useListFilters({
     entityName,
     manager,
@@ -605,7 +605,6 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
     entityFilters,
     loadItems: () => loadItems(),
     setSearch: (searchCfg) => setSearch(searchCfg),
-    invokeFilterAlterHook: () => alterHooks.invokeFilterAlterHook(),
   })
   const {
     filtersMap,
@@ -623,6 +622,7 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
     loadFilterOptions,
     updateCacheBasedFilters,
     restoreFilters,
+    writeStateToUrl,
   } = listFilters
 
   // ============ ACTIONS ============
@@ -799,6 +799,10 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
     page.value = event.page + 1
     pageSize.value = event.rows
     persistPageSize(event.rows)
+    // The page joins the URL (#2113) — it was the only piece of list state
+    // that survived nothing, so leaving a list for a detail view and coming
+    // back dropped the user on page 1.
+    writeStateToUrl()
     loadItems()
   }
 
@@ -851,21 +855,55 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
     return { name: `${routePrefix}-create` }
   }
 
+  /** Route names already reported as missing — one warning each. */
+  const warnedMissingRoutes = new Set<string>()
+
+  /**
+   * Navigate by route name, and say something when that name does not exist
+   * (#1923 lot 2).
+   *
+   * The failure this catches is quiet by nature: the route prefix is derived
+   * from the entity name, so a mismatch between the side that NAMES routes
+   * and the side that LOOKS THEM UP produces a push to a name nobody
+   * registered. Nothing happens, and nothing says why — the divergence that
+   * caused #1923 behaved exactly like this, invisible until someone clicked.
+   *
+   * We warn at the moment of use rather than auditing the prefix upfront: an
+   * entity that only ever appears as a child of another has no routes under
+   * its own prefix and is perfectly healthy, so an upfront check would cry
+   * wolf. A warning nobody trusts is worse than none (ADR 0011).
+   */
+  function pushNamedRoute(name: string, params?: Record<string, unknown>): void {
+    if (!router.hasRoute(name)) {
+      if (!warnedMissingRoutes.has(name)) {
+        warnedMissingRoutes.add(name)
+        console.warn(
+          `[qdadm] No route named "${name}" — this navigation does nothing. ` +
+            `The list for "${entity}" derives it from the route prefix ` +
+            `"${routePrefix}". Either that page is not declared, or the ` +
+            `prefix disagrees with the one its routes were registered under ` +
+            `(pass routePrefix on the entity, or on useListPage, to pin it).`
+        )
+      }
+      return
+    }
+    router.push({ name, ...(params ? { params } : {}) } as RouteLocationRaw)
+  }
+
   function goToCreate(): void {
-    router.push(findCreateRoute() as { name: string })
+    const target = findCreateRoute() as { name: string; params?: Record<string, unknown> }
+    pushNamedRoute(target.name, target.params)
   }
 
   function goToEdit(item: unknown): void {
-    router.push({
-      name: `${routePrefix}-edit`,
-      params: { [manager.idField]: (item as Record<string, unknown>)[resolvedDataKey] as string },
+    pushNamedRoute(`${routePrefix}-edit`, {
+      [manager.idField]: (item as Record<string, unknown>)[resolvedDataKey] as string,
     })
   }
 
   function goToShow(item: unknown): void {
-    router.push({
-      name: `${routePrefix}-show`,
-      params: { [manager.idField]: (item as Record<string, unknown>)[resolvedDataKey] as string },
+    pushNamedRoute(`${routePrefix}-show`, {
+      [manager.idField]: (item as Record<string, unknown>)[resolvedDataKey] as string,
     })
   }
 
@@ -1018,7 +1056,7 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
     headerActionsMap,
     actionRegistry,
   })
-  const { invokeListAlterHook } = alterHooks
+  const { invokeListAlterHook, invokeFilterAlterHook } = alterHooks
 
   // ============ LIFECYCLE ============
   initFromRegistry()
@@ -1030,18 +1068,35 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
   onMounted(async () => {
     window.addEventListener('resize', handleResize)
 
+    // Two kinds of work, and they used to be interleaved (#1934).
+    //
+    // SETTLING THE QUERY comes first, and only this blocks the rows.
+    // `restoreFilters()` reads the filters, the search and the page out of
+    // the URL; the alter hooks may add filters and their default values, and
+    // may replace a filter's `toQuery`/`local_filter` — all of which
+    // `loadItems()` reads. Skipping ahead of them sends the wrong request,
+    // and nothing retries it.
+    //
+    // FETCHING comes second. Filter options populate dropdowns and have no
+    // bearing on what the rows request, so the rows no longer wait behind
+    // them: a page whose filters pull options from related entities used to
+    // show nothing until every one of those round trips had returned.
     restoreFilters()
 
-    if (!filterOptionsLoaded) {
-      filterOptionsLoaded = true
-      await loadFilterOptions()
-    }
-
+    await invokeFilterAlterHook()
     await invokeListAlterHook()
 
     if (loadOnMount && manager) {
       loadItems()
     }
+
+    if (!filterOptionsLoaded) {
+      filterOptionsLoaded = true
+      // Deliberately not awaited: the dropdowns fill in when they fill in.
+      void loadFilterOptions().catch((error) => {
+        console.warn('[qdadm] Failed to load filter options:', error)
+      })
+    }
   })
 
   onUnmounted(() => {

package/src/entity/storage/ApiStorage.ts

@@ -36,6 +36,13 @@ export interface ApiStorageOptions<T extends EntityRecord = EntityRecord> {
   getClient?: (() => HttpClient) | null
   responseItemsKey?: string
   responseTotalKey?: string
+  /**
+   * Response HEADER carrying the total, for APIs that report it there rather
+   * than in the body (`X-Total-Count` is the json-server convention). Read
+   * before `responseTotalKey`. The header must be CORS-exposed to be
+   * readable from a browser.
+   */
+  responseTotalHeader?: string | null
   paramMapping?: Record<string, string>
   normalize?: ((data: T, context?: RoutingContext | null) => T) | null
   denormalize?: ((data: Partial<T>) => Partial<T>) | null
@@ -60,6 +67,7 @@ export class ApiStorage<T extends EntityRecord = EntityRecord> extends IStorage<
   readonly endpoint: string
   readonly responseItemsKey: string
   readonly responseTotalKey: string
+  readonly responseTotalHeader: string | null
   readonly paramMapping: Record<string, string>
 
   protected _client: HttpClient | null
@@ -75,6 +83,7 @@ export class ApiStorage<T extends EntityRecord = EntityRecord> extends IStorage<
       getClient = null,
       responseItemsKey = 'items',
       responseTotalKey = 'total',
+      responseTotalHeader = null,
       paramMapping = {},
       normalize = null,
       denormalize = null,
@@ -85,13 +94,16 @@ export class ApiStorage<T extends EntityRecord = EntityRecord> extends IStorage<
     this._getClient = getClient
     this.responseItemsKey = responseItemsKey
     this.responseTotalKey = responseTotalKey
+    this.responseTotalHeader = responseTotalHeader
     this.paramMapping = paramMapping
     this._normalize = normalize
     this._denormalize = denormalize
   }
 
   /**
-   * Apply parameter mapping to transform filter names
+   * Rename outgoing query parameters to the backend's vocabulary.
+   *
+   * Applies to filters AND to the pagination/sort keys (#2113) — see `list()`.
    */
   protected _applyParamMapping(params: Record<string, unknown>): Record<string, unknown> {
     if (!this.paramMapping || Object.keys(this.paramMapping).length === 0) {
@@ -141,10 +153,19 @@ export class ApiStorage<T extends EntityRecord = EntityRecord> extends IStorage<
   async list(params: ListParams = {}, context: RoutingContext | null = null): Promise<ListResult<T>> {
     const { page = 1, page_size = 20, sort_by, sort_order, filters = {} } = params
 
-    const mappedFilters = this._applyParamMapping(filters)
+    // `paramMapping` covers the WHOLE outgoing query, pagination included
+    // (#2113). It used to be applied to the filters only, so `status` could
+    // be renamed to `state` but `page_size` could not be renamed to `limit` —
+    // and an API speaking any other pagination dialect had to subclass the
+    // storage for that alone. The names qdadm uses internally are its own
+    // business; what goes on the wire is the backend's.
+    //
+    // Filters keep their precedence over the pagination keys, exactly as
+    // before: a filter named `page` still wins, for better or worse.
+    const outgoing = { page, page_size, sort_by, sort_order, ...filters }
 
     const response = await this.client.get<Record<string, unknown>>(this.endpoint, {
-      params: { page, page_size, sort_by, sort_order, ...mappedFilters },
+      params: this._applyParamMapping(outgoing),
     })
 
     const data = response.data
@@ -154,12 +175,39 @@ export class ApiStorage<T extends EntityRecord = EntityRecord> extends IStorage<
     return {
       items,
       total:
-        (data[this.responseTotalKey] as number) ||
-        (data.total as number) ||
-        (Array.isArray(data) ? data.length : 0),
+        this._totalFromHeader(response) ??
+        ((data[this.responseTotalKey] as number) ||
+          (data.total as number) ||
+          (Array.isArray(data) ? data.length : 0)),
     }
   }
 
+  /**
+   * Total announced in a response header, when `responseTotalHeader` says so.
+   *
+   * Returns null — not 0 — when there is nothing to read, so the body-based
+   * fallbacks still get their turn. A 0 from the server is a real answer and
+   * is preserved.
+   */
+  protected _totalFromHeader(response: unknown): number | null {
+    if (!this.responseTotalHeader) return null
+
+    const headers = (response as { headers?: unknown })?.headers as
+      | { get?: (name: string) => unknown }
+      | Record<string, unknown>
+      | undefined
+    if (!headers) return null
+
+    const raw =
+      typeof (headers as { get?: unknown }).get === 'function'
+        ? (headers as { get: (name: string) => unknown }).get(this.responseTotalHeader)
+        : (headers as Record<string, unknown>)[this.responseTotalHeader.toLowerCase()]
+
+    if (raw === null || raw === undefined || raw === '') return null
+    const total = Number(raw)
+    return Number.isFinite(total) ? total : null
+  }
+
   async get(id: string | number, context: RoutingContext | null = null): Promise<T> {
     const response = await this.client.get<T>(`${this.endpoint}/${id}`)
     return this._normalizeData(response.data, context) as T

package/src/gen/createManagers.ts

@@ -196,7 +196,7 @@ function findSchemaForEntity(
  * const users = await usersManager.list()
  * ```
  */
-export function createManagers(config: CreateManagersConfig): Map<string, EntityManager> {
+export function createGeneratedManagers(config: CreateManagersConfig): Map<string, EntityManager> {
   // Validate config structure early
   validateConfig(config)
 
@@ -243,3 +243,17 @@ export function createManagers(config: CreateManagersConfig): Map<string, Entity
 
   return managers
 }
+
+/**
+ * @deprecated Renamed to `createGeneratedManagers` (#1902).
+ *
+ * The root exports a DIFFERENT `createManagers` — `entity/factory.ts`, which
+ * takes `(config, context)` and returns a `Record`, where this one takes a
+ * single generated config and returns a `Map`. Same name, two public entry
+ * points, different signatures and different return types, with nothing to
+ * warn whoever picked the wrong import: the mistake surfaces at the first
+ * `.get()`.
+ *
+ * This alias keeps existing imports working. Use `createGeneratedManagers`.
+ */
+export const createManagers = createGeneratedManagers

package/src/gen/index.ts

@@ -51,7 +51,13 @@ export { OpenAPIConnector, type OpenAPIConnectorOptions, type OperationFilter }
 export { type StorageProfileFactory, type StorageProfileOptions } from './StorageProfileFactory'
 
 // T00317: createManagers - Runtime factory for EntityManager creation
-export { createManagers, type CreateManagersConfig, type EntityConfig } from './createManagers'
+export {
+  createGeneratedManagers,
+  /** @deprecated Renamed to `createGeneratedManagers` (#1902) — it collided with the root's own `createManagers`. */
+  createManagers,
+  type CreateManagersConfig,
+  type EntityConfig,
+} from './createManagers'
 
 // T00318: Decorators - Per-entity field customization layer
 export { applyDecorators, type FieldDecorator, type EntityDecorator } from './decorators'

package/src/kernel/Kernel.registries.ts

@@ -52,9 +52,14 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
    * Create hook registry for Drupal-inspired extensibility
    */
   proto._createHookRegistry = function (this: Self): void {
+    // Idempotent, and built in the constructor (#1906 lot B1): replacing it in
+    // createApp() would orphan every hook registered before then — silently,
+    // which is the failure this lot exists to remove.
+    if (this.hookRegistry) return
+
     const debug = this.options.debug ?? false
     this.hookRegistry = createHookRegistry({
-      kernel: this.signals!.getKernel(),
+      kernel: this.signals.getKernel(),
       debug,
     })
   }
@@ -94,6 +99,9 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
    * Create PermissionRegistry early so modules can register permissions
    */
   proto._createPermissionRegistry = function (this: Self): void {
+    // Idempotent, built in the constructor (#1906 lot B1) — see _createHookRegistry.
+    if (this.permissionRegistry) return
+
     this.permissionRegistry = new PermissionRegistry()
     this._registerCorePermissions()
   }
@@ -102,12 +110,12 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
    * Register core system permissions provided by the framework
    */
   proto._registerCorePermissions = function (this: Self): void {
-    this.permissionRegistry!.register('auth', {
+    this.permissionRegistry.register('auth', {
       impersonate: 'Impersonate other users',
       manage: 'Manage authentication settings',
     })
 
-    this.permissionRegistry!.register('admin', {
+    this.permissionRegistry.register('admin', {
       access: 'Access admin panel',
       config: 'Edit system configuration',
     })
@@ -119,12 +127,10 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
   proto._setupSecurity = function (this: Self): void {
     const { security, entityAuthAdapter } = this.options
 
-    if (!this.permissionRegistry) {
-      this.permissionRegistry = new PermissionRegistry()
-    }
-
     if (!security) return
 
+    this._validateSecurityConfig(security as unknown as Record<string, unknown>)
+
     // 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) {
@@ -173,6 +179,9 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
    * Create zone registry for extensible UI composition
    */
   proto._createZoneRegistry = function (this: Self): void {
+    // Idempotent, built in the constructor (#1906 lot B1) — see _createHookRegistry.
+    if (this.zoneRegistry) return
+
     const debug = this.options.debug ?? false
     this.zoneRegistry = createZoneRegistry({ debug })
   }
@@ -199,9 +208,15 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
    * Create deferred registry for async service loading
    */
   proto._createDeferredRegistry = function (this: Self): void {
+    // Idempotent, built in the constructor (#1906 lot B1) — see _createHookRegistry.
+    if (this.deferred) return
+
     const debug = this.options.debug ?? false
+    // `this.signals` is never null now, so the defensive `?.` this line used
+    // to carry is gone. Less guarding, not more: that is the point of closing
+    // the window rather than warning about it.
     this.deferred = createDeferredRegistry({
-      kernel: this.signals?.getKernel() || null,
+      kernel: this.signals.getKernel(),
       debug,
     })
   }
@@ -225,49 +240,93 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
    * Create SSEBridge for Server-Sent Events to SignalBus integration
    */
   /**
-   * Warn about unrecognised `sse` keys (#1898 lot A).
+   * The known key a typo most likely meant, or undefined.
    *
-   * A consumer configured `sse.getToken` against a version that predated it.
-   * It was not rejected — it was ignored, and the bridge fell back to the
-   * session's DURABLE token, which then travelled in the query string of every
-   * `/events` request and into logs that outlive the session by months. No
-   * error, no warning, and a stream that worked perfectly.
-   *
-   * The warning therefore names what happens INSTEAD, not merely that the key
-   * was ignored: "ignored" reads as "no effect", not as "falls back to a more
-   * sensitive secret". That reading is what made the failure invisible.
+   * Case differences and prefixes were all the original matcher caught
+   * (#1898), which misses the commonest typo of all: one missing or
+   * transposed letter. `securty` suggested nothing, so the reader got
+   * "IGNORED" with no hint and no consequence — the two things that make the
+   * warning worth printing. An edit distance of one covers an omission, an
+   * insertion, a substitution or a transposition; two is allowed only for
+   * longer keys, where it stays specific enough not to guess wildly.
    */
-  proto._validateSseConfig = function (this: Self, sse: SSEConfig): void {
-    const known = new Set([
-      'url',
-      'reconnectDelay',
-      'signalPrefix',
-      'autoConnect',
-      'withCredentials',
-      'tokenParam',
-      'events',
-      'entities',
-      'getToken',
-      'connectOnSignal',
-      'disconnectOnSignal',
-    ])
-
-    const unknown = Object.keys(sse).filter((key) => !known.has(key))
-    if (!unknown.length) return
+  function nearestKnownKey(key: string, known: Set<string>): string | undefined {
+    const exact = [...known].find(
+      (k) => k.toLowerCase() === key.toLowerCase() || k.startsWith(key) || key.startsWith(k)
+    )
+    if (exact) return exact
+
+    const budget = key.length >= 8 ? 2 : 1
+    let best: string | undefined
+    let bestDistance = budget + 1
+    for (const candidate of known) {
+      const distance = editDistance(key.toLowerCase(), candidate.toLowerCase(), bestDistance)
+      if (distance < bestDistance) {
+        bestDistance = distance
+        best = candidate
+      }
+    }
+    return bestDistance <= budget ? best : undefined
+  }
 
-    // What the app loses by having the key ignored, wherever we can say it.
-    const consequences: Record<string, string> = {
-      getToken:
-        'the session auth token will be sent in the stream URL instead — ' +
-        'and query strings reach access logs',
-      entities: 'no entity cache will be invalidated from the stream',
-      tokenParam: 'the token will be sent under the default name "token"',
+  /** Damerau-Levenshtein, abandoned as soon as it exceeds `cap`. */
+  function editDistance(a: string, b: string, cap: number): number {
+    if (Math.abs(a.length - b.length) > cap) return cap + 1
+
+    let previous: number[] = Array.from({ length: b.length + 1 }, (_, i) => i)
+    let beforePrevious: number[] = []
+
+    for (let i = 1; i <= a.length; i++) {
+      const current: number[] = [i]
+      let rowBest = i
+      for (let j = 1; j <= b.length; j++) {
+        const cost = a[i - 1] === b[j - 1] ? 0 : 1
+        let value = Math.min(
+          (current[j - 1] as number) + 1,
+          (previous[j] as number) + 1,
+          (previous[j - 1] as number) + cost
+        )
+        // Transposition: `raods` for `roads`.
+        if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+          value = Math.min(value, (beforePrevious[j - 2] as number) + 1)
+        }
+        current[j] = value
+        rowBest = Math.min(rowBest, value)
+      }
+      if (rowBest > cap) return cap + 1
+      beforePrevious = previous
+      previous = current
     }
+    return previous[b.length] as number
+  }
+
+  /**
+   * Warn about keys a config object does not recognise (#1906 lot B2).
+   *
+   * Extracted from the `sse` validator of #1898, which was the only one of its
+   * kind: every other qdadm config accepted anything in silence. The shape of
+   * the message is the lesson from that incident and is kept intact — it names
+   * what happens INSTEAD of what was asked, because "ignored" reads as "no
+   * effect" rather than "falls back to something else", and that reading is
+   * what cost a durable auth token in access logs.
+   *
+   * Only for CLOSED shapes. A config that deliberately forwards unknown keys
+   * elsewhere — `debugBar`, whose extra options reach the DebugModule — must
+   * not be passed through here: a warning that cries wolf is worse than none
+   * (ADR 0011).
+   */
+  proto._warnUnknownKeys = function (
+    this: Self,
+    scope: string,
+    config: Record<string, unknown>,
+    known: Set<string>,
+    consequences: Record<string, string> = {}
+  ): void {
+    const unknown = Object.keys(config).filter((key) => !known.has(key))
+    if (!unknown.length) return
 
     for (const key of unknown) {
-      const near = [...known].find(
-        (k) => k.toLowerCase() === key.toLowerCase() || k.startsWith(key) || key.startsWith(k)
-      )
+      const near = nearestKnownKey(key, known)
       // Look the consequence up under the NEAREST KNOWN key: a typo like
       // `getTokens` means `getToken` is absent, and it is that absence whose
       // effect the reader needs to hear.
@@ -275,13 +334,110 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
       const because = consequence ? ` — ${consequence}` : ''
       const suggestion = near ? ` Did you mean "${near}"?` : ''
       console.warn(
-        `[Kernel] sse.${key} is not a recognised option and is IGNORED${because}.` +
+        `[Kernel] ${scope}${key} is not a recognised option and is IGNORED${because}.` +
           `${suggestion} This usually means the installed qdadm predates the option ` +
           `— check the version before assuming the key has no effect.`
       )
     }
   }
 
+  /**
+   * Every option `KernelOptions` accepts (#1906 lot B2).
+   *
+   * A misspelled TOP-LEVEL key is the worst silence of the family: it does not
+   * degrade a feature, it removes a whole section of configuration. `securty:`
+   * means no security config at all, and nothing says so. TypeScript catches
+   * it; the many consumers whose module files are plain JavaScript get
+   * nothing.
+   *
+   * Kept in sync with the interface by a test that reads `Kernel.types.ts` and
+   * compares — a hand-maintained list that drifts would start crying wolf,
+   * which is the failure mode this whole ticket exists to avoid.
+   */
+  const KNOWN_KERNEL_OPTIONS = new Set([
+    'apiClient', 'app', 'authAdapter', 'authTypes', 'basePath', 'coreRoutes',
+    'debug', 'debugBar', 'defaultEntityCacheTtlMs', 'entityAuthAdapter',
+    'eventRouter', 'existingApp', 'existingRouter', 'existingSignals',
+    'features', 'hashMode', 'homeRoute', 'i18n', 'layouts', 'managerRegistry',
+    'managerResolver', 'managers', 'moduleDefs', 'modules', 'modulesOptions',
+    'notifications', 'onAuthExpired', 'pages', 'parentParamMode', 'primevue',
+    'root', 'routeParamResolver', 'routePrefix', 'sectionOrder', 'security',
+    'sse', 'storageResolver', 'toast', 'warmup',
+  ])
+
+  proto._validateKernelOptions = function (this: Self): void {
+    this._warnUnknownKeys('', this.options as Record<string, unknown>, KNOWN_KERNEL_OPTIONS, {
+      security: 'no role hierarchy or permissions will be applied — every check falls back to the default',
+      sse: 'no server-sent events will be connected',
+      debugBar: 'no debug bar will be mounted',
+      layouts: 'pages will fall back to the base layout',
+      i18n: 'translations will not be configured',
+      authAdapter: 'the app will run unauthenticated',
+    })
+  }
+
+  /**
+   * Warn about unrecognised `security` keys (#1906 lot B2).
+   *
+   * Chosen first, and by damage: a misspelled key here means a role hierarchy
+   * or a permission map is simply absent, and every check then falls through
+   * to whatever the default is. Nothing fails, nothing warns, and the app is
+   * open where its author believed it closed.
+   */
+  proto._validateSecurityConfig = function (this: Self, security: Record<string, unknown>): void {
+    this._warnUnknownKeys(
+      'security.',
+      security,
+      new Set(['role_hierarchy', 'role_permissions', 'role_labels', 'entity_permissions', 'rolesProvider']),
+      {
+        role_hierarchy: 'roles will not inherit from one another',
+        role_permissions: 'no role will carry any permission',
+        entity_permissions: 'per-entity permissions will not be generated',
+        rolesProvider: "the current user's roles will not be resolved",
+      }
+    )
+  }
+
+  /**
+   * Warn about unrecognised `sse` keys (#1898 lot A).
+   *
+   * A consumer configured `sse.getToken` against a version that predated it.
+   * It was not rejected — it was ignored, and the bridge fell back to the
+   * session's DURABLE token, which then travelled in the query string of every
+   * `/events` request and into logs that outlive the session by months. No
+   * error, no warning, and a stream that worked perfectly.
+   *
+   * The warning therefore names what happens INSTEAD, not merely that the key
+   * was ignored: "ignored" reads as "no effect", not as "falls back to a more
+   * sensitive secret". That reading is what made the failure invisible.
+   */
+  proto._validateSseConfig = function (this: Self, sse: SSEConfig): void {
+    this._warnUnknownKeys(
+      'sse.',
+      sse as unknown as Record<string, unknown>,
+      new Set([
+        'url',
+        'reconnectDelay',
+        'signalPrefix',
+        'autoConnect',
+        'withCredentials',
+        'tokenParam',
+        'events',
+        'entities',
+        'getToken',
+        'connectOnSignal',
+        'disconnectOnSignal',
+      ]),
+      {
+        getToken:
+          'the session auth token will be sent in the stream URL instead — ' +
+          'and query strings reach access logs',
+        entities: 'no entity cache will be invalidated from the stream',
+        tokenParam: 'the token will be sent under the default name "token"',
+      }
+    )
+  }
+
   proto._createSSEBridge = function (this: Self): void {
     const { sse, authAdapter } = this.options
     if (!sse?.url) return

package/src/kernel/Kernel.ts

@@ -76,6 +76,7 @@ import { applyRoutingMethods } from './Kernel.routing'
 import { applyModuleMethods } from './Kernel.modules'
 import { applyRegistryMethods } from './Kernel.registries'
 import { setQdadmDebugBar, applyVueMethods } from './Kernel.vue'
+import { isDebugBarKilled } from './debugBarKillSwitch'
 import { applyApiMethods } from './Kernel.api'
 import { applyI18nMethods } from './Kernel.i18n'
 import type { I18n } from '../i18n/I18n'
@@ -93,18 +94,18 @@ export class Kernel {
    * window existed for no reason. Removing it beats warning about it
    * (ADR 0011).
    */
-  signals: SignalBus | null = null
+  signals!: SignalBus
   orchestrator: Orchestrator | null = null
-  zoneRegistry: ZoneRegistry | null = null
-  hookRegistry: HookRegistry | null = null
-  deferred: DeferredRegistry | null = null
+  zoneRegistry!: ZoneRegistry
+  hookRegistry!: HookRegistry
+  deferred!: DeferredRegistry
   eventRouter: EventRouter | null = null
   sseBridge: SSEBridge | null = null
   /** Routes external entity changes to cache invalidation (#1888). */
   liveEntityRouter: LiveEntityRouter | null = null
   layoutComponents: InternalLayoutComponents | null = null
   securityChecker: SecurityChecker | null = null
-  permissionRegistry: PermissionRegistry | null = null
+  permissionRegistry!: PermissionRegistry
   moduleLoader: ModuleLoader | null = null
   activeStack: ActiveStack | null = null
   stackHydrator: StackHydrator | null = null
@@ -157,7 +158,10 @@ export class Kernel {
       // the key inert — including to keep the bar ON, "since it changes
       // nothing" — will now see it disappear. Both readings were possible
       // precisely because the flag did nothing.
-      const debugBarEnabled = debugModuleOptions.enabled !== false
+      // The emergency switch wins over everything (#1900 lot C.3): a bar that
+      // is taking the app down has to be stoppable without a redeploy, so
+      // `?qddebug=off` overrides even an explicit `enabled: true`.
+      const debugBarEnabled = debugModuleOptions.enabled !== false && !isDebugBarKilled()
 
       // Store component for root wrapper
       setQdadmDebugBar(debugBarEnabled ? options.debugBar.component || null : null)
@@ -177,11 +181,28 @@ export class Kernel {
 
     this.options = options
 
-    // The bus exists from here on (#1905 lot B). It has no dependencies, and
-    // the natural place to wire it is right after `new Kernel()` — so it must
-    // be usable there. _createSignalBus() is idempotent, so the later call in
-    // createApp() keeps this instance rather than orphaning its listeners.
+    // Everything that CAN exist from here on, does (#1905 lot B, #1906 lot B1).
+    //
+    // These five have no dependency beyond `options` and each other, and the
+    // natural place to wire a kernel is right after `new Kernel()` — so they
+    // have to be usable there. Someone reached for `kernel.signals` before
+    // createApp(), got `null`, and `null?.emit?.()` swallowed it without a
+    // word; there were seventeen properties shaped like that, and these are
+    // the ones that need not have been.
+    //
+    // Every creator is idempotent, so the later calls in createApp() keep
+    // these instances rather than orphaning whatever was registered on them
+    // in between — which would be the same silent failure wearing a new hat.
+    // Before anything reads them (#1906 lot B2): a misspelled top-level key
+    // removes a whole section of configuration, and TypeScript only catches
+    // it for consumers whose module files are TypeScript.
+    this._validateKernelOptions()
+
     this._createSignalBus()
+    this._createHookRegistry()
+    this._createZoneRegistry()
+    this._createDeferredRegistry()
+    this._createPermissionRegistry()
   }
 
   /**
@@ -475,6 +496,14 @@ export interface Kernel {
   _createDeferredRegistry(): void
   _createEventRouter(): void
   _validateSseConfig(sse: SSEConfigType): void
+  _validateSecurityConfig(security: Record<string, unknown>): void
+  _validateKernelOptions(): void
+  _warnUnknownKeys(
+    scope: string,
+    config: Record<string, unknown>,
+    known: Set<string>,
+    consequences?: Record<string, string>
+  ): void
   _createSSEBridge(): void
 
   // Vue (Kernel.vue.ts)

package/src/kernel/Kernel.types.ts

@@ -70,10 +70,12 @@ export interface Pages {
 export interface LayoutComponents {
   list?: Component | null
   form?: Component | null
+  show?: Component | null
   dashboard?: Component | null
   base?: Component | null
   ListLayout?: Component
   FormLayout?: Component
+  ShowLayout?: Component
   DashboardLayout?: Component
   BaseLayout?: Component
 }
@@ -293,6 +295,7 @@ export interface KernelOptions {
 export interface InternalLayoutComponents {
   list: Component | null
   form: Component | null
+  show: Component | null
   dashboard: Component | null
   base: Component | null
 }

package/src/kernel/Kernel.vue.ts

@@ -3,6 +3,7 @@ import {
   h,
   defineComponent,
   ref,
+  onErrorCaptured,
   type App,
   type Component,
   type Ref,
@@ -58,6 +59,51 @@ export function setQdadmDebugBar(component: Component | null): void {
 /**
  * Patch Kernel prototype with Vue app creation methods.
  */
+/**
+ * The debug bar must not be able to take down the app it observes
+ * (#1900 lot C.1).
+ *
+ * Before this, a bar that threw during render propagated the error to the root
+ * and killed the application — a diagnostic tool failing precisely when
+ * someone needed it, and the consumer's only way out was to rebuild without
+ * it.
+ *
+ * `onErrorCaptured` returning false stops the error here: the bar is dropped,
+ * the app keeps rendering. The failure is loud in the console rather than on
+ * screen, because a crashed debug tool leaving debris in the corner of a
+ * working app helps nobody.
+ *
+ * This catches THROWN errors only. A runaway render loop throws nothing, so it
+ * needs its own guard — that is the bar's circuit breaker in `@quazardous/qddebug`,
+ * and the two are deliberately separate.
+ *
+ * Exported so the guard can be tested as a unit; the Kernel is its only caller.
+ */
+export function createDebugBarBoundary(BarComponent: Component): Component {
+  return defineComponent({
+    name: 'QdadmDebugBarBoundary',
+    setup() {
+      const failed = ref(false)
+
+      onErrorCaptured((err: unknown) => {
+        if (!failed.value) {
+          failed.value = true
+          console.error(
+            '[qdadm] The debug bar threw and has been removed for this ' +
+              'session. The application is unaffected. Use ?qddebug=off to ' +
+              'keep it off across reloads.',
+            err
+          )
+        }
+        // Stop propagation: the app must not die with its instrument.
+        return false
+      })
+
+      return () => (failed.value ? null : h(BarComponent))
+    },
+  })
+}
+
 export function applyVueMethods(KernelClass: { prototype: Kernel }): void {
   const proto = KernelClass.prototype
 
@@ -69,6 +115,10 @@ export function applyVueMethods(KernelClass: { prototype: Kernel }): void {
     this.layoutComponents = {
       list: layouts.list || layouts.ListLayout || null,
       form: layouts.form || layouts.FormLayout || null,
+      // Until #1922 this literal had no `show` key, so an app that passed one
+      // had it dropped without a word while crud({ show }) kept emitting
+      // `layout: 'show'` for a layout nothing could honour.
+      show: layouts.show || layouts.ShowLayout || null,
       dashboard: layouts.dashboard || layouts.DashboardLayout || null,
       base: layouts.base || layouts.BaseLayout || null,
     }
@@ -102,6 +152,9 @@ export function applyVueMethods(KernelClass: { prototype: Kernel }): void {
       this.options.debugBar?.component && debugBarRef.value
         ? debugBarRef.value
         : null
+    const DebugBarBoundary = DebugBarComponent
+      ? createDebugBarBoundary(DebugBarComponent as Component)
+      : null
     const hasPrimeVue = !!this.options.primevue?.plugin
     const appKey = this._appKey
 
@@ -116,8 +169,8 @@ export function applyVueMethods(KernelClass: { prototype: Kernel }): void {
             children.push(h(ToastListener))
           }
 
-          if (DebugBarComponent) {
-            children.push(h(DebugBarComponent))
+          if (DebugBarBoundary) {
+            children.push(h(DebugBarBoundary))
           }
 
           return h(

package/src/kernel/KernelContext.routing.ts

@@ -9,9 +9,13 @@
  * The string helpers (`singularize`, `toKebab`, `capitalize`) are kept
  * module-local — they're pure, stateless, and were only used by `crud()` and
  * `childPage()`. Keeping them off the prototype keeps the public shape clean.
+ * `singularize` is a thin call into the vendored `pluralize` since #1923: the
+ * hand-rolled version disagreed with the one `EntityManager` uses, and a
+ * framework cannot afford two answers to the same question.
  */
 
 import type { RouteRecordRaw } from 'vue-router'
+import pluralize from '../utils/pluralize'
 import { registry, getRoutes } from '../module/moduleRegistry'
 import type {
   ChildPageOptions,
@@ -26,14 +30,21 @@ import type { KernelContext } from './KernelContext'
 // #1196 Phase B — this-typing against the real KernelContext shape (was Self = any)
 type Self = KernelContext
 
-/** Singularize a plural word (simple English rules) */
+/**
+ * Singularize an entity name (#1923).
+ *
+ * This used to be six hand-rolled lines, while `EntityManager.routePrefix`
+ * used the vendored `pluralize`. Two engines, and they disagreed: `crud()`
+ * named a route `people-show` while `useListPage` looked for `person-show`,
+ * so every navigation helper missed silently — no error at boot, nothing until
+ * someone clicked. They agreed on every regular plural, which is exactly why
+ * it went unnoticed.
+ *
+ * One engine now, the real one. `pluralize` is vendored (#1454) and imports
+ * nothing, so there is no cycle to fear from calling it here.
+ */
 function singularize(plural: string): string {
-  if (plural.endsWith('ies')) return plural.slice(0, -3) + 'y'
-  if (plural.endsWith('ses') || plural.endsWith('xes') || plural.endsWith('zes')) {
-    return plural.slice(0, -2)
-  }
-  if (plural.endsWith('s') && !plural.endsWith('ss')) return plural.slice(0, -1)
-  return plural
+  return pluralize.singular(plural)
 }
 
 /** Convert camelCase to kebab-case (e.g. 'botTasks' → 'bot-tasks') */

package/src/kernel/debugBarKillSwitch.ts

@@ -0,0 +1,79 @@
+/**
+ * The emergency switch for the debug bar (#1900 lot C.3).
+ *
+ * A consumer whose debug bar took down the application it was observing had
+ * no way to turn it off: they had to rebuild and redeploy. A diagnostic tool
+ * that can only be disabled by a deploy fails exactly when it is needed.
+ *
+ * So the bar answers to a switch that needs no rebuild and no code change:
+ *
+ *   ?qddebug=off   turn it off, and REMEMBER that across navigations
+ *   ?qddebug=on    turn it back on (clears the memory)
+ *
+ * The query parameter is the way in — it is the only thing reachable when the
+ * app is unusable — and localStorage is what makes it stick, so the next page
+ * load is survivable too. Without persistence the switch would be lost by the
+ * first redirect, which is the moment a broken app is most likely to hit.
+ *
+ * This is a KILL switch, deliberately one-directional in effect: it can only
+ * take the bar away, never conjure one that `enabled: false` refused. See
+ * [[docs/adr/0011]] — the point of the switch is that it does something
+ * observable, and `?qddebug=on` on an app with no bar configured stays a
+ * no-op because there is nothing to turn on.
+ */
+
+/** localStorage key, under qddebug's existing `qddebug:` namespace (ADR 0008). */
+const KILL_KEY = 'qddebug:off'
+
+/** Read a key without letting a hostile storage throw into the boot path. */
+function readFlag(): boolean {
+  try {
+    return localStorage.getItem(KILL_KEY) === '1'
+  } catch {
+    // Private mode, disabled cookies, quota. Absent, not fatal.
+    return false
+  }
+}
+
+function writeFlag(on: boolean): void {
+  try {
+    if (on) localStorage.setItem(KILL_KEY, '1')
+    else localStorage.removeItem(KILL_KEY)
+  } catch {
+    // The switch still holds for THIS page load — the caller uses our return
+    // value, not the storage. It just will not survive a reload.
+  }
+}
+
+/**
+ * Whether the debug bar has been killed for this browser.
+ *
+ * Reads the query parameter first (it is an explicit act, and it updates the
+ * remembered state), then falls back to what was remembered.
+ *
+ * Safe to call before anything is mounted, and outside a browser.
+ */
+export function isDebugBarKilled(): boolean {
+  if (typeof window === 'undefined') return false
+
+  let param: string | null = null
+  try {
+    param = new URLSearchParams(window.location.search).get('qddebug')
+  } catch {
+    // Nothing readable in the URL; fall through to the remembered flag.
+  }
+
+  if (param === 'off') {
+    writeFlag(true)
+    return true
+  }
+  if (param === 'on') {
+    writeFlag(false)
+    return false
+  }
+
+  return readFlag()
+}
+
+/** Exported for tests and for an app that wants to offer its own switch. */
+export const DEBUG_BAR_KILL_KEY = KILL_KEY