Files
faunosteo/docs/history/superpowers/plans/2026-05-23-laterality-support.md
T
bchanot 02052f3622 docs(docs): restore 2026-05 design specs and plans under docs/history
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.
2026-10-08 21:51:13 +02:00

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 lateral field 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