feat: PDF annotations for documents (#40) #54

Merged

marcel merged 10 commits from feat/40-pdf-annotations into main 2026-03-24 10:00:28 +01:00

Conversation 0 Commits 10 Files Changed 40 +1884 -34

marcel commented 2026-03-24 08:32:35 +01:00

Owner

Copy Link

Summary

• Adds an annotation layer on top of the PDF.js viewer — admin users can draw highlight rectangles directly on PDF pages
• Annotations are persisted to the backend (new DocumentAnnotation entity + REST endpoints) and reload on page visit
• Admin users see an active Annotieren button; read-only users see a disabled one (permission: ANNOTATE_ALL)
• Adds ANNOTATE_ALL permission to the Administrators group via Flyway migration

E2E fixes included

• beforeAll hooks in the PDF viewer and annotation test suites now use the Playwright request fixture (direct API calls) instead of UI automation — eliminates 90 s timeout failures in CI
• Fixed pointer-capture bug in AnnotationLayer.svelte: closest('[data-annotation]') replaces direct dataset.annotation check so delete buttons inside annotation divs fire correctly
• DataInitializer: reader test user is created independently of the person-seed guard (was silently skipped when DB already had seed data)
• Maven dev profile now activates dev,e2e Spring profiles so the E2E seed always runs locally

Test plan

• All 21 E2E tests pass (npm run test:e2e)
• Admin can draw, persist, reload, and delete annotations on a PDF
• Reader user sees disabled Annotieren button
• Backend unit tests pass (./mvnw test)

🤖 Generated with Claude Code

## Summary - Adds an annotation layer on top of the PDF.js viewer — admin users can draw highlight rectangles directly on PDF pages - Annotations are persisted to the backend (new `DocumentAnnotation` entity + REST endpoints) and reload on page visit - Admin users see an active **Annotieren** button; read-only users see a disabled one (permission: `ANNOTATE_ALL`) - Adds `ANNOTATE_ALL` permission to the Administrators group via Flyway migration ## E2E fixes included - `beforeAll` hooks in the PDF viewer and annotation test suites now use the Playwright `request` fixture (direct API calls) instead of UI automation — eliminates 90 s timeout failures in CI - Fixed pointer-capture bug in `AnnotationLayer.svelte`: `closest('[data-annotation]')` replaces direct `dataset.annotation` check so delete buttons inside annotation divs fire correctly - `DataInitializer`: reader test user is created independently of the person-seed guard (was silently skipped when DB already had seed data) - Maven dev profile now activates `dev,e2e` Spring profiles so the E2E seed always runs locally ## Test plan - [ ] All 21 E2E tests pass (`npm run test:e2e`) - [ ] Admin can draw, persist, reload, and delete annotations on a PDF - [ ] Reader user sees disabled Annotieren button - [ ] Backend unit tests pass (`./mvnw test`) 🤖 Generated with [Claude Code](https://claude.com/claude-code)

marcel added 8 commits 2026-03-24 08:32:36 +01:00

feat(frontend): replace iframe with PDF.js viewer (#39) ... 5fb6a1eec0

- Install pdfjs-dist v5 and add optimizeDeps pre-bundle config
- New PdfViewer.svelte component: renders each page on a <canvas> with
  correct device-pixel-ratio scaling, overlays a text layer (enables
  text selection; foundation for annotations in #40), prev/next
  navigation, zoom controls, and lazy page rendering (only current ±1
  pre-fetched — avoids freezing on multi-page documents)
- Replace the <iframe> in documents/[id]/+page.svelte with PdfViewer;
  image attachments continue to use <img>; detection now uses
  doc.contentType instead of filename extension
- Unit tests for navigation controls and page counter (pdfjs mocked)
- E2E tests: PDF renders as canvas (not iframe), nav controls visible,
  image fallback stays as <img>; minimal.pdf fixture for upload tests

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

fix(frontend): load pdfjs-dist dynamically to avoid SSR crash (#39) ... 1ad8fffd1b

Static import of pdfjs-dist fails during SSR because DOMMatrix and
other browser globals are unavailable in Node.js. Move the import into
onMount so it only ever executes in the browser. A plain pdfjsLib
variable holds the module; a $state boolean pdfjsReady triggers the
load-document effect once the library is available.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

devops: add rebuild-frontend.sh script ... 0ef81e20f6

Stops the container, removes the stale node_modules volume, and
rebuilds the image. Run this after adding or updating npm dependencies.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

fix(frontend): zoom buttons now re-render immediately (#39) ... ca5726e7c3

scale was only read inside the async renderPage function, so Svelte 5
never tracked it as a reactive dependency of the effect. Reading scale
synchronously in the effect condition registers it as a dependency and
triggers a re-render on every zoom change.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

feat: add PDF annotation feature (#40) ... b45ec744b2

Backend:
- Add ANNOTATE_ALL permission
- Add ANNOTATION_NOT_FOUND and ANNOTATION_OVERLAP error codes
- V10 migration: document_annotations table with page/rect/color/owner
- DocumentAnnotation entity, AnnotationRepository, CreateAnnotationDTO
- AnnotationService: overlap detection (rectangle intersection), ownership enforcement on delete
- AnnotationController: GET (authenticated), POST/DELETE (ANNOTATE_ALL)
- 15 new tests (AnnotationServiceTest, AnnotationControllerTest) — TDD red/green

Frontend:
- AnnotationLayer.svelte: pointer-event drawing, colored rect overlays, delete buttons
- PdfViewer.svelte: annotate toggle, color picker, loads/saves/deletes annotations via API
- Disabled annotate button with tooltip for users without ANNOTATE_ALL
- canAnnotate exposed from layout server, passed to PdfViewer
- errors.ts + de/en/es translations for new error codes
- 3 new unit tests for AnnotationLayer — TDD red/green

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

fix(e2e): activate e2e profile in dev mode and create reader user idempotently ... ea1c097ae0

- Add e2e to the dev Maven profile's spring.profiles.active so
  DataInitializer always runs when developing/testing locally
- Create the reader test user independently of the person-seed guard
  so it survives restarts where seed data already exists
- Set SPRING_PROFILES_ACTIVE=dev,e2e in docker-compose backend service

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

fix(frontend): use closest() to skip pointer capture on annotation children ... 06e846f2f8

When a child element inside an annotation div (e.g. the delete button)
was clicked, the AnnotationLayer's pointerdown handler would call
setPointerCapture, preventing the child's click event from firing.
Using closest('[data-annotation]') instead of checking dataset.annotation
on the target directly fixes delete buttons inside annotation elements.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

test(e2e): rewrite PDF viewer and annotation beforeAll to use API calls ... 05f3ce687f

- Replace UI-based document setup in beforeAll hooks with direct API
  calls via Playwright's request fixture — avoids the 90s timeout from
  navigating + uploading through the Docker dev server
- Fix non-PDF test: create a file-less document in beforeAll instead of
  relying on seed data that may not exist
- Share annotationDocId across describe blocks so the read-only user
  test can navigate to a known PDF document
- Add annotation visibility check before enabling annotate mode in the
  delete test

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

marcel added 1 commit 2026-03-24 08:50:29 +01:00

fix(frontend): make annotation delete button fully opaque ... eb8bcdb426

Replace opacity: 0.3 on the annotation container with an rgba
background so child elements (the × button) are not affected by
the parent's opacity and render at full opacity.

Refs #40
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

marcel added 1 commit 2026-03-24 08:52:59 +01:00

feat(db): add migration to grant ANNOTATE_ALL to existing admin groups ... 37f5c3d005

Covers existing deployments where the Administrators group was created
before DataInitializer started including ANNOTATE_ALL.

Refs #40
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

marcel merged commit 37f5c3d005 into main 2026-03-24 10:00:28 +01:00

marcel deleted branch feat/40-pdf-annotations 2026-03-24 10:00:31 +01:00

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

P0-critical

Blocks a core user journey, causes data loss, or is a security/accessibility barrier. Work on this before P1+.

P1-high

Significant friction on a main user journey; workaround exists but is non-obvious. Next up after P0.

P2-medium

Noticeable improvement; doesn't block anything; schedule opportunistically.

P3-later

Cosmetic or parking-lot work; fine to stay open indefinitely.

audit

Read-only audit / assessment work; produces a report rather than changing code

bug

Something isn't working

cleanup

Removal of dead code, vague comments, naming violations, and scratch artifacts

collaboration

We want to extend the family archive to have more collaboration tools

conversation

descoped

We will do that later

devops

documentation

README, ARCHITECTURE, GLOSSARY, CONTRIBUTING, per-domain docs

epic

Marker for epic-level issues that group multiple child issues

feature

file-upload

legibility

Codebase Legibility Refactor — preparing the codebase for human evaluation and bus-factor reduction

notification

person

phase-1: security

Security hygiene — must be done first

phase-2: container-images

Production-ready multi-stage Docker images

phase-3: prod-compose

Production compose overlay + Caddy reverse proxy

phase-4: spring-prod-profile

Spring Boot production configuration profile

phase-5: backups

Database and object storage backup strategy

phase-6: deployment-docs

.env.example, DEPLOYMENT.md, runbook

phase-7: monitoring

Prometheus, Loki, Grafana, Alertmanager

refactor

Code restructuring without behaviour change

security

test

ui

UI/UX and accessibility issues

user

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

Jens marcel

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: marcel/familienarchiv#54