@ttsc/win32-arm64 0.33.1 → 0.34.0

package/bin/go/src/encoding/json/internal/jsonwire/wire.go

@@ -17,7 +17,7 @@ import (
 	"unicode/utf8"
 )
 
-// TrimSuffixWhitespace trims JSON from the end of b.
+// TrimSuffixWhitespace trims JSON whitespace from the end of b.
 func TrimSuffixWhitespace(b []byte) []byte {
 	// NOTE: The arguments and logic are kept simple to keep this inlinable.
 	n := len(b) - 1
@@ -59,8 +59,8 @@ func TrimSuffixByte(b []byte, c byte) []byte {
 }
 
 // QuoteRune quotes the first rune in the input.
-func QuoteRune[Bytes ~[]byte | ~string](b Bytes) string {
-	r, n := utf8.DecodeRuneInString(string(truncateMaxUTF8(b)))
+func QuoteRune(b []byte) string {
+	r, n := utf8.DecodeRune(b)
 	if r == utf8.RuneError && n == 1 {
 		return `'\x` + strconv.FormatUint(uint64(b[0]), 16) + `'`
 	}
@@ -70,7 +70,7 @@ func QuoteRune[Bytes ~[]byte | ~string](b Bytes) string {
 // CompareUTF16 lexicographically compares x to y according
 // to the UTF-16 codepoints of the UTF-8 encoded input strings.
 // This implements the ordering specified in RFC 8785, section 3.2.3.
-func CompareUTF16[Bytes ~[]byte | ~string](x, y Bytes) int {
+func CompareUTF16(x, y []byte) int {
 	// NOTE: This is an optimized, mostly allocation-free implementation
 	// of CompareUTF16Simple in wire_test.go. FuzzCompareUTF16 verifies that the
 	// two implementations agree on the result of comparing any two strings.
@@ -93,8 +93,8 @@ func CompareUTF16[Bytes ~[]byte | ~string](x, y Bytes) int {
 		}
 
 		// Decode next pair of runes as UTF-8.
-		rx, nx := utf8.DecodeRuneInString(string(truncateMaxUTF8(x)))
-		ry, ny := utf8.DecodeRuneInString(string(truncateMaxUTF8(y)))
+		rx, nx := utf8.DecodeRune(x)
+		ry, ny := utf8.DecodeRune(y)
 
 		selfx := isUTF16Self(rx)
 		selfy := isUTF16Self(ry)
@@ -123,49 +123,41 @@ func CompareUTF16[Bytes ~[]byte | ~string](x, y Bytes) int {
 	}
 }
 
-// truncateMaxUTF8 truncates b such it contains at least one rune.
-//
-// The utf8 package currently lacks generic variants, which complicates
-// generic functions that operates on either []byte or string.
-// As a hack, we always call the utf8 function operating on strings,
-// but always truncate the input such that the result is identical.
-//
-// Example usage:
-//
-//	utf8.DecodeRuneInString(string(truncateMaxUTF8(b)))
-//
-// Converting a []byte to a string is stack allocated since
-// truncateMaxUTF8 guarantees that the []byte is short.
-func truncateMaxUTF8[Bytes ~[]byte | ~string](b Bytes) Bytes {
-	// TODO(https://go.dev/issue/56948): Remove this function and
-	// instead directly call generic utf8 functions wherever used.
-	if len(b) > utf8.UTFMax {
-		return b[:utf8.UTFMax]
-	}
-	return b
-}
-
 // TODO(https://go.dev/issue/70547): Use utf8.ErrInvalid instead.
 var ErrInvalidUTF8 = errors.New("invalid UTF-8")
 
 func NewInvalidCharacterError[Bytes ~[]byte | ~string](prefix Bytes, where string) error {
-	what := QuoteRune(prefix)
-	return errors.New("invalid character " + what + " " + where)
+	_, n := utf8.DecodeRune([]byte(prefix))
+	return &InvalidTextError{"character", string(prefix[:n]), where}
 }
 
 func NewInvalidEscapeSequenceError[Bytes ~[]byte | ~string](what Bytes) error {
-	label := "escape sequence"
 	if len(what) > 6 {
-		label = "surrogate pair"
+		return &InvalidTextError{"surrogate pair", string(what), "in string"}
 	}
-	needEscape := strings.IndexFunc(string(what), func(r rune) bool {
+	return &InvalidTextError{"escape sequence", string(what), "in string"}
+}
+
+type InvalidTextError struct {
+	Label string // e.g., "character" | "escape sequence" | "surrogate pair"
+	What  string // raw invalid text
+	Where string // e.g., "in string" | "at start of value"
+}
+
+func (e *InvalidTextError) Error() string {
+	var what string
+	needEscape := strings.ContainsFunc(e.What, func(r rune) bool {
 		return r == '`' || r == utf8.RuneError || unicode.IsSpace(r) || !unicode.IsPrint(r)
-	}) >= 0
-	if needEscape {
-		return errors.New("invalid " + label + " " + strconv.Quote(string(what)) + " in string")
-	} else {
-		return errors.New("invalid " + label + " `" + string(what) + "` in string")
+	})
+	switch {
+	case utf8.RuneCount([]byte(e.What)) == 1:
+		what = QuoteRune([]byte(e.What))
+	case needEscape:
+		what = strconv.Quote(e.What)
+	default:
+		what = "`" + e.What + "`"
 	}
+	return strings.TrimSuffix("invalid "+e.Label+" "+what+" "+e.Where, " ")
 }
 
 // TruncatePointer optionally truncates the JSON pointer,

package/bin/go/src/encoding/json/jsontext/decode.go

@@ -34,11 +34,11 @@ import (
 //     return the end of the consumed JSON token as a position,
 //     also relative to the start of Decoder.buf.
 //
-//   - In the event of an I/O errors or state machine violations,
+//   - In the event of an I/O error or state machine violations,
 //     the implementation avoids mutating the state of Decoder
 //     (aside from the book-keeping needed to implement Decoder.fetch).
 //     For this reason, only Decoder.ReadToken and Decoder.ReadValue are
-//     responsible for updated Decoder.prevStart and Decoder.prevEnd.
+//     responsible for updating Decoder.prevStart and Decoder.prevEnd.
 //
 //   - For performance, much of the implementation uses the pattern of calling
 //     the inlinable consumeXXX functions first, and if more work is necessary,
@@ -71,7 +71,7 @@ import (
 //	d.ReadValue() // {"k":"v"}
 //	d.ReadToken() // }
 //
-// The above is one of many possible sequence of calls and
+// The above is one of many possible sequences of calls and
 // may not represent the most sensible method to call for any given token/value.
 // For example, it is probably more common to call [Decoder.ReadToken] to obtain a
 // string token for object names.
@@ -80,7 +80,7 @@ type Decoder struct {
 }
 
 // decoderState is the low-level state of Decoder.
-// It has exported fields and method for use by the "json" package.
+// It has exported fields and methods for use by the "json" package.
 type decoderState struct {
 	state
 	decodeBuffer
@@ -126,7 +126,7 @@ func NewDecoder(r io.Reader, opts ...Options) *Decoder {
 }
 
 // Reset resets a decoder such that it is reading afresh from r and
-// configured with the provided options. Reset must not be called on an
+// configured with the provided options. Reset must not be called on
 // a Decoder passed to the [encoding/json/v2.UnmarshalerFrom.UnmarshalJSONFrom] method
 // or the [encoding/json/v2.UnmarshalFromFunc] function.
 func (d *Decoder) Reset(r io.Reader, opts ...Options) {
@@ -154,7 +154,7 @@ func (d *decoderState) reset(b []byte, r io.Reader, opts ...Options) {
 	d.Struct = opts2
 }
 
-// Options returns the options used to construct the encoder and
+// Options returns the options used to construct the decoder and
 // may additionally contain semantic options passed to a
 // [encoding/json/v2.UnmarshalDecode] call.
 //
@@ -166,6 +166,8 @@ func (d *Decoder) Options() Options {
 	return &d.s.Struct
 }
 
+func (d *decoderState) options() *jsonopts.Struct { return &d.Struct }
+
 var errBufferWriteAfterNext = errors.New("invalid bytes.Buffer.Write call after calling bytes.Buffer.Next")
 
 // fetch reads at least 1 byte from the underlying io.Reader.
@@ -193,7 +195,7 @@ func (d *decoderState) fetch() error {
 			// may overwrite the contents of the current buffer.
 			//
 			// The user is trying to use a bytes.Buffer as a pipe,
-			// but a bytes.Buffer is poor implementation of a pipe,
+			// but a bytes.Buffer is a poor implementation of a pipe,
 			// the purpose-built io.Pipe should be used instead.
 			return &ioError{action: "read", err: errBufferWriteAfterNext}
 		}
@@ -407,10 +409,11 @@ func (d *decoderState) checkDelim(delim byte, next Kind) error {
 }
 
 // SkipValue is semantically equivalent to calling [Decoder.ReadValue] and discarding
-// the result except that memory is not wasted trying to hold the entire result.
+// the result, except that memory is not wasted trying to hold the entire result.
 func (d *Decoder) SkipValue() error {
 	return d.s.SkipValue()
 }
+
 func (d *decoderState) SkipValue() error {
 	switch d.PeekKind() {
 	case '{', '[':
@@ -621,6 +624,7 @@ func (d *decoderState) ReadToken() (Token, error) {
 		if !d.Flags.Get(jsonflags.AllowDuplicateNames) {
 			d.Namespaces.push()
 		}
+		d.Flags.Clear(jsonflags.TagFlags) // tags only apply to current depth
 		pos += 1
 		d.prevStart, d.prevEnd = pos, pos
 		return BeginObject, nil
@@ -641,6 +645,7 @@ func (d *decoderState) ReadToken() (Token, error) {
 		if err = d.Tokens.pushArray(); err != nil {
 			return Token{}, wrapSyntacticError(d, err, pos, +1)
 		}
+		d.Flags.Clear(jsonflags.TagFlags) // tags only apply to current depth
 		pos += 1
 		d.prevStart, d.prevEnd = pos, pos
 		return BeginArray, nil
@@ -1127,24 +1132,54 @@ func (d *decoderState) consumeArray(flags *jsonwire.ValueFlags, pos, depth int)
 // InputOffset returns the current input byte offset. It gives the location
 // of the next byte immediately after the most recently returned token or value.
 // The number of bytes actually read from the underlying [io.Reader] may be more
-// than this offset due to internal buffering effects.
+// than this offset due to internal buffering.
 func (d *Decoder) InputOffset() int64 {
 	return d.s.previousOffsetEnd()
 }
 
 // UnreadBuffer returns the data remaining in the unread buffer,
 // which may contain zero or more bytes.
+// This is the data already consumed from the input [io.Reader],
+// but not yet read by a [Decoder.ReadToken] or [Decoder.ReadValue] call.
+// It may contain bytes that do not form valid JSON, since it has not yet
+// been validated according to the JSON grammar.
+// The exact amount of buffered data is an implementation detail
+// of the Decoder and may change over time.
+//
+// It is the caller's responsibility to concatenate this buffer with
+// the remainder of the input Reader to obtain the full sequence
+// of bytes after the last read JSON token or value.
+//
 // The returned buffer must not be mutated while Decoder continues to be used.
 // The buffer contents are valid until the next Peek, Read, or Skip call.
 func (d *Decoder) UnreadBuffer() []byte {
 	return d.s.unreadBuffer()
 }
 
-// StackDepth returns the depth of the state machine for read JSON data.
+// StackDepth returns the depth of the state machine for JSON data
+// that has already been read.
 // Each level on the stack represents a nested JSON object or array.
-// It is incremented whenever an [BeginObject] or [BeginArray] token is encountered
+// It is incremented whenever a [BeginObject] or [BeginArray] token is encountered
 // and decremented whenever an [EndObject] or [EndArray] token is encountered.
-// The depth is zero-indexed, where zero represents the top-level JSON value.
+//
+// StackDepth returns 0 when not inside any object or array.
+// In particular, it returns 0 before any tokens have been read,
+// after any top-level value has been read, and between values
+// when decoding a stream of top-level values (e.g., NDJSON).
+// StackDepth returns 1 inside a top-level object or array,
+// 2 inside a nested object or array, and so on.
+//
+// For example, consider decoding the following JSON:
+//
+//	{"a": [1, 2], "b": {"c": 3}}
+//
+// While decoding, StackDepth would report the following:
+//
+//   - At the start, StackDepth reports 0.
+//   - After decoding the outer '{', StackDepth reports 1.
+//   - After decoding the inner '[', StackDepth reports 2.
+//   - After decoding the inner ']', StackDepth reports 1.
+//   - After decoding the outer '}', StackDepth reports 0.
 func (d *Decoder) StackDepth() int {
 	// NOTE: Keep in sync with Encoder.StackDepth.
 	return d.s.Tokens.Depth() - 1
@@ -1158,9 +1193,9 @@ func (d *Decoder) StackDepth() int {
 //   - [KindBeginObject] for a level representing a JSON object, and
 //   - [KindBeginArray] for a level representing a JSON array.
 //
-// It also reports the length of that JSON object or array.
+// It also reports the length of that JSON object or array decoded so far.
 // Each name and value in a JSON object is counted separately,
-// so the effective number of members would be half the length.
+// so the effective number of members is half the length.
 // A complete JSON object must have an even length.
 func (d *Decoder) StackIndex(i int) (Kind, int64) {
 	// NOTE: Keep in sync with Encoder.StackIndex.

package/bin/go/src/encoding/json/jsontext/doc.go

@@ -10,11 +10,6 @@
 // primitive data types such as booleans, strings, and numbers,
 // in addition to structured data types such as objects and arrays.
 //
-// This package (encoding/json/jsontext) is experimental,
-// and not subject to the Go 1 compatibility promise.
-// It only exists when building with the GOEXPERIMENT=jsonv2 environment variable set.
-// Most users should use [encoding/json].
-//
 // The [Encoder] and [Decoder] types are used to encode or decode
 // a stream of JSON tokens or values.
 //
@@ -39,7 +34,7 @@
 //
 //   - a JSON literal, string, or number
 //   - a JSON object (e.g., `{"name":"value"}`)
-//   - a JSON array (e.g., `[1,2,3,]`)
+//   - a JSON array (e.g., `[1,2,3]`)
 //
 // A JSON value is represented by the [Value] type in Go and is a []byte
 // containing the raw textual representation of the value. There is some overlap
@@ -48,18 +43,18 @@
 //
 // The [Encoder] and [Decoder] types contain methods to read or write the next
 // [Token] or [Value] in a sequence. They maintain a state machine to validate
-// whether the sequence of JSON tokens and/or values produces a valid JSON.
+// whether the sequence of JSON tokens and/or values produces valid JSON.
 // [Options] may be passed to the [NewEncoder] or [NewDecoder] constructors
-// to configure the syntactic behavior of encoding and decoding.
+// to configure the behavior of encoding and decoding.
 //
 // # Terminology
 //
 // The terms "encode" and "decode" are used for syntactic functionality
 // that is concerned with processing JSON based on its grammar, and
 // the terms "marshal" and "unmarshal" are used for semantic functionality
-// that determines the meaning of JSON values as Go values and vice-versa.
-// This package (i.e., [jsontext]) deals with JSON at a syntactic layer,
-// while [encoding/json/v2] deals with JSON at a semantic layer.
+// that determines the meaning of JSON values as Go values and vice versa.
+// This package deals with JSON syntax,
+// while [encoding/json/v2] deals with JSON semantics.
 // The goal is to provide a clear distinction between functionality that
 // is purely concerned with encoding versus that of marshaling.
 // For example, one can directly encode a stream of JSON tokens without

package/bin/go/src/encoding/json/jsontext/encode.go

@@ -16,7 +16,7 @@ import (
 	"encoding/json/internal/jsonwire"
 )
 
-// Encoder is a streaming encoder from raw JSON tokens and values.
+// Encoder is a streaming encoder to raw JSON tokens and values.
 // It is used to write a stream of top-level JSON values,
 // each terminated with a newline character.
 //
@@ -41,7 +41,7 @@ import (
 //	e.WriteValue(Value(`{"k":"v"}`)) // {"k":"v"}
 //	e.WriteToken(EndObject)          // }
 //
-// The above is one of many possible sequence of calls and
+// The above is one of many possible sequences of calls and
 // may not represent the most sensible method to call for any given token/value.
 // For example, it is probably more common to call [Encoder.WriteToken] with a string
 // for object names.
@@ -50,7 +50,7 @@ type Encoder struct {
 }
 
 // encoderState is the low-level state of Encoder.
-// It has exported fields and method for use by the "json" package.
+// It has exported fields and methods for use by the "json" package.
 type encoderState struct {
 	state
 	encodeBuffer
@@ -96,7 +96,7 @@ func NewEncoder(w io.Writer, opts ...Options) *Encoder {
 
 // Reset resets an encoder such that it is writing afresh to w and
 // configured with the provided options. Reset must not be called on
-// a Encoder passed to the [encoding/json/v2.MarshalerTo.MarshalJSONTo] method
+// an Encoder passed to the [encoding/json/v2.MarshalerTo.MarshalJSONTo] method
 // or the [encoding/json/v2.MarshalToFunc] function.
 func (e *Encoder) Reset(w io.Writer, opts ...Options) {
 	switch {
@@ -124,21 +124,12 @@ func (e *encoderState) reset(b []byte, w io.Writer, opts ...Options) {
 	opts2 := jsonopts.Struct{} // avoid mutating e.Struct in case it is part of opts
 	opts2.Join(opts...)
 	e.Struct = opts2
-	if e.Flags.Get(jsonflags.Multiline) {
-		if !e.Flags.Has(jsonflags.SpaceAfterColon) {
-			e.Flags.Set(jsonflags.SpaceAfterColon | 1)
-		}
-		if !e.Flags.Has(jsonflags.SpaceAfterComma) {
-			e.Flags.Set(jsonflags.SpaceAfterComma | 0)
-		}
-		if !e.Flags.Has(jsonflags.Indent) {
-			e.Flags.Set(jsonflags.Indent | 1)
-			e.Indent = "\t"
-		}
+	if e.Struct.Flags.Get(jsonflags.Multiline) {
+		e.Struct.InitializeMultiline()
 	}
 }
 
-// Options returns the options used to construct the decoder and
+// Options returns the options used to construct the encoder and
 // may additionally contain semantic options passed to a
 // [encoding/json/v2.MarshalEncode] call.
 //
@@ -150,6 +141,8 @@ func (e *Encoder) Options() Options {
 	return &e.s.Struct
 }
 
+func (e *encoderState) options() *jsonopts.Struct { return &e.Struct }
+
 // NeedFlush determines whether to flush at this point.
 func (e *encoderState) NeedFlush() bool {
 	// NOTE: This function is carefully written to be inlinable.
@@ -178,7 +171,7 @@ func (e *encoderState) Flush() error {
 
 	// Specialize bytes.Buffer for better performance.
 	if bb, ok := e.wr.(*bytes.Buffer); ok {
-		// If e.buf already aliases the internal buffer of bb,
+		// If e.Buf already aliases the internal buffer of bb,
 		// then the Write call simply increments the internal offset,
 		// otherwise Write operates as expected.
 		// See https://go.dev/issue/42986.
@@ -213,7 +206,7 @@ func (e *encoderState) Flush() error {
 	e.Buf = e.Buf[:0]
 
 	// Check whether to grow the buffer.
-	// Note that cap(e.buf) may already exceed maxBufferSize since
+	// Note that cap(e.Buf) may already exceed maxBufferSize since
 	// an append elsewhere already grew it to store a large token.
 	const maxBufferSize = 4 << 10
 	const growthSizeFactor = 2 // higher value is faster
@@ -229,7 +222,7 @@ func (e *encoderState) Flush() error {
 
 	return nil
 }
-func (d *encodeBuffer) offsetAt(pos int) int64   { return d.baseOffset + int64(pos) }
+func (e *encodeBuffer) offsetAt(pos int) int64   { return e.baseOffset + int64(pos) }
 func (e *encodeBuffer) previousOffsetEnd() int64 { return e.baseOffset + int64(len(e.Buf)) }
 func (e *encodeBuffer) unflushedBuffer() []byte  { return e.Buf }
 
@@ -344,9 +337,10 @@ func (e *encoderState) UnwriteOnlyObjectMemberName() string {
 // For example, it is an error to provide a number when the encoder
 // is expecting an object name (which is always a string), or
 // to provide an end object delimiter when the encoder is finishing an array.
-// If the provided token is invalid, then it reports a [SyntacticError] and
+// If the provided token is invalid, then WriteToken reports a [SyntacticError] and
 // the internal state remains unchanged. The offset reported
-// in [SyntacticError] will be relative to the [Encoder.OutputOffset].
+// in [SyntacticError] will be the [Encoder.OutputOffset] plus any delimiter
+// or whitespace characters that would have preceded the provided token.
 func (e *Encoder) WriteToken(t Token) error {
 	return e.s.WriteToken(t)
 }
@@ -405,6 +399,7 @@ func (e *encoderState) WriteToken(t Token) error {
 		if !e.Flags.Get(jsonflags.AllowDuplicateNames) {
 			e.Namespaces.push()
 		}
+		e.Flags.Clear(jsonflags.TagFlags) // tags only apply to current depth
 	case '}':
 		b = append(b, '}')
 		if err = e.Tokens.popObject(); err != nil {
@@ -417,6 +412,7 @@ func (e *encoderState) WriteToken(t Token) error {
 	case '[':
 		b = append(b, '[')
 		err = e.Tokens.pushArray()
+		e.Flags.Clear(jsonflags.TagFlags) // tags only apply to current depth
 	case ']':
 		b = append(b, ']')
 		err = e.Tokens.popArray()
@@ -471,7 +467,7 @@ func (e *encoderState) AppendRaw(k Kind, safeASCII bool, appendFn func([]byte) (
 		if !isVerbatim {
 			var err error
 			b2 := append(e.availBuffer, b[pos+len(`"`):len(b)-len(`"`)]...)
-			b, err = jsonwire.AppendQuote(b[:pos], string(b2), &e.Flags)
+			b, err = jsonwire.AppendQuote(b[:pos], b2, &e.Flags)
 			e.availBuffer = b2[:0]
 			if err != nil {
 				return wrapSyntacticError(e, err, pos, +1)
@@ -482,7 +478,7 @@ func (e *encoderState) AppendRaw(k Kind, safeASCII bool, appendFn func([]byte) (
 		if e.Tokens.Last.NeedObjectName() {
 			if !e.Flags.Get(jsonflags.AllowDuplicateNames) {
 				if !e.Tokens.Last.isValidNamespace() {
-					return wrapSyntacticError(e, err, pos, +1)
+					return wrapSyntacticError(e, errInvalidNamespace, pos, +1)
 				}
 				if e.Tokens.Last.isActiveNamespace() && !e.Namespaces.Last().insertQuoted(b[pos:], isVerbatim) {
 					err = wrapWithObjectName(ErrDuplicateName, b[pos:])
@@ -522,9 +518,9 @@ func (e *encoderState) AppendRaw(k Kind, safeASCII bool, appendFn func([]byte) (
 //
 // The provided value kind must be consistent with the JSON grammar
 // (see examples on [Encoder.WriteToken]). If the provided value is invalid,
-// then it reports a [SyntacticError] and the internal state remains unchanged.
-// The offset reported in [SyntacticError] will be relative to the
-// [Encoder.OutputOffset] plus the offset into v of any encountered syntax error.
+// then WriteValue reports a [SyntacticError] and the internal state remains unchanged.
+// The offset reported in [SyntacticError] will be the [Encoder.OutputOffset]
+// plus the offset into v of any encountered syntax error.
 func (e *Encoder) WriteValue(v Value) error {
 	return e.s.WriteValue(v)
 }
@@ -541,7 +537,7 @@ func (e *encoderState) WriteValue(v Value) error {
 	}
 	pos := len(b) // offset before the value
 
-	// Append the value the output.
+	// Append the value to the output.
 	var n int
 	n += jsonwire.ConsumeWhitespace(v[n:])
 	b, m, err := e.reformatValue(b, v[n:], e.Tokens.Depth())
@@ -715,7 +711,7 @@ func (e *encoderState) reformatValue(dst []byte, src Value, depth int) ([]byte,
 }
 
 // reformatObject parses a JSON object from the start of src and
-// appends it to the end of src, reformatting whitespace and strings as needed.
+// appends it to the end of dst, reformatting whitespace and strings as needed.
 // It returns the extended dst buffer and the number of consumed input bytes.
 func (e *encoderState) reformatObject(dst []byte, src Value, depth int) ([]byte, int, error) {
 	// Append object begin.
@@ -900,7 +896,7 @@ func (e *encoderState) reformatArray(dst []byte, src Value, depth int) ([]byte,
 // OutputOffset returns the current output byte offset. It gives the location
 // of the next byte immediately after the most recently written token or value.
 // The number of bytes actually written to the underlying [io.Writer] may be less
-// than this offset due to internal buffering effects.
+// than this offset due to internal buffering.
 func (e *Encoder) OutputOffset() int64 {
 	return e.s.previousOffsetEnd()
 }
@@ -911,19 +907,21 @@ func (e *Encoder) OutputOffset() int64 {
 //
 // Example usage:
 //
-//	b := d.AvailableBuffer()
+//	b := e.AvailableBuffer()
 //	b = append(b, '"')
 //	b = appendString(b, v) // append the string formatting of v
 //	b = append(b, '"')
-//	... := d.WriteValue(b)
+//	... := e.WriteValue(b)
 //
-// It is the user's responsibility to ensure that the value is valid JSON.
+// Note that WriteValue expects a valid JSON value. Constructing a value in a
+// raw []byte requires more care than using constructor functions like
+// [String], which always return valid [Token]s or [Value]s.
 func (e *Encoder) AvailableBuffer() []byte {
-	// NOTE: We don't return e.buf[len(e.buf):cap(e.buf)] since WriteValue would
+	// NOTE: We don't return e.Buf[len(e.Buf):cap(e.Buf)] since WriteValue would
 	// need to take special care to avoid mangling the data while reformatting.
-	// WriteValue can't easily identify whether the input Value aliases e.buf
+	// WriteValue can't easily identify whether the input Value aliases e.Buf
 	// without using unsafe.Pointer. Thus, we just return a different buffer.
-	// Should this ever alias e.buf, we need to consider how it operates with
+	// Should this ever alias e.Buf, we need to consider how it operates with
 	// the specialized performance optimization for bytes.Buffer.
 	n := 1 << bits.Len(uint(e.s.maxValue|63)) // fast approximation for max length
 	if cap(e.s.availBuffer) < n {
@@ -934,9 +932,27 @@ func (e *Encoder) AvailableBuffer() []byte {
 
 // StackDepth returns the depth of the state machine for written JSON data.
 // Each level on the stack represents a nested JSON object or array.
-// It is incremented whenever an [BeginObject] or [BeginArray] token is encountered
+// It is incremented whenever a [BeginObject] or [BeginArray] token is encountered
 // and decremented whenever an [EndObject] or [EndArray] token is encountered.
-// The depth is zero-indexed, where zero represents the top-level JSON value.
+//
+// StackDepth returns 0 when not inside any object or array.
+// In particular, it returns 0 before any tokens have been written,
+// after any top-level value has been written, and between values
+// when encoding a stream of top-level values (e.g., NDJSON).
+// StackDepth returns 1 inside a top-level object or array,
+// 2 inside a nested object or array, and so on.
+//
+// For example, consider encoding the following JSON:
+//
+//	{"a": [1, 2], "b": {"c": 3}}
+//
+// While encoding, StackDepth would report the following:
+//
+//   - At the start, StackDepth reports 0.
+//   - After encoding the outer '{', StackDepth reports 1.
+//   - After encoding the inner '[', StackDepth reports 2.
+//   - After encoding the inner ']', StackDepth reports 1.
+//   - After encoding the outer '}', StackDepth reports 0.
 func (e *Encoder) StackDepth() int {
 	// NOTE: Keep in sync with Decoder.StackDepth.
 	return e.s.Tokens.Depth() - 1
@@ -950,9 +966,9 @@ func (e *Encoder) StackDepth() int {
 //   - [KindBeginObject] for a level representing a JSON object, and
 //   - [KindBeginArray] for a level representing a JSON array.
 //
-// It also reports the length of that JSON object or array.
+// It also reports the length of that JSON object or array encoded so far.
 // Each name and value in a JSON object is counted separately,
-// so the effective number of members would be half the length.
+// so the effective number of members is half the length.
 // A complete JSON object must have an even length.
 func (e *Encoder) StackIndex(i int) (Kind, int64) {
 	// NOTE: Keep in sync with Decoder.StackIndex.

package/bin/go/src/encoding/json/jsontext/errors.go

@@ -11,6 +11,8 @@ import (
 	"io"
 	"strconv"
 
+	"encoding/json/internal/jsonflags"
+	"encoding/json/internal/jsonopts"
 	"encoding/json/internal/jsonwire"
 )
 
@@ -28,7 +30,20 @@ func (e *ioError) Unwrap() error {
 	return e.err
 }
 
-// SyntacticError is a description of a syntactic error that occurred when
+type numError struct {
+	accessor string // either "Int", "Uint", or "Float"
+	value    string // e.g., "1e1000"
+	err      error  // either [strconv.ErrSyntax] or [strconv.ErrRange]
+}
+
+func (e *numError) Error() string {
+	return "jsontext.Token(" + e.value + ")." + e.accessor + " error: " + e.err.Error()
+}
+func (e *numError) Unwrap() error {
+	return e.err
+}
+
+// SyntacticError is a description of an error that occurred when
 // encoding or decoding JSON according to the grammar.
 //
 // The contents of this error as produced by this package may change over time.
@@ -36,7 +51,7 @@ type SyntacticError struct {
 	requireKeyedLiterals
 	nonComparable
 
-	// ByteOffset indicates that an error occurred after this byte offset.
+	// ByteOffset indicates that an error occurred at or after this byte offset.
 	ByteOffset int64
 	// JSONPointer indicates that an error occurred within this JSON value
 	// as indicated using the JSON Pointer notation (see RFC 6901).
@@ -53,10 +68,11 @@ type SyntacticError struct {
 // It takes a relative offset pos that can be resolved into
 // an absolute offset using state.offsetAt.
 //
-// It takes a where that specify how the JSON pointer is derived.
+// It takes a where that specifies how the JSON pointer is derived.
 // If the underlying error is a [pointerSuffixError],
 // then the suffix is appended to the derived pointer.
 func wrapSyntacticError(state interface {
+	options() *jsonopts.Struct
 	offsetAt(pos int) int64
 	AppendStackPointer(b []byte, where int) []byte
 }, err error, pos, where int) error {
@@ -83,6 +99,21 @@ func wrapSyntacticError(state interface {
 		}
 		err = jsonwire.NewInvalidCharacterError(d.buf[pos:], where)
 	}
+	if state.options().Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) && err != io.ErrUnexpectedEOF {
+		// The v1 error offset more consistently reported
+		// the number of bytes read that lead to the error.
+		// This implies that the offset is after the invalid text.
+		if werr, ok := err.(*jsonwire.InvalidTextError); ok && werr != nil {
+			offset += int64(len(werr.What))
+		} else {
+			// This implies a structural error (e.g., parsing a JSON number
+			// when the grammar is expecting a JSON string for the object name).
+			// In such a case, simply increment by one, since the first byte
+			// is usually sufficient to indicate that the incoming token
+			// cannot possibly be correct.
+			offset++
+		}
+	}
 	return &SyntacticError{ByteOffset: offset, JSONPointer: Pointer(ptr), Err: err}
 }
 

package/bin/go/src/encoding/json/jsontext/export.go

@@ -12,6 +12,20 @@ import (
 	"encoding/json/internal"
 )
 
+// TODO(https://go.dev/issue/73435): Remove the Internal symbol.
+//
+// The Go language lacks a 3rd category of visibility where
+// certain symbols can only be referenced from within the same module.
+// One solution to this is to put the entirety of a package with
+// both public and module-only symbols exposed as an internal package.
+// A separate, public package can re-export all of the public symbols
+// via type aliases and thus ensuring module-only symbols cannot be
+// referenced by the end-user. While this works, it unfortunately
+// leads to a poor user experience since the Go pkgsite is unable to
+// forward the documentation for symbols like methods and fields.
+// We need to improve the pkgsite experience before we can delete
+// the Internal symbol.
+
 // Internal is for internal use only.
 // This is exempt from the Go compatibility agreement.
 var Internal exporter