toiljs 0.0.48 → 0.0.50

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "toiljs",
     "type": "module",
-    "version": "0.0.48",
+    "version": "0.0.50",
     "author": "Dacely",
     "description": "The modern React framework: a file-based React frontend and a ToilScript-compiled WebAssembly backend.",
     "repository": {
@@ -130,7 +130,7 @@
         "nodemailer": "^9.0.0",
         "picocolors": "^1.1.1",
         "sharp": "^0.35.0",
-        "toilscript": "^0.1.26",
+        "toilscript": "^0.1.27",
         "typescript-eslint": "^8.60.0",
         "vite": "^8.0.14",
         "vite-imagetools": "^10.0.0",

package/src/cli/create.ts

@@ -114,7 +114,7 @@ function scaffold(
         '@types/react-dom': '^19.2.3',
         eslint: '^10.2.0',
         prettier: '^3.8.1',
-        toilscript: '^0.1.26',
+        toilscript: '^0.1.27',
         typescript: '^6.0.3',
     };
     for (const dep of requiredPackages(features).sort()) {
@@ -302,7 +302,6 @@ declare enum EmailStatus { Sent, Disabled, Budget, RecipientCapped, Deduped, Try
 declare namespace EmailService { function send(to: string, subject: string, body: string, purpose?: string, html?: string): EmailStatus; }
 declare class RenderedEmail { subject: string; body: string; html: string; constructor(subject: string, body: string, html: string); }
 declare class EmailTemplate { constructor(subject: string, body: string, html?: string); render(vars: Map<string, string>): RenderedEmail; send(to: string, vars: Map<string, string>, purpose?: string): EmailStatus; }
-declare enum RateLimit { FixedWindow, SlidingWindow, TokenBucket }
 declare namespace RateLimitService { function guard(routeId: i32, strategy: i32, limit: i32, window: i32): import('toiljs/server/runtime/response').Response | null; function guardKeyed(routeId: i32, strategy: i32, limit: i32, window: i32, key: string): import('toiljs/server/runtime/response').Response | null; }
 declare namespace Environment { function get(key: string): string | null; function getSecure(key: string): string | null; }
 declare class TwoFactorIssue { code: string; token: string; constructor(code: string, token: string); }

package/src/cli/diagnostics.ts

@@ -402,8 +402,8 @@ export function checkWasmBuilt(exists: boolean): Check {
 
 // --- Typed RPC (@data / @remote / @service) -------------------------------------------------------
 
-/** Minimum toilscript: @rest/@route HTTP layer + RPC codegen + hardened decoders + correct @data editor decls (TS2395 fix). */
-export const RPC_TOILSCRIPT_MIN = '0.1.26';
+/** Minimum toilscript: @rest/@route + RPC codegen + hardened decoders + @data editor decls (TS2395 fix) + RateLimit-enum @ratelimit typing. */
+export const RPC_TOILSCRIPT_MIN = '0.1.27';
 
 /** Whether each piece of the typed-RPC wiring is in place (computed in `doctor.ts`). */
 export interface RpcFacts {

package/src/cli/proc.ts

@@ -6,12 +6,18 @@ import { spawn } from 'node:child_process';
  * `shell: true` is deprecated (DEP0190), so the whole command is passed as one string there
  * (args are fixed/allowlisted, never raw user input). POSIX spawns directly.
  */
-export function run(cmd: string, args: string[], cwd: string): Promise<void> {
+export function run(
+    cmd: string,
+    args: string[],
+    cwd: string,
+    opts: { stdio?: 'ignore' | 'inherit' } = {},
+): Promise<void> {
     return new Promise((resolve, reject) => {
         const onWindows = process.platform === 'win32';
+        const stdio = opts.stdio ?? 'ignore';
         const child = onWindows
-            ? spawn([cmd, ...args].join(' '), { cwd, stdio: 'ignore', shell: true })
-            : spawn(cmd, args, { cwd, stdio: 'ignore' });
+            ? spawn([cmd, ...args].join(' '), { cwd, stdio, shell: true })
+            : spawn(cmd, args, { cwd, stdio });
         child.on('error', reject);
         child.on('close', (code) =>
             code === 0 ? resolve() : reject(new Error(`${cmd} exited with code ${String(code)}`)),

package/src/cli/ui.ts

@@ -134,7 +134,6 @@ export function box(lines: readonly string[], paint: (s: string) => string = (s)
  * first full-stack framework for a globally distributed application delivery network.
  */
 const TAGLINES: ReadonlyArray<(a: (s: string) => string) => string> = [
-    (a) => `the most performant ${a('react')} framework`,
     (a) => `bringing ${a('hyper scale')} to anyone`,
     (a) => `the first full-stack ${a('application delivery network')}`,
     (a) => `your app, ${a('globally distributed')} by default`,

package/src/cli/update.ts

@@ -140,9 +140,22 @@ export async function runUpdate(opts: UpdateOptions): Promise<void> {
     await run('npx', ncuArgs(applyAll ? ['-u'] : ['-u', '--filter', selected.join(' ')]), root);
     s.stop('package.json updated');
 
-    s.start(`Installing with ${pm.name}`);
-    await run(pm.name, ['install'], root);
-    s.stop('Dependencies installed');
+    // Run the install with VISIBLE output (so a failure is diagnosable — npm
+    // prints the real error) and handle a non-zero exit gracefully, instead of
+    // leaving the spinner spinning forever on a failed install.
+    note(dim(`Running ${pm.name} install…`), 'Install');
+    try {
+        await run(pm.name, ['install'], root, { stdio: 'inherit' });
+    } catch {
+        outro(
+            danger(
+                `${pm.name} install failed — package.json was updated to the new versions, but the ` +
+                    `install did not finish. Fix the error printed above, then run \`${pm.name} install\`.`,
+            ),
+        );
+        process.exitCode = 1;
+        return;
+    }
 
     outro(
         success(`Updated ${String(selected.length)} package${selected.length === 1 ? '' : 's'}.`),

package/src/client/head/head.ts

@@ -25,7 +25,7 @@ export interface LinkTag {
 export interface HeadSpec {
     /** Document title. */
     readonly title?: string;
-    /** Template applied to a child's title, `%s` = the title (e.g. `'%s · toiljs'`). */
+    /** Template applied to a child's title, `%s` = the title (e.g. `'%s, toiljs'`). */
     readonly titleTemplate?: string;
     readonly meta?: readonly MetaTag[];
     readonly link?: readonly LinkTag[];

package/src/client/head/metadata.ts

@@ -21,7 +21,7 @@ export interface OpenGraph {
 export interface Metadata {
     /** Document title. */
     readonly title?: string;
-    /** Template applied to the title (`%s` = the title), e.g. `'%s · toiljs'`. */
+    /** Template applied to the title (`%s` = the title), e.g. `'%s, toiljs'`. */
     readonly titleTemplate?: string;
     /** `<meta name="description">`. */
     readonly description?: string;

package/src/compiler/docs.ts

@@ -8,7 +8,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 /** Shared body for the per-tool pointer files. */
-const POINTER_BODY = `# toiljs · AI assistant guide
+const POINTER_BODY = `# toiljs, AI assistant guide
 
 This is a **toiljs** project, a full-stack React framework (React + Vite client, file-based
 routing, and a toilscript→WebAssembly server).
@@ -183,7 +183,7 @@ export const TOIL_DOCS: Record<string, string> = {
         '',
         '    Toil.useHead({',
         '        title: "Blog",',
-        '        titleTemplate: "%s · MyApp",',
+        '        titleTemplate: "%s, MyApp",',
         '        meta: [{ name: "description", content: "..." }],',
         '    });',
     ]),

package/src/compiler/email-preview.ts

@@ -120,7 +120,7 @@ export function previewShellHtml(): string {
 <head>
 <meta charset="utf-8" />
 <meta name="viewport" content="width=device-width, initial-scale=1" />
-<title>Email preview · toiljs</title>
+<title>Email preview, toiljs</title>
 <style>
   /* Matches the toiljs demo brand (examples/basic/client/styles/main.css). */
   :root {
@@ -213,7 +213,9 @@ export function previewShellHtml(): string {
     subjectEl.textContent = fill(rendered.subject);
     if (format === 'html') {
       frame.hidden = false; textEl.hidden = true;
-      frame.srcdoc = fill(rendered.html);
+      // Wrap the email FRAGMENT in a minimal dark document so the iframe doesn't
+      // show the browser-default white body/margin around and below the email.
+      frame.srcdoc = '<!doctype html><meta charset="utf-8"><style>html,body{margin:0;padding:0;background:#080d11}</style>' + fill(rendered.html);
     } else {
       frame.hidden = true; textEl.hidden = false;
       textEl.textContent = fill(rendered.text);

package/src/compiler/generate.ts

@@ -115,7 +115,8 @@ export const TOIL_SERVER_ENV_DTS =
     `declare namespace EmailService { function send(to: string, subject: string, body: string, purpose?: string, html?: string): EmailStatus; }\n` +
     `declare class RenderedEmail { subject: string; body: string; html: string; constructor(subject: string, body: string, html: string); }\n` +
     `declare class EmailTemplate { constructor(subject: string, body: string, html?: string); render(vars: Map<string, string>): RenderedEmail; send(to: string, vars: Map<string, string>, purpose?: string): EmailStatus; }\n` +
-    `declare enum RateLimit { FixedWindow, SlidingWindow, TokenBucket }\n` +
+    // `RateLimit` (the @ratelimit strategy enum) is declared by toilscript's std d.ts,
+    // which owns the @ratelimit decorator; declaring it here too would collide.
     `declare namespace RateLimitService { function guard(routeId: i32, strategy: i32, limit: i32, window: i32): import('toiljs/server/runtime/response').Response | null; function guardKeyed(routeId: i32, strategy: i32, limit: i32, window: i32, key: string): import('toiljs/server/runtime/response').Response | null; }\n` +
     `declare namespace Environment { function get(key: string): string | null; function getSecure(key: string): string | null; }\n` +
     `declare class TwoFactorIssue { code: string; token: string; constructor(code: string, token: string); }\n` +

package/src/compiler/index.ts

@@ -220,6 +220,14 @@ function watchServer(cfg: ResolvedToilConfig, watcher: ViteDevServer['watcher'])
         dirs.some((dir) => file === dir || file.startsWith(dir + path.sep));
     const isEmailSource = (file: string): boolean =>
         /\.(tsx|jsx)$/.test(file) && (file === emailsDir || file.startsWith(emailsDir + path.sep));
+    // A transient watch error must NOT crash the dev server: an unhandled 'error'
+    // on the chokidar watcher takes down the whole process. Windows throws EBUSY /
+    // EPERM when a file is momentarily locked (an editor save, a formatter, our own
+    // rebuild, a just-written file). Swallow it — the next change still fires.
+    watcher.on('error', (err: unknown) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stdout.write(pc.yellow('  ! ') + pc.dim(`file watcher: ${msg}`) + '\n');
+    });
     watcher.add([...dirs, emailsDir]);
     watcher.on('all', (_event, file) => {
         if (!isServerSource(file) && !isEmailSource(file)) return;
@@ -237,12 +245,22 @@ function watchServer(cfg: ResolvedToilConfig, watcher: ViteDevServer['watcher'])
  * close the servers, and force-exit after a short grace period no matter what.
  */
 function installDevShutdown(close: () => Promise<void> | void): void {
+    // Final, SYNCHRONOUS cursor + style restore — `exit` runs no matter how we go
+    // (signal, throw, normal), so the terminal can't be left without a cursor.
+    const restoreTerminal = (): void => {
+        try {
+            process.stdout.write('\x1b[0m\x1b[?25h');
+        } catch {
+            /* stream already closed */
+        }
+    };
+    process.on('exit', restoreTerminal);
+
     let closing = false;
     const shutdown = (): void => {
         if (closing) return;
         closing = true;
-        // Restore the cursor (anything that hid it leaves the terminal odd on exit).
-        process.stdout.write('\x1b[?25h');
+        restoreTerminal();
         process.stdout.write(pc.dim('\n  shutting down dev server…') + '\n');
         // Force-exit even if a server hangs on close (the orphan-prevention).
         const hard = setTimeout(() => process.exit(0), 1500);

package/src/compiler/vite.ts

@@ -3,10 +3,11 @@ import { createRequire } from 'node:module';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 
+import pc from 'picocolors';
 import react from '@vitejs/plugin-react';
 import { imagetools } from 'vite-imagetools';
 import { nodePolyfills } from 'vite-plugin-node-polyfills';
-import { mergeConfig, type InlineConfig, type PluginOption } from 'vite';
+import { createLogger, mergeConfig, type InlineConfig, type Logger, type PluginOption } from 'vite';
 
 import { type ResolvedToilConfig } from './config.js';
 import { fontPreloadPlugin } from './fonts.js';
@@ -120,6 +121,24 @@ function manualChunks(id: string): string | undefined {
  * splitting and tuned build options, is applied here; `toiljs/client` is aliased to the
  * runtime, and the user's `client.vite` overrides deep-merge on top.
  */
+/**
+ * Vite's `(ssr)` environment label is dark blue — nearly invisible on a black
+ * terminal. Wrap the default logger to recolor `(ssr)` magenta (purple) and
+ * `(client)` cyan, so the dev reload logs are readable.
+ */
+function brandedLogger(): Logger {
+    const logger = createLogger();
+    const recolor = (msg: string): string =>
+        msg
+            .replace(/(?:\[[0-9;]*m)*\(ssr\)(?:\[[0-9;]*m)*/g, pc.magenta('(ssr)'))
+            .replace(/(?:\[[0-9;]*m)*\(client\)(?:\[[0-9;]*m)*/g, pc.cyan('(client)'));
+    const info = logger.info.bind(logger);
+    const warn = logger.warn.bind(logger);
+    logger.info = (msg, opts) => info(recolor(msg), opts);
+    logger.warn = (msg, opts) => warn(recolor(msg), opts);
+    return logger;
+}
+
 export async function createViteConfig(cfg: ResolvedToilConfig): Promise<InlineConfig> {
     const frameworkRoot = path.resolve(path.dirname(cfg.runtimePath), '..', '..');
     const tailwind = await tailwindPlugin(cfg.root);
@@ -128,6 +147,7 @@ export async function createViteConfig(cfg: ResolvedToilConfig): Promise<InlineC
         root: cfg.toilDir,
         base: cfg.base,
         configFile: false,
+        customLogger: brandedLogger(),
         plugins: [
             tailwind,
             // Build-time image resize/optimization. Every *imported* raster image is compressed to