novaui 0.1.0__tar.gz

novaui-0.1.0/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+
+[*.{yml,yaml,json,toml,md,css,js}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab

novaui-0.1.0/.gitattributes

@@ -0,0 +1,5 @@
+* text=auto eol=lf
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.webp binary

novaui-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.DS_Store
+.env
+.env.*
+!.env.example
+*.log
+.coverage
+htmlcov/
+.tox/
+.mypy_cache/

novaui-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,102 @@
+# NovaUI Architecture
+
+## Direction
+
+NovaUI uses a Python declarative API and a browser renderer. The same HTML/CSS/JavaScript frontend can run in a browser or inside a desktop webview. This is not a native-widget renderer.
+
+## Layers
+
+1. **Public API** (`novaui/__init__.py`): ergonomic exports.
+2. **Components** (`novaui/components.py`): component definitions, validated layout/style properties, and JSON-safe serialization.
+3. **State** (`novaui/state.py`): mutable state objects with subscriptions and dependency collection for computed `Text` values.
+4. **Runtime** (`novaui/app.py`, `novaui/server.py`): lifecycle, HTTP endpoints, event registry.
+5. **Frontend** (`novaui/frontend/`): DOM renderer, CSS tokens, event bridge.
+6. **Desktop host** (`novaui/app.py`, `novaui/desktop.py`): optional `pywebview` adapter over the same local HTTP frontend, with validated window options and a per-window facade.
+7. **Application logic** (`novaui/forms.py`, `novaui/routing.py`, `novaui/shell.py`, `novaui/feedback.py`): Python-side form state/validation, route matching, layout compositions, and event-backed feedback controls.
+8. **Native adapters** (`novaui/dialogs.py`, `novaui/clipboard.py`, `novaui/window.py`, `novaui/shortcuts.py`): explicit desktop-only OS access and per-application shortcut registrations.
+9. **Developer tooling** (`novaui/cli.py`, `novaui/project.py`): argparse commands, starter templates, project options, and a context-local project root for runtime asset resolution.
+10. **Data components** (`novaui/data_table.py`): validated column definitions and server-owned table interaction state.
+
+## Component and layout pipeline
+
+Component instances serialize to a small JSON tree. The browser renderer (`novaui/frontend/app.js`) maps the known component types to DOM elements and updates existing elements by stable ID. `Row` and `Column` use Flexbox, `Grid` uses CSS Grid with responsive integer-column presets, `Wrap` uses wrapping Flexbox, `ScrollView` uses overflow scrolling, and `Stack` overlays children in one grid cell. `Container`, `Card`, and `Center` provide box, surface, and centering behavior.
+
+Shared visual properties serialize as style tokens and are applied with DOM `style` APIs. The Python layer validates class names, common CSS lengths, and a constrained style-property allowlist; it rejects CSS URL and expression values. `Theme` serializes its validated mode, primary color, radius, font family, and optional semantic palette overrides into an allowlist of CSS variables. Omitted palette values preserve the built-in light/dark defaults. The server never evaluates browser-supplied code.
+
+## Event flow
+
+1. Python builds a component tree and registers handlers with random 256-bit event IDs.
+2. The browser requests `/api/tree` with the private `X-NovaUI-Request: tree` fetch header; this blocks simple cross-site requests from embedding the endpoint as an image or form target.
+3. The frontend renders safe, known component types using DOM APIs.
+4. A user event posts an event ID and, for a bound input, a validated string value to `/api/event`.
+5. Python invokes only the handler registered for that ID; each ID is single-use.
+6. The server returns the serialized tree. Stable component IDs let the frontend reuse unchanged DOM nodes and update changed properties in place.
+
+The browser never sends source code or callable names.
+
+## Desktop lifecycle and native features
+
+`App.run(desktop=True)` lazily imports optional pywebview, binds the existing server to `127.0.0.1` on port `0` by default, starts the server thread, then creates a webview window pointed at the selected port. The GUI loop runs on the main thread. On close or startup failure, the HTTP server is shut down, its socket is closed, its thread is joined, and the component tree is disposed. Desktop mode rejects non-loopback hosts.
+
+`WindowOptions` validates sizes, minimum sizes, booleans, and a `#RRGGBB` background. `DesktopWindow` wraps a specific pywebview window instance; it does not rely on a process-global active window. The active desktop window is carried through a `ContextVar` only while registered application events execute. Native file dialogs use pywebview. The text clipboard uses Python's optional-at-build-time Tkinter module and reports unavailable Tk/clipboard environments. Menu items are converted to pywebview native menu objects; GTK does not support those menu objects. Shortcut definitions are application-owned and serialized to the existing frontend as opaque event IDs; they do not expose Python names or source code.
+
+The desktop runtime does not expose a general JavaScript-to-Python bridge. The renderer posts registered opaque event IDs through the local HTTP endpoint. The server requires loopback Host values and same-origin `application/json` event requests, bounds concurrent workers and request reads, and limits served project assets to 32 MiB. Responses include a restrictive Content Security Policy, frame denial, and no-referrer policy. Loopback and origin checks reduce browser-based request risk, but do not authenticate local processes or make this a production server.
+
+## CLI and project assets
+
+The CLI runs the same Python entry point through `runpy`; it does not implement a second app runtime. `novaui run` applies project settings from `[tool.novaui]` (CLI flags override config, which overrides defaults) and enforces loopback binding. The CLI carries the entry point's parent as a `ContextVar` while the app is constructed. `App` captures this asset root; direct script launches infer it from `sys.argv[0]`, while interactive launches use the current working directory.
+
+`Image` serializes a relative asset URL under `/assets/`. The HTTP handler decodes the request path, resolves it under `<asset_root>/assets`, checks the resolved target remains inside that directory (including symlinks), and serves a guessed MIME type or 404. Files above 32 MiB are rejected. No arbitrary filesystem path is accepted, and NovaUI does not bundle or transform static files.
+
+`novaui check` compiles project Python sources, verifies NovaUI imports and basic `[project]` name/version metadata, then runs pytest if a tests directory exists. `novaui build` delegates source/wheel creation to the standard `build` frontend; it is an optional development tool, not a runtime dependency. Hot reload and standalone executable packaging are not part of the CLI.
+
+## Data table
+
+`DataTable` validates its `ColumnDef` objects and row mappings during serialization. It applies sort, search, per-column filters, selection, and pagination in Python, then sends only the visible page's formatted cell strings and registered opaque event IDs to the renderer. A `State[list[Mapping]]` is re-read whenever a tree is requested. Formatting returns plain scalar text and the frontend sets it with `textContent`; cell formatters cannot inject HTML. Row click and row-action handlers are registered for that tree and are subject to the existing one-shot event lifecycle. Sorting and filtering currently scan the full in-memory dataset; the table has no virtualization and the local Python timings below do not characterize large-dataset browser responsiveness.
+
+## Local Python performance baseline
+
+Run `env PYTHONPATH=. .venv/bin/python benchmarks/runtime.py` to reproduce the framework-only baseline. On Linux 7.0.0-31-generic x86_64 with CPython 3.14.4, median times across 7 runs were: construct an App with 100 `Text` children, 0.203 ms; serialize that tree, 0.306 ms; notify one state subscriber, 0.000418 ms; dispatch a button event plus serialize the next tree, 0.010 ms; bind and close the HTTP listening socket without serving requests, 0.103 ms. The 3-column DataTable serialization medians were 0.195 ms for 100 rows, 1.163 ms for 1,000 rows, and 6.557 ms for 5,000 rows, with traced peaks of 16.5, 70.0, and 884.5 KiB respectively. General operations use 100 iterations/run; event and socket operations use 20, and DataTable operations use 10. DataTable memory excludes source data; no browser engine, frontend layout/paint, network round trip, full threaded-server shutdown, or desktop startup is included. These are local baselines, not cross-framework claims.
+
+## Forms and navigation
+
+`Field` owns a string `State`; `Form` binds fields to existing `Input` components and validates submitted values before calling application code. Form event bodies are bounded mappings of safe field names to strings. Validation callback errors and submission errors are returned as generic messages; logs include only the exception type. Form callbacks are synchronous. This is local application logic, not a replacement for validation in trusted services.
+
+`Router` resolves exact static paths and single-segment `{parameter}` patterns in Python. The frontend requests `/api/tree?path=...`; `server.py` serves a fixed `index.html` for non-API paths, so route paths cannot expose files. Browser navigation updates the URL with History API and reloads the Python component tree on `popstate`. The current page factory cache is in-memory. `ui.navigate()` is scoped to the callback currently being dispatched.
+
+`AppShell`, `Tabs`, `Alert`, `Spinner`, and `Dialog` are composed or rendered through the same known-component renderer. Dialog confirm and cancel have separate registered event IDs.
+
+## Extension boundary
+
+`novaui/extensions.py` provides explicit extension configuration. Each `App` copies component, theme, and plugin registrations so services and extension names remain app-scoped. `CustomComponent` composes one cached NovaUI component subtree and delegates serialization to the existing known-component renderer; it cannot emit raw markup or script. Named `Theme` instances use the same token serialization as inline themes. Plugins are application-supplied trusted Python objects: setup is run at app construction, runtime hooks run in deterministic order, and start hooks are unwound in reverse order on shutdown or startup failure. Optional version and module checks use the standard library. Entry-point discovery, sandboxing, renderer plugins, and a stable binary/plugin ABI are intentionally absent.
+
+`App.set_theme()` changes the theme used by the next serialized tree, allowing callbacks to switch themes through the existing full-tree event response. The Phase 11 Studio and Admin apps exercise this path. Component metadata is not currently machine-readable, so Studio maintains a curated app-level catalogue. The PyOffice validation app demonstrates native file dialogs and bounded plain-text persistence; NovaUI does not yet provide multiline text editing, charts, or editable grids.
+
+## Security boundary and limitations
+
+The development server accepts only loopback bind hosts (`127.0.0.1` or `localhost`), validates the Host authority, requires the private fetch header for tree requests, and requires a matching loopback Origin plus JSON content type for event POSTs. Requests without Origin are rejected. The server caps event bodies at 16 KiB, bounds active request workers to 32, sets a 10 second socket timeout, and refuses project assets larger than 32 MiB. The frontend uses known component types and DOM text APIs; the server does not evaluate browser-provided code. See [SECURITY.md](SECURITY.md) for the threat model and reporting policy.
+
+These checks do not provide authentication, per-user sessions, isolation from other processes running as the same user, or hardened public hosting. Callback and route code is application code and runs synchronously in a request thread. Desktop applications still expose their local endpoint to processes able to reach loopback. The current browser frontend requires inline style attributes through DOM style properties, so the CSP allows inline styles while restricting scripts to same-origin files.
+
+## Important MVP limitations
+
+- The handler registry is in-memory and intended for one local application session.
+- The development server binds to loopback.
+- The renderer is intentionally small; components are not yet fully accessible or production hardened.
+- Visual components support validated integer pixel `width` and `height`; shared min/max constraints and margins accept CSS lengths. Width and height themselves remain integer pixels in this release.
+- Form fields are strings and currently render text, email, password, number, and date inputs. Checkbox, radio, select, textarea, native date object conversion, async callbacks, and persistent settings are not implemented.
+- Router route factories and event handlers run synchronously in bounded server request threads. There is no authentication, production session isolation, or hardened public hosting mode.
+- Dialogs are basic native HTML dialogs; focus restoration and complete assistive-technology behavior need further review. `Toast` and global imperative `ui.confirm()` do not exist.
+- The server still serializes the full tree after each event. The frontend reuses existing DOM nodes, but the protocol does not yet send narrow property patches.
+- `Text` tracks `State.value` reads, caches computed text until a dependency changes, and releases its subscriptions when its owning `App` is disposed. Updates from background Python code are not pushed to browsers without a subsequent tree request.
+- Inputs support `State[str]`, optional `on_change`, text/email/password/number/date types, disabled, and read-only modes. They commit on browser `change`; values are limited to 8,000 characters. `on_change` can return a text error message, which is safely displayed and associated with the field. `Form` validates on change and submit.
+- Event request bodies are limited to 16 KiB. Event IDs are single-use and expire when the tree is serialized again. The registry contains handlers for the current tree only.
+- Desktop mode requires a platform webview backend in addition to pywebview. Linux users can install the optional Qt extra; host display and system-library issues remain outside NovaUI's runtime.
+- The tested backend API targets pywebview 6.2; legacy dialog constants are used as a fallback for older supported pywebview releases. Windows WebView2/.NET, macOS Cocoa/WebKit, and Linux GTK/WebKit or Qt/WebEngine dependencies remain OS-managed. No Windows or macOS GUI run has been performed from this environment.
+- Native open/save dialogs return a selected path or `None`; NovaUI never opens or writes the selected path automatically. The current pywebview API has no file-dialog title option. Clipboard support is text-only through Tk and depends on a working desktop clipboard service. Native menus are not supported by GTK; context menus, app icons, and notifications are not included.
+- `Mod` shortcuts map to Ctrl on Windows/Linux and Meta/Command on macOS. They are ignored in text-entry elements unless explicitly allowed. Browser/OS shortcut conflicts are possible.
+- PyInstaller configuration is a sample and has not been run. A frozen app still relies on platform webview/system libraries and should be built and tested on its target OS.
+
+## Planned evolution
+
+Next: broader form controls, robust route lifecycle and async callbacks, narrower property-patch delivery, push updates for background state changes, accessibility standards, hot reload, and verified distribution packaging. See `ROADMAP.md`.

novaui-0.1.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0 - 2026-10-24
+
+- Made `novaui/__init__.py` the authoritative package version source, declared the existing MIT license for distribution, removed the unverified placeholder author from package metadata, and explicitly included frontend resources in wheels.
+- Switched the HTTP server to `importlib.resources` for frontend asset access and added package-resource smoke tests.
+- Added version-tagged PyPI Trusted Publishing and manually confirmed TestPyPI verification workflows, plus GitHub issue and pull-request templates.
+- Configured package metadata, public GitHub project links, and PyPI Trusted Publishing workflows; PyPI publication remains pending.
+- Added validated optional semantic theme colors for page backgrounds, surfaces, foreground and muted text, borders, and primary hover states; existing themes retain their defaults when these values are omitted.
+- Reworked the README and added a navigable Markdown documentation set, runnable tutorial gallery, public API reference additions, and automatic documentation/example smoke checks.
+- Documented pre-1.0 API stability and semantic versioning, and clarified private security reporting setup and maintainer response expectations.
+- Added an explicit app-scoped extension configuration for compositional custom components, named themes, trusted plugins, and plugin-owned services. Plugins are never discovered or executed automatically.
+- Hardened the loopback HTTP server with Host and same-origin checks for event requests, a bounded request-worker pool, socket timeouts, response security headers, and a project-asset size limit.
+- Added security regression tests, CI checks, security policy, contribution guide, and release checklist.
+- Recorded the current local DataTable Python serialization baseline and remaining MVP limitations.

novaui-0.1.0/CLI.md

@@ -0,0 +1,34 @@
+# NovaUI CLI
+
+Install NovaUI (editable from this source checkout with `python -m pip install -e '.[dev]'`) to register the `novaui` command. `python -m novaui` is equivalent.
+
+## Commands
+
+- `novaui --help`, `novaui --version` — show command help or installed package version.
+- `novaui create my_app` — create a starter project. Names must start with a letter and contain letters, digits, `_`, or `-`. Existing paths are never overwritten.
+- `novaui run` — run `app.py` in the current project, or use `[tool.novaui].entry` from `pyproject.toml`.
+- `novaui run path/to/app.py --mode web|desktop` — select hosting explicitly. `web` is the default. Desktop requires `python -m pip install 'novaui[desktop]'` and a working platform webview.
+- `novaui run --host 127.0.0.1 --port 8000 --open-browser` — choose a loopback address and port and open the browser. Port `0` asks the OS for an available port. `--no-browser` is the default.
+- `novaui run --debug` or `novaui --debug run` — include detailed Python diagnostics. Without debug, ordinary configuration/runtime errors are concise.
+- `novaui check` — compile Python files outside virtualenv/cache/build directories, import NovaUI, validate basic project name/version metadata when `pyproject.toml` exists, and run `pytest -q` in-process if a `tests/` directory exists. If pytest is missing, the test check is clearly marked skipped.
+- `novaui build` — run `python -m build --sdist --wheel` into `dist/`. Install the optional build frontend first with `python -m pip install 'novaui[build]'` (or use the `dev` extra).
+
+CLI values override `[tool.novaui]`, which overrides defaults:
+
+```toml
+[tool.novaui]
+entry = "app.py"
+mode = "web"
+host = "127.0.0.1"
+port = 8000
+```
+
+Only these four scalar keys are supported. The development CLI rejects non-loopback hosts. Use `novaui create` for a complete starter layout; install NovaUI into that project's environment before installing its `novaui` dependency when working from an unpublished source checkout.
+
+## Assets
+
+Put files under the project `assets/` directory. `ui.Image("assets/logo.png", alt="Logo")` renders through the local asset endpoint. The endpoint confines requests to that directory, including symlink resolution, and returns 404 for missing or escaping paths. Other files such as CSS, JavaScript, fonts, and icons can be loaded by the application using `/assets/<relative-path>` URLs. NovaUI does not bundle or transform assets. The CLI and direct script launches resolve the asset root from the entry point's directory; interactive launches use the current working directory.
+
+## Exit status and limitations
+
+Argument/configuration errors return `2`; application/runtime/check failures return a nonzero status; successful commands return `0`. `check` is a deterministic source syntax/import/test check, not a type checker or security audit. Hot reload is not implemented. `build` creates Python distributions; it does not create a desktop executable. For that, see the PyInstaller sample in `packaging/` and build on the target OS.

novaui-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,16 @@
+# Contributor Code of Conduct
+
+NovaUI contributors and community members are expected to keep project spaces
+welcoming, respectful, and focused on constructive technical collaboration.
+
+Examples of unacceptable behavior include harassment, discrimination,
+intimidation, personal attacks, and publishing another person's private
+information without permission.
+
+Please report conduct concerns privately to the repository owner through the
+hosting service's private contact mechanism. This repository does not currently
+publish a monitored conduct-reporting address. Maintainers should enable a
+private reporting channel before opening public community spaces.
+
+Maintainers may edit, remove, or decline contributions that violate this policy
+and may restrict participation when necessary to protect community members.

novaui-0.1.0/COMPONENTS.md

@@ -0,0 +1,170 @@
+# NovaUI Component Reference
+
+This reference documents components currently implemented by NovaUI. Components are Python objects that serialize to a validated tree and render through the shared HTML/CSS/JavaScript frontend.
+
+## Shared properties
+
+All current components accept these keyword-only properties:
+
+| Property | Accepted values | Default | Behavior |
+| --- | --- | --- | --- |
+| `margin` | pixel integer or CSS length; margin also accepts 1–4 CSS length tokens | `None` | Outer spacing |
+| `min_width`, `max_width`, `min_height`, `max_height` | pixel integer or CSS length | `None` | CSS min/max size |
+| `background`, `border`, `shadow` | safe CSS value string | `None` | Inline visual token |
+| `visible` | `bool` | `True` | Hides the rendered element when false |
+| `class_name` | CSS class names separated by spaces | `None` | Adds classes to the rendered element |
+| `style` | Mapping of allowed CSS property names to strings or numbers | `None` | Applied with DOM style properties; numbers use pixels except unitless CSS properties |
+
+Style values reject declaration delimiters, markup delimiters, `url()`, and `expression()`. Supported custom style properties include color, background color, borders, typography, spacing, overflow, and grid columns. Component-specific properties take precedence where they set the same CSS property.
+
+The visual components `Text`, `Button`, `Image`, `Input`, `Card`, `Center`, `Container`, `Grid`, `ScrollView`, `Stack`, `Wrap`, and `Spacer` also accept `width` and `height` as non-negative integer pixels.
+
+## Content and controls
+
+### `Text(text, size=None, bold=False, color=None)`
+
+Renders text with `textContent` (never as HTML). `text` may be a string or zero-argument callable. Callables track reads from `State` instances and recalculate when those states change. `size` is a non-negative pixel integer; `bold` is a bool; `color` is a CSS color string.
+
+### `Image(src, alt, width=None, height=None)`
+
+Displays a local file from the app's `assets/` directory, for example `ui.Image("assets/logo.png", alt="NovaUI logo")`. `alt` is required. Absolute paths, parent-directory traversal, and paths outside `assets/` are rejected. The CLI resolves assets relative to the entry-point directory; direct Python launches use the working directory. Other static files can be requested at `/assets/<path>` without a bundler.
+
+### `Button(label, on_click=None, disabled=False, variant="primary")`
+
+Renders a keyboard-operable button. `on_click` is registered with an opaque one-shot event ID. `variant` is `primary` or `secondary`.
+
+### `Input(placeholder="", value="", password=False, label=None, on_change=None, disabled=False, read_only=False, input_type="text", ...)`
+
+Renders a text or password field. `value` may be a string or `State[str]`. When bound or when `on_change` is supplied, the browser sends the changed string through the validated event bridge. `on_change(value)` may return an error string or `None`; errors are rendered as text and associated with the field.
+
+`input_type` supports `text`, `email`, `password`, `number`, and `date`; `password=True` remains a shorthand for password type. Optional `name`, `required`, `min_length`, `max_length`, `min_value`, and `max_value` set the corresponding field semantics and are validated in Python. See [Forms](FORMS.md) for Python-side `Field`/`Form` validation.
+
+## Layouts
+
+### `Animated(child, enter="fade", duration=240, easing="ease-out")`
+
+Wraps one component and applies a CSS entrance animation the first time that component node is mounted. Presets are `fade`, `fade_up`, `fade_down`, `slide_in`, `scale_in`, and `pop`; easing is one of `linear`, `ease`, `ease-in`, `ease-out`, or `ease-in-out`; duration is an integer from 0 to 2000 milliseconds. Nested child behavior and events use the normal component renderer. The wrapper remains mounted during state updates, so the entrance effect does not replay on each update. Exit animation is not supported because the current reconciliation lifecycle removes obsolete nodes immediately. The frontend honors `prefers-reduced-motion` for animations, transitions, and the spinner.
+
+All layout constructors accept child components as positional arguments. Empty layouts render as empty elements.
+
+### `Row(*children, spacing=8, padding=0, align="center", justify="start")`
+
+Flexbox horizontal layout. `align` accepts `start`, `center`, `end`, `stretch`, or `baseline`; `justify` accepts `start`, `center`, `end`, `between`, `around`, or `evenly`. Rows wrap on narrow screens.
+
+### `Column(*children, spacing=8, padding=0, align="stretch", justify="start")`
+
+Flexbox vertical layout, with the same alignment options as `Row`.
+
+### `Card(*children, padding=16, radius=12)`
+
+Surface section with theme background, border, and shadow defaults. `radius` is a non-negative pixel integer.
+
+### `Center(child)`
+
+Centers one child using Flexbox.
+
+### `Container(*children, padding=0)`
+
+Generic box for sizing and shared visual properties.
+
+### `Grid(*children, columns=2, spacing=8, padding=0)`
+
+CSS Grid layout. `columns` is an integer from 1 to 12 or a CSS grid-template string. Integer templates use equal-width columns and collapse to two columns on tablet widths and one on narrow screens when the configured count is greater than one.
+
+### `ScrollView(*children, direction="vertical", padding=0)`
+
+Scrollable container. `direction` is `vertical`, `horizontal`, or `both`. Use `height`, `width`, `max_height`, or `max_width` to constrain its viewport.
+
+### `Stack(*children)`
+
+Overlays children in a shared CSS Grid cell. Give the stack dimensions or constrain it through shared min/max properties when needed.
+
+### `Wrap(*children, spacing=8, run_spacing=8, align="start")`
+
+Wrapping Flexbox layout. `spacing` sets horizontal gaps; `run_spacing` sets gaps between wrapped lines. `align` is `start`, `center`, `end`, or `stretch`.
+
+### `Spacer(size=8)`
+
+Flexible empty space in a row or column. `size` is a non-negative pixel minimum.
+
+## Data components
+
+### `ColumnDef(key, title=None, width=None, sortable=True, formatter=None)`
+
+Defines one table column. Keys must be unique valid field names and must exist in every row. `width` accepts non-negative pixel integers or supported CSS lengths. `formatter(value, row)` may return text or a scalar; results are always rendered as text, never HTML.
+
+### `DataTable(columns, data, selectable=False, sortable=True, searchable=True, filterable=True, page_size=20, ...)`
+
+Renders a semantic, horizontally scrollable table. `data` is a sequence of mappings or a `State` containing one. Header buttons sort ascending/descending; a global search box and per-column filter fields update server-owned filters. Pagination is one-based. Select-all applies to the visible page; `on_selection_change(rows)` receives all currently selected records. Use `row_key` for a unique stable field; without it, selection keys use the source row positions.
+
+`on_row_click(row)` handles accessible mouse and Enter/Space activation of a row. `row_actions` accepts `RowAction(label, on_click)` items and calls each callback with the row. `loading=True` disables actions and shows a loading status. `empty_message` controls the empty-state copy.
+
+```python
+ui.DataTable(
+    columns=[ui.ColumnDef("name", title="Employee"), ui.ColumnDef("salary")],
+    data=[{"id": 1, "name": "Alice", "salary": 65000}],
+    row_key="id",
+    selectable=True,
+    page_size=20,
+)
+```
+
+The table scans/sorts the in-memory dataset on each tree request but sends only the current page's formatted rows to the browser. It is intended for small and medium datasets; it has no virtualization. Search/filter callbacks update the table after the browser `change` event, and NovaUI currently returns the full application tree after each interaction.
+
+Local baseline (Linux 7.0.0-31-generic x86_64, CPython 3.14.4; median across 7 runs, 10 serializations per run, 3 columns sorted descending, page size 20; one additional `tracemalloc` serialization): 100 rows — 0.195 ms / 16.5 KiB; 1,000 rows — 1.163 ms / 70.0 KiB; 5,000 rows — 6.557 ms / 884.5 KiB. Source data is allocated before tracing. Timing excludes browser rendering and HTTP dispatch; memory excludes source data. The reproducible Python-only baseline, including tree construction, state notification, event dispatch, and server socket bind/close, is `env PYTHONPATH=. .venv/bin/python benchmarks/runtime.py`. Figures are environment-specific, not a performance guarantee; full sorting/filtering scans all rows.
+
+## Forms, navigation, and feedback
+
+- `Field(value="", label=None, input_type="text", required=False, min_length=None, max_length=None, min_value=None, max_value=None, validator=None, disabled=False)` tracks a string value, dirty state, and validation result.
+- `Form(fields=..., on_submit=..., submit_label="Submit", reset_label="Reset", disabled=False, loading=False)` validates submitted string values in Python. It exposes `values`, `errors`, `dirty_fields`, `revalidate()`, `reset()`, and `submit(values)`.
+- `Router(routes=..., not_found=None)` maps paths to components or factories. Route factories accept `{parameter}` path values; `params`, `query_params`, and `current_path` describe the resolved URL. Call `ui.navigate(path)` from a component event callback.
+- `AppShell`, `Header`, `Sidebar`, `MainContent`, `Footer`, `NavigationItem`, and `Breadcrumbs` compose the standard layout components. `Sidebar(collapsed=True)` selects a narrow width; it does not provide interactive collapse state.
+- `Tabs({label: component}, selected=None)` serializes the selected panel and supports a `State[str]` selection.
+- `Alert(message, kind="info")` accepts `info`, `success`, `warning`, or `error`; `Spinner(label="Loading")` displays a status indicator.
+- `Dialog(title, child, open=False, on_confirm=None, on_cancel=None, confirm_label="Confirm", cancel_label="Cancel")` provides separate confirm and cancel events. Pass `State[bool]` for controlled visibility.
+
+See [Forms](FORMS.md) and [Routing](ROUTING.md) for runnable examples and security limits. Checkboxes, radio groups, select, textarea, toast queues, and asynchronous form handlers are not implemented.
+
+## Shell, theme, and application APIs
+
+- `AppShell(*children, **shared_props)` composes its children in the standard shell layout. `Header`, `MainContent`, and `Footer` are layout helpers with the same child-first convention.
+- `Sidebar(*children, collapsed=False, **shared_props)` renders a sidebar; `collapsed` chooses a narrow width and is not an interactive toggle. `NavigationItem(label, href, active=False)` renders a navigation link. `Breadcrumbs(items)` accepts labels or `(label, href)` pairs.
+- `Theme(mode="light", primary="#6558d3", radius="10px", font_family="Inter, ui-sans-serif, system-ui, sans-serif", name=None, background=None, surface=None, foreground=None, muted=None, border=None, primary_hover=None)` validates theme tokens. Optional colors override `--bg`, `--surface`, `--text`, `--muted`, `--border`, and `--primary-hover`; omitted values retain the built-in light/dark palette. `name` is used for explicit extension registration; it is omitted from renderer output. See [extensions](EXTENSIONS.md).
+- `State(value)` and `ui.state(value)` provide mutable Python state. Read and assign `.value`, call `.update(value)`, subscribe with `.subscribe(callback)`, and release listeners with `.dispose()`.
+- `App(root, title="NovaUI", theme="light", host="127.0.0.1", port=0, debug=False, extensions=None)` creates a runtime object. `App.set_theme(theme)` accepts `"light"`, `"dark"`, an app-registered theme name, or a `Theme` instance; call it in an event callback to change tokens on the next tree render. `ui.app(root, title=..., theme=..., debug=False, host="127.0.0.1", port=0, extensions=None)` creates and immediately runs it. `ui.desktop(root, title=..., theme=..., width=1200, height=800, min_width=200, min_height=100, resizable=True, fullscreen=False, frameless=False, background_color="#FFFFFF", debug=False, menu=(), on_close=None, extensions=None)` runs it in the optional webview host.
+- `WindowOptions(width=1200, height=800, min_width=200, min_height=100, resizable=True, fullscreen=False, frameless=False, background_color="#FFFFFF")` carries validated desktop settings. `Menu(title, items)`, `MenuItem(title, callback)`, and `MenuSeparator()` describe supported native menu entries.
+- `ShortcutRegistry.register(shortcut, callback, prevent_default=True, allow_in_inputs=False, replace=False)` accepts combinations such as `Mod+S`; `unregister(shortcut)`, `set_enabled(shortcut, enabled)`, and `clear()` manage registrations. Callbacks take no arguments. `Mod` resolves to Ctrl on Windows/Linux and Meta on macOS; shortcuts are ignored in input controls unless opted in.
+- Extension APIs are `Extensions.register_component(name, CustomComponentSubclass)`, `register_theme(named_theme)`, and `use(plugin_instance)`. `CustomComponent.render()` returns a built-in component. See [the extension guide](EXTENSIONS.md) for plugin hooks, compatibility attributes, and trust limitations.
+
+Window controls, file dialogs, clipboard, and shortcuts are runtime integrations rather than visual components. Their support depends on the desktop backend; see [native desktop APIs](docs/desktop/native-apis.md). The root-level `ui.window`, `ui.dialogs`, and `ui.clipboard` modules are only usable from an active desktop event callback.
+
+## Themes
+
+Pass a `Theme` to `ui.app` to set CSS variables:
+
+```python
+theme = ui.Theme(
+    mode="light",
+    primary="#635BFF",
+    radius="12px",
+    font_family="Inter, sans-serif",
+    background="#f7f8fc",
+    surface="#ffffff",
+    foreground="#202333",
+)
+ui.app(ui.Text("Hello"), theme=theme)
+```
+
+`mode` is `light` or `dark`; color fields must be CSS color names, hex, RGB, or HSL values; `radius` is a non-negative pixel integer or CSS length; and `font_family` accepts a restricted family-list string. Existing `theme="light"` and `theme="dark"` calls remain supported.
+
+## Examples
+
+- `python examples/landing.py` — responsive page layout and custom theme.
+- `python examples/dashboard.py` — sidebar-style layout, cards, grid, and scrolling.
+- `python examples/form_validation.py` — input callback validation.
+- `python examples/login.py` — controlled login fields.
+- `python -m examples.phase11_studio.app` — predefined component playground.
+- `python -m examples.phase11_admin.app` — routed administration dashboard.
+- `python -m examples.phase11_pyoffice.app` — desktop plain-text notes prototype (desktop extra required).
+
+Icons, dividers, badges, tooltips, checkbox/radio/select/textarea controls, toast notifications, and machine-readable component metadata remain planned.

novaui-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# Contributing
+
+NovaUI is an early-stage project. Public APIs may evolve before a stable 1.0 release. Avoid breaking documented behavior without tests, migration notes, and a roadmap update.
+
+## Development setup
+
+```bash
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+python -m pip install -e '.[dev]'
+```
+
+Run checks from the repository root:
+
+```bash
+python -m ruff check novaui tests examples packaging
+python -m pytest -q
+node --check novaui/frontend/app.js
+```
+
+HTTP integration tests bind to loopback. Environments that prohibit local sockets cannot run those tests successfully.
+
+## Change expectations
+
+- Add tests for behavior and security-sensitive boundaries.
+- Keep browser payloads structured and never execute client-provided code.
+- Avoid logging application input or secrets.
+- Document implemented APIs and limitations; do not mark planned work complete.
+- Keep base dependencies minimal and optional integrations in extras.
+- Include browser/desktop manual-test notes when a change needs a GUI.
+- New components should include construction/serialization tests, a component-reference entry, and a runnable example where practical.
+
+## Issues and pull requests
+
+Bug reports should include the NovaUI version or commit, Python/OS details, a minimal reproducible example, expected behavior, and actual behavior. Remove passwords, tokens, personal data, and private files before sharing logs. Feature proposals should describe the user problem and a small API sketch; discuss larger changes before implementing them. Pull requests should state the behavior changed, tests and documentation updated, commands run, and any manual platform checks. Keep each change focused and do not claim untested platform support.
+
+## API stability
+
+NovaUI follows semantic versioning for released versions: patch releases are for compatible fixes, minor releases add backward-compatible features, and major releases may break APIs. Before 1.0, the public API is experimental unless a specific interface is marked stable in its docs; pre-1.0 minor releases may still revise experimental APIs. We aim to preserve documented APIs; incompatible changes require a reason, migration guidance, updated examples, and tests. Deprecations should be documented for at least one release before removal where practical.
+
+## Security issues
+
+See [SECURITY.md](SECURITY.md). Do not publish exploit details in an issue before contacting the maintainer privately.

novaui-0.1.0/EXTENSIONS.md

@@ -0,0 +1,119 @@
+# NovaUI Extensions
+
+NovaUI 0.1 exposes a small, explicit extension API for Python code trusted by
+the application owner. Extensions run in the application process with the same
+permissions as the application. They are **not sandboxed**. NovaUI does not
+automatically discover or execute installed plugins.
+
+## Per-application registration
+
+Create an `Extensions` configuration, register additions, then pass it to
+`ui.App`, `ui.app`, or `ui.desktop`. An `App` copies the registrations so
+separate applications do not share service/component/theme registries.
+Plugin objects themselves are the instances supplied by the caller; create a
+fresh `Extensions` object and plugin instance for each independently configured
+application if the plugin stores mutable per-app state.
+
+```python
+import novaui as ui
+
+class StatusBadge(ui.CustomComponent):
+    def __init__(self, text: str, status: str = "ok"):
+        super().__init__()
+        if status not in {"ok", "error"}:
+            raise ValueError("status must be 'ok' or 'error'")
+        self.text, self.status = text, status
+
+    def render(self) -> ui.Component:
+        color = "#087443" if self.status == "ok" else "#b42318"
+        return ui.Text(self.text, color=color, bold=True)
+
+extensions = ui.Extensions()
+extensions.register_component("StatusBadge", StatusBadge)
+ui.app(ui.Column(StatusBadge("Connected")), extensions=extensions)
+```
+
+Custom components subclass `CustomComponent` and implement `render()` to
+return one NovaUI `Component`. NovaUI caches that returned subtree per instance
+and sends it through the ordinary renderer and event registry. Common styling
+on a custom instance uses the existing `Container` renderer, which adds a
+wrapper only when styling is set. Custom components cannot return raw HTML,
+JavaScript, renderer instructions, or arbitrary JSON. Names must start with a
+letter and contain up to 64 ASCII letters, digits, or underscores. Duplicate
+names in one registry are rejected. A custom component must be registered in
+each `Extensions` configuration used by an app.
+
+## Themes
+
+`Theme` supports validated `mode`, `primary`, `radius`, and `font_family`
+tokens. A named theme can be registered and selected by name:
+
+```python
+extensions = ui.Extensions()
+extensions.register_theme(ui.Theme(
+    name="corporate", mode="light", primary="#3157D5", radius="10px",
+))
+ui.app(ui.Text("Hello"), theme="corporate", extensions=extensions)
+```
+
+Theme registration rejects unnamed themes and duplicate names. The selected
+theme is serialized using the same renderer tokens as an inline `Theme`; it
+does not merge with another theme. Application selection wins because exactly
+one theme is sent to the frontend.
+
+## Plugins and services
+
+Plugins are explicit trusted Python instances. Their unique `name` is required.
+The optional `setup(app)` runs once while the `App` is constructed. Plugins may
+register app-scoped services through `app.register_service(name, service)`;
+application callbacks can retrieve them using `app.get_service(name)`. Duplicate
+service names are errors.
+
+```python
+class MetricsPlugin:
+    name = "metrics"
+    min_novaui_version = "0.1.0"  # inclusive
+    max_novaui_version_exclusive = "1.0.0"
+    optional_dependencies = ("my_metrics_package",)
+
+    def setup(self, app: ui.App) -> None:
+        app.register_service("metrics", MetricsService())
+
+    def on_app_start(self, app: ui.App) -> None:
+        app.get_service("metrics").start()
+
+    def on_app_stop(self, app: ui.App) -> None:
+        app.get_service("metrics").stop()
+
+extensions = ui.Extensions()
+extensions.use(MetricsPlugin())
+application = ui.App(ui.Text("Metrics enabled"), extensions=extensions)
+application.run()
+```
+
+Setup runs in registration order. Version checks use `major.minor.patch`, with
+an inclusive minimum and exclusive maximum. Missing optional modules and
+incompatible NovaUI versions fail app construction with an actionable error.
+`on_app_start(app)` runs in registration order immediately before runtime
+startup; `on_app_stop(app)` runs in reverse order for every plugin whose start
+hook began, including when a later startup hook fails. A startup failure stops
+the application instead of continuing with partial functionality. Shutdown
+hook failures are logged by exception type and do not prevent other plugins or
+app resources from being cleaned up. Hooks are synchronous.
+
+Plugins should keep `setup` limited to registration/configuration and allocate
+runtime resources in `on_app_start`, releasing them in `on_app_stop`. NovaUI
+does not provide process isolation, permission prompts, dependency solving, or
+automatic package entry-point discovery. Importing a plugin module executes
+Python code; only import plugins that you trust.
+
+## Public API and limitations
+
+The supported extension surface is `Extensions`, `CustomComponent`, named
+`Theme`, `App.register_component`, `App.register_theme`,
+`App.register_service`, `App.get_service`, and the three plugin hooks above.
+The component registry, renderer serialization format, and frontend protocol
+remain internal and may change. There is no extension marketplace, hot reload,
+remote plugin support, sandbox, or stable plugin ABI guarantee in NovaUI 0.1.
+For a sample of each extension type, run `examples/extensions_component_pack.py`,
+`examples/extensions_theme_pack.py`, or `examples/extensions_service_plugin.py`.

novaui-0.1.0/FORMS.md

@@ -0,0 +1,28 @@
+# Forms
+
+`ui.Field` keeps a string value and its validation rules; `ui.Form` renders fields, collects browser input through generated event IDs, validates on the Python side, and invokes a synchronous callback with a copy of the submitted values.
+
+```python
+email = ui.Field(label="Email", input_type="email", required=True)
+password = ui.Field(label="Password", input_type="password", required=True, min_length=8)
+
+def sign_in(values: dict[str, str]) -> None:
+    # Validate credentials and authorize against trusted application services here.
+    print("Sign in requested for", values["email"])
+
+form = ui.Form(fields={"email": email, "password": password}, on_submit=sign_in)
+ui.app(form)
+```
+
+Supported field types are `text`, `email`, `password`, `number`, and `date`. Fields support `required`, `min_length`, `max_length`, numeric `min_value`/`max_value`, a `validator(value) -> str | None`, `disabled`, and `placeholder`. `Form` exposes `values`, `errors`, `dirty_fields`, `revalidate()`, `reset()`, `submit_label`, `reset_label`, and external `disabled`/`loading` flags. A successful callback may return a status string; callback exceptions produce a generic status and a safe log entry. Because callbacks are synchronous, the browser cannot show a transient loading indicator while a callback is running. Async callbacks are not supported yet.
+
+Custom validators run in Python:
+
+```python
+def validate_handle(value: str) -> str | None:
+    return "Use at least one letter." if not any(ch.isalpha() for ch in value) else None
+
+handle = ui.Field(required=True, validator=validate_handle)
+```
+
+The browser's native constraints are only a usability aid. Form checks in this local UI process are not a security boundary. Repeat sensitive validation and authorization in trusted server-side business logic. Password values are not stored in browser storage or logged by NovaUI, but the current event bridge sends form values to the Python process over the local HTTP connection.

novaui-0.1.0/LICENSE

@@ -0,0 +1,17 @@
+MIT License
+
+Copyright (c) 2026 NovaUI Contributors
+
+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.