@webjsdev/server 0.8.91 → 0.10.0

package/src/browser-entries.js

@@ -13,15 +13,14 @@
  * does, without booting a server.
  *
  * Entries:
- *   - page / layout (both re-run on the client for hydration)
- *   - the error / loading / not-found / forbidden / unauthorized boundaries
- *   - the two root-only boundaries (global-error, global-not-found)
  *   - instrumentation-client (imported first in the boot)
  *   - every discovered component (a `static lazy` one is fetched by the lazy
  *     loader rather than imported by a page, so the component scan is an entry
  *     source in its own right)
  *
  * NOT entries, because the browser never fetches them as a module:
+ *   - pages, layouts and every boundary: they run only on the server, and the
+ *     boot imports the components they render instead (#1686)
  *   - route.{js,ts} (API handlers) and middleware.{js,ts}
  *   - metadata routes (sitemap.js, robots.js, manifest.js, …)
  *   - .server.{js,ts} files (the browser gets a stub, not the source)
@@ -38,20 +37,6 @@
 export function browserEntryFiles(routeTable, components) {
   /** @type {Set<string>} */
   const entries = new Set();
-  for (const page of routeTable.pages) {
-    if (page.file) entries.add(page.file);
-    for (const f of page.layouts || []) entries.add(f);
-    for (const f of page.errors || []) entries.add(f);
-    for (const f of page.loadings || []) entries.add(f);
-    for (const f of page.forbiddens || []) entries.add(f);
-    for (const f of page.unauthorizeds || []) entries.add(f);
-  }
-  if (routeTable.notFound) entries.add(routeTable.notFound);
-  if (routeTable.notFounds) {
-    for (const f of routeTable.notFounds.values()) entries.add(f);
-  }
-  if (routeTable.globalError) entries.add(routeTable.globalError);
-  if (routeTable.globalNotFound) entries.add(routeTable.globalNotFound);
   // instrumentation-client is browser-bound (imported first in the boot), so it
   // must be servable through the gate.
   if (routeTable.instrumentationClient) entries.add(routeTable.instrumentationClient);

package/src/build-epoch.js

@@ -4,7 +4,7 @@
  *
  * "Build" here is the word in its no-build sense, the one `data-webjs-build`
  * already uses: the analysis generation of a RUNNING process (its route table,
- * module graph, elision verdict, importmap, asset hashes), which changes on a
+ * module graph, component frontiers, importmap, asset hashes), which changes on a
  * deploy or a dev rebuild. Nothing is compiled, bundled, or written to disk.
  *
  * A production page render recomputed several values on every request that

package/src/cache-tags.js

@@ -134,10 +134,14 @@ export async function addKeyToTags(tags, cacheKey, ttlMs) {
  * }
  * ```
  *
+ * Next.js 16's second argument (a cache-life profile, `'max'` or
+ * `{ expire }`) is accepted and ignored: eviction is immediate (#1686).
+ *
  * @param {string} tag
+ * @param {string | { expire?: number }} [_profile]
  * @returns {Promise<void>}
  */
-export async function revalidateTag(tag) {
+export async function revalidateTag(tag, _profile) {
   if (typeof tag !== 'string' || !tag) return;
   const store = getStore();
   const keys = await readTagKeys(tag);

package/src/check/helpers.js

@@ -179,6 +179,91 @@ const HTMLELEMENT_MEMBERS = [
   'focus', 'blur', 'scrollIntoView',
 ];
 
+/**
+ * Writes to a signal field of a WebComponent class body: any `this.<name>`
+ * assignment (plain, compound, `++` / `--`) where `<name>` is a field the same
+ * class creates with `signal(` / `computed(`, either as a class-field
+ * initializer (`readonly #open = signal(false)`) or in the constructor
+ * (`this.open = signal(false)`). That creation is the one write allowed.
+ * Assigning to the field replaces the signal object: the component stays
+ * subscribed to the old one, so nothing re-renders, and the next `.get()`
+ * throws. Expects the redacted body (strings and template text blanked,
+ * holes kept).
+ *
+ * @param {string} body
+ * @returns {string[]} the offending field names, each once, `#` kept
+ */
+export function findSignalFieldWrites(body) {
+  const MAKE = String.raw`(?:signal|computed)\s*(?:<[^()]*>)?\s*\(`;
+  // Brace depth at each index, so a field initializer counts only at the
+  // class body's own level.
+  const depth = new Int32Array(body.length + 1);
+  for (let i = 0, d = 0; i < body.length; i++) {
+    if (body[i] === '{') d++;
+    else if (body[i] === '}') d--;
+    depth[i + 1] = d;
+  }
+  const fields = new Set();
+  // Find each class-level `= signal(` / `= computed(`, then read the field
+  // name from the start of its member, so a type annotation of any shape
+  // (`Signal<{ open: boolean }>`, `Signal<() => void>`, one spanning lines)
+  // sits in between.
+  const make = new RegExp(String.raw`(?<![=!<>])=(?!=)\s*` + MAKE, 'g');
+  const head = /^\s*((?:(?:public|private|protected|readonly|static|declare|override)\s+)*)(#?[A-Za-z_$][\w$]*)/;
+  let m;
+  while ((m = make.exec(body))) {
+    if (depth[m.index] !== 0) continue;
+    const h = head.exec(body.slice(memberStart(body, m.index), m.index));
+    if (h && !/\bstatic\s/.test(h[1])) fields.add(h[2]);
+  }
+  const ctor = methodBodyOf(body, 'constructor');
+  const made = new RegExp(String.raw`this\.(#?[A-Za-z_$][\w$]*)\s*=\s*` + MAKE, 'g');
+  const created = new Set();
+  while ((m = made.exec(ctor))) { fields.add(m[1]); created.add(m.index); }
+  if (!fields.size) return [];
+  const bad = new Set();
+  const write = /this\.(#?[A-Za-z_$][\w$]*)\s*(?:(\+\+|--)|(?:[-+*\/%]|\*\*|\|\||&&|\?\?|<<|>>>?|[&|^])?=(?![=>]))|(?:\+\+|--)\s*this\.(#?[A-Za-z_$][\w$]*)/g;
+  const ctorStart = ctor ? body.indexOf(ctor) : -1;
+  while ((m = write.exec(body))) {
+    const name = m[1] || m[3];
+    if (!fields.has(name)) continue;
+    // The creation in the constructor is the one allowed write.
+    if (ctorStart !== -1 && m.index >= ctorStart && m.index < ctorStart + ctor.length && created.has(m.index - ctorStart)) continue;
+    bad.add(name);
+  }
+  return [...bad];
+}
+
+/**
+ * Index where the class member holding `end` starts: just past the previous
+ * `;`, line break, or method body, skipping any of those nested inside
+ * brackets (a type annotation can hold all three).
+ * @param {string} body
+ * @param {number} end
+ * @returns {number}
+ */
+function memberStart(body, end) {
+  let nest = 0;
+  for (let i = end - 1; i >= 0; i--) {
+    const c = body[i];
+    if (c === '>' && body[i - 1] === '=') { i--; continue; }
+    if (c === ')' || c === ']' || c === '}' || c === '>') {
+      // A method body ends the previous member: `m() { ... } x = signal(0)`.
+      if (c === '}' && nest === 0) {
+        let j = i - 1;
+        for (let d = 1; j >= 0 && d; j--) d += body[j] === '}' ? 1 : body[j] === '{' ? -1 : 0;
+        if (/\)\s*$/.test(body.slice(0, j + 1))) return i + 1;
+      }
+      nest++;
+    } else if (c === '(' || c === '[' || c === '{' || c === '<') {
+      nest--;
+    } else if (nest === 0 && (c === ';' || c === '\n')) {
+      return i + 1;
+    }
+  }
+  return 0;
+}
+
 /**
  * Extract the body text of a named method from a (redacted) class body, or
  * '' if absent. Handles `async`, a TS return-type annotation, and params.

package/src/check/rules-actions.js

@@ -38,12 +38,18 @@ export function checkUseServerNeedsExtension(files, violations) {
       if (/\.server\.m?[jt]s$/.test(rel)) continue; // OK: has both markers
       const fileBase = basename(rel);
       const renamedBase = fileBase.replace(/\.(m?[jt]sx?)$/, '.server.$1');
+      // A routing file (page, layout, ...) cannot be renamed: the router
+      // matches its exact name, so `page.server.ts` would stop being a page.
+      // Next.js lets a page carry 'use server' actions; here they move out.
+      const routing = /^(?:page|layout|route|error|loading|not-found|forbidden|unauthorized|global-error|global-not-found|middleware|template|default)\.m?[jt]sx?$/.test(fileBase);
       violations.push({
         rule: 'use-server-needs-extension',
         file: rel,
         message:
           "File declares `'use server'` but its name does not match `.server.{js,ts,mts,mjs}`. The directive is silently ignored: the file is served to the browser as plain source and its exports are not RPC-callable. Code the developer expects to run on the server actually runs in the browser.",
-        fix: `Rename to ${renamedBase} (add the .server. infix before the extension)`,
+        fix: routing
+          ? `Do not rename ${fileBase}: it is a routing file. Move its server actions into their own module (modules/<feature>/actions/<name>.server.ts starting with 'use server'), export them, and import them here.`
+          : `Rename to ${renamedBase} (add the .server. infix before the extension)`,
       });
     }
   }
@@ -172,3 +178,33 @@ export function checkOneActionPerConfiguredFile(files, violations) {
     }
   }
 }
+
+/**
+ * Rule: `no-inline-use-server`.
+ *
+ * A `'use server'` directive as the first statement of a FUNCTION body,
+ * Next.js's inline server action. WebJs honours the directive only at the top
+ * of a `*.server.{js,ts}` module, so an inline one is an ordinary string: the
+ * function is not an action, runs wherever it is called, and binding it to a
+ * form throws because it has no action identity.
+ *
+ * @param {ScannedFile[]} files
+ * @param {Violation[]} violations
+ */
+export function checkNoInlineUseServer(files, violations) {
+  for (const { rel, scan } of files) {
+    // `scan` blanks comments and template bodies but keeps plain-string
+    // bodies, so the directive is visible and a mention in a comment or a
+    // template sample is not.
+    const re = /\{\s*(['"])use server\1/g;
+    const m = re.exec(scan);
+    if (!m) continue;
+    const line = scan.slice(0, m.index).split('\n').length;
+    violations.push({
+      rule: 'no-inline-use-server',
+      file: rel,
+      message: `A 'use server' directive inside a function body (line ${line}) does nothing in WebJs: the server boundary is a FILE, so this function is not a server action and runs wherever it is called. Binding it to a <form action> throws.`,
+      fix: "Move the function into its own module, e.g. modules/<feature>/actions/<name>.server.ts whose first line is 'use server', export it, and import it where it is used (a form binds it with action=${fn}).",
+    });
+  }
+}

package/src/check/rules-components.js

@@ -7,11 +7,11 @@
  * logic, and its position in the run order.
  */
 import {
-  extractWebComponentClassBodies, matchClosingBrace, parsePropEntries,
+  extractWebComponentClassBodies, matchClosingBrace, parsePropEntries, parsePropsFromObjectLiteral,
 } from '../js-scan.js';
 import {
-  isComponentFile, arrayPropUsesObject, findFieldInitializers, methodBodyOf,
-  findBrowserMemberUses,
+  isComponentFile, arrayPropUsesObject, findFieldInitializers,
+  findSignalFieldWrites, methodBodyOf, findBrowserMemberUses,
 } from './helpers.js';
 
 /**
@@ -54,35 +54,31 @@ export function checkComponentsHaveRegister(files, violations) {
 }
 
 /**
- * Rule: `no-static-properties`.
+ * Rule: `no-signal-field-assignment`.
  *
  * @param {ScannedFile[]} files  every JS/TS file in the app, raw and redacted
  * @param {Violation[]} violations  accumulator the rule pushes onto
  * @returns {void}
  */
-export function checkNoStaticProperties(files, violations) {
-  // --- 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.
+export function checkNoSignalFieldAssignment(files, violations) {
+  // --- Rule: no-signal-field-assignment ---
+  // A signal field is written through `.set()`, never by assignment, which
+  // swaps the signal object out from under the component (#1679). TypeScript
+  // `readonly` catches this where tsc runs; this rule covers plain `.js` and a
+  // forgotten `readonly`. It only sees writes inside the declaring class,
+  // which for a `#private` field is every write there can be.
   {
     for (const { rel, scan } of files) {
-      // 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;
+      if (!/class\s+\w+(?:\s*<[^{}();]*?>)?\s+extends\s+WebComponent/.test(scan)) continue;
       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 in the constructor after super(). Delete the `static properties` block and any `declare` fields for those props.',
-        });
+        for (const name of findSignalFieldWrites(body)) {
+          violations.push({
+            rule: 'no-signal-field-assignment',
+            file: rel,
+            message: `\`this.${name}\` holds a signal and is assigned to. Assignment replaces the signal object: the component stays subscribed to the old one, nothing re-renders, and the next \`.get()\` throws.`,
+            fix: `Write through the signal: \`this.${name}.set(value)\` (or \`this.${name}.set(this.${name}.get() + 1)\` for a counter), and declare the field \`readonly\` in TypeScript so the compiler catches the next one.`,
+          });
+        }
       }
     }
   }
@@ -102,13 +98,17 @@ export function checkReactivePropsNoClassField(files, violations) {
   // semantics (including `erasableSyntaxOnly: true`) every class-field declaration
   // compiles to Object.defineProperty after super() and clobbers the framework's
   // reactive accessor (silent broken re-renders). Catches `count = 0`,
-  // `count: number = 0`, `count!: number`, and `count?: number`.
+  // `count: number = 0`, `count!: number`, and `count?: number`. Props declared
+  // in Lit's `static properties` count the same as factory props, since the
+  // field clobbers the accessor either way; `declare count: number` is erased
+  // and is never flagged.
   {
     for (const { rel, scan } of files) {
-      if (!/class\s+\w+\s+extends\s+WebComponent/.test(scan)) continue;
+      if (!/class\s+\w+(?:\s*<[^{}();]*?>)?\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)) {
+        const props = new Set([...factoryProps, ...staticPropertyNames(body)]);
+        if (props.size === 0) continue;
+        for (const bad of findFieldInitializers(body, props)) {
           violations.push({
             rule: 'reactive-props-no-class-field',
             file: rel,
@@ -121,6 +121,32 @@ export function checkReactivePropsNoClassField(files, violations) {
   }
 }
 
+/**
+ * The prop names a class body declares through Lit's `static properties`,
+ * spelled as a field (with any of `override` / `readonly` / an access
+ * modifier, and an optional type annotation) or as a `static get` returning an
+ * object literal. Reads the redacted body, so a quoted key is not recovered;
+ * that only means one fewer name to check, never a false positive.
+ *
+ * @param {string} body  a class body from `extractWebComponentClassBodies`
+ * @returns {Set<string>}
+ */
+function staticPropertyNames(body) {
+  const names = new Set();
+  const mods = '(?:(?:override|readonly|public|protected)\\s+)*';
+  const field = new RegExp(`\\bstatic\\s+${mods}properties\\s*(?::[^=;{]*)?=\\s*\\{`, 'g');
+  const getter = new RegExp(`\\bstatic\\s+${mods}get\\s+properties\\s*\\(\\s*\\)[^{]*\\{\\s*return\\s*\\{`, 'g');
+  for (const re of [field, getter]) {
+    let m;
+    while ((m = re.exec(body)) !== null) {
+      const start = m.index + m[0].length;
+      const end = matchClosingBrace(body, start);
+      if (end !== -1) parsePropsFromObjectLiteral(body.slice(start, end), names);
+    }
+  }
+  return names;
+}
+
 /**
  * Rule: `array-prop-uses-array-type`.
  *
@@ -273,3 +299,82 @@ export function checkNoShadowedNativeMember(files, violations) {
     }
   }
 }
+
+/**
+ * The value a class body gives `static shadow`: `true`, `false` (an explicit
+ * `= false` or no declaration at all, the light-DOM default), or `null` when
+ * it cannot be evaluated statically (a getter, a variable, an expression).
+ * @param {string} body  string/comment-masked class body
+ * @returns {boolean | null}
+ */
+function staticShadowValue(body) {
+  if (/\bstatic\s+(?:override\s+)?get\s+shadow\b/.test(body)) return null;
+  const m = /\bstatic\s+(?:override\s+)?(?:readonly\s+)?shadow\s*(?::[^=;\n]*)?=\s*([^;\n]*)/.exec(body);
+  if (!m) return false;
+  const v = m[1].trim();
+  if (/^true\b/.test(v)) return true;
+  if (/^false\b/.test(v)) return false;
+  return null;
+}
+
+/**
+ * Rules: `static-styles-need-shadow` and `shadow-options-need-shadow`.
+ *
+ * WebJs adopts `static styles` into a SHADOW root, and `static
+ * shadowRootOptions` configures that root, but a component renders into light
+ * DOM unless it sets `static shadow = true`. Lit's habit is the opposite
+ * (shadow by default), so a Lit-shaped component declaring either one with no
+ * `static shadow = true` ships styles that never apply, or options nothing
+ * reads, with no other signal at edit time.
+ *
+ * @param {ScannedFile[]} files  every JS/TS file in the app, raw and redacted
+ * @param {Violation[]} violations  accumulator the rule pushes onto
+ * @returns {void}
+ */
+export function checkShadowOnlyStatics(files, violations) {
+  for (const { rel, scan } of files) {
+    if (!/class\s+\w+[^{]*?\s+extends\s+WebComponent/.test(scan)) continue;
+    for (const { body } of extractWebComponentClassBodies(scan)) {
+      if (staticShadowValue(body) !== false) continue;
+      // Only TOP-LEVEL members of this class, never a nested class's.
+      const top = topLevelText(body);
+      if (/\bstatic\s+(?:override\s+)?(?:readonly\s+)?(?:get\s+)?styles\b/.test(top)) {
+        violations.push({
+          rule: 'static-styles-need-shadow',
+          file: rel,
+          message:
+            '`static styles` on a light-DOM component is never applied. WebJs adopts it into a shadow root, and this component renders into light DOM (the default, unlike Lit) because it does not set `static shadow = true`.',
+          fix:
+            'Add `static shadow = true` to scope the styles in a shadow root, or drop `static styles` and style the light DOM with Tailwind utilities or a global stylesheet whose class selectors are prefixed with the tag name.',
+        });
+      }
+      if (/\bstatic\s+(?:override\s+)?(?:readonly\s+)?(?:get\s+)?shadowRootOptions\b/.test(top)) {
+        violations.push({
+          rule: 'shadow-options-need-shadow',
+          file: rel,
+          message:
+            '`static shadowRootOptions` configures a shadow root, and this component has none: it renders into light DOM (the default, unlike Lit) because it does not set `static shadow = true`, so the options are ignored.',
+          fix: 'Add `static shadow = true` so the component attaches a shadow root with these options, or remove `shadowRootOptions`.',
+        });
+      }
+    }
+  }
+}
+
+/**
+ * The text of a class body at brace depth 0, with every nested block blanked,
+ * so a member of a nested class or object literal never reads as this class's.
+ * @param {string} body
+ * @returns {string}
+ */
+function topLevelText(body) {
+  let d = 0;
+  let out = '';
+  for (let i = 0; i < body.length; i++) {
+    const c = body[i];
+    if (c === '{') { d++; out += ' '; continue; }
+    if (c === '}') { d--; out += ' '; continue; }
+    out += d === 0 ? c : (c === '\n' ? '\n' : ' ');
+  }
+  return out;
+}

package/src/check/rules-imports.js

@@ -6,11 +6,15 @@
  * in one 900-line function. Each rule keeps its original comment header, its
  * logic, and its position in the run order.
  */
-import { relative } from 'node:path';
+import { relative, dirname, sep } from 'node:path';
 import {
   redactStringsAndTemplates, redactToPlaceholders, classifyActionHole,
 } from '../js-scan.js';
 import { resolveImport } from '../module-graph.js';
+import { coreSurface, isTypeOnlyAnywhere } from '../core-exports.js';
+import { missingCoreNameFix } from '../lit-hints.js';
+import { foreignImport, foreignImportAllowed } from '../foreign-imports.js';
+import { CSS_IMPORT_FIX } from '../app-layout.js';
 import {
   hasUseServerDirective, enumerableExports, importedLocalNames, importedValueNames,
 } from './helpers.js';
@@ -31,7 +35,7 @@ import {
 export function checkNoMissingLocalImport(appDir, files, violations) {
   // --- Rule: no-missing-local-import ---
   // A named value import of a symbol an app-internal module does not export is a
-  // runtime crash (the binding is undefined) that the elision-based checks miss,
+  // runtime crash (the binding is undefined) that the graph-based checks miss,
   // so `check` can stay green while `typecheck` is red (a dropped schema table
   // orphaning a gallery module is the motivating dogfood case). Conservative by
   // construction: only app-internal specifiers resolving to a known app file,
@@ -71,11 +75,21 @@ export function checkNoMissingLocalImport(appDir, files, violations) {
         if (exp == null) continue; // not an app file, or exports not enumerable
         for (const name of names) {
           if (exp.has(name)) continue;
+          // The usual cause is the right name from the wrong module (a UI
+          // helper imported from its sibling's file), so name the app modules
+          // that do export it, spelled the way this import was (#1686).
+          const owners = [];
+          for (const f of files) {
+            if (f.abs !== target && exportsByAbs.get(f.abs)?.has(name)) owners.push(specFor(f.abs, spec, abs, appDir));
+          }
+          const elsewhere = owners.length ? ` \`${name}\` is exported by ${owners.slice(0, 3).map((o) => `\`${o}\``).join(', ')}.` : '';
           violations.push({
             rule: 'no-missing-local-import',
             file: rel,
-            message: `Imports \`${name}\` from \`${spec}\`, but that module does not export \`${name}\`. The binding is undefined at runtime and crashes on first use (often a renamed or removed export, e.g. a dropped schema table).`,
-            fix: `Add \`${name}\` to \`${spec}\`, correct the imported name, or remove the import.`,
+            message: `Imports \`${name}\` from \`${spec}\`, but that module does not export \`${name}\`. The binding is undefined at runtime and crashes on first use (often a renamed or removed export, e.g. a dropped schema table).${elsewhere}`,
+            fix: owners.length
+              ? `Import \`${name}\` from \`${owners[0]}\`.`
+              : `Add \`${name}\` to \`${spec}\`, correct the imported name, or remove the import.`,
           });
         }
       }
@@ -164,3 +178,160 @@ export function checkFormActionNotAGetAction(appDir, files, violations) {
     }
   }
 }
+
+/**
+ * Rule: `core-imports-exist`.
+ *
+ * A named import from `@webjsdev/core` (or one of its subpaths) of a name the
+ * module does not export is a load-time crash: ESM refuses to link the module
+ * with `does not provide an export named X`, which names neither the cause nor
+ * the fix. Lit muscle memory produces exactly this (`LitElement`, a decorator
+ * function, `PropertyValues` imported as a value). The rule reads the
+ * INSTALLED core's real export surface (`core-exports.js`), so a name core
+ * gains later is accepted the day it ships, and maps the miss to its WebJs fix
+ * through the `lit-hints.js` table: a type-only name gets the `import type`
+ * fix, a Lit name that will never exist gets its WebJs spelling.
+ *
+ * @param {string} appDir  absolute path to the app root
+ * @param {ScannedFile[]} files  every JS/TS file in the app, raw and redacted
+ * @param {Violation[]} violations  accumulator the rule pushes onto
+ * @returns {void}
+ */
+export function checkCoreImportsExist(appDir, files, violations) {
+  /** @type {import('../core-exports.js').CoreSurface | null | undefined} */
+  let surface;
+  // Statement position only (line start or after `;` / `}`), so an import
+  // spelled inside a plain string, which the mask keeps verbatim, is not read.
+  const IMPORT_RE = /(?:^|[;}])[ \t]*(import|export)\s+(type\s+)?([^'";]*?)\s*from\s*(['"])(@webjsdev\/core(?:\/[^'"]*)?)\4/gm;
+  for (const f of files) {
+    if (!f.content.includes('@webjsdev/core')) continue;
+    // The default mask keeps plain-string bodies (the specifier) and blanks
+    // comments and templates, so an import shown in a docs code sample or a
+    // JSDoc example is never read as a real one.
+    IMPORT_RE.lastIndex = 0;
+    let m;
+    while ((m = IMPORT_RE.exec(f.scan))) {
+      const [, kw, typeKw, clauseRaw, , spec] = m;
+      if (typeKw) continue; // `import type { ... }` is erased before load
+      if (surface === undefined) surface = coreSurface(appDir);
+      if (!surface) return;
+      const line = f.content.slice(0, m.index).split('\n').length;
+      const mod = surface.subpaths.get(spec);
+      if (!mod) {
+        if (spec === '@webjsdev/core/package.json') continue;
+        violations.push({
+          rule: 'core-imports-exist',
+          file: f.rel,
+          message: `\`${spec}\` (line ${line}) is not a subpath @webjsdev/core exports, so the import fails to resolve at load.`,
+          fix: `Import from one of: ${[...surface.subpaths.keys()].map((k) => '`' + k + '`').join(', ')}.`,
+        });
+        continue;
+      }
+      const clause = clauseRaw.trim();
+      if (kw === 'export' && clause.startsWith('*')) continue;
+      // Default import (`import x from` or `import x, { ... } from`).
+      const defMatch = kw === 'import' ? /^([A-Za-z_$][\w$]*)\s*(?:,|$)/.exec(clause) : null;
+      if (defMatch && !mod.hasDefault) {
+        violations.push({
+          rule: 'core-imports-exist',
+          file: f.rel,
+          message: `\`import ${defMatch[1]} from '${spec}'\` (line ${line}) is a default import, and ${spec} has no default export, so the module fails to load.`,
+          fix: `Use named imports: \`import { WebComponent, html } from '${spec}'\`, or a namespace import \`import * as ${defMatch[1]} from '${spec}'\`.`,
+        });
+      }
+      const brace = /\{([^}]*)\}/.exec(clause);
+      if (!brace) continue;
+      for (const part of brace[1].split(',')) {
+        const p = part.trim();
+        if (!p || /^type\s/.test(p)) continue;
+        const name = p.split(/\s+as\s+/)[0].trim();
+        if (!/^[A-Za-z_$][\w$]*$/.test(name) || mod.runtime.has(name)) continue;
+        const typeOnly = mod.types.has(name) || isTypeOnlyAnywhere(surface, name);
+        const elsewhere = typeOnly ? null : [...surface.subpaths].find(([, s]) => s.runtime.has(name));
+        violations.push({
+          rule: 'core-imports-exist',
+          file: f.rel,
+          message: typeOnly
+            ? `\`${name}\` (line ${line}) is imported as a value from ${spec}, which exports it only as a type. The type stripper keeps a plain import, so the module fails to load with "does not provide an export named ${name}".`
+            : `\`${name}\` (line ${line}) is not exported by ${spec}, so the module fails to load with "does not provide an export named ${name}".`,
+          fix: elsewhere
+            ? `Import it from \`${elsewhere[0]}\`.`
+            : missingCoreNameFix(name, { typeOnly, specifier: spec }),
+        });
+      }
+    }
+  }
+}
+
+/**
+ * Rule: `no-foreign-framework-import`.
+ *
+ * A `next/*`, `react`, `react-dom`, `lit`, `lit-html`, `lit-element`,
+ * `@lit/*` or `@lit-labs/*` import, in any form (named, default, namespace,
+ * `import type`, side-effect, `export ... from`, or a string-literal dynamic
+ * `import()`). WebJs never loads those packages; the violation names the exact
+ * `@webjsdev/*` replacement from the shared table in foreign-imports.js.
+ * `react` / `react-dom` stay allowed in a `*.server.*` module.
+ *
+ * @param {ScannedFile[]} files
+ * @param {Violation[]} violations
+ * @returns {void}
+ */
+export function checkNoForeignFrameworkImport(files, violations) {
+  // Keyword positions come from the fully-blanked view (no literal body
+  // survives, so an import written inside a string or template is never
+  // matched); the specifier is read back from the raw content at the same,
+  // length-preserved offset.
+  const reStatic = /\b(?:import|export)\b[^'";]*?\bfrom\s*(['"])/g;
+  const reBare = /\bimport\s*(['"])/g;
+  const reDynamic = /\bimport\s*\(\s*(['"])/g;
+  for (const { rel, content } of files) {
+    const masked = redactStringsAndTemplates(content, true);
+    const seen = new Set();
+    for (const re of [reStatic, reBare, reDynamic]) {
+      re.lastIndex = 0;
+      let m;
+      while ((m = re.exec(masked))) {
+        const quote = m[1];
+        const start = re.lastIndex;
+        const end = content.indexOf(quote, start);
+        if (end < 0) continue;
+        const spec = content.slice(start, end);
+        if (/\.css(?:\?.*)?$/i.test(spec) && !seen.has(spec)) {
+          seen.add(spec);
+          violations.push({
+            rule: 'no-css-import',
+            file: rel,
+            message: `Imports '${spec}', a stylesheet. WebJs has no bundler: the import fails on Node, is silently dropped on Bun, and stops the module from loading in the browser.`,
+            fix: CSS_IMPORT_FIX,
+          });
+          continue;
+        }
+        const f = foreignImport(spec);
+        if (!f || seen.has(spec) || foreignImportAllowed(spec, rel)) continue;
+        seen.add(spec);
+        violations.push({
+          rule: 'no-foreign-framework-import',
+          file: rel,
+          message: `Imports '${spec}', a ${f.framework} package. WebJs does not load ${f.framework}: the import fails in the browser and on the server, or (for Lit) loads a second component runtime beside WebJs.`,
+          fix: f.fix,
+        });
+      }
+    }
+  }
+}
+
+/**
+ * The specifier for an app module, in the style the failing import used: a
+ * `#` path from the app root for a `#` import, else a path relative to the
+ * importer.
+ * @param {string} targetAbs
+ * @param {string} styleSpec
+ * @param {string} importerAbs
+ * @param {string} appDir
+ */
+function specFor(targetAbs, styleSpec, importerAbs, appDir) {
+  if (styleSpec.startsWith('#')) return '#' + relative(appDir, targetAbs).split(sep).join('/');
+  const r = relative(dirname(importerAbs), targetAbs).split(sep).join('/');
+  return r.startsWith('.') ? r : './' + r;
+}