demo-files

name	demo-files
description	How to run and verify the `*_demo.html` files scattered across packages (e.g. packages/frontend/navi/src/control/demos/). Use when the user explicitly asks to load a demo in a browser / Playwright to check it works — not proactively (see .agents/instructions.md's "never verify on your own initiative" constraint).

Overview

Many packages (especially @jsenv/navi) ship standalone *_demo.html files next to the source they demonstrate, e.g. packages/frontend/navi/src/control/demos/00_field_demo.html. These are plain HTML files loaded through jsenv's dev server — no build step, no bundler config to write.

1. The dev server

Started with:

node scripts/dev/dev.mjs

It serves the whole repo (sourceDirectoryUrl = repo root) on port 3456.

Check before starting one — it's often already running in the background:

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3456/ --max-time 2

A 200 means it's already up; don't start a second instance (the port is fixed, a second dev.mjs will just fail to bind).

2. Opening a demo

URLs mirror the repo path directly under the server root:

http://127.0.0.1:3456/packages/frontend/navi/src/control/demos/00_field_demo.html

No routing/registration needed — any .html file under the repo is reachable this way as soon as it exists on disk.

3. Verifying with Playwright

playwright is a repo-root dependency (see other *.test.mjs files under packages/*/tests/ for the same pattern: import { chromium } from "playwright"). To actually drive a demo instead of just reading the code:

import { chromium } from "playwright";

const browser = await chromium.launch();
const page = await browser.newPage();
page.on("pageerror", (err) => console.log("PAGEERROR", err));
page.on("console", (msg) => {
  if (msg.type() === "error") console.log("CONSOLE ERROR", msg.text());
});

await page.goto(
  "http://127.0.0.1:3456/packages/frontend/navi/src/control/demos/00_field_demo.html",
  { waitUntil: "networkidle" },
);

await page.locator('input[name="lazy_neighbor_name"]').click();
await page.locator('input[name="lazy_neighbor_name"]').type("hello");
await page.screenshot({ path: "/tmp/demo.png" });

await browser.close();

Run it with plain node from anywhere inside the repo tree (so playwright resolves from the root node_modules) — no special flags needed.

Notes

• Demo files import from the package's source directly (e.g. @jsenv/navi), so edits to source are reflected on browser reload — no rebuild step.
• When the user does ask for verification, prefer checking a demo actually renders/behaves correctly over trusting the JSX by inspection alone, especially for anything involving events, focus, or async (Suspense/lazy) — those are exactly the class of bugs these demo files exist to catch.
• Do NOT run this on your own initiative — not for a demo you just wrote, not as a "regression check" against unrelated existing demos after touching shared code (e.g. Popover/Dialog). The user drives when verification happens; wait for an explicit ask.