ricekit 0.2.0__tar.gz

ricekit-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gheat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ricekit-0.2.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: ricekit
+Version: 0.2.0
+Summary: A developer's TUI suite for Textual — themes, widgets, modals, icons, and the design system behind ltui, jtui, and sctui
+Author: Gheat
+License: MIT
+Project-URL: Homepage, https://github.com/Gheat1/ricekit
+Project-URL: Repository, https://github.com/Gheat1/ricekit
+Project-URL: Issues, https://github.com/Gheat1/ricekit/issues
+Keywords: tui,textual,terminal,design-system,widgets,themes
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Terminals
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: textual>=1.0
+Dynamic: license-file
+
+<div align="center">
+
+# 🍚 ricekit
+
+**A developer's TUI suite for [Textual](https://github.com/Textualize/textual).**
+
+The themes, widgets, modals, icons, and design rules extracted from building
+[ltui](https://github.com/runpantheon/ltui) — and now powering its whole family
+(jtui, sctui, same repo) —
+everything a fast, clean, rice-friendly terminal app needs, minus the app.
+
+<img src="assets/gallery.png" alt="ricekit gallery" width="100%">
+
+</div>
+
+---
+
+## what's in the box
+
+| module | contents |
+| --- | --- |
+| `ricekit.themes` | five themes — `mocha`, OLED-black `void`, monochrome `onyx`, **`clear`** (transparent: your terminal's blur shows through), **`system`** (your terminal's own ANSI palette) — all sharing one `$kit-*` CSS variable contract, with the scrollbar/selection fixes baked in |
+| `ricekit.palette` | swappable chrome palette (`palette.text`, `.dim`, `.blue`, …) that flips to terminal ANSI colors under the `system` theme |
+| `ricekit.app` | `KitApp` — registers the themes, flips `ansi_color` for transparent themes, injects CSS variables, replaces the palette's theme command with a live-preview picker |
+| `ricekit.widgets` | `NavList` (vim keys, quiet cursor), `Splitter` (drag-to-resize with persistence hook, double-click reset), `KitScroll`, `pop_in` (the one sanctioned animation) |
+| `ricekit.modals` | `PickerModal` (generic chooser), `ThemeModal` (restyles the app live as you scroll), `HelpModal` (keybinding cheatsheet from plain data) |
+| `ricekit.icons` | curated nerd-font icons as `\uXXXX` escapes + unicode state glyphs (◌ ○ ◐ ◑ ● ⊘) + mini bar gauges |
+| `ricekit.fx` | text effects — the letter wave (`Wave` + `wave_markup`: **G**heat → g**H**eat → …) and braille spinner frames, driven by one cheap shared ticker |
+| `ricekit.storage` | `AppDirs` — XDG state/cache/config with merge-on-save state and chmod-600 secrets |
+| [`DESIGN.md`](DESIGN.md) | the philosophy: cache-first speed, shape language, color roles, motion rules — and the appendix of Textual sharp edges that each cost a day to find |
+
+## see it
+
+```sh
+uv tool install git+https://github.com/Gheat1/ricekit
+ricekit-gallery
+```
+
+The gallery demos the palette, icons, glyphs, widgets, and modals — cycle
+themes with `t`, live-preview every Textual theme with `ctrl+p`, drag the
+divider, press `?`.
+
+## use it
+
+```sh
+uv add git+https://github.com/Gheat1/ricekit   # or pip install git+…
+```
+
+```python
+from textual.binding import Binding
+from textual.widgets import Footer
+
+from ricekit import KitApp, icons, palette
+from ricekit.storage import AppDirs
+from ricekit.widgets import NavList
+
+DIRS = AppDirs("myapp")
+
+class MyApp(KitApp):
+    BINDINGS = [Binding("t", "cycle_kit_theme", "theme")]
+    CSS = """
+    NavList { border: round $kit-border; }
+    NavList:focus { border: round $kit-border-focus; }
+    """
+
+    def compose(self):
+        yield NavList(id="items")
+        yield Footer()
+
+    def on_mount(self):
+        self.init_kit(theme=DIRS.load_state().get("theme"))
+
+    def on_kit_theme_changed(self):
+        if not self.kit_theme_previewing:
+            DIRS.save_state({"theme": self.theme})
+```
+
+That's a themed, transparent-capable, live-previewing app in ~25 lines.
+Read [`DESIGN.md`](DESIGN.md) before building anything serious — especially
+the sharp-edges table.
+
+## the suite
+
+- [**the tracker TUI suite**](https://github.com/runpantheon/ltui) — ltui (Linear), jtui (Jira), sctui (Shortcut); where all of this came from, now backed by Pantheon
+- [**NaviTui**](https://github.com/Gheat1/NaviTui) — an animated terminal player for Navidrome, cover art and all
+- yours next?
+
+## license
+
+[MIT](LICENSE) — made by [@Gheat1](https://github.com/Gheat1)

ricekit-0.2.0/README.md

@@ -0,0 +1,90 @@
+<div align="center">
+
+# 🍚 ricekit
+
+**A developer's TUI suite for [Textual](https://github.com/Textualize/textual).**
+
+The themes, widgets, modals, icons, and design rules extracted from building
+[ltui](https://github.com/runpantheon/ltui) — and now powering its whole family
+(jtui, sctui, same repo) —
+everything a fast, clean, rice-friendly terminal app needs, minus the app.
+
+<img src="assets/gallery.png" alt="ricekit gallery" width="100%">
+
+</div>
+
+---
+
+## what's in the box
+
+| module | contents |
+| --- | --- |
+| `ricekit.themes` | five themes — `mocha`, OLED-black `void`, monochrome `onyx`, **`clear`** (transparent: your terminal's blur shows through), **`system`** (your terminal's own ANSI palette) — all sharing one `$kit-*` CSS variable contract, with the scrollbar/selection fixes baked in |
+| `ricekit.palette` | swappable chrome palette (`palette.text`, `.dim`, `.blue`, …) that flips to terminal ANSI colors under the `system` theme |
+| `ricekit.app` | `KitApp` — registers the themes, flips `ansi_color` for transparent themes, injects CSS variables, replaces the palette's theme command with a live-preview picker |
+| `ricekit.widgets` | `NavList` (vim keys, quiet cursor), `Splitter` (drag-to-resize with persistence hook, double-click reset), `KitScroll`, `pop_in` (the one sanctioned animation) |
+| `ricekit.modals` | `PickerModal` (generic chooser), `ThemeModal` (restyles the app live as you scroll), `HelpModal` (keybinding cheatsheet from plain data) |
+| `ricekit.icons` | curated nerd-font icons as `\uXXXX` escapes + unicode state glyphs (◌ ○ ◐ ◑ ● ⊘) + mini bar gauges |
+| `ricekit.fx` | text effects — the letter wave (`Wave` + `wave_markup`: **G**heat → g**H**eat → …) and braille spinner frames, driven by one cheap shared ticker |
+| `ricekit.storage` | `AppDirs` — XDG state/cache/config with merge-on-save state and chmod-600 secrets |
+| [`DESIGN.md`](DESIGN.md) | the philosophy: cache-first speed, shape language, color roles, motion rules — and the appendix of Textual sharp edges that each cost a day to find |
+
+## see it
+
+```sh
+uv tool install git+https://github.com/Gheat1/ricekit
+ricekit-gallery
+```
+
+The gallery demos the palette, icons, glyphs, widgets, and modals — cycle
+themes with `t`, live-preview every Textual theme with `ctrl+p`, drag the
+divider, press `?`.
+
+## use it
+
+```sh
+uv add git+https://github.com/Gheat1/ricekit   # or pip install git+…
+```
+
+```python
+from textual.binding import Binding
+from textual.widgets import Footer
+
+from ricekit import KitApp, icons, palette
+from ricekit.storage import AppDirs
+from ricekit.widgets import NavList
+
+DIRS = AppDirs("myapp")
+
+class MyApp(KitApp):
+    BINDINGS = [Binding("t", "cycle_kit_theme", "theme")]
+    CSS = """
+    NavList { border: round $kit-border; }
+    NavList:focus { border: round $kit-border-focus; }
+    """
+
+    def compose(self):
+        yield NavList(id="items")
+        yield Footer()
+
+    def on_mount(self):
+        self.init_kit(theme=DIRS.load_state().get("theme"))
+
+    def on_kit_theme_changed(self):
+        if not self.kit_theme_previewing:
+            DIRS.save_state({"theme": self.theme})
+```
+
+That's a themed, transparent-capable, live-previewing app in ~25 lines.
+Read [`DESIGN.md`](DESIGN.md) before building anything serious — especially
+the sharp-edges table.
+
+## the suite
+
+- [**the tracker TUI suite**](https://github.com/runpantheon/ltui) — ltui (Linear), jtui (Jira), sctui (Shortcut); where all of this came from, now backed by Pantheon
+- [**NaviTui**](https://github.com/Gheat1/NaviTui) — an animated terminal player for Navidrome, cover art and all
+- yours next?
+
+## license
+
+[MIT](LICENSE) — made by [@Gheat1](https://github.com/Gheat1)

ricekit-0.2.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ricekit"
+version = "0.2.0"
+description = "A developer's TUI suite for Textual — themes, widgets, modals, icons, and the design system behind ltui, jtui, and sctui"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Gheat" }]
+requires-python = ">=3.11"
+dependencies = ["textual>=1.0"]
+keywords = ["tui", "textual", "terminal", "design-system", "widgets", "themes"]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Terminals",
+    "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+Homepage = "https://github.com/Gheat1/ricekit"
+Repository = "https://github.com/Gheat1/ricekit"
+Issues = "https://github.com/Gheat1/ricekit/issues"
+
+[project.scripts]
+ricekit-gallery = "ricekit.gallery:main"
+
+[tool.setuptools]
+packages = ["ricekit"]

ricekit-0.2.0/ricekit/__init__.py

@@ -0,0 +1,36 @@
+"""ricekit — a developer's TUI suite for Textual.
+
+The themes, widgets, modals, icons, and design rules extracted from
+building ltui (https://github.com/Gheat1/ltui) — and now shared by its
+siblings jtui (Jira) and sctui (Shortcut): everything a fast,
+clean, rice-friendly terminal app needs, minus the app.
+
+    from ricekit import KitApp, palette, icons
+    from ricekit.widgets import NavList, Splitter, KitScroll, pop_in
+    from ricekit.modals import PickerModal, ThemeModal, HelpModal
+    from ricekit.storage import AppDirs
+
+See DESIGN.md for the philosophy and the sharp edges.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"
+
+from ricekit import fx, icons
+from ricekit.app import KitApp
+from ricekit.palette import Palette, palette
+from ricekit.storage import AppDirs
+from ricekit.themes import KIT_THEMES, KIT_THEME_NAMES
+
+__all__ = [
+    "KitApp",
+    "Palette",
+    "palette",
+    "icons",
+    "fx",
+    "AppDirs",
+    "KIT_THEMES",
+    "KIT_THEME_NAMES",
+    "__version__",
+]

ricekit-0.2.0/ricekit/app.py

@@ -0,0 +1,86 @@
+"""KitApp — the base App that wires the whole kit together."""
+
+from __future__ import annotations
+
+from textual.app import App
+from textual.color import Color
+
+from ricekit.modals import ThemeModal
+from ricekit.palette import palette
+from ricekit.themes import KIT_THEMES, KIT_THEME_NAMES
+
+
+class KitApp(App):
+    """App base with the kit's theme machinery.
+
+    Call `self.init_kit(theme=...)` from your `on_mount`. Then:
+
+    - the five kit themes are registered and one is active
+    - `App.ansi_color` flips automatically for ansi-background themes
+      (clear, system, ansi-dark, …) so the terminal background shows
+    - the shared `palette` swaps to ANSI colors under the `system` theme
+    - `action_change_theme` opens the live-preview ThemeModal (this also
+      replaces the command palette's built-in "Change theme" flow)
+    - `action_cycle_kit_theme` cycles the five kit themes (bind it to `t`)
+    - override `on_kit_theme_changed()` to re-render palette-dependent
+      content and persist the choice — check `self.kit_theme_previewing`
+      before persisting
+    """
+
+    kit_theme_previewing: bool = False
+
+    def get_css_variables(self) -> dict[str, str]:
+        # kit-* variables must exist even before our themes register (the
+        # stylesheet is parsed while the default textual theme is active),
+        # and when a non-kit builtin theme is active
+        variables = super().get_css_variables()
+        theme = next((t for t in KIT_THEMES if t.name == self.theme), KIT_THEMES[0])
+        for name, value in theme.variables.items():
+            variables.setdefault(name, value)
+        return variables
+
+    def init_kit(self, theme: str | None = None) -> None:
+        for t in KIT_THEMES:
+            self.register_theme(t)
+        self.theme_changed_signal.subscribe(self, self._kit_theme_changed)
+        if theme and theme in self.available_themes:
+            self.theme = theme
+        else:
+            self.theme = KIT_THEME_NAMES[0]
+        self._kit_apply()
+
+    def _kit_theme_is_ansi(self) -> bool:
+        theme = self.available_themes.get(self.theme)
+        if theme is None or theme.background is None:
+            return False
+        try:
+            return Color.parse(theme.background).ansi is not None
+        except Exception:
+            return False
+
+    def _kit_apply(self) -> None:
+        self.ansi_color = self._kit_theme_is_ansi()
+        palette.set_ansi(self.theme == "system")
+
+    def _kit_theme_changed(self, _theme) -> None:
+        self._kit_apply()
+        self.on_kit_theme_changed()
+
+    def on_kit_theme_changed(self) -> None:
+        """Override me: re-render Rich-text chrome, persist self.theme
+        (skip persisting while `self.kit_theme_previewing` is True)."""
+
+    def action_cycle_kit_theme(self) -> None:
+        idx = (
+            KIT_THEME_NAMES.index(self.theme)
+            if self.theme in KIT_THEME_NAMES
+            else -1
+        )
+        self.theme = KIT_THEME_NAMES[(idx + 1) % len(KIT_THEME_NAMES)]
+
+    def action_change_theme(self) -> None:
+        # overrides App.action_change_theme, so the command palette's
+        # "Change theme" command opens the live-preview picker too
+        if isinstance(self.screen, ThemeModal):
+            return
+        self.push_screen(ThemeModal())

ricekit-0.2.0/ricekit/fx.py

@@ -0,0 +1,53 @@
+"""Text effects: the letter wave and the braille spinner.
+
+One shared ticker at ~8fps (0.12s) drives both; render only while a sweep
+or spin is active — idle frames should cost nothing.
+"""
+
+from __future__ import annotations
+
+from rich.markup import escape
+
+SPINNER_FRAMES = "\u280b\u2819\u2839\u2838\u283c\u2834\u2826\u2827\u2807\u280f"
+
+FX_TICK = 0.12  # seconds per animation frame
+FX_REST_TICKS = 26  # pause between wave sweeps (~3s)
+
+
+def wave_markup(s: str, pos: int, base: str, hi: str) -> str:
+    """One traveling letter, bolded + capitalized: gheatmc -> Gheatmc -> gHeatmc.
+
+    `pos` is the index of the highlighted letter (-1 or out of range = no
+    highlight). Advance pos on a timer; after the sweep, rest FX_REST_TICKS.
+    """
+    out = []
+    for i, ch in enumerate(s):
+        e = escape(ch)
+        if i == pos:
+            out.append(f"[bold {hi}]{e.upper()}[/]")
+        else:
+            out.append(f"[{base}]{e}[/]")
+    return "".join(out)
+
+
+class Wave:
+    """Sweep/rest state machine for wave_markup.
+
+    tick() returns True when a re-render is needed this frame.
+    """
+
+    def __init__(self, length: int, rest_ticks: int = FX_REST_TICKS) -> None:
+        self.length = length
+        self.rest_ticks = rest_ticks
+        self.pos = -1
+        self._rest = 0
+
+    def tick(self) -> bool:
+        if self._rest > 0:
+            self._rest -= 1
+            return False
+        self.pos += 1
+        if self.pos >= self.length:
+            self.pos = -1
+            self._rest = self.rest_ticks
+        return True

ricekit-0.2.0/ricekit/gallery.py

@@ -0,0 +1,203 @@
+"""ricekit-gallery — a live demo of every piece of the kit.
+
+Also serves as the kit's integration test: if the gallery runs, the
+themes, palette, widgets, and modals all compose.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from rich.text import Text
+from textual import on
+from textual.app import ComposeResult
+from textual.binding import Binding
+from textual.containers import Horizontal, Vertical
+from textual.widgets import Footer, OptionList, Static
+from textual.widgets.option_list import Option
+
+from ricekit import __version__, icons
+from ricekit.app import KitApp
+from ricekit.modals import HelpModal, PickerModal
+from ricekit.palette import palette
+from ricekit.storage import AppDirs
+from ricekit.widgets import KitScroll, NavList, Splitter, pop_in
+
+DIRS = AppDirs("ricekit-gallery")
+
+HELP_SECTIONS = [
+    ("navigate", [("j / k / arrows", "move"), ("enter", "show a demo"), ("esc", "close modal")]),
+    ("kit", [("t", "cycle the five kit themes"), ("ctrl+p", "palette → Change theme (live preview)"),
+             ("p", "open a PickerModal"), ("?", "this help")]),
+    ("layout", [("drag the divider", "resize the sidebar"), ("double-click it", "reset")]),
+    ("app", [("q", "quit")]),
+]
+
+DEMOS = ["palette", "icons", "state glyphs", "bars", "widgets", "philosophy"]
+
+
+class Gallery(KitApp):
+    TITLE = "ricekit gallery"
+
+    BINDINGS = [
+        Binding("t", "cycle_kit_theme", "theme"),
+        Binding("p", "picker_demo", "picker"),
+        Binding("question_mark", "help", "help"),
+        Binding("q", "quit", "quit"),
+    ]
+
+    CSS = """
+    #side {
+        width: 26;
+        margin: 0 0 0 1;
+        border: round $kit-border;
+        border-title-color: $kit-border-alt;
+    }
+    #side:focus-within { border: round $kit-border-focus; }
+    #stage {
+        width: 1fr;
+        margin: 0 1 0 0;
+        border: round $kit-border;
+        border-title-color: $kit-border-alt;
+    }
+    #stage-body { height: auto; padding: 1 2; }
+    """
+
+    def compose(self) -> ComposeResult:
+        with Horizontal():
+            with Vertical(id="side"):
+                yield NavList(id="demos")
+            yield Splitter("#side", min_width=18, max_width=40,
+                           on_resized=self._layout_changed, id="split")
+            with Vertical(id="stage"):
+                with KitScroll(id="stage-scroll"):
+                    yield Static(id="stage-body")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        state = DIRS.load_state()
+        self.init_kit(theme=state.get("theme"))
+        side = self.query_one("#side")
+        side.border_title = f" {icons.STAR} ricekit {__version__} "
+        if w := state.get("side_w"):
+            side.styles.width = int(w)
+        self.query_one("#stage").border_title = " gallery "
+        demos = self.query_one("#demos", NavList)
+        demos.add_options([Option(Text(f" {d}"), id=d) for d in DEMOS])
+        demos.highlighted = 0
+        demos.focus()
+        self._show("palette")
+
+    def _layout_changed(self, target: str, width: int | None) -> None:
+        DIRS.save_state({"side_w": width})
+
+    def on_kit_theme_changed(self) -> None:
+        # re-render palette-dependent content; persist unless previewing
+        current = self.query_one("#demos", NavList).highlighted or 0
+        self._show(DEMOS[current])
+        if not self.kit_theme_previewing:
+            DIRS.save_state({"theme": self.theme})
+
+    # ── demo panes ────────────────────────────────────────────────────
+    @on(OptionList.OptionHighlighted, "#demos")
+    def _pick(self, event: OptionList.OptionHighlighted) -> None:
+        if event.option.id:
+            self._show(event.option.id)
+
+    def _show(self, demo: str) -> None:
+        body = Text()
+        if demo == "palette":
+            body.append("the swappable chrome palette\n\n", style=f"bold {palette.text}")
+            for role in ("text", "sub", "dim", "faint", "vfaint", "blue", "lav",
+                         "peach", "green", "red", "mauve", "yellow"):
+                value = getattr(palette, role)
+                body.append("  ██ ", style=value)
+                body.append(f"palette.{role}".ljust(18), style=palette.sub)
+                body.append(f"{value}\n", style=palette.dim)
+            body.append("\nswitch to the system theme (t) and watch these\n"
+                        "become your terminal's own ANSI colors.", style=palette.dim)
+        elif demo == "icons":
+            body.append("nerd-font icons (as \\uXXXX escapes)\n\n", style=f"bold {palette.text}")
+            names = [n for n in dir(icons) if n.isupper() and isinstance(getattr(icons, n), str)
+                     and n not in ("BULLET", "DOT_SEP")]
+            for name in sorted(names):
+                body.append(f"  {getattr(icons, name)}  ", style=palette.blue)
+                body.append(f"icons.{name}\n", style=palette.sub)
+        elif demo == "state glyphs":
+            body.append("workflow-state circles (plain unicode)\n\n", style=f"bold {palette.text}")
+            colors = {"triage": palette.mauve, "backlog": palette.dim,
+                      "unstarted": palette.sub, "started": palette.yellow,
+                      "review": palette.green, "completed": palette.blue,
+                      "canceled": palette.dim}
+            for state, glyph in icons.STATE_GLYPHS.items():
+                body.append(f"  {glyph}  ", style=colors.get(state, palette.sub))
+                body.append(f"{state}\n", style=palette.sub)
+        elif demo == "bars":
+            body.append("mini bar gauges\n\n", style=f"bold {palette.text}")
+            for label, lit in (("urgent", 3), ("high", 3), ("medium", 2), ("low", 1), ("none", 0)):
+                body.append("  ")
+                body.append_text(icons.bars(lit, palette.sub, palette.vfaint))
+                body.append(f"  {label}\n", style=palette.sub)
+        elif demo == "widgets":
+            body.append("what you're looking at\n\n", style=f"bold {palette.text}")
+            for name, desc in (
+                ("NavList", "vim keys, quiet cursor via $kit-cursor"),
+                ("Splitter", "drag the divider left of this pane; double-click resets"),
+                ("KitScroll", "focusable scrolling with j/k"),
+                ("PickerModal", "press p"),
+                ("ThemeModal", "ctrl+p → Change theme — previews as you scroll"),
+                ("HelpModal", "press ?"),
+                ("pop_in", "every modal fades in (~150ms)"),
+            ):
+                body.append(f"  {name.ljust(14)}", style=palette.blue)
+                body.append(f"{desc}\n", style=palette.sub)
+        elif demo == "philosophy":
+            body.append("the short version\n\n", style=f"bold {palette.text}")
+            for line in (
+                "cache first — render instantly, refresh in the background",
+                "rounded borders, titles in the border, one accent at a time",
+                "chrome colors are roles, data colors are data",
+                "keyboard first, everything clickable anyway",
+                "motion is a fade, 150ms, out_cubic — never more",
+                "themes restyle chrome only; clear + system respect the rice",
+            ):
+                body.append(f"  {icons.CHECK} ", style=palette.green)
+                body.append(f"{line}\n", style=palette.sub)
+            body.append("\nfull document: DESIGN.md", style=palette.dim)
+        self.query_one("#stage-body", Static).update(body)
+        self.query_one("#stage").border_subtitle = f" {demo} "
+
+    # ── modal demos ───────────────────────────────────────────────────
+    def action_picker_demo(self) -> None:
+        opts = []
+        for i, (glyph, label) in enumerate([
+            (icons.CHECK_CIRCLE, "ship it"),
+            (icons.CLOCK, "later"),
+            (icons.CROSS_CIRCLE, "never"),
+        ]):
+            row = Text()
+            row.append(f"{glyph} ", style=(palette.green, palette.yellow, palette.red)[i])
+            row.append(label, style=palette.text)
+            opts.append(Option(row, id=label))
+
+        def done(choice: str | None) -> None:
+            if choice:
+                self.notify(f"{icons.CHECK} you picked: {choice}")
+
+        self.push_screen(PickerModal("a PickerModal", opts), done)
+
+    def action_help(self) -> None:
+        if isinstance(self.screen, HelpModal):
+            return
+        self.push_screen(HelpModal(HELP_SECTIONS, title=f"{icons.KEYBOARD}  ricekit gallery"))
+
+
+def main() -> None:
+    if "--version" in sys.argv or "-v" in sys.argv:
+        print(f"ricekit {__version__}")
+        return
+    Gallery().run()
+
+
+if __name__ == "__main__":
+    main()