Document serialization compiler intrinsics

Author: Frotty

_doc/manual.md

@@ -880,30 +880,67 @@ function foo()
 
 ### Compiler-assisted field mapping
 
-For dedicated state classes, the compiler provides two save/load intrinsics that expand into direct field
-accesses:
+The compiler provides three prefixed operations for libraries that need type-safe structural mapping without
+runtime reflection: `wurstForFields`, `wurstMapFields`, and `wurstNewInstance<T>()`. They are declared in
+`MagicFunctions` with `@compilerintrinsic`, so editors can show their documentation and signatures while the
+compiler still replaces calls with direct accesses and constructor calls.
 
 ```wurst
 class PlayerState
     int level = 1
     string name = ""
 
     function save(FieldWriter writer)
-        __wurst_forFields((fieldName, value) -> writer.write(fieldName, value))
+        wurstForFields((fieldName, value) -> writer.write(fieldName, value))
 
     function load(FieldReader reader)
-        __wurst_mapFields((fieldName, value) -> reader.read(fieldName, value))
+        wurstMapFields((fieldName, value) -> reader.read(fieldName, value))
+
+function loadPlayerState(FieldReader reader) returns PlayerState
+    let result = wurstNewInstance<PlayerState>()
+    result.load(reader)
+    return result
+```
+
+`wurstForFields` invokes the callback once for every accessible, non-static instance field, including inherited
+and module-injected fields. Readonly and constant fields are included. `wurstMapFields` assigns each callback
+result back to its field, so every included field must be mutable. The callback's value parameter has the concrete
+type of the current field; leave it inferred and overload the reader or writer for every supported field type.
+This allows a library to compose codecs for primitives, enums, nullable values, nested state classes, tuples, and
+generic collections without a runtime type registry.
+
+Both operations also accept an explicit target as their first argument. Class targets are evaluated exactly once.
+Tuple targets use direct component accesses; a tuple passed to `wurstMapFields` must be a variable so the updated
+tuple can be written back safely.
+
+```wurst
+tuple Position(int x, int y)
+
+function savePosition(Position position, FieldWriter writer)
+    wurstForFields(position, (fieldName, value) -> writer.write(fieldName, value))
+
+function loadPosition(Position position, FieldReader reader) returns Position
+    var result = position
+    wurstMapFields(result, (fieldName, value) -> reader.read(fieldName, value))
+    return result
 ```
 
-`__wurst_forFields` invokes the callback once for every non-static instance field. The callback receives the
-field name and current value and must produce a statement. `__wurst_mapFields` invokes a reader callback and
-assigns its result back to each field. Leave the two callback parameter types inferred; overload the reader or
-writer for the field types used by the state class.
+`wurstNewInstance<T>()` calls the normal accessible zero-argument constructor of a concrete class. Constructor
+initializers therefore provide defaults for fields absent from older records; the operation never allocates an
+uninitialized object or performs class-name lookup.
+
+These operations generate ordinary constructor calls and direct field or tuple accesses in both Jass and Lua.
+They do not define a save format or make field names stable persisted identities. A serialization library must
+own numeric field IDs, object versions, migrations, parsing, and integrity checks. Cyclic object graphs and field
+types for which the library has no codec still require an explicit user-provided codec.
+
+The original unprefixed `forFields`, `mapFields`, and `newInstance<T>()` spellings remain available as compatibility
+fallbacks. New code should use the `wurst`-prefixed names to avoid accidental collisions. If an applicable ordinary
+function with the same name is visible, normal overload resolution selects that function instead of the compiler
+operation.
 
-These are compile-time transformations, not runtime reflection, and generate equivalent direct accesses in both
-Jass and Lua. Keep serializable state in a small class with mutable instance fields and keep the persistence
-codec separate from the rest of the game logic. See the [Save and Load tutorial](/tutorials/saveload.html) for
-integration with Warcraft III's file API.
+Keep serializable state in a small class and keep persistence policy separate from the rest of the game logic.
+See the [Save and Load tutorial](/tutorials/saveload.html) for integration with Warcraft III's file API.
 
 ### Array Members