# 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