fix(examples): use jsDelivr and typed pipeline records

Author: vados-cosmonic

examples/components/script-only-pipeline/README.md

@@ -28,7 +28,7 @@ Use Node.js 24 or newer. This example uses the workspace version of Jco, which i
 `pnpm run all` follows the other examples: generate types, check TypeScript, build the components,
 transpile the engine and dataset initializer, run the Node.js demo, and run Node.js and Puppeteer tests.
 The QuickJS engine uses a synchronous ABI and stubbed WASI because these processors only operate on
-in-memory JSON. Neither host needs JSPI flags, filesystem access from the guest, or WASI shims.
+in-memory records. Neither host needs JSPI flags, filesystem access from the guest, or WASI shims.
 
 ## Try the browser demo
 
@@ -42,6 +42,10 @@ Open `http://localhost:5173/demo/` after `pnpm run demo`, or use `pnpm run demo:
 5. Set the risk step's options to `{"minScore":70}` and rerun. Three logs remain, with scores 70, 70, and 90.
 6. Move the page counter to the beginning. Its report now counts all 12 input logs, before filtering.
 
+Choose **Use one sample log** to call `process-single` with one `access-log` record. You can also paste
+a JSON object into the input; arrays call `process-batch` with `list<access-log>`. A single-record filter
+can return no record, which stops subsequent steps. **Restore sample** switches back to the full batch.
+
 The JSON input is editable. Every run starts from that input, so a previous run's filters, scores, and
 reports never leak into the next run. **Restore sample** resets the input; **Clear pipeline** removes
 the steps. Invalid uploads or options show an error on the page and can be corrected without a reload.
@@ -71,8 +75,10 @@ It reads that Wasm back through the same loader as an upload and validates `desc
 the step. Code runs inside the shared QuickJS engine. The JavaScript engine is reused as you build
 and load new components.
 
-The editor and compiler load from versioned CDN URLs, so browser authoring needs internet access.
-Your source stays in the browser; no compilation requests are sent to a server. If the editor CDN is
+The editor and compiler load from versioned [jsDelivr](https://www.jsdelivr.com/) CDN URLs, so browser
+authoring needs internet access. An import map pins CodeMirror's shared dependencies to one version
+each so its extension identity checks work. Your source stays in the browser; no compilation requests
+are sent to a server. If the editor CDN is
 unavailable, the page keeps a plain source text area. Build errors appear beside the editor and leave
 the pipeline intact. Browser builds validate syntax and exports; full TypeScript checking for the
 checked-in components and editor template is provided by `pnpm run check`.
@@ -118,18 +124,29 @@ export is checked against its generated interface, for example:
 
 ```ts
 import type { processor as ProcessorInterface } from 'example:log-pipeline/pipeline';
+import { getDataset } from '../shared/state.ts';
 
 export const processor: typeof ProcessorInterface = {
     describe() {
-        /* name, description, defaultOptions */
+        return { name: 'My processor', description: 'Process access logs.', defaultOptions: '{}' };
+    },
+    processBatch(logs, options) {
+        const data = getDataset();
+        data.logs = logs;
+        /* parse options and update shared data */
+        return { logs: data.logs, summary: `Processed ${logs.length} logs` };
     },
-    process(options) {
-        /* update shared data and return a summary */
+    processSingle(log, options) {
+        const { logs, summary } = processor.processBatch([log], options);
+        return { log: logs[0], summary };
     },
 };
 ```
 
-The generated `AccessLog` type also describes the shared records. These declarations are checked in
+The shared WIT `types` interface defines `access-log`. The dataset and processor interfaces both use
+it: `reset` accepts a list, `snapshot` returns typed logs, `process-batch` accepts and returns a list,
+and `process-single` accepts one record and returns an optional record. The generated `AccessLog`
+TypeScript type also describes the shared records. These declarations are checked in
 for editor support and regenerated by `build`; Jco bundles TypeScript directly, so there is no separate
 JavaScript compilation step.
 
@@ -172,12 +189,20 @@ The shared [`createPipeline`](./demo/shared/pipeline.js) runner instantiates the
 platform adapter is a function that reads bytes from a URL: Node.js supplies `readFile`, and the browser
 supplies `fetch`. Both entry points use the same script reader and execution code.
 
-For each run, the runner loads the dataset script and calls `dataset.reset(input)`. For each step, it
-loads that step's source with `scriptLoader.load`, calls `processor.process(options)`, then reloads the
-dataset script to read a snapshot. Loading scripts replaces the active exports, but retains the
-engine's JavaScript realm. The working dataset lives on that realm's `globalThis`, shared through
-[`components/shared/state.ts`](./components/shared/state.ts); it is not passed back and forth between
-processors as JSON. Only input, options, summaries, and output snapshots cross the host boundary.
+For each run, the host parses the JSON input into records. The runner loads the dataset script and
+calls `dataset.reset(logs)`. `runBatch(logs, stages)` calls each processor's `processBatch(logs, options)`
+and passes its returned records to the next step. `runSingle(log, stages)` instead calls
+`processSingle(log, options)` and stops if a filter returns no record. The checked-in single-record
+implementations reuse the batch algorithm with a one-element list. Batch statistics, such as repeated
+IP counts, therefore apply only to the records in that call.
+
+Logs cross the WIT boundary as records, including optional country and risk-score annotations.
+Options and extensible reports remain JSON strings; log records are never encoded as JSON inside the
+engine. After each step, the runner reloads the dataset script to read a typed snapshot. Loading
+scripts replaces the active exports, but retains the engine's JavaScript realm. The dataset and
+reports live on that realm's `globalThis`, shared through
+[`components/shared/state.ts`](./components/shared/state.ts). Reports survive switching processors
+and reset at the beginning of each run. Both hosts format the final records as JSON for display.
 
 > [!NOTE]
 > Scripts in one engine share a realm and can access each other's data. Use trusted scripts together;
@@ -202,15 +227,19 @@ Choose the Node.js stages and their execution order with positional arguments or
 pnpm run run top-pages geoip
 PIPELINE_STAGES=geoip,top-pages pnpm run run
 PIPELINE_STAGES= pnpm run run
+pnpm run run --single risk-score top-pages
 ```
 
 Arguments take precedence over the environment variable. With neither specified, the demo runs
 `geoip`, `risk-score`, then `top-pages`. An empty environment value runs an empty pipeline. Stage names
 are the filenames in `dist/components/` without `.wasm`; unknown names report the available stages and
 exit with a nonzero status. Each selected stage uses its own default options.
+`--single` processes the first sample record through `process-single`; the default processes the
+whole sample array through `process-batch`.
 
-The entry point exports an async `main()` and calls it only when executed directly, so importing
-`demo/node.mjs` does not run the demo.
+The entry point exports an async `main({ stageNames, mode })` and calls it only when executed directly,
+so importing `demo/node.mjs` does not run the demo. CLI and environment parsing happen in the
+direct-execution block at the bottom; `main` receives named options.
 
 ### Add a processor
 
@@ -227,8 +256,9 @@ pnpm run test:node
 pnpm run test:browser
 ```
 
-The tests exercise the built Wasm components, shared data across script loads, ordering and options,
-repeat runs, empty input, invalid uploads, and recovery from errors. Node.js tests also cover CLI and
+The tests exercise typed batches and single records through the built Wasm components, optional
+filter results, shared data across script loads, ordering and options, repeat runs, empty input,
+invalid uploads, and recovery from errors. Node.js tests also cover CLI and
 environment stage selection, precedence, unknown names, and the direct-execution guard. The Puppeteer
 test uploads actual `.wasm` files, edits the highlighted TypeScript editor, builds custom components,
 loads the downloadable bytes in Node.js, uploads them again, and checks recovery from syntax errors.

examples/components/script-only-pipeline/components/dataset/dataset.ts

@@ -1,28 +1,11 @@
 import type { dataset as DatasetInterface } from 'example:log-pipeline/pipeline';
-import type { AccessLog } from 'example:log-pipeline/dataset';
 import { getDataset, resetDataset } from '../shared/state.ts';
 
 export const dataset: typeof DatasetInterface = {
-    reset(json) {
-        let rows: unknown;
-        try {
-            rows = JSON.parse(json);
-        } catch {
-            throw 'Input must be valid JSON';
-        }
-        if (!Array.isArray(rows)) {
-            throw 'Input must be a JSON array of access logs';
-        }
-        const logs: AccessLog[] = rows.map((row, index) => {
-            if (
-                !row ||
-                typeof row !== 'object' ||
-                !['timestamp', 'ip', 'method', 'path'].every((key) => typeof row[key] === 'string') ||
-                !Number.isInteger(row.status) ||
-                row.status < 100 ||
-                row.status > 599
-            ) {
-                throw `Log ${index + 1} needs timestamp, ip, method, path, and an HTTP status (100–599)`;
+    reset(rows) {
+        const logs = rows.map((row, index) => {
+            if (row.status < 100 || row.status > 599) {
+                throw `Log ${index + 1} needs an HTTP status (100–599)`;
             }
             // Start each run from raw logs; annotations belong to the processors.
             return {
@@ -38,6 +21,7 @@ export const dataset: typeof DatasetInterface = {
         resetDataset(logs);
     },
     snapshot() {
-        return JSON.stringify(getDataset());
+        const { logs, reports } = getDataset();
+        return { logs, reportsJson: JSON.stringify(reports) };
     },
 };

examples/components/script-only-pipeline/components/geoip/geoip.ts

@@ -17,19 +17,24 @@ export const processor: typeof ProcessorInterface = {
             defaultOptions: JSON.stringify({ country: 'DE' }),
         };
     },
-    process(json) {
+    processBatch(logs, json) {
         const { country = 'DE' } = parseOptions(json);
         if (typeof country !== 'string' || !['all', 'US', 'DE', 'JP', 'unknown'].includes(country)) {
             throw 'country must be all, US, DE, JP, or unknown';
         }
         const data = getDataset();
+        data.logs = logs;
         const before = data.logs.length;
         data.logs = data.logs
             .map((log) => ({
                 ...log,
                 country: countries.get(log.ip.split('.').slice(0, 3).join('.')) ?? 'unknown',
             }))
             .filter((log) => country === 'all' || log.country === country);
-        return `GeoIP: ${before} → ${data.logs.length} logs (${country})`;
+        return { logs: data.logs, summary: `GeoIP: ${before} → ${data.logs.length} logs (${country})` };
+    },
+    processSingle(log, options) {
+        const { logs, summary } = processor.processBatch([log], options);
+        return { log: logs[0], summary };
     },
 };

examples/components/script-only-pipeline/components/risk-score/risk-score.ts

@@ -9,12 +9,13 @@ export const processor: typeof ProcessorInterface = {
             defaultOptions: JSON.stringify({ minScore: 0 }),
         };
     },
-    process(json) {
+    processBatch(logs, json) {
         const { minScore = 0 } = parseOptions(json);
         if (typeof minScore !== 'number' || !Number.isInteger(minScore) || minScore < 0 || minScore > 100) {
             throw 'minScore must be an integer from 0 to 100';
         }
         const data = getDataset();
+        data.logs = logs;
         const requests = new Map<string, number>();
         for (const log of data.logs) {
             requests.set(log.ip, (requests.get(log.ip) ?? 0) + 1);
@@ -30,6 +31,10 @@ export const processor: typeof ProcessorInterface = {
                 ),
             }))
             .filter((log) => log.riskScore >= minScore);
-        return `Risk: scored logs and kept ${data.logs.length} with score ≥ ${minScore}`;
+        return { logs: data.logs, summary: `Risk: scored logs and kept ${data.logs.length} with score ≥ ${minScore}` };
+    },
+    processSingle(log, options) {
+        const { logs, summary } = processor.processBatch([log], options);
+        return { log: logs[0], summary };
     },
 };

examples/components/script-only-pipeline/components/shared/state.ts

@@ -1,4 +1,4 @@
-import type { AccessLog } from 'example:log-pipeline/dataset';
+import type { AccessLog } from 'example:log-pipeline/types';
 
 export interface Dataset {
     logs: AccessLog[];

examples/components/script-only-pipeline/components/top-pages/top-pages.ts

@@ -9,12 +9,13 @@ export const processor: typeof ProcessorInterface = {
             defaultOptions: JSON.stringify({ limit: 5 }),
         };
     },
-    process(json) {
+    processBatch(logs, json) {
         const { limit = 5 } = parseOptions(json);
         if (typeof limit !== 'number' || !Number.isInteger(limit) || limit < 1 || limit > 100) {
             throw 'limit must be an integer from 1 to 100';
         }
         const data = getDataset();
+        data.logs = logs;
         const counts = new Map<string, number>();
         for (const log of data.logs) {
             counts.set(log.path, (counts.get(log.path) ?? 0) + 1);
@@ -24,6 +25,10 @@ export const processor: typeof ProcessorInterface = {
             .sort((a, b) => b.visits - a.visits || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
             .slice(0, limit);
         data.reports.topPages = pages;
-        return `Pages: counted ${data.logs.length} logs across ${counts.size} paths`;
+        return { logs: data.logs, summary: `Pages: counted ${data.logs.length} logs across ${counts.size} paths` };
+    },
+    processSingle(log, options) {
+        const { logs, summary } = processor.processBatch([log], options);
+        return { log: logs[0], summary };
     },
 };

examples/components/script-only-pipeline/demo/browser.js

@@ -117,15 +117,16 @@ $('#components').addEventListener('change', async (event) => {
 $('#run').addEventListener('click', () => {
     invalidate();
     try {
-        const result = pipeline.run(
-            $('#input').value,
-            stages.map((stage) => ({
-                script: stage.script,
-                options: JSON.parse(stage.options),
-            })),
-        );
+        const input = JSON.parse($('#input').value);
+        const configuredStages = stages.map((stage) => ({
+            script: stage.script,
+            options: JSON.parse(stage.options),
+        }));
+        const result = Array.isArray(input)
+            ? pipeline.runBatch(input, configuredStages)
+            : pipeline.runSingle(input, configuredStages);
         $('#output').textContent = JSON.stringify({ logs: result.logs, reports: result.reports }, null, 2);
-        $('#count').textContent = `${result.logs.length} logs / ${stages.length} steps`;
+        $('#count').textContent = `${result.logs.length} logs / ${result.steps.length} steps`;
         $('#output-note').textContent = 'Every run starts with fresh input. Steps share data inside the engine.';
         for (const step of result.steps) {
             const row = document.createElement('li');
@@ -145,6 +146,10 @@ $('#clear').addEventListener('click', () => {
     status('Pipeline cleared · upload a component to start again');
 });
 $('#restore').addEventListener('click', restoreSample);
+$('#single-input').addEventListener('click', () => {
+    $('#input').value = JSON.stringify(sample[1], null, 2);
+    invalidate();
+});
 $('#input').addEventListener('input', invalidate);
 function restoreSample() {
     $('#input').value = JSON.stringify(sample, null, 2);

examples/components/script-only-pipeline/demo/custom-component.js

@@ -58,7 +58,7 @@ export async function createCustomComponent(name, source) {
     });
     const exports = Object.values(result.metafile.outputs).flatMap((output) => output.exports);
     if (exports.length !== 1 || exports[0] !== 'processor') {
-        throw new Error('Export one processor object with describe() and process(options) methods');
+        throw new Error('Export one processor object with describe(), processBatch(), and processSingle() methods');
     }
     await $init;
     return scripts.createComponent({

examples/components/script-only-pipeline/demo/custom-template.ts

@@ -9,13 +9,18 @@ export const processor: typeof ProcessorInterface = {
             defaultOptions: JSON.stringify({ minStatus: 400 }),
         };
     },
-    process(json) {
+    processBatch(logs, json) {
         const { minStatus = 400 } = parseOptions(json);
         if (typeof minStatus !== 'number' || minStatus < 100 || minStatus > 599) {
             throw 'minStatus must be a number from 100 to 599';
         }
         const data = getDataset();
+        data.logs = logs;
         data.logs = data.logs.filter((log) => log.status >= minStatus);
-        return `HTTP status: kept ${data.logs.length} logs with status >= ${minStatus}`;
+        return { logs: data.logs, summary: `HTTP status: kept ${data.logs.length} logs with status >= ${minStatus}` };
+    },
+    processSingle(log, options) {
+        const { logs, summary } = processor.processBatch([log], options);
+        return { log: logs[0], summary };
     },
 };

examples/components/script-only-pipeline/demo/editor.js

@@ -1,12 +1,9 @@
-const CODEMIRROR_URL = 'https://esm.sh/codemirror@6.0.2';
-const JAVASCRIPT_URL = 'https://esm.sh/@codemirror/lang-javascript@6.2.4';
-
 /** Enhance the source textarea without making the rest of the demo depend on a CDN. */
 export async function mountEditor(textarea, parent) {
-    const [{ EditorView, basicSetup }, { javascript }] = await Promise.all([
-        import(/* @vite-ignore */ CODEMIRROR_URL),
-        import(/* @vite-ignore */ JAVASCRIPT_URL),
-    ]);
+    const modules = ['codemirror', '@codemirror/lang-javascript'];
+    const [{ EditorView, basicSetup }, { javascript }] = await Promise.all(
+        modules.map((name) => import(/* @vite-ignore */ name)),
+    );
     const view = new EditorView({
         parent,
         doc: textarea.value,