Purged from docs/superpowers by the gitflow finish of step 1 (BDR-065); that path is purged at every finish, so the records live under docs/history/superpowers/ instead. References updated.
18 KiB
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:
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:
export const LateralSideSchema = z.enum(['left', 'right'])
export type LateralSide = z.infer<typeof LateralSideSchema>
Add side to ObservationZoneSchema:
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
lateralfield to Bone interface
In src/anatomy/types.ts, add to Bone interface after special?:
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
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:
<circle data-anno-id="point-knee" data-anno-name-fr="Genou" data-anno-name-en="Knee"
data-anno-category="articulations" data-anno-lateral="bilateral" />
Add tests:
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:
const lateral = el.getAttribute('data-anno-lateral') as
| 'bilateral'
| 'unpaired'
| undefined ?? undefined
In the else branch (new Bone creation), add lateral to the object:
map.set(id, {
id,
fr,
en,
category,
opensDetail,
special,
lateral,
els: [el],
})
In the existing merge branch, add:
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
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:
// 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:
// 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
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:
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 (
<Dialog open={open} onClose={onClose} title={title} size="sm">
<div className="space-y-4">
<p className="text-sm text-[var(--color-ink-muted)]">
{t('lateral.which_side')}
</p>
<div className="flex gap-3 justify-center">
<Button
variant={hasLeft ? 'ghost' : 'default'}
disabled={hasLeft}
onClick={() => onSelect(['left'])}
>
{t('lateral.left')}
</Button>
<Button
variant={hasRight ? 'ghost' : 'default'}
disabled={hasRight}
onClick={() => onSelect(['right'])}
>
{t('lateral.right')}
</Button>
<Button
variant={hasLeft && hasRight ? 'ghost' : 'default'}
disabled={hasLeft && hasRight}
onClick={() => {
const sides: LateralSide[] = []
if (!hasLeft) sides.push('left')
if (!hasRight) sides.push('right')
onSelect(sides)
}}
>
{t('lateral.both')}
</Button>
</div>
</div>
</Dialog>
)
}
- Step 2: Run typecheck
Run: pnpm typecheck
Expected: No errors
- Step 3: Commit
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:
import LateralityPicker from '@/components/observation/LateralityPicker'
import type { LateralSide } from '@/domain/schema/observation'
Add state after vertebraTarget state:
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:
if (bone.lateral === 'bilateral') {
setLateralTarget({
boneId,
...(detailSourceId ? { detailSourceId } : {}),
})
return
}
- Step 3: Add LateralityPicker to JSX
Add before the closing </main> tag, after the VertebraPicker block:
{lateralTarget && activeObs && (
<LateralityPicker
open
onClose={() => 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:
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
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:
function describeZone(
z: ObservationZone,
bones: Map<string, Bone>,
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:
{describeZone(z, bones, locale, t)}
- Step 3: Run typecheck
Run: pnpm typecheck
Expected: No errors
- Step 4: Commit
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:
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
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:
'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:
'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 <select>, add:
<label>{t('svg_editor.lateral')}</label>
<select id="svg-editor-edit-lateral">
<option value="">{t('svg_editor.lateral_unpaired')}</option>
<option value="bilateral">{t('svg_editor.lateral_bilateral')}</option>
</select>
- Step 3: Wire up event listener in initSvgEditor
In setupGlobalListeners(), add the lateral select to the change listener array:
;['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:
;(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:
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:
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:
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
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:
| `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
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