From b10f2442ba2e059b6abade2fb5d0a9091390b37d Mon Sep 17 00:00:00 2001
From: Barret Schloerke <barret@posit.co>
Date: Wed, 19 Aug 2026 16:54:46 -0400
Subject: [PATCH 1/5] feat: add page_react() and template-mode
 page_react_html()
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two coherent page modes replacing the halfway index.html fragment:

- page_react() (Python + R): zero-config server-composed page. Discovers
  www/ui.js + www/ui.css, serves them as an mtime-versioned
  HTMLDependency (cache-busted, unlike raw script tags), title defaults
  to the app folder name, no body HTML — the client appends its own
  mount container
- set_react_page() (Express): path now optional; with no args it uses
  www/index.html when present, else falls back to page_react() discovery
  (renderer-dep harvesting preserved via extracted helper)
- R page_react_html(): accepts a complete HTML document with a
  {{ headContent() }} marker (htmltools::htmlTemplate); shinyreact deps
  render at the marker via the new config_head_dep(). Fragments now
  error with a pointer to page_react()
- Python page_react_html(): unchanged fragment behavior, documented as
  blocked on an upstream py-shiny gap (App cannot accept a pre-rendered
  document with extra dependencies)
---
 pkg-py/README.md                              |   1 +
 pkg-py/src/shinyreact/__init__.py             |   2 +
 pkg-py/src/shinyreact/_page.py                | 180 ++++++++++++++----
 .../tests/playwright/test_bookmark_restore.py |  12 +-
 pkg-py/tests/test_bookmark_restore.py         |   8 +-
 pkg-py/tests/test_page.py                     |  99 ++++++++++
 pkg-py/tests/test_set_react_page.py           |  75 +++++++-
 pkg-r/NAMESPACE                               |   1 +
 pkg-r/R/dep.R                                 |  15 ++
 pkg-r/R/page.R                                |  93 ++++++++-
 pkg-r/_pkgdown.yml                            |   2 +-
 pkg-r/man/page_react.Rd                       |  48 +++++
 pkg-r/man/page_react_html.Rd                  |  22 ++-
 pkg-r/tests/testthat/helper-render.R          |  17 ++
 .../testthat/test-bookmark-restore-context.R  |  14 +-
 pkg-r/tests/testthat/test-page.R              | 157 +++++++++++++--
 16 files changed, 655 insertions(+), 91 deletions(-)
 create mode 100644 pkg-r/man/page_react.Rd
 create mode 100644 pkg-r/tests/testthat/helper-render.R

diff --git a/pkg-py/README.md b/pkg-py/README.md
index 4653dae4..a0574d99 100644
--- a/pkg-py/README.md
+++ b/pkg-py/README.md
@@ -33,6 +33,7 @@ from shinyreact import reactive_output, set_react_page
 
 set_react_page()
 
+
 @reactive_output
 def greeting():
     return {"message": f"Hello, {input.name()}"}
diff --git a/pkg-py/src/shinyreact/__init__.py b/pkg-py/src/shinyreact/__init__.py
index 366fb0c3..de0fa8f5 100644
--- a/pkg-py/src/shinyreact/__init__.py
+++ b/pkg-py/src/shinyreact/__init__.py
@@ -3,6 +3,7 @@
 )
 from ._page import (
     page_bare,
+    page_react,
     page_react_dep,
     page_react_html,
     set_react_page,
@@ -12,6 +13,7 @@
 
 __all__ = [
     "page_bare",
+    "page_react",
     "page_react_dep",
     "page_react_html",
     "reactive_output",
diff --git a/pkg-py/src/shinyreact/_page.py b/pkg-py/src/shinyreact/_page.py
index fa7d5379..7afe2e46 100644
--- a/pkg-py/src/shinyreact/_page.py
+++ b/pkg-py/src/shinyreact/_page.py
@@ -45,6 +45,74 @@ def page_bare(
     )
 
 
+def _resolve_react_dirs(
+    src_dir: str | Path | None, caller_dir: Path
+) -> tuple[Path, str]:
+    """Resolve ``page_react``'s asset dir and derive the app name.
+
+    Returns ``(base_dir, app_name)``. ``app_name`` is the app folder's name:
+    when the asset dir is the conventional ``www/``, its parent (the app dir)
+    names the app; otherwise the asset dir itself does.
+    """
+    if src_dir is None:
+        base_dir = caller_dir / "www"
+    else:
+        src_dir = Path(src_dir)
+        base_dir = src_dir if src_dir.is_absolute() else caller_dir / src_dir
+    app_name = base_dir.parent.name if base_dir.name == "www" else base_dir.name
+    return base_dir, app_name
+
+
+def page_react(
+    *args: TagChild,
+    src_dir: str | Path | None = None,
+    js_file: str = "ui.js",
+    css_file: str = "ui.css",
+    title: str | None = None,
+    lang: str = "en",
+) -> Tag:
+    """Create a React page from conventional assets — no HTML file required.
+
+    The zero-configuration page for the ui.tsx pattern: the server emits no
+    body HTML at all. It attaches the shinyreact bundle plus your app's entry
+    assets, discovered at ``www/ui.js`` and ``www/ui.css`` (relative to the
+    calling module). Your JS owns the DOM — create and append your own mount
+    container::
+
+        const root = ReactDOM.createRoot(
+          document.body.appendChild(document.createElement("div")),
+        );
+
+    ``ui.js`` is required (a missing file warns, pointing at the resolved
+    path); ``ui.css`` is attached only when it exists. Both are served as an
+    :class:`~htmltools.HTMLDependency` versioned by ``ui.js``'s mtime, so the
+    browser re-fetches after every edit — unlike raw ``<script src=...>``
+    tags in a hand-written HTML file, which the browser caches.
+
+    Args:
+        *args: Extra children or :class:`~htmltools.HTMLDependency` objects.
+        src_dir: Directory containing the assets. Defaults to ``www/`` next
+            to the calling module; relative paths resolve against the caller.
+        js_file: JS entry filename within ``src_dir`` (default ``"ui.js"``).
+        css_file: CSS filename within ``src_dir`` (default ``"ui.css"``).
+        title: Page title. Defaults to the app folder's name (``src_dir``'s
+            parent when ``src_dir`` is a ``www/`` dir).
+        lang: HTML ``lang`` attribute.
+    """
+    caller_file = sys._getframe(1).f_globals.get("__file__")
+    caller_dir = Path(caller_file).parent if caller_file else Path.cwd()
+    base_dir, app_name = _resolve_react_dirs(src_dir, caller_dir)
+    return page_bare(
+        _dep_page(),
+        page_react_dep(
+            src_dir=base_dir, js_file=js_file, css_file=css_file, name=app_name
+        ),
+        *args,
+        title=title if title is not None else app_name,
+        lang=lang,
+    )
+
+
 def page_react_dep(
     *,
     src_dir: str | Path | None = None,
@@ -148,13 +216,19 @@ def page_react_dep(
     )
 
 
-def set_react_page(path: str | Path = "www/index.html") -> None:
-    """Set the page for this Express app to an HTML file hosting a React app.
+def set_react_page(path: str | Path | None = None) -> None:
+    """Set the page for this Express app to a React app (the ui.tsx pattern).
+
+    With no arguments, serves ``www/index.html`` when it exists; otherwise
+    falls back to :func:`page_react`-style discovery of ``www/ui.js`` /
+    ``www/ui.css``, emitting no body HTML at all (your JS appends its own
+    mount container to ``<body>``). Passing ``path`` explicitly requires the
+    file to exist.
 
-    Reads the specified HTML file once (cached at call time) and uses it as
-    the page body. Dependencies from traditional Shiny renderers (e.g.
-    ``@render.data_frame``) are discovered automatically and injected into
-    the page head.
+    When an HTML file is used, it is read once (cached at call time) and used
+    as the page body. In both modes, dependencies from traditional Shiny
+    renderers (e.g. ``@render.data_frame``) are discovered automatically and
+    injected into the page head.
 
     Renderers defined inside ``@module.server`` are discovered too: every
     renderer mounted while the app body runs is found via the session's
@@ -210,17 +284,22 @@ def set_react_page(path: str | Path = "www/index.html") -> None:
         path: Path to the HTML file. Absolute paths are used verbatim;
             relative paths resolve against the caller module's directory,
             or against ``Path.cwd()`` when there is no caller ``__file__``.
-            Defaults to ``"www/index.html"``.
+            When ``None`` (the default), uses ``www/index.html`` if it
+            exists, else discovers ``www/ui.js`` / ``www/ui.css``.
     """
-    path = Path(path)
-    if path.is_absolute():
-        index_path = path
+    caller_file = sys._getframe(1).f_globals.get("__file__")
+    # If the caller has no __file__ (REPL or dynamically exec'd code),
+    # fall back to the current working directory.
+    caller_dir = Path(caller_file).parent if caller_file else Path.cwd()
+
+    if path is None:
+        index_path = caller_dir / "www" / "index.html"
+        if not index_path.exists():
+            page_opts(page_fn=_build_react_page_fn_discovered(caller_dir))
+            return
     else:
-        caller_file = sys._getframe(1).f_globals.get("__file__")
-        # If the caller has no __file__ (REPL or dynamically exec'd code),
-        # fall back to the current working directory.
-        caller_dir = Path(caller_file).parent if caller_file else Path.cwd()
-        index_path = caller_dir / path
+        path = Path(path)
+        index_path = path if path.is_absolute() else caller_dir / path
     page_opts(page_fn=_build_react_page_fn(index_path))
 
 
@@ -257,6 +336,17 @@ def page_react_html(path: str | Path = "www/index.html") -> TagList:
     (R's ``shiny::runApp()`` serves ``www/`` next to ``app.R`` automatically,
     so the R counterpart needs no equivalent.)
 
+    .. note::
+
+       The file is a body *fragment*, not a complete document — Shiny owns
+       ``<html>``/``<head>``. R's ``page_react_html()`` instead accepts a full
+       document with a ``{{ headContent() }}`` marker (htmltools
+       ``htmlTemplate()``); Python cannot match that yet because ``shiny.App``
+       has no way to accept a pre-rendered document with extra dependencies
+       (``HTMLTextDocument`` is only used internally for ``ui=Path``, with no
+       dependency-injection hook). Until that upstream gap closes, prefer
+       :func:`page_react` — it needs no HTML file at all.
+
     Args:
         path: Path to the HTML file. Absolute paths are used verbatim;
             relative paths resolve against the caller module's directory, or
@@ -293,6 +383,45 @@ def _collect_renderer_deps(renderer: Renderer, deps: list[HTMLDependency]) -> No
         deps.extend(ui.tagify().get_dependencies())
 
 
+def _harvest_renderer_deps(args: tuple[Any, ...]) -> list[HTMLDependency]:
+    """Collect HTMLDependencies from Express renderers for the page head.
+
+    Looks at the top-level renderers Shiny Express hands to the page function,
+    plus every renderer registered on the active session — including those
+    defined inside ``@module.server``, which ``args`` never sees (issue #87).
+    At the tagify pass the stub session already holds every synchronously
+    mounted renderer in ``output._outputs``.
+    """
+    deps: list[HTMLDependency] = []
+    for arg in args:
+        if isinstance(arg, Renderer):
+            _collect_renderer_deps(arg, deps)
+    session = get_current_session()
+    if session is not None:
+        # `_outputs` is private; Shiny exposes no public API to iterate
+        # registered outputs.
+        for info in session.output._outputs.values():
+            _collect_renderer_deps(info.renderer, deps)
+    return deps
+
+
+def _build_react_page_fn_discovered(app_dir: Path) -> Callable[..., Tag]:
+    """Express page function for the no-HTML-file mode.
+
+    Serves a :func:`page_react` page from ``app_dir/www`` with the same
+    renderer-dependency discovery as the index.html mode.
+    """
+
+    def _react_page_fn(*args: Any) -> Tag:
+        return page_react(
+            *_harvest_renderer_deps(args),
+            src_dir=app_dir / "www",
+            title=app_dir.name,
+        )
+
+    return _react_page_fn
+
+
 def _build_react_page_fn(index_path: Path) -> Callable[..., Tag]:
     if not index_path.exists():
         raise FileNotFoundError(f"HTML file not found: {index_path}")
@@ -317,26 +446,9 @@ def _build_react_page_fn(index_path: Path) -> Callable[..., Tag]:
     index_html = index_path.read_text()
 
     def _react_page_fn(*args: Any) -> Tag:
-        deps: list[HTMLDependency] = []
-
-        # Top-level renderers Shiny Express hands to the page function.
-        for arg in args:
-            if isinstance(arg, Renderer):
-                _collect_renderer_deps(arg, deps)
-
-        # Renderers registered on the active session — including those defined
-        # inside @module.server, which `*args` never sees (issue #87). At the
-        # tagify pass the stub session already holds every synchronously
-        # mounted renderer in `output._outputs`.
-        session = get_current_session()
-        if session is not None:
-            # `_outputs` is private; Shiny exposes no public API to iterate
-            # registered outputs.
-            for info in session.output._outputs.values():
-                _collect_renderer_deps(info.renderer, deps)
-
+        deps = _harvest_renderer_deps(args)
         # Shiny de-duplicates dependencies by name+version when hoisting to
-        # <head>, so any overlap between the two passes is harmless.
+        # <head>, so any overlap between the harvest passes is harmless.
         # page_opts types page_fn as -> Tag, but TagList works at runtime
         return cast(Tag, TagList(_dep_page(), *deps, HTML(index_html)))
 
diff --git a/pkg-py/tests/playwright/test_bookmark_restore.py b/pkg-py/tests/playwright/test_bookmark_restore.py
index 1b7cf43f..f19ba32d 100644
--- a/pkg-py/tests/playwright/test_bookmark_restore.py
+++ b/pkg-py/tests/playwright/test_bookmark_restore.py
@@ -35,9 +35,7 @@ def test_url_mode_restores_inputs(page: Page, bookmark_app: ShinyAppProc) -> Non
 
     # React tracks checkbox state in JS rather than the DOM `checked` attribute,
     # so verify via JS evaluation rather than to_be_checked().
-    checked = page.evaluate(
-        "document.querySelector('[data-testid=chk]').checked"
-    )
+    checked = page.evaluate("document.querySelector('[data-testid=chk]').checked")
     assert checked is True
 
     # The server-rendered output should reflect the restored inputs.
@@ -47,9 +45,7 @@ def test_url_mode_restores_inputs(page: Page, bookmark_app: ShinyAppProc) -> Non
     expect(echo).to_contain_text("checked=yes")
 
 
-def test_no_bookmark_renders_defaults(
-    page: Page, bookmark_app: ShinyAppProc
-) -> None:
+def test_no_bookmark_renders_defaults(page: Page, bookmark_app: ShinyAppProc) -> None:
     """Plain URL renders defaults and the _restore sentinel is applied."""
     page.goto(bookmark_app.url)
     _wait_for_shiny_initialized(page)
@@ -58,9 +54,7 @@ def test_no_bookmark_renders_defaults(
     expect(page.get_by_test_id("txt")).to_have_value("")
     expect(page.get_by_test_id("num")).to_have_value("0")
 
-    checked = page.evaluate(
-        "document.querySelector('[data-testid=chk]').checked"
-    )
+    checked = page.evaluate("document.querySelector('[data-testid=chk]').checked")
     assert checked is False
 
     # After shinyreact initialises without restore data the sentinel should show
diff --git a/pkg-py/tests/test_bookmark_restore.py b/pkg-py/tests/test_bookmark_restore.py
index c85b28c8..df84fa8a 100644
--- a/pkg-py/tests/test_bookmark_restore.py
+++ b/pkg-py/tests/test_bookmark_restore.py
@@ -185,9 +185,7 @@ def test_dep_returns_htmldependency_only_with_context() -> None:
 def test_dep_page_no_context_includes_config_tag() -> None:
     result = _dep_page()
     assert isinstance(result, TagList)
-    assert any(
-        isinstance(c, HTMLDependency) and c.name == "shinyreact" for c in result
-    )
+    assert any(isinstance(c, HTMLDependency) and c.name == "shinyreact" for c in result)
     config = _extract_config(_rendered_html(result))
     assert config == {"protocolVersion": PROTOCOL_VERSION}
 
@@ -198,9 +196,7 @@ def test_dep_page_with_active_context_includes_restore() -> None:
     with restore_context_cm(ctx):
         result = _dep_page()
     assert isinstance(result, TagList)
-    assert any(
-        isinstance(c, HTMLDependency) and c.name == "shinyreact" for c in result
-    )
+    assert any(isinstance(c, HTMLDependency) and c.name == "shinyreact" for c in result)
     config = _extract_config(_rendered_html(result))
     assert config["restore"] == {"foo": "hello"}
 
diff --git a/pkg-py/tests/test_page.py b/pkg-py/tests/test_page.py
index 57a82c85..aca22b67 100644
--- a/pkg-py/tests/test_page.py
+++ b/pkg-py/tests/test_page.py
@@ -91,3 +91,102 @@ def test_page_react_html_falls_back_to_cwd_without_file(tmp_path, monkeypatch):
 
     rendered = str(captured["ui"].tagify())
     assert 'id="root"' in rendered
+
+
+def _make_react_app(tmp_path, name="myapp", css=True):
+    """An app folder with the page_react() conventional assets."""
+    www = tmp_path / name / "www"
+    www.mkdir(parents=True)
+    (www / "ui.js").write_text("// ui entry")
+    if css:
+        (www / "ui.css").write_text("body {}")
+    return tmp_path / name
+
+
+def _dep_tags_html(ui) -> str:
+    rendered = ui.tagify().render()
+    return (
+        "".join(d.as_html_tags().get_html_string() for d in rendered["dependencies"])
+        + rendered["html"]
+    )
+
+
+def test_page_react_attaches_bundle_app_dep_and_config(tmp_path):
+    from shinyreact import page_react
+
+    app_dir = _make_react_app(tmp_path)
+    ui = page_react(src_dir=app_dir / "www")
+    names = [d.name for d in ui.get_dependencies()]
+    assert "shinyreact" in names
+    assert "myapp" in names
+    html = _dep_tags_html(ui)
+    assert "ui.js" in html
+    assert "ui.css" in html
+    assert 'id="shinyreact-config"' in html
+
+
+def test_page_react_title_defaults_to_app_folder_name(tmp_path):
+    from shinyreact import page_react
+
+    app_dir = _make_react_app(tmp_path)
+    rendered = str(page_react(src_dir=app_dir / "www").tagify())
+    assert re.findall(r"<title>.*?</title>", rendered) == ["<title>myapp</title>"]
+
+
+def test_page_react_title_override(tmp_path):
+    from shinyreact import page_react
+
+    app_dir = _make_react_app(tmp_path)
+    rendered = str(page_react(src_dir=app_dir / "www", title="Custom").tagify())
+    assert re.findall(r"<title>.*?</title>", rendered) == ["<title>Custom</title>"]
+
+
+def test_page_react_skips_missing_css(tmp_path):
+    from shinyreact import page_react
+
+    app_dir = _make_react_app(tmp_path, css=False)
+    html = _dep_tags_html(page_react(src_dir=app_dir / "www"))
+    assert "ui.js" in html
+    assert "ui.css" not in html
+
+
+def test_page_react_warns_on_missing_js(tmp_path):
+    from shinyreact import page_react
+
+    app_dir = tmp_path / "empty-app"
+    (app_dir / "www").mkdir(parents=True)
+    with pytest.warns(UserWarning, match="ui.js"):
+        page_react(src_dir=app_dir / "www")
+
+
+def test_page_react_includes_extra_dependencies(tmp_path):
+    from shinyreact import page_react
+
+    app_dir = _make_react_app(tmp_path)
+    extra = HTMLDependency(
+        name="extra-dep",
+        version="1.0",
+        source={"href": "/x"},
+        script={"src": "x.js"},
+    )
+    ui = page_react(extra, src_dir=app_dir / "www")
+    names = [d.name for d in ui.get_dependencies()]
+    assert "extra-dep" in names
+
+
+def test_page_react_defaults_resolve_against_cwd_without_caller_file(
+    tmp_path, monkeypatch
+):
+    """With no src_dir and no caller __file__, www/ resolves against CWD."""
+    app_dir = _make_react_app(tmp_path, name="cwd-app")
+    monkeypatch.chdir(app_dir)
+
+    captured: dict[str, Tag] = {}
+    src = "from shinyreact import page_react\ncaptured['ui'] = page_react()\n"
+    exec(compile(src, "<test>", "exec"), {"captured": captured})
+
+    ui = captured["ui"]
+    names = [d.name for d in ui.get_dependencies()]
+    assert "cwd-app" in names
+    rendered = str(ui.tagify())
+    assert "<title>cwd-app</title>" in rendered
diff --git a/pkg-py/tests/test_set_react_page.py b/pkg-py/tests/test_set_react_page.py
index 35206561..dcb42c57 100644
--- a/pkg-py/tests/test_set_react_page.py
+++ b/pkg-py/tests/test_set_react_page.py
@@ -159,8 +159,7 @@ def fake_page_opts(*, page_fn: Callable[..., Tag], **_: Any) -> None:
         # Caller frame has no __file__ — relative path resolves against CWD.
         exec(
             compile(
-                "from shinyreact import set_react_page\n"
-                "set_react_page('cwd.html')\n",
+                "from shinyreact import set_react_page\nset_react_page('cwd.html')\n",
                 "<test>",
                 "exec",
             ),
@@ -194,3 +193,75 @@ def fake_page_opts(*, page_fn: Callable[..., Tag], **_: Any) -> None:
 
     rendered = _render(captured["page_fn"])
     assert "<div id='abs'></div>" in rendered["html"]
+
+
+def test_build_page_fn_discovered_serves_conventional_assets(tmp_path: Path) -> None:
+    """The no-index.html mode serves www/ui.js + ui.css with the app-dir title."""
+    from shinyreact._page import _build_react_page_fn_discovered
+
+    www = tmp_path / "www"
+    www.mkdir()
+    (www / "ui.js").write_text("// entry")
+    (www / "ui.css").write_text("body {}")
+
+    rendered = _render(_build_react_page_fn_discovered(tmp_path))
+    deps_html = "".join(
+        d.as_html_tags().get_html_string() for d in rendered["dependencies"]
+    )
+    dep_names = [d.name for d in rendered["dependencies"]]
+    assert "shinyreact" in dep_names
+    assert tmp_path.name in dep_names
+    assert "ui.js" in deps_html
+    assert "ui.css" in deps_html
+    assert f"<title>{tmp_path.name}</title>" in rendered["html"]
+
+
+def test_set_react_page_none_prefers_index_html(tmp_path: Path) -> None:
+    """With no path, www/index.html wins over ui.js discovery when present."""
+    www = tmp_path / "www"
+    www.mkdir()
+    (www / "index.html").write_text("<div id='from-index'></div>")
+    (www / "ui.js").write_text("// entry")
+
+    app_file = tmp_path / "app.py"
+    app_file.write_text("from shinyreact import set_react_page\nset_react_page()\n")
+
+    captured: dict[str, Callable[..., Tag]] = {}
+
+    def fake_page_opts(*, page_fn: Callable[..., Tag], **_: Any) -> None:
+        captured["page_fn"] = page_fn
+
+    with patch("shinyreact._page.page_opts", fake_page_opts):
+        exec(
+            compile(app_file.read_text(), str(app_file), "exec"),
+            {"__file__": str(app_file)},
+        )
+
+    rendered = _render(captured["page_fn"])
+    assert "from-index" in rendered["html"]
+
+
+def test_set_react_page_none_falls_back_to_discovery(tmp_path: Path) -> None:
+    """With no path and no www/index.html, ui.js discovery kicks in."""
+    www = tmp_path / "www"
+    www.mkdir()
+    (www / "ui.js").write_text("// entry")
+
+    app_file = tmp_path / "app.py"
+    app_file.write_text("from shinyreact import set_react_page\nset_react_page()\n")
+
+    captured: dict[str, Callable[..., Tag]] = {}
+
+    def fake_page_opts(*, page_fn: Callable[..., Tag], **_: Any) -> None:
+        captured["page_fn"] = page_fn
+
+    with patch("shinyreact._page.page_opts", fake_page_opts):
+        exec(
+            compile(app_file.read_text(), str(app_file), "exec"),
+            {"__file__": str(app_file)},
+        )
+
+    rendered = _render(captured["page_fn"])
+    dep_names = [d.name for d in rendered["dependencies"]]
+    assert tmp_path.name in dep_names
+    assert f"<title>{tmp_path.name}</title>" in rendered["html"]
diff --git a/pkg-r/NAMESPACE b/pkg-r/NAMESPACE
index c8ae25c0..edd01c84 100644
--- a/pkg-r/NAMESPACE
+++ b/pkg-r/NAMESPACE
@@ -1,6 +1,7 @@
 # Generated by roxygen2: do not edit by hand
 
 export(page_bare)
+export(page_react)
 export(page_react_dep)
 export(page_react_html)
 export(reactive_output)
diff --git a/pkg-r/R/dep.R b/pkg-r/R/dep.R
index 8827df6f..17ff08bb 100644
--- a/pkg-r/R/dep.R
+++ b/pkg-r/R/dep.R
@@ -28,3 +28,18 @@ shinyreact_dep <- function() {
 shinyreact_dep_page <- function() {
   htmltools::tagList(shinyreact_dep(), config_script_tag())
 }
+
+# Internal: the `#shinyreact-config` tag as an htmlDependency `head` entry, for
+# UIs where a plain tag has no place to land — htmlTemplate() documents render
+# attached dependencies into `{{ headContent() }}`, and a dependency's `head`
+# HTML rides along verbatim. src is an empty href: the dependency ships no
+# files, only head content.
+config_head_dep <- function() {
+  htmltools::htmlDependency(
+    name = "shinyreact-config",
+    version = .protocol_version,
+    src = c(href = ""),
+    head = as.character(config_script_tag()),
+    all_files = FALSE
+  )
+}
diff --git a/pkg-r/R/page.R b/pkg-r/R/page.R
index 8bb69aa1..c10a3cd9 100644
--- a/pkg-r/R/page.R
+++ b/pkg-r/R/page.R
@@ -11,11 +11,74 @@ page_bare <- function(..., title = NULL, lang = "en") {
   shiny::bootstrapPage(..., title = title, lang = lang)
 }
 
-#' Serve a static React `index.html` (the `ui.tsx` pattern)
+#' Create a React page from conventional assets — no HTML file required
 #'
-#' Reads an HTML file and attaches the shinyreact page-level dependency. Use as
-#' the `ui` argument: `shinyApp(ui = page_react_html(), server = ...)`. Works
-#' with plain HTML (no `{{ headContent() }}` template syntax required).
+#' The zero-configuration page for the `ui.tsx` pattern: the server emits no
+#' body HTML at all. Attaches the shinyreact bundle plus your app's entry
+#' assets, discovered at `www/ui.js` and `www/ui.css` (relative to the working
+#' directory — the app directory under `shiny::runApp()`). Your JS owns the
+#' DOM: create and append your own mount container, e.g.
+#' `ReactDOM.createRoot(document.body.appendChild(document.createElement("div")))`.
+#'
+#' `ui.js` is required (a missing file warns, pointing at the resolved path);
+#' `ui.css` is attached only when it exists. Both are served as an
+#' [htmltools::htmlDependency] versioned by `ui.js`'s mtime, so the browser
+#' re-fetches after every edit — unlike raw `<script src=...>` tags in a
+#' hand-written HTML file, which the browser caches.
+#'
+#' @param ... Extra children or [htmltools::htmlDependency] objects.
+#' @param src_dir Directory containing the assets. Defaults to `"www"`,
+#'   relative to the working directory.
+#' @param js_file JS entry filename within `src_dir`. Defaults to `"ui.js"`.
+#' @param css_file CSS filename within `src_dir`. Defaults to `"ui.css"`.
+#' @param title Page title. Defaults to the app folder's name (`src_dir`'s
+#'   parent when `src_dir` is a `www` directory).
+#' @param lang HTML `lang` attribute.
+#' @return UI suitable for `shinyApp(ui = ...)`.
+#' @export
+page_react <- function(
+  ...,
+  src_dir = "www",
+  js_file = "ui.js",
+  css_file = "ui.css",
+  title = NULL,
+  lang = "en"
+) {
+  base_dir <-
+    if (basename(src_dir) == "www") {
+      dirname(normalizePath(src_dir, mustWork = FALSE))
+    } else {
+      normalizePath(src_dir, mustWork = FALSE)
+    }
+  app_name <- basename(base_dir)
+  page_bare(
+    shinyreact_dep_page(),
+    page_react_dep(
+      src_dir,
+      js_file = js_file,
+      css_file = css_file,
+      name = app_name
+    ),
+    ...,
+    title = if (is.null(title)) app_name else title,
+    lang = lang
+  )
+}
+
+#' Serve a React `index.html` document (the `ui.tsx` pattern)
+#'
+#' Reads a complete HTML document — the kind a Vite build emits — and injects
+#' the shinyreact page-level dependencies into it via
+#' [htmltools::htmlTemplate()]. The document must contain a
+#' `{{ headContent() }}` marker inside `<head>`; Shiny's and shinyreact's
+#' script/link tags render there. Use as the `ui` argument:
+#' `shinyApp(ui = page_react_html(), server = ...)`.
+#'
+#' Assets the document references (your bundle's JS/CSS) should live in `www/`,
+#' where Shiny serves them statically.
+#'
+#' For apps that don't need to own the HTML document, prefer [page_react()] —
+#' it requires no HTML file at all.
 #'
 #' @section Path resolution:
 #' A relative `path` resolves against the process working directory. Under
@@ -25,8 +88,8 @@ page_bare <- function(..., title = NULL, lang = "en") {
 #' directory — there is nothing to resolve against outside the working
 #' directory. Pass an absolute path if you need to be independent of it.
 #'
-#' @param path Path to the HTML file. Defaults to `"www/index.html"`, relative
-#'   to the working directory.
+#' @param path Path to the HTML document. Defaults to `"www/index.html"`,
+#'   relative to the working directory.
 #' @return UI suitable for `shinyApp(ui = ...)`.
 #' @export
 page_react_html <- function(path = "www/index.html") {
@@ -37,12 +100,22 @@ page_react_html <- function(path = "www/index.html") {
              {.path {getwd()}}."
     ))
   }
-  # Read the file verbatim rather than readLines() + paste(collapse = "\n"),
-  # which drops a trailing newline and rewrites CRLF -- Python's read_text() is
-  # byte-exact, so the same index.html must render identically (#184).
   # brio::read_file() always reads UTF-8 and never touches line endings.
   html <- brio::read_file(path)
-  htmltools::tagList(shinyreact_dep_page(), htmltools::HTML(html))
+  if (!grepl("{{ headContent() }}", html, fixed = TRUE)) {
+    cli::cli_abort(c(
+      "{.path {path}} must be a complete HTML document containing a
+       {.code {{{{ headContent() }}}}} marker inside {.code <head>}.",
+      "i" = "shinyreact's script and stylesheet tags render at the marker.",
+      "i" = "For a page without an HTML file, use {.fn page_react} instead."
+    ))
+  }
+  ui <- htmltools::htmlTemplate(path, document_ = TRUE)
+  htmltools::attachDependencies(
+    ui,
+    list(shinyreact_dep(), config_head_dep()),
+    append = TRUE
+  )
 }
 
 #' HTML dependency for a downstream package's own JS/CSS bundle
diff --git a/pkg-r/_pkgdown.yml b/pkg-r/_pkgdown.yml
index afd341d7..f7cee92f 100644
--- a/pkg-r/_pkgdown.yml
+++ b/pkg-r/_pkgdown.yml
@@ -3,7 +3,7 @@ template:
   bootstrap: 5
 reference:
   - title: Pages
-    contents: [page_bare, page_react_html, page_react_dep]
+    contents: [page_bare, page_react, page_react_html, page_react_dep]
   - title: Outputs
     contents: [reactive_output]
   - title: Messaging
diff --git a/pkg-r/man/page_react.Rd b/pkg-r/man/page_react.Rd
new file mode 100644
index 00000000..24a653fe
--- /dev/null
+++ b/pkg-r/man/page_react.Rd
@@ -0,0 +1,48 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/page.R
+\name{page_react}
+\alias{page_react}
+\title{Create a React page from conventional assets — no HTML file required}
+\usage{
+page_react(
+  ...,
+  src_dir = "www",
+  js_file = "ui.js",
+  css_file = "ui.css",
+  title = NULL,
+  lang = "en"
+)
+}
+\arguments{
+\item{...}{Extra children or \link[htmltools:htmlDependency]{htmltools::htmlDependency} objects.}
+
+\item{src_dir}{Directory containing the assets. Defaults to \code{"www"},
+relative to the working directory.}
+
+\item{js_file}{JS entry filename within \code{src_dir}. Defaults to \code{"ui.js"}.}
+
+\item{css_file}{CSS filename within \code{src_dir}. Defaults to \code{"ui.css"}.}
+
+\item{title}{Page title. Defaults to the app folder's name (\code{src_dir}'s
+parent when \code{src_dir} is a \code{www} directory).}
+
+\item{lang}{HTML \code{lang} attribute.}
+}
+\value{
+UI suitable for \code{shinyApp(ui = ...)}.
+}
+\description{
+The zero-configuration page for the \code{ui.tsx} pattern: the server emits no
+body HTML at all. Attaches the shinyreact bundle plus your app's entry
+assets, discovered at \code{www/ui.js} and \code{www/ui.css} (relative to the working
+directory — the app directory under \code{shiny::runApp()}). Your JS owns the
+DOM: create and append your own mount container, e.g.
+\code{ReactDOM.createRoot(document.body.appendChild(document.createElement("div")))}.
+}
+\details{
+\code{ui.js} is required (a missing file warns, pointing at the resolved path);
+\code{ui.css} is attached only when it exists. Both are served as an
+\link[htmltools:htmlDependency]{htmltools::htmlDependency} versioned by \code{ui.js}'s mtime, so the browser
+re-fetches after every edit — unlike raw \verb{<script src=...>} tags in a
+hand-written HTML file, which the browser caches.
+}
diff --git a/pkg-r/man/page_react_html.Rd b/pkg-r/man/page_react_html.Rd
index 2e47db2a..45699691 100644
--- a/pkg-r/man/page_react_html.Rd
+++ b/pkg-r/man/page_react_html.Rd
@@ -2,21 +2,31 @@
 % Please edit documentation in R/page.R
 \name{page_react_html}
 \alias{page_react_html}
-\title{Serve a static React \code{index.html} (the \code{ui.tsx} pattern)}
+\title{Serve a React \code{index.html} document (the \code{ui.tsx} pattern)}
 \usage{
 page_react_html(path = "www/index.html")
 }
 \arguments{
-\item{path}{Path to the HTML file. Defaults to \code{"www/index.html"}, relative
-to the working directory.}
+\item{path}{Path to the HTML document. Defaults to \code{"www/index.html"},
+relative to the working directory.}
 }
 \value{
 UI suitable for \code{shinyApp(ui = ...)}.
 }
 \description{
-Reads an HTML file and attaches the shinyreact page-level dependency. Use as
-the \code{ui} argument: \code{shinyApp(ui = page_react_html(), server = ...)}. Works
-with plain HTML (no \code{{{ headContent() }}} template syntax required).
+Reads a complete HTML document — the kind a Vite build emits — and injects
+the shinyreact page-level dependencies into it via
+\code{\link[htmltools:htmlTemplate]{htmltools::htmlTemplate()}}. The document must contain a
+\code{{{ headContent() }}} marker inside \verb{<head>}; Shiny's and shinyreact's
+script/link tags render there. Use as the \code{ui} argument:
+\code{shinyApp(ui = page_react_html(), server = ...)}.
+}
+\details{
+Assets the document references (your bundle's JS/CSS) should live in \verb{www/},
+where Shiny serves them statically.
+
+For apps that don't need to own the HTML document, prefer \code{\link[=page_react]{page_react()}} —
+it requires no HTML file at all.
 }
 \section{Path resolution}{
 
diff --git a/pkg-r/tests/testthat/helper-render.R b/pkg-r/tests/testthat/helper-render.R
new file mode 100644
index 00000000..7786c79e
--- /dev/null
+++ b/pkg-r/tests/testthat/helper-render.R
@@ -0,0 +1,17 @@
+# Render a template-mode UI (page_react_html()) to a full HTML document.
+#
+# htmltools::renderDocument() renders dependencies href-based, but
+# shinyreact_dep() is file-based; in a running app shiny converts it via
+# shiny::createWebDependency() at serve time. Mimic that conversion here so
+# tests exercise the same rendering path without a live app.
+render_document <- function(ui) {
+  htmltools::renderDocument(
+    ui,
+    processDep = function(dep) {
+      if (is.null(dep$src$href)) {
+        dep$src <- list(href = paste0("lib/", dep$name, "-", dep$version))
+      }
+      dep
+    }
+  )
+}
diff --git a/pkg-r/tests/testthat/test-bookmark-restore-context.R b/pkg-r/tests/testthat/test-bookmark-restore-context.R
index 01eb560e..40437676 100644
--- a/pkg-r/tests/testthat/test-bookmark-restore-context.R
+++ b/pkg-r/tests/testthat/test-bookmark-restore-context.R
@@ -76,13 +76,16 @@ test_that("page_react_html() emits the restore payload when a bookmark is active
   dir <- withr::local_tempdir()
   index <- file.path(dir, "index.html")
   writeLines(
-    "<!DOCTYPE html><html><body><div id='root'></div></body></html>",
+    paste0(
+      "<!DOCTYPE html><html><head>{{ headContent() }}</head>",
+      "<body><div id='root'></div></body></html>"
+    ),
     index
   )
 
   html <- with_restore_values(
     list(name = "Alice"),
-    as.character(htmltools::renderTags(page_react_html(index))$html)
+    render_document(page_react_html(index))
   )
   expect_identical(
     extract_restore_payload(html),
@@ -95,11 +98,14 @@ test_that("page_react_html() emits the config tag without restore when not bookm
   dir <- withr::local_tempdir()
   index <- file.path(dir, "index.html")
   writeLines(
-    "<!DOCTYPE html><html><body><div id='root'></div></body></html>",
+    paste0(
+      "<!DOCTYPE html><html><head>{{ headContent() }}</head>",
+      "<body><div id='root'></div></body></html>"
+    ),
     index
   )
 
-  html <- as.character(htmltools::renderTags(page_react_html(index))$html)
+  html <- render_document(page_react_html(index))
   config <- extract_config(html)
   expect_identical(config, list(protocolVersion = .protocol_version))
 })
diff --git a/pkg-r/tests/testthat/test-page.R b/pkg-r/tests/testthat/test-page.R
index 99ca666d..fa79405d 100644
--- a/pkg-r/tests/testthat/test-page.R
+++ b/pkg-r/tests/testthat/test-page.R
@@ -34,26 +34,58 @@ test_that("page_bare includes HTMLDependency arguments", {
   expect_true(any(vapply(deps, function(d) d$name == "my-dep", logical(1))))
 })
 
-test_that("page_react_html reads a plain HTML file and attaches the dep", {
+full_doc <- function(body = "<div id='root'></div>", title = "T") {
+  paste0(
+    "<!DOCTYPE html><html><head><title>",
+    title,
+    "</title>",
+    "{{ headContent() }}</head><body>",
+    body,
+    "</body></html>"
+  )
+}
+
+write_full_doc <- function(path, ...) {
+  writeLines(full_doc(...), path)
+}
+
+test_that("page_react_html renders shinyreact deps into the template head", {
   tmp <- withr::local_tempfile(fileext = ".html")
-  writeLines(
-    "<!DOCTYPE html><html><body><div id='root'></div></body></html>",
-    tmp
+  write_full_doc(tmp)
+  html <- render_document(page_react_html(tmp))
+  expect_match(html, "shinyreact.js", fixed = TRUE)
+  expect_match(html, 'id="shinyreact-config"', fixed = TRUE)
+  # The user's document is the only <html> -- no nested document.
+  expect_identical(
+    lengths(regmatches(html, gregexpr("<html", html, fixed = TRUE))),
+    1L
   )
-  ui <- page_react_html(tmp)
-  deps <- htmltools::findDependencies(ui)
-  expect_true(any(vapply(deps, function(d) d$name == "shinyreact", logical(1))))
+  expect_match(html, "<title>T</title>", fixed = TRUE)
 })
 
-test_that("page_react_html includes the HTML verbatim", {
-  # Byte-exact, including the trailing newline and any CRLF -- readLines() +
-  # paste(collapse = "\n") used to normalize both (#184).
+test_that("page_react_html emits the config payload readable by the client", {
   tmp <- withr::local_tempfile(fileext = ".html")
-  body <- "<!DOCTYPE html>\r\n<html><body><div id='root'></div></body></html>\n"
-  writeBin(charToRaw(body), tmp)
+  write_full_doc(tmp)
+  html <- render_document(page_react_html(tmp))
+  config <- extract_config(html)
+  expect_identical(config$protocolVersion, .protocol_version)
+})
 
-  html <- as.character(htmltools::renderTags(page_react_html(tmp))$html)
-  expect_true(grepl(body, html, fixed = TRUE))
+test_that("page_react_html preserves the document body", {
+  tmp <- withr::local_tempfile(fileext = ".html")
+  write_full_doc(tmp, body = "<main class='xyz'>content</main>")
+  html <- render_document(page_react_html(tmp))
+  expect_match(html, "<main class='xyz'>content</main>", fixed = TRUE)
+})
+
+test_that("page_react_html errors on a document without the marker", {
+  tmp <- withr::local_tempfile(fileext = ".html")
+  writeLines(
+    "<!DOCTYPE html><html><head></head><body>hi</body></html>",
+    tmp
+  )
+  expect_error(page_react_html(tmp), "headContent")
+  expect_error(page_react_html(tmp), "page_react")
 })
 
 test_that("page_react_html errors clearly on a missing file", {
@@ -71,12 +103,99 @@ test_that("page_react_html's not-found error names the working directory", {
 test_that("page_react_html resolves a relative path against the working directory", {
   dir <- withr::local_tempdir()
   dir.create(file.path(dir, "www"))
-  writeLines(
-    "<html><body>hi</body></html>",
-    file.path(dir, "www", "index.html")
+  write_full_doc(file.path(dir, "www", "index.html"), body = "<b>hi</b>")
+  withr::local_dir(dir)
+
+  html <- render_document(page_react_html())
+  expect_match(html, "<b>hi</b>", fixed = TRUE)
+})
+
+local_react_app <- function(css = TRUE, env = parent.frame()) {
+  # An app folder with the page_react() conventional assets, as the working
+  # directory. Mirrors Python's _make_react_app().
+  dir <- withr::local_tempdir("reactapp", .local_envir = env)
+  dir.create(file.path(dir, "www"))
+  writeLines("// ui entry", file.path(dir, "www", "ui.js"))
+  if (css) {
+    writeLines("body {}", file.path(dir, "www", "ui.css"))
+  }
+  withr::local_dir(dir, .local_envir = env)
+  dir
+}
+
+dep_tags_html <- function(ui) {
+  rendered <- htmltools::renderTags(ui)
+  paste0(
+    paste(
+      vapply(
+        htmltools::resolveDependencies(rendered$dependencies),
+        function(d) as.character(htmltools::renderDependencies(list(d))),
+        character(1)
+      ),
+      collapse = ""
+    ),
+    as.character(rendered$head),
+    as.character(rendered$html)
+  )
+}
+
+test_that("page_react attaches bundle, app dep, and config", {
+  dir <- local_react_app()
+  ui <- page_react()
+  deps <- htmltools::findDependencies(ui)
+  names <- vapply(deps, function(d) d$name, character(1))
+  expect_true("shinyreact" %in% names)
+  expect_true(basename(dir) %in% names)
+  html <- dep_tags_html(ui)
+  expect_match(html, "ui.js", fixed = TRUE)
+  expect_match(html, "ui.css", fixed = TRUE)
+  expect_match(html, 'id="shinyreact-config"', fixed = TRUE)
+})
+
+test_that("page_react title defaults to the app folder name", {
+  # Mirrors Python's test_page_react_title_defaults_to_app_folder_name.
+  dir <- local_react_app()
+  rendered <- htmltools::renderTags(page_react())
+  html <- paste0(as.character(rendered$head), as.character(rendered$html))
+  expect_identical(
+    regmatches(html, gregexpr("<title>.*?</title>", html))[[1]],
+    paste0("<title>", basename(dir), "</title>")
   )
+})
+
+test_that("page_react title can be overridden", {
+  local_react_app()
+  rendered <- htmltools::renderTags(page_react(title = "Custom"))
+  html <- paste0(as.character(rendered$head), as.character(rendered$html))
+  expect_match(html, "<title>Custom</title>", fixed = TRUE)
+})
+
+test_that("page_react skips a missing ui.css", {
+  local_react_app(css = FALSE)
+  html <- dep_tags_html(page_react())
+  expect_match(html, "ui.js", fixed = TRUE)
+  expect_no_match(html, "ui.css", fixed = TRUE)
+})
+
+test_that("page_react warns on a missing ui.js", {
+  dir <- withr::local_tempdir("emptyapp")
+  dir.create(file.path(dir, "www"))
   withr::local_dir(dir)
+  expect_warning(page_react(), "ui.js")
+})
 
-  html <- as.character(htmltools::renderTags(page_react_html())$html)
-  expect_match(html, "<body>hi</body>", fixed = TRUE)
+test_that("page_react includes extra HTMLDependency arguments", {
+  local_react_app()
+  dep <- htmltools::htmlDependency(
+    "extra-dep",
+    "1.0",
+    src = c(href = "/x"),
+    script = "x.js"
+  )
+  deps <- htmltools::findDependencies(page_react(dep))
+  expect_true(any(vapply(
+    deps,
+    function(d) d$name == "extra-dep",
+    logical(1)
+  )))
 })

From c75a14bb04cf94af8255eabe151f5425ade37d6d Mon Sep 17 00:00:00 2001
From: Barret Schloerke <barret@posit.co>
Date: Thu, 20 Aug 2026 11:13:03 -0400
Subject: [PATCH 2/5] refactor(examples): build-step examples emit the free
 ui.js/ui.css names

- 03-columns-shadcn, 04-shadcn, 09-hmr build to www/ui.js (+ www/ui.css
  where CSS exists) so set_react_page() discovery needs zero arguments
- Delete their www/index.html fragments; entries append their own mount
  container to <body>
- Rename src/main.jsx to src/ui.jsx (09 already used src/ui.tsx);
  update READMEs, .gitignores, and the 09 dev-stub outFile
---
 examples/03-columns-shadcn/.gitignore     |  4 ++--
 examples/03-columns-shadcn/README.md      |  9 ++++-----
 examples/03-columns-shadcn/src/main.jsx   |  8 --------
 examples/03-columns-shadcn/src/ui.jsx     | 12 ++++++++++++
 examples/03-columns-shadcn/vite.config.js |  6 ++++--
 examples/03-columns-shadcn/www/index.html |  3 ---
 examples/04-shadcn/.gitignore             |  4 ++--
 examples/04-shadcn/README.md              |  9 ++++-----
 examples/04-shadcn/src/main.jsx           |  8 --------
 examples/04-shadcn/src/ui.jsx             | 12 ++++++++++++
 examples/04-shadcn/vite.config.js         |  6 ++++--
 examples/04-shadcn/www/index.html         |  3 ---
 examples/09-hmr/.gitignore                |  2 +-
 examples/09-hmr/README.md                 | 10 +++++-----
 examples/09-hmr/src/ui.tsx                |  6 +++++-
 examples/09-hmr/vite-dev-stub.js          |  4 ++--
 examples/09-hmr/vite.config.js            |  4 ++--
 examples/09-hmr/www/index.html            |  2 --
 18 files changed, 59 insertions(+), 53 deletions(-)
 delete mode 100644 examples/03-columns-shadcn/src/main.jsx
 create mode 100644 examples/03-columns-shadcn/src/ui.jsx
 delete mode 100644 examples/03-columns-shadcn/www/index.html
 delete mode 100644 examples/04-shadcn/src/main.jsx
 create mode 100644 examples/04-shadcn/src/ui.jsx
 delete mode 100644 examples/04-shadcn/www/index.html
 delete mode 100644 examples/09-hmr/www/index.html

diff --git a/examples/03-columns-shadcn/.gitignore b/examples/03-columns-shadcn/.gitignore
index 9558ca43..a790fdb1 100644
--- a/examples/03-columns-shadcn/.gitignore
+++ b/examples/03-columns-shadcn/.gitignore
@@ -1,4 +1,4 @@
 node_modules/
 package-lock.json
-www/app.js
-www/style.css
+www/ui.js
+www/ui.css
diff --git a/examples/03-columns-shadcn/README.md b/examples/03-columns-shadcn/README.md
index d1de682c..a6d0a8cb 100644
--- a/examples/03-columns-shadcn/README.md
+++ b/examples/03-columns-shadcn/README.md
@@ -19,23 +19,22 @@ examples/03-columns-shadcn/
 ├── vite.config.js                  # lib-mode IIFE; React → window.shinyreact
 ├── src/
 │   ├── App.jsx                     # composes Column → ItemRow with shadcn Card/Button
-│   ├── main.jsx                    # mounts via window.shinyreact.React/ReactDOM
+│   ├── ui.jsx                      # mounts via window.shinyreact.React/ReactDOM (appends its own container)
 │   ├── index.css                   # Tailwind v4 + shadcn theme tokens
 │   ├── lib/utils.js                # cn() = clsx + tailwind-merge
 │   └── components/ui/
 │       ├── button.jsx              # actual shadcn Button (cva variants)
 │       └── card.jsx                # actual shadcn Card stack
 └── www/
-    ├── index.html                  # 3 lines, committed
-    ├── app.js                      # built by Vite (gitignored)
-    └── style.css                   # built by Vite (gitignored)
+    ├── ui.js                       # built by Vite (gitignored)
+    └── ui.css                      # built by Vite (gitignored)
 ```
 
 ## Build plumbing
 
 Worth understanding because every shadcn-style example in this repo uses the same setup:
 
-- `vite.config.js` is in **lib mode** with `format: "iife"`, output filename `app.js`. We can't use Vite's regular HTML pipeline because we need a single self-contained bundle that reuses the page's existing React.
+- `vite.config.js` is in **lib mode** with `format: "iife"`, output filename `ui.js` — the name `set_react_page()` discovers, so the app file needs no arguments and no `index.html`. We can't use Vite's regular HTML pipeline because we need a single self-contained bundle that reuses the page's existing React.
 - `react`, `react-dom`, `react-dom/client` are listed as `external` and mapped via `rollupOptions.output.globals` to `window.shinyreact.React` / `window.shinyreact.ReactDOM`. The IIFE bundle reuses the React instance that owns the shinyreact hooks (mixing two React copies would break the hooks).
 - `@tailwindcss/vite` wires Tailwind v4 in directly; the shadcn design tokens live in `src/index.css`.
 - `define: { "process.env.NODE_ENV": '"production"' }` is set because lib mode does not auto-replace it (it assumes a downstream bundler will). Without it the bundled React jsx-runtime hits a `process is not defined` error in the browser.
diff --git a/examples/03-columns-shadcn/src/main.jsx b/examples/03-columns-shadcn/src/main.jsx
deleted file mode 100644
index 7e1137b6..00000000
--- a/examples/03-columns-shadcn/src/main.jsx
+++ /dev/null
@@ -1,8 +0,0 @@
-import "@/index.css";
-
-import App from "@/App";
-
-const { React, ReactDOM } = window.shinyreact;
-
-const root = ReactDOM.createRoot(document.getElementById("root"));
-root.render(React.createElement(App));
diff --git a/examples/03-columns-shadcn/src/ui.jsx b/examples/03-columns-shadcn/src/ui.jsx
new file mode 100644
index 00000000..e19e6126
--- /dev/null
+++ b/examples/03-columns-shadcn/src/ui.jsx
@@ -0,0 +1,12 @@
+import "@/index.css";
+
+import App from "@/App";
+
+const { React, ReactDOM } = window.shinyreact;
+
+// No index.html in this example -- the server page is generated by
+// set_react_page() discovery, so the app appends its own mount container.
+const root = ReactDOM.createRoot(
+  document.body.appendChild(document.createElement("div")),
+);
+root.render(React.createElement(App));
diff --git a/examples/03-columns-shadcn/vite.config.js b/examples/03-columns-shadcn/vite.config.js
index 0afcf25a..7962d843 100644
--- a/examples/03-columns-shadcn/vite.config.js
+++ b/examples/03-columns-shadcn/vite.config.js
@@ -22,14 +22,16 @@ export default defineConfig({
     emptyOutDir: false,
     cssCodeSplit: false,
     lib: {
-      entry: path.resolve(__dirname, "src/main.jsx"),
+      entry: path.resolve(__dirname, "src/ui.jsx"),
       formats: ["iife"],
       name: "ColumnsShadcn",
-      fileName: () => "app.js",
+      fileName: () => "ui.js",
     },
     rollupOptions: {
       external: ["react", "react-dom", "react-dom/client"],
       output: {
+        // Name the emitted CSS asset ui.css (Vite 5 lib mode defaults to style.css).
+        assetFileNames: "ui.[ext]",
         globals: {
           react: "window.shinyreact.React",
           "react-dom": "window.shinyreact.ReactDOM",
diff --git a/examples/03-columns-shadcn/www/index.html b/examples/03-columns-shadcn/www/index.html
deleted file mode 100644
index 11059352..00000000
--- a/examples/03-columns-shadcn/www/index.html
+++ /dev/null
@@ -1,3 +0,0 @@
-<link rel="stylesheet" href="style.css" />
-<div id="root"></div>
-<script src="app.js" defer></script>
diff --git a/examples/04-shadcn/.gitignore b/examples/04-shadcn/.gitignore
index 9558ca43..a790fdb1 100644
--- a/examples/04-shadcn/.gitignore
+++ b/examples/04-shadcn/.gitignore
@@ -1,4 +1,4 @@
 node_modules/
 package-lock.json
-www/app.js
-www/style.css
+www/ui.js
+www/ui.css
diff --git a/examples/04-shadcn/README.md b/examples/04-shadcn/README.md
index 9b24b6b3..563fe163 100644
--- a/examples/04-shadcn/README.md
+++ b/examples/04-shadcn/README.md
@@ -30,7 +30,7 @@ examples/04-shadcn/
 ├── README.md
 ├── src/
 │   ├── App.jsx                     # composes the cards
-│   ├── main.jsx                    # mounts via window.shinyreact.React/ReactDOM
+│   ├── ui.jsx                      # mounts via window.shinyreact.React/ReactDOM (appends its own container)
 │   ├── index.css                   # Tailwind v4 + shadcn theme tokens
 │   ├── lib/utils.js                # cn() = clsx + tailwind-merge
 │   └── components/
@@ -46,16 +46,15 @@ examples/04-shadcn/
 │           ├── input.jsx
 │           └── separator.jsx
 └── www/
-    ├── index.html                  # 3 lines, committed
-    ├── app.js                      # built by Vite (gitignored)
-    └── style.css                   # built by Vite (gitignored)
+    ├── ui.js                       # built by Vite (gitignored)
+    └── ui.css                      # built by Vite (gitignored)
 ```
 
 ## Build plumbing
 
 The non-obvious bit is how the bundle stays compatible with the page-level `window.shinyreact` runtime:
 
-- `vite.config.js` is in **lib mode** with format `iife`, output filename `app.js`.
+- `vite.config.js` is in **lib mode** with format `iife`, output filename `ui.js` — the name `set_react_page()` discovers, so the app file needs no arguments and no `index.html`.
 - `react`, `react-dom`, and `react-dom/client` are listed as `external` and mapped via `rollupOptions.output.globals` to `window.shinyreact.React` / `window.shinyreact.ReactDOM`. The IIFE bundle reuses the React instance that owns the shinyreact hooks (mixing two React copies would break the hooks).
 - `react`/`react-dom` are still listed as `devDependencies` so `react/jsx-runtime` resolves at build time when Vite's automatic JSX transform inlines it.
 - Tailwind v4 is wired in through `@tailwindcss/vite`; the shadcn design tokens live in `src/index.css`.
diff --git a/examples/04-shadcn/src/main.jsx b/examples/04-shadcn/src/main.jsx
deleted file mode 100644
index 7e1137b6..00000000
--- a/examples/04-shadcn/src/main.jsx
+++ /dev/null
@@ -1,8 +0,0 @@
-import "@/index.css";
-
-import App from "@/App";
-
-const { React, ReactDOM } = window.shinyreact;
-
-const root = ReactDOM.createRoot(document.getElementById("root"));
-root.render(React.createElement(App));
diff --git a/examples/04-shadcn/src/ui.jsx b/examples/04-shadcn/src/ui.jsx
new file mode 100644
index 00000000..e19e6126
--- /dev/null
+++ b/examples/04-shadcn/src/ui.jsx
@@ -0,0 +1,12 @@
+import "@/index.css";
+
+import App from "@/App";
+
+const { React, ReactDOM } = window.shinyreact;
+
+// No index.html in this example -- the server page is generated by
+// set_react_page() discovery, so the app appends its own mount container.
+const root = ReactDOM.createRoot(
+  document.body.appendChild(document.createElement("div")),
+);
+root.render(React.createElement(App));
diff --git a/examples/04-shadcn/vite.config.js b/examples/04-shadcn/vite.config.js
index 0afcf25a..7962d843 100644
--- a/examples/04-shadcn/vite.config.js
+++ b/examples/04-shadcn/vite.config.js
@@ -22,14 +22,16 @@ export default defineConfig({
     emptyOutDir: false,
     cssCodeSplit: false,
     lib: {
-      entry: path.resolve(__dirname, "src/main.jsx"),
+      entry: path.resolve(__dirname, "src/ui.jsx"),
       formats: ["iife"],
       name: "ColumnsShadcn",
-      fileName: () => "app.js",
+      fileName: () => "ui.js",
     },
     rollupOptions: {
       external: ["react", "react-dom", "react-dom/client"],
       output: {
+        // Name the emitted CSS asset ui.css (Vite 5 lib mode defaults to style.css).
+        assetFileNames: "ui.[ext]",
         globals: {
           react: "window.shinyreact.React",
           "react-dom": "window.shinyreact.ReactDOM",
diff --git a/examples/04-shadcn/www/index.html b/examples/04-shadcn/www/index.html
deleted file mode 100644
index 11059352..00000000
--- a/examples/04-shadcn/www/index.html
+++ /dev/null
@@ -1,3 +0,0 @@
-<link rel="stylesheet" href="style.css" />
-<div id="root"></div>
-<script src="app.js" defer></script>
diff --git a/examples/09-hmr/.gitignore b/examples/09-hmr/.gitignore
index 9c039c55..b428e492 100644
--- a/examples/09-hmr/.gitignore
+++ b/examples/09-hmr/.gitignore
@@ -1,3 +1,3 @@
 node_modules/
 package-lock.json
-www/app.js
+www/ui.js
diff --git a/examples/09-hmr/README.md b/examples/09-hmr/README.md
index 2d000165..63bba406 100644
--- a/examples/09-hmr/README.md
+++ b/examples/09-hmr/README.md
@@ -6,11 +6,11 @@ state — no full page reload, no `vite build` wait.
 
 ## How it works
 
-Shiny serves `www/index.html` (which loads `www/app.js` as a module) and the
+Shiny serves a `set_react_page()`-generated page (which loads `www/ui.js` as a module) and the
 reactive WebSocket. A Vite dev server serves your React modules with Fast
-Refresh. The dev server writes `www/app.js` as a tiny stub that pulls the HMR
+Refresh. The dev server writes `www/ui.js` as a tiny stub that pulls the HMR
 client + your entry from the dev server; `npm run build` overwrites it with the
-real bundle. `index.html` never changes between modes.
+real bundle. The served page never changes between modes.
 
 Component code lives in `src/App.tsx` (the Fast Refresh boundary). The entry
 `src/ui.tsx` only mounts it — keep `createRoot()` there, never in a file that
@@ -23,7 +23,7 @@ externalized to the shared `window.shinyreact`.
 ## Develop (two terminals)
 
 ```bash
-# terminal 1 — Vite dev server (writes www/app.js as a dev stub, serves HMR)
+# terminal 1 — Vite dev server (writes www/ui.js as a dev stub, serves HMR)
 npm install
 npm run dev
 
@@ -44,7 +44,7 @@ Open the URL Shiny prints. Editing `app.py` reloads via Shiny; editing
 ## Build for production
 
 ```bash
-npm run build          # writes www/app.js (the real bundle)
+npm run build          # writes www/ui.js (the real bundle)
 uv run shiny run app.py
 ```
 
diff --git a/examples/09-hmr/src/ui.tsx b/examples/09-hmr/src/ui.tsx
index bfef27f9..19a65ee2 100644
--- a/examples/09-hmr/src/ui.tsx
+++ b/examples/09-hmr/src/ui.tsx
@@ -6,4 +6,8 @@ import App from "./App";
 // clean. Editing THIS file triggers a full reload (rare); editing App.tsx does
 // not. Calling createRoot in a file that also defines components would defeat
 // Fast Refresh.
-ReactDOM.createRoot(document.getElementById("root")!).render(<App />);
+// No index.html in this example -- the server page is generated by
+// set_react_page() discovery, so the app appends its own mount container.
+ReactDOM.createRoot(
+  document.body.appendChild(document.createElement("div")),
+).render(<App />);
diff --git a/examples/09-hmr/vite-dev-stub.js b/examples/09-hmr/vite-dev-stub.js
index 10b481dc..2139b090 100644
--- a/examples/09-hmr/vite-dev-stub.js
+++ b/examples/09-hmr/vite-dev-stub.js
@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 
-// The contents of the dev-mode `www/app.js`. Shiny serves this file statically.
+// The contents of the dev-mode `www/ui.js`. Shiny serves this file statically.
 // It (1) installs the React Fast Refresh preamble that @vitejs/plugin-react
 // normally injects into the HTML it serves — but here Shiny serves the page, so
 // we install it ourselves — then (2) dynamically imports Vite's HMR client and
@@ -22,7 +22,7 @@ export function makeDevStub(origin, entry) {
 }
 
 // Vite plugin (serve only). On dev-server start it writes `outFile` (e.g.
-// www/app.js) as the dev stub, and removes it on shutdown so a later plain
+// www/ui.js) as the dev stub, and removes it on shutdown so a later plain
 // `shiny run` doesn't load a stub pointing at a dead dev server. `vite build`
 // (apply:"serve" excludes this plugin) overwrites `outFile` with the real bundle.
 export function shinyreactDevStub({ entry, outFile }) {
diff --git a/examples/09-hmr/vite.config.js b/examples/09-hmr/vite.config.js
index 0962756a..742ac41c 100644
--- a/examples/09-hmr/vite.config.js
+++ b/examples/09-hmr/vite.config.js
@@ -18,7 +18,7 @@ export default defineConfig(({ command }) => ({
   plugins: [
     react(),
     // serve only: writes www/app.js as the dev stub (apply:"serve" inside).
-    shinyreactDevStub({ entry: ENTRY, outFile: "www/app.js" }),
+    shinyreactDevStub({ entry: ENTRY, outFile: "www/ui.js" }),
   ],
   resolve: {
     // One React instance across App.tsx and the bundled shiny-react source.
@@ -43,7 +43,7 @@ export default defineConfig(({ command }) => ({
       entry: path.resolve(__dirname, ENTRY),
       formats: ["iife"],
       name: "HmrExample",
-      fileName: () => "app.js",
+      fileName: () => "ui.js",
     },
     rollupOptions: {
       external: ["react", "react-dom", "react-dom/client"],
diff --git a/examples/09-hmr/www/index.html b/examples/09-hmr/www/index.html
deleted file mode 100644
index a80fc4b3..00000000
--- a/examples/09-hmr/www/index.html
+++ /dev/null
@@ -1,2 +0,0 @@
-<div id="root"></div>
-<script type="module" src="app.js"></script>

From 45f3e91c927188e9597bce9c5327b4f10a687f97 Mon Sep 17 00:00:00 2001
From: Barret Schloerke <barret@posit.co>
Date: Thu, 20 Aug 2026 11:19:48 -0400
Subject: [PATCH 3/5] refactor: page_react_dep() defaults follow the
 ui.js/ui.css convention

- main.js/main.css defaults were inconsistent with page_react()'s
  discovery names; one convention everywhere (#205)
- Update default-exercising tests in both languages; fix a stale
  dev-stub comment in 09-hmr's vite config
---
 examples/09-hmr/vite.config.js             |  2 +-
 pkg-py/src/shinyreact/_page.py             | 10 +++----
 pkg-py/tests/test_dep.py                   | 32 +++++++++++-----------
 pkg-py/tests/test_page.py                  |  2 +-
 pkg-r/R/page.R                             |  8 +++---
 pkg-r/man/page_react_dep.Rd                |  8 +++---
 pkg-r/tests/testthat/test-page-react-dep.R | 28 +++++++++----------
 7 files changed, 45 insertions(+), 45 deletions(-)

diff --git a/examples/09-hmr/vite.config.js b/examples/09-hmr/vite.config.js
index 742ac41c..c0a1dae0 100644
--- a/examples/09-hmr/vite.config.js
+++ b/examples/09-hmr/vite.config.js
@@ -17,7 +17,7 @@ export default defineConfig(({ command }) => ({
   },
   plugins: [
     react(),
-    // serve only: writes www/app.js as the dev stub (apply:"serve" inside).
+    // serve only: writes www/ui.js as the dev stub (apply:"serve" inside).
     shinyreactDevStub({ entry: ENTRY, outFile: "www/ui.js" }),
   ],
   resolve: {
diff --git a/pkg-py/src/shinyreact/_page.py b/pkg-py/src/shinyreact/_page.py
index 7afe2e46..7d89c609 100644
--- a/pkg-py/src/shinyreact/_page.py
+++ b/pkg-py/src/shinyreact/_page.py
@@ -67,7 +67,7 @@ def page_react(
     *args: TagChild,
     src_dir: str | Path | None = None,
     js_file: str = "ui.js",
-    css_file: str = "ui.css",
+    css_file: str | None = "ui.css",
     title: str | None = None,
     lang: str = "en",
 ) -> Tag:
@@ -116,8 +116,8 @@ def page_react(
 def page_react_dep(
     *,
     src_dir: str | Path | None = None,
-    js_file: str = "main.js",
-    css_file: str | None = "main.css",
+    js_file: str = "ui.js",
+    css_file: str | None = "ui.css",
     name: str | None = None,
 ) -> HTMLDependency:
     """Build an HTMLDependency for a React app's JS and CSS entry points.
@@ -172,9 +172,9 @@ def page_react_dep(
         src_dir: Directory containing the JS/CSS. Inferred from the calling
             frame when omitted (see above).
         js_file: Filename of the JS entry point, relative to ``src_dir``
-            (default ``"main.js"``). Attached only if the file exists.
+            (default ``"ui.js"``). Attached only if the file exists.
         css_file: Filename of the CSS file, relative to ``src_dir`` (default
-            ``"main.css"``). Attached only if the file exists; ``None`` to skip.
+            ``"ui.css"``). Attached only if the file exists; ``None`` to skip.
         name: Dependency name. Defaults to ``src_dir``'s basename.
     """
     if src_dir is not None:
diff --git a/pkg-py/tests/test_dep.py b/pkg-py/tests/test_dep.py
index 654fbbb1..ec45cbe9 100644
--- a/pkg-py/tests/test_dep.py
+++ b/pkg-py/tests/test_dep.py
@@ -35,8 +35,8 @@ def test_dep_script_has_defer():
 def _run_page_react_dep(
     tmp_path: Path,
     *,
-    js_file: str = "main.js",
-    css_file: str = "main.css",
+    js_file: str = "ui.js",
+    css_file: str = "ui.css",
 ) -> HTMLDependency:
     """Call page_react_dep() from a script located in tmp_path."""
     app_file = tmp_path / "app.py"
@@ -50,8 +50,8 @@ def _run_page_react_dep(
 
 
 def test_page_react_dep_returns_htmldependency(tmp_path):
-    (tmp_path / "main.js").write_text("// app")
-    (tmp_path / "main.css").write_text("/* styles */")
+    (tmp_path / "ui.js").write_text("// app")
+    (tmp_path / "ui.css").write_text("/* styles */")
 
     dep = _run_page_react_dep(tmp_path)
     assert isinstance(dep, HTMLDependency)
@@ -60,9 +60,9 @@ def test_page_react_dep_returns_htmldependency(tmp_path):
 
 
 def test_page_react_dep_uses_mtime_version(tmp_path):
-    js = tmp_path / "main.js"
+    js = tmp_path / "ui.js"
     js.write_text("// app")
-    (tmp_path / "main.css").write_text("/* styles */")
+    (tmp_path / "ui.css").write_text("/* styles */")
 
     dep = _run_page_react_dep(tmp_path)
     expected_version = str(int(js.stat().st_mtime))
@@ -85,11 +85,11 @@ def test_page_react_dep_omits_script_when_js_absent(tmp_path):
 
 
 def test_page_react_dep_attaches_script_when_js_present(tmp_path):
-    (tmp_path / "main.js").write_text("// app")
+    (tmp_path / "ui.js").write_text("// app")
 
     dep = page_react_dep(src_dir=tmp_path)
     script = dep.script if isinstance(dep.script, dict) else dep.script[0]
-    assert script["src"] == "main.js"
+    assert script["src"] == "ui.js"
     assert script.get("type") == "module"
 
 
@@ -107,8 +107,8 @@ def test_page_react_dep_custom_filenames(tmp_path):
 
 
 def test_page_react_dep_script_type_module(tmp_path):
-    (tmp_path / "main.js").write_text("// app")
-    (tmp_path / "main.css").write_text("/* styles */")
+    (tmp_path / "ui.js").write_text("// app")
+    (tmp_path / "ui.css").write_text("/* styles */")
 
     dep = _run_page_react_dep(tmp_path)
     script = dep.script if isinstance(dep.script, dict) else dep.script[0]
@@ -121,18 +121,18 @@ def test_page_react_dep_explicit_src_dir_and_name(tmp_path):
     Frame inspection reads the *immediate* caller, so wrapping page_react_dep()
     in a helper would otherwise resolve against the wrapper's directory (#184).
     """
-    (tmp_path / "main.js").write_text("// app")
+    (tmp_path / "ui.js").write_text("// app")
 
     dep = page_react_dep(src_dir=tmp_path, name="my-app")
     assert dep.source is not None
     assert dep.source["subdir"] == str(tmp_path)
     assert dep.name == "my-app"
-    assert str(dep.version) == str(int((tmp_path / "main.js").stat().st_mtime))
+    assert str(dep.version) == str(int((tmp_path / "ui.js").stat().st_mtime))
 
 
 def test_page_react_dep_omits_stylesheet_when_css_absent(tmp_path):
     """A bundle with no CSS must not emit a 404-ing stylesheet link (#184)."""
-    (tmp_path / "main.js").write_text("// app")
+    (tmp_path / "ui.js").write_text("// app")
 
     # htmltools normalizes an absent stylesheet to an empty list.
     assert page_react_dep(src_dir=tmp_path).stylesheet == []
@@ -140,10 +140,10 @@ def test_page_react_dep_omits_stylesheet_when_css_absent(tmp_path):
 
 
 def test_page_react_dep_attaches_stylesheet_when_css_present(tmp_path):
-    (tmp_path / "main.js").write_text("// app")
-    (tmp_path / "main.css").write_text("/* styles */")
+    (tmp_path / "ui.js").write_text("// app")
+    (tmp_path / "ui.css").write_text("/* styles */")
 
     stylesheet = page_react_dep(src_dir=tmp_path).stylesheet
     assert stylesheet is not None
     entry = stylesheet if isinstance(stylesheet, dict) else stylesheet[0]
-    assert entry["href"] == "main.css"
+    assert entry["href"] == "ui.css"
diff --git a/pkg-py/tests/test_page.py b/pkg-py/tests/test_page.py
index aca22b67..a4a145fa 100644
--- a/pkg-py/tests/test_page.py
+++ b/pkg-py/tests/test_page.py
@@ -31,7 +31,7 @@ def test_page_bare_no_shinyreact_dep():
 
 def test_page_react_dep_falls_back_to_cwd_without_file(tmp_path, monkeypatch):
     """page_react_dep() falls back to CWD when the caller has no __file__."""
-    (tmp_path / "main.js").write_text("// ...")
+    (tmp_path / "ui.js").write_text("// ...")
     monkeypatch.chdir(tmp_path)
 
     captured: dict[str, HTMLDependency] = {}
diff --git a/pkg-r/R/page.R b/pkg-r/R/page.R
index c10a3cd9..ae85f804 100644
--- a/pkg-r/R/page.R
+++ b/pkg-r/R/page.R
@@ -138,17 +138,17 @@ page_react_html <- function(path = "www/index.html") {
 #' @param src_dir Directory containing the JS/CSS. Required; Python infers this
 #'   from the calling module's `__file__` when omitted, which R has no
 #'   equivalent of.
-#' @param js_file JS filename within `src_dir`. Defaults to `"main.js"`,
+#' @param js_file JS filename within `src_dir`. Defaults to `"ui.js"`,
 #'   matching Python; attached only if the file exists.
-#' @param css_file CSS filename within `src_dir`. Defaults to `"main.css"`,
+#' @param css_file CSS filename within `src_dir`. Defaults to `"ui.css"`,
 #'   matching Python; attached only if the file exists. `NULL` to skip.
 #' @param name Dependency name; defaults to `basename(src_dir)`.
 #' @return An [htmltools::htmlDependency].
 #' @export
 page_react_dep <- function(
   src_dir,
-  js_file = "main.js",
-  css_file = "main.css",
+  js_file = "ui.js",
+  css_file = "ui.css",
   name = basename(src_dir)
 ) {
   js_path <- file.path(src_dir, js_file)
diff --git a/pkg-r/man/page_react_dep.Rd b/pkg-r/man/page_react_dep.Rd
index 121ded5b..f608f682 100644
--- a/pkg-r/man/page_react_dep.Rd
+++ b/pkg-r/man/page_react_dep.Rd
@@ -6,8 +6,8 @@
 \usage{
 page_react_dep(
   src_dir,
-  js_file = "main.js",
-  css_file = "main.css",
+  js_file = "ui.js",
+  css_file = "ui.css",
   name = basename(src_dir)
 )
 }
@@ -16,10 +16,10 @@ page_react_dep(
 from the calling module's \verb{__file__} when omitted, which R has no
 equivalent of.}
 
-\item{js_file}{JS filename within \code{src_dir}. Defaults to \code{"main.js"},
+\item{js_file}{JS filename within \code{src_dir}. Defaults to \code{"ui.js"},
 matching Python; attached only if the file exists.}
 
-\item{css_file}{CSS filename within \code{src_dir}. Defaults to \code{"main.css"},
+\item{css_file}{CSS filename within \code{src_dir}. Defaults to \code{"ui.css"},
 matching Python; attached only if the file exists. \code{NULL} to skip.}
 
 \item{name}{Dependency name; defaults to \code{basename(src_dir)}.}
diff --git a/pkg-r/tests/testthat/test-page-react-dep.R b/pkg-r/tests/testthat/test-page-react-dep.R
index b65eae0d..b5fca81c 100644
--- a/pkg-r/tests/testthat/test-page-react-dep.R
+++ b/pkg-r/tests/testthat/test-page-react-dep.R
@@ -1,8 +1,8 @@
 test_that("page_react_dep() returns an html_dependency pointing at src_dir", {
   dir <- withr::local_tempdir()
-  writeLines("// app", file.path(dir, "main.js"))
+  writeLines("// app", file.path(dir, "ui.js"))
 
-  dep <- page_react_dep(dir, "main.js")
+  dep <- page_react_dep(dir, "ui.js")
   expect_s3_class(dep, "html_dependency")
   expect_identical(dep$src$file, dir)
   expect_identical(dep$name, basename(dir))
@@ -10,16 +10,16 @@ test_that("page_react_dep() returns an html_dependency pointing at src_dir", {
 
 test_that("page_react_dep() versions by the JS file's mtime", {
   dir <- withr::local_tempdir()
-  js <- file.path(dir, "main.js")
+  js <- file.path(dir, "ui.js")
   writeLines("// app", js)
 
-  dep <- page_react_dep(dir, "main.js")
+  dep <- page_react_dep(dir, "ui.js")
   expect_identical(dep$version, as.character(as.integer(file.mtime(js))))
 })
 
 test_that("page_react_dep() falls back to version \"0\" when the JS is missing", {
   dir <- withr::local_tempdir()
-  expect_warning(dep <- page_react_dep(dir, "main.js"), "JS entry point")
+  expect_warning(dep <- page_react_dep(dir, "ui.js"), "JS entry point")
   expect_identical(dep$version, "0")
 })
 
@@ -42,20 +42,20 @@ test_that("page_react_dep() honours custom filenames and the name override", {
   expect_identical(dep$stylesheet, "app.css")
 })
 
-test_that("page_react_dep() defaults to main.js / main.css like Python", {
+test_that("page_react_dep() defaults to ui.js / ui.css like Python", {
   dir <- withr::local_tempdir()
-  writeLines("// app", file.path(dir, "main.js"))
-  writeLines("/* styles */", file.path(dir, "main.css"))
+  writeLines("// app", file.path(dir, "ui.js"))
+  writeLines("/* styles */", file.path(dir, "ui.css"))
 
   dep <- page_react_dep(dir)
-  expect_identical(dep$script[["src"]], "main.js")
-  expect_identical(dep$stylesheet, "main.css")
+  expect_identical(dep$script[["src"]], "ui.js")
+  expect_identical(dep$stylesheet, "ui.css")
 })
 
 test_that("page_react_dep() omits the stylesheet when the CSS is absent", {
-  # A bundle that ships no CSS should not 404 on main.css (#184).
+  # A bundle that ships no CSS should not 404 on ui.css (#184).
   dir <- withr::local_tempdir()
-  writeLines("// app", file.path(dir, "main.js"))
+  writeLines("// app", file.path(dir, "ui.js"))
 
   expect_null(page_react_dep(dir)$stylesheet)
   expect_null(page_react_dep(dir, css_file = NULL)$stylesheet)
@@ -65,9 +65,9 @@ test_that("page_react_dep() emits script type=\"module\" and no defer", {
   # Matches Python (`page_react_dep()` in _page.py); an ESM bundle throws on
   # its first `import` when served from a classic <script> tag. See #182.
   dir <- withr::local_tempdir()
-  writeLines("// app", file.path(dir, "main.js"))
+  writeLines("// app", file.path(dir, "ui.js"))
 
-  dep <- page_react_dep(dir, "main.js")
+  dep <- page_react_dep(dir, "ui.js")
   expect_identical(dep$script[["type"]], "module")
   expect_null(dep$script[["defer"]])
 

From 33da98fdf17bad69e592ceaddf2257f20f0a8310 Mon Sep 17 00:00:00 2001
From: Barret Schloerke <barret@posit.co>
Date: Thu, 20 Aug 2026 11:32:23 -0400
Subject: [PATCH 4/5] refactor(examples,docs): adopt ui.js/ui.css across
 no-build examples

- Convert 01,02,05,06,07,08,10 to page_react()-style discovery: rename
  www/app.js -> www/ui.js (+ css -> ui.css), delete the index.html
  fragments, mount by appending to <body>
- 01-hello app-core.py and app.R switch to page_react(); the
  static_assets mount is no longer needed (assets serve via the
  mtime-versioned dependency)
- Update terminology docs (README, CLAUDE.md, DESIGN.md, examples
  catalog, pkg READMEs): the no-build role name is ui.js, the Vite
  entry role is ui.jsx/ui.tsx; refresh CLAUDE.md API descriptions for
  set_react_page(path=None), page_react(), and the R/Python
  page_react_html divergence
---
 CLAUDE.md                                     | 14 ++++++-----
 DESIGN.md                                     |  8 +++----
 README.md                                     |  2 +-
 examples/01-hello/README.md                   | 24 +++++++++----------
 examples/01-hello/app-core.py                 | 13 ++++------
 examples/01-hello/app.R                       |  2 +-
 examples/01-hello/www/index.html              |  2 --
 examples/01-hello/www/{main.css => ui.css}    |  0
 examples/01-hello/www/{app.js => ui.js}       |  2 +-
 examples/02-columns/README.md                 |  5 ++--
 examples/02-columns/www/index.html            |  3 ---
 examples/02-columns/www/{main.css => ui.css}  |  0
 examples/02-columns/www/{app.js => ui.js}     |  6 ++++-
 examples/05-temperature/www/index.html        |  3 ---
 .../05-temperature/www/{main.css => ui.css}   |  0
 examples/05-temperature/www/{app.js => ui.js} |  6 ++++-
 examples/06-data-frame/www/index.html         |  2 --
 examples/06-data-frame/www/{app.js => ui.js}  |  6 ++++-
 examples/07-plotly/www/index.html             |  2 --
 examples/07-plotly/www/{app.js => ui.js}      |  6 ++++-
 examples/08-input-handler/www/index.html      |  3 ---
 .../08-input-handler/www/{main.css => ui.css} |  0
 .../08-input-handler/www/{app.js => ui.js}    |  6 ++++-
 examples/10-bookmarking/www/index.html        |  3 ---
 .../10-bookmarking/www/{styles.css => ui.css} |  0
 examples/10-bookmarking/www/{app.js => ui.js} |  6 ++++-
 examples/README.md                            |  6 ++---
 pkg-py/README.md                              | 16 ++++---------
 pkg-r/README.md                               |  4 ++--
 29 files changed, 74 insertions(+), 76 deletions(-)
 delete mode 100644 examples/01-hello/www/index.html
 rename examples/01-hello/www/{main.css => ui.css} (100%)
 rename examples/01-hello/www/{app.js => ui.js} (98%)
 delete mode 100644 examples/02-columns/www/index.html
 rename examples/02-columns/www/{main.css => ui.css} (100%)
 rename examples/02-columns/www/{app.js => ui.js} (89%)
 delete mode 100644 examples/05-temperature/www/index.html
 rename examples/05-temperature/www/{main.css => ui.css} (100%)
 rename examples/05-temperature/www/{app.js => ui.js} (91%)
 delete mode 100644 examples/06-data-frame/www/index.html
 rename examples/06-data-frame/www/{app.js => ui.js} (81%)
 delete mode 100644 examples/07-plotly/www/index.html
 rename examples/07-plotly/www/{app.js => ui.js} (83%)
 delete mode 100644 examples/08-input-handler/www/index.html
 rename examples/08-input-handler/www/{main.css => ui.css} (100%)
 rename examples/08-input-handler/www/{app.js => ui.js} (84%)
 delete mode 100644 examples/10-bookmarking/www/index.html
 rename examples/10-bookmarking/www/{styles.css => ui.css} (100%)
 rename examples/10-bookmarking/www/{app.js => ui.js} (89%)

diff --git a/CLAUDE.md b/CLAUDE.md
index 3cdf508e..17909b53 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -6,13 +6,13 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 `shinyreact` is a monorepo providing React UI infrastructure for Shiny (Python and R). It provides zero UI components — it is the bridge between a Shiny server that contains only reactive computation and a React client the app author owns.
 
-The repo ships one first-class pattern: the **`ui.tsx` pattern** — `set_react_page()` (Python Express) / `page_react_html()` (Python Core, R) bootstraps a static `www/index.html` hosting a React client whose entry conventionally lives in `ui.tsx`; the client and server communicate through the `useShinyInput` / `useShinyOutputValue` hook family. See `DESIGN.md` for background.
+The repo ships one first-class pattern: the **`ui.tsx` pattern** — `set_react_page()` (Python Express) / `page_react()` (Python Core, R) bootstraps a React client whose entry conventionally lives in `ui.tsx` (compiled to `www/ui.js`, discovered automatically); the client and server communicate through the `useShinyInput` / `useShinyOutputValue` hook family. See `DESIGN.md` for background.
 
 ## Terminology
 
 **`ui.tsx`** is the canonical name of the pattern. **Never write "SPA", "Single Page App", "Single-Page Application", "traditional pattern", `client-ui`, or `ui-object`** in new content (docs, comments, commit messages, PR/issue text).
 
-- **`ui.tsx` pattern** — UI defined in a client-side codebase whose entry is conventionally `ui.tsx` (or `App.jsx`, or `app.js` for no-build); bootstrapped from the app file via `set_react_page()` / `page_react_html()`. `ui.tsx` is the *idiomatic* canonical name — examples may use simpler variants like `www/app.js` (no-build) or `src/App.jsx` (Vite + JSX). Treat `ui.tsx` as a *role label* for the React entry, not a strict filename requirement.
+- **`ui.tsx` pattern** — UI defined in a client-side codebase whose entry is conventionally `ui.tsx` (or `ui.jsx`, or `ui.js` for no-build); bootstrapped from the app file via `set_react_page()` / `page_react()` (or `page_react_html()` for apps that own a full HTML document). `ui.tsx` is the *idiomatic* canonical name — examples use the same role at different tiers: `www/ui.js` (no-build) or `src/ui.jsx` (Vite + JSX, built to `www/ui.js`). Treat `ui.tsx` as a *role label* for the React entry, not a strict filename requirement.
 - The phrase "traditional Shiny" is fine when it refers to vanilla Shiny (no shinyreact involved).
 - The repo formerly also shipped an **`app.py` pattern** (server-side JSON-spec rendering via `Node` / `render_react` / `page_react`). It was removed in #168; see the tracking comment on #167 for git-history pointers if you encounter stale references.
 
@@ -91,17 +91,19 @@ The JS output (`pkg-js/dist/shinyreact.js`) is a self-contained IIFE that bundle
 
 - `@shinyreact.reactive_output` — `Renderer[Jsonifiable]` subclass; passes raw JSON data through for `useShinyOutputValue()` hooks, with no placeholder (`auto_output_ui()` returns `None`)
 - `shinyreact.send_message(session, type, data)` — sends `shinyReactMessage` custom messages consumed by `useShinyMessageHandler()`
-- `shinyreact.set_react_page(path="www/index.html")` — Express helper that serves a static `www/index.html`; auto-discovers `HTMLDependency` objects from traditional Shiny renderers and injects the shinyreact dep
-- `shinyreact.page_react_html(path="www/index.html")` — Core-mode helper that serves a static `www/index.html` as the `ui` argument of `App(ui=..., server=...)`; attaches the shinyreact dep. The Core counterpart to the Express-only `set_react_page()`. Unlike `set_react_page`, it does not auto-discover renderer dependencies
+- `shinyreact.set_react_page(path=None)` — Express helper; with no args serves `www/index.html` when present, else discovers `www/ui.js` / `www/ui.css` and emits no body HTML. Auto-discovers `HTMLDependency` objects from traditional Shiny renderers and injects the shinyreact dep
+- `shinyreact.page_react(src_dir=None, js_file="ui.js", css_file="ui.css", title=None)` — Core-mode zero-config page: discovers `www/ui.js` / `www/ui.css` next to the calling module, serves them as an mtime-versioned dependency (cache-busted), title defaults to the app folder name; the client appends its own mount container to `<body>`
+- `shinyreact.page_react_html(path="www/index.html")` — Core-mode helper that serves an HTML file as the `ui` argument of `App(ui=..., server=...)`; attaches the shinyreact dep. In Python the file is a body *fragment* (full-document support is blocked on an upstream py-shiny gap); in R it must be a complete document with a `{{ headContent() }}` marker (htmltools `htmlTemplate()`). Neither auto-discovers renderer dependencies
 - `shinyreact.page_bare(...)` / `shinyreact.page_react_dep(...)` — escape-hatch page builder and app-bundle `HTMLDependency` helper
 - Bookmark restore + protocol handshake: page entry points emit a `<script type="application/json" id="shinyreact-config">` tag carrying the wire-protocol version and any restored input values (`_bookmark.py` / `bookmark.R`); the bundle asserts the protocol major version and seeds `useShinyInput` initial values from it; the config tag is the only delivery channel (`window.shinyreact._restore` is a write-only DevTools sentinel)
 
 ### R package
 
-The R package (`pkg-r/`) mirrors the Python API in R idioms; exports are `reactive_output`, `page_bare`, `page_react_html`, `page_react_dep`, `send_message`. Key shape differences from Python:
+The R package (`pkg-r/`) mirrors the Python API in R idioms; exports are `reactive_output`, `page_bare`, `page_react`, `page_react_html`, `page_react_dep`, `send_message`. Key shape differences from Python:
 
 - `reactive_output(expr, ...)` is a **function** assigned to `output$id`, not a decorator/`Renderer` class.
-- `page_react_html(path = "www/index.html")` matches Python's `page_react_html()`; Python additionally has the Express-only `set_react_page()`.
+- `page_react(src_dir = "www", ...)` matches Python's `page_react()` (R resolves against the working directory; Python against the calling module).
+- `page_react_html(path = "www/index.html")` requires a complete HTML document with a `{{ headContent() }}` marker — unlike Python's, which still takes a body fragment (upstream py-shiny gap; see the `page_react_html` docstring). Python additionally has the Express-only `set_react_page()`.
 - `send_message(session, type, data)` matches Python.
 - `page_react_dep()` takes `src_dir` as a required first argument; Python's is keyword-only and infers `src_dir`/`name` from the caller's `__file__` when omitted (R has no equivalent). Pass `src_dir=` explicitly in Python too if you wrap the call in a helper — the inference reads the *immediate* calling frame.
 
diff --git a/DESIGN.md b/DESIGN.md
index b3aedc3b..ff7c233d 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -131,13 +131,13 @@ A Shiny app under the ui.tsx-first model consists of two parts:
 my-app/
   app.py              # Server logic: reactive computations, data access, business logic
   package.json        # JS dependencies (AI-generated)
-  index.html          # Entry point for the React app (AI-generated)
   src/                # Client source (AI-generated)
+    ui.jsx            # Entry point for the React app
     App.jsx
     styles.css
-  dist/               # Built bundle (generated by build step, served by Shiny)
-    app.js
-    styles.css
+  www/                # Built bundle (generated by build step, served by Shiny)
+    ui.js
+    ui.css
 ```
 
 The author owns `app.py`. Everything else is generated by AI (Claude or equivalent), typically via a Claude Skill or similar tooling that understands Shiny's client-server bridge. The `package.json` declares dependencies on the Shiny client runtime (`@posit/shiny`), the bridge hooks (`@posit/shinyreact`), React, and any component libraries. The build step (managed by `shiny run` or equivalent) resolves dependencies and bundles `src/` into `dist/`.
diff --git a/README.md b/README.md
index 62a060ef..91b4e519 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@ This repo ships per-language packages:
 
 ## How it works
 
-`shinyreact` implements the **`ui.tsx` pattern**: UI defined in a client codebase whose entry conventionally lives in `ui.tsx` (or `App.jsx`, or `app.js` for no-build):
+`shinyreact` implements the **`ui.tsx` pattern**: UI defined in a client codebase whose entry conventionally lives in `ui.tsx` (or `ui.jsx`, or `ui.js` for no-build):
 
 1. The Shiny server contains only reactive computation; it bootstraps a static page — `set_react_page()` (Express) or `page_react_html()` (Core) in Python, `page_react_html()` in R
 2. A static `www/index.html` plus your React client serve the UI
diff --git a/examples/01-hello/README.md b/examples/01-hello/README.md
index 2e11c287..be18954c 100644
--- a/examples/01-hello/README.md
+++ b/examples/01-hello/README.md
@@ -3,7 +3,7 @@
 Shiny's canonical [`01_hello`](https://github.com/rstudio/shiny/blob/main/inst/examples-shiny/01_hello/app.R)
 app — a bins slider over the Old Faithful waiting times — rebuilt as the
 smallest possible `ui.tsx`-first app. No JSX, no bundler, no `package.json`.
-Edit `app.js` and reload.
+Edit `ui.js` and reload.
 
 `app.py` (Express, via `set_react_page()`) and `app-core.py` (Core, via
 `page_react_html()`) are two server-side entries for the same `www/` client;
@@ -20,7 +20,7 @@ produces a picture:
   from R's `hist(..., plot = FALSE)` / a dependency-free Python binner), plus a
   caption string. That's the entire server. No plotting library, no image
   encoding, no `plotOutput` placeholder.
-- **Client** — `www/app.js` reads that JSON with `useShinyOutputValue` and draws
+- **Client** — `www/ui.js` reads that JSON with `useShinyOutputValue` and draws
   the bars as SVG `<rect>`s. Because the chart is real DOM the client owns, it
   can be styled, animated, or made interactive without another round trip.
 
@@ -37,14 +37,13 @@ never tears the SVG down and re-mounts it.
 ```
 examples/01-hello/
 ├── app.py            # Express: set_react_page() + 2 reactive_output outputs
-├── app-core.py       # Core: page_react_html() + App(..., static_assets=), same outputs
-├── app.R             # R: page_react_html() + reactive_output, same outputs
+├── app-core.py       # Core: page_react() + App(app_ui, server), same outputs
+├── app.R             # R: page_react() + reactive_output, same outputs
 ├── faithful.py       # Old Faithful waiting times + a stdlib-only binner (Python)
 ├── faithful.csv      # base R's `faithful` dataset, exported for the Python servers
 └── www/
-    ├── index.html    # 2 lines: stylesheet, script (the app appends its own mount div to <body>)
-    ├── app.js        # raw React.createElement (with `h` shorthand) + an SVG histogram
-    └── main.css      # sidebar/panel layout
+    ├── ui.js         # raw React.createElement (with `h` shorthand) + an SVG histogram
+    └── ui.css        # sidebar/panel layout
 ```
 
 No `node_modules`, no Vite, no build script — and on the Python side no
@@ -56,14 +55,15 @@ return `NULL` until the client's first `bins` message arrives (Python raises a
 silent exception instead), and wrap the histogram vectors in `I()` so a
 single-bin result still serializes as a JSON array rather than a scalar.
 
-`app-core.py` passes `static_assets={"/": .../www}` to `App()`. Shiny Express
-(`app.py`) and R's `runApp()` (`app.R`) both mount the app directory's `www/`
-automatically; Core's `App()` does not, so without it `index.html` loads and
-then 404s on `app.js` and `main.css`.
+There is no `index.html`: every server calls a zero-argument page function
+(`set_react_page()` / `page_react()`) that discovers `www/ui.js` and
+`www/ui.css` and serves them as an mtime-versioned dependency — so edits are
+never stale in the browser cache, and Core's `App()` needs no
+`static_assets=` mount. The client appends its own container to `<body>`.
 
 ## Bridge primitives used
 
-- `from shinyreact import reactive_output, set_react_page` (Express server, `app.py`) / `page_react_html` (Core server, `app-core.py`); `library(shinyreact)` with `page_react_html()` + `reactive_output()` in `app.R`
+- `from shinyreact import reactive_output, set_react_page` (Express server, `app.py`) / `page_react` (Core server, `app-core.py`); `library(shinyreact)` with `page_react()` + `reactive_output()` in `app.R`
 - `window.shinyreact.useShinyInput(id, default)` for the bins slider
 - `window.shinyreact.useShinyOutputValue(id, default)` for the histogram data and caption
 - `window.shinyreact.useShinyOutputStatus(id)` to dim the chart while it recalculates
diff --git a/examples/01-hello/app-core.py b/examples/01-hello/app-core.py
index 0fbb6fb6..0608b07b 100644
--- a/examples/01-hello/app-core.py
+++ b/examples/01-hello/app-core.py
@@ -1,10 +1,8 @@
-from pathlib import Path
-
 from faithful import histogram, waiting
 from shiny import App, Inputs, Outputs, Session
-from shinyreact import page_react_html, reactive_output
+from shinyreact import page_react, reactive_output
 
-app_ui = page_react_html()  # serves www/index.html (Core API)
+app_ui = page_react()  # discovers www/ui.js + www/ui.css (Core API)
 
 
 def server(input: Inputs, output: Outputs, session: Session):
@@ -18,7 +16,6 @@ def dist_caption():
         return f"{len(waiting)} eruptions in {n} bin{'' if n == 1 else 's'}"
 
 
-# Core apps must mount www/ themselves. Shiny Express auto-serves the app
-# directory's www/ at "/", but App() does not — without this, index.html loads
-# and then 404s on app.js and main.css.
-app = App(app_ui, server, static_assets={"/": Path(__file__).parent / "www"})
+# page_react() serves ui.js/ui.css itself (an mtime-versioned dependency), so
+# no static_assets mount is needed for them.
+app = App(app_ui, server)
diff --git a/examples/01-hello/app.R b/examples/01-hello/app.R
index be9718fd..01d56c5c 100644
--- a/examples/01-hello/app.R
+++ b/examples/01-hello/app.R
@@ -5,7 +5,7 @@ library(shinyreact)
 # from the faithful.csv exported next to this file.
 waiting <- faithful$waiting
 
-ui <- page_react_html("www/index.html")
+ui <- page_react() # discovers www/ui.js + www/ui.css
 
 server <- function(input, output, session) {
   # input$bins is NULL until the client's first useShinyInput("bins", 30)
diff --git a/examples/01-hello/www/index.html b/examples/01-hello/www/index.html
deleted file mode 100644
index 880e7633..00000000
--- a/examples/01-hello/www/index.html
+++ /dev/null
@@ -1,2 +0,0 @@
-<link rel="stylesheet" href="main.css" />
-<script src="app.js" defer></script>
diff --git a/examples/01-hello/www/main.css b/examples/01-hello/www/ui.css
similarity index 100%
rename from examples/01-hello/www/main.css
rename to examples/01-hello/www/ui.css
diff --git a/examples/01-hello/www/app.js b/examples/01-hello/www/ui.js
similarity index 98%
rename from examples/01-hello/www/app.js
rename to examples/01-hello/www/ui.js
index b5a85903..65c170d9 100644
--- a/examples/01-hello/www/app.js
+++ b/examples/01-hello/www/ui.js
@@ -183,7 +183,7 @@ function App() {
   );
 }
 
-// No mount div in index.html — create the container and append it to <body>.
+// No mount div in the generated page — create the container and append it to <body>.
 // The script is deferred, so document.body is parsed by the time this runs.
 const root = ReactDOM.createRoot(
   document.body.appendChild(document.createElement("div")),
diff --git a/examples/02-columns/README.md b/examples/02-columns/README.md
index dfcd901f..e727861d 100644
--- a/examples/02-columns/README.md
+++ b/examples/02-columns/README.md
@@ -21,9 +21,8 @@ The result: ~20 lines of server logic, versus ~80 lines wrestling with observers
 examples/02-columns/
 ├── app.py            # set_react_page() + 1 reactive_output (column_data) + 1 reactive.effect on input.move_item
 └── www/
-    ├── index.html
-    ├── app.js        # raw React.createElement (Column + ItemRow components)
-    └── main.css
+    ├── ui.js         # raw React.createElement (Column + ItemRow components)
+    └── ui.css
 ```
 
 Same no-build shape as [01-hello](../01-hello/). No `package.json`, no bundler.
diff --git a/examples/02-columns/www/index.html b/examples/02-columns/www/index.html
deleted file mode 100644
index 7a54efb1..00000000
--- a/examples/02-columns/www/index.html
+++ /dev/null
@@ -1,3 +0,0 @@
-<link rel="stylesheet" href="main.css" />
-<div id="root"></div>
-<script src="app.js" defer></script>
diff --git a/examples/02-columns/www/main.css b/examples/02-columns/www/ui.css
similarity index 100%
rename from examples/02-columns/www/main.css
rename to examples/02-columns/www/ui.css
diff --git a/examples/02-columns/www/app.js b/examples/02-columns/www/ui.js
similarity index 89%
rename from examples/02-columns/www/app.js
rename to examples/02-columns/www/ui.js
index 6369a707..2130e1cd 100644
--- a/examples/02-columns/www/app.js
+++ b/examples/02-columns/www/ui.js
@@ -90,5 +90,9 @@ function App() {
   );
 }
 
-const root = ReactDOM.createRoot(document.getElementById("root"));
+// No mount div in the generated page -- create the container and append it
+// to <body>. The script is deferred, so document.body is parsed by now.
+const root = ReactDOM.createRoot(
+  document.body.appendChild(document.createElement("div")),
+);
 root.render(h(App));
diff --git a/examples/05-temperature/www/index.html b/examples/05-temperature/www/index.html
deleted file mode 100644
index 7a54efb1..00000000
--- a/examples/05-temperature/www/index.html
+++ /dev/null
@@ -1,3 +0,0 @@
-<link rel="stylesheet" href="main.css" />
-<div id="root"></div>
-<script src="app.js" defer></script>
diff --git a/examples/05-temperature/www/main.css b/examples/05-temperature/www/ui.css
similarity index 100%
rename from examples/05-temperature/www/main.css
rename to examples/05-temperature/www/ui.css
diff --git a/examples/05-temperature/www/app.js b/examples/05-temperature/www/ui.js
similarity index 91%
rename from examples/05-temperature/www/app.js
rename to examples/05-temperature/www/ui.js
index 7272c23b..02bfe85d 100644
--- a/examples/05-temperature/www/app.js
+++ b/examples/05-temperature/www/ui.js
@@ -106,5 +106,9 @@ function App() {
   );
 }
 
-const root = ReactDOM.createRoot(document.getElementById("root"));
+// No mount div in the generated page -- create the container and append it
+// to <body>. The script is deferred, so document.body is parsed by now.
+const root = ReactDOM.createRoot(
+  document.body.appendChild(document.createElement("div")),
+);
 root.render(h(App));
diff --git a/examples/06-data-frame/www/index.html b/examples/06-data-frame/www/index.html
deleted file mode 100644
index 8145daad..00000000
--- a/examples/06-data-frame/www/index.html
+++ /dev/null
@@ -1,2 +0,0 @@
-<div id="root"></div>
-<script src="app.js" defer></script>
diff --git a/examples/06-data-frame/www/app.js b/examples/06-data-frame/www/ui.js
similarity index 81%
rename from examples/06-data-frame/www/app.js
rename to examples/06-data-frame/www/ui.js
index a39cab45..0607b1fb 100644
--- a/examples/06-data-frame/www/app.js
+++ b/examples/06-data-frame/www/ui.js
@@ -34,5 +34,9 @@ function App() {
   );
 }
 
-const root = ReactDOM.createRoot(document.getElementById("root"));
+// No mount div in the generated page -- create the container and append it
+// to <body>. The script is deferred, so document.body is parsed by now.
+const root = ReactDOM.createRoot(
+  document.body.appendChild(document.createElement("div")),
+);
 root.render(h(App));
diff --git a/examples/07-plotly/www/index.html b/examples/07-plotly/www/index.html
deleted file mode 100644
index 8145daad..00000000
--- a/examples/07-plotly/www/index.html
+++ /dev/null
@@ -1,2 +0,0 @@
-<div id="root"></div>
-<script src="app.js" defer></script>
diff --git a/examples/07-plotly/www/app.js b/examples/07-plotly/www/ui.js
similarity index 83%
rename from examples/07-plotly/www/app.js
rename to examples/07-plotly/www/ui.js
index 3de37fbe..55b687cf 100644
--- a/examples/07-plotly/www/app.js
+++ b/examples/07-plotly/www/ui.js
@@ -38,5 +38,9 @@ function App() {
   );
 }
 
-const root = ReactDOM.createRoot(document.getElementById("root"));
+// No mount div in the generated page -- create the container and append it
+// to <body>. The script is deferred, so document.body is parsed by now.
+const root = ReactDOM.createRoot(
+  document.body.appendChild(document.createElement("div")),
+);
 root.render(h(App));
diff --git a/examples/08-input-handler/www/index.html b/examples/08-input-handler/www/index.html
deleted file mode 100644
index 7a54efb1..00000000
--- a/examples/08-input-handler/www/index.html
+++ /dev/null
@@ -1,3 +0,0 @@
-<link rel="stylesheet" href="main.css" />
-<div id="root"></div>
-<script src="app.js" defer></script>
diff --git a/examples/08-input-handler/www/main.css b/examples/08-input-handler/www/ui.css
similarity index 100%
rename from examples/08-input-handler/www/main.css
rename to examples/08-input-handler/www/ui.css
diff --git a/examples/08-input-handler/www/app.js b/examples/08-input-handler/www/ui.js
similarity index 84%
rename from examples/08-input-handler/www/app.js
rename to examples/08-input-handler/www/ui.js
index ac051262..459530d9 100644
--- a/examples/08-input-handler/www/app.js
+++ b/examples/08-input-handler/www/ui.js
@@ -53,5 +53,9 @@ function App() {
   );
 }
 
-const root = ReactDOM.createRoot(document.getElementById("root"));
+// No mount div in the generated page -- create the container and append it
+// to <body>. The script is deferred, so document.body is parsed by now.
+const root = ReactDOM.createRoot(
+  document.body.appendChild(document.createElement("div")),
+);
 root.render(h(App));
diff --git a/examples/10-bookmarking/www/index.html b/examples/10-bookmarking/www/index.html
deleted file mode 100644
index 37a81bc0..00000000
--- a/examples/10-bookmarking/www/index.html
+++ /dev/null
@@ -1,3 +0,0 @@
-<link rel="stylesheet" href="styles.css" />
-<div id="root"></div>
-<script src="app.js" defer></script>
diff --git a/examples/10-bookmarking/www/styles.css b/examples/10-bookmarking/www/ui.css
similarity index 100%
rename from examples/10-bookmarking/www/styles.css
rename to examples/10-bookmarking/www/ui.css
diff --git a/examples/10-bookmarking/www/app.js b/examples/10-bookmarking/www/ui.js
similarity index 89%
rename from examples/10-bookmarking/www/app.js
rename to examples/10-bookmarking/www/ui.js
index f8247baa..25240c7f 100644
--- a/examples/10-bookmarking/www/app.js
+++ b/examples/10-bookmarking/www/ui.js
@@ -81,5 +81,9 @@
     );
   }
 
-  ReactDOM.createRoot(document.getElementById("root")).render(h(App));
+  // No mount div in the generated page -- create the container and append it
+  // to <body>. The script is deferred, so document.body is parsed by now.
+  ReactDOM.createRoot(
+    document.body.appendChild(document.createElement("div")),
+  ).render(h(App));
 })();
diff --git a/examples/README.md b/examples/README.md
index 4c9e8e4d..f9d9b7bb 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -2,8 +2,8 @@
 
 Runnable example apps for the `ui.tsx` pattern: the server contains only
 reactive computation, and the UI is defined in a client-side React codebase
-whose entry is conventionally `ui.tsx` (simpler variants like `www/app.js`
-for no-build or `src/App.jsx` for Vite + JSX fill the same role).
+whose entry is conventionally `ui.tsx` (simpler variants like `www/ui.js`
+for no-build or `src/ui.jsx` for Vite + JSX fill the same role).
 
 Examples are Python unless noted; [01-hello](01-hello/) also ships an `app.R`
 showing the same app on the R package.
@@ -18,5 +18,5 @@ showing the same app on the R package.
 | [06-data-frame](06-data-frame/) | Embeds `@render.data_frame` via `ShinyOutput` and `set_react_page()` |
 | [07-plotly](07-plotly/) | Embeds `@render_plotly` via `ShinyOutput` and `set_react_page()` |
 | [08-input-handler](08-input-handler/) | `useShinyInput` with `type="shiny.datetime"` — client sends unix seconds; server `input.when()` is a `datetime.datetime` via Shiny's built-in handler |
-| [09-hmr](09-hmr/) | React Fast Refresh in dev (Vite dev server alongside Shiny); the `app.py` and no-build `www/app.js` paths reload too |
+| [09-hmr](09-hmr/) | React Fast Refresh in dev (Vite dev server alongside Shiny); the `app.py` and no-build `www/ui.js` paths reload too |
 | [10-bookmarking](10-bookmarking/) | Bookmark restoration: URL query string (or server-stored state) hydrates `useShinyInput` initial values via a head `<script>` emitted by `page_react_html()` |
diff --git a/pkg-py/README.md b/pkg-py/README.md
index a0574d99..ddc86c7b 100644
--- a/pkg-py/README.md
+++ b/pkg-py/README.md
@@ -19,7 +19,7 @@ pip install "git+https://github.com/posit-dev/shinyreact.git"
 
 ## How it works
 
-`shinyreact` implements the **`ui.tsx` pattern** — UI defined in a client codebase whose entry conventionally lives in `ui.tsx` (or `App.jsx`, or `app.js` for no-build):
+`shinyreact` implements the **`ui.tsx` pattern** — UI defined in a client codebase whose entry conventionally lives in `ui.tsx` (or `ui.jsx`, or `ui.js` for no-build):
 
 1. The Python server contains only reactive computation; it calls `set_react_page()` (Express) or uses `page_react_html()` as the `ui` argument (Core)
 2. A static `www/index.html` + client bundle serve as the React app
@@ -39,22 +39,16 @@ def greeting():
     return {"message": f"Hello, {input.name()}"}
 ```
 
-Pair with a `www/index.html` that loads your React client (no-build `app.js` or a built bundle from `src/ui.tsx`). See the [examples catalog](../examples/README.md) for file layouts and dev workflows, from no-build to Vite + HMR.
+Pair with client assets at `www/ui.js` / `www/ui.css` (written by hand for no-build, or built from `src/ui.tsx`). See the [examples catalog](../examples/README.md) for file layouts and dev workflows, from no-build to Vite + HMR.
 
-In Core mode, use `page_react_html()`. Core apps must also mount `www/`
-themselves — Shiny Express does this automatically, `App()` does not, and
-without it the page loads and then 404s on its own scripts and stylesheets:
+In Core mode, use `page_react()` — it serves the discovered assets itself
+(an mtime-versioned dependency), so no `static_assets=` mount is needed:
 
 ```python
-from pathlib import Path
 from shiny import App
 import shinyreact
 
-app = App(
-    shinyreact.page_react_html("www/index.html"),
-    server,
-    static_assets={"/": Path(__file__).parent / "www"},
-)
+app = App(shinyreact.page_react(), server)
 ```
 
 ### Sending messages to React components
diff --git a/pkg-r/README.md b/pkg-r/README.md
index 71861adb..de6b6911 100644
--- a/pkg-r/README.md
+++ b/pkg-r/README.md
@@ -23,13 +23,13 @@ pak::pak("posit-dev/shinyreact/pkg-r")
 
 ## Usage
 
-A minimal `app.R`. The UI lives in `www/` (a static `index.html` plus your React client); the server owns only reactive computation:
+A minimal `app.R`. The UI lives in `www/` (`ui.js`, plus `ui.css` if you want styles — discovered automatically); the server owns only reactive computation:
 
 ```r
 library(shiny)
 library(shinyreact)
 
-ui <- page_react_html("www/index.html")
+ui <- page_react() # discovers www/ui.js + www/ui.css
 
 server <- function(input, output, session) {
   output$greeting <- reactive_output({

From d106148fc5e7117d0cace98ddcbcf16f5582737d Mon Sep 17 00:00:00 2001
From: Barret Schloerke <barret@posit.co>
Date: Thu, 20 Aug 2026 11:50:44 -0400
Subject: [PATCH 5/5] fix(examples): 10-bookmarking uses page_react() after
 index.html removal

- The sweep deleted www/index.html but app.py still called
  page_react_html("www/index.html"); the per-request callable UI now
  returns page_react(), whose config tag carries the restore payload
- Verified: bookmark query string renders restore values into
  #shinyreact-config
---
 examples/01-hello/README.md       | 4 ++--
 examples/10-bookmarking/README.md | 2 +-
 examples/10-bookmarking/app.py    | 6 +++---
 examples/README.md                | 2 +-
 4 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/examples/01-hello/README.md b/examples/01-hello/README.md
index be18954c..c336c411 100644
--- a/examples/01-hello/README.md
+++ b/examples/01-hello/README.md
@@ -6,7 +6,7 @@ smallest possible `ui.tsx`-first app. No JSX, no bundler, no `package.json`.
 Edit `ui.js` and reload.
 
 `app.py` (Express, via `set_react_page()`) and `app-core.py` (Core, via
-`page_react_html()`) are two server-side entries for the same `www/` client;
+`page_react()`) are two server-side entries for the same `www/` client;
 `app.R` is the R twin.
 
 ## What it shows
@@ -80,7 +80,7 @@ uv run shiny run examples/01-hello/app.py
 # Core API (same client, same outputs)
 uv run shiny run examples/01-hello/app-core.py
 
-# R (same client, same outputs — the R package's page_react_html + reactive_output)
+# R (same client, same outputs — the R package's page_react + reactive_output)
 Rscript -e 'shiny::runApp("examples/01-hello/app.R")'
 ```
 
diff --git a/examples/10-bookmarking/README.md b/examples/10-bookmarking/README.md
index 14a43fea..2aa87737 100644
--- a/examples/10-bookmarking/README.md
+++ b/examples/10-bookmarking/README.md
@@ -2,7 +2,7 @@
 
 Demonstrates bookmark restoration in shinyreact:
 
-- `page_react_html()` emits a `<script>` in `<head>` carrying the restored
+- `page_react()` emits the `#shinyreact-config` tag in `<head>` carrying the restored
   input values when Shiny parses a bookmark query string. The UI is a
   function of `request` so the page re-renders per request and sees the
   active RestoreContext.
diff --git a/examples/10-bookmarking/app.py b/examples/10-bookmarking/app.py
index ca8c5e15..121c4410 100644
--- a/examples/10-bookmarking/app.py
+++ b/examples/10-bookmarking/app.py
@@ -6,9 +6,9 @@
 
 def app_ui(request):
     # A function-of-request UI makes Shiny re-render the page per request, so
-    # page_react_html() sees the active RestoreContext and emits the restore
-    # <script> tag when a bookmark query string is present.
-    return shinyreact.page_react_html("www/index.html")
+    # page_react() sees the active RestoreContext and emits the restore payload
+    # in the #shinyreact-config tag when a bookmark query string is present.
+    return shinyreact.page_react()
 
 
 def server(input: Inputs, output: Outputs, session: Session):
diff --git a/examples/README.md b/examples/README.md
index f9d9b7bb..9be7cb14 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -19,4 +19,4 @@ showing the same app on the R package.
 | [07-plotly](07-plotly/) | Embeds `@render_plotly` via `ShinyOutput` and `set_react_page()` |
 | [08-input-handler](08-input-handler/) | `useShinyInput` with `type="shiny.datetime"` — client sends unix seconds; server `input.when()` is a `datetime.datetime` via Shiny's built-in handler |
 | [09-hmr](09-hmr/) | React Fast Refresh in dev (Vite dev server alongside Shiny); the `app.py` and no-build `www/ui.js` paths reload too |
-| [10-bookmarking](10-bookmarking/) | Bookmark restoration: URL query string (or server-stored state) hydrates `useShinyInput` initial values via a head `<script>` emitted by `page_react_html()` |
+| [10-bookmarking](10-bookmarking/) | Bookmark restoration: URL query string (or server-stored state) hydrates `useShinyInput` initial values via the `#shinyreact-config` tag emitted by `page_react()` |