Jenn

This commit introduces a **new API feature** to the **`@fluidframework/tree` package**, enhancing the **`Simple Tree` schema definition** by allowing default values for fields. The new `withDefault` and `withDefaultRecursive` APIs in `SchemaFactoryAlpha` enable developers to specify defaults, making fields optional during object construction even when marked as required in the schema. This significantly improves developer ergonomics and schema flexibility by reducing boilerplate during object instantiation. The change impacts schema definition, type inference for `InsertableObjectFromSchemaRecord`, and object creation within the `Simple Tree` subsystem.

This commit **enhances the test suite** for the **`tree` DDS** by introducing **new performance and summary size benchmarks** specifically for **incremental summarization**. It adds comprehensive scenarios to measure the overhead and efficiency of the `forest summarizer`, including cases with no changes and partial changes, and refactors existing test utilities for better reusability. This **test infrastructure improvement** provides crucial data for identifying performance regressions and optimizing the incremental summary process within the `tree` module.

This commit **fixes a bug** in the **`tree-agent`** package where **Fluid handles were not correctly rendered** or included in generated prompts. It introduces new logic within `prompt.ts` to **detect Fluid handles** in the schema and ensures their type definitions are properly included, while `renderSchemaTypeScript.ts` is updated to correctly display these types. This **enhances the accuracy** of the tree agent's schema representation and prompt generation by ensuring all data types, including Fluid handles, are fully supported. Extensive **test updates** confirm the correct inclusion and rendering of these handle types.

This commit provides **documentation improvement** for the **`tree` data structure's schema evolution guides**. It **adds and updates internal links** to enhance navigation and clarity within the documentation. Specifically, the `allowed-types-rollout.mdx` document now includes more precise links to the `schemafactorybeta-class` documentation, incorporating specific anchor tags for the `staged-property`. Additionally, the `index.mdx` page gains a new link to the 'Adding a new allowed type' guide and updates a placeholder link to correctly point to the `allowed-types-rollout.mdx` page, improving the overall user experience for understanding **schema evolution** and **staged property types**.

This commit provides a **minor fix** to the **documentation** for the `Tree` data structure's **recommended initialization flow**. It **removes explicit type annotations** from variable declarations within the example code snippets in `docs/docs/data-structures/tree/recommended-init-flow.mdx`. This **documentation improvement** enhances the clarity and conciseness of the examples, making the initialization process easier for users to understand and adopt.

This commit **enhances documentation** for the **SharedTree** data structure by introducing a new guide on its recommended initialization flow. A new document, `docs/docs/data-structures/tree/recommended-init-flow.mdx`, is added to provide clear instructions for safely initializing `SharedTree` and avoiding common pitfalls or race conditions. Concurrently, the existing `docs/docs/start/tree-start.mdx` Quick Start guide is updated with a warning, directing users to this new resource for best practices. This **documentation improvement** aims to prevent common integration issues and ensure developers correctly set up `SharedTree` instances.

This commit **improves documentation** for the `tree` data structure by introducing a new guide on rolling out new allowed types using the `staged` alpha API. It **refactors** existing documentation, specifically within `docs/docs/data-structures/tree/schema-evolution/`, to remove redundant content and link to this comprehensive new guide. Additionally, JSDoc comments for the `staged` property in `packages/dds/tree/src/simple-tree/api/schemaFactoryAlpha.ts` are refined to direct users to the external documentation. This change centralizes usage instructions for **schema evolution** with the `staged` API, making it easier for developers to understand and implement new type rollouts.

This commit **improves and centralizes the documentation** for **schema evolution within the `SharedTree` data structure**. It introduces a new landing page (`docs/data-structures/tree/schema-evolution/index.mdx`) covering general concepts like stored vs. view schema and compatibility, alongside a dedicated page (`docs/data-structures/tree/schema-evolution/types-of-changes.mdx`) detailing various types of schema changes. This **documentation refactoring** consolidates previously scattered information, making it easier for developers to understand and implement **`SharedTree` schema updates**. The work enhances the overall **developer experience** by providing a clearer, more comprehensive guide on managing schema changes.

This commit **refactors** the **schema compatibility testing logic** within the `simple-tree` and `shared-tree` packages. The `SchemaCompatibilityTester` now directly compares view schemas against stored schemas, moving away from an intermediate conversion step. This change, which introduces a new **`discrepancies` module** to centralize comparison logic, is a **foundational improvement** necessary for future support of **schema annotations**. It directly impacts the **schema evolution and schematization mechanisms**, ensuring more accurate and detailed validation of schema compatibility.

This commit introduces **new capabilities** for the **Simple Tree API** by adding `AnnotatedAllowedType` and `NormalizedAnnotatedAllowedTypes` to represent schema annotations during traversal. It **fixes** the `walkAllowedTypes` and `walkNodeSchema` functions within the `packages/dds/tree` package, ensuring they correctly utilize these new annotated types instead of the older `childTypes` API. This required extensive **refactoring** across schema definitions, context management, and various node kinds like `arraySchema` and `objectSchema` to incorporate `childAnnotatedAllowedTypes`. The change improves the accuracy of schema traversal by making annotations available, which is vital for features that depend on detailed schema information.

This commit introduces the **new capability** to define **annotated `AllowedTypes`** within schemas in the **`packages/dds/tree`** module, enhancing the flexibility of schema definitions. It provides new types and utilities for creating, handling, and unannotating these enriched schema elements. The **`SchemaFactoryAlpha`** APIs have been updated to leverage this feature, allowing for more expressive and metadata-rich schema creation. This change includes a **breaking change** for existing alpha API users, as `SchemaFactoryAlpha.object` has been renamed to `objectAlpha`.

This commit introduces a **new capability** within the **tree data structure** to robustly track **detached nodes** by storing `DetachedNodeId`s directly on `AnchorNode`s within the `AnchorSet`. It defines a new `DetachedUpPath` type and modifies the `DeltaVisitor` interface to pass these IDs during detach and replace operations, ensuring that `AnchorSet` can maintain stable references to nodes even when they are detached. This change impacts core **tree traversal and delta application logic**, requiring updates to `ChunkedForest` and `ObjectForest` implementations. It also involves significant **refactoring** of path types, such as `NormalizedUpPath` and `NormalizedFieldUpPath`, across various feature libraries and tests to accommodate the new detached node identification. The enhancement improves the precision and stability of node referencing, especially for nodes that are temporarily removed from the tree.

This commit performs a **refactoring** within the **`tree`** package's core **`visitorUtils`** to enhance code quality and type safety. It specifically cleans up the utility for creating `AnnouncedVisitor` instances by modifying the parameter type of the `createAnnouncedVisitor` function. The parameter now leverages `Partial<AnnouncedVisitor>`, which significantly improves the type definition and conciseness of visitor creation. This change streamlines the implementation and maintenance of visitor patterns within the **`tree`** subsystem, making the code more robust and easier to understand.

This commit performs a **significant refactoring** by **removing the unused `PathVisitor` infrastructure** and its related `AnnouncedVisitor` functions from the **`@fluidframework/tree` package**. This cleanup primarily targets the **`AnchorSet` core component**, where `PathVisitor` and `AnnouncedVisitor` types and logic are removed, and also updates `editableForest.ts`, `treeEvents.ts`, and `treeCheckout.ts` to remove redundant arguments from `combineVisitors` calls and update the `subtreeChanging` event signature. The change **reduces code complexity and maintenance overhead** by eliminating dead code that supported previously removed functionality, with **no functional alterations or impact on external APIs**.

This commit performs a **refactoring** within the **`simple-tree` DDS package** to enhance the clarity and accuracy of internal tree node mapping mechanisms. It **renames an internal weak map** from `mapTreeNodeToProxy` to `unhydratedFlexTreeNodeToTreeNodeInternal`, better reflecting its role in mapping unhydrated flex tree nodes to their corresponding tree nodes. Concurrently, the helper function `tryGetTreeNodeFromMapNode` is removed, with its functionality replaced by direct access to the renamed map, thereby streamlining the **tree node retrieval logic**. This cleanup primarily affects core files like `treeNodeKernel.ts`, `getOrCreateNode.ts`, and `proxies.ts`, improving the maintainability of the **tree node management subsystem**.

This commit **enhances error reporting** within the **`tree`** package's cursor utilities. It **replaces a generic assertion** in the `enterNode` function, located in `packages/dds/tree/src/feature-libraries/treeCursorUtils.ts`, with a more specific `UsageError`. This **diagnostic improvement** provides a significantly more helpful message when a child node cannot be found at a particular index, including instructions to check the node's status. Consequently, developers using the **`tree`** package will receive clearer, more actionable feedback, making it easier to debug issues related to tree navigation.

This commit **refactors** the **delta data model** within the **`@fluidframework/tree`** package by moving `global` and `rename` effects from nested `FieldChanges` into the **delta root object**. This **internal API change** simplifies the delta structure, introducing a new `FieldChangeDelta` interface for field-level changes. Consequently, all delta construction, processing, and testing logic across `core/tree` and `feature-libraries/modular-schema` have been updated to align with this new, flattened representation. This ensures consistency and improved clarity in how tree modifications are represented and applied, impacting `delta` generation, visiting, and serialization.

This commit **enhances the documentation** for the **tree data structure** by adding crucial internal links to its main page. Specifically, it updates `docs/docs/data-structures/tree/index.mdx` to include navigation to the 'Events', 'Transactions', and 'Undo Redo Support' sections. This **documentation improvement** makes the tree's feature set more discoverable and the overall documentation more navigable for users.