fix: release QA hardening across processing, media, security, and CI gates (#649)

A release-readiness QA pass over the whole product. The commits split into defects a user would hit and gates that were reporting green while measuring nothing. ## Fixes that change behaviour Rate limiting was bypassable on every install: TRUST_PROXY defaulted to true, so request.ip came from a client-set header and a forged X-Forwarded-For got past the login limiter. The default is now a private-network trust list. A transient Postgres outage stranded in-flight jobs, leaving finished output on disk with no row pointing at it. A reconciler now resolves those rows and adopts the bytes rather than dropping the work. A Redis connection that moved to a new address wedged every read-blocked consumer, so completions stopped signalling while health still answered 200. Socket timeouts plus subscriber pings recover it. Installing more than one AI bundle left the shared venv multi-versioned and silently broke three tools. The installer now reconciles distributions to one version each. Converting an image to JXL at quality 1 through 4 returned a 500, because libjxl 0.7 rejects the distance those values compute. The quality is floored at what the encoder honours. A missing ffmpeg was also reported to the user as a corrupt upload; it now says the engine is unavailable. RAW uploads reached an unpatched LibRaw on arm64, so it is built from source at 0.22.2, and the release scan was split so it can fail on an unfixed critical instead of hiding it behind ignore-unfixed. ## Gates that could not fail Two mutation lanes ran zero mutants because Stryker crawled the gitignored docs build; coverage discarded its whole report on any failing test; the lint gate skipped root tests, scripts, and two workspaces; and several generated matrices counted a host missing ffmpeg as a passing tool. Each now measures what it claims. Full evidence and the outstanding release items are tracked locally and are not part of this branch.
2026-08-03 07:46:42 +02:00 · 2026-07-27 15:37:30 +08:00
parent bc32f86a07
commit d10d0f544f
855 changed files with 54564 additions and 13092 deletions
@@ -4,6 +4,7 @@ import { pagefindPlugin } from "vitepress-plugin-pagefind";
 import pkg from "../../../package.json";
 import { SUPPORTED_LOCALES } from "../../../packages/shared/src/i18n/index.ts";
 import { t } from "./i18n/ui.mjs";
+import { pageOnlySidebar } from "./llms-sidebar.mjs";

 const NON_EN = SUPPORTED_LOCALES.filter((l) => l.code !== "en");
 const HOSTNAME = "https://docs.snapotter.com";
@@ -127,6 +128,14 @@ export default defineConfig({

  sitemap: { hostname: "https://docs.snapotter.com" },

+  // VitePress defaults to shiki's `github-light`, whose comment (#6a737d, 4.45:1)
+  // and string (#22863a, 4.28:1) tokens both miss AA against the code-block
+  // background. The high-contrast variant is built for exactly this and is bundled
+  // with shiki already. Dark mode was never the failing side.
+  markdown: {
+    theme: { light: "github-light-high-contrast", dark: "github-dark" },
+  },
+
  head: [
    ["meta", { name: "theme-color", content: "#E07832" }],
    [
@@ -224,6 +233,7 @@ export default defineConfig({
      }),
      llmstxt({
        domain: "https://docs.snapotter.com",
+        sidebar: pageOnlySidebar,
        customLLMsTxtTemplate: `# {title}

 {description}
@@ -342,19 +352,19 @@ function buildBaseTheme() {
              {
                text: "Essentials",
                items: [
-                  { text: "Resize", link: "/tools/image/resize" },
-                  { text: "Crop", link: "/tools/image/crop" },
-                  { text: "Rotate & Flip", link: "/tools/image/rotate" },
-                  { text: "Convert", link: "/tools/image/convert" },
-                  { text: "Compress", link: "/tools/image/compress" },
+                  { text: "Resize Image", link: "/tools/image/resize" },
+                  { text: "Crop Image", link: "/tools/image/crop" },
+                  { text: "Rotate & Flip Image", link: "/tools/image/rotate" },
+                  { text: "Convert Image", link: "/tools/image/convert" },
+                  { text: "Compress Image", link: "/tools/image/compress" },
                ],
              },
              {
                text: "Optimization",
                items: [
                  { text: "Optimize for Web", link: "/tools/image/optimize-for-web" },
-                  { text: "Remove Metadata", link: "/tools/image/strip-metadata" },
-                  { text: "Edit Metadata", link: "/tools/image/edit-metadata" },
+                  { text: "Remove Image Metadata", link: "/tools/image/strip-metadata" },
+                  { text: "Edit Image Metadata", link: "/tools/image/edit-metadata" },
                  { text: "Bulk Rename", link: "/tools/image/bulk-rename" },
                  { text: "Image to PDF", link: "/tools/image/image-to-pdf" },
                  { text: "Favicon Generator", link: "/tools/image/favicon" },
@@ -364,7 +374,7 @@ function buildBaseTheme() {
                text: "Adjustments",
                items: [
                  { text: "Adjust Colors", link: "/tools/image/adjust-colors" },
-                  { text: "Sharpening", link: "/tools/image/sharpening" },
+                  { text: "Sharpen Image", link: "/tools/image/sharpening" },
                  { text: "Replace & Invert Color", link: "/tools/image/replace-color" },
                  { text: "Color Blindness Simulation", link: "/tools/image/color-blindness" },
                  { text: "Duotone", link: "/tools/image/duotone" },
@@ -401,9 +411,9 @@ function buildBaseTheme() {
              {
                text: "Layout",
                items: [
-                  { text: "Collage / Grid", link: "/tools/image/collage" },
-                  { text: "Stitch / Combine", link: "/tools/image/stitch" },
-                  { text: "Image Splitting", link: "/tools/image/split" },
+                  { text: "Collage & Grid", link: "/tools/image/collage" },
+                  { text: "Stitch Images", link: "/tools/image/stitch" },
+                  { text: "Split Image", link: "/tools/image/split" },
                  { text: "Border & Frame", link: "/tools/image/border" },
                  { text: "Beautify Screenshot", link: "/tools/image/beautify" },
                  { text: "Circle Crop", link: "/tools/image/circle-crop" },
@@ -426,8 +436,8 @@ function buildBaseTheme() {
                  { text: "Remove Background", link: "/tools/image/remove-background" },
                  { text: "Image Upscaling", link: "/tools/image/upscale" },
                  { text: "Object Eraser", link: "/tools/image/erase-object" },
-                  { text: "OCR / Text Extraction", link: "/tools/image/ocr" },
-                  { text: "Face / PII Blur", link: "/tools/image/blur-faces" },
+                  { text: "Extract Text from Image (OCR)", link: "/tools/image/ocr" },
+                  { text: "Blur Faces & PII", link: "/tools/image/blur-faces" },
                  { text: "Smart Crop", link: "/tools/image/smart-crop" },
                  { text: "Image Enhancement", link: "/tools/image/image-enhancement" },
                  { text: "Face Enhancement", link: "/tools/image/enhance-faces" },
@@ -460,7 +470,7 @@ function buildBaseTheme() {
              { text: "Video Color", link: "/tools/video/video-color" },
              { text: "Video Speed", link: "/tools/video/video-speed" },
              { text: "Reverse Video", link: "/tools/video/reverse-video" },
-              { text: "Normalize Audio", link: "/tools/video/video-loudnorm" },
+              { text: "Normalize Video Audio", link: "/tools/video/video-loudnorm" },
              { text: "Aspect Pad", link: "/tools/video/aspect-pad" },
              { text: "Blur Pad", link: "/tools/video/blur-pad" },
              { text: "Watermark Video", link: "/tools/video/watermark-video" },
@@ -484,7 +494,7 @@ function buildBaseTheme() {
            items: [
              { text: "Convert Audio", link: "/tools/audio/convert-audio" },
              { text: "Trim Audio", link: "/tools/audio/trim-audio" },
-              { text: "Volume Adjust", link: "/tools/audio/volume-adjust" },
+              { text: "Adjust Volume", link: "/tools/audio/volume-adjust" },
              { text: "Normalize Audio", link: "/tools/audio/normalize-audio" },
              { text: "Fade Audio", link: "/tools/audio/fade-audio" },
              { text: "Reverse Audio", link: "/tools/audio/reverse-audio" },
@@ -517,9 +527,9 @@ function buildBaseTheme() {
              { text: "Repair PDF", link: "/tools/pdf/repair-pdf" },
              { text: "Web-Optimize PDF", link: "/tools/pdf/linearize-pdf" },
              { text: "Grayscale PDF", link: "/tools/pdf/grayscale-pdf" },
-              { text: "PDF/A Convert", link: "/tools/pdf/pdfa-convert" },
+              { text: "PDF/A Converter", link: "/tools/pdf/pdfa-convert" },
              { text: "Crop PDF", link: "/tools/pdf/crop-pdf" },
-              { text: "N-up PDF", link: "/tools/pdf/nup-pdf" },
+              { text: "Pages Per Sheet (N-up)", link: "/tools/pdf/nup-pdf" },
              { text: "Booklet PDF", link: "/tools/pdf/booklet-pdf" },
              { text: "Watermark PDF", link: "/tools/pdf/watermark-pdf" },
              { text: "PDF Page Numbers", link: "/tools/pdf/pdf-page-numbers" },
@@ -545,7 +555,7 @@ function buildBaseTheme() {
              { text: "Markdown to Word", link: "/tools/files/markdown-to-docx" },
              { text: "Markdown to HTML", link: "/tools/files/markdown-to-html" },
              { text: "Markdown to PDF", link: "/tools/files/markdown-to-pdf" },
-              { text: "Convert EPUB", link: "/tools/files/epub-convert" },
+              { text: "Convert from EPUB", link: "/tools/files/epub-convert" },
              { text: "Convert to EPUB", link: "/tools/files/to-epub" },
              { text: "Chart Maker", link: "/tools/files/chart-maker" },
              { text: "CSV to Excel", link: "/tools/files/csv-excel" },
@@ -553,7 +563,7 @@ function buildBaseTheme() {
              { text: "JSON to XML", link: "/tools/files/json-xml" },
              { text: "Split CSV", link: "/tools/files/split-csv" },
              { text: "Merge CSVs", link: "/tools/files/merge-csvs" },
-              { text: "YAML / JSON", link: "/tools/files/yaml-json" },
+              { text: "Convert YAML / JSON", link: "/tools/files/yaml-json" },
              { text: "XML to CSV", link: "/tools/files/xml-to-csv" },
              { text: "Create ZIP", link: "/tools/files/create-zip" },
              { text: "Extract ZIP", link: "/tools/files/extract-zip" },
@@ -0,0 +1,22 @@
+function filterSectionLinks(items) {
+  return (items ?? []).flatMap((item) => {
+    if (typeof item?.link === "string" && item.link.includes("#")) return [];
+
+    const next = { ...item };
+    if (Array.isArray(next.items)) next.items = filterSectionLinks(next.items);
+    return [next];
+  });
+}
+
+/**
+ * Keep the LLM index page-oriented. VitePress supports sidebar links to page
+ * sections, but vitepress-plugin-llms resolves every link as a source file.
+ */
+export function pageOnlySidebar(sidebar) {
+  if (Array.isArray(sidebar)) return filterSectionLinks(sidebar);
+  if (!sidebar || typeof sidebar !== "object") return sidebar;
+
+  return Object.fromEntries(
+    Object.entries(sidebar).map(([base, items]) => [base, filterSectionLinks(items)]),
+  );
+}
@@ -51,12 +51,14 @@ function copyCommand() {
 </script>

 <template>
-  <div class="so-home">
+  <!-- <main>, not <div>: this page uses layout "page", which gives it no main
+       landmark of its own, so every element on it fell outside a landmark. -->
+  <main class="so-home">
    <section class="hero">
      <h1 class="hero-title">{{ tt("home.title") }}</h1>
      <p class="hero-sub">{{ tt("home.heroSub") }}</p>
      <div class="cmd" :title="tt('home.clickToCopy')" @click="copyCommand">
-        <code>$ {{ command }}</code>
+        <code tabindex="0">$ {{ command }}</code>
        <button class="copy" type="button" :aria-label="tt('home.copyCommandAria')" @click.stop="copyCommand">{{ copyLabel }}</button>
      </div>
      <p class="hero-meta">
@@ -112,7 +114,7 @@ function copyCommand() {
        <span>{{ tt(s.subKey) }}</span>
      </a>
    </section>
-  </div>
+  </main>
 </template>

 <style scoped>
@@ -14,10 +14,63 @@
  --vp-button-brand-active-border: transparent;
  --vp-button-brand-active-text: #fff;
  --vp-button-brand-active-bg: #7A3D10;
+
+  /* Inline `code` never sits on white. VitePress tints it with --vp-c-default-soft
+     (#e7e9ec in tables and prose) and custom blocks tint it further (#f7dcca), which
+     drops brand-1 to 4.34:1 and 4.03:1. The darker ink clears AA on both: 5.62:1 and
+     5.22:1. This was 482 failures on the REST page alone. */
+  --vp-code-color: #8F4712;
+  /* The language label above a code block was #929295 on #f6f6f7, 2.87:1. */
+  --vp-code-lang-color: #5C5C60;
 }
+/* Inside a tip/info block VitePress paints inline code with brand-1 over the brand
+   tint directly, so --vp-code-color never reaches it: 4.03:1. Dark mode was fine. */
+.vp-doc .custom-block :not(pre) > code {
+  color: #8F4712;
+}
+
+.dark .vp-doc .custom-block :not(pre) > code {
+  color: var(--vp-c-brand-1);
+}
+
 .dark {
  --vp-c-brand-1: #F0A766;
  --vp-c-brand-2: #F09550;
  --vp-c-brand-3: #A85518;
  --vp-c-brand-soft: rgba(240, 149, 80, 0.16);
 }
+
+/* Tablet navbar overflow (SITE-20260726-011).
+
+   VitePress swaps to the desktop nav at 768px. Several locales carry top-level
+   labels far longer than English (es 55 characters, pt-BR 54, th 53, ru 52,
+   de 48 against en 33), so between 768px and the 960px sidebar breakpoint the
+   navbar's right edge landed outside the viewport and every docs page in those
+   languages scrolled sideways.
+
+   Moving that one switch to 960px puts the top-level nav back in the hamburger
+   overlay for the 768-959 band. Nothing becomes unreachable: the sidebar is
+   already opened from VPLocalNav's menu button below 960px, and this is exactly
+   the arrangement VitePress uses below 768px. VPNavScreen is v-if-mounted, so
+   the display override only ever applies to an open overlay.
+
+   One upstream wart is inherited: useNav closes an open overlay on resize past
+   768px, so dragging the window across that width inside the band shuts the
+   menu. Reopening it works.
+
+   The declarations carry !important because VitePress ships these rules from
+   Vue `<style scoped>` blocks, which compile to `.VPNavBarMenu[data-v-hash]`
+   and outrank a plain class selector however late it loads. */
+@media (min-width: 768px) and (max-width: 959.9px) {
+  .VPNavBarMenu {
+    display: none !important;
+  }
+
+  .VPNavBarHamburger {
+    display: block !important;
+  }
+
+  .VPNavScreen {
+    display: block !important;
+  }
+}