# cat-miner-ui

A **Cat Miner** animation UI widget.  
Framework-agnostic HTML/CSS/JS fragments — inject into the body of **NiceGUI**, **Streamlit**, **Flask**, or any web app.

## Install

**Standard install (recommended)** — from PyPI or from a local wheel:

```bash
pip install cat-miner-ui
```

For local development (editable install):

```bash
cd preorder_app_final
pip install -e .
```

## Demo (see it in action)

Importing alone does **not** show anything: `from cat_miner_ui import render` only loads the function.  
`render()` returns HTML/CSS/JS **strings**; you need to inject them into a web page for the animation to appear.

To open a demo in your browser, run in a terminal:

```bash
python -m cat_miner_ui
```

Your default browser will open with the cat miner demo page.

## Image

- **Sprite**: 3 frames horizontally (300% width), 100% height (1/3 width per frame).
- **Default**: Uses the bundled `static/cat_mining.png`. No extra serving needed.
- **Custom**: Pass a URL, e.g. `render(image_url="/img/my_sprite.png")`.

## Example (NiceGUI)

```python
from nicegui import ui
from cat_miner_ui import render

# Pass your own list of messages (or omit to use defaults)
parts = render(messages=["Loading...", "Hold on", "Almost there"])
# Or use defaults: parts = render()

ui.add_body_html(parts["font_link"])
ui.add_body_html(parts["css"])
ui.add_body_html(parts["html_left"])
ui.add_body_html(parts["html_right"])
ui.add_body_html(parts["script"])
```

## API

- **`get_css(image_url=None)`** → CSS string
- **`get_html(first_message, flip=False)`** → Speech bubble + miner div HTML (flip=True for right-facing)
- **`get_script(messages)`** → Speech-bubble rotation script
- **`get_font_link()`** → Noto Sans KR webfont link tag
- **`render(messages=None, image_url=None)`** → Dict with all of the above.  
  `messages`: list of strings for the speech bubble (any strings).  
  `image_url`: None = use bundled image.
- **`DEFAULT_MESSAGES`** → Default speech-bubble strings (reference).
- **`get_demo_html(messages=None)`** → Full HTML document string for a standalone demo page.

## Publishing to PyPI

See **BUILD.md** in the project root for step-by-step build and upload. Summary:

1. `pip install build twine`
2. `python -m build` → creates wheel/sdist in `dist/`
3. Create an API token on PyPI, then `twine upload dist/*`
