Rewrite RAGOT imports in copied JS assets

BleedingXiko · BleedingXiko · commit 430cfe3abf52 · 2026-05-11T09:58:12.000-07:00
Rewrite local JS/MJS asset imports that point at ragot.esm.min.js so user-authored vanilla JS can import RAGOT from /vendor/ragot.esm.min.js while builds resolve the emitted runtime location correctly.

Document vanilla JavaScript RAGOT interop, add static asset README files to the default and labs templates, and clarify when to use app/static/ versus project-root public/. Extend asset build coverage for rewritten static and surface script imports, including dynamic imports and external CDN imports.
diff --git a/docs/app/content/docs/ragot/dom.md b/docs/app/content/docs/ragot/dom.md
@@ -99,3 +99,45 @@ class ChartModule(Module):
 ## Lower-level Ragot helpers
 
 If you need to drop below the `dom.*` helper surface, the shipped Ragot runtime also includes lower-level primitives such as `createLazyLoader(...)` and `createInfiniteScroll(...)`. SPRAG's normal authoring path usually reaches those through `ui.LazyImage`, `@infinite_scroll`, and virtual-scroll integration, but they are part of the underlying runtime.
+
+## Vanilla JavaScript with Ragot
+
+For complex browser-only behavior, put a normal JavaScript module in
+`app/static/` and import Ragot from the vendored runtime:
+
+```javascript
+// app/static/js/gallery.mjs
+import { Component, createElement, VirtualScroller } from "/vendor/ragot.esm.min.js";
+
+class GalleryRail extends Component {
+    render() {
+        return createElement("div", { className: "gallery-rail" });
+    }
+}
+
+export function mountGallery(root) {
+    const rail = new GalleryRail();
+    rail.mount(root);
+    return rail;
+}
+```
+
+Attach it to a page or mount as a module script:
+
+```python
+from sprag import page, script
+
+gallery = page(
+    path="/gallery",
+    controller=GalleryController,
+    screen=GalleryScreen,
+    mode="hybrid",
+    js=[script("app/static/js/gallery.mjs", module=True)],
+)
+```
+
+During builds, SPRAG copies `app/static/js/gallery.mjs` to
+`/static/js/gallery.mjs` and rewrites imports that point at
+`ragot.esm.min.js` to the emitted runtime location. That means the source can
+use `/vendor/ragot.esm.min.js`, while static and packaged builds still get the
+correct relative import path.
diff --git a/sprag/__init__.py b/sprag/__init__.py
@@ -1,6 +1,6 @@
 """Public SPRAG framework surface."""
 
-__version__ = "0.1.14"
+__version__ = "0.1.15"
 
 from .runtime import dom
 from .runtime.app import App
diff --git a/sprag/dev/templates/default/app/static/README.md.tmpl b/sprag/dev/templates/default/app/static/README.md.tmpl
@@ -0,0 +1,19 @@
+# Static Assets
+
+Files in `app/static/` are served at `/static/...` and copied into builds.
+Use this folder for images, fonts, vendored JavaScript, CSS, web workers,
+WASM, and small browser-only bridge modules.
+
+Examples:
+
+- `app/static/images/logo.png` -> `/static/images/logo.png`
+- `app/static/js/gallery.mjs` -> `/static/js/gallery.mjs`
+- `app/static/vendor/widget.js` -> `/static/vendor/widget.js`
+
+Use `page(js=[...])`, `mount(js=[...])`, or `modules={...}` to attach scripts
+from here to a surface. For vanilla JavaScript that needs Ragot directly,
+import from `/vendor/ragot.esm.min.js`; SPRAG rewrites that import to the
+correct emitted runtime path during builds.
+
+The project-root `public/` folder is different: it is copied to the build
+output root for files like `favicon.ico`, `robots.txt`, and `sitemap.xml`.
diff --git a/sprag/runtime/assets.py b/sprag/runtime/assets.py
@@ -5,6 +5,8 @@
 import hashlib
 import html
 import importlib
+import posixpath
+import re
 import shutil
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -241,6 +243,46 @@ def emit_assets(output_dir: str | Path, assets: Iterable[Asset]):
         target_path = target_root / asset.web_path.lstrip("/")
         target_path.parent.mkdir(parents=True, exist_ok=True)
         shutil.copy2(asset.source_path, target_path)
+        _rewrite_copied_js_ragot_imports(target_path, asset.web_path)
+
+
+_JS_IMPORT_SPEC_RE = re.compile(
+    r"""(?P<head>\bimport\s*(?:\(\s*)?(?:[^'";]*?\s+from\s*)?)(?P<quote>['"])(?P<spec>[^'"]+)(?P=quote)""",
+    re.M,
+)
+
+
+def _rewrite_copied_js_ragot_imports(target_path: Path, web_path: str) -> None:
+    if target_path.suffix.lower() not in {".js", ".mjs"}:
+        return
+    try:
+        content = target_path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        return
+    rewritten = _rewrite_ragot_import_specs(content, web_path)
+    if rewritten != content:
+        target_path.write_text(rewritten, encoding="utf-8")
+
+
+def _rewrite_ragot_import_specs(content: str, web_path: str) -> str:
+    current_dir = posixpath.dirname(web_path.lstrip("/"))
+    if current_dir:
+        runtime_spec = posixpath.relpath("vendor/ragot.esm.min.js", current_dir)
+    else:
+        runtime_spec = "vendor/ragot.esm.min.js"
+    if not runtime_spec.startswith("."):
+        runtime_spec = "./" + runtime_spec
+
+    def replace(match: re.Match) -> str:
+        spec = match.group("spec")
+        if _is_external_path(spec):
+            return match.group(0)
+        spec_path = spec.split("#", 1)[0].split("?", 1)[0]
+        if posixpath.basename(spec_path) != "ragot.esm.min.js":
+            return match.group(0)
+        return f"{match.group('head')}{match.group('quote')}{runtime_spec}{match.group('quote')}"
+
+    return _JS_IMPORT_SPEC_RE.sub(replace, content)
 
 
 def render_css_links(assets: Iterable[Asset], *, document_path: str | None = None) -> str:
diff --git a/tests/test_assets.py b/tests/test_assets.py
@@ -117,13 +117,21 @@ def test_build_web_preview_emits_surface_assets_and_static_tree(self):
             )
             (root / "app" / "shell.css").write_text("body { color: red; }\n", encoding="utf-8")
             (root / "app" / "routes" / "docs" / "module-helper.mjs").write_text(
-                "window.__SPRAG_TEST_MODULE__ = true;\n",
+                "import { bus } from '/vendor/ragot.esm.min.js';\n"
+                "window.__SPRAG_TEST_MODULE__ = bus;\n",
                 encoding="utf-8",
             )
             (root / "app" / "static" / "vendor" / "dayjs.mjs").write_text(
                 "export default function dayjs() { return { format() { return '2026-04-12'; } }; }\n",
                 encoding="utf-8",
             )
+            (root / "app" / "static" / "vendor" / "ragot-widget.mjs").write_text(
+                "import { Component } from '/vendor/ragot.esm.min.js';\n"
+                "import('./ragot.esm.min.js');\n"
+                "import('https://cdn.example.test/ragot.esm.min.js');\n"
+                "export { Component };\n",
+                encoding="utf-8",
+            )
             (root / "app" / "static" / "vendor" / "widget.js").write_text(
                 "window.__SPRAG_WIDGET__ = true;\n",
                 encoding="utf-8",
@@ -173,13 +181,22 @@ def test_build_web_preview_emits_surface_assets_and_static_tree(self):
             self.assertTrue((root / "dist" / "assets" / "app" / "shell.css").exists())
             self.assertTrue((root / "dist" / "assets" / "app" / "routes" / "docs" / "module-helper.mjs").exists())
             self.assertTrue((root / "dist" / "static" / "vendor" / "dayjs.mjs").exists())
+            self.assertTrue((root / "dist" / "static" / "vendor" / "ragot-widget.mjs").exists())
             self.assertTrue((root / "dist" / "static" / "vendor" / "widget.js").exists())
             self.assertTrue((root / "dist" / "static" / "images" / "logo.svg").exists())
 
+            module_helper = (root / "dist" / "assets" / "app" / "routes" / "docs" / "module-helper.mjs").read_text(encoding="utf-8")
+            ragot_widget = (root / "dist" / "static" / "vendor" / "ragot-widget.mjs").read_text(encoding="utf-8")
+            self.assertIn("from '../../../../vendor/ragot.esm.min.js'", module_helper)
+            self.assertIn("from '../../vendor/ragot.esm.min.js'", ragot_widget)
+            self.assertIn("import('../../vendor/ragot.esm.min.js')", ragot_widget)
+            self.assertIn("import('https://cdn.example.test/ragot.esm.min.js')", ragot_widget)
+
             asset_paths = {asset["web_path"] for asset in manifest["assets"]}
             self.assertIn("/assets/app/shell.css", asset_paths)
             self.assertIn("/assets/app/routes/docs/module-helper.mjs", asset_paths)
             self.assertIn("/static/vendor/dayjs.mjs", asset_paths)
+            self.assertIn("/static/vendor/ragot-widget.mjs", asset_paths)
             self.assertIn("/static/vendor/widget.js", asset_paths)
             self.assertIn("/static/images/logo.svg", asset_paths)
 
