feat(dart): support dart web platform (#3608)

## Why?

Dart web builds use JavaScript number semantics, so raw Dart `int`
cannot safely represent the full 64-bit value space used by Fory xlang
integer encodings. The Dart runtime needs browser-compatible buffer,
generated serializer, and 64-bit wrapper implementations that preserve
wire compatibility instead of silently corrupting JS-unsafe values.


## What does this PR do?

- Adds Dart web support through conditional native/web implementations
for `Buffer`, generated cursors, and `Int64` / `Uint64` value and list
wrappers.
- Updates code generation and serializers to handle full-range signed
and unsigned 64-bit fields on web, while keeping Dart `int` fast paths
for JS-safe values.
- Adds explicit range checks so web builds reject JS-unsafe Dart `int`
conversions instead of writing or reading imprecise bytes.
- Extends Dart serializer, buffer, generated-field, numeric-wrapper,
typed-array, and time tests for 64-bit edge cases and browser behavior.
- Adds Chrome test coverage to CI with `dart test -p chrome` for the
Dart package.
- Documents Dart web support, 64-bit integer rules, custom serializer
guidance, and troubleshooting steps.


## Related issues

Closes #3600


## AI Contribution Checklist



- [ ] Substantial AI assistance was used in this PR: `yes` / `no`
- [ ] If `yes`, I included a completed [AI Contribution
Checklist](https://github.com/apache/fory/blob/main/AI_POLICY.md#9-contributor-checklist-for-ai-assisted-prs)
in this PR description and the required `AI Usage Disclosure`.
- [ ] If `yes`, my PR description includes the required `ai_review`
summary and screenshot evidence of the final clean AI review results
from both fresh reviewers on the current PR diff or current HEAD after
the latest code changes.



## Does this PR introduce any user-facing change?

Yes. Dart users can now use generated serializers and manual serializers
on web/browser targets. Full-range 64-bit values should use `Int64` or
`Uint64`; Dart `int` fields remain limited to JS-safe values on web.

- [x] Does this PR introduce any public API change?
- [ ] Does this PR introduce any binary protocol compatibility change?

## Benchmark
<img width="4200" height="900" alt="throughput"
src="https://github.com/user-attachments/assets/ca422bc6-5345-4560-a35a-2678f4c54b9c"
/>

| Datatype | Operation | Fory TPS | Protobuf TPS | Fastest |
| ---------------- | ----------- | --------: | -----------: |
------------ |
| Struct | Serialize | 5,041,693 | 2,073,839 | fory (2.43x) |
| Struct | Deserialize | 6,395,290 | 4,991,881 | fory (1.28x) |
| Sample | Serialize | 1,783,688 | 552,140 | fory (3.23x) |
| Sample | Deserialize | 2,124,197 | 934,794 | fory (2.27x) |
| MediaContent | Serialize | 952,498 | 438,419 | fory (2.17x) |
| MediaContent | Deserialize | 1,649,039 | 737,340 | fory (2.24x) |
| StructList | Serialize | 1,945,119 | 399,007 | fory (4.87x) |
| StructList | Deserialize | 2,119,403 | 764,832 | fory (2.77x) |
| SampleList | Serialize | 475,413 | 52,512 | fory (9.05x) |
| SampleList | Deserialize | 508,939 | 116,236 | fory (4.38x) |
| MediaContentList | Serialize | 224,925 | 84,860 | fory (2.65x) |
| MediaContentList | Deserialize | 387,070 | 154,392 | fory (2.51x) |

Author: chaokunyang

.agents/skills/fory-code-review/SKILL.md

@@ -11,21 +11,34 @@ Find the highest-value bugs, regressions, and missing verification in Apache For
 
 ## Start Here
 
-1. If the target is a GitHub PR, create a new local git worktree for the review before checking out or fetching the PR branch.
-2. Do not switch the current branch or reuse the current worktree for PR review unless the user explicitly asks for that.
-3. If reviewing against main, run `git fetch apache main` before diffing.
-4. Inspect the changed files first and cluster them by subsystem.
-5. Load only the references needed for the touched areas:
+1. Always perform the code review in a subagent. The main agent coordinates scope, gathers the subagent's findings, sanity-checks them, and reports the final review.
+2. Reuse the same review subagent for later review passes on the same feature unless the user explicitly asks to review that feature in a new subagent.
+3. Do not reuse a review subagent across different features; start a new subagent for each distinct feature or review topic.
+4. The review subagent must be read-only: it must not write code, apply patches, create commits, push branches, fix tests, or update docs. It sends review findings or an explicit no-findings result back to the caller.
+5. If the target is a GitHub PR, create a new local git worktree for the review before checking out or fetching the PR branch.
+6. Do not switch the current branch or reuse the current worktree for PR review unless the user explicitly asks for that.
+7. If reviewing against main, run `git fetch apache main` before diffing.
+8. Inspect the changed files first and cluster them by subsystem.
+9. Load only the references needed for the touched areas:
    - `references/review-checklist.md`
    - `references/lesson-derived-red-flags.md`
    - `references/validation-command-matrix.md`
    - matching runtime docs under `../../languages/*.md` when the patch is language-specific
 
+## Subagent Reuse
+
+- Treat each feature under review as the reuse key. A feature may be a PR, issue, branch, commit range, local diff topic, or clearly named subsystem change.
+- When the user asks for another pass on the same feature, send the updated context to the existing review subagent and ask it to continue from its prior review state.
+- When the user asks to review a different feature, spawn a fresh review subagent even if the same files, language, or subsystem are involved.
+- If the user explicitly requests a new subagent for the same feature, honor that request and do not reuse the prior subagent.
+- Keep implementation work, CI fixing, and non-review exploration out of the review subagent. The review subagent reports comments to the caller; the caller decides whether any separate implementation task should happen.
+
 ## Review Workflow
 
 1. Define the review target.
 
 - Determine whether the user wants a review of a PR, branch, commit range, or local diff.
+- Assign the target to the correct review subagent using the Subagent Reuse rules before inspecting code.
 - For a GitHub PR, create and use a dedicated local worktree for the review. Keep the current worktree and branch unchanged unless the user explicitly requests otherwise.
 - In that worktree, fetch the PR head and review there instead of checking out the PR branch in the current workspace.
 - Prefer `git diff --stat` first, then inspect the full patch only for touched subsystems.
@@ -63,6 +76,7 @@ Find the highest-value bugs, regressions, and missing verification in Apache For
 ## Hard Rules
 
 - Do not lead with style nits when there are correctness or verification risks.
+- Do not write code, edit files, apply patches, commit, push, or fix tests from the review subagent.
 - Treat benchmark-shape tricks, payload-specific caches, and methodology changes as real findings.
 - Treat undocumented public API additions, compatibility shims, and one-line wrapper growth as findings when they increase maintenance surface without clear need.
 - Treat protocol or performance claims without verification evidence as incomplete.

.github/workflows/ci.yml

@@ -999,6 +999,10 @@ jobs:
         run: |
           cd dart/packages/fory-test
           dart test
+      - name: Run web tests
+        run: |
+          cd dart/packages/fory
+          dart test -p chrome
       - name: Run code analysis
         run: |
           cd dart/packages/fory-test

dart/packages/fory-test/test/cross_lang_test/xlang_test_main.dart

@@ -244,8 +244,8 @@ void _verifyDecimalCase() {
 
 Uint8List _hashBytes(int low, int high) {
   final buffer = Buffer();
-  buffer.writeInt64(low);
-  buffer.writeInt64(high);
+  buffer.writeInt64(Int64(low));
+  buffer.writeInt64(Int64(high));
   return buffer.toBytes();
 }
 

dart/packages/fory/README.md

@@ -9,12 +9,13 @@ cases.
 ## Features
 
 - Cross-language serialization with the Fory xlang format
+- Dart VM/AOT, Flutter, and web platform support
 - Generated serializers for annotated structs and enums
 - Compatible mode for schema evolution
 - Optional reference tracking for shared and circular object graphs
 - Manual serializers for external types, custom payloads, and unions
-- Explicit xlang value wrappers such as `Int32`, `Uint32`, `Float16`,
-  `Bfloat16`, `Float32`, `LocalDate`, and `Timestamp`, plus `Duration`
+- Explicit xlang value class such as `Int32`, `Int64`, `Uint32`, `Uint64`,
+  `Float16`, `Bfloat16`, `Float32`, `LocalDate`, and `Timestamp`, plus `Duration`
   support
 
 ## Getting Started
@@ -193,13 +194,13 @@ final class PersonSerializer extends Serializer<Person> {
   void write(WriteContext context, Person value) {
     final buffer = context.buffer;
     buffer.writeUtf8(value.name);
-    buffer.writeInt64(value.age);
+    buffer.writeInt64FromInt(value.age);
   }
 
   @override
   Person read(ReadContext context) {
     final buffer = context.buffer;
-    return Person(buffer.readUtf8(), buffer.readInt64());
+    return Person(buffer.readUtf8(), buffer.readInt64AsInt());
   }
 }
 
@@ -222,9 +223,9 @@ void main() {
 
 Dart has no native fixed-width 8/16/32-bit integer, unsigned 64-bit integer,
 or single-precision float types. Fory Dart provides thin wrapper types
-(`Int8`, `Int16`, `Int32`, `Uint8`, `Uint16`, `Uint32`, `Uint64`, `Float16`,
-`Bfloat16`, `Float32`) imported from `package:fory/fory.dart` to represent
-these xlang wire types. For 16-bit floating-point arrays, Dart exposes
+(`Int8`, `Int16`, `Int32`, `Int64`, `Uint8`, `Uint16`, `Uint32`, `Uint64`,
+`Float16`, `Bfloat16`, `Float32`) imported from `package:fory/fory.dart` to
+represent these xlang wire types. For 16-bit floating-point arrays, Dart exposes
 `Float16List` and `Bfloat16List` as contiguous fixed-length buffers.
 
 | Fory xlang type | Dart type                 |
@@ -233,7 +234,7 @@ these xlang wire types. For 16-bit floating-point arrays, Dart exposes
 | int8            | `fory.Int8` (wrapper)     |
 | int16           | `fory.Int16` (wrapper)    |
 | int32           | `fory.Int32` (wrapper)    |
-| int64           | `int`                     |
+| int64           | `int` or `fory.Int64`     |
 | uint8           | `fory.Uint8` (wrapper)    |
 | uint16          | `fory.Uint16` (wrapper)   |
 | uint32          | `fory.Uint32` (wrapper)   |
@@ -257,6 +258,9 @@ these xlang wire types. For 16-bit floating-point arrays, Dart exposes
 | int16_array     | `Int16List`               |
 | int32_array     | `Int32List`               |
 | int64_array     | `Int64List`               |
+| uint16_array    | `Uint16List`              |
+| uint32_array    | `Uint32List`              |
+| uint64_array    | `Uint64List`              |
 | float16_array   | `Float16List`             |
 | bfloat16_array  | `Bfloat16List`            |
 | float32_array   | `Float32List`             |
@@ -276,8 +280,8 @@ The main exported API includes:
   annotations
 - `Int32Type`, `Int64Type`, `Uint32Type`, `Uint64Type` — numeric encoding
   overrides
-- Numeric wrappers: `Int8`, `Int16`, `Int32`, `Uint8`, `Uint16`, `Uint32`,
-  `Uint64`, `Float16`, `Bfloat16`, `Float32`
+- Numeric wrappers: `Int8`, `Int16`, `Int32`, `Int64`, `Uint8`, `Uint16`,
+  `Uint32`, `Uint64`, `Float16`, `Bfloat16`, `Float32`
 - Temporal types: `LocalDate`, `Timestamp`, `Duration`
 
 ## Cross-Language Notes

dart/packages/fory/example/manual_serializer.dart

@@ -23,7 +23,7 @@ final class Person {
   Person(this.name, this.age);
 
   final String name;
-  final int age;
+  final Int64 age;
 }
 
 final class PersonSerializer extends Serializer<Person> {
@@ -52,7 +52,7 @@ void main() {
     typeName: 'Person',
   );
 
-  final person = Person('Ada', 36);
+  final person = Person('Ada', Int64(36));
   final bytes = fory.serialize(person);
   final roundTrip = fory.deserialize<Person>(bytes);
   print(roundTrip.name);

dart/packages/fory/lib/fory.dart

@@ -30,7 +30,7 @@ export 'src/annotation/fory_struct.dart';
 export 'src/annotation/fory_union.dart';
 export 'src/annotation/type_spec.dart';
 export 'src/annotation/numeric_types.dart';
-export 'src/buffer.dart'
+export 'src/memory/buffer.dart'
     hide
         bufferByteData,
         bufferBytes,
@@ -55,6 +55,7 @@ export 'src/types/float16.dart';
 export 'src/types/float32.dart';
 export 'src/types/int16.dart';
 export 'src/types/int32.dart';
+export 'src/types/int64.dart';
 export 'src/types/int8.dart';
 export 'src/types/local_date.dart';
 export 'src/types/timestamp.dart';