kopscript 0.8.0 → 0.9.0

package/LLM.md

@@ -11,8 +11,8 @@ Compiles to plain ES modules.
 ## CLI
 
 ```
-ks build <file.ks>          # type-check + emit <file>.js next to the source
-ks run <file.ks>            # build, then execute with node
+ks build <file.ks>          # type-check + emit <file>.js and <file>.js.map next to the source
+ks run <file.ks>            # build, then execute with node --enable-source-maps
 ks watch <file.ks>          # build, then rebuild on every change to any file in the graph
 ks check <file.ks>          # type-check only, no output files
 ks build|check <file.ks> --json   # single JSON object on stdout instead of human text
@@ -25,9 +25,14 @@ ks build|check <file.ks> --json   # single JSON object on stdout instead of huma
 ```
 
 `written` is the absolute paths actually written (`build` only, and only on success — a
-failed `build` writes nothing). Exit code is `0` iff `success` is `true`. A missing entry
+failed `build` writes nothing; `.js.map` paths aren't listed separately, one is written next
+to each `.js` path in `written`). Exit code is `0` iff `success` is `true`. A missing entry
 file yields `{ success: false, diagnostics: [], written: [], error: "cannot find file '...'" }`.
 
+Source maps are statement-level, not column-level (see `src/sourcemap.ts`, hand-rolled VLQ,
+zero added dependencies) — a thrown/uncaught error resolves to the right `.ks` line, but a
+specific sub-expression within one line isn't separately mapped.
+
 ## File shape
 
 ```ks

package/README.md

@@ -54,6 +54,10 @@ LLM's context, as opposed to this README's narrative explanation.
   file — interpolation, event/property bindings, `*if`/`*for` — down to the exact same
   AST a hand-written `Render()` would produce, with auto-`Subscribe` wiring for state
   referenced directly in the markup. See [Templates](#templates).
+- **Real debugging, not just readable output**: `ks build` emits a real source map next to
+  every `.js` file (original `.ks` embedded, no separate file to ship), and `ks run` enables
+  it automatically — an uncaught exception names the real `.ks` file and line, not the
+  generated JS. Hand-rolled VLQ encoder, zero added dependencies. See "Source maps" below.
 - **A companion framework, [Kopular](https://dev.azure.com/koppinator/Koppindependence/_git/Kopular)**:
   components, constructor-injected services via a composition root (no DI container), and
   real-URL routing (no config DSL) — built entirely on the features above, in a separate
@@ -741,8 +745,8 @@ runtime representation at all and are dropped from the emitted JS entirely.
 ## CLI
 
 ```
-ks build <file.ks>   # type-check and emit <file>.js next to the source
-ks run <file.ks>     # build, then execute the emitted JS with node
+ks build <file.ks>   # type-check and emit <file>.js (+ <file>.js.map) next to the source
+ks run <file.ks>     # build, then execute the emitted JS with node --enable-source-maps
 ks watch <file.ks>   # build, then rebuild on every change to any file in the graph
 ks check <file.ks>   # type-check only — no output files written
 ```
@@ -776,6 +780,19 @@ here), `KS5xxx` templates. There's no generated reference doc mapping every code
 explanation yet — for now, `message` is still the primary explanation; `code` is for
 matching, not (yet) for looking up docs.
 
+**Source maps**: `build` writes a real source-map v3 `<file>.js.map` alongside every
+`<file>.js`, with the original `.ks` source embedded (`sourcesContent`) so a deployed app
+doesn't need to ship its `.ks` files for devtools/stack traces to show real source. `run`
+passes Node's own `--enable-source-maps` flag automatically, so an uncaught exception
+during `ks run` names the real `.ks` file and line, not the generated `.js`. Hand-rolled
+(base64 VLQ), not the `source-map` npm package — kopscript has zero runtime dependencies
+and this keeps it that way (see `src/sourcemap.ts`). **Scope**: statement-level, not full
+expression/column-level — every statement (a class member, a block statement, a top-level
+declaration) gets its own mapping, but a specific sub-expression *within* one line doesn't.
+This is a deliberate v1 cut, the same spirit as generics/nullable types/templates: real,
+useful debugging (correct stack-trace lines, working breakpoints) without a full rewrite of
+codegen's string-concatenation architecture into a position-tracking writer.
+
 During development, use `npm run ks -- <build|run|watch|check> <file.ks>` (backed by
 `tsx`), or run `npm run build` to compile the TypeScript compiler itself to `dist/` and
 use `node dist/cli.js` directly.

package/dist/cli.js

@@ -66,7 +66,14 @@ function build(filePath, jsonMode = false) {
         return { outPath: null, watchFiles: allWatchFiles(result) };
     }
     for (const absPath of result.order) {
-        writeFileSync(outputPathFor(absPath), result.outputs.get(absPath), "utf-8");
+        const outPath = outputPathFor(absPath);
+        writeFileSync(outPath, result.outputs.get(absPath), "utf-8");
+        const map = result.sourceMaps.get(absPath);
+        // Only a file with real code got a `sourceMappingURL` comment appended
+        // (see codegen.ts) — skip writing an orphaned .map for one that didn't.
+        if (result.outputs.get(absPath).includes("//# sourceMappingURL=")) {
+            writeFileSync(`${outPath}.map`, map, "utf-8");
+        }
     }
     if (jsonMode)
         printJson(result, result.order.map(outputPathFor));
@@ -102,7 +109,10 @@ function run(filePath) {
     const { outPath } = build(filePath);
     if (!outPath)
         return;
-    const result = spawnSync(process.execPath, [outPath], { stdio: "inherit" });
+    // Node has resolved `//# sourceMappingURL` comments natively since v12.12
+    // — this is what makes an uncaught exception during `ks run` show the
+    // real .ks file/line instead of the generated .js, with no extra setup.
+    const result = spawnSync(process.execPath, ["--enable-source-maps", outPath], { stdio: "inherit" });
     process.exitCode = result.status ?? 0;
 }
 // Rebuilds on every save of any file in the graph (not just the entry —

package/dist/codegen.js

@@ -1,3 +1,11 @@
+import { SourceMapBuilder } from "./sourcemap.js";
+function countNewlines(text) {
+    let n = 0;
+    for (let i = 0; i < text.length; i++)
+        if (text[i] === "\n")
+            n++;
+    return n;
+}
 // KopScript's PascalCase stdlib member names, mapped to their real JS names — a
 // blind syntactic rename (codegen has no type information, so this fires on
 // any member access with a matching name, string/array/user-class alike;
@@ -55,19 +63,45 @@ export class CodeGenerator {
         this.matchCounter = 0;
         this.interfaceNames = new Set();
         this.usesState = false;
+        // The current 1-indexed *generated* output line — kept in sync with the
+        // text being built by every method that can introduce a literal `\n`
+        // (genBlock, genClass, genConstructor, genMatch, genInterpolatedString,
+        // and this method's own top-level loop). Nothing else needs to touch it:
+        // a "simple" single-line gen* case just leaves it untouched, and by the
+        // time control returns to whichever loop called it, `outputLine` already
+        // correctly reflects how many lines that call's output actually took —
+        // including a lambda/match-expression buried inside it, since those
+        // recurse back into the same bookkeeping. See sourcemap.ts for the actual
+        // encoder; see README.md's "Source maps" section for the v1 scope this
+        // is deliberately limited to (statement-level, not per-expression/column).
+        this.outputLine = 1;
+    }
+    mark(node, generatedColumn) {
+        this.sourceMap.addMapping(this.outputLine, generatedColumn, node.line, node.col);
     }
     // `usingExports` maps each `using "<path>"` path (as written in source) to
     // the list of names that module exports — resolved by the caller from that
     // module's own checked Program, since a bare `using` brings everything
-    // `public` into scope without naming it explicitly.
-    generate(program, usingExports = new Map(), rawContents = new Map()) {
+    // `public` into scope without naming it explicitly. `sourceFileName`/
+    // `sourceText` are for the emitted source map only (both optional so every
+    // existing test call site keeps compiling unchanged).
+    generate(program, usingExports = new Map(), rawContents = new Map(), sourceFileName = "source.ks", sourceText = "") {
         this.interfaceNames = new Set(program.statements.filter((s) => s.kind === "InterfaceDecl").map((s) => s.name));
+        this.outputLine = 1;
+        const outFileName = sourceFileName.replace(/\.ks$/, ".js");
+        this.sourceMap = new SourceMapBuilder(outFileName, sourceFileName, sourceText);
         const importLines = program.usings
             .map((u) => {
             const names = usingExports.get(u.path) ?? [];
             return names.length > 0 ? `import { ${names.join(", ")} } from "${u.path}.js";` : null;
         })
             .filter((line) => line !== null);
+        // Body statements are generated (and marked) starting from *relative*
+        // line 1 — whether the import/prelude sections actually precede them in
+        // the final output depends on `this.usesState`, which genExpr only
+        // finishes deciding partway through this very loop (StateExpr flips it
+        // lazily). Every mark recorded below gets shifted by the real prefix's
+        // line count right after, once that's known for certain.
         const lines = [];
         for (const stmt of program.statements) {
             if (stmt.kind === "InterfaceDecl")
@@ -78,24 +112,41 @@ export class CodeGenerator {
                 // whatever the class's own binding resolves to at runtime; only the
                 // binding itself (import / ambient alias / re-export) needs emitting.
                 const binding = this.genExternBinding(stmt.name, stmt.jsName, stmt.modulePath, stmt.isExported);
-                if (binding)
+                if (binding) {
+                    this.mark(stmt, 0);
                     lines.push(binding);
+                    this.outputLine += countNewlines(binding) + 1;
+                }
                 continue;
             }
             if (stmt.kind === "RawStringDecl") {
                 const content = rawContents.get(stmt.name) ?? "";
-                lines.push(`${stmt.isExported ? "export const" : "const"} ${stmt.name} = ${JSON.stringify(content)};`);
+                const code = `${stmt.isExported ? "export const" : "const"} ${stmt.name} = ${JSON.stringify(content)};`;
+                this.mark(stmt, 0);
+                lines.push(code);
+                this.outputLine += countNewlines(code) + 1;
                 continue;
             }
+            this.mark(stmt, 0);
             let code = this.genStatement(stmt, 0);
             if ((stmt.kind === "ClassDecl" || stmt.kind === "EnumDecl" || stmt.kind === "FunctionDecl") && stmt.isExported) {
                 code = `export ${code}`;
             }
             lines.push(code);
+            this.outputLine += 1; // move past this statement's own last line, to the "\n" join separator
         }
         const body = lines.join("\n") + "\n";
         const sections = [importLines.join("\n"), this.usesState ? STATE_PRELUDE : "", body].filter((s) => s.length > 0);
-        return sections.join("\n\n");
+        const prefixSections = sections.slice(0, -1); // body is always last (see filter above) and always non-empty
+        const prefixText = prefixSections.length > 0 ? prefixSections.join("\n\n") + "\n\n" : "";
+        this.sourceMap.shiftLines(countNewlines(prefixText));
+        const rawCode = sections.join("\n\n");
+        // A file whose only statements were private/unexported/ambient-with-no-
+        // rename externs (nothing else) legitimately generates zero real code —
+        // leave it exactly empty rather than tacking on a comment pointing at a
+        // map with nothing worth mapping.
+        const code = rawCode.trim().length > 0 ? rawCode + `\n//# sourceMappingURL=${outFileName.split("/").pop()}.map\n` : rawCode;
+        return { code, map: this.sourceMap.toJSON() };
     }
     // Builds the code (if any) that creates the local `name` binding for an
     // extern declaration, wiring in `export` when needed:
@@ -179,11 +230,30 @@ export class CodeGenerator {
         }
         return code;
     }
+    // Entry: `outputLine` is the line the caller's own `{` is being appended
+    // to (a block never starts its own fresh line — see e.g. genIf's ` else `
+    // continuing straight on from the previous block's own closing `}`).
+    // Exit: `outputLine` is left AT this block's own closing-`}` line (not one
+    // past it), so a caller that continues on the same line (`} else {`,
+    // `} catch (e) {`) doesn't need to undo anything, and one that doesn't
+    // (the statement/member loops below) just adds one more line itself.
     genBlock(block, indent) {
         const pad = this.indentStr(indent);
-        if (block.statements.length === 0)
+        if (block.statements.length === 0) {
+            this.outputLine += 1; // the "\n" between "{" and the closing pad}
             return `{\n${pad}}`;
-        const body = block.statements.map((s) => this.genStatement(s, indent + 1)).join("\n");
+        }
+        const memberCol = this.indentStr(indent + 1).length;
+        this.outputLine += 1; // "\n" after "{", moving to the first statement's line
+        const pieces = block.statements.map((s, i) => {
+            this.mark(s, memberCol);
+            const text = this.genStatement(s, indent + 1);
+            if (i < block.statements.length - 1)
+                this.outputLine += 1; // "\n" before the next statement
+            return text;
+        });
+        this.outputLine += 1; // "\n" before the closing pad}
+        const body = pieces.join("\n");
         return `{\n${body}\n${pad}}`;
     }
     genIf(stmt, indent) {
@@ -205,26 +275,48 @@ export class CodeGenerator {
         const prefix = decl.isAsync ? "async function" : "function";
         return `${pad}${prefix} ${decl.name}(${params}) ${this.genBlock(decl.body, indent).trimStart()}`;
     }
+    // Same entry/exit `outputLine` convention as genBlock. The one difference:
+    // members are separated by a full blank line (`.join("\n\n")`), so each
+    // non-last member advances by 2, not 1. Marking has to happen immediately
+    // before each member's *own* generation call (a constructor/method body
+    // can itself contain nested blocks that advance `outputLine` further), so
+    // member sources are built as `{ node, build }` pairs and only invoked
+    // inside the loop below, not gathered as plain strings up front.
     genClass(decl, indent) {
         const pad = this.indentStr(indent);
         // The base list mixes an optional superclass with interface names (checker-validated);
         // only the non-interface entry, if any, becomes a JS `extends` clause.
         const superclass = decl.baseList.find((n) => !this.interfaceNames.has(n)) ?? null;
         const header = superclass ? `class ${decl.name} extends ${superclass} {` : `class ${decl.name} {`;
-        const parts = [];
         const memberPad = this.indentStr(indent + 1);
+        const memberCol = memberPad.length;
+        const sources = [];
         for (const field of decl.fields) {
             if (field.isStatic)
-                parts.push(`${memberPad}static ${field.name} = ${this.genExpr(field.initializer)};`);
+                sources.push({ node: field, build: () => `${memberPad}static ${field.name} = ${this.genExpr(field.initializer)};` });
         }
         if (decl.constructor) {
-            parts.push(this.genConstructor(decl.constructor, indent + 1));
+            const ctor = decl.constructor;
+            sources.push({ node: ctor, build: () => this.genConstructor(ctor, indent + 1) });
         }
         for (const method of decl.methods) {
             const params = method.params.map((p) => p.name).join(", ");
             const prefix = `${method.isStatic ? "static " : ""}${method.isAsync ? "async " : ""}`;
-            parts.push(`${memberPad}${prefix}${method.name}(${params}) ${this.genBlock(method.body, indent + 1).trimStart()}`);
+            sources.push({ node: method, build: () => `${memberPad}${prefix}${method.name}(${params}) ${this.genBlock(method.body, indent + 1).trimStart()}` });
+        }
+        if (sources.length === 0) {
+            this.outputLine += 2; // "\n" after header, "\n" before the closing pad}
+            return `${pad}${header}\n\n${pad}}`;
         }
+        this.outputLine += 1; // "\n" after header, moving to the first member's line
+        const parts = sources.map((m, i) => {
+            this.mark(m.node, memberCol);
+            const text = m.build();
+            if (i < sources.length - 1)
+                this.outputLine += 2; // blank line before the next member
+            return text;
+        });
+        this.outputLine += 1; // "\n" before the closing pad}
         const body = parts.join("\n\n");
         return `${pad}${header}\n${body}\n${pad}}`;
     }
@@ -235,14 +327,36 @@ export class CodeGenerator {
     genConstructor(ctor, indent) {
         const pad = this.indentStr(indent);
         const bodyPad = this.indentStr(indent + 1);
+        const bodyCol = bodyPad.length;
         const params = ctor.params.map((p) => p.name).join(", ");
+        // `super(...)` (if any) has no AST statement node of its own to mark —
+        // it's synthesized from `ctor.baseArgs`, a plain expression list, not a
+        // Statement — so it's the one line in a constructor body that goes
+        // unmapped; every real statement after it still gets its own mark.
+        const hasSuper = ctor.baseArgs !== null;
+        const totalLines = (hasSuper ? 1 : 0) + ctor.body.statements.length;
+        if (totalLines === 0) {
+            this.outputLine += 1; // "\n" before the closing pad}
+            return `${pad}constructor(${params}) {\n${pad}}`;
+        }
+        this.outputLine += 1; // "\n" after "{", moving to the first line
         const lines = [];
-        if (ctor.baseArgs) {
+        let emitted = 0;
+        if (hasSuper) {
             lines.push(`${bodyPad}super(${ctor.baseArgs.map((a) => this.genExpr(a)).join(", ")});`);
+            emitted++;
+            if (emitted < totalLines)
+                this.outputLine += 1;
+        }
+        for (const s of ctor.body.statements) {
+            this.mark(s, bodyCol);
+            lines.push(this.genStatement(s, indent + 1));
+            emitted++;
+            if (emitted < totalLines)
+                this.outputLine += 1;
         }
-        lines.push(...ctor.body.statements.map((s) => this.genStatement(s, indent + 1)));
-        const bodyStr = lines.length > 0 ? `{\n${lines.join("\n")}\n${pad}}` : `{\n${pad}}`;
-        return `${pad}constructor(${params}) ${bodyStr}`;
+        this.outputLine += 1; // "\n" before the closing pad}
+        return `${pad}constructor(${params}) {\n${lines.join("\n")}\n${pad}}`;
     }
     // ---------- expressions ----------
     // genExpr wraps an assignment in parens unconditionally (`(x = y)`), since
@@ -316,7 +430,19 @@ export class CodeGenerator {
     genInterpolatedString(expr) {
         const escapeText = (text) => text.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\$\{/g, "\\${");
         const body = expr.parts
-            .map((part) => (part.kind === "Text" ? escapeText(part.text) : `\${${this.genExpr(part.expression)}}`))
+            .map((part) => {
+            if (part.kind === "Text") {
+                // A `\n` escape in the source literal is already a real newline
+                // character in `part.text` by the time it reaches codegen (the
+                // lexer resolves it) — it lands verbatim in the JS template
+                // literal too (backticks support real embedded newlines), so
+                // `outputLine` has to account for it or every mark recorded after
+                // this point in the file would be off.
+                this.outputLine += countNewlines(part.text);
+                return escapeText(part.text);
+            }
+            return `\${${this.genExpr(part.expression)}}`;
+        })
             .join("");
         return `\`${body}\``;
     }
@@ -348,15 +474,31 @@ export class CodeGenerator {
         const jsProperty = expr.property === "Length" ? "length" : MEMBER_METHOD_MAP[expr.property] ?? expr.property;
         return `${this.genExpr(expr.object)}.${jsProperty}`;
     }
+    // Each arm gets its own mark, at the line its own `if`/`else` opens on —
+    // MatchArm carries `line`/`col` even though its pattern variants don't
+    // (see ast.ts). One known v1 imprecision, same spirit as the rest of this
+    // file's statement-level (not full-expression) granularity: if an arm's
+    // *result* expression itself contains a nested multi-line construct (a
+    // lambda with a block body, or another `match`), the fixed "+1 line" this
+    // method advances by per template line undercounts, and marks recorded
+    // after that arm land one or more lines early. Rare in practice (a match
+    // arm's result is usually a short expression), not attempted here.
     genMatch(expr) {
         const subjectVar = `__subject${this.matchCounter++}`;
-        const lines = [`(() => {`, `  const ${subjectVar} = ${this.genExpr(expr.subject)};`];
+        this.outputLine += 1; // "\n" after "(() => {", moving to the "const subjectN = ..." line
+        const subjectText = this.genExpr(expr.subject);
+        const lines = [`(() => {`, `  const ${subjectVar} = ${subjectText};`];
+        this.outputLine += 1; // "\n" before the first arm's own line
         let emittedIf = false;
         expr.arms.forEach((arm) => {
+            this.mark(arm, 2);
             if (arm.pattern.kind === "WildcardPattern") {
                 lines.push(emittedIf ? `  else {` : `  if (true) {`);
+                this.outputLine += 1;
                 lines.push(`    return ${this.genExpr(arm.result)};`);
+                this.outputLine += 1;
                 lines.push(`  }`);
+                this.outputLine += 1;
                 emittedIf = true;
                 return;
             }
@@ -364,8 +506,11 @@ export class CodeGenerator {
                 ? `new RegExp(${JSON.stringify(arm.pattern.source)}).test(${subjectVar})`
                 : arm.pattern.values.map((v) => `${subjectVar} === ${this.genExpr(v)}`).join(" || ");
             lines.push(`  ${emittedIf ? "else if" : "if"} (${condition}) {`);
+            this.outputLine += 1;
             lines.push(`    return ${this.genExpr(arm.result)};`);
+            this.outputLine += 1;
             lines.push(`  }`);
+            this.outputLine += 1;
             emittedIf = true;
         });
         lines.push(`})()`);

package/dist/modules.js

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from "node:fs";
-import { dirname, relative, resolve } from "node:path";
+import { basename, dirname, relative, resolve } from "node:path";
 import { Lexer } from "./lexer.js";
 import { Parser } from "./parser.js";
 import { Checker, emptyModuleExports } from "./checker.js";
@@ -157,7 +157,7 @@ export function loadModuleGraph(entryAbsPath, fileOverrides) {
 export function compileGraph(entryAbsPath, fileOverrides) {
     const { modules, order, entryMissing } = loadModuleGraph(entryAbsPath, fileOverrides);
     if (entryMissing) {
-        return { success: false, entryMissing: true, modules, order, outputs: new Map() };
+        return { success: false, entryMissing: true, modules, order, outputs: new Map(), sourceMaps: new Map() };
     }
     const exportsByModule = new Map();
     const rawContentsByModule = new Map();
@@ -219,9 +219,10 @@ export function compileGraph(entryAbsPath, fileOverrides) {
         rawContentsByModule.set(absPath, checker.getRawContents());
     }
     if (hasErrors) {
-        return { success: false, entryMissing: false, modules, order, outputs: new Map() };
+        return { success: false, entryMissing: false, modules, order, outputs: new Map(), sourceMaps: new Map() };
     }
     const outputs = new Map();
+    const sourceMaps = new Map();
     for (const absPath of order) {
         const mod = modules.get(absPath);
         const usingExports = new Map();
@@ -235,7 +236,13 @@ export function compileGraph(entryAbsPath, fileOverrides) {
                 usingExports.set(u.path, [...importableTypeNames, ...depExports.functions.keys(), ...depExports.externValues.keys()]);
             }
         }
-        outputs.set(absPath, new CodeGenerator().generate(mod.program, usingExports, rawContentsByModule.get(absPath) ?? new Map()));
+        // Just the basename, not a cwd-relative path — the .js.map file always
+        // lands right next to its .ks/.js siblings (ks build writes output in
+        // place), so "sources" has to resolve relative to *that* directory, not
+        // wherever the compiler happened to be invoked from.
+        const { code, map } = new CodeGenerator().generate(mod.program, usingExports, rawContentsByModule.get(absPath) ?? new Map(), basename(absPath), mod.source);
+        outputs.set(absPath, code);
+        sourceMaps.set(absPath, map);
     }
-    return { success: true, entryMissing: false, modules, order, outputs };
+    return { success: true, entryMissing: false, modules, order, outputs, sourceMaps };
 }

package/dist/sourcemap.js

@@ -0,0 +1,113 @@
+// A minimal, self-contained source-map v3 (base64 VLQ) encoder — hand-rolled
+// rather than pulling in the `source-map` package, to keep kopscript at zero
+// runtime dependencies (see README.md/package.json). No imports beyond this
+// file's own code; nothing here reads or writes the filesystem.
+//
+// Spec: https://sourcemaps.info/spec.html — the encoding this file
+// implements (VLQ digit format, per-line column reset) is described there.
+const BASE64_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const VLQ_BASE_SHIFT = 5;
+const VLQ_BASE = 1 << VLQ_BASE_SHIFT; // 32 — 5 data bits per base64 digit
+const VLQ_BASE_MASK = VLQ_BASE - 1; // 0x1F
+const VLQ_CONTINUATION_BIT = VLQ_BASE; // 0x20 — set on every digit but the last
+// Sign-and-magnitude, not two's complement: the sign lives in the low bit of
+// the shifted value, not as a separate leading digit — this is what makes a
+// small negative delta (the common case for a line's *second* segment
+// resetting a column back down) encode just as compactly as a small
+// positive one.
+function toSignedVLQ(value) {
+    return value < 0 ? (-value << 1) + 1 : value << 1;
+}
+function encodeVLQValue(value) {
+    let vlq = toSignedVLQ(value);
+    let result = "";
+    do {
+        let digit = vlq & VLQ_BASE_MASK;
+        vlq >>>= VLQ_BASE_SHIFT;
+        if (vlq > 0)
+            digit |= VLQ_CONTINUATION_BIT;
+        result += BASE64_CHARS[digit];
+    } while (vlq > 0);
+    return result;
+}
+// Encodes one mapping segment's fields (already converted to deltas by the
+// caller) as a contiguous run of VLQ digit-groups — e.g. `[0, 0, 0, 0]` (the
+// "no change from the previous segment" case) always encodes to `"AAAA"`.
+export function encodeVLQ(values) {
+    return values.map(encodeVLQValue).join("");
+}
+// Builds one file's source-map v3 JSON incrementally, one `addMapping` call
+// per source position worth recording (see codegen.ts for how call sites are
+// chosen — statement-level, not full expression/column granularity). Only
+// ever describes a single source file per generated file, matching
+// kopscript's one-.ks-file-in, one-.js-file-out compilation model.
+export class SourceMapBuilder {
+    constructor(fileName, sourceFileName, sourceContent) {
+        // `mappings` is one comma-joined segment-string per GENERATED line,
+        // joined with `;` at the end — an empty array entry for a generated line
+        // with no recorded mapping produces the required-but-empty group between
+        // two semicolons, not a skipped line (that would shift every later line's
+        // meaning, since position in the `;`-separated list *is* the line number).
+        this.lineGroups = [];
+        // Per the spec, `generatedColumn` deltas reset to being measured from 0
+        // at the start of every generated line, but `sourceLine`/`sourceColumn`
+        // deltas accumulate across the *entire* file, never resetting — tracking
+        // both correctly is the one genuinely easy-to-get-wrong part of this.
+        this.prevGeneratedColumn = 0;
+        this.prevSourceLine = 0;
+        this.prevSourceColumn = 0;
+        this.fileName = fileName;
+        this.sourceFileName = sourceFileName;
+        this.sourceContent = sourceContent;
+    }
+    lineGroup(generatedLine) {
+        const index = generatedLine - 1;
+        while (this.lineGroups.length <= index)
+            this.lineGroups.push([]);
+        return this.lineGroups[index];
+    }
+    // `generatedLine`/`sourceLine`/`sourceColumn` are 1-indexed (kopscript's
+    // own convention throughout the lexer/parser/AST — see lexer.ts). Per the
+    // source-map spec itself, everything is 0-indexed in the encoded output;
+    // the `- 1`s below are that conversion, done in exactly one place.
+    // `generatedColumn` is the real (already 0-indexed) character offset from
+    // the start of its generated line — there's no separate convention to
+    // convert there since "0 spaces of indent" already means column 0.
+    addMapping(generatedLine, generatedColumn, sourceLine, sourceColumn) {
+        const group = this.lineGroup(generatedLine);
+        if (group.length === 0)
+            this.prevGeneratedColumn = 0; // new line: column deltas restart at 0
+        const zSourceLine = sourceLine - 1;
+        const zSourceColumn = sourceColumn - 1;
+        group.push(encodeVLQ([
+            generatedColumn - this.prevGeneratedColumn,
+            0, // sourceIndex delta — always 0, exactly one source file per map
+            zSourceLine - this.prevSourceLine,
+            zSourceColumn - this.prevSourceColumn,
+        ]));
+        this.prevGeneratedColumn = generatedColumn;
+        this.prevSourceLine = zSourceLine;
+        this.prevSourceColumn = zSourceColumn;
+    }
+    // Prepends `count` empty line-groups — for when marks were recorded
+    // relative to a chunk's own start (line 1) before it was known how many
+    // lines of *other* content would end up preceding that chunk in the final
+    // output. See codegen.ts's `generate()`: body statements are marked
+    // before it's known whether the `state<T>` prelude will precede them.
+    shiftLines(count) {
+        if (count <= 0)
+            return;
+        this.lineGroups.unshift(...Array.from({ length: count }, () => []));
+    }
+    toJSON() {
+        const mappings = this.lineGroups.map((segments) => segments.join(",")).join(";");
+        return JSON.stringify({
+            version: 3,
+            file: this.fileName,
+            sources: [this.sourceFileName],
+            sourcesContent: [this.sourceContent],
+            names: [],
+            mappings,
+        });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kopscript",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "KopScript: a small OOP, strongly-typed language that transpiles to JavaScript, with generics and nullable types",
   "type": "module",
   "license": "MIT",