pywebview-htmx 0.2.1__tar.gz → 0.3.1__tar.gz

{pywebview_htmx-0.2.1 → pywebview_htmx-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pywebview-htmx
-Version: 0.2.1
+Version: 0.3.1
 Summary: HTMX-style declarative UI bindings for PyWebview apps
 Author-Email: "B.T. Franklin" <brandon.franklin@gmail.com>
 License: MIT License
@@ -35,7 +35,7 @@ Classifier: Intended Audience :: Developers
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Internet :: WWW/HTTP
 Requires-Python: >=3.14
-Requires-Dist: pywebview>=6.1
+Requires-Dist: pywebview>=6.2.1
 Description-Content-Type: text/markdown
 
 # pywebview-htmx
@@ -84,6 +84,39 @@ pdm install
 pdm add pywebview-htmx
 ```
 
+## Maintainer Docs
+
+For maintainer and agent-facing repository guidance, see
+[`docs/index.md`](docs/index.md).
+
+## Agent Skill
+
+This repository includes an installable coding-agent skill at
+`skills/use-pywebview-htmx/`.
+
+The folder in this repository is the source for a skill that tools such as
+[`npx skills`](https://skills.sh/) can discover and install from GitHub.
+
+List the available skill from this repository:
+
+```bash
+npx skills add btfranklin/pywebview-htmx --list --full-depth
+```
+
+Install just this skill:
+
+```bash
+npx skills add btfranklin/pywebview-htmx --skill use-pywebview-htmx
+```
+
+Other skill installers can consume the same skill folder from this repository.
+The skill includes:
+
+- the core usage workflow
+- a concise contract reference
+- implementation patterns
+- troubleshooting guidance
+
 ## Quick Start
 
 ```python
@@ -117,6 +150,18 @@ create_window("Quickstart", html, js_api=API())
 You do **not** manually include `runtime.js` when using `create_window()`;
 it is injected automatically.
 
+## Important Differences From HTMX
+
+- There is no HTTP request layer. `pywebview-htmx` calls a Python method on
+  `window.pywebview.api` directly.
+- Python handlers should return an HTML string fragment. Returning objects or
+  other data types is treated as an error.
+- For ordinary buttons/links, params still come from `data-py-params`.
+- For `<form py-trigger="submit">`, named fields are serialized automatically
+  and merged over `data-py-params`.
+- Returned HTML is inserted directly into the DOM, so escape untrusted values
+  before returning markup.
+
 ## API Reference (Python)
 
 ### `create_window(title, html, js_api=None, theme="aurora", start=True, **kwargs)`
@@ -143,6 +188,18 @@ Returns the bundled JavaScript runtime as a string.
 
 Injects the runtime script tag into an HTML string (idempotent).
 
+### `encode_params_attr(params)`
+
+Returns HTML-escaped JSON that is safe to place in a `data-py-params`
+attribute.
+
+```python
+from pywebview_htmx import encode_params_attr
+
+payload = encode_params_attr({"user_id": 42, "mode": "full"})
+button = f'<button data-py-params="{payload}">Load user</button>'
+```
+
 ### Theme helpers
 
 - `list_themes()` -> sorted list of available themes
@@ -183,6 +240,8 @@ JSON payload passed to Python method.
 Notes:
 - If missing, params default to `{}`.
 - Invalid JSON logs an error and falls back to `{}`.
+- For submit-triggered forms, named form fields are serialized automatically and
+  merged over this payload.
 
 ### `py-target` (optional)
 
@@ -201,7 +260,15 @@ Unknown value falls back to `innerHTML`.
 ### `py-wait` (optional)
 
 CSS selector of element receiving `.py-waiting` while request is in flight.
-If missing/empty/unresolvable, the triggering element is used.
+If missing, empty, invalid, or unresolvable, the triggering element is used.
+
+### `py-policy` (optional)
+
+Per-element concurrency override. If omitted, the global
+`window.pywebviewHtmx.config.requestPolicy` value is used.
+
+- `latest-wins`
+- `drop`
 
 ## Runtime Config (JavaScript)
 
@@ -240,17 +307,21 @@ document.body.addEventListener("py:error", (event) => {
 
 ## Concurrency Behavior
 
-Per trigger element, `pywebview-htmx` tracks request state.
+`pywebview-htmx` tracks request state by resolved target. Controls that share
+the same `py-target` coordinate request ordering and `drop` behavior. Controls
+without `py-target` use the triggering element as their request state scope.
+Loading state is counted separately per resolved `py-wait` target so shared
+spinners stay active until all in-flight requests finish.
 
 ### `latest-wins` (default)
 
-Multiple rapid requests are allowed; stale responses are ignored.
-Only latest request updates the DOM.
+Multiple rapid requests are allowed; stale responses in the same request state
+scope are ignored. Only the latest request for that scope updates the DOM.
 
 ### `drop`
 
-If a request is already in flight for that element, new triggers are ignored and
-`py:ignored` is emitted.
+If a request is already in flight for the same request state scope, new triggers
+are ignored and `py:ignored` is emitted.
 
 ## Dynamic Content Re-processing
 
@@ -297,7 +368,8 @@ behavior, add your own `<style data-pywebview-theme="my-theme">...</style>` bloc
 ### Pattern 1: Form submit to Python
 
 - Use `py-trigger="submit"` on `<form>`
-- Keep `data-py-params` in sync from form inputs (via JS)
+- Give fields `name` attributes so they can be serialized
+- Use `data-py-params` only for extra static values you want merged in
 - `py-target` a result card/summary region
 
 ### Pattern 2: Append activity/log rows
@@ -308,7 +380,8 @@ behavior, add your own `<style data-pywebview-theme="my-theme">...</style>` bloc
 ### Pattern 3: Replace full component
 
 - Use `py-swap="outerHTML"`
-- Return full replacement markup with same outer id/selector
+- Return full replacement markup with the same outer id/selector if future
+  interactions should keep targeting that component
 
 ### Pattern 4: Theme switch from Python
 
@@ -331,6 +404,7 @@ Check:
 - method returns a string of HTML
 - no JSON parse error in `data-py-params`
 - `py-target` selector exists
+- for forms, fields have `name` attributes
 
 ### "New buttons in swapped HTML do not work"
 
@@ -345,6 +419,21 @@ window.pywebviewHtmx.process(document.body);
 
 Style `.py-waiting` globally and/or point `py-wait` at a dedicated element.
 
+### "I got a Python API return type error"
+
+`pywebview-htmx` expects handlers to return an HTML string fragment. Convert
+structured data into markup before returning it.
+
+## Common Mistakes
+
+- Returning dicts/lists instead of HTML strings
+- Forgetting to escape untrusted values before interpolating into markup
+- Omitting `name` attributes on form fields and expecting them to serialize
+- Using `py-swap="outerHTML"` but not preserving the target component's
+  selector/id
+- Manually mutating the DOM outside of `pywebview-htmx` swaps without calling
+  `window.pywebviewHtmx.process(...)`
+
 ## Demo
 
 Run the full feature showcase:

{pywebview_htmx-0.2.1 → pywebview_htmx-0.3.1}/README.md

@@ -44,6 +44,39 @@ pdm install
 pdm add pywebview-htmx
 ```
 
+## Maintainer Docs
+
+For maintainer and agent-facing repository guidance, see
+[`docs/index.md`](docs/index.md).
+
+## Agent Skill
+
+This repository includes an installable coding-agent skill at
+`skills/use-pywebview-htmx/`.
+
+The folder in this repository is the source for a skill that tools such as
+[`npx skills`](https://skills.sh/) can discover and install from GitHub.
+
+List the available skill from this repository:
+
+```bash
+npx skills add btfranklin/pywebview-htmx --list --full-depth
+```
+
+Install just this skill:
+
+```bash
+npx skills add btfranklin/pywebview-htmx --skill use-pywebview-htmx
+```
+
+Other skill installers can consume the same skill folder from this repository.
+The skill includes:
+
+- the core usage workflow
+- a concise contract reference
+- implementation patterns
+- troubleshooting guidance
+
 ## Quick Start
 
 ```python
@@ -77,6 +110,18 @@ create_window("Quickstart", html, js_api=API())
 You do **not** manually include `runtime.js` when using `create_window()`;
 it is injected automatically.
 
+## Important Differences From HTMX
+
+- There is no HTTP request layer. `pywebview-htmx` calls a Python method on
+  `window.pywebview.api` directly.
+- Python handlers should return an HTML string fragment. Returning objects or
+  other data types is treated as an error.
+- For ordinary buttons/links, params still come from `data-py-params`.
+- For `<form py-trigger="submit">`, named fields are serialized automatically
+  and merged over `data-py-params`.
+- Returned HTML is inserted directly into the DOM, so escape untrusted values
+  before returning markup.
+
 ## API Reference (Python)
 
 ### `create_window(title, html, js_api=None, theme="aurora", start=True, **kwargs)`
@@ -103,6 +148,18 @@ Returns the bundled JavaScript runtime as a string.
 
 Injects the runtime script tag into an HTML string (idempotent).
 
+### `encode_params_attr(params)`
+
+Returns HTML-escaped JSON that is safe to place in a `data-py-params`
+attribute.
+
+```python
+from pywebview_htmx import encode_params_attr
+
+payload = encode_params_attr({"user_id": 42, "mode": "full"})
+button = f'<button data-py-params="{payload}">Load user</button>'
+```
+
 ### Theme helpers
 
 - `list_themes()` -> sorted list of available themes
@@ -143,6 +200,8 @@ JSON payload passed to Python method.
 Notes:
 - If missing, params default to `{}`.
 - Invalid JSON logs an error and falls back to `{}`.
+- For submit-triggered forms, named form fields are serialized automatically and
+  merged over this payload.
 
 ### `py-target` (optional)
 
@@ -161,7 +220,15 @@ Unknown value falls back to `innerHTML`.
 ### `py-wait` (optional)
 
 CSS selector of element receiving `.py-waiting` while request is in flight.
-If missing/empty/unresolvable, the triggering element is used.
+If missing, empty, invalid, or unresolvable, the triggering element is used.
+
+### `py-policy` (optional)
+
+Per-element concurrency override. If omitted, the global
+`window.pywebviewHtmx.config.requestPolicy` value is used.
+
+- `latest-wins`
+- `drop`
 
 ## Runtime Config (JavaScript)
 
@@ -200,17 +267,21 @@ document.body.addEventListener("py:error", (event) => {
 
 ## Concurrency Behavior
 
-Per trigger element, `pywebview-htmx` tracks request state.
+`pywebview-htmx` tracks request state by resolved target. Controls that share
+the same `py-target` coordinate request ordering and `drop` behavior. Controls
+without `py-target` use the triggering element as their request state scope.
+Loading state is counted separately per resolved `py-wait` target so shared
+spinners stay active until all in-flight requests finish.
 
 ### `latest-wins` (default)
 
-Multiple rapid requests are allowed; stale responses are ignored.
-Only latest request updates the DOM.
+Multiple rapid requests are allowed; stale responses in the same request state
+scope are ignored. Only the latest request for that scope updates the DOM.
 
 ### `drop`
 
-If a request is already in flight for that element, new triggers are ignored and
-`py:ignored` is emitted.
+If a request is already in flight for the same request state scope, new triggers
+are ignored and `py:ignored` is emitted.
 
 ## Dynamic Content Re-processing
 
@@ -257,7 +328,8 @@ behavior, add your own `<style data-pywebview-theme="my-theme">...</style>` bloc
 ### Pattern 1: Form submit to Python
 
 - Use `py-trigger="submit"` on `<form>`
-- Keep `data-py-params` in sync from form inputs (via JS)
+- Give fields `name` attributes so they can be serialized
+- Use `data-py-params` only for extra static values you want merged in
 - `py-target` a result card/summary region
 
 ### Pattern 2: Append activity/log rows
@@ -268,7 +340,8 @@ behavior, add your own `<style data-pywebview-theme="my-theme">...</style>` bloc
 ### Pattern 3: Replace full component
 
 - Use `py-swap="outerHTML"`
-- Return full replacement markup with same outer id/selector
+- Return full replacement markup with the same outer id/selector if future
+  interactions should keep targeting that component
 
 ### Pattern 4: Theme switch from Python
 
@@ -291,6 +364,7 @@ Check:
 - method returns a string of HTML
 - no JSON parse error in `data-py-params`
 - `py-target` selector exists
+- for forms, fields have `name` attributes
 
 ### "New buttons in swapped HTML do not work"
 
@@ -305,6 +379,21 @@ window.pywebviewHtmx.process(document.body);
 
 Style `.py-waiting` globally and/or point `py-wait` at a dedicated element.
 
+### "I got a Python API return type error"
+
+`pywebview-htmx` expects handlers to return an HTML string fragment. Convert
+structured data into markup before returning it.
+
+## Common Mistakes
+
+- Returning dicts/lists instead of HTML strings
+- Forgetting to escape untrusted values before interpolating into markup
+- Omitting `name` attributes on form fields and expecting them to serialize
+- Using `py-swap="outerHTML"` but not preserving the target component's
+  selector/id
+- Manually mutating the DOM outside of `pywebview-htmx` swaps without calling
+  `window.pywebviewHtmx.process(...)`
+
 ## Demo
 
 Run the full feature showcase:

{pywebview_htmx-0.2.1 → pywebview_htmx-0.3.1}/pyproject.toml

@@ -6,7 +6,7 @@ authors = [
     { name = "B.T. Franklin", email = "brandon.franklin@gmail.com" },
 ]
 dependencies = [
-    "pywebview>=6.1",
+    "pywebview>=6.2.1",
 ]
 requires-python = ">=3.14"
 readme = "README.md"
@@ -21,14 +21,14 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: Internet :: WWW/HTTP",
 ]
-version = "0.2.1"
+version = "0.3.1"
 
 [project.license]
 file = "LICENSE"
 
 [build-system]
 requires = [
-    "pdm-backend",
+    "pdm-backend>=2.4.9",
 ]
 build-backend = "pdm.backend"
 
@@ -65,6 +65,6 @@ select = [
 
 [dependency-groups]
 dev = [
-    "pytest>=9.0.2",
-    "ruff>=0.15.4",
+    "pytest>=9.0.3",
+    "ruff>=0.15.17",
 ]

{pywebview_htmx-0.2.1 → pywebview_htmx-0.3.1}/src/pywebview_htmx/__init__.py

@@ -1,6 +1,7 @@
 from .runtime import (
     DEFAULT_THEME,
     create_window,
+    encode_params_attr,
     get_runtime_script,
     get_theme_css,
     inject_runtime,
@@ -11,6 +12,7 @@ from .runtime import (
 __all__ = [
     "DEFAULT_THEME",
     "create_window",
+    "encode_params_attr",
     "get_runtime_script",
     "get_theme_css",
     "inject_runtime",

pywebview_htmx-0.3.1/src/pywebview_htmx/py.typed

@@ -0,0 +1 @@
+

{pywebview_htmx-0.2.1 → pywebview_htmx-0.3.1}/src/pywebview_htmx/runtime.py

@@ -1,7 +1,9 @@
 from __future__ import annotations
 
 from importlib.resources import files
+import json
 import re
+from html import escape as html_escape
 from typing import Any
 
 import webview
@@ -56,6 +58,14 @@ def get_runtime_script() -> str:
     )
 
 
+def encode_params_attr(params: Any) -> str:
+    """Encode a payload for safe embedding in ``data-py-params``."""
+    return html_escape(
+        json.dumps(params, sort_keys=True),
+        quote=True,
+    )
+
+
 def inject_runtime(html: str) -> str:
     """Inject the runtime script into an HTML string before ``</body>`` when present."""
     if _SCRIPT_TAG_RE.search(html):

{pywebview_htmx-0.2.1 → pywebview_htmx-0.3.1}/src/pywebview_htmx/static/runtime.js

@@ -8,10 +8,16 @@
     requestPolicy: "latest-wins",
   };
   const requestState = new WeakMap();
+  const waitState = new WeakMap();
 
   function $(selector, root = document) {
     if (!selector) return null;
-    return root.querySelector(selector);
+    try {
+      return root.querySelector(selector);
+    } catch (error) {
+      console.warn("PyWebview HTMX: invalid selector", selector, error);
+      return null;
+    }
   }
 
   function triggerEvent(target, eventName, detail = {}) {
@@ -58,6 +64,47 @@
     }
   }
 
+  function mergeParamValue(target, key, value) {
+    if (Object.prototype.hasOwnProperty.call(target, key)) {
+      const existing = target[key];
+      if (Array.isArray(existing)) {
+        existing.push(value);
+      } else {
+        target[key] = [existing, value];
+      }
+      return;
+    }
+    target[key] = value;
+  }
+
+  function serializeForm(form, event) {
+    const params = {};
+    const formData = new FormData(form);
+
+    for (const [key, value] of formData.entries()) {
+      if (typeof File !== "undefined" && value instanceof File) {
+        console.warn("PyWebview HTMX: file inputs are not supported in data-py-params", key);
+        continue;
+      }
+      mergeParamValue(params, key, value);
+    }
+
+    const submitter = event && "submitter" in event ? event.submitter : null;
+    if (submitter && submitter.name) {
+      mergeParamValue(params, submitter.name, submitter.value || "");
+    }
+
+    return params;
+  }
+
+  function buildRequestParams(element, eventName, event) {
+    const params = parseParams(element);
+    if (element.tagName !== "FORM" || eventName !== "submit") {
+      return params;
+    }
+    return { ...params, ...serializeForm(element, event) };
+  }
+
   function getWaitTarget(element) {
     if (!element.hasAttribute("py-wait")) {
       return element;
@@ -85,25 +132,60 @@
     return await func(params);
   }
 
-  function getRequestState(element) {
-    let state = requestState.get(element);
+  function getRequestState(key) {
+    let state = requestState.get(key);
     if (!state) {
       state = { lastIssued: 0, inFlightCount: 0 };
-      requestState.set(element, state);
+      requestState.set(key, state);
     }
     return state;
   }
 
+  function getRequestStateKey(element, targetSelector) {
+    if (!targetSelector) {
+      return element;
+    }
+    return $(targetSelector) || element;
+  }
+
+  function addWaiting(waitTarget) {
+    const count = (waitState.get(waitTarget) || 0) + 1;
+    waitState.set(waitTarget, count);
+    waitTarget.classList.add("py-waiting");
+  }
+
+  function removeWaiting(waitTarget) {
+    const count = Math.max(0, (waitState.get(waitTarget) || 0) - 1);
+    if (count === 0) {
+      waitState.delete(waitTarget);
+      waitTarget.classList.remove("py-waiting");
+      return;
+    }
+    waitState.set(waitTarget, count);
+  }
+
   function shouldPreventDefault(eventName) {
     return eventName === "submit";
   }
 
+  function getRequestPolicy(element) {
+    const policy = element.getAttribute("py-policy") || config.requestPolicy;
+    if (policy === "drop" || policy === "latest-wins") {
+      return policy;
+    }
+    return config.requestPolicy;
+  }
+
   function processPyWebviewHtmxNodes(root = document) {
     if (!root || typeof root.querySelectorAll !== "function") {
       return;
     }
 
-    const elements = root.querySelectorAll("[py-call]");
+    const elements = [];
+    if (root.matches && root.matches("[py-call]")) {
+      elements.push(root);
+    }
+    elements.push(...root.querySelectorAll("[py-call]"));
 
     elements.forEach((element) => {
       if (element.getAttribute("data-pywebview-bound") === "true") {
@@ -127,9 +209,10 @@
           event.preventDefault();
         }
 
-        const params = parseParams(element);
-        const state = getRequestState(element);
-        if (config.requestPolicy === "drop" && state.inFlightCount > 0) {
+        const params = buildRequestParams(element, eventName, event);
+        const state = getRequestState(getRequestStateKey(element, targetSelector));
+        const requestPolicy = getRequestPolicy(element);
+        if (requestPolicy === "drop" && state.inFlightCount > 0) {
           triggerEvent(element, "py:ignored", { reason: "in-flight" });
           return;
         }
@@ -144,13 +227,16 @@
           requestId,
         });
 
-        waitTarget.classList.add("py-waiting");
+        addWaiting(waitTarget);
 
         try {
           const response = await invokePython(functionName, params);
           if (requestId !== state.lastIssued) {
             return;
           }
+          if (typeof response !== "string") {
+            throw new Error("PyWebview HTMX: Python API methods must return an HTML string");
+          }
 
           const target = targetSelector ? $(targetSelector) : element;
           if (!target) {
@@ -182,9 +268,7 @@
           triggerEvent(element, "py:error", { error, requestId });
         } finally {
           state.inFlightCount = Math.max(0, state.inFlightCount - 1);
-          if (state.inFlightCount === 0) {
-            waitTarget.classList.remove("py-waiting");
-          }
+          removeWaiting(waitTarget);
         }
       });
     });

pywebview_htmx-0.3.1/tests/js_runtime_behavior_harness.mjs

@@ -0,0 +1,369 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import vm from "node:vm";
+
+class DomEvent {
+  constructor(type, options = {}) {
+    this.type = type;
+    this.bubbles = Boolean(options.bubbles);
+    this.cancelable = Boolean(options.cancelable);
+    this.detail = options.detail || {};
+    this.defaultPrevented = false;
+    this.target = null;
+    this.currentTarget = null;
+  }
+
+  preventDefault() {
+    if (this.cancelable) {
+      this.defaultPrevented = true;
+    }
+  }
+}
+
+class DomCustomEvent extends DomEvent {}
+
+class ClassList {
+  constructor() {
+    this.tokens = new Set();
+  }
+
+  add(...tokens) {
+    tokens.forEach((token) => this.tokens.add(token));
+  }
+
+  remove(...tokens) {
+    tokens.forEach((token) => this.tokens.delete(token));
+  }
+
+  contains(token) {
+    return this.tokens.has(token);
+  }
+}
+
+class Element {
+  constructor(tagName, ownerDocument) {
+    this.tagName = tagName.toUpperCase();
+    this.ownerDocument = ownerDocument;
+    this.parentElement = null;
+    this.children = [];
+    this.attributes = new Map();
+    this.classList = new ClassList();
+    this.listeners = new Map();
+    this._innerHTML = "";
+    this.id = "";
+  }
+
+  append(...children) {
+    children.forEach((child) => {
+      child.parentElement = this;
+      child.ownerDocument = this.ownerDocument;
+      this.children.push(child);
+    });
+  }
+
+  setAttribute(name, value) {
+    const stringValue = String(value);
+    this.attributes.set(name, stringValue);
+    if (name === "id") {
+      this.id = stringValue;
+    }
+  }
+
+  getAttribute(name) {
+    return this.attributes.has(name) ? this.attributes.get(name) : null;
+  }
+
+  hasAttribute(name) {
+    return this.attributes.has(name);
+  }
+
+  matches(selector) {
+    return this.ownerDocument.matchesSelector(this, selector);
+  }
+
+  querySelector(selector) {
+    return this.ownerDocument.querySelectorFrom(selector, this);
+  }
+
+  querySelectorAll(selector) {
+    return this.ownerDocument.querySelectorAllFrom(selector, this);
+  }
+
+  addEventListener(type, listener) {
+    const listeners = this.listeners.get(type) || [];
+    listeners.push(listener);
+    this.listeners.set(type, listeners);
+  }
+
+  dispatchEvent(event) {
+    if (!event.target) {
+      event.target = this;
+    }
+    event.currentTarget = this;
+
+    for (const listener of this.listeners.get(event.type) || []) {
+      listener.call(this, event);
+    }
+
+    if (event.bubbles && this.parentElement) {
+      this.parentElement.dispatchEvent(event);
+    }
+    return !event.defaultPrevented;
+  }
+
+  set innerHTML(value) {
+    this._innerHTML = String(value);
+    this.children = [];
+  }
+
+  get innerHTML() {
+    return this._innerHTML;
+  }
+
+  set outerHTML(value) {
+    if (!this.parentElement) {
+      this.innerHTML = value;
+      return;
+    }
+
+    const replacement = this.ownerDocument.createElement("div");
+    replacement.innerHTML = value;
+    const index = this.parentElement.children.indexOf(this);
+    this.parentElement.children.splice(index, 1, replacement);
+    replacement.parentElement = this.parentElement;
+  }
+
+  insertAdjacentHTML(position, value) {
+    assert.equal(position, "beforeend");
+    this._innerHTML += String(value);
+  }
+}
+
+class Document {
+  constructor() {
+    this.listeners = new Map();
+    this.body = new Element("body", this);
+  }
+
+  createElement(tagName) {
+    return new Element(tagName, this);
+  }
+
+  addEventListener(type, listener) {
+    const listeners = this.listeners.get(type) || [];
+    listeners.push(listener);
+    this.listeners.set(type, listeners);
+  }
+
+  querySelector(selector) {
+    return this.querySelectorFrom(selector, this.body);
+  }
+
+  querySelectorAll(selector) {
+    return this.querySelectorAllFrom(selector, this.body);
+  }
+
+  querySelectorFrom(selector, root) {
+    return this.querySelectorAllFrom(selector, root)[0] || null;
+  }
+
+  querySelectorAllFrom(selector, root) {
+    this.validateSelector(selector);
+    const matches = [];
+
+    const visit = (node) => {
+      for (const child of node.children) {
+        if (this.matchesSelector(child, selector)) {
+          matches.push(child);
+        }
+        visit(child);
+      }
+    };
+
+    visit(root);
+    return matches;
+  }
+
+  matchesSelector(element, selector) {
+    this.validateSelector(selector);
+    if (selector === "[py-call]") {
+      return element.hasAttribute("py-call");
+    }
+    if (selector.startsWith("#")) {
+      return element.id === selector.slice(1);
+    }
+    throw new SyntaxError(`Unsupported selector in test harness: ${selector}`);
+  }
+
+  validateSelector(selector) {
+    if (!selector || selector === "[" || selector.includes("###")) {
+      throw new SyntaxError(`Invalid selector: ${selector}`);
+    }
+  }
+}
+
+function makeElement(document, tagName, attributes = {}) {
+  const element = document.createElement(tagName);
+  for (const [name, value] of Object.entries(attributes)) {
+    element.setAttribute(name, value);
+  }
+  return element;
+}
+
+function createHarness(runtimeSource) {
+  const document = new Document();
+  const warnings = [];
+  const context = {
+    clearTimeout,
+    console: {
+      ...console,
+      warn: (...args) => warnings.push(args.map(String).join(" ")),
+    },
+    CustomEvent: DomCustomEvent,
+    document,
+    Promise,
+    setTimeout,
+  };
+  context.window = context;
+  context.globalThis = context;
+
+  vm.createContext(context);
+  vm.runInContext(runtimeSource, context);
+
+  context.pywebviewHtmx.config.settleDelay = 0;
+  context.pywebviewHtmx.config.swapDelay = 0;
+
+  return { document, warnings, window: context };
+}
+
+async function flushAsyncWork() {
+  await Promise.resolve();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  await Promise.resolve();
+}
+
+function click(element) {
+  element.dispatchEvent(new DomEvent("click", { bubbles: true, cancelable: true }));
+}
+
+async function testInvalidWaitSelectorFallsBackAndDoesNotAbort(runtimeSource) {
+  const { document, warnings, window } = createHarness(runtimeSource);
+  const result = makeElement(document, "div", { id: "result" });
+  const badWait = makeElement(document, "button", {
+    "py-call": "load",
+    "py-target": "#result",
+    "py-wait": "[",
+  });
+  const laterButton = makeElement(document, "button", { "py-call": "later" });
+  document.body.append(badWait, result, laterButton);
+
+  let resolveLoad;
+  window.pywebview = {
+    api: {
+      load: () => new Promise((resolve) => {
+        resolveLoad = resolve;
+      }),
+      later: () => "<p>later</p>",
+    },
+  };
+
+  window.pywebviewHtmx.process(document.body);
+  assert.equal(badWait.getAttribute("data-pywebview-bound"), "true");
+  assert.equal(laterButton.getAttribute("data-pywebview-bound"), "true");
+  assert.ok(warnings.some((warning) => warning.includes("invalid selector")));
+
+  click(badWait);
+  assert.equal(badWait.classList.contains("py-waiting"), true);
+
+  resolveLoad("<p>loaded</p>");
+  await flushAsyncWork();
+
+  assert.equal(result.innerHTML, "<p>loaded</p>");
+  assert.equal(badWait.classList.contains("py-waiting"), false);
+}
+
+async function testLatestWinsIsSharedByTarget(runtimeSource) {
+  const { document, window } = createHarness(runtimeSource);
+  const result = makeElement(document, "div", { id: "race-result" });
+  const wait = makeElement(document, "span", { id: "race-status" });
+  const slow = makeElement(document, "button", {
+    "py-call": "long_task",
+    "py-target": "#race-result",
+    "py-wait": "#race-status",
+  });
+  const fast = makeElement(document, "button", {
+    "py-call": "long_task",
+    "py-target": "#race-result",
+    "py-wait": "#race-status",
+  });
+  document.body.append(slow, fast, wait, result);
+
+  const requests = [];
+  window.pywebview = {
+    api: {
+      long_task: () => new Promise((resolve) => {
+        requests.push(resolve);
+      }),
+    },
+  };
+
+  window.pywebviewHtmx.process(document.body);
+  click(slow);
+  click(fast);
+
+  assert.equal(requests.length, 2);
+  assert.equal(wait.classList.contains("py-waiting"), true);
+
+  requests[1]("<p>fast</p>");
+  await flushAsyncWork();
+
+  assert.equal(result.innerHTML, "<p>fast</p>");
+  assert.equal(wait.classList.contains("py-waiting"), true);
+
+  requests[0]("<p>slow</p>");
+  await flushAsyncWork();
+
+  assert.equal(result.innerHTML, "<p>fast</p>");
+  assert.equal(wait.classList.contains("py-waiting"), false);
+}
+
+async function testDropPolicyIsSharedByTarget(runtimeSource) {
+  const { document, window } = createHarness(runtimeSource);
+  const result = makeElement(document, "div", { id: "drop-result" });
+  const first = makeElement(document, "button", {
+    "py-call": "long_task",
+    "py-policy": "drop",
+    "py-target": "#drop-result",
+  });
+  const second = makeElement(document, "button", {
+    "py-call": "long_task",
+    "py-policy": "drop",
+    "py-target": "#drop-result",
+  });
+  document.body.append(first, second, result);
+
+  const requests = [];
+  window.pywebview = {
+    api: {
+      long_task: () => new Promise((resolve) => {
+        requests.push(resolve);
+      }),
+    },
+  };
+
+  window.pywebviewHtmx.process(document.body);
+  click(first);
+  click(second);
+
+  assert.equal(requests.length, 1);
+  requests[0]("<p>first</p>");
+  await flushAsyncWork();
+  assert.equal(result.innerHTML, "<p>first</p>");
+}
+
+const runtimePath = process.argv[2];
+const runtimeSource = fs.readFileSync(runtimePath, "utf8");
+
+await testInvalidWaitSelectorFallsBackAndDoesNotAbort(runtimeSource);
+await testLatestWinsIsSharedByTarget(runtimeSource);
+await testDropPolicyIsSharedByTarget(runtimeSource);

pywebview_htmx-0.3.1/tests/test_js_contract_ergonomics.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import pytest
+
+TESTED_BEHAVIOR_IDS = set(range(101, 114))
+
+
+def _assert_fragments_present(js_compact: str, fragments: tuple[str, ...]) -> None:
+    for fragment in fragments:
+        assert fragment in js_compact
+
+
+JS_BEHAVIOR_FRAGMENTS: list[tuple[int, tuple[str, ...]]] = [
+    (
+        101,
+        (
+            "function mergeParamValue(target, key, value)",
+            "if (Object.prototype.hasOwnProperty.call(target, key))",
+        ),
+    ),
+    (
+        102,
+        (
+            "function serializeForm(form, event)",
+            "const formData = new FormData(form);",
+        ),
+    ),
+    (
+        103,
+        (
+            'const submitter = event && "submitter" in event ? event.submitter : null;',
+            "submitter.name",
+        ),
+    ),
+    (
+        104,
+        (
+            "value instanceof File",
+            (
+                'console.warn("PyWebview HTMX: file inputs are not supported '
+                'in data-py-params"'
+            ),
+        ),
+    ),
+    (
+        105,
+        (
+            "function buildRequestParams(element, eventName, event)",
+            'if (element.tagName !== "FORM" || eventName !== "submit")',
+            "return { ...params, ...serializeForm(element, event) };",
+        ),
+    ),
+    (
+        106,
+        (
+            "const elements = [];",
+            'if (root.matches && root.matches("[py-call]"))',
+            "elements.push(root);",
+            'elements.push(...root.querySelectorAll("[py-call]"));',
+        ),
+    ),
+    (
+        107,
+        (
+            "function getRequestPolicy(element)",
+            'const policy = element.getAttribute("py-policy") || config.requestPolicy;',
+        ),
+    ),
+    (
+        108,
+        (
+            'policy === "drop" || policy === "latest-wins"',
+            "return config.requestPolicy;",
+        ),
+    ),
+    (
+        109,
+        (
+            "const requestPolicy = getRequestPolicy(element);",
+            'if (requestPolicy === "drop" && state.inFlightCount > 0)',
+        ),
+    ),
+    (
+        110,
+        (
+            "const params = buildRequestParams(element, eventName, event);",
+        ),
+    ),
+    (
+        111,
+        (
+            'if (typeof response !== "string") {',
+            (
+                'throw new Error("PyWebview HTMX: Python API methods must return '
+                'an HTML string")'
+            ),
+        ),
+    ),
+    (
+        112,
+        (
+            'triggerEvent(element, "py:error", { error, requestId });',
+        ),
+    ),
+    (
+        113,
+        (
+            'element.getAttribute("py-policy")',
+        ),
+    ),
+]
+
+
+@pytest.mark.parametrize(
+    ("behavior_id", "fragments"),
+    JS_BEHAVIOR_FRAGMENTS,
+    ids=[f"B{behavior_id}" for behavior_id, _ in JS_BEHAVIOR_FRAGMENTS],
+)
+def test_js_ergonomic_contract_fragments(
+    behavior_id: int,
+    fragments: tuple[str, ...],
+    js_compact: str,
+) -> None:
+    _ = behavior_id
+    _assert_fragments_present(js_compact, fragments)

{pywebview_htmx-0.2.1 → pywebview_htmx-0.3.1}/tests/test_js_contract_request_and_swap.py

@@ -20,12 +20,25 @@ JS_BEHAVIOR_FRAGMENTS: list[tuple[int, tuple[str, ...]]] = [
             "event.preventDefault();",
         ),
     ),
-    (74, ("let state = requestState.get(element);", "if (!state) {")),
+    (
+        74,
+        (
+            "function getRequestState(key)",
+            "let state = requestState.get(key);",
+            "requestState.set(key, state);",
+        ),
+    ),
     (75, ("lastIssued: 0", "state.lastIssued = requestId;")),
     (76, ("inFlightCount: 0", "state.inFlightCount += 1;")),
-    (77, ('config.requestPolicy === "drop"', 'triggerEvent(element, "py:ignored"')),
+    (77, ('requestPolicy === "drop"', 'triggerEvent(element, "py:ignored"')),
     (78, ('triggerEvent(element, "py:trigger"', "requestId,")),
-    (79, ('waitTarget.classList.add("py-waiting")',)),
+    (
+        79,
+        (
+            "function addWaiting(waitTarget)",
+            'waitTarget.classList.add("py-waiting")',
+        ),
+    ),
     (80, ("if (requestId !== state.lastIssued) { return; }",)),
     (81, ("const target = targetSelector ? $(targetSelector) : element;",)),
     (82, (" : element;",)),
@@ -50,7 +63,7 @@ JS_BEHAVIOR_FRAGMENTS: list[tuple[int, tuple[str, ...]]] = [
     (
         94,
         (
-            "if (state.inFlightCount === 0)",
+            "function removeWaiting(waitTarget)",
             'waitTarget.classList.remove("py-waiting")',
         ),
     ),

pywebview_htmx-0.3.1/tests/test_js_runtime_behavior.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+HARNESS = REPO_ROOT / "tests/js_runtime_behavior_harness.mjs"
+RUNTIME = REPO_ROOT / "src/pywebview_htmx/static/runtime.js"
+
+
+def test_runtime_behaviors_execute_in_dom_harness() -> None:
+    node = shutil.which("node")
+    if node is None:
+        pytest.skip("Node.js is required for JavaScript runtime behavior tests")
+
+    result = subprocess.run(
+        [node, str(HARNESS), str(RUNTIME)],
+        capture_output=True,
+        check=False,
+        text=True,
+    )
+
+    assert result.returncode == 0, result.stdout + result.stderr

pywebview_htmx-0.3.1/tests/test_python_params_attr.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from pywebview_htmx import encode_params_attr
+
+
+def test_encode_params_attr_returns_json_string() -> None:
+    encoded = encode_params_attr({"count": 3, "enabled": True})
+    assert encoded == "{"count": 3, "enabled": true}"
+
+
+def test_encode_params_attr_escapes_quotes_and_tags() -> None:
+    encoded = encode_params_attr({"message": '"hi" <b>unsafe</b>'})
+    assert "\\&quot;hi\\&quot;" in encoded
+    assert "&lt;b&gt;unsafe&lt;/b&gt;" in encoded
+
+
+def test_encode_params_attr_is_exported_from_package() -> None:
+    encoded = encode_params_attr({"name": "pywebview-htmx"})
+    assert isinstance(encoded, str)

pywebview_htmx-0.3.1/tests/test_repo_legibility.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+REQUIRED_DOCS = [
+    "AGENTS.md",
+    "docs/index.md",
+    "docs/architecture.md",
+    "docs/development.md",
+    "docs/releasing.md",
+]
+AGENT_REQUIRED_ROUTES = [
+    "README.md",
+    "docs/index.md",
+    "src/pywebview_htmx/runtime.py",
+    "src/pywebview_htmx/static/runtime.js",
+    "app.py",
+    "pyproject.toml",
+    "docs/releasing.md",
+    "tests/",
+    "skills/use-pywebview-htmx/",
+]
+LOCAL_MARKDOWN_LINK_RE = re.compile(r"(?<!!)\[[^\]]+\]\(([^)]+)\)")
+
+
+def _read_repo_file(path: str) -> str:
+    return (REPO_ROOT / path).read_text(encoding="utf-8")
+
+
+def _iter_local_links(markdown_path: Path) -> list[str]:
+    links: list[str] = []
+    for raw_link in LOCAL_MARKDOWN_LINK_RE.findall(
+        markdown_path.read_text(encoding="utf-8"),
+    ):
+        target = raw_link.split("#", 1)[0].strip()
+        if not target or re.match(r"^[a-z][a-z0-9+.-]*:", target):
+            continue
+        links.append(target)
+    return links
+
+
+def test_required_agent_legibility_docs_exist() -> None:
+    missing = [path for path in REQUIRED_DOCS if not (REPO_ROOT / path).exists()]
+    assert not missing, f"Missing agent-legibility docs: {missing}"
+
+
+def test_new_docs_have_resolvable_local_markdown_links() -> None:
+    checked_paths = [REPO_ROOT / path for path in REQUIRED_DOCS]
+    broken_links: list[str] = []
+
+    for markdown_path in checked_paths:
+        for target in _iter_local_links(markdown_path):
+            resolved = (markdown_path.parent / target).resolve()
+            link_description = f"{markdown_path.relative_to(REPO_ROOT)} -> {target}"
+            try:
+                resolved.relative_to(REPO_ROOT)
+            except ValueError:
+                broken_links.append(link_description)
+                continue
+            if not resolved.exists():
+                broken_links.append(link_description)
+
+    assert not broken_links, f"Broken local Markdown links: {broken_links}"
+
+
+def test_agents_md_routes_to_core_repo_surfaces() -> None:
+    agents_md = _read_repo_file("AGENTS.md")
+    missing_routes = [
+        route for route in AGENT_REQUIRED_ROUTES if route not in agents_md
+    ]
+    assert not missing_routes, f"AGENTS.md is missing route(s): {missing_routes}"
+
+
+def test_development_guidance_captures_package_policy() -> None:
+    combined_guidance = "\n".join(
+        _read_repo_file(path) for path in ("AGENTS.md", "docs/development.md")
+    ).lower()
+
+    required_fragments = [
+        "pdm install",
+        "pdm run lint",
+        "pdm run test",
+        "pdm run python app.py",
+        "do not use pip to add",
+        ">=",
+        "latest version",
+    ]
+    missing_fragments = [
+        fragment for fragment in required_fragments if fragment not in combined_guidance
+    ]
+    assert not missing_fragments, (
+        "Development guidance is missing durable instruction(s): "
+        f"{missing_fragments}"
+    )
+
+
+def test_release_guidance_captures_tag_first_release_notes_flow() -> None:
+    release_guidance = _read_repo_file("docs/releasing.md")
+
+    required_fragments = [
+        "release-notes-scribe",
+        "Draft Release Notes",
+        "git tag",
+        "git push origin",
+        ".github/workflows/draft-release-notes.yml",
+        ".github/workflows/python-publish.yml",
+        "PyPI",
+    ]
+    missing_fragments = [
+        fragment for fragment in required_fragments if fragment not in release_guidance
+    ]
+
+    assert not missing_fragments, (
+        "Release guidance must preserve the tag-first release notes process. "
+        f"Missing: {missing_fragments}"
+    )
+
+
+def test_typed_classifier_has_pep_561_marker() -> None:
+    pyproject = _read_repo_file("pyproject.toml")
+    assert "Typing :: Typed" in pyproject
+    assert (REPO_ROOT / "src/pywebview_htmx/py.typed").is_file()