diff --git a/.agents/skills/webjs/SKILL.md b/.agents/skills/webjs/SKILL.md
index a79f216a0..a912c6560 100644
--- a/.agents/skills/webjs/SKILL.md
+++ b/.agents/skills/webjs/SKILL.md
@@ -116,6 +116,7 @@ Find the right export fast. Load the linked reference for full examples.
 - `notFound()` / `redirect(url[, status])` control-flow throws (page/layout/action only, NOT `route.ts`). `forbidden()` / `unauthorized()` render the nearest boundary.
 - `Suspense({fallback, children})` page-level streaming; `<webjs-suspense>` component-level streaming.
 - `optimistic()` optimistic UI; `navigate(url)` / `revalidate(url?)` client-router control; `connectWS` / `richFetch`.
+- `asset(path)` content-hashes a `public/` url so a deploy cannot serve stale bytes (`href=${asset('/public/app.css')}`), served `immutable` for a year. Page / layout / metadata route only, inside the render function. See `references/built-ins.md`.
 - Types: `Metadata`, `PageProps<R>`, `LayoutProps<R>`, `RouteHandlerContext<R>`, `WebjsConfig`.
 - `@webjsdev/core/server`: `renderToString` / `renderToStream` (Node side).
 - `@webjsdev/core/directives`: `repeat`, `unsafeHTML` (trusted only), `live`, `keyed`, `guard`, `cache`, `until`, `watch(signal)`, `ref` / `createRef`, `asyncAppend` / `asyncReplace`, `templateContent`. `Task` / `TaskStatus` live at `@webjsdev/core/task`, context (`createContext` / `ContextProvider` / `ContextConsumer`) at `/context`. See `references/components.md` for the directive table + Task + context.
diff --git a/.agents/skills/webjs/references/built-ins.md b/.agents/skills/webjs/references/built-ins.md
index e554513b8..275d11ee4 100644
--- a/.agents/skills/webjs/references/built-ins.md
+++ b/.agents/skills/webjs/references/built-ins.md
@@ -82,7 +82,18 @@ export const revalidate = 60;   // cache this page's HTML for 60s
 
 ### Content-hash asset URLs and conditional GET
 
-Both are automatic, prod-focused, and need no config. In production every served module and `public/` asset gets a per-file `?v=<hash>` and `Cache-Control: public, max-age=31536000, immutable`, so a returning client fetches a changed file only when its bytes change. Every cacheable response also carries a weak `ETag`, and a repeat request with a matching `If-None-Match` gets a `304 Not Modified` with no body. Unstorable (`no-store`) and streamed responses are excluded from the ETag path. A `private` response IS validated: `private` forbids SHARED storage, not validation, and the ETag hashes that response's own body, so two users with different bodies get different ETags and neither can match the other's, while two users with identical bodies are asking about identical bytes, where a 304 discloses nothing (#1140). That is what keeps the client router's partial responses cheap on a page that opted into caching; a default `no-store` page has nothing to validate either way. Dev is byte-faithful (no hashing).
+Both are automatic, prod-focused, and need no config. In production every served MODULE gets a per-file `?v=<hash>`, and a `?v=`-carrying request is answered `Cache-Control: public, max-age=31536000, immutable`, so a returning client fetches a changed file only when its bytes change.
+
+A `public/` asset you reference yourself is opt-in, via `asset()` (#1194):
+
+```ts
+import { html, asset } from '@webjsdev/core';
+html`<link rel="stylesheet" href=${asset('/public/app.css')}>`
+```
+
+That emits `/public/app.css?v=<hash>` in production and gets the immutable year; the same url un-marked gets a ~1h cap and can serve stale bytes from a CDN after a deploy until something purges it. `asset()` resolves on the server; the browser has no resolver and returns the path unchanged. Call it from a PAGE, LAYOUT, or metadata route, which render only on the server. Inside a component that ships to the browser it silently costs you the caching: hydration is a full client re-render, so the bare path overwrites the hashed one and the asset downloads twice. The url stays valid either way, which is why this is a convention rather than a check rule. Under `webjs.basePath`, include the prefix yourself (`asset('/app/public/x.css')`): the framework base-path-prefixes only the urls it emits, so an author-written url is already yours to prefix. Two more constraints: call it INSIDE the render function, because a module-scope call is a side effect the elision analyser reads as client work and it ships the whole module; and mark only files that change with a DEPLOY, because the hash is memoized for the process lifetime, so a `public/` file rewritten in place at runtime would keep its old url while being served `immutable` for a year. Off in dev, so dev output is byte-identical. Only `public/` paths resolve; anything else (and a path that fails to resolve) is returned untouched.
+
+It is opt-in rather than automatic because only the author knows which urls are the REQUEST. Do NOT mark a `rel="preload"` hint whose asset is actually fetched by CSS `url()`: the preload cache is keyed on the full url, so a versioned hint can never satisfy the unversioned request the stylesheet makes, and the file is fetched twice. Mark the thing that fetches, not the hint. Every cacheable response also carries a weak `ETag`, and a repeat request with a matching `If-None-Match` gets a `304 Not Modified` with no body. Unstorable (`no-store`) and streamed responses are excluded from the ETag path. A `private` response IS validated: `private` forbids SHARED storage, not validation, and the ETag hashes that response's own body, so two users with different bodies get different ETags and neither can match the other's, while two users with identical bodies are asking about identical bytes, where a 304 discloses nothing (#1140). That is what keeps the client router's partial responses cheap on a page that opted into caching; a default `no-store` page has nothing to validate either way. Dev is byte-faithful (no hashing).
 
 **A page's ETag is only useful if the page renders the same bytes twice.** The ETag is a hash of the response body, so any per-render-varying value anywhere in the document defeats it: a `Date.now()`, a `Math.random()`, an id from a module-scope counter (which never resets in a long-lived server), or a CSP nonce. The failure is silent and total. The page renders correctly, every content assertion still passes, the header is still present, and the only symptom is that no `If-None-Match` ever matches, so every revalidation ships the whole document instead of an empty 304. A page under CSP is excluded from the server HTML cache for exactly this reason (the nonce must differ per response). If a page opts into a public `Cache-Control`, guard it with a test that renders the page twice, through its layout, and asserts the two outputs are byte-identical.
 
diff --git a/.agents/skills/webjs/references/service-worker.md b/.agents/skills/webjs/references/service-worker.md
index 11bebb7a8..598a1c24d 100644
--- a/.agents/skills/webjs/references/service-worker.md
+++ b/.agents/skills/webjs/references/service-worker.md
@@ -40,7 +40,9 @@ With WebJs's CSP enabled (`webjs.csp` in package.json), stamp the nonce on the s
 Registered from `/sw.js`, the worker's scope is the site root (`/`), so it sees every navigation and same-origin asset request. Your worker file lives at `public/sw.js`, and although most `public/*` assets serve at `/public/<name>`, the framework serves this one (and `public/offline.html`) at the SITE ROOT with a `Service-Worker-Allowed: /` header, so `register('/sw.js')` resolves to a 200 and the worker controls the whole origin.
 
 - **Navigations are network-first.** The worker tries the network first, so the user sees fresh server-rendered HTML, and it caches each successful page (the SSR shell). When the network fails, it serves the cached page if you have visited it, otherwise `/offline.html`. Network-first means the cache never makes a page go stale; it is purely an offline safety net.
-- **Static assets are stale-while-revalidate.** Same-origin modules (the per-file ESM the no-build runtime serves), the framework runtime under `/__webjs/core/`, vendor bundles under `/__webjs/vendor/`, and `public/` assets are served from cache when present and refreshed in the background. In production these URLs carry a `?v=<hash>` content fingerprint, so a changed file gets a new URL and the cache can never serve stale bytes.
+- **Static assets are stale-while-revalidate.** Same-origin modules (the per-file ESM the no-build runtime serves), the framework runtime under `/__webjs/core/`, vendor bundles under `/__webjs/vendor/`, and `public/` assets are served from cache when present and refreshed in the background. In production the framework-emitted URLs (modules, the core runtime, vendor bundles) carry a `?v=<hash>` content fingerprint automatically, so a changed file gets a new URL and the cache cannot serve stale bytes for those.
+
+  A `public/` asset is the exception, and it matters most here. Its URL is fingerprinted only when you mark it with `asset()` (`href=${asset('/public/app.css')}`, see `built-ins.md`). An un-marked `public/` URL is stable across deploys, so the worker keeps serving the CACHED copy and revalidates in the background, which means the first load after a deploy renders the OLD bytes. Do not rely on the worker's cache version to save you: it is derived from the deploy build id, which is a deploy fingerprint rather than a per-file content hash, so a deploy that only changes a `public/` file need not change it. Mark any `public/` asset whose bytes change with `asset()`.
 
 **Never cached:** non-GET requests (writes), cross-origin requests, the action RPC endpoint (`/__webjs/action/`), and the dev-only `/__webjs/events` (SSE) and `/__webjs/reload.js`. Keeping writes and RPC off the cache means the worker can never serve a stale mutation result or replay a POST, so correctness is unaffected whether the worker is active or not.
 
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 3f0ffbde5..25e2b2244 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -140,6 +140,16 @@ jobs:
       # silently vanish on the other. Asserts both directions.
       - name: SSR comment and raw-text handling on Bun
         run: bun test/bun/comment-not-an-element.mjs
+      # asset() url resolution on Bun (#1194): the helper reads the file
+      # synchronously, hashes it with node:crypto, and compares node:path
+      # containment to decide whether a url may be fingerprinted at all. A
+      # divergence would either hand the two runtimes different urls for one
+      # file (thrashing every client's immutable cache across a mixed fleet) or
+      # weaken the gate that keeps a private file from being hashed and
+      # published. Asserts the hash, the fragment split, verdict-independence,
+      # and the traversal refusals.
+      - name: asset() url resolution on Bun
+        run: bun test/bun/asset-url.mjs
       # Dev hot reload on Bun (#514): start `webjs dev` under Bun, edit a
       # re-imported route module, and assert the response updates with NO manual
       # restart. The CLI re-execs under `bun --hot` on Bun (vs `node --watch` on
diff --git a/AGENTS.md b/AGENTS.md
index faaf9649e..ba72e77e0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -199,7 +199,7 @@ import { html, css, WebComponent, prop, render } from '@webjsdev/core';
 import { renderToString } from '@webjsdev/core/server';
 ```
 
-The bare `@webjsdev/core` specifier resolves to a BROWSER bundle dropping server-only modules (`render-server.js`, `setCspNonceProvider`); `renderToString` / `renderToStream` live at `@webjsdev/core/server` for Node-side consumers.
+The bare `@webjsdev/core` specifier resolves to a BROWSER bundle dropping server-only modules (`render-server.js`, `setCspNonceProvider`, `setAssetUrlProvider`); `renderToString` / `renderToStream` live at `@webjsdev/core/server` for Node-side consumers.
 
 | Export | Purpose |
 |---|---|
@@ -213,6 +213,7 @@ The bare `@webjsdev/core` specifier resolves to a BROWSER bundle dropping server
 | `forbidden()` / `unauthorized()` | Throw to return 403 / 401 (#848, Next 15/16 parity). Renders the nearest `forbidden.{js,ts}` / `unauthorized.{js,ts}` boundary (innermost wins), else a default page, from a page/layout render OR a page `action` (the no-JS write path). `forbidden()` for an authenticated user lacking permission, `unauthorized()` for a request that is not authenticated. Same control-flow-throw model as `notFound()`: NOT for a `route.ts` handler, and inside a `'use server'` RPC action return an `ActionResult` for an auth failure instead (a raw throw there is a generic 500, like `notFound()`/`redirect()`). |
 | `Suspense({fallback, children})` | Page/region-level streaming boundary (a value in a hole). `repeat` keyed-list directive is also re-exported. |
 | `<webjs-suspense .fallback=${html\`…\`}>` | Component-level streaming boundary element (#471): wraps one or more components, flushes `.fallback` on the first byte, streams the resolved content in (concurrently across boundaries, progressively on soft nav). The renderer-recognized opt-in for SLOW async-render data. |
+| `asset(path)` | Content-hash a `public/` asset url so a deploy cannot serve stale bytes: `href=${asset('/public/app.css')}` emits `?v=<hash>` and is served `immutable` for a year (#1194). Prod-only, `public/` paths only. Use it in a PAGE, LAYOUT, or metadata route, not inside a component that ships: hydration re-renders on the client where there is no resolver, so the hashed url is swapped for the bare path and the asset is fetched twice. Call it inside the render function, since a module-scope call is a side effect that ships the module. Mark only files that change with a DEPLOY (the hash is memoized for the process lifetime). Opt-in on purpose: do NOT mark a `rel=preload` hint whose asset is fetched by CSS `url()`, or the preload can never match. |
 | `connectWS(url, handlers)` / `richFetch<T>` | Client WebSocket (auto-reconnect, queued sends); content-negotiated rich-type fetch. |
 | `navigate(url, opts?)` / `revalidate(url?)` | Programmatic client-router nav; evict the BROWSER snapshot cache. |
 | `optimistic(signal, value, action)` / `optimistic(host, { source, update })` | Imperative: set `signal` immediately, run `action`, roll back on error. Declarative (preferred): queue optimistic updates with auto-release via `.add(payload, promise?)`. See `references/client-router-and-streaming.md`. |
diff --git a/examples/blog/app/layout.ts b/examples/blog/app/layout.ts
index 81135cd6d..cab72c7a8 100644
--- a/examples/blog/app/layout.ts
+++ b/examples/blog/app/layout.ts
@@ -1,4 +1,4 @@
-import { html, cspNonce, type Metadata, type LayoutProps } from '@webjsdev/core';
+import { html, cspNonce, asset, type Metadata, type LayoutProps } from '@webjsdev/core';
 import '#components/theme-toggle.ts';
 
 const navLink = (href: string, label: string) => html`
@@ -135,7 +135,7 @@ export default function RootLayout({ children }: LayoutProps) {
         }
       });
     </script>
-    <link rel="stylesheet" href="/public/tailwind.css">
+    <link rel="stylesheet" href=${asset('/public/tailwind.css')}>
     <style>
       :root {
         color-scheme: light dark;
diff --git a/framework-dev.md b/framework-dev.md
index 2e62894a4..88f392e1a 100644
--- a/framework-dev.md
+++ b/framework-dev.md
@@ -49,7 +49,14 @@ The purge is zone-wide rather than a path list: all four hostnames (`webjs.dev`,
   cmp /tmp/o /tmp/e && echo fresh || echo stale
   ```
 
-The permanent fix for the assets themselves is a content hash in the url, the way the framework already fingerprints module imports and its own emitted urls (`?v=`, #243). `tailwind.css` and the brand marks are referenced by hand-written urls in `website/app/layout.ts` and `website/lib/design/brand.ts`, which that machinery never sees, so they stay on stable urls and depend on this purge. Fingerprinting them would retire the dependency; the workflow stays worthwhile as the safety net for anything else on a stable url.
+The assets that actually caused those incidents no longer depend on this purge. `tailwind.css`, the brand lockups and marks, and the highlight script are marked with `asset()` (#1194) in `website/app/layout.ts`, `website/lib/design/brand.ts`, and `website/app/brand/page.ts` (whose images AND download links are marked, so a designer cannot download the previous drawing while the thumbnail above it shows the new one), so each carries a `?v=<content-hash>` and is served `immutable` for a year. `examples/blog/app/layout.ts` marks its stylesheet for the same reason, since `example-blog.webjs.dev` sits in the same Cloudflare zone. New bytes mean a new url, which no cache can serve stale.
+
+Some urls are deliberately NOT marked, and that is the point of an opt-in helper rather than an automatic rewrite:
+
+- the three **font preloads**, because the real request comes from `@font-face url()` in the compiled stylesheet and CSS `url()` is not rewritten. The preload cache is keyed on the full url, so a versioned hint could never satisfy the unversioned request, and each font would be fetched twice.
+- the **favicons**, whose hrefs are parsed literally by the SEO repo-health tests guarding the #1088 size bug, and where fingerprinting buys almost nothing.
+
+The purge workflow therefore STAYS as the safety net for everything still on a stable url (an asset referenced from CSS, a `srcset` candidate, an un-marked path), and it remains the way to clear the edge after a deploy that changes one of those.
 
 ---
 
@@ -116,6 +123,11 @@ npm runs first; if it fails (auth, network, transient registry error), the GitHu
 
 The workflow uses `NPM_TOKEN` (repo secret) and the auto-provisioned `GITHUB_TOKEN`. Free for public repos.
 
+**When `server` or the scaffold consumes a NEW `@webjsdev/core` export, core MUST publish first.** `packages/server/src/dev.js` and `context.js` import core symbols statically (`setAssetUrlProvider`, `setCspNonceProvider`), and `webjs create` emits an app that imports them too. A server published against an older core dies at module load with `does not provide an export named ...`, and a cli published first makes every freshly scaffolded app 500 on every route. Two things force the right order:
+
+1. **Give `changelog/core/<version>.md` the EARLIEST `date:` of the batch.** The publish loop sorts by that timestamp ASC, and the tie-break on equal timestamps is filename DESC, which would publish `server` BEFORE `core`. The loop is `set -e` sequential, so core-first is also the fail-safe order: if core's publish fails, nothing after it ships and no skew can reach the registry.
+2. **Bump the declared range in the same release PR.** `packages/server/package.json` still declares `"@webjsdev/core": "^0.7.1"`, which every published core satisfies, so npm cannot catch the skew. Raising it to the version that actually carries the new export makes the resolver enforce the coupling permanently, independent of publish order. The scaffold cannot be range-protected (it installs `@latest`), so it relies on the ordering above.
+
 **Update the global CLI after the publish lands.** The maintainer scaffolds and dogfoods with the globally installed `webjs` CLI, which lags a release until refreshed. So once `release.yml` has published (verify `npm view @webjsdev/cli version` matches the released version), refresh the global CLI on every manager: `npm update -g webjsdev`, `bun add -g webjsdev`, and `mise use -g npm:webjsdev@latest`. Run them AFTER the publish, never at merge time (they pull the LATEST PUBLISHED version). The `mise use` line is the one that actually moves a mise-shimmed `webjs` (a shim on PATH ahead of the npm/bun globals); verify with `mise which webjs`. This is reminded automatically by the `.claude/hooks/release-global-update.sh` PostToolUse hook, which fires when a `chore/release-*` PR merges (escape hatch `WEBJS_NO_RELEASE_GLOBAL_UPDATE=1`, regression test `test/hooks/release-global-update.test.mjs`).
 
 ---
diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index c54dafe19..9ea28741d 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -1148,7 +1148,7 @@ ${uiThemeRaw}
     // or shed the whole gallery at once with `gallery:clear`.
     await copyGallery(appDir);
 
-  await writeFile(join(appDir, 'app', 'layout.ts'), `import { html, cspNonce } from '@webjsdev/core';
+  await writeFile(join(appDir, 'app', 'layout.ts'), `import { html, cspNonce, asset } from '@webjsdev/core';
 import '#components/theme-toggle.ts';
 
 /**
@@ -1226,9 +1226,16 @@ export default function RootLayout({ children }: { children: unknown }) {
          public/tailwind.css by css:build (run automatically by the dev and start
          tasks; in dev it is also recompiled on request when a source changes, so
          it never goes stale). A real stylesheet, so the app is fully styled with
-         JavaScript DISABLED (no in-browser compile). -->
+         JavaScript DISABLED (no in-browser compile).
 
-    <link rel="stylesheet" href="/public/tailwind.css">
+         asset() adds a content hash in production (/public/tailwind.css?v=...)
+         and the framework then serves it immutable for a year, so a deploy that
+         changes the CSS changes the url and no browser or CDN can serve the old
+         bytes. Mark the thing that FETCHES: do not wrap a <link rel="preload">
+         whose asset is really fetched by an @font-face url() in the CSS, or the
+         preload can never match the request and the file downloads twice. -->
+
+    <link rel="stylesheet" href=\${asset('/public/tailwind.css')}>
     <style>
       /* Design tokens: ONE definition per colour via light-dark(LIGHT, DARK), so
          a palette change lands in a single place (DRY). The token NAMES are
diff --git a/packages/cli/templates/gallery/app/features/caching/page.ts b/packages/cli/templates/gallery/app/features/caching/page.ts
index 841ed7ad1..2d2c94cf8 100644
--- a/packages/cli/templates/gallery/app/features/caching/page.ts
+++ b/packages/cli/templates/gallery/app/features/caching/page.ts
@@ -3,9 +3,9 @@
 // changes once per window: reload inside 10s and it is identical, reload after
 // and it refreshes. SAFETY: only cache a page that is identical for every
 // visitor (no cookies(), no session, no per-user data), since the key is the URL
-// alone. For per-query reads use cache() + tags with revalidateTag; for assets
-// use HTTP Cache-Control + ETag (conditional GET).
-import { html } from '@webjsdev/core';
+// alone. For per-query reads use cache() + tags with revalidateTag; for a
+// public/ asset use asset(), demonstrated at the bottom of this page.
+import { html, asset } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
 import { pageHeading, lede } from '#lib/utils/ui.ts';
 import '#modules/caching/components/cache-buster.ts';
@@ -46,5 +46,27 @@ export default function CachingExample() {
       copy until the window elapses.
     </p>
     <cache-buster></cache-buster>
+
+    <h2 class="mt-8 mb-2 font-semibold">Caching a public/ asset</h2>
+    <p class="mb-2">
+      A file in <code>public/</code> sits at a stable url, so after a deploy a
+      browser or CDN can keep serving the PREVIOUS bytes until its cache
+      expires. Wrap the url in <code>asset()</code> and it gains a content hash,
+      which the framework then serves <code>immutable</code> for a year:
+    </p>
+    <pre class="mb-2 overflow-x-auto rounded-md bg-muted p-3 text-sm"><code>&lt;link rel="stylesheet" href=\${asset('/public/tailwind.css')}&gt;</code></pre>
+    <p class="mb-2">
+      This app's stylesheet resolves to
+      <code class="font-mono text-primary">${asset('/public/tailwind.css')}</code>
+      (the hash appears in production only, so dev output stays byte-identical).
+      New bytes mean a new url, so a stale copy can never be served.
+    </p>
+    <p class="text-muted-foreground text-sm">
+      Mark the thing that FETCHES, not a hint. Wrapping a
+      <code>&lt;link rel="preload"&gt;</code> whose asset is really fetched by an
+      <code>@font-face url()</code> in your CSS would version the hint but not
+      the request, so the preload could never match and the file would download
+      twice.
+    </p>
   `;
 }
diff --git a/packages/cli/templates/public/sw.js b/packages/cli/templates/public/sw.js
index b1ab96255..5ea66821c 100644
--- a/packages/cli/templates/public/sw.js
+++ b/packages/cli/templates/public/sw.js
@@ -15,8 +15,17 @@
  *   - Same-origin static assets (the per-file ESM modules, the framework
  *     runtime under /__webjs/core/, vendor bundles, public assets) are
  *     stale-while-revalidate, so a repeat visit works offline. In production
- *     these URLs carry a ?v=<hash> content fingerprint, so a changed file gets
- *     a new URL and the cache can never serve stale bytes.
+ *     the FRAMEWORK-emitted URLs (modules, the core runtime, vendor bundles)
+ *     carry a ?v=<hash> content fingerprint automatically, so a changed file
+ *     gets a new URL and the cache cannot serve stale bytes for those.
+ *
+ *     A public/ asset is the exception: its URL is fingerprinted only when you
+ *     mark it with asset() (href=${asset('/public/app.css')}). An un-marked
+ *     public/ URL is stable across deploys, so this worker serves the CACHED
+ *     copy and revalidates behind it, and the first load after a deploy shows
+ *     the OLD bytes. The cache version below will not necessarily rescue you,
+ *     because the build id it derives from is a deploy fingerprint rather than
+ *     a per-file content hash. Mark any public/ asset whose bytes change.
  *
  * Versioning ties to the deploy. The page registers this worker as
  * `/sw.js?v=<data-webjs-build>` (the importmap build id), so a new deploy
diff --git a/packages/cli/templates/scripts/clear-gallery.mjs b/packages/cli/templates/scripts/clear-gallery.mjs
index 2902cd61f..864025131 100644
--- a/packages/cli/templates/scripts/clear-gallery.mjs
+++ b/packages/cli/templates/scripts/clear-gallery.mjs
@@ -173,7 +173,7 @@ export default function Home() {
 }
 
 function MINIMAL_LAYOUT() {
-  return `import { html } from '@webjsdev/core';
+  return `import { html, asset } from '@webjsdev/core';
 
 /**
  * Root layout: the ONLY file that writes the document shell. It links the
@@ -194,7 +194,11 @@ export const metadata = { icons: '/public/favicon.svg' };
 export default function RootLayout({ children }: { children: unknown }) {
   return html\`
     <meta name="color-scheme" content="light dark">
-    <link rel="stylesheet" href="/public/tailwind.css">
+    <!-- asset() content-hashes the url in production, so a deploy that changes
+         the CSS changes the url and the framework serves it immutable for a
+         year. Without it this stable url can serve the PREVIOUS stylesheet
+         from a CDN or a service-worker cache after a deploy. -->
+    <link rel="stylesheet" href=\${asset('/public/tailwind.css')}>
     <style>
       html, body { margin: 0; }
       body {
diff --git a/packages/core/AGENTS.md b/packages/core/AGENTS.md
index cb61d4824..9d8db6715 100644
--- a/packages/core/AGENTS.md
+++ b/packages/core/AGENTS.md
@@ -48,6 +48,7 @@ the same output in all three.
 | `action-stream.js` | Streaming RPC wire protocol (#489), isomorphic. The length-prefixed frame format (`[type:1][length:4 BE][payload]`, CHUNK / END / ERROR frame types, `STREAM_CONTENT_TYPE` = `application/vnd.webjs+stream`) shared by the server (which frames a streamed action result, `encodeFrame`) and the generated client stub (which decodes the body into an async iterable, `createFrameDecoder`, a stateful decoder buffering partial frames across network reads). Pure byte ops, no DOM / `node:*`, so it is safe in the browser bundle and on the server alike. An action that returns a `ReadableStream` / async iterable / async generator streams its chunks over one RPC response; each chunk is rich-serialized so a `Date` / `Map` / `BigInt` round-trips. Re-exported from `index.js` + `index-browser.js` |
 | `action-seed-client.js` | Client consumer for SSR action-result seeding (#472): `takeSeed(hash, fn, argsKey)` (consume-once lookup, `SEED_MISS` sentinel) + `scanSeeds(root)` (ingest the page-level `#__webjs-seeds` JSON block and per-element `[data-webjs-seed]` carriers, stripping them). The generated RPC stub calls `takeSeed` before its `fetch`, so an async-render component's first client call resolves from the SSR seed instead of a hydration round-trip; `router-client.js`'s `applySwap` calls `scanSeeds` so a soft nav ingests seeds too. Inert server-side (DOM access only inside `scanSeeds`). Re-exported from `index.js` + `index-browser.js` |
 | `escape.js` | HTML attribute / text escaping (the only sanitiser) |
+| `asset-url.js` | Isomorphic content-hashed asset urls (#1194): `asset(path)` returns `/public/x.css?v=<hash>` on the server and the path UNCHANGED in the browser, plus `setAssetUrlProvider` (server-only wiring, installed by `@webjsdev/server`'s `dev.js`). Same provider seam as `csp-nonce.js`, and the same scoping rule follows from it: call it from a page / layout / metadata route and INSIDE the render function, since a shipping component re-renders on hydration where no provider exists (the hashed url would be swapped for the bare path) and a module-scope call is a side effect that ships the module. `setAssetUrlProvider` is stripped from the browser surface. |
 | `csp-nonce.js` | Isomorphic CSP nonce reader: `cspNonce()` (returns the request nonce, `''` in the browser) + `setCspNonceProvider` (server-only wiring). The provider is installed by `@webjsdev/server`'s `context.js`; as of #233 it returns a freshly-MINTED per-request nonce (not just an inbound-header parse). `setCspNonceProvider` is stripped from the browser surface |
 | `rich-fetch.js` | Content-negotiated fetch helper |
 | `websocket-client.js` | `connectWS()` with auto-reconnect |
diff --git a/packages/core/index-browser.js b/packages/core/index-browser.js
index 6fa901f96..8ae6afe8e 100644
--- a/packages/core/index-browser.js
+++ b/packages/core/index-browser.js
@@ -30,6 +30,7 @@ export { render } from './src/render-client.js';
 export { escapeText, escapeAttr } from './src/escape.js';
 export { notFound, redirect, forbidden, unauthorized, isNotFound, isRedirect, isForbidden, isUnauthorized } from './src/nav.js';
 export { cspNonce } from './src/csp-nonce.js';
+export { asset } from './src/asset-url.js';
 export { repeat, isRepeat } from './src/repeat.js';
 export { Suspense, isSuspense } from './src/suspense.js';
 export { connectWS } from './src/websocket-client.js';
diff --git a/packages/core/index.d.ts b/packages/core/index.d.ts
index 9528a2089..3d780e274 100644
--- a/packages/core/index.d.ts
+++ b/packages/core/index.d.ts
@@ -104,6 +104,7 @@ export { Task, TaskStatus } from './src/task.js';
 // src/*.d.ts (#388 fixed the index.d.ts drift from index.js).
 export { signal, computed, effect, batch, isSignal, Signal } from './src/signal.js';
 export { cspNonce, setCspNonceProvider } from './src/csp-nonce.js';
+export { asset, setAssetUrlProvider } from './src/asset-url.js';
 export { takeSeed, scanSeeds, SEED_MISS } from './src/action-seed-client.js';
 export { markStale, registerKeyTags, consumeStale, parseTagHeader, fetchMark } from './src/action-cache-client.js';
 // Client action-abort plumbing (#492): a superseded async render aborts its
diff --git a/packages/core/index.js b/packages/core/index.js
index aa426838a..f95a66ffd 100644
--- a/packages/core/index.js
+++ b/packages/core/index.js
@@ -15,6 +15,7 @@ export { render } from './src/render-client.js';
 export { escapeText, escapeAttr } from './src/escape.js';
 export { notFound, redirect, forbidden, unauthorized, isNotFound, isRedirect, isForbidden, isUnauthorized } from './src/nav.js';
 export { cspNonce, setCspNonceProvider } from './src/csp-nonce.js';
+export { asset, setAssetUrlProvider } from './src/asset-url.js';
 export { repeat, isRepeat } from './src/repeat.js';
 export { Suspense, isSuspense } from './src/suspense.js';
 export { connectWS } from './src/websocket-client.js';
diff --git a/packages/core/src/asset-url.d.ts b/packages/core/src/asset-url.d.ts
new file mode 100644
index 000000000..2c9d023ca
--- /dev/null
+++ b/packages/core/src/asset-url.d.ts
@@ -0,0 +1,3 @@
+/** Content-hashed `public/` asset urls (#1194). Server-side resolver; the browser bundle drops setAssetUrlProvider and `asset` returns its argument. */
+export function setAssetUrlProvider(fn: (path: string) => string): void;
+export function asset(path: string): string;
diff --git a/packages/core/src/asset-url.js b/packages/core/src/asset-url.js
new file mode 100644
index 000000000..c11e93e70
--- /dev/null
+++ b/packages/core/src/asset-url.js
@@ -0,0 +1,99 @@
+/**
+ * Resolve a `public/` asset url to its content-fingerprinted form, so a
+ * deploy that changes the file changes the url and no cache can serve the
+ * previous bytes.
+ *
+ *   import { html, asset } from '@webjsdev/core';
+ *   html`<link rel="stylesheet" href=${asset('/public/app.css')}>`
+ *
+ * On the server, `@webjsdev/server` installs a provider that appends
+ * `?v=<content-hash>`; the framework then serves a `?v=`-carrying request
+ * `immutable` for a year instead of the short fallback. On the browser there
+ * is no provider and the path is returned UNCHANGED.
+ *
+ * USE IT IN A PAGE, LAYOUT, OR METADATA ROUTE, not inside a component that
+ * ships to the browser. Those modules render only on the server, so the
+ * fingerprinted url is the one the browser sees and keeps. A component is
+ * different: hydration is a full client RE-RENDER (`render-client.js` drops
+ * the hydrate marker and `createInstance` replaces the SSR'd children), so
+ * the client value overwrites the server one. With no provider in the
+ * browser, `asset()` returns the bare path there, so an `<img src=${asset(
+ * '/public/logo.svg')}>` inside a shipping component paints the hashed url
+ * at SSR and then swaps it for the un-hashed one on upgrade, fetching the
+ * same bytes twice and leaving the short-lived url in the DOM. It still
+ * WORKS (the path is always valid), which is why this is a convention rather
+ * than a `webjs check` rule, but it silently forfeits the caching the call
+ * was for. Import the asset url into a layout, or accept the plain path.
+ *
+ * The sibling `cspNonce()` carries the same server/browser asymmetry and the
+ * same scoping, for the same hydration reason.
+ *
+ * Call it INSIDE the render function, not at module scope. A depth-0 call is a
+ * module-scope side effect, which the elision analyser reads as client work, so
+ * hoisting `const CSS = asset('/public/app.css')` pins the whole page or layout
+ * into the browser bundle for no benefit. Resolver ordering is not the issue
+ * (the server installs its resolver at boot, before any app module loads).
+ *
+ * Under `webjs.basePath`, write the prefix yourself: `asset('/app/public/x.css')`.
+ * The framework only base-path-prefixes urls IT emits, so an author-written
+ * url is already your responsibility (an un-prefixed one 404s under a
+ * sub-path deploy with or without this helper). `asset()` strips the prefix
+ * to find the file and keeps it on the url it returns.
+ *
+ * Mark files that change only with a DEPLOY. The hash is memoized for the
+ * process lifetime, and prod never rebuilds, so a `public/` file rewritten in
+ * place while the server runs keeps its old url while being served `immutable`
+ * for a year. A build artifact (a compiled stylesheet, a bundled script, a
+ * committed image) is exactly right; a runtime-written upload is not, and
+ * should keep its plain path (or carry its own version in the filename).
+ *
+ * Why this is opt-in rather than automatic. An earlier attempt (#1196)
+ * rewrote asset urls by matching the assembled HTML, and two deep-review
+ * rounds found six major defects, five of them the same bug: at that layer
+ * framework output and author data are indistinguishable, so the matcher kept
+ * touching things it did not own (a custom element's reactive prop, a
+ * rendered code sample, a `rel=preload` hint whose real request comes from
+ * CSS, a data-driven `src` pointing at `/.env`). Marking the url at the point
+ * the author writes it makes the meaning unambiguous, so the blast radius is
+ * exactly the set of urls someone deliberately marked and nothing else in the
+ * document is ever read or rewritten.
+ *
+ * Scope note: only a `public/` path is fingerprinted, matching what the
+ * static-asset route will actually serve. Anything else is returned
+ * unchanged rather than guessed at.
+ */
+
+/** @type {((path: string) => string) | null} */
+let _provider = null;
+
+/**
+ * Internal: server-only wiring. `@webjsdev/server` calls this once at load
+ * time to install the real resolver. Browser builds never call it, so
+ * `asset()` stays an identity function there.
+ *
+ * @param {(path: string) => string} fn
+ * @returns {void}
+ */
+export function setAssetUrlProvider(fn) {
+  _provider = fn;
+}
+
+/**
+ * The runtime function. Returns the fingerprinted url on the server, or the
+ * path unchanged when there is no provider (browser), when fingerprinting is
+ * off (dev, so dev output stays byte-identical), or when the file cannot be
+ * resolved. Every failure mode degrades to the plain path, never to a broken
+ * one.
+ *
+ * @param {string} path  a root-absolute same-origin path, e.g. `/public/app.css`
+ * @returns {string}
+ */
+export function asset(path) {
+  if (typeof path !== 'string' || !path) return path;
+  if (!_provider) return path;
+  try {
+    return _provider(path) || path;
+  } catch {
+    return path;
+  }
+}
diff --git a/packages/server/AGENTS.md b/packages/server/AGENTS.md
index 384951e57..3f55f49f3 100644
--- a/packages/server/AGENTS.md
+++ b/packages/server/AGENTS.md
@@ -64,7 +64,7 @@ with metadata, Suspense, streaming) for HTML, or `api.js` /
 | `build-info.js` | Build-info / version probe payload (#239). `buildInfo()` composes `{ version, build, node, uptime }` (framework version read once from this package's own `package.json`, `build` from `publishedBuildId()`, no secrets); `buildInfoResponse()` wraps it as the `no-store` JSON `GET /__webjs/version` response. Served in `handle()` before `ensureReady`, like the health / ready probes |
 | `redirects.js` | Declarative permanent / temporary redirects (#254). `compileRedirectRules(pkg)` normalizes the `webjs.redirects` package.json key (an array of `{ source, destination, permanent?, statusCode? }`) into URLPattern rules compiled ONCE at boot, dropping any malformed entry with a warning (the #232 fail-safe posture). `applyRedirects(req, rules)` matches the request pathname against the rules, fills `:name` groups from the source into the destination, preserves (and merges) the incoming query string, and returns a 308 (permanent default) / 307 (temporary) / configured-`statusCode` redirect Response on the first match, else null so the request falls through to routing. Skips `/__webjs/*`. Wired in `dev.js`: `readRedirectRules` reads it at boot and `produce()` applies it at the very start of request handling (before the probes / routing / SSR), the secure-header + conditional-GET funnel in `handle()` still wrapping the redirect Response. ALSO hosts the trailing-slash policy (#255): `readTrailingSlashPolicy(pkg)` normalizes the `webjs.trailingSlash` package.json key to `'never'` / `'always'` / `'ignore'` (default `'ignore'`, the non-breaking no-op); `applyTrailingSlash(req, policy)` 308-redirects a non-canonical path to the canonical form (`never` strips a trailing slash, `always` adds one), exempting the root `/`, file paths (last segment has a dot, under `always`), `/__webjs/*`, and network-path references (a path starting with `//` or `/\`, which would otherwise emit a protocol-relative cross-origin `Location`, an open redirect), and preserving query + hash. Wired in `dev.js` right AFTER `applyRedirects` in `produce()` (`readTrailingSlashFromApp` reads it at boot), so an explicit redirect wins first. NOT loop-free: a redirect destination that contradicts the slash policy loops forever (no server guard, the author's responsibility, matching `applyRedirects`) |
 | `base-path.js` | Sub-path deployment support (#256). `readBasePath(pkg)` / `normalizeBasePath(raw)` normalize the `webjs.basePath` package.json key to `''` (the root-mount default) or `/segment[/segment...]`, rejecting an unsafe value (`..`, a protocol, a `//host` reference, whitespace, a backslash) to `''` so a typo fails safe. The model is strip-at-ingress + prefix-on-emit, two seams only: `stripBasePath(pathname, basePath)` computes the root-relative path for the ingress strip (returns null when the path is not under the base path, so `dev.js` 404s it), and `withBasePath(url, basePath)` prefixes a framework-emitted same-origin absolute URL (a no-op when empty, leaving a cross-origin `https://` CDN target untouched). The ingress strip is wired in `dev.js`'s `produce()` (it rewrites the Request with the stripped URL, BEFORE `applyRedirects`, so all downstream config + matching sees a root-relative path; that rewrite is a FRESH Request, so it strips the inbound `x-webjs-remote-ip` header and carries the framework-trusted IP forward via `propagateTrustedRemoteIp` (#773), else on Bun, where the listener stamps the IP out of band on the ORIGINAL request, `clientIp` would fall back to the spoofable copied header); the prefix-on-emit is wired in `importmap.js` (`setBasePath` prefixes every importmap target + recomputes the hash) and `ssr.js` (the boot module specifiers, the modulepreload hrefs, the lazy entries, the dev reload src, read via importmap.js's `basePath()`), plus the 103 Early Hints `routeFor` in `dev.js`. Empty basePath is byte-identical to before the feature (guarded by a differential test). Author-written `<a href>` links + client-router nav are NOT prefixed (a documented follow-up) |
-| `asset-hash.js` | Content-hash asset URLs for immutable caching (#243, feature 1). `setAssetRoots({ appDir, coreDir, enabled })` binds the app + core roots and enables fingerprinting in PROD only (`dev.js` passes `enabled: !dev`, so dev is a pure no-op). `assetHashFor(absPath)` computes (and memoizes in a `Map<absPath, hash>`) a short 12-hex prefix of a sha-256 over the file BYTES (`node:crypto`, synchronous so the emit hot path stays sync), returning `''` on a read failure (NOT memoized, so a transient failure re-attempts). For a file under `_appDir` it ALSO folds in `_elisionFp` (set by `setElisionFingerprint`, called from `ensureReady`): an app module's served body is elision-transformed (a display-only import stripped), so a verdict flip must bust the importer's `?v` even when its source is byte-identical. The fingerprint is a relativized digest of the elidable + inert set (empty when nothing is elidable, leaving an app module's hash at exactly `sha256(bytes)`); core / `public/` files are never elision-transformed, so they hash over bytes alone. `routeFor` (the 103 Early Hints) applies `withAssetHash` too, so the hint and the body request the same URL. `withAssetHash(url, basePath?)` appends `?v=<hash>` to a framework-emitted SAME-ORIGIN absolute url (the importmap targets, the modulepreload hrefs, the boot specifiers): a NO-OP when disabled (dev), for a CROSS-ORIGIN / protocol-relative / relative url (so a `https://` jspm vendor target keeps its exact url, its #235 SRI key intact, and is never re-fingerprinted; an already-version-named `/__webjs/vendor/*` bundle is left alone too), and when the url does not resolve to a readable same-origin file (1h fallback). Composes with `withBasePath` (basePath then `?v`; it strips the base path before file resolution). `clearAssetHashCache()` is wired into `dev.js`'s rebuild path next to `clearVendorCache` so a changed file re-hashes (the deploy-busts mechanism). The emit is in `importmap.js`'s `buildImportMap` (`fingerprint` flag, true for the SERVED map, false for the internal hash so the build id stays a stable per-deploy fingerprint) and `ssr.js`'s `wrapHead` (boot specifiers + modulepreload hrefs + lazy entries). The SERVE seam is `dev.js`: a request carrying a `?v=` query is served `Cache-Control: public, max-age=31536000, immutable` (vs the 1h fallback) by `fileResponse` (`immutable` flag), `jsModuleResponse` / `tsResponse` (an `immutable` arg), and the core serve in `tryServeFrameworkStatic` (a `versioned` ctx flag); the pathname (query stripped) resolves the file as today, only the cache header changes. Dev stays `no-cache` regardless. **`versionModuleImports(source, importerAbs)` (#369)** is the matching SERVED-SOURCE rewrite: a layout/page/component imports its dependencies with a BARE relative specifier (`import '../components/x.ts'`), and the browser resolves that against the importer's `?v=`-versioned URL WITHOUT inheriting the `?v` query, so it would fetch the un-versioned URL (a different cache key from the `?v=`-versioned modulepreload hint -> wasted preload, double download, 1h cache). The pass appends the target's `?v=<hash>` (the same `assetHashFor` the preload href uses, so the URLs are byte-identical) to every same-origin relative / root-absolute static-import specifier in a served module, matching over a redaction mask (so a templated example import is skipped). Bare specifiers (importmap-resolved, versioned at their target) and `.server.*` stubs (bare-URL, not in the preload set) are left untouched. Run AFTER `elideImportsFromSource` in `jsModuleResponse` / `tsResponse`; a pure no-op when disabled (dev), so dev source stays byte-faithful. |
+| `asset-hash.js` | Content-hash asset URLs for immutable caching (#243, feature 1). `setAssetRoots({ appDir, coreDir, enabled })` binds the app + core roots and enables fingerprinting in PROD only (`dev.js` passes `enabled: !dev`, so dev is a pure no-op). `assetHashFor(absPath)` computes (and memoizes in a `Map<absPath, hash>`) a short 12-hex prefix of a sha-256 over the file BYTES (`node:crypto`, synchronous so the emit hot path stays sync), returning `''` on a read failure (NOT memoized, so a transient failure re-attempts). For a file under `_appDir` it ALSO folds in `_elisionFp` (set by `setElisionFingerprint`, called from `ensureReady`): an app module's served body is elision-transformed (a display-only import stripped), so a verdict flip must bust the importer's `?v` even when its source is byte-identical. The fingerprint is a relativized digest of the elidable + inert set (empty when nothing is elidable, leaving an app module's hash at exactly `sha256(bytes)`); core / `public/` files are never elision-transformed, so they hash over bytes alone. `routeFor` (the 103 Early Hints) applies `withAssetHash` too, so the hint and the body request the same URL. `withAssetHash(url, basePath?)` appends `?v=<hash>` to a framework-emitted SAME-ORIGIN absolute url (the importmap targets, the modulepreload hrefs, the boot specifiers): a NO-OP when disabled (dev), for a CROSS-ORIGIN / protocol-relative / relative url (so a `https://` jspm vendor target keeps its exact url, its #235 SRI key intact, and is never re-fingerprinted; an already-version-named `/__webjs/vendor/*` bundle is left alone too), and when the url does not resolve to a readable same-origin file (1h fallback). Composes with `withBasePath` (basePath then `?v`; it strips the base path before file resolution). `clearAssetHashCache()` is wired into `dev.js`'s rebuild path next to `clearVendorCache` so a changed file re-hashes (the deploy-busts mechanism). The emit is in `importmap.js`'s `buildImportMap` (`fingerprint` flag, true for the SERVED map, false for the internal hash so the build id stays a stable per-deploy fingerprint) and `ssr.js`'s `wrapHead` (boot specifiers + modulepreload hrefs + lazy entries). The SERVE seam is `dev.js`: a request carrying a `?v=` query is served `Cache-Control: public, max-age=31536000, immutable` (vs the 1h fallback) by `fileResponse` (`immutable` flag), `jsModuleResponse` / `tsResponse` (an `immutable` arg), and the core serve in `tryServeFrameworkStatic` (a `versioned` ctx flag); the pathname (query stripped) resolves the file as today, only the cache header changes. Dev stays `no-cache` regardless. **`versionModuleImports(source, importerAbs)` (#369)** is the matching SERVED-SOURCE rewrite: a layout/page/component imports its dependencies with a BARE relative specifier (`import '../components/x.ts'`), and the browser resolves that against the importer's `?v=`-versioned URL WITHOUT inheriting the `?v` query, so it would fetch the un-versioned URL (a different cache key from the `?v=`-versioned modulepreload hint -> wasted preload, double download, 1h cache). The pass appends the target's `?v=<hash>` (the same `assetHashFor` the preload href uses, so the URLs are byte-identical) to every same-origin relative / root-absolute static-import specifier in a served module, matching over a redaction mask (so a templated example import is skipped). Bare specifiers (importmap-resolved, versioned at their target) and `.server.*` stubs (bare-URL, not in the preload set) are left untouched. Run AFTER `elideImportsFromSource` in `jsModuleResponse` / `tsResponse`; a pure no-op when disabled (dev), so dev source stays byte-faithful. **`resolveAssetUrl(path, basePath?)` (#1194)** is the server body behind core's isomorphic `asset()` helper (installed via `setAssetUrlProvider` at `dev.js` boot), and it carries a STRICTER contract than `withAssetHash`: it resolves ONLY `public/` paths and refuses traversal, because an app may pass request- or user-derived data (`asset(user.avatarPath)`), and `resolveUrlToFile` would otherwise map any same-origin path under the PROJECT ROOT, publishing a content hash for `/.env` or a `.server.ts` and leaking both its existence and a fingerprint of its bytes. It also splits a `#fragment` before hashing, so the query lands ahead of it. Anything it refuses is returned unchanged WITHOUT touching the disk. |
 | `csp.js` | CSP nonce minting + `Content-Security-Policy` header building (#233). `readCspConfig` normalizes the `webjs.csp` package.json key (off by default; `true` = strict default policy, object = custom directives + `reportOnly`); `mintNonce` is the per-request CSPRNG nonce; `buildCspHeader` substitutes the nonce into the policy. Plugs into the #232 `applySecurityHeaders` seam in `dev.js`'s `handle()` |
 | `env-schema.js` | Boot-time env-var validation (#236). `validateEnv(schema, env)` is the PURE validator: it checks an env object against a schema (an object of `name -> type-name | options`, supporting `string`/`number`/`boolean`/`url`/`enum`, `required`/`optional`/`default`, `minLength`/`pattern`), collecting ALL errors at once and returning the coerced + defaulted values to write back. A schema may instead be a FUNCTION `(env) => void` (the escape hatch for zod etc.), whose throw becomes the single error. `loadEnvSchema(appDir)` reads the optional app-root `env.{js,ts}` (null when absent, so opt-in); `applyEnvValidation(appDir)` is the side-effecting boot wrapper called from `createRequestHandler` right after the `.env` auto-load: it validates `process.env`, applies coerced values back, and THROWS a clear aggregated Error on failure (CLI exits non-zero, embedded host rejects), consistent with the Node-version preflight. `formatEnvErrors` composes the aggregated message. |
 | `ts-strip.js` | Pluggable TypeScript stripper (#508), the seam that lets webjs run on both Node and Bun. `stripTypeScript(source)` erases types in place (position-preserving, no sourcemap) via the backend `ensureStripper()` resolves once at boot: Node 24+'s built-in `module.stripTypeScriptTypes` (zero deps, the default), or `amaro` on a runtime lacking it (Bun), lazily imported. Node's built-in is itself a wrapper over amaro's `strip-only` mode, so the output is BYTE-IDENTICAL (a unit test asserts it). `amaro` is an `optionalDependency` of this package: a Node-only install that prunes optionals still runs (it never loads amaro); a Bun install gets it. `WEBJS_TS_STRIPPER=builtin|amaro` forces a backend. Namespace-imports `node:module` (not a named `stripTypeScriptTypes` import) so the module LINKS on a runtime lacking the builtin (Bun, old Node) instead of link-failing before the runtime check (the PR #282 link-safety pattern, now living here). Also hosts the one-shot `stripTypeScriptTypes` ExperimentalWarning suppression, co-located with the call. `dev.js`'s `stripTs` delegates here and `createRequestHandler` calls `ensureStripper()` at boot. |
diff --git a/packages/server/src/asset-hash.js b/packages/server/src/asset-hash.js
index 5796fb464..c3bfa8375 100644
--- a/packages/server/src/asset-hash.js
+++ b/packages/server/src/asset-hash.js
@@ -159,10 +159,32 @@ export function assetHashFor(absPath) {
     const bytes = readFileSync(absPath);
     const h = createHash('sha256').update(bytes);
     // An app module's served body is elision-transformed, so fold the verdict
-    // fingerprint in (see `_elisionFp`). Core / public files are never
-    // transformed, so they hash over their bytes alone. Empty fp leaves an app
-    // module's hash at exactly `sha256(bytes)`.
-    if (_elisionFp && _appDir && absPath.startsWith(_appDir + sep)) {
+    // fingerprint in (see `_elisionFp`). Core and `public/` files are never
+    // transformed, so they hash over their bytes alone, which the two
+    // exclusions below enforce rather than merely assume. Empty fp leaves an
+    // app module's hash at exactly `sha256(bytes)`.
+    //
+    // Both exclusions are EXPLICIT because the containment test alone admits
+    // them, and the intent above is otherwise silently false:
+    //
+    //   - `public/` sits under `_appDir`. Inert while only module specifiers
+    //     reached here, but `asset()` (#1194) routes public paths through this
+    //     function.
+    //   - `_coreDir` sits under `_appDir` too in a REAL install, where it
+    //     resolves to `<appDir>/node_modules/@webjsdev/core`. It escapes only
+    //     in this monorepo, where the workspace symlink lands outside, which
+    //     is exactly why no in-repo test ever caught it.
+    //
+    // Neither file set is elision-transformed (core is served verbatim by
+    // `fileResponse`), so folding the verdict in buys nothing and costs
+    // correctness: any deploy that merely flips an UNRELATED component between
+    // elidable and interactive would move their urls, re-downloading the whole
+    // core runtime plus every marked stylesheet, image, and script even though
+    // not one of those bytes changed. That is the precise cost a content hash
+    // exists to avoid.
+    if (_elisionFp && _appDir && absPath.startsWith(_appDir + sep)
+        && !absPath.startsWith(join(_appDir, 'public') + sep)
+        && !(_coreDir && absPath.startsWith(_coreDir + sep))) {
       h.update('\0');
       h.update(_elisionFp);
     }
@@ -267,6 +289,46 @@ export function withAssetHash(url, basePath = '') {
   return `${url}${sepChar}v=${hash}`;
 }
 
+/**
+ * Resolve one author-marked asset path to its fingerprinted url. This is the
+ * body behind the isomorphic `asset()` helper (#1194); `dev.js` installs it
+ * via `setAssetUrlProvider` at boot.
+ *
+ * The `public/` gate is defensive, not decorative. `resolveUrlToFile` maps any
+ * same-origin path under the PROJECT ROOT, so an app that passed request- or
+ * user-derived data in (`asset(user.avatarPath)`) would otherwise read and
+ * publish a content hash for `/.env`, `/db/app.db`, or a `.server.ts`, leaking
+ * both that the file exists and a fingerprint of its exact bytes for files the
+ * serve path deliberately 404s. Mirror the static-asset route instead: under
+ * `public/`, no traversal. Anything else returns unchanged WITHOUT touching
+ * the disk, so a rejected path costs nothing and reveals nothing.
+ *
+ * A fragment is split before hashing. `withAssetHash` appends the query, so
+ * passing the whole thing would emit `/x.svg#icon?v=H`: the browser then
+ * requests `/x.svg` with no query (losing the immutable caching this exists
+ * for) and the fragment becomes `icon?v=H`, matching no element id.
+ *
+ * @param {string} p          the author-supplied path
+ * @param {string} [bp]       the active base path
+ * @returns {string}          the fingerprinted url, or `p` unchanged
+ */
+export function resolveAssetUrl(p, bp = '') {
+  if (typeof p !== 'string' || p[0] !== '/' || p[1] === '/') return p;
+  let probe = p;
+  if (bp && probe.startsWith(bp + '/')) probe = probe.slice(bp.length);
+  const cuts = [probe.indexOf('?'), probe.indexOf('#')].filter((i) => i !== -1);
+  let decoded = probe.slice(0, cuts.length ? Math.min(...cuts) : probe.length);
+  try { decoded = decodeURIComponent(decoded); } catch { /* keep raw */ }
+  if (decoded.includes('..') || !decoded.startsWith('/public/')) return p;
+  const h = p.indexOf('#');
+  const path = h === -1 ? p : p.slice(0, h);
+  const frag = h === -1 ? '' : p.slice(h);
+  // An author-supplied query is left alone: it may carry meaning we do not
+  // own, and appending would merge with `&`.
+  if (path.includes('?')) return p;
+  return withAssetHash(path, bp) + frag;
+}
+
 /**
  * Static `import` specifier with positional indices. Mirrors module-graph.js's
  * `IMPORT_RE` (side-effect / default / namespace / named imports), but captures
diff --git a/packages/server/src/dev.js b/packages/server/src/dev.js
index eea248df6..17bc1265e 100644
--- a/packages/server/src/dev.js
+++ b/packages/server/src/dev.js
@@ -93,7 +93,8 @@ import { setVendorEntries, setCoreInstall, publishBuildId, setAppSourceId, setBa
 import { readBasePath, stripBasePath, withBasePath } from './base-path.js';
 import { propagateTrustedRemoteIp } from './rate-limit.js';
 import { readAllowedOrigins } from './csrf.js';
-import { setAssetRoots, clearAssetHashCache, setElisionFingerprint, withAssetHash, assetHashFor, versionModuleImports } from './asset-hash.js';
+import { setAssetUrlProvider } from '@webjsdev/core';
+import { setAssetRoots, clearAssetHashCache, setElisionFingerprint, withAssetHash, assetHashFor, versionModuleImports, resolveAssetUrl } from './asset-hash.js';
 import { urlFromRequest } from './forwarded.js';
 import { compileHeaderRules, applySecurityHeaders, webRequestIsHttps } from './headers.js';
 import {
@@ -624,6 +625,21 @@ export async function createRequestHandler(opts) {
   // id is a stable deploy fingerprint independent of per-file content hashes.
   setAssetRoots({ appDir, coreDir, enabled: !dev });
 
+  // Install the resolver behind the isomorphic `asset()` helper (#1194), the
+  // same provider seam `cspNonce()` uses. An author writes
+  // `href=${asset('/public/app.css')}` and gets the fingerprinted url on the
+  // server; the browser has no provider and returns the path unchanged.
+  //
+  // The `public/` gate is defensive rather than decorative. `resolveUrlToFile`
+  // maps any same-origin path under the PROJECT ROOT, so an app that passed
+  // request- or user-derived data here (`asset(user.avatarPath)`) would
+  // otherwise read and publish a content hash for `/.env`, `/db/app.db`, or a
+  // `.server.ts`, leaking both existence and a fingerprint of the bytes for
+  // files the serve path deliberately 404s. Mirror the static-asset route:
+  // under `public/`, no traversal. Everything else returns unchanged, having
+  // never touched the disk.
+  setAssetUrlProvider((p) => resolveAssetUrl(p, basePath()));
+
   // SSR action-result seeding (#472). Install the process-global module load
   // hook NOW, at boot, before any `'use server'` action module is imported (ESM
   // caches by URL, so a module loaded before the hook would never be faceted).
diff --git a/packages/server/test/dev/asset-helper-serve.test.js b/packages/server/test/dev/asset-helper-serve.test.js
new file mode 100644
index 000000000..527c6b577
--- /dev/null
+++ b/packages/server/test/dev/asset-helper-serve.test.js
@@ -0,0 +1,99 @@
+/**
+ * End-to-end serving test for the `asset()` helper (#1194).
+ *
+ * The unit tests for `resolveAssetUrl` prove the resolver. This proves the
+ * WIRING: that a real prod handler installs the provider at boot, that a
+ * layout calling `asset()` therefore renders a fingerprinted url, and that
+ * requesting that url gets `immutable` caching back. Without this, the two
+ * halves could each be correct while nothing connected them, which is exactly
+ * the failure mode a manual browser check kept hiding (a worktree resolves
+ * `@webjsdev/*` through node_modules, so a hand-booted server can silently be
+ * running a DIFFERENT checkout's code).
+ *
+ * `dev: false` matters: fingerprinting is prod-only, so a dev handler must
+ * leave the url untouched, which the second test pins.
+ */
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync, symlinkSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { createRequestHandler } from '../../src/dev.js';
+
+// The fixture app's own source does `import { asset } from '@webjsdev/core'`,
+// and a temp dir outside the monorepo cannot resolve that. Link the repo's
+// node_modules into each fixture so the app resolves the SAME core this test
+// is exercising, rather than whatever a parent directory happens to expose.
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..');
+const REPO_MODULES = join(REPO_ROOT, 'node_modules');
+
+let tmpRoot;
+before(() => { tmpRoot = mkdtempSync(join(tmpdir(), 'webjs-asset-serve-')); });
+after(() => { rmSync(tmpRoot, { recursive: true, force: true }); });
+
+function makeApp(files) {
+  const appDir = mkdtempSync(join(tmpRoot, 'app-'));
+  for (const [rel, body] of Object.entries(files)) {
+    const abs = join(appDir, rel);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, body);
+  }
+  if (existsSync(REPO_MODULES)) symlinkSync(REPO_MODULES, join(appDir, 'node_modules'), 'dir');
+  return appDir;
+}
+
+const FILES = {
+  // A layout that marks one asset and leaves a second one bare, so the same
+  // render proves both that marking works and that nothing else is touched.
+  'app/layout.ts': `
+import { html, asset } from '@webjsdev/core';
+export default ({ children }) => html\`<!doctype html><html><head>
+<link rel="stylesheet" href=\${asset('/public/app.css')}>
+<link rel="preload" href="/public/app.css" as="style">
+</head><body>\${children}</body></html>\`;
+`,
+  'app/page.ts': `import { html } from '@webjsdev/core';\nexport default () => html\`<main>hi</main>\`;`,
+  'public/app.css': 'body{color:red}',
+  'package.json': JSON.stringify({ name: 'asset-serve' }),
+};
+
+test('a prod handler renders asset() fingerprinted and serves it immutable', async () => {
+  const appDir = makeApp(FILES);
+  const app = await createRequestHandler({ appDir, dev: false });
+
+  const page = await app.handle(new Request('http://x/'));
+  assert.equal(page.status, 200);
+  const html = await page.text();
+
+  const m = html.match(/<link rel="stylesheet" href="(\/public\/app\.css\?v=[0-9a-f]+)"/);
+  assert.ok(m, `the marked url should carry ?v=, got:\n${html.slice(0, 400)}`);
+
+  // The UNMARKED preload is untouched. This is the property the previous
+  // design (#1196) could not hold: it rewrote every asset-looking url in the
+  // document, which desynced font preloads from the `@font-face url()` that
+  // actually fetches them. Opt-in means the author decides per url.
+  assert.match(html, /<link rel="preload" href="\/public\/app\.css" as="style">/);
+
+  // And the emitted url is really servable, with the caching that is the
+  // whole point: a hashed url is immutable for a year, a bare one is not.
+  const hashed = await app.handle(new Request(`http://x${m[1]}`));
+  assert.equal(hashed.status, 200);
+  assert.match(hashed.headers.get('cache-control') || '', /immutable/);
+
+  const bare = await app.handle(new Request('http://x/public/app.css'));
+  assert.equal(bare.status, 200);
+  assert.doesNotMatch(bare.headers.get('cache-control') || '', /immutable/);
+});
+
+test('a dev handler leaves asset() urls untouched', async () => {
+  // Fingerprinting is prod-only so dev output stays byte-identical. Note the
+  // resolver IS installed in dev too (dev.js wires it unconditionally); what
+  // makes dev a no-op is `_enabled` inside withAssetHash, two modules away.
+  const appDir = makeApp(FILES);
+  const app = await createRequestHandler({ appDir, dev: true });
+  const html = await (await app.handle(new Request('http://x/'))).text();
+  assert.match(html, /<link rel="stylesheet" href="\/public\/app\.css">/);
+  assert.doesNotMatch(html, /\?v=/);
+});
diff --git a/packages/server/test/importmap/resolve-asset-url.test.js b/packages/server/test/importmap/resolve-asset-url.test.js
new file mode 100644
index 000000000..edbae549c
--- /dev/null
+++ b/packages/server/test/importmap/resolve-asset-url.test.js
@@ -0,0 +1,196 @@
+/**
+ * Unit tests for `resolveAssetUrl` (#1194), the server-side body behind the
+ * isomorphic `asset()` helper. An author marks a url explicitly:
+ *
+ *   html`<link rel="stylesheet" href=${asset('/public/app.css')}>`
+ *
+ * and gets `?v=<content-hash>` in production, which the static route serves
+ * `immutable` for a year, so a deploy that changes the file changes the url
+ * and no cache can serve the previous bytes.
+ *
+ * This replaces the approach in #1196, which matched asset urls in the
+ * assembled HTML. Two deep-review rounds found six major defects there, five
+ * of them the same bug: at that layer framework output and author data are
+ * indistinguishable, so the matcher kept rewriting things it did not own (a
+ * custom element's reactive prop, a rendered code sample, a `rel=preload`
+ * hint, a data-driven `src` pointing at `/.env`). Those whole classes are
+ * gone here by construction, because nothing is scanned. What remains worth
+ * testing is this function's own contract, and the security gate in
+ * particular, since an app may pass user-derived data to `asset()`.
+ */
+import { test, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  setAssetRoots,
+  clearAssetHashCache,
+  setElisionFingerprint,
+  withAssetHash,
+  resolveAssetUrl,
+  assetHashFor,
+} from '../../src/asset-hash.js';
+
+let root;
+let appDir;
+let coreDir;
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), 'webjs-asseturl-'));
+  appDir = join(root, 'app');
+  coreDir = join(root, 'core');
+  mkdirSync(join(appDir, 'public', 'brand'), { recursive: true });
+  mkdirSync(coreDir, { recursive: true });
+  writeFileSync(join(appDir, 'public', 'app.css'), 'body{color:red}');
+  writeFileSync(join(appDir, 'public', 'brand', 'logo.svg'), '<svg/>');
+  clearAssetHashCache();
+  setAssetRoots({ appDir, coreDir, enabled: true });
+});
+
+afterEach(() => {
+  setAssetRoots({ appDir: '', coreDir: '', enabled: false });
+  clearAssetHashCache();
+  rmSync(root, { recursive: true, force: true });
+});
+
+test('a public asset is fingerprinted', () => {
+  const out = resolveAssetUrl('/public/app.css');
+  assert.match(out, /^\/public\/app\.css\?v=[0-9a-f]+$/);
+  assert.equal(out, withAssetHash('/public/app.css'), 'agrees with the framework hash');
+});
+
+test('the hash changes when the bytes change', () => {
+  const before = resolveAssetUrl('/public/app.css');
+  writeFileSync(join(appDir, 'public', 'app.css'), 'body{color:blue}');
+  clearAssetHashCache();
+  assert.notEqual(resolveAssetUrl('/public/app.css'), before);
+});
+
+test('a public asset hash does not move with the elision verdict', () => {
+  // public/ lives under appDir, so the elision-fingerprint fold admits it
+  // unless excluded explicitly. That was inert while only module specifiers
+  // were hashed; asset() routes public paths here. Without the exclusion a
+  // deploy that merely flips an UNRELATED component between elidable and
+  // interactive changes every marked asset url, so every visitor re-downloads
+  // byte-identical files, which is the cost the hash exists to avoid.
+  const seen = new Set();
+  for (const fp of ['', 'verdict-a', 'verdict-b']) {
+    setElisionFingerprint(fp);
+    clearAssetHashCache();
+    seen.add(resolveAssetUrl('/public/app.css'));
+  }
+  setElisionFingerprint('');
+  clearAssetHashCache();
+  assert.equal(seen.size, 1, `the url must depend on bytes alone, saw: ${[...seen].join(' ')}`);
+});
+
+test('a core file hash does not move with the elision verdict either', () => {
+  // Same bug as the public/ case, one directory over, and invisible in this
+  // monorepo: a REAL install resolves core to <appDir>/node_modules/@webjsdev/
+  // core, which IS under appDir, whereas the workspace symlink here lands
+  // outside it. So the fold silently applied to core in every deployed app.
+  // Core is served verbatim (never elision-transformed), so folding buys
+  // nothing and would re-download the whole runtime on any deploy that merely
+  // flipped an unrelated component's elidability.
+  const realInstallCore = join(appDir, 'node_modules', '@webjsdev', 'core');
+  mkdirSync(realInstallCore, { recursive: true });
+  const coreFile = join(realInstallCore, 'webjs-core-browser.js');
+  writeFileSync(coreFile, 'export const core = 1;');
+  setAssetRoots({ appDir, coreDir: realInstallCore, enabled: true });
+
+  const seen = new Set();
+  for (const fp of ['', 'verdict-a', 'verdict-b']) {
+    setElisionFingerprint(fp);
+    clearAssetHashCache();
+    seen.add(assetHashFor(coreFile));
+  }
+  setElisionFingerprint('');
+  clearAssetHashCache();
+  assert.equal(seen.size, 1, `core must hash over bytes alone, saw: ${[...seen].join(' ')}`);
+});
+
+test('a fragment survives and the query precedes it', () => {
+  // An SVG sprite (`#icon`) and a media fragment (`#t=10,20`) are real.
+  // Appending naively would emit `/logo.svg#icon?v=H`, which requests the
+  // file with NO query (losing immutable caching) and leaves a fragment that
+  // matches no element id.
+  const out = resolveAssetUrl('/public/brand/logo.svg#icon');
+  assert.match(out, /^\/public\/brand\/logo\.svg\?v=[0-9a-f]+#icon$/);
+});
+
+test('a private file is never read, whatever the caller passes', () => {
+  // The gate is defensive: an app may pass user-derived data, e.g.
+  // `asset(user.avatarPath)`. Publishing a hash would leak that the file
+  // exists AND a stable fingerprint of its bytes, for files the serve path
+  // deliberately 404s.
+  writeFileSync(join(appDir, '.env'), 'DATABASE_URL=postgres://u:SECRET@h/db');
+  mkdirSync(join(appDir, 'db'), { recursive: true });
+  writeFileSync(join(appDir, 'db', 'app.db'), 'SQLITE FORMAT 3');
+  mkdirSync(join(appDir, 'lib'), { recursive: true });
+  writeFileSync(join(appDir, 'lib', 'session.server.ts'), 'export const KEY = 1');
+  // Every path here must EXIST, or it is refused by the missing-file fail-safe
+  // rather than by the gate under test, and the assertion proves nothing.
+  writeFileSync(join(appDir, 'package.json'), '{"name":"probe"}');
+
+  for (const p of ['/.env', '/db/app.db', '/lib/session.server.ts', '/package.json']) {
+    assert.equal(resolveAssetUrl(p), p, `${p} must not be fingerprinted`);
+  }
+});
+
+test('a traversal out of public/ is refused', () => {
+  writeFileSync(join(appDir, '.env'), 'SECRET=1');
+  for (const p of ['/public/../.env', '/public/%2E%2E/.env', '/public/%2e%2e/.env']) {
+    assert.equal(resolveAssetUrl(p), p, `${p} must not escape public/`);
+  }
+});
+
+test('non-public, cross-origin, relative, and queried paths pass through', () => {
+  for (const p of [
+    'https://cdn.example.com/a.css',
+    '//cdn.example.com/a.css',
+    './a.css',
+    '/public/app.css?theme=dark',
+    '/public/missing.css',
+    '',
+  ]) {
+    assert.equal(resolveAssetUrl(p), p);
+  }
+});
+
+test('a base path is stripped for resolution and kept on the url', () => {
+  // Compose order matches withAssetHash: basePath first, then the hash.
+  const out = resolveAssetUrl('/base/public/app.css', '/base');
+  assert.match(out, /^\/base\/public\/app\.css\?v=[0-9a-f]+$/);
+});
+
+test('it is a no-op when fingerprinting is disabled', () => {
+  // Dev never enables it, so dev output stays byte-identical.
+  setAssetRoots({ appDir: '', coreDir: '', enabled: false });
+  assert.equal(resolveAssetUrl('/public/app.css'), '/public/app.css');
+});
+
+/*
+ * The isomorphic contract: `asset()` must be safe to call from a module that
+ * also loads in the browser, because a layout does exactly that to register
+ * its component imports. With no provider installed it returns the path
+ * unchanged, which is always a correct url, just an un-versioned one.
+ */
+test('asset() returns the path unchanged with no provider (the browser case)', async () => {
+  // Imported by source path, not by `@webjsdev/core`. The bare specifier
+  // resolves through node_modules, which in a git worktree can point at a
+  // DIFFERENT checkout of the monorepo, so the test would silently exercise
+  // another copy of this file. The relative path pins it to this tree.
+  const { asset, setAssetUrlProvider } = await import('../../../core/src/asset-url.js');
+  setAssetUrlProvider(null);
+  assert.equal(asset('/public/app.css'), '/public/app.css');
+
+  setAssetUrlProvider((p) => resolveAssetUrl(p));
+  assert.match(asset('/public/app.css'), /\?v=[0-9a-f]+$/);
+
+  // A throwing provider must degrade to the plain path, never propagate.
+  setAssetUrlProvider(() => { throw new Error('boom'); });
+  assert.equal(asset('/public/app.css'), '/public/app.css');
+  setAssetUrlProvider(null);
+});
diff --git a/test/bun/asset-url.mjs b/test/bun/asset-url.mjs
new file mode 100644
index 000000000..f39fe0888
--- /dev/null
+++ b/test/bun/asset-url.mjs
@@ -0,0 +1,91 @@
+/**
+ * Cross-runtime proof that `asset()` url resolution (#1194) behaves identically
+ * on Node and Bun. WebJs runs on Node 24+ OR Bun, and this path touches several
+ * runtime-sensitive surfaces at once: a synchronous `readFileSync`, a
+ * `node:crypto` sha-256 over the bytes, `node:path` joins and separator
+ * comparisons for the containment gates, and `decodeURIComponent` for the
+ * traversal refusal. A divergence in any of them would either change the
+ * emitted url (breaking cache continuity across a mixed-runtime fleet) or,
+ * worse, weaken the gate that keeps a private file from being hashed. Run from
+ * the repo root:
+ *
+ *   node test/bun/asset-url.mjs
+ *   bun  test/bun/asset-url.mjs
+ *
+ * Asserts, on whichever runtime executes it: a public asset resolves to
+ * `?v=<sha256(bytes) prefix>` computed the same way, the hash tracks the bytes,
+ * a fragment survives with the query ahead of it, the hash ignores the elision
+ * verdict (core and `public/` are never elision-transformed), and every
+ * non-public or traversal path is refused WITHOUT reading the file.
+ */
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+
+import {
+  setAssetRoots,
+  setElisionFingerprint,
+  clearAssetHashCache,
+  resolveAssetUrl,
+} from '../../packages/server/src/asset-hash.js';
+
+const runtime = typeof globalThis.Bun !== 'undefined' ? 'bun' : 'node';
+
+const root = mkdtempSync(join(tmpdir(), 'webjs-asset-bun-'));
+const appDir = join(root, 'app');
+const coreDir = join(root, 'core');
+mkdirSync(join(appDir, 'public'), { recursive: true });
+mkdirSync(coreDir, { recursive: true });
+writeFileSync(join(appDir, 'public', 'app.css'), 'body{color:red}');
+writeFileSync(join(appDir, '.env'), 'SECRET=1');
+
+setAssetRoots({ appDir, coreDir, enabled: true });
+clearAssetHashCache();
+
+// 1. The emitted hash is sha-256 over the bytes, identically on both runtimes.
+// A mismatch would hand the two runtimes different urls for one file, so a
+// mixed-runtime fleet would thrash every client's immutable cache.
+const expected = createHash('sha256').update('body{color:red}').digest('hex').slice(0, 12);
+const url = resolveAssetUrl('/public/app.css');
+assert.equal(url, `/public/app.css?v=${expected}`, `${runtime}: hash must be sha256(bytes)[0:12]`);
+
+// 2. The hash tracks the bytes.
+writeFileSync(join(appDir, 'public', 'app.css'), 'body{color:blue}');
+clearAssetHashCache();
+assert.notEqual(resolveAssetUrl('/public/app.css'), url, `${runtime}: new bytes must yield a new url`);
+
+// 3. A fragment survives, with the query ahead of it (string handling parity).
+writeFileSync(join(appDir, 'public', 'icons.svg'), '<svg/>');
+clearAssetHashCache();
+assert.match(
+  resolveAssetUrl('/public/icons.svg#logo'),
+  /^\/public\/icons\.svg\?v=[0-9a-f]{12}#logo$/,
+  `${runtime}: fragment must survive with the query before it`,
+);
+
+// 4. The elision verdict must not reach a public asset's hash (path
+// containment comparisons use `sep`, which is worth pinning per runtime).
+const seen = new Set();
+for (const fp of ['', 'verdict-a', 'verdict-b']) {
+  setElisionFingerprint(fp);
+  clearAssetHashCache();
+  seen.add(resolveAssetUrl('/public/app.css'));
+}
+setElisionFingerprint('');
+clearAssetHashCache();
+assert.equal(seen.size, 1, `${runtime}: a public url must depend on bytes alone`);
+
+// 5. The security gate holds. These must be refused by the gate, never read,
+// so a private file's existence and bytes stay undisclosed.
+for (const p of ['/.env', '/public/../.env', '/public/%2E%2E/.env', '/etc/passwd']) {
+  assert.equal(resolveAssetUrl(p), p, `${runtime}: ${p} must be refused unchanged`);
+}
+
+// Clean up the fixture, matching every sibling in this directory. Both `npm
+// test` and the Bun CI step run this file, so leaking would strand a
+// `webjs-asset-bun-*` directory in the temp dir on every single run.
+rmSync(root, { recursive: true, force: true });
+
+console.log(`[asset-url] ok on ${runtime}`);
diff --git a/test/bun/asset-url.test.mjs b/test/bun/asset-url.test.mjs
new file mode 100644
index 000000000..7d2ef0411
--- /dev/null
+++ b/test/bun/asset-url.test.mjs
@@ -0,0 +1,11 @@
+/**
+ * Run the cross-runtime `asset()` url-resolution check (#1194) under whichever
+ * runtime runs the suite. `npm test` covers Node; CI runs
+ * `bun test/bun/asset-url.mjs` for Bun. The behaviour script is a plain assert
+ * file (not `*.test.mjs`, so the runner does not double-run it).
+ */
+import { test } from 'node:test';
+
+test('asset() resolves urls identically on this runtime (#1194)', async () => {
+  await import('./asset-url.mjs');
+});
diff --git a/test/scaffolds/gallery-coverage.json b/test/scaffolds/gallery-coverage.json
index 685abcd8d..fa218fd01 100644
--- a/test/scaffolds/gallery-coverage.json
+++ b/test/scaffolds/gallery-coverage.json
@@ -301,6 +301,12 @@
     },
     "watch": {
       "demo": "modules/directives/components/directive-demo.ts"
+    },
+    "asset": {
+      "demo": "app/features/caching/page.ts"
+    },
+    "setAssetUrlProvider": {
+      "exempt": "internal: server-only asset url provider setup"
     }
   },
   "serverSpecifier": "@webjsdev/server",
diff --git a/test/scaffolds/scaffold-gallery.test.js b/test/scaffolds/scaffold-gallery.test.js
index 8c73c0995..e608c5968 100644
--- a/test/scaffolds/scaffold-gallery.test.js
+++ b/test/scaffolds/scaffold-gallery.test.js
@@ -229,6 +229,17 @@ test('full-stack gallery:clear strips the app to a barebones blank slate', async
     assert.doesNotMatch(layout, /--(?:background|foreground|primary):/, 'reset layout ships no design-token palette');
     assert.match(layout, /background:\s*Canvas/, 'reset layout uses OS system colours');
 
+    // The blank slate keeps the asset() marking (#1194). The clear script writes
+    // its OWN layout, so it can silently drop what create.js emitted: an
+    // un-marked /public/tailwind.css sits at a stable url, and a later deploy
+    // then serves the PREVIOUS stylesheet from a CDN or service-worker cache.
+    // This is the reset path an agent runs before building the real app, so a
+    // regression here ships to every app that ever cleared the gallery.
+    assert.match(layout, /href=\$\{asset\('\/public\/tailwind\.css'\)\}/,
+      'reset layout still content-hashes the stylesheet via asset()');
+    assert.match(layout, /import \{[^}]*\basset\b[^}]*\} from '@webjsdev\/core'/,
+      'and imports asset so the reset layout type-checks');
+
     // The reset home is minimal: no <theme-toggle>, no gallery links.
     const home = await readFile(join(appDir, 'app', 'page.ts'), 'utf8');
     assert.doesNotMatch(home, /theme-toggle/, 'reset home drops theme-toggle');
diff --git a/test/scaffolds/scaffold-ui-integration.test.js b/test/scaffolds/scaffold-ui-integration.test.js
index 886a32d43..218eb958a 100644
--- a/test/scaffolds/scaffold-ui-integration.test.js
+++ b/test/scaffolds/scaffold-ui-integration.test.js
@@ -56,8 +56,14 @@ test('full-stack scaffold pre-initialises the Webjs UI kit', async () => {
     // CSS delivery (#947): the layout links a STATIC compiled stylesheet (works
     // with JS off), not the browser runtime. The Tailwind @theme maps live in
     // public/input.css; the token VALUES stay inline in the layout (plain CSS).
-    assert.match(layout, /<link rel="stylesheet" href="\/public\/tailwind\.css">/,
-      'layout links the static compiled stylesheet');
+    // The href goes through asset() (#1194), so the compiled stylesheet carries
+    // a content hash in production and is served immutable: a deploy that
+    // changes the CSS changes the url, and no browser or CDN can serve the old
+    // bytes at the stable path. Still a plain static stylesheet, JS-off safe.
+    assert.match(layout, /<link rel="stylesheet" href=\$\{asset\('\/public\/tailwind\.css'\)\}>/,
+      'layout links the static compiled stylesheet through asset()');
+    assert.match(layout, /import \{[^}]*\basset\b[^}]*\} from '@webjsdev\/core'/,
+      'and imports asset from core');
     assert.doesNotMatch(layout, /tailwind-browser\.js|type="text\/tailwindcss"/,
       'layout no longer ships the Tailwind browser runtime');
     const inputCss = await readFile(join(appDir, 'public', 'input.css'), 'utf8');
diff --git a/test/types/dts-no-phantom-exports.test.mjs b/test/types/dts-no-phantom-exports.test.mjs
index 52f0c552d..ad48c7c28 100644
--- a/test/types/dts-no-phantom-exports.test.mjs
+++ b/test/types/dts-no-phantom-exports.test.mjs
@@ -96,7 +96,7 @@ const BROWSER_SURFACES = [
     name: '@webjsdev/core',
     dir: 'packages/core',
     overlay: 'index.d.ts',
-    intentionalAbsent: ['renderToString', 'renderToStream', 'setCspNonceProvider'],
+    intentionalAbsent: ['renderToString', 'renderToStream', 'setCspNonceProvider', 'setAssetUrlProvider'],
     // Resolve the browser entry AUTHORITATIVELY via the real importmap builder
     // (not a regex on the fallback literal), so a rename in the actual dev-mode
     // mapping follows. `distMode: false` selects the src browser entry
diff --git a/website/app/brand/page.ts b/website/app/brand/page.ts
index 012e61d6c..ab732ecf0 100644
--- a/website/app/brand/page.ts
+++ b/website/app/brand/page.ts
@@ -1,4 +1,4 @@
-import { html } from '@webjsdev/core';
+import { html, asset } from '@webjsdev/core';
 import { BTN_PRIMARY, BTN_GHOST, H2, PROSE } from '#lib/design/recipes.ts';
 import { brandMark } from '#lib/design/brand.ts';
 import { SWATCHES, ACCENTS, type Swatch } from '#lib/design/tokens.ts';
@@ -102,7 +102,7 @@ export default function BrandPage() {
           terms further down the page.
         </p>
         <div class="flex gap-3 flex-wrap">
-          <a class=${BTN_PRIMARY} href="/public/brand/webjs-brand-assets.zip" download>
+          <a class=${BTN_PRIMARY} href=${asset('/public/brand/webjs-brand-assets.zip')} download>
             Download all assets
             <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><polyline points="7 10 12 15 17 10"/><line x1="12" y1="15" x2="12" y2="3"/></svg>
           </a>
@@ -128,12 +128,12 @@ export default function BrandPage() {
           ${ASSETS.map(a => html`
             <div class="flex flex-col rounded-2xl border border-border bg-bg-elev overflow-hidden">
               <div class="h-36 flex items-center justify-center px-7 ${a.on === 'dark' ? 'bg-[oklch(0_0_0)]' : 'bg-[oklch(0.985_0.008_75)]'}">
-                <img src="/public/brand/${a.file}" alt=${a.name} class="max-h-12 w-auto" />
+                <img src=${asset('/public/brand/' + a.file)} alt=${a.name} class="max-h-12 w-auto" />
               </div>
               <div class="flex flex-col flex-1 p-5 border-t border-border">
                 <h3 class="text-sm font-bold text-fg mb-1.5">${a.name}</h3>
                 <p class="text-sm text-fg-muted leading-relaxed flex-1">${a.use}</p>
-                <a href="/public/brand/${a.file}" download class="mt-4 font-mono text-xs text-fg hover:text-accent transition-colors no-underline">
+                <a href=${asset('/public/brand/' + a.file)} download class="mt-4 font-mono text-xs text-fg hover:text-accent transition-colors no-underline">
                   ${a.file} &darr;
                 </a>
               </div>
@@ -159,8 +159,8 @@ export default function BrandPage() {
           <div class="rounded-2xl border border-border bg-bg-elev p-8 flex flex-col">
             <div class="flex-1 flex items-center justify-center">
               <div class="cs-pad cs-guide p-8 rounded">
-                <img src="/public/brand/webjs-lockup-on-dark.svg" alt="Clear space around the lockup" class="h-8 w-auto hidden dark:block" />
-                <img src="/public/brand/webjs-lockup-on-light.svg" alt="Clear space around the lockup" class="h-8 w-auto dark:hidden" />
+                <img src=${asset('/public/brand/webjs-lockup-on-dark.svg')} alt="Clear space around the lockup" class="h-8 w-auto hidden dark:block" />
+                <img src=${asset('/public/brand/webjs-lockup-on-light.svg')} alt="Clear space around the lockup" class="h-8 w-auto dark:hidden" />
               </div>
             </div>
             <div class="mt-7 pt-5 border-t border-border">
@@ -179,8 +179,8 @@ export default function BrandPage() {
                 <p class="mt-3 font-mono text-xs leading-[1.5] text-fg-subtle">24 px<br>monogram floor</p>
               </div>
               <div class="text-center flex flex-col items-center">
-                <img src="/public/brand/webjs-lockup-on-dark.svg" alt="" class="w-24 h-auto hidden dark:block" />
-                <img src="/public/brand/webjs-lockup-on-light.svg" alt="" class="w-24 h-auto dark:hidden" />
+                <img src=${asset('/public/brand/webjs-lockup-on-dark.svg')} alt="" class="w-24 h-auto hidden dark:block" />
+                <img src=${asset('/public/brand/webjs-lockup-on-light.svg')} alt="" class="w-24 h-auto dark:hidden" />
                 <p class="mt-3 font-mono text-xs leading-[1.5] text-fg-subtle">96 px wide<br>lockup floor</p>
               </div>
             </div>
diff --git a/website/app/docs/cache/page.ts b/website/app/docs/cache/page.ts
index 7525fcd83..6c215be51 100644
--- a/website/app/docs/cache/page.ts
+++ b/website/app/docs/cache/page.ts
@@ -102,6 +102,21 @@ export const metadata = {
 
     <p>Note that <code>max-age=0</code> is a common default worth thinking about. It keeps the browser revalidating on every view, which is right when deploys must be visible immediately, but it means a stored copy is never reused directly. A small non-zero value is what produces real browser cache hits on back/forward and repeat visits.</p>
 
+    <h2>Static Assets: asset()</h2>
+    <p>A file in <code>public/</code> is served at a stable url, so after a deploy a browser or CDN can keep serving the PREVIOUS bytes until its cache expires. Wrap the url in <code>asset()</code> and it gains a content hash, which the framework then serves <code>immutable</code> for a year:</p>
+
+    <pre>import { html, asset } from '@webjsdev/core';
+
+export default function RootLayout({ children }) {
+  return html\`&lt;link rel="stylesheet" href=\${asset('/public/app.css')}&gt;\`;
+}</pre>
+
+    <p>In production that renders <code>/public/app.css?v=&lt;hash&gt;</code>. New bytes mean a new url, so no cache can serve a stale copy, and the year-long <code>immutable</code> lifetime is safe precisely because the url changes when the file does. The same url un-marked gets a short <code>max-age</code> instead. <code>asset()</code> resolves on the server; the browser has no resolver and returns the path unchanged. Call it from a <strong>page, layout, or metadata route</strong>, which render only on the server. Inside a component that ships to the browser it quietly forfeits the caching it was for: hydration is a full client re-render, so the bare path overwrites the hashed one and the asset is fetched twice. The url stays valid either way, so this is a convention rather than something <code>webjs check</code> rejects. It is off in development, so dev output stays byte-identical, and only <code>public/</code> paths resolve.</p>
+
+    <p>Two smaller rules follow from how it works. Call <code>asset()</code> <strong>inside the render function</strong>, not at module scope: a top-level call is a side effect the elision analyser reads as client work, so hoisting it into a constant ships the whole page or layout to the browser. And mark only files that change with a <strong>deploy</strong>: the hash is memoized for the process lifetime, so a <code>public/</code> file rewritten in place while the server runs would keep its old url while being served <code>immutable</code> for a year. A compiled stylesheet or a committed image is the right shape; a runtime-written upload is not.</p>
+
+    <p><strong>Mark the thing that FETCHES, not a hint.</strong> Do not wrap a <code>&lt;link rel="preload"&gt;</code> whose asset is really fetched by an <code>@font-face url()</code> in your stylesheet. The preload cache is keyed on the full url, so a versioned hint can never satisfy the un-versioned request the CSS makes, and the file downloads twice. Framework-emitted urls (your modules, the core runtime, vendor bundles) are fingerprinted automatically and need no marking.</p>
+
     <h2>Server HTML Response Cache (export const revalidate)</h2>
     <p>For a page that renders identical HTML for every visitor, opt into the server HTML response cache so the SSR pipeline runs once per window instead of once per request (webjs's no-build equivalent of Next.js's Full Route Cache and ISR). Declare a revalidation window on the page module:</p>
 
diff --git a/website/app/docs/deployment/page.ts b/website/app/docs/deployment/page.ts
index aa9fac412..1e4949313 100644
--- a/website/app/docs/deployment/page.ts
+++ b/website/app/docs/deployment/page.ts
@@ -17,7 +17,7 @@ npm run start -- --port 8080</pre>
     <p>Key differences:</p>
     <ul>
       <li><strong>Dev:</strong> Node's built-in <code>fs.watch</code> watches your source tree and triggers live reload via SSE. TypeScript files are served with <code>Cache-Control: no-cache</code>. Errors include full stack traces. No compression.</li>
-      <li><strong>Prod:</strong> no file watcher, no SSE endpoint. Static files get ETags and <code>Cache-Control: public, max-age=3600</code>. Auto-vendored npm packages get <code>max-age=31536000, immutable</code>. Gzip and Brotli compression are enabled. Error responses omit stack traces.</li>
+      <li><strong>Prod:</strong> no file watcher, no SSE endpoint. Static files get ETags and <code>Cache-Control: public, max-age=3600</code>, unless the url carries a content hash, which promotes it to <code>max-age=31536000, immutable</code>. Served modules get that hash automatically; a <code>public/</code> asset gets it when you mark the url with <code>asset()</code>. Auto-vendored npm packages get <code>max-age=31536000, immutable</code>. Gzip and Brotli compression are enabled. Error responses omit stack traces.</li>
     </ul>
 
     <h2>No build step</h2>
@@ -34,7 +34,7 @@ npm run start -- --port 8080</pre>
     <p>In production mode, WebJs automatically negotiates <code>Accept-Encoding</code> and compresses responses with Brotli (quality 4) or Gzip (level 6). Compression applies to text-based content types: HTML, JavaScript, JSON, CSS, SVG, XML. Binary assets (images, fonts) are served uncompressed.</p>
 
     <h3>ETags and Cache Headers</h3>
-    <p>Static files are served with a SHA-1 ETag and a 1-hour <code>max-age</code>. Vendor npm packages resolve through importmap to jspm.io URLs (default) or to local <code>/__webjs/vendor/&lt;pkg&gt;@&lt;version&gt;.js</code> paths (after <code>webjs vendor pin --download</code>). Direct jspm.io URLs use jspm.io's own immutable headers; locally-served <code>--download</code> bundles use <code>max-age=31536000, immutable</code>. In dev, all files use <code>Cache-Control: no-cache</code>.</p>
+    <p>Static files are served with a SHA-1 ETag and a 1-hour <code>max-age</code>, which is the fallback for an un-versioned url. Any request carrying a <code>?v=</code> content hash is served <code>max-age=31536000, immutable</code> instead, since a change to the bytes changes the url. Served modules are hashed automatically; mark a <code>public/</code> asset with <code>asset()</code> to opt it in (see <a href="/docs/cache">Caching</a>). Vendor npm packages resolve through importmap to jspm.io URLs (default) or to local <code>/__webjs/vendor/&lt;pkg&gt;@&lt;version&gt;.js</code> paths (after <code>webjs vendor pin --download</code>). Direct jspm.io URLs use jspm.io's own immutable headers; locally-served <code>--download</code> bundles use <code>max-age=31536000, immutable</code>. In dev, all files use <code>Cache-Control: no-cache</code>.</p>
 
     <h3>Conditional GET (ETag + If-None-Match)</h3>
     <p>Every <em>cacheable</em> response carries a content-hash <code>ETag</code>, and a repeat request whose <code>If-None-Match</code> matches it gets a <code>304 Not Modified</code> with no body (RFC 7232). A client holding an identical copy revalidates with a tiny 304 instead of re-downloading the whole body. This applies uniformly to static assets, app source modules, the core / vendor runtime, and to SSR HTML pages that opt into caching via <code>metadata.cacheControl</code>. The ETag is a <em>weak</em> validator (<code>W/"..."</code>), since it is computed over the uncompressed body and reused across the identity, gzip, and Brotli encodings, which a strong validator may not do (RFC 7232 2.3.3).</p>
diff --git a/website/app/layout.ts b/website/app/layout.ts
index 083d161b7..f252ae20c 100644
--- a/website/app/layout.ts
+++ b/website/app/layout.ts
@@ -1,4 +1,4 @@
-import { html, cspNonce } from '@webjsdev/core';
+import { html, cspNonce, asset } from '@webjsdev/core';
 import '#components/theme-toggle.ts';
 import { DOCS_START_PATH, UI_PATH, GH_URL, NEW_TAB } from '#lib/links.ts';
 import { siteFooter } from '#lib/ui/site-footer.ts';
@@ -229,7 +229,7 @@ export default function RootLayout({ children }: { children: unknown }) {
       });
     </script>
 
-    <link rel="stylesheet" href="/public/tailwind.css">
+    <link rel="stylesheet" href=${asset('/public/tailwind.css')}>
     <style>
       /* Foundation tokens + effects that Tailwind utilities cannot express. */
       /* A single static gradient glow layer. It used to breathe (two layers
@@ -439,6 +439,6 @@ export default function RootLayout({ children }: { children: unknown }) {
          by the client router: a copy inside the swap range would depend on
          the router re-executing it, and would never run at all for a reader
          whose first docs page arrives by soft navigation. -->
-    <script src="/public/code-highlight.js" defer nonce="${nonce}"></script>
+    <script src=${asset('/public/code-highlight.js')} defer nonce="${nonce}"></script>
   `;
 }
diff --git a/website/lib/design/brand.ts b/website/lib/design/brand.ts
index d6de79c66..f41eedf6a 100644
--- a/website/lib/design/brand.ts
+++ b/website/lib/design/brand.ts
@@ -1,4 +1,4 @@
-import { html } from '@webjsdev/core';
+import { html, asset } from '@webjsdev/core';
 
 /**
  * The brand marks.
@@ -16,6 +16,14 @@ import { html } from '@webjsdev/core';
  * hidden variant's download is noise.
  */
 
+// Paths, not resolved urls. `asset()` is called at RENDER time below, never at
+// module scope. The reason is not resolver ordering (the server installs its
+// resolver at boot, before any app module loads, so a module-scope call would
+// in fact resolve): a depth-0 call is a module-scope SIDE EFFECT, and the
+// elision analyser treats that as client work, which pins the whole importing
+// page or layout into the browser bundle. Hoisting the constant here would
+// therefore ship this module and its importer for no benefit. Calling inside
+// the template keeps the module inert and costs a memoized lookup.
 const LOCKUP_DARK = '/public/brand/webjs-lockup-on-dark.svg';
 const LOCKUP_LIGHT = '/public/brand/webjs-lockup-on-light.svg';
 
@@ -37,8 +45,8 @@ export function brandLockup(_id: string, opts: { height?: number } = {}) {
   const cls = `block w-auto`;
   return html`
     <span class="inline-flex items-center" style="height:${h}px">
-      <img src=${LOCKUP_DARK} alt="WebJs" width=${Math.round(h * RATIO)} height=${h} class="${cls} hidden dark:block" style="height:${h}px" />
-      <img src=${LOCKUP_LIGHT} alt="WebJs" width=${Math.round(h * RATIO)} height=${h} class="${cls} dark:hidden" style="height:${h}px" />
+      <img src=${asset(LOCKUP_DARK)} alt="WebJs" width=${Math.round(h * RATIO)} height=${h} class="${cls} hidden dark:block" style="height:${h}px" />
+      <img src=${asset(LOCKUP_LIGHT)} alt="WebJs" width=${Math.round(h * RATIO)} height=${h} class="${cls} dark:hidden" style="height:${h}px" />
     </span>
   `;
 }
@@ -55,8 +63,8 @@ export function brandMark(_id: string, opts: { height?: number } = {}) {
   const h = opts.height ?? 24;
   return html`
     <span class="inline-flex items-center" style="height:${h}px">
-      <img src="/public/brand/webjs-mark-on-dark.svg" alt="WebJs" class="block w-auto hidden dark:block" style="height:${h}px" />
-      <img src="/public/brand/webjs-mark-on-light.svg" alt="WebJs" class="block w-auto dark:hidden" style="height:${h}px" />
+      <img src=${asset('/public/brand/webjs-mark-on-dark.svg')} alt="WebJs" class="block w-auto hidden dark:block" style="height:${h}px" />
+      <img src=${asset('/public/brand/webjs-mark-on-light.svg')} alt="WebJs" class="block w-auto dark:hidden" style="height:${h}px" />
     </span>
   `;
 }