Update dependencies

vendor/github.com/go-json-experiment/json/jsontext/encode.go

@@ -25,19 +25,19 @@ import (
 //
 // can be composed with the following calls (ignoring errors for brevity):
 //
-//	e.WriteToken(ObjectStart)        // {
+//	e.WriteToken(BeginObject)        // {
 //	e.WriteToken(String("name"))     // "name"
 //	e.WriteToken(String("value"))    // "value"
 //	e.WriteValue(Value(`"array"`))   // "array"
-//	e.WriteToken(ArrayStart)         // [
+//	e.WriteToken(BeginArray)         // [
 //	e.WriteToken(Null)               // null
 //	e.WriteToken(False)              // false
 //	e.WriteValue(Value("true"))      // true
 //	e.WriteToken(Float(3.14159))     // 3.14159
-//	e.WriteToken(ArrayEnd)           // ]
+//	e.WriteToken(EndArray)           // ]
 //	e.WriteValue(Value(`"object"`))  // "object"
 //	e.WriteValue(Value(`{"k":"v"}`)) // {"k":"v"}
-//	e.WriteToken(ObjectEnd)          // }
+//	e.WriteToken(EndObject)          // }
 //
 // The above is one of many possible sequence of calls and
 // may not represent the most sensible method to call for any given token/value.
@@ -94,8 +94,8 @@ 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.MarshalerV2.MarshalJSONV2] method
-// or the [encoding/json/v2.MarshalFuncV2] function.
+// a 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 {
 	case e == nil:
@@ -103,7 +103,7 @@ func (e *Encoder) Reset(w io.Writer, opts ...Options) {
 	case w == nil:
 		panic("jsontext: invalid nil io.Writer")
 	case e.s.Flags.Get(jsonflags.WithinArshalCall):
-		panic("jsontext: cannot reset Encoder passed to json.MarshalerV2")
+		panic("jsontext: cannot reset Encoder passed to json.MarshalerTo")
 	}
 	e.s.reset(nil, w, opts...)
 }
@@ -114,13 +114,35 @@ func (e *encoderState) reset(b []byte, w io.Writer, opts ...Options) {
 	if bb, ok := w.(*bytes.Buffer); ok && bb != nil {
 		e.Buf = bb.Bytes()[bb.Len():] // alias the unused buffer of bb
 	}
-	e.Struct = jsonopts.Struct{}
-	e.Struct.Join(opts...)
-	if e.Flags.Get(jsonflags.Expand) && !e.Flags.Has(jsonflags.Indent) {
-		e.Indent = "\t"
+	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"
+		}
 	}
 }
 
+// Options returns the options used to construct the decoder and
+// may additionally contain semantic options passed to a
+// [encoding/json/v2.MarshalEncode] call.
+//
+// If operating within
+// a [encoding/json/v2.MarshalerTo.MarshalJSONTo] method call or
+// a [encoding/json/v2.MarshalToFunc] function call,
+// then the returned options are only valid within the call.
+func (e *Encoder) Options() Options {
+	return &e.s.Struct
+}
+
 // NeedFlush determines whether to flush at this point.
 func (e *encoderState) NeedFlush() bool {
 	// NOTE: This function is carefully written to be inlinable.
@@ -200,17 +222,7 @@ func (e *encoderState) Flush() error {
 
 	return nil
 }
-
-// injectSyntacticErrorWithPosition wraps a SyntacticError with the position,
-// otherwise it returns the error as is.
-// It takes a position relative to the start of the start of e.buf.
-func (e *encodeBuffer) injectSyntacticErrorWithPosition(err error, pos int) error {
-	if serr, ok := err.(*SyntacticError); ok {
-		return serr.withOffset(e.baseOffset + int64(pos))
-	}
-	return err
-}
-
+func (d *encodeBuffer) offsetAt(pos int) int64   { return d.baseOffset + int64(pos) }
 func (e *encodeBuffer) previousOffsetEnd() int64 { return e.baseOffset + int64(len(e.Buf)) }
 func (e *encodeBuffer) unflushedBuffer() []byte  { return e.Buf }
 
@@ -219,7 +231,7 @@ func (e *encodeBuffer) unflushedBuffer() []byte  { return e.Buf }
 func (e *encoderState) avoidFlush() bool {
 	switch {
 	case e.Tokens.Last.Length() == 0:
-		// Never flush after ObjectStart or ArrayStart since we don't know yet
+		// Never flush after BeginObject or BeginArray since we don't know yet
 		// if the object or array will end up being empty.
 		return true
 	case e.Tokens.Last.needObjectValue():
@@ -286,11 +298,11 @@ func (e *encoderState) UnwriteEmptyObjectMember(prevName *string) bool {
 		if e.Tokens.Last.isActiveNamespace() {
 			e.Namespaces.Last().removeLast()
 		}
-		e.Names.clearLast()
-		if prevName != nil {
-			e.Names.copyQuotedBuffer(e.Buf) // required by objectNameStack.replaceLastUnquotedName
-			e.Names.replaceLastUnquotedName(*prevName)
-		}
+	}
+	e.Names.clearLast()
+	if prevName != nil {
+		e.Names.copyQuotedBuffer(e.Buf) // required by objectNameStack.replaceLastUnquotedName
+		e.Names.replaceLastUnquotedName(*prevName)
 	}
 	return true
 }
@@ -314,8 +326,8 @@ func (e *encoderState) UnwriteOnlyObjectMemberName() string {
 		if e.Tokens.Last.isActiveNamespace() {
 			e.Namespaces.Last().removeLast()
 		}
-		e.Names.clearLast()
 	}
+	e.Names.clearLast()
 	return name
 }
 
@@ -337,7 +349,7 @@ func (e *encoderState) WriteToken(t Token) error {
 
 	// Append any delimiters or optional whitespace.
 	b = e.Tokens.MayAppendDelim(b, k)
-	if e.Flags.Get(jsonflags.Expand) {
+	if e.Flags.Get(jsonflags.AnyWhitespace) {
 		b = e.appendWhitespace(b, k)
 	}
 	pos := len(b) // offset before the token
@@ -358,20 +370,22 @@ func (e *encoderState) WriteToken(t Token) error {
 		if b, err = t.appendString(b, &e.Flags); err != nil {
 			break
 		}
-		if !e.Flags.Get(jsonflags.AllowDuplicateNames) && e.Tokens.Last.NeedObjectName() {
-			if !e.Tokens.Last.isValidNamespace() {
-				err = errInvalidNamespace
-				break
-			}
-			if e.Tokens.Last.isActiveNamespace() && !e.Namespaces.Last().insertQuoted(b[pos:], false) {
-				err = newDuplicateNameError(b[pos:])
-				break
+		if e.Tokens.Last.NeedObjectName() {
+			if !e.Flags.Get(jsonflags.AllowDuplicateNames) {
+				if !e.Tokens.Last.isValidNamespace() {
+					err = errInvalidNamespace
+					break
+				}
+				if e.Tokens.Last.isActiveNamespace() && !e.Namespaces.Last().insertQuoted(b[pos:], false) {
+					err = wrapWithObjectName(ErrDuplicateName, b[pos:])
+					break
+				}
 			}
 			e.Names.ReplaceLastQuotedOffset(pos) // only replace if insertQuoted succeeds
 		}
 		err = e.Tokens.appendString()
 	case '0':
-		if b, err = t.appendNumber(b, e.Flags.Get(jsonflags.CanonicalizeNumbers)); err != nil {
+		if b, err = t.appendNumber(b, &e.Flags); err != nil {
 			break
 		}
 		err = e.Tokens.appendNumber()
@@ -380,8 +394,8 @@ func (e *encoderState) WriteToken(t Token) error {
 		if err = e.Tokens.pushObject(); err != nil {
 			break
 		}
+		e.Names.push()
 		if !e.Flags.Get(jsonflags.AllowDuplicateNames) {
-			e.Names.push()
 			e.Namespaces.push()
 		}
 	case '}':
@@ -389,8 +403,8 @@ func (e *encoderState) WriteToken(t Token) error {
 		if err = e.Tokens.popObject(); err != nil {
 			break
 		}
+		e.Names.pop()
 		if !e.Flags.Get(jsonflags.AllowDuplicateNames) {
-			e.Names.pop()
 			e.Namespaces.pop()
 		}
 	case '[':
@@ -400,10 +414,10 @@ func (e *encoderState) WriteToken(t Token) error {
 		b = append(b, ']')
 		err = e.Tokens.popArray()
 	default:
-		err = &SyntacticError{str: "invalid json.Token"}
+		err = errInvalidToken
 	}
 	if err != nil {
-		return e.injectSyntacticErrorWithPosition(err, pos)
+		return wrapSyntacticError(e, err, pos, +1)
 	}
 
 	// Finish off the buffer and store it back into e.
@@ -428,7 +442,7 @@ func (e *encoderState) AppendRaw(k Kind, safeASCII bool, appendFn func([]byte) (
 
 	// Append any delimiters or optional whitespace.
 	b = e.Tokens.MayAppendDelim(b, k)
-	if e.Flags.Get(jsonflags.Expand) {
+	if e.Flags.Get(jsonflags.AnyWhitespace) {
 		b = e.appendWhitespace(b, k)
 	}
 	pos := len(b) // offset before the token
@@ -453,30 +467,32 @@ func (e *encoderState) AppendRaw(k Kind, safeASCII bool, appendFn func([]byte) (
 			b, err = jsonwire.AppendQuote(b[:pos], string(b2), &e.Flags)
 			e.unusedCache = b2[:0]
 			if err != nil {
-				return e.injectSyntacticErrorWithPosition(err, pos)
+				return wrapSyntacticError(e, err, pos, +1)
 			}
 		}
 
 		// Update the state machine.
-		if !e.Flags.Get(jsonflags.AllowDuplicateNames) && e.Tokens.Last.NeedObjectName() {
-			if !e.Tokens.Last.isValidNamespace() {
-				return errInvalidNamespace
-			}
-			if e.Tokens.Last.isActiveNamespace() && !e.Namespaces.Last().insertQuoted(b[pos:], isVerbatim) {
-				err := newDuplicateNameError(b[pos:])
-				return e.injectSyntacticErrorWithPosition(err, pos)
+		if e.Tokens.Last.NeedObjectName() {
+			if !e.Flags.Get(jsonflags.AllowDuplicateNames) {
+				if !e.Tokens.Last.isValidNamespace() {
+					return wrapSyntacticError(e, err, pos, +1)
+				}
+				if e.Tokens.Last.isActiveNamespace() && !e.Namespaces.Last().insertQuoted(b[pos:], isVerbatim) {
+					err = wrapWithObjectName(ErrDuplicateName, b[pos:])
+					return wrapSyntacticError(e, err, pos, +1)
+				}
 			}
 			e.Names.ReplaceLastQuotedOffset(pos) // only replace if insertQuoted succeeds
 		}
 		if err := e.Tokens.appendString(); err != nil {
-			return e.injectSyntacticErrorWithPosition(err, pos)
+			return wrapSyntacticError(e, err, pos, +1)
 		}
 	case '0':
 		if b, err = appendFn(b); err != nil {
 			return err
 		}
 		if err := e.Tokens.appendNumber(); err != nil {
-			return e.injectSyntacticErrorWithPosition(err, pos)
+			return wrapSyntacticError(e, err, pos, +1)
 		}
 	default:
 		panic("BUG: invalid kind")
@@ -513,7 +529,7 @@ func (e *encoderState) WriteValue(v Value) error {
 
 	// Append any delimiters or optional whitespace.
 	b = e.Tokens.MayAppendDelim(b, k)
-	if e.Flags.Get(jsonflags.Expand) {
+	if e.Flags.Get(jsonflags.AnyWhitespace) {
 		b = e.appendWhitespace(b, k)
 	}
 	pos := len(b) // offset before the value
@@ -523,13 +539,13 @@ func (e *encoderState) WriteValue(v Value) error {
 	n += jsonwire.ConsumeWhitespace(v[n:])
 	b, m, err := e.reformatValue(b, v[n:], e.Tokens.Depth())
 	if err != nil {
-		return e.injectSyntacticErrorWithPosition(err, pos+n+m)
+		return wrapSyntacticError(e, err, pos+n+m, +1)
 	}
 	n += m
 	n += jsonwire.ConsumeWhitespace(v[n:])
 	if len(v) > n {
-		err = newInvalidCharacterError(v[n:], "after top-level value")
-		return e.injectSyntacticErrorWithPosition(err, pos+n)
+		err = jsonwire.NewInvalidCharacterError(v[n:], "after top-level value")
+		return wrapSyntacticError(e, err, pos+n, 0)
 	}
 
 	// Append the kind to the state machine.
@@ -537,14 +553,16 @@ func (e *encoderState) WriteValue(v Value) error {
 	case 'n', 'f', 't':
 		err = e.Tokens.appendLiteral()
 	case '"':
-		if !e.Flags.Get(jsonflags.AllowDuplicateNames) && e.Tokens.Last.NeedObjectName() {
-			if !e.Tokens.Last.isValidNamespace() {
-				err = errInvalidNamespace
-				break
-			}
-			if e.Tokens.Last.isActiveNamespace() && !e.Namespaces.Last().insertQuoted(b[pos:], false) {
-				err = newDuplicateNameError(b[pos:])
-				break
+		if e.Tokens.Last.NeedObjectName() {
+			if !e.Flags.Get(jsonflags.AllowDuplicateNames) {
+				if !e.Tokens.Last.isValidNamespace() {
+					err = errInvalidNamespace
+					break
+				}
+				if e.Tokens.Last.isActiveNamespace() && !e.Namespaces.Last().insertQuoted(b[pos:], false) {
+					err = wrapWithObjectName(ErrDuplicateName, b[pos:])
+					break
+				}
 			}
 			e.Names.ReplaceLastQuotedOffset(pos) // only replace if insertQuoted succeeds
 		}
@@ -558,6 +576,9 @@ func (e *encoderState) WriteValue(v Value) error {
 		if err = e.Tokens.popObject(); err != nil {
 			panic("BUG: popObject should never fail immediately after pushObject: " + err.Error())
 		}
+		if e.Flags.Get(jsonflags.ReorderRawObjects) {
+			mustReorderObjects(b[pos:])
+		}
 	case '[':
 		if err = e.Tokens.pushArray(); err != nil {
 			break
@@ -565,9 +586,12 @@ func (e *encoderState) WriteValue(v Value) error {
 		if err = e.Tokens.popArray(); err != nil {
 			panic("BUG: popArray should never fail immediately after pushArray: " + err.Error())
 		}
+		if e.Flags.Get(jsonflags.ReorderRawObjects) {
+			mustReorderObjects(b[pos:])
+		}
 	}
 	if err != nil {
-		return e.injectSyntacticErrorWithPosition(err, pos)
+		return wrapSyntacticError(e, err, pos, +1)
 	}
 
 	// Finish off the buffer and store it back into e.
@@ -578,13 +602,47 @@ func (e *encoderState) WriteValue(v Value) error {
 	return nil
 }
 
+// CountNextDelimWhitespace counts the number of bytes of delimiter and
+// whitespace bytes assuming the upcoming token is a JSON value.
+// This method is used for error reporting at the semantic layer.
+func (e *encoderState) CountNextDelimWhitespace() (n int) {
+	const next = Kind('"') // arbitrary kind as next JSON value
+	delim := e.Tokens.needDelim(next)
+	if delim > 0 {
+		n += len(",") | len(":")
+	}
+	if delim == ':' {
+		if e.Flags.Get(jsonflags.SpaceAfterColon) {
+			n += len(" ")
+		}
+	} else {
+		if delim == ',' && e.Flags.Get(jsonflags.SpaceAfterComma) {
+			n += len(" ")
+		}
+		if e.Flags.Get(jsonflags.Multiline) {
+			if m := e.Tokens.NeedIndent(next); m > 0 {
+				n += len("\n") + len(e.IndentPrefix) + (m-1)*len(e.Indent)
+			}
+		}
+	}
+	return n
+}
+
 // appendWhitespace appends whitespace that immediately precedes the next token.
 func (e *encoderState) appendWhitespace(b []byte, next Kind) []byte {
-	if e.Tokens.needDelim(next) == ':' {
-		return append(b, ' ')
+	if delim := e.Tokens.needDelim(next); delim == ':' {
+		if e.Flags.Get(jsonflags.SpaceAfterColon) {
+			b = append(b, ' ')
+		}
 	} else {
-		return e.AppendIndent(b, e.Tokens.NeedIndent(next))
+		if delim == ',' && e.Flags.Get(jsonflags.SpaceAfterComma) {
+			b = append(b, ' ')
+		}
+		if e.Flags.Get(jsonflags.Multiline) {
+			b = e.AppendIndent(b, e.Tokens.NeedIndent(next))
+		}
 	}
+	return b
 }
 
 // AppendIndent appends the appropriate number of indentation characters
@@ -630,22 +688,22 @@ func (e *encoderState) reformatValue(dst []byte, src Value, depth int) ([]byte,
 		return append(dst, "true"...), len("true"), nil
 	case '"':
 		if n := jsonwire.ConsumeSimpleString(src); n > 0 {
-			dst, src = append(dst, src[:n]...), src[n:] // copy simple strings verbatim
+			dst = append(dst, src[:n]...) // copy simple strings verbatim
 			return dst, n, nil
 		}
 		return jsonwire.ReformatString(dst, src, &e.Flags)
 	case '0':
 		if n := jsonwire.ConsumeSimpleNumber(src); n > 0 && !e.Flags.Get(jsonflags.CanonicalizeNumbers) {
-			dst, src = append(dst, src[:n]...), src[n:] // copy simple numbers verbatim
+			dst = append(dst, src[:n]...) // copy simple numbers verbatim
 			return dst, n, nil
 		}
-		return jsonwire.ReformatNumber(dst, src, e.Flags.Get(jsonflags.CanonicalizeNumbers))
+		return jsonwire.ReformatNumber(dst, src, &e.Flags)
 	case '{':
 		return e.reformatObject(dst, src, depth)
 	case '[':
 		return e.reformatArray(dst, src, depth)
 	default:
-		return dst, 0, newInvalidCharacterError(src, "at start of value")
+		return dst, 0, jsonwire.NewInvalidCharacterError(src, "at start of value")
 	}
 }
 
@@ -683,7 +741,7 @@ func (e *encoderState) reformatObject(dst []byte, src Value, depth int) ([]byte,
 	depth++
 	for {
 		// Append optional newline and indentation.
-		if e.Flags.Get(jsonflags.Expand) {
+		if e.Flags.Get(jsonflags.Multiline) {
 			dst = e.AppendIndent(dst, depth)
 		}
 
@@ -693,7 +751,8 @@ func (e *encoderState) reformatObject(dst []byte, src Value, depth int) ([]byte,
 			return dst, n, io.ErrUnexpectedEOF
 		}
 		m := jsonwire.ConsumeSimpleString(src[n:])
-		if m > 0 {
+		isVerbatim := m > 0
+		if isVerbatim {
 			dst = append(dst, src[n:n+m]...)
 		} else {
 			dst, m, err = jsonwire.ReformatString(dst, src[n:], &e.Flags)
@@ -701,34 +760,35 @@ func (e *encoderState) reformatObject(dst []byte, src Value, depth int) ([]byte,
 				return dst, n + m, err
 			}
 		}
-		// TODO: Specify whether the name is verbatim or not.
-		if !e.Flags.Get(jsonflags.AllowDuplicateNames) && !names.insertQuoted(src[n:n+m], false) {
-			return dst, n, newDuplicateNameError(src[n : n+m])
+		quotedName := src[n : n+m]
+		if !e.Flags.Get(jsonflags.AllowDuplicateNames) && !names.insertQuoted(quotedName, isVerbatim) {
+			return dst, n, wrapWithObjectName(ErrDuplicateName, quotedName)
 		}
 		n += m
 
 		// Append colon.
 		n += jsonwire.ConsumeWhitespace(src[n:])
 		if uint(len(src)) <= uint(n) {
-			return dst, n, io.ErrUnexpectedEOF
+			return dst, n, wrapWithObjectName(io.ErrUnexpectedEOF, quotedName)
 		}
 		if src[n] != ':' {
-			return dst, n, newInvalidCharacterError(src[n:], "after object name (expecting ':')")
+			err = jsonwire.NewInvalidCharacterError(src[n:], "after object name (expecting ':')")
+			return dst, n, wrapWithObjectName(err, quotedName)
 		}
 		dst = append(dst, ':')
 		n += len(":")
-		if e.Flags.Get(jsonflags.Expand) {
+		if e.Flags.Get(jsonflags.SpaceAfterColon) {
 			dst = append(dst, ' ')
 		}
 
 		// Append object value.
 		n += jsonwire.ConsumeWhitespace(src[n:])
 		if uint(len(src)) <= uint(n) {
-			return dst, n, io.ErrUnexpectedEOF
+			return dst, n, wrapWithObjectName(io.ErrUnexpectedEOF, quotedName)
 		}
 		dst, m, err = e.reformatValue(dst, src[n:], depth)
 		if err != nil {
-			return dst, n + m, err
+			return dst, n + m, wrapWithObjectName(err, quotedName)
 		}
 		n += m
 
@@ -740,17 +800,20 @@ func (e *encoderState) reformatObject(dst []byte, src Value, depth int) ([]byte,
 		switch src[n] {
 		case ',':
 			dst = append(dst, ',')
+			if e.Flags.Get(jsonflags.SpaceAfterComma) {
+				dst = append(dst, ' ')
+			}
 			n += len(",")
 			continue
 		case '}':
-			if e.Flags.Get(jsonflags.Expand) {
+			if e.Flags.Get(jsonflags.Multiline) {
 				dst = e.AppendIndent(dst, depth-1)
 			}
 			dst = append(dst, '}')
 			n += len("}")
 			return dst, n, nil
 		default:
-			return dst, n, newInvalidCharacterError(src[n:], "after object value (expecting ',' or '}')")
+			return dst, n, jsonwire.NewInvalidCharacterError(src[n:], "after object value (expecting ',' or '}')")
 		}
 	}
 }
@@ -779,11 +842,12 @@ func (e *encoderState) reformatArray(dst []byte, src Value, depth int) ([]byte,
 		return dst, n, nil
 	}
 
+	var idx int64
 	var err error
 	depth++
 	for {
 		// Append optional newline and indentation.
-		if e.Flags.Get(jsonflags.Expand) {
+		if e.Flags.Get(jsonflags.Multiline) {
 			dst = e.AppendIndent(dst, depth)
 		}
 
@@ -795,7 +859,7 @@ func (e *encoderState) reformatArray(dst []byte, src Value, depth int) ([]byte,
 		var m int
 		dst, m, err = e.reformatValue(dst, src[n:], depth)
 		if err != nil {
-			return dst, n + m, err
+			return dst, n + m, wrapWithArrayIndex(err, idx)
 		}
 		n += m
 
@@ -807,17 +871,21 @@ func (e *encoderState) reformatArray(dst []byte, src Value, depth int) ([]byte,
 		switch src[n] {
 		case ',':
 			dst = append(dst, ',')
+			if e.Flags.Get(jsonflags.SpaceAfterComma) {
+				dst = append(dst, ' ')
+			}
 			n += len(",")
+			idx++
 			continue
 		case ']':
-			if e.Flags.Get(jsonflags.Expand) {
+			if e.Flags.Get(jsonflags.Multiline) {
 				dst = e.AppendIndent(dst, depth-1)
 			}
 			dst = append(dst, ']')
 			n += len("]")
 			return dst, n, nil
 		default:
-			return dst, n, newInvalidCharacterError(src[n:], "after array value (expecting ',' or ']')")
+			return dst, n, jsonwire.NewInvalidCharacterError(src[n:], "after array value (expecting ',' or ']')")
 		}
 	}
 }
@@ -859,8 +927,8 @@ func (e *Encoder) UnusedBuffer() []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 [ObjectStart] or [ArrayStart] token is encountered
-// and decremented whenever an [ObjectEnd] or [ArrayEnd] token is encountered.
+// It is incremented whenever an [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.
 func (e *Encoder) StackDepth() int {
 	// NOTE: Keep in sync with Decoder.StackDepth.
@@ -879,7 +947,7 @@ func (e *Encoder) StackDepth() int {
 // Each name and value in a JSON object is counted separately,
 // so the effective number of members would be half the length.
 // A complete JSON object must have an even length.
-func (e *Encoder) StackIndex(i int) (Kind, int) {
+func (e *Encoder) StackIndex(i int) (Kind, int64) {
 	// NOTE: Keep in sync with Decoder.StackIndex.
 	switch s := e.s.Tokens.index(i); {
 	case i > 0 && s.isObject():
@@ -892,9 +960,11 @@ func (e *Encoder) StackIndex(i int) (Kind, int) {
 }
 
 // StackPointer returns a JSON Pointer (RFC 6901) to the most recently written value.
-// Object names are only present if [AllowDuplicateNames] is false, otherwise
-// object members are represented using their index within the object.
-func (e *Encoder) StackPointer() string {
-	e.s.Names.copyQuotedBuffer(e.s.Buf)
-	return string(e.s.appendStackPointer(nil))
+func (e *Encoder) StackPointer() Pointer {
+	return Pointer(e.s.AppendStackPointer(nil, -1))
+}
+
+func (e *encoderState) AppendStackPointer(b []byte, where int) []byte {
+	e.Names.copyQuotedBuffer(e.Buf)
+	return e.state.appendStackPointer(b, where)
 }