pll-python 0.1.0 → 0.1.2

package/cli.cjs

@@ -24,1329 +24,1616 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // src/cli/main.ts
-var path6 = __toESM(require("node:path"));
+var path7 = __toESM(require("node:path"));
 
-// src/cli/runtime.ts
-var path2 = __toESM(require("node:path"));
+// src/cli/examplar.ts
+var fs3 = __toESM(require("node:fs/promises"));
+var path3 = __toESM(require("node:path"));
 
-// src/desktop/pyodideRuntime.ts
-var fs = __toESM(require("node:fs"));
-var path = __toESM(require("node:path"));
-var import_node_worker_threads = require("node:worker_threads");
+// src/cli/run.ts
+var fs2 = __toESM(require("node:fs/promises"));
+var path2 = __toESM(require("node:path"));
 
-// src/common/deliverResult.ts
-function deliverRunResult(result, onEvent, fileName) {
-  if (result.displays) {
-    for (const display of result.displays) {
-      deliverDisplay(display, onEvent, fileName);
-    }
-  }
-  if (result.result_repr !== null && result.result_repr !== void 0) {
-    onEvent({ kind: "result", repr: result.result_repr });
-  }
-  if (!result.ok && result.error_type) {
-    onEvent({
-      kind: "error",
-      errorType: result.error_type,
-      message: result.error_message ?? "",
-      traceback: result.traceback ?? "",
-      lineNumber: result.line_number,
-      column: result.column,
-      fileName
-    });
+// src/common/analyzers/static/shadowingExplainer.ts
+function outerScopeNoun(kind) {
+  switch (kind) {
+    case "module":
+      return "the file";
+    case "function":
+    case "lambda":
+      return "an enclosing function";
+    case "class":
+      return "an enclosing class";
+    case "comprehension":
+      return "an enclosing comprehension";
+    default:
+      return "an outer scope";
   }
-  onEvent({ kind: "done" });
 }
-function deliverDisplay(display, onEvent, fileName) {
-  switch (display.type) {
-    case "stdout":
-      onEvent({ kind: "stdout", text: display.text });
-      break;
-    case "stderr":
-      onEvent({ kind: "stderr", text: display.text });
-      break;
+function explainShadowing(raw, level, fileName) {
+  const name = raw.name_token ?? "this name";
+  const outerLine = raw.outer_line_number ?? null;
+  const outerNoun = outerScopeNoun(raw.outer_scope_kind);
+  const knownOuterLine = outerLine !== null && outerLine > 0;
+  const outerHint = knownOuterLine ? ` (first defined on line ${outerLine}, in ${outerNoun})` : ` in ${outerNoun}`;
+  return {
+    id: "shadowing",
+    errorType: "Shadowing",
+    message: raw.message,
+    headline: `\`${name}\` is already defined${outerHint}.`,
+    howToFix: [
+      `Rename the inner \`${name}\` to something distinct (e.g. \`${name}_inner\`, \`local_${name}\`, or whatever describes its role).`,
+      `Or, if you want to use the outer \`${name}\`, just read it directly without making a new variable.`
+    ],
+    fileName,
+    lineNumber: raw.line_number,
+    column: raw.column,
+    nameToken: raw.name_token,
+    severity: "error",
+    raw: JSON.stringify(raw),
+    origin: "static",
+    level
+  };
+}
+function explainShadowingBuiltin(raw, level, fileName) {
+  const name = raw.name_token ?? "this name";
+  const headline = `\`${name}\` is the name of a Python built-in.`;
+  return {
+    id: "shadowing-builtin",
+    errorType: "Shadowing",
+    message: raw.message,
+    headline,
+    howToFix: [
+      `Pick a different name. Common patterns: \`my_${name}\`, \`${name}_value\`, \`${name}s\` (plural), or a more specific noun describing what this value represents.`
+    ],
+    fileName,
+    lineNumber: raw.line_number,
+    column: raw.column,
+    nameToken: raw.name_token,
+    severity: "error",
+    raw: JSON.stringify(raw),
+    origin: "static",
+    level
+  };
+}
+function libraryNoun(library) {
+  switch (library) {
     case "image":
-      onEvent({
-        kind: "image",
-        svg: display.data,
-        width: display.width,
-        height: display.height,
-        source: fileName
-      });
-      break;
-    case "reactor":
-      onEvent({
-        kind: "reactor",
-        id: display.id,
-        title: display.title,
-        tickRate: display.tick_rate,
-        ticking: display.ticking,
-        wantsKeys: display.wants_keys,
-        wantsMouse: display.wants_mouse,
-        register: display.register,
-        frame: display.frame,
-        index: display.index,
-        length: display.length,
-        atEnd: display.at_end,
-        stopped: display.stopped,
-        valueRepr: display.value_repr
-      });
-      break;
+      return "the image library";
     case "table":
-      onEvent({
-        kind: "table",
-        columns: display.columns,
-        rows: display.rows,
-        rowCount: display.row_count,
-        shownCount: display.shown_count,
-        truncated: display.truncated,
-        source: fileName
-      });
-      break;
+      return "the table library";
+    case "reactor":
+      return "the reactor library";
+    default:
+      return "the PLL libraries";
   }
 }
-function asPlain(value) {
-  if (value instanceof Map) {
-    const obj = {};
-    for (const [k, v] of value.entries()) {
-      obj[String(k)] = asPlain(v);
-    }
-    return obj;
-  }
-  if (Array.isArray(value)) {
-    return value.map(asPlain);
-  }
-  return value;
+function explainShadowingLibrary(raw, level, fileName) {
+  const name = raw.name_token ?? "this name";
+  const noun = libraryNoun(raw.library);
+  const headline = `\`${name}\` is already defined by ${noun}.`;
+  return {
+    id: "shadowing-library",
+    errorType: "Shadowing",
+    message: raw.message,
+    headline,
+    howToFix: [
+      `Pick a different name for your definition - for example \`my_${name}\`, \`${name}_value\`, or a word that describes what yours represents.`,
+      `If you meant to use the library's \`${name}\`, call it directly instead of defining a new \`${name}\` of your own.`
+    ],
+    fileName,
+    lineNumber: raw.line_number,
+    column: raw.column,
+    nameToken: raw.name_token,
+    severity: "error",
+    raw: JSON.stringify(raw),
+    origin: "static",
+    level
+  };
 }
-function adaptTestCase(raw) {
-  const row = asPlain(raw) ?? {};
-  const line = row.line_number;
+
+// src/common/analyzers/static/reassignmentExplainer.ts
+function explainReassignment(raw, level, fileName) {
+  const name = raw.name_token ?? "this name";
+  const firstLine = raw.first_line_number ?? null;
+  const firstLineHint = firstLine !== null && firstLine > 0 ? ` (first assigned on line ${firstLine})` : "";
   return {
-    name: String(row.name ?? ""),
-    outcome: String(row.outcome ?? "failed"),
-    lineNumber: typeof line === "number" ? line : null,
-    message: row.message == null ? null : String(row.message),
-    stdout: row.stdout == null ? null : String(row.stdout)
+    id: "reassignment",
+    errorType: "Reassignment",
+    message: raw.message,
+    headline: `\`${name}\` is already assigned${firstLineHint}.`,
+    howToFix: level === "intermediate" ? [
+      `If you want a different value, give it a different name (e.g. \`${name}_doubled\`, \`new_${name}\`, \`${name}2\`).`,
+      `If you're trying to update a value (\`x = x + 1\`, accumulators, running totals), wrap the work in a function and rebind \`${name}\` from the function's return value: \`${name} = compute_${name}(...)\`.`
+    ] : [
+      `If you want a different value, give it a different name (e.g. \`${name}_doubled\`, \`new_${name}\`, \`${name}2\`).`,
+      `If you're trying to update a value (\`x = x + 1\`, accumulators, running totals), use a built-in like \`sum(...)\`, \`max(...)\`, or a small helper function that returns the new value instead.`
+    ],
+    fileName,
+    lineNumber: raw.line_number,
+    column: raw.column,
+    nameToken: raw.name_token,
+    severity: "error",
+    raw: JSON.stringify(raw),
+    origin: "static",
+    level
   };
 }
-function deliverTestResult(result, onEvent, fileName) {
-  if (result.internal_error && result.error_type) {
-    onEvent({
-      kind: "error",
-      errorType: result.error_type,
-      message: result.error_message ?? "",
-      traceback: result.traceback ?? "",
-      lineNumber: result.line_number,
-      column: result.column,
-      fileName
-    });
-    onEvent({ kind: "done" });
-    return;
+
+// src/common/analyzers/static/disallowedKeywordExplainer.ts
+function explainDisallowedKeyword(raw, level, fileName) {
+  const keyword = raw.keyword === "nonlocal" ? "nonlocal" : "global";
+  const names = Array.isArray(raw.names) ? raw.names : [];
+  const formattedNames = names.map((n) => `\`${n}\``).join(", ");
+  const namesPhrase = formattedNames.length > 0 ? ` ${formattedNames}` : "";
+  const headline = `\`${keyword}\` is not allowed at the ${level} level.`;
+  const howToFix = [];
+  if (keyword === "global") {
+    howToFix.push(
+      `Pass${namesPhrase || " the value"} into this function as an argument instead of declaring it \`global\`.`,
+      `If the function needs to *change* a value, return the new value and let the caller decide what to do with it (e.g. \`x = update(x)\`).`
+    );
+  } else {
+    howToFix.push(
+      `Return${namesPhrase || " the new value"} from this inner function and have the outer function rebind it explicitly (e.g. \`x = inner(x)\`).`,
+      `If the inner function only needs to *read* the outer name, just use it directly - you don't need \`nonlocal\` for that.`
+    );
   }
-  const tests = Array.isArray(result.tests) ? result.tests.map(adaptTestCase) : [];
-  onEvent({
-    kind: "testReport",
+  return {
+    id: "disallowed-keyword",
+    errorType: "DisallowedKeyword",
+    message: raw.message,
+    headline,
+    howToFix,
     fileName,
-    passed: result.passed ?? 0,
-    failed: result.failed ?? 0,
-    skipped: result.skipped ?? 0,
-    errors: result.errors ?? 0,
-    tests
-  });
-  onEvent({ kind: "done" });
+    lineNumber: raw.line_number,
+    column: raw.column,
+    nameToken: raw.name_token,
+    severity: "error",
+    raw: JSON.stringify(raw),
+    origin: "static",
+    level
+  };
 }
 
-// src/common/interruptBuffer.ts
-var INTERRUPT_SAB_BYTES = 1;
-var INTERRUPT_SIGINT = 2;
-function tryCreateInterruptBuffer() {
-  try {
-    return new SharedArrayBuffer(INTERRUPT_SAB_BYTES);
-  } catch {
-    return null;
-  }
+// src/common/analyzers/static/registry.ts
+var explainers = {
+  shadowing: explainShadowing,
+  "shadowing-builtin": explainShadowingBuiltin,
+  "shadowing-library": explainShadowingLibrary,
+  reassignment: explainReassignment,
+  "disallowed-keyword": explainDisallowedKeyword
+};
+function fallbackExplainer(raw, level, fileName) {
+  return {
+    id: raw.id,
+    errorType: raw.error_type || "StaticError",
+    message: raw.message,
+    headline: raw.message,
+    howToFix: [],
+    fileName,
+    lineNumber: raw.line_number,
+    column: raw.column,
+    nameToken: raw.name_token,
+    severity: "error",
+    raw: JSON.stringify(raw),
+    origin: "static",
+    level
+  };
 }
-function signalInterrupt(sab) {
-  Atomics.store(new Uint8Array(sab), 0, INTERRUPT_SIGINT);
+function enrichStaticFindings(rawFindings, level, fileName) {
+  return rawFindings.map((raw) => {
+    const explainer = explainers[raw.id] ?? fallbackExplainer;
+    return explainer(raw, level, fileName);
+  });
 }
 
-// src/common/stdinBuffer.ts
-var STDIN_SAB_BYTES = 64 * 1024;
-var STDIN_STATE_INDEX = 0;
-var STDIN_LENGTH_INDEX = 1;
-var STDIN_PAYLOAD_OFFSET = 8;
-var STDIN_STATE_LINE = 1;
-var STDIN_STATE_EOF = 2;
-function tryCreateStdinBuffer() {
-  try {
-    return new SharedArrayBuffer(STDIN_SAB_BYTES);
-  } catch {
-    return null;
+// src/common/errors/pythonErrorParser.ts
+var NON_USER_FRAME = [
+  "<exec>",
+  "/pll_vendor",
+  "site-packages",
+  "/lib/python",
+  "_pytest",
+  "pluggy"
+];
+function userTracebackFrames(traceback) {
+  const frames = [];
+  for (const raw of traceback.split(/\r?\n/)) {
+    const m = raw.match(/^\s*File "([^"]+)", line (\d+)(?:, in (\S+))?/);
+    if (!m) continue;
+    const fileName = m[1];
+    if (NON_USER_FRAME.some((token) => fileName.includes(token))) continue;
+    frames.push({
+      fileName,
+      line: parseInt(m[2], 10),
+      functionName: m[3] && m[3] !== "<module>" ? m[3] : null
+    });
   }
+  return frames;
 }
-function writeStdinLine(sab, line) {
-  const state = new Int32Array(sab);
-  if (line === null) {
-    Atomics.store(state, STDIN_STATE_INDEX, STDIN_STATE_EOF);
-    Atomics.notify(state, STDIN_STATE_INDEX);
-    return;
+function parsePythonError(rawTraceback) {
+  const traceback = rawTraceback.trimEnd();
+  const lines = traceback.split(/\r?\n/);
+  let errorType = "Error";
+  let message = traceback;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    const m = line.match(/^([A-Za-z_][A-Za-z0-9_.]*):\s?(.*)$/);
+    if (m && !line.startsWith(" ")) {
+      errorType = m[1];
+      message = m[2];
+      break;
+    }
+    if (line.match(/^[A-Za-z_][A-Za-z0-9_.]*$/) && !line.startsWith(" ")) {
+      errorType = line;
+      message = "";
+      break;
+    }
   }
-  const encoded = new TextEncoder().encode(line);
-  const max = sab.byteLength - STDIN_PAYLOAD_OFFSET;
-  const n = Math.min(encoded.length, max);
-  const bytes = new Uint8Array(sab, STDIN_PAYLOAD_OFFSET);
-  bytes.set(encoded.subarray(0, n));
-  Atomics.store(state, STDIN_LENGTH_INDEX, n);
-  Atomics.store(state, STDIN_STATE_INDEX, STDIN_STATE_LINE);
-  Atomics.notify(state, STDIN_STATE_INDEX);
-}
-
-// src/common/workerRuntime.ts
-var WorkerPythonRuntime = class {
-  worker = null;
-  nextId = 1;
-  pending = /* @__PURE__ */ new Map();
-  initPromise = null;
-  stdinBuffer = null;
-  interruptBuffer = null;
-  stdinHandler = null;
-  /** Event sink for the in-flight runFile, so live displays can stream. */
-  live = null;
-  async initialize() {
-    if (!this.initPromise) {
-      this.initPromise = this.doInitialize();
+  let fileName = null;
+  let lineNumber = null;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    const m = line.match(/^\s*File\s+"([^"]+)",\s+line\s+(\d+)/);
+    if (m) {
+      fileName = m[1];
+      lineNumber = parseInt(m[2], 10);
+      break;
     }
-    await this.initPromise;
   }
-  async doInitialize() {
-    const indexUrl = this.resolveIndexUrl();
-    this.worker = this.spawn({
-      onMessage: (msg) => this.handleMessage(msg),
-      onError: (err) => this.rejectAllPending(err)
-    });
-    this.stdinBuffer = tryCreateStdinBuffer();
-    this.interruptBuffer = tryCreateInterruptBuffer();
-    await this.request(
-      {
-        type: "init",
-        indexUrl,
-        ...this.stdinBuffer ? { stdinBuffer: this.stdinBuffer } : {},
-        ...this.interruptBuffer ? { interruptBuffer: this.interruptBuffer } : {}
-      },
-      "ready"
-    );
+  let column = null;
+  if (lineNumber !== null) {
+    for (let i = 0; i < lines.length - 1; i++) {
+      if (/^\s*\^+\s*$/.test(lines[i + 1] ?? "")) {
+        const caretLine = lines[i + 1];
+        const caretIdx = caretLine.indexOf("^");
+        if (caretIdx >= 0) {
+          column = caretIdx;
+        }
+      }
+    }
   }
-  async runFile(request, onEvent) {
-    await this.initialize();
-    this.live = { onEvent, fileName: request.fileName };
-    try {
-      const { result } = await this.request({ type: "runFile", ...request }, "result");
-      deliverRunResult(result, onEvent, request.fileName);
-    } finally {
-      this.live = null;
+  let nameToken = null;
+  if (errorType === "NameError") {
+    const nm = message.match(/name '([^']+)' is not defined/);
+    if (nm) {
+      nameToken = nm[1];
     }
   }
-  async replEval(request, onEvent) {
-    await this.initialize();
-    const { result } = await this.request({ type: "replEval", ...request }, "result");
-    deliverRunResult(result, onEvent, "<repl>");
+  return {
+    errorType,
+    message,
+    traceback,
+    fileName,
+    lineNumber,
+    column,
+    nameToken
+  };
+}
+
+// src/common/errors/nameErrorExplainer.ts
+function explainNameError(parsed) {
+  const name = parsed.nameToken ?? "this name";
+  const didYouMean = extractDidYouMean(parsed.message);
+  const headline = `Python doesn't know what \`${name}\` means.`;
+  const howToFix = [
+    `Check the spelling of \`${name}\` (Python is case-sensitive).`,
+    `Make sure \`${name}\` is defined before this line runs.`,
+    `If \`${name}\` should be text, put it in quotes: \`"${name}"\`.`
+  ];
+  if (didYouMean.length > 0) {
+    howToFix.unshift(
+      `Python suggested: ${didYouMean.map((s) => "`" + s + "`").join(", ")} - try one of those.`
+    );
   }
-  async checkReplComplete(code) {
-    await this.initialize();
-    const { result } = await this.request({ type: "checkSyntax", code }, "syntax");
+  return { headline, howToFix };
+}
+function extractDidYouMean(message) {
+  const m = message.match(/Did you mean:\s*([^?]+)\??/i);
+  if (!m) {
+    return [];
+  }
+  return m[1].split(/,|\bor\b/).map((s) => s.trim().replace(/^['"`]|['"`]$/g, "")).filter((s) => s.length > 0);
+}
+
+// src/common/analyzers/nameErrorAnalyzer.ts
+var nameErrorAnalyzer = {
+  handles: ["NameError"],
+  analyze(input) {
+    const { parsedError, fileName, level } = input;
+    if (parsedError.errorType !== "NameError") {
+      return null;
+    }
+    const explanation = explainNameError(parsedError);
     return {
-      status: result.status,
-      errorType: result.error_type,
-      message: result.message,
-      lineNumber: result.lineno,
-      offset: result.offset
+      id: "name-error",
+      errorType: "NameError",
+      message: parsedError.message,
+      headline: explanation.headline,
+      howToFix: explanation.howToFix,
+      fileName,
+      lineNumber: parsedError.lineNumber,
+      column: parsedError.column,
+      nameToken: parsedError.nameToken,
+      severity: "error",
+      raw: parsedError.traceback,
+      origin: "runtime",
+      level
     };
   }
-  async hasTests(code) {
-    await this.initialize();
-    const { result } = await this.request({ type: "hasTests", code }, "hasTests");
-    return result;
-  }
-  async ensurePackages(code) {
-    await this.initialize();
-    await this.request({ type: "loadPackages", code }, "packagesReady");
-  }
-  async ensurePytest() {
-    await this.initialize();
-    await this.request({ type: "loadPytest" }, "pytestReady");
-  }
-  async runTests(request, onEvent) {
-    await this.initialize();
-    const { result } = await this.request(
-      {
-        type: "runTests",
-        code: request.code,
-        fileName: request.fileName,
-        level: request.level
-      },
-      "testResult"
-    );
-    deliverTestResult(result, onEvent, request.fileName);
-  }
-  async staticAnalyze(request) {
-    await this.initialize();
-    const { result } = await this.request({ type: "staticAnalyze", ...request }, "static");
-    return result ?? [];
-  }
-  async mountWorkspaceFiles(files) {
-    await this.initialize();
-    await this.request({ type: "mountWorkspace", files }, "workspaceReady");
-  }
-  async collectWorkspaceFiles() {
-    await this.initialize();
-    const { files } = await this.request({ type: "collectWorkspace" }, "workspaceFiles");
-    return files;
+};
+
+// src/common/level.ts
+var DEFAULT_LEVEL = "raw";
+var HEADER_RE = /^#\s*level\s+([a-z]+)\s*$/;
+var LEVEL_NAMES = [
+  "raw",
+  "beginner",
+  "intermediate",
+  "advanced"
+];
+function parseLevel(source) {
+  const lines = source.split(/\r?\n/);
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (line.length === 0) {
+      continue;
+    }
+    const match = HEADER_RE.exec(line);
+    if (!match) {
+      return DEFAULT_LEVEL;
+    }
+    const name = match[1];
+    for (const level of LEVEL_NAMES) {
+      if (name === level) return level;
+    }
+    return DEFAULT_LEVEL;
   }
-  async reactorStep(reactorId, event) {
-    await this.initialize();
-    const { result } = await this.request(
-      { type: "reactorStep", reactorId, event },
-      "reactorFrame"
-    );
-    return result;
+  return DEFAULT_LEVEL;
+}
+function levelRejectsBoolAsNumber(level) {
+  return level === "beginner" || level === "intermediate";
+}
+function levelHasStaticChecks(level) {
+  return level === "beginner" || level === "intermediate";
+}
+
+// src/common/errors/typeCheckExplainer.ts
+var FRIENDLY_TYPES = {
+  int: "a whole number",
+  float: "a number",
+  complex: "a complex number",
+  str: "a string",
+  bool: "`True` or `False`",
+  bytes: "bytes",
+  list: "a list",
+  dict: "a dictionary",
+  set: "a set",
+  tuple: "a tuple",
+  None: "`None`",
+  NoneType: "`None`"
+};
+function cleanTypeName(type) {
+  return type.startsWith("__main__.") ? type.slice("__main__.".length) : type;
+}
+function describeType(type) {
+  const name = cleanTypeName(type);
+  if (name === "None" || name === "NoneType") return "`None`";
+  const friendly = FRIENDLY_TYPES[name];
+  return friendly ? `${friendly} (\`${name}\`)` : `\`${name}\``;
+}
+function describeTypes(types) {
+  const described = types.map(describeType);
+  if (described.length === 0) return "a different type";
+  if (described.length === 1) return described[0];
+  return `${described.slice(0, -1).join(", ")} or ${described[described.length - 1]}`;
+}
+function boolAsNumberNote(expected, actual, level) {
+  if (actual !== "bool" || expected.length === 0) return null;
+  if (!expected.some((type) => type === "int" || type === "float")) return null;
+  if (level !== void 0 && !levelRejectsBoolAsNumber(level)) return null;
+  return "At `#level beginner` and `#level intermediate`, `True` and `False` are not accepted as numbers, even though Python counts them as `1` and `0`.";
+}
+function conversionFor(expected, actual) {
+  if (expected.length !== 1 || actual === null) return null;
+  const to = expected[0];
+  const numeric = actual === "int" || actual === "float" || actual === "bool";
+  if (to === "int" && (actual === "str" || actual === "float")) return "int";
+  if (to === "float" && actual === "str") return "float";
+  if (to === "str" && numeric) return "str";
+  return null;
+}
+var ELEMENT_RE = /^(item \d+|key .+|value of key .+|\[.+\]) of (.+)$/;
+function membersPhrase(element) {
+  if (element.startsWith("the value for key")) return "every value in";
+  if (element.startsWith("key ")) return "every key in";
+  return "every item in";
+}
+function describeElement(element) {
+  if (element.startsWith("value of key ")) {
+    return `the value for key ${element.slice("value of key ".length)}`;
   }
-  async reactorSeek(reactorId, index) {
-    await this.initialize();
-    const { result } = await this.request(
-      { type: "reactorSeek", reactorId, index },
-      "reactorFrame"
-    );
-    return result;
+  if (element.startsWith("[")) return "one of the values";
+  return element;
+}
+function parseTypeCheckMessage(message) {
+  const unknown = {
+    kind: "unknown",
+    name: null,
+    element: null,
+    actual: null,
+    expected: []
+  };
+  const lines = message.split(/\r?\n/);
+  const first = lines[0].trim();
+  let expected = [];
+  let subject = null;
+  const unionAt = first.indexOf(" did not match any element in the union:");
+  if (unionAt >= 0) {
+    subject = first.slice(0, unionAt);
+    for (const raw of lines.slice(1)) {
+      const m = raw.match(/^\s*([A-Za-z_][A-Za-z0-9_.\[\], ]*):/);
+      if (m) expected.push(m[1].trim());
+    }
+  } else {
+    const predicates = [
+      [/^(.*) is not an instance of (.+)$/, (m) => [m[2]]],
+      [/^(.*) is neither float or int$/, () => ["float"]],
+      [/^(.*) is not None$/, () => ["None"]],
+      [/^(.*) is not a ([A-Za-z_][A-Za-z0-9_]*)$/, (m) => [m[2]]]
+    ];
+    for (const [re, pick] of predicates) {
+      const m = first.match(re);
+      if (m) {
+        subject = m[1];
+        expected = pick(m);
+        break;
+      }
+    }
   }
-  async reactorDispose(reactorId) {
-    await this.initialize();
-    await this.request({ type: "reactorDispose", reactorId }, "reactorDisposed");
+  if (subject === null) return unknown;
+  let actual = null;
+  const withActual = subject.match(/^(.*) \(([^()]*)\)$/);
+  if (withActual) {
+    subject = withActual[1];
+    actual = withActual[2];
   }
-  interrupt() {
-    if (!this.interruptBuffer) {
-      return false;
-    }
-    signalInterrupt(this.interruptBuffer);
-    return true;
+  let element = null;
+  const elementMatch = subject.match(ELEMENT_RE);
+  if (elementMatch) {
+    element = describeElement(elementMatch[1]);
+    subject = elementMatch[2];
   }
-  setStdinHandler(handler) {
-    this.stdinHandler = handler;
+  if (subject === "the return value") {
+    return { kind: "return", name: null, element, actual, expected };
   }
-  dispose() {
-    this.worker?.terminate();
-    this.worker = null;
-    this.initPromise = null;
-    this.stdinBuffer = null;
-    this.interruptBuffer = null;
-    this.live = null;
-    this.rejectAllPending(new Error("Runtime disposed"));
+  const argument = subject.match(/^argument "(.+)"$/);
+  if (argument) {
+    return { kind: "argument", name: argument[1], element, actual, expected };
   }
-  /** Send `msg` and resolve with the reply, asserting it is of type `expected`. */
-  async request(msg, expected) {
-    const worker = this.worker;
-    if (!worker) {
-      throw new Error("Worker not initialized");
-    }
-    const id = this.nextId++;
-    const reply = await new Promise((resolve3, reject) => {
-      this.pending.set(id, { resolve: resolve3, reject });
-      worker.post({ id, ...msg });
-    });
-    if (reply.type !== expected) {
-      throw new Error(`Pyodide worker replied "${reply.type}", expected "${expected}"`);
-    }
-    return reply;
+  const assigned = subject.match(/^value assigned to (.+)$/);
+  if (assigned) {
+    return { kind: "variable", name: assigned[1], element, actual, expected };
   }
-  handleMessage(msg) {
-    if (msg.type === "display") {
-      if (this.live) {
-        deliverDisplay(msg.payload, this.live.onEvent, this.live.fileName);
-      }
-      return;
-    }
-    if (msg.type === "stdinRequest") {
-      void this.handleStdinRequest();
-      return;
-    }
-    const pending = this.pending.get(msg.id);
-    if (!pending) {
-      return;
+  return { ...unknown, element, actual, expected };
+}
+function explainTypeCheckError(message, functionName, level) {
+  const parsed = parseTypeCheckMessage(message);
+  const wanted = describeTypes(parsed.expected);
+  const owner = functionName ? `\`${functionName}\`` : "this function";
+  const named = parsed.name ? `\`${parsed.name}\`` : "a value";
+  const convert = conversionFor(parsed.expected, parsed.actual);
+  const boolNote = boolAsNumberNote(parsed.expected, parsed.actual, level);
+  const annotation = parsed.expected.length === 1 ? cleanTypeName(parsed.expected[0]) : null;
+  if (parsed.kind === "argument") {
+    if (parsed.element) {
+      return {
+        headline: `${owner} expects ${membersPhrase(parsed.element)} ${named} to be ${wanted}, but ${parsed.element} is not.`,
+        howToFix: [
+          `Look at ${parsed.element} of the ${parsed.actual ?? "value"} you passed for ${named}.`,
+          "Every one has to match the annotation, not just the first."
+        ]
+      };
     }
-    this.pending.delete(msg.id);
-    if (msg.type === "error") {
-      pending.reject(new Error(msg.message));
-    } else {
-      pending.resolve(msg);
+    const got = parsed.actual ? `, but got ${describeType(parsed.actual)}` : "";
+    const howToFix = [`Check the value you passed for ${named} on this line.`];
+    if (boolNote) howToFix.push(boolNote);
+    if (convert) {
+      howToFix.push(`If it should be ${wanted}, convert it with \`${convert}(...)\`.`);
     }
-  }
-  rejectAllPending(err) {
-    for (const pending of this.pending.values()) {
-      pending.reject(err);
+    if (annotation && parsed.actual) {
+      howToFix.push(
+        `Or, if ${named} really should be ${describeType(parsed.actual)}, change its annotation in ${owner} from \`${annotation}\` to \`${cleanTypeName(parsed.actual)}\`.`
+      );
     }
-    this.pending.clear();
+    return {
+      headline: `${owner} expects ${named} to be ${wanted}${got}.`,
+      howToFix
+    };
   }
-  async handleStdinRequest() {
-    let line = null;
-    try {
-      line = this.stdinHandler ? await this.stdinHandler() : null;
-    } catch {
-      line = null;
+  if (parsed.kind === "return") {
+    if (parsed.actual === "None" || parsed.actual === "NoneType") {
+      return {
+        headline: `${owner} should return ${wanted}, but it finished without returning a value.`,
+        howToFix: [
+          "Make sure every path through the function reaches a `return`.",
+          "An `if` with no `else` falls off the end, and Python then returns `None`.",
+          `Or annotate the return type as \`None\` if ${owner} is not meant to return anything.`
+        ]
+      };
     }
-    if (this.stdinBuffer) {
-      writeStdinLine(this.stdinBuffer, line);
+    const got = parsed.actual ? describeType(parsed.actual) : "something else";
+    const howToFix = [];
+    const wantsNone = parsed.expected.length === 1 && /^(None|NoneType)$/.test(parsed.expected[0]);
+    if (wantsNone) {
+      howToFix.push("Use a bare `return`, or drop the `return` entirely.");
+    } else if (convert) {
+      howToFix.push(`Convert the returned value with \`${convert}(...)\`.`);
+    } else {
+      howToFix.push(`Return ${wanted} from this line.`);
     }
-  }
-};
-
-// src/desktop/pyodideRuntime.ts
-var DesktopPyodideRuntime = class extends WorkerPythonRuntime {
-  constructor(paths) {
-    super();
-    this.paths = paths;
-  }
-  paths;
-  resolveIndexUrl() {
-    const found = this.paths.indexUrlCandidates.find(
-      (dir) => fs.existsSync(path.join(dir, "pyodide.asm.wasm"))
-    );
-    if (!found) {
-      throw new Error(this.paths.missingAssetsHint);
+    if (boolNote) howToFix.push(boolNote);
+    if (annotation && parsed.actual) {
+      howToFix.push(
+        `Or change ${owner}'s return annotation from \`${annotation}\` to \`${cleanTypeName(parsed.actual)}\`.`
+      );
     }
-    return found;
-  }
-  spawn(handlers) {
-    const worker = new import_node_worker_threads.Worker(this.paths.workerPath);
-    worker.on("message", (msg) => handlers.onMessage(msg));
-    worker.on(
-      "error",
-      (err) => handlers.onError(err instanceof Error ? err : new Error(String(err)))
-    );
     return {
-      post: (msg) => worker.postMessage(msg),
-      terminate: () => void worker.terminate()
+      headline: `${owner} says it returns ${wanted}, but this line returns ${got}.`,
+      howToFix
+    };
+  }
+  if (parsed.kind === "variable") {
+    if (parsed.element) {
+      return {
+        headline: `${named} is annotated so ${membersPhrase(parsed.element)} it is ${wanted}, but ${parsed.element} is not.`,
+        howToFix: [`Look at ${parsed.element} of the value assigned to ${named}.`]
+      };
+    }
+    const got = parsed.actual ? describeType(parsed.actual) : "a different type";
+    const howToFix = [`Assign ${wanted} to ${named}.`];
+    if (boolNote) howToFix.push(boolNote);
+    if (convert) {
+      howToFix.push(`You can convert the value with \`${convert}(...)\`.`);
+    }
+    if (annotation && parsed.actual) {
+      howToFix.push(
+        `Or change ${named}'s annotation from \`${annotation}\` to \`${cleanTypeName(parsed.actual)}\`.`
+      );
+    }
+    return {
+      headline: `${named} is annotated as ${wanted}, but ${got} was assigned here.`,
+      howToFix
     };
   }
-};
-
-// src/cli/runtime.ts
-function createCliRuntime() {
-  return new DesktopPyodideRuntime({
-    // `pyodide` is external in the bundle, so this resolves at run time
-    // from the installed package rather than being inlined.
-    indexUrlCandidates: [path2.dirname(require.resolve("pyodide"))],
-    workerPath: path2.join(__dirname, "worker.cjs"),
-    missingAssetsHint: "Could not find Pyodide's assets. Reinstall pll-python so its `pyodide` dependency is present."
-  });
-}
-
-// src/cli/run.ts
-var fs3 = __toESM(require("node:fs/promises"));
-var path4 = __toESM(require("node:path"));
-
-// src/common/analyzers/static/shadowingExplainer.ts
-function outerScopeNoun(kind) {
-  switch (kind) {
-    case "module":
-      return "the file";
-    case "function":
-    case "lambda":
-      return "an enclosing function";
-    case "class":
-      return "an enclosing class";
-    case "comprehension":
-      return "an enclosing comprehension";
-    default:
-      return "an outer scope";
-  }
-}
-function explainShadowing(raw, level, fileName) {
-  const name = raw.name_token ?? "this name";
-  const outerLine = raw.outer_line_number ?? null;
-  const outerNoun = outerScopeNoun(raw.outer_scope_kind);
-  const knownOuterLine = outerLine !== null && outerLine > 0;
-  const outerHint = knownOuterLine ? ` (first defined on line ${outerLine}, in ${outerNoun})` : ` in ${outerNoun}`;
-  return {
-    id: "shadowing",
-    errorType: "Shadowing",
-    message: raw.message,
-    headline: `\`${name}\` is already defined${outerHint}.`,
-    howToFix: [
-      `Rename the inner \`${name}\` to something distinct (e.g. \`${name}_inner\`, \`local_${name}\`, or whatever describes its role).`,
-      `Or, if you want to use the outer \`${name}\`, just read it directly without making a new variable.`
-    ],
-    fileName,
-    lineNumber: raw.line_number,
-    column: raw.column,
-    nameToken: raw.name_token,
-    severity: "error",
-    raw: JSON.stringify(raw),
-    origin: "static",
-    level
-  };
-}
-function explainShadowingBuiltin(raw, level, fileName) {
-  const name = raw.name_token ?? "this name";
-  const headline = `\`${name}\` is the name of a Python built-in.`;
   return {
-    id: "shadowing-builtin",
-    errorType: "Shadowing",
-    message: raw.message,
-    headline,
+    headline: "A value does not match the type annotation written for it.",
     howToFix: [
-      `Pick a different name. Common patterns: \`my_${name}\`, \`${name}_value\`, \`${name}s\` (plural), or a more specific noun describing what this value represents.`
-    ],
-    fileName,
-    lineNumber: raw.line_number,
-    column: raw.column,
-    nameToken: raw.name_token,
-    severity: "error",
-    raw: JSON.stringify(raw),
-    origin: "static",
-    level
+      message.split(/\r?\n/)[0].trim(),
+      "Either pass a value of the annotated type, or change the annotation."
+    ]
   };
 }
 
-// src/common/analyzers/static/reassignmentExplainer.ts
-function explainReassignment(raw, level, fileName) {
-  const name = raw.name_token ?? "this name";
-  const firstLine = raw.first_line_number ?? null;
-  const firstLineHint = firstLine !== null && firstLine > 0 ? ` (first assigned on line ${firstLine})` : "";
-  return {
-    id: "reassignment",
-    errorType: "Reassignment",
-    message: raw.message,
-    headline: `\`${name}\` is already assigned${firstLineHint}.`,
-    howToFix: level === "intermediate" ? [
-      `If you want a different value, give it a different name (e.g. \`${name}_doubled\`, \`new_${name}\`, \`${name}2\`).`,
-      `If you're trying to update a value (\`x = x + 1\`, accumulators, running totals), wrap the work in a function and rebind \`${name}\` from the function's return value: \`${name} = compute_${name}(...)\`.`
-    ] : [
-      `If you want a different value, give it a different name (e.g. \`${name}_doubled\`, \`new_${name}\`, \`${name}2\`).`,
-      `If you're trying to update a value (\`x = x + 1\`, accumulators, running totals), use a built-in like \`sum(...)\`, \`max(...)\`, or a small helper function that returns the new value instead.`
-    ],
-    fileName,
-    lineNumber: raw.line_number,
-    column: raw.column,
-    nameToken: raw.name_token,
-    severity: "error",
-    raw: JSON.stringify(raw),
-    origin: "static",
-    level
-  };
+// src/common/analyzers/typeCheckAnalyzer.ts
+var HANDLED = ["TypeCheckError", "typeguard.TypeCheckError"];
+function messageWithDetail(traceback, fallback) {
+  const lines = traceback.split(/\r?\n/);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    const marker = line.indexOf("TypeCheckError:");
+    if (line.startsWith(" ") || marker < 0) continue;
+    const detail = [line.slice(marker + "TypeCheckError:".length).trim()];
+    for (let j = i + 1; j < lines.length; j++) {
+      if (lines[j].trim() === "") continue;
+      if (!lines[j].startsWith(" ")) break;
+      detail.push(lines[j]);
+    }
+    return detail.join("\n");
+  }
+  return fallback;
 }
-
-// src/common/analyzers/static/disallowedKeywordExplainer.ts
-function explainDisallowedKeyword(raw, level, fileName) {
-  const keyword = raw.keyword === "nonlocal" ? "nonlocal" : "global";
-  const names = Array.isArray(raw.names) ? raw.names : [];
-  const formattedNames = names.map((n) => `\`${n}\``).join(", ");
-  const namesPhrase = formattedNames.length > 0 ? ` ${formattedNames}` : "";
-  const headline = `\`${keyword}\` is not allowed at the ${level} level.`;
-  const howToFix = [];
-  if (keyword === "global") {
-    howToFix.push(
-      `Pass${namesPhrase || " the value"} into this function as an argument instead of declaring it \`global\`.`,
-      `If the function needs to *change* a value, return the new value and let the caller decide what to do with it (e.g. \`x = update(x)\`).`
-    );
-  } else {
-    howToFix.push(
-      `Return${namesPhrase || " the new value"} from this inner function and have the outer function rebind it explicitly (e.g. \`x = inner(x)\`).`,
-      `If the inner function only needs to *read* the outer name, just use it directly - you don't need \`nonlocal\` for that.`
+var typeCheckAnalyzer = {
+  handles: HANDLED,
+  analyze(input) {
+    const { parsedError, fileName, level } = input;
+    if (!HANDLED.includes(parsedError.errorType)) {
+      return null;
+    }
+    const message = messageWithDetail(parsedError.traceback, parsedError.message);
+    const parsed = parseTypeCheckMessage(message);
+    const frames = userTracebackFrames(parsedError.traceback);
+    const innermost = frames.length > 0 ? frames[frames.length - 1] : null;
+    const blamed = parsed.kind === "argument" && frames.length >= 2 ? frames[frames.length - 2] : innermost;
+    const explanation = explainTypeCheckError(
+      message,
+      innermost ? innermost.functionName : null,
+      level
     );
+    return {
+      id: "type-check",
+      // Not a real Python exception name; "TypeCheckError" means nothing to
+      // a student, and "TypeError" would name a different Python error.
+      errorType: "TypeMismatch",
+      message,
+      headline: explanation.headline,
+      howToFix: explanation.howToFix,
+      fileName: blamed ? blamed.fileName : fileName,
+      lineNumber: blamed ? blamed.line : parsedError.lineNumber,
+      column: null,
+      nameToken: parsed.name,
+      severity: "error",
+      raw: parsedError.traceback,
+      origin: "runtime",
+      level
+    };
   }
-  return {
-    id: "disallowed-keyword",
-    errorType: "DisallowedKeyword",
-    message: raw.message,
-    headline,
-    howToFix,
-    fileName,
-    lineNumber: raw.line_number,
-    column: raw.column,
-    nameToken: raw.name_token,
-    severity: "error",
-    raw: JSON.stringify(raw),
-    origin: "static",
-    level
-  };
-}
-
-// src/common/analyzers/static/registry.ts
-var explainers = {
-  shadowing: explainShadowing,
-  "shadowing-builtin": explainShadowingBuiltin,
-  reassignment: explainReassignment,
-  "disallowed-keyword": explainDisallowedKeyword
 };
-function fallbackExplainer(raw, level, fileName) {
-  return {
-    id: raw.id,
-    errorType: raw.error_type || "StaticError",
-    message: raw.message,
-    headline: raw.message,
-    howToFix: [],
-    fileName,
-    lineNumber: raw.line_number,
-    column: raw.column,
-    nameToken: raw.name_token,
-    severity: "error",
-    raw: JSON.stringify(raw),
-    origin: "static",
-    level
-  };
+
+// src/common/analyzers/registry.ts
+var analyzers = [nameErrorAnalyzer, typeCheckAnalyzer];
+function findRuntimeFinding(source, fileName, level, parsedError) {
+  for (const analyzer of analyzers) {
+    if (!analyzer.handles.includes(parsedError.errorType)) {
+      continue;
+    }
+    const finding = analyzer.analyze({ source, fileName, level, parsedError });
+    if (finding) {
+      return finding;
+    }
+  }
+  return null;
 }
-function enrichStaticFindings(rawFindings, level, fileName) {
-  return rawFindings.map((raw) => {
-    const explainer = explainers[raw.id] ?? fallbackExplainer;
-    return explainer(raw, level, fileName);
-  });
+
+// src/common/analyzers/runtimeFinding.ts
+function findingForErrorEvent(event, source, fileName, level) {
+  const traceback = event.traceback || `${event.errorType}: ${event.message}`;
+  const parsed = parsePythonError(traceback);
+  if (parsed.lineNumber === null && event.lineNumber !== null) {
+    parsed.lineNumber = event.lineNumber;
+  }
+  if (parsed.column === null && event.column !== null) {
+    parsed.column = event.column;
+  }
+  if (parsed.fileName === null && event.fileName) {
+    parsed.fileName = event.fileName;
+  }
+  return findRuntimeFinding(source, fileName, level, parsed);
 }
 
-// src/common/errors/pythonErrorParser.ts
-var NON_USER_FRAME = [
-  "<exec>",
-  "/pll_vendor",
-  "site-packages",
-  "/lib/python",
-  "_pytest",
-  "pluggy"
-];
-function userTracebackFrames(traceback) {
-  const frames = [];
-  for (const raw of traceback.split(/\r?\n/)) {
-    const m = raw.match(/^\s*File "([^"]+)", line (\d+)(?:, in (\S+))?/);
-    if (!m) continue;
-    const fileName = m[1];
-    if (NON_USER_FRAME.some((token) => fileName.includes(token))) continue;
-    frames.push({
-      fileName,
-      line: parseInt(m[2], 10),
-      functionName: m[3] && m[3] !== "<module>" ? m[3] : null
-    });
+// src/common/pyodideRunner.ts
+var ANY_IMPORT_RE = /(^|\n)[ \t]*(import|from)[ \t]+\S/;
+
+// src/cli/files.ts
+var fs = __toESM(require("node:fs/promises"));
+var path = __toESM(require("node:path"));
+
+// src/common/workspaceFilePolicy.ts
+var MAX_FILE_BYTES = 2 * 1024 * 1024;
+var MAX_TOTAL_BYTES = 8 * 1024 * 1024;
+var MAX_FILES = 50;
+var MOUNT_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".csv",
+  ".txt",
+  ".tsv",
+  ".json",
+  ".md",
+  ".dat",
+  ".xml",
+  ".py"
+]);
+var WRITEBACK_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".csv",
+  ".txt",
+  ".tsv",
+  ".json",
+  ".md",
+  ".dat",
+  ".xml"
+]);
+function extensionOf(name) {
+  const dot = name.lastIndexOf(".");
+  if (dot <= 0) {
+    return "";
+  }
+  return name.slice(dot).toLowerCase();
+}
+function isSafeBasename(name) {
+  if (!name || name === "." || name === "..") {
+    return false;
+  }
+  if (name.startsWith(".")) {
+    return false;
+  }
+  if (name.includes("/") || name.includes("\\") || name.includes("\0")) {
+    return false;
   }
-  return frames;
+  return true;
 }
-function parsePythonError(rawTraceback) {
-  const traceback = rawTraceback.trimEnd();
-  const lines = traceback.split(/\r?\n/);
-  let errorType = "Error";
-  let message = traceback;
-  for (let i = lines.length - 1; i >= 0; i--) {
-    const line = lines[i];
-    const m = line.match(/^([A-Za-z_][A-Za-z0-9_.]*):\s?(.*)$/);
-    if (m && !line.startsWith(" ")) {
-      errorType = m[1];
-      message = m[2];
-      break;
-    }
-    if (line.match(/^[A-Za-z_][A-Za-z0-9_.]*$/) && !line.startsWith(" ")) {
-      errorType = line;
-      message = "";
-      break;
+function isMountableName(name) {
+  return isSafeBasename(name) && MOUNT_EXTENSIONS.has(extensionOf(name));
+}
+function isWritebackName(name) {
+  return isSafeBasename(name) && WRITEBACK_EXTENSIONS.has(extensionOf(name));
+}
+function utf8ByteLength(text) {
+  return new TextEncoder().encode(text).byteLength;
+}
+function decodeMountContents(data) {
+  if (data.byteLength > MAX_FILE_BYTES) {
+    return void 0;
+  }
+  for (let i = 0; i < data.byteLength; i++) {
+    if (data[i] === 0) {
+      return void 0;
     }
   }
-  let fileName = null;
-  let lineNumber = null;
-  for (let i = lines.length - 1; i >= 0; i--) {
-    const line = lines[i];
-    const m = line.match(/^\s*File\s+"([^"]+)",\s+line\s+(\d+)/);
-    if (m) {
-      fileName = m[1];
-      lineNumber = parseInt(m[2], 10);
+  return new TextDecoder("utf-8").decode(data);
+}
+function selectMountableFiles(candidates) {
+  const selected = [];
+  let total = 0;
+  for (const candidate of candidates) {
+    if (selected.length >= MAX_FILES) {
       break;
     }
-  }
-  let column = null;
-  if (lineNumber !== null) {
-    for (let i = 0; i < lines.length - 1; i++) {
-      if (/^\s*\^+\s*$/.test(lines[i + 1] ?? "")) {
-        const caretLine = lines[i + 1];
-        const caretIdx = caretLine.indexOf("^");
-        if (caretIdx >= 0) {
-          column = caretIdx;
-        }
+    if (!isMountableName(candidate.name)) {
+      continue;
+    }
+    let text;
+    if (typeof candidate.contents === "string") {
+      if (utf8ByteLength(candidate.contents) > MAX_FILE_BYTES) {
+        continue;
+      }
+      if (candidate.contents.includes("\0")) {
+        continue;
       }
+      text = candidate.contents;
+    } else {
+      const decoded = decodeMountContents(candidate.contents);
+      if (decoded === void 0) {
+        continue;
+      }
+      text = decoded;
+    }
+    const size = utf8ByteLength(text);
+    if (total + size > MAX_TOTAL_BYTES) {
+      continue;
     }
+    selected.push({ name: candidate.name, contents: text });
+    total += size;
   }
-  let nameToken = null;
-  if (errorType === "NameError") {
-    const nm = message.match(/name '([^']+)' is not defined/);
-    if (nm) {
-      nameToken = nm[1];
+  return selected;
+}
+function selectWritebackFiles(files) {
+  const selected = [];
+  let total = 0;
+  for (const file of files) {
+    if (selected.length >= MAX_FILES) {
+      break;
+    }
+    if (!isWritebackName(file.name)) {
+      continue;
+    }
+    const size = utf8ByteLength(file.contents);
+    if (size > MAX_FILE_BYTES || total + size > MAX_TOTAL_BYTES) {
+      continue;
+    }
+    if (file.contents.includes("\0")) {
+      continue;
     }
+    selected.push(file);
+    total += size;
   }
-  return {
-    errorType,
-    message,
-    traceback,
-    fileName,
-    lineNumber,
-    column,
-    nameToken
-  };
+  return selected;
 }
 
-// src/common/errors/nameErrorExplainer.ts
-function explainNameError(parsed) {
-  const name = parsed.nameToken ?? "this name";
-  const didYouMean = extractDidYouMean(parsed.message);
-  const headline = `Python doesn't know what \`${name}\` means.`;
-  const howToFix = [
-    `Check the spelling of \`${name}\` (Python is case-sensitive).`,
-    `Make sure \`${name}\` is defined before this line runs.`,
-    `If \`${name}\` should be text, put it in quotes: \`"${name}"\`.`
-  ];
-  if (didYouMean.length > 0) {
-    howToFix.unshift(
-      `Python suggested: ${didYouMean.map((s) => "`" + s + "`").join(", ")} - try one of those.`
-    );
+// src/cli/files.ts
+async function collectSiblingFiles(scriptPath) {
+  const folder = path.dirname(path.resolve(scriptPath));
+  let entries;
+  try {
+    entries = await fs.readdir(folder, { withFileTypes: true });
+  } catch {
+    return [];
   }
-  return { headline, howToFix };
+  const candidates = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !isMountableName(entry.name)) {
+      continue;
+    }
+    try {
+      candidates.push({ name: entry.name, contents: await fs.readFile(path.join(folder, entry.name)) });
+    } catch {
+    }
+  }
+  return selectMountableFiles(candidates);
 }
-function extractDidYouMean(message) {
-  const m = message.match(/Did you mean:\s*([^?]+)\??/i);
-  if (!m) {
-    return [];
+async function writeBackSiblingFiles(scriptPath, files) {
+  const folder = path.dirname(path.resolve(scriptPath));
+  const written = [];
+  for (const file of selectWritebackFiles(files)) {
+    try {
+      await fs.writeFile(path.join(folder, file.name), file.contents, "utf8");
+      written.push(file.name);
+    } catch {
+    }
   }
-  return m[1].split(/,|\bor\b/).map((s) => s.trim().replace(/^['"`]|['"`]$/g, "")).filter((s) => s.length > 0);
+  return written;
 }
 
-// src/common/analyzers/nameErrorAnalyzer.ts
-var nameErrorAnalyzer = {
-  handles: ["NameError"],
-  analyze(input) {
-    const { parsedError, fileName, level } = input;
-    if (parsedError.errorType !== "NameError") {
-      return null;
+// src/cli/run.ts
+var EXIT = {
+  ok: 0,
+  /** The program raised. */
+  programError: 1,
+  /** Level checks found problems, so the file was not run. */
+  blocked: 2,
+  /** The program ran, but its in-file tests did not all pass. */
+  testsFailed: 3,
+  /** Bad usage, or PLL itself could not run. */
+  usage: 64
+};
+async function runFile(runtime, view, opts) {
+  const fileName = path2.basename(opts.file);
+  let source;
+  try {
+    source = await fs2.readFile(opts.file, "utf8");
+  } catch (err) {
+    view.problem(`Cannot read ${opts.file}: ${errText(err)}`);
+    return EXIT.usage;
+  }
+  const level = parseLevel(source);
+  view.note(`${fileName} [${level}]`);
+  if (levelHasStaticChecks(level)) {
+    const blocked = await staticChecks(runtime, view, source, fileName, level);
+    if (blocked) {
+      return EXIT.blocked;
     }
-    const explanation = explainNameError(parsedError);
-    return {
-      id: "name-error",
-      errorType: "NameError",
-      message: parsedError.message,
-      headline: explanation.headline,
-      howToFix: explanation.howToFix,
-      fileName,
-      lineNumber: parsedError.lineNumber,
-      column: parsedError.column,
-      nameToken: parsedError.nameToken,
-      severity: "error",
-      raw: parsedError.traceback,
-      origin: "runtime",
-      level
-    };
   }
-};
-
-// src/common/level.ts
-var DEFAULT_LEVEL = "raw";
-var HEADER_RE = /^#\s*level\s+([a-z]+)\s*$/;
-var LEVEL_NAMES = [
-  "raw",
-  "beginner",
-  "intermediate",
-  "advanced"
-];
-function parseLevel(source) {
-  const lines = source.split(/\r?\n/);
-  for (const raw of lines) {
-    const line = raw.trim();
-    if (line.length === 0) {
-      continue;
-    }
-    const match = HEADER_RE.exec(line);
-    if (!match) {
-      return DEFAULT_LEVEL;
+  await ensurePackages(runtime, view, source);
+  try {
+    await runtime.mountWorkspaceFiles(await collectSiblingFiles(opts.file));
+  } catch (err) {
+    view.note(`Could not load files next to this script (${errText(err)}).`);
+  }
+  const onEvent = (event) => {
+    if (event.kind === "error") {
+      const finding = findingForErrorEvent(event, source, fileName, level);
+      if (finding) {
+        view.runtimeFinding(finding);
+        return;
+      }
+    }
+    view.handle(event);
+  };
+  if (opts.runTests) {
+    await maybeRunTests(runtime, view, source, fileName, level, onEvent);
+  }
+  await runtime.runFile({ code: source, fileName, sessionKey: opts.file, level }, onEvent);
+  await writeBack(runtime, view, opts.file);
+  if (view.sawError) return EXIT.programError;
+  if (view.testFailures > 0) return EXIT.testsFailed;
+  return EXIT.ok;
+}
+async function staticChecks(runtime, view, source, fileName, level) {
+  let raw;
+  try {
+    raw = await runtime.staticAnalyze({ code: source, fileName, level });
+  } catch (err) {
+    view.note(`Static analysis failed (${errText(err)}); running anyway.`);
+    return false;
+  }
+  const findings = enrichStaticFindings(raw, level, fileName);
+  if (findings.length === 0) {
+    return false;
+  }
+  view.findings(findings);
+  view.problem(`Static analysis found ${findings.length} problem(s). File not run.`);
+  return true;
+}
+async function ensurePackages(runtime, view, source) {
+  if (!ANY_IMPORT_RE.test(source)) {
+    return;
+  }
+  try {
+    await runtime.ensurePackages(source);
+  } catch (err) {
+    const message = errText(err);
+    if (!/syntaxerror|invalid syntax/i.test(message)) {
+      view.note(`Could not load libraries (${message}). Continuing.`);
     }
-    const name = match[1];
-    for (const level of LEVEL_NAMES) {
-      if (name === level) return level;
+  }
+}
+async function maybeRunTests(runtime, view, source, fileName, level, onEvent) {
+  try {
+    if (!await runtime.hasTests(source)) {
+      return;
     }
-    return DEFAULT_LEVEL;
+    await runtime.ensurePytest();
+  } catch (err) {
+    view.note(`Could not check for tests (${errText(err)}); skipping them.`);
+    return;
   }
-  return DEFAULT_LEVEL;
+  await runtime.runTests({ code: source, fileName, sessionKey: fileName, level }, onEvent);
 }
-function levelRejectsBoolAsNumber(level) {
-  return level === "beginner" || level === "intermediate";
+async function writeBack(runtime, view, file) {
+  try {
+    const changed = await runtime.collectWorkspaceFiles();
+    if (changed.length === 0) {
+      return;
+    }
+    const written = await writeBackSiblingFiles(file, changed);
+    if (written.length > 0) {
+      view.note(`Saved ${written.join(", ")} next to ${path2.basename(file)}.`);
+    }
+  } catch (err) {
+    view.note(`Could not save files next to this script (${errText(err)}).`);
+  }
 }
-function levelHasStaticChecks(level) {
-  return level === "beginner" || level === "intermediate";
+function errText(err) {
+  return err instanceof Error ? err.message : String(err);
 }
 
-// src/common/errors/typeCheckExplainer.ts
-var FRIENDLY_TYPES = {
-  int: "a whole number",
-  float: "a number",
-  complex: "a complex number",
-  str: "a string",
-  bool: "`True` or `False`",
-  bytes: "bytes",
-  list: "a list",
-  dict: "a dictionary",
-  set: "a set",
-  tuple: "a tuple",
-  None: "`None`",
-  NoneType: "`None`"
-};
-function cleanTypeName(type) {
-  return type.startsWith("__main__.") ? type.slice("__main__.".length) : type;
-}
-function describeType(type) {
-  const name = cleanTypeName(type);
-  if (name === "None" || name === "NoneType") return "`None`";
-  const friendly = FRIENDLY_TYPES[name];
-  return friendly ? `${friendly} (\`${name}\`)` : `\`${name}\``;
-}
-function describeTypes(types) {
-  const described = types.map(describeType);
-  if (described.length === 0) return "a different type";
-  if (described.length === 1) return described[0];
-  return `${described.slice(0, -1).join(", ")} or ${described[described.length - 1]}`;
-}
-function boolAsNumberNote(expected, actual, level) {
-  if (actual !== "bool" || expected.length === 0) return null;
-  if (!expected.some((type) => type === "int" || type === "float")) return null;
-  if (level !== void 0 && !levelRejectsBoolAsNumber(level)) return null;
-  return "At `#level beginner` and `#level intermediate`, `True` and `False` are not accepted as numbers, even though Python counts them as `1` and `0`.";
-}
-function conversionFor(expected, actual) {
-  if (expected.length !== 1 || actual === null) return null;
-  const to = expected[0];
-  const numeric = actual === "int" || actual === "float" || actual === "bool";
-  if (to === "int" && (actual === "str" || actual === "float")) return "int";
-  if (to === "float" && actual === "str") return "float";
-  if (to === "str" && numeric) return "str";
-  return null;
+// src/cli/examplar.ts
+var EXAMPLAR_USAGE = `pll examplar - author Examplar bundles
+
+  pll examplar build <dir> [-o bundle.json] [--verify tests.py]
+
+<dir> holds the implementations, one file each:
+
+  <dir>/wheats/reference.py       known-good; every test must pass on these
+  <dir>/wheats/alternative.py     more than one stops tests over-fitting
+  <dir>/chaffs/initials/1.py      known-bad; each must be caught by some test
+  <dir>/chaffs/longest/1.py
+
+A chaff goes in a directory named after the function it breaks, because a
+student's report is per function. Its id is its filename, and that id is the
+only thing a student sees about a chaff they missed - so number them rather
+than naming them after the bug. Every function needs at least one.
+
+Only bytecode is written to the bundle, so the sources stay in your
+repository.
+
+The bytecode is compiled by the Pyodide this package pins, so it always
+matches the interpreter that will run it - which is the reason to build
+bundles with this tool rather than a local python.
+
+  -o FILE           write here instead of stdout
+  --verify TESTS    check the bundle with your own suite: it must pass on
+                    every wheat and fail on every chaff. A chaff no test can
+                    catch is a broken chaff, and better found now. Chaffs are
+                    only checked once the wheats pass, since a suite that is
+                    wrong fails on everything.
+`;
+function parseExamplarArgs(argv) {
+  const args = { help: false };
+  if (argv[0] !== "build") {
+    args.error = argv.length === 0 ? "examplar needs a subcommand" : `unknown examplar subcommand ${argv[0]}`;
+    if (argv[0] === "-h" || argv[0] === "--help") {
+      args.error = void 0;
+      args.help = true;
+    }
+    return args;
+  }
+  for (let i = 1; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "-h" || arg === "--help") args.help = true;
+    else if (arg === "-o") {
+      args.out = argv[++i];
+      if (args.out === void 0) {
+        args.error = "-o needs a file";
+        return args;
+      }
+    } else if (arg === "--verify") {
+      args.verify = argv[++i];
+      if (args.verify === void 0) {
+        args.error = "--verify needs a test file";
+        return args;
+      }
+    } else if (arg.startsWith("-")) {
+      args.error = `unknown option ${arg}`;
+      return args;
+    } else if (args.dir === void 0) {
+      args.dir = arg;
+    } else {
+      args.error = `unexpected extra argument ${arg}`;
+      return args;
+    }
+  }
+  if (!args.help && args.dir === void 0) {
+    args.error = "no directory given";
+  }
+  return args;
 }
-var ELEMENT_RE = /^(item \d+|key .+|value of key .+|\[.+\]) of (.+)$/;
-function membersPhrase(element) {
-  if (element.startsWith("the value for key")) return "every value in";
-  if (element.startsWith("key ")) return "every key in";
-  return "every item in";
+async function readDir(folder) {
+  try {
+    return await fs3.readdir(folder, { withFileTypes: true });
+  } catch {
+    throw new Error(`${folder} does not exist. See \`pll examplar --help\`.`);
+  }
 }
-function describeElement(element) {
-  if (element.startsWith("value of key ")) {
-    return `the value for key ${element.slice("value of key ".length)}`;
+async function readWheats(dir) {
+  const folder = path3.join(dir, "wheats");
+  const out = {};
+  for (const entry of await readDir(folder)) {
+    if (!entry.isFile() || !entry.name.endsWith(".py")) continue;
+    out[entry.name.slice(0, -3)] = await fs3.readFile(path3.join(folder, entry.name), "utf8");
   }
-  if (element.startsWith("[")) return "one of the values";
-  return element;
+  if (Object.keys(out).length === 0) {
+    throw new Error(`${folder} has no .py files in it.`);
+  }
+  return out;
 }
-function parseTypeCheckMessage(message) {
-  const unknown = {
-    kind: "unknown",
-    name: null,
-    element: null,
-    actual: null,
-    expected: []
-  };
-  const lines = message.split(/\r?\n/);
-  const first = lines[0].trim();
-  let expected = [];
-  let subject = null;
-  const unionAt = first.indexOf(" did not match any element in the union:");
-  if (unionAt >= 0) {
-    subject = first.slice(0, unionAt);
-    for (const raw of lines.slice(1)) {
-      const m = raw.match(/^\s*([A-Za-z_][A-Za-z0-9_.\[\], ]*):/);
-      if (m) expected.push(m[1].trim());
+async function readChaffs(dir) {
+  const folder = path3.join(dir, "chaffs");
+  const out = {};
+  const loose = [];
+  for (const entry of await readDir(folder)) {
+    if (entry.isFile() && entry.name.endsWith(".py")) {
+      loose.push(entry.name);
+      continue;
     }
-  } else {
-    const predicates = [
-      [/^(.*) is not an instance of (.+)$/, (m) => [m[2]]],
-      [/^(.*) is neither float or int$/, () => ["float"]],
-      [/^(.*) is not None$/, () => ["None"]],
-      [/^(.*) is not a ([A-Za-z_][A-Za-z0-9_]*)$/, (m) => [m[2]]]
-    ];
-    for (const [re, pick] of predicates) {
-      const m = first.match(re);
-      if (m) {
-        subject = m[1];
-        expected = pick(m);
-        break;
-      }
+    if (!entry.isDirectory()) continue;
+    const inner = path3.join(folder, entry.name);
+    const group = {};
+    for (const file of await fs3.readdir(inner, { withFileTypes: true })) {
+      if (!file.isFile() || !file.name.endsWith(".py")) continue;
+      group[file.name.slice(0, -3)] = await fs3.readFile(path3.join(inner, file.name), "utf8");
+    }
+    if (Object.keys(group).length > 0) {
+      out[entry.name] = group;
     }
   }
-  if (subject === null) return unknown;
-  let actual = null;
-  const withActual = subject.match(/^(.*) \(([^()]*)\)$/);
-  if (withActual) {
-    subject = withActual[1];
-    actual = withActual[2];
+  if (loose.length > 0) {
+    throw new Error(
+      `${path3.join(folder, loose[0])} is not inside a function's directory. Chaffs go in \`chaffs/<function>/\`, named after the function they break - move it to \`chaffs/<function>/${loose[0]}\`.`
+    );
   }
-  let element = null;
-  const elementMatch = subject.match(ELEMENT_RE);
-  if (elementMatch) {
-    element = describeElement(elementMatch[1]);
-    subject = elementMatch[2];
+  if (Object.keys(out).length === 0) {
+    throw new Error(`${folder} has no \`<function>/*.py\` in it.`);
   }
-  if (subject === "the return value") {
-    return { kind: "return", name: null, element, actual, expected };
+  return out;
+}
+async function runExamplar(runtime, view, argv) {
+  const args = parseExamplarArgs(argv);
+  if (args.help) {
+    process.stdout.write(EXAMPLAR_USAGE);
+    return EXIT.ok;
   }
-  const argument = subject.match(/^argument "(.+)"$/);
-  if (argument) {
-    return { kind: "argument", name: argument[1], element, actual, expected };
+  if (args.error !== void 0) {
+    process.stderr.write(`pll: ${args.error}
+
+${EXAMPLAR_USAGE}`);
+    return EXIT.usage;
   }
-  const assigned = subject.match(/^value assigned to (.+)$/);
-  if (assigned) {
-    return { kind: "variable", name: assigned[1], element, actual, expected };
+  const dir = path3.resolve(args.dir);
+  let sources;
+  try {
+    sources = { wheats: await readWheats(dir), chaffs: await readChaffs(dir) };
+  } catch (err) {
+    view.problem(`pll: ${err instanceof Error ? err.message : String(err)}`);
+    return EXIT.usage;
   }
-  return { ...unknown, element, actual, expected };
-}
-function explainTypeCheckError(message, functionName, level) {
-  const parsed = parseTypeCheckMessage(message);
-  const wanted = describeTypes(parsed.expected);
-  const owner = functionName ? `\`${functionName}\`` : "this function";
-  const named = parsed.name ? `\`${parsed.name}\`` : "a value";
-  const convert = conversionFor(parsed.expected, parsed.actual);
-  const boolNote = boolAsNumberNote(parsed.expected, parsed.actual, level);
-  const annotation = parsed.expected.length === 1 ? cleanTypeName(parsed.expected[0]) : null;
-  if (parsed.kind === "argument") {
-    if (parsed.element) {
-      return {
-        headline: `${owner} expects ${membersPhrase(parsed.element)} ${named} to be ${wanted}, but ${parsed.element} is not.`,
-        howToFix: [
-          `Look at ${parsed.element} of the ${parsed.actual ?? "value"} you passed for ${named}.`,
-          "Every one has to match the annotation, not just the first."
-        ]
-      };
-    }
-    const got = parsed.actual ? `, but got ${describeType(parsed.actual)}` : "";
-    const howToFix = [`Check the value you passed for ${named} on this line.`];
-    if (boolNote) howToFix.push(boolNote);
-    if (convert) {
-      howToFix.push(`If it should be ${wanted}, convert it with \`${convert}(...)\`.`);
-    }
-    if (annotation && parsed.actual) {
-      howToFix.push(
-        `Or, if ${named} really should be ${describeType(parsed.actual)}, change its annotation in ${owner} from \`${annotation}\` to \`${cleanTypeName(parsed.actual)}\`.`
-      );
+  const built = await runtime.examplarBuild(JSON.stringify(sources));
+  if (!built.ok || !built.bundle) {
+    view.problem(`pll: ${built.error ?? "could not build the bundle"}`);
+    return EXIT.usage;
+  }
+  const bundle = built.bundle;
+  view.note(
+    `built for Python ${bundle.built.python}: ${bundle.wheats.length} wheat(s), ${bundle.chaffs.length} chaff(s), providing ${bundle.provides.join(", ")}`
+  );
+  if (args.verify !== void 0) {
+    const code = await verify(runtime, view, bundle, args.verify);
+    if (code !== EXIT.ok) {
+      return code;
     }
-    return {
-      headline: `${owner} expects ${named} to be ${wanted}${got}.`,
-      howToFix
-    };
   }
-  if (parsed.kind === "return") {
-    if (parsed.actual === "None" || parsed.actual === "NoneType") {
-      return {
-        headline: `${owner} should return ${wanted}, but it finished without returning a value.`,
-        howToFix: [
-          "Make sure every path through the function reaches a `return`.",
-          "An `if` with no `else` falls off the end, and Python then returns `None`.",
-          `Or annotate the return type as \`None\` if ${owner} is not meant to return anything.`
-        ]
-      };
+  const json = JSON.stringify(bundle);
+  if (args.out === void 0) {
+    process.stdout.write(json + "\n");
+  } else {
+    await fs3.writeFile(path3.resolve(args.out), json + "\n", "utf8");
+    view.note(`wrote ${args.out} (${json.length} bytes)`);
+  }
+  return EXIT.ok;
+}
+function caught(impl) {
+  return !impl.loaded || Object.values(impl.tests).some((t) => t.outcome !== "pass");
+}
+async function verify(runtime, view, bundle, testsPath) {
+  let testSource;
+  try {
+    testSource = await fs3.readFile(path3.resolve(testsPath), "utf8");
+  } catch (err) {
+    view.problem(`pll: cannot read ${testsPath}: ${err instanceof Error ? err.message : err}`);
+    return EXIT.usage;
+  }
+  try {
+    await runtime.ensurePytest();
+  } catch {
+    view.note("could not load pytest; assertion messages will be terse.");
+  }
+  const result = await runtime.examplarRun(
+    testSource,
+    JSON.stringify(bundle)
+  );
+  if (!result.ok) {
+    view.problem(`pll: ${result.error ?? "the bundle could not be run"}`);
+    return EXIT.usage;
+  }
+  let bad = 0;
+  view.problem(`verifying with ${path3.basename(testsPath)}:`);
+  for (const wheat of result.wheats ?? []) {
+    const failures = Object.entries(wheat.tests).filter(([, t]) => t.outcome !== "pass");
+    if (wheat.loaded && failures.length === 0) {
+      view.note(`  ok    wheat ${wheat.id}: all ${Object.keys(wheat.tests).length} pass`);
+      continue;
     }
-    const got = parsed.actual ? describeType(parsed.actual) : "something else";
-    const howToFix = [];
-    const wantsNone = parsed.expected.length === 1 && /^(None|NoneType)$/.test(parsed.expected[0]);
-    if (wantsNone) {
-      howToFix.push("Use a bare `return`, or drop the `return` entirely.");
-    } else if (convert) {
-      howToFix.push(`Convert the returned value with \`${convert}(...)\`.`);
-    } else {
-      howToFix.push(`Return ${wanted} from this line.`);
+    bad += 1;
+    view.problem(`  BAD   wheat ${wheat.id}: your own tests do not all pass on it`);
+    if (!wheat.loaded) {
+      view.problem(`          ${wheat.error_type}: ${wheat.error_message}`);
     }
-    if (boolNote) howToFix.push(boolNote);
-    if (annotation && parsed.actual) {
-      howToFix.push(
-        `Or change ${owner}'s return annotation from \`${annotation}\` to \`${cleanTypeName(parsed.actual)}\`.`
-      );
+    for (const [name, t] of failures) {
+      view.problem(`          ${name}: ${(t.message ?? t.outcome).split("\n")[0]}`);
     }
-    return {
-      headline: `${owner} says it returns ${wanted}, but this line returns ${got}.`,
-      howToFix
-    };
   }
-  if (parsed.kind === "variable") {
-    if (parsed.element) {
-      return {
-        headline: `${named} is annotated so ${membersPhrase(parsed.element)} it is ${wanted}, but ${parsed.element} is not.`,
-        howToFix: [`Look at ${parsed.element} of the value assigned to ${named}.`]
-      };
+  for (const chaff of result.chaffs ?? []) {
+    const where = `chaff ${chaff.targets}/${chaff.id}`;
+    if (caught(chaff)) {
+      const by = Object.entries(chaff.tests).filter(([, t]) => t.outcome !== "pass").map(([name]) => name);
+      view.note(`  ok    ${where}: caught by ${by.join(", ")}`);
+      continue;
     }
-    const got = parsed.actual ? describeType(parsed.actual) : "a different type";
-    const howToFix = [`Assign ${wanted} to ${named}.`];
-    if (boolNote) howToFix.push(boolNote);
-    if (convert) {
-      howToFix.push(`You can convert the value with \`${convert}(...)\`.`);
+    bad += 1;
+    view.problem(`  BAD   ${where}: no test catches it - it would never count`);
+  }
+  const attributed = Object.values(result.attribution ?? {});
+  for (const name of result.chaffs_skipped ?? []) {
+    if (attributed.some((names) => names.includes(name))) {
+      view.problem(`  ---   ${name} chaffs not checked: its tests have to pass first`);
+      continue;
     }
-    if (annotation && parsed.actual) {
-      howToFix.push(
-        `Or change ${named}'s annotation from \`${annotation}\` to \`${cleanTypeName(parsed.actual)}\`.`
-      );
+    bad += 1;
+    view.problem(
+      `  BAD   your own suite has no tests for ${name}, so its chaffs are unproven`
+    );
+  }
+  if (bad > 0) {
+    view.problem(`pll: ${bad} problem(s) with this bundle; not written.`);
+    return EXIT.testsFailed;
+  }
+  view.problem("verified.");
+  return EXIT.ok;
+}
+
+// src/cli/runtime.ts
+var path5 = __toESM(require("node:path"));
+
+// src/desktop/pyodideRuntime.ts
+var fs4 = __toESM(require("node:fs"));
+var path4 = __toESM(require("node:path"));
+var import_node_worker_threads = require("node:worker_threads");
+
+// src/common/deliverResult.ts
+function deliverRunResult(result, onEvent, fileName) {
+  if (result.displays) {
+    for (const display of result.displays) {
+      deliverDisplay(display, onEvent, fileName);
     }
-    return {
-      headline: `${named} is annotated as ${wanted}, but ${got} was assigned here.`,
-      howToFix
-    };
   }
+  if (result.result_repr !== null && result.result_repr !== void 0) {
+    onEvent({ kind: "result", repr: result.result_repr });
+  }
+  if (!result.ok && result.error_type) {
+    onEvent({
+      kind: "error",
+      errorType: result.error_type,
+      message: result.error_message ?? "",
+      traceback: result.traceback ?? "",
+      lineNumber: result.line_number,
+      column: result.column,
+      fileName
+    });
+  }
+  onEvent({ kind: "done" });
+}
+function deliverDisplay(display, onEvent, fileName) {
+  switch (display.type) {
+    case "stdout":
+      onEvent({ kind: "stdout", text: display.text });
+      break;
+    case "stderr":
+      onEvent({ kind: "stderr", text: display.text });
+      break;
+    case "image":
+      onEvent({
+        kind: "image",
+        svg: display.data,
+        width: display.width,
+        height: display.height,
+        source: fileName
+      });
+      break;
+    case "reactor":
+      onEvent({
+        kind: "reactor",
+        id: display.id,
+        title: display.title,
+        tickRate: display.tick_rate,
+        ticking: display.ticking,
+        wantsKeys: display.wants_keys,
+        wantsMouse: display.wants_mouse,
+        register: display.register,
+        frame: display.frame,
+        index: display.index,
+        length: display.length,
+        atEnd: display.at_end,
+        stopped: display.stopped,
+        valueRepr: display.value_repr
+      });
+      break;
+    case "table":
+      onEvent({
+        kind: "table",
+        columns: display.columns,
+        rows: display.rows,
+        rowCount: display.row_count,
+        shownCount: display.shown_count,
+        truncated: display.truncated,
+        source: fileName
+      });
+      break;
+  }
+}
+function asPlain(value) {
+  if (value instanceof Map) {
+    const obj = {};
+    for (const [k, v] of value.entries()) {
+      obj[String(k)] = asPlain(v);
+    }
+    return obj;
+  }
+  if (Array.isArray(value)) {
+    return value.map(asPlain);
+  }
+  return value;
+}
+function adaptTestCase(raw) {
+  const row = asPlain(raw) ?? {};
+  const line = row.line_number;
   return {
-    headline: "A value does not match the type annotation written for it.",
-    howToFix: [
-      message.split(/\r?\n/)[0].trim(),
-      "Either pass a value of the annotated type, or change the annotation."
-    ]
+    name: String(row.name ?? ""),
+    outcome: String(row.outcome ?? "failed"),
+    lineNumber: typeof line === "number" ? line : null,
+    message: row.message == null ? null : String(row.message),
+    stdout: row.stdout == null ? null : String(row.stdout)
   };
 }
+function deliverTestResult(result, onEvent, fileName) {
+  if (result.internal_error && result.error_type) {
+    onEvent({
+      kind: "error",
+      errorType: result.error_type,
+      message: result.error_message ?? "",
+      traceback: result.traceback ?? "",
+      lineNumber: result.line_number,
+      column: result.column,
+      fileName
+    });
+    onEvent({ kind: "done" });
+    return;
+  }
+  const tests = Array.isArray(result.tests) ? result.tests.map(adaptTestCase) : [];
+  onEvent({
+    kind: "testReport",
+    fileName,
+    passed: result.passed ?? 0,
+    failed: result.failed ?? 0,
+    skipped: result.skipped ?? 0,
+    errors: result.errors ?? 0,
+    tests
+  });
+  onEvent({ kind: "done" });
+}
 
-// src/common/analyzers/typeCheckAnalyzer.ts
-var HANDLED = ["TypeCheckError", "typeguard.TypeCheckError"];
-function messageWithDetail(traceback, fallback) {
-  const lines = traceback.split(/\r?\n/);
-  for (let i = lines.length - 1; i >= 0; i--) {
-    const line = lines[i];
-    const marker = line.indexOf("TypeCheckError:");
-    if (line.startsWith(" ") || marker < 0) continue;
-    const detail = [line.slice(marker + "TypeCheckError:".length).trim()];
-    for (let j = i + 1; j < lines.length; j++) {
-      if (lines[j].trim() === "") continue;
-      if (!lines[j].startsWith(" ")) break;
-      detail.push(lines[j]);
+// src/common/interruptBuffer.ts
+var INTERRUPT_SAB_BYTES = 1;
+var INTERRUPT_SIGINT = 2;
+function tryCreateInterruptBuffer() {
+  try {
+    return new SharedArrayBuffer(INTERRUPT_SAB_BYTES);
+  } catch {
+    return null;
+  }
+}
+function signalInterrupt(sab) {
+  Atomics.store(new Uint8Array(sab), 0, INTERRUPT_SIGINT);
+}
+
+// src/common/stdinBuffer.ts
+var STDIN_SAB_BYTES = 64 * 1024;
+var STDIN_STATE_INDEX = 0;
+var STDIN_LENGTH_INDEX = 1;
+var STDIN_PAYLOAD_OFFSET = 8;
+var STDIN_STATE_LINE = 1;
+var STDIN_STATE_EOF = 2;
+function tryCreateStdinBuffer() {
+  try {
+    return new SharedArrayBuffer(STDIN_SAB_BYTES);
+  } catch {
+    return null;
+  }
+}
+function writeStdinLine(sab, line) {
+  const state = new Int32Array(sab);
+  if (line === null) {
+    Atomics.store(state, STDIN_STATE_INDEX, STDIN_STATE_EOF);
+    Atomics.notify(state, STDIN_STATE_INDEX);
+    return;
+  }
+  const encoded = new TextEncoder().encode(line);
+  const max = sab.byteLength - STDIN_PAYLOAD_OFFSET;
+  const n = Math.min(encoded.length, max);
+  const bytes = new Uint8Array(sab, STDIN_PAYLOAD_OFFSET);
+  bytes.set(encoded.subarray(0, n));
+  Atomics.store(state, STDIN_LENGTH_INDEX, n);
+  Atomics.store(state, STDIN_STATE_INDEX, STDIN_STATE_LINE);
+  Atomics.notify(state, STDIN_STATE_INDEX);
+}
+
+// src/common/workerRuntime.ts
+var WorkerPythonRuntime = class {
+  worker = null;
+  nextId = 1;
+  pending = /* @__PURE__ */ new Map();
+  initPromise = null;
+  stdinBuffer = null;
+  interruptBuffer = null;
+  stdinHandler = null;
+  /** Event sink for the in-flight runFile, so live displays can stream. */
+  live = null;
+  async initialize() {
+    if (!this.initPromise) {
+      this.initPromise = this.doInitialize();
     }
-    return detail.join("\n");
+    await this.initPromise;
   }
-  return fallback;
-}
-var typeCheckAnalyzer = {
-  handles: HANDLED,
-  analyze(input) {
-    const { parsedError, fileName, level } = input;
-    if (!HANDLED.includes(parsedError.errorType)) {
-      return null;
-    }
-    const message = messageWithDetail(parsedError.traceback, parsedError.message);
-    const parsed = parseTypeCheckMessage(message);
-    const frames = userTracebackFrames(parsedError.traceback);
-    const innermost = frames.length > 0 ? frames[frames.length - 1] : null;
-    const blamed = parsed.kind === "argument" && frames.length >= 2 ? frames[frames.length - 2] : innermost;
-    const explanation = explainTypeCheckError(
-      message,
-      innermost ? innermost.functionName : null,
-      level
+  async doInitialize() {
+    const indexUrl = this.resolveIndexUrl();
+    this.worker = this.spawn({
+      onMessage: (msg) => this.handleMessage(msg),
+      onError: (err) => this.rejectAllPending(err)
+    });
+    this.stdinBuffer = tryCreateStdinBuffer();
+    this.interruptBuffer = tryCreateInterruptBuffer();
+    await this.request(
+      {
+        type: "init",
+        indexUrl,
+        ...this.stdinBuffer ? { stdinBuffer: this.stdinBuffer } : {},
+        ...this.interruptBuffer ? { interruptBuffer: this.interruptBuffer } : {}
+      },
+      "ready"
     );
+  }
+  async runFile(request, onEvent) {
+    await this.initialize();
+    this.live = { onEvent, fileName: request.fileName };
+    try {
+      const { result } = await this.request({ type: "runFile", ...request }, "result");
+      deliverRunResult(result, onEvent, request.fileName);
+    } finally {
+      this.live = null;
+    }
+  }
+  async replEval(request, onEvent) {
+    await this.initialize();
+    const { result } = await this.request({ type: "replEval", ...request }, "result");
+    deliverRunResult(result, onEvent, "<repl>");
+  }
+  async checkReplComplete(code) {
+    await this.initialize();
+    const { result } = await this.request({ type: "checkSyntax", code }, "syntax");
     return {
-      id: "type-check",
-      // Not a real Python exception name; "TypeCheckError" means nothing to
-      // a student, and "TypeError" would name a different Python error.
-      errorType: "TypeMismatch",
-      message,
-      headline: explanation.headline,
-      howToFix: explanation.howToFix,
-      fileName: blamed ? blamed.fileName : fileName,
-      lineNumber: blamed ? blamed.line : parsedError.lineNumber,
-      column: null,
-      nameToken: parsed.name,
-      severity: "error",
-      raw: parsedError.traceback,
-      origin: "runtime",
-      level
+      status: result.status,
+      errorType: result.error_type,
+      message: result.message,
+      lineNumber: result.lineno,
+      offset: result.offset
     };
   }
-};
-
-// src/common/analyzers/registry.ts
-var analyzers = [nameErrorAnalyzer, typeCheckAnalyzer];
-function findRuntimeFinding(source, fileName, level, parsedError) {
-  for (const analyzer of analyzers) {
-    if (!analyzer.handles.includes(parsedError.errorType)) {
-      continue;
-    }
-    const finding = analyzer.analyze({ source, fileName, level, parsedError });
-    if (finding) {
-      return finding;
-    }
+  async hasTests(code) {
+    await this.initialize();
+    const { result } = await this.request({ type: "hasTests", code }, "hasTests");
+    return result;
   }
-  return null;
-}
-
-// src/common/analyzers/runtimeFinding.ts
-function findingForErrorEvent(event, source, fileName, level) {
-  const traceback = event.traceback || `${event.errorType}: ${event.message}`;
-  const parsed = parsePythonError(traceback);
-  if (parsed.lineNumber === null && event.lineNumber !== null) {
-    parsed.lineNumber = event.lineNumber;
+  async ensurePackages(code) {
+    await this.initialize();
+    await this.request({ type: "loadPackages", code }, "packagesReady");
   }
-  if (parsed.column === null && event.column !== null) {
-    parsed.column = event.column;
+  async ensurePytest() {
+    await this.initialize();
+    await this.request({ type: "loadPytest" }, "pytestReady");
   }
-  if (parsed.fileName === null && event.fileName) {
-    parsed.fileName = event.fileName;
+  async runTests(request, onEvent) {
+    await this.initialize();
+    const { result } = await this.request(
+      {
+        type: "runTests",
+        code: request.code,
+        fileName: request.fileName,
+        level: request.level
+      },
+      "testResult"
+    );
+    deliverTestResult(result, onEvent, request.fileName);
   }
-  return findRuntimeFinding(source, fileName, level, parsed);
-}
-
-// src/common/pyodideRunner.ts
-var ANY_IMPORT_RE = /(^|\n)[ \t]*(import|from)[ \t]+\S/;
-
-// src/cli/files.ts
-var fs2 = __toESM(require("node:fs/promises"));
-var path3 = __toESM(require("node:path"));
-
-// src/common/workspaceFilePolicy.ts
-var MAX_FILE_BYTES = 2 * 1024 * 1024;
-var MAX_TOTAL_BYTES = 8 * 1024 * 1024;
-var MAX_FILES = 50;
-var MOUNT_EXTENSIONS = /* @__PURE__ */ new Set([
-  ".csv",
-  ".txt",
-  ".tsv",
-  ".json",
-  ".md",
-  ".dat",
-  ".xml",
-  ".py"
-]);
-var WRITEBACK_EXTENSIONS = /* @__PURE__ */ new Set([
-  ".csv",
-  ".txt",
-  ".tsv",
-  ".json",
-  ".md",
-  ".dat",
-  ".xml"
-]);
-function extensionOf(name) {
-  const dot = name.lastIndexOf(".");
-  if (dot <= 0) {
-    return "";
+  async staticAnalyze(request) {
+    await this.initialize();
+    const { result } = await this.request({ type: "staticAnalyze", ...request }, "static");
+    return result ?? [];
   }
-  return name.slice(dot).toLowerCase();
-}
-function isSafeBasename(name) {
-  if (!name || name === "." || name === "..") {
-    return false;
+  async mountWorkspaceFiles(files) {
+    await this.initialize();
+    await this.request({ type: "mountWorkspace", files }, "workspaceReady");
   }
-  if (name.startsWith(".")) {
-    return false;
+  async collectWorkspaceFiles() {
+    await this.initialize();
+    const { files } = await this.request({ type: "collectWorkspace" }, "workspaceFiles");
+    return files;
   }
-  if (name.includes("/") || name.includes("\\") || name.includes("\0")) {
-    return false;
+  async examplarBuild(sources) {
+    await this.initialize();
+    const { result } = await this.request({ type: "examplarBuild", sources }, "examplarBuilt");
+    return result;
   }
-  return true;
-}
-function isMountableName(name) {
-  return isSafeBasename(name) && MOUNT_EXTENSIONS.has(extensionOf(name));
-}
-function isWritebackName(name) {
-  return isSafeBasename(name) && WRITEBACK_EXTENSIONS.has(extensionOf(name));
-}
-function utf8ByteLength(text) {
-  return new TextEncoder().encode(text).byteLength;
-}
-function decodeMountContents(data) {
-  if (data.byteLength > MAX_FILE_BYTES) {
-    return void 0;
+  async examplarRun(testSource, bundle) {
+    await this.initialize();
+    const { result } = await this.request(
+      { type: "examplarRun", testSource, bundle },
+      "examplarRan"
+    );
+    return result;
   }
-  for (let i = 0; i < data.byteLength; i++) {
-    if (data[i] === 0) {
-      return void 0;
-    }
+  async reactorStep(reactorId, event) {
+    await this.initialize();
+    const { result } = await this.request(
+      { type: "reactorStep", reactorId, event },
+      "reactorFrame"
+    );
+    return result;
   }
-  return new TextDecoder("utf-8").decode(data);
-}
-function selectMountableFiles(candidates) {
-  const selected = [];
-  let total = 0;
-  for (const candidate of candidates) {
-    if (selected.length >= MAX_FILES) {
-      break;
-    }
-    if (!isMountableName(candidate.name)) {
-      continue;
-    }
-    let text;
-    if (typeof candidate.contents === "string") {
-      if (utf8ByteLength(candidate.contents) > MAX_FILE_BYTES) {
-        continue;
-      }
-      if (candidate.contents.includes("\0")) {
-        continue;
-      }
-      text = candidate.contents;
-    } else {
-      const decoded = decodeMountContents(candidate.contents);
-      if (decoded === void 0) {
-        continue;
-      }
-      text = decoded;
+  async reactorSeek(reactorId, index) {
+    await this.initialize();
+    const { result } = await this.request(
+      { type: "reactorSeek", reactorId, index },
+      "reactorFrame"
+    );
+    return result;
+  }
+  async reactorDispose(reactorId) {
+    await this.initialize();
+    await this.request({ type: "reactorDispose", reactorId }, "reactorDisposed");
+  }
+  interrupt() {
+    if (!this.interruptBuffer) {
+      return false;
     }
-    const size = utf8ByteLength(text);
-    if (total + size > MAX_TOTAL_BYTES) {
-      continue;
+    signalInterrupt(this.interruptBuffer);
+    return true;
+  }
+  setStdinHandler(handler) {
+    this.stdinHandler = handler;
+  }
+  dispose() {
+    this.worker?.terminate();
+    this.worker = null;
+    this.initPromise = null;
+    this.stdinBuffer = null;
+    this.interruptBuffer = null;
+    this.live = null;
+    this.rejectAllPending(new Error("Runtime disposed"));
+  }
+  /** Send `msg` and resolve with the reply, asserting it is of type `expected`. */
+  async request(msg, expected) {
+    const worker = this.worker;
+    if (!worker) {
+      throw new Error("Worker not initialized");
     }
-    selected.push({ name: candidate.name, contents: text });
-    total += size;
+    const id = this.nextId++;
+    const reply = await new Promise((resolve4, reject) => {
+      this.pending.set(id, { resolve: resolve4, reject });
+      worker.post({ id, ...msg });
+    });
+    if (reply.type !== expected) {
+      throw new Error(`Pyodide worker replied "${reply.type}", expected "${expected}"`);
+    }
+    return reply;
   }
-  return selected;
-}
-function selectWritebackFiles(files) {
-  const selected = [];
-  let total = 0;
-  for (const file of files) {
-    if (selected.length >= MAX_FILES) {
-      break;
+  handleMessage(msg) {
+    if (msg.type === "display") {
+      if (this.live) {
+        deliverDisplay(msg.payload, this.live.onEvent, this.live.fileName);
+      }
+      return;
     }
-    if (!isWritebackName(file.name)) {
-      continue;
+    if (msg.type === "stdinRequest") {
+      void this.handleStdinRequest();
+      return;
     }
-    const size = utf8ByteLength(file.contents);
-    if (size > MAX_FILE_BYTES || total + size > MAX_TOTAL_BYTES) {
-      continue;
+    const pending = this.pending.get(msg.id);
+    if (!pending) {
+      return;
     }
-    if (file.contents.includes("\0")) {
-      continue;
+    this.pending.delete(msg.id);
+    if (msg.type === "error") {
+      pending.reject(new Error(msg.message));
+    } else {
+      pending.resolve(msg);
     }
-    selected.push(file);
-    total += size;
-  }
-  return selected;
-}
-
-// src/cli/files.ts
-async function collectSiblingFiles(scriptPath) {
-  const folder = path3.dirname(path3.resolve(scriptPath));
-  let entries;
-  try {
-    entries = await fs2.readdir(folder, { withFileTypes: true });
-  } catch {
-    return [];
   }
-  const candidates = [];
-  for (const entry of entries) {
-    if (!entry.isFile() || !isMountableName(entry.name)) {
-      continue;
-    }
-    try {
-      candidates.push({ name: entry.name, contents: await fs2.readFile(path3.join(folder, entry.name)) });
-    } catch {
+  rejectAllPending(err) {
+    for (const pending of this.pending.values()) {
+      pending.reject(err);
     }
+    this.pending.clear();
   }
-  return selectMountableFiles(candidates);
-}
-async function writeBackSiblingFiles(scriptPath, files) {
-  const folder = path3.dirname(path3.resolve(scriptPath));
-  const written = [];
-  for (const file of selectWritebackFiles(files)) {
+  async handleStdinRequest() {
+    let line = null;
     try {
-      await fs2.writeFile(path3.join(folder, file.name), file.contents, "utf8");
-      written.push(file.name);
+      line = this.stdinHandler ? await this.stdinHandler() : null;
     } catch {
+      line = null;
     }
-  }
-  return written;
-}
-
-// src/cli/run.ts
-var EXIT = {
-  ok: 0,
-  /** The program raised. */
-  programError: 1,
-  /** Level checks found problems, so the file was not run. */
-  blocked: 2,
-  /** The program ran, but its in-file tests did not all pass. */
-  testsFailed: 3,
-  /** Bad usage, or PLL itself could not run. */
-  usage: 64
-};
-async function runFile(runtime, view, opts) {
-  const fileName = path4.basename(opts.file);
-  let source;
-  try {
-    source = await fs3.readFile(opts.file, "utf8");
-  } catch (err) {
-    view.problem(`Cannot read ${opts.file}: ${errText(err)}`);
-    return EXIT.usage;
-  }
-  const level = parseLevel(source);
-  view.note(`${fileName} [${level}]`);
-  if (levelHasStaticChecks(level)) {
-    const blocked = await staticChecks(runtime, view, source, fileName, level);
-    if (blocked) {
-      return EXIT.blocked;
-    }
-  }
-  await ensurePackages(runtime, view, source);
-  try {
-    await runtime.mountWorkspaceFiles(await collectSiblingFiles(opts.file));
-  } catch (err) {
-    view.note(`Could not load files next to this script (${errText(err)}).`);
-  }
-  const onEvent = (event) => {
-    if (event.kind === "error") {
-      const finding = findingForErrorEvent(event, source, fileName, level);
-      if (finding) {
-        view.runtimeFinding(finding);
-        return;
-      }
+    if (this.stdinBuffer) {
+      writeStdinLine(this.stdinBuffer, line);
     }
-    view.handle(event);
-  };
-  if (opts.runTests) {
-    await maybeRunTests(runtime, view, source, fileName, level, onEvent);
-  }
-  await runtime.runFile({ code: source, fileName, sessionKey: opts.file, level }, onEvent);
-  await writeBack(runtime, view, opts.file);
-  if (view.sawError) return EXIT.programError;
-  if (view.testFailures > 0) return EXIT.testsFailed;
-  return EXIT.ok;
-}
-async function staticChecks(runtime, view, source, fileName, level) {
-  let raw;
-  try {
-    raw = await runtime.staticAnalyze({ code: source, fileName, level });
-  } catch (err) {
-    view.note(`Static analysis failed (${errText(err)}); running anyway.`);
-    return false;
-  }
-  const findings = enrichStaticFindings(raw, level, fileName);
-  if (findings.length === 0) {
-    return false;
-  }
-  view.findings(findings);
-  view.problem(`Static analysis found ${findings.length} problem(s). File not run.`);
-  return true;
-}
-async function ensurePackages(runtime, view, source) {
-  if (!ANY_IMPORT_RE.test(source)) {
-    return;
   }
-  try {
-    await runtime.ensurePackages(source);
-  } catch (err) {
-    const message = errText(err);
-    if (!/syntaxerror|invalid syntax/i.test(message)) {
-      view.note(`Could not load libraries (${message}). Continuing.`);
-    }
+};
+
+// src/desktop/pyodideRuntime.ts
+var DesktopPyodideRuntime = class extends WorkerPythonRuntime {
+  constructor(paths) {
+    super();
+    this.paths = paths;
   }
-}
-async function maybeRunTests(runtime, view, source, fileName, level, onEvent) {
-  try {
-    if (!await runtime.hasTests(source)) {
-      return;
+  paths;
+  resolveIndexUrl() {
+    const found = this.paths.indexUrlCandidates.find(
+      (dir) => fs4.existsSync(path4.join(dir, "pyodide.asm.wasm"))
+    );
+    if (!found) {
+      throw new Error(this.paths.missingAssetsHint);
     }
-    await runtime.ensurePytest();
-  } catch (err) {
-    view.note(`Could not check for tests (${errText(err)}); skipping them.`);
-    return;
+    return found;
   }
-  await runtime.runTests({ code: source, fileName, sessionKey: fileName, level }, onEvent);
-}
-async function writeBack(runtime, view, file) {
-  try {
-    const changed = await runtime.collectWorkspaceFiles();
-    if (changed.length === 0) {
-      return;
-    }
-    const written = await writeBackSiblingFiles(file, changed);
-    if (written.length > 0) {
-      view.note(`Saved ${written.join(", ")} next to ${path4.basename(file)}.`);
-    }
-  } catch (err) {
-    view.note(`Could not save files next to this script (${errText(err)}).`);
+  spawn(handlers) {
+    const worker = new import_node_worker_threads.Worker(this.paths.workerPath);
+    worker.on("message", (msg) => handlers.onMessage(msg));
+    worker.on(
+      "error",
+      (err) => handlers.onError(err instanceof Error ? err : new Error(String(err)))
+    );
+    return {
+      post: (msg) => worker.postMessage(msg),
+      terminate: () => void worker.terminate()
+    };
   }
-}
-function errText(err) {
-  return err instanceof Error ? err.message : String(err);
+};
+
+// src/cli/runtime.ts
+function createCliRuntime() {
+  return new DesktopPyodideRuntime({
+    // `pyodide` is external in the bundle, so this resolves at run time
+    // from the installed package rather than being inlined.
+    indexUrlCandidates: [path5.dirname(require.resolve("pyodide"))],
+    workerPath: path5.join(__dirname, "worker.cjs"),
+    missingAssetsHint: "Could not find Pyodide's assets. Reinstall pll-python so its `pyodide` dependency is present."
+  });
 }
 
 // src/cli/stdin.ts
@@ -1381,7 +1668,7 @@ function createLineReader() {
         return Promise.resolve(null);
       }
       ensure();
-      return new Promise((resolve3) => pending.push(resolve3));
+      return new Promise((resolve4) => pending.push(resolve4));
     },
     close() {
       closed = true;
@@ -1392,8 +1679,8 @@ function createLineReader() {
 }
 
 // src/cli/view.ts
-var fs4 = __toESM(require("node:fs"));
-var path5 = __toESM(require("node:path"));
+var fs5 = __toESM(require("node:fs"));
+var path6 = __toESM(require("node:path"));
 
 // src/common/analyzers/findingLocation.ts
 function findingLocation(finding) {
@@ -1532,10 +1819,10 @@ var CliView = class {
       );
       return;
     }
-    const target = path5.join(dir, `image-${this.imageCount}.svg`);
+    const target = path6.join(dir, `image-${this.imageCount}.svg`);
     try {
-      fs4.mkdirSync(dir, { recursive: true });
-      fs4.writeFileSync(target, svg, "utf8");
+      fs5.mkdirSync(dir, { recursive: true });
+      fs5.writeFileSync(target, svg, "utf8");
       this.note(this.dim(`[image ${width}x${height} -> ${target}]`));
     } catch (err) {
       this.problem(`Could not write ${target}: ${errText2(err)}`);
@@ -1591,6 +1878,9 @@ The level comes from the file's own \`#level\` line, exactly as in the
 editor; there is deliberately no flag to override it, so a file behaves the
 same everywhere.
 
+Subcommands
+  examplar build       author an Examplar bundle; see \`pll examplar --help\`
+
 Options
   --no-tests           do not run the file's \`test_*\` functions first
   --save-images <dir>  write pictures there as .svg (they cannot be drawn
@@ -1607,12 +1897,14 @@ Exit codes
   0  ran, tests passed        2  level checks blocked it
   1  the program raised       3  a test failed
 `;
+function colorDefault() {
+  return process.stderr.isTTY === true && !process.env.NO_COLOR;
+}
 function parseArgs(argv) {
   const args = {
     runTests: true,
     quiet: false,
-    // Colour only when stderr is a terminal, and never when NO_COLOR is set.
-    color: process.stderr.isTTY === true && !process.env.NO_COLOR,
+    color: colorDefault(),
     help: false,
     version: false
   };
@@ -1649,13 +1941,31 @@ function parseArgs(argv) {
   return args;
 }
 async function main(argv) {
+  const firstPositional = argv.find((arg) => !arg.startsWith("-"));
+  if (firstPositional === "examplar") {
+    const at = argv.indexOf("examplar");
+    const leading = argv.slice(0, at);
+    const view2 = new CliView({
+      quiet: leading.includes("-q") || leading.includes("--quiet"),
+      color: colorDefault() && !leading.includes("--no-color")
+    });
+    const runtime2 = createCliRuntime();
+    try {
+      return await runExamplar(runtime2, view2, argv.slice(at + 1));
+    } catch (err) {
+      view2.problem(`pll: ${err instanceof Error ? err.message : String(err)}`);
+      return EXIT.usage;
+    } finally {
+      runtime2.dispose();
+    }
+  }
   const args = parseArgs(argv);
   if (args.help) {
     process.stdout.write(USAGE);
     return EXIT.ok;
   }
   if (args.version) {
-    process.stdout.write("0.1.0\n");
+    process.stdout.write("0.1.2\n");
     return EXIT.ok;
   }
   if (args.error !== void 0) {
@@ -1686,7 +1996,7 @@ ${USAGE}`);
   process.on("SIGINT", onSigint);
   try {
     return await runFile(runtime, view, {
-      file: path6.resolve(args.file),
+      file: path7.resolve(args.file),
       runTests: args.runTests
     });
   } catch (err) {