Replace batch DAG system with streaming architecture

- Remove legacy_tasks.py, hybrid_state.py, render.py
- Remove old task modules (analyze, execute, execute_sexp, orchestrate)
- Add streaming interpreter from test repo
- Add sexp_effects with primitives and video effects
- Add streaming Celery task with CID-based asset resolution
- Support both CID and friendly name references for assets
- Add .dockerignore to prevent local clones from conflicting

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

sexp_effects/__init__.py

@@ -0,0 +1,32 @@
+"""
+S-Expression Effects System
+
+Safe, shareable effects defined in S-expressions.
+"""
+
+from .parser import parse, parse_file, Symbol, Keyword
+from .interpreter import (
+    Interpreter,
+    get_interpreter,
+    load_effect,
+    load_effects_dir,
+    run_effect,
+    list_effects,
+    make_process_frame,
+)
+from .primitives import PRIMITIVES
+
+__all__ = [
+    'parse',
+    'parse_file',
+    'Symbol',
+    'Keyword',
+    'Interpreter',
+    'get_interpreter',
+    'load_effect',
+    'load_effects_dir',
+    'run_effect',
+    'list_effects',
+    'make_process_frame',
+    'PRIMITIVES',
+]

sexp_effects/effects/ascii_art.sexp

@@ -0,0 +1,17 @@
+;; ASCII Art effect - converts image to ASCII characters
+(require-primitives "ascii")
+
+(define-effect ascii_art
+  :params (
+    (char_size :type int :default 8 :range [4 32])
+    (alphabet :type string :default "standard")
+    (color_mode :type string :default "color" :desc ""color", "mono", "invert", or any color name/hex")
+    (background_color :type string :default "black" :desc "background color name/hex")
+    (invert_colors :type int :default 0 :desc "swap foreground and background colors")
+    (contrast :type float :default 1.5 :range [1 3])
+  )
+  (let* ((sample (cell-sample frame char_size))
+         (colors (nth sample 0))
+         (luminances (nth sample 1))
+         (chars (luminance-to-chars luminances alphabet contrast)))
+    (render-char-grid frame chars colors char_size color_mode background_color invert_colors)))

sexp_effects/effects/ascii_art_fx.sexp

@@ -0,0 +1,52 @@
+;; ASCII Art FX - converts image to ASCII characters with per-character effects
+(require-primitives "ascii")
+
+(define-effect ascii_art_fx
+  :params (
+    ;; Basic parameters
+    (char_size :type int :default 8 :range [4 32]
+      :desc "Size of each character cell in pixels")
+    (alphabet :type string :default "standard"
+      :desc "Character set to use")
+    (color_mode :type string :default "color"
+      :choices [color mono invert]
+      :desc "Color mode: color, mono, invert, or any color name/hex")
+    (background_color :type string :default "black"
+      :desc "Background color name or hex value")
+    (invert_colors :type int :default 0 :range [0 1]
+      :desc "Swap foreground and background colors (0/1)")
+    (contrast :type float :default 1.5 :range [1 3]
+      :desc "Character selection contrast")
+
+    ;; Per-character effects
+    (char_jitter :type float :default 0 :range [0 20]
+      :desc "Position jitter amount in pixels")
+    (char_scale :type float :default 1.0 :range [0.5 2.0]
+      :desc "Character scale factor")
+    (char_rotation :type float :default 0 :range [0 180]
+      :desc "Rotation amount in degrees")
+    (char_hue_shift :type float :default 0 :range [0 360]
+      :desc "Hue shift in degrees")
+
+    ;; Modulation sources
+    (jitter_source :type string :default "none"
+      :choices [none luminance inv_luminance saturation position_x position_y position_diag random center_dist]
+      :desc "What drives jitter modulation")
+    (scale_source :type string :default "none"
+      :choices [none luminance inv_luminance saturation position_x position_y position_diag random center_dist]
+      :desc "What drives scale modulation")
+    (rotation_source :type string :default "none"
+      :choices [none luminance inv_luminance saturation position_x position_y position_diag random center_dist]
+      :desc "What drives rotation modulation")
+    (hue_source :type string :default "none"
+      :choices [none luminance inv_luminance saturation position_x position_y position_diag random center_dist]
+      :desc "What drives hue shift modulation")
+  )
+  (let* ((sample (cell-sample frame char_size))
+         (colors (nth sample 0))
+         (luminances (nth sample 1))
+         (chars (luminance-to-chars luminances alphabet contrast)))
+    (render-char-grid-fx frame chars colors luminances char_size
+                         color_mode background_color invert_colors
+                         char_jitter char_scale char_rotation char_hue_shift
+                         jitter_source scale_source rotation_source hue_source)))

sexp_effects/effects/ascii_fx_zone.sexp

@@ -0,0 +1,102 @@
+;; Composable ASCII Art with Per-Zone Expression-Driven Effects
+;; Requires ascii primitive library for the ascii-fx-zone primitive
+
+(require-primitives "ascii")
+
+;; Two modes of operation:
+;;
+;; 1. EXPRESSION MODE: Use zone-* variables in expression parameters
+;;    Zone variables available:
+;;      zone-row, zone-col: Grid position (integers)
+;;      zone-row-norm, zone-col-norm: Normalized position (0-1)
+;;      zone-lum: Cell luminance (0-1)
+;;      zone-sat: Cell saturation (0-1)
+;;      zone-hue: Cell hue (0-360)
+;;      zone-r, zone-g, zone-b: RGB components (0-1)
+;;
+;;    Example:
+;;      (ascii-fx-zone frame
+;;        :cols 80
+;;        :char_hue (* zone-lum 180)
+;;        :char_rotation (* zone-col-norm 30))
+;;
+;; 2. CELL EFFECT MODE: Pass a lambda to apply arbitrary effects per-cell
+;;    The lambda receives (cell-image zone-dict) and returns modified cell.
+;;    Zone dict contains: row, col, row-norm, col-norm, lum, sat, hue, r, g, b,
+;;                        char, color, cell_size, plus any bound analysis values.
+;;
+;;    Any loaded sexp effect can be called on cells - each cell is just a small frame:
+;;      (blur cell radius)           - Gaussian blur
+;;      (rotate cell angle)          - Rotate by angle degrees
+;;      (brightness cell factor)     - Adjust brightness
+;;      (contrast cell factor)       - Adjust contrast
+;;      (saturation cell factor)     - Adjust saturation
+;;      (hue_shift cell degrees)     - Shift hue
+;;      (rgb_split cell offset_x offset_y) - RGB channel split
+;;      (invert cell)                - Invert colors
+;;      (pixelate cell block_size)   - Pixelate
+;;      (wave cell amplitude freq)   - Wave distortion
+;;      ... and any other loaded effect
+;;
+;;    Example:
+;;      (ascii-fx-zone frame
+;;        :cols 60
+;;        :cell_effect (lambda [cell zone]
+;;          (blur (rotate cell (* (get zone "energy") 45))
+;;                (if (> (get zone "lum") 0.5) 3 0))))
+
+(define-effect ascii_fx_zone
+  :params (
+    (cols :type int :default 80 :range [20 200]
+      :desc "Number of character columns")
+    (char_size :type int :default nil :range [4 32]
+      :desc "Character cell size in pixels (overrides cols if set)")
+    (alphabet :type string :default "standard"
+      :desc "Character set: standard, blocks, simple, digits, or custom string")
+    (color_mode :type string :default "color"
+      :desc "Color mode: color, mono, invert, or any color name/hex")
+    (background :type string :default "black"
+      :desc "Background color name or hex value")
+    (contrast :type float :default 1.5 :range [0.5 3.0]
+      :desc "Contrast for character selection")
+    (char_hue :type any :default nil
+      :desc "Hue shift expression (evaluated per-zone with zone-* vars)")
+    (char_saturation :type any :default nil
+      :desc "Saturation multiplier expression (1.0 = unchanged)")
+    (char_brightness :type any :default nil
+      :desc "Brightness multiplier expression (1.0 = unchanged)")
+    (char_scale :type any :default nil
+      :desc "Character scale expression (1.0 = normal size)")
+    (char_rotation :type any :default nil
+      :desc "Character rotation expression (degrees)")
+    (char_jitter :type any :default nil
+      :desc "Position jitter expression (pixels)")
+    (cell_effect :type any :default nil
+      :desc "Lambda (cell zone) -> cell for arbitrary per-cell effects")
+    ;; Convenience params for staged recipes (avoids compile-time expression issues)
+    (energy :type float :default nil
+      :desc "Energy multiplier (0-1) from audio analysis bind")
+    (rotation_scale :type float :default 0
+      :desc "Max rotation at top-right when energy=1 (degrees)")
+  )
+  ;; The ascii-fx-zone special form handles expression params
+  ;; If energy + rotation_scale provided, it builds: energy * scale * position_factor
+  ;; where position_factor = 0 at bottom-left, 3 at top-right
+  ;; If cell_effect provided, each character is rendered to a cell image,
+  ;; passed to the lambda, and the result composited back
+  (ascii-fx-zone frame
+    :cols cols
+    :char_size char_size
+    :alphabet alphabet
+    :color_mode color_mode
+    :background background
+    :contrast contrast
+    :char_hue char_hue
+    :char_saturation char_saturation
+    :char_brightness char_brightness
+    :char_scale char_scale
+    :char_rotation char_rotation
+    :char_jitter char_jitter
+    :cell_effect cell_effect
+    :energy energy
+    :rotation_scale rotation_scale))

sexp_effects/effects/ascii_zones.sexp

@@ -0,0 +1,30 @@
+;; ASCII Zones effect - different character sets for different brightness zones
+;; Dark areas use simple chars, mid uses standard, bright uses blocks
+(require-primitives "ascii")
+
+(define-effect ascii_zones
+  :params (
+    (char_size :type int :default 8 :range [4 32])
+    (dark_threshold :type int :default 80 :range [0 128])
+    (bright_threshold :type int :default 180 :range [128 255])
+    (color_mode :type string :default "color")
+  )
+  (let* ((sample (cell-sample frame char_size))
+         (colors (nth sample 0))
+         (luminances (nth sample 1))
+         ;; Start with simple chars as base
+         (base-chars (luminance-to-chars luminances "simple" 1.2))
+         ;; Map each cell to appropriate alphabet based on brightness zone
+         (zoned-chars (map-char-grid base-chars luminances
+                        (lambda (r c ch lum)
+                          (cond
+                            ;; Bright zones: use block characters
+                            ((> lum bright_threshold)
+                             (alphabet-char "blocks" (floor (/ (- lum bright_threshold) 15))))
+                            ;; Dark zones: use simple sparse chars
+                            ((< lum dark_threshold)
+                             (alphabet-char " .-" (floor (/ lum 30))))
+                            ;; Mid zones: use standard ASCII
+                            (else
+                             (alphabet-char "standard" (floor (/ lum 4)))))))))
+    (render-char-grid frame zoned-chars colors char_size color_mode (list 0 0 0))))

sexp_effects/effects/blend.sexp

@@ -0,0 +1,31 @@
+;; Blend effect - combines two video frames
+;; Streaming-compatible: frame is background, overlay is second frame
+;; Usage: (blend background overlay :opacity 0.5 :mode "alpha")
+;;
+;; Params:
+;;   mode - blend mode (add, multiply, screen, overlay, difference, lighten, darken, alpha)
+;;   opacity - blend amount (0-1)
+
+(require-primitives "image" "blending" "core")
+
+(define-effect blend
+  :params (
+    (overlay :type frame :default nil)
+    (mode :type string :default "alpha")
+    (opacity :type float :default 0.5)
+  )
+  (if (core:is-nil overlay)
+    frame
+    (let [a frame
+          b overlay
+          a-h (image:height a)
+          a-w (image:width a)
+          b-h (image:height b)
+          b-w (image:width b)
+          ;; Resize b to match a if needed
+          b-sized (if (and (= a-w b-w) (= a-h b-h))
+                    b
+                    (image:resize b a-w a-h "linear"))]
+      (if (= mode "alpha")
+        (blending:blend-images a b-sized opacity)
+        (blending:blend-images a (blending:blend-mode a b-sized mode) opacity)))))

sexp_effects/effects/blend_multi.sexp

@@ -0,0 +1,58 @@
+;; N-way weighted blend effect
+;; Streaming-compatible: pass inputs as a list of frames
+;; Usage: (blend_multi :inputs [(read a) (read b) (read c)] :weights [0.3 0.4 0.3])
+;;
+;; Parameters:
+;;   inputs      - list of N frames to blend
+;;   weights     - list of N floats, one per input (resolved per-frame)
+;;   mode        - blend mode applied when folding each frame in:
+;;                   "alpha"       — pure weighted average (default)
+;;                   "multiply"    — darken by multiplication
+;;                   "screen"      — lighten (inverse multiply)
+;;                   "overlay"     — contrast-boosting midtone blend
+;;                   "soft-light"  — gentle dodge/burn
+;;                   "hard-light"  — strong dodge/burn
+;;                   "color-dodge" — brightens towards white
+;;                   "color-burn"  — darkens towards black
+;;                   "difference"  — absolute pixel difference
+;;                   "exclusion"   — softer difference
+;;                   "add"         — additive (clamped)
+;;                   "subtract"    — subtractive (clamped)
+;;                   "darken"      — per-pixel minimum
+;;                   "lighten"     — per-pixel maximum
+;;   resize_mode - how to match frame dimensions (fit, crop, stretch)
+;;
+;; Uses a left-fold over inputs[1..N-1].  At each step the running
+;; opacity is:  w[i] / (w[0] + w[1] + ... + w[i])
+;; which produces the correct normalised weighted result.
+
+(require-primitives "image" "blending")
+
+(define-effect blend_multi
+  :params (
+    (inputs :type list :default [])
+    (weights :type list :default [])
+    (mode :type string :default "alpha")
+    (resize_mode :type string :default "fit")
+  )
+  (let [n (len inputs)
+        ;; Target dimensions from first frame
+        target-w (image:width (nth inputs 0))
+        target-h (image:height (nth inputs 0))
+        ;; Fold over indices 1..n-1
+        ;; Accumulator is (list blended-frame running-weight-sum)
+        seed (list (nth inputs 0) (nth weights 0))
+        result (reduce (range 1 n) seed
+                 (lambda (pair i)
+                   (let [acc (nth pair 0)
+                         running (nth pair 1)
+                         w (nth weights i)
+                         new-running (+ running w)
+                         opacity (/ w (max new-running 0.001))
+                         f (image:resize (nth inputs i) target-w target-h "linear")
+                         ;; Apply blend mode then mix with opacity
+                         blended (if (= mode "alpha")
+                                   (blending:blend-images acc f opacity)
+                                   (blending:blend-images acc (blending:blend-mode acc f mode) opacity))]
+                     (list blended new-running))))]
+    (nth result 0)))

sexp_effects/effects/bloom.sexp

@@ -0,0 +1,16 @@
+;; Bloom effect - glow on bright areas
+(require-primitives "image" "blending")
+
+(define-effect bloom
+  :params (
+    (intensity :type float :default 0.5 :range [0 2])
+    (threshold :type int :default 200 :range [0 255])
+    (radius :type int :default 15 :range [1 50])
+  )
+  (let* ((bright (map-pixels frame
+                   (lambda (x y c)
+                     (if (> (luminance c) threshold)
+                         c
+                         (rgb 0 0 0)))))
+         (blurred (image:blur bright radius)))
+    (blending:blend-mode frame blurred "add")))

sexp_effects/effects/blur.sexp

@@ -0,0 +1,8 @@
+;; Blur effect - gaussian blur
+(require-primitives "image")
+
+(define-effect blur
+  :params (
+    (radius :type int :default 5 :range [1 50])
+  )
+  (image:blur frame (max 1 radius)))

sexp_effects/effects/brightness.sexp

@@ -0,0 +1,9 @@
+;; Brightness effect - adjusts overall brightness
+;; Uses vectorized adjust primitive for fast processing
+(require-primitives "color_ops")
+
+(define-effect brightness
+  :params (
+    (amount :type int :default 0 :range [-255 255])
+  )
+  (color_ops:adjust-brightness frame amount))

sexp_effects/effects/color-adjust.sexp

@@ -0,0 +1,13 @@
+;; Color adjustment effect - replaces TRANSFORM node
+(require-primitives "color_ops")
+
+(define-effect color-adjust
+  :params (
+    (brightness :type int :default 0 :range [-255 255] :desc "Brightness adjustment")
+    (contrast :type float :default 1 :range [0 3] :desc "Contrast multiplier")
+    (saturation :type float :default 1 :range [0 2] :desc "Saturation multiplier")
+  )
+  (-> frame
+      (color_ops:adjust-brightness brightness)
+      (color_ops:adjust-contrast contrast)
+      (color_ops:adjust-saturation saturation)))

sexp_effects/effects/color_cycle.sexp

@@ -0,0 +1,13 @@
+;; Color Cycle effect - animated hue rotation
+(require-primitives "color_ops")
+
+(define-effect color_cycle
+  :params (
+    (speed :type int :default 1 :range [0 10])
+  )
+  (let ((shift (* t speed 360)))
+    (map-pixels frame
+      (lambda (x y c)
+        (let* ((hsv (rgb->hsv c))
+               (new-h (mod (+ (first hsv) shift) 360)))
+          (hsv->rgb (list new-h (nth hsv 1) (nth hsv 2))))))))

sexp_effects/effects/contrast.sexp

@@ -0,0 +1,9 @@
+;; Contrast effect - adjusts image contrast
+;; Uses vectorized adjust primitive for fast processing
+(require-primitives "color_ops")
+
+(define-effect contrast
+  :params (
+    (amount :type int :default 1 :range [0.5 3])
+  )
+  (color_ops:adjust-contrast frame amount))

sexp_effects/effects/crt.sexp

@@ -0,0 +1,30 @@
+;; CRT effect - old monitor simulation
+(require-primitives "image")
+
+(define-effect crt
+  :params (
+    (line_spacing :type int :default 2 :range [1 10])
+    (line_opacity :type float :default 0.3 :range [0 1])
+    (vignette_amount :type float :default 0.2)
+  )
+  (let* ((w (image:width frame))
+         (h (image:height frame))
+         (cx (/ w 2))
+         (cy (/ h 2))
+         (max-dist (sqrt (+ (* cx cx) (* cy cy)))))
+    (map-pixels frame
+      (lambda (x y c)
+        (let* (;; Scanline darkening
+               (scanline-factor (if (= 0 (mod y line_spacing))
+                                    (- 1 line_opacity)
+                                    1))
+               ;; Vignette
+               (dx (- x cx))
+               (dy (- y cy))
+               (dist (sqrt (+ (* dx dx) (* dy dy))))
+               (vignette-factor (- 1 (* (/ dist max-dist) vignette_amount)))
+               ;; Combined
+               (factor (* scanline-factor vignette-factor)))
+          (rgb (* (red c) factor)
+               (* (green c) factor)
+               (* (blue c) factor)))))))

sexp_effects/effects/datamosh.sexp

@@ -0,0 +1,14 @@
+;; Datamosh effect - glitch block corruption
+
+(define-effect datamosh
+  :params (
+    (block_size :type int :default 32 :range [8 128])
+    (corruption :type float :default 0.3 :range [0 1])
+    (max_offset :type int :default 50 :range [0 200])
+    (color_corrupt :type bool :default true)
+  )
+  ;; Get previous frame from state, or use current frame if none
+  (let ((prev (state-get "prev_frame" frame)))
+    (begin
+      (state-set "prev_frame" (copy frame))
+      (datamosh frame prev block_size corruption max_offset color_corrupt))))

sexp_effects/effects/echo.sexp

@@ -0,0 +1,19 @@
+;; Echo effect - motion trails using frame buffer
+(require-primitives "blending")
+
+(define-effect echo
+  :params (
+    (num_echoes :type int :default 4 :range [1 20])
+    (decay :type float :default 0.5 :range [0 1])
+  )
+  (let* ((buffer (state-get 'buffer (list)))
+         (new-buffer (take (cons frame buffer) (+ num_echoes 1))))
+    (begin
+      (state-set 'buffer new-buffer)
+      ;; Blend frames with decay
+      (if (< (length new-buffer) 2)
+          frame
+          (let ((result (copy frame)))
+            ;; Simple blend of first two frames for now
+            ;; Full version would fold over all frames
+            (blending:blend-images frame (nth new-buffer 1) (* decay 0.5)))))))

sexp_effects/effects/edge_detect.sexp

@@ -0,0 +1,9 @@
+;; Edge detection effect - highlights edges
+(require-primitives "image")
+
+(define-effect edge_detect
+  :params (
+    (low :type int :default 50 :range [10 100])
+    (high :type int :default 150 :range [50 300])
+  )
+  (image:edge-detect frame low high))

sexp_effects/effects/emboss.sexp

@@ -0,0 +1,13 @@
+;; Emboss effect - creates raised/3D appearance
+(require-primitives "blending")
+
+(define-effect emboss
+  :params (
+    (strength :type int :default 1 :range [0.5 3])
+    (blend :type float :default 0.3 :range [0 1])
+  )
+  (let* ((kernel (list (list (- strength) (- strength) 0)
+                       (list (- strength) 1 strength)
+                       (list 0 strength strength)))
+         (embossed (convolve frame kernel)))
+    (blending:blend-images embossed frame blend)))

sexp_effects/effects/film_grain.sexp

@@ -0,0 +1,19 @@
+;; Film Grain effect - adds film grain texture
+(require-primitives "core")
+
+(define-effect film_grain
+  :params (
+    (intensity :type float :default 0.2 :range [0 1])
+    (colored :type bool :default false)
+  )
+  (let ((grain-amount (* intensity 50)))
+    (map-pixels frame
+      (lambda (x y c)
+        (if colored
+            (rgb (clamp (+ (red c) (gaussian 0 grain-amount)) 0 255)
+                 (clamp (+ (green c) (gaussian 0 grain-amount)) 0 255)
+                 (clamp (+ (blue c) (gaussian 0 grain-amount)) 0 255))
+            (let ((n (gaussian 0 grain-amount)))
+              (rgb (clamp (+ (red c) n) 0 255)
+                   (clamp (+ (green c) n) 0 255)
+                   (clamp (+ (blue c) n) 0 255))))))))

sexp_effects/effects/fisheye.sexp

@@ -0,0 +1,16 @@
+;; Fisheye effect - barrel/pincushion lens distortion
+(require-primitives "geometry" "image")
+
+(define-effect fisheye
+  :params (
+    (strength :type float :default 0.3 :range [-1 1])
+    (center_x :type float :default 0.5 :range [0 1])
+    (center_y :type float :default 0.5 :range [0 1])
+    (zoom_correct :type bool :default true)
+  )
+  (let* ((w (image:width frame))
+         (h (image:height frame))
+         (cx (* w center_x))
+         (cy (* h center_y))
+         (coords (geometry:fisheye-coords w h strength cx cy zoom_correct)))
+    (geometry:remap frame (geometry:coords-x coords) (geometry:coords-y coords))))

sexp_effects/effects/flip.sexp

@@ -0,0 +1,16 @@
+;; Flip effect - flips image horizontally or vertically
+(require-primitives "geometry")
+
+(define-effect flip
+  :params (
+    (horizontal :type bool :default true)
+    (vertical :type bool :default false)
+  )
+  (let ((result frame))
+    (if horizontal
+        (set! result (geometry:flip-img result "horizontal"))
+        nil)
+    (if vertical
+        (set! result (geometry:flip-img result "vertical"))
+        nil)
+    result))

sexp_effects/effects/grayscale.sexp

@@ -0,0 +1,7 @@
+;; Grayscale effect - converts to grayscale
+;; Uses vectorized mix-gray primitive for fast processing
+(require-primitives "image")
+
+(define-effect grayscale
+  :params ()
+  (image:grayscale frame))

sexp_effects/effects/hue_shift.sexp

@@ -0,0 +1,12 @@
+;; Hue shift effect - rotates hue values
+;; Uses vectorized shift-hsv primitive for fast processing
+
+(require-primitives "color_ops")
+
+(define-effect hue_shift
+  :params (
+    (degrees :type int :default 0 :range [0 360])
+    (speed :type int :default 0 :desc "rotation per second")
+  )
+  (let ((shift (+ degrees (* speed t))))
+    (color_ops:shift-hsv frame shift 1 1)))

sexp_effects/effects/invert.sexp

@@ -0,0 +1,9 @@
+;; Invert effect - inverts all colors
+;; Uses vectorized invert-img primitive for fast processing
+;; amount param: 0 = no invert, 1 = full invert (threshold at 0.5)
+
+(require-primitives "color_ops")
+
+(define-effect invert
+  :params ((amount :type float :default 1 :range [0 1]))
+  (if (> amount 0.5) (color_ops:invert-img frame) frame))

sexp_effects/effects/kaleidoscope.sexp

@@ -0,0 +1,20 @@
+;; Kaleidoscope effect - mandala-like symmetry patterns
+(require-primitives "geometry" "image")
+
+(define-effect kaleidoscope
+  :params (
+    (segments :type int :default 6 :range [3 16])
+    (rotation :type int :default 0 :range [0 360])
+    (rotation_speed :type int :default 0 :range [-180 180])
+    (center_x :type float :default 0.5 :range [0 1])
+    (center_y :type float :default 0.5 :range [0 1])
+    (zoom :type int :default 1 :range [0.5 3])
+  )
+  (let* ((w (image:width frame))
+         (h (image:height frame))
+         (cx (* w center_x))
+         (cy (* h center_y))
+         ;; Total rotation including time-based animation
+         (total_rot (+ rotation (* rotation_speed (or _time 0))))
+         (coords (geometry:kaleidoscope-coords w h segments total_rot cx cy zoom)))
+    (geometry:remap frame (geometry:coords-x coords) (geometry:coords-y coords))))

sexp_effects/effects/layer.sexp

@@ -0,0 +1,36 @@
+;; Layer effect - composite overlay over background at position
+;; Streaming-compatible: frame is background, overlay is foreground
+;; Usage: (layer background overlay :x 10 :y 20 :opacity 0.8)
+;;
+;; Params:
+;;   overlay - frame to composite on top
+;;   x, y - position to place overlay
+;;   opacity - blend amount (0-1)
+;;   mode - blend mode (alpha, multiply, screen, etc.)
+
+(require-primitives "image" "blending" "core")
+
+(define-effect layer
+  :params (
+    (overlay :type frame :default nil)
+    (x :type int :default 0)
+    (y :type int :default 0)
+    (opacity :type float :default 1.0)
+    (mode :type string :default "alpha")
+  )
+  (if (core:is-nil overlay)
+    frame
+    (let [bg (copy frame)
+          fg overlay
+          fg-w (image:width fg)
+          fg-h (image:height fg)]
+      (if (= opacity 1.0)
+        ;; Simple paste
+        (paste bg fg x y)
+        ;; Blend with opacity
+        (let [blended (if (= mode "alpha")
+                        (blending:blend-images (image:crop bg x y fg-w fg-h) fg opacity)
+                        (blending:blend-images (image:crop bg x y fg-w fg-h)
+                                     (blending:blend-mode (image:crop bg x y fg-w fg-h) fg mode)
+                                     opacity))]
+          (paste bg blended x y))))))

sexp_effects/effects/mirror.sexp

@@ -0,0 +1,33 @@
+;; Mirror effect - mirrors half of image
+(require-primitives "geometry" "image")
+
+(define-effect mirror
+  :params (
+    (mode :type string :default "left_right")
+  )
+  (let* ((w (image:width frame))
+         (h (image:height frame))
+         (hw (floor (/ w 2)))
+         (hh (floor (/ h 2))))
+    (cond
+      ((= mode "left_right")
+       (let ((left (image:crop frame 0 0 hw h))
+             (result (copy frame)))
+         (paste result (geometry:flip-img left "horizontal") hw 0)))
+
+      ((= mode "right_left")
+       (let ((right (image:crop frame hw 0 hw h))
+             (result (copy frame)))
+         (paste result (geometry:flip-img right "horizontal") 0 0)))
+
+      ((= mode "top_bottom")
+       (let ((top (image:crop frame 0 0 w hh))
+             (result (copy frame)))
+         (paste result (geometry:flip-img top "vertical") 0 hh)))
+
+      ((= mode "bottom_top")
+       (let ((bottom (image:crop frame 0 hh w hh))
+             (result (copy frame)))
+         (paste result (geometry:flip-img bottom "vertical") 0 0)))
+
+      (else frame))))

sexp_effects/effects/neon_glow.sexp

@@ -0,0 +1,23 @@
+;; Neon Glow effect - glowing edge effect
+(require-primitives "image" "blending")
+
+(define-effect neon_glow
+  :params (
+    (edge_low :type int :default 50 :range [10 200])
+    (edge_high :type int :default 150 :range [50 300])
+    (glow_radius :type int :default 15 :range [1 50])
+    (glow_intensity :type int :default 2 :range [0.5 5])
+    (background :type float :default 0.3 :range [0 1])
+  )
+  (let* ((edge-img (image:edge-detect frame edge_low edge_high))
+         (glow (image:blur edge-img glow_radius))
+         ;; Intensify the glow
+         (bright-glow (map-pixels glow
+                        (lambda (x y c)
+                          (rgb (clamp (* (red c) glow_intensity) 0 255)
+                               (clamp (* (green c) glow_intensity) 0 255)
+                               (clamp (* (blue c) glow_intensity) 0 255))))))
+    (blending:blend-mode (blending:blend-images frame (make-image (image:width frame) (image:height frame) (list 0 0 0))
+                              (- 1 background))
+                bright-glow
+                "screen")))

sexp_effects/effects/noise.sexp

@@ -0,0 +1,8 @@
+;; Noise effect - adds random noise
+;; Uses vectorized add-noise primitive for fast processing
+
+(define-effect noise
+  :params (
+    (amount :type int :default 20 :range [0 100])
+  )
+  (add-noise frame amount))

sexp_effects/effects/outline.sexp

@@ -0,0 +1,24 @@
+;; Outline effect - shows only edges
+(require-primitives "image")
+
+(define-effect outline
+  :params (
+    (thickness :type int :default 2 :range [1 10])
+    (threshold :type int :default 100 :range [20 300])
+    (color :type list :default (list 0 0 0)
+  )
+  (fill_mode "original"))
+  (let* ((edge-img (image:edge-detect frame (/ threshold 2) threshold))
+         (dilated (if (> thickness 1)
+                      (dilate edge-img thickness)
+                      edge-img))
+         (base (cond
+                 ((= fill_mode "original") (copy frame))
+                 ((= fill_mode "white") (make-image (image:width frame) (image:height frame) (list 255 255 255)))
+                 (else (make-image (image:width frame) (image:height frame) (list 0 0 0))))))
+    (map-pixels base
+      (lambda (x y c)
+        (let ((edge-val (luminance (pixel dilated x y))))
+          (if (> edge-val 128)
+              color
+              c))))))

sexp_effects/effects/pixelate.sexp

@@ -0,0 +1,13 @@
+;; Pixelate effect - creates blocky pixels
+(require-primitives "image")
+
+(define-effect pixelate
+  :params (
+    (block_size :type int :default 8 :range [2 64])
+  )
+  (let* ((w (image:width frame))
+         (h (image:height frame))
+         (small-w (max 1 (floor (/ w block_size))))
+         (small-h (max 1 (floor (/ h block_size))))
+         (small (image:resize frame small-w small-h "area")))
+    (image:resize small w h "nearest")))

sexp_effects/effects/pixelsort.sexp

@@ -0,0 +1,11 @@
+;; Pixelsort effect - glitch art pixel sorting
+
+(define-effect pixelsort
+  :params (
+    (sort_by :type string :default "lightness")
+    (threshold_low :type int :default 50 :range [0 255])
+    (threshold_high :type int :default 200 :range [0 255])
+    (angle :type int :default 0 :range [0 180])
+    (reverse :type bool :default false)
+  )
+  (pixelsort frame sort_by threshold_low threshold_high angle reverse))

sexp_effects/effects/posterize.sexp

@@ -0,0 +1,8 @@
+;; Posterize effect - reduces color levels
+(require-primitives "color_ops")
+
+(define-effect posterize
+  :params (
+    (levels :type int :default 8 :range [2 32])
+  )
+  (color_ops:posterize frame levels))

sexp_effects/effects/resize-frame.sexp

@@ -0,0 +1,11 @@
+;; Resize effect - replaces RESIZE node
+;; Note: uses target-w/target-h to avoid conflict with width/height primitives
+(require-primitives "image")
+
+(define-effect resize-frame
+  :params (
+    (target-w :type int :default 640 :desc "Target width in pixels")
+    (target-h :type int :default 480 :desc "Target height in pixels")
+    (mode :type string :default "linear" :choices [linear nearest area] :desc "Interpolation mode")
+  )
+  (image:resize frame target-w target-h mode))

sexp_effects/effects/rgb_split.sexp

@@ -0,0 +1,13 @@
+;; RGB Split effect - chromatic aberration
+
+(define-effect rgb_split
+  :params (
+    (offset_x :type int :default 10 :range [-50 50])
+    (offset_y :type int :default 0 :range [-50 50])
+  )
+  (let* ((r (channel frame 0))
+         (g (channel frame 1))
+         (b (channel frame 2))
+         (r-shifted (translate (merge-channels r r r) offset_x offset_y))
+         (b-shifted (translate (merge-channels b b b) (- offset_x) (- offset_y))))
+    (merge-channels (channel r-shifted 0) g (channel b-shifted 0))))

sexp_effects/effects/ripple.sexp

@@ -0,0 +1,19 @@
+;; Ripple effect - radial wave distortion from center
+(require-primitives "geometry" "image" "math")
+
+(define-effect ripple
+  :params (
+    (frequency :type int :default 5 :range [1 20])
+    (amplitude :type int :default 10 :range [0 50])
+    (center_x :type float :default 0.5 :range [0 1])
+    (center_y :type float :default 0.5 :range [0 1])
+    (decay :type int :default 1 :range [0 5])
+    (speed :type int :default 1 :range [0 10])
+  )
+  (let* ((w (image:width frame))
+         (h (image:height frame))
+         (cx (* w center_x))
+         (cy (* h center_y))
+         (phase (* (or t 0) speed 2 pi))
+         (coords (geometry:ripple-displace w h frequency amplitude cx cy decay phase)))
+    (geometry:remap frame (geometry:coords-x coords) (geometry:coords-y coords))))

sexp_effects/effects/rotate.sexp

@@ -0,0 +1,11 @@
+;; Rotate effect - rotates image
+
+(require-primitives "geometry")
+
+(define-effect rotate
+  :params (
+    (angle :type int :default 0 :range [-360 360])
+    (speed :type int :default 0 :desc "rotation per second")
+  )
+  (let ((total-angle (+ angle (* speed t))))
+    (geometry:rotate-img frame total-angle)))

sexp_effects/effects/saturation.sexp

@@ -0,0 +1,9 @@
+;; Saturation effect - adjusts color saturation
+;; Uses vectorized shift-hsv primitive for fast processing
+(require-primitives "color_ops")
+
+(define-effect saturation
+  :params (
+    (amount :type int :default 1 :range [0 3])
+  )
+  (color_ops:adjust-saturation frame amount))

sexp_effects/effects/scanlines.sexp

@@ -0,0 +1,15 @@
+;; Scanlines effect - VHS-style horizontal line shifting
+(require-primitives "core")
+
+(define-effect scanlines
+  :params (
+    (amplitude :type int :default 10 :range [0 100])
+    (frequency :type int :default 10 :range [1 100])
+    (randomness :type float :default 0.5 :range [0 1])
+  )
+  (map-rows frame
+    (lambda (y row)
+      (let* ((sine-shift (* amplitude (sin (/ (* y 6.28) (max 1 frequency)))))
+             (rand-shift (core:rand-range (- amplitude) amplitude))
+             (shift (floor (lerp sine-shift rand-shift randomness))))
+        (roll row shift 0)))))

sexp_effects/effects/sepia.sexp

@@ -0,0 +1,7 @@
+;; Sepia effect - applies sepia tone
+;; Classic warm vintage look
+(require-primitives "color_ops")
+
+(define-effect sepia
+  :params ()
+  (color_ops:sepia frame))

sexp_effects/effects/sharpen.sexp

@@ -0,0 +1,8 @@
+;; Sharpen effect - sharpens edges
+(require-primitives "image")
+
+(define-effect sharpen
+  :params (
+    (amount :type int :default 1 :range [0 5])
+  )
+  (image:sharpen frame amount))

sexp_effects/effects/strobe.sexp

@@ -0,0 +1,16 @@
+;; Strobe effect - holds frames for choppy look
+(require-primitives "core")
+
+(define-effect strobe
+  :params (
+    (frame_rate :type int :default 12 :range [1 60])
+  )
+  (let* ((held (state-get 'held nil))
+         (held-until (state-get 'held-until 0))
+         (frame-duration (/ 1 frame_rate)))
+    (if (or (core:is-nil held) (>= t held-until))
+        (begin
+          (state-set 'held (copy frame))
+          (state-set 'held-until (+ t frame-duration))
+          frame)
+        held)))

sexp_effects/effects/swirl.sexp

@@ -0,0 +1,17 @@
+;; Swirl effect - spiral vortex distortion
+(require-primitives "geometry" "image")
+
+(define-effect swirl
+  :params (
+    (strength :type int :default 1 :range [-10 10])
+    (radius :type float :default 0.5 :range [0.1 2])
+    (center_x :type float :default 0.5 :range [0 1])
+    (center_y :type float :default 0.5 :range [0 1])
+    (falloff :type string :default "quadratic")
+  )
+  (let* ((w (image:width frame))
+         (h (image:height frame))
+         (cx (* w center_x))
+         (cy (* h center_y))
+         (coords (geometry:swirl-coords w h strength radius cx cy falloff)))
+    (geometry:remap frame (geometry:coords-x coords) (geometry:coords-y coords))))

sexp_effects/effects/threshold.sexp

@@ -0,0 +1,9 @@
+;; Threshold effect - converts to black and white
+(require-primitives "color_ops")
+
+(define-effect threshold
+  :params (
+    (level :type int :default 128 :range [0 255])
+    (invert :type bool :default false)
+  )
+  (color_ops:threshold frame level invert))

sexp_effects/effects/tile_grid.sexp

@@ -0,0 +1,29 @@
+;; Tile Grid effect - tiles image in grid
+(require-primitives "geometry" "image")
+
+(define-effect tile_grid
+  :params (
+    (rows :type int :default 2 :range [1 10])
+    (cols :type int :default 2 :range [1 10])
+    (gap :type int :default 0 :range [0 50])
+  )
+  (let* ((w (image:width frame))
+         (h (image:height frame))
+         (tile-w (floor (/ (- w (* gap (- cols 1))) cols)))
+         (tile-h (floor (/ (- h (* gap (- rows 1))) rows)))
+         (tile (image:resize frame tile-w tile-h "area"))
+         (result (make-image w h (list 0 0 0))))
+    (begin
+      ;; Manually place tiles using nested iteration
+      ;; This is a simplified version - full version would loop
+      (paste result tile 0 0)
+      (if (> cols 1)
+          (paste result tile (+ tile-w gap) 0)
+          nil)
+      (if (> rows 1)
+          (paste result tile 0 (+ tile-h gap))
+          nil)
+      (if (and (> cols 1) (> rows 1))
+          (paste result tile (+ tile-w gap) (+ tile-h gap))
+          nil)
+      result)))

sexp_effects/effects/trails.sexp

@@ -0,0 +1,20 @@
+;; Trails effect - persistent motion trails
+(require-primitives "image" "blending")
+
+(define-effect trails
+  :params (
+    (persistence :type float :default 0.8 :range [0 0.99])
+  )
+  (let* ((buffer (state-get 'buffer nil))
+         (current frame))
+    (if (= buffer nil)
+        (begin
+          (state-set 'buffer (copy frame))
+          frame)
+        (let* ((faded (blending:blend-images buffer
+                                    (make-image (image:width frame) (image:height frame) (list 0 0 0))
+                                    (- 1 persistence)))
+               (result (blending:blend-mode faded current "lighten")))
+          (begin
+            (state-set 'buffer result)
+            result)))))

sexp_effects/effects/vignette.sexp

@@ -0,0 +1,23 @@
+;; Vignette effect - darkens corners
+(require-primitives "image")
+
+(define-effect vignette
+  :params (
+    (strength :type float :default 0.5 :range [0 1])
+    (radius :type int :default 1 :range [0.5 2])
+  )
+  (let* ((w (image:width frame))
+         (h (image:height frame))
+         (cx (/ w 2))
+         (cy (/ h 2))
+         (max-dist (* (sqrt (+ (* cx cx) (* cy cy))) radius)))
+    (map-pixels frame
+      (lambda (x y c)
+        (let* ((dx (- x cx))
+               (dy (- y cy))
+               (dist (sqrt (+ (* dx dx) (* dy dy))))
+               (factor (- 1 (* (/ dist max-dist) strength)))
+               (factor (clamp factor 0 1)))
+          (rgb (* (red c) factor)
+               (* (green c) factor)
+               (* (blue c) factor)))))))

sexp_effects/effects/wave.sexp

@@ -0,0 +1,22 @@
+;; Wave effect - sine wave displacement distortion
+(require-primitives "geometry" "image")
+
+(define-effect wave
+  :params (
+    (amplitude :type int :default 10 :range [0 100])
+    (wavelength :type int :default 50 :range [10 500])
+    (speed :type int :default 1 :range [0 10])
+    (direction :type string :default "horizontal")
+  )
+  (let* ((w (image:width frame))
+         (h (image:height frame))
+         ;; Use _time for animation phase
+         (phase (* (or _time 0) speed 2 pi))
+         ;; Calculate frequency: waves per dimension
+         (freq (/ (if (= direction "vertical") w h) wavelength))
+         (axis (cond
+                 ((= direction "horizontal") "x")
+                 ((= direction "vertical") "y")
+                 (else "both")))
+         (coords (geometry:wave-coords w h axis freq amplitude phase)))
+    (geometry:remap frame (geometry:coords-x coords) (geometry:coords-y coords))))

sexp_effects/effects/zoom.sexp

@@ -0,0 +1,8 @@
+;; Zoom effect - zooms in/out from center
+(require-primitives "geometry")
+
+(define-effect zoom
+  :params (
+    (amount :type int :default 1 :range [0.1 5])
+  )
+  (geometry:scale-img frame amount amount))

sexp_effects/parser.py

@@ -0,0 +1,168 @@
+"""
+S-Expression Parser
+
+Parses S-expressions into Python data structures:
+- Lists become Python lists
+- Symbols become Symbol objects
+- Numbers become int/float
+- Strings become str
+- Keywords (:foo) become Keyword objects
+"""
+
+import re
+from dataclasses import dataclass
+from typing import Any, List, Union
+
+
+@dataclass(frozen=True)
+class Symbol:
+    """A symbol (identifier) in the S-expression."""
+    name: str
+
+    def __repr__(self):
+        return self.name
+
+
+@dataclass(frozen=True)
+class Keyword:
+    """A keyword like :foo in the S-expression."""
+    name: str
+
+    def __repr__(self):
+        return f":{self.name}"
+
+
+# Token patterns
+TOKEN_PATTERNS = [
+    (r'\s+', None),  # Whitespace (skip)
+    (r';[^\n]*', None),  # Comments (skip)
+    (r'\(', 'LPAREN'),
+    (r'\)', 'RPAREN'),
+    (r'\[', 'LBRACKET'),
+    (r'\]', 'RBRACKET'),
+    (r"'", 'QUOTE'),
+    (r'"([^"\\]|\\.)*"', 'STRING'),
+    (r':[a-zA-Z_][a-zA-Z0-9_\-]*', 'KEYWORD'),
+    (r'-?[0-9]+\.[0-9]+', 'FLOAT'),
+    (r'-?[0-9]+', 'INT'),
+    (r'#t|#f|true|false', 'BOOL'),
+    (r'[a-zA-Z_+\-*/<>=!?][a-zA-Z0-9_+\-*/<>=!?]*', 'SYMBOL'),
+]
+
+TOKEN_REGEX = '|'.join(f'(?P<{name}>{pattern})' if name else f'(?:{pattern})'
+                       for pattern, name in TOKEN_PATTERNS)
+
+
+def tokenize(source: str) -> List[tuple]:
+    """Tokenize S-expression source code."""
+    tokens = []
+    for match in re.finditer(TOKEN_REGEX, source):
+        kind = match.lastgroup
+        value = match.group()
+        if kind:
+            tokens.append((kind, value))
+    return tokens
+
+
+def parse(source: str) -> Any:
+    """Parse S-expression source into Python data structures."""
+    tokens = tokenize(source)
+    pos = [0]  # Use list for mutability in nested function
+
+    def parse_expr():
+        if pos[0] >= len(tokens):
+            raise SyntaxError("Unexpected end of input")
+
+        kind, value = tokens[pos[0]]
+
+        if kind == 'LPAREN':
+            pos[0] += 1
+            items = []
+            while pos[0] < len(tokens) and tokens[pos[0]][0] != 'RPAREN':
+                items.append(parse_expr())
+            if pos[0] >= len(tokens):
+                raise SyntaxError("Missing closing parenthesis")
+            pos[0] += 1  # Skip RPAREN
+            return items
+
+        if kind == 'LBRACKET':
+            pos[0] += 1
+            items = []
+            while pos[0] < len(tokens) and tokens[pos[0]][0] != 'RBRACKET':
+                items.append(parse_expr())
+            if pos[0] >= len(tokens):
+                raise SyntaxError("Missing closing bracket")
+            pos[0] += 1  # Skip RBRACKET
+            return items
+
+        elif kind == 'RPAREN':
+            raise SyntaxError("Unexpected closing parenthesis")
+
+        elif kind == 'QUOTE':
+            pos[0] += 1
+            return [Symbol('quote'), parse_expr()]
+
+        elif kind == 'STRING':
+            pos[0] += 1
+            # Remove quotes and unescape
+            return value[1:-1].replace('\\"', '"').replace('\\n', '\n')
+
+        elif kind == 'INT':
+            pos[0] += 1
+            return int(value)
+
+        elif kind == 'FLOAT':
+            pos[0] += 1
+            return float(value)
+
+        elif kind == 'BOOL':
+            pos[0] += 1
+            return value in ('#t', 'true')
+
+        elif kind == 'KEYWORD':
+            pos[0] += 1
+            return Keyword(value[1:])  # Remove leading :
+
+        elif kind == 'SYMBOL':
+            pos[0] += 1
+            return Symbol(value)
+
+        else:
+            raise SyntaxError(f"Unknown token: {kind} {value}")
+
+    result = parse_expr()
+
+    # Check for multiple top-level expressions
+    if pos[0] < len(tokens):
+        # Allow multiple top-level expressions, return as list
+        results = [result]
+        while pos[0] < len(tokens):
+            results.append(parse_expr())
+        return results
+
+    return result
+
+
+def parse_file(path: str) -> Any:
+    """Parse an S-expression file."""
+    with open(path, 'r') as f:
+        return parse(f.read())
+
+
+# Convenience for pretty-printing
+def to_sexp(obj: Any) -> str:
+    """Convert Python object back to S-expression string."""
+    if isinstance(obj, list):
+        return '(' + ' '.join(to_sexp(x) for x in obj) + ')'
+    elif isinstance(obj, Symbol):
+        return obj.name
+    elif isinstance(obj, Keyword):
+        return f':{obj.name}'
+    elif isinstance(obj, str):
+        return f'"{obj}"'
+    elif isinstance(obj, bool):
+        return '#t' if obj else '#f'
+    elif isinstance(obj, (int, float)):
+        return str(obj)
+    else:
+        return repr(obj)

sexp_effects/primitive_libs/__init__.py

@@ -0,0 +1,102 @@
+"""
+Primitive Libraries System
+
+Provides modular loading of primitives. Core primitives are always available,
+additional primitive libraries can be loaded on-demand with scoped availability.
+
+Usage in sexp:
+    ;; Load at recipe level - available throughout
+    (primitives math :path "primitive_libs/math.py")
+
+    ;; Or use with-primitives for scoped access
+    (with-primitives "image"
+      (blur frame 3))  ;; blur only available inside
+
+    ;; Nested scopes work
+    (with-primitives "math"
+      (with-primitives "color"
+        (hue-shift frame (* (sin t) 30))))
+
+Library file format (primitive_libs/math.py):
+    import math
+
+    def prim_sin(x): return math.sin(x)
+    def prim_cos(x): return math.cos(x)
+
+    PRIMITIVES = {
+        'sin': prim_sin,
+        'cos': prim_cos,
+    }
+"""
+
+import importlib.util
+from pathlib import Path
+from typing import Dict, Callable, Any, Optional
+
+# Cache of loaded primitive libraries
+_library_cache: Dict[str, Dict[str, Any]] = {}
+
+# Core primitives - always available, cannot be overridden
+CORE_PRIMITIVES: Dict[str, Any] = {}
+
+
+def register_core_primitive(name: str, fn: Callable):
+    """Register a core primitive that's always available."""
+    CORE_PRIMITIVES[name] = fn
+
+
+def load_primitive_library(name: str, path: Optional[str] = None) -> Dict[str, Any]:
+    """
+    Load a primitive library by name or path.
+
+    Args:
+        name: Library name (e.g., "math", "image", "color")
+        path: Optional explicit path to library file
+
+    Returns:
+        Dict of primitive name -> function
+    """
+    # Check cache first
+    cache_key = path or name
+    if cache_key in _library_cache:
+        return _library_cache[cache_key]
+
+    # Find library file
+    if path:
+        lib_path = Path(path)
+    else:
+        # Look in standard locations
+        lib_dir = Path(__file__).parent
+        lib_path = lib_dir / f"{name}.py"
+
+        if not lib_path.exists():
+            raise ValueError(f"Primitive library '{name}' not found at {lib_path}")
+
+    if not lib_path.exists():
+        raise ValueError(f"Primitive library file not found: {lib_path}")
+
+    # Load the module
+    spec = importlib.util.spec_from_file_location(f"prim_lib_{name}", lib_path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+
+    # Get PRIMITIVES dict from module
+    if not hasattr(module, 'PRIMITIVES'):
+        raise ValueError(f"Primitive library '{name}' missing PRIMITIVES dict")
+
+    primitives = module.PRIMITIVES
+
+    # Cache and return
+    _library_cache[cache_key] = primitives
+    return primitives
+
+
+def get_library_names() -> list:
+    """Get names of available primitive libraries."""
+    lib_dir = Path(__file__).parent
+    return [p.stem for p in lib_dir.glob("*.py") if p.stem != "__init__"]
+
+
+def clear_cache():
+    """Clear the library cache (useful for testing)."""
+    _library_cache.clear()

sexp_effects/primitive_libs/arrays.py

@@ -0,0 +1,196 @@
+"""
+Array Primitives Library
+
+Vectorized operations on numpy arrays for coordinate transformations.
+"""
+import numpy as np
+
+
+# Arithmetic
+def prim_arr_add(a, b):
+    return np.add(a, b)
+
+
+def prim_arr_sub(a, b):
+    return np.subtract(a, b)
+
+
+def prim_arr_mul(a, b):
+    return np.multiply(a, b)
+
+
+def prim_arr_div(a, b):
+    return np.divide(a, b)
+
+
+def prim_arr_mod(a, b):
+    return np.mod(a, b)
+
+
+def prim_arr_neg(a):
+    return np.negative(a)
+
+
+# Math functions
+def prim_arr_sin(a):
+    return np.sin(a)
+
+
+def prim_arr_cos(a):
+    return np.cos(a)
+
+
+def prim_arr_tan(a):
+    return np.tan(a)
+
+
+def prim_arr_sqrt(a):
+    return np.sqrt(np.maximum(a, 0))
+
+
+def prim_arr_pow(a, b):
+    return np.power(a, b)
+
+
+def prim_arr_abs(a):
+    return np.abs(a)
+
+
+def prim_arr_exp(a):
+    return np.exp(a)
+
+
+def prim_arr_log(a):
+    return np.log(np.maximum(a, 1e-10))
+
+
+def prim_arr_atan2(y, x):
+    return np.arctan2(y, x)
+
+
+# Comparison / selection
+def prim_arr_min(a, b):
+    return np.minimum(a, b)
+
+
+def prim_arr_max(a, b):
+    return np.maximum(a, b)
+
+
+def prim_arr_clip(a, lo, hi):
+    return np.clip(a, lo, hi)
+
+
+def prim_arr_where(cond, a, b):
+    return np.where(cond, a, b)
+
+
+def prim_arr_floor(a):
+    return np.floor(a)
+
+
+def prim_arr_ceil(a):
+    return np.ceil(a)
+
+
+def prim_arr_round(a):
+    return np.round(a)
+
+
+# Interpolation
+def prim_arr_lerp(a, b, t):
+    return a + (b - a) * t
+
+
+def prim_arr_smoothstep(edge0, edge1, x):
+    t = prim_arr_clip((x - edge0) / (edge1 - edge0), 0.0, 1.0)
+    return t * t * (3 - 2 * t)
+
+
+# Creation
+def prim_arr_zeros(shape):
+    return np.zeros(shape, dtype=np.float32)
+
+
+def prim_arr_ones(shape):
+    return np.ones(shape, dtype=np.float32)
+
+
+def prim_arr_full(shape, value):
+    return np.full(shape, value, dtype=np.float32)
+
+
+def prim_arr_arange(start, stop, step=1):
+    return np.arange(start, stop, step, dtype=np.float32)
+
+
+def prim_arr_linspace(start, stop, num):
+    return np.linspace(start, stop, num, dtype=np.float32)
+
+
+def prim_arr_meshgrid(x, y):
+    return np.meshgrid(x, y)
+
+
+# Coordinate transforms
+def prim_polar_from_center(map_x, map_y, cx, cy):
+    """Convert Cartesian to polar coordinates centered at (cx, cy)."""
+    dx = map_x - cx
+    dy = map_y - cy
+    r = np.sqrt(dx**2 + dy**2)
+    theta = np.arctan2(dy, dx)
+    return (r, theta)
+
+
+def prim_cart_from_polar(r, theta, cx, cy):
+    """Convert polar to Cartesian, adding center offset."""
+    x = r * np.cos(theta) + cx
+    y = r * np.sin(theta) + cy
+    return (x, y)
+
+
+PRIMITIVES = {
+    # Arithmetic
+    'arr+': prim_arr_add,
+    'arr-': prim_arr_sub,
+    'arr*': prim_arr_mul,
+    'arr/': prim_arr_div,
+    'arr-mod': prim_arr_mod,
+    'arr-neg': prim_arr_neg,
+
+    # Math
+    'arr-sin': prim_arr_sin,
+    'arr-cos': prim_arr_cos,
+    'arr-tan': prim_arr_tan,
+    'arr-sqrt': prim_arr_sqrt,
+    'arr-pow': prim_arr_pow,
+    'arr-abs': prim_arr_abs,
+    'arr-exp': prim_arr_exp,
+    'arr-log': prim_arr_log,
+    'arr-atan2': prim_arr_atan2,
+
+    # Selection
+    'arr-min': prim_arr_min,
+    'arr-max': prim_arr_max,
+    'arr-clip': prim_arr_clip,
+    'arr-where': prim_arr_where,
+    'arr-floor': prim_arr_floor,
+    'arr-ceil': prim_arr_ceil,
+    'arr-round': prim_arr_round,
+
+    # Interpolation
+    'arr-lerp': prim_arr_lerp,
+    'arr-smoothstep': prim_arr_smoothstep,
+
+    # Creation
+    'arr-zeros': prim_arr_zeros,
+    'arr-ones': prim_arr_ones,
+    'arr-full': prim_arr_full,
+    'arr-arange': prim_arr_arange,
+    'arr-linspace': prim_arr_linspace,
+    'arr-meshgrid': prim_arr_meshgrid,
+
+    # Coordinates
+    'polar-from-center': prim_polar_from_center,
+    'cart-from-polar': prim_cart_from_polar,
+}

sexp_effects/primitive_libs/ascii.py

@@ -0,0 +1,388 @@
+"""
+ASCII Art Primitives Library
+
+ASCII art rendering with per-zone expression evaluation and cell effects.
+"""
+import numpy as np
+import cv2
+from PIL import Image, ImageDraw, ImageFont
+from typing import Any, Dict, List, Optional, Callable
+import colorsys
+
+
+# Character sets
+CHAR_SETS = {
+    "standard": " .:-=+*#%@",
+    "blocks": " ░▒▓█",
+    "simple": " .:oO@",
+    "digits": "0123456789",
+    "binary": "01",
+    "ascii": " `.-':_,^=;><+!rc*/z?sLTv)J7(|Fi{C}fI31tlu[neoZ5Yxjya]2ESwqkP6h9d4VpOGbUAKXHm8RD#$Bg0MNWQ%&@",
+}
+
+# Default font
+_default_font = None
+
+
+def _get_font(size: int):
+    """Get monospace font at given size."""
+    global _default_font
+    try:
+        return ImageFont.truetype("/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf", size)
+    except:
+        return ImageFont.load_default()
+
+
+def _parse_color(color_str: str) -> tuple:
+    """Parse color string to RGB tuple."""
+    if color_str.startswith('#'):
+        hex_color = color_str[1:]
+        if len(hex_color) == 3:
+            hex_color = ''.join(c*2 for c in hex_color)
+        return tuple(int(hex_color[i:i+2], 16) for i in (0, 2, 4))
+
+    colors = {
+        'black': (0, 0, 0), 'white': (255, 255, 255),
+        'red': (255, 0, 0), 'green': (0, 255, 0), 'blue': (0, 0, 255),
+        'yellow': (255, 255, 0), 'cyan': (0, 255, 255), 'magenta': (255, 0, 255),
+        'gray': (128, 128, 128), 'grey': (128, 128, 128),
+    }
+    return colors.get(color_str.lower(), (0, 0, 0))
+
+
+def _cell_sample(frame: np.ndarray, cell_size: int):
+    """Sample frame into cells, returning colors and luminances.
+
+    Uses cv2.resize with INTER_AREA (pixel-area averaging) which is
+    ~25x faster than numpy reshape+mean for block downsampling.
+    """
+    h, w = frame.shape[:2]
+    rows = h // cell_size
+    cols = w // cell_size
+
+    # Crop to exact grid then block-average via cv2 area interpolation.
+    cropped = frame[:rows * cell_size, :cols * cell_size]
+    colors = cv2.resize(cropped, (cols, rows), interpolation=cv2.INTER_AREA)
+
+    luminances = ((0.299 * colors[:, :, 0] +
+                    0.587 * colors[:, :, 1] +
+                    0.114 * colors[:, :, 2]) / 255.0).astype(np.float32)
+
+    return colors, luminances
+
+
+def _luminance_to_char(lum: float, alphabet: str, contrast: float) -> str:
+    """Map luminance to character."""
+    chars = CHAR_SETS.get(alphabet, alphabet)
+    lum = ((lum - 0.5) * contrast + 0.5)
+    lum = max(0, min(1, lum))
+    idx = int(lum * (len(chars) - 1))
+    return chars[idx]
+
+
+def _render_char_cell(char: str, cell_size: int, color: tuple, bg_color: tuple) -> np.ndarray:
+    """Render a single character to a cell image."""
+    img = Image.new('RGB', (cell_size, cell_size), bg_color)
+    draw = ImageDraw.Draw(img)
+    font = _get_font(cell_size)
+
+    # Center the character
+    bbox = draw.textbbox((0, 0), char, font=font)
+    text_w = bbox[2] - bbox[0]
+    text_h = bbox[3] - bbox[1]
+    x = (cell_size - text_w) // 2
+    y = (cell_size - text_h) // 2 - bbox[1]
+
+    draw.text((x, y), char, fill=color, font=font)
+    return np.array(img)
+
+
+def prim_ascii_fx_zone(
+    frame: np.ndarray,
+    cols: int = 80,
+    char_size: int = None,
+    alphabet: str = "standard",
+    color_mode: str = "color",
+    background: str = "black",
+    contrast: float = 1.5,
+    char_hue = None,
+    char_saturation = None,
+    char_brightness = None,
+    char_scale = None,
+    char_rotation = None,
+    char_jitter = None,
+    cell_effect = None,
+    energy: float = None,
+    rotation_scale: float = 0,
+    _interp = None,
+    _env = None,
+    **extra_params
+) -> np.ndarray:
+    """
+    Render frame as ASCII art with per-zone effects.
+
+    Args:
+        frame: Input image
+        cols: Number of character columns
+        char_size: Cell size in pixels (overrides cols if set)
+        alphabet: Character set name or custom string
+        color_mode: "color", "mono", "invert", or color name
+        background: Background color name or hex
+        contrast: Contrast for character selection
+        char_hue/saturation/brightness/scale/rotation/jitter: Per-zone expressions
+        cell_effect: Lambda (cell, zone) -> cell for per-cell effects
+        energy: Energy value from audio analysis
+        rotation_scale: Max rotation degrees
+        _interp: Interpreter (auto-injected)
+        _env: Environment (auto-injected)
+        **extra_params: Additional params passed to zone dict
+    """
+    h, w = frame.shape[:2]
+
+    # Calculate cell size
+    if char_size is None or char_size == 0:
+        cell_size = max(4, w // cols)
+    else:
+        cell_size = max(4, int(char_size))
+
+    # Sample cells
+    colors, luminances = _cell_sample(frame, cell_size)
+    rows, cols_actual = luminances.shape
+
+    # Parse background color
+    bg_color = _parse_color(background)
+
+    # Create output image
+    out_h = rows * cell_size
+    out_w = cols_actual * cell_size
+    output = np.full((out_h, out_w, 3), bg_color, dtype=np.uint8)
+
+    # Check if we have cell_effect
+    has_cell_effect = cell_effect is not None
+
+    # Process each cell
+    for r in range(rows):
+        for c in range(cols_actual):
+            lum = luminances[r, c]
+            cell_color = tuple(colors[r, c])
+
+            # Build zone context
+            zone = {
+                'row': r,
+                'col': c,
+                'row-norm': r / max(1, rows - 1),
+                'col-norm': c / max(1, cols_actual - 1),
+                'lum': float(lum),
+                'r': cell_color[0] / 255,
+                'g': cell_color[1] / 255,
+                'b': cell_color[2] / 255,
+                'cell_size': cell_size,
+            }
+
+            # Add HSV
+            r_f, g_f, b_f = cell_color[0]/255, cell_color[1]/255, cell_color[2]/255
+            hsv = colorsys.rgb_to_hsv(r_f, g_f, b_f)
+            zone['hue'] = hsv[0] * 360
+            zone['sat'] = hsv[1]
+
+            # Add energy and rotation_scale
+            if energy is not None:
+                zone['energy'] = energy
+            zone['rotation_scale'] = rotation_scale
+
+            # Add extra params
+            for k, v in extra_params.items():
+                if isinstance(v, (int, float, str, bool)) or v is None:
+                    zone[k] = v
+
+            # Get character
+            char = _luminance_to_char(lum, alphabet, contrast)
+            zone['char'] = char
+
+            # Determine cell color based on mode
+            if color_mode == "mono":
+                render_color = (255, 255, 255)
+            elif color_mode == "invert":
+                render_color = tuple(255 - c for c in cell_color)
+            elif color_mode == "color":
+                render_color = cell_color
+            else:
+                render_color = _parse_color(color_mode)
+
+            zone['color'] = render_color
+
+            # Render character to cell
+            cell_img = _render_char_cell(char, cell_size, render_color, bg_color)
+
+            # Apply cell_effect if provided
+            if has_cell_effect and _interp is not None:
+                cell_img = _apply_cell_effect(cell_img, zone, cell_effect, _interp, _env, extra_params)
+
+            # Paste cell to output
+            y1, y2 = r * cell_size, (r + 1) * cell_size
+            x1, x2 = c * cell_size, (c + 1) * cell_size
+            output[y1:y2, x1:x2] = cell_img
+
+    # Resize to match input dimensions
+    if output.shape[:2] != frame.shape[:2]:
+        output = cv2.resize(output, (w, h), interpolation=cv2.INTER_LINEAR)
+
+    return output
+
+
+def _apply_cell_effect(cell_img, zone, cell_effect, interp, env, extra_params):
+    """Apply cell_effect lambda to a cell image.
+
+    cell_effect is a Lambda object with params and body.
+    We create a child environment with zone variables and cell,
+    then evaluate the lambda body.
+    """
+    # Get Environment class from the interpreter's module
+    Environment = type(env)
+
+    # Create child environment with zone variables
+    cell_env = Environment(env)
+
+    # Bind zone variables
+    for k, v in zone.items():
+        cell_env.set(k, v)
+
+    # Also bind with zone- prefix for consistency
+    cell_env.set('zone-row', zone.get('row', 0))
+    cell_env.set('zone-col', zone.get('col', 0))
+    cell_env.set('zone-row-norm', zone.get('row-norm', 0))
+    cell_env.set('zone-col-norm', zone.get('col-norm', 0))
+    cell_env.set('zone-lum', zone.get('lum', 0))
+    cell_env.set('zone-sat', zone.get('sat', 0))
+    cell_env.set('zone-hue', zone.get('hue', 0))
+    cell_env.set('zone-r', zone.get('r', 0))
+    cell_env.set('zone-g', zone.get('g', 0))
+    cell_env.set('zone-b', zone.get('b', 0))
+
+    # Inject loaded effects as callable functions
+    if hasattr(interp, 'effects'):
+        for effect_name in interp.effects:
+            def make_effect_fn(name):
+                def effect_fn(frame, *args):
+                    params = {}
+                    if name == 'blur' and len(args) >= 1:
+                        params['radius'] = args[0]
+                    elif name == 'rotate' and len(args) >= 1:
+                        params['angle'] = args[0]
+                    elif name == 'brightness' and len(args) >= 1:
+                        params['amount'] = args[0]
+                    elif name == 'contrast' and len(args) >= 1:
+                        params['amount'] = args[0]
+                    elif name == 'saturation' and len(args) >= 1:
+                        params['amount'] = args[0]
+                    elif name == 'hue_shift' and len(args) >= 1:
+                        params['degrees'] = args[0]
+                    elif name == 'rgb_split' and len(args) >= 2:
+                        params['offset_x'] = args[0]
+                        params['offset_y'] = args[1]
+                    elif name == 'pixelate' and len(args) >= 1:
+                        params['size'] = args[0]
+                    elif name == 'invert':
+                        pass
+                    result, _ = interp.run_effect(name, frame, params, {})
+                    return result
+                return effect_fn
+            cell_env.set(effect_name, make_effect_fn(effect_name))
+
+    # Bind cell image and zone dict
+    cell_env.set('cell', cell_img)
+    cell_env.set('zone', zone)
+
+    # Evaluate the cell_effect lambda
+    # Lambda has params and body - we need to bind the params then evaluate
+    if hasattr(cell_effect, 'params') and hasattr(cell_effect, 'body'):
+        # Bind lambda parameters: (lambda [cell zone] body)
+        if len(cell_effect.params) >= 1:
+            cell_env.set(cell_effect.params[0], cell_img)
+        if len(cell_effect.params) >= 2:
+            cell_env.set(cell_effect.params[1], zone)
+
+        result = interp.eval(cell_effect.body, cell_env)
+    elif isinstance(cell_effect, list):
+        # Raw S-expression lambda like (lambda [cell zone] body) or (fn [cell zone] body)
+        # Check if it's a lambda expression
+        head = cell_effect[0] if cell_effect else None
+        head_name = head.name if head and hasattr(head, 'name') else str(head) if head else None
+        is_lambda = head_name in ('lambda', 'fn')
+
+        if is_lambda:
+            # (lambda [params...] body)
+            params = cell_effect[1] if len(cell_effect) > 1 else []
+            body = cell_effect[2] if len(cell_effect) > 2 else None
+
+            # Bind lambda parameters
+            if isinstance(params, list) and len(params) >= 1:
+                param_name = params[0].name if hasattr(params[0], 'name') else str(params[0])
+                cell_env.set(param_name, cell_img)
+            if isinstance(params, list) and len(params) >= 2:
+                param_name = params[1].name if hasattr(params[1], 'name') else str(params[1])
+                cell_env.set(param_name, zone)
+
+            result = interp.eval(body, cell_env) if body else cell_img
+        else:
+            # Some other expression - just evaluate it
+            result = interp.eval(cell_effect, cell_env)
+    elif callable(cell_effect):
+        # It's a callable
+        result = cell_effect(cell_img, zone)
+    else:
+        raise ValueError(f"cell_effect must be a Lambda, list, or callable, got {type(cell_effect)}")
+
+    if isinstance(result, np.ndarray) and result.shape == cell_img.shape:
+        return result
+    elif isinstance(result, np.ndarray):
+        # Shape mismatch - resize to fit
+        result = cv2.resize(result, (cell_img.shape[1], cell_img.shape[0]))
+        return result
+
+    raise ValueError(f"cell_effect must return an image array, got {type(result)}")
+
+
+def _get_legacy_ascii_primitives():
+    """Import ASCII primitives from legacy primitives module.
+
+    These are loaded lazily to avoid import issues during module loading.
+    By the time a primitive library is loaded, sexp_effects.primitives
+    is already in sys.modules (imported by sexp_effects.__init__).
+    """
+    from sexp_effects.primitives import (
+        prim_cell_sample,
+        prim_luminance_to_chars,
+        prim_render_char_grid,
+        prim_render_char_grid_fx,
+        prim_alphabet_char,
+        prim_alphabet_length,
+        prim_map_char_grid,
+        prim_map_colors,
+        prim_make_char_grid,
+        prim_set_char,
+        prim_get_char,
+        prim_char_grid_dimensions,
+        cell_sample_extended,
+    )
+    return {
+        'cell-sample': prim_cell_sample,
+        'cell-sample-extended': cell_sample_extended,
+        'luminance-to-chars': prim_luminance_to_chars,
+        'render-char-grid': prim_render_char_grid,
+        'render-char-grid-fx': prim_render_char_grid_fx,
+        'alphabet-char': prim_alphabet_char,
+        'alphabet-length': prim_alphabet_length,
+        'map-char-grid': prim_map_char_grid,
+        'map-colors': prim_map_colors,
+        'make-char-grid': prim_make_char_grid,
+        'set-char': prim_set_char,
+        'get-char': prim_get_char,
+        'char-grid-dimensions': prim_char_grid_dimensions,
+    }
+
+
+PRIMITIVES = {
+    'ascii-fx-zone': prim_ascii_fx_zone,
+    **_get_legacy_ascii_primitives(),
+}

sexp_effects/primitive_libs/blending.py

@@ -0,0 +1,116 @@
+"""
+Blending Primitives Library
+
+Image blending and compositing operations.
+"""
+import numpy as np
+
+
+def prim_blend_images(a, b, alpha):
+    """Blend two images: a * (1-alpha) + b * alpha."""
+    alpha = max(0.0, min(1.0, alpha))
+    return (a.astype(float) * (1 - alpha) + b.astype(float) * alpha).astype(np.uint8)
+
+
+def prim_blend_mode(a, b, mode):
+    """Blend using Photoshop-style blend modes."""
+    a = a.astype(float) / 255
+    b = b.astype(float) / 255
+
+    if mode == "multiply":
+        result = a * b
+    elif mode == "screen":
+        result = 1 - (1 - a) * (1 - b)
+    elif mode == "overlay":
+        mask = a < 0.5
+        result = np.where(mask, 2 * a * b, 1 - 2 * (1 - a) * (1 - b))
+    elif mode == "soft-light":
+        mask = b < 0.5
+        result = np.where(mask,
+                         a - (1 - 2 * b) * a * (1 - a),
+                         a + (2 * b - 1) * (np.sqrt(a) - a))
+    elif mode == "hard-light":
+        mask = b < 0.5
+        result = np.where(mask, 2 * a * b, 1 - 2 * (1 - a) * (1 - b))
+    elif mode == "color-dodge":
+        result = np.clip(a / (1 - b + 0.001), 0, 1)
+    elif mode == "color-burn":
+        result = 1 - np.clip((1 - a) / (b + 0.001), 0, 1)
+    elif mode == "difference":
+        result = np.abs(a - b)
+    elif mode == "exclusion":
+        result = a + b - 2 * a * b
+    elif mode == "add":
+        result = np.clip(a + b, 0, 1)
+    elif mode == "subtract":
+        result = np.clip(a - b, 0, 1)
+    elif mode == "darken":
+        result = np.minimum(a, b)
+    elif mode == "lighten":
+        result = np.maximum(a, b)
+    else:
+        # Default to normal (just return b)
+        result = b
+
+    return (result * 255).astype(np.uint8)
+
+
+def prim_mask(img, mask_img):
+    """Apply grayscale mask to image (white=opaque, black=transparent)."""
+    if len(mask_img.shape) == 3:
+        mask = mask_img[:, :, 0].astype(float) / 255
+    else:
+        mask = mask_img.astype(float) / 255
+
+    mask = mask[:, :, np.newaxis]
+    return (img.astype(float) * mask).astype(np.uint8)
+
+
+def prim_alpha_composite(base, overlay, alpha_channel):
+    """Composite overlay onto base using alpha channel."""
+    if len(alpha_channel.shape) == 3:
+        alpha = alpha_channel[:, :, 0].astype(float) / 255
+    else:
+        alpha = alpha_channel.astype(float) / 255
+
+    alpha = alpha[:, :, np.newaxis]
+    result = base.astype(float) * (1 - alpha) + overlay.astype(float) * alpha
+    return result.astype(np.uint8)
+
+
+def prim_overlay(base, overlay, x, y, alpha=1.0):
+    """Overlay image at position (x, y) with optional alpha."""
+    result = base.copy()
+    x, y = int(x), int(y)
+    oh, ow = overlay.shape[:2]
+    bh, bw = base.shape[:2]
+
+    # Clip to bounds
+    sx1 = max(0, -x)
+    sy1 = max(0, -y)
+    dx1 = max(0, x)
+    dy1 = max(0, y)
+    sx2 = min(ow, bw - x)
+    sy2 = min(oh, bh - y)
+
+    if sx2 > sx1 and sy2 > sy1:
+        src = overlay[sy1:sy2, sx1:sx2]
+        dst = result[dy1:dy1+(sy2-sy1), dx1:dx1+(sx2-sx1)]
+        blended = (dst.astype(float) * (1 - alpha) + src.astype(float) * alpha)
+        result[dy1:dy1+(sy2-sy1), dx1:dx1+(sx2-sx1)] = blended.astype(np.uint8)
+
+    return result
+
+
+PRIMITIVES = {
+    # Basic blending
+    'blend-images': prim_blend_images,
+    'blend-mode': prim_blend_mode,
+
+    # Masking
+    'mask': prim_mask,
+    'alpha-composite': prim_alpha_composite,
+
+    # Overlay
+    'overlay': prim_overlay,
+}

sexp_effects/primitive_libs/color.py

@@ -0,0 +1,137 @@
+"""
+Color Primitives Library
+
+Color manipulation: RGB, HSV, blending, luminance.
+"""
+import numpy as np
+import colorsys
+
+
+def prim_rgb(r, g, b):
+    """Create RGB color as [r, g, b] (0-255)."""
+    return [int(max(0, min(255, r))),
+            int(max(0, min(255, g))),
+            int(max(0, min(255, b)))]
+
+
+def prim_red(c):
+    return c[0]
+
+
+def prim_green(c):
+    return c[1]
+
+
+def prim_blue(c):
+    return c[2]
+
+
+def prim_luminance(c):
+    """Perceived luminance (0-1) using standard weights."""
+    return (0.299 * c[0] + 0.587 * c[1] + 0.114 * c[2]) / 255
+
+
+def prim_rgb_to_hsv(c):
+    """Convert RGB [0-255] to HSV [h:0-360, s:0-1, v:0-1]."""
+    r, g, b = c[0] / 255, c[1] / 255, c[2] / 255
+    h, s, v = colorsys.rgb_to_hsv(r, g, b)
+    return [h * 360, s, v]
+
+
+def prim_hsv_to_rgb(hsv):
+    """Convert HSV [h:0-360, s:0-1, v:0-1] to RGB [0-255]."""
+    h, s, v = hsv[0] / 360, hsv[1], hsv[2]
+    r, g, b = colorsys.hsv_to_rgb(h, s, v)
+    return [int(r * 255), int(g * 255), int(b * 255)]
+
+
+def prim_rgb_to_hsl(c):
+    """Convert RGB [0-255] to HSL [h:0-360, s:0-1, l:0-1]."""
+    r, g, b = c[0] / 255, c[1] / 255, c[2] / 255
+    h, l, s = colorsys.rgb_to_hls(r, g, b)
+    return [h * 360, s, l]
+
+
+def prim_hsl_to_rgb(hsl):
+    """Convert HSL [h:0-360, s:0-1, l:0-1] to RGB [0-255]."""
+    h, s, l = hsl[0] / 360, hsl[1], hsl[2]
+    r, g, b = colorsys.hls_to_rgb(h, l, s)
+    return [int(r * 255), int(g * 255), int(b * 255)]
+
+
+def prim_blend_color(c1, c2, alpha):
+    """Blend two colors: c1 * (1-alpha) + c2 * alpha."""
+    return [int(c1[i] * (1 - alpha) + c2[i] * alpha) for i in range(3)]
+
+
+def prim_average_color(img):
+    """Get average color of an image."""
+    mean = np.mean(img, axis=(0, 1))
+    return [int(mean[0]), int(mean[1]), int(mean[2])]
+
+
+def prim_dominant_color(img, k=1):
+    """Get dominant color using k-means (simplified: just average for now)."""
+    return prim_average_color(img)
+
+
+def prim_invert_color(c):
+    """Invert a color."""
+    return [255 - c[0], 255 - c[1], 255 - c[2]]
+
+
+def prim_grayscale_color(c):
+    """Convert color to grayscale."""
+    gray = int(0.299 * c[0] + 0.587 * c[1] + 0.114 * c[2])
+    return [gray, gray, gray]
+
+
+def prim_saturate(c, amount):
+    """Adjust saturation of color. amount=0 is grayscale, 1 is unchanged, >1 is more saturated."""
+    hsv = prim_rgb_to_hsv(c)
+    hsv[1] = max(0, min(1, hsv[1] * amount))
+    return prim_hsv_to_rgb(hsv)
+
+
+def prim_brighten(c, amount):
+    """Adjust brightness. amount=0 is black, 1 is unchanged, >1 is brighter."""
+    return [int(max(0, min(255, c[i] * amount))) for i in range(3)]
+
+
+def prim_shift_hue(c, degrees):
+    """Shift hue by degrees."""
+    hsv = prim_rgb_to_hsv(c)
+    hsv[0] = (hsv[0] + degrees) % 360
+    return prim_hsv_to_rgb(hsv)
+
+
+PRIMITIVES = {
+    # Construction
+    'rgb': prim_rgb,
+
+    # Component access
+    'red': prim_red,
+    'green': prim_green,
+    'blue': prim_blue,
+    'luminance': prim_luminance,
+
+    # Color space conversion
+    'rgb->hsv': prim_rgb_to_hsv,
+    'hsv->rgb': prim_hsv_to_rgb,
+    'rgb->hsl': prim_rgb_to_hsl,
+    'hsl->rgb': prim_hsl_to_rgb,
+
+    # Blending
+    'blend-color': prim_blend_color,
+
+    # Analysis
+    'average-color': prim_average_color,
+    'dominant-color': prim_dominant_color,
+
+    # Manipulation
+    'invert-color': prim_invert_color,
+    'grayscale-color': prim_grayscale_color,
+    'saturate': prim_saturate,
+    'brighten': prim_brighten,
+    'shift-hue': prim_shift_hue,
+}

sexp_effects/primitive_libs/color_ops.py

@@ -0,0 +1,90 @@
+"""
+Color Operations Primitives Library
+
+Vectorized color adjustments: brightness, contrast, saturation, invert, HSV.
+These operate on entire images for fast processing.
+"""
+import numpy as np
+import cv2
+
+
+def prim_adjust(img, brightness=0, contrast=1):
+    """Adjust brightness and contrast. Brightness: -255 to 255, Contrast: 0 to 3+."""
+    result = (img.astype(np.float32) - 128) * contrast + 128 + brightness
+    return np.clip(result, 0, 255).astype(np.uint8)
+
+
+def prim_mix_gray(img, amount):
+    """Mix image with its grayscale version. 0=original, 1=grayscale."""
+    gray = 0.299 * img[:, :, 0] + 0.587 * img[:, :, 1] + 0.114 * img[:, :, 2]
+    gray_rgb = np.stack([gray, gray, gray], axis=-1)
+    result = img.astype(np.float32) * (1 - amount) + gray_rgb * amount
+    return np.clip(result, 0, 255).astype(np.uint8)
+
+
+def prim_invert_img(img):
+    """Invert all pixel values."""
+    return (255 - img).astype(np.uint8)
+
+
+def prim_shift_hsv(img, h=0, s=1, v=1):
+    """Shift HSV: h=degrees offset, s/v=multipliers."""
+    hsv = cv2.cvtColor(img, cv2.COLOR_RGB2HSV).astype(np.float32)
+    hsv[:, :, 0] = (hsv[:, :, 0] + h / 2) % 180
+    hsv[:, :, 1] = np.clip(hsv[:, :, 1] * s, 0, 255)
+    hsv[:, :, 2] = np.clip(hsv[:, :, 2] * v, 0, 255)
+    return cv2.cvtColor(hsv.astype(np.uint8), cv2.COLOR_HSV2RGB)
+
+
+def prim_add_noise(img, amount):
+    """Add gaussian noise to image."""
+    noise = np.random.normal(0, amount, img.shape)
+    result = img.astype(np.float32) + noise
+    return np.clip(result, 0, 255).astype(np.uint8)
+
+
+def prim_quantize(img, levels):
+    """Reduce to N color levels per channel."""
+    levels = max(2, int(levels))
+    factor = 256 / levels
+    result = (img // factor) * factor + factor // 2
+    return np.clip(result, 0, 255).astype(np.uint8)
+
+
+def prim_sepia(img, intensity=1.0):
+    """Apply sepia tone effect."""
+    sepia_matrix = np.array([
+        [0.393, 0.769, 0.189],
+        [0.349, 0.686, 0.168],
+        [0.272, 0.534, 0.131]
+    ])
+    sepia = np.dot(img, sepia_matrix.T)
+    result = img.astype(np.float32) * (1 - intensity) + sepia * intensity
+    return np.clip(result, 0, 255).astype(np.uint8)
+
+
+def prim_grayscale(img):
+    """Convert to grayscale (still RGB output)."""
+    gray = 0.299 * img[:, :, 0] + 0.587 * img[:, :, 1] + 0.114 * img[:, :, 2]
+    return np.stack([gray, gray, gray], axis=-1).astype(np.uint8)
+
+
+PRIMITIVES = {
+    # Brightness/Contrast
+    'adjust': prim_adjust,
+
+    # Saturation
+    'mix-gray': prim_mix_gray,
+    'grayscale': prim_grayscale,
+
+    # HSV manipulation
+    'shift-hsv': prim_shift_hsv,
+
+    # Inversion
+    'invert-img': prim_invert_img,
+
+    # Effects
+    'add-noise': prim_add_noise,
+    'quantize': prim_quantize,
+    'sepia': prim_sepia,
+}

sexp_effects/primitive_libs/core.py

@@ -0,0 +1,271 @@
+"""
+Core Primitives - Always available, minimal essential set.
+
+These are the primitives that form the foundation of the language.
+They cannot be overridden by libraries.
+"""
+
+
+# Arithmetic
+def prim_add(*args):
+    if len(args) == 0:
+        return 0
+    result = args[0]
+    for arg in args[1:]:
+        result = result + arg
+    return result
+
+
+def prim_sub(a, b=None):
+    if b is None:
+        return -a
+    return a - b
+
+
+def prim_mul(*args):
+    if len(args) == 0:
+        return 1
+    result = args[0]
+    for arg in args[1:]:
+        result = result * arg
+    return result
+
+
+def prim_div(a, b):
+    return a / b
+
+
+def prim_mod(a, b):
+    return a % b
+
+
+def prim_abs(x):
+    return abs(x)
+
+
+def prim_min(*args):
+    return min(args)
+
+
+def prim_max(*args):
+    return max(args)
+
+
+def prim_round(x):
+    return round(x)
+
+
+def prim_floor(x):
+    import math
+    return math.floor(x)
+
+
+def prim_ceil(x):
+    import math
+    return math.ceil(x)
+
+
+# Comparison
+def prim_lt(a, b):
+    return a < b
+
+
+def prim_gt(a, b):
+    return a > b
+
+
+def prim_le(a, b):
+    return a <= b
+
+
+def prim_ge(a, b):
+    return a >= b
+
+
+def prim_eq(a, b):
+    if isinstance(a, float) or isinstance(b, float):
+        return abs(a - b) < 1e-9
+    return a == b
+
+
+def prim_ne(a, b):
+    return not prim_eq(a, b)
+
+
+# Logic
+def prim_not(x):
+    return not x
+
+
+def prim_and(*args):
+    for a in args:
+        if not a:
+            return False
+    return True
+
+
+def prim_or(*args):
+    for a in args:
+        if a:
+            return True
+    return False
+
+
+# Basic data access
+def prim_get(obj, key, default=None):
+    """Get value from dict or list."""
+    if isinstance(obj, dict):
+        return obj.get(key, default)
+    elif isinstance(obj, (list, tuple)):
+        try:
+            return obj[int(key)]
+        except (IndexError, ValueError):
+            return default
+    return default
+
+
+def prim_nth(seq, i):
+    i = int(i)
+    if 0 <= i < len(seq):
+        return seq[i]
+    return None
+
+
+def prim_first(seq):
+    return seq[0] if seq else None
+
+
+def prim_length(seq):
+    return len(seq)
+
+
+def prim_list(*args):
+    return list(args)
+
+
+# Type checking
+def prim_is_number(x):
+    return isinstance(x, (int, float))
+
+
+def prim_is_string(x):
+    return isinstance(x, str)
+
+
+def prim_is_list(x):
+    return isinstance(x, (list, tuple))
+
+
+def prim_is_dict(x):
+    return isinstance(x, dict)
+
+
+def prim_is_nil(x):
+    return x is None
+
+
+# Higher-order / iteration
+def prim_reduce(seq, init, fn):
+    """(reduce seq init fn) — fold left: fn(fn(fn(init, s0), s1), s2) ..."""
+    acc = init
+    for item in seq:
+        acc = fn(acc, item)
+    return acc
+
+
+def prim_map(seq, fn):
+    """(map seq fn) — apply fn to each element, return new list."""
+    return [fn(item) for item in seq]
+
+
+def prim_range(*args):
+    """(range end), (range start end), or (range start end step) — integer range."""
+    if len(args) == 1:
+        return list(range(int(args[0])))
+    elif len(args) == 2:
+        return list(range(int(args[0]), int(args[1])))
+    elif len(args) >= 3:
+        return list(range(int(args[0]), int(args[1]), int(args[2])))
+    return []
+
+
+# Random
+import random
+_rng = random.Random()
+
+def prim_rand():
+    """Return random float in [0, 1)."""
+    return _rng.random()
+
+def prim_rand_int(lo, hi):
+    """Return random integer in [lo, hi]."""
+    return _rng.randint(int(lo), int(hi))
+
+def prim_rand_range(lo, hi):
+    """Return random float in [lo, hi)."""
+    return lo + _rng.random() * (hi - lo)
+
+def prim_map_range(val, from_lo, from_hi, to_lo, to_hi):
+    """Map value from one range to another."""
+    if from_hi == from_lo:
+        return to_lo
+    t = (val - from_lo) / (from_hi - from_lo)
+    return to_lo + t * (to_hi - to_lo)
+
+
+# Core primitives dict
+PRIMITIVES = {
+    # Arithmetic
+    '+': prim_add,
+    '-': prim_sub,
+    '*': prim_mul,
+    '/': prim_div,
+    'mod': prim_mod,
+    'abs': prim_abs,
+    'min': prim_min,
+    'max': prim_max,
+    'round': prim_round,
+    'floor': prim_floor,
+    'ceil': prim_ceil,
+
+    # Comparison
+    '<': prim_lt,
+    '>': prim_gt,
+    '<=': prim_le,
+    '>=': prim_ge,
+    '=': prim_eq,
+    '!=': prim_ne,
+
+    # Logic
+    'not': prim_not,
+    'and': prim_and,
+    'or': prim_or,
+
+    # Data access
+    'get': prim_get,
+    'nth': prim_nth,
+    'first': prim_first,
+    'length': prim_length,
+    'len': prim_length,
+    'list': prim_list,
+
+    # Type predicates
+    'number?': prim_is_number,
+    'string?': prim_is_string,
+    'list?': prim_is_list,
+    'dict?': prim_is_dict,
+    'nil?': prim_is_nil,
+    'is-nil': prim_is_nil,
+
+    # Higher-order / iteration
+    'reduce': prim_reduce,
+    'fold': prim_reduce,
+    'map': prim_map,
+    'range': prim_range,
+
+    # Random
+    'rand': prim_rand,
+    'rand-int': prim_rand_int,
+    'rand-range': prim_rand_range,
+    'map-range': prim_map_range,
+}

sexp_effects/primitive_libs/drawing.py

@@ -0,0 +1,136 @@
+"""
+Drawing Primitives Library
+
+Draw shapes, text, and characters on images.
+"""
+import numpy as np
+import cv2
+from PIL import Image, ImageDraw, ImageFont
+
+
+# Default font (will be loaded lazily)
+_default_font = None
+
+
+def _get_default_font(size=16):
+    """Get default font, creating if needed."""
+    global _default_font
+    if _default_font is None or _default_font.size != size:
+        try:
+            _default_font = ImageFont.truetype("/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf", size)
+        except:
+            _default_font = ImageFont.load_default()
+    return _default_font
+
+
+def prim_draw_char(img, char, x, y, font_size=16, color=None):
+    """Draw a single character at (x, y)."""
+    if color is None:
+        color = [255, 255, 255]
+
+    pil_img = Image.fromarray(img)
+    draw = ImageDraw.Draw(pil_img)
+    font = _get_default_font(font_size)
+    draw.text((x, y), char, fill=tuple(color), font=font)
+    return np.array(pil_img)
+
+
+def prim_draw_text(img, text, x, y, font_size=16, color=None):
+    """Draw text string at (x, y)."""
+    if color is None:
+        color = [255, 255, 255]
+
+    pil_img = Image.fromarray(img)
+    draw = ImageDraw.Draw(pil_img)
+    font = _get_default_font(font_size)
+    draw.text((x, y), text, fill=tuple(color), font=font)
+    return np.array(pil_img)
+
+
+def prim_fill_rect(img, x, y, w, h, color=None):
+    """Fill a rectangle with color."""
+    if color is None:
+        color = [255, 255, 255]
+
+    result = img.copy()
+    x, y, w, h = int(x), int(y), int(w), int(h)
+    result[y:y+h, x:x+w] = color
+    return result
+
+
+def prim_draw_rect(img, x, y, w, h, color=None, thickness=1):
+    """Draw rectangle outline."""
+    if color is None:
+        color = [255, 255, 255]
+
+    result = img.copy()
+    cv2.rectangle(result, (int(x), int(y)), (int(x+w), int(y+h)),
+                  tuple(color), thickness)
+    return result
+
+
+def prim_draw_line(img, x1, y1, x2, y2, color=None, thickness=1):
+    """Draw a line from (x1, y1) to (x2, y2)."""
+    if color is None:
+        color = [255, 255, 255]
+
+    result = img.copy()
+    cv2.line(result, (int(x1), int(y1)), (int(x2), int(y2)),
+             tuple(color), thickness)
+    return result
+
+
+def prim_draw_circle(img, cx, cy, radius, color=None, thickness=1, fill=False):
+    """Draw a circle."""
+    if color is None:
+        color = [255, 255, 255]
+
+    result = img.copy()
+    t = -1 if fill else thickness
+    cv2.circle(result, (int(cx), int(cy)), int(radius), tuple(color), t)
+    return result
+
+
+def prim_draw_ellipse(img, cx, cy, rx, ry, angle=0, color=None, thickness=1, fill=False):
+    """Draw an ellipse."""
+    if color is None:
+        color = [255, 255, 255]
+
+    result = img.copy()
+    t = -1 if fill else thickness
+    cv2.ellipse(result, (int(cx), int(cy)), (int(rx), int(ry)),
+                angle, 0, 360, tuple(color), t)
+    return result
+
+
+def prim_draw_polygon(img, points, color=None, thickness=1, fill=False):
+    """Draw a polygon from list of [x, y] points."""
+    if color is None:
+        color = [255, 255, 255]
+
+    result = img.copy()
+    pts = np.array(points, dtype=np.int32).reshape((-1, 1, 2))
+
+    if fill:
+        cv2.fillPoly(result, [pts], tuple(color))
+    else:
+        cv2.polylines(result, [pts], True, tuple(color), thickness)
+
+    return result
+
+
+PRIMITIVES = {
+    # Text
+    'draw-char': prim_draw_char,
+    'draw-text': prim_draw_text,
+
+    # Rectangles
+    'fill-rect': prim_fill_rect,
+    'draw-rect': prim_draw_rect,
+
+    # Lines and shapes
+    'draw-line': prim_draw_line,
+    'draw-circle': prim_draw_circle,
+    'draw-ellipse': prim_draw_ellipse,
+    'draw-polygon': prim_draw_polygon,
+}

sexp_effects/primitive_libs/filters.py

@@ -0,0 +1,119 @@
+"""
+Filters Primitives Library
+
+Image filters: blur, sharpen, edges, convolution.
+"""
+import numpy as np
+import cv2
+
+
+def prim_blur(img, radius):
+    """Gaussian blur with given radius."""
+    radius = max(1, int(radius))
+    ksize = radius * 2 + 1
+    return cv2.GaussianBlur(img, (ksize, ksize), 0)
+
+
+def prim_box_blur(img, radius):
+    """Box blur with given radius."""
+    radius = max(1, int(radius))
+    ksize = radius * 2 + 1
+    return cv2.blur(img, (ksize, ksize))
+
+
+def prim_median_blur(img, radius):
+    """Median blur (good for noise removal)."""
+    radius = max(1, int(radius))
+    ksize = radius * 2 + 1
+    return cv2.medianBlur(img, ksize)
+
+
+def prim_bilateral(img, d=9, sigma_color=75, sigma_space=75):
+    """Bilateral filter (edge-preserving blur)."""
+    return cv2.bilateralFilter(img, d, sigma_color, sigma_space)
+
+
+def prim_sharpen(img, amount=1.0):
+    """Sharpen image using unsharp mask."""
+    blurred = cv2.GaussianBlur(img, (0, 0), 3)
+    return cv2.addWeighted(img, 1.0 + amount, blurred, -amount, 0)
+
+
+def prim_edges(img, low=50, high=150):
+    """Canny edge detection."""
+    gray = cv2.cvtColor(img, cv2.COLOR_RGB2GRAY)
+    edges = cv2.Canny(gray, low, high)
+    return cv2.cvtColor(edges, cv2.COLOR_GRAY2RGB)
+
+
+def prim_sobel(img, ksize=3):
+    """Sobel edge detection."""
+    gray = cv2.cvtColor(img, cv2.COLOR_RGB2GRAY)
+    sobelx = cv2.Sobel(gray, cv2.CV_64F, 1, 0, ksize=ksize)
+    sobely = cv2.Sobel(gray, cv2.CV_64F, 0, 1, ksize=ksize)
+    mag = np.sqrt(sobelx**2 + sobely**2)
+    mag = np.clip(mag, 0, 255).astype(np.uint8)
+    return cv2.cvtColor(mag, cv2.COLOR_GRAY2RGB)
+
+
+def prim_laplacian(img, ksize=3):
+    """Laplacian edge detection."""
+    gray = cv2.cvtColor(img, cv2.COLOR_RGB2GRAY)
+    lap = cv2.Laplacian(gray, cv2.CV_64F, ksize=ksize)
+    lap = np.abs(lap)
+    lap = np.clip(lap, 0, 255).astype(np.uint8)
+    return cv2.cvtColor(lap, cv2.COLOR_GRAY2RGB)
+
+
+def prim_emboss(img):
+    """Emboss effect."""
+    kernel = np.array([[-2, -1, 0],
+                       [-1,  1, 1],
+                       [ 0,  1, 2]])
+    result = cv2.filter2D(img, -1, kernel)
+    return np.clip(result + 128, 0, 255).astype(np.uint8)
+
+
+def prim_dilate(img, size=1):
+    """Morphological dilation."""
+    kernel = np.ones((size * 2 + 1, size * 2 + 1), np.uint8)
+    return cv2.dilate(img, kernel)
+
+
+def prim_erode(img, size=1):
+    """Morphological erosion."""
+    kernel = np.ones((size * 2 + 1, size * 2 + 1), np.uint8)
+    return cv2.erode(img, kernel)
+
+
+def prim_convolve(img, kernel):
+    """Apply custom convolution kernel."""
+    kernel = np.array(kernel, dtype=np.float32)
+    return cv2.filter2D(img, -1, kernel)
+
+
+PRIMITIVES = {
+    # Blur
+    'blur': prim_blur,
+    'box-blur': prim_box_blur,
+    'median-blur': prim_median_blur,
+    'bilateral': prim_bilateral,
+
+    # Sharpen
+    'sharpen': prim_sharpen,
+
+    # Edges
+    'edges': prim_edges,
+    'sobel': prim_sobel,
+    'laplacian': prim_laplacian,
+
+    # Effects
+    'emboss': prim_emboss,
+
+    # Morphology
+    'dilate': prim_dilate,
+    'erode': prim_erode,
+
+    # Custom
+    'convolve': prim_convolve,
+}

sexp_effects/primitive_libs/geometry.py

@@ -0,0 +1,143 @@
+"""
+Geometry Primitives Library
+
+Geometric transforms: rotate, scale, flip, translate, remap.
+"""
+import numpy as np
+import cv2
+
+
+def prim_translate(img, dx, dy):
+    """Translate image by (dx, dy) pixels."""
+    h, w = img.shape[:2]
+    M = np.float32([[1, 0, dx], [0, 1, dy]])
+    return cv2.warpAffine(img, M, (w, h))
+
+
+def prim_rotate(img, angle, cx=None, cy=None):
+    """Rotate image by angle degrees around center (cx, cy)."""
+    h, w = img.shape[:2]
+    if cx is None:
+        cx = w / 2
+    if cy is None:
+        cy = h / 2
+    M = cv2.getRotationMatrix2D((cx, cy), angle, 1.0)
+    return cv2.warpAffine(img, M, (w, h))
+
+
+def prim_scale(img, sx, sy, cx=None, cy=None):
+    """Scale image by (sx, sy) around center (cx, cy)."""
+    h, w = img.shape[:2]
+    if cx is None:
+        cx = w / 2
+    if cy is None:
+        cy = h / 2
+
+    # Build transform matrix
+    M = np.float32([
+        [sx, 0, cx * (1 - sx)],
+        [0, sy, cy * (1 - sy)]
+    ])
+    return cv2.warpAffine(img, M, (w, h))
+
+
+def prim_flip_h(img):
+    """Flip image horizontally."""
+    return cv2.flip(img, 1)
+
+
+def prim_flip_v(img):
+    """Flip image vertically."""
+    return cv2.flip(img, 0)
+
+
+def prim_flip(img, direction="horizontal"):
+    """Flip image in given direction."""
+    if direction in ("horizontal", "h"):
+        return prim_flip_h(img)
+    elif direction in ("vertical", "v"):
+        return prim_flip_v(img)
+    elif direction in ("both", "hv", "vh"):
+        return cv2.flip(img, -1)
+    return img
+
+
+def prim_transpose(img):
+    """Transpose image (swap x and y)."""
+    return np.transpose(img, (1, 0, 2))
+
+
+def prim_remap(img, map_x, map_y):
+    """Remap image using coordinate maps."""
+    return cv2.remap(img, map_x.astype(np.float32),
+                     map_y.astype(np.float32),
+                     cv2.INTER_LINEAR)
+
+
+def prim_make_coords(w, h):
+    """Create coordinate grids for remapping."""
+    x = np.arange(w, dtype=np.float32)
+    y = np.arange(h, dtype=np.float32)
+    map_x, map_y = np.meshgrid(x, y)
+    return (map_x, map_y)
+
+
+def prim_perspective(img, src_pts, dst_pts):
+    """Apply perspective transform."""
+    src = np.float32(src_pts)
+    dst = np.float32(dst_pts)
+    M = cv2.getPerspectiveTransform(src, dst)
+    h, w = img.shape[:2]
+    return cv2.warpPerspective(img, M, (w, h))
+
+
+def prim_affine(img, src_pts, dst_pts):
+    """Apply affine transform using 3 point pairs."""
+    src = np.float32(src_pts)
+    dst = np.float32(dst_pts)
+    M = cv2.getAffineTransform(src, dst)
+    h, w = img.shape[:2]
+    return cv2.warpAffine(img, M, (w, h))
+
+
+def _get_legacy_geometry_primitives():
+    """Import geometry primitives from legacy primitives module."""
+    from sexp_effects.primitives import (
+        prim_coords_x,
+        prim_coords_y,
+        prim_ripple_displace,
+        prim_fisheye_displace,
+        prim_kaleidoscope_displace,
+    )
+    return {
+        'coords-x': prim_coords_x,
+        'coords-y': prim_coords_y,
+        'ripple-displace': prim_ripple_displace,
+        'fisheye-displace': prim_fisheye_displace,
+        'kaleidoscope-displace': prim_kaleidoscope_displace,
+    }
+
+
+PRIMITIVES = {
+    # Basic transforms
+    'translate': prim_translate,
+    'rotate-img': prim_rotate,
+    'scale-img': prim_scale,
+
+    # Flips
+    'flip-h': prim_flip_h,
+    'flip-v': prim_flip_v,
+    'flip': prim_flip,
+    'transpose': prim_transpose,
+
+    # Remapping
+    'remap': prim_remap,
+    'make-coords': prim_make_coords,
+
+    # Advanced transforms
+    'perspective': prim_perspective,
+    'affine': prim_affine,
+
+    # Displace / coordinate ops (from legacy primitives)
+    **_get_legacy_geometry_primitives(),
+}

sexp_effects/primitive_libs/image.py

@@ -0,0 +1,144 @@
+"""
+Image Primitives Library
+
+Basic image operations: dimensions, pixels, resize, crop, paste.
+"""
+import numpy as np
+import cv2
+
+
+def prim_width(img):
+    return img.shape[1]
+
+
+def prim_height(img):
+    return img.shape[0]
+
+
+def prim_make_image(w, h, color=None):
+    """Create a new image filled with color (default black)."""
+    if color is None:
+        color = [0, 0, 0]
+    img = np.zeros((h, w, 3), dtype=np.uint8)
+    img[:] = color
+    return img
+
+
+def prim_copy(img):
+    return img.copy()
+
+
+def prim_pixel(img, x, y):
+    """Get pixel color at (x, y) as [r, g, b]."""
+    h, w = img.shape[:2]
+    if 0 <= x < w and 0 <= y < h:
+        return list(img[int(y), int(x)])
+    return [0, 0, 0]
+
+
+def prim_set_pixel(img, x, y, color):
+    """Set pixel at (x, y) to color, returns modified image."""
+    result = img.copy()
+    h, w = result.shape[:2]
+    if 0 <= x < w and 0 <= y < h:
+        result[int(y), int(x)] = color
+    return result
+
+
+def prim_sample(img, x, y):
+    """Bilinear sample at float coordinates, returns [r, g, b] as floats."""
+    h, w = img.shape[:2]
+    x = max(0, min(w - 1.001, x))
+    y = max(0, min(h - 1.001, y))
+
+    x0, y0 = int(x), int(y)
+    x1, y1 = min(x0 + 1, w - 1), min(y0 + 1, h - 1)
+    fx, fy = x - x0, y - y0
+
+    c00 = img[y0, x0].astype(float)
+    c10 = img[y0, x1].astype(float)
+    c01 = img[y1, x0].astype(float)
+    c11 = img[y1, x1].astype(float)
+
+    top = c00 * (1 - fx) + c10 * fx
+    bottom = c01 * (1 - fx) + c11 * fx
+    return list(top * (1 - fy) + bottom * fy)
+
+
+def prim_channel(img, c):
+    """Extract single channel (0=R, 1=G, 2=B)."""
+    return img[:, :, c]
+
+
+def prim_merge_channels(r, g, b):
+    """Merge three single-channel arrays into RGB image."""
+    return np.stack([r, g, b], axis=2).astype(np.uint8)
+
+
+def prim_resize(img, w, h, mode="linear"):
+    """Resize image to w x h."""
+    interp = cv2.INTER_LINEAR
+    if mode == "nearest":
+        interp = cv2.INTER_NEAREST
+    elif mode == "cubic":
+        interp = cv2.INTER_CUBIC
+    elif mode == "area":
+        interp = cv2.INTER_AREA
+    return cv2.resize(img, (int(w), int(h)), interpolation=interp)
+
+
+def prim_crop(img, x, y, w, h):
+    """Crop rectangle from image."""
+    x, y, w, h = int(x), int(y), int(w), int(h)
+    ih, iw = img.shape[:2]
+    x = max(0, min(x, iw - 1))
+    y = max(0, min(y, ih - 1))
+    w = min(w, iw - x)
+    h = min(h, ih - y)
+    return img[y:y+h, x:x+w].copy()
+
+
+def prim_paste(dst, src, x, y):
+    """Paste src onto dst at position (x, y)."""
+    result = dst.copy()
+    x, y = int(x), int(y)
+    sh, sw = src.shape[:2]
+    dh, dw = dst.shape[:2]
+
+    # Clip to bounds
+    sx1 = max(0, -x)
+    sy1 = max(0, -y)
+    dx1 = max(0, x)
+    dy1 = max(0, y)
+    sx2 = min(sw, dw - x)
+    sy2 = min(sh, dh - y)
+
+    if sx2 > sx1 and sy2 > sy1:
+        result[dy1:dy1+(sy2-sy1), dx1:dx1+(sx2-sx1)] = src[sy1:sy2, sx1:sx2]
+
+    return result
+
+
+PRIMITIVES = {
+    # Dimensions
+    'width': prim_width,
+    'height': prim_height,
+
+    # Creation
+    'make-image': prim_make_image,
+    'copy': prim_copy,
+
+    # Pixel access
+    'pixel': prim_pixel,
+    'set-pixel': prim_set_pixel,
+    'sample': prim_sample,
+
+    # Channels
+    'channel': prim_channel,
+    'merge-channels': prim_merge_channels,
+
+    # Geometry
+    'resize': prim_resize,
+    'crop': prim_crop,
+    'paste': prim_paste,
+}

sexp_effects/primitive_libs/math.py

@@ -0,0 +1,164 @@
+"""
+Math Primitives Library
+
+Trigonometry, rounding, clamping, random numbers, etc.
+"""
+import math
+import random as rand_module
+
+
+def prim_sin(x):
+    return math.sin(x)
+
+
+def prim_cos(x):
+    return math.cos(x)
+
+
+def prim_tan(x):
+    return math.tan(x)
+
+
+def prim_asin(x):
+    return math.asin(x)
+
+
+def prim_acos(x):
+    return math.acos(x)
+
+
+def prim_atan(x):
+    return math.atan(x)
+
+
+def prim_atan2(y, x):
+    return math.atan2(y, x)
+
+
+def prim_sqrt(x):
+    return math.sqrt(x)
+
+
+def prim_pow(x, y):
+    return math.pow(x, y)
+
+
+def prim_exp(x):
+    return math.exp(x)
+
+
+def prim_log(x, base=None):
+    if base is None:
+        return math.log(x)
+    return math.log(x, base)
+
+
+def prim_abs(x):
+    return abs(x)
+
+
+def prim_floor(x):
+    return math.floor(x)
+
+
+def prim_ceil(x):
+    return math.ceil(x)
+
+
+def prim_round(x):
+    return round(x)
+
+
+def prim_min(*args):
+    if len(args) == 1 and hasattr(args[0], '__iter__'):
+        return min(args[0])
+    return min(args)
+
+
+def prim_max(*args):
+    if len(args) == 1 and hasattr(args[0], '__iter__'):
+        return max(args[0])
+    return max(args)
+
+
+def prim_clamp(x, lo, hi):
+    return max(lo, min(hi, x))
+
+
+def prim_lerp(a, b, t):
+    """Linear interpolation: a + (b - a) * t"""
+    return a + (b - a) * t
+
+
+def prim_smoothstep(edge0, edge1, x):
+    """Smooth interpolation between 0 and 1."""
+    t = prim_clamp((x - edge0) / (edge1 - edge0), 0.0, 1.0)
+    return t * t * (3 - 2 * t)
+
+
+def prim_random(lo=0.0, hi=1.0):
+    return rand_module.uniform(lo, hi)
+
+
+def prim_randint(lo, hi):
+    return rand_module.randint(lo, hi)
+
+
+def prim_gaussian(mean=0.0, std=1.0):
+    return rand_module.gauss(mean, std)
+
+
+def prim_sign(x):
+    if x > 0:
+        return 1
+    elif x < 0:
+        return -1
+    return 0
+
+
+def prim_fract(x):
+    """Fractional part of x."""
+    return x - math.floor(x)
+
+
+PRIMITIVES = {
+    # Trigonometry
+    'sin': prim_sin,
+    'cos': prim_cos,
+    'tan': prim_tan,
+    'asin': prim_asin,
+    'acos': prim_acos,
+    'atan': prim_atan,
+    'atan2': prim_atan2,
+
+    # Powers and roots
+    'sqrt': prim_sqrt,
+    'pow': prim_pow,
+    'exp': prim_exp,
+    'log': prim_log,
+
+    # Rounding
+    'abs': prim_abs,
+    'floor': prim_floor,
+    'ceil': prim_ceil,
+    'round': prim_round,
+    'sign': prim_sign,
+    'fract': prim_fract,
+
+    # Min/max/clamp
+    'min': prim_min,
+    'max': prim_max,
+    'clamp': prim_clamp,
+    'lerp': prim_lerp,
+    'smoothstep': prim_smoothstep,
+
+    # Random
+    'random': prim_random,
+    'randint': prim_randint,
+    'gaussian': prim_gaussian,
+
+    # Constants
+    'pi': math.pi,
+    'tau': math.tau,
+    'e': math.e,
+}

sexp_effects/primitive_libs/streaming.py

@@ -0,0 +1,304 @@
+"""
+Streaming primitives for video/audio processing.
+
+These primitives handle video source reading and audio analysis,
+keeping the interpreter completely generic.
+"""
+
+import numpy as np
+import subprocess
+import json
+from pathlib import Path
+
+
+class VideoSource:
+    """Video source with persistent streaming pipe for fast sequential reads."""
+
+    def __init__(self, path: str, fps: float = 30):
+        self.path = Path(path)
+        self.fps = fps  # Output fps for the stream
+        self._frame_size = None
+        self._duration = None
+        self._proc = None  # Persistent ffmpeg process
+        self._stream_time = 0.0  # Current position in stream
+        self._frame_time = 1.0 / fps  # Time per frame at output fps
+        self._last_read_time = -1
+        self._cached_frame = None
+
+        # Get video info
+        cmd = ["ffprobe", "-v", "quiet", "-print_format", "json",
+               "-show_streams", str(self.path)]
+        result = subprocess.run(cmd, capture_output=True, text=True)
+        info = json.loads(result.stdout)
+
+        for stream in info.get("streams", []):
+            if stream.get("codec_type") == "video":
+                self._frame_size = (stream.get("width", 720), stream.get("height", 720))
+                # Try direct duration field first
+                if "duration" in stream:
+                    self._duration = float(stream["duration"])
+                # Fall back to tags.DURATION (webm format: "00:01:00.124000000")
+                elif "tags" in stream and "DURATION" in stream["tags"]:
+                    dur_str = stream["tags"]["DURATION"]
+                    parts = dur_str.split(":")
+                    if len(parts) == 3:
+                        h, m, s = parts
+                        self._duration = int(h) * 3600 + int(m) * 60 + float(s)
+                break
+
+        if not self._frame_size:
+            self._frame_size = (720, 720)
+
+    def _start_stream(self, seek_time: float = 0):
+        """Start or restart the ffmpeg streaming process."""
+        if self._proc:
+            self._proc.kill()
+            self._proc = None
+
+        w, h = self._frame_size
+        cmd = [
+            "ffmpeg", "-v", "quiet",
+            "-ss", f"{seek_time:.3f}",
+            "-i", str(self.path),
+            "-f", "rawvideo", "-pix_fmt", "rgb24",
+            "-s", f"{w}x{h}",
+            "-r", str(self.fps),  # Output at specified fps
+            "-"
+        ]
+        self._proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL)
+        self._stream_time = seek_time
+
+    def _read_frame_from_stream(self) -> np.ndarray:
+        """Read one frame from the stream."""
+        w, h = self._frame_size
+        frame_size = w * h * 3
+
+        if not self._proc or self._proc.poll() is not None:
+            return None
+
+        data = self._proc.stdout.read(frame_size)
+        if len(data) < frame_size:
+            return None
+
+        return np.frombuffer(data, dtype=np.uint8).reshape((h, w, 3)).copy()
+
+    def read(self) -> np.ndarray:
+        """Read frame (uses last cached or t=0)."""
+        if self._cached_frame is not None:
+            return self._cached_frame
+        return self.read_at(0)
+
+    def read_at(self, t: float) -> np.ndarray:
+        """Read frame at specific time using streaming with smart seeking."""
+        # Cache check - return same frame for same time
+        if t == self._last_read_time and self._cached_frame is not None:
+            return self._cached_frame
+
+        w, h = self._frame_size
+
+        # Loop time if video is shorter
+        seek_time = t
+        if self._duration and self._duration > 0:
+            seek_time = t % self._duration
+
+        # Decide whether to seek or continue streaming
+        # Seek if: no stream, going backwards (more than 1 frame), or jumping more than 2 seconds ahead
+        # Allow small backward tolerance to handle floating point and timing jitter
+        need_seek = (
+            self._proc is None or
+            self._proc.poll() is not None or
+            seek_time < self._stream_time - self._frame_time or  # More than 1 frame backward
+            seek_time > self._stream_time + 2.0
+        )
+
+        if need_seek:
+            import sys
+            reason = "no proc" if self._proc is None else "proc dead" if self._proc.poll() is not None else "backward" if seek_time < self._stream_time else "jump"
+            print(f"SEEK {self.path.name}: t={t:.4f} seek={seek_time:.4f} stream={self._stream_time:.4f} ({reason})", file=sys.stderr)
+            self._start_stream(seek_time)
+
+        # Skip frames to reach target time
+        while self._stream_time + self._frame_time <= seek_time:
+            frame = self._read_frame_from_stream()
+            if frame is None:
+                # Stream ended, restart from seek point
+                self._start_stream(seek_time)
+                break
+            self._stream_time += self._frame_time
+
+        # Read the target frame
+        frame = self._read_frame_from_stream()
+        if frame is None:
+            import sys
+            print(f"NULL FRAME {self.path.name}: t={t:.2f} seek={seek_time:.2f}", file=sys.stderr)
+            frame = np.zeros((h, w, 3), dtype=np.uint8)
+        else:
+            self._stream_time += self._frame_time
+
+        self._last_read_time = t
+        self._cached_frame = frame
+        return frame
+
+    def skip(self):
+        """No-op for seek-based reading."""
+        pass
+
+    @property
+    def size(self):
+        return self._frame_size
+
+    def close(self):
+        if self._proc:
+            self._proc.kill()
+            self._proc = None
+
+
+class AudioAnalyzer:
+    """Audio analyzer for energy and beat detection."""
+
+    def __init__(self, path: str, sample_rate: int = 22050):
+        self.path = Path(path)
+        self.sample_rate = sample_rate
+
+        # Load audio via ffmpeg
+        cmd = ["ffmpeg", "-v", "quiet", "-i", str(self.path),
+               "-f", "f32le", "-ac", "1", "-ar", str(sample_rate), "-"]
+        result = subprocess.run(cmd, capture_output=True)
+        self._audio = np.frombuffer(result.stdout, dtype=np.float32)
+
+        # Get duration
+        cmd = ["ffprobe", "-v", "quiet", "-print_format", "json",
+               "-show_format", str(self.path)]
+        info = json.loads(subprocess.run(cmd, capture_output=True, text=True).stdout)
+        self.duration = float(info.get("format", {}).get("duration", 60))
+
+        # Beat detection state
+        self._flux_history = []
+        self._last_beat_time = -1
+        self._beat_count = 0
+        self._last_beat_check_time = -1
+        # Cache beat result for current time (so multiple scans see same result)
+        self._beat_cache_time = -1
+        self._beat_cache_result = False
+
+    def get_energy(self, t: float) -> float:
+        """Get energy level at time t (0-1)."""
+        idx = int(t * self.sample_rate)
+        start = max(0, idx - 512)
+        end = min(len(self._audio), idx + 512)
+        if start >= end:
+            return 0.0
+        return min(1.0, np.sqrt(np.mean(self._audio[start:end] ** 2)) * 3.0)
+
+    def get_beat(self, t: float) -> bool:
+        """Check if there's a beat at time t."""
+        # Return cached result if same time (multiple scans query same frame)
+        if t == self._beat_cache_time:
+            return self._beat_cache_result
+
+        idx = int(t * self.sample_rate)
+        size = 2048
+
+        start, end = max(0, idx - size//2), min(len(self._audio), idx + size//2)
+        if end - start < size/2:
+            self._beat_cache_time = t
+            self._beat_cache_result = False
+            return False
+        curr = self._audio[start:end]
+
+        pstart, pend = max(0, start - 512), max(0, end - 512)
+        if pend <= pstart:
+            self._beat_cache_time = t
+            self._beat_cache_result = False
+            return False
+        prev = self._audio[pstart:pend]
+
+        curr_spec = np.abs(np.fft.rfft(curr * np.hanning(len(curr))))
+        prev_spec = np.abs(np.fft.rfft(prev * np.hanning(len(prev))))
+
+        n = min(len(curr_spec), len(prev_spec))
+        flux = np.sum(np.maximum(0, curr_spec[:n] - prev_spec[:n])) / (n + 1)
+
+        self._flux_history.append((t, flux))
+        if len(self._flux_history) > 50:
+            self._flux_history = self._flux_history[-50:]
+
+        if len(self._flux_history) < 5:
+            self._beat_cache_time = t
+            self._beat_cache_result = False
+            return False
+
+        recent = [f for _, f in self._flux_history[-20:]]
+        threshold = np.mean(recent) + 1.5 * np.std(recent)
+
+        is_beat = flux > threshold and (t - self._last_beat_time) > 0.1
+        if is_beat:
+            self._last_beat_time = t
+            if t > self._last_beat_check_time:
+                self._beat_count += 1
+                self._last_beat_check_time = t
+
+        # Cache result for this time
+        self._beat_cache_time = t
+        self._beat_cache_result = is_beat
+        return is_beat
+
+    def get_beat_count(self, t: float) -> int:
+        """Get cumulative beat count up to time t."""
+        # Ensure beat detection has run up to this time
+        self.get_beat(t)
+        return self._beat_count
+
+
+# === Primitives ===
+
+def prim_make_video_source(path: str, fps: float = 30):
+    """Create a video source from a file path."""
+    return VideoSource(path, fps)
+
+
+def prim_source_read(source: VideoSource, t: float = None):
+    """Read a frame from a video source."""
+    import sys
+    if t is not None:
+        frame = source.read_at(t)
+        # Debug: show source and time
+        if int(t * 10) % 10 == 0:  # Every second
+            print(f"READ {source.path.name}: t={t:.2f} stream={source._stream_time:.2f}", file=sys.stderr)
+        return frame
+    return source.read()
+
+
+def prim_source_skip(source: VideoSource):
+    """Skip a frame (keep pipe in sync)."""
+    source.skip()
+
+
+def prim_source_size(source: VideoSource):
+    """Get (width, height) of source."""
+    return source.size
+
+
+def prim_make_audio_analyzer(path: str):
+    """Create an audio analyzer from a file path."""
+    return AudioAnalyzer(path)
+
+
+def prim_audio_energy(analyzer: AudioAnalyzer, t: float) -> float:
+    """Get energy level (0-1) at time t."""
+    return analyzer.get_energy(t)
+
+
+def prim_audio_beat(analyzer: AudioAnalyzer, t: float) -> bool:
+    """Check if there's a beat at time t."""
+    return analyzer.get_beat(t)
+
+
+def prim_audio_beat_count(analyzer: AudioAnalyzer, t: float) -> int:
+    """Get cumulative beat count up to time t."""
+    return analyzer.get_beat_count(t)
+
+
+def prim_audio_duration(analyzer: AudioAnalyzer) -> float:
+    """Get audio duration in seconds."""
+    return analyzer.duration

sexp_effects/test_interpreter.py

@@ -0,0 +1,236 @@
+#!/usr/bin/env python3
+"""
+Test the S-expression effect interpreter.
+"""
+
+import numpy as np
+import sys
+from pathlib import Path
+
+# Add parent to path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from sexp_effects import (
+    get_interpreter,
+    load_effects_dir,
+    run_effect,
+    list_effects,
+    parse,
+)
+
+
+def test_parser():
+    """Test S-expression parser."""
+    print("Testing parser...")
+
+    # Simple expressions
+    assert parse("42") == 42
+    assert parse("3.14") == 3.14
+    assert parse('"hello"') == "hello"
+    assert parse("true") == True
+
+    # Lists
+    assert parse("(+ 1 2)")[0].name == "+"
+    assert parse("(+ 1 2)")[1] == 1
+
+    # Nested
+    expr = parse("(define x (+ 1 2))")
+    assert expr[0].name == "define"
+
+    print("  Parser OK")
+
+
+def test_interpreter_basics():
+    """Test basic interpreter operations."""
+    print("Testing interpreter basics...")
+
+    interp = get_interpreter()
+
+    # Math
+    assert interp.eval(parse("(+ 1 2)")) == 3
+    assert interp.eval(parse("(* 3 4)")) == 12
+    assert interp.eval(parse("(- 10 3)")) == 7
+
+    # Comparison
+    assert interp.eval(parse("(< 1 2)")) == True
+    assert interp.eval(parse("(> 1 2)")) == False
+
+    # Let binding
+    assert interp.eval(parse("(let ((x 5)) x)")) == 5
+    assert interp.eval(parse("(let ((x 5) (y 3)) (+ x y))")) == 8
+
+    # Lambda
+    result = interp.eval(parse("((lambda (x) (* x 2)) 5)"))
+    assert result == 10
+
+    # If
+    assert interp.eval(parse("(if true 1 2)")) == 1
+    assert interp.eval(parse("(if false 1 2)")) == 2
+
+    print("  Interpreter basics OK")
+
+
+def test_primitives():
+    """Test image primitives."""
+    print("Testing primitives...")
+
+    interp = get_interpreter()
+
+    # Create test image
+    img = np.zeros((100, 100, 3), dtype=np.uint8)
+    img[50, 50] = [255, 128, 64]
+
+    interp.global_env.set('test_img', img)
+
+    # Width/height
+    assert interp.eval(parse("(width test_img)")) == 100
+    assert interp.eval(parse("(height test_img)")) == 100
+
+    # Pixel
+    pixel = interp.eval(parse("(pixel test_img 50 50)"))
+    assert pixel == [255, 128, 64]
+
+    # RGB
+    color = interp.eval(parse("(rgb 100 150 200)"))
+    assert color == [100, 150, 200]
+
+    # Luminance
+    lum = interp.eval(parse("(luminance (rgb 100 100 100))"))
+    assert abs(lum - 100) < 1
+
+    print("  Primitives OK")
+
+
+def test_effect_loading():
+    """Test loading effects from .sexp files."""
+    print("Testing effect loading...")
+
+    # Load all effects
+    effects_dir = Path(__file__).parent / "effects"
+    load_effects_dir(str(effects_dir))
+
+    effects = list_effects()
+    print(f"  Loaded {len(effects)} effects: {', '.join(sorted(effects))}")
+
+    assert len(effects) > 0
+    print("  Effect loading OK")
+
+
+def test_effect_execution():
+    """Test running effects on images."""
+    print("Testing effect execution...")
+
+    # Create test image
+    img = np.random.randint(0, 255, (100, 100, 3), dtype=np.uint8)
+
+    # Load effects
+    effects_dir = Path(__file__).parent / "effects"
+    load_effects_dir(str(effects_dir))
+
+    # Test each effect
+    effects = list_effects()
+    passed = 0
+    failed = []
+
+    for name in sorted(effects):
+        try:
+            result, state = run_effect(name, img.copy(), {'_time': 0.5}, {})
+            assert isinstance(result, np.ndarray)
+            assert result.shape == img.shape
+            passed += 1
+            print(f"    {name}: OK")
+        except Exception as e:
+            failed.append((name, str(e)))
+            print(f"    {name}: FAILED - {e}")
+
+    print(f"  Passed: {passed}/{len(effects)}")
+    if failed:
+        print(f"  Failed: {[f[0] for f in failed]}")
+
+    return passed, failed
+
+
+def test_ascii_fx_zone():
+    """Test ascii_fx_zone effect with zone expressions."""
+    print("Testing ascii_fx_zone...")
+
+    interp = get_interpreter()
+
+    # Load the effect
+    effects_dir = Path(__file__).parent / "effects"
+    load_effects_dir(str(effects_dir))
+
+    # Create gradient test frame
+    frame = np.zeros((120, 160, 3), dtype=np.uint8)
+    for x in range(160):
+        frame[:, x] = int(x / 160 * 255)
+    frame = np.stack([frame[:,:,0]]*3, axis=2)
+
+    # Test 1: Basic without expressions
+    result, _ = run_effect('ascii_fx_zone', frame, {'cols': 20}, {})
+    assert result.shape == frame.shape
+    print("    Basic run: OK")
+
+    # Test 2: With zone-lum expression
+    expr = parse('(* zone-lum 180)')
+    result, _ = run_effect('ascii_fx_zone', frame, {
+        'cols': 20,
+        'char_hue': expr
+    }, {})
+    assert result.shape == frame.shape
+    print("    Zone-lum expression: OK")
+
+    # Test 3: With multiple expressions
+    scale_expr = parse('(+ 0.5 (* zone-lum 0.5))')
+    rot_expr = parse('(* zone-row-norm 30)')
+    result, _ = run_effect('ascii_fx_zone', frame, {
+        'cols': 20,
+        'char_scale': scale_expr,
+        'char_rotation': rot_expr
+    }, {})
+    assert result.shape == frame.shape
+    print("    Multiple expressions: OK")
+
+    # Test 4: With numeric literals
+    result, _ = run_effect('ascii_fx_zone', frame, {
+        'cols': 20,
+        'char_hue': 90,
+        'char_scale': 1.2
+    }, {})
+    assert result.shape == frame.shape
+    print("    Numeric literals: OK")
+
+    # Test 5: Zone position expressions
+    col_expr = parse('(* zone-col-norm 360)')
+    result, _ = run_effect('ascii_fx_zone', frame, {
+        'cols': 20,
+        'char_hue': col_expr
+    }, {})
+    assert result.shape == frame.shape
+    print("    Zone position expression: OK")
+
+    print("  ascii_fx_zone OK")
+
+
+def main():
+    print("=" * 60)
+    print("S-Expression Effect Interpreter Tests")
+    print("=" * 60)
+
+    test_parser()
+    test_interpreter_basics()
+    test_primitives()
+    test_effect_loading()
+    test_ascii_fx_zone()
+    passed, failed = test_effect_execution()
+
+    print("=" * 60)
+    if not failed:
+        print("All tests passed!")
+    else:
+        print(f"Tests completed with {len(failed)} failures")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()