spiderly 19.13.0 → 19.15.0

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

@@ -274,6 +274,23 @@ The table renders the store as a **chip bar** above the header: one chip per *ap
 this.views = this.views.map((view) => ({ ...view, count: counts[view.id] }));
 ```
 
+**A count can honor each view's saved filters**: the table's `viewFilterPayload(viewId)` returns the `filters` payload that view's own list request carries, so a count query that applies it counts the rows that tab lists (on screen for the active view, after a click for the others), including bar filters the user saved on that view. The active view answers with the live filters; any other view with what a click would enter: its saved filters, else its `apply` (always `apply` for a transient view). It switches nothing and sends no request. `apply` runs on a scratch store for this, so it must write only into the store it receives. It returns `{}` on a table without `[filters]` and `null` for an id not in `[views]` (yet). Call it beside each list load; a non-static `@ViewChild` is still unresolved during the first one, so hand the table in from a template reference:
+
+```html
+<spiderly-data-table #table [views]="views" (onLazyLoad)="refreshCounts(table)" ...></spiderly-data-table>
+```
+
+```typescript
+refreshCounts(table: SpiderlyDataTableComponent): void {
+  const filtersByView: Record<string, Record<string, FilterRule[]>> = {};
+  for (const view of this.views) {
+    const filters = table.viewFilterPayload(view.id);
+    if (filters) filtersByView[view.id] = filters; // null: the table does not hold this view yet
+  }
+  // send filtersByView with your count query, then rebuild [views] with the counts
+}
+```
+
 **A view can declare its columns**: `columns` is a field → visible map that overrides `Column.visible` in that view only, naming just the deviation — a column it does not name keeps its `Column.visible`. Visibility resolves per field as the user's own per-view choice ?? the view's `columns` ?? `Column.visible`; the user's choice is stored only where it differs from the view's declaration, *Reset to default* returns to the declaration, and `lockVisible` columns always show. To swap one column for another, declare them next to each other in `cols` (the swapped-in one `visible: false`) and the view's column takes the other's place. Type the row as the second generic to check the field names.
 
 ```typescript

package/agent/docs/frontend-localization/index.md

@@ -1,33 +1,46 @@
 ---
 name: frontend-localization
-description: How Spiderly localizes Angular admin-panel UI strings — labels, buttons, menu items, validation messages, any user-facing text. Spiderly uses Transloco with flat assets/i18n/{lang}.json files loaded by SpiderlyTranslocoLoader. Use whenever you add or translate a UI string, hit a raw translation key rendering on screen, set up or change languages (provideTransloco / availableLangs), use translocoService.translate or the *transloco template directive, run i18n:extract, or wonder how form labels get auto-translated. For .NET backend strings (error messages, Excel names, IStringLocalizer), use the backend-localization skill instead.
+description: How Spiderly localizes Angular admin-panel UI strings — labels, buttons, menu items, validation messages, any user-facing text. Spiderly uses Transloco with flat assets/i18n/{lang}.json files imported into the build by the app's ImportedTranslocoLoader. Use whenever you add or translate a UI string, hit a raw translation key rendering on screen, set up or change languages (provideTransloco / availableLangs), use translocoService.translate or the *transloco template directive, run i18n:extract, or wonder how form labels get auto-translated. For .NET backend strings (error messages, Excel names, IStringLocalizer), use the backend-localization skill instead.
 ---
 
 # Frontend Localization
 
-The Spiderly Angular admin panel localizes every user-facing string through **Transloco**. Translation files are flat key→value JSON, one per language, served as static assets and loaded over HTTP at runtime — there is no compile-time embedding. Never hardcode user-facing English in a template; route it through a translation key so it localizes with the rest of the panel (e.g. a PACMS app runs entirely in Serbian).
+The Spiderly Angular admin panel localizes every user-facing string through **Transloco**. Translation files are flat key→value JSON, one per language, imported into the build: each becomes a content-hashed chunk that ships with the code reading its keys, loaded when Transloco first needs the language. Never hardcode user-facing English in a template; route it through a translation key so it localizes with the rest of the panel (e.g. a PACMS app runs entirely in Serbian).
 
 This is a **separate system from the backend**: a string shown by the API (a `BusinessException` message) is translated on the .NET side via `IStringLocalizer` (see the **backend-localization** skill); a string rendered by the admin UI is translated here.
 
-## Setup (`app.config.ts`)
+## Setup (`translations.ts`)
 
-Transloco is registered in the app's `ApplicationConfig` with Spiderly's loader:
+`spiderly init` writes the loader and the Transloco config to `src/app/business/services/translations.ts`; `app.config.ts` only calls `provideTranslations()`:
 
 ```typescript
-provideTransloco({
-  config: {
-    availableLangs: ['sr-Latn-RS'],   // every language you ship a JSON file for
-    defaultLang: 'sr-Latn-RS',
-    reRenderOnLangChange: false,       // true only if you let users switch language at runtime
-  },
-  loader: SpiderlyTranslocoLoader,     // from the `spiderly` package
-}),
+@Injectable({ providedIn: 'root' })
+export class ImportedTranslocoLoader implements TranslocoLoader {
+  getTranslation(lang: string): Promise<Translation> {
+    return import(`../../../assets/i18n/${lang}.json`).then((file) => file.default);
+  }
+}
+
+export function provideTranslations() {
+  return provideTransloco({
+    config: {
+      availableLangs: ['en'],          // every language you ship a JSON file for
+      defaultLang: 'en',
+      reRenderOnLangChange: true,      // false if users never switch language at runtime
+    },
+    loader: ImportedTranslocoLoader,
+  });
+}
 ```
 
-`SpiderlyTranslocoLoader` fetches `${ConfigService.frontendUrl}/assets/i18n/{lang}.json`. So:
+So:
 
 - Files live in **`src/assets/i18n/{lang}.json`**, named **exactly** after a `lang` in `availableLangs` (e.g. `sr-Latn-RS.json`, `en.json`).
-- They must be deployed as static assets (they're requested over HTTP, not bundled). They already are under `src/assets`, but a build that drops the `assets/` glob will 404 the translations and every key renders raw.
+- The build bundles them; they are **not** published as `/assets/i18n/*.json`. `angular.json` leaves them out of the assets glob (`"ignore": ["i18n/**"]`), so nothing can fetch them back.
+
+### Why imported, not fetched
+
+A file at an unchanging URL outlives a deploy in the browser cache. A server that sends no `Cache-Control` lets the browser guess a freshness lifetime (Chromium: a tenth of the time since `Last-Modified`), and a hard reload does not help: it bypasses the cache only for requests made before the page's load event, and Transloco asks for the file after it. The user then runs the new code against the old file, and every key added by the deploy renders raw. An imported file gets a new URL whenever its content changes, so this cannot happen. Spiderly's former `SpiderlyTranslocoLoader` fetched `${frontendUrl}/assets/i18n/{lang}.json` and was removed for this reason.
 
 ## File format
 
@@ -111,8 +124,8 @@ If you build a reusable control/component with text baked into its template, rou
 ## Gotchas
 
 - **A missing key renders the raw key.** Transloco's default `missingHandler` returns the key string, so a typo'd or unseeded key leaks the identifier (e.g. `InvalidSKU`) onto the screen instead of erroring. Treat a raw-key sighting as a missing-translation bug. Keep keys in sync across all `{lang}.json` files and lean on `i18n:extract`.
-- **Filename must match `availableLangs`.** `SpiderlyTranslocoLoader` requests `{lang}.json` for the active lang; a mismatch (`sr.json` while `availableLangs` is `['sr-Latn-RS']`) 404s and the whole file falls through to raw keys.
-- **Translations are fetched, not bundled.** They load over HTTP from `frontendUrl/assets/i18n/`. A misconfigured `frontendUrl` (in `ConfigService`) or a build that strips the `assets` glob breaks all translations at once — a useful first thing to check when *everything* shows raw keys.
+- **Filename must match `availableLangs`.** `ImportedTranslocoLoader` imports `{lang}.json` for the active lang; a mismatch (`sr.json` while `availableLangs` is `['sr-Latn-RS']`) fails the import and the whole file falls through to raw keys.
+- **New keys render raw for some users right after a deploy, and a hard reload does not fix it?** Something still fetches the translations from a URL that survives deploys (see *Why imported, not fetched*). Check that `app.config.ts` calls `provideTranslations()` and that the network panel shows no `/assets/i18n/` request.
 - **`reRenderOnLangChange: false`** means a runtime language switch won't re-render already-rendered text. Set it to `true` only if you actually offer in-session language switching.
 
 ## Backend strings are a separate system

package/agent/skills/deployment/SKILL.md

@@ -183,13 +183,16 @@ HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
     root * /srv
     encode zstd gzip
 
-    @hashedAssets {
-        path_regexp hashed \.[a-f0-9]{8,}\.(js|css|woff2?|ttf|otf|svg|png|jpg|jpeg|webp|ico)$
+    # Content-hashed build output (main-QCWZPP5O.js, media/primeicons-4GST5W3O.woff2) that exists
+    # on disk; a missing chunk falls back to index.html and must not be marked immutable.
+    @hashed {
+        path_regexp ^/(media/)?[^/]+-[A-Z0-9]{8}\.[a-z0-9]+$
+        file
     }
-    header @hashedAssets Cache-Control "public, max-age=31536000, immutable"
+    header @hashed Cache-Control "public, max-age=31536000, immutable"
 
-    @indexHtml path /index.html
-    header @indexHtml Cache-Control "no-cache, no-store, must-revalidate"
+    # Everything else (index.html under every route, /assets/*) is revalidated on every use.
+    header ?Cache-Control "no-cache"
 
     try_files {path} /index.html
     file_server
@@ -198,6 +201,8 @@ HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
 
 The `try_files {path} /index.html` line is the SPA fallback that lets the Angular router handle deep links.
 
+Two details in the cache rules matter. Angular's esbuild builder names hashed files `name-HASH.js` (eight uppercase letters and digits), so a `\.[a-f0-9]{8,}\.js` pattern written for the old webpack names matches nothing. And `header` runs before `try_files`, so a `path /index.html` matcher never sees a navigation to `/` or `/orders`: the `?Cache-Control` default covers them. Without any `Cache-Control` a browser guesses a freshness lifetime (Chromium: a tenth of the time since `Last-Modified`) and can open the app from a pre-deploy `index.html`.
+
 **Lockfile gotcha:** `npm ci` requires `package.json` and `package-lock.json` to be in sync. If a stale dev-dep pins an older Angular major as a peer (e.g. `@jsverse/transloco-keys-manager` 5.x pins Angular 17 while your project is on Angular 19), `npm ci` fails. Bump the dev-dep to the matching major (e.g. `transloco-keys-manager` 6.x for Angular 19) rather than reaching for `--legacy-peer-deps`.
 
 ## Terraform layout
@@ -406,7 +411,7 @@ Postgres data lives in a Docker volume on a single VPS — disk failure, acciden
 - **CORS `FrontendUrl`.** The backend's `AppSettings__Spiderly.Shared__FrontendUrl` must point to the admin subdomain, not a build-preview URL. Update it when you cut over from staging hosting.
 - **First deploy ordering.** The backend compose references `${ADMIN_IMAGE}`. On a fresh VPS, that image must exist in GHCR before backend deploys, or the admin service definition fails to pull. Push admin first, or run the admin workflow once before the first backend deploy.
 - **`docker compose up -d` scoping.** Always scope to the services you're updating: `docker compose up -d backend caddy` for backend deploys, `docker compose up -d admin` for admin deploys. Unscoped `up -d` bounces every service that's currently down or has a config change — including admin and postgres on a backend-only commit. The healthcheck-gated `depends_on` makes the unscoped form *safe* but not *desirable*.
-- **Static assets caching.** Hashed Angular bundles (e.g. `main.abc123.js`) can be cached forever; `index.html` must never cache, or users will get a stale shell after a deploy. The Caddyfile in this skill already handles both cases.
+- **Static assets caching.** Hashed Angular bundles (e.g. `main-QCWZPP5O.js`) can be cached forever; `index.html` and every other unhashed file must be revalidated on each use, or users get a stale shell after a deploy. The Caddyfile in this skill handles both, and translations are imported into the build rather than served from `/assets/i18n/` (see the **frontend-localization** doc).
 - **`tls_private_key` lives in Terraform state in cleartext.** R2 encryption-at-rest is bucket-level; anyone with R2 API access (or a leaked state file) can read the key. Scope the R2 token tightly, audit who can pull state, and never copy `terraform.tfstate` to laptops or shared drives. Rotating the cert means a fresh `terraform apply` followed by re-pasting the new outputs into GitHub Secrets — plan a maintenance window. Add `lifecycle { prevent_destroy = true }` to the `tls_private_key` and `cloudflare_origin_ca_certificate` resources so accidental config changes can't trigger a silent rotation. Also add `ignore_changes = [hostnames, csr]` on the cert — Cloudflare normalizes hostname/CSR ordering server-side, otherwise every plan would show a phantom recreate.
 - **Postgres data on Docker named volumes is not durable across server replacement.** If the VPS itself is Terraform-managed (`hcloud_server`) and gets recreated for any reason — image change, server_type change, accidental destroy — the local Docker named volume `postgres_data` goes with it. Add `lifecycle { prevent_destroy = true }` to the `hcloud_server` resource. For genuine durability, attach an `hcloud_volume` and bind-mount it into postgres (`/var/lib/postgresql` on the 18+ image); volumes survive server destruction and snapshot independently.
 - **Cloudflare in front of Vercel must stay "DNS only".** When the Next.js storefront (or a Vercel-hosted admin) deploys to Vercel and DNS is on Cloudflare, those records must be **DNS only** (grey cloud), not proxied. Vercel terminates TLS and runs its own edge — CDN, image optimization, ISR, PPR — so adding the Cloudflare proxy on top breaks the TLS handshake and double-caches/conflicts with Vercel's edge features. Cloudflare's WAF/cache/analytics/Turnstile belong on the **Hetzner-served** records (`api.*`, `admin.*`) where the orange cloud stays on. If you want Cloudflare features in front of Vercel anyway, that's an advanced setup ("Full (strict)" SSL + custom hostnames) that Vercel does not officially recommend.