summaryrefslogtreecommitdiff
path: root/docs/effects.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/effects.md')
-rw-r--r--docs/effects.md285
1 files changed, 0 insertions, 285 deletions
diff --git a/docs/effects.md b/docs/effects.md
deleted file mode 100644
index a9b27a6b..00000000
--- a/docs/effects.md
+++ /dev/null
@@ -1,285 +0,0 @@
-# Effects: feel reviews
-
-**The rule above all the others:** no effect may alter or cover a focus
-indicator (the focused pane's tag colour, its grip, the cursor, the
-selection) or reduce its contrast. The effects are sugar; the indicators are
-how a person knows where they are. Every G stage is reviewed against this.
-Lift, for one, falls only on pane bodies and rails, never on a tag, a grip or
-a header, and its strength is capped so text and the selection keep min(their
-contrast, 4.5) (tests in src/gui/gui.zig). The rule binds effects, not a
-theme's structure: the rules between panes (2px, `rule_px`) are the theme's
-borders, and the one over a tag band stays in the band's slack, never over
-its text. A dim touches only the unfocused
-panes, with the same floor, and the focused pane's text is never at less
-contrast than theirs (tests in src/draw.zig).
-
-**Density.** A pixel shell draws every size given in pixels in logical
-pixels, `dp()` in gui.zig (SDL's window display scale, rounded, at least
-one; `PARDES_TEST_SCALE` forces one in a harness, and a test window is 1x
-otherwise): the rules (`rule_px`), the tag rule, the grip's ring and its
-dirty gap and mode bars, the rail's gap to the text and its minimum, the
-thumb's inset, the rim, a bar cursor's minimum width, underline and
-strikethrough thickness, the rule-grab margin, and the Crt's scanline and
-mask periods (`pardesScale`). Left as they are: what is measured in cells
-or the tagline (the rail's width, `rail_px` scaled with the tagline; Lift's
-blur and offsets; every motion, in cells), Shadertoy's iResolution,
-fragCoord and iMouse (the display's pixels, as ghostty's), and the pet
-overlay.
-
-Each effect of docs/render-pipeline.md §9 lands behind its own switch, off,
-and is kept only after a feel review (§8.4): a frame series on the virtual
-clock, a recording, and a verdict — keep, polish or drop — with one line of
-why. The verdict is the user's.
-
-| effect | switch | state | review material | verdict |
-|---|---|---|---|---|
-| Crt (bundled post pass) | `Crt 0..3` | kept, rewritten (no barrel) | fx-compare stills, live window | kept at the user's live look |
-| Ripple, Glitch | — | removed | live window | dropped by the user after a live look |
-| G1 lift | `Lift shadow\|rim\|auto` (off), `InactiveDim <percent>` | opt-in until the focus-lift default is decided | lift-shots-2 (off, shadow, rim, auto on acme, dusk, forge); frame series + mp4 per Motion flavour | shadow on acme: keep as is. Round 1 dropped glow and surface (surface lowered the focused text's contrast) and made rim a hairline just above the focused tag (light on a dark page, shade on a light one). auto on a dark page recedes the others (InactiveDim 30) |
-| G3 cursor | follows `Motion`; `CursorBlink on\|off` (on) | glide on by default through the default flavour (smooth); blink on (decision 6) | .scratch/render/cursor/cursor-flavours-grid.mp4 (and quarter speed), raw/<flavour>/<motion>/ | pending |
-| G4 bloom, vignette, grain | `Bloom`, `Vignette`, `Grain` `0..3` (off) | bundled post passes; none touches a tag, grip, notice or the cursor (pardesSpare); each capped per theme (pardesCap) | .scratch/render/{bloom,vignette,grain}/ (levels 0-3 on forge, dusk, acme; crops; mp4 stepping through the levels) | pending |
-| G5 lapis | `Theme lapis` (its `decor`) | a native theme with ornament: tag plaques with hard shadows inside their bands (the focused one striped), dots, rail checker, title shadow | .scratch/render/lapis/ (whole window at 1x and 2x, crops, a slide mp4) | pending |
-| G6 smooth scroll | follows `Motion` (on through the default smooth; `Motion off` lands at once) | a mouse wheel's notch glides, a touchpad follows the finger | .scratch/render/scroll/ (glide-<flavour>.mp4, quarter speed, strips) | pending |
-| G7 panel transitions | `PanelSlide`, `PanelZoom`, `PanelVertical`, `PanelDissolve` (off) with `Motion` | a moving pane casts a shadow; a retargeted move keeps its speed; the GUI's dissolve is a crossfade | .scratch/render/transitions/ (slide smooth, bouncy, retargeted; dissolve) | pending |
-| G8 notice chips | follows `Motion` and `Lift` | a notice floats in tier 4 on a lift (shadow) while Lift is on, drops in easing out and dissolves easing in, quicker than it came (150 ms against 180) | .scratch/render/notices/ (acme, forge) | pending |
-| G9 selection glow | `SelectionGlow on\|off` (off) | a soft halo of the selection's colour round each block of it in a body, fading in over 100 ms | .scratch/render/selection/ (forge, acme, lapis; lapis-glow-zoom.png) | pending |
-| G10 theme crossfade | always (a theme change) | the chrome's colours fade through OKLab, easing in and out (out when retargeted) | .scratch/render/crossfade/ (forge, lapis, acme cut short by dusk) | pending |
-| G11 look-hover glow | `HoverGlow on\|off` (off) | a soft underline of the theme's accent under the word a look-hover would open, fading in over 80 ms | .scratch/render/hover/ (forge, acme, lapis; zooms) | pending |
-| G12 ambient occlusion | `Occlusion on\|off` (off) | pane bodies darken toward their edges, at most 2% (§9.1: 1 to 2%) | .scratch/render/occlusion/ (on/off on forge, acme, lapis; acme-diff-x40.png) | pending |
-| G13 parallax | `Parallax on\|off` (off) | a theme's page pattern under the bodies (lapis's dots) moves with the text at a quarter of its speed, glides included | .scratch/render/parallax/ (lapis, notches down and up) | pending |
-| G14 afterglow | — | removed | live lapis showcase | dropped by the user: "one of the animations is like a flashing on the whole pane or something, that is really bad, just remove it" (a pane whose whole text changed, a file opened, a +Search refilled, a terminal's output, lit up at once) |
-
-## Motion flavours
-
-`Motion off|crisp|smooth|bouncy|playful` (default smooth, tuned so arrivals
-land inside §8.1's 220 ms; bouncy and playful run longer, opt-in) is one parameter set
-(animation.Motion) every fx animation reads, so a flavour is data, not a
-branch in each effect. Input is never blocked, and a new target always
-retargets from the current position and velocity.
-
-| flavour | timing (ω, length) | follow-through (ζ) | anticipation | squash/stretch | exaggeration (gain) | secondary lag | arcs |
-|---|---|---|---|---|---|---|---|
-| off | instant | — | — | — | — | — | — |
-| crisp | 60, 0.6× (leaves at full speed) | 1 (none) | — | — | 1 | in step | — |
-| smooth | 34, 1.1× (slow in, slow out; ≤220 ms) | 1 (none) | — | — | 1 | 0.85 | 0.04 |
-| bouncy | 24, 1.4× | 0.35 (overshoots ~30%, settles twice) | — | 0.15 | 1.25 | 0.8 | 0.08 |
-| playful | 18, 1.7× | 0.28 (overshoots ~40%) | 0.15 of the move | 0.35 | 1.4 | 0.55 | 0.15 |
-
-The flavours are distinct by design, not tuning: crisp leaves at full speed
-and never passes its mark; smooth takes twice as long and eases in and out; bouncy clearly passes its mark and settles back once or twice;
-playful winds up the other way first, flies well past, and stretches along
-its path and squashes as it lands, its text with it (the user's choice); a
-pointer inverts the same stretched box, and landed, a pane is exactly its
-target. A motion only a few pixels big (Lift) is
-exaggerated by the flavour's gain so its character shows. The flavours drive
-the Lift spring (time-based), the notice drop and the pane moves (PanelSlide,
-PanelZoom, PanelVertical opening or moving, whose length scales with the
-flavour); a closing pane keeps its effect's own exit. Chart and side-by-side
-video: .scratch/render/motion/compare/.
-
-Which principles each motion uses:
-
-- **Lift** (G1): timing, slow in / slow out (the spring), follow-through
- (bouncy and playful lift past full and settle back), anticipation (playful
- dips before it rises; below zero nothing is drawn, so it reads as a beat
- before the lift), staging (only the focused pane lifts; nothing else moves
- with a focus change), exaggeration (the flavour's gain). Squash, stretch,
- arcs and secondary lag have nothing to act on in a lift.
-- **Notice drop and pane moves**: timing and follow-through from the flavour's
- spring over the move's length; anticipation (playful). A pane past its mark
- never takes a neighbour's click, a rising one stays in its box, and a notice
- past its row stays in its pane's body.
-- **Cursor** (G3): timing (the flavour's spring, 2.4x its pace: it follows
- input), follow-through (bouncy and playful pass the target), squash and
- stretch and secondary action (the trailing corners lag by the flavour's
- follow, so a jump smears and collapses), arcs (a jump over 8 cells bows by
- the flavour's arc), anticipation (playful's wind-up). A step of a cell or
- less, or any move in insert mode, lands at once, so typing never trails;
- a scroll carries the cursor with the text. Only the focused cursor moves.
- A pane that moves carries it too: the springs keep its place in the pane
- and the quad is drawn through the pane's presented box, so through a
- slide, a zoom or a drag it rides with the text, and a layout change with
- no transition lands it with the text. A focus change (to another pane, or
- into a column's or the workspace's tag) glides from where the cursor is
- drawn to the new one, free of the old pane's edges while it crosses
- (.scratch/render/cursor/move/: ride-*, cross-*).
-
-
-Notes on G1: the lift and the dim run on one focus spring per pane, at the
-Motion flavour's pace, sampled at each frame's own time; while it moves the
-GUI draws at the display's rate, and a grid snaps. A notice floats on a lift
-of 1 while a shadow or rim is on. InactiveDim under `Lift auto` defaults to
-30. The fade is in linear light, so on a dark page it is gentle: at 30
-forge's text goes from 15.5:1 to 11.2:1 and dusk's from 6.4:1 to 4.8:1,
-plainly quieter and still easy reading; at 10 forge barely moves (14.1:1).
-On a light page the same percent bites far harder (acme: 7.0:1 at 10, the
-4.5 floor at 30), which is why `auto` shades there instead of dimming.
-
-Notes on G4: the three are post passes, so each is a frame of cost only
-when it is in the chain. None moves (grain is still, by choice: moving
-grain would redraw every frame for a texture), so none asks for frames.
-The focus rule is kept by construction: the shell hands every pass the
-rectangles of the tags (with their grips), the column and workspace tags,
-the notices and the cursor, and a bundled pass leaves them as they are; its
-strength is capped per theme so the text on the page and the selection's
-text keep min(their contrast, 4.5) (Post.capsOf, tested over the native
-themes). Bloom takes only what is brighter than the page, so a light page
-does not bloom at all; its glow is a dual Kawase blur in float textures at
-half size and down (3 to 5 steps by level), within §8.2's 5%. The vignette
-is round, starts halfway to a corner and reaches 10, 18 and 28%. Grain is
-1.5, 3 and 5 of 255 on page-coloured pixels only, a logical pixel big.
-Found on the way: SDL GPU binds at most 4 KiB of a uniform block, so every
-Shadertoy colour after the palette (iBackgroundColor and on) read zero; the
-block is now cut in three with ghostty's names and order kept.
-
-Notes on G5: lapis (src/themes/lapis.zig) is 0x4200.cafe's lapis.css in
-pardes's chrome, drawn inside it (decision 1). The tags are the site's
-trail and title bars: every tag a plaque in its own band, framed in gold
-(2 px, the trail's border) with the trail's hard vermilion shadow (5 px)
-down and right, the frame and the shadow both inside the band's rows and
-columns, so no shadow reaches a body, a grip or the next pane; down, the
-shadow gets what the band's slack under the text leaves (a pixel or three
-at a tagline under the body's size, more at a larger one), to the right
-its full offset. The focused pane's plaque is the code window's title bar,
-gold and lapis stripes of 2 px, its words on plates of the focused ground
-(the words' cells stay opaque, the blanks between let the stripes show),
-so the focus indicator is plainer to see than any theme's tint, never
-less; the unfocused ones are plain. Column and workspace tags take the
-quieter object-label language: a 1 px frame and a 2 px shadow of vermilion
-toward the page. The plaques are decor drawn under their cells (a group's
-under range) with the cells blended premultiplied over them; blank tag
-cells on the tag's ground are see-through there. They need an opaque
-window: under WindowOpacity 100 the tags are plain. Also from the site:
-the colours (lapis-deep page, vellum text, gold names and rules,
-vermilion rubrics and tag rule, gold selection in lapis ink), the page's
-gold dot grid (22 px, #e8c46a22) on page-coloured cells only, fixed to the
-window; the dither frame's checker in the scroll track, anchored to its
-rail (the thumb solid gold); the titles' vermilion offset shadow under a
-file name's letters. Left out: Crimson Pro and Departure Mono, the
-ornaments, a decor crossfade (it snaps while the colours fade). The tty
-shows the colours alone: a tag row abuts its body and its neighbour, so
-there is no cell for a shadow row or column.
-
-Notes on G6: a mouse wheel's notch (SDL's whole-number step) scrolls the
-core by its lines at once, so keys and clicks act where the text is, and
-the picture follows on the Motion flavour's spring at half again its pace,
-critically damped whatever the flavour (text never passes its mark; §8.1),
-from its current speed, so notches in a row carry on without a stall. How
-far the rows moved is measured on the next frame against the last (a
-wrapped line's rows, a terminal's output), within a couple of rows' slack
-for the cursor's line and its number moving with the scroll; the rows that
-left are kept and drawn in the gap the lag opens, and a lag is never more
-than the body's height (a flick past that jumps). A touchpad's fractions
-keep moving the picture under the finger, as before; there is no momentum
-(SDL reports no finger lift on a wheel). The glide runs on the core's
-continuous path (Pardes.shell_continuous), so the shell draws every loop
-while it moves and a virtual clock moves with it; idle, it costs nothing.
-A PDF page scrolls as before. The test feed takes wheel events
-(ESC]777;mouse;wheel;<amount>;<x>;<y>BEL).
-
-Notes on G7: the geometry already followed the Motion flavour's spring
-(sxrrwplk); a move retargeted mid-way now carries its speed on
-(Track.launch, from the old move's speed along the new one's longest
-side), so a second Newcol during a slide bends the motion instead of
-stopping it dead. A pane that slides, zooms or rises stands off the page
-while it moves: a soft shadow as Lift's, at sin(pi x progress) of its
-strength (none as it sets out or lands), on the other panes' bodies and
-rails alone and under the same contrast ceiling, moving with the pane. The
-GUI's PanelDissolve is a crossfade: a changed cell's new form drawn whole,
-its old one over it at 1 - progress; the blend is in sRGB, not linear
-light (a two-colour mix in linear light needs both in one shader; open
-point 3). The tty keeps its per-cell swap. GUI golden 18-mid-transition
-changes (the slide's shadow at frame 6).
-
-Notes on G8: most of it was there: the drop eases out on the Motion
-flavour's spring (sxrrwplk), the dissolve eases in, and a notice floats in
-tier 4 with Lift's shadow at its fade while Lift is on, on the bodies
-alone. What G8 changed: leaving was slower than arriving (a 300 ms
-dissolve against a 180 ms fall); §8.1 wants leaving the quicker, in 100 to
-160 ms, so MessageDissolve now defaults to 150 (a test holds both bands).
-
-Notes on G9: the halo is Lift's soft kind in the selection's own colour,
-cast by each block of selected rows in a pane body (the rows that touch),
-with the block as its caster, so the selection itself is never touched;
-a cursor beside a block joins the caster, so it is never glowed over
-either. It stays on bodies (never a tag or a grip), is at most 22% (§8.2:
-coloured glows at most 25%) and less where the text round it would drop
-below min(its contrast, 4.5); it comes up over 100 ms with an ease-out
-(micro-feedback), on the core's continuous path, and is not drawn while
-panes move. The blocks are read from the cells painted in the theme's
-selection colour, a pixel shell's inference (§1.5, smell 4) until
-selections are regions.
-
-Notes on G10: a theme change already faded the chrome (tags, rules, grips,
-rails) over 10 frames (160 ms, in §8.1's 150 to 250 for a state change),
-mixing sRGB bytes linearly in time. Now each colour goes through OKLab, so
-a fade between two hues keeps its lightness instead of dipping dark and
-muddy, on a smooth ease-in-out; a change made mid-fade sets off from where
-it shows and eases out, so it moves at once instead of stalling. The page,
-its text and the syntax colours still change at once with the theme, as
-before: fading them would re-resolve every cell each frame.
-
-Notes on G11: the word a look-hover would open is already lit (the
-affordance's tint); HoverGlow adds a strip three logical pixels tall along
-its foot in the theme's accent, its edges blurred by one, at most 22% and
-under the text's contrast floor, fading in over 80 ms (micro-feedback). It
-stays on bodies and is split round a cursor, so it never touches one. The
-word is found by the tint's colour, as G9 finds the selection.
-Found while reviewing: with the machine loaded, test/gui_golden.py's
-two-captures-agree settle can take a scene's frame before the scene's
-change lands, and every later hash moves up a scene; a rerun on a quiet
-machine matches.
-
-Notes on G12: four soft strips cast from just outside each body inward,
-clipped to it and round a cursor, black in linear light, 2% at most and
-under the lift's contrast ceiling, in the pane's own group so it moves
-with it. At §9.1's strength it is all but invisible on a dark page (a
-level of 255 on forge) and faint on a light one (acme's page steps one
-level toward the edges); acme-diff-x40.png shows where it falls.
-
-Notes on G13: a body region now carries its first line (Region.line: a
-file's scroll, a terminal's grid offset; on the wire, a u32 more a
-region). Under Parallax the dots under each body are offset by a quarter
-of its line times the row height, plus G6's glide offset while one runs,
-so they drift with the text as it glides and settle with it (measured: 4
-lines at 35 px move the 22 px grid 13 px, 35 mod 22). The cell shader
-reads the offset from the instance's serial slot, free since G7 took the
-dissolve's per-cell noise out. Without a pattern, nothing happens.
-
-Notes on G14: removed with its builtin, setting and code after the user
-saw it in the lapis showcase: "one of the animations is like a flashing on
-the whole pane or something, that is really bad, just remove it". Every
-changed cell glowing meant a pane whose whole text changed flashed whole.
-
-## Terminal track (§9.2)
-
-Audit, after decision 2 (keep every whimsical effect and polish it, never
-remove it): the six core-composed character transitions (ascii, edges,
-fall, wave, scramble, typewriter) and curtain stay as they are, each
-bounded to its pane's final rectangle and each cell's last sample its
-canonical one; slide and vertical are the tty compositor's and follow the
-Motion flavour (sxrrwplk); zoom stays (nearest-cell scaling, its look is
-the effect); dissolve swaps each changed cell once at its threshold;
-message fades and the theme's chrome fade are the core's (the latter in
-OKLab since G10), and InactiveDim (T5's unfocused dim) works in a grid as
-it does in a pixel shell.
-
-| # | effect | switch | state | review material | verdict |
-|---|---|---|---|---|---|
-| T2 | cursor jump trail | `JumpTrail on\|off` (off) | a jump of three cells or more leaves 3 to 5 cells of trail behind the cursor, their ground drawn toward the text's colour in OKLab, most beside it, fading in 120 ms; truecolor terminals (vaxis's answer or COLORTERM); never the cursor's cell, a selection or outside the focused body; off under Motion off; a few cells a frame | .scratch/render/tty/trail/ (pyte replay of a real tui session at 60 fps: trail-forge.mp4, zooms) | pending |
-| T1 chip shadow | `ChipShadow on\|off` (off) | a notice chip casts a shadow a cell right and down in its body: half blocks (▌ ▀ ▘) in a darker ground on blank cells, the ground 35% darker (OKLab) under text; never the cursor, a selection, a tag or another chip; truecolor only | .scratch/render/tty/shadow/ (forge, acme; zooms) | pending |
-| T4 ordered swap | `PanelDissolve` (off) | the terminal's dissolve swaps each changed cell once at its place in a 4x4 Bayer matrix (shifted per pane), an even patterned screen instead of noise; hit-testing follows the same order | .scratch/render/tty/dissolve/ (ordered-swap-sim: the matrix applied to two real frames; see note) | pending |
-| T7 thumb flash | `ThumbFlash on\|off` (off) | a pane whose view moves has its scroll thumb drawn toward the text's colour, 60% at once and back over 250 ms (quadratic); the thumb only, never a focus indicator; truecolor only; a few cells a frame while it fades | .scratch/render/tty/thumb-flash.mp4, thumb-flash-strip.png (pyte replay, forge) | pending |
-| T3 wipe | `PanelCurtain` (off) | the curtain becomes a wipe, left to right: new grid behind the head, old ahead, and a soft edge of two columns whose ink and ground sit 2/3 and 1/3 of the way to the old ground (OKLab; a palette colour steps at the half); only the head's columns change a frame; the head's cells are not hit-testable until settled | .scratch/render/tty/wipe/ (curtain-gui.mp4, curtain-edge-zoom.png) | pending |
-
-Note on T4's material: a pane opening in a tui session recorded through
-pyte did not animate (PanelSlide did not either there), so the review
-material applies the same matrix to two real frames of that session; the
-unit test holds the order (a 4x4 block reveals exactly t x 16 cells).
-
-Not built: T5 (unfocused dim) is InactiveDim, which already works in a
-grid. T6 (a truecolor ramp on the active tag band) would change the
-focused tag's colour, a focus indicator no effect may alter, so it stays
-out. The §9.2 byte budget (deferring a sample after an oversized frame,
-DECRQM for sync 2026) is not built either: the terminal effects here change
-a few cells a frame, and only PanelSlide rewrites a whole pane per sample.