jFdZddlmZddlZddlmZddlmZdZdZ dZ ed Gd d Z dd Z ddZ ddZddZddZGddZy)uA The guided EXCURSION — a continuous narrated flight over the venue's surroundings. Filler for the pauses in a broadcast day: the camera leaves the course, glides past the places that stand around the water while a guide speaks about them, and comes home — a small scenic flight, never a slideshow. The one rule that shapes everything here is that the aim point is ALWAYS MOVING (Ulf 2026-08-10): the tour never parks at a stop; a long narration slows the leg that carries it rather than halting the flight. This module is pure — no clock, no store, no server (the `cruise_tour.py` discipline). It emits one `tour_poi` beat per second with an interpolated aim point; the renderer's one critically damped camera spring (scene.js `_driveCamera`, retuned to TOUR) turns that 1 Hz stair-step into smooth flight, trailing the aim by design. Three beat fields beyond the landmark tour's: * `poiBearingDeg` — the TRUE compass bearing from the aim point to where the camera should stand: the travel bearing + 180°, so the camera flies BEHIND the aim looking forward along the route. Blended by shortest delta over a few seconds at leg joins (angles wrap — root CLAUDE.md); the renderer converts to its scene azimuth, this module never knows scene axes. * `poiSpeedMps` — present only on the recall home-run: raises the renderer's spring cap for the express return (with headroom over the aim's own ground speed, or the camera could never close on it). * `focusUntilSec = t + 3` — each beat expires almost immediately, so a stalled feed releases the camera instead of pinning it to the last aim point for ever. WHAT it flies to is event data (`venue.tourSites`, published beside `venue.landmarks`), never authored here: a flat catalogue of `{name, lat, lon, line?, tour?}`. `line` optional — an entry without one is a shape point that bends the path silently. Entries sharing a `tour` id form a STORY ROUTE (the Vasa story, the Lidingö Runt loop): an indivisible, ordered unit the planner flies whole, chapters in listed order, never re-sorted and never interleaved with other sites. Eligibility is COMPUTED, never tagged: a unit qualifies when every point lies within `radius_m` of home (None = unbounded — the cruise day's whole catalogue) and its flight time fits the `excursion_target_s` budget. On a race day the caller derives a conservative radius from the return knobs (`recall_speed_mps * recall_budget_s`). The broadcast's ARM is now both recall and immediate programme hand-over, so the venue/course opening re-establishes the picture without delaying the countdown; keeping the waiting flight local makes that transition visually coherent. `recall()` remains the graceful return for callers that have advance notice: the remaining route is replaced by a single home leg while narration already playing is allowed to finish. ) annotationsN) dataclass)_speech_secondsg?T)frozenceZdZUdZdZded<dZded<dZded<d Zded <d Z ded <dddd d d Z e ddZ ddZ y)ExcursionConfiguThe excursion's knobs. Defaults here; an event overrides via the same `presentation.cruise` (camelCase) block the tour's other knobs ride — event data, never a renderer constant.intexcursion_speed_mpsexcursion_standoff_miXexcursion_target_sFrecall_speed_mps<recall_budget_s)excursionSpeedMpsexcursionStandoffMexcursionTargetSrecallSpeedMps recallBudgetSc(i}|jjD]l\}}|xsij|}t|tt fs2t|t rCtj|sY|dk\s_t |||<n|di|S)u`presentation.cruise` → a config; unknown keys ignored, non-numeric values ignored (a malformed knob falls back to the default rather than crashing the show — `CruiseConfig`).r) _KEYSitemsget isinstancer floatboolmathisfinite)clsblockkwargswire field_namevs >B ::td{b(4$;)*C DDr,ctjtj||zdz }tjtj||z |z||z dzS)zDTRUE compass bearing from point 0 to point 1 (0 = north, 90 = east).rv@)r"r;r<degreesatan2r>s r* _bearing_degrI`sN $,,t q01 2B << D4K2#5td{C Du LLr,c||z dzdzdz S)uVShortest signed delta a→b in degrees — bearings live on a circle (root CLAUDE.md).g@rFf@r)abs r* _wrap_deltarNfs UU]e #u ,,r,cg}|xsgD]}t|ts|jd|jd}}t|ttfr@t|ttfr*t j |rt j |st|jdxsdjs|j||S)uEntries a camera can actually be aimed at: finite lat/lon and a non-empty name (the plate reads the name of the site being approached, a nameless aim point would blank it). Anything else is dropped — an invalid entry must never reach the geometry (the sensor-values rule).latlonname) rdictrr r r"r#strstripappend)sitesoutsrPrQs r* _valid_sitesr[ms C [b !T" 55<uS3e -*S3,2OMM#&4==+= 155=&B'--/  1   Jr,cg}i}|D]v}t|jdxsdj}|s|j|gD||vr||j|]|g||<|j||x|S)zRoute units in catalogue order: a free site is its own unit; sites sharing a `tour` id form ONE ordered unit (chapters in listed order), seated where its first chapter appears.tourrS)rUrrVrW)rXunitsby_tourrZtids r*_unitsras!E%'G '!%%-%2&,,. LL!  G^ CL   "3GCL LL &' Lr,ceZdZdZddddd ddZeddZeddZddZddZ dd Z ddd Z dd Z e dd Zdd ZddZddZy) ExcursionaOne planner/flyer, owned by a driver (the cruise scheduler on its excursion laps, the waiting picture directly). `begin(t)` plans a route and starts flying; `tick(t)` returns this second's beat; `recall(t)` turns for home; `update_sites` swaps the catalogue live.N)rXcentreradius_m home_namec.||_t||_|duxr"t|dk(xrt d|D}|rt |dt |dfnd|_||_||_d|_ g|_ d|_ d|_ d|_ y)Nrc3vK|]1}t|ttfxrtj|3ywN)rr r r"r#).0cs r* z%Excursion.__init__..s-^RSZC<8MT]]1=MM^s79rr.F)cfgr[rXlenallr rdrerf_n_legs_i_leg_t0 _recalled)r1rmrXrdrerf ok_centres r*__init__zExcursion.__init__s!%( 4'_CK1,<_^W]^^ >GuVAY'vay)9:T   "!# " r,c|jduSrirrr0s r*flyingzExcursion.flyingswwd""r,c|jduSrirxr0s r*donezExcursion.donesww$r,cT|jduxrt|jS)uIs there anything to fly at all — a home point and at least one unit that fits the radius AND the time budget? (What `cruise_tour` asks before scheduling an excursion lap.)N)rdr! _plan_router0s r* availablezExcursion.availables&{{$&C40@0@0B+CCr,cRt|}|r|sy||jk7}||_|S)uSwap the catalogue mid-broadcast (an operator — or Claude — republished the event). Returns whether anything changed. A publish whose every entry is invalid keeps the working catalogue (hold-last: a malformed read must not blank a running tour), while a deliberate EMPTY list is honoured — that is how the tour is retired by data. Legs already planned keep flying; the next `begin()` sees the new list.F)r[rX)r1rXfreshchangeds r* update_siteszExcursion.update_sitess0 U# 4::% r,c$td|jj}d||}}}|D]d}t|||d|d|z } t |j dxsd} |t| | rt | tzndz }|d|d}}f|S)uEstimated flying time through a unit from a given point — each leg the LONGER of its travel time and its narration (a long line slows the leg, never stops it).r.rPrQlinerS)r/rmr rDrUrr SAY_MARGIN_S) r1unitfrom_latfrom_lonspeedtotallalorZtravelrs r* _unit_time_szExcursion._unit_time_ssAtxx334Xx2r (ARQuXqx85@FquuV}*+D S4/$"7,"FUXY YEuXqxB  (  r,c jgSj\ tj}j%|Dcgc]}t fd|Dr|}}|sgSt dj j}| jn|t|z}||d|d|z}g}d} c|r|s|dnt|fd} j| } t| dd | dd  |z } || z| zj jkr9|j| |j| || z }| dd | dd cn|s|j!dn |S|r|Scc}w) u9The deterministic route for excursion `n`: eligible units (every point within the radius), the starting unit rotated by `n`, then nearest-neighbour among the rest — a story route always whole, in chapter order. Units are added only while the running total plus the flight home fits `excursion_target_s`; a unit too long for the whole budget simply never flies until an event raises the budget. No randomness anywhere — the same catalogue and the same counter always plan the same route (the scheduler is pure and replayable).Nc3`K|]%}t|d|djk'yw)rPrQN)rDre)rjrZclatclonr1s r*rlz(Excursion._plan_route..s.`YZGD$%!E(Ct}}T`s+.r.rrc8t|dd|ddS)NrrPrQ)rD)urPrQs r*z'Excursion._plan_route..s"73QqT%[!A$u++Vr,)keyrPrQ)rdrarXreror/rmr rprnminrrDrremoverWpop)r1nr^rrkpoolrouteusednxtt_unitt_homerrrPrQs` @@@@r*r}zExcursion._plan_routes ;; I[[ dtzz" == $ %b1`^_``bEbIAtxx334 TWWqCJ 6QRy5!9$"$S"'47t!VW &&sC5FSWU^SWU^T4H5PFf}v%)D)DD C  S!r75>3r75>S   3bsE;cd|_|j}|xjdz c_|r |jgdc|_|_y|j\}}t d|jj}g||}}}|D cgc] } | D]} |  c} } D]a} |j|j||| d| d|t| dt| jdxsd | d| d}}c|j|j||||||jd |d t|c|_|_|_ycc} } w) uPlan the next excursion and start flying at second `t` (nothing eligible → immediately `done`, the caller falls back to its ordinary programme).Fr.NrPrQrRrrSrRrr)rtr}rprdrqrrr/rmr rW_legrUrrfr rs) r1trrrrlegsrrrrZsites r*beginzExcursion.beginsG  " 1  +"$d DJ [[ dAtxx3344"b %11q1!Q1Q1 .D KK "b$u+tE{E'*4<'8s488FCSCYWY?Z"\ ]%[$u+B . DIIb"dD%dnnSUIVW,0!SV) DGT\ 2sEct||||}|rt|tznd}tdt j t||z |} ||||| t ||||||d|rtd| |z d Sdd S)Nrr.F) r?r@rArBdur_sbearingrRrsaidsay_at)rDrrr/r"ceilrI) r?r@rArBrrRrdistspeechdurs r*rzExcursion._leg stT4.9=&51!TYYs4%<89:dD$dD$)MdE26#av. B B=A B Br,c 6|jgSt|}|j|j}||jz }||dk\rt||dz}|xjdz c_||z |_|jt |jk\r d|_gS|j|j}||dk\rt||dz }|dddd|d|d |dz |zz|d |d |d z |zzd |j j t|j|d|d zd }|dr|d|d<|jr3ttd|j jtz|d<|dr|ds||dxsdk\r d|d<|d|d<|gS)uThe beat for second `t`: the aim point moved along the route — EVERY tick, never stationary. Empty once the route is flown (and `done` turns true).Nrr.tour_poi structureleadz boat-featurer?rAr@rB)rPrQ) tSectype claimClasscommentaryRoleshotTypepoipoiDistM poiBearingDeg focusUntilSecrR poiSpeedMpsrrrrTtext) rrr rqrsrnrmrround_camera_bearingrtr/rRECALL_CAP_FACTOR)r1rlegelapsedfbeats r*tickzExcursion.ticks 77?I Fjj!dll"W% s7| #G GGqLGw;DLww#djj/) **TWW%CW% c'l ":["(n"6{c&kCK.G1-LL"6{c&kCK.G1-LLN HH99!&t';';G'Da!H!"Q ( v;v;DL >>"%c!TXX-F-F&GJ[&["\D  v;s6{w3x=;MA/NCKv;DLv r,c|j|j}|ddzdz}|jdk(s |tk\r|S|j|jdz ddzdz}|t|||tz zzdzS)uCompass bearing aim→camera: behind the aim along the travel direction, blended by the SHORTEST delta over the first `BLEND_S` of a leg (a turn banks; it never whips the long way round the circle).rrKrFrr.)rqrrBLEND_SrN)r1rrbehindprevs r*rzExcursion._camera_bearing9sjj!i.5(E1 77a<7g-M 477Q;' 2U:eC{40Gg4EFF%OOr,c @|j|js |jyt|}|j|j}t dt d||jz |dz }|d|d|dz |zz}|d|d|dz |zz}t d |jj}|j|||jd|jd ||jd }t||g|_d |c|_|_d |_y) zA race was armed (T-4): drop the rest of the route and fly straight home at the recall speed. The narration already playing is left to finish (no beat retracts a line); no NEW line is spoken. Idempotent, and a no-op when not flying.Ng?rrr?rAr@rBr.rSrT) rrrtrdr rqrr/rsrmrrrfrT)r1rrrrPrQrhomes r*recallzExcursion.recallDs 77?dnn 0C  Fjj! SA ,-G < =&kS[3v;6!;;&kS[3v;6!;;Atxx001yyc4;;q>4;;q>5"nn273i& !1r,) rmr rX list | Nonerdztuple[float, float] | Nonerez float | Nonerf str | Noner3None)r3r!)rXrr3r!)r list[dict]rr rr r3r ri)rz int | Noner3list[list[dict]])rr r3r)r?r r@r rAr rBr rr rRrrrUr3rT)rr r3r)rr r3r )r4r5r6r7rvpropertyryr{r~rrr}r staticmethodrrrrrr,r*rcrcs[FJ6:UY)-3FR&26&##D  %N<& B B%( B-1 B BB Pr,rc) r?r r@r rAr rBr r3r )rLr rMr r3r )rXrr3r)rXrr3r)r7 __future__rr" dataclassesr cruise_tourrrrrr rDrIrNr[rarcrr,r*rsv%L# !'   $SSSDE M -$"EEr,