toiljs 0.0.16 → 0.0.19

package/src/client/errors.ts

@@ -0,0 +1,11 @@
+/**
+ * Extracts a human-readable message from an unknown thrown value. Handy in `catch`
+ * blocks where the caught value is typed `unknown`. Exposed as a global `parseError`
+ * (no import) alongside the other toiljs globals.
+ *
+ * @param err - the caught value (an `Error`, a string, or anything else).
+ * @returns the `Error.message` when `err` is an `Error`, otherwise `String(err)`.
+ */
+export function parseError(err: unknown): string {
+    return err instanceof Error ? err.message : String(err);
+}

package/src/client/index.ts

@@ -87,3 +87,5 @@ export { Form } from './components/Form.js';
 export type { FormProps } from './components/Form.js';
 export { Slot } from './components/Slot.js';
 export type { SlotProps } from './components/Slot.js';
+export { Server } from './rpc.js';
+export { parseError } from './errors.js';

package/src/client/rpc.ts

@@ -0,0 +1,64 @@
+/**
+ * The client-callable server surface (`Server`). Its TYPED shape is generated by
+ * the toilscript server build into the project's `shared/server.ts`
+ * (`declare global { const Server }`); this module is the runtime behind it.
+ *
+ * Two surfaces live under `Server`:
+ *   - `Server.REST.<controller>.<route>(args)` is a WORKING fetch client. The
+ *     generated `shared/server.ts` attaches it to `globalThis.__toilRest` when
+ *     imported; the proxy below surfaces it under `Server.REST`.
+ *   - `Server.<service>.<method>()` (RPC) is not wired yet, so any call throws.
+ *     The pipeline (tags -> generated types -> proxy) is in place; only the
+ *     network dispatch is a TODO. Build the server (`npm run build:server`) to
+ *     (re)generate the typed surface.
+ */
+
+/** A recursive proxy that throws on call, used when the REST client hasn't loaded. */
+function restMissingStub(path: string): unknown {
+    const call = (): never => {
+        throw new Error(
+            `toiljs REST: ${path}() is unavailable. The generated REST client has not loaded - ` +
+                `import a type from your 'shared/server' (so the client attaches), or run 'npm run build:server'.`,
+        );
+    };
+    return new Proxy(call, {
+        get(_target, prop) {
+            if (typeof prop === 'symbol' || prop === 'then') return undefined;
+            return restMissingStub(`${path}.${String(prop)}`);
+        },
+        apply() {
+            return call();
+        },
+    });
+}
+
+/** Builds a recursive proxy that throws on call, supporting `Server.svc.method()`. */
+function rpcStub(path: string): unknown {
+    const call = (): never => {
+        throw new Error(
+            `toiljs RPC: ${path}() is not available yet. The client<->server transport ` +
+                `is not wired; this is a generated stub. Remote calls will work once transport lands.`,
+        );
+    };
+    return new Proxy(call, {
+        get(_target, prop) {
+            // Not thenable, and ignore symbol probes (e.g. from awaiting/inspection).
+            if (typeof prop === 'symbol' || prop === 'then') return undefined;
+            // `Server.REST` surfaces the generated fetch client attached by shared/server.ts.
+            if (path === 'Server' && prop === 'REST') {
+                const rest = (globalThis as { __toilRest?: unknown }).__toilRest;
+                return rest !== undefined ? rest : restMissingStub('Server.REST');
+            }
+            return rpcStub(`${path}.${prop}`);
+        },
+        apply() {
+            return call();
+        },
+    });
+}
+
+/**
+ * Runtime value for the global `Server`. Typed as `unknown` here; the real types
+ * come from the generated `shared/server.ts`. toiljs assigns this to `globalThis`.
+ */
+export const Server: unknown = rpcStub('Server');

package/src/compiler/config.ts

@@ -211,7 +211,9 @@ export async function loadConfig(
         transitions: client.transitions ?? false,
         devtools: client.devtools !== false,
         devtoolsAi:
-            typeof client.devtools === 'object' && client.devtools.ai ? client.devtools.ai : null,
+            client.devtools != null && typeof client.devtools === 'object'
+                ? (client.devtools.ai ?? null)
+                : null,
         seo: client.seo ?? null,
         runtimePath: resolveRuntimePath(),
         vite: client.vite ?? {},

package/src/compiler/docs.ts

@@ -85,14 +85,17 @@ export const TOIL_DOCS: Record<string, string> = {
         '- `client/`, the app: `routes/` (file-based), `layout.tsx`, `components/`, `styles/`,',
         '  `public/`, and `toil.tsx` (the entry that calls `Toil.mount`).',
         '- `server/`, the toilscript → WASM target (`@main` entry), compiled by `toilscript`.',
+        '  `@data`/`@remote`/`@service` here generate the typed client `Server` API (see `server.md`).',
         '- `toil.config.ts`, configuration via `defineConfig` (`toiljs.config.ts` also works).',
         '- Generated, gitignored, do not edit: `.toil/` (working dir), `toil-env.d.ts` (ambient',
-        '  globals), `toil-routes.d.ts` (typed routes).',
+        '  globals), `toil-routes.d.ts` (typed routes), `shared/server.ts` (the typed RPC module,',
+        '  emitted by the server build; import `@data` classes from `shared/server`).',
         '',
         '## Key ideas',
         '',
         '- `Toil` is a native global (no import): `Toil.Link`, `Toil.useRouter`, `Toil.useLoaderData`,',
-        '  etc. The IO classes (`BinaryWriter`, `BinaryReader`, `FastMap`, `FastSet`) are globals too.',
+        '  etc. The IO classes (`FastMap`, `FastSet`, `DataWriter`, `DataReader`), `parseError`, and the',
+        '  generated `Server` RPC surface are globals too.',
         '- Scripts: `npm run dev` (HMR), `npm run build` (→ `build/client` + `build/server`),',
         '  `npm start` (self-host the build).',
         '',
@@ -161,7 +164,14 @@ export const TOIL_DOCS: Record<string, string> = {
         '- Data: `useLoaderData` (see `routing.md`)',
         '- Head: `useHead`, `useTitle`, `<Head>`, set the `<title>` / meta per route',
         '- Realtime: `useChannel`, `connectChannel` (WebSocket to the backend at `/_toil`)',
-        '- IO globals (no `Toil.` prefix): `BinaryWriter`, `BinaryReader`, `FastMap`, `FastSet`',
+        '- IO globals (no `Toil.` prefix): `FastMap`, `FastSet`, `DataWriter`, `DataReader`',
+        '- `parseError(err)` global: message from an unknown caught value (handy in `catch`)',
+        '- `Server` global: the typed RPC surface generated from the server (see `server.md`)',
+        '- `Server.REST.<controller>.<route>(args)`: a working, typed `fetch` client for your',
+        '  `@rest` controllers, e.g. `await Server.REST.todos.getTodo({ params: { id } })` or',
+        '  `await Server.REST.todos.add({ body: new AddTodo("milk") })`. `args` is',
+        '  `{ params?, body?, query?, headers? }`; returns are typed (`@data` classes are parsed for',
+        '  you). The REST client attaches when you import from `shared/server`.',
         '',
         '## Head example',
         '',
@@ -202,9 +212,53 @@ export const TOIL_DOCS: Record<string, string> = {
         '- `server/index.ts`, your functions.',
         '- `server/tsconfig.json`, extends `toilscript/std/assembly.json` (AssemblyScript/toilscript',
         '  globals like `i32`, not the DOM), so editors resolve server types correctly.',
-        '- `npm run build:server` (or `npm run build`) emits `build/server/release.wasm`.',
+        '- `npm run build:server` (or `npm run build`) emits `build/server/release.wasm` and',
+        '  regenerates `shared/server.ts` (the typed client RPC module).',
         '',
-        'Note: the client↔server bridge (calling WASM exports from the client) is not wired yet.',
+        '## Typed RPC (`@data` / `@remote` / `@service`)',
+        '',
+        'Tag server code and the build generates a typed client `Server` surface:',
+        '',
+        '- `@data class X {}`, a serializable struct. Generates a client class with the same fields',
+        '  plus `encode`/`decode`; construct it on the client: `import { X } from "shared/server"`.',
+        '- `@remote function f(a: T): R`, a client-callable endpoint, becomes `Server.f(a)`.',
+        '- `@service class S { @remote m(...) {} }`, namespaces methods: `Server.s.m(...)`.',
+        '',
+        'On the client, `Server` is a global (no import) and fully typed; every call is async',
+        '(`Promise<R>`). Inputs/outputs are scalars, arrays, or `@data` classes, both directions.',
+        '',
+        'Note: the client↔server transport is not wired yet, so calling a `Server` method throws',
+        'until it lands; the typed surface + codec are generated and ready.',
+        '',
+        '## HTTP REST (`@rest` / `@route`)',
+        '',
+        'Tag a class `@rest` and its methods with a verb to expose a real HTTP API. Unlike RPC,',
+        'the generated client is working `fetch` code (it is just HTTP).',
+        '',
+        '- `@rest("api") class Todos {}`, mounts the controller at `/api` (bare `@rest` → `/`).',
+        '- `@get("/todos/:id")` / `@post` / `@put` / `@del` / `@patch` / `@head` / `@options`, verb',
+        '  shortcuts; or `@route({ method: Methods.GET, path: "/todos", stream: DataStream.JSON })`.',
+        '- A method takes an optional `@data` body + an optional `ctx: RouteContext` (path params via',
+        '  `ctx.param("id")`, `ctx.query(...)`, `ctx.header(...)`), and returns a `@data` type (encoded',
+        '  per `stream`) or a `Response` (sent verbatim). `stream` is `DataStream.JSON` (default) or',
+        '  `DataStream.Binary` (lossless for large `u64`/bignum).',
+        '',
+        'Each `@rest` class self-registers; dispatch them from your handler - it composes, it never',
+        'takes over `handle()`:',
+        '',
+        '```ts',
+        'import { ToilHandler, Request, Response, Rest } from "toiljs/server/runtime";',
+        'export class App extends ToilHandler {',
+        '    public handle(req: Request): Response {',
+        '        const hit = Rest.dispatch(req); // try every @rest controller',
+        '        if (hit != null) return hit;',
+        '        return Response.notFound();     // your own logic / static fallback',
+        '    }',
+        '}',
+        '```',
+        '',
+        'For a REST-only project, `Server.handler = () => new RestHandler()` does the same with no',
+        'boilerplate. On the client: `Server.REST.todos.getTodo({ params: { id } })` (see client.md).',
     ]),
     'cli.md': doc([
         '# CLI',
@@ -215,6 +269,9 @@ export const TOIL_DOCS: Record<string, string> = {
         '- `toiljs build`, production build → `build/client` (chain `toilscript` for the server).',
         '- `toiljs start`, self-host the built app (hyper-express) with a `/_toil` WebSocket channel.',
         '- `toiljs configure`, toggle styling features on an existing project (see `styling.md`).',
+        '- `toiljs doctor`, diagnose project setup (`--json` for CI). `--fix` auto-wires the typed-RPC',
+        '  setup (build scripts, tsconfig `shared` + alias, `.gitignore`, toilscript version, and the',
+        '  toilscript prettier plugin) so an existing project upgrades in one command.',
     ]),
 };
 

package/src/compiler/generate.ts

@@ -8,7 +8,7 @@ import { scanRoutes, type ScannedRoute } from './routes.js';
 import { llmsTxt, robotsTxt, sitemapXml } from './seo.js';
 
 /**
- * Contents of the root `toil-env.d.ts`: ambient global types so `new BinaryWriter()` etc. resolve
+ * Contents of the root `toil-env.d.ts`: ambient global types so `new DataWriter()` etc. resolve
  * in the IDE without an import. Script-mode declaration (no top-level import/export → the
  * `declare const`s are truly global, and it's not a module that could confuse ESLint's project
  * service); the inline `import('toiljs/io')` type only needs the normal `toiljs/io` export.
@@ -55,10 +55,11 @@ export const TOIL_ENV_DTS =
     `    type PageMeta = import('toiljs/client').PageMeta;\n` +
     `    type SearchHints = import('toiljs/client').SearchHints;\n` +
     `}\n` +
-    `declare const BinaryWriter: typeof import('toiljs/io').BinaryWriter;\n` +
-    `declare const BinaryReader: typeof import('toiljs/io').BinaryReader;\n` +
     `declare const FastMap: typeof import('toiljs/io').FastMap;\n` +
     `declare const FastSet: typeof import('toiljs/io').FastSet;\n` +
+    `declare const DataWriter: typeof import('toiljs/io').DataWriter;\n` +
+    `declare const DataReader: typeof import('toiljs/io').DataReader;\n` +
+    `declare const parseError: typeof import('toiljs/client').parseError;\n` +
     `\n` +
     `${STYLE_MODULES}\n` +
     `\n` +
@@ -290,9 +291,9 @@ export function generate(cfg: ResolvedToilConfig): ScannedRoute[] {
         `// @ts-nocheck\n` +
         `// AUTO-GENERATED by toil, do not edit.\n` +
         `import * as Toil from 'toiljs/client';\n` +
-        `import { BinaryWriter, BinaryReader, FastMap, FastSet } from 'toiljs/io';\n` +
+        `import { FastMap, FastSet, DataWriter, DataReader } from 'toiljs/io';\n` +
         `import { pages } from './routes';\n\n` +
-        `Object.assign(globalThis, { Toil, BinaryWriter, BinaryReader, FastMap, FastSet });\n` +
+        `Object.assign(globalThis, { Toil, FastMap, FastSet, DataWriter, DataReader, Server: Toil.Server, parseError: Toil.parseError });\n` +
         `Toil.setViewTransitions(${String(cfg.viewTransitions)});\n` +
         `Toil.setTransitions(${String(cfg.transitions)});\n` +
         `Toil.registerPages(pages);\n`;

package/src/compiler/index.ts

@@ -12,6 +12,8 @@ import { createViteConfig } from './vite.js';
 export interface ToilCommandOptions {
     readonly root?: string;
     readonly port?: number;
+    /** Bind host for `start`. Defaults to loopback (`127.0.0.1`); pass `0.0.0.0` to expose. */
+    readonly host?: string;
 }
 
 /** Starts the Vite dev server (HMR + transforms) for the client app. Returns the running server. */
@@ -44,7 +46,7 @@ export async function start(opts: ToilCommandOptions = {}): Promise<RunningBacke
     if (!fs.existsSync(path.join(outDir, 'index.html'))) {
         throw new Error(`No build found in ${outDir}. Run \`toiljs build\` first.`);
     }
-    return startBackend({ root: outDir, port: cfg.port });
+    return startBackend({ root: outDir, port: cfg.port, host: opts.host });
 }
 
 export { defineConfig, loadConfig, AiProvider } from './config.js';

package/src/compiler/plugin.ts

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process';
 import fs from 'node:fs';
+import { type IncomingMessage } from 'node:http';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -102,6 +103,37 @@ function devInfo(cfg: ResolvedToilConfig, port: number): Record<string, unknown>
     };
 }
 
+/**
+ * Resolves a request's `file` param to an absolute path that is genuinely inside the project root,
+ * or null. Guards against `..` traversal, sibling-prefix escapes (`<root>-evil/secret` passes a bare
+ * `startsWith(root)`), and symlinks inside the project that point outside it (realpath re-check).
+ */
+function safeProjectPath(cfg: ResolvedToilConfig, file: string | null): string | null {
+    if (!file) return null;
+    const root = cfg.root;
+    const inside = (p: string): boolean => p === root || p.startsWith(root + path.sep);
+    const abs = path.resolve(file);
+    if (!inside(abs) || !fs.existsSync(abs)) return null;
+    try {
+        const real = fs.realpathSync(abs);
+        return inside(real) ? real : null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * True for requests that must NOT reach the dev endpoints (they open files, read source, and spend
+ * AI credits). Uses an allowlist on the browser-set `Sec-Fetch-Site`: only `same-origin` (the
+ * toolbar), `none` (user-initiated, e.g. the address bar), or an absent header (non-browser tooling
+ * like curl) are allowed. Everything else, `cross-site`, `same-site`, or any unexpected value, is
+ * rejected. This blocks CSRF (a malicious site's fetch/img) without breaking local dev tooling.
+ */
+function isCrossSiteRequest(headers: IncomingMessage['headers']): boolean {
+    const site = headers['sec-fetch-site'];
+    return site !== undefined && site !== 'same-origin' && site !== 'none';
+}
+
 /** Opens `file` in the user's editor (best-effort): `$EDITOR file`, else `code -g file`. */
 function openInEditor(file: string): void {
     try {
@@ -150,7 +182,12 @@ export function toilPlugin(cfg: ResolvedToilConfig): Plugin {
         configureServer(server) {
             // Dev toolbar endpoints (dev only). `/__toil/devinfo` -> build/config snapshot;
             // `/__toil/open?file=` -> open the file in the editor.
-            server.middlewares.use('/__toil/devinfo', (_req, res) => {
+            server.middlewares.use('/__toil/devinfo', (req, res) => {
+                if (isCrossSiteRequest(req.headers)) {
+                    res.statusCode = 403;
+                    res.end();
+                    return;
+                }
                 const port = server.config.server.port ?? cfg.port;
                 res.setHeader('content-type', 'application/json');
                 res.end(JSON.stringify(devInfo(cfg, port)));
@@ -158,6 +195,11 @@ export function toilPlugin(cfg: ResolvedToilConfig): Plugin {
             // `/__toil/ai` -> server-side AI proxy. The key is read from the env here and never
             // reaches the browser; 404 when AI isn't configured (the toolbar then only hands off).
             server.middlewares.use('/__toil/ai', (req, res) => {
+                if (isCrossSiteRequest(req.headers)) {
+                    res.statusCode = 403;
+                    res.end();
+                    return;
+                }
                 if (req.method !== 'POST') {
                     res.statusCode = 405;
                     res.end();
@@ -170,31 +212,52 @@ export function toilPlugin(cfg: ResolvedToilConfig): Plugin {
                     return;
                 }
                 let body = '';
-                req.on('data', (chunk) => (body += String(chunk)));
+                let aborted = false;
+                req.on('data', (chunk) => {
+                    if (aborted) return;
+                    body += String(chunk);
+                    if (body.length > 100_000) {
+                        // Cap the request body so a runaway/malicious POST can't grow it unbounded.
+                        aborted = true;
+                        res.statusCode = 413;
+                        res.end();
+                        req.destroy();
+                    }
+                });
                 req.on('end', () => {
+                    if (aborted) return;
                     void (async () => {
                         try {
-                            const { prompt } = JSON.parse(body || '{}') as { prompt?: string };
-                            const text = await aiComplete(ai, prompt ?? '');
+                            const parsed = JSON.parse(body || '{}') as { prompt?: string };
+                            // Cap the prompt actually forwarded upstream (independent of the raw-body cap).
+                            const prompt =
+                                typeof parsed.prompt === 'string' ? parsed.prompt.slice(0, 16000) : '';
+                            const text = await aiComplete(ai, prompt);
                             res.setHeader('content-type', 'application/json');
                             res.end(JSON.stringify({ text }));
                         } catch (e) {
+                            // Log the detail to the dev's terminal; return a generic message to the
+                            // client so upstream/provider error text is never reflected over HTTP.
+                            process.stderr.write(
+                                `toil: /__toil/ai failed: ${e instanceof Error ? e.message : String(e)}\n`,
+                            );
                             res.statusCode = 500;
                             res.setHeader('content-type', 'application/json');
-                            res.end(
-                                JSON.stringify({ error: e instanceof Error ? e.message : String(e) }),
-                            );
+                            res.end(JSON.stringify({ error: 'AI request failed (see dev server logs).' }));
                         }
                     })();
                 });
             });
             server.middlewares.use('/__toil/open', (req, res) => {
                 try {
+                    if (isCrossSiteRequest(req.headers)) {
+                        res.statusCode = 403;
+                        res.end();
+                        return;
+                    }
                     const url = new URL(req.url ?? '', 'http://localhost');
-                    const file = url.searchParams.get('file');
-                    const abs = file ? path.resolve(file) : '';
-                    // Only files inside the project root, never an arbitrary path.
-                    if (abs && abs.startsWith(cfg.root) && fs.existsSync(abs)) openInEditor(abs);
+                    const abs = safeProjectPath(cfg, url.searchParams.get('file'));
+                    if (abs) openInEditor(abs);
                     res.statusCode = 204;
                     res.end();
                 } catch {
@@ -202,6 +265,31 @@ export function toilPlugin(cfg: ResolvedToilConfig): Plugin {
                     res.end();
                 }
             });
+            // `/__toil/source?file=` -> the file's text, so the AI tab can include the page's code in
+            // its prompt. Same root-confinement (`safeProjectPath`) as `/__toil/open`; capped so a
+            // stray huge file can't bloat the response.
+            server.middlewares.use('/__toil/source', (req, res) => {
+                try {
+                    if (isCrossSiteRequest(req.headers)) {
+                        res.statusCode = 403;
+                        res.end();
+                        return;
+                    }
+                    const url = new URL(req.url ?? '', 'http://localhost');
+                    const abs = safeProjectPath(cfg, url.searchParams.get('file'));
+                    if (!abs) {
+                        res.statusCode = 404;
+                        res.end();
+                        return;
+                    }
+                    const text = fs.readFileSync(abs, 'utf8').slice(0, 20000);
+                    res.setHeader('content-type', 'text/plain; charset=utf-8');
+                    res.end(text);
+                } catch {
+                    res.statusCode = 400;
+                    res.end();
+                }
+            });
 
             // Trailing slash so a sibling like `routes-extra/` doesn't match the `routes/` prefix.
             const routesPrefix = cfg.routesAbsDir.replace(/\\/g, '/').replace(/\/?$/, '/');

package/src/compiler/seo.ts

@@ -135,6 +135,22 @@ function escapeAttr(value: string): string {
 export function escapeHtml(value: string): string {
     return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
+/**
+ * Neutralizes a string for safe single-line Markdown interpolation (e.g. `llms.txt`): collapses
+ * newlines/control chars to a space and backslash-escapes the characters that would break out of a
+ * `[text](url)` link or start a new block (`[ ] ( ) < > \``). Without this, a page title/description
+ * from `generateMetadata` could inject extra list items, links, or headings.
+ */
+function escapeMarkdownInline(value: string): string {
+    return value
+        .replace(/[\r\n\t\f\v]+/g, ' ')
+        .replace(/[\\[\]()<>`]/g, (c) => `\\${c}`)
+        .trim();
+}
+/** Escapes a URL for a Markdown link target: strips whitespace/control chars and parens. */
+function escapeMarkdownUrl(value: string): string {
+    return value.replace(/\s+/g, '').replace(/[()<>]/g, encodeURIComponent);
+}
 /**
  * Serializes a value for embedding in an inline `<script>` (JSON-LD). Escapes `<`, `>`, and `&`,
  * which neutralizes `</script>` and `<!--` (the only HTML-significant sequences inside a script),
@@ -388,9 +404,13 @@ export function llmsTxt(
     if (resolvedPages.length) {
         out.push('\n## Pages\n');
         for (const page of resolvedPages) {
-            out.push(
-                `- [${page.title}](${page.url})${page.description !== undefined ? `: ${page.description}` : ''}`,
-            );
+            const title = escapeMarkdownInline(page.title);
+            const url = escapeMarkdownUrl(page.url);
+            const desc =
+                page.description !== undefined
+                    ? `: ${escapeMarkdownInline(page.description)}`
+                    : '';
+            out.push(`- [${title}](${url})${desc}`);
         }
     }
     return out.join('\n') + '\n';

package/src/compiler/ssg.ts

@@ -98,6 +98,16 @@ export async function prerenderStaticParams(cfg: ResolvedToilConfig): Promise<st
             const paramSets = await mod.generateStaticParams();
             for (const params of paramSets) {
                 const url = fillPattern(route.pattern, params);
+                // Containment guard: a param value with `..`/separators could make `url` resolve the
+                // output path outside `outDir`. Resolve the target up front and skip anything that
+                // escapes, so a (possibly externally-derived) param can't clobber files elsewhere.
+                const target = path.join(outDir, url.replace(/^\//, ''), 'index.html');
+                const outRoot = path.resolve(outDir);
+                const absTarget = path.resolve(target);
+                if (absTarget !== outRoot && !absTarget.startsWith(outRoot + path.sep)) {
+                    warn(`skipped ${route.pattern}: params escape outDir (${url})`);
+                    continue;
+                }
                 let metadata: Record<string, unknown> | null = null;
                 try {
                     if (typeof mod.generateMetadata === 'function') {
@@ -114,7 +124,6 @@ export async function prerenderStaticParams(cfg: ResolvedToilConfig): Promise<st
                     warn(`metadata failed for ${url} (${err instanceof Error ? err.message : String(err)})`);
                 }
                 const html = injectSeoHtml(shell, routeSeo(cfg.seo, metadata, url));
-                const target = path.join(outDir, url.replace(/^\//, ''), 'index.html');
                 fs.mkdirSync(path.dirname(target), { recursive: true });
                 fs.writeFileSync(target, html);
                 generated.push(url);

package/src/compiler/vite.ts

@@ -1,3 +1,4 @@
+import fs from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -41,6 +42,36 @@ const IMAGE_EXT = /^(png|jpe?g|svg|gif|tiff|bmp|ico|webp|avif)$/i;
 /** Font extensions routed to `fonts/`. */
 const FONT_EXT = /^(woff|woff2|eot|ttf|otf)$/i;
 
+/**
+ * Resolves bare `shared/*` imports to the project's `shared/` folder (replacing a plain alias so it
+ * can run early), and fails `shared/server` with an actionable message when the module has not been
+ * generated yet (it comes from the server build, which must run first), instead of Vite's opaque
+ * `UNLOADABLE_DEPENDENCY`.
+ */
+function sharedResolverPlugin(cfg: ResolvedToilConfig): PluginOption {
+    const sharedDir = path.join(cfg.root, 'shared');
+    return {
+        name: 'toiljs:shared-resolver',
+        enforce: 'pre',
+        resolveId(source: string) {
+            if (source !== 'shared' && !source.startsWith('shared/')) return null;
+            const rel = source === 'shared' ? 'index' : source.slice('shared/'.length);
+            for (const ext of ['', '.ts', '.tsx', '.js', '.jsx', '.mjs']) {
+                const candidate = path.join(sharedDir, rel + ext);
+                if (fs.existsSync(candidate)) return candidate;
+            }
+            if (source === 'shared/server') {
+                throw new Error(
+                    'toiljs: "shared/server" is generated by the server build but is missing. ' +
+                        'Run the server build first (it emits shared/server.ts from your @data/@remote code): ' +
+                        '`npm run build:server`  (toilscript --target release --rpcModule shared/server.ts).',
+                );
+            }
+            return null;
+        },
+    };
+}
+
 /** Routes a built asset to a typed sub-folder (`images/`, `fonts/`, `css/`, else `assets/`). */
 function assetFileName(name: string): string {
     const ext = name.split('.').pop() ?? '';
@@ -116,12 +147,15 @@ export async function createViteConfig(cfg: ResolvedToilConfig): Promise<InlineC
             cfg.fonts ? fontPreloadPlugin(cfg) : undefined,
             nodePolyfills({ globals: { Buffer: true, global: true, process: true } }),
             react(),
+            sharedResolverPlugin(cfg),
             toilPlugin(cfg),
         ],
         resolve: {
             alias: {
                 'toiljs/client': cfg.runtimePath,
                 'toiljs/routes': path.join(cfg.toilDir, 'routes.ts'),
+                // `shared/*` is resolved by sharedResolverPlugin (above) so a missing generated
+                // shared/server.ts gives an actionable error instead of an opaque load failure.
                 ...polyfillShimAliases,
             },
             dedupe: ['react', 'react-dom'],