@bablr/agast-vm 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Conrad Buck
+
+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

@@ -0,0 +1,78 @@
+# @bablr/agast-vm
+
+The agAST VM provides consistency guarantees when with CSTML documents to parse or transform code. It has no language-specific functionality of any kind. Instead it acts as a streaming traversal engine for CSTML.
+
+## Why
+
+The goal of this project is to transition editors towards being a lot more like web browsers. You can have many of them, and they can be written in a variety of languages (though many share internals). You can even have a terminal browser like Lynx that does presentation very differently, yet it is still possible (if not trivial) to write a website once that will run on all (er, most) web browsers.
+
+If the parallel is not immediately obvious, try thinking about it this way: a webapp is really more or less a set of automated tools for editing a DOM tree. As programmers we have all these amazing web libraries and frameworks that can exist because at the end of the day everything comes down to editing a shared DOM tree. There's a great explanation of those dynamics here: https://glazkov.com/2024/01/02/the-protocol-force/
+
+If a code-DOM existed and was shared by all IDEs there would spring up a rich ecosystem of tools for accomplishing many kinds of tree alterations. For example it could become common for library authors to publish codemods that could help any project upgrade past breaking changes in its APIs!
+
+## API
+
+The VM responds to several instructions, but its primary API is `advance(token)`, where `token` may be a `StartFragmentTag`, `EndFragmentTag`, `StartNodeTag`, `EndNodeTag`, `Literal`, `Reference`, or `Gap`.
+
+The VM requires the basic invariants of CSTML to be followed, for example that `Reference` must be followed by either a `StartNodeTag` or a `Gap`. In fact, `agast-vm` is the reference implementation of these invariants.
+
+The VM supports `branch()`, `accept()`, and `reject()` instructions, which allow a series of instructions to have their effects applied or discarded together in a kind of transaction.
+
+Finally the VM supports `bindAttribute(key, value)`. A node's attributes start unbound, and this command is used to give them values. Once all declared attributes for a node are bound, that node's full start tag is known and can be emitted.
+
+Here are the basic types used by the VM:
+
+```ts
+type Token = StartFragmentTag | EndFragmentTag | StartNodeTag | EndNodeTag | Literal | Reference | Gap;
+
+type StartFragmentTag {
+  type: 'StartFragmentTag',
+  value: {
+    flags: {
+      trivia: boolean
+    },
+    language: string,
+  }
+}
+
+type EndFragmentTag {
+  type: 'EndFragmentTag',
+  value: null
+}
+
+type StartNodeTag {
+  type: 'StartNodeTag',
+  value: {
+    flags: {
+      token: boolean,
+      trivia: boolean,
+      escape: boolean
+    },
+    language: string,
+    type: string,
+    attributes: { [key: string]: boolean | number | string }
+  }
+}
+
+type EndNodeTag {
+  type: 'EndNodeTag',
+  value: null
+}
+
+type Literal {
+  value: string
+}
+
+type Reference {
+  type: 'Reference',
+  value: {
+    name: string,
+    isArray: boolean
+  }
+}
+
+type Gap {
+  type: 'Gap',
+  value: null,
+}
+```

package/lib/context.js

@@ -0,0 +1,170 @@
+import { reifyExpressionShallow, reifyExpression } from '@bablr/agast-vm-helpers';
+import { getCooked, sourceTextFor } from '@bablr/agast-helpers/stream';
+import { facades, actuals } from './facades.js';
+
+function* ownTerminalsFor(range, nextTerminals, tagNodes) {
+  if (!range) return;
+
+  const { 0: start, 1: end } = range;
+
+  const pastEnd = nextTerminals.get(end);
+
+  for (let term = start; term && term !== pastEnd; term = nextTerminals.get(term)) {
+    if (!(term === range[0] || term === range[1]) && term.type === 'OpenNodeTag') {
+      term = nextTerminals.get(tagNodes.get(term).endTag);
+    }
+
+    yield term;
+  }
+}
+
+function* allTerminalsFor(range, nextTerminals) {
+  if (!range) return;
+  const { 0: start, 1: end } = range;
+
+  const pastEnd = nextTerminals.get(end);
+
+  for (let tag = start; tag !== pastEnd; tag = nextTerminals.get(tag)) {
+    yield tag;
+  }
+}
+
+export const ContextFacade = class AgastContextFacade {
+  getPreviousTerminal(token) {
+    return actuals.get(this).prevTerminals.get(token);
+  }
+
+  getNextTerminal(token) {
+    return actuals.get(this).nextTerminals.get(token);
+  }
+
+  ownTerminalsFor(range) {
+    return actuals.get(this).ownTerminalsFor(range);
+  }
+
+  allTerminalsFor(range) {
+    return actuals.get(this).allTerminalsFor(range);
+  }
+
+  getCooked(range) {
+    return actuals.get(this).getCooked(range);
+  }
+
+  reifyExpression(range) {
+    return actuals.get(this).reifyExpression(range);
+  }
+
+  getProperty(node, name) {
+    return actuals.get(this).getProperty(node, name);
+  }
+
+  sourceTextFor(range) {
+    return actuals.get(this).sourceTextFor(range);
+  }
+
+  buildRange(terminals) {
+    return actuals.get(this).buildRange(terminals);
+  }
+
+  nodeForTag(tag) {
+    return actuals.get(this).nodeForTag(tag);
+  }
+
+  unbox(value) {
+    return actuals.get(this).unbox(value);
+  }
+};
+
+export const Context = class AgastContext {
+  static create() {
+    return new Context();
+  }
+
+  constructor() {
+    this.prevTerminals = new WeakMap();
+    this.nextTerminals = new WeakMap();
+    this.tagNodes = new WeakMap();
+    this.unboxedValues = new WeakMap();
+    this.facade = new ContextFacade();
+
+    facades.set(this, this.facade);
+  }
+
+  getProperty(result, name) {
+    return this.tagNodes.get(result[0] || result).properties.get(name);
+  }
+
+  isEmpty(range) {
+    const { path, parent } = this;
+
+    if (range[0]?.type === 'OpenNodeTag' && path !== parent.path) {
+      const nextTag = this.nextTerminals.get(range[0]);
+      if (!nextTag || nextTag.type === 'CloseNodeTag') {
+        return null;
+      }
+    } else {
+      return range[0] === range[1];
+    }
+  }
+
+  allTerminalsFor(range) {
+    return allTerminalsFor(range, this.nextTerminals);
+  }
+
+  allTerminalsReverseFor(range) {
+    return allTerminalsFor(range, this.prevTerminals);
+  }
+
+  ownTerminalsFor(range) {
+    return ownTerminalsFor(range, this.nextTerminals, this.tagNodes);
+  }
+
+  ownTerminalsReverseFor(range) {
+    return ownTerminalsFor(range, this.prevTerminals, this.tagNodes);
+  }
+
+  nodeForTag(tag) {
+    return this.tagNodes.get(tag);
+  }
+
+  sourceTextFor(range) {
+    return sourceTextFor(this.allTerminalsFor(range));
+  }
+
+  buildRange(terminals) {
+    const { prevTerminals, nextTerminals } = this;
+
+    let start, end;
+    for (const terminal of terminals) {
+      if (prevTerminals.has(terminal) || nextTerminals.has(terminal)) {
+        throw new Error('buildRange must not overwrite linkages');
+      }
+
+      if (end) {
+        prevTerminals.set(terminal, end);
+        nextTerminals.set(end, terminal);
+      }
+
+      start = start || terminal;
+      end = terminal || end;
+    }
+    return start ? [start, end] : null;
+  }
+
+  unbox(value) {
+    const { unboxedValues } = this;
+    if (!unboxedValues.has(value)) {
+      unboxedValues.set(value, reifyExpressionShallow(value));
+    }
+
+    return unboxedValues.get(value);
+  }
+
+  reifyExpression(value) {
+    return reifyExpression(value);
+  }
+
+  getCooked(range) {
+    return getCooked(this.ownTerminalsFor(range));
+  }
+};

package/lib/evaluate.js

@@ -0,0 +1,422 @@
+import { Coroutine } from '@bablr/coroutine';
+import {
+  buildNull,
+  buildGap,
+  buildReference,
+  buildLiteral,
+  buildDoctypeTag,
+  buildNodeOpenTag,
+  buildFragmentOpenTag,
+  buildFragmentCloseTag,
+  buildNodeCloseTag,
+} from '@bablr/agast-helpers/builders';
+import { StreamIterable, getStreamIterator } from '@bablr/agast-helpers/stream';
+import { printExpression } from '@bablr/agast-helpers/print';
+import { reifyExpression } from '@bablr/agast-vm-helpers';
+import { Path, Node } from './path.js';
+import { State } from './state.js';
+import { facades } from './facades.js';
+
+export const evaluate = (ctx, strategy) => new StreamIterable(__evaluate(ctx, strategy));
+
+const __evaluate = function* agastStrategy(ctx, strategy) {
+  let s = State.from(ctx);
+
+  const co = new Coroutine(getStreamIterator(strategy(facades.get(ctx), facades.get(s))));
+
+  co.advance();
+
+  for (;;) {
+    if (co.current instanceof Promise) {
+      co.current = yield co.current;
+    }
+
+    if (co.done) break;
+
+    const sourceInstr = co.value;
+    const instr = reifyExpression(sourceInstr);
+    let returnValue = undefined;
+
+    const { verb } = instr;
+
+    switch (verb) {
+      case 'branch': {
+        s = s.branch();
+
+        returnValue = facades.get(s);
+        break;
+      }
+
+      case 'accept': {
+        s = s.accept();
+
+        if (s.depth === 0) {
+          yield* s.emit();
+        }
+
+        returnValue = facades.get(s);
+        break;
+      }
+
+      case 'reject': {
+        const rejectedState = s;
+
+        s = s.reject();
+
+        if (rejectedState.path.depth > s.path.depth) {
+          const lowPath = rejectedState.path.at(
+            Math.min(s.path.depth + 1, rejectedState.path.depth),
+          );
+
+          const { name, isArray } = lowPath.reference?.value || {};
+
+          if (!s.node.resolver.counters.has(name) && !lowPath.openTag?.value.flags.trivia) {
+            yield* s.emit(buildReference(name, isArray));
+          }
+
+          if (s.result.type === 'Reference') {
+            yield* s.emit(buildNull());
+          }
+        }
+
+        returnValue = facades.get(s);
+        break;
+      }
+
+      case 'advance': {
+        const { arguments: { 0: terminal } = [] } = instr;
+
+        switch (terminal?.type || 'Null') {
+          case 'DoctypeTag': {
+            const { attributes } = terminal.value;
+            const doctypeTag = buildDoctypeTag(attributes);
+            const rootPath = Path.from(ctx);
+
+            if (s.path) {
+              throw new Error();
+            }
+
+            s.path = rootPath;
+
+            yield* s.emit(doctypeTag);
+
+            returnValue = doctypeTag;
+            break;
+          }
+
+          case 'Literal': {
+            const literal = buildLiteral(terminal.value);
+
+            if (!s.node.flags.token) {
+              throw new Error('literals must occur inside tokens');
+            }
+
+            if (s.held) {
+              throw new Error('Cannot consume input while hold register is full');
+            }
+
+            yield* s.emit(literal);
+
+            returnValue = literal;
+            break;
+          }
+
+          case 'Reference': {
+            const { name, isArray } = terminal.value;
+
+            const tag = buildReference(name, isArray);
+
+            if (s.result.type === 'Reference') {
+              throw new Error('double reference');
+            }
+
+            if (!s.path.depth) {
+              throw new Error();
+            }
+
+            if (s.node.flags.token) {
+              throw new Error();
+            }
+
+            s.node.resolver.consume(tag);
+
+            s.path = s.path.push(ctx, tag);
+
+            yield* s.emit(tag);
+
+            returnValue = tag;
+            break;
+          }
+
+          case 'Gap': {
+            const reference = s.result;
+
+            if (reference?.type !== 'Reference') throw new Error();
+
+            s.path = s.path.parent;
+
+            const gapTag = buildGap();
+
+            yield* s.emit(gapTag);
+
+            returnValue = gapTag;
+            break;
+          }
+
+          case 'Null': {
+            const reference = s.result;
+
+            if (reference?.type !== 'Reference') throw new Error();
+
+            s.path = s.path.parent;
+
+            const null_ = buildNull();
+
+            yield* s.emit(null_);
+
+            returnValue = null_;
+            break;
+          }
+
+          case 'OpenFragmentTag': {
+            const openTag = buildFragmentOpenTag();
+
+            s.node = Node.from(s.path, openTag);
+
+            yield* s.emit(openTag);
+
+            returnValue = openTag;
+            break;
+          }
+
+          case 'CloseFragmentTag': {
+            const closeTag = buildFragmentCloseTag();
+
+            yield* s.emit(closeTag);
+
+            returnValue = closeTag;
+            break;
+          }
+
+          case 'OpenNodeTag': {
+            const { flags, language, type, intrinsicValue, attributes } = terminal.value;
+            const reference = s.result;
+            const boundAttributes = Object.entries(attributes).filter((a) => a[1].type !== 'Gap');
+            const unboundAttributes = Object.entries(attributes).filter((a) => a[1].type === 'Gap');
+            const openTag = buildNodeOpenTag(
+              flags,
+              language,
+              type,
+              intrinsicValue,
+              Object.fromEntries(boundAttributes),
+            );
+
+            if (!flags.trivia && !flags.escape && s.path.depth > 1) {
+              if (reference.type !== 'Reference' && reference.type !== 'OpenFragmentTag') {
+                throw new Error('Invalid location for OpenNodeTag');
+              }
+            }
+
+            if (!flags.expression) {
+              const { flags } = openTag.value;
+
+              if (!(flags.trivia || flags.escape) && !s.path.depth) {
+                const tag = buildReference('root', false);
+                s.path = s.path.push(ctx, tag);
+                s.node.resolver.consume(tag);
+              }
+            } else {
+              s.expressionDepth++;
+            }
+
+            const newNode = s.node.push(s.path, openTag);
+
+            newNode.unboundAttributes = new Set(unboundAttributes.map((e) => e[0]));
+
+            ctx.tagNodes.set(openTag, newNode);
+
+            if (!flags.intrinsic) {
+              s.node = newNode;
+            } else {
+              s.path = s.path.parent;
+
+              if (s.path.depth > 1) {
+                const { properties } = s.node;
+                const { name: refName, isArray } = reference.value;
+
+                if (!isArray) {
+                  properties.set(refName, [openTag, openTag]);
+                } else {
+                  if (!properties.has(refName)) {
+                    properties.set(refName, []);
+                  }
+                  properties.get(refName).push([openTag, openTag]);
+                }
+              }
+            }
+
+            yield* s.emit(openTag);
+
+            returnValue = openTag;
+            break;
+          }
+
+          case 'CloseNodeTag': {
+            const { type, language } = terminal.value;
+            const { openTag } = s.node;
+            const { flags, type: openType } = openTag.value;
+
+            if (s.node.unboundAttributes?.size)
+              throw new Error('Grammar failed to bind all attributes');
+
+            if (!type) throw new Error(`CloseNodeTag must have type`);
+
+            if (s.path.depth > 1 && type !== openType)
+              throw new Error(
+                `Grammar close {type: ${type}} did not match open {type: ${openType}}`,
+              );
+
+            const closeTag = buildNodeCloseTag(type, language);
+
+            if (!flags.escape && !flags.trivia) {
+              const { name: refName, isArray } = s.path.reference.value;
+
+              if (s.path.depth > 2) {
+                const { properties } = s.node.parent;
+
+                if (!isArray) {
+                  properties.set(refName, [openTag, closeTag]);
+                } else {
+                  if (!properties.has(refName)) {
+                    properties.set(refName, []);
+                  }
+                  properties.get(refName).push([openTag, closeTag]);
+                }
+              }
+            }
+
+            if (flags.expression) {
+              s.expressionDepth--;
+            }
+
+            ctx.tagNodes.set(closeTag, s.node);
+
+            s.node.closeTag = closeTag;
+
+            s.node = s.node.parent;
+
+            if (!(flags.trivia || flags.escape)) {
+              s.path = s.path.parent;
+            }
+
+            yield* s.emit(closeTag, flags.expression);
+
+            returnValue = closeTag;
+            break;
+          }
+
+          default:
+            throw new Error();
+        }
+
+        break;
+      }
+
+      case 'shift': {
+        s.shift();
+        break;
+      }
+
+      case 'unshift': {
+        s.unshift();
+        break;
+      }
+
+      case 'bindAttribute': {
+        const { arguments: { 0: key, 1: value } = [] } = instr;
+
+        const { unboundAttributes } = s.node;
+
+        if (!unboundAttributes || !unboundAttributes.has(key)) {
+          throw new Error('No unbound attribute to bind');
+        }
+
+        if (s.node.openTag.type === 'OpenFragmentTag') {
+          throw new Error();
+        }
+
+        if (key === 'span') throw new Error('too late');
+
+        if (key === 'balancedSpan') {
+          throw new Error('not implemented');
+        }
+
+        // if (stateIsDifferent) {
+        //   // we can't allow effects to cross state branches
+        //   throw new Error();
+        // }
+
+        unboundAttributes.delete(key);
+
+        const { openTag } = s.node;
+
+        if (value != null) {
+          const { flags, language, type, intrinsicValue } = openTag.value;
+          const attributes = { ...openTag.value.attributes, [key]: value };
+          const newStartTag = buildNodeOpenTag(flags, language, type, intrinsicValue, attributes);
+
+          let startNext = ctx.nextTerminals.get(openTag);
+          let startPrev = ctx.prevTerminals.get(openTag);
+
+          ctx.prevTerminals.set(newStartTag, startPrev);
+          ctx.nextTerminals.set(startPrev, newStartTag);
+
+          ctx.tagNodes.set(newStartTag, s.node);
+
+          if (startNext) {
+            ctx.nextTerminals.set(newStartTag, startNext);
+            ctx.prevTerminals.set(startNext, newStartTag);
+          } else {
+            // could this terminal be stored anywhere else?
+            s.result = newStartTag;
+          }
+
+          s.node.openTag = newStartTag;
+        }
+
+        if (!unboundAttributes.size) {
+          yield* s.emit();
+        }
+
+        returnValue = s.node.openTag;
+        break;
+      }
+
+      case 'getState': {
+        returnValue = facades.get(s);
+        break;
+      }
+
+      case 'getContext': {
+        returnValue = facades.get(ctx);
+        break;
+      }
+
+      default: {
+        throw new Error(`Unexpected call of {type: ${printExpression(verb)}}`);
+      }
+    }
+
+    co.advance(returnValue);
+  }
+
+  s.path = s.path.parent;
+
+  if (s.depth > 0) {
+    throw new Error('Did not unwind state stack');
+  }
+
+  if (s.path?.depth > 0) {
+    throw new Error('Did not unwind path stack');
+  }
+};

package/lib/facades.js

@@ -0,0 +1,3 @@
+import { buildFacadeLayer } from '@bablr/agast-vm-helpers/facades';
+
+export const { facades, actuals } = buildFacadeLayer();

package/lib/index.js

@@ -0,0 +1,3 @@
+export { evaluate } from './evaluate.js';
+
+export { Context } from './context.js';

package/lib/path.js

@@ -0,0 +1,221 @@
+import { WeakStackFrame } from '@bablr/weak-stack';
+import { Resolver } from '@bablr/agast-helpers/tree';
+import { findRight } from './utils/array.js';
+import { facades, actuals } from './facades.js';
+
+const skipLevels = 3;
+const skipShiftExponentGrowth = 4;
+const skipAmounts = new Array(skipLevels)
+  .fill(null)
+  .map((_, i) => 2 >> (i * skipShiftExponentGrowth));
+const skipsByPath = new WeakMap();
+
+export const NodeFacade = class AgastNodeFacade {
+  constructor(path) {
+    facades.set(path, this);
+  }
+
+  get language() {
+    return actuals.get(this).language;
+  }
+
+  get type() {
+    return actuals.get(this).type;
+  }
+
+  get path() {
+    return actuals.get(this).path;
+  }
+
+  get parent() {
+    return facades.get(actuals.get(this).parent);
+  }
+
+  get range() {
+    return actuals.get(this).range;
+  }
+
+  get openTag() {
+    return actuals.get(this).openTag;
+  }
+
+  get closeTag() {
+    return actuals.get(this).closeTag;
+  }
+
+  get depth() {
+    return actuals.get(this).depth;
+  }
+
+  get flags() {
+    return actuals.get(this).flags;
+  }
+
+  get attributes() {
+    return actuals.get(this).attributes;
+  }
+};
+
+export const PathFacade = class AgastPathFacade {
+  constructor(path) {
+    facades.set(path, this);
+  }
+
+  get reference() {
+    return actuals.get(this).reference;
+  }
+
+  get parent() {
+    return facades.get(actuals.get(this).parent);
+  }
+
+  get depth() {
+    return actuals.get(this).depth;
+  }
+
+  at(depth) {
+    let parent = this;
+
+    if (depth > this.depth) throw new Error();
+
+    let d = actuals.get(parent).depth;
+    for (; d > depth; ) {
+      const skips = skipsByPath.get(actuals.get(this));
+      parent = (skips && findRight(skips, (skip) => d - skip > depth)) || parent.parent;
+      d = actuals.get(parent).depth;
+    }
+    return parent;
+  }
+
+  *parents(includeSelf = false) {
+    if (includeSelf) yield this;
+    let parent = this;
+    while ((parent = parent.parent)) {
+      yield parent;
+    }
+  }
+};
+
+export const Node = class AgastNode extends WeakStackFrame {
+  static from(path, openTag) {
+    return AgastNode.create(path, openTag);
+  }
+
+  constructor(
+    path,
+    openTag,
+    closeTag = null,
+    properties = new Map(),
+    resolver = new Resolver(),
+    unboundAttributes = null,
+  ) {
+    super();
+
+    this.path = path;
+    this.openTag = openTag;
+    this.closeTag = closeTag;
+    this.properties = properties;
+    this.resolver = resolver;
+    this.unboundAttributes = unboundAttributes;
+  }
+
+  get context() {
+    return this.path.context;
+  }
+
+  get language() {
+    return this.openTag.value?.language;
+  }
+
+  get type() {
+    return this.openTag.value?.type || Symbol.for('@bablr/fragment');
+  }
+
+  get flags() {
+    return this.openTag.value?.flags || {};
+  }
+
+  get attributes() {
+    return this.openTag.value?.attributes || {};
+  }
+
+  branch() {
+    const { path, openTag, closeTag, properties, resolver, unboundAttributes } = this;
+
+    return this.push(
+      path,
+      openTag,
+      closeTag,
+      new Map(properties), // there is probably a better way
+      resolver.branch(),
+      new Set(unboundAttributes),
+    );
+  }
+
+  accept(node) {
+    this.openTag = node.openTag;
+    this.closeTag = node.closeTag;
+    this.properties = node.properties;
+    this.unboundAttributes = node.unboundAttributes;
+
+    this.resolver.accept(node.resolver);
+
+    return this;
+  }
+};
+
+export const Path = class AgastPath extends WeakStackFrame {
+  static from(context, tag) {
+    return Path.create(context, tag);
+  }
+
+  constructor(context, reference) {
+    super();
+
+    if (reference && reference.type !== 'Reference') {
+      throw new Error('Invalid reference for path');
+    }
+
+    this.context = context;
+    this.reference = reference;
+
+    let skipIdx = 0;
+    let skipAmount = skipAmounts[skipIdx];
+    let skips;
+    while ((this.depth & skipAmount) === skipAmount) {
+      if (!skips) {
+        skips = [];
+        skipsByPath.set(this, skips);
+      }
+
+      skips[skipIdx] = this.at(this.depth - skipAmount);
+
+      skipIdx++;
+      skipAmount = skipAmounts[skipIdx];
+    }
+
+    new PathFacade(this);
+  }
+
+  at(depth) {
+    let parent = this;
+
+    if (depth > this.depth) throw new Error();
+
+    let d = this.depth;
+    for (; d > depth; ) {
+      const skips = skipsByPath.get(this);
+      parent = (skips && findRight(skips, (skip) => d - skip > depth)) || parent.parent;
+      d = parent.depth;
+    }
+    return parent;
+  }
+
+  *parents(includeSelf = false) {
+    if (includeSelf) yield this;
+    let parent = this;
+    while ((parent = parent.parent)) {
+      yield parent;
+    }
+  }
+};

package/lib/state.js

@@ -0,0 +1,199 @@
+import { WeakStackFrame } from '@bablr/weak-stack';
+import { startsDocument } from '@bablr/agast-helpers/stream';
+import { facades, actuals } from './facades.js';
+
+export const StateFacade = class AgastStateFacade {
+  constructor(state) {
+    facades.set(state, this);
+  }
+
+  static from(context) {
+    return State.from(actuals.get(context));
+  }
+
+  get result() {
+    return actuals.get(this).result;
+  }
+
+  get context() {
+    return facades.get(actuals.get(this).context);
+  }
+
+  get path() {
+    return facades.get(actuals.get(this).path);
+  }
+
+  get node() {
+    return actuals.get(this).node;
+  }
+
+  get holding() {
+    return actuals.get(this).holding;
+  }
+
+  get depth() {
+    return actuals.get(this).depth;
+  }
+
+  get ctx() {
+    return this.context;
+  }
+};
+
+export const State = class AgastState extends WeakStackFrame {
+  constructor(
+    context,
+    path = null,
+    node = null,
+    result = null,
+    emitted = null,
+    held = null,
+    expressionDepth = 0,
+  ) {
+    super();
+
+    if (!context) throw new Error('invalid args to tagState');
+
+    this.context = context;
+    this.path = path;
+    this.node = node;
+    this.result = result;
+    this.emitted = emitted;
+    this.held = held;
+    this.expressionDepth = expressionDepth;
+
+    new StateFacade(this);
+  }
+
+  static from(context) {
+    return State.create(context, null);
+  }
+
+  get holding() {
+    return !!this.held;
+  }
+
+  shift() {
+    const { tagNodes, prevTerminals, nextTerminals } = this.context;
+
+    const finishedNode = tagNodes.get(this.result);
+
+    if (!finishedNode.openTag.value.flags.expression) {
+      throw new Error();
+    }
+
+    this.result = prevTerminals.get(finishedNode.openTag);
+
+    nextTerminals.delete(this.result);
+
+    this.held = finishedNode;
+
+    // put the first expression node into the holding register
+  }
+
+  unshift() {
+    const { tagNodes, prevTerminals, nextTerminals } = this.context;
+
+    if (!this.held) {
+      throw new Error('cannot unshift when no expression is in the holding register');
+    }
+
+    nextTerminals.set(this.result, this.held.openTag);
+    prevTerminals.set(this.held.openTag, this.result);
+
+    this.result = this.held.closeTag;
+
+    this.held = null;
+  }
+
+  *emit(terminal, suppressEmit) {
+    const { prevTerminals, nextTerminals, tagNodes } = this.context;
+
+    if (terminal) {
+      if (prevTerminals.has(terminal)) {
+        throw new Error('Double emit');
+      }
+
+      if (
+        this.result?.type === 'Reference' &&
+        !['OpenNodeTag', 'Gap', 'Null'].includes(terminal.type)
+      ) {
+        throw new Error('Bad reference emit');
+      }
+
+      prevTerminals.set(terminal, this.result);
+      if (this.result) {
+        nextTerminals.set(this.result, terminal);
+      }
+
+      this.result = terminal;
+
+      if (!this.emitted) {
+        if (!startsDocument(terminal)) throw new Error();
+        this.emitted = terminal;
+        yield terminal;
+      }
+    }
+
+    if (!this.depth && !this.expressionDepth && !suppressEmit) {
+      let emittable = nextTerminals.get(this.emitted);
+
+      while (
+        emittable &&
+        !(emittable.type === 'OpenNodeTag' && tagNodes.get(emittable).unboundAttributes?.size)
+      ) {
+        yield emittable;
+        this.emitted = emittable;
+        emittable = nextTerminals.get(this.emitted);
+      }
+    }
+
+    return terminal;
+  }
+
+  get ctx() {
+    return this.context;
+  }
+
+  get isGap() {
+    return this.tag.type === 'NodeGapTag';
+  }
+
+  get speculative() {
+    return !!this.parent;
+  }
+
+  branch() {
+    const { context, path, node, result, emitted, held, expressionDepth } = this;
+
+    return this.push(context, path, node.branch(), result, emitted, held, expressionDepth);
+  }
+
+  accept() {
+    const { parent } = this;
+
+    if (!parent) {
+      throw new Error('accepted the root state');
+    }
+
+    parent.node.accept(this.node);
+
+    // emitted isn't used here and probably doesn't need to be part of state
+
+    parent.result = this.result;
+    parent.held = this.held;
+    parent.expressionDepth = this.expressionDepth;
+
+    return parent;
+  }
+
+  reject() {
+    const { parent, context } = this;
+
+    if (!parent) throw new Error('rejected root state');
+
+    context.nextTerminals.delete(parent.result);
+
+    return parent;
+  }
+};

package/lib/symbols.js

@@ -0,0 +1 @@
+export const unbound = Symbol.for('@bablr/unbound');

package/lib/utils/array.js

@@ -0,0 +1,7 @@
+export const findRight = (arr, predicate) => {
+  for (let i = arr.length - 1; i >= 0; i--) {
+    const value = arr[i];
+    if (predicate(value)) return value;
+  }
+  return null;
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@bablr/agast-vm",
+  "description": "A VM providing DOM-like guarantees about agAST trees",
+  "version": "0.1.0",
+  "author": "Conrad Buck<conartist6@gmail.com>",
+  "type": "module",
+  "files": [
+    "lib"
+  ],
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "test": "node ./test/runner.js"
+  },
+  "dependencies": {
+    "@bablr/agast-helpers": "0.1.0",
+    "@bablr/agast-vm-helpers": "0.1.0",
+    "@bablr/coroutine": "0.1.0",
+    "@bablr/weak-stack": "0.1.0"
+  },
+  "devDependencies": {
+    "@bablr/agast-vm-strategy-passthrough": "github:bablr-lang/agast-vm-strategy-passthrough#2bd3a0c7311037af92c5b81941c79161499f6c9e",
+    "@bablr/eslint-config-base": "github:bablr-lang/eslint-config-base#49f5952efed27f94ee9b94340eb1563c440bf64e",
+    "@bablr/strategy_enhancer-debug-log": "0.1.0",
+    "enhanced-resolve": "^5.12.0",
+    "eslint": "^8.32.0",
+    "eslint-import-resolver-enhanced-resolve": "^1.0.5",
+    "eslint-plugin-import": "^2.27.5",
+    "expect": "29.7.0",
+    "iter-tools-es": "^7.3.1",
+    "prettier": "^2.6.2"
+  },
+  "repository": "github:bablr-lang/agast-vm",
+  "homepage": "https://github.com/bablr-lang/agast-vm",
+  "license": "MIT"
+}