Moho 0.2.5__tar.gz

moho-0.2.5/.cursor/skills/moho-framework/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: moho-framework
+description: >-
+  Develop Moho Rich Internet Applications using Python, Cython, Tornado,
+  Bootstrap, and .mh declarative UI files. Use when working in moho-framework,
+  creating or editing .mh files, BootstrapApp/WebApp classes, Element widgets,
+  Factory registration, or Moho server-client WebSocket sync.
+---
+
+# Moho Framework
+
+## Framework identity
+
+Moho is an open-source Python framework for building Rich Internet Applications (RIAs). It is inspired by Kivy but targets the web: instead of an OpenGL desktop app, you run a server-client application over HTTP and WebSocket.
+
+- UI language files use `.mh` extension (not Kivy `.kv`)
+- Stack: Python 3.9+, Cython, Tornado (HTTP + WebSocket), Bootstrap 5, vanilla JS (`moho.events`)
+- License: GPLv3
+- Live API docs: https://escape-projects.gitlab.io/moho-framework/
+
+## Architecture
+
+```mermaid
+flowchart TB
+    subgraph server [PythonServer]
+        App[BootstrapApp]
+        MH[show.mh via Builder]
+        Elements[Element tree]
+        WS[WebSocket /ws/moho]
+        App --> MH
+        App --> Elements
+        Elements --> WS
+    end
+    subgraph browser [Browser]
+        JS[moho.js]
+        BS[Bootstrap widgets]
+        JS --> BS
+    end
+    WS <-->|JSON events| JS
+```
+
+Python defines logic and the element tree; `.mh` files define layout and rules; `html_tpl`/`js_tpl` render widgets in the browser. Attribute changes with `sync=True` sync to the client over WebSocket.
+
+### Static files
+
+`/static/...` is served from the app's `data/static` **first**, then falls back to the Moho package `moho/data/static`. You do **not** need to copy `moho.js`, Bootstrap, Plotly helpers, etc. into every app — only keep local overrides or app-specific assets. `moho-admin project` may still scaffold a full static copy for convenience.
+
+## Minimum application pattern
+
+```python
+from moho.core.logger import Logger
+from moho.uix.bootstrap.app import BootstrapApp
+from moho.uix.body import Body
+
+
+class MainBody(Body):
+    pass
+
+
+class ShowcaseApp(BootstrapApp):
+
+    def build(self):
+        return MainBody()
+
+
+if __name__ == "__main__":
+    Logger.setLevel('DEBUG')
+    ShowcaseApp(cookie_secret="__GENERATE_RANDOM_SECRET__").run()  # default port 8888
+```
+
+Reference: `moho/core/app.py`, `examples/showcase/app.py`.
+
+## `.mh` auto-loading
+
+The app class name determines which `.mh` file loads automatically:
+
+- `ShowcaseApp` → `showcase.mh` in the same directory as `app.py`
+- Strip trailing `App`, lowercase the remainder
+- `.mh` rules load during `run()`, **before** `build()` executes
+- Override with `mh_file` or `mh_directory` properties on the app class
+
+## Property vs Attribute
+
+| Type | Examples | Scope | Syncs to browser? |
+|------|----------|-------|-------------------|
+| Property | `StringProperty`, `BooleanProperty`, `NumericProperty` | Backend only | No |
+| Attribute | `ElementAttribute`, `ClassAttribute`, `StyleAttribute` | HTML representation | Yes, when `sync=True` |
+
+Use Moho `Property`/`Attribute` types for widget state — not Python `@property`.
+
+### Local vs client vs synced
+
+| Concept | How to declare | Example |
+|---------|----------------|---------|
+| Local event | `register_event('on_select')` or property `on_<prop>` | Parent dropdown selection |
+| Client event | `EventAttribute` / `register_event('on_click', client=True)` | Browser click → `on_click` |
+| Synced attribute | `ElementAttribute(..., sync=True)` | Push `value` to the DOM |
+
+- Local / property events: `on_<propname>` callbacks and `.mh` `on_<prop>:`
+- Client (browser) events: `on_<event>` handlers (e.g. `on_click`) — also bindable in `.mh` as `on_click:`
+- Push to browser: `element.emit_to_client(event, **kwargs)`
+
+## Widget development checklist
+
+1. **Python class** — subclass `moho.uix.widget.Widget`; declare Kivy-style
+   properties and events only (no Bootstrap `ClassAttribute` / `html_tpl`)
+2. **Backend** — implement presentation in
+   `moho.uix.engines.bootstrap.backends` and add it to `BACKENDS`
+3. **Factory registration** — `Factory.register(...)` in
+   `moho/uix/engines/bootstrap/app.py` (compat: `moho.uix.bootstrap.app`)
+4. **Style rules** — add rules to `moho/data/engines/bootstrap.mh` /
+   `widgets.bootstrap.mh` or app-specific `.mh`
+5. Escape hatch: subclass `BootstrapElement` only for app-local chrome that
+   needs Bootstrap spacing utilities
+
+### Custom widget example (from showcase)
+
+```python
+class CustomButton(Button):
+
+    def __init__(self, **kwargs):
+        super(CustomButton, self).__init__(**kwargs)
+        self._numclicks = 0
+
+    def on_click(self, *args, **kwargs):
+        self.text = "Clicked {0}".format(self._numclicks + 1)
+        self._numclicks += 1
+```
+
+Register in `.mh` via dynamic class or rule targeting the Python class.
+
+## `.mh` quick rules
+
+Every `.mh` file starts with a version header:
+
+```
+#:moho 1.0
+```
+
+| Construct | Syntax |
+|-----------|--------|
+| Rule (applies to class) | `<ClassName>:` |
+| Root widget | `ClassName:` (no angle brackets) |
+| Dynamic class | `<NewWidget@BaseClass>:` |
+| Import | `#:import alias module` |
+| Include | `#:include other.mh` |
+| Variable | `#:set name value` |
+
+Keywords in expressions: `self`, `root`, `app`, `args` (in callbacks).
+
+Indentation must be consistent spaces (no tab/space mixing). Property values must be single-line Python expressions.
+
+See [reference.md](reference.md) for full `.mh` syntax.
+
+## Project layout
+
+Scaffold with `moho-admin project <name> [--type bootstrap|native|w3css]`:
+
+```
+myproject/
+├── app.py
+├── showcase.mh      # auto-loaded if class is ShowcaseApp
+├── __init__.py
+└── data/
+    ├── static/      # CSS, JS
+    └── templates/   # index.html
+```
+
+Showcase reference: `examples/showcase/` (`app.py`, `showcase.mh`, per-screen demos under `data/screens/`).
+
+## Build, test, and run
+
+| Task | Command |
+|------|---------|
+| Compile Cython extensions | `bash build_inplace.sh` |
+| Full install | `python setup.py install` |
+| Quick tests | `bash test.sh` |
+| Widget regression | `python -m unittest discover -s moho/tests/widgets_regression -v` |
+| Full test suite | `python -m unittest discover -v` (from `moho/tests/`) |
+| Run showcase | `cd examples/showcase && python app.py` |
+| Capture showcase screenshots | `.\scripts\capture_showcase_screenshots.ps1` |
+| Docker showcase | `docker run -d -p 8888:8888 escapeapp/moho-examples:master` |
+| WASM package / serve | `.\scripts\wasm\build_all.ps1` then `.\scripts\wasm\serve.ps1` (vendors Pyodide; CI publishes to Pages `/showcase/`) |
+| Build docs | `scripts/linux/compile_docs.sh` |
+
+Visualization façades (`MplFigure`, `PlotlyFigure`, `Svg*`, `X3d*`) are imported from
+`moho.uix.widgets` (modules `widgets.mpl`, `widgets.plotly`, `widgets.svg`,
+`widgets.x3d`). Regression coverage and showcase gallery notes:
+`moho/tests/widgets_regression/README.md`, `doc/showcase_gallery.rst`,
+`doc/_static/showcase_gallery.html`.
+
+Always compile Cython extensions before running or testing.
+
+## Code conventions
+
+- Match existing style in the file being edited
+- Register new widgets in `moho/uix/engines/bootstrap/app.py` via `Factory.register()`
+  (and add a Backend under `moho.uix.engines.bootstrap.backends`)
+- Use `examples/showcase/` for the full widget / Bootstrap / plot demo
+- Prefer `from moho.uix.widgets import ...` for Kivy-familiar names (ScrollView, ScreenManager, Label, …)
+- Prefer `add_widget` / `remove_widget` / `clear_widgets` (Kivy names); do not use the removed `add_element` API
+- Module docstrings in `moho/lang/__init__.py` and `moho/uix/element.py` are the authoritative API references
+
+## Anti-patterns
+
+- Do not use Kivy `.kv` files or `.kv` naming conventions
+- Do not use Python `@property` for Moho widget state
+- Do not expect `.mh` rules to apply before `run()` is called
+- Do not omit `cookie_secret` on `BootstrapApp`
+- Do not mix tabs and spaces in `.mh` files
+- Do not create deeply nested widget trees entirely in Python when `.mh` rules are the idiomatic approach
+- Do not put `remote` in event names; use semantic names (`on_click`) and `client=True`
+- Do not use `emit_to_client` for in-process communication — use `dispatch`
+- Do not re-register a bubbled parent event as `client=True` unless the browser should invoke that parent name directly
+
+## Additional resources
+
+- [BREAKING.md](../../../BREAKING.md) — Moho 0.2 event/attribute rename table
+- [.mh language reference](reference.md) — syntax cheat sheet, file touch map, Kivy migration notes
+- `moho/lang/__init__.py` — complete language specification
+- `moho/uix/element.py` — Element model and property/attribute docs
+- `moho/data/bootstrap.mh` — default Bootstrap widget styling rules
+- `moho/data/static/js/moho.js` — client WebSocket protocol

moho-0.2.5/.cursor/skills/moho-framework/reference.md

@@ -0,0 +1,270 @@
+# Moho Framework Reference
+
+## `.mh` language syntax
+
+### File header
+
+```
+#:moho 1.0
+```
+
+### Directives
+
+| Directive | Syntax | Purpose |
+|-----------|--------|---------|
+| Import | `#:import np numpy` | Bind a Python module to an alias |
+| Include | `#:include buttons.mh` | Load another `.mh` file |
+| Set | `#:set myvar 42` | Define a file-level variable |
+
+### Constructs
+
+**Rule** — applies styling/behavior to all instances of a class (like CSS):
+
+```
+<Button>:
+    btn_style: "primary"
+    icon: "star"
+```
+
+**Root widget** — single root element for the file (no angle brackets):
+
+```
+MainBody:
+    HBoxLayout:
+        Tab:
+            ...
+```
+
+**Dynamic class** — define a new widget inline without a Python declaration:
+
+```
+<DangerButton@Button>:
+    btn_style: "outline-danger"
+    text: "Danger!"
+    icon: "ban"
+```
+
+**Multiple rules sharing definitions** (comma-separated):
+
+```
+<Rule1,Rule2>:
+    shared_prop: value
+```
+
+### Property expressions
+
+Property values are evaluated as single-line Python expressions:
+
+```
+Button:
+    text: 'State is %s' % self.state
+    disabled: self.state != 'normal'
+```
+
+Reserved keywords:
+
+| Keyword | Scope | Meaning |
+|---------|-------|---------|
+| `self` | Anywhere | Current widget instance |
+| `root` | Rules only | Root widget of the rule |
+| `app` | Anywhere | Running app instance |
+| `args` | `on_<action>` callbacks | Arguments passed to the callback |
+
+### IDs
+
+```
+<MyWidget>:
+    Button:
+        id: btn1
+    Button:
+        text: 'Other state: %s' % btn1.state
+```
+
+`id` is a weakref, not the widget itself. Access via `widget.ids["btn1"]` or `widget.ids.btn1` in Python.
+
+### Event callbacks
+
+**Property change** (`on_<propname>`) — multi-line allowed with consistent indentation:
+
+```
+TextInput:
+    on_focus:
+        if args[1]: self.insert_text("Focus")
+        else: self.insert_text("No focus")
+```
+
+**Client events** — browser-originated events such as `on_click` / `on_change`.
+Bind them in Python (`def on_click`) **or** in `.mh`:
+
+```
+Button:
+    on_click: root.do_something()
+```
+
+**Local bubbled events** — composites like `Dropdown` expose `on_select` (local),
+not a second client click name on the parent.
+
+**Synced attributes** — declare with `sync=True` so server changes push to the DOM.
+
+### Class targeting (`cls`)
+
+Target specific widget instances by class attribute:
+
+```
+<Button>:
+    cls: my_special_btn
+    btn_style: "success"
+```
+
+### Indentation rules
+
+- Use spaces only; consistent indentation multiples
+- Property values: single line only
+- `on_<prop>` callbacks: multiple single-line statements allowed; no extra indentation levels
+
+## Layouts (kivy-style)
+
+Moho ships kivy-inspired layout widgets built on CSS flexbox/grid. Children fill
+the available space by default, which fixes alignment and "won't take full
+height" problems.
+
+| Widget | Module | Behavior |
+|--------|--------|----------|
+| `BoxLayout` | `moho.uix.bootstrap.boxlayout` | Flexbox row/column; base class |
+| `HBoxLayout` | `moho.uix.bootstrap.boxlayout` | Horizontal row (`orientation="horizontal"`) |
+| `VBoxLayout` | `moho.uix.bootstrap.boxlayout` | Vertical column (`orientation="vertical"`) |
+| `GridLayout` | `moho.uix.bootstrap.gridlayout` | CSS grid with `cols` / `rows` |
+
+### Size hints
+
+Every element has `size_hint_x` and `size_hint_y` (`NumericProperty`, default
+`1.0`):
+
+- On the layout's **main axis**, the hint maps to `flex-grow`, so children share
+  the space proportionally (e.g. `size_hint_x: 5` next to `size_hint_x: 2`).
+- A hint of `None` makes the child keep its fixed `width`/`height` (set those via
+  CSS or `width`/`height`/`max_height` attributes).
+- On the **cross axis**, a numeric hint stretches the child to fill; `None` keeps
+  its intrinsic size.
+
+`BoxLayout` automatically sets `min-width:0`/`min-height:0` on children so nested
+scroll areas and canvases shrink/fill instead of overflowing.
+
+### BoxLayout properties
+
+| Property | Meaning |
+|----------|---------|
+| `orientation` | `"horizontal"` or `"vertical"` |
+| `spacing` | Gap between children (CSS `gap`), e.g. `spacing: 10` |
+| `align_items` | Cross-axis alignment (default `"stretch"`) |
+| `justify_content` | Main-axis distribution |
+
+### Example
+
+```
+HBoxLayout:
+    spacing: 10
+    Viewer:
+        size_hint_x: 5
+    Figure:
+        size_hint_x: 5
+    Controls:
+        size_hint_x: 2
+
+GridLayout:
+    cols: 3
+    rows: 1
+    spacing: 10
+    Card:
+    Card:
+    Card:
+```
+
+The root `Body` is rendered as a full-height flex column, so a top-level layout
+fills the viewport without manual `height: 100%` chains.
+
+## File touch map
+
+| Task | Files to edit |
+|------|---------------|
+| New Bootstrap widget | `moho/uix/bootstrap/<widget>.py`, register in `moho/uix/bootstrap/app.py`, rules in `moho/data/bootstrap.mh` or app `.mh` |
+| New application | `app.py`, `<name>.mh`, `data/static/`, `data/templates/` |
+| App UI tab/section | App-specific `.mh` file, `#:include` from root `.mh` |
+| Widget styling | `.mh` rules, `StyleAttribute`/`ClassAttribute` on element |
+| Custom HTML rendering | `html_tpl` / `js_tpl` on element class |
+| Client event handling | `on_<event>` in Python and/or `.mh` (`on_click:`) |
+| Push to browser | `emit_to_client(...)` / synced attributes (`sync=True`) |
+| WebSocket protocol | `moho/data/static/js/moho.js` |
+| Default widget styles | `moho/data/bootstrap.mh` |
+| Core app lifecycle | `moho/core/app.py` |
+| Language parser/builder | `moho/lang/builder.py`, `moho/lang/parser.py` |
+
+## Kivy to Moho migration
+
+| Kivy | Moho |
+|------|------|
+| `.kv` files | `.mh` files |
+| `#:kivy` header | `#:moho 0.1.1` header (or project version) |
+| `App` subclass | `BootstrapApp` / `WebApp` subclass |
+| `build()` returns root widget | `build()` returns `Body` subclass |
+| Desktop OpenGL rendering | Server renders HTML; browser displays via WebSocket sync |
+| `on_touch_down` etc. | `on_click`, `on_change`, `on_mousedown` / `on_mouseup`, etc. |
+| Canvas instructions | `html_tpl` / `js_tpl` templates |
+| `kivy.app.App.get_running_app()` | `app` keyword in `.mh`; running app via WebApp instance |
+| `add_widget` / `remove_widget` / `clear_widgets` | Same names on `Element` |
+| `BoxLayout`, `orientation`, `spacing`, `padding` | Same names; `HBoxLayout`/`VBoxLayout` built on CSS flexbox |
+| `size_hint_x` / `size_hint_y` (0..1+, `None`) | Same semantics, mapped to `flex-grow` / fixed size |
+| `x` / `y` / `pos` / `pos_hint` | Same; FloatLayout maps to CSS absolute positioning |
+| `GridLayout` `cols` / `rows` | Same; rendered with CSS grid (`repeat(n, 1fr)`) |
+| `Label`, `TextInput`, `Slider`, `Switch`, `ToggleButton` | `moho.uix.widgets` façades over Bootstrap controls |
+| `ScrollView` (`scroll_x`/`scroll_y`, `do_scroll_*`) | `moho.uix.widgets` (CSS overflow + DOM sync) |
+| `AnchorLayout`, `StackLayout`, `FloatLayout` | `moho.uix.widgets` (CSS flex / absolute) |
+| `ScreenManager`, `ActionBar`, `Popup`, `Carousel`, `Splitter` | `moho.uix.widgets` |
+| `ActionGroup` / `ActionOverflow` / `ActionSeparator` | `moho.uix.widgets.actionbar` |
+| `TabbedPanel` / `TabbedPanelItem` (`text`, `tab_pos`, `switch_to`) | Façade over Bootstrap tabs |
+| `Video` `position` / `volume` / `duration` | Synced via HTML5 media events |
+| `ValuesSpinner` (not `Factory.Spinner`) | Combobox `<select>` values picker |
+| `Popup.content` | `Popup.content_widget` (HTML `content` is reserved) or `Popup(content=…)` |
+| Scatter / EffectWidget / VKeyboard | Not ported (GPU / multitouch) |
+
+Import convenience: `from moho.uix.widgets import Label, ScrollView, ScreenManager, ...`
+
+Moho reuses Kivy's event model, properties, and language parser — but the deployment model and file extension differ.
+
+> Note: the legacy Bootstrap 12-column `size_hint_xs..xxl` properties and the
+> `Row`/`Col` widgets were removed in favor of the kivy-style model above.
+
+## Showcase example structure
+
+`examples/showcase/` is the full Moho demo (Kivy-style ActionBar + ScreenManager,
+Bootstrap chrome, Matplotlib/Plotly, SVG, X3D):
+
+```
+examples/showcase/
+├── app.py                 # ShowcaseApp + CustomMplFigure (LivePlot)
+├── showcase.mh            # shell chrome
+└── data/screens/*.mh      # one demo per screen
+```
+
+Run: `cd examples/showcase && python app.py`
+
+Screens are lazy-loaded with `Builder.load_file`. Plot / Bootstrap feature demos
+(Theme, Components, Navbar, Modal, Sidebar, Toast, Matplotlib, Plotly, LivePlot,
+Cards, SVG, X3D) live alongside the original Kivy-parity widget screens.
+
+## Known repo caveats
+
+- `starterapp/` templates referenced by `moho/admin.py` are not present in tracked `moho/data/` — scaffolding may be incomplete
+- `w3css` project type in `moho-admin` raises `NotImplementedError`
+- Sphinx API docs (`doc/rst/api/`) are generated at build time by `doc/autobuild.py`, not committed
+- Legacy name "ESCAPE" appears in older docs and Docker image tags (`escapeapp/moho-examples`)
+
+## Reporting bugs
+
+Per `doc/contribute.rst`:
+
+1. Set a clear issue title
+2. Provide exact reproduction steps and error output
+3. Attach failing code if applicable
+
+Contact: escape.app.net@gmail.com

moho-0.2.5/.gitattributes

@@ -0,0 +1,22 @@
+# Auto detect text files and perform LF normalization
+* text=auto
+
+# Custom for Visual Studio
+*.cs     diff=csharp
+*.sln    merge=union
+*.csproj merge=union
+*.vbproj merge=union
+*.fsproj merge=union
+*.dbproj merge=union
+
+# Standard to msysgit
+*.doc	 diff=astextplain
+*.DOC	 diff=astextplain
+*.docx diff=astextplain
+*.DOCX diff=astextplain
+*.dot  diff=astextplain
+*.DOT  diff=astextplain
+*.pdf  diff=astextplain
+*.PDF	 diff=astextplain
+*.rtf	 diff=astextplain
+*.RTF	 diff=astextplain

moho-0.2.5/.gitignore

@@ -0,0 +1,97 @@
+.coverage
+.noseids
+*.so
+*.pyd
+*.pyc
+*.pyo
+*.py#
+*~
+*.swp
+*.DS_Store
+*.kpf
+build/*
+doc/build
+doc/autobuild.py-done*
+doc/sources/api-*.rst
+doc/sources/examples/gen__*.rst
+doc/sources/examples/gallery.rst
+doc/sources/examples/index.rst
+examples/*/bin
+examples/*/.buildozer
+moho/*.c
+moho/*.pyd
+moho/core/text/text_layout.c
+moho/core/text/text_layout.pyd
+moho/core/*.c
+moho/core/*.so
+moho/core/*.pyd
+moho/uix/*.c
+moho/uix/*.pyd
+moho/graphics/*.c
+moho/graphics/*.cpp
+moho/graphics/*.pyd
+moho/graphics/cgl_backend/*.c
+moho/graphics/cgl_backend/*.pyd
+moho/include/config.h
+moho/include/config.pxi
+moho/lib/gstplayer/_gstplayer.c
+moho/core/camera/camera_avfoundation.c
+moho/tests/build
+moho/tests/results
+moho/garden
+.last_known_portable_deps_hash
+deps.zip
+iosbuild
+moho/core/image/osxcoreimage.c
+moho/core/window/sdl.c
+python
+python.exe
+.idea
+dist
+htmlcov
+moho/deps/*
+!moho/deps/__init__.py
+moho.deps*
+moho/version.py
+# Generated by setuptools-scm from git tags (see pyproject.toml).
+moho/_version.py
+
+MANIFEST
+
+moho/core/image/img_imageio.c
+moho/core/audio/audio_sdl2.c
+moho/core/text/text_sdlttf.c
+moho/core/window/window_x11.c
+moho/lib/vidcore_lite/bcm.c
+moho/lib/vidcore_lite/bcm.h
+moho/lib/vidcore_lite/egl.c
+moho/core/image/_img_sdl2.c
+moho/core/text/_text_sdl2.c
+moho/core/window/_window_sdl2.c
+
+# PyDev
+.project
+.pydevproject
+.settings/
+
+# Virtualenv
+env2
+env3
+.venv
+
+# Emacs
+.projectile
+
+moho/setupconfig.py
+
+moho/core/clipboard/_clipboard_sdl2.c
+/Moho.egg-info
+
+.cursor
+.python-cache
+.venv-pyodide-build
+.venv-wasm-package
+public/*
+
+# Local-only internet showcase pool deploy kit (not tracked).
+docker/showcase-pool/