ɰSjn4UdZddlmZddlZddlZddlZddlZddlZddlm Z ddl m Z ddl m Z mZmZmZmZmZejeZdZdRd Zdd dSdZdTdZdZdUdZe ddVdZe ddWd!Zeeed"dXd%ZdYd'ZdZd)Z d*Z!dZ"dZ#d+Z$d[d.Z%ddd/d\d3Z&d4Z'd5Z(d6e)d7<d]d9Z*d^d;Z+d_d?Z,d`d@Z-ddd/d\dAZ.dRdBZ/dCZ0e1e1e2e2e2e2fe1e2e2e2e2ffZ3dadFZ4dbdGZ5GdHdIZ6de dJddKdcdQZ7dS)du)Decode a pet spritesheet and encode frames for a terminal. Shared by the base CLI (writes the escape bytes to its own stdout) and the TUI (``tui_gateway`` ships the encoded bytes to Ink, which writes them) so the decode + capability-detection + protocol-encoding logic exists exactly once. Supported output modes, in fidelity order: - ``kitty`` — the kitty graphics protocol (kitty, Ghostty, WezTerm). - ``iterm`` — iTerm2 inline images (iTerm2, WezTerm). - ``sixel`` — DEC sixel (xterm -ti vt340, foot, mlterm, WezTerm, …). - ``unicode`` — 24-bit half-block downscale; works in any truecolor terminal. Frame decoding requires Pillow (a core Hermes dependency). If Pillow or the spritesheet is unavailable the renderer degrades to ``unicode`` text or an empty string rather than raising. ) annotationsN) lru_cache)Path) DEFAULT_SCALEFRAME_HFRAME_WFRAMES_PER_STATEPetStatestate_row_index)autokittyitermsixelunicodeoffreturnstrctjdd}tjdd}|dkrdStjdsd|vsd|vrdS|d vrdS|d kstjd rdS|d kstjd rdS|dvsd|vsd|vrdSd|vrdSdS)uHBest-effort detection of the richest graphics protocol available. Env-based (non-blocking — we never issue a DA1/terminal query that could hang a pipe). Returns one of ``kitty`` / ``iterm`` / ``sixel`` / ``unicode``. Conservative: unknown terminals get ``unicode``, which works anywhere with truecolor. TERM TERM_PROGRAMvscoderKITTY_WINDOW_IDr ghostty>rwezterm WEZTERM_PANEz iterm.appITERM_SESSION_IDr>minttyfootmltermr)osenvirongetlower)term term_programs 6/home/thesage/.hermes/hermes-agent/agent/pet/render.pydetect_terminal_graphicsr(0s :>>&" % % + + - -D:>>."55;;==Lxy z~~'((GtOOyD?P?Pw{""wy  BJNN>$B$B w{""bjnn5G&H&H"wz!!Vt^^x47G7Gw$w 9stream configured str | Nonec@|pd}|tvrd}|dkrdS|p tj} t |dr|sdSn#ttf$rYdSwxYw|dkrtS|S)uResolve the effective render mode from config + the environment. ``configured`` is ``display.pet.render_mode`` (``auto`` → detect). Returns ``off`` when not attached to a TTY (no point emitting graphics into a pipe or logfile). r risatty) stripr$ RENDER_MODESsysstdouthasattrr/ ValueErrorOSErrorr()r,r+modes r' resolve_moder8]s  & ' ' ) ) / / 1 1D < u}}u  !szF)) fmmoo 5   uu v~~'))) Ks $A22BBpathrcbddlm}||}|dS)NrImageRGBA)PILr<openconvert)r9r<imgs r' _open_sheetrBzs7 **T  C ;;v  r)boolcn|ddtkS)zGTrue if *frame* has no meaningfully opaque pixel (transparent padding).A) getchannel getextrema _BLANK_ALPHA)frames r'_frame_is_blankrLs,   C + + - -a 0L @@r))maxsize sheet_path state_valueframe_wintframe_hframes_per_statetuplecr tt|}td|j|z}td|j|z}t ||}||z} | |z|jkrtd|j|z } g} t t||D]L} | |z} || | | |z| |zf} t| rn| | Mt| S#t$r(}td|||Yd}~dSd}~wwxYw)aCropped, padding-trimmed RGBA frames for one state row (unscaled). Steps across the row until the first blank column so pets with ragged per-state frame counts never animate into empty padding. Cached; returns ``()`` on any decode failure. rGrz$pet frame decode failed (%s, %s): %sN)rBrmaxwidthheightr rangemincroprLappendrU Exceptionloggerdebug)rOrPrQrSrTsheetcolsrowsrowtopframesileftrKexcs r' _raw_framesrksWD,,--1ekW,--1elg-..k400Gm =5< ' 'a/00Cs+T2233 ! !Aw;DJJc4'>3=IJJEu%%  MM% V}}  ;ZVYZZZrrrrrsDD D6D11D6scale_wscale_hct|||||}|r f||fkrt|Sddlmfd|DS)zReturn padding-trimmed RGBA frames for one state row, scaled. Thin scaling layer over :func:`_raw_frames`; both are cached so repeated frame requests during animation are free. rr;cJg|]}|fj SrWresizeLANCZOS).0fr<rmrls r' z_frames_for..s. E E EAAHHgw' 7 7 E E Er))rklistr>r<) rOrPrQrSrTrlrmrawr<s `` @r' _frames_forrxsw j+wAQ R RC 7G$'(:::Cyy E E E E E E E E EEr))rQrSrT str | Pathdict[str, int]c6fdtDS)u3Map each driven :class:`PetState` → its real (padding-trimmed) frame count. The single source of truth for "how many frames does this state actually have?". The CLI/TUI consume the trimmed frame lists directly; the gateway ships this map to the desktop canvas, which steps its own loop. c i|]:}|jttt|j;SrW)valuelenrkr)rsstaterSrQrTrOs r' z&state_frame_counts..sU      S JgwHX Y Y     r))r )rOrQrSrTs````r'state_frame_countsrsB           r)bytesc~tj}||d|S)NPNG)format)ioBytesIOsavegetvalue)rKbufs r' _png_bytesrs1 *,,C JJs5J!!! <<>>r) tuple[int, int, int, int] | Nonecfdx}x}x}}|D]} |d}n#t$rd}YnwxYw|s@|\}}} } ||nt||}||nt||}|| nt || }|| nt || }||||dS||||fS)zFUnion opaque-pixel bbox across *frames* (a stable trim for animation).NrF)rHgetbboxr_r\rX) rgrirfrightbottomrKbboxltrbs r'_union_alpha_bboxrs"&&D&3& 9 9 ##C((0022DD   DDD    1aLqqc$ll;aaCQKK]E1 n#fa.. |s{emv~t #uf %%s'6 AAcFt|s|Sfd|DS)a1Crop every frame to the union opaque bbox so the sprite hugs its box. kitty paints the whole transmitted rectangle, transparent margins included, which makes the visible pet look small and adrift inside a larger cell box. Trimming to the visible bounds keeps the pet tight in its corner. c:g|]}|SrW)r])rsrtrs r'ruz/_crop_frames_to_alpha_union..s# ) ) )QAFF4LL ) ) )r))r)rgrs @r'_crop_frames_to_alpha_unionrs9 V $ $D  ) ) ) )& ) ) ))r)c(|s|Sddlm|dj\}}tdt |t z }tdt |t z }|t z|t zf||fkr|Sfd|DS)zResize frames so width/height are exact multiples of the cell box. Removes the sub-cell remainder kitty would otherwise round up + clip. All frames share the union-cropped size, so they snap to the same cell grid. rr;rGcFg|]}|jSrWrp)rsrtr<targets r'ruz-_snap_frames_to_cell_grid..$s) < < <AHHVU] + + < < r<sizerXround_CELL_W_CELL_H)rgwhrcrdr<rs @@r'_snap_frames_to_cell_gridrs   !9>DAq q%G $$ % %D q%G $$ % %DWndWn -F 1v < < < < 4.aaQ>>>>>??? @ 773<<r) cell_cols cell_rowsr int | Nonercd}|r|d|z }|r|d|z }t|tjt|dS)zEncode one frame via the kitty graphics protocol (transmit + display). ``a=T`` transmits & displays at the cursor; ``c``/``r`` request a display box in terminal cells so successive frames overwrite the same area. z f=100,a=T,q=2,c=,r=asciirbase64standard_b64encoderdecode)rKrrrs r' _encode_kittyr4sq D" !i!!!" !i!!! dF5j6G6GHHOOPWXX Y YYr)u􎻮()ii iiii=i>i?iFiJiKiLiPiQiRiWi[icidieifigihiiijikiliminioiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiWiXiYiZi[i]i^iiiiiiiiiiiiiiiii0i2i3i5i6i:i=i?i@iAiCiEiGiIiJiiiiiiiiiiiiiiiiii i!i"i#i%i&i'i)i*i+i,i-iQ iS iT iiiii]i^i_ii:iiuiviwixiyizi{i|ikiminioipiqirisiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii i i i i i i i i i i i i,i,i,i-i-i-i-i-i-i-i-i-i-i-i-i-i-i-i-i-i-i-i-i-i-i-i-i-i-i-i-i-i-i-i-ioi|i}iiiiiiiiiiiiiiiiiiiiiiiiiiiii i!i"i#i$i%i&i i8 iiiiiiiiiiBiCiDztuple[int, ...]_ROWCOL_DIACRITICSslugcfddl}||ddzdzS)a\Stable per-pet image id in ``[1, 0x7FFF]``. The id is encoded in the placeholder's 24-bit foreground color, so it must be non-zero and fit comfortably under ``0xFFFFFF``. A small CRC keeps it deterministic per slug (so re-renders reuse the same terminal-side image) while making collisions between two different pets unlikely. rNzutf-8irG)zlibcrc32encode)rrs r'kitty_image_idrvs5KKK JJt{{7++ , ,v 5 ::r)image_idcd|dzzS)zEHex foreground color (``#rrggbb``) that encodes *image_id* for kitty.z#%06xirW)rs r'kitty_color_hexrs h) **r)rcrd list[str]c>td|}g}ttd|D]l}t|ttdz }t t t|z}||t |dz zzm|S)ugBuild the placeholder text grid for an *rows*×*cols* image. Each line is one row of the grid: the first cell carries the row diacritic (column defaults to 0), and the remaining ``cols-1`` bare placeholders let the terminal auto-increment the column. The foreground color (the image id) is applied by the caller / Ink, not embedded here. rG)rXr[r\r~r_KITTY_PLACEHOLDERchrr^)rcrdrridxfirsts r'kitty_placeholder_rowsrs q$< >T > >d > > >D dF5j6G6GHHOOPWXX Y YYr)c8tjt|d}t |}dd|dg}|r|d||r|d|dd|d |d S) z;Encode one frame as an iTerm2 inline image (OSC 1337 File).rzinline=1zsize=zpreserveAspectRatio=1zwidth=zheight=z ]1337;File=r:)rrrrr~r^r)rKrrpayloadrargss r' _encode_itermrs' 5(9(9::AA'JJG w<z _encode_sixel..s4@@@uQxx@@!2ad8@@@@r)rGz#%d;2;%d;%d;%ddz#%dNcdSdkrdfznzd\dS)Nrz!%d%s)Nr)r^)linerun_charrun_lensr'flushz_encode_sixel..flushs[#FQ;;KK7H*= =>>>>KK7 2333$+!'''r) ?r$-r)r>r<r@quantize MEDIANCUT getpaletteloadrHrsortedr[r~r^rr)rKr<rgbapalpalettealpharrusedrrgrband color_idxrrbitsbitrchrrrrrs @@@@@r' _encode_sixelrs D ,,u   & &c%/ & J JCnn$"G B OOC % % ' 'E 8DAq ,!Q/ 0C @@@@@U1XX@@@ A AD]] #a#g,, 6 6GC!G  A$'!GaK#g,,$>$>GC!GaK A$'!GaK#g,,$>$>GC!GaK A #sAGsNAGsNAPSGWZN&[[\\\\aA , ,II%&DHG , , , , , , ,1XX . . 88))Cs A1uuq!tr!1!1bAh)6K6KS(d^^>>qLGGEGGG(*A%Hgg EGGG JJrwwt}}s* + + + + 3JJx 773<<r)u▀ target_colslist[list[Cell]]c Jddlm}td|}|jtd|jz }tdt t ||zdzdz}|||f|j d}| }g}td|dD]d}g} t|D];} || |f} |dz|kr || |dzfnd} | | | f<| | e|S) u>Downscale a frame to a grid of half-block cells. Each cell pairs a top and bottom pixel so one terminal row encodes two pixel rows. Returns rows of ``((tr,tg,tb,ta),(br,bg,bb,ba))`` — the framework-neutral representation shared by the ANSI encoder (CLI) and the structured ``cells`` API (Ink). rr;rGrg?r=)rrrr) r>r<rXrZrYrRrrqrrr@rr[r^) rKrr<aspect target_rowssmallrgridrrerrfrs r'_downscale_cellsrs?a%%K \C5;// /FaU;#7##=>>??!CDDK LL+{3U] C C K KF S SE BD 1k1 % %{## & &AQT(C%&U[%8%8R1q5\\lF JJV} % % % % C Kr)cxg}t||D]}g}|D]`\\}}}}\} } } } |dkr| dkr|d1|d|d|d|d| d| d| dta|d|d zd |S) zGDownscale to truecolor ANSI half-blocks (one char = 2 vertical pixels).rrz zzm[48;2;mrz )rr^ _HALF_BLOCKr) rKrlinesrecellstrtgtbtabrbgbbbas r'_encode_unicodersE;???1125 ] ] . RR.r2r2Bww277 Z((( LL[b[[2[[[[r[[B[[[[k[[ \ \ \ \ RWWU^^i/0000 99U  r)cxeZdZdZdedeeedd&dZe d'dZ d(dZ d)dZ ddd*dZ d+d!Zd,d$Zd-d%ZdS). PetRendereruHolds a pet's spritesheet and yields encoded frames per (state, index). Construct once per pet, then call :meth:`frame` on an animation timer. Cheap to call repeatedly — decoded frames are cached. r)r7scale unicode_colsrQrSrT spritesheetryr7rrfloatrrRrQrSrTrNonect||_|tvr|nd|_||_||_||_||_||_dS)Nr) rrr1r7rrrQrSrT)selfrr7rrrQrSrTs r'__init__zPetRenderer.__init__*sT{++ L00DDi  (  0r)rDcd|jdko%t|jS)Nr)r7rris_file)rs r' availablezPetRenderer.available=s+yE!Fd4+;&<&<&D&D&F&FFr)rPetState | strcFt||S)N)r~_frames)rrs r' frame_countzPetRenderer.frame_countAs4<<&&'''r)c Rt|tr|jnt|}t dt |j|jz}t dt |j|jz}t|j ||j|j|j ||S)NrG) isinstancer r}rrXrRrQrrSrxrrT)rrr}rlrms r'r&zPetRenderer._framesDs)%::J E aT\DJ67788aT\DJ67788    L L  !     r)N)rcindexrcrrc||}|sgS||t|z}t||p|jS)zReturn one frame as a half-block cell grid (framework-neutral). Used by the TUI, which renders the grid with native Ink color props instead of raw ANSI. Returns ``[]`` when no frame is available. r)r&r~rr)rrr*rcrgrKs r'r zPetRenderer.cellsRsR e$$ Ius6{{*+43L4;LMMMMr)tuple[int, int]cbtd|jdztd|jdzfS)u/Terminal cell box for a scaled frame (~8×16 px per cell). Must match :meth:`frame` graphics sizing — kitty stretches the image to fill ``c``×``r`` cells, so these must reflect the scaled pixel dimensions, not a native-aspect column count (that upscales small pets). rGrCrM)rXrYrZ)rrKs r' _cell_boxzPetRenderer._cell_box^s11ekQ&''Q 0B)C)CCCr)r dict | Nonec||}|sdSt|}t|}||d\t fd|DdS)uBuild the kitty Unicode-placeholder payload for one state. Returns ``{cols, rows, placeholder, frames}`` where ``frames`` is a list of transmit escapes (one per animation frame, all reusing ``image_id``) and ``placeholder`` is the static text grid Ink paints. Placement geometry is derived from the scaled frame pixels (via :meth:`_cell_box`), not ``unicode_cols`` — kitty upscales to fill ``c``×``r`` cells. ``None`` when no frame is available. Nrc6g|]}t|S))rrcrd)r)rsrtrcrrds r'ruz-PetRenderer.kitty_payload..{s8VW%a(DQQQr))rcrd placeholderrg)r&rrr.r)rrrrgrcrds ` @@r' kitty_payloadzPetRenderer.kitty_payloadgse$$ 4,V44*622^^F1I.. d1$==[a    r)c|jdkrdS||}|sdS||t|z}||\}} |jdkrt |||S|jdkrt |||S|jdkrt |St||jS#t$r,}t d|j|Yd }~dSd }~wwxYw) zReturn the encoded escape string for one frame, or ``""``. ``index`` is taken modulo the available frame count so callers can pass a free-running counter. rrr rrrrz%pet frame encode failed (mode=%s): %sN) r7r&r~r.rrrrrr_r`ra)rrr*rgrKrrrjs r'rKzPetRenderer.frames 9  2e$$ 2us6{{*+#~~e44 9 yG##$Ui9UUUUyG##$Ui9UUUUyG##$U+++"5d6GHHH H    LL@$)S Q Q Q22222 s*C5CC,C C8 !C33C8)rryr7rrrrrRrQrRrSrRrTrRrrrrD)rr$rrR)rr$)rr$r*rRrcrrr)rr,)rr$rrRrr/)rr$r*rRrr)__name__ __module__ __qualname____doc__rrrr r propertyr#r'r&r r.r3rKrWr)r'rr#s$ 0111111&GGGXG((((     NR N N N N N NDDDD    2r)rr)configured_moderrr+rr;rrrcJt||}t||||S)zFConvenience factory: resolve the mode from config+env, then construct.r*)r7rr)r8r)rr;rrr+r7s r'build_rendererr=s9  7 7 7D  !    r))rr)r,r-rr)r9rr5) rOrrPrrQrRrSrRrTrRrrU)rOrrPrrQrRrSrRrTrRrlrRrmrR) rOryrQrRrSrRrTrRrrz)rr)rr)rrrrrr)rrrrrr)rrrrR)rrRrr)rcrRrdrRrr)rrRrcrRrdrRrr)rrRrr)rrRrr) rryr;r-rrrrRrr)8r9 __future__rrrloggingr!r2 functoolsrpathlibragent.pet.constantsrrrr r r getLoggerr6r`r1r(r8rBrJrLrkrxrrrrrrrrrrr__annotations__rrrrrrr rUrRCellrrrr=rWr)r'rFs$#"""""    8 $ $E ****Z48: AAAA  2""""J 1FFFF2, 2 &&&&( * * *&  ===&    59RV Z Z Z Z Z Z6" 'D ; ; ; ;++++ " Z Z Z Z59RV < < < < < <;;;;|  U3S#% &c3S.@(A AB6    $uuuuuuuuv#'   r)