@telorun/http-server 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @telorun/http-server
 
+## 0.14.0
+
+### Minor Changes
+
+- ca095ac: Add `Http.Static`, a `Telo.Mount` that serves a directory of static assets (a built SPA, plain HTML, images, …). Mount it on an `Http.Server` alongside an `Http.Api` so one application delivers both its API and its frontend. Supports a manifest-relative `root` (assets ship with the app), `index`, `spaFallback` for client-side routing, and `maxAge` / `immutable` cache control. Backed by `@fastify/static` (MIME, ETag, conditional and range requests).
+
+### Patch Changes
+
+- @telorun/http-dispatch@0.4.1
+
+## 0.13.0
+
+### Minor Changes
+
+- 95f168e: Cache, rate-limit, and background-task primitives, plus a comprehensive URL-shortener example.
+
+  - New `cache` family: the backend-pluggable `Cache.Store` abstract with `Cache.Lookup` / `Cache.Entry` (freshness-aware: `ttl` fresh window + optional `staleTtl` grace window, `state` of `miss`/`fresh`/`stale`) and the `Cache.View` read-through decorator (single-flight background revalidation). Backends ship as `cache-memory` (`CacheMemory.Store`) and `cache-redis` (`CacheRedis.Store`, with observable degrade-to-`fallback`).
+  - New `rate-limit` module: `RateLimit.Guard`, a non-throwing sliding-window limiter whose counters live in any `Cache.Store`.
+  - `run` gains `Run.Detach` (generic, zero-config fire-and-forget).
+  - SDK + kernel: `ResourceContext.runDetached(fn)` runs a function detached from the caller's cancellation/trace scope; the kernel tracks each detached task against its owning resource and drains it (bounded) when that resource tears down, routing failures to the EventBus. Used by `Run.Detach` and `Cache.View`'s background revalidation.
+  - `http-server`: `Http.Server.trustProxy` and a derived `request.ip` in the handler CEL context (canonical client address for rate-limit keys).
+
+### Patch Changes
+
+- 95f168e: Fix OpenAPI documentation conflating routes from different mounts.
+
+  Each `Http.Api` route is now registered at its full `<mountPrefix><path>` instead of inside a Fastify `{ prefix }`-encapsulated context, and the generated OpenAPI `servers` block is a single origin (`baseUrl`, the forwarded host, or relative `/`) rather than one entry per mount prefix. Previously `@fastify/swagger` stripped each mount's prefix from the documented path while the prefixes were hoisted into `servers`, so different APIs mounted at different prefixes collapsed together — e.g. an `Http.Api` mounted at `/admin` was documented at `/links` instead of `/admin/links`. Actual request routing was unaffected; this corrects only the generated document.
+
+  - @telorun/http-dispatch@0.4.1
+
 ## 0.12.0
 
 ### Minor Changes

package/README.md

@@ -9,6 +9,7 @@ Language- and framework-agnostic HTTP server for Telo. Declarative routes, schem
 - **Schema-driven validation** — `request.schema` (`body`, `query`, `params`, `headers`) yields a standardized HTTP 400 with `details[]` on failure.
 - **Typed returns and catches** — render successful values and structured `InvokeError`s into status + headers + per-MIME bodies via CEL.
 - **Composable mounts** — attach `Telo.Mount` resources (HTTP APIs, MCP endpoints, custom mounts) under any path prefix.
+- **Serve a frontend** — `Http.Static` serves a directory of assets (a built SPA, plain HTML) so one application delivers both its API and its UI.
 - **CORS and content-type parsers** — first-class manifest fields; no controller code needed.
 
 ## Kinds
@@ -17,6 +18,7 @@ Language- and framework-agnostic HTTP server for Telo. Declarative routes, schem
 | --- | --- |
 | `Http.Server` | Long-lived HTTP listener that hosts mounts on configured paths and ports. |
 | `Http.Api` | Mountable router exposing route definitions with returns/catches rendering. |
+| `Http.Static` | Mountable static-file server for a directory of assets (built SPA, plain HTML, images). |
 
 ## Example
 
@@ -77,6 +79,7 @@ code: |
 ## Reference
 
 - [`Http.Server` / `Http.Api` returns & catches](docs/returns-and-catches.md) — outcome lists, MIME negotiation, stream mode.
+- [Serving static files & frontends](docs/static-files.md) — `Http.Static`, manifest-relative roots, SPA fallback, asset caching.
 
 ## Implementation Contract
 
@@ -210,15 +213,18 @@ request:
 ### 5. External URL & OpenAPI `servers`
 
 A server is usually reached through a reverse proxy / ingress, so its own bound
-`host:port` is not the URL clients use. The generated OpenAPI `servers` block MUST
-follow this resolution, identically across runtimes (Node/Rust/Go) — the inputs
-are standard HTTP, never a framework's proxy-config object:
+`host:port` is not the URL clients use. The generated OpenAPI `servers` block is a
+**single origin** — each operation is documented at its full `<mountPrefix><path>`,
+so different APIs mounted at different prefixes stay distinct (an `Http.Api` mounted
+at `/admin` is documented at `/admin/...`, never flattened to `/...`). The origin
+resolves identically across runtimes (Node/Rust/Go) — the inputs are standard HTTP,
+never a framework's proxy-config object:
 
 | Manifest | `servers[].url` |
 | --- | --- |
-| `baseUrl: <url>` | `<url><mountPrefix>` — explicit, fixed; wins over everything |
-| `trustForwardedHeaders: true` | `<X-Forwarded-Proto>://<X-Forwarded-Host><mountPrefix>`, derived per request |
-| neither (default) | `<mountPrefix>` — **relative**; the client resolves it against the origin the document was loaded from |
+| `baseUrl: <url>` | `<url>` — explicit, fixed; wins over everything |
+| `trustForwardedHeaders: true` | `<X-Forwarded-Proto>://<X-Forwarded-Host>`, derived per request |
+| neither (default) | `/` — **relative**; the client resolves it against the origin the document was loaded from |
 
 - The default is **relative** so the document is correct behind any proxy, ingress,
   or origin with zero configuration.

package/dist/http-api-controller.js

@@ -35,28 +35,27 @@ export class HttpServerApi {
     }
     async init() { }
     register(app, prefix = "") {
-        if (prefix) {
-            app.register(async (scoped) => {
-                this.registerRoutes(scoped);
-            }, { prefix });
-        }
-        else {
-            this.registerRoutes(app);
-        }
+        // Register each route at its full `prefix + path` on the root app rather than
+        // inside a `{ prefix }`-encapsulated context. Fastify encapsulation makes
+        // @fastify/swagger strip the prefix from the documented path, which conflates
+        // routes from different mounts (e.g. an Api at `/admin` documented as `/links`).
+        // Carrying the prefix on the path keeps the OpenAPI doc unambiguous for any mix
+        // of mounts; a single `servers` origin is set by the server controller.
+        this.registerRoutes(app, normalizeMountPrefix(prefix));
     }
-    registerRoutes(app) {
+    registerRoutes(app, prefix) {
         const routes = this.manifest.routes || [];
         for (const route of routes) {
-            this.registerRoute(app, route);
+            this.registerRoute(app, route, prefix);
         }
     }
-    registerRoute(app, route) {
+    registerRoute(app, route, prefix) {
         // After Phase 5 injection, KindRef<Invocable> is replaced with the live Invocable instance.
         const handler = route.handler;
         const handlerRef = this.handlerRefs.get(route);
         const handlerKind = handlerRef?.kind ?? "";
         const handlerName = handlerRef?.name ?? "";
-        const translatedPath = translateOpenApiPath(route.request.path);
+        const translatedPath = prefix + translateOpenApiPath(route.request.path);
         const schema = { response: {} };
         // A stream-marked body is delivered as a raw `Stream<Uint8Array>` (see the
         // server's `contentTypeParsers[].stream`); it is opaque to AJV, so skip
@@ -97,6 +96,9 @@ export class HttpServerApi {
                         query: request.query || {},
                         headers: normalizeHeaders(request.headers),
                         body: streamBody ? toByteStream(request) : request.body,
+                        // Canonical client address — honours X-Forwarded-For per the
+                        // server's `trustProxy` setting (Fastify resolves it).
+                        ip: request.ip,
                     },
                 };
                 const acceptHeader = request.headers["accept"]?.toString();
@@ -193,6 +195,16 @@ export async function create(resource, ctx) {
 function translateOpenApiPath(openApiPath) {
     return openApiPath.replace(/{([a-zA-Z_][a-zA-Z0-9_]*)}/g, ":$1");
 }
+/**
+ * Normalizes a mount prefix into a path segment that prepends cleanly to a route
+ * path: the root mount (`""` / `"/"`) contributes nothing, and a trailing slash
+ * is dropped so `"/admin" + "/links"` is `/admin/links`, never `/admin//links`.
+ */
+function normalizeMountPrefix(prefix) {
+    if (!prefix || prefix === "/")
+        return "";
+    return prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+}
 /**
  * Wraps an incoming request's raw body as a `Stream<Uint8Array>`. Requires a
  * stream content-type parser (`contentTypeParsers[].stream`) for the request's

package/dist/http-server-controller.d.ts

@@ -26,6 +26,7 @@ type HttpServerResource = RuntimeResource & {
     port?: number;
     baseUrl?: string;
     trustForwardedHeaders?: boolean;
+    trustProxy?: boolean | number;
     logger?: boolean;
     cors?: CorsOptions;
     contentTypeParsers?: Array<{

package/dist/http-server-controller.js

@@ -28,11 +28,14 @@ class HttpServer {
         if (!this.port) {
             throw new Error("Http.Server port is required");
         }
+        // `trustProxy` is the single Fastify knob behind both the forwarded
+        // protocol/host (request.protocol/host) and the canonical client address
+        // (request.ip). An explicit `trustProxy` (boolean / hop-count) wins; absent
+        // it, the legacy `trustForwardedHeaders` boolean still applies.
+        const trustProxy = resource.trustProxy ?? this.trustForwardedHeaders;
         this.app = Fastify({
             logger: resource.logger,
-            // Honour X-Forwarded-Proto / X-Forwarded-Host so request.protocol/host (and
-            // the OpenAPI servers derived from them) reflect a fronting proxy's URL.
-            trustProxy: this.trustForwardedHeaders,
+            trustProxy,
             ajv: { customOptions: { useDefaults: true }, plugins: [addFormats.default] },
         });
     }
@@ -96,15 +99,13 @@ class HttpServer {
             throw error;
         });
         if (this.resource.openapi) {
-            const mounts = this.resource.mounts || [];
-            const prefixes = [...new Set(mounts.map((mount) => mount.path || ""))];
-            // Server URL precedence: an explicit `baseUrl` is an absolute, fixed
-            // override; otherwise the URLs are relative (just the mount prefix) so the
-            // doc is correct behind any proxy/ingress/origin without configuration —
-            // the client resolves them against wherever the reference was loaded.
-            const servers = prefixes.map((prefix) => ({
-                url: this.resource.baseUrl ? this.resource.baseUrl + prefix : prefix || "/",
-            }));
+            // Each route is documented at its full `mount-prefix + path` (see
+            // http-api-controller), so the server is a single origin, not one entry per
+            // mount. Server URL precedence: an explicit `baseUrl` is an absolute, fixed
+            // override; otherwise the URL is relative (`/`) so the doc is correct behind
+            // any proxy/ingress/origin — the client resolves it against wherever the
+            // reference was loaded.
+            const servers = [{ url: this.resource.baseUrl ?? "/" }];
             await this.app.register(swagger, {
                 openapi: {
                     openapi: "3.0.0",
@@ -135,9 +136,7 @@ class HttpServer {
                     try {
                         const doc = JSON.parse(text);
                         if (doc && typeof doc === "object" && Array.isArray(doc.servers)) {
-                            doc.servers = prefixes.map((prefix) => ({
-                                url: `${request.protocol}://${request.host}${prefix}`,
-                            }));
+                            doc.servers = [{ url: `${request.protocol}://${request.host}` }];
                             const out = JSON.stringify(doc);
                             reply.header("content-length", Buffer.byteLength(out));
                             return out;

package/dist/http-static-controller.d.ts

@@ -0,0 +1,10 @@
+import { type ResourceContext, type ResourceInstance, type RuntimeResource } from "@telorun/sdk";
+type HttpStaticResource = RuntimeResource & {
+    root: string;
+    index?: string;
+    spaFallback?: boolean;
+    maxAge?: number;
+    immutable?: boolean;
+};
+export declare function create(resource: HttpStaticResource, ctx: ResourceContext): Promise<ResourceInstance>;
+export {};

package/dist/http-static-controller.js

@@ -0,0 +1,92 @@
+import fastifyStatic from "@fastify/static";
+import { readFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Collapse a mount prefix to a single leading slash with no trailing slash;
+ *  an empty/`"/"` prefix becomes `"/"`. Unlike Http.Api (which returns `""` and
+ *  concatenates the prefix onto each route path on the root app), this serves
+ *  from an encapsulated `register({ prefix })`, which needs a non-empty prefix —
+ *  hence root maps to `"/"`, not `""`. */
+function normalizeMountPrefix(prefix) {
+    const trimmed = prefix.replace(/\/+$/, "");
+    if (!trimmed)
+        return "/";
+    return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+/** Serves a directory of static assets (a built SPA, plain HTML, images, …) as a
+ *  Telo.Mount. Mirrors Http.Api's `register(app, prefix)` contract so it slots into
+ *  Http.Server.mounts identically. Backed by @fastify/static, which handles MIME,
+ *  ETag, conditional requests, and range requests. */
+class HttpStatic {
+    root;
+    index;
+    spaFallback;
+    maxAge;
+    immutable;
+    constructor(resource, ctx) {
+        this.root = resolveRoot(resource.root, ctx);
+        this.index = resource.index ?? "index.html";
+        this.spaFallback = resource.spaFallback === true;
+        this.maxAge = resource.maxAge;
+        this.immutable = resource.immutable === true;
+    }
+    async init() { }
+    register(app, prefix = "") {
+        const mountPrefix = normalizeMountPrefix(prefix);
+        const root = this.root;
+        const index = this.index;
+        const spaFallback = this.spaFallback;
+        const cacheControl = this.maxAge != null;
+        // @fastify/static takes maxAge in milliseconds; the manifest declares seconds.
+        const maxAge = this.maxAge != null ? this.maxAge * 1000 : undefined;
+        const immutable = this.immutable;
+        // Encapsulated scope so the static plugin, its routes, and the SPA not-found
+        // handler are confined to this mount's prefix and don't collide with sibling
+        // mounts or the server-level notFoundHandler. `decorateReply: false` keeps
+        // multiple static mounts from fighting over the shared `reply.sendFile`
+        // decorator — the SPA fallback reads the index file directly instead.
+        app.register(async (scope) => {
+            await scope.register(fastifyStatic, {
+                root,
+                prefix: "/",
+                index,
+                // With spaFallback we want unmatched paths to fall through to the
+                // not-found handler (client-side routing); the wildcard glob route
+                // would otherwise 404 them itself.
+                wildcard: !spaFallback,
+                cacheControl,
+                maxAge,
+                immutable,
+                decorateReply: false,
+            });
+            if (spaFallback) {
+                const indexPath = join(root, index);
+                // Deep-link/refresh navigations are the common path for a client-routed
+                // SPA, so read the index once and serve the cached buffer — mirroring
+                // the caching @fastify/static does for real files. (A build that swaps
+                // index.html while the server runs isn't picked up, consistent with
+                // @fastify/static's own behavior.)
+                let indexHtml = null;
+                scope.setNotFoundHandler(async (_request, reply) => {
+                    if (indexHtml === null)
+                        indexHtml = await readFile(indexPath);
+                    return reply.type("text/html").send(indexHtml);
+                });
+            }
+        }, { prefix: mountPrefix });
+    }
+}
+/** Resolve the asset root relative to the manifest that declared the resource, so
+ *  the frontend ships co-located with the app (same pattern as mcp-client). */
+function resolveRoot(root, ctx) {
+    if (isAbsolute(root))
+        return root;
+    const source = ctx.moduleContext.source;
+    if (!source.startsWith("file://"))
+        return resolve(root);
+    const baseDir = dirname(fileURLToPath(source));
+    return resolve(baseDir, root);
+}
+export async function create(resource, ctx) {
+    return new HttpStatic(resource, ctx);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/http-server",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Telo HTTP Server module - HTTP server and API resource kinds for Telo manifests.",
   "keywords": [
     "telo",
@@ -33,10 +33,16 @@
       "types": "./dist/http-api-controller.d.ts",
       "bun": "./src/http-api-controller.ts",
       "import": "./dist/http-api-controller.js"
+    },
+    "./http-static": {
+      "types": "./dist/http-static-controller.d.ts",
+      "bun": "./src/http-static-controller.ts",
+      "import": "./dist/http-static-controller.js"
     }
   },
   "dependencies": {
     "@fastify/cors": "^11.2.0",
+    "@fastify/static": "^8.0.0",
     "@fastify/swagger": "^9.6.1",
     "@scalar/fastify-api-reference": "^1.44.6",
     "@sinclair/typebox": "^0.34.48",
@@ -49,7 +55,7 @@
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.32.0"
+    "@telorun/sdk": "0.34.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/http-api-controller.ts

@@ -65,32 +65,29 @@ export class HttpServerApi implements ResourceInstance {
   async init() {}
 
   register(app: FastifyInstance, prefix = "") {
-    if (prefix) {
-      app.register(
-        async (scoped) => {
-          this.registerRoutes(scoped);
-        },
-        { prefix },
-      );
-    } else {
-      this.registerRoutes(app);
-    }
+    // Register each route at its full `prefix + path` on the root app rather than
+    // inside a `{ prefix }`-encapsulated context. Fastify encapsulation makes
+    // @fastify/swagger strip the prefix from the documented path, which conflates
+    // routes from different mounts (e.g. an Api at `/admin` documented as `/links`).
+    // Carrying the prefix on the path keeps the OpenAPI doc unambiguous for any mix
+    // of mounts; a single `servers` origin is set by the server controller.
+    this.registerRoutes(app, normalizeMountPrefix(prefix));
   }
 
-  private registerRoutes(app: FastifyInstance) {
+  private registerRoutes(app: FastifyInstance, prefix: string) {
     const routes = this.manifest.routes || [];
     for (const route of routes) {
-      this.registerRoute(app, route);
+      this.registerRoute(app, route, prefix);
     }
   }
 
-  private registerRoute(app: FastifyInstance, route: HttpApiRouteManifest) {
+  private registerRoute(app: FastifyInstance, route: HttpApiRouteManifest, prefix: string) {
     // After Phase 5 injection, KindRef<Invocable> is replaced with the live Invocable instance.
     const handler = route.handler as unknown as ResourceInstance | undefined;
     const handlerRef = this.handlerRefs.get(route as unknown as object);
     const handlerKind = handlerRef?.kind ?? "";
     const handlerName = handlerRef?.name ?? "";
-    const translatedPath = translateOpenApiPath(route.request.path);
+    const translatedPath = prefix + translateOpenApiPath(route.request.path);
 
     const schema: any = { response: {} };
 
@@ -131,6 +128,9 @@ export class HttpServerApi implements ResourceInstance {
             query: request.query || {},
             headers: normalizeHeaders(request.headers),
             body: streamBody ? toByteStream(request) : request.body,
+            // Canonical client address — honours X-Forwarded-For per the
+            // server's `trustProxy` setting (Fastify resolves it).
+            ip: request.ip,
           },
         };
         const acceptHeader = (
@@ -259,6 +259,16 @@ function translateOpenApiPath(openApiPath: string): string {
   return openApiPath.replace(/{([a-zA-Z_][a-zA-Z0-9_]*)}/g, ":$1");
 }
 
+/**
+ * Normalizes a mount prefix into a path segment that prepends cleanly to a route
+ * path: the root mount (`""` / `"/"`) contributes nothing, and a trailing slash
+ * is dropped so `"/admin" + "/links"` is `/admin/links`, never `/admin//links`.
+ */
+function normalizeMountPrefix(prefix: string): string {
+  if (!prefix || prefix === "/") return "";
+  return prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+}
+
 /**
  * Wraps an incoming request's raw body as a `Stream<Uint8Array>`. Requires a
  * stream content-type parser (`contentTypeParsers[].stream`) for the request's

package/src/http-server-controller.ts

@@ -46,6 +46,7 @@ type HttpServerResource = RuntimeResource & {
   port?: number;
   baseUrl?: string;
   trustForwardedHeaders?: boolean;
+  trustProxy?: boolean | number;
   logger?: boolean;
   cors?: CorsOptions;
   contentTypeParsers?: Array<{ contentType: string; parser?: Invocable; stream?: boolean }>;
@@ -105,11 +106,14 @@ class HttpServer implements ResourceInstance {
     if (!this.port) {
       throw new Error("Http.Server port is required");
     }
+    // `trustProxy` is the single Fastify knob behind both the forwarded
+    // protocol/host (request.protocol/host) and the canonical client address
+    // (request.ip). An explicit `trustProxy` (boolean / hop-count) wins; absent
+    // it, the legacy `trustForwardedHeaders` boolean still applies.
+    const trustProxy = resource.trustProxy ?? this.trustForwardedHeaders;
     this.app = Fastify({
       logger: resource.logger,
-      // Honour X-Forwarded-Proto / X-Forwarded-Host so request.protocol/host (and
-      // the OpenAPI servers derived from them) reflect a fronting proxy's URL.
-      trustProxy: this.trustForwardedHeaders,
+      trustProxy,
       ajv: { customOptions: { useDefaults: true }, plugins: [addFormats.default as any] },
     });
   }
@@ -178,15 +182,13 @@ class HttpServer implements ResourceInstance {
       throw error;
     });
     if (this.resource.openapi) {
-      const mounts = this.resource.mounts || [];
-      const prefixes = [...new Set(mounts.map((mount) => mount.path || ""))];
-      // Server URL precedence: an explicit `baseUrl` is an absolute, fixed
-      // override; otherwise the URLs are relative (just the mount prefix) so the
-      // doc is correct behind any proxy/ingress/origin without configuration —
-      // the client resolves them against wherever the reference was loaded.
-      const servers = prefixes.map((prefix) => ({
-        url: this.resource.baseUrl ? this.resource.baseUrl + prefix : prefix || "/",
-      }));
+      // Each route is documented at its full `mount-prefix + path` (see
+      // http-api-controller), so the server is a single origin, not one entry per
+      // mount. Server URL precedence: an explicit `baseUrl` is an absolute, fixed
+      // override; otherwise the URL is relative (`/`) so the doc is correct behind
+      // any proxy/ingress/origin — the client resolves it against wherever the
+      // reference was loaded.
+      const servers = [{ url: this.resource.baseUrl ?? "/" }];
       await this.app.register(swagger, {
         openapi: {
           openapi: "3.0.0",
@@ -216,9 +218,7 @@ class HttpServer implements ResourceInstance {
           try {
             const doc = JSON.parse(text);
             if (doc && typeof doc === "object" && Array.isArray(doc.servers)) {
-              doc.servers = prefixes.map((prefix) => ({
-                url: `${request.protocol}://${request.host}${prefix}`,
-              }));
+              doc.servers = [{ url: `${request.protocol}://${request.host}` }];
               const out = JSON.stringify(doc);
               reply.header("content-length", Buffer.byteLength(out));
               return out;

package/src/http-static-controller.ts

@@ -0,0 +1,113 @@
+import fastifyStatic from "@fastify/static";
+import { type ResourceContext, type ResourceInstance, type RuntimeResource } from "@telorun/sdk";
+import { FastifyInstance } from "fastify";
+import { readFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+type HttpStaticResource = RuntimeResource & {
+  root: string;
+  index?: string;
+  spaFallback?: boolean;
+  maxAge?: number;
+  immutable?: boolean;
+};
+
+/** Collapse a mount prefix to a single leading slash with no trailing slash;
+ *  an empty/`"/"` prefix becomes `"/"`. Unlike Http.Api (which returns `""` and
+ *  concatenates the prefix onto each route path on the root app), this serves
+ *  from an encapsulated `register({ prefix })`, which needs a non-empty prefix —
+ *  hence root maps to `"/"`, not `""`. */
+function normalizeMountPrefix(prefix: string): string {
+  const trimmed = prefix.replace(/\/+$/, "");
+  if (!trimmed) return "/";
+  return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+
+/** Serves a directory of static assets (a built SPA, plain HTML, images, …) as a
+ *  Telo.Mount. Mirrors Http.Api's `register(app, prefix)` contract so it slots into
+ *  Http.Server.mounts identically. Backed by @fastify/static, which handles MIME,
+ *  ETag, conditional requests, and range requests. */
+class HttpStatic implements ResourceInstance {
+  private readonly root: string;
+  private readonly index: string;
+  private readonly spaFallback: boolean;
+  private readonly maxAge?: number;
+  private readonly immutable: boolean;
+
+  constructor(resource: HttpStaticResource, ctx: ResourceContext) {
+    this.root = resolveRoot(resource.root, ctx);
+    this.index = resource.index ?? "index.html";
+    this.spaFallback = resource.spaFallback === true;
+    this.maxAge = resource.maxAge;
+    this.immutable = resource.immutable === true;
+  }
+
+  async init() {}
+
+  register(app: FastifyInstance, prefix = ""): void {
+    const mountPrefix = normalizeMountPrefix(prefix);
+    const root = this.root;
+    const index = this.index;
+    const spaFallback = this.spaFallback;
+    const cacheControl = this.maxAge != null;
+    // @fastify/static takes maxAge in milliseconds; the manifest declares seconds.
+    const maxAge = this.maxAge != null ? this.maxAge * 1000 : undefined;
+    const immutable = this.immutable;
+
+    // Encapsulated scope so the static plugin, its routes, and the SPA not-found
+    // handler are confined to this mount's prefix and don't collide with sibling
+    // mounts or the server-level notFoundHandler. `decorateReply: false` keeps
+    // multiple static mounts from fighting over the shared `reply.sendFile`
+    // decorator — the SPA fallback reads the index file directly instead.
+    app.register(
+      async (scope) => {
+        await scope.register(fastifyStatic, {
+          root,
+          prefix: "/",
+          index,
+          // With spaFallback we want unmatched paths to fall through to the
+          // not-found handler (client-side routing); the wildcard glob route
+          // would otherwise 404 them itself.
+          wildcard: !spaFallback,
+          cacheControl,
+          maxAge,
+          immutable,
+          decorateReply: false,
+        });
+
+        if (spaFallback) {
+          const indexPath = join(root, index);
+          // Deep-link/refresh navigations are the common path for a client-routed
+          // SPA, so read the index once and serve the cached buffer — mirroring
+          // the caching @fastify/static does for real files. (A build that swaps
+          // index.html while the server runs isn't picked up, consistent with
+          // @fastify/static's own behavior.)
+          let indexHtml: Buffer | null = null;
+          scope.setNotFoundHandler(async (_request, reply) => {
+            if (indexHtml === null) indexHtml = await readFile(indexPath);
+            return reply.type("text/html").send(indexHtml);
+          });
+        }
+      },
+      { prefix: mountPrefix },
+    );
+  }
+}
+
+/** Resolve the asset root relative to the manifest that declared the resource, so
+ *  the frontend ships co-located with the app (same pattern as mcp-client). */
+function resolveRoot(root: string, ctx: ResourceContext): string {
+  if (isAbsolute(root)) return root;
+  const source = ctx.moduleContext.source;
+  if (!source.startsWith("file://")) return resolve(root);
+  const baseDir = dirname(fileURLToPath(source));
+  return resolve(baseDir, root);
+}
+
+export async function create(
+  resource: HttpStaticResource,
+  ctx: ResourceContext,
+): Promise<ResourceInstance> {
+  return new HttpStatic(resource, ctx);
+}