@adobe/ecs 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Adobe, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,58 @@
-# Temporary Holding Version
+# @adobe/ecs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A high-performance, multithreaded Entity Component System for web-based applications, simulations and games.
+
+## Features
+
+- **Linear, gapless structure-of-arrays component storage**
+  - Fixed-length values (numbers, tuples, structs) in a `SharedArrayBuffer`
+    - Shared across the main thread and all workers
+    - Read by WASM kernels without copying
+    - WebGPU-compatible struct layout for fast uploads
+  - WebGPU storage for GPU system kernels
+    - Synced back to shared memory only when the CPU reads it
+  - Strings in shared memory, readable on every thread
+  - Objects and other variable-length values on the thread that owns them
+- **Declarations**
+  - Components and resources declared once, as TypeScript types; the build registers them
+  - Named types such as `F32`, `U32` and your own `Schema.Type`s give storage precision, width and bounds
+- **Systems**
+  - Plain TypeScript bodies with declared reads and writes
+  - Kernels compiled and checked at build time to optimized JavaScript, WASM and WGSL
+  - Balanced scheduling across the main thread, workers and the GPU
+  - Typed input, with its schema generated from the TypeScript type
+  - Render systems that draw straight from component storage
+  - Observer systems for reading state into a UI
+- **Changes**
+  - Per-component added and changed ticks: an O(1) check per entity, with each change seen exactly once
+  - Filters that skip unchanged chunks and 64-row blocks
+  - Structural changes batched at sync points, so memory never moves while systems run
+  - Rules, finalizers and traits for derived components, cleanup and references
+- **Queries**
+  - Hash, unique, sorted and keyless indexes, all updated incrementally
+  - Hierarchy traversal that reruns only below what changed
+- **Threads**
+  - Worlds shared with other threads through a `MessagePort` or worker
+  - Joined threads run their own systems and observers, and lend their workers to the pool
+- **Runtime**
+  - Kernels allocate nothing per row; commands and lookups reuse their buffers
+  - Runs resolve to what a body returns, and reject naming each system that failed; ticks' failures are reported out of
+    band, once per failing system
+
+## Setup
+
+Install it with `npm install @adobe/ecs`, and build with its plugin:
+
+```ts
+// vite.config.ts
+import { Compiler } from "@adobe/ecs/compiler";
+export default defineConfig({ plugins: [Compiler.plugin()] });
+```
+
+A library builds with `Compiler.plugin({ library: true })`, so its build ships the registrations its declarations give.
+
+## Guide
+
+See the [guide](https://opensource.adobe.com/data/ecs/samples/#ecs-guide) for how to use it, each chapter's program edited
+and run in the browser beside its prose, and the [API reference](https://opensource.adobe.com/data/ecs/) for every type and
+function. The guide is the `ecs-guide` package in this package's repository, its chapters in `src/guide`.

package/dist/implementation/compiler/access.d.ts

@@ -0,0 +1,6 @@
+import type { Node } from 'estree';
+import type { Key } from './key.js';
+import type { Scope } from './scope.js';
+import { type Value } from './value.js';
+/** `value[key]`, resolved at compile time where the kernel subset allows. */
+export declare const access: (value: Value, key: Key, node: Node, scope: Scope, optional: boolean) => Value;

package/dist/implementation/compiler/access.js

@@ -0,0 +1,159 @@
+import { entityRead } from './columns.js';
+import { fail } from './failure.js';
+import { local, number } from './ir.js';
+import { mathConstants, mathFunctions } from './math.js';
+import { scalar } from './scalar.js';
+import { resolveExport } from './link.js';
+import { resolvedValue } from './module-value.js';
+import { describeValue, scalarValue } from './value.js';
+const commandNames = new Set(["spawn", "despawn", "add", "remove"]);
+const literal = (key) => key.kind === "static" ? key.name : undefined;
+/** Indexes a plain JS value. A static index into a resource or the input extends its path. */
+const element = (node, scope, object, key, optional) => {
+    if (key.kind === "static" && !optional && (object.kind === "resource" || object.kind === "args" || object.kind === "shared")) {
+        return { ...object, path: [...object.path, key.name] };
+    }
+    const index = key.kind === "static"
+        ? typeof key.name === "number" ? number(key.name) : { kind: "string", value: key.name }
+        : key.kind === "value" ? scalar(key.value, node, scope)
+            : fail(node, `${key.name} is not an index here`);
+    return { kind: "element", object, index, optional };
+};
+const mathConstant = (name) => {
+    const value = Reflect.get(Math, name);
+    return number(typeof value === "number" ? value : NaN);
+};
+/** `value[key]`, resolved at compile time where the kernel subset allows. */
+export const access = (value, key, node, scope, optional) => {
+    const signature = scope.unit.signature;
+    const name = literal(key);
+    switch (value.kind) {
+        case "row":
+            if (key.kind === "binding") {
+                if (!signature.read.has(key.name) && !signature.write.has(key.name))
+                    fail(node, `${key.name} is not in components read or write`);
+                // A shared component is the call's archetype's value, which each call takes as a parameter.
+                const shared = signature.shared.indexOf(key.name);
+                if (shared >= 0) {
+                    scope.unit.used.read.add(key.name);
+                    return { kind: "dynamic", expression: { kind: "shared", index: shared, path: [] } };
+                }
+                return { kind: "component", component: key.name, path: [] };
+            }
+            if (name === "entity")
+                return scalarValue(entityRead(scope.unit));
+            return fail(node, "row is indexed by a component in components read or write, or .entity");
+        case "context":
+            if (name === "resources")
+                return { kind: "resources" };
+            if (name === "lookup")
+                return { kind: "lookups" };
+            if (name === "reduce")
+                return { kind: "reducers" };
+            if (name === "commands")
+                return { kind: "commands" };
+            if (name === "up" && scope.unit.up !== null)
+                return { kind: "found", lookup: signature.lookups.length, expression: local(scope.unit.up) };
+            return fail(node, "the context holds the declared resources, lookup, reduce and up, and commands");
+        case "resources": {
+            const index = key.kind === "binding" ? signature.resources.indexOf(key.name) : -1;
+            if (key.kind !== "binding" || index < 0)
+                return fail(node, `${key.kind === "binding" ? key.name : "resources"} is not in resources read`);
+            scope.unit.used.resources.add(key.name);
+            return { kind: "dynamic", expression: { kind: "resource", index, path: [] } };
+        }
+        case "reducers": {
+            const reduced = key.kind === "binding" ? signature.reduced.findIndex(entry => entry.resource === key.name) : -1;
+            return reduced >= 0 ? { kind: "reducer", reduced } : fail(node, "reduce is indexed by a resource in the declaration's resources.reduce");
+        }
+        case "lookups": {
+            const lookup = signature.lookups.findIndex(entry => entry.name === name);
+            return lookup >= 0 ? { kind: "lookup", lookup } : fail(node, "lookup holds the declaration's lookups, by name");
+        }
+        case "found": {
+            // The lookup after the declaration's is `up`'s.
+            const up = value.lookup === signature.lookups.length ? signature.up : null;
+            const lookup = up ?? signature.lookups[value.lookup];
+            // A lookup by entity with `changed` gives it after what it reads.
+            if (up === null && lookup !== undefined && "watches" in lookup && lookup.watches && name === "changed") {
+                return { kind: "dynamic", expression: { kind: "element", object: value.expression, index: number(lookup.read.length), optional } };
+            }
+            const index = key.kind === "binding" ? (lookup?.read ?? []).indexOf(key.name) : -1;
+            if (lookup === undefined || key.kind !== "binding" || index < 0)
+                return fail(node, up === null ? "a lookup result is indexed by a component in that lookup's read, or by changed with changed declared" : "up is indexed by a component in up.read");
+            if (up !== null) {
+                // Read straight from the parent's columns, at the parent's row.
+                if (optional)
+                    return fail(node, "up is read only where it isn't null: test up === null first");
+                scope.unit.used.up.add(key.name);
+                return { kind: "component", component: key.name, path: [], up: true };
+            }
+            else {
+                const used = scope.unit.used.lookups;
+                const name = signature.lookups[value.lookup]?.name ?? "";
+                used.set(name, (used.get(name) ?? new Set()).add(key.name));
+            }
+            return { kind: "dynamic", expression: { kind: "element", object: value.expression, index: number(index), optional } };
+        }
+        case "indexed":
+            // A unique index's result is its first row.
+            if (name === "length")
+                return scalarValue({ kind: "listLength", list: value.list, lookup: value.lookup });
+            if (name === "changed")
+                return scalarValue({ kind: "listChanged", list: value.list, lookup: value.lookup });
+            if (name === "at")
+                return { kind: "listAt", lookup: value.lookup, list: value.list };
+            return access({ kind: "indexRow", lookup: value.lookup, row: value.first }, key, node, scope, optional);
+        case "indexRow": {
+            if (name === "entity")
+                return scalarValue({ kind: "rowEntity", row: value.row, lookup: value.lookup });
+            const lookup = signature.lookups[value.lookup];
+            const read = key.kind === "binding" ? (lookup?.read ?? []).indexOf(key.name) : -1;
+            if (lookup === undefined || key.kind !== "binding" || read < 0)
+                return fail(node, "a lookup's row is indexed by a component in that lookup's read, or .entity");
+            const used = scope.unit.used.lookups;
+            used.set(lookup.name, (used.get(lookup.name) ?? new Set()).add(key.name));
+            return { kind: "rowRead", lookup: value.lookup, row: value.row, read, path: [] };
+        }
+        case "rowRead":
+            return name === undefined
+                ? fail(node, "component values are indexed by literal elements or field names")
+                : { ...value, path: [...value.path, name] };
+        case "dynamic":
+            return { kind: "dynamic", expression: element(node, scope, value.expression, key, optional) };
+        case "tuple":
+            return typeof name === "number" && value.items[name] !== undefined
+                ? value.items[name]
+                : fail(node, "tuple elements are indexed by an in-range literal");
+        case "struct": {
+            const field = value.fields.find(([fieldName]) => fieldName === name);
+            return field ? field[1] : fail(node, `no field ${String(name)}`);
+        }
+        case "component":
+        case "snapshot":
+            return name === undefined
+                ? fail(node, "component values are indexed by literal elements or field names")
+                : { ...value, path: [...value.path, name] };
+        case "math":
+            if (typeof name === "string" && mathConstants.has(name))
+                return scalarValue(mathConstant(name));
+            if (typeof name === "string" && mathFunctions.has(name))
+                return { kind: "method", owner: "math", name };
+            return fail(node, `Math.${String(name)} is not in the kernel subset`);
+        case "namespace": {
+            const link = scope.unit.link;
+            if (typeof name !== "string" || link === null)
+                return fail(node, "namespaces are indexed by an export name");
+            const out = [];
+            const member = resolvedValue(node, resolveExport(link, value.file, name), scope, out);
+            return out.length === 0 ? member : fail(node, `${name} must be a function or a literal constant`);
+        }
+        case "commands":
+            if (typeof name === "string" && commandNames.has(name))
+                return { kind: "method", owner: "commands", name };
+            return fail(node, "commands has spawn, despawn, add and remove");
+        default:
+            return fail(node, `${describeValue(value)} can't be indexed`);
+    }
+};
+//# sourceMappingURL=access.js.map

package/dist/implementation/compiler/access.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.js","sourceRoot":"","sources":["../../../src/implementation/compiler/access.ts"],"names":[],"mappings":"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"}

package/dist/implementation/compiler/archetypes.d.ts

@@ -0,0 +1,17 @@
+import type { PassResult } from './input-schemas.js';
+import type { Module } from './type-schemas.js';
+/**
+ * The function the plugin appends, as `name`, to a module with lists of keys it can read: it gives a list a
+ * program-wide index, by which worlds find what they resolved for it without comparing components, when every member is
+ * a symbol, each once, and returns the list. It runs where the list is made, before any key's declaration may be
+ * registered, so whether they're components is checked where the list is used. Generated code imports nothing, so it
+ * shares the count through a global, as every copy of the package does (`registry/archetypes.ts`).
+ */
+export declare const archetypeFunction: (name: string) => string;
+/**
+ * Gives each top-level list of keys declared `as const`, `const List = [a, b] as const`, a program-wide index: its
+ * members are the module's `Symbol()` constants or value imports, and the appended function indexes it once they're
+ * all declared components. `as const` makes it a readonly tuple, which nothing changes, as an indexed list must not.
+ * A list naming one of the module's keys twice fails; one naming an import twice is left without an index.
+ */
+export declare const archetypeInsertions: (module: Module) => PassResult | null;

package/dist/implementation/compiler/archetypes.js

@@ -0,0 +1,141 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { archetypeCountName, archetypeIndexName } from '../../interface/registry/archetypes.js';
+/**
+ * The function the plugin appends, as `name`, to a module with lists of keys it can read: it gives a list a
+ * program-wide index, by which worlds find what they resolved for it without comparing components, when every member is
+ * a symbol, each once, and returns the list. It runs where the list is made, before any key's declaration may be
+ * registered, so whether they're components is checked where the list is used. Generated code imports nothing, so it
+ * shares the count through a global, as every copy of the package does (`registry/archetypes.ts`).
+ */
+export const archetypeFunction = (name) => [
+    `function ${name}(list) {`,
+    ` const index = Symbol.for(${JSON.stringify(archetypeIndexName)}), count = Symbol.for(${JSON.stringify(archetypeCountName)});`,
+    ` if (Object.prototype.hasOwnProperty.call(list, index) || !Object.isExtensible(list)) return list;`,
+    ` for (let k = 0; k < list.length; k++) if (typeof list[k] !== "symbol" || list.indexOf(list[k]) < k) return list;`,
+    ` const next = globalThis[count] || 0; globalThis[count] = next + 1; Object.defineProperty(list, index, { value: next });`,
+    ` return list;`,
+    `}`,
+].join("");
+const uniqueName = (code, base) => {
+    let name = base;
+    for (let n = 1; code.includes(name); n++)
+        name = `${base}${n}`;
+    return name;
+};
+const isNode = (value) => typeof Reflect.get(value, "start") === "number" && typeof Reflect.get(value, "type") === "string";
+const isConstList = (node) => {
+    if (node.type !== "TSAsExpression")
+        return false;
+    const expression = Reflect.get(node, "expression");
+    const annotation = Reflect.get(node, "typeAnnotation");
+    const typeName = typeof annotation === "object" && annotation !== null ? Reflect.get(annotation, "typeName") : undefined;
+    return typeof expression === "object" && expression !== null && Reflect.get(expression, "type") === "ArrayExpression"
+        && typeof typeName === "object" && typeName !== null && Reflect.get(typeName, "type") === "Identifier" && Reflect.get(typeName, "name") === "const";
+};
+/** Nodes whose code runs when called, not when the module loads. */
+const functions = new Set(["ArrowFunctionExpression", "FunctionExpression", "FunctionDeclaration", "ClassDeclaration", "ClassExpression"]);
+/** A top-level statement's variable declaration, exported or not. */
+const variablesOf = (statement) => {
+    const declared = statement.type === "ExportNamedDeclaration" ? statement.declaration : statement;
+    return declared?.type === "VariableDeclaration" ? declared : null;
+};
+/** Whether a module binds at top level a global the appended function uses. */
+const bindsGlobals = (module) => module.program.body.some(statement => {
+    const declared = statement.type === "ExportNamedDeclaration" ? statement.declaration : statement;
+    const names = declared?.type === "VariableDeclaration" ? declared.declarations.map(declarator => declarator.id.type === "Identifier" ? declarator.id.name : "")
+        : (declared?.type === "FunctionDeclaration" || declared?.type === "ClassDeclaration") ? [declared.id?.name ?? ""]
+            : statement.type === "ImportDeclaration" ? statement.specifiers.map(specifier => specifier.local.name)
+                : [];
+    return names.some(name => name === "Symbol" || name === "globalThis" || name === "Object");
+});
+/**
+ * Gives each top-level list of keys declared `as const`, `const List = [a, b] as const`, a program-wide index: its
+ * members are the module's `Symbol()` constants or value imports, and the appended function indexes it once they're
+ * all declared components. `as const` makes it a readonly tuple, which nothing changes, as an indexed list must not.
+ * A list naming one of the module's keys twice fails; one naming an import twice is left without an index.
+ */
+export const archetypeInsertions = (module) => {
+    const { code, program } = module;
+    if (!code.includes("as const") || bindsGlobals(module))
+        return null;
+    const keys = new Set();
+    const local = new Set();
+    for (const [name, imported] of module.imports)
+        if (imported.value && imported.imported !== null)
+            keys.add(name);
+    for (const statement of program.body) {
+        const variables = variablesOf(statement);
+        if (variables?.kind !== "const")
+            continue;
+        for (const { id, init } of variables.declarations) {
+            if (id.type === "Identifier" && init?.type === "CallExpression" && init.callee.type === "Identifier" && init.callee.name === "Symbol") {
+                keys.add(id.name);
+                local.add(id.name);
+            }
+        }
+    }
+    if (keys.size === 0 && module.imports.size === 0)
+        return null;
+    /** The module's top-level constants holding lists it indexes, which other lists may spread. */
+    const lists = new Set();
+    const insertions = [];
+    const name = uniqueName(code, "archetype$");
+    /** Lists naming one of the module's keys twice, which fail the build. */
+    const repeated = [];
+    /** Whether a list declared `as const` names only keys: the module's or imported, or spreads lists of them. */
+    const indexes = (list) => {
+        const named = [];
+        for (const element of list.expression.elements) {
+            if (element?.type === "Identifier" && keys.has(element.name))
+                named.push(element.name);
+            // A namespace's member, `Shapes.circle`, is a key of the package or a module imported.
+            else if (element?.type === "MemberExpression" && !element.computed && element.object.type === "Identifier" && element.property.type === "Identifier"
+                && module.imports.get(element.object.name)?.value === true)
+                named.push(`${element.object.name}.${element.property.name}`);
+            else if (element?.type !== "SpreadElement" || element.argument.type !== "Identifier" || !(lists.has(element.argument.name) || module.imports.get(element.argument.name)?.value === true))
+                return false;
+        }
+        const twice = named.find((member, k) => named.indexOf(member) < k);
+        if (twice === undefined)
+            return true;
+        if (local.has(twice))
+            repeated.push({ name: twice, at: list.start });
+        return false;
+    };
+    // Lists made when the module loads: those in functions are made on every call, so they aren't indexed.
+    const visit = (node, binding) => {
+        if (Array.isArray(node)) {
+            for (const item of node)
+                visit(item, null);
+            return;
+        }
+        if (typeof node !== "object" || node === null || !isNode(node) || functions.has(node.type))
+            return;
+        if (isConstList(node) && node.expression.elements.length > 0 && indexes(node)) {
+            insertions.push({ at: node.start, text: `${name}(` }, { at: node.end, text: ")" });
+            if (binding !== null)
+                lists.add(binding);
+            return;
+        }
+        for (const key of Object.keys(node))
+            if (key !== "parent")
+                visit(Reflect.get(node, key), null);
+    };
+    for (const statement of program.body) {
+        const variables = variablesOf(statement);
+        // A list a top-level `const` holds may be spread by those after it.
+        if (variables?.kind === "const")
+            for (const { id, init } of variables.declarations)
+                visit(init, id.type === "Identifier" ? id.name : null);
+        else
+            visit(statement, null);
+    }
+    const [twice] = repeated;
+    if (twice !== undefined)
+        return { failure: { message: `this list names ${twice.name} twice; a list of components names each once`, position: twice.at, frames: [] }, dependencies: [] };
+    if (insertions.length === 0)
+        return null;
+    insertions.push({ at: code.length, text: `\n${archetypeFunction(name)}\n` });
+    return { insertions, dependencies: [] };
+};
+//# sourceMappingURL=archetypes.js.map

package/dist/implementation/compiler/archetypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"archetypes.js","sourceRoot":"","sources":["../../../src/implementation/compiler/archetypes.ts"],"names":[],"mappings":"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"}

package/dist/implementation/compiler/assign.d.ts

@@ -0,0 +1,7 @@
+import type { AssignmentExpression, UpdateExpression } from 'estree';
+import type { Out } from './out.js';
+import { type Scope } from './scope.js';
+/** Compiles an assignment statement. */
+export declare const assign: (node: AssignmentExpression, scope: Scope, out: Out) => void;
+/** Compiles `x++`, `--x` and friends as statements. */
+export declare const update: (node: UpdateExpression, scope: Scope, out: Out) => void;

package/dist/implementation/compiler/assign.js

@@ -0,0 +1,162 @@
+import { access } from './access.js';
+import { failPattern } from './bind.js';
+import { set } from './booleans.js';
+import { changedColumns, fieldColumn, fieldRead } from './columns.js';
+import { leavesOf, toData } from './data.js';
+import { fail } from './failure.js';
+import { isBinary, local, number, references } from './ir.js';
+import { propertyKey } from './key.js';
+import { requireReadable } from './scalar.js';
+import { findLocal } from './scope.js';
+import { snapshotLeaf } from './snapshot.js';
+import { fresh } from './unit.js';
+import { describeValue } from './value.js';
+const localTarget = (node, expression) => expression.kind === "local" ? { kind: "local", local: expression.local } : fail(node, "this can't be assigned in a kernel");
+const root = (node) => node.type === "Identifier" ? node.name : node.type === "MemberExpression" ? root(node.object) : undefined;
+const requireWritable = (node, scope, component) => {
+    if (!scope.unit.signature.write.has(component))
+        fail(node, `${component} is not in components write`);
+    scope.unit.used.write.add(component);
+};
+/** Resolves an assignment target to a value whose scalar leaves are assignable. */
+const targetValue = (node, scope, out) => {
+    const value = scope.unit.expression(node, scope, out);
+    if (value.kind === "component") {
+        if (value.up === true)
+            return fail(node, "up is read-only");
+        requireWritable(node, scope, value.component);
+        // Values are immutable: a write replaces the whole component value.
+        if (value.path.length > 0)
+            return fail(node, "component values are immutable; write the whole value");
+        return value;
+    }
+    if (node.type !== "Identifier")
+        return fail(node, "values are immutable; assign a whole new value to a let local");
+    const name = root(node);
+    const local = name === undefined ? undefined : findLocal(scope, name);
+    if (value.kind === "dynamic" && (local?.mutable !== true || node.type !== "Identifier"))
+        return fail(node, "resources, args and lookup results are read-only in kernels");
+    if (local === undefined)
+        return fail(node, "this can't be assigned in a kernel");
+    if (!local.mutable)
+        return fail(node, `${name} is const`);
+    return value;
+};
+/** Pairs a target with assigned data, leaf by leaf. */
+const pair = (node, target, data, scope) => {
+    const unit = scope.unit;
+    switch (target.kind) {
+        case "component": {
+            const leaves = leavesOf(data);
+            if (target.path.length === 0 && data.kind !== "leaf") {
+                unit.shapes.add(`{ component: ${target.component}, leaves: ${JSON.stringify(leaves.map(leaf => leaf.path))} }`);
+            }
+            return leaves.map(leaf => ({
+                target: { kind: "column", column: fieldColumn(unit, target.component, [...target.path, ...leaf.path]) }, value: leaf.expression, component: target.component,
+            }));
+        }
+        case "snapshot":
+            return leavesOf(data).map(leaf => ({
+                target: { kind: "local", local: snapshotLeaf(unit, target.snapshot, [...target.path, ...leaf.path]) }, value: leaf.expression, component: undefined,
+            }));
+        case "scalar":
+        case "dynamic":
+            return data.kind === "leaf" ? [{ target: localTarget(node, target.expression), value: data.expression, component: undefined }] : fail(node, "can't assign a tuple or struct to a scalar");
+        case "tuple":
+            return data.kind === "tuple" && data.items.length === target.items.length
+                ? target.items.flatMap((item, index) => pair(node, item, data.items[index], scope))
+                : fail(node, "the assigned value must have the same shape");
+        case "struct":
+            if (data.kind !== "struct")
+                return fail(node, "the assigned value must have the same shape");
+            return target.fields.flatMap(([name, field]) => {
+                const source = data.fields.find(([sourceName]) => sourceName === name);
+                return source ? pair(node, field, source[1], scope) : fail(node, `the assigned value has no field ${name}`);
+            });
+        default:
+            return fail(node, `can't assign to ${describeValue(target)}`);
+    }
+};
+const collect = (pattern, value, scope, out) => {
+    switch (pattern.type) {
+        case "ArrayPattern":
+            return pattern.elements.flatMap((element, index) => element === null ? []
+                : element.type === "RestElement" ? fail(element, "rest elements are not in the kernel subset")
+                    : collect(element, access(value, { kind: "static", name: index }, element, scope, false), scope, out));
+        case "ObjectPattern":
+            return pattern.properties.flatMap(property => property.type === "RestElement"
+                ? fail(property, "rest elements are not in the kernel subset")
+                : collect(property.value, access(value, propertyKey(property, scope, out), property, scope, false), scope, out));
+        case "Identifier":
+        case "MemberExpression":
+            return pair(pattern, targetValue(pattern, scope, out), toData(value, pattern, scope), scope);
+        default:
+            return failPattern(pattern);
+    }
+};
+/** Whether `value` reads what `target` writes. */
+const reads = (value, target) => references(value, node => target.kind === "local"
+    ? node.kind === "local" && node.local === target.local
+    : node.kind === "column" && node.column === target.column);
+/**
+ * Emits stores as if every right-hand leaf were evaluated first, so `[a, b] = [b, a]` swaps: a leaf that reads an
+ * earlier store's target is copied to a temporary first. Each written component is stamped once.
+ */
+const emit = (stores, scope, out) => {
+    const unit = scope.unit;
+    const values = stores.map((store, index) => {
+        if (!stores.slice(0, index).some(earlier => reads(store.value, earlier.target)))
+            return store.value;
+        const temporary = fresh(unit, "t");
+        out.push(set(unit, temporary, store.value, "const"));
+        return local(temporary);
+    });
+    stores.forEach((store, index) => out.push(store.target.kind === "local"
+        ? set(unit, store.target.local, values[index], undefined)
+        : { kind: "store", column: store.target.column, value: values[index] }));
+    for (const component of new Set(stores.flatMap(store => store.component === undefined ? [] : [store.component]))) {
+        out.push({ kind: "stamp", ...changedColumns(unit, component) });
+    }
+};
+/** A scalar read-modify-write target. */
+const compoundStore = (node, operator, operand, scope, out) => {
+    if (!isBinary(operator))
+        return fail(node, `${operator}= is not in the kernel subset`);
+    const target = targetValue(node, scope, out);
+    const unit = scope.unit;
+    const combine = (current) => ({ kind: "binary", operator, left: current, right: operand });
+    switch (target.kind) {
+        case "component":
+            requireReadable(node, scope, target.component);
+            return {
+                target: { kind: "column", column: fieldColumn(unit, target.component, target.path) },
+                value: combine(fieldRead(unit, target.component, target.path)), component: target.component,
+            };
+        case "snapshot": {
+            const leaf = snapshotLeaf(unit, target.snapshot, target.path);
+            return { target: { kind: "local", local: leaf }, value: combine(local(leaf)), component: undefined };
+        }
+        case "scalar":
+        case "dynamic":
+            return { target: localTarget(node, target.expression), value: combine(target.expression), component: undefined };
+        default:
+            return fail(node, `compound assignment needs a scalar, not ${describeValue(target)}`);
+    }
+};
+const logical = new Set(["&&=", "||=", "??="]);
+/** Compiles an assignment statement. */
+export const assign = (node, scope, out) => {
+    if (node.operator === "=") {
+        const value = scope.unit.expression(node.right, scope, out);
+        return emit(collect(node.left, value, scope, out), scope, out);
+    }
+    if (logical.has(node.operator))
+        return fail(node, `${node.operator} is not in the kernel subset`);
+    const operand = toData(scope.unit.expression(node.right, scope, out), node.right, scope);
+    if (operand.kind !== "leaf")
+        return fail(node.right, "compound assignment needs a scalar");
+    emit([compoundStore(node.left, node.operator.slice(0, -1), operand.expression, scope, out)], scope, out);
+};
+/** Compiles `x++`, `--x` and friends as statements. */
+export const update = (node, scope, out) => emit([compoundStore(node.argument, node.operator === "++" ? "+" : "-", number(1), scope, out)], scope, out);
+//# sourceMappingURL=assign.js.map