@fluidframework/sequence 1.4.0-115997 → 2.0.0-dev-rc.1.0.0.224419

package/README.md

@@ -1,25 +1,48 @@
 # @fluidframework/sequence
 
+<!-- AUTO-GENERATED-CONTENT:START (README_DEPENDENCY_GUIDELINES_SECTION:includeHeading=TRUE) -->
+
+<!-- prettier-ignore-start -->
+<!-- NOTE: This section is automatically generated using @fluid-tools/markdown-magic. Do not update these generated contents directly. -->
+
+## Using Fluid Framework libraries
+
+When taking a dependency on a Fluid Framework library, we recommend using a `^` (caret) version range, such as `^1.3.4`.
+While Fluid Framework libraries may use different ranges with interdependencies between other Fluid Framework libraries,
+library consumers should always prefer `^`.
+
+Note that when depending on a library version of the form `2.0.0-internal.x.y.z`, called the Fluid internal version scheme,
+you must use a `>= <` dependency range (such as `>=2.0.0-internal.x.y.z <2.0.0-internal.w.0.0` where `w` is `x+1`).
+Standard `^` and `~` ranges will not work as expected.
+See the [@fluid-tools/version-tools](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/version-tools/README.md)
+package for more information including tools to convert between version schemes.
+
+<!-- prettier-ignore-end -->
+
+<!-- AUTO-GENERATED-CONTENT:END -->
+
+## Description
+
 The **@fluidframework/sequence** package supports distributed data structures which are list-like.
 Its main export is [SharedString][], a DDS for storing and simultaneously editing a sequence of text.
 
 Note that SharedString is a sequence DDS but it has additional specialized features and behaviors for working with text.
 
 This package historically contained several other sequence-based DDSes, but because they have unintuitive behaviors,
-they are deprecated and being moved to the *experimental* folder.
+they are deprecated and being moved to the _experimental_ folder.
 
-The main reason for this is the lack of *move* semantics within the sequence, which becomes crucial when dealing with sequences of
+The main reason for this is the lack of _move_ semantics within the sequence, which becomes crucial when dealing with sequences of
 complex content.
 For that reason, all of the examples in this README use `SharedString`. However, the APIs discussed are available on the common base class: `SharedSegmentSequence`.
 
-For the remainder of this document, the term *sequence* will refer to this base class.
+For the remainder of this document, the term _sequence_ will refer to this base class.
 
-*Item*s are the individual units that are stored within the sequence (e.g. in a SharedString, the items are characters),
-but regardless of the type of data stored in the sequence, every item in a sequence is at a specific *position* starting
+_Items_ are the individual units that are stored within the sequence (e.g. in a SharedString, the items are characters),
+but regardless of the type of data stored in the sequence, every item in a sequence is at a specific _position_ starting
 at 0, similar to an array. However, sequences differ from arrays in that the positions can move as local and remote
 editors make modifications to the sequence.
 
-As its name suggests, SharedSegmentSequence is composed of *segments*. Segments are the unit that the sequence works
+As its name suggests, SharedSegmentSequence is composed of _segments_. Segments are the unit that the sequence works
 with internally, and contain items within them. Thus, every segment has a length of at least 1 -- that is, it contains
 at least one item -- and segments may be split and merged arbitrarily as the sequence is edited. This means the length
 of the sequence is not the number of segments, but rather the sum of the length of all the segments.
@@ -63,49 +86,45 @@ can be any position in the sequence including 0, to insert at the beginning of t
 sequence, to insert at the end.
 
 ```typescript
-    //   content:
-    // positions:
-
-    // insert text at position 0
-    sharedString.insertText(0, "hi");
-    //   content: hi
-    // positions: 01
-
-    // insert text at the end position
-    sharedString.insertText(
-        sharedString.getLength(),
-        "!");
-    //   content: hi!
-    // positions: 012
-
-    // insert text at position 2
-    sharedString.insertText(
-        2,
-        " world");
-    //   content: hi world!
-    // positions: 012345678
+//   content:
+// positions:
+
+// insert text at position 0
+sharedString.insertText(0, "hi");
+//   content: hi
+// positions: 01
+
+// insert text at the end position
+sharedString.insertText(sharedString.getLength(), "!");
+//   content: hi!
+// positions: 012
+
+// insert text at position 2
+sharedString.insertText(2, " world");
+//   content: hi world!
+// positions: 012345678
 ```
 
 ### Remove
 
-Remove operations take a start and an end position, referred to as a *range*. The start position is inclusive and can be
+Remove operations take a start and an end position, referred to as a _range_. The start position is inclusive and can be
 any position in the sequence from 0 to its `length - 1`. The start position cannot be the length of the sequence like it
 can in insert, because there is nothing at that position. The end position is exclusive and must be greater than the
-start, so it can be any value from 1 to *n* (where *n* is the length of the sequence).
+start, so it can be any value from 1 to _n_ (where _n_ is the length of the sequence).
 
 ```typescript
-    //   content: hi world!
-    // positions: 012345678
-
-    // remove the first 3 characters
-    sharedString.removeRange(0, 3);
-    //   content: world!
-    // positions: 012345
-
-    // remove all the characters
-    sharedString.removeRange(0, sharedString.getLength());
-    //   content:
-    // positions:
+//   content: hi world!
+// positions: 012345678
+
+// remove the first 3 characters
+sharedString.removeRange(0, 3);
+//   content: world!
+// positions: 012345
+
+// remove all the characters
+sharedString.removeRange(0, sharedString.getLength());
+//   content:
+// positions:
 ```
 
 ### Annotate
@@ -117,64 +136,58 @@ also takes a map-like properties object. Each key of the provided properties obj
 specified range. Setting a property key to null will remove that property from the positions in the range.
 
 ```typescript
-    //   content: hi world
-    // positions: 01234567
-
-    let props1 = sharedString.getPropertiesAtPosition(1);
-    let props5 = sharedString.getPropertiesAtPosition(5);
-    // props1 = {}
-    // props5 = {}
-
-    // set property called weight on positions 0 and 1
-    sharedString.annotateRange(0, 2, { weight: 5 });
-    props1 = sharedString.getPropertiesAtPosition(1);
-    props5 = sharedString.getPropertiesAtPosition(5);
-    // props1 = { weight: 5 }
-    // props5 = {}
-
-    // set property called decoration on all positions
-    sharedString.annotateRange(
-        0,
-        sharedString.getLength(),
-        { decoration: "underline" });
-    props1 = sharedString.getPropertiesAtPosition(1);
-    props5 = sharedString.getPropertiesAtPosition(5);
-    // props1 = { weight: 5, decoration: "underline" }
-    // props5 = { decoration: "underline" }
-
-    // remove property called weight on all positions
-    sharedString.annotateRange(
-        0,
-        sharedString.getLength(),
-        { weight: null });
-    props1 = sharedString.getPropertiesAtPosition(1);
-    props5 = sharedString.getPropertiesAtPosition(5);
-    // props1 = { decoration: "underline" }
-    // props5 = { decoration: "underline" }
+//   content: hi world
+// positions: 01234567
+
+let props1 = sharedString.getPropertiesAtPosition(1);
+let props5 = sharedString.getPropertiesAtPosition(5);
+// props1 = {}
+// props5 = {}
+
+// set property called weight on positions 0 and 1
+sharedString.annotateRange(0, 2, { weight: 5 });
+props1 = sharedString.getPropertiesAtPosition(1);
+props5 = sharedString.getPropertiesAtPosition(5);
+// props1 = { weight: 5 }
+// props5 = {}
+
+// set property called decoration on all positions
+sharedString.annotateRange(0, sharedString.getLength(), { decoration: "underline" });
+props1 = sharedString.getPropertiesAtPosition(1);
+props5 = sharedString.getPropertiesAtPosition(5);
+// props1 = { weight: 5, decoration: "underline" }
+// props5 = { decoration: "underline" }
+
+// remove property called weight on all positions
+sharedString.annotateRange(0, sharedString.getLength(), { weight: null });
+props1 = sharedString.getPropertiesAtPosition(1);
+props5 = sharedString.getPropertiesAtPosition(5);
+// props1 = { decoration: "underline" }
+// props5 = { decoration: "underline" }
 ```
 
 ### Sequence delta event
 
-Whenever an operation is performed on a sequence a *sequenceDelta* event will be raised. This event provides the ranges
-affected by the operation, the type of the operation, and the properties that were changes by the operation.
+Whenever an operation is performed on a sequence a _sequenceDelta_ event will be raised. This event provides the ranges
+affected by the operation, the type of the operation, and the properties that were changed by the operation.
 
 ```typescript
 sharedString.on("sequenceDelta", ({ deltaOperation, ranges, isLocal }) => {
-    if (isLocal) {
-        // undo-redo implementations frequently will only concern themselves with local ops: only operations submitted
-        // by the local client should be undoable by the current user
-        addOperationToUndoStack(deltaOperation, ranges);
-    }
+	if (isLocal) {
+		// undo-redo implementations frequently will only concern themselves with local ops: only operations submitted
+		// by the local client should be undoable by the current user
+		addOperationToUndoStack(deltaOperation, ranges);
+	}
 
-    if (deltaOperation === MergeTreeDeltaType.INSERT) {
-        syncInsertSegmentToModel(deltaOperation, ranges);
-    }
+	if (deltaOperation === MergeTreeDeltaType.INSERT) {
+		syncInsertSegmentToModel(deltaOperation, ranges);
+	}
 
-    // realistic app code would likely handle the other deltaOperation types as well here.
+	// realistic app code would likely handle the other deltaOperation types as well here.
 });
 ```
 
-Internally, the sequence package depends on `@fluidframework/merge-tree`, and also raises `MergeTreeMaintenance` events on that tree as *maintenance* events.
+Internally, the sequence package depends on `@fluidframework/merge-tree`, and also raises `MergeTreeMaintenance` events on that tree as _maintenance_ events.
 These events don't correspond directly to APIs invoked on a sequence DDS, but may be useful for advanced users.
 
 Both sequenceDelta and maintenance events are commonly used to synchronize or invalidate a view an application might have over a backing sequence DDS.
@@ -196,7 +209,7 @@ Consider a sequence like this:
 ```
 
 Now two users simultaneously insert characters at the end of the sequence. One inserts `k` and the other inserts a `c`.
-This is an *insert conflict*. The basic strategy for insert conflict resolution in the sequence is to merge *far*,
+This is an _insert conflict_. The basic strategy for insert conflict resolution in the sequence is to merge _far_,
 closer to the end of the sequence.
 
 This merge strategy is possible because of a fundamental property of the Fluid Framework, which is guaranteed ordering.
@@ -278,53 +291,53 @@ determine the value.
 
 ## Local references
 
-Sequences support addition and manipulation of *local references* to locally track positions in the sequence over time.
+Sequences support addition and manipulation of _local references_ to locally track positions in the sequence over time.
 As the name suggests, any created references will only exist locally; other clients will not see them.
 This can be used to implement user interactions with sequence data in a way that is robust to concurrent editing.
 For example, consider a text editor which tracks a user's cursor state.
 The application can store a local reference to the character after the cursor position:
 
 ```typescript
-    //   content: hi world!
-    // positions: 012345678
-    const { segment, offset } = sharedString.getContainingSegment(5)
-    const cursor = sharedString.createLocalReferencePosition(
-        segment,
-        offset,
-        ReferenceType.SlideOnRemove,
-        /* any additional properties */ { cursorColor: 'blue' }
-    );
-
-    //    cursor:      x
-    //   content: hi world!
-    // positions: 012345678
-
-    // ... in some view code, retrieve the position of the local reference for rendering:
-    const pos = sharedString.localReferencePositionToPosition(cursor); // 5
-
-    // meanwhile, some other client submits an edit which gets applied to our string:
-    otherSharedString.replaceText(1, 2, "ello");
-
-    // The local sharedString state will now look like this:
-    //    cursor:         x
-    //   content: hello world!
-    // positions: 0123456789AB (hex)
-
-    // ... in some view code, retrieve the position of the local reference for rendering:
-    const pos = sharedString.localReferencePositionToPosition(cursor); // 8
+//   content: hi world!
+// positions: 012345678
+const { segment, offset } = sharedString.getContainingSegment(5);
+const cursor = sharedString.createLocalReferencePosition(
+	segment,
+	offset,
+	ReferenceType.SlideOnRemove,
+	/* any additional properties */ { cursorColor: "blue" },
+);
+
+//    cursor:      x
+//   content: hi world!
+// positions: 012345678
+
+// ... in some view code, retrieve the position of the local reference for rendering:
+const pos = sharedString.localReferencePositionToPosition(cursor); // 5
+
+// meanwhile, some other client submits an edit which gets applied to our string:
+otherSharedString.replaceText(1, 2, "ello");
+
+// The local sharedString state will now look like this:
+//    cursor:         x
+//   content: hello world!
+// positions: 0123456789AB (hex)
+
+// ... in some view code, retrieve the position of the local reference for rendering:
+const pos = sharedString.localReferencePositionToPosition(cursor); // 8
 ```
 
 Notice that even though another client concurrently edited the string, the local reference representing the cursor is still in the correct location with no further work for the API consumer.
 The `ReferenceType.SlideOnRemove` parameter changes what happens when the segment that reference is associated with is removed.
-`SlideOnRemove` instructs the sequence to attempt to *slide* the reference to the start of the next furthest segment, or if no such segment exists (i.e. the end of the string has been removed), the end of the next nearest one.
+`SlideOnRemove` instructs the sequence to attempt to _slide_ the reference to the start of the next furthest segment, or if no such segment exists (i.e. the end of the string has been removed), the end of the next nearest one.
 
 The [webflow](https://github.com/microsoft/FluidFramework/blob/main/examples/data-objects/webflow/src/editor/caret.ts) example demonstrates this idea in more detail.
 
-Unlike segments, it *is* safe to persist local references in auxiliary data structures, such as an undo-redo stack.
+Unlike segments, it _is_ safe to persist local references in auxiliary data structures, such as an undo-redo stack.
 
 ## Interval collections
 
-Sequences support creation of *interval collections*, an auxiliary collection of intervals associated with positions in the sequence.
+Sequences support creation of _interval collections_, an auxiliary collection of intervals associated with positions in the sequence.
 Like segments, intervals support adding arbitrary properties, including handles (references) to other DDSes.
 The interval collection implementation uses local references, and so benefits from all of the robustness to concurrent editing
 described in the previous section.
@@ -332,98 +345,266 @@ Unlike local references, operations on interval collections are sent to all clie
 This makes them suitable for implementing features like comment threads on a text-based documents.
 The following example illustrates these properties and highlights the major APIs supported by IntervalCollection.
 
+```typescript
+//   content: hi world!
+// positions: 012345678
+
+const comments = sharedString.getIntervalCollection("comments");
+const comment = comments.add(
+	3, // (inclusive)
+	8, // (exclusive): references "world"
+	IntervalType.SlideOnRemove,
+	{
+		creator: "my-user-id",
+		handle: myCommentThreadDDS.handle,
+	},
+);
+//   content: hi world!
+// positions: 012345678
+//   comment:    [    )
+
+// Interval collection supports iterating over all intervals via Symbol.iterator or `.map()`:
+const allIntervalsInCollection = Array.from(comments);
+const allProperties = comments.map((comment) => comment.properties);
+// or iterating over intervals overlapping a region:
+const intervalsOverlappingFirstHalf = comments.findOverlappingIntervals(0, 4);
+
+// Interval endpoints are LocalReferencePositions, so all APIs in the above section can be used:
+const startPosition = sharedString.localReferencePositionToPosition(comment.start); // returns 3
+const endPosition = sharedString.localReferencePositionToPosition(comment.end); // returns 8: note this is exclusive!
+
+// Intervals can be modified:
+comments.change(comment.getIntervalId(), 0, 1);
+//   content: hi world!
+// positions: 012345678
+//   comment: [)
+
+// their properties can be changed:
+comments.changeProperties(comment.getIntervalId(), { status: "resolved" });
+// comment.properties === { creator: 'my-user-id', handle: <some DDS handle object>, status: "resolved" }
+
+// and they can be removed:
+comments.removeIntervalById(comment.getIntervalId());
+```
+
+### Interval stickiness
+
+"Stickiness" refers to the behavior of intervals when text is inserted on either
+side of the interval. A "sticky" interval is one which expands to include text
+inserted directly adjacent to it.
+
+A "start sticky" interval is one which expands only to include text inserted to
+the start of it. An "end sticky" interval is the same, but with regard to text
+inserted adjacent to the end.
+
+For example, let's look at the string "abc". If we have an interval on the
+character "b", what happens when we insert text on either side of it? In the
+below diagrams, we represent an interval by putting a caret directly underneath
+the characters it contains.
+
+#### Example
+
+##### Original string
 
 ```typescript
-    //   content: hi world!
-    // positions: 012345678
+abc
+ ^
+```
 
-    const comments = sharedString.getIntervalCollection("comments");
-    const comment = comments.add(
-        3,
-        7, // (inclusive range): references "world"
-        IntervalType.SlideOnRemove,
-        {
-            creator: 'my-user-id',
-            handle: myCommentThreadDDS.handle
-        }
-    );
-    //   content: hi world!
-    // positions: 012345678
-    //   comment:    [   ]
+##### No stickiness
 
-    // Interval collection supports iterating over all intervals via Symbol.iterator or `.map()`:
-    const allIntervalsInCollection = Array.from(comments);
-    const allProperties = comments.map((comment) => comment.properties);
-    // or iterating over intervals overlapping a region:
-    const intervalsOverlappingFirstHalf = comments.findOverlappingIntervals(0, 4);
+```typescript
+aXbYc
+  ^
+```
 
-    // Interval endpoints are LocalReferencePositions, so all APIs in the above section can be used:
-    const startPosition = sharedString.localReferencePositionToPosition(comment.start);
-    const endPosition = sharedString.localReferencePositionToPosition(comment.end);
+The interval does not expand to include the newly inserted characters `X` and `Y`.
 
-    // Intervals can be modified:
-    comments.change(comment.getIntervalId(), 0, 1);
-    //   content: hi world!
-    // positions: 012345678
-    //   comment: []
+##### Start stickiness
 
-    // their properties can be changed:
-    comments.changeProperties(comment.getIntervalId(), { status: "resolved" });
-    // comment.properties === { creator: 'my-user-id', handle: <some DDS handle object>, status: "resolved" }
+```typescript
+aXbYc
+ ^^
+```
+
+##### End stickiness
 
-    // and they can be removed:
-    comments.removeIntervalById(comment.getIntervalId());
+```typescript
+aXbYc
+  ^^
 ```
 
+##### Full stickiness
+
+```typescript
+aXbYc
+ ^^^
+```
+
+#### Concrete Implementation
+
+The above is a description of the abstract semantics of the concept of stickiness.
+In practice, this is implemented using the concept of "sides."
+
+For a given sequence of N characters, there are 2N + 2 positions which can be
+referenced: the position immediately before and after each character, and two
+special endpoint segments denoting the position before and after the start and
+end of the sequence respectively.
+
+By placing the endpoints of an interval either before or after a character, it
+is possible to make the endpoints inclusive or exclusive. An exclusive endpoint
+in a given direction implies stickiness in that direction. Whether an endpoint
+is inclusive or exclusive depends on both the Side and if it is the start or the
+end.
+
+Given the string "ABCD":
+
+```typescript
+// Refers to "BC". If any content is inserted before B or after C, this
+// interval will include that content
+//
+// Picture:
+// {start} - A[- B - C -]D - {end}
+// {start} - A - B - C - D - {end}
+collection.add(
+	{ pos: 0, side: Side.After },
+	{ pos: 3, side: Side.Before },
+	IntervalType.SlideOnRemove,
+);
+// Equivalent to specifying the same positions and Side.Before.
+// Refers to "ABC". Content inserted after C will be included in the
+// interval, but content inserted before A will not.
+// {start} -[A - B - C -]D - {end}
+// {start} - A - B - C - D - {end}
+collection.add(0, 3, IntervalType.SlideOnRemove);
+```
+
+In the case of the first interval shown, if text is deleted,
+
+```typescript
+// Delete the character "B"
+string.removeRange(1, 2);
+```
+
+The start point of the interval will slide to the position immediately before
+"C", and the same will be true.
+
+```typescript
+{start} - A[- C -]D - {end}
+```
+
+In this case, text inserted immediately before "C" would be included in the
+interval.
+
+```typescript
+string.insertText(1, "EFG");
+```
+
+With the string now being,
+
+```typescript
+{start} - A[- E - F - G - C -]D - {end}
+```
+
+Note that the endpoint continues to remain with the associated character, except
+when the character is removed. When content containing endpoints is removed,
+`After` endpoints move backward and `Before` endpoints move forward to maintain their
+side value and inclusive/exclusive behavior.
+
+<!-- This line ends the content that is copied to the sequences.md README -->
+
+## SharedString
+
+SharedString is a specialized data structure for handling collaborative text. It is based on a more general
+Sequence data structure but has additional features that make working with text easier.
+
+In addition to text, a SharedString can also contain markers.
+Markers can be used to store metadata at positions within the text, like a reference to an image or Fluid object that should be rendered with the text.
+
+Both markers and text are stored as segments in the SharedString.
+Text segments will be split and merged when modifications are made to the SharedString and will therefore have variable length
+matching the length of the text content they contain.
+Marker segments are never split or merged, and always have a length of 1.
+
+The length of the SharedString will be the combined length of all the text and marker segments.
+Just like with other sequences, when talking about positions in a SharedString we use the terms near and far.
+The nearest position in a SharedString is 0, and the farthest position is its length.
+When comparing two positions the nearer positions is closer to 0, and the farther position is closer to the length.
+
 ### Intervals vs. markers
 
-Interval endpoints and markers both implement *ReferencePosition* and seem to serve a similar function so it's not obvious how they differ and why you would choose one or the other.
+Interval endpoints and markers both implement _ReferencePosition_ and seem to serve a similar function so it's not obvious how they differ and why you would choose one or the other.
 
 Using the interval collection API has two main benefits:
 
 1. Efficient spatial querying
+
     - Interval collections support iterating all intervals overlapping the region `[start, end]` in `O(log N) + O(overlap size)` time, where `N` is the total number of intervals in the collection.
-    This may be critical for applications that display only a small view of the document contents.
-    On the other hand, using markers to implement intervals would require a linear scan from the start or end of the sequence to determine which intervals overlap.
+      This may be critical for applications that display only a small view of the document contents.
+      On the other hand, using markers to implement intervals would require a linear scan from the start or end of the sequence to determine which intervals overlap.
 
 2. More ergonomic modification APIs
     - Interval collections natively support a modify operation on the intervals, which allows moving the endpoints of the interval to a different place in the sequence.
-    This operation is atomic, whereas with markers one would have to submit a delete operation for the existing position and an insert for the new one.
-    In order to achieve the same atomicity, those operations would need to leverage the `SharedSegmentSequence.groupOperation` API,
-    which is less user-friendly.
-    If the ops were submitted using standard insert and delete APIs instead, there would be some potential for data loss if the delete
-    operation ended up acknowledged by the server but the insert operation did not.
+      This operation is atomic, whereas with markers one would have to submit a delete operation for the existing position and an insert for the new one.
+      In order to achieve the same atomicity, those operations would need to leverage the `SharedSegmentSequence.groupOperation` API,
+      which is less user-friendly.
+      If the ops were submitted using standard insert and delete APIs instead, there would be some potential for data loss if the delete
+      operation ended up acknowledged by the server but the insert operation did not.
 
-## SharedString
+### Attribution
 
-The SharedString is a specialized data structure for handling collaborative text. It is based on a more general
-Sequence data structure but has additional features that make working with text easier.
+**Important: Attribution is currently in alpha: expect breaking changes in minor releases as we get feedback on the API shape.**
+
+SharedString supports storing information attributing each character position to the user who inserted it and the time at which that insertion happened.
+This functionality is off by default.
+To enable this functionality, first ensure that all clients are created with an attribution policy factory in the loader settings:
 
-In addition to text, a SharedString can also contain markers. Markers can be used to store metadata at positions within
-the text, like the details of an image or Fluid object that should be rendered with the text.
+```typescript
+import { createInsertOnlyAttributionPolicy } from "@fluidframework/merge-tree";
+// Use these options in the IContainerContext used to instantiate your container runtime.
+const options: ILoaderOptions = {
+	attribution: {
+		policyFactory: createInsertOnlyAttributionPolicy,
+	},
+};
+```
+
+This ensures that the client is able to load existing documents containing attribution information,
+and specifies which kinds of operations should be attributed at the SharedString level (currently, only insertions).
+The stored attribution information can be found on the `attribution` field of the SharedString's segments.
 
-Both markers and text are stored as segments in the SharedString. Text segments will be split and merged when
-modifications are made to the SharedString and will therefore have variable length matching the length of the text
-content they contain. Marker segments are never split or merged, and always have a length of 1.
+Next, enable the `"Fluid.Attribution.EnableOnNewFile"` config flag to start tracking attribution information for new files.
+
+```typescript
+const { segment, offset } = sharedString.getContainingSegment(5);
+const key = segment.attribution.getAtOffset(offset);
+// `key` can be used with an IAttributor to recover user/timestamp info about the insertion of the character at offset 5.
+// See the @fluid-experimental/attributor package for more details.
+```
 
-The length of the SharedString will be the combined length of all the text and marker segments. Just like with other
-sequences, when talking about positions in a SharedString we use the terms near and far. The nearest position in a
-SharedString is 0, and the farthest position is its length. When comparing two positions the nearer positions is closer
-to 0, and the farther position is closer to the length.
+For further reading on attribution, see the [@fluid-experimental/attributor README](https://github.com/microsoft/FluidFramework/blob/main/packages/framework/attributor/README.md).
+
+There are plans to make attribution policies more flexible, for example tracking attribution of property changes separately from segment insertion.
+
+<!-- This line begins the content that is copied to the string.md README -->
 
 ### Examples
 
-- Rich Text Editor Implementations
-  - [webflow](https://github.com/microsoft/FluidFramework/tree/main/examples/data-objects/webflow)
-  - [flowView](https://github.com/microsoft/FluidFramework/blob/main/examples/data-objects/shared-text/src/client-ui-lib/controls/flowView.ts)
+-   Rich Text Editor Implementations
+
+    -   [webflow](https://github.com/microsoft/FluidFramework/tree/main/examples/data-objects/webflow)
+    -   [flowView](https://github.com/microsoft/FluidFramework/blob/main/examples/data-objects/shared-text/src/client-ui-lib/controls/flowView.ts)
+
+-   Integrations with Open Source Rich Text Editors
+
+    -   [prosemirror](https://github.com/microsoft/FluidFramework/tree/main/examples/data-objects/prosemirror)
+    -   [smde](https://github.com/microsoft/FluidFramework/tree/main/examples/data-objects/smde)
 
-- Integrations with Open Source Rich Text Editors
-  - [prosemirror](https://github.com/microsoft/FluidFramework/tree/main/examples/data-objects/prosemirror)
-  - [smde](https://github.com/microsoft/FluidFramework/tree/main/examples/data-objects/smde)
+-   Plain Text Editor Implementations
+    -   [collaborativeTextArea](https://github.com/microsoft/FluidFramework/blob/main/experimental/framework/react-inputs/src/CollaborativeTextArea.tsx)
+    -   [collaborativeInput](https://github.com/microsoft/FluidFramework/blob/main/experimental/framework/react-inputs/src/CollaborativeInput.tsx)
 
-- Plain Text Editor Implementations
-  - [collaborativeTextArea](https://github.com/microsoft/FluidFramework/blob/main/experimental/framework/react-inputs/src/CollaborativeTextArea.tsx)
-  - [collaborativeInput](https://github.com/microsoft/FluidFramework/blob/main/experimental/framework/react-inputs/src/CollaborativeInput.tsx)
+<!-- This line ends the content that is copied to the string.md README -->
 
-[SharedMap]: https://fluidframework.com/docs/data-structures/map/
-[SharedString]: https://github.com/microsoft/FluidFramework/blob/main/packages/dds/sequence/src/sharedString.ts
+[sharedmap]: https://fluidframework.com/docs/data-structures/map/
+[sharedstring]: https://github.com/microsoft/FluidFramework/blob/main/packages/dds/sequence/src/sharedString.ts