soml-lang 0.0.2 → 0.0.4

package/distribution/parse.js

@@ -1,43 +1,41 @@
 import { ParseError } from "./error.js";
-import { MAX_DEPTH, INT64_MIN, INT64_MAX, MIN_INSTANT, MAX_INSTANT, DURATION_UNITS, createDuration, requireTemporal, trimTrailingZeros, validateIntegersOption, describeCharacter, formatCodePoint, isBareKey, isBareKeyCharacter, findNumberEnd, findLineEnd, findBlockStringEnd, abbreviate, } from "./shared.js";
-const TAB = 0x09;
-const LF = 0x0A;
-const SPACE = 0x20;
-const DOUBLE_QUOTE = 0x22;
-const HASH = 0x23;
-const SINGLE_QUOTE = 0x27;
-const ASTERISK = 0x2A;
-const COMMA = 0x2C;
-const DASH = 0x2D;
-const DOT = 0x2E;
-const SLASH = 0x2F;
-const COLON = 0x3A;
-const OPEN_BRACKET = 0x5B;
-const CLOSE_BRACKET = 0x5D;
-const OPEN_BRACE = 0x7B;
-const CLOSE_BRACE = 0x7D;
-/*
-What may directly follow a scalar value: whitespace, a separator, a closing bracket, a comment, or the end.
-*/
+import { formatKey } from "./stringify.js";
+import { MAX_DEPTH, INT64_MIN, INT64_MAX, MIN_INSTANT, MAX_INSTANT, DURATION_UNITS, createDuration, requireTemporal, trimTrailingZeros, getIntegersOption, describeCharacter, formatCodePoint, describeKey, isBareKeyCharacter, isSpace, skipSpaces, skipSpacesBack, isBlankLine, findNumberEnd, findLineEnd, findBlockStringEnd, abbreviate, LF, SPACE, DOUBLE_QUOTE, HASH, SINGLE_QUOTE, ASTERISK, COMMA, DASH, DOT, SLASH, COLON, OPEN_BRACKET, CLOSE_BRACKET, OPEN_BRACE, CLOSE_BRACE, } from "./shared.js";
 const valueEndCharacters = new Uint8Array(128);
 for (const character of ' \t\n,]}#/') {
     valueEndCharacters[character.codePointAt(0)] = 1;
 }
-const RADIX_DIGIT = {
-    x: code => (code >= 0x30 && code <= 0x39) || (code >= 0x41 && code <= 0x46),
-    o: code => code >= 0x30 && code <= 0x37,
-    b: code => code === 0x30 || code === 0x31,
-};
 /*
-The longest token the diagnostic regular expressions look at. Their repeated groups need stack in proportion to the input, so a longer invalid token is described from its first part.
+Whether a UTF-16 code unit may directly follow a scalar value: whitespace, a separator, a closing bracket, a comment, or the end, where `charCodeAt()` returns `NaN`.
+*/
+function isValueEnd(code) {
+    return Number.isNaN(code) || (code < 128 && valueEndCharacters[code] === 1);
+}
+/*
+Whether a UTF-16 code unit is a space, a tab, a line feed, or the end.
+*/
+function isSpaceOrLineEnd(code) {
+    return isSpace(code) || code === LF || Number.isNaN(code);
+}
+/*
+The lookup tables are maps rather than objects, so that a property added to `Object.prototype` is never read as an entry.
+*/
+const RADIX_DIGIT = new Map([
+    ['x', code => (code >= 0x30 && code <= 0x39) || (code >= 0x41 && code <= 0x46)],
+    ['o', code => code >= 0x30 && code <= 0x37],
+    ['b', code => code === 0x30 || code === 0x31],
+]);
+/*
+The longest token that the instant regular expression and the diagnostic regular expressions look at. Their repeated groups need stack in proportion to the input, so a longer token is rejected with a general message, or described from its first part.
 */
 const MAX_DIAGNOSED_LENGTH = 1000;
 const RADIX_NAME = { x: 'hexadecimal', o: 'octal', b: 'binary' };
 const RADIX_ARTICLE = { x: 'A', o: 'An', b: 'A' };
 const INSTANT_PREFIX = /^\d{4}-\d{2}-\d{2}/v;
-const INSTANT_START = /^\d{4}-\d{2}-\d{2}T\d{2}:\d/v;
 const DURATION_UNIT_NAMES = DURATION_UNITS.keys().toArray();
 const INSTANT = /^(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})T(?<hour>\d{2}):(?<minute>\d{2}):(?<second>\d{2})(?:\.(?<fraction>\d+))?(?<offset>Z|[+\-](?<offsetHour>\d{2}):(?<offsetMinute>\d{2}))$/v;
+const LOCAL_DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?$/v;
+const INSTANT_FORMAT = 'An instant is written as 2026-09-19T14:00:00Z, with an optional fraction of up to nine digits and an offset of Z or ±HH:MM';
 const UNICODE_ESCAPE = /u\{(?<hex>[\da-f]{1,6})\}/vy;
 /*
 Every C0 control character except tab and line feed, and DEL. They are errors anywhere in a document.
@@ -45,14 +43,23 @@ Every C0 control character except tab and line feed, and DEL. They are errors an
 // eslint-disable-next-line no-control-regex, regexp/no-control-character -- Control characters are exactly what must be found.
 const CONTROL_CHARACTER = /[\u{0}-\u{8}\u{B}-\u{1F}\u{7F}]/v;
 const LITERAL_STRING_END = /[\n']/gv;
-const BLANK_LINE = /^[\t ]*$/v;
+const KEY_QUOTING_HINT = '. A key that contains characters other than letters, digits, “_”, and “-” must be quoted';
+/*
+The characters that may be meant as part of a key: visible ones that have no meaning in the grammar, which includes every bare key character. A `=` is left out, because after a key, as in `name=foo`, it was most likely meant as the `:` of INI and TOML, so a key that holds a `=` gets no quoting hint.
+*/
+const QUOTABLE_KEY_CHARACTER = String.raw `[^\p{Default_Ignorable_Code_Point}\p{Other}\p{White_Space}"#'*,.\/:=\[\]\{\}]`;
+const QUOTABLE_KEY_START = new RegExp(`^${QUOTABLE_KEY_CHARACTER}`, 'v');
+/*
+A key made of them, up to its `:`, so the quoting hint can show it quoted.
+*/
+const QUOTABLE_KEY = new RegExp(`^${QUOTABLE_KEY_CHARACTER}+(?=:)`, 'v');
 const ESCAPED_STRING_SPECIAL = /[\n"\\]/gv;
-const SIMPLE_ESCAPES = {
-    '\\': '\\',
-    '"': '"',
-    n: '\n',
-    t: '\t',
-};
+const SIMPLE_ESCAPES = new Map([
+    ['\\', '\\'],
+    ['"', '"'],
+    ['n', '\n'],
+    ['t', '\t'],
+]);
 /*
 What a backslash followed by one of these characters was probably meant to be.
 */
@@ -61,13 +68,34 @@ const ESCAPE_MISTAKES = new Map([
     ['\'', 'A \' needs no escape inside "..."'],
     ['\n', String.raw `A backslash must be followed by an escape character. Use \\ for a literal backslash, or a '...' string`],
 ]);
-export function parse(text, options = {}) {
-    const { integers = 'bigint' } = options;
-    validateIntegersOption(integers);
+export function parse(text, options) {
+    const integers = getIntegersOption(options);
     const source = decode(text);
     checkCharacters(source);
+    // The default `createTime` makes a `Temporal` object of every instant and duration, so no `Time` is left.
     return new Parser(source, integers).parseDocument();
 }
+/*
+An instant, as nanoseconds since the Unix epoch, or a duration, as its length in nanoseconds.
+*/
+export class Time {
+    type;
+    nanoseconds;
+    constructor(type, nanoseconds) {
+        this.type = type;
+        this.nanoseconds = nanoseconds;
+    }
+    toTemporal() {
+        return this.type === 'Instant' ? new (requireTemporal().Instant)(this.nanoseconds) : createDuration(this.nanoseconds);
+    }
+}
+/*
+The same as `parse()` for a string, except that each instant and duration is a `Time` instead of a `Temporal` object, so that it works without `Temporal`. For the tree, which makes the `Temporal` object only when the value is read.
+*/
+export function parseWithTimes(text) {
+    checkCharacters(text);
+    return new Parser(text, 'bigint', time => time).parseDocument();
+}
 const typedArrayTag = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(Uint8Array.prototype), Symbol.toStringTag).get;
 function decode(text) {
     if (typeof text === 'string') {
@@ -170,27 +198,19 @@ function defineMember(object, key, value) {
         object[key] = value;
     }
 }
-function describeValue(value) {
-    if (Array.isArray(value)) {
-        return 'an array';
-    }
-    // Every parsed object is created with `{}`, unlike an instant or a duration.
-    return value !== null && typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype ? 'an object' : 'a value';
-}
-function formatPath(path) {
-    return path.map(segment => isBareKey(segment) ? abbreviate(segment) : JSON.stringify(abbreviate(segment))).join('.');
-}
 class Parser {
     #source;
     #index = 0;
     #integers;
+    #createTime;
     /*
-    Objects created by dotted keys. They may be extended by further dotted keys, while an object written with braces is closed.
+    Where the document's collection starts, after the comments and whitespace before it.
     */
-    #dottedObjects = new WeakSet();
-    constructor(source, integers) {
+    #documentStart = 0;
+    constructor(source, integers, createTime = time => time.toTemporal()) {
         this.#source = source;
         this.#integers = integers;
+        this.#createTime = createTime;
     }
     #fail(reason, offset = this.#index) {
         throw ParseError.create(reason, this.#source, offset);
@@ -218,11 +238,11 @@ class Parser {
         }
         let hasLineBreak = this.#skipTrivia();
         while (!this.#isAtEnd()) {
+            if (this.#code() === COMMA) {
+                this.#fail('Top-level entries are separated by line breaks, not commas. Use braces for a one-line object');
+            }
             if (!hasLineBreak) {
-                if (this.#code() === COMMA) {
-                    this.#fail('Top-level entries are separated by line breaks, not commas. Use braces for a one-line object');
-                }
-                this.#fail(`Expected a line break before the next entry, but found ${this.#describeHere()}`);
+                this.#fail(`Expected a line break before the next entry, but found ${this.#describeHere()}${this.#slashCommentHint()}`);
             }
             this.#parseEntry(object, 1);
             hasLineBreak = this.#skipTrivia();
@@ -230,21 +250,18 @@ class Parser {
         return object;
     }
     /*
-    A first line that is one scalar, such as `5` or an instant, fails as an entry. That failure is reported as what it is.
+    A whole document that is one scalar, such as `5` or an instant, fails as an entry. That failure is reported as what it is.
     */
     #diagnoseBareValue(start) {
         this.#index = start;
         let isBareValue = false;
         try {
             this.#parseValue(1);
-            isBareValue = this.#skipTrivia() || this.#isAtEnd();
+            this.#skipTrivia();
+            isBareValue = this.#isAtEnd();
         }
-        catch (error) {
-            // A bare key cannot hold a ":", so a token shaped like an instant was meant as one, and its own error says what is wrong with it.
-            if (INSTANT_START.test(this.#source.slice(start, start + 15))) {
-                throw error;
-            }
-            // Otherwise it is not a bare value either, and the original error stands.
+        catch {
+            // Not a bare value either, so the original error stands.
         }
         if (isBareValue) {
             this.#fail('A bare value is not a document. A document is an object or an array, so write it as `key: value` or `[value]`', start);
@@ -258,7 +275,7 @@ class Parser {
         let hasCrossedLineBreak = false;
         for (;;) {
             const code = source.charCodeAt(this.#index);
-            if (code === SPACE || code === TAB) {
+            if (isSpace(code)) {
                 this.#index++;
             }
             else if (code === LF) {
@@ -296,7 +313,7 @@ class Parser {
         const nested = source.indexOf('/*', start + 2);
         // The body may not contain `/*`. An opening that overlaps the closing `*/`, as in `/*/`, is not inside the body.
         if (nested !== -1 && nested + 2 <= end) {
-            this.#fail('Block comments cannot be nested, and their body may not contain "/*"', nested);
+            this.#fail('Block comments cannot be nested, and their body may not contain “/*”', nested);
         }
         this.#index = end + 2;
     }
@@ -305,59 +322,155 @@ class Parser {
     */
     #parseEntry(object, depth) {
         const keyStart = this.#index;
-        const path = this.#parseKey();
-        if (depth + path.length - 1 > MAX_DEPTH) {
-            this.#fail(`The document is nested more than ${MAX_DEPTH} levels deep`, keyStart);
-        }
+        const key = this.#parseKey();
         const code = this.#code();
+        if (code === DOT) {
+            this.#failDotInKey(keyStart);
+        }
         if (code !== COLON) {
             this.#failMissingColon(keyStart);
         }
+        const colon = this.#index;
         this.#index++;
         this.#skipTrivia();
-        const value = this.#parseValue(depth + path.length);
-        this.#assign(object, path, value, keyStart);
+        let value;
+        try {
+            value = this.#parseValue(depth + 1);
+        }
+        catch (error) {
+            if (error instanceof ParseError) {
+                this.#diagnoseBadValue(error, key, keyStart, colon);
+            }
+            throw error;
+        }
+        if (Object.hasOwn(object, key)) {
+            this.#fail(`Duplicate key ${describeKey(key)}`, keyStart);
+        }
+        defineMember(object, key, value);
     }
-    #failMissingColon(keyStart) {
+    /*
+    Reports a value that failed to parse as what the entry was meant to be, when that is clear.
+    */
+    #diagnoseBadValue(error, key, keyStart, colon) {
+        // A key that contains a `:`, as in `12:30: 'lunch'`, ends at the first `:`, and the rest is read as the value.
+        if (isBareKeyCharacter(this.#code(colon + 1))) {
+            this.#diagnoseKeyWithColon(keyStart);
+        }
+        this.#index = colon + 1;
+        const isValueOnNextLine = this.#skipTrivia();
+        const valueStart = this.#index;
+        const commentHint = this.#describeCommentAsValue(colon);
+        if (isValueOnNextLine) {
+            this.#diagnoseMissingValue(valueStart, key, keyStart, commentHint);
+        }
+        // A value that was left out at the end of the document or of an object.
+        const code = this.#code(valueStart);
+        if (commentHint !== '' && error.offset === valueStart && (code === CLOSE_BRACE || Number.isNaN(code))) {
+            this.#fail(`${error.reason}${commentHint}`, valueStart);
+        }
+    }
+    /*
+    A bare key followed directly by `:` and more of a key, up to a `:` that ends the key, as in `a:b: 1`.
+    */
+    #diagnoseKeyWithColon(keyStart) {
         const source = this.#source;
-        let next = this.#index;
-        while (source.charCodeAt(next) === SPACE || source.charCodeAt(next) === TAB) {
-            next++;
+        for (let index = keyStart; index < keyStart + MAX_DIAGNOSED_LENGTH; index++) {
+            const code = source.charCodeAt(index);
+            if (code === COLON) {
+                const next = source.charCodeAt(index + 1);
+                if (next === LF || isSpace(next) || Number.isNaN(next)) {
+                    this.#fail(`A key that contains “:” must be quoted, as in '${abbreviate(source.slice(keyStart, index))}'`, keyStart);
+                }
+            }
+            else if (!isBareKeyCharacter(code)) {
+                return;
+            }
+        }
+    }
+    /*
+    The hint for a `#` directly after a `:`, as in `color: #FFF`, which starts a comment rather than a value.
+    */
+    #describeCommentAsValue(colon) {
+        const source = this.#source;
+        const hash = skipSpaces(source, colon + 1);
+        if (source.charCodeAt(hash) !== HASH) {
+            return '';
         }
+        // A `#` followed by a space, or by another `#`, starts an ordinary comment. A separator or a closing bracket after the value is not part of it. The regular expression, which needs stack in proportion to its match, only sees the start of a long comment, which is cut short in the message anyway.
+        const match = /^#[^\t\n #,\]\}][^\t\n ,\]\}]*/v.exec(source.slice(hash, hash + MAX_DIAGNOSED_LENGTH));
+        return match === null ? '' : `. “#” starts a comment, so a value that starts with “#” must be quoted${quotingExample(match[0])}`;
+    }
+    /*
+    An entry whose value was left out, as in `a:` followed by `'b': 1` on the next line, reads the next key as the value. That failure is reported as what it is.
+    */
+    #diagnoseMissingValue(start, parent, keyStart, commentHint) {
+        // A YAML block sequence.
+        if (this.#code(start) === DASH && isSpace(this.#code(start + 1))) {
+            this.#fail('Expected a value, but found a “-” list. An array is written in brackets, as in [80, 443]', start);
+        }
+        this.#index = start;
+        let key;
+        try {
+            key = this.#parseKey();
+        }
+        catch {
+            // Not a key either, so the original error stands.
+        }
+        if (key === undefined || this.#code() !== COLON) {
+            return;
+        }
+        // Whitespace or the end follows the `:` of a bare key. A digit follows the `:` in an instant such as `2026-09-19T25:00:00Z`, whose own error is more precise. A quoted key cannot be part of a value, so anything may follow its `:`.
+        const next = this.#code(this.#index + 1);
+        const firstCode = this.#code(start);
+        if (firstCode !== SINGLE_QUOTE && firstCode !== DOUBLE_QUOTE && next !== LF && !isSpace(next) && !Number.isNaN(next)) {
+            return;
+        }
+        const hint = commentHint === '' ? this.#describeIndentedKey(parent, key, keyStart, start) : commentHint;
+        this.#fail(`Expected a value, but found the key ${describeKey(key)}${hint}`, start);
+    }
+    /*
+    The hint for a key at `start` that is indented under the entry whose value is missing, as YAML nests an object.
+    */
+    #describeIndentedKey(parent, key, keyStart, start) {
+        const keyIndentation = getIndentation(this.#source, keyStart);
+        const indentation = getIndentation(this.#source, start);
+        // The keys are written as in a document, so that the suggestion is valid, rather than as JSON strings like the rest of the message, whose escapes, such as `\b`, are not all valid.
+        const hint = `. Indentation does not nest objects, so write ${abbreviate(formatKey(parent), 200)}: {${abbreviate(formatKey(key), 200)}: …}`;
+        return keyIndentation === undefined || indentation === undefined || indentation <= keyIndentation ? '' : hint;
+    }
+    #failMissingColon(keyStart) {
+        const source = this.#source;
+        const next = skipSpaces(source, this.#index);
         const nextCode = source.charCodeAt(next);
         if (nextCode === COLON && next > this.#index) {
-            this.#fail('Whitespace is not allowed between a key and its ":"');
+            this.#fail('Whitespace is not allowed between a key and its “:”');
         }
-        // Nothing else can follow a key, so a block comment there was meant to come before the ":".
+        // A block comment followed by the ":" was meant to come before it.
         if (nextCode === SLASH && source.charCodeAt(next + 1) === ASTERISK) {
-            this.#fail('A comment is not allowed between a key and its ":"', next);
+            const commentEnd = source.indexOf('*/', next + 2);
+            if (commentEnd !== -1 && source.charCodeAt(skipSpaces(source, commentEnd + 2)) === COLON) {
+                this.#fail('A comment is not allowed between a key and its “:”', next);
+            }
         }
         const colon = source.indexOf(':', next);
-        // A key with a space in it, such as `the name: 1`. The hint is only given for plain words, because quoting a dotted or quoted key would change what it means.
-        if (colon !== -1 && next > this.#index && isBareKeyCharacter(nextCode) && colon < findLineEnd(source, next)) {
-            const key = source.slice(keyStart, colon).trimEnd();
+        // A key with a space in it, such as `the name: 1`. The hint is only given for plain words, because quoting a quoted key would change what it means, and for a `:` that whitespace or the end follows, because quoting the words before the `:` in `server localhost:8080` would give a valid document with another meaning. So `the name:1` gets no hint.
+        if (colon !== -1 && next > this.#index && isBareKeyCharacter(nextCode) && colon < findLineEnd(source, next) && isSpaceOrLineEnd(source.charCodeAt(colon + 1))) {
+            // Only spaces and tabs are trimmed, because `trimEnd()` would also remove characters that are not whitespace in SOML, such as U+00A0.
+            const key = source.slice(keyStart, skipSpacesBack(source, colon));
             if (isWordsWithSpaces(key)) {
                 this.#fail(`A bare key cannot contain spaces. Quote it, as in '${abbreviate(key)}'`, keyStart);
             }
         }
         if (this.#isAtEnd() || this.#code() === LF) {
-            this.#fail('Expected ":" after the key');
+            this.#fail('Expected “:” after the key');
         }
         // A character directly after a bare key is most likely meant to be part of it.
         const previousCode = source.charCodeAt(this.#index - 1);
-        const hint = previousCode !== SINGLE_QUOTE && previousCode !== DOUBLE_QUOTE && next === this.#index ? '. A key that contains characters other than letters, digits, "_", and "-" must be quoted' : '';
+        const hint = previousCode !== SINGLE_QUOTE && previousCode !== DOUBLE_QUOTE && next === this.#index && QUOTABLE_KEY_START.test(source.slice(next, next + 2)) ? KEY_QUOTING_HINT : '';
         this.#index = next;
-        this.#fail(`Expected ":" after the key, but found ${this.#describeHere()}${hint}`);
+        this.#fail(`Expected “:” after the key, but found ${this.#describeHere()}${hint}`);
     }
     #parseKey() {
-        const path = [this.#parseKeySegment()];
-        while (this.#code() === DOT) {
-            this.#index++;
-            path.push(this.#parseKeySegment(true));
-        }
-        return path;
-    }
-    #parseKeySegment(isAfterDot = false) {
         const source = this.#source;
         const start = this.#index;
         const code = source.charCodeAt(start);
@@ -373,100 +486,93 @@ class Parser {
             end++;
         }
         if (end === start) {
-            if (isAfterDot) {
-                this.#fail(this.#isAtEnd() ? 'Expected a key segment after "."' : `Expected a key segment after ".", but found ${this.#describeHere()}`);
+            if (code === OPEN_BRACKET) {
+                this.#diagnoseTableHeader();
             }
-            this.#fail(this.#isAtEnd() ? 'Expected a key' : `Expected a key, but found ${this.#describeHere()}`);
+            this.#fail(this.#isAtEnd() ? 'Expected a key' : `Expected a key, but found ${this.#describeHere()}${this.#keyQuotingHint()}${this.#slashCommentHint()}`);
         }
         this.#index = end;
         return source.slice(start, end);
     }
-    #assign(object, path, value, keyStart) {
-        let target = object;
-        const lastIndex = path.length - 1;
-        for (let index = 0; index < lastIndex; index++) {
-            const key = path[index];
-            if (!Object.hasOwn(target, key)) {
-                const child = {};
-                this.#dottedObjects.add(child);
-                defineMember(target, key, child);
-                target = child;
-                continue;
-            }
-            // Only an object built by dotted keys is in the set, which is checked next.
-            const existing = target[key];
-            if (!this.#dottedObjects.has(existing)) {
-                const prefix = formatPath(path.slice(0, index + 1));
-                const what = describeValue(existing);
-                const reason = what === 'an object' ? 'an object written with braces, which is closed' : what;
-                this.#fail(`Cannot set ${formatPath(path)}, because ${prefix} is already ${reason} and a dotted key cannot extend it`, keyStart);
-            }
-            target = existing;
+    /*
+    The hint for a key that starts with a character a bare key cannot hold, such as the `$` in `$schema`, or nothing for a character with another meaning, such as `}`.
+    */
+    #keyQuotingHint() {
+        if (!QUOTABLE_KEY_START.test(this.#source.slice(this.#index, this.#index + 2))) {
+            return '';
         }
-        const key = path[lastIndex];
-        if (Object.hasOwn(target, key)) {
-            if (this.#dottedObjects.has(target[key])) {
-                this.#fail(`Cannot set ${formatPath(path)}: it is already an object built by dotted keys`, keyStart);
-            }
-            this.#fail(`Duplicate key ${formatPath(path)}`, keyStart);
+        // A longer key gets the hint without the example, and the regular expression, which backtracks, never sees a huge run.
+        const key = QUOTABLE_KEY.exec(this.#source.slice(this.#index, this.#index + MAX_DIAGNOSED_LENGTH))?.[0];
+        return key === undefined ? KEY_QUOTING_HINT : `${KEY_QUOTING_HINT}, as in '${abbreviate(key)}'`;
+    }
+    /*
+    A `.` after a key, as in `example.com: 1`. A key is never a path, so the `.` is meant either as part of the key or as nesting.
+    */
+    #failDotInKey(keyStart) {
+        const source = this.#source;
+        let end = this.#index;
+        while (end < keyStart + MAX_DIAGNOSED_LENGTH && (isBareKeyCharacter(source.charCodeAt(end)) || source.charCodeAt(end) === DOT)) {
+            end++;
+        }
+        const key = source.slice(keyStart, end);
+        const words = key.split('.');
+        // The suggestions are only given for a bare key whose dots each have a word on both sides, so that both are valid.
+        if (source.charCodeAt(end) !== COLON || !isBareKeyCharacter(source.charCodeAt(keyStart)) || words.includes('')) {
+            this.#fail('A key cannot contain “.” unless it is quoted. Quote the whole key, or use braces to nest, as in a: {b: …}');
         }
-        defineMember(target, key, value);
+        const nested = `${words.join(': {')}: …${'}'.repeat(words.length - 1)}`;
+        this.#fail(`A bare key cannot contain “.”. Quote it, as in '${abbreviate(key)}', or use braces to nest, as in ${abbreviate(nested)}`);
     }
     #parseObject(depth) {
-        if (depth > MAX_DEPTH) {
-            this.#fail(`The document is nested more than ${MAX_DEPTH} levels deep`);
-        }
-        const start = this.#index;
         const object = {};
-        this.#index++;
-        this.#skipTrivia();
-        for (;;) {
-            const code = this.#code();
-            if (code === CLOSE_BRACE) {
-                this.#index++;
-                return object;
-            }
-            if (this.#isAtEnd()) {
-                this.#fail('Unterminated object: expected "}"', start);
-            }
+        this.#parseItems(depth, CLOSE_BRACE, () => {
             this.#parseEntry(object, depth);
-            this.#skipTrivia();
-            if (this.#code() === COMMA) {
-                this.#index++;
-                this.#skipTrivia();
-            }
-            else if (this.#code() !== CLOSE_BRACE) {
-                this.#fail(this.#isAtEnd() ? 'Unterminated object: expected "}"' : `Expected "," or "}" after an object member, but found ${this.#describeHere()}`, this.#isAtEnd() ? start : this.#index);
-            }
-        }
+        });
+        return object;
     }
     #parseArray(depth) {
+        const array = [];
+        this.#parseItems(depth, CLOSE_BRACKET, () => {
+            array.push(this.#parseValue(depth + 1));
+        });
+        return array;
+    }
+    /*
+    `{` or `[` at depth `depth`, then items separated by a comma, a line break, or both, with an optional trailing comma, then the `closing` bracket. A comma must be on the line of the item before it.
+    */
+    #parseItems(depth, closing, parseItem) {
         if (depth > MAX_DEPTH) {
             this.#fail(`The document is nested more than ${MAX_DEPTH} levels deep`);
         }
         const start = this.#index;
-        const array = [];
         this.#index++;
         this.#skipTrivia();
-        for (;;) {
-            const code = this.#code();
-            if (code === CLOSE_BRACKET) {
-                this.#index++;
-                return array;
+        while (this.#code() !== closing) {
+            let hasLineBreak = false;
+            let itemEnd = this.#index;
+            if (!this.#isAtEnd()) {
+                parseItem();
+                itemEnd = this.#index;
+                hasLineBreak = this.#skipTrivia();
             }
             if (this.#isAtEnd()) {
-                this.#fail('Unterminated array: expected "]"', start);
+                this.#fail(`Unterminated ${closing === CLOSE_BRACE ? 'object' : 'array'}: expected “${String.fromCharCode(closing)}”`, start);
             }
-            array.push(this.#parseValue(depth + 1));
-            this.#skipTrivia();
             if (this.#code() === COMMA) {
+                if (hasLineBreak) {
+                    this.#fail('A comma must be on the same line as the item before it. The line break already separates the items, so remove the comma');
+                }
                 this.#index++;
                 this.#skipTrivia();
             }
-            else if (this.#code() !== CLOSE_BRACKET) {
-                this.#fail(this.#isAtEnd() ? 'Unterminated array: expected "]"' : `Expected "," or "]" after an array item, but found ${this.#describeHere()}`, this.#isAtEnd() ? start : this.#index);
+            else if (!hasLineBreak && this.#code() !== closing) {
+                const item = closing === CLOSE_BRACE ? 'an object member' : 'an array item';
+                // Without a line break that separates, a line break in the gap is inside a block comment.
+                const hint = this.#source.slice(itemEnd, this.#index).includes('\n') ? '. A line break inside a block comment does not separate items' : this.#slashCommentHint();
+                this.#fail(`Expected “,”, a line break, or “${String.fromCharCode(closing)}” after ${item}, but found ${this.#describeHere()}${hint}`);
             }
         }
+        this.#index++;
     }
     #parseValue(depth) {
         const code = this.#code();
@@ -476,7 +582,10 @@ class Parser {
         if (code === OPEN_BRACKET) {
             return this.#parseArray(depth);
         }
+        const start = this.#index;
         let value;
+        // An int or a float written with digits.
+        let isNumber = false;
         if (code === SINGLE_QUOTE || code === DOUBLE_QUOTE) {
             value = this.#parseString();
         }
@@ -497,16 +606,55 @@ class Parser {
         }
         else if (code === DASH || isDigit(code)) {
             value = this.#parseNumberOrInstant();
+            isNumber = typeof value === 'bigint' || typeof value === 'number';
         }
         else {
             this.#failUnexpectedValue();
         }
-        const next = this.#code();
-        if (!this.#isAtEnd() && (next >= 128 || valueEndCharacters[next] !== 1)) {
-            this.#fail(`Unexpected ${this.#describeHere()} after a value`);
+        if (!isValueEnd(this.#code())) {
+            this.#failAfterValue(start, isNumber);
+        }
+        if (isNumber && isSpace(this.#code())) {
+            this.#diagnoseUnitAfterSpace(start);
         }
         return value;
     }
+    /*
+    A character that cannot follow the value that starts at `start`.
+    */
+    #failAfterValue(start, isNumber) {
+        const code = this.#code();
+        // Go writes microseconds as `µs`, with the micro sign or the Greek letter mu. The duration is only suggested when it is valid, which a number with an exponent or a radix prefix, for example, is not.
+        if (isNumber && (code === 0xB5 || code === 0x3_BC) && this.#code(this.#index + 1) === 0x73 /* s */) {
+            const number = this.#source.slice(start, this.#index);
+            this.#fail(`The unit for microseconds is written us${isValidValue(`${number}us`) ? `, as in ${abbreviate(number)}us` : ''}`);
+        }
+        // A `''` inside a '...' string, as SQL and YAML escape a quote, ends the string.
+        if (code === SINGLE_QUOTE && this.#code(start) === SINGLE_QUOTE) {
+            this.#fail('There is no \'\' escape in a \'...\' string. Write a string that contains \' as "...", as in "it\'s"');
+        }
+        this.#fail(`Unexpected ${this.#describeHere()} after a value`);
+    }
+    /*
+    A number followed by a space and a word, such as `512 MiB` or `10 seconds`, which is an error anyway. A word followed by more than spaces, a separator, or a comment is left to the general errors, because it may be a key, as in `a: 1 b: 2`, or a sentence.
+    */
+    #diagnoseUnitAfterSpace(start) {
+        const source = this.#source;
+        const unitStart = skipSpaces(source, this.#index);
+        let unitEnd = unitStart;
+        while (isLetter(source.charCodeAt(unitEnd))) {
+            unitEnd++;
+        }
+        const unit = source.slice(unitStart, unitEnd);
+        // A keyword after a number is a missing comma.
+        if (unit === '' || !isValueEnd(source.charCodeAt(skipSpaces(source, unitEnd))) || ['true', 'false', 'null', 'infinity'].includes(unit)) {
+            return;
+        }
+        const number = source.slice(start, this.#index);
+        // The duration is only suggested when it is valid, which a number with an exponent or a radix prefix, a fraction of a nanosecond, a negative zero, or a value outside the 64-bit range is not. The string is always offered, because a unit such as `m` may mean meters rather than minutes.
+        const duration = DURATION_UNITS.has(unit) && isValidValue(`${number}${unit}`) ? `${abbreviate(number)}${unit}` : '10s';
+        this.#fail(`A unit cannot follow a number after a space. Write a duration without the space, as in ${duration}, and anything else, such as a size, as a string, as in '${abbreviate(`${number} ${unit}`)}'`, unitStart);
+    }
     #isKeyword(word) {
         if (!this.#source.startsWith(word, this.#index)) {
             return false;
@@ -525,10 +673,11 @@ class Parser {
         }
         const code = this.#code();
         if (code === 0x2B /* + */) {
-            this.#fail('A "+" sign is not allowed. A number without a sign is positive');
+            this.#fail('A “+” sign is not allowed. A number without a sign is positive');
         }
+        // A `.` that no digit follows begins a string, such as `.env` or `./foo`, rather than a number.
         if (code === DOT) {
-            this.#fail('A number cannot begin with "."; write a digit before it, as in 0.5');
+            this.#fail(isDigit(this.#code(this.#index + 1)) ? 'A number cannot begin with “.”; write a digit before it, as in 0.5' : describeUnknownWord('.', this.#unquotedText()));
         }
         let wordEnd = this.#index;
         while (isBareKeyCharacter(this.#code(wordEnd))) {
@@ -536,13 +685,66 @@ class Parser {
         }
         if (wordEnd > this.#index) {
             const word = this.#source.slice(this.#index, wordEnd);
-            // An entry whose value was left out, as in `a:` followed by `b: 1` on the next line, reads the next key as the value.
-            if (this.#code(wordEnd) === COLON) {
+            // A key where a value should be, as when the value of an entry is left out and the next line has a key, or as in `[a: 1]`, is reported as a key. A word after the `:` of a member and a space, as in `msg: Error: file not found` or `url: https://example.com`, is that member's value instead, an unquoted string. Without the space, as in `a:b: 1`, the first `:` was most likely meant as part of the key.
+            const spacesStart = skipSpacesBack(this.#source, this.#index);
+            const isMemberValue = spacesStart < this.#index && this.#code(spacesStart - 1) === COLON;
+            if (!isMemberValue && this.#code(wordEnd) === COLON) {
                 this.#fail(`Expected a value, but found the key ${abbreviate(word)}`);
             }
-            this.#fail(describeUnknownWord(word));
+            this.#diagnoseTableHeader(true);
+            this.#fail(describeUnknownWord(word, this.#unquotedText()));
+        }
+        this.#fail(`Expected a value, but found ${this.#describeHere()}${this.#isBlockScalarIndicator() ? '. Write a multiline string as a block string, between \'\'\' lines' : this.#slashCommentHint()}`);
+    }
+    /*
+    The text from `start` that was most likely meant as one unquoted string, such as `John Smith`: up to the end of the line, a comma, a closing bracket, or a comment after a space or a tab, without the spaces and tabs at its end.
+    */
+    #unquotedText(start = this.#index) {
+        const source = this.#source;
+        const limit = Math.min(source.length, start + MAX_DIAGNOSED_LENGTH);
+        let end = start;
+        while (end < limit && !isUnquotedTextEnd(source, end)) {
+            end++;
         }
-        this.#fail(`Expected a value, but found ${this.#describeHere()}`);
+        return source.slice(start, skipSpacesBack(source, end));
+    }
+    /*
+    A TOML table header, as in `[server]` or `[[servers]]` on a line of its own, reads as an array that holds a word, or as a key that starts with "[". Where a value is expected, `isValue`, it is only a table header when its bracket opens the document, because a table cannot be written as an item of an array inside it.
+    */
+    #diagnoseTableHeader(isValue = false) {
+        const source = this.#source;
+        const lineStart = source.lastIndexOf('\n', this.#index - 1) + 1;
+        if (isValue && skipSpaces(source, lineStart) !== this.#documentStart) {
+            return;
+        }
+        const line = source.slice(lineStart, Math.min(findLineEnd(source, this.#index), lineStart + MAX_DIAGNOSED_LENGTH));
+        // The name is a valid key, so that the suggestion is valid.
+        const match = /^[\t ]*\[\[?(?<name>[A-Z_a-z][\w\-]*)\]\]?[\t ]*$/v.exec(line);
+        if (match === null) {
+            return;
+        }
+        const { name } = match.groups;
+        this.#fail(`There are no table headers. Write the table as an object, as in ${abbreviate(name)}: {…}`);
+    }
+    /*
+    A YAML literal block scalar indicator, as in `key: |` or `key: |-`, at the end of its line.
+    */
+    #isBlockScalarIndicator() {
+        const code = this.#code();
+        // A folded block scalar, `>`, joins its lines, which a block string does not, so only `|` gets the hint.
+        if (code !== 0x7C /* | */) {
+            return false;
+        }
+        const chomping = this.#code(this.#index + 1);
+        const end = skipSpaces(this.#source, chomping === DASH || chomping === 0x2B /* + */ ? this.#index + 2 : this.#index + 1);
+        const next = this.#code(end);
+        return next === LF || Number.isNaN(next);
+    }
+    /*
+    The hint for a `//` comment, as in JavaScript.
+    */
+    #slashCommentHint() {
+        return this.#code() === SLASH && this.#code(this.#index + 1) === SLASH ? '. A comment starts with “#”' : '';
     }
     #describeHere() {
         if (this.#isAtEnd()) {
@@ -602,8 +804,9 @@ class Parser {
     #parseEscape(offset) {
         const source = this.#source;
         const character = source[offset + 1];
-        if (character !== undefined && Object.hasOwn(SIMPLE_ESCAPES, character)) {
-            return { text: SIMPLE_ESCAPES[character], end: offset + 2 };
+        const simple = SIMPLE_ESCAPES.get(character ?? '');
+        if (simple !== undefined) {
+            return { text: simple, end: offset + 2 };
         }
         if (character === 'u') {
             UNICODE_ESCAPE.lastIndex = offset + 1;
@@ -612,12 +815,10 @@ class Parser {
                 this.#fail(describeBadUnicodeEscape(source, offset + 1), offset);
             }
             const { hex } = match.groups;
-            if (hex.length > 1 && hex.startsWith('0')) {
-                this.#fail(String.raw `A Unicode escape may not have leading zeros; write \u{${hex.replace(/^0+(?=.)/v, '')}}`, offset);
-            }
             const codePoint = Number.parseInt(hex, 16);
+            // The value is checked before the spelling, so that the leading zeros error never suggests an escape that is not allowed either.
             if (codePoint === 0x0D) {
-                this.#fail(String.raw `A carriage return (U+000D) cannot be represented, so \u{d} is not allowed`, offset);
+                this.#fail(String.raw `A carriage return (U+000D) cannot be represented, so \u{${hex}} is not allowed`, offset);
             }
             if (codePoint >= 0xD8_00 && codePoint <= 0xDF_FF) {
                 this.#fail(String.raw `\u{${hex}} is a surrogate, which is not a Unicode scalar value`, offset);
@@ -625,10 +826,13 @@ class Parser {
             if (codePoint > 0x10_FF_FF) {
                 this.#fail(String.raw `\u{${hex}} is above U+10FFFF, the largest Unicode scalar value`, offset);
             }
+            if (hex.length > 1 && hex.startsWith('0')) {
+                this.#fail(String.raw `A Unicode escape may not have leading zeros; write \u{${hex.replace(/^0+(?=.)/v, '')}}`, offset);
+            }
             return { text: String.fromCodePoint(codePoint), end: offset + 1 + match[0].length };
         }
         // A backslash at the end of the document is the same mistake as one at the end of a line.
-        const reason = ESCAPE_MISTAKES.get(character ?? '\n') ?? `Unknown escape "\\${String.fromCodePoint(source.codePointAt(offset + 1))}". The escapes are \\\\, \\", \\n, \\t, and \\u{…}; use a '...' string for literal backslashes`;
+        const reason = ESCAPE_MISTAKES.get(character ?? '\n') ?? `Unknown escape “\\${String.fromCodePoint(source.codePointAt(offset + 1))}”. The escapes are \\\\, \\", \\n, \\t, and \\u{…}; use a '...' string for literal backslashes`;
         this.#fail(reason, offset);
     }
     /*
@@ -652,7 +856,7 @@ class Parser {
         const contentStart = this.#index + 1;
         const closing = findBlockStringEnd(source, contentStart, quote, delimiterLength);
         if (closing === undefined) {
-            this.#fail('Unterminated block string', start);
+            this.#fail(`Unterminated block string${this.#describeInlineClosingDelimiter(contentStart, quote, delimiterLength)}`, start);
         }
         const indentation = source.slice(closing.lineStart, closing.delimiterStart);
         this.#index = closing.delimiterStart + delimiterLength;
@@ -660,7 +864,7 @@ class Parser {
         for (let lineStart = contentStart; lineStart < closing.lineStart; lineStart = findLineEnd(source, lineStart) + 1) {
             const line = source.slice(lineStart, findLineEnd(source, lineStart));
             // A blank line, which is empty or holds only spaces and tabs, may leave out the indentation, and it becomes an empty line. Swift is stricter here: there only a completely empty line may leave it out.
-            if (BLANK_LINE.test(line)) {
+            if (isBlankLine(line)) {
                 contents.push({ text: '', offset: lineStart });
             }
             else if (line.startsWith(indentation)) {
@@ -682,6 +886,24 @@ class Parser {
         const kept = contents.slice(first, last);
         return quote === SINGLE_QUOTE ? kept.map(line => line.text).join('\n') : kept.map(line => this.#unescapeLine(line.text, line.offset)).join('\n');
     }
+    /*
+    The hint for a content line that ends with the delimiter, as TOML allows. Adding a closing line after it would keep the delimiter as content.
+    */
+    #describeInlineClosingDelimiter(contentStart, quote, delimiterLength) {
+        const source = this.#source;
+        const quoteCharacter = String.fromCharCode(quote);
+        const delimiter = quoteCharacter.repeat(delimiterLength);
+        let line = source.slice(0, contentStart).split('\n').length;
+        for (let lineStart = contentStart; lineStart < source.length; lineStart = findLineEnd(source, lineStart) + 1) {
+            const text = source.slice(skipSpaces(source, lineStart), skipSpacesBack(source, findLineEnd(source, lineStart)));
+            // A line of only quotes, longer than the delimiter, is content.
+            if (text.endsWith(delimiter) && text !== quoteCharacter.repeat(text.length)) {
+                return `. Its closing delimiter must start a line, so move the ${delimiter} at the end of line ${line} to a new line`;
+            }
+            line++;
+        }
+        return '';
+    }
     #unescapeLine(text, offset) {
         let value = '';
         let chunkStart = 0;
@@ -710,17 +932,16 @@ class Parser {
             return this.#parseDuration(text, start);
         }
         switch (kind) {
-            case 'decimal':
-            case 'radix': {
+            case 'int': {
                 if (text === '-0') {
-                    this.#fail('"-0" is not allowed, because zero has one spelling: 0', start);
+                    this.#fail('“-0” is not allowed, because zero has one spelling: 0', start);
                 }
                 return this.#integer(text.replaceAll('_', ''), text, start);
             }
             case 'float': {
                 const value = Number(text.replaceAll('_', ''));
                 if (!Number.isFinite(value)) {
-                    this.#fail(`${abbreviate(text)} is too large to be a finite float. Use infinity if you mean it`, start);
+                    this.#fail(`${abbreviate(text)} is too large to be a finite float. Use ${value < 0 ? '-infinity' : 'infinity'} if you mean it`, start);
                 }
                 if (value === 0) {
                     // A nonzero digit before the exponent means the literal is not zero, so it underflowed.
@@ -736,7 +957,49 @@ class Parser {
                 break;
             }
         }
-        this.#fail(describeBadNumber(text), start);
+        this.#fail(this.#describeThousandsSeparator(text, start) ?? describeBadNumber(text, this.#unquotedText(start)), start);
+    }
+    /*
+    A comma used as a thousands separator, as in `[1,000]`, makes the group after it a separate item, which fails only when it has a leading zero. Writing that item in octal, as the leading zero message suggests, would parse to the wrong items.
+    */
+    #describeThousandsSeparator(text, start) {
+        if (!/^0\d{2}$/v.test(text) || this.#code(start - 1) !== COMMA) {
+            return undefined;
+        }
+        const getGroupStart = (groupEnd) => {
+            let groupStart = groupEnd;
+            while (isDigit(this.#code(groupStart - 1))) {
+                groupStart--;
+            }
+            return groupStart;
+        };
+        let groupEnd = start - 1;
+        let numberStart = getGroupStart(groupEnd);
+        // Earlier groups of three digits, as in `12,345,000`.
+        while (groupEnd - numberStart === 3 && this.#code(numberStart - 1) === COMMA && isDigit(this.#code(numberStart - 2))) {
+            groupEnd = numberStart - 1;
+            numberStart = getGroupStart(groupEnd);
+        }
+        const before = this.#code(numberStart - 1);
+        // The first group has one to three digits, which are not the end of a float, of a number with underscores, or of a number with a radix prefix.
+        if (numberStart === groupEnd
+            || before === DOT
+            || before === 0x5F /* _ */
+            || numberStart < groupEnd - 3
+            || isLetter(before)) {
+            return undefined;
+        }
+        // The sign belongs to the number, as in `-1,000`.
+        if (before === DASH) {
+            numberStart--;
+        }
+        const groupsStart = start + text.length;
+        const groups = /^(?:,\d{3}(?!\d))*/v.exec(this.#source.slice(groupsStart, groupsStart + MAX_DIAGNOSED_LENGTH))[0];
+        const number = this.#source.slice(numberStart, groupsStart + groups.length);
+        const reason = `Leading zeros are not allowed in a decimal number. A comma separates items, so ${abbreviate(number)} is not one number`;
+        // Both spellings are the same int, so they are suggested only when it is in range.
+        const withUnderscores = number.replaceAll(',', '_');
+        return isValidValue(withUnderscores) ? `${reason}. Write it as ${abbreviate(withUnderscores)} or ${abbreviate(number.replaceAll(',', ''))}` : reason;
     }
     /*
     The common case, a short decimal int or float such as `8080`, `-3`, or `30.5`, without the general path's maximal-run scan and classification. Anything else, including every error, returns `undefined` and is left to the general path.
@@ -750,7 +1013,7 @@ class Parser {
             index++;
         }
         const integerLength = index - integerStart;
-        // No digits, or a leading zero, which is either `0` alone or an error.
+        // No digits, or a leading zero followed by more digits, which the general path reports as an error or reads as an instant before the year 1000.
         if (integerLength === 0 || (integerLength > 1 && source.charCodeAt(integerStart) === 0x30)) {
             return;
         }
@@ -766,9 +1029,8 @@ class Parser {
             }
             isFloat = true;
         }
-        const next = source.charCodeAt(index);
         // At most 15 digits, so an int is exact as a number. A character that may continue a number, such as `e`, `_`, or `-`, needs the general path.
-        if (index - integerStart > 15 || (index < source.length && (next >= 128 || valueEndCharacters[next] !== 1))) {
+        if (index - integerStart > 15 || !isValueEnd(source.charCodeAt(index))) {
             return;
         }
         const value = Number(source.slice(start, index));
@@ -811,7 +1073,14 @@ class Parser {
     #parseInstant(text, start) {
         const match = text.length > MAX_DIAGNOSED_LENGTH ? null : INSTANT.exec(text);
         if (match === null) {
-            this.#fail(describeBadInstant(text), start);
+            // A date, a space, and a time, as TOML and Python write a date and time.
+            const timeStart = this.#index + 1;
+            const end = this.#code() === SPACE && isDigit(this.#code(timeStart)) ? findNumberEnd(this.#source, timeStart) : this.#index;
+            const time = this.#source.slice(timeStart, end);
+            // More of the instant may follow, as in `14:00:00,5Z` or `14:00:00[Europe/Oslo]`, so it may have an offset.
+            const next = this.#code(end);
+            const isWholeValue = isValueEnd(next) && !(next === COMMA && isDigit(this.#code(end + 1)));
+            this.#fail(describeBadInstant(text, time, isWholeValue), start);
         }
         const { year, month, day, hour, minute, second, fraction, offset, offsetHour, offsetMinute } = match.groups;
         const check = (isValid, reason) => {
@@ -830,12 +1099,13 @@ class Parser {
         if (offset !== 'Z') {
             check(offsetHour <= '23', 'the offset hour must be 00 to 23');
             check(offsetMinute <= '59', 'the offset minute must be 00 to 59');
-            check(offset !== '-00:00', '-00:00 means "offset unknown" in RFC 3339, which is not representable; use Z or +00:00');
+            check(offset !== '-00:00', '-00:00 means “offset unknown” in RFC 3339, which is not representable; use Z or +00:00');
         }
-        const instant = requireTemporal().Instant.from(text);
-        const nanoseconds = instant.epochNanoseconds;
+        // `Date.parse()` reads this format exactly, for every year from 0001 to 9999 and every offset, so the range check needs no `Temporal`.
+        const milliseconds = Date.parse(`${year}-${month}-${day}T${hour}:${minute}:${second}${offset}`);
+        const nanoseconds = (BigInt(milliseconds) * 1000000n) + BigInt((fraction ?? '').padEnd(9, '0'));
         check(nanoseconds >= MIN_INSTANT && nanoseconds <= MAX_INSTANT, 'in UTC it falls outside the years 0001 to 9999');
-        return instant;
+        return this.#createTime(new Time('Instant', nanoseconds));
     }
     /*
     A scan of the parts in order, so that each error names the part it is about.
@@ -859,7 +1129,7 @@ class Parser {
                 if (code === DASH && isDigit(text.charCodeAt(index + 1))) {
                     fail('only the whole duration takes a sign, as in -1h30m');
                 }
-                fail(code === 0x2B /* + */ ? 'a "+" sign is not allowed' : `expected a number at "${abbreviate(text.slice(index), 10)}"`);
+                fail(code === 0x2B /* + */ ? 'a “+” sign is not allowed' : `expected a number at “${abbreviate(text.slice(index), 10)}”`);
             }
             if (text.charCodeAt(index) === 0x30 && (next === 0x5F /* _ */ || isDigit(next))) {
                 fail('leading zeros are not allowed');
@@ -872,7 +1142,7 @@ class Parser {
             if (next === DOT) {
                 unitStart = skipDigits(text, digitsEnd + 1, isDigit);
                 if (unitStart === digitsEnd + 1) {
-                    fail('a "." must be followed by a digit');
+                    fail('a “.” must be followed by a digit');
                 }
                 if (text.charCodeAt(unitStart) === 0x5F /* _ */) {
                     fail('an underscore must be between two digits');
@@ -887,7 +1157,7 @@ class Parser {
             const unit = text.slice(unitStart, unitEnd);
             const rank = DURATION_UNIT_NAMES.indexOf(unit);
             if (rank === -1) {
-                fail(describeBadDurationUnit(unit));
+                fail(describeBadDurationUnit(unit, text));
             }
             if (rank <= previousRank) {
                 fail('the units are in the order h, m, s, ms, us, ns, and each appears at most once');
@@ -915,15 +1185,16 @@ class Parser {
             total += fractionNanoseconds / scale;
         }
         if (isNegative && total === 0n) {
-            fail('"-" is not allowed before zero, because zero has one spelling: 0s');
+            fail('“-” is not allowed before zero, because zero has one spelling: 0s');
         }
         if (total > (isNegative ? -INT64_MIN : INT64_MAX)) {
             fail('it is outside the 64-bit range of nanoseconds, about 292 years either way');
         }
-        return createDuration(isNegative ? -total : total);
+        return this.#createTime(new Time('Duration', isNegative ? -total : total));
     }
     parseDocument() {
         this.#skipTrivia();
+        this.#documentStart = this.#index;
         if (this.#isAtEnd()) {
             this.#fail('A document must contain an object or an array, but this one is empty');
         }
@@ -946,13 +1217,24 @@ class Parser {
     }
 }
 /*
-Whether `text` is a decimal int, a radix int, or a float, following the grammar. A run of digits may have single underscores between digits.
+Whether `text` is one valid value, so that an error message only suggests a fix that works.
+*/
+function isValidValue(text) {
+    try {
+        return new Parser(`[${text}]`, 'bigint', time => time).parseDocument().length === 1;
+    }
+    catch {
+        return false;
+    }
+}
+/*
+Whether `text` is an int, in any radix, or a float, following the grammar. A run of digits may have single underscores between digits.
 */
 function classifyNumber(text) {
-    const radix = text.charCodeAt(0) === 0x30 ? RADIX_DIGIT[text.charAt(1)] : undefined;
+    const radix = text.charCodeAt(0) === 0x30 ? RADIX_DIGIT.get(text.charAt(1)) : undefined;
     if (radix !== undefined) {
         const end = skipDigits(text, 2, radix);
-        return end > 2 && end === text.length ? 'radix' : undefined;
+        return end > 2 && end === text.length ? 'int' : undefined;
     }
     let index = text.charCodeAt(0) === DASH ? 1 : 0;
     // The integer part is `0` or has no leading zero.
@@ -961,7 +1243,7 @@ function classifyNumber(text) {
         return undefined;
     }
     index = integerEnd;
-    let kind = 'decimal';
+    let kind = 'int';
     if (text.charCodeAt(index) === DOT) {
         const end = skipDigits(text, index + 1, isDigit);
         if (end === index + 1) {
@@ -1037,7 +1319,7 @@ function isDurationLike(text) {
     }
     return /^[dhmnsuw]$/iv.test(text.charAt(index));
 }
-function describeBadDurationUnit(unit) {
+function describeBadDurationUnit(unit, text) {
     if (unit === '') {
         return 'every number needs a unit: h, m, s, ms, us, or ns';
     }
@@ -1047,12 +1329,24 @@ function describeBadDurationUnit(unit) {
     if (/^w(?:eeks?)?$/v.test(unit)) {
         return 'there is no week unit, because a day is not a fixed length. Write 168h for a fixed 168 hours';
     }
-    return DURATION_UNITS.has(unit.toLowerCase()) ? `the units are lowercase: ${unit.toLowerCase()}` : `"${abbreviate(unit, 10)}" is not a unit. The units are h, m, s, ms, us, and ns, and a string must be quoted`;
+    if (unit === 'M') {
+        // A number with `M` alone is more often a size, as in `memory: 512M`, and `512m` would read as minutes.
+        const sizeHint = text.length <= MAX_DIAGNOSED_LENGTH && /^\d[\d_]*M$/v.test(text) ? `. A size, such as 512M, is a string: '${abbreviate(text)}'` : '';
+        return `there is no month unit, because a month is not a fixed length${sizeHint}`;
+    }
+    return DURATION_UNITS.has(unit.toLowerCase()) ? `the units are lowercase: ${unit.toLowerCase()}` : `“${abbreviate(unit, 10)}” is not a unit. The units are h, m, s, ms, us, and ns, and a string must be quoted`;
+}
+/*
+The number of spaces and tabs before `offset` on its line, or `undefined` when something else comes before it.
+*/
+function getIndentation(source, offset) {
+    const lineStart = source.lastIndexOf('\n', offset - 1) + 1;
+    return skipSpaces(source, lineStart) === offset ? offset - lineStart : undefined;
 }
 function isWordsWithSpaces(text) {
     for (let index = 0; index < text.length; index++) {
         const code = text.charCodeAt(index);
-        if (code !== SPACE && code !== TAB && !isBareKeyCharacter(code)) {
+        if (!isSpace(code) && !isBareKeyCharacter(code)) {
             return false;
         }
     }
@@ -1065,23 +1359,38 @@ function daysInMonth(year, month) {
     }
     return [4, 6, 9, 11].includes(month) ? 30 : 31;
 }
-function describeUnknownWord(word) {
-    const lowercase = word.toLowerCase();
+function isUnquotedTextEnd(source, index) {
+    const code = source.charCodeAt(index);
+    const isComment = code === HASH || (code === SLASH && source.charCodeAt(index + 1) === ASTERISK);
+    return code === LF || code === COMMA || code === CLOSE_BRACKET || code === CLOSE_BRACE || (isComment && isSpace(source.charCodeAt(index - 1)));
+}
+/*
+The example in a message that a string must be quoted, which quotes `text` as a `'...'` string. That cannot hold a `'`, so then there is no simple example.
+*/
+function quotingExample(text) {
+    return text.includes('\'') ? '' : `, as in '${abbreviate(text)}'`;
+}
+/*
+`text` is the unquoted string that `word` begins, which the suggestion quotes.
+*/
+function describeUnknownWord(word, text) {
+    // A keyword hint is only for the word on its own. In `Yes please` or `Nan Goldin`, following it would leave text behind or change the value.
+    const lowercase = text === word ? word.toLowerCase() : '';
     if (['true', 'false', 'yes', 'no', 'on', 'off'].includes(lowercase)) {
-        return `"${word}" is not a value. Booleans are written true and false, in lowercase`;
+        return `“${word}” is not a value. Booleans are written true and false, in lowercase`;
     }
     if (['null', 'nil', 'none', 'undefined'].includes(lowercase)) {
-        return `"${word}" is not a value. Null is written null, in lowercase`;
+        return `“${word}” is not a value. Null is written null, in lowercase`;
     }
     if (lowercase === 'nan') {
         return 'NaN is not representable. Use null for a missing value';
     }
-    return ['inf', 'infinity'].includes(lowercase) ? `"${word}" is not a value. Infinity is written infinity, in lowercase` : `Unexpected "${abbreviate(word)}". A string value must be quoted, as in '${abbreviate(word)}'`;
+    return ['inf', 'infinity'].includes(lowercase) ? `“${word}” is not a value. Infinity is written infinity, in lowercase` : `Unexpected “${abbreviate(word)}”. A string value must be quoted${quotingExample(text)}`;
 }
 function describeBadUnicodeEscape(source, offset) {
     const rest = source.slice(offset, offset + 12);
     if (/^u[\dA-Fa-f]{4}/v.test(rest)) {
-        return `The four-digit \\${rest.slice(0, 5)} form is not an escape. Write \\u{${rest.slice(1, 5).toLowerCase().replace(/^0+(?=.)/v, '')}}`;
+        return describeFourDigitEscape(rest);
     }
     if (/^u\{[\dA-Fa-f]*[A-F]/v.test(rest)) {
         return 'A Unicode escape uses lowercase hexadecimal digits';
@@ -1091,15 +1400,36 @@ function describeBadUnicodeEscape(source, offset) {
     }
     return /^u\{[\da-f]{7}/v.test(rest) ? 'A Unicode escape has at most six hexadecimal digits' : String.raw `A Unicode escape is written \u{…} with one to six lowercase hexadecimal digits`;
 }
-function describeBadNumber(fullText) {
+/*
+The JSON form `\uXXXX`, from its `u`, with the escape to write instead. JSON writes a character above U+FFFF as two of them, a surrogate pair, which is one `\u{…}` escape here. Here, a lone surrogate and a carriage return have no escape.
+*/
+function describeFourDigitEscape(rest) {
+    const code = Number.parseInt(rest.slice(1, 5), 16);
+    const low = /^\\u[\dA-Fa-f]{4}/v.test(rest.slice(5)) ? rest.slice(7, 11) : undefined;
+    const lowCode = low === undefined ? NaN : Number.parseInt(low, 16);
+    if (code >= 0xD8_00 && code <= 0xDB_FF && lowCode >= 0xDC_00 && lowCode <= 0xDF_FF) {
+        const codePoint = 0x1_00_00 + ((code - 0xD8_00) * 0x4_00) + (lowCode - 0xDC_00);
+        return `The four-digit \\${rest.slice(0, 5)}\\u${low} form is not an escape. Write \\u{${codePoint.toString(16)}}`;
+    }
+    const form = `The four-digit \\${rest.slice(0, 5)} form is not an escape`;
+    if (code >= 0xD8_00 && code <= 0xDF_FF) {
+        return String.raw `${form}, and a lone surrogate is not a Unicode scalar value. Write the character it is half of as one \u{…} escape`;
+    }
+    return code === 0x0D ? `${form}, and a carriage return (U+000D) cannot be represented` : String.raw `${form}. Write \u{${code.toString(16)}}`;
+}
+/*
+`unquotedText` is the unquoted string that `fullText` begins, for the suggestion to quote it.
+*/
+function describeBadNumber(fullText, unquotedText) {
     const text = fullText.slice(0, MAX_DIAGNOSED_LENGTH);
     if (text.includes('+')) {
-        return 'A "+" sign is not allowed in a number, including in an exponent';
+        return 'A “+” sign is not allowed in a number, including in an exponent';
     }
     if (/^-?0[BOX]/v.test(text)) {
         return 'A number prefix is lowercase: 0x, 0o, or 0b';
     }
-    const radixMatch = /^(?<sign>-?)0(?<radix>[box])(?<digits>.*)$/v.exec(text);
+    // The whole number, not the part cut at the diagnosed length, because a cut can end before the digit or the underscore that the message is about. Each check below takes linear time.
+    const radixMatch = /^(?<sign>-?)0(?<radix>[box])(?<digits>.*)$/v.exec(fullText);
     if (radixMatch !== null) {
         const { sign, radix, digits } = radixMatch.groups;
         const name = RADIX_NAME[radix];
@@ -1107,26 +1437,44 @@ function describeBadNumber(fullText) {
             return `${RADIX_ARTICLE[radix]} ${name} integer cannot have a sign, because it states a bit pattern rather than a quantity`;
         }
         if (digits === '') {
-            return `Expected ${name} digits after "0${radix}"`;
+            return `Expected ${name} digits after “0${radix}”`;
         }
         if (radix === 'x' && /[a-f]/v.test(digits) && !/[^\da-f_]/iv.test(digits)) {
-            return `Hexadecimal digits are uppercase: 0x${abbreviate(digits.toUpperCase())}`;
+            // The uppercase spelling is only suggested when it is valid, so a misplaced underscore is reported first, and a value outside the 64-bit range gets no example.
+            if (!/^[\da-f]+(?:_[\da-f]+)*$/iv.test(digits)) {
+                return 'An underscore in a number must be between two digits';
+            }
+            const uppercase = `0x${digits.toUpperCase()}`;
+            return isValidValue(uppercase) ? `Hexadecimal digits are uppercase: ${abbreviate(uppercase)}` : 'Hexadecimal digits are uppercase';
         }
-        const validCharacter = { x: /[\dA-F_]/v, o: /[0-7_]/v, b: /[01_]/v }[radix];
+        // A lowercase hexadecimal digit is a digit in the wrong case, so the one named is a character that is no digit in either case.
+        const validCharacter = { x: /[\da-f_]/iv, o: /[0-7_]/v, b: /[01_]/v }[radix];
         const character = [...digits].find(character => !validCharacter.test(character));
-        return character === undefined ? 'An underscore in a number must be between two digits' : `Invalid ${name} digit "${character}"`;
+        return character === undefined ? 'An underscore in a number must be between two digits' : `Invalid ${name} digit “${character}”`;
     }
     if (/^-?\d[\d_]*E/v.test(text) || /^-?\d[\d_]*\.[\d_]+E/v.test(text)) {
-        return 'An exponent marker is a lowercase "e"';
+        return 'An exponent marker is a lowercase “e”';
     }
     if (/^-?[\d_]+\.(?:$|[^\d_])/v.test(text)) {
         return 'A decimal point must be followed by a digit';
     }
     if (text.startsWith('-.')) {
-        return 'A number cannot begin with "."; write a digit before it, as in -0.5';
+        return 'A number cannot begin with “.”; write a digit before it, as in -0.5';
+    }
+    if (/^\d+(?::\d+)+$/v.test(text)) {
+        return /^\d{1,2}:\d{2}(?::\d{2}(?:\.\d+)?)?$/v.test(text) ? 'A time of day is a string, so it must be quoted' : `Invalid number “${abbreviate(text)}”. A value that contains “:” must be quoted, as in '${abbreviate(text)}'`;
     }
     if (/^-?0[\d_]/v.test(text)) {
-        return 'Leading zeros are not allowed in a decimal number';
+        // Removing the zero gives a valid number with a different meaning, so the message says what the zero usually meant.
+        // A `'...'` string cannot hold a `'`, so then there is no example.
+        const identifier = `an identifier, such as a ZIP code, as a string${unquotedText.includes('\'') ? '' : `: '${abbreviate(unquotedText)}'`}`;
+        // The octal suggestion is only for the number on its own, not for one that more text follows, as in `0412 345 678`, and only when it is in range. It is decided on the whole number, because a cut can end before a digit that is not octal or that changes the value.
+        const digits = fullText.replace(/^0+/v, '');
+        const octal = `0o${digits === '' ? '0' : digits}`;
+        if (unquotedText === fullText && /^0[0-7]+$/v.test(fullText) && isValidValue(octal)) {
+            return `Leading zeros are not allowed in a decimal number. Write an octal number, such as a file mode, as ${abbreviate(octal)}, and ${identifier}`;
+        }
+        return /^0\d+$/v.test(text) ? `Leading zeros are not allowed in a decimal number. Write ${identifier}` : 'Leading zeros are not allowed in a decimal number';
     }
     if (/_(?:$|\D)|(?:^|\D)_/v.test(text)) {
         return 'An underscore in a number must be between two digits';
@@ -1135,37 +1483,65 @@ function describeBadNumber(fullText) {
         return 'Leading zeros are not allowed in an exponent';
     }
     if (/^-?\d[\d_]*(?:\.[\d_]+)?e-0$/v.test(text)) {
-        return '"e-0" is not allowed, because an exponent of zero has one spelling: e0';
+        return '“e-0” is not allowed, because an exponent of zero has one spelling: e0';
     }
     if (/e-?$/v.test(text)) {
-        return 'Expected digits after the exponent marker "e"';
+        return 'Expected digits after the exponent marker “e”';
     }
     if (text.split('.').length > 2) {
-        return `Invalid number "${abbreviate(text)}". A value with several dots, such as a version number, must be quoted`;
+        return `Invalid number “${abbreviate(text)}”. A value with several dots, such as a version number, must be quoted`;
     }
     if (/^-(?:\D|$)/v.test(text)) {
         if (/^-nan/iv.test(text)) {
             return 'NaN is not representable. Use null for a missing value';
         }
-        return /^-inf/iv.test(text) ? `"${abbreviate(text)}" is not a value. Negative infinity is written -infinity` : 'Expected a digit or "infinity" after "-"';
+        return /^-inf/iv.test(text) ? `“${abbreviate(text)}” is not a value. Negative infinity is written -infinity` : 'Expected a digit or “infinity” after “-”';
     }
-    return /[A-Za-z]/v.test(text) ? `Invalid number "${abbreviate(text)}". A string value must be quoted, as in '${abbreviate(text)}'` : `Invalid number "${abbreviate(text)}"`;
+    return /[A-Za-z]/v.test(text) ? `Invalid number “${abbreviate(text)}”. A string value must be quoted${quotingExample(unquotedText)}` : `Invalid number “${abbreviate(text)}”`;
 }
-function describeBadInstant(text) {
+/*
+A date alone, which is not an instant. The instant it could be is only shown when the date exists, so that the example is valid.
+*/
+function describeDate(date) {
+    const [year, month, day] = date.split('-').map(Number);
+    const isExisting = year >= 1 && month >= 1 && month <= 12 && day >= 1 && day <= daysInMonth(year, month);
+    return `${date} is a date, not an instant. Write a date as a string, as in '${date}'${isExisting ? `. An instant needs a time and an offset, as in ${date}T00:00:00Z` : ''}`;
+}
+/*
+`time` is the token after a space that follows `text`, or an empty string. `isWholeValue` is whether nothing that may be part of the instant follows `text`.
+*/
+function describeBadInstant(text, time, isWholeValue) {
     if (text.length > MAX_DIAGNOSED_LENGTH) {
-        return `Invalid instant "${abbreviate(text)}". An instant is written as 2026-09-19T14:00:00Z, with an optional fraction of up to nine digits and an offset of Z or ±HH:MM`;
+        return `Invalid instant “${abbreviate(text)}”. ${INSTANT_FORMAT}`;
     }
     if (/^\d{4}-\d{2}-\d{2}$/v.test(text)) {
-        return `${text} is a date, not an instant. An instant needs a time and an offset, as in ${text}T00:00:00Z; use a string for a date`;
+        return /^\d{2}:\d{2}/v.test(time) ? describeSpaceSeparatedInstant(text, time, isWholeValue) : describeDate(text);
     }
     if (/^\d{4}-\d{2}-\d{2}t/v.test(text)) {
-        return 'The date and time separator in an instant is an uppercase "T"';
+        return 'The date and time separator in an instant is an uppercase “T”';
     }
     if (text.endsWith('z')) {
-        return 'The UTC offset in an instant is an uppercase "Z"';
+        return 'The UTC offset in an instant is an uppercase “Z”';
     }
     if (/[+\-]\d{4}$/v.test(text)) {
         return 'An instant\'s offset is written with a colon, as in +07:00';
     }
-    return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?$/v.test(text) ? 'An instant needs an offset: Z or ±HH:MM' : `Invalid instant "${abbreviate(text)}". An instant is written as 2026-09-19T14:00:00Z, with an optional fraction of up to nine digits and an offset of Z or ±HH:MM`;
+    if (!LOCAL_DATE_TIME.test(text)) {
+        return `Invalid instant “${abbreviate(text)}”. ${INSTANT_FORMAT}`;
+    }
+    return isWholeValue ? `An instant needs an offset: Z or ±HH:MM. A date and time without an offset is a local time, which is not an instant, so write it as a string, as in '${abbreviate(text)}', or add the offset it was meant in` : 'An instant needs an offset: Z or ±HH:MM';
+}
+/*
+A date and a time with a space between them, where an instant has a "T". Following the example must not turn a local time into UTC silently, so a time without an offset is described as what it is. An instant is only shown when it is valid, so a date that does not exist, a time out of range, or an instant outside the years 0001 to 9999 in UTC gets the general format instead.
+*/
+function describeSpaceSeparatedInstant(date, time, isWholeValue) {
+    const separator = 'The date and time separator in an instant is an uppercase “T”, not a space';
+    const instant = `${date}T${time}`;
+    if (instant.length > MAX_DIAGNOSED_LENGTH) {
+        return `${separator}. ${INSTANT_FORMAT}`;
+    }
+    if (isValidValue(instant)) {
+        return `${separator}, as in ${abbreviate(instant)}`;
+    }
+    return isWholeValue && LOCAL_DATE_TIME.test(instant) && isValidValue(`${instant}Z`) ? `${separator}, and an instant needs the offset it was meant in, as in ${abbreviate(instant)}Z for UTC. A date and time without an offset is a local time, which is not an instant, so write it as a string, as in '${abbreviate(`${date} ${time}`)}'` : `${separator}. ${INSTANT_FORMAT}`;
 }