Reece Browne
4d207f0c3f
## What Two fixes to the pull-request a11y job (#7086 follow-up), both found on its first day live. ### It now scans a component's stories when the component changes The job picked its scan set from changed **story files** alone. But a story renders the live component — editing `Button.tsx` changes what every Button story shows without touching a story file, and the job scanned nothing. That's the common way a11y regressions arrive, and it was exactly the case the job missed. The scan set now also includes stories whose **same-named sibling source file changed**: edit `Button.tsx` or `Button.css` and `Button.stories.tsx` is scanned. Changes that ripple further than a component's own stories (shared UI, theme tokens) remain the nightly sweep's job. ### It no longer fails on cold-start infrastructure noise The job's first real run (#7163) flagged a story as "failed to render". The story was fine — on a cold dependency cache (**every** CI run), Vite discovered the preview's own dependency graph mid-run and reloaded the page, killing whichever story happened to be loading with `Failed to fetch dynamically imported module`. Reproduced on a cold cache, passes on a warm one. - The preview's deps are named in `optimizeDeps.include`, which removes the mid-run reload (verified cold). - A batch whose report contains crash-class failures (failures carrying no axe rule) is retried once — a one-off infrastructure death passes the retry, a story that genuinely can't render fails both attempts and is still reported. Also: the scan-report artifacts were never actually uploading — they live in a dot-directory, which `upload-artifact` silently skips as hidden by default. `include-hidden-files: true` fixes that for the PR job and the nightly, so a red run finally has its evidence attached. ### The glue is Node now, so tasks work from any shell Raised in review: the pipeline leaned on `bash`, `sed`, `grep`, `sort` and `tr`. Task runs its commands in an embedded POSIX interpreter, but those are external binaries it has to find on PATH — and a Windows dev calling tasks from **PowerShell** has none of them (`sed`/`tr` missing outright, `sort` resolves to Windows' own, and `bash` resolves to *WSL's*). Confirmed broken by running the task from PowerShell before the change. The batch runner and affected-story detection are now small Node scripts (`a11y-scan.mjs`, `a11y-changed.mjs`) — the repo already requires Node, so one implementation serves PowerShell, git-bash and CI alike, instead of maintaining `.sh`/`.ps1` twins. ## Testing - Sibling detection: editing `Tabs.tsx` (component only) pulls `Tabs.stories.tsx` into the scan set; editing a `.css` sibling does the same; nothing unrelated leaks in. - **From PowerShell**: `task frontend:storybook:a11y:changed` early-exits cleanly with no changes, and with a component edit it detects the sibling, runs the browser scan and passes the gate — same result from git-bash. - Cold cache end-to-end: cleared both Vite caches, ran the scan — no re-optimize, no reload, stories fail only on their (baselined) axe results. - Crash classifier: 1 on a synthetic crash report, 0 on axe-only failures, 0 on a real report — so the retry can't be triggered by legitimate violations. - Full scan + gate run green end-to-end; taskfile parses, workflows are valid YAML, Prettier/ESLint pass. #7163's red check needs no action from that PR's author — it should go green on re-run once this lands.
Frontend
All frontend commands are run from the repository root using Task:
task frontend:dev— start Vite dev server (localhost:5173)task frontend:build— production buildtask frontend:test— run teststask frontend:test:watch— run tests in watch modetask frontend:lint— run ESLint + cycle detectiontask frontend:typecheck— run TypeScript type checkingtask frontend:check— run typecheck + lint + testtask frontend:install— install npm dependencies
For desktop app development, see the Tauri section below.
Layout
frontend/ is a workspace containing one or more apps. Today it holds the
PDF editor under frontend/editor/; new apps (the developer portal, etc.)
will sit alongside it as siblings. Shared tooling — package.json, node_modules,
.storybook/, ESLint, Prettier — lives at frontend/ so every app installs
once and lints with the same config.
Environment Variables
The editor's environment variables live in committed .env files at
frontend/editor/:
.env— used by all builds (core, proprietary, and as the base for desktop/SaaS).env.desktop— additional vars loaded in desktop (Tauri) mode.env.saas— additional vars loaded in SaaS mode
These files contain non-secret defaults and are checked into Git, so most dev work needs no further setup.
To override values locally (API keys, machine-specific settings), create an uncommitted sibling editor/.env.local / editor/.env.desktop.local / editor/.env.saas.local. Vite automatically layers these on top of the committed files.
Docker Setup
For Docker deployments and configuration, see the Docker README.
Tauri
All desktop tasks are available via Task. From the root of the repo:
Dev
task desktop:dev
This ensures the JLink runtime and backend JAR exist (skipping if already built), then starts Tauri in dev mode.
Build
task desktop:build
This does a full clean rebuild of the backend JAR and JLink runtime, then builds the Tauri app for production.
Platform-specific dev builds are also available:
task desktop:build:dev # No bundling
task desktop:build:dev:mac # macOS .app bundle
task desktop:build:dev:windows # Windows NSIS installer
task desktop:build:dev:linux # Linux AppImage
JLink Tasks
You can also run JLink steps individually:
task desktop:jlink # Build JAR + create JLink runtime
task desktop:jlink:jar # Build backend JAR only
task desktop:jlink:runtime # Create JLink custom JRE only
task desktop:jlink:clean # Remove JLink artifacts
Clean
task desktop:clean
Removes all desktop build artifacts including JLink runtime, bundled JARs, Cargo build, and dist/build directories.