@fluidframework/tree 2.113.1 → 2.115.0

package/src/simple-tree/node-kinds/array/arrayNode.ts

@@ -3,10 +3,10 @@
  * Licensed under the MIT License.
  */
 
-import { Lazy, oob, fail, assert } from "@fluidframework/core-utils/internal";
+import { Lazy, oob, fail, assert, clamp } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import { EmptyKey, ObjectNodeStoredSchema } from "../../../core/index.js";
+import { EmptyKey, ObjectNodeStoredSchema, type DeltaMark } from "../../../core/index.js";
 import type {
 	FlexibleFieldContent,
 	FlexTreeNode,
@@ -23,7 +23,7 @@ import type { NodeSchemaOptionsAlpha, System_Unsafe } from "../../api/index.js";
 import {
 	CompatibilityLevel,
 	type WithType,
-	// eslint-disable-next-line import-x/no-deprecated
+	// eslint-disable-next-line import-x/no-deprecated -- Required to implement the deprecated typeNameSymbol API.
 	typeNameSymbol,
 	NodeKind,
 	type TreeNode,
@@ -158,6 +158,11 @@ export interface TreeArrayNode<
 	 * Removes the item at the specified location.
 	 * @param index - The index at which to remove the item.
 	 * @throws Throws if `index` is not in the range [0, `array.length`).
+	 * @remarks
+	 * The item to remove is determined when this method is called, not when the resulting edit is sequenced.
+	 * This means that, once the edit is sequenced, the item being removed may no longer be at `index`,
+	 * and may in fact no longer be in this array at all (for example, if a concurrent edit moved it to another array).
+	 * This operation removes that item from wherever it then resides.
 	 */
 	removeAt(index: number): void;
 
@@ -534,12 +539,22 @@ export interface TreeArrayNodeAlpha<
 	/**
 	 * Removes the last item from the array and returns it.
 	 * @returns The removed item, or `undefined` if the array is empty (in which case the array is not modified).
+	 * @remarks
+	 * Equivalent to `removeAt(array.length - 1)`, additionally returning the removed item:
+	 * see {@link (TreeArrayNode:interface).removeAt} for details, including merge semantics with concurrent edits.
+	 * In particular, the item removed is the one that is last at the time this method is called,
+	 * not the one that is last at the time the resulting edit is sequenced.
 	 */
 	pop(): T | undefined;
 
 	/**
 	 * Removes the first item from the array and returns it.
 	 * @returns The removed item, or `undefined` if the array is empty (in which case the array is not modified).
+	 * @remarks
+	 * Equivalent to `removeAt(0)`, additionally returning the removed item:
+	 * see {@link (TreeArrayNode:interface).removeAt} for details, including merge semantics with concurrent edits.
+	 * In particular, the item removed is the one that is first at the time this method is called,
+	 * not the one that is first at the time the resulting edit is sequenced.
 	 */
 	shift(): T | undefined;
 
@@ -550,8 +565,10 @@ export interface TreeArrayNodeAlpha<
 	 * @remarks
 	 * Unlike `Array.prototype.unshift`, this method does not return the new length of the array.
 	 *
-	 * Equivalent to `insertAt(0, ...value)`:
-	 * see {@link (TreeArrayNode:interface).insertAt} for details, including merge semantics with concurrent edits.
+	 * All items inserted by a single call to this method are inserted consecutively.
+	 * The order of the inserted items relative to other concurrently inserted items is fully specified:
+	 * Concurrently unshifting `[A, B]` and `[X, Y]` will yield `[A, B, X, Y]` if the edit unshifting `[A, B]`
+	 * is sequenced after the edit unshifting `[X, Y]`.
 	 */
 	unshift(...value: readonly (TNew | IterableTreeArrayContent<TNew>)[]): void;
 
@@ -563,6 +580,8 @@ export interface TreeArrayNodeAlpha<
 	 * Must be a non-negative integer no greater than the number of items from `start` to the end of the array.
 	 * @param items - The item(s) to insert at `start`.
 	 * @returns An array containing the item(s) that were removed.
+	 * @remarks
+	 * See {@link (TreeArrayNode:interface).insertAt} for the merge semantics of the inserted items.
 	 */
 	splice(
 		start: number,
@@ -1515,7 +1534,7 @@ export function arraySchema<
 		public static readonly persistedMetadata: JsonCompatibleReadOnlyObject | undefined =
 			persistedMetadata;
 
-		// eslint-disable-next-line import-x/no-deprecated
+		// eslint-disable-next-line import-x/no-deprecated -- Required to implement the deprecated typeNameSymbol API.
 		public get [typeNameSymbol](): TName {
 			return identifier;
 		}
@@ -1649,11 +1668,21 @@ export interface ArrayPlaceAnchor {
 	 * The current index within the array that this anchor refers to.
 	 * @remarks
 	 * This value is updated as the array is edited in a way that depends on the specific anchor implementation.
-	 * This index may take on a value from 0 to the length of the array (inclusive).
+	 * This index is a value from 0 to the current length of the array (inclusive).
 	 * If used as the index to insert content into the array, this means it can point to any location in the array,
 	 * including just after the last child.
+	 * @throws A {@link @fluidframework/telemetry-utils#UsageError} if the anchor has been {@link ArrayPlaceAnchor.dispose | disposed}.
 	 */
 	get index(): number;
+
+	/**
+	 * Stop tracking this anchor and release any resources it holds.
+	 * @remarks
+	 * Call this when the anchor is no longer needed (for example when a tracked cursor position is discarded).
+	 * Interacting with an anchor (including reading its properties) after it has been disposed is invalid and will throw.
+	 * Calling `dispose` more than once has no effect.
+	 */
+	dispose(): void;
 }
 
 /**
@@ -1671,9 +1700,29 @@ export interface ArrayPlaceAnchor {
  * This is intended to track a location that might be used for an insertion point (for example in a text editor): future changes to its details should
  * make it behave better for such uses.
  *
- * The current implementation is known to behave particularly poorly if the child which was at the original anchor point's index is removed
- * (jumps to the end of the array): this behavior is subject to change.
+ * In rare cases the tracked index cannot be updated precisely and the anchor falls back to best-effort behavior:
+ * it keeps reporting a valid in-bounds index, but that index may no longer correspond to the same logical position
+ * as before the change (this can happen when an incremental delta is unavailable for a change, such as during a
+ * schema change). Consumers that require an accurate position across such changes should re-derive it from their
+ * own state rather than relying solely on this anchor.
  * @privateRemarks
+ * The index is maintained incrementally from the shallow (insert/remove) delta delivered by the array node's
+ * `childrenChangedAfterBatch` event: inserts and removes before the anchor point shift it, while edits after it
+ * (or a removal of the span it sits between) leave it in place. This keeps the anchor pinned to the gap between
+ * children even when the child originally at its index is removed.
+ *
+ * The best-effort behavior noted in the public remarks is the no-delta path: when the composed delta is unavailable
+ * (see {@link NodeChangedDataDelta.delta}), the exact shift is unknown so the index is only clamped back into range.
+ * This is intentionally weak rather than reintroducing a per-edit O(n) snapshot of the array to diff old-vs-new
+ * (which would defeat the point of delta-based tracking) for a case that is rare and, for this alpha API, acceptable
+ * to degrade. A stronger fallback could instead let a consumer that already maintains the array contents re-seed the
+ * anchor's position on this path, so it lives with the consumer that has the data instead of being duplicated here.
+ *
+ * TODO: The no-delta case above is one of several places whose behavior is limited by changes for which a composed
+ * delta cannot be produced (see {@link NodeChangedDataDelta.delta}). The underlying eventing limitation should be
+ * fixed so a delta is always available; when adding new code constrained by it, note it here (or track it centrally)
+ * so the full set of affected call sites is known and can be prioritized.
+ *
  * When stabilized, this should probably become a method on {@link (TreeArrayNode:interface)}.
  * Future versions of this should use rebaser / changeset logic to do a better job of tracking a location across removals or reinsertion.
  * How this would work, especially for unhydrated nodes is not yet clear.
@@ -1683,17 +1732,82 @@ export function createArrayInsertionAnchor(
 	node: TreeArrayNode,
 	currentIndex: number,
 ): ArrayPlaceAnchor {
+	// An out-of-range or non-integer index is a usage error. An index equal to the array length is valid
+	// (it points just past the last child).
 	const field = getInnerNode(node).getBoxed(EmptyKey);
-	const child = field.boxedAt(currentIndex);
+	validateIndex(currentIndex, field, "createArrayInsertionAnchor", /* allowOnePastEnd */ true);
+	let trackedIndex = currentIndex;
+
+	const kernel = getKernel(node);
+	let off: (() => void) | undefined = kernel.events.on(
+		"childrenChangedAfterBatch",
+		({ fieldMarks }) => {
+			const marks = fieldMarks.get(EmptyKey);
+			// This event fires after the change is applied, so the field reflects the post-edit length.
+			const length = getInnerNode(node).getBoxed(EmptyKey).length;
+			if (marks === undefined) {
+				// No-delta path: the composed delta is unavailable, so the exact shift is unknown. Keep the
+				// index valid by clamping it to the current length (best-effort). See this function's
+				// @privateRemarks for when this happens and why the fallback is intentionally weak.
+				trackedIndex = clamp(trackedIndex, 0, length);
+				return;
+			}
+			// Clamp defensively so a malformed or partial delta can never push the tracked index outside the
+			// valid insertion range while the anchor is live (adjustIndexForArrayDelta has no final clamp).
+			trackedIndex = clamp(adjustIndexForArrayDelta(trackedIndex, marks), 0, length);
+		},
+	);
+
 	return {
 		get index() {
-			if (child === undefined) {
-				return field.length;
-			}
-			if (child.parentField.parent !== field) {
-				return field.length;
+			if (off === undefined) {
+				throw new UsageError("Cannot read the index of a disposed ArrayPlaceAnchor.");
 			}
-			return child.parentField.index;
+			return trackedIndex;
+		},
+		dispose() {
+			off?.();
+			off = undefined;
 		},
 	};
 }
+
+/**
+ * Compute the new index of an {@link ArrayPlaceAnchor} after applying a shallow array delta.
+ * @remarks
+ * The marks cover the array's sequence field in order. `readPosition` walks the pre-edit array as the marks are
+ * consumed while `index` stays fixed at the anchor's pre-edit location; comparing the two (both in pre-edit
+ * coordinates) shifts `newIndex` to keep the anchor in the same gap between children as content is inserted or
+ * removed around it. Each mark is a removal (`detach`), an insertion (`attach`), or a retain (neither); a mark may
+ * carry both `detach` and `attach`, which is handled as a removal followed by an insertion. The per-mark behavior is
+ * commented inline below.
+ */
+function adjustIndexForArrayDelta(index: number, marks: readonly DeltaMark[]): number {
+	let readPosition = 0;
+	let newIndex = index;
+	for (const mark of marks) {
+		// A removal consumes pre-edit content: if it lies entirely before the anchor it pulls the anchor left,
+		// and if it contains the anchor's position the anchor collapses to the start of the removed span.
+		if (mark.detach !== undefined) {
+			const removeEnd = readPosition + mark.count;
+			if (removeEnd <= index) {
+				newIndex -= mark.count;
+			} else if (readPosition < index) {
+				newIndex -= index - readPosition;
+			}
+			readPosition += mark.count;
+		}
+		if (mark.attach !== undefined) {
+			// Content inserted at or before the anchor pushes it right; inserting exactly at the anchor leaves the
+			// anchor after the new content (insertion-point behavior). Inserted content is new, so it does not
+			// advance the pre-edit read position.
+			if (readPosition <= index) {
+				newIndex += mark.count;
+			}
+		} else if (mark.detach === undefined) {
+			// Retain: existing content that was neither inserted nor removed.
+			readPosition += mark.count;
+		}
+	}
+	return newIndex;
+}

package/src/simple-tree/node-kinds/map/mapNode.ts

@@ -22,14 +22,18 @@ import {
 	type JsonCompatibleReadOnlyObject,
 	type RestrictiveStringRecord,
 } from "../../../util/index.js";
-import type { NodeSchemaOptionsAlpha } from "../../api/index.js";
+import type {
+	NodeSchemaOptionsAlpha,
+	// eslint-disable-next-line @typescript-eslint/no-unused-vars -- Referenced by TSDoc {@link} in this file.
+	RunTransactionParamsAlpha,
+} from "../../api/index.js";
 import {
 	CompatibilityLevel,
 	getKernel,
 	type InnerNode,
 	NodeKind,
 	type TreeNodeSchema,
-	// eslint-disable-next-line import-x/no-deprecated
+	// eslint-disable-next-line import-x/no-deprecated -- Required to implement the deprecated typeNameSymbol API.
 	typeNameSymbol,
 	type TreeNode,
 	typeSchemaSymbol,
@@ -166,7 +170,105 @@ export interface TreeMapNode<T extends ImplicitAllowedTypes = ImplicitAllowedTyp
 export interface TreeMapNodeAlpha<T extends ImplicitAllowedTypes = ImplicitAllowedTypes>
 	extends FluidReadonlyMap<string, TreeNodeFromImplicitAllowedTypes<T>>,
 		TreeNode,
-		Pick<TreeMapNode<T>, "set" | "delete"> {}
+		Pick<TreeMapNode<T>, "set" | "delete"> {
+	/**
+	 * Removes all elements from the map.
+	 * @remarks
+	 * The merge semantics of this operation are loosely specified. Either of the following may occur:
+	 *
+	 * - `clear` may remove all elements that were in the map when the edit was authored,
+	 * even if some of those elements have since been moved elsewhere in the tree
+	 * (in which case they are removed from their new location).
+	 *
+	 * - `clear` may remove all elements that are in the map when the edit is sequenced,
+	 * even if some of those elements were not yet in the map when the edit was authored.
+	 */
+	clear(): void;
+	/**
+	 * Returns the value at `key`, first inserting `fallbackValue` if this map has no entry for `key`.
+	 *
+	 * @param key - The key of the element to return or insert at.
+	 * @param fallbackValue - The value to insert if `key` has no entry.
+	 * @returns The value at `key`, which may be the provided `fallbackValue`
+	 * if the map had no previous entry for `key`.
+	 *
+	 * @remarks
+	 * The check for the presence of an existing entry with the given `key` is performed at the time the edit is authored.
+	 * This has implications for the merge semantics of this operation:
+	 *
+	 * - If no entry is present for `key` at authoring time (thus leading to an insert)
+	 * while a peer concurrently inserts a value for the same `key`,
+	 * then the two inserts will race and the one that is sequenced second will overwrite the value inserted by the one
+	 * that is sequenced first.
+	 *
+	 * - If an entry is present for `key` at authoring time (thus leading to no insert)
+	 * while a peer concurrently deletes the entry for `key`,
+	 * then the map will end up with no entry for `key` no matter how the two edits are sequenced.
+	 *
+	 * - If an entry is present for `key` at authoring time (thus leading to no insert)
+	 * while a peer concurrently inserts a new entry for `key`,
+	 * then the map will end up with the entry set by the peer no matter how the two edits are sequenced.
+	 *
+	 * These last two points mean that, upon sequencing of an edit made with this API,
+	 * there is no guarantee that the entry for the given key will be the current one (if any) or the fallback one.
+	 * If such a guarantee is important, then consider using {@link RunTransactionParamsAlpha.preconditions}
+	 * to ensure the edit only applies when appropriate.
+	 *
+	 * This API is **not** equivalent to the following alternative:
+	 *
+	 * ```typescript
+	 * map.set(key, map.get(key) ?? fallbackValue);
+	 * ```
+	 *
+	 * They differ in the following ways:
+	 *
+	 * - This API treats entries containing `null` values as populated.
+	 * By contrast, the above alternative's usage of `??` means that a `null` entry is treated as equivalent to a missing entry.
+	 *
+	 * - This API only inserts/sets the entry for the given `key` when there is no current one.
+	 * By contrast, the above alternative always performs an insert.
+	 * That insert will throw an error for non-leaf types (objects, maps, arrays, and records) in cases where the entry
+	 * is already populated, because inserting a node that was already inserted is not supported.
+	 * It will always succeed for leaf types (number, string, boolean, null, and handle) since a new node is created
+	 * from the value.
+	 * Note that even in the cases where it does not throw,
+	 * the `set` operation has the potential to overwrite entries that are concurrently inserted even when the map had
+	 * an entry for `key`, which is not the case with this API.
+	 *
+	 * Avoid using this API to write a default value into the document when the application could instead return that
+	 * default when reading a missing entry, which is much less costly.
+	 * A more appropriate use of this API is when the value to be optionally inserted varies with the key.
+	 */
+	getOrInsert(
+		key: string,
+		fallbackValue: InsertableTreeNodeFromImplicitAllowedTypes<T>,
+	): TreeNodeFromImplicitAllowedTypes<T>;
+
+	/**
+	 * Returns the value at `key`, first inserting the value produced by `callback` if this map has no entry for `key`.
+	 *
+	 * @param key - The key of the element to return or insert at.
+	 * @param callback - Invoked with `key` to produce the value to insert if `key` has no entry.
+	 * Not invoked if an entry is present.
+	 * @returns The value at `key`, which may be the value produced by `callback`
+	 * if the map had no previous entry for `key`.
+	 *
+	 * @remarks
+	 * This API is equivalent to {@link TreeMapNodeAlpha.getOrInsert} except that the fallback value is computed lazily:
+	 * `callback` is only invoked when the map has no entry for `key`.
+	 * Prefer this API over {@link TreeMapNodeAlpha.getOrInsert} when producing the fallback value is expensive.
+	 *
+	 * The check for the presence of an existing entry with the given `key` is performed at the time the edit is authored.
+	 * See {@link TreeMapNodeAlpha.getOrInsert} for the implications this has on the merge semantics of this operation.
+	 *
+	 * If `callback` throws, no edit is made and the error is propagated to the caller.
+	 * If `callback` sets an entry for `key` in this map, that entry is overwritten with the value `callback` returned.
+	 */
+	getOrInsertComputed(
+		key: string,
+		callback: (key: string) => InsertableTreeNodeFromImplicitAllowedTypes<T>,
+	): TreeNodeFromImplicitAllowedTypes<T>;
+}
 
 // TreeMapNode is invariant over schema type, so for this handler to work with all schema, the only possible type for the schema is `any`.
 // This is not ideal, but no alternatives are possible.
@@ -247,6 +349,28 @@ abstract class CustomMapNodeBase<const T extends ImplicitAllowedTypes> extends T
 		this.editor(key).set(mapTree, field.length === 0);
 		return this;
 	}
+	public getOrInsert(
+		key: string,
+		fallbackValue: InsertableTreeNodeFromImplicitAllowedTypes<T>,
+	): TreeNodeFromImplicitAllowedTypes<T> {
+		const existing = this.get(key);
+		if (existing !== undefined) {
+			return existing;
+		}
+		this.set(key, fallbackValue);
+		return this.get(key);
+	}
+	public getOrInsertComputed(
+		key: string,
+		callback: (key: string) => InsertableTreeNodeFromImplicitAllowedTypes<T>,
+	): TreeNodeFromImplicitAllowedTypes<T> {
+		const existing = this.get(key);
+		if (existing !== undefined) {
+			return existing;
+		}
+		this.set(key, callback(key));
+		return this.get(key);
+	}
 	public get size(): number {
 		return count(this.innerNode.keys());
 	}
@@ -265,7 +389,15 @@ abstract class CustomMapNodeBase<const T extends ImplicitAllowedTypes> extends T
 			callbackFn.call(thisArg, node, field.key, this);
 		}
 	}
-	// TODO: add `clear` once we have established merge semantics for it.
+	public clear(): void {
+		const node = this.innerNode;
+		const transaction = node.isHydrated() ? node.context.checkout.transaction : undefined;
+		transaction?.start();
+		for (const key of [...node.keys()]) {
+			this.delete(key);
+		}
+		transaction?.commit();
+	}
 }
 
 /**
@@ -353,7 +485,7 @@ export function mapSchema<
 		public static readonly persistedMetadata: JsonCompatibleReadOnlyObject | undefined =
 			persistedMetadata;
 
-		// eslint-disable-next-line import-x/no-deprecated
+		// eslint-disable-next-line import-x/no-deprecated -- Required to implement the deprecated typeNameSymbol API.
 		public get [typeNameSymbol](): TName {
 			return identifier;
 		}

package/src/simple-tree/node-kinds/object/objectNode.ts

@@ -32,7 +32,7 @@ import {
 	type TreeNodeSchema,
 	NodeKind,
 	type WithType,
-	// eslint-disable-next-line import-x/no-deprecated
+	// eslint-disable-next-line import-x/no-deprecated -- Required to handle the deprecated typeNameSymbol API.
 	typeNameSymbol,
 	typeSchemaSymbol,
 	type InternalTreeNode,
@@ -335,7 +335,7 @@ function createProxyHandler(
 			if (propertyKey === typeSchemaSymbol) {
 				return schema;
 			}
-			// eslint-disable-next-line import-x/no-deprecated
+			// eslint-disable-next-line import-x/no-deprecated -- Required to handle the deprecated typeNameSymbol API.
 			if (propertyKey === typeNameSymbol) {
 				return schema.identifier;
 			}
@@ -633,7 +633,7 @@ export function objectSchema<
 		public static readonly persistedMetadata: JsonCompatibleReadOnlyObject | undefined =
 			nodeOptions.persistedMetadata;
 
-		// eslint-disable-next-line import-x/no-deprecated
+		// eslint-disable-next-line import-x/no-deprecated -- Required to implement the deprecated typeNameSymbol API.
 		public get [typeNameSymbol](): TName {
 			return identifier;
 		}

package/src/simple-tree/node-kinds/record/recordNode.ts

@@ -17,7 +17,7 @@ import type { NodeSchemaOptionsAlpha } from "../../api/index.js";
 import {
 	type TreeNodeSchema,
 	NodeKind,
-	// eslint-disable-next-line import-x/no-deprecated
+	// eslint-disable-next-line import-x/no-deprecated -- Required to handle the deprecated typeNameSymbol API.
 	typeNameSymbol,
 	typeSchemaSymbol,
 	type UnhydratedFlexTreeNode,
@@ -78,7 +78,7 @@ function createRecordNodeProxy(
 					case typeSchemaSymbol: {
 						return schema;
 					}
-					// eslint-disable-next-line import-x/no-deprecated
+					// eslint-disable-next-line import-x/no-deprecated -- Required to handle the deprecated typeNameSymbol API.
 					case typeNameSymbol: {
 						return schema.identifier;
 					}
@@ -370,7 +370,7 @@ export function recordSchema<
 		public static readonly persistedMetadata: JsonCompatibleReadOnlyObject | undefined =
 			persistedMetadata;
 
-		// eslint-disable-next-line import-x/no-deprecated
+		// eslint-disable-next-line import-x/no-deprecated -- Required to implement the deprecated typeNameSymbol API.
 		public get [typeNameSymbol](): TName {
 			return identifier;
 		}

package/src/text/README.md

@@ -5,4 +5,4 @@ A collection of text related types, schema and utilities for working with text b
 ## Status
 
 Very early work in progress.
-See doc comment on `TextAsTree` for more details.
+See doc comment on `PlainText` for more details.

package/src/text/codePointUtils.ts

@@ -9,7 +9,7 @@ import { UsageError } from "@fluidframework/telemetry-utils/internal";
  * Returns the number of Unicode code points in `value`.
  * @remarks
  * Use this to translate a JavaScript string length (which is in UTF-16 code units) into
- * the atom/code-point space used by {@link TextAsTree}.
+ * the atom/code-point space used by {@link PlainText} and {@link FormattedText}.
  *
  * @example
  * ```typescript
@@ -33,7 +33,7 @@ export function codePointCount(value: string): number {
  * Returns the number of UTF-16 code units occupied by the first `count` Unicode code points in `value`,
  * starting at UTF-16 index `start`.
  * @remarks
- * Use this to translate {@link TextAsTree}-space counts (code points) into JavaScript string indices (UTF-16).
+ * Use this to translate {@link PlainText}-space counts (code points) into JavaScript string indices (UTF-16).
  * One code point outside the Basic Multilingual Plane (e.g. most emoji) occupies two UTF-16 code units.
  *
  * Validates that the requested `count` code points are fully consumable from `start`; silent truncation

package/src/text/index.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-export { TextAsTree } from "./textDomain.js";
-export { FormattedTextAsTree } from "./textDomainFormatted.js";
-export { FormattedTextAsTreeDefault } from "./textDomainFormattedDefault.js";
+export { PlainText } from "./textDomain.js";
+export { FormattedText } from "./textDomainFormatted.js";
+export { FormattedTextDefault } from "./textDomainFormattedDefault.js";
 export { codePointCount, utf16LengthForCodePoints } from "./codePointUtils.js";