@perspective-dev/client 4.4.0 → 4.5.0

package/package.json

@@ -1,29 +1,53 @@
 {
   "name": "@perspective-dev/client",
-  "version": "4.4.0",
-  "description": "",
+  "version": "4.5.0",
+  "description": "Client for Perspective, a high-performance WASM engine with reactive Tables, Views, and joins.",
+  "keywords": [
+    "perspective",
+    "data",
+    "analytics",
+    "streaming",
+    "wasm",
+    "arrow",
+    "duckdb",
+    "clickhouse"
+  ],
+  "homepage": "https://perspective-dev.github.io",
   "repository": {
     "type": "git",
     "url": "https://github.com/perspective-dev/perspective"
   },
   "type": "module",
   "license": "Apache-2.0",
+  "sideEffects": false,
   "unpkg": "dist/cdn/perspective.js",
   "jsdelivr": "dist/cdn/perspective.js",
   "exports": {
     ".": {
       "node": {
         "types": "./dist/esm/perspective.node.d.ts",
+        "import": "./dist/esm/perspective.node.js",
         "default": "./dist/esm/perspective.node.js"
       },
       "types": "./dist/esm/perspective.browser.d.ts",
+      "import": "./dist/esm/perspective.js",
       "default": "./dist/esm/perspective.js"
     },
     "./node": {
       "types": "./dist/esm/perspective.node.d.ts",
+      "import": "./dist/esm/perspective.node.js",
       "default": "./dist/esm/perspective.node.js"
     },
-    "./virtual_servers/*": "./dist/esm/virtual_servers/*",
+    "./inline": {
+      "types": "./dist/esm/perspective.browser.d.ts",
+      "import": "./dist/esm/perspective.inline.js",
+      "default": "./dist/esm/perspective.inline.js"
+    },
+    "./virtual_servers/*": {
+      "types": "./dist/esm/virtual_servers/*.d.ts",
+      "import": "./dist/esm/virtual_servers/*.js",
+      "default": "./dist/esm/virtual_servers/*.js"
+    },
     "./dist/*": "./dist/*",
     "./src/*": "./src/*",
     "./test/*": "./test/*",

package/src/rust/client.rs

@@ -481,6 +481,34 @@ impl Client {
         Ok(Table(self.client.open_table(entity_id).await?))
     }
 
+    /// Unsafely gets a [`View`] by raw ID, useful for JavaScript multi-threaded
+    /// (via Web Worker) context where a standard `View` cannot otherwise be
+    /// shared because its wrapper is not serializable.
+    ///
+    /// # Safety
+    ///
+    /// This method is unsafe because the lifetime of a [`View`] is bound to
+    /// the [`Client`] which created it.
+    ///
+    /// The caller must guarantee that `entity_id` corresponds to a live
+    /// [`crate::View`] on the connected server (obtained from another
+    /// [`Client`]'s [`crate::View::get_name`] and forwarded across the
+    /// serialization boundary).
+    ///
+    /// # JavaScript Examples
+    ///
+    /// ```javascript
+    /// const view = client.__unsafe_open_view(name_from_main_thread);
+    /// const cols = await view.to_columns();
+    /// ```
+    #[wasm_bindgen]
+    pub fn __unsafe_open_view(&self, entity_id: String) -> crate::view::View {
+        crate::view::View(perspective_client::View::new(
+            entity_id,
+            self.client.clone(),
+        ))
+    }
+
     /// Retrieves the names of all tables that this client has access to.
     ///
     /// `name` is a string identifier unique to the [`Table`] (per [`Client`]),

package/src/rust/lib.rs

@@ -29,6 +29,7 @@ mod client;
 mod generic_sql_model;
 mod table;
 mod table_data;
+mod typed_array;
 pub mod utils;
 mod view;
 mod virtual_server;
@@ -40,6 +41,7 @@ pub use crate::client::Client;
 pub use crate::generic_sql_model::*;
 pub use crate::table::*;
 pub use crate::table_data::*;
+pub use crate::typed_array::*;
 pub use crate::virtual_server::*;
 
 #[cfg(feature = "export-init")]
@@ -61,10 +63,12 @@ export type * from "../../src/ts/ts-rs/Filter.d.ts";
 export type * from "../../src/ts/ts-rs/ViewConfig.d.ts";
 export type * from "../../src/ts/ts-rs/JoinOptions.ts";
 export type * from "../../src/ts/ts-rs/JoinType.ts";
+export type * from "../../src/ts/ts-rs/TypedArrayWindow.ts";
 
 import type {ColumnWindow} from "../../src/ts/ts-rs/ColumnWindow.d.ts";
 import type {ColumnType} from "../../src/ts/ts-rs/ColumnType.d.ts";
 import type {ViewWindow} from "../../src/ts/ts-rs/ViewWindow.d.ts";
+import type {TypedArrayWindow} from "../../src/ts/ts-rs/TypedArrayWindow.ts";
 import type {TableInitOptions} from "../../src/ts/ts-rs/TableInitOptions.d.ts";
 import type {JoinOptions} from "../../src/ts/ts-rs/JoinOptions.ts";
 import type {JoinType} from "../../src/ts/ts-rs/JoinType.ts";

package/src/rust/typed_array.rs

@@ -0,0 +1,243 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+use std::io::Cursor;
+
+use arrow_array::Array as _;
+use arrow_array::cast::AsArray;
+use arrow_array::types::*;
+use arrow_ipc::reader::StreamReader;
+use arrow_schema::{DataType, TimeUnit};
+use js_sys::{Array, Function, JsString, Uint8Array};
+use perspective_client::ViewWindow;
+use ts_rs::TS;
+use wasm_bindgen::JsCast;
+use wasm_bindgen::prelude::*;
+
+#[wasm_bindgen]
+unsafe extern "C" {
+    #[wasm_bindgen(typescript_type = "TypedArrayWindow")]
+    #[derive(Clone)]
+    pub type JsTypedArrayWindow;
+}
+
+/// Options for `with_typed_arrays`, extending `ViewWindow` with
+/// typed-array-specific options.
+#[derive(Default, serde::Deserialize, TS)]
+pub struct TypedArrayWindow {
+    #[serde(flatten)]
+    pub view_window: ViewWindow,
+
+    /// When `true`, Float64/Date32/Timestamp columns are output as
+    /// `Float32Array` instead of `Float64Array`.
+    #[serde(default)]
+    pub float32: bool,
+}
+
+impl From<TypedArrayWindow> for ViewWindow {
+    fn from(w: TypedArrayWindow) -> Self {
+        w.view_window
+    }
+}
+
+/// Decode an Arrow IPC batch and call `callback` once with all columns.
+///
+/// Callback signature:
+/// ```js
+/// callback(names: string[], values: TypedArray[], validities: (Uint8Array|null)[], dictionaries: (string[]|null)[]) => void | Promise<void>
+/// ```
+///
+/// If the callback returns a `Promise`, it is awaited before the Arrow
+/// batch (and therefore the zero-copy typed-array views into it) is
+/// dropped. A synchronous callback returning `undefined` is supported
+/// with no promise-handling overhead.
+pub(crate) async fn decode_and_call(
+    arrow: &[u8],
+    float32: bool,
+    callback: &Function,
+) -> Result<(), JsValue> {
+    let cursor = Cursor::new(arrow);
+    let reader = StreamReader::try_new(cursor, None)
+        .map_err(|e| JsValue::from_str(&format!("Arrow decode error: {e}")))?;
+
+    let batch = reader
+        .into_iter()
+        .next()
+        .ok_or_else(|| JsValue::from_str("Arrow IPC contained no record batches"))?
+        .map_err(|e| JsValue::from_str(&format!("Arrow batch error: {e}")))?;
+
+    let schema = batch.schema();
+    let num_cols = batch.num_columns();
+
+    let js_names = Array::new_with_length(num_cols as u32);
+    let js_values = Array::new_with_length(num_cols as u32);
+    let js_validities = Array::new_with_length(num_cols as u32);
+    let js_dicts = Array::new_with_length(num_cols as u32);
+
+    // Storage for allocated conversion buffers. These MUST outlive the
+    // callback because `js_sys::*Array::view()` creates zero-copy views
+    // into their heap memory. Using `Box<[T]>` (rather than `Vec<T>`)
+    // yields a stable pointer that won't move when the outer Vec grows.
+    let mut f32_storage: Vec<Box<[f32]>> = Vec::new();
+    let mut f64_storage: Vec<Box<[f64]>> = Vec::new();
+
+    for col_idx in 0..num_cols {
+        let field = schema.field(col_idx);
+        let col = batch.column(col_idx);
+        let validity = col.nulls().map(|nulls| nulls.validity());
+
+        js_names.set(col_idx as u32, JsString::from(field.name().as_str()).into());
+
+        match col.data_type() {
+            DataType::UInt32 => {
+                let vals = col.as_primitive::<UInt32Type>().values();
+                let arr = unsafe { js_sys::Uint32Array::view(vals.as_ref()) };
+                js_values.set(col_idx as u32, arr.into());
+                js_dicts.set(col_idx as u32, JsValue::NULL);
+            },
+            DataType::Int32 => {
+                let vals = col.as_primitive::<Int32Type>().values();
+                let arr = unsafe { js_sys::Int32Array::view(vals.as_ref()) };
+                js_values.set(col_idx as u32, arr.into());
+                js_dicts.set(col_idx as u32, JsValue::NULL);
+            },
+            DataType::Float32 => {
+                let vals = col.as_primitive::<Float32Type>().values();
+                let arr = unsafe { js_sys::Float32Array::view(vals.as_ref()) };
+                js_values.set(col_idx as u32, arr.into());
+                js_dicts.set(col_idx as u32, JsValue::NULL);
+            },
+            DataType::Float64 => {
+                if float32 {
+                    let vals = col.as_primitive::<Float64Type>().values();
+                    f32_storage.push(vals.iter().map(|&v| v as f32).collect());
+                } else {
+                    let vals = col.as_primitive::<Float64Type>().values();
+                    let arr = unsafe { js_sys::Float64Array::view(vals.as_ref()) };
+                    js_values.set(col_idx as u32, arr.into());
+                }
+                js_dicts.set(col_idx as u32, JsValue::NULL);
+            },
+            DataType::Date32 => {
+                // Datetime values are always emitted as Float64 — narrowing
+                // epoch-ms to f32 collapses ~256 ms of resolution at modern
+                // timestamps, so the `float32` flag is intentionally ignored
+                // for date/timestamp columns.
+                let typed = col.as_primitive::<Date32Type>();
+                f64_storage.push(
+                    typed
+                        .values()
+                        .iter()
+                        .map(|&v| v as f64 * 86_400_000.0)
+                        .collect(),
+                );
+                js_dicts.set(col_idx as u32, JsValue::NULL);
+            },
+            DataType::Timestamp(TimeUnit::Millisecond, _) => {
+                let typed = col.as_primitive::<TimestampMillisecondType>();
+                f64_storage.push(typed.values().iter().map(|&v| v as f64).collect());
+                js_dicts.set(col_idx as u32, JsValue::NULL);
+            },
+            DataType::Int64 => {
+                let typed = col.as_primitive::<Int64Type>();
+                if float32 {
+                    f32_storage.push(typed.values().iter().map(|&v| v as f32).collect());
+                } else {
+                    f64_storage.push(typed.values().iter().map(|&v| v as f64).collect());
+                }
+                js_dicts.set(col_idx as u32, JsValue::NULL);
+            },
+            DataType::Dictionary(..) => {
+                let dict = col.as_dictionary::<Int32Type>();
+                let keys = dict.keys();
+                let arr = unsafe { js_sys::Int32Array::view(keys.values().as_ref()) };
+                js_values.set(col_idx as u32, arr.into());
+
+                let values = dict.values().as_string::<i32>();
+                let js_dict = Array::new_with_length(values.len() as u32);
+                for i in 0..values.len() {
+                    js_dict.set(i as u32, JsValue::from_str(values.value(i)));
+                }
+                js_dicts.set(col_idx as u32, js_dict.into());
+            },
+            dt => {
+                return Err(JsValue::from_str(&format!(
+                    "Unsupported column type for typed array: {dt}"
+                )));
+            },
+        }
+
+        // SAFETY: Validity bitmap is owned by `batch` which outlives the
+        // callback — safe to view zero-copy.
+        let js_validity = validity.map(|v| unsafe { Uint8Array::view(v) });
+        js_validities.set(
+            col_idx as u32,
+            js_validity
+                .as_ref()
+                .map(JsValue::from)
+                .unwrap_or(JsValue::NULL),
+        );
+    }
+
+    // Second pass: fill in value views for columns backed by f32_storage /
+    // f64_storage. The Box<[T]> buffers are heap-allocated and stable; their
+    // data pointers remain valid even as the outer Vec grows.
+    let mut f32_idx = 0;
+    let mut f64_idx = 0;
+    for col_idx in 0..num_cols {
+        let col = batch.column(col_idx);
+        let uses_f32_storage = matches!(
+            (col.data_type(), float32),
+            (DataType::Float64, true) | (DataType::Int64, true),
+        );
+        let uses_f64_storage = matches!(
+            (col.data_type(), float32),
+            (DataType::Date32, _)
+                | (DataType::Timestamp(TimeUnit::Millisecond, _), _)
+                | (DataType::Int64, false),
+        );
+
+        if uses_f32_storage {
+            let arr = unsafe { js_sys::Float32Array::view(&f32_storage[f32_idx]) };
+            js_values.set(col_idx as u32, arr.into());
+            f32_idx += 1;
+        } else if uses_f64_storage {
+            let arr = unsafe { js_sys::Float64Array::view(&f64_storage[f64_idx]) };
+            js_values.set(col_idx as u32, arr.into());
+            f64_idx += 1;
+        }
+    }
+
+    let ret = callback.call4(
+        &JsValue::UNDEFINED,
+        &js_names.into(),
+        &js_values.into(),
+        &js_validities.into(),
+        &js_dicts.into(),
+    )?;
+
+    // If the callback returned a Promise, await it before releasing the
+    // batch — zero-copy TypedArray views into `batch`/`f32_storage`/
+    // `f64_storage` must remain valid for the full lifetime of the
+    // awaited work.
+    if ret.is_instance_of::<js_sys::Promise>() {
+        let promise: js_sys::Promise = ret.unchecked_into();
+        wasm_bindgen_futures::JsFuture::from(promise).await?;
+    }
+
+    // Keep storage alive until after the callback (and its awaited
+    // promise, if any) returns.
+    drop(f32_storage);
+    drop(f64_storage);
+
+    Ok(())
+}

package/src/rust/view.rs

@@ -88,6 +88,12 @@ impl View {
         self.clone()
     }
 
+    #[wasm_bindgen]
+    #[doc(hidden)]
+    pub fn __unsafe_get_name(&self) -> String {
+        self.0.name.clone()
+    }
+
     /// Returns an array of strings containing the column paths of the [`View`]
     /// without any of the source columns.
     ///
@@ -247,6 +253,38 @@ impl View {
         Ok(self.0.to_csv(window.unwrap_or_default()).await?)
     }
 
+    /// Fetches columns from the [`View`] in Arrow format, decodes them, and
+    /// passes typed array views to `callback`. All arrays are only valid for
+    /// the duration of the callback — if `callback` returns a `Promise`, it
+    /// is awaited before the backing Arrow buffer is released, so async
+    /// callbacks may use the views for the full duration of the awaited
+    /// work (e.g. across an `await requestAnimationFrame`-backed promise).
+    ///
+    /// # Arguments
+    ///
+    /// - `window` - Optional [`TypedArrayWindow`] controlling row/column
+    ///   windowing and output options (e.g., `float32` mode).
+    /// - `callback` - A JS function called with `(names: string[], values:
+    ///   TypedArray[], validities: (Uint8Array|null)[], dictionaries:
+    ///   (string[]|null)[]) => void | Promise<void>`.
+    #[wasm_bindgen]
+    pub async fn with_typed_arrays(
+        &self,
+        window: Option<crate::typed_array::JsTypedArrayWindow>,
+        callback: Function,
+    ) -> ApiResult<()> {
+        let opts: crate::typed_array::TypedArrayWindow = window
+            .into_serde_ext::<Option<crate::typed_array::TypedArrayWindow>>()?
+            .unwrap_or_default();
+
+        let float32 = opts.float32;
+        let mut view_window: ViewWindow = opts.into();
+        view_window.emit_legacy_row_path_names = Some(false);
+        let arrow = self.0.to_arrow(view_window).await?;
+        crate::typed_array::decode_and_call(&arrow, float32, &callback).await?;
+        Ok(())
+    }
+
     /// Register a callback with this [`View`]. Whenever the view's underlying
     /// table emits an update, this callback will be invoked with an object
     /// containing `port_id`, indicating which port the update fired on, and

package/src/rust/virtual_server.rs

@@ -372,7 +372,7 @@ impl VirtualServerHandler for JsServerHandler {
 
         let handler = self.0.clone();
         let view_id = view_id.to_string();
-        let config_value = serde_wasm_bindgen::to_value(config).unwrap();
+        let config_value = JsValue::from_serde_ext(config).unwrap();
         let config = config.clone();
         Box::pin(async move {
             let this = JsServerHandler(handler);
@@ -493,7 +493,7 @@ impl VirtualServerHandler for JsServerHandler {
         let handler = self.0.clone();
         let view_id = view_id.to_string();
         let column_name = column_name.to_string();
-        let config_js = serde_wasm_bindgen::to_value(config).unwrap();
+        let config_js = JsValue::from_serde_ext(config).unwrap();
         Box::pin(async move {
             let this = JsServerHandler(handler);
             let args = Array::new();
@@ -518,8 +518,8 @@ impl VirtualServerHandler for JsServerHandler {
         let handler = self.0.clone();
         let view_id = view_id.to_string();
         let window: JsViewPort = viewport.clone().into();
-        let config_value = serde_wasm_bindgen::to_value(config).unwrap();
-        let window_value = serde_wasm_bindgen::to_value(&window).unwrap();
+        let config_value = JsValue::from_serde_ext(config).unwrap();
+        let window_value = JsValue::from_serde_ext(&window).unwrap();
         let schema_value = JsValue::from_serde_ext(&schema).unwrap();
 
         Box::pin(async move {

package/src/ts/perspective.browser.ts

@@ -65,13 +65,32 @@ export function init_server(
 }
 
 let GLOBAL_CLIENT_WASM: Promise<typeof psp>;
+let GLOBAL_CLIENT_MODULE: Promise<WebAssembly.Module> | undefined;
+
+async function compile_module(wasm: any): Promise<WebAssembly.Module> {
+    if (wasm instanceof WebAssembly.Module) {
+        return wasm;
+    }
+
+    if (typeof Response !== "undefined" && wasm instanceof Response) {
+        return WebAssembly.compileStreaming(wasm);
+    }
+
+    return WebAssembly.compile(wasm);
+}
 
 async function compilerize(
     wasm: PerspectiveWasm,
     disable_stage_0: boolean = false,
 ) {
     const wasm_buff = disable_stage_0 ? wasm : await load_wasm_stage_0(wasm);
-    await wasm_module.default({ module_or_path: wasm_buff });
+    // Compile to a `WebAssembly.Module` once so it can be both instantiated
+    // locally and forwarded to other workers via `getCompiledClientWasm()`.
+    // `WebAssembly.Module` is structured-cloneable across workers, so the
+    // recipient can instantiate without re-fetching or re-compiling.
+    const compiled = await compile_module(wasm_buff);
+    GLOBAL_CLIENT_MODULE = Promise.resolve(compiled);
+    await wasm_module.default({ module_or_path: compiled });
     await wasm_module.init();
     return wasm_module;
 }
@@ -103,6 +122,14 @@ function get_client() {
     const viewer_class: any = customElements.get("perspective-viewer");
     if (viewer_class) {
         GLOBAL_CLIENT_WASM = Promise.resolve(viewer_class.__wasm_module__);
+        if (
+            GLOBAL_CLIENT_MODULE === undefined &&
+            viewer_class.__wasm_client_module__
+        ) {
+            GLOBAL_CLIENT_MODULE = Promise.resolve(
+                viewer_class.__wasm_client_module__,
+            );
+        }
     } else if (GLOBAL_CLIENT_WASM === undefined) {
         throw new Error("Missing perspective-client.wasm");
     }
@@ -110,6 +137,43 @@ function get_client() {
     return GLOBAL_CLIENT_WASM;
 }
 
+/**
+ * Returns the compiled `WebAssembly.Module` for the perspective-js client
+ * runtime. The module is structured-cloneable, so it can be sent via
+ * `postMessage` to a Worker which can instantiate its own `Client` without
+ * re-fetching or re-compiling the wasm binary.
+ *
+ * Requires that the client wasm has been initialized — typically by a prior
+ * call to `init_client(...)`, or implicitly by mounting a `<perspective-viewer>`
+ * element. Throws otherwise.
+ *
+ * # Examples
+ *
+ * ```javascript
+ * const mod = await perspective.getCompiledClientWasm();
+ * worker.postMessage({ kind: "init", clientWasm: mod }, [port]);
+ * ```
+ */
+export async function getCompiledClientWasm(): Promise<WebAssembly.Module> {
+    if (GLOBAL_CLIENT_MODULE !== undefined) {
+        return GLOBAL_CLIENT_MODULE;
+    }
+
+    const viewer_class: any = customElements.get("perspective-viewer");
+    if (viewer_class?.__wasm_client_module__) {
+        GLOBAL_CLIENT_MODULE = Promise.resolve(
+            viewer_class.__wasm_client_module__,
+        );
+        return GLOBAL_CLIENT_MODULE;
+    }
+
+    throw new Error(
+        "perspective-js client wasm has not been compiled yet — call " +
+            "`init_client(...)` or `perspective.worker()` before " +
+            "`getCompiledClientWasm()`.",
+    );
+}
+
 function get_server() {
     if (GLOBAL_SERVER_WASM === undefined) {
         throw new Error("Missing perspective-server.wasm");
@@ -122,13 +186,30 @@ function get_server() {
 
 let GLOBAL_WORKER: undefined | (() => Promise<Worker>) = undefined;
 
-// Inline the worker for now. This code will eventually allow outlining this resource
-// @ts-ignore
-import perspective_wasm_worker from "../../src/ts/perspective-server.worker.js";
-
-function get_worker(): Promise<Worker> {
+// `WorkerPlugin` resolves this import to a stub that exports
+// `getPerspectiveWorkerURL(): Promise<string>`. The URL is either a
+// Blob URL (inline mode — production builds) or a real file path
+// resolved against `import.meta.url` (file mode — debug builds).
+// Constructing the `Worker` lives here in the consumer rather than
+// inside the plugin so the same module text can also be loaded
+// in-process via dynamic `import(url)` when a future caller wants
+// it; the plugin no longer owns Worker lifecycle.
+//
+// `initialize()` constructs `new Worker(blobUrl)` and falls back to
+// running the worker source on the main thread via `new Function(...)`
+// when Worker construction is unavailable (e.g. `file://` origins where
+// module-Worker support is gated). The shim it returns is
+// MessagePort-shaped so downstream code can treat it like a real
+// Worker.
+// @ts-ignore — resolved at build time by `@perspective-dev/esbuild-plugin/worker`
+import { initialize as initializePerspectiveWorker } from "../../src/ts/perspective-server.worker.js";
+
+async function get_worker(): Promise<Worker> {
     if (GLOBAL_WORKER === undefined) {
-        return perspective_wasm_worker();
+        return await initializePerspectiveWorker({
+            type: "module",
+            name: "perspective-server",
+        });
     }
 
     return GLOBAL_WORKER();
@@ -154,6 +235,7 @@ export default {
     init_client,
     init_server,
     createMessageHandler,
+    getCompiledClientWasm,
     GenericSQLVirtualServerModel,
     VirtualDataSlice,
     VirtualServer,

package/src/ts/perspective.node.ts

@@ -108,6 +108,7 @@ const CONTENT_TYPES: Record<string, string> = {
     ".arrow": "arraybuffer",
     ".feather": "arraybuffer",
     ".wasm": "application/wasm",
+    ".svg": "image/svg+xml",
 };
 
 /**
@@ -120,7 +121,7 @@ export async function cwd_static_file_handler(
     request: http.IncomingMessage,
     response: http.ServerResponse<http.IncomingMessage>,
     assets = ["./"],
-    { debug = true } = {},
+    { debug = false } = {},
 ) {
     let url =
         request.url
@@ -142,14 +143,16 @@ export async function cwd_static_file_handler(
                     if (debug) {
                         console.log(`200 ${url}`);
                     }
+
                     response.writeHead(200, {
                         "Content-Type": contentType,
                         "Access-Control-Allow-Origin": "*",
                     });
+
                     if (extname === ".arrow" || extname === ".feather") {
-                        response.end(content, "utf-8");
+                        response.end(content, "utf8");
                     } else {
-                        response.end(content);
+                        response.end(content, "utf8");
                     }
 
                     return;
@@ -192,6 +195,18 @@ function buffer_to_arraybuffer(
     }
 }
 
+/**
+ * A simple Node `http`-based WebSocket adapter that exposes a
+ * `PerspectiveServer` over the wire.
+ *
+ * @remarks
+ *
+ * **Security.** `WebSocketServer` is a reference integration with no
+ * authentication, authorization, origin enforcement, or rate limiting, and
+ * is not safe to expose to untrusted networks — see
+ * [`SECURITY.md`](https://github.com/perspective-dev/perspective/blob/master/SECURITY.md)
+ * for the full threat model.
+ */
 export class WebSocketServer {
     _server: http.Server | any; // stoppable has no type ...
     _wss: HttpWebSocketServer;

package/src/ts/ts-rs/TypedArrayWindow.ts

@@ -0,0 +1,26 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * Options for `with_typed_arrays`, extending `ViewWindow` with
+ * typed-array-specific options.
+ */
+export type TypedArrayWindow = { 
+/**
+ * When `true`, Float64/Date32/Timestamp columns are output as
+ * `Float32Array` instead of `Float64Array`.
+ */
+float32: boolean, start_row?: number, start_col?: number, end_row?: number, end_col?: number, id?: boolean, index?: boolean, 
+/**
+ * Only impacts [`View::to_csv`]
+ */
+formatted?: boolean, 
+/**
+ * Only impacts [`View::to_arrow`]
+ */
+compression?: string, 
+/**
+ * When `true`, group-by columns use legacy `"colname (Group by N)"`
+ * naming. When `false`, they use `__ROW_PATH_N__` naming consistent
+ * with the SQL backend. Defaults to `true` for backwards compatibility.
+ */
+emit_legacy_row_path_names?: boolean, };

package/src/ts/ts-rs/ViewWindow.ts

@@ -14,4 +14,10 @@ formatted?: boolean,
 /**
  * Only impacts [`View::to_arrow`]
  */
-compression?: string, };
+compression?: string, 
+/**
+ * When `true`, group-by columns use legacy `"colname (Group by N)"`
+ * naming. When `false`, they use `__ROW_PATH_N__` naming consistent
+ * with the SQL backend. Defaults to `true` for backwards compatibility.
+ */
+emit_legacy_row_path_names?: boolean, };