@sheetxl/runner 0.8.0-beta.1 → 0.8.0-beta.3

package/README.md

@@ -19,7 +19,19 @@ npm i -D @sheetxl/runner
 ## Using  the runner
 
 ``` ts
-export type Runner = (workbook: IWorkbook, target: RunTarget | RunTarget[], options?: RunOptions) => Promise<void>;
+export type Runner = (workbook: IWorkbook | null, args: ArgV | undefined, options: RunOptions) => Promise<IWorkbook | any | void>;
+```
+
+The two data inputs are positional — the workbook and the args. Everything else is host wiring and
+lives in `RunOptions`, `target` included.
+
+`run` hands back whatever the script returned: a tally, a range, nothing. A returned `IWorkbook` is
+also the workbook the run ended on — the one to write for `--save`/`--out` — so a host that needs it
+reads it off the result:
+
+```ts
+const result = await Runner.run(wb, args, { target: 'scripts/transform.ts' });
+const ended = (result as IWorkbook)?.isIWorkbook ? result as IWorkbook : wb;
 ```
 
 ``` ts
@@ -28,8 +40,8 @@ import { Runner } from '@sheetxl/runner';
 
 const wb = new Workbook();
 
-await Runner.run(wb, 'scripts/transform.ts', {
-  args: ['region=EU']
+await Runner.run(wb, { raw: ['--region', 'EU'], kv: { region: 'EU' }, _: [] }, {
+  target: 'scripts/transform.ts'
 });
 
 ```

package/node/esm/index.mjs

@@ -1,5 +1,5 @@
 /**
-* @license @sheetxl/runner - SheetXL - Programmatic execution for SheetXL scripts - v0.8.0-beta.1
+* @license @sheetxl/runner - SheetXL - Programmatic execution for SheetXL scripts - v0.8.0-beta.3
 *
 * (C) 2026-present SheetXL Inc. & Michael T. Ford
 * License: The license can be found at https://www.sheetxl.com/license.
@@ -7,37 +7,38 @@
 import t from "node:path";
 import e from "node:fs";
 import { pathToFileURL as n } from "node:url";
-import { createLogChannels as r } from "@sheetxl/utils";
-var i = Object.defineProperty;
-function s(e, n = "SHEETXL_IN") {
+import { createLogChannels as r, resolveLogTimeout as s } from "@sheetxl/utils";
+var o = Object.defineProperty;
+function i(e, n = "SHEETXL_IN") {
 	if (t.isAbsolute(e)) return e;
 	const r = n ? process.env[n] : void 0;
 	return t.resolve(r ?? process.cwd(), e);
 }
-var o = ((t, e) => {
+var a = ((t, e) => {
 	let n = {};
-	for (var r in t) i(n, r, {
+	for (var r in t) o(n, r, {
 		get: t[r],
 		enumerable: !0
 	});
-	return e || i(n, Symbol.toStringTag, { value: "Module" }), n;
+	return e || o(n, Symbol.toStringTag, { value: "Module" }), n;
 })({
-	DEFAULT_DESCRIPTION: () => g,
-	classify: () => m,
-	prepare: () => y
-}), a = null;
-function c() {
-	return a || (a = (async () => {
+	DEFAULT_DESCRIPTION: () => S,
+	classify: () => x,
+	prepare: () => E,
+	toSnippetOffset: () => _
+}), c = null;
+function l() {
+	return c || (c = (async () => {
 		try {
 			const t = await import("typescript");
 			return t.default ?? t;
 		} catch {
 			return null;
 		}
-	})()), a;
+	})()), c;
 }
-async function l(t) {
-	const e = await c();
+async function u(t) {
+	const e = await l();
 	if (!e) return null;
 	const n = e.createSourceFile("snippet.ts", t, e.ScriptTarget.Latest, !1, e.ScriptKind.TS);
 	return (n.parseDiagnostics?.length ?? 0) > 0 ? null : {
@@ -45,154 +46,252 @@ async function l(t) {
 		sf: n
 	};
 }
-function u(t, e) {
-	return t.text.slice(e.getStart(t), e.end);
-}
-function f(t) {
-	return t.endsWith(";") ? t : `${t};`;
-}
 function p(t) {
 	let e = 0;
 	for (let n = 0; n < t.length; n++) "\n" === t[n] && e++;
 	return e;
 }
-function d(t, e) {
-	const n = e.getStart(t);
-	let r = t.text.slice(n, e.end);
-	const i = e.declarationList.declarations;
-	for (let e = i.length - 1; e >= 0; e--) {
-		const s = i[e].initializer;
-		if (!s) continue;
-		const o = s.getStart(t) - n, a = s.end - n;
-		r = `${r.slice(0, o)}await (${r.slice(o, a)})${r.slice(a)}`;
+function f(t, e, n) {
+	let r = n.getStart(e);
+	for (const s of n.declarationList.declarations) {
+		const n = s.initializer;
+		if (!n) continue;
+		const o = n.getStart(e);
+		t.copy(r, o), t.add("await ("), t.copy(o, n.end), t.add(")"), r = n.end;
 	}
-	return f(r);
+	t.copy(r, n.end), t.terminate();
 }
-async function m(t) {
-	const e = await l(t);
-	return e ? function(t, e) {
+var d = class {
+	constructor(t) {
+		this._code = t, this.spans = [], this._parts = [], this._length = 0;
+	}
+	add(t) {
+		this._parts.push(t), this._length += t.length;
+	}
+	copy(t, e) {
+		e <= t || (this.spans.push({
+			at: this._length,
+			from: t,
+			length: e - t
+		}), this.add(this._code.slice(t, e)));
+	}
+	terminate() {
+		this._parts[this._parts.length - 1]?.endsWith(";") || this.add(";");
+	}
+	toString() {
+		return this._parts.join("");
+	}
+}, m = "await wb?.whenCalculationReady?.(); ";
+function h(t, e) {
+	const n = e.statements;
+	let r = n.length - 1;
+	for (; r >= 0 && n[r].kind === t.SyntaxKind.EmptyStatement;) r--;
+	if (r < 0) return null;
+	const s = n[r];
+	if ((t.isExpressionStatement(s) || t.isExportAssignment(s) && !s.isExportEquals) && ((e) => {
+		for (; t.isParenthesizedExpression(e);) e = e.expression;
+		return t.isArrowFunction(e) || t.isFunctionExpression(e);
+	})(s.expression)) return {
+		index: r,
+		from: s.expression.getStart(e),
+		to: s.expression.end
+	};
+	if (t.isFunctionDeclaration(s) && s.body) {
+		const n = t.getModifiers(s) ?? [], o = n.some((e) => e.kind === t.SyntaxKind.ExportKeyword);
+		if (n.some((e) => e.kind === t.SyntaxKind.DefaultKeyword) && !s.name || !o && function(t, e) {
+			let n = -1;
+			for (let r = 0; r < e.statements.length; r++) {
+				const s = e.statements[r];
+				if (s.kind !== t.SyntaxKind.EmptyStatement && !t.isImportDeclaration(s) && !t.isImportEqualsDeclaration(s)) {
+					if (-1 !== n) return -1;
+					n = r;
+				}
+			}
+			return n;
+		}(t, e) === r) {
+			let o = s.getStart(e);
+			for (const e of n) e.kind !== t.SyntaxKind.ExportKeyword && e.kind !== t.SyntaxKind.DefaultKeyword || (o = e.end);
+			for (; o < s.end && /\s/.test(e.text[o]);) o++;
+			return {
+				index: r,
+				from: o,
+				to: s.end
+			};
+		}
+	}
+	return null;
+}
+var y = "const __entry: (ctx: SheetXL.IScript.ScriptContext) => unknown = (", g = (t) => `); ${t} = await __entry(ctx);`;
+async function x(t) {
+	const e = await u(t);
+	if (!e) return function(t) {
+		return /^\s*export\s+default\b/m.test(t) || /^\s*export\s*\{[^}]*\bas\s+default\b/m.test(t);
+	}(t) ? "script" : "snippet";
+	const { ts: n, sf: r } = e;
+	return function(t, e) {
 		for (const n of e.statements) {
 			if (t.isExportAssignment(n) && !n.isExportEquals) return !0;
 			if (t.canHaveModifiers(n) && t.getModifiers(n)?.some((e) => e.kind === t.SyntaxKind.DefaultKeyword)) return !0;
 			if (t.isExportDeclaration(n) && n.exportClause && t.isNamedExports(n.exportClause) && n.exportClause.elements.some((t) => "default" === t.name.text)) return !0;
 		}
 		return !1;
-	}(e.ts, e.sf) ? "script" : "snippet" : function(t) {
-		return /^\s*export\s+default\b/m.test(t) || /^\s*export\s*\{[^}]*\bas\s+default\b/m.test(t);
-	}(t) ? "script" : "snippet";
+	}(n, r) && !function(t, e) {
+		const n = h(t, e);
+		return !!n && e.statements.every((e, r) => r === n.index || !t.isExportAssignment(e) && !t.isExportDeclaration(e) && !(t.canHaveModifiers(e) && t.getModifiers(e)?.some((e) => e.kind === t.SyntaxKind.ExportKeyword)));
+	}(n, r) ? "script" : "snippet";
 }
-var w = 3, g = "Run Snippet", h = (t, e, n = [], r) => [
-	...n,
-	...r ? [r] : [],
-	"export default async function __snippet(ctx: SheetXL.IScript.ScriptContext): Promise<void> {",
-	"  const { wb, log, warn, error, args } = ctx as any;",
-	"  let __result: any = undefined;",
-	t,
-	"  ;",
-	e,
-	"};"
-].join("\n");
-async function y(t, e) {
-	const n = e?.epilogue ?? "  return __result;", r = await l(t);
+var w = 3, S = "Run Snippet", v = (t, e, n = [], r) => {
+	const s = [
+		...n,
+		...r ? [r] : [],
+		"export default async function __snippet(ctx: SheetXL.IScript.ScriptContext): Promise<void> {",
+		"  const { wb, log, warn, error, args } = ctx;",
+		"  let __result: any = undefined;"
+	].join("\n") + "\n";
+	return {
+		source: s + [
+			t,
+			"  ;",
+			e,
+			"};"
+		].join("\n"),
+		bodyStart: s.length
+	};
+};
+async function E(t, e) {
+	const n = e?.epilogue ?? "  return __result;", r = await u(t);
 	if (!r) {
-		const e = await c() ? void 0 : "TypeScript is unavailable, so this snippet ran without implicit await or a result value. Install the `typescript` peer dependency to restore them.";
+		const e = await l() ? void 0 : "TypeScript is unavailable, so this snippet ran without implicit await or a result value. Install the `typescript` peer dependency to restore them.", { source: r, bodyStart: s } = v(t, n);
 		return {
-			source: h(t, n),
+			source: r,
 			kind: "verbatim",
 			lineOffset: w,
+			spans: [{
+				at: s,
+				from: 0,
+				length: t.length
+			}],
 			warning: e
 		};
 	}
-	const { ts: i, sf: s } = r, o = s.statements, a = function(t, e) {
+	const { ts: s, sf: o } = r, i = o.statements, a = function(t, e) {
 		if (!e.statements[0]) return;
 		const n = t.getLeadingCommentRanges(e.text, 0);
 		if (n?.length) for (let r = n.length - 1; r >= 0; r--) {
-			const i = n[r];
-			if (i.kind !== t.SyntaxKind.MultiLineCommentTrivia) continue;
-			const s = e.text.slice(i.pos, i.end);
-			if (s.startsWith("/**")) return s;
+			const s = n[r];
+			if (s.kind !== t.SyntaxKind.MultiLineCommentTrivia) continue;
+			const o = e.text.slice(s.pos, s.end);
+			if (o.startsWith("/**")) return o;
 		}
-	}(i, s), m = a ? p(a) + 1 : 0;
-	if (1 === o.length && i.isBlock(o[0])) return {
-		source: h(`  __result = await (\n${t}\n  );`, n, [], a),
-		kind: "expression",
-		lineOffset: w + m + 1
-	};
-	const { body: g, hoisted: y } = function(t, e, n) {
-		const r = e.text, i = e.statements;
-		let s = -1;
-		for (let e = i.length - 1; e >= 0; e--) if (i[e].kind !== t.SyntaxKind.EmptyStatement) {
-			t.isExpressionStatement(i[e]) && (s = e);
+	}(s, o), c = a ? p(a) + 1 : 0;
+	if (1 === i.length && s.isBlock(i[0])) {
+		const { source: r, bodyStart: s } = v(`  __result = await (
+${t}\n  );`, n, [], a);
+		return {
+			source: r,
+			kind: "expression",
+			lineOffset: w + c + 1,
+			spans: [{
+				at: s + 21,
+				from: 0,
+				length: t.length
+			}]
+		};
+	}
+	const { body: x, spans: S, hoisted: E } = function(t, e, n) {
+		const r = e.text, s = e.statements;
+		let o = -1;
+		for (let e = s.length - 1; e >= 0; e--) if (s[e].kind !== t.SyntaxKind.EmptyStatement) {
+			t.isExpressionStatement(s[e]) && (o = e);
 			break;
 		}
-		const o = [], a = [];
-		let c = 0;
-		for (let l = 0; l < i.length; l++) {
-			const m = i[l], w = m.getStart(e);
-			a.push(r.slice(c, w)), c = m.end;
-			const g = r.slice(w, m.end);
-			if (t.isImportDeclaration(m) || t.isImportEqualsDeclaration(m)) o.push(g), a.push("\n".repeat(p(g)));
-			else if (t.isVariableStatement(m)) a.push(d(e, m));
-			else {
-				if (t.isExpressionStatement(m)) {
-					const t = u(e, m.expression);
-					a.push(l === s ? `${n} = await (${t});` : `await (${t});`);
-					continue;
-				}
-				a.push(f(g));
+		const i = h(t, e), a = [], c = new d(r);
+		let l = 0, u = !1;
+		for (let d = 0; d < s.length; d++) {
+			const h = s[d], x = h.getStart(e);
+			if (c.copy(l, x), l = h.end, t.isImportDeclaration(h) || t.isImportEqualsDeclaration(h)) {
+				const t = r.slice(x, h.end);
+				a.push({
+					text: t,
+					from: x
+				}), c.add("\n".repeat(p(t)));
+				continue;
 			}
+			u && c.add(m), u = !0, i?.index !== d ? t.isVariableStatement(h) ? f(c, e, h) : t.isExpressionStatement(h) ? (c.add(d === o ? `${n} = await (` : "await ("), c.copy(h.expression.getStart(e), h.expression.end), c.add(");")) : (c.copy(x, h.end), c.terminate()) : (c.add(y), c.copy(i.from, i.to), c.add(g(n)));
 		}
-		return a.push(r.slice(c)), {
-			body: a.join(""),
-			hoisted: o
+		return c.copy(l, r.length), {
+			body: c.toString(),
+			spans: c.spans,
+			hoisted: a
+		};
+	}(s, o, "__result"), _ = E.map((t) => t.text), b = E.length > 0 ? p(_.join("\n")) + E.length : 0, { source: k, bodyStart: K } = v(x, n, _, a);
+	let D = 0;
+	const R = E.map((t) => {
+		const e = {
+			at: D,
+			from: t.from,
+			length: t.text.length
 		};
-	}(i, s, "__result"), x = y.length > 0 ? p(y.join("\n")) + y.length : 0;
+		return D += t.text.length + 1, e;
+	});
 	return {
-		source: h(g, n, y, a),
+		source: k,
 		kind: "statements",
-		lineOffset: w + x + m
+		lineOffset: w + b + c,
+		spans: [...R, ...S.map((t) => ({
+			...t,
+			at: t.at + K
+		}))]
 	};
 }
-async function x(t, e, n = "Runner timed out") {
+function _(t, e) {
+	let n = null;
+	for (const r of t.spans) {
+		if (r.at > e) return null !== n && e < n.at + n.length ? n.from + (e - n.at) : r.from;
+		n = r;
+	}
+	return n ? n.from + Math.min(e - n.at, n.length) : 0;
+}
+async function b(t, e, n = "Runner timed out") {
 	if (!e || e <= 0) return t;
 	let r;
-	const i = new Promise((t, i) => r = setTimeout(() => i(new Error(n)), e));
+	const s = new Promise((t, s) => r = setTimeout(() => s(new Error(n)), e));
 	try {
-		return await Promise.race([t, i]);
+		return await Promise.race([t, s]);
 	} finally {
 		clearTimeout(r);
 	}
 }
-var S = null;
-function v() {
-	return S || (S = (async () => {
+var k = null;
+function K() {
+	return k || (k = (async () => {
 		const { register: t } = await import("tsx/esm/api");
 		t({ tsconfig: !1 });
-	})()), S;
+	})()), k;
 }
-var b = "data:text/typescript,", $ = "data:text/javascript,", E = null;
-function _() {
-	return E || (E = (async () => {
-		const { registerHooks: e, stripTypeScriptTypes: r } = await import("node:module"), i = r;
+var D = "data:text/typescript,", R = "data:text/javascript,", I = null;
+function $() {
+	return I || (I = (async () => {
+		const { registerHooks: e, stripTypeScriptTypes: r } = await import("node:module"), s = r;
 		e({
-			resolve(e, r, i) {
-				const s = r.parentURL;
-				if (s && (s.startsWith(b) || s.startsWith($))) {
-					const s = n(t.join(process.cwd(), "_inline_.ts")).href;
-					return i(e, {
+			resolve(e, r, s) {
+				const o = r.parentURL;
+				if (o && (o.startsWith(D) || o.startsWith(R))) {
+					const o = n(t.join(process.cwd(), "_inline_.ts")).href;
+					return s(e, {
 						...r,
-						parentURL: s
+						parentURL: o
 					});
 				}
-				return i(e, r);
+				return s(e, r);
 			},
 			load(t, e, n) {
-				if (t.startsWith(b)) {
+				if (t.startsWith(D)) {
 					const e = decodeURIComponent(t.slice(21)), n = process.emitWarning;
 					let r;
 					process.emitWarning = () => {};
 					try {
-						r = i(e, { mode: "transform" });
+						r = s(e, { mode: "transform" });
 					} finally {
 						process.emitWarning = n;
 					}
@@ -205,85 +304,89 @@ function _() {
 				return n(t, e);
 			}
 		});
-	})()), E;
+	})()), I;
 }
-async function R(e) {
-	const r = "string" == typeof (i = e) ? i.startsWith("file:") ? i : n(t.resolve(process.cwd(), i)).href : i.href;
-	var i;
-	const s = t.extname(new URL(r).pathname).toLowerCase();
-	return ".ts" !== s && ".tsx" !== s || await v(), import(r);
+async function C(e) {
+	const r = "string" == typeof (s = e) ? s.startsWith("file:") ? s : n(t.resolve(process.cwd(), s)).href : s.href;
+	var s;
+	const o = t.extname(new URL(r).pathname).toLowerCase();
+	return ".ts" !== o && ".tsx" !== o || await K(), import(r);
 }
-async function k(t, e) {
-	const n = e.notifier ?? (await import("@sheetxl/sdk")).Notifier, i = r({
-		debug: (t) => n.debug(t),
-		log: (t) => n.log(t),
-		info: (t) => n.log(t),
-		warn: (t) => n.warn(t),
-		error: (t) => n.error(t)
-	}, { render: e.render });
+async function L(t, e, n) {
+	const s = n.notifier ?? (await import("@sheetxl/sdk")).Notifier, o = r({
+		debug: (t) => s.debug(t),
+		log: (t) => s.log(t),
+		info: (t) => s.log(t),
+		warn: (t) => s.warn(t),
+		error: (t) => s.error(t)
+	}, { render: n.render });
 	return {
 		ctx: {
-			args: e.args ?? {
+			args: e ?? {
 				raw: [],
 				kv: {},
 				_: []
 			},
 			wb: t,
-			log: i.log,
-			warn: i.warn,
-			error: i.error
+			log: o.log,
+			warn: o.warn,
+			error: o.error
 		},
-		channels: i,
-		notifier: n
+		channels: o,
+		notifier: s
 	};
 }
-var C = { run: async (n, r, i = {}) => {
-	const s = Array.isArray(r) ? r : [r], o = await Promise.all(s.map((n) => (async (n, r = {}) => {
-		let i = null;
-		const s = (t, e) => {
+var T = async (n, r, o) => {
+	const i = o.target, a = Array.isArray(i) ? i : [i], c = await Promise.all(a.map((n) => (async (n, r = {}) => {
+		let s = null;
+		const o = (t, e) => {
 			let n = t?.default;
 			if (n && "function" != typeof n && "function" == typeof n.default && (n = n.default), "function" != typeof n) throw new Error(`Script '${e}' has no runnable entry: export a default function, e.g. \`export default function main(ctx) { … }\`.`);
 			return n;
 		};
-		if ("function" == typeof n) i = n;
+		if ("function" == typeof n) s = n;
 		else if ("string" == typeof n || n instanceof URL) {
-			let o = null;
-			if ("string" != typeof n || /^[a-z]+:\/\//i.test(n)) o = await R(n);
+			let i = null;
+			if ("string" != typeof n || /^[a-z]+:\/\//i.test(n)) i = await C(n);
 			else {
-				const i = t.resolve(r.cwd ?? process.cwd(), n);
-				if (!e.existsSync(i)) throw new Error(`Script not found: ${i}`);
-				e.accessSync(i, e.constants.R_OK), o = await R(i);
+				const s = t.resolve(r.cwd ?? process.cwd(), n);
+				if (!e.existsSync(s)) throw new Error(`Script not found: ${s}`);
+				e.accessSync(s, e.constants.R_OK), i = await C(s);
 			}
-			i = s(o, String(n));
+			s = o(i, String(n));
 		} else if ("code" in n) {
 			const t = n.filename ?? "inline.ts";
 			let e, r = null;
-			t.endsWith(".ts") || t.endsWith(".tsx") ? (await v(), await _(), e = `${b}${encodeURIComponent(n.code)}`, r = await import(e)) : (await _(), e = `${$}${encodeURIComponent(n.code)}`, r = await import(e)), i = s(r, t);
+			t.endsWith(".ts") || t.endsWith(".tsx") ? (await K(), await $(), e = `${D}${encodeURIComponent(n.code)}`, r = await import(e)) : (await $(), e = `${R}${encodeURIComponent(n.code)}`, r = await import(e)), s = o(r, t);
 		} else {
 			if (!("runner" in n)) throw new Error("Invalid run target specified.");
-			i = n.runner;
+			s = n.runner;
 		}
-		return i;
-	})(n, i))), a = Date.now();
-	let c = n, l = null;
-	const u = o.length;
-	for (let t = 0; t < u; t++) {
-		const e = o[t], { ctx: n, channels: r, notifier: s } = await k(c, i);
-		l = s;
-		const a = Date.now();
-		let f;
+		return s;
+	})(n, o))), l = Date.now();
+	let u, p = n, f = null;
+	const d = c.length;
+	for (let t = 0; t < d; t++) {
+		const e = c[t], { ctx: n, channels: i, notifier: a } = await L(p, r, o);
+		f = a;
+		const l = Date.now();
+		let m;
+		const h = p, y = () => Promise.resolve().then(() => e(n));
 		try {
-			f = await x(Promise.resolve().then(() => e(n)), i.timeoutMs, "Runner timed out");
+			m = await b(null !== h ? Promise.resolve(h.doBatch(y, "Run Script")) : y(), o.timeoutMs, "Runner timed out");
 		} finally {
-			await r.flush();
+			await i.flush({ timeoutMs: s(o.logTimeoutMs) });
 		}
-		const p = Date.now();
-		null != f && f.isIWorkbook && (c = f), s.debug(`Run ${1 === u ? "" : `${t + 1}/${u} `}completed in ${p - a} ms.`);
+		const g = Date.now();
+		u = m, null != m && m.isIWorkbook && (p = m), a.debug(`Run ${1 === d ? "" : `${t + 1}/${d} `}completed in ${g - l} ms.`);
 	}
-	if (u > 1 && l) {
+	if (d > 1 && f) {
 		const t = Date.now();
-		l.debug(`All runs completed in ${t - a} ms.`);
+		f.debug(`All runs completed in ${t - l} ms.`);
 	}
-	return c ?? void 0;
+	return u;
+}, W = { run: async (t, e, n) => {
+	const { withScriptRuntime: r } = await import("@sheetxl/sdk");
+	return r(() => T(t, e, n));
 } };
-export { o as Snippet, C as default, s as resolvePath };
+export { a as Snippet, W as default, i as resolvePath };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sheetxl/runner",
   "description": "SheetXL - Programmatic execution for SheetXL scripts",
-  "version": "0.8.0-beta.1",
+  "version": "0.8.0-beta.3",
   "license": "SEE LICENSE IN <LICENSE>",
   "type": "module",
   "exports": {
@@ -36,11 +36,11 @@
     "runner"
   ],
   "dependencies": {
-    "@sheetxl/io": "^0.8.0-beta.1",
-    "@sheetxl/primitives": "^0.8.0-beta.1",
-    "@sheetxl/scripting": "^0.8.0-beta.1",
-    "@sheetxl/sdk": "^0.8.0-beta.1",
-    "@sheetxl/utils": "^0.8.0-beta.1"
+    "@sheetxl/io": "^0.8.0-beta.3",
+    "@sheetxl/primitives": "^0.8.0-beta.3",
+    "@sheetxl/scripting": "^0.8.0-beta.3",
+    "@sheetxl/sdk": "^0.8.0-beta.3",
+    "@sheetxl/utils": "^0.8.0-beta.3"
   },
   "peerDependencies": {
     "typescript": "^5.9.0 || ^6.0.0"

package/types/src/Runner.d.ts

@@ -1,14 +1,12 @@
 import { Runner } from './Types';
-/** Core: run targets as a serial pipeline, each receiving the current workbook.
+/**
+ * Runs the pipeline with the `SheetXL` global installed.
  *
- * Pipeline semantics:
- * - Targets run **serially** in order, never in parallel.
- * - Each target receives a fresh `RunContext` built with the **current** workbook.
- * - If a target returns an `IWorkbook`, that becomes the workbook for all subsequent targets.
- * - `args` are shared across all targets — they represent pipeline-level configuration,
- *   not per-step input.  This follows the standard Unix convention where environment
- *   variables / flags are visible to every process in a pipeline.
- * - Returns the final workbook (which may differ from the one passed in).
+ * @remarks
+ * The declarations a script is written against promise `SheetXL.ISheet.Visibility.Hidden` is a
+ * VALUE. A compiled macro gets it from the macro runtime; source run here is type-stripped and
+ * imported, so nothing would define it. The install spans module LOADING too, not only the call —
+ * a script may read an enum at its top level — and is removed however the run ends.
  */
 export declare const run: Runner;
 declare const _default: {

package/types/src/Snippet.d.ts

@@ -9,7 +9,16 @@
  * contract promises two things a bare paste into an async function does not give them —
  *  1. **implicit await**: nothing in a snippet is ever written `await`, yet a promise-returning
  *     statement must have settled before the next one runs;
- *  2. **the final expression is the result**: exactly like a REPL, or `node -p`.
+ *  2. **the final expression is the result**: exactly like a REPL, or `node -p`;
+ *  3. **values are current**: calculation is asynchronous, so a formula set by one statement is
+ *     settled before the next statement runs — `setFormula('=1+1')` then `getValue()` reads `2`,
+ *     the way it reads in Excel, rather than the `null` a bare paste would see.
+ *
+ * **A snippet that is a function is called.** Its value is the function — `async ({ wb }) => …` as
+ * the final expression, or a snippet that is only `function main(ctx) { … }` — so it is called with
+ * the context, typed as a script's entry would be, and its return is the result. `export default` in
+ * front of an arrow or an anonymous function, with nothing else exported, is ceremony for the same
+ * thing and runs the same way: the script form is kept for what needs it, a named entry or exports.
  *
  * This is the same problem Node's REPL solves in `lib/internal/repl/await.js`, and it is solved the
  * same way: **parse for real, then rewrite the top-level statements from the AST.** Statement
@@ -32,9 +41,21 @@
  * context parameter) so the identical source compiles on every path: the CLI's type-stripping
  * loader ignores the annotations, and the `ScriptCompiler`'s linter requires them.
  */
+/**
+ * A run of the author's own text inside an emitted source: `length` characters that sit at `at`
+ * in the emitted text and came from `from` in the snippet.
+ */
+export interface Span {
+    at: number;
+    from: number;
+    length: number;
+}
 /** How a source will run — see the module remarks for the contract. */
 export type SourceForm = 'script' | 'snippet';
-/** `script` when the source has a top-level default export; `snippet` otherwise. */
+/**
+ * `script` when the source has a top-level default export; `snippet` otherwise — and when that
+ * export is only an entry function (`export default async ({ wb }) => …`), which runs as a snippet.
+ */
 export declare function classify(code: string): Promise<SourceForm>;
 export interface WrapOptions {
     /**
@@ -55,11 +76,13 @@ export interface Prepared {
      */
     kind: 'expression' | 'statements' | 'verbatim';
     /**
-     * Lines of wrapper prologue before the first line of user code — subtract from a compiler
-     * diagnostic's line to point back into the snippet. Exact for every kind: the rewrite emits the
-     * original trivia, so no line moves.
+     * Lines of wrapper prologue before the first line of user code. Exact for every kind: the
+     * rewrite emits the original trivia, so no line moves. It places LINES only — to point a
+     * compiler position back into the snippet, line and column, use {@link toSnippetOffset}.
      */
     lineOffset: number;
+    /** Where the author's text sits within {@link source}, in source order. */
+    spans: Span[];
     /**
      * Set only when the contract could not be honored — no implicit await, no result. Callers should
      * surface it; a snippet quietly returning `undefined` is worse than one that failed.
@@ -86,4 +109,14 @@ export declare const DEFAULT_DESCRIPTION = "Run Snippet";
  * sidesteps any position mapping — the whole snippet is the expression.
  */
 export declare function prepare(code: string, options?: WrapOptions): Promise<Prepared>;
+/**
+ * Where an offset into a prepared {@link Prepared.source} sits in the snippet the author wrote.
+ *
+ * @remarks
+ * Exact wherever the offset falls in the author's own text, which is where a compiler puts a
+ * diagnostic about it. An offset in text the wrapper added has no place in the snippet, so it
+ * answers with the nearest thing that does: the author's next character, or the end of their last
+ * text when nothing of theirs follows.
+ */
+export declare function toSnippetOffset(prepared: Prepared, offset: number): number;
 //# sourceMappingURL=Snippet.d.ts.map

package/types/src/Types.d.ts

@@ -1,5 +1,5 @@
 import { IWorkbook } from '@sheetxl/sdk';
-import { LogRenderer } from '@sheetxl/utils';
+import { LogRenderer, MaybePromise } from '@sheetxl/utils';
 export type Notifier = typeof import('@sheetxl/sdk').Notifier;
 /**
  * Arguments passed after `--` on the CLI (`sheetxl -f <script> [workbook] -- [args...]`).
@@ -48,6 +48,9 @@ export type RunContext = {
      * Variadic and value-taking, like `console.log`: `log('rows:', n)` and `log(range.getStats())`
      * both work. An SDK object renders as its markdown report when the host supplies a renderer
      * (the CLI does); otherwise it falls back to JSON.
+     *
+     * A promise is awaited and logs as its settled value, so `log(sheet.evaluate(…))` needs no
+     * `await`. Output order is still call order.
      */
     readonly log: (...args: any[]) => void;
     /** Diagnostics: something surprising but survivable. Travels separately from `log` (stderr). */
@@ -57,8 +60,19 @@ export type RunContext = {
 };
 /**
  * The function signature for a script run by the CLI or the MCP `run` tool.
+ *
+ * @remarks
+ * The return value is the run's RESULT, the same contract a snippet's final expression has, so it
+ * is deliberately unconstrained — a tally, an `ICellRange`, a `getStats()` object. Returning
+ * nothing is normal: a run whose output is its `log` has no answer to hand back.
+ *
+ * An `IWorkbook` is the one return that is also *structural*: it becomes the workbook the next
+ * stage runs against, on top of being the result. Nothing else is inspected — an array is just an
+ * array.
+ *
+ * Sync or async, both real: `function main(ctx): number[]` is as valid as the `async` spelling.
  */
-export type RunFunction = (ctx: RunContext) => Promise<void | IWorkbook>;
+export type RunFunction = (ctx: RunContext) => MaybePromise<IWorkbook | any | void>;
 /**
  * Possible targets for the runner to execute
  */
@@ -69,7 +83,17 @@ export type RunTarget = string | URL | {
     runner: RunFunction;
 };
 export interface RunOptions {
-    args?: ArgV;
+    /**
+     * What to run — a path, a URL, inline code, or a function.
+     *
+     * @remarks
+     * An array runs as a serial pipeline: each stage gets the workbook the one before it left, and
+     * the run answers with the LAST stage's return value. That makes a chain lossy in one corner —
+     * an early stage that swapped the workbook is only visible if the last stage hands it back — so
+     * a host that needs per-stage reporting calls `run` once per target instead, which is what the
+     * CLI does (it owns the error report for the target that failed).
+     */
+    target: RunTarget | RunTarget[];
     /** The host's output sink (toasts on a UI host, the console on the CLI). Not exposed to scripts. */
     notifier?: Notifier;
     /**
@@ -82,6 +106,18 @@ export interface RunOptions {
     render?: LogRenderer;
     signal?: AbortSignal;
     timeoutMs?: number;
+    /**
+     * How long a finished stage waits for what it logged to settle, in milliseconds. `0` waits
+     * indefinitely.
+     *
+     * @remarks
+     * `log(promise)` prints what the promise settles to, so a stage is not done until its log is. A
+     * value still unsettled when this elapses prints as `[pending]`; nothing is thrown and the rest
+     * of the log is kept. Independent of `timeoutMs`, which bounds the script itself.
+     *
+     * @defaultValue `DEFAULT_LOG_TIMEOUT_MS` (10 seconds)
+     */
+    logTimeoutMs?: number;
     cwd?: string;
     ts?: {
         enabled?: boolean;
@@ -90,6 +126,24 @@ export interface RunOptions {
 }
 /**
  * Run any RunFunction with a built in context.
+ *
+ * @remarks
+ * The two data inputs are positional — the workbook the run is against, and the args it was given.
+ * Everything else is host wiring and lives in {@link RunOptions}, including `target`, which is why
+ * the options are required rather than optional.
+ *
+ * **Hands back exactly what the entry returned**, undisturbed — see {@link RunFunction}. A host
+ * that also needs the workbook the run ended on reads it off that value when it is one:
+ *
+ * ```ts
+ * const result = await run(wb, args, { target: 'transform.ts' });
+ * const ended = (result as IWorkbook)?.isIWorkbook ? result as IWorkbook : wb;
+ * ```
+ *
+ * Always a promise, even for a sync entry: resolving a target loads modules.
+ *
+ * `args` is spelled `ArgV | undefined` rather than `args?` because TypeScript will not let an
+ * optional parameter precede a required one — a run with no args passes `undefined` for it.
  */
-export type Runner = (workbook: IWorkbook | null, target: RunTarget | RunTarget[], options?: RunOptions) => Promise<void | IWorkbook>;
+export type Runner = (workbook: IWorkbook | null, args: ArgV | undefined, options: RunOptions) => Promise<IWorkbook | any | void>;
 //# sourceMappingURL=Types.d.ts.map