big slow change: prebuilt shaders (SPIR-V/Metal), core gui reflow, docs, web + snapshot refresh

1 files changed, 119 insertions, 7 deletions

diff --git a/src/macos/pardes.h b/src/macos/pardes.h
index 9a64501a..cfe83ffa 100644
--- a/src/macos/pardes.h
+++ b/src/macos/pardes.h
@@ -45,6 +45,8 @@ typedef struct {
   uint8_t len;
   // bit 0: the core never painted this cell — draw it as the default cell
   // (background only), which is what makes a partial redraw cheap.
+  // bit 1: rasterize text and its colour band with the tagline face's measured
+  // height. Logical cell geometry stays body-sized; this is a visual role.
   uint8_t flags;
 } pardes_cell_s;
 
@@ -73,6 +75,54 @@ typedef struct {
 #define PARDES_UL_DASHED 5
 
 #define PARDES_CELL_DEFAULT 0x01u
+#define PARDES_CELL_TAGLINE 0x02u
+
+// One coherent snapshot for the full-window shader pass. The bitmask lets the
+// host run CRT, ripple and glitch in one kernel instead of stacking filters;
+// time/frame advance only on pardes_animation_tick's display clock.
+typedef struct {
+  uint32_t flags;
+  float time_seconds;
+  uint32_t frame;
+} pardes_scene_s;
+
+#define PARDES_SCENE_CRT 0x01u
+#define PARDES_SCENE_RIPPLE 0x02u
+#define PARDES_SCENE_GLITCH 0x04u
+
+// One backend-neutral pane transition. Boxes are logical cell rectangles;
+// the native shader converts them to backing pixels using the same measured
+// cell as the renderer. The list is already in paint order: moving first,
+// opening next, frozen closing tombstones last, and slot order within a phase.
+typedef struct {
+  float x;
+  float y;
+  float w;
+  float h;
+} pardes_panel_box_s;
+
+typedef struct {
+  uint32_t serial;
+  uint8_t pane;
+  uint8_t phase;
+  uint8_t effect;
+  uint8_t reserved0;
+  uint16_t frame;
+  uint16_t reserved1;
+  pardes_panel_box_s from;
+  pardes_panel_box_s to;
+} pardes_panel_track_s;
+
+#define PARDES_PANEL_OPENING 0u
+#define PARDES_PANEL_MOVING 1u
+#define PARDES_PANEL_CLOSING 2u
+
+#define PARDES_PANEL_OFF 0u
+#define PARDES_PANEL_SLIDE 1u
+#define PARDES_PANEL_ZOOM 2u
+#define PARDES_PANEL_DISSOLVE 3u
+#define PARDES_PANEL_ASCII 4u
+#define PARDES_PANEL_VERTICAL 5u
 
 // ---------------------------------------------------------------- input
 
@@ -173,10 +223,15 @@ void pardes_deinit(void);
 // into the core and use this only to decide whether there was work.
 bool pardes_tick(void);
 
+// Advance one frame-count animation step. Call only from the scheduled ~60 Hz
+// callback, never from ordinary input or pty pumps: those drain work but do
+// not represent elapsed display time. Returns whether anything advanced.
+bool pardes_animation_tick(void);
+
 // The core asked to exit (the Exit builtin, or the last pane closing).
 bool pardes_should_quit(void);
 
-// A theme transition is mid-flight and wants ~60 Hz ticks until it settles.
+// A theme/pane transition, scene effect, or rotation coast wants ~60 Hz ticks.
 bool pardes_animating(void);
 
 // What to paint where the grid does not: the window background behind the
@@ -189,6 +244,25 @@ bool pardes_animating(void);
 // wear, so the host should go transparent and show its own backdrop.
 uint32_t pardes_theme_bg(void);
 
+// Pane taglines use this percentage of the current body font size. It is the
+// embedded default before init and the live core setting afterwards; the host
+// polls it and rebuilds only tagline glyph/metric state.
+uint8_t pardes_gui_tagline_font_percent(void);
+
+// Persistent full-window effect switches and their display-clock time. A zero
+// flags word means draw the CoreText frame directly; any nonzero combination
+// is one postprocess pass. Snapshot by value, with no borrowed storage.
+pardes_scene_s pardes_scene(void);
+
+// The shared Metal/Core Image pass is unavailable for this session. Clears
+// scene effects and future panel transitions so Config reflects what the host
+// can actually present and the display clock cannot retry forever.
+void pardes_postprocessor_unavailable(void);
+
+// A transient postprocess failure will be presented as the canonical grid.
+// Drop current panel tracks so a later scene retry cannot resume them midway.
+void pardes_panel_animation_failed(void);
+
 // ---------------------------------------------------------------- events in
 
 // `cp` is a codepoint or one of PARDES_KEY_*; `text`/`len` are the host's
@@ -198,6 +272,15 @@ void pardes_key(uint32_t cp, const char *text, size_t len, uint32_t mods);
 void pardes_paste(const char *text, size_t len);
 void pardes_mouse(pardes_mouse_button_e button, pardes_mouse_kind_e kind,
                   uint16_t col, uint16_t row, uint32_t mods);
+// The pointer left the view. A clamped motion on its final cell is not the
+// same event: it would keep hover previews and resize hints alive off-window.
+void pardes_pointer_leave(void);
+
+// Host file watchers call this after their debounce interval. `generation`
+// comes from pardes_host_watch_file and makes an event queued before a pane
+// replacement inert. The callback only schedules the ordinary main-thread
+// pump; file IO and the shared text/PDF reload happen inside pardes_tick.
+void pardes_watch_changed(uint8_t pane, uint32_t generation);
 
 // Trackpad/precision wheel distance in CELLS, sign following the grid
 // (positive scrolls down and right). The core has no fractional scroll — it
@@ -224,9 +307,10 @@ void pardes_rotate(float degrees);
 // how hard it was thrown, and the two are the same curve — momentum ramps up
 // from zero rather than switching on at a threshold.
 //
-// A coast makes pardes_animating true and is spent by pardes_tick, so a host
-// that already re-pumps for theme transitions needs no new machinery; one that
-// never calls this simply has a dial with no momentum.
+// A coast makes pardes_animating true and is spent by
+// pardes_animation_tick, so a host that already re-pumps for theme transitions
+// needs no new machinery; one that never calls this simply has a dial with no
+// momentum.
 void pardes_rotate_end(void);
 
 // Run one builtin command line, exactly as executing the same text in a tag
@@ -246,6 +330,11 @@ void pardes_resize(uint16_t cols, uint16_t rows, uint16_t cell_w,
 // The buffer returned by pardes_frame_cells is valid until the next call.
 uint32_t pardes_frame(void);
 const pardes_cell_s *pardes_frame_cells(void);
+// Frozen old grid and its byte-per-cell semantic change mask. Both are either
+// present for exactly cols*rows cells or NULL together, and are borrowed until
+// the next pardes_frame call just like the canonical cells.
+const pardes_cell_s *pardes_frame_previous_cells(void);
+const uint8_t *pardes_frame_changed_cells(void);
 uint16_t pardes_frame_cols(void);
 uint16_t pardes_frame_rows(void);
 
@@ -290,6 +379,16 @@ typedef struct {
 uint32_t pardes_frame_images(void);
 const pardes_image_s *pardes_frame_image_list(void);
 
+// Shader transition records for this frame, borrowed until pardes_frame is
+// called again. Empty means draw the canonical grid without a panel pass.
+uint32_t pardes_frame_panel_tracks(void);
+const pardes_panel_track_s *pardes_frame_panel_track_list(void);
+// Call only after the host has put this frame on screen. `true` commits the
+// borrowed panel-track list above; `false` records a direct canonical fallback.
+// Returns true only when remapping a stationary pointer newly started a clock
+// the host was not already running.
+bool pardes_frame_presented(bool animated_panels);
+
 // The file behind the FOCUSED pane, or NULL when there is none: a terminal, an
 // output buffer, or nothing focused. PDFs and images count — they are real
 // paths, and a titlebar proxy icon is about the file, not about who may edit
@@ -323,11 +422,24 @@ pardes_haptic_e pardes_take_haptic(void);
 // file is named after.
 //
 // The host loads it, re-measures its cell, and reports the new grid through
-// pardes_resize. A file the host cannot load is one to ignore: keep wearing
-// the face that works, because a terminal that cannot draw has no way back
-// out of it.
+// pardes_resize. A file the host cannot load must be rejected explicitly while
+// keeping the face that works; otherwise Config would leave the request pending
+// forever or claim a fallback was accepted.
 const char *pardes_font_take(void);
 
+// Boot, zoom and display-scale changes observe the face already on screen;
+// this never consumes a pending request. `point_hundredths` is the effective
+// body size (14pt => 1400).
+bool pardes_font_observe(const char *effective_name, size_t len,
+                         uint16_t point_hundredths);
+
+// A taken Font request is not effective until the host says what CoreText
+// actually accepted. Calling this without a request from pardes_font_take is
+// inert, so an unrelated host report cannot consume the request.
+bool pardes_font_ack(const char *effective_name, size_t len,
+                     uint16_t point_hundredths);
+void pardes_font_reject(void);
+
 #ifdef __cplusplus
 }
 #endif