` element in your add-on's HTML |
+| | Design | Visual design component in Adobe Express UI | "Text elements in your design" (user-facing term) |
+| **exports** | Named exports | ES Module syntax for exporting multiple values from a module. **Requires curly braces `{ }` in import statement** | `export { editor, colorUtils }` → `import { editor } from "..."` |
+| | Default export | ES Module syntax for a single main export from a module. **No curly braces in import statement** | `export default addOnUISdk` → `import addOnUISdk from "..."` |
+| | Module pattern | How SDKs expose functionality: UI SDK uses default, Document SDK uses named | UI SDK: default export; Express Document SDK: named exports |
+| **Web APIs** | Standard browser APIs | JavaScript APIs available in web browsers (fetch, localStorage, Blob, etc.) | "iframe runtime has standard Web APIs" |
+| | Limited in sandbox | Document sandbox only has limited Web APIs (console, Blob) | "Document sandbox has restricted Web APIs" |
+| | vs Browser APIs | Same meaning - standard JavaScript APIs built into browsers | "Web APIs" and "Browser APIs" are interchangeable terms |
+
+### Common Sources of Confusion
+
+**"I need to access the document"** - Which document?
+
+- Adobe Express user's project → "The document has 3 pages"
+- Manipulate Adobe Express content → `editor.documentRoot`
+- Import/export Adobe Express document → `addOnUISdk.app.document`
+- Your add-on's UI HTML page → `document.getElementById()`
+
+**"What's the DOM?"** - Which DOM?
+
+- Your add-on's HTML structure → `document.querySelector()` (Browser DOM)
+- Adobe Express's document structure → Use "scenegraph" not "DOM"
+
+**"How do I use the runtime?"** - Which runtime?
+
+- Execution environment → "Code runs in iframe runtime or document sandbox"
+- Communication APIs → `addOnUISdk.instance.runtime` or `addOnSandboxSdk.instance.runtime`
+
+**"What is the context?"** - Which context?
+
+- Execution environment → "The iframe context has standard Web APIs"
+- Editor's selection/insertion → `editor.context.selection`
+- Security boundaries → See [iframe Context & Security](../platform_concepts/context.md)
+
+**"What does instance mean?"** - Which instance?
+
+- SDK property → `addOnUISdk.instance` or `addOnSandboxSdk.instance`
+- Class object → "rectangle is an instance of RectangleNode"
+- Running session → "User's add-on instance"
+
+**"How do I import SDKs?"** - Named or default export?
+
+- Add-on UI SDK → Default export (no curly braces): `import addOnUISdk from "..."`
+- Document Sandbox SDK → Default export (no curly braces): `import addOnSandboxSdk from "..."`
+- Express Document SDK → Named exports (requires curly braces): `import { editor, colorUtils } from "..."`
+
+**"Are Web APIs and Browser APIs the same?"** - Yes!
+
+- Same thing, different names → "Web APIs" = "Browser APIs"
+- iframe runtime → Standard Web APIs available
+- Document sandbox → Limited Web APIs only (console, Blob)
+
+**"Should I say node or element?"** - It depends!
+
+- Adobe Express scenegraph → Use "node" (`RectangleNode`, `TextNode`, etc.) to describe visual elements in the document
+- Your add-on's HTML → Use "DOM node" or "HTML element"
+- User-facing docs → "element" is okay (e.g., "text elements in your design")
+- Developer docs → Prefer "node" for precision and to match API class names
+
+**"Should I use `addOnUISdk.instance` or `addOnUISdk.app`?"** - Different scopes
+
+- **Add-on scope** (`instance`) → Features specific to YOUR add-on
+ - `instance.runtime` - YOUR add-on's communication
+ - `instance.clientStorage` - YOUR add-on's storage (per-user, per-addon)
+ - `instance.manifest` - YOUR add-on's configuration
+- **Application scope** (`app`) → Features shared across Adobe Express
+ - `app.document` - The Adobe Express document (same for all add-ons)
+ - `app.currentUser` - The Express user (not specific to your add-on)
+ - `app.ui` - Adobe Express UI state (`theme`, `locale`)
+
+## Runtime Environments
+
+Adobe Express add-ons use a **dual-runtime architecture** with two separate JavaScript execution environments:
+
+### **Iframe Runtime**
+
+- **What it is**: A sandboxed iframe environment where your add-on's user interface runs
+- **Purpose**: Hosts your HTML, CSS, and JavaScript UI code
+- **SDK Used**: Add-on UI SDK
+- **File reference**: Typically your `index.html` and associated UI JavaScript files
+- **Security**: Sandboxed for security with standard Web APIs (some features require manifest permissions)
+- **Also known as**: "Panel Runtime", "iframe Sandbox"
+- **Terminology Note**: While the browser term is "iframe sandbox" (as used in [HTML sandbox attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#sandbox) and manifest permissions), we use "iframe runtime" throughout the documentation for consistency with "document sandbox runtime" and to distinguish between the two execution environments
+
+### **Document Sandbox**
+
+- **What it is**: A separate sandboxed JavaScript environment for document manipulation
+- **Purpose**: Provides secure access to Adobe Express document structure and content
+- **SDKs Used**: Document Sandbox SDK (for communication) + Express Document SDK (for document APIs)
+- **File reference**: Specified in your manifest's `documentSandbox` entry (e.g., `code.js`)
+- **Security**: Isolated environment with limited Web APIs but direct document access
+- **Also known as**: "Document Model Sandbox"
+
+#### Understanding Runtime Communication
+
+The two runtimes communicate with each other through the [Communication APIs](../../../references/document-sandbox/communication/index.md), allowing your UI to trigger document changes and vice versa.
+
+**About Web APIs**: The terms "browser capabilities," "browser features," and "Web APIs" all refer to the standard JavaScript APIs available in web environments (like `fetch`, `localStorage`, `console`, `Blob`, etc.). The iframe runtime has standard Web APIs, while the document sandbox has limited Web APIs for security reasons. See the [Web APIs Reference](../../../references/document-sandbox/web/index.md) for details on what's available in each environment.
+
+
+
+For a comprehensive deep-dive into the dual-runtime architecture with visual diagrams, communication patterns, and code examples, see the [Add-on Architecture Guide](../platform_concepts/architecture.md).
+
+## SDK Concepts
+
+### Add-on UI SDK
+
+**`addOnUISdk`**: The JavaScript module you import in your iframe code that provides `runtime` instance, `app` interfaces, `constants`, and UI-specific APIs.
+
+The `addOnUISdk` object provides two distinct scopes of functionality:
+
+**`addOnUISdk.instance` - Add-on Scope**
+Features specific to your individual add-on:
+
+- `runtime` - Communication between your add-on's iframe and document sandbox
+- `clientStorage` - Data storage for your add-on only (per-user, per-addon)
+- `manifest` - Your add-on's configuration
+- `entrypointType` - Your add-on's current entry point
+- `logger` - Logging for your add-on
+
+**Scope**: Isolated to your add-on instance; doesn't interact with other add-ons.
+
+**`addOnUISdk.app` - Application Scope**
+Features shared across Adobe Express (the host application):
+
+- `document` - The active Adobe Express document (shared across all add-ons)
+- `oauth` - Authentication with external services
+- `currentUser` - The Adobe Express user (not specific to your add-on)
+- `ui` - Adobe Express UI state (theme, locale, etc.)
+- `command` - Commands in the host application
+
+**Scope**: Interacts with Adobe Express itself and its global state.
+
+### Express Document SDK
+
+**Express Document SDK** (`express-document-sdk`): The JavaScript module providing document manipulation capabilities for the document sandbox. Import named exports: `editor`, `colorUtils`, `constants`, `fonts`, `viewport`.
+
+### Document Sandbox SDK
+
+**Document Sandbox SDK** (`add-on-sdk-document-sandbox`): The JavaScript module for communication between iframe runtime and document sandbox. Import as `addOnSandboxSdk`. Only needed when you require bi-directional communication between the two environments.
+
+
+
+**Note**: All Adobe Express add-on SDKs use the singleton pattern - pre-instantiated objects you import and use directly. You never create new instances yourself. See the [FAQ on singleton pattern](#q-what-is-the-singleton-pattern-and-why-do-add-on-sdks-use-it) and [Architecture Guide](../platform_concepts/architecture.md#sdk-structure--import-patterns) for details.
+
+## Import Patterns & Usage
+
+### Complete Import Reference
+
+```js
+// iframe runtime (UI code) - index.js/index.html
+import addOnUISdk from "https://express.adobe.com/static/add-on-sdk/sdk.js";
+
+// Document sandbox runtime (content manipulation) - code.js
+import addOnSandboxSdk from "add-on-sdk-document-sandbox"; // For communication
+import { editor, colorUtils, constants, fonts, viewport } from "express-document-sdk"; // For document APIs
+
+// Add-on UI SDK with explicit constants
+import addOnUISdk, { Range, RenditionFormat, Variant } from "https://express.adobe.com/static/add-on-sdk/sdk.js";
+```
+
+### When to Use Each Import
+
+| Your Add-on Needs | iframe runtime | document sandbox | Required SDKs |
+|-------------------|------------|------------------|------------------|
+| **UI only** (no document changes) | ✅ | ❌ | Add-on UI SDK |
+| **Document manipulation** | ✅ | ✅ | Add-on UI SDK + Document Sandbox SDK + Express Document SDK |
+| **Cross-runtime communication** | ✅ | ✅ | Add-on UI SDK + Document Sandbox SDK |
+| **Export/Import workflows** | ✅ | ❌ | Add-on UI SDK |
+
+## Communication System
+
+### Bidirectional Communication Pattern
+
+**iframe runtime → document sandbox**:
+
+```js
+// iframe runtime (index.js)
+const { runtime } = addOnUISdk.instance;
+const sandboxProxy = await runtime.apiProxy("documentSandbox");
+await sandboxProxy.createRectangle();
+
+// document sandbox (code.js)
+const { runtime } = addOnSandboxSdk.instance; // Document Sandbox SDK
+runtime.exposeApi({
+ createRectangle() {
+ const rect = editor.createRectangle();
+ editor.context.insertionParent.children.append(rect);
+ }
+});
+```
+
+**document sandbox → iframe runtime**:
+
+```js
+// document sandbox (code.js)
+const panelProxy = await runtime.apiProxy("panel");
+await panelProxy.updateUI("Rectangle created");
+
+// iframe runtime (index.js)
+runtime.exposeApi({
+ updateUI(message) {
+ document.getElementById('status').textContent = message;
+ }
+});
+```
+
+### Runtime Types
+
+- **`panel`**: The main iframe runtime for your add-on UI
+- **`documentSandbox`**: The document manipulation runtime
+- **`dialog`**: Runtime context when code is running within a modal dialog
+
+## Core Development Objects
+
+### **`editor` Object**
+
+Primary interface for document manipulation in the document sandbox.
+
+```js
+import { editor } from "express-document-sdk";
+
+const rectangle = editor.createRectangle();
+const textNode = editor.createText("Hello World");
+const insertionParent = editor.context.insertionParent;
+```
+
+### **`constants`**
+
+Type-safe values for SDK operations that prevent string literal errors.
+
+```js
+// UI SDK Constants
+await addOnUISdk.app.document.createRenditions({
+ range: Range.currentPage,
+ format: RenditionFormat.png
+});
+
+// Document Sandbox Constants
+rectangle.fill = {
+ type: constants.FillType.color,
+ color: { red: 1, green: 0, blue: 0, alpha: 1 }
+};
+```
+
+### **ColorUtils**
+
+Utility functions for creating and converting colors in the document sandbox.
+
+```js
+import { colorUtils } from "express-document-sdk";
+
+const redColor = colorUtils.fromRGB(1, 0, 0); // RGB values (0-1)
+const blueColor = colorUtils.fromHex("#0066CC"); // Hex string
+const hexString = colorUtils.toHex(redColor); // "#FF0000FF"
+```
+
+## Node Hierarchy
+
+Adobe Express documents are structured as a **scenegraph** - a hierarchical tree of nodes representing visual elements.
+
+**`BaseNode`**: The minimal base class for all document elements with basic properties like `id`, `type`, `parent`, `allChildren`.
+
+**`Node`**: Full-featured visual content that extends `BaseNode` with visual properties and transformations.
+
+**Common Node Types**:
+
+- **Container Nodes**: `ArtboardNode`, `GroupNode`, `PageNode` (hold other elements)
+- **Content Nodes**: `RectangleNode`, `EllipseNode`, `TextNode`, `LineNode`, `PathNode` (visual elements)
+- **Media Nodes**: `MediaContainerNode`, `ImageRectangleNode` (images and media)
+
+```js
+// Navigate the document hierarchy
+const root = editor.documentRoot; // ExpressRootNode
+const currentPage = root.pages.first; // PageNode
+const artboard = currentPage.artboards.first; // ArtboardNode
+
+// Create and add content
+const rectangle = editor.createRectangle(); // RectangleNode
+artboard.children.append(rectangle);
+```
+
+## Development Environment & Tools
+
+### **Add-on Marketplace**
+
+Distribution platform where users discover and install add-ons within [Adobe Express](https://express.adobe.com/add-ons) via the "Add-ons" button in the left sidebar.
+
+### **Code Playground**
+
+Interactive browser-based development environment for experimenting with add-on APIs without local setup. See the [Code Playground](../../getting_started/code_playground.md) guide for more details.
+
+### **Adobe Express Add-on CLI**
+
+Command Line Interface tool for creating, building, and packaging add-ons for local development.
+
+- **Installation**: `npm install -g @adobe/ccweb-add-on-cli`
+- **Common Commands**: `create`, `start`, `build`, `package`
+
+See the [Adobe Express Add-on CLI](../../getting_started/local_development/dev_tooling.md) guide for more details.
+
+### **MCP Server (Model Context Protocol)**
+
+AI-assisted development tool that enhances LLM responses with Adobe Express add-on documentation and TypeScript definitions.
+
+- **Purpose**: Provide semantic documentation search and accurate code suggestions through AI assistants
+- **Requirements**: Node.js 18+ and MCP-compatible IDE (Cursor, VS Code, Claude Desktop)
+
+See the [Adobe Express Add-on MCP Server](../../getting_started/local_development/mcp_server.md) guide for more details.
+
+### **Add-on Development Mode**
+
+Special mode in Adobe Express (**Settings > Add-on Development** toggle) that allows loading and testing local add-ons during development. See [Add-on Development Mode](../../getting_started/local_development/dev_tooling.md) for more details.
+
+## Manifest Configuration
+
+```json
+{
+ "entryPoints": [
+ {
+ "type": "panel",
+ "id": "panel1",
+ "main": "index.html", // iframe runtime entry
+ "documentSandbox": "code.js" // document sandbox entry (optional)
+ }
+ ],
+ "permissions": {
+ "sandbox": ["allow-popups", "allow-downloads"],
+ "oauth": ["www.dropbox.com", "api.example.com"]
+ }
+}
+```
+
+## Quick Decision Guide
+
+**Building a UI Panel?** → Add-on UI SDK (`addOnUISdk`)
+**Creating new content?** → Document APIs (in Document Sandbox, via `editor`)
+**Modifying existing content?** → Document APIs (in Document Sandbox, via `editor`)
+**Connecting UI to Document?** → Communication APIs (`runtime.exposeApi()`, `runtime.apiProxy()`)
+**Need browser features in sandbox?** → Web APIs or proxy from iframe
+
+
+
+**Confused by terminology?**
+
+Many terms like "document", "context", "runtime", and "instance" have multiple meanings. See [Overloaded Terms Clarification](#overloaded-terms-clarification) at the top for complete clarification.
+
+## Troubleshooting Common Issues
+
+### Import Errors
+
+```js
+// ✅ Correct patterns
+import addOnUISdk from "https://express.adobe.com/static/add-on-sdk/sdk.js"; // Default export (no curly braces)
+import addOnSandboxSdk from "add-on-sdk-document-sandbox"; // Default export (no curly braces)
+import { editor, colorUtils, constants, fonts, viewport } from "express-document-sdk"; // Named exports (requires curly braces)
+
+// ❌ Common mistakes
+import { addOnUISdk } from "..."; // Wrong: should be default import (no curly braces)
+import addOnSandboxSdk from "add-on-ui-sdk"; // Wrong: mixed up the SDKs
+import editor from "express-document-sdk"; // Wrong: should be named import (needs curly braces)
+```
+
+### Runtime Context
+
+| When you're in... | You have access to... | To communicate with the other side... |
+|-------------------|----------------------|--------------------------------------|
+| **iframe runtime** | Add-on UI SDK, DOM, Web APIs | Use `runtime.exposeApi()` or `runtime.apiProxy()` |
+| **document sandbox** | Express Document SDK, limited Web APIs | Use `runtime.exposeApi()` or `runtime.apiProxy()` (from Document Sandbox SDK) |
+
+### "undefined" Errors
+
+**Problem**: `addOnUISdk.constants.SomeConstant` returns `undefined`
+**Solution**: Some constants require explicit imports. Check the [Constants Reference](../../../references/addonsdk/addonsdk-constants.md)
+
+---
+
+## FAQs
+
+#### Q: What's the difference between "Add-on UI SDK" and "Document APIs"?
+
+**A:** The **Add-on UI SDK** runs in the iframe runtime and handles UI, user interactions, and import/export. **Document APIs** (via Express Document SDK) run in the document sandbox and handle content creation and document manipulation.
+
+#### Q: Why are there two different runtime environments?
+
+**A:** Security and performance. The **iframe runtime** is sandboxed for security but has standard Web APIs. The **document sandbox** has direct access to Adobe Express's document engine but limited Web APIs.
+
+#### Q: Can I use Document APIs directly from the iframe runtime?
+
+**A:** No, Document APIs (Express Document SDK) are only available in the document sandbox for security reasons. You must use the communication system (Document Sandbox SDK) to bridge between environments.
+
+#### Q: When do I use `addOnUISdk` vs `addOnSandboxSdk`?
+
+**A:** Use `addOnUISdk` (Add-on UI SDK) in your **iframe runtime code** (usually `index.html` or `ui/` folder). Use `addOnSandboxSdk` (Document Sandbox SDK) in your **document sandbox code** (usually `code.js` or `sandbox/` folder).
+
+#### Q: I see references to "UI SDK" - is this different from "Add-on UI SDK"?
+
+**A:** No, they're the same. **"Add-on UI SDK"** is the full, preferred term for clarity, but "UI SDK" is commonly used as shorthand throughout the documentation.
+
+#### Q: What's the difference between `addOnUISdk.instance` and `addOnUISdk.app`?
+
+**A:** These represent **different scopes** of functionality:
+
+- **`addOnUISdk.instance`** - **Add-on scope**: Features specific to YOUR add-on
+ - `instance.runtime` - Communication for YOUR add-on
+ - `instance.clientStorage` - Storage for YOUR add-on only (per-user, per-addon)
+ - `instance.manifest` - YOUR add-on's configuration
+
+- **`addOnUISdk.app`** - **Application scope**: Features shared across Adobe Express
+ - `app.document` - The Adobe Express document (same for all add-ons)
+ - `app.currentUser` - The Express user (not specific to your add-on)
+ - `app.ui` - Adobe Express UI state (theme, locale)
+
+Use `instance` for add-on-specific features; use `app` to interact with Adobe Express itself.
+
+#### Q: I'm confused by terms like "document", "context", "runtime", and "instance" - they seem to mean different things in different places?
+
+**A:** Yes! Many terms in add-on development are overloaded with multiple meanings. Check the **[Overloaded Terms Clarification](#overloaded-terms-clarification)** table at the top of this page for complete clarification. For example, "document" can mean:
+
+- The Adobe Express user's project
+- `editor.documentRoot` (scenegraph manipulation)
+- `addOnUISdk.app.document` (import/export operations)
+- Browser DOM `document` object (your add-on's HTML)
+
+This table provides all meanings with examples for 17 commonly overloaded terms.
+
+#### Q: What is the singleton pattern and why do add-on SDKs use it?
+
+**A:** All Adobe Express add-on SDKs use the **singleton pattern** - they provide pre-instantiated objects you import and use directly. You **never create new instances yourself**.
+
+This ensures all your code works with the same SDK instances, preventing conflicts and maintaining consistent state. For Express Document SDK specifically, you import **lowercase names** (`editor`, `colorUtils`, `constants`, `fonts`, `viewport`) which are singleton objects, NOT the uppercase class names (`Editor`, `ColorUtils`, etc.).
+
+See the [Architecture Guide](../platform_concepts/architecture.md#sdk-structure--import-patterns) for complete details.
+
+---
+
+## Related Documentation
+
+- [Adobe Express Add-ons Developer Guide](https://developer-stage.adobe.com/express/add-ons/docs/guides/) - Official documentation and getting started guide
+- [Add-on Architecture Guide](../platform_concepts/architecture.md) - Comprehensive guide with visual diagrams
+- [Add-on UI SDK Reference](../../../references/addonsdk/index.md)
+- [Document Sandbox Overview](../../../references/document-sandbox/index.md)
+- [Communication APIs](../../../references/document-sandbox/communication/index.md)
+- [Add-on UI SDK Constants Usage Guide](./ui-sdk-constants.md)
+- [Document Sandbox Constants Usage Guide](./document-sandbox-constants.md)
diff --git a/src/pages/guides/learn/fundamentals/ui-sdk-constants.md b/src/pages/guides/learn/fundamentals/ui-sdk-constants.md
new file mode 100644
index 000000000..8ded6ed41
--- /dev/null
+++ b/src/pages/guides/learn/fundamentals/ui-sdk-constants.md
@@ -0,0 +1,320 @@
+---
+keywords:
+ - Adobe Express
+ - Express Add-on SDK
+ - Add-on UI SDK
+ - Constants
+ - Import patterns
+ - Type safety
+ - JavaScript
+ - TypeScript
+ - Named exports
+ - SDK constants
+ - UI constants
+ - Modal dialogs
+ - Document export
+ - Event handling
+ - Color picker
+ - AppEvent
+ - ColorPickerEvent
+title: Using Add-on UI SDK Constants
+description: A practical guide to using constants in the Add-on UI SDK for type-safe development,
+ covering import patterns, common use cases, and best practices for iframe environment development.
+contributors:
+ - https://github.com/hollyschinsky
+faq:
+ questions:
+ - question: "Why do some constants require imports while others don't?"
+ answer: "Adobe Express SDK has two types of constants: dual-access (available both ways) and named-only exports (security/architecture reasons). Always check the Import Patterns section."
+
+ - question: "How do I know if a constant requires import?"
+ answer: "Check the Import Quick Reference in the Constants Reference or use TypeScript for compile-time validation. When in doubt, use named imports - they work for all constants."
+
+ - question: "What's the difference between Range.currentPage and addOnUISdk.constants.Range.currentPage?"
+ answer: "Both work for dual-access constants like Range. Named imports (Range.currentPage) are recommended for cleaner code, while constants object access is useful for dynamic scenarios."
+
+ - question: "Why does addOnUISdk.constants.AppEvent return undefined?"
+ answer: "AppEvent is a named-only export and must be imported. It's not available through the constants object."
+
+ - question: "Can I use string literals instead of constants?"
+ answer: "While possible, constants provide type safety, IDE autocomplete, and future-proofing. Always prefer constants over string literals."
+
+ - question: "What import should I use for document export?"
+ answer: "Use import addOnUISdk, { Range, RenditionFormat, RenditionIntent } from the SDK URL for most export scenarios."
+
+ - question: "Do constants work the same in Document Sandbox?"
+ answer: "No, Document Sandbox has different constants from express-document-sdk. See Document Sandbox Constants for sandbox-specific constants."
+# LLM optimization metadata
+canonical: true
+ai_assistant_note: "This guide focuses specifically on Add-on UI SDK constants used in the iframe
+ environment. For document sandbox constants, refer to the Document Sandbox Constants guide.
+ Covers import patterns, dual access vs named-only exports, and practical usage examples."
+semantic_tags:
+ - ui-sdk-constants
+ - iframe-environment
+ - import-patterns
+ - type-safety
+ - practical-guide
+---
+
+# Using Add-on UI SDK Constants
+
+Add-on UI SDK constants provide type-safe ways to interact with the Add-on UI SDK for UI operations like dialogs, document export, and event handling. This guide covers the most common patterns for iframe environment development.
+
+## Why Use Constants?
+
+Constants equal their variable name as a string (e.g., `ButtonType.primary` equals `"primary"`), but using constants provides type safety, IDE autocomplete, and future-proofing against API changes.
+
+
+
+For complete technical specifications of all constants, see the [Constants Reference](../../../references/addonsdk/addonsdk-constants.md).
+
+## Quick Start
+
+Most constants support two import patterns. Choose based on your needs:
+
+```javascript
+// Named imports (recommended for cleaner code)
+import addOnUISdk, { Range, RenditionFormat, Variant } from "https://express.adobe.com/static/add-on-sdk/sdk.js";
+
+// Constants object access (good for dynamic access)
+const format = addOnUISdk.constants.RenditionFormat.png;
+```
+
+
+
+#### Important
+
+Some constants (like `AppEvent`, `ColorPickerEvent`) are **only available as named exports** and cannot be accessed through `addOnUISdk.constants.*`. See [Import Patterns](#import-patterns) below.
+
+## Most Common Use Cases
+
+### Document Export
+
+The most common constants you'll use for exporting documents:
+
+```javascript
+import addOnUISdk, { Range, RenditionFormat, RenditionIntent } from "https://express.adobe.com/static/add-on-sdk/sdk.js";
+
+// Export current page as PNG
+await addOnUISdk.app.document.createRenditions({
+ range: Range.currentPage,
+ format: RenditionFormat.png
+});
+
+// Export entire document as PDF for printing
+await addOnUISdk.app.document.createRenditions({
+ range: Range.entireDocument,
+ format: RenditionFormat.pdf,
+ intent: RenditionIntent.print
+});
+```
+
+**Available Options:**
+
+- `Range`: `currentPage`, `entireDocument`, `specificPages`
+- `RenditionFormat`: `png`, `jpg`, `mp4`, `pdf`, `pptx`
+- `RenditionIntent`: `export`, `preview`, `print`
+
+### Modal Dialogs
+
+Essential constants for user interactions:
+
+```javascript
+import addOnUISdk, { Variant, ButtonType } from "https://express.adobe.com/static/add-on-sdk/sdk.js";
+
+// Show confirmation dialog
+const result = await addOnUISdk.app.showModalDialog({
+ variant: Variant.confirmation,
+ title: "Delete Item",
+ description: "Are you sure?"
+});
+
+// Handle user response
+if (result.buttonType === ButtonType.primary) {
+ // User confirmed
+} else if (result.buttonType === ButtonType.cancel) {
+ // User cancelled
+}
+```
+
+**Available Options:**
+
+- `Variant`: `confirmation`, `information`, `warning`, `error`, `input`
+- `ButtonType`: `primary`, `secondary`, `cancel`, `close`
+- `FieldType`: `text`, `password` (for input dialogs)
+
+### Event Handling
+
+**Important:** Event constants must be imported - they're not available in the constants object:
+
+```javascript
+import addOnUISdk, { AppEvent } from "https://express.adobe.com/static/add-on-sdk/sdk.js";
+
+// ✅ Correct - must import AppEvent
+addOnUISdk.app.on(AppEvent.themechange, (event) => {
+ updateUITheme(event.theme);
+});
+
+// ❌ This will NOT work
+addOnUISdk.app.on(addOnUISdk.constants.AppEvent.themechange, handler); // undefined!
+```
+
+**Common Event Types:**
+
+- `AppEvent.themechange` - Detect theme changes (light/dark)
+- `AppEvent.localechange` - Detect locale/language changes
+
+## Copy-Paste Import Statements
+
+### Most Common Scenarios
+
+```javascript
+// Document Export & Rendering
+import addOnUISdk, { Range, RenditionFormat, RenditionIntent } from "https://express.adobe.com/static/add-on-sdk/sdk.js";
+
+// Modal Dialogs & UI
+import addOnUISdk, { Variant, ButtonType, FieldType } from "https://express.adobe.com/static/add-on-sdk/sdk.js";
+
+// Event Handling (Import Required)
+import addOnUISdk, { AppEvent, ColorPickerEvent } from "https://express.adobe.com/static/add-on-sdk/sdk.js";
+```
+
+## Import Patterns
+
+Understanding import patterns is crucial for avoiding runtime errors. Adobe Express Add-on SDK constants are available through different patterns depending on the constant type.
+
+### Must Import (Named Exports Only)
+
+These constants **must be imported** and are **not available** through `addOnUISdk.constants.*`:
+
+```javascript
+import addOnUISdk, {
+ AppEvent, // ❌ NOT in constants object
+ ColorPickerEvent, // ❌ NOT in constants object
+ SupportedMimeTypes, // ❌ NOT in constants object
+ EntrypointType // ❌ NOT in constants object
+} from "https://express.adobe.com/static/add-on-sdk/sdk.js";
+
+// ✅ Correct usage
+const docxMimeType = SupportedMimeTypes.docx;
+const colorChangeEvent = ColorPickerEvent.colorChange;
+
+// ❌ Will NOT work - these are not in the constants object
+const docxMimeType = addOnUISdk.constants.SupportedMimeTypes.docx; // undefined!
+```
+
+### Flexible Access (Both Ways Work)
+
+These constants support **both patterns** - you can use either approach:
+
+```javascript
+import addOnUISdk, { Range, RenditionFormat, Variant } from "https://express.adobe.com/static/add-on-sdk/sdk.js";
+
+// Option 1: Named import (recommended for cleaner code)
+const options = {
+ range: Range.currentPage,
+ format: RenditionFormat.png,
+ variant: Variant.error
+};
+
+// Option 2: Constants object (good for dynamic access)
+const userFormat = "png";
+const format = addOnUISdk.constants.RenditionFormat[userFormat];
+```
+
+**Dual Access Constants Include:**
+
+- `Range`, `RenditionFormat`, `RenditionIntent`, `RenditionType`
+- `Variant`, `ButtonType`, `FieldType`, `DialogResultType`
+- `PlatformType`, `DeviceClass`, `PlatformEnvironment`
+- `EditorPanel`, `MediaTabs`, `ElementsTabs`, `PanelActionType`
+- `AuthorizationStatus`, `RuntimeType`, `BleedUnit`, `ColorPickerPlacement`
+- `VideoResolution`, `FrameRate`, `BitRate`, `FileSizeLimitUnit`, `LinkOptions`
+
+## Common Errors & Solutions
+
+### "Cannot read property of undefined"
+
+**Problem**: Trying to access named-only exports through constants object.
+
+```javascript
+// ❌ This causes errors
+const event = addOnUISdk.constants.AppEvent.themechange; // undefined!
+```
+
+**Solution**: Always import named-only exports.
+
+```javascript
+// ✅ This works
+import addOnUISdk, { AppEvent } from "https://express.adobe.com/static/add-on-sdk/sdk.js";
+const event = AppEvent.themechange;
+```
+
+### Using String Literals Instead of Constants
+
+**Problem**: Using fragile string literals.
+
+```javascript
+// ❌ Fragile - might break if API changes
+await createRenditions({
+ range: "currentPage", // String literal
+ format: "image/png" // String literal
+});
+```
+
+**Solution**: Always use constants.
+
+```javascript
+// ✅ Safe - will be updated if API changes
+await createRenditions({
+ range: Range.currentPage, // Constant
+ format: RenditionFormat.png // Constant
+});
+```
+
+## Best Practices
+
+1. **Use named imports for known constants** - cleaner and more reliable
+2. **Use constants object for dynamic access** - when the constant name is determined at runtime
+3. **Always import named-only exports** - there's no alternative way to access them
+4. **Group related imports** - organize by functionality for better readability
+
+## FAQs
+
+#### Q: Why do some constants require imports while others don't?
+
+**A:** Adobe Express SDK has two types of constants: dual-access (available both ways) and named-only exports (security/architecture reasons). Always check the [Import Patterns](#import-patterns) section.
+
+#### Q: How do I know if a constant requires import?
+
+**A:** Check the [Import Quick Reference](../../../references/addonsdk/addonsdk-constants.md#import-quick-reference) in the Constants Reference or use TypeScript for compile-time validation. When in doubt, use named imports - they work for all constants.
+
+#### Q: What's the difference between `Range.currentPage` and `addOnUISdk.constants.Range.currentPage`?
+
+**A:** Both work for dual-access constants like `Range`. Named imports (`Range.currentPage`) are recommended for cleaner code, while constants object access is useful for dynamic scenarios.
+
+#### Q: Why does `addOnUISdk.constants.AppEvent` return undefined?
+
+**A:** `AppEvent` is a named-only export and must be imported: `import addOnUISdk, { AppEvent } from "..."`. It's not available through the constants object.
+
+#### Q: Can I use string literals instead of constants?
+
+**A:** While possible, constants provide type safety, IDE autocomplete, and future-proofing. Always prefer constants over string literals like `"currentPage"`.
+
+#### Q: What import should I use for document export?
+
+**A:** Use `import addOnUISdk, { Range, RenditionFormat, RenditionIntent } from "https://express.adobe.com/static/add-on-sdk/sdk.js"` for most export scenarios.
+
+#### Q: Do constants work the same in Document Sandbox?
+
+**A:** No, Document Sandbox has different constants from `express-document-sdk`. See [Document Sandbox Constants](./document-sandbox-constants.md) for sandbox-specific constants.
+
+## Next Steps
+
+- **Complete Reference**: See [Constants Reference](../../../references/addonsdk/addonsdk-constants.md) for all available constants
+- **Practical Guides**:
+ - [Create Renditions](../how_to/create_renditions.md) - Using export constants
+ - [Modal Dialogs](../how_to/modal_dialogs.md) - Using dialog constants
+ - [Use Color](../how_to/use_color.md) - Using color picker constants
+ - [Theme & Locale](../how_to/theme_locale.md) - Using event constants
diff --git a/src/pages/guides/learn/how_to/handle_selection.md b/src/pages/guides/learn/how_to/handle_selection.md
index 9676905cd..c7ed3dbd6 100644
--- a/src/pages/guides/learn/how_to/handle_selection.md
+++ b/src/pages/guides/learn/how_to/handle_selection.md
@@ -59,6 +59,26 @@ faq:
- question: "What are common selection-based actions?"
answer: "Typical actions include updating properties panels, enabling/disabling tools, applying formatting to selected text, grouping elements, and showing context-appropriate options."
+canonical: true
+ai_assistant_note: "This is the authoritative guide for working with element selections in Adobe Express add-ons.
+ Use this when helping developers understand: how to get/set/clear selections, selection change event handling,
+ selection rules and constraints, locked/non-editable element handling, selection-based UI updates, and communication
+ between document sandbox and UI panel for selection data. Critical: Always emphasize that document modifications
+ must NEVER happen inside selection change handlers - this can crash the application. Selection handlers should only
+ update UI, analyze data, or communicate with the panel."
+semantic_tags:
+ - canonical-reference
+ - selection-handling
+ - event-handling
+ - context-api
+ - selection-change-events
+ - document-sandbox
+ - ui-integration
+ - selection-rules
+ - locked-nodes
+ - properties-panel
+ - real-time-updates
+ - best-practices
---
# Handle Element Selection
@@ -77,7 +97,7 @@ All selection operations use the **Document API** and run in the **document sand
Make sure your `manifest.json` includes `"documentSandbox": "code.js"` in the entry points to set up the document sandbox environment.
-### Check Current Selection
+### Quick Start Example
@@ -89,13 +109,7 @@ import { editor } from "express-document-sdk";
// Check if anything is selected
if (editor.context.hasSelection) {
- const selection = editor.context.selection;
- console.log(`Selected ${selection.length} item(s)`);
-
- // Process each selected node
- selection.forEach((node, index) => {
- console.log(`Node ${index + 1}: ${node.type}`);
- });
+ console.log(`Selected ${editor.context.selection.length} item(s)`);
} else {
console.log("Nothing is selected");
}
@@ -105,17 +119,11 @@ if (editor.context.hasSelection) {
```ts
// sandbox/code.ts
-import { editor, Node, EditorEvent } from "express-document-sdk";
+import { editor } from "express-document-sdk";
// Check if anything is selected
if (editor.context.hasSelection) {
- const selection: readonly Node[] = editor.context.selection;
- console.log(`Selected ${selection.length} item(s)`);
-
- // Process each selected node
- selection.forEach((node: Node, index: number) => {
- console.log(`Node ${index + 1}: ${node.type}`);
- });
+ console.log(`Selected ${editor.context.selection.length} item(s)`);
} else {
console.log("Nothing is selected");
}
@@ -130,14 +138,7 @@ In Adobe Express, the selection system provides:
- **Selection events** - React to selection changes
- **Selection filtering** - Handle locked/non-editable content
-### Selection Rules
-
-Adobe Express enforces these constraints:
-
-1. **Artboard constraint** - Only nodes within the current artboard can be selected
-2. **Hierarchy filtering** - Cannot select both parent and child nodes simultaneously
-3. **Locked node filtering** - Locked nodes are excluded from the main selection
-4. **Editable-only** - Main selection only includes editable nodes
+The selection system automatically enforces constraints like artboard boundaries and hierarchy rules. See the [Best Practices & Guidelines](#best-practices--guidelines) section for complete details on selection rules and restrictions.
## Basic Selection Operations
@@ -676,13 +677,13 @@ editor.context.on(EditorEvent.selectionChange, () => {
});
```
-## UI Integration
+## Practical Selection Patterns
-Communicate selection changes between the document sandbox and your UI panel to create responsive interfaces.
+Real-world patterns for building selection-based features in your add-on.
-### Selection-Based Actions
+### Performing Actions on Selected Elements
-Common patterns for performing actions on selected elements:
+Common patterns for applying changes to selected elements:
@@ -831,7 +832,9 @@ editor.context.on(EditorEvent.selectionChange, () => {
});
```
-### Selection State Management
+### Advanced: Selection State Management
+
+Track selection history and manage complex selection states:
@@ -984,205 +987,105 @@ const selectionManager = new SelectionManager();
## Best Practices & Guidelines
-### Event Handler Cleanup
-
-⚠️ **Important**: Always clean up event handlers to prevent memory leaks.
-
-
-
-#### JavaScript
-
-```js
-// sandbox/code.js
-import { editor, EditorEvent } from "express-document-sdk";
-
-// Store handler IDs for cleanup
-let selectionHandlerId = null;
-
-function setupSelectionHandling() {
- // Register handler and store ID
- selectionHandlerId = editor.context.on(EditorEvent.selectionChange, () => {
- console.log("Selection changed");
- // Handle selection change
- });
-
- console.log("Selection handler registered");
-}
-
-function cleanupSelectionHandling() {
- // Unregister the handler
- if (selectionHandlerId) {
- editor.context.off(EditorEvent.selectionChange, selectionHandlerId);
- selectionHandlerId = null;
- console.log("Selection handler unregistered");
- }
-}
-
-// Setup
-setupSelectionHandling();
-
-// Cleanup when add-on is being destroyed or reset
-// cleanupSelectionHandling();
-```
+### Selection Handler Restrictions
-#### TypeScript
+
-```ts
-// code.ts
-import { editor, EditorEvent } from "express-document-sdk";
+Document Modification Restrictions
-// Store handler IDs for cleanup
-let selectionHandlerId: string | null = null;
+**Never modify the document inside selection change handlers!** This can crash the application.
-function setupSelectionHandling(): void {
- // Register handler and store ID
- selectionHandlerId = editor.context.on(EditorEvent.selectionChange, () => {
- console.log("Selection changed");
- // Handle selection change
- });
-
- console.log("Selection handler registered");
-}
+**✅ Safe in selection handlers:**
-function cleanupSelectionHandling(): void {
- // Unregister the handler
- if (selectionHandlerId) {
- editor.context.off(EditorEvent.selectionChange, selectionHandlerId);
- selectionHandlerId = null;
- console.log("Selection handler unregistered");
- }
-}
+ - Update UI panels
+ - Log information
+ - Analyze selection
+ - Enable/disable buttons
+ - Send data to UI panel
-// Setup
-setupSelectionHandling();
+**❌ Never do in selection handlers:**
-// Cleanup when add-on is being destroyed or reset
-// cleanupSelectionHandling();
-```
+ - Create, delete, or modify nodes
+ - Change document structure
+ - Set properties on selected elements
### Selection System Rules
+Adobe Express enforces these constraints:
+
1. **Artboard constraint**: Only nodes within the current artboard can be selected
2. **Hierarchy filtering**: Cannot select both parent and child nodes simultaneously
3. **Locked node handling**: Locked nodes are excluded from main selection but available in `selectionIncludingNonEditable`
4. **Automatic filtering**: System automatically filters out invalid selections
-### Important: Selection Handler Restrictions
-
-
-
-**Document Modification Restrictions**
-
-**Never modify the document inside selection change handlers!** This can crash the application.
-
-**✅ Safe in selection handlers:**
-
-- Update UI panels
-- Log information
-- Analyze selection
-- Enable/disable buttons
-- Send data to UI panel
-
-**❌ Never do in selection handlers:**
-
-- Create, delete, or modify nodes
-- Change document structure
-- Set properties on selected elements
-
-
-
### Performance Guidelines
-1. **Keep handlers fast**: Minimize processing time
-2. **Essential work only**: Avoid heavy computations
-3. **Clean Up**: Always unregister handlers when done (`editor.context.off()`)
-4. **Avoid Heavy Work**: Don't do complex calculations in selection callbacks
+1. **Keep handlers fast**: Minimize processing time and avoid heavy computations in selection callbacks
+2. **Essential work only**: Only perform UI updates, logging, or data analysis in selection handlers
+3. **Always clean up**: Unregister event handlers when done using `editor.context.off()` to prevent memory leaks
-### Communication Between UI and Document Sandbox
+### Communicating with Your UI Panel
-One of the most important real-world patterns is communicating selection changes from the document sandbox to your UI panel, allowing you to update the interface based on what the user has selected.
+To create responsive interfaces, you'll need to communicate selection changes from the document sandbox to your UI panel. This allows you to update buttons, property panels, and other UI elements based on what the user has selected.
-For detailed information on the communication APIs, see the [Communication API reference](../../../references/document-sandbox/communication/).
+For complete details on setting up bidirectional communication between your document sandbox and UI panel, see the [Communication API reference](../../../references/document-sandbox/communication/).
-#### Complete Communication Example
+## Quick Reference
-This example shows how to set up bidirectional communication between your UI panel and document sandbox for selection-based interactions.
+### Common Selection Operations
-## Quick Reference & Common Patterns
+```js
+// Get current selection
+const selection = editor.context.selection;
-Here are some frequently used patterns you can copy and adapt:
+// Check if anything is selected
+if (editor.context.hasSelection) { /* ... */ }
-### Conditional Actions Based on Selection
+// Select a single element
+editor.context.selection = node;
-```js
-// code.js
-import { editor, EditorEvent } from "express-document-sdk";
+// Select multiple elements
+editor.context.selection = [node1, node2, node3];
-// Enable/disable actions based on selection type
-editor.context.on(EditorEvent.selectionChange, () => {
- const selection = editor.context.selection;
-
- // Communicate with your UI panel
- const actions = {
- canGroup: selection.length >= 2,
- canApplyTextStyle: selection.some(node => node.type === "Text"),
- canApplyFill: selection.some(node =>
- ["Rectangle", "Ellipse"].includes(node.type)
- ),
- isEmpty: selection.length === 0
- };
-
- // Send to UI panel for enabling/disabling buttons
- // (Use the communication API to send this data)
-});
+// Clear selection
+editor.context.selection = [];
+
+// Get selection including locked nodes
+const fullSelection = editor.context.selectionIncludingNonEditable;
```
-### Selection-Based Properties Panel
+### Selection Event Handling
```js
-// code.js
-import { editor, EditorEvent } from "express-document-sdk";
-
-// Update properties panel based on selection
-editor.context.on(EditorEvent.selectionChange, () => {
+// Register selection change handler
+const handlerId = editor.context.on(EditorEvent.selectionChange, () => {
const selection = editor.context.selection;
-
- if (selection.length === 1) {
- const node = selection[0]; // Common pattern: access first selected element
-
- // Send node properties to UI for editing
- const properties = {
- type: node.type,
- width: node.width || null,
- height: node.height || null,
- x: node.translation?.x || null,
- y: node.translation?.y || null,
- locked: node.locked || false
- };
-
- // Update UI panel with these properties
- console.log("Node properties:", properties);
- }
+ // Handle selection change
});
-```
-### Working with Single Selection
+// Clean up handler
+editor.context.off(EditorEvent.selectionChange, handlerId);
+```
-Many add-ons focus on single-element operations. Here's a common pattern used throughout the documentation:
+### Common Selection Patterns
```js
-// code.js
-import { editor } from "express-document-sdk";
-
-// Safe access to first selected element (used in use_text.md and other guides)
-if (editor.context.hasSelection) {
- const selectedNode = editor.context.selection[0];
-
- // Perform operations on the selected node
- if (selectedNode.type === "Text") {
- // Handle text-specific operations
- }
-}
+// Access first selected element
+const node = editor.context.selection[0];
+
+// Filter selection by type
+const textNodes = selection.filter(node => node.type === "Text");
+
+// Check selection count
+if (selection.length === 0) { /* nothing selected */ }
+if (selection.length === 1) { /* single selection */ }
+if (selection.length > 1) { /* multiple selection */ }
+
+// Check for specific node types
+const hasText = selection.some(node => node.type === "Text");
+const hasShapes = selection.some(node =>
+ ["Rectangle", "Ellipse"].includes(node.type)
+);
```
## FAQs
diff --git a/src/pages/guides/learn/how_to/manage_pages.md b/src/pages/guides/learn/how_to/manage_pages.md
index 27f6554b5..23e6cb79a 100644
--- a/src/pages/guides/learn/how_to/manage_pages.md
+++ b/src/pages/guides/learn/how_to/manage_pages.md
@@ -41,7 +41,7 @@ faq:
answer: "Adding a page automatically switches to it. You can also access pages via `editor.documentRoot.pages`."
- question: "What happens when I add a page?"
- answer: "A new page with a default artboard is created and automatically becomes the active page and insertion parent."
+ answer: "A new page with a default artboard is created and automatically becomes the active page. The artboard becomes the insertion parent for new content."
- question: "Can I remove pages?"
answer: "Currently, the Document API doesn't provide a direct method to remove pages programmatically."
@@ -51,6 +51,25 @@ faq:
- question: "What are the minimum requirements for a page?"
answer: "Every page must have at least one artboard. The `editor.documentRoot.pages.addPage()` method automatically creates a default artboard."
+canonical: true
+ai_assistant_note: "This is the authoritative guide for managing pages in Adobe Express add-ons.
+ Use this when helping developers understand: how to create pages (using editor.documentRoot.pages.addPage(),
+ NOT createPage()), accessing current and all pages, working with page artboards, page dimensions and geometry,
+ and the relationship between pages, artboards, and content. Important: Always emphasize that pages are created
+ with editor.documentRoot.pages.addPage() - there is NO createPage() method. Adding a page automatically makes
+ it active and switches the viewport to it."
+semantic_tags:
+ - canonical-reference
+ - page-management
+ - document-structure
+ - page-creation
+ - artboards
+ - document-api
+ - page-navigation
+ - page-hierarchy
+ - insertion-context
+ - page-dimensions
+ - best-practices
---
# Manage Pages
@@ -59,14 +78,18 @@ Learn how to programmatically create, access, and manage pages in Adobe Express
## Understanding Pages in Adobe Express
-In Adobe Express, documents are organized hierarchically:
+In Adobe Express, documents are organized as a **scenegraph** - a hierarchical tree structure:
-- **Document** (root)
- - **Pages** (timeline sequence)
- - **Artboards** (scenes within a page)
- - **Content** (text, shapes, media, etc.)
+- **Document** (root - `ExpressRootNode`)
+ - **Pages** (`PageNode` in `PageList`)
+ - **Artboards** (`ArtboardNode` in `ArtboardList` - timeline scenes)
+ - **Content** (shapes, text, images, groups, etc.)
-Every page contains at least one artboard, and all artboards within a page share the same dimensions.
+Every page contains at least one artboard. When a page has multiple artboards, they represent keyframe "scenes" in a linear animation timeline. All artboards within a page share the same dimensions.
+
+
+
+For more on the document scenegraph and node hierarchy, see the [Document API Concepts Guide](../platform_concepts/document-api.md) and [Developer Terminology Guide](../fundamentals/terminology.md).
## Add a Page
@@ -198,7 +221,7 @@ console.log("Number of artboards:", currentPage.artboards.length);
#### TypeScript
```ts
-// sandbox/code.js
+// sandbox/code.ts
import { editor, PageNode } from "express-document-sdk";
// Get the currently active page
@@ -449,7 +472,7 @@ const templatePages = createTemplatePages();
### Check Page Properties
-For detailed page information including content analysis and print readiness, see the [Page Metadata Ho-to Guide](page_metadata.md).
+For detailed page information including content analysis and print readiness, see the [Page Metadata How-to Guide](page_metadata.md).
@@ -513,86 +536,36 @@ function analyzeDocument(): void {
analyzeDocument();
```
-## Key Concepts
-
-### Pages vs Artboards
-
-- **Pages**: Top-level containers in the document timeline
-- **Artboards**: "Scenes" within a page containing the actual content
-- All artboards within a page share the same dimensions
-- When you add a page, it automatically gets one default artboard
-
-### Insertion Context
-
-- Adding a page automatically makes it the active page
-- `editor.context.insertionParent` points to the active artboard
-- New content is added to the current insertion parent
-- The viewport switches to display the new page
+## Key Concepts & Best Practices
-### Common Pitfalls
-
-When working with pages, avoid these common mistakes:
+### Important: Use the Correct Method
-Critical: Use the correct method path
+Pages require a unique API path
-The Adobe Express Document API requires the full method path to create pages:
+Unlike other creation methods (like `editor.createRectangle()`), pages require the full path through the document structure:
- ❌ `editor.addPage()` (doesn't exist)
- ❌ `editor.createPage()` (doesn't exist)
- ✅ `editor.documentRoot.pages.addPage()` (correct)
-1. **Don't assume API consistency** - Unlike other creation methods (like `editor.createRectangle()`), pages require the full path through the document structure.
-2. **Provide page dimensions** - The `addPage()` method requires a geometry parameter with width and height.
-3. **Expect automatic navigation** - Adding a page automatically switches to it and updates the viewport.
-4. **Remember shared dimensions** - All artboards within a page must have the same dimensions.
-
-## Integration with Other APIs
-
-### Using with Metadata APIs
-
-Pages created with `editor.documentRoot.pages.addPage()` can be used with other Document APIs, particularly for retrieving metadata. See the [Page Metadata How-to Guide](page_metadata.md) for complete examples.
-
-
-
-#### JavaScript
-
-```js
-// sandbox/code.js
-import { editor } from "express-document-sdk";
-
-// Add a page and get its metadata
-const newPage = editor.documentRoot.pages.addPage({ width: 1080, height: 1080 });
-
-// Get the page ID for use with Add-on UI SDK metadata APIs
-console.log("New page ID:", newPage.id);
-
-// You can use this ID with the Add-on UI SDK to get detailed metadata
-// See the Page Metadata guide for complete examples:
-// const pageMetadata = await addOnUISdk.app.document.getPagesMetadata({
-// pageIds: [newPage.id]
-// });
-```
-
-#### TypeScript
+### Important Behaviors
-```ts
-// sandbox/code.ts
-import { editor, PageNode } from "express-document-sdk";
+1. **Automatic activation** - Adding a page automatically makes it the active page and switches the viewport to it
+2. **Required dimensions** - The `addPage()` method requires a geometry parameter with width and height
+3. **Default artboard** - Every new page automatically gets one default artboard
+4. **Shared dimensions** - All artboards within a page must have the same dimensions
+5. **Insertion context** - `editor.context.insertionParent` points to the active artboard where new content is added
-// Add a page and get its metadata
-const newPage: PageNode = editor.documentRoot.pages.addPage({ width: 1080, height: 1080 });
+## Integration with Other APIs
-// Get the page ID for use with Add-on UI SDK metadata APIs
-console.log("New page ID:", newPage.id);
+Pages created with `editor.documentRoot.pages.addPage()` integrate seamlessly with other Adobe Express APIs:
-// You can use this ID with the Add-on UI SDK to get detailed metadata
-// See the Page Metadata guide for complete examples:
-// const pageMetadata = await addOnUISdk.app.document.getPagesMetadata({
-// pageIds: [newPage.id]
-// });
-```
+- **Metadata APIs** - Use `newPage.id` with Add-on UI SDK metadata APIs to retrieve detailed page information. See the [Page Metadata How-to Guide](page_metadata.md) for complete examples.
+- **Rendition APIs** - Export specific pages as images, PDFs, or videos. See [Create Renditions](create_renditions.md).
+- **Selection APIs** - Work with selected content on pages. See [Handle Element Selection](handle_selection.md).
+- **Content APIs** - Add text, shapes, images, and other content to page artboards using the Document API.
## FAQs
@@ -614,7 +587,7 @@ console.log("New page ID:", newPage.id);
#### Q: What happens when I add a page?
-**A:** A new page with a default artboard is created and automatically becomes the active page and insertion parent.
+**A:** A new page with a default artboard is created and automatically becomes the active page. The artboard becomes the insertion parent for new content.
#### Q: Can I remove pages?
@@ -654,4 +627,4 @@ console.log("New page ID:", newPage.id);
### Advanced Topics
- **[Create Renditions](create_renditions.md)** - Export specific pages or entire documents as images, PDFs, or videos
-- **[Page Metadata](page_metadata.md)** - Retrieve detailed page information including dimensions, content analysis, and print readiness
+- **[Handle Element Selection](handle_selection.md)** - Work with selected elements on pages
diff --git a/src/pages/guides/learn/how_to/tutorials/grids-addon.md b/src/pages/guides/learn/how_to/tutorials/grids-addon.md
index 674e71643..ec424a5af 100644
--- a/src/pages/guides/learn/how_to/tutorials/grids-addon.md
+++ b/src/pages/guides/learn/how_to/tutorials/grids-addon.md
@@ -99,7 +99,7 @@ Your add-on will allow users to create a variable number of rows and columns, co
As part of the [Document Model Sandbox](/references/document-sandbox/index.md), the Adobe Express Document API (from now on, Document API) is a powerful tool that extends the capabilities of Adobe Express add-ons, offering direct interaction with the open document. Let's take a moment to review the difference between the two core components of the architecture of an add-on.
-- The **iframe** hosts the add-on User Interface and runs its internal logic. You can think about it as a web application operating in a sandboxed environment: it needs to be separate from the rest of the Adobe Express content for security reasons, which is precisely why the add-on is hosted within an `