Improved GLTF API (#282)

* feat(gltf-scene): introduce GLTF Scene Modification API and related components

- Added a new GLTF Scene Modification API, including components like GltfScene, Modify, and hooks for entity management.
- Implemented context for managing GLTF scene state and hierarchy.
- Introduced examples demonstrating the usage of the new API for modifying GLTF assets.
- Updated existing components (Camera, Light, Render) to export their definitions for better integration with the new API.
- Added type definitions for improved TypeScript support.

This commit enhances the library's capabilities for declarative modifications of GLTF assets, providing a more flexible and powerful way to manage 3D scenes.

* feat: add new <Gltf/> API for enhanced 3D scene management

* refactor(gltf): restructure GLTF API and introduce new components

- Moved GLTF scene management to a dedicated API, enhancing modularity and usability.
- Introduced new components: Gltf, Modify, and associated hooks for improved entity manipulation.
- Updated type definitions and context management for better integration and TypeScript support.
- Added examples demonstrating the new API's capabilities for modifying GLTF assets.
- Removed deprecated components and streamlined the overall structure for clarity.

This commit significantly enhances the library's functionality for declarative modifications of GLTF assets, providing a more robust framework for 3D scene management.

* Improve tests

* fix(gltf): enhance Gltf component and integration tests

- Updated the Gltf component to include a check for the parent entity in the useEffect hook, improving asset instantiation logic.
- Refactored integration tests to improve clarity and coverage, including modifications to existing component props and handling of edge cases.
- Adjusted test assertions to ensure proper state before and after modifications, enhancing reliability of test outcomes.
- Improved the structure of test cases for better readability and maintainability.

* refactor(gltf): enhance integration tests with new test components

- Introduced a new file containing test component fixtures to streamline integration tests for the Gltf component.
- Replaced direct Gltf usage in tests with specific test components to improve clarity and maintainability.
- Updated various test cases to utilize the new components, demonstrating different GLTF modification patterns.
- Enhanced the overall structure of integration tests for better readability and organization.

* add warnings tests

* feat(gltf): add warnings for adding existing components to entities

- Enhanced the RuleProcessor component to check for existing components on entities before adding new ones.
- Introduced a warning mechanism to inform users when attempting to add a component that already exists, guiding them to use modification actions instead.
- Updated tests to reflect changes in component handling and ensure proper functionality.

* Fixed entity cast

* updated changeset

* Update packages/lib/src/gltf/examples.tsx

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* refactor(gltf): update rule merging logic to use MODIFY_COMPONENT action

- Changed instances of REMOVE_COMPONENT to MODIFY_COMPONENT in rule merging tests to reflect updated action handling.
- Enhanced test cases to ensure proper functionality of component modifications, including the addition of props for removal.
- Improved clarity and maintainability of tests by aligning with the new action structure.

* refactor(tests): enhance rule merging tests for clarity and accuracy

- Updated assertions in the rule merging test to explicitly check the winning rule's ID, action type, and properties.
- Improved test readability by assigning the winning action to a variable for clearer context.
- Ensured that the tests accurately reflect the expected behavior of the merging logic with the MODIFY_COMPONENT action.

* Update packages/lib/src/gltf/components/Gltf.tsx

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* refactor(gltf): optimize child clearing logic in RuleProcessor component

- Improved efficiency of child clearing by using a Map for O(1) lookups of current children by GUID.
- Updated the logic to find original children, enhancing performance and clarity of the code.
- Ensured that the functionality remains intact while streamlining the process of managing entity children.

* fix(gltf): correct import extension and add useEntity tests

- Updated the import of useParent from '.ts' to '.tsx' for consistency.
- Introduced comprehensive tests for the useEntity hook, covering various path matching scenarios, wildcard usage, and predicate functions.
- Enhanced test coverage to ensure accurate entity retrieval and handling of edge cases.

* fix(gltf): resolve entity component duplication warnings

- Implemented logic in the RuleProcessor to prevent adding duplicate components to entities.
- Added warning messages to inform users when attempting to add an existing component, promoting the use of modification actions.
- Updated tests to verify the new warning functionality and ensure correct handling of component additions.

* test(gltf): add comprehensive tests for functional prop updates

- Introduced multiple test cases to validate the behavior of functional updates for light and render components.
- Ensured correct handling of various scenarios, including undefined values, boolean toggles, and zero values.
- Enhanced test coverage for the Modify component to verify the integration of functional updates with direct prop modifications.

* Update .changeset/stale-pandas-fetch.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* feat(gltf): enhance useEntity hook with PathMatcher for improved entity retrieval

- Integrated PathMatcher into the useEntity hook to support consistent path matching, including component filters and wildcards.
- Updated the logic for finding entities by pattern, allowing for more flexible and efficient entity searches.
- Added comprehensive tests to validate the new functionality, ensuring correct behavior with various path patterns and component filters.

* refactor(gltf): improve useEntity hook for enhanced entity retrieval

- Refactored the useEntity hook to streamline entity matching logic, ensuring consistent handling of string paths and predicate functions.
- Updated return logic to handle wildcards and predicates more effectively, returning arrays or null as appropriate.
- Enhanced traversal methods in helper functions to build relative paths correctly, improving the accuracy of entity searches.

* Update packages/lib/src/gltf/components/Gltf.tsx

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* linting fix

* refactor(gltf): remove unused exports from index files

- Removed unused exports PathMatcher and defaultPathMatcher from gltf/index.ts to streamline the module.
- Cleaned up index.ts by eliminating the unused useEntity export, improving code clarity and maintainability.

* Update packages/lib/src/gltf/components/RuleProcessor.tsx

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update packages/lib/src/Application.test.tsx

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update packages/lib/src/gltf/hooks/use-entity.tsx

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* chore(gltf): remove COVERAGE_ANALYSIS.md file

- Deleted the COVERAGE_ANALYSIS.md file as it is no longer needed for tracking test coverage analysis for the GLTF module.
- This cleanup helps streamline the documentation and focuses on more relevant resources.

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: marklundin

.changeset/stale-pandas-fetch.md

@@ -0,0 +1,5 @@
+---
+"@playcanvas/react": minor
+---
+
+Introduced a new declarative GLTF modification API. Users can now use the `<Gltf>` and `Modify` components to add, remove, and modify components (like `light`, `render`, `camera`) on entities within a loaded GLB hierarchy.

packages/lib/src/components/Camera.tsx

@@ -33,4 +33,6 @@ const componentDefinition = createComponentDefinition<CameraProps, CameraCompone
     () => new Entity("mock-camera", getStaticNullApplication()).addComponent('camera') as CameraComponent,
     (component) => (component as CameraComponent).system.destroy(),
     { apiName: "CameraComponent" }
-)
+)
+
+export { componentDefinition as cameraComponentDefinition };

packages/lib/src/components/Light.tsx

@@ -47,4 +47,6 @@ componentDefinition.schema = {
         errorMsg: (value: unknown) => `Invalid value for prop "type": ${value}. Expected one of: "directional", "omni", "spot".`,
         default: "directional"
     }
-} as Schema<LightProps, LightComponent>
+} as Schema<LightProps, LightComponent>
+
+export { componentDefinition as lightComponentDefinition };

packages/lib/src/components/Render.tsx

@@ -95,4 +95,5 @@ componentDefinition.schema = {
     }
 }
 
+export { componentDefinition as renderComponentDefinition };
 export default Render;

packages/lib/src/gltf/components/Gltf.tsx

@@ -0,0 +1,309 @@
+"use client";
+
+import React, { useState, useEffect, useMemo, useCallback, ReactNode, useRef } from 'react';
+import { Asset, Entity } from 'playcanvas';
+import { GltfContext } from '../context.tsx';
+import { Rule, MergedRule, ActionType, ModifyComponentAction } from '../types.ts';
+import { EntityMetadata, PathMatcher } from '../utils/path-matcher.ts';
+import { RuleProcessor } from './RuleProcessor.tsx';
+import { useParent } from '../../hooks/use-parent.tsx';
+
+export interface GltfProps {
+  /**
+   * The GLTF asset loaded via useModel
+   */
+  asset: Asset;
+  
+  /**
+   * Whether to render the GLTF scene visuals
+   * @default true
+   */
+  render?: boolean;
+  
+  /**
+   * Children should contain <Modify.Node> components
+   */
+  children?: ReactNode;
+}
+
+/**
+ * Root component for GLTF scene modification system
+ * 
+ * Provides:
+ * - Lazy instantiation of GLTF assets
+ * - Hierarchy cache for entity lookups
+ * - Rule collection and conflict resolution
+ * - Batched modification application
+ * - Optional rendering of GLTF visuals
+ * 
+ * @example
+ * ```tsx
+ * const { asset } = useModel('model.glb');
+ * 
+ * return (
+ *   <Gltf asset={asset} key={asset.id}>
+ *     <Modify.Node path="head.*[light]">
+ *       <Modify.Component type="light" remove />
+ *     </Modify.Node>
+ *   </Gltf>
+ * );
+ * ```
+ * 
+ * @example
+ * ```tsx
+ * // Don't render visuals, only process modifications
+ * <Gltf asset={asset} key={asset.id} render={false}>
+ *   <Modify.Node path="**[light]">
+ *     <Modify.Component type="light" remove />
+ *   </Modify.Node>
+ * </Gltf>
+ * ```
+ */
+export const Gltf: React.FC<GltfProps> = ({ asset, render = true, children }) => {
+  const parent = useParent();
+  const [rootEntity, setRootEntity] = useState<Entity | null>(null);
+  const [hierarchyCache, setHierarchyCache] = useState<Map<string, EntityMetadata>>(new Map());
+  const rulesRef = useRef<Map<string, Rule>>(new Map());
+  const [mergedRules, setMergedRules] = useState<Map<string, MergedRule>>(new Map());
+  const pathMatcher = useMemo(() => new PathMatcher(), []);
+  const [rulesVersion, setRulesVersion] = useState(0);
+  
+  // Check if we need to instantiate (render is true OR has Modify.Node children)
+  const shouldInstantiate = useMemo(() => {
+    // Always instantiate if render is true
+    if (render) return true;
+    
+    // Otherwise, check for Modify.Node children
+    if (!children) return false;
+    
+    const childArray = React.Children.toArray(children);
+    return childArray.some((child) => {
+      if (React.isValidElement(child)) {
+        const type = child.type as { displayName?: string; name?: string };
+        const displayName = type?.displayName || type?.name;
+        return displayName === 'ModifyNode';
+      }
+      return false;
+    });
+  }, [render, children]);
+
+  // Instantiate asset and build hierarchy cache
+  useEffect(() => {
+    if (!asset || !asset.resource || !shouldInstantiate || !parent) {
+      return;
+    }
+
+    // Instantiate the render entity
+    if (
+      !asset.resource ||
+      // We should use GLBContainerResource instead of any, but its not exported from playcanvas
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      typeof (asset.resource as any).instantiateRenderEntity !== 'function'
+    ) {
+      console.error('Asset resource does not have instantiateRenderEntity method');
+      return;
+    }
+    const entity = (asset.resource as { instantiateRenderEntity: () => Entity }).instantiateRenderEntity();
+    
+    if (!entity) {
+      console.error('Failed to instantiate GLTF asset');
+      return;
+    }
+
+    // Build hierarchy cache
+    const cache = new Map<string, EntityMetadata>();
+    buildHierarchyCache(entity, '', cache);
+    
+    setRootEntity(entity);
+    setHierarchyCache(cache);
+
+    // Cleanup
+    return () => {
+      entity.destroy();
+      setRootEntity(null);
+      setHierarchyCache(new Map());
+    };
+  }, [asset, shouldInstantiate, parent]);
+
+  // Process rules and resolve conflicts
+  const processRules = useCallback(() => {
+    if (!rootEntity || hierarchyCache.size === 0) {
+      setMergedRules(new Map());
+      return;
+    }
+
+    const merged = new Map<string, MergedRule>();
+    
+    // For each entity in the hierarchy
+    for (const [guid, metadata] of hierarchyCache.entries()) {
+      const matchingRules: Rule[] = [];
+      
+      // Find all rules that match this entity
+      for (const rule of rulesRef.current.values()) {
+        if (pathMatcher.matches(rule.path, metadata)) {
+          matchingRules.push(rule);
+        }
+      }
+
+      // If no rules match, skip
+      if (matchingRules.length === 0) {
+        continue;
+      }
+
+      // Merge and resolve conflicts
+      const mergedRule = mergeRules(guid, matchingRules);
+      merged.set(guid, mergedRule);
+    }
+
+    setMergedRules(merged);
+  }, [rootEntity, hierarchyCache, pathMatcher]);
+
+  // Rule registration callbacks
+  const registerRule = useCallback((rule: Rule) => {
+    rulesRef.current.set(rule.id, rule);
+    // "Poke" the component to re-process rules
+    setRulesVersion(v => v + 1);
+  }, []);
+
+  const unregisterRule = useCallback((ruleId: string) => {
+    rulesRef.current.delete(ruleId);
+    // "Poke" the component to re-process rules
+    setRulesVersion(v => v + 1);
+  }, []);
+
+  // Re-process rules when dependencies change
+  useEffect(() => {
+    // This effect now runs ONLY when the cache is ready
+    // or when the rules have *actually* changed.
+    processRules();
+  }, [processRules, hierarchyCache, rulesVersion]);
+
+  // Add root entity to parent scene (merged from Gltf component)
+  useEffect(() => {
+    if (!rootEntity || !parent || !render) {
+      return;
+    }
+
+    parent.addChild(rootEntity);
+    
+    return () => {
+      // Only remove if still a child (Gltf's cleanup will destroy it)
+      if (rootEntity.parent === parent) {
+        parent.removeChild(rootEntity);
+      }
+    };
+  }, [rootEntity, parent, render]);
+
+  // Context value
+  const contextValue = useMemo(() => ({
+    hierarchyCache,
+    rootEntity,
+    pathMatcher,
+    registerRule,
+    unregisterRule,
+  }), [hierarchyCache, rootEntity, pathMatcher, registerRule, unregisterRule]);
+
+  // Don't render anything if not instantiated
+  if (!rootEntity) {
+    return null;
+  }
+
+  return (
+    <GltfContext.Provider value={contextValue}>
+      {/* Render children (includes Gltf and Modify.Node components) */}
+      {children}
+      
+      {/* Render rule processors */}
+      {Array.from(mergedRules.entries()).map(([guid, rule]) => {
+        const metadata = hierarchyCache.get(guid);
+        if (!metadata) return null;
+        
+        return (
+          <RuleProcessor
+            key={guid}
+            entity={metadata.entity}
+            rule={rule}
+            originalChildGUIDs={metadata.originalChildGUIDs ?? []}
+          />
+        );
+      })}
+    </GltfContext.Provider>
+  );
+};
+
+/**
+ * Builds a hierarchy cache by traversing the entity tree
+ */
+function buildHierarchyCache(
+  entity: Entity,
+  parentPath: string,
+  cache: Map<string, EntityMetadata>
+): void {
+  const path = parentPath ? `${parentPath}.${entity.name}` : entity.name;
+  const guid = entity.getGuid();
+
+  const originalChildGUIDs = entity.children.map((child) => (child as Entity).getGuid());
+  
+  cache.set(guid, {
+    entity,
+    path,
+    guid,
+    name: entity.name,
+    originalChildGUIDs
+  });
+
+  // Recursively process children
+  for (const child of entity.children) {
+    buildHierarchyCache(child as Entity, path, cache);
+  }
+}
+
+/**
+ * Merges multiple rules for the same entity and resolves conflicts
+ */
+function mergeRules(entityGuid: string, rules: Rule[]): MergedRule {
+  const merged: MergedRule = {
+    entityGuid,
+    clearChildren: false,
+    componentActions: new Map(),
+    addChildren: []
+  };
+
+  // Sort rules by specificity (highest first)
+  const sortedRules = [...rules].sort((a, b) => b.specificity - a.specificity);
+
+  // Process each rule
+  for (const rule of sortedRules) {
+    for (const action of rule.actions) {
+      switch (action.type) {
+        case ActionType.CLEAR_CHILDREN:
+          // First rule with clearChildren wins
+          if (!merged.clearChildren) {
+            merged.clearChildren = true;
+          }
+          break;
+
+        case ActionType.ADD_CHILDREN: {
+          // Collect all additions
+          const addAction = action as { children: ReactNode[] };
+          merged.addChildren.push(...addAction.children);
+          break;
+        }
+
+        case ActionType.MODIFY_COMPONENT: {
+          // For component actions, highest specificity wins per component type
+          const componentAction = action as ModifyComponentAction;
+          if (!merged.componentActions.has(componentAction.componentType)) {
+            merged.componentActions.set(componentAction.componentType, action);
+          }
+          break;
+        }
+      }
+    }
+  }
+
+  return merged;
+}
+
+Gltf.displayName = 'Gltf';
+