@scriptc/cli-darwin-arm64 0.2.0 → 0.2.2

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

@@ -7,6 +7,7 @@
  * encoding conversions (utf8 with WHATWG replacement, hex, base64) match
  * Node byte-for-byte — the differential corpus holds them to it. */
 #include "scr_runtime.h"
+#include "scr_text_decoder_labels.h"
 #ifdef SCR_TEXT_DECODER_LEGACY
 #include "scr_text_decoder_data.h"
 #endif
@@ -16,6 +17,61 @@
 #include <stdlib.h>
 #include <string.h>
 
+static bool scr_td_label_space(unsigned char c) {
+  return c == 9 || c == 10 || c == 12 || c == 13 || c == 32;
+}
+
+double scr_text_decoder_encoding(const ScrDyn *label) {
+  if (!label || label->kind == SCR_DYN_UNDEF) return -1;
+  ScrStr *text = scr_dyn_string_coerce_js(label);
+  if (!text) return -1;
+  size_t start = 0, end = text->len;
+  while (start < end && scr_td_label_space((unsigned char)text->data[start])) start++;
+  while (end > start && scr_td_label_space((unsigned char)text->data[end - 1])) end--;
+  for (size_t i = 0; i < sizeof scr_td_labels / sizeof scr_td_labels[0]; i++) {
+    const char *candidate = scr_td_labels[i].label;
+    if (strlen(candidate) != end - start) continue;
+    bool matches = true;
+    for (size_t j = start; j < end; j++) {
+      unsigned char c = (unsigned char)text->data[j];
+      if (c >= 'A' && c <= 'Z') c += 'a' - 'A';
+      if (c != (unsigned char)candidate[j - start]) { matches = false; break; }
+    }
+    if (matches) {
+      double result = scr_td_labels[i].encoding;
+      scr_str_release(text);
+      return result;
+    }
+  }
+  static const char prefix[] = "The \"";
+  static const char suffix[] = "\" encoding is not supported";
+  size_t length = sizeof prefix - 1 + text->len + sizeof suffix - 1;
+  char *message = malloc(length + 1);
+  if (!message) scr_trap("scriptc: out of memory\n");
+  memcpy(message, prefix, sizeof prefix - 1);
+  memcpy(message + sizeof prefix - 1, text->data, text->len);
+  memcpy(message + sizeof prefix - 1 + text->len, suffix, sizeof suffix);
+  scr_throw_error_msg_code(SCR_ERR_RANGE, message, length, "ERR_ENCODING_NOT_SUPPORTED");
+  free(message);
+  scr_str_release(text);
+  return -1;
+}
+
+ScrStr *scr_text_decoder_name(double encoding) {
+  static const char *names[] = {
+    "ibm866", "iso-8859-2", "iso-8859-3", "iso-8859-4", "iso-8859-5",
+    "iso-8859-6", "iso-8859-7", "iso-8859-8", "iso-8859-10", "iso-8859-13",
+    "iso-8859-14", "iso-8859-15", "iso-8859-16", "koi8-r", "koi8-u",
+    "macintosh", "windows-874", "windows-1250", "windows-1251", "windows-1252",
+    "windows-1253", "windows-1254", "windows-1255", "windows-1256", "windows-1257",
+    "windows-1258", "x-mac-cyrillic", "x-user-defined", "utf-16le", "utf-16be",
+    "gb18030", "big5", "euc-jp", "iso-2022-jp", "shift_jis", "euc-kr",
+    "iso-8859-8-i", "gbk",
+  };
+  const char *name = encoding < 0 ? "utf-8" : names[(unsigned)encoding];
+  return scr_str_new(name, strlen(name));
+}
+
 #ifdef SCR_RC_AUDIT
 static SCR_TL long scr_live_bytes = 0;
 long scr_bytes_live_count(void) { return scr_live_bytes; }
@@ -70,6 +126,7 @@ static ScrBytes *scr_bytes_alloc(ScrBytesElem elem, size_t len) {
   if (!b->data) scr_bytes_oom();
   b->backing = NULL;
   b->is_buffer = false;
+  b->is_data_view = false;
   b->external = false;
 #ifdef SCR_RC_AUDIT
   scr_live_bytes++;
@@ -129,6 +186,7 @@ ScrBytes *scr_bytes_raw_view(ScrBytes *bytes) {
 
 ScrBytes *scr_bytes_as_buffer(ScrBytes *bytes) {
   bytes->is_buffer = true;
+  bytes->is_data_view = false;
   return scr_bytes_retain(bytes);
 }
 
@@ -172,9 +230,8 @@ double scr_bytes_byte_len(const ScrBytes *b) {
 }
 
 /* ── element access ────────────────────────────────────────────────────
- * JS reads undefined and IGNORES writes out of bounds on typed arrays;
- * both are unrepresentable here, so any invalid index traps — the array
- * runtime's exact discipline (SEMANTICS.md). */
+ * Invalid writes are ignored. Typed numeric reads cannot represent
+ * undefined, so invalid reads trap; checked reads return undefined. */
 
 static size_t scr_bytes_check_index(const ScrBytes *b, double i) {
   if (!(i >= 0) || i != trunc(i) || i >= (double)b->len) {
@@ -241,7 +298,8 @@ double scr_bytes_get(const ScrBytes *b, double i) {
 }
 
 void scr_bytes_set(ScrBytes *b, double i, double v) {
-  size_t idx = scr_bytes_check_index(b, i);
+  if (!(i >= 0) || i != trunc(i) || i >= (double)b->len) return;
+  size_t idx = (size_t)i;
   switch (b->elem) {
     case SCR_BYTES_U8: case SCR_BYTES_I8:
       b->data[idx] = (uint8_t)scr_bytes_to_u32(v);
@@ -341,6 +399,7 @@ ScrBytes *scr_bytes_subarray(ScrBytes *b, double start, double end) {
   v->data = b->data + s * scr_bytes_elem_size(b->elem);
   v->backing = scr_bytes_retain(owner);
   v->is_buffer = b->is_buffer;
+  v->is_data_view = false;
   v->external = false;
 #ifdef SCR_RC_AUDIT
   scr_live_bytes++;
@@ -554,6 +613,7 @@ ScrBytes *scr_dataview_new(ScrBytes *src, double byte_off, bool has_len, double
   v->data = owner->data + (size_t)off;
   v->backing = scr_bytes_retain(owner);
   v->is_buffer = false;
+  v->is_data_view = true;
   v->external = false;
 #ifdef SCR_RC_AUDIT
   scr_live_bytes++;
@@ -581,6 +641,7 @@ ScrBytes *scr_bytes_buffer_view(ScrBytes *src, ScrBytesElem elem,
   if (!view) return NULL;
   view->elem = elem;
   view->len /= width;
+  view->is_data_view = false;
   return view;
 }
 
@@ -699,7 +760,13 @@ static const char scr_hex_digits[] = "0123456789abcdef";
 /* WHATWG UTF-8 decode with U+FFFD replacement per maximal invalid subpart
  * — what Buffer.prototype.toString("utf8") does. Output re-encodes as
  * (now valid) UTF-8: worst case 3 bytes per input byte. */
-static ScrStr *scr_bytes_decode_utf8(const uint8_t *in, size_t n) {
+static void scr_td_invalid(const char *encoding) {
+  char message[160];
+  int n = snprintf(message, sizeof message, "The encoded data was not valid for encoding %s", encoding);
+  scr_throw_error_msg_code(SCR_ERR_TYPE, message, (size_t)n, "ERR_ENCODING_INVALID_ENCODED_DATA");
+}
+
+static ScrStr *scr_bytes_decode_utf8_options(const uint8_t *in, size_t n, bool fatal) {
   if (in == NULL && n != 0) {
     scr_trap("scriptc: native callback passed a NULL span with nonzero length\n");
   }
@@ -713,6 +780,7 @@ static ScrStr *scr_bytes_decode_utf8(const uint8_t *in, size_t n) {
   for (size_t i = 0; i <= n; i++) {
     if (i == n) {
       if (needed > 0) { /* EOF inside a sequence: one replacement */
+        if (fatal) { free(out); scr_td_invalid("utf-8"); return NULL; }
         memcpy(out + o, "\xef\xbf\xbd", 3);
         o += 3;
       }
@@ -733,6 +801,7 @@ static ScrStr *scr_bytes_decode_utf8(const uint8_t *in, size_t n) {
         if (byte == 0xf4) upper = 0x8f;
         needed = 3; cp = byte & 0x7;
       } else {
+        if (fatal) { free(out); scr_td_invalid("utf-8"); return NULL; }
         memcpy(out + o, "\xef\xbf\xbd", 3);
         o += 3;
       }
@@ -740,6 +809,7 @@ static ScrStr *scr_bytes_decode_utf8(const uint8_t *in, size_t n) {
     }
     if (byte < lower || byte > upper) {
       /* Invalid continuation: replace the subpart, REPROCESS this byte. */
+      if (fatal) { free(out); scr_td_invalid("utf-8"); return NULL; }
       memcpy(out + o, "\xef\xbf\xbd", 3);
       o += 3;
       needed = 0; lower = 0x80; upper = 0xbf;
@@ -772,6 +842,10 @@ static ScrStr *scr_bytes_decode_utf8(const uint8_t *in, size_t n) {
   return s;
 }
 
+static ScrStr *scr_bytes_decode_utf8(const uint8_t *in, size_t n) {
+  return scr_bytes_decode_utf8_options(in, n, false);
+}
+
 ScrStr *scr_str_from_utf8_lossy(const uint8_t *bytes, size_t len) {
   return scr_bytes_decode_utf8(bytes, len);
 }
@@ -780,14 +854,47 @@ ScrStr *scr_str_from_utf8_lossy(const uint8_t *bytes, size_t len) {
  * subpart replacement decode as toString("utf8") above, with one
  * difference — a leading UTF-8 BOM is stripped (ignoreBOM defaults to
  * false in the spec; Buffer.toString keeps the BOM as U+FEFF). */
-ScrStr *scr_text_decode(const ScrBytes *b) {
+ScrStr *scr_text_decode_options(const ScrBytes *b, bool fatal, bool ignore_bom) {
   const uint8_t *in = b->data;
   size_t n = b->len;
-  if (n >= 3 && in[0] == 0xef && in[1] == 0xbb && in[2] == 0xbf) {
+  if (!ignore_bom && n >= 3 && in[0] == 0xef && in[1] == 0xbb && in[2] == 0xbf) {
     in += 3;
     n -= 3;
   }
-  return scr_bytes_decode_utf8(in, n);
+  return scr_bytes_decode_utf8_options(in, n, fatal);
+}
+
+ScrBytes *scr_bytes_buffer_source(const ScrDyn *value) {
+  if (value->kind == SCR_DYN_TYPED_REF) {
+    ScrDyn *materialized = scr_dyn_typed_ref_materialize(value);
+    if (!materialized) return NULL;
+    ScrBytes *result = scr_bytes_buffer_source(materialized);
+    scr_dyn_release(materialized);
+    return result;
+  }
+  if (value->kind == SCR_DYN_UNDEF) return scr_bytes_new(SCR_BYTES_U8, 0);
+  if (value->kind == SCR_DYN_BYTES) {
+    ScrBytes *bytes = value->v.bytes;
+    return scr_bytes_buffer_view(bytes, SCR_BYTES_U8, scr_bytes_byte_offset(bytes), true, scr_bytes_byte_len(bytes));
+  }
+  if (scr_array_buffer_is(value)) {
+    return scr_array_buffer_view(SCR_BYTES_U8, value, scr_dyn_undefined(), scr_dyn_undefined());
+  }
+  static const char message[] = "The input argument must be an instance of SharedArrayBuffer, ArrayBuffer or ArrayBufferView.";
+  scr_throw_error_msg_code(SCR_ERR_TYPE, message, sizeof message - 1, "ERR_INVALID_ARG_TYPE");
+  return NULL;
+}
+
+ScrStr *scr_text_decode_buffer_source(const ScrDyn *value) {
+  ScrBytes *view = scr_bytes_buffer_source(value);
+  if (!view) return NULL;
+  ScrStr *out = scr_text_decode(view);
+  scr_bytes_release(view);
+  return out;
+}
+
+ScrStr *scr_text_decode(const ScrBytes *b) {
+  return scr_text_decode_options(b, false, false);
 }
 
 /* ── node:string_decoder, the utf8 StringDecoder ─────────────────────────
@@ -1067,11 +1174,12 @@ enum {
 typedef struct {
   char *data;
   size_t len;
+  bool failed;
 } ScrTdOut;
 
 static ScrTdOut scr_td_out_new(size_t input_len) {
   if (input_len > (SIZE_MAX - 8) / 3) scr_bytes_oom();
-  ScrTdOut out = { malloc(input_len * 3 + 8), 0 };
+  ScrTdOut out = { malloc(input_len * 3 + 8), 0, false };
   if (!out.data) scr_bytes_oom();
   return out;
 }
@@ -1081,39 +1189,42 @@ static void scr_td_put(ScrTdOut *out, uint32_t cp) {
 }
 
 static void scr_td_error(ScrTdOut *out) {
+  out->failed = true;
   scr_td_put(out, 0xfffd);
 }
 
-static ScrStr *scr_td_finish(ScrTdOut *out) {
+static ScrStr *scr_td_finish(ScrTdOut *out, bool fatal) {
+  if (fatal && out->failed) { free(out->data); scr_td_invalid("legacy encoding"); return NULL; }
   ScrStr *str = scr_str_new(out->data, out->len);
   free(out->data);
   return str;
 }
 
-static ScrStr *scr_td_single_byte(const ScrBytes *b, unsigned encoding) {
+static ScrStr *scr_td_single_byte(const ScrBytes *b, unsigned encoding, bool fatal) {
   ScrTdOut out = scr_td_out_new(b->len);
   for (size_t i = 0; i < b->len; i++) {
     uint8_t byte = b->data[i];
-    scr_td_put(&out, byte < 0x80 ? byte : scr_td_single[encoding][byte - 0x80]);
+    uint32_t cp = byte < 0x80 ? byte : scr_td_single[encoding][byte - 0x80];
+    if (cp == 0xfffd) scr_td_error(&out); else scr_td_put(&out, cp);
   }
-  return scr_td_finish(&out);
+  return scr_td_finish(&out, fatal);
 }
 
-static ScrStr *scr_td_x_user_defined(const ScrBytes *b) {
+static ScrStr *scr_td_x_user_defined(const ScrBytes *b, bool fatal) {
   ScrTdOut out = scr_td_out_new(b->len);
   for (size_t i = 0; i < b->len; i++) {
     uint8_t byte = b->data[i];
     scr_td_put(&out, byte < 0x80 ? byte : 0xf780 + byte - 0x80);
   }
-  return scr_td_finish(&out);
+  return scr_td_finish(&out, fatal);
 }
 
-static ScrStr *scr_td_utf16(const ScrBytes *b, bool be) {
+static ScrStr *scr_td_utf16(const ScrBytes *b, bool be, bool fatal, bool ignore_bom) {
   const uint8_t *in = b->data;
   size_t n = b->len;
   /* TextDecoder's BOM handling strips only the BOM matching the selected
    * endian decoder. The opposite BOM decodes to U+FFFE and remains. */
-  if (n >= 2 && ((!be && in[0] == 0xff && in[1] == 0xfe) ||
+  if (!ignore_bom && n >= 2 && ((!be && in[0] == 0xff && in[1] == 0xfe) ||
                  (be && in[0] == 0xfe && in[1] == 0xff))) {
     in += 2;
     n -= 2;
@@ -1146,7 +1257,7 @@ static ScrStr *scr_td_utf16(const ScrBytes *b, bool be) {
     else scr_td_put(&out, cu);
   }
   if (i < n) scr_td_error(&out); /* odd trailing byte */
-  return scr_td_finish(&out);
+  return scr_td_finish(&out, fatal);
 }
 
 static uint32_t scr_td_gb_range(uint32_t pointer) {
@@ -1165,7 +1276,7 @@ static uint32_t scr_td_gb_range(uint32_t pointer) {
 /* A tiny prepend stack models the Encoding Standard's I/O queue restore.
  * The gb18030 decoder is the only legacy decoder which can restore three
  * bytes after discovering a malformed four-byte sequence. */
-static ScrStr *scr_td_gb18030_decode(const ScrBytes *b) {
+static ScrStr *scr_td_gb18030_decode(const ScrBytes *b, bool fatal) {
   ScrTdOut out = scr_td_out_new(b->len);
   uint8_t first = 0, second = 0, third = 0;
   uint8_t replay[3];
@@ -1238,10 +1349,10 @@ static ScrStr *scr_td_gb18030_decode(const ScrBytes *b) {
     else scr_td_error(&out);
   }
   if (first || second || third) scr_td_error(&out);
-  return scr_td_finish(&out);
+  return scr_td_finish(&out, fatal);
 }
 
-static ScrStr *scr_td_big5_decode(const ScrBytes *b) {
+static ScrStr *scr_td_big5_decode(const ScrBytes *b, bool fatal) {
   ScrTdOut out = scr_td_out_new(b->len);
   uint8_t lead = 0;
   for (size_t i = 0; i < b->len; i++) {
@@ -1267,10 +1378,10 @@ static ScrStr *scr_td_big5_decode(const ScrBytes *b) {
     else scr_td_error(&out);
   }
   if (lead) scr_td_error(&out);
-  return scr_td_finish(&out);
+  return scr_td_finish(&out, fatal);
 }
 
-static ScrStr *scr_td_euc_jp_decode(const ScrBytes *b) {
+static ScrStr *scr_td_euc_jp_decode(const ScrBytes *b, bool fatal) {
   ScrTdOut out = scr_td_out_new(b->len);
   uint8_t lead = 0;
   bool jis0212 = false;
@@ -1330,10 +1441,10 @@ static ScrStr *scr_td_euc_jp_decode(const ScrBytes *b) {
     else scr_td_error(&out);
   }
   if (lead) scr_td_error(&out);
-  return scr_td_finish(&out);
+  return scr_td_finish(&out, fatal);
 }
 
-static ScrStr *scr_td_shift_jis_decode(const ScrBytes *b) {
+static ScrStr *scr_td_shift_jis_decode(const ScrBytes *b, bool fatal) {
   ScrTdOut out = scr_td_out_new(b->len);
   uint8_t lead = 0;
   for (size_t i = 0; i < b->len; i++) {
@@ -1367,10 +1478,10 @@ static ScrStr *scr_td_shift_jis_decode(const ScrBytes *b) {
     else scr_td_error(&out);
   }
   if (lead) scr_td_error(&out);
-  return scr_td_finish(&out);
+  return scr_td_finish(&out, fatal);
 }
 
-static ScrStr *scr_td_euc_kr_decode(const ScrBytes *b) {
+static ScrStr *scr_td_euc_kr_decode(const ScrBytes *b, bool fatal) {
   ScrTdOut out = scr_td_out_new(b->len);
   uint8_t lead = 0;
   for (size_t i = 0; i < b->len; i++) {
@@ -1393,7 +1504,7 @@ static ScrStr *scr_td_euc_kr_decode(const ScrBytes *b) {
     else scr_td_error(&out);
   }
   if (lead) scr_td_error(&out);
-  return scr_td_finish(&out);
+  return scr_td_finish(&out, fatal);
 }
 
 enum ScrTdIsoState {
@@ -1406,7 +1517,7 @@ enum ScrTdIsoState {
   SCR_TD_ISO_ESCAPE,
 };
 
-static ScrStr *scr_td_iso_2022_jp_decode(const ScrBytes *b) {
+static ScrStr *scr_td_iso_2022_jp_decode(const ScrBytes *b, bool fatal) {
   ScrTdOut out = scr_td_out_new(b->len);
   enum ScrTdIsoState state = SCR_TD_ISO_ASCII;
   enum ScrTdIsoState output_state = SCR_TD_ISO_ASCII;
@@ -1574,27 +1685,98 @@ static ScrStr *scr_td_iso_2022_jp_decode(const ScrBytes *b) {
       }
     }
   }
-  return scr_td_finish(&out);
+  return scr_td_finish(&out, fatal);
 }
 
-ScrStr *scr_text_decode_legacy(const ScrBytes *b, double encoding_value) {
+ScrStr *scr_text_decode_legacy_options(const ScrBytes *b, double encoding_value, bool fatal, bool ignore_bom) {
   unsigned encoding = (unsigned)encoding_value;
-  if (encoding < SCR_TD_SINGLE_COUNT) return scr_td_single_byte(b, encoding);
+  if (encoding == 36) encoding = 7; /* ISO-8859-8-I */
+  if (encoding == 37) encoding = SCR_TD_GB18030; /* GBK */
+  if (encoding < SCR_TD_SINGLE_COUNT) return scr_td_single_byte(b, encoding, fatal);
   switch (encoding) {
-    case SCR_TD_X_USER_DEFINED: return scr_td_x_user_defined(b);
-    case SCR_TD_UTF16LE: return scr_td_utf16(b, false);
-    case SCR_TD_UTF16BE: return scr_td_utf16(b, true);
-    case SCR_TD_GB18030: return scr_td_gb18030_decode(b);
-    case SCR_TD_BIG5: return scr_td_big5_decode(b);
-    case SCR_TD_EUC_JP: return scr_td_euc_jp_decode(b);
-    case SCR_TD_ISO_2022_JP: return scr_td_iso_2022_jp_decode(b);
-    case SCR_TD_SHIFT_JIS: return scr_td_shift_jis_decode(b);
-    case SCR_TD_EUC_KR: return scr_td_euc_kr_decode(b);
+    case SCR_TD_X_USER_DEFINED: return scr_td_x_user_defined(b, fatal);
+    case SCR_TD_UTF16LE: return scr_td_utf16(b, false, fatal, ignore_bom);
+    case SCR_TD_UTF16BE: return scr_td_utf16(b, true, fatal, ignore_bom);
+    case SCR_TD_GB18030: return scr_td_gb18030_decode(b, fatal);
+    case SCR_TD_BIG5: return scr_td_big5_decode(b, fatal);
+    case SCR_TD_EUC_JP: return scr_td_euc_jp_decode(b, fatal);
+    case SCR_TD_ISO_2022_JP: return scr_td_iso_2022_jp_decode(b, fatal);
+    case SCR_TD_SHIFT_JIS: return scr_td_shift_jis_decode(b, fatal);
+    case SCR_TD_EUC_KR: return scr_td_euc_kr_decode(b, fatal);
     default: return scr_str_new("", 0); /* compiler invariant */
   }
 }
+ScrStr *scr_text_decode_legacy(const ScrBytes *b, double encoding_value) {
+  return scr_text_decode_legacy_options(b, encoding_value, false, false);
+}
 #endif /* SCR_TEXT_DECODER_LEGACY */
 
+/* Streaming decoders retain only an incomplete character and whether the
+ * initial BOM has been handled. The state object belongs to the codec's
+ * private record, so aliases and closure captures share the same decoder. */
+static size_t scr_td_utf8_tail(const uint8_t *bytes, size_t n) {
+  size_t tail = scr_strdec_tail(bytes, n);
+  if (!tail) return 0;
+  uint8_t lead = bytes[n - tail];
+  if (lead < 0xc2 || lead > 0xf4) return 0;
+  if (tail > 1) {
+    uint8_t second = bytes[n - tail + 1];
+    if ((lead == 0xe0 && second < 0xa0) || (lead == 0xed && second > 0x9f) ||
+        (lead == 0xf0 && second < 0x90) || (lead == 0xf4 && second > 0x8f)) return 0;
+  }
+  return tail;
+}
+
+ScrStr *scr_text_decode_stream(ScrDyn *state, const ScrBytes *input,
+    double encoding, bool fatal, bool ignore_bom, bool stream) {
+  if (encoding == 36) encoding = 7; /* ISO-8859-8-I is a single-byte decoder. */
+  ScrDyn *saved = scr_dyn_obj_read(state, "pending", 7);
+  size_t pending = saved->kind == SCR_DYN_BYTES ? saved->v.bytes->len : 0;
+  if (input->len > SIZE_MAX - pending) scr_bytes_oom();
+  ScrBytes *combined = scr_bytes_new(SCR_BYTES_U8, (double)(pending + input->len));
+  if (pending) memcpy(combined->data, saved->v.bytes->data, pending);
+  if (input->len) memcpy(combined->data + pending, input->data, input->len);
+  scr_dyn_release(saved);
+  ScrDyn *bom = scr_dyn_obj_read(state, "bom", 3);
+  bool seen_bom = scr_dyn_truthy(bom);
+  scr_dyn_release(bom);
+  size_t hold = stream && encoding < 0 ? scr_td_utf8_tail(combined->data, combined->len) : 0;
+#ifdef SCR_TEXT_DECODER_LEGACY
+  if (stream && ((unsigned)encoding == SCR_TD_UTF16LE || (unsigned)encoding == SCR_TD_UTF16BE)) {
+    size_t complete = combined->len & ~(size_t)1;
+    hold = combined->len - complete;
+    if (complete >= 2) {
+      const uint8_t *last = combined->data + complete - 2;
+      uint16_t unit = (unsigned)encoding == SCR_TD_UTF16BE
+        ? ((uint16_t)last[0] << 8) | last[1] : last[0] | ((uint16_t)last[1] << 8);
+      if (unit >= 0xd800 && unit <= 0xdbff) hold += 2;
+    }
+  }
+  if (stream && encoding >= SCR_TD_GB18030) {
+    scr_bytes_release(combined);
+    static const char message[] = "Streaming TextDecoder for this legacy encoding has no native lowering";
+    scr_throw_error_msg_code(SCR_ERR_ERROR, message, sizeof message - 1, "SC2020");
+    return NULL;
+  }
+#endif
+  size_t complete = combined->len - hold;
+  ScrBytes *tail = scr_bytes_new(SCR_BYTES_U8, (double)hold);
+  if (hold) memcpy(tail->data, combined->data + complete, hold);
+  scr_dyn_obj_set(state, "pending", 7, scr_dyn_new_bytes(tail));
+  scr_bytes_release(tail);
+  scr_dyn_obj_set(state, "bom", 3, scr_dyn_new_bool(stream && (seen_bom || complete > 0)));
+  combined->len = complete;
+  ScrStr *result;
+  if (encoding < 0) result = scr_text_decode_options(combined, fatal, ignore_bom || seen_bom);
+#ifdef SCR_TEXT_DECODER_LEGACY
+  else result = scr_text_decode_legacy_options(combined, encoding, fatal, ignore_bom || seen_bom);
+#else
+  else { result = NULL; scr_trap("legacy TextDecoder requires its runtime pack variant"); }
+#endif
+  scr_bytes_release(combined);
+  return result;
+}
+
 /* Decode the next code point from an ScrStr's storage — ALWAYS valid
  * UTF-8 (the string runtime never stores ill-formed sequences), so no
  * validation re-runs here. */
@@ -1621,6 +1803,214 @@ static uint32_t scr_bytes_next_cp(const uint8_t *in, size_t *ip) {
   return cp;
 }
 
+/* encodeInto consumes complete Unicode scalars while counting UTF-16 units.
+ * Borrow the destination so writes through a subarray retain their aliasing. */
+ScrDyn *scr_text_encode_into(const ScrDyn *source, const ScrDyn *destination) {
+  if (source->kind != SCR_DYN_STR) {
+    scr_dyn_arg_type_fail("src", "of type string", source);
+    return NULL;
+  }
+  if (destination->kind != SCR_DYN_BYTES || destination->v.bytes->elem != SCR_BYTES_U8 || destination->v.bytes->is_data_view) {
+    scr_dyn_arg_type_fail("dest", "an instance of Uint8Array", destination);
+    return NULL;
+  }
+  const ScrStr *text = source->v.str;
+  ScrBytes *dest = destination->v.bytes;
+  size_t read = 0, written = 0;
+  while (written < text->len) {
+    size_t end = written;
+    uint32_t cp = scr_bytes_next_cp((const uint8_t *)text->data, &end);
+    if (end > dest->len) break;
+    read += cp > 0xffff ? 2 : 1;
+    written = end;
+  }
+  if (written) memcpy(dest->data, text->data, written);
+  ScrDyn *result = scr_dyn_new_obj();
+  scr_dyn_obj_set(result, "read", 4, scr_dyn_new_num((double)read));
+  scr_dyn_obj_set(result, "written", 7, scr_dyn_new_num((double)written));
+  return result;
+}
+
+static ScrBytes *scr_buffer_validation_input(const ScrDyn *input) {
+  if ((input->kind == SCR_DYN_BYTES && !input->v.bytes->is_data_view) || scr_array_buffer_is(input)) {
+    return scr_bytes_buffer_source(input);
+  }
+  scr_dyn_arg_type_fail("input", "an instance of ArrayBuffer, Buffer, or TypedArray", input);
+  return NULL;
+}
+
+static bool scr_buffer_utf8_valid(const uint8_t *data, size_t len) {
+  size_t i = 0;
+  while (i < len) {
+    unsigned byte = data[i++], count;
+    unsigned low = 0x80, high = 0xbf;
+    if (byte < 0x80) continue;
+    if (byte >= 0xc2 && byte <= 0xdf) count = 1;
+    else if (byte >= 0xe0 && byte <= 0xef) {
+      count = 2;
+      if (byte == 0xe0) low = 0xa0;
+      if (byte == 0xed) high = 0x9f;
+    } else if (byte >= 0xf0 && byte <= 0xf4) {
+      count = 3;
+      if (byte == 0xf0) low = 0x90;
+      if (byte == 0xf4) high = 0x8f;
+    } else return false;
+    if (count > len - i || data[i] < low || data[i] > high) return false;
+    i++;
+    for (unsigned j = 1; j < count; j++, i++) if (data[i] < 0x80 || data[i] > 0xbf) return false;
+  }
+  return true;
+}
+
+bool scr_buffer_is_ascii(const ScrDyn *input) {
+  ScrBytes *bytes = scr_buffer_validation_input(input);
+  if (!bytes) return false;
+  bool result = true;
+  for (size_t i = 0; i < bytes->len; i++) if (bytes->data[i] > 0x7f) { result = false; break; }
+  scr_bytes_release(bytes);
+  return result;
+}
+
+bool scr_buffer_is_utf8(const ScrDyn *input) {
+  ScrBytes *bytes = scr_buffer_validation_input(input);
+  if (!bytes) return false;
+  bool result = scr_buffer_utf8_valid(bytes->data, bytes->len);
+  scr_bytes_release(bytes);
+  return result;
+}
+
+/* Node's ICU wrapper recognizes Buffer encoding aliases. Empty inputs return
+ * before resolving either encoding. The four actual converter families are
+ * implemented here without adding an ICU dependency to a native binary. */
+enum { SCR_TC_UTF8, SCR_TC_ASCII, SCR_TC_LATIN1, SCR_TC_UTF16 };
+
+static int scr_transcode_encoding(const ScrDyn *value) {
+  if (value->kind == SCR_DYN_NULL || value->kind == SCR_DYN_UNDEF ||
+      (value->kind == SCR_DYN_STR && value->v.str->len == 0)) return SCR_TC_UTF8;
+  if (value->kind != SCR_DYN_STR) return -1;
+  const ScrStr *name = value->v.str;
+  static const struct { const char *name; int encoding; } aliases[] = {
+    {"utf8", SCR_TC_UTF8}, {"utf-8", SCR_TC_UTF8}, {"ascii", SCR_TC_ASCII},
+    {"latin1", SCR_TC_LATIN1}, {"binary", SCR_TC_LATIN1},
+    {"utf16le", SCR_TC_UTF16}, {"utf-16le", SCR_TC_UTF16},
+    {"ucs2", SCR_TC_UTF16}, {"ucs-2", SCR_TC_UTF16},
+  };
+  for (size_t i = 0; i < sizeof aliases / sizeof aliases[0]; i++) {
+    if (strlen(aliases[i].name) != name->len) continue;
+    bool match = true;
+    for (size_t j = 0; j < name->len; j++) {
+      unsigned char c = (unsigned char)name->data[j];
+      if (c >= 'A' && c <= 'Z') c += 'a' - 'A';
+      if (c != (unsigned char)aliases[i].name[j]) { match = false; break; }
+    }
+    if (match) return aliases[i].encoding;
+  }
+  return -1;
+}
+
+static ScrBytes *scr_transcode_error(bool invalid_data) {
+  const char *code = invalid_data ? "U_INVALID_CHAR_FOUND" : "U_ILLEGAL_ARGUMENT_ERROR";
+  char message[100];
+  int length = snprintf(message, sizeof message, "Unable to transcode Buffer [%s]", code);
+  ScrStr *text = scr_str_new(message, (size_t)length);
+  ScrError *error = scr_error_new(SCR_ERR_ERROR, text);
+  scr_str_release(text);
+  scr_error_set_code(error, code);
+  scr_throw_obj(error, &scr_error_retain_v, &scr_error_release_v, scr_error_trace_arg());
+  return NULL;
+}
+
+/* ICU's pinned substitute callback skips unmappable default-ignorable code
+ * points. Mappable Latin-1 characters (including soft hyphen) still survive. */
+static bool scr_transcode_ignorable(uint32_t cp) {
+  return cp == 0xad || cp == 0x34f || cp == 0x61c || cp == 0x115f || cp == 0x1160 ||
+    (cp >= 0x17b4 && cp <= 0x17b5) || (cp >= 0x180b && cp <= 0x180f) ||
+    (cp >= 0x200b && cp <= 0x200f) || (cp >= 0x202a && cp <= 0x202e) ||
+    (cp >= 0x2060 && cp <= 0x206f) || cp == 0x3164 ||
+    (cp >= 0xfe00 && cp <= 0xfe0f) || cp == 0xfeff || cp == 0xffa0 ||
+    (cp >= 0xfff0 && cp <= 0xfff8) || (cp >= 0x1bca0 && cp <= 0x1bca3) ||
+    (cp >= 0x1d173 && cp <= 0x1d17a) || (cp >= 0xe0000 && cp <= 0xe0fff);
+}
+
+static size_t scr_transcode_put(uint8_t *out, size_t index, uint32_t cp, int encoding) {
+  if (encoding == SCR_TC_ASCII || encoding == SCR_TC_LATIN1) {
+    unsigned limit = encoding == SCR_TC_ASCII ? 0x7f : 0xff;
+    if (cp <= limit) out[index++] = (uint8_t)cp;
+    else if (!scr_transcode_ignorable(cp)) out[index++] = '?';
+  } else if (encoding == SCR_TC_UTF16) {
+    if (cp > 0xffff) {
+      uint32_t high = 0xd800 + ((cp - 0x10000) >> 10);
+      out[index++] = (uint8_t)high;
+      out[index++] = (uint8_t)(high >> 8);
+      cp = 0xdc00 + ((cp - 0x10000) & 0x3ff);
+    }
+    out[index++] = (uint8_t)cp;
+    out[index++] = (uint8_t)(cp >> 8);
+  } else if (cp < 0x80) out[index++] = (uint8_t)cp;
+  else if (cp < 0x800) {
+    out[index++] = 0xc0 | (cp >> 6); out[index++] = 0x80 | (cp & 63);
+  } else if (cp < 0x10000) {
+    out[index++] = 0xe0 | (cp >> 12); out[index++] = 0x80 | ((cp >> 6) & 63); out[index++] = 0x80 | (cp & 63);
+  } else {
+    out[index++] = 0xf0 | (cp >> 18); out[index++] = 0x80 | ((cp >> 12) & 63);
+    out[index++] = 0x80 | ((cp >> 6) & 63); out[index++] = 0x80 | (cp & 63);
+  }
+  return index;
+}
+
+ScrBytes *scr_buffer_transcode(const ScrDyn *source, const ScrDyn *from, const ScrDyn *to) {
+  if (source->kind != SCR_DYN_BYTES || source->v.bytes->elem != SCR_BYTES_U8 || source->v.bytes->is_data_view) {
+    scr_dyn_arg_type_fail("source", "an instance of Buffer or Uint8Array", source);
+    return NULL;
+  }
+  const ScrBytes *input = source->v.bytes;
+  size_t len = input->len;
+  if (!len) { ScrBytes *empty = scr_bytes_alloc(SCR_BYTES_U8, 0); empty->is_buffer = true; return empty; }
+  int from_encoding = scr_transcode_encoding(from), to_encoding = scr_transcode_encoding(to);
+  if (from_encoding < 0 || to_encoding < 0) return scr_transcode_error(false);
+  if (len > (SIZE_MAX - 4) / 4) scr_bytes_oom();
+  ScrBytes *result = scr_bytes_alloc(SCR_BYTES_U8, len * 4 + 4);
+  result->is_buffer = true;
+  size_t written = 0;
+  if (from_encoding == SCR_TC_UTF8) {
+    if (to_encoding == SCR_TC_UTF16 && !scr_buffer_utf8_valid(input->data, len)) {
+      scr_bytes_release(result); return scr_transcode_error(true);
+    }
+    ScrStr *text = scr_str_from_utf8_lossy(input->data, len);
+    for (size_t i = 0; i < text->len;) {
+      uint32_t cp = scr_bytes_next_cp((const uint8_t *)text->data, &i);
+      written = scr_transcode_put(result->data, written, cp, to_encoding);
+    }
+    scr_str_release(text);
+  } else if (from_encoding == SCR_TC_UTF16) {
+    size_t end = to_encoding == SCR_TC_UTF16 ? len : len & ~(size_t)1;
+    if (to_encoding == SCR_TC_UTF8 && end == 0) { scr_bytes_release(result); return scr_transcode_error(true); }
+    for (size_t i = 0; i < end;) {
+      uint32_t cp = 0xfffd;
+      bool invalid = false;
+      if (i + 1 < end) {
+        cp = input->data[i] | ((uint32_t)input->data[i + 1] << 8);
+        i += 2;
+        if (cp >= 0xd800 && cp <= 0xdbff) {
+          uint32_t next = i + 1 < end ? input->data[i] | ((uint32_t)input->data[i + 1] << 8) : 0;
+          if (next >= 0xdc00 && next <= 0xdfff) { cp = 0x10000 + ((cp - 0xd800) << 10) + next - 0xdc00; i += 2; }
+          else { cp = 0xfffd; invalid = true; }
+        } else if (cp >= 0xdc00 && cp <= 0xdfff) { cp = 0xfffd; invalid = true; }
+      } else { i++; invalid = true; }
+      if (invalid && to_encoding == SCR_TC_UTF8) { scr_bytes_release(result); return scr_transcode_error(true); }
+      written = scr_transcode_put(result->data, written, cp, to_encoding);
+    }
+  } else {
+    for (size_t i = 0; i < len; i++) {
+      uint32_t cp = input->data[i];
+      if (from_encoding == SCR_TC_ASCII && cp > 0x7f && to_encoding != SCR_TC_UTF16) cp = 0xfffd;
+      written = scr_transcode_put(result->data, written, cp, to_encoding);
+    }
+  }
+  result->len = written;
+  return result;
+}
+
 static bool scr_enc_is(const ScrStr *enc, const char *name) {
   size_t n = strlen(name);
   return enc->len == n && memcmp(enc->data, name, n) == 0;