Fix/socketio parser max attachments

.gitignore

@@ -130,3 +130,6 @@ test/assets/testing-*.db
 test/assets/1brc/1brc_*.csv
 test/assets/1brc/1brc_*.sql
 reports/test-report.html
+
+# local tarball for examples (npm pack)
+sqlitecloud-drivers.tgz

examples/with-websocket-browser/.env.example

@@ -0,0 +1,4 @@
+# Optional: prefill the connection string field on load.
+# Anything exposed via VITE_* is bundled into the client, so only use this for
+# local development / demo databases — never ship a production secret this way.
+VITE_DATABASE_URL=sqlitecloud://host.sqlite.cloud:8860/chinook.sqlite?apikey=YOUR_KEY

examples/with-websocket-browser/.gitignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+.env

examples/with-websocket-browser/README.md

@@ -0,0 +1,84 @@
+# SQLite Cloud — WebSocket browser example
+
+A minimal [Vite](https://vitejs.dev/) + TypeScript app that uses
+[`@sqlitecloud/drivers`](https://www.npmjs.com/package/@sqlitecloud/drivers)
+to query SQLite Cloud **over WebSocket** from the browser.
+
+This example consumes the driver from a locally packed tarball
+(`file:../../sqlitecloud-drivers.tgz`) so you can test changes in this repo
+before publishing — see [Using a local build of the driver](#using-a-local-build-of-the-driver).
+
+In the browser the driver cannot open a raw TLS socket, so it automatically
+connects through the **SQLite Cloud Gateway** using `socket.io` (WebSocket).
+This example also passes `usewebsocket: true` explicitly so the same
+`runQuery` helper works under Node.js too.
+
+## Files
+
+- [`src/query.ts`](src/query.ts) — opens a WebSocket connection,
+  runs one SQL statement and normalizes the result into `{ rows }`.
+- [`src/main.ts`](src/main.ts) — wires the form in `index.html` to `runQuery`.
+- [`index.html`](index.html) — small UI to enter a connection string + SQL.
+
+## Run it
+
+```bash
+npm install        # installs deps, incl. the locally packed @sqlitecloud/drivers tarball
+npm run dev        # starts Vite on http://localhost:5173
+```
+
+Open the page, paste your SQLite Cloud connection string, e.g.
+
+```
+sqlitecloud://host.sqlite.cloud:8860/chinook.sqlite?apikey=YOUR_KEY
+```
+
+and click **Run query**.
+
+Optionally copy `.env.example` to `.env` and set `VITE_DATABASE_URL` to prefill
+the connection string field. Note that any `VITE_*` value is bundled into the
+client, so only use it for local/demo databases — never a production secret.
+
+## Pointing at a specific gateway
+
+By default the gateway URL is derived from the host (`wss://<host>:443`). To
+target a different gateway, add `gatewayurl` to the config in
+[`src/main.ts`](src/main.ts):
+
+```ts
+{ connectionstring, gatewayurl: 'wss://my-gateway.example.com:443' }
+```
+
+## Using a local build of the driver
+
+This example does not depend on the published npm package. Instead it installs
+`@sqlitecloud/drivers` from a tarball built from this repo, pinned in
+`package.json` as:
+
+```json
+"@sqlitecloud/drivers": "file:../../sqlitecloud-drivers.tgz"
+```
+
+To rebuild that tarball from your current source and reinstall it, run:
+
+```bash
+npm run sync-driver
+```
+
+This script:
+
+1. builds the driver in the repo root (`npm run build`);
+2. runs `npm pack` to produce `sqlitecloud-drivers.tgz` — the exact tarball that
+   would be published to npm (same file set, same `package.json` exports);
+3. clears `node_modules/@sqlitecloud`, the Vite cache, and the lockfile;
+4. reinstalls from the fresh tarball.
+
+Because it consumes the packed tarball rather than a symlinked workspace,
+`sync-driver` faithfully simulates a real `npm install @sqlitecloud/drivers` —
+so you can validate local driver changes against this example before publishing.
+Re-run it whenever you change the driver source.
+
+> `sync-driver` clears `node_modules/.vite`, so a plain `npm run dev` picks up the
+> new build. If you ever rebuild the tarball without `sync-driver`, start Vite with
+> `npm run dev -- --force` to bust its stale dependency cache (the `file:` version
+> never changes, so Vite can't detect the new contents on its own).

examples/with-websocket-browser/index.html

@@ -0,0 +1,77 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>SQLite Cloud — WebSocket browser example</title>
+    <style>
+      body {
+        font-family: system-ui, sans-serif;
+        max-width: 720px;
+        margin: 2rem auto;
+        padding: 0 1rem;
+      }
+      label {
+        display: block;
+        font-size: 0.85rem;
+        font-weight: 600;
+        margin: 0.75rem 0 0.25rem;
+      }
+      input[type='text'],
+      textarea {
+        width: 100%;
+        padding: 0.5rem;
+        font: inherit;
+        box-sizing: border-box;
+      }
+      textarea {
+        min-height: 5rem;
+        font-family: ui-monospace, monospace;
+      }
+      .row {
+        display: flex;
+        align-items: center;
+        gap: 0.5rem;
+        margin-top: 0.75rem;
+      }
+      button {
+        margin-top: 1rem;
+        padding: 0.5rem 1rem;
+        font: inherit;
+        cursor: pointer;
+      }
+      pre {
+        background: #f4f4f5;
+        padding: 1rem;
+        border-radius: 6px;
+        overflow: auto;
+        white-space: pre-wrap;
+      }
+    </style>
+  </head>
+  <body>
+    <h1>SQLite Cloud — WebSocket browser example</h1>
+    <p>
+      Installs <code>@sqlitecloud/drivers</code> from npm and queries SQLite Cloud over WebSocket (through the SQLite Cloud Gateway) using a
+      <code>runQuery</code> helper.
+    </p>
+
+    <label for="connectionString">Connection string</label>
+    <input id="connectionString" type="text" placeholder="sqlitecloud://host.sqlite.cloud:8860/chinook.sqlite?apikey=YOUR_KEY" />
+
+    <label for="sql">SQL</label>
+    <textarea id="sql">USE DATABASE chinook.sqlite; SELECT * FROM albums LIMIT 5;</textarea>
+
+    <div class="row">
+      <input id="arrayMode" type="checkbox" />
+      <label for="arrayMode" style="margin: 0">array mode (rows as arrays via row.getData())</label>
+    </div>
+
+    <button id="run">Run query</button>
+
+    <h2>Result</h2>
+    <pre id="output">—</pre>
+
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>