spiderly 19.10.0 → 19.11.0

package/agent/docs/angular-customization/index.md

@@ -205,6 +205,8 @@ new Column({ field: 'total', name: 'Total', filterType: 'numeric',
 
 It receives a `CellClickEvent` — `{ id, field, row, value, displayValue, element, originalEvent }`, where `value` is the raw cell value and `displayValue` is the formatted text shown. Only columns that set it become clickable (they get a `cursor`/hover affordance), and the click stops propagation so it does **not** also trigger `navigateOnRowClick`. Anchor overlays with `element` — it's the clicked `<td>`, captured synchronously, so it stays valid inside an async handler (`originalEvent.currentTarget` is null once dispatch ends). Not applied to editable cells. (Reusing one popover across rows is the `show()` + `align()` case shown in the snippet above — bare `show()` swaps content but won't move an already-open panel.)
 
+Style the popover's content at your component's SCSS **top level**, never nested under `:host` — PrimeNG appends the open popover to `document.body`, where `:host`-scoped rules (compiled to `[_nghost] … [_ngcontent]` descendant selectors) silently stop matching; top-level rules keep the `[_ngcontent]` scoping that travels with the moved nodes.
+
 ### Custom Toolbar Actions
 
 Project an `<ng-template spiderlyDataTableActions>` to add your own buttons (or any markup) to the table's toolbar, alongside the built-in Clear Filters / Export to Excel / Reload / Delete Selected buttons. Import `SpiderlyDataTableActionsDirective` in the consuming component.
@@ -361,6 +363,8 @@ menu: SpiderlyMenuItem[] = [
 </spiderly-layout>
 ```
 
+The side menu's desktop collapse state persists automatically (localStorage key `spiderly-layout:menu-desktop-inactive`), so the sidebar stays collapsed/expanded across reloads.
+
 ## Validation
 
 ### ValidatorAbstractService

package/agent/docs/entity-design/index.md

@@ -25,6 +25,23 @@ namespace Foo.Business.Entities
 
 Hand-written DTOs use `[SpiderlyDTO]`. Generated DTOs (`{Entity}DTO`, `{Entity}SaveBodyDTO`, `{Entity}MainUIFormDTO`) need no marker. The `spiderly add-new-entity` CLI emits `[SpiderlyEntity]` automatically.
 
+### Generated DTO nullability
+
+`[Required]` decides it for **reference types only**:
+
+| Entity property           | Generated DTO property                                    |
+| ------------------------- | --------------------------------------------------------- |
+| `[Required] string Name`  | `string Name { get; set; } = null!;`                       |
+| `string Slug`             | `string? Slug` (bare `string` for a nullable-oblivious app) |
+| `[Required] int Quantity` | `int? Quantity` — value types stay nullable, see below      |
+| `int Stock`               | `int? Stock`                                                |
+| any navigation            | `long? CategoryId` + `string? CategoryDisplayName`          |
+| any collection            | unchanged, with `= new()`                                   |
+
+**Value types stay nullable even under `[Required]`, deliberately.** A generated `{Entity}DTO` serves four roles at once: response shape, request shape, the Angular form model (an empty numeric input posts `null`), and the sparse placeholder carrier for `[ComplexManyToManyList]` grids, where an all-null row *is* the "no record" sentinel. The last two need `null` to be representable, and `int` cannot hold it. Reference types are safe to tighten because, with `RespectNullableAnnotations` off, a non-nullable `string` still accepts `null` at runtime — `= null!` is an assertion for the compiler and for humans, not a runtime constraint.
+
+**The C# annotation is invisible to the OpenAPI spec unless the app opts in** with `spiderly.AddSwagger(options => options.SupportNonNullableReferenceTypes())`. Not on by default: it narrows the published contract (members become `required`), which regenerates every consumer's typed client — schedule it as its own deploy. `spiderly init` scaffolds it, since a new app has no consumers yet. `AddSwagger`'s callback runs after Spiderly's defaults and is the seam for any other Swashbuckle option too.
+
 ## Base Classes
 
 | Base Class          | Use When               | Generated                                        |
@@ -67,7 +84,7 @@ public virtual Brand Brand { get; set; }
 ### When to use it
 
 - **Hand-written save/sync code** that builds the entity directly (`new Order { BrandId = id, ... }`) — skips the `FindAsync` + navigation-attach roundtrip that the naive pattern requires
-- **Hot read paths** with `ProjectToDTO` — the mapper emits `x.BrandId` instead of the `EF.Property<long>(x, "BrandId")` workaround for [EF Core #15826](https://github.com/dotnet/efcore/issues/15826), which otherwise still forces a JOIN in some queries
+- **Hot read paths** in mapper projections — the mapper emits `x.BrandId` instead of the `EF.Property<long>(x, "BrandId")` workaround for [EF Core #15826](https://github.com/dotnet/efcore/issues/15826), which otherwise still forces a JOIN in some queries
 
 ### Rules
 
@@ -298,7 +315,6 @@ The complete list of every Spiderly attribute and its valid target is generated
 | `[ExcludeServiceMethodsFromGeneration]` | Property       | Skip generated service methods (implement custom logic)                                              |
 | `[GreaterThanOrEqualTo(N)]`             | Property       | Numeric minimum validation                                                                           |
 | `[Email]`                               | Property       | Email format validation                                                                              |
-| `[ProjectToDTO(".Map(...)")]`           | Class          | Custom Mapster projection                                                                            |
 | `[GenerateCommaSeparatedDisplayName]`   | Property       | Add comma-separated display names to DTO                                                             |
 | `[ComplexManyToManyList]`               | Property       | Editable list UI for complex M2M junction (small sets only)                                          |
 | `[ComplexManyToManyReadonlyTable]`      | Property       | Read-only table for complex M2M junction                                                             |

package/agent/docs/entity-design/references/attributes.generated.md

@@ -27,7 +27,6 @@
 | `[M2MWithMany]` | Property | Marks a property in a many-to-many (M2M) relationship. |
 | `[MaxFileSize]` | Property | Specifies the maximum allowed file size (in bytes) for a blob property. When not applied, the file upload defaults to 20 MB (20,000,000 bytes). Use this attribute alongside any StorageAttribute subclass for file uploads. |
 | `[Output]` | All | Specifies the output configuration for the Source Generator. Note: This is a temporary solution and may be replaced in future versions. |
-| `[ProjectToDTO]` | Class | Specifies custom mapping configuration when projecting an entity to its DTO. |
 | `[ReadOnly]` | Property | Marks a property as server-owned: the client may read it, but can never write it (mirrors OpenAPI readOnly). The property stays in the read {Entity}DTO — so it's still returned by GET endpoints and shown in the list table — but the generator closes the write path for it: no inbound FluentValidation rule is emitted, and the generated DTO→entity Mapster config .Ignore()s it, so a crafted payload can't tamper with it. It also gets no editable control in the generated details form. Use for values only backend code assigns — usage counters, denormalized aggregates, computed timestamps. Combine with [Required] to document the non-null DB column without generating an unsatisfiable inbound rule (the form never sends it). This differs from [UIDoNotGenerate] (hidden from the form but still writable and validated) and [ExcludeFromDTO] (dropped from every DTO, unreadable). |
 | `[S3PrivateStorage]` | Property | Routes upload/delete operations for the decorated string property through S3PrivateStorageService. The column stores an opaque S3 key; access is expected to be mediated via signed URLs or a backend proxy rather than direct CDN retrieval. Intended for files that contain personal or compliance-sensitive data (warranty receipts, ID documents, customer-uploaded invoices). |
 | `[S3PublicStorage]` | Property | Routes upload/delete operations for the decorated string property through S3PublicStorageService. The bucket is configured for public access and the column stores a fully-qualified CDN URL; objects are uploaded with Cache-Control: public, max-age=31536000, immutable. |

package/agent/docs/mapper-customization/index.md

@@ -1,6 +1,6 @@
 ---
 name: mapper-customization
-description: Customize Spiderly-generated Mapster mappers. Use when overriding DTO-to-entity or entity-to-DTO mapping, adding computed fields to DTOs, customizing query projections, or using the ProjectToDTO attribute.
+description: Customize Spiderly-generated Mapster mappers. Use when overriding DTO-to-entity or entity-to-DTO mapping, adding computed fields to DTOs, customizing query projections, or implementing Customize* partial mapper hooks.
 ---
 
 # Mapper Customization
@@ -35,48 +35,71 @@ public static TypeAdapterConfig CartToDTOConfig()
 }
 ```
 
-## `[ProjectToDTO]` — Inline Custom Mappings
+## `Customize*` Partial Hooks — Add Mappings in Real C#
 
-Add custom mappings to the projection method without overriding it. Applied to the **entity class** (not properties). `AllowMultiple = true`.
+Every generated config method declares a matching `static partial void Customize{MethodName}(TypeAdapterConfig config)`
+hook and calls it before returning. Implement it in your hand-written `Mapper` partial class to
+**add** custom mappings on top of the generated ones — compiler-checked, IntelliSense-assisted,
+and able to express null guards (which a projection through an optional navigation requires):
 
 ```csharp
-[ProjectToDTO(".Map(dest => dest.TransactionPrice, src => src.Transaction.Price)")]
-public class Achievement : BusinessObject<long>
+[SpiderlyDataMapper]
+public static partial class Mapper
 {
-    // ...
+    static partial void CustomizeOrderItemProjectToConfig(TypeAdapterConfig config)
+    {
+        // ProductVariant is an optional nav (nullable FK) — the guard is mandatory:
+        // an unguarded src.ProductVariant.ProductId LEFT JOINs to NULL and crashes the
+        // EF shaper with "Nullable object must have a value" at materialization.
+        config.ForType<OrderItem, OrderItemDTO>()
+            .Map(dest => dest.ProductId, src => src.ProductVariant != null ? (int?)src.ProductVariant.ProductId : null);
+    }
 }
 ```
 
-The string is appended directly to the generated `.NewConfig<Entity, EntityDTO>()` chain. Use this for simple field mappings that the generator doesn't produce automatically.
+Use `config.ForType<...>()` (get-or-extend), never `NewConfig` (replace) — the generated
+M2O/display-name mappings are already on the config when the hook runs. An unimplemented hook
+compiles away entirely; implementing a hook whose config method you also fully overrode (see below)
+is a compile error (`CS0759`), so a dead hook can't sit around silently.
 
-### `[ProjectToDTO]` only fills the value — the field must exist on the DTO
+**Precedence (verified against Mapster 7.4.0):** `.Map` is *first-registration-wins* — a hook
+`.Map` targeting a member the generator already mapped is a **silent no-op**, not an override.
+`.Ignore` *does* win over an earlier `.Map`. So from a hook you can **add** new member mappings and
+**suppress** generated ones, but you cannot **replace** a generated mapping's expression — that is
+exactly what the full-method override (below) remains for.
 
-`[ProjectToDTO]` adds a Mapster *mapping*; it does **not** create the property. If `dest.ProductId`
-is not a property on the DTO, the field **never appears in the generated Angular type**
-(`entities.generated.ts`) — `[ProjectToDTO]` fills a value that has nowhere to land. (A common
-false alarm: the value maps fine at runtime, so it looks like the frontend "didn't regenerate" —
-but a normal `dotnet build` *does* regenerate the Angular files; the property was just never on
-the DTO for the generator to emit.)
+### Convention flattening is OFF — unmapped extension props stay unmapped
 
-To add a computed/projected field end-to-end, declare the property on a `partial class {Entity}DTO`
-extension — it merges into the generated DTO automatically, no attribute needed — **then** map its value:
+Generated configs strip Mapster's flatten-by-name strategy (`NewStrictConfig()` in the generated
+mapper). Without this, a DTO extension prop named e.g. `ShippingTierIsBulky` would *silently*
+project through `src.ShippingTier.IsBulky` — and when that navigation is optional, the LEFT JOIN's
+NULL crashes the shaper on a non-nullable member. With flattening off, a prop you never mapped
+simply stays at its default; wire it deliberately via a `Customize*` hook.
+
+### The hook only fills the value — the field must exist on the DTO
+
+A mapping does **not** create the property. If `dest.ProductId` is not a property on the DTO, the
+field **never appears in the generated Angular type** (`entities.generated.ts`). Declare the
+property on a `partial class {Entity}DTO` extension — it merges into the generated DTO
+automatically, no attribute needed — **then** map its value in the hook:
 
 ```csharp
-// 1. The property — a partial extension of the generated OrderItemDTO. No [SpiderlyDTO]
-//    needed: a partial that extends a generated DTO is merged in by name.
+// The property — a partial extension of the generated OrderItemDTO. No [SpiderlyDTO]
+// needed: a partial that extends a generated DTO is merged in by name.
 public partial class OrderItemDTO
 {
     public int? ProductId { get; set; }
 }
-
-// 2. The value — [ProjectToDTO] on the entity fills it during projection.
-[ProjectToDTO(".Map(dest => dest.ProductId, src => src.ProductVariant.ProductId)")]
-public class OrderItem : BusinessObject<long> { /* ... */ }
 ```
 
 Then `dotnet build` the backend — the source generators run on build and the field appears
 in `entities.generated.ts`. There is no separate "regenerate" command; the build is it.
 
+> **Removed:** the string-based `[ProjectToDTO(".Map(...)")]` entity attribute. Its string DSL
+> could not express a null guard (the parser choked on anything beyond a bare dotted path), which
+> made unsafe projections through optional navs the *only* writable form. Move any existing usage
+> into the corresponding `Customize{Entity}ProjectToConfig` hook.
+
 ## Partial Method Override — Full Control
 
 For complex mapping logic, override the entire generated method. The generator **skips generation** for any method that already exists in the user's partial `Mapper` class (detected by method name match).
@@ -124,10 +147,9 @@ public static partial class Mapper
 
 | Scenario | Approach |
 |---|---|
-| Add a simple computed field to projection | `[ProjectToDTO(".Map(...)")]` on entity class |
-| Add multiple computed fields to projection | Stack multiple `[ProjectToDTO]` attributes |
-| Complex mapping with conditionals or method calls | Override the full method in `Mapper.cs` |
-| Change DTO → Entity mapping (e.g., ignore a field) | Override `{Entity}DTOToEntityConfig()` |
-| Change Excel export projection | Override `{Entity}ExcelProjectToConfig()` |
+| Add computed/custom fields to any config (projection, DTO, save, Excel) | Implement the matching `Customize{Entity}{Method}` partial hook |
+| Mapping through an optional navigation | `Customize*` hook with an explicit null guard |
+| Suppress a generated mapping | `Customize*` hook with `.Ignore(dest => dest.X)` |
+| Change or replace generated mappings | Override the full method in `Mapper.cs` |
 
 Most projects never need custom mappers — the generated mappings handle M2O, M2M display names, and standard field-to-field mapping automatically.

package/agent/skills/spiderly-upgrade/SKILL.md

@@ -31,7 +31,12 @@ Follow Spiderly's fail-loudly convention: every refused-to-start condition exits
 
    > Working tree must be clean before upgrading. Commit or stash your changes first — the upgrade will make many edits, and a clean tree is your `git restore .` safety net.
 
-4. **Detect current version.** Read all `Spiderly.*` `PackageReference` `Version=` values across every csproj, plus the `"spiderly"` value in `Frontend/package.json`. They should agree. If they drift, list the values and ask the user which to treat as "current".
+4. **Detect current version.** Versions live in one of two places — check for **Central Package Management first**:
+
+   - **CPM (`Directory.Packages.props` exists next to or above the csprojs):** versions are `<PackageVersion Include="Spiderly.X" Version="..." />` there, and the csprojs carry **versionless** `<PackageReference Include="Spiderly.X" />`. Reading `Version=` off the csprojs finds nothing — don't conclude "not a Spiderly app".
+   - **Classic:** `Version=` on each csproj's `PackageReference`.
+
+   Read whichever applies, plus the `"spiderly"` value in `Frontend/package.json`. They should agree. If they drift, list the values and ask the user which to treat as "current". Record which layout you found — Step 6 bumps the same place.
 
 5. **Multi-solution monorepo.** If multiple Backend dirs (each with their own Spiderly refs) exist, ask the user which one to upgrade. One app per invocation.
 
@@ -39,7 +44,7 @@ Follow Spiderly's fail-loudly convention: every refused-to-start condition exits
 
 - If arg is `latest` or omitted: WebFetch `https://api.nuget.org/v3-flatcontainer/spiderly.shared/index.json`, parse the `versions` array, pick the highest stable (no `-` suffix), confirm with the user.
 - Otherwise validate the arg as `X.Y.Z` (or `X.Y.Z-preview.N` if the user is explicitly opting into a preview — warn that preview release notes are usually thin).
-- Reject downgrades: if target < current, exit `Downgrades are not supported. To downgrade, edit Spiderly.* PackageReference Version= attributes and the "spiderly" npm dep manually, then run dotnet restore and npm install.`
+- Reject downgrades: if target < current, exit `Downgrades are not supported. To downgrade, edit the Spiderly.* versions (Directory.Packages.props under CPM, otherwise the csproj PackageReference Version= attributes) and the "spiderly" npm dep manually, then run dotnet restore and npm install.`
 - Reject no-op: if target == current, exit `Already on {version}.`
 
 ## Step 3 — Fetch what changed
@@ -94,7 +99,7 @@ Code edits (N items affect you):
 Manual steps after upgrade:
   - <step the agent can't do for you>
 
-Version bumps: Spiderly.*  19.5.0 → 21.2.0  (4 csproj + Frontend/package.json[ + .claude/settings.json legacy-plugin removal])
+Version bumps: Spiderly.*  19.5.0 → 21.2.0  (Directory.Packages.props | 4 csproj + Frontend/package.json[ + .claude/settings.json legacy-plugin removal])
 
 After approval: apply → bump → migrate guidance + config → restore + install (parallel) → build → agent-sync. Up to 2 build-fix retries on failure.
 ```
@@ -108,7 +113,19 @@ Present the plan and ask the user explicitly. Don't proceed without a clear yes.
 In this order. A failure at any step is a hard stop until the recovery procedure in Step 7.
 
 1. **Code edits.** Apply each plan item via Edit. Read each target file first.
-2. **Version bumps.** Iterate the csproj list cached in Step 1: rewrite every `<PackageReference Include="Spiderly.X" Version="OLD" />` to the new version. Rewrite `"spiderly": "OLD"` in `Frontend/package.json`. Don't re-glob.
+2. **Version bumps.** Bump the layout detected in Step 1.4:
+
+   - **CPM:** rewrite each `<PackageVersion Include="Spiderly.X" Version="OLD" />` in `Directory.Packages.props`. The csprojs need no edit — that is the point of CPM, and adding a `Version=` there is an error (`NU1008`).
+   - **Classic:** iterate the csproj list cached in Step 1 and rewrite every `<PackageReference Include="Spiderly.X" Version="OLD" />`.
+
+   Then rewrite `"spiderly": "OLD"` in `Frontend/package.json`. Don't re-glob.
+
+   **If the app commits `packages.lock.json` files** (`RestorePackagesWithLockFile`), the restore in item 5 updates them — but only for the current OS's resolution graph. Apps whose CI restores in `--locked-mode` on linux must regenerate the locks under the **linux SDK image**, or a macOS-only regeneration ships a lock that CI rejects. Add it to the manual steps:
+
+   ```bash
+   docker run --rm -v "$PWD:/src" -v <cache-volume>:/root/.nuget/packages -w /src \
+     mcr.microsoft.com/dotnet/sdk:<version> dotnet restore <Solution>.sln --force
+   ```
 3. **Migrate agent guidance off the legacy plugin.** Spiderly's AI-agent guidance now ships *inside* the `spiderly` npm package (projected by `spiderly agent-sync` in item 7 below), replacing the old `spiderly@spiderly` Claude Code plugin. If `.claude/settings.json` contains `extraKnownMarketplaces.spiderly` and/or `enabledPlugins."spiderly@spiderly"`, remove just those keys (leave any other settings intact; delete the file only if it becomes an empty `{}`). No settings file or no spiderly entries → skip.
 4. **Migrate `spiderly.json` → `.spiderly/config.json`.** Recent Spiderly moved the generator/api config out of a root `spiderly.json` into `.spiderly/config.json`. If the app has a `spiderly.json` registered via `<AdditionalFiles Include="spiderly.json" />`, `git mv` it to `.spiderly/config.json` and rewrite that csproj line to `<AdditionalFiles Include=".spiderly/config.json" />`. No `spiderly.json` → skip.
 5. **Restore packages in parallel.** Same message, two Bash calls: `dotnet restore` in Backend and `npm install` in Frontend. They share no locks. If either fails, surface the actual error and exit.

package/fesm2022/spiderly.mjs

@@ -3151,7 +3151,27 @@ class InitTopBarData extends BaseEntity {
     static { this.typeName = 'InitTopBarData'; }
 }
 
+/** Parses a JSON entry from web storage; missing or corrupted entries read as null. */
+function readStoredJson(storage, key) {
+    try {
+        return JSON.parse(storage.getItem(key) ?? 'null');
+    }
+    catch {
+        return null;
+    }
+}
+/** Writes a value to web storage as JSON; the counterpart of readStoredJson. */
+function writeStoredJson(storage, key, value) {
+    storage.setItem(key, JSON.stringify(value));
+}
+
 class LayoutServiceBase {
+    /**
+     * Only the desktop collapse persists across reloads (a durable preference,
+     * like the data table's column layout); the rest of LayoutState is
+     * deliberately transient.
+     */
+    static { this.menuDesktopInactiveKey = 'spiderly-layout:menu-desktop-inactive'; }
     constructor(apiService, config, authService) {
         this.apiService = apiService;
         this.config = config;
@@ -3163,7 +3183,8 @@ class LayoutServiceBase {
             colorScheme: 'light',
         };
         this.state = {
-            staticMenuDesktopInactive: false,
+            staticMenuDesktopInactive: readStoredJson(localStorage, LayoutServiceBase.menuDesktopInactiveKey) ===
+                true,
             overlayMenuActive: false,
             profileSidebarVisible: false,
             profileDropdownSidebarVisible: false,
@@ -3200,6 +3221,7 @@ class LayoutServiceBase {
         if (this.isDesktop()) {
             this.state.staticMenuDesktopInactive =
                 !this.state.staticMenuDesktopInactive;
+            writeStoredJson(localStorage, LayoutServiceBase.menuDesktopInactiveKey, this.state.staticMenuDesktopInactive);
         }
         else {
             this.state.staticMenuMobileActive = !this.state.staticMenuMobileActive;
@@ -4179,23 +4201,14 @@ class SpiderlyDataTableComponent {
             localStorage.removeItem(this.columnsStateKey);
         }
         else {
-            localStorage.setItem(this.columnsStateKey, JSON.stringify(this.columnVisibilityOverrides));
+            writeStoredJson(localStorage, this.columnsStateKey, this.columnVisibilityOverrides);
         }
     }
     restoreColumnVisibility() {
         if (!this.columnsStateKey)
             return;
         this.columnVisibilityOverrides =
-            SpiderlyDataTableComponent.readStoredJson(localStorage, this.columnsStateKey) ?? {};
-    }
-    /** Parses a JSON entry from web storage; missing or corrupted entries read as null. */
-    static readStoredJson(storage, key) {
-        try {
-            return JSON.parse(storage.getItem(key) ?? 'null');
-        }
-        catch {
-            return null;
-        }
+            readStoredJson(localStorage, this.columnsStateKey) ?? {};
     }
     /**
      * PrimeNG's persisted table state (filters/sort/pagination), read directly from storage
@@ -4204,7 +4217,7 @@ class SpiderlyDataTableComponent {
     persistedTableState() {
         if (!this.resolvedStateKey)
             return null;
-        return SpiderlyDataTableComponent.readStoredJson(this.stateStorage === 'local' ? localStorage : sessionStorage, this.resolvedStateKey);
+        return readStoredJson(this.stateStorage === 'local' ? localStorage : sessionStorage, this.resolvedStateKey);
     }
     /**
      * Guards the "hidden contributes nothing" invariant against state this component didn't
@@ -5421,6 +5434,8 @@ const unauthorizedInterceptor = (req, next) => {
         if (!config.production) {
             console.error(err);
         }
+        // TODO: type this as an ApiError interface (TS mirror of ApiErrorDTO, next to errors/api-error-codes.ts)
+        // so message/errorCode/traceId reads of the cross-language contract are compile-checked, not conventional.
         let errorResponse = err.error;
         if (request.responseType !== 'json' && typeof err.error === 'string') {
             try {
@@ -5430,31 +5445,36 @@ const unauthorizedInterceptor = (req, next) => {
                 errorResponse = null;
             }
         }
+        // ApiErrorDTO.traceId is present only on reportable errors, so this is a no-op everywhere else —
+        // the server decides which responses carry a support reference, never this status-code chain.
+        const withReference = (detail) => errorResponse?.traceId
+            ? `${detail} ${translocoService.translate('ErrorReference', { traceId: errorResponse.traceId })}`
+            : detail;
         if (err.status === 0) {
             // Server unreachable; defer so the message isn't lost during a shutdown/refresh race.
             setTimeout(() => {
-                messageService.warningMessage(translocoService.translate('ServerLostConnectionDetails'), translocoService.translate('ServerLostConnectionTitle'));
+                messageService.warningMessage(withReference(translocoService.translate('ServerLostConnectionDetails')), translocoService.translate('ServerLostConnectionTitle'));
             }, 100);
         }
         else if (err.status === 400) {
-            messageService.warningMessage(errorResponse?.message ?? translocoService.translate('BadRequestDetails'), translocoService.translate('Warning'));
+            messageService.warningMessage(withReference(errorResponse?.message ?? translocoService.translate('BadRequestDetails')), translocoService.translate('Warning'));
         }
         else if (err.status === 401) {
             if (errorResponse?.errorCode === ApiErrorCodes.InvalidToken) {
                 authService.clearSession(); // expired/invalid session — drop it; guards send the user to login
             }
             else {
-                messageService.warningMessage(errorResponse?.message ?? translocoService.translate('LoginRequired'), translocoService.translate('Warning'));
+                messageService.warningMessage(withReference(errorResponse?.message ?? translocoService.translate('LoginRequired')), translocoService.translate('Warning'));
             }
         }
         else if (err.status === 403) {
-            messageService.warningMessage(translocoService.translate('PermissionErrorDetails'), translocoService.translate('PermissionErrorTitle'));
+            messageService.warningMessage(withReference(translocoService.translate('PermissionErrorDetails')), translocoService.translate('PermissionErrorTitle'));
         }
         else if (err.status === 404) {
-            messageService.warningMessage(translocoService.translate('NotFoundDetails'), translocoService.translate('NotFoundTitle'));
+            messageService.warningMessage(withReference(translocoService.translate('NotFoundDetails')), translocoService.translate('NotFoundTitle'));
         }
         else {
-            messageService.errorMessage(translocoService.translate('UnexpectedErrorDetails'), translocoService.translate('UnexpectedErrorTitle'));
+            messageService.errorMessage(withReference(translocoService.translate('UnexpectedErrorDetails')), translocoService.translate('UnexpectedErrorTitle'));
         }
     };
     return next(req).pipe(catchError((err) => {