diff --git a/docs/superpowers/specs/2026-05-23-laterality-support-design.md b/docs/superpowers/specs/2026-05-23-laterality-support-design.md new file mode 100644 index 00000000..8748d2de --- /dev/null +++ b/docs/superpowers/specs/2026-05-23-laterality-support-design.md @@ -0,0 +1,234 @@ +# Laterality Support — Design Spec + +**Date**: 2026-05-23 +**Status**: Approved +**Approach**: A — per-zone SVG attribute + inline side picker + separate observation entries + +--- + +## Problem + +Anatomical zones have no laterality concept. A practitioner clicking "Genou" (knee) creates one observation zone without specifying left or right. Bilateral structures (knee, hip, shoulder) need side differentiation; midline/unpaired structures (spine, sternum) do not. + +## Solution Overview + +Three layers: +1. **SVG convention** — new `data-anno-lateral` attribute marks zones as bilateral or unpaired +2. **Report schema** — new `side` field on `ObservationZone` records which side +3. **UI** — LateralityPicker modal when clicking bilateral zones; badge display shows side + +Backward-compatible: missing attribute = unpaired, `side` field is optional. + +--- + +## 1. SVG Convention + +New optional attribute on annotated elements: + +| Attribute | Values | Default when absent | +|---|---|---| +| `data-anno-lateral` | `bilateral` \| `unpaired` | `unpaired` | + +- `bilateral`: zone has left and right instances (e.g. knee, hip, shoulder) +- `unpaired`: zone has no laterality (e.g. sternum, sacrum) or laterality is not relevant + +The parser reads and forwards this attribute like `data-anno-special` — optional, opaque string. The `Bone` interface gains a `lateral` field. + +### Validation + +- If present, value must be `bilateral` or `unpaired`. Any other value → `SvgConventionError`. +- If absent → treated as `unpaired` at the application level (not by the parser — parser sets `undefined`, app code defaults). + +### Doc update + +`docs/ANATOMY-SVG-CONVENTION.md` gains a row in the optional attributes table. + +--- + +## 2. Schema Changes + +### ObservationZone + +```ts +export const LateralSideSchema = z.enum(['left', 'right']) +export type LateralSide = z.infer + +export const ObservationZoneSchema = z.object({ + boneId: z.string().min(1), + detailSourceId: z.string().optional(), + vertebrae: z.array(VertebraSchema).optional(), + side: LateralSideSchema.optional(), +}) +``` + +Rules: +- `side` is present only when the bone is bilateral +- Unpaired zones never carry `side` +- Two zones with same `boneId` but different `side` values are valid (left knee + right knee in same observation) +- No schema version bump — `side` is additive and optional; old reports parse cleanly + +### Bone interface + +```ts +export interface Bone { + id: string + fr: string + en: string + category: BoneCategory + opensDetail?: string + special?: string + lateral?: 'bilateral' | 'unpaired' // NEW + els: Element[] +} +``` + +--- + +## 3. SVG Parser Changes + +`parseSvgBones()` reads `data-anno-lateral` from SVG elements and sets `Bone.lateral`: + +```ts +const lateral = el.getAttribute('data-anno-lateral') ?? undefined +``` + +Merging logic (multiple elements sharing same `data-anno-id`): first non-undefined `lateral` value wins, same pattern as `special` and `opensDetail`. + +No validation of the value in the parser — validation happens at the convention level if desired. The parser is permissive (accepts any string); the application layer checks for known values. + +--- + +## 4. UX Flow — LateralityPicker + +### Trigger + +When practitioner clicks a bilateral zone (`bone.lateral === 'bilateral'`): + +1. **LateralityPicker** modal opens with three options: + - Gauche / Left + - Droite / Right + - Les deux / Both + +2. Selection behavior: + - "Left" → adds `ObservationZone { boneId, side: 'left' }` + - "Right" → adds `ObservationZone { boneId, side: 'right' }` + - "Both" → adds two entries: `{ boneId, side: 'left' }` + `{ boneId, side: 'right' }` + +3. Duplicate prevention: if a zone with the same `boneId + side + detailSourceId` already exists in the active observation, skip silently. + +4. Re-click behavior: if the zone already has one or both sides in the observation, the picker opens again so the user can add the missing side. If both sides already exist, clicking removes both (toggle off — matching current toggle behavior for unpaired zones). + +### Component + +`src/components/observation/LateralityPicker.tsx` + +- Reuses `Dialog` component for modal shell +- Three `Button` components for the choices +- Receives `onSelect(sides: LateralSide[])` callback +- Small, focused modal — not a full-screen overlay + +### Integration point + +`EditorRoute.onZoneClick()` — after the `opensDetail` check and `vertebral-precision` check, before the toggle logic: + +``` +if bone.lateral === 'bilateral' → open LateralityPicker + → onSelect callback adds zone(s) with side +else → existing toggle logic (unpaired zone) +``` + +--- + +## 5. Zone Badge Display + +In `ObservationCard`, the `describeZone()` function appends a side suffix for bilateral zones: + +- FR: `Genou (G)` for left, `Genou (D)` for right +- EN: `Knee (L)` for left, `Knee (R)` for right + +The short labels come from i18n keys `lateral.left_short` / `lateral.right_short`. + +Format: `{zoneName} ({sideShort})` + +--- + +## 6. SVG Editor Changes + +In the edit panel (`svg-editor-osteo-fields`), a new select dropdown after the category select: + +```html + + +``` + +Behavior: +- Reads `data-anno-lateral` from selected element on select +- Writes `data-anno-lateral` attribute on change (removes attribute if "unpaired" selected) +- Propagates to sibling elements sharing same `data-anno-id` (same pattern as category/name propagation) +- Exported SVG includes the attribute + +### Backward compatibility + +Existing SVGs loaded in the editor: zones without `data-anno-lateral` show "Impair" (default). User can change to "Bilatéral" and re-export. + +--- + +## 7. PDF Output + +Zone labels in PDF include side when present: + +- FR: `Genou (Gauche)`, `Genou (Droit)` +- EN: `Knee (Left)`, `Knee (Right)` + +Uses full side name (not abbreviation) for PDF clarity. + +The `describeZone()` helper used in PDF rendering checks `zone.side` and appends the localized label. + +--- + +## 8. i18n Keys + +New keys in `src/i18n/fr.ts` and `src/i18n/en.ts`: + +| Key | FR | EN | +|---|---|---| +| `lateral.which_side` | Quel côté ? | Which side? | +| `lateral.left` | Gauche | Left | +| `lateral.right` | Droite | Right | +| `lateral.both` | Les deux | Both | +| `lateral.left_short` | G | L | +| `lateral.right_short` | D | R | +| `lateral.bilateral` | Bilatéral | Bilateral | +| `lateral.unpaired` | Impair | Unpaired | + +--- + +## 9. Scope Exclusions + +- No changes to findings tree — findings are zone-level, same pathologies apply to both sides +- No SVG visual differentiation between left/right — same zone highlights for both sides +- No auto-detection of laterality from zone names +- No report schema version bump — additive optional field +- No changes to PDF attachment format — JSON includes `side` field naturally + +--- + +## 10. Files Touched + +| File | Change | +|---|---| +| `src/anatomy/types.ts` | Add `lateral` to `Bone` interface | +| `src/anatomy/svgConvention.ts` | Read `data-anno-lateral` in parser | +| `src/domain/schema/observation.ts` | Add `LateralSideSchema`, `side` field | +| `src/components/observation/LateralityPicker.tsx` | NEW — modal component | +| `src/components/observation/ObservationCard.tsx` | Update `describeZone()` | +| `src/app/routes/EditorRoute.tsx` | Integrate LateralityPicker in click flow | +| `src/app/routes/SvgEditorRoute.tsx` | Add lateral dropdown in edit panel | +| `src/i18n/fr.ts` | Add lateral keys | +| `src/i18n/en.ts` | Add lateral keys | +| `src/pdf/render/observationPage.ts` | Update zone label rendering | +| `docs/ANATOMY-SVG-CONVENTION.md` | Document `data-anno-lateral` | +| `tests/unit/observation.test.ts` | Test side field parsing |