ESP Design Platform

Survey grid (MD · Inc · Azi) ─► backend (average tangential)
  ─► trajectory (TVD · North · East)
       ├─► 2D charts: MD vs TVD · MD vs Angle · top view · isometric
       └─► WellboreThree (React Three Fiber) ◄─ pump setting depth
              └─► toDataURL ─► A4 report attachment

• Coordinates: East → +X, TVD → −Y, North → +Z, at 1 unit = 1,000 ft
• Well path built as a CatmullRomCurve3 → TubeGeometry with an emissive material
• Bounding box computed from the data: 6 translucent planes, 12 edges, and a grid on each plane, memoized
• Billboard labels for surface, max TVD, compass points, and PSD, outlined to stay readable over the grid
• Tooltips rendered through drei <Html> into the regular DOM so they can use theme CSS variables
• PSD marker with its own index so its selection never collides with survey stations
• OrbitControls with damping and zoom limits, a GizmoHelper, and fog for depth

• In useFrame, the distance from the camera to the bounding-box center drives station scale
• Far away only the tube shows; zooming in grows the stations smoothly until each one is clickable

• Twin palettes (PALETTES.light / PALETTES.dark) with 26 tokens: colors, opacities, and light intensities
• Selected from a Zustand theme store: a module-level store is still readable inside <Canvas>, which runs in a separate React reconciler where regular Context doesn't reach

• Chart.js and Three.js canvases captured with toDataURL()
• Recharts SVG serialized and rasterized at 3× for 300 dpi print, with computed styles inlined first because an SVG inside <img> can't read page CSS variables
• preserveDrawingBuffer is optional: off in the workflow, on only in the report snapshot modal, so the workflow keeps driver optimizations
• Snapshot canvas ratio derived from A4 page geometry (card size after padding, header, and gap), so the PNG fills the report card with no empty bands

Input ─blur─► 1 Client     number format, empty fields
             2 Server     domain rules via per-field upsert
                ├─ error {key, detail} ─► mapped to dotted field path
                └─ success ─► 3 Step status   can_continue → Next button
                               4 Calculations  results marked stale on change
                               5 Cross-step    /impact → equipment cascade
                                  └─► Equipment selection summary

• Every field saves on blur or Enter through an upsert endpoint; no giant Save button validating 30 fields at once
• Errors extracted from several response shapes and mapped to dotted paths like perforation.top, so the message appears right under the wrong input
• Per-step error stores in Zustand; editing a field clears its own error, a successful save clears the step
• Technical backend messages normalized into actionable sentences
• A pending-save counter blocks leaving a step before the last blur has saved
• Two-stage confirmation for risky changes, such as a PSD that may cause pump-off; declining restores the value and flags the field

• Static (Pr / static fluid level) and flowing (Pwf / flowing fluid level / test rate) groups compared separately
• Changed group marked stale and its result hidden until the engineer recalculates
• Switching the IPR model deliberately doesn't invalidate results, since it doesn't change test data
• Composite model selectable only when bubble-point conditions recommend it
• Uncalculated drafts kept in sessionStorage so they survive navigation

• EquipmentSelectionGuard mounted once on the workflow canvas, active only on the four upstream routes
• Triggered when all mutations on the page settle (useIsMutating), not by hooks in each form, so a new save path can't slip through
• Calls /impact, then fires the cascade endpoint from the right point (pump → intake → protector → motor → cable → MLE) and shows what was released

• Design criteria (rate, TDH, target Q, fluid SG, GVF) grouped with status colors; GVF has its own explained scale
• Shares query keys with the selection forms, so recommendations stay filled after the form unmounts, with no extra requests
• One motor catalog endpoint stores max_motor_load as a side effect; the summary calls it without that parameter so reading never writes