ttym patches
============

Each patch is a unified diff against the pristine base. Apply with:

    cd ttym
    patch -p1 < patches/ttym-<name>-2.0.diff

Then rebuild:

    rm -f config.h ; make

To get every feature at once, skip the individual patches entirely and
apply ttym-full-2.0.diff -- one combined diff, no conflicts to resolve.
See "The full build" below.


The full build
--------------

  ttym-full-2.0.diff
      Every feature in a single patch: persist-alert, flash, notify,
      logging, hooks, bar-styles and config-file, with all inter-patch
      conflicts already resolved. Apply it to the pristine base and
      rebuild:

          patch -p1 < patches/ttym-full-2.0.diff
          rm -f config.h ; make

      This is the recommended route to the full-featured build. It is
      equivalent to stacking all seven feature patches below and hand-
      resolving every collision, but deterministic and conflict-free.
      Use the individual patches only when you want a specific subset.


Available patches
-----------------

  ttym-persist-alert-2.0.diff
      After a countdown completes, keep ringing the bell every ~1.5s
      until any key is pressed. Foreground-only; backgrounded runs
      fall through. Adds: --no-persist flag, ALERT_PERSIST knob.

  ttym-flash-2.0.diff                              [requires persist-alert]
      Add reverse-video terminal flash to the persistent alert loop.
      Adds: --flash on|off flag, FLASH knob.

  ttym-notify-2.0.diff
      One-shot desktop notification and sound on countdown completion,
      plus a MESSAGE positional argument piped through {title}/{msg}
      placeholders. Adds: TITLE, NOTIFY_CMD, SOUND_CMD knobs.

  ttym-logging-2.0.diff
      TSV log at ~/.config/ttym/ttym.log, +tag extraction, the -r
      reader (-n, --raw), and --stats (today|week|month|all). Adds
      one-shot directory migration from ~/.config/timer/.
      Adds: -c TEXT flag.

  ttym-hooks-2.0.diff
      Optional executables at ~/.config/ttym/hooks/{on_start,on_done,
      on_quit} invoked with: mode duration_seconds comment.
      Adds: -c TEXT flag (passed as 3rd hook arg).

  ttym-bar-styles-2.0.diff
      Eight built-in bar styles (unicode, ascii, hash, dots, line,
      block, arrow, minimal) with locale-aware auto-detect.
      Adds: --bar STYLE flag, BAR_STYLE knob.

  ttym-config-file-2.0.diff               [capstone -- see Dependencies]
      Runtime config at ~/.config/ttym/config (key = value), auto-
      generated and self-documenting on first run. Exposes eight keys:
      bar_fill, bar_empty, bar_style, flash, alert_persist, title,
      notify_cmd, sound_cmd. A system-wide /etc/ttym.conf is read
      first. Because it wires up knobs owned by other patches, it must
      be applied LAST.


Dependencies
------------

flash depends on persist-alert.

config-file is the capstone: it reads knobs introduced by persist-
alert, flash, notify, logging and bar-styles, and extends a usage()
line added by hooks -- so all six must be applied before it. Apply
config-file last.

All other patches are independent of each other and of the base.


Stacking
--------

The simplest route to the full build is ttym-full-2.0.diff (see "The
full build" above). The notes here apply only when stacking the
feature patches by hand to assemble a subset.

Every patch in this directory applies and compiles cleanly against the
pristine base -- except flash, which builds on persist-alert, and
config-file, the capstone, which builds on six other patches (see
Dependencies). That is the property the verification step guarantees.

Combining multiple optional patches will produce conflicts at shared
regions: the Config struct, usage(), the getopt() option string, and
in some cases #include lines. This is normal suckless territory --
resolve by hand, or apply ttym-full-2.0.diff instead. The base is laid
out so most patches add their new code in fresh sections (before
usage(), before main()) where they do not collide; the inevitable
collisions are in points where every patch must add a line or field.

Recommended order when stacking:

    persist-alert  ->  flash  ->  notify  ->  logging  ->  hooks  ->
    bar-styles     ->  config-file

config-file must come last -- after bar-styles in particular, since it
overrides the resolved bar glyphs. Apply, resolve any .rej files,
rebuild.


Authoring new patches
---------------------

Match the discipline used here:

  - Add compile-time knobs to config.def.h, never inline in ttym.c.
  - Update usage() in the same hunk as the option parser change, so
    `timer -h` never drifts from what the build actually supports.
  - Verify with `patch -p1` against a fresh copy of the base -- or,
    for a patch with prerequisites, the base plus those -- and confirm
    the result compiles before publishing.
  - When the patch set changes, regenerate ttym-full-2.0.diff so the
    one-shot full build stays in sync.