fix(assets): image CLS/a11y polish and cache hygiene

.github/workflows/ci.yml

@@ -234,6 +234,9 @@ jobs:
       - name: Brand asset check
         run: npm run brand:check
 
+      - name: Asset linting
+        run: npm run check:assets
+
       # More generated-output drift detectors that were local-only in
       # verify:cheap — same rationale as the design-system guards above. Without
       # them a stale site map, therapy index, or design-system contract merged

next.config.ts

@@ -49,12 +49,17 @@ const nextConfig: NextConfig = {
   },
   poweredByHeader: false,
   images: {
+    // Explicit responsive breakpoints for next/image. Leave minimumCacheTTL at
+    // Next's default (60s): a day-long floor can retain optimizer output past
+    // signed-URL lifetimes if a private preview ever omits `unoptimized`.
+    deviceSizes: [640, 750, 828, 1080, 1200, 1920],
+    imageSizes: [32, 48, 64, 96, 128, 256, 384],
     // Prefer AVIF (~20-30% smaller than WebP), falling back to WebP, for any
     // next/image output.
     formats: ["image/avif", "image/webp"],
     // Private signed document/image previews opt out of the optimizer at the
-    // component level (`SignedImage` sets `unoptimized`). Do not rely on
-    // `minimumCacheTTL` as an expiry cap for bearer URLs: it is a lower bound,
+    // component level (`SignedImage` sets `unoptimized`). Do not raise
+    // `minimumCacheTTL` as a "safety" cap for bearer URLs: it is a lower bound,
     // and stale-while-revalidate can keep serving private bytes past the
     // signed-URL lifetime without re-entering the authenticated signed-URL route.
     // Permit optimizing other Supabase Storage URLs through next/image when a

package.json

@@ -48,7 +48,7 @@
     "clean:worktree": "node scripts/clean-worktree.mjs",
     "verify:preflight": "npm run typecheck && npm run verify:cheap && npm run clean:worktree",
     "verify:cheap": "node scripts/run-heavy.mjs --npm-script verify:cheap:internal",
-    "verify:cheap:internal": "npm run check:runtime && npm run check:github-actions && npm run check:ci-scope && npm run check:ci-triage && npm run check:pr-policy && npm run check:gate-manifest && npm run check:branch-review-ledger && npm run sitemap:check && npm run docs:check-index && npm run docs:check-scripts && npm run docs:check-links && npm run check:knip && npm run check:maintainability-budgets && npm run brand:check && npm run check:therapy-data-index && npm run check:type-scale && npm run check:icon-scale && npm run check:design-system-contract && npm run check:migration-role && npm run check:function-grants && npm run check:owner-scope && npm run lint && npm run typecheck && npm run test",
+    "verify:cheap:internal": "npm run check:runtime && npm run check:github-actions && npm run check:ci-scope && npm run check:ci-triage && npm run check:pr-policy && npm run check:gate-manifest && npm run check:branch-review-ledger && npm run sitemap:check && npm run docs:check-index && npm run docs:check-scripts && npm run docs:check-links && npm run check:knip && npm run check:maintainability-budgets && npm run brand:check && npm run check:assets && npm run check:therapy-data-index && npm run check:type-scale && npm run check:icon-scale && npm run check:design-system-contract && npm run check:migration-role && npm run check:function-grants && npm run check:owner-scope && npm run lint && npm run typecheck && npm run test",
     "verify:pr-local": "node scripts/verify-pr-local.mjs",
     "verify:ui": "npm run check:runtime && npm run test:e2e:pr",
     "verify:release": "npm run check:runtime && npm run lint && npm run typecheck && npm run test && npm run build && npm run test:e2e && npm run check:production-readiness && npm run governance:release && npm run eval:quality:release",
@@ -194,7 +194,8 @@
     "check:migration-history": "node scripts/run-tsx.mjs scripts/check-migration-history-alignment.ts",
     "drift:manifest": "node scripts/run-tsx.mjs scripts/generate-drift-manifest.ts",
     "sync:pr-branches": "node scripts/sync-open-pr-branches.mjs",
-    "sync:pr-branches:apply": "node scripts/sync-open-pr-branches.mjs --apply"
+    "sync:pr-branches:apply": "node scripts/sync-open-pr-branches.mjs --apply",
+    "check:assets": "node scripts/check-assets.mjs"
   },
   "dependencies": {
     "@next/env": "16.2.11",

scripts/check-assets.mjs

@@ -0,0 +1,37 @@
+/**
+ * Lightweight asset gate that does not require an `svgo` lockfile delta.
+ *
+ * Full SVGO multipass stability checking is deferred: adding `svgo` flips CI
+ * `lockfile_changed` and makes pre-existing exceljs/brace-expansion audit highs
+ * blocking. Until that lands in a dedicated dependency PR, this gate protects
+ * the highest-value asset contract: `src/app/icon.svg` must keep the
+ * prefers-color-scheme theme swap owned by `brand:check` / `brandIconSvg()`.
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const rootDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+const iconPath = path.join(rootDir, "src", "app", "icon.svg");
+
+async function main() {
+  const icon = await fs.readFile(iconPath, "utf8");
+  const required = ["prefers-color-scheme: dark", "viewBox=", "<style>"];
+
+  const missing = required.filter((token) => !icon.includes(token));
+  if (missing.length > 0) {
+    console.error("src/app/icon.svg is missing themed-favicon markers:");
+    for (const token of missing) {
+      console.error(`  - ${token}`);
+    }
+    console.error("Hint: npm run brand:update  (do not SVGO-multipass this file)");
+    process.exit(1);
+  }
+
+  console.log("check:assets OK — themed favicon markers present (SVGO multipass deferred).");
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exit(1);
+});

src/app/icons/[variant]/route.tsx

@@ -32,6 +32,15 @@ export async function GET(_request: Request, { params }: { params: Promise<{ var
       inset={conf.inset}
       colors={"colors" in conf ? conf.colors : undefined}
     />,
-    { width: conf.size, height: conf.size },
+    {
+      width: conf.size,
+      height: conf.size,
+      // Paths are unversioned (`/icons/icon-192`); do not mark immutable for a
+      // year. Revalidate daily so brand-mark updates propagate without a query
+      // bust (manifest tests forbid `?`/`#` on icon URLs).
+      headers: {
+        "Cache-Control": "public, max-age=86400, stale-while-revalidate=604800",
+      },
+    },
   );
 }

src/components/clinical-dashboard/signed-image.tsx

@@ -98,6 +98,8 @@ export const SignedImage = memo(function SignedImage({
     return (
       <div
         ref={frameRef}
+        role="status"
+        aria-live="polite"
         className={cn(
           className,
           "grid aspect-[4/3] w-full place-items-center rounded-lg border border-[color:var(--warning)]/30 bg-[color:var(--warning-soft)] p-4 text-center text-xs font-semibold text-[color:var(--warning)]",
@@ -141,6 +143,9 @@ export const SignedImage = memo(function SignedImage({
         // `unoptimized` so bearer URLs never enter the unauthenticated
         // `/_next/image` optimizer cache (stale-while-revalidate can outlive the
         // signed token). Authorization stays on `/api/.../signed-url` issuance.
+        // Do not append Storage transform query params here: createSignedUrl()
+        // returns object/sign URLs, and client-side width/height/resize mutation
+        // is a silent no-op (or can invalidate the token) without render/image.
         <Image
           src={url}
           alt={alt}

src/components/document-viewer/non-pdf-source-preview.tsx

@@ -108,7 +108,7 @@ function InlineImagePreview({
 
   if (failed) {
     return (
-      <div className={placeholderSurface}>
+      <div className={placeholderSurface} role="status" aria-live="polite">
         <div className="max-w-md">
           <CircleAlert aria-hidden="true" className="mx-auto mb-2 h-8 w-8 text-[color:var(--warning)]" />
           <p className="font-semibold text-[color:var(--text)]">Image preview could not load</p>
@@ -138,14 +138,16 @@ function InlineImagePreview({
 
   return (
     <div className="flex flex-col items-center gap-3 bg-[color:var(--surface-inset)] p-3 sm:p-4">
-      <img
-        src={signedUrl}
-        alt={title}
-        loading="lazy"
-        decoding="async"
-        onError={() => setFailed(true)}
-        className="max-h-[70vh] w-auto max-w-full rounded-lg bg-[color:var(--surface)] object-contain shadow-[var(--shadow-tight)]"
-      />
+      <div className="relative w-full aspect-[4/3] overflow-hidden rounded-lg bg-[color:var(--surface)] shadow-[var(--shadow-tight)]">
+        <img
+          src={signedUrl}
+          alt={title}
+          loading="lazy"
+          decoding="async"
+          onError={() => setFailed(true)}
+          className="absolute inset-0 h-full w-full object-contain"
+        />
+      </div>
       <a href={signedUrl} target="_blank" rel="noreferrer" className={secondaryButton}>
         <ExternalLink aria-hidden="true" className="h-4 w-4" />
         Open full image

tests/pwa-manifest.test.ts

@@ -109,4 +109,20 @@ describe("PWA manifest and public bootstrap resources", () => {
     expect(nextConfig).toContain('source: "/offline.html"');
     expect(nextConfig).toContain('{ key: "X-Robots-Tag", value: "noindex, nofollow" }');
   });
+
+  it("keeps unversioned PWA icon routes revalidatable and avoids a day-long image TTL floor", () => {
+    const iconsRoute = readFileSync(join(process.cwd(), "src/app/icons/[variant]/route.tsx"), "utf8");
+    const nextConfig = readFileSync(join(process.cwd(), "next.config.ts"), "utf8");
+
+    expect(iconsRoute).toContain("public, max-age=86400, stale-while-revalidate=604800");
+    expect(iconsRoute).not.toMatch(/max-age=31536000,\s*immutable/);
+    expect(nextConfig).not.toMatch(/minimumCacheTTL:\s*86400/);
+  });
+
+  it("keeps the themed favicon markers that check:assets guards without SVGO", () => {
+    const icon = readFileSync(join(process.cwd(), "src/app/icon.svg"), "utf8");
+    expect(icon).toContain("prefers-color-scheme: dark");
+    expect(icon).toContain("<style>");
+    expect(icon).toContain("viewBox=");
+  });
 });

tests/signed-image.dom.test.tsx

@@ -42,8 +42,9 @@ describe("SignedImage failure/retry (jsdom)", () => {
       <SignedImage endpoint={ENDPOINT} alt="Airway diagram" failureLabel="Image preview failed." retryLabel="Retry" />,
     );
 
-    // The first fetch fails → failure state with a retry action.
+    // The first fetch fails → polite status region with a retry action.
     expect(await screen.findByText("Image preview failed.")).toBeInTheDocument();
+    expect(screen.getByRole("status")).toHaveAttribute("aria-live", "polite");
     const retry = screen.getByRole("button", { name: "Retry" });
     expect(fetchMock).toHaveBeenCalledTimes(1);
 
@@ -97,4 +98,23 @@ describe("SignedImage failure/retry (jsdom)", () => {
     expect(frame).toHaveStyle({ aspectRatio: "4.2" });
     expect(frame?.className).not.toContain("aspect-[4/3]");
   });
+
+  it("does not append Storage transform query params onto issued signed URLs", async () => {
+    const signedUrl = "https://example.supabase.co/storage/v1/object/sign/images/demo.png?token=abc";
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({ ok: true, status: 200, json: async () => ({ url: signedUrl }) }),
+    );
+
+    // Default className is max-h-52; a prior broken heuristic rewrote that into
+    // width/height/resize query params on object/sign URLs (silent no-op / risk).
+    render(<SignedImage endpoint={ENDPOINT} alt="Signed crop" />);
+
+    const img = await screen.findByRole("img", { name: "Signed crop" });
+    const src = img.getAttribute("src") ?? "";
+    expect(src).toContain("/object/sign/");
+    expect(src).not.toContain("width=");
+    expect(src).not.toContain("height=");
+    expect(src).not.toContain("resize=");
+  });
 });