tempestweb 0.2.0__tar.gz → 0.4.0__tar.gz

{tempestweb-0.2.0 → tempestweb-0.4.0}/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to **tempestweb** are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/); this project adheres to semantic
 versioning.
 
+## [0.4.0] — 2026-06-13
+
+### Added
+
+- **`[wasm].modules` resolves from the installed environment** — each entry is now
+  resolved in two steps: a vendored copy beside `app.py`
+  (`<project>/<module>/`) still wins, but when none exists the module is pulled
+  straight from the project's `.venv` `site-packages` via `importlib`. A
+  dependency you `uv add` no longer has to be cloned and committed at the repo
+  root to make it into the wasm bundle — just list it in `modules`. A name that is
+  neither vendored nor importable fails the build with a clear message.
+  Backward compatible: existing vendored layouts build unchanged. A stale project
+  directory holding only `__pycache__` (real source deleted, bytecode lingering)
+  no longer shadows the installed package and silently bundles nothing — it falls
+  through to the installed copy.
+
+## [0.3.0] — 2026-06-13
+
+### Added
+
+- **`native.install` capability** — the PWA install flow in Python:
+  `install.state()` → `InstallState(can_install, installed)` and
+  `install.prompt()` → `"accepted" | "dismissed" | "unavailable"`. Wraps the soft
+  controller in `client/pwa/install-prompt.js` (now copied into the wasm
+  artifact) via `client/native/install.js`.
+
 ## [0.2.0] — 2026-06-13
 
 Real-app capabilities, driven by building a full on-device vision PWA (FAMACHApp)

{tempestweb-0.2.0 → tempestweb-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempestweb
-Version: 0.2.0
+Version: 0.4.0
 Summary: Build web apps in typed Python — one tree, a DOM renderer, two execution modes (WASM + server).
 Author-email: Mauricio Benjamin <mauricio.benjamin@reloverelations.com>
 License: MIT

{tempestweb-0.2.0 → tempestweb-0.4.0}/client/native/index.js

@@ -19,6 +19,7 @@ import { storageGet, storageList, storagePut, storageRemove } from "./storage.js
 import { cameraCapture } from "./camera.js";
 import { onnxLoad, onnxRun } from "./onnx.js";
 import { fileSave, filePick } from "./file.js";
+import { installState, installPrompt } from "./install.js";
 import {
   notificationsNotify,
   notificationsRequestPermission,
@@ -80,6 +81,8 @@ export const HANDLERS = {
   "onnx.run": onnxRun,
   "file.save": fileSave,
   "file.pick": filePick,
+  "install.state": installState,
+  "install.prompt": installPrompt,
   "notifications.notify": notificationsNotify,
   "notifications.request_permission": notificationsRequestPermission,
   "notifications.subscribe": notificationsSubscribe,

tempestweb-0.4.0/client/native/install.js

@@ -0,0 +1,51 @@
+// native/install.js — PWA install-prompt capability.
+//
+// Wraps the soft install controller (client/pwa/install-prompt.js) in a single
+// process-wide instance so Python can ask whether the app is installable and
+// fire the stashed `beforeinstallprompt` after a real gesture. The controller is
+// created on first import so its listeners attach as early as the native bundle
+// loads (suppressing the browser mini-infobar when it catches the event).
+
+import { createInstallPrompt } from "../pwa/install-prompt.js";
+
+/** @type {ReturnType<typeof createInstallPrompt> | null} */
+let _controller = null;
+
+/**
+ * Lazily create (and cache) the install-prompt controller.
+ * @param {import("./index.js").NativeDeps} [deps]
+ * @returns {ReturnType<typeof createInstallPrompt>}
+ */
+function controller(deps) {
+  if (_controller) return _controller;
+  const win = (deps && /** @type {any} */ (deps).window) || globalThis;
+  _controller = createInstallPrompt({ window: win });
+  return _controller;
+}
+
+// Attach listeners as early as this module loads.
+if (typeof globalThis !== "undefined" && globalThis.addEventListener) {
+  controller();
+}
+
+/**
+ * Report the current install state.
+ * @param {Object} _args
+ * @param {import("./index.js").NativeDeps} deps
+ * @returns {Promise<{can_install:boolean, installed:boolean}>}
+ */
+export async function installState(_args, deps) {
+  const state = controller(deps).getState();
+  return { can_install: Boolean(state.canInstall), installed: Boolean(state.installed) };
+}
+
+/**
+ * Fire the stashed native install prompt.
+ * @param {Object} _args
+ * @param {import("./index.js").NativeDeps} deps
+ * @returns {Promise<{outcome:"accepted"|"dismissed"|"unavailable"}>}
+ */
+export async function installPrompt(_args, deps) {
+  const outcome = await controller(deps).promptInstall();
+  return { outcome };
+}

{tempestweb-0.2.0 → tempestweb-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tempestweb"
-version = "0.2.0"
+version = "0.4.0"
 description = "Build web apps in typed Python — one tree, a DOM renderer, two execution modes (WASM + server)."
 readme = "README.md"
 requires-python = ">=3.11"

{tempestweb-0.2.0 → tempestweb-0.4.0}/tempestweb/cli/commands/build.py

@@ -23,6 +23,7 @@ WebSocket transport — ``python server.py`` (or ``uvicorn server:app``) serves
 from __future__ import annotations
 
 import hashlib
+import importlib.util
 import json
 import shutil
 import zipfile
@@ -74,6 +75,7 @@ _NATIVE_ASSETS: tuple[str, ...] = (
     "file.js",
     "geolocation.js",
     "http.js",
+    "install.js",
     "notifications.js",
     "onnx.js",
     "share.js",
@@ -119,6 +121,7 @@ WASM_ARTIFACT_FILES: tuple[str, ...] = (
     *(f"client/{asset}" for asset in (*_CLIENT_ASSETS, "transport-wasm.js")),
     *(f"client/native/{asset}" for asset in _NATIVE_ASSETS),
     "client/push/web-push-client.js",
+    "client/pwa/install-prompt.js",
 )
 
 # Files a server artifact must contain, relative to the artifact root.
@@ -234,6 +237,80 @@ def _zip_tree(
             archive.write(path, str(path.relative_to(root)))
 
 
+def _is_vendored(candidate: Path) -> bool:
+    """Tell whether ``candidate`` is a usable vendored module/package.
+
+    A single file counts. A directory counts only if it holds at least one
+    bundlable file (anything outside ``__pycache__``) — so a stale directory
+    left holding only ``__pycache__`` after the real source was deleted does
+    **not** shadow the installed package and silently bundle nothing.
+
+    Args:
+        candidate: The ``project_root/module`` path to test.
+
+    Returns:
+        ``True`` if the path is a file or a directory with real content.
+    """
+    if candidate.is_file():
+        return True
+    if not candidate.is_dir():
+        return False
+    return any(
+        path.is_file() and "__pycache__" not in path.parts
+        for path in candidate.rglob("*")
+    )
+
+
+def _resolve_module(module: str, project_root: Path | None) -> tuple[Path, str]:
+    """Resolve a ``[wasm].modules`` entry to its ``(root, top)`` for bundling.
+
+    Resolution order:
+
+    1. A **vendored copy** under ``project_root`` (``project_root/module``) that
+       carries real content — preserves the historical behavior where a copy
+       sitting beside ``app.py`` wins. A stale directory holding only
+       ``__pycache__`` is skipped (see :func:`_is_vendored`).
+    2. An **installed** package or module on ``sys.path`` (resolved via
+       ``importlib``) — so a dependency declared in the project's environment
+       (e.g. an ``uv``-managed ``.venv``) is pulled straight from site-packages
+       with no vendored copy committed to the repository.
+
+    Args:
+        module: The top-level module or package name from ``[wasm].modules``.
+        project_root: The project directory, when available.
+
+    Returns:
+        A ``(root, top)`` pair where ``root`` is the parent directory archive
+        entries are made relative to and ``top`` is the file or directory name
+        under it — fed straight into :func:`_zip_tree`.
+
+    Raises:
+        BuildError: If the module is neither vendored under ``project_root`` nor
+            importable from the current environment.
+    """
+    if project_root is not None and _is_vendored(project_root / module):
+        return project_root, module
+
+    try:
+        spec = importlib.util.find_spec(module)
+    except (ImportError, ValueError):
+        spec = None
+    if spec is not None:
+        locations = list(spec.submodule_search_locations or ())
+        if locations:
+            package_dir = Path(locations[0]).resolve()
+            return package_dir.parent, module
+        if spec.origin and spec.origin not in ("built-in", "frozen"):
+            origin = Path(spec.origin).resolve()
+            return origin.parent, origin.name
+
+    vendored = f"{project_root / module}" if project_root is not None else "<none>"
+    raise BuildError(
+        f"wasm module {module!r} not found: no vendored copy at {vendored} "
+        f"and not importable from the current environment"
+    )
+
+
 def _zip_package(
     dest: Path,
     *,
@@ -254,11 +331,16 @@ def _zip_package(
         dest: The ``.zip`` path to write.
         project_root: The project directory the ``modules`` are relative to.
             Required when ``modules`` is non-empty.
-        modules: Project-relative names (files or package dirs) to bundle next to
-            ``app.py`` (e.g. ``("famacha",)``).
+        modules: Names (files or package dirs) to bundle next to ``app.py``
+            (e.g. ``("famacha",)``). Each is resolved by :func:`_resolve_module`:
+            a vendored copy under ``project_root`` wins, otherwise the module is
+            pulled from the installed environment (site-packages) via importlib —
+            so a dependency declared in the project's ``.venv`` need not be
+            vendored into the repository.
 
     Raises:
-        BuildError: If an expected package part or a declared module is missing.
+        BuildError: If an expected package part is missing, or a declared module
+            is neither vendored nor importable.
     """
     tempestweb_root = _package_dir().parent
     tempest_core_root = _tempest_core_dir().parent
@@ -266,9 +348,8 @@ def _zip_package(
         _zip_tree(archive, tempestweb_root, "tempestweb", _WASM_PACKAGE_PARTS)
         _zip_tree(archive, tempest_core_root, "tempest_core", None)
         for module in modules:
-            if project_root is None:
-                raise BuildError("project_root is required to bundle wasm modules")
-            _zip_tree(archive, project_root, module, None)
+            root, top = _resolve_module(module, project_root)
+            _zip_tree(archive, root, top, None)
 
 
 def _build_pwa(out: Path, client: Path, name: str, precache: tuple[str, ...]) -> None:
@@ -773,6 +854,13 @@ def _build_wasm(
     push_dest = out / "client" / "push"
     push_dest.mkdir(parents=True, exist_ok=True)
     shutil.copyfile(push_source, push_dest / "web-push-client.js")
+    # The install capability imports the soft install-prompt controller.
+    install_source = client / "pwa" / "install-prompt.js"
+    if not install_source.is_file():
+        raise BuildError(f"missing pwa asset: {install_source}")
+    pwa_dest = out / "client" / "pwa"
+    pwa_dest.mkdir(parents=True, exist_ok=True)
+    shutil.copyfile(install_source, pwa_dest / "install-prompt.js")
     # Project static assets (ONNX models, vendored JS libs) copied verbatim,
     # preserving their relative path, and precached for the offline second load.
     assets: list[str] = []

{tempestweb-0.2.0 → tempestweb-0.4.0}/tempestweb/native/__init__.py

@@ -46,6 +46,7 @@ from tempestweb.native import (
     file,
     geolocation,
     http,
+    install,
     notifications,
     onnx,
     storage,
@@ -78,6 +79,9 @@ from tempestweb.native.http import (
     request,
     upload,
 )
+from tempestweb.native.install import InstallState
+from tempestweb.native.install import prompt as install_prompt
+from tempestweb.native.install import state as install_state
 from tempestweb.native.notifications import (
     NotificationPermission,
     notify,
@@ -109,6 +113,7 @@ __all__ = [
     "file",
     "geolocation",
     "http",
+    "install",
     "notifications",
     "onnx",
     "storage",
@@ -161,6 +166,10 @@ __all__ = [
     "SaveResult",
     "file_pick",
     "file_save",
+    # install (PWA install prompt)
+    "InstallState",
+    "install_prompt",
+    "install_state",
     # notifications
     "NotificationPermission",
     "notify",

tempestweb-0.4.0/tempestweb/native/install.py

@@ -0,0 +1,57 @@
+"""Native PWA install-prompt capability (P0).
+
+Exposes the browser's soft install flow to Python: whether the app is installable
+(a ``beforeinstallprompt`` was captured) or already installed, and a call to fire
+the stashed prompt after a real user gesture. ``client/native/install.js`` wraps
+the tested ``client/pwa/install-prompt.js`` controller.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+from tempestweb.native.dispatch import send_native_call
+
+__all__ = ["InstallState", "prompt", "state"]
+
+
+class InstallState(BaseModel):
+    """The current PWA install state.
+
+    Attributes:
+        can_install: A deferred prompt is available to fire.
+        installed: The app reports as installed (standalone / appinstalled).
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    can_install: bool = False
+    installed: bool = False
+
+
+async def state() -> InstallState:
+    """Report whether the app is installable and/or already installed.
+
+    Returns:
+        The current :class:`InstallState`.
+
+    Raises:
+        BrowserUnavailableError: If called with no native bridge installed.
+    """
+    value = await send_native_call("install.state", {})
+    return InstallState.model_validate(value)
+
+
+async def prompt() -> str:
+    """Fire the stashed native install prompt after a user gesture.
+
+    Returns:
+        The outcome: ``"accepted"``, ``"dismissed"``, or ``"unavailable"`` (no
+        prompt was captured, or it was already used).
+
+    Raises:
+        BrowserUnavailableError: If called with no native bridge installed.
+    """
+    value = await send_native_call("install.prompt", {})
+    outcome = value.get("outcome", "unavailable")
+    return str(outcome)

{tempestweb-0.2.0 → tempestweb-0.4.0}/tests/client/native-onnx-file.test.js

@@ -163,6 +163,23 @@ test("file.pick: reads the chosen file back as base64", async () => {
   assert.equal(res.value.name, "ovino.png");
 });
 
+test("install.state/prompt: no captured event → not installable, unavailable", async () => {
+  const fakeWindow = {
+    addEventListener() {},
+    removeEventListener() {},
+    matchMedia: () => ({ matches: false }),
+    navigator: {},
+  };
+  const deps = { window: fakeWindow };
+  const s = await dispatch(call("install.state"), deps);
+  assert.equal(s.ok, true);
+  assert.equal(s.value.can_install, false);
+  assert.equal(s.value.installed, false);
+  const p = await dispatch(call("install.prompt"), deps);
+  assert.equal(p.ok, true);
+  assert.equal(p.value.outcome, "unavailable");
+});
+
 test("file.save: uses the Web Share API when it accepts files", async () => {
   const dom = new JSDOM("<!doctype html><html><body></body></html>");
   globalThis.Blob = dom.window.Blob;

{tempestweb-0.2.0 → tempestweb-0.4.0}/tests/client/native.test.js

@@ -58,6 +58,8 @@ test("HANDLERS covers every documented capability name", () => {
     "onnx.run",
     "file.save",
     "file.pick",
+    "install.state",
+    "install.prompt",
     "notifications.notify",
     "notifications.request_permission",
     "notifications.subscribe",