Merge pull request #1 from BleedingXiko/dev

Add searchable docs UI, static serving, and browser provider resolver

Author: BleedingXiko

README.md

@@ -513,6 +513,7 @@ sprag new myapp --template=labs      # full framework showcase
 ```bash
 sprag dev                            # dev server with hot reload
 sprag dev --port 3000
+sprag dev static                     # serve the pure static build locally
 sprag routes                         # list all routes, mounts, and actions
 ```
 
@@ -529,6 +530,7 @@ sprag add content guides             # markdown collection + routes
 
 ```bash
 sprag build                          # compile to dist/
+sprag build static                   # compile a pure static site
 sprag pack                           # optimize dist for production
 sprag pack --zip                     # optimize + archive
 ```
@@ -650,4 +652,4 @@ The docs site is itself a SPRAG app built with the `docs` template — dogfoodin
 - **Framework** — two runtimes, routes, controllers, stores, auth, uploads, realtime, codegen
 - **Specter** — services, schemas, queues (server runtime)
 - **Ragot** — components, modules, ui primitives, decorators (browser runtime)
-- **Guides** — deployment, forms, background jobs
+- **Guides** — deployment, forms, background jobs

docs/.gitignore

@@ -1,2 +1,3 @@
 public/llms.txt
 public/llms-full.txt
+app/static/search-index.json

docs/app/__init__.py

@@ -3,9 +3,11 @@
 from sprag import App, shell
 
 from app.llms_txt import write_llms_txt
+from app.search_index import write_search_index
 
 
 _PUBLIC_DIR = Path(__file__).resolve().parent.parent / "public"
+_STATIC_DIR = Path(__file__).resolve().parent / "static"
 _SITE_URL = "https://bleedingxiko.github.io/SPRAG"
 
 app_shell = shell(template="app/shell.html", css=["app/shell.css"])
@@ -24,6 +26,8 @@
     },
 )
 
-# Regenerate /llms.txt + /llms-full.txt on every boot.
-# public/ is copied verbatim to the static build output by sprag build.
+# Regenerate generated docs artifacts on every boot.
+# public/ is copied verbatim to the static build output; app/static/ is
+# served at /static/ in dev and copied to dist/static/ in build.
 write_llms_txt(_PUBLIC_DIR, site_url=_SITE_URL)
+write_search_index(_STATIC_DIR)

docs/app/content/docs/framework/routes.md

@@ -52,6 +52,7 @@ my_page = page(
 | `modules` | No | JS import aliases: `{"alias": "path/to/module.js"}` |
 | `static_paths` | No | Function returning path params for static builds |
 | `metadata` | No | Dict of metadata (title, description, etc.) |
+| `providers` | No | Browser provider Modules for this page |
 
 ### Metadata
 
@@ -139,6 +140,38 @@ Merge order: **app metadata → page metadata → `__sprag_meta__`** (last wins)
 
 If you want a browser-owned client app instead of a page route, use `mount(...)` under `app/mounts/`. Mounts are separate from page modes.
 
+## Browser providers
+
+Use `providers` when a page or mount needs a browser Module that starts before the hydrated or mounted Module code.
+
+```python
+from sprag import Module, page
+
+
+class ToastProvider(Module):
+    def on_start(self):
+        self.last_message = ""
+
+    def push(self, message):
+        self.last_message = message
+
+
+class InboxModule(Module):
+    def on_start(self):
+        toast = self.provider("toast")
+        toast.push("Inbox ready")
+
+
+inbox = page(
+    path="/inbox",
+    controller=InboxController,
+    screen=InboxScreen,
+    providers={"toast": ToastProvider},
+)
+```
+
+`App.providers` are server-side services resolved from controllers with `self.service(...)`. `page.providers` and `mount.providers` are browser-side Modules resolved from browser Modules with `self.provider(...)`.
+
 ## Dynamic routes
 
 Use brackets in directory names for dynamic segments:

docs/app/content/docs/ragot/modules.md

@@ -192,3 +192,33 @@ class MyModule(Module):
 ```
 
 Auto-cleaned on `on_stop()`.
+
+## Page and Mount Providers
+
+`page(..., providers={...})` and `mount(..., providers={...})` start browser provider Modules before the page hydrates or the mount starts. Resolve them from another browser Module with `self.provider(key)`.
+
+```python
+class ToastProvider(Module):
+    def on_start(self):
+        self.last_message = ""
+
+    def push(self, message):
+        self.last_message = message
+
+
+class InboxModule(Module):
+    def on_start(self):
+        toast = self.provider("toast")
+        toast.push("Inbox ready")
+```
+
+Declare the provider on the surface:
+
+```python
+inbox = page(
+    path="/inbox",
+    controller=InboxController,
+    screen=InboxScreen,
+    providers={"toast": ToastProvider},
+)
+```

docs/app/content/docs/reference/cli.md

@@ -37,11 +37,12 @@ Build a local preview, watch the project for changes, and start the dev server.
 **Usage**
 
 ```bash
-sprag dev [--port 8000] [--host 127.0.0.1] [--interval 1.0] [--server-mode wsgi|websocket]
+sprag dev [static] [--port 8000] [--host 127.0.0.1] [--interval 1.0] [--server-mode wsgi|websocket]
 ```
 
 **Flags**
 
+- `static` — optional mode that builds and serves a pure static site preview
 - `--port` — port to bind
 - `--host` — host/interface to bind
 - `--interval` — file-watch polling interval in seconds
@@ -54,10 +55,13 @@ sprag dev [--port 8000] [--host 127.0.0.1] [--interval 1.0] [--server-mode wsgi|
 
 ```bash
 sprag dev --host 0.0.0.0 --port 9000 --server-mode websocket
+sprag dev static --port 9000
 ```
 
 If you use websocket mode from a `spragkit` install, also install `gevent-websocket`.
 
+`sprag dev static` serves only the generated static files, matching hosts such as GitHub Pages. It does not expose SPRAG action, websocket, or dev reload endpoints.
+
 ## `sprag build`
 
 Build the app into a deployable artifact.

docs/app/mounts/__init__.py

@@ -0,0 +1 @@
+"""SPRAG client app mounts."""

docs/app/mounts/search/__init__.py

@@ -0,0 +1 @@
+"""search client app mount."""

docs/app/mounts/search/modules.py

@@ -0,0 +1,207 @@
+from sprag import Module, debounce, dom
+
+
+class SearchModule(Module):
+    def __init__(self, screen=None, state=None):
+        super().__init__(screen=screen, state=state or {})
+        self._docs = []
+        self._loaded = False
+
+    def on_start(self):
+        initial = self._read_query_param()
+        input_el = dom.query("[data-role='search-input']", self.element)
+        if input_el and initial:
+            input_el.value = initial
+        self.delegate(self.element, "input", "[data-role='search-input']", self.on_input)
+        self._set_status("Loading search index…")
+        self.load_index(initial)
+
+    async def load_index(self, initial_query):
+        try:
+            response = await browser.fetch("../static/search-index.json")
+            payload = await response.json()
+            self._docs = self._prepare(payload["docs"])
+            self._loaded = True
+            self._run(initial_query)
+        except Exception as err:
+            self._render_results([], [])
+            self._set_status("Couldn't load the search index.")
+
+    @debounce(0.12)
+    def on_input(self, event, target):
+        self._run(target.value)
+
+    def _run(self, query):
+        if not self._loaded:
+            return None
+        trimmed = query.strip()
+        if not trimmed:
+            self._render_results([], [])
+            self._set_status("Type to search the docs.")
+            return None
+        tokens = self._tokenize(trimmed.lower())
+        if len(tokens) == 0:
+            self._render_results([], [])
+            self._set_status("Type to search the docs.")
+            return None
+        results = self._score(tokens)
+        if len(results) == 0:
+            self._render_results([], [])
+            self._set_status("No results for “" + trimmed + "”.")
+            return None
+        self._render_results(results, tokens)
+        self._set_status(str(len(results)) + " result" + ("" if len(results) == 1 else "s") + " for “" + trimmed + "”")
+
+    def _set_status(self, text):
+        el = dom.query("[data-role='search-status']", self.element)
+        if el:
+            el.textContent = text
+
+    def _render_results(self, items, tokens):
+        container = dom.query("[data-role='search-results']", self.element)
+        if not container:
+            return None
+        dom.clear(container)
+        doc = browser.document
+        for item in items:
+            li = doc.createElement("li")
+            li.className = "search-result"
+            a = doc.createElement("a")
+            a.href = item["url"]
+            a.className = "search-result-link"
+            section = doc.createElement("div")
+            section.className = "search-result-section"
+            section.textContent = item["section"]
+            a.appendChild(section)
+            title = doc.createElement("div")
+            title.className = "search-result-title"
+            self._highlight(title, item["title"], tokens)
+            a.appendChild(title)
+            if item["snippet"]:
+                snippet = doc.createElement("div")
+                snippet.className = "search-result-snippet"
+                self._highlight(snippet, item["snippet"], tokens)
+                a.appendChild(snippet)
+            li.appendChild(a)
+            container.appendChild(li)
+
+    def _highlight(self, parent, text, tokens):
+        if not text:
+            return None
+        if len(tokens) == 0:
+            parent.textContent = text
+            return None
+        doc = browser.document
+        text_lc = text.lower()
+        n = len(text)
+        i = 0
+        plain_start = 0
+        while i < n:
+            matched_len = 0
+            for token in tokens:
+                tlen = len(token)
+                if text_lc.slice(i, i + tlen) == token:
+                    matched_len = tlen
+                    break
+            if matched_len > 0:
+                if i > plain_start:
+                    parent.appendChild(doc.createTextNode(text.slice(plain_start, i)))
+                mark = doc.createElement("mark")
+                mark.textContent = text.slice(i, i + matched_len)
+                parent.appendChild(mark)
+                i = i + matched_len
+                plain_start = i
+            else:
+                i = i + 1
+        if plain_start < n:
+            parent.appendChild(doc.createTextNode(text.slice(plain_start, n)))
+
+    def _tokenize(self, query_lc):
+        tokens = []
+        for word in query_lc.split(" "):
+            cleaned = word.strip()
+            if cleaned:
+                tokens.push(cleaned)
+        return tokens
+
+    def _score(self, tokens):
+        matches = []
+        for doc in self._docs:
+            score = 0
+            all_hit = True
+            for token in tokens:
+                if token in doc["title_lc"]:
+                    score += 10
+                elif token in doc["headings_lc"]:
+                    score += 4
+                elif token in doc["description_lc"]:
+                    score += 3
+                elif token in doc["body_lc"]:
+                    score += 1
+                else:
+                    all_hit = False
+                    break
+            if all_hit and score > 0:
+                matches.push({
+                    "title": doc["title"],
+                    "url": doc["url"],
+                    "section": doc["section"],
+                    "snippet": self._snippet(doc, tokens),
+                    "score": score,
+                })
+
+        matches.sort(lambda a, b: b["score"] - a["score"])
+        return matches.slice(0, 30)
+
+    def _snippet(self, doc, tokens):
+        body = doc["body"]
+        body_lc = doc["body_lc"]
+        if not body:
+            return doc["description"] or ""
+
+        pos = -1
+        for token in tokens:
+            i = body_lc.indexOf(token)
+            if i >= 0:
+                pos = i
+                break
+
+        if pos < 0:
+            tail = "…" if len(body) > 160 else ""
+            return body.slice(0, 160) + tail
+
+        start = pos - 60
+        if start < 0:
+            start = 0
+        end = pos + 120
+        prefix = "…" if start > 0 else ""
+        suffix = "…" if end < len(body) else ""
+        return prefix + body.slice(start, end) + suffix
+
+    def _prepare(self, docs):
+        prepared = []
+        for d in docs:
+            headings_joined = d["headings"].join(" ")
+            prepared.push({
+                "title": d["title"],
+                "title_lc": d["title"].lower(),
+                "url": d["url"],
+                "section": d["section"],
+                "description": d["description"],
+                "description_lc": d["description"].lower(),
+                "headings_lc": headings_joined.lower(),
+                "body": d["body"],
+                "body_lc": d["body"].lower(),
+            })
+        return prepared
+
+    def _read_query_param(self):
+        raw = browser.location.search
+        if not raw or len(raw) < 3:
+            return ""
+        body = raw.slice(1)
+        for pair in body.split("&"):
+            if pair.slice(0, 2) == "q=":
+                value = pair.slice(2).replace_all("+", " ")
+                return browser.decodeURIComponent(value)
+        return ""

docs/app/mounts/search/mount.py

@@ -0,0 +1,14 @@
+from sprag import mount
+
+from .modules import SearchModule
+from .server import SearchBoot
+from .web import SearchApp
+
+
+search = mount(
+    path="/search",
+    component=SearchApp,
+    module=SearchModule,
+    boot=SearchBoot,
+    metadata={"title": "Search"},
+)