nextpytk 0.3.0__tar.gz → 0.4.1__tar.gz

nextpytk-0.4.1/PKG-INFO

@@ -0,0 +1,412 @@
+Metadata-Version: 2.4
+Name: nextpytk
+Version: 0.4.1
+Summary: Accessible, declarative Tkinter applications from ordinary Python functions.
+Project-URL: Homepage, https://github.com/nishimotz/nextpytk
+Project-URL: Repository, https://github.com/nishimotz/nextpytk
+Project-URL: Issues, https://github.com/nishimotz/nextpytk/issues
+Project-URL: Changelog, https://github.com/nishimotz/nextpytk/blob/main/ROADMAP.md
+Author: Takuya Nishimoto
+License: MIT
+License-File: LICENSE
+Keywords: accessibility,declarative-ui,gui,tkinter,ttk
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# nextpytk
+
+Accessible, declarative Tkinter applications from ordinary Python functions.
+
+Register widgets as plain Python functions, declare layout separately, and
+keep roles/descriptions in one place. The decorator style is Flask-inspired;
+`schema()` exports the same structure for agents and tools.
+Uses ttk widgets where available.
+
+---
+
+## Quick Start
+
+```python
+from nextpytk import TkApp, Layout
+
+app = TkApp(title="Hello")
+
+@app.status("msg")
+def msg():
+    return "Hello, world!"
+
+@app.button("greet", label="Greet")
+def on_greet(values):
+    return {"msg": "Button clicked!"}
+
+app.run(layout=Layout().section("msg").section("greet"))
+```
+
+**Three layout styles — pick the one that fits:**
+
+```python
+# 1) Simple list (easiest)
+app.run(layout=["msg", "greet"])
+
+# 2) Fluent DSL
+app.run(layout=Layout().section("msg").section("greet"))
+
+# 3) with-block (context manager)
+with app.layout() as b:
+    b.section("msg")
+    b.section("greet")
+app.run(layout=b.build())
+```
+
+---
+
+## Design System
+
+nextpytk ships with typed constants and design tokens. Prefer them over raw tkinter strings and magic numbers so every app stays consistent and IDE completion works out of the box.
+
+### Typed Constants
+
+```python
+from nextpytk.types import Side, Fill, Sticky, State, Orient
+
+Layout().section("msg", side=Side.LEFT, fill=Fill.X)
+```
+
+| Type | Namespace | Example |
+|------|-----------|---------|
+| `Side` | `Side.TOP/BOTTOM/LEFT/RIGHT` | pack side |
+| `Fill` | `Fill.X/Y/BOTH/NONE` | pack fill |
+| `Sticky` | `Sticky.NSEW/EW/NS/TOP/BOTTOM/LEFT/RIGHT` | grid sticky |
+| `State` | `State.NORMAL/DISABLED/ACTIVE` | widget state |
+| `Orient` | `Orient.HORIZONTAL/VERTICAL` | scale / paned orientation |
+| `Relief` | `Relief.FLAT/RAISED/SUNKEN/...` | border style |
+| `Justify` | `Justify.LEFT/RIGHT/CENTER` | text alignment |
+| `SelectMode` | `SelectMode.SINGLE/BROWSE/MULTIPLE/EXTENDED` | listbox mode |
+
+Each type has a matching `*Like` literal alias (e.g. `FillLike`), so raw strings still work when needed.
+
+### Spacing tokens
+
+```python
+from nextpytk.tokens import SPACE
+
+SPACE[1]  # 4px  — small padding inside a widget
+SPACE[2]  # 8px  — adjacent widgets
+SPACE[3]  # 12px — section inner gaps
+SPACE[4]  # 16px — section margins
+SPACE[6]  # 24px — large blocks
+SPACE[8]  # 32px — page-level gaps
+```
+
+The scale is based on a 4px unit and only common steps are provided. Use `SPACE[n]` for every `padx`/`pady` value and for widget-level `padding` values where practical.
+
+### Themes
+
+`TkApp` accepts a `theme` parameter:
+
+| Value | Meaning |
+|-------|---------|
+| `"kizashi"` (default) | Apply the built-in Kizashi design system |
+| `"none"` | Do not touch ttk styles; use the platform default theme |
+| any built-in name (e.g. `"clam"`, `"vista"`, `"aqua"`) | Switch to that ttk theme without Kizashi overrides |
+
+```python
+# Use the platform default ttk theme
+app = TkApp(title="Native", theme="none")
+
+# Use any installed ttk theme
+app = TkApp(title="Clam", theme="clam")
+```
+
+See `examples/header_demo.py` for `Layout.header()` / `.status()` chrome and `nextpytk.theme.apply_theme()` usage.
+
+---
+
+## Multiview (Multi-tab)
+
+```python
+from nextpytk import TkApp, Layout
+
+app = TkApp(title="Multi-tab App")
+
+@app.status("header")
+def header(): return "Common header"
+
+with app.view("Tab1", layout=Layout().section("t1_label", "t1_btn")) as v:
+    @v.label("t1_label")
+    def t1_label(): return "Tab 1 content"
+    @v.button("t1_btn", label="Click")
+    def t1_btn(vals): return {}
+
+with app.view("Tab2", layout=Layout().section("t2_label")) as v:
+    @v.label("t2_label")
+    def t2_label(): return "Tab 2 content"
+
+@app.multiview(
+    "main",
+    views=["Tab1", "Tab2"],
+    toplevel_widgets=("header",),
+    initial_state={"tab": "Tab1"},
+    on_tab_change=lambda tab: {"tab": tab},
+)
+def main_multiview(): pass
+
+app.run(multiview="main")
+```
+
+View layouts also accept lists or with-block builders. For example,
+`view_layouts` values may be simple widget-name lists:
+
+```python
+view_layouts = {
+    "Home": ["title", "start"],
+    "Settings": ["timer", "status"],
+}
+```
+
+---
+
+## Layout DSL
+
+### Simple list
+
+```python
+app.run(layout=["title", "timer", "start", "status"])
+```
+
+Each name gets its own pack-based section. Extra kwargs forwarded to `section()`:
+
+```python
+Layout.from_list(["a", "b"], fill="both", expand=True)
+```
+
+### Fluent DSL
+
+**Pack sections:**
+
+```python
+Layout().section("msg").section("phase", "count").section("start", "pause")
+```
+
+**Grid builder:**
+
+```python
+from nextpytk.types import Sticky
+
+layout = (
+    Layout()
+    .grid()
+    .span(2).widget("title", sticky=Sticky.W)
+    .next_row()
+    .widget("label", sticky=Sticky.RIGHT).widget("input", sticky=Sticky.LEFT_RIGHT)
+    .next_row()
+    .span(2).widget("ok")
+    .end_grid()
+)
+```
+
+Grid builder methods:
+
+| Method | Description |
+|--------|-------------|
+| `widget(name, *, sticky, padx, pady, colspan, rowspan)` | Place widget at cursor, advance column |
+| `span(n)` | Set colspan for the next `widget()` call |
+| `next_row()` | Move to next row, reset column |
+| `next_col(n)` | Skip n columns |
+| `at(row, col)` | Jump to absolute position |
+| `col_weight(col, w)` | Set a single column weight |
+| `row_weight(row, w)` | Set a single row weight |
+| `col_minsize(col, px)` | Column minimum width |
+| `row_minsize(row, px)` | Row minimum height |
+| `end_grid()` | Return to Layout chain |
+
+Use `col_weight(0, 0).col_weight(1, 1)` to set column 0 → weight 0 and column 1 → weight 1. This is explicit and less error-prone than index-position bulk lists.
+
+### With-block (context manager)
+
+```python
+from nextpytk import LayoutBuilder
+
+# Standalone builder
+builder = LayoutBuilder()
+with builder:
+    builder.section("title")
+    with builder.grid():
+        builder.col_weight(0, 0).col_weight(1, 1)
+        builder.widget("celsius", sticky="ew")
+        builder.widget("fahrenheit", sticky="ew")
+        builder.next_row().span(2).widget("note")
+app.run(layout=builder.build())
+
+# Via app.layout() shortcut
+with app.layout() as b:
+    b.section("title")
+    with b.grid():
+        b.col_weight(0, 0).col_weight(1, 1)
+        b.widget("celsius", sticky="ew")
+app.run(layout=b.build())
+```
+
+`with b.grid(...)` auto-closes — no `end_grid()` needed.
+
+`grid()` options available directly: `padx`, `pady`, `fill`, `expand`, `uniform`.
+
+---
+
+## Widget Reference
+
+| Decorator | Widget | Callback receives | Returns |
+|-----------|--------|-------------------|---------|
+| `@app.label(name, font=..., anchor=..., justify=..., padding=...)` | tk.Label | — | `str` or `dict` |
+| `@app.status(name)` | tk.Label (`role=status` metadata) | — | `str` or `dict` |
+| `@app.message(name, width=..., auto_width=...)` | tk.Label (auto-wrap) | — | `str` or `dict` |
+| `@app.button(name, label=..., font=..., enabled_if=...)` | ttk.Button | entry values `dict` | `dict` |
+| `@app.job(name)` | async callable | entry values `dict` | `dict` |
+| `@app.entry(name, placeholder=..., show=..., font=..., padding=..., width=...)` | ttk.Entry | `str` | `dict` |
+| `@app.checkbutton(name, text=..., font=...)` | ttk.Checkbutton | `bool` | `dict` |
+| `@app.radiobutton(name, text=..., value=..., group=..., font=...)` | ttk.Radiobutton | selected value `str` | `dict` |
+| `@app.combobox(name, values=..., readonly=..., font=...)` | ttk.Combobox | selected value `str` | `dict` |
+| `@app.menubar(name)` | tk.Menu (window menubar) | — | menu item list |
+| `@app.text(name, width=..., height=..., font=...)` | tk.Text | full content `str` | `dict` |
+| `@app.scale(name, from_=..., to=..., orient=...)` | ttk.Scale | value `str` | `dict` |
+| `@app.spinbox(name, from_=..., to=..., values=..., font=...)` | ttk.Spinbox | value `str` | `dict` |
+| `@app.listbox(name, items=..., selectmode=..., font=...)` | tk.Listbox | selected item `str` | `dict` |
+| `@app.canvas(name, width=..., height=...)` | tk.Canvas | — | — |
+
+`@app.status` sets schema / accessible `role="status"` metadata. It is **not** an ARIA live region yet (planned for a later release). Prefer it for operation feedback labels; use `@app.label` for static or high-frequency mirror text.
+
+`app.run(stages=..., tabposition=...)` and `@app.stages` provide state-driven screen switching (one visible stage at a time). Theme helpers (`apply_theme`, `tokens`, layout chrome) ship in the package root — see `examples/header_demo.py`.
+
+Common options:
+- `font`: `(family, size[, weight])` tuple, e.g. `font=("TkDefaultFont", 18, "bold")`
+- `padding`: internal padding; integer or `(x, y)` / `(left, top, right, bottom)` tuple, e.g. `padding=4` or `padding=(4, 2)`
+
+Label options: `font`, `anchor`, `justify`, `padding`, `width`.
+
+Entry options: `placeholder`, `show`, `font`, `padding`, `width`, `state`.
+- `padding` is the declarative way to increase visual height (ttk.Entry does not support `height`).
+
+Button, checkbutton, radiobutton, spinbox, combobox, listbox, text options:
+- `font` is accepted uniformly. Under the hood, ttk widgets use a derived style so the rest of the theme (colors, maps, layout) is inherited.
+
+`@app.message` creates an auto-wrapping label. `width` sets initial pixel width; `auto_width=True` (default) tracks parent container resize.
+
+---
+
+## Typed Constants
+
+```python
+from nextpytk.types import Side, Fill, Sticky, State, Orient
+
+Layout().section("msg", side=Side.LEFT, fill=Fill.X)
+```
+
+Values use `str` literals compatible with tkinter. `SideLike` / `FillLike` etc.
+accept raw strings too.
+
+| Type | Namespace | Example |
+|------|-----------|---------|
+| `Side` | `Side.TOP/BOTTOM/LEFT/RIGHT` | pack side |
+| `Fill` | `Fill.X/Y/BOTH/NONE` | pack fill |
+| `Sticky` | `Sticky.NSEW/LEFT_RIGHT/TOP/BOTTOM/LEFT/RIGHT` | grid sticky |
+| `State` | `State.NORMAL/DISABLED/ACTIVE` | widget state |
+| `Orient` | `Orient.HORIZONTAL/VERTICAL` | scale orientation |
+| `Relief` | `Relief.FLAT/RAISED/SUNKEN/GROOVE/RIDGE/SOLID` | border style |
+| `Justify` | `Justify.LEFT/RIGHT/CENTER` | text alignment |
+| `SelectMode` | `SelectMode.SINGLE/BROWSE/MULTIPLE/EXTENDED` | listbox mode |
+
+---
+
+## Schema Export (Agent/LLM)
+
+```python
+@label("temperature")
+def t(): return "25°C"
+
+app.schema()
+# → {"title": "...", "widgets": [{"name": "temperature", "kind": "label", ...}]}
+```
+
+Output is JSON-compatible and can be used as a foundation for agent tools and LLM function definitions.
+
+---
+
+## Layout debug
+
+After widgets are built, `app.debug_layout()` returns JSON-compatible geometry
+and pack/grid info for every registered widget (useful for clipping, minsize,
+and layout regressions; also handy to hand to an agent).
+
+```python
+app.run(layout=["msg", "go"])  # or build via tests / custom runner
+print(app.debug_layout())
+# → {"title": "...", "sections": [{"widgets": [{"name": "msg", "geometry": ..., ...}, ...]}]}
+```
+
+---
+
+## Async-Native (asyncio + Tkinter)
+
+`app.run_async()` runs the app on an asyncio event loop, cooperatively scheduled
+with the Tk main loop via `root.tk.dooneevent(0)`.
+`app.spawn(coro)` schedules async tasks during GUI runtime.
+`@app.job(name)` registers async callables.
+
+```python
+@app.job("scan")
+async def scan(vals):
+    result = await asyncio.to_thread(some_blocking_call)
+    return {"status": "done"}
+
+app.run_async(layout=Layout().section("status"))
+```
+
+## Examples
+
+```bash
+uv run python examples/grid_temp.py          # temperature converter
+uv run python examples/task_panel.py          # multi-button panel
+uv run python examples/multiscreen.py         # order app with screens
+uv run python examples/widget_gallery.py      # all widget types
+uv run python examples/header_demo.py         # Layout.header / .status chrome
+uv run python examples/combobox_demo.py       # ttk.Combobox
+uv run python examples/menubar_demo.py        # menubar
+uv run python examples/disk_usage_flat_async.py       # ncdu-style viewer (async)
+```
+
+---
+
+## Requirements
+
+- Python 3.13+ (`requires-python`; examples default to 3.14 via `Makefile` `PYTHON=...`)
+- Tkinter support in your Python build
+- No other dependencies
+
+> Note: On some macOS environments, `uv` + `3.14+freethreaded` can fail at Tk startup with `Can't find a usable init.tcl`.
+> You can switch runtimes per command, e.g. `make run PYTHON=3.13`, `make run PYTHON=3.14+freethreaded`, `make run PYTHON=3.15`.
+
+---
+
+## Related Projects
+
+- **`tkinter` (stdlib)**: nextpytk builds on top — adding Decorator / Schema / A11y layers.
+- **`ttk`**: Native look and accessibility; nextpytk prefers ttk widgets where available.
+- **`CustomTkinter`**: Modern look via Canvas rendering. nextpytk takes the opposite approach: use native widgets and embed A11y from the start.
+- **`TkRouter`** (israel-dryer, author of ttkbootstrap): Declarative view routing with URL-style paths, animated transitions, and history stack. Complements nextpytk's `multiview` — routing vs widget composition.
+
+## License
+
+MIT
+
+## Author
+
+Takuya Nishimoto — Shuaruta Inc.

nextpytk-0.3.0/PKG-INFO → nextpytk-0.4.1/README.md

@@ -1,20 +1,11 @@
-Metadata-Version: 2.4
-Name: nextpytk
-Version: 0.3.0
-Summary: Flask-style decorator API for tkinter GUI: schema-driven, A11y-first, agent-compatible.
-Project-URL: Homepage, https://github.com/nishimotz/nextpytk
-Author: Takuya Nishimoto
-License: MIT
-License-File: LICENSE
-Requires-Python: >=3.13
-Description-Content-Type: text/markdown
-
-# nextpytk — Flask-style Decorator API for Tkinter
-
-nextpytk wraps Tkinter in Python decorators, inspired by Flask.
-Widget registration and layout are decoupled via dependency injection.
-All widgets expose a JSON schema for AI/LLM consumption.
-Uses ttk widgets where available (Button, Entry, Checkbutton, Radiobutton, Scale, Spinbox, Notebook).
+# nextpytk
+
+Accessible, declarative Tkinter applications from ordinary Python functions.
+
+Register widgets as plain Python functions, declare layout separately, and
+keep roles/descriptions in one place. The decorator style is Flask-inspired;
+`schema()` exports the same structure for agents and tools.
+Uses ttk widgets where available.
 
 ---
 
@@ -54,6 +45,68 @@ app.run(layout=b.build())
 
 ---
 
+## Design System
+
+nextpytk ships with typed constants and design tokens. Prefer them over raw tkinter strings and magic numbers so every app stays consistent and IDE completion works out of the box.
+
+### Typed Constants
+
+```python
+from nextpytk.types import Side, Fill, Sticky, State, Orient
+
+Layout().section("msg", side=Side.LEFT, fill=Fill.X)
+```
+
+| Type | Namespace | Example |
+|------|-----------|---------|
+| `Side` | `Side.TOP/BOTTOM/LEFT/RIGHT` | pack side |
+| `Fill` | `Fill.X/Y/BOTH/NONE` | pack fill |
+| `Sticky` | `Sticky.NSEW/EW/NS/TOP/BOTTOM/LEFT/RIGHT` | grid sticky |
+| `State` | `State.NORMAL/DISABLED/ACTIVE` | widget state |
+| `Orient` | `Orient.HORIZONTAL/VERTICAL` | scale / paned orientation |
+| `Relief` | `Relief.FLAT/RAISED/SUNKEN/...` | border style |
+| `Justify` | `Justify.LEFT/RIGHT/CENTER` | text alignment |
+| `SelectMode` | `SelectMode.SINGLE/BROWSE/MULTIPLE/EXTENDED` | listbox mode |
+
+Each type has a matching `*Like` literal alias (e.g. `FillLike`), so raw strings still work when needed.
+
+### Spacing tokens
+
+```python
+from nextpytk.tokens import SPACE
+
+SPACE[1]  # 4px  — small padding inside a widget
+SPACE[2]  # 8px  — adjacent widgets
+SPACE[3]  # 12px — section inner gaps
+SPACE[4]  # 16px — section margins
+SPACE[6]  # 24px — large blocks
+SPACE[8]  # 32px — page-level gaps
+```
+
+The scale is based on a 4px unit and only common steps are provided. Use `SPACE[n]` for every `padx`/`pady` value and for widget-level `padding` values where practical.
+
+### Themes
+
+`TkApp` accepts a `theme` parameter:
+
+| Value | Meaning |
+|-------|---------|
+| `"kizashi"` (default) | Apply the built-in Kizashi design system |
+| `"none"` | Do not touch ttk styles; use the platform default theme |
+| any built-in name (e.g. `"clam"`, `"vista"`, `"aqua"`) | Switch to that ttk theme without Kizashi overrides |
+
+```python
+# Use the platform default ttk theme
+app = TkApp(title="Native", theme="none")
+
+# Use any installed ttk theme
+app = TkApp(title="Clam", theme="clam")
+```
+
+See `examples/header_demo.py` for `Layout.header()` / `.status()` chrome and `nextpytk.theme.apply_theme()` usage.
+
+---
+
 ## Multiview (Multi-tab)
 
 ```python
@@ -86,11 +139,14 @@ def main_multiview(): pass
 app.run(multiview="main")
 ```
 
-View layouts also accept lists or with-block builders:
+View layouts also accept lists or with-block builders. For example,
+`view_layouts` values may be simple widget-name lists:
 
 ```python
-@app.multiview("main", views=["Home", "Settings"],
-    view_layouts={"Home": ["title", "start"], "Settings": ["timer", "status"]})
+view_layouts = {
+    "Home": ["title", "start"],
+    "Settings": ["timer", "status"],
+}
 ```
 
 ---
@@ -122,13 +178,16 @@ Layout().section("msg").section("phase", "count").section("start", "pause")
 ```python
 from nextpytk.types import Sticky
 
-Layout().grid()
-  .span(2).widget("title", sticky=Sticky.W)
-  .next_row()
-  .widget("label", sticky=Sticky.RIGHT).widget("input", sticky=Sticky.LEFT_RIGHT)
-  .next_row()
-  .span(2).widget("ok")
-.end_grid()
+layout = (
+    Layout()
+    .grid()
+    .span(2).widget("title", sticky=Sticky.W)
+    .next_row()
+    .widget("label", sticky=Sticky.RIGHT).widget("input", sticky=Sticky.LEFT_RIGHT)
+    .next_row()
+    .span(2).widget("ok")
+    .end_grid()
+)
 ```
 
 Grid builder methods:
@@ -140,15 +199,13 @@ Grid builder methods:
 | `next_row()` | Move to next row, reset column |
 | `next_col(n)` | Skip n columns |
 | `at(row, col)` | Jump to absolute position |
-| `col_weights(*w)` | Bulk column weights: `col_weights(0, 1, 1)` |
-| `row_weights(*w)` | Bulk row weights |
-| `col_weight(col, w)` | Single column weight |
-| `row_weight(row, w)` | Single row weight |
+| `col_weight(col, w)` | Set a single column weight |
+| `row_weight(row, w)` | Set a single row weight |
 | `col_minsize(col, px)` | Column minimum width |
 | `row_minsize(row, px)` | Row minimum height |
 | `end_grid()` | Return to Layout chain |
 
-`col_weights(0, 1, 1)` means column 0 → weight 0, column 1 → weight 1, column 2 → weight 1.
+Use `col_weight(0, 0).col_weight(1, 1)` to set column 0 → weight 0 and column 1 → weight 1. This is explicit and less error-prone than index-position bulk lists.
 
 ### With-block (context manager)
 
@@ -159,7 +216,8 @@ from nextpytk import LayoutBuilder
 builder = LayoutBuilder()
 with builder:
     builder.section("title")
-    with builder.grid(col_weights=(0, 1)):
+    with builder.grid():
+        builder.col_weight(0, 0).col_weight(1, 1)
         builder.widget("celsius", sticky="ew")
         builder.widget("fahrenheit", sticky="ew")
         builder.next_row().span(2).widget("note")
@@ -168,14 +226,15 @@ app.run(layout=builder.build())
 # Via app.layout() shortcut
 with app.layout() as b:
     b.section("title")
-    with b.grid(col_weights=(0, 1)):
+    with b.grid():
+        b.col_weight(0, 0).col_weight(1, 1)
         b.widget("celsius", sticky="ew")
 app.run(layout=b.build())
 ```
 
 `with b.grid(...)` auto-closes — no `end_grid()` needed.
 
-`grid()` options available directly: `col_weights=(0,1)`, `row_weights=(...)`, `padx`, `pady`, `fill`, `expand`, `uniform`.
+`grid()` options available directly: `padx`, `pady`, `fill`, `expand`, `uniform`.
 
 ---
 
@@ -184,24 +243,36 @@ app.run(layout=b.build())
 | Decorator | Widget | Callback receives | Returns |
 |-----------|--------|-------------------|---------|
 | `@app.label(name, font=..., anchor=..., justify=..., padding=...)` | tk.Label | — | `str` or `dict` |
-| `@app.status(name)` | tk.Label (role=status) | — | `str` or `dict` |
+| `@app.status(name)` | tk.Label (`role=status` metadata) | — | `str` or `dict` |
 | `@app.message(name, width=..., auto_width=...)` | tk.Label (auto-wrap) | — | `str` or `dict` |
-| `@app.button(name, label=..., enabled_if=...)` | ttk.Button | entry values `dict` | `dict` |
+| `@app.button(name, label=..., font=..., enabled_if=...)` | ttk.Button | entry values `dict` | `dict` |
 | `@app.job(name)` | async callable | entry values `dict` | `dict` |
-| `@app.entry(name, placeholder=..., show=...)` | ttk.Entry | `str` | `dict` |
-| `@app.checkbutton(name, text=...)` | ttk.Checkbutton | `bool` | `dict` |
-| `@app.radiobutton(name, text=..., value=..., group=...)` | ttk.Radiobutton | selected value `str` | `dict` |
-| `@app.text(name, width=..., height=...)` | tk.Text | full content `str` | `dict` |
+| `@app.entry(name, placeholder=..., show=..., font=..., padding=..., width=...)` | ttk.Entry | `str` | `dict` |
+| `@app.checkbutton(name, text=..., font=...)` | ttk.Checkbutton | `bool` | `dict` |
+| `@app.radiobutton(name, text=..., value=..., group=..., font=...)` | ttk.Radiobutton | selected value `str` | `dict` |
+| `@app.combobox(name, values=..., readonly=..., font=...)` | ttk.Combobox | selected value `str` | `dict` |
+| `@app.menubar(name)` | tk.Menu (window menubar) | — | menu item list |
+| `@app.text(name, width=..., height=..., font=...)` | tk.Text | full content `str` | `dict` |
 | `@app.scale(name, from_=..., to=..., orient=...)` | ttk.Scale | value `str` | `dict` |
-| `@app.spinbox(name, from_=..., to=..., values=...)` | ttk.Spinbox | value `str` | `dict` |
-| `@app.listbox(name, items=..., selectmode=...)` | tk.Listbox | selected item `str` | `dict` |
+| `@app.spinbox(name, from_=..., to=..., values=..., font=...)` | ttk.Spinbox | value `str` | `dict` |
+| `@app.listbox(name, items=..., selectmode=..., font=...)` | tk.Listbox | selected item `str` | `dict` |
 | `@app.canvas(name, width=..., height=...)` | tk.Canvas | — | — |
 
-Label options:
-- `font`: e.g. `font=("TkDefaultFont", 18, "bold")`
-- `anchor`: e.g. `anchor="e"` (right-aligned)
-- `justify`: multi-line alignment, e.g. `justify="right"`
-- `padding`: e.g. `padding=4` or `padding=(4, 2)`
+`@app.status` sets schema / accessible `role="status"` metadata. It is **not** an ARIA live region yet (planned for a later release). Prefer it for operation feedback labels; use `@app.label` for static or high-frequency mirror text.
+
+`app.run(stages=..., tabposition=...)` and `@app.stages` provide state-driven screen switching (one visible stage at a time). Theme helpers (`apply_theme`, `tokens`, layout chrome) ship in the package root — see `examples/header_demo.py`.
+
+Common options:
+- `font`: `(family, size[, weight])` tuple, e.g. `font=("TkDefaultFont", 18, "bold")`
+- `padding`: internal padding; integer or `(x, y)` / `(left, top, right, bottom)` tuple, e.g. `padding=4` or `padding=(4, 2)`
+
+Label options: `font`, `anchor`, `justify`, `padding`, `width`.
+
+Entry options: `placeholder`, `show`, `font`, `padding`, `width`, `state`.
+- `padding` is the declarative way to increase visual height (ttk.Entry does not support `height`).
+
+Button, checkbutton, radiobutton, spinbox, combobox, listbox, text options:
+- `font` is accepted uniformly. Under the hood, ttk widgets use a derived style so the rest of the theme (colors, maps, layout) is inherited.
 
 `@app.message` creates an auto-wrapping label. `width` sets initial pixel width; `auto_width=True` (default) tracks parent container resize.
 
@@ -241,7 +312,21 @@ app.schema()
 # → {"title": "...", "widgets": [{"name": "temperature", "kind": "label", ...}]}
 ```
 
-Output is JSON-compatible and can serve as LLM Function Calling definitions.
+Output is JSON-compatible and can be used as a foundation for agent tools and LLM function definitions.
+
+---
+
+## Layout debug
+
+After widgets are built, `app.debug_layout()` returns JSON-compatible geometry
+and pack/grid info for every registered widget (useful for clipping, minsize,
+and layout regressions; also handy to hand to an agent).
+
+```python
+app.run(layout=["msg", "go"])  # or build via tests / custom runner
+print(app.debug_layout())
+# → {"title": "...", "sections": [{"widgets": [{"name": "msg", "geometry": ..., ...}, ...]}]}
+```
 
 ---
 
@@ -268,7 +353,9 @@ uv run python examples/grid_temp.py          # temperature converter
 uv run python examples/task_panel.py          # multi-button panel
 uv run python examples/multiscreen.py         # order app with screens
 uv run python examples/widget_gallery.py      # all widget types
-uv run python examples/disk_usage_flat_viewer.py      # ncdu-style viewer (sync)
+uv run python examples/header_demo.py         # Layout.header / .status chrome
+uv run python examples/combobox_demo.py       # ttk.Combobox
+uv run python examples/menubar_demo.py        # menubar
 uv run python examples/disk_usage_flat_async.py       # ncdu-style viewer (async)
 ```
 
@@ -276,7 +363,7 @@ uv run python examples/disk_usage_flat_async.py       # ncdu-style viewer (async
 
 ## Requirements
 
-- Python 3.14 by default (`PYTHON=...` override supported)
+- Python 3.13+ (`requires-python`; examples default to 3.14 via `Makefile` `PYTHON=...`)
 - Tkinter support in your Python build
 - No other dependencies