@quazardous/qdadm 2.20.0 → 2.22.0

package/src/entity/auth/SecurityChecker.ts

@@ -15,6 +15,43 @@ export interface RoleProvider {
   readonly canPersist: boolean
 }
 
+/**
+ * What an application's judge receives at install time (#2225).
+ */
+export interface GrantJudgeContext {
+  orchestrator?: unknown
+  signals?: unknown
+  /**
+   * The live permission registry — a REFERENCE, not a snapshot.
+   *
+   * `install` runs while the Kernel is still being built, before modules
+   * register their entities, so `getKeys()` called here returns only the
+   * framework's own namespaces. Read the keys when you pre-warm (after login,
+   * before mount), not in `install`.
+   */
+  permissionRegistry?: { getKeys(): string[] }
+}
+
+/**
+ * An application-provided judgement of permissions (#2225).
+ *
+ * For apps whose backend decides who may do what: the judge answers from its
+ * own cache instead of qdadm's role matrix. It is consulted FIRST, for roles
+ * and permissions alike.
+ *
+ * - `true` / `false` is the verdict.
+ * - Anything else (`undefined`, `null`, a cache miss) falls through to the
+ *   built-in judgement, which stays the default.
+ * - A judge that THROWS denies — see `SecurityChecker._judge`.
+ *
+ * `isGranted` is called synchronously on every check, so answer from memory.
+ * Fetch in bulk beforehand and emit `security:changed` when answers change.
+ */
+export interface GrantJudge {
+  isGranted(attribute: string, subject: unknown, user: AuthUser): boolean | undefined
+  install?(ctx: GrantJudgeContext): void
+}
+
 /**
  * SecurityChecker constructor options
  */
@@ -22,6 +59,8 @@ export interface SecurityCheckerOptions {
   rolesProvider?: RoleProvider
   roleHierarchy?: RoleHierarchy | RoleHierarchyConfig
   rolePermissions?: Record<string, string[]>
+  /** Application-provided judgement, consulted first (#2225). */
+  grant?: GrantJudge
   getCurrentUser: () => AuthUser | null
 }
 
@@ -32,6 +71,8 @@ export interface SecurityCheckerConfig {
   rolesProvider?: RoleProvider
   role_hierarchy?: RoleHierarchyConfig
   role_permissions?: Record<string, string[]>
+  /** Application-provided judgement, consulted first (#2225). */
+  grant?: GrantJudge
   getCurrentUser: () => AuthUser | null
 }
 
@@ -55,8 +96,12 @@ export class SecurityChecker {
   readonly getCurrentUser: () => AuthUser | null
   /** Roles already warned about (warn-once, #1388) */
   protected _warnedRoles = new Set<string>()
+  /** Application-provided judgement, consulted before the role matrix (#2225) */
+  protected _grant: GrantJudge | null
+  /** Attributes whose judge already threw (report-once) */
+  protected _judgeFailures = new Set<string>()
 
-  constructor({ rolesProvider, roleHierarchy, rolePermissions, getCurrentUser }: SecurityCheckerOptions) {
+  constructor({ rolesProvider, roleHierarchy, rolePermissions, grant, getCurrentUser }: SecurityCheckerOptions) {
     if (rolesProvider) {
       this._rolesProvider = rolesProvider
     } else {
@@ -75,6 +120,12 @@ export class SecurityChecker {
     }
 
     this.getCurrentUser = getCurrentUser
+    this._grant = grant ?? null
+  }
+
+  /** The application's judge, when one is configured (#2225). */
+  get grant(): GrantJudge | null {
+    return this._grant
   }
 
   /**
@@ -108,10 +159,15 @@ export class SecurityChecker {
    *
    * This is the main contract method, similar to Symfony's isGranted().
    */
-  isGranted(attribute: string, _subject: unknown = null): boolean {
+  isGranted(attribute: string, subject: unknown = null): boolean {
     const user = this.getCurrentUser()
     if (!user) return false
 
+    // 0. The application's own judgement comes first (#2225). A boolean is a
+    //    verdict; anything else falls through to the built-in matrix below.
+    const verdict = this._judge(attribute, subject, user)
+    if (verdict !== undefined) return verdict
+
     // 1. Check if it's a role (ROLE_*)
     if (attribute.startsWith('ROLE_')) {
       return this.roleHierarchy.isGrantedRole(user.roles || [user.role || ''], attribute)
@@ -122,6 +178,34 @@ export class SecurityChecker {
     return PermissionMatcher.any(userPerms, attribute)
   }
 
+  /**
+   * Ask the application's judge, if any.
+   *
+   * A judge that THROWS denies. Falling through to the built-in matrix would
+   * quietly substitute a different authority for the one the app configured,
+   * and failing open would grant whatever the backend never got to answer —
+   * the worst direction a security check can fail in (the rule the route
+   * guard already follows, #1190). Reported once per attribute.
+   */
+  protected _judge(attribute: string, subject: unknown, user: AuthUser): boolean | undefined {
+    if (!this._grant) return undefined
+    let answer: unknown
+    try {
+      answer = this._grant.isGranted(attribute, subject, user)
+    } catch (error) {
+      if (!this._judgeFailures.has(attribute)) {
+        this._judgeFailures.add(attribute)
+        console.error(
+          `[qdadm] security.grant threw while judging "${attribute}" — DENIED. ` +
+            `A failing judge denies rather than falling back to the role matrix.`,
+          error
+        )
+      }
+      return false
+    }
+    return typeof answer === 'boolean' ? answer : undefined
+  }
+
   /**
    * Get all permissions for a user (resolved from roles + user overrides)
    */
@@ -203,6 +287,7 @@ export function createSecurityChecker(config: SecurityCheckerConfig): SecurityCh
   if (config.rolesProvider) {
     return new SecurityChecker({
       rolesProvider: config.rolesProvider,
+      grant: config.grant,
       getCurrentUser: config.getCurrentUser,
     })
   }
@@ -213,6 +298,7 @@ export function createSecurityChecker(config: SecurityCheckerConfig): SecurityCh
       role_hierarchy: config.role_hierarchy || {},
       role_permissions: config.role_permissions || {},
     }),
+    grant: config.grant,
     getCurrentUser: config.getCurrentUser,
   })
 }

package/src/entity/auth/index.ts

@@ -23,6 +23,8 @@ export type {
   RoleProvider,
   SecurityCheckerOptions,
   SecurityCheckerConfig,
+  GrantJudge,
+  GrantJudgeContext,
 } from './SecurityChecker'
 
 // Implementations

package/src/i18n/defaults/DefaultCoreProvider.ts

@@ -1,6 +1,8 @@
 /**
- * Default core provider — ships qdadm's `core.*` defaults (EN + FR) as a
- * `LazyTranslationProvider` configured with a YAML loader.
+ * Default core provider — ships qdadm's own defaults (EN + FR) as a
+ * `LazyTranslationProvider` configured with a YAML loader: the `core.*` tree,
+ * plus the `breadcrumb.*` keys the breadcrumb's View↔Edit toggle reads (#2270).
+ * It comes first in the provider chain, so an app's own translations win.
  *
  * The YAML text is imported from `core.<locale>.generated.ts` — plain TS
  * modules that `export default` the raw YAML string, generated from the

package/src/i18n/defaults/__tests__/generated-sync.test.ts

@@ -39,4 +39,13 @@ describe('i18n default providers — generated/.yml sync', () => {
     expect(en.core.actions.save).toBe('Save')
     expect(fr.core.actions.save).toBe('Enregistrer')
   })
+
+  it('ships the breadcrumb View↔Edit labels next to core.* (#2270)', async () => {
+    type BreadcrumbBundle = { breadcrumb: { view: string; edit: string } }
+    const provider = createDefaultCoreProvider()
+    const en = (await provider.load('en')) as BreadcrumbBundle
+    const fr = (await provider.load('fr')) as BreadcrumbBundle
+    expect(en.breadcrumb).toEqual({ view: 'View', edit: 'Edit' })
+    expect(fr.breadcrumb).toEqual({ view: 'Voir', edit: 'Modifier' })
+  })
 })

package/src/i18n/defaults/core.en.generated.ts

@@ -55,4 +55,24 @@ export default `core:
     invalid: Invalid value
     notFound: Not found
     unknown: An unknown error occurred
+  # RoleGrantsEditor (#2313)
+  roles:
+    inherits: Inherits from
+    inheritsHint: A role gets every grant of the roles it inherits from.
+    noRoles: No other role to inherit from
+    brings: "brings {count}"
+    entities: Entities
+    entity: Entity
+    all: All
+    ownRecords: own records
+    others: Other grants
+    othersHint: Wildcards and keys the registry does not know
+    covers: "covers {count}"
+    notRegistered: not registered
+    remove: Remove
+    via: "via {origin}"
+# The breadcrumb's View↔Edit toggle (useNavContext).
+breadcrumb:
+  view: View
+  edit: Edit
 `

package/src/i18n/defaults/core.en.yml

@@ -53,3 +53,23 @@ core:
     invalid: Invalid value
     notFound: Not found
     unknown: An unknown error occurred
+  # RoleGrantsEditor (#2313)
+  roles:
+    inherits: Inherits from
+    inheritsHint: A role gets every grant of the roles it inherits from.
+    noRoles: No other role to inherit from
+    brings: "brings {count}"
+    entities: Entities
+    entity: Entity
+    all: All
+    ownRecords: own records
+    others: Other grants
+    othersHint: Wildcards and keys the registry does not know
+    covers: "covers {count}"
+    notRegistered: not registered
+    remove: Remove
+    via: "via {origin}"
+# The breadcrumb's View↔Edit toggle (useNavContext).
+breadcrumb:
+  view: View
+  edit: Edit

package/src/i18n/defaults/core.fr.generated.ts

@@ -55,4 +55,24 @@ export default `core:
     invalid: Valeur invalide
     notFound: Introuvable
     unknown: Une erreur inconnue est survenue
+  # RoleGrantsEditor (#2313)
+  roles:
+    inherits: Hérite de
+    inheritsHint: Un rôle reçoit toutes les permissions des rôles dont il hérite.
+    noRoles: Aucun autre rôle dont hériter
+    brings: "apporte {count}"
+    entities: Entités
+    entity: Entité
+    all: Tout
+    ownRecords: ses propres enregistrements
+    others: Autres permissions
+    othersHint: Jokers et clés que le registre ne connaît pas
+    covers: "couvre {count}"
+    notRegistered: non enregistrée
+    remove: Retirer
+    via: "via {origin}"
+# The breadcrumb's View↔Edit toggle (useNavContext).
+breadcrumb:
+  view: Voir
+  edit: Modifier
 `

package/src/i18n/defaults/core.fr.yml

@@ -53,3 +53,23 @@ core:
     invalid: Valeur invalide
     notFound: Introuvable
     unknown: Une erreur inconnue est survenue
+  # RoleGrantsEditor (#2313)
+  roles:
+    inherits: Hérite de
+    inheritsHint: Un rôle reçoit toutes les permissions des rôles dont il hérite.
+    noRoles: Aucun autre rôle dont hériter
+    brings: "apporte {count}"
+    entities: Entités
+    entity: Entité
+    all: Tout
+    ownRecords: ses propres enregistrements
+    others: Autres permissions
+    othersHint: Jokers et clés que le registre ne connaît pas
+    covers: "couvre {count}"
+    notRegistered: non enregistrée
+    remove: Retirer
+    via: "via {origin}"
+# The breadcrumb's View↔Edit toggle (useNavContext).
+breadcrumb:
+  view: Voir
+  edit: Modifier

package/src/index.ts

@@ -262,6 +262,7 @@ export {
 } from './composables/usePageTitle'
 export { useApp, type UseAppReturn } from './composables/useApp'
 export { useAuth, type UseAuthReturn } from './composables/useAuth'
+export { useSecurity, type UseSecurityReturn } from './composables/useSecurity'
 export {
   useEntityItemPage,
   type UseEntityItemPageOptions,

package/src/kernel/Kernel.auth.ts

@@ -120,11 +120,15 @@ export function applyAuthMethods(KernelClass: { prototype: Kernel }): void {
    */
   proto._setupAuthInvalidation = function (this: Self): void {
     const debug = this.options.debug ?? false
+    // `security:changed` (#2225) rides the same path: nothing on screen reads
+    // permissions reactively (canCreate, menu filtering and the route guard
+    // all ask synchronously), so a remount is what makes new answers show.
     const authSignals = [
       'auth:login',
       'auth:logout',
       'auth:impersonate',
       'auth:impersonate:stop',
+      'security:changed',
     ]
 
     for (const signal of authSignals) {

package/src/kernel/Kernel.registries.ts

@@ -141,6 +141,15 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
       )
     }
 
+    // A `grant` that cannot judge would be silently skipped, leaving the role
+    // matrix to decide alone while the app believes its backend does (#2225).
+    if (security.grant && typeof security.grant.isGranted !== 'function') {
+      throw new Error(
+        '[qdadm] security.grant must provide isGranted(attribute, subject, user). ' +
+          'Without it the application judgement would be skipped and the role matrix would decide alone.'
+      )
+    }
+
     let rolesProvider = security.rolesProvider
     if (!rolesProvider && (security.role_permissions || security.role_hierarchy)) {
       rolesProvider = new StaticRoleProvider({
@@ -152,6 +161,7 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
 
     this.securityChecker = createSecurityChecker({
       rolesProvider: rolesProvider || undefined,
+      grant: security.grant,
       getCurrentUser: () =>
         (entityAuthAdapter as EntityAuthAdapter | null)?.getCurrentUser?.() || null,
     })
@@ -165,14 +175,22 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
       adapter.setSecurityChecker(this.securityChecker)
     }
 
+    // One context for both installers. `permissionRegistry` lets a provider or
+    // a judge pre-warm in one batch (#2225) — but modules register their
+    // entities AFTER this point, so the keys must be read at fetch time, not
+    // inside install().
+    const ctx = {
+      orchestrator: this.orchestrator,
+      signals: this.signals,
+      permissionRegistry: this.permissionRegistry,
+    }
     if (rolesProvider?.install) {
-      const ctx = {
-        orchestrator: this.orchestrator,
-        signals: this.signals,
-      }
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       rolesProvider.install(ctx as any)
     }
+    if (security.grant?.install) {
+      security.grant.install(ctx)
+    }
   }
 
   /**
@@ -388,12 +406,13 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
     this._warnUnknownKeys(
       'security.',
       security,
-      new Set(['role_hierarchy', 'role_permissions', 'role_labels', 'entity_permissions', 'rolesProvider']),
+      new Set(['role_hierarchy', 'role_permissions', 'role_labels', 'entity_permissions', 'rolesProvider', 'grant']),
       {
         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",
+        grant: "the application's judgement will not be consulted — the role matrix decides alone",
       }
     )
   }

package/src/kernel/Kernel.routing.ts

@@ -7,6 +7,7 @@ import {
   type RouteRecordNormalized,
 } from 'vue-router'
 import { getRoutes } from '../module/moduleRegistry'
+import { installChunkReload } from './chunkReload'
 import type { Kernel } from './Kernel'
 // #1196 Phase B — this-typing against the real Kernel shape (was Self = any)
 type Self = Kernel
@@ -148,6 +149,20 @@ export function applyRoutingMethods(KernelClass: { prototype: Kernel }): void {
     })
   }
 
+  /**
+   * A lazy page whose chunk is gone, typically after a deploy (#2295): reload once, then say so.
+   */
+  proto._setupChunkReload = function (this: Self): void {
+    installChunkReload(this.router!, {
+      notify: () =>
+        this.orchestrator!.toast.error(
+          'A new version is available',
+          'This page could not be loaded. Reload the page to get the new version.',
+          { life: 0, emitter: 'Kernel' }
+        ),
+    })
+  }
+
   /**
    * Setup auth guard on router
    */
@@ -190,7 +205,9 @@ export function applyRoutingMethods(KernelClass: { prototype: Kernel }): void {
       )
 
       if (requiresAuth && !authAdapter.isAuthenticated()) {
-        if (wasEverAuthenticated) {
+        // Only a session this tab had can be lost: a first visit goes to login without the flag (#2292).
+        const sessionLost = wasEverAuthenticated
+        if (sessionLost) {
           const debug = this.options.debug ?? false
           if (debug) {
             console.warn(
@@ -204,9 +221,8 @@ export function applyRoutingMethods(KernelClass: { prototype: Kernel }): void {
           wasEverAuthenticated = false
         }
 
-        return this.router!.hasRoute('login')
-          ? { name: 'login', query: { session_lost: '1' } }
-          : '/'
+        if (!this.router!.hasRoute('login')) return '/'
+        return sessionLost ? { name: 'login', query: { session_lost: '1' } } : { name: 'login' }
       }
 
       const entity = to.meta?.entity as string | undefined

package/src/kernel/Kernel.ts

@@ -228,6 +228,7 @@ export class Kernel {
     this._createRouter()
     this._setupStackSync()
     this._setupAuthGuard()
+    this._setupChunkReload()
     this._setupAuthExpiredHandler()
     this._setupAuthImpersonation()
     this._setupAuthInvalidation()
@@ -262,6 +263,7 @@ export class Kernel {
     this._createRouter()
     this._setupStackSync()
     this._setupAuthGuard()
+    this._setupChunkReload()
     this._setupAuthExpiredHandler()
     this._setupAuthImpersonation()
     this._setupAuthInvalidation()
@@ -467,6 +469,7 @@ export interface Kernel {
   // Routing (Kernel.routing.ts)
   _createRouter(): void
   _setupAuthGuard(): void
+  _setupChunkReload(): void
   _setupStackSync(): void
   _rebuildActiveStack(route: RouteLocationNormalized): void
 

package/src/kernel/Kernel.types.ts

@@ -10,6 +10,7 @@ import type { RoutesConfig } from './EventRouter'
 import type { EntityManager } from '../entity/EntityManager'
 import type { EntityAuthAdapter } from '../entity/auth/EntityAuthAdapter'
 import type { RoleProvider } from '../security/RolesProvider'
+import type { GrantJudge } from '../entity/auth/SecurityChecker'
 import type { I18nOptions } from '../i18n/types'
 import type { ApiClientSource } from '../api/apiClient'
 import type { RouteStatePersister } from '../routeState'
@@ -98,7 +99,12 @@ export interface SecurityConfig {
   role_permissions?: Record<string, string[]>
   role_labels?: Record<string, string>
   entity_permissions?: boolean | string[]
-  rolesProvider?: RoleProvider
+  rolesProvider?: RoleProvider  /**
+   * Application-provided judgement (#2225), consulted before the role matrix.
+   * `true`/`false` is the verdict, anything else falls through; a judge that
+   * throws denies. See docs/security.md.
+   */
+  grant?: GrantJudge
 }
 
 /**

package/src/kernel/Kernel.vue.ts

@@ -17,6 +17,7 @@ import ToastListener from '../toast/ToastListener.vue'
 import { createQdadm } from '../plugin.js'
 import { createNotificationStore, NOTIFICATION_KEY } from '../notifications/NotificationStore'
 import { I18N_INJECTION_KEY } from '../i18n/useI18n'
+import { warnWithoutQdadmVitePlugin } from './vitePluginCheck'
 import type { Kernel } from './Kernel'
 // #1196 Phase B — this-typing against the real Kernel shape (was Self = any)
 type Self = Kernel
@@ -197,6 +198,8 @@ export function applyVueMethods(KernelClass: { prototype: Kernel }): void {
    * ConfirmationService.
    */
   proto._installPlugins = function (this: Self): void {
+    // Before PrimeVue: without the vite plugin, PrimeVue is what fails, without naming qdadm (#2259).
+    warnWithoutQdadmVitePlugin()
     const app = this.vueApp!
     const { authAdapter, features, primevue, existingApp } = this.options
     // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/src/kernel/SignalBus.ts

@@ -43,6 +43,12 @@ export const SIGNALS = {
   AUTH_LOGOUT: 'auth:logout',
   AUTH_EXPIRED: 'auth:expired', // Emitted on 401/403 API responses
 
+  // Security signals
+  // The application's permission answers changed — every screen re-evaluates
+  // (#2225). Emit it only when an answer actually differs: it remounts the app,
+  // which discards unsaved form state.
+  SECURITY_CHANGED: 'security:changed',
+
   // API error signals
   API_ERROR: 'api:error', // Emitted on any API error { status, message, url }
 } as const

package/src/kernel/chunkReload.ts

@@ -0,0 +1,110 @@
+/**
+ * A lazy page whose chunk no longer exists (#2295), typically in a tab left open across a deploy: the build renamed
+ * its hashed chunks, the tab still runs the old bundle, and the import 404s. The router aborts the navigation and
+ * nothing tells the user; on a first load the screen stays blank.
+ *
+ * The page reloads once, at the URL the user was going to, which fetches the new index.html. A flag in
+ * sessionStorage keeps a chunk that is really missing from reloading in a loop: a second failure is reported
+ * instead. The flag is cleared by the next navigation that succeeds.
+ */
+import type { Router } from 'vue-router'
+
+export const CHUNK_RELOAD_KEY = 'qdadm:chunk-reload'
+
+// Chrome, Firefox, Safari, Vite's preload helper, webpack.
+const CHUNK_ERROR =
+  /Failed to fetch dynamically imported module|error loading dynamically imported module|Importing a module script failed|Unable to preload CSS|ChunkLoadError|Loading chunk \S+ failed/i
+
+export function isChunkLoadError(error: unknown): boolean {
+  if (!error) return false
+  const { name, message } = error as { name?: unknown; message?: unknown }
+  return CHUNK_ERROR.test(`${String(name ?? '')} ${typeof message === 'string' ? message : String(error)}`)
+}
+
+type FlagStorage = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>
+
+export interface ChunkReloadOptions {
+  /** A second failure, or no way to guard a reload: tell the user. */
+  notify(error: unknown): void
+  /** Default: sessionStorage. Without one, nothing reloads: a loop could not be stopped. */
+  storage?: FlagStorage | null
+  /** Default: load `href` for real. */
+  reload?(href: string): void
+  /** Where Vite dispatches `vite:preloadError`. Default: window. */
+  target?: EventTarget | null
+}
+
+function sessionFlags(): FlagStorage | null {
+  try {
+    return typeof sessionStorage === 'undefined' ? null : sessionStorage
+  } catch {
+    return null
+  }
+}
+
+function reloadAt(href: string): void {
+  const url = new URL(href, window.location.href).href
+  // The failed navigation never changed the URL; the reload must land where the user was going.
+  if (url !== window.location.href) window.history.pushState(null, '', url)
+  window.location.reload()
+}
+
+/** Returns a function that removes the handlers. */
+export function installChunkReload(router: Router, options: ChunkReloadOptions): () => void {
+  const storage = options.storage === undefined ? sessionFlags() : options.storage
+  const reload = options.reload ?? reloadAt
+  const target = options.target === undefined ? (typeof window === 'undefined' ? null : window) : options.target
+  let reloading = false
+
+  const failed = (error: unknown, href: string | null) => {
+    if (reloading) return
+    let tried = true
+    try {
+      tried = !storage || storage.getItem(CHUNK_RELOAD_KEY) !== null
+      if (!tried) storage!.setItem(CHUNK_RELOAD_KEY, String(Date.now()))
+    } catch {
+      tried = true
+    }
+    if (tried) {
+      console.error('[qdadm] a page could not be loaded, and reloading did not help', error)
+      options.notify(error)
+      return
+    }
+    reloading = true
+    console.warn('[qdadm] a page could not be loaded, probably a new deploy: reloading once', error)
+    reload(href ?? (typeof window === 'undefined' ? '/' : window.location.href))
+  }
+
+  let routerSaw = false
+  const removeOnError = router.onError((error, to) => {
+    if (!isChunkLoadError(error)) return
+    routerSaw = true
+    failed(error, to ? router.resolve(to).href : null)
+  })
+  const removeAfterEach = router.afterEach((_to, _from, failure) => {
+    if (failure || reloading) return
+    try {
+      storage?.removeItem(CHUNK_RELOAD_KEY)
+    } catch {
+      /* nothing to clear */
+    }
+  })
+
+  // Vite dispatches this before the import rejects. When the import belongs to a navigation, the router hears the
+  // rejection a few microtasks later and handles it with the page the user wanted; waiting one task lets it go
+  // first, and the failure is then not handled twice.
+  const onPreloadError = (event: Event) => {
+    const error = (event as Event & { payload?: unknown }).payload ?? event
+    routerSaw = false
+    setTimeout(() => {
+      if (!routerSaw) failed(error, null)
+    }, 0)
+  }
+  target?.addEventListener('vite:preloadError', onPreloadError)
+
+  return () => {
+    removeOnError()
+    removeAfterEach()
+    target?.removeEventListener('vite:preloadError', onPreloadError)
+  }
+}