From c73af46c33b9e94730116a95451b09ac99987f18 Mon Sep 17 00:00:00 2001 From: Bastien Chanot Date: Sat, 23 May 2026 22:12:06 +0200 Subject: [PATCH] docs(plans): add laterality support implementation plan 10 tasks: schema, parser, i18n, LateralityPicker, EditorRoute integration, ObservationCard display, PDF output, SVG editor dropdown, docs, verification. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../plans/2026-05-23-laterality-support.md | 738 ++++++++++++++++++ 1 file changed, 738 insertions(+) create mode 100644 docs/superpowers/plans/2026-05-23-laterality-support.md diff --git a/docs/superpowers/plans/2026-05-23-laterality-support.md b/docs/superpowers/plans/2026-05-23-laterality-support.md new file mode 100644 index 00000000..f84ec153 --- /dev/null +++ b/docs/superpowers/plans/2026-05-23-laterality-support.md @@ -0,0 +1,738 @@ +# Laterality Support Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Add bilateral/unpaired laterality to anatomical zones so practitioners can specify left/right side on bilateral structures. + +**Architecture:** New `data-anno-lateral` SVG attribute parsed into `Bone.lateral`. New `side` field on `ObservationZone` schema. LateralityPicker modal triggered on bilateral zone clicks. Side displayed in zone badges and PDF output. SVG editor gets a laterality dropdown. + +**Tech Stack:** React 19, TypeScript strict, Zustand 5, Zod 3, Tailwind v4, pdf-lib, vitest + +--- + +### Task 1: Schema + Bone Type — Add `side` to ObservationZone and `lateral` to Bone + +**Files:** +- Modify: `src/domain/schema/observation.ts` +- Modify: `src/anatomy/types.ts` +- Test: `tests/unit/schema.observation.test.ts` + +- [ ] **Step 1: Write failing tests for LateralSideSchema and side field** + +Add to `tests/unit/schema.observation.test.ts`: + +```ts +import { + ObservationSchema, + ObservationZoneSchema, + LateralSideSchema, + VertebraSchema, + SeveritySchema, + FindingSchema, +} from '@/domain/schema/observation' + +describe('LateralSideSchema', () => { + it('accepts left and right', () => { + expect(LateralSideSchema.parse('left')).toBe('left') + expect(LateralSideSchema.parse('right')).toBe('right') + }) + + it('rejects unknown side', () => { + expect(() => LateralSideSchema.parse('both')).toThrow() + expect(() => LateralSideSchema.parse('')).toThrow() + }) +}) + +describe('ObservationZoneSchema with side', () => { + it('accepts a zone without side (unpaired)', () => { + expect(() => ObservationZoneSchema.parse({ boneId: 'sternum' })).not.toThrow() + }) + + it('accepts a zone with side left', () => { + const parsed = ObservationZoneSchema.parse({ boneId: 'knee', side: 'left' }) + expect(parsed.side).toBe('left') + }) + + it('accepts a zone with side right', () => { + const parsed = ObservationZoneSchema.parse({ boneId: 'knee', side: 'right' }) + expect(parsed.side).toBe('right') + }) + + it('accepts two zones with same boneId but different sides', () => { + const obs = { + id: 'obs-1', + zones: [ + { boneId: 'knee', side: 'left' }, + { boneId: 'knee', side: 'right' }, + ], + findings: [], + freeTextFindings: [], + comment: '', + } + expect(() => ObservationSchema.parse(obs)).not.toThrow() + }) +}) +``` + +- [ ] **Step 2: Run tests to verify they fail** + +Run: `pnpm test:run -- tests/unit/schema.observation.test.ts` +Expected: FAIL — `LateralSideSchema` is not exported + +- [ ] **Step 3: Add LateralSideSchema and side field to observation.ts** + +In `src/domain/schema/observation.ts`, add after the `VertebraSchema` definition: + +```ts +export const LateralSideSchema = z.enum(['left', 'right']) + +export type LateralSide = z.infer +``` + +Add `side` to `ObservationZoneSchema`: + +```ts +export const ObservationZoneSchema = z.object({ + boneId: z.string().min(1), + detailSourceId: z.string().optional(), + vertebrae: z.array(VertebraSchema).optional(), + side: LateralSideSchema.optional(), +}) +``` + +- [ ] **Step 4: Add `lateral` field to Bone interface** + +In `src/anatomy/types.ts`, add to `Bone` interface after `special?`: + +```ts +lateral?: 'bilateral' | 'unpaired' +``` + +- [ ] **Step 5: Run tests to verify they pass** + +Run: `pnpm test:run -- tests/unit/schema.observation.test.ts` +Expected: ALL PASS + +- [ ] **Step 6: Run full typecheck** + +Run: `pnpm typecheck` +Expected: No errors + +- [ ] **Step 7: Commit** + +```bash +git add src/domain/schema/observation.ts src/anatomy/types.ts tests/unit/schema.observation.test.ts +git commit -m "feat(schema): add LateralSideSchema and Bone.lateral for laterality support" +``` + +--- + +### Task 2: SVG Parser — Read `data-anno-lateral` attribute + +**Files:** +- Modify: `src/anatomy/svgConvention.ts` +- Test: `tests/unit/anatomy.svgConvention.test.ts` + +- [ ] **Step 1: Write failing tests for lateral parsing** + +Add to `tests/unit/anatomy.svgConvention.test.ts`, update the `FIXTURE` and add tests: + +Update `FIXTURE` — add a bilateral element: + +```xml + +``` + +Add tests: + +```ts +it('captures data-anno-lateral when present', () => { + const map = parseSvgBones(svgFromString(FIXTURE)) + expect(map.get('point-knee')?.lateral).toBe('bilateral') +}) + +it('leaves lateral undefined when attribute absent', () => { + const map = parseSvgBones(svgFromString(FIXTURE)) + expect(map.get('point-shoulder')?.lateral).toBeUndefined() +}) +``` + +- [ ] **Step 2: Run tests to verify they fail** + +Run: `pnpm test:run -- tests/unit/anatomy.svgConvention.test.ts` +Expected: FAIL — `lateral` is undefined for knee + +- [ ] **Step 3: Update parseSvgBones to read data-anno-lateral** + +In `src/anatomy/svgConvention.ts`, in `parseSvgBones()`, add after the `special` read: + +```ts +const lateral = el.getAttribute('data-anno-lateral') as + | 'bilateral' + | 'unpaired' + | undefined ?? undefined +``` + +In the `else` branch (new Bone creation), add `lateral` to the object: + +```ts +map.set(id, { + id, + fr, + en, + category, + opensDetail, + special, + lateral, + els: [el], +}) +``` + +In the `existing` merge branch, add: + +```ts +if (lateral && !existing.lateral) { + existing.lateral = lateral +} +``` + +- [ ] **Step 4: Run tests to verify they pass** + +Run: `pnpm test:run -- tests/unit/anatomy.svgConvention.test.ts` +Expected: ALL PASS + +- [ ] **Step 5: Commit** + +```bash +git add src/anatomy/svgConvention.ts tests/unit/anatomy.svgConvention.test.ts +git commit -m "feat(anatomy): parse data-anno-lateral attribute from SVG" +``` + +--- + +### Task 3: i18n — Add laterality translation keys + +**Files:** +- Modify: `src/i18n/fr.ts` +- Modify: `src/i18n/en.ts` +- Test: `tests/unit/i18n.dicts.test.ts` (existing test verifies key parity) + +- [ ] **Step 1: Add keys to fr.ts** + +Add after the vertebra section in `src/i18n/fr.ts`: + +```ts +// laterality +'lateral.which_side': 'Quel côté ?', +'lateral.left': 'Gauche', +'lateral.right': 'Droite', +'lateral.both': 'Les deux', +'lateral.left_short': 'G', +'lateral.right_short': 'D', +'lateral.bilateral': 'Bilatéral', +'lateral.unpaired': 'Impair', +``` + +- [ ] **Step 2: Add keys to en.ts** + +Add after the vertebra section in `src/i18n/en.ts`: + +```ts +// laterality +'lateral.which_side': 'Which side?', +'lateral.left': 'Left', +'lateral.right': 'Right', +'lateral.both': 'Both', +'lateral.left_short': 'L', +'lateral.right_short': 'R', +'lateral.bilateral': 'Bilateral', +'lateral.unpaired': 'Unpaired', +``` + +- [ ] **Step 3: Run i18n key parity test** + +Run: `pnpm test:run -- tests/unit/i18n.dicts.test.ts` +Expected: PASS (both dicts have same keys) + +- [ ] **Step 4: Commit** + +```bash +git add src/i18n/fr.ts src/i18n/en.ts +git commit -m "feat(i18n): add laterality translation keys (FR/EN)" +``` + +--- + +### Task 4: LateralityPicker Component + +**Files:** +- Create: `src/components/observation/LateralityPicker.tsx` + +- [ ] **Step 1: Create LateralityPicker component** + +Create `src/components/observation/LateralityPicker.tsx`: + +```tsx +import Dialog from '@/components/ui/Dialog' +import Button from '@/components/ui/Button' +import type { LateralSide } from '@/domain/schema/observation' +import { useT } from '@/i18n/useT' + +export interface LateralityPickerProps { + open: boolean + onClose: () => void + onSelect: (sides: LateralSide[]) => void + title: string + /** Sides already present in the active observation for this boneId. */ + existingSides: LateralSide[] +} + +export default function LateralityPicker({ + open, + onClose, + onSelect, + title, + existingSides, +}: LateralityPickerProps) { + const t = useT() + const hasLeft = existingSides.includes('left') + const hasRight = existingSides.includes('right') + + return ( + +
+

+ {t('lateral.which_side')} +

+
+ + + +
+
+
+ ) +} +``` + +- [ ] **Step 2: Run typecheck** + +Run: `pnpm typecheck` +Expected: No errors + +- [ ] **Step 3: Commit** + +```bash +git add src/components/observation/LateralityPicker.tsx +git commit -m "feat(ui): add LateralityPicker modal component" +``` + +--- + +### Task 5: EditorRoute — Integrate LateralityPicker into zone click flow + +**Files:** +- Modify: `src/app/routes/EditorRoute.tsx` + +- [ ] **Step 1: Add laterality state and imports** + +Add imports at top of `EditorRoute.tsx`: + +```ts +import LateralityPicker from '@/components/observation/LateralityPicker' +import type { LateralSide } from '@/domain/schema/observation' +``` + +Add state after `vertebraTarget` state: + +```ts +const [lateralTarget, setLateralTarget] = useState<{ + boneId: string + detailSourceId?: string +} | null>(null) +``` + +- [ ] **Step 2: Modify onZoneClick to handle bilateral zones** + +In `onZoneClick()`, after the `vertebral-precision` block and before the unpaired toggle logic, add: + +```ts +if (bone.lateral === 'bilateral') { + setLateralTarget({ + boneId, + ...(detailSourceId ? { detailSourceId } : {}), + }) + return +} +``` + +- [ ] **Step 3: Add LateralityPicker to JSX** + +Add before the closing `` tag, after the VertebraPicker block: + +```tsx +{lateralTarget && activeObs && ( + setLateralTarget(null)} + title={boneLabel( + allBones.get(lateralTarget.boneId), + locale, + lateralTarget.boneId, + )} + existingSides={ + activeObs.zones + .filter( + (z) => + z.boneId === lateralTarget.boneId && + z.detailSourceId === lateralTarget.detailSourceId && + z.side, + ) + .map((z) => z.side!) as LateralSide[] + } + onSelect={(sides) => { + const fresh = + useReportStore.getState().report?.observations[activeIndex] + if (!fresh) { + setLateralTarget(null) + return + } + let nextZones = [...fresh.zones] + for (const side of sides) { + const exists = nextZones.some( + (z) => + z.boneId === lateralTarget.boneId && + z.detailSourceId === lateralTarget.detailSourceId && + z.side === side, + ) + if (!exists) { + nextZones.push({ + boneId: lateralTarget.boneId, + ...(lateralTarget.detailSourceId + ? { detailSourceId: lateralTarget.detailSourceId } + : {}), + side, + }) + } + } + updateObservation(activeIndex, { ...fresh, zones: nextZones }) + setLateralTarget(null) + }} + /> +)} +``` + +- [ ] **Step 4: Handle re-click toggle for bilateral zones** + +The current flow in `onZoneClick` for the bilateral case: +- If both sides already exist → remove both (toggle off) +- If one or zero sides → open picker + +Update the bilateral block: + +```ts +if (bone.lateral === 'bilateral') { + const sidesPresent = activeObs.zones + .filter( + (z) => + z.boneId === boneId && + z.detailSourceId === detailSourceId, + ) + .map((z) => z.side) + .filter(Boolean) as LateralSide[] + + if (sidesPresent.includes('left') && sidesPresent.includes('right')) { + const nextZones = activeObs.zones.filter( + (z) => + !(z.boneId === boneId && z.detailSourceId === detailSourceId), + ) + updateObservation(activeIndex, { ...activeObs, zones: nextZones }) + return + } + + setLateralTarget({ + boneId, + ...(detailSourceId ? { detailSourceId } : {}), + }) + return +} +``` + +- [ ] **Step 5: Run typecheck** + +Run: `pnpm typecheck` +Expected: No errors + +- [ ] **Step 6: Commit** + +```bash +git add src/app/routes/EditorRoute.tsx +git commit -m "feat(editor): integrate LateralityPicker in zone click flow" +``` + +--- + +### Task 6: ObservationCard — Display side in zone badges + +**Files:** +- Modify: `src/components/observation/ObservationCard.tsx` + +- [ ] **Step 1: Update describeZone to show side suffix** + +In `ObservationCard.tsx`, update the `describeZone` function: + +```ts +function describeZone( + z: ObservationZone, + bones: Map, + locale: Locale, + t: (key: string) => string, +): string { + const label = boneLabel(bones.get(z.boneId), locale, z.boneId) + if (z.vertebrae?.length) { + const vs = z.vertebrae + .map((v: Vertebra) => `${v.region}${v.index}`) + .join(', ') + return `${label} (${vs})` + } + if (z.side) { + const sideLabel = t( + z.side === 'left' ? 'lateral.left_short' : 'lateral.right_short', + ) + return `${label} (${sideLabel})` + } + return label +} +``` + +- [ ] **Step 2: Update describeZone call sites to pass t** + +In the JSX, update the two places `describeZone` is called: + +In the zone badges list: +```tsx +{describeZone(z, bones, locale, t)} +``` + +- [ ] **Step 3: Run typecheck** + +Run: `pnpm typecheck` +Expected: No errors + +- [ ] **Step 4: Commit** + +```bash +git add src/components/observation/ObservationCard.tsx +git commit -m "feat(ui): display laterality side in zone badges" +``` + +--- + +### Task 7: PDF Output — Include side in zone labels + +**Files:** +- Modify: `src/pdf/render/observationPage.ts` + +- [ ] **Step 1: Update zone label rendering** + +In `addObservationPage()`, find the `zonesText` construction (around line 369-379). Update to include side: + +```ts +const zonesText = observation.zones + .map((z) => { + const pair = zoneLabels.get(z.boneId) + const label = pair + ? (locale === 'en' ? pair.en || pair.fr : pair.fr || pair.en) || z.boneId + : z.boneId + const v = z.vertebrae?.length + ? ` (${z.vertebrae.map((x) => `${x.region}${x.index}`).join(', ')})` + : '' + const side = z.side + ? ` (${dict[z.side === 'left' ? 'lateral.left' : 'lateral.right']})` + : '' + return `${label}${v}${side}` + }) + .join(' · ') +``` + +- [ ] **Step 2: Run typecheck** + +Run: `pnpm typecheck` +Expected: No errors + +- [ ] **Step 3: Commit** + +```bash +git add src/pdf/render/observationPage.ts +git commit -m "feat(pdf): include laterality side in zone labels" +``` + +--- + +### Task 8: SVG Editor — Add laterality dropdown + +**Files:** +- Modify: `src/app/routes/SvgEditorRoute.tsx` +- Modify: `src/i18n/fr.ts` +- Modify: `src/i18n/en.ts` + +- [ ] **Step 1: Add SVG editor i18n keys** + +In `src/i18n/fr.ts`, add: + +```ts +'svg_editor.lateral': 'Latéralité', +'svg_editor.lateral_unpaired': 'Impair (pas de côté)', +'svg_editor.lateral_bilateral': 'Bilatéral (gauche / droite)', +``` + +In `src/i18n/en.ts`, add: + +```ts +'svg_editor.lateral': 'Laterality', +'svg_editor.lateral_unpaired': 'Unpaired (no side)', +'svg_editor.lateral_bilateral': 'Bilateral (left / right)', +``` + +- [ ] **Step 2: Add dropdown to SvgEditorRoute JSX** + +In `SvgEditorRoute.tsx`, inside the `svg-editor-osteo-fields` div, after the category ` + + + +``` + +- [ ] **Step 3: Wire up event listener in initSvgEditor** + +In `setupGlobalListeners()`, add the lateral select to the change listener array: + +```ts +;['svg-editor-edit-fr', 'svg-editor-edit-en', 'svg-editor-edit-category', 'svg-editor-edit-lateral'].forEach( + (id) => { + getEl(id).addEventListener('change', applyEdit, sig) + }, +) +``` + +- [ ] **Step 4: Read lateral in showEditPanel** + +In `showEditPanel()`, after reading category, add: + +```ts +;(getEl('svg-editor-edit-lateral') as HTMLSelectElement).value = + svgEl.getAttribute('data-anno-lateral') || '' +``` + +- [ ] **Step 5: Write lateral in applyEdit** + +In `applyEdit()`, after reading `cat`, add: + +```ts +const lateral = (getEl('svg-editor-edit-lateral') as HTMLSelectElement).value +``` + +In the siblings loop, inside the non-opens-detail branch (where `data-anno-name-fr` etc. are set), add after the special attribute logic: + +```ts +if (lateral) { + s.setAttribute('data-anno-lateral', lateral) +} else { + s.removeAttribute('data-anno-lateral') +} +``` + +- [ ] **Step 6: Propagate lateral when creating new elements** + +In `addCircleAt()`, after setting `data-anno-special` on both `hit` and `vis`, add for each: + +```ts +if (CATEGORIES[cat]?.lateral) hit.setAttribute('data-anno-lateral', CATEGORIES[cat].lateral!) +``` + +Wait — categories don't carry lateral. Lateral is per-element, not per-category. New elements start as unpaired (no attribute). The user sets it via the edit panel. No change needed for addCircleAt/finalizePolygon. + +- [ ] **Step 7: Run typecheck and i18n test** + +Run: `pnpm typecheck && pnpm test:run -- tests/unit/i18n.dicts.test.ts` +Expected: No errors, i18n parity PASS + +- [ ] **Step 8: Commit** + +```bash +git add src/app/routes/SvgEditorRoute.tsx src/i18n/fr.ts src/i18n/en.ts +git commit -m "feat(editor): add laterality dropdown to SVG editor" +``` + +--- + +### Task 9: Documentation — Update ANATOMY-SVG-CONVENTION.md + +**Files:** +- Modify: `docs/ANATOMY-SVG-CONVENTION.md` + +- [ ] **Step 1: Add data-anno-lateral to optional attributes table** + +In the "Optional data attributes" table, add a row: + +```markdown +| `data-anno-lateral` | `string` | Laterality hint: `bilateral` (zone has left/right instances, e.g. knee) or `unpaired` (no laterality). Default when absent: `unpaired`. Used by the report editor to prompt side selection on bilateral zones. | +``` + +- [ ] **Step 2: Commit** + +```bash +git add docs/ANATOMY-SVG-CONVENTION.md +git commit -m "docs(anatomy): document data-anno-lateral attribute" +``` + +--- + +### Task 10: Full Verification + +- [ ] **Step 1: Run full test suite** + +Run: `pnpm test:run` +Expected: ALL PASS + +- [ ] **Step 2: Run typecheck** + +Run: `pnpm typecheck` +Expected: No errors + +- [ ] **Step 3: Run lint** + +Run: `pnpm lint` +Expected: No errors + +- [ ] **Step 4: Build** + +Run: `pnpm build` +Expected: Build succeeds