@weft-js/start 0.1.1 → 0.1.2

package/crate/src/native.rs

@@ -0,0 +1,212 @@
+//! `native()` (PLAN §4.3, research 39): a service's functions in-process. One crossing per function, as with a sidecar,
+//! with no HTTP and no signature: nothing outside the process can reach it.
+//!
+//! A real addon runs each call on the host's worker pool, so a long one doesn't hold the event loop. A `.wasm` is the
+//! same code behind a small ABI of its own, on whatever thread calls it. Neither brings an async runtime: this is for
+//! CPU, and a function that waits on IO belongs in `remote()`.
+
+use std::future::Future;
+use std::panic::{AssertUnwindSafe, catch_unwind};
+use std::pin::pin;
+use std::sync::OnceLock;
+use std::task::{Context, Poll, Waker};
+
+use serde_json::json;
+
+use crate::ctx::{Base, Envelope};
+use crate::functions::{Answer, Failed, Functions, drift_body, internal_body, ok_body, panic_text};
+
+static MAKE: OnceLock<fn() -> Functions> = OnceLock::new();
+static FUNCTIONS: OnceLock<Functions> = OnceLock::new();
+
+/// Called once by `weft::native!`. The service is built on the first call, not while the library loads.
+pub fn install(make: fn() -> Functions) {
+    let _ = MAKE.set(make);
+}
+
+fn functions() -> &'static Functions {
+    FUNCTIONS.get_or_init(|| MAKE.get().expect("weft::native! ran")())
+}
+
+/// `{ service, hash, functions }`: TS refuses a library built from another contract (R103).
+fn contract() -> String {
+    let f = functions();
+    json!({ "service": f.service(), "hash": f.hash(), "functions": f.ids() }).to_string()
+}
+
+#[cfg(not(target_family = "wasm"))]
+fn wait<F: Future>(mut future: std::pin::Pin<&mut F>) -> F::Output {
+    struct Unpark(std::thread::Thread);
+    impl std::task::Wake for Unpark {
+        fn wake(self: std::sync::Arc<Self>) {
+            self.0.unpark();
+        }
+    }
+    let waker = Waker::from(std::sync::Arc::new(Unpark(std::thread::current())));
+    let mut cx = Context::from_waker(&waker);
+    loop {
+        match future.as_mut().poll(&mut cx) {
+            Poll::Ready(v) => return v,
+            Poll::Pending => std::thread::park(),
+        }
+    }
+}
+
+#[cfg(target_family = "wasm")]
+fn wait<F: Future>(future: std::pin::Pin<&mut F>) -> F::Output {
+    match future.poll(&mut Context::from_waker(Waker::noop())) {
+        Poll::Ready(v) => v,
+        Poll::Pending => {
+            panic!(
+                "a `native()` function can't wait on WASM: nothing would wake it. Use `remote()` for IO"
+            )
+        }
+    }
+}
+
+/// One call, start to finish, on this thread.
+fn dispatch(id: &str, ctx: &str, body: Vec<u8>) -> String {
+    let envelope: Envelope = match serde_json::from_str(ctx) {
+        Ok(e) => e,
+        Err(e) => return drift_body(&format!("the call's context didn't parse: {e}")).to_string(),
+    };
+    let Some(handler) = functions().handler(id) else {
+        return drift_body(&format!(
+            "this library has no function `{id}`: rebuild it from the current contract"
+        ))
+        .to_string();
+    };
+    let base = Base::new(id, envelope);
+    let call = handler(base.clone(), body);
+    let answer = catch_unwind(AssertUnwindSafe(|| wait(pin!(call)))).unwrap_or_else(|p| {
+        Answer::Failed(Failed::Internal(format!("panicked: {}", panic_text(&*p))))
+    });
+    match answer {
+        Answer::Value(value) => ok_body(&value, &base),
+        Answer::Failed(Failed::Typed(error)) => json!({ "ok": false, "error": error }).to_string(),
+        Answer::Failed(Failed::Internal(detail)) => internal_body(&base, Some(&detail)).to_string(),
+        Answer::Drift(detail) => drift_body(&detail).to_string(),
+    }
+}
+
+#[cfg(not(target_family = "wasm"))]
+mod addon {
+    use napi::bindgen_prelude::{AsyncTask, Env, Result, Task};
+    use napi_derive::napi;
+
+    pub struct Call {
+        id: String,
+        ctx: String,
+        body: Option<String>,
+    }
+
+    impl Task for Call {
+        type Output = String;
+        type JsValue = String;
+
+        fn compute(&mut self) -> Result<String> {
+            Ok(super::dispatch(
+                &self.id,
+                &self.ctx,
+                self.body.take().unwrap_or_default().into_bytes(),
+            ))
+        }
+
+        fn resolve(&mut self, _: Env, reply: String) -> Result<String> {
+            Ok(reply)
+        }
+    }
+
+    #[napi]
+    pub fn call(id: String, ctx: String, body: String) -> AsyncTask<Call> {
+        AsyncTask::new(Call {
+            id,
+            ctx,
+            body: Some(body),
+        })
+    }
+
+    #[napi]
+    pub fn contract() -> String {
+        super::contract()
+    }
+}
+
+/// A pointer and a length in one number: the only return value this ABI needs, and it fits a JS `BigInt`.
+#[cfg(target_family = "wasm")]
+mod wasm {
+    #[link(wasm_import_module = "weft")]
+    unsafe extern "C" {
+        fn now() -> f64;
+        fn panicked(ptr: *const u8, len: usize);
+    }
+
+    fn give(text: String) -> u64 {
+        let bytes = text.into_bytes().into_boxed_slice();
+        let len = bytes.len() as u64;
+        ((Box::into_raw(bytes).cast::<u8>() as u64) << 32) | len
+    }
+
+    /// # Safety
+    /// `ptr` and `len` are valid UTF-8 that outlives `'a`.
+    unsafe fn text<'a>(ptr: *const u8, len: usize) -> &'a str {
+        // SAFETY: the caller's contract above.
+        unsafe { std::str::from_utf8_unchecked(std::slice::from_raw_parts(ptr, len)) }
+    }
+
+    #[unsafe(no_mangle)]
+    pub extern "C" fn weft_alloc(len: usize) -> *mut u8 {
+        Box::into_raw(vec![0u8; len].into_boxed_slice()).cast::<u8>()
+    }
+
+    /// # Safety
+    /// `ptr` and `len` are what `weft_alloc`, `weft_call` or `weft_contract` handed out.
+    #[unsafe(no_mangle)]
+    pub unsafe extern "C" fn weft_free(ptr: *mut u8, len: usize) {
+        // SAFETY: the caller hands back a boxed slice of exactly `len` bytes.
+        drop(unsafe { Box::from_raw(std::ptr::slice_from_raw_parts_mut(ptr, len)) });
+    }
+
+    /// `body` is the caller's, and is taken over, as `weft_alloc` gave it.
+    ///
+    /// # Safety
+    /// Each pair is valid UTF-8 from `weft_alloc`.
+    #[unsafe(no_mangle)]
+    pub unsafe extern "C" fn weft_call(
+        id: *const u8,
+        id_len: usize,
+        ctx: *const u8,
+        ctx_len: usize,
+        body: *mut u8,
+        body_len: usize,
+    ) -> u64 {
+        // A panic aborts here: the instance traps, and TS starts a new one. This is how the message gets out first.
+        static HOOK: std::sync::Once = std::sync::Once::new();
+        HOOK.call_once(|| {
+            std::panic::set_hook(Box::new(|info| {
+                let message = info.to_string();
+                // SAFETY: the host copies the bytes out during the call; `message` is live and UTF-8.
+                unsafe { panicked(message.as_ptr(), message.len()) }
+            }));
+        });
+        // SAFETY: `body` is a `weft_alloc` box of `body_len` bytes, and it's ours now.
+        let body =
+            unsafe { Box::from_raw(std::ptr::slice_from_raw_parts_mut(body, body_len)) }.into_vec();
+        // SAFETY: the caller keeps both strings, valid UTF-8, for the whole call.
+        let (id, ctx) = unsafe { (text(id, id_len), text(ctx, ctx_len)) };
+        give(super::dispatch(id, ctx, body))
+    }
+
+    #[unsafe(no_mangle)]
+    pub extern "C" fn weft_contract() -> u64 {
+        give(super::contract())
+    }
+
+    pub(crate) fn time() -> f64 {
+        // SAFETY: a plain import: no arguments, no memory.
+        unsafe { now() }
+    }
+}
+
+#[cfg(target_family = "wasm")]
+pub(crate) use wasm::time as now_ms;

package/crate/src/otel.rs

@@ -0,0 +1,62 @@
+//! With the `otel` feature, a call's span continues the trace TS started: the app installs an OpenTelemetry layer, and
+//! the envelope's `traceparent` becomes the parent. Without one, `trace_id` and `parent_id` are plain span fields.
+
+use opentelemetry::Context;
+use opentelemetry::trace::{SpanContext, SpanId, TraceContextExt, TraceFlags, TraceId, TraceState};
+use tracing_opentelemetry::OpenTelemetrySpanExt;
+
+pub(crate) fn parent(traceparent: &str) -> Option<SpanContext> {
+    let mut parts = traceparent.split('-');
+    let (version, trace, span, flags) =
+        (parts.next()?, parts.next()?, parts.next()?, parts.next()?);
+    if version != "00" {
+        return None;
+    }
+    let trace = TraceId::from_hex(trace)
+        .ok()
+        .filter(|t| *t != TraceId::INVALID)?;
+    let span = SpanId::from_hex(span)
+        .ok()
+        .filter(|s| *s != SpanId::INVALID)?;
+    let flags = TraceFlags::new(u8::from_str_radix(flags, 16).ok()?);
+    Some(SpanContext::new(
+        trace,
+        span,
+        flags,
+        true,
+        TraceState::default(),
+    ))
+}
+
+pub(crate) fn link(span: &tracing::Span, traceparent: Option<&str>) {
+    if let Some(remote) = traceparent.and_then(parent) {
+        let _ = span.set_parent(Context::new().with_remote_span_context(remote));
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn reads_a_w3c_traceparent() {
+        let p = parent("00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01").unwrap();
+        assert_eq!(p.trace_id().to_string(), "4bf92f3577b34da6a3ce929d0e0e4736");
+        assert_eq!(p.span_id().to_string(), "00f067aa0ba902b7");
+        assert!(p.is_sampled());
+        assert!(p.is_remote());
+    }
+
+    #[test]
+    fn refuses_what_isnt_one() {
+        for bad in [
+            "",
+            "junk",
+            "01-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
+            "00-00000000000000000000000000000000-00f067aa0ba902b7-01",
+            "00-4bf92f3577b34da6a3ce929d0e0e4736-0000000000000000-01",
+        ] {
+            assert!(parent(bad).is_none(), "{bad}");
+        }
+    }
+}

package/crate/src/server.rs

@@ -0,0 +1,203 @@
+//! `weft::router()`: an axum `Router`, so a sidecar can be one binary or part of a Loco or axum app. Each call is
+//! verified, deserialized, run in its own task with a deadline, and answered as
+//!
+//! ```text
+//! { "ok": true, "value": …, "tags": […], "touched": […] }
+//! { "ok": false, "error": { "code": "NotFound", "data": … } }
+//! ```
+
+use std::sync::Arc;
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
+
+use axum::Router;
+use axum::body::Bytes;
+use axum::extract::{Path, State};
+use axum::http::{HeaderMap, StatusCode, header};
+use axum::response::{IntoResponse, Response};
+use axum::routing::{get, post};
+use serde_json::{Value, json};
+use tracing::Instrument;
+
+use crate::ctx::Base;
+use crate::envelope::{Envelope, verify};
+use crate::functions::{Answer, Failed, Functions, drift_body, internal_body, ok_body};
+
+struct Shared {
+    functions: Functions,
+    secret: Vec<u8>,
+}
+
+/// The `Router`: `POST /_weft/fn/:id`, and `GET /_weft/health` for the supervisor. The key comes from `WEFT_RUST_SECRET`.
+///
+/// # Panics
+/// With no `WEFT_RUST_SECRET`: a sidecar that took unsigned calls would trust any process that could reach it.
+pub fn router(functions: Functions) -> Router {
+    let secret = std::env::var("WEFT_RUST_SECRET").unwrap_or_default();
+    assert!(
+        !secret.is_empty(),
+        "R106: WEFT_RUST_SECRET is not set. `weft dev` and `weft start` set it; a sidecar deployed on its own needs the same value as the server"
+    );
+    router_with(functions, secret.into_bytes())
+}
+
+/// [`router`] with the key in hand.
+pub fn router_with(functions: Functions, secret: Vec<u8>) -> Router {
+    Router::new()
+        .route("/_weft/fn/{id}", post(call))
+        .route("/_weft/health", get(health))
+        .with_state(Arc::new(Shared { functions, secret }))
+}
+
+async fn health(State(s): State<Arc<Shared>>) -> Response {
+    json_response(
+        StatusCode::OK,
+        &json!({ "ok": true, "service": s.functions.service(), "contract": s.functions.hash(), "functions": s.functions.ids(), "pid": std::process::id() }),
+    )
+}
+
+fn json_response(status: StatusCode, body: &Value) -> Response {
+    text_response(status, body.to_string())
+}
+
+fn text_response(status: StatusCode, body: String) -> Response {
+    (status, [(header::CONTENT_TYPE, "application/json")], body).into_response()
+}
+
+fn refused(status: StatusCode, code: &str, message: impl std::fmt::Display) -> Response {
+    json_response(
+        status,
+        &json!({ "ok": false, "error": { "code": code, "message": message.to_string() } }),
+    )
+}
+
+fn now_ms() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map_or(0, |d| d.as_millis() as u64)
+}
+
+/// `00-<trace>-<span>-<flags>` split, or nothing if it isn't one.
+fn trace_ids(traceparent: Option<&str>) -> (&str, &str) {
+    let mut parts = traceparent.unwrap_or("").split('-');
+    match (parts.next(), parts.next(), parts.next()) {
+        (Some("00"), Some(trace), Some(span)) if trace.len() == 32 && span.len() == 16 => {
+            (trace, span)
+        }
+        _ => ("", ""),
+    }
+}
+
+/// Dropping this stops the task: axum drops the handler's future when TS hangs up.
+struct AbortOnDrop(tokio::task::AbortHandle);
+impl Drop for AbortOnDrop {
+    fn drop(&mut self) {
+        self.0.abort();
+    }
+}
+
+async fn call(
+    State(s): State<Arc<Shared>>,
+    Path(id): Path<String>,
+    headers: HeaderMap,
+    body: Bytes,
+) -> Response {
+    let text = |name: &str| headers.get(name).and_then(|v| v.to_str().ok());
+    let (Some(ctx), Some(sig)) = (text("weft-ctx"), text("weft-sig")) else {
+        return refused(
+            StatusCode::UNAUTHORIZED,
+            "Refused",
+            crate::envelope::Refused::Malformed,
+        );
+    };
+    let envelope: Envelope = match verify(&s.secret, &id, ctx, sig, &body, now_ms()) {
+        Ok(e) => e,
+        Err(e) => return refused(StatusCode::UNAUTHORIZED, "Refused", e),
+    };
+    let Some(handler) = s.functions.handler(&id) else {
+        return refused(
+            StatusCode::NOT_FOUND,
+            "Drift",
+            format!("this sidecar has no function `{id}`: rebuild it from the current contract"),
+        );
+    };
+    let budget = Duration::from_millis(envelope.deadline_ms);
+    let base = Base::new(&id, envelope);
+    let (trace_id, parent_id) = trace_ids(base.traceparent());
+    let span = tracing::info_span!(
+        "weft.fn",
+        otel.name = id.as_str(),
+        function = id.as_str(),
+        request_id = base.request_id(),
+        trace_id,
+        parent_id
+    );
+    #[cfg(feature = "otel")]
+    crate::otel::link(&span, base.traceparent());
+
+    // A task of its own, so a panic is one failed call and not a dropped connection.
+    let task = tokio::spawn(handler(base.clone(), Vec::from(body)).instrument(span.clone()));
+    let _abort = AbortOnDrop(task.abort_handle());
+    let outcome = tokio::time::timeout(budget, task).await;
+    let _enter = span.enter();
+    let answer = match outcome {
+        Ok(Ok(answer)) => answer,
+        Ok(Err(e)) if e.is_panic() => Answer::Failed(Failed::Internal(format!(
+            "panicked: {}",
+            crate::functions::panic_text(&*e.into_panic())
+        ))),
+        Ok(Err(e)) => Answer::Failed(Failed::Internal(e.to_string())),
+        Err(_) => {
+            tracing::warn!(budget_ms = budget.as_millis() as u64, "deadline passed");
+            return refused(
+                StatusCode::GATEWAY_TIMEOUT,
+                "Deadline",
+                format!("`{id}` ran past its deadline"),
+            );
+        }
+    };
+    match answer {
+        Answer::Value(value) => text_response(StatusCode::OK, ok_body(&value, &base)),
+        Answer::Failed(Failed::Typed(error)) => {
+            json_response(StatusCode::OK, &json!({ "ok": false, "error": error }))
+        }
+        Answer::Failed(Failed::Internal(detail)) => {
+            tracing::error!(detail, "failed");
+            json_response(
+                StatusCode::INTERNAL_SERVER_ERROR,
+                &internal_body(&base, None),
+            )
+        }
+        Answer::Drift(detail) => {
+            tracing::error!(detail, "drift");
+            json_response(StatusCode::UNPROCESSABLE_ENTITY, &drift_body(&detail))
+        }
+    }
+}
+
+/// Serve on `WEFT_LISTEN` (`127.0.0.1:0` when unset), print `weft-listening <addr>` for the supervisor, and drain on
+/// SIGTERM or Ctrl-C. Logs go to stderr, by `RUST_LOG` (`info`), unless the app installed a subscriber first.
+pub async fn serve(router: Router) -> std::io::Result<()> {
+    use tracing_subscriber::EnvFilter;
+    let filter = EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new("info"));
+    let _ = tracing_subscriber::fmt()
+        .with_env_filter(filter)
+        .with_writer(std::io::stderr)
+        .try_init();
+    let addr = std::env::var("WEFT_LISTEN").unwrap_or_else(|_| "127.0.0.1:0".into());
+    let listener = tokio::net::TcpListener::bind(&addr).await?;
+    println!("weft-listening {}", listener.local_addr()?);
+    axum::serve(listener, router)
+        .with_graceful_shutdown(stopped())
+        .await
+}
+
+async fn stopped() {
+    #[cfg(unix)]
+    {
+        use tokio::signal::unix::{SignalKind, signal};
+        let mut term = signal(SignalKind::terminate()).expect("a SIGTERM handler");
+        tokio::select! { _ = term.recv() => {}, _ = tokio::signal::ctrl_c() => {} }
+    }
+    #[cfg(not(unix))]
+    let _ = tokio::signal::ctrl_c().await;
+}

package/package.json

@@ -1,28 +1,31 @@
 {
   "name": "@weft-js/start",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "weft Start: file routes, server functions, streaming SSR, a database and auth",
+  "keywords": [
+    "weft"
+  ],
   "license": "MIT",
-  "type": "module",
-  "dependencies": {
-    "@fontsource/inter": "5.3.0",
-    "@takumi-rs/core": "2.18.2",
-    "@takumi-rs/helpers": "2.18.2",
-    "@takumi-rs/wasm": "2.18.2",
-    "@tanstack/history": "1.162.5",
-    "@tanstack/router-core": "1.171.39",
-    "nitro": "3.0.260903-beta",
-    "vite": "8.3.5"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ravonus/weft.git",
+    "directory": "packages/start"
   },
-  "peerDependencies": {
-    "better-auth": "^1.7.0",
-    "drizzle-orm": "^0.45.0",
-    "drizzle-zod": "^0.8.0",
-    "mysql2": "^3.24.0",
-    "postgres": ">=3",
-    "@weft-js/core": "^0.1.1",
-    "zod": "^4.0.0"
+  "homepage": "https://github.com/Ravonus/weft/tree/main/packages/start#readme",
+  "bugs": {
+    "url": "https://github.com/Ravonus/weft/issues"
   },
+  "files": [
+    "src",
+    "crate",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "**/*.css",
+    "./src/share.ts"
+  ],
   "exports": {
     ".": "./src/index.ts",
     "./data": "./src/data.ts",
@@ -61,10 +64,28 @@
     "./rust": "./src/rust.ts",
     "./sidecar": "./src/sidecar.mjs"
   },
-  "sideEffects": [
-    "**/*.css",
-    "./src/share.ts"
-  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@fontsource/inter": "5.3.0",
+    "@takumi-rs/core": "2.18.2",
+    "@takumi-rs/helpers": "2.18.2",
+    "@takumi-rs/wasm": "2.18.2",
+    "@tanstack/history": "1.162.5",
+    "@tanstack/router-core": "1.171.39",
+    "nitro": "3.0.260903-beta",
+    "vite": "8.3.5"
+  },
+  "peerDependencies": {
+    "@weft-js/core": "^0.1.2",
+    "better-auth": "^1.7.0",
+    "drizzle-orm": "^0.45.0",
+    "drizzle-zod": "^0.8.0",
+    "mysql2": "^3.24.0",
+    "postgres": ">=3",
+    "zod": "^4.0.0"
+  },
   "peerDependenciesMeta": {
     "better-auth": {
       "optional": true
@@ -91,19 +112,7 @@
       "optional": true
     }
   },
-  "publishConfig": {
-    "access": "public"
-  },
   "engines": {
     "node": ">=26"
-  },
-  "keywords": [
-    "weft"
-  ],
-  "files": [
-    "src",
-    "crate",
-    "README.md",
-    "LICENSE"
-  ]
-}
+  }
+}

package/src/app.mjs

@@ -15,21 +15,39 @@ import weftStart, { startDir } from './vite.mjs'
 function usesSockets(root) {
   const src = join(root, 'src')
   if (!existsSync(src)) return false
-  return readdirSync(src, { recursive: true, withFileTypes: true }).some(f => f.isFile() && /\.[cm]?[jt]sx?$/.test(f.name) && /\b(channel|sharedState)\s*[(<]/.test(readFileSync(join(f.parentPath, f.name), 'utf8')))
+  return readdirSync(src, { recursive: true, withFileTypes: true }).some(
+    (f) =>
+      f.isFile() &&
+      /\.[cm]?[jt]sx?$/.test(f.name) &&
+      /\b(channel|sharedState)\s*[(<]/.test(readFileSync(join(f.parentPath, f.name), 'utf8')),
+  )
 }
 
-function config({ root, site, hydration, preset, port, logLevel, command, nitro: nitroOptions = {} }) {
+function config({
+  root,
+  site,
+  hydration,
+  preset,
+  port,
+  logLevel,
+  command,
+  nitro: nitroOptions = {},
+}) {
   root = resolve(root)
   const sockets = usesSockets(root)
   const runner = devRunner(sockets)
-  const user = ['vite.config.ts', 'vite.config.mts', 'vite.config.js', 'vite.config.mjs'].map(f => join(root, f)).find(existsSync)
+  const user = ['vite.config.ts', 'vite.config.mts', 'vite.config.js', 'vite.config.mjs']
+    .map((f) => join(root, f))
+    .find(existsSync)
   return {
     root,
     configFile: user ?? false,
     logLevel,
     server: { port: port ?? 5173, strictPort: port !== undefined },
     // A function host can't hold a socket: the page goes straight to SSE, and a channel says `unavailable` (R024)
-    ...(command === 'build' && { define: { __WEFT_SOCKETS__: JSON.stringify(holdsSockets(preset)) } }),
+    ...(command === 'build' && {
+      define: { __WEFT_SOCKETS__: JSON.stringify(holdsSockets(preset)) },
+    }),
     plugins: [
       weft({ hydratable: true }),
       weftStart({ root, site, hydration }),
@@ -38,7 +56,11 @@ function config({ root, site, hydration, preset, port, logLevel, command, nitro:
         preset,
         // Every app gets this: built assets ship as .br and .gz next to the file, and Nitro picks by Accept-Encoding.
         compressPublicAssets: { gzip: true, brotli: true },
-        ...(site?.headers && { routeRules: Object.fromEntries(Object.entries(site.headers).map(([path, headers]) => [path, { headers }])) }),
+        ...(site?.headers && {
+          routeRules: Object.fromEntries(
+            Object.entries(site.headers).map(([path, headers]) => [path, { headers }]),
+          ),
+        }),
         ...(sockets && { features: { websocket: true } }),
         ...(runner && { devServer: { runner } }),
         // Build mode for share cards (research 20 §4.3): the server lists them and Nitro's prerender writes the PNGs.
@@ -46,9 +68,14 @@ function config({ root, site, hydration, preset, port, logLevel, command, nitro:
         // Prerendered cards are static files at content-addressed URLs: immutable. The rule names each file (a
         // `/_weft/og/**` rule would also override the handler's no-cache for a stale `?v=` on demand). Prerender runs
         // before Nitro bundles the server, so rules added when it is done are in the build. (Dev sends no-store.)
-        ...(command === 'build' && { hooks: immutableCards(), plugins: [fileURLToPath(new URL('./range.mjs', import.meta.url))] }),
+        ...(command === 'build' && {
+          hooks: immutableCards(),
+          plugins: [fileURLToPath(new URL('./range.mjs', import.meta.url))],
+        }),
         // The media route: sharp's addon, and css-tree and csso (under svgo) read JSON from their packages at runtime.
-        ...(existsSync(join(root, '.weft/slots/media.server.ts')) && { traceDeps: ['css-tree*', 'csso*', 'sharp*'] }),
+        ...(existsSync(join(root, '.weft/slots/media.server.ts')) && {
+          traceDeps: ['css-tree*', 'csso*', 'sharp*'],
+        }),
         ...nitroOptions,
       }),
     ],
@@ -69,7 +96,10 @@ function immutableCards() {
     'prerender:done'({ prerenderedRoutes }) {
       if (!built) return
       for (const r of prerenderedRoutes) {
-        if (r.route.startsWith('/_weft/og/') && r.route.endsWith('.png')) built.options.routeRules[r.route] = { headers: { 'cache-control': 'public, max-age=31536000, immutable' } }
+        if (r.route.startsWith('/_weft/og/') && r.route.endsWith('.png'))
+          built.options.routeRules[r.route] = {
+            headers: { 'cache-control': 'public, max-age=31536000, immutable' },
+          }
       }
       built.routing.sync()
     },

package/src/asset-receipt.d.mts

@@ -0,0 +1,13 @@
+import type { AssetReceipt, RouteAssetCosts } from './router'
+
+/** Select only matched levels and union their emitted files for this build. */
+export function selectRouteAssets(
+  receipt: AssetReceipt | null | undefined,
+  build: string | undefined,
+  ids: string[],
+): RouteAssetCosts | null
+/** The costs, if they were measured for this build. */
+export function matchingRouteAssets(
+  costs: RouteAssetCosts | undefined,
+  build: string | null | undefined,
+): RouteAssetCosts | null