@vention/vention-skills 0.1.0

package/skills/vention-machine-logic/scripts/library-readme.py

@@ -0,0 +1,233 @@
+#!/usr/bin/env python3
+"""Print the published README of a Vention library at the exact version an application pins.
+
+The Vention libraries an application depends on ship their documentation as their package README:
+vention-storage, vention-state-machine and vention-communication on PyPI, @vention/machine-ui,
+@vention/machine-apps-components and @vention/machine-logic-ui-sdk on npm. Reading the pinned
+version's README beats recalling an API that moved between releases.
+
+A range is not a version: a README is printed only for an exact pin, and anything else is reported
+as unavailable rather than answered from the newest release.
+
+    python3 library-readme.py --from-app .
+    python3 library-readme.py --pypi vention-storage 0.6.48
+    python3 library-readme.py --npm @vention/machine-ui 5.0.38
+"""
+
+from __future__ import annotations
+
+import argparse
+import http.client
+import json
+import re
+import sys
+import tarfile
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import IO
+from urllib.parse import urlsplit
+
+PYPI_REGISTRY = "https://pypi.org"
+NPM_REGISTRY = "https://registry.npmjs.org"
+TIMEOUT = 20
+ALLOWED_SCHEMES = frozenset({"http", "https", "file"})
+
+PYPI_LIBRARIES = ("vention-state-machine", "vention-storage", "vention-communication")
+NPM_LIBRARIES = ("@vention/machine-ui", "@vention/machine-apps-components", "@vention/machine-logic-ui-sdk")
+
+REQUIREMENT_PATTERN = re.compile(
+    r"^\s*(?P<name>[A-Za-z0-9][A-Za-z0-9._-]*)\s*(?:\[[^\]]*\])?\s*(?P<operator>[=<>!~]+)?\s*(?P<version>[^\s;#,]*)"
+)
+EXACT_VERSION_PATTERN = re.compile(r"^\d+\.\d+\.\d+[\w.+-]*$")
+NAME_SEPARATOR_PATTERN = re.compile(r"[-_.]+")
+PACKAGE_README = "package/readme.md"
+
+
+class Unavailable(Exception):
+    """A README that cannot be produced, carrying the reason a reader needs."""
+
+
+@dataclass(frozen=True)
+class Pin:
+    name: str
+    version: str
+    registry: str
+
+
+def open_url(url: str) -> IO[bytes]:
+    scheme = urlsplit(url).scheme
+    if scheme not in ALLOWED_SCHEMES:
+        raise Unavailable(f"unsupported url scheme {scheme}")
+    response: IO[bytes] = urllib.request.urlopen(url, timeout=TIMEOUT)  # noqa: S310  # nosemgrep: python.lang.security.audit.dynamic-urllib-use-detected.dynamic-urllib-use-detected
+
+    return response
+
+
+def fetch_bytes(url: str) -> bytes:
+    try:
+        with open_url(url) as response:
+            return response.read()
+    except (OSError, http.client.HTTPException, ValueError) as error:
+        raise Unavailable(f"cannot reach {url}: {error}") from error
+
+
+def fetch_json(url: str) -> dict[str, object]:
+    try:
+        payload = json.loads(fetch_bytes(url))
+    except json.JSONDecodeError as error:
+        raise Unavailable(f"{url} did not answer with JSON: {error}") from error
+    if not isinstance(payload, dict):
+        raise Unavailable(f"{url} did not answer with a JSON object")
+    return payload
+
+
+def pypi_readme(registry: str, name: str, version: str) -> str:
+    url = f"{registry}/pypi/{name}/{version}/json"
+    info = fetch_json(url).get("info")
+    description = info.get("description") if isinstance(info, dict) else None
+    if not isinstance(description, str) or description.strip() == "":
+        raise Unavailable(f"{name} {version} publishes no description on PyPI")
+    return description
+
+
+def npm_readme(registry: str, name: str, version: str) -> str:
+    url = f"{registry}/{name.replace('/', '%2F')}"
+    releases = fetch_json(url).get("versions")
+    release = releases.get(version) if isinstance(releases, dict) else None
+    if not isinstance(release, dict):
+        raise Unavailable(f"{url} publishes no {name}@{version}")
+    distribution = release.get("dist")
+    tarball = distribution.get("tarball") if isinstance(distribution, dict) else None
+    if not isinstance(tarball, str):
+        raise Unavailable(f"{name}@{version} publishes no tarball")
+    return readme_from_tarball(tarball)
+
+
+def readme_from_tarball(url: str) -> str:
+    """The README from inside a published npm tarball, streamed rather than written to disk."""
+    try:
+        with open_url(url) as response:
+            with tarfile.open(fileobj=response, mode="r|gz") as archive:
+                for member in archive:
+                    if not member.isfile() or member.name.lower().removeprefix("./") != PACKAGE_README:
+                        continue
+                    content = archive.extractfile(member)
+                    if content is not None:
+                        readme = content.read().decode("utf-8", errors="replace")
+                        if readme.strip() == "":
+                            raise Unavailable(f"{url} publishes an empty README")
+                        return readme
+    except (OSError, http.client.HTTPException, ValueError, tarfile.TarError) as error:
+        raise Unavailable(f"cannot read {url}: {error}") from error
+    raise Unavailable(f"{url} carries no {PACKAGE_README}")
+
+
+def normalised(name: str) -> str:
+    """PEP 503 normalisation: vention_storage, Vention.Storage and vention-storage are one project."""
+    return NAME_SEPARATOR_PATTERN.sub("-", name).lower()
+
+
+def pypi_pins(app_directory: Path) -> tuple[list[Pin], list[str]]:
+    """Exact pins of the Vention PyPI libraries, and a note for each one left unpinned."""
+    path = app_directory / "requirements.txt"
+    if not path.is_file():
+        return [], []
+    pins: list[Pin] = []
+    notes: list[str] = []
+    for line in path.read_text(encoding="utf-8-sig").splitlines():
+        found = REQUIREMENT_PATTERN.match(line)
+        if not found or normalised(found.group("name")) not in PYPI_LIBRARIES:
+            continue
+        name, operator, version = found.group("name"), found.group("operator"), found.group("version")
+        if operator == "==" and version:
+            pins.append(Pin(normalised(name), version, "pypi"))
+        else:
+            notes.append(f"{name} in {path} is not pinned to an exact version")
+    return pins, notes
+
+
+def npm_pins(app_directory: Path) -> tuple[list[Pin], list[str]]:
+    """Exact versions of the Vention npm libraries, and a note for each one declared as a range.
+
+    The HMI manifest lives in customui/, not in the ui/ folder beside it, which holds only the
+    built bundle. mm-execution-engine owns that layout as MachineCodeDirectoryManager's
+    CUSTOMUI_FOLDER_NAME, so check there before changing this path.
+    """
+    path = app_directory / "customui" / "package.json"
+    if not path.is_file():
+        return [], []
+    try:
+        manifest = json.loads(path.read_text(encoding="utf-8-sig"))
+    except json.JSONDecodeError as error:
+        return [], [f"{path} is not valid JSON: {error}"]
+    declared = {**manifest.get("devDependencies", {}), **manifest.get("dependencies", {})}
+    pins: list[Pin] = []
+    notes: list[str] = []
+    for name in NPM_LIBRARIES:
+        version = declared.get(name)
+        if not isinstance(version, str):
+            continue
+        if EXACT_VERSION_PATTERN.match(version):
+            pins.append(Pin(name, version, "npm"))
+        else:
+            notes.append(f"{name} in {path} is declared as {version}, which is a range, not a version")
+    return pins, notes
+
+
+def read_pin(pin: Pin, pypi_registry: str, npm_registry: str) -> str:
+    if pin.registry == "pypi":
+        return pypi_readme(pypi_registry, pin.name, pin.version)
+    return npm_readme(npm_registry, pin.name, pin.version)
+
+
+def print_app_readmes(app_directory: Path, pypi_registry: str, npm_registry: str) -> int:
+    pypi_found, pypi_notes = pypi_pins(app_directory)
+    npm_found, npm_notes = npm_pins(app_directory)
+    notes = pypi_notes + npm_notes
+    printed = 0
+
+    for pin in pypi_found + npm_found:
+        try:
+            readme = read_pin(pin, pypi_registry, npm_registry)
+        except Unavailable as error:
+            notes.append(str(error))
+            continue
+        print(f"## {pin.name}@{pin.version}\n")
+        print(readme.strip())
+        print()
+        printed += 1
+
+    for note in notes:
+        print(f"unavailable: {note}", file=sys.stderr)
+    if printed == 0:
+        print(f"unavailable: no Vention library README could be read for {app_directory}", file=sys.stderr)
+        return 2
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    source = parser.add_mutually_exclusive_group(required=True)
+    source.add_argument("--from-app", metavar="DIR", help="read every Vention library pinned by an application directory")
+    source.add_argument("--pypi", nargs=2, metavar=("NAME", "VERSION"), help="one PyPI package at one version")
+    source.add_argument("--npm", nargs=2, metavar=("NAME", "VERSION"), help="one npm package at one version")
+    parser.add_argument("--pypi-registry-url", default=PYPI_REGISTRY, help=f"PyPI base URL (default: {PYPI_REGISTRY})")
+    parser.add_argument("--npm-registry-url", default=NPM_REGISTRY, help=f"npm registry base URL (default: {NPM_REGISTRY})")
+    arguments = parser.parse_args()
+
+    if arguments.from_app:
+        return print_app_readmes(Path(arguments.from_app), arguments.pypi_registry_url, arguments.npm_registry_url)
+
+    name, version = arguments.pypi or arguments.npm
+    registry = "pypi" if arguments.pypi else "npm"
+    try:
+        print(read_pin(Pin(name, version, registry), arguments.pypi_registry_url, arguments.npm_registry_url).strip())
+    except Unavailable as error:
+        print(f"unavailable: {error}", file=sys.stderr)
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/vention-machine-logic/scripts/vention-docs.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""Resolve the Vention documentation page for one machine-logic-sdk version.
+
+Ported from the delivery team's plugins/delivery-pipeline/pipeline/vention-docs.py in
+delivery-team-standards; this copy is now the canonical one.
+
+Three SDK majors are documented at once and an application pins one, so handing an author the wrong
+version's signatures produces confident code that compiles against nothing. docs.vention.com
+publishes llms.txt (an index of every page) and a .md twin of each page, but no search API, so the
+version is matched against index titles and the page is fetched live.
+
+Index entries carry a description after the closing parenthesis. Those descriptions are stale --
+the v3.1.x entry describes version 2.0.x -- so nothing here reads them. Titles only.
+
+A pinned version with no matching page fails loudly rather than serving a different version's page,
+and so does a fetched page whose body does not name the series its index title claims.
+
+    python3 vention-docs.py --version 3.1.0 --print-page
+    python3 vention-docs.py --from-requirements requirements.txt --print-url
+    python3 vention-docs.py --from-uv-lock uv.lock
+"""
+
+from __future__ import annotations
+
+import argparse
+import http.client
+import re
+import sys
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import IO, NoReturn
+from urllib.parse import urljoin, urlsplit
+
+INDEX_URL = "https://docs.vention.com/llms.txt"
+PACKAGE = "machine-logic-sdk"
+TIMEOUT = 20
+ALLOWED_SCHEMES = frozenset({"http", "https", "file"})
+
+ENTRY_PATTERN = re.compile(r"^- \[([^\]]+)\]\(([^)\s]+\.md)\)", re.MULTILINE)
+LOCK_PATTERN = re.compile(r'\[\[package\]\]\s*\nname = "machine-logic-sdk"\s*\nversion = "([^"]+)"')
+REQUIREMENT_PATTERN = re.compile(
+    r"^\s*machine[-_]logic[-_]sdk\s*(?:\[[^\]]*\])?\s*(?P<operator>[=<>!~]+)\s*(?P<version>[^\s;#,]+)",
+    re.IGNORECASE | re.MULTILINE,
+)
+EXACT_VERSION_PATTERN = re.compile(r"^\d+(\.\d+)+[\w.+-]*$")
+CATCH_ALL_PATTERN = re.compile(rf"^(?:{re.escape(PACKAGE)}\s+)?v(?P<bound>\d+(?:\.\d+)*)\s+and\s+lower\b", re.IGNORECASE)
+
+
+@dataclass(frozen=True)
+class Page:
+    title: str
+    url: str
+    series: str
+
+
+def unavailable(reason: str) -> NoReturn:
+    print(f"unavailable: {reason}", file=sys.stderr)
+    raise SystemExit(2)
+
+
+def open_url(url: str) -> IO[bytes]:
+    scheme = urlsplit(url).scheme
+    if scheme not in ALLOWED_SCHEMES:
+        unavailable(f"unsupported url scheme {scheme}")
+    response: IO[bytes] = urllib.request.urlopen(url, timeout=TIMEOUT)  # noqa: S310  # nosemgrep: python.lang.security.audit.dynamic-urllib-use-detected.dynamic-urllib-use-detected
+
+    return response
+
+
+def fetch(url: str) -> str:
+    try:
+        with open_url(url) as response:
+            return response.read().decode("utf-8", errors="replace")
+    except (OSError, http.client.HTTPException, ValueError) as error:
+        unavailable(f"cannot reach {url}: {error}")
+
+
+def version_from_requirements(path: Path) -> str:
+    if not path.is_file():
+        unavailable(f"no requirements file at {path}")
+    found = REQUIREMENT_PATTERN.search(path.read_text(encoding="utf-8-sig"))
+    if not found:
+        unavailable(f"{path} carries no machine-logic-sdk requirement")
+    operator, version = found.group("operator"), found.group("version")
+    if operator != "==":
+        unavailable(f"{path} allows machine-logic-sdk{operator}{version}, which is a range, not a version")
+    return version
+
+
+def version_from_uv_lock(path: Path) -> str:
+    if not path.is_file():
+        unavailable(f"no lock file at {path}")
+    found = LOCK_PATTERN.search(path.read_text(encoding="utf-8-sig"))
+    if not found:
+        unavailable(f"{path} does not resolve machine-logic-sdk")
+    return found.group(1)
+
+
+def index_entries(index_url: str) -> list[tuple[str, str]]:
+    """(title, absolute url) for every page the index lists, descriptions left unread."""
+    return [(title, urljoin(index_url, target)) for title, target in ENTRY_PATTERN.findall(fetch(index_url))]
+
+
+def release_order(version: str) -> tuple[int, ...]:
+    """Version components as numbers, so 1.13.3 sorts above 1.13.2 the way 'v1.13.3' does not."""
+    return tuple(int(part) for part in re.findall(r"\d+", version))
+
+
+def page_for_version(entries: list[tuple[str, str]], version: str) -> Page:
+    """The page titled for this version's minor series, or exit 2 saying none is published.
+
+    Matched on vMAJOR.MINOR, the grain the docs use (v3.1.x, v3.0.x) and the grain a pin gives. The
+    title has to start with it, so "Migration guide machine-logic-sdk v2.2.0 to v3.0.0" never
+    answers for 3.0.1. One title is a bound rather than a series -- "v1.13.2 and lower" -- and
+    answers for every version at or below it instead.
+    """
+    wanted = "v" + ".".join(version.split(".")[:2])
+    titled = re.compile(rf"(?:{re.escape(PACKAGE)}\s+)?{re.escape(wanted)}(?![0-9])", re.IGNORECASE)
+    for title, url in entries:
+        stripped = title.strip()
+        catch_all = CATCH_ALL_PATTERN.match(stripped)
+        if catch_all:
+            bound = catch_all.group("bound")
+            if release_order(version) <= release_order(bound):
+                return Page(stripped, url, "v" + ".".join(bound.split(".")[:2]))
+        elif titled.match(stripped):
+            return Page(stripped, url, wanted)
+    published = sorted({found.group(0) for title, _ in entries if (found := re.search(r"v\d+\.\d+", title))})
+    unavailable(
+        f"the docs publish no {PACKAGE} page for {wanted} (published: {', '.join(published) or 'none'}); "
+        f"refusing to answer from another version"
+    )
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    source = parser.add_mutually_exclusive_group(required=True)
+    source.add_argument("--version", help="the exact SDK version to document, e.g. 3.1.0")
+    source.add_argument("--from-requirements", metavar="PATH", help="read an exact machine-logic-sdk== pin from a requirements file")
+    source.add_argument("--from-uv-lock", metavar="PATH", help="read the resolved machine-logic-sdk version from a uv lock file")
+    parser.add_argument("--index-url", default=INDEX_URL, help=f"documentation index to read (default: {INDEX_URL})")
+    output = parser.add_mutually_exclusive_group()
+    output.add_argument("--print-url", action="store_true", help="print only the page URL")
+    output.add_argument("--print-page", action="store_true", help="fetch the page and print it verbatim")
+    arguments = parser.parse_args()
+
+    if arguments.from_requirements:
+        version = version_from_requirements(Path(arguments.from_requirements))
+    elif arguments.from_uv_lock:
+        version = version_from_uv_lock(Path(arguments.from_uv_lock))
+    else:
+        version = arguments.version
+    if not EXACT_VERSION_PATTERN.match(version):
+        unavailable(f"{version} is not an exact version")
+
+    page = page_for_version(index_entries(arguments.index_url), version)
+
+    if arguments.print_url:
+        print(page.url)
+        return 0
+
+    body = fetch(page.url)
+    if not re.search(rf"{re.escape(page.series)}(?![0-9])", body, re.IGNORECASE):
+        unavailable(f"{page.url} does not document {page.series}")
+
+    if arguments.print_page:
+        print(body, end="")
+    else:
+        print(f"{PACKAGE} {version} is documented by: {page.title}")
+        print(page.url)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/vention-machine-logic-hmi/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: vention-machine-logic-hmi
+description: Build or edit the custom operator HMI of a MachineLogic application, the React touch screen in customui/ that runs in MachineBuilder and on the MachineMotion pendant, wired to the application's Python process through vention-communication. Use when the user asks for an operator screen, a custom HMI or UI, a touch panel, start and stop buttons, live machine state on screen, or recipes an operator picks, for a Vention machine or inside a directory holding .machine-code-app-directory-info.json. Uses @vention/machine-ui, @vention/machine-apps-components and @vention/machine-logic-ui-sdk. Do not use for the no-code HMI Builder, or for the Python motion logic alone (that is vention-machine-logic).
+license: MIT
+metadata:
+  version: "0.1.0"
+  author: Vention
+---
+
+# Vention MachineLogic HMIs
+
+A custom HMI is a React app in `customui/` that an operator uses on a touch screen. It talks to one Python process, `server.py` served by uvicorn, which owns the machine and exposes an RPC surface through `vention-communication`. The HMI reaches that process only through the client generated from the proto the server emits. For the machine calls themselves (devices, moves, safety states), follow the `vention-machine-logic` skill.
+
+## Before you start
+
+1. Work only in a directory the Vention CLI has linked: `.machine-code-app-directory-info.json` is in its root. If it is missing, ask the user to run `vention pull` or `vention link` there. Never create the marker by hand.
+2. Read `.vention-design-configuration.json` for device names, character for character, as the `vention-machine-logic` skill says.
+3. If `customui/` is missing, copy `package.json`, `buf.gen.yaml`, `tsconfig.json` and `index.html` from `examples/indexing-station-hmi/customui/`, rename the package, then write `src/`.
+
+## The layout the engine expects
+
+| Path | What it is |
+| --- | --- |
+| `customui/` | The HMI source and its `package.json`. The engine runs `npm install`, then `npm run build`, in it. |
+| `ui/` | Build output only. The build script writes `../ui/index.html` and `../ui/assets/`. Never edit it or read versions from it. |
+| `project.json` | One process under `processes.onPlay`: `{ name, command, port }`. The command sets its own port. |
+| `requirements.txt` | Exact pins for `machine-logic-sdk`, `vention-communication`, `vention-state-machine`, `vention-storage` and `uvicorn`. |
+| `proto/app.proto` | Written by `app.finalize()` when `server.py` is imported. Commit it; never edit it. |
+| `customui/src/gen/` | The client `buf generate ../proto` writes before every build. Gitignored; never commit or edit it. |
+
+```json
+{ "processes": { "onPlay": [{ "name": "indexing-station", "command": "python3 -m uvicorn server:app --host 0.0.0.0 --port 8000", "port": 8000 }] } }
+```
+
+## The Python surface
+
+One `VentionApp` carries everything: the state machine bundle, the storage bundle, `@action` commands and `@stream` feeds. Register every plugin, then call `finalize()` last.
+
+```python
+bootstrap(database_url=f"sqlite:///{DATA_DIR / 'recipes.db'}")
+recipe_accessor = ModelAccessor(Recipe, "recipe")
+station = IndexingStation()  # a StateMachine subclass
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI) -> AsyncIterator[None]:
+    try:
+        station.machine = await asyncio.to_thread(Machine)
+    except Exception as error:
+        station.fault_message = f"cannot reach the controller: {error}"
+    await publish_status()
+    yield
+
+
+app = VentionApp(name="IndexingStation", emit_proto=True, proto_path="proto/app.proto", lifespan=lifespan)
+
+
+@action("Start")
+async def start(request: StartRequest) -> CommandResponse:
+    ...  # refuse unless connected and ready, load the recipe, then station.trigger(Triggers.run.name)
+
+
+app.register_rpc_plugin(build_state_machine_rpc_bundle(station, triggers=[Triggers.stop.name, BaseTriggers.RESET.value]))
+app.register_rpc_plugin(build_storage_rpc_bundle(accessors=[recipe_accessor], max_records_per_model=None))
+app.finalize()
+```
+
+- Create `Machine()` in the FastAPI `lifespan`, through `asyncio.to_thread`, never at import. Importing `server.py` must work with no machine attached: that is how the proto is emitted. When it fails, show the failure as a fault the operator can read.
+- `@action("Start")` names the RPC `Start`. Without the name the RPC takes the function's name as written.
+- The state machine bundle adds `GetState`, `GetHistory` and one `Trigger_<Name>` per trigger you list. List only the triggers the operator may fire.
+- The storage bundle adds `Recipe_ListRecords`, `Recipe_CreateRecord`, `Recipe_UpdateRecord` and `Recipe_DeleteRecord` among others, named after the accessor. `max_records_per_model=None` lifts its default cap of 5 records.
+- The storage bundle also adds `Database_*` RPCs, including a whole-database restore. Never expose them to operators.
+- Give every storage model field a zero-value default (`dwell_ms: int = 0`). The client leaves zero values out of the JSON it sends, and a field with no default then fails as NULL.
+- Every storage write takes a non-empty `actor`, the name recorded in the audit log.
+
+### Running the cycle
+
+Blocking SDK calls, cancellation and the shutdown path follow the `vention-machine-logic` skill's "Doing several things at once". What the server adds:
+
+- Start the cycle from an `@on_enter_state` handler with `self.spawn(...)`.
+- Never publish a stream or fire a trigger from inside a worker thread. Return to the loop first.
+- Make one thread call per move and check a stop flag between them, so Stop finishes the move in progress. Release what the cycle holds (clamp open, outputs off) before you fire `BaseTriggers.TO_FAULT` or re-raise.
+
+## Live data is a stream
+
+Anything the HMI shows live comes from a Connect server stream. Never poll `GetState` or a list RPC on a timer.
+
+```python
+@stream(name="Status", payload=StationStatus, replay=True, queue_maxsize=1, policy="latest")
+async def publish_status() -> StationStatus:
+    return station.snapshot()
+
+
+@stream(name="Events", payload=Event, replay=False, queue_maxsize=100, policy="fifo")
+async def publish_event(level: str, message: str, detail: str) -> Event:
+    return Event(timestamp=datetime.now(timezone.utc).isoformat(), level=level, message=message, detail=detail)
+```
+
+Awaiting the function publishes its result. Publish status from an `@on_state_change` method on the state machine (`self.spawn(publish_status())`) and after every count or fault change. `replay=True` hands a new subscriber the last status at once; the event log uses `replay=False` so a reconnect does not repeat old events. Also republish status every `STATUS_HEARTBEAT_S` from a task the `lifespan` starts, as the example does: a connection can hang without closing, and the HMI only notices when the heartbeat stops.
+
+## The generated client
+
+`npm run build` regenerates `src/gen/` from `proto/app.proto` first (the `prebuild` script), so the engine always builds against the committed proto. Re-emit the proto after every change to the Python surface, then run `npm run build` to refresh the client. RPC names become camelCase methods (`Trigger_Stop` is `client.trigger_Stop`), and snake_case fields become camelCase (`recipe_id` is `recipeId`).
+
+```ts
+import { createClient } from "@connectrpc/connect"
+import { createConnectTransport } from "@connectrpc/connect-web"
+import { getMachineCodeProcessHttpUrl } from "@vention/machine-logic-ui-sdk"
+import { IndexingStationService } from "./gen/app_pb"
+
+// Must match the process name in project.json.
+const PROCESS_NAME = "indexing-station"
+
+export const client = createClient(
+  IndexingStationService,
+  createConnectTransport({ baseUrl: `${getMachineCodeProcessHttpUrl(PROCESS_NAME)}/rpc`, useBinaryFormat: false })
+)
+
+export const openStatus = (signal: AbortSignal) => client.status({}, { signal })
+export const openEvents = (signal: AbortSignal) => client.events({}, { signal })
+```
+
+Copy `examples/indexing-station-hmi/customui/src/use-stream.ts` for the stream hook. Pass it a stable opener such as `openStatus`: it aborts on unmount, reopens a dropped stream with backoff, and returns `{ value, connected }` so the page can show Disconnected. Pass `STATUS_STALL_MS`, three heartbeats, as the second argument for the status stream only; a stream with no heartbeat, such as events, would look stalled whenever nothing happens. No `fetch`, `XMLHttpRequest`, `EventSource` or `WebSocket` anywhere in `customui/src`.
+
+## Which component for which job
+
+| Job | Use |
+| --- | --- |
+| Screen shell, from `@vention/machine-apps-components` | `StatusTopBar`, `NavigationBar`, `LogsPanel`, `SettingsPage`, `I18nProvider` when the screen is translated |
+| Actions, from `@vention/machine-ui` | `VentionButton`, `VentionIconButton` |
+| Inputs | `VentionSelect`, `VentionTextInput`, `VentionStepper`, `VentionSwitch`, `VentionCheckbox`, `VentionSlider` |
+| State and feedback | `VentionStatusIndicator`, `VentionAlert`, `VentionBanner`, `VentionProgressBar` |
+| Overlays and navigation | `VentionModal`, `VentionDrawer`, `VentionTabs`, `VentionSteps` |
+| Touch and the process URL, from `@vention/machine-logic-ui-sdk` | `VirtualKeyboard`, `isTouchScreenDevice`, `getMachineCodeProcessHttpUrl` |
+
+Layout comes from MUI `Box`, `Stack` and `Typography` only, with `ThemeProvider` at the root. Every other MUI control has a Vention equivalent above; use it. Route with `HashRouter`: the bundle is served under a prefix you cannot know, at `.../index.html`.
+
+Read each library's README at the version `customui/package.json` pins before using a prop you have not seen in the example. The script ships in the `vention-machine-logic` skill, which must be installed beside this one:
+
+```bash
+python3 ../vention-machine-logic/scripts/library-readme.py --from-app <application directory>
+```
+
+The machine-apps-components README is behind its code: `NavigationBar` takes `NavigationBar.Item` children, not `navigationItems`, and a `LogsPanel` fetcher returns `hasMorePages`, not `hasMore`. When a README and `npx tsc --noEmit` disagree, the compiler is right.
+
+## Design rules
+
+- Wrap the app in `machineUiHmiTheme`.
+- Set `size="x-large"` or `size="xx-large"` on every control that takes a size. The default `"small"` is 24 px, below the 44 px touch minimum.
+- Text uses the `heading*` and `paragraph*` typography variants: `heading24SemiBold` for what the operator must see from a distance, such as the cycle count, `heading18SemiBold` for labels, `paragraph18Medium` for detail. The theme marks `hmiText*` deprecated.
+- Leave at least 16 px between adjacent touch targets and 24 px between buttons with opposite effects, such as Save and Delete. `theme.spacing` is a lookup table, not a multiplier: `gap: 2` is 8 px, `gap: 4` is 16 px, `gap: 5` is 24 px.
+- Give each state one color from `COLORS` and always a text label next to it: green for running, amber for stopping or a warning, red for a fault, slate for ready, idle or disconnected.
+- Nothing an operator needs lives only in a tooltip. No drag, swipe or multi-touch gestures: every action is a tap.
+- Render `VirtualKeyboard` when `isTouchScreenDevice()` is true, so text inputs work on the pendant.
+- Confirm anything that starts motion or deletes data in a `VentionModal` with `isTouchDevice`, and say in it what will move.
+- `VentionButton` variants are `filled-brand`, `filled`, `outline`, `text-only`, `shaded` and `destructive`. MUI's `contained` and `outlined` do not exist on it, and neither does a `color` prop.
+- Start is green and Stop is red, both set through the `StatusTopBar` button's `backgroundColor`, `backgroundColorHover` and `textColor`.
+- A `LogsPanel` row cuts `message` and `description` to one line and shows the rest only on hover. Keep `message` to a few words saying what happened, put the cause and what to do next in `description`, and open the whole entry in a `VentionModal` from `onLogClick`.
+
+## Validate before you push
+
+1. In the application directory, with the `requirements.txt` packages installed locally: `python3 -c "import server"` to re-emit `proto/app.proto`, and commit it if `git status` shows a change.
+2. In `customui/`: `npm install`, `npm run build`, then `npx tsc --noEmit`, and check that `ui/index.html` exists and loads its script from `./assets/`, a relative path.
+3. `vention push`, then open the HMI from the MachineLogic tab in MachineBuilder and run it on the digital twin before any hardware run.
+4. Read `vention logs` when a command fails; the server's errors land there.
+
+## Safety
+
+The HMI drives physical machinery that can injure someone.
+
+- Start never fires on page load, on reconnect, or from a stream message. Only an operator's tap, confirmed in a modal, starts motion.
+- Start and Stop live in the `StatusTopBar`, so they are on every page. Do not repeat them on a page. Raise the bar above `theme.zIndex.modal`, as the example's `app.tsx` does, or an open `VentionModal` covers Stop.
+- Stop stays enabled unless the station is known to be ready. That includes while the stream is disconnected: a dropped stream may hide a moving machine. Every other command is disabled while disconnected.
+- Send Start with a `timeoutMs` and an abort signal, and abort it when the stream drops. A Start the operator can no longer see must not land later; say it was not confirmed and to check the station.
+- The HMI never offers a way around an emergency stop, safety interlock, light curtain or guard, not even a hidden one for testing.
+- The confirmation for anything that starts motion says what will move. The button itself can just say Start.
+
+## Complete example
+
+`examples/indexing-station-hmi/` indexes a part on a conveyor, clamps it, proves the clamp closed, dwells and releases, for the cycle count of the recipe the operator picked.
+
+- `server.py`: the state machine, the streams, the Start action, both bundles, and `Machine()` in the `lifespan`.
+- `models.py`: the `Recipe` storage model, every field with a zero default.
+- `project.json`, `requirements.txt`: the one process and the exact pins.
+- `proto/app.proto`: what `finalize()` emits.
+- `customui/package.json`, `customui/buf.gen.yaml`, `customui/tsconfig.json`, `customui/index.html`: the scaffold to copy.
+- `customui/src/client.ts`, `customui/src/use-stream.ts`: the generated client and the stream hook.
+- `customui/src/station.ts`: state labels and colors, and when Start and Stop are enabled.
+- `customui/src/app.tsx`, `customui/src/main.tsx`: the shell with Start, Stop and the Start confirmation, the theme, the router and the keyboard.
+- `customui/src/pages/`: the Run, Recipes and Logs pages.
+
+## Common mistakes
+
+- Polling for live state instead of a stream.
+- A raw `fetch` to `/rpc`, or any request that skips the generated client.
+- Editing or committing `src/gen/`, or forgetting to re-emit `proto/app.proto` after a Python change.
+- Dropping `chmod -R g+w` from the build scripts. The engine deletes the application as another user, and it cannot remove files the build left group-read-only.
+- A stream named after its payload model: `rpc Status` returning `Status` fails in buf. Name the payload `StationStatus`.
+- A storage field with no zero default, or a storage write with no `actor`.
+- A process name in `client.ts` that differs from `project.json`.
+- `Machine()` at import, or a retry loop around it in the same process.
+- A blocking SDK call on the event loop, or a publish or trigger from inside `asyncio.to_thread`.
+- Trusting task cancellation to stop motion already running in a thread.
+- MUI `Button` where `VentionButton` exists, or MUI variants such as `contained` on a Vention button.
+- `size` left at the `"small"` default on a touch screen.
+- `BrowserRouter`, whose routes miss under `.../index.html`.
+- Reading versions from `ui/package.json`; the manifest is `customui/package.json`.
+- Disabling Stop whenever the stream drops.
+- `--legacy-peer-deps` to get past a peer dependency conflict. Pin versions whose peers agree, as the example does.
+- A Start still in flight after the connection drops.

package/skills/vention-machine-logic-hmi/examples/indexing-station-hmi/customui/buf.gen.yaml

@@ -0,0 +1,5 @@
+version: v2
+plugins:
+  - local: protoc-gen-es
+    opt: target=ts
+    out: src/gen

package/skills/vention-machine-logic-hmi/examples/indexing-station-hmi/customui/index.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Indexing station</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>