This is an automated email from the ASF dual-hosted git repository.

chaokunyang pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/fory-site.git

commit 1030d44513646e8ae90454689c21cafa547ac4e7
Author: chaokunyang <[email protected]>
AuthorDate: Tue Jul 28 04:51:03 2026 +0000

    🔄 synced local 'docs/guide/' with remote 'docs/guide/'
---
 docs/guide/dart/code-generation.md      |  93 ++------------
 docs/guide/dart/custom-serializers.md   |   2 +-
 docs/guide/dart/external-types.md       |   8 +-
 docs/guide/dart/grpc-support.md         |   2 +-
 docs/guide/dart/index.md                |   7 +-
 docs/guide/dart/inheritance.md          | 211 ++++++++++++++++++++++++++++++++
 docs/guide/dart/schema-evolution.md     |  30 ++---
 docs/guide/dart/schema-metadata.md      |  27 ++--
 docs/guide/dart/supported-types.md      |  26 ++--
 docs/guide/dart/troubleshooting.md      |  43 +++----
 docs/guide/dart/type-registration.md    |   6 +-
 docs/guide/dart/web-platform-support.md |  13 +-
 docs/guide/dart/xlang-serialization.md  |  17 +--
 13 files changed, 320 insertions(+), 165 deletions(-)

diff --git a/docs/guide/dart/code-generation.md 
b/docs/guide/dart/code-generation.md
index 63e5aee954..a3a06745e2 100644
--- a/docs/guide/dart/code-generation.md
+++ b/docs/guide/dart/code-generation.md
@@ -58,87 +58,13 @@ For a class owned by another library, define an
 
 ## Inherited Fields
 
-For an ordinary struct, Fory follows the concrete superclass and applied-mixin
-storage chain. All non-static instance storage is flattened into the concrete
-child's one generated schema, globally ordered with fields declared directly
-on the child. Interfaces and abstract accessors do not add storage.
+An ordinary `@ForyStruct()` flattens its concrete superclass and applied-mixin
+fields into one generated child schema. Public inherited fields require no
+annotation on the parent.
 
-Field annotations belong to the field declaration. In particular,
-`@ForyField(ignore: true)` on the declaring field is the only way to omit
-ordinary storage. Fory reports a generation error instead of silently omitting
-a field that is inaccessible, hidden, unsupported, or cannot be reconstructed.
-
-| Inherited field                         | Requirement                        
                                       |
-| --------------------------------------- | 
------------------------------------------------------------------------- |
-| Public field                            | No parent annotation; generated 
child code accesses it directly           |
-| Private field in the child's library    | No parent annotation; the 
generated part accesses it directly             |
-| Private field in another Dart library   | A public boundary in that 
declaring library uses `exposePrivateFields`    |
-| Field marked `@ForyField(ignore: true)` | Omitted from the schema; no access 
or construction requirement is checked |
-
-To expose private state from a library that owns a base class:
-
-```dart
-// package:model_owner/base.dart
-import 'package:fory/fory.dart';
-
-part 'base.fory.dart';
-
-@ForyStruct(exposePrivateFields: true)
-abstract class AccountBase {
-  AccountBase(String tenantId) : _tenantId = tenantId;
-
-  final String _tenantId;
-
-  String get tenantId => _tenantId;
-}
-```
-
-The consumer annotates only its concrete type:
-
-```dart
-// lib/account.dart
-import 'package:fory/fory.dart';
-import 'package:model_owner/base.dart';
-
-part 'account.fory.dart';
-
-@ForyStruct()
-final class Account extends AccountBase {
-  Account(String tenantId) : super(tenantId);
-}
-```
-
-`exposePrivateFields` defaults to `false` and authorizes only the generated
-private-field access companion owned by that library. It does not control field
-discovery or same-library private access. Placing it on `Account` cannot expose
-private fields owned by `model_owner`. If a hierarchy contains private fields
-from several libraries, each declaring library needs its own public opted-in
-boundary.
-
-The child source must import the provider namespace without hiding the
-generated companion. A barrel is valid when it re-exports both the public
-boundary and the companion. Across packages, generate and publish the
-provider's `.fory.dart` part before building a consumer.
-
-For example, a restrictive barrel for the model above must include both names:
-
-```dart
-export 'base.dart'
-    show AccountBase, $AccountBaseForyFieldAccess;
-```
-
-Non-ignored `final` and `late final` fields require an identity-preserving path
-from a parameter of the concrete child's selected generative constructor to
-the exact field. Initializing formals, super formals, redirects, and direct
-constructor initializers are supported. A parameter with the same name is not
-proof if the constructor ignores or transforms it. Use
-`@ForyField(ignore: true)` or a manual serializer when the object cannot be
-reconstructed without custom logic.
-
-The concrete child is registered independently and owns the only serializer
-for its flattened schema. Parent serializers are not nested or invoked.
-Inherited reference annotations feed the existing reference behavior exactly
-like fields declared directly on the child.
+See [Struct Inheritance](inheritance.md) for private fields,
+`ignoreInheritedPrivateFields`, cross-library access, constructors, mixins, and
+schema compatibility.
 
 ## Step 2 — Run the Generator
 
@@ -150,7 +76,7 @@ dart run build_runner build
 
 This emits a `.fory.dart` file next to your source file. Re-run this command 
any
 time you add or rename annotated types, change hierarchy storage, or change an
-exposure boundary.
+exposure boundary or `ignoreInheritedPrivateFields`.
 
 ## Step 3 — Register and Use
 
@@ -193,8 +119,8 @@ class Event {
 
 When using evolving structs, also assign stable field IDs with `@ForyField(id: 
...)` before you ship your first payload — those IDs are how Fory matches 
fields after a schema change.
 
-Inherited and direct fields share this one ID namespace. Do not reuse an ID in
-another superclass, mixin, or child field.
+Included inherited and direct fields share this one ID namespace. Do not reuse
+an ID among fields included in the same child schema.
 
 ## Choosing Generated or Manual Serialization
 
@@ -205,6 +131,7 @@ field names, values, or construction need custom logic.
 
 ## Related Topics
 
+- [Struct Inheritance](inheritance.md)
 - [Type Registration](type-registration.md)
 - [External-Type Serialization](external-types.md)
 - [Schema Metadata](schema-metadata.md)
diff --git a/docs/guide/dart/custom-serializers.md 
b/docs/guide/dart/custom-serializers.md
index 14c677fde5..c9714f60fa 100644
--- a/docs/guide/dart/custom-serializers.md
+++ b/docs/guide/dart/custom-serializers.md
@@ -1,6 +1,6 @@
 ---
 title: Manual Serializers
-sidebar_position: 10
+sidebar_position: 11
 id: custom_serializers
 license: |
   Licensed to the Apache Software Foundation (ASF) under one or more
diff --git a/docs/guide/dart/external-types.md 
b/docs/guide/dart/external-types.md
index 827c058e05..20540fad76 100644
--- a/docs/guide/dart/external-types.md
+++ b/docs/guide/dart/external-types.md
@@ -1,6 +1,6 @@
 ---
 title: External-Type Serialization
-sidebar_position: 4
+sidebar_position: 5
 id: external_types
 license: |
   Licensed to the Apache Software Foundation (ASF) under one or more
@@ -65,8 +65,9 @@ arguments, must exactly match an accessible getter on the 
target.
 The declaration's field list is the complete external schema. Fory does not
 automatically add fields from the target, its superclass, or its mixins. You
 may explicitly declare an accessible inherited target property just like any
-other schema field. `exposePrivateFields` applies only to ordinary Dart
-hierarchies and is invalid with `ForyStruct.target`.
+other schema field. `exposePrivateFields` and
+`ignoreInheritedPrivateFields` apply only to ordinary Dart hierarchies and are
+invalid with `ForyStruct.target`.
 
 Public target fields count toward the graph-memory budget automatically, but
 that accounting does not add them to the serialized schema. Use
@@ -314,6 +315,7 @@ setters.
 
 ## Related Topics
 
+- [Struct Inheritance](inheritance.md)
 - [Code Generation](code-generation.md)
 - [Type Registration](type-registration.md)
 - [Schema Metadata](schema-metadata.md)
diff --git a/docs/guide/dart/grpc-support.md b/docs/guide/dart/grpc-support.md
index 58f77a2a13..c53530a597 100644
--- a/docs/guide/dart/grpc-support.md
+++ b/docs/guide/dart/grpc-support.md
@@ -1,6 +1,6 @@
 ---
 title: gRPC Support
-sidebar_position: 13
+sidebar_position: 14
 id: grpc_support
 license: |
   Licensed to the Apache Software Foundation (ASF) under one or more
diff --git a/docs/guide/dart/index.md b/docs/guide/dart/index.md
index 8097bc48ed..2317e5acaa 100644
--- a/docs/guide/dart/index.md
+++ b/docs/guide/dart/index.md
@@ -114,8 +114,8 @@ dart run build_runner build
 
 An ordinary annotated class includes its concrete superclass and applied-mixin
 storage. Public and same-library private inherited fields need no parent
-annotation. See [Code Generation](code-generation.md) for cross-library private
-fields and constructor requirements.
+annotation. See [Struct Inheritance](inheritance.md) for private fields,
+constructors, mixins, and field inclusion options.
 
 ## API Overview
 
@@ -125,6 +125,8 @@ fields and constructor requirements.
 - `@ForyStruct()` — marks a class for code generation
 - `@ForyStruct(exposePrivateFields: true)` — lets another library's generated
   child serializer access private state owned by this library
+- `@ForyStruct(ignoreInheritedPrivateFields: true)` — omits all private
+  superclass and applied-mixin storage from this concrete child's schema
 - `@ForyStruct(target: Type)` — generates an external structural serializer
 - `@ForyField(...)` — per-field options and canonical `type:` overrides
 - `@ListField(...)`, `@SetField(...)`, `@MapField(...)` — container sugar for 
nested `type:` trees
@@ -140,6 +142,7 @@ fields and constructor requirements.
 | [Configuration](configuration.md)                | Fory options, compatible 
mode, and safety limits                |
 | [Basic Serialization](basic-serialization.md)    | `serialize`, 
`deserialize`, generated registration, root graphs |
 | [Code Generation](code-generation.md)            | `@ForyStruct`, build 
runner, and generated modules              |
+| [Struct Inheritance](inheritance.md)             | Superclasses, mixins, 
private fields, and constructors          |
 | [External-Type Serialization](external-types.md) | Generated serializers for 
classes owned by another package      |
 | [Xlang Serialization](xlang-serialization.md)    | Interoperability rules 
and field alignment                      |
 | [Schema Metadata](schema-metadata.md)            | `@ForyField`, field IDs, 
nullability, references, polymorphism  |
diff --git a/docs/guide/dart/inheritance.md b/docs/guide/dart/inheritance.md
new file mode 100644
index 0000000000..4ca58612d0
--- /dev/null
+++ b/docs/guide/dart/inheritance.md
@@ -0,0 +1,211 @@
+---
+title: Struct Inheritance
+sidebar_position: 4
+id: inheritance
+license: |
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You under the Apache License, Version 2.0
+  (the "License"); you may not use this file except in compliance with
+  the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+---
+
+Ordinary Dart `@ForyStruct()` classes serialize one flattened view of their
+concrete superclass and applied-mixin storage. The generated child schema does
+not nest or invoke a parent serializer.
+
+## Public Fields
+
+Public inherited fields need no annotation on the parent:
+
+```dart
+class MessageBase {
+  int sequence = 0;
+}
+
+@ForyStruct()
+class TextMessage extends MessageBase {
+  TextMessage();
+
+  String text = '';
+}
+```
+
+The generated `TextMessage` schema contains both `sequence` and `text`.
+Interfaces, abstract getters, static fields, and mixin `on` constraints do not
+add storage.
+
+## Field Inclusion
+
+Fory first discovers the complete concrete superclass and applied-mixin
+storage chain. It applies declaration-owned field omission first, followed by
+the concrete-child option:
+
+| Configuration                                     | Scope                    
                                                                            |
+| ------------------------------------------------- | 
----------------------------------------------------------------------------------------------------
 |
+| `@ForyField(ignore: true)`                        | Omits that declaring 
field from every child schema                                                   
|
+| `@ForyStruct(ignoreInheritedPrivateFields: true)` | Omits every private 
field declared by an ancestor or applied mixin from this concrete child's 
schema |
+
+Every remaining field must have a supported type, an unambiguous access path,
+and a valid reconstruction path. Fory reports a generation error instead of
+silently dropping unresolved state.
+
+Both omission options are applied during code generation. They do not add a
+runtime flag, branch, or parent serializer.
+
+## Ignoring Inherited Private Fields
+
+`ignoreInheritedPrivateFields` defaults to `false`. Set it on a concrete child
+when that child's wire schema intentionally excludes all private ancestor
+state:
+
+```dart
+class FrameworkBase {
+  String _cache = '';
+  String publicLabel = '';
+}
+
+@ForyStruct(ignoreInheritedPrivateFields: true)
+class PublicMessage extends FrameworkBase {
+  PublicMessage();
+
+  String _localState = '';
+  String text = '';
+}
+```
+
+The `PublicMessage` schema contains `_localState`, `text`, and `publicLabel`.
+It does not contain `_cache`.
+
+The option has the following exact scope:
+
+- It applies to private fields declared by direct or transitive superclasses
+  and applied mixins.
+- It treats same-library and cross-library private fields identically.
+- It never omits a private field declared directly by the annotated child.
+- It never omits an inherited public field.
+- It belongs only to the annotated concrete child. A parent annotation does
+  not change a child's setting.
+- It filters matching fields before private access is resolved. An omitted
+  field does not require an access companion, even when one exists.
+- It is invalid on `ForyStruct.target` declarations and provider-only abstract,
+  open-generic, or mixin declarations.
+
+A concrete class may set both `exposePrivateFields: true` and
+`ignoreInheritedPrivateFields: true`. Its own serializer omits its private
+ancestor fields, while its generated access companion remains available to
+other child libraries.
+
+## Including Cross-Library Private Fields
+
+With the default `ignoreInheritedPrivateFields: false`, private fields declared
+in another Dart library remain part of the child schema. The declaring library
+must expose them through a public hierarchy boundary:
+
+```dart
+// package:model_owner/base.dart
+import 'package:fory/fory.dart';
+
+part 'base.fory.dart';
+
+@ForyStruct(exposePrivateFields: true)
+abstract class AccountBase {
+  String _tenant = '';
+
+  String get tenant => _tenant;
+}
+```
+
+The consumer uses the normal annotation:
+
+```dart
+// lib/account.dart
+import 'package:fory/fory.dart';
+import 'package:model_owner/base.dart';
+
+part 'account.fory.dart';
+
+@ForyStruct()
+class Account extends AccountBase {
+  Account();
+}
+```
+
+Generate and publish `base.fory.dart` before generating a dependent consumer.
+A direct import or barrel export must expose both the public boundary and its
+generated `$AccountBaseForyFieldAccess` companion. If private fields come from
+several libraries, each declaring library needs its own public boundary and
+companion.
+
+Private inherited fields declared in the same Dart library as the child need
+no parent annotation or companion.
+
+## Constructors and Final Fields
+
+Every included `final` or `late final` field must receive its decoded value
+unchanged through the selected concrete-child generative constructor. Fory can
+follow initializing formals, super formals, redirects, and direct constructor
+initializers. A parameter with the same name is not sufficient proof if the
+value is ignored or transformed.
+
+Filtering a private field does not let Fory invent constructor inputs. If a
+required child constructor parameter no longer has a serialized field source,
+generation fails. Use a reconstructing constructor, declaration-owned
+`@ForyField(ignore: true)` where appropriate, or a manual serializer.
+
+## Mixins, Generics, and Field IDs
+
+Applied mixin storage is flattened like superclass storage. Generic field types
+are specialized for the concrete child before schema metadata is generated.
+All included child, superclass, and mixin fields share one field-ID namespace
+and one canonical ordering.
+
+Field hiding is rejected when it prevents generated access from reaching an
+included physical storage slot. Omitting private ancestor storage does not
+relax validation for retained public or child-declared fields.
+
+## References and Graph Memory
+
+Included inherited `ref: true` fields and nested container reference metadata
+use the same reference behavior as equivalent fields declared directly on the
+child. Omitted fields do not enter generated reference analysis. Inheritance
+does not add a reference mode or parent-level reference state.
+
+Physical inherited storage still contributes to shallow graph-memory
+accounting when omitted, matching `@ForyField(ignore: true)` behavior.
+
+## External Types
+
+`ForyStruct.target` declarations retain their explicit field list. Fory does
+not scan an external target hierarchy automatically, and neither
+`exposePrivateFields` nor `ignoreInheritedPrivateFields` is valid with
+`target`.
+
+An external declaration may explicitly list an accessible property inherited
+by its target. See [External-Type Serialization](external-types.md).
+
+## Regeneration and Compatibility
+
+Regenerate affected `.fory.dart` files after changing hierarchy storage,
+`exposePrivateFields`, or `ignoreInheritedPrivateFields`.
+
+Changing `ignoreInheritedPrivateFields` changes the generated field set.
+Compatible mode uses its normal missing-field and unknown-field behavior.
+Fixed-schema peers must update together.
+
+## Related Topics
+
+- [Code Generation](code-generation.md)
+- [Schema Metadata](schema-metadata.md)
+- [Schema Evolution](schema-evolution.md)
+- [Type Registration](type-registration.md)
+- [Troubleshooting](troubleshooting.md)
diff --git a/docs/guide/dart/schema-evolution.md 
b/docs/guide/dart/schema-evolution.md
index 741bf9cefe..123fc9315d 100644
--- a/docs/guide/dart/schema-evolution.md
+++ b/docs/guide/dart/schema-evolution.md
@@ -1,6 +1,6 @@
 ---
 title: Schema Evolution
-sidebar_position: 9
+sidebar_position: 10
 id: schema_evolution
 license: |
   Licensed to the Apache Software Foundation (ASF) under one or more
@@ -62,10 +62,9 @@ class UserProfile {
 
 If you add field IDs after payloads are already in production, existing stored 
messages won't have them and evolution won't work correctly.
 
-For an ordinary inherited struct, the concrete child's schema contains every
-non-ignored field from its superclass and applied-mixin storage chain. Assign
-IDs across that complete flattened hierarchy; an ID used by a parent or mixin
-cannot be reused by the child.
+For an ordinary inherited struct, assign IDs across every field included in
+the concrete child's flattened schema. An ID used by an included parent or
+mixin field cannot be reused by the child.
 
 For an [external structural serializer](external-types.md), the local
 serializer declaration supplies the evolving schema and each declaration field
@@ -113,20 +112,23 @@ final fory = Fory(compatible: false);
 ## Regenerating Inherited Schemas
 
 Regenerate every affected `.fory.dart` part after adding inherited storage,
-changing a superclass or mixin, or changing `exposePrivateFields`. Generate a
-dependency package's provider part before building its consumers.
+changing a superclass or mixin, changing `exposePrivateFields`, or changing
+`ignoreInheritedPrivateFields`. Generate a dependency package's provider part
+before building consumers that include its private fields.
 
-Older Dart generated code did not include ordinary inherited fields. After
-regeneration, compatible schemas use their normal missing-field and
-unknown-field behavior. Fixed schemas written without the inherited fields are
-not compatible with the corrected flattened schema; Fory does not add a
-special legacy reader for those payloads.
+Enabling `ignoreInheritedPrivateFields` removes every private ancestor and
+applied-mixin field from that concrete child's generated schema. Disabling it
+adds those fields back and may require provider companions. Compatible schemas
+use their normal missing-field and unknown-field behavior. Fixed-schema peers
+must change together because the resulting field list is different. A parent
+annotation does not propagate this setting to children.
 
-This migration changes generated field discovery only. It does not change the
-runtime reference protocol.
+This option changes generated field selection only. It does not change the
+runtime reference protocol or add a compatibility reader.
 
 ## Related Topics
 
+- [Struct Inheritance](inheritance.md)
 - [Configuration](configuration.md)
 - [External-Type Serialization](external-types.md)
 - [Schema Metadata](schema-metadata.md)
diff --git a/docs/guide/dart/schema-metadata.md 
b/docs/guide/dart/schema-metadata.md
index 61f93c522f..e874fbb05c 100644
--- a/docs/guide/dart/schema-metadata.md
+++ b/docs/guide/dart/schema-metadata.md
@@ -1,6 +1,6 @@
 ---
 title: Schema Metadata
-sidebar_position: 6
+sidebar_position: 7
 id: schema_metadata
 license: |
   Licensed to the Apache Software Foundation (ASF) under one or more
@@ -23,7 +23,8 @@ Add `@ForyField(...)` to a field inside a `@ForyStruct()` 
class to change how th
 
 For ordinary inheritance, metadata stays with the storage declaration and is
 applied when any concrete annotated child discovers that field. A child
-redeclaration does not replace or merge the ancestor field's metadata.
+redeclaration does not replace or merge the ancestor field's metadata. See
+[Struct Inheritance](inheritance.md) for inherited-field inclusion rules.
 
 The same annotations apply to fields in an
 [external structural serializer declaration](external-types.md).
@@ -43,10 +44,14 @@ The same annotations apply to fields in an
 ## `ignore`
 
 Exclude the declaring field from serialization entirely. This is the only
-supported way to omit ordinary instance storage, including inherited storage.
-Useful examples include cached, computed, or UI-only values that should not
-land in a persisted or transmitted message. The field still contributes to
-graph-memory accounting; because it has no wire representation, do not combine
+per-field, declaration-owned omission and applies to every concrete child that
+discovers the field. Useful examples include cached, computed, or UI-only
+values that should not land in a persisted or transmitted message.
+
+For child-specific omission of all private ancestor fields, see
+[`ignoreInheritedPrivateFields`](inheritance.md#ignoring-inherited-private-fields).
+Omitted physical storage still contributes to shallow graph-memory accounting.
+Because a declaration-ignored field has no wire representation, do not combine
 `ignore` with other `ForyField` options.
 
 ```dart
@@ -66,7 +71,8 @@ String name = '';
 Once a payload is shared across services, never reuse an `id` for a different 
field.
 
 An ordinary child has one flattened field namespace. IDs must therefore be
-unique across its child, superclass, and applied-mixin declarations.
+unique across all fields included from its child, superclass, and
+applied-mixin declarations.
 
 ## `nullable`
 
@@ -90,9 +96,9 @@ List<Object?> sharedNodes = <Object?>[];
 
 Note: scalar types like `int`, `double`, and `bool` never benefit from 
reference tracking even if `ref: true` is set.
 
-An inherited `ref` annotation behaves exactly like the same annotation on a
-field declared directly by the concrete child. Inheritance does not introduce
-another reference-tracking mode or owner.
+An included inherited `ref` annotation behaves exactly like the same
+annotation on a field declared directly by the concrete child. See
+[Struct Inheritance](inheritance.md#references-and-graph-memory).
 
 ## `dynamic`
 
@@ -159,6 +165,7 @@ When the same model is defined in multiple languages:
 
 ## Related Topics
 
+- [Struct Inheritance](inheritance.md)
 - [Code Generation](code-generation.md)
 - [External-Type Serialization](external-types.md)
 - [Schema Evolution](schema-evolution.md)
diff --git a/docs/guide/dart/supported-types.md 
b/docs/guide/dart/supported-types.md
index 6af5f93777..91b8a08186 100644
--- a/docs/guide/dart/supported-types.md
+++ b/docs/guide/dart/supported-types.md
@@ -1,6 +1,6 @@
 ---
 title: Supported Types
-sidebar_position: 8
+sidebar_position: 9
 id: supported_types
 license: |
   Licensed to the Apache Software Foundation (ASF) under one or more
@@ -130,22 +130,19 @@ class User {
 }
 ```
 
-Ordinary annotated classes may extend classes and apply mixins. Fory includes
-every concrete instance storage field from that hierarchy in one child schema,
-including inherited generic fields after specialization. Public fields and
-private fields in the child's Dart library are accessed directly.
-Cross-library private storage is supported only when its declaring library
-provides a public boundary annotated with
-`@ForyStruct(exposePrivateFields: true)`.
+Ordinary annotated classes may extend classes and apply mixins. Fory discovers
+every concrete instance storage field from that hierarchy, including inherited
+generic fields after specialization, then builds one child schema. See
+[Struct Inheritance](inheritance.md) for private-field access and omission.
 
 Abstract getters, interfaces, static members, and other declarations without
-instance storage are not fields. A real non-ignored storage field must have a
-supported type, an unambiguous access path, and a valid reconstruction path;
-otherwise generation fails. In particular, each `final` or `late final` field
-must receive the decoded value unchanged through the concrete child's
-constructor chain.
+instance storage are not fields. Every field that remains after explicit
+omission must have a supported type, an unambiguous access path, and a valid
+reconstruction path; otherwise generation fails. In particular, each included
+`final` or `late final` field must receive the decoded value unchanged through
+the concrete child's constructor chain.
 
-See [Code Generation](code-generation.md).
+See [Code Generation](code-generation.md) for generator setup.
 
 Classes owned by another library can use an
 [external structural serializer](external-types.md) when their public fields
@@ -174,6 +171,7 @@ width is one of the most common cross-language bugs.
 
 ## Related Topics
 
+- [Struct Inheritance](inheritance.md)
 - [Schema Metadata](schema-metadata.md)
 - [Xlang Serialization](xlang-serialization.md)
 - [Schema Evolution](schema-evolution.md)
diff --git a/docs/guide/dart/troubleshooting.md 
b/docs/guide/dart/troubleshooting.md
index 5e184fe8d6..c99fee9b69 100644
--- a/docs/guide/dart/troubleshooting.md
+++ b/docs/guide/dart/troubleshooting.md
@@ -1,6 +1,6 @@
 ---
 title: Troubleshooting
-sidebar_position: 12
+sidebar_position: 13
 id: troubleshooting
 license: |
   Licensed to the Apache Software Foundation (ASF) under one or more
@@ -57,24 +57,19 @@ Ordinary hierarchy discovery includes private storage even 
when it is declared
 in another Dart library. Privacy affects generated access, not whether the
 field exists in the schema.
 
-- A private field declared in the same library as the child needs no parent
-  annotation.
-- For a private field declared in another library, annotate a public hierarchy
-  boundary in that declaring library with
-  `@ForyStruct(exposePrivateFields: true)`.
-- Import that provider directly, or use a barrel that re-exports both the
-  public boundary and its generated `$<Boundary>ForyFieldAccess` companion.
-- If several libraries declare private fields in the hierarchy, each library
-  must provide its own boundary.
-
-Putting `exposePrivateFields: true` only on the consumer child cannot authorize
-another library's private state. To omit a field intentionally, place
-`@ForyField(ignore: true)` on its declaration. Fory does not silently omit an
-inaccessible inherited field.
+Same-library private fields need no parent annotation. For a cross-library
+field, expose it from its declaring library with `exposePrivateFields: true` 
and
+make the generated companion visible to the child. If the child intentionally
+excludes all private ancestor state, set
+`ignoreInheritedPrivateFields: true` on that child instead.
+
+See [Struct Inheritance](inheritance.md) for complete access, omission, and
+multi-library rules.
 
 ## Final inherited field cannot be reconstructed
 
-A non-ignored `final` or `late final` field must receive its decoded value
+A final or `late final` field that remains in the schema must receive its
+decoded value
 unchanged from a parameter of the concrete child's selected generative
 constructor. Fory can follow initializing formals, super formals, redirects,
 and direct constructor initializers across the hierarchy.
@@ -82,15 +77,20 @@ and direct constructor initializers across the hierarchy.
 A parameter with the same name and type is insufficient if it is unused or its
 value is cast, transformed, or passed through a function. Forward the decoded
 value directly to the exact field, mark the field declaration with
-`@ForyField(ignore: true)`, or use a manual serializer.
+`@ForyField(ignore: true)`, or use a manual serializer. If
+`ignoreInheritedPrivateFields` removes the only serialized source for a
+required constructor parameter, Fory still reports this error rather than
+inventing a value. See
+[Constructors and Final Fields](inheritance.md#constructors-and-final-fields).
 
 ## Inherited field is hidden
 
-A subclass field or accessor can hide an ancestor storage slot while both
-physical slots remain on the object. Fory rejects this shape instead of
+A subclass field or accessor can hide an included ancestor storage slot while
+both physical slots remain on the object. Fory rejects this shape instead of
 choosing one slot and losing the other. Rename or remove the hiding member,
-ignore the ancestor field at its declaration when omission is intentional, or
-use a manual serializer.
+ignore the ancestor field at its declaration, or use a manual serializer. For
+private ancestor state, setting `ignoreInheritedPrivateFields: true` omits all
+private ancestor storage from that child schema.
 
 ## External target generation fails
 
@@ -216,6 +216,7 @@ separate protobuf service endpoint for generic protobuf 
clients.
 
 ## Related Topics
 
+- [Struct Inheritance](inheritance.md)
 - [Xlang Serialization](xlang-serialization.md)
 - [Code Generation](code-generation.md)
 - [Manual Serializers](custom-serializers.md)
diff --git a/docs/guide/dart/type-registration.md 
b/docs/guide/dart/type-registration.md
index 0a2f6bcae4..938f0a046e 100644
--- a/docs/guide/dart/type-registration.md
+++ b/docs/guide/dart/type-registration.md
@@ -1,6 +1,6 @@
 ---
 title: Type Registration
-sidebar_position: 7
+sidebar_position: 8
 id: type_registration
 license: |
   Licensed to the Apache Software Foundation (ASF) under one or more
@@ -73,7 +73,8 @@ it contributes fields.
 Register an independently annotated concrete parent only when values whose
 runtime type is that parent are also serialized. A provider-only
 `@ForyStruct(exposePrivateFields: true)` boundary supplies generated field
-access and has no registration entry of its own.
+access and has no registration entry of its own. See
+[Struct Inheritance](inheritance.md) for boundary and child-schema options.
 
 External structural serializers use the same generated registration API. Pass
 the external target type:
@@ -118,6 +119,7 @@ The same numeric ID or name must be used in every peer that 
reads or writes the
 
 ## Related Topics
 
+- [Struct Inheritance](inheritance.md)
 - [Code Generation](code-generation.md)
 - [External-Type Serialization](external-types.md)
 - [Xlang Serialization](xlang-serialization.md)
diff --git a/docs/guide/dart/web-platform-support.md 
b/docs/guide/dart/web-platform-support.md
index 0d0190d272..ece2829216 100644
--- a/docs/guide/dart/web-platform-support.md
+++ b/docs/guide/dart/web-platform-support.md
@@ -1,6 +1,6 @@
 ---
 title: Web Platform Support
-sidebar_position: 11
+sidebar_position: 12
 id: web_platform_support
 license: |
   Licensed to the Apache Software Foundation (ASF) under one or more
@@ -84,12 +84,10 @@ The registration call is the same on VM/AOT, Flutter, and 
web. Manual
 serializers use `registerSerializer(...)`; generated structs use the generated
 `register` wrapper.
 
-Inherited fields use the same statically generated code on every platform.
-Public and same-library private fields are accessed directly. A provider
-library annotated with `@ForyStruct(exposePrivateFields: true)` emits typed
-static access methods for its own private state; it does not use mirrors,
-callbacks, runtime member lookup, or a parent serializer. Generate a dependency
-provider before compiling its consumer.
+Included inherited fields use the same statically generated code on every
+platform. `ignoreInheritedPrivateFields` is applied during generation and adds
+no runtime branch. See [Struct Inheritance](inheritance.md) for cross-library
+provider setup.
 
 ## 64-Bit Integer Rules
 
@@ -234,6 +232,7 @@ JS-safe non-negative range.
 
 ## Related Topics
 
+- [Struct Inheritance](inheritance.md)
 - [Supported Types](supported-types.md)
 - [Schema Metadata](schema-metadata.md)
 - [Code Generation](code-generation.md)
diff --git a/docs/guide/dart/xlang-serialization.md 
b/docs/guide/dart/xlang-serialization.md
index 2bea4ca01e..d66475a7fb 100644
--- a/docs/guide/dart/xlang-serialization.md
+++ b/docs/guide/dart/xlang-serialization.md
@@ -1,6 +1,6 @@
 ---
 title: Xlang Serialization
-sidebar_position: 5
+sidebar_position: 6
 id: xlang_serialization
 license: |
   Licensed to the Apache Software Foundation (ASF) under one or more
@@ -194,12 +194,14 @@ Fory matches fields by name or by stable field ID. For 
robust cross-language int
 For an ordinary Dart class, Fory flattens concrete superclass and applied-mixin
 storage into the annotated child's one struct schema. Parent and child fields
 share one field-ID namespace and one canonical ordering, so the peer language
-should define the equivalent flat field set. A parent is not encoded as a
-nested object.
-
-Inherited `@ForyField(ref: true)` and nested container reference metadata use
-the same reference behavior as fields declared directly on the child.
-Inheritance does not change xlang reference framing or add parent-level
+should define the equivalent included flat field set. Fields omitted by
+`@ForyField(ignore: true)` or the concrete child's
+`ignoreInheritedPrivateFields` option are absent from that peer schema. A
+parent is not encoded as a nested object.
+
+Included inherited `@ForyField(ref: true)` and nested container reference
+metadata use the same reference behavior as fields declared directly on the
+child. Inheritance does not change xlang reference framing or add parent-level
 reference state.
 
 ## Type Mapping Notes for Dart
@@ -253,6 +255,7 @@ dart test
 
 ## Related Topics
 
+- [Struct Inheritance](inheritance.md)
 - [Type Registration](type-registration.md)
 - [External-Type Serialization](external-types.md)
 - [Schema Evolution](schema-evolution.md)


---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]


Reply via email to