@quazardous/qdadm 2.17.3 → 2.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quazardous/qdadm",
-  "version": "2.17.3",
+  "version": "2.18.0",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",
@@ -55,7 +55,7 @@
   ],
   "dependencies": {
     "@quazardous/qdcore": "^1.1.2",
-    "@quazardous/qddebug": "^1.1.0",
+    "@quazardous/qddebug": "^1.2.0",
     "@quazardous/quarkernel": "^2.1.0",
     "yaml": "^2.8.4"
   },

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

@@ -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()
   }
 
@@ -1018,7 +1022,7 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
     headerActionsMap,
     actionRegistry,
   })
-  const { invokeListAlterHook } = alterHooks
+  const { invokeListAlterHook, invokeFilterAlterHook } = alterHooks
 
   // ============ LIFECYCLE ============
   initFromRegistry()
@@ -1030,18 +1034,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/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'
@@ -144,10 +145,29 @@ export class Kernel {
       const debugModule = new DebugModuleClass(debugModuleOptions)
       options.moduleDefs = options.moduleDefs || []
       options.moduleDefs.push(debugModule)
+
+      // `enabled: false` now actually disables (#1900 lot D).
+      //
+      // The component used to be registered whatever `enabled` said, and
+      // Kernel forced options.debug = true on top — which DebugModule.enabled()
+      // reads as "turn on". A consumer who wrote `debugBar: { enabled: false }`
+      // to switch the bar OFF found it running in PRODUCTION, and the only way
+      // out was to omit the key entirely.
+      //
+      // Note this cuts both ways: an app that passed `enabled: false` believing
+      // 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.
+      // 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(options.debugBar.component || null)
-      // Enable debug mode
-      if (!options.debug) {
+      setQdadmDebugBar(debugBarEnabled ? options.debugBar.component || null : null)
+
+      // Debug mode follows the bar, and only when the bar is actually on.
+      if (debugBarEnabled && !options.debug) {
         options.debug = true
       }
     }

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
 
@@ -102,6 +148,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 +165,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/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