diff --git a/CORE_REFACTOR_DEFERRED.md b/CORE_REFACTOR_DEFERRED.md
index 3984c81a6..3a4aa5689 100644
--- a/CORE_REFACTOR_DEFERRED.md
+++ b/CORE_REFACTOR_DEFERRED.md
@@ -6,7 +6,7 @@ These items came out of the PR reviews for the multi-phase refactor (`core-refac
 
 ### Type the `core: any` back-reference in extracted managers
 
-Every new manager declares `core: any;` — Phase 1 (`DiagnosticsManager`, `VisibilityTracker`, `StatePersistence`, `AutoSubmitManager`, `NavigationHandler`, `ResolverAdapter`) and Phase 2 (`RendererInstructionBuilder`, `ProcessQueue`, `ComponentLifecycle`, `ChildMatcher`, `DeletionEngine`, `ActionTriggerScheduler`). That defeats the point of converting to TypeScript — typos and accidental property reads through `core` go unchecked.
+Every new manager declares `core: any;` — Phase 1 (`DiagnosticsManager`, `VisibilityTracker`, `StatePersistence`, `AutoSubmitManager`, `NavigationHandler`, `ResolverAdapter`), Phase 2 (`RendererInstructionBuilder`, `ProcessQueue`, `ComponentLifecycle`, `ChildMatcher`, `DeletionEngine`, `ActionTriggerScheduler`), and Phase 3 (`StateVariableDefinitionFactory`, `StateVariableInitializer`, `ComponentBuilder`, `CompositeExpander`). That defeats the point of converting to TypeScript — typos and accidental property reads through `core` go unchecked.
 
 Since `Core.js` is still JavaScript, defining a real `Core` interface is awkward. Two practical paths:
 
@@ -21,6 +21,7 @@ Several managers hold no state of their own — only a `core` back-reference:
 
 - Phase 1: `NavigationHandler`, `ResolverAdapter`
 - Phase 2: `ComponentLifecycle`, `DeletionEngine` (and `ChildMatcher`, modulo its single recursion-guard array)
+- Phase 3: `StateVariableDefinitionFactory`, `StateVariableInitializer`, `ComponentBuilder`, `CompositeExpander` — none keep their own state; they only read/write through `core`
 
 The pure-function shape used in `StateVariableNameResolver.ts` is more honest for these:
 
@@ -67,9 +68,9 @@ A cleaner shape: make `calcStartEndIdx` a standalone helper (or a private method
 
 Three intentionally unawaited Promise calls remain in `Core.js`. They pre-date this PR (this refactor did not introduce them, and adding `.catch` handlers was out of scope for a behavior-preserving extraction), but they violate the AGENTS.md convention that fire-and-forget Promises must attach an explicit `.catch(...)` handler. They should be picked up in the next phase that touches Core directly.
 
-- **`Core.js:410`** — `this.saveState();` inside the `generateDast` epilogue (`if (!this.receivedStateVariableChanges) { this.saveState(); }`). Returns a Promise; rejection is unhandled.
-- **`Core.js:11160`** — `this.saveState(true, true);` inside `processNewStateVariableValues` after recording component submissions. Same shape as above.
-- **`Core.js:449-452`** — `setTimeout(this.sendVisibilityChangedEvents.bind(this), this.visibilityInfo.saveDelay)` inside `onDocumentFirstVisible()`. The bound function returns `Promise<void> | undefined`; setTimeout discards the return, so any rejection is unhandled.
+- **`Core.js:444`** — `this.saveState();` inside the `generateDast` epilogue (`if (!this.receivedStateVariableChanges) { this.saveState(); }`). Returns a Promise; rejection is unhandled.
+- **`Core.js:4387`** — `this.saveState(true, true);` inside `processNewStateVariableValues` after recording component submissions. Same shape as above.
+- **`Core.js:483-486`** — `setTimeout(this.sendVisibilityChangedEvents.bind(this), this.visibilityInfo.saveDelay)` inside `onDocumentFirstVisible()`. The bound function returns `Promise<void> | undefined`; setTimeout discards the return, so any rejection is unhandled.
 
 Suggested fix in each case: wrap with `.catch(reportTimerError("<label>"))` using the helper added in this PR (`src/utils/timerErrors.ts`). For the setTimeout case, use a thin arrow wrapper: `setTimeout(() => { this.sendVisibilityChangedEvents()?.catch(reportTimerError("first-visible visibility send")); }, ...)`.
 
@@ -86,6 +87,19 @@ When the Phase 2 modules were extracted, several `TODO` / `XXX` markers were lif
 - `RendererInstructionBuilder.ts:275` — `// TODO: need this to ignore baseVariables change: is this right place?` on `rendererType` capture.
 - `ChildMatcher.ts:430, 468` — two `// XXX: how does this work with the new componentIdx approach?` comments on the placeholder-adapter branch.
 
+Phase 3 lifted further `TODO`s verbatim from `Core.js` into the new modules:
+
+- `StateVariableInitializer.ts:42` — `// TODO: do we want to delete alias from state?` on the alias-handling branch of `initializeComponentStateVariables`.
+- `StateVariableInitializer.ts:313` — `// TODO: delete since arrayEntrySize isn't currently used?` on the array-entry size dependency setup.
+- `StateVariableInitializer.ts:362, 923` — `// TODO: we are communicating this to updateDependencies by adding ...` on dependency-name punning.
+- `StateVariableInitializer.ts:666, 766` — duplicate `// TODO: if we redesign arrays to be based on indices (or even slices), ...` reflections on array-entry materialization.
+- `StateVariableInitializer.ts:817` — `// TODO: wrapping components (like most array features) was designed before ...`.
+- `StateVariableInitializer.ts:868, 1449` — duplicate `// TODO: a better idea? This seems like it could lead to confusion.` on the public-state-variable-name resolution path.
+- `StateVariableDefinitionFactory.ts:1355, 1451` — duplicate `// TODO: how do we make it do this just once?` on the array-entry definition setup.
+- `ComponentBuilder.ts:170, 238` — duplicate `// TODO: should we check for child results earlier so we don't have to check them ...` on the post-creation child-result re-derivation.
+- `CompositeExpander.ts:373` — `// TODO: are there any scenarios where this will lead to an infinite loop?` on the `createSerializedReplacements` retry loop.
+- `CompositeExpander.ts:688` — `// XXX: what is the replacement for targetComponentIdx?` on the shadow-mediating composite branch.
+
 ### `processQueue` field naming inside Core
 
 `Core` stores the `ProcessQueue` instance as `this.processQueueManager` while every other manager is named after its class (`this.componentLifecycle`, `this.childMatcher`, `this.deletionEngine`, `this.actionTriggerScheduler`, `this.rendererInstructionBuilder`, `this.diagnosticsManager`, `this.statePersistence`, etc.). The `Manager` suffix is here because `Core` already exposes `get processQueue() { return this.processQueueManager.queue; }` for the underlying array — and JS doesn't let an instance field shadow an inherited accessor of the same name.
@@ -99,7 +113,7 @@ Pick one; the current shape inherits the asymmetry from a half-finished rename.
 
 ### Standardize `core._components` vs `core.components` access in extracted managers
 
-`Core` exposes `_components` as the canonical array and `get components()` as a read-only accessor returning the same array. Phase 2's modules now consistently use `core._components` (Phase 1 mostly does too). If future managers are added, keep this convention so reviewers don't have to remember the array and getter are the same thing. The deferred `CoreBackref` interface above is the natural place to enforce it (expose only `_components`).
+`Core` exposes `_components` as the canonical array and `get components()` as a read-only accessor returning the same array. Phase 2's and Phase 3's modules now consistently use `core._components` (Phase 1 mostly does too). If future managers are added, keep this convention so reviewers don't have to remember the array and getter are the same thing. The deferred `CoreBackref` interface above is the natural place to enforce it (expose only `_components`).
 
 ### Regression test for the `.primitive.number` → `.primitive.value` fix
 
@@ -107,6 +121,67 @@ Commit `aed7910c` fixed a latent bug at `ResolverAdapter.ts:84` (was reading `co
 
 This codepath fires when a copy component (created via `extend`) has a `source:sequence` attribute and a numeric `createComponentIdx`. A targeted Vitest case constructing that specific shape and asserting the resolver receives a `parentSourceSequence` with the correct `parent: <number>` field would lock the fix in. Without it, regressions could re-introduce the silent `undefined`-parent bug.
 
+### De-duplicate attribute-derived state variable construction in `StateVariableDefinitionFactory`
+
+The factory builds attribute-derived state variables in three almost-identical sites: `createAttributeStateVariableDefinitions` (around lines 130, 170, 232-402, 405-419), `createReferenceShadowStateVariableDefinitions` (around lines 678, 721-743, 782-952, 955-968), and the adapter-shadow path (around line 448, 554-567). Four families of duplication are visible:
+
+1. **`shadowingInstructions` block.** Three near-identical 30-line blocks that map `attributeSpecification.createPrimitiveOfType` (string/stringArray/numberArray) to the corresponding component type (text/textList/numberList) and assign it to `stateVarDef.shadowingInstructions.createComponentOfType`. Extract a `_setShadowingInstructionsFromAttribute(stateVarDef, attributeSpecification)` helper.
+2. **`stateVariableForAttributeValue` resolution.** Two identical lookups of `componentStateVariableForAttributeValue → attributeClass.stateVariableToBeShadowed → "value"`, both with the same "Component type … does not exist" throw. Extract `_resolveAttributeValueVariable(attributeSpecification, attrName, componentClass)`.
+3. **`definition` / `inverseDefinition` callback pair on attribute-derived state vars.** ~170 lines duplicated almost verbatim between `createAttributeStateVariableDefinitions` and `createReferenceShadowStateVariableDefinitions`. A shared closure-builder returning `{ definition, inverseDefinition }` would absorb the duplication.
+4. **`attributesToCopy` loop.** Three copies of the array + copy loop. The first intentionally adds `"triggerActionOnChange"`; the other two omit it. Today this divergence relies on visual diff; a helper like `_copyPassthroughAttributes(stateVarDef, attributeSpecification, { includeTriggerActionOnChange })` would make it explicit.
+
+### Collapse the two branches of `ComponentBuilder.addComponents`
+
+The initial-add branch (`addComponents` body when `initialAdd === true`, around lines 89-185) and the incremental-add branch (around lines 186-254) share three drains verbatim:
+
+- Two `expandAllComposites(document)` calls (force=false then force=true).
+- The `stateVariablesToEvaluate` drain loop (~16 lines apiece).
+- The trailing `if (compositesToUpdateReplacements.size > 0)` "drain + re-render" tail (~12 lines apiece).
+
+Extracting `_drainStateVariablesToEvaluate()`, `_expandAllCompositesBothPasses(component)`, and `_drainCompositesToUpdateReplacements()` would shrink `addComponents` by roughly 40 lines and make the initial-add vs incremental-add asymmetry obvious.
+
+### Extract `_finishExpanding` and unexpanded-composite helpers in `CompositeExpander`
+
+Two patterns duplicate verbatim across `expandCompositeComponent` and `expandShadowingComposite`:
+
+1. **"Finished expanding" cleanup** (lines 411-420 and 741-750). Identical 9-line `compositesBeingExpanded.indexOf(componentIdx)` + `throw if -1` + `splice` block. Extract `_finishExpanding(componentIdx)`.
+2. **Unexpanded-composite list cleanup** in `expandCompositeComponent` (lines 277-294 of the current file). The `unexpandedCompositesReady` and `unexpandedCompositesNotReady` lists each get the same `indexOf` + `splice` treatment; can collapse to `for (const arr of [parent.unexpandedCompositesReady, parent.unexpandedCompositesNotReady])`.
+
+### Drop dead `replacementsCreated` guard in `CompositeExpander.expandShadowingComposite`
+
+Around line 674 (the second `if (component.replacementsWorkspace.replacementsCreated === undefined) { ... = 0 }` inside the `!foundCircular` branch). `replacementsCreated` is already initialized to `0` ~200 lines earlier in the same function (around line 467) and is never re-set to undefined between the two checks. The second guard is dead.
+
+### Pre-existing `verifyReplacementsMatchSpecifiedType` warnings loop bug
+
+`CompositeExpander.expandShadowingComposite`, around lines 695-704. Both loops iterate `verificationResult.diagnostics` and add the items as both `"error"` and `"warning"` diagnostics, so every diagnostic is double-reported and there is no path for a true warning to come through. The second loop almost certainly should iterate `verificationResult.warnings` (or equivalent), or be deleted. Carried over verbatim from `Core.js`; not introduced by the refactor. Confirm against the verifier's actual output shape and fix in a separate PR.
+
+### Pre-existing unreachable diagnostic in `StateVariableInitializer.initializeArrayStateVariable`
+
+Around line 453 of the current file:
+
+```ts
+if (!numDimensionsInArrayKey > stateVarObj.numDimensions) {
+    core.addDiagnostic({ ... "Number of dimensions specified in array key ..." ... });
+    ...
+}
+```
+
+`!numDimensionsInArrayKey` is `false` for any positive integer, and `false > number` is always `false`, so the diagnostic is unreachable. Almost certainly intended `numDimensionsInArrayKey > stateVarObj.numDimensions`. Pre-dates the refactor (present in `Core.js` since the 2021 rename); flag for a separate fix once the intended check has been confirmed against test expectations.
+
+### Re-home `recursivelyReplaceCompositesWithReplacements`
+
+Currently at `StateVariableInitializer.ts:1609` and exposed via the wrapper `Core.js:recursivelyReplaceCompositesWithReplacements`. Conceptually it walks composites and substitutes their replacements — nothing to do with state-variable initialization. Better home: `CompositeExpander` (or a new `CompositeReplacementWalker` if `CompositeExpander` shouldn't grow further). While moving it, drop the unread `forceExpandComposites` parameter — declared at line 1612, never read in the body, only forwarded recursively (line 1673). Pre-existing dead parameter, lifted from `Core.js`.
+
+### Minor cleanups in `ComponentBuilder`
+
+- **`componentIdx == undefined` (line 311)** uses loose equality where the rest of the file uses strict (`=== undefined`). Tighten for consistency.
+- **`if (!this.core.nTimesAddedComponents) { ... = 1 } else { ...++ }` (lines 67-71)** is a verbose increment-or-init. `this.core.nTimesAddedComponents = (this.core.nTimesAddedComponents ?? 0) + 1;` is one line.
+- **Bare `catch (e) { console.error(e); throw e; }` (around line 534)** in the `attribute.references` branch of `createChildrenThenComponent`. The catch adds nothing the caller can't see; consider dropping it. The sibling catch at line 503 has real logic (rewrites circular-dependency messages) and should stay.
+
+### Move `findShadowedChildInSerializedComponents` to `utils/`
+
+`ComponentBuilder.findShadowedChildInSerializedComponents` (around lines 850-869 of the current file) reads/writes nothing on `this.core` and is a pure recursion over a serialized component tree. A natural fit for `utils/` next to the other serialized-tree walkers. This overlaps with the broader "stateless managers → plain functions" deferred item but is a particularly clean lift.
+
 ## Notes for the next agent
 
 - The applied items in this PR are self-contained — see the diff against the previous commit. The structural deferrals above don't depend on each other except that #1 (typing) makes #2 (stateless→plain) cleaner since the back-reference type would already exist.
diff --git a/packages/doenetml-worker-javascript/src/ComponentBuilder.ts b/packages/doenetml-worker-javascript/src/ComponentBuilder.ts
new file mode 100644
index 000000000..08336a863
--- /dev/null
+++ b/packages/doenetml-worker-javascript/src/ComponentBuilder.ts
@@ -0,0 +1,979 @@
+import { convertToErrorComponent } from "./utils/dast/errors";
+import { gatherVariantComponents } from "./utils/variants";
+import { unwrapSource } from "./utils/dast/convertNormalizedDast";
+import { extractCreateComponentIdxMapping } from "./utils/componentIndices";
+
+/**
+ * Builds component instances from serialized DAST. Handles the recursive
+ * walk that creates a parent before its children, registers each new
+ * component in the live tree (`core._components`), wires up state-variable
+ * definitions and initial dependencies, and on the initial document load
+ * performs the post-creation flush of error components requested by
+ * state-variable definitions.
+ *
+ * The expansion of composite components into their replacements is the
+ * responsibility of `CompositeExpander` (mutual recursion is expected;
+ * cross-calls go through Core's delegators).
+ *
+ * Holds a back-reference to Core to read the hot fields
+ * (`_components`, `componentInfoObjects`, `parameterStack`, `dependencies`,
+ * `updateInfo`, `numerics`, `flags`, `coreFunctions`, `document`,
+ * `componentIdxByStateId`, `nTimesAddedComponents`, `rootNames`,
+ * `createComponentIdxMapping`, `errorComponentsToAdd`, `initialAddPhase`)
+ * and to dispatch through the other extracted managers.
+ */
+export class ComponentBuilder {
+    core: any;
+
+    constructor({ core }: { core: any }) {
+        this.core = core;
+    }
+
+    async addComponents({
+        serializedComponents,
+        parentIdx,
+        indexOfDefiningChildren,
+        initialAdd = false,
+    }) {
+        this.core.initialAddPhase = initialAdd;
+
+        if (!Array.isArray(serializedComponents)) {
+            serializedComponents = [serializedComponents];
+        }
+
+        let parent;
+        let ancestors = [];
+
+        if (!initialAdd) {
+            parent = this.core._components[parentIdx];
+            if (!parent) {
+                this.core.addDiagnostic({
+                    type: "warning",
+                    message: `Cannot add children to parent ${parentIdx} as ${parentIdx} does not exist`,
+                });
+                return [];
+            }
+
+            ancestors = [
+                {
+                    componentIdx: parentIdx,
+                    componentClass: parent.constructor,
+                },
+                ...parent.ancestors,
+            ];
+
+            this.core.parameterStack.push(parent.sharedParameters, false);
+
+            if (!this.core.nTimesAddedComponents) {
+                this.core.nTimesAddedComponents = 1;
+            } else {
+                this.core.nTimesAddedComponents++;
+            }
+
+            this.core.addComponentsToResolver(serializedComponents, parentIdx);
+        }
+        let createResult = await this.createIsolatedComponents({
+            serializedComponents,
+            ancestors,
+        });
+        if (!initialAdd) {
+            this.core.parameterStack.pop();
+        }
+
+        const newComponents = createResult.components;
+
+        let deletedComponents = {};
+        let addedComponents = {};
+        newComponents.forEach((x) => (addedComponents[x.componentIdx] = x));
+
+        if (initialAdd) {
+            if (newComponents.length !== 1) {
+                throw Error(
+                    "Initial components need to be an array of just one component.",
+                );
+            }
+            this.core.document = newComponents[0];
+
+            await this.core.expandAllComposites(this.core.document);
+
+            await this.core.expandAllComposites(this.core.document, true);
+
+            if (this.core.updateInfo.stateVariablesToEvaluate) {
+                let stateVariablesToEvaluate =
+                    this.core.updateInfo.stateVariablesToEvaluate;
+                this.core.updateInfo.stateVariablesToEvaluate = [];
+                for (let {
+                    componentIdx,
+                    stateVariable,
+                } of stateVariablesToEvaluate) {
+                    let comp = this.core._components[componentIdx];
+                    if (comp && comp.state[stateVariable]) {
+                        await this.core.getStateVariableValue({
+                            component: comp,
+                            stateVariable,
+                        });
+                    }
+                }
+            }
+
+            await this.addQueuedErrorComponentsFromStateVariables();
+
+            await this.core.replacementChangesFromCompositesToUpdate();
+
+            let results =
+                await this.core.initializeRenderedComponentInstruction(
+                    this.core.document,
+                );
+
+            if (this.core.errorComponentsToAdd.length > 0) {
+                await this.addQueuedErrorComponentsFromStateVariables();
+
+                // Adding queued _error components can touch composites and alter
+                // what needs to be rendered from the document root.
+                await this.core.replacementChangesFromCompositesToUpdate();
+
+                results =
+                    await this.core.initializeRenderedComponentInstruction(
+                        this.core.document,
+                    );
+            }
+
+            this.core.documentRendererInstructions = results.componentToRender;
+
+            let updateInstructions = [
+                {
+                    instructionType: "updateRendererStates",
+                    rendererStatesToUpdate: results.rendererStatesToUpdate,
+                },
+            ];
+
+            this.core.callUpdateRenderers({ updateInstructions }, true);
+
+            // if have some states to force update
+            // then post these updates without setting init to true
+            if (results.rendererStatesToForceUpdate.length > 0) {
+                let updateInstructions = [
+                    {
+                        instructionType: "updateRendererStates",
+                        rendererStatesToUpdate:
+                            results.rendererStatesToForceUpdate,
+                    },
+                ];
+                this.core.callUpdateRenderers({ updateInstructions });
+            }
+
+            // initializing renderer instructions could trigger more composite updates
+            // (presumably from deriving child results)
+            // if so, make replacement changes and update renderer instructions again
+            // TODO: should we check for child results earlier so we don't have to check them
+            // when updating renderer instructions?
+            if (this.core.updateInfo.compositesToUpdateReplacements.size > 0) {
+                await this.core.replacementChangesFromCompositesToUpdate();
+
+                let componentNamesToUpdate = [
+                    ...this.core.updateInfo.componentsToUpdateRenderers,
+                ];
+                this.core.updateInfo.componentsToUpdateRenderers.clear();
+
+                await this.core.updateRendererInstructions({
+                    componentNamesToUpdate,
+                });
+            }
+
+            await this.core.processStateVariableTriggers(true);
+        } else {
+            if (parent === undefined) {
+                throw Error("Must specify parent when adding components.");
+            }
+            if (indexOfDefiningChildren === undefined) {
+                indexOfDefiningChildren = parent.definingChildren.length;
+            }
+
+            let addResults = await this.core.addChildrenAndRecurseToShadows({
+                parent,
+                indexOfDefiningChildren: indexOfDefiningChildren,
+                newChildren: newComponents,
+            });
+            if (!addResults.success) {
+                throw Error(
+                    "Couldn't satisfy child logic result.  Need informative error message",
+                );
+            }
+            Object.assign(addedComponents, addResults.addedComponents);
+            Object.assign(deletedComponents, addResults.deletedComponents);
+
+            await this.core.expandAllComposites(this.core.document);
+            await this.core.expandAllComposites(this.core.document, true);
+
+            if (this.core.updateInfo.stateVariablesToEvaluate) {
+                let stateVariablesToEvaluate =
+                    this.core.updateInfo.stateVariablesToEvaluate;
+                this.core.updateInfo.stateVariablesToEvaluate = [];
+                for (let {
+                    componentIdx,
+                    stateVariable,
+                } of stateVariablesToEvaluate) {
+                    let comp = this.core._components[componentIdx];
+                    if (comp && comp.state[stateVariable]) {
+                        await this.core.getStateVariableValue({
+                            component: comp,
+                            stateVariable,
+                        });
+                    }
+                }
+            }
+            await this.core.replacementChangesFromCompositesToUpdate();
+
+            await this.core.updateRendererInstructions({
+                componentNamesToUpdate:
+                    await this.core.componentAndRenderedDescendants(parent),
+            });
+
+            // updating renderer instructions could trigger more composite updates
+            // (presumably from deriving child results)
+            // if so, make replacement changes and update renderer instructions again
+            // TODO: should we check for child results earlier so we don't have to check them
+            // when updating renderer instructions?
+            if (this.core.updateInfo.compositesToUpdateReplacements.size > 0) {
+                await this.core.replacementChangesFromCompositesToUpdate();
+
+                let componentNamesToUpdate = [
+                    ...this.core.updateInfo.componentsToUpdateRenderers,
+                ];
+                this.core.updateInfo.componentsToUpdateRenderers.clear();
+
+                await this.core.updateRendererInstructions({
+                    componentNamesToUpdate,
+                });
+            }
+
+            await this.core.processStateVariableTriggers(true);
+        }
+
+        this.core.initialAddPhase = false;
+        return newComponents;
+    }
+
+    async createIsolatedComponents({
+        serializedComponents,
+        ancestors,
+        shadow = false,
+        componentsReplacementOf,
+    }) {
+        const newComponents = [];
+
+        let lastErrorMessage = "";
+
+        const res = extractCreateComponentIdxMapping(serializedComponents);
+        Object.assign(
+            this.core.createComponentIdxMapping,
+            res.createComponentIdxMapping,
+        );
+
+        for (let serializedComponent of serializedComponents) {
+            if (typeof serializedComponent !== "object") {
+                newComponents.push(serializedComponent);
+                continue;
+            }
+
+            let componentClass =
+                this.core.componentInfoObjects.allComponentClasses[
+                    serializedComponent.componentType
+                ];
+            if (componentClass === undefined) {
+                // Note: This error shouldn't get reached from author-typed code,
+                // as it should get caught by the correctComponentTypeCapitalization function.
+                // However, it could get called from Javascript if developers
+                // create a serialized component that doesn't exist.
+                const message = `Invalid component type: \`<${serializedComponent.componentType}>\`.`;
+
+                this.core.diagnosticsManager.markPending();
+
+                const convertResult = convertToErrorComponent(
+                    serializedComponent,
+                    message,
+                );
+                serializedComponent = convertResult.component;
+
+                lastErrorMessage = message;
+
+                componentClass =
+                    this.core.componentInfoObjects.allComponentClasses[
+                        serializedComponent.componentType
+                    ];
+            }
+
+            if (!serializedComponent.doenetAttributes) {
+                serializedComponent.doenetAttributes = {};
+            }
+
+            let componentIdx = serializedComponent.componentIdx;
+            if (componentIdx == undefined) {
+                throw Error(
+                    "Found a serialized component without a componentIdx",
+                    serializedComponent,
+                );
+            }
+
+            const createResult = await this.createChildrenThenComponent({
+                serializedComponent,
+                componentIdx,
+                ancestors,
+                componentClass,
+                shadow,
+                componentsReplacementOf,
+            });
+
+            const newComponent = createResult.newComponent;
+            newComponents.push(newComponent);
+
+            if (createResult.lastErrorMessage) {
+                lastErrorMessage = createResult.lastErrorMessage;
+            }
+        }
+
+        let results = {
+            components: newComponents,
+            lastErrorMessage,
+        };
+
+        return results;
+    }
+
+    async createChildrenThenComponent({
+        serializedComponent,
+        componentIdx,
+        ancestors,
+        componentClass,
+        shadow = false,
+        componentsReplacementOf,
+    }) {
+        let lastErrorMessage = "";
+        let lastErrorMessageFromAttribute = "";
+
+        if (!(Number.isInteger(componentIdx) && componentIdx >= 0)) {
+            throw Error(`Found an invalid componentIdx: ${componentIdx}`);
+        }
+
+        if (this.core._components[componentIdx] !== undefined) {
+            console.log(
+                this.core._components[componentIdx],
+                serializedComponent,
+            );
+            throw Error(`Found a duplicate componentIdx: ${componentIdx}`);
+        }
+
+        const serializedChildren = serializedComponent.children;
+        let definingChildren = [];
+        const childrenToRemainSerialized = [];
+
+        const ancestorsForChildren = [
+            { componentIdx, componentClass },
+            ...ancestors,
+        ];
+
+        const parentSharedParameters = this.core.parameterStack.parameters;
+        this.core.parameterStack.push();
+        const sharedParameters = this.core.parameterStack.parameters;
+
+        if (
+            componentClass.descendantCompositesMustHaveAReplacement &&
+            !shadow
+        ) {
+            sharedParameters.compositesMustHaveAReplacement = true;
+            sharedParameters.compositesDefaultReplacementType =
+                componentClass.descendantCompositesDefaultReplacementType;
+        } else if (
+            componentClass.descendantCompositesMustHaveAReplacement === false ||
+            shadow
+        ) {
+            sharedParameters.compositesMustHaveAReplacement = false;
+        }
+
+        if (serializedChildren !== undefined) {
+            if (componentClass.preprocessSerializedChildren) {
+                componentClass.preprocessSerializedChildren({
+                    serializedChildren,
+                    attributes: serializedComponent.attributes,
+                    componentIdx,
+                });
+            }
+
+            if (componentClass.setUpVariant) {
+                const descendantVariantComponents = gatherVariantComponents({
+                    serializedComponents: serializedChildren,
+                    componentInfoObjects: this.core.componentInfoObjects,
+                });
+
+                componentClass.setUpVariant({
+                    serializedComponent,
+                    sharedParameters,
+                    descendantVariantComponents,
+                });
+            }
+
+            if (componentClass.keepChildrenSerialized) {
+                const childrenAddressed = new Set([]);
+
+                const keepSerializedInds =
+                    componentClass.keepChildrenSerialized({
+                        serializedComponent,
+                        componentInfoObjects: this.core.componentInfoObjects,
+                    });
+
+                for (const ind of keepSerializedInds) {
+                    if (childrenAddressed.has(Number(ind))) {
+                        throw Error(
+                            "Invalid instructions to keep children serialized from " +
+                                componentClass.componentType +
+                                ": child repeated",
+                        );
+                    }
+                    childrenAddressed.add(Number(ind));
+                    childrenToRemainSerialized.push(serializedChildren[ind]);
+                }
+
+                const childrenToCreate = [];
+                for (const [ind, child] of serializedChildren.entries()) {
+                    if (!childrenAddressed.has(ind)) {
+                        childrenToCreate.push(child);
+                    }
+                }
+
+                if (childrenToCreate.length > 0) {
+                    const childrenResult = await this.createIsolatedComponents({
+                        serializedComponents: childrenToCreate,
+                        ancestors: ancestorsForChildren,
+                        shadow,
+                        componentsReplacementOf,
+                    });
+
+                    definingChildren = childrenResult.components;
+                    if (childrenResult.lastErrorMessage) {
+                        lastErrorMessage = childrenResult.lastErrorMessage;
+                    }
+                }
+            } else {
+                const childrenResult = await this.createIsolatedComponents({
+                    serializedComponents: serializedChildren,
+                    ancestors: ancestorsForChildren,
+                    shadow,
+                    componentsReplacementOf,
+                });
+
+                definingChildren = childrenResult.components;
+                if (childrenResult.lastErrorMessage) {
+                    lastErrorMessage = childrenResult.lastErrorMessage;
+                }
+            }
+        }
+
+        let attributes = {};
+
+        if (serializedComponent.attributes) {
+            for (const attrName in serializedComponent.attributes) {
+                const attribute = serializedComponent.attributes[attrName];
+
+                if (attribute.component) {
+                    if (attrName === componentClass.addAttributeToResolver) {
+                        this.core.addComponentsToResolver(
+                            [attribute.component],
+                            serializedComponent.componentIdx,
+                        );
+                    }
+
+                    try {
+                        const attrResult = await this.createIsolatedComponents({
+                            serializedComponents: [attribute.component],
+                            ancestors: ancestorsForChildren,
+                            shadow,
+                            componentsReplacementOf,
+                        });
+
+                        if (attrResult.lastErrorMessage) {
+                            lastErrorMessage = attrResult.lastErrorMessage;
+                            lastErrorMessageFromAttribute =
+                                attrResult.lastErrorMessage;
+                        }
+
+                        attributes[attrName] = {
+                            component: attrResult.components[0],
+                        };
+                    } catch (e) {
+                        console.error(e);
+                        if (e.message.includes("Circular dependency")) {
+                            throw Error(
+                                this.core.dependencies.getCircularDependencyMessage(
+                                    [serializedComponent],
+                                ),
+                            );
+                        } else {
+                            throw e;
+                        }
+                    }
+                } else if (attribute.references) {
+                    try {
+                        const attrResult = await this.createIsolatedComponents({
+                            serializedComponents: attribute.references,
+                            ancestors: ancestorsForChildren,
+                            shadow,
+                            componentsReplacementOf,
+                        });
+
+                        if (attrResult.lastErrorMessage) {
+                            lastErrorMessage = attrResult.lastErrorMessage;
+                            lastErrorMessageFromAttribute =
+                                attrResult.lastErrorMessage;
+                        }
+
+                        attributes[attrName] = {
+                            references: attrResult.components,
+                            stringChildren: attribute.stringChildren,
+                        };
+                    } catch (e) {
+                        console.error(e);
+                        throw e;
+                    }
+                } else {
+                    attributes[attrName] =
+                        serializedComponent.attributes[attrName];
+                }
+            }
+        }
+
+        let refResolution = null;
+        if (serializedComponent.extending) {
+            refResolution = unwrapSource(serializedComponent.extending);
+
+            const nodeIdx = refResolution.nodeIdx;
+
+            const originalPath = [];
+            for (const pathPart of refResolution.originalPath) {
+                const index = [];
+                for (const indexPiece of pathPart.index) {
+                    const valueResult = await this.createIsolatedComponents({
+                        serializedComponents: indexPiece.value,
+                        ancestors: ancestorsForChildren,
+                        shadow,
+                        componentsReplacementOf,
+                    });
+                    if (valueResult.lastErrorMessage) {
+                        lastErrorMessage = valueResult.lastErrorMessage;
+                    }
+                    const value = valueResult.components;
+                    index.push({
+                        value,
+                        position: indexPiece.position,
+                        sourceDoc: indexPiece.sourceDoc,
+                    });
+                }
+                originalPath.push({
+                    name: pathPart.name,
+                    index,
+                    position: pathPart.position,
+                    sourceDoc: pathPart.sourceDoc,
+                });
+            }
+            refResolution = {
+                nodeIdx,
+                unresolvedPath: refResolution.unresolvedPath,
+                originalPath,
+                nodesInResolvedPath: refResolution.nodesInResolvedPath,
+            };
+        }
+
+        if (serializedComponent.componentType === "_error") {
+            lastErrorMessage = serializedComponent.state.message;
+
+            this.core.addDiagnostic({
+                type: "error",
+                message: serializedComponent.state.message,
+                position: serializedComponent.position,
+                sourceDoc: serializedComponent.sourceDoc,
+            });
+        } else if (
+            lastErrorMessageFromAttribute ||
+            (lastErrorMessage && !componentClass.canDisplayChildErrors)
+        ) {
+            // We have to deal with two special cases where errors wouldn't be displayed:
+            // 1. there is an error message from an attribute, or
+            // 2. this component cannot display errors from children
+            // In these cases, we turn this component into an error component
+            // to ensure the error message is displayed.
+
+            const convertResult = convertToErrorComponent(
+                serializedComponent,
+                lastErrorMessageFromAttribute || lastErrorMessage,
+            );
+            serializedComponent = convertResult.component;
+
+            attributes = {};
+            componentClass =
+                this.core.componentInfoObjects.allComponentClasses[
+                    serializedComponent.componentType
+                ];
+        }
+
+        const prescribedDependencies = {};
+
+        if (serializedComponent.downstreamDependencies) {
+            for (const idxStr in serializedComponent.downstreamDependencies) {
+                const idx = Number(idxStr);
+                if (idx === componentIdx) {
+                    throw Error(
+                        this.core.dependencies.getCircularDependencyMessage([
+                            serializedComponent,
+                        ]),
+                    );
+                }
+                if (this.core._components[idx]) {
+                    prescribedDependencies[idx] =
+                        serializedComponent.downstreamDependencies[idx];
+                } else {
+                    throw Error(
+                        this.core.dependencies.getCircularDependencyMessage([
+                            serializedComponent,
+                        ]),
+                    );
+                }
+            }
+        }
+
+        const stateVariableDefinitions =
+            await this.core.createStateVariableDefinitions({
+                componentClass,
+                prescribedDependencies,
+                componentIdx,
+            });
+
+        // In case a component with the same idx was deleted before, clear it
+        // from the deleted-tracking maps so the new component isn't shadowed
+        // by the prior tombstone.
+        delete this.core.updateInfo.deletedComponents[componentIdx];
+        delete this.core.updateInfo.deletedStateVariables[componentIdx];
+
+        const stateId = serializedComponent.stateId ?? componentIdx.toString();
+        this.core.componentIdxByStateId[stateId] = componentIdx;
+
+        const newComponent = new componentClass({
+            componentIdx,
+            stateId,
+            rootName:
+                this.core.rootNames?.[componentIdx] ??
+                "_id_" + componentIdx.toString(),
+            ancestors,
+            definingChildren,
+            stateVariableDefinitions,
+            serializedChildren: childrenToRemainSerialized,
+            serializedComponent,
+            attributes,
+            componentInfoObjects: this.core.componentInfoObjects,
+            coreFunctions: this.core.coreFunctions,
+            flags: this.core.flags,
+            shadow,
+            numerics: this.core.numerics,
+            sharedParameters,
+            parentSharedParameters,
+            refResolution,
+        });
+
+        this.core.registerComponent(newComponent);
+
+        if (componentsReplacementOf) {
+            newComponent.replacementOf = componentsReplacementOf;
+        }
+
+        if (serializedComponent.adaptedFrom) {
+            // record adapter relationship
+            newComponent.adaptedFrom =
+                this.core._components[serializedComponent.adaptedFrom];
+            newComponent.adaptedFrom.adapterUsed = newComponent;
+        }
+
+        for (const idxStr in prescribedDependencies) {
+            const idx = Number(idxStr);
+            const depArray = prescribedDependencies[idx];
+            for (const dep of depArray) {
+                if (dep.dependencyType === "referenceShadow") {
+                    const shadowInfo = {
+                        componentIdx: idx,
+                    };
+                    Object.assign(shadowInfo, dep);
+                    delete shadowInfo.dependencyType;
+                    newComponent.shadows = shadowInfo;
+
+                    if (dep.firstLevelReplacement) {
+                        newComponent.firstLevelReplacement = true;
+                    }
+
+                    const shadowedComponent = this.core._components[idx];
+                    if (!shadowedComponent.shadowedBy) {
+                        shadowedComponent.shadowedBy = [];
+                    }
+                    shadowedComponent.shadowedBy.push(newComponent);
+
+                    const mediatingShadowComposite =
+                        this.core._components[shadowInfo.compositeIdx];
+                    if (!mediatingShadowComposite.mediatesShadows) {
+                        mediatingShadowComposite.mediatesShadows = [];
+                    }
+                    mediatingShadowComposite.mediatesShadows.push({
+                        shadowing: newComponent.componentIdx,
+                        shadowed: idx,
+                        propVariable: dep.propVariable,
+                    });
+
+                    if (dep.isPrimaryShadow) {
+                        shadowedComponent.primaryShadow =
+                            newComponent.componentIdx;
+
+                        if (
+                            this.core.dependencies.updateTriggers
+                                .primaryShadowDependencies[idx]
+                        ) {
+                            for (const dep of this.core.dependencies
+                                .updateTriggers.primaryShadowDependencies[
+                                idx
+                            ]) {
+                                await dep.recalculateDownstreamComponents();
+                            }
+                        }
+                    }
+
+                    break;
+                }
+            }
+        }
+
+        if (serializedComponent.unlinkedCopySource) {
+            newComponent.unlinkedCopySource =
+                serializedComponent.unlinkedCopySource;
+        }
+
+        await this.core.deriveChildResultsFromDefiningChildren({
+            parent: newComponent,
+            expandComposites: false,
+        });
+
+        await this.core.initializeComponentStateVariables(newComponent);
+
+        await this.core.dependencies.setUpComponentDependencies(newComponent);
+
+        const variablesChanged =
+            await this.core.dependencies.checkForDependenciesOnNewComponent(
+                componentIdx,
+            );
+
+        for (const varDescription of variablesChanged) {
+            await this.core.markStateVariableAndUpstreamDependentsStale({
+                component: this.core._components[varDescription.componentIdx],
+                varName: varDescription.varName,
+            });
+        }
+
+        await this.checkForStateVariablesUpdatesForNewComponent(componentIdx);
+
+        await this.core.dependencies.resolveStateVariablesIfReady({
+            component: newComponent,
+        });
+
+        this.core.recordStateVariablesMustEvaluate(componentIdx);
+
+        await this.core.checkForActionChaining({ component: newComponent });
+
+        this.core.parameterStack.pop();
+
+        const results = { newComponent: newComponent, lastErrorMessage };
+
+        return results;
+    }
+
+    async checkForStateVariablesUpdatesForNewComponent(componentIdx) {
+        let comp = this.core._components[componentIdx];
+        const stateId = comp.stateId;
+        if (
+            stateId in
+            this.core.updateInfo.stateVariableUpdatesForMissingComponents
+        ) {
+            let result = await this.core.processNewStateVariableValues(
+                {
+                    [componentIdx]:
+                        this.core.updateInfo
+                            .stateVariableUpdatesForMissingComponents[stateId],
+                },
+                // This `true` indicates we have a new component
+                true,
+            );
+
+            // In order to make sure that a component takes on the same value
+            // that was saved to the database,
+            // it may be necessary for a component to treat the value received differently
+            // in the first pass of the definition.
+            // Hence, we run the definition of all variables with the extra flag
+            // justUpdatedForNewComponent = true
+            if (
+                comp.constructor.processWhenJustUpdatedForNewComponent ||
+                result.foundIgnore
+            ) {
+                for (let vName in this.core.updateInfo
+                    .stateVariableUpdatesForMissingComponents[stateId]) {
+                    if (comp.state[vName]) {
+                        this.core.updateInfo.stateVariablesToEvaluate.push({
+                            componentIdx,
+                            stateVariable: vName,
+                        });
+                        comp.state[vName].justUpdatedForNewComponent = true;
+                        if (result.foundIgnore) {
+                            // This is a kludge
+                            // The only case so far with ignored children is that Math ignores strings
+                            // (set in inverse definition of expressionWithCodes).
+                            // We need change its value a second time after evaluating
+                            // so that the next time the definition of expressionWithCodes is run,
+                            // the strings don't show any changes and we'll use the essential value
+                            // of expressionWithCodes
+                            comp.reprocessAfterEvaluate =
+                                this.core.updateInfo.stateVariableUpdatesForMissingComponents[
+                                    stateId
+                                ];
+                        }
+                    }
+                }
+            }
+
+            delete this.core.updateInfo
+                .stateVariableUpdatesForMissingComponents[stateId];
+        }
+    }
+
+    findShadowedChildInSerializedComponents({
+        serializedComponents,
+        shadowedComponentName,
+    }) {
+        for (let serializedComponent of serializedComponents) {
+            if (serializedComponent.originalIdx === shadowedComponentName) {
+                return serializedComponent;
+            }
+            if (serializedComponent.children) {
+                let result = this.findShadowedChildInSerializedComponents({
+                    serializedComponents: serializedComponent.children,
+                    shadowedComponentName,
+                });
+                if (result) {
+                    return result;
+                }
+            }
+        }
+
+        return;
+    }
+
+    async addQueuedErrorComponentsFromStateVariables() {
+        if (!this.core.errorComponentsToAdd?.length) {
+            return;
+        }
+
+        const errorComponentsToAdd = this.core.errorComponentsToAdd;
+        this.core.errorComponentsToAdd = [];
+
+        const numberInsertedAfterSource = {};
+
+        for (let errorInfo of errorComponentsToAdd) {
+            let sourceComponent = this.core._components[errorInfo.componentIdx];
+            let parent;
+
+            while (sourceComponent?.parentIdx > 0) {
+                const candidateParent =
+                    this.core._components[sourceComponent.parentIdx];
+
+                if (!candidateParent) {
+                    break;
+                }
+
+                if (candidateParent.constructor.canDisplayChildErrors) {
+                    parent = candidateParent;
+                    break;
+                }
+
+                sourceComponent = candidateParent;
+            }
+
+            if (!parent) {
+                if (this.core.document?.constructor.canDisplayChildErrors) {
+                    parent = this.core.document;
+                }
+            }
+
+            if (!parent) {
+                continue;
+            }
+
+            let indexOfDefiningChildren = parent.definingChildren.length;
+
+            if (sourceComponent?.parentIdx === parent.componentIdx) {
+                const sourceInd = parent.definingChildren.findIndex(
+                    (child) =>
+                        typeof child === "object" &&
+                        child.componentIdx === sourceComponent.componentIdx,
+                );
+
+                if (sourceInd !== -1) {
+                    const numberAlreadyInserted =
+                        numberInsertedAfterSource[
+                            sourceComponent.componentIdx
+                        ] ?? 0;
+                    indexOfDefiningChildren =
+                        sourceInd + 1 + numberAlreadyInserted;
+                    numberInsertedAfterSource[sourceComponent.componentIdx] =
+                        numberAlreadyInserted + 1;
+                }
+            }
+
+            let serializedErrorComponents = [
+                {
+                    type: "serialized",
+                    componentType: "_error",
+                    componentIdx: this.core._components.length,
+                    state: { message: errorInfo.message },
+                    position: errorInfo.position,
+                    sourceDoc: errorInfo.sourceDoc,
+                    children: [],
+                    attributes: {},
+                    doenetAttributes: {},
+                },
+            ];
+
+            this.core._components[this.core._components.length] = undefined;
+
+            let ancestors = [
+                {
+                    componentIdx: parent.componentIdx,
+                    componentClass: parent.constructor,
+                },
+                ...parent.ancestors,
+            ];
+
+            this.core.parameterStack.push(parent.sharedParameters, false);
+            let createResult;
+            try {
+                createResult = await this.createIsolatedComponents({
+                    serializedComponents: serializedErrorComponents,
+                    ancestors,
+                });
+            } finally {
+                this.core.parameterStack.pop();
+            }
+
+            let addResults = await this.core.addChildrenAndRecurseToShadows({
+                parent,
+                indexOfDefiningChildren,
+                newChildren: createResult.components,
+            });
+
+            if (!addResults.success) {
+                throw Error(
+                    "Couldn't add error component from state variable evaluation.",
+                );
+            }
+        }
+    }
+}
diff --git a/packages/doenetml-worker-javascript/src/CompositeExpander.ts b/packages/doenetml-worker-javascript/src/CompositeExpander.ts
new file mode 100644
index 000000000..65be56964
--- /dev/null
+++ b/packages/doenetml-worker-javascript/src/CompositeExpander.ts
@@ -0,0 +1,1193 @@
+import { deepClone } from "@doenet/utils";
+import {
+    addAttributesToSingleReplacement,
+    postProcessCopy,
+    verifyReplacementsMatchSpecifiedType,
+} from "./utils/copy";
+import { preprocessAttributesObject } from "./utils/attributes";
+import {
+    createComponentIndicesFromSerializedChildren,
+    createNewComponentIndices,
+} from "./utils/componentIndices";
+
+/**
+ * Expands composite components into their replacements: walks descendants
+ * looking for unexpanded composites, resolves their `readyToExpand`
+ * dependency, runs the composite's `createSerializedReplacements`,
+ * registers the new replacements with the resolver, propagates expansion
+ * into shadows, swaps replacement composites into the active-children
+ * list during child-result derivation, and marks composite ranges as
+ * active or inactive when their visibility changes.
+ *
+ * Mutually recursive with `ComponentBuilder` (creating components
+ * triggers expansion; expansion creates components). Cross-calls go
+ * through Core's delegators.
+ *
+ * Holds a back-reference to Core to read `_components`,
+ * `componentInfoObjects`, `parameterStack`, `dependencies`, `flags`,
+ * `updateInfo`, `rootNames`, and to invoke the other extracted managers.
+ */
+export class CompositeExpander {
+    core: any;
+
+    constructor({ core }: { core: any }) {
+        this.core = core;
+    }
+
+    async expandAllComposites(component, force = false) {
+        let parentsWithCompositesNotReady =
+            await this.expandCompositesOfDescendants(component, force);
+
+        let expandedAnother = true;
+
+        while (expandedAnother) {
+            expandedAnother = false;
+
+            for (let parentIdx of parentsWithCompositesNotReady) {
+                let parent = this.core._components[parentIdx];
+                let foundReady = false;
+                for (let compositeIdx of parent.unexpandedCompositesNotReady) {
+                    let composite = this.core._components[compositeIdx];
+                    if (composite.state.readyToExpandWhenResolved.isResolved) {
+                        foundReady = true;
+                        break;
+                    } else {
+                        let resolveResult =
+                            await this.core.dependencies.resolveItem({
+                                componentIdx: composite.componentIdx,
+                                type: "stateVariable",
+                                stateVariable: "readyToExpandWhenResolved",
+                                force,
+                                recurseUpstream: true,
+                            });
+
+                        if (resolveResult.success) {
+                            foundReady = true;
+                            break;
+                        }
+                    }
+                }
+
+                if (foundReady) {
+                    let parent = this.core._components[parentIdx];
+                    await this.core.deriveChildResultsFromDefiningChildren({
+                        parent,
+                        expandComposites: true,
+                        forceExpandComposites: force,
+                    });
+                    expandedAnother = true;
+                }
+            }
+        }
+    }
+
+    async expandCompositesOfDescendants(
+        component,
+        forceExpandComposites = false,
+    ) {
+        // Attempt to expand the composites of all descendants, including
+        // attribute components.
+        let parentsWithCompositesNotReady = [];
+
+        if (!component.matchedCompositeChildren) {
+            await this.core.deriveChildResultsFromDefiningChildren({
+                parent: component,
+                expandComposites: true,
+                forceExpandComposites,
+            });
+            if (component.unexpandedCompositesNotReady.length > 0) {
+                parentsWithCompositesNotReady.push(component.componentIdx);
+            } else {
+                await this.core.dependencies.resolveBlockersFromChangedActiveChildren(
+                    component,
+                    forceExpandComposites,
+                );
+            }
+        }
+
+        for (let attrName in component.attributes) {
+            let attrComp = component.attributes[attrName].component;
+            if (attrComp) {
+                let additionalParentsWithNotReady =
+                    await this.expandCompositesOfDescendants(
+                        attrComp,
+                        forceExpandComposites,
+                    );
+                parentsWithCompositesNotReady.push(
+                    ...additionalParentsWithNotReady,
+                );
+            }
+        }
+
+        for (let childIdxStr in component.allChildren) {
+            let child = component.allChildren[childIdxStr].component;
+            if (typeof child !== "object") {
+                continue;
+            }
+
+            let additionalParentsWithNotReady =
+                await this.expandCompositesOfDescendants(
+                    child,
+                    forceExpandComposites,
+                );
+            parentsWithCompositesNotReady.push(
+                ...additionalParentsWithNotReady,
+            );
+        }
+
+        return parentsWithCompositesNotReady;
+    }
+
+    async componentAndRenderedDescendants(component) {
+        if (component?.componentIdx == undefined) {
+            return [];
+        }
+
+        let componentIndices = [component.componentIdx];
+        if (component.constructor.renderChildren) {
+            if (!component.matchedCompositeChildren) {
+                await this.core.deriveChildResultsFromDefiningChildren({
+                    parent: component,
+                    expandComposites: true, //forceExpandComposites: true,
+                });
+            }
+            for (let child of component.activeChildren) {
+                componentIndices.push(
+                    ...(await this.componentAndRenderedDescendants(child)),
+                );
+            }
+        }
+        return componentIndices;
+    }
+
+    async expandCompositeOfDefiningChildren(
+        parent,
+        children,
+        expandComposites,
+        forceExpandComposites,
+    ) {
+        // If a composite is not directly matched by any childGroup, replace
+        // the composite with its replacements, expanding it if not already
+        // expanded.
+        let unexpandedCompositesReady = [];
+        let unexpandedCompositesNotReady = [];
+
+        for (let childInd = 0; childInd < children.length; childInd++) {
+            let child = children[childInd];
+
+            if (
+                child instanceof
+                this.core.componentInfoObjects.allComponentClasses._composite
+            ) {
+                // if composite itself is in the child logic
+                // then don't replace it with its replacements
+                // but leave the composite as an activeChild
+                if (
+                    this.core.findChildGroup(
+                        child.componentType,
+                        parent.constructor,
+                    ).success
+                ) {
+                    continue;
+                }
+
+                // expand composite if it isn't already
+                if (!child.isExpanded) {
+                    if (!child.state.readyToExpandWhenResolved.isResolved) {
+                        if (expandComposites) {
+                            let resolveResult =
+                                await this.core.dependencies.resolveItem({
+                                    componentIdx: child.componentIdx,
+                                    type: "stateVariable",
+                                    stateVariable: "readyToExpandWhenResolved",
+                                    expandComposites, //: forceExpandComposites,
+                                    force: forceExpandComposites,
+                                });
+
+                            if (!resolveResult.success) {
+                                unexpandedCompositesNotReady.push(
+                                    child.componentIdx,
+                                );
+                                this.core.updateInfo.compositesToExpand.add(
+                                    child.componentIdx,
+                                );
+                                continue;
+                            }
+                        } else {
+                            unexpandedCompositesNotReady.push(
+                                child.componentIdx,
+                            );
+                            this.core.updateInfo.compositesToExpand.add(
+                                child.componentIdx,
+                            );
+                            continue;
+                        }
+                    } else if (!expandComposites) {
+                        unexpandedCompositesReady.push(child.componentIdx);
+                        this.core.updateInfo.compositesToExpand.add(
+                            child.componentIdx,
+                        );
+                        continue;
+                    }
+
+                    // will either succeed or throw error since is ready to expand
+                    await this.expandCompositeComponent(child);
+                }
+
+                // recurse on replacements
+                let result = await this.expandCompositeOfDefiningChildren(
+                    parent,
+                    child.replacements,
+                    expandComposites,
+                    forceExpandComposites,
+                );
+
+                unexpandedCompositesReady.push(
+                    ...result.unexpandedCompositesReady,
+                );
+                unexpandedCompositesNotReady.push(
+                    ...result.unexpandedCompositesNotReady,
+                );
+            }
+        }
+
+        return { unexpandedCompositesReady, unexpandedCompositesNotReady };
+    }
+
+    async expandCompositeComponent(component) {
+        if (!("readyToExpandWhenResolved" in component.state)) {
+            throw Error(
+                `Could not find state variable readyToExpandWhenResolved of composite ${component.componentIdx}`,
+            );
+        }
+
+        if (!component.state.readyToExpandWhenResolved.isResolved) {
+            this.core.updateInfo.compositesToExpand.add(component.componentIdx);
+            return { success: false };
+        }
+
+        this.core.updateInfo.compositesToExpand.delete(component.componentIdx);
+
+        this.core.updateInfo.compositesBeingExpanded.push(
+            component.componentIdx,
+        );
+
+        if (component.parent) {
+            if (component.parent.unexpandedCompositesReady) {
+                let ind = component.parent.unexpandedCompositesReady.indexOf(
+                    component.componentIdx,
+                );
+                if (ind !== -1) {
+                    component.parent.unexpandedCompositesReady.splice(ind, 1);
+                }
+            }
+            if (component.parent.unexpandedCompositesNotReady) {
+                let ind = component.parent.unexpandedCompositesNotReady.indexOf(
+                    component.componentIdx,
+                );
+                if (ind !== -1) {
+                    component.parent.unexpandedCompositesNotReady.splice(
+                        ind,
+                        1,
+                    );
+                }
+            }
+        }
+
+        if (
+            component.shadows &&
+            !component.shadows.propVariable &&
+            !component.constructor.doNotExpandAsShadowed
+            //&&
+            // this.core.componentInfoObjects.isCompositeComponent({
+            //   componentType: component.componentType,
+            //   includeNonStandard: false,
+            // })
+        ) {
+            return await this.expandShadowingComposite(component);
+        }
+
+        // Call the static function createSerializedReplacements from the composite component
+        // which returns an object containing a key "replacements" with value an array
+        // of serialized components that will be turned into real components.
+        // The replacement components will be used to replace
+        // the composite itself as children for the composite's parent
+        // Arguments
+        // component: the composite component
+        // components: all components in the document
+        // workspace: an initially empty object that a composite can use to store information that will then
+        //   be provided when updating composite replacements via calculateReplacementChanges
+        // componentInfoObjects
+        // flags
+        // resolveItem: a function that the composite can use to resolve any state variables
+        // publicCaseInsensitiveAliasSubstitutions: a function that can be used to find a case insensitive match
+        //   to a public state variable, substituting aliases if necessary
+        let initialNComponents;
+        let result;
+        const originalWorkspace = { ...component.replacementsWorkspace };
+
+        do {
+            initialNComponents = this.core._components.length;
+            component.replacementsWorkspace = { ...originalWorkspace };
+            result = await component.constructor.createSerializedReplacements({
+                component: this.core._components[component.componentIdx], // to create proxy
+                components: this.core._components,
+                nComponents: this.core._components.length,
+                workspace: component.replacementsWorkspace,
+                componentInfoObjects: this.core.componentInfoObjects,
+                allDoenetMLs: this.core.allDoenetMLs,
+                flags: this.core.flags,
+                resolveItem: this.core.dependencies.resolveItem.bind(
+                    this.core.dependencies,
+                ),
+                publicCaseInsensitiveAliasSubstitutions:
+                    this.core.publicCaseInsensitiveAliasSubstitutions.bind(
+                        this.core,
+                    ),
+            });
+
+            // If `this.core._components` changed in length while `createSerializedReplacements` was executing,
+            // it means that some other action (like calling another `createSerializedReplacements`)
+            // occurred while resolving state variables.
+            // Since this would lead to collisions in assigned component indices, we rerun `createSerializedReplacements`.
+            // TODO: are there any scenarios where this will lead to an infinite loop?
+        } while (this.core._components.length !== initialNComponents);
+
+        const newNComponents = result.nComponents;
+
+        if (
+            !(
+                Number.isInteger(newNComponents) &&
+                newNComponents >= this.core._components.length
+            )
+        ) {
+            throw Error(
+                `Invalid nComponents returned by createSerializedReplacements for ${component.componentType}: `,
+                newNComponents,
+            );
+        }
+
+        let position = this.core._components[component.componentIdx].position;
+        let sourceDoc = this.core._components[component.componentIdx].sourceDoc;
+        let overwriteDoenetMLRange = component.componentType === "_copy";
+
+        this.core.gatherDiagnosticsAndAssignDoenetMLRange({
+            components: result.replacements,
+            diagnostics: result.diagnostics,
+            position,
+            sourceDoc,
+            overwriteDoenetMLRange,
+        });
+
+        if (component.constructor.stateVariableToEvaluateAfterReplacements) {
+            await component.stateValues[
+                component.constructor.stateVariableToEvaluateAfterReplacements
+            ];
+        }
+
+        if (result.replacements) {
+            let serializedReplacements = result.replacements;
+
+            await this.core.addReplacementsToResolver({
+                serializedReplacements,
+                component,
+            });
+
+            // expand `this.core._components` to length `newNComponents` so that the component indices will not be reused
+            if (newNComponents > this.core._components.length) {
+                this.core._components[newNComponents - 1] = undefined;
+            }
+
+            await this.createAndSetReplacements({
+                component,
+                serializedReplacements,
+            });
+        } else {
+            throw Error(
+                `Invalid createSerializedReplacements of ${component.componentIdx}`,
+            );
+        }
+
+        // record that are finished expanding the composite
+        let targetInd = this.core.updateInfo.compositesBeingExpanded.indexOf(
+            component.componentIdx,
+        );
+        if (targetInd === -1) {
+            throw Error(
+                `Something is wrong as we lost track that we were expanding ${component.componentIdx}`,
+            );
+        }
+        this.core.updateInfo.compositesBeingExpanded.splice(targetInd, 1);
+
+        return { success: true, compositesExpanded: [component.componentIdx] };
+    }
+
+    async expandShadowingComposite(component) {
+        if (
+            this.core.updateInfo.compositesBeingExpanded.includes(
+                component.shadows.componentIdx,
+            )
+        ) {
+            // found a circular dependency,
+            // as we are in the middle of expanding a composite
+            // that we are now trying to shadow
+            let compositeInvolved =
+                this.core._components[component.shadows.componentIdx];
+            // find non-shadow for error message, as that would be a component from document
+            while (compositeInvolved.shadows) {
+                compositeInvolved =
+                    this.core._components[
+                        compositeInvolved.shadows.componentIdx
+                    ];
+            }
+            throw Error(
+                `Circular dependency involving ${compositeInvolved.componentIdx}.`,
+            );
+        }
+
+        let shadowedComposite =
+            this.core._components[component.shadows.componentIdx];
+        let compositesExpanded = [];
+
+        if (!shadowedComposite.isExpanded) {
+            let result = await this.expandCompositeComponent(shadowedComposite);
+
+            if (!result.success) {
+                throw Error(
+                    `expand result of ${component.componentIdx} was not a success even though ready to expand.`,
+                );
+            }
+            compositesExpanded.push(...result.compositesExpanded);
+        }
+
+        // we'll copy the replacements of the shadowed composite
+        // and make those be the replacements of the shadowing composite
+        let serializedReplacements = [];
+
+        if (component.replacementsWorkspace.replacementsCreated === undefined) {
+            component.replacementsWorkspace.replacementsCreated = 0;
+        }
+
+        const stateIdInfo = {
+            prefix: `${component.stateId}|`,
+            num: component.replacementsWorkspace.replacementsCreated,
+        };
+
+        let nComponents = this.core._components.length;
+        let newNComponents = nComponents;
+
+        // We address one complication from shadowing a component with copied in children.
+        // In this case, the name resolver will already have the component indices of the serialized children of `component`.
+        // The corresponding replacements of `component` should have those component indices.
+        // However, those replacements already exist in the replacements of `shadowedComposite` which we are copying.
+        // As a workaround, we create a map from the indices of the children of `shadowedComposite`
+        // to the indices of the children of `component` and override the component indices created on the new replacements.
+        const idxMapOverride = {};
+        const copyInChildren =
+            shadowedComposite.attributes.copyInChildren?.primitive.value;
+        if (copyInChildren) {
+            const componentChildren = JSON.parse(
+                JSON.stringify(component.serializedChildren),
+            );
+            const shadowedChildren = JSON.parse(
+                JSON.stringify(shadowedComposite.serializedChildren),
+            );
+
+            // We are reusing this code that maps indices from serialized components to get the map
+            // from indices of `shadowedChildren` to indices of `componentChildren`.
+            const res = createComponentIndicesFromSerializedChildren(
+                shadowedChildren,
+                componentChildren,
+                newNComponents,
+            );
+
+            for (const idx in res.idxMap) {
+                // the above code might also have created new indices, which we ignore
+                if (res.idxMap[idx] < newNComponents) {
+                    idxMapOverride[idx] = res.idxMap[idx];
+                }
+            }
+        }
+
+        for (let [idx, repl] of shadowedComposite.replacements.entries()) {
+            if (typeof repl === "object") {
+                const serializedComponent = await repl.serialize();
+
+                if (
+                    component.constructor.useSerializedChildrenComponentIndices
+                ) {
+                    const res = createComponentIndicesFromSerializedChildren(
+                        [serializedComponent],
+                        [component.serializedChildren[idx]],
+                        newNComponents,
+                        stateIdInfo,
+                    );
+                    newNComponents = res.nComponents;
+
+                    serializedReplacements.push(...res.components);
+                } else {
+                    const res = createNewComponentIndices(
+                        [serializedComponent],
+                        newNComponents,
+                        stateIdInfo,
+                        idxMapOverride,
+                    );
+                    newNComponents = res.nComponents;
+
+                    serializedReplacements.push(...res.components);
+                }
+            } else {
+                serializedReplacements.push(repl);
+            }
+        }
+
+        if (component.constructor.addExtraSerializedChildrenWhenShadowing) {
+            let rendered = true;
+            if ("rendered" in component.state) {
+                rendered = await component.state.rendered.value;
+            }
+
+            if (rendered) {
+                // add any serialized children that are beyond the replacements we already have
+                serializedReplacements.push(
+                    ...deepClone(
+                        component.serializedChildren.slice(
+                            serializedReplacements.length,
+                        ),
+                    ),
+                );
+            }
+        }
+
+        this.adjustForCreateComponentIdxName(serializedReplacements, component);
+
+        // Have three composites involved:
+        // 1. the shadowing composite (component, the one we're trying to expand)
+        // 2. the shadowed composite
+        // 3. the composite mediating the shadowing
+        //    (of which shadowing composite is the replacement)
+
+        let nameOfCompositeMediatingTheShadow = component.shadows.compositeIdx;
+        let compositeMediatingTheShadow =
+            this.core._components[nameOfCompositeMediatingTheShadow];
+        serializedReplacements = postProcessCopy({
+            serializedComponents: serializedReplacements,
+            componentIdx: nameOfCompositeMediatingTheShadow,
+        });
+
+        // If shadowed composite mediates the shadow of compositeMediatingTheShadow,
+        // then we have a circular reference.
+        // mediatesShadows is an array of objects with keys shadows and shadowed,
+        // that the shadow mediated by the component.
+        // We check if shadowedComposite mediates the shadow of compositeMediatingTheShadow,
+        // or, recursively, if one of those shadowed components
+        // mediates the shadow of compositeMediatingTheShadow
+
+        let foundCircular = false;
+        let shadowedByShadowed = shadowedComposite.mediatesShadows
+            ?.filter((v) => v.propVariable === undefined)
+            .map((v) => v.shadowed);
+
+        while (shadowedByShadowed?.length > 0) {
+            if (
+                shadowedByShadowed.includes(nameOfCompositeMediatingTheShadow)
+            ) {
+                foundCircular = true;
+                let message = "Circular dependency detected";
+                if (component.attributes.createComponentOfType?.primitive) {
+                    message += ` involving \`<${component.attributes.createComponentOfType.primitive.value}>\` component`;
+                }
+                message += ".";
+                serializedReplacements = [
+                    {
+                        type: "serialized",
+                        componentType: "_error",
+                        componentIdx: newNComponents++,
+                        attributes: {},
+                        doenetAttributes: {},
+                        children: [],
+                        state: { message },
+                        position: compositeMediatingTheShadow.position,
+                        sourceDoc: compositeMediatingTheShadow.sourceDoc,
+                    },
+                ];
+                this.core.addDiagnostic({
+                    type: "error",
+                    message,
+                    position: compositeMediatingTheShadow.position,
+                    sourceDoc: compositeMediatingTheShadow.sourceDoc,
+                });
+
+                break;
+            }
+
+            // recurse to check if one the shadowed components mediates
+            // the shadow of compositeMediatingTheShadow
+            shadowedByShadowed = shadowedByShadowed.reduce((acc, cIdx) => {
+                let comp = this.core._components[cIdx];
+                if (comp?.mediatesShadows) {
+                    return [
+                        ...acc,
+                        ...comp.mediatesShadows
+                            .filter((v) => v.propVariable === undefined)
+                            .map((v) => v.shadowed),
+                    ];
+                } else {
+                    return acc;
+                }
+            }, []);
+        }
+
+        // XXX: what is the replacement for targetComponentIdx?
+        // let target =
+        //     this.core._components[
+        //         compositeMediatingTheShadow.doenetAttributes.targetComponentIdx
+        //     ];
+
+        // if (
+        //     target?.componentIdx === shadowedComposite.componentIdx &&
+        //     compositeMediatingTheShadow.attributes.copyInChildren?.primitive
+        //         .value
+        // ) {
+        //     let newReplacements = deepClone(
+        //         compositeMediatingTheShadow.serializedChildren,
+        //     );
+        //     let componentClass =
+        //         this.core.componentInfoObjects.allComponentClasses[
+        //             component.componentType
+        //         ];
+
+        //     if (!componentClass.includeBlankStringChildren) {
+        //         newReplacements = newReplacements.filter(
+        //             (x) => typeof x !== "string" || x.trim() !== "",
+        //         );
+        //     }
+
+        //     serializedReplacements.push(...newReplacements);
+        // }
+
+        if (!foundCircular) {
+            if (
+                component.replacementsWorkspace.replacementsCreated ===
+                undefined
+            ) {
+                component.replacementsWorkspace.replacementsCreated = 0;
+            }
+
+            let verificationResult = await verifyReplacementsMatchSpecifiedType(
+                {
+                    component,
+                    replacements: serializedReplacements,
+                    componentInfoObjects: this.core.componentInfoObjects,
+                    compositeAttributesObj: preprocessAttributesObject(
+                        component.constructor.createAttributesObject(),
+                    ),
+                    components: this.core._components,
+                    nComponents: newNComponents,
+                    stateIdInfo,
+                    publicCaseInsensitiveAliasSubstitutions:
+                        this.core.publicCaseInsensitiveAliasSubstitutions.bind(
+                            this.core,
+                        ),
+                },
+            );
+
+            for (const error of verificationResult.diagnostics) {
+                this.core.addDiagnostic({
+                    ...error,
+                    type: "error",
+                });
+            }
+            for (const warning of verificationResult.diagnostics) {
+                this.core.addDiagnostic({
+                    ...warning,
+                    type: "warning",
+                });
+            }
+
+            newNComponents = verificationResult.nComponents;
+
+            serializedReplacements = verificationResult.replacements;
+
+            addAttributesToSingleReplacement(
+                serializedReplacements,
+                component,
+                this.core.componentInfoObjects,
+            );
+        }
+
+        component.replacementsWorkspace.replacementsCreated = stateIdInfo.num;
+
+        await this.core.addReplacementsToResolver({
+            serializedReplacements,
+            component,
+        });
+
+        // expand `this.core._components` to length `newNComponents` so that the component indices will not be reused
+        if (newNComponents > this.core._components.length) {
+            this.core._components[newNComponents - 1] = undefined;
+        }
+
+        await this.createAndSetReplacements({
+            component,
+            serializedReplacements,
+        });
+
+        if (shadowedComposite.replacementsToWithhold > 0) {
+            component.replacementsToWithhold =
+                shadowedComposite.replacementsToWithhold;
+        }
+
+        // record that are finished expanding the composite
+        let targetInd = this.core.updateInfo.compositesBeingExpanded.indexOf(
+            component.componentIdx,
+        );
+        if (targetInd === -1) {
+            throw Error(
+                `Something is wrong as we lost track that we were expanding ${component.componentIdx}`,
+            );
+        }
+        this.core.updateInfo.compositesBeingExpanded.splice(targetInd, 1);
+
+        compositesExpanded.push(component.componentIdx);
+
+        return { success: true, compositesExpanded };
+    }
+
+    /**
+     * If `composite` has `createComponentIdx` specified,
+     * then its one replacement should have the componentIdx.
+     * Similarly, if it has `createComponentName` specified,
+     * then its one replacement should receive that name.
+     */
+    adjustForCreateComponentIdxName(serializedReplacements, composite) {
+        if (serializedReplacements.length === 1) {
+            if (
+                composite.attributes.createComponentIdx?.primitive.value !=
+                undefined
+            ) {
+                serializedReplacements[0].componentIdx =
+                    composite.attributes.createComponentIdx.primitive.value;
+            }
+
+            if (
+                composite.attributes.createComponentName?.primitive.value !=
+                undefined
+            ) {
+                serializedReplacements[0].attributes.name = {
+                    type: "primitive",
+                    name: "name",
+                    primitive: {
+                        type: "string",
+                        value: composite.attributes.createComponentName
+                            .primitive.value,
+                    },
+                };
+            }
+        }
+    }
+
+    async createAndSetReplacements({ component, serializedReplacements }) {
+        this.core.parameterStack.push(component.sharedParameters, false);
+
+        try {
+            let replacementResult = await this.core.createIsolatedComponents({
+                serializedComponents: serializedReplacements,
+                ancestors: component.ancestors,
+                shadow: true,
+                componentsReplacementOf: component,
+            });
+            component.replacements = replacementResult.components;
+        } catch (e) {
+            console.error(e);
+            // throw e;
+            component.replacements = await this.core.setErrorReplacements({
+                composite: component,
+                message: e.message,
+            });
+        }
+        this.core.parameterStack.pop();
+
+        await this.core.dependencies.addBlockersFromChangedReplacements(
+            component,
+        );
+
+        component.isExpanded = true;
+    }
+
+    async replaceCompositeChildren(parent) {
+        // If a composite is not directly matched by any childGroup, replace
+        // the composite with its replacements, expanding it if not already
+        // expanded.
+        delete parent.placeholderActiveChildrenIndices;
+        delete parent.placeholderActiveChildrenIndicesByComposite;
+        delete parent.compositeReplacementActiveRange;
+
+        let undisplayableErrorChildren;
+
+        let nPlaceholdersAdded = 0;
+
+        for (
+            let childInd = 0;
+            childInd < parent.activeChildren.length;
+            childInd++
+        ) {
+            let child = parent.activeChildren[childInd];
+
+            if (
+                child instanceof
+                this.core.componentInfoObjects.allComponentClasses._composite
+            ) {
+                // if composite itself is in the child logic
+                // then don't replace it with its replacements
+                // but leave the composite as an activeChild
+                if (
+                    this.core.findChildGroup(
+                        child.componentType,
+                        parent.constructor,
+                    ).success
+                ) {
+                    continue;
+                }
+
+                let replaceWithPlaceholders = false;
+
+                // if an unexpanded composite has a createComponentOfType specified
+                // replace with placeholders
+                // otherwise, leave composite as an activeChild
+                if (!child.isExpanded) {
+                    if (child.attributes.createComponentOfType?.primitive) {
+                        replaceWithPlaceholders = true;
+                    } else {
+                        continue;
+                    }
+                }
+
+                let replacements;
+
+                if (replaceWithPlaceholders) {
+                    let numComponents;
+
+                    if (child.attributes.numComponents) {
+                        numComponents =
+                            child.attributes.numComponents.primitive.value;
+                    } else {
+                        numComponents = 1;
+                    }
+
+                    let componentType =
+                        this.core.componentInfoObjects
+                            .componentTypeLowerCaseMapping[
+                            child.attributes.createComponentOfType.primitive.value.toLowerCase()
+                        ];
+                    replacements = [];
+
+                    for (let i = 0; i < numComponents; i++) {
+                        replacements.push({
+                            componentType,
+                            fromComposite: child.componentIdx,
+                            placeholderInd: nPlaceholdersAdded,
+                        });
+                        nPlaceholdersAdded++;
+                    }
+
+                    parent.hasPlaceholderActiveChildren = true;
+                    let placeholdInds = [...Array(numComponents).keys()].map(
+                        (x) => x + childInd,
+                    );
+
+                    if (!parent.placeholderActiveChildrenIndices) {
+                        parent.placeholderActiveChildrenIndices = [];
+                    }
+                    parent.placeholderActiveChildrenIndices.push(
+                        ...placeholdInds,
+                    );
+
+                    if (!parent.placeholderActiveChildrenIndicesByComposite) {
+                        parent.placeholderActiveChildrenIndicesByComposite = {};
+                    }
+                    parent.placeholderActiveChildrenIndicesByComposite[
+                        child.componentIdx
+                    ] = placeholdInds;
+                } else {
+                    // don't use any replacements that are marked as being withheld
+                    await this.markWithheldReplacementsInactive(child);
+
+                    replacements = child.replacements;
+                    if (child.replacementsToWithhold > 0) {
+                        replacements = replacements.slice(
+                            0,
+                            -child.replacementsToWithhold,
+                        );
+                    }
+
+                    // don't include blank string replacements if parent excludes blank children
+                    if (
+                        !parent.constructor.includeBlankStringChildren ||
+                        parent.constructor.removeBlankStringChildrenPostSugar
+                    ) {
+                        replacements = replacements.filter(
+                            (x) => typeof x !== "string" || /\S/.test(x),
+                        );
+                    }
+                }
+
+                if (!parent.compositeReplacementActiveRange) {
+                    parent.compositeReplacementActiveRange = [];
+                }
+
+                // Record whether or not each component can be considered an element of a list.
+                // If this composite or a containing composite has asList set,
+                // then it may be turned into a list if all the components can be list elements.
+
+                // All inline components and any components with canBeInList set
+                // are considered potential components for a list.
+                let replacementsCanBeInList = replacements.map((repl) =>
+                    Boolean(
+                        typeof repl !== "object" ||
+                        (this.core.componentInfoObjects.isInheritedComponentType(
+                            {
+                                inheritedComponentType: repl.componentType,
+                                baseComponentType: "_inline",
+                            },
+                        ) &&
+                            repl.constructor.canBeInList !== false) ||
+                        repl.constructor.canBeInList,
+                    ),
+                );
+
+                for (let otherCompositeObject of parent.compositeReplacementActiveRange) {
+                    if (otherCompositeObject.lastInd >= childInd) {
+                        otherCompositeObject.lastInd += replacements.length - 1;
+                        otherCompositeObject.potentialListComponents.splice(
+                            childInd,
+                            1,
+                            ...replacementsCanBeInList,
+                        );
+                    }
+                }
+
+                if (
+                    replacements.some(
+                        (repl) => repl.componentType === "_error",
+                    ) &&
+                    !parent.constructor.canDisplayChildErrors
+                ) {
+                    // The composite returned an error but this parent cannot display child errors,
+                    // so remove it from the replacements
+                    // (to avoid a confusing warning about an invalid _error child)
+                    // and store it in undisplayableErrorChildren.
+                    // We will add these error children to an ancestor that can display them, below.
+
+                    if (!undisplayableErrorChildren) {
+                        undisplayableErrorChildren = [];
+                    }
+                    let errorReplacements = replacements.filter(
+                        (repl) => repl.componentType === "_error",
+                    );
+                    replacements = replacements.filter(
+                        (repl) => repl.componentType !== "_error",
+                    );
+                    undisplayableErrorChildren.push(...errorReplacements);
+                }
+
+                // compositeReplacementActiveRange will be used
+                // - in renderers to determined if they should add commas
+                // - in child dependencies, where they will be translated for matched children
+                //   and used in some components to determine if those children can be formed into a list
+                if (child.isExpanded) {
+                    parent.compositeReplacementActiveRange.push({
+                        compositeIdx: child.componentIdx,
+                        compositeName:
+                            this.core.rootNames?.[child.componentIdx] ??
+                            "_id_" + child.componentIdx.toString(),
+                        extendIdx: await child.stateValues.extendIdx,
+                        unresolvedPath: await child.stateValues.unresolvedPath,
+                        firstInd: childInd,
+                        lastInd: childInd + replacements.length - 1,
+                        asList: await child.stateValues.asList,
+                        potentialListComponents: replacementsCanBeInList,
+                    });
+                }
+
+                parent.activeChildren.splice(childInd, 1, ...replacements);
+
+                // Update allChildren object with info on composite and its replacemnts
+                let allChildrenObj = parent.allChildren[child.componentIdx];
+                delete allChildrenObj.activeChildrenIndex;
+                for (let ind2 = 0; ind2 < replacements.length; ind2++) {
+                    let replacement = replacements[ind2];
+                    if (replacement.componentIdx != undefined) {
+                        // ignore placeholder, string, and primitive number active children
+                        parent.allChildren[replacement.componentIdx] = {
+                            activeChildrenIndex: childInd + ind2,
+                            component: replacement,
+                        };
+                    }
+                }
+
+                // find index of child in allChildrenOrdered
+                // and place replacements immediately afterward
+                let ind2 = parent.allChildrenOrdered.indexOf(
+                    child.componentIdx,
+                );
+                parent.allChildrenOrdered.splice(
+                    ind2 + 1,
+                    0,
+                    ...replacements
+                        .filter((x) => typeof x === "object")
+                        .map((x) =>
+                            x.componentIdx ? x.componentIdx : x.placeholderInd,
+                        ),
+                );
+
+                if (replacements.length !== 1) {
+                    // if replaced composite with anything other than one replacement
+                    // shift activeChildrenIndices of later children
+                    let nShift = replacements.length - 1;
+                    for (
+                        let ind2 = childInd + replacements.length;
+                        ind2 < parent.activeChildren.length;
+                        ind2++
+                    ) {
+                        let child2 = parent.activeChildren[ind2];
+                        if (child2.componentIdx != undefined) {
+                            parent.allChildren[
+                                child2.componentIdx
+                            ].activeChildrenIndex += nShift;
+                        }
+                    }
+                }
+
+                // rewind one index, in case any of the new activeChildren are composites
+                childInd--;
+            }
+        }
+
+        if (undisplayableErrorChildren) {
+            await this.addUndisplayableErrorChildrenToAncestor(
+                parent,
+                undisplayableErrorChildren,
+            );
+        }
+    }
+
+    async addUndisplayableErrorChildrenToAncestor(
+        parent,
+        undisplayableErrorChildren,
+    ) {
+        // If parent had an error added by a composite, but it can't display errors,
+        // then look for an ancestor that can display errors
+        // (which will exist since document can display errors).
+        // Add the errors to the defining children of that ancestor.
+        // Note: this breaks the rules of DoenetML and
+        // it is possible that these errors will accumulate in the ancestor
+        // if this code is repeated. But, the DoenetML is broken anyway with errors,
+        // and the purpose is just to make sure that the error is prominently displayed.
+
+        let ancestorToDisplayErrors = parent;
+        let definingChildIndToAddError;
+        while (!ancestorToDisplayErrors.constructor.canDisplayChildErrors) {
+            let nextAncestor =
+                this.core._components[ancestorToDisplayErrors.parentIdx];
+
+            definingChildIndToAddError = nextAncestor.definingChildren.indexOf(
+                ancestorToDisplayErrors,
+            );
+
+            ancestorToDisplayErrors = nextAncestor;
+        }
+
+        // if child wasn't a defining child, put the error as the first child
+        if (definingChildIndToAddError === -1) {
+            definingChildIndToAddError = 0;
+        }
+
+        ancestorToDisplayErrors.definingChildren.splice(
+            definingChildIndToAddError,
+            0,
+            ...undisplayableErrorChildren,
+        );
+
+        await this.core.processNewDefiningChildren({
+            parent: ancestorToDisplayErrors,
+            expandComposites: false,
+        });
+    }
+
+    async markWithheldReplacementsInactive(composite) {
+        let numActive = composite.replacements.length;
+
+        if (await composite.stateValues.isInactiveCompositeReplacement) {
+            numActive = 0;
+        } else if (composite.replacementsToWithhold > 0) {
+            numActive -= composite.replacementsToWithhold;
+        }
+
+        for (let repl of composite.replacements.slice(0, numActive)) {
+            await this.changeInactiveComponentAndDescendants(repl, false);
+        }
+
+        for (let repl of composite.replacements.slice(numActive)) {
+            await this.changeInactiveComponentAndDescendants(repl, true);
+        }
+
+        // composite is newly active
+        // if updates to replacements were postponed
+        // add them back to the queue
+        if (!(await composite.stateValues.isInactiveCompositeReplacement)) {
+            let cIdx = composite.componentIdx;
+            if (
+                this.core.updateInfo.inactiveCompositesToUpdateReplacements.has(
+                    cIdx,
+                )
+            ) {
+                this.core.updateInfo.inactiveCompositesToUpdateReplacements.delete(
+                    cIdx,
+                );
+                this.core.updateInfo.compositesToUpdateReplacements.add(cIdx);
+            }
+        }
+    }
+
+    async changeInactiveComponentAndDescendants(component, inactive) {
+        if (typeof component !== "object") {
+            return;
+        }
+
+        if (
+            (await component.stateValues.isInactiveCompositeReplacement) !==
+            inactive
+        ) {
+            component.state.isInactiveCompositeReplacement.value = inactive;
+            await this.core.markUpstreamDependentsStale({
+                component,
+                varName: "isInactiveCompositeReplacement",
+            });
+            this.core.dependencies.recordActualChangeInUpstreamDependencies({
+                component,
+                varName: "isInactiveCompositeReplacement",
+            });
+            for (const childIdxStr in component.allChildren) {
+                await this.changeInactiveComponentAndDescendants(
+                    this.core._components[childIdxStr],
+                    inactive,
+                );
+            }
+
+            for (let attrName in component.attributes) {
+                let attrComp = component.attributes[attrName].component;
+                if (attrComp) {
+                    await this.changeInactiveComponentAndDescendants(
+                        this.core._components[attrComp.componentIdx],
+                        inactive,
+                    );
+                }
+            }
+
+            if (component.replacements) {
+                await this.markWithheldReplacementsInactive(component);
+            }
+        }
+    }
+}
diff --git a/packages/doenetml-worker-javascript/src/Core.js b/packages/doenetml-worker-javascript/src/Core.js
index 6f88cf6fb..ac585b811 100644
--- a/packages/doenetml-worker-javascript/src/Core.js
+++ b/packages/doenetml-worker-javascript/src/Core.js
@@ -30,7 +30,9 @@ import { DependencyHandler } from "./Dependencies";
 import { ActionTriggerScheduler } from "./ActionTriggerScheduler";
 import { AutoSubmitManager } from "./AutoSubmitManager";
 import { ChildMatcher } from "./ChildMatcher";
+import { ComponentBuilder } from "./ComponentBuilder";
 import { ComponentLifecycle } from "./ComponentLifecycle";
+import { CompositeExpander } from "./CompositeExpander";
 import { DeletionEngine } from "./DeletionEngine";
 import { DiagnosticsManager } from "./DiagnosticsManager";
 import { NavigationHandler } from "./NavigationHandler";
@@ -38,6 +40,8 @@ import { ProcessQueue } from "./ProcessQueue";
 import { RendererInstructionBuilder } from "./RendererInstructionBuilder";
 import { ResolverAdapter } from "./ResolverAdapter";
 import { StatePersistence } from "./StatePersistence";
+import { StateVariableDefinitionFactory } from "./StateVariableDefinitionFactory";
+import { StateVariableInitializer } from "./StateVariableInitializer";
 import { VisibilityTracker } from "./VisibilityTracker";
 import * as nameResolver from "./StateVariableNameResolver";
 import {
@@ -56,11 +60,13 @@ import {
 // (DiagnosticsManager, VisibilityTracker, StatePersistence, AutoSubmitManager,
 // NavigationHandler, ResolverAdapter, RendererInstructionBuilder,
 // ProcessQueue, ComponentLifecycle, ChildMatcher, DeletionEngine,
-// ActionTriggerScheduler, and the `nameResolver` namespace). Core retains
-// thin wrapper methods so the public surface — used by CoreWorker,
-// `coreFunctions`-bound references, components, and tests — keeps working.
-// Each delegating block is grouped near its original location and tagged with
-// a `// → managerName` marker; see the corresponding module for details.
+// ActionTriggerScheduler, StateVariableDefinitionFactory,
+// StateVariableInitializer, ComponentBuilder, CompositeExpander, and the
+// `nameResolver` namespace). Core retains thin wrapper methods so the public
+// surface — used by CoreWorker, `coreFunctions`-bound references, components,
+// and tests — keeps working. Each delegating block is grouped near its
+// original location and tagged with a `// → managerName` marker; see the
+// corresponding module for details.
 
 export default class Core {
     constructor({
@@ -216,6 +222,15 @@ export default class Core {
         this.actionTriggerScheduler = new ActionTriggerScheduler({
             core: this,
         });
+        this.stateVariableDefinitionFactory =
+            new StateVariableDefinitionFactory({
+                core: this,
+            });
+        this.stateVariableInitializer = new StateVariableInitializer({
+            core: this,
+        });
+        this.componentBuilder = new ComponentBuilder({ core: this });
+        this.compositeExpander = new CompositeExpander({ core: this });
 
         // console.time('serialize doenetML');
 
@@ -514,230 +529,33 @@ export default class Core {
         return this.diagnosticsManager.getSourceLocationForComponent(component);
     }
 
-    async addComponents({
-        serializedComponents,
-        parentIdx,
-        indexOfDefiningChildren,
-        initialAdd = false,
-    }) {
-        this.initialAddPhase = initialAdd;
-
-        if (!Array.isArray(serializedComponents)) {
-            serializedComponents = [serializedComponents];
-        }
-
-        let parent;
-        let ancestors = [];
-
-        if (!initialAdd) {
-            parent = this._components[parentIdx];
-            if (!parent) {
-                this.addDiagnostic({
-                    type: "warning",
-                    message: `Cannot add children to parent ${parentIdx} as ${parentIdx} does not exist`,
-                });
-                return [];
-            }
-
-            ancestors = [
-                {
-                    componentIdx: parentIdx,
-                    componentClass: parent.constructor,
-                },
-                ...parent.ancestors,
-            ];
-
-            this.parameterStack.push(parent.sharedParameters, false);
-
-            if (!this.nTimesAddedComponents) {
-                this.nTimesAddedComponents = 1;
-            } else {
-                this.nTimesAddedComponents++;
-            }
-
-            this.addComponentsToResolver(serializedComponents, parentIdx);
-        }
-        let createResult = await this.createIsolatedComponents({
-            serializedComponents,
-            ancestors,
-        });
-        if (!initialAdd) {
-            this.parameterStack.pop();
-        }
-
-        const newComponents = createResult.components;
-
-        let deletedComponents = {};
-        let addedComponents = {};
-        newComponents.forEach((x) => (addedComponents[x.componentIdx] = x));
-
-        if (initialAdd) {
-            if (newComponents.length !== 1) {
-                throw Error(
-                    "Initial components need to be an array of just one component.",
-                );
-            }
-            // this.setAncestors(newComponents[0]);
-            this.document = newComponents[0];
-
-            await this.expandAllComposites(this.document);
-
-            await this.expandAllComposites(this.document, true);
-
-            if (this.updateInfo.stateVariablesToEvaluate) {
-                let stateVariablesToEvaluate =
-                    this.updateInfo.stateVariablesToEvaluate;
-                this.updateInfo.stateVariablesToEvaluate = [];
-                for (let {
-                    componentIdx,
-                    stateVariable,
-                } of stateVariablesToEvaluate) {
-                    let comp = this._components[componentIdx];
-                    if (comp && comp.state[stateVariable]) {
-                        await this.getStateVariableValue({
-                            component: comp,
-                            stateVariable,
-                        });
-                    }
-                }
-            }
-
-            await this.addQueuedErrorComponentsFromStateVariables();
-
-            // calculate any replacement changes on composites touched
-            await this.replacementChangesFromCompositesToUpdate();
-
-            let results = await this.initializeRenderedComponentInstruction(
-                this.document,
-            );
-
-            if (this.errorComponentsToAdd.length > 0) {
-                await this.addQueuedErrorComponentsFromStateVariables();
-
-                // Adding queued _error components can touch composites and alter
-                // what needs to be rendered from the document root.
-                await this.replacementChangesFromCompositesToUpdate();
-
-                results = await this.initializeRenderedComponentInstruction(
-                    this.document,
-                );
-            }
-
-            this.documentRendererInstructions = results.componentToRender;
-
-            let updateInstructions = [
-                {
-                    instructionType: "updateRendererStates",
-                    rendererStatesToUpdate: results.rendererStatesToUpdate,
-                },
-            ];
-
-            this.callUpdateRenderers({ updateInstructions }, true);
-
-            // if have some states to force update
-            // then post these updates without setting init to true
-            if (results.rendererStatesToForceUpdate.length > 0) {
-                let updateInstructions = [
-                    {
-                        instructionType: "updateRendererStates",
-                        rendererStatesToUpdate:
-                            results.rendererStatesToForceUpdate,
-                    },
-                ];
-                this.callUpdateRenderers({ updateInstructions });
-            }
-
-            // initializing renderer instructions could trigger more composite updates
-            // (presumably from deriving child results)
-            // if so, make replacement changes and update renderer instructions again
-            // TODO: should we check for child results earlier so we don't have to check them
-            // when updating renderer instructions?
-            if (this.updateInfo.compositesToUpdateReplacements.size > 0) {
-                await this.replacementChangesFromCompositesToUpdate();
-
-                let componentNamesToUpdate = [
-                    ...this.updateInfo.componentsToUpdateRenderers,
-                ];
-                this.updateInfo.componentsToUpdateRenderers.clear();
-
-                await this.updateRendererInstructions({
-                    componentNamesToUpdate,
-                });
-            }
-
-            await this.processStateVariableTriggers(true);
-        } else {
-            if (parent === undefined) {
-                throw Error("Must specify parent when adding components.");
-            }
-            if (indexOfDefiningChildren === undefined) {
-                indexOfDefiningChildren = parent.definingChildren.length;
-            }
-
-            let addResults = await this.addChildrenAndRecurseToShadows({
-                parent,
-                indexOfDefiningChildren: indexOfDefiningChildren,
-                newChildren: newComponents,
-            });
-            if (!addResults.success) {
-                throw Error(
-                    "Couldn't satisfy child logic result.  Need informative error message",
-                );
-            }
-            Object.assign(addedComponents, addResults.addedComponents);
-            Object.assign(deletedComponents, addResults.deletedComponents);
-
-            await this.expandAllComposites(this.document);
-            await this.expandAllComposites(this.document, true);
-
-            if (this.updateInfo.stateVariablesToEvaluate) {
-                let stateVariablesToEvaluate =
-                    this.updateInfo.stateVariablesToEvaluate;
-                this.updateInfo.stateVariablesToEvaluate = [];
-                for (let {
-                    componentIdx,
-                    stateVariable,
-                } of stateVariablesToEvaluate) {
-                    let comp = this._components[componentIdx];
-                    if (comp && comp.state[stateVariable]) {
-                        await this.getStateVariableValue({
-                            component: comp,
-                            stateVariable,
-                        });
-                    }
-                }
-            }
-            // calculate any replacement changes on composites touched
-            await this.replacementChangesFromCompositesToUpdate();
-
-            await this.updateRendererInstructions({
-                componentNamesToUpdate:
-                    await this.componentAndRenderedDescendants(parent),
-            });
+    // → componentBuilder
+    async addComponents(args) {
+        return this.componentBuilder.addComponents(args);
+    }
 
-            // updating renderer instructions could trigger more composite updates
-            // (presumably from deriving child results)
-            // if so, make replacement changes and update renderer instructions again
-            // TODO: should we check for child results earlier so we don't have to check them
-            // when updating renderer instructions?
-            if (this.updateInfo.compositesToUpdateReplacements.size > 0) {
-                await this.replacementChangesFromCompositesToUpdate();
+    async createIsolatedComponents(args) {
+        return this.componentBuilder.createIsolatedComponents(args);
+    }
 
-                let componentNamesToUpdate = [
-                    ...this.updateInfo.componentsToUpdateRenderers,
-                ];
-                this.updateInfo.componentsToUpdateRenderers.clear();
+    async createChildrenThenComponent(args) {
+        return this.componentBuilder.createChildrenThenComponent(args);
+    }
 
-                await this.updateRendererInstructions({
-                    componentNamesToUpdate,
-                });
-            }
+    async checkForStateVariablesUpdatesForNewComponent(componentIdx) {
+        return this.componentBuilder.checkForStateVariablesUpdatesForNewComponent(
+            componentIdx,
+        );
+    }
 
-            await this.processStateVariableTriggers(true);
-        }
+    findShadowedChildInSerializedComponents(args) {
+        return this.componentBuilder.findShadowedChildInSerializedComponents(
+            args,
+        );
+    }
 
-        this.initialAddPhase = false;
-        return newComponents;
+    async addQueuedErrorComponentsFromStateVariables() {
+        return this.componentBuilder.addQueuedErrorComponentsFromStateVariables();
     }
 
     async updateRendererInstructions(args) {
@@ -783,5068 +601,224 @@ export default class Core {
         );
     }
 
-    async expandAllComposites(component, force = false) {
-        // console.log(`*****expand all composites force=${force} *****`);
-
-        let parentsWithCompositesNotReady =
-            await this.expandCompositesOfDescendants(component, force);
-
-        let expandedAnother = true;
-
-        while (expandedAnother) {
-            expandedAnother = false;
-
-            for (let parentIdx of parentsWithCompositesNotReady) {
-                let parent = this._components[parentIdx];
-                let foundReady = false;
-                for (let compositeIdx of parent.unexpandedCompositesNotReady) {
-                    let composite = this._components[compositeIdx];
-                    if (composite.state.readyToExpandWhenResolved.isResolved) {
-                        foundReady = true;
-                        break;
-                    } else {
-                        let resolveResult = await this.dependencies.resolveItem(
-                            {
-                                componentIdx: composite.componentIdx,
-                                type: "stateVariable",
-                                stateVariable: "readyToExpandWhenResolved",
-                                force,
-                                recurseUpstream: true,
-                            },
-                        );
-
-                        if (resolveResult.success) {
-                            foundReady = true;
-                            break;
-                        }
-                    }
-                }
-
-                if (foundReady) {
-                    let parent = this._components[parentIdx];
-                    await this.deriveChildResultsFromDefiningChildren({
-                        parent,
-                        expandComposites: true,
-                        forceExpandComposites: force,
-                    });
-                    expandedAnother = true;
-                }
-            }
-        }
-
-        // console.log(`*********finished expanding all composites*****`)
+    recordStateVariablesMustEvaluate(componentIdx) {
+        return this.actionTriggerScheduler.recordStateVariablesMustEvaluate(
+            componentIdx,
+        );
     }
 
-    async expandCompositesOfDescendants(
-        component,
-        forceExpandComposites = false,
-    ) {
-        // console.log(`expand composites of descendants of ${component.componentIdx}, forceExpandComposites = ${forceExpandComposites}`)
-
-        // attempt to expand the composites of all descendants
-        // include attributes with children
-
-        let parentsWithCompositesNotReady = [];
-
-        if (!component.matchedCompositeChildren) {
-            await this.deriveChildResultsFromDefiningChildren({
-                parent: component,
-                expandComposites: true,
-                forceExpandComposites,
-            });
-            if (component.unexpandedCompositesNotReady.length > 0) {
-                parentsWithCompositesNotReady.push(component.componentIdx);
-            } else {
-                // console.log(`resolving blockers from changed active children of ${component.componentIdx}`)
-                await this.dependencies.resolveBlockersFromChangedActiveChildren(
-                    component,
-                    forceExpandComposites,
-                );
-                // console.log(`done resolving blockers from changed active children of ${component.componentIdx}`)
-            }
-        }
-
-        for (let attrName in component.attributes) {
-            let attrComp = component.attributes[attrName].component;
-            if (attrComp) {
-                let additionalParentsWithNotReady =
-                    await this.expandCompositesOfDescendants(
-                        attrComp,
-                        forceExpandComposites,
-                    );
-                parentsWithCompositesNotReady.push(
-                    ...additionalParentsWithNotReady,
-                );
-            }
-        }
-
-        for (let childIdxStr in component.allChildren) {
-            let child = component.allChildren[childIdxStr].component;
-            if (typeof child !== "object") {
-                continue;
-            }
+    async checkForActionChaining(args) {
+        return this.actionTriggerScheduler.checkForActionChaining(args);
+    }
 
-            let additionalParentsWithNotReady =
-                await this.expandCompositesOfDescendants(
-                    child,
-                    forceExpandComposites,
-                );
-            parentsWithCompositesNotReady.push(
-                ...additionalParentsWithNotReady,
-            );
-        }
-        // console.log(`done expanding composites of descendants of ${component.componentIdx}`)
+    // → compositeExpander
+    async expandAllComposites(component, force = false) {
+        return this.compositeExpander.expandAllComposites(component, force);
+    }
 
-        return parentsWithCompositesNotReady;
+    async expandCompositesOfDescendants(component, force = false) {
+        return this.compositeExpander.expandCompositesOfDescendants(
+            component,
+            force,
+        );
     }
 
     async componentAndRenderedDescendants(component) {
-        if (component?.componentIdx == undefined) {
-            return [];
-        }
-
-        let componentIndices = [component.componentIdx];
-        if (component.constructor.renderChildren) {
-            if (!component.matchedCompositeChildren) {
-                await this.deriveChildResultsFromDefiningChildren({
-                    parent: component,
-                    expandComposites: true, //forceExpandComposites: true,
-                });
-            }
-            for (let child of component.activeChildren) {
-                componentIndices.push(
-                    ...(await this.componentAndRenderedDescendants(child)),
-                );
-            }
-        }
-        return componentIndices;
+        return this.compositeExpander.componentAndRenderedDescendants(
+            component,
+        );
     }
 
-    async createIsolatedComponents({
-        serializedComponents,
-        ancestors,
-        shadow = false,
-        componentsReplacementOf,
-    }) {
-        const newComponents = [];
-
-        let lastErrorMessage = "";
-
-        const res = extractCreateComponentIdxMapping(serializedComponents);
-        Object.assign(
-            this.createComponentIdxMapping,
-            res.createComponentIdxMapping,
+    async expandCompositeOfDefiningChildren(
+        parent,
+        children,
+        expandComposites,
+        forceExpandComposites,
+    ) {
+        return this.compositeExpander.expandCompositeOfDefiningChildren(
+            parent,
+            children,
+            expandComposites,
+            forceExpandComposites,
         );
+    }
 
-        for (let serializedComponent of serializedComponents) {
-            // console.timeLog('core','<-Top serializedComponents ',serializedComponent.componentIdx);
-
-            if (typeof serializedComponent !== "object") {
-                newComponents.push(serializedComponent);
-                continue;
-            }
-
-            let componentClass =
-                this.componentInfoObjects.allComponentClasses[
-                    serializedComponent.componentType
-                ];
-            if (componentClass === undefined) {
-                // Note: This error shouldn't get reached from author-typed code,
-                // as it should get caught by the correctComponentTypeCapitalization function.
-                // However, it could get called from Javascript if developers
-                // create a serialized component that doesn't exist.
-                const message = `Invalid component type: \`<${serializedComponent.componentType}>\`.`;
-
-                this.diagnosticsManager.markPending();
-
-                const convertResult = convertToErrorComponent(
-                    serializedComponent,
-                    message,
-                );
-                serializedComponent = convertResult.component;
-
-                lastErrorMessage = message;
-
-                componentClass =
-                    this.componentInfoObjects.allComponentClasses[
-                        serializedComponent.componentType
-                    ];
-            }
-
-            if (!serializedComponent.doenetAttributes) {
-                serializedComponent.doenetAttributes = {};
-            }
-
-            let componentIdx = serializedComponent.componentIdx;
-            if (componentIdx == undefined) {
-                throw Error(
-                    "Found a serialized component without a componentIdx",
-                    serializedComponent,
-                );
-            }
-
-            const createResult = await this.createChildrenThenComponent({
-                serializedComponent,
-                componentIdx,
-                ancestors,
-                componentClass,
-                shadow,
-                componentsReplacementOf,
-            });
-
-            const newComponent = createResult.newComponent;
-            newComponents.push(newComponent);
+    async expandCompositeComponent(component) {
+        return this.compositeExpander.expandCompositeComponent(component);
+    }
 
-            if (createResult.lastErrorMessage) {
-                lastErrorMessage = createResult.lastErrorMessage;
-            }
+    async expandShadowingComposite(component) {
+        return this.compositeExpander.expandShadowingComposite(component);
+    }
 
-            // console.timeLog('core','<-Bottom serializedComponents ',serializedComponent.componentIdx);
-        }
+    adjustForCreateComponentIdxName(serializedReplacements, composite) {
+        return this.compositeExpander.adjustForCreateComponentIdxName(
+            serializedReplacements,
+            composite,
+        );
+    }
 
-        let results = {
-            components: newComponents,
-            lastErrorMessage,
-        };
+    async createAndSetReplacements(args) {
+        return this.compositeExpander.createAndSetReplacements(args);
+    }
 
-        return results;
+    async replaceCompositeChildren(parent) {
+        return this.compositeExpander.replaceCompositeChildren(parent);
     }
 
-    async createChildrenThenComponent({
-        serializedComponent,
-        componentIdx,
-        ancestors,
-        componentClass,
-        shadow = false,
-        componentsReplacementOf,
-    }) {
-        let lastErrorMessage = "";
-        let lastErrorMessageFromAttribute = "";
+    async addUndisplayableErrorChildrenToAncestor(
+        parent,
+        undisplayableErrorChildren,
+    ) {
+        return this.compositeExpander.addUndisplayableErrorChildrenToAncestor(
+            parent,
+            undisplayableErrorChildren,
+        );
+    }
 
-        if (!(Number.isInteger(componentIdx) && componentIdx >= 0)) {
-            throw Error(`Found an invalid componentIdx: ${componentIdx}`);
-        }
+    async markWithheldReplacementsInactive(composite) {
+        return this.compositeExpander.markWithheldReplacementsInactive(
+            composite,
+        );
+    }
 
-        if (this._components[componentIdx] !== undefined) {
-            console.log(this._components[componentIdx], serializedComponent);
-            throw Error(`Found a duplicate componentIdx: ${componentIdx}`);
-        }
+    async changeInactiveComponentAndDescendants(component, inactive) {
+        return this.compositeExpander.changeInactiveComponentAndDescendants(
+            component,
+            inactive,
+        );
+    }
 
-        // first recursively create children and attribute components
-        const serializedChildren = serializedComponent.children;
-        let definingChildren = [];
-        const childrenToRemainSerialized = [];
+    // Child matching, adapter substitution, and rendered-child filtering
+    // live in `this.childMatcher` (see ChildMatcher.ts). The methods below
+    // preserve the public surface by delegating through.
 
-        const ancestorsForChildren = [
-            { componentIdx, componentClass },
-            ...ancestors,
-        ];
-
-        // add a new level to parameter stack;
-        const parentSharedParameters = this.parameterStack.parameters;
-        this.parameterStack.push();
-        const sharedParameters = this.parameterStack.parameters;
-
-        if (
-            componentClass.descendantCompositesMustHaveAReplacement &&
-            !shadow
-        ) {
-            sharedParameters.compositesMustHaveAReplacement = true;
-            sharedParameters.compositesDefaultReplacementType =
-                componentClass.descendantCompositesDefaultReplacementType;
-        } else if (
-            componentClass.descendantCompositesMustHaveAReplacement === false ||
-            shadow
-        ) {
-            sharedParameters.compositesMustHaveAReplacement = false;
-        }
-
-        if (serializedChildren !== undefined) {
-            if (componentClass.preprocessSerializedChildren) {
-                componentClass.preprocessSerializedChildren({
-                    serializedChildren,
-                    attributes: serializedComponent.attributes,
-                    componentIdx,
-                });
-            }
-
-            if (componentClass.setUpVariant) {
-                const descendantVariantComponents = gatherVariantComponents({
-                    serializedComponents: serializedChildren,
-                    componentInfoObjects: this.componentInfoObjects,
-                });
-
-                componentClass.setUpVariant({
-                    serializedComponent,
-                    sharedParameters,
-                    descendantVariantComponents,
-                });
-            }
-
-            if (componentClass.keepChildrenSerialized) {
-                const childrenAddressed = new Set([]);
-
-                const keepSerializedInds =
-                    componentClass.keepChildrenSerialized({
-                        serializedComponent,
-                        componentInfoObjects: this.componentInfoObjects,
-                    });
-
-                for (const ind of keepSerializedInds) {
-                    if (childrenAddressed.has(Number(ind))) {
-                        throw Error(
-                            "Invalid instructions to keep children serialized from " +
-                                componentClass.componentType +
-                                ": child repeated",
-                        );
-                    }
-                    childrenAddressed.add(Number(ind));
-                    childrenToRemainSerialized.push(serializedChildren[ind]);
-                }
-
-                // create any remaining children
-                const childrenToCreate = [];
-                for (const [ind, child] of serializedChildren.entries()) {
-                    if (!childrenAddressed.has(ind)) {
-                        childrenToCreate.push(child);
-                    }
-                }
-
-                if (childrenToCreate.length > 0) {
-                    const childrenResult = await this.createIsolatedComponents({
-                        serializedComponents: childrenToCreate,
-                        ancestors: ancestorsForChildren,
-                        shadow,
-                        componentsReplacementOf,
-                    });
-
-                    definingChildren = childrenResult.components;
-                    if (childrenResult.lastErrorMessage) {
-                        lastErrorMessage = childrenResult.lastErrorMessage;
-                    }
-                }
-            } else {
-                //create all children
-
-                const childrenResult = await this.createIsolatedComponents({
-                    serializedComponents: serializedChildren,
-                    ancestors: ancestorsForChildren,
-                    shadow,
-                    componentsReplacementOf,
-                });
-
-                definingChildren = childrenResult.components;
-                if (childrenResult.lastErrorMessage) {
-                    lastErrorMessage = childrenResult.lastErrorMessage;
-                }
-            }
-        }
-
-        let attributes = {};
-
-        if (serializedComponent.attributes) {
-            for (const attrName in serializedComponent.attributes) {
-                const attribute = serializedComponent.attributes[attrName];
-
-                if (attribute.component) {
-                    if (attrName === componentClass.addAttributeToResolver) {
-                        this.addComponentsToResolver(
-                            [attribute.component],
-                            serializedComponent.componentIdx,
-                        );
-                    }
-
-                    try {
-                        const attrResult = await this.createIsolatedComponents({
-                            serializedComponents: [attribute.component],
-                            ancestors: ancestorsForChildren,
-                            shadow,
-                            componentsReplacementOf,
-                        });
-
-                        if (attrResult.lastErrorMessage) {
-                            lastErrorMessage = attrResult.lastErrorMessage;
-                            lastErrorMessageFromAttribute =
-                                attrResult.lastErrorMessage;
-                        }
-
-                        attributes[attrName] = {
-                            component: attrResult.components[0],
-                        };
-                    } catch (e) {
-                        console.error(e);
-                        if (e.message.includes("Circular dependency")) {
-                            throw Error(
-                                this.dependencies.getCircularDependencyMessage([
-                                    serializedComponent,
-                                ]),
-                            );
-                        } else {
-                            throw e;
-                        }
-                    }
-                } else if (attribute.references) {
-                    try {
-                        const attrResult = await this.createIsolatedComponents({
-                            serializedComponents: attribute.references,
-                            ancestors: ancestorsForChildren,
-                            shadow,
-                            componentsReplacementOf,
-                        });
-
-                        if (attrResult.lastErrorMessage) {
-                            lastErrorMessage = attrResult.lastErrorMessage;
-                            lastErrorMessageFromAttribute =
-                                attrResult.lastErrorMessage;
-                        }
-
-                        attributes[attrName] = {
-                            references: attrResult.components,
-                            stringChildren: attribute.stringChildren,
-                        };
-                    } catch (e) {
-                        console.error(e);
-                        throw e;
-                    }
-                } else {
-                    attributes[attrName] =
-                        serializedComponent.attributes[attrName];
-                }
-            }
-        }
-
-        // If `serializedComponent` has a `extending`
-        // then create components for all the indices of the original path.
-        let refResolution = null;
-        if (serializedComponent.extending) {
-            refResolution = unwrapSource(serializedComponent.extending);
-
-            const nodeIdx = refResolution.nodeIdx;
-
-            const originalPath = [];
-            for (const pathPart of refResolution.originalPath) {
-                const index = [];
-                for (const indexPiece of pathPart.index) {
-                    const valueResult = await this.createIsolatedComponents({
-                        serializedComponents: indexPiece.value,
-                        ancestors: ancestorsForChildren,
-                        shadow,
-                        componentsReplacementOf,
-                    });
-                    if (valueResult.lastErrorMessage) {
-                        lastErrorMessage = valueResult.lastErrorMessage;
-                    }
-                    const value = valueResult.components;
-                    index.push({
-                        value,
-                        position: indexPiece.position,
-                        sourceDoc: indexPiece.sourceDoc,
-                    });
-                }
-                originalPath.push({
-                    name: pathPart.name,
-                    index,
-                    position: pathPart.position,
-                    sourceDoc: pathPart.sourceDoc,
-                });
-            }
-            refResolution = {
-                nodeIdx,
-                unresolvedPath: refResolution.unresolvedPath,
-                originalPath,
-                nodesInResolvedPath: refResolution.nodesInResolvedPath,
-            };
-        }
-
-        if (serializedComponent.componentType === "_error") {
-            lastErrorMessage = serializedComponent.state.message;
-
-            this.addDiagnostic({
-                type: "error",
-                message: serializedComponent.state.message,
-                position: serializedComponent.position,
-                sourceDoc: serializedComponent.sourceDoc,
-            });
-        } else if (
-            lastErrorMessageFromAttribute ||
-            (lastErrorMessage && !componentClass.canDisplayChildErrors)
-        ) {
-            // We have to deal with two special cases where errors wouldn't be displayed:
-            // 1. there is an error message from an attribute, or
-            // 2. this component cannot display errors from children
-            // In these cases, we turn this component into an error component
-            // to ensure the error message is displayed.
-
-            const convertResult = convertToErrorComponent(
-                serializedComponent,
-                lastErrorMessageFromAttribute || lastErrorMessage,
-            );
-            serializedComponent = convertResult.component;
-
-            attributes = {};
-            componentClass =
-                this.componentInfoObjects.allComponentClasses[
-                    serializedComponent.componentType
-                ];
-        }
-
-        const prescribedDependencies = {};
-
-        if (serializedComponent.downstreamDependencies) {
-            for (const idxStr in serializedComponent.downstreamDependencies) {
-                const idx = Number(idxStr);
-                if (idx === componentIdx) {
-                    throw Error(
-                        this.dependencies.getCircularDependencyMessage([
-                            serializedComponent,
-                        ]),
-                    );
-                }
-                if (this.components[idx]) {
-                    prescribedDependencies[idx] =
-                        serializedComponent.downstreamDependencies[idx];
-                } else {
-                    throw Error(
-                        this.dependencies.getCircularDependencyMessage([
-                            serializedComponent,
-                        ]),
-                    );
-                }
-            }
-        }
-
-        const stateVariableDefinitions =
-            await this.createStateVariableDefinitions({
-                componentClass,
-                prescribedDependencies,
-                componentIdx,
-            });
-
-        // in case component with same name was deleted before, delete from deleteComponents and deletedStateVariable
-        delete this.updateInfo.deletedComponents[componentIdx];
-        delete this.updateInfo.deletedStateVariables[componentIdx];
-
-        const stateId = serializedComponent.stateId ?? componentIdx.toString();
-        this.componentIdxByStateId[stateId] = componentIdx;
-
-        // create component itself
-        const newComponent = new componentClass({
-            componentIdx,
-            stateId,
-            rootName:
-                this.rootNames?.[componentIdx] ??
-                "_id_" + componentIdx.toString(),
-            ancestors,
-            definingChildren,
-            stateVariableDefinitions,
-            serializedChildren: childrenToRemainSerialized,
-            serializedComponent,
-            attributes,
-            componentInfoObjects: this.componentInfoObjects,
-            coreFunctions: this.coreFunctions,
-            flags: this.flags,
-            shadow,
-            numerics: this.numerics,
-            sharedParameters,
-            parentSharedParameters,
-            refResolution,
-        });
-
-        this.registerComponent(newComponent);
-
-        if (componentsReplacementOf) {
-            newComponent.replacementOf = componentsReplacementOf;
-        }
-
-        if (serializedComponent.adaptedFrom) {
-            // record adapter relationship
-            newComponent.adaptedFrom =
-                this._components[serializedComponent.adaptedFrom];
-            newComponent.adaptedFrom.adapterUsed = newComponent;
-        }
-
-        for (const idxStr in prescribedDependencies) {
-            const idx = Number(idxStr);
-            const depArray = prescribedDependencies[idx];
-            for (const dep of depArray) {
-                if (dep.dependencyType === "referenceShadow") {
-                    const shadowInfo = {
-                        componentIdx: idx,
-                    };
-                    Object.assign(shadowInfo, dep);
-                    delete shadowInfo.dependencyType;
-                    // newComponent.shadows = new Proxy(shadowInfo, readOnlyProxyHandler);
-                    newComponent.shadows = shadowInfo;
-
-                    if (dep.firstLevelReplacement) {
-                        newComponent.firstLevelReplacement = true;
-                    }
-
-                    const shadowedComponent = this._components[idx];
-                    if (!shadowedComponent.shadowedBy) {
-                        shadowedComponent.shadowedBy = [];
-                    }
-                    shadowedComponent.shadowedBy.push(newComponent);
-
-                    const mediatingShadowComposite =
-                        this._components[shadowInfo.compositeIdx];
-                    if (!mediatingShadowComposite.mediatesShadows) {
-                        mediatingShadowComposite.mediatesShadows = [];
-                    }
-                    mediatingShadowComposite.mediatesShadows.push({
-                        shadowing: newComponent.componentIdx,
-                        shadowed: idx,
-                        propVariable: dep.propVariable,
-                    });
-
-                    if (dep.isPrimaryShadow) {
-                        shadowedComponent.primaryShadow =
-                            newComponent.componentIdx;
-
-                        if (
-                            this.dependencies.updateTriggers
-                                .primaryShadowDependencies[idx]
-                        ) {
-                            for (const dep of this.dependencies.updateTriggers
-                                .primaryShadowDependencies[idx]) {
-                                await dep.recalculateDownstreamComponents();
-                            }
-                        }
-                    }
-
-                    break;
-                }
-            }
-        }
-
-        if (serializedComponent.unlinkedCopySource) {
-            newComponent.unlinkedCopySource =
-                serializedComponent.unlinkedCopySource;
-        }
-
-        await this.deriveChildResultsFromDefiningChildren({
-            parent: newComponent,
-            expandComposites: false,
-        });
-
-        await this.initializeComponentStateVariables(newComponent);
-
-        await this.dependencies.setUpComponentDependencies(newComponent);
-
-        const variablesChanged =
-            await this.dependencies.checkForDependenciesOnNewComponent(
-                componentIdx,
-            );
-
-        for (const varDescription of variablesChanged) {
-            await this.markStateVariableAndUpstreamDependentsStale({
-                component: this._components[varDescription.componentIdx],
-                varName: varDescription.varName,
-            });
-        }
-
-        await this.checkForStateVariablesUpdatesForNewComponent(componentIdx);
-
-        await this.dependencies.resolveStateVariablesIfReady({
-            component: newComponent,
-        });
-
-        this.recordStateVariablesMustEvaluate(componentIdx);
-
-        await this.checkForActionChaining({ component: newComponent });
-
-        // this.dependencies.collateCountersAndPropagateToAncestors(newComponent);
-
-        // remove a level from parameter stack;
-        this.parameterStack.pop();
-
-        const results = { newComponent: newComponent, lastErrorMessage };
-
-        return results;
-    }
-
-    async checkForStateVariablesUpdatesForNewComponent(componentIdx) {
-        let comp = this._components[componentIdx];
-        const stateId = comp.stateId;
-        if (
-            stateId in this.updateInfo.stateVariableUpdatesForMissingComponents
-        ) {
-            let result = await this.processNewStateVariableValues(
-                {
-                    [componentIdx]:
-                        this.updateInfo
-                            .stateVariableUpdatesForMissingComponents[stateId],
-                },
-                // This `true` indicates we have a new component
-                true,
-            );
-
-            // In order to make sure that a component takes on the same value
-            // that was saved to the database,
-            // it may be necessary for a component to treat the value received differently
-            // in the first pass of the definition.
-            // Hence, we run the definition of all variables with the extra flag
-            // justUpdatedForNewComponent = true
-            if (
-                comp.constructor.processWhenJustUpdatedForNewComponent ||
-                result.foundIgnore
-            ) {
-                for (let vName in this.updateInfo
-                    .stateVariableUpdatesForMissingComponents[stateId]) {
-                    if (comp.state[vName]) {
-                        this.updateInfo.stateVariablesToEvaluate.push({
-                            componentIdx,
-                            stateVariable: vName,
-                        });
-                        comp.state[vName].justUpdatedForNewComponent = true;
-                        if (result.foundIgnore) {
-                            // This is a kludge
-                            // The only case so far with ignored children is that Math ignores strings
-                            // (set in inverse definition of expressionWithCodes).
-                            // We need change its value a second time after evaluating
-                            // so that the next time the definition of expressionWithCodes is run,
-                            // the strings don't show any changes and we'll use the essential value
-                            // of expressionWithCodes
-                            comp.reprocessAfterEvaluate =
-                                this.updateInfo.stateVariableUpdatesForMissingComponents[
-                                    stateId
-                                ];
-                        }
-                    }
-                }
-            }
-
-            delete this.updateInfo.stateVariableUpdatesForMissingComponents[
-                stateId
-            ];
-        }
-    }
-
-    recordStateVariablesMustEvaluate(componentIdx) {
-        return this.actionTriggerScheduler.recordStateVariablesMustEvaluate(
-            componentIdx,
-        );
-    }
-
-    // → childMatcher
     async deriveChildResultsFromDefiningChildren(args) {
-        return this.childMatcher.deriveChildResultsFromDefiningChildren(args);
-    }
-
-    async expandCompositeOfDefiningChildren(
-        parent,
-        children,
-        expandComposites,
-        forceExpandComposites,
-    ) {
-        // if composite is not directly matched by any childGroup
-        // then replace the composite with its replacements,
-        // expanding it if not already expanded
-
-        // console.log(`expanding defining children of of ${parent.componentIdx}`)
-
-        let unexpandedCompositesReady = [];
-        let unexpandedCompositesNotReady = [];
-
-        for (let childInd = 0; childInd < children.length; childInd++) {
-            let child = children[childInd];
-
-            if (
-                child instanceof
-                this.componentInfoObjects.allComponentClasses._composite
-            ) {
-                // if composite itself is in the child logic
-                // then don't replace it with its replacements
-                // but leave the composite as an activeChild
-                if (
-                    this.findChildGroup(child.componentType, parent.constructor)
-                        .success
-                ) {
-                    continue;
-                }
-
-                // expand composite if it isn't already
-                if (!child.isExpanded) {
-                    // console.log(`child ${child.componentIdx} is not expanded`)
-                    // console.log(child.state.readyToExpandWhenResolved.isResolved)
-
-                    if (!child.state.readyToExpandWhenResolved.isResolved) {
-                        if (expandComposites) {
-                            let resolveResult =
-                                await this.dependencies.resolveItem({
-                                    componentIdx: child.componentIdx,
-                                    type: "stateVariable",
-                                    stateVariable: "readyToExpandWhenResolved",
-                                    expandComposites, //: forceExpandComposites,
-                                    force: forceExpandComposites,
-                                });
-
-                            if (!resolveResult.success) {
-                                unexpandedCompositesNotReady.push(
-                                    child.componentIdx,
-                                );
-                                this.updateInfo.compositesToExpand.add(
-                                    child.componentIdx,
-                                );
-                                continue;
-                            }
-                        } else {
-                            unexpandedCompositesNotReady.push(
-                                child.componentIdx,
-                            );
-                            this.updateInfo.compositesToExpand.add(
-                                child.componentIdx,
-                            );
-                            continue;
-                        }
-                    } else if (!expandComposites) {
-                        unexpandedCompositesReady.push(child.componentIdx);
-                        this.updateInfo.compositesToExpand.add(
-                            child.componentIdx,
-                        );
-                        continue;
-                    }
-
-                    // will either succeed or throw error since is ready to expand
-                    await this.expandCompositeComponent(child);
-                }
-
-                // recurse on replacements
-                let result = await this.expandCompositeOfDefiningChildren(
-                    parent,
-                    child.replacements,
-                    expandComposites,
-                    forceExpandComposites,
-                );
-
-                unexpandedCompositesReady.push(
-                    ...result.unexpandedCompositesReady,
-                );
-                unexpandedCompositesNotReady.push(
-                    ...result.unexpandedCompositesNotReady,
-                );
-            }
-        }
-
-        // console.log(`done expanding defining children of of ${parent.componentIdx}`)
-
-        return { unexpandedCompositesReady, unexpandedCompositesNotReady };
-    }
-
-    async matchChildrenToChildGroups(parent) {
-        return this.childMatcher.matchChildrenToChildGroups(parent);
-    }
-
-    findChildGroup(childType, parentClass) {
-        return this.childMatcher.findChildGroup(childType, parentClass);
-    }
-
-    findChildGroupNoAdapters(
-        componentType,
-        parentClass,
-        afterAdapters = false,
-    ) {
-        return this.childMatcher.findChildGroupNoAdapters(
-            componentType,
-            parentClass,
-            afterAdapters,
-        );
-    }
-
-    async returnActiveChildrenIndicesToRender(component) {
-        return this.childMatcher.returnActiveChildrenIndicesToRender(component);
-    }
-
-    async substituteAdapter(args) {
-        return this.childMatcher.substituteAdapter(args);
-    }
-
-    async expandCompositeComponent(component) {
-        if (!("readyToExpandWhenResolved" in component.state)) {
-            throw Error(
-                `Could not find state variable readyToExpandWhenResolved of composite ${component.componentIdx}`,
-            );
-        }
-
-        if (!component.state.readyToExpandWhenResolved.isResolved) {
-            this.updateInfo.compositesToExpand.add(component.componentIdx);
-            return { success: false };
-        }
-
-        this.updateInfo.compositesToExpand.delete(component.componentIdx);
-
-        // console.log(`expanding composite ${component.componentIdx}`);
-
-        this.updateInfo.compositesBeingExpanded.push(component.componentIdx);
-
-        if (component.parent) {
-            if (component.parent.unexpandedCompositesReady) {
-                let ind = component.parent.unexpandedCompositesReady.indexOf(
-                    component.componentIdx,
-                );
-                if (ind !== -1) {
-                    component.parent.unexpandedCompositesReady.splice(ind, 1);
-                }
-            }
-            if (component.parent.unexpandedCompositesNotReady) {
-                let ind = component.parent.unexpandedCompositesNotReady.indexOf(
-                    component.componentIdx,
-                );
-                if (ind !== -1) {
-                    component.parent.unexpandedCompositesNotReady.splice(
-                        ind,
-                        1,
-                    );
-                }
-            }
-        }
-
-        if (
-            component.shadows &&
-            !component.shadows.propVariable &&
-            !component.constructor.doNotExpandAsShadowed
-            //&&
-            // this.componentInfoObjects.isCompositeComponent({
-            //   componentType: component.componentType,
-            //   includeNonStandard: false,
-            // })
-        ) {
-            return await this.expandShadowingComposite(component);
-        }
-
-        // Call the static function createSerializedReplacements from the composite component
-        // which returns an object containing a key "replacements" with value an array
-        // of serialized components that will be turned into real components.
-        // The replacement components will be used to replace
-        // the composite itself as children for the composite's parent
-        // Arguments
-        // component: the composite component
-        // components: all components in the document
-        // workspace: an initially empty object that a composite can use to store information that will then
-        //   be provided when updating composite replacements via calculateReplacementChanges
-        // componentInfoObjects
-        // flags
-        // resolveItem: a function that the composite can use to resolve any state variables
-        // publicCaseInsensitiveAliasSubstitutions: a function that can be used to find a case insensitive match
-        //   to a public state variable, substituting aliases if necessary
-        let initialNComponents;
-        let result;
-        const originalWorkspace = { ...component.replacementsWorkspace };
-
-        do {
-            initialNComponents = this.components.length;
-            component.replacementsWorkspace = { ...originalWorkspace };
-            result = await component.constructor.createSerializedReplacements({
-                component: this.components[component.componentIdx], // to create proxy
-                components: this.components,
-                nComponents: this.components.length,
-                workspace: component.replacementsWorkspace,
-                componentInfoObjects: this.componentInfoObjects,
-                allDoenetMLs: this.allDoenetMLs,
-                flags: this.flags,
-                resolveItem: this.dependencies.resolveItem.bind(
-                    this.dependencies,
-                ),
-                publicCaseInsensitiveAliasSubstitutions:
-                    this.publicCaseInsensitiveAliasSubstitutions.bind(this),
-            });
-
-            // If `this.components` changed in length while `createSerializedReplacements` was executing,
-            // it means that some other action (like calling another `createSerializedReplacements`)
-            // occurred while resolving state variables.
-            // Since this would lead to collisions in assigned component indices, we rerun `createSerializedReplacements`.
-            // TODO: are there any scenarios where this will lead to an infinite loop?
-        } while (this.components.length !== initialNComponents);
-
-        const newNComponents = result.nComponents;
-
-        if (
-            !(
-                Number.isInteger(newNComponents) &&
-                newNComponents >= this._components.length
-            )
-        ) {
-            throw Error(
-                `Invalid nComponents returned by createSerializedReplacements for ${component.componentType}: `,
-                newNComponents,
-            );
-        }
-
-        let position = this.components[component.componentIdx].position;
-        let sourceDoc = this.components[component.componentIdx].sourceDoc;
-        let overwriteDoenetMLRange = component.componentType === "_copy";
-
-        this.gatherDiagnosticsAndAssignDoenetMLRange({
-            components: result.replacements,
-            diagnostics: result.diagnostics,
-            position,
-            sourceDoc,
-            overwriteDoenetMLRange,
-        });
-
-        // console.log(`expand result for ${component.componentIdx}`);
-        // console.log(JSON.parse(JSON.stringify(result)));
-
-        if (component.constructor.stateVariableToEvaluateAfterReplacements) {
-            // console.log(`evaluating ${component.constructor.stateVariableToEvaluateAfterReplacements} of ${component.componentIdx}`)
-            await component.stateValues[
-                component.constructor.stateVariableToEvaluateAfterReplacements
-            ];
-            // console.log(`done evaluating ${component.constructor.stateVariableToEvaluateAfterReplacements} of ${composite.componentIdx}`)
-        }
-
-        if (result.replacements) {
-            let serializedReplacements = result.replacements;
-
-            await this.addReplacementsToResolver({
-                serializedReplacements,
-                component,
-            });
-
-            // expand `this._components` to length `newNComponents` so that the component indices will not be reused
-            if (newNComponents > this._components.length) {
-                this._components[newNComponents - 1] = undefined;
-            }
-
-            await this.createAndSetReplacements({
-                component,
-                serializedReplacements,
-            });
-        } else {
-            throw Error(
-                `Invalid createSerializedReplacements of ${component.componentIdx}`,
-            );
-        }
-
-        // record that are finished expanding the composite
-        let targetInd = this.updateInfo.compositesBeingExpanded.indexOf(
-            component.componentIdx,
-        );
-        if (targetInd === -1) {
-            throw Error(
-                `Something is wrong as we lost track that we were expanding ${component.componentIdx}`,
-            );
-        }
-        this.updateInfo.compositesBeingExpanded.splice(targetInd, 1);
-
-        return { success: true, compositesExpanded: [component.componentIdx] };
-    }
-
-    // → resolverAdapter
-    async addReplacementsToResolver(args) {
-        return this.resolverAdapter.addReplacementsToResolver(args);
-    }
-
-    async determineParentAndIndexResolutionForResolver(args) {
-        return this.resolverAdapter.determineParentAndIndexResolutionForResolver(
-            args,
-        );
-    }
-
-    addComponentsToResolver(components, parentIdx) {
-        return this.resolverAdapter.addComponentsToResolver(
-            components,
-            parentIdx,
-        );
-    }
-
-    gatherDiagnosticsAndAssignDoenetMLRange(args) {
-        return this.resolverAdapter.gatherDiagnosticsAndAssignDoenetMLRange(
-            args,
-        );
-    }
-
-    async expandShadowingComposite(component) {
-        // console.log(`expand shadowing composite, ${component.componentIdx}`);
-
-        if (
-            this.updateInfo.compositesBeingExpanded.includes(
-                component.shadows.componentIdx,
-            )
-        ) {
-            // found a circular dependency,
-            // as we are in the middle of expanding a composite
-            // that we are now trying to shadow
-            let compositeInvolved =
-                this._components[component.shadows.componentIdx];
-            // find non-shadow for error message, as that would be a component from document
-            while (compositeInvolved.shadows) {
-                compositeInvolved =
-                    this._components[compositeInvolved.shadows.componentIdx];
-            }
-            throw Error(
-                `Circular dependency involving ${compositeInvolved.componentIdx}.`,
-            );
-        }
-
-        let shadowedComposite =
-            this._components[component.shadows.componentIdx];
-        let compositesExpanded = [];
-
-        // console.log(`shadowedComposite: ${shadowedComposite.componentIdx}`);
-        // console.log(shadowedComposite.isExpanded);
-        if (!shadowedComposite.isExpanded) {
-            let result = await this.expandCompositeComponent(shadowedComposite);
-
-            if (!result.success) {
-                throw Error(
-                    `expand result of ${component.componentIdx} was not a success even though ready to expand.`,
-                );
-            }
-            compositesExpanded.push(...result.compositesExpanded);
-        }
-
-        // we'll copy the replacements of the shadowed composite
-        // and make those be the replacements of the shadowing composite
-        let serializedReplacements = [];
-
-        if (component.replacementsWorkspace.replacementsCreated === undefined) {
-            component.replacementsWorkspace.replacementsCreated = 0;
-        }
-
-        const stateIdInfo = {
-            prefix: `${component.stateId}|`,
-            num: component.replacementsWorkspace.replacementsCreated,
-        };
-
-        let nComponents = this._components.length;
-        let newNComponents = nComponents;
-
-        // We address one complication from shadowing a component with copied in children.
-        // In this case, the name resolver will already have the component indices of the serialized children of `component`.
-        // The corresponding replacements of `component` should have those component indices.
-        // However, those replacements already exist in the replacements of `shadowedComposite` which we are copying.
-        // As a workaround, we create a map from the indices of the children of `shadowedComposite`
-        // to the indices of the children of `component` and override the component indices created on the new replacements.
-        const idxMapOverride = {};
-        const copyInChildren =
-            shadowedComposite.attributes.copyInChildren?.primitive.value;
-        if (copyInChildren) {
-            const componentChildren = JSON.parse(
-                JSON.stringify(component.serializedChildren),
-            );
-            const shadowedChildren = JSON.parse(
-                JSON.stringify(shadowedComposite.serializedChildren),
-            );
-
-            // We are reusing this code that maps indices from serialized components to get the map
-            // from indices of `shadowedChildren` to indices of `componentChildren`.
-            const res = createComponentIndicesFromSerializedChildren(
-                shadowedChildren,
-                componentChildren,
-                newNComponents,
-            );
-
-            for (const idx in res.idxMap) {
-                // the above code might also have created new indices, which we ignore
-                if (res.idxMap[idx] < newNComponents) {
-                    idxMapOverride[idx] = res.idxMap[idx];
-                }
-            }
-        }
-
-        for (let [idx, repl] of shadowedComposite.replacements.entries()) {
-            if (typeof repl === "object") {
-                const serializedComponent = await repl.serialize();
-
-                if (
-                    component.constructor.useSerializedChildrenComponentIndices
-                ) {
-                    const res = createComponentIndicesFromSerializedChildren(
-                        [serializedComponent],
-                        [component.serializedChildren[idx]],
-                        newNComponents,
-                        stateIdInfo,
-                    );
-                    newNComponents = res.nComponents;
-
-                    serializedReplacements.push(...res.components);
-                } else {
-                    const res = createNewComponentIndices(
-                        [serializedComponent],
-                        newNComponents,
-                        stateIdInfo,
-                        idxMapOverride,
-                    );
-                    newNComponents = res.nComponents;
-
-                    serializedReplacements.push(...res.components);
-                }
-            } else {
-                serializedReplacements.push(repl);
-            }
-        }
-
-        if (component.constructor.addExtraSerializedChildrenWhenShadowing) {
-            let rendered = true;
-            if ("rendered" in component.state) {
-                rendered = await component.state.rendered.value;
-            }
-
-            if (rendered) {
-                // add any serialized children that are beyond the replacements we already have
-                serializedReplacements.push(
-                    ...deepClone(
-                        component.serializedChildren.slice(
-                            serializedReplacements.length,
-                        ),
-                    ),
-                );
-            }
-        }
-
-        this.adjustForCreateComponentIdxName(serializedReplacements, component);
-
-        // console.log(
-        //     `serialized replacements of ${shadowedComposite.componentIdx}`,
-        // );
-        // console.log(JSON.parse(JSON.stringify(serializedReplacements)));
-
-        // Have three composites involved:
-        // 1. the shadowing composite (component, the one we're trying to expand)
-        // 2. the shadowed composite
-        // 3. the composite mediating the shadowing
-        //    (of which shadowing composite is the replacement)
-
-        let nameOfCompositeMediatingTheShadow = component.shadows.compositeIdx;
-        let compositeMediatingTheShadow =
-            this.components[nameOfCompositeMediatingTheShadow];
-        serializedReplacements = postProcessCopy({
-            serializedComponents: serializedReplacements,
-            componentIdx: nameOfCompositeMediatingTheShadow,
-        });
-
-        // console.log("--------------");
-        // console.log(
-        //   `name of composite mediating shadow: ${nameOfCompositeMediatingTheShadow}`,
-        // );
-        // console.log(`name of composite shadowing: ${component.componentIdx}`);
-        // console.log(
-        //   `name of shadowed composite: ${shadowedComposite.componentIdx}`,
-        // );
-
-        // If shadowed composite mediates the shadow of compositeMediatingTheShadow,
-        // then we have a circular reference.
-        // mediatesShadows is an array of objects with keys shadows and shadowed,
-        // that the shadow mediated by the component.
-        // We check if shadowedComposite mediates the shadow of compositeMediatingTheShadow,
-        // or, recursively, if one of those shadowed components
-        // mediates the shadow of compositeMediatingTheShadow
-
-        let foundCircular = false;
-        let shadowedByShadowed = shadowedComposite.mediatesShadows
-            ?.filter((v) => v.propVariable === undefined)
-            .map((v) => v.shadowed);
-
-        while (shadowedByShadowed?.length > 0) {
-            if (
-                shadowedByShadowed.includes(nameOfCompositeMediatingTheShadow)
-            ) {
-                foundCircular = true;
-                let message = "Circular dependency detected";
-                if (component.attributes.createComponentOfType?.primitive) {
-                    message += ` involving \`<${component.attributes.createComponentOfType.primitive.value}>\` component`;
-                }
-                message += ".";
-                serializedReplacements = [
-                    {
-                        type: "serialized",
-                        componentType: "_error",
-                        componentIdx: newNComponents++,
-                        attributes: {},
-                        doenetAttributes: {},
-                        children: [],
-                        state: { message },
-                        position: compositeMediatingTheShadow.position,
-                        sourceDoc: compositeMediatingTheShadow.sourceDoc,
-                    },
-                ];
-                this.addDiagnostic({
-                    type: "error",
-                    message,
-                    position: compositeMediatingTheShadow.position,
-                    sourceDoc: compositeMediatingTheShadow.sourceDoc,
-                });
-
-                break;
-            }
-
-            // recurse to check if one the shadowed components mediates
-            // the shadow of compositeMediatingTheShadow
-            shadowedByShadowed = shadowedByShadowed.reduce((acc, cIdx) => {
-                let comp = this.components[cIdx];
-                if (comp?.mediatesShadows) {
-                    return [
-                        ...acc,
-                        ...comp.mediatesShadows
-                            .filter((v) => v.propVariable === undefined)
-                            .map((v) => v.shadowed),
-                    ];
-                } else {
-                    return acc;
-                }
-            }, []);
-        }
-
-        // XXX: what is the replacement for targetComponentIdx?
-        // let target =
-        //     this._components[
-        //         compositeMediatingTheShadow.doenetAttributes.targetComponentIdx
-        //     ];
-
-        // if (
-        //     target?.componentIdx === shadowedComposite.componentIdx &&
-        //     compositeMediatingTheShadow.attributes.copyInChildren?.primitive
-        //         .value
-        // ) {
-        //     let newReplacements = deepClone(
-        //         compositeMediatingTheShadow.serializedChildren,
-        //     );
-        //     let componentClass =
-        //         this.componentInfoObjects.allComponentClasses[
-        //             component.componentType
-        //         ];
-
-        //     if (!componentClass.includeBlankStringChildren) {
-        //         newReplacements = newReplacements.filter(
-        //             (x) => typeof x !== "string" || x.trim() !== "",
-        //         );
-        //     }
-
-        //     serializedReplacements.push(...newReplacements);
-        // }
-
-        if (!foundCircular) {
-            if (
-                component.replacementsWorkspace.replacementsCreated ===
-                undefined
-            ) {
-                component.replacementsWorkspace.replacementsCreated = 0;
-            }
-
-            let verificationResult = await verifyReplacementsMatchSpecifiedType(
-                {
-                    component,
-                    replacements: serializedReplacements,
-                    componentInfoObjects: this.componentInfoObjects,
-                    compositeAttributesObj: preprocessAttributesObject(
-                        component.constructor.createAttributesObject(),
-                    ),
-                    components: this._components,
-                    nComponents: newNComponents,
-                    stateIdInfo,
-                    publicCaseInsensitiveAliasSubstitutions:
-                        this.publicCaseInsensitiveAliasSubstitutions.bind(this),
-                },
-            );
-
-            for (const error of verificationResult.diagnostics) {
-                this.addDiagnostic({
-                    ...error,
-                    type: "error",
-                });
-            }
-            for (const warning of verificationResult.diagnostics) {
-                this.addDiagnostic({
-                    ...warning,
-                    type: "warning",
-                });
-            }
-
-            newNComponents = verificationResult.nComponents;
-
-            serializedReplacements = verificationResult.replacements;
-
-            addAttributesToSingleReplacement(
-                serializedReplacements,
-                component,
-                this.componentInfoObjects,
-            );
-        }
-
-        // console.log(
-        //     `serialized replacements for ${component.componentIdx} who is shadowing ${shadowedComposite.componentIdx}`,
-        // );
-        // console.log(deepClone(serializedReplacements));
-
-        component.replacementsWorkspace.replacementsCreated = stateIdInfo.num;
-
-        await this.addReplacementsToResolver({
-            serializedReplacements,
-            component,
-        });
-
-        // expand `this._components` to length `newNComponents` so that the component indices will not be reused
-        if (newNComponents > this._components.length) {
-            this._components[newNComponents - 1] = undefined;
-        }
-
-        await this.createAndSetReplacements({
-            component,
-            serializedReplacements,
-        });
-
-        if (shadowedComposite.replacementsToWithhold > 0) {
-            component.replacementsToWithhold =
-                shadowedComposite.replacementsToWithhold;
-        }
-
-        // record that are finished expanding the composite
-        let targetInd = this.updateInfo.compositesBeingExpanded.indexOf(
-            component.componentIdx,
-        );
-        if (targetInd === -1) {
-            throw Error(
-                `Something is wrong as we lost track that we were expanding ${component.componentIdx}`,
-            );
-        }
-        this.updateInfo.compositesBeingExpanded.splice(targetInd, 1);
-
-        compositesExpanded.push(component.componentIdx);
-
-        return { success: true, compositesExpanded };
-    }
-
-    /**
-     * If `composite` has `createComponentIdx` specified,
-     * then its one replacement should have the componentIdx.
-     * Similarly, if it has `createComponentName` specified,
-     * then its one replacement receive that name.
-     */
-    adjustForCreateComponentIdxName(serializedReplacements, composite) {
-        if (serializedReplacements.length === 1) {
-            if (
-                composite.attributes.createComponentIdx?.primitive.value !=
-                undefined
-            ) {
-                serializedReplacements[0].componentIdx =
-                    composite.attributes.createComponentIdx.primitive.value;
-            }
-
-            if (
-                composite.attributes.createComponentName?.primitive.value !=
-                undefined
-            ) {
-                serializedReplacements[0].attributes.name = {
-                    type: "primitive",
-                    name: "name",
-                    primitive: {
-                        type: "string",
-                        value: composite.attributes.createComponentName
-                            .primitive.value,
-                    },
-                };
-            }
-        }
-    }
-
-    async createAndSetReplacements({ component, serializedReplacements }) {
-        this.parameterStack.push(component.sharedParameters, false);
-
-        try {
-            let replacementResult = await this.createIsolatedComponents({
-                serializedComponents: serializedReplacements,
-                ancestors: component.ancestors,
-                shadow: true,
-                componentsReplacementOf: component,
-            });
-            component.replacements = replacementResult.components;
-        } catch (e) {
-            console.error(e);
-            // throw e;
-            component.replacements = await this.setErrorReplacements({
-                composite: component,
-                message: e.message,
-            });
-        }
-        this.parameterStack.pop();
-
-        await this.dependencies.addBlockersFromChangedReplacements(component);
-
-        component.isExpanded = true;
-    }
-
-    async replaceCompositeChildren(parent) {
-        // if composite is not directly matched by any childGroup
-        // then replace the composite with its replacements,
-        // expanding it if not already expanded
-
-        // console.log(`replace composite children of ${parent.componentIdx}`)
-
-        delete parent.placeholderActiveChildrenIndices;
-        delete parent.placeholderActiveChildrenIndicesByComposite;
-        delete parent.compositeReplacementActiveRange;
-
-        let undisplayableErrorChildren;
-
-        let nPlaceholdersAdded = 0;
-
-        for (
-            let childInd = 0;
-            childInd < parent.activeChildren.length;
-            childInd++
-        ) {
-            let child = parent.activeChildren[childInd];
-
-            if (
-                child instanceof
-                this.componentInfoObjects.allComponentClasses._composite
-            ) {
-                // if composite itself is in the child logic
-                // then don't replace it with its replacements
-                // but leave the composite as an activeChild
-                if (
-                    this.findChildGroup(child.componentType, parent.constructor)
-                        .success
-                ) {
-                    continue;
-                }
-
-                let replaceWithPlaceholders = false;
-
-                // if an unexpanded composite has a createComponentOfType specified
-                // replace with placeholders
-                // otherwise, leave composite as an activeChild
-                if (!child.isExpanded) {
-                    if (child.attributes.createComponentOfType?.primitive) {
-                        replaceWithPlaceholders = true;
-                    } else {
-                        continue;
-                    }
-                }
-
-                let replacements;
-
-                if (replaceWithPlaceholders) {
-                    let numComponents;
-
-                    if (child.attributes.numComponents) {
-                        numComponents =
-                            child.attributes.numComponents.primitive.value;
-                    } else {
-                        numComponents = 1;
-                    }
-
-                    let componentType =
-                        this.componentInfoObjects.componentTypeLowerCaseMapping[
-                            child.attributes.createComponentOfType.primitive.value.toLowerCase()
-                        ];
-                    replacements = [];
-
-                    for (let i = 0; i < numComponents; i++) {
-                        replacements.push({
-                            componentType,
-                            fromComposite: child.componentIdx,
-                            placeholderInd: nPlaceholdersAdded,
-                        });
-                        nPlaceholdersAdded++;
-                    }
-
-                    parent.hasPlaceholderActiveChildren = true;
-                    let placeholdInds = [...Array(numComponents).keys()].map(
-                        (x) => x + childInd,
-                    );
-
-                    if (!parent.placeholderActiveChildrenIndices) {
-                        parent.placeholderActiveChildrenIndices = [];
-                    }
-                    parent.placeholderActiveChildrenIndices.push(
-                        ...placeholdInds,
-                    );
-
-                    if (!parent.placeholderActiveChildrenIndicesByComposite) {
-                        parent.placeholderActiveChildrenIndicesByComposite = {};
-                    }
-                    parent.placeholderActiveChildrenIndicesByComposite[
-                        child.componentIdx
-                    ] = placeholdInds;
-                } else {
-                    // don't use any replacements that are marked as being withheld
-                    await this.markWithheldReplacementsInactive(child);
-
-                    replacements = child.replacements;
-                    if (child.replacementsToWithhold > 0) {
-                        replacements = replacements.slice(
-                            0,
-                            -child.replacementsToWithhold,
-                        );
-                    }
-
-                    // don't include blank string replacements if parent excludes blank children
-                    if (
-                        !parent.constructor.includeBlankStringChildren ||
-                        parent.constructor.removeBlankStringChildrenPostSugar
-                    ) {
-                        replacements = replacements.filter(
-                            (x) => typeof x !== "string" || /\S/.test(x),
-                        );
-                    }
-                }
-
-                if (!parent.compositeReplacementActiveRange) {
-                    parent.compositeReplacementActiveRange = [];
-                }
-
-                // Record whether or not each component can be considered an element of a list.
-                // If this composite or a containing composite has asList set,
-                // then it may be turned into a list if all the components can be list elements.
-
-                // All inline components and any components with canBeInList set
-                // are considered potential components for a list.
-                let replacementsCanBeInList = replacements.map((repl) =>
-                    Boolean(
-                        typeof repl !== "object" ||
-                        (this.componentInfoObjects.isInheritedComponentType({
-                            inheritedComponentType: repl.componentType,
-                            baseComponentType: "_inline",
-                        }) &&
-                            repl.constructor.canBeInList !== false) ||
-                        repl.constructor.canBeInList,
-                    ),
-                );
-
-                for (let otherCompositeObject of parent.compositeReplacementActiveRange) {
-                    if (otherCompositeObject.lastInd >= childInd) {
-                        otherCompositeObject.lastInd += replacements.length - 1;
-                        otherCompositeObject.potentialListComponents.splice(
-                            childInd,
-                            1,
-                            ...replacementsCanBeInList,
-                        );
-                    }
-                }
-
-                if (
-                    replacements.some(
-                        (repl) => repl.componentType === "_error",
-                    ) &&
-                    !parent.constructor.canDisplayChildErrors
-                ) {
-                    // The composite returned an error but this parent cannot display child errors,
-                    // so remove it from the replacements
-                    // (to avoid a confusing warning about an invalid _error child)
-                    // and store it in undisplayableErrorChildren.
-                    // We will add these error children to an ancestor that can display them, below.
-
-                    if (!undisplayableErrorChildren) {
-                        undisplayableErrorChildren = [];
-                    }
-                    let errorReplacements = replacements.filter(
-                        (repl) => repl.componentType === "_error",
-                    );
-                    replacements = replacements.filter(
-                        (repl) => repl.componentType !== "_error",
-                    );
-                    undisplayableErrorChildren.push(...errorReplacements);
-                }
-
-                // compositeReplacementActiveRange will be used
-                // - in renderers to determined if they should add commas
-                // - in child dependencies, where they will be translated for matched children
-                //   and used in some components to determine if those children can be formed into a list
-                if (child.isExpanded) {
-                    parent.compositeReplacementActiveRange.push({
-                        compositeIdx: child.componentIdx,
-                        compositeName:
-                            this.rootNames?.[child.componentIdx] ??
-                            "_id_" + child.componentIdx.toString(),
-                        extendIdx: await child.stateValues.extendIdx,
-                        unresolvedPath: await child.stateValues.unresolvedPath,
-                        firstInd: childInd,
-                        lastInd: childInd + replacements.length - 1,
-                        asList: await child.stateValues.asList,
-                        potentialListComponents: replacementsCanBeInList,
-                    });
-                }
-
-                parent.activeChildren.splice(childInd, 1, ...replacements);
-
-                // Update allChildren object with info on composite and its replacemnts
-                let allChildrenObj = parent.allChildren[child.componentIdx];
-                delete allChildrenObj.activeChildrenIndex;
-                for (let ind2 = 0; ind2 < replacements.length; ind2++) {
-                    let replacement = replacements[ind2];
-                    if (replacement.componentIdx != undefined) {
-                        // ignore placeholder, string, and primitive number active children
-                        parent.allChildren[replacement.componentIdx] = {
-                            activeChildrenIndex: childInd + ind2,
-                            component: replacement,
-                        };
-                    }
-                }
-
-                // find index of child in allChildrenOrdered
-                // and place replacements immediately afterward
-                let ind2 = parent.allChildrenOrdered.indexOf(
-                    child.componentIdx,
-                );
-                parent.allChildrenOrdered.splice(
-                    ind2 + 1,
-                    0,
-                    ...replacements
-                        .filter((x) => typeof x === "object")
-                        .map((x) =>
-                            x.componentIdx ? x.componentIdx : x.placeholderInd,
-                        ),
-                );
-
-                if (replacements.length !== 1) {
-                    // if replaced composite with anything other than one replacement
-                    // shift activeChildrenIndices of later children
-                    let nShift = replacements.length - 1;
-                    for (
-                        let ind2 = childInd + replacements.length;
-                        ind2 < parent.activeChildren.length;
-                        ind2++
-                    ) {
-                        let child2 = parent.activeChildren[ind2];
-                        if (child2.componentIdx != undefined) {
-                            parent.allChildren[
-                                child2.componentIdx
-                            ].activeChildrenIndex += nShift;
-                        }
-                    }
-                }
-
-                // rewind one index, in case any of the new activeChildren are composites
-                childInd--;
-            }
-        }
-
-        if (undisplayableErrorChildren) {
-            await this.addUndisplayableErrorChildrenToAncestor(
-                parent,
-                undisplayableErrorChildren,
-            );
-        }
-    }
-
-    async addUndisplayableErrorChildrenToAncestor(
-        parent,
-        undisplayableErrorChildren,
-    ) {
-        // If parent had an error added by a composite, but it can't display errors,
-        // then look for an ancestor that can display errors
-        // (which will exist since document can display errors).
-        // Add the errors to the defining children of that ancestor.
-        // Note: this breaks the rules of DoenetML and
-        // it is possible that these errors will accumulate in the ancestor
-        // if this code is repeated. But, the DoenetML is broken anyway with errors,
-        // and the purpose is just to make sure that the error is prominently displayed.
-
-        let ancestorToDisplayErrors = parent;
-        let definingChildIndToAddError;
-        while (!ancestorToDisplayErrors.constructor.canDisplayChildErrors) {
-            let nextAncestor =
-                this._components[ancestorToDisplayErrors.parentIdx];
-
-            definingChildIndToAddError = nextAncestor.definingChildren.indexOf(
-                ancestorToDisplayErrors,
-            );
-
-            ancestorToDisplayErrors = nextAncestor;
-        }
-
-        // if child wasn't a defining child, put the error as the first child
-        if (definingChildIndToAddError === -1) {
-            definingChildIndToAddError = 0;
-        }
-
-        ancestorToDisplayErrors.definingChildren.splice(
-            definingChildIndToAddError,
-            0,
-            ...undisplayableErrorChildren,
-        );
-
-        await this.processNewDefiningChildren({
-            parent: ancestorToDisplayErrors,
-            expandComposites: false,
-        });
-    }
-
-    async markWithheldReplacementsInactive(composite) {
-        let numActive = composite.replacements.length;
-
-        if (await composite.stateValues.isInactiveCompositeReplacement) {
-            numActive = 0;
-        } else if (composite.replacementsToWithhold > 0) {
-            numActive -= composite.replacementsToWithhold;
-        }
-
-        for (let repl of composite.replacements.slice(0, numActive)) {
-            await this.changeInactiveComponentAndDescendants(repl, false);
-        }
-
-        for (let repl of composite.replacements.slice(numActive)) {
-            await this.changeInactiveComponentAndDescendants(repl, true);
-        }
-
-        // composite is newly active
-        // if updates to replacements were postponed
-        // add them back to the queue
-        if (!(await composite.stateValues.isInactiveCompositeReplacement)) {
-            let cIdx = composite.componentIdx;
-            if (
-                this.updateInfo.inactiveCompositesToUpdateReplacements.has(cIdx)
-            ) {
-                this.updateInfo.inactiveCompositesToUpdateReplacements.delete(
-                    cIdx,
-                );
-                this.updateInfo.compositesToUpdateReplacements.add(cIdx);
-            }
-        }
-    }
-
-    async changeInactiveComponentAndDescendants(component, inactive) {
-        if (typeof component !== "object") {
-            return;
-        }
-
-        if (
-            (await component.stateValues.isInactiveCompositeReplacement) !==
-            inactive
-        ) {
-            component.state.isInactiveCompositeReplacement.value = inactive;
-            await this.markUpstreamDependentsStale({
-                component,
-                varName: "isInactiveCompositeReplacement",
-            });
-            this.dependencies.recordActualChangeInUpstreamDependencies({
-                component,
-                varName: "isInactiveCompositeReplacement",
-            });
-            for (const childIdxStr in component.allChildren) {
-                await this.changeInactiveComponentAndDescendants(
-                    this._components[childIdxStr],
-                    inactive,
-                );
-            }
-
-            for (let attrName in component.attributes) {
-                let attrComp = component.attributes[attrName].component;
-                if (attrComp) {
-                    await this.changeInactiveComponentAndDescendants(
-                        this._components[attrComp.componentIdx],
-                        inactive,
-                    );
-                }
-            }
-
-            if (component.replacements) {
-                await this.markWithheldReplacementsInactive(component);
-            }
-        }
-    }
-
-    findShadowedChildInSerializedComponents({
-        serializedComponents,
-        shadowedComponentName,
-    }) {
-        for (let serializedComponent of serializedComponents) {
-            if (serializedComponent.originalIdx === shadowedComponentName) {
-                return serializedComponent;
-            }
-            if (serializedComponent.children) {
-                let result = this.findShadowedChildInSerializedComponents({
-                    serializedComponents: serializedComponent.children,
-                    shadowedComponentName,
-                });
-                if (result) {
-                    return result;
-                }
-            }
-        }
-
-        return;
-    }
-
-    async createStateVariableDefinitions({
-        componentClass,
-        prescribedDependencies,
-        componentIdx,
-    }) {
-        let redefineDependencies;
-
-        if (prescribedDependencies) {
-            for (const idxStr in prescribedDependencies) {
-                const idx = Number(idxStr);
-                let depArray = prescribedDependencies[idx];
-                for (let dep of depArray) {
-                    if (dep.dependencyType === "referenceShadow") {
-                        if (idx === componentIdx) {
-                            throw Error(
-                                `Circular dependency involving ${componentIdx}.`,
-                            );
-                        }
-                        redefineDependencies = {
-                            linkSource: "referenceShadow",
-                            targetIdx: idx,
-                            compositeIdx: dep.compositeIdx,
-                            propVariable: dep.propVariable,
-                            fromImplicitProp: dep.fromImplicitProp,
-                            arrayStateVariable: dep.arrayStateVariable,
-                            arrayKey: dep.arrayKey,
-                            ignorePrimaryStateVariable:
-                                dep.ignorePrimaryStateVariable,
-                            substituteForPrimaryStateVariable:
-                                dep.substituteForPrimaryStateVariable,
-                            firstLevelReplacement: dep.firstLevelReplacement,
-                            additionalStateVariableShadowing:
-                                dep.additionalStateVariableShadowing,
-                        };
-                    } else if (dep.dependencyType === "adapter") {
-                        redefineDependencies = {
-                            linkSource: "adapter",
-                            adapterTargetIdentity: dep.adapterTargetIdentity,
-                            adapterVariable: dep.adapterVariable,
-                            substituteForPrimaryStateVariable:
-                                dep.substituteForPrimaryStateVariable,
-                            stateVariablesToShadow: dep.stateVariablesToShadow,
-                        };
-                    }
-                }
-            }
-        }
-
-        let stateVariableDefinitions = {};
-
-        if (!redefineDependencies) {
-            this.createAttributeStateVariableDefinitions({
-                stateVariableDefinitions,
-                componentClass,
-            });
-        }
-
-        //  add state variable definitions from component class
-        let newDefinitions =
-            componentClass.returnNormalizedStateVariableDefinitions(
-                this.numerics,
-            );
-
-        Object.assign(stateVariableDefinitions, newDefinitions);
-
-        if (redefineDependencies) {
-            if (redefineDependencies.linkSource === "adapter") {
-                this.createAdapterStateVariableDefinitions({
-                    redefineDependencies,
-                    stateVariableDefinitions,
-                    componentClass,
-                });
-            } else {
-                await this.createReferenceShadowStateVariableDefinitions({
-                    redefineDependencies,
-                    stateVariableDefinitions,
-                    componentClass,
-                });
-            }
-        }
-
-        return stateVariableDefinitions;
-    }
-
-    createAttributeStateVariableDefinitions({
-        componentClass,
-        stateVariableDefinitions,
-    }) {
-        let attributes = preprocessAttributesObject(
-            componentClass.createAttributesObject(),
-        );
-
-        for (let attrName in attributes) {
-            let attributeSpecification = attributes[attrName];
-            if (!attributeSpecification.createStateVariable) {
-                continue;
-            }
-
-            let varName = attributeSpecification.createStateVariable;
-
-            let stateVarDef = (stateVariableDefinitions[varName] = {
-                isAttribute: true, // Note: isAttribute is not accessed anywhere
-                hasEssential: true,
-                provideEssentialValuesInDefinition: true,
-            });
-
-            if (attributeSpecification.public) {
-                stateVarDef.public = true;
-                stateVarDef.shadowingInstructions = {};
-                if (attributeSpecification.createPrimitiveOfType) {
-                    stateVarDef.shadowingInstructions.createComponentOfType =
-                        attributeSpecification.createPrimitiveOfType;
-                    if (
-                        stateVarDef.shadowingInstructions
-                            .createComponentOfType === "string"
-                    ) {
-                        stateVarDef.shadowingInstructions.createComponentOfType =
-                            "text";
-                    } else if (
-                        stateVarDef.shadowingInstructions
-                            .createComponentOfType === "stringArray"
-                    ) {
-                        stateVarDef.shadowingInstructions.createComponentOfType =
-                            "textList";
-                    } else if (
-                        stateVarDef.shadowingInstructions
-                            .createComponentOfType === "numberArray"
-                    ) {
-                        stateVarDef.shadowingInstructions.createComponentOfType =
-                            "numberList";
-                    }
-                } else if (attributeSpecification.createReferences) {
-                    throw Error(
-                        "Cannot make a public state variable from an attribute with createReferences",
-                    );
-                } else {
-                    stateVarDef.shadowingInstructions.createComponentOfType =
-                        attributeSpecification.createComponentOfType;
-                }
-            }
-
-            let stateVariableForAttributeValue;
-
-            if (attributeSpecification.createComponentOfType) {
-                let attributeClass =
-                    this.componentInfoObjects.allComponentClasses[
-                        attributeSpecification.createComponentOfType
-                    ];
-                if (!attributeClass) {
-                    throw Error(
-                        `Component type ${attributeSpecification.createComponentOfType} does not exist so cannot create state variable for attribute ${attrName} of componentType ${componentClass.componentType}.`,
-                    );
-                }
-
-                stateVariableForAttributeValue =
-                    attributeSpecification.componentStateVariableForAttributeValue;
-                if (stateVariableForAttributeValue === undefined) {
-                    stateVariableForAttributeValue =
-                        attributeClass.stateVariableToBeShadowed;
-                    if (stateVariableForAttributeValue === undefined) {
-                        stateVariableForAttributeValue = "value";
-                    }
-                }
-            }
-
-            stateVarDef.returnDependencies = function () {
-                let dependencies = {};
-                if (attributeSpecification.fallBackToParentStateVariable) {
-                    dependencies.parentValue = {
-                        dependencyType: "parentStateVariable",
-                        variableName:
-                            attributeSpecification.fallBackToParentStateVariable,
-                    };
-                }
-                if (
-                    attributeSpecification.fallBackToSourceCompositeStateVariable
-                ) {
-                    dependencies.sourceCompositeValue = {
-                        dependencyType: "sourceCompositeStateVariable",
-                        variableName:
-                            attributeSpecification.fallBackToSourceCompositeStateVariable,
-                    };
-                }
-                if (attributeSpecification.createPrimitiveOfType) {
-                    dependencies.attributePrimitive = {
-                        dependencyType: "attributePrimitive",
-                        attributeName: attrName,
-                    };
-                } else if (attributeSpecification.createReferences) {
-                    dependencies.attributeRefResolutions = {
-                        dependencyType: "attributeRefResolutions",
-                        attributeName: attrName,
-                    };
-                } else {
-                    dependencies.attributeComponent = {
-                        dependencyType: "attributeComponent",
-                        attributeName: attrName,
-                        variableNames: [stateVariableForAttributeValue],
-                    };
-                }
-
-                return dependencies;
-            };
-
-            stateVarDef.definition = function ({
-                dependencyValues,
-                usedDefault,
-                essentialValues,
-            }) {
-                let attributeValue;
-                if (dependencyValues.attributeComponent) {
-                    attributeValue =
-                        dependencyValues.attributeComponent.stateValues[
-                            stateVariableForAttributeValue
-                        ];
-                } else if (dependencyValues.attributePrimitive != null) {
-                    attributeValue = dependencyValues.attributePrimitive;
-                } else if (
-                    dependencyValues.attributeRefResolutions != null &&
-                    !usedDefault.attributeRefResolutions
-                ) {
-                    attributeValue = dependencyValues.attributeRefResolutions;
-                } else {
-                    // parentValue would be undefined if fallBackToParentStateVariable wasn't specified
-                    // parentValue would be null if the parentValue state variables
-                    // did not exist or its value was null
-                    let haveParentValue = dependencyValues.parentValue != null;
-                    if (
-                        haveParentValue &&
-                        !usedDefault.parentValue &&
-                        essentialValues[varName] === undefined
-                    ) {
-                        return {
-                            setValue: {
-                                [varName]: dependencyValues.parentValue,
-                            },
-                            checkForActualChange: { [varName]: true },
-                        };
-                    } else {
-                        // sourceCompositeValue would be undefined if fallBackToSourceCompositeStateVariable wasn't specified
-                        // sourceCompositeValue would be null if the sourceCompositeValue state variables
-                        // did not exist or its value was null
-
-                        let haveSourceCompositeValue =
-                            dependencyValues.sourceCompositeValue != null;
-                        if (
-                            haveSourceCompositeValue &&
-                            !usedDefault.sourceCompositeValue &&
-                            essentialValues[varName] === undefined
-                        ) {
-                            return {
-                                setValue: {
-                                    [varName]:
-                                        dependencyValues.sourceCompositeValue,
-                                },
-                                checkForActualChange: { [varName]: true },
-                            };
-                        } else {
-                            return {
-                                useEssentialOrDefaultValue: {
-                                    [varName]: true,
-                                },
-                                checkForActualChange: { [varName]: true },
-                            };
-                        }
-                    }
-                }
-
-                let res = validateAttributeValue({
-                    value: attributeValue,
-                    attributeSpecification,
-                    attribute: attrName,
-                });
-
-                return {
-                    setValue: { [varName]: res.value },
-                    checkForActualChange: { [varName]: true },
-                    sendDiagnostics: res.diagnostics,
-                };
-            };
-
-            if (!attributeSpecification.noInverse) {
-                stateVarDef.inverseDefinition = async function ({
-                    desiredStateVariableValues,
-                    dependencyValues,
-                    usedDefault,
-                    essentialValues,
-                }) {
-                    if (!dependencyValues.attributeComponent) {
-                        if (dependencyValues.attributePrimitive != null) {
-                            // can't invert if have primitive
-                            return { success: false };
-                        }
-                        if (dependencyValues.attributeRefResolutions != null) {
-                            // can't invert if have attribute ref resolutions
-                            return { success: false };
-                        }
-
-                        let haveParentValue =
-                            dependencyValues.parentValue != null;
-                        if (
-                            haveParentValue &&
-                            !usedDefault.parentValue &&
-                            essentialValues[varName] === undefined
-                        ) {
-                            // value from parent was used, so propagate back to parent
-                            return {
-                                success: true,
-                                instructions: [
-                                    {
-                                        setDependency: "parentValue",
-                                        desiredValue:
-                                            desiredStateVariableValues[varName],
-                                    },
-                                ],
-                            };
-                        } else {
-                            let haveSourceCompositeValue =
-                                dependencyValues.sourceCompositeValue != null;
-                            if (
-                                haveSourceCompositeValue &&
-                                !usedDefault.sourceCompositeValue &&
-                                essentialValues[varName] === undefined
-                            ) {
-                                // value from source composite was used, so propagate back to source composite
-                                return {
-                                    success: true,
-                                    instructions: [
-                                        {
-                                            setDependency:
-                                                "sourceCompositeValue",
-                                            desiredValue:
-                                                desiredStateVariableValues[
-                                                    varName
-                                                ],
-                                        },
-                                    ],
-                                };
-                            } else {
-                                // no component or primitive, so value is essential and give it the desired value, but validated
-
-                                let res = validateAttributeValue({
-                                    value: desiredStateVariableValues[varName],
-                                    attributeSpecification,
-                                    attribute: attrName,
-                                });
-
-                                return {
-                                    success: true,
-                                    instructions: [
-                                        {
-                                            setEssentialValue: varName,
-                                            value: res.value,
-                                        },
-                                    ],
-                                    sendDiagnostics: res.diagnostics,
-                                };
-                            }
-                        }
-                    }
-
-                    // attribute based on component
-
-                    return {
-                        success: true,
-                        instructions: [
-                            {
-                                setDependency: "attributeComponent",
-                                desiredValue:
-                                    desiredStateVariableValues[varName],
-                                variableIndex: 0,
-                            },
-                        ],
-                    };
-                };
-            }
-
-            let attributesToCopy = [
-                "forRenderer",
-                "defaultValue",
-                "propagateToProps",
-                "triggerActionOnChange",
-                "ignoreFixed",
-                "isLocation",
-                "essentialVarName",
-            ];
-
-            for (let attrName2 of attributesToCopy) {
-                if (attrName2 in attributeSpecification) {
-                    stateVarDef[attrName2] = attributeSpecification[attrName2];
-                }
-            }
-        }
-    }
-
-    createAdapterStateVariableDefinitions({
-        redefineDependencies,
-        stateVariableDefinitions,
-        componentClass,
-    }) {
-        // attributes depend on adapterTarget (if attribute exists in adapterTarget)
-        let adapterTargetComponent =
-            this._components[
-                redefineDependencies.adapterTargetIdentity.componentIdx
-            ];
-
-        let attributes = preprocessAttributesObject(
-            componentClass.createAttributesObject(),
-        );
-
-        for (let attrName in attributes) {
-            let attributeSpecification = attributes[attrName];
-            if (!attributeSpecification.createStateVariable) {
-                continue;
-            }
-
-            let varName = attributeSpecification.createStateVariable;
-
-            let stateVarDef = (stateVariableDefinitions[varName] = {
-                isAttribute: true, // Note: isAttribute is not accessed anywhere
-                hasEssential: true,
-            });
-
-            if (attributeSpecification.public) {
-                stateVarDef.public = true;
-                stateVarDef.shadowingInstructions = {};
-                if (attributeSpecification.createPrimitiveOfType) {
-                    stateVarDef.shadowingInstructions.createComponentOfType =
-                        attributeSpecification.createPrimitiveOfType;
-                    if (
-                        stateVarDef.shadowingInstructions
-                            .createComponentOfType === "string"
-                    ) {
-                        stateVarDef.shadowingInstructions.createComponentOfType =
-                            "text";
-                    } else if (
-                        stateVarDef.shadowingInstructions
-                            .createComponentOfType === "stringArray"
-                    ) {
-                        stateVarDef.shadowingInstructions.createComponentOfType =
-                            "textList";
-                    } else if (
-                        stateVarDef.shadowingInstructions
-                            .createComponentOfType === "numberArray"
-                    ) {
-                        stateVarDef.shadowingInstructions.createComponentOfType =
-                            "numberList";
-                    }
-                } else if (attributeSpecification.createReferences) {
-                    throw Error(
-                        "Cannot make a public state variable from an attribute with createReferences",
-                    );
-                } else {
-                    stateVarDef.shadowingInstructions.createComponentOfType =
-                        attributeSpecification.createComponentOfType;
-                }
-            }
-
-            if (varName in adapterTargetComponent.state) {
-                stateVarDef.returnDependencies = () => ({
-                    adapterTargetVariable: {
-                        dependencyType: "stateVariable",
-                        componentIdx:
-                            redefineDependencies.adapterTargetIdentity
-                                .componentIdx,
-                        variableName: varName,
-                    },
-                });
-            } else {
-                stateVarDef.returnDependencies = () => ({});
-            }
-
-            stateVarDef.definition = function ({
-                dependencyValues,
-                usedDefault,
-            }) {
-                if (
-                    dependencyValues.adapterTargetVariable === undefined ||
-                    usedDefault.adapterTargetVariable
-                ) {
-                    return {
-                        useEssentialOrDefaultValue: {
-                            [varName]: true,
-                        },
-                        checkForActualChange: { [varName]: true },
-                    };
-                } else {
-                    return {
-                        setValue: {
-                            [varName]: dependencyValues.adapterTargetVariable,
-                        },
-                        checkForActualChange: { [varName]: true },
-                    };
-                }
-            };
-
-            if (!attributeSpecification.noInverse) {
-                stateVarDef.inverseDefinition = async function ({
-                    desiredStateVariableValues,
-                    dependencyValues,
-                }) {
-                    if (dependencyValues.adapterTargetVariable === undefined) {
-                        return {
-                            success: true,
-                            instructions: [
-                                {
-                                    setEssentialValue: varName,
-                                    value: desiredStateVariableValues[varName],
-                                },
-                            ],
-                        };
-                    } else {
-                        return {
-                            success: true,
-                            instructions: [
-                                {
-                                    setDependency: "adapterTargetVariable",
-                                    desiredValue:
-                                        desiredStateVariableValues[varName],
-                                },
-                            ],
-                        };
-                    }
-                };
-            }
-
-            let attributesToCopy = [
-                "forRenderer",
-                "defaultValue",
-                "propagateToProps",
-                "ignoreFixed",
-                "isLocation",
-                "essentialVarName",
-            ];
-
-            for (let attrName2 of attributesToCopy) {
-                if (attrName2 in attributeSpecification) {
-                    stateVarDef[attrName2] = attributeSpecification[attrName2];
-                }
-            }
-        }
-
-        // primaryStateVariableForDefinition is the state variable that the componentClass
-        // being created has specified should be given the value when it
-        // is created from an outside source like a reference to a prop or an adapter
-        let primaryStateVariableForDefinition = "value";
-        if (redefineDependencies.substituteForPrimaryStateVariable) {
-            primaryStateVariableForDefinition =
-                redefineDependencies.substituteForPrimaryStateVariable;
-        } else if (componentClass.primaryStateVariableForDefinition) {
-            primaryStateVariableForDefinition =
-                componentClass.primaryStateVariableForDefinition;
-        }
-        let stateDef =
-            stateVariableDefinitions[primaryStateVariableForDefinition];
-        stateDef.isShadow = true;
-        stateDef.returnDependencies = () => ({
-            adapterTargetVariable: {
-                dependencyType: "stateVariable",
-                componentIdx:
-                    redefineDependencies.adapterTargetIdentity.componentIdx,
-                variableName: redefineDependencies.adapterVariable,
-            },
-        });
-        if (stateDef.set) {
-            stateDef.definition = function ({ dependencyValues }) {
-                return {
-                    setValue: {
-                        [primaryStateVariableForDefinition]: stateDef.set(
-                            dependencyValues.adapterTargetVariable,
-                        ),
-                    },
-                };
-            };
-        } else {
-            stateDef.definition = function ({ dependencyValues }) {
-                return {
-                    setValue: {
-                        [primaryStateVariableForDefinition]:
-                            dependencyValues.adapterTargetVariable,
-                    },
-                };
-            };
-        }
-        stateDef.inverseDefinition = function ({ desiredStateVariableValues }) {
-            return {
-                success: true,
-                instructions: [
-                    {
-                        setDependency: "adapterTargetVariable",
-                        desiredValue:
-                            desiredStateVariableValues[
-                                primaryStateVariableForDefinition
-                            ],
-                    },
-                ],
-            };
-        };
-
-        if (redefineDependencies.stateVariablesToShadow) {
-            this.modifyStateDefsToBeShadows({
-                stateVariablesToShadow:
-                    redefineDependencies.stateVariablesToShadow,
-                stateVariableDefinitions,
-                targetComponent: adapterTargetComponent,
-            });
-        }
-    }
-
-    async createReferenceShadowStateVariableDefinitions({
-        redefineDependencies,
-        stateVariableDefinitions,
-        componentClass,
-    }) {
-        let targetComponent = this._components[redefineDependencies.targetIdx];
-
-        if (redefineDependencies.propVariable) {
-            // if we have an array entry state variable that hasn't been created yet
-            // create it now
-            if (
-                !targetComponent.state[redefineDependencies.propVariable] &&
-                this.checkIfArrayEntry({
-                    stateVariable: redefineDependencies.propVariable,
-                    component: targetComponent,
-                }).isArrayEntry
-            ) {
-                await this.createFromArrayEntry({
-                    stateVariable: redefineDependencies.propVariable,
-                    component: targetComponent,
-                });
-            }
-        }
-
-        // attributes depend
-        // - first on attributes from component attribute components, if they exist
-        // - then on targetComponent (if not copying a prop and attribute exists in targetComponent)
-
-        let attributes = preprocessAttributesObject(
-            componentClass.createAttributesObject(),
-        );
-
-        for (let attrName in attributes) {
-            let attributeSpecification = attributes[attrName];
-            let varName = attributeSpecification.createStateVariable;
-            if (!varName) {
-                continue;
-            }
-
-            let stateVarDef = (stateVariableDefinitions[varName] = {
-                isAttribute: true, // Note: isAttribute is not accessed anywhere
-                hasEssential: true,
-                provideEssentialValuesInDefinition: true,
-            });
-
-            let attributeFromPrimitive =
-                !attributeSpecification.createComponentOfType;
-
-            if (attributeSpecification.public) {
-                stateVarDef.public = true;
-                stateVarDef.shadowingInstructions = {};
-                if (attributeSpecification.createPrimitiveOfType) {
-                    stateVarDef.shadowingInstructions.createComponentOfType =
-                        attributeSpecification.createPrimitiveOfType;
-                    if (
-                        stateVarDef.shadowingInstructions
-                            .createComponentOfType === "string"
-                    ) {
-                        stateVarDef.shadowingInstructions.createComponentOfType =
-                            "text";
-                    } else if (
-                        stateVarDef.shadowingInstructions
-                            .createComponentOfType === "stringArray"
-                    ) {
-                        stateVarDef.shadowingInstructions.createComponentOfType =
-                            "textList";
-                    } else if (
-                        stateVarDef.shadowingInstructions
-                            .createComponentOfType === "numberArray"
-                    ) {
-                        stateVarDef.shadowingInstructions.createComponentOfType =
-                            "numberList";
-                    }
-                } else if (attributeSpecification.createReferences) {
-                    throw Error(
-                        "Cannot make a public state variable from an attribute with createReferences",
-                    );
-                } else {
-                    stateVarDef.shadowingInstructions.createComponentOfType =
-                        attributeSpecification.createComponentOfType;
-                }
-            }
-
-            let stateVariableForAttributeValue;
-
-            if (attributeSpecification.createComponentOfType) {
-                let attributeClass =
-                    this.componentInfoObjects.allComponentClasses[
-                        attributeSpecification.createComponentOfType
-                    ];
-                if (!attributeClass) {
-                    throw Error(
-                        `Component type ${attributeSpecification.createComponentOfType} does not exist so cannot create state variable for attribute ${attrName} of componentType ${componentClass.componentType}.`,
-                    );
-                }
-
-                stateVariableForAttributeValue =
-                    attributeSpecification.componentStateVariableForAttributeValue;
-                if (stateVariableForAttributeValue === undefined) {
-                    stateVariableForAttributeValue =
-                        attributeClass.stateVariableToBeShadowed;
-                    if (stateVariableForAttributeValue === undefined) {
-                        stateVariableForAttributeValue = "value";
-                    }
-                }
-            }
-
-            let thisDependencies = {};
-
-            if (attributeSpecification.createPrimitiveOfType) {
-                thisDependencies.attributePrimitive = {
-                    dependencyType: "attributePrimitive",
-                    attributeName: attrName,
-                };
-            } else if (attributeSpecification.createReferences) {
-                thisDependencies.attributeRefResolutions = {
-                    dependencyType: "attributeRefResolutions",
-                    attributeName: attrName,
-                };
-            } else {
-                thisDependencies.attributeComponent = {
-                    dependencyType: "attributeComponent",
-                    attributeName: attrName,
-                    variableNames: [stateVariableForAttributeValue],
-                };
-            }
-
-            if (attributeSpecification.fallBackToParentStateVariable) {
-                thisDependencies.parentValue = {
-                    dependencyType: "parentStateVariable",
-                    variableName:
-                        attributeSpecification.fallBackToParentStateVariable,
-                };
-            }
-            if (attributeSpecification.fallBackToSourceCompositeStateVariable) {
-                thisDependencies.sourceCompositeValue = {
-                    dependencyType: "sourceCompositeStateVariable",
-                    variableName:
-                        attributeSpecification.fallBackToSourceCompositeStateVariable,
-                };
-            }
-
-            stateVarDef.returnDependencies = () => thisDependencies;
-
-            stateVarDef.definition = function ({
-                dependencyValues,
-                usedDefault,
-                essentialValues,
-            }) {
-                let attributeValue;
-                if (dependencyValues.attributeComponent) {
-                    attributeValue =
-                        dependencyValues.attributeComponent.stateValues[
-                            stateVariableForAttributeValue
-                        ];
-                } else if (dependencyValues.attributePrimitive != null) {
-                    attributeValue = dependencyValues.attributePrimitive;
-                } else if (
-                    dependencyValues.attributeRefResolutions != null &&
-                    !usedDefault.attributeRefResolutions
-                ) {
-                    attributeValue = dependencyValues.attributeRefResolutions;
-                } else {
-                    // parentValue would be undefined if fallBackToParentStateVariable wasn't specified
-                    // parentValue would be null if the parentValue state variables
-                    // did not exist or its value was null
-                    let haveParentValue = dependencyValues.parentValue != null;
-                    if (
-                        haveParentValue &&
-                        !usedDefault.parentValue &&
-                        essentialValues[varName] === undefined
-                    ) {
-                        return {
-                            setValue: {
-                                [varName]: dependencyValues.parentValue,
-                            },
-                            checkForActualChange: { [varName]: true },
-                        };
-                    } else {
-                        // sourceCompositeValue would be undefined if fallBackToSourceCompositeStateVariable wasn't specified
-                        // sourceCompositeValue would be null if the sourceCompositeValue state variables
-                        // did not exist or its value was null
-
-                        let haveSourceCompositeValue =
-                            dependencyValues.sourceCompositeValue != null;
-                        if (
-                            haveSourceCompositeValue &&
-                            !usedDefault.sourceCompositeValue &&
-                            essentialValues[varName] === undefined
-                        ) {
-                            return {
-                                setValue: {
-                                    [varName]:
-                                        dependencyValues.sourceCompositeValue,
-                                },
-                                checkForActualChange: { [varName]: true },
-                            };
-                        } else {
-                            return {
-                                useEssentialOrDefaultValue: {
-                                    [varName]: true,
-                                },
-                                checkForActualChange: { [varName]: true },
-                            };
-                        }
-                    }
-                }
-
-                let res = validateAttributeValue({
-                    value: attributeValue,
-                    attributeSpecification,
-                    attribute: attrName,
-                });
-
-                return {
-                    setValue: { [varName]: res.value },
-                    checkForActualChange: { [varName]: true },
-                    sendDiagnostics: res.diagnostics,
-                };
-            };
-
-            if (!attributeSpecification.noInverse) {
-                stateVarDef.inverseDefinition = async function ({
-                    desiredStateVariableValues,
-                    dependencyValues,
-                    usedDefault,
-                    essentialValues,
-                    stateValues,
-                    workspace,
-                }) {
-                    if (!dependencyValues.attributeComponent) {
-                        if (dependencyValues.attributePrimitive != null) {
-                            // can't invert if have primitive
-                            return { success: false };
-                        }
-                        if (dependencyValues.attributeRefResolutions != null) {
-                            // can't invert if have attribute ref resolutions
-                            return { success: false };
-                        }
-
-                        let haveParentValue =
-                            dependencyValues.parentValue != null;
-                        if (
-                            haveParentValue &&
-                            !usedDefault.parentValue &&
-                            essentialValues[varName] === undefined
-                        ) {
-                            // value from parent was used, so propagate back to parent
-                            return {
-                                success: true,
-                                instructions: [
-                                    {
-                                        setDependency: "parentValue",
-                                        desiredValue:
-                                            desiredStateVariableValues[varName],
-                                    },
-                                ],
-                            };
-                        } else {
-                            let haveSourceCompositeValue =
-                                dependencyValues.sourceCompositeValue != null;
-                            if (
-                                haveSourceCompositeValue &&
-                                !usedDefault.sourceCompositeValue &&
-                                essentialValues[varName] === undefined
-                            ) {
-                                // value from source composite was used, so propagate back to source composite
-                                return {
-                                    success: true,
-                                    instructions: [
-                                        {
-                                            setDependency:
-                                                "sourceCompositeValue",
-                                            desiredValue:
-                                                desiredStateVariableValues[
-                                                    varName
-                                                ],
-                                        },
-                                    ],
-                                };
-                            } else {
-                                // no component or primitive, so value is essential and give it the desired value, but validated
-                                let res = validateAttributeValue({
-                                    value: desiredStateVariableValues[varName],
-                                    attributeSpecification,
-                                    attribute: attrName,
-                                });
-
-                                return {
-                                    success: true,
-                                    instructions: [
-                                        {
-                                            setEssentialValue: varName,
-                                            value: res.value,
-                                        },
-                                    ],
-                                    sendDiagnostics: res.diagnostics,
-                                };
-                            }
-                        }
-                    }
-                    // attribute based on child
-
-                    return {
-                        success: true,
-                        instructions: [
-                            {
-                                setDependency: "attributeComponent",
-                                desiredValue:
-                                    desiredStateVariableValues[varName],
-                                variableIndex: 0,
-                            },
-                        ],
-                    };
-                };
-            }
-
-            let attributesToCopy = [
-                "forRenderer",
-                "defaultValue",
-                "propagateToProps",
-                "ignoreFixed",
-                "isLocation",
-                "essentialVarName",
-            ];
-
-            for (let attrName2 of attributesToCopy) {
-                if (attrName2 in attributeSpecification) {
-                    stateVarDef[attrName2] = attributeSpecification[attrName2];
-                }
-            }
-        }
-
-        if (redefineDependencies.propVariable) {
-            if (!redefineDependencies.ignorePrimaryStateVariable) {
-                // primaryStateVariableForDefinition is the state variable that the componentClass
-                // being created has specified should be given the value when it
-                // is created from an outside source like a reference to a prop or an adapter
-                let primaryStateVariableForDefinition = "value";
-                if (redefineDependencies.substituteForPrimaryStateVariable) {
-                    primaryStateVariableForDefinition =
-                        redefineDependencies.substituteForPrimaryStateVariable;
-                } else if (componentClass.primaryStateVariableForDefinition) {
-                    primaryStateVariableForDefinition =
-                        componentClass.primaryStateVariableForDefinition;
-                }
-                let stateDef =
-                    stateVariableDefinitions[primaryStateVariableForDefinition];
-                if (!stateDef) {
-                    if (
-                        redefineDependencies.substituteForPrimaryStateVariable
-                    ) {
-                        throw Error(
-                            `Invalid public state variable of componentType ${componentClass.componentType}: substituteForPrimaryStateVariable ${redefineDependencies.substituteForPrimaryStateVariable} does not exist`,
-                        );
-                    } else {
-                        throw Error(
-                            `Cannot have a public state variable with componentType ${componentClass.componentType} as the class doesn't have a primary state variable for definition`,
-                        );
-                    }
-                }
-                stateDef.isShadow = true;
-                stateDef.returnDependencies = () => ({
-                    targetVariable: {
-                        dependencyType: "stateVariable",
-                        componentIdx: targetComponent.componentIdx,
-                        variableName: redefineDependencies.propVariable,
-                    },
-                });
-
-                let setDefault = false;
-                if (
-                    targetComponent.state[redefineDependencies.propVariable]
-                        .defaultValue !== undefined
-                ) {
-                    stateDef.defaultValue =
-                        targetComponent.state[
-                            redefineDependencies.propVariable
-                        ].defaultValue;
-                    if (stateDef.set) {
-                        stateDef.defaultValue = stateDef.set(
-                            stateDef.defaultValue,
-                        );
-                    }
-                    stateDef.hasEssential = true;
-                    setDefault = true;
-                }
-
-                let targetVariableIsArray =
-                    targetComponent.state[redefineDependencies.propVariable]
-                        .isArray;
-
-                if (stateDef.set) {
-                    stateDef.definition = function ({
-                        dependencyValues,
-                        usedDefault,
-                    }) {
-                        let targetVariable = dependencyValues.targetVariable;
-                        if (
-                            targetVariable === undefined ||
-                            (targetVariableIsArray &&
-                                targetVariable.length === 0)
-                        ) {
-                            // allow for case where we depend on array entry that does not yet exist
-                            return {
-                                useEssentialOrDefaultValue: {
-                                    [primaryStateVariableForDefinition]: true,
-                                },
-                            };
-                        }
-                        let valueFromTarget = stateDef.set(targetVariable);
-                        if (setDefault && usedDefault.targetVariable) {
-                            return {
-                                useEssentialOrDefaultValue: {
-                                    [primaryStateVariableForDefinition]: {
-                                        defaultValue: valueFromTarget,
-                                    },
-                                },
-                            };
-                        }
-                        return {
-                            setValue: {
-                                [primaryStateVariableForDefinition]:
-                                    valueFromTarget,
-                            },
-                        };
-                    };
-                } else {
-                    stateDef.definition = function ({
-                        dependencyValues,
-                        usedDefault,
-                    }) {
-                        let targetVariable = dependencyValues.targetVariable;
-                        if (
-                            targetVariable === undefined ||
-                            (targetVariableIsArray &&
-                                targetVariable.length === 0)
-                        ) {
-                            // allow for case where we depend on array entry that does not yet exist
-                            return {
-                                useEssentialOrDefaultValue: {
-                                    [primaryStateVariableForDefinition]: true,
-                                },
-                            };
-                        }
-                        if (setDefault && usedDefault.targetVariable) {
-                            return {
-                                useEssentialOrDefaultValue: {
-                                    [primaryStateVariableForDefinition]: {
-                                        defaultValue: targetVariable,
-                                    },
-                                },
-                            };
-                        }
-                        return {
-                            setValue: {
-                                [primaryStateVariableForDefinition]:
-                                    targetVariable,
-                            },
-                        };
-                    };
-                }
-                stateDef.inverseDefinition = function ({
-                    desiredStateVariableValues,
-                }) {
-                    return {
-                        success: true,
-                        instructions: [
-                            {
-                                setDependency: "targetVariable",
-                                desiredValue:
-                                    desiredStateVariableValues[
-                                        primaryStateVariableForDefinition
-                                    ],
-                            },
-                        ],
-                    };
-                };
-            }
-
-            let shadowStandardVariables = false;
-            let stateVariablesToShadow = [];
-            if (targetComponent.constructor.implicitPropReturnsSameType) {
-                if (redefineDependencies.fromImplicitProp) {
-                    shadowStandardVariables = true;
-                }
-
-                // shadow any variables marked as shadowVariable
-                for (let varName in targetComponent.state) {
-                    let stateObj = targetComponent.state[varName];
-                    if (stateObj.shadowVariable || stateObj.isShadow) {
-                        stateVariablesToShadow.push(varName);
-                    }
-                }
-            }
-
-            if (redefineDependencies.additionalStateVariableShadowing) {
-                // since using parallel arrays, start with empty array to match next indices
-                let differentStateVariablesInTarget = Array(
-                    stateVariablesToShadow.length,
-                );
-                for (let varName in redefineDependencies.additionalStateVariableShadowing) {
-                    if (!stateVariablesToShadow.includes(varName)) {
-                        stateVariablesToShadow.push(varName);
-                        differentStateVariablesInTarget.push(
-                            redefineDependencies
-                                .additionalStateVariableShadowing[varName]
-                                .stateVariableToShadow,
-                        );
-                    }
-                }
-
-                this.modifyStateDefsToBeShadows({
-                    stateVariablesToShadow,
-                    stateVariableDefinitions,
-                    targetComponent,
-                    differentStateVariablesInTarget,
-                });
-            } else if (shadowStandardVariables) {
-                this.modifyStateDefsToBeShadows({
-                    stateVariablesToShadow,
-                    stateVariableDefinitions,
-                    targetComponent,
-                });
-            }
-
-            // for referencing a prop variable, don't shadow standard state variables
-            // (unless except for above cases)
-            // so just return now
-            return;
-        }
-
-        let foundReadyToExpandWhenResolved = false;
-        if ("readyToExpandWhenResolved" in stateVariableDefinitions) {
-            // if shadowing a composite
-            // make readyToExpandWhenResolved depend on the same variable
-            // of the targetComponent also being resolved
-
-            foundReadyToExpandWhenResolved = true;
-
-            let stateDef = stateVariableDefinitions.readyToExpandWhenResolved;
-            let originalReturnDependencies =
-                stateDef.returnDependencies.bind(stateDef);
-            let originalDefinition = stateDef.definition;
-
-            stateDef.returnDependencies = function (args) {
-                let dependencies = originalReturnDependencies(args);
-                dependencies.targetReadyToExpandWhenResolved = {
-                    dependencyType: "stateVariable",
-                    componentIdx: targetComponent.componentIdx,
-                    variableName: "readyToExpandWhenResolved",
-                };
-                return dependencies;
-            };
-
-            // change definition so that it is false if targetComponent isn't ready to expand
-            stateDef.definition = function (args) {
-                let result = originalDefinition(args);
-
-                if (
-                    result.setValue &&
-                    result.setValue.readyToExpandWhenResolved
-                ) {
-                    if (
-                        !args.dependencyValues.targetReadyToExpandWhenResolved
-                    ) {
-                        result.setValue.readyToExpandWhenResolved = false;
-                    }
-                }
-                return result;
-            };
-        }
-
-        let stateVariablesToShadow = [];
-
-        // shadow any variables marked as shadowVariable
-        for (let varName in targetComponent.state) {
-            let stateObj = targetComponent.state[varName];
-            if (stateObj.shadowVariable || stateObj.isShadow) {
-                stateVariablesToShadow.push(varName);
-            }
-        }
-
-        this.modifyStateDefsToBeShadows({
-            stateVariablesToShadow,
-            stateVariableDefinitions,
-            foundReadyToExpandWhenResolved,
-            targetComponent,
-        });
-    }
-
-    modifyStateDefsToBeShadows({
-        stateVariablesToShadow,
-        stateVariableDefinitions,
-        foundReadyToExpandWhenResolved,
-        targetComponent,
-        differentStateVariablesInTarget = [],
-    }) {
-        // Note: if add a markStale function to these shadow,
-        // will need to modify array size state variable definition
-        // (createArraySizeStateVariable)
-        // to not overwrite markStale when it finds a shadow
-
-        let deleteStateVariablesFromDefinition = {};
-        for (let [varInd, varName] of stateVariablesToShadow.entries()) {
-            let stateDef = stateVariableDefinitions[varName];
-
-            if (stateDef === undefined) {
-                if (varName.slice(0, 8) === "__array_") {
-                    // have an array variable name that is created on the fly
-                    // rather than being specified in original definition.
-                    stateDef = stateVariableDefinitions[varName] = {};
-                } else {
-                    continue;
-                }
-            }
-
-            stateDef.isShadow = true;
-
-            if (stateDef.additionalStateVariablesDefined) {
-                for (let varName2 of stateDef.additionalStateVariablesDefined) {
-                    if (!stateVariablesToShadow.includes(varName2)) {
-                        // varName2 is not shadowed, however, it includes varName
-                        // in its definition
-                        if (!deleteStateVariablesFromDefinition[varName2]) {
-                            deleteStateVariablesFromDefinition[varName2] = [];
-                        }
-                        deleteStateVariablesFromDefinition[varName2].push(
-                            varName,
-                        );
-                    }
-                }
-            }
-            delete stateDef.additionalStateVariablesDefined;
-            if (!foundReadyToExpandWhenResolved) {
-                // if didn't find a readyToExpandWhenResolved,
-                // then won't use original dependencies so can delete any
-                // stateVariablesDeterminingDependencies
-                delete stateDef.stateVariablesDeterminingDependencies;
-            }
-
-            let copyComponentType =
-                stateDef.public &&
-                stateDef.shadowingInstructions.hasVariableComponentType;
-
-            if (stateDef.isArray) {
-                let overrideVarNameWith =
-                    differentStateVariablesInTarget[varInd];
-
-                stateDef.returnArrayDependenciesByKey = function ({
-                    arrayKeys,
-                }) {
-                    let dependenciesByKey = {};
-
-                    for (let key of arrayKeys) {
-                        dependenciesByKey[key] = {
-                            targetVariable: {
-                                dependencyType: "stateVariable",
-                                componentIdx: targetComponent.componentIdx,
-                                variableName:
-                                    overrideVarNameWith ||
-                                    this.arrayVarNameFromArrayKey(key),
-                            },
-                        };
-                    }
-
-                    let globalDependencies = {};
-
-                    if (copyComponentType) {
-                        globalDependencies.targetVariableComponentType = {
-                            dependencyType: "stateVariableComponentType",
-                            componentIdx: targetComponent.componentIdx,
-                            variableName: varName,
-                        };
-                    }
-
-                    if (stateDef.inverseShadowToSetEntireArray) {
-                        globalDependencies.targetArray = {
-                            dependencyType: "stateVariable",
-                            componentIdx: targetComponent.componentIdx,
-                            variableName: varName,
-                        };
-                    }
-
-                    return { globalDependencies, dependenciesByKey };
-                };
-
-                stateDef.arrayDefinitionByKey = function ({
-                    globalDependencyValues,
-                    dependencyValuesByKey,
-                    arrayKeys,
-                }) {
-                    // console.log(`shadow array definition by key for ${varName}`)
-                    // console.log(JSON.parse(JSON.stringify(globalDependencyValues)))
-                    // console.log(JSON.parse(JSON.stringify(dependencyValuesByKey)))
-                    // console.log(JSON.parse(JSON.stringify(arrayKeys)))
-
-                    let newEntries = {};
-
-                    for (let arrayKey of arrayKeys) {
-                        if (
-                            "targetVariable" in dependencyValuesByKey[arrayKey]
-                        ) {
-                            newEntries[arrayKey] =
-                                dependencyValuesByKey[arrayKey].targetVariable;
-                        } else {
-                            // put in a placeholder value until this can be rerun
-                            // with the updated dependencies
-                            newEntries[arrayKey] =
-                                stateDef.defaultValueByArrayKey?.(arrayKey);
-                        }
-                    }
-
-                    let result = {
-                        setValue: { [varName]: newEntries },
-                    };
-
-                    // TODO: how do we make it do this just once?
-                    if (
-                        "targetVariableComponentType" in globalDependencyValues
-                    ) {
-                        result.setCreateComponentOfType = {
-                            [varName]:
-                                globalDependencyValues.targetVariableComponentType,
-                        };
-                    }
-
-                    return result;
-                };
-
-                stateDef.inverseArrayDefinitionByKey = function ({
-                    desiredStateVariableValues,
-                    dependencyValuesByKey,
-                    dependencyNamesByKey,
-                    arraySize,
-                    initialChange,
-                }) {
-                    if (stateDef.inverseShadowToSetEntireArray) {
-                        return {
-                            success: true,
-                            instructions: [
-                                {
-                                    setDependency: "targetArray",
-                                    desiredValue:
-                                        desiredStateVariableValues[varName],
-                                    treatAsInitialChange: initialChange,
-                                },
-                            ],
-                        };
-                    }
-
-                    let instructions = [];
-                    for (let key in desiredStateVariableValues[varName]) {
-                        if (!dependencyValuesByKey[key]) {
-                            continue;
-                        }
-
-                        instructions.push({
-                            setDependency:
-                                dependencyNamesByKey[key].targetVariable,
-                            desiredValue:
-                                desiredStateVariableValues[varName][key],
-                            shadowedVariable: true,
-                        });
-                    }
-                    return {
-                        success: true,
-                        instructions,
-                    };
-                };
-            } else {
-                let returnStartingDependencies = () => ({});
-
-                if (foundReadyToExpandWhenResolved) {
-                    // even though won't use original dependencies
-                    // if found a readyToExpandWhenResolved
-                    // keep original dependencies so that readyToExpandWhenResolved
-                    // won't be resolved until all its dependent variables are resolved
-                    returnStartingDependencies =
-                        stateDef.returnDependencies.bind(stateDef);
-                }
-
-                let varNameInTarget = differentStateVariablesInTarget[varInd];
-                if (!varNameInTarget) {
-                    varNameInTarget = varName;
-                }
-
-                stateDef.returnDependencies = function (args) {
-                    let dependencies = Object.assign(
-                        {},
-                        returnStartingDependencies(args),
-                    );
-
-                    dependencies.targetVariable = {
-                        dependencyType: "stateVariable",
-                        componentIdx: targetComponent.componentIdx,
-                        variableName: varNameInTarget,
-                    };
-                    if (copyComponentType) {
-                        dependencies.targetVariableComponentType = {
-                            dependencyType: "stateVariableComponentType",
-                            componentIdx: targetComponent.componentIdx,
-                            variableName: varNameInTarget,
-                        };
-                    }
-                    return dependencies;
-                };
-                stateDef.definition = function ({
-                    dependencyValues,
-                    usedDefault,
-                }) {
-                    let result = {};
-
-                    // TODO: how do we make it do this just once?
-                    if ("targetVariableComponentType" in dependencyValues) {
-                        result.setCreateComponentOfType = {
-                            [varName]:
-                                dependencyValues.targetVariableComponentType,
-                        };
-                    }
-
-                    if (
-                        usedDefault.targetVariable &&
-                        "defaultValue" in stateDef &&
-                        stateDef.hasEssential
-                    ) {
-                        result.useEssentialOrDefaultValue = {
-                            [varName]: {
-                                defaultValue: dependencyValues.targetVariable,
-                            },
-                        };
-                    } else {
-                        result.setValue = {
-                            [varName]: dependencyValues.targetVariable,
-                        };
-                    }
-
-                    return result;
-                };
-                stateDef.excludeDependencyValuesInInverseDefinition = true;
-                stateDef.inverseDefinition = function ({
-                    desiredStateVariableValues,
-                }) {
-                    return {
-                        success: true,
-                        instructions: [
-                            {
-                                setDependency: "targetVariable",
-                                desiredValue:
-                                    desiredStateVariableValues[varName],
-                                shadowedVariable: true,
-                            },
-                        ],
-                    };
-                };
-            }
-        }
-        for (let varName in deleteStateVariablesFromDefinition) {
-            this.modifyStateDefToDeleteVariableReferences({
-                varNamesToDelete: deleteStateVariablesFromDefinition[varName],
-                stateDef: stateVariableDefinitions[varName],
-            });
-        }
-    }
-
-    modifyStateDefToDeleteVariableReferences({ varNamesToDelete, stateDef }) {
-        // delete variables from additionalStateVariablesDefined
-        for (let varName2 of varNamesToDelete) {
-            let ind =
-                stateDef.additionalStateVariablesDefined.indexOf(varName2);
-            stateDef.additionalStateVariablesDefined.splice(ind, 1);
-        }
-
-        // remove variables from definition
-        let originalDefinition = stateDef.definition;
-        stateDef.definition = function (args) {
-            let results = originalDefinition(args);
-            for (let key in results) {
-                if (Array.isArray(results[key])) {
-                    for (let varName2 of varNamesToDelete) {
-                        let ind = results[key].indexOf(varName2);
-                        if (ind !== -1) {
-                            results[key].splice(ind, 1);
-                        }
-                    }
-                } else {
-                    for (let varName2 of varNamesToDelete) {
-                        delete results[key][varName2];
-                    }
-                }
-            }
-            return results;
-        };
-    }
-
-    async initializeComponentStateVariables(component) {
-        for (let stateVariable in component.state) {
-            if (component.state[stateVariable].isAlias) {
-                if (!component.stateVarAliases) {
-                    component.stateVarAliases = {};
-                }
-                component.stateVarAliases[stateVariable] =
-                    component.state[stateVariable].targetVariableName;
-
-                // TODO: do we want to delete alias from state?
-                delete component.state[stateVariable];
-            } else {
-                await this.initializeStateVariable({
-                    component,
-                    stateVariable,
-                });
-            }
-        }
-    }
-
-    async initializeStateVariable({
-        component,
-        stateVariable,
-        arrayStateVariable,
-        arrayEntryPrefix,
-    }) {
-        let getStateVar = this.getStateVariableValue;
-        if (!component.state[stateVariable]) {
-            component.state[stateVariable] = {};
-        }
-        let stateVarObj = component.state[stateVariable];
-        stateVarObj.isResolved = false;
-        Object.defineProperty(stateVarObj, "value", {
-            get: () => getStateVar({ component, stateVariable }),
-            configurable: true,
-        });
-        // Object.defineProperty(stateVarObj, 'value', {
-        //   get:
-        //     async function () {
-        //       try {
-        //         return getStateVar({ component, stateVariable });
-        //       } catch (e) {
-        //         console.log(`got an error in getter`, e);
-        //         throw e;
-        //       }
-        //     },
-        //   configurable: true
-        // });
-
-        // Object.defineProperty(stateVarObj, 'value', { get: () => Promise.resolve(getStateVar({ component, stateVariable })), configurable: true });
-
-        if (arrayEntryPrefix !== undefined) {
-            await this.initializeArrayEntryStateVariable({
-                stateVarObj,
-                arrayStateVariable,
-                arrayEntryPrefix,
-                component,
-                stateVariable,
-            });
-        } else if (stateVarObj.isArray) {
-            await this.initializeArrayStateVariable({
-                stateVarObj,
-                component,
-                stateVariable,
-            });
-        }
-
-        if (stateVarObj.triggerActionOnChange) {
-            let componentTriggers =
-                this.stateVariableChangeTriggers[component.componentIdx];
-            if (!componentTriggers) {
-                componentTriggers = this.stateVariableChangeTriggers[
-                    component.componentIdx
-                ] = {};
-            }
-            componentTriggers[stateVariable] = {
-                action: stateVarObj.triggerActionOnChange,
-            };
-        }
-    }
-
-    async checkForActionChaining(args) {
-        return this.actionTriggerScheduler.checkForActionChaining(args);
-    }
-
-    async initializeArrayEntryStateVariable({
-        stateVarObj,
-        arrayStateVariable,
-        arrayEntryPrefix,
-        component,
-        stateVariable,
-    }) {
-        // This function used for initializing array entry variables
-        // (not the original array variable)
-        // It adds many attributes to state variables corresponding to
-        // array entries, including
-        // - arrayStateVariable: the name of the array for which this is an entry
-        // - arrayKeys: an array of the key(s) that constitute this entry
-        // - markStale: function from array state variable
-        // - freshnessInfo: object from array state variable
-        // - getValueFromArrayValues: function used to get this entry's value
-        // - isLocation: array entries are locations if the array state variable is
-        //   (See expanation of location in fixLocation state variable of BaseComponent.js)
-
-        stateVarObj.isArrayEntry = true;
-
-        stateVarObj.arrayStateVariable = arrayStateVariable;
-        let arrayStateVarObj = component.state[arrayStateVariable];
-        stateVarObj.definition = arrayStateVarObj.definition;
-        stateVarObj.inverseDefinition = arrayStateVarObj.inverseDefinition;
-        stateVarObj.markStale = arrayStateVarObj.markStale;
-        stateVarObj.freshnessInfo = arrayStateVarObj.freshnessInfo;
-        stateVarObj.getPreviousDependencyValuesForMarkStale =
-            arrayStateVarObj.getPreviousDependencyValuesForMarkStale;
-        stateVarObj.provideEssentialValuesInDefinition =
-            arrayStateVarObj.provideEssentialValuesInDefinition;
-        stateVarObj.providePreviousValuesInDefinition =
-            arrayStateVarObj.providePreviousValuesInDefinition;
-        stateVarObj.isLocation = arrayStateVarObj.isLocation;
-
-        stateVarObj.numDimensions =
-            arrayStateVarObj.returnEntryDimensions(arrayEntryPrefix);
-        stateVarObj.entryPrefix = arrayEntryPrefix;
-        stateVarObj.varEnding = stateVariable.slice(arrayEntryPrefix.length);
-
-        if (arrayStateVarObj.createWorkspace) {
-            stateVarObj.createWorkspace = true;
-            stateVarObj.workspace = arrayStateVarObj.workspace;
-        }
-
-        if (arrayStateVarObj.basedOnArrayKeyStateVariables) {
-            stateVarObj.basedOnArrayKeyStateVariables = true;
-        }
-
-        // if any of the additional state variables defined are arrays,
-        // (which should be all of them)
-        // transform to their array entry
-        if (arrayStateVarObj.additionalStateVariablesDefined) {
-            stateVarObj.additionalStateVariablesDefined = [];
-
-            let entryPrefixInd =
-                arrayStateVarObj.entryPrefixes.indexOf(arrayEntryPrefix);
-
-            for (let varName of arrayStateVarObj.additionalStateVariablesDefined) {
-                let sObj = component.state[varName];
-
-                if (sObj.isArray) {
-                    // find the same array entry prefix in the other array state variable
-                    let newArrayEntryPrefix =
-                        sObj.entryPrefixes[entryPrefixInd];
-                    let arrayEntryVarName =
-                        newArrayEntryPrefix + stateVarObj.varEnding;
-
-                    stateVarObj.additionalStateVariablesDefined.push(
-                        arrayEntryVarName,
-                    );
-                } else {
-                    stateVarObj.additionalStateVariablesDefined.push(varName);
-                }
-            }
-        }
-
-        if (arrayStateVarObj.shadowingInstructions) {
-            stateVarObj.shadowingInstructions = {};
-
-            // See description of returnWrappingComponents in initializeArrayStateVariable, below.
-            stateVarObj.wrappingComponents =
-                arrayStateVarObj.shadowingInstructions.returnWrappingComponents(
-                    arrayEntryPrefix,
-                );
-
-            if (arrayStateVarObj.shadowingInstructions.attributesToShadow) {
-                stateVarObj.shadowingInstructions.attributesToShadow =
-                    arrayStateVarObj.shadowingInstructions.attributesToShadow;
-            }
-
-            if (arrayStateVarObj.shadowingInstructions.createComponentOfType) {
-                let entryPrefixInd =
-                    arrayStateVarObj.entryPrefixes.indexOf(arrayEntryPrefix);
-                if (
-                    arrayStateVarObj.shadowingInstructions
-                        .createComponentOfType[entryPrefixInd]
-                ) {
-                    stateVarObj.shadowingInstructions.createComponentOfType = [
-                        arrayStateVarObj.shadowingInstructions
-                            .createComponentOfType[entryPrefixInd],
-                    ];
-                }
-            }
-        }
-
-        // Each arrayEntry state variable will have a function getValueFromArrayValue
-        // that will be used to retrieve the actual value of the components
-        // specified by this entry from the whole array stored in arrayValues
-        // Note: getValueFromArrayValues assumes that arrayValues has been populated
-        if (arrayStateVarObj.getEntryValues) {
-            // the function getEntryValues must have been overwritten by the class
-            // so use this function instead
-            stateVarObj.getValueFromArrayValues = async function () {
-                return await arrayStateVarObj.getEntryValues({
-                    varName: stateVariable,
-                });
-            };
-        } else {
-            // getValueFromArrayValues returns an array of the values
-            // that correspond to the arrayKeys of this entry state variable
-            // (returning a scalar instead if it is just a single value)
-            // It uses the function getArrayValue, which gets the values
-            // from arrayValues of the corresponding array state variable
-            stateVarObj.getValueFromArrayValues = async function () {
-                let arrayKeys = await stateVarObj.arrayKeys;
-                if (arrayKeys.length === 0) {
-                    return;
-                }
-                let value = [];
-                for (let arrayKey of arrayKeys) {
-                    value.push(arrayStateVarObj.getArrayValue({ arrayKey }));
-                }
-                if (value.length === 1) {
-                    return value[0];
-                } else {
-                    return value;
-                }
-            };
-        }
-
-        stateVarObj.arraySizeStateVariable =
-            arrayStateVarObj.arraySizeStateVariable;
-
-        stateVarObj._arrayKeys = [];
-        stateVarObj._unflattenedArrayKeys = [];
-
-        Object.defineProperty(stateVarObj, "arrayKeys", {
-            get: function () {
-                return (async () => {
-                    // first evaluate arraySize so _arrayKeys is recalculated
-                    // in case arraySize change
-                    await arrayStateVarObj.arraySize;
-                    return stateVarObj._arrayKeys;
-                })();
-            },
-        });
-
-        Object.defineProperty(stateVarObj, "unflattenedArrayKeys", {
-            get: function () {
-                return (async () => {
-                    // first evaluate arraySize so _unflattenedArrayKeys is recalculated
-                    // in case arraySize change
-                    await arrayStateVarObj.arraySize;
-                    return stateVarObj._unflattenedArrayKeys;
-                })();
-            },
-        });
-
-        if (
-            component.state[stateVarObj.arraySizeStateVariable]
-                .initiallyResolved
-        ) {
-            let arraySize = await arrayStateVarObj.arraySize;
-            let arrayKeys = arrayStateVarObj.getArrayKeysFromVarName({
-                arrayEntryPrefix: stateVarObj.entryPrefix,
-                varEnding: stateVarObj.varEnding,
-                arraySize,
-                numDimensions: arrayStateVarObj.numDimensions,
-            });
-
-            stateVarObj._unflattenedArrayKeys = arrayKeys;
-            stateVarObj._arrayKeys = flattenDeep(arrayKeys);
-
-            // for each arrayKey, add this entry name to the array's list variables
-            let varNamesIncluding = arrayStateVarObj.varNamesIncludingArrayKeys;
-            for (let arrayKey of stateVarObj._arrayKeys) {
-                if (!varNamesIncluding[arrayKey]) {
-                    varNamesIncluding[arrayKey] = [];
-                }
-                varNamesIncluding[arrayKey].push(stateVariable);
-            }
-        }
-
-        arrayStateVarObj.arrayEntryNames.push(stateVariable);
-
-        Object.defineProperty(stateVarObj, "arraySize", {
-            get: () => arrayStateVarObj.arraySize,
-        });
-
-        // TODO: delete since arrayEntrySize isn't currently used?
-        Object.defineProperty(stateVarObj, "arrayEntrySize", {
-            get: function () {
-                return (async () => {
-                    // assume array is rectangular, so just look at first subarray of each dimension
-                    let unflattenedArrayKeys =
-                        await stateVarObj.unflattenedArrayKeys;
-                    let arrayEntrySize = [];
-                    let subArray = [unflattenedArrayKeys];
-                    for (let i = 0; i < stateVarObj.numDimensions; i++) {
-                        subArray = subArray[0];
-                        arrayEntrySize.push(subArray.length);
-                    }
-                    arrayEntrySize.reverse(); // so starts with inner dimension
-                    return arrayEntrySize;
-                })();
-            },
-        });
-
-        if (arrayStateVarObj.stateVariablesDeterminingDependencies) {
-            if (!stateVarObj.stateVariablesDeterminingDependencies) {
-                stateVarObj.stateVariablesDeterminingDependencies = [];
-            }
-
-            for (let varName of arrayStateVarObj.stateVariablesDeterminingDependencies) {
-                if (
-                    !stateVarObj.stateVariablesDeterminingDependencies.includes(
-                        varName,
-                    )
-                ) {
-                    stateVarObj.stateVariablesDeterminingDependencies.push(
-                        varName,
-                    );
-                }
-            }
-        }
-
-        // add a returnDependencies function based on the array returnDependencies
-        let arrayReturnDependencies =
-            arrayStateVarObj.returnDependencies.bind(arrayStateVarObj);
-        stateVarObj.returnDependencies = async function (args) {
-            // add array size to argument of return dependencies
-            args.arraySize = await stateVarObj.arraySize;
-            args.arrayKeys = await stateVarObj.arrayKeys;
-            let dependencies = await arrayReturnDependencies(args);
-
-            // We keep track of how many names were defined when we calculate dependencies
-            // If this number changes, it should be treated as dependencies changing
-            // so that we recalculate the value of the arrayEntry variable
-            // TODO: we are communicating this to updateDependencies by adding
-            // an attribute to the arguments?  Is there a better way of doing it.
-            // Didn't want to add to the return value, as that would add complexity
-            // to how we normally define returnDependencies
-            // We could change returnDependencies to output an object.
-            // That would probably be cleaner.
-            let numNames = Object.keys(
-                arrayStateVarObj.dependencyNames.namesByKey,
-            ).length;
-            if (stateVarObj.numberNamesInPreviousReturnDep !== numNames) {
-                args.changedDependency = true;
-            }
-            stateVarObj.numberNamesInPreviousReturnDep = numNames;
-
-            return dependencies;
-        };
-    }
-
-    async initializeArrayStateVariable({
-        stateVarObj,
-        component,
-        stateVariable,
-    }) {
-        // This function used for initializing original array variables
-        // (not array entry variables)
-
-        // Arrays values are stored in a (possibly-multidimensional) array
-        // called arrayValues.  However, so that core doesn't have to deal
-        // with special cases for multiple dimensions, array values are typically
-        // referenced with an arrayKey, which is a single string that corresponds
-        // to a single entry in the array.
-        // For one dimension, index is an integer and arrayKey is its string representation
-        // For multiple dimensions, index is an array of integers, e.g. [i,j,k]
-        // and arrayKey is its string representation, i.e., "i,j,k"
-
-        // The function adds attributes to array state variables, including
-        // - arrayValues: the array of the current values of the array
-        //   (i.e., based on index rather than arrayKey)
-        //   arrayValues is used rather than value given that value is
-        //   sometimes deleted and replaced by a getter.  arrayValues is
-        //   never deleted, but entries are marked as stale using freshnessInfo
-        // - freshnessInfo: this object can be used to track information about the
-        //   freshness of the array entries or other array features, such as size.
-        //   freshnessInfo is prepopulated with
-        //     - a freshByKey object for tracking by key
-        //     - a freshArraySize for tracking array size
-        //   To take advantage of this object, a component can read and modify
-        //   freshnessInfo (as core will pass it in as an argument) in
-        //   - the state variable's definition function
-        //     (to short circuit calculation of something that is already fresh and/or
-        //     to indicate what is now fresh)
-        //   - the state variable's optional markStale function
-        //     (to indicate what is no longer fresh)
-        // - keyToIndex: maps arrayKey (single string) to (multi-)index
-        // - indexToKey: maps (multi-)index to arrayKey
-        // - setArrayValue: sets value in arrayValues corresponding to arrayKey
-        // - getArrayValue: gets value in arrayValues corresponding to arrayKey
-        // - getArrayKeysFromVarName: returns array of the arrayKeys that correspond
-        //   to a given variable name of an array entry
-        // - arrayVarNameFromArrayKey: returns the variable name of an array entry
-        //   that contains a given array key (if there are many, just return one)
-        //   This variable may not yet be created.
-
-        let core = this;
-
-        stateVarObj.arrayValues = [];
-
-        if (stateVarObj.numDimensions === undefined) {
-            stateVarObj.numDimensions = 1;
-        }
-
-        let entryPrefixes = stateVarObj.entryPrefixes;
-
-        if (!entryPrefixes) {
-            entryPrefixes = stateVarObj.entryPrefixes = [stateVariable];
-        }
-
-        if (!component.arrayEntryPrefixes) {
-            component.arrayEntryPrefixes = {};
-        }
-        for (let prefix of entryPrefixes) {
-            component.arrayEntryPrefixes[prefix] = stateVariable;
-        }
-
-        if (stateVarObj.numDimensions > 1) {
-            // for multiple dimensions, have to convert from arrayKey
-            // to multi-index when getting or setting
-            // Note: we don't check that arrayKey has the appropriate number of dimensions
-            // If it has fewer dimensions than numDimensions, it will set the slice
-            // to the given value
-            // (useful, for example, to set entire rows)
-            // If it has more dimensinos than numDimensions, behavior isn't determined
-            // (it should throw an error, assuming the array entries aren't arrays)
-            stateVarObj.keyToIndex = (key) =>
-                key.split(",").map((x) => Number(x));
-            stateVarObj.setArrayValue = function ({
-                value,
-                arrayKey,
-                arraySize,
-                arrayValues = stateVarObj.arrayValues,
-            }) {
-                let index = stateVarObj.keyToIndex(arrayKey);
-                let numDimensionsInArrayKey = index.length;
-                if (!numDimensionsInArrayKey > stateVarObj.numDimensions) {
-                    core.addDiagnostic({
-                        type: "info",
-                        message:
-                            "Cannot set array value.  Number of dimensions is too large.",
-                        position: component.position,
-                        sourceDoc: component.sourceDoc,
-                    });
-                    return { nFailures: 1 };
-                }
-                let arrayValuesDrillDown = arrayValues;
-                let arraySizeDrillDown = arraySize;
-                for (let indComponent of index.slice(0, index.length - 1)) {
-                    if (
-                        indComponent >= 0 &&
-                        indComponent < arraySizeDrillDown[0]
-                    ) {
-                        if (!arrayValuesDrillDown[indComponent]) {
-                            arrayValuesDrillDown[indComponent] = [];
-                        }
-                        arrayValuesDrillDown =
-                            arrayValuesDrillDown[indComponent];
-                        arraySizeDrillDown = arraySizeDrillDown.slice(1);
-                    } else {
-                        core.addDiagnostic({
-                            type: "info",
-                            message: "ignore setting array value out of bounds",
-                            position: component.position,
-                            sourceDoc: component.sourceDoc,
-                        });
-                        return { nFailures: 1 };
-                    }
-                }
-
-                let nFailures = 0;
-
-                if (numDimensionsInArrayKey < stateVarObj.numDimensions) {
-                    // if dimensions from arrayKey is less than number of dimensions
-                    // then attempt to get additional dimensions from
-                    // array indices of value
-
-                    let setArrayValuesPiece = function (
-                        desiredValue,
-                        arrayValuesPiece,
-                        arraySizePiece,
-                    ) {
-                        // try to set value of entries of arrayValuePiece to entries of desiredValue
-                        // given that size of arrayValuesPieces is arraySizePiece
-
-                        if (!Array.isArray(desiredValue)) {
-                            core.addDiagnostic({
-                                type: "info",
-                                message:
-                                    "ignoring array values with insufficient dimensions",
-                                position: component.position,
-                                sourceDoc: component.sourceDoc,
-                            });
-                            return { nFailures: 1 };
-                        }
-
-                        let nFailuresSub = 0;
-
-                        let currentSize = arraySizePiece[0];
-                        if (desiredValue.length > currentSize) {
-                            core.addDiagnostic({
-                                type: "info",
-                                message: "ignoring array values of out bounds",
-                                position: component.position,
-                                sourceDoc: component.sourceDoc,
-                            });
-                            nFailuresSub += desiredValue.length - currentSize;
-                            desiredValue = desiredValue.slice(0, currentSize);
-                        }
-
-                        if (arraySizePiece.length === 1) {
-                            // down to last dimension
-                            for (let [ind, val] of desiredValue.entries()) {
-                                arrayValuesPiece[ind] = val;
-                            }
-                        } else {
-                            for (let [ind, val] of desiredValue.entries()) {
-                                if (!arrayValuesPiece[ind]) {
-                                    arrayValuesPiece = [];
-                                }
-                                let result = setArrayValuesPiece(
-                                    val,
-                                    arrayValuesPiece[ind],
-                                    arraySizePiece[ind],
-                                );
-                                nFailuresSub += result.nFailures;
-                            }
-                        }
-
-                        return { nFailures: nFailuresSub };
-                    };
-
-                    let result = setArrayValuesPiece(
-                        value,
-                        arrayValuesDrillDown,
-                        arraySizeDrillDown,
-                    );
-                    nFailures += result.nFailures;
-                } else {
-                    arrayValuesDrillDown[index[index.length - 1]] = value;
-                }
-
-                return { nFailures };
-            };
-            stateVarObj.getArrayValue = function ({
-                arrayKey,
-                arrayValues = stateVarObj.arrayValues,
-            }) {
-                let index = stateVarObj.keyToIndex(arrayKey);
-                let aVals = arrayValues;
-                for (let indComponent of index.slice(0, index.length - 1)) {
-                    aVals = aVals[indComponent];
-                    if (!aVals) {
-                        return undefined;
-                    }
-                }
-                return aVals[index[index.length - 1]];
-            };
-
-            if (!stateVarObj.getAllArrayKeys) {
-                stateVarObj.getAllArrayKeys = function (
-                    arraySize,
-                    flatten = true,
-                    desiredSize,
-                ) {
-                    function prependToAllKeys(keys, newStuff) {
-                        for (let [ind, key] of keys.entries()) {
-                            if (Array.isArray(key)) {
-                                prependToAllKeys(key, newStuff);
-                            } else {
-                                keys[ind] = newStuff + "," + key;
-                            }
-                        }
-                    }
-
-                    function getAllArrayKeysSub(subArraySize) {
-                        if (subArraySize.length === 1) {
-                            // array of numbers from 0 to subArraySize[0], cast to strings
-                            return Array.from(Array(subArraySize[0]), (_, i) =>
-                                String(i),
-                            );
-                        } else {
-                            let currentSize = subArraySize[0];
-                            let subSubKeys = getAllArrayKeysSub(
-                                subArraySize.slice(1),
-                            );
-                            let subKeys = [];
-                            for (let ind = 0; ind < currentSize; ind++) {
-                                if (flatten) {
-                                    subKeys.push(
-                                        ...subSubKeys.map((x) => ind + "," + x),
-                                    );
-                                } else {
-                                    let newSubSubKeys = deepClone(subSubKeys);
-                                    prependToAllKeys(newSubSubKeys, ind);
-                                    subKeys.push(newSubSubKeys);
-                                }
-                            }
-                            return subKeys;
-                        }
-                    }
-
-                    if (desiredSize) {
-                        if (desiredSize.length === 0) {
-                            return [];
-                        } else {
-                            return getAllArrayKeysSub(desiredSize);
-                        }
-                    } else if (!arraySize || arraySize.length === 0) {
-                        return [];
-                    } else {
-                        return getAllArrayKeysSub(arraySize);
-                    }
-                };
-            }
-
-            if (!stateVarObj.arrayVarNameFromArrayKey) {
-                stateVarObj.arrayVarNameFromArrayKey = function (arrayKey) {
-                    return (
-                        entryPrefixes[0] +
-                        arrayKey
-                            .split(",")
-                            .map((x) => Number(x) + 1)
-                            .join("_")
-                    );
-                };
-            }
-
-            // arrayVarNameFromPropIndex is a function that calculates the name
-            // an array entry state variable that corresponds to the specified propIndex.
-            // It is a consequence of retrofitting the ability to index an array (e.g., $a.b[1])
-            // onto a system that was designed with just array entry variables (e..g, $a.b1).
-            // arrayVarNameFromPropIndex can be specified in the definition of the array state variable.
-            // Since numDimensions > 1 here, the default arrayVarNameFromPropIndex
-            // is to turn $a.b[1][2][3] to $a.p1_2_3,
-            // where "p" is the first entry prefix of the array "b".
-
-            // TODO: if we redesign arrays to be based on indices (or even slices),
-            // then arrayVarNameFromPropIndex will be obsolete.
-            if (!stateVarObj.arrayVarNameFromPropIndex) {
-                stateVarObj.arrayVarNameFromPropIndex =
-                    returnDefaultArrayVarNameFromPropIndex(
-                        stateVarObj.numDimensions,
-                        entryPrefixes[0],
-                    );
-            }
-
-            stateVarObj.adjustArrayToNewArraySize = async function () {
-                function resizeSubArray(subArray, subArraySize) {
-                    subArray.length = subArraySize[0];
-
-                    if (subArraySize.length > 1) {
-                        let subSubArraySize = subArraySize.slice(1);
-                        for (let [ind, subSubArray] of subArray.entries()) {
-                            if (!subSubArray) {
-                                // add in any empty entries
-                                subSubArray = subArray[ind] = [];
-                            }
-                            resizeSubArray(subSubArray, subSubArraySize);
-                        }
-                    }
-                }
-
-                let arraySize = await stateVarObj.arraySize;
-                resizeSubArray(stateVarObj.arrayValues, arraySize);
-            };
-        } else {
-            // have just one dimension
-            stateVarObj.keyToIndex = (key) => Number(key);
-            stateVarObj.setArrayValue = function ({
-                value,
-                arrayKey,
-                arraySize,
-                arrayValues = stateVarObj.arrayValues,
-            }) {
-                let ind = stateVarObj.keyToIndex(arrayKey);
-                if (ind >= 0 && ind < arraySize[0]) {
-                    arrayValues[ind] = value;
-                    return { nFailures: 0 };
-                } else {
-                    core.addDiagnostic({
-                        type: "info",
-                        message: `Ignoring setting array values out of bounds: ${arrayKey} of ${stateVariable}`,
-                        position: component.position,
-                        sourceDoc: component.sourceDoc,
-                    });
-                    return { nFailures: 1 };
-                }
-            };
-            stateVarObj.getArrayValue = function ({
-                arrayKey,
-                arrayValues = stateVarObj.arrayValues,
-            }) {
-                return arrayValues[arrayKey];
-            };
-
-            if (!stateVarObj.getAllArrayKeys) {
-                stateVarObj.getAllArrayKeys = function (
-                    arraySize,
-                    flatten,
-                    desiredSize,
-                ) {
-                    if (desiredSize) {
-                        if (desiredSize.length === 0) {
-                            return [];
-                        } else {
-                            // array of numbers from 0 to desiredSize[0], cast to strings
-                            return Array.from(Array(desiredSize[0]), (_, i) =>
-                                String(i),
-                            );
-                        }
-                    } else if (!arraySize || arraySize.length === 0) {
-                        return [];
-                    } else {
-                        // array of numbers from 0 to arraySize[0], cast to strings
-                        return Array.from(Array(arraySize[0]), (_, i) =>
-                            String(i),
-                        );
-                    }
-                };
-            }
-
-            if (!stateVarObj.arrayVarNameFromArrayKey) {
-                stateVarObj.arrayVarNameFromArrayKey = function (arrayKey) {
-                    return entryPrefixes[0] + String(Number(arrayKey) + 1);
-                };
-            }
-
-            // arrayVarNameFromPropIndex is a function that calculates the name
-            // an array entry state variable that corresponds to the specified propIndex.
-            // It is a consequence of retrofitting the ability to index an array (e.g., $a.b[1])
-            // onto a system that was designed with just array entry variables (e..g, $a.b1).
-            // arrayVarNameFromPropIndex can be specified in the definition of the array state variable.
-            // Since numDimensions = 1 here, the default arrayVarNameFromPropIndex
-            // is to turn $a.b[1] to $a.p1,
-            // where "p" is the first entry prefix of the array "b".
-
-            // TODO: if we redesign arrays to be based on indices (or even slices),
-            // then arrayVarNameFromPropIndex will be obsolete.
-            if (!stateVarObj.arrayVarNameFromPropIndex) {
-                stateVarObj.arrayVarNameFromPropIndex =
-                    returnDefaultArrayVarNameFromPropIndex(1, entryPrefixes[0]);
-            }
-
-            stateVarObj.adjustArrayToNewArraySize = async function () {
-                // console.log(`adjust array ${stateVariable} of ${component.componentIdx} to new array size: ${stateVarObj.arraySize[0]}`);
-                let arraySize = await stateVarObj.arraySize;
-                stateVarObj.arrayValues.length = arraySize[0];
-            };
-        }
-
-        if (!stateVarObj.getArrayKeysFromVarName) {
-            stateVarObj.getArrayKeysFromVarName =
-                returnDefaultGetArrayKeysFromVarName(stateVarObj.numDimensions);
-        }
-
-        // converting from index to key is the same for single and multiple
-        // dimensions, as we just want the string representation
-        stateVarObj.indexToKey = (index) => String(index);
-
-        if (!stateVarObj.returnEntryDimensions) {
-            stateVarObj.returnEntryDimensions = () => 0;
-        }
-
-        if (stateVarObj.shadowingInstructions) {
-            // returnWrappingComponents is a function that returns the wrapping components for
-            // - the whole array (if called with no arguments), or
-            // - an array entry (if called with an array entry prefix as the argument)
-            // It returns wrappingComponents, which is an array of arrays.
-            // Each inner array corresponds to a dimension of the array,
-            // starting with the inner dimension,
-            // so that wrappingComponents[numDimensions-1], if it exists,
-            // corresponds to the wrapping of the entire array (or array entry),
-            // leading to the return of a single component.
-            // Each element of the inner array indicates a wrapping of the corresponding dimension,
-            // and they are applied in reverse order.
-            // Each element can be either:
-            // - a string corresponding to the component type used to wrap
-            // - an object with fields:
-            //   - componentType: a string corresponding to the component type used to wrap
-            //   - isAttributeNamed: a string giving the name of the attribute that this
-            //     wrapping component should be for the wrapping component immediately preceding
-            //     (no effect if isAttributeNamed appears in the first wrapping component)
-            // Unless the subsequent wrapping component has been designated isAttributeNamed,
-            // each wrapping component takes as children either
-            // - the subsequent wrapping component if it exists,
-            // - else the original array components.
-            //
-            // TODO: wrapping components (like most array features) was designed before
-            // we had array indexing such as $a.b[1].
-            // Hence it is based on array entries such as $a.b1, where b is the "prefix".
-            // $a.b[1] has to be converted to something like $a.b1
-            // before calculating wrapping components.
-            // We should rework wrapping components (and other array features)
-            // to make array indexing (maybe even including slices) be the basis.
-
-            if (!stateVarObj.shadowingInstructions.returnWrappingComponents) {
-                stateVarObj.shadowingInstructions.returnWrappingComponents = (
-                    prefix,
-                ) => [];
-            }
-            stateVarObj.wrappingComponents =
-                stateVarObj.shadowingInstructions.returnWrappingComponents();
-        }
-
-        stateVarObj.usedDefaultByArrayKey = {};
-
-        stateVarObj.arrayEntryNames = [];
-        stateVarObj.varNamesIncludingArrayKeys = {};
-
-        let allStateVariablesAffected = [stateVariable];
-        if (stateVarObj.additionalStateVariablesDefined) {
-            allStateVariablesAffected.push(
-                ...stateVarObj.additionalStateVariablesDefined,
-            );
-        }
-
-        // create the definition, etc., functions for the array state variable
-
-        // create returnDependencies function from returnArrayDependenciesByKey
-        stateVarObj.returnDependencies = async function (args) {
-            // console.log(`return dependencies for array ${stateVariable} of ${component.componentIdx}`)
-            // console.log(JSON.parse(JSON.stringify(args)));
-
-            args.arraySize = await stateVarObj.arraySize;
-
-            // delete the internally added dependencies from args.stateValues
-            for (let key in args.stateValues) {
-                if (key.slice(0, 8) === "__array_") {
-                    delete args.stateValues[key];
-                }
-            }
-
-            if (args.arrayKeys === undefined) {
-                args.arrayKeys = stateVarObj.getAllArrayKeys(args.arraySize);
-            }
-
-            // link all dependencyNames of additionalStateVariablesDefined
-            // to the same object, as they will share the same freshnessinfo
-            // TODO: a better idea?  This seems like it could lead to confusion.
-            if (!stateVarObj.dependencyNames) {
-                stateVarObj.dependencyNames = {
-                    namesByKey: {},
-                    keysByName: {},
-                    global: [],
-                };
-                if (stateVarObj.additionalStateVariablesDefined) {
-                    for (let vName of stateVarObj.additionalStateVariablesDefined) {
-                        component.state[vName].dependencyNames =
-                            stateVarObj.dependencyNames;
-                    }
-                }
-            }
-
-            let dependencies = {};
-
-            if (
-                stateVarObj.basedOnArrayKeyStateVariables &&
-                args.arrayKeys.length > 1
-            ) {
-                for (let arrayKey of args.arrayKeys) {
-                    for (let vName of allStateVariablesAffected) {
-                        let sObj = component.state[vName];
-                        dependencies[vName + "_" + arrayKey] = {
-                            dependencyType: "stateVariable",
-                            variableName:
-                                sObj.arrayVarNameFromArrayKey(arrayKey),
-                        };
-                    }
-                }
-            } else {
-                let arrayDependencies =
-                    stateVarObj.returnArrayDependenciesByKey(args);
-
-                if (arrayDependencies.globalDependencies) {
-                    stateVarObj.dependencyNames.global = Object.keys(
-                        arrayDependencies.globalDependencies,
-                    );
-                    Object.assign(
-                        dependencies,
-                        arrayDependencies.globalDependencies,
-                    );
-                }
-
-                if (!arrayDependencies.dependenciesByKey) {
-                    arrayDependencies.dependenciesByKey = {};
-                }
-
-                for (let arrayKey of args.arrayKeys) {
-                    // namesByKey also functions to indicate that dependencies
-                    // have been returned for that arrayKey
-
-                    // If had additional nameByKey, it should be treated as dependencies changing
-                    // so that we recalculate the value of the array variable
-                    // TODO: we are communicating this to updateDependencies by adding
-                    // an attribute to the arguments?  Is there a better way of doing it.
-                    // Didn't want to add to the return value, as that would add complexity
-                    // to how we normally define returnDependencies
-                    // We could change returnDependencies to output an object.
-                    // That would probably be cleaner.
-                    if (!(arrayKey in stateVarObj.dependencyNames.namesByKey)) {
-                        args.changedDependency = true;
-                    }
-                    stateVarObj.dependencyNames.namesByKey[arrayKey] = {};
-                    for (let depName in arrayDependencies.dependenciesByKey[
-                        arrayKey
-                    ]) {
-                        let extendedDepName = "__" + arrayKey + "_" + depName;
-                        dependencies[extendedDepName] =
-                            arrayDependencies.dependenciesByKey[arrayKey][
-                                depName
-                            ];
-                        stateVarObj.dependencyNames.namesByKey[arrayKey][
-                            depName
-                        ] = extendedDepName;
-                        if (
-                            !stateVarObj.dependencyNames.keysByName[
-                                extendedDepName
-                            ]
-                        ) {
-                            stateVarObj.dependencyNames.keysByName[
-                                extendedDepName
-                            ] = [];
-                        }
-                        if (
-                            !stateVarObj.dependencyNames.keysByName[
-                                extendedDepName
-                            ].includes(arrayKey)
-                        ) {
-                            stateVarObj.dependencyNames.keysByName[
-                                extendedDepName
-                            ].push(arrayKey);
-                        }
-                    }
-                }
-
-                // to tie into making sure array size is a dependency, below
-                stateVarObj.dependencyNames.global.push("__array_size");
-            }
-
-            // make sure array size is a dependency
-            dependencies.__array_size = {
-                dependencyType: "stateVariable",
-                variableName: stateVarObj.arraySizeStateVariable,
-            };
-
-            // console.log(`resulting dependencies for ${stateVariable} of ${component.componentIdx}`)
-            // console.log(dependencies)
-            return dependencies;
-        };
-
-        stateVarObj.getCurrentFreshness = function ({
-            freshnessInfo,
-            arrayKeys,
-            arraySize,
-        }) {
-            // console.log(`getCurrentFreshness for array ${stateVariable} of ${component.componentIdx}`)
-            // console.log(arrayKeys, arraySize);
-            // console.log(JSON.parse(JSON.stringify(freshnessInfo)))
-
-            if (arrayKeys === undefined) {
-                arrayKeys = stateVarObj.getAllArrayKeys(arraySize);
-            }
-
-            let freshByKey = freshnessInfo.freshByKey;
-
-            let numberFresh = freshnessInfo.freshArraySize ? 1 : 0;
-            for (let arrayKey of arrayKeys) {
-                if (freshByKey[arrayKey]) {
-                    numberFresh += 1;
-                }
-            }
-
-            if (numberFresh > 0) {
-                if (numberFresh === arrayKeys.length + 1) {
-                    return { fresh: { [stateVariable]: true } };
-                } else {
-                    return { partiallyFresh: { [stateVariable]: numberFresh } };
-                }
-            } else {
-                return { fresh: { [stateVariable]: false } };
-            }
-        };
-
-        stateVarObj.markStale = function ({
-            freshnessInfo,
-            changes,
-            arrayKeys,
-            arraySize,
-        }) {
-            // console.log(`markStale for array ${stateVariable} of ${component.componentIdx}`)
-            // console.log(changes, arrayKeys, arraySize);
-            // console.log(JSON.parse(JSON.stringify(freshnessInfo)))
-
-            let result = {};
-
-            if (arrayKeys === undefined) {
-                arrayKeys = stateVarObj.getAllArrayKeys(arraySize);
-            }
-
-            if (stateVarObj.markStaleByKey) {
-                result = stateVarObj.markStaleByKey({ arrayKeys, changes });
-            }
-
-            let freshByKey = freshnessInfo.freshByKey;
-
-            if (changes.__array_size) {
-                freshnessInfo.freshArraySize = false;
-                // everything is stale
-                freshnessInfo.freshByKey = {};
-                result.fresh = { [stateVariable]: false };
-                return result;
-            }
-
-            if (Object.keys(freshByKey).length === 0) {
-                // everything is stale, except possibly array size
-                // (check for nothing fresh as a shortcut, as mark stale could
-                // be called repeated if size doesn't change, given that it's partially fresh)
-                freshnessInfo.freshByKey = {};
-                if (freshnessInfo.freshArraySize) {
-                    result.partiallyFresh = { [stateVariable]: 1 };
-                    return result;
-                } else {
-                    result.fresh = { [stateVariable]: false };
-                    return result;
-                }
-            }
-
-            for (let changeName in changes) {
-                if (stateVarObj.dependencyNames.global.includes(changeName)) {
-                    // everything is stale, except possible array size
-                    freshnessInfo.freshByKey = {};
-                    if (freshnessInfo.freshArraySize) {
-                        result.partiallyFresh = { [stateVariable]: 1 };
-                        return result;
-                    } else {
-                        result.fresh = { [stateVariable]: false };
-                        return result;
-                    }
-                }
-
-                if (
-                    stateVarObj.basedOnArrayKeyStateVariables &&
-                    arrayKeys.length > 1
-                ) {
-                    delete freshByKey[changeName];
-                } else {
-                    for (let key of stateVarObj.dependencyNames.keysByName[
-                        changeName
-                    ]) {
-                        delete freshByKey[key];
-                    }
-                }
-            }
-
-            // check if the array keys requested are fresh
-            let numberFresh = freshnessInfo.freshArraySize ? 1 : 0;
-            for (let arrayKey of arrayKeys) {
-                if (freshByKey[arrayKey]) {
-                    numberFresh += 1;
-                }
-            }
-
-            // console.log(`ending freshness`)
-            // console.log(JSON.parse(JSON.stringify(freshnessInfo)))
-
-            if (numberFresh > 0) {
-                if (numberFresh === arrayKeys.length + 1) {
-                    result.fresh = { [stateVariable]: true };
-                    return result;
-                } else {
-                    result.partiallyFresh = { [stateVariable]: numberFresh };
-                    return result;
-                }
-            } else {
-                result.fresh = { [stateVariable]: false };
-                return result;
-            }
-        };
-
-        stateVarObj.freshenOnNoChanges = function ({
-            arrayKeys,
-            freshnessInfo,
-            arraySize,
-        }) {
-            // console.log(`freshenOnNoChanges for ${stateVariable} of ${component.componentIdx}`)
-            let freshByKey = freshnessInfo.freshByKey;
-
-            if (arrayKeys === undefined) {
-                arrayKeys = stateVarObj.getAllArrayKeys(arraySize);
-            }
-
-            for (let arrayKey of arrayKeys) {
-                freshByKey[arrayKey] = true;
-            }
-        };
-
-        function extractArrayDependencies(
-            dependencyValues,
-            arrayKeys,
-            usedDefault,
-        ) {
-            // console.log(`extract array dependencies`, dependencyValues, arrayKeys, usedDefault)
-            // console.log(JSON.parse(JSON.stringify(arrayKeys)))
-
-            let globalDependencyValues = {};
-            let globalUsedDefault = {};
-            for (let dependencyName of stateVarObj.dependencyNames.global) {
-                globalDependencyValues[dependencyName] =
-                    dependencyValues[dependencyName];
-                globalUsedDefault[dependencyName] = usedDefault[dependencyName];
-            }
-
-            let dependencyValuesByKey = {};
-            let usedDefaultByKey = {};
-            let foundAllDependencyValuesForKey = {};
-            for (let arrayKey of arrayKeys) {
-                dependencyValuesByKey[arrayKey] = {};
-                usedDefaultByKey[arrayKey] = {};
-                if (arrayKey in stateVarObj.dependencyNames.namesByKey) {
-                    foundAllDependencyValuesForKey[arrayKey] = true;
-                    for (let dependencyName in stateVarObj.dependencyNames
-                        .namesByKey[arrayKey]) {
-                        let extendedDepName =
-                            stateVarObj.dependencyNames.namesByKey[arrayKey][
-                                dependencyName
-                            ];
-                        if (extendedDepName in dependencyValues) {
-                            dependencyValuesByKey[arrayKey][dependencyName] =
-                                dependencyValues[extendedDepName];
-                            usedDefaultByKey[arrayKey][dependencyName] =
-                                usedDefault[extendedDepName];
-                        } else {
-                            foundAllDependencyValuesForKey[arrayKey] = false;
-                        }
-                    }
-                }
-            }
-
-            return {
-                globalDependencyValues,
-                globalUsedDefault,
-                dependencyValuesByKey,
-                usedDefaultByKey,
-                foundAllDependencyValuesForKey,
-            };
-        }
-
-        stateVarObj.definition = function (args) {
-            // console.log(`definition in array ${stateVariable} of ${component.componentIdx}`)
-            // console.log(JSON.parse(JSON.stringify(args)));
-            // console.log(args.arrayKeys)
-            // console.log(args.dependencyValues)
-
-            if (args.arrayKeys === undefined) {
-                args.arrayKeys = stateVarObj.getAllArrayKeys(args.arraySize);
-            }
-
-            if (
-                stateVarObj.basedOnArrayKeyStateVariables &&
-                args.arrayKeys.length > 1
-            ) {
-                // if based on array key state variables and have more than one array key
-                // then must have calculated all the relevant array keys
-                // when retrieving the dependency values
-                // Hence there is nothing to do, as arrayValues has been populated
-                // with all the requisite values
-
-                return {};
-            } else {
-                let extractedDeps = extractArrayDependencies(
-                    args.dependencyValues,
-                    args.arrayKeys,
-                    args.usedDefault,
-                );
-                let globalDependencyValues =
-                    extractedDeps.globalDependencyValues;
-                let globalUsedDefault = extractedDeps.globalUsedDefault;
-                let dependencyValuesByKey = extractedDeps.dependencyValuesByKey;
-                let usedDefaultByKey = extractedDeps.usedDefaultByKey;
-                let foundAllDependencyValuesForKey =
-                    extractedDeps.foundAllDependencyValuesForKey;
-
-                delete args.dependencyValues;
-                args.globalDependencyValues = globalDependencyValues;
-                args.globalUsedDefault = globalUsedDefault;
-                args.dependencyValuesByKey = dependencyValuesByKey;
-                args.usedDefaultByKey = usedDefaultByKey;
-
-                let arrayKeysToRecalculate = [];
-                let freshByKey = args.freshnessInfo.freshByKey;
-                for (let arrayKey of args.arrayKeys) {
-                    // only recalculate if
-                    // - arrayKey isn't fresh, and
-                    // - found all dependency values for array key (i.e., have calculated dependencies for arrayKey)
-                    if (
-                        !freshByKey[arrayKey] &&
-                        foundAllDependencyValuesForKey[arrayKey]
-                    ) {
-                        freshByKey[arrayKey] = true;
-                        arrayKeysToRecalculate.push(arrayKey);
-                    }
-                }
-
-                let result;
-                if (arrayKeysToRecalculate.length === 0) {
-                    // console.log(`nothing to recalculate`)
-                    // console.log(`was going to recalculate`, args.arrayKeys)
-                    // console.log(JSON.parse(JSON.stringify(args.freshnessInfo)))
-                    // console.log(JSON.parse(JSON.stringify(stateVarObj.dependencyNames)))
-                    result = {};
-                } else {
-                    args.arrayKeys = arrayKeysToRecalculate;
-
-                    if (!stateVarObj.arrayDefinitionByKey) {
-                        throw Error(
-                            `For ${stateVariable} of ${component.componentType}, arrayDefinitionByKey must be a function`,
-                        );
-                    }
-
-                    result = stateVarObj.arrayDefinitionByKey(args);
-
-                    // in case definition returns additional array entries,
-                    // mark all array keys received as fresh as well
-                    if (result.setValue && result.setValue[stateVariable]) {
-                        for (let arrayKey in result.setValue[stateVariable]) {
-                            freshByKey[arrayKey] = true;
-                        }
-                    }
-                    if (
-                        result.useEssentialOrDefaultValue &&
-                        result.useEssentialOrDefaultValue[stateVariable]
-                    ) {
-                        for (let arrayKey in result.useEssentialOrDefaultValue[
-                            stateVariable
-                        ]) {
-                            freshByKey[arrayKey] = true;
-                        }
-                    }
-                }
-
-                if (!args.freshnessInfo.freshArraySize) {
-                    if (args.changes.__array_size) {
-                        result.arraySizeChanged = [stateVariable];
-                        if (stateVarObj.additionalStateVariablesDefined) {
-                            for (let varName of stateVarObj.additionalStateVariablesDefined) {
-                                // do we have to check if it is array?
-                                if (component.state[varName].isArray) {
-                                    result.arraySizeChanged.push(varName);
-                                }
-                            }
-                        }
-                    }
-                    args.freshnessInfo.freshArraySize = true;
-                }
-
-                // console.log(`result of array definition of ${stateVariable} of ${component.componentIdx}`)
-                // console.log(JSON.parse(JSON.stringify(result)))
-                // console.log(JSON.parse(JSON.stringify(args.freshnessInfo)))
-                return result;
-            }
-        };
-
-        stateVarObj.inverseDefinition = function (args) {
-            // console.log(`inverse definition args for ${stateVariable}`)
-            // console.log(args)
-
-            if (!stateVarObj.inverseArrayDefinitionByKey) {
-                return { success: false };
-            }
-
-            if (args.arrayKeys === undefined) {
-                args.arrayKeys = stateVarObj.getAllArrayKeys(args.arraySize);
-            }
-
-            if (
-                stateVarObj.basedOnArrayKeyStateVariables &&
-                args.arrayKeys.length > 1
-            ) {
-                let instructions = [];
-
-                for (let vName of allStateVariablesAffected) {
-                    for (let key in args.desiredStateVariableValues[vName]) {
-                        let depName = vName + "_" + key;
-                        if (depName in args.dependencyValues) {
-                            instructions.push({
-                                setDependency: depName,
-                                desiredValue:
-                                    args.desiredStateVariableValues[vName][key],
-                                treatAsInitialChange: args.initialChange,
-                            });
-                        }
-                    }
-                }
-
-                return {
-                    success: true,
-                    instructions,
-                };
-            } else {
-                let extractedDeps = extractArrayDependencies(
-                    args.dependencyValues,
-                    args.arrayKeys,
-                    args.usedDefault,
-                );
-                let globalDependencyValues =
-                    extractedDeps.globalDependencyValues;
-                let globalUsedDefault = extractedDeps.globalUsedDefault;
-                let dependencyValuesByKey = extractedDeps.dependencyValuesByKey;
-                let usedDefaultByKey = extractedDeps.usedDefaultByKey;
-                // let foundAllDependencyValuesForKey = extractedDeps.foundAllDependencyValuesForKey;
-
-                delete args.dependencyValues;
-                args.globalDependencyValues = globalDependencyValues;
-                args.globalUsedDefault = globalUsedDefault;
-                args.dependencyValuesByKey = dependencyValuesByKey;
-                args.usedDefaultByKey = usedDefaultByKey;
-
-                args.dependencyNamesByKey =
-                    stateVarObj.dependencyNames.namesByKey;
-
-                if (!stateVarObj.allowExtraArrayKeysInInverse) {
-                    // by default, inverseArrayDefinitionByKey does not need to be
-                    // programmed defensively against arrayKeys that don't exist
-                    // as they are filtered out here.
-                    // However, if allowExtraArrayKeysInInverse, then we skip this
-                    // filtering to allow the possibility that the array size
-                    // could be changed.
-                    let newDesiredStateVariableValues = {};
-                    for (let vName in args.desiredStateVariableValues) {
-                        newDesiredStateVariableValues[vName] = {};
-                        for (let key in args.desiredStateVariableValues[
-                            vName
-                        ]) {
-                            if (args.arrayKeys.includes(key)) {
-                                newDesiredStateVariableValues[vName][key] =
-                                    args.desiredStateVariableValues[vName][key];
-                            }
-                        }
-                    }
-                    args.desiredStateVariableValues =
-                        newDesiredStateVariableValues;
-                }
-
-                let result = stateVarObj.inverseArrayDefinitionByKey(args);
-                // console.log(`result of inverse definition of array`)
-                // console.log(JSON.parse(JSON.stringify(result)))
-                return result;
-            }
-        };
-
-        await this.createArraySizeStateVariable({
-            stateVarObj,
-            component,
-            stateVariable,
-        });
-
-        stateVarObj.arraySizeStale = true;
-        stateVarObj.previousArraySize = [];
+        return this.childMatcher.deriveChildResultsFromDefiningChildren(args);
+    }
 
-        Object.defineProperty(stateVarObj, "arraySize", {
-            get: function () {
-                return (async () => {
-                    if (
-                        !component.state[stateVarObj.arraySizeStateVariable]
-                            .initiallyResolved
-                    ) {
-                        return [];
-                    }
-                    if (stateVarObj.arraySizeStale) {
-                        await stateVarObj.recalculateArraySizeDependentQuantities();
-                    }
-                    return await component.stateValues[
-                        stateVarObj.arraySizeStateVariable
-                    ];
-                })();
-            },
-        });
+    async matchChildrenToChildGroups(parent) {
+        return this.childMatcher.matchChildrenToChildGroups(parent);
+    }
 
-        stateVarObj.recalculateArraySizeDependentQuantities =
-            async function () {
-                let newArraySize =
-                    await component.stateValues[
-                        stateVarObj.arraySizeStateVariable
-                    ];
-                if (
-                    stateVarObj.previousArraySize.length !==
-                        newArraySize.length ||
-                    stateVarObj.previousArraySize.some(
-                        (v, i) => v != newArraySize[i],
-                    )
-                ) {
-                    stateVarObj.previousArraySize = [...newArraySize];
-                    let varNamesIncluding =
-                        (stateVarObj.varNamesIncludingArrayKeys = {});
-                    for (let entryName of stateVarObj.arrayEntryNames) {
-                        let entryStateVarObj = component.state[entryName];
-                        let arrayKeys = stateVarObj.getArrayKeysFromVarName({
-                            arrayEntryPrefix: entryStateVarObj.entryPrefix,
-                            varEnding: entryStateVarObj.varEnding,
-                            arraySize: newArraySize,
-                            numDimensions: stateVarObj.numDimensions,
-                        });
-                        entryStateVarObj._unflattenedArrayKeys = arrayKeys;
-                        entryStateVarObj._arrayKeys = flattenDeep(arrayKeys);
+    findChildGroup(childType, parentClass) {
+        return this.childMatcher.findChildGroup(childType, parentClass);
+    }
 
-                        // for each arrayKey, add this entry name to the array's list variables
-                        for (let arrayKey of entryStateVarObj._arrayKeys) {
-                            if (!varNamesIncluding[arrayKey]) {
-                                varNamesIncluding[arrayKey] = [];
-                            }
-                            varNamesIncluding[arrayKey].push(entryName);
-                        }
-                    }
-                }
-                stateVarObj.arraySizeStale = false;
-            };
+    findChildGroupNoAdapters(
+        componentType,
+        parentClass,
+        afterAdapters = false,
+    ) {
+        return this.childMatcher.findChildGroupNoAdapters(
+            componentType,
+            parentClass,
+            afterAdapters,
+        );
+    }
 
-        // link all freshnessInfo of additionalStateVariablesDefined
-        // to the same object, as they will share the same freshnessinfo
-        // TODO: a better idea?  This seems like it could lead to confusion.
-        if (!stateVarObj.freshnessInfo) {
-            stateVarObj.freshnessInfo = { freshByKey: {} };
-            if (stateVarObj.additionalStateVariablesDefined) {
-                for (let vName of stateVarObj.additionalStateVariablesDefined) {
-                    if (!component.state[vName]) {
-                        component.state[vName] = {};
-                    }
-                    component.state[vName].freshnessInfo =
-                        stateVarObj.freshnessInfo;
-                }
-            }
-        }
+    async returnActiveChildrenIndicesToRender(component) {
+        return this.childMatcher.returnActiveChildrenIndicesToRender(component);
     }
 
-    async createArraySizeStateVariable({
-        stateVarObj,
-        component,
-        stateVariable,
-    }) {
-        let allStateVariablesAffected = [stateVariable];
-        if (stateVarObj.additionalStateVariablesDefined) {
-            allStateVariablesAffected.push(
-                ...stateVarObj.additionalStateVariablesDefined,
-            );
-        }
-        allStateVariablesAffected.sort();
+    async substituteAdapter(args) {
+        return this.childMatcher.substituteAdapter(args);
+    }
 
-        let arraySizeStateVar =
-            `__array_size_` + allStateVariablesAffected.join("_");
-        stateVarObj.arraySizeStateVariable = arraySizeStateVar;
+    // → resolverAdapter
+    async addReplacementsToResolver(args) {
+        return this.resolverAdapter.addReplacementsToResolver(args);
+    }
 
-        let originalStateVariablesDeterminingDependencies;
-        let originalAdditionalStateVariablesDefined;
+    async determineParentAndIndexResolutionForResolver(args) {
+        return this.resolverAdapter.determineParentAndIndexResolutionForResolver(
+            args,
+        );
+    }
 
-        // Make the array's dependencies depend on the array size state variable
-        if (stateVarObj.stateVariablesDeterminingDependencies) {
-            originalStateVariablesDeterminingDependencies = [
-                ...stateVarObj.stateVariablesDeterminingDependencies,
-            ];
-            stateVarObj.stateVariablesDeterminingDependencies.push(
-                arraySizeStateVar,
-            );
-        } else {
-            stateVarObj.stateVariablesDeterminingDependencies = [
-                arraySizeStateVar,
-            ];
-        }
+    addComponentsToResolver(components, parentIdx) {
+        return this.resolverAdapter.addComponentsToResolver(
+            components,
+            parentIdx,
+        );
+    }
 
-        // If array size state variable has already been created,
-        // either it was created due to being shadowed
-        // or from an additional state variable defined.
-        // If it is shadowing target array size state variable,
-        // make it mark the array's arraySize as stale on markStale
-        if (component.state[arraySizeStateVar]) {
-            if (component.state[arraySizeStateVar].isShadow) {
-                let arraySizeStateVarObj = component.state[arraySizeStateVar];
-                arraySizeStateVarObj.markStale = function () {
-                    for (let varName of allStateVariablesAffected) {
-                        component.state[varName].arraySizeStale = true;
-                    }
-                    return {};
-                };
-            }
-            return;
-        }
+    gatherDiagnosticsAndAssignDoenetMLRange(args) {
+        return this.resolverAdapter.gatherDiagnosticsAndAssignDoenetMLRange(
+            args,
+        );
+    }
 
-        component.state[arraySizeStateVar] = {
-            returnDependencies: stateVarObj.returnArraySizeDependencies,
-            definition({ dependencyValues }) {
-                let arraySize = stateVarObj.returnArraySize({
-                    dependencyValues,
-                });
-                for (let [ind, value] of arraySize.entries()) {
-                    if (!(Number.isInteger(value) && value >= 0)) {
-                        arraySize[ind] = 0;
-                    }
-                }
-                return { setValue: { [arraySizeStateVar]: arraySize } };
-            },
-            markStale() {
-                for (let varName of allStateVariablesAffected) {
-                    component.state[varName].arraySizeStale = true;
-                }
-                return {};
-            },
-        };
+    // → stateVariableDefinitionFactory
+    async createStateVariableDefinitions(args) {
+        return this.stateVariableDefinitionFactory.createStateVariableDefinitions(
+            args,
+        );
+    }
 
-        if (stateVarObj.stateVariablesDeterminingArraySizeDependencies) {
-            component.state[
-                arraySizeStateVar
-            ].stateVariablesDeterminingDependencies =
-                stateVarObj.stateVariablesDeterminingArraySizeDependencies;
-        }
+    createAttributeStateVariableDefinitions(args) {
+        return this.stateVariableDefinitionFactory.createAttributeStateVariableDefinitions(
+            args,
+        );
+    }
 
-        await this.initializeStateVariable({
-            component,
-            stateVariable: arraySizeStateVar,
-        });
+    createAdapterStateVariableDefinitions(args) {
+        return this.stateVariableDefinitionFactory.createAdapterStateVariableDefinitions(
+            args,
+        );
     }
 
-    // arrayEntryNamesFromPropIndex is essentially a wrapper around
-    // stateVarObj.arrayVarNameFromPropIndex.
-    // (See above description of arrayVarNameFromPropIndex for technical debt commentary.)
-    // It calls arrayVarNameFromPropIndex on each of an array of stateVariables,
-    // first creating any missing array entry state variables,
-    // logs diagnostics,
-    // and returns an array of the resulting state variables.
-    async arrayEntryNamesFromPropIndex({
-        stateVariables,
-        component,
-        propIndex,
-    }) {
-        let newVarNames = [];
-        for (let varName of stateVariables) {
-            let stateVarObj = component.state[varName];
-            if (!stateVarObj) {
-                if (
-                    !this.checkIfArrayEntry({
-                        stateVariable: varName,
-                        component,
-                    }).isArrayEntry
-                ) {
-                    // varName doesn't exist.  Ignore error here
-                    newVarNames.push(varName);
-                    continue;
-                }
-                await this.createFromArrayEntry({
-                    stateVariable: varName,
-                    component,
-                });
-                stateVarObj = component.state[varName];
-            }
+    async createReferenceShadowStateVariableDefinitions(args) {
+        return this.stateVariableDefinitionFactory.createReferenceShadowStateVariableDefinitions(
+            args,
+        );
+    }
 
-            let newName;
-            if (stateVarObj.isArray) {
-                newName = stateVarObj.arrayVarNameFromPropIndex(
-                    propIndex,
-                    varName,
-                );
-            } else if (stateVarObj.isArrayEntry) {
-                let arrayStateVarObj =
-                    component.state[stateVarObj.arrayStateVariable];
-                newName = arrayStateVarObj.arrayVarNameFromPropIndex(
-                    propIndex,
-                    varName,
-                );
-            } else {
-                this.addDiagnostic({
-                    type: "warning",
-                    message: `Cannot get propIndex from ${varName} of ${component.componentIdx} as it is not an array or array entry state variable`,
-                    position: component.position,
-                    sourceDoc: component.sourceDoc,
-                });
-                newName = varName;
-            }
-            if (newName) {
-                newVarNames.push(newName);
-            } else {
-                this.addDiagnostic({
-                    type: "warning",
-                    message: `Cannot get propIndex from ${varName} of ${component.componentIdx}`,
-                    position: component.position,
-                    sourceDoc: component.sourceDoc,
-                });
-                newVarNames.push(varName);
-            }
-        }
+    modifyStateDefsToBeShadows(args) {
+        return this.stateVariableDefinitionFactory.modifyStateDefsToBeShadows(
+            args,
+        );
+    }
 
-        return newVarNames;
+    modifyStateDefToDeleteVariableReferences(args) {
+        return this.stateVariableDefinitionFactory.modifyStateDefToDeleteVariableReferences(
+            args,
+        );
     }
 
-    recursivelyReplaceCompositesWithReplacements({
-        replacements,
-        recurseNonStandardComposites = false,
-        forceExpandComposites = false,
-        includeWithheldReplacements = false,
-        stopIfHaveProp,
-    }) {
-        let compositesFound = [];
-        let newReplacements = [];
-        let unexpandedCompositesReady = [];
-        let unexpandedCompositesNotReady = [];
+    // → stateVariableInitializer
+    async initializeComponentStateVariables(component) {
+        return this.stateVariableInitializer.initializeComponentStateVariables(
+            component,
+        );
+    }
 
-        for (let replacement of replacements) {
-            if (
-                this.componentInfoObjects.isCompositeComponent({
-                    componentType: replacement.componentType,
-                    includeNonStandard: recurseNonStandardComposites,
-                })
-            ) {
-                if (stopIfHaveProp) {
-                    const checkForPublic = this.matchPublicStateVariables({
-                        stateVariables: [stopIfHaveProp],
-                        componentClass: replacement.constructor,
-                    })[0];
+    async initializeStateVariable(args) {
+        return this.stateVariableInitializer.initializeStateVariable(args);
+    }
 
-                    if (!checkForPublic.startsWith("__not_public_")) {
-                        // The composite has a public state variable that matches `stopIfHaveProp`.
-                        // Therefore, we don't recurse to its replacements but treat the composite itself as the replacement
-                        newReplacements.push(replacement);
-                        continue;
-                    }
-                }
+    async initializeArrayEntryStateVariable(args) {
+        return this.stateVariableInitializer.initializeArrayEntryStateVariable(
+            args,
+        );
+    }
 
-                compositesFound.push(replacement.componentIdx);
+    async initializeArrayStateVariable(args) {
+        return this.stateVariableInitializer.initializeArrayStateVariable(args);
+    }
 
-                if (!replacement.isExpanded) {
-                    if (
-                        replacement.state.readyToExpandWhenResolved.isResolved
-                    ) {
-                        unexpandedCompositesReady.push(
-                            replacement.componentIdx,
-                        );
-                    } else {
-                        unexpandedCompositesNotReady.push(
-                            replacement.componentIdx,
-                        );
-                    }
-                }
+    async createArraySizeStateVariable(args) {
+        return this.stateVariableInitializer.createArraySizeStateVariable(args);
+    }
 
-                if (replacement.isExpanded) {
-                    let replacementReplacements = replacement.replacements;
-                    if (
-                        !includeWithheldReplacements &&
-                        replacement.replacementsToWithhold > 0
-                    ) {
-                        replacementReplacements = replacementReplacements.slice(
-                            0,
-                            -replacement.replacementsToWithhold,
-                        );
-                    }
-                    let recursionResult =
-                        this.recursivelyReplaceCompositesWithReplacements({
-                            replacements: replacementReplacements,
-                            recurseNonStandardComposites,
-                            forceExpandComposites,
-                            includeWithheldReplacements,
-                            stopIfHaveProp,
-                        });
-                    compositesFound.push(...recursionResult.compositesFound);
-                    newReplacements.push(...recursionResult.newReplacements);
-                    unexpandedCompositesReady.push(
-                        ...recursionResult.unexpandedCompositesReady,
-                    );
-                    unexpandedCompositesNotReady.push(
-                        ...recursionResult.unexpandedCompositesNotReady,
-                    );
-                } else {
-                    newReplacements.push(replacement);
-                }
-            } else {
-                newReplacements.push(replacement);
-            }
-        }
+    async arrayEntryNamesFromPropIndex(args) {
+        return this.stateVariableInitializer.arrayEntryNamesFromPropIndex(args);
+    }
 
-        return {
-            compositesFound,
-            newReplacements,
-            unexpandedCompositesReady,
-            unexpandedCompositesNotReady,
-        };
+    recursivelyReplaceCompositesWithReplacements(args) {
+        return this.stateVariableInitializer.recursivelyReplaceCompositesWithReplacements(
+            args,
+        );
     }
 
     async getStateVariableValue({ component, stateVariable }) {
@@ -7799,116 +2773,6 @@ export default class Core {
      * Create and insert `_error` siblings requested by state-variable definitions
      * during initial document construction.
      */
-    async addQueuedErrorComponentsFromStateVariables() {
-        if (!this.errorComponentsToAdd?.length) {
-            return;
-        }
-
-        const errorComponentsToAdd = this.errorComponentsToAdd;
-        this.errorComponentsToAdd = [];
-
-        const numberInsertedAfterSource = {};
-
-        for (let errorInfo of errorComponentsToAdd) {
-            let sourceComponent = this._components[errorInfo.componentIdx];
-            let parent;
-
-            while (sourceComponent?.parentIdx > 0) {
-                const candidateParent =
-                    this._components[sourceComponent.parentIdx];
-
-                if (!candidateParent) {
-                    break;
-                }
-
-                if (candidateParent.constructor.canDisplayChildErrors) {
-                    parent = candidateParent;
-                    break;
-                }
-
-                sourceComponent = candidateParent;
-            }
-
-            if (!parent) {
-                if (this.document?.constructor.canDisplayChildErrors) {
-                    parent = this.document;
-                }
-            }
-
-            if (!parent) {
-                continue;
-            }
-
-            let indexOfDefiningChildren = parent.definingChildren.length;
-
-            if (sourceComponent?.parentIdx === parent.componentIdx) {
-                const sourceInd = parent.definingChildren.findIndex(
-                    (child) =>
-                        typeof child === "object" &&
-                        child.componentIdx === sourceComponent.componentIdx,
-                );
-
-                if (sourceInd !== -1) {
-                    const numberAlreadyInserted =
-                        numberInsertedAfterSource[
-                            sourceComponent.componentIdx
-                        ] ?? 0;
-                    indexOfDefiningChildren =
-                        sourceInd + 1 + numberAlreadyInserted;
-                    numberInsertedAfterSource[sourceComponent.componentIdx] =
-                        numberAlreadyInserted + 1;
-                }
-            }
-
-            let serializedErrorComponents = [
-                {
-                    type: "serialized",
-                    componentType: "_error",
-                    componentIdx: this._components.length,
-                    state: { message: errorInfo.message },
-                    position: errorInfo.position,
-                    sourceDoc: errorInfo.sourceDoc,
-                    children: [],
-                    attributes: {},
-                    doenetAttributes: {},
-                },
-            ];
-
-            this._components[this._components.length] = undefined;
-
-            let ancestors = [
-                {
-                    componentIdx: parent.componentIdx,
-                    componentClass: parent.constructor,
-                },
-                ...parent.ancestors,
-            ];
-
-            this.parameterStack.push(parent.sharedParameters, false);
-            let createResult;
-            try {
-                createResult = await this.createIsolatedComponents({
-                    serializedComponents: serializedErrorComponents,
-                    ancestors,
-                });
-            } finally {
-                this.parameterStack.pop();
-            }
-
-            let addResults = await this.addChildrenAndRecurseToShadows({
-                parent,
-                indexOfDefiningChildren,
-                newChildren: createResult.components,
-            });
-
-            if (!addResults.success) {
-                throw Error(
-                    "Couldn't add error component from state variable evaluation.",
-                );
-            }
-        }
-    }
-
     async processNewDefiningChildren(args) {
         return this.componentLifecycle.processNewDefiningChildren(args);
     }
@@ -11097,59 +5961,6 @@ export default class Core {
     }
 }
 
-function validateAttributeValue({ value, attributeSpecification, attribute }) {
-    let diagnostics = [];
-
-    const valueOrig = value;
-
-    if (
-        attributeSpecification.transformNonFiniteTo !== undefined &&
-        !Number.isFinite(value)
-    ) {
-        value = attributeSpecification.transformNonFiniteTo;
-    }
-
-    if (attributeSpecification.toLowerCase) {
-        value = value.toLowerCase();
-    }
-
-    // `validValues` implies `trim` so that extra spaces don't break the matches
-    if (attributeSpecification.trim || attributeSpecification.validValues) {
-        value = value.trim();
-    }
-
-    if (attributeSpecification.validValues) {
-        if (!attributeSpecification.validValues.includes(value)) {
-            let defaultValue = attributeSpecification.defaultValue;
-            if (defaultValue === undefined) {
-                if (attributeSpecification.createPrimitiveOfType) {
-                    defaultValue = attributeSpecification.defaultPrimitiveValue;
-                }
-                if (defaultValue === undefined) {
-                    throw Error(
-                        "Invalid attribute specification: no default value specified",
-                    );
-                }
-            }
-            diagnostics.push({
-                message: `Invalid value \`${valueOrig}\` for attribute \`${attribute}\`, using value \`${defaultValue}\``,
-                type: "info",
-            });
-            value = defaultValue;
-        }
-    } else if (attributeSpecification.clamp) {
-        if (value < attributeSpecification.clamp[0]) {
-            value = attributeSpecification.clamp[0];
-        } else if (value > attributeSpecification.clamp[1]) {
-            value = attributeSpecification.clamp[1];
-        } else if (!Number.isFinite(value)) {
-            value = attributeSpecification.defaultValue;
-        }
-    }
-
-    return { value, diagnostics };
-}
-
 function calculateAllComponentsShadowing(component) {
     let allShadowing = [];
     if (component.shadowedBy) {
diff --git a/packages/doenetml-worker-javascript/src/StateVariableDefinitionFactory.ts b/packages/doenetml-worker-javascript/src/StateVariableDefinitionFactory.ts
new file mode 100644
index 000000000..f9aa17bfa
--- /dev/null
+++ b/packages/doenetml-worker-javascript/src/StateVariableDefinitionFactory.ts
@@ -0,0 +1,1589 @@
+import { preprocessAttributesObject } from "./utils/attributes";
+
+/**
+ * Builds the synchronous state-variable *shape* (the schema-like definition
+ * objects that say what each state variable depends on, how to compute it,
+ * how to invert it, etc.) for a component class.
+ *
+ * Three sources of definitions are merged into one map:
+ *   1. Attribute-derived state variables (one per `createStateVariable` attribute)
+ *   2. The component class's own `returnNormalizedStateVariableDefinitions`
+ *   3. Adapter or reference-shadow overrides, when a component is created as
+ *      an adapter for another component or as a shadow of one
+ *
+ * The runtime side — wiring `getStateVariableValue` getters, resolving
+ * dependencies, materializing array entries — is in `StateVariableInitializer`.
+ *
+ * Holds a back-reference to Core to read `_components`, `componentInfoObjects`,
+ * and `numerics`, and to invoke `checkIfArrayEntry` and `createFromArrayEntry`.
+ * (`arrayVarNameFromArrayKey` is invoked on the per-variable `stateDef`, not
+ * on Core.)
+ */
+export class StateVariableDefinitionFactory {
+    core: any;
+
+    constructor({ core }: { core: any }) {
+        this.core = core;
+    }
+
+    async createStateVariableDefinitions({
+        componentClass,
+        prescribedDependencies,
+        componentIdx,
+    }) {
+        let redefineDependencies;
+
+        if (prescribedDependencies) {
+            for (const idxStr in prescribedDependencies) {
+                const idx = Number(idxStr);
+                let depArray = prescribedDependencies[idx];
+                for (let dep of depArray) {
+                    if (dep.dependencyType === "referenceShadow") {
+                        if (idx === componentIdx) {
+                            throw Error(
+                                `Circular dependency involving ${componentIdx}.`,
+                            );
+                        }
+                        redefineDependencies = {
+                            linkSource: "referenceShadow",
+                            targetIdx: idx,
+                            compositeIdx: dep.compositeIdx,
+                            propVariable: dep.propVariable,
+                            fromImplicitProp: dep.fromImplicitProp,
+                            arrayStateVariable: dep.arrayStateVariable,
+                            arrayKey: dep.arrayKey,
+                            ignorePrimaryStateVariable:
+                                dep.ignorePrimaryStateVariable,
+                            substituteForPrimaryStateVariable:
+                                dep.substituteForPrimaryStateVariable,
+                            firstLevelReplacement: dep.firstLevelReplacement,
+                            additionalStateVariableShadowing:
+                                dep.additionalStateVariableShadowing,
+                        };
+                    } else if (dep.dependencyType === "adapter") {
+                        redefineDependencies = {
+                            linkSource: "adapter",
+                            adapterTargetIdentity: dep.adapterTargetIdentity,
+                            adapterVariable: dep.adapterVariable,
+                            substituteForPrimaryStateVariable:
+                                dep.substituteForPrimaryStateVariable,
+                            stateVariablesToShadow: dep.stateVariablesToShadow,
+                        };
+                    }
+                }
+            }
+        }
+
+        let stateVariableDefinitions = {};
+
+        if (!redefineDependencies) {
+            this.createAttributeStateVariableDefinitions({
+                stateVariableDefinitions,
+                componentClass,
+            });
+        }
+
+        //  add state variable definitions from component class
+        let newDefinitions =
+            componentClass.returnNormalizedStateVariableDefinitions(
+                this.core.numerics,
+            );
+
+        Object.assign(stateVariableDefinitions, newDefinitions);
+
+        if (redefineDependencies) {
+            if (redefineDependencies.linkSource === "adapter") {
+                this.createAdapterStateVariableDefinitions({
+                    redefineDependencies,
+                    stateVariableDefinitions,
+                    componentClass,
+                });
+            } else {
+                await this.createReferenceShadowStateVariableDefinitions({
+                    redefineDependencies,
+                    stateVariableDefinitions,
+                    componentClass,
+                });
+            }
+        }
+
+        return stateVariableDefinitions;
+    }
+
+    createAttributeStateVariableDefinitions({
+        componentClass,
+        stateVariableDefinitions,
+    }) {
+        let attributes = preprocessAttributesObject(
+            componentClass.createAttributesObject(),
+        );
+
+        for (let attrName in attributes) {
+            let attributeSpecification = attributes[attrName];
+            if (!attributeSpecification.createStateVariable) {
+                continue;
+            }
+
+            let varName = attributeSpecification.createStateVariable;
+
+            let stateVarDef = (stateVariableDefinitions[varName] = {
+                isAttribute: true,
+                hasEssential: true,
+                provideEssentialValuesInDefinition: true,
+            });
+
+            if (attributeSpecification.public) {
+                stateVarDef.public = true;
+                stateVarDef.shadowingInstructions = {};
+                if (attributeSpecification.createPrimitiveOfType) {
+                    stateVarDef.shadowingInstructions.createComponentOfType =
+                        attributeSpecification.createPrimitiveOfType;
+                    if (
+                        stateVarDef.shadowingInstructions
+                            .createComponentOfType === "string"
+                    ) {
+                        stateVarDef.shadowingInstructions.createComponentOfType =
+                            "text";
+                    } else if (
+                        stateVarDef.shadowingInstructions
+                            .createComponentOfType === "stringArray"
+                    ) {
+                        stateVarDef.shadowingInstructions.createComponentOfType =
+                            "textList";
+                    } else if (
+                        stateVarDef.shadowingInstructions
+                            .createComponentOfType === "numberArray"
+                    ) {
+                        stateVarDef.shadowingInstructions.createComponentOfType =
+                            "numberList";
+                    }
+                } else if (attributeSpecification.createReferences) {
+                    throw Error(
+                        "Cannot make a public state variable from an attribute with createReferences",
+                    );
+                } else {
+                    stateVarDef.shadowingInstructions.createComponentOfType =
+                        attributeSpecification.createComponentOfType;
+                }
+            }
+
+            let stateVariableForAttributeValue;
+
+            if (attributeSpecification.createComponentOfType) {
+                let attributeClass =
+                    this.core.componentInfoObjects.allComponentClasses[
+                        attributeSpecification.createComponentOfType
+                    ];
+                if (!attributeClass) {
+                    throw Error(
+                        `Component type ${attributeSpecification.createComponentOfType} does not exist so cannot create state variable for attribute ${attrName} of componentType ${componentClass.componentType}.`,
+                    );
+                }
+
+                stateVariableForAttributeValue =
+                    attributeSpecification.componentStateVariableForAttributeValue;
+                if (stateVariableForAttributeValue === undefined) {
+                    stateVariableForAttributeValue =
+                        attributeClass.stateVariableToBeShadowed;
+                    if (stateVariableForAttributeValue === undefined) {
+                        stateVariableForAttributeValue = "value";
+                    }
+                }
+            }
+
+            stateVarDef.returnDependencies = function () {
+                let dependencies = {};
+                if (attributeSpecification.fallBackToParentStateVariable) {
+                    dependencies.parentValue = {
+                        dependencyType: "parentStateVariable",
+                        variableName:
+                            attributeSpecification.fallBackToParentStateVariable,
+                    };
+                }
+                if (
+                    attributeSpecification.fallBackToSourceCompositeStateVariable
+                ) {
+                    dependencies.sourceCompositeValue = {
+                        dependencyType: "sourceCompositeStateVariable",
+                        variableName:
+                            attributeSpecification.fallBackToSourceCompositeStateVariable,
+                    };
+                }
+                if (attributeSpecification.createPrimitiveOfType) {
+                    dependencies.attributePrimitive = {
+                        dependencyType: "attributePrimitive",
+                        attributeName: attrName,
+                    };
+                } else if (attributeSpecification.createReferences) {
+                    dependencies.attributeRefResolutions = {
+                        dependencyType: "attributeRefResolutions",
+                        attributeName: attrName,
+                    };
+                } else {
+                    dependencies.attributeComponent = {
+                        dependencyType: "attributeComponent",
+                        attributeName: attrName,
+                        variableNames: [stateVariableForAttributeValue],
+                    };
+                }
+
+                return dependencies;
+            };
+
+            stateVarDef.definition = function ({
+                dependencyValues,
+                usedDefault,
+                essentialValues,
+            }) {
+                let attributeValue;
+                if (dependencyValues.attributeComponent) {
+                    attributeValue =
+                        dependencyValues.attributeComponent.stateValues[
+                            stateVariableForAttributeValue
+                        ];
+                } else if (dependencyValues.attributePrimitive != null) {
+                    attributeValue = dependencyValues.attributePrimitive;
+                } else if (
+                    dependencyValues.attributeRefResolutions != null &&
+                    !usedDefault.attributeRefResolutions
+                ) {
+                    attributeValue = dependencyValues.attributeRefResolutions;
+                } else {
+                    // parentValue would be undefined if fallBackToParentStateVariable wasn't specified
+                    // parentValue would be null if the parentValue state variables
+                    // did not exist or its value was null
+                    let haveParentValue = dependencyValues.parentValue != null;
+                    if (
+                        haveParentValue &&
+                        !usedDefault.parentValue &&
+                        essentialValues[varName] === undefined
+                    ) {
+                        return {
+                            setValue: {
+                                [varName]: dependencyValues.parentValue,
+                            },
+                            checkForActualChange: { [varName]: true },
+                        };
+                    } else {
+                        // sourceCompositeValue would be undefined if fallBackToSourceCompositeStateVariable wasn't specified
+                        // sourceCompositeValue would be null if the sourceCompositeValue state variables
+                        // did not exist or its value was null
+
+                        let haveSourceCompositeValue =
+                            dependencyValues.sourceCompositeValue != null;
+                        if (
+                            haveSourceCompositeValue &&
+                            !usedDefault.sourceCompositeValue &&
+                            essentialValues[varName] === undefined
+                        ) {
+                            return {
+                                setValue: {
+                                    [varName]:
+                                        dependencyValues.sourceCompositeValue,
+                                },
+                                checkForActualChange: { [varName]: true },
+                            };
+                        } else {
+                            return {
+                                useEssentialOrDefaultValue: {
+                                    [varName]: true,
+                                },
+                                checkForActualChange: { [varName]: true },
+                            };
+                        }
+                    }
+                }
+
+                let res = validateAttributeValue({
+                    value: attributeValue,
+                    attributeSpecification,
+                    attribute: attrName,
+                });
+
+                return {
+                    setValue: { [varName]: res.value },
+                    checkForActualChange: { [varName]: true },
+                    sendDiagnostics: res.diagnostics,
+                };
+            };
+
+            if (!attributeSpecification.noInverse) {
+                stateVarDef.inverseDefinition = async function ({
+                    desiredStateVariableValues,
+                    dependencyValues,
+                    usedDefault,
+                    essentialValues,
+                }) {
+                    if (!dependencyValues.attributeComponent) {
+                        if (dependencyValues.attributePrimitive != null) {
+                            // can't invert if have primitive
+                            return { success: false };
+                        }
+                        if (dependencyValues.attributeRefResolutions != null) {
+                            // can't invert if have attribute ref resolutions
+                            return { success: false };
+                        }
+
+                        let haveParentValue =
+                            dependencyValues.parentValue != null;
+                        if (
+                            haveParentValue &&
+                            !usedDefault.parentValue &&
+                            essentialValues[varName] === undefined
+                        ) {
+                            // value from parent was used, so propagate back to parent
+                            return {
+                                success: true,
+                                instructions: [
+                                    {
+                                        setDependency: "parentValue",
+                                        desiredValue:
+                                            desiredStateVariableValues[varName],
+                                    },
+                                ],
+                            };
+                        } else {
+                            let haveSourceCompositeValue =
+                                dependencyValues.sourceCompositeValue != null;
+                            if (
+                                haveSourceCompositeValue &&
+                                !usedDefault.sourceCompositeValue &&
+                                essentialValues[varName] === undefined
+                            ) {
+                                // value from source composite was used, so propagate back to source composite
+                                return {
+                                    success: true,
+                                    instructions: [
+                                        {
+                                            setDependency:
+                                                "sourceCompositeValue",
+                                            desiredValue:
+                                                desiredStateVariableValues[
+                                                    varName
+                                                ],
+                                        },
+                                    ],
+                                };
+                            } else {
+                                // no component or primitive, so value is essential and give it the desired value, but validated
+
+                                let res = validateAttributeValue({
+                                    value: desiredStateVariableValues[varName],
+                                    attributeSpecification,
+                                    attribute: attrName,
+                                });
+
+                                return {
+                                    success: true,
+                                    instructions: [
+                                        {
+                                            setEssentialValue: varName,
+                                            value: res.value,
+                                        },
+                                    ],
+                                    sendDiagnostics: res.diagnostics,
+                                };
+                            }
+                        }
+                    }
+
+                    // attribute based on component
+
+                    return {
+                        success: true,
+                        instructions: [
+                            {
+                                setDependency: "attributeComponent",
+                                desiredValue:
+                                    desiredStateVariableValues[varName],
+                                variableIndex: 0,
+                            },
+                        ],
+                    };
+                };
+            }
+
+            let attributesToCopy = [
+                "forRenderer",
+                "defaultValue",
+                "propagateToProps",
+                "triggerActionOnChange",
+                "ignoreFixed",
+                "isLocation",
+                "essentialVarName",
+            ];
+
+            for (let attrName2 of attributesToCopy) {
+                if (attrName2 in attributeSpecification) {
+                    stateVarDef[attrName2] = attributeSpecification[attrName2];
+                }
+            }
+        }
+    }
+
+    createAdapterStateVariableDefinitions({
+        redefineDependencies,
+        stateVariableDefinitions,
+        componentClass,
+    }) {
+        // attributes depend on adapterTarget (if attribute exists in adapterTarget)
+        let adapterTargetComponent =
+            this.core._components[
+                redefineDependencies.adapterTargetIdentity.componentIdx
+            ];
+
+        let attributes = preprocessAttributesObject(
+            componentClass.createAttributesObject(),
+        );
+
+        for (let attrName in attributes) {
+            let attributeSpecification = attributes[attrName];
+            if (!attributeSpecification.createStateVariable) {
+                continue;
+            }
+
+            let varName = attributeSpecification.createStateVariable;
+
+            let stateVarDef = (stateVariableDefinitions[varName] = {
+                isAttribute: true,
+                hasEssential: true,
+            });
+
+            if (attributeSpecification.public) {
+                stateVarDef.public = true;
+                stateVarDef.shadowingInstructions = {};
+                if (attributeSpecification.createPrimitiveOfType) {
+                    stateVarDef.shadowingInstructions.createComponentOfType =
+                        attributeSpecification.createPrimitiveOfType;
+                    if (
+                        stateVarDef.shadowingInstructions
+                            .createComponentOfType === "string"
+                    ) {
+                        stateVarDef.shadowingInstructions.createComponentOfType =
+                            "text";
+                    } else if (
+                        stateVarDef.shadowingInstructions
+                            .createComponentOfType === "stringArray"
+                    ) {
+                        stateVarDef.shadowingInstructions.createComponentOfType =
+                            "textList";
+                    } else if (
+                        stateVarDef.shadowingInstructions
+                            .createComponentOfType === "numberArray"
+                    ) {
+                        stateVarDef.shadowingInstructions.createComponentOfType =
+                            "numberList";
+                    }
+                } else if (attributeSpecification.createReferences) {
+                    throw Error(
+                        "Cannot make a public state variable from an attribute with createReferences",
+                    );
+                } else {
+                    stateVarDef.shadowingInstructions.createComponentOfType =
+                        attributeSpecification.createComponentOfType;
+                }
+            }
+
+            if (varName in adapterTargetComponent.state) {
+                stateVarDef.returnDependencies = () => ({
+                    adapterTargetVariable: {
+                        dependencyType: "stateVariable",
+                        componentIdx:
+                            redefineDependencies.adapterTargetIdentity
+                                .componentIdx,
+                        variableName: varName,
+                    },
+                });
+            } else {
+                stateVarDef.returnDependencies = () => ({});
+            }
+
+            stateVarDef.definition = function ({
+                dependencyValues,
+                usedDefault,
+            }) {
+                if (
+                    dependencyValues.adapterTargetVariable === undefined ||
+                    usedDefault.adapterTargetVariable
+                ) {
+                    return {
+                        useEssentialOrDefaultValue: {
+                            [varName]: true,
+                        },
+                        checkForActualChange: { [varName]: true },
+                    };
+                } else {
+                    return {
+                        setValue: {
+                            [varName]: dependencyValues.adapterTargetVariable,
+                        },
+                        checkForActualChange: { [varName]: true },
+                    };
+                }
+            };
+
+            if (!attributeSpecification.noInverse) {
+                stateVarDef.inverseDefinition = async function ({
+                    desiredStateVariableValues,
+                    dependencyValues,
+                }) {
+                    if (dependencyValues.adapterTargetVariable === undefined) {
+                        return {
+                            success: true,
+                            instructions: [
+                                {
+                                    setEssentialValue: varName,
+                                    value: desiredStateVariableValues[varName],
+                                },
+                            ],
+                        };
+                    } else {
+                        return {
+                            success: true,
+                            instructions: [
+                                {
+                                    setDependency: "adapterTargetVariable",
+                                    desiredValue:
+                                        desiredStateVariableValues[varName],
+                                },
+                            ],
+                        };
+                    }
+                };
+            }
+
+            let attributesToCopy = [
+                "forRenderer",
+                "defaultValue",
+                "propagateToProps",
+                "ignoreFixed",
+                "isLocation",
+                "essentialVarName",
+            ];
+
+            for (let attrName2 of attributesToCopy) {
+                if (attrName2 in attributeSpecification) {
+                    stateVarDef[attrName2] = attributeSpecification[attrName2];
+                }
+            }
+        }
+
+        // primaryStateVariableForDefinition is the state variable that the componentClass
+        // being created has specified should be given the value when it
+        // is created from an outside source like a reference to a prop or an adapter
+        let primaryStateVariableForDefinition = "value";
+        if (redefineDependencies.substituteForPrimaryStateVariable) {
+            primaryStateVariableForDefinition =
+                redefineDependencies.substituteForPrimaryStateVariable;
+        } else if (componentClass.primaryStateVariableForDefinition) {
+            primaryStateVariableForDefinition =
+                componentClass.primaryStateVariableForDefinition;
+        }
+        let stateDef =
+            stateVariableDefinitions[primaryStateVariableForDefinition];
+        stateDef.isShadow = true;
+        stateDef.returnDependencies = () => ({
+            adapterTargetVariable: {
+                dependencyType: "stateVariable",
+                componentIdx:
+                    redefineDependencies.adapterTargetIdentity.componentIdx,
+                variableName: redefineDependencies.adapterVariable,
+            },
+        });
+        if (stateDef.set) {
+            stateDef.definition = function ({ dependencyValues }) {
+                return {
+                    setValue: {
+                        [primaryStateVariableForDefinition]: stateDef.set(
+                            dependencyValues.adapterTargetVariable,
+                        ),
+                    },
+                };
+            };
+        } else {
+            stateDef.definition = function ({ dependencyValues }) {
+                return {
+                    setValue: {
+                        [primaryStateVariableForDefinition]:
+                            dependencyValues.adapterTargetVariable,
+                    },
+                };
+            };
+        }
+        stateDef.inverseDefinition = function ({ desiredStateVariableValues }) {
+            return {
+                success: true,
+                instructions: [
+                    {
+                        setDependency: "adapterTargetVariable",
+                        desiredValue:
+                            desiredStateVariableValues[
+                                primaryStateVariableForDefinition
+                            ],
+                    },
+                ],
+            };
+        };
+
+        if (redefineDependencies.stateVariablesToShadow) {
+            this.modifyStateDefsToBeShadows({
+                stateVariablesToShadow:
+                    redefineDependencies.stateVariablesToShadow,
+                stateVariableDefinitions,
+                targetComponent: adapterTargetComponent,
+            });
+        }
+    }
+
+    async createReferenceShadowStateVariableDefinitions({
+        redefineDependencies,
+        stateVariableDefinitions,
+        componentClass,
+    }) {
+        let targetComponent =
+            this.core._components[redefineDependencies.targetIdx];
+
+        if (redefineDependencies.propVariable) {
+            // if we have an array entry state variable that hasn't been created yet
+            // create it now
+            if (
+                !targetComponent.state[redefineDependencies.propVariable] &&
+                this.core.checkIfArrayEntry({
+                    stateVariable: redefineDependencies.propVariable,
+                    component: targetComponent,
+                }).isArrayEntry
+            ) {
+                await this.core.createFromArrayEntry({
+                    stateVariable: redefineDependencies.propVariable,
+                    component: targetComponent,
+                });
+            }
+        }
+
+        // attributes depend
+        // - first on attributes from component attribute components, if they exist
+        // - then on targetComponent (if not copying a prop and attribute exists in targetComponent)
+
+        let attributes = preprocessAttributesObject(
+            componentClass.createAttributesObject(),
+        );
+
+        for (let attrName in attributes) {
+            let attributeSpecification = attributes[attrName];
+            let varName = attributeSpecification.createStateVariable;
+            if (!varName) {
+                continue;
+            }
+
+            let stateVarDef = (stateVariableDefinitions[varName] = {
+                isAttribute: true,
+                hasEssential: true,
+                provideEssentialValuesInDefinition: true,
+            });
+
+            let attributeFromPrimitive =
+                !attributeSpecification.createComponentOfType;
+
+            if (attributeSpecification.public) {
+                stateVarDef.public = true;
+                stateVarDef.shadowingInstructions = {};
+                if (attributeSpecification.createPrimitiveOfType) {
+                    stateVarDef.shadowingInstructions.createComponentOfType =
+                        attributeSpecification.createPrimitiveOfType;
+                    if (
+                        stateVarDef.shadowingInstructions
+                            .createComponentOfType === "string"
+                    ) {
+                        stateVarDef.shadowingInstructions.createComponentOfType =
+                            "text";
+                    } else if (
+                        stateVarDef.shadowingInstructions
+                            .createComponentOfType === "stringArray"
+                    ) {
+                        stateVarDef.shadowingInstructions.createComponentOfType =
+                            "textList";
+                    } else if (
+                        stateVarDef.shadowingInstructions
+                            .createComponentOfType === "numberArray"
+                    ) {
+                        stateVarDef.shadowingInstructions.createComponentOfType =
+                            "numberList";
+                    }
+                } else if (attributeSpecification.createReferences) {
+                    throw Error(
+                        "Cannot make a public state variable from an attribute with createReferences",
+                    );
+                } else {
+                    stateVarDef.shadowingInstructions.createComponentOfType =
+                        attributeSpecification.createComponentOfType;
+                }
+            }
+
+            let stateVariableForAttributeValue;
+
+            if (attributeSpecification.createComponentOfType) {
+                let attributeClass =
+                    this.core.componentInfoObjects.allComponentClasses[
+                        attributeSpecification.createComponentOfType
+                    ];
+                if (!attributeClass) {
+                    throw Error(
+                        `Component type ${attributeSpecification.createComponentOfType} does not exist so cannot create state variable for attribute ${attrName} of componentType ${componentClass.componentType}.`,
+                    );
+                }
+
+                stateVariableForAttributeValue =
+                    attributeSpecification.componentStateVariableForAttributeValue;
+                if (stateVariableForAttributeValue === undefined) {
+                    stateVariableForAttributeValue =
+                        attributeClass.stateVariableToBeShadowed;
+                    if (stateVariableForAttributeValue === undefined) {
+                        stateVariableForAttributeValue = "value";
+                    }
+                }
+            }
+
+            let thisDependencies = {};
+
+            if (attributeSpecification.createPrimitiveOfType) {
+                thisDependencies.attributePrimitive = {
+                    dependencyType: "attributePrimitive",
+                    attributeName: attrName,
+                };
+            } else if (attributeSpecification.createReferences) {
+                thisDependencies.attributeRefResolutions = {
+                    dependencyType: "attributeRefResolutions",
+                    attributeName: attrName,
+                };
+            } else {
+                thisDependencies.attributeComponent = {
+                    dependencyType: "attributeComponent",
+                    attributeName: attrName,
+                    variableNames: [stateVariableForAttributeValue],
+                };
+            }
+
+            if (attributeSpecification.fallBackToParentStateVariable) {
+                thisDependencies.parentValue = {
+                    dependencyType: "parentStateVariable",
+                    variableName:
+                        attributeSpecification.fallBackToParentStateVariable,
+                };
+            }
+            if (attributeSpecification.fallBackToSourceCompositeStateVariable) {
+                thisDependencies.sourceCompositeValue = {
+                    dependencyType: "sourceCompositeStateVariable",
+                    variableName:
+                        attributeSpecification.fallBackToSourceCompositeStateVariable,
+                };
+            }
+
+            stateVarDef.returnDependencies = () => thisDependencies;
+
+            stateVarDef.definition = function ({
+                dependencyValues,
+                usedDefault,
+                essentialValues,
+            }) {
+                let attributeValue;
+                if (dependencyValues.attributeComponent) {
+                    attributeValue =
+                        dependencyValues.attributeComponent.stateValues[
+                            stateVariableForAttributeValue
+                        ];
+                } else if (dependencyValues.attributePrimitive != null) {
+                    attributeValue = dependencyValues.attributePrimitive;
+                } else if (
+                    dependencyValues.attributeRefResolutions != null &&
+                    !usedDefault.attributeRefResolutions
+                ) {
+                    attributeValue = dependencyValues.attributeRefResolutions;
+                } else {
+                    // parentValue would be undefined if fallBackToParentStateVariable wasn't specified
+                    // parentValue would be null if the parentValue state variables
+                    // did not exist or its value was null
+                    let haveParentValue = dependencyValues.parentValue != null;
+                    if (
+                        haveParentValue &&
+                        !usedDefault.parentValue &&
+                        essentialValues[varName] === undefined
+                    ) {
+                        return {
+                            setValue: {
+                                [varName]: dependencyValues.parentValue,
+                            },
+                            checkForActualChange: { [varName]: true },
+                        };
+                    } else {
+                        // sourceCompositeValue would be undefined if fallBackToSourceCompositeStateVariable wasn't specified
+                        // sourceCompositeValue would be null if the sourceCompositeValue state variables
+                        // did not exist or its value was null
+
+                        let haveSourceCompositeValue =
+                            dependencyValues.sourceCompositeValue != null;
+                        if (
+                            haveSourceCompositeValue &&
+                            !usedDefault.sourceCompositeValue &&
+                            essentialValues[varName] === undefined
+                        ) {
+                            return {
+                                setValue: {
+                                    [varName]:
+                                        dependencyValues.sourceCompositeValue,
+                                },
+                                checkForActualChange: { [varName]: true },
+                            };
+                        } else {
+                            return {
+                                useEssentialOrDefaultValue: {
+                                    [varName]: true,
+                                },
+                                checkForActualChange: { [varName]: true },
+                            };
+                        }
+                    }
+                }
+
+                let res = validateAttributeValue({
+                    value: attributeValue,
+                    attributeSpecification,
+                    attribute: attrName,
+                });
+
+                return {
+                    setValue: { [varName]: res.value },
+                    checkForActualChange: { [varName]: true },
+                    sendDiagnostics: res.diagnostics,
+                };
+            };
+
+            if (!attributeSpecification.noInverse) {
+                stateVarDef.inverseDefinition = async function ({
+                    desiredStateVariableValues,
+                    dependencyValues,
+                    usedDefault,
+                    essentialValues,
+                    stateValues,
+                    workspace,
+                }) {
+                    if (!dependencyValues.attributeComponent) {
+                        if (dependencyValues.attributePrimitive != null) {
+                            // can't invert if have primitive
+                            return { success: false };
+                        }
+                        if (dependencyValues.attributeRefResolutions != null) {
+                            // can't invert if have attribute ref resolutions
+                            return { success: false };
+                        }
+
+                        let haveParentValue =
+                            dependencyValues.parentValue != null;
+                        if (
+                            haveParentValue &&
+                            !usedDefault.parentValue &&
+                            essentialValues[varName] === undefined
+                        ) {
+                            // value from parent was used, so propagate back to parent
+                            return {
+                                success: true,
+                                instructions: [
+                                    {
+                                        setDependency: "parentValue",
+                                        desiredValue:
+                                            desiredStateVariableValues[varName],
+                                    },
+                                ],
+                            };
+                        } else {
+                            let haveSourceCompositeValue =
+                                dependencyValues.sourceCompositeValue != null;
+                            if (
+                                haveSourceCompositeValue &&
+                                !usedDefault.sourceCompositeValue &&
+                                essentialValues[varName] === undefined
+                            ) {
+                                // value from source composite was used, so propagate back to source composite
+                                return {
+                                    success: true,
+                                    instructions: [
+                                        {
+                                            setDependency:
+                                                "sourceCompositeValue",
+                                            desiredValue:
+                                                desiredStateVariableValues[
+                                                    varName
+                                                ],
+                                        },
+                                    ],
+                                };
+                            } else {
+                                // no component or primitive, so value is essential and give it the desired value, but validated
+                                let res = validateAttributeValue({
+                                    value: desiredStateVariableValues[varName],
+                                    attributeSpecification,
+                                    attribute: attrName,
+                                });
+
+                                return {
+                                    success: true,
+                                    instructions: [
+                                        {
+                                            setEssentialValue: varName,
+                                            value: res.value,
+                                        },
+                                    ],
+                                    sendDiagnostics: res.diagnostics,
+                                };
+                            }
+                        }
+                    }
+                    // attribute based on child
+
+                    return {
+                        success: true,
+                        instructions: [
+                            {
+                                setDependency: "attributeComponent",
+                                desiredValue:
+                                    desiredStateVariableValues[varName],
+                                variableIndex: 0,
+                            },
+                        ],
+                    };
+                };
+            }
+
+            let attributesToCopy = [
+                "forRenderer",
+                "defaultValue",
+                "propagateToProps",
+                "ignoreFixed",
+                "isLocation",
+                "essentialVarName",
+            ];
+
+            for (let attrName2 of attributesToCopy) {
+                if (attrName2 in attributeSpecification) {
+                    stateVarDef[attrName2] = attributeSpecification[attrName2];
+                }
+            }
+        }
+
+        if (redefineDependencies.propVariable) {
+            if (!redefineDependencies.ignorePrimaryStateVariable) {
+                // primaryStateVariableForDefinition is the state variable that the componentClass
+                // being created has specified should be given the value when it
+                // is created from an outside source like a reference to a prop or an adapter
+                let primaryStateVariableForDefinition = "value";
+                if (redefineDependencies.substituteForPrimaryStateVariable) {
+                    primaryStateVariableForDefinition =
+                        redefineDependencies.substituteForPrimaryStateVariable;
+                } else if (componentClass.primaryStateVariableForDefinition) {
+                    primaryStateVariableForDefinition =
+                        componentClass.primaryStateVariableForDefinition;
+                }
+                let stateDef =
+                    stateVariableDefinitions[primaryStateVariableForDefinition];
+                if (!stateDef) {
+                    if (
+                        redefineDependencies.substituteForPrimaryStateVariable
+                    ) {
+                        throw Error(
+                            `Invalid public state variable of componentType ${componentClass.componentType}: substituteForPrimaryStateVariable ${redefineDependencies.substituteForPrimaryStateVariable} does not exist`,
+                        );
+                    } else {
+                        throw Error(
+                            `Cannot have a public state variable with componentType ${componentClass.componentType} as the class doesn't have a primary state variable for definition`,
+                        );
+                    }
+                }
+                stateDef.isShadow = true;
+                stateDef.returnDependencies = () => ({
+                    targetVariable: {
+                        dependencyType: "stateVariable",
+                        componentIdx: targetComponent.componentIdx,
+                        variableName: redefineDependencies.propVariable,
+                    },
+                });
+
+                let setDefault = false;
+                if (
+                    targetComponent.state[redefineDependencies.propVariable]
+                        .defaultValue !== undefined
+                ) {
+                    stateDef.defaultValue =
+                        targetComponent.state[
+                            redefineDependencies.propVariable
+                        ].defaultValue;
+                    if (stateDef.set) {
+                        stateDef.defaultValue = stateDef.set(
+                            stateDef.defaultValue,
+                        );
+                    }
+                    stateDef.hasEssential = true;
+                    setDefault = true;
+                }
+
+                let targetVariableIsArray =
+                    targetComponent.state[redefineDependencies.propVariable]
+                        .isArray;
+
+                if (stateDef.set) {
+                    stateDef.definition = function ({
+                        dependencyValues,
+                        usedDefault,
+                    }) {
+                        let targetVariable = dependencyValues.targetVariable;
+                        if (
+                            targetVariable === undefined ||
+                            (targetVariableIsArray &&
+                                targetVariable.length === 0)
+                        ) {
+                            // allow for case where we depend on array entry that does not yet exist
+                            return {
+                                useEssentialOrDefaultValue: {
+                                    [primaryStateVariableForDefinition]: true,
+                                },
+                            };
+                        }
+                        let valueFromTarget = stateDef.set(targetVariable);
+                        if (setDefault && usedDefault.targetVariable) {
+                            return {
+                                useEssentialOrDefaultValue: {
+                                    [primaryStateVariableForDefinition]: {
+                                        defaultValue: valueFromTarget,
+                                    },
+                                },
+                            };
+                        }
+                        return {
+                            setValue: {
+                                [primaryStateVariableForDefinition]:
+                                    valueFromTarget,
+                            },
+                        };
+                    };
+                } else {
+                    stateDef.definition = function ({
+                        dependencyValues,
+                        usedDefault,
+                    }) {
+                        let targetVariable = dependencyValues.targetVariable;
+                        if (
+                            targetVariable === undefined ||
+                            (targetVariableIsArray &&
+                                targetVariable.length === 0)
+                        ) {
+                            // allow for case where we depend on array entry that does not yet exist
+                            return {
+                                useEssentialOrDefaultValue: {
+                                    [primaryStateVariableForDefinition]: true,
+                                },
+                            };
+                        }
+                        if (setDefault && usedDefault.targetVariable) {
+                            return {
+                                useEssentialOrDefaultValue: {
+                                    [primaryStateVariableForDefinition]: {
+                                        defaultValue: targetVariable,
+                                    },
+                                },
+                            };
+                        }
+                        return {
+                            setValue: {
+                                [primaryStateVariableForDefinition]:
+                                    targetVariable,
+                            },
+                        };
+                    };
+                }
+                stateDef.inverseDefinition = function ({
+                    desiredStateVariableValues,
+                }) {
+                    return {
+                        success: true,
+                        instructions: [
+                            {
+                                setDependency: "targetVariable",
+                                desiredValue:
+                                    desiredStateVariableValues[
+                                        primaryStateVariableForDefinition
+                                    ],
+                            },
+                        ],
+                    };
+                };
+            }
+
+            let shadowStandardVariables = false;
+            let stateVariablesToShadow = [];
+            if (targetComponent.constructor.implicitPropReturnsSameType) {
+                if (redefineDependencies.fromImplicitProp) {
+                    shadowStandardVariables = true;
+                }
+
+                // shadow any variables marked as shadowVariable
+                for (let varName in targetComponent.state) {
+                    let stateObj = targetComponent.state[varName];
+                    if (stateObj.shadowVariable || stateObj.isShadow) {
+                        stateVariablesToShadow.push(varName);
+                    }
+                }
+            }
+
+            if (redefineDependencies.additionalStateVariableShadowing) {
+                // since using parallel arrays, start with empty array to match next indices
+                let differentStateVariablesInTarget = Array(
+                    stateVariablesToShadow.length,
+                );
+                for (let varName in redefineDependencies.additionalStateVariableShadowing) {
+                    if (!stateVariablesToShadow.includes(varName)) {
+                        stateVariablesToShadow.push(varName);
+                        differentStateVariablesInTarget.push(
+                            redefineDependencies
+                                .additionalStateVariableShadowing[varName]
+                                .stateVariableToShadow,
+                        );
+                    }
+                }
+
+                this.modifyStateDefsToBeShadows({
+                    stateVariablesToShadow,
+                    stateVariableDefinitions,
+                    targetComponent,
+                    differentStateVariablesInTarget,
+                });
+            } else if (shadowStandardVariables) {
+                this.modifyStateDefsToBeShadows({
+                    stateVariablesToShadow,
+                    stateVariableDefinitions,
+                    targetComponent,
+                });
+            }
+
+            // for referencing a prop variable, don't shadow standard state variables
+            // (unless except for above cases)
+            // so just return now
+            return;
+        }
+
+        let foundReadyToExpandWhenResolved = false;
+        if ("readyToExpandWhenResolved" in stateVariableDefinitions) {
+            // if shadowing a composite
+            // make readyToExpandWhenResolved depend on the same variable
+            // of the targetComponent also being resolved
+
+            foundReadyToExpandWhenResolved = true;
+
+            let stateDef = stateVariableDefinitions.readyToExpandWhenResolved;
+            let originalReturnDependencies =
+                stateDef.returnDependencies.bind(stateDef);
+            let originalDefinition = stateDef.definition;
+
+            stateDef.returnDependencies = function (args) {
+                let dependencies = originalReturnDependencies(args);
+                dependencies.targetReadyToExpandWhenResolved = {
+                    dependencyType: "stateVariable",
+                    componentIdx: targetComponent.componentIdx,
+                    variableName: "readyToExpandWhenResolved",
+                };
+                return dependencies;
+            };
+
+            // change definition so that it is false if targetComponent isn't ready to expand
+            stateDef.definition = function (args) {
+                let result = originalDefinition(args);
+
+                if (
+                    result.setValue &&
+                    result.setValue.readyToExpandWhenResolved
+                ) {
+                    if (
+                        !args.dependencyValues.targetReadyToExpandWhenResolved
+                    ) {
+                        result.setValue.readyToExpandWhenResolved = false;
+                    }
+                }
+                return result;
+            };
+        }
+
+        let stateVariablesToShadow = [];
+
+        // shadow any variables marked as shadowVariable
+        for (let varName in targetComponent.state) {
+            let stateObj = targetComponent.state[varName];
+            if (stateObj.shadowVariable || stateObj.isShadow) {
+                stateVariablesToShadow.push(varName);
+            }
+        }
+
+        this.modifyStateDefsToBeShadows({
+            stateVariablesToShadow,
+            stateVariableDefinitions,
+            foundReadyToExpandWhenResolved,
+            targetComponent,
+        });
+    }
+
+    modifyStateDefsToBeShadows({
+        stateVariablesToShadow,
+        stateVariableDefinitions,
+        foundReadyToExpandWhenResolved,
+        targetComponent,
+        differentStateVariablesInTarget = [],
+    }) {
+        // Note: if add a markStale function to these shadow,
+        // will need to modify array size state variable definition
+        // (createArraySizeStateVariable)
+        // to not overwrite markStale when it finds a shadow
+
+        let deleteStateVariablesFromDefinition = {};
+        for (let [varInd, varName] of stateVariablesToShadow.entries()) {
+            let stateDef = stateVariableDefinitions[varName];
+
+            if (stateDef === undefined) {
+                if (varName.slice(0, 8) === "__array_") {
+                    // have an array variable name that is created on the fly
+                    // rather than being specified in original definition.
+                    stateDef = stateVariableDefinitions[varName] = {};
+                } else {
+                    continue;
+                }
+            }
+
+            stateDef.isShadow = true;
+
+            if (stateDef.additionalStateVariablesDefined) {
+                for (let varName2 of stateDef.additionalStateVariablesDefined) {
+                    if (!stateVariablesToShadow.includes(varName2)) {
+                        // varName2 is not shadowed, however, it includes varName
+                        // in its definition
+                        if (!deleteStateVariablesFromDefinition[varName2]) {
+                            deleteStateVariablesFromDefinition[varName2] = [];
+                        }
+                        deleteStateVariablesFromDefinition[varName2].push(
+                            varName,
+                        );
+                    }
+                }
+            }
+            delete stateDef.additionalStateVariablesDefined;
+            if (!foundReadyToExpandWhenResolved) {
+                // if didn't find a readyToExpandWhenResolved,
+                // then won't use original dependencies so can delete any
+                // stateVariablesDeterminingDependencies
+                delete stateDef.stateVariablesDeterminingDependencies;
+            }
+
+            let copyComponentType =
+                stateDef.public &&
+                stateDef.shadowingInstructions.hasVariableComponentType;
+
+            if (stateDef.isArray) {
+                let overrideVarNameWith =
+                    differentStateVariablesInTarget[varInd];
+
+                stateDef.returnArrayDependenciesByKey = function ({
+                    arrayKeys,
+                }) {
+                    let dependenciesByKey = {};
+
+                    for (let key of arrayKeys) {
+                        dependenciesByKey[key] = {
+                            targetVariable: {
+                                dependencyType: "stateVariable",
+                                componentIdx: targetComponent.componentIdx,
+                                variableName:
+                                    overrideVarNameWith ||
+                                    this.arrayVarNameFromArrayKey(key),
+                            },
+                        };
+                    }
+
+                    let globalDependencies = {};
+
+                    if (copyComponentType) {
+                        globalDependencies.targetVariableComponentType = {
+                            dependencyType: "stateVariableComponentType",
+                            componentIdx: targetComponent.componentIdx,
+                            variableName: varName,
+                        };
+                    }
+
+                    if (stateDef.inverseShadowToSetEntireArray) {
+                        globalDependencies.targetArray = {
+                            dependencyType: "stateVariable",
+                            componentIdx: targetComponent.componentIdx,
+                            variableName: varName,
+                        };
+                    }
+
+                    return { globalDependencies, dependenciesByKey };
+                };
+
+                stateDef.arrayDefinitionByKey = function ({
+                    globalDependencyValues,
+                    dependencyValuesByKey,
+                    arrayKeys,
+                }) {
+                    let newEntries = {};
+
+                    for (let arrayKey of arrayKeys) {
+                        if (
+                            "targetVariable" in dependencyValuesByKey[arrayKey]
+                        ) {
+                            newEntries[arrayKey] =
+                                dependencyValuesByKey[arrayKey].targetVariable;
+                        } else {
+                            // put in a placeholder value until this can be rerun
+                            // with the updated dependencies
+                            newEntries[arrayKey] =
+                                stateDef.defaultValueByArrayKey?.(arrayKey);
+                        }
+                    }
+
+                    let result = {
+                        setValue: { [varName]: newEntries },
+                    };
+
+                    // TODO: how do we make it do this just once?
+                    if (
+                        "targetVariableComponentType" in globalDependencyValues
+                    ) {
+                        result.setCreateComponentOfType = {
+                            [varName]:
+                                globalDependencyValues.targetVariableComponentType,
+                        };
+                    }
+
+                    return result;
+                };
+
+                stateDef.inverseArrayDefinitionByKey = function ({
+                    desiredStateVariableValues,
+                    dependencyValuesByKey,
+                    dependencyNamesByKey,
+                    arraySize,
+                    initialChange,
+                }) {
+                    if (stateDef.inverseShadowToSetEntireArray) {
+                        return {
+                            success: true,
+                            instructions: [
+                                {
+                                    setDependency: "targetArray",
+                                    desiredValue:
+                                        desiredStateVariableValues[varName],
+                                    treatAsInitialChange: initialChange,
+                                },
+                            ],
+                        };
+                    }
+
+                    let instructions = [];
+                    for (let key in desiredStateVariableValues[varName]) {
+                        if (!dependencyValuesByKey[key]) {
+                            continue;
+                        }
+
+                        instructions.push({
+                            setDependency:
+                                dependencyNamesByKey[key].targetVariable,
+                            desiredValue:
+                                desiredStateVariableValues[varName][key],
+                            shadowedVariable: true,
+                        });
+                    }
+                    return {
+                        success: true,
+                        instructions,
+                    };
+                };
+            } else {
+                let returnStartingDependencies = () => ({});
+
+                if (foundReadyToExpandWhenResolved) {
+                    // even though won't use original dependencies
+                    // if found a readyToExpandWhenResolved
+                    // keep original dependencies so that readyToExpandWhenResolved
+                    // won't be resolved until all its dependent variables are resolved
+                    returnStartingDependencies =
+                        stateDef.returnDependencies.bind(stateDef);
+                }
+
+                let varNameInTarget = differentStateVariablesInTarget[varInd];
+                if (!varNameInTarget) {
+                    varNameInTarget = varName;
+                }
+
+                stateDef.returnDependencies = function (args) {
+                    let dependencies = Object.assign(
+                        {},
+                        returnStartingDependencies(args),
+                    );
+
+                    dependencies.targetVariable = {
+                        dependencyType: "stateVariable",
+                        componentIdx: targetComponent.componentIdx,
+                        variableName: varNameInTarget,
+                    };
+                    if (copyComponentType) {
+                        dependencies.targetVariableComponentType = {
+                            dependencyType: "stateVariableComponentType",
+                            componentIdx: targetComponent.componentIdx,
+                            variableName: varNameInTarget,
+                        };
+                    }
+                    return dependencies;
+                };
+                stateDef.definition = function ({
+                    dependencyValues,
+                    usedDefault,
+                }) {
+                    let result = {};
+
+                    // TODO: how do we make it do this just once?
+                    if ("targetVariableComponentType" in dependencyValues) {
+                        result.setCreateComponentOfType = {
+                            [varName]:
+                                dependencyValues.targetVariableComponentType,
+                        };
+                    }
+
+                    if (
+                        usedDefault.targetVariable &&
+                        "defaultValue" in stateDef &&
+                        stateDef.hasEssential
+                    ) {
+                        result.useEssentialOrDefaultValue = {
+                            [varName]: {
+                                defaultValue: dependencyValues.targetVariable,
+                            },
+                        };
+                    } else {
+                        result.setValue = {
+                            [varName]: dependencyValues.targetVariable,
+                        };
+                    }
+
+                    return result;
+                };
+                stateDef.excludeDependencyValuesInInverseDefinition = true;
+                stateDef.inverseDefinition = function ({
+                    desiredStateVariableValues,
+                }) {
+                    return {
+                        success: true,
+                        instructions: [
+                            {
+                                setDependency: "targetVariable",
+                                desiredValue:
+                                    desiredStateVariableValues[varName],
+                                shadowedVariable: true,
+                            },
+                        ],
+                    };
+                };
+            }
+        }
+        for (let varName in deleteStateVariablesFromDefinition) {
+            this.modifyStateDefToDeleteVariableReferences({
+                varNamesToDelete: deleteStateVariablesFromDefinition[varName],
+                stateDef: stateVariableDefinitions[varName],
+            });
+        }
+    }
+
+    modifyStateDefToDeleteVariableReferences({ varNamesToDelete, stateDef }) {
+        // delete variables from additionalStateVariablesDefined
+        for (let varName2 of varNamesToDelete) {
+            let ind =
+                stateDef.additionalStateVariablesDefined.indexOf(varName2);
+            stateDef.additionalStateVariablesDefined.splice(ind, 1);
+        }
+
+        // remove variables from definition
+        let originalDefinition = stateDef.definition;
+        stateDef.definition = function (args) {
+            let results = originalDefinition(args);
+            for (let key in results) {
+                if (Array.isArray(results[key])) {
+                    for (let varName2 of varNamesToDelete) {
+                        let ind = results[key].indexOf(varName2);
+                        if (ind !== -1) {
+                            results[key].splice(ind, 1);
+                        }
+                    }
+                } else {
+                    for (let varName2 of varNamesToDelete) {
+                        delete results[key][varName2];
+                    }
+                }
+            }
+            return results;
+        };
+    }
+}
+
+function validateAttributeValue({
+    value,
+    attributeSpecification,
+    attribute,
+}: {
+    value: any;
+    attributeSpecification: any;
+    attribute: string;
+}): { value: any; diagnostics: any[] } {
+    let diagnostics: any[] = [];
+
+    const valueOrig = value;
+
+    if (
+        attributeSpecification.transformNonFiniteTo !== undefined &&
+        !Number.isFinite(value)
+    ) {
+        value = attributeSpecification.transformNonFiniteTo;
+    }
+
+    if (attributeSpecification.toLowerCase) {
+        value = value.toLowerCase();
+    }
+
+    // `validValues` implies `trim` so that extra spaces don't break the matches
+    if (attributeSpecification.trim || attributeSpecification.validValues) {
+        value = value.trim();
+    }
+
+    if (attributeSpecification.validValues) {
+        if (!attributeSpecification.validValues.includes(value)) {
+            let defaultValue = attributeSpecification.defaultValue;
+            if (defaultValue === undefined) {
+                if (attributeSpecification.createPrimitiveOfType) {
+                    defaultValue = attributeSpecification.defaultPrimitiveValue;
+                }
+                if (defaultValue === undefined) {
+                    throw Error(
+                        "Invalid attribute specification: no default value specified",
+                    );
+                }
+            }
+            diagnostics.push({
+                message: `Invalid value \`${valueOrig}\` for attribute \`${attribute}\`, using value \`${defaultValue}\``,
+                type: "info",
+            });
+            value = defaultValue;
+        }
+    } else if (attributeSpecification.clamp) {
+        if (value < attributeSpecification.clamp[0]) {
+            value = attributeSpecification.clamp[0];
+        } else if (value > attributeSpecification.clamp[1]) {
+            value = attributeSpecification.clamp[1];
+        } else if (!Number.isFinite(value)) {
+            value = attributeSpecification.defaultValue;
+        }
+    }
+
+    return { value, diagnostics };
+}
diff --git a/packages/doenetml-worker-javascript/src/StateVariableInitializer.ts b/packages/doenetml-worker-javascript/src/StateVariableInitializer.ts
new file mode 100644
index 000000000..ecdc97da6
--- /dev/null
+++ b/packages/doenetml-worker-javascript/src/StateVariableInitializer.ts
@@ -0,0 +1,1700 @@
+import { deepClone, flattenDeep } from "@doenet/utils";
+import {
+    returnDefaultArrayVarNameFromPropIndex,
+    returnDefaultGetArrayKeysFromVarName,
+} from "./utils/stateVariables";
+
+/**
+ * Initializes state variables on a freshly-created component: walks the
+ * component's `state` map (definitions produced by
+ * `StateVariableDefinitionFactory`) and wires up each variable's runtime
+ * representation — getters that resolve the value lazily, array entry
+ * materialization, size-tracking variables for arrays, and prop-index-to-
+ * array-key resolution.
+ *
+ * The per-state-variable getter captures `core.getStateVariableValue` once
+ * inside `initializeStateVariable` (~line 59). This works today because
+ * Core's constructor eagerly binds that method (`Core.js:148`), so the
+ * captured reference stays valid for the lifetime of the manager. If a
+ * future phase moves `getStateVariableValue` onto a separate manager, this
+ * capture must become a lazy lookup so the binding source stays live.
+ *
+ * Holds a back-reference to Core to read `_components`,
+ * `componentInfoObjects`, and `stateVariableChangeTriggers`, and to invoke
+ * `getStateVariableValue`, `checkIfArrayEntry`, `matchPublicStateVariables`,
+ * `addDiagnostic`, and `createFromArrayEntry`.
+ */
+export class StateVariableInitializer {
+    core: any;
+
+    constructor({ core }: { core: any }) {
+        this.core = core;
+    }
+
+    async initializeComponentStateVariables(component) {
+        for (let stateVariable in component.state) {
+            if (component.state[stateVariable].isAlias) {
+                if (!component.stateVarAliases) {
+                    component.stateVarAliases = {};
+                }
+                component.stateVarAliases[stateVariable] =
+                    component.state[stateVariable].targetVariableName;
+
+                // TODO: do we want to delete alias from state?
+                delete component.state[stateVariable];
+            } else {
+                await this.initializeStateVariable({
+                    component,
+                    stateVariable,
+                });
+            }
+        }
+    }
+
+    async initializeStateVariable({
+        component,
+        stateVariable,
+        arrayStateVariable,
+        arrayEntryPrefix,
+    }) {
+        let getStateVar = this.core.getStateVariableValue;
+        if (!component.state[stateVariable]) {
+            component.state[stateVariable] = {};
+        }
+        let stateVarObj = component.state[stateVariable];
+        stateVarObj.isResolved = false;
+        Object.defineProperty(stateVarObj, "value", {
+            get: () => getStateVar({ component, stateVariable }),
+            configurable: true,
+        });
+
+        if (arrayEntryPrefix !== undefined) {
+            await this.initializeArrayEntryStateVariable({
+                stateVarObj,
+                arrayStateVariable,
+                arrayEntryPrefix,
+                component,
+                stateVariable,
+            });
+        } else if (stateVarObj.isArray) {
+            await this.initializeArrayStateVariable({
+                stateVarObj,
+                component,
+                stateVariable,
+            });
+        }
+
+        if (stateVarObj.triggerActionOnChange) {
+            let componentTriggers =
+                this.core.stateVariableChangeTriggers[component.componentIdx];
+            if (!componentTriggers) {
+                componentTriggers = this.core.stateVariableChangeTriggers[
+                    component.componentIdx
+                ] = {};
+            }
+            componentTriggers[stateVariable] = {
+                action: stateVarObj.triggerActionOnChange,
+            };
+        }
+    }
+
+    async initializeArrayEntryStateVariable({
+        stateVarObj,
+        arrayStateVariable,
+        arrayEntryPrefix,
+        component,
+        stateVariable,
+    }) {
+        // This function used for initializing array entry variables
+        // (not the original array variable)
+        // It adds many attributes to state variables corresponding to
+        // array entries, including
+        // - arrayStateVariable: the name of the array for which this is an entry
+        // - arrayKeys: an array of the key(s) that constitute this entry
+        // - markStale: function from array state variable
+        // - freshnessInfo: object from array state variable
+        // - getValueFromArrayValues: function used to get this entry's value
+        // - isLocation: array entries are locations if the array state variable is
+        //   (See expanation of location in fixLocation state variable of BaseComponent.js)
+
+        stateVarObj.isArrayEntry = true;
+
+        stateVarObj.arrayStateVariable = arrayStateVariable;
+        let arrayStateVarObj = component.state[arrayStateVariable];
+        stateVarObj.definition = arrayStateVarObj.definition;
+        stateVarObj.inverseDefinition = arrayStateVarObj.inverseDefinition;
+        stateVarObj.markStale = arrayStateVarObj.markStale;
+        stateVarObj.freshnessInfo = arrayStateVarObj.freshnessInfo;
+        stateVarObj.getPreviousDependencyValuesForMarkStale =
+            arrayStateVarObj.getPreviousDependencyValuesForMarkStale;
+        stateVarObj.provideEssentialValuesInDefinition =
+            arrayStateVarObj.provideEssentialValuesInDefinition;
+        stateVarObj.providePreviousValuesInDefinition =
+            arrayStateVarObj.providePreviousValuesInDefinition;
+        stateVarObj.isLocation = arrayStateVarObj.isLocation;
+
+        stateVarObj.numDimensions =
+            arrayStateVarObj.returnEntryDimensions(arrayEntryPrefix);
+        stateVarObj.entryPrefix = arrayEntryPrefix;
+        stateVarObj.varEnding = stateVariable.slice(arrayEntryPrefix.length);
+
+        if (arrayStateVarObj.createWorkspace) {
+            stateVarObj.createWorkspace = true;
+            stateVarObj.workspace = arrayStateVarObj.workspace;
+        }
+
+        if (arrayStateVarObj.basedOnArrayKeyStateVariables) {
+            stateVarObj.basedOnArrayKeyStateVariables = true;
+        }
+
+        // if any of the additional state variables defined are arrays,
+        // (which should be all of them)
+        // transform to their array entry
+        if (arrayStateVarObj.additionalStateVariablesDefined) {
+            stateVarObj.additionalStateVariablesDefined = [];
+
+            let entryPrefixInd =
+                arrayStateVarObj.entryPrefixes.indexOf(arrayEntryPrefix);
+
+            for (let varName of arrayStateVarObj.additionalStateVariablesDefined) {
+                let sObj = component.state[varName];
+
+                if (sObj.isArray) {
+                    // find the same array entry prefix in the other array state variable
+                    let newArrayEntryPrefix =
+                        sObj.entryPrefixes[entryPrefixInd];
+                    let arrayEntryVarName =
+                        newArrayEntryPrefix + stateVarObj.varEnding;
+
+                    stateVarObj.additionalStateVariablesDefined.push(
+                        arrayEntryVarName,
+                    );
+                } else {
+                    stateVarObj.additionalStateVariablesDefined.push(varName);
+                }
+            }
+        }
+
+        if (arrayStateVarObj.shadowingInstructions) {
+            stateVarObj.shadowingInstructions = {};
+
+            // See description of returnWrappingComponents in initializeArrayStateVariable, below.
+            stateVarObj.wrappingComponents =
+                arrayStateVarObj.shadowingInstructions.returnWrappingComponents(
+                    arrayEntryPrefix,
+                );
+
+            if (arrayStateVarObj.shadowingInstructions.attributesToShadow) {
+                stateVarObj.shadowingInstructions.attributesToShadow =
+                    arrayStateVarObj.shadowingInstructions.attributesToShadow;
+            }
+
+            if (arrayStateVarObj.shadowingInstructions.createComponentOfType) {
+                let entryPrefixInd =
+                    arrayStateVarObj.entryPrefixes.indexOf(arrayEntryPrefix);
+                if (
+                    arrayStateVarObj.shadowingInstructions
+                        .createComponentOfType[entryPrefixInd]
+                ) {
+                    stateVarObj.shadowingInstructions.createComponentOfType = [
+                        arrayStateVarObj.shadowingInstructions
+                            .createComponentOfType[entryPrefixInd],
+                    ];
+                }
+            }
+        }
+
+        // Each arrayEntry state variable will have a function getValueFromArrayValue
+        // that will be used to retrieve the actual value of the components
+        // specified by this entry from the whole array stored in arrayValues
+        // Note: getValueFromArrayValues assumes that arrayValues has been populated
+        if (arrayStateVarObj.getEntryValues) {
+            // the function getEntryValues must have been overwritten by the class
+            // so use this function instead
+            stateVarObj.getValueFromArrayValues = async function () {
+                return await arrayStateVarObj.getEntryValues({
+                    varName: stateVariable,
+                });
+            };
+        } else {
+            // getValueFromArrayValues returns an array of the values
+            // that correspond to the arrayKeys of this entry state variable
+            // (returning a scalar instead if it is just a single value)
+            // It uses the function getArrayValue, which gets the values
+            // from arrayValues of the corresponding array state variable
+            stateVarObj.getValueFromArrayValues = async function () {
+                let arrayKeys = await stateVarObj.arrayKeys;
+                if (arrayKeys.length === 0) {
+                    return;
+                }
+                let value = [];
+                for (let arrayKey of arrayKeys) {
+                    value.push(arrayStateVarObj.getArrayValue({ arrayKey }));
+                }
+                if (value.length === 1) {
+                    return value[0];
+                } else {
+                    return value;
+                }
+            };
+        }
+
+        stateVarObj.arraySizeStateVariable =
+            arrayStateVarObj.arraySizeStateVariable;
+
+        stateVarObj._arrayKeys = [];
+        stateVarObj._unflattenedArrayKeys = [];
+
+        Object.defineProperty(stateVarObj, "arrayKeys", {
+            get: function () {
+                return (async () => {
+                    // first evaluate arraySize so _arrayKeys is recalculated
+                    // in case arraySize change
+                    await arrayStateVarObj.arraySize;
+                    return stateVarObj._arrayKeys;
+                })();
+            },
+        });
+
+        Object.defineProperty(stateVarObj, "unflattenedArrayKeys", {
+            get: function () {
+                return (async () => {
+                    // first evaluate arraySize so _unflattenedArrayKeys is recalculated
+                    // in case arraySize change
+                    await arrayStateVarObj.arraySize;
+                    return stateVarObj._unflattenedArrayKeys;
+                })();
+            },
+        });
+
+        if (
+            component.state[stateVarObj.arraySizeStateVariable]
+                .initiallyResolved
+        ) {
+            let arraySize = await arrayStateVarObj.arraySize;
+            let arrayKeys = arrayStateVarObj.getArrayKeysFromVarName({
+                arrayEntryPrefix: stateVarObj.entryPrefix,
+                varEnding: stateVarObj.varEnding,
+                arraySize,
+                numDimensions: arrayStateVarObj.numDimensions,
+            });
+
+            stateVarObj._unflattenedArrayKeys = arrayKeys;
+            stateVarObj._arrayKeys = flattenDeep(arrayKeys);
+
+            // for each arrayKey, add this entry name to the array's list variables
+            let varNamesIncluding = arrayStateVarObj.varNamesIncludingArrayKeys;
+            for (let arrayKey of stateVarObj._arrayKeys) {
+                if (!varNamesIncluding[arrayKey]) {
+                    varNamesIncluding[arrayKey] = [];
+                }
+                varNamesIncluding[arrayKey].push(stateVariable);
+            }
+        }
+
+        arrayStateVarObj.arrayEntryNames.push(stateVariable);
+
+        Object.defineProperty(stateVarObj, "arraySize", {
+            get: () => arrayStateVarObj.arraySize,
+        });
+
+        // TODO: delete since arrayEntrySize isn't currently used?
+        Object.defineProperty(stateVarObj, "arrayEntrySize", {
+            get: function () {
+                return (async () => {
+                    // assume array is rectangular, so just look at first subarray of each dimension
+                    let unflattenedArrayKeys =
+                        await stateVarObj.unflattenedArrayKeys;
+                    let arrayEntrySize = [];
+                    let subArray = [unflattenedArrayKeys];
+                    for (let i = 0; i < stateVarObj.numDimensions; i++) {
+                        subArray = subArray[0];
+                        arrayEntrySize.push(subArray.length);
+                    }
+                    arrayEntrySize.reverse(); // so starts with inner dimension
+                    return arrayEntrySize;
+                })();
+            },
+        });
+
+        if (arrayStateVarObj.stateVariablesDeterminingDependencies) {
+            if (!stateVarObj.stateVariablesDeterminingDependencies) {
+                stateVarObj.stateVariablesDeterminingDependencies = [];
+            }
+
+            for (let varName of arrayStateVarObj.stateVariablesDeterminingDependencies) {
+                if (
+                    !stateVarObj.stateVariablesDeterminingDependencies.includes(
+                        varName,
+                    )
+                ) {
+                    stateVarObj.stateVariablesDeterminingDependencies.push(
+                        varName,
+                    );
+                }
+            }
+        }
+
+        // add a returnDependencies function based on the array returnDependencies
+        let arrayReturnDependencies =
+            arrayStateVarObj.returnDependencies.bind(arrayStateVarObj);
+        stateVarObj.returnDependencies = async function (args) {
+            // add array size to argument of return dependencies
+            args.arraySize = await stateVarObj.arraySize;
+            args.arrayKeys = await stateVarObj.arrayKeys;
+            let dependencies = await arrayReturnDependencies(args);
+
+            // We keep track of how many names were defined when we calculate dependencies
+            // If this number changes, it should be treated as dependencies changing
+            // so that we recalculate the value of the arrayEntry variable
+            // TODO: we are communicating this to updateDependencies by adding
+            // an attribute to the arguments?  Is there a better way of doing it.
+            // Didn't want to add to the return value, as that would add complexity
+            // to how we normally define returnDependencies
+            // We could change returnDependencies to output an object.
+            // That would probably be cleaner.
+            let numNames = Object.keys(
+                arrayStateVarObj.dependencyNames.namesByKey,
+            ).length;
+            if (stateVarObj.numberNamesInPreviousReturnDep !== numNames) {
+                args.changedDependency = true;
+            }
+            stateVarObj.numberNamesInPreviousReturnDep = numNames;
+
+            return dependencies;
+        };
+    }
+
+    async initializeArrayStateVariable({
+        stateVarObj,
+        component,
+        stateVariable,
+    }) {
+        // This function used for initializing original array variables
+        // (not array entry variables)
+
+        // Arrays values are stored in a (possibly-multidimensional) array
+        // called arrayValues.  However, so that core doesn't have to deal
+        // with special cases for multiple dimensions, array values are typically
+        // referenced with an arrayKey, which is a single string that corresponds
+        // to a single entry in the array.
+        // For one dimension, index is an integer and arrayKey is its string representation
+        // For multiple dimensions, index is an array of integers, e.g. [i,j,k]
+        // and arrayKey is its string representation, i.e., "i,j,k"
+
+        // The function adds attributes to array state variables, including
+        // - arrayValues: the array of the current values of the array
+        //   (i.e., based on index rather than arrayKey)
+        //   arrayValues is used rather than value given that value is
+        //   sometimes deleted and replaced by a getter.  arrayValues is
+        //   never deleted, but entries are marked as stale using freshnessInfo
+        // - freshnessInfo: this object can be used to track information about the
+        //   freshness of the array entries or other array features, such as size.
+        //   freshnessInfo is prepopulated with
+        //     - a freshByKey object for tracking by key
+        //     - a freshArraySize for tracking array size
+        //   To take advantage of this object, a component can read and modify
+        //   freshnessInfo (as core will pass it in as an argument) in
+        //   - the state variable's definition function
+        //     (to short circuit calculation of something that is already fresh and/or
+        //     to indicate what is now fresh)
+        //   - the state variable's optional markStale function
+        //     (to indicate what is no longer fresh)
+        // - keyToIndex: maps arrayKey (single string) to (multi-)index
+        // - indexToKey: maps (multi-)index to arrayKey
+        // - setArrayValue: sets value in arrayValues corresponding to arrayKey
+        // - getArrayValue: gets value in arrayValues corresponding to arrayKey
+        // - getArrayKeysFromVarName: returns array of the arrayKeys that correspond
+        //   to a given variable name of an array entry
+        // - arrayVarNameFromArrayKey: returns the variable name of an array entry
+        //   that contains a given array key (if there are many, just return one)
+        //   This variable may not yet be created.
+
+        let core = this.core;
+
+        stateVarObj.arrayValues = [];
+
+        if (stateVarObj.numDimensions === undefined) {
+            stateVarObj.numDimensions = 1;
+        }
+
+        let entryPrefixes = stateVarObj.entryPrefixes;
+
+        if (!entryPrefixes) {
+            entryPrefixes = stateVarObj.entryPrefixes = [stateVariable];
+        }
+
+        if (!component.arrayEntryPrefixes) {
+            component.arrayEntryPrefixes = {};
+        }
+        for (let prefix of entryPrefixes) {
+            component.arrayEntryPrefixes[prefix] = stateVariable;
+        }
+
+        if (stateVarObj.numDimensions > 1) {
+            // for multiple dimensions, have to convert from arrayKey
+            // to multi-index when getting or setting
+            // Note: we don't check that arrayKey has the appropriate number of dimensions
+            // If it has fewer dimensions than numDimensions, it will set the slice
+            // to the given value
+            // (useful, for example, to set entire rows)
+            // If it has more dimensinos than numDimensions, behavior isn't determined
+            // (it should throw an error, assuming the array entries aren't arrays)
+            stateVarObj.keyToIndex = (key) =>
+                key.split(",").map((x) => Number(x));
+            stateVarObj.setArrayValue = function ({
+                value,
+                arrayKey,
+                arraySize,
+                arrayValues = stateVarObj.arrayValues,
+            }) {
+                let index = stateVarObj.keyToIndex(arrayKey);
+                let numDimensionsInArrayKey = index.length;
+                if (!numDimensionsInArrayKey > stateVarObj.numDimensions) {
+                    core.addDiagnostic({
+                        type: "info",
+                        message:
+                            "Cannot set array value.  Number of dimensions is too large.",
+                        position: component.position,
+                        sourceDoc: component.sourceDoc,
+                    });
+                    return { nFailures: 1 };
+                }
+                let arrayValuesDrillDown = arrayValues;
+                let arraySizeDrillDown = arraySize;
+                for (let indComponent of index.slice(0, index.length - 1)) {
+                    if (
+                        indComponent >= 0 &&
+                        indComponent < arraySizeDrillDown[0]
+                    ) {
+                        if (!arrayValuesDrillDown[indComponent]) {
+                            arrayValuesDrillDown[indComponent] = [];
+                        }
+                        arrayValuesDrillDown =
+                            arrayValuesDrillDown[indComponent];
+                        arraySizeDrillDown = arraySizeDrillDown.slice(1);
+                    } else {
+                        core.addDiagnostic({
+                            type: "info",
+                            message: "ignore setting array value out of bounds",
+                            position: component.position,
+                            sourceDoc: component.sourceDoc,
+                        });
+                        return { nFailures: 1 };
+                    }
+                }
+
+                let nFailures = 0;
+
+                if (numDimensionsInArrayKey < stateVarObj.numDimensions) {
+                    // if dimensions from arrayKey is less than number of dimensions
+                    // then attempt to get additional dimensions from
+                    // array indices of value
+
+                    let setArrayValuesPiece = function (
+                        desiredValue,
+                        arrayValuesPiece,
+                        arraySizePiece,
+                    ) {
+                        // try to set value of entries of arrayValuePiece to entries of desiredValue
+                        // given that size of arrayValuesPieces is arraySizePiece
+
+                        if (!Array.isArray(desiredValue)) {
+                            core.addDiagnostic({
+                                type: "info",
+                                message:
+                                    "ignoring array values with insufficient dimensions",
+                                position: component.position,
+                                sourceDoc: component.sourceDoc,
+                            });
+                            return { nFailures: 1 };
+                        }
+
+                        let nFailuresSub = 0;
+
+                        let currentSize = arraySizePiece[0];
+                        if (desiredValue.length > currentSize) {
+                            core.addDiagnostic({
+                                type: "info",
+                                message: "ignoring array values of out bounds",
+                                position: component.position,
+                                sourceDoc: component.sourceDoc,
+                            });
+                            nFailuresSub += desiredValue.length - currentSize;
+                            desiredValue = desiredValue.slice(0, currentSize);
+                        }
+
+                        if (arraySizePiece.length === 1) {
+                            // down to last dimension
+                            for (let [ind, val] of desiredValue.entries()) {
+                                arrayValuesPiece[ind] = val;
+                            }
+                        } else {
+                            for (let [ind, val] of desiredValue.entries()) {
+                                if (!arrayValuesPiece[ind]) {
+                                    arrayValuesPiece = [];
+                                }
+                                let result = setArrayValuesPiece(
+                                    val,
+                                    arrayValuesPiece[ind],
+                                    arraySizePiece[ind],
+                                );
+                                nFailuresSub += result.nFailures;
+                            }
+                        }
+
+                        return { nFailures: nFailuresSub };
+                    };
+
+                    let result = setArrayValuesPiece(
+                        value,
+                        arrayValuesDrillDown,
+                        arraySizeDrillDown,
+                    );
+                    nFailures += result.nFailures;
+                } else {
+                    arrayValuesDrillDown[index[index.length - 1]] = value;
+                }
+
+                return { nFailures };
+            };
+            stateVarObj.getArrayValue = function ({
+                arrayKey,
+                arrayValues = stateVarObj.arrayValues,
+            }) {
+                let index = stateVarObj.keyToIndex(arrayKey);
+                let aVals = arrayValues;
+                for (let indComponent of index.slice(0, index.length - 1)) {
+                    aVals = aVals[indComponent];
+                    if (!aVals) {
+                        return undefined;
+                    }
+                }
+                return aVals[index[index.length - 1]];
+            };
+
+            if (!stateVarObj.getAllArrayKeys) {
+                stateVarObj.getAllArrayKeys = function (
+                    arraySize,
+                    flatten = true,
+                    desiredSize,
+                ) {
+                    function prependToAllKeys(keys, newStuff) {
+                        for (let [ind, key] of keys.entries()) {
+                            if (Array.isArray(key)) {
+                                prependToAllKeys(key, newStuff);
+                            } else {
+                                keys[ind] = newStuff + "," + key;
+                            }
+                        }
+                    }
+
+                    function getAllArrayKeysSub(subArraySize) {
+                        if (subArraySize.length === 1) {
+                            // array of numbers from 0 to subArraySize[0], cast to strings
+                            return Array.from(Array(subArraySize[0]), (_, i) =>
+                                String(i),
+                            );
+                        } else {
+                            let currentSize = subArraySize[0];
+                            let subSubKeys = getAllArrayKeysSub(
+                                subArraySize.slice(1),
+                            );
+                            let subKeys = [];
+                            for (let ind = 0; ind < currentSize; ind++) {
+                                if (flatten) {
+                                    subKeys.push(
+                                        ...subSubKeys.map((x) => ind + "," + x),
+                                    );
+                                } else {
+                                    let newSubSubKeys = deepClone(subSubKeys);
+                                    prependToAllKeys(newSubSubKeys, ind);
+                                    subKeys.push(newSubSubKeys);
+                                }
+                            }
+                            return subKeys;
+                        }
+                    }
+
+                    if (desiredSize) {
+                        if (desiredSize.length === 0) {
+                            return [];
+                        } else {
+                            return getAllArrayKeysSub(desiredSize);
+                        }
+                    } else if (!arraySize || arraySize.length === 0) {
+                        return [];
+                    } else {
+                        return getAllArrayKeysSub(arraySize);
+                    }
+                };
+            }
+
+            if (!stateVarObj.arrayVarNameFromArrayKey) {
+                stateVarObj.arrayVarNameFromArrayKey = function (arrayKey) {
+                    return (
+                        entryPrefixes[0] +
+                        arrayKey
+                            .split(",")
+                            .map((x) => Number(x) + 1)
+                            .join("_")
+                    );
+                };
+            }
+
+            // arrayVarNameFromPropIndex is a function that calculates the name
+            // an array entry state variable that corresponds to the specified propIndex.
+            // It is a consequence of retrofitting the ability to index an array (e.g., $a.b[1])
+            // onto a system that was designed with just array entry variables (e..g, $a.b1).
+            // arrayVarNameFromPropIndex can be specified in the definition of the array state variable.
+            // Since numDimensions > 1 here, the default arrayVarNameFromPropIndex
+            // is to turn $a.b[1][2][3] to $a.p1_2_3,
+            // where "p" is the first entry prefix of the array "b".
+
+            // TODO: if we redesign arrays to be based on indices (or even slices),
+            // then arrayVarNameFromPropIndex will be obsolete.
+            if (!stateVarObj.arrayVarNameFromPropIndex) {
+                stateVarObj.arrayVarNameFromPropIndex =
+                    returnDefaultArrayVarNameFromPropIndex(
+                        stateVarObj.numDimensions,
+                        entryPrefixes[0],
+                    );
+            }
+
+            stateVarObj.adjustArrayToNewArraySize = async function () {
+                function resizeSubArray(subArray, subArraySize) {
+                    subArray.length = subArraySize[0];
+
+                    if (subArraySize.length > 1) {
+                        let subSubArraySize = subArraySize.slice(1);
+                        for (let [ind, subSubArray] of subArray.entries()) {
+                            if (!subSubArray) {
+                                // add in any empty entries
+                                subSubArray = subArray[ind] = [];
+                            }
+                            resizeSubArray(subSubArray, subSubArraySize);
+                        }
+                    }
+                }
+
+                let arraySize = await stateVarObj.arraySize;
+                resizeSubArray(stateVarObj.arrayValues, arraySize);
+            };
+        } else {
+            // have just one dimension
+            stateVarObj.keyToIndex = (key) => Number(key);
+            stateVarObj.setArrayValue = function ({
+                value,
+                arrayKey,
+                arraySize,
+                arrayValues = stateVarObj.arrayValues,
+            }) {
+                let ind = stateVarObj.keyToIndex(arrayKey);
+                if (ind >= 0 && ind < arraySize[0]) {
+                    arrayValues[ind] = value;
+                    return { nFailures: 0 };
+                } else {
+                    core.addDiagnostic({
+                        type: "info",
+                        message: `Ignoring setting array values out of bounds: ${arrayKey} of ${stateVariable}`,
+                        position: component.position,
+                        sourceDoc: component.sourceDoc,
+                    });
+                    return { nFailures: 1 };
+                }
+            };
+            stateVarObj.getArrayValue = function ({
+                arrayKey,
+                arrayValues = stateVarObj.arrayValues,
+            }) {
+                return arrayValues[arrayKey];
+            };
+
+            if (!stateVarObj.getAllArrayKeys) {
+                stateVarObj.getAllArrayKeys = function (
+                    arraySize,
+                    flatten,
+                    desiredSize,
+                ) {
+                    if (desiredSize) {
+                        if (desiredSize.length === 0) {
+                            return [];
+                        } else {
+                            // array of numbers from 0 to desiredSize[0], cast to strings
+                            return Array.from(Array(desiredSize[0]), (_, i) =>
+                                String(i),
+                            );
+                        }
+                    } else if (!arraySize || arraySize.length === 0) {
+                        return [];
+                    } else {
+                        // array of numbers from 0 to arraySize[0], cast to strings
+                        return Array.from(Array(arraySize[0]), (_, i) =>
+                            String(i),
+                        );
+                    }
+                };
+            }
+
+            if (!stateVarObj.arrayVarNameFromArrayKey) {
+                stateVarObj.arrayVarNameFromArrayKey = function (arrayKey) {
+                    return entryPrefixes[0] + String(Number(arrayKey) + 1);
+                };
+            }
+
+            // arrayVarNameFromPropIndex is a function that calculates the name
+            // an array entry state variable that corresponds to the specified propIndex.
+            // It is a consequence of retrofitting the ability to index an array (e.g., $a.b[1])
+            // onto a system that was designed with just array entry variables (e..g, $a.b1).
+            // arrayVarNameFromPropIndex can be specified in the definition of the array state variable.
+            // Since numDimensions = 1 here, the default arrayVarNameFromPropIndex
+            // is to turn $a.b[1] to $a.p1,
+            // where "p" is the first entry prefix of the array "b".
+
+            // TODO: if we redesign arrays to be based on indices (or even slices),
+            // then arrayVarNameFromPropIndex will be obsolete.
+            if (!stateVarObj.arrayVarNameFromPropIndex) {
+                stateVarObj.arrayVarNameFromPropIndex =
+                    returnDefaultArrayVarNameFromPropIndex(1, entryPrefixes[0]);
+            }
+
+            stateVarObj.adjustArrayToNewArraySize = async function () {
+                // console.log(`adjust array ${stateVariable} of ${component.componentIdx} to new array size: ${stateVarObj.arraySize[0]}`);
+                let arraySize = await stateVarObj.arraySize;
+                stateVarObj.arrayValues.length = arraySize[0];
+            };
+        }
+
+        if (!stateVarObj.getArrayKeysFromVarName) {
+            stateVarObj.getArrayKeysFromVarName =
+                returnDefaultGetArrayKeysFromVarName(stateVarObj.numDimensions);
+        }
+
+        // converting from index to key is the same for single and multiple
+        // dimensions, as we just want the string representation
+        stateVarObj.indexToKey = (index) => String(index);
+
+        if (!stateVarObj.returnEntryDimensions) {
+            stateVarObj.returnEntryDimensions = () => 0;
+        }
+
+        if (stateVarObj.shadowingInstructions) {
+            // returnWrappingComponents is a function that returns the wrapping components for
+            // - the whole array (if called with no arguments), or
+            // - an array entry (if called with an array entry prefix as the argument)
+            // It returns wrappingComponents, which is an array of arrays.
+            // Each inner array corresponds to a dimension of the array,
+            // starting with the inner dimension,
+            // so that wrappingComponents[numDimensions-1], if it exists,
+            // corresponds to the wrapping of the entire array (or array entry),
+            // leading to the return of a single component.
+            // Each element of the inner array indicates a wrapping of the corresponding dimension,
+            // and they are applied in reverse order.
+            // Each element can be either:
+            // - a string corresponding to the component type used to wrap
+            // - an object with fields:
+            //   - componentType: a string corresponding to the component type used to wrap
+            //   - isAttributeNamed: a string giving the name of the attribute that this
+            //     wrapping component should be for the wrapping component immediately preceding
+            //     (no effect if isAttributeNamed appears in the first wrapping component)
+            // Unless the subsequent wrapping component has been designated isAttributeNamed,
+            // each wrapping component takes as children either
+            // - the subsequent wrapping component if it exists,
+            // - else the original array components.
+            //
+            // TODO: wrapping components (like most array features) was designed before
+            // we had array indexing such as $a.b[1].
+            // Hence it is based on array entries such as $a.b1, where b is the "prefix".
+            // $a.b[1] has to be converted to something like $a.b1
+            // before calculating wrapping components.
+            // We should rework wrapping components (and other array features)
+            // to make array indexing (maybe even including slices) be the basis.
+
+            if (!stateVarObj.shadowingInstructions.returnWrappingComponents) {
+                stateVarObj.shadowingInstructions.returnWrappingComponents = (
+                    prefix,
+                ) => [];
+            }
+            stateVarObj.wrappingComponents =
+                stateVarObj.shadowingInstructions.returnWrappingComponents();
+        }
+
+        stateVarObj.usedDefaultByArrayKey = {};
+
+        stateVarObj.arrayEntryNames = [];
+        stateVarObj.varNamesIncludingArrayKeys = {};
+
+        let allStateVariablesAffected = [stateVariable];
+        if (stateVarObj.additionalStateVariablesDefined) {
+            allStateVariablesAffected.push(
+                ...stateVarObj.additionalStateVariablesDefined,
+            );
+        }
+
+        // create the definition, etc., functions for the array state variable
+
+        // create returnDependencies function from returnArrayDependenciesByKey
+        stateVarObj.returnDependencies = async function (args) {
+            // console.log(`return dependencies for array ${stateVariable} of ${component.componentIdx}`)
+            // console.log(JSON.parse(JSON.stringify(args)));
+
+            args.arraySize = await stateVarObj.arraySize;
+
+            // delete the internally added dependencies from args.stateValues
+            for (let key in args.stateValues) {
+                if (key.slice(0, 8) === "__array_") {
+                    delete args.stateValues[key];
+                }
+            }
+
+            if (args.arrayKeys === undefined) {
+                args.arrayKeys = stateVarObj.getAllArrayKeys(args.arraySize);
+            }
+
+            // link all dependencyNames of additionalStateVariablesDefined
+            // to the same object, as they will share the same freshnessinfo
+            // TODO: a better idea?  This seems like it could lead to confusion.
+            if (!stateVarObj.dependencyNames) {
+                stateVarObj.dependencyNames = {
+                    namesByKey: {},
+                    keysByName: {},
+                    global: [],
+                };
+                if (stateVarObj.additionalStateVariablesDefined) {
+                    for (let vName of stateVarObj.additionalStateVariablesDefined) {
+                        component.state[vName].dependencyNames =
+                            stateVarObj.dependencyNames;
+                    }
+                }
+            }
+
+            let dependencies = {};
+
+            if (
+                stateVarObj.basedOnArrayKeyStateVariables &&
+                args.arrayKeys.length > 1
+            ) {
+                for (let arrayKey of args.arrayKeys) {
+                    for (let vName of allStateVariablesAffected) {
+                        let sObj = component.state[vName];
+                        dependencies[vName + "_" + arrayKey] = {
+                            dependencyType: "stateVariable",
+                            variableName:
+                                sObj.arrayVarNameFromArrayKey(arrayKey),
+                        };
+                    }
+                }
+            } else {
+                let arrayDependencies =
+                    stateVarObj.returnArrayDependenciesByKey(args);
+
+                if (arrayDependencies.globalDependencies) {
+                    stateVarObj.dependencyNames.global = Object.keys(
+                        arrayDependencies.globalDependencies,
+                    );
+                    Object.assign(
+                        dependencies,
+                        arrayDependencies.globalDependencies,
+                    );
+                }
+
+                if (!arrayDependencies.dependenciesByKey) {
+                    arrayDependencies.dependenciesByKey = {};
+                }
+
+                for (let arrayKey of args.arrayKeys) {
+                    // namesByKey also functions to indicate that dependencies
+                    // have been returned for that arrayKey
+
+                    // If had additional nameByKey, it should be treated as dependencies changing
+                    // so that we recalculate the value of the array variable
+                    // TODO: we are communicating this to updateDependencies by adding
+                    // an attribute to the arguments?  Is there a better way of doing it.
+                    // Didn't want to add to the return value, as that would add complexity
+                    // to how we normally define returnDependencies
+                    // We could change returnDependencies to output an object.
+                    // That would probably be cleaner.
+                    if (!(arrayKey in stateVarObj.dependencyNames.namesByKey)) {
+                        args.changedDependency = true;
+                    }
+                    stateVarObj.dependencyNames.namesByKey[arrayKey] = {};
+                    for (let depName in arrayDependencies.dependenciesByKey[
+                        arrayKey
+                    ]) {
+                        let extendedDepName = "__" + arrayKey + "_" + depName;
+                        dependencies[extendedDepName] =
+                            arrayDependencies.dependenciesByKey[arrayKey][
+                                depName
+                            ];
+                        stateVarObj.dependencyNames.namesByKey[arrayKey][
+                            depName
+                        ] = extendedDepName;
+                        if (
+                            !stateVarObj.dependencyNames.keysByName[
+                                extendedDepName
+                            ]
+                        ) {
+                            stateVarObj.dependencyNames.keysByName[
+                                extendedDepName
+                            ] = [];
+                        }
+                        if (
+                            !stateVarObj.dependencyNames.keysByName[
+                                extendedDepName
+                            ].includes(arrayKey)
+                        ) {
+                            stateVarObj.dependencyNames.keysByName[
+                                extendedDepName
+                            ].push(arrayKey);
+                        }
+                    }
+                }
+
+                // to tie into making sure array size is a dependency, below
+                stateVarObj.dependencyNames.global.push("__array_size");
+            }
+
+            // make sure array size is a dependency
+            dependencies.__array_size = {
+                dependencyType: "stateVariable",
+                variableName: stateVarObj.arraySizeStateVariable,
+            };
+
+            // console.log(`resulting dependencies for ${stateVariable} of ${component.componentIdx}`)
+            // console.log(dependencies)
+            return dependencies;
+        };
+
+        stateVarObj.getCurrentFreshness = function ({
+            freshnessInfo,
+            arrayKeys,
+            arraySize,
+        }) {
+            // console.log(`getCurrentFreshness for array ${stateVariable} of ${component.componentIdx}`)
+            // console.log(arrayKeys, arraySize);
+            // console.log(JSON.parse(JSON.stringify(freshnessInfo)))
+
+            if (arrayKeys === undefined) {
+                arrayKeys = stateVarObj.getAllArrayKeys(arraySize);
+            }
+
+            let freshByKey = freshnessInfo.freshByKey;
+
+            let numberFresh = freshnessInfo.freshArraySize ? 1 : 0;
+            for (let arrayKey of arrayKeys) {
+                if (freshByKey[arrayKey]) {
+                    numberFresh += 1;
+                }
+            }
+
+            if (numberFresh > 0) {
+                if (numberFresh === arrayKeys.length + 1) {
+                    return { fresh: { [stateVariable]: true } };
+                } else {
+                    return { partiallyFresh: { [stateVariable]: numberFresh } };
+                }
+            } else {
+                return { fresh: { [stateVariable]: false } };
+            }
+        };
+
+        stateVarObj.markStale = function ({
+            freshnessInfo,
+            changes,
+            arrayKeys,
+            arraySize,
+        }) {
+            // console.log(`markStale for array ${stateVariable} of ${component.componentIdx}`)
+            // console.log(changes, arrayKeys, arraySize);
+            // console.log(JSON.parse(JSON.stringify(freshnessInfo)))
+
+            let result = {};
+
+            if (arrayKeys === undefined) {
+                arrayKeys = stateVarObj.getAllArrayKeys(arraySize);
+            }
+
+            if (stateVarObj.markStaleByKey) {
+                result = stateVarObj.markStaleByKey({ arrayKeys, changes });
+            }
+
+            let freshByKey = freshnessInfo.freshByKey;
+
+            if (changes.__array_size) {
+                freshnessInfo.freshArraySize = false;
+                // everything is stale
+                freshnessInfo.freshByKey = {};
+                result.fresh = { [stateVariable]: false };
+                return result;
+            }
+
+            if (Object.keys(freshByKey).length === 0) {
+                // everything is stale, except possibly array size
+                // (check for nothing fresh as a shortcut, as mark stale could
+                // be called repeated if size doesn't change, given that it's partially fresh)
+                freshnessInfo.freshByKey = {};
+                if (freshnessInfo.freshArraySize) {
+                    result.partiallyFresh = { [stateVariable]: 1 };
+                    return result;
+                } else {
+                    result.fresh = { [stateVariable]: false };
+                    return result;
+                }
+            }
+
+            for (let changeName in changes) {
+                if (stateVarObj.dependencyNames.global.includes(changeName)) {
+                    // everything is stale, except possible array size
+                    freshnessInfo.freshByKey = {};
+                    if (freshnessInfo.freshArraySize) {
+                        result.partiallyFresh = { [stateVariable]: 1 };
+                        return result;
+                    } else {
+                        result.fresh = { [stateVariable]: false };
+                        return result;
+                    }
+                }
+
+                if (
+                    stateVarObj.basedOnArrayKeyStateVariables &&
+                    arrayKeys.length > 1
+                ) {
+                    delete freshByKey[changeName];
+                } else {
+                    for (let key of stateVarObj.dependencyNames.keysByName[
+                        changeName
+                    ]) {
+                        delete freshByKey[key];
+                    }
+                }
+            }
+
+            // check if the array keys requested are fresh
+            let numberFresh = freshnessInfo.freshArraySize ? 1 : 0;
+            for (let arrayKey of arrayKeys) {
+                if (freshByKey[arrayKey]) {
+                    numberFresh += 1;
+                }
+            }
+
+            // console.log(`ending freshness`)
+            // console.log(JSON.parse(JSON.stringify(freshnessInfo)))
+
+            if (numberFresh > 0) {
+                if (numberFresh === arrayKeys.length + 1) {
+                    result.fresh = { [stateVariable]: true };
+                    return result;
+                } else {
+                    result.partiallyFresh = { [stateVariable]: numberFresh };
+                    return result;
+                }
+            } else {
+                result.fresh = { [stateVariable]: false };
+                return result;
+            }
+        };
+
+        stateVarObj.freshenOnNoChanges = function ({
+            arrayKeys,
+            freshnessInfo,
+            arraySize,
+        }) {
+            // console.log(`freshenOnNoChanges for ${stateVariable} of ${component.componentIdx}`)
+            let freshByKey = freshnessInfo.freshByKey;
+
+            if (arrayKeys === undefined) {
+                arrayKeys = stateVarObj.getAllArrayKeys(arraySize);
+            }
+
+            for (let arrayKey of arrayKeys) {
+                freshByKey[arrayKey] = true;
+            }
+        };
+
+        function extractArrayDependencies(
+            dependencyValues,
+            arrayKeys,
+            usedDefault,
+        ) {
+            // console.log(`extract array dependencies`, dependencyValues, arrayKeys, usedDefault)
+            // console.log(JSON.parse(JSON.stringify(arrayKeys)))
+
+            let globalDependencyValues = {};
+            let globalUsedDefault = {};
+            for (let dependencyName of stateVarObj.dependencyNames.global) {
+                globalDependencyValues[dependencyName] =
+                    dependencyValues[dependencyName];
+                globalUsedDefault[dependencyName] = usedDefault[dependencyName];
+            }
+
+            let dependencyValuesByKey = {};
+            let usedDefaultByKey = {};
+            let foundAllDependencyValuesForKey = {};
+            for (let arrayKey of arrayKeys) {
+                dependencyValuesByKey[arrayKey] = {};
+                usedDefaultByKey[arrayKey] = {};
+                if (arrayKey in stateVarObj.dependencyNames.namesByKey) {
+                    foundAllDependencyValuesForKey[arrayKey] = true;
+                    for (let dependencyName in stateVarObj.dependencyNames
+                        .namesByKey[arrayKey]) {
+                        let extendedDepName =
+                            stateVarObj.dependencyNames.namesByKey[arrayKey][
+                                dependencyName
+                            ];
+                        if (extendedDepName in dependencyValues) {
+                            dependencyValuesByKey[arrayKey][dependencyName] =
+                                dependencyValues[extendedDepName];
+                            usedDefaultByKey[arrayKey][dependencyName] =
+                                usedDefault[extendedDepName];
+                        } else {
+                            foundAllDependencyValuesForKey[arrayKey] = false;
+                        }
+                    }
+                }
+            }
+
+            return {
+                globalDependencyValues,
+                globalUsedDefault,
+                dependencyValuesByKey,
+                usedDefaultByKey,
+                foundAllDependencyValuesForKey,
+            };
+        }
+
+        stateVarObj.definition = function (args) {
+            // console.log(`definition in array ${stateVariable} of ${component.componentIdx}`)
+            // console.log(JSON.parse(JSON.stringify(args)));
+            // console.log(args.arrayKeys)
+            // console.log(args.dependencyValues)
+
+            if (args.arrayKeys === undefined) {
+                args.arrayKeys = stateVarObj.getAllArrayKeys(args.arraySize);
+            }
+
+            if (
+                stateVarObj.basedOnArrayKeyStateVariables &&
+                args.arrayKeys.length > 1
+            ) {
+                // if based on array key state variables and have more than one array key
+                // then must have calculated all the relevant array keys
+                // when retrieving the dependency values
+                // Hence there is nothing to do, as arrayValues has been populated
+                // with all the requisite values
+
+                return {};
+            } else {
+                let extractedDeps = extractArrayDependencies(
+                    args.dependencyValues,
+                    args.arrayKeys,
+                    args.usedDefault,
+                );
+                let globalDependencyValues =
+                    extractedDeps.globalDependencyValues;
+                let globalUsedDefault = extractedDeps.globalUsedDefault;
+                let dependencyValuesByKey = extractedDeps.dependencyValuesByKey;
+                let usedDefaultByKey = extractedDeps.usedDefaultByKey;
+                let foundAllDependencyValuesForKey =
+                    extractedDeps.foundAllDependencyValuesForKey;
+
+                delete args.dependencyValues;
+                args.globalDependencyValues = globalDependencyValues;
+                args.globalUsedDefault = globalUsedDefault;
+                args.dependencyValuesByKey = dependencyValuesByKey;
+                args.usedDefaultByKey = usedDefaultByKey;
+
+                let arrayKeysToRecalculate = [];
+                let freshByKey = args.freshnessInfo.freshByKey;
+                for (let arrayKey of args.arrayKeys) {
+                    // only recalculate if
+                    // - arrayKey isn't fresh, and
+                    // - found all dependency values for array key (i.e., have calculated dependencies for arrayKey)
+                    if (
+                        !freshByKey[arrayKey] &&
+                        foundAllDependencyValuesForKey[arrayKey]
+                    ) {
+                        freshByKey[arrayKey] = true;
+                        arrayKeysToRecalculate.push(arrayKey);
+                    }
+                }
+
+                let result;
+                if (arrayKeysToRecalculate.length === 0) {
+                    // console.log(`nothing to recalculate`)
+                    // console.log(`was going to recalculate`, args.arrayKeys)
+                    // console.log(JSON.parse(JSON.stringify(args.freshnessInfo)))
+                    // console.log(JSON.parse(JSON.stringify(stateVarObj.dependencyNames)))
+                    result = {};
+                } else {
+                    args.arrayKeys = arrayKeysToRecalculate;
+
+                    if (!stateVarObj.arrayDefinitionByKey) {
+                        throw Error(
+                            `For ${stateVariable} of ${component.componentType}, arrayDefinitionByKey must be a function`,
+                        );
+                    }
+
+                    result = stateVarObj.arrayDefinitionByKey(args);
+
+                    // in case definition returns additional array entries,
+                    // mark all array keys received as fresh as well
+                    if (result.setValue && result.setValue[stateVariable]) {
+                        for (let arrayKey in result.setValue[stateVariable]) {
+                            freshByKey[arrayKey] = true;
+                        }
+                    }
+                    if (
+                        result.useEssentialOrDefaultValue &&
+                        result.useEssentialOrDefaultValue[stateVariable]
+                    ) {
+                        for (let arrayKey in result.useEssentialOrDefaultValue[
+                            stateVariable
+                        ]) {
+                            freshByKey[arrayKey] = true;
+                        }
+                    }
+                }
+
+                if (!args.freshnessInfo.freshArraySize) {
+                    if (args.changes.__array_size) {
+                        result.arraySizeChanged = [stateVariable];
+                        if (stateVarObj.additionalStateVariablesDefined) {
+                            for (let varName of stateVarObj.additionalStateVariablesDefined) {
+                                // do we have to check if it is array?
+                                if (component.state[varName].isArray) {
+                                    result.arraySizeChanged.push(varName);
+                                }
+                            }
+                        }
+                    }
+                    args.freshnessInfo.freshArraySize = true;
+                }
+
+                // console.log(`result of array definition of ${stateVariable} of ${component.componentIdx}`)
+                // console.log(JSON.parse(JSON.stringify(result)))
+                // console.log(JSON.parse(JSON.stringify(args.freshnessInfo)))
+                return result;
+            }
+        };
+
+        stateVarObj.inverseDefinition = function (args) {
+            // console.log(`inverse definition args for ${stateVariable}`)
+            // console.log(args)
+
+            if (!stateVarObj.inverseArrayDefinitionByKey) {
+                return { success: false };
+            }
+
+            if (args.arrayKeys === undefined) {
+                args.arrayKeys = stateVarObj.getAllArrayKeys(args.arraySize);
+            }
+
+            if (
+                stateVarObj.basedOnArrayKeyStateVariables &&
+                args.arrayKeys.length > 1
+            ) {
+                let instructions = [];
+
+                for (let vName of allStateVariablesAffected) {
+                    for (let key in args.desiredStateVariableValues[vName]) {
+                        let depName = vName + "_" + key;
+                        if (depName in args.dependencyValues) {
+                            instructions.push({
+                                setDependency: depName,
+                                desiredValue:
+                                    args.desiredStateVariableValues[vName][key],
+                                treatAsInitialChange: args.initialChange,
+                            });
+                        }
+                    }
+                }
+
+                return {
+                    success: true,
+                    instructions,
+                };
+            } else {
+                let extractedDeps = extractArrayDependencies(
+                    args.dependencyValues,
+                    args.arrayKeys,
+                    args.usedDefault,
+                );
+                let globalDependencyValues =
+                    extractedDeps.globalDependencyValues;
+                let globalUsedDefault = extractedDeps.globalUsedDefault;
+                let dependencyValuesByKey = extractedDeps.dependencyValuesByKey;
+                let usedDefaultByKey = extractedDeps.usedDefaultByKey;
+                // let foundAllDependencyValuesForKey = extractedDeps.foundAllDependencyValuesForKey;
+
+                delete args.dependencyValues;
+                args.globalDependencyValues = globalDependencyValues;
+                args.globalUsedDefault = globalUsedDefault;
+                args.dependencyValuesByKey = dependencyValuesByKey;
+                args.usedDefaultByKey = usedDefaultByKey;
+
+                args.dependencyNamesByKey =
+                    stateVarObj.dependencyNames.namesByKey;
+
+                if (!stateVarObj.allowExtraArrayKeysInInverse) {
+                    // by default, inverseArrayDefinitionByKey does not need to be
+                    // programmed defensively against arrayKeys that don't exist
+                    // as they are filtered out here.
+                    // However, if allowExtraArrayKeysInInverse, then we skip this
+                    // filtering to allow the possibility that the array size
+                    // could be changed.
+                    let newDesiredStateVariableValues = {};
+                    for (let vName in args.desiredStateVariableValues) {
+                        newDesiredStateVariableValues[vName] = {};
+                        for (let key in args.desiredStateVariableValues[
+                            vName
+                        ]) {
+                            if (args.arrayKeys.includes(key)) {
+                                newDesiredStateVariableValues[vName][key] =
+                                    args.desiredStateVariableValues[vName][key];
+                            }
+                        }
+                    }
+                    args.desiredStateVariableValues =
+                        newDesiredStateVariableValues;
+                }
+
+                let result = stateVarObj.inverseArrayDefinitionByKey(args);
+                // console.log(`result of inverse definition of array`)
+                // console.log(JSON.parse(JSON.stringify(result)))
+                return result;
+            }
+        };
+
+        await this.createArraySizeStateVariable({
+            stateVarObj,
+            component,
+            stateVariable,
+        });
+
+        stateVarObj.arraySizeStale = true;
+        stateVarObj.previousArraySize = [];
+
+        Object.defineProperty(stateVarObj, "arraySize", {
+            get: function () {
+                return (async () => {
+                    if (
+                        !component.state[stateVarObj.arraySizeStateVariable]
+                            .initiallyResolved
+                    ) {
+                        return [];
+                    }
+                    if (stateVarObj.arraySizeStale) {
+                        await stateVarObj.recalculateArraySizeDependentQuantities();
+                    }
+                    return await component.stateValues[
+                        stateVarObj.arraySizeStateVariable
+                    ];
+                })();
+            },
+        });
+
+        stateVarObj.recalculateArraySizeDependentQuantities =
+            async function () {
+                let newArraySize =
+                    await component.stateValues[
+                        stateVarObj.arraySizeStateVariable
+                    ];
+                if (
+                    stateVarObj.previousArraySize.length !==
+                        newArraySize.length ||
+                    stateVarObj.previousArraySize.some(
+                        (v, i) => v != newArraySize[i],
+                    )
+                ) {
+                    stateVarObj.previousArraySize = [...newArraySize];
+                    let varNamesIncluding =
+                        (stateVarObj.varNamesIncludingArrayKeys = {});
+                    for (let entryName of stateVarObj.arrayEntryNames) {
+                        let entryStateVarObj = component.state[entryName];
+                        let arrayKeys = stateVarObj.getArrayKeysFromVarName({
+                            arrayEntryPrefix: entryStateVarObj.entryPrefix,
+                            varEnding: entryStateVarObj.varEnding,
+                            arraySize: newArraySize,
+                            numDimensions: stateVarObj.numDimensions,
+                        });
+                        entryStateVarObj._unflattenedArrayKeys = arrayKeys;
+                        entryStateVarObj._arrayKeys = flattenDeep(arrayKeys);
+
+                        // for each arrayKey, add this entry name to the array's list variables
+                        for (let arrayKey of entryStateVarObj._arrayKeys) {
+                            if (!varNamesIncluding[arrayKey]) {
+                                varNamesIncluding[arrayKey] = [];
+                            }
+                            varNamesIncluding[arrayKey].push(entryName);
+                        }
+                    }
+                }
+                stateVarObj.arraySizeStale = false;
+            };
+
+        // link all freshnessInfo of additionalStateVariablesDefined
+        // to the same object, as they will share the same freshnessinfo
+        // TODO: a better idea?  This seems like it could lead to confusion.
+        if (!stateVarObj.freshnessInfo) {
+            stateVarObj.freshnessInfo = { freshByKey: {} };
+            if (stateVarObj.additionalStateVariablesDefined) {
+                for (let vName of stateVarObj.additionalStateVariablesDefined) {
+                    if (!component.state[vName]) {
+                        component.state[vName] = {};
+                    }
+                    component.state[vName].freshnessInfo =
+                        stateVarObj.freshnessInfo;
+                }
+            }
+        }
+    }
+
+    async createArraySizeStateVariable({
+        stateVarObj,
+        component,
+        stateVariable,
+    }) {
+        let allStateVariablesAffected = [stateVariable];
+        if (stateVarObj.additionalStateVariablesDefined) {
+            allStateVariablesAffected.push(
+                ...stateVarObj.additionalStateVariablesDefined,
+            );
+        }
+        allStateVariablesAffected.sort();
+
+        let arraySizeStateVar =
+            `__array_size_` + allStateVariablesAffected.join("_");
+        stateVarObj.arraySizeStateVariable = arraySizeStateVar;
+
+        let originalStateVariablesDeterminingDependencies;
+        let originalAdditionalStateVariablesDefined;
+
+        // Make the array's dependencies depend on the array size state variable
+        if (stateVarObj.stateVariablesDeterminingDependencies) {
+            originalStateVariablesDeterminingDependencies = [
+                ...stateVarObj.stateVariablesDeterminingDependencies,
+            ];
+            stateVarObj.stateVariablesDeterminingDependencies.push(
+                arraySizeStateVar,
+            );
+        } else {
+            stateVarObj.stateVariablesDeterminingDependencies = [
+                arraySizeStateVar,
+            ];
+        }
+
+        // If array size state variable has already been created,
+        // either it was created due to being shadowed
+        // or from an additional state variable defined.
+        // If it is shadowing target array size state variable,
+        // make it mark the array's arraySize as stale on markStale
+        if (component.state[arraySizeStateVar]) {
+            if (component.state[arraySizeStateVar].isShadow) {
+                let arraySizeStateVarObj = component.state[arraySizeStateVar];
+                arraySizeStateVarObj.markStale = function () {
+                    for (let varName of allStateVariablesAffected) {
+                        component.state[varName].arraySizeStale = true;
+                    }
+                    return {};
+                };
+            }
+            return;
+        }
+
+        component.state[arraySizeStateVar] = {
+            returnDependencies: stateVarObj.returnArraySizeDependencies,
+            definition({ dependencyValues }) {
+                let arraySize = stateVarObj.returnArraySize({
+                    dependencyValues,
+                });
+                for (let [ind, value] of arraySize.entries()) {
+                    if (!(Number.isInteger(value) && value >= 0)) {
+                        arraySize[ind] = 0;
+                    }
+                }
+                return { setValue: { [arraySizeStateVar]: arraySize } };
+            },
+            markStale() {
+                for (let varName of allStateVariablesAffected) {
+                    component.state[varName].arraySizeStale = true;
+                }
+                return {};
+            },
+        };
+
+        if (stateVarObj.stateVariablesDeterminingArraySizeDependencies) {
+            component.state[
+                arraySizeStateVar
+            ].stateVariablesDeterminingDependencies =
+                stateVarObj.stateVariablesDeterminingArraySizeDependencies;
+        }
+
+        await this.initializeStateVariable({
+            component,
+            stateVariable: arraySizeStateVar,
+        });
+    }
+
+    // arrayEntryNamesFromPropIndex is essentially a wrapper around
+    // stateVarObj.arrayVarNameFromPropIndex.
+    // (See above description of arrayVarNameFromPropIndex for technical debt commentary.)
+    // It calls arrayVarNameFromPropIndex on each of an array of stateVariables,
+    // first creating any missing array entry state variables,
+    // logs diagnostics,
+    // and returns an array of the resulting state variables.
+    async arrayEntryNamesFromPropIndex({
+        stateVariables,
+        component,
+        propIndex,
+    }) {
+        let newVarNames = [];
+        for (let varName of stateVariables) {
+            let stateVarObj = component.state[varName];
+            if (!stateVarObj) {
+                if (
+                    !this.core.checkIfArrayEntry({
+                        stateVariable: varName,
+                        component,
+                    }).isArrayEntry
+                ) {
+                    // varName doesn't exist.  Ignore error here
+                    newVarNames.push(varName);
+                    continue;
+                }
+                await this.core.createFromArrayEntry({
+                    stateVariable: varName,
+                    component,
+                });
+                stateVarObj = component.state[varName];
+            }
+
+            let newName;
+            if (stateVarObj.isArray) {
+                newName = stateVarObj.arrayVarNameFromPropIndex(
+                    propIndex,
+                    varName,
+                );
+            } else if (stateVarObj.isArrayEntry) {
+                let arrayStateVarObj =
+                    component.state[stateVarObj.arrayStateVariable];
+                newName = arrayStateVarObj.arrayVarNameFromPropIndex(
+                    propIndex,
+                    varName,
+                );
+            } else {
+                this.core.addDiagnostic({
+                    type: "warning",
+                    message: `Cannot get propIndex from ${varName} of ${component.componentIdx} as it is not an array or array entry state variable`,
+                    position: component.position,
+                    sourceDoc: component.sourceDoc,
+                });
+                newName = varName;
+            }
+            if (newName) {
+                newVarNames.push(newName);
+            } else {
+                this.core.addDiagnostic({
+                    type: "warning",
+                    message: `Cannot get propIndex from ${varName} of ${component.componentIdx}`,
+                    position: component.position,
+                    sourceDoc: component.sourceDoc,
+                });
+                newVarNames.push(varName);
+            }
+        }
+
+        return newVarNames;
+    }
+
+    recursivelyReplaceCompositesWithReplacements({
+        replacements,
+        recurseNonStandardComposites = false,
+        forceExpandComposites = false,
+        includeWithheldReplacements = false,
+        stopIfHaveProp,
+    }) {
+        let compositesFound = [];
+        let newReplacements = [];
+        let unexpandedCompositesReady = [];
+        let unexpandedCompositesNotReady = [];
+
+        for (let replacement of replacements) {
+            if (
+                this.core.componentInfoObjects.isCompositeComponent({
+                    componentType: replacement.componentType,
+                    includeNonStandard: recurseNonStandardComposites,
+                })
+            ) {
+                if (stopIfHaveProp) {
+                    const checkForPublic = this.core.matchPublicStateVariables({
+                        stateVariables: [stopIfHaveProp],
+                        componentClass: replacement.constructor,
+                    })[0];
+
+                    if (!checkForPublic.startsWith("__not_public_")) {
+                        // The composite has a public state variable that matches `stopIfHaveProp`.
+                        // Therefore, we don't recurse to its replacements but treat the composite itself as the replacement
+                        newReplacements.push(replacement);
+                        continue;
+                    }
+                }
+
+                compositesFound.push(replacement.componentIdx);
+
+                if (!replacement.isExpanded) {
+                    if (
+                        replacement.state.readyToExpandWhenResolved.isResolved
+                    ) {
+                        unexpandedCompositesReady.push(
+                            replacement.componentIdx,
+                        );
+                    } else {
+                        unexpandedCompositesNotReady.push(
+                            replacement.componentIdx,
+                        );
+                    }
+                }
+
+                if (replacement.isExpanded) {
+                    let replacementReplacements = replacement.replacements;
+                    if (
+                        !includeWithheldReplacements &&
+                        replacement.replacementsToWithhold > 0
+                    ) {
+                        replacementReplacements = replacementReplacements.slice(
+                            0,
+                            -replacement.replacementsToWithhold,
+                        );
+                    }
+                    let recursionResult =
+                        this.recursivelyReplaceCompositesWithReplacements({
+                            replacements: replacementReplacements,
+                            recurseNonStandardComposites,
+                            forceExpandComposites,
+                            includeWithheldReplacements,
+                            stopIfHaveProp,
+                        });
+                    compositesFound.push(...recursionResult.compositesFound);
+                    newReplacements.push(...recursionResult.newReplacements);
+                    unexpandedCompositesReady.push(
+                        ...recursionResult.unexpandedCompositesReady,
+                    );
+                    unexpandedCompositesNotReady.push(
+                        ...recursionResult.unexpandedCompositesNotReady,
+                    );
+                } else {
+                    newReplacements.push(replacement);
+                }
+            } else {
+                newReplacements.push(replacement);
+            }
+        }
+
+        return {
+            compositesFound,
+            newReplacements,
+            unexpandedCompositesReady,
+            unexpandedCompositesNotReady,
+        };
+    }
+}