Files
faunosteo/docs/superpowers/specs/2026-05-23-laterality-support-design.md
T
Bastien ChanotandClaude Opus 4.6 880de17dbe docs(specs): add laterality support design spec
Defines per-zone bilateral/unpaired SVG attribute, ObservationZone.side
schema field, LateralityPicker UI flow, and SVG editor integration.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-05-23 22:09:50 +02:00

7.6 KiB

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

export const LateralSideSchema = z.enum(['left', 'right'])
export type LateralSide = z.infer<typeof LateralSideSchema>

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

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:

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:

<label>Latéralité / Laterality</label>
<select id="svg-editor-edit-lateral">
  <option value="">Impair / Unpaired</option>
  <option value="bilateral">Bilatéral / Bilateral</option>
</select>

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