fix!: normalize blob layouts and support external byte ranges (#4589)

docs/src/js/functions/blob.md

@@ -11,6 +11,15 @@ function blob(name, options): Field
 ```
 
 Declares a `lance.blob.v2` column.
+Uses nullable `data`, `uri`, `position`, and `size` fields for inline bytes,
+whole external files, and external byte ranges. Set both `position` and
+positive `size` for a range, or omit both for a whole file.
+
+Existing two-field columns remain writable. Appends and merge inserts fill
+missing range fields with nulls for four-field targets and drop all-null
+range fields for two-field targets. Non-null ranges require a four-field
+target. Overwrite with Arrow input replaces the table's schema; row objects
+are converted using the current table schema.
 
 Query results are descriptors, not payload bytes. Use [Table.fetchBlobs](../classes/Table.md#fetchblobs)
 or [Table.fetchBlobFiles](../classes/Table.md#fetchblobfiles) to read bytes.

docs/src/js/type-aliases/BlobInput.md

@@ -12,6 +12,7 @@ type BlobInput:
   | BlobUri
   | object
   | object
+  | object
   | null
   | undefined;
 ```
@@ -20,6 +21,9 @@ A value accepted for a `lance.blob.v2` column (see [blob](../functions/blob.md))
 
 Either inline bytes, a URI pointing at external bytes, or a struct that sets
 exactly one of `data` or `uri`. `null` and `undefined` write a null blob.
+External byte ranges require both
+`position` (non-negative) and `size` (positive). Use safe integer numbers or
+`bigint` values for these unsigned 64-bit byte counts.
 
 ## Example