toiljs 0.0.80 → 0.0.82

package/build/devserver/production.js

@@ -8,7 +8,7 @@ import pc from 'picocolors';
 import { startDaemonRuntime } from './daemon/runtime.js';
 import { configureDbPersistence } from './db/index.js';
 import { initEmailService } from './email/index.js';
-import { assembleRouteSsr, dispatchEnvelopeRequest, installRuntimeErrorHandler, isDispatchableMethod, prepareSsrResponse, prepareWasmResponse, resolveStaticFile, runtimeServerOptions, toEnvelopeRequest, } from './http/runtime.js';
+import { assembleRouteSsr, dispatchEnvelopeRequest, installRuntimeErrorHandler, isDispatchableMethod, prepareSsrResponse, prepareWasmResponse, resolveDynamicFile, resolveStaticFile, runtimeServerOptions, toEnvelopeRequest, } from './http/runtime.js';
 import { decodeBody, encodeBody, isWorkerToPrimaryMessage, } from './production-ipc.js';
 import { WasmServerModule } from './runtime/module.js';
 import { buildSsrRoutes, pathnameOf } from './ssr.js';
@@ -297,7 +297,8 @@ async function startBuiltHttpServer(options, paths, dynamicHandler, runtimeOptio
             return;
         if (request.method === 'GET' || request.method === 'HEAD') {
             const routeHtml = resolveStaticFile(paths.staticRoot, `${request.path}/index.html`);
-            response.sendFile(routeHtml ?? paths.indexHtml);
+            const dynHtml = routeHtml === null ? resolveDynamicFile(paths.staticRoot, request.path) : null;
+            response.sendFile(routeHtml ?? dynHtml ?? paths.indexHtml);
             return;
         }
         response.status(404).send('not found\n');

package/examples/basic/client/routes/test.tsx

@@ -1,7 +1,12 @@
+import cube from '../assets/cube.webp?toil';
+
 export default function TestPage() {
     return (
         <div className="test-page">
             <img src="/images/test_image.webp" alt="Test" className="test-page-image" />
+            {/* A `?toil` import auto-generates a blurred LQIP + dimensions; placeholder="blur" fades
+                the real image in over it, and the aspect-ratio reserves space (no layout shift). */}
+            <Toil.Image src={cube} alt="Cube" placeholder="blur" />
         </div>
     );
 }

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "toiljs",
     "type": "module",
-    "version": "0.0.80",
+    "version": "0.0.82",
     "author": "Dacely",
     "description": "The modern React framework: a file-based React frontend and a ToilScript-compiled WebAssembly backend.",
     "repository": {

package/src/client/components/Image.tsx

@@ -5,11 +5,21 @@ import { type ComponentPropsWithRef, type CSSProperties, type ReactNode, useStat
  * `src` and `alt` are required (`alt` is enforced for accessibility, pass `alt=""` for decorative
  * images). `width`/`height` (or `fill`) reserve space to prevent layout shift.
  */
+/** A toil image source carrying an auto-generated blur LQIP + intrinsic size, produced by importing an
+ * image with the `?toil` flag (`import hero from './hero.webp?toil'`). Pass it straight to `Image`. */
+export interface ToilImageSource {
+    src: string;
+    width?: number;
+    height?: number;
+    blurDataURL?: string;
+}
+
 export interface ImageProps extends Omit<
     ComponentPropsWithRef<'img'>,
-    'loading' | 'placeholder' | 'width' | 'height'
+    'loading' | 'placeholder' | 'width' | 'height' | 'src'
 > {
-    src: string;
+    /** The image URL, or a `?toil` import object that auto-fills the blur placeholder + aspect-ratio. */
+    src: string | ToilImageSource;
     alt: string;
     /** Intrinsic width in px. Set together with `height` to reserve space (avoids layout shift). */
     width?: number;
@@ -31,12 +41,17 @@ export interface ImageProps extends Omit<
      */
     priority?: boolean;
     /**
-     * Placeholder shown until the image loads: `'empty'` (default) or `'blur'`. `'blur'` needs
-     * `blurDataURL` AND a reserved size (`width`+`height`, or `fill`) — without a box there's nothing
-     * to paint it in. Layout shift is prevented by the reserved size, not by the placeholder.
+     * Placeholder shown until the image loads: `'empty'` (default) or `'blur'`. `'blur'` paints the
+     * `blurDataURL` (auto-filled from a `?toil` import, or passed) blurred, or a neutral skeleton
+     * shimmer if there's none. It needs a reserved size (`width`+`height`, or `fill`) to paint into —
+     * which also prevents layout shift (the placeholder is cosmetic; the reserved size is what holds).
      */
     placeholder?: 'empty' | 'blur';
-    /** A tiny (base64) image shown blurred behind the image while it loads, when `placeholder="blur"`. */
+    /**
+     * A tiny base64 image shown blurred while the real image loads (with `placeholder="blur"`).
+     * Auto-generated when you import via `?toil` (`import hero from './hero.webp?toil'`); pass it
+     * explicitly only for a string `src`. Omit it to fall back to a neutral skeleton shimmer.
+     */
     blurDataURL?: string;
 }
 
@@ -48,36 +63,58 @@ export interface ImageProps extends Omit<
  */
 export function Image(props: ImageProps): ReactNode {
     const {
-        src,
+        src: srcProp,
         alt,
-        width,
-        height,
+        width: widthProp,
+        height: heightProp,
         fill = false,
         objectFit,
         priority = false,
         placeholder = 'empty',
-        blurDataURL,
+        blurDataURL: blurDataURLProp,
         className: userClassName,
         style,
         onLoad,
         ...rest
     } = props;
 
+    // `src` may be a plain URL or a `?toil` import object; unpack it and let explicit props win, so a
+    // `?toil` import auto-fills the blur placeholder + aspect-ratio with no extra props.
+    const source = typeof srcProp === 'string' ? null : srcProp;
+    const src = typeof srcProp === 'string' ? srcProp : srcProp.src;
+    const width = widthProp ?? source?.width;
+    const height = heightProp ?? source?.height;
+    const blurDataURL = blurDataURLProp ?? source?.blurDataURL;
+
     const [loaded, setLoaded] = useState(false);
-    const showBlur = placeholder === 'blur' && blurDataURL !== undefined && !loaded;
+    // The placeholder paints while the real image loads, then drops on load. With a `blurDataURL`
+    // (auto-filled by a `?toil` import, or passed) it's that tiny image blurred; otherwise it's a
+    // neutral skeleton shimmer — so `placeholder="blur"` is never a silent no-op. It only shows if
+    // there's a reserved box to paint into (give `width`+`height`, or use `fill` in a sized parent).
+    const showPlaceholder = placeholder === 'blur' && !loaded;
+    const placeholderClass = !showPlaceholder
+        ? undefined
+        : blurDataURL !== undefined
+          ? 'toil-img-blur'
+          : 'toil-img-skeleton';
+    // Reserve space so the image can't shift layout when it loads: an explicit aspect-ratio derived
+    // from width+height survives responsive `width:100%` CSS (bare width/height attributes do not).
+    const aspectRatio =
+        width !== undefined && height !== undefined ? `${width} / ${height}` : undefined;
 
-    // Layout + the blur placeholder come from toil's shipped CSS classes (see `buildHtml`'s
-    // `<style id="toil-base">`) rather than inline styles, so they're SSR-safe AND overridable by the
-    // app's CSS. Only genuinely per-instance bits stay inline: `objectFit` and the blur image URL. For
-    // a non-`fill` image the caller's `className`/`style` ride on the <img>; for `fill` they go on the
-    // wrapper box (below) instead, since that box is what the caller sizes.
+    // Layout + placeholder come from toil's shipped CSS classes (see `buildHtml`'s `<style id="toil-
+    // base">`) not inline styles, so they're SSR-safe AND overridable. Only per-instance bits stay
+    // inline: `objectFit`, the aspect-ratio, and the blur image URL. For a non-`fill` image the
+    // caller's `className`/`style` ride on the <img>; for `fill` they go on the wrapper box below.
     const imgClass =
-        [fill ? 'toil-img-fill' : userClassName, showBlur ? 'toil-img-blur' : undefined]
-            .filter(Boolean)
-            .join(' ') || undefined;
+        [fill ? 'toil-img-fill' : userClassName, placeholderClass].filter(Boolean).join(' ') ||
+        undefined;
     const imgStyle: CSSProperties = {
         ...(objectFit !== undefined ? { objectFit } : {}),
-        ...(showBlur ? { backgroundImage: `url(${blurDataURL})` } : {}),
+        ...(showPlaceholder && blurDataURL !== undefined
+            ? { backgroundImage: `url(${blurDataURL})` }
+            : {}),
+        ...(fill || aspectRatio === undefined ? {} : { aspectRatio }),
         ...(fill ? {} : style),
     };
 
@@ -107,6 +144,7 @@ export function Image(props: ImageProps): ReactNode {
     // NEVER absolutely positioned, so it can't escape to fill the page nor collapse to a zero-height
     // box. We still wrap it so the caller's `width`/`height`/`style` size the box, not the raw `<img>`.
     const boxStyle: CSSProperties = {
+        ...(aspectRatio !== undefined ? { aspectRatio } : {}),
         ...(width !== undefined ? { width } : {}),
         ...(height !== undefined ? { height } : {}),
         ...style,

package/src/client/index.ts

@@ -96,7 +96,7 @@ export type {
 export { usePageSearch } from './search/use-page-search.js';
 export type { PageSearch } from './search/use-page-search.js';
 export { Image } from './components/Image.js';
-export type { ImageProps } from './components/Image.js';
+export type { ImageProps, ToilImageSource } from './components/Image.js';
 export { Script } from './components/Script.js';
 export type { ScriptProps, ScriptStrategy } from './components/Script.js';
 export { Form } from './components/Form.js';

package/src/compiler/generate.ts

@@ -36,6 +36,9 @@ const IMAGETOOLS_MODULES = [
     `declare module '*as=srcset' {\n    const src: string;\n    export default src;\n}`,
     `declare module '*as=url' {\n    const src: string;\n    export default src;\n}`,
     `declare module '*as=metadata' {\n    const metadata: { src: string; width?: number; height?: number; format?: string }[];\n    export default metadata;\n}`,
+    // `import hero from './hero.webp?toil'` -> a Toil.Image source carrying an auto-generated blur LQIP
+    // and intrinsic size (see compiler/image-blur.ts). Pass it straight to `<Toil.Image src={hero} />`.
+    `declare module '*?toil' {\n    const image: { src: string; width: number; height: number; blurDataURL: string };\n    export default image;\n}`,
 ].join('\n');
 
 export const TOIL_ENV_DTS =
@@ -412,6 +415,9 @@ const TOIL_BASE_STYLE =
     `.toil-img-fill-box{display:block;overflow:hidden}` +
     `.toil-img-fill{display:block;width:100%;height:100%;object-fit:cover}` +
     `.toil-img-blur{background-size:cover;background-position:center;filter:blur(20px)}` +
+    `.toil-img-skeleton{background:linear-gradient(90deg,#ececed 25%,#f4f4f5 37%,#ececed 63%);background-size:400% 100%;animation:toil-img-shimmer 1.4s ease infinite}` +
+    `@keyframes toil-img-shimmer{0%{background-position:100% 50%}100%{background-position:0 50%}}` +
+    `@media (prefers-reduced-motion:reduce){.toil-img-skeleton{animation:none}}` +
     `</style>`;
 
 /**

package/src/compiler/image-blur.ts

@@ -0,0 +1,42 @@
+import type { Plugin } from 'vite';
+
+/** An image import carrying the `?toil` flag: `import hero from './hero.webp?toil'`. */
+const TOIL_QUERY = /[?&]toil(?:&|$)/;
+/** Raster formats sharp can downscale into an LQIP. (SVG/animated stay as-is — no blur.) */
+const RASTER = /\.(?:png|jpe?g|webp|avif|gif|tiff?)(?:\?|$)/i;
+
+/**
+ * Auto-generates a tiny blurred base64 LQIP (low-quality image placeholder) for raster images imported
+ * with the `?toil` flag, and returns a `{ src, width, height, blurDataURL }` object that `Toil.Image`
+ * consumes to auto-fill its `blurDataURL` (`placeholder="blur"`) and its aspect-ratio — the way Next.js
+ * bakes a `blurDataURL` for static image imports. Runs in dev and build (Vite `load`); `sharp` is loaded
+ * lazily so it only costs anything when a `?toil` import is actually resolved.
+ *
+ * Usage: `import hero from './hero.webp?toil'` then `<Toil.Image src={hero} placeholder="blur" />`.
+ * The bare `src` is re-imported with no query, so Vite/imagetools still optimize + hash the real asset
+ * (this plugin only adds the placeholder + intrinsic size); it skips itself on that bare import.
+ */
+export function imageBlurPlugin(): Plugin {
+    return {
+        name: 'toil:image-blur',
+        enforce: 'pre',
+        async load(id) {
+            if (!TOIL_QUERY.test(id) || !RASTER.test(id)) return undefined;
+            const file = id.replace(/\?.*$/, '');
+            const { default: sharp } = await import('sharp');
+            const meta = await sharp(file).metadata();
+            // ~24px longest edge, blurred, webp — a few hundred base64 bytes, inlined as a data URI.
+            const lqip = await sharp(file)
+                .resize(24, 24, { fit: 'inside' })
+                .blur()
+                .webp({ quality: 40 })
+                .toBuffer();
+            const blurDataURL = `data:image/webp;base64,${lqip.toString('base64')}`;
+            return (
+                `import src from ${JSON.stringify(file)};\n` +
+                `export default { src, width: ${meta.width ?? 0}, height: ${meta.height ?? 0}, ` +
+                `blurDataURL: ${JSON.stringify(blurDataURL)} };\n`
+            );
+        },
+    };
+}

package/src/compiler/prerender.ts

@@ -7,7 +7,7 @@ import type * as TS from 'typescript';
 import type { Plugin } from 'vite';
 
 import { type ResolvedToilConfig } from './config.js';
-import { scanRoutes } from './routes.js';
+import { patternToBracketFile, scanRoutes, staticSectionPattern } from './routes.js';
 import { injectSeoHtml, routeSeo } from './seo.js';
 
 type Ts = typeof TS;
@@ -115,12 +115,51 @@ export function extractStaticMetadata(ts: Ts, filePath: string): Record<string,
     return extractStaticExports(ts, filePath, ['metadata']).metadata ?? null;
 }
 
+/**
+ * True when the route file has a literal `export const <name> = true`. Used to detect the edge-SSR
+ * opt-in (`export const ssr = true`) without spinning up a Vite SSR server, so the static prerender
+ * can leave SSR routes to the SSR path.
+ */
+export function exportsTrue(ts: Ts, filePath: string, name: string): boolean {
+    let source: string;
+    try {
+        source = fs.readFileSync(filePath, 'utf8');
+    } catch {
+        return false;
+    }
+    const sf = ts.createSourceFile(
+        filePath,
+        source,
+        ts.ScriptTarget.Latest,
+        true,
+        ts.ScriptKind.TSX,
+    );
+    for (const stmt of sf.statements) {
+        if (!ts.isVariableStatement(stmt)) continue;
+        if (!stmt.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) continue;
+        for (const decl of stmt.declarationList.declarations) {
+            if (
+                ts.isIdentifier(decl.name) &&
+                decl.name.text === name &&
+                decl.initializer?.kind === ts.SyntaxKind.TrueKeyword
+            ) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+
 /**
  * Build-only plugin that statically pre-renders per-route HTML for SEO. After the bundle is written,
- * it takes the built shell (`index.html`), and for each static route bakes that route's
- * `metadata` (merged over the site-wide `seo` defaults) into a `<route>/index.html` so a JS-less
- * crawler hitting the route gets correct per-page tags. Dynamic (`generateMetadata`) and `:param`
- * routes are skipped (no data at build) and fall back to the client-rendered shell.
+ * it takes the built shell (`index.html`), and for each route bakes that route's `metadata` (merged
+ * over the site-wide `seo` defaults) into a browsable HTML file so a JS-less crawler gets correct
+ * per-page tags:
+ *   - a STATIC route (`/about`) -> `<route>/index.html`;
+ *   - a DYNAMIC route (`/blog/:id`) -> a literal bracket template `blog/[id].html` that the static
+ *     server serves for any concrete `/blog/<x>` and the client router hydrates. Its canonical points
+ *     at the route's static section (`/blog`); the client sets the exact per-value URL on hydration.
+ * A dynamic template is a file, never a `<seg>/index.html` folder, so it never shadows a sibling.
  */
 export function prerenderPlugin(cfg: ResolvedToilConfig): Plugin {
     return {
@@ -139,15 +178,29 @@ export function prerenderPlugin(cfg: ResolvedToilConfig): Plugin {
             const ts = await loadTypeScript(cfg.root);
 
             const routes = scanRoutes(cfg.routesAbsDir).filter(
-                (r) => r.slot === undefined && !r.intercept && !/[:*]/.test(r.pattern),
+                (r) => r.slot === undefined && !r.intercept,
             );
             for (const route of routes) {
+                const isDynamic = /[:*]/.test(route.pattern);
+                // A dynamic route that opts into edge SSR (`export const ssr = true`) is rendered by
+                // the SSR template path. Baking a static bracket template would let the edge's
+                // static-first serving shadow it, so leave SSR routes to SSR. (When `ts` is null the
+                // check is skipped and we bake anyway: fail-OPEN deliberately favors the common
+                // non-SSR dynamic route, which would 404 without a template; typescript is always
+                // present in a real toiljs project, so this branch is effectively unreachable.)
+                if (isDynamic && ts && exportsTrue(ts, route.file, 'ssr')) continue;
                 const metadata = ts ? extractStaticMetadata(ts, route.file) : null;
-                const html = injectSeoHtml(shell, routeSeo(cfg.seo, metadata, route.pattern));
-                const target =
-                    route.pattern === '/'
-                        ? shellPath
-                        : path.join(outDir, route.pattern.replace(/^\//, ''), 'index.html');
+                // A dynamic route's concrete URL is unknown at build, so its canonical/OG URL points
+                // at the static section (`/blog/:id` -> `/blog`); the client refines it on hydration.
+                const seoPattern = isDynamic ? staticSectionPattern(route.pattern) : route.pattern;
+                const html = injectSeoHtml(shell, routeSeo(cfg.seo, metadata, seoPattern));
+                // Dynamic -> a literal bracket template (`blog/[id].html`); static -> `<route>/index.html`
+                // (the `/` route is the shell itself). The bracket file is never a folder+index.html.
+                const target = isDynamic
+                    ? path.join(outDir, patternToBracketFile(route.pattern))
+                    : route.pattern === '/'
+                      ? shellPath
+                      : path.join(outDir, route.pattern.replace(/^\//, ''), 'index.html');
                 fs.mkdirSync(path.dirname(target), { recursive: true });
                 fs.writeFileSync(target, html);
             }

package/src/compiler/routes.ts

@@ -34,6 +34,44 @@ function toUrlSegment(segment: string): string {
         .replace(/^\[(.+)\]$/, ':$1');
 }
 
+/** Inverse of {@link toUrlSegment}: turns a URL pattern segment back into its on-disk bracket
+ *  form (`:id`→`[id]`, `*x`→`[...x]`, `**x`→`[[...x]]`). Static segments pass through unchanged. */
+function bracketSegment(segment: string): string {
+    if (segment.startsWith('**')) return `[[...${segment.slice(2)}]]`;
+    if (segment.startsWith('*')) return `[...${segment.slice(1)}]`;
+    if (segment.startsWith(':')) return `[${segment.slice(1)}]`;
+    return segment;
+}
+
+/**
+ * The on-disk HTML filename (relative to the build output dir) a DYNAMIC route pattern bakes to:
+ * the inverse of the scan mapping, with the last segment as the file and the rest as directories.
+ * This is the literal bracket template the static server serves for any matching URL and the client
+ * router hydrates, so it must not become a `<seg>/index.html` folder (which would shadow siblings).
+ *   /blog/:id      -> blog/[id].html
+ *   /docs/*slug    -> docs/[...slug].html
+ *   /docs/**slug   -> docs/[[...slug]].html
+ *   /:category/:id -> [category]/[id].html
+ */
+export function patternToBracketFile(pattern: string): string {
+    return pattern.split('/').filter(Boolean).map(bracketSegment).join('/') + '.html';
+}
+
+/**
+ * The static "section" of a pattern: the same pattern with every dynamic (`:`/`*`) segment dropped.
+ * Used as the canonical/OG base URL when baking a dynamic route's build-time SEO (the concrete
+ * per-value URL is unknown at build; the client sets it on hydration).
+ *   /blog/:id      -> /blog
+ *   /:category/:id -> /
+ */
+export function staticSectionPattern(pattern: string): string {
+    const kept = pattern
+        .split('/')
+        .filter(Boolean)
+        .filter((s) => !s.startsWith(':') && !s.startsWith('*'));
+    return '/' + kept.join('/');
+}
+
 /** Interception markers: `(.)` same level, `(..)` up one, `(...)` from the routes root. */
 const INTERCEPT_RE = /^\((\.{1,3})\)(.+)$/;
 

package/src/compiler/vite.ts

@@ -12,6 +12,7 @@ import { createLogger, type InlineConfig, type Logger, mergeConfig, type PluginO
 import { type ResolvedToilConfig } from './config.js';
 import { fontPreloadPlugin } from './fonts.js';
 import { imageReportPlugin } from './image-report.js';
+import { imageBlurPlugin } from './image-blur.js';
 import { toilPlugin } from './plugin.js';
 import { prerenderPlugin } from './prerender.js';
 
@@ -166,6 +167,10 @@ export async function createViteConfig(cfg: ResolvedToilConfig): Promise<InlineC
         customLogger: brandedLogger(),
         plugins: [
             tailwind,
+            // Auto-generate a tiny blurred base64 LQIP for `?toil` image imports (consumed by
+            // `Toil.Image` placeholder="blur"). Runs before imagetools (enforce:'pre') so it owns the
+            // `?toil` query; the bare re-imported src still flows through imagetools below.
+            cfg.images ? imageBlurPlugin() : undefined,
             // Build-time image resize/optimization. Every *imported* raster image is compressed to
             // webp by default (so a plain `<img src={imported}>` is optimized too, not just
             // `Toil.Image`); add `?w=400;800&format=…` to resize or pick a format. `public/` assets

package/src/devserver/http/runtime.ts

@@ -84,6 +84,106 @@ export function resolveStaticFile(root: string, requestPath: string): string | n
     return resolveFileInside(root, decoded.replace(/^\/+/, ''));
 }
 
+// --- Dynamic bracket-template routing (mirrors the toil-backend edge) ---------
+//
+// The build emits a dynamic route `blog/[id].tsx` as a literal `blog/[id].html`
+// template that boots the SPA for any concrete `/blog/<x>`. When no exact file
+// matches, walk the URL segments and, at each directory, serve a bracket sibling
+// using the client router's precedence: a real subdir wins (static > dynamic),
+// then `[x].html` (one segment), then `[x]/` (descend), then `[...x].html` (1+),
+// then `[[...x]].html` (0+). Directory scans are memoized.
+
+interface DirDynamic {
+    singleFile: string | null;
+    singleDir: string | null;
+    catchall: string | null;
+    optCatchall: string | null;
+}
+
+const dynDirCache = new Map<string, DirDynamic>();
+
+function classifyBracket(name: string, isDir: boolean): keyof DirDynamic | null {
+    if (isDir) {
+        if (name.startsWith('[') && name.endsWith(']') && !name.includes('...') && name.length > 2)
+            return 'singleDir';
+        return null;
+    }
+    if (!name.endsWith('.html')) return null;
+    const stem = name.slice(0, -'.html'.length);
+    if (stem.startsWith('[[...') && stem.endsWith(']]') && stem.length > 7) return 'optCatchall';
+    if (stem.startsWith('[...') && stem.endsWith(']') && stem.length > 5) return 'catchall';
+    if (stem.startsWith('[') && stem.endsWith(']') && !stem.startsWith('[..') && stem.length > 2)
+        return 'singleFile';
+    return null;
+}
+
+function scanDirDynamic(absDir: string): DirDynamic {
+    const cached = dynDirCache.get(absDir);
+    if (cached) return cached;
+    const d: DirDynamic = { singleFile: null, singleDir: null, catchall: null, optCatchall: null };
+    try {
+        for (const e of fs.readdirSync(absDir, { withFileTypes: true })) {
+            const kind = classifyBracket(e.name, e.isDirectory());
+            if (kind === null) continue;
+            const cur = d[kind];
+            if (cur === null || e.name < cur) d[kind] = e.name;
+        }
+    } catch {
+        // missing/unreadable directory: no templates
+    }
+    dynDirCache.set(absDir, d);
+    return d;
+}
+
+const joinRel = (dir: string, name: string): string => (dir === '' ? name : `${dir}/${name}`);
+
+function isDirInside(root: string, rel: string): boolean {
+    const resolved = path.resolve(root, rel);
+    if (resolved !== root && !resolved.startsWith(root + path.sep)) return false;
+    try {
+        return fs.statSync(resolved).isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+function resolveDynamicWalk(root: string, dir: string, segs: string[], i: number): string | null {
+    if (i >= segs.length) {
+        // Nothing left: only an optional catch-all (0 segments) serves the bare dir.
+        const oc = scanDirDynamic(path.join(root, dir)).optCatchall;
+        return oc === null ? null : joinRel(dir, oc);
+    }
+    const isLast = i + 1 === segs.length;
+    // A real static subdirectory wins over any dynamic template at this level.
+    const child = joinRel(dir, segs[i]);
+    if (isDirInside(root, child)) {
+        const r = resolveDynamicWalk(root, child, segs, i + 1);
+        if (r !== null) return r;
+    }
+    const d = scanDirDynamic(path.join(root, dir));
+    if (isLast && d.singleFile !== null) return joinRel(dir, d.singleFile);
+    if (d.singleDir !== null) {
+        const r = resolveDynamicWalk(root, joinRel(dir, d.singleDir), segs, i + 1);
+        if (r !== null) return r;
+    }
+    if (d.catchall !== null) return joinRel(dir, d.catchall);
+    if (d.optCatchall !== null) return joinRel(dir, d.optCatchall);
+    return null;
+}
+
+/** Resolve a request path to a bracket-template file (`blog/[id].html`) if one matches, else null. */
+export function resolveDynamicFile(root: string, requestPath: string): string | null {
+    let decoded: string;
+    try {
+        decoded = decodeURIComponent(requestPath);
+    } catch {
+        return null;
+    }
+    const segs = decoded.split('/').filter(Boolean);
+    const rel = resolveDynamicWalk(root, '', segs, 0);
+    return rel === null ? null : resolveFileInside(root, rel);
+}
+
 export interface PreparedHttpResponse {
     readonly status: number;
     readonly headers: readonly (readonly [string, string])[];

package/src/devserver/production.ts

@@ -31,6 +31,7 @@ import {
     isDispatchableMethod,
     prepareSsrResponse,
     prepareWasmResponse,
+    resolveDynamicFile,
     resolveStaticFile,
     runtimeServerOptions,
     toEnvelopeRequest,
@@ -456,7 +457,12 @@ async function startBuiltHttpServer(
             // lookup EVERY route served the root index.html, so view-source on e.g. /login showed
             // the home page's <head> (title/description/canonical/og) instead of the page's own.
             const routeHtml = resolveStaticFile(paths.staticRoot, `${request.path}/index.html`);
-            response.sendFile(routeHtml ?? paths.indexHtml);
+            // A dynamic route with no baked concrete page is served by its bracket template
+            // (`blog/[id].html`) matched the way the client router matches, mirroring the edge; the
+            // client then hydrates it for the concrete URL. Falls back to the root shell if none.
+            const dynHtml =
+                routeHtml === null ? resolveDynamicFile(paths.staticRoot, request.path) : null;
+            response.sendFile(routeHtml ?? dynHtml ?? paths.indexHtml);
             return;
         }
 

package/test/dom/Image.test.tsx

@@ -23,8 +23,8 @@ describe('Image', () => {
         expect(img.getAttribute('width')).toBe('200');
         expect(img.getAttribute('height')).toBe('100');
         expect(img.getAttribute('fetchpriority')).toBe('auto');
-        // A plain image adds no inline style and no toil class (nothing to lay out).
-        expect(img.getAttribute('style')).toBe(null);
+        // width+height reserve space via an explicit aspect-ratio (survives responsive `width:100%`).
+        expect(img.style.aspectRatio).toBe('200 / 100');
         expect(img.className).toBe('');
     });
 
@@ -105,4 +105,40 @@ describe('Image', () => {
         expect(img.style.backgroundImage).toBe('');
         expect(img.classList.contains('toil-img-blur')).toBe(false);
     });
+
+    it('falls back to a skeleton shimmer when placeholder="blur" has no blurDataURL', () => {
+        const { getByAltText } = render(
+            <Image src="/s.png" alt="s" width={10} height={10} placeholder="blur" />,
+        );
+        const img = getByAltText('s') as HTMLImageElement;
+        // never a silent no-op: a neutral skeleton paints (not the blur class, no background image)
+        expect(img.classList.contains('toil-img-skeleton')).toBe(true);
+        expect(img.classList.contains('toil-img-blur')).toBe(false);
+        expect(img.style.backgroundImage).toBe('');
+        fireEvent.load(img);
+        expect(img.classList.contains('toil-img-skeleton')).toBe(false);
+    });
+
+    it('reserves space with an aspect-ratio derived from width+height', () => {
+        const { getByAltText } = render(<Image src="/a.png" alt="a" width={400} height={300} />);
+        const img = getByAltText('a') as HTMLImageElement;
+        expect(img.style.aspectRatio).toBe('400 / 300');
+        expect(img.getAttribute('width')).toBe('400');
+        expect(img.getAttribute('height')).toBe('300');
+    });
+
+    it('reads src/dimensions/blur from a ?toil import object', () => {
+        const { getByAltText } = render(
+            <Image
+                src={{ src: '/hero.webp', width: 40, height: 30, blurDataURL: 'data:image/blur' }}
+                alt="h"
+                placeholder="blur"
+            />,
+        );
+        const img = getByAltText('h') as HTMLImageElement;
+        expect(img.getAttribute('src')).toBe('/hero.webp');
+        expect(img.style.aspectRatio).toBe('40 / 30');
+        expect(img.classList.contains('toil-img-blur')).toBe(true);
+        expect(img.style.backgroundImage).toContain('data:image/blur');
+    });
 });