akanjs 3.0.0-beta.20 → 3.0.0-beta.21

package/vendor/@akanjs/native/native/desktop/src/panels.rs

@@ -0,0 +1,333 @@
+//! Native sheets on an app window (plugins.md Q-P6 (b)): NSOpenPanel and NSSavePanel for the
+//! file-picker plugin, NSAlert for the dialog plugin. A sheet answers later, from its completion
+//! handler, so these ops take the shell request id and call `super::reply` themselves.
+//!
+//! - Sheets, not app-modal panels: the other windows keep working, and a second sheet on the same
+//!   window is queued by AppKit (Tauri's dialog plugin also passes the parent window to rfd,
+//!   tauri-plugins-workspace/plugins/dialog/src/desktop.rs:100-101). The window is shown first when
+//!   it is hidden: a sheet on a hidden window never appears and its handler never runs.
+//! - Types: MIME types and extensions become UTTypes (UniformTypeIdentifiers, reached through the
+//!   objc2 runtime; no `objc2-uniform-type-identifiers` crate, plugins.md Q-P6). A type without a
+//!   registered UTType turns the filter off, so a file is never unpickable (the rule of the earlier
+//!   osascript version).
+//! - The app is not sandboxed, so the picked URLs need no security-scoped access; the panel still
+//!   grants this process files in TCC-protected folders (~/Documents), and the plugin host copies
+//!   them in-process. A sandboxed build would need startAccessingSecurityScopedResource.
+//! - Tests (dev builds only): with AKAN_NATIVE_TEST_PANELS set, every sheet is ended by a timer instead of
+//!   a click, through the same completion handlers (`TestAnswers`, dialog_args.rs, shared with Windows and Linux).
+
+use block2::RcBlock;
+use objc2::{
+  msg_send,
+  rc::Retained,
+  runtime::{AnyClass, AnyObject},
+  MainThreadMarker, Message,
+};
+use objc2_app_kit::{NSAlert, NSAlertFirstButtonReturn, NSModalResponse, NSModalResponseAbort, NSModalResponseOK, NSOpenPanel, NSSavePanel, NSTextField, NSWindow};
+use objc2_foundation::{NSArray, NSPoint, NSRect, NSSize, NSString, NSURL};
+use tao::platform::macos::WindowExtMacOS;
+
+use crate::dialog_args::{alert_answer, json_list, mime_answer, open_answer, save_answer, strings, Alert, CANCELLED};
+use crate::json::{self, V};
+
+#[link(name = "UniformTypeIdentifiers", kind = "framework")]
+extern "C" {}
+
+/// Handles `panel.*` and `alert.*` shell ops. Returns false for any other op.
+pub fn shell_op(id: u64, json: &str, windows: &super::Windows) -> bool {
+  if !json.contains("\"panel.") && !json.contains("\"alert.") {
+    return false;
+  }
+  let Ok(cmd) = json::parse(json) else { return false };
+  let Some(op) = cmd.get("op").and_then(|v| v.as_str()) else { return false };
+  if !op.starts_with("panel.") && !op.starts_with("alert.") {
+    return false;
+  }
+  if let Err(e) = run(id, op, &cmd, windows) {
+    super::reply(id, Err(e));
+  }
+  true
+}
+
+thread_local! {
+  /// Alert sheets on screen by tag (main thread): the parent window and the sheet.
+  static OPEN_ALERTS: std::cell::RefCell<std::collections::HashMap<String, (Retained<NSWindow>, Retained<NSWindow>)>> = Default::default();
+}
+
+fn run(id: u64, op: &str, cmd: &V, windows: &super::Windows) -> Result<(), String> {
+  match op {
+    // The call that showed it was cancelled or its page ended: the sheet goes, answering -1.
+    "alert.dismiss" => {
+      let tag = cmd.get("tag").and_then(|v| v.as_str()).unwrap_or("");
+      let open = OPEN_ALERTS.with(|m| m.borrow_mut().remove(tag));
+      if let Some((window, sheet)) = &open {
+        window.endSheet_returnCode(sheet, NSModalResponseAbort);
+      }
+      super::reply(id, Ok(format!(r#"{{"dismissed":{}}}"#, open.is_some())));
+      Ok(())
+    }
+    "panel.types" => {
+      let utis = utis(&strings(cmd.get("types")));
+      super::reply(id, Ok(format!(r#"{{"utis":{}}}"#, utis.map_or("null".into(), |u| json_list(&u.iter().map(|(_, id)| id.clone()).collect::<Vec<_>>())))));
+      Ok(())
+    }
+    "panel.mime" => {
+      super::reply(id, Ok(mime_answer(&strings(cmd.get("exts")), mime_for_ext)));
+      Ok(())
+    }
+    "panel.open" | "panel.save" | "alert.show" => {
+      let mtm = MainThreadMarker::new().ok_or("not on the main thread")?;
+      let wid = match super::window_arg(cmd)? {
+        Some(w) => w,
+        None => windows.primary().ok_or("there is no window")?,
+      };
+      let win = windows.map.get(&wid).ok_or_else(|| format!("no window {wid}"))?;
+      if !win.window.is_visible() {
+        win.window.set_visible(true);
+      }
+      // Safety: tao's ns_window is the NSWindow of this live window.
+      let ns_window: Retained<NSWindow> = unsafe { Retained::retain(win.window.ns_window() as *mut NSWindow) }.ok_or("the window has no NSWindow")?;
+      let test = TestAnswers::get(windows.shell.devtools);
+      match op {
+        "panel.open" => open(mtm, id, cmd, &ns_window, test),
+        "panel.save" => save(mtm, id, cmd, &ns_window, test),
+        _ => alert(mtm, id, cmd, &ns_window, test),
+      }
+      Ok(())
+    }
+    _ => Err(format!("unknown op {op}")),
+  }
+}
+
+// ───────────────────────── file panels ─────────────────────────
+
+fn open(mtm: MainThreadMarker, id: u64, cmd: &V, window: &NSWindow, test: Option<&'static TestAnswers>) {
+  let directory = cmd.get("directory").and_then(|v| v.as_bool()).unwrap_or(false);
+  let panel = NSOpenPanel::openPanel(mtm);
+  panel.setCanChooseDirectories(directory);
+  panel.setCanChooseFiles(!directory);
+  panel.setAllowsMultipleSelection(!directory && cmd.get("multiple").and_then(|v| v.as_bool()).unwrap_or(false));
+  if !directory {
+    if let Some(types) = utis(&strings(cmd.get("types"))) {
+      let list: Vec<Retained<AnyObject>> = types.into_iter().map(|(t, _)| t).collect();
+      let array = NSArray::from_retained_slice(&list);
+      let _: () = unsafe { msg_send![&*panel, setAllowedContentTypes: &*array] };
+    }
+  }
+  prepare_panel(test, &panel);
+  let p = panel.clone();
+  let handler = RcBlock::new(move |response: NSModalResponse| {
+    if response != NSModalResponseOK {
+      return super::reply(id, Ok(CANCELLED.into()));
+    }
+    let paths: Vec<String> = p.URLs().iter().filter_map(|u| u.path().map(|s| s.to_string())).collect();
+    super::reply(id, Ok(open_answer(&paths)));
+  });
+  panel.beginSheetModalForWindow_completionHandler(window, &handler);
+  if let Some(t) = test {
+    end_panel_later(t, window, &panel, directory);
+  }
+}
+
+/// Tests: ends a file panel sheet after the delay. The panels run out of process: `ok:` sent from
+/// here is ignored, and a directory or name set after the panel is shown does not reach it (verified:
+/// it saved under the default name in ~/Documents). So `prepare_panel` sets them before the sheet
+/// begins, and ending the sheet with NSModalResponseOK from the parent window reaches the same
+/// completion handler. An open panel for files is always cancelled: nothing can be selected.
+/// Tests: the directory and name to answer with, set before the sheet is shown.
+fn prepare_panel(test: Option<&'static TestAnswers>, panel: &NSSavePanel) {
+  let Some(t) = test else { return };
+  if let Some(dir) = &t.directory {
+    panel.setDirectoryURL(Some(&NSURL::fileURLWithPath(&NSString::from_str(dir))));
+  }
+  if let Some(name) = &t.name {
+    panel.setNameFieldStringValue(&NSString::from_str(name));
+  }
+}
+
+fn end_panel_later(t: &'static TestAnswers, window: &NSWindow, panel: &NSSavePanel, can_ok: bool) {
+  let window = window.retain();
+  let panel = panel.retain();
+  t.later(move || unsafe {
+    if t.panel_ok && can_ok {
+      window.endSheet_returnCode(&panel, NSModalResponseOK);
+    } else {
+      panel.cancel(None);
+    }
+  });
+}
+
+fn save(mtm: MainThreadMarker, id: u64, cmd: &V, window: &NSWindow, test: Option<&'static TestAnswers>) {
+  let panel = NSSavePanel::savePanel(mtm);
+  panel.setCanCreateDirectories(true);
+  if let Some(name) = cmd.get("name").and_then(|v| v.as_str()) {
+    panel.setNameFieldStringValue(&NSString::from_str(name));
+  }
+  prepare_panel(test, &panel);
+  let p = panel.clone();
+  let handler = RcBlock::new(move |response: NSModalResponse| {
+    let path = if response == NSModalResponseOK { p.URL().and_then(|u| u.path()).map(|s| s.to_string()) } else { None };
+    super::reply(id, Ok(save_answer(path.as_deref())));
+  });
+  panel.beginSheetModalForWindow_completionHandler(window, &handler);
+  if let Some(t) = test {
+    end_panel_later(t, window, &panel, true);
+  }
+}
+
+// ───────────────────────── alerts ─────────────────────────
+
+/// `alert.show` (dialog_args.rs Alert) as a sheet: the first button is the rightmost one.
+fn alert(mtm: MainThreadMarker, id: u64, cmd: &V, window: &NSWindow, test: Option<&'static TestAnswers>) {
+  let a = Alert::parse(cmd);
+  let (alert, field) = make_alert(mtm, &a.title, &a.message, &a.buttons, a.input.as_ref().map(|(t, p)| (t.as_str(), p.as_str())));
+  let f = field.clone();
+  let tag = a.tag.clone();
+  let handler = RcBlock::new(move |response: NSModalResponse| {
+    if let Some(tag) = &tag {
+      OPEN_ALERTS.with(|m| m.borrow_mut().remove(tag));
+    }
+    let button = (response - NSAlertFirstButtonReturn).max(-1);
+    super::reply(id, Ok(alert_answer(button, f.as_ref().map(|f| f.stringValue().to_string()).as_deref())));
+  });
+  alert.beginSheetModalForWindow_completionHandler(window, Some(&handler));
+  if let Some(tag) = &a.tag {
+    OPEN_ALERTS.with(|m| m.borrow_mut().insert(tag.clone(), (window.retain(), alert.window())));
+  }
+  if let Some(t) = test {
+    end_alert_later(t, window, &alert, field);
+  }
+}
+
+/// An NSAlert with its buttons and, for a prompt, a text field. Shared with the JavaScript panels (D7).
+pub fn make_alert(mtm: MainThreadMarker, title: &str, message: &str, buttons: &[(String, String)], input: Option<(&str, &str)>) -> (Retained<NSAlert>, Option<Retained<NSTextField>>) {
+  let alert = NSAlert::new(mtm);
+  // messageText is the bold line: the title, or the message when there is no title.
+  if title.is_empty() {
+    alert.setMessageText(&NSString::from_str(message));
+  } else {
+    alert.setMessageText(&NSString::from_str(title));
+    alert.setInformativeText(&NSString::from_str(message));
+  }
+  for (label, style) in buttons {
+    let button = alert.addButtonWithTitle(&NSString::from_str(label));
+    match style.as_str() {
+      "cancel" => button.setKeyEquivalent(&NSString::from_str("\u{1b}")),
+      "destructive" => button.setHasDestructiveAction(true),
+      _ => {}
+    }
+  }
+  let field = input.map(|(text, placeholder)| {
+    let field = NSTextField::textFieldWithString(&NSString::from_str(text), mtm);
+    field.setFrame(NSRect::new(NSPoint::new(0.0, 0.0), NSSize::new(260.0, 24.0)));
+    if !placeholder.is_empty() {
+      field.setPlaceholderString(Some(&NSString::from_str(placeholder)));
+    }
+    alert.setAccessoryView(Some(&field));
+    alert.layout();
+    alert.window().setInitialFirstResponder(Some(&field));
+    field
+  });
+  (alert, field)
+}
+
+/// Tests: ends an alert sheet with the configured button (and text) after the delay.
+pub fn end_alert_later(t: &'static TestAnswers, window: &NSWindow, alert: &NSAlert, field: Option<Retained<NSTextField>>) {
+  let window = window.retain();
+  let sheet = alert.window();
+  t.later(move || {
+    if let (Some(field), Some(text)) = (&field, &t.text) {
+      field.setStringValue(&NSString::from_str(text));
+    }
+    window.endSheet_returnCode(&sheet, NSAlertFirstButtonReturn + t.button);
+  });
+}
+
+// ───────────────────────── types ─────────────────────────
+
+/// Broad MIME wildcards as UTType identifiers (the earlier JXA mapping).
+fn wildcard(kind: &str) -> Option<&'static str> {
+  Some(match kind {
+    "image" => "public.image",
+    "video" => "public.movie",
+    "audio" => "public.audio",
+    "text" => "public.text",
+    "application" => "public.data",
+    "font" => "public.font",
+    "model" => "public.3d-content",
+    _ => return None,
+  })
+}
+
+fn ut_type(ty: &str) -> Option<Retained<AnyObject>> {
+  let class = AnyClass::get(c"UTType")?;
+  let t: Option<Retained<AnyObject>> = unsafe {
+    if let Some(kind) = ty.strip_suffix("/*") {
+      msg_send![class, typeWithIdentifier: &*NSString::from_str(wildcard(kind)?)]
+    } else if ty.contains('/') {
+      msg_send![class, typeWithMIMEType: &*NSString::from_str(ty)]
+    } else {
+      msg_send![class, typeWithFilenameExtension: &*NSString::from_str(ty.trim_start_matches('.'))]
+    }
+  };
+  let t = t?;
+  let dynamic: bool = unsafe { msg_send![&*t, isDynamic] };
+  (!dynamic).then_some(t)
+}
+
+/// The UTTypes and identifiers for `types`, or None (no filter) when any type is unknown or none is given.
+fn utis(types: &[String]) -> Option<Vec<(Retained<AnyObject>, String)>> {
+  let mut out = Vec::new();
+  for ty in types {
+    if ty == "*/*" {
+      return None;
+    }
+    let t = ut_type(ty)?;
+    let id: Retained<NSString> = unsafe { msg_send![&*t, identifier] };
+    out.push((t, id.to_string()));
+  }
+  (!out.is_empty()).then_some(out)
+}
+
+/// The preferred MIME type of a file extension, from UTType.
+fn mime_for_ext(ext: &str) -> Option<String> {
+  let class = AnyClass::get(c"UTType")?;
+  let t: Option<Retained<AnyObject>> = unsafe { msg_send![class, typeWithFilenameExtension: &*NSString::from_str(ext)] };
+  let mime: Option<Retained<NSString>> = unsafe { msg_send![&*t?, preferredMIMEType] };
+  mime.map(|m| m.to_string())
+}
+
+// ───────────────────────── tests (dev builds) ─────────────────────────
+
+/// AKAN_NATIVE_TEST_PANELS answers (dialog_args.rs). On macOS a sheet is ended by an NSTimer.
+pub use crate::dialog_args::TestAnswers;
+
+impl TestAnswers {
+  /// Runs `f` on the main run loop after the delay (a block-based NSTimer, reached through the runtime).
+  pub fn later(&'static self, f: impl Fn() + 'static) {
+    let Some(class) = AnyClass::get(c"NSTimer") else { return };
+    let block = RcBlock::new(move |_timer: *mut AnyObject| f());
+    let _: Option<Retained<AnyObject>> = unsafe { msg_send![class, scheduledTimerWithTimeInterval: self.delay, repeats: false, block: &*block] };
+  }
+}
+
+#[cfg(test)]
+mod tests {
+  use super::*;
+
+  #[test]
+  fn uti_mapping_like_the_osascript_version() {
+    let ids = |types: &[&str]| utis(&types.iter().map(|s| s.to_string()).collect::<Vec<_>>()).map(|v| v.into_iter().map(|(_, id)| id).collect::<Vec<_>>());
+    assert_eq!(
+      ids(&["image/*", "application/pdf", "csv", ".md"]),
+      Some(vec!["public.image".into(), "com.adobe.pdf".into(), "public.comma-separated-values-text".into(), "net.daringfireball.markdown".into()])
+    );
+    assert_eq!(ids(&["pdf", "zzzunknown"]), None); // an unknown type turns the filter off
+    assert_eq!(ids(&["application/x-nope"]), None);
+    assert_eq!(ids(&["*/*"]), None);
+    assert_eq!(ids(&[]), None);
+    assert_eq!(mime_for_ext("png").as_deref(), Some("image/png"));
+    assert_eq!(mime_for_ext("pdf").as_deref(), Some("application/pdf"));
+    assert_eq!(mime_for_ext("zzzunknown"), None);
+  }
+}

package/vendor/@akanjs/native/native/desktop/src/placement.rs

@@ -0,0 +1,92 @@
+//! Where a restored window may open (window-state plugin). All values are logical points.
+//!
+//! Tauri window-state restores the position when any corner lies on a monitor
+//! (`tauri-plugins-workspace/plugins/window-state/src/lib.rs:550-575`). A window whose only
+//! visible corner is its bottom-right one cannot be dragged back, so this checks the title bar:
+//! a strip at the top of the window must overlap a monitor enough to grab it.
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct Rect {
+  pub x: f64,
+  pub y: f64,
+  pub width: f64,
+  pub height: f64,
+}
+
+/// Height of the strip that must be reachable (the macOS title bar is 28 points).
+const GRAB_HEIGHT: f64 = 28.0;
+/// How much of that strip must be on one monitor to grab it.
+const GRAB_WIDTH: f64 = 80.0;
+
+fn overlap(a0: f64, a1: f64, b0: f64, b1: f64) -> f64 {
+  (a1.min(b1) - a0.max(b0)).max(0.0)
+}
+
+/// The rect to open at: the saved one, shrunk to fit its monitor, or None when its title bar
+/// would be on no monitor (a display was unplugged): then the default position is used.
+pub fn place(saved: Rect, monitors: &[Rect], min: (f64, f64)) -> Option<Rect> {
+  let monitor = monitors.iter().find(|m| {
+    let top = saved.y.max(m.y);
+    let reachable = saved.y >= m.y - GRAB_HEIGHT / 2.0 && top < m.y + m.height - GRAB_HEIGHT;
+    reachable && overlap(saved.x, saved.x + saved.width, m.x, m.x + m.width) >= GRAB_WIDTH.min(saved.width)
+  })?;
+  let width = saved.width.min(monitor.width).max(min.0);
+  let height = saved.height.min(monitor.height).max(min.1);
+  // Above the monitor's top edge (under the menu bar) the title bar cannot be grabbed.
+  let y = saved.y.max(monitor.y);
+  Some(Rect { x: saved.x, y, width, height })
+}
+
+#[cfg(test)]
+mod tests {
+  use super::*;
+
+  const MIN: (f64, f64) = (320.0, 240.0);
+  const LAPTOP: Rect = Rect { x: 0.0, y: 0.0, width: 1512.0, height: 982.0 };
+  // An external display to the left and a bit higher.
+  const LEFT: Rect = Rect { x: -1920.0, y: -200.0, width: 1920.0, height: 1080.0 };
+
+  fn r(x: f64, y: f64, width: f64, height: f64) -> Rect {
+    Rect { x, y, width, height }
+  }
+
+  #[test]
+  fn keeps_a_window_that_is_on_screen() {
+    let w = r(100.0, 80.0, 800.0, 600.0);
+    assert_eq!(place(w, &[LAPTOP], MIN), Some(w));
+    let on_left = r(-1500.0, -100.0, 1200.0, 800.0);
+    assert_eq!(place(on_left, &[LAPTOP, LEFT], MIN), Some(on_left));
+  }
+
+  #[test]
+  fn drops_a_window_on_an_unplugged_display() {
+    assert_eq!(place(r(-1500.0, -100.0, 1200.0, 800.0), &[LAPTOP], MIN), None);
+    assert_eq!(place(r(3000.0, 100.0, 800.0, 600.0), &[LAPTOP], MIN), None);
+    assert_eq!(place(r(100.0, 2000.0, 800.0, 600.0), &[LAPTOP], MIN), None);
+    assert_eq!(place(r(100.0, 80.0, 800.0, 600.0), &[], MIN), None);
+  }
+
+  #[test]
+  fn title_bar_must_be_reachable_not_just_a_corner() {
+    // Only the bottom-right corner is on the laptop: Tauri would restore it, this does not.
+    assert_eq!(place(r(-700.0, -500.0, 800.0, 600.0), &[LAPTOP], MIN), None);
+    // Title bar hanging 60 points off the left edge but mostly visible: fine.
+    let w = r(-60.0, 100.0, 800.0, 600.0);
+    assert_eq!(place(w, &[LAPTOP], MIN), Some(w));
+    // Only 40 points of the title bar are on screen: too little to grab.
+    assert_eq!(place(r(1472.0, 100.0, 800.0, 600.0), &[LAPTOP], MIN), None);
+  }
+
+  #[test]
+  fn shrinks_to_the_monitor_and_keeps_the_minimum() {
+    let big = place(r(0.0, 0.0, 1920.0, 1080.0), &[LAPTOP], MIN).unwrap();
+    assert_eq!((big.width, big.height), (1512.0, 982.0));
+    let tiny = place(r(10.0, 10.0, 100.0, 50.0), &[LAPTOP], MIN).unwrap();
+    assert_eq!((tiny.width, tiny.height), MIN);
+  }
+
+  #[test]
+  fn moves_a_title_bar_out_from_above_the_top_edge() {
+    assert_eq!(place(r(100.0, -10.0, 800.0, 600.0), &[LAPTOP], MIN), Some(r(100.0, 0.0, 800.0, 600.0)));
+  }
+}

package/vendor/@akanjs/native/native/desktop/src/routes.rs

@@ -0,0 +1,153 @@
+//! Host decisions shared with every akan-native host (docs/architecture.md §5): asset routes, path
+//! decoding, ids, MIME types and Range requests. The reference is packages/core/src/kernel.ts;
+//! vectors.rs runs the shared vectors (packages/core/vectors) against these functions.
+
+use crate::contract::{self, IdSpec};
+
+#[derive(Debug, PartialEq, Eq)]
+pub enum Route {
+  Init,
+  Ipc,
+  /// Android's port doorbell; the desktop answers 404.
+  Hello,
+  File(String),
+  /// Relative path inside the app folder.
+  Asset(String),
+  NotFound,
+}
+
+/// Strict percent-decoding: "%" and two hex digits, and the result must be UTF-8; otherwise None.
+pub fn decode(s: &str) -> Option<String> {
+  let b = s.as_bytes();
+  let mut out = Vec::with_capacity(b.len());
+  let mut i = 0;
+  while i < b.len() {
+    if b[i] == b'%' {
+      let hex = s.get(i + 1..i + 3).filter(|h| h.bytes().all(|c| c.is_ascii_hexdigit()))?; // not "%+1"
+      out.push(u8::from_str_radix(hex, 16).ok()?);
+      i += 3;
+    } else {
+      out.push(b[i]);
+      i += 1;
+    }
+  }
+  String::from_utf8(out).ok()
+}
+
+/// Whether `s` follows an id grammar: its characters and length, and an optional ".ext" after the first dot.
+pub fn id_valid(spec: &IdSpec, s: &str) -> bool {
+  let run = |s: &str, chars: &str, min: usize, max: usize| (min..=max).contains(&s.len()) && s.chars().all(|c| chars.contains(c));
+  if spec.ext_max > 0 {
+    return match s.split_once('.') {
+      None => run(s, spec.chars, spec.min, spec.max),
+      Some((stem, ext)) => run(stem, spec.chars, spec.min, spec.max) && run(ext, spec.ext_chars, 1, spec.ext_max),
+    };
+  }
+  let mut chars = s.chars();
+  let Some(first) = chars.next() else { return false };
+  let first_set = if spec.first.is_empty() { spec.chars } else { spec.first };
+  (spec.min..=spec.max).contains(&s.len()) && first_set.contains(first) && !spec.not_first.contains(first) && chars.all(|c| spec.chars.contains(c))
+}
+
+pub fn route(pathname: &str, exists: impl Fn(&str) -> bool) -> Route {
+  let Some(decoded) = decode(pathname) else { return Route::NotFound };
+  let segments: Vec<&str> = decoded.split('/').filter(|s| !s.is_empty()).collect();
+  if segments.iter().any(|s| *s == ".." || *s == "." || s.contains('\\') || s.contains('\0')) {
+    return Route::NotFound;
+  }
+  if segments.first() == Some(&contract::ROUTE_ROOT) {
+    return match segments.as_slice() {
+      [_, s] if *s == contract::ROUTE_INIT => Route::Init,
+      [_, s] if *s == contract::ROUTE_IPC => Route::Ipc,
+      [_, s] if *s == contract::ROUTE_HELLO => Route::Hello,
+      [_, s, id] if *s == contract::ROUTE_FILE && id_valid(&contract::ID_FILE_REF, id) => Route::File((*id).to_string()),
+      _ => Route::NotFound,
+    };
+  }
+  let relative = segments.join("/");
+  if relative.is_empty() || relative == "index.html" {
+    return Route::Asset("index.html".into());
+  }
+  // ":" never reaches the filesystem: "C:" would make the joined path absolute on Windows, "a:b"
+  // names an alternate data stream (kernel.ts). The path can still be an SPA route.
+  if !relative.contains(':') && exists(&relative) {
+    return Route::Asset(relative);
+  }
+  if segments.last().is_some_and(|s| s.contains('.')) {
+    Route::NotFound
+  } else {
+    Route::Asset("index.html".into())
+  }
+}
+
+/// Paths the host answers itself even when its pages come from a dev server (akan-native dev --hmr,
+/// devproxy.rs): /__akan_native/*, and paths that do not decode (route() refuses them).
+pub fn is_host_path(pathname: &str) -> bool {
+  let Some(decoded) = decode(pathname) else { return true };
+  decoded.split('/').find(|s| !s.is_empty()) == Some(contract::ROUTE_ROOT)
+}
+
+/// The MIME type for a file name (FileRefs): application/octet-stream when unknown.
+pub fn file_mime(path: &str) -> &'static str {
+  let base = path.rsplit('/').next().unwrap_or(path);
+  let ext = match base.rfind('.') {
+    Some(dot) if dot > 0 => base[dot + 1..].to_ascii_lowercase(),
+    _ => return "application/octet-stream", // no extension, or a dot file such as .env
+  };
+  contract::MIME.iter().find(|(e, _)| *e == ext).map_or("application/octet-stream", |(_, m)| m)
+}
+
+/// The Content-Type an asset is served with: text types carry charset=utf-8.
+pub fn asset_mime(path: &str) -> String {
+  let mime = file_mime(path);
+  if mime.starts_with("text/") || contract::MIME_UTF8.contains(&mime) {
+    format!("{mime}; charset=utf-8")
+  } else {
+    mime.to_string()
+  }
+}
+
+/// kernel.ts fileRefSandboxed: every FileRef but images other than SVG, audio, video, fonts and PDF
+/// is served with `Content-Security-Policy: sandbox` (an opaque origin: no bridge, no page). macOS
+/// WebKit draws nothing for a sandboxed PDF.
+pub fn file_ref_sandboxed(mime: &str) -> bool {
+  let kind = mime.split(';').next().unwrap_or("").trim().to_ascii_lowercase();
+  kind == "image/svg+xml" || !(["image/", "audio/", "video/", "font/"].iter().any(|p| kind.starts_with(p)) || kind == "application/pdf")
+}
+
+#[derive(Debug, PartialEq, Eq)]
+pub enum RangeAnswer {
+  Whole,
+  /// First and last byte, inclusive.
+  Part(u64, u64),
+  Unsatisfiable,
+}
+
+/// A Range header (IN-5, RFC 9110 §14) for a file of `size` bytes. One "bytes=" range is supported:
+/// a header that is not one (another unit, several ranges, bad syntax, last before first) is ignored
+/// and the whole file is sent. A valid range the file cannot satisfy is 416. A response carries at
+/// most MAX_RANGE_BYTES, from the range's start.
+pub fn parse_range(header: Option<&str>, size: u64) -> RangeAnswer {
+  let number = |s: &str| (s.len() <= 18 && s.bytes().all(|c| c.is_ascii_digit())).then(|| if s.is_empty() { None } else { s.parse::<u64>().ok() });
+  let Some((a, b)) = header.and_then(|h| h.strip_prefix("bytes=")).and_then(|spec| spec.split_once('-')) else { return RangeAnswer::Whole };
+  let (Some(a), Some(b)) = (number(a), number(b)) else { return RangeAnswer::Whole };
+  let (start, end) = match (a, b) {
+    (None, None) => return RangeAnswer::Whole,
+    (None, Some(suffix)) => {
+      if suffix == 0 || size == 0 {
+        return RangeAnswer::Unsatisfiable;
+      }
+      (size.saturating_sub(suffix), size - 1)
+    }
+    (Some(start), last) => {
+      if last.is_some_and(|last| last < start) {
+        return RangeAnswer::Whole;
+      }
+      if start >= size {
+        return RangeAnswer::Unsatisfiable;
+      }
+      (start, last.unwrap_or(u64::MAX).min(size - 1))
+    }
+  };
+  RangeAnswer::Part(start, end.min(start + contract::MAX_RANGE_BYTES as u64 - 1))
+}