browser-commander 0.31.0 → 0.31.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.31.1
+
+### Patch Changes
+
+- c8f52e3: Upgrade Links Notation to ^0.25.2 so consumers using 0.25.2 can share one copy without an override. Preserve trace text containing lone UTF-16 surrogates, verify export/import and streaming compatibility, and document the new empty/control-value literals for consumers upgrading older parsers.
+
 ## 0.31.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-commander",
-  "version": "0.31.0",
+  "version": "0.31.1",
   "description": "Universal browser automation library that supports Playwright, Puppeteer, and Selenium with a unified API",
   "main": "src/index.js",
   "bin": {
@@ -84,7 +84,7 @@
     "command-stream": "^2.0.2",
     "csv-parse": "^7.0.3",
     "gifenc": "^1.0.3",
-    "links-notation": "^0.23.0",
+    "links-notation": "^0.25.2",
     "log-lazy": "^1.0.4",
     "plist": "^5.0.0",
     "test-anywhere": "^0.9.1",

package/src/traces/links.js

@@ -107,11 +107,11 @@ const HEAD_FIELDS = new Set([
 /**
  * Make one value safe to write as a link.
  *
- * Links Notation 0.20 quotes a value with whichever quote character the value
- * does not contain, and its parser does not read escapes, so a value holding
- * both quote characters cannot be read back. Newlines are worse: they would
- * split one record across lines. Both are encoded here, reversibly, rather
- * than dropped, so the export loses nothing the bundle holds.
+ * Keep the representation's legacy escapes even though current Links Notation
+ * can quote both quote characters. Newlines must not split a record across
+ * lines. Lone UTF-16 surrogates are escaped too: the notation requires valid
+ * Unicode, but JavaScript trace strings can hold individual surrogate units.
+ * All these encodings are reversible, so the export loses no scalar text.
  *
  * @param {*} value - Any scalar from a trace record
  * @returns {string} Text that survives a format and parse round trip
@@ -122,9 +122,13 @@ export function encodeLinkText(value) {
     .replaceAll('\\', '\\\\')
     .replaceAll('\n', '\\n')
     .replaceAll('\r', '\\r')
-    .replaceAll('\t', '\\t');
-  // Only a value that holds both quote characters is unquotable, so only that
-  // value pays for the ugliness of an escaped quote.
+    .replaceAll('\t', '\\t')
+    // Unicode mode matches lone surrogates without splitting valid pairs.
+    .replace(
+      /[\ud800-\udfff]/gu,
+      (unit) => `\\u${unit.charCodeAt(0).toString(16)}`
+    );
+  // Preserve the existing encoding for values holding both quote characters.
   return escaped.includes("'") && escaped.includes('"')
     ? escaped.replaceAll('"', '\\u0022')
     : escaped;
@@ -139,8 +143,9 @@ export function encodeLinkText(value) {
 export function decodeLinkText(text) {
   const decoded = { '\\': '\\', n: '\n', r: '\r', t: '\t', u0022: '"' };
   return String(text).replace(
-    /\\(\\|n|r|t|u0022)/g,
-    (match, code) => decoded[code]
+    /\\(\\|n|r|t|u0022|ud[89a-f][0-9a-f]{2})/g,
+    (match, code) =>
+      decoded[code] ?? String.fromCharCode(Number.parseInt(code.slice(1), 16))
   );
 }
 

package/tests/unit/traces/links-compatibility.test.js

@@ -0,0 +1,56 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { Parser, StreamParser } from 'links-notation';
+import {
+  decodeLinkText,
+  formatTraceLinks,
+  timelineLink,
+} from '../../../src/traces/links.js';
+import { readRepoText } from '../../helpers/repo.js';
+
+describe(
+  'trace compatibility with Links Notation (issue #168)',
+  { timeout: 10000 },
+  () => {
+    it('preserves scalar text through the formatter, parser and trace decoder', () => {
+      for (const text of [
+        '',
+        '#comment',
+        'issue#168',
+        '~1{61}',
+        'both\'and" with `backticks`',
+        'line\r\nbreak\ttab\\literal\\u0022\\ud800\\udfff',
+        '\u0000\u0001\u007f',
+        'a\u00a0b\u2028c\u2029d\ufeff',
+        'Tiếng Việt 日本語 🧭 e\u0301',
+        '\ud800',
+        '\udfff',
+        '🧭\ud800🧭\udfff',
+      ]) {
+        const line = formatTraceLinks([
+          timelineLink({ kind: 'console', text }),
+        ]);
+        assert.equal(line.split('\n').length, 2, 'one record per line');
+        const [parsed] = new Parser().parse(line);
+        const field = parsed.values.find((value) => value.id === 'text');
+        assert.equal(decodeLinkText(field.values[0].id), text);
+      }
+    });
+
+    it('imports the existing cross-language golden export in arbitrary chunks', () => {
+      const text = readRepoText(
+        'js/tests/fixtures/traces/conformance/expected/trace.lino'
+      );
+      const expected = new Parser().parse(text);
+      assert.equal(expected.length, 27);
+      for (const chunkSize of [1, 17, text.length]) {
+        const stream = new StreamParser();
+        for (let offset = 0; offset < text.length; offset += chunkSize) {
+          stream.write(text.slice(offset, offset + chunkSize));
+        }
+        stream.end();
+        assert.deepEqual(stream.drain(), expected);
+      }
+    });
+  }
+);

package/tests/unit/traces/links.test.js

@@ -544,8 +544,8 @@ describe('trace links export (issue #94)', () => {
     // The notation's formatter and parser decide whether an export can be read
     // back, so the range this package depends on and the version the tests
     // proved are the same range.
-    assert.strictEqual(manifest.dependencies['links-notation'], '^0.23.0');
-    assert.match(installed.version, /^0\.23\./);
+    assert.strictEqual(manifest.dependencies['links-notation'], '^0.25.2');
+    assert.match(installed.version, /^0\.25\./);
   });
 
   it('should export a bundle named by path as readily as an open one', async () => {