✨ Add naturalChildOrdering flag to Plugin's API

plugins/CHANGELOG.md

@@ -1,6 +1,10 @@
+## 1.5.0 (Unreleased)
+
+- **plugin-types**: Added a flags subcontexts with the flag `naturalChildrenOrdering`
+
 ## 1.4.2 (2026-01-21)
 
-- **plugin-types:** fix atob/btoa functions
+- **plugin-runtime:** fix atob/btoa functions
 
 ## 1.4.0 (2026-01-21)
 

plugins/libs/plugin-types/index.d.ts

@@ -804,6 +804,11 @@ export interface Context {
    */
   readonly viewport: Viewport;
 
+  /**
+   * Provides flags to customize the API behavior.
+   */
+  readonly flags: Flags;
+
   /**
    * Context encapsulating the history operations
    *
@@ -1679,6 +1684,19 @@ export interface Fill {
   fillImage?: ImageData;
 }
 
+/**
+ * This subcontext allows the API o change certain defaults
+ */
+export interface Flags {
+  /**
+   * If `true` the .children property will be always sorted in the z-index ordering.
+   * Also, appendChild method will be append the children in the top-most position.
+   * The insertchild method is changed acordingly to respect this ordering.
+   * Defaults to false
+   */
+  naturalChildOrdering: boolean;
+}
+
 /**
  * Represents a flexible layout configuration in Penpot.
  * This interface extends `CommonLayout` and includes properties for defining the direction,

plugins/libs/plugins-runtime/src/lib/api/index.ts

@@ -1,31 +1,32 @@
 import type {
-  Penpot,
-  EventsMap,
-  Page,
-  Shape,
-  Rectangle,
-  Board,
-  Group,
-  Viewport,
-  Text,
-  File,
-  Theme,
-  LibraryContext,
-  Ellipse,
-  Path,
-  BooleanType,
-  Boolean,
-  User,
   ActiveUser,
-  FontsContext,
-  SvgRaw,
+  Board,
+  Boolean,
+  BooleanType,
   Color,
   ColorShapeInfo,
+  Ellipse,
+  EventsMap,
+  File,
+  Flags,
+  FontsContext,
+  Group,
   HistoryContext,
-  LocalStorage,
-  VariantContainer,
   LibraryComponent,
+  LibraryContext,
   LibraryVariantComponent,
+  LocalStorage,
+  Page,
+  Path,
+  Penpot,
+  Rectangle,
+  Shape,
+  SvgRaw,
+  Text,
+  Theme,
+  User,
+  VariantContainer,
+  Viewport,
 } from '@penpot/plugin-types';
 
 import { Permissions } from '../models/manifest.model.js';
@@ -193,6 +194,10 @@ export function createApi(
       return plugin.context.fonts;
     },
 
+    get flags(): Flags {
+      return plugin.context.flags;
+    },
+
     get currentUser(): User {
       checkPermission('user:read');
       return plugin.context.currentUser;