@ttsc/playground 0.30.4 → 0.31.1

package/lib/src/compiler/loadTypiaSourcePack.d.ts

@@ -1,10 +1,32 @@
 import type { IInstallTypiaSourcePackOptions } from "../structures/IInstallTypiaSourcePackOptions";
 /**
- * Fetch the typia source pack JSON once per URL.
+ * Fetch the typia source pack JSON once per URL and transport identity.
  *
  * Concurrent callers share one load. A caller abort cancels that shared
  * attempt; rejection removes it from the cache so the next call retries from
  * scratch. Nothing else ends the load: how long a fetch takes belongs to the
  * network, not to a number chosen here.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   The source-pack loader uses fetch/AbortController and Promise sharing,
+ *   with an explicit fetch injection seam for the same transport contract. It
+ *   supplies source records to the existing mounting operation rather than
+ *   coupling network loading to compiler execution.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One transport-specific URL map owns attempt sharing; cancellation helpers
+ *   keep event ownership separate from response decoding and source mounting.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The site supplies the URL and transport; no package name, test case or
+ *   fixed deadline decides success. The injected transport leaves global fetch
+ *   intact. Rejection evicts only this attempt, preserving the real failure
+ *   instead of inventing a successful empty source pack.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   JSDoc explains the once-per-URL purpose, shared cancellation, rejection
+ *   eviction and why an arbitrary timeout is not the network policy. Purpose
+ *   and reasons use separate native paragraphs under the documentation skill;
+ *   IInstallTypiaSourcePackOptions owns option documentation.
  */
 export declare function loadTypiaSourcePack(options: IInstallTypiaSourcePackOptions): Promise<Record<string, string>>;

package/lib/src/compiler/loadTypiaSourcePack.js

@@ -1,46 +1,82 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadTypiaSourcePack = loadTypiaSourcePack;
-const packCache = new Map();
+const packCaches = new WeakMap();
 /**
- * Fetch the typia source pack JSON once per URL.
+ * Fetch the typia source pack JSON once per URL and transport identity.
  *
  * Concurrent callers share one load. A caller abort cancels that shared
  * attempt; rejection removes it from the cache so the next call retries from
  * scratch. Nothing else ends the load: how long a fetch takes belongs to the
  * network, not to a number chosen here.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   The source-pack loader uses fetch/AbortController and Promise sharing,
+ *   with an explicit fetch injection seam for the same transport contract. It
+ *   supplies source records to the existing mounting operation rather than
+ *   coupling network loading to compiler execution.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One transport-specific URL map owns attempt sharing; cancellation helpers
+ *   keep event ownership separate from response decoding and source mounting.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The site supplies the URL and transport; no package name, test case or
+ *   fixed deadline decides success. The injected transport leaves global fetch
+ *   intact. Rejection evicts only this attempt, preserving the real failure
+ *   instead of inventing a successful empty source pack.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   JSDoc explains the once-per-URL purpose, shared cancellation, rejection
+ *   eviction and why an arbitrary timeout is not the network policy. Purpose
+ *   and reasons use separate native paragraphs under the documentation skill;
+ *   IInstallTypiaSourcePackOptions owns option documentation.
  */
 function loadTypiaSourcePack(options) {
-    const cached = packCache.get(options.url);
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (!fetchImpl) {
+        throw new Error("loadTypiaSourcePack: no fetch implementation available in this environment.");
+    }
+    let packCache = packCaches.get(fetchImpl);
+    if (!packCache) {
+        packCache = new Map();
+        packCaches.set(fetchImpl, packCache);
+    }
+    const cache = packCache;
+    const cached = cache.get(options.url);
     if (cached) {
         attachSourcePackCancellation(cached, options.signal);
         return cached.promise;
     }
-    const fetchImpl = options.fetch ?? globalThis.fetch?.bind(globalThis);
-    if (!fetchImpl) {
-        throw new Error("loadTypiaSourcePack: no fetch implementation available in this environment.");
-    }
     const url = options.url;
+    const fetchPack = options.fetch ? fetchImpl : fetchImpl.bind(globalThis);
     const controller = new AbortController();
     let phase = `fetching ${url}`;
     const cancellation = createSourcePackCancellation(controller.signal, () => phase);
     let entry;
     const promise = (async () => {
-        const response = await raceSourcePackCancellation(fetchImpl(url, { signal: controller.signal }), cancellation.promise, controller.signal, () => phase);
+        const response = await raceSourcePackCancellation(fetchPack(url, { signal: controller.signal }), cancellation.promise, controller.signal, () => phase);
         if (!response.ok) {
             throw new Error(`loadTypiaSourcePack: failed to fetch ${url}: ${response.status}`);
         }
         phase = `reading JSON from ${url}`;
-        return (await raceSourcePackCancellation(response.json(), cancellation.promise, controller.signal, () => phase));
+        const pack = await raceSourcePackCancellation(response.json(), cancellation.promise, controller.signal, () => phase);
+        if (!pack ||
+            typeof pack !== "object" ||
+            Array.isArray(pack) ||
+            !Object.values(pack).every((value) => typeof value === "string")) {
+            throw new Error("loadTypiaSourcePack: expected a source-text record map.");
+        }
+        return pack;
     })()
         .catch((error) => {
-        if (packCache.get(url) === entry)
-            packCache.delete(url);
+        if (cache.get(url) === entry)
+            cache.delete(url);
         throw error;
     })
         .finally(cancellation.dispose);
     entry = { controller, promise };
-    packCache.set(url, entry);
+    cache.set(url, entry);
     attachSourcePackCancellation(entry, options.signal);
     return promise;
 }

package/lib/src/compiler/loadTypiaSourcePack.js.map

@@ -1 +1 @@
-{"version":3,"file":"loadTypiaSourcePack.js","sourceRoot":"","sources":["../../../src/compiler/loadTypiaSourcePack.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"loadTypiaSourcePack.js","sourceRoot":"","sources":["../../../src/compiler/loadTypiaSourcePack.ts"],"names":[],"mappings":";;;AAiBA,MAAM,UAAU,GAAG,IAAI,OAAO,EAG3B,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,6BACE,OAAuC;IAEvC,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC;IACpD,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,6EAA6E,CAC9E,CAAC;IACJ,CAAC;IAED,IAAI,SAAS,GAAG,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAC1C,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,SAAS,GAAG,IAAI,GAAG,EAAE,CAAC;QACtB,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IACvC,CAAC;IACD,MAAM,KAAK,GAAG,SAAS,CAAC;IACxB,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACtC,IAAI,MAAM,EAAE,CAAC;QACX,4BAA4B,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QACrD,OAAO,MAAM,CAAC,OAAO,CAAC;IACxB,CAAC;IAED,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IACxB,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACzE,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,IAAI,KAAK,GAAG,YAAY,GAAG,EAAE,CAAC;IAC9B,MAAM,YAAY,GAAG,4BAA4B,CAC/C,UAAU,CAAC,MAAM,EACjB,GAAG,EAAE,CAAC,KAAK,CACZ,CAAC;IACF,IAAI,KAAuB,CAAC;IAC5B,MAAM,OAAO,GAAG,CAAC,KAAK,IAAI,EAAE;QAC1B,MAAM,QAAQ,GAAG,MAAM,0BAA0B,CAC/C,SAAS,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC,EAC7C,YAAY,CAAC,OAAO,EACpB,UAAU,CAAC,MAAM,EACjB,GAAG,EAAE,CAAC,KAAK,CACZ,CAAC;QACF,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CACb,wCAAwC,GAAG,KAAK,QAAQ,CAAC,MAAM,EAAE,CAClE,CAAC;QACJ,CAAC;QAED,KAAK,GAAG,qBAAqB,GAAG,EAAE,CAAC;QACnC,MAAM,IAAI,GAAY,MAAM,0BAA0B,CACpD,QAAQ,CAAC,IAAI,EAAE,EACf,YAAY,CAAC,OAAO,EACpB,UAAU,CAAC,MAAM,EACjB,GAAG,EAAE,CAAC,KAAK,CACZ,CAAC;QACF,IACE,CAAC,IAAI;YACL,OAAO,IAAI,KAAK,QAAQ;YACxB,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;YACnB,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,EAChE,CAAC;YACD,MAAM,IAAI,KAAK,CACb,yDAAyD,CAC1D,CAAC;QACJ,CAAC;QACD,OAAO,IAA8B,CAAC;IACxC,CAAC,CAAC,EAAE;SACD,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;QACf,IAAI,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,KAAK;YAAE,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAChD,MAAM,KAAK,CAAC;IACd,CAAC,CAAC;SACD,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;IAEjC,KAAK,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;IAChC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACtB,4BAA4B,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACpD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,4BAA4B,CACnC,KAAsB,EACtB,YAAqC;IAErC,MAAM,eAAe,GAAG,GAAS,EAAE;QACjC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACrC,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC;gBACrB,IAAI,EAAE,OAAO;gBACb,MAAM,EAAE,YAAY,EAAE,MAAM;aACU,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC,CAAC;IACF,IAAI,YAAY,EAAE,OAAO;QAAE,eAAe,EAAE,CAAC;;QACxC,YAAY,EAAE,gBAAgB,CAAC,OAAO,EAAE,eAAe,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAE9E,MAAM,OAAO,GAAG,GAAS,EAAE;QACzB,YAAY,EAAE,mBAAmB,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;IAC9D,CAAC,CAAC;IACF,KAAK,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAC5C,CAAC;AAED,SAAS,4BAA4B,CACnC,MAAmB,EACnB,QAAsB;IAEtB,IAAI,kBAA2C,CAAC;IAChD,MAAM,OAAO,GAAG,IAAI,OAAO,CAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE;QACtD,kBAAkB,GAAG,MAAM,CAAC;IAC9B,CAAC,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,GAAS,EAAE;QACzB,kBAAkB,CAAC,2BAA2B,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;IACtE,CAAC,CAAC;IACF,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1D,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IAC9B,OAAO;QACL,OAAO;QACP,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC;KAC5D,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,0BAA0B,CACvC,IAAgB,EAChB,YAA4B,EAC5B,MAAmB,EACnB,QAAsB;IAEtB,IAAI,CAAC;QACH,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC;IAClD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,MAAM,2BAA2B,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;QACxD,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,2BAA2B,CAClC,MAAmB,EACnB,KAAa;IAEb,MAAM,MAAM,GAAG,MAAM,CAAC,MAAkD,CAAC;IACzE,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,sCAAsC,KAAK,GAAG,CAAC,CAAC;IACxE,MAAM,KAAK,GAAG,MAAM,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC;IACvE,IAAI,KAAK,KAAK,SAAS;QAAG,KAAqC,CAAC,KAAK,GAAG,KAAK,CAAC;IAC9E,OAAO,KAAK,CAAC;AACf,CAAC"}

package/lib/src/compiler/mapDiagnostic.d.ts

@@ -3,7 +3,12 @@ import type { ICompilerService } from "../structures/ICompilerService";
 /**
  * Convert a `@ttsc/wasm` diagnostic into the playground's normalized shape.
  *
- * Falls back to computing line/column from the source text when the wasm
- * diagnostic did not carry them (some plugin emitters drop them).
+ * Native positions and spans count UTF-8 bytes; the editor counts UTF-16 units.
+ * Source text converts that boundary, including optional coordinates.
+ *
+ * @evidence contracts/common.md#principled-implementation Native byte offsets and spans are converted against the same source into UTF-16 editor coordinates; optional line/byte-column metadata supplies the start only when the absolute offset is absent.
+ * @evidence contracts/common.md#clear-and-simple-design A single mapping keeps WASM diagnostic fields and UI conventions separate from rendering.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Fallback is based on omitted producer metadata, not special casing a diagnostic code or source fixture.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains producer-to-UI conversion and fallback purpose, following documentation-skill paragraph separation.
  */
 export declare function mapDiagnostic(diag: NonNullable<ITtscCompileResult["diagnostics"]>[number], source: string): ICompilerService.IDiagnostic;

package/lib/src/compiler/mapDiagnostic.js

@@ -5,18 +5,65 @@ const lineColumnOf_1 = require("./lineColumnOf");
 /**
  * Convert a `@ttsc/wasm` diagnostic into the playground's normalized shape.
  *
- * Falls back to computing line/column from the source text when the wasm
- * diagnostic did not carry them (some plugin emitters drop them).
+ * Native positions and spans count UTF-8 bytes; the editor counts UTF-16 units.
+ * Source text converts that boundary, including optional coordinates.
+ *
+ * @evidence contracts/common.md#principled-implementation Native byte offsets and spans are converted against the same source into UTF-16 editor coordinates; optional line/byte-column metadata supplies the start only when the absolute offset is absent.
+ * @evidence contracts/common.md#clear-and-simple-design A single mapping keeps WASM diagnostic fields and UI conventions separate from rendering.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Fallback is based on omitted producer metadata, not special casing a diagnostic code or source fixture.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains producer-to-UI conversion and fallback purpose, following documentation-skill paragraph separation.
  */
 function mapDiagnostic(diag, source) {
-    const fallback = (0, lineColumnOf_1.lineColumnOf)(source, diag.start);
+    const start = typeof diag.start === "number" &&
+        Number.isFinite(diag.start) &&
+        diag.start >= 0
+        ? utf16OffsetOfBytes(source, diag.start)
+        : optionalStart(source, diag.line, diag.character);
+    const location = (0, lineColumnOf_1.lineColumnOf)(source, start);
+    const byteLength = typeof diag.length === "number" && Number.isFinite(diag.length)
+        ? Math.max(0, Math.trunc(diag.length))
+        : 0;
+    const end = utf16OffsetOfBytes(source, byteLength, start);
     return {
-        line: diag.line && diag.line > 0 ? diag.line : fallback.line,
-        column: diag.character && diag.character > 0 ? diag.character : fallback.column,
-        length: typeof diag.length === "number" ? diag.length : 1,
+        line: location.line,
+        column: location.column,
+        length: Math.max(1, end - start),
         severity: diag.category === "warning" ? "warning" : "error",
         message: diag.messageText,
         code: typeof diag.code === "number" ? `TS${diag.code}` : String(diag.code),
     };
 }
+/** Convert a UTF-8 byte boundary to its JavaScript string offset. */
+function utf16OffsetOfBytes(source, bytes, start = 0) {
+    let offset = start;
+    let consumed = 0;
+    while (offset < source.length && consumed < bytes) {
+        const code = source.codePointAt(offset);
+        const width = code <= 0x7f ? 1 : code <= 0x7ff ? 2 : code <= 0xffff ? 3 : 4;
+        if (consumed + width > bytes)
+            break;
+        consumed += width;
+        offset += code > 0xffff ? 2 : 1;
+    }
+    return offset;
+}
+/** Optional native line and byte-column metadata uses the same source domain. */
+function optionalStart(source, line, character) {
+    let start = 0;
+    const targetLine = typeof line === "number" && Number.isFinite(line)
+        ? Math.max(1, Math.trunc(line))
+        : 1;
+    for (let current = 1; current < targetLine && start < source.length; ++current) {
+        while (start < source.length &&
+            ![10, 13, 0x2028, 0x2029].includes(source.charCodeAt(start)))
+            ++start;
+        const code = source.charCodeAt(start++);
+        if (code === 13 && source.charCodeAt(start) === 10)
+            ++start;
+    }
+    const column = typeof character === "number" && Number.isFinite(character)
+        ? Math.max(0, Math.trunc(character) - 1)
+        : 0;
+    return Math.min(source.length, utf16OffsetOfBytes(source, column, start));
+}
 //# sourceMappingURL=mapDiagnostic.js.map

package/lib/src/compiler/mapDiagnostic.js.map

@@ -1 +1 @@
-{"version":3,"file":"mapDiagnostic.js","sourceRoot":"","sources":["../../../src/compiler/mapDiagnostic.ts"],"names":[],"mappings":";;;AAGA,iDAA8C;AAE9C;;;;;GAKG;AACH,uBACE,IAA4D,EAC5D,MAAc;IAEd,MAAM,QAAQ,GAAG,IAAA,2BAAY,EAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IAClD,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI;QAC5D,MAAM,EACJ,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM;QACzE,MAAM,EAAE,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACzD,QAAQ,EAAE,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO;QAC3D,OAAO,EAAE,IAAI,CAAC,WAAW;QACzB,IAAI,EAAE,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC;KAC3E,CAAC;AACJ,CAAC"}
+{"version":3,"file":"mapDiagnostic.js","sourceRoot":"","sources":["../../../src/compiler/mapDiagnostic.ts"],"names":[],"mappings":";;;AAGA,iDAA8C;AAE9C;;;;;;;;;;GAUG;AACH,uBACE,IAA4D,EAC5D,MAAc;IAEd,MAAM,KAAK,GACT,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ;QAC9B,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,KAAK,IAAI,CAAC;QACb,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC;QACxC,CAAC,CAAC,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IACvD,MAAM,QAAQ,GAAG,IAAA,2BAAY,EAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC7C,MAAM,UAAU,GACd,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC;QAC7D,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACtC,CAAC,CAAC,CAAC,CAAC;IACR,MAAM,GAAG,GAAG,kBAAkB,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC;IAC1D,OAAO;QACL,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,GAAG,KAAK,CAAC;QAChC,QAAQ,EAAE,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO;QAC3D,OAAO,EAAE,IAAI,CAAC,WAAW;QACzB,IAAI,EAAE,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC;KAC3E,CAAC;AACJ,CAAC;AAED,qEAAqE;AACrE,SAAS,kBAAkB,CAAC,MAAc,EAAE,KAAa,EAAE,KAAK,GAAG,CAAC;IAClE,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,OAAO,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,QAAQ,GAAG,KAAK,EAAE,CAAC;QAClD,MAAM,IAAI,GAAG,MAAM,CAAC,WAAW,CAAC,MAAM,CAAE,CAAC;QACzC,MAAM,KAAK,GAAG,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5E,IAAI,QAAQ,GAAG,KAAK,GAAG,KAAK;YAAE,MAAM;QACpC,QAAQ,IAAI,KAAK,CAAC;QAClB,MAAM,IAAI,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,iFAAiF;AACjF,SAAS,aAAa,CACpB,MAAc,EACd,IAAwB,EACxB,SAA6B;IAE7B,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,MAAM,UAAU,GACd,OAAO,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;QAC/C,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC/B,CAAC,CAAC,CAAC,CAAC;IACR,KACE,IAAI,OAAO,GAAG,CAAC,EACf,OAAO,GAAG,UAAU,IAAI,KAAK,GAAG,MAAM,CAAC,MAAM,EAC7C,EAAE,OAAO,EACT,CAAC;QACD,OACE,KAAK,GAAG,MAAM,CAAC,MAAM;YACrB,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;YAE5D,EAAE,KAAK,CAAC;QACV,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC;QACxC,IAAI,IAAI,KAAK,EAAE,IAAI,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE;YAAE,EAAE,KAAK,CAAC;IAC9D,CAAC;IACD,MAAM,MAAM,GACV,OAAO,SAAS,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC;QACzD,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QACxC,CAAC,CAAC,CAAC,CAAC;IACR,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;AAC5E,CAAC"}

package/lib/src/compiler/normalizeError.d.ts

@@ -1,2 +1,10 @@
-/** Best-effort error normalization for tgrid transport. */
+/**
+ * Normalize native errors to enumerable fields for tgrid transport; preserve
+ * message-bearing records and stringify other thrown values.
+ *
+ * @evidence contracts/common.md#principled-implementation Explicit Error field copying preserves non-enumerable message and stack while carrying the terminal-runtime string code across RPC.
+ * @evidence contracts/common.md#clear-and-simple-design One normalization boundary leaves rendering and recovery classification to their consumers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The mapper carries actual errors without converting rejection into fabricated compiler success.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states copying and preservation policies, separated from tags under the documentation skill.
+ */
 export declare function normalizeError(error: unknown): unknown;

package/lib/src/compiler/normalizeError.js

@@ -1,7 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeError = normalizeError;
-/** Best-effort error normalization for tgrid transport. */
+/**
+ * Normalize native errors to enumerable fields for tgrid transport; preserve
+ * message-bearing records and stringify other thrown values.
+ *
+ * @evidence contracts/common.md#principled-implementation Explicit Error field copying preserves non-enumerable message and stack while carrying the terminal-runtime string code across RPC.
+ * @evidence contracts/common.md#clear-and-simple-design One normalization boundary leaves rendering and recovery classification to their consumers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The mapper carries actual errors without converting rejection into fabricated compiler success.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states copying and preservation policies, separated from tags under the documentation skill.
+ */
 function normalizeError(error) {
     if (error instanceof Error) {
         const normalized = {

package/lib/src/compiler/normalizeError.js.map

@@ -1 +1 @@
-{"version":3,"file":"normalizeError.js","sourceRoot":"","sources":["../../../src/compiler/normalizeError.ts"],"names":[],"mappings":";;;AAAA,2DAA2D;AAC3D,wBAA+B,KAAc;IAC3C,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,MAAM,UAAU,GAKZ;YACF,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,KAAK,EAAE,KAAK,CAAC,KAAK;SACnB,CAAC;QACF,MAAM,IAAI,GAAI,KAAoC,CAAC,IAAI,CAAC;QACxD,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,UAAU,CAAC,IAAI,GAAG,IAAI,CAAC;QACrD,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,IACE,KAAK;QACL,OAAO,KAAK,KAAK,QAAQ;QACzB,SAAS,IAAK,KAAiC;QAE/C,OAAO,KAAK,CAAC;IACf,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AACnD,CAAC"}
+{"version":3,"file":"normalizeError.js","sourceRoot":"","sources":["../../../src/compiler/normalizeError.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;GAQG;AACH,wBAA+B,KAAc;IAC3C,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,MAAM,UAAU,GAKZ;YACF,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,KAAK,EAAE,KAAK,CAAC,KAAK;SACnB,CAAC;QACF,MAAM,IAAI,GAAI,KAAoC,CAAC,IAAI,CAAC;QACxD,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,UAAU,CAAC,IAAI,GAAG,IAAI,CAAC;QACrD,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,IACE,KAAK;QACL,OAAO,KAAK,KAAK,QAAQ;QACzB,SAAS,IAAK,KAAiC;QAE/C,OAAO,KAAK,CAAC;IACf,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AACnD,CAAC"}

package/lib/src/compiler/normalizeNodeModulePath.d.ts

@@ -4,5 +4,10 @@
  *
  * Returns `null` for paths that don't match the expected shape — the caller
  * skips those entries instead of writing them to the MemFS.
+ *
+ * @evidence contracts/common.md#principled-implementation Separator normalization establishes the virtual namespace, prefix checking restricts writes to node_modules and rejecting parent segments prevents root escape.
+ * @evidence contracts/common.md#clear-and-simple-design One path gate returns a normalized key or null; callers own writes and rejection policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The same structural checks apply to every package entry without allowlisting consumers.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain accepted spelling, confinement and null meaning under the documentation skill.
  */
 export declare function normalizeNodeModulePath(path: string): string | null;

package/lib/src/compiler/normalizeNodeModulePath.js

@@ -7,6 +7,11 @@ exports.normalizeNodeModulePath = normalizeNodeModulePath;
  *
  * Returns `null` for paths that don't match the expected shape — the caller
  * skips those entries instead of writing them to the MemFS.
+ *
+ * @evidence contracts/common.md#principled-implementation Separator normalization establishes the virtual namespace, prefix checking restricts writes to node_modules and rejecting parent segments prevents root escape.
+ * @evidence contracts/common.md#clear-and-simple-design One path gate returns a normalized key or null; callers own writes and rejection policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The same structural checks apply to every package entry without allowlisting consumers.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain accepted spelling, confinement and null meaning under the documentation skill.
  */
 function normalizeNodeModulePath(path) {
     const normalized = path.replace(/\\/g, "/").replace(/^\/+/, "");

package/lib/src/compiler/normalizeNodeModulePath.js.map

@@ -1 +1 @@
-{"version":3,"file":"normalizeNodeModulePath.js","sourceRoot":"","sources":["../../../src/compiler/normalizeNodeModulePath.ts"],"names":[],"mappings":";;;AAAA;;;;;;GAMG;AACH,iCAAwC,IAAY;IAClD,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAChE,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,eAAe,CAAC;QAAE,OAAO,IAAI,CAAC;IACzD,IAAI,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,KAAK,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3E,OAAO,UAAU,CAAC;AACpB,CAAC"}
+{"version":3,"file":"normalizeNodeModulePath.js","sourceRoot":"","sources":["../../../src/compiler/normalizeNodeModulePath.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;GAWG;AACH,iCAAwC,IAAY;IAClD,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAChE,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,eAAe,CAAC;QAAE,OAAO,IAAI,CAAC;IACzD,IAAI,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,KAAK,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3E,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/lib/src/compiler/pickEmittedJS.d.ts

@@ -1,6 +1,13 @@
 /**
  * Pick the most likely emitted JavaScript file from a compile result's output
- * map. Tries common paths first, then falls back to the first `.js` entry.
- * Returns null when no `.js` was emitted.
+ * map. Tries the default playground layout (`rootDir` `src`, `outDir` `dist`,
+ * which emits `dist/playground.js` for `src/playground.ts`) and other common
+ * paths first, then falls back to the first `.js` entry. Returns null when no
+ * `.js` was emitted.
+ *
+ * @evidence contracts/common.md#principled-implementation The first candidate is the default playground layout (the entry's path below the default `src` root under `dist`), the others cover layouts rooted at the project; the first remaining JavaScript entry is an explicitly heuristic fallback, not a general entrypoint solver.
+ * @evidence contracts/common.md#clear-and-simple-design A small selector separates UI output choice from compiler emit configuration.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Layout candidates are product defaults rather than fixture filenames, and absent JavaScript remains null.
+ * @evidence contracts/common.md#meaningful-documentation Native prose honestly documents priority and heuristic fallback, separated from tags under the documentation skill.
  */
 export declare function pickEmittedJS(output: Record<string, string>, entryFile: string): string | null;

package/lib/src/compiler/pickEmittedJS.js

@@ -3,19 +3,36 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.pickEmittedJS = pickEmittedJS;
 /**
  * Pick the most likely emitted JavaScript file from a compile result's output
- * map. Tries common paths first, then falls back to the first `.js` entry.
- * Returns null when no `.js` was emitted.
+ * map. Tries the default playground layout (`rootDir` `src`, `outDir` `dist`,
+ * which emits `dist/playground.js` for `src/playground.ts`) and other common
+ * paths first, then falls back to the first `.js` entry. Returns null when no
+ * `.js` was emitted.
+ *
+ * @evidence contracts/common.md#principled-implementation The first candidate is the default playground layout (the entry's path below the default `src` root under `dist`), the others cover layouts rooted at the project; the first remaining JavaScript entry is an explicitly heuristic fallback, not a general entrypoint solver.
+ * @evidence contracts/common.md#clear-and-simple-design A small selector separates UI output choice from compiler emit configuration.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Layout candidates are product defaults rather than fixture filenames, and absent JavaScript remains null.
+ * @evidence contracts/common.md#meaningful-documentation Native prose honestly documents priority and heuristic fallback, separated from tags under the documentation skill.
  */
 function pickEmittedJS(output, entryFile) {
     const base = entryFile.replace(/\.[cm]?tsx?$/i, ".js");
-    const candidates = [`dist/${base}`, `dist/src/${base}`, `src/${base}`, base];
+    // `buildTsconfigJSON` roots sources at `src` and emits to `dist`, so the
+    // default entry `src/playground.ts` is reported as `dist/playground.js`.
+    const underSrcRoot = base.replace(/^src\//, "");
+    const candidates = [
+        `dist/${underSrcRoot}`,
+        `dist/${base}`,
+        `dist/src/${base}`,
+        `src/${base}`,
+        base,
+    ];
     for (const key of candidates) {
         if (output[key] !== undefined)
             return output[key];
     }
-    const jsKeys = Object.keys(output).filter((k) => k.endsWith(".js"));
-    if (jsKeys.length > 0)
-        return output[jsKeys[0]] ?? null;
+    for (const key of Object.keys(output)) {
+        if (key.endsWith(".js"))
+            return output[key] ?? null;
+    }
     return null;
 }
 //# sourceMappingURL=pickEmittedJS.js.map

package/lib/src/compiler/pickEmittedJS.js.map

@@ -1 +1 @@
-{"version":3,"file":"pickEmittedJS.js","sourceRoot":"","sources":["../../../src/compiler/pickEmittedJS.ts"],"names":[],"mappings":";;;AAAA;;;;GAIG;AACH,uBACE,MAA8B,EAC9B,SAAiB;IAEjB,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,eAAe,EAAE,KAAK,CAAC,CAAC;IACvD,MAAM,UAAU,GAAG,CAAC,QAAQ,IAAI,EAAE,EAAE,YAAY,IAAI,EAAE,EAAE,OAAO,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;IAC7E,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC7B,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,SAAS;YAAE,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;IACpD,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IACpE,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,IAAI,IAAI,CAAC;IACzD,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"pickEmittedJS.js","sourceRoot":"","sources":["../../../src/compiler/pickEmittedJS.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;GAWG;AACH,uBACE,MAA8B,EAC9B,SAAiB;IAEjB,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,eAAe,EAAE,KAAK,CAAC,CAAC;IACvD,yEAAyE;IACzE,yEAAyE;IACzE,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IAChD,MAAM,UAAU,GAAG;QACjB,QAAQ,YAAY,EAAE;QACtB,QAAQ,IAAI,EAAE;QACd,YAAY,IAAI,EAAE;QAClB,OAAO,IAAI,EAAE;QACb,IAAI;KACL,CAAC;IACF,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC7B,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,SAAS;YAAE,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;IACpD,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACtC,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,OAAO,MAAM,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;IACtD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/lib/src/npm/collectExternalPackageNames.d.ts

@@ -1,5 +1,22 @@
 /**
  * Scan `source` for `import` / `require` specifiers and return the unique
  * sorted list of bare npm package names that are not in `ignoredPackages`.
+ *
+ * This is a lexical discovery pass, not name binding: a locally shadowed direct
+ * require call still looks like a dependency request. Computed strings are
+ * omitted.
+ *
+ * Static arguments are quoted strings and substitution-free, escape-free
+ * templates (`require(`x`)`, `import(`x`)`). Deliberate limits of the
+ * TypeScript-source lane: JSX is not lexed (the playground entry is a `.ts`
+ * file), so quote or `import` text in JSX children can be misread; a type
+ * argument between the callee and its parenthesis (`require<T>("x")`) is not
+ * recognized because `require` is not generic; and a source-phase import
+ * (`import source x from "y"`) collects `y`, the package it loads.
+ *
+ * @evidence contracts/common.md#principled-implementation Tokenization distinguishes executable quoted and static-template specifiers from inert comments, strings and regex bodies; package-name normalization and a Set produce unique sorted install requests. Lexical discovery does not resolve shadowed require bindings.
+ * @evidence contracts/common.md#clear-and-simple-design Lexer, module-construct recognition and package filtering are separate local responsibilities, without importing the full compiler into browser keystroke discovery.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Ignored package names are explicit caller policy; source matching does not fabricate dependency results for known examples.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states discovery domain and binding limitations; helper comments explain escaped strings and lexical boundaries under the documentation skill.
  */
 export declare function collectExternalPackageNames(source: string, ignoredPackages?: Iterable<string>): string[];

package/lib/src/npm/collectExternalPackageNames.js

@@ -6,6 +6,23 @@ const packageNameFromSpecifier_1 = require("./packageNameFromSpecifier");
 /**
  * Scan `source` for `import` / `require` specifiers and return the unique
  * sorted list of bare npm package names that are not in `ignoredPackages`.
+ *
+ * This is a lexical discovery pass, not name binding: a locally shadowed direct
+ * require call still looks like a dependency request. Computed strings are
+ * omitted.
+ *
+ * Static arguments are quoted strings and substitution-free, escape-free
+ * templates (`require(`x`)`, `import(`x`)`). Deliberate limits of the
+ * TypeScript-source lane: JSX is not lexed (the playground entry is a `.ts`
+ * file), so quote or `import` text in JSX children can be misread; a type
+ * argument between the callee and its parenthesis (`require<T>("x")`) is not
+ * recognized because `require` is not generic; and a source-phase import
+ * (`import source x from "y"`) collects `y`, the package it loads.
+ *
+ * @evidence contracts/common.md#principled-implementation Tokenization distinguishes executable quoted and static-template specifiers from inert comments, strings and regex bodies; package-name normalization and a Set produce unique sorted install requests. Lexical discovery does not resolve shadowed require bindings.
+ * @evidence contracts/common.md#clear-and-simple-design Lexer, module-construct recognition and package filtering are separate local responsibilities, without importing the full compiler into browser keystroke discovery.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Ignored package names are explicit caller policy; source matching does not fabricate dependency results for known examples.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states discovery domain and binding limitations; helper comments explain escaped strings and lexical boundaries under the documentation skill.
  */
 function collectExternalPackageNames(source, ignoredPackages = BUILT_IN_PLAYGROUND_PACKAGES_1.BUILT_IN_PLAYGROUND_PACKAGES) {
     const ignored = new Set(ignoredPackages);
@@ -32,11 +49,22 @@ function collectExternalPackageNames(source, ignoredPackages = BUILT_IN_PLAYGROU
 function collectModuleSpecifiers(source) {
     const tokens = tokenize(source);
     const out = [];
+    // A quoted literal only; `import "x"` and `from "x"` cannot take a template.
+    const asQuoted = (token) => token && token.kind === "string" && !token.template ? token.value : null;
+    // A call argument may also be a static template: `require(`x`)`.
     const asString = (token) => token && token.kind === "string" ? token.value : null;
     const isOpenParen = (token) => token !== undefined && token.kind === "punct" && token.value === "(";
-    const isMemberAccess = (token) => token !== undefined &&
-        token.kind === "punct" &&
-        (token.value === "." || token.value === "?.");
+    const isPunct = (token, value) => token !== undefined && token.kind === "punct" && token.value === value;
+    // `obj.name`, `obj?.name` and `this.#name` are not the free binding. The
+    // three dots of a spread are not a member access.
+    const isMemberAccessAt = (index) => {
+        const previous = tokens[index - 1];
+        if (isPunct(previous, "#") || isPunct(previous, "?."))
+            return true;
+        if (!isPunct(previous, "."))
+            return false;
+        return !(isPunct(tokens[index - 2], ".") && isPunct(tokens[index - 3], "."));
+    };
     const isOptionalChain = (token) => token !== undefined && token.kind === "punct" && token.value === "?.";
     for (let i = 0; i < tokens.length; i++) {
         const token = tokens[i];
@@ -44,7 +72,7 @@ function collectModuleSpecifiers(source) {
             continue;
         if (token.value === "require") {
             // `obj.require(...)` is an unrelated method call, not CommonJS require.
-            if (isMemberAccess(tokens[i - 1]))
+            if (isMemberAccessAt(i))
                 continue;
             const optional = isOptionalChain(tokens[i + 1]) && isOpenParen(tokens[i + 2]);
             if (isOpenParen(tokens[i + 1]) || optional) {
@@ -56,7 +84,7 @@ function collectModuleSpecifiers(source) {
         }
         if (token.value === "import" || token.value === "export") {
             // `foo.import(...)` / `import.meta` are not module-loading imports.
-            if (token.value === "import" && isMemberAccess(tokens[i - 1]))
+            if (token.value === "import" && isMemberAccessAt(i))
                 continue;
             // Dynamic `import("x")`.
             if (token.value === "import" && isOpenParen(tokens[i + 1])) {
@@ -67,7 +95,7 @@ function collectModuleSpecifiers(source) {
             }
             // Side-effect `import "x"`.
             if (token.value === "import") {
-                const bare = asString(tokens[i + 1]);
+                const bare = asQuoted(tokens[i + 1]);
                 if (bare !== null) {
                     out.push(bare);
                     continue;
@@ -99,7 +127,9 @@ function findFromSpecifier(tokens, start) {
             return null;
         if (token.kind === "word" && token.value === "from") {
             const next = tokens[i + 1];
-            return next && next.kind === "string" ? next.value : null;
+            return next && next.kind === "string" && !next.template
+                ? next.value
+                : null;
         }
     }
     return null;
@@ -302,7 +332,7 @@ function tokenize(source) {
         // Line comment.
         if (c === "/" && source[i + 1] === "/") {
             i += 2;
-            while (i < n && source[i] !== "\n")
+            while (i < n && !isLineTerminator(source[i]))
                 i++;
             continue;
         }
@@ -334,9 +364,12 @@ function tokenize(source) {
         // JavaScript and must receive the same lexical treatment as top-level code.
         if (c === "`") {
             i++;
+            // A template with no substitution and no escape is one static string.
+            let staticValue = "";
             while (i < n) {
                 const d = source[i];
                 if (d === "\\") {
+                    staticValue = null;
                     i += 2;
                     continue;
                 }
@@ -347,15 +380,22 @@ function tokenize(source) {
                 if (d === "$" && source[i + 1] === "{") {
                     const start = i + 2;
                     const end = findTemplateSubstitutionEnd(source, start);
+                    staticValue = null;
                     context.pushOther();
-                    tokens.push(...tokenize(source.slice(start, end)));
+                    for (const entryToAppend of tokenize(source.slice(start, end)))
+                        tokens.push(entryToAppend);
                     context.pushOther();
                     i = end < n ? end + 1 : end;
                     continue;
                 }
+                if (staticValue !== null)
+                    staticValue += d;
                 i++;
             }
-            context.pushOther();
+            if (staticValue !== null && source[i - 1] === "`")
+                tokens.push({ kind: "string", value: staticValue, template: true });
+            else
+                context.pushOther();
             continue;
         }
         // Identifier / keyword.
@@ -419,7 +459,7 @@ function findTemplateSubstitutionEnd(source, start) {
         }
         if (c === "/" && source[i + 1] === "/") {
             i += 2;
-            while (i < source.length && source[i] !== "\n")
+            while (i < source.length && !isLineTerminator(source[i]))
                 i++;
             continue;
         }