feat: honour TextMarshaler and TextUnmarshaler by default

Assisted-by: DeepSeek V4.1 Flash

docs/API.md

@@ -147,6 +147,9 @@ zero date for a local time). Every kind may omit the seconds as of TOML 1.1
 (`07:32`, `1979-05-27T07:32`); such a value carries a zero second, and the
 canonical rendering writes full seconds. There is no implicit conversion
 between the offset and local kinds; assigning one to the other is an error.
+The four types take a bare timestamp and never a quoted string, so a document
+that writes a date-time with quotes does not decode into them, and neither
+`encoding.TextUnmarshaler` nor the embedded `time.Time` changes that.
 
 ### Arrays of tables
 
@@ -177,6 +180,38 @@ automatically, and a nil pointer destination is allocated first. An error
 returned from `UnmarshalTOML` halts the decode and propagates wrapped with the
 key path, for example `addr: unmarshal: not a string`.
 
+### Custom decoding: `encoding.TextUnmarshaler`
+
+A destination type that implements `encoding.TextUnmarshaler` receives a TOML
+string as its text content, the rule `encoding/json` follows:
+
+```go
+func (ip *IP) UnmarshalText(text []byte) error
+```
+
+The decoder looks for the method on the destination and on its address, so a
+pointer-receiver `UnmarshalText` is invoked on an addressable struct field, and
+the elements of a slice destination are reached the same way. The text path
+applies to TOML strings only: every other value kind keeps its own rule, so
+`r = 1` does not reach a receiver that expects text. An error from
+`UnmarshalText` halts the decode and propagates with the key path and the
+prefix `unmarshal text:`, for example `addr: unmarshal text: not an address`.
+
+[`UnmarshalTOML`](#custom-decoding-unmarshaler) wins over `UnmarshalText` when
+a type implements both, and the four [date-time
+types](#date-time-values) are excluded: a quoted string stays a string and
+never becomes a `time.Time` or one of the local wrappers.
+
+### Durations
+
+TOML has no duration type, so `time.Duration` has a rule of its own. The
+encoder writes the canonical Go form in a TOML string, `1h30m0s`, and the
+decoder reads that string back with `time.ParseDuration`. A bare integer is
+still the nanosecond count it has always been, so `from_int = 5400000000000`
+and `from_text = "1h30m"` decode to the same duration. Text that
+`time.ParseDuration` rejects, `d = "90"` among it, fails with
+`interpres: invalid duration "90"`.
+
 ### Strict decoding
 
 By default unknown keys are dropped silently. A `Decoder` built with
@@ -329,6 +364,27 @@ func (p Port) MarshalTOML() (any, error) {
 }
 ```
 
+### Custom encoding: `encoding.TextMarshaler`
+
+A type that implements `encoding.TextMarshaler` is encoded as a TOML string
+holding the text the method returns, which is the rule `encoding/json` follows:
+
+```go
+func (ip IP) MarshalText() ([]byte, error)
+```
+
+The encoder looks for the method on the value and on its address, so a
+pointer-receiver `MarshalText` is found on a struct field of an addressable
+value (pass a pointer to `Marshal`) and always on a slice element. `net.IP`,
+`netip.Addr` and user types follow this rule, and a struct that implements the
+interface becomes a string rather than a table. `MarshalTOML` wins when a type
+implements both, the four [date-time types](#date-time-values) keep their bare
+timestamp form, and text that is not valid UTF-8 is an error rather than a
+replacement character.
+
+A duration carries no text method of its own; see [Durations](#durations) for
+its rule.
+
 ### Arrays
 
 An array whose every element is a table (`[]struct`, `[]map[string]V`, after