@player-tools/fluent 0.12.1--canary.241.6077

package/src/core/base-builder/resolution/path-resolver.ts

@@ -0,0 +1,116 @@
+import type { ValuePath } from "../types";
+import { isAssetWrapperValue, isPlainObject } from "../guards";
+
+/**
+ * Safely gets a value as a Record<string, unknown>, returning empty object if not.
+ * This avoids unsafe `as` assertions by using the isPlainObject type guard.
+ */
+function asRecordOrEmpty(value: unknown): Record<string, unknown> {
+  return isPlainObject(value) ? value : {};
+}
+
+/**
+ * Sets a value at a nested path in an object
+ * Handles nested objects, arrays, and AssetWrapper structures
+ *
+ * @param obj - The target object to modify
+ * @param path - Array of keys/indices representing the path
+ * @param value - The value to set at the path
+ *
+ * @example
+ * setValueAtPath(obj, ["actions", 0, "label"], "Click me")
+ * // Sets obj.actions[0].label = "Click me"
+ */
+export function setValueAtPath(
+  obj: Record<string, unknown>,
+  path: ValuePath,
+  value: unknown,
+): void {
+  if (path.length === 0) return;
+
+  if (path.length === 1) {
+    obj[path[0]] = value;
+    return;
+  }
+
+  const [currentKey, ...restPath] = path;
+  const nextKey = restPath[0];
+  const currentValue = obj[currentKey];
+
+  // Check if current value is an AssetWrapper containing an array
+  const isAssetWrapperWithArray =
+    isAssetWrapperValue(currentValue) && Array.isArray(currentValue.asset);
+
+  if (isAssetWrapperWithArray && typeof nextKey === "number") {
+    setValueInAssetWrapperArray(
+      obj,
+      currentKey,
+      currentValue as { asset: unknown[] },
+      nextKey,
+      restPath,
+      value,
+    );
+  } else if (Array.isArray(currentValue) && typeof nextKey === "number") {
+    setValueInArray(obj, currentKey, currentValue, nextKey, restPath, value);
+  } else {
+    setValueInObject(obj, currentKey, restPath, value);
+  }
+}
+
+/**
+ * Sets value in an array within an AssetWrapper
+ */
+function setValueInAssetWrapperArray(
+  obj: Record<string, unknown>,
+  currentKey: string | number,
+  wrappedArray: { asset: unknown[] },
+  nextKey: number,
+  restPath: ValuePath,
+  value: unknown,
+): void {
+  const arrayResult = [...wrappedArray.asset];
+  if (restPath.length === 1) {
+    arrayResult[nextKey] = value;
+  } else {
+    const nestedObj = asRecordOrEmpty(arrayResult[nextKey]);
+    setValueAtPath(nestedObj, restPath.slice(1), value);
+    arrayResult[nextKey] = nestedObj;
+  }
+  obj[currentKey] = { asset: arrayResult };
+}
+
+/**
+ * Sets value in a regular array
+ */
+function setValueInArray(
+  obj: Record<string, unknown>,
+  currentKey: string | number,
+  array: unknown[],
+  nextKey: number,
+  restPath: ValuePath,
+  value: unknown,
+): void {
+  const arrayResult = [...array];
+  if (restPath.length === 1) {
+    arrayResult[nextKey] = value;
+  } else {
+    const nestedObj = asRecordOrEmpty(arrayResult[nextKey]);
+    setValueAtPath(nestedObj, restPath.slice(1), value);
+    arrayResult[nextKey] = nestedObj;
+  }
+  obj[currentKey] = arrayResult;
+}
+
+/**
+ * Sets value in a nested object
+ */
+function setValueInObject(
+  obj: Record<string, unknown>,
+  currentKey: string | number,
+  restPath: ValuePath,
+  value: unknown,
+): void {
+  const nestedObj = asRecordOrEmpty(obj[currentKey]);
+  setValueAtPath(nestedObj, restPath, value);
+  obj[currentKey] = nestedObj;
+}

package/src/core/base-builder/resolution/pipeline.ts

@@ -0,0 +1,103 @@
+import type { BaseBuildContext } from "../types";
+import type { ValueStorage } from "../storage/value-storage";
+import type { AuxiliaryStorage } from "../storage/auxiliary-storage";
+import { resolveStaticValues } from "./steps/static-values";
+import { generateAssetIdForBuilder } from "./steps/asset-id";
+import { resolveAssetWrappers } from "./steps/asset-wrappers";
+import { resolveMixedArrays } from "./steps/mixed-arrays";
+import { resolveBuilders } from "./steps/builders";
+import { resolveSwitches } from "./steps/switches";
+import { resolveTemplates } from "./steps/templates";
+import { resolveNestedAssetWrappers } from "./steps/nested-asset-wrappers";
+
+/**
+ * Creates a nested context for child assets
+ * This is Step 3 of the build process
+ */
+function createNestedParentContext<C extends BaseBuildContext>(
+  result: Record<string, unknown>,
+  context: C | undefined,
+): C | undefined {
+  if (!context) {
+    return undefined;
+  }
+
+  // Extract parent ID with type checking
+  const parentId =
+    "id" in result && typeof result.id === "string" ? result.id : undefined;
+
+  // Create context for nested assets
+  // We clear the branch to avoid double-nesting
+  return {
+    ...context,
+    parentId,
+    branch: undefined,
+  } as C;
+}
+
+/**
+ * Executes the complete build pipeline
+ *
+ * The pipeline consists of 9 steps that transform builder state into a final object:
+ * 1. Resolve static values (extract TaggedTemplateValue, resolve simple builders)
+ * 2. Generate asset ID if needed
+ * 3. Create nested context for child assets
+ * 4. Resolve AssetWrapper values
+ * 5. Resolve mixed arrays
+ * 6. Resolve builders
+ * 7. Resolve nested AssetWrapper paths
+ * 8. Resolve switches
+ * 9. Resolve templates
+ *
+ * @param valueStorage - Storage containing property values
+ * @param auxiliaryStorage - Storage containing metadata (templates, switches)
+ * @param defaults - Optional default values to merge into result
+ * @param context - Optional build context
+ * @param arrayProperties - Set of property names that are array types
+ * @param assetWrapperPaths - Paths to nested AssetWrapper properties
+ * @returns The fully built object
+ */
+export function executeBuildPipeline<T, C extends BaseBuildContext>(
+  valueStorage: ValueStorage<T>,
+  auxiliaryStorage: AuxiliaryStorage,
+  defaults: Partial<T> | undefined,
+  context: C | undefined,
+  arrayProperties: ReadonlySet<string>,
+  assetWrapperPaths: ReadonlyArray<ReadonlyArray<string>> = [],
+): T {
+  const result: Record<string, unknown> = defaults ? { ...defaults } : {};
+
+  // Step 1: Resolve static values
+  resolveStaticValues(valueStorage, result, context);
+
+  // Step 2: Generate asset ID if needed
+  generateAssetIdForBuilder(valueStorage, result, context);
+
+  // Step 3: Create nested context for child assets
+  const nestedParentContext = createNestedParentContext(result, context);
+
+  // Step 4: Resolve AssetWrapper values
+  resolveAssetWrappers(valueStorage, result, nestedParentContext);
+
+  // Step 5: Resolve mixed arrays
+  resolveMixedArrays(valueStorage, result, nestedParentContext);
+
+  // Step 6: Resolve builders
+  resolveBuilders(valueStorage, result, nestedParentContext);
+
+  // Step 7: Resolve nested AssetWrapper paths
+  resolveNestedAssetWrappers(result, nestedParentContext, assetWrapperPaths);
+
+  // Step 8: Resolve switches
+  resolveSwitches(
+    auxiliaryStorage,
+    result,
+    nestedParentContext,
+    arrayProperties,
+  );
+
+  // Step 9: Resolve templates
+  resolveTemplates(auxiliaryStorage, result, context);
+
+  return result as T;
+}

package/src/core/base-builder/resolution/steps/__tests__/nested-asset-wrappers.test.ts

@@ -0,0 +1,206 @@
+import { describe, test, expect } from "vitest";
+import { resolveNestedAssetWrappers } from "../nested-asset-wrappers";
+import type { BaseBuildContext } from "../../../types";
+import { FLUENT_BUILDER_SYMBOL } from "../../../types";
+
+describe("resolveNestedAssetWrappers", () => {
+  test("skips paths with length < 2", () => {
+    const result: Record<string, unknown> = {
+      label: { type: "text", value: "Hello" },
+    };
+
+    resolveNestedAssetWrappers(result, undefined, [["label"]]);
+
+    // Should not wrap - this is handled by direct AssetWrapper resolution
+    expect(result.label).toEqual({ type: "text", value: "Hello" });
+  });
+
+  test("wraps asset at nested path", () => {
+    const result: Record<string, unknown> = {
+      header: {
+        left: { type: "text", value: "Hello" },
+      },
+    };
+
+    resolveNestedAssetWrappers(result, undefined, [["header", "left"]]);
+
+    expect(result.header).toEqual({
+      left: { asset: { type: "text", value: "Hello" } },
+    });
+  });
+
+  test("wraps multiple nested paths", () => {
+    const result: Record<string, unknown> = {
+      header: {
+        left: { type: "text", value: "Left" },
+        right: { type: "text", value: "Right" },
+      },
+    };
+
+    resolveNestedAssetWrappers(result, undefined, [
+      ["header", "left"],
+      ["header", "right"],
+    ]);
+
+    expect(result.header).toEqual({
+      left: { asset: { type: "text", value: "Left" } },
+      right: { asset: { type: "text", value: "Right" } },
+    });
+  });
+
+  test("handles deeply nested paths", () => {
+    const result: Record<string, unknown> = {
+      section: {
+        content: {
+          slot: { type: "text", value: "Deep" },
+        },
+      },
+    };
+
+    resolveNestedAssetWrappers(result, undefined, [
+      ["section", "content", "slot"],
+    ]);
+
+    expect(result.section).toEqual({
+      content: {
+        slot: { asset: { type: "text", value: "Deep" } },
+      },
+    });
+  });
+
+  test("skips already wrapped assets", () => {
+    const result: Record<string, unknown> = {
+      header: {
+        left: { asset: { type: "text", value: "Already wrapped" } },
+      },
+    };
+
+    resolveNestedAssetWrappers(result, undefined, [["header", "left"]]);
+
+    expect(result.header).toEqual({
+      left: { asset: { type: "text", value: "Already wrapped" } },
+    });
+  });
+
+  test("handles missing intermediate path", () => {
+    const result: Record<string, unknown> = {
+      // header.left doesn't exist
+    };
+
+    // Should not throw
+    resolveNestedAssetWrappers(result, undefined, [["header", "left"]]);
+
+    expect(result).toEqual({});
+  });
+
+  test("handles null value in path", () => {
+    const result: Record<string, unknown> = {
+      header: {
+        left: null,
+      },
+    };
+
+    resolveNestedAssetWrappers(result, undefined, [["header", "left"]]);
+
+    expect(result.header).toEqual({ left: null });
+  });
+
+  test("wraps arrays of assets", () => {
+    const result: Record<string, unknown> = {
+      content: {
+        items: [
+          { type: "text", value: "Item 1" },
+          { type: "text", value: "Item 2" },
+        ],
+      },
+    };
+
+    resolveNestedAssetWrappers(result, undefined, [["content", "items"]]);
+
+    expect(result.content).toEqual({
+      items: [
+        { asset: { type: "text", value: "Item 1" } },
+        { asset: { type: "text", value: "Item 2" } },
+      ],
+    });
+  });
+
+  test("filters null/undefined from arrays", () => {
+    const result: Record<string, unknown> = {
+      content: {
+        items: [{ type: "text", value: "Valid" }, null, undefined],
+      },
+    };
+
+    resolveNestedAssetWrappers(result, undefined, [["content", "items"]]);
+
+    expect(result.content).toEqual({
+      items: [{ asset: { type: "text", value: "Valid" } }],
+    });
+  });
+
+  test("skips non-asset values", () => {
+    const result: Record<string, unknown> = {
+      config: {
+        name: "test",
+      },
+    };
+
+    resolveNestedAssetWrappers(result, undefined, [["config", "name"]]);
+
+    // String value should not be wrapped
+    expect(result.config).toEqual({ name: "test" });
+  });
+
+  test("generates slot names from path", () => {
+    const context: BaseBuildContext = {
+      parentId: "parent",
+    };
+
+    const result: Record<string, unknown> = {
+      header: {
+        left: { type: "text", value: "Hello", id: "" },
+      },
+    };
+
+    resolveNestedAssetWrappers(result, context, [["header", "left"]]);
+
+    // The ID should be generated using the path as slot name
+    const header = result.header as Record<string, unknown>;
+    const left = header.left as { asset: { id: string } };
+    expect(left.asset.id).toBe("parent-header-left");
+  });
+
+  test("resolves intermediate builders before continuing traversal", () => {
+    // Create a mock builder for the intermediate object
+    const mockBuilder = {
+      [FLUENT_BUILDER_SYMBOL]: true as const,
+      build: () => ({
+        left: { type: "text", value: "From builder" },
+      }),
+    };
+
+    const result: Record<string, unknown> = {
+      header: mockBuilder,
+    };
+
+    resolveNestedAssetWrappers(result, undefined, [["header", "left"]]);
+
+    // The intermediate builder should be resolved, and the leaf should be wrapped
+    expect(result.header).toEqual({
+      left: { asset: { type: "text", value: "From builder" } },
+    });
+  });
+
+  test("handles empty path gracefully", () => {
+    const result: Record<string, unknown> = {
+      label: { type: "text", value: "Hello" },
+    };
+
+    // Should not throw for empty path
+    resolveNestedAssetWrappers(result, undefined, [[]]);
+
+    // Result should be unchanged
+    expect(result.label).toEqual({ type: "text", value: "Hello" });
+  });
+});

package/src/core/base-builder/resolution/steps/asset-id.ts

@@ -0,0 +1,77 @@
+import type { BaseBuildContext, AssetMetadata } from "../../types";
+import type { ValueStorage } from "../../storage/value-storage";
+import { isStringOrUndefined } from "../../guards";
+import { generateAssetId } from "../../id/generator";
+
+/**
+ * Step 2: Generates ID for this asset if needed
+ *
+ * Note: This runs AFTER resolveStaticValues, so we use values from result
+ * rather than from storage.
+ *
+ * @param storage - The value storage (used to check if ID was explicitly set)
+ * @param result - The result object being built (contains resolved values)
+ * @param context - Optional build context
+ */
+export function generateAssetIdForBuilder<T, C extends BaseBuildContext>(
+  storage: ValueStorage<T>,
+  result: Record<string, unknown>,
+  context: C | undefined,
+): void {
+  const hasIdSet = storage.has("id" as keyof T);
+  const hasType = storage.has("type" as keyof T) || "type" in result;
+  const hasIdField = "id" in result;
+
+  // Case 1: Asset with type field (standard case)
+  if (!hasIdSet && hasType) {
+    // Use values from result since they're already extracted
+    const typeValue = result.type;
+    const assetValue = result.value;
+    const assetBinding = result.binding;
+
+    // Validate types with type guards
+    if (!isStringOrUndefined(typeValue)) {
+      return; // Skip ID generation if type is not a string
+    }
+
+    if (!isStringOrUndefined(assetValue)) {
+      return; // Skip if value is not string/undefined
+    }
+
+    if (!isStringOrUndefined(assetBinding)) {
+      return; // Skip if binding is not string/undefined
+    }
+
+    const assetMetadata: AssetMetadata = {
+      type: typeValue as string,
+      ...(assetValue ? { value: assetValue as string } : {}),
+      ...(assetBinding ? { binding: assetBinding as string } : {}),
+    };
+
+    const generatedId = generateAssetId({
+      context,
+      parameterName: typeValue as string,
+      assetMetadata,
+      explicitId: undefined,
+    });
+
+    if (generatedId) {
+      result.id = generatedId;
+    }
+  }
+  // Case 2: Object with id field but no type (e.g., ChoiceItem)
+  // Generate ID based on context branch if available
+  else if (!hasIdSet && hasIdField && !hasType && context && context.branch) {
+    // Use genId directly with the context to generate ID based on branch
+    const generatedId = generateAssetId({
+      context,
+      parameterName: "item",
+      assetMetadata: undefined,
+      explicitId: undefined,
+    });
+
+    if (generatedId) {
+      result.id = generatedId;
+    }
+  }
+}

package/src/core/base-builder/resolution/steps/asset-wrappers.ts

@@ -0,0 +1,64 @@
+import type { BaseBuildContext } from "../../types";
+import type { ValueStorage } from "../../storage/value-storage";
+import { isAssetWrapperValue } from "../../guards";
+import { resolveAndWrapAsset } from "../value-resolver";
+
+/**
+ * Step 4: Resolves AssetWrapper values in static storage
+ *
+ * Processes values that were marked as AssetWrapper during value setting.
+ * These values contain assets or builders that need special context handling.
+ *
+ * @param storage - The value storage
+ * @param result - The result object being built
+ * @param nestedParentContext - Context for nested assets
+ */
+export function resolveAssetWrappers<T, C extends BaseBuildContext>(
+  storage: ValueStorage<T>,
+  result: Record<string, unknown>,
+  nestedParentContext: C | undefined,
+): void {
+  if (!nestedParentContext) {
+    return;
+  }
+
+  const values = storage.getValues();
+
+  for (const key of Object.keys(values)) {
+    const value = values[key as keyof T];
+
+    if (isAssetWrapperValue(value)) {
+      const unwrapped = value.asset;
+
+      if (Array.isArray(unwrapped)) {
+        result[key] = resolveAssetWrapperArray(
+          unwrapped,
+          nestedParentContext,
+          key,
+        );
+      } else {
+        result[key] = resolveAndWrapAsset(unwrapped, {
+          context: nestedParentContext,
+          slotName: key,
+        });
+      }
+    }
+  }
+}
+
+/**
+ * Helper: Resolves an array within an AssetWrapper
+ */
+function resolveAssetWrapperArray<C extends BaseBuildContext>(
+  array: readonly unknown[],
+  context: C,
+  key: string,
+): unknown[] {
+  // Filter out null/undefined values before processing
+  return array
+    .filter((item) => item !== null && item !== undefined)
+    .map((item, index) => {
+      const slotName = `${key}-${index}`;
+      return resolveAndWrapAsset(item, { context, slotName });
+    });
+}

package/src/core/base-builder/resolution/steps/builders.ts

@@ -0,0 +1,84 @@
+import type { BaseBuildContext } from "../../types";
+import type { ValueStorage } from "../../storage/value-storage";
+import { isAssetWrapperValue } from "../../guards";
+import { resolveAndWrapAsset, resolveValue } from "../value-resolver";
+
+/**
+ * Step 6: Resolves regular builders (non-array)
+ *
+ * Processes FluentBuilder instances and objects containing builders.
+ * Creates nested contexts for proper ID generation.
+ *
+ * @param storage - The value storage
+ * @param result - The result object being built
+ * @param nestedParentContext - Context for nested builders
+ */
+export function resolveBuilders<T, C extends BaseBuildContext>(
+  storage: ValueStorage<T>,
+  result: Record<string, unknown>,
+  nestedParentContext: C | undefined,
+): void {
+  const builders = storage.getBuilders();
+
+  builders.forEach((value, key) => {
+    // Check if this is an AssetWrapper
+    if (isAssetWrapperValue(value)) {
+      resolveBuilderAsAssetWrapper(result, key, value, nestedParentContext);
+    } else {
+      resolveBuilderNormal(result, key, value, nestedParentContext);
+    }
+  });
+}
+
+/**
+ * Helper: Resolves builder that is wrapped in AssetWrapper
+ */
+function resolveBuilderAsAssetWrapper<C extends BaseBuildContext>(
+  result: Record<string, unknown>,
+  key: string,
+  wrapperValue: { asset: unknown },
+  nestedParentContext: C | undefined,
+): void {
+  const unwrapped = wrapperValue.asset;
+
+  if (nestedParentContext) {
+    if (Array.isArray(unwrapped)) {
+      // Filter out null/undefined values before processing
+      result[key] = unwrapped
+        .filter((item) => item !== null && item !== undefined)
+        .map((item, index) => {
+          const slotName = `${key}-${index}`;
+          return resolveAndWrapAsset(item, {
+            context: nestedParentContext,
+            slotName,
+          });
+        });
+    } else {
+      result[key] = resolveAndWrapAsset(unwrapped, {
+        context: nestedParentContext,
+        slotName: key,
+      });
+    }
+  } else {
+    // No context, just resolve the wrapper
+    result[key] = resolveValue(wrapperValue, {});
+  }
+}
+
+/**
+ * Helper: Resolves builder normally (not wrapped)
+ * Uses resolveAndWrapAsset to properly wrap Asset builders in { asset: ... } format
+ */
+function resolveBuilderNormal<C extends BaseBuildContext>(
+  result: Record<string, unknown>,
+  key: string,
+  value: unknown,
+  nestedParentContext: C | undefined,
+): void {
+  // Use resolveAndWrapAsset which correctly wraps Asset builders
+  // This ensures slot properties like 'label' get wrapped in { asset: ... }
+  result[key] = resolveAndWrapAsset(value, {
+    context: nestedParentContext,
+    slotName: key,
+  });
+}