@scriptc/cli-darwin-x64 0.2.1 → 0.2.3

package/dist/lib/runtime-sources/src/scr_url.c

@@ -1,4 +1,4 @@
-/* The WHATWG URL slice (scr_runtime.h has the API contract): an immutable,
+/* The WHATWG URL slice (scr_runtime.h has the API contract): a mutable,
  * refcounted URL value parsed once at construction, plus the file-URL
  * bridge pair (fileURLToPath / pathToFileURL).
  *
@@ -197,7 +197,7 @@ static void ub_push_encoded(UrlBuf *b, unsigned char c, bool (*needs)(unsigned c
 /* ── parsing ─────────────────────────────────────────────────────────── */
 
 static void scr_url_throw_invalid(void) {
-  scr_throw_error_msg(SCR_ERR_TYPE, "Invalid URL", 11);
+  scr_throw_error_msg_code(SCR_ERR_TYPE, "Invalid URL", 11, "ERR_INVALID_URL");
 }
 
 static bool is_special_scheme(const char *s, size_t len) {
@@ -322,6 +322,47 @@ static ScrStr *parse_rooted_path(const char *raw, size_t len, bool special) {
   return parse_rooted_path_mode(raw, len, special, false);
 }
 
+/* Shared constructor/setter host parsing keeps the existing ASCII-host
+ * boundary and canonical IPv6 serialization in both execution tiers. */
+static bool parse_host(const char *hp, size_t host_len, bool special, bool is_file,
+                       ScrStr **host) {
+  bool ipv6 = host_len > 0 && hp[0] == '[';
+  size_t ipv6_end = host_len ? host_len - 1 : 0;
+  if (ipv6 && (host_len < 3 || hp[ipv6_end] != ']')) return false;
+  /* Validate + lowercase (special) the host. Divergence: non-ASCII and
+   * %-escapes (IDNA territory) are rejected outright. */
+  UrlBuf hb;
+  ub_init(&hb);
+  if (ipv6) {
+    if (!ub_append_ipv6(&hb, hp + 1, ipv6_end - 1)) {
+      free(hb.data);
+      return false;
+    }
+  } else {
+    for (size_t i = 0; i < host_len; i++) {
+      unsigned char c = (unsigned char)hp[i];
+      if (c >= 0x80 || c == '%' || c == ':' || c == '[' || c == ']' ||
+          c <= 0x20 || c == '#' || c == '/' || c == '<' || c == '>' ||
+          c == '?' || c == '@' || c == '\\' || c == '^' || c == '|') {
+        free(hb.data);
+        return false;
+      }
+      if (special && c >= 'A' && c <= 'Z') {
+        c = (unsigned char)(c - 'A' + 'a');
+      }
+      ub_push(&hb, (char)c);
+    }
+  }
+  /* file: "localhost" normalizes to "" at parse time (Node). */
+  if (is_file && hb.len == 9 && memcmp(hb.data, "localhost", 9) == 0) hb.len = 0;
+  if (hb.len == 0 && special && !is_file) {
+    free(hb.data);
+    return false; /* http:// — special non-file needs a host */
+  }
+  *host = ub_take(&hb);
+  return true;
+}
+
 /* Parses `authority` (between the slashes and the path/query/fragment):
  * [userinfo@]host[:port]. Returns false (throws) on invalid input. */
 static bool parse_authority(const char *raw, size_t len, bool special, bool is_file,
@@ -376,37 +417,7 @@ static bool parse_authority(const char *raw, size_t len, bool special, bool is_f
     }
     host_len = colon >= 0 ? (size_t)colon : hp_len;
   }
-  /* Validate + lowercase (special) the host. Divergence: non-ASCII and
-   * %-escapes (IDNA territory) are rejected outright. */
-  UrlBuf hb;
-  ub_init(&hb);
-  if (ipv6) {
-    if (!ub_append_ipv6(&hb, hp + 1, ipv6_end - 1)) {
-      free(hb.data);
-      return false;
-    }
-  } else {
-    for (size_t i = 0; i < host_len; i++) {
-      unsigned char c = (unsigned char)hp[i];
-      if (c >= 0x80 || c == '%' || c == ':' || c == '[' || c == ']' ||
-          c <= 0x20 || c == '#' || c == '/' || c == '<' || c == '>' ||
-          c == '?' || c == '@' || c == '\\' || c == '^' || c == '|') {
-        free(hb.data);
-        return false;
-      }
-      if (special && c >= 'A' && c <= 'Z') {
-        c = (unsigned char)(c - 'A' + 'a');
-      }
-      ub_push(&hb, (char)c);
-    }
-  }
-  /* file: "localhost" normalizes to "" at parse time (Node). */
-  if (is_file && hb.len == 9 && memcmp(hb.data, "localhost", 9) == 0) hb.len = 0;
-  if (hb.len == 0 && special && !is_file) {
-    free(hb.data);
-    return false; /* http:// — special non-file needs a host */
-  }
-  *host = ub_take(&hb);
+  if (!parse_host(hp, host_len, special, is_file, host)) return false;
   /* Port: digits only, leading zeros stripped, defaults dropped. */
   UrlBuf pb;
   ub_init(&pb);
@@ -645,7 +656,9 @@ ScrUrl *scr_url_new(ScrStr *input) {
   u->query = query;
   u->fragment = fragment;
   u->has_authority = has_authority;
+  u->host_path_escape = false;
   u->sp_cache = NULL;
+  u->sp_reload = NULL;
   return u;
 }
 
@@ -763,6 +776,33 @@ ScrStr *scr_url_protocol(ScrUrl *u) {
   return ub_take(&b);
 }
 
+/* Input conversion is the caller's responsibility. Only parser errors are
+ * suppressed: user toString errors must still escape the public factories. */
+static ScrUrl *url_try_parse(ScrStr *input, ScrStr *base) {
+  ScrUrl *u = base ? scr_url_new_base(input, base) : scr_url_new(input);
+  if (!u) scr_exc_clear();
+  return u;
+}
+
+bool scr_url_can_parse_base(ScrStr *input, ScrStr *base) {
+  ScrUrl *u = url_try_parse(input, base);
+  bool valid = u != NULL;
+  scr_url_release(u);
+  return valid;
+}
+
+bool scr_url_can_parse(ScrStr *input) { return scr_url_can_parse_base(input, NULL); }
+
+ScrDyn *scr_url_parse_base(ScrStr *input, ScrStr *base) {
+  ScrUrl *u = url_try_parse(input, base);
+  if (!u) return scr_dyn_new_null();
+  ScrDyn *value = scr_dyn_native_url(u);
+  scr_url_release(u);
+  return value;
+}
+
+ScrDyn *scr_url_parse(ScrStr *input) { return scr_url_parse_base(input, NULL); }
+
 ScrStr *scr_url_pathname(ScrUrl *u) { return scr_str_retain(u->path); }
 
 /* WHATWG host getter: host[:port] — the port only when non-default (the
@@ -770,12 +810,15 @@ ScrStr *scr_url_pathname(ScrUrl *u) { return scr_str_retain(u->path); }
  * normalized form findRoute-style authority compares want (lowercased
  * host, no default :443/:80). */
 ScrStr *scr_url_host(ScrUrl *u) {
-  if (u->port->len == 0) return scr_str_retain(u->host);
+  if (u->port->len == 0 && !u->host_path_escape) return scr_str_retain(u->host);
   UrlBuf b;
   ub_init(&b);
   ub_append(&b, u->host->data, u->host->len);
-  ub_push(&b, ':');
-  ub_append(&b, u->port->data, u->port->len);
+  if (u->port->len) {
+    ub_push(&b, ':');
+    ub_append(&b, u->port->data, u->port->len);
+  }
+  if (u->host_path_escape) ub_append(&b, "/.", 2);
   return ub_take(&b);
 }
 
@@ -851,12 +894,289 @@ ScrStr *scr_url_href(ScrUrl *u) {
       ub_append(&b, u->port->data, u->port->len);
     }
   }
+  /* A host-less hierarchical path starting with // must not serialize
+   * as an authority (the URL Standard's /. escape). */
+  if (u->host_path_escape || (!u->has_authority && u->path->len >= 2 && !memcmp(u->path->data, "//", 2))) ub_append(&b, "/.", 2);
   ub_append(&b, u->path->data, u->path->len);
   ub_append(&b, u->query->data, u->query->len);
   ub_append(&b, u->fragment->data, u->fragment->len);
   return ub_take(&b);
 }
 
+static bool url_opaque(ScrUrl *u) {
+  return !u->has_authority && (u->path->len == 0 || u->path->data[0] != '/');
+}
+
+static void url_strip_opaque_spaces(ScrUrl *u) {
+  if (!url_opaque(u) || u->query->len || u->fragment->len) return;
+  size_t end = u->path->len;
+  while (end && u->path->data[end - 1] == ' ') end--;
+  if (end != u->path->len) {
+    ScrStr *path = scr_str_new(u->path->data, end);
+    scr_str_release(u->path);
+    u->path = path;
+  }
+}
+
+/* Setter state overrides preserve the other components. Unlike the full
+ * parser they strip TAB/LF/CR without trimming surrounding spaces. */
+static void url_copy_fields(ScrUrl *u, ScrUrl *next) {
+  scr_str_release(u->scheme); u->scheme = scr_str_retain(next->scheme);
+  scr_str_release(u->userinfo); u->userinfo = scr_str_retain(next->userinfo);
+  scr_str_release(u->host); u->host = scr_str_retain(next->host);
+  scr_str_release(u->port); u->port = scr_str_retain(next->port);
+  scr_str_release(u->path); u->path = scr_str_retain(next->path);
+  scr_str_release(u->query); u->query = scr_str_retain(next->query);
+  scr_str_release(u->fragment); u->fragment = scr_str_retain(next->fragment);
+  u->has_authority = next->has_authority;
+  u->host_path_escape = next->host_path_escape;
+}
+
+static bool url_file(ScrUrl *u) {
+  return u->scheme->len == 4 && !memcmp(u->scheme->data, "file", 4);
+}
+
+static bool url_cannot_have_credentials_or_port(ScrUrl *u) {
+  return !u->host->len || url_file(u) || url_opaque(u);
+}
+
+static bool url_set_port(ScrUrl *u, const char *raw, size_t len, bool empty_input) {
+  if (url_cannot_have_credentials_or_port(u)) return false;
+  if (empty_input) {
+    scr_str_release(u->port);
+    u->port = scr_str_new("", 0);
+    return true;
+  }
+  if (!len) return true; /* TAB/LF/CR-only input leaves the port unchanged. */
+  if (raw[0] < '0' || raw[0] > '9') return false;
+  unsigned int number = 0;
+  for (size_t i = 0; i < len && raw[i] >= '0' && raw[i] <= '9'; i++) {
+    number = number * 10 + (unsigned int)(raw[i] - '0');
+    if (number > 65535) return false;
+  }
+  char digits[6];
+  size_t size = (size_t)snprintf(digits, sizeof digits, "%u", number);
+  const char *dflt = default_port(u->scheme->data, u->scheme->len);
+  scr_str_release(u->port);
+  u->port = scr_str_new(digits, dflt && strlen(dflt) == size && !memcmp(dflt, digits, size) ? 0 : size);
+  return true;
+}
+
+static bool url_set_protocol(ScrUrl *u, const char *raw, size_t len) {
+  if (!len) return true;
+  if (!((raw[0] >= 'a' && raw[0] <= 'z') || (raw[0] >= 'A' && raw[0] <= 'Z'))) return false;
+  size_t end = 1;
+  while (end < len && ((raw[end] >= 'a' && raw[end] <= 'z') ||
+         (raw[end] >= 'A' && raw[end] <= 'Z') || (raw[end] >= '0' && raw[end] <= '9') ||
+         raw[end] == '+' || raw[end] == '-' || raw[end] == '.')) end++;
+  if (end < len && raw[end] != ':') return false;
+  UrlBuf normalized;
+  ub_init(&normalized);
+  for (size_t i = 0; i < end; i++) {
+    char c = raw[i];
+    ub_push(&normalized, c >= 'A' && c <= 'Z' ? (char)(c + 'a' - 'A') : c);
+  }
+  ScrStr *scheme = ub_take(&normalized);
+  bool special = is_special_scheme(scheme->data, scheme->len);
+  bool file = scheme->len == 4 && !memcmp(scheme->data, "file", 4);
+  if (is_special_scheme(u->scheme->data, u->scheme->len) != special ||
+      (file && (u->userinfo->len || u->port->len)) || (url_file(u) && !u->host->len)) {
+    scr_str_release(scheme);
+    /* Ada reports a successful unchanged URL for non-special targets,
+     * so these writes still replace the pre-conversion snapshot in Node. */
+    return !special;
+  }
+  scr_str_release(u->scheme);
+  u->scheme = scheme;
+  const char *dflt = default_port(scheme->data, scheme->len);
+  if (dflt && u->port->len == strlen(dflt) && !memcmp(u->port->data, dflt, u->port->len)) {
+    scr_str_release(u->port);
+    u->port = scr_str_new("", 0);
+  }
+  return true;
+}
+
+static bool url_set_credentials(ScrUrl *u, ScrStr *value, bool username) {
+  if (url_cannot_have_credentials_or_port(u)) return false;
+  ScrStr *other = username ? scr_url_password(u) : scr_url_username(u);
+  UrlBuf encoded;
+  ub_init(&encoded);
+  for (size_t i = 0; i < value->len; i++) ub_push_encoded(&encoded, (unsigned char)value->data[i], enc_userinfo);
+  ScrStr *part = ub_take(&encoded);
+  ScrStr *user = username ? part : other;
+  ScrStr *pass = username ? other : part;
+  UrlBuf combined;
+  ub_init(&combined);
+  ub_append(&combined, user->data, user->len);
+  if (pass->len) {
+    ub_push(&combined, ':');
+    ub_append(&combined, pass->data, pass->len);
+  }
+  scr_str_release(u->userinfo);
+  u->userinfo = ub_take(&combined);
+  scr_str_release(other);
+  scr_str_release(part);
+  return true;
+}
+
+static bool url_set_host(ScrUrl *u, const char *raw, size_t len, bool hostname) {
+  if (url_opaque(u)) return false;
+  bool file = url_file(u);
+  bool special = is_special_scheme(u->scheme->data, u->scheme->len);
+  size_t end = 0;
+  bool bracket = false, colon = false;
+  for (; end < len; end++) {
+    char c = raw[end];
+    if (c == '/' || c == '?' || c == '#' || (special && c == '\\')) break;
+    if (!file && c == ':' && !bracket) { colon = true; break; }
+    if (c == '[') bracket = true;
+    if (c == ']') bracket = false;
+  }
+  if (colon && (hostname || !end)) return false;
+  if (!end && !file && (special || u->userinfo->len || u->port->len)) return false;
+  ScrStr *host = NULL;
+  if (!parse_host(raw, end, special, file, &host)) return false;
+  bool escaped_path = !u->has_authority && u->path->len >= 2 && !memcmp(u->path->data, "//", 2);
+  scr_str_release(u->host);
+  u->host = host;
+  if (host->len || escaped_path) u->has_authority = true;
+  if (colon) {
+    u->host_path_escape = escaped_path;
+    if (end + 1 < len) url_set_port(u, raw + end + 1, len - end - 1, false);
+  }
+  return true;
+}
+
+/* The result distinguishes successful state overrides from ignored writes:
+ * only successful writes replace Node's pre-conversion URL snapshot. */
+static bool url_apply_component(ScrUrl *u, ScrStr *field, ScrStr *value) {
+  if (field->len == 4 && !memcmp(field->data, "href", 4)) {
+    ScrUrl *next = scr_url_new(value);
+    if (!next) return false;
+    url_copy_fields(u, next);
+    scr_url_release(next);
+    if (u->sp_cache) u->sp_reload(u->sp_cache, u->query);
+    return true;
+  }
+  bool pathname = field->len == 8 && !memcmp(field->data, "pathname", 8);
+  bool search = field->len == 6 && !memcmp(field->data, "search", 6);
+  bool hash = field->len == 4 && !memcmp(field->data, "hash", 4);
+  bool protocol = field->len == 8 && !memcmp(field->data, "protocol", 8);
+  bool username = field->len == 8 && !memcmp(field->data, "username", 8);
+  bool password = field->len == 8 && !memcmp(field->data, "password", 8);
+  bool host = field->len == 4 && !memcmp(field->data, "host", 4);
+  bool hostname = field->len == 8 && !memcmp(field->data, "hostname", 8);
+  bool port = field->len == 4 && !memcmp(field->data, "port", 4);
+  if (!pathname && !search && !hash && !protocol && !username && !password && !host && !hostname && !port) {
+    static const char message[] = "Native URL setter has no lowering";
+    scr_throw_error_msg_code(SCR_ERR_ERROR, message, sizeof message - 1, "SC2020");
+    return false;
+  }
+  if (username || password) return url_set_credentials(u, value, username);
+  if (pathname && url_opaque(u)) return false;
+  UrlBuf raw;
+  ub_init(&raw);
+  size_t start = (search || hash) && value->len && value->data[0] == (search ? '?' : '#') ? 1 : 0;
+  for (size_t i = start; i < value->len; i++) {
+    char c = value->data[i];
+    if ((host || hostname) && c == '#') break;
+    if (c != '\t' && c != '\n' && c != '\r') ub_push(&raw, c);
+  }
+  bool special = is_special_scheme(u->scheme->data, u->scheme->len);
+  bool applied = true;
+  if (protocol) applied = url_set_protocol(u, raw.data, raw.len);
+  else if (port) applied = url_set_port(u, raw.data, raw.len, !value->len);
+  else if (host || hostname) applied = url_set_host(u, raw.data, raw.len, hostname);
+  else if (pathname) {
+    bool file = u->scheme->len == 4 && !memcmp(u->scheme->data, "file", 4);
+    ScrStr *path = parse_rooted_path_mode(raw.data, raw.len, special, file);
+    if (!path->len && (special || !u->has_authority)) {
+      scr_str_release(path);
+      path = scr_str_new("/", 1);
+    }
+    scr_str_release(u->path);
+    u->path = path;
+  } else {
+    UrlBuf encoded;
+    ub_init(&encoded);
+    if (value->len) {
+      char prefix = search ? '?' : '#';
+      ub_push(&encoded, prefix);
+      for (size_t i = 0; i < raw.len; i++) {
+        unsigned char c = (unsigned char)raw.data[i];
+        bool needs = search ? enc_query(c, special) : enc_fragment(c);
+        if (needs) {
+          char hex[4];
+          snprintf(hex, sizeof hex, "%%%02X", c);
+          ub_append(&encoded, hex, 3);
+        } else ub_push(&encoded, (char)c);
+      }
+    }
+    ScrStr **slot = search ? &u->query : &u->fragment;
+    scr_str_release(*slot);
+    *slot = ub_take(&encoded);
+    url_strip_opaque_spaces(u);
+    if (search && u->sp_cache) u->sp_reload(u->sp_cache, u->query);
+  }
+  free(raw.data);
+  return applied;
+}
+
+bool scr_url_set_component(ScrUrl *u, ScrStr *field, ScrStr *value) {
+  if (field->len == 4 && !memcmp(field->data, "href", 4)) return url_apply_component(u, field, value);
+  /* Node's binding reparses the captured href before applying an override.
+   * This matters after protocol writes to file://localhost and for the
+   * host-to-port serialization escape. Ignored overrides retain the live URL. */
+  ScrStr *href = scr_url_href(u);
+  ScrUrl *next = scr_url_new(href);
+  scr_str_release(href);
+  if (!next) return false;
+  bool applied = url_apply_component(next, field, value);
+  if (applied) {
+    url_copy_fields(u, next);
+    if (field->len == 6 && !memcmp(field->data, "search", 6) && u->sp_cache) u->sp_reload(u->sp_cache, u->query);
+  }
+  scr_url_release(next);
+  return applied;
+}
+
+void scr_url_set(ScrUrl *u, ScrStr *field, ScrStr *value) {
+  scr_url_set_component(u, field, value);
+}
+
+/* Node snapshots a component setter's URL before invoking user string
+ * conversion. href converts first, and opaque pathname writes are ignored. */
+void scr_url_set_checked(ScrUrl *u, ScrStr *field, const ScrDyn *value) {
+  bool href = field->len == 4 && !memcmp(field->data, "href", 4);
+  bool ignored = field->len == 8 && !memcmp(field->data, "pathname", 8) && url_opaque(u);
+  ScrUrl *saved = NULL;
+  if (!href && !ignored) {
+    saved = malloc(sizeof *saved);
+    if (!saved) abort();
+    *saved = *u;
+    saved->rc = 1;
+    saved->sp_cache = NULL;
+    saved->sp_reload = NULL;
+    saved->scheme = scr_str_retain(u->scheme);
+    saved->userinfo = scr_str_retain(u->userinfo);
+    saved->host = scr_str_retain(u->host);
+    saved->port = scr_str_retain(u->port);
+    saved->path = scr_str_retain(u->path);
+    saved->query = scr_str_retain(u->query);
+    saved->fragment = scr_str_retain(u->fragment);
+  }
+  ScrStr *text = scr_dyn_string_coerce_js(value);
+  if (text && !ignored) {
+    bool applied = scr_url_set_component(saved ? saved : u, field, text);
+    if (saved && applied && !scr_exc_pending()) {
+      url_copy_fields(u, saved);
+      if (field->len == 6 && !memcmp(field->data, "search", 6) && u->sp_cache) u->sp_reload(u->sp_cache, u->query);
+    }
+  }
+  scr_str_release(text);
+  scr_url_release(saved);
+}
+
 /* ── the file-URL bridge ─────────────────────────────────────────────── */
 
 static int hex_val(char c) {
@@ -866,15 +1186,36 @@ static int hex_val(char c) {
   return -1;
 }
 
+static bool url_file_scheme(ScrUrl *u) {
+  if (u->scheme->len == 4 && memcmp(u->scheme->data, "file", 4) == 0) return true;
+  scr_throw_error_msg_code(SCR_ERR_TYPE, "The URL must be of scheme file", 30, "ERR_INVALID_URL_SCHEME");
+  return false;
+}
+
+static bool url_file_posix_host(ScrUrl *u) {
+  if (u->host->len == 0) return true;
+  const char *platform =
+#if defined(__APPLE__)
+      "darwin";
+#elif defined(__linux__)
+      "linux";
+#elif defined(_WIN32)
+      "win32";
+#else
+      "posix";
+#endif
+  char message[96];
+  int length = snprintf(message, sizeof message, "File URL host must be \"localhost\" or empty on %s", platform);
+  scr_throw_error_msg_code(SCR_ERR_TYPE, message, (size_t)length, "ERR_INVALID_FILE_URL_HOST");
+  return false;
+}
+
 /* fileURLToPath over a parsed URL: Node's checks, Node's messages. The
  * posix arm rejects hosts and keeps forward slashes; the win32 arm maps
  * hosts to UNC \\host prefixes, flips separators, and demands a drive
  * letter otherwise. The public wrappers below select by TARGET. */
 static ScrStr *scr_url_to_path_impl(ScrUrl *u, bool win32) {
-  if (!(u->scheme->len == 4 && memcmp(u->scheme->data, "file", 4) == 0)) {
-    scr_throw_error_msg(SCR_ERR_TYPE, "The URL must be of scheme file", 30);
-    return NULL;
-  }
+  if (!url_file_scheme(u)) return NULL;
   const char *p = u->path->data;
   size_t len = u->path->len;
   if (win32) {
@@ -884,8 +1225,8 @@ static ScrStr *scr_url_to_path_impl(ScrUrl *u, bool win32) {
       char c1 = p[n + 1];
       int third = (n + 2 < len ? (unsigned char)p[n + 2] : 0) | 0x20;
       if ((c1 == '2' && third == 'f') || (c1 == '5' && third == 'c')) {
-        scr_throw_error_msg(SCR_ERR_TYPE,
-                             "File URL path must not include encoded \\ or / characters", 56);
+        scr_throw_error_msg_code(SCR_ERR_TYPE,
+                             "File URL path must not include encoded \\ or / characters", 56, "ERR_INVALID_FILE_URL_PATH");
         return NULL;
       }
     }
@@ -916,7 +1257,7 @@ static ScrStr *scr_url_to_path_impl(ScrUrl *u, bool win32) {
     char drive_sep = plen > 2 ? pp[2] : 0;
     if (letter < 'a' || letter > 'z' || drive_sep != ':') {
       free(out.data);
-      scr_throw_error_msg(SCR_ERR_TYPE, "File URL path must be absolute", 30);
+      scr_throw_error_msg_code(SCR_ERR_TYPE, "File URL path must be absolute", 30, "ERR_INVALID_FILE_URL_PATH");
       return NULL;
     }
     /* pathname.slice(1): the leading backslash drops. */
@@ -924,23 +1265,7 @@ static ScrStr *scr_url_to_path_impl(ScrUrl *u, bool win32) {
     free(out.data);
     return s;
   }
-  if (u->host->len > 0) {
-    /* Parse-time normalization already emptied "localhost". */
-    const char *plat =
-#if defined(__APPLE__)
-        "darwin";
-#elif defined(__linux__)
-        "linux";
-#elif defined(_WIN32)
-        "win32";
-#else
-        "posix";
-#endif
-    char msg[96];
-    int mlen = snprintf(msg, sizeof msg, "File URL host must be \"localhost\" or empty on %s", plat);
-    scr_throw_error_msg(SCR_ERR_TYPE, msg, (size_t)mlen);
-    return NULL;
-  }
+  if (!url_file_posix_host(u)) return NULL;
   for (size_t i = 0; i < len; i++) {
     if (p[i] == '%' && i + 2 < len) {
       int hi = hex_val(p[i + 1]);
@@ -948,8 +1273,8 @@ static ScrStr *scr_url_to_path_impl(ScrUrl *u, bool win32) {
       if (hi >= 0 && lo >= 0) {
         unsigned char decoded = (unsigned char)((hi << 4) | lo);
         if (decoded == '/') {
-          scr_throw_error_msg(SCR_ERR_TYPE,
-                               "File URL path must not include encoded / characters", 51);
+          scr_throw_error_msg_code(SCR_ERR_TYPE,
+                               "File URL path must not include encoded / characters", 51, "ERR_INVALID_FILE_URL_PATH");
           return NULL;
         }
         i += 2;
@@ -994,7 +1319,9 @@ static ScrUrl *scr_url_new_file(ScrStr *host, ScrStr *encoded_path) {
   u->query = scr_str_new("", 0);
   u->fragment = scr_str_new("", 0);
   u->has_authority = true;
+  u->host_path_escape = false;
   u->sp_cache = NULL;
+  u->sp_reload = NULL;
   return u;
 }
 
@@ -1017,7 +1344,7 @@ static void scr_url_throw_arg_value(const char *reason, ScrStr *value) {
   ub_append(&msg, reason, strlen(reason));
   ub_append(&msg, ". Received ", 11);
   ub_push_inspected(&msg, value->data, value->len);
-  scr_throw_error_msg(SCR_ERR_TYPE, msg.data, msg.len);
+  scr_throw_error_msg_code(SCR_ERR_TYPE, msg.data, msg.len, "ERR_INVALID_ARG_VALUE");
   free(msg.data);
 }
 
@@ -1206,10 +1533,21 @@ static ScrDyn *scr_native_url_invoke(void *ptr, ScrDyn *self, const char *method
   return NULL;
 }
 
+static bool scr_native_url_set(void *ptr, const char *key, size_t len, const ScrDyn *value) {
+  bool modeled = (len == 4 && (!memcmp(key, "href", 4) || !memcmp(key, "hash", 4) || !memcmp(key, "host", 4) || !memcmp(key, "port", 4))) ||
+    (len == 8 && (!memcmp(key, "pathname", 8) || !memcmp(key, "protocol", 8) || !memcmp(key, "username", 8) || !memcmp(key, "password", 8) || !memcmp(key, "hostname", 8))) ||
+    (len == 6 && !memcmp(key, "search", 6));
+  if (!modeled) return false;
+  ScrStr *field = scr_str_new(key, len);
+  scr_url_set_checked(ptr, field, value);
+  scr_str_release(field);
+  return true;
+}
+
 ScrDyn *scr_dyn_native_url(ScrUrl *value) {
   static const ScrDynHandleOps ops = {
     "URL", &scr_url_retain_v, &scr_url_release_v, &scr_native_url_invoke,
-    &scr_native_url_get, NULL, NULL, NULL,
+    &scr_native_url_get, &scr_native_url_set, NULL, NULL,
   };
   scr_dyn_handle_install(SCR_DYNH_URL, &ops);
   return scr_dyn_new_handle(value, SCR_DYNH_URL);
@@ -1398,3 +1736,148 @@ ScrStr *scr_url_checked_to_path(const ScrDyn *value) {
   scr_dyn_arg_type_fail("path", "of type string or an instance of URL", value);
   return NULL;
 }
+
+/* Property reads keep option accessors/proxies live, including typed
+ * record getter closures and objects held by the dynamic engine. */
+static ScrDyn *url_property_read(const ScrDyn *object, const char *name) {
+  if (object->kind == SCR_DYN_TYPED_REF) {
+    ScrDyn *view = scr_dyn_typed_ref_materialize(object);
+    if (!view) return NULL;
+    char getter_name[64];
+    snprintf(getter_name, sizeof getter_name, "%%get:%s", name);
+    const ScrDyn *getter = scr_dyn_obj_get(view, getter_name, strlen(getter_name));
+    ScrDyn *value = getter ? scr_dyn_call(getter, NULL, 0, "getter") : url_property_read(view, name);
+    scr_dyn_release(view);
+    return value;
+  }
+  if (object->kind == SCR_DYN_JSVAL || object->kind == SCR_DYN_HANDLE) {
+    ScrStr *key = scr_str_new(name, strlen(name));
+    ScrDyn *value = object->kind == SCR_DYN_JSVAL ? scr_dyn_isl_key_get(object, key) : scr_dyn_handle_key_get(object, key);
+    scr_str_release(key);
+    return value;
+  }
+  return scr_dyn_obj_read(object, name, strlen(name));
+}
+
+/* options?.windows is a nullish default followed by JS truthiness. */
+static bool url_options_windows(const ScrDyn *options, bool *windows) {
+#ifdef _WIN32
+  *windows = true;
+#else
+  *windows = false;
+#endif
+  if (scr_dyn_is_nullish(options)) return true;
+  ScrDyn *value = url_property_read(options, "windows");
+  if (!value || scr_exc_pending()) { scr_dyn_release(value); return false; }
+  if (!scr_dyn_is_nullish(value)) *windows = scr_dyn_truthy(value);
+  scr_dyn_release(value);
+  return true;
+}
+
+static ScrUrl *url_checked_file_input(const ScrDyn *value) {
+  if (scr_dyn_native_url_is(value)) return scr_url_retain(value->v.handle.ptr);
+  if (value->kind == SCR_DYN_STR) return scr_url_new(value->v.str);
+  /* Node's isURL checks href/protocol/auth/path structurally. Keep the
+   * short circuit order and getter exceptions before its scheme check. */
+  bool is_url = !scr_dyn_is_nullish(value);
+  const char *keys[] = {"href", "protocol", "auth", "path"};
+  for (size_t i = 0; is_url && i < 4; i++) {
+    ScrDyn *property = url_property_read(value, keys[i]);
+    if (!property || scr_exc_pending()) { scr_dyn_release(property); return NULL; }
+    is_url = i < 2 ? scr_dyn_truthy(property) : property->kind == SCR_DYN_UNDEF;
+    scr_dyn_release(property);
+  }
+  if (!is_url) {
+    scr_dyn_arg_type_fail("path", "of type string or an instance of URL", value);
+    return NULL;
+  }
+  ScrDyn *protocol = url_property_read(value, "protocol");
+  if (!protocol || scr_exc_pending()) { scr_dyn_release(protocol); return NULL; }
+  bool file = protocol->kind == SCR_DYN_STR && protocol->v.str->len == 5 && memcmp(protocol->v.str->data, "file:", 5) == 0;
+  scr_dyn_release(protocol);
+  if (!file) {
+    scr_throw_error_msg_code(SCR_ERR_TYPE, "The URL must be of scheme file", 30, "ERR_INVALID_URL_SCHEME");
+    return NULL;
+  }
+  ScrDyn *host = url_property_read(value, "hostname");
+  if (!host || scr_exc_pending()) { scr_dyn_release(host); return NULL; }
+  ScrDyn *path = url_property_read(value, "pathname");
+  if (!path || scr_exc_pending()) { scr_dyn_release(host); scr_dyn_release(path); return NULL; }
+  if (host->kind != SCR_DYN_STR || path->kind != SCR_DYN_STR) {
+    static const char message[] = "file URL-like objects require string hostname and pathname properties in scriptc";
+    scr_throw_error_msg(SCR_ERR_TYPE, message, sizeof message - 1);
+    scr_dyn_release(host); scr_dyn_release(path);
+    return NULL;
+  }
+  ScrUrl *url = scr_url_new_file(scr_str_retain(host->v.str), scr_str_retain(path->v.str));
+  scr_dyn_release(host); scr_dyn_release(path);
+  return url;
+}
+
+ScrStr *scr_url_checked_to_path_options(const ScrDyn *value, const ScrDyn *options) {
+  bool windows;
+  if (!url_options_windows(options, &windows)) return NULL;
+  ScrUrl *url = url_checked_file_input(value);
+  if (!url) return NULL;
+  ScrStr *path = scr_url_to_path_impl(url, windows);
+  scr_url_release(url);
+  return path;
+}
+
+ScrUrl *scr_url_checked_from_path(const ScrDyn *value, const ScrDyn *options) {
+  if (value->kind != SCR_DYN_STR) {
+    scr_dyn_arg_type_fail("path", "of type string", value);
+    return NULL;
+  }
+  bool windows;
+  if (!url_options_windows(options, &windows)) return NULL;
+  return scr_url_from_path_impl(value->v.str, windows);
+}
+
+ScrBytes *scr_url_checked_to_path_buffer(const ScrDyn *value, const ScrDyn *options) {
+  bool windows;
+  if (!url_options_windows(options, &windows)) return NULL;
+  ScrUrl *url = url_checked_file_input(value);
+  if (!url) return NULL;
+  if (!url_file_scheme(url) || (!windows && !url_file_posix_host(url))) {
+    scr_url_release(url);
+    return NULL;
+  }
+  UrlBuf decoded;
+  ub_init(&decoded);
+  if (windows && url->host->len) {
+    ub_append(&decoded, "\\\\", 2);
+    ub_append(&decoded, url->host->data, url->host->len);
+  }
+  const char *path = url->path->data;
+  for (size_t i = 0; i < url->path->len; i++) {
+    if (path[i] == '%' && i + 2 < url->path->len) {
+      int high = hex_val(path[i + 1]), low = hex_val(path[i + 2]);
+      if (high >= 0 && low >= 0) {
+        ub_push(&decoded, (char)((high << 4) | low));
+        i += 2;
+        continue;
+      }
+    }
+    /* Convert literal separators before decoding: encoded %2F stays '/'.
+     * Invalid escapes and invalid UTF-8 are preserved as raw bytes. */
+    ub_push(&decoded, windows && path[i] == '/' ? '\\' : path[i]);
+  }
+  size_t start = 0;
+  if (windows && url->host->len == 0) {
+    int letter = (decoded.len > 1 ? (unsigned char)decoded.data[1] : 0) | 0x20;
+    if (letter < 'a' || letter > 'z' || decoded.len < 3 || decoded.data[2] != ':') {
+      free(decoded.data);
+      scr_url_release(url);
+      scr_throw_error_msg_code(SCR_ERR_TYPE, "File URL path must be absolute", 30, "ERR_INVALID_FILE_URL_PATH");
+      return NULL;
+    }
+    start = 1;
+  }
+  ScrBytes *result = scr_bytes_new(SCR_BYTES_U8, (double)(decoded.len - start));
+  result->is_buffer = true;
+  if (decoded.len > start) memcpy(result->data, decoded.data + start, decoded.len - start);
+  free(decoded.data);
+  scr_url_release(url);
+  return result;
+}