@smartsoft001-mobilems/claude-plugins 2.87.0 → 2.88.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartsoft001-mobilems/claude-plugins",
-  "version": "2.87.0",
+  "version": "2.88.0",
   "publishConfig": {
     "access": "public"
   },

package/plugins/mobilems/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "mobilems",
   "description": "MobilEMS-specific Claude Code skills (MuzaCMS / MobileMS indexer API)",
-  "version": "2.87.0"
+  "version": "2.88.0"
 }

package/plugins/mobilems/skills/mobilems-articles/SKILL.md

@@ -75,6 +75,30 @@ and the reference repo path (same one init used).
    library exists, the `forFeature` carries the chosen `entity` (and template, if given), the route is
    registered, and the article card shared components are built and exported. Fix and re-run.
 
+## Known QA pitfalls (from live deployments — fix while copying, not after)
+
+Each of these was a real Linear bug on a museum project built with this skill (Ostrowiec MOB-962,
+Tomaszów MOB-957/993). The cross-cutting rules live in `mobilems-project-init`
+`references/qa-hardening.md`; these are the article-module-specific ones:
+
+- **Author filter dictionary key is lowercase `authors`.** `dictionaryKey="authors"` routes to
+  `api/article/authors/...`; `"Author"` silently falls through to `api/dictionary/Author/...` →
+  HTTP 409 and an empty options list (one-character bug that shipped to QA).
+- **alt from CMS titles must strip HTML.** The detail header image shipped with
+  `alt="<p>Tytuł</p>"` — pipe the title through `smartRemoveHtml` before binding it to `alt`.
+- **Detail page structure:** an `h1` (article title — copied reference had only `h2`), breadcrumbs
+  (`/ Artykuły / {tytuł}`), and gallery image captions rendered as text, NOT `h3` (an `h1 → h3`
+  jump is a recurring axe-core finding).
+- **List item field order per mockup:** date ABOVE the title (implementations kept shipping it at
+  the bottom), keywords as inline links styled per the design, and mockup-exact sort labels
+  ("Sortowanie: Od najnowszych", not "Sortuj: Data publikacji - od najnowszych").
+- **List spacing:** in list view the items need a real gap (`gap-4` fixed the "too close together"
+  QA bug).
+- **Search debounce 250 ms** (`@debounce(250)`), total count + shared `NextPageComponent` on the
+  list — consistent with objects/collections.
+- **Warning-clean templates:** remove needless `?.` on non-nullable signals (NG8107) and unused
+  `@let` declarations (NG8112) after copying.
+
 ## Notes
 
 - One run builds one named article module. Run the skill again — with a different name + template — for

package/plugins/mobilems/skills/mobilems-object-collections/SKILL.md

@@ -45,6 +45,31 @@ run `/mobilems:project-init` first. Hold `<PREFIX>` (from `tsconfig.base.json`;
    (top-level + search child), the `collections-grid-item` component is built and exported, and the
    three public-collections deps are present. Fix and re-run.
 
+## Known QA pitfalls (from live deployments — fix while copying, not after)
+
+Each of these was a real Linear bug on a museum project built with this skill (Ostrowiec MOB-961/994,
+Tomaszów MOB-956). The cross-cutting rules live in `mobilems-project-init`
+`references/qa-hardening.md`; these are the collections-specific ones:
+
+- **One card component, reused everywhere.** The home page and the collection detail must render the
+  SAME shared `collections-grid-item` / object card components as the list views — a second ad-hoc
+  card on the home page was a High-priority bug (MOB-994). Never fork a card per page.
+- **No hardcoded UI strings.** The detail heading was shipped as a literal `Zbiory {{ title }}` and
+  stayed Polish in EN — every static label goes through a translation key (PL + EN in
+  `translations.json`). The list page needs a VISIBLE translated heading (not only `sr-only`), and
+  exactly one `h1` per page.
+- **Card image fallback:** when a collection thumbnail fails to load, show the app's `no-image`
+  placeholder instead of a broken image.
+- **Hover:** underline the card **title** on hover (not the "Zobacz więcej" link) — same pattern as
+  objects.
+- **Search debounce 250 ms** in the filters (`@debounce(250)`), total count + shared
+  `NextPageComponent` on the list — consistent with objects/news.
+- **Keyword/cycle chips wrap on 360 px** — chips caused page-level horizontal scroll on mobile.
+- **Heading font must cover Polish diacritics** — collection card titles rendered in a fallback
+  font because the configured serif (Bacasime Antique) lacks `ą ć ę ł ń ś ź ż`; verify the Tailwind
+  heading `fontFamily` is non-empty and latin-ext complete (see qa-hardening).
+- **Warning-clean templates:** remove needless `?.` on non-nullable signals (NG8107) after copying.
+
 ## Notes
 
 - This skill builds only the collections module + its shared component + its route. It never adds

package/plugins/mobilems/skills/mobilems-objects/SKILL.md

@@ -45,6 +45,34 @@ run `/mobilems:project-init` first. Hold `<PREFIX>` (from `tsconfig.base.json`;
    and exported, the widget map registers the object gallery widget, and `ISpecificObject` is present.
    Fix and re-run.
 
+## Known QA pitfalls (from live deployments — fix while copying, not after)
+
+Each of these was a real Linear bug on a museum project built with this skill (Ostrowiec MOB-960/991,
+Tomaszów MOB-949/993). The cross-cutting rules live in `mobilems-project-init`
+`references/qa-hardening.md`; these are the objects-specific ones:
+
+- **Search debounce.** The panel full-text search (`app-objects-searchbar variant="panel"`) must
+  re-emit through a handler with `@debounce(250)` (`lodash-decorators`) — without it every keystroke
+  hits the API. Collections and news filters already do this; keep the modules consistent.
+- **List page:** show the total result count (`facade.totalCount()`) and add the shared
+  `NextPageComponent` at the bottom (same `selectedPage`/`lastPageIndex` pattern as the news list).
+- **Map tab coordinates.** Read coordinates through ONE helper (`getObjectCoordinates()`) used by
+  both the tab-visibility predicate and the map render: `archeoMap.latitude/longitude` first, then
+  fall back to the first valid `createPlaces[]` entry; accept **both `lon` and `long`** (upstream
+  `MsObjectPlace` says `long`, the real API sends `lon`); validate with `Number.isFinite` (lat `0`
+  is valid; `Number('') === 0` — reject empty strings explicitly). Duplicating the predicate in two
+  components caused a "map never renders" bug.
+- **Field labels match the client's field spec everywhere** — list card, detail and filters must use
+  the same names (QA rejected "Materiał" vs "Tworzywo", "Miejsca:" vs "Miejsce powstania").
+- **Keywords section** maps the API `tags[]` field (not `keywords[]`) and renders clickable links
+  that filter the list.
+- **Warning-clean templates:** after copying, remove needless `?.` on non-nullable signals (NG8107)
+  and drop unused entries from `imports: []` (NG8113 — the tab container often imports
+  Model3d/Map/VirtualWalk tabs its template no longer references). Masonry grid items must not set
+  `width` after change detection (NG0100).
+- **A11y:** exactly one `h1` (detail = object title); cards exposed as `role="link"` must activate
+  on Enter/Space; focused/hovered cards change label colours together with the rest of the content.
+
 ## Notes
 
 - This skill builds only the objects module + its shared components + its route. It never adds other

package/plugins/mobilems/skills/mobilems-project-init/SKILL.md

@@ -100,16 +100,33 @@ the static pages (`home`, `page`, `contact`, `search`, `not-found`) + their reso
 catch-all). Each module skill adds its own feature route to the `appRoutes` array when it runs
 (`article-preview` is articles-coupled — `mobilems-articles` adds it, not the foundation).
 
-### 9. .claude extension
+### 9. QA hardening — SEO, i18n, WCAG, branding
+
+Apply `references/qa-hardening.md` — a checklist distilled from real QA bug reports on live museum
+deployments. The copied foundation carries the _reference museum's_ identity, so this step removes
+leftovers and closes the recurring gaps QA always finds:
+
+- dynamic `/sitemap.xml` + `/robots.txt` SSR endpoints driven by `SITE_URL` (never static copies —
+  they shipped another museum's domain twice),
+- og/twitter images + URLs on the target domain, favicon set, skip links rewritten for this app,
+- meta description + OpenGraph on home in both languages; `og:locale` follows the active language,
+- default language = Polish, `<html lang>` synced on switch, zero hardcoded UI strings,
+- WCAG: one `h1`, no skipped heading levels, contrast ≥4.5:1 (reference greys fail), heading font
+  with full Polish diacritics,
+- warning-clean build & console (NG8107/NG8112/NG8113/NG0100/NG0913, Swiper loop, duplicate API
+  calls).
+
+### 10. .claude extension
 
 Apply `references/claude-config.md`: add `flow@mobilems` to `enabledPlugins`, grow the
 MobilEMS-specific permissions / MCP allow-lists, and seed `tools/specs` + `tools/prompts` pointers.
 
-### 10. Verify
+### 11. Verify
 
 Run `scripts/verify-init.sh <workspace-root> <PREFIX>`. It asserts the delta landed (Tailwind,
-multimediaUrl, MobilEMS providers, populated shared-lib barrel) AND the foundation is self-contained
-(no `libs/museum-*`, no feature routes, and the build-safety invariant — no file under
+multimediaUrl, MobilEMS providers, populated shared-lib barrel), the QA-hardening basics (sitemap +
+robots endpoints, favicon, non-empty heading font), AND the foundation is self-contained (no
+`libs/museum-*`, no feature routes, and the build-safety invariant — no file under
 `libs/shared/angular/src` imports a feature package). Fix and re-run until it passes. Gate
 `npm install` behind an explicit ask — skip it during self-validation/eval.
 

package/plugins/mobilems/skills/mobilems-project-init/references/app-shell.md

@@ -10,7 +10,11 @@ Copy verbatim and thread `<PREFIX>`. The root component imports the `COMPONENTS`
 `SkipLinksComponent` from `@<PREFIX>/angular`, injects `ConfigsFacade` + `SeoService` (from
 `@smartsoft001-mobilems/angular`), `LocalStorageService` (shared lib) and `Router`; it inits the
 language, loads the global `Config` in `ngOnInit`, and focuses `#skip-links` on each `NavigationEnd`.
-`app.html`:
+
+> **QA gotcha (skip links):** the copied skip-link labels/targets describe the _reference_ museum's
+> sections — a project shipped skip links that still said "Światowid". Rewrite them for this app's
+> actual sections and localize them (PL/EN keys). See `references/qa-hardening.md` §1.
+> `app.html`:
 
 ```html
 <app-skip-links></app-skip-links>
@@ -29,7 +33,11 @@ Copy `pages/{home,page,contact,search,not-found}` + the `home` and `page` resolv
   `NewsCarouselComponent`, `PartnersCarouselComponent`) and the `IObject`/`IArticle`/`IPartner` types
   from the shared `models/` dir, plus the `DataService` home loaders — all foundation code (see
   `references/shared-lib.md`). The home page renders fully; its carousels populate from the API at
-  runtime.
+  runtime. **QA gotchas:** home sections must reuse the SAME shared card components as the module
+  list pages (an ad-hoc home card was a High bug); Swiper `loop` only when there are enough slides
+  for `slidesPerView` (else a console warning on every load); don't fire the same home API call
+  multiple times on load (`object-of-the-week` went out 3× — share/replay it). See
+  `references/qa-hardening.md` §6–7.
 - `search.component` renders results through a `<router-outlet>`; it has no feature import.
 
 Run a feature-package grep over the pages you copy as a guard. **Do not copy `article-preview`** — the

package/plugins/mobilems/skills/mobilems-project-init/references/qa-hardening.md

@@ -0,0 +1,124 @@
+# QA hardening — lessons from live museum deployments
+
+Every item below is a **real defect reported in QA on production museum projects** (Linear: Muzeum
+Ostrowiec MOB-938…MOB-995, Muzeum Tomaszów Lubelski MOB-948…MOB-996). The foundation is copied from
+a reference repo, so the default failure mode is **reference-project leftovers** plus a handful of
+recurring SEO/i18n/WCAG gaps. Work through this checklist when applying the delta — each item is
+cheap to do during init and expensive to chase later in QA.
+
+## 1. No reference-project leftovers (branding)
+
+The reference repo belongs to a _different museum_. Everything carrying that museum's identity must
+be replaced or generated for the target project:
+
+- **`sitemap.xml` + `robots.txt`** — never copy static files (QA found `zbiory.muzeum-orkana.pl`
+  URLs shipped to another museum). Implement them as **dynamic SSR endpoints** driven by the
+  `SITE_URL` env var — see section 2.
+- **`og:image` / `og:image:secure_url` / `twitter:image` / `og:url`** — must point at the target
+  museum's domain, not the reference deploy (QA found `mobilems-muzeum-swiatowid-qa.smartsoft.biz.pl/gfx/social-logo.jpg`).
+  Use `SITE_URL`/`siteUrl` to build absolute URLs; ship a local `gfx/social-logo.jpg` for this app.
+- **Favicon** — the base often has none. Ship the full set: `favicon.ico`, 32×32 + 192×192 PNG,
+  `apple-touch-icon` (two projects opened QA bugs "Brak ikony").
+- **Skip links** — keep them (they are required), but rewrite their labels/targets for THIS app's
+  sections; copied skip links still said "Światowid". Localize them (PL/EN translation keys).
+- **Footer / contact data** — target museum's phone, e-mail, socials; links come from the CMS API,
+  not hardcode.
+- Local static assets (funding logos etc.) must be served near their rendered size — oversized
+  copies trigger Angular `NG0913` warnings and hurt LCP.
+
+## 2. Dynamic sitemap + robots endpoints (server.ts)
+
+Pattern proven in MOB-948 — put the logic in **pure, testable functions** in
+`apps/web/src/seo/seo-endpoints.ts` (`resolveSiteUrl`, `buildSitemapXml`, `buildRobotsTxt`), and
+wire thin routes in `server.ts`:
+
+- Register `GET /sitemap.xml` and `GET /robots.txt` **after** `/api/translations` but **before**
+  `express.static` and the `'/**'` SSR catch-all — otherwise SSR answers with HTML and status 200
+  and the endpoints "work" only apparently.
+- Normalize `SITE_URL`: strip trailing `/`, prepend `https://` when the schema is missing; fall back
+  to the request host when the env var is unset.
+- Headers: `application/xml; charset=utf-8` / `text/plain; charset=utf-8`,
+  `Cache-Control: public, max-age=3600`.
+- Sitemap content: home + the module list pages (`/strona-glowna`, `/obiekty`, `/kolekcje`, …). Do
+  **not** include CMS static pages (`/strona/:id`) — their ids are CMS-assigned and go stale.
+- `robots.txt` points `Sitemap:` at the same `SITE_URL`.
+
+## 3. SEO meta (home + every routed page)
+
+- `<meta name="description">` + complete OpenGraph (`og:title`, `og:description`, `og:image`,
+  `og:url`) + Twitter Card on the home page, in **both** languages, re-set on language switch.
+- `og:locale` must follow the active language — a hardcoded `pl_PL` was a QA bug. In
+  `museum-seo.service.ts` use a locale map (`pl → pl_PL`, `en → en_GB`) read from
+  `translateService.currentLang` (fallback via `defaultLang` — `currentLang` can be `undefined`
+  during SSR), and emit one `og:locale:alternate`.
+
+## 4. i18n invariants
+
+- **Default language is Polish.** A Polish museum site rendering English on first visit while
+  `<html lang="pl">` is a WCAG 3.1.1 violation and was a reported bug.
+- `<html lang>` must track the actually rendered language after every switch; `<title>`, meta
+  description and `og:title` retranslate with it.
+- **No hardcoded UI strings in templates.** QA repeatedly caught literals like `Zbiory {{ title }}`
+  untranslated in EN. Every static label goes through a translation key with both PL and EN values
+  in `translations.json`.
+- Dictionary keys for filter dictionaries are **lowercase** conventions of the framework:
+  `dictionaryKey="authors"` routes to `api/article/authors/...`; `"Author"` silently falls through
+  to `api/dictionary/Author/...` → HTTP 409 and an empty options list.
+
+## 5. WCAG invariants
+
+- **Contrast:** the reference grey `#9ca3af` on white is 2.53:1 — fails AA and was flagged on menus
+  and breadcrumbs in two projects. Use ≥4.5:1 for text: `#6f6f6f` ≈ 5.0:1, `#4b5563` ≈ 7.6:1.
+  Figma mockups themselves sometimes specify failing colours — match the design _intent_ with the
+  nearest compliant shade instead of copying the hex blindly, and note the deviation.
+- **Headings:** exactly one `h1` per page; no skipped levels (an `h1 → h3` jump was a recurring
+  axe-core finding). Detail pages get an `h1` (the item title), image captions are NOT headings.
+- **alt text:** when the alt comes from a CMS title, strip HTML first (`smartRemoveHtml`) —
+  `alt="<p>Tytuł</p>"` shipped to QA.
+- **Keyboard:** any card implemented as `role="link"`/`tabindex=0` must activate on Enter/Space
+  (or better, be a real `<a href>`). Focus must be visible; labels should react to focus/hover the
+  same way the rest of the card content does.
+- **Fonts must cover Polish diacritics.** Bacasime Antique, Prata and Italiana lack 16/18 of
+  `ą ć ę ł ń ś ź ż` (+ uppercase) — titles rendered in a fallback font and QA rejected it. Verified
+  full-latin-ext replacements: **Gilda Display** (closest to Bacasime) or **Playfair Display**.
+  Never leave a `tailwind.config.js` `fontFamily` entry as an empty array — it silently falls back
+  to system sans.
+
+## 6. Console hygiene (build + runtime must be warning-clean)
+
+QA files bugs for compiler warnings, so treat them as errors after copying code:
+
+- `NG8107` — remove `?.` on receivers whose type excludes null/undefined (typical after copying
+  templates: `list()?.length`, `filter()?.searchText`).
+- `NG8112` — remove unused `@let` declarations.
+- `NG8113` — remove components from `imports: []` that the template doesn't use (copied tab
+  containers often import Model3d/Map/VirtualWalk tabs conditionally rendered away).
+- `NG0100` (`ExpressionChangedAfterItHasBeenCheckedError`) — masonry/grid items must not set their
+  `width` binding after change detection completes.
+- **Never log API payloads to the console** — QA flagged leaked responses.
+- Swiper: enable `loop` only when there are enough slides for the configured
+  `slidesPerView`/`slidesPerGroup`, otherwise Swiper logs a loop warning on every load.
+- Avoid duplicate API calls on page load (home fired `object-of-the-week` 3×) — share/replay the
+  request in the service.
+
+## 7. Cross-module UI consistency
+
+These conventions were enforced by QA across modules — bake them in from the start:
+
+- **One card component per entity, reused everywhere.** The home page, module lists and search
+  results must render the same shared `*-grid-item` / `*-list-item` components — a second ad-hoc
+  card implementation on the home page was a High-priority bug (MOB-994).
+- **Full-text search inputs debounce 250 ms** (`@debounce(250)` from `lodash-decorators`) — in every
+  module's filters (objects, collections, articles/news).
+- **Every list page shows the total result count** (`facade.totalCount()`), independent of
+  pagination (MOB-995/996).
+- **"Next page" button** at the bottom of each list follows one shared pattern
+  (`NextPageComponent`: `selectedPage`/`lastPageIndex` from `totalCount()` + limit, scroll-to-top on
+  advance, hidden on the last page).
+- **Breadcrumbs:** everything except the active (last) item greyed — separators `#8e8e8e`,
+  intermediate links a WCAG-compliant grey (`#4b5563`/`#6f6f6f`), active item dark/semibold.
+- **Card hover:** underline the card **title** only (not the "Zobacz więcej" link) — pattern
+  aligned across objects/collections.
+- **Image fallback:** cards show the app's `no-image` placeholder when a thumbnail fails to load.
+- Keyword/tag chips must wrap on 360 px wide screens — no page-level horizontal scroll at
+  360/768/1024/1440.

package/plugins/mobilems/skills/mobilems-project-init/references/server-env.md

@@ -87,3 +87,11 @@ app.get('/api/translations', (req, res) => {
 The `app.config.ts` `provideAppInitializer` hits `/api/translations` in dev and `apiUrl + 'setting/theme'`
 in prod (see `references/config-providers.md`). Optionally seed an empty
 `apps/web/public/translations.json` (`{"en":{},"pl":{}}`) so dev SSR doesn't 404.
+
+## 4. `/sitemap.xml` + `/robots.txt` — dynamic endpoints (required)
+
+Never ship static `sitemap.xml`/`robots.txt` copied from the reference — two projects went to QA
+with another museum's domain in them. Build them as SSR endpoints from `SITE_URL`, with the logic in
+pure functions (`apps/web/src/seo/seo-endpoints.ts`) and thin routes in `server.ts`, registered
+after `/api/translations` and **before** `express.static` + the `'/**'` catch-all. Full pattern
+(normalization, headers, content rules): `references/qa-hardening.md` §2.

package/plugins/mobilems/skills/mobilems-project-init/references/tailwind-styles.md

@@ -62,6 +62,12 @@ module.exports = {
 > The `content` globs already cover `libs/**`, so feature libs added later are picked up — no edit
 > needed when modules arrive. `darkMode` keys off `contrast-high` for the WCAG high-contrast toggle.
 
+> **QA gotcha (fonts):** when the project's design swaps in its own heading font, verify it covers
+> Polish diacritics (`ą ć ę ł ń ś ź ż` + uppercase). Bacasime Antique, Prata and Italiana lack them
+> — titles silently render in a fallback font and QA rejects it (verified replacements: Gilda
+> Display, Playfair Display). Never leave a `fontFamily` entry as an empty array — it falls back to
+> system sans. See `references/qa-hardening.md` §5.
+
 ## 2. postcss
 
 Add Tailwind + autoprefixer to postcss. If the base has a `postcss.config.js`/`.json`, add the

package/plugins/mobilems/skills/mobilems-project-init/scripts/verify-init.sh

@@ -24,6 +24,14 @@ grep -q "SharedModule.forRoot" apps/web/src/app/app.config.ts && pass "SharedMod
 grep -q "SEARCH_CONFIG_TOKEN" apps/web/src/app/app.config.ts && pass "SEARCH_CONFIG_TOKEN" || bad "SEARCH_CONFIG_TOKEN in app.config.ts"
 grep -q "multimediaUrl" apps/web/src/server.ts && pass "multimediaUrl in server.ts" || bad "multimediaUrl in server.ts"
 grep -q "/api/translations" apps/web/src/server.ts && pass "/api/translations endpoint" || bad "/api/translations in server.ts"
+
+echo "== QA hardening (references/qa-hardening.md) =="
+# dynamic sitemap/robots endpoints (static copies shipped another museum's domain in past projects)
+grep -q "sitemap.xml" apps/web/src/server.ts && pass "dynamic /sitemap.xml endpoint" || bad "/sitemap.xml endpoint in server.ts (SITE_URL-driven, never a static copy)"
+grep -q "robots.txt" apps/web/src/server.ts && pass "dynamic /robots.txt endpoint" || bad "/robots.txt endpoint in server.ts (SITE_URL-driven, never a static copy)"
+if ls apps/web/public/favicon.ico apps/web/src/favicon.ico >/dev/null 2>&1; then pass "favicon present"; else bad "favicon.ico missing (QA bug 'Brak ikony' in two projects)"; fi
+# an empty fontFamily array silently falls back to system sans (QA-rejected typography)
+if grep -qE ":\s*\[\s*\]" tailwind.config.js 2>/dev/null; then bad "empty fontFamily array in tailwind.config.js (heading font falls back to system sans)"; else pass "no empty fontFamily entries"; fi
 grep -q "./lib/components" libs/shared/angular/src/index.ts && pass "shared-lib components barrel populated" || bad "components barrel in shared-lib index.ts"
 [ -f .claude/settings.json ] && grep -q "flow@mobilems" .claude/settings.json && pass "flow@mobilems enabled" || bad "flow@mobilems in .claude/settings.json"