@webjsdev/server 0.8.30 → 0.8.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.30",
+  "version": "0.8.32",
   "type": "module",
   "description": "webjs dev/prod server: SSR, router, API, server actions, live reload",
   "main": "index.js",

package/src/asset-hash.js

@@ -39,9 +39,9 @@
 
 import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
-import { extname, join, resolve, sep } from 'node:path';
+import { dirname, extname, join, relative, resolve, sep } from 'node:path';
 import { redactStringsAndTemplates } from './js-scan.js';
-import { resolveImport } from './module-graph.js';
+import { resolveImport, expandImportAlias } from './module-graph.js';
 
 /**
  * Length of the emitted hex hash. 12 hex chars (48 bits) is plenty to
@@ -306,6 +306,24 @@ const JS_SPEC_EXTS = new Set(['.js', '.mjs', '.jsx', '.cjs']);
  * @param {string} abs   the resolved absolute file path
  * @returns {string}
  */
+/**
+ * A base-path-safe relative specifier from the importing module to a resolved
+ * target file, used to rewrite a `#`-alias import in served source (#555). The
+ * browser resolves a relative specifier against the importer's own URL (already
+ * base-path-prefixed), so the result needs no importmap and no basePath fix-up,
+ * and it carries the `?v` the caller appends. Uses the resolved file's actual
+ * extension (so no `normalizeSpecToResolved` pass is needed).
+ *
+ * @param {string} importerAbs  absolute path of the module being served
+ * @param {string} abs          resolved absolute path of the import target
+ * @returns {string}
+ */
+function relativeSpecifier(importerAbs, abs) {
+  let rel = relative(dirname(importerAbs), abs).split(sep).join('/');
+  if (!rel.startsWith('.')) rel = './' + rel;
+  return rel;
+}
+
 function normalizeSpecToResolved(spec, abs) {
   const absExt = extname(abs);
   if (!absExt) return spec;
@@ -391,9 +409,15 @@ export function versionModuleImports(source, importerAbs) {
       // inside a string / template / comment and is not a real import edge.
       if (masked[/** @type {number} */ (m.index)] === ' ') continue;
       const spec = m[2];
-      // Only `./` `../` relative specifiers (base-path-correct, the app pattern).
-      // Bare -> importmap target; `/`-absolute -> pre-existing basePath gap.
-      if (spec[0] !== '.') continue;
+      const isRelative = spec[0] === '.';
+      // A `#`-style subpath alias (#555) is rewritten to a base-path-safe
+      // RELATIVE specifier below (so it carries `?v` and matches the preload,
+      // exactly like a relative import). Only `./`/`../` relatives and
+      // app-imports aliases qualify: a bare specifier is importmap-resolved and
+      // versioned at its target; a `/`-root-absolute specifier would miss the
+      // basePath prefix.
+      const isAlias = !isRelative && expandImportAlias(spec, _appDir) !== null;
+      if (!isRelative && !isAlias) continue;
       if (spec.includes('?')) continue;
       const abs = resolveImport(spec, importerAbs, _appDir);
       if (!abs || SERVER_FILE_RE.test(abs)) continue;
@@ -402,9 +426,14 @@ export function versionModuleImports(source, importerAbs) {
       if (!hash) continue;
       // `/d` flag: indices[2] is [start, end] of the specifier CONTENT (no
       // quotes). Replace it with the resolved-extension form + `?v` so the
-      // fetched URL is byte-identical to the preload href.
+      // fetched URL is byte-identical to the preload href. An alias is emitted
+      // as a relative specifier to the resolved file (the browser resolves it
+      // against the importer's already-prefixed URL, so it stays base-path-safe
+      // without the importmap, and the `?v` collapses fetch + preload to one
+      // immutable cache key).
       const [start, end] = /** @type {[number, number]} */ (m.indices[2]);
-      edits.push({ start, end, text: `${normalizeSpecToResolved(spec, abs)}?v=${hash}` });
+      const versioned = isAlias ? relativeSpecifier(importerAbs, abs) : normalizeSpecToResolved(spec, abs);
+      edits.push({ start, end, text: `${versioned}?v=${hash}` });
     }
   }
   if (edits.length === 0) return source;

package/src/check.js

@@ -74,9 +74,14 @@ export const RULES = [
       'A custom-element tag name must be registered exactly once across the app. Two `Class.register(\'tag\')` / `customElements.define(\'tag\', …)` calls for the SAME tag resolve INCONSISTENTLY at runtime: SSR overwrites the registry (last registration wins) while the browser keeps the first native upgrade, so the rendered element and the webjs registry disagree. Rename one tag.',
   },
   {
-    name: 'reactive-props-use-declare',
+    name: 'no-static-properties',
     description:
-      'Reactive properties listed in `static properties = { … }` must be typed with `declare propName: Type` (no value), and have their default set in `constructor()`. Plain class-field initializers (`prop = value` or `prop: Type = value`) compile to Object.defineProperty *after* super() under modern class-field semantics, clobbering the framework\'s reactive accessor and silently breaking re-renders.',
+      'Reactive properties must be declared via the `extends WebComponent({ … })` factory, never a hand-written `static properties = { … }` field in the class body. The factory types each field for you (no `declare` needed) and the runtime throws on a direct `static properties`. Migrate `class X extends WebComponent { static properties = { count: { type: Number } } }` to `class X extends WebComponent({ count: Number })`; use the `prop()` helper for options (`prop(Number, { reflect: true })`) and set defaults via the `default` option or in the constructor.',
+  },
+  {
+    name: 'reactive-props-no-class-field',
+    description:
+      'A reactive property declared via the `extends WebComponent({ … })` factory must NOT also have a plain class-field initializer (`count = 0` or `count: number = 0`) in the class body. Under modern class-field semantics that initializer runs Object.defineProperty *after* super(), clobbering the framework\'s reactive accessor and silently breaking re-renders. Set the default via the `default` property option (`prop(Number, { default: 0 })`) or by assigning in the constructor after super().',
   },
   {
     name: 'shell-in-non-root-layout',
@@ -166,58 +171,6 @@ function isComponentFile(relPath) {
   return segments.includes('components');
 }
 
-/**
- * Find every `<key>:` entry inside the first `static properties = { … }`
- * literal in `classBody`. Returns the bare property names: the keys
- * we'll then look up as class fields.
- *
- * @param {string} classBody
- * @returns {Set<string>}
- */
-function extractStaticPropertyNames(classBody) {
-  /** @type {Set<string>} */
-  const names = new Set();
-  const m = /static\s+properties\s*=\s*\{/.exec(classBody);
-  if (!m) return names;
-  const objStart = m.index + m[0].length;
-  const objEnd = matchClosingBrace(classBody, objStart);
-  if (objEnd === -1) return names;
-  const obj = classBody.slice(objStart, objEnd);
-  // Match keys at the top level of the object literal. A nested `{ … }`
-  // (the per-property declaration) is skipped via brace counting.
-  let i = 0;
-  while (i < obj.length) {
-    // Skip whitespace and commas.
-    while (i < obj.length && /[\s,]/.test(obj[i])) i++;
-    if (i >= obj.length) break;
-    // Read the identifier or string-literal key.
-    let key = '';
-    if (obj[i] === '"' || obj[i] === "'") {
-      const quote = obj[i++];
-      while (i < obj.length && obj[i] !== quote) { key += obj[i++]; }
-      i++; // closing quote
-    } else {
-      while (i < obj.length && /[A-Za-z0-9_$]/.test(obj[i])) key += obj[i++];
-    }
-    // Skip whitespace, then expect `:`.
-    while (i < obj.length && /\s/.test(obj[i])) i++;
-    if (obj[i] !== ':') break;
-    i++;
-    // Skip whitespace, then skip the value (either a `{ … }` literal or
-    // a single token like `String`).
-    while (i < obj.length && /\s/.test(obj[i])) i++;
-    if (obj[i] === '{') {
-      const valEnd = matchClosingBrace(obj, i + 1);
-      if (valEnd === -1) break;
-      i = valEnd + 1;
-    } else {
-      while (i < obj.length && obj[i] !== ',' && obj[i] !== '}') i++;
-    }
-    if (key) names.add(key);
-  }
-  return names;
-}
-
 /**
  * Scan a class body for class-field initializers naming any of `props`.
  * "Class-field" means: at the top of the class body (brace depth 0
@@ -440,23 +393,47 @@ export async function checkConventions(appDir) {
     }
   }
 
-  // --- Rule: reactive-props-use-declare ---
+  // --- Rule: no-static-properties ---
+  // A hand-written `static properties = { … }` in a WebComponent class body is
+  // no longer supported: reactive properties are declared via the
+  // `extends WebComponent({ … })` factory (the runtime throws on a direct
+  // `static properties`). Flag it statically so the editor catches it before
+  // the page 500s.
   {
     for (const { rel, scan } of files) {
-      // Use redacted source so test-fixture-style strings like
-      // `class X extends WebComponent { x = 0 }` inside template
-      // literals don't trip the rule. Real declarations live at
+      // Use redacted source so fixture-style strings like
+      // `class X extends WebComponent { static properties = {…} }` inside
+      // template literals don't trip the rule. Real declarations live at
       // top-level code where the redactor leaves them alone.
       if (!/class\s+\w+\s+extends\s+WebComponent/.test(scan)) continue;
-      for (const body of extractWebComponentClassBodies(scan)) {
-        const propNames = extractStaticPropertyNames(body);
-        if (propNames.size === 0) continue;
-        for (const bad of findFieldInitializers(body, propNames)) {
+      for (const { body } of extractWebComponentClassBodies(scan)) {
+        if (!/static\s+properties\s*=\s*\{/.test(body)) continue;
+        violations.push({
+          rule: 'no-static-properties',
+          file: rel,
+          message:
+            '`static properties = { … }` is no longer supported; declare reactive properties via the `extends WebComponent({ … })` factory instead.',
+          fix: 'Move the properties into the factory call: `class X extends WebComponent({ count: Number })`. Use `prop(Number, { reflect: true })` for options and set defaults via the `default` option or the constructor. Delete the `static properties` block and any `declare` fields for those props.',
+        });
+      }
+    }
+  }
+
+  // --- Rule: reactive-props-no-class-field ---
+  // A reactive property declared via the factory must not also carry a plain
+  // class-field initializer: it runs Object.defineProperty after super() and
+  // clobbers the framework's reactive accessor (silent broken re-renders).
+  {
+    for (const { rel, scan } of files) {
+      if (!/class\s+\w+\s+extends\s+WebComponent/.test(scan)) continue;
+      for (const { body, factoryProps } of extractWebComponentClassBodies(scan)) {
+        if (factoryProps.size === 0) continue;
+        for (const bad of findFieldInitializers(body, factoryProps)) {
           violations.push({
-            rule: 'reactive-props-use-declare',
+            rule: 'reactive-props-no-class-field',
             file: rel,
             message: `Reactive prop \`${bad}\` uses a class-field initializer; this clobbers the framework's reactive accessor under modern class-field semantics.`,
-            fix: `Replace with \`declare ${bad}: <Type>;\` and set the default inside \`constructor()\` after \`super()\`.`,
+            fix: `Remove the class-field initializer and set the default via the \`default\` option (\`prop(<Type>, { default: <value> })\`) or by assigning \`this.${bad} = <value>\` inside \`constructor()\` after \`super()\`.`,
           });
         }
       }
@@ -473,7 +450,7 @@ export async function checkConventions(appDir) {
   {
     for (const { rel, scan } of files) {
       if (!/class\s+\w+\s+extends\s+WebComponent/.test(scan)) continue;
-      for (const body of extractWebComponentClassBodies(scan)) {
+      for (const { body } of extractWebComponentClassBodies(scan)) {
         for (const method of ['constructor', 'willUpdate', 'render']) {
           const code = methodBodyOf(body, method);
           if (!code) continue;
@@ -661,7 +638,7 @@ export async function checkConventions(appDir) {
         // modifiers immediately followed by an identifier inside the
         // constructor's parameter list.
         regex: /constructor[ \t]*\([^)]*\b(?:public|private|protected|readonly)[ \t]+\w+/,
-        fix: 'Replace `constructor(public x: number)` with `x: number; constructor(x: number) { this.x = x; }`. The reactive-props-use-declare rule has the framework-specific shape: `declare x: number;` (no value) plus the assignment in the constructor body.',
+        fix: 'Replace `constructor(public x: number)` with `x: number; constructor(x: number) { this.x = x; }`.',
       },
       {
         name: 'import = require',

package/src/component-elision.js

@@ -416,7 +416,7 @@ export function analyzeComponentSource(src) {
     return { interactive: true, reason: 'no parseable WebComponent class body' };
   }
 
-  for (const body of bodies) {
+  for (const { body, factoryArg } of bodies) {
     // Shadow DOM always ships (#474). Declarative Shadow DOM attaches ONLY
     // during HTML parsing; an elided component that arrives via a client DOM
     // insertion (a soft-nav swap, a streamed <webjs-suspense> boundary's
@@ -447,7 +447,7 @@ export function analyzeComponentSource(src) {
         return { interactive: true, reason: `calls '${call}'` };
       }
     }
-    if (hasNonStateReactiveProperty(body)) {
+    if (hasNonStateReactiveProperty(body) || hasNonStateFactoryProperty(factoryArg)) {
       return {
         interactive: true,
         reason: 'declares a reactive property that is not { state: true }',
@@ -571,6 +571,36 @@ function hasNonStateReactiveProperty(classBody) {
   return false;
 }
 
+/**
+ * True if the class factory argument declares any property that is NOT
+ * marked `{ state: true }`.
+ *
+ * @param {string} factoryArg
+ * @returns {boolean}
+ */
+function hasNonStateFactoryProperty(factoryArg) {
+  if (!factoryArg) return false;
+  const objStart = factoryArg.indexOf('{');
+  if (objStart === -1) return false;
+  const objEnd = matchClosingBrace(factoryArg, objStart);
+  if (objEnd === -1) return true;
+  const obj = factoryArg.slice(objStart + 1, objEnd);
+  if (/\.\.\./.test(obj)) return true; // spread
+  for (const entry of topLevelPropertyValues(obj)) {
+    if (entry.startsWith('{')) {
+      const code = entry
+        .replace(/'[^'\n]*'/g, "''")
+        .replace(/"[^"\n]*"/g, '""')
+        .replace(/`[^`]*`/g, '``');
+      if (!/\bstate\s*:\s*true\b/.test(code)) return true;
+    } else {
+      // Shorthand like `count: Number` rides an attribute, not state
+      return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Yield the trimmed VALUE text of each top-level `key: value` entry in a
  * properties object body, splitting on depth-0 commas and respecting

package/src/dev.js

@@ -1,6 +1,6 @@
 import { createServer as createHttp1Server } from 'node:http';
 import { stat, readFile, watch as fsWatch } from 'node:fs/promises';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join, extname, resolve, dirname, relative, sep } from 'node:path';
 import { createRequire } from 'node:module';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -45,7 +45,7 @@ import {
   varyWithAcceptEncoding,
 } from './listener-core.js';
 import { scanBareImports, resolveVendorImports, serveDownloadedBundle, clearVendorCache, hasVendorPin, readPinFile, prunePinToReachable } from './vendor.js';
-import { buildModuleGraph, transitiveDeps, reachableFromEntries, resolveImport } from './module-graph.js';
+import { buildModuleGraph, transitiveDeps, reachableFromEntries, resolveImport, appImportsMap } from './module-graph.js';
 import { primeComponentRegistry, findOrphanComponents, scanComponents } from './component-scanner.js';
 import { analyzeElision, elideImportsFromSource } from './component-elision.js';
 
@@ -85,7 +85,7 @@ function resolveRequestId(req) {
 function shouldAccessLog(pathname) {
   return !pathname.startsWith('/__webjs/');
 }
-import { setVendorEntries, setCoreInstall, publishBuildId, setBasePath, basePath } from './importmap.js';
+import { setVendorEntries, setCoreInstall, publishBuildId, setBasePath, basePath, setImportAliasEntries, importAliasBrowserEntries } from './importmap.js';
 import { readBasePath, stripBasePath, withBasePath } from './base-path.js';
 import { setAssetRoots, clearAssetHashCache, setElisionFingerprint, withAssetHash, assetHashFor, versionModuleImports } from './asset-hash.js';
 import { urlFromRequest } from './forwarded.js';
@@ -493,6 +493,16 @@ export async function createRequestHandler(opts) {
     existsSync(join(distDir, 'webjs-core-browser.js'));
   await setCoreInstall(coreDir, distComplete);
 
+  // Path-alias imports (#555). Emit the browser importmap scopes for the app's
+  // `package.json "imports"` aliases, derived from the SAME map the server
+  // resolver (`expandImportAlias`) reads, so SSR and the browser agree. The
+  // scaffold ships the single catch-all `"#*": "./*"` (one key, zero
+  // maintenance, Bun-safe), which expands to one browser prefix scope per
+  // top-level dir (`#lib/` -> `/lib/`, ...); the dir scan is here so a new
+  // folder is picked up on boot. An app with no `"imports"` block yields {}
+  // (a no-op, byte-identical to before this feature).
+  await setImportAliasEntries(importAliasBrowserEntries(appImportsMap(appDir), appTopLevelDirs(appDir)));
+
   // Content-hash asset URLs for immutable caching (issue #243). Bind the
   // asset-hash module to the app + core roots and enable fingerprinting in
   // PROD only. In dev `withAssetHash` stays a pure no-op (never enabled), so
@@ -2361,6 +2371,26 @@ function computeBrowserBoundFiles(routeTable, moduleGraph, components, appDir) {
   return reachableFromEntries(moduleGraph, [...entries], appDir);
 }
 
+/**
+ * List the app's top-level source directory names, for expanding a `#*`
+ * catch-all import alias into one browser importmap prefix scope per dir (#555).
+ * Excludes infra dirs that are never imported via `#` (node_modules, dotfiles,
+ * the build/vendor caches). A new top-level folder is picked up on the next boot
+ * (dev restarts on changes), so the alias stays zero-maintenance.
+ * @param {string} appDir
+ * @returns {string[]}
+ */
+function appTopLevelDirs(appDir) {
+  const SKIP = new Set(['node_modules', 'dist', 'public']);
+  try {
+    return readdirSync(appDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && !e.name.startsWith('.') && !SKIP.has(e.name))
+      .map((e) => e.name);
+  } catch {
+    return [];
+  }
+}
+
 /**
  * Find the absolute directory of the `@webjsdev/core` package, regardless of
  * whether we're running from the monorepo or an installed copy.

package/src/importmap.js

@@ -28,6 +28,17 @@ function escapeAttr(s) {
 /** @type {Record<string, string>} */
 let _extraEntries = {};
 
+/**
+ * Browser importmap entries for the app's `package.json "imports"` subpath
+ * aliases (#555), e.g. `{ "#lib/": "/lib/" }` for `"#lib/*": "./lib/*"`. Kept in lockstep
+ * with the server-side resolver (`module-graph.js`'s `expandImportAlias`):
+ * BOTH are derived from the one `"imports"` map, so an alias that resolves in
+ * SSR never 404s in the browser (the #158/#159 preload-mismatch class). Set at
+ * boot by `dev.js` via `setImportAliasEntries`.
+ * @type {Record<string, string>}
+ */
+let _aliasEntries = {};
+
 /**
  * The normalized `webjs.basePath` for a sub-path deployment (issue #256),
  * `''` (the default) for a root mount. When non-empty, every same-origin
@@ -67,6 +78,65 @@ export function basePath() {
   return _basePath;
 }
 
+/**
+ * Derive the BROWSER importmap entries for an app's `package.json "imports"`
+ * subpath-alias map (#555). The scaffold ships a single root catch-all key
+ * `"#*": "./*"` (one key, zero maintenance: a new top-level folder is aliased
+ * with no config change, and `#*` resolves natively on Node AND Bun, unlike a
+ * `#/`-prefixed key which Bun rejects). A browser importmap needs a
+ * trailing-slash PREFIX key to match, and a bare `#` is not one, so a catch-all
+ * is expanded into one prefix scope PER top-level directory (`topLevelDirs`):
+ * `#lib/` -> `/lib/`, `#components/` -> `/components/`, etc. The dirs are scanned
+ * by the caller (dev.js) so this stays pure; a new folder produces a new scope
+ * on the next boot. A non-catch-all key is mapped directly: a per-dir wildcard
+ * `"#lib/*": "./lib/*"` becomes `"#lib/": "/lib/"`, an exact `"#db": "./x.ts"`
+ * becomes `"#db": "/x.ts"`. The leading `./` becomes a root-absolute `/` and the
+ * `*` is dropped (the trailing slash carries the prefix match). A non-default
+ * base (`"#*": "./src/*"`) folds into the emitted URL. Only string targets are
+ * mappable (a conditional-export object is skipped). Derived from the SAME map
+ * the server resolver reads, so SSR and the browser agree.
+ *
+ * @param {Record<string, unknown> | null | undefined} importsMap
+ * @param {string[]} [topLevelDirs]  app top-level dir names, for expanding a `#*` catch-all
+ * @returns {Record<string, string>}
+ */
+export function importAliasBrowserEntries(importsMap, topLevelDirs = []) {
+  /** @type {Record<string, string>} */
+  const out = {};
+  if (!importsMap || typeof importsMap !== 'object') return out;
+  for (const [key, value] of Object.entries(importsMap)) {
+    if (typeof value !== 'string') continue;
+    if (!value.startsWith('./')) continue; // only app-root-relative targets map to a URL
+    const star = key.indexOf('*');
+    if (star !== -1 && key.slice(0, star) === '#') {
+      // Root catch-all `#*` -> `./<base>*`: expand to a prefix scope per dir.
+      // base is the part of the value between `.` and `*` (`'' ` for `./*`,
+      // `/src/` for `./src/*`), so `#<dir>/` -> `/<base><dir>/`.
+      const base = value.slice(1, value.lastIndexOf('*')); // './*' -> '/', './src/*' -> '/src/'
+      for (const dir of topLevelDirs) out[`#${dir}/`] = `${base}${dir}/`;
+      continue;
+    }
+    // Per-dir wildcard or exact key: map directly.
+    out[key.replace('*', '')] = value.replace(/^\./, '').replace('*', '');
+  }
+  return out;
+}
+
+/**
+ * Bind the browser importmap to the app's `package.json "imports"` aliases
+ * (#555). Called once at boot by `dev.js`, derived from the SAME `"imports"`
+ * map the server resolver reads, so SSR and the browser agree. The hash is
+ * recomputed eagerly (like `setBasePath` / `setCoreInstall`) so
+ * `importMapHash()` stays synchronous on the per-request path.
+ *
+ * @param {Record<string, string>} entries  browser entries from `importAliasBrowserEntries`
+ * @returns {Promise<void>}
+ */
+export async function setImportAliasEntries(entries) {
+  _aliasEntries = entries && typeof entries === 'object' ? entries : {};
+  _importMapHash = await digestHex('SHA-256', JSON.stringify(buildImportMap({ fingerprint: false })));
+}
+
 /**
  * SRI integrity hashes keyed by FINAL URL (post-importmap-rewrite).
  * Populated only when a pin file with `integrity` is present;
@@ -338,6 +408,7 @@ export function buildImportMap(opts = {}) {
   const merged = {
     ..._coreEntries,
     ..._extraEntries,
+    ..._aliasEntries,
   };
   // Sort keys so logically-identical importmaps serialize byte-for-byte
   // identically. The client router compares textContent to detect

package/src/js-scan.js

@@ -347,16 +347,127 @@ export function maskComments(src) {
  */
 export function extractWebComponentClassBodies(content) {
   const bodies = [];
-  const re = /class\s+\w+\s+extends\s+WebComponent\s*\{/g;
+  const re = /class\s+\w+\s+extends\s+WebComponent/g;
   let m;
   while ((m = re.exec(content)) !== null) {
-    const bodyStart = m.index + m[0].length;
-    const end = matchClosingBrace(content, bodyStart);
-    if (end !== -1) bodies.push(content.slice(bodyStart, end));
+    let i = m.index + m[0].length;
+    while (i < content.length && /\s/.test(content[i])) i++;
+    if (i >= content.length) continue;
+    
+    let factoryArg = '';
+    const factoryProps = new Set();
+    if (content[i] === '(') {
+      const closeParen = matchClosingParenthesis(content, i + 1);
+      if (closeParen === -1) continue;
+      factoryArg = content.slice(i + 1, closeParen);
+      
+      const objStart = factoryArg.indexOf('{');
+      if (objStart !== -1) {
+        const objEnd = matchClosingBrace(factoryArg, objStart + 1);
+        if (objEnd !== -1) {
+          const objContent = factoryArg.slice(objStart + 1, objEnd);
+          parsePropsFromObjectLiteral(objContent, factoryProps);
+        }
+      }
+      i = closeParen + 1;
+      while (i < content.length && /\s/.test(content[i])) i++;
+    }
+    if (content[i] === '{') {
+      const bodyStart = i + 1;
+      const end = matchClosingBrace(content, bodyStart);
+      if (end !== -1) {
+        bodies.push({
+          body: content.slice(bodyStart, end),
+          factoryProps,
+          factoryArg
+        });
+      }
+    }
   }
   return bodies;
 }
 
+/**
+ * Extract properties from an object literal block.
+ *
+ * @param {string} obj
+ * @param {Set<string>} names
+ */
+export function parsePropsFromObjectLiteral(obj, names) {
+  let i = 0;
+  while (i < obj.length) {
+    while (i < obj.length && /[\s,]/.test(obj[i])) i++;
+    if (i >= obj.length) break;
+    let key = '';
+    if (obj[i] === '"' || obj[i] === "'") {
+      const quote = obj[i++];
+      while (i < obj.length && obj[i] !== quote) { key += obj[i++]; }
+      i++; // closing quote
+    } else {
+      while (i < obj.length && /[A-Za-z0-9_$]/.test(obj[i])) key += obj[i++];
+    }
+    while (i < obj.length && /\s/.test(obj[i])) i++;
+    if (obj[i] !== ':') break;
+    i++;
+    while (i < obj.length && /\s/.test(obj[i])) i++;
+    if (obj[i] === '{') {
+      const valEnd = matchClosingBrace(obj, i + 1);
+      if (valEnd === -1) break;
+      i = valEnd + 1;
+    } else {
+      while (i < obj.length && obj[i] !== ',' && obj[i] !== '}') i++;
+    }
+    if (key) names.add(key);
+  }
+}
+
+
+/**
+ * Walk forward from `start` (just after an opening `(`) and return the
+ * index of the matching `)`. Tracks string/template-literal state so
+ * `)` inside strings or templates does not decrement depth.
+ * Returns -1 if no balanced parenthesis is found.
+ *
+ * @param {string} s
+ * @param {number} start
+ */
+export function matchClosingParenthesis(s, start) {
+  let depth = 1;
+  let i = start;
+  let str = ''; // '', "'", '"', or backtick
+  while (i < s.length) {
+    const c = s[i];
+    if (str) {
+      if (c === '\\') { i += 2; continue; }
+      if (c === str) str = '';
+      else if (str === '`' && c === '$' && s[i + 1] === '{') {
+        const closeBrace = matchClosingBrace(s, i + 2);
+        if (closeBrace === -1) return -1;
+        i = closeBrace + 1;
+        continue;
+      }
+      i++;
+      continue;
+    }
+    if (c === "'" || c === '"' || c === '`') { str = c; i++; continue; }
+    if (c === '/' && s[i + 1] === '/') { // line comment
+      while (i < s.length && s[i] !== '\n') i++;
+      continue;
+    }
+    if (c === '/' && s[i + 1] === '*') { // block comment
+      i += 2;
+      while (i < s.length && !(s[i] === '*' && s[i + 1] === '/')) i++;
+      i += 2;
+      continue;
+    }
+    if (c === '(') depth++;
+    else if (c === ')') { depth--; if (depth === 0) return i; }
+    i++;
+  }
+  return -1;
+}
+
+
 /**
  * Walk forward from `start` (just after an opening `{`) and return the
  * index of the matching `}`. Tracks string/template-literal state so

package/src/module-graph.js

@@ -12,10 +12,71 @@
  */
 
 import { readFile, readdir, stat } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve, dirname, extname, sep } from 'node:path';
 import { redactStringsAndTemplates } from './js-scan.js';
 
+/**
+ * Per-appDir cache of the parsed `package.json "imports"` subpath-alias map
+ * (#555). `null` means "no imports block" (the common case for an app that
+ * does not use the `#` alias). Read once per appDir; cleared with the parse
+ * cache on rebuild.
+ * @type {Map<string, Record<string,string> | null>}
+ */
+const IMPORTS_CACHE = new Map();
+
+/**
+ * Read an app's `package.json "imports"` subpath-import map (Node's native
+ * import-alias mechanism). Cached per appDir.
+ * @param {string} appDir
+ * @returns {Record<string,string> | null}
+ */
+export function appImportsMap(appDir) {
+  if (IMPORTS_CACHE.has(appDir)) return IMPORTS_CACHE.get(appDir) ?? null;
+  let map = null;
+  try {
+    const pkg = JSON.parse(readFileSync(join(appDir, 'package.json'), 'utf8'));
+    if (pkg && typeof pkg.imports === 'object' && pkg.imports) map = pkg.imports;
+  } catch { /* no package.json / unparseable: no aliases */ }
+  IMPORTS_CACHE.set(appDir, map);
+  return map;
+}
+
+/**
+ * Expand a `package.json "imports"` subpath alias (e.g. `#lib/db.server.ts`
+ * with the scaffold's catch-all `"#*": "./*"`) to its real APP-RELATIVE target
+ * string (`./lib/db.server.ts`).
+ * The security-critical seam (#555): the graph walker, auth gate, elision, and
+ * `no-server-import-in-browser-module` all route through `resolveImport`, so
+ * expanding the alias here (to the real path) is what stops an alias from
+ * laundering a `.server.ts` past those checks. Driven off the actual `"imports"`
+ * map so a non-default base (`"#lib/*": "./src/lib/*"`) is honored; never
+ * hardcodes `./`. Supports one trailing `*` wildcard per key (Node's rule) plus
+ * exact keys. (A `#/`-prefixed key is avoided in the scaffold because Bun's
+ * native resolver rejects it; the expansion here is key-shape-agnostic.)
+ * @param {string} spec  the import specifier, e.g. `'#lib/db.server.ts'`
+ * @param {string} appDir
+ * @returns {string | null}  the app-relative target (e.g. `'./lib/db.server.ts'`), or null if no alias matches
+ */
+export function expandImportAlias(spec, appDir) {
+  const map = appImportsMap(appDir);
+  if (!map) return null;
+  for (const [key, value] of Object.entries(map)) {
+    if (typeof value !== 'string') continue; // conditional-export objects are not graph-resolvable
+    const star = key.indexOf('*');
+    if (star === -1) {
+      if (spec === key) return value;
+      continue;
+    }
+    const prefix = key.slice(0, star);
+    const suffix = key.slice(star + 1);
+    if (!spec.startsWith(prefix) || !spec.endsWith(suffix)) continue;
+    const middle = spec.slice(prefix.length, spec.length - suffix.length);
+    return value.replace('*', middle);
+  }
+  return null;
+}
+
 /** @type {RegExp} match static `import … from '…'` and `import '…'` */
 const IMPORT_RE = /\bimport\s+(?:(?:[\w*{}\s,]+)\s+from\s+)?['"]([^'"]+)['"]/g;
 
@@ -52,6 +113,9 @@ const EXPORT_FROM_RE = /\bexport\b[^'";]+?\sfrom\s+['"]([^'"]+)['"]/g;
  * @returns {Promise<ModuleGraph>}
  */
 export async function buildModuleGraph(appDir) {
+  // Re-read the app's `package.json "imports"` each build so an edit to the
+  // alias map (#555) is picked up on rebuild.
+  IMPORTS_CACHE.delete(appDir);
   /** @type {ModuleGraph} */
   const graph = new Map();
   /** @type {Set<string>} every file walked this build (graph holds only files
@@ -286,8 +350,11 @@ async function parseFile(file, appDir, graph, seen) {
       // and is not a real import edge.
       if (masked[m.index] === ' ') continue;
       const spec = m[1];
-      // Only resolve relative imports within the project.
-      if (!spec.startsWith('.') && !spec.startsWith('/')) continue;
+      // Only resolve relative imports + `#`-style subpath aliases (#555)
+      // within the project. A bare npm specifier (dayjs) has no alias match
+      // and is skipped; an aliased `#lib/x.server.ts` IS followed so the
+      // graph / auth gate / elision see the real path through the alias.
+      if (!spec.startsWith('.') && !spec.startsWith('/') && !expandImportAlias(spec, appDir)) continue;
       const resolved = resolveImport(spec, file, appDir);
       if (resolved) deps.add(resolved);
     }
@@ -308,7 +375,13 @@ async function parseFile(file, appDir, graph, seen) {
 export function resolveImport(spec, fromFile, appDir) {
   const base = dirname(fromFile);
   let target;
-  if (spec.startsWith('/')) {
+  const aliased = expandImportAlias(spec, appDir);
+  if (aliased) {
+    // `#`-style subpath alias (#555): the app-relative target is resolved
+    // against the app root, then run through the same extension fallback below
+    // so the boundary / elision / preload all see the real on-disk path.
+    target = resolve(appDir, aliased);
+  } else if (spec.startsWith('/')) {
     // Absolute from app root (how browser sees it)
     target = join(appDir, spec);
   } else {