@routevn/creator-model 1.10.4 → 1.12.0

package/src/model.js

@@ -341,7 +341,7 @@ const ANIMATION_EASING_KEYS = [
   "easeInOutElastic",
 ];
 const VARIABLE_SCOPE_KEYS = ["context", "device", "account"];
-const VARIABLE_TYPE_KEYS = ["string", "number", "boolean"];
+const VARIABLE_TYPE_KEYS = ["string", "number", "boolean", "object"];
 const LAYOUT_TYPE_KEYS = [
   "general",
   "save-load",
@@ -403,7 +403,7 @@ const SAVE_LOAD_DATE_FORMATS = new Set([
   "DD MMM YYYY",
   "YYYY年MM月DD日",
 ]);
-export const SCHEMA_VERSION = 10;
+export const SCHEMA_VERSION = 12;
 const LAYOUT_CONTAINER_ELEMENT_TYPES = [
   "folder",
   "container",
@@ -1680,7 +1680,7 @@ const validateAnimationKeyframes = ({ keyframes, path, errorFactory }) => {
     {
       const result = validateAllowedKeys({
         value: keyframe,
-        allowedKeys: ["value", "duration", "easing", "relative"],
+        allowedKeys: ["value", "duration", "delay", "easing", "relative"],
         path: keyframePath,
         errorFactory,
       });
@@ -1717,6 +1717,16 @@ const validateAnimationKeyframes = ({ keyframes, path, errorFactory }) => {
       );
     }
 
+    if (
+      keyframe.delay !== undefined &&
+      (!isFiniteNumber(keyframe.delay) || keyframe.delay < 0)
+    ) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${keyframePath}.delay must be a finite number >= 0 when provided`,
+      );
+    }
+
     if (
       keyframe.easing !== undefined &&
       !ANIMATION_EASING_KEYS.includes(keyframe.easing)
@@ -2776,138 +2786,1196 @@ const validateParticleItems = ({ items, path, errorFactory }) => {
 
     {
       const result = validateAllowedKeys({
-        value: item,
-        allowedKeys:
-          item.type === "folder"
-            ? ["id", "type", "name", "description"]
-            : [
-                "id",
-                "type",
-                "name",
-                "description",
-                "tagIds",
-                "width",
-                "height",
-                "seed",
-                "modules",
-                "thumbnailFileId",
-              ],
-        path: itemPath,
+        value: item,
+        allowedKeys:
+          item.type === "folder"
+            ? ["id", "type", "name", "description"]
+            : [
+                "id",
+                "type",
+                "name",
+                "description",
+                "tagIds",
+                "width",
+                "height",
+                "seed",
+                "modules",
+                "thumbnailFileId",
+              ],
+        path: itemPath,
+        errorFactory,
+      });
+      if (result?.valid === false) {
+        return result;
+      }
+    }
+
+    if (!isNonEmptyString(item.id)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.id must be a non-empty string`,
+      );
+    }
+
+    if (item.id !== itemId) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.id must match item key '${itemId}'`,
+      );
+    }
+
+    if (!isNonEmptyString(item.name)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.name must be a non-empty string`,
+      );
+    }
+
+    if (item.description !== undefined && !isString(item.description)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.description must be a string when provided`,
+      );
+    }
+
+    if (item.type !== "particle") {
+      continue;
+    }
+
+    {
+      const result = validateOptionalUniqueIdArray({
+        value: item.tagIds,
+        path: `${itemPath}.tagIds`,
+        errorFactory,
+        allowEmpty: false,
+      });
+      if (result?.valid === false) {
+        return result;
+      }
+    }
+
+    if (!isFiniteNumber(item.width) || item.width <= 0) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.width must be a positive finite number`,
+      );
+    }
+
+    if (!isFiniteNumber(item.height) || item.height <= 0) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.height must be a positive finite number`,
+      );
+    }
+
+    if (item.seed !== undefined && !isFiniteNumber(item.seed)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.seed must be a finite number when provided`,
+      );
+    }
+
+    if (
+      item.thumbnailFileId !== undefined &&
+      !isNonEmptyString(item.thumbnailFileId)
+    ) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath}.thumbnailFileId must be a non-empty string when provided`,
+      );
+    }
+
+    {
+      const result = validateParticleModules({
+        modules: item.modules,
+        path: `${itemPath}.modules`,
+        errorFactory,
+      });
+      if (result?.valid === false) {
+        return result;
+      }
+    }
+  }
+};
+
+const validateVariableTypedValue = ({
+  value,
+  variableType,
+  path,
+  errorFactory,
+}) => {
+  if (variableType === "string" && !isString(value)) {
+    return invalidFromErrorFactory(errorFactory, `${path} must be a string`);
+  }
+
+  if (variableType === "number" && !isFiniteNumber(value)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} must be a finite number`,
+    );
+  }
+
+  if (variableType === "boolean" && typeof value !== "boolean") {
+    return invalidFromErrorFactory(errorFactory, `${path} must be a boolean`);
+  }
+
+  if (
+    variableType === "object" &&
+    (value === null || typeof value !== "object")
+  ) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} must be a non-null object or array`,
+    );
+  }
+
+  if (variableType === "object") {
+    return validateComputedDataValue({
+      value,
+      path,
+      errorFactory,
+    });
+  }
+};
+
+const COMPUTED_EXPRESSION_FIXED_OPERAND_COUNTS = Object.freeze({
+  add: 2,
+  sub: 2,
+  mul: 2,
+  div: 2,
+  mod: 2,
+  neg: 1,
+  round: 1,
+  floor: 1,
+  ceil: 1,
+  min: 2,
+  max: 2,
+  clamp: 3,
+  eq: 2,
+  neq: 2,
+  gt: 2,
+  gte: 2,
+  lt: 2,
+  lte: 2,
+  in: 2,
+  not: 1,
+  length: 1,
+  includes: 2,
+});
+const COMPUTED_EXPRESSION_VARIADIC_OPERATORS = new Set([
+  "and",
+  "or",
+  "all",
+  "any",
+]);
+const COMPUTED_EXPRESSION_NUMERIC_OPERAND_OPERATORS = new Set([
+  "add",
+  "sub",
+  "mul",
+  "div",
+  "mod",
+  "neg",
+  "round",
+  "floor",
+  "ceil",
+  "min",
+  "max",
+  "clamp",
+]);
+const COMPUTED_EXPRESSION_NUMERIC_RESULT_OPERATORS = new Set([
+  ...COMPUTED_EXPRESSION_NUMERIC_OPERAND_OPERATORS,
+  "length",
+]);
+const COMPUTED_EXPRESSION_BOOLEAN_RESULT_OPERATORS = new Set([
+  "eq",
+  "neq",
+  "gt",
+  "gte",
+  "lt",
+  "lte",
+  "in",
+  "and",
+  "or",
+  "all",
+  "any",
+  "not",
+  "includes",
+]);
+const COMPUTED_CONDITION_FIXED_OPERAND_COUNTS = Object.freeze({
+  eq: 2,
+  neq: 2,
+  gt: 2,
+  gte: 2,
+  lt: 2,
+  lte: 2,
+  in: 2,
+  add: 2,
+  sub: 2,
+});
+const COMPUTED_CONDITION_VARIADIC_OPERATORS = new Set(["all", "any"]);
+
+const getComputedValueType = (value) => {
+  if (value === null) {
+    return "null";
+  }
+  if (typeof value === "object") {
+    return "object";
+  }
+  return typeof value;
+};
+
+const validComputedResult = (valueType) => ({
+  valid: true,
+  valueType,
+});
+
+const validateComputedDataValue = ({
+  value,
+  path,
+  errorFactory,
+  ancestors = new Set(),
+}) => {
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "boolean"
+  ) {
+    return VALID_RESULT;
+  }
+
+  if (typeof value === "number") {
+    if (Number.isFinite(value)) {
+      return VALID_RESULT;
+    }
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} must use finite numeric values`,
+    );
+  }
+
+  if (Array.isArray(value)) {
+    if (ancestors.has(value)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${path} must not contain cyclic data`,
+      );
+    }
+    ancestors.add(value);
+
+    for (const [index, item] of value.entries()) {
+      const result = validateComputedDataValue({
+        value: item,
+        path: `${path}[${index}]`,
+        errorFactory,
+        ancestors,
+      });
+      if (result?.valid === false) {
+        return result;
+      }
+    }
+    ancestors.delete(value);
+    return VALID_RESULT;
+  }
+
+  if (
+    !isPlainObject(value) ||
+    ![Object.prototype, null].includes(Object.getPrototypeOf(value))
+  ) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} must contain JSON-compatible data`,
+    );
+  }
+
+  if (ancestors.has(value)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} must not contain cyclic data`,
+    );
+  }
+  ancestors.add(value);
+
+  for (const [key, item] of Object.entries(value)) {
+    const result = validateComputedDataValue({
+      value: item,
+      path: `${path}.${key}`,
+      errorFactory,
+      ancestors,
+    });
+    if (result?.valid === false) {
+      return result;
+    }
+  }
+
+  ancestors.delete(value);
+  return VALID_RESULT;
+};
+
+const invalidComputedReferenceParseResult = Object.freeze({
+  valid: false,
+});
+
+const decodeComputedReferenceQuotedPart = (rawValue) => {
+  if (rawValue[0] === '"') {
+    try {
+      return {
+        valid: true,
+        value: JSON.parse(rawValue),
+      };
+    } catch {
+      return invalidComputedReferenceParseResult;
+    }
+  }
+
+  let value = "";
+  const escapedValues = {
+    "\\": "\\",
+    '"': '"',
+    "'": "'",
+    "/": "/",
+    n: "\n",
+    r: "\r",
+    t: "\t",
+    b: "\b",
+    f: "\f",
+  };
+
+  for (let index = 1; index < rawValue.length - 1; index += 1) {
+    const character = rawValue[index];
+    if (character !== "\\") {
+      if (character.charCodeAt(0) < 0x20) {
+        return invalidComputedReferenceParseResult;
+      }
+      value += character;
+      continue;
+    }
+
+    index += 1;
+    if (index >= rawValue.length - 1) {
+      return invalidComputedReferenceParseResult;
+    }
+
+    const escapedCharacter = rawValue[index];
+    if (escapedCharacter === "u") {
+      const hexValue = rawValue.slice(index + 1, index + 5);
+      if (hexValue.length !== 4 || !/^[0-9a-fA-F]{4}$/.test(hexValue)) {
+        return invalidComputedReferenceParseResult;
+      }
+      value += String.fromCharCode(Number.parseInt(hexValue, 16));
+      index += 4;
+      continue;
+    }
+
+    if (!Object.hasOwn(escapedValues, escapedCharacter)) {
+      return invalidComputedReferenceParseResult;
+    }
+    value += escapedValues[escapedCharacter];
+  }
+
+  return {
+    valid: true,
+    value,
+  };
+};
+
+const parseComputedReferencePath = (value) => {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.trim() !== value
+  ) {
+    return invalidComputedReferenceParseResult;
+  }
+
+  const parts = [];
+  let index = 0;
+
+  const readBarePart = () => {
+    const startIndex = index;
+    while (
+      index < value.length &&
+      value[index] !== "." &&
+      value[index] !== "[" &&
+      value[index] !== "]"
+    ) {
+      index += 1;
+    }
+
+    const part = value.slice(startIndex, index);
+    if (part.length === 0 || part.trim() !== part || /\s/.test(part)) {
+      return false;
+    }
+    parts.push(part);
+    return true;
+  };
+
+  const readBracketPart = () => {
+    index += 1;
+    while (index < value.length && /\s/.test(value[index])) {
+      index += 1;
+    }
+
+    const firstCharacter = value[index];
+    if (/\d/.test(firstCharacter ?? "")) {
+      const startIndex = index;
+      while (index < value.length && /\d/.test(value[index])) {
+        index += 1;
+      }
+      const rawPart = value.slice(startIndex, index);
+      while (index < value.length && /\s/.test(value[index])) {
+        index += 1;
+      }
+      if (
+        value[index] !== "]" ||
+        (rawPart.length > 1 && rawPart.startsWith("0"))
+      ) {
+        return false;
+      }
+      index += 1;
+      parts.push(rawPart);
+      return true;
+    }
+
+    if (firstCharacter !== '"' && firstCharacter !== "'") {
+      return false;
+    }
+
+    const quote = firstCharacter;
+    const startIndex = index;
+    index += 1;
+    let escaped = false;
+    while (index < value.length) {
+      const character = value[index];
+      if (escaped) {
+        escaped = false;
+      } else if (character === "\\") {
+        escaped = true;
+      } else if (character === quote) {
+        const decodedPart = decodeComputedReferenceQuotedPart(
+          value.slice(startIndex, index + 1),
+        );
+        if (!decodedPart.valid) {
+          return false;
+        }
+
+        index += 1;
+        while (index < value.length && /\s/.test(value[index])) {
+          index += 1;
+        }
+        if (value[index] !== "]") {
+          return false;
+        }
+        index += 1;
+        parts.push(decodedPart.value);
+        return true;
+      }
+      index += 1;
+    }
+
+    return false;
+  };
+
+  if (!readBarePart()) {
+    return invalidComputedReferenceParseResult;
+  }
+
+  while (index < value.length) {
+    if (value[index] === ".") {
+      index += 1;
+      if (!readBarePart()) {
+        return invalidComputedReferenceParseResult;
+      }
+      continue;
+    }
+
+    if (value[index] === "[") {
+      if (!readBracketPart()) {
+        return invalidComputedReferenceParseResult;
+      }
+      continue;
+    }
+
+    return invalidComputedReferenceParseResult;
+  }
+
+  return {
+    valid: true,
+    parts,
+  };
+};
+
+const validateComputedReferencePath = ({
+  value,
+  path,
+  errorFactory,
+  variables,
+  dependencies,
+}) => {
+  if (!isNonEmptyString(value)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} must be a non-empty string path`,
+    );
+  }
+
+  const parsedPath = parseComputedReferencePath(value);
+  if (!parsedPath.valid) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} has an invalid reference path`,
+    );
+  }
+
+  const [root, referencedId, ...nestedPath] = parsedPath.parts;
+  if (root !== "variables" && root !== "runtime") {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} must reference a concrete variables.* or runtime.* path`,
+    );
+  }
+
+  if (!isNonEmptyString(referencedId)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} must reference a concrete ${root} member`,
+    );
+  }
+
+  if (root === "runtime" || variables === undefined) {
+    return validComputedResult(undefined);
+  }
+
+  const referencedVariable = Object.hasOwn(variables, referencedId)
+    ? variables[referencedId]
+    : undefined;
+  if (
+    !isPlainObject(referencedVariable) ||
+    referencedVariable.type !== "variable"
+  ) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} references unknown variable '${referencedId}'`,
+    );
+  }
+
+  if (Object.hasOwn(referencedVariable, "computed")) {
+    dependencies?.add(referencedId);
+  }
+
+  return validComputedResult(
+    nestedPath.length === 0 ? referencedVariable.variableType : undefined,
+  );
+};
+
+const validateComputedExpression = ({
+  expression,
+  path,
+  errorFactory,
+  variables,
+  dependencies,
+  ancestors = new Set(),
+}) => {
+  if (expression === null) {
+    return validComputedResult("null");
+  }
+
+  if (typeof expression !== "object") {
+    if (typeof expression === "number") {
+      if (Number.isFinite(expression)) {
+        return validComputedResult("number");
+      }
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${path} must use finite numeric literals`,
+      );
+    }
+
+    if (typeof expression === "string" || typeof expression === "boolean") {
+      return validComputedResult(typeof expression);
+    }
+
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} must use JSON-compatible primitive literals`,
+    );
+  }
+
+  if (Array.isArray(expression)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} arrays must be wrapped in a literal operator or authored as value`,
+    );
+  }
+
+  if (ancestors.has(expression)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} must not contain cyclic expression data`,
+    );
+  }
+  const nextAncestors = new Set(ancestors);
+  nextAncestors.add(expression);
+
+  const entries = Object.entries(expression);
+  if (entries.length !== 1) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} must contain exactly one expression operator`,
+    );
+  }
+
+  const [[operator, operands]] = entries;
+  if (operator === "var") {
+    const result = validateComputedReferencePath({
+      value: operands,
+      path: `${path}.var`,
+      errorFactory,
+      variables,
+      dependencies,
+    });
+    return result;
+  }
+
+  if (operator === "literal") {
+    const result = validateComputedDataValue({
+      value: operands,
+      path: `${path}.literal`,
+      errorFactory,
+    });
+    return result?.valid === false
+      ? result
+      : validComputedResult(getComputedValueType(operands));
+  }
+
+  const fixedOperandCount = COMPUTED_EXPRESSION_FIXED_OPERAND_COUNTS[operator];
+  const isVariadic = COMPUTED_EXPRESSION_VARIADIC_OPERATORS.has(operator);
+  if (fixedOperandCount === undefined && !isVariadic) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} contains unsupported expression operator '${operator}'`,
+    );
+  }
+
+  if (!Array.isArray(operands)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path}.${operator} must be an operand array`,
+    );
+  }
+
+  if (
+    (fixedOperandCount !== undefined &&
+      operands.length !== fixedOperandCount) ||
+    (isVariadic && operands.length === 0)
+  ) {
+    const operandRequirement = isVariadic
+      ? "at least one operand"
+      : `exactly ${fixedOperandCount} operands`;
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path}.${operator} requires ${operandRequirement}`,
+    );
+  }
+
+  const operandTypes = [];
+  for (const [index, operand] of operands.entries()) {
+    const result = validateComputedExpression({
+      expression: operand,
+      path: `${path}.${operator}[${index}]`,
+      errorFactory,
+      variables,
+      dependencies,
+      ancestors: nextAncestors,
+    });
+    if (result?.valid === false) {
+      return result;
+    }
+    operandTypes.push(result.valueType);
+  }
+
+  if (
+    COMPUTED_EXPRESSION_NUMERIC_OPERAND_OPERATORS.has(operator) &&
+    operandTypes.some(
+      (operandType) => operandType !== undefined && operandType !== "number",
+    )
+  ) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path}.${operator} requires numeric operands`,
+    );
+  }
+
+  if (COMPUTED_EXPRESSION_NUMERIC_RESULT_OPERATORS.has(operator)) {
+    return validComputedResult("number");
+  }
+  if (COMPUTED_EXPRESSION_BOOLEAN_RESULT_OPERATORS.has(operator)) {
+    return validComputedResult("boolean");
+  }
+  return validComputedResult(undefined);
+};
+
+const validateComputedCondition = ({
+  condition,
+  path,
+  errorFactory,
+  variables,
+  dependencies,
+  isRoot = true,
+  ancestors = new Set(),
+}) => {
+  if (isRoot && typeof condition === "string") {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} string conditions are not supported`,
+    );
+  }
+
+  if (condition === null) {
+    return validComputedResult("null");
+  }
+
+  if (typeof condition !== "object") {
+    if (typeof condition === "number") {
+      if (Number.isFinite(condition)) {
+        return validComputedResult("number");
+      }
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${path} must use finite numeric literals`,
+      );
+    }
+
+    if (typeof condition === "string" || typeof condition === "boolean") {
+      return validComputedResult(typeof condition);
+    }
+
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} must use JSON-compatible primitive literals`,
+    );
+  }
+
+  if (Array.isArray(condition)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} arrays must be wrapped in a condition operator or literal`,
+    );
+  }
+
+  if (ancestors.has(condition)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} must not contain cyclic condition data`,
+    );
+  }
+  const nextAncestors = new Set(ancestors);
+  nextAncestors.add(condition);
+
+  const entries = Object.entries(condition);
+  if (entries.length !== 1) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} must contain exactly one condition operator`,
+    );
+  }
+
+  const [[operator, operands]] = entries;
+  if (operator === "var") {
+    const result = validateComputedReferencePath({
+      value: operands,
+      path: `${path}.var`,
+      errorFactory,
+      variables,
+      dependencies,
+    });
+    return result;
+  }
+  if (operator === "literal") {
+    const result = validateComputedDataValue({
+      value: operands,
+      path: `${path}.literal`,
+      errorFactory,
+    });
+    return result?.valid === false
+      ? result
+      : validComputedResult(getComputedValueType(operands));
+  }
+  if (operator === "call") {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} function calls are not supported`,
+    );
+  }
+  if (operator === "not") {
+    const result = validateComputedCondition({
+      condition: operands,
+      path: `${path}.not`,
+      errorFactory,
+      variables,
+      dependencies,
+      isRoot: false,
+      ancestors: nextAncestors,
+    });
+    return result?.valid === false ? result : validComputedResult("boolean");
+  }
+
+  const fixedOperandCount = COMPUTED_CONDITION_FIXED_OPERAND_COUNTS[operator];
+  const isVariadic = COMPUTED_CONDITION_VARIADIC_OPERATORS.has(operator);
+  if (fixedOperandCount === undefined && !isVariadic) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} contains unsupported condition operator '${operator}'`,
+    );
+  }
+  if (!Array.isArray(operands)) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path}.${operator} must be an operand array`,
+    );
+  }
+  if (
+    (fixedOperandCount !== undefined &&
+      operands.length !== fixedOperandCount) ||
+    (isVariadic && operands.length === 0)
+  ) {
+    const operandRequirement = isVariadic
+      ? "at least one operand"
+      : `exactly ${fixedOperandCount} operands`;
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path}.${operator} requires ${operandRequirement}`,
+    );
+  }
+
+  const operandTypes = [];
+  for (const [index, operand] of operands.entries()) {
+    const result = validateComputedCondition({
+      condition: operand,
+      path: `${path}.${operator}[${index}]`,
+      errorFactory,
+      variables,
+      dependencies,
+      isRoot: false,
+      ancestors: nextAncestors,
+    });
+    if (result?.valid === false) {
+      return result;
+    }
+    operandTypes.push(result.valueType);
+  }
+
+  if (
+    (operator === "add" || operator === "sub") &&
+    operandTypes.some(
+      (operandType) => operandType !== undefined && operandType !== "number",
+    )
+  ) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path}.${operator} requires numeric operands`,
+    );
+  }
+
+  return validComputedResult(
+    operator === "add" || operator === "sub" ? "number" : "boolean",
+  );
+};
+
+const validateComputedResultConfig = ({
+  resultConfig,
+  variableType,
+  path,
+  errorFactory,
+  variables,
+  dependencies,
+  allowedKeys = ["expr", "value"],
+}) => {
+  if (!isPlainObject(resultConfig)) {
+    return invalidFromErrorFactory(errorFactory, `${path} must be an object`);
+  }
+
+  {
+    const result = validateAllowedKeys({
+      value: resultConfig,
+      allowedKeys,
+      path,
+      errorFactory,
+    });
+    if (result?.valid === false) {
+      return result;
+    }
+  }
+
+  const hasExpression = Object.hasOwn(resultConfig, "expr");
+  const hasValue = Object.hasOwn(resultConfig, "value");
+  if (hasExpression === hasValue) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path} must contain exactly one of expr or value`,
+    );
+  }
+
+  if (hasValue) {
+    const dataResult = validateComputedDataValue({
+      value: resultConfig.value,
+      path: `${path}.value`,
+      errorFactory,
+    });
+    if (dataResult?.valid === false) {
+      return dataResult;
+    }
+    return validateVariableTypedValue({
+      value: resultConfig.value,
+      variableType,
+      path: `${path}.value`,
+      errorFactory,
+    });
+  }
+
+  const expressionResult = validateComputedExpression({
+    expression: resultConfig.expr,
+    path: `${path}.expr`,
+    errorFactory,
+    variables,
+    dependencies,
+  });
+  if (expressionResult?.valid === false) {
+    return expressionResult;
+  }
+  if (
+    expressionResult.valueType !== undefined &&
+    expressionResult.valueType !== variableType
+  ) {
+    return invalidFromErrorFactory(
+      errorFactory,
+      `${path}.expr must resolve to ${variableType}`,
+    );
+  }
+  return VALID_RESULT;
+};
+
+const validateVariableComputedConfig = ({
+  computed,
+  variableType,
+  path,
+  errorFactory,
+  variables,
+  dependencies,
+}) => {
+  if (!isPlainObject(computed)) {
+    return invalidFromErrorFactory(errorFactory, `${path} must be an object`);
+  }
+
+  if (Object.hasOwn(computed, "branches")) {
+    {
+      const result = validateAllowedKeys({
+        value: computed,
+        allowedKeys: ["branches", "default"],
+        path,
         errorFactory,
       });
       if (result?.valid === false) {
         return result;
       }
     }
-
-    if (!isNonEmptyString(item.id)) {
+    if (!Array.isArray(computed.branches) || computed.branches.length === 0) {
       return invalidFromErrorFactory(
         errorFactory,
-        `${itemPath}.id must be a non-empty string`,
+        `${path}.branches must be a non-empty array`,
       );
     }
-
-    if (item.id !== itemId) {
+    if (!isPlainObject(computed.default)) {
       return invalidFromErrorFactory(
         errorFactory,
-        `${itemPath}.id must match item key '${itemId}'`,
+        `${path}.default must be an object`,
       );
     }
 
-    if (!isNonEmptyString(item.name)) {
-      return invalidFromErrorFactory(
+    for (const [index, branch] of computed.branches.entries()) {
+      const branchPath = `${path}.branches[${index}]`;
+      if (!isPlainObject(branch)) {
+        return invalidFromErrorFactory(
+          errorFactory,
+          `${branchPath} must be an object`,
+        );
+      }
+      if (!Object.hasOwn(branch, "when")) {
+        return invalidFromErrorFactory(
+          errorFactory,
+          `${branchPath}.when is required`,
+        );
+      }
+      const conditionResult = validateComputedCondition({
+        condition: branch.when,
+        path: `${branchPath}.when`,
         errorFactory,
-        `${itemPath}.name must be a non-empty string`,
-      );
-    }
-
-    if (item.description !== undefined && !isString(item.description)) {
-      return invalidFromErrorFactory(
+        variables,
+        dependencies,
+      });
+      if (conditionResult?.valid === false) {
+        return conditionResult;
+      }
+      const branchResult = validateComputedResultConfig({
+        resultConfig: branch,
+        variableType,
+        path: branchPath,
         errorFactory,
-        `${itemPath}.description must be a string when provided`,
-      );
+        variables,
+        dependencies,
+        allowedKeys: ["when", "expr", "value"],
+      });
+      if (branchResult?.valid === false) {
+        return branchResult;
+      }
     }
 
-    if (item.type !== "particle") {
+    return validateComputedResultConfig({
+      resultConfig: computed.default,
+      variableType,
+      path: `${path}.default`,
+      errorFactory,
+      variables,
+      dependencies,
+    });
+  }
+
+  return validateComputedResultConfig({
+    resultConfig: computed,
+    variableType,
+    path,
+    errorFactory,
+    variables,
+    dependencies,
+  });
+};
+
+const validateComputedVariableGraph = ({ items, path, errorFactory }) => {
+  const dependencyGraph = new Map();
+
+  for (const [variableId, variable] of Object.entries(items)) {
+    if (variable?.type !== "variable" || !Object.hasOwn(variable, "computed")) {
       continue;
     }
 
-    {
-      const result = validateOptionalUniqueIdArray({
-        value: item.tagIds,
-        path: `${itemPath}.tagIds`,
-        errorFactory,
-        allowEmpty: false,
-      });
-      if (result?.valid === false) {
-        return result;
-      }
+    const dependencies = new Set();
+    const result = validateVariableComputedConfig({
+      computed: variable.computed,
+      variableType: variable.variableType,
+      path: `${path}.${variableId}.computed`,
+      errorFactory,
+      variables: items,
+      dependencies,
+    });
+    if (result?.valid === false) {
+      return result;
     }
+    dependencyGraph.set(variableId, dependencies);
+  }
 
-    if (!isFiniteNumber(item.width) || item.width <= 0) {
-      return invalidFromErrorFactory(
-        errorFactory,
-        `${itemPath}.width must be a positive finite number`,
-      );
+  const visited = new Set();
+  for (const startVariableId of dependencyGraph.keys()) {
+    if (visited.has(startVariableId)) {
+      continue;
     }
 
-    if (!isFiniteNumber(item.height) || item.height <= 0) {
-      return invalidFromErrorFactory(
-        errorFactory,
-        `${itemPath}.height must be a positive finite number`,
-      );
-    }
+    const frames = [
+      {
+        variableId: startVariableId,
+        dependencies: [...(dependencyGraph.get(startVariableId) ?? [])],
+        nextDependencyIndex: 0,
+      },
+    ];
+    const activeIndexes = new Map([[startVariableId, 0]]);
+
+    while (frames.length > 0) {
+      const frame = frames.at(-1);
+      if (frame.nextDependencyIndex >= frame.dependencies.length) {
+        frames.pop();
+        activeIndexes.delete(frame.variableId);
+        visited.add(frame.variableId);
+        continue;
+      }
 
-    if (item.seed !== undefined && !isFiniteNumber(item.seed)) {
-      return invalidFromErrorFactory(
-        errorFactory,
-        `${itemPath}.seed must be a finite number when provided`,
-      );
-    }
+      const dependencyId = frame.dependencies[frame.nextDependencyIndex];
+      frame.nextDependencyIndex += 1;
+      if (visited.has(dependencyId)) {
+        continue;
+      }
 
-    if (
-      item.thumbnailFileId !== undefined &&
-      !isNonEmptyString(item.thumbnailFileId)
-    ) {
-      return invalidFromErrorFactory(
-        errorFactory,
-        `${itemPath}.thumbnailFileId must be a non-empty string when provided`,
-      );
-    }
+      const cycleStartIndex = activeIndexes.get(dependencyId);
+      if (cycleStartIndex !== undefined) {
+        const cycle = [
+          ...frames.slice(cycleStartIndex).map(({ variableId }) => variableId),
+          dependencyId,
+        ].join(" -> ");
+        return invalidFromErrorFactory(
+          errorFactory,
+          `${path} contains computed variable cycle: ${cycle}`,
+        );
+      }
 
-    {
-      const result = validateParticleModules({
-        modules: item.modules,
-        path: `${itemPath}.modules`,
-        errorFactory,
-      });
-      if (result?.valid === false) {
-        return result;
+      if (!dependencyGraph.has(dependencyId)) {
+        visited.add(dependencyId);
+        continue;
       }
+
+      activeIndexes.set(dependencyId, frames.length);
+      frames.push({
+        variableId: dependencyId,
+        dependencies: [...(dependencyGraph.get(dependencyId) ?? [])],
+        nextDependencyIndex: 0,
+      });
     }
   }
+
+  return VALID_RESULT;
 };
 
-const validateVariableTypedValue = ({
-  value,
+const validateVariableStoredOrComputedData = ({
+  data,
   variableType,
   path,
   errorFactory,
 }) => {
-  if (variableType === "string" && !isString(value)) {
-    return invalidFromErrorFactory(errorFactory, `${path} must be a string`);
-  }
-
-  if (variableType === "number" && !isFiniteNumber(value)) {
-    return invalidFromErrorFactory(
+  const isComputed = Object.hasOwn(data, "computed");
+  if (isComputed) {
+    if (Object.hasOwn(data, "default") || Object.hasOwn(data, "value")) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${path} computed variables must not contain default or value`,
+      );
+    }
+    if (data.isEnum !== undefined || data.enumValues !== undefined) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${path} computed variables must not contain enum metadata`,
+      );
+    }
+    return validateVariableComputedConfig({
+      computed: data.computed,
+      variableType,
+      path: `${path}.computed`,
       errorFactory,
-      `${path} must be a finite number`,
-    );
+    });
   }
 
-  if (variableType === "boolean" && typeof value !== "boolean") {
-    return invalidFromErrorFactory(errorFactory, `${path} must be a boolean`);
+  {
+    const result = validateVariableTypedValue({
+      value: data.default,
+      variableType,
+      path: `${path}.default`,
+      errorFactory,
+    });
+    if (result?.valid === false) {
+      return result;
+    }
   }
+  return validateVariableTypedValue({
+    value: data.value,
+    variableType,
+    path: `${path}.value`,
+    errorFactory,
+  });
 };
 
 const normalizeVariableEnumValues = (values = []) => {
@@ -2995,6 +4063,13 @@ const validateVariableItems = ({ items, path, errorFactory }) => {
     const itemType = item?.type;
     const variableType = item?.variableType;
 
+    if (itemId === "__proto__") {
+      return invalidFromErrorFactory(
+        errorFactory,
+        `${itemPath} uses reserved variable id '__proto__'`,
+      );
+    }
+
     if (itemType !== "folder" && itemType !== "variable") {
       return invalidFromErrorFactory(
         errorFactory,
@@ -3020,6 +4095,7 @@ const validateVariableItems = ({ items, path, errorFactory }) => {
                 "value",
                 "isEnum",
                 "enumValues",
+                "computed",
               ],
         path: itemPath,
         errorFactory,
@@ -3061,7 +4137,7 @@ const validateVariableItems = ({ items, path, errorFactory }) => {
       if (!VARIABLE_TYPE_KEYS.includes(variableType)) {
         return invalidFromErrorFactory(
           errorFactory,
-          `${itemPath}.variableType must be 'string', 'number', or 'boolean'`,
+          `${itemPath}.variableType must be 'string', 'number', 'boolean', or 'object'`,
         );
       }
 
@@ -3089,7 +4165,14 @@ const validateVariableItems = ({ items, path, errorFactory }) => {
         }
       }
 
-      if (!VARIABLE_SCOPE_KEYS.includes(item.scope)) {
+      if (item.computed !== undefined) {
+        if (item.scope !== undefined) {
+          return invalidFromErrorFactory(
+            errorFactory,
+            `${itemPath}.scope must be omitted for computed variables`,
+          );
+        }
+      } else if (!VARIABLE_SCOPE_KEYS.includes(item.scope)) {
         return invalidFromErrorFactory(
           errorFactory,
           `${itemPath}.scope must be 'context', 'device', or 'account'`,
@@ -3097,21 +4180,10 @@ const validateVariableItems = ({ items, path, errorFactory }) => {
       }
 
       {
-        const result = validateVariableTypedValue({
-          value: item.default,
-          variableType,
-          path: `${itemPath}.default`,
-          errorFactory,
-        });
-        if (result?.valid === false) {
-          return result;
-        }
-      }
-      {
-        const result = validateVariableTypedValue({
-          value: item.value,
+        const result = validateVariableStoredOrComputedData({
+          data: item,
           variableType,
-          path: `${itemPath}.value`,
+          path: itemPath,
           errorFactory,
         });
         if (result?.valid === false) {
@@ -3120,6 +4192,12 @@ const validateVariableItems = ({ items, path, errorFactory }) => {
       }
     }
   }
+
+  return validateComputedVariableGraph({
+    items,
+    path,
+    errorFactory,
+  });
 };
 
 const validateTextStyleShadow = ({ shadow, path, errorFactory }) => {
@@ -11070,6 +12148,7 @@ const validateVariableCreateData = ({ data, errorFactory }) => {
               "value",
               "isEnum",
               "enumValues",
+              "computed",
             ],
       path: "payload.data",
       errorFactory,
@@ -11097,7 +12176,7 @@ const validateVariableCreateData = ({ data, errorFactory }) => {
     if (!VARIABLE_TYPE_KEYS.includes(data.variableType)) {
       return invalidFromErrorFactory(
         errorFactory,
-        "payload.data.variableType must be 'string', 'number', or 'boolean'",
+        "payload.data.variableType must be 'string', 'number', 'boolean', or 'object'",
       );
     }
 
@@ -11124,7 +12203,14 @@ const validateVariableCreateData = ({ data, errorFactory }) => {
       }
     }
 
-    if (!VARIABLE_SCOPE_KEYS.includes(data.scope)) {
+    if (data.computed !== undefined) {
+      if (data.scope !== undefined) {
+        return invalidFromErrorFactory(
+          errorFactory,
+          "payload.data.scope must be omitted for computed variables",
+        );
+      }
+    } else if (!VARIABLE_SCOPE_KEYS.includes(data.scope)) {
       return invalidFromErrorFactory(
         errorFactory,
         "payload.data.scope must be 'context', 'device', or 'account'",
@@ -11132,21 +12218,10 @@ const validateVariableCreateData = ({ data, errorFactory }) => {
     }
 
     {
-      const result = validateVariableTypedValue({
-        value: data.default,
-        variableType: data.variableType,
-        path: "payload.data.default",
-        errorFactory,
-      });
-      if (result?.valid === false) {
-        return result;
-      }
-    }
-    {
-      const result = validateVariableTypedValue({
-        value: data.value,
+      const result = validateVariableStoredOrComputedData({
+        data,
         variableType: data.variableType,
-        path: "payload.data.value",
+        path: "payload.data",
         errorFactory,
       });
       if (result?.valid === false) {
@@ -11169,6 +12244,7 @@ const validateVariableUpdateData = ({ data, errorFactory }) => {
         "value",
         "isEnum",
         "enumValues",
+        "computed",
       ],
       path: "payload.data",
       errorFactory,
@@ -11217,6 +12293,15 @@ const validateVariableUpdateData = ({ data, errorFactory }) => {
     }
   }
 
+  if (data.computed !== undefined) {
+    if (!isPlainObject(data.computed)) {
+      return invalidFromErrorFactory(
+        errorFactory,
+        "payload.data.computed must be an object when provided",
+      );
+    }
+  }
+
   if (data.scope !== undefined && !VARIABLE_SCOPE_KEYS.includes(data.scope)) {
     return invalidFromErrorFactory(
       errorFactory,
@@ -13038,6 +14123,7 @@ const createFolderedCollectionCommandDefinitions = ({
   validateDeleteState = () => {},
   afterDelete = () => {},
   includeUpdate = true,
+  reservedItemIds = [],
 }) => {
   const existingMessage = `payload.${idField} must reference an existing ${itemLabel}`;
   const duplicateMessage = `payload.${idField} must not already exist`;
@@ -13078,6 +14164,12 @@ const createFolderedCollectionCommandDefinitions = ({
           );
         }
 
+        if (reservedItemIds.includes(payload[idField])) {
+          return invalidPayload(
+            `payload.${idField} must not use reserved id '${payload[idField]}'`,
+          );
+        }
+
         if (
           payload.parentId !== undefined &&
           payload.parentId !== null &&
@@ -18514,6 +19606,7 @@ const COMMAND_DEFINITIONS = [
     itemLabel: "variable item",
     createDataValidator: validateVariableCreateData,
     updateDataValidator: validateVariableUpdateData,
+    reservedItemIds: ["__proto__"],
     createItem: ({ payload }) => {
       const data = structuredClone(payload.data);
       if (!Array.isArray(data.tagIds) || data.tagIds.length === 0) {
@@ -18538,7 +19631,7 @@ const COMMAND_DEFINITIONS = [
         return;
       }
 
-      return validateTagIdsAgainstScope({
+      const tagResult = validateTagIdsAgainstScope({
         state,
         tagIds: payload.data.tagIds,
         scopeKey: "variables",
@@ -18547,6 +19640,25 @@ const COMMAND_DEFINITIONS = [
           variableId: payload.variableId,
         },
       });
+      if (!tagResult.valid) {
+        return tagResult;
+      }
+
+      if (!Object.hasOwn(payload.data, "computed")) {
+        return VALID_RESULT;
+      }
+
+      return validateComputedVariableGraph({
+        items: {
+          ...state.variables.items,
+          [payload.variableId]: {
+            id: payload.variableId,
+            ...payload.data,
+          },
+        },
+        path: "state.variables.items",
+        errorFactory: createPreconditionValidationError,
+      });
     },
     validateUpdateState: ({ state, payload, currentItem }) => {
       if (
@@ -18570,6 +19682,36 @@ const COMMAND_DEFINITIONS = [
         );
       }
 
+      const currentItemIsComputed = Object.hasOwn(currentItem, "computed");
+      if (
+        currentItemIsComputed &&
+        ["scope", "default", "value", "isEnum", "enumValues"].some((key) =>
+          Object.hasOwn(payload.data, key),
+        )
+      ) {
+        return invalidPrecondition(
+          "computed variables cannot update scope, stored value, or enum fields",
+        );
+      }
+
+      if (!currentItemIsComputed && Object.hasOwn(payload.data, "computed")) {
+        return invalidPrecondition(
+          "stored variables cannot be converted to computed variables",
+        );
+      }
+
+      if (currentItemIsComputed && Object.hasOwn(payload.data, "computed")) {
+        const result = validateVariableComputedConfig({
+          computed: payload.data.computed,
+          variableType: currentItem.variableType,
+          path: "payload.data.computed",
+          errorFactory: createPreconditionValidationError,
+        });
+        if (result?.valid === false) {
+          return result;
+        }
+      }
+
       if (currentItem.type !== "folder") {
         {
           const result = validateTagIdsAgainstScope({
@@ -18614,6 +19756,49 @@ const COMMAND_DEFINITIONS = [
           }
         }
       }
+
+      if (currentItemIsComputed && Object.hasOwn(payload.data, "computed")) {
+        return validateComputedVariableGraph({
+          items: {
+            ...state.variables.items,
+            [payload.variableId]: applyVariableUpdate({
+              currentItem,
+              data: payload.data,
+            }),
+          },
+          path: "state.variables.items",
+          errorFactory: createPreconditionValidationError,
+        });
+      }
+
+      return VALID_RESULT;
+    },
+    validateDeleteState: ({ state, payload }) => {
+      const deletedIds = new Set();
+      for (const variableId of payload.variableIds) {
+        const node = findTreeNode({
+          nodes: state.variables.tree,
+          nodeId: variableId,
+        });
+        if (!node) {
+          deletedIds.add(variableId);
+          continue;
+        }
+        for (const descendantId of collectTreeDescendantIds({ node })) {
+          deletedIds.add(descendantId);
+        }
+      }
+
+      const remainingItems = Object.fromEntries(
+        Object.entries(state.variables.items).filter(
+          ([variableId]) => !deletedIds.has(variableId),
+        ),
+      );
+      return validateComputedVariableGraph({
+        items: remainingItems,
+        path: "state.variables.items",
+        errorFactory: createPreconditionValidationError,
+      });
     },
   }),
   ...createFolderedCollectionCommandDefinitions({