screenbuffer 0.1.0__tar.gz → 1.0.1__tar.gz

{screenbuffer-0.1.0/screenbuffer.egg-info → screenbuffer-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: screenbuffer
-Version: 0.1.0
+Version: 1.0.1
 Summary: A Python utility for managing dynamic output, tracking progress, and organizing information throughout data-driven workflows.
 Keywords: jupyter,notebook,progress,logging,display,data
 Classifier: Programming Language :: Python :: 3
@@ -14,45 +14,52 @@ Requires-Dist: ipython; extra == "jupyter"
 
 # ScreenBuffer
 
-**A Python utility for managing dynamic output, tracking progress, and organizing information throughout data-driven workflows.**
+**A live output panel for Jupyter: a pinned header, a body that shows the newest N lines, and a footer for anything you want. Change any part, any time, and the rest stays exactly where it is.**
 
 Long-running loops (scrapers, ETL jobs, model sweeps, simulations, data pulls) leave you two bad choices in Jupyter:
 
 - `print()` every step: the cell fills with thousands of lines you cannot read.
 - `clear_output()` every step: you lose everything, including the parts you wanted to keep (a progress header, a running total, the last error).
 
-ScreenBuffer keeps the output as a **list of lines** and redraws the whole panel from that list. You change one line, the header, or the footer; the rest stays on screen. Every line is also appended to a log file, so the screen can stay small while the full history is kept.
+ScreenBuffer is the third choice. It keeps the output as a **list of numbered lines** and redraws the whole panel from that list. You decide what lives at each index, and you rewrite a slot whenever you like. The rest of the screen never moves.
 
 ```python
 from screenbuffer import ScreenBuffer
 
-sb = ScreenBuffer(max_display=8, header="Scraper | page 0/200",
-                  log_file="scrape_run", max_wait=1000, start=True)
+sb = ScreenBuffer(max_display=8, header="Scraper, page 0/200")
 
 for i, page in enumerate(pages, 1):
-    sb.update(header=f"Scraper | page {i}/200")
+    sb.update(header=f"Scraper, page {i}/200")
     sb.put(f"page {i}: +{len(page)} rows")
     sb.display()                                       # draw once per step
 ```
 
 The panel shows a fixed header, the newest 8 lines, and (optionally) a footer. Nothing else on screen moves.
 
+That is the whole style: header, body, footer. [Header, body, footer](#header-body-footer) shows the different ways to play it.
+
 ---
 
 ## Who it is for
 
-Analysts, data engineers, data scientists and researchers who run long jobs in Jupyter and want to watch progress without flooding the cell, and who want a plain-text record of what happened.
+Analysts, data engineers, data scientists and researchers who run long jobs in Jupyter and want to watch progress without flooding the cell, and who want a plain-text record of what happened if they ask for one.
 
-**Not** for: plain terminals or scripts outside Jupyter (it is Jupyter-only for now), rich dashboards (use `tqdm`, `rich`, or a BI tool), or log shipping (it writes local text files; sending them elsewhere is up to you).
+---
 
 ## Requirements
 
 - Python 3.8+ and Jupyter (Notebook, JupyterLab, VS Code, or a Jupyter console).
 - No third-party packages. Uses `IPython.display.clear_output`; if IPython is missing, drawing silently does nothing (the buffer and log still work).
 
+---
+
 ## Install
 
-Copy the `screenbuffer/` folder next to your work (or onto your `PYTHONPATH`), then:
+```
+pip install screenbuffer
+```
+
+In a notebook cell, use `%pip install screenbuffer` so it installs into the kernel's environment. Then:
 
 ```python
 from screenbuffer import ScreenBuffer
@@ -60,56 +67,122 @@ from screenbuffer import ScreenBuffer
 
 ---
 
-## Create a buffer
+## Header, body, footer
 
-Everything starts here. All arguments are optional.
+Every panel has three parts:
+
+```
+header      pinned at the top. Set it with header=, change it with sb.update(header=...)
+body        the lines you put(). max_display is how many of them are shown
+footer      pinned at the bottom. Anything you want: counters, status, ETA, an error banner
+```
+
+The header and footer never scroll. The body is the window of `max_display` lines. You decide what goes in each part, and you can change any of them in the middle of a loop.
+
+### Ways to play
+
+**1. Rolling body.** Append lines and let the window show the newest N. Use the footer for the running count.
 
 ```python
-sb = ScreenBuffer(
-    wait=True,                     # False = redraw on every change
-    log_file=None,                 # name for the log set; None = no files
-    max_main=None,                 # history file line cap
-    max_wait=None,                 # saved-buffer file line cap
-    max_display=None,              # lines drawn (newest N)
-    start=False,                   # True = wipe existing files for this log_file
-    header=None, header_alignment=None,
-    footer=None, footer_alignment=None,
-    show_header=None, show_footer=None,
-    silent_display=None, only_display=None,
-    auto_clean_edges=False,
-    auto_clean_silent_only_display=False,
-    shift_max_display=True,
-    width=None,                    # None = detect terminal width
-)
+sb = ScreenBuffer(max_display=8, width=70,
+                  header="Scraper", header_alignment="center",
+                  footer="starting", footer_alignment="center")
+
+for i, page in enumerate(pages, 1):
+    sb.put(f"page {i}: +{len(page)} rows")
+    sb.update(footer=f"{i}/{len(pages)} pages")
+    sb.display()                                  # one redraw per step
 ```
 
-| Argument | What it does | Details |
-|---|---|---|
-| `wait` | `True` (default): draw only when you call `display()`. `False`: redraw on every change | [Redraw modes](#redraw-modes) |
-| `log_file` | Name of the log set (creates `screen_buffer_logs/<name>.txt` and companions). `None` = nothing written to disk | [Log files](#log-files) |
-| `start` | `True` wipes existing files for that name; `False` restores the saved panel | [Persistence](#persistence-and-resume) |
-| `max_display` | Draw only the newest N lines | [Display window](#display-window) |
-| `max_main`, `max_wait` | Line caps for the history and saved-buffer files | [Limits](#limits-and-long-runs) |
-| `header`, `footer` | Fixed text above / below the lines | [Header and footer](#header-and-footer) |
-| `header_alignment`, `footer_alignment` | Alignment for those two | [Alignment](#alignment) |
-| `show_header`, `show_footer` | Hide or show them (default: shown when text is set) | [Header and footer](#header-and-footer) |
-| `silent_display`, `only_display` | Hide some lines / show only some lines | [Filtering](#filtering) |
-| `auto_clean_silent_only_display`, `shift_max_display`, `auto_clean_edges` | Fine-tune filtering and spacing | [Filtering](#filtering) |
-| `width` | Panel width in columns for `center` / `right`; `None` = detect | [Alignment](#alignment) |
+**2. Slot body.** Treat the body as a few fixed slots and rewrite them by index. Writing to the highest index builds all the slots in one call, and `max_display` equals the number of slots, so every slot is always on screen.
 
-Typical setups:
+```python
+sb = ScreenBuffer(max_display=3, header="Current job", footer="running")
+sb.put("", index=2)                               # builds body slots 0, 1 and 2
+
+for item in items:
+    sb.put(f"working on {item}", index=0)         # slot 0: what is running now
+    try:
+        sb.put(f"last ok: {work(item)}", index=1) # slot 1: last success
+    except Exception as e:
+        sb.put(f"last error: {e}", index=2)       # slot 2: last error
+    sb.display()
+```
+
+**3. Ring of recent results.** Keep a small list and rewrite the slots each time. No deleting, and the newest result is always at the bottom.
 
 ```python
-sb = ScreenBuffer()                                              # simplest: collect lines, then sb.display()
-sb = ScreenBuffer(wait=False, max_display=10)                    # live panel, newest 10 lines
-sb = ScreenBuffer(max_display=10, log_file="run1", max_wait=1000, start=True)   # long job with a log
+sb = ScreenBuffer(max_display=4, footer="0 found")
+sb.put("", index=3)
+
+recent = []
+for n, item in enumerate(items, 1):
+    if hit(item):
+        recent = (recent + [str(item)])[-4:]
+        for k, text in enumerate(recent):
+            sb.put(text, index=k)
+    sb.update(footer=f"{n}/{len(items)} checked")
+    sb.display()
 ```
 
+**4. Scoreboard.** One body slot per metric, rewritten every step.
+
+```python
+sb = ScreenBuffer(max_display=3, header="Run stats")
+sb.put("", index=2)
+sb.put(f"rows: {rows}", index=0)
+sb.put(f"errors: {errors}", index=1)
+sb.put(f"speed: {speed}/s", index=2)
+sb.display()
+```
+
+**5. Footer as a banner.** The footer can carry a warning and then go back to normal.
+
+```python
+sb.update(footer="!! network error, retrying !!")
+sb.display()
+# later
+sb.update(footer="back online")
+```
+
+### Mixing and matching
+
+| Move | How |
+|---|---|
+| Something that must always be visible | Put it in the header or footer |
+| A rolling log | Append with `sb.put("text")`; `max_display` shows the newest N |
+| Fixed slots | Build them with `put("", index=last)`, rewrite with `put(text, index=n)`, set `max_display` to the slot count |
+| A spacer line | `sb.put("", index=n)` |
+| Different looks per line | `alignment="center"`, `"right"`, or an indent |
+| A rolling log plus a status footer | Append to the body and call `sb.update(footer=...)` |
+
+### House rules
+
+1. **Use the header and footer for what must stay visible.** They never scroll, whatever the body does.
+2. **The body is `max_display` lines.** Append for a rolling log, or rewrite by index for fixed slots.
+3. **For slots, match the window to the slot count.** Then nothing scrolls out, and appending would break the layout, so rewrite instead.
+4. **One redraw per step.** Keep the default `wait=True` and call `sb.display()` once at the end of each step, so you never see a half-updated panel.
+5. **Spacing is yours.** `auto_clean_edges=True` trims blank edge lines in the body and adds one blank line on each side. For a tight panel, leave it `False` and add your own blank lines.
+
+It is still one plain list of lines, so everything else works too: per-line alignment, a log of every change, filters, and resume after a crash.
+
+---
+
+## Core concepts
+
+- **Slots**: body lines used as fixed numbered positions that you rewrite by index. See [Header, body, footer](#header-body-footer).
+- **Buffer**: the list of all lines you have `put()`. Each line has an index (0, 1, 2, ...).
+- **View**: what is drawn. It is the header, then the visible lines (after the window and any filter), then the footer.
+- **History log**: a timestamped file of every `put()`, only if you set `log_file`. Append-only record of the run.
+- **Wait file**: a saved copy of the *current* buffer, so the panel can be restored (also only with `log_file`).
+
+The screen is redrawn with Jupyter's own `clear_output(wait=True)`: the old frame stays until the new text is ready, then they are swapped. The new text is printed as one string, with your exact spacing.
+
 ---
 
 ## `put()`: the core call
 
-`put()` is how everything gets into the panel. Every other feature (alignment, window, filters, logs, resume) works on the lines you `put()`.
+`put()` is how everything gets into the panel. It is also how you rewrite slots. Every other feature (alignment, window, filters, logs, resume) works on the lines you `put()`.
 
 ```python
 sb.put(text, state=0, index=None, fill_value=None, alignment=None)
@@ -135,7 +208,7 @@ sb.put("row 10", index=10)               # lines 2..9 become blank, line 10 is "
 sb.put("progress: 80%", index=-1)        # negative: replaces the LAST line
 ```
 
-**Replacing by index is the "update one part in a loop" trick.** Reserve a line, then keep rewriting it:
+**Replacing by index is the "update one part in a loop" trick**, and it is how slots work (see [Header, body, footer](#header-body-footer)). Reserve a line, then keep rewriting it:
 
 ```python
 sb.put("Progress: 0%", index=0)           # reserve line 0 as a status line
@@ -144,7 +217,7 @@ for i in range(100):
     sb.put(f"processed item {i}")         # new lines keep appending below
 ```
 
-(In a window with `max_display`, a line that has scrolled out of the window is still updated in the buffer, but you won't see it. Keep status lines in the header or footer if they must always be visible.)
+(In a window with `max_display`, a line that has scrolled out of the window is still updated in the buffer, but you won't see it. To keep something always visible, use the header or footer, or keep the buffer no longer than the window, as in the slot body (see [Header, body, footer](#header-body-footer)).)
 
 ### What happens on every `put()`
 
@@ -170,53 +243,78 @@ The history entry records the index, even for replacements:
 
 ---
 
-## Feature index
+## Create a buffer
 
-Find what you need:
+Everything starts here. All arguments are optional.
 
-| I want to... | Use | Section |
+```python
+sb = ScreenBuffer(
+    wait=True,                     # False = redraw on every change
+    log_file=None,                 # name for the log set; None = no files
+    max_main=None,                 # history file line cap
+    max_wait=None,                 # saved-buffer file line cap
+    max_display=None,              # lines drawn (newest N)
+    start=False,                   # True = wipe existing files for this log_file
+    header=None, header_alignment=None,
+    footer=None, footer_alignment=None,
+    show_header=None, show_footer=None,
+    silent_display=None, only_display=None,
+    auto_clean_edges=False,
+    auto_clean_silent_only_display=False,
+    shift_max_display=True,
+    width=None,                    # None = detect terminal width
+)
+```
+
+| Argument | What it does | Details |
 |---|---|---|
-| Create a buffer, see every option | `ScreenBuffer(...)` | [Create a buffer](#create-a-buffer) |
-| Add a line | `sb.put("text")` | [put()](#put-the-core-call) |
-| Replace / update an existing line | `sb.put("new", index=3)` | [put()](#put-the-core-call) |
-| Mark a line OK / warning / error in the log | `sb.put("x", state=0/1/2)` | [put()](#put-the-core-call) |
-| Center, right-align or indent a line | `put(..., alignment=...)` | [Alignment](#alignment) |
-| Show only the newest N lines | `max_display=N` | [Display window](#display-window) |
-| Have a fixed header / footer | `header=`, `footer=` | [Header and footer](#header-and-footer) |
-| Change header/footer in a loop | `sb.update(header=...)` | [Header and footer](#header-and-footer) |
-| Hide / show header or footer | `show_header`, `show_footer` | [Header and footer](#header-and-footer) |
-| Draw once per loop step (no flicker) | `wait=True` + `sb.display()` | [Smooth updates](#smooth-updates) |
-| Control when the screen redraws | `wait=True/False`, `sb.display()` | [Redraw modes](#redraw-modes) |
-| Hide some lines on screen, keep them stored | `silent_display=` | [Filtering](#filtering) |
-| Show only some lines on screen | `only_display=` | [Filtering](#filtering) |
-| Remove blank gaps left by filtering | `auto_clean_silent_only_display=True` | [Filtering](#filtering) |
-| Delete lines | `sb.delete(...)` | [Deleting and clearing](#deleting-and-clearing) |
-| Wipe the screen buffer | `sb.clear()`, `sb.clear_all()` | [Deleting and clearing](#deleting-and-clearing) |
-| Keep a full history file | `log_file="name"` | [Log files](#log-files) |
-| Read the history back (with its location) | `sb.read_log()` | [Log files](#log-files) |
-| Resume the panel after a kernel restart | `log_file=` without `start=True` | [Persistence](#persistence-and-resume) |
-| Start fresh and wipe old files | `start=True` | [Persistence](#persistence-and-resume) |
-| Cap file sizes | `max_main`, `max_wait` | [Limits](#limits-and-long-runs) |
-| Change any setting while running | `sb.update(...)` | [Changing settings](#changing-settings-at-runtime) |
-| Fix wrong center/right alignment | `width=` | [Alignment](#alignment) |
-| Get the panel as a string | `sb.get_text()` | [Reading state](#reading-state) |
-| See raw buffer with indexes | `sb.display_index()` | [Reading state](#reading-state) |
-| Use from several threads | built in | [Threads](#threads) |
+| `wait` | `True` (default): draw only when you call `display()`. `False`: redraw on every change | [Redraw modes](#redraw-modes) |
+| `log_file` | Name of the log set (creates `screen_buffer_logs/<name>.txt` and companions). `None` = nothing written to disk | [Log files](#log-files) |
+| `start` | `True` wipes existing files for that name; `False` restores the saved panel | [Persistence](#persistence-and-resume) |
+| `max_display` | Draw only the newest N lines | [Display window](#display-window) |
+| `max_main`, `max_wait` | Line caps for the history and saved-buffer files | [Limits](#limits-and-long-runs) |
+| `header`, `footer` | Fixed text above / below the lines | [Header and footer](#header-and-footer) |
+| `header_alignment`, `footer_alignment` | Alignment for those two | [Alignment](#alignment) |
+| `show_header`, `show_footer` | Hide or show them (default: shown when text is set) | [Header and footer](#header-and-footer) |
+| `silent_display`, `only_display` | Hide some lines / show only some lines | [Filtering](#filtering) |
+| `auto_clean_silent_only_display`, `shift_max_display`, `auto_clean_edges` | Fine-tune filtering and spacing | [Filtering](#filtering) |
+| `width` | Panel width in columns for `center` / `right`; `None` = detect | [Alignment](#alignment) |
+
+Typical setups:
+
+```python
+sb = ScreenBuffer()                                              # simplest: collect lines, then sb.display()
+sb = ScreenBuffer(wait=False, max_display=10)                    # live panel, newest 10 lines
+sb = ScreenBuffer(max_display=10, log_file="run1", max_wait=1000, start=True)   # long job with a log
+```
 
 ---
 
-## Core concepts
+## Usage
 
-- **Buffer**: the list of all lines you have `put()`. Each line has an index (0, 1, 2, ...).
-- **View**: what is drawn. It is the header, then the visible lines (after the window and any filter), then the footer.
-- **History log**: a timestamped file of every `put()`. Append-only record of the run.
-- **Wait file**: a saved copy of the *current* buffer, so the panel can be restored.
+### Display window
 
-The screen is redrawn with Jupyter's own `clear_output(wait=True)`: the old frame stays until the new text is ready, then they are swapped. The new text is printed as one string, with your exact spacing.
+```python
+sb = ScreenBuffer(wait=False, max_display=10)
+```
 
----
+Only the newest 10 lines are drawn; all lines stay in the buffer and the log. Drawing cost depends on `max_display`, not on how many lines exist (8 lines out of 100,000 draws in under a millisecond).
 
-## Usage
+When the buffer is exactly as long as `max_display`, the window shows the whole thing. That is how a slot body keeps every slot visible (see [Header, body, footer](#header-body-footer)).
+
+### Header and footer
+
+```python
+sb = ScreenBuffer(wait=False, header="Job: nightly_etl", footer="status: running",
+                  header_alignment="center")
+
+sb.update(header="Job: nightly_etl, 42%")       # change in a loop
+sb.update(footer="!! source unreachable !!")
+sb.update(show_footer=False)                     # hide it (the text is kept)
+sb.update(show_footer=True)                      # bring it back
+```
+
+Setting a non-empty header/footer turns it on. Header and footer are saved to files when `log_file` is set. `set_header(text, save_to_file=False)` / `set_footer(...)` keep one in memory only.
 
 ### Alignment
 
@@ -243,27 +341,14 @@ Alignment follows its line: it is saved and restored with the buffer, and re-key
 
 **Width:** by default the terminal width is detected. Jupyter front ends sometimes report the wrong width, which skews `center`/`right`. Set `width=70` (or whatever suits your output area) to fix it.
 
-### Display window
-
-```python
-sb = ScreenBuffer(wait=False, max_display=10)
-```
-
-Only the newest 10 lines are drawn; all lines stay in the buffer and the log. Drawing cost depends on `max_display`, not on how many lines exist (8 lines out of 100,000 draws in under a millisecond).
-
-### Header and footer
-
-```python
-sb = ScreenBuffer(wait=False, header="Job: nightly_etl", footer="status: running",
-                  header_alignment="center")
+### Redraw modes
 
-sb.update(header="Job: nightly_etl | 42%")       # change in a loop
-sb.update(footer="!! source unreachable !!")
-sb.update(show_footer=False)                     # hide it (the text is kept)
-sb.update(show_footer=True)                      # bring it back
-```
+| Mode | Behaviour |
+|---|---|
+| `wait=False` | Live. Every change redraws (skipped if nothing on screen changed). The panel draws once on creation. |
+| `wait=True` (default) | Quiet. Changes are stored but nothing is drawn until you call `sb.display()`. Good for loading lots of lines first. |
 
-Setting a non-empty header/footer turns it on. Header and footer are saved to files when `log_file` is set. `set_header(text, save_to_file=False)` / `set_footer(...)` keep one in memory only.
+`sb.display()` always draws, even if nothing changed. `sb.flush()` clears the Jupyter output immediately.
 
 ### Smooth updates
 
@@ -286,15 +371,6 @@ Other things that keep it smooth, all automatic:
 
 **Fast loops:** if a loop calls `put()` hundreds or thousands of times per second, Jupyter itself can be flooded (its output channel is rate-limited). Call `sb.display()` once per chunk of ~50 items instead of on every item, or add a short sleep.
 
-### Redraw modes
-
-| Mode | Behaviour |
-|---|---|
-| `wait=False` | Live. Every change redraws (skipped if nothing on screen changed). The panel draws once on creation. |
-| `wait=True` (default) | Quiet. Changes are stored but nothing is drawn until you call `sb.display()`. Good for loading lots of lines first. |
-
-`sb.display()` always draws, even if nothing changed. `sb.flush()` clears the Jupyter output immediately.
-
 ### Filtering
 
 Hide or isolate lines **on screen only**. They stay in the buffer and the log. Indexes refer to the full buffer.
@@ -331,6 +407,33 @@ sb.clear_all()                                 # empty the buffer AND remove hea
 
 `contains` is case-insensitive. With `exact=True` (default) it matches a whole word; with `exact=False`, any substring. Alignments move with their lines when others are deleted. Deleting does **not** remove entries from the history log.
 
+With slots you rarely need `delete`: rewrite the slot instead, and the layout never shifts.
+
+### Reading state
+
+```python
+sb.get_text()          # the current panel as one string
+sb.display_index()     # prints every buffer line with its index (debugging)
+sb.buffer              # the raw list of lines
+```
+
+`display_index()` is handy while designing slots: it shows which index holds which line.
+
+### Changing settings at runtime
+
+```python
+sb.update(max_display=20, width=90, wait=False)
+sb.update(log_file="second_phase")      # switch to a different log set
+```
+
+Settable: `wait`, `max_main`, `max_wait`, `max_display`, `shift_max_display`, `auto_clean_edges`, `auto_clean_silent_only_display`, `header`, `footer`, `header_alignment`, `footer_alignment`, `show_header`, `show_footer`, `silent_display`, `only_display`, `width`, `log_file`.
+
+`update()` checks everything first: if any value is invalid it raises and changes **nothing**. Unknown names raise `ValueError`.
+
+### Threads
+
+`put()`, `update()`, `delete()` and drawing are thread-safe. Disk writes keep buffer order even when several threads write at once.
+
 ### Log files
 
 ```python
@@ -390,30 +493,44 @@ Log file: /home/you/project/screen_buffer_logs/scrape_run.txt
 
 `max_wait` cannot be smaller than `max_display`. **Set `max_wait` (500–1000 is typical) on long runs**; it keeps the saved copy small and makes appends cheap.
 
-These cap files, **not memory**. The in-memory buffer keeps every line (roughly 100 MB per million short lines).
-
-### Changing settings at runtime
-
-```python
-sb.update(max_display=20, width=90, wait=False)
-sb.update(log_file="second_phase")      # switch to a different log set
-```
-
-Settable: `wait`, `max_main`, `max_wait`, `max_display`, `shift_max_display`, `auto_clean_edges`, `auto_clean_silent_only_display`, `header`, `footer`, `header_alignment`, `footer_alignment`, `show_header`, `show_footer`, `silent_display`, `only_display`, `width`, `log_file`.
-
-`update()` checks everything first: if any value is invalid it raises and changes **nothing**. Unknown names raise `ValueError`.
+These cap files, **not memory**. The in-memory buffer keeps every line (roughly 100 MB per million short lines). A slot body has a fixed number of lines, so its memory never grows.
 
-### Reading state
+---
 
-```python
-sb.get_text()          # the current panel as one string
-sb.display_index()     # prints every buffer line with its index (debugging)
-sb.buffer              # the raw list of lines
-```
+## Feature index
 
-### Threads
+Find what you need:
 
-`put()`, `update()`, `delete()` and drawing are thread-safe. Disk writes keep buffer order even when several threads write at once.
+| I want to... | Use | Section |
+|---|---|---|
+| Keep fixed slots in the body | `put(..., index=n)` + `max_display` = slot count | [Header, body, footer](#header-body-footer) |
+| Keep something always visible | `header=` / `footer=`, changed with `sb.update(...)` | [Header, body, footer](#header-body-footer) |
+| Create a buffer, see every option | `ScreenBuffer(...)` | [Create a buffer](#create-a-buffer) |
+| Add a line | `sb.put("text")` | [put()](#put-the-core-call) |
+| Replace / update an existing line | `sb.put("new", index=3)` | [put()](#put-the-core-call) |
+| Mark a line OK / warning / error in the log | `sb.put("x", state=0/1/2)` | [put()](#put-the-core-call) |
+| Center, right-align or indent a line | `put(..., alignment=...)` | [Alignment](#alignment) |
+| Show only the newest N lines | `max_display=N` | [Display window](#display-window) |
+| Have a fixed header / footer | `header=`, `footer=` | [Header and footer](#header-and-footer) |
+| Change header/footer in a loop | `sb.update(header=...)` | [Header and footer](#header-and-footer) |
+| Hide / show header or footer | `show_header`, `show_footer` | [Header and footer](#header-and-footer) |
+| Draw once per loop step (no flicker) | `wait=True` + `sb.display()` | [Smooth updates](#smooth-updates) |
+| Control when the screen redraws | `wait=True/False`, `sb.display()` | [Redraw modes](#redraw-modes) |
+| Hide some lines on screen, keep them stored | `silent_display=` | [Filtering](#filtering) |
+| Show only some lines on screen | `only_display=` | [Filtering](#filtering) |
+| Remove blank gaps left by filtering | `auto_clean_silent_only_display=True` | [Filtering](#filtering) |
+| Delete lines | `sb.delete(...)` | [Deleting and clearing](#deleting-and-clearing) |
+| Wipe the screen buffer | `sb.clear()`, `sb.clear_all()` | [Deleting and clearing](#deleting-and-clearing) |
+| Keep a full history file | `log_file="name"` | [Log files](#log-files) |
+| Read the history back (with its location) | `sb.read_log()` | [Log files](#log-files) |
+| Resume the panel after a kernel restart | `log_file=` without `start=True` | [Persistence](#persistence-and-resume) |
+| Start fresh and wipe old files | `start=True` | [Persistence](#persistence-and-resume) |
+| Cap file sizes | `max_main`, `max_wait` | [Limits](#limits-and-long-runs) |
+| Change any setting while running | `sb.update(...)` | [Changing settings](#changing-settings-at-runtime) |
+| Fix wrong center/right alignment | `width=` | [Alignment](#alignment) |
+| Get the panel as a string | `sb.get_text()` | [Reading state](#reading-state) |
+| See raw buffer with indexes | `sb.display_index()` | [Reading state](#reading-state) |
+| Use from several threads | built in | [Threads](#threads) |
 
 ---
 
@@ -421,7 +538,7 @@ sb.buffer              # the raw list of lines
 
 | Method | Purpose |
 |---|---|
-| `put(text, state=0, index=None, fill_value=None, alignment=None)` | Add or replace a line |
+| `put(text, state=0, index=None, fill_value=None, alignment=None)` | Add or replace a line (also the slot move) |
 | `update(**settings)` | Change any setting (validated first) |
 | `display()` | Draw now |
 | `flush()` | Clear the Jupyter output now |
@@ -437,6 +554,34 @@ sb.buffer              # the raw list of lines
 
 ---
 
+## Example: slots
+
+The same scraper with a slot body: three body slots, a header and a footer.
+
+```python
+import time, random
+from screenbuffer import ScreenBuffer
+
+sb = ScreenBuffer(max_display=3, width=70,
+                  header="SCRAPER", header_alignment="center",
+                  footer="0s elapsed", footer_alignment="center")
+sb.put("", index=2)                                   # builds body slots 0, 1 and 2
+
+for t in range(1, 121):
+    sb.put(f"page {t}: +{random.randint(3, 9)} items", index=0)   # current page
+    if t % 10 == 0:
+        sb.put(f"checkpoint at {t}s", index=1)                    # last checkpoint
+    if t % 40 == 0:
+        sb.put(f"retry at {t}s", index=2, alignment=4)            # last retry
+    sb.update(footer=f"{t}s elapsed")
+    sb.display()                                      # one redraw per step
+    time.sleep(0.5)
+```
+
+Nothing scrolls. The header and footer stay put, and each slot keeps its latest value.
+
+---
+
 ## Example: network scraper with an error banner
 
 ```python
@@ -444,18 +589,18 @@ import time, random
 from screenbuffer import ScreenBuffer
 
 sb = ScreenBuffer(max_display=8, width=70,
-                  header="SCRAPER | ONLINE", header_alignment="center",
+                  header="SCRAPER ONLINE", header_alignment="center",
                   footer_alignment="center",
                   log_file="scraper", max_wait=500, start=True)
 
 for t in range(120):
     online = not (40 <= t < 70)
     if online:
-        sb.update(header=f"SCRAPER | ONLINE | {t}s", show_footer=False)
+        sb.update(header=f"SCRAPER ONLINE, {t}s", show_footer=False)
         sb.put(f"[{t}s] page {t//2}: +{random.randint(3, 9)} items")
     else:
-        sb.update(header=f"SCRAPER | OFFLINE | {t}s",
-                  footer="!! NETWORK ERROR - retrying !!")
+        sb.update(header=f"SCRAPER OFFLINE, {t}s",
+                  footer="!! NETWORK ERROR, retrying !!")
         if t % 5 == 0:
             sb.put(f"[{t}s] retrying...", state=1, alignment=4)
     sb.display()                       # one redraw per step
@@ -468,22 +613,10 @@ The error banner appears at the bottom during the outage and disappears when the
 
 ---
 
-## Performance (measured in a sandbox)
-
-| Case | Before tuning | Now |
-|---|---|---|
-| `put()` with 20k lines in the buffer (no log / log / log + `max_main`) | 2.1 / 10.7 / 16.4 ms | 0.005 / 0.035 / 0.11 ms |
-| Draw 8 lines out of 100k | 30.5 ms | 0.72 ms |
-| Frame wait with a 20 ms disk delay | 202 ms | 0.1 ms |
-| Old frame cleared → new text shown | 100–200 ms | ~0.5 ms |
-| Redraws in a 300-step demo (one draw per step) | 241 | 81 |
-
-These come from a Linux sandbox with a simulated Jupyter kernel. Real browser rendering was not measurable there; if you see flicker, see Troubleshooting.
-
 ## Known limits
 
 - **Jupyter only.** Terminals and plain scripts are not supported (drawing is a no-op without IPython).
-- **Replacing or deleting an old line rewrites the saved-buffer file.** Appending is cheap; edits cost O(lines in that file), which `max_wait` keeps small.
+- **Replacing or deleting an old line rewrites the saved-buffer file.** Appending is cheap; edits cost O(lines in that file), which `max_wait` keeps small. A slot body is small by design, so this stays cheap.
 - **`max_main` trimming** rewrites the history file once it goes over the cap.
 - **Memory is not capped** (see Limits).
 - **Queued writes** can be lost if the kernel is killed abruptly. Call `sb.read_log()` (it waits for writes) or let the cell finish before shutting down.
@@ -496,6 +629,8 @@ These come from a Linux sandbox with a simulated Jupyter kernel. Real browser re
 | Symptom | Likely cause / fix |
 |---|---|
 | Nothing appears | `wait=True` (default): call `sb.display()`, or create with `wait=False` |
+| A slot scrolls out of view | The buffer is longer than `max_display`. Make the window equal the slot count, or stop appending and rewrite slots by index |
+| Blank line above the first body line | `auto_clean_edges=True` adds one. Set it to `False` and add your own blank lines |
 | Flicker in a fast loop | Use `wait=True` and call `sb.display()` once per step (or per chunk of items); add a tiny sleep |
 | Header and footer change on separate frames | Use `wait=True`, make both updates, then call `sb.display()` once |
 | `center` / `right` look off | Set `width=` to your output area's real width |