@nifrajs/web 5.3.0 → 5.5.0

package/src/public-dir.ts

@@ -12,12 +12,22 @@
  * Distinct from `publicPath` in `build.ts`, which is the URL prefix for content-hashed bundle chunks.
  * The names collide and the concepts do not: `publicPath` never covers user-authored files.
  */
+import { createHash } from "node:crypto"
 import { type FileHandle, realpath } from "node:fs/promises"
-import { extname, normalize, resolve, sep } from "node:path"
+import { normalize, resolve, sep } from "node:path"
 import { Readable } from "node:stream"
 import { parseByteRange } from "@nifrajs/core/range"
 import { pathnameOf } from "@nifrajs/core/server"
-import { isHiddenPublicPath } from "./internal/public-url.ts"
+import {
+  CONTENT_SNAPSHOT_MAX,
+  contentTags,
+  contentTypeOf,
+  ifRangeAllowsPartial,
+  isHiddenPath,
+  isNotModified,
+  lastModifiedOf,
+  streamedLastModifiedOf,
+} from "@nifrajs/core/static-file"
 import { openResolved } from "./open-resolved.ts"
 
 /** How long each subtree may be cached. Content-hashed bundle output can be immutable; a
@@ -50,65 +60,25 @@ export const IMMUTABLE = "public, max-age=31536000, immutable"
 export const ONE_DAY = "public, max-age=86400"
 
 /**
- * Media types by extension. A table rather than `Bun.file(path).type`: this handler also runs on the
- * Node and Deno adapters, where `Bun` does not exist and every hit would throw. Unknown extensions
- * (and extensionless files such as ACME tokens) are served as `application/octet-stream`, which
- * together with `nosniff` keeps the browser from guessing a more dangerous type.
- */
-export const CONTENT_TYPES: Readonly<Record<string, string>> = {
-  ".html": "text/html; charset=utf-8",
-  ".htm": "text/html; charset=utf-8",
-  ".css": "text/css; charset=utf-8",
-  ".js": "text/javascript; charset=utf-8",
-  ".mjs": "text/javascript; charset=utf-8",
-  ".cjs": "text/javascript; charset=utf-8",
-  ".json": "application/json; charset=utf-8",
-  ".map": "application/json; charset=utf-8",
-  ".webmanifest": "application/manifest+json",
-  ".txt": "text/plain; charset=utf-8",
-  ".md": "text/markdown; charset=utf-8",
-  ".csv": "text/csv; charset=utf-8",
-  ".xml": "application/xml",
-  ".rss": "application/rss+xml",
-  ".atom": "application/atom+xml",
-  ".svg": "image/svg+xml",
-  ".png": "image/png",
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".gif": "image/gif",
-  ".webp": "image/webp",
-  ".avif": "image/avif",
-  ".ico": "image/x-icon",
-  ".bmp": "image/bmp",
-  ".woff": "font/woff",
-  ".woff2": "font/woff2",
-  ".ttf": "font/ttf",
-  ".otf": "font/otf",
-  ".wasm": "application/wasm",
-  ".pdf": "application/pdf",
-  ".zip": "application/zip",
-  ".mp4": "video/mp4",
-  ".webm": "video/webm",
-  ".ogg": "audio/ogg",
-  ".mp3": "audio/mpeg",
-  ".wav": "audio/wav",
-  ".m4a": "audio/mp4",
-  ".vtt": "text/vtt; charset=utf-8",
-}
-
-/**
- * Whether a confined path crosses a hidden segment ({@link isHiddenPublicPath}). Checked on the
+ * Whether a confined path crosses a hidden segment ({@link isHiddenPath}). Checked on the
  * resolved path, so `%2e` encodings are covered, and again on the real target, so a visible name
  * linking to `.env` is refused too.
  */
-function isHiddenPath(root: string, abs: string): boolean {
-  return abs !== root && isHiddenPublicPath(abs.slice(root.length + 1))
+function hiddenUnder(root: string, abs: string): boolean {
+  return abs !== root && isHiddenPath(abs.slice(root.length + 1))
 }
 
 // Up to this many bytes are read whole through the pinned descriptor, which then closes before the
 // response leaves: on Bun a 200 KB asset is served in 0.17 ms against 0.28 ms through a node:fs
-// stream. A larger body streams, so a video holds 64 KiB per request rather than the file.
-const BUFFERED_BODY_MAX = 256 * 1024
+// stream. A larger body streams, so a video holds a stream's buffer per request rather than the file.
+const BUFFERED_BODY_MAX = CONTENT_SNAPSHOT_MAX
+// Bun.serve drops the declared length of any stream body and sends it chunked, and a Bun.file body
+// would need this descriptor open for a send nothing reports the end of. So on Bun a body up to 1 MiB
+// is read whole as well: a slow client then holds ~1 MB, against ~0.6 MB through Bun's stream sink.
+const BUN_BUFFERED_BODY_MAX = 1024 * 1024
+
+// One per process: the tag of a file served by any handler is remembered by its real path.
+const TAGS = contentTags(createHash)
 
 /** `length` bytes of `handle` from `start`; fewer when the file shrank since its stat. */
 async function readPinned(
@@ -126,35 +96,6 @@ async function readPinned(
   return offset === length ? bytes : bytes.subarray(0, offset)
 }
 
-/** HTTP dates carry second precision; comparing raw milliseconds makes every file look stale. */
-function seconds(time: number): number {
-  return Math.floor(time / 1000)
-}
-
-/**
- * `If-Range` decides whether a range request is still safe to answer partially. The only validator
- * this handler publishes is `last-modified`, so an entity-tag form can never match and the whole
- * representation is sent instead - which is the conformant outcome, not a fallback. Dates use strong
- * comparison (RFC 9110 13.1.5): a file modified since the client's copy invalidates its byte offsets.
- */
-function ifRangeMatches(value: string | null, lastModified: number | undefined): boolean {
-  if (value === null) return true
-  if (lastModified === undefined) return false
-  const item = value.trim()
-  if (item.startsWith('"') || item.startsWith("W/")) return false
-  const parsed = Date.parse(item)
-  return Number.isFinite(parsed) && seconds(parsed) === seconds(lastModified)
-}
-
-/** `If-Modified-Since` freshness. No ETag is published, so there is no `If-None-Match` precedence. */
-function isNotModified(request: Request, lastModified: number | undefined): boolean {
-  if (lastModified === undefined) return false
-  const since = request.headers.get("if-modified-since")
-  if (since === null) return false
-  const parsed = Date.parse(since)
-  return Number.isFinite(parsed) && seconds(parsed) >= seconds(lastModified)
-}
-
 /**
  * Resolve a URL pathname to an absolute path **confined** to `root`, or `undefined` if it escapes.
  *
@@ -185,6 +126,11 @@ export function resolvePublicPath(root: string, pathname: string): string | unde
  * never shadow a route. That ordering is also why a `routes/robots.txt.tsx` beats a
  * `public/robots.txt` only if the caller checks routes first; the documented precedence is that the
  * static probe runs first, so `public/` wins, and an app wanting the route should not ship both.
+ *
+ * Files up to 256 KiB carry a strong `ETag` from the exact snapshot served, matching the Node and
+ * Deno readers. Those snapshots carry `Last-Modified` only while mtime reflects their own last change.
+ * Larger files stream without an `ETag`: an open inode can change after a separate hash pass. They
+ * are dated once settled, but an `If-Range` request gets the whole file rather than spliced versions.
  */
 export function servePublicDir(
   options: ServePublicDirOptions,
@@ -195,6 +141,7 @@ export function servePublicDir(
   const hashedFiles = options.hashedFiles
   const hashed = options.cache?.hashed ?? IMMUTABLE
   const assets = options.cache?.assets ?? ONE_DAY
+  const bufferedMax = typeof Bun === "undefined" ? BUFFERED_BODY_MAX : BUN_BUFFERED_BODY_MAX
 
   return async (request: Request): Promise<Response | undefined> => {
     if (request.method !== "GET" && request.method !== "HEAD") return undefined
@@ -205,7 +152,7 @@ export function servePublicDir(
     // A production manifest can reject page routes without touching the filesystem.
     if (options.files !== undefined && !options.files.has(pathname)) return undefined
     const abs = resolvePublicPath(root, pathname)
-    if (abs === undefined || isHiddenPath(root, abs)) return undefined
+    if (abs === undefined || hiddenUnder(root, abs)) return undefined
     const [resolvedRoot, resolvedFile] = await Promise.all([
       rootReal,
       realpath(abs).catch(() => undefined),
@@ -214,7 +161,7 @@ export function servePublicDir(
       resolvedRoot === undefined ||
       resolvedFile === undefined ||
       (resolvedFile !== resolvedRoot && !resolvedFile.startsWith(resolvedRoot + sep)) ||
-      isHiddenPath(resolvedRoot, resolvedFile)
+      hiddenUnder(resolvedRoot, resolvedFile)
     ) {
       return undefined
     }
@@ -224,13 +171,15 @@ export function servePublicDir(
     // symlink; the descriptor then pins the bytes for the lifetime of the response.
     let handle: Awaited<ReturnType<typeof openResolved>> | undefined
     try {
+      let file: FileHandle
       try {
-        handle = await openResolved(resolvedFile)
+        file = await openResolved(resolvedFile)
       } catch {
         // A name refused or gone since realpath falls through, as a failed realpath does.
         return undefined
       }
-      const stat = await handle.stat()
+      handle = file
+      const stat = await file.stat()
       if (!stat.isFile()) return undefined
       const size = stat.size
       const headers = new Headers({
@@ -248,25 +197,46 @@ export function servePublicDir(
         // rendered as HTML, say). The declared type below is authoritative.
         "x-content-type-options": "nosniff",
         // Set explicitly rather than inferred from the body, so HEAD (a null body) carries it too.
-        "content-type":
-          CONTENT_TYPES[extname(resolvedFile).toLowerCase()] ?? "application/octet-stream",
+        "content-type": contentTypeOf(resolvedFile),
       })
-      const lastModified =
-        Number.isFinite(stat.mtimeMs) && stat.mtimeMs > 0 ? stat.mtimeMs : undefined
+      const snapshot = size <= CONTENT_SNAPSHOT_MAX
+      const lastModified = snapshot ? lastModifiedOf(stat) : streamedLastModifiedOf(stat)
       if (lastModified !== undefined) {
         headers.set("last-modified", new Date(lastModified).toUTCString())
       }
       const head = request.method === "HEAD"
+      const ifNoneMatch = request.headers.get("if-none-match")
+      const ifModifiedSince = request.headers.get("if-modified-since")
+      // The whole file, when tagging it had to read it: the response is then served from these bytes.
+      let whole: Uint8Array<ArrayBuffer> | undefined
+      // A HEAD or a 304 sends none of the file, so the tag remembered for this settled version
+      // answers it from the stat alone: a write since that tag would show in the stat.
+      let etag = snapshot ? TAGS.cached(resolvedFile, stat) : undefined
+      if (
+        snapshot &&
+        (etag === undefined ||
+          !(head || isNotModified(ifNoneMatch, ifModifiedSince, etag, lastModified)))
+      ) {
+        whole = await readPinned(file, 0, size)
+        etag = await TAGS.ofSnapshot(resolvedFile, stat, whole, () => file.stat())
+      }
+      if (etag !== undefined) headers.set("etag", etag)
 
-      if (isNotModified(request, lastModified)) {
+      if (isNotModified(ifNoneMatch, ifModifiedSince, etag, lastModified)) {
         headers.delete("content-type")
         return new Response(null, { status: 304, headers })
       }
 
       // Range applies to GET only (RFC 9110 section 14.2); HEAD reports the whole representation.
       const rangeHeader = head ? null : request.headers.get("range")
+      // A streamed body's date is weak: a write during the stream must never splice two versions.
       const range =
-        rangeHeader !== null && ifRangeMatches(request.headers.get("if-range"), lastModified)
+        rangeHeader !== null &&
+        ifRangeAllowsPartial(
+          request.headers.get("if-range"),
+          etag,
+          snapshot ? lastModified : undefined,
+        )
           ? parseByteRange(rangeHeader, size)
           : ({ kind: "none" } as const)
 
@@ -281,12 +251,15 @@ export function servePublicDir(
         end: number,
       ): Promise<Uint8Array<ArrayBuffer> | ReadableStream<Uint8Array>> => {
         const length = end - start + 1
-        if (length <= BUFFERED_BODY_MAX) {
-          const bytes = await readPinned(handle!, start, length)
+        if (length <= bufferedMax) {
+          const bytes =
+            whole === undefined
+              ? await readPinned(file, start, length)
+              : whole.subarray(start, start + length)
           headers.set("content-length", String(bytes.byteLength))
           return bytes
         }
-        const stream = handle!.createReadStream({ start, end })
+        const stream = file.createReadStream({ start, end })
         // FileHandle.createReadStream owns closing the descriptor after EOF/abort.
         handle = undefined
         return Readable.toWeb(stream) as unknown as ReadableStream<Uint8Array>
@@ -346,7 +319,7 @@ export function prerenderedPageReader(
     const rel = files.get(pathname)
     if (rel === undefined) return undefined
     const abs = resolve(root, rel)
-    if (!abs.startsWith(root + sep) || isHiddenPath(root, abs)) return undefined
+    if (!abs.startsWith(root + sep) || hiddenUnder(root, abs)) return undefined
     const [resolvedRoot, resolvedFile] = await Promise.all([
       rootReal,
       realpath(abs).catch(() => undefined),

package/src/router.ts

@@ -24,7 +24,8 @@ export const DATA_HEADER = "x-nifra-data"
 /**
  * Global the server injects (`createWebApp({ prerenderedPaths })`) listing the SSG-prerendered paths.
  * The client's default data fetch reads it: a soft-nav INTO a prerendered route fetches its static
- * `<path>/_data.json` (a CDN file - no worker round-trip) instead of the dynamic header-GET.
+ * `<path>/_data.json` (a CDN file - no worker round-trip) instead of the dynamic header-GET, unless
+ * the target carries a query string.
  */
 export const PRERENDERED_GLOBAL = "__NIFRA_PRERENDERED__"
 
@@ -422,13 +423,13 @@ const defaultFetchData: FetchRouteData = async (path, _match, signal, navigation
   // worker). Falls through to the dynamic header-GET on any miss (file absent, e.g. a deferred route,
   // or a stale set), so it's always safe. Non-SSG apps have no global → the dynamic path, unchanged.
   const prerendered = await prerenderedOf()
-  if (Array.isArray(prerendered)) {
-    const query = path.indexOf("?")
-    const hash = path.indexOf("#")
-    // `indexOf` rather than `replace(/[?#].*$/)`: no regex allocation or backtracking on a
-    // caller-controlled navigation path.
-    const cut = query === -1 ? hash : hash === -1 ? query : Math.min(query, hash)
-    const pathname = cut === -1 ? path : path.slice(0, cut)
+  // `indexOf` rather than a regex: no allocation or backtracking on a caller-controlled path.
+  const query = path.indexOf("?")
+  const hash = path.indexOf("#")
+  // The file was rendered without a query, so a query-bearing path renders on demand, exactly as
+  // `servePrerenderedPages` answers the same URL on a hard request.
+  if (Array.isArray(prerendered) && (query === -1 || (hash !== -1 && hash < query))) {
+    const pathname = hash === -1 ? path : path.slice(0, hash)
     if (prerenderedSetOf(prerendered).has(pathname)) {
       const staticRes = await fetch(appUrl(dataUrlFor(pathname)), { signal: signal ?? null })
       if (staticRes.ok) return readResponseData(staticRes, signal)

package/src/server-components/vite.ts

@@ -3,6 +3,10 @@ import { createRequire } from "node:module"
 import { resolve } from "node:path"
 import type * as TS from "typescript"
 import { type Plugin, version as viteVersion } from "vite"
+import {
+  CERTIFIED_COMPONENT_REACT,
+  CERTIFIED_COMPONENT_VITE,
+} from "../internal/certified-components.ts"
 import {
   compileComponentModule,
   componentReference,
@@ -102,25 +106,26 @@ export function serverComponentsPlugin(
     name: "nifra:server-components",
     enforce: "pre",
     configResolved(config) {
-      if (viteVersion !== "8.2.1")
+      if (viteVersion !== CERTIFIED_COMPONENT_VITE)
         throw new Error(
-          "[nifra/components] Use the certified Vite 8.2.1 component pipeline; Bun remains a supported server runtime",
+          `[nifra/components] Use the certified Vite ${CERTIFIED_COMPONENT_VITE} component pipeline, not ${viteVersion}; Bun remains a supported server runtime`,
         )
       if (options.adapter === "react") {
         const require = createRequire(resolve(config.root, "package.json"))
-        const versions = ["react", "react-dom", "react-server-dom-webpack"].map((name) => {
+        const packages = ["react", "react-dom", "react-server-dom-webpack"]
+        const versions = packages.map((name) => {
           try {
             // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: The compiler inspects trusted AST/package metadata and its own populated stub map; application data never supplies these values.
             return (require(`${name}/package.json`) as { version: string }).version
           } catch {
             throw new Error(
-              `[nifra/components] Install ${name}@19.2.8 for the React component pipeline`,
+              `[nifra/components] Install ${name}@${CERTIFIED_COMPONENT_REACT} for the React component pipeline`,
             )
           }
         })
-        if (versions.some((version) => version !== "19.2.8"))
+        if (versions.some((version) => version !== CERTIFIED_COMPONENT_REACT))
           throw new Error(
-            "[nifra/components] React, React DOM, and Flight must all use the matching 19.2.8 version",
+            `[nifra/components] React, React DOM, and Flight must all use the matching ${CERTIFIED_COMPONENT_REACT} version, not ${packages.map((name, index) => `${name}@${versions[index]}`).join(", ")}`,
           )
       }
     },

package/src/service-worker.ts

@@ -37,7 +37,9 @@ export interface ServiceWorkerOptions {
   /**
    * URL of a page to serve when a navigation fails and the network is unreachable. It must be a
    * static, user-independent document (a prerendered `/offline`), because every visitor gets the same
-   * bytes. Omit it and failed navigations simply fail, which is the honest default.
+   * bytes. Install fails rather than store it, or any precached URL, when the response is an error, a
+   * redirect, or marked `private` or `no-store`. Omit it and failed navigations simply fail, which is
+   * the honest default.
    */
   readonly offlineUrl?: string
   /**
@@ -115,10 +117,35 @@ const OWN_URLS = new Set(PRECACHE)
 const OWN = { cacheName: CACHE }
 const OFFLINE = ${offline === undefined ? "null" : JSON.stringify(offline)}
 
+// Whether every visitor may be served these bytes from this cache. CacheStorage itself ignores
+// Cache-Control, and a redirect can land one visitor's page under a shared URL.
+const shareable = (response) =>
+  response.ok &&
+  response.type === "basic" &&
+  !response.redirected &&
+  !(response.headers.get("cache-control") ?? "")
+    .split(",")
+    .some((directive) => /^\\s*(?:no-store|private)\\s*(?:=|$)/i.test(directive))
+
 self.addEventListener("install", (event) => {
-  // Take over as soon as the new assets are stored; the activate handler drops the old cache, so
-  // waiting would only serve stale bytes for longer.
-  event.waitUntil(caches.open(CACHE).then((c) => c.addAll(PRECACHE)).then(() => self.skipWaiting()))
+  // Every response is checked before any is stored, so a refused one leaves this build's cache
+  // empty and the install failed, as addAll would on an error status. Take over as soon as the new
+  // assets are stored; the activate handler drops the old cache, so waiting would only serve stale
+  // bytes for longer.
+  event.waitUntil(
+    Promise.all(
+      PRECACHE.map((url) =>
+        fetch(url).then((response) => {
+          if (shareable(response)) return response
+          throw new TypeError("[nifra/web] not precached, the response is not shareable: " + url)
+        }),
+      ),
+    )
+      .then((responses) =>
+        caches.open(CACHE).then((c) => Promise.all(responses.map((r, i) => c.put(PRECACHE[i], r)))),
+      )
+      .then(() => self.skipWaiting()),
+  )
 })
 
 self.addEventListener("activate", (event) => {
@@ -156,11 +183,7 @@ self.addEventListener("fetch", (event) => {
     caches.match(request, OWN).then((hit) => {
       if (hit !== undefined) return hit
       return fetch(request).then((response) => {
-        const cacheable =
-          response.ok &&
-          response.type === "basic" &&
-          !(response.headers.get("cache-control") ?? "").includes("no-store")
-        if (cacheable) {
+        if (shareable(response)) {
           const copy = response.clone()
           void caches.open(CACHE).then((c) => c.put(request, copy))
         }

package/src/vite.ts

@@ -19,6 +19,7 @@ import {
 } from "node:http"
 import { dirname, isAbsolute, join, relative, resolve as resolvePath, sep } from "node:path"
 import { singleCopyPackageNames } from "@nifrajs/core/single-copy"
+import { isHiddenPath } from "@nifrajs/core/static-file"
 import { CLIENT_BATCH_MAX_BYTES } from "./dev-client.ts"
 import { DEV_REQUEST_ID_HEADER, DEV_SERVER_FILES } from "./dev-feed.ts"
 import { listenOrExplain } from "./dev-port.ts"
@@ -33,7 +34,6 @@ import {
   formatIdentityParityFindings,
   identityParityHeadline,
 } from "./internal/parity.ts"
-import { isHiddenPublicPath } from "./internal/public-url.ts"
 import { vitePublicEnvPrefix } from "./internal/server-boundary.ts"
 import { importVite } from "./internal/vite-import.ts"
 import { normalizeRolldownPlugins } from "./internal/vite-plugin-compat.ts"
@@ -473,12 +473,12 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
     }
     const file = resolvePath(publicDir, rel)
     if (!file.startsWith(publicDir + sep) || !existsSync(file)) return false
-    if (isHiddenPublicPath(rel)) return true
+    if (isHiddenPath(rel)) return true
     // A visible name linking to a hidden file is refused too, as `servePublicDir` refuses it.
     try {
       const real = realpathSync(file)
       const realRoot = realpathSync(publicDir)
-      return real.startsWith(realRoot + sep) && isHiddenPublicPath(real.slice(realRoot.length + 1))
+      return real.startsWith(realRoot + sep) && isHiddenPath(real.slice(realRoot.length + 1))
     } catch {
       return false
     }

package/src/zones.ts

@@ -170,7 +170,11 @@ export interface ZoneConfig {
   readonly backend?: readonly string[]
   /** App-relative folders or files holding frontend code, beside `frontend/`. */
   readonly frontend?: readonly string[]
-  /** App-relative folders or files holding code both sides import, beside `shared/`. */
+  /**
+   * App-relative folders or files holding code both sides import, beside `shared/`. Unlike the other
+   * sides, an entry may sit inside `frontend/` or `backend/`: a module there that both sides import
+   * stays where it is, held to the shared rules (it may import only shared code and packages).
+   */
   readonly shared?: readonly string[]
 }
 
@@ -258,8 +262,15 @@ export function parseZoneConfig(value: unknown, source: string): ZoneConfig {
       if (folder.split("/").includes("..")) fail(`"${side}" entry "${entry}" may not contain ".."`)
       if (/[*?[\]{}!]/.test(folder))
         fail(`"${side}" entry "${entry}" must be a plain path (a trailing "/**" is allowed)`)
-      if (RESERVED_FOLDERS.has(top) || top.startsWith(".nifra"))
-        fail(`"${side}" entry "${entry}" is inside ${top}/, which already has its own rules`)
+      const sharedInSide =
+        side === "shared" && (top === "frontend" || top === "backend") && folder !== top
+      if ((RESERVED_FOLDERS.has(top) && !sharedInSide) || top.startsWith(".nifra"))
+        fail(
+          `"${side}" entry "${entry}" is inside ${top}/, which already has its own rules` +
+            (top === "frontend" || top === "backend"
+              ? `; only a "shared" entry may name a path inside ${top}/`
+              : ""),
+        )
       const other = owner.get(folder)
       if (other !== undefined && other !== side)
         fail(`"${folder}" is listed as both ${other} and ${side}; a path has one side`)
@@ -587,11 +598,22 @@ export function createZoneClassifier(options: ZoneClassifierOptions): ZoneClassi
         if (suffix === "shared") return { zone: "shared" }
         return { zone: "route-frontend" }
       }
-      const configured = ZONE_FOLDERS[top] === undefined ? configuredPath(rel) : undefined
-      const folder = ZONE_FOLDERS[top] ?? configured?.[1]
+      // Inside a reserved folder only a "shared" entry can match: the parser refuses the others there.
+      const configured = configuredPath(rel)
+      const folder = configured?.[1] ?? ZONE_FOLDERS[top]
       if (folder !== undefined) {
         if (suffix === undefined || suffix === folder) return { zone: folder }
         if (suffix === "fn" && folder === "backend") return { zone: "fn" }
+        // Code both sides import may live beside the side that wrote it. Shared code may import only
+        // shared code and packages, so the declaration narrows what the file may reach, never widens it.
+        // A file "nifra.zones" lists by name has that side; its suffix cannot contradict it.
+        if (
+          suffix === "shared" &&
+          (folder === "frontend" || folder === "backend") &&
+          top !== "public" &&
+          configured?.[0] !== rel
+        )
+          return { zone: "shared" }
         const where =
           configured === undefined
             ? `sits in ${top}/`