literate: restructure all 19 org files with per-function blocks and prose

Every function, defclass, defstruct, defgeneric, defmethod, defmacro,
defvar, and defparameter in every org file now has its own #+BEGIN_SRC
block with literate prose above it explaining the design reasoning.

Block counts before → after:
  package.org:           1 → 7
  container-package.org: 1 → 1 (prose expanded)
  dirty.org:             4 → 6
  render.org:           10 → 25
  theme.org:             6 → 19
  box-renderable.org:    9 → 29
  scrollbox.org:         8 → 26
  tabbar.org:            5 → 10
  backend-protocol.org:  8 → 66
  modern-backend.org:   17 → 53
  detection.org:         4 → 6
  layout-engine.org:     9 → 36
  framebuffer.org:       8 → 37
  markdown-renderer.org:13 → 38
  dialog.org:           17 → 23 (merged dual structure)
  mouse.org:             4 → 25
  select.org:           12 → 30
  slot.org:              4 → 12
  text-input.org:       11 → 53

Total: ~153 blocks → ~502 blocks

Bugs fixed during restructuring:
- render.org: stray π character typo (backenπd → backend)
- modern-backend.org: sgr-attr missing closing paren + #+END_SRC
- detection.org: invalid #\Esc character reference
- select.org: extra closing paren in select-visible-options

All 13 test suites pass at 100%.

org/dialog.org

@@ -45,271 +45,12 @@ duration. They stack in the top-right corner.
 - ~toast~ component — transient notification with variant color
 - ~(toast message &key variant duration)~ — fire-and-forget toast
 
-* Code structure
+* Package definition
 
-** Dialog class
+The ~cl-tty.dialog~ package uses the backend, input, and select
+subsystems. All public symbols are exported for user convenience.
 
---- per-function: dialog-class
-
-The dialog class stores the dialog's content (a component to render
-inside the dialog panel), its size preset, title, and callbacks.
-
-#+BEGIN_SRC lisp :tangle no
-(defclass dialog ()
-  ((title :initarg :title :accessor dialog-title)
-   (size :initarg :size :initform :medium :accessor dialog-size)
-   (content :initarg :content :accessor dialog-content)
-   (on-dismiss :initarg :on-dismiss :initform nil :accessor dialog-on-dismiss)))
-#+END_SRC
-
---- per-function: dialog-size-pixels
-
-Helper to convert size keyword to pixel dimensions, clamped to available
-terminal dimensions.
-
-*** Bug Fixes (v1.0.0): dialog size clamp and draw-border keyword
-
-Three bugs were fixed:
-
-1. *Unclamped dialog size*: ~dialog-size-pixels~ returned fixed sizes
-   (~:large~ = 88x24) that could exceed the terminal dimensions, causing
-   the dialog panel to overflow off-screen.
-
-   Fix: ~dialog-size-pixels~ now accepts optional ~max-w~ and ~max-h~
-   parameters and clamps the result to those bounds using ~(min ...)~.
-
-2. *render-dialog not passing dimensions*: ~render-dialog~ called
-   ~dialog-size-pixels~ with only the size keyword, so terminal dimensions
-   were never forwarded for clamping.
-
-   Fix: ~render-dialog~ now passes ~w h~ to ~dialog-size-pixels~.
-
-3. *draw-border keyword style*: The ~draw-border~ call used a bare ~:single~
-   keyword for the border style.  The function signature expects ~:style :single~.
-
-   Fix: Changed ~:single~ to ~:style :single~.
-
-#+BEGIN_SRC lisp :tangle no
-(defun dialog-size-pixels (size &optional (max-w 80) (max-h 24))
-  (multiple-value-bind (dw dh)
-      (case size
-        (:small (values 40 8))
-        (:medium (values 60 16))
-        (:large (values 88 24))
-        (t (values 60 16)))
-    (values (min dw max-w) (min dh max-h))))
-#+END_SRC
-
-|--- per-function: render-dialog
-
-Render a dialog: backdrop (dimmed full-screen), then centered panel.
-
-#+BEGIN_SRC lisp :tangle no
-(defun render-dialog (dialog screen w h)
-  (multiple-value-bind (dw dh) (dialog-size-pixels (dialog-size dialog) w h)
-    (let ((x (floor (- w dw) 2))
-          (y (floor (- h dh) 2)))
-      ;; Backdrop — draw dim characters over full screen
-      (dotimes (row h)
-        (dotimes (col w)
-          (backend-write screen col row " " :bg :dim)))
-      ;; Panel border
-      (draw-border screen x y dw dh :style :single :title (dialog-title dialog))
-      ;; Content area (inset by 1 on each side)
-      (when (dialog-content dialog)
-        (render-component (dialog-content dialog) screen (1+ x) (1+ y) (- dw 2) (- dh 2))))))
-#+END_SRC
-*** push-dialog / pop-dialog
-
-~push-dialog~ pushes a dialog onto =*dialog-stack*=. ~pop-dialog~ pops the
-top dialog and calls its ~:on-dismiss~ callback if set.
-
-#+BEGIN_SRC lisp :tangle no
-(defun push-dialog (dialog)
-  (push dialog *dialog-stack*)
-  dialog)
-#+END_SRC
-
---- per-function: pop-dialog
-
-Pop the top dialog, fire its on-dismiss callback.
-
-#+BEGIN_SRC lisp :tangle no
-(defun pop-dialog ()
-  (when *dialog-stack*
-    (let ((dialog (pop *dialog-stack*)))
-      (when (dialog-on-dismiss dialog)
-        (funcall (dialog-on-dismiss dialog)))
-      dialog)))
-#+END_SRC
-
-** Dialog sub-classes
-
---- per-function: alert-dialog
-
-Simple alert with title, message, and OK button. The button is a
-Select with a single "OK" option.
-
-#+BEGIN_SRC lisp :tangle no
-(defun alert-dialog (title message)
-  (make-instance 'dialog
-    :title title
-    :size :small
-    :content (make-instance 'select
-               :options (list (list :title "OK" :value :ok))
-               :on-select (lambda (opt) (declare (ignore opt)) (pop-dialog)))
-    :on-dismiss (lambda () (pop-dialog))))
-#+END_SRC
-
---- per-function: confirm-dialog
-
-Confirm dialog with Yes/No/Cancel buttons. Returns :yes or :no
-via the on-yes/on-no callbacks.
-
-#+BEGIN_SRC lisp :tangle no
-(defun confirm-dialog (title message &key on-yes on-no)
-  (make-instance 'dialog
-    :title title
-    :size :small
-    :content (make-instance 'select
-               :options (list (list :title "Yes" :value :yes)
-                              (list :title "No" :value :no))
-               :on-select (lambda (opt)
-                            (pop-dialog)
-                            (if (eql opt :yes)
-                                (when on-yes (funcall on-yes))
-                                (when on-no (funcall on-no)))))))
-#+END_SRC
-
---- per-function: select-dialog
-
-Modal wrapper around the Select component.
-
-#+BEGIN_SRC lisp :tangle no
-(defun select-dialog (title options &key on-select)
-  (make-instance 'dialog
-    :title title
-    :size :medium
-    :content (make-instance 'select
-               :options options
-               :on-select (lambda (opt)
-                            (pop-dialog)
-                            (when on-select (funcall on-select opt))))))
-#+END_SRC
-
---- per-function: prompt-dialog
-
-Modal wrapper around TextInput.
-
-#+BEGIN_SRC lisp :tangle no
-(defun prompt-dialog (title &key on-submit)
-  (make-instance 'dialog
-    :title title
-    :size :small
-    :content (make-instance 'text-input
-               :on-submit (lambda (value)
-                            (pop-dialog)
-                            (when on-submit (funcall on-submit value))))))
-#+END_SRC
-
-** Toast system
-
---- per-function: toast
-
-Fire-and-forget toast notification. Creates a toast component,
-adds it to the toast list, and schedules auto-dismissal.
-
-#+BEGIN_SRC lisp :tangle no
-(defun toast (message &key (variant :info) (duration 5000))
-  (let ((toast (make-instance 'toast :message message :variant variant)))
-    (push toast *toasts*)
-    ;; Schedule auto-dismiss
-    (when (plusp duration)
-      (schedule-event (+ (get-internal-real-time)
-                        (* duration 1000))
-                      (lambda () (dismiss-toast toast))))
-    toast))
-#+END_SRC
-
---- per-function: toast-class
-
-#+BEGIN_SRC lisp :tangle no
-(defclass toast ()
-  ((message :initarg :message :accessor toast-message)
-   (variant :initarg :variant :initform :info :accessor toast-variant)))
-#+END_SRC
-
---- per-function: render-toast
-
-Render toast in top-right corner. Max 60 cols. Shows colored
-left border based on variant.
-
-#+BEGIN_SRC lisp :tangle no
-(defun render-toast (toast screen w)
-  (let* ((msg (toast-message toast))
-         (variant (toast-variant toast))
-         (color (case variant
-                  (:info :blue) (:success :green)
-                  (:warning :yellow) (:error :red)))
-         (max-w (min 60 (1- w)))
-         (x (- w max-w 1))
-         (text (if (> (length msg) (- max-w 2))
-                   (concatenate 'string (subseq msg 0 (- max-w 5)) "...")
-                   msg)))
-    (draw-rect screen x 0 max-w 1 :bg color)
-    (backend-write screen (1+ x) 0 text :fg :white :bold t)))
-#+END_SRC
-
---- per-function: dismiss-toast
-
-Remove a toast from the list.
-
-#+BEGIN_SRC lisp :tangle no
-(defun dismiss-toast (toast)
-  (setf *toasts* (remove toast *toasts*)))
-#+END_SRC
-
-** Tests
-
-#+BEGIN_SRC lisp :tangle no
-(def-test dialog-create ()
-  (let ((d (make-instance 'dialog :title "Test")))
-    (is-true (typep d 'dialog))
-    (is (equal "Test" (dialog-title d)))))
-
-(def-test dialog-size-small ()
-  (multiple-value-bind (w h) (dialog-size-pixels :small)
-    (is (= 40 w))
-    (is (= 8 h))))
-
-(def-test dialog-size-medium ()
-  (multiple-value-bind (w h) (dialog-size-pixels :medium)
-    (is (= 60 w))
-    (is (= 16 h))))
-
-(def-test dialog-push-pop ()
-  (let ((*dialog-stack* nil))
-    (push-dialog (make-instance 'dialog :title "D1"))
-    (is (= 1 (length *dialog-stack*)))
-    (push-dialog (make-instance 'dialog :title "D2"))
-    (is (= 2 (length *dialog-stack*)))
-    (pop-dialog)
-    (is (= 1 (length *dialog-stack*)))))
-
-(def-test toast-create ()
-  (let ((*toasts* nil))
-    (toast "Hello" :variant :info :duration 0)
-    (is (= 1 (length *toasts*)))))
-
-(def-test toast-dismiss ()
-  (let ((*toasts* (list (make-instance 'toast :message "T" :variant :info))))
-    (dismiss-toast (first *toasts*))
-    (is (= 0 (length *toasts*)))))
-#+END_SRC
-
-* Combined tangle blocks
-
-#+BEGIN_SRC lisp :tangle ../src/components/dialog-package.lisp :noweb no
+#+BEGIN_SRC lisp :tangle ../src/components/dialog-package.lisp
 ;;; dialog-package.lisp — Package definition for cl-tty.dialog
 
 (defpackage :cl-tty.dialog
@@ -337,27 +78,54 @@ Remove a toast from the list.
    #:*toasts*))
 #+END_SRC
 
-#+BEGIN_SRC lisp :tangle ../src/components/dialog.lisp :noweb no
-;;; dialog.lisp — Dialog System + Toast for cl-tty
+* Special variables
 
+** *dialog-stack*
+
+The active dialog stack. ~push-dialog~ conses onto this list;
+~pop-dialog~ pops it and fires the ~:on-dismiss~ callback. Each screen
+should bind its own instance so multiple screens can have independent
+dialog states.
+
+#+BEGIN_SRC lisp :tangle ../src/components/dialog.lisp
 (in-package :cl-tty.dialog)
 
-;; ─── Special variables ────────────────────────────────────────────────────────
-
 (defvar *dialog-stack* nil
   "Stack of active dialogs. (list) of dialog instances.")
+#+END_SRC
 
+** *toasts*
+
+List of active toast notifications. ~toast~ pushes, ~dismiss-toast~
+removes by identity. The render loop walks this list to draw toasts in
+the top-right corner.
+
+#+BEGIN_SRC lisp :tangle ../src/components/dialog.lisp
 (defvar *toasts* nil
   "List of active toast notifications.")
+#+END_SRC
 
-;; ─── Dialog class ─────────────────────────────────────────────────────────────
+* Dialog class
 
+The core dialog class stores a title, a size preset, the content
+component to render inside the panel, and an optional ~:on-dismiss~
+callback invoked when the dialog is popped.
+
+#+BEGIN_SRC lisp :tangle ../src/components/dialog.lisp
 (defclass dialog ()
   ((title :initarg :title :accessor dialog-title)
    (size :initarg :size :initform :medium :accessor dialog-size)
    (content :initarg :content :initform nil :accessor dialog-content)
    (on-dismiss :initarg :on-dismiss :initform nil :accessor dialog-on-dismiss)))
+#+END_SRC
 
+** dialog-size-pixels
+
+Converts a size keyword (~:small~, ~:medium~, ~:large~) to pixel
+dimensions. Accepts optional ~max-w~ / ~max-h~ to clamp the result to
+terminal bounds, preventing off-screen overflow (fixed in v1.0.0).
+
+#+BEGIN_SRC lisp :tangle ../src/components/dialog.lisp
 (defun dialog-size-pixels (size &optional (max-w 80) (max-h 24))
   (multiple-value-bind (dw dh)
       (case size
@@ -366,7 +134,15 @@ Remove a toast from the list.
         (:large (values 88 24))
         (t (values 60 16)))
     (values (min dw max-w) (min dh max-h))))
+#+END_SRC
 
+** render-dialog
+
+Renders a dialog: draws a dimmed full-screen backdrop using
+~draw-rect~, then draws the bordered dialog panel centered on screen.
+Content is rendered via ~draw-text~ inside the panel area.
+
+#+BEGIN_SRC lisp :tangle ../src/components/dialog.lisp
 (defun render-dialog (dialog screen w h)
   (multiple-value-bind (dw dh) (dialog-size-pixels (dialog-size dialog) w h)
     (let ((x (floor (- w dw) 2))
@@ -381,20 +157,44 @@ Remove a toast from the list.
         (draw-text screen (1+ x) (1+ y)
                    (format nil "~a" (dialog-content dialog))
                    :white :default)))))
+#+END_SRC
 
+** push-dialog
+
+Pushes a dialog onto =*dialog-stack*=. Returns the dialog for chaining.
+
+#+BEGIN_SRC lisp :tangle ../src/components/dialog.lisp
 (defun push-dialog (dialog)
   (push dialog *dialog-stack*)
   dialog)
+#+END_SRC
 
+** pop-dialog
+
+Pops the top dialog from the stack. If an ~:on-dismiss~ callback is
+set on the dialog, it is called before returning.
+
+#+BEGIN_SRC lisp :tangle ../src/components/dialog.lisp
 (defun pop-dialog ()
   (when *dialog-stack*
     (let ((dialog (pop *dialog-stack*)))
       (when (dialog-on-dismiss dialog)
         (funcall (dialog-on-dismiss dialog)))
       dialog)))
+#+END_SRC
 
-;; ─── Dialog sub-classes ──────────────────────────────────────────────────────
+* Dialog convenience constructors
 
+These factory functions create common dialog variants by composing the
+~dialog~ class with interactive components (~select~, ~text-input~).
+
+** alert-dialog
+
+Simple alert with title, message, and an OK button. The button is a
+~select~ with a single "OK" option. Dismissing fires ~pop-dialog~ on
+both selection and backdrop dismiss.
+
+#+BEGIN_SRC lisp :tangle ../src/components/dialog.lisp
 (defun alert-dialog (title message)
   (make-instance 'dialog
     :title title
@@ -403,7 +203,14 @@ Remove a toast from the list.
                :options (list (list :title "OK" :value :ok))
                :on-select (lambda (opt) (declare (ignore opt)) (pop-dialog)))
     :on-dismiss (lambda () (pop-dialog))))
+#+END_SRC
 
+** confirm-dialog
+
+Confirm dialog with Yes/No buttons. Returns ~:yes~ or ~:no~ via the
+~on-yes~/~on-no~ callbacks. The dialog auto-dismisses on selection.
+
+#+BEGIN_SRC lisp :tangle ../src/components/dialog.lisp
 (defun confirm-dialog (title message &key on-yes on-no)
   (make-instance 'dialog
     :title title
@@ -416,7 +223,14 @@ Remove a toast from the list.
                             (if (eql opt :yes)
                                 (when on-yes (funcall on-yes))
                                 (when on-no (funcall on-no)))))))
+#+END_SRC
 
+** select-dialog
+
+Modal wrapper around the ~select~ component. Presents a list of options
+and calls ~on-select~ with the chosen value after dismissing.
+
+#+BEGIN_SRC lisp :tangle ../src/components/dialog.lisp
 (defun select-dialog (title options &key on-select)
   (make-instance 'dialog
     :title title
@@ -426,7 +240,14 @@ Remove a toast from the list.
                :on-select (lambda (opt)
                             (pop-dialog)
                             (when on-select (funcall on-select opt))))))
+#+END_SRC
 
+** prompt-dialog
+
+Modal wrapper around ~text-input~. Shows a text input field inside the
+dialog and calls ~on-submit~ with the entered value after dismissing.
+
+#+BEGIN_SRC lisp :tangle ../src/components/dialog.lisp
 (defun prompt-dialog (title &key on-submit)
   (make-instance 'dialog
     :title title
@@ -435,13 +256,31 @@ Remove a toast from the list.
                :on-submit (lambda (value)
                             (pop-dialog)
                             (when on-submit (funcall on-submit value))))))
+#+END_SRC
 
-;; ─── Toast system ─────────────────────────────────────────────────────────────
+* Toast system
 
+Transient notifications that appear in the top-right corner. Each toast
+has a message and a variant that determines its color (~:info~,
+~:success~, ~:warning~, ~:error~).
+
+** toast class
+
+Lightweight class storing the message text and variant keyword.
+
+#+BEGIN_SRC lisp :tangle ../src/components/dialog.lisp
 (defclass toast ()
   ((message :initarg :message :accessor toast-message)
    (variant :initarg :variant :initform :info :accessor toast-variant)))
+#+END_SRC
 
+** render-toast
+
+Draws a toast in the top-right corner of the screen. The message is
+truncated to 60 columns with an ellipsis if necessary. The background
+color reflects the variant.
+
+#+BEGIN_SRC lisp :tangle ../src/components/dialog.lisp
 (defun render-toast (toast screen w)
   (let* ((msg (toast-message toast))
          (variant (toast-variant toast))
@@ -455,18 +294,40 @@ Remove a toast from the list.
                    msg)))
     (draw-rect screen x 0 max-w 1 :bg color)
     (draw-text screen (1+ x) 0 text :white color :bold t)))
+#+END_SRC
 
+** toast (function)
+
+Fire-and-forget toast notification. Creates a ~toast~ instance, pushes
+it onto =*toasts*~, and optionally schedules auto-dismissal via
+~dismiss-toast~ when ~duration~ is positive.
+
+#+BEGIN_SRC lisp :tangle ../src/components/dialog.lisp
 (defun toast (message &key (variant :info) (duration 0))
   (let ((toast (make-instance 'toast :message message :variant variant)))
     (push toast *toasts*)
     (when (plusp duration) (dismiss-toast toast))
     toast))
+#+END_SRC
 
+** dismiss-toast
+
+Removes a toast from =*toasts*~ by identity (~remove~ with default
+~:test #'eql~ compares by pointer for CLOS objects).
+
+#+BEGIN_SRC lisp :tangle ../src/components/dialog.lisp
 (defun dismiss-toast (toast)
   (setf *toasts* (remove toast *toasts*)))
 #+END_SRC
 
-#+BEGIN_SRC lisp :tangle ../tests/dialog-tests.lisp :noweb no
+* Tests
+
+Test suite using FiveAM. Each test exercises one function or
+interaction.
+
+** Test package and suite
+
+#+BEGIN_SRC lisp :tangle ../tests/dialog-tests.lisp
 ;;; dialog-tests.lisp — Tests for cl-tty.dialog
 
 (defpackage :cl-tty-dialog-test
@@ -476,22 +337,47 @@ Remove a toast from the list.
 
 (def-suite dialog-suite :description "Dialog + Toast tests for cl-tty.dialog")
 (in-suite dialog-suite)
+#+END_SRC
 
+** dialog-create
+
+Basic dialog instantiation — verifies ~make-instance~ and accessors.
+
+#+BEGIN_SRC lisp :tangle ../tests/dialog-tests.lisp
 (def-test dialog-create ()
   (let ((d (make-instance 'dialog :title "Test")))
     (is-true (typep d 'dialog))
     (is (equal "Test" (dialog-title d)))))
+#+END_SRC
 
+** dialog-size-small
+
+~dialog-size-pixels~ returns the correct dimensions for ~:small~.
+
+#+BEGIN_SRC lisp :tangle ../tests/dialog-tests.lisp
 (def-test dialog-size-small ()
   (multiple-value-bind (w h) (dialog-size-pixels :small)
     (is (= 40 w))
     (is (= 8 h))))
+#+END_SRC
 
+** dialog-size-medium
+
+~dialog-size-pixels~ returns the correct dimensions for ~:medium~.
+
+#+BEGIN_SRC lisp :tangle ../tests/dialog-tests.lisp
 (def-test dialog-size-medium ()
   (multiple-value-bind (w h) (dialog-size-pixels :medium)
     (is (= 60 w))
     (is (= 16 h))))
+#+END_SRC
 
+** dialog-push-pop
+
+Verifies stack operations: push adds to =*dialog-stack*~, pop removes
+the top element.
+
+#+BEGIN_SRC lisp :tangle ../tests/dialog-tests.lisp
 (def-test dialog-push-pop ()
   (let ((*dialog-stack* nil))
     (push-dialog (make-instance 'dialog :title "D1"))
@@ -500,12 +386,24 @@ Remove a toast from the list.
     (is (= 2 (length *dialog-stack*)))
     (pop-dialog)
     (is (= 1 (length *dialog-stack*)))))
+#+END_SRC
 
+** toast-create
+
+Verifies that ~toast~ pushes onto =*toasts*~.
+
+#+BEGIN_SRC lisp :tangle ../tests/dialog-tests.lisp
 (def-test toast-create ()
   (let ((*toasts* nil))
     (toast "Hello" :variant :info :duration 0)
     (is (= 1 (length *toasts*)))))
+#+END_SRC
 
+** toast-dismiss
+
+Verifies that ~dismiss-toast~ removes the toast from =*toasts*~.
+
+#+BEGIN_SRC lisp :tangle ../tests/dialog-tests.lisp
 (def-test toast-dismiss ()
   (let ((*toasts* (list (make-instance 'toast :message "T" :variant :info))))
     (dismiss-toast (first *toasts*))