Files
faunosteo/docs/superpowers/specs/2026-05-22-pathology-editor-design.md
T
Bastien ChanotandClaude Opus 4.6 2d6ed809e2 chore: rename Zoosteo → Faunosteo across entire project
Brand strings, config defaults, i18n dicts, PDF attachment metadata,
HTML titles, Docker container name, package name, repo URLs, deploy
paths, and all documentation updated. Git remote switched to
faunosteo.git. Domain URLs (zoosteo.fr) preserved — DNS update is
separate. 155/155 tests green.

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

13 KiB

Pathology Editor — Design Spec

Date: 2026-05-22 Status: Draft Scope: Standalone HTML tool for editing species pathology JSON via SVG-based zone selection


1. Overview

Single-file standalone HTML tool (pathology-editor.html at project root) that lets users visually select anatomical zones on an SVG and edit the corresponding pathology tree in the species JSON. Same architectural pattern as editor.html (SVG editor): vanilla JS/CSS, no build step, no dependencies.

The tool never modifies source files. It works on an in-memory copy and exports a downloadable JSON file.


2. Layout

Two-panel horizontal layout, identical to SVG editor:

Panel Width Content
Left (canvas) flex: 1 SVG display, click-to-select zones
Right (sidebar) 380px Source picker → zone info → tree editor → export

Sidebar is scrollable. Canvas contains the SVG with auto-viewBox (same logic as editor.html).


3. Source Selection

On launch, sidebar shows source picker with two modes:

3a. Pre-wired list

Two-step selection:

  1. Species dropdown — lists registered species (MVP: "Cheval" only)
  2. View dropdown — lists available SVGs for selected species

Hardcoded config (easily extensible):

const SPECIES_CONFIG = [
  {
    id: 'equine',
    label: 'Cheval',
    jsonPath: '/species/equine/pathologies.json',
    views: [
      { label: 'Corps complet', svgPath: '/species/equine/Horse.svg' },
      { label: 'Tête (détail)', svgPath: '/species/equine/Horse_head.svg' },
    ],
  },
];

Pre-requisite: pathologies.json must be copied (or symlinked) to public/species/equine/pathologies.json so it's accessible via HTTP when served statically. The source of truth remains src/domain/species/equine/pathologies.json — the public copy is read-only for the editor.

"Charger" button fetches both files. If either fetch fails, show error with HTTP status.

All views of a species share the same JSON. Switching view reloads SVG only, keeps JSON state.

3b. Manual upload

Two file inputs:

  • "Fichier SVG" — accepts .svg
  • "Fichier JSON" — accepts .json

Both required. If only one provided, "Charger" button disabled with message: "Les deux fichiers (SVG et JSON) sont obligatoires."

Files read via FileReader as UTF-8 text.

Source switch

After loading, sidebar transitions to editing mode. A "Changer de source" link at the top returns to the source picker. Switching source discards current edits (with confirmation if modifications exist).


4. SVG Display

Loading

Parse SVG text, inject into canvas container as inline SVG. Auto-viewBox: if viewBox attribute missing, compute from SVG width/height or getBBox() and set it (same as editor.html pattern).

Zone detection

Walk all SVG elements. An element is a clickable zone if it has data-anno-id AND at least one of data-anno-name-fr or data-anno-name-en.

Interaction

  • Hover: subtle opacity/highlight change on annotated elements
  • Click: select zone (see section 5)
  • Selected state: distinct highlight color (blue outline or fill overlay), persists until another zone clicked

No editing of SVG content. SVG is read-only visual selector.


5. Zone Selection Logic

When user clicks an annotated SVG element:

Step 1 — Read SVG attributes

Extract from clicked element (walk up DOM to find data-anno-id parent if needed):

  • data-anno-id
  • data-anno-name-fr
  • data-anno-name-en
  • data-anno-opens-detail (if present)
  • data-anno-special (if present)

Step 2 — Special attribute handling

Attribute Behavior
data-anno-opens-detail present Show info message: "Zone de navigation vers un SVG de détail — non éditable ici. Chargez le SVG de détail pour éditer ses zones." Do NOT open tree editor.
data-anno-special present (e.g., vertebral-precision) Treat as normal editable zone. special attribute is irrelevant to pathology editing.

Step 3 — Fuzzy match to JSON zone

Match SVG name_fr/name_en against zones[*].name_fr/name_en in loaded JSON.

Matching algorithm (port from src/lib/zoneMatch.ts):

  1. Normalize both strings: str.normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase().replace(/[^a-z0-9]/g, '')
  2. Score pairs (SVG label vs JSON zone label):
    • Exact match → score 0
    • Substring containment → score 1
    • Levenshtein distance ≤ 25% of max length (min 2 edits) → score 2 + distance
  3. Priority: EN-on-EN first, FR-on-FR second, cross-language last
  4. Take lowest score. If no candidate below threshold → no match.

Step 4 — Result

Result Sidebar action
Match found Select zone, show tree editor for matched zone
No match Show "Aucune zone correspondante dans le JSON" + "Créer cette zone" button

Creating a new zone

"Créer cette zone" pre-fills:

  • id: generated from name_en (fallback name_fr) → kebab-case (see section 7 for ID generation)
  • name_fr: from SVG data-anno-name-fr
  • name_en: from SVG data-anno-name-en
  • categories: empty array []

Zone added to in-memory JSON zones object immediately.


6. Pathology Tree Editor

Zone header

When a zone is selected, sidebar shows:

  • Zone name: name_fr / name_en (read-only display, not editable — zone names come from SVG)
  • Zone ID: displayed as badge (read-only)
  • Zone stats: count of categories, total node count

Tree display

Recursive collapsible tree rendering all categories and their nested children:

📁 Dysfonctions ostéopathiques          [+ Ajouter enfant] [✏️] [🗑️]
  📁 Lésions de mobilité                [+ Ajouter enfant] [✏️] [🗑️]
    🔹 En flexion (rotation externe)    [✏️] [🗑️]
    🔹 En extension (rotation interne)  [✏️] [🗑️]
  📁 Lésions intra-osseuses             [+ Ajouter enfant] [✏️] [🗑️]
    🔹 Compression intra-osseuse        [✏️] [🗑️]
📁 Observations / motifs de consultation [+ Ajouter enfant] [✏️] [🗑️]
  ...

Visual conventions:

  • 📁 = node with children (category/intermediate) — collapsible
  • 🔹 = leaf node (no children or empty children) — selectable by practitioner in main app
  • Indentation: 20px per level
  • Collapse state: all collapsed by default, expand on click

Node operations

Edit node (✏️)

Click edit icon → inline form expands below the node:

Field Type Required
name_fr text input yes
name_en text input yes
description_fr textarea no
description_en textarea no
requires_vet_referral checkbox no (default false)
Sources repeatable row group no

Each source row:

  • type: select dropdown (manual, journal, database, web)
  • citation: text input
  • url: text input (optional)
  • [Remove source] button

[Add source] button below sources list.

"Enregistrer" saves changes to in-memory JSON. "Annuler" discards form.

When saving, id is NOT editable — it was set at creation and remains stable.

Add child node (+ Ajouter enfant)

Available on any node. Opens inline form (same as edit) for the new child.

On save:

  • New node inserted as last child of parent
  • id auto-generated from name_en (see section 7)
  • If parent was a leaf (no children), it becomes a category (gets children array)

Add root category (+ Ajouter catégorie)

Button at bottom of zone's tree. Creates new top-level category in categories array.

Delete node (🗑️)

Click delete → confirmation dialog: "Supprimer « {name_fr} » et tous ses enfants ({N} nœuds) ?"

On confirm: remove node and entire subtree from parent's children (or from zone's categories if root-level).

No reordering

Drag-and-drop reordering excluded from this version. Node order matches JSON array order.


7. ID Generation

Auto-generate id for new nodes and zones:

function generateId(nameEn, nameFr, existingSiblingIds) {
  const source = (nameEn || nameFr || 'node').trim();
  let slug = source
    .normalize('NFD')
    .replace(/[̀-ͯ]/g, '')  // strip accents
    .toLowerCase()
    .replace(/[^a-z0-9]+/g, '-')     // non-alnum → hyphen
    .replace(/^-|-$/g, '');           // trim leading/trailing hyphens

  if (!slug) slug = 'node';

  // Ensure uniqueness among siblings
  let candidate = slug;
  let counter = 2;
  while (existingSiblingIds.includes(candidate)) {
    candidate = `${slug}-${counter}`;
    counter++;
  }
  return candidate;
}

8. JSON Export

Trigger

"Télécharger JSON" button — always visible in sidebar header area, enabled once source is loaded.

Output

  • Full JSON object with all root fields preserved: schema_version, scope_disclaimer, species, zones
  • ALL zones included (modified + unmodified)
  • UTF-8 encoding, 2-space indentation
  • Filename: pathologies-{speciesId}-{YYYYMMDD-HHmmss}.json (or pathologies-custom-{timestamp}.json for manual uploads)

Implementation

const blob = new Blob(
  [JSON.stringify(jsonData, null, 2)],
  { type: 'application/json;charset=utf-8' }
);
const url = URL.createObjectURL(blob);
// trigger download via <a> element

Integrity rules

  • Never drop fields from nodes (even if empty/optional — omit only if truly absent)
  • Never reorder zone keys (use insertion order from original parse)
  • schema_version preserved as-is (no auto-bump)
  • Empty children: [] on a leaf is valid and preserved if originally present

9. Unsaved Changes Protection

Track modification state (dirty flag). When user attempts to:

  • Switch source → confirm dialog: "Des modifications non enregistrées seront perdues. Continuer ?"
  • Close/navigate away → beforeunload event handler

10. Error Handling

Scenario Behavior
SVG fetch fails (pre-wired) Show error: "Impossible de charger le SVG: {status}"
JSON fetch fails (pre-wired) Show error: "Impossible de charger le JSON: {status}"
JSON parse error Show error: "Le fichier JSON est invalide: {error.message}"
JSON missing required root fields Show error: "Structure JSON invalide: champ '{field}' manquant"
SVG has no annotated elements Show warning: "Aucun élément annoté (data-anno-*) trouvé dans ce SVG"
Uploaded file too large (>10MB) Show error: "Fichier trop volumineux (max 10 Mo)"

11. Styling

Consistent with editor.html aesthetic:

  • Dark header bar with tool title
  • White sidebar background, light gray canvas background
  • System font stack: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif
  • Buttons: solid background (blue primary, red destructive, gray secondary)
  • Inputs: bordered, rounded, consistent padding
  • Tree nodes: hover highlight, selected state with left border accent
  • Responsive: min-width 900px, below that show a "use larger screen" message

12. File Structure

Single file: pathology-editor.html at project root (same level as editor.html).

No external dependencies. All CSS inline in <style>. All JS inline in <script>.

Approximate structure:

<!DOCTYPE html>
<html lang="fr">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta name="robots" content="noindex,nofollow">
  <title>Faunosteo — Éditeur de pathologies</title>
  <style>/* all styles */</style>
</head>
<body>
  <header><!-- title bar --></header>
  <main>
    <div id="canvas"><!-- SVG container --></div>
    <aside id="sidebar"><!-- source picker / tree editor --></aside>
  </main>
  <script>/* all logic */</script>
</body>
</html>

13. Out of Scope

  • Node drag-and-drop reordering
  • Undo/redo history
  • Multi-zone selection
  • Zone name editing (names come from SVG, not JSON)
  • SVG modification or export
  • Schema version auto-bumping
  • Diff/merge between JSON versions
  • Integration as React route (standalone only)

14. Acceptance Criteria

  1. Pre-wired source loads SVG + JSON from local paths, displays SVG with clickable zones
  2. Manual upload accepts SVG + JSON files, rejects incomplete uploads
  3. Clicking annotated SVG zone matches to JSON zone via fuzzy matching
  4. Clicking data-anno-opens-detail zone shows navigation info, not tree editor
  5. Tree editor displays full recursive hierarchy for selected zone
  6. Can add node at any level (root category, intermediate, leaf)
  7. Can edit all node fields (name_fr, name_en, descriptions, vet referral, sources)
  8. Can delete node with confirmation, removes entire subtree
  9. New node IDs auto-generated as unique kebab-case slugs
  10. "Créer cette zone" works for SVG zones with no JSON match
  11. Downloaded JSON contains all zones (modified + unmodified) with root fields preserved
  12. Downloaded JSON is valid UTF-8 with 2-space indentation
  13. Unsaved changes trigger confirmation on source switch and page close
  14. All error scenarios show user-facing French messages