hedron-sim 0.1.0__tar.gz

hedron_sim-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+.DS_Store
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+/build/
+# Artifact/output build trees only — never ignore package source such as
+# packages/hedron/src/hedron/build (Hatchling respects gitignore and would
+# omit it from sdists/wheels; see #32).
+**/.hedron/build/
+packages/hedron-runtime-java/build/
+target/
+.venv*/
+venv*/
+.env
+.coverage
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.tox/
+.nox/
+.audit-build-proj/
+examples/reference-app/.hedron/
+*.html.gz
+/site/
+*.so
+*.dylib
+*.pyd
+.devcontainer/
+# Local SQLite demos (e.g. examples/notes-sqlalchemy)
+*.db

hedron_sim-0.1.0/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+## [Unreleased]
+
+### Fixed
+
+- Store route tables in ``<template data-hedron-sim-routes>`` instead of
+  ``<script type="application/json">``. MkDocs Material ``navigation.instant``
+  strips ``<script>`` nodes from fetched pages, which left demo buttons dead until
+  a hard refresh.
+- Escape ``__HEDRON_SIM_FORM:*__`` token substitutions with ``escapeHtml`` so invite
+  demos cannot inject markup via form fields.
+- Boot on ``DOMContentLoaded`` even when Material's ``document$`` is present, and
+  handle Text-node click targets / form-inherited ``hx-*`` on submit buttons.
+- Expand docs sim includes *after* Markdown so `__HEDRON_SIM_UTC__` tokens are not
+  turned into `<strong>` (which broke timestamp swaps on Read the Docs).
+- Neutralize *all* progressive `a[href]` / `form[action]` targets inside sim islands
+  (not only `hx-*` anchors), and block leftover navigations/submits in capture phase
+  so demo clicks cannot hit Read the Docs / Cloudflare WAF paths.
+- Force `action="#"` on every sim `<form>` (even when `action` was omitted) and always
+  `preventDefault` sim submits before route init, so `method="post"` forms cannot POST
+  the current docs URL.
+- Re-check boot invariants (no root/http `href`, forms `action="#"`) and record repairs
+  on `data-hedron-sim-blocked` for tests.
+- While a sim click/submit is in flight, reject `fetch` / `XMLHttpRequest` so a
+  regression cannot hit Read the Docs network paths (MkDocs/RTD traffic outside that
+  window is unaffected).
+- Accept legacy markdown-mangled `<strong>HEDRON_SIM_UTC</strong>` tokens in the JS shim.
+- Intercept demo `hx-*` clicks/submits in the capture phase so MkDocs Material
+  instant navigation cannot follow progressive-enhancement `href`s out of the docs.
+- Rewrite demo anchor `href`s to `#` at boot (original kept in `data-hedron-sim-href`)
+  because Material registers its capture listener before extra scripts.
+
+### Added
+
+- Route ``validate="credentials"`` + ``variants`` for docs auth demos (``ada`` /
+  ``correct-horse``).
+- Route extras ``accumulate="field"`` + ``empty=...`` and ``list_remove=True`` so list
+  demos (CRUD notes) append and delete items client-side instead of replacing one row.
+- Layout styles for ``OobHost`` rows so the host id and caption are not jammed together.
+- Docs theme tokens for Material `slate` / `default` schemes.
+- Bounded `hx-trigger="load"` and `hx-confirm` support in the JS shim.
+- PAGE / FRAGMENT mode-toggle helper for core-concepts demos.
+
+## [0.1.0] — 2026-08-07
+
+### Added
+
+- Initial Alpha: `SimApp`, `embed_demo`, `sim_utc` / `sim_form` placeholders, and a browser HTMX shim.
+- Route extras: email `validate` + `variants`, and `sequence` responses for poll-style demos.
+- Docs guides and HTMX-native component galleries migrated onto generated `<!-- hedron-sim:… -->` islands.

hedron_sim-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Odos Matthews
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hedron_sim-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: hedron-sim
+Version: 0.1.0
+Summary: Offline HTMX simulation for Hedron docs and demos — real components, no live server
+Project-URL: Homepage, https://github.com/eddiethedean/hedron
+Project-URL: Repository, https://github.com/eddiethedean/hedron
+Project-URL: Issues, https://github.com/eddiethedean/hedron/issues
+Project-URL: Changelog, https://github.com/eddiethedean/hedron/blob/main/packages/hedron-sim/CHANGELOG.md
+Project-URL: Documentation, https://hedron.readthedocs.io/en/latest/
+Author-email: Odos Matthews <odosmatthews@gmail.com>
+Maintainer-email: Odos Matthews <odosmatthews@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: components,docs,hedron,htmx,simulation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: <3.15,>=3.11
+Requires-Dist: hedron-core<0.23,>=0.22.0
+Requires-Dist: hedron<0.23,>=0.22.0
+Description-Content-Type: text/markdown
+
+# hedron-sim
+
+[![PyPI](https://img.shields.io/pypi/v/hedron-sim.svg)](https://pypi.org/project/hedron-sim/)
+[![Python](https://img.shields.io/pypi/pyversions/hedron-sim.svg)](https://pypi.org/project/hedron-sim/)
+[![CI](https://img.shields.io/github/actions/workflow/status/eddiethedean/hedron/ci.yml?branch=main&label=CI)](https://github.com/eddiethedean/hedron/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/eddiethedean/hedron/blob/main/LICENSE)
+
+Offline HTMX simulation for Hedron docs and demos.
+
+Author demos with ordinary Hedron components (`Page`, `RefreshButton`, `swap`,
+regions), then embed them in static docs. A small JavaScript runtime intercepts
+`hx-*` attributes and serves pre-rendered fragment HTML — no FastAPI process
+required.
+
+**Package maturity:** Alpha (`0.1.x`) · pin `>=0.1.0,<0.2` and expect churn
+
+## Install
+
+```bash
+pip install "hedron-sim>=0.1.0,<0.2"
+# or
+uv add "hedron-sim>=0.1.0,<0.2"
+```
+
+Requires Python 3.11–3.14 and `hedron` (for component imports used in demos).
+
+## Quick start
+
+```python
+from hedron import Page, RefreshButton, Stack, Text, html, swap
+from hedron_sim import SimApp, embed_demo, sim_utc
+
+app = SimApp(demo_id="hello-status")
+status = app.region("service-status")
+
+
+def status_panel():
+    return html.div(
+        Text(f"All systems operational · refreshed {sim_utc()}"),
+        id=status.id,
+        role="status",
+        aria={"live": "polite"},
+    )
+
+
+@app.page("/")
+def home() -> Page:
+    return Page(
+        Stack(
+            Text("Hello from hedron-sim"),
+            status_panel(),
+            RefreshButton.for_region(status, href="/status", label="Refresh status"),
+        ),
+        title="Demo",
+    )
+
+
+@app.fragment("/status", region=status)
+def refresh_status():
+    return swap(status_panel())
+
+
+print(embed_demo(app))
+```
+
+### Ship static assets
+
+```python
+from pathlib import Path
+from hedron_sim.assets import copy_assets
+
+copy_assets(Path("docs/javascript"), Path("docs/stylesheets"))
+```
+
+Then load `hedron-sim.js` (and optionally `hedron-sim.css`) from MkDocs
+`extra_javascript` / `extra_css`.
+
+## Public API
+
+| Symbol | Role |
+|---|---|
+| `SimApp` | Offline app with `@page` / `@fragment` and regions |
+| `embed_demo(app)` | HTML snippet for static docs |
+| `sim_utc` / `sim_local_time` | Deterministic clock helpers for demos |
+| `hedron_sim.assets.copy_assets` | Copy JS/CSS into a docs tree |
+
+## Links
+
+- [Package docs](https://hedron.readthedocs.io/en/latest/packages/hedron-sim/)
+- [Documentation](https://hedron.readthedocs.io/en/latest/)
+- [Changelog](https://github.com/eddiethedean/hedron/blob/main/packages/hedron-sim/CHANGELOG.md)
+- [Source](https://github.com/eddiethedean/hedron/tree/main/packages/hedron-sim)
+- [Issues](https://github.com/eddiethedean/hedron/issues)
+- [`hedron`](https://pypi.org/project/hedron/)
+
+## License
+
+MIT. See [LICENSE](LICENSE).

hedron_sim-0.1.0/README.md

@@ -0,0 +1,98 @@
+# hedron-sim
+
+[![PyPI](https://img.shields.io/pypi/v/hedron-sim.svg)](https://pypi.org/project/hedron-sim/)
+[![Python](https://img.shields.io/pypi/pyversions/hedron-sim.svg)](https://pypi.org/project/hedron-sim/)
+[![CI](https://img.shields.io/github/actions/workflow/status/eddiethedean/hedron/ci.yml?branch=main&label=CI)](https://github.com/eddiethedean/hedron/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/eddiethedean/hedron/blob/main/LICENSE)
+
+Offline HTMX simulation for Hedron docs and demos.
+
+Author demos with ordinary Hedron components (`Page`, `RefreshButton`, `swap`,
+regions), then embed them in static docs. A small JavaScript runtime intercepts
+`hx-*` attributes and serves pre-rendered fragment HTML — no FastAPI process
+required.
+
+**Package maturity:** Alpha (`0.1.x`) · pin `>=0.1.0,<0.2` and expect churn
+
+## Install
+
+```bash
+pip install "hedron-sim>=0.1.0,<0.2"
+# or
+uv add "hedron-sim>=0.1.0,<0.2"
+```
+
+Requires Python 3.11–3.14 and `hedron` (for component imports used in demos).
+
+## Quick start
+
+```python
+from hedron import Page, RefreshButton, Stack, Text, html, swap
+from hedron_sim import SimApp, embed_demo, sim_utc
+
+app = SimApp(demo_id="hello-status")
+status = app.region("service-status")
+
+
+def status_panel():
+    return html.div(
+        Text(f"All systems operational · refreshed {sim_utc()}"),
+        id=status.id,
+        role="status",
+        aria={"live": "polite"},
+    )
+
+
+@app.page("/")
+def home() -> Page:
+    return Page(
+        Stack(
+            Text("Hello from hedron-sim"),
+            status_panel(),
+            RefreshButton.for_region(status, href="/status", label="Refresh status"),
+        ),
+        title="Demo",
+    )
+
+
+@app.fragment("/status", region=status)
+def refresh_status():
+    return swap(status_panel())
+
+
+print(embed_demo(app))
+```
+
+### Ship static assets
+
+```python
+from pathlib import Path
+from hedron_sim.assets import copy_assets
+
+copy_assets(Path("docs/javascript"), Path("docs/stylesheets"))
+```
+
+Then load `hedron-sim.js` (and optionally `hedron-sim.css`) from MkDocs
+`extra_javascript` / `extra_css`.
+
+## Public API
+
+| Symbol | Role |
+|---|---|
+| `SimApp` | Offline app with `@page` / `@fragment` and regions |
+| `embed_demo(app)` | HTML snippet for static docs |
+| `sim_utc` / `sim_local_time` | Deterministic clock helpers for demos |
+| `hedron_sim.assets.copy_assets` | Copy JS/CSS into a docs tree |
+
+## Links
+
+- [Package docs](https://hedron.readthedocs.io/en/latest/packages/hedron-sim/)
+- [Documentation](https://hedron.readthedocs.io/en/latest/)
+- [Changelog](https://github.com/eddiethedean/hedron/blob/main/packages/hedron-sim/CHANGELOG.md)
+- [Source](https://github.com/eddiethedean/hedron/tree/main/packages/hedron-sim)
+- [Issues](https://github.com/eddiethedean/hedron/issues)
+- [`hedron`](https://pypi.org/project/hedron/)
+
+## License
+
+MIT. See [LICENSE](LICENSE).

hedron_sim-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[project]
+name = "hedron-sim"
+version = "0.1.0"
+description = "Offline HTMX simulation for Hedron docs and demos — real components, no live server"
+readme = "README.md"
+requires-python = ">=3.11,<3.15"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Odos Matthews", email = "odosmatthews@gmail.com" },
+]
+maintainers = [
+    { name = "Odos Matthews", email = "odosmatthews@gmail.com" },
+]
+keywords = [
+    "components",
+    "docs",
+    "hedron",
+    "htmx",
+    "simulation",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "hedron-core>=0.22.0,<0.23",
+    "hedron>=0.22.0,<0.23",
+]
+
+[project.urls]
+Homepage = "https://github.com/eddiethedean/hedron"
+Repository = "https://github.com/eddiethedean/hedron"
+Issues = "https://github.com/eddiethedean/hedron/issues"
+Changelog = "https://github.com/eddiethedean/hedron/blob/main/packages/hedron-sim/CHANGELOG.md"
+Documentation = "https://hedron.readthedocs.io/en/latest/"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hedron_sim"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/hedron_sim/static/hedron-sim.js" = "hedron_sim/static/hedron-sim.js"
+"src/hedron_sim/static/hedron-sim.css" = "hedron_sim/static/hedron-sim.css"
+
+[tool.hatch.build.targets.sdist]
+only-include = [
+    "src/hedron_sim",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "pyproject.toml",
+]

hedron_sim-0.1.0/src/hedron_sim/__init__.py

@@ -0,0 +1,22 @@
+"""Offline HTMX simulation for Hedron docs and static demos."""
+
+from __future__ import annotations
+
+from hedron_sim.app import SimApp, SimRoute
+from hedron_sim.embed import embed_demo, render_handler_html, wrap_browser_chrome
+from hedron_sim.tokens import SIM_LOCAL_TIME, SIM_UTC, sim_form, sim_local_time, sim_utc
+
+__all__ = [
+    "SIM_LOCAL_TIME",
+    "SIM_UTC",
+    "SimApp",
+    "SimRoute",
+    "embed_demo",
+    "render_handler_html",
+    "sim_form",
+    "sim_local_time",
+    "sim_utc",
+    "wrap_browser_chrome",
+]
+
+__version__ = "0.1.0"

hedron_sim-0.1.0/src/hedron_sim/app.py

@@ -0,0 +1,190 @@
+"""SimApp: register pages and fragments with ordinary Hedron handlers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any, TypeVar
+
+from hedron_core.interaction import FragmentRegion
+
+__all__ = ["SimApp", "SimRoute"]
+
+F = TypeVar("F", bound=Callable[..., Any])
+Handler = Callable[..., Any]
+
+
+def _as_regions(
+    region: FragmentRegion | str | None,
+    regions: Sequence[FragmentRegion | str] | None,
+    fragment_regions: Sequence[FragmentRegion | str] | None,
+) -> tuple[FragmentRegion, ...]:
+    merged: list[FragmentRegion] = []
+    for item in (
+        *(() if region is None else (region,)),
+        *(regions or ()),
+        *(fragment_regions or ()),
+    ):
+        if isinstance(item, FragmentRegion):
+            merged.append(item)
+        else:
+            text = str(item)
+            selector = text if text.startswith("#") or text.startswith(".") else f"#{text}"
+            region_id = text[1:] if text.startswith("#") else text
+            merged.append(FragmentRegion(id=region_id, selector=selector))
+    return tuple(merged)
+
+
+@dataclass(frozen=True, slots=True)
+class SimRoute:
+    """One simulated HTTP fragment/action endpoint."""
+
+    method: str
+    path: str
+    handler: Handler
+    regions: tuple[FragmentRegion, ...] = ()
+    explanation: str = ""
+    validate: str | None = None
+    variants: Mapping[str, Handler] | None = None
+    sequence: tuple[Handler, ...] | None = None
+    accumulate: str | None = None
+    """Form field name — append values into a client-side list for this region."""
+    empty: Handler | None = None
+    """Handler that renders the empty list container (required with ``accumulate``)."""
+    list_remove: bool = False
+    """DELETE (or similar): remove one list item by ``data-hedron-sim-list-index``."""
+
+    @property
+    def key(self) -> str:
+        return f"{self.method.upper()} {self.path}"
+
+
+@dataclass
+class SimApp:
+    """Register a page and fragment routes for offline HTMX simulation.
+
+    Handlers use the same return types as a real Hedron app (``Page``, components,
+    ``InteractionResult`` / ``swap(...)``). ``embed_demo`` pre-renders them into an
+    HTML island plus a JSON route table consumed by ``hedron-sim.js``.
+
+    Optional route extras:
+
+    - ``validate="email"`` + ``variants={"invalid": ..., "valid": ...}`` for form demos
+    - ``validate="credentials"`` + ``variants`` (demo user ``ada`` / ``correct-horse``)
+    - ``sequence=(handler1, handler2, ...)`` for polling / multi-step GETs
+    - ``accumulate="field"`` + ``empty=...`` for append-only list demos (CRUD notes)
+    - ``list_remove=True`` on DELETE to drop one accumulated item by index
+    """
+
+    title: str = "Hedron sim"
+    demo_id: str | None = None
+    _page_path: str = field(default="/", init=False, repr=False)
+    _page_handler: Handler | None = field(default=None, init=False, repr=False)
+    _routes: dict[str, SimRoute] = field(
+        default_factory=lambda: {},
+        init=False,
+        repr=False,
+    )
+
+    def region(
+        self,
+        id: str,
+        *,
+        selector: str | None = None,
+        description: str = "",
+    ) -> FragmentRegion:
+        """Declare a fragment region (default selector ``#{id}``)."""
+        return FragmentRegion(id=id, selector=selector or f"#{id}", description=description)
+
+    def page(self, path: str = "/") -> Callable[[F], F]:
+        """Register the initial document body for the demo."""
+
+        def wrap(fn: F) -> F:
+            self._page_path = path
+            self._page_handler = fn
+            return fn
+
+        return wrap
+
+    def fragment(
+        self,
+        path: str,
+        *,
+        region: FragmentRegion | str | None = None,
+        regions: Sequence[FragmentRegion | str] | None = None,
+        fragment_regions: Sequence[FragmentRegion | str] | None = None,
+        method: str = "GET",
+        explanation: str = "",
+        validate: str | None = None,
+        variants: Mapping[str, Handler] | None = None,
+        sequence: Sequence[Handler] | None = None,
+        accumulate: str | None = None,
+        empty: Handler | None = None,
+        list_remove: bool = False,
+    ) -> Callable[[F], F]:
+        """Register a fragment endpoint with an optional region allowlist."""
+
+        def wrap(fn: F) -> F:
+            if accumulate and empty is None:
+                raise ValueError("accumulate=... requires empty= handler for the empty list UI")
+            route = SimRoute(
+                method=method.upper(),
+                path=path,
+                handler=fn,
+                regions=_as_regions(region, regions, fragment_regions),
+                explanation=explanation,
+                validate=validate,
+                variants=dict(variants) if variants else None,
+                sequence=tuple(sequence) if sequence else None,
+                accumulate=accumulate,
+                empty=empty,
+                list_remove=list_remove,
+            )
+            self._routes[route.key] = route
+            return fn
+
+        return wrap
+
+    def action(
+        self,
+        path: str,
+        *,
+        region: FragmentRegion | str | None = None,
+        regions: Sequence[FragmentRegion | str] | None = None,
+        fragment_regions: Sequence[FragmentRegion | str] | None = None,
+        method: str = "POST",
+        explanation: str = "",
+        validate: str | None = None,
+        variants: Mapping[str, Handler] | None = None,
+        sequence: Sequence[Handler] | None = None,
+        accumulate: str | None = None,
+        empty: Handler | None = None,
+        list_remove: bool = False,
+    ) -> Callable[[F], F]:
+        """Register a mutation endpoint (default POST) for form demos."""
+        return self.fragment(
+            path,
+            region=region,
+            regions=regions,
+            fragment_regions=fragment_regions,
+            method=method,
+            explanation=explanation,
+            validate=validate,
+            variants=variants,
+            sequence=sequence,
+            accumulate=accumulate,
+            empty=empty,
+            list_remove=list_remove,
+        )
+
+    @property
+    def page_handler(self) -> Handler | None:
+        return self._page_handler
+
+    @property
+    def page_path(self) -> str:
+        return self._page_path
+
+    @property
+    def routes(self) -> dict[str, SimRoute]:
+        return dict(self._routes)

hedron_sim-0.1.0/src/hedron_sim/assets.py

@@ -0,0 +1,50 @@
+"""Locate and copy packaged JS/CSS assets into a docs tree."""
+
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+
+__all__ = ["asset_path", "copy_assets", "css_text", "javascript_text"]
+
+
+def asset_path(name: str) -> Path:
+    """Return a filesystem path to a packaged static asset (may be inside a zip)."""
+    target = resources.files("hedron_sim").joinpath("static").joinpath(name)
+    with resources.as_file(target) as path:
+        return Path(path)
+
+
+def javascript_text() -> str:
+    return (
+        resources.files("hedron_sim").joinpath("static/hedron-sim.js").read_text(encoding="utf-8")
+    )
+
+
+def css_text() -> str:
+    return (
+        resources.files("hedron_sim").joinpath("static/hedron-sim.css").read_text(encoding="utf-8")
+    )
+
+
+def copy_assets(
+    javascript_dir: Path | str,
+    stylesheets_dir: Path | str | None = None,
+) -> tuple[Path, Path | None]:
+    """Copy ``hedron-sim.js`` (and optional CSS) into docs asset directories.
+
+    Returns:
+        Paths to the written JS file and CSS file (CSS may be ``None`` when skipped).
+    """
+    js_dir = Path(javascript_dir)
+    js_dir.mkdir(parents=True, exist_ok=True)
+    js_dest = js_dir / "hedron-sim.js"
+    js_dest.write_text(javascript_text(), encoding="utf-8")
+
+    css_dest: Path | None = None
+    if stylesheets_dir is not None:
+        css_dir = Path(stylesheets_dir)
+        css_dir.mkdir(parents=True, exist_ok=True)
+        css_dest = css_dir / "hedron-sim.css"
+        css_dest.write_text(css_text(), encoding="utf-8")
+    return js_dest, css_dest