Add pagx embed command, restructure pagx font, and support external font files.

.codebuddy/skills/pagx/references/attributes.md

@@ -406,6 +406,7 @@ Embedded font resource containing subsetted glyph data (vector outlines or bitma
 
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
+| `file` | string | - | External font file path (TTF/OTF). Font nodes with `file` serve as font source declarations. `pagx embed` auto-discovers them, loads the referenced font files, and registers fonts for text shaping. After embed, `file` is preserved for source traceability. |
 | `unitsPerEm` | int | 1000 | Font design space units; rendering scale = fontSize / unitsPerEm |
 
 ### Glyph

.codebuddy/skills/pagx/references/cli.md

@@ -246,50 +246,62 @@ element, an error is reported.
 
 ## pagx font
 
-Font operations with two subcommands: `info` (query metrics) and `embed` (embed into PAGX).
-
-### pagx font info
-
-Query font identity and metrics from a font file or system font.
+Query font identity and metrics from a font file or system font, or enumerate installed
+system font families.
 
 ```bash
-pagx font info --file ./CustomFont.ttf
-pagx font info --file ./CustomFont.ttf --size 24
-pagx font info --name "PingFang SC,Bold"
-pagx font info --name "Arial" --size 24 --json
+pagx font --file ./CustomFont.ttf
+pagx font --file ./CustomFont.ttf --size 24
+pagx font --name "PingFang SC,Bold"
+pagx font --name "Arial" --size 24 --json
+pagx font --list
+pagx font --list --json
 ```
 
 | Option | Description |
 |--------|-------------|
-| `--file <path>` | Font file path |
-| `--name <family[,style]>` | System font by name (e.g., `"Arial"` or `"Arial,Bold"`) |
+| `--file <path>` | Query a font file |
+| `--name <family[,style]>` | Query a system font (e.g., `"Arial"` or `"Arial,Bold"`) |
 | `--size <pt>` | Font size in points (default: 12, the PAGX spec default) |
-| `--json` | JSON output |
+| `--json` | Output in JSON format |
+| `--list` | List every installed system font family |
 
-Either `--file` or `--name` is required (mutually exclusive).
+Exactly one of `--file`, `--name`, or `--list` is required. `--list` cannot be combined
+with `--file` or `--name`; `--file` and `--name` are mutually exclusive.
 
 Returns typeface info (fontFamily, fontStyle, glyphsCount, unitsPerEm, hasColor, hasOutlines)
 and all FontMetrics fields at the specified size (top, ascent, descent, bottom, leading, xMin,
 xMax, xHeight, capHeight, underlineThickness, underlinePosition).
 
-### pagx font embed
+The retired `pagx font info` and `pagx font embed` subcommands now error out with a redirect
+message; use `pagx font ...` for font queries and `pagx embed` for font embedding.
 
-Embed fonts into a PAGX file by performing text layout and glyph extraction.
+---
+
+## pagx embed
+
+Embed font glyphs and images into a PAGX file for self-contained output. Font embedding extracts glyph data from laid-out text; image embedding inlines external image files as base64. Font nodes with a `file` attribute are automatically discovered and registered for text shaping — no `--font-file` flag needed.
 
 ```bash
-pagx font embed input.pagx
-pagx font embed -o out.pagx input.pagx
-pagx font embed --file a.ttf --file b.ttf input.pagx
-pagx font embed --file a.ttf --fallback "PingFang SC" --fallback b.otf input.pagx
+pagx embed input.pagx                                    # embed fonts + images (overwrite)
+pagx embed -o out.pagx input.pagx                        # embed fonts + images to new file
+pagx embed --skip-fonts input.pagx                       # embed images only
+pagx embed --skip-images input.pagx                      # embed fonts only
 ```
 
 | Option | Description |
 |--------|-------------|
 | `-o, --output <path>` | Output file path (default: overwrite input) |
-| `--file <path>` | Register a font file (can be specified multiple times) |
 | `--fallback <path\|name>` | Fallback font file or system font name (can be specified multiple times) |
+| `--skip-fonts` | Skip font embedding |
+| `--skip-images` | Skip image embedding |
+| `-h, --help` | Show this help message |
+
+Fonts are resolved in the following order:
+1. Font nodes with `file` attribute are loaded and registered by their internal family name
+2. `--fallback` fonts are tried when a character is not found in the primary font
 
-`--file` and `--fallback` work the same as in `pagx render`.
+Image embedding inlines external file references (Image nodes with `filePath`) as base64 data. See the Font `file` attribute in `attributes.md` for details on external font references.
 
 ---
 

.codebuddy/skills/pagx/references/guide.md

@@ -425,7 +425,7 @@ over `position`.
 - **Text**: `text`, `fontFamily`, `fontStyle`, `fontSize`, `letterSpacing`. Wrap in TextBox
   for paragraph features. `fauxBold`/`fauxItalic` for algorithmic styles. `
` for line
   breaks. Use `<![CDATA[...]]>` for XML special characters (e.g., `<![CDATA[A < B]]>`).
-- **GlyphRun**: Pre-laid-out glyph data with embedded font. Generated by `pagx font embed`,
+- **GlyphRun**: Pre-laid-out glyph data with embedded font. Generated by `pagx embed`,
   not written by hand.
 
 ## Painters

cli/npm/README.md

@@ -22,8 +22,8 @@ npm install -g @libpag/pagx
 | `pagx optimize` | Validate, optimize, and format in one step |
 | `pagx format` | Format a PAGX file with consistent indentation and attribute ordering |
 | `pagx bounds` | Query the precise rendered bounds of layers |
-| `pagx font info` | Query font identity and metrics from a file or system font |
-| `pagx font embed` | Embed fonts into a PAGX file with glyph extraction |
+| `pagx font` | Query a font file, a system font by name, or list system font families |
+| `pagx embed` | Embed font glyphs and images into a PAGX file for self-contained output |
 
 ## Usage Examples
 
@@ -65,13 +65,22 @@ pagx bounds --xpath "//Layer[@id='btn']" input.pagx
 pagx bounds --xpath "//Layer[@id='icon']" --relative "//Layer[@id='card']" --json input.pagx
 
 # Query system font metrics at 24pt
-pagx font info --name "Arial" --size 24
+pagx font --name "Arial" --size 24
 
 # Query font metrics from a file
-pagx font info --file CustomFont.ttf --json
+pagx font --file CustomFont.ttf --json
 
-# Embed fonts with a custom fallback
-pagx font embed --file BrandFont.ttf --fallback "Arial" input.pagx
+# List all installed system font families
+pagx font --list
+
+# Embed fonts and images into a PAGX file
+pagx embed input.pagx
+
+# Embed with fallback fonts
+pagx embed --fallback "Arial" input.pagx
+
+# Embed images only (skip font embedding)
+pagx embed --skip-fonts input.pagx
 ```
 
 ## Command Reference
@@ -147,26 +156,29 @@ coordinates by default.
 
 `--id` and `--xpath` are mutually exclusive. Without either, outputs bounds for all layers.
 
-### `pagx font info [options]`
+### `pagx font [options]`
 
-Query font identity and metrics. Requires either `--file` or `--name` (mutually exclusive).
+Query a font file, a system font by name, or list system font families. Exactly one of `--file`,
+`--name`, or `--list` must be specified.
 
 | Option | Description |
 |--------|-------------|
-| `--file <path>` | Font file path |
-| `--name <family,style>` | System font name (e.g., `"Arial"` or `"Arial,Bold"`) |
+| `--file <path>` | Query a font file |
+| `--name <family,style>` | Query a system font (e.g., `"Arial"` or `"Arial,Bold"`) |
 | `--size <pt>` | Font size in points (default: `12`) |
 | `--json` | Output in JSON format |
+| `--list` | List every installed system font family |
 
-### `pagx font embed [options] <file.pagx>`
+### `pagx embed [options] <file.pagx>`
 
-Embed fonts into a PAGX file by performing text layout and glyph extraction.
+Embed font glyphs and images into a PAGX file for self-contained output.
 
 | Option | Description |
 |--------|-------------|
 | `-o, --output <path>` | Output file path (default: overwrite input) |
-| `--file <path>` | Register a font file (repeatable) |
 | `--fallback <path\|name>` | Add a fallback font file or system font name (repeatable) |
+| `--skip-fonts` | Skip font embedding |
+| `--skip-images` | Skip image embedding |
 
 ## Supported Platforms
 

include/pagx/PAGXDocument.h

@@ -20,6 +20,8 @@
 
 #include <memory>
 #include <string>
+#include <unordered_map>
+#include <unordered_set>
 #include <vector>
 #include "pagx/FontConfig.h"
 #include "pagx/nodes/Layer.h"
@@ -127,11 +129,20 @@ class PAGXDocument : public Node {
    */
   bool loadFileData(const std::string& filePath, std::shared_ptr<Data> data);
 
+  /**
+   * Batch version of loadFileData. Loads file data for all Image nodes whose filePath matches
+   * a key in the map in a single pass over the nodes. More efficient than calling loadFileData
+   * individually for each file when embedding multiple images.
+   * @param fileDataMap a map from file path to the file content to embed
+   */
+  void loadFileDataMap(
+      const std::unordered_map<std::string, std::shared_ptr<Data>>& fileDataMap);
+
   /**
    * Executes auto layout on the document, positioning layers according to their layout
-   * constraints. Must be called before rendering or font embedding. This method should only
-   * be called once per document — repeated calls may produce incorrect results because
-   * measurement data is cached and some layout operations permanently modify source geometry.
+   * constraints. Must be called before rendering or font embedding. Repeated calls are safe
+   * only after calling ClearEmbeddedGlyphRuns + resetLayoutState(), which clears embedded
+   * glyph data and resets the layout flag so layout re-runs with fresh shaping data.
    * @param fontConfig Optional font config for text measurement and rendering. When provided,
    *                   updates the internal config before layout. Pass nullptr to use the
    *                   previously set config (or no config).
@@ -160,6 +171,28 @@ class PAGXDocument : public Node {
    */
   void clearEmbed();
 
+  /**
+   * Removes the specified nodes from the document and cleans up their nodeMap entries.
+   * Node pointers in the set and any pointers derived from them (e.g. child glyphs) are
+   * invalidated after this call. Callers must first collect all affected nodes to remove
+   * before calling.
+   */
+  void removeNodes(const std::unordered_set<Node*>& nodesToRemove);
+
+  /**
+   * Assigns or changes the ID of an existing node. If the new ID already exists in the
+   * document, the old entry is replaced. If the ID is empty, the node is removed from the
+   * lookup index. The node must already be managed by this document.
+   */
+  void setNodeId(Node* node, const std::string& id);
+
+  /**
+   * Resets the layout-applied flag to allow applyLayout() to be called again. Must be paired
+   * with ClearEmbeddedGlyphRuns before re-embedding to ensure layout re-runs with fresh
+   * shaping data.
+   */
+  void resetLayoutState();
+
   NodeType nodeType() const override {
     return NodeType::Document;
   }

include/pagx/nodes/Font.h

@@ -18,6 +18,7 @@
 
 #pragma once
 
+#include <string>
 #include <vector>
 #include "pagx/nodes/Node.h"
 #include "pagx/types/Point.h"
@@ -76,6 +77,15 @@ class Font : public Node {
    */
   int unitsPerEm = 1000;
 
+  /**
+   * Path to an external font file. When set, this Font node serves as a font source declaration:
+   * `pagx embed` loads and registers the referenced font for text shaping. Extracted glyph data
+   * is stored in separate Font nodes (the source node's `glyphs` is preserved as empty across
+   * embed). The path is resolved relative to the PAGX file's directory. An empty string means
+   * no external reference.
+   */
+  std::string file = {};
+
   /**
    * The list of glyphs in this font. GlyphID is the index + 1 (GlyphID 0 is reserved for missing
    * glyph).

resources/cli/embed_font_file.pagx

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<pagx width="400" height="200">
+  <Layer>
+    <TextBox textAlign="center">
+      <Text text="Hello PAGX" fontFamily="Noto Sans SC" fontSize="32"/>
+      <Fill color="#000000"/>
+    </TextBox>
+  </Layer>
+  <Resources>
+    <Font id="noto" file="NotoSansSC-Regular.otf" unitsPerEm="1000"/>
+  </Resources>
+</pagx>

resources/cli/embed_sample.pagx

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<pagx width="200" height="200">
+  <Layer>
+    <Rectangle left="10" top="10" width="80" height="80"/>
+    <Fill>
+      <ImagePattern image="@sample" matrix="0.3,0,0,0.3,0,0" tileModeX="clamp" tileModeY="clamp"/>
+    </Fill>
+  </Layer>
+  <Layer>
+    <TextBox textAlign="center">
+      <Text text="Hello" fontFamily="Helvetica" fontSize="24"/>
+      <Fill color="#000000"/>
+    </TextBox>
+  </Layer>
+  <Resources>
+    <Image id="sample" source="image_as_mask.png"/>
+  </Resources>
+</pagx>

spec/pagx.xsd

@@ -508,6 +508,7 @@
     </xs:sequence>
     <xs:attributeGroup ref="CommonAttributes"/>
     <xs:attribute name="unitsPerEm" type="xs:integer" default="1000"/>
+    <xs:attribute name="file" type="xs:string"/>
   </xs:complexType>
 
   <!-- ========================= GlyphRun ========================= -->

spec/pagx_spec.md

@@ -488,7 +488,7 @@ Compositions are used for content reuse (similar to After Effects pre-comps).
 
 #### 3.3.5 Font
 
-Font defines embedded font resources containing subsetted glyph data (vector outlines or bitmaps). Embedding glyph data makes PAGX files fully self-contained, ensuring consistent rendering across platforms.
+Font defines embedded font resources containing subsetted glyph data (vector outlines or bitmaps). Embedding glyph data makes PAGX files fully self-contained, ensuring consistent rendering across platforms. Font nodes can also reference external font files via the optional `file` attribute, serving as font source declarations for `pagx embed` to discover and register before text layout.
 
 ```xml
 <!-- Embedded vector font -->
@@ -502,10 +502,14 @@ Font defines embedded font resources containing subsetted glyph data (vector out
   <Glyph advance="136" image="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA..."/>
   <Glyph advance="136" image="emoji/heart.png" offset="0,-5"/>
 </Font>
+
+<!-- External font file reference (before embed) -->
+<Font id="Noto" file="./fonts/NotoSansSC-Regular.otf" unitsPerEm="1000"/>
 ```
 
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
+| `file` | string | - | External font file path. When set, the Font node references an external TTF/OTF file. Relative paths resolve against the PAGX file's directory. `pagx embed` discovers Font nodes with `file`, loads the fonts, and registers them for text shaping. After embed, `file` is preserved for source traceability while embedded glyph data lives in separate Font nodes. |
 | `unitsPerEm` | int | 1000 | Font design space units. Rendering scale = `fontSize / unitsPerEm` |
 
 **Consistency Constraint**: All Glyphs within the same Font must be of the same type—either all `path` or all `image`. Mixing is not allowed.

spec/pagx_spec.zh_CN.md

@@ -488,7 +488,7 @@ PathData 定义可复用的路径数据，供 Path 元素和 TextPath 修改器
 
 #### 3.3.5 字体（Font）
 
-Font 定义嵌入字体资源，包含子集化的字形数据（矢量轮廓或位图）。PAGX 文件通过嵌入字形数据实现完全自包含，确保跨平台渲染一致性。
+Font 定义嵌入字体资源，包含子集化的字形数据（矢量轮廓或位图）。PAGX 文件通过嵌入字形数据实现完全自包含，确保跨平台渲染一致性。Font 节点还可以通过可选的 `file` 属性引用外部字体文件，作为字体来源声明，供 `pagx embed` 在执行文本排版前发现并注册。
 
 ```xml
 <!-- 嵌入矢量字体 -->
@@ -502,10 +502,14 @@ Font 定义嵌入字体资源，包含子集化的字形数据（矢量轮廓或
   <Glyph advance="136" image="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA..."/>
   <Glyph advance="136" image="emoji/heart.png" offset="0,-5"/>
 </Font>
+
+<!-- 外部字体文件引用（嵌入前） -->
+<Font id="Noto" file="./fonts/NotoSansSC-Regular.otf" unitsPerEm="1000"/>
 ```
 
 | 属性 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
+| `file` | string | - | 外部字体文件路径。设置后 Font 节点引用外部 TTF/OTF 文件。相对路径基于 PAGX 文件所在目录解析。`pagx embed` 会自动发现带 `file` 的 Font 节点，加载并注册字体用于文本排版。嵌入后 `file` 属性保留在输出中以保持源文件可追溯性，嵌入的字形数据位于独立的 Font 节点中。 |
 | `unitsPerEm` | int | 1000 | 字体设计空间单位。渲染时按 `fontSize / unitsPerEm` 缩放 |
 
 **一致性约束**：同一 Font 内的所有 Glyph 必须使用相同类型（全部 `path` 或全部 `image`），不允许混用。