Add WeChat MiniProgram support for PAGX viewer with rendering fixes and performance optimizations. (#3507)

Co-authored-by: richardshan <richardshan0614@gmail.com>
Co-authored-by: 风笛 <1753894329@qq.com>

Author: 3 people

.gitignore

@@ -121,3 +121,5 @@ cli/npm/package-lock.json
 # PAGX verify artifacts
 *.layout.xml
 
+# Local-only helper scripts (not part of the project)
+pagx/wechat/script/copy-to-cocraft.js

include/pagx/ImageResourceProvider.h

@@ -0,0 +1,65 @@
+/////////////////////////////////////////////////////////////////////////////////////////////////
+//
+//  Tencent is pleased to support the open source community by making libpag available.
+//
+//  Copyright (C) 2026 Tencent. All rights reserved.
+//
+//  Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file
+//  except in compliance with the License. You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+//  unless required by applicable law or agreed to in writing, software distributed under the
+//  license is distributed on an "as is" basis, without warranties or conditions of any kind,
+//  either express or implied. see the license for the specific language governing permissions
+//  and limitations under the license.
+//
+/////////////////////////////////////////////////////////////////////////////////////////////////
+
+#pragma once
+
+#include <memory>
+#include <string>
+
+namespace tgfx {
+class Image;
+}
+
+namespace pagx {
+
+/**
+ * Provides pre-decoded image resources to the rendering pipeline. Platform-specific implementations
+ * can manage their own caching, eviction, and progressive loading strategies without coupling
+ * decoded image state to the document model layer.
+ *
+ * The renderer queries this provider during layer building. When resolveImage() returns non-null,
+ * the renderer uses that image directly and skips all codec-based decoding paths (embedded data,
+ * data URI, file path). When it returns nullptr, the renderer falls back to the standard decoding
+ * chain.
+ *
+ * Thread safety: the provider is accessed only on the render thread (inside draw()/flush()), so
+ * implementations do not need internal synchronization unless they share state with other threads.
+ */
+class ImageResourceProvider {
+ public:
+  virtual ~ImageResourceProvider() = default;
+
+  /**
+   * Resolves a pre-decoded image for the given external file path. The implementation decides
+   * which quality level to return (full, thumbnail, or nullptr for fallback).
+   * @param filePath the external file path as declared in the PAGX document's Image node.
+   * @return A tgfx::Image ready for rendering, or nullptr to signal the renderer should decode
+   *         from embedded data / file path.
+   */
+  virtual std::shared_ptr<tgfx::Image> resolveImage(const std::string& filePath) = 0;
+
+  /**
+   * Returns true if the provider currently holds any decoded image (full or thumbnail) for the
+   * given path. Used by getExternalFilePaths() to exclude paths that already have a decoded
+   * counterpart, preventing redundant network fetches.
+   * @param filePath the external file path to check.
+   */
+  virtual bool hasImage(const std::string& filePath) const = 0;
+};
+
+}  // namespace pagx

include/pagx/PAGXDocument.h

@@ -24,6 +24,7 @@
 #include <unordered_set>
 #include <vector>
 #include "pagx/FontConfig.h"
+#include "pagx/ImageResourceProvider.h"
 #include "pagx/nodes/Animation.h"
 #include "pagx/nodes/Layer.h"
 #include "pagx/nodes/Node.h"
@@ -33,6 +34,8 @@ namespace pagx {
 
 class LayoutContext;
 class PAGScene;
+class Image;
+class ImagePattern;
 
 /**
  * PAGXDocument is the root container for a PAGX document.
@@ -126,7 +129,9 @@ class PAGXDocument : public Node {
 
   /**
    * Returns a list of external file paths referenced by Image nodes or external composition layers
-   * that have no embedded data. Data URIs (paths starting with "data:") are excluded.
+   * that have no embedded data. Data URIs (paths starting with "data:") are excluded. Image nodes
+   * for which the current ImageResourceProvider already holds a decoded counterpart are also
+   * excluded so the same resource is not fetched twice.
    */
   std::vector<std::string> getExternalFilePaths() const;
 
@@ -143,6 +148,17 @@ class PAGXDocument : public Node {
    */
   bool loadFileData(const std::string& filePath, std::shared_ptr<Data> data);
 
+  /**
+   * Sets the image resource provider used by the rendering pipeline to resolve pre-decoded images.
+   * When set, getExternalFilePaths() consults the provider to exclude paths that already have a
+   * decoded counterpart. The renderer queries the provider during layer building via
+   * resolveImage().
+   *
+   * Passing nullptr removes the provider; the renderer will use only embedded data / file paths.
+   * @param provider the platform-specific image resource provider, or nullptr to remove.
+   */
+  void setImageResourceProvider(std::shared_ptr<ImageResourceProvider> provider);
+
   /**
    * Executes auto layout on the document, positioning layers according to their layout
    * constraints. Must be called before rendering or font embedding. Re-running layout on an
@@ -234,6 +250,9 @@ class PAGXDocument : public Node {
 
  private:
   PAGXDocument() = default;
+
+  const std::vector<const Layer*>& findLayersByImageFilePath(const std::string& imageFilePath);
+
   // Recursive layout worker. visited holds the documents on the current ancestor path so an
   // externalDoc cycle built directly through the API (bypassing loadFileData's own chain guard)
   // is detected and stops the recursion instead of overflowing the stack.
@@ -247,6 +266,7 @@ class PAGXDocument : public Node {
   void registerLiveScene(const std::shared_ptr<PAGScene>& scene);
   void unregisterLiveScene(PAGScene* scene);
 
+  std::shared_ptr<ImageResourceProvider> _imageResourceProvider = nullptr;
   FontConfig fontConfig;
   bool layoutApplied = false;
   std::unordered_map<std::string, Node*> nodeMap = {};
@@ -257,11 +277,20 @@ class PAGXDocument : public Node {
   // does not keep PAGScene alive; expired entries are pruned during notifyChange.
   std::vector<std::weak_ptr<PAGScene>> liveScenes = {};
 
+  // Lazily built index of Image node filePath -> pagx Layer list, used by
+  // findLayersByImageFilePath(). Built on first query; invalidated by notifyChange() since edits
+  // may alter the tree topology or Image node filePath values. Also freed when the document is
+  // destroyed (on the next parsePAGX() call).
+  std::unordered_map<std::string, std::vector<const Layer*>> layersByImageFilePath = {};
+  bool layersByImageFilePathBuilt = false;
+
   friend class PAGXImporter;
   friend class PAGXExporter;
   friend class TextLayoutContext;
   friend class PAGScene;
   friend class PAGComposition;
+  friend class LayerBuilderContext;
+  friend class LayerBuilderSession;
 };
 
 }  // namespace pagx

include/pagx/nodes/Image.h

@@ -27,12 +27,13 @@ namespace pagx {
 
 /**
  * Image represents an image resource that can be referenced by other nodes. The image source can
- * be a file path, a URL, or a base64-encoded data URI.
+ * be a file path, a URL, or a base64-encoded data URI. Platform-specific decoded images are
+ * managed externally via ImageResourceProvider, not stored on this node.
  */
 class Image : public Node {
  public:
   /**
-   * Image binary data (decoded from base64).
+   * Image binary data (decoded from base64 or loaded via loadFileData).
    */
   std::shared_ptr<Data> data = nullptr;
 

pagx/wechat/.gitignore

@@ -0,0 +1,15 @@
+# Build outputs
+wasm-mt/
+wasm/
+dist/
+
+# Build cache
+script/build-pagx-viewer/
+script/wasm-mt/
+script/.build.lock
+.*.md5
+package-lock.json
+ts/wasm
+types/
+lib/
+docs/