vsn 1.0.0 → 1.0.2

package/dist/index.d.cts

@@ -129,10 +129,21 @@ declare class ProgramNode extends BaseNode {
     uses: UseNode[];
     constructor(behaviors: BehaviorNode[], uses?: UseNode[]);
 }
+interface UseFlags {
+    wait?: boolean;
+}
+interface UseFlagArgs {
+    wait?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    };
+}
 declare class UseNode extends BaseNode {
     name: string;
     alias: string;
-    constructor(name: string, alias: string);
+    flags: UseFlags;
+    flagArgs: UseFlagArgs;
+    constructor(name: string, alias: string, flags?: UseFlags, flagArgs?: UseFlagArgs);
 }
 declare class BlockNode extends BaseNode {
     statements: CFSNode[];
@@ -168,8 +179,13 @@ declare class OnBlockNode extends BaseNode {
 declare class AssignmentNode extends BaseNode {
     target: AssignmentTarget;
     value: ExpressionNode;
-    constructor(target: AssignmentTarget, value: ExpressionNode);
+    operator: "=" | "+=" | "-=" | "*=" | "/=";
+    constructor(target: AssignmentTarget, value: ExpressionNode, operator?: "=" | "+=" | "-=" | "*=" | "/=");
     evaluate(context: ExecutionContext): Promise<any>;
+    private applyCompoundAssignment;
+    private resolveAssignmentTarget;
+    private resolveIndexPath;
+    private resolveTargetPath;
     private assignTarget;
 }
 declare class ReturnNode extends BaseNode {
@@ -241,7 +257,7 @@ declare class DeclarationNode extends BaseNode {
 }
 type ExpressionNode = IdentifierExpression | LiteralExpression | TemplateExpression | UnaryExpression | BinaryExpression | MemberExpression | CallExpression | ArrayExpression | ObjectExpression | IndexExpression | FunctionExpression | AwaitExpression | TernaryExpression | DirectiveExpression | QueryExpression;
 type DeclarationTarget = IdentifierExpression | DirectiveExpression;
-type AssignmentTarget = IdentifierExpression | DirectiveExpression | ArrayPattern | ObjectPattern;
+type AssignmentTarget = IdentifierExpression | MemberExpression | IndexExpression | DirectiveExpression | ArrayPattern | ObjectPattern;
 type FunctionParam = {
     name: string;
     defaultValue?: ExpressionNode;
@@ -394,6 +410,7 @@ declare class Parser {
     private parseBehavior;
     private parseSelector;
     private parseUseStatement;
+    private parseUseFlags;
     private wrapErrors;
     private formatError;
     private getLineSnippet;
@@ -435,6 +452,7 @@ declare class Parser {
     private parseCustomFlagArg;
     private isDeclarationStart;
     private isAssignmentStart;
+    private isAssignmentOperatorStart;
     private isCallStart;
     private isExpressionStatementStart;
     private isFunctionDeclarationStart;
@@ -447,6 +465,7 @@ declare class Parser {
     private parseForBlock;
     private parseForClause;
     private parseAssignmentExpression;
+    private parseAssignmentOperator;
     private parseTryBlock;
     private parseConstructBlock;
     private parseDestructBlock;
@@ -532,6 +551,7 @@ declare class Engine {
     private ignoredAdded;
     private diagnostics;
     private logger;
+    private pendingUses;
     constructor(options?: EngineOptions);
     mount(root: HTMLElement): Promise<void>;
     unmount(element: Element): void;
@@ -545,6 +565,8 @@ declare class Engine {
     };
     registerAttributeHandler(handler: AttributeHandler): void;
     private resolveGlobalPath;
+    private waitForUses;
+    private waitForUseGlobal;
     getScope(element: Element, parentScope?: Scope): Scope;
     evaluate(element: Element): void;
     private attachObserver;
@@ -580,6 +602,7 @@ declare class Engine {
     private describeElement;
     private logDiagnostic;
     private emitError;
+    private emitUseError;
     private attachOnHandler;
     private attachBehaviorOnHandler;
     private attachGetHandler;
@@ -627,4 +650,4 @@ declare const VERSION = "0.1.0";
 declare function parseCFS(source: string): ProgramNode;
 declare function autoMount(root?: HTMLElement | Document): Engine | null;
 
-export { type ArrayElement, ArrayExpression, ArrayPattern, type ArrayPatternElement, AssignmentNode, type AssignmentTarget, AwaitExpression, BaseNode, BehaviorNode, BinaryExpression, BlockNode, type CFSNode, CallExpression, type DeclarationFlagArgs, type DeclarationFlags, DeclarationNode, type DeclarationTarget, DirectiveExpression, Engine, type ExecutionContext, type ExpressionNode, ForNode, FunctionDeclarationNode, FunctionExpression, type FunctionParam, IdentifierExpression, IfNode, IndexExpression, Lexer, LiteralExpression, MemberExpression, type ObjectEntry, ObjectExpression, ObjectPattern, type ObjectPatternEntry, OnBlockNode, Parser, type PatternNode, ProgramNode, QueryExpression, RestElement, ReturnNode, SelectorNode, SpreadElement, StateBlockNode, StateEntryNode, TemplateExpression, TernaryExpression, TokenType, TryNode, UnaryExpression, UseNode, VERSION, WhileNode, autoMount, parseCFS };
+export { type ArrayElement, ArrayExpression, ArrayPattern, type ArrayPatternElement, AssignmentNode, type AssignmentTarget, AwaitExpression, BaseNode, BehaviorNode, BinaryExpression, BlockNode, type CFSNode, CallExpression, type DeclarationFlagArgs, type DeclarationFlags, DeclarationNode, type DeclarationTarget, DirectiveExpression, Engine, type ExecutionContext, type ExpressionNode, ForNode, FunctionDeclarationNode, FunctionExpression, type FunctionParam, IdentifierExpression, IfNode, IndexExpression, Lexer, LiteralExpression, MemberExpression, type ObjectEntry, ObjectExpression, ObjectPattern, type ObjectPatternEntry, OnBlockNode, Parser, type PatternNode, ProgramNode, QueryExpression, RestElement, ReturnNode, SelectorNode, SpreadElement, StateBlockNode, StateEntryNode, TemplateExpression, TernaryExpression, TokenType, TryNode, UnaryExpression, type UseFlagArgs, type UseFlags, UseNode, VERSION, WhileNode, autoMount, parseCFS };

package/dist/index.d.ts

@@ -129,10 +129,21 @@ declare class ProgramNode extends BaseNode {
     uses: UseNode[];
     constructor(behaviors: BehaviorNode[], uses?: UseNode[]);
 }
+interface UseFlags {
+    wait?: boolean;
+}
+interface UseFlagArgs {
+    wait?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    };
+}
 declare class UseNode extends BaseNode {
     name: string;
     alias: string;
-    constructor(name: string, alias: string);
+    flags: UseFlags;
+    flagArgs: UseFlagArgs;
+    constructor(name: string, alias: string, flags?: UseFlags, flagArgs?: UseFlagArgs);
 }
 declare class BlockNode extends BaseNode {
     statements: CFSNode[];
@@ -168,8 +179,13 @@ declare class OnBlockNode extends BaseNode {
 declare class AssignmentNode extends BaseNode {
     target: AssignmentTarget;
     value: ExpressionNode;
-    constructor(target: AssignmentTarget, value: ExpressionNode);
+    operator: "=" | "+=" | "-=" | "*=" | "/=";
+    constructor(target: AssignmentTarget, value: ExpressionNode, operator?: "=" | "+=" | "-=" | "*=" | "/=");
     evaluate(context: ExecutionContext): Promise<any>;
+    private applyCompoundAssignment;
+    private resolveAssignmentTarget;
+    private resolveIndexPath;
+    private resolveTargetPath;
     private assignTarget;
 }
 declare class ReturnNode extends BaseNode {
@@ -241,7 +257,7 @@ declare class DeclarationNode extends BaseNode {
 }
 type ExpressionNode = IdentifierExpression | LiteralExpression | TemplateExpression | UnaryExpression | BinaryExpression | MemberExpression | CallExpression | ArrayExpression | ObjectExpression | IndexExpression | FunctionExpression | AwaitExpression | TernaryExpression | DirectiveExpression | QueryExpression;
 type DeclarationTarget = IdentifierExpression | DirectiveExpression;
-type AssignmentTarget = IdentifierExpression | DirectiveExpression | ArrayPattern | ObjectPattern;
+type AssignmentTarget = IdentifierExpression | MemberExpression | IndexExpression | DirectiveExpression | ArrayPattern | ObjectPattern;
 type FunctionParam = {
     name: string;
     defaultValue?: ExpressionNode;
@@ -394,6 +410,7 @@ declare class Parser {
     private parseBehavior;
     private parseSelector;
     private parseUseStatement;
+    private parseUseFlags;
     private wrapErrors;
     private formatError;
     private getLineSnippet;
@@ -435,6 +452,7 @@ declare class Parser {
     private parseCustomFlagArg;
     private isDeclarationStart;
     private isAssignmentStart;
+    private isAssignmentOperatorStart;
     private isCallStart;
     private isExpressionStatementStart;
     private isFunctionDeclarationStart;
@@ -447,6 +465,7 @@ declare class Parser {
     private parseForBlock;
     private parseForClause;
     private parseAssignmentExpression;
+    private parseAssignmentOperator;
     private parseTryBlock;
     private parseConstructBlock;
     private parseDestructBlock;
@@ -532,6 +551,7 @@ declare class Engine {
     private ignoredAdded;
     private diagnostics;
     private logger;
+    private pendingUses;
     constructor(options?: EngineOptions);
     mount(root: HTMLElement): Promise<void>;
     unmount(element: Element): void;
@@ -545,6 +565,8 @@ declare class Engine {
     };
     registerAttributeHandler(handler: AttributeHandler): void;
     private resolveGlobalPath;
+    private waitForUses;
+    private waitForUseGlobal;
     getScope(element: Element, parentScope?: Scope): Scope;
     evaluate(element: Element): void;
     private attachObserver;
@@ -580,6 +602,7 @@ declare class Engine {
     private describeElement;
     private logDiagnostic;
     private emitError;
+    private emitUseError;
     private attachOnHandler;
     private attachBehaviorOnHandler;
     private attachGetHandler;
@@ -627,4 +650,4 @@ declare const VERSION = "0.1.0";
 declare function parseCFS(source: string): ProgramNode;
 declare function autoMount(root?: HTMLElement | Document): Engine | null;
 
-export { type ArrayElement, ArrayExpression, ArrayPattern, type ArrayPatternElement, AssignmentNode, type AssignmentTarget, AwaitExpression, BaseNode, BehaviorNode, BinaryExpression, BlockNode, type CFSNode, CallExpression, type DeclarationFlagArgs, type DeclarationFlags, DeclarationNode, type DeclarationTarget, DirectiveExpression, Engine, type ExecutionContext, type ExpressionNode, ForNode, FunctionDeclarationNode, FunctionExpression, type FunctionParam, IdentifierExpression, IfNode, IndexExpression, Lexer, LiteralExpression, MemberExpression, type ObjectEntry, ObjectExpression, ObjectPattern, type ObjectPatternEntry, OnBlockNode, Parser, type PatternNode, ProgramNode, QueryExpression, RestElement, ReturnNode, SelectorNode, SpreadElement, StateBlockNode, StateEntryNode, TemplateExpression, TernaryExpression, TokenType, TryNode, UnaryExpression, UseNode, VERSION, WhileNode, autoMount, parseCFS };
+export { type ArrayElement, ArrayExpression, ArrayPattern, type ArrayPatternElement, AssignmentNode, type AssignmentTarget, AwaitExpression, BaseNode, BehaviorNode, BinaryExpression, BlockNode, type CFSNode, CallExpression, type DeclarationFlagArgs, type DeclarationFlags, DeclarationNode, type DeclarationTarget, DirectiveExpression, Engine, type ExecutionContext, type ExpressionNode, ForNode, FunctionDeclarationNode, FunctionExpression, type FunctionParam, IdentifierExpression, IfNode, IndexExpression, Lexer, LiteralExpression, MemberExpression, type ObjectEntry, ObjectExpression, ObjectPattern, type ObjectPatternEntry, OnBlockNode, Parser, type PatternNode, ProgramNode, QueryExpression, RestElement, ReturnNode, SelectorNode, SpreadElement, StateBlockNode, StateEntryNode, TemplateExpression, TernaryExpression, TokenType, TryNode, UnaryExpression, type UseFlagArgs, type UseFlags, UseNode, VERSION, WhileNode, autoMount, parseCFS };

package/dist/index.js

@@ -445,10 +445,12 @@ var ProgramNode = class extends BaseNode {
   }
 };
 var UseNode = class extends BaseNode {
-  constructor(name, alias) {
+  constructor(name, alias, flags = {}, flagArgs = {}) {
     super("Use");
     this.name = name;
     this.alias = alias;
+    this.flags = flags;
+    this.flagArgs = flagArgs;
   }
 };
 var BlockNode = class extends BaseNode {
@@ -504,24 +506,117 @@ var OnBlockNode = class extends BaseNode {
   }
 };
 var AssignmentNode = class extends BaseNode {
-  constructor(target, value) {
+  constructor(target, value, operator = "=") {
     super("Assignment");
     this.target = target;
     this.value = value;
+    this.operator = operator;
   }
   async evaluate(context) {
     if (!context.scope || !context.scope.setPath) {
       return void 0;
     }
     const value = await this.value.evaluate(context);
+    if (this.operator !== "=") {
+      return await this.applyCompoundAssignment(context, value);
+    }
     if (this.target instanceof IdentifierExpression && this.target.name.startsWith("root.") && context.rootScope) {
       const path = this.target.name.slice("root.".length);
-      context.rootScope.setPath?.(`self.${path}`, value);
+      context.rootScope.setPath?.(path, value);
       return value;
     }
+    if (this.target instanceof MemberExpression || this.target instanceof IndexExpression) {
+      const resolved = await this.resolveAssignmentTarget(context);
+      if (resolved?.scope?.setPath) {
+        resolved.scope.setPath(resolved.path, value);
+        return value;
+      }
+    }
     this.assignTarget(context, this.target, value);
     return value;
   }
+  async applyCompoundAssignment(context, value) {
+    if (!context.scope || !context.scope.setPath) {
+      return void 0;
+    }
+    const resolved = await this.resolveAssignmentTarget(context);
+    if (!resolved) {
+      throw new Error("Compound assignment requires a simple identifier or member path");
+    }
+    const { scope, path } = resolved;
+    const current = scope?.getPath ? scope.getPath(path) : void 0;
+    let result;
+    if (this.operator === "+=") {
+      result = current + value;
+    } else if (this.operator === "-=") {
+      result = current - value;
+    } else if (this.operator === "*=") {
+      result = current * value;
+    } else {
+      result = current / value;
+    }
+    scope?.setPath?.(path, result);
+    return result;
+  }
+  async resolveAssignmentTarget(context) {
+    if (this.target instanceof IdentifierExpression) {
+      const isRoot = this.target.name.startsWith("root.");
+      const rawPath = isRoot ? this.target.name.slice("root.".length) : this.target.name;
+      if (isRoot) {
+        return { scope: context.scope, path: `root.${rawPath}` };
+      }
+      return { scope: context.scope, path: rawPath };
+    }
+    if (this.target instanceof MemberExpression) {
+      const resolvedPath = this.target.getIdentifierPath();
+      if (!resolvedPath) {
+        return null;
+      }
+      const path = resolvedPath.path;
+      const isRoot = path.startsWith("root.");
+      const rawPath = isRoot ? path.slice("root.".length) : path;
+      if (isRoot) {
+        return { scope: context.scope, path: `root.${rawPath}` };
+      }
+      return { scope: context.scope, path: rawPath };
+    }
+    if (this.target instanceof IndexExpression) {
+      const path = await this.resolveIndexPath(context, this.target);
+      if (!path) {
+        return null;
+      }
+      const isRoot = path.startsWith("root.");
+      const rawPath = isRoot ? path.slice("root.".length) : path;
+      if (isRoot) {
+        return { scope: context.scope, path: `root.${rawPath}` };
+      }
+      return { scope: context.scope, path: rawPath };
+    }
+    return null;
+  }
+  async resolveIndexPath(context, expr) {
+    const base = await this.resolveTargetPath(context, expr.target);
+    if (!base) {
+      return null;
+    }
+    const indexValue = await expr.index.evaluate(context);
+    if (indexValue == null) {
+      return null;
+    }
+    return `${base}.${indexValue}`;
+  }
+  async resolveTargetPath(context, target) {
+    if (target instanceof IdentifierExpression) {
+      return target.name;
+    }
+    if (target instanceof MemberExpression) {
+      return target.getIdentifierPath()?.path ?? null;
+    }
+    if (target instanceof IndexExpression) {
+      return this.resolveIndexPath(context, target);
+    }
+    return null;
+  }
   assignTarget(context, target, value) {
     if (!context.scope || !context.scope.setPath) {
       return;
@@ -1392,11 +1487,46 @@ var Parser = class _Parser {
         this.stream.skipWhitespace();
         alias = this.stream.expect("Identifier" /* Identifier */).value;
       }
+      const { flags, flagArgs } = this.parseUseFlags();
       this.stream.skipWhitespace();
       this.stream.expect("Semicolon" /* Semicolon */);
-      return new UseNode(name, alias);
+      return new UseNode(name, alias, flags, flagArgs);
     });
   }
+  parseUseFlags() {
+    const flags = {};
+    const flagArgs = {};
+    while (true) {
+      this.stream.skipWhitespace();
+      if (this.stream.peek()?.type !== "Bang" /* Bang */) {
+        break;
+      }
+      this.stream.next();
+      const name = this.stream.expect("Identifier" /* Identifier */).value;
+      if (name !== "wait") {
+        throw new Error(`Unknown flag ${name}`);
+      }
+      flags.wait = true;
+      if (this.stream.peek()?.type === "LParen" /* LParen */) {
+        this.stream.next();
+        this.stream.skipWhitespace();
+        const timeoutToken = this.stream.expect("Number" /* Number */);
+        const timeoutMs = Number(timeoutToken.value);
+        let intervalMs;
+        this.stream.skipWhitespace();
+        if (this.stream.peek()?.type === "Comma" /* Comma */) {
+          this.stream.next();
+          this.stream.skipWhitespace();
+          const intervalToken = this.stream.expect("Number" /* Number */);
+          intervalMs = Number(intervalToken.value);
+          this.stream.skipWhitespace();
+        }
+        this.stream.expect("RParen" /* RParen */);
+        flagArgs.wait = { timeoutMs, ...intervalMs !== void 0 ? { intervalMs } : {} };
+      }
+    }
+    return { flags, flagArgs };
+  }
   wrapErrors(fn) {
     try {
       return fn();
@@ -1627,11 +1757,11 @@ ${caret}`;
   parseAssignment() {
     const target = this.parseAssignmentTarget();
     this.stream.skipWhitespace();
-    this.stream.expect("Equals" /* Equals */);
+    const operator = this.parseAssignmentOperator();
     this.stream.skipWhitespace();
     const value = this.parseExpression();
     this.consumeStatementTerminator();
-    return new AssignmentNode(target, value);
+    return new AssignmentNode(target, value, operator);
   }
   parseExpression() {
     return this.parsePipeExpression();
@@ -2213,7 +2343,14 @@ ${caret}`;
       return this.parseObjectPattern();
     }
     if (token.type === "Identifier" /* Identifier */) {
-      return new IdentifierExpression(this.parseIdentifierPath());
+      const expr = this.parseCallExpression();
+      if (expr instanceof CallExpression) {
+        throw new Error("Invalid assignment target CallExpression");
+      }
+      if (expr instanceof IdentifierExpression || expr instanceof MemberExpression || expr instanceof IndexExpression) {
+        return expr;
+      }
+      throw new Error("Invalid assignment target");
     }
     throw new Error(`Invalid assignment target ${token.type}`);
   }
@@ -2492,12 +2629,31 @@ ${caret}`;
       while (this.stream.peekNonWhitespace(index)?.type === "Dot" /* Dot */ && this.stream.peekNonWhitespace(index + 1)?.type === "Identifier" /* Identifier */) {
         index += 2;
       }
-      return this.stream.peekNonWhitespace(index)?.type === "Equals" /* Equals */;
+      while (this.stream.peekNonWhitespace(index)?.type === "LBracket" /* LBracket */) {
+        let depth = 0;
+        while (true) {
+          const token = this.stream.peekNonWhitespace(index);
+          if (!token) {
+            return false;
+          }
+          if (token.type === "LBracket" /* LBracket */) {
+            depth += 1;
+          } else if (token.type === "RBracket" /* RBracket */) {
+            depth -= 1;
+            if (depth === 0) {
+              index += 1;
+              break;
+            }
+          }
+          index += 1;
+        }
+      }
+      return this.isAssignmentOperatorStart(index);
     }
     if (first.type === "At" /* At */ || first.type === "Dollar" /* Dollar */) {
       const second = this.stream.peekNonWhitespace(1);
       const third = this.stream.peekNonWhitespace(2);
-      return second?.type === "Identifier" /* Identifier */ && third?.type === "Equals" /* Equals */;
+      return second?.type === "Identifier" /* Identifier */ && this.isAssignmentOperatorStart(2);
     }
     if (first.type === "LBrace" /* LBrace */ || first.type === "LBracket" /* LBracket */) {
       const stack = [];
@@ -2512,7 +2668,7 @@ ${caret}`;
         } else if (token.type === "RBrace" /* RBrace */ || token.type === "RBracket" /* RBracket */) {
           stack.pop();
           if (stack.length === 0) {
-            return this.stream.peekNonWhitespace(index + 1)?.type === "Equals" /* Equals */;
+            return this.isAssignmentOperatorStart(index + 1);
           }
         }
         index += 1;
@@ -2520,6 +2676,20 @@ ${caret}`;
     }
     return false;
   }
+  isAssignmentOperatorStart(index) {
+    const token = this.stream.peekNonWhitespace(index);
+    if (!token) {
+      return false;
+    }
+    if (token.type === "Equals" /* Equals */) {
+      return true;
+    }
+    if (token.type === "Plus" /* Plus */ || token.type === "Minus" /* Minus */ || token.type === "Star" /* Star */ || token.type === "Slash" /* Slash */) {
+      const next = this.stream.peekNonWhitespace(index + 1);
+      return next?.type === "Equals" /* Equals */;
+    }
+    return false;
+  }
   isCallStart() {
     const first = this.stream.peekNonWhitespace(0);
     if (!first || first.type !== "Identifier" /* Identifier */) {
@@ -2744,10 +2914,35 @@ ${caret}`;
   parseAssignmentExpression() {
     const target = this.parseAssignmentTarget();
     this.stream.skipWhitespace();
-    this.stream.expect("Equals" /* Equals */);
+    const operator = this.parseAssignmentOperator();
     this.stream.skipWhitespace();
     const value = this.parseExpression();
-    return new AssignmentNode(target, value);
+    return new AssignmentNode(target, value, operator);
+  }
+  parseAssignmentOperator() {
+    const next = this.stream.peek();
+    if (!next) {
+      throw new Error("Expected assignment operator");
+    }
+    if (next.type === "Equals" /* Equals */) {
+      this.stream.next();
+      return "=";
+    }
+    if (next.type === "Plus" /* Plus */ || next.type === "Minus" /* Minus */ || next.type === "Star" /* Star */ || next.type === "Slash" /* Slash */) {
+      const op = this.stream.next();
+      this.stream.expect("Equals" /* Equals */);
+      if (op.type === "Plus" /* Plus */) {
+        return "+=";
+      }
+      if (op.type === "Minus" /* Minus */) {
+        return "-=";
+      }
+      if (op.type === "Star" /* Star */) {
+        return "*=";
+      }
+      return "/=";
+    }
+    throw new Error("Expected assignment operator");
   }
   parseTryBlock() {
     this.stream.expect("Try" /* Try */);
@@ -3250,6 +3445,7 @@ var Engine = class _Engine {
   ignoredAdded = /* @__PURE__ */ new WeakMap();
   diagnostics;
   logger;
+  pendingUses = [];
   constructor(options = {}) {
     this.diagnostics = options.diagnostics ?? false;
     this.logger = options.logger ?? console;
@@ -3319,6 +3515,10 @@ var Engine = class _Engine {
   registerBehaviors(source) {
     const program = new Parser(source, { customFlags: new Set(this.flagHandlers.keys()) }).parseProgram();
     for (const use of program.uses) {
+      if (use.flags?.wait) {
+        this.pendingUses.push(this.waitForUseGlobal(use));
+        continue;
+      }
       const value = this.resolveGlobalPath(use.name);
       if (value === void 0) {
         console.warn(`vsn: global '${use.name}' not found`);
@@ -3368,6 +3568,52 @@ var Engine = class _Engine {
     }
     return value;
   }
+  async waitForUses() {
+    while (this.pendingUses.length > 0) {
+      const pending = this.pendingUses;
+      this.pendingUses = [];
+      await Promise.all(pending);
+    }
+  }
+  waitForUseGlobal(use) {
+    const config = use.flagArgs?.wait ?? {};
+    const timeoutMs = config.timeoutMs ?? 1e4;
+    const initialDelayMs = config.intervalMs ?? 100;
+    const maxDelayMs = 1e3;
+    const existing = this.resolveGlobalPath(use.name);
+    if (existing !== void 0) {
+      this.registerGlobal(use.alias, existing);
+      return Promise.resolve();
+    }
+    if (timeoutMs <= 0) {
+      this.emitUseError(use.name, new Error(`vsn: global '${use.name}' not found`));
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      let elapsedMs = 0;
+      let delayMs = initialDelayMs;
+      const check = () => {
+        const value = this.resolveGlobalPath(use.name);
+        if (value !== void 0) {
+          this.registerGlobal(use.alias, value);
+          resolve();
+          return;
+        }
+        if (elapsedMs >= timeoutMs) {
+          this.emitUseError(use.name, new Error(`vsn: global '${use.name}' not found`));
+          resolve();
+          return;
+        }
+        const scheduledDelay = Math.min(delayMs, timeoutMs - elapsedMs);
+        setTimeout(() => {
+          elapsedMs += scheduledDelay;
+          delayMs = Math.min(delayMs * 2, maxDelayMs);
+          check();
+        }, scheduledDelay);
+      };
+      check();
+    });
+  }
   getScope(element, parentScope) {
     const existing = this.scopes.get(element);
     if (existing) {
@@ -3491,6 +3737,7 @@ var Engine = class _Engine {
     }
   }
   async applyBehaviors(root) {
+    await this.waitForUses();
     if (this.behaviorRegistry.length === 0) {
       return;
     }
@@ -3898,6 +4145,19 @@ var Engine = class _Engine {
       })
     );
   }
+  emitUseError(name, error) {
+    const selector = `use:${name}`;
+    this.logger.warn?.("vsn:error", { error, selector });
+    const target = globalThis.document;
+    if (target && typeof target.dispatchEvent === "function") {
+      target.dispatchEvent(
+        new CustomEvent("vsn:error", {
+          detail: { error, selector },
+          bubbles: true
+        })
+      );
+    }
+  }
   attachOnHandler(element, config) {
     const options = this.getListenerOptions(config.modifiers);
     const listenerTarget = config.modifiers?.includes("outside") ? element.ownerDocument : element;