@neocompose/cli 0.31.2 → 0.31.4

package/dist/neo.mjs

@@ -1253,7 +1253,15 @@ function neoProjectPathHasIgnoredDirectory(path) {
 }
 function isNeoVariantFamilyTypeName(name) {
   if (name === NEO_VARIANT_TYPE_NAME) return true;
-  return name === NEO_VARIANT_FOLDER_TYPE_NAME;
+  if (name === NEO_VARIANT_FOLDER_TYPE_NAME) return true;
+  if (name === NEO_LOOKUP_VARIANT_TYPE_NAME) return true;
+  return name === NEO_LOOKUP_VARIANT_FOLDER_TYPE_NAME;
+}
+function isNeoVariantTypeName(name) {
+  return name === NEO_VARIANT_TYPE_NAME || name === NEO_LOOKUP_VARIANT_TYPE_NAME;
+}
+function isNeoVariantFolderTypeName(name) {
+  return name === NEO_VARIANT_FOLDER_TYPE_NAME || name === NEO_LOOKUP_VARIANT_FOLDER_TYPE_NAME;
 }
 function isNeoScriptStructuredLeafTypeName(name) {
   return Object.prototype.hasOwnProperty.call(
@@ -1314,7 +1322,7 @@ function vectorTypes() {
     members: structuredLeafFieldProperties(name)
   }));
 }
-var NEO_PROJECT_IGNORED_DIRECTORY_NAMES, NEOSCRIPT_KEYWORDS, NEOSCRIPT_INFERRED_LOCAL_KEYWORD, NEOSCRIPT_CONSTRUCTOR_KEYWORD, NEOSCRIPT_PRIMITIVE_TYPES, NEOSCRIPT_BUILTIN_TYPES, NEO_VARIANT_TYPE_NAME, NEO_VARIANT_FOLDER_TYPE_NAME, NEO_VARIANT_SCOPE_NAME, NEO_VARIANT_RESERVED_NAME, NEO_VARIANT_FOLDER_PATH_SEPARATOR, NEOSCRIPT_OPERATORS, NEOSCRIPT_STATEMENT_SNIPPETS, STRING_TYPE, INT_TYPE, FLOAT_TYPE, BOOL_TYPE, IMAGE_REF_TYPE, SPRITE_INFO_TYPE, FLOAT_OPTIONAL_TYPE, NEOSCRIPT_STRUCTURED_LEAF_FIELDS, NEOSCRIPT_IMAGE_REGISTRY_TYPE, NEOSCRIPT_AUDIO_CLIP_REGISTRY_TYPE, NEOSCRIPT_PENDING_SYMBOL_ID_PREFIX, REGISTRY_ENTRY_TYPES, NEOSCRIPT_GLOBALS, NEOSCRIPT_SPRITE_INFO_EMPTY_MEMBER_ID, NEOSCRIPT_SPRITE_INFO_EMPTY_VALUE, NEOSCRIPT_BUILTIN_TYPE_SYMBOLS;
+var NEO_PROJECT_IGNORED_DIRECTORY_NAMES, NEOSCRIPT_KEYWORDS, NEOSCRIPT_INFERRED_LOCAL_KEYWORD, NEOSCRIPT_CONSTRUCTOR_KEYWORD, NEOSCRIPT_PRIMITIVE_TYPES, NEOSCRIPT_BUILTIN_TYPES, NEO_VARIANT_TYPE_NAME, NEO_VARIANT_FOLDER_TYPE_NAME, NEO_LOOKUP_VARIANT_TYPE_NAME, NEO_LOOKUP_VARIANT_FOLDER_TYPE_NAME, NEO_VARIANT_SCOPE_NAME, NEO_VARIANT_RESERVED_NAME, NEO_VARIANT_FOLDER_PATH_SEPARATOR, NEOSCRIPT_OPERATORS, NEOSCRIPT_STATEMENT_SNIPPETS, STRING_TYPE, INT_TYPE, FLOAT_TYPE, BOOL_TYPE, IMAGE_REF_TYPE, SPRITE_INFO_TYPE, FLOAT_OPTIONAL_TYPE, NEOSCRIPT_STRUCTURED_LEAF_FIELDS, NEOSCRIPT_IMAGE_REGISTRY_TYPE, NEOSCRIPT_AUDIO_CLIP_REGISTRY_TYPE, NEOSCRIPT_PENDING_SYMBOL_ID_PREFIX, REGISTRY_ENTRY_TYPES, NEOSCRIPT_GLOBALS, NEOSCRIPT_SPRITE_INFO_EMPTY_MEMBER_ID, NEOSCRIPT_SPRITE_INFO_EMPTY_VALUE, NEOSCRIPT_BUILTIN_TYPE_SYMBOLS;
 var init_language_spec = __esm({
   "../packages/neoscript-language/src/language-spec.ts"() {
     "use strict";
@@ -1404,6 +1412,8 @@ var init_language_spec = __esm({
     ];
     NEO_VARIANT_TYPE_NAME = "NeoVariant";
     NEO_VARIANT_FOLDER_TYPE_NAME = "NeoVariantFolder";
+    NEO_LOOKUP_VARIANT_TYPE_NAME = "NeoLookupVariant";
+    NEO_LOOKUP_VARIANT_FOLDER_TYPE_NAME = "NeoLookupVariantFolder";
     NEO_VARIANT_SCOPE_NAME = "Variants";
     NEO_VARIANT_RESERVED_NAME = "Base";
     NEO_VARIANT_FOLDER_PATH_SEPARATOR = "/";
@@ -7928,7 +7938,7 @@ var NEOSCRIPT_COMPILER_REVISION;
 var init_strict_ir = __esm({
   "../packages/neoscript-language/src/strict-ir.ts"() {
     "use strict";
-    NEOSCRIPT_COMPILER_REVISION = 10;
+    NEOSCRIPT_COMPILER_REVISION = 11;
   }
 });
 
@@ -11464,10 +11474,11 @@ var init_strict_resolver = __esm({
        * over {@link NeoScriptTypeRef} already handles a `named` type.
        */
       variantExpression(classType, variant, pos) {
-        const variantType = this.project.typeByName.get(NEO_VARIANT_TYPE_NAME);
+        const typeName = variant?.valueTypeId == null ? NEO_VARIANT_TYPE_NAME : NEO_LOOKUP_VARIANT_TYPE_NAME;
+        const variantType = this.project.typeByName.get(typeName);
         if (variantType === void 0) {
           throw new CompileError(
-            `The seeded '${NEO_VARIANT_TYPE_NAME}' class is not in this project's type table, so '${classType.name}.${NEO_VARIANT_SCOPE_NAME}' cannot be typed.`,
+            `The seeded '${typeName}' class is not in this project's type table, so '${classType.name}.${NEO_VARIANT_SCOPE_NAME}' cannot be typed.`,
             pos
           );
         }
@@ -11475,24 +11486,31 @@ var init_strict_resolver = __esm({
           pointer: {
             type: "variant" /* Variant */,
             classId: classType.id,
-            variantId: variant === null ? null : variant.id
+            variantId: variant === null ? null : variant.id,
+            rowValueId: null
           },
           type: {
             kind: "named",
             typeId: variantType.id,
-            typeArguments: [{ kind: "named", typeId: classType.id }]
+            typeArguments: [
+              { kind: "named", typeId: classType.id },
+              ...variant?.valueTypeId == null ? [] : [{ kind: "named", typeId: variant.valueTypeId }]
+            ]
           }
         };
       }
-      /** The `TObject` of a `NeoVariant<TObject>` type, or null for anything else. */
-      variantTargetClassId(type) {
+      variantTypeInfo(type) {
         if (type.kind !== "named") return null;
         const declared = this.project.typeById.get(type.typeId);
         if (declared === void 0) return null;
-        if (declared.name !== NEO_VARIANT_TYPE_NAME) return null;
+        if (declared.name !== NEO_VARIANT_TYPE_NAME && declared.name !== NEO_LOOKUP_VARIANT_TYPE_NAME)
+          return null;
         const argument2 = type.typeArguments?.[0];
         if (argument2 === void 0 || argument2.kind !== "named") return null;
-        return argument2.typeId;
+        return {
+          targetClassId: argument2.typeId,
+          valueType: declared.name === NEO_LOOKUP_VARIANT_TYPE_NAME ? type.typeArguments?.[1] ?? null : null
+        };
       }
       /**
        * P67 §4.1/§4.2 — `<variant>.Initialize()` and `<source>.ToVariant(<variant>)`.
@@ -11512,23 +11530,35 @@ var init_strict_resolver = __esm({
         }
         const receiver = this.resolveExpression(callee.receiver, scope);
         if (isInitialize) {
-          const targetClassId2 = this.variantTargetClassId(receiver.type);
-          if (targetClassId2 === null) return null;
+          const variantInfo2 = this.variantTypeInfo(receiver.type);
+          if (variantInfo2 === null) return null;
           if (callee.optional === true) {
             throw new CompileError(
               `\`?.\` is not valid on ${NEO_VARIANT_TYPE_NAME}.${VARIANT_INITIALIZE_NAME}; narrow the variant with a null check or force-unwrap it first.`,
               pos
             );
           }
+          const expectedArgCount = variantInfo2.valueType === null ? 0 : 1;
           requireArgCount(
-            `${NEO_VARIANT_TYPE_NAME}.${VARIANT_INITIALIZE_NAME}`,
+            `${variantInfo2.valueType === null ? NEO_VARIANT_TYPE_NAME : NEO_LOOKUP_VARIANT_TYPE_NAME}.${VARIANT_INITIALIZE_NAME}`,
             argumentsList2,
-            0,
+            expectedArgCount,
             pos
           );
+          const row2 = variantInfo2.valueType === null ? null : this.resolveExpression(
+            argumentsList2[0],
+            scope,
+            variantInfo2.valueType
+          );
+          if (row2 !== null && !isNeoScriptTypeAssignable(row2.type, variantInfo2.valueType, this.project)) {
+            throw new CompileError(
+              `Lookup variant row expected ${this.describe(variantInfo2.valueType)} but got ${this.describe(row2.type)}.`,
+              pos
+            );
+          }
           const targetType2 = {
             kind: "named",
-            typeId: targetClassId2
+            typeId: variantInfo2.targetClassId
           };
           return {
             pointer: {
@@ -11537,6 +11567,7 @@ var init_strict_resolver = __esm({
                 type: "variantInitialize" /* VariantInitialize */,
                 info: {
                   variantPointer: receiver.pointer,
+                  ...row2 === null ? {} : { rowPointer: row2.pointer },
                   schemaClassInfo: this.requireClassWireType(targetType2, pos)
                 }
               }
@@ -11558,25 +11589,36 @@ var init_strict_resolver = __esm({
             pos
           );
         }
+        const argumentAst = argumentsList2[0];
+        if (argumentAst === void 0) return null;
+        const argument2 = this.resolveExpression(argumentAst, scope);
+        const variantInfo = this.variantTypeInfo(argument2.type);
+        if (variantInfo === null) {
+          throw new CompileError(
+            `${receiverType.name}.${VARIANT_APPLY_NAME} takes a ${NEO_VARIANT_TYPE_NAME}<${receiverType.name}>, got ${this.describe(argument2.type)}.`,
+            pos
+          );
+        }
         requireArgCount(
           `${receiverType.name}.${VARIANT_APPLY_NAME}`,
           argumentsList2,
-          1,
+          variantInfo.valueType === null ? 1 : 2,
           pos
         );
-        const argumentAst = argumentsList2[0];
-        if (argumentAst === void 0) return null;
-        const argument2 = this.resolveExpression(argumentAst, scope);
-        const targetClassId = this.variantTargetClassId(argument2.type);
-        if (targetClassId === null) {
+        const row = variantInfo.valueType === null ? null : this.resolveExpression(
+          argumentsList2[1],
+          scope,
+          variantInfo.valueType
+        );
+        if (row !== null && !isNeoScriptTypeAssignable(row.type, variantInfo.valueType, this.project)) {
           throw new CompileError(
-            `${receiverType.name}.${VARIANT_APPLY_NAME} takes a ${NEO_VARIANT_TYPE_NAME}<${receiverType.name}>, got ${this.describe(argument2.type)}.`,
+            `Lookup variant row expected ${this.describe(variantInfo.valueType)} but got ${this.describe(row.type)}.`,
             pos
           );
         }
         const targetType = {
           kind: "named",
-          typeId: targetClassId
+          typeId: variantInfo.targetClassId
         };
         if (!isNeoScriptTypeAssignable(receiver.type, targetType, this.project)) {
           throw new CompileError(
@@ -11592,6 +11634,7 @@ var init_strict_resolver = __esm({
               info: {
                 receiverPointer: receiver.pointer,
                 variantPointer: argument2.pointer,
+                ...row === null ? {} : { rowPointer: row.pointer },
                 schemaClassInfo: this.requireClassWireType(receiver.type, pos)
               }
             }
@@ -14772,7 +14815,7 @@ function applyDelimiterToken(stack, token, lambdaBraceOffsets) {
     if (token.text === "{" && lambdaBraceOffsets.has(token.start)) {
       for (let index = stack.length - 1; index >= 0; index--) {
         const candidate = stack[index];
-        if (candidate?.text === "(" && candidate.contributes) {
+        if (candidate?.text === "(" && candidate.contributes && candidate.openingLine === token.range.start.line) {
           restores = candidate;
           break;
         }
@@ -14781,6 +14824,7 @@ function applyDelimiterToken(stack, token, lambdaBraceOffsets) {
     }
     stack.push({
       text: token.text,
+      openingLine: token.range.start.line,
       contributes: true,
       ...restores ? { restores } : {}
     });
@@ -14804,6 +14848,7 @@ function delimiterDepth(stack) {
 function cloneDelimiterStack(stack) {
   const clones = stack.map((frame) => ({
     text: frame.text,
+    openingLine: frame.openingLine,
     contributes: frame.contributes
   }));
   for (let index = 0; index < stack.length; index++) {
@@ -17705,6 +17750,7 @@ var init_project_schema_contract_generated = __esm({
           "collectionValueId",
           "declaredTypeInfo",
           "targetTypeInfo",
+          "variantValueTypeInfo",
           "dialogueGroupId",
           "code",
           "setterCode",
@@ -17756,7 +17802,8 @@ var init_project_schema_contract_generated = __esm({
         "variant-folder": [
           "id",
           "classId",
-          "path"
+          "path",
+          "binding"
         ],
         "interface": [
           "id",
@@ -17967,7 +18014,9 @@ var init_project_schema_contract_generated = __esm({
           "AnimationSegmentTrack",
           "SpriteAnimationSegmentTrack",
           "Variant",
-          "VariantFolder"
+          "VariantFolder",
+          "LookupVariant",
+          "LookupVariantFolder"
         ],
         "NeoTextureType": [
           "Default",
@@ -19832,7 +19881,15 @@ var init_project_source_construction_diagnostics = __esm({
 
 // ../packages/neoscript-language/src/project-source-variants.ts
 function neoVariantConstructionSiteCall(className, argumentNames, initializerNames) {
-  if (className !== NEO_VARIANT_TYPE_NAME) return null;
+  if (className === NEO_LOOKUP_VARIANT_FOLDER_TYPE_NAME) {
+    return {
+      argumentNames: argumentNames.filter(
+        (name) => name !== "collection" && name !== "collectionValue"
+      ),
+      initializerNames
+    };
+  }
+  if (!isNeoVariantTypeName(className)) return null;
   const settled = [...initializerNames];
   const remaining = [];
   for (const name of argumentNames) {
@@ -19851,12 +19908,15 @@ function collectNeoVariantDeclarations(documents) {
     for (const declaration of document.declarations) {
       if (declaration.kind !== "global") continue;
       if (!isNeoVariantFamilyTypeName(declaration.type.name)) continue;
-      const family = declaration.type.name === NEO_VARIANT_TYPE_NAME ? "variant" : "folder";
+      const family = isNeoVariantTypeName(declaration.type.name) ? "variant" : "folder";
       declarations.push({
         uri,
         declaration,
         family,
+        lookup: declaration.type.name === NEO_LOOKUP_VARIANT_TYPE_NAME || declaration.type.name === NEO_LOOKUP_VARIANT_FOLDER_TYPE_NAME,
         owningClassName: declaration.type.typeArguments[0]?.name ?? null,
+        valueClassName: declaration.type.typeArguments[1]?.name ?? null,
+        collectionPath: family === "folder" && declaration.type.name === NEO_LOOKUP_VARIANT_FOLDER_TYPE_NAME ? folderCollectionPath(declaration) : null,
         folderSymbol: neoVariantFolderAnnotationSymbol(declaration.annotations),
         path: family === "folder" ? folderPath(declaration) : null
       });
@@ -19887,10 +19947,32 @@ function neoVariantFolderAnnotationSymbol(annotations) {
 function folderPath(declaration) {
   const expression = parseInitializer(declaration);
   if (expression === null || expression.kind !== "new") return null;
-  const argument2 = expression.args[0];
+  const pathIndex = expression.argumentNames?.findIndex(
+    (name) => name === "path"
+  );
+  const argument2 = expression.args[pathIndex !== void 0 && pathIndex >= 0 ? pathIndex : 0];
   if (argument2 === void 0 || argument2.kind !== "litString") return null;
   return argument2.value;
 }
+function folderCollectionPath(declaration) {
+  const expression = parseInitializer(declaration);
+  if (expression === null || expression.kind !== "new") return null;
+  const index = expression.argumentNames?.findIndex(
+    (name) => name === "collection"
+  );
+  if (index === void 0 || index < 0) return null;
+  const argument2 = expression.args[index];
+  if (argument2 === void 0) return null;
+  const parts = [];
+  let cursor = argument2;
+  while (cursor.kind === "member") {
+    parts.unshift(cursor.name);
+    cursor = cursor.receiver;
+  }
+  if (cursor.kind !== "ident") return null;
+  parts.unshift(cursor.name);
+  return parts.join(".");
+}
 function parseInitializer(declaration) {
   try {
     return unwrapAnnotated(parseExpression(declaration.initializer.text));
@@ -19932,7 +20014,7 @@ function buildNeoVariantScopeIndex(documents) {
     const className = folder.owningClassName;
     if (folder.family !== "folder" || className === null) continue;
     if (folder.path === null) continue;
-    const segments = folder.path.split(NEO_VARIANT_FOLDER_PATH_SEPARATOR);
+    const segments = folder.path.length === 0 ? [] : folder.path.split(NEO_VARIANT_FOLDER_PATH_SEPARATOR);
     segments.forEach((segment, index) => {
       const parent = dottedScope(
         className,
@@ -20077,8 +20159,29 @@ function validateVariantDeclarations(documents) {
     validateScopeName(entry, entry.declaration.name, diagnostics);
   }
   const folderPathsByClass = /* @__PURE__ */ new Map();
+  const rootFolderByClass = /* @__PURE__ */ new Map();
   for (const folder of folders) {
-    validateFolderDeclaration(folder, folderPathsByClass, diagnostics);
+    validateFolderDeclaration(
+      folder,
+      folderPathsByClass,
+      classesByName,
+      diagnostics
+    );
+    if (folder.path === "" && folder.owningClassName !== null) {
+      const prior = rootFolderByClass.get(folder.owningClassName);
+      if (prior !== void 0) {
+        diagnostics.push(
+          variantDiagnostic(
+            folder,
+            folder.declaration.initializer.range,
+            "duplicate-root-lookup-variant-folder",
+            `Class '${folder.owningClassName}' already has root lookup folder '${prior.declaration.name}'; at most one bound folder may enumerate the class root.`
+          )
+        );
+      } else {
+        rootFolderByClass.set(folder.owningClassName, folder);
+      }
+    }
   }
   const foldersBySymbol = /* @__PURE__ */ new Map();
   for (const folder of folders) {
@@ -20125,7 +20228,7 @@ function validateVariantDeclarations(documents) {
   for (const folder of folders) {
     const owningClassName2 = folder.owningClassName;
     if (owningClassName2 === null || folder.path === null) continue;
-    const segments = folder.path.split(NEO_VARIANT_FOLDER_PATH_SEPARATOR);
+    const segments = folder.path.length === 0 ? [] : folder.path.split(NEO_VARIANT_FOLDER_PATH_SEPARATOR);
     segments.forEach((segment, index) => {
       claimFolderSegment(
         owningClassName2,
@@ -20146,12 +20249,49 @@ function validateVariantDeclarations(documents) {
   for (const variant of variants) {
     validateVariantInitializer(variant, diagnostics);
     if (variant.owningClassName === null) continue;
+    if (variant.folderSymbol === null && rootFolderByClass.has(variant.owningClassName)) {
+      diagnostics.push(
+        variantDiagnostic(
+          variant,
+          variant.declaration.nameRange,
+          "root-lookup-variant-folder-conflict",
+          `Class '${variant.owningClassName}' has a root lookup folder, so variants at the class root must belong to that bound folder rather than coexist as plain root variants.`
+        )
+      );
+      continue;
+    }
     const scopePath = resolveVariantScopePath(
       variant,
       foldersBySymbol,
       diagnostics
     );
     if (scopePath === null) continue;
+    const folder = variant.folderSymbol === null ? null : foldersBySymbol.get(
+      `${variant.owningClassName} ${variant.folderSymbol}`
+    ) ?? null;
+    if ((folder?.lookup ?? false) !== variant.lookup) {
+      const argument2 = variantFolderAnnotationArgument(variant);
+      diagnostics.push(
+        variantDiagnostic(
+          variant,
+          argument2?.range ?? variant.declaration.type.range,
+          "variant-folder-family-mismatch",
+          variant.lookup ? `NeoLookupVariant requires a NeoLookupVariantFolder with a collection binding.` : `NeoVariant cannot be placed in a NeoLookupVariantFolder; lookup variants receive the bound row parameter.`
+        )
+      );
+      continue;
+    }
+    if (variant.lookup && folder !== null && variant.valueClassName !== folder.valueClassName) {
+      diagnostics.push(
+        variantDiagnostic(
+          variant,
+          variant.declaration.type.range,
+          "lookup-variant-value-type-mismatch",
+          `Lookup variant '${variant.declaration.name}' uses '${variant.valueClassName ?? "<missing>"}', but folder '${folder.declaration.name}' expects '${folder.valueClassName ?? "<missing>"}'.`
+        )
+      );
+      continue;
+    }
     claim(
       variant.owningClassName,
       scopePath,
@@ -20273,13 +20413,14 @@ function validateVariantInitializer(variant, diagnostics) {
 function validateInitialize(variant, argument2, diagnostics) {
   const lambda = unwrapAnnotated(argument2);
   if (lambda.kind !== "lambda") return;
-  if (lambda.params.length > 0) {
+  const expected = variant.lookup ? 1 : 0;
+  if (lambda.params.length !== expected) {
     diagnostics.push(
       variantDiagnostic(
         variant,
         variant.declaration.initializer.range,
         "variant-initialize-arity",
-        `A variant's initialize delegate takes no parameters and returns ${variant.owningClassName ?? "the target class"}; it was declared with ${lambda.params.length}.`
+        variant.lookup ? `A lookup variant's initialize delegate takes exactly one ${variant.valueClassName ?? "row"} parameter and returns ${variant.owningClassName ?? "the target class"}; it was declared with ${lambda.params.length}.` : `A variant's initialize delegate takes no parameters and returns ${variant.owningClassName ?? "the target class"}; it was declared with ${lambda.params.length}.`
       )
     );
   }
@@ -20299,13 +20440,14 @@ function validateInitialize(variant, argument2, diagnostics) {
 function validateApply(variant, argument2, diagnostics) {
   const lambda = unwrapAnnotated(argument2);
   if (lambda.kind !== "lambda") return;
-  if (lambda.params.length !== 1) {
+  const expected = variant.lookup ? 2 : 1;
+  if (lambda.params.length !== expected) {
     diagnostics.push(
       variantDiagnostic(
         variant,
         variant.declaration.initializer.range,
         "variant-apply-arity",
-        `A variant's apply delegate takes exactly one ${variant.owningClassName ?? "target class"} parameter; it was declared with ${lambda.params.length}.`
+        variant.lookup ? `A lookup variant's apply delegate takes exactly (${variant.owningClassName ?? "source"}, ${variant.valueClassName ?? "row"}); it was declared with ${lambda.params.length} parameters.` : `A variant's apply delegate takes exactly one ${variant.owningClassName ?? "target class"} parameter; it was declared with ${lambda.params.length}.`
       )
     );
   }
@@ -20322,7 +20464,7 @@ function validateApply(variant, argument2, diagnostics) {
     )
   );
 }
-function validateFolderDeclaration(folder, folderPathsByClass, diagnostics) {
+function validateFolderDeclaration(folder, folderPathsByClass, classesByName, diagnostics) {
   if (folder.path === null) {
     diagnostics.push(
       variantDiagnostic(
@@ -20334,7 +20476,43 @@ function validateFolderDeclaration(folder, folderPathsByClass, diagnostics) {
     );
     return;
   }
+  if (folder.path.length === 0 && !folder.lookup) {
+    diagnostics.push(
+      variantDiagnostic(
+        folder,
+        folder.declaration.initializer.range,
+        "invalid-variant-folder-path",
+        "Only a bound NeoLookupVariantFolder may use the class-root path ''."
+      )
+    );
+    return;
+  }
+  if (folder.lookup) {
+    const [className, memberName, ...rest] = folder.collectionPath?.split(".") ?? [];
+    const collectionMember = className !== void 0 && memberName !== void 0 && rest.length === 0 ? classesByName.get(className)?.members.find((member) => member.name === memberName) : void 0;
+    const entryType = collectionMember?.type.name === "List" ? collectionMember.type.typeArguments[0]?.name : void 0;
+    if (entryType === void 0) {
+      diagnostics.push(
+        variantDiagnostic(
+          folder,
+          folder.declaration.initializer.range,
+          "invalid-lookup-variant-folder-collection",
+          `Lookup variant folder '${folder.declaration.name}' requires collection: Class.ListMember whose entries are Class values.`
+        )
+      );
+    } else if (entryType !== folder.valueClassName) {
+      diagnostics.push(
+        variantDiagnostic(
+          folder,
+          folder.declaration.type.range,
+          "lookup-folder-value-type-mismatch",
+          `Lookup variant folder '${folder.declaration.name}' declares TValue '${folder.valueClassName ?? "<missing>"}', but collection '${folder.collectionPath}' contains '${entryType}'.`
+        )
+      );
+    }
+  }
   for (const segment of folder.path.split(NEO_VARIANT_FOLDER_PATH_SEPARATOR)) {
+    if (segment.length === 0) continue;
     validateScopeName(folder, segment, diagnostics);
   }
   if (folder.owningClassName === null) return;
@@ -20386,7 +20564,7 @@ function validateOwningClass(entry, classesByName, diagnostics) {
         entry,
         entry.declaration.type.range,
         "variant-target-missing",
-        `${entry.declaration.type.name} names the class it belongs to as its single type argument.`
+        `${entry.declaration.type.name} names the class it belongs to as its first type argument.`
       )
     );
     return;
@@ -20459,7 +20637,7 @@ function validateVariantTypePositions(documents, diagnostics) {
   }
 }
 function reportVariantTypePositions(uri, type, diagnostics, root = "nested") {
-  if (type.name === NEO_VARIANT_TYPE_NAME && root === "reference") {
+  if (isNeoVariantTypeName(type.name) && root === "reference") {
     for (const argument2 of type.typeArguments) {
       reportVariantTypePositions(uri, argument2, diagnostics);
     }
@@ -20481,7 +20659,7 @@ function reportVariantTypePositions(uri, type, diagnostics, root = "nested") {
   }
 }
 function variantTypePositionMessage(typeName, root) {
-  if (typeName === NEO_VARIANT_FOLDER_TYPE_NAME) {
+  if (isNeoVariantFolderTypeName(typeName)) {
     return `'${typeName}' is reference-only: it declares variant folders as top-level globals and is never a member, entry, parameter, or generic binding type.`;
   }
   return `'${typeName}' cannot be nested inside another type. A variant reference is a member, parameter, or return type in its own right (P67 \xA76); wrapping it in a collection, lookup, or 'Reference' asks for an instance of a class that has none.`;
@@ -21178,7 +21356,7 @@ function validateProjectSourceSemantics(documents) {
 }
 function annotationContextForDeclaration(declaration) {
   if (declaration.kind === "class") return { kind: "class", declaration };
-  if (declaration.kind === "global" && declaration.type.name === NEO_VARIANT_TYPE_NAME) {
+  if (declaration.kind === "global" && isNeoVariantTypeName(declaration.type.name)) {
     return { kind: "variantGlobal", declaration };
   }
   return { kind: "schema" };
@@ -21843,10 +22021,11 @@ function fieldsForAnnotation(name, context, environment) {
 }
 function settingsFields(context) {
   if (context.kind === "variantGlobal") {
+    const lookup = context.declaration.type.name !== NEO_VARIANT_TYPE_NAME;
     return [
       {
         name: NEO_VARIANT_FOLDER_SETTING,
-        type: `${NEO_VARIANT_FOLDER_TYPE_NAME}<${context.declaration.type.typeArguments[0]?.name ?? "TObject"}>`
+        type: lookup ? `${NEO_LOOKUP_VARIANT_FOLDER_TYPE_NAME}<${context.declaration.type.typeArguments[0]?.name ?? "TObject"}, ${context.declaration.type.typeArguments[1]?.name ?? "TValue"}>` : `${NEO_VARIANT_FOLDER_TYPE_NAME}<${context.declaration.type.typeArguments[0]?.name ?? "TObject"}>`
       }
     ];
   }
@@ -22347,7 +22526,7 @@ function validateStatements(statements, returnType, scope, environment, uri, ran
   }
 }
 function validateExpression(expression, expected, scope, environment, uri, range2, diagnostics, anchor) {
-  if (expected?.name === NEO_VARIANT_TYPE_NAME) {
+  if (expected !== void 0 && isNeoVariantTypeName(expected.name)) {
     validateVariantValuedExpression(
       expression,
       expected,
@@ -22565,6 +22744,9 @@ function validateExpression(expression, expected, scope, environment, uri, range
     const overload = declaration && declaration.constructors.length > 0 ? matchingDeclaredConstructor(declaration, expression.argumentNames) : null;
     expression.args.forEach((argument2, index) => {
       const named = expression.argumentNames?.[index];
+      if (declaration.name === NEO_LOOKUP_VARIANT_FOLDER_TYPE_NAME && named === "collection") {
+        return;
+      }
       const parameter4 = named ? (declaration.headerParameters ?? []).find(
         (candidate) => candidate.name === named
       ) ?? overload?.parameters.find((candidate) => candidate.name === named) : void 0;
@@ -22573,9 +22755,10 @@ function validateExpression(expression, expected, scope, environment, uri, range
         (candidate) => candidate.name === (variantMember ?? named)
       ) : fields[index];
       const expectedType = parameter4?.type ?? field?.type;
+      const expectedSemanticType = declaration.name === NEO_LOOKUP_VARIANT_FOLDER_TYPE_NAME && named === "collectionValue" ? { name: "string" } : expectedType ? semanticType(expectedType) : void 0;
       validateExpression(
         argument2,
-        expectedType ? semanticType(expectedType) : void 0,
+        expectedSemanticType,
         scope,
         environment,
         uri,
@@ -23424,7 +23607,11 @@ function compileProjectSourceBodies(documents) {
       if (declaration.kind !== "class") continue;
       const owner = graph.declarationsByName.get(declaration.name);
       if (!owner) continue;
-      const declaringType = declarationTypeRef(owner, declaration);
+      const declaringType = declarationTypeRef(
+        owner,
+        declaration,
+        graph.typeIdsByName
+      );
       diagnostics.push(
         ...declaredConstructorOverloadDiagnostics(
           uri,
@@ -23740,16 +23927,22 @@ function buildProjectGraph(documents) {
         const target = declarationsByName.get(base.name);
         return target?.declaration.kind === "interface" ? [target.id] : [];
       }) : [];
-      const typeParameters = classDeclaration ? classDeclaration.genericParameters.map((parameter4) => ({
-        id: sourceIdentity(
-          parameter4.annotations,
-          `generic:${info.id}:${parameter4.name}`
-        ),
-        name: parameter4.name,
-        type: { kind: "primitive", name: "unknown" },
-        location: location(info.uri, parameter4.range),
-        selectionLocation: location(info.uri, parameter4.nameRange)
-      })) : [];
+      const typeParameters = classDeclaration ? classDeclaration.genericParameters.map((parameter4) => {
+        const type = sourceTypeParameterRef(
+          parameter4,
+          info,
+          typeIds,
+          /* @__PURE__ */ new Set(),
+          false
+        );
+        return {
+          id: type.id,
+          name: parameter4.name,
+          type,
+          location: location(info.uri, parameter4.range),
+          selectionLocation: location(info.uri, parameter4.nameRange)
+        };
+      }) : [];
       return {
         id: info.id,
         name: info.declaration.name,
@@ -24087,50 +24280,49 @@ function projectRootType(documents, declarations) {
   }
   return { id: "builtin:Root", name: "Root", kind: "synthetic", members };
 }
-function sourceTypeRef(type, owner, typeIds) {
+function sourceTypeRef(type, owner, typeIds, resolvingTypeParameters = /* @__PURE__ */ new Set()) {
   const nullable = type.nullable || void 0;
+  const resolveNested = (nested) => sourceTypeRef(nested, owner, typeIds, resolvingTypeParameters);
   if (type.name === "List") {
     return {
       kind: "list",
-      elementType: type.typeArguments[0] ? sourceTypeRef(type.typeArguments[0], owner, typeIds) : { kind: "primitive", name: "unknown" },
+      elementType: type.typeArguments[0] ? resolveNested(type.typeArguments[0]) : { kind: "primitive", name: "unknown" },
       ...nullable ? { nullable } : {}
     };
   }
   if (type.name === "Set") {
     return {
       kind: "set",
-      elementType: type.typeArguments[0] ? sourceTypeRef(type.typeArguments[0], owner, typeIds) : { kind: "primitive", name: "unknown" },
+      elementType: type.typeArguments[0] ? resolveNested(type.typeArguments[0]) : { kind: "primitive", name: "unknown" },
       ...nullable ? { nullable } : {}
     };
   }
   if (type.name === "Dictionary") {
     return {
       kind: "dictionary",
-      keyType: type.typeArguments[0] ? sourceTypeRef(type.typeArguments[0], owner, typeIds) : { kind: "primitive", name: "unknown" },
-      valueType: type.typeArguments[1] ? sourceTypeRef(type.typeArguments[1], owner, typeIds) : { kind: "primitive", name: "unknown" },
+      keyType: type.typeArguments[0] ? resolveNested(type.typeArguments[0]) : { kind: "primitive", name: "unknown" },
+      valueType: type.typeArguments[1] ? resolveNested(type.typeArguments[1]) : { kind: "primitive", name: "unknown" },
       ...nullable ? { nullable } : {}
     };
   }
   if (type.name === "NeoDelegate") {
-    const returnType = type.typeArguments[0] ? sourceTypeRef(type.typeArguments[0], owner, typeIds) : { kind: "primitive", name: "unknown" };
+    const returnType = type.typeArguments[0] ? resolveNested(type.typeArguments[0]) : { kind: "primitive", name: "unknown" };
     return {
       kind: "delegate",
       returnType,
-      parameterTypes: type.typeArguments.slice(1).map((argument2) => sourceTypeRef(argument2, owner, typeIds)),
+      parameterTypes: type.typeArguments.slice(1).map(resolveNested),
       ...nullable ? { nullable } : {}
     };
   }
   if (type.name === "NeoAction") {
     return {
       kind: "action",
-      parameterTypes: type.typeArguments.map(
-        (argument2) => sourceTypeRef(argument2, owner, typeIds)
-      )
+      parameterTypes: type.typeArguments.map(resolveNested)
     };
   }
   if (type.name === "Reference" && type.typeArguments[0]) {
     return {
-      ...sourceTypeRef(type.typeArguments[0], owner, typeIds),
+      ...resolveNested(type.typeArguments[0]),
       ...nullable ? { nullable } : {}
     };
   }
@@ -24139,16 +24331,13 @@ function sourceTypeRef(type, owner, typeIds) {
       (candidate) => candidate.name === type.name
     );
     if (parameter4) {
-      return {
-        kind: "typeParameter",
-        id: sourceIdentity(
-          parameter4.annotations,
-          `generic:${owner.id}:${parameter4.name}`
-        ),
-        name: parameter4.name,
-        ownerClassId: owner.id,
-        ...nullable ? { nullable } : {}
-      };
+      return sourceTypeParameterRef(
+        parameter4,
+        owner,
+        typeIds,
+        resolvingTypeParameters,
+        nullable === true
+      );
     }
   }
   const primitive3 = primitiveTypeName(type.name);
@@ -24164,27 +24353,37 @@ function sourceTypeRef(type, owner, typeIds) {
     kind: "named",
     typeId: targetId ?? `builtin:${type.name}`,
     ...type.typeArguments.length ? {
-      typeArguments: type.typeArguments.map(
-        (argument2) => sourceTypeRef(argument2, owner, typeIds)
-      )
+      typeArguments: type.typeArguments.map(resolveNested)
     } : {},
     ...nullable ? { nullable } : {}
   };
 }
-function declarationTypeRef(info, declaration) {
+function sourceTypeParameterRef(parameter4, owner, typeIds, resolvingTypeParameters, nullable) {
+  const id2 = sourceIdentity(
+    parameter4.annotations,
+    `generic:${owner.id}:${parameter4.name}`
+  );
+  const next = new Set(resolvingTypeParameters);
+  next.add(id2);
+  const constraintSource = parameter4.constraint;
+  const constraint = constraintSource !== void 0 && !resolvingTypeParameters.has(id2) ? sourceTypeRef(constraintSource, owner, typeIds, next) : void 0;
+  return {
+    kind: "typeParameter",
+    id: id2,
+    name: parameter4.name,
+    ownerClassId: owner.id,
+    ...constraint === void 0 ? {} : { constraint },
+    ...nullable ? { nullable: true } : {}
+  };
+}
+function declarationTypeRef(info, declaration, typeIds) {
   return {
     kind: "named",
     typeId: info.id,
     ...declaration.genericParameters.length ? {
-      typeArguments: declaration.genericParameters.map((parameter4) => ({
-        kind: "typeParameter",
-        id: sourceIdentity(
-          parameter4.annotations,
-          `generic:${info.id}:${parameter4.name}`
-        ),
-        name: parameter4.name,
-        ownerClassId: info.id
-      }))
+      typeArguments: declaration.genericParameters.map(
+        (parameter4) => sourceTypeParameterRef(parameter4, info, typeIds, /* @__PURE__ */ new Set(), false)
+      )
     } : {}
   };
 }
@@ -27537,10 +27736,18 @@ function projectConstructorArgumentCompletions(analysis, document, position) {
       used.add(token.text);
     }
   }
-  const fields = graphConstructorNamedArguments(typeName) ?? declaredConstructorNamedArguments(analysis, typeName, used);
+  const fields = lookupVariantFolderArgumentFields(typeName) ?? graphConstructorNamedArguments(typeName) ?? declaredConstructorNamedArguments(analysis, typeName, used);
   if (!fields) return null;
   return fields.filter((field) => !used.has(field.name));
 }
+function lookupVariantFolderArgumentFields(typeName) {
+  if (typeName !== NEO_LOOKUP_VARIANT_FOLDER_TYPE_NAME) return null;
+  return [
+    { name: "path", type: "string" },
+    { name: "collection", type: "List<TValue>" },
+    { name: "collectionValue", type: "Reference<List<TValue>>" }
+  ];
+}
 function declaredConstructorNamedArguments(analysis, typeName, used) {
   const contract = classConstructionContract(
     projectConstructionIndex(analysis),
@@ -27673,7 +27880,7 @@ function projectDottedPathBefore(document, position) {
 }
 function projectVariantFolderCompletions(analysis, source, position) {
   const declaration = source.declarations.find(
-    (candidate) => candidate.kind === "global" && candidate.type.name === NEO_VARIANT_TYPE_NAME && candidate.annotations.some(
+    (candidate) => candidate.kind === "global" && isNeoVariantTypeName(candidate.type.name) && candidate.annotations.some(
       (annotation2) => rangeContains(annotation2.range, position)
     )
   );
@@ -28836,6 +29043,8 @@ function projectConstructorTypeName(analysis, document, callee, beforeCallee) {
   return contextualConstructorType(analysis, document, callee.range.start);
 }
 function projectConstructorParameters(analysis, typeName) {
+  const lookup = lookupVariantFolderArgumentFields(typeName);
+  if (lookup !== null) return lookup;
   const declaration = findTypeDeclaration(analysis, typeName);
   return declaration ? declarationConstructorParameters(declaration) : graphConstructorParameters(typeName);
 }
@@ -32970,6 +33179,7 @@ var init_document_contracts = __esm({
           "collectionValueId",
           "declaredTypeInfo",
           "targetTypeInfo",
+          "variantValueTypeInfo",
           "dialogueGroupId",
           "code",
           "setterCode",
@@ -33085,10 +33295,12 @@ var init_document_contracts = __esm({
         }
       },
       "variant-folder": {
-        authored: ["id", "classId", "path"],
+        authored: ["id", "classId", "path", "binding"],
         derived: [],
         volatile: ["projectId", "createdAt", "updatedAt"],
-        normalization: {}
+        normalization: {
+          binding: "missingIsNull"
+        }
       },
       interface: {
         authored: [
@@ -34425,6 +34637,11 @@ function memberFromDocument(record3, members, owners, classNames, context) {
         field("targetTypeInfo", void 0),
         record3,
         "targetTypeInfo"
+      ),
+      valueType: field("variantValueTypeInfo", null) === null ? null : documentTypeToManifest(
+        field("variantValueTypeInfo", void 0),
+        record3,
+        "variantValueTypeInfo"
       )
     };
   }
@@ -34572,6 +34789,7 @@ function memberToDocumentFields(member, baseData3) {
   }
   if (member.kind === "variant") {
     fields.targetTypeInfo = manifestTypeToDocument(member.targetType);
+    fields.variantValueTypeInfo = member.valueType === null ? null : manifestTypeToDocument(member.valueType);
   }
   if (member.kind === "generic") {
     fields.genericParamId = member.genericParamId;
@@ -35109,7 +35327,9 @@ function isSchemaSystemMetadata(value) {
     "animationSegmentTrack",
     "spriteAnimationSegmentTrack",
     "variant",
-    "variantFolder"
+    "variantFolder",
+    "lookupVariant",
+    "lookupVariantFolder"
   ]);
   return typeof value.kind === "string" && kinds.has(value.kind) && (value.worldKind === null || typeof value.worldKind === "string" && worlds.has(value.worldKind));
 }
@@ -36382,6 +36602,7 @@ function variantFromDocument(record3, context) {
 }
 function variantFolderFromDocument(record3, context) {
   const data = normalizeDocumentFields("variant-folder", record3.data);
+  const binding = variantFolderBinding(data.binding, record3);
   return {
     id: record3.recordId,
     source: context.sourceForRecord(
@@ -36390,9 +36611,21 @@ function variantFolderFromDocument(record3, context) {
       "variantFolder"
     ),
     classId: requiredString(data, "classId", record3),
-    path: requiredString(data, "path", record3)
+    path: variantFolderPath(data.path, binding, record3),
+    binding
   };
 }
+function variantFolderPath(value, binding, record3) {
+  if (typeof value !== "string") {
+    throw new Error(`Variant folder ${record3.recordId} has a non-string path.`);
+  }
+  if (value.length === 0 && binding === null) {
+    throw new Error(
+      `Variant folder ${record3.recordId} may use the class-root path only with a collection binding.`
+    );
+  }
+  return value;
+}
 function variantFolderId(value, record3) {
   if (value === null) return null;
   if (typeof value !== "string") {
@@ -36420,9 +36653,27 @@ function variantFolderToDocument(folder) {
   return omitUndefined({
     id: folder.id,
     classId: folder.classId,
-    path: folder.path
+    path: folder.path,
+    binding: folder.binding
   });
 }
+function variantFolderBinding(value, record3) {
+  if (value === null || value === void 0) return null;
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(
+      `Variant folder ${record3.recordId} has an invalid binding.`
+    );
+  }
+  const binding = value;
+  const collectionMemberId = binding.collectionMemberId;
+  const collectionValueId = binding.collectionValueId;
+  if (typeof collectionMemberId !== "string" || collectionMemberId.length === 0 || typeof collectionValueId !== "string" || collectionValueId.length === 0) {
+    throw new Error(
+      `Variant folder ${record3.recordId} binding requires collectionMemberId and collectionValueId.`
+    );
+  }
+  return { collectionMemberId, collectionValueId };
+}
 var VARIANT_SCHEMA_RECORD_ADAPTER, VARIANT_FOLDER_SCHEMA_RECORD_ADAPTER;
 var init_variant = __esm({
   "src/project-manifest/record-adapters/variant.ts"() {
@@ -36761,10 +37012,33 @@ function assertVariant(value, path) {
   nonEmptyString(variant.folderId, `${path}.folderId`);
 }
 function assertVariantFolder(value, path) {
-  const folder = objectAt(value, path, ["id", "source", "classId", "path"]);
+  const folder = objectAt(value, path, [
+    "id",
+    "source",
+    "classId",
+    "path",
+    "binding"
+  ]);
   assertIdentity2(folder, path, "variantFolder");
   nonEmptyString(folder.classId, `${path}.classId`);
-  nonEmptyString(folder.path, `${path}.path`);
+  if (typeof folder.path !== "string")
+    invalid(`${path}.path`, "must be a string.");
+  if (folder.binding === null) {
+    nonEmptyString(folder.path, `${path}.path`);
+    return;
+  }
+  const binding = objectAt(folder.binding, `${path}.binding`, [
+    "collectionMemberId",
+    "collectionValueId"
+  ]);
+  nonEmptyString(
+    binding.collectionMemberId,
+    `${path}.binding.collectionMemberId`
+  );
+  nonEmptyString(
+    binding.collectionValueId,
+    `${path}.binding.collectionValueId`
+  );
 }
 function assertConstructorBaseArgument(value, path) {
   const argument2 = objectAt(value, path, ["name", "code"]);
@@ -37702,6 +37976,19 @@ function assertMember2(value, path) {
         `a variant member targets a class or a generic parameter, not ${JSON.stringify(targetKind)}.`
       );
     }
+    if (member.valueType !== null) {
+      assertType2(member.valueType, `${path}.valueType`);
+      const valueKind = requireRecord(
+        member.valueType,
+        `${path}.valueType`
+      ).kind;
+      if (valueKind !== "class") {
+        invalid(
+          `${path}.valueType.kind`,
+          "a lookup variant member's TValue must be a collection entry class."
+        );
+      }
+    }
     return;
   }
   if (kind === "generic") {
@@ -38903,7 +39190,9 @@ var init_validate = __esm({
       "animationSegmentTrack",
       "spriteAnimationSegmentTrack",
       "variant",
-      "variantFolder"
+      "variantFolder",
+      "lookupVariant",
+      "lookupVariantFolder"
     ]);
     MEMBER_COMMON_KEYS = [
       "id",
@@ -38959,7 +39248,7 @@ var init_validate = __esm({
       action: ["arguments"],
       // P67 §6: a variant member carries only its declared target; the selection
       // itself is an ordinary `defaultValue`.
-      variant: ["targetType"]
+      variant: ["targetType", "valueType"]
     };
     PRIMITIVE_TYPE_KINDS = /* @__PURE__ */ new Set([
       "null",
@@ -39705,7 +39994,9 @@ var init_world_system_kinds_generated = __esm({
       AnimationSegmentTrack: "animationSegmentTrack",
       SpriteAnimationSegmentTrack: "spriteAnimationSegmentTrack",
       Variant: "variant",
-      VariantFolder: "variantFolder"
+      VariantFolder: "variantFolder",
+      LookupVariant: "lookupVariant",
+      LookupVariantFolder: "lookupVariantFolder"
     };
     NEO_WORLD_SYSTEM_CLASS_KIND_VALUES = new Set(
       Object.values(NeoWorldSystemClassKind)
@@ -40462,6 +40753,8 @@ function isNSFunctionVariantInitialize(value) {
   const info = v.info;
   if (typeof info !== "object" || info === null) return false;
   if (!isNSPointer(info.variantPointer)) return false;
+  if (info.rowPointer !== void 0 && !isNSPointer(info.rowPointer))
+    return false;
   return isNSTypeInfoClass(info.schemaClassInfo) && info.schemaClassInfo.required;
 }
 function isNSFunctionVariantApply(value) {
@@ -40471,6 +40764,8 @@ function isNSFunctionVariantApply(value) {
   if (typeof info !== "object" || info === null) return false;
   if (!isNSPointer(info.receiverPointer)) return false;
   if (!isNSPointer(info.variantPointer)) return false;
+  if (info.rowPointer !== void 0 && !isNSPointer(info.rowPointer))
+    return false;
   return isNSTypeInfoClass(info.schemaClassInfo) && info.schemaClassInfo.required;
 }
 function isNSFunctionClassConstructor(value) {
@@ -41619,6 +41914,9 @@ function isMemberListBase(value) {
   if (v.listKind !== void 0 && v.listKind !== null && !isListKind(v.listKind)) {
     return false;
   }
+  if (v.valueTypeInfo !== void 0 && v.valueTypeInfo !== null && (!isNSTypeInfo(v.valueTypeInfo) || v.valueTypeInfo.type !== 7 /* Class */)) {
+    return false;
+  }
   if (v.indexes !== void 0 && v.indexes !== null) {
     if (!Array.isArray(v.indexes)) return false;
     const seenIndexKeys = /* @__PURE__ */ new Set();
@@ -42018,10 +42316,14 @@ function isMemberFunctionRefBase(value) {
 function isVariantRefValue(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
   const record3 = value;
-  if (!hasExactKeys(record3, ["classId", "variantId"])) return false;
+  const keys = Object.hasOwn(record3, "rowValueId") ? ["classId", "variantId", "rowValueId"] : ["classId", "variantId"];
+  if (!hasExactKeys(record3, keys)) return false;
   if (!isString(record3.classId)) return false;
   if (record3.classId.length === 0) return false;
-  if (record3.variantId === null) return true;
+  if (record3.rowValueId !== void 0 && record3.rowValueId !== null && (!isString(record3.rowValueId) || record3.rowValueId.length === 0)) {
+    return false;
+  }
+  if (record3.variantId === null) return record3.rowValueId == null;
   if (!isString(record3.variantId)) return false;
   return record3.variantId.length > 0;
 }
@@ -44031,6 +44333,222 @@ var init_world_system_classes_generated = __esm({
           }
         ],
         worldKind: "variantFolder"
+      },
+      {
+        classId: "system_38ddb113-5df8-4385-9324-1cecf7f3bd99",
+        name: "NeoLookupVariant",
+        docsText: "A NeoObject configuration parameterized by a row from a bound collection.",
+        isAbstract: false,
+        isSealed: true,
+        hiddenInMemberSelector: true,
+        allowedStorage: "immutable" /* Immutable */,
+        requiredConstructorId: "system_d29a7faa-7196-52ab-ac8f-0f4d6230cc0e",
+        constructors: [
+          {
+            constructorId: "system_d29a7faa-7196-52ab-ac8f-0f4d6230cc0e",
+            argumentTypes: [
+              {
+                name: "initialize",
+                type: 25,
+                required: true,
+                returnTypeInfo: {
+                  type: 21,
+                  required: true,
+                  ownerClassId: "system_38ddb113-5df8-4385-9324-1cecf7f3bd99",
+                  genericParamId: "system_1d416b31-fa1a-4bbe-a716-249eb855712d"
+                },
+                argumentTypes: [
+                  {
+                    type: 21,
+                    required: true,
+                    ownerClassId: "system_38ddb113-5df8-4385-9324-1cecf7f3bd99",
+                    genericParamId: "system_4031d9da-38a7-4332-892e-b3fd8282378a"
+                  }
+                ]
+              },
+              {
+                name: "apply",
+                type: 25,
+                required: false,
+                returnTypeInfo: { type: "Void", required: true },
+                argumentTypes: [
+                  {
+                    type: 21,
+                    required: true,
+                    ownerClassId: "system_38ddb113-5df8-4385-9324-1cecf7f3bd99",
+                    genericParamId: "system_1d416b31-fa1a-4bbe-a716-249eb855712d"
+                  },
+                  {
+                    type: 21,
+                    required: true,
+                    ownerClassId: "system_38ddb113-5df8-4385-9324-1cecf7f3bd99",
+                    genericParamId: "system_4031d9da-38a7-4332-892e-b3fd8282378a"
+                  }
+                ],
+                defaultValue: { value: null }
+              },
+              {
+                name: "overrides",
+                type: 21,
+                required: false,
+                ownerClassId: "system_38ddb113-5df8-4385-9324-1cecf7f3bd99",
+                genericParamId: "system_1d416b31-fa1a-4bbe-a716-249eb855712d",
+                defaultValue: { value: null }
+              },
+              {
+                name: "childOverrides",
+                type: 6,
+                required: false,
+                entryTypeInfo: {
+                  type: 7,
+                  required: true,
+                  classId: "system_e2e88eba-5335-4a16-9dcf-2c0e1951e8bd",
+                  typeArguments: {
+                    "system_de23448a-45be-4e3f-8965-072a545e08f0": {
+                      type: 7,
+                      required: true,
+                      classId: "system_61b30a92-90dc-4bf8-8503-ee4f6414effc"
+                    }
+                  }
+                },
+                defaultValue: { value: null }
+              }
+            ],
+            code: null
+          }
+        ],
+        genericParams: [
+          {
+            id: "system_1d416b31-fa1a-4bbe-a716-249eb855712d",
+            name: "TObject",
+            constraintClassWorldKind: "object"
+          },
+          { id: "system_4031d9da-38a7-4332-892e-b3fd8282378a", name: "TValue" }
+        ],
+        schemaFields: [
+          {
+            memberId: "system_ddff93cb-2e4e-43ed-ae1a-b523eb53e0e9",
+            memberKind: "delegate",
+            defaultInitializerCode: "initialize",
+            returnTypeInfo: {
+              type: 21,
+              required: true,
+              ownerClassId: "system_38ddb113-5df8-4385-9324-1cecf7f3bd99",
+              genericParamId: "system_1d416b31-fa1a-4bbe-a716-249eb855712d"
+            },
+            argumentTypes: [
+              {
+                type: 21,
+                required: true,
+                ownerClassId: "system_38ddb113-5df8-4385-9324-1cecf7f3bd99",
+                genericParamId: "system_4031d9da-38a7-4332-892e-b3fd8282378a",
+                name: "p1"
+              }
+            ],
+            required: true,
+            schemaKey: "Initialize"
+          },
+          {
+            memberId: "system_42da97f6-c714-47b6-b750-232232ec4f83",
+            memberKind: "delegate",
+            defaultInitializerCode: "apply",
+            returnTypeInfo: { type: "Void", required: true },
+            argumentTypes: [
+              {
+                type: 21,
+                required: true,
+                ownerClassId: "system_38ddb113-5df8-4385-9324-1cecf7f3bd99",
+                genericParamId: "system_1d416b31-fa1a-4bbe-a716-249eb855712d",
+                name: "p1"
+              },
+              {
+                type: 21,
+                required: true,
+                ownerClassId: "system_38ddb113-5df8-4385-9324-1cecf7f3bd99",
+                genericParamId: "system_4031d9da-38a7-4332-892e-b3fd8282378a",
+                name: "p2"
+              }
+            ],
+            required: false,
+            schemaKey: "Apply"
+          },
+          {
+            memberId: "system_070ae22a-7603-48cf-94e2-528d88b72825",
+            memberKind: "generic",
+            defaultInitializerCode: "overrides",
+            genericParamId: "system_1d416b31-fa1a-4bbe-a716-249eb855712d",
+            partial: true,
+            required: false,
+            schemaKey: "Overrides"
+          },
+          {
+            memberId: "system_ae23d675-2531-44a2-b792-8a121d99aec2",
+            memberKind: "list",
+            defaultInitializerCode: "childOverrides",
+            entryMemberId: "system_d922e73b-d2d8-5b2e-b333-75b80ca9c3ab",
+            required: false,
+            schemaKey: "ChildOverrides"
+          }
+        ],
+        supportingFields: [
+          {
+            memberId: "system_d922e73b-d2d8-5b2e-b333-75b80ca9c3ab",
+            memberKind: "class",
+            schemaClassWorldKind: "animationChildOverride",
+            classArguments: {
+              "system_de23448a-45be-4e3f-8965-072a545e08f0": {
+                kind: "member",
+                memberId: "system_788215c7-3dcf-5df0-8810-79f08da02c66"
+              }
+            },
+            required: true,
+            schemaKey: "__ChildOverrideEntry"
+          },
+          {
+            memberId: "system_788215c7-3dcf-5df0-8810-79f08da02c66",
+            memberKind: "class",
+            schemaClassWorldKind: "objectBase",
+            required: true,
+            schemaKey: "__NeoObjectBaseTypeArgument"
+          }
+        ],
+        worldKind: "lookupVariant"
+      },
+      {
+        classId: "system_b3bd4d91-6e03-4034-b201-05afd78f7c72",
+        name: "NeoLookupVariantFolder",
+        docsText: "A variant folder whose variants receive a row from a bound collection.",
+        isAbstract: false,
+        isSealed: true,
+        hiddenInMemberSelector: true,
+        allowedStorage: "immutable" /* Immutable */,
+        requiredConstructorId: "system_b0239c15-91f3-5ddb-bd4e-43fd86e42e50",
+        constructors: [
+          {
+            constructorId: "system_b0239c15-91f3-5ddb-bd4e-43fd86e42e50",
+            argumentTypes: [{ name: "path", type: 3, required: true }],
+            code: null
+          }
+        ],
+        genericParams: [
+          {
+            id: "system_a5488f2b-966e-4643-93df-71995c9c24ad",
+            name: "TObject",
+            constraintClassWorldKind: "object"
+          },
+          { id: "system_39544f5d-e527-44fb-96b7-f584b7cd1a25", name: "TValue" }
+        ],
+        schemaFields: [
+          {
+            memberId: "system_d36ebea5-151f-4d9d-95f2-28d8cfb05870",
+            memberKind: "string",
+            defaultInitializerCode: "path",
+            localizable: false,
+            required: true,
+            schemaKey: "Path"
+          }
+        ],
+        worldKind: "lookupVariantFolder"
       }
     ];
   }
@@ -45161,6 +45679,28 @@ var init_member_kinds_db_response = __esm({
 });
 
 // ../src/models/members/unordered-list-membership.ts
+function unorderedListEntryIds(values, listValue2, membershipIndex) {
+  if (!Array.isArray(listValue2.value)) return [];
+  if (membershipIndex !== void 0) {
+    return [...membershipIndex.get(listValue2.id) ?? []];
+  }
+  const ids = [];
+  for (const candidate of values) {
+    if (candidate.containerId === listValue2.id) ids.push(candidate.id);
+  }
+  ids.sort();
+  return ids;
+}
+function listEntryIdsForValue(member, listValue2, values) {
+  if (listValue2.value === null) return [];
+  if (listKindOf(member) === "unordered") {
+    return unorderedListEntryIds(values, listValue2);
+  }
+  if (!Array.isArray(listValue2.value)) return [];
+  return listValue2.value.filter(
+    (entry) => typeof entry === "string"
+  );
+}
 var init_unordered_list_membership = __esm({
   "../src/models/members/unordered-list-membership.ts"() {
     "use strict";
@@ -47267,6 +47807,11 @@ function primitiveFallbackValue(document, member) {
     return { value: { listeners: [] } };
   }
   if (isMemberVariantBase(member)) {
+    if (member.valueTypeInfo != null) {
+      throw new Error(
+        `Cannot create default value: lookup variant member "${member.name}" requires an authored lookup-variant selection.`
+      );
+    }
     if (!member.required) return { value: null };
     if (member.targetTypeInfo.type !== 7 /* Class */) {
       throw new Error(
@@ -47274,7 +47819,11 @@ function primitiveFallbackValue(document, member) {
       );
     }
     return {
-      value: { classId: member.targetTypeInfo.classId, variantId: null }
+      value: {
+        classId: member.targetTypeInfo.classId,
+        variantId: null,
+        rowValueId: null
+      }
     };
   }
   if (member.kind === 21 /* Generic */) {
@@ -49209,7 +49758,7 @@ function renderMemberType(context, member, enclosingClassId) {
       );
       break;
     case "variant":
-      value = `NeoVariant<${renderType(context, member.targetType)}>`;
+      value = member.valueType === null ? `NeoVariant<${renderType(context, member.targetType)}>` : `${NEO_LOOKUP_VARIANT_TYPE_NAME}<${renderType(context, member.targetType)}, ${renderType(context, member.valueType)}>`;
       break;
   }
   if ((member.kind === "class" || member.kind === "generic") && member.partial === true) {
@@ -49842,7 +50391,7 @@ function emitVariantFiles(context, variantInitializers) {
   const foldersById = new Map(
     manifest.variantFolders.map((folder) => [folder.id, folder])
   );
-  const pathFor = (className, folderPath3) => folderPath3 === null ? `Variants/${className}.neo` : `Variants/${className}/${folderPath3}.neo`;
+  const pathFor = (className, folderPath3) => folderPath3 === null || folderPath3.length === 0 ? `Variants/${className}.neo` : `Variants/${className}/${folderPath3}.neo`;
   const fileFor = (className, folder) => {
     const path = pathFor(className, folder?.path ?? null);
     const existing = files.get(path);
@@ -49873,7 +50422,7 @@ function emitVariantFiles(context, variantInitializers) {
     const declarations = [];
     const recordKeys = [];
     if (file.folder !== null) {
-      declarations.push(emitVariantFolder(className, file.folder));
+      declarations.push(emitVariantFolder(context, className, file.folder));
       recordKeys.push(`variant-folder:${file.folder.id}`);
     }
     const ordered = [...file.variants].sort(
@@ -49895,11 +50444,27 @@ function emitVariantFiles(context, variantInitializers) {
 `, recordKeys };
   });
 }
-function emitVariantFolder(className, folder) {
+function emitVariantFolder(context, className, folder) {
   for (const segment of folder.path.split("/")) {
+    if (segment.length === 0) continue;
     assertIdentifier(segment, "variant folder path segment");
   }
-  return `${id(folder.id)}NeoVariantFolder<${className}> ${variantFolderSymbol(folder)} = new(${quote(folder.path)});`;
+  if (folder.binding === null) {
+    return `${id(folder.id)}NeoVariantFolder<${className}> ${variantFolderSymbol(folder)} = new(${quote(folder.path)});`;
+  }
+  const valueType = renderLookupEntryType(
+    context,
+    folder.binding.collectionMemberId
+  );
+  const rootPath = context.collectionValuePaths.get(
+    folder.binding.collectionValueId
+  );
+  const collectionValue = rootPath === void 0 ? `Reference(id: ${quote(folder.binding.collectionValueId)})` : `Reference(${rootPath})`;
+  return `${id(folder.id)}${NEO_LOOKUP_VARIANT_FOLDER_TYPE_NAME}<${className}, ${valueType}> ${variantFolderSymbol(folder)} = new(
+  path: ${quote(folder.path)},
+  collection: ${qualifiedMember(context, folder.binding.collectionMemberId)},
+  collectionValue: ${collectionValue},
+);`;
 }
 function emitVariant(context, className, variant, folder, variantInitializers) {
   assertIdentifier(variant.name, "variant");
@@ -49913,11 +50478,13 @@ function emitVariant(context, className, variant, folder, variantInitializers) {
     id(variant.id).trimEnd(),
     ...folder === null ? [] : [`@settings(folder: ${variantFolderSymbol(folder)})`]
   ];
+  const type = folder?.binding == null ? `NeoVariant<${className}>` : `${NEO_LOOKUP_VARIANT_TYPE_NAME}<${className}, ${renderLookupEntryType(context, folder.binding.collectionMemberId)}>`;
   return `${annotations.join("\n")}
-NeoVariant<${className}> ${variant.name} =
+${type} ${variant.name} =
 ${indentNeoSourceNonEmptyLines(initializer, 2)};`;
 }
 function variantFolderSymbol(folder) {
+  if (folder.path.length === 0) return "Root";
   return neoVariantFolderSymbol(folder.path);
 }
 function assertUniqueVariantFolderSymbols(folders) {
@@ -50031,7 +50598,16 @@ function renderVariantSelection(context, member, value) {
       `Variant member ${member.name} selects variant ${JSON.stringify(variantId)}, which this project does not declare.`
     );
   }
-  return path;
+  const rowValueId = value.rowValueId;
+  if (rowValueId === null || rowValueId === void 0) return path;
+  if (typeof rowValueId !== "string") {
+    throw new Error(
+      `Variant member ${member.name} stores a malformed rowValueId.`
+    );
+  }
+  const rootPath = context.collectionValuePaths.get(rowValueId);
+  const reference2 = rootPath === void 0 ? `Reference(id: ${quote(rowValueId)})` : `Reference(${rootPath})`;
+  return `${path}.Bind(${reference2})`;
 }
 var SPECIALIZED_RELATION_PROPERTIES;
 var init_emitter = __esm({
@@ -55540,7 +56116,7 @@ function lowerFieldMember(context, ownerClass, declaration, id2, commonInput, ba
       }))
     };
   }
-  if (name === NEO_VARIANT_TYPE_NAME) {
+  if (name === NEO_VARIANT_TYPE_NAME || name === NEO_LOOKUP_VARIANT_TYPE_NAME) {
     if (partial) {
       throw new Error("Partial<T> requires a Class or Class generic target.");
     }
@@ -55551,7 +56127,8 @@ function lowerFieldMember(context, ownerClass, declaration, id2, commonInput, ba
         context,
         requiredTypeArgument(fieldType, 0),
         ownerClass
-      )
+      ),
+      valueType: name === NEO_LOOKUP_VARIANT_TYPE_NAME ? lowerType(context, requiredTypeArgument(fieldType, 1), ownerClass) : null
     };
   }
   if (name === "NeoAction") {
@@ -56429,7 +57006,7 @@ function lowerExpressionValue(context, expression, declaredExpected, ownerClass,
   if (expected.name === "NeoAction") {
     return lowerActionDefault(context, expression, ownerClass, path);
   }
-  if (expected.name === NEO_VARIANT_TYPE_NAME) {
+  if (expected.name === NEO_VARIANT_TYPE_NAME || expected.name === NEO_LOOKUP_VARIANT_TYPE_NAME) {
     return lowerVariantDefault(context, expression, expected, path);
   }
   switch (expression.kind) {
@@ -57420,7 +57997,22 @@ function lowerVariantDefault(context, expression, expected, path) {
     }
     return null;
   }
-  const segments = variantPathSegments2(unwrapped);
+  let candidate = unwrapped;
+  let rowValueId = null;
+  if (candidate.kind === "call" && candidate.callee.kind === "member" && candidate.callee.name === "Bind") {
+    if (expected.name !== NEO_VARIANT_TYPE_NAME) {
+      throw new Error(
+        `${path} cannot Bind a row to NeoLookupVariant; keep the lookup handle unbound.`
+      );
+    }
+    const row = candidate.args[0];
+    if (row === void 0) {
+      throw new Error(`${path}.Bind requires one Reference row.`);
+    }
+    rowValueId = lowerVariantBindingReference(context, row, path);
+    candidate = candidate.callee.receiver;
+  }
+  const segments = variantPathSegments2(candidate);
   if (segments === null) {
     throw new Error(
       `${path} must be a variant path such as Tree.${NEO_VARIANT_SCOPE_NAME}.ChoppedTree (or Tree.${NEO_VARIANT_SCOPE_NAME}.${NEO_VARIANT_RESERVED_NAME} for the class itself). A variant is a record, so Reference(...) cannot name one.`
@@ -57433,7 +58025,59 @@ function lowerVariantDefault(context, expression, expected, path) {
       `${path} names variant path ${JSON.stringify(spelled)}, which this project does not declare.`
     );
   }
-  return { classId: target.classId, variantId: target.variantId };
+  if (target.valueClassId !== null && expected.name === NEO_VARIANT_TYPE_NAME) {
+    if (rowValueId === null) {
+      throw new Error(
+        `${path} selects a lookup variant and must bind a collection row with .Bind(Reference(...)).`
+      );
+    }
+  } else if (rowValueId !== null) {
+    throw new Error(`${path} can bind a row only to a lookup variant.`);
+  }
+  if (expected.name === NEO_LOOKUP_VARIANT_TYPE_NAME && target.valueClassId === null) {
+    throw new Error(
+      `${path} expects NeoLookupVariant but selects a plain NeoVariant.`
+    );
+  }
+  return {
+    classId: target.classId,
+    variantId: target.variantId,
+    rowValueId
+  };
+}
+function lowerVariantBindingReference(context, expression, path) {
+  const id2 = referenceId(expressionSource(expression));
+  if (id2 === null) {
+    throw new Error(
+      `${path}.Bind requires Reference(id: ...) or Reference(root....).`
+    );
+  }
+  const prefix = `${PENDING_ID_PREFIX}root-path:`;
+  if (!id2.startsWith(prefix)) return id2;
+  const rootPath = id2.slice(prefix.length);
+  const target = context.rootValueTargetsByPath.get(rootPath);
+  if (target === void 0) {
+    throw new Error(`${path}.Bind references unknown row path ${rootPath}.`);
+  }
+  return target.valueId;
+}
+function expressionSource(expression) {
+  if (expression.kind === "annotated") {
+    return expressionSource(expression.expression);
+  }
+  if (expression.kind === "litString") return JSON.stringify(expression.value);
+  if (expression.kind === "ident") return expression.name;
+  if (expression.kind === "member") {
+    return `${expressionSource(expression.receiver)}.${expression.name}`;
+  }
+  if (expression.kind === "call") {
+    const args = expression.args.map((argument2, index) => {
+      const name = expression.argumentNames?.[index];
+      return `${name == null ? "" : `${name}: `}${expressionSource(argument2)}`;
+    });
+    return `${expressionSource(expression.callee)}(${args.join(", ")})`;
+  }
+  throw new Error("Unsupported Reference expression in variant binding.");
 }
 function variantPathSegments2(expression) {
   const segments = [];
@@ -57617,7 +58261,12 @@ function isNeoClassVariantFolder(value) {
   const v = value;
   if (!isNonEmptyString2(v.id)) return false;
   if (!isNonEmptyString2(v.classId)) return false;
-  if (!isNonEmptyString2(v.path)) return false;
+  if (typeof v.path !== "string") return false;
+  if (v.binding === void 0 || v.binding === null) return v.path.length > 0;
+  if (typeof v.binding !== "object" || Array.isArray(v.binding)) return false;
+  const binding = v.binding;
+  if (!isNonEmptyString2(binding.collectionMemberId)) return false;
+  if (!isNonEmptyString2(binding.collectionValueId)) return false;
   return true;
 }
 var init_variants = __esm({
@@ -57627,14 +58276,19 @@ var init_variants = __esm({
 });
 
 // ../src/models/variants/variant-member.ts
-function neoVariantSystemClass(classes) {
+function neoVariantSystemClass(classes, lookup = false) {
   const declared = classes.find(
-    (item) => item.system?.worldKind === NeoWorldSystemClassKind.Variant
+    (item) => item.system?.worldKind === (lookup ? NeoWorldSystemClassKind.LookupVariant : NeoWorldSystemClassKind.Variant)
   );
   if (declared === void 0) return null;
   const targetParamId = declared.genericParams?.[0]?.id;
   if (targetParamId === void 0) return null;
-  return { classId: declared.id, targetParamId };
+  const valueParamId = declared.genericParams?.[1]?.id;
+  return {
+    classId: declared.id,
+    targetParamId,
+    ...valueParamId === void 0 ? {} : { valueParamId }
+  };
 }
 var init_variant_member = __esm({
   "../src/models/variants/variant-member.ts"() {
@@ -57876,11 +58530,25 @@ function variantProjection(context) {
       (folder) => [folder.id, folder.path]
     )
   );
+  const foldersById = new Map(
+    (context.variantFolders ?? []).map(
+      (folder) => [folder.id, folder]
+    )
+  );
+  const membersById = new Map(
+    context.vm.members.map((member) => [member.id, member])
+  );
   return variants.map((variant) => ({
     id: variant.id,
     classId: variant.classId,
     name: variant.name,
-    folder: variant.folderId === null ? null : pathByFolderId.get(variant.folderId) ?? null
+    folder: variant.folderId === null ? null : pathByFolderId.get(variant.folderId) ?? null,
+    ...(() => {
+      const folder = variant.folderId === null ? void 0 : foldersById.get(variant.folderId);
+      const collection = folder?.binding == null ? void 0 : membersById.get(folder.binding.collectionMemberId);
+      const entry = isMemberListBase(collection) ? membersById.get(collection.entryMemberId) : void 0;
+      return isMemberClassBase(entry) ? { valueTypeId: entry.classId } : {};
+    })()
   }));
 }
 function virtualCSharpIdentifier(value) {
@@ -58658,7 +59326,10 @@ function memberRuntimeType(record3, context, seen = /* @__PURE__ */ new Set(), g
     }
     case 27 /* Variant */: {
       if (!isMemberVariantBase(member)) return UNKNOWN_TYPE2;
-      const systemClass = neoVariantSystemClass(context.vm.classes);
+      const systemClass = neoVariantSystemClass(
+        context.vm.classes,
+        member.valueTypeInfo != null
+      );
       if (systemClass === null) return UNKNOWN_TYPE2;
       const target = toLanguageType(
         member.targetTypeInfo,
@@ -58669,7 +59340,16 @@ function memberRuntimeType(record3, context, seen = /* @__PURE__ */ new Set(), g
         kind: "named",
         typeId: systemClass.classId,
         nullable: !required2,
-        typeArguments: [target]
+        typeArguments: [
+          target,
+          ...member.valueTypeInfo == null ? [] : [
+            toLanguageType(
+              member.valueTypeInfo,
+              context,
+              genericEnvironment
+            )
+          ]
+        ]
       };
     }
     case 22 /* Interface */:
@@ -64699,7 +65379,11 @@ function evalPointer(pointer, scope, ctx) {
       return row.value;
     }
     case "variant" /* variant */:
-      return { classId: pointer.classId, variantId: pointer.variantId };
+      return {
+        classId: pointer.classId,
+        variantId: pointer.variantId,
+        rowValueId: pointer.rowValueId ?? null
+      };
     case "staticMember" /* staticMember */:
       return evalStaticMember(pointer.memberId, ctx);
     case "keyOf" /* keyOf */:
@@ -68508,13 +69192,22 @@ function readVariantSelection(value, label) {
     throw new NSGetterRuntimeError(`${label} carries no class id.`);
   }
   const variantId = record3.variantId;
+  const rowValueId = record3.rowValueId;
+  if (rowValueId !== void 0 && rowValueId !== null && (typeof rowValueId !== "string" || rowValueId.length === 0)) {
+    throw new NSGetterRuntimeError(
+      `${label} carries a malformed lookup row id.`
+    );
+  }
   if (variantId === null || variantId === void 0) {
-    return { classId, variantId: null };
+    if (rowValueId != null) {
+      throw new NSGetterRuntimeError(`${label} cannot bind a row to Base.`);
+    }
+    return { classId, variantId: null, rowValueId: null };
   }
   if (typeof variantId !== "string" || variantId.length === 0) {
     throw new NSGetterRuntimeError(`${label} carries a malformed variant id.`);
   }
-  return { classId, variantId };
+  return { classId, variantId, rowValueId: rowValueId ?? null };
 }
 function resolveVariantGraph(selection2, ctx) {
   const variantId = selection2.variantId;
@@ -68557,9 +69250,67 @@ function resolveVariantGraph(selection2, ctx) {
     variantId,
     name: record3.name,
     targetClassId: record3.classId,
-    root
+    root,
+    binding: record3.folderId === null ? null : (ctx.vm.variantFolders ?? []).find(
+      (folder) => folder.id === record3.folderId
+    )?.binding ?? null
   };
 }
+function resolveVariantRowParameter(args) {
+  const { graph, selection: selection2, explicitPointer, scope, ctx } = args;
+  const binding = graph.binding;
+  if (binding === null) {
+    if (explicitPointer !== void 0 || selection2.rowValueId !== null) {
+      throw new NSGetterRuntimeError(
+        `Variant '${graph.name}' is not collection-bound and cannot receive a row.`
+      );
+    }
+    return [];
+  }
+  let rowId = selection2.rowValueId;
+  let rowValue;
+  if (explicitPointer !== void 0) {
+    rowValue = evalPointer(explicitPointer, scope, ctx);
+    if (typeof rowValue === "object" && rowValue !== null) {
+      rowId = trackedRowForValueReference(rowValue, ctx)?.id ?? null;
+    }
+  }
+  if (rowId === null) {
+    throw new NSGetterRuntimeError(
+      `Lookup variant '${graph.name}' requires a row from its bound collection.`
+    );
+  }
+  const row = evalValueById(
+    ctx,
+    rowId,
+    ctx.__runtimeSessionValues,
+    ctx.__valueOverlay
+  );
+  if (row === null) {
+    throw new NSGetterRuntimeError(
+      `Lookup variant '${graph.name}' references missing row '${rowId}'.`
+    );
+  }
+  const collection = evalValueById(
+    ctx,
+    binding.collectionValueId,
+    ctx.__runtimeSessionValues,
+    ctx.__valueOverlay
+  );
+  const isOrderedEntry = Array.isArray(collection?.value) ? collection.value.includes(rowId) : false;
+  const isUnorderedEntry = row.containerId === binding.collectionValueId;
+  if (!isOrderedEntry && !isUnorderedEntry) {
+    throw new NSGetterRuntimeError(
+      `Lookup variant '${graph.name}' row '${rowId}' is not an entry of collection '${binding.collectionValueId}'.`
+    );
+  }
+  if (explicitPointer !== void 0 && rowValue !== row.value) {
+    throw new NSGetterRuntimeError(
+      `Lookup variant '${graph.name}' received a value that does not resolve to bound row '${rowId}'.`
+    );
+  }
+  return [row.value];
+}
 function invokeVariantClosure(args) {
   const { closureValueId, ctx, label, lexicalThis, parameters } = args;
   if (typeof closureValueId !== "string" || closureValueId.length === 0) {
@@ -68743,6 +69494,13 @@ function evalVariantInitialize(info, scope, ctx) {
     );
   }
   const graph = resolveVariantGraph(selection2, ctx);
+  const parameters = resolveVariantRowParameter({
+    graph,
+    selection: selection2,
+    explicitPointer: info.rowPointer,
+    scope,
+    ctx
+  });
   const closeFrame = pushConstructionFrame(ctx, `Variants.${graph.name}`);
   try {
     const instance = invokeVariantClosure({
@@ -68750,7 +69508,7 @@ function evalVariantInitialize(info, scope, ctx) {
       ctx,
       label: `Variant '${graph.name}' Initialize`,
       lexicalThis: null,
-      parameters: []
+      parameters
     });
     if (instance === null || instance === void 0) {
       throw new NSGetterRuntimeError(
@@ -68777,6 +69535,13 @@ function evalVariantApply(info, scope, ctx) {
   );
   if (selection2.variantId === null) return receiver;
   const graph = resolveVariantGraph(selection2, ctx);
+  const rowParameters = resolveVariantRowParameter({
+    graph,
+    selection: selection2,
+    explicitPointer: info.rowPointer,
+    scope,
+    ctx
+  });
   const applyValueId = graph.root.Apply;
   if (typeof applyValueId === "string" && applyValueId.length > 0) {
     invokeVariantClosure({
@@ -68784,7 +69549,7 @@ function evalVariantApply(info, scope, ctx) {
       ctx,
       label: `Variant '${graph.name}' Apply`,
       lexicalThis: null,
-      parameters: [receiver]
+      parameters: [receiver, ...rowParameters]
     });
   }
   applyVariantDeclarativeHalves(receiver, graph, ctx);
@@ -73573,17 +74338,17 @@ var init_lower_relations = __esm({
 function lowerVariants(context, analysis) {
   const folders = lowerVariantFolders(context, analysis);
   const foldersBySymbol = new Map(
-    analysis.variants.globals.filter((global) => global.type.name === NEO_VARIANT_FOLDER_TYPE_NAME).map(
+    analysis.variants.globals.filter((global) => isNeoVariantFolderTypeName(global.type.name)).map(
       (global) => [
         folderSymbolKey(owningClassName(global), global.name),
-        variantRecordId(global, NEO_VARIANT_FOLDER_TYPE_NAME)
+        variantRecordId(global, global.type.name)
       ]
     )
   );
   const variants = variantGlobals(analysis).map((global) => {
     const className = owningClassName(global);
     const classId = requiredName2(context.classIdsByName, className, "class");
-    const variantId = variantRecordId(global, NEO_VARIANT_TYPE_NAME);
+    const variantId = variantRecordId(global, global.type.name);
     return {
       id: variantId,
       source: sourceIdentity2(global, "variant", global.name),
@@ -73613,6 +74378,14 @@ function variantValueBindingsV4(manifest, analysis) {
         variantId: variant.id,
         targetClassId: variant.classId,
         targetClassName: requiredClassName2(classNames, variant.classId),
+        variantTypeName: global.type.name,
+        valueClassId: global.type.name === NEO_LOOKUP_VARIANT_TYPE_NAME ? requiredName2(
+          new Map(
+            manifest.classes.map((entry) => [entry.name, entry.id])
+          ),
+          valueClassName(global),
+          "class"
+        ) : null,
         valueId: variant.valueId,
         initializer: global.initializer,
         source: global.source,
@@ -73632,17 +74405,18 @@ function requiredClassName2(classNames, classId) {
 }
 function variantGlobals(analysis) {
   return analysis.variants.globals.filter(
-    (global) => global.type.name === NEO_VARIANT_TYPE_NAME
+    (global) => isNeoVariantTypeName(global.type.name)
   );
 }
 function lowerVariantFolders(context, analysis) {
-  return analysis.variants.globals.filter((global) => global.type.name === NEO_VARIANT_FOLDER_TYPE_NAME).map((global) => {
+  return analysis.variants.globals.filter((global) => isNeoVariantFolderTypeName(global.type.name)).map((global) => {
     const className = owningClassName(global);
     return {
       id: variantRecordId(global, NEO_VARIANT_FOLDER_TYPE_NAME),
       source: sourceIdentity2(global, "variantFolder", global.name),
       classId: requiredName2(context.classIdsByName, className, "class"),
-      path: folderPath2(global)
+      path: folderPath2(global),
+      binding: folderBinding(context, global)
     };
   });
 }
@@ -73656,7 +74430,7 @@ function owningClassName(global) {
   return argument2;
 }
 function variantRecordId(global, typeName) {
-  const kind = typeName === NEO_VARIANT_TYPE_NAME ? "variant" : "variant-folder";
+  const kind = isNeoVariantTypeName(typeName) ? "variant" : "variant-folder";
   return materializedIdentityId(global, kind, global.name);
 }
 function variantRootValueId(context, variantId, global, className) {
@@ -73702,14 +74476,19 @@ function folderPath2(global) {
       `Variant folder ${global.name} must be declared as new("Path").`
     );
   }
-  const argument2 = expression.args[0];
+  const pathIndex = expression.argumentNames?.findIndex(
+    (name) => name === "path"
+  );
+  const argument2 = expression.args[pathIndex !== void 0 && pathIndex >= 0 ? pathIndex : 0];
   if (argument2 === void 0 || argument2.kind !== "litString") {
     throw new Error(
       `Variant folder ${global.name} requires one string-literal path argument.`
     );
   }
-  if (argument2.value.length === 0) {
-    throw new Error(`Variant folder ${global.name} has an empty path.`);
+  if (argument2.value.length === 0 && global.type.name !== NEO_LOOKUP_VARIANT_FOLDER_TYPE_NAME) {
+    throw new Error(
+      `Only a bound lookup variant folder may have an empty path.`
+    );
   }
   return argument2.value;
 }
@@ -73721,7 +74500,7 @@ function unwrapAnnotated2(expression) {
 function buildVariantPathIndexV4(classIdsByName, analysis) {
   const index = /* @__PURE__ */ new Map();
   const foldersBySymbol = new Map(
-    analysis.variants.globals.filter((global) => global.type.name === NEO_VARIANT_FOLDER_TYPE_NAME).map(
+    analysis.variants.globals.filter((global) => isNeoVariantFolderTypeName(global.type.name)).map(
       (global) => [
         folderSymbolKey(owningClassName(global), global.name),
         folderPath2(global)
@@ -73733,7 +74512,8 @@ function buildVariantPathIndexV4(classIdsByName, analysis) {
       `${className}.${NEO_VARIANT_SCOPE_NAME}.${NEO_VARIANT_RESERVED_NAME}`,
       {
         classId,
-        variantId: null
+        variantId: null,
+        valueClassId: null
       }
     );
   }
@@ -73748,16 +74528,88 @@ function buildVariantPathIndexV4(classIdsByName, analysis) {
     const scope = path === null ? `${className}.${NEO_VARIANT_SCOPE_NAME}` : `${className}.${NEO_VARIANT_SCOPE_NAME}.${path.split(NEO_VARIANT_FOLDER_PATH_SEPARATOR).join(".")}`;
     index.set(`${scope}.${global.name}`, {
       classId,
-      variantId: variantRecordId(global, NEO_VARIANT_TYPE_NAME)
+      variantId: variantRecordId(global, global.type.name),
+      valueClassId: global.type.name === NEO_LOOKUP_VARIANT_TYPE_NAME ? classIdsByName.get(valueClassName(global)) ?? null : null
     });
   }
   return index;
 }
+function valueClassName(global) {
+  const argument2 = global.type.arguments[1]?.name;
+  if (argument2 === void 0) {
+    throw new Error(
+      `${global.type.name} ${global.name} requires a TValue type argument.`
+    );
+  }
+  return argument2;
+}
+function folderBinding(context, global) {
+  if (global.type.name !== NEO_LOOKUP_VARIANT_FOLDER_TYPE_NAME) return null;
+  const expression = unwrapAnnotated2(parseExpression(global.initializer));
+  if (expression.kind !== "new") {
+    throw new Error(
+      `Lookup variant folder ${global.name} must be declared with new(...).`
+    );
+  }
+  const named = /* @__PURE__ */ new Map();
+  expression.args.forEach((argument2, index) => {
+    const name = expression.argumentNames?.[index];
+    if (name !== void 0 && name !== null) named.set(name, argument2);
+  });
+  const collection = named.get("collection");
+  const collectionValue = named.get("collectionValue");
+  const collectionPath = collection === void 0 ? null : dottedPath(collection);
+  if (collectionPath === null) {
+    throw new Error(
+      `Lookup variant folder ${global.name} requires collection: Class.Member.`
+    );
+  }
+  const collectionMemberId = resolveQualifiedMemberId(context, collectionPath);
+  if (collectionMemberId === null) {
+    throw new Error(
+      `Lookup variant folder ${global.name} names unknown collection ${collectionPath}.`
+    );
+  }
+  if (collectionValue === void 0) {
+    throw new Error(
+      `Lookup variant folder ${global.name} requires collectionValue: Reference(...).`
+    );
+  }
+  const collectionValueId = lowerReferenceValue(collectionValue);
+  if (collectionValueId === null) {
+    throw new Error(
+      `Lookup variant folder ${global.name} has an invalid collectionValue reference.`
+    );
+  }
+  return { collectionMemberId, collectionValueId };
+}
+function lowerReferenceValue(expression) {
+  if (expression.kind !== "call" || expression.callee.kind !== "ident" || expression.callee.name !== "Reference")
+    return null;
+  const idIndex = expression.argumentNames?.findIndex((name) => name === "id") ?? -1;
+  const target = expression.args[idIndex >= 0 ? idIndex : 0];
+  if (target?.kind === "litString") return target.value;
+  const path = target === void 0 ? null : dottedPath(target);
+  if (path === null || !path.startsWith("root.")) return null;
+  return referenceId(`Reference(${path})`);
+}
+function dottedPath(expression) {
+  const parts = [];
+  let cursor = expression;
+  while (cursor.kind === "member") {
+    parts.unshift(cursor.name);
+    cursor = cursor.receiver;
+  }
+  if (cursor.kind !== "ident") return null;
+  parts.unshift(cursor.name);
+  return parts.join(".");
+}
 var init_lower_variants = __esm({
   "src/project-source/lower-variants.ts"() {
     "use strict";
     init_src();
     init_lower_support();
+    init_lower_members();
   }
 });
 
@@ -76406,6 +77258,30 @@ function resolveRootPathCollectionValuesV4(args) {
   }
   return resolved;
 }
+function resolveRootPathVariantFolderCollectionValuesV4(args) {
+  const resolved = /* @__PURE__ */ new Map();
+  for (const folder of args.manifest.variantFolders) {
+    const spelled = folder.binding?.collectionValueId;
+    if (typeof spelled !== "string") continue;
+    if (!spelled.startsWith(ROOT_PATH_PENDING_PREFIX)) continue;
+    const path = spelled.slice(ROOT_PATH_PENDING_PREFIX.length);
+    const site = args.siteForFolder(folder.id);
+    const fail = (message) => {
+      args.registry.loweringFailures.push({
+        message,
+        site: {
+          uri: site?.uri ?? "<schema>",
+          declarationStart: site?.start ?? { line: 1, character: 0 },
+          expression: null,
+          label: folder.path
+        }
+      });
+    };
+    const target = walkRootValuePath(path, args.state, args.registry, fail);
+    if (target !== null) resolved.set(folder.id, target);
+  }
+  return resolved;
+}
 function walkRootValuePath(path, state, registry, fail) {
   const segments = path.split(".");
   const slotName = segments[1];
@@ -77890,18 +78766,31 @@ function syntheticMember(fields) {
 function variantOwnershipRoots(args) {
   const empty = { roots: [], bindingMembers: [] };
   if (args.variants.length === 0) return empty;
-  const variantClass = args.classes.find(
+  const plainVariantClass = args.classes.find(
     (schemaClass2) => schemaClass2.system?.worldKind === NeoWorldSystemClassKind.Variant
   );
-  if (variantClass === void 0) return empty;
-  const parameterId = variantClass.genericParams?.[0]?.id;
-  if (parameterId === void 0) return empty;
+  if (plainVariantClass === void 0) return empty;
   const valueById = new Map(args.values.map((value) => [value.id, value]));
+  const folderById = new Map(
+    (args.variantFolders ?? []).map((folder) => [folder.id, folder])
+  );
+  const memberById = new Map(
+    (args.members ?? []).map((member) => [member.id, member])
+  );
   const roots = [];
   const bindingMembers = [];
   for (const variant of args.variants) {
     const root = valueById.get(variant.valueId);
     if (root === void 0) continue;
+    const lookupFolder = variant.folderId == null ? void 0 : folderById.get(variant.folderId);
+    const inferredVariantKind = lookupFolder?.binding == null ? NeoWorldSystemClassKind.Variant : NeoWorldSystemClassKind.LookupVariant;
+    const variantClass = args.classes.find(
+      (schemaClass2) => schemaClass2.id === root.classId && (schemaClass2.system?.worldKind === NeoWorldSystemClassKind.Variant || schemaClass2.system?.worldKind === NeoWorldSystemClassKind.LookupVariant)
+    ) ?? args.classes.find(
+      (schemaClass2) => schemaClass2.system?.worldKind === inferredVariantKind
+    ) ?? plainVariantClass;
+    const parameterId = variantClass.genericParams?.[0]?.id;
+    if (parameterId === void 0) continue;
     const stampedTargetMemberId = readStampedTargetMemberId(root, parameterId);
     const targetClassId = variant.classId;
     let binding = null;
@@ -77919,13 +78808,31 @@ function variantOwnershipRoots(args) {
       );
       binding = { kind: "member", memberId: bindingMemberId };
     }
+    const stampedArguments = Object.fromEntries(
+      (variantClass.genericParams ?? []).flatMap((parameter4) => {
+        const memberId = root.genericBindings?.[parameter4.id];
+        return typeof memberId === "string" ? [[parameter4.id, { kind: "member", memberId }]] : [];
+      })
+    );
+    const lookupParameterId = variantClass.genericParams?.[1]?.id;
+    const lookupCollection = lookupFolder?.binding == null ? void 0 : memberById.get(lookupFolder.binding.collectionMemberId);
+    const lookupBinding = lookupParameterId !== void 0 && isMemberListBase(lookupCollection) ? {
+      [lookupParameterId]: {
+        kind: "member",
+        memberId: lookupCollection.entryMemberId
+      }
+    } : {};
     roots.push({
       valueId: variant.valueId,
       member: syntheticMember({
         id: variantRootMemberId(variant.id),
         name: "Variant",
         classId: variantClass.id,
-        classArguments: binding === null ? {} : { [parameterId]: binding }
+        classArguments: {
+          ...stampedArguments,
+          ...binding === null ? {} : { [parameterId]: binding },
+          ...lookupBinding
+        }
       })
     });
   }
@@ -77941,8 +78848,10 @@ function readStampedTargetMemberId(root, parameterId) {
 function withVariantOwnershipRoots(document, variants) {
   const { roots, bindingMembers } = variantOwnershipRoots({
     variants,
+    variantFolders: document.variantFolders,
     values: document.values,
-    classes: document.classes
+    classes: document.classes,
+    members: document.members
   });
   if (bindingMembers.length === 0) return { document, roots };
   return {
@@ -79716,6 +80625,28 @@ var init_world_layer_link_target = __esm({
 });
 
 // ../src/models/project/world-content-sidecar-validation.ts
+function worldPlacementVariantBindings(args) {
+  const foldersById = new Map(
+    args.variantFolders.map((folder) => [folder.id, folder])
+  );
+  const membersById = new Map(
+    args.members.map((member) => [member.id, member])
+  );
+  const valuesById = new Map(args.values.map((value) => [value.id, value]));
+  return args.variants.map((variant) => {
+    const folder = variant.folderId === null ? null : foldersById.get(variant.folderId) ?? null;
+    const binding = folder?.binding ?? null;
+    if (binding === null) return { id: variant.id, classId: variant.classId };
+    const collection = membersById.get(binding.collectionMemberId);
+    const value = valuesById.get(binding.collectionValueId);
+    const rows = isMemberListBase(collection) && value !== void 0 ? listEntryIdsForValue(collection, value, args.values) : [];
+    return {
+      id: variant.id,
+      classId: variant.classId,
+      lookupRowValueIds: rows
+    };
+  });
+}
 function validateWorldContentSidecars(args) {
   const variants = args.variants ?? [];
   const valuesById = new Map(args.values.map((value) => [value.id, value]));
@@ -79984,11 +80915,19 @@ function validateWorldPlacementSidecars(args) {
     assetClassId,
     placementId: args.placement.id,
     variantId: optionalNonEmptyString(record3.variantId),
+    rowValueId: optionalNonEmptyString(record3.rowValueId),
     variants: args.variants
   });
 }
 function validatePlacementVariantBinding(args) {
-  if (args.variantId === null) return;
+  if (args.variantId === null) {
+    if (args.rowValueId !== null) {
+      throw new Error(
+        `Placement value "${args.placementId}" binds row "${args.rowValueId}" without a variant.`
+      );
+    }
+    return;
+  }
   const variant = args.variants.find(
     (candidate) => candidate.id === args.variantId
   );
@@ -80002,6 +80941,20 @@ function validatePlacementVariantBinding(args) {
       `Placement value "${args.placementId}" places class "${args.assetClassId}" but names variant "${args.variantId}" of class "${variant.classId}"; variant lookup is not virtual.`
     );
   }
+  const lookupRows = variant.lookupRowValueIds;
+  if (lookupRows === void 0) {
+    if (args.rowValueId !== null) {
+      throw new Error(
+        `Placement value "${args.placementId}" binds a row to plain variant "${args.variantId}".`
+      );
+    }
+    return;
+  }
+  if (args.rowValueId === null || !lookupRows.includes(args.rowValueId)) {
+    throw new Error(
+      `Placement value "${args.placementId}" must bind a live row from lookup variant "${args.variantId}".`
+    );
+  }
 }
 function validateOwnedSparseValue(args) {
   if (args.referenceId === null) return;
@@ -80136,6 +81089,7 @@ var init_world_content_sidecar_validation = __esm({
     init_classes();
     init_world_layer_link_target();
     init_core();
+    init_members();
     init_internal_record_relations();
     WORLD_PLACEMENT_SIDECAR_KEYS = [
       "assetClassId",
@@ -80199,10 +81153,29 @@ function readVariantFolderRecord(value) {
   if (typeof value.classId !== "string" || value.classId.length === 0) {
     throw new Error(`Variant folder "${value.id}" classId is invalid.`);
   }
-  if (typeof value.path !== "string" || value.path.length === 0) {
+  if (typeof value.path !== "string") {
     throw new Error(`Variant folder "${value.id}" path is invalid.`);
   }
-  return { id: value.id, classId: value.classId, path: value.path };
+  let binding = null;
+  if (value.binding !== void 0 && value.binding !== null) {
+    if (!isRecordObject(value.binding)) {
+      throw new Error(`Variant folder "${value.id}" binding is invalid.`);
+    }
+    const collectionMemberId = value.binding.collectionMemberId;
+    const collectionValueId = value.binding.collectionValueId;
+    if (typeof collectionMemberId !== "string" || collectionMemberId.length === 0 || typeof collectionValueId !== "string" || collectionValueId.length === 0) {
+      throw new Error(
+        `Variant folder "${value.id}" binding requires collectionMemberId and collectionValueId.`
+      );
+    }
+    binding = { collectionMemberId, collectionValueId };
+  }
+  if (value.path.length === 0 && binding === null) {
+    throw new Error(
+      `Variant folder "${value.id}" may use the class-root path only with a collection binding.`
+    );
+  }
+  return { id: value.id, classId: value.classId, path: value.path, binding };
 }
 function resolveVariantWorldKind(classId, classesById) {
   const visited = /* @__PURE__ */ new Set();
@@ -80220,7 +81193,9 @@ function resolveVariantWorldKind(classId, classesById) {
 function isVariantFamilyClassId(classId, classesById) {
   const worldKind = resolveVariantWorldKind(classId, classesById);
   if (worldKind === VARIANT_WORLD_KIND) return true;
-  return worldKind === VARIANT_FOLDER_WORLD_KIND;
+  if (worldKind === VARIANT_FOLDER_WORLD_KIND) return true;
+  if (worldKind === LOOKUP_VARIANT_WORLD_KIND) return true;
+  return worldKind === LOOKUP_VARIANT_FOLDER_WORLD_KIND;
 }
 function variantFamilyLabel(classId, classesById) {
   const schemaClass2 = classesById.get(classId);
@@ -80325,7 +81300,7 @@ function assertNoVariantTypePositions(args) {
 function assertNoAuthoredVariantMembers(args) {
   for (const schemaClass2 of args.classesById.values()) {
     const worldKind = schemaClass2.system?.worldKind;
-    if (worldKind !== VARIANT_WORLD_KIND && worldKind !== VARIANT_FOLDER_WORLD_KIND) {
+    if (worldKind !== VARIANT_WORLD_KIND && worldKind !== VARIANT_FOLDER_WORLD_KIND && worldKind !== LOOKUP_VARIANT_WORLD_KIND && worldKind !== LOOKUP_VARIANT_FOLDER_WORLD_KIND) {
       continue;
     }
     for (const [schemaKey, memberId] of Object.entries(schemaClass2.schema)) {
@@ -80354,6 +81329,12 @@ function assertOpaqueVariantsValid(args) {
     args.folders.map((folder) => [folder.id, folder])
   );
   const folderPathsByClass = /* @__PURE__ */ new Map();
+  const rootFolderByClass = /* @__PURE__ */ new Map();
+  const valuesById = new Map(
+    (args.values ?? []).flatMap(
+      (value) => isRecordObject(value) && typeof value.id === "string" ? [[value.id, value]] : []
+    )
+  );
   for (const folder of args.folders) {
     const owner = args.classesById.get(folder.classId);
     if (owner === void 0) {
@@ -80362,7 +81343,42 @@ function assertOpaqueVariantsValid(args) {
       );
     }
     assertVariantTargetClass(owner, args, `Variant folder "${folder.id}"`);
-    const segments = folder.path.split(VARIANT_FOLDER_PATH_SEPARATOR);
+    const binding = folder.binding ?? null;
+    if (binding !== null) {
+      const collection = args.membersById?.get(binding.collectionMemberId);
+      if (collection === void 0 || collection.kind !== MEMBER_KIND_LIST) {
+        throw new Error(
+          `Lookup variant folder "${folder.id}" binds missing or non-list collection member "${binding.collectionMemberId}".`
+        );
+      }
+      const entry = typeof collection.entryMemberId === "string" ? args.membersById?.get(collection.entryMemberId) : void 0;
+      if (entry === void 0 || entry.kind !== MEMBER_KIND_CLASS || typeof entry.classId !== "string") {
+        throw new Error(
+          `Lookup variant folder "${folder.id}" collection "${binding.collectionMemberId}" must contain Class entries.`
+        );
+      }
+      const collectionValue = valuesById.get(binding.collectionValueId);
+      if (collectionValue === void 0) {
+        throw new Error(
+          `Lookup variant folder "${folder.id}" binds missing collection value "${binding.collectionValueId}".`
+        );
+      }
+      if (Object.hasOwn(collectionValue, "memberId") && collectionValue.memberId !== null && collectionValue.memberId !== void 0 && collectionValue.memberId !== binding.collectionMemberId) {
+        throw new Error(
+          `Lookup variant folder "${folder.id}" binds collection value "${binding.collectionValueId}" from member "${String(collectionValue.memberId)}" instead of collection "${binding.collectionMemberId}".`
+        );
+      }
+    }
+    if (folder.path.length === 0) {
+      const prior = rootFolderByClass.get(folder.classId);
+      if (prior !== void 0) {
+        throw new Error(
+          `Lookup variant folders "${prior}" and "${folder.id}" both enumerate the class root; at most one is allowed per class.`
+        );
+      }
+      rootFolderByClass.set(folder.classId, folder.id);
+    }
+    const segments = folder.path.length === 0 ? [] : folder.path.split(VARIANT_FOLDER_PATH_SEPARATOR);
     for (const segment of segments) {
       assertVariantIdentifier(
         segment,
@@ -80402,7 +81418,7 @@ function assertOpaqueVariantsValid(args) {
     scopeMembers.set(key, members);
   };
   for (const folder of args.folders) {
-    const segments = folder.path.split(VARIANT_FOLDER_PATH_SEPARATOR);
+    const segments = folder.path.length === 0 ? [] : folder.path.split(VARIANT_FOLDER_PATH_SEPARATOR);
     segments.forEach((segment, index) => {
       const parentPath = segments.slice(0, index).join(VARIANT_FOLDER_PATH_SEPARATOR);
       const ownPath = segments.slice(0, index + 1).join(VARIANT_FOLDER_PATH_SEPARATOR);
@@ -80449,6 +81465,19 @@ function assertOpaqueVariantsValid(args) {
         );
       }
       scopePath = folder.path;
+      const root = valuesById.get(variant.valueId);
+      const rootClassId = root?.classId;
+      const rootWorldKind = typeof rootClassId === "string" ? resolveVariantWorldKind(rootClassId, args.classesById) : null;
+      const expectedWorldKind = (folder.binding ?? null) === null ? VARIANT_WORLD_KIND : LOOKUP_VARIANT_WORLD_KIND;
+      if (rootWorldKind !== null && rootWorldKind !== expectedWorldKind) {
+        throw new Error(
+          `Variant "${variant.id}" in folder "${folder.id}" roots world kind "${rootWorldKind}"; this folder requires "${expectedWorldKind}".`
+        );
+      }
+    } else if (rootFolderByClass.has(variant.classId)) {
+      throw new Error(
+        `Variant "${variant.id}" is declared at the class root beside root lookup folder "${rootFolderByClass.get(variant.classId)}"; the root is either authored or collection-bound, never both.`
+      );
     }
     claimScope(
       variant.classId,
@@ -80467,13 +81496,15 @@ function assertVariantTargetClass(owner, args, describe2) {
     );
   }
 }
-var VARIANT_WORLD_KIND, VARIANT_FOLDER_WORLD_KIND, RESERVED_VARIANT_NAME, VARIANT_FOLDER_PATH_SEPARATOR, MEMBER_KIND_DICTIONARY, MEMBER_KIND_LIST, MEMBER_KIND_CLASS, MEMBER_KIND_LOOKUP, MEMBER_KIND_VARIANT, variantScopeKey, variantFolderScopeKey;
+var VARIANT_WORLD_KIND, VARIANT_FOLDER_WORLD_KIND, LOOKUP_VARIANT_WORLD_KIND, LOOKUP_VARIANT_FOLDER_WORLD_KIND, RESERVED_VARIANT_NAME, VARIANT_FOLDER_PATH_SEPARATOR, MEMBER_KIND_DICTIONARY, MEMBER_KIND_LIST, MEMBER_KIND_CLASS, MEMBER_KIND_LOOKUP, MEMBER_KIND_VARIANT, variantScopeKey, variantFolderScopeKey;
 var init_projectVariantValidation = __esm({
   "../convex/projectVariantValidation.ts"() {
     "use strict";
     init_src();
     VARIANT_WORLD_KIND = "variant";
     VARIANT_FOLDER_WORLD_KIND = "variantFolder";
+    LOOKUP_VARIANT_WORLD_KIND = "lookupVariant";
+    LOOKUP_VARIANT_FOLDER_WORLD_KIND = "lookupVariantFolder";
     RESERVED_VARIANT_NAME = "Base";
     VARIANT_FOLDER_PATH_SEPARATOR = "/";
     MEMBER_KIND_DICTIONARY = 5;
@@ -80873,7 +81904,9 @@ function assertProjectInterfaceDocumentValid(view, options = {}) {
       variants: (view.variants ?? []).map(readVariantRecord),
       folders: (view.variantFolders ?? []).map(readVariantFolderRecord),
       classesById,
-      objectWorldKind: NEO_OBJECT_WORLD_KIND
+      objectWorldKind: NEO_OBJECT_WORLD_KIND,
+      membersById,
+      values: view.values
     });
   }
   for (const member of members) {
@@ -90083,7 +91116,13 @@ function assertStagedWorldContentLayerBindingsValid(current, projected, changes)
   validateWorldContentSidecars({
     classes,
     relations,
-    values: projected.values
+    values: projected.values,
+    variants: worldPlacementVariantBindings({
+      variants: projected.variants ?? [],
+      variantFolders: projected.variantFolders ?? [],
+      members: projected.members,
+      values: projected.values
+    })
   });
   validateWorldLayerLinkClassTargets({
     classes,
@@ -90235,7 +91274,8 @@ function assertStagedProjectInterfaceValid(projected, changes) {
       constructors: projected.constructors ?? [],
       variants: projected.variants ?? [],
       variantFolders: projected.variantFolders ?? [],
-      interfaces: projected.interfaces
+      interfaces: projected.interfaces,
+      values: projected.values
     },
     {
       validateMemberSchemaKeys: relevant.some(
@@ -90555,6 +91595,15 @@ function assertStagedVariantMemberValuesValid(projected, changes) {
   const variantsById = new Map(
     (projected.variants ?? []).map((variant) => [variant.id, variant])
   );
+  const foldersById = new Map(
+    (projected.variantFolders ?? []).map((folder) => [folder.id, folder])
+  );
+  const membersById = new Map(
+    projected.members.map((member) => [member.id, member])
+  );
+  const valuesById = new Map(
+    projected.values.map((value) => [value.id, value])
+  );
   const graded = [];
   for (const member of variantMembers) {
     const declaration = substituteMemberForListenerGrading(member, projected);
@@ -90594,7 +91643,11 @@ function assertStagedVariantMemberValuesValid(projected, changes) {
       declaration: entry.declaration,
       owner: entry.label,
       classesById,
-      variantsById
+      variantsById,
+      foldersById,
+      membersById,
+      valuesById,
+      values: projected.values
     });
   }
 }
@@ -90625,7 +91678,16 @@ function assertVariantMemberTargetValid(args) {
   }
 }
 function assertVariantReferenceValid(args) {
-  const { value, declaration, owner, classesById, variantsById } = args;
+  const {
+    value,
+    declaration,
+    owner,
+    classesById,
+    variantsById,
+    foldersById,
+    membersById,
+    valuesById
+  } = args;
   const target = variantMemberTargetTypeInfo(declaration);
   if (target === null) return;
   if (value === null) {
@@ -90659,7 +91721,18 @@ function assertVariantReferenceValid(args) {
       );
     }
   }
-  if (value.variantId === null) return;
+  const declaredValueType = variantMemberValueTypeInfo(declaration);
+  if (value.variantId === null) {
+    if (declaredValueType !== null) {
+      throw new Error(
+        `${owner} declares NeoLookupVariant and must select a lookup variant rather than the base class.`
+      );
+    }
+    if (value.rowValueId !== null && value.rowValueId !== void 0) {
+      throw new Error(`${owner} cannot bind a row to the base class.`);
+    }
+    return;
+  }
   const variant = variantsById.get(value.variantId);
   if (variant === void 0) {
     throw new Error(
@@ -90672,6 +91745,58 @@ function assertVariantReferenceValid(args) {
       `${owner} selects class "${selectedClass.name}" but names variant "${variant.name}" of "${ownerClassName}". Variant lookup is not virtual, so a variant belongs to exactly one class (P67 \xA74.3).`
     );
   }
+  const folder = variant.folderId === null ? null : foldersById.get(variant.folderId) ?? null;
+  const binding = folder?.binding ?? null;
+  if (declaredValueType !== null) {
+    if (binding === null) {
+      throw new Error(
+        `${owner} declares NeoLookupVariant but selects plain variant "${variant.name}".`
+      );
+    }
+    if (value.rowValueId !== null && value.rowValueId !== void 0) {
+      throw new Error(
+        `${owner} keeps its lookup row unbound, so rowValueId must be null.`
+      );
+    }
+    if (declaredValueType.type === 7 /* Class */ && lookupBindingEntryClassId(binding, membersById) !== declaredValueType.classId) {
+      throw new Error(
+        `${owner} lookup value type does not match variant folder "${folder?.path ?? ""}".`
+      );
+    }
+    return;
+  }
+  if (binding === null) {
+    if (value.rowValueId !== null && value.rowValueId !== void 0) {
+      throw new Error(
+        `${owner} binds a row to plain variant "${variant.name}".`
+      );
+    }
+    return;
+  }
+  if (value.rowValueId === null || value.rowValueId === void 0) {
+    throw new Error(
+      `${owner} selects lookup variant "${variant.name}" and must bind one collection row.`
+    );
+  }
+  const collection = membersById.get(binding.collectionMemberId);
+  const collectionValue = valuesById.get(binding.collectionValueId);
+  if (!isMemberListBase(collection) || collectionValue === void 0 || !valuesById.has(value.rowValueId) || !listEntryIdsForValue(collection, collectionValue, args.values).includes(
+    value.rowValueId
+  )) {
+    throw new Error(
+      `${owner} binds row "${value.rowValueId}", which is not in lookup variant folder "${folder?.path ?? ""}".`
+    );
+  }
+}
+function variantMemberValueTypeInfo(declaration) {
+  const valueType = Reflect.get(declaration, "valueTypeInfo");
+  return isNSTypeInfo(valueType) ? valueType : null;
+}
+function lookupBindingEntryClassId(binding, membersById) {
+  const collection = membersById.get(binding.collectionMemberId);
+  if (!isMemberListBase(collection)) return null;
+  const entry = membersById.get(collection.entryMemberId);
+  return isMemberClassBase(entry) ? entry.classId : null;
 }
 function variantMemberTargetTypeInfo(declaration) {
   const target = Reflect.get(declaration, "targetTypeInfo");
@@ -91054,6 +92179,43 @@ function computeWorkspaceStatus(workspace, options) {
       }
     }
   }
+  const resolvedVariantFolderPaths = resolveRootPathVariantFolderCollectionValuesV4({
+    manifest,
+    state: rootPathResolutionState,
+    registry: valueLowerRegistry,
+    siteForFolder: (folderId) => {
+      const span2 = sourceByKey.get(
+        recordStateKey("variant-folder", folderId)
+      )?.span;
+      return span2 === void 0 ? null : { uri: span2.path, start: span2.start };
+    }
+  });
+  if (resolvedVariantFolderPaths.size > 0) {
+    manifest = {
+      ...manifest,
+      variantFolders: manifest.variantFolders.map((folder) => {
+        const resolvedId = resolvedVariantFolderPaths.get(folder.id);
+        return resolvedId === void 0 || folder.binding === null ? folder : {
+          ...folder,
+          binding: { ...folder.binding, collectionValueId: resolvedId }
+        };
+      })
+    };
+    for (const [folderId, resolvedId] of resolvedVariantFolderPaths) {
+      const document = documentsByKey.get(
+        recordStateKey("variant-folder", folderId)
+      );
+      if (document !== void 0 && isObjectRecord2(document.data.binding)) {
+        document.data.binding.collectionValueId = resolvedId;
+      }
+      const record3 = records2.find(
+        (candidate) => candidate.recordKind === "variant-folder" && candidate.recordId === folderId
+      );
+      if (record3 !== void 0 && isObjectRecord2(record3.fileFields.binding)) {
+        record3.fileFields.binding.collectionValueId = resolvedId;
+      }
+    }
+  }
   const resolvedDefaultKeys = resolveKeyReferenceMemberDefaultsV4({
     manifest,
     state: rootPathResolutionState,
@@ -93967,8 +95129,14 @@ function lowerVariantRootRow(context, binding, rootMember, source, rows, localiz
     rows,
     localizedTexts,
     void 0,
-    /* @__PURE__ */ new Map([
-      [parameter4.id, inferredGenericClassBinding(binding.targetClassId)]
+    new Map([
+      [parameter4.id, inferredGenericClassBinding(binding.targetClassId)],
+      ...binding.valueClassId === null || variantClass.genericParameters[1] === void 0 ? [] : [
+        [
+          variantClass.genericParameters[1].id,
+          inferredGenericClassBinding(binding.valueClassId)
+        ]
+      ]
     ]),
     binding.initializer
   );
@@ -94081,10 +95249,10 @@ function variantValueRecord(binding, fileFields, source) {
   };
 }
 function variantRootMember(context, binding) {
-  const variantClass = context.classesByName.get(NEO_VARIANT_TYPE_NAME);
+  const variantClass = context.classesByName.get(binding.variantTypeName);
   if (variantClass === void 0) {
     throw new Error(
-      `Variant ${binding.label} cannot be lowered: this project has no seeded ${NEO_VARIANT_TYPE_NAME} class. Run \`neo pull\` against a project on the current platform schema.`
+      `Variant ${binding.label} cannot be lowered: this project has no seeded ${binding.variantTypeName} class. Run \`neo pull\` against a project on the current platform schema.`
     );
   }
   const parameter4 = variantClass.genericParameters[0];
@@ -94115,6 +95283,12 @@ function variantRootMember(context, binding) {
       [parameter4.id]: {
         kind: "member",
         memberId: inferredGenericClassBinding(binding.targetClassId)
+      },
+      ...binding.valueClassId === null || variantClass.genericParameters[1] === void 0 ? {} : {
+        [variantClass.genericParameters[1].id]: {
+          kind: "member",
+          memberId: inferredGenericClassBinding(binding.valueClassId)
+        }
       }
     },
     isStatic: false,
@@ -109477,7 +110651,7 @@ var init_registry2 = __esm({
     PROJECT_SCHEMA_CONTRACT = Object.freeze({
       formatVersion: 3,
       contractVersion: "3.12",
-      cliVersion: "0.31.2",
+      cliVersion: "0.31.4",
       projectFileUploadBatchSize: 32,
       documentRecords: {
         member: {
@@ -109519,6 +110693,7 @@ var init_registry2 = __esm({
             "collectionValueId",
             "declaredTypeInfo",
             "targetTypeInfo",
+            "variantValueTypeInfo",
             "dialogueGroupId",
             "code",
             "setterCode",
@@ -109650,10 +110825,10 @@ var init_registry2 = __esm({
         "variant-folder": {
           // P67 §3.3. A folder's whole content is its path, which is what lets a
           // rename be a one-record edit that orphans nothing.
-          authored: ["id", "classId", "path"],
+          authored: ["id", "classId", "path", "binding"],
           derived: [],
           volatile: ["projectId", "createdAt", "updatedAt"],
-          normalization: {}
+          normalization: { binding: "missingIsNull" }
         },
         interface: {
           authored: [
@@ -110169,7 +111344,9 @@ var init_registry2 = __esm({
               "AnimationSegmentTrack",
               "SpriteAnimationSegmentTrack",
               "Variant",
-              "VariantFolder"
+              "VariantFolder",
+              "LookupVariant",
+              "LookupVariantFolder"
             ],
             NeoTextureType: [
               "Default",
@@ -116069,7 +117246,7 @@ There is no --keep-current: preserving current semantic state defines flatten.
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   if (args.command === "--version") {
-    console.log("0.31.2");
+    console.log("0.31.4");
     return;
   }
   if (args.command === null || args.command === "help" || args.command === "--help" || args.command === "-h") {