simple-module-hosting 0.0.30__tar.gz → 0.0.31__tar.gz

{simple_module_hosting-0.0.30 → simple_module_hosting-0.0.31}/.gitignore

@@ -63,3 +63,4 @@ Thumbs.db
 host/client_app/.playwright-cli/*
 .superpowers/
 .qa/
+.verify/

{simple_module_hosting-0.0.30 → simple_module_hosting-0.0.31}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: simple_module_hosting
-Version: 0.0.30
+Version: 0.0.31
 Summary: FastAPI + Inertia.js host runtime for simple_module — app_builder, middleware stack, CLI (sm / simple-module), scaffolding
 Project-URL: Homepage, https://github.com/antosubash/simple_module_python
 Project-URL: Repository, https://github.com/antosubash/simple_module_python
@@ -27,8 +27,8 @@ Requires-Dist: fastapi>=0.115
 Requires-Dist: httpx>=0.27
 Requires-Dist: itsdangerous>=2.0
 Requires-Dist: jinja2>=3.1
-Requires-Dist: simple-module-core==0.0.30
-Requires-Dist: simple-module-db==0.0.30
+Requires-Dist: simple-module-core==0.0.31
+Requires-Dist: simple-module-db==0.0.31
 Requires-Dist: starlette>=0.44
 Requires-Dist: tomlkit>=0.13
 Requires-Dist: uvicorn[standard]>=0.34

{simple_module_hosting-0.0.30 → simple_module_hosting-0.0.31}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_hosting"
-version = "0.0.30"
+version = "0.0.31"
 description = "FastAPI + Inertia.js host runtime for simple_module — app_builder, middleware stack, CLI (sm / simple-module), scaffolding"
 readme = "README.md"
 license = "MIT"
@@ -30,8 +30,8 @@ dependencies = [
     # it directly — out-of-tree hosts have nothing else pulling it in.
     "itsdangerous>=2.0",
     "jinja2>=3.1",
-    "simple_module_core==0.0.30",
-    "simple_module_db==0.0.30",
+    "simple_module_core==0.0.31",
+    "simple_module_db==0.0.31",
     "starlette>=0.44",
     "tomlkit>=0.13",
     "uvicorn[standard]>=0.34",

simple_module_hosting-0.0.31/simple_module_hosting/_db_health.py

@@ -0,0 +1,56 @@
+"""The host's own readiness check: can we reach the database?
+
+Registered by ``create_app`` rather than by a module, because it is the one
+dependency no request can do without — unlike a mailer or an object store,
+which a page load never touches.
+
+It also gives ``/health/ready`` something to actually report. Modules
+contribute checks for third-party services, and those are ``probe=False``
+(polling an SMTP login every 10s earns a rate-limit), so without this the
+readiness endpoint would answer "healthy" from an empty check set — a green
+light that proves nothing.
+
+It is owned by the host, not a module, so it deliberately does not light up any
+tile on the dashboard's per-module health strip — those are keyed by
+``HealthCheck.module``.
+"""
+
+from __future__ import annotations
+
+from simple_module_core.health import HealthCheck, HealthCheckResult, HealthStatus
+from sqlalchemy import text
+
+CHECK_DATABASE = "host.database"
+
+_MODULE = "Host"
+
+
+def build_database_check(db_state):
+    """Return an async check issuing the cheapest possible round trip."""
+
+    async def check() -> HealthCheckResult:
+        try:
+            async with db_state.session_factory() as session:
+                await session.execute(text("SELECT 1"))
+        except Exception as exc:
+            return HealthCheckResult(status=HealthStatus.UNHEALTHY, detail=str(exc))
+        return HealthCheckResult(status=HealthStatus.HEALTHY, detail="Database reachable")
+
+    return check
+
+
+def register_database_check(health_registry, db_state) -> None:
+    """Add the database check to *health_registry*.
+
+    ``probe=True``: a ``SELECT 1`` against an already-pooled connection is
+    cheap enough to run on a probe timer, and it is exactly what a readiness
+    probe should be asking.
+    """
+    health_registry.add(
+        HealthCheck(
+            name=CHECK_DATABASE,
+            check=build_database_check(db_state),
+            module=_MODULE,
+            probe=True,
+        )
+    )

simple_module_hosting-0.0.31/simple_module_hosting/_error_handlers.py

@@ -0,0 +1,159 @@
+"""Framework-wide exception handlers that render Inertia error pages."""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi.encoders import jsonable_encoder
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from inertia import (
+    Inertia,
+    InertiaConfig,
+    InertiaVersionConflictException,
+    inertia_version_conflict_exception_handler,
+)
+from simple_module_core.exceptions import NotFoundError
+from starlette.exceptions import HTTPException
+from starlette.requests import Request
+from starlette.responses import Response
+
+from simple_module_hosting._inertia_shared import _INERTIA_HEADER
+
+logger = logging.getLogger(__name__)
+
+_INERTIA_ERROR_STATUSES = frozenset({403, 404, 500})
+
+
+def _explicit_accept_q(accept: str, media_type: str) -> float | None:
+    """Quality the Accept header gives ``media_type`` by explicit listing, or
+    ``None`` when the caller never named it at all.
+
+    Only exact entries count (no ``*/*`` / ``type/*`` wildcards) — the
+    negotiation below cares whether the caller *named* html or json, and at
+    what preference, and separately whether they named it *at all* (``None``
+    vs. an explicit ``q=0``). Malformed q-values fall back to 1.0 per RFC 9110.
+    """
+    for part in accept.split(","):
+        media, _, params = part.partition(";")
+        if media.strip().lower() != media_type:
+            continue
+        q = 1.0
+        for param in params.split(";"):
+            name, _, value = param.partition("=")
+            if name.strip().lower() == "q":
+                try:
+                    q = float(value.strip())
+                except ValueError:
+                    q = 1.0
+        return q
+    return None
+
+
+def _wants_json(request: Request) -> bool:
+    """API callers get JSON error bodies; browser-shaped requests get the page.
+
+    A request that explicitly accepts ``text/html`` is a browser navigation —
+    and those reach ``/api/*`` too (OAuth login links, file-download hrefs) —
+    so it always gets the rendered page, unless the caller *prefers* JSON via
+    q-values (``application/json, text/html;q=0.5`` is an API client keeping
+    an html fallback). So does an Inertia visit (``X-Inertia`` header),
+    whatever its Accept — an Inertia client can only consume Inertia-protocol
+    responses, never a bare JSON body. Otherwise ``/api/*``, the documented
+    prefix for every module's JSON surface (``ModuleMeta.route_prefix``),
+    gets JSON — a bare ``fetch()`` sends ``Accept: */*`` — as does an
+    explicit ``Accept: application/json`` anywhere else.
+
+    ``text/html;q=0`` rules html out *everywhere*, not just under ``/api/*``:
+    once the caller has explicitly said they won't accept html, this never
+    chooses the html page. The (already-moot) html fallback survives only
+    when json wasn't mentioned either — there's nothing else to offer, so a
+    view path keeps its pre-existing default and an ``/api/*`` path keeps
+    getting JSON either way.
+    """
+    if request.headers.get(_INERTIA_HEADER):
+        return False
+    accept = request.headers.get("accept", "")
+    html_q = _explicit_accept_q(accept, "text/html")
+    json_q = _explicit_accept_q(accept, "application/json")
+    if html_q is not None and html_q > 0 and html_q >= (json_q or 0.0):
+        return False
+    path = request.url.path
+    is_api = path == "/api" or path.startswith("/api/")
+    if html_q == 0:
+        return is_api if json_q is None else True
+    return is_api or bool(json_q)
+
+
+async def render_error_page(request: Request, status_code: int, message: str) -> Response:
+    config: InertiaConfig = request.app.state.sm.inertia_config
+    try:
+        inertia = Inertia(request, config)
+        # This builds its own Inertia instead of going through get_inertia, so
+        # the share step has to be repeated here. Without it the error page
+        # renders raw translation keys (host.error.not_found_title) and loses
+        # auth/menus, so a signed-in user's 404 has no layout.
+        shared = getattr(request.state, "inertia_shared", None)
+        if shared:
+            inertia.share(**shared)
+        # The correlation id is the only handle a user has on their own failed
+        # request — without it a support report is just "it broke". It is already
+        # on every log line for this request, so quoting it back makes the page
+        # and the logs joinable.
+        response = await inertia.render(
+            "Error",
+            {
+                "status": status_code,
+                "message": message,
+                "correlation_id": getattr(request.state, "correlation_id", "") or "",
+            },
+        )
+        response.status_code = status_code
+        return response
+    except InertiaVersionConflictException as exc:
+        return await inertia_version_conflict_exception_handler(request, exc)
+    except Exception:
+        # Fallback if Inertia rendering itself fails (e.g. missing session)
+        logger.exception("Error page rendering failed, falling back to JSON")
+        return JSONResponse(
+            status_code=status_code, content={"detail": message or "Internal Server Error"}
+        )
+
+
+async def http_exception_handler(request: Request, exc: HTTPException) -> Response:
+    if exc.status_code in _INERTIA_ERROR_STATUSES and not _wants_json(request):
+        detail = str(exc.detail) if exc.detail else ""
+        return await render_error_page(request, exc.status_code, detail)
+    # Preserve exception headers (WWW-Authenticate, Retry-After, ...) the way
+    # FastAPI's stock handler does.
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={"detail": exc.detail},
+        headers=getattr(exc, "headers", None),
+    )
+
+
+async def not_found_error_handler(request: Request, exc: NotFoundError) -> Response:
+    if _wants_json(request):
+        return JSONResponse(status_code=404, content={"detail": str(exc)})
+    return await render_error_page(request, 404, str(exc))
+
+
+async def request_validation_error_handler(
+    request: Request, exc: RequestValidationError
+) -> Response:
+    """Return an Inertia error page for browser requests with invalid params.
+
+    Same negotiation rule as 403/404/500 (``_wants_json``), so one request
+    never sees two different error shapes depending on the error class.
+    """
+    if _wants_json(request):
+        return JSONResponse(status_code=422, content={"detail": jsonable_encoder(exc.errors())})
+    return await render_error_page(request, 422, "The requested URL contains invalid parameters.")
+
+
+async def unhandled_exception_handler(request: Request, exc: Exception) -> Response:
+    logger.exception("Unhandled exception: %s", exc)
+    if _wants_json(request):
+        return JSONResponse(status_code=500, content={"detail": "Internal Server Error"})
+    return await render_error_page(request, 500, "")

{simple_module_hosting-0.0.30 → simple_module_hosting-0.0.31}/simple_module_hosting/_phase_helpers.py

@@ -21,6 +21,7 @@ from inertia import (
 )
 from simple_module_core.diagnostics import Diagnostic, DiagnosticLevel
 from simple_module_core.exceptions import NotFoundError
+from simple_module_db import CommitBeforeResponseMiddleware
 from starlette.exceptions import HTTPException
 from starlette.middleware.gzip import GZipMiddleware
 from starlette.middleware.sessions import SessionMiddleware
@@ -46,6 +47,7 @@ from simple_module_hosting.settings import Settings
 from simple_module_hosting.static_files import PrecompressedStaticFiles
 
 if TYPE_CHECKING:
+    from simple_module_core.csp import CspSourceRegistry
     from simple_module_core.menu import MenuRegistry
     from simple_module_core.permissions import PermissionRegistry
 
@@ -72,19 +74,41 @@ def register_exception_handlers(app: FastAPI, modules: list) -> None:
         mod.register_exception_handlers(app)
 
 
+def build_csp(settings: Settings, csp_registry: CspSourceRegistry) -> str:
+    """Choose the CSP for this boot and fold in module-declared sources.
+
+    Development gets the Vite-widened policy; production the strict default.
+    ``csp_registry`` carries origins modules declared via
+    ``register_csp_sources`` (e.g. an external font host) — merged here so
+    both variants honor them. An empty registry leaves the policy unchanged.
+    """
+    base = (
+        SecurityHeadersMiddleware.dev_csp(settings.vite_dev_url)
+        if settings.is_development
+        else SecurityHeadersMiddleware.DEFAULT_CSP
+    )
+    return csp_registry.extend_policy(base)
+
+
 def install_middleware(
     app: FastAPI,
     settings: Settings,
     modules: list,
     menu_registry: MenuRegistry,
     perm_registry: PermissionRegistry,
+    csp_registry: CspSourceRegistry,
 ) -> None:
     """Install the full middleware pipeline.
 
     Order matters: last added = first executed. Execution order:
     (ProxyHeaders, if trusted_proxy) → CorrelationId → RequestLogging
-    → Security → Session → [module] → (Tenant, if multi_tenant) → Locale → Inertia.
+    → Security → Session → [module] → (Tenant, if multi_tenant) → Locale
+    → Inertia → CommitBeforeResponse.
     """
+    # Added first, so it is innermost and its send-wrapper is the first to see
+    # the response: the request's DB work commits before any byte reaches the
+    # client, instead of in get_db's post-response exit code (GH #257).
+    app.add_middleware(CommitBeforeResponseMiddleware)
     app.add_middleware(
         InertiaLayoutDataMiddleware,
         menu_registry=menu_registry,
@@ -102,16 +126,14 @@ def install_middleware(
         mod.register_middleware(app)
     app.add_middleware(SessionMiddleware, secret_key=settings.secret_key)
     # In dev, relax CSP so the browser can fetch @vite/client, main.tsx, and
-    # the HMR WebSocket from the Vite origin. HSTS is also suppressed because
-    # dev runs over plain HTTP on loopback.
+    # the HMR WebSocket from the Vite origin (build_csp picks the variant).
+    # HSTS is suppressed in dev because it runs over plain HTTP on loopback.
+    security_kwargs: dict[str, str | None] = {
+        "content_security_policy": build_csp(settings, csp_registry)
+    }
     if settings.is_development:
-        app.add_middleware(
-            SecurityHeadersMiddleware,
-            content_security_policy=SecurityHeadersMiddleware.dev_csp(settings.vite_dev_url),
-            strict_transport_security=None,
-        )
-    else:
-        app.add_middleware(SecurityHeadersMiddleware)
+        security_kwargs["strict_transport_security"] = None
+    app.add_middleware(SecurityHeadersMiddleware, **security_kwargs)
     # Compress response bodies. Added here so it sits inside CorrelationId and
     # RequestLogging (which set headers and read request state) but outside
     # everything that produces a body — including the /static mount, where it

simple_module_hosting-0.0.31/simple_module_hosting/_registrations.py

@@ -0,0 +1,69 @@
+"""Phase 5 of boot — every module's declarative registration hooks.
+
+Extracted from ``app_builder.py`` to keep that file readable; this is the one
+place that knows the full set of hooks a module may implement, and the order
+they run in. ``app_builder.create_app`` is the only intended caller.
+"""
+
+from __future__ import annotations
+
+import inspect
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+
+def run_module_registrations(
+    modules: list,
+    *,
+    app: FastAPI,
+    event_bus,
+    menu_registry,
+    perm_registry,
+    ff_registry,
+    health_registry,
+    public_route_registry,
+    design_pack_registry,
+    audit_link_registry,
+    csp_registry,
+) -> None:
+    """Invoke each module's registration hooks, in dependency order.
+
+    Health checks are attributed to the module that registers them, so the
+    dashboard can report health per module rather than one global number. The
+    owner is cleared afterwards: anything registered later — a module's
+    ``on_startup``, say — belongs to no module in this loop, and inheriting
+    the last one's name would be a lie.
+    """
+    for mod in modules:
+        mod.register_menu_items(menu_registry)
+        mod.register_permissions(perm_registry)
+        mod.register_feature_flags(ff_registry)
+        dispatch_event_handlers(mod, event_bus, app)
+        health_registry.set_owner(mod.meta.name)
+        mod.register_health_checks(health_registry)
+        mod.register_public_routes(public_route_registry)
+        # csp before design packs — the documented lifecycle order
+        # (docs/framework/lifecycle.md).
+        mod.register_csp_sources(csp_registry)
+        mod.register_design_packs(design_pack_registry)
+        mod.register_audit_links(audit_link_registry)
+
+    health_registry.set_owner("")
+
+
+def dispatch_event_handlers(mod, event_bus, app: FastAPI) -> None:
+    """Call ``mod.register_event_handlers`` with or without ``app``.
+
+    Back-compat shim for modules that still override the one-arg form
+    ``(self, bus)``; passing ``app=`` to those crashes.
+    """
+    sig = inspect.signature(mod.register_event_handlers)
+    accepts_app = "app" in sig.parameters or any(
+        p.kind is inspect.Parameter.VAR_KEYWORD for p in sig.parameters.values()
+    )
+    if accepts_app:
+        mod.register_event_handlers(event_bus, app=app)
+    else:
+        mod.register_event_handlers(event_bus)

{simple_module_hosting-0.0.30 → simple_module_hosting-0.0.31}/simple_module_hosting/app_builder.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import inspect
 import logging
 import os
 from collections.abc import AsyncGenerator
@@ -10,6 +9,8 @@ from contextlib import asynccontextmanager
 from pathlib import Path
 
 from fastapi import FastAPI
+from simple_module_core import CspSourceRegistry
+from simple_module_core.audit_links import AuditLinkRegistry
 from simple_module_core.design_packs import DesignPackRegistry
 from simple_module_core.diagnostics import DiagnosticLevel, print_diagnostics, run_diagnostics
 from simple_module_core.discovery import discover_modules, select_auth_provider, topological_sort
@@ -23,6 +24,7 @@ from simple_module_core.services import Services
 from simple_module_db.listeners import register_listeners
 from simple_module_db.session import init_db
 
+from simple_module_hosting._db_health import register_database_check
 from simple_module_hosting._inertia_setup import setup_inertia
 from simple_module_hosting._phase_helpers import (
     attach_public_routes,
@@ -33,6 +35,7 @@ from simple_module_hosting._phase_helpers import (
     register_host_settings,
     wire_module_routes,
 )
+from simple_module_hosting._registrations import run_module_registrations
 from simple_module_hosting.health import router as health_router
 from simple_module_hosting.i18n_manifest import build_i18n_registry, emit_frontend_types
 from simple_module_hosting.migrations import check_migrations
@@ -66,6 +69,10 @@ def _resolve_project_root() -> Path:
     Falls back to ``parents[3]`` for the in-tree dev loop only when the walk
     finds nothing — which still keeps ``framework/`` users working without
     setting the env var explicitly.
+
+    Compare ``simple_module_core.dotenv.find_env_file``: both honor
+    ``SM_PROJECT_ROOT`` first, but this anchors the static/i18n root while
+    that anchors which ``.env`` loads — different sentinels, kept separate.
     """
     override = os.environ.get(_ENV_PROJECT_ROOT)
     if override:
@@ -80,22 +87,6 @@ def _resolve_project_root() -> Path:
 _PROJECT_ROOT = _resolve_project_root()
 
 
-def _register_event_handlers(mod, event_bus: EventBus, app: FastAPI) -> None:
-    """Dispatch to ``mod.register_event_handlers`` with or without ``app``.
-
-    Back-compat shim for modules that still override the one-arg form
-    ``(self, bus)``; passing ``app=`` to those crashes.
-    """
-    sig = inspect.signature(mod.register_event_handlers)
-    accepts_app = "app" in sig.parameters or any(
-        p.kind is inspect.Parameter.VAR_KEYWORD for p in sig.parameters.values()
-    )
-    if accepts_app:
-        mod.register_event_handlers(event_bus, app=app)
-    else:
-        mod.register_event_handlers(event_bus)
-
-
 def create_app(settings: Settings | None = None) -> FastAPI:
     """Build and configure the full FastAPI application.
 
@@ -173,6 +164,7 @@ def create_app(settings: Settings | None = None) -> FastAPI:
     health_registry = HealthRegistry()
     public_route_registry = PublicRouteRegistry()
     design_pack_registry = DesignPackRegistry()
+    audit_link_registry = AuditLinkRegistry()
 
     @asynccontextmanager
     async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
@@ -219,14 +211,20 @@ def create_app(settings: Settings | None = None) -> FastAPI:
             print_diagnostics(settings_diagnostics)
 
     # ── Phase 5: Module registrations ──────────────────────
-    for mod in modules:
-        mod.register_menu_items(menu_registry)
-        mod.register_permissions(perm_registry)
-        mod.register_feature_flags(ff_registry)
-        _register_event_handlers(mod, event_bus, app)
-        mod.register_health_checks(health_registry)
-        mod.register_public_routes(public_route_registry)
-        mod.register_design_packs(design_pack_registry)
+    csp_registry = CspSourceRegistry()
+    run_module_registrations(
+        modules,
+        app=app,
+        event_bus=event_bus,
+        menu_registry=menu_registry,
+        perm_registry=perm_registry,
+        ff_registry=ff_registry,
+        health_registry=health_registry,
+        public_route_registry=public_route_registry,
+        design_pack_registry=design_pack_registry,
+        audit_link_registry=audit_link_registry,
+        csp_registry=csp_registry,
+    )
 
     attach_public_routes(app, settings, public_route_registry)
 
@@ -255,6 +253,9 @@ def create_app(settings: Settings | None = None) -> FastAPI:
         pool_recycle=settings.db_pool_recycle,
     )
     register_listeners(db_state)
+    # The host's own readiness signal, and the only probe-safe check in a
+    # default install — module checks reach third parties and are on-demand.
+    register_database_check(health_registry, db_state)
 
     # ── Phase 7: Inertia + exception handlers ──────────────
     inertia_config = setup_inertia(app, settings, modules, _PROJECT_ROOT)
@@ -263,7 +264,9 @@ def create_app(settings: Settings | None = None) -> FastAPI:
     register_exception_handlers(app, modules)
 
     # ── Phase 8: Middleware pipeline ───────────────────────
-    install_middleware(app, settings, modules, menu_registry, perm_registry)
+    install_middleware(
+        app, settings, modules, menu_registry, perm_registry, csp_registry=csp_registry
+    )
 
     # ── Phase 9: Routes, health, static files ──────────────
     for mod in modules:
@@ -288,6 +291,7 @@ def create_app(settings: Settings | None = None) -> FastAPI:
         health_registry=health_registry,
         public_routes=public_route_registry,
         design_packs=design_pack_registry,
+        audit_links=audit_link_registry,
         i18n_registry=i18n_registry,
         inertia_config=inertia_config,
         modules=tuple(modules),

{simple_module_hosting-0.0.30 → simple_module_hosting-0.0.31}/simple_module_hosting/assets.py

@@ -47,6 +47,8 @@ logger = logging.getLogger(__name__)
 THEME_CSS = "theme.css"
 STYLES_CSS = "styles.css"
 PACKAGE_JSON = "package.json"
+PAGES_DIR = "pages"
+COMPONENTS_DIR = "components"
 
 
 @dataclass(frozen=True)
@@ -60,6 +62,7 @@ class ModuleAssets:
     theme_css: Path | None
     styles_css: Path | None
     npm_name: str | None = None
+    components_dir: Path | None = None
 
 
 def find_npm_name(pkg_root: Path) -> str | None:
@@ -114,7 +117,8 @@ def compute_module_assets(modules: Sequence[ModuleBase]) -> list[ModuleAssets]:
                 "Module '%s': package %s not importable — skipping", mod.meta.name, pkg_name
             )
             continue
-        pages_dir = pkg_root / "pages"
+        pages_dir = pkg_root / PAGES_DIR
+        components_dir = pkg_root / COMPONENTS_DIR
         theme = pkg_root / THEME_CSS
         styles = pkg_root / STYLES_CSS
         entry = ModuleAssets(
@@ -125,8 +129,9 @@ def compute_module_assets(modules: Sequence[ModuleBase]) -> list[ModuleAssets]:
             theme_css=theme.resolve() if theme.is_file() else None,
             styles_css=styles.resolve() if styles.is_file() else None,
             npm_name=find_npm_name(pkg_root),
+            components_dir=components_dir.resolve() if components_dir.is_dir() else None,
         )
-        if entry.pages_dir or entry.theme_css or entry.styles_css:
+        if entry.pages_dir or entry.theme_css or entry.styles_css or entry.components_dir:
             result.append(entry)
     return result
 
@@ -157,13 +162,23 @@ def render_modules_css(
     ``@import`` is emitted for *every* module, in-repo and wheel alike, because
     there is no static-glob equivalent for CSS.
 
+    Both ``pages/`` and ``components/`` are scanned. A wheel module's widgets
+    live under ``components/``, and leaving them out meant every host had to
+    hand-write a ``@source`` pointing into ``.venv`` — which cannot be written
+    portably: POSIX venvs nest under ``lib/python3.x/site-packages`` while
+    Windows uses ``Lib/site-packages``. Tailwind accepts a glob that matches
+    nothing without complaint, so the hand-written POSIX path silently dropped
+    every widget class on Windows. Emitting the resolved absolute path here
+    works on both. See GH #258.
+
     Every path is absolute, so nothing here depends on the host's
     ``vite.config.ts`` — see the module docstring for why that matters.
     """
     source_lines = [
-        f'@source "{e.pages_dir.as_posix()}/**/*.{{ts,tsx}}";'
+        f'@source "{d.as_posix()}/**/*.{{ts,tsx}}";'
         for e in assets
-        if e.pages_dir and not in_repo(e.pages_dir)
+        for d in (e.pages_dir, e.components_dir)
+        if d and not in_repo(d)
     ]
     theme_lines = [f'@import "{e.theme_css.as_posix()}";' for e in assets if e.theme_css]
     style_lines = [
@@ -205,6 +220,7 @@ def render_assets_json(assets: Sequence[ModuleAssets]) -> str:
             "package_name": e.package_name,
             "package": e.package_dir.as_posix(),
             "pages": e.pages_dir.as_posix() if e.pages_dir else None,
+            "components": e.components_dir.as_posix() if e.components_dir else None,
             "theme": e.theme_css.as_posix() if e.theme_css else None,
             "styles": e.styles_css.as_posix() if e.styles_css else None,
             "npm_name": e.npm_name,