@digital-gravy/etch-public-api 0.8.0 → 0.8.2

package/dist/index.d.cts

@@ -1048,7 +1048,7 @@ interface EtchComponentsApi {
  * - `loop-manager` — the loop manager
  * - `asset-manager` — the asset (media) library
  */
-type NavigationPlace = 'builder' | 'templates' | 'style-manager' | 'content-hub' | 'loop-manager' | 'asset-manager';
+type NavigationPlace = 'builder' | 'templates' | 'style-manager' | 'content-hub' | 'loop-manager' | 'data-manager' | 'asset-manager';
 /** Lightweight post entry returned by `navigation.listPostsAsync()`. */
 interface PostSummary {
     /** Post id. */
@@ -1290,6 +1290,38 @@ interface EtchSkillsApi {
     getReference(name: string, file: string): string | undefined;
 }
 
+/**
+ * External AI agent presence (`etch.ai`).
+ *
+ * Lets a connected agent advertise that it is working in this tab and what
+ * phase it is in, driving the builder's presence overlay. Intended to be set
+ * from a bridge connection (see `connectAs`), where pushed scripts reach only
+ * `window.etch` — so this is the supported way to toggle the overlay.
+ */
+/**
+ * The phase an external agent reports.
+ *
+ * - `idle` — agent not present; the presence overlay is hidden.
+ * - `working` — agent is actively editing the canvas.
+ * - `waiting` — agent is waiting on the human (input, approval).
+ * - `thinking` — agent is reasoning before it acts.
+ */
+type ExternalAiState = 'idle' | 'working' | 'waiting' | 'thinking';
+/** Advertise external AI agent presence and phase to the builder. */
+interface EtchAiApi {
+    /** The agent's current presence phase (`idle` when not present). */
+    getState(): ExternalAiState;
+    /**
+     * Set the agent's presence phase. Any non-`idle` value shows the presence
+     * overlay; `idle` hides it.
+     *
+     * @throws `EtchApiError` (`INVALID_ARGUMENT`) for an unknown state.
+     */
+    setState(state: ExternalAiState): void;
+    /** Clear presence — shorthand for `setState('idle')`. */
+    hide(): void;
+}
+
 /**
  * Builder chrome controls (`etch.ui`) and undo/redo (`etch.history`).
  */
@@ -1425,6 +1457,8 @@ interface Etch {
     history: EtchHistoryApi;
     /** Bundled, read-only authoring skills (guides + reference subskills). */
     skills: EtchSkillsApi;
+    /** External AI agent presence: advertise that an agent is working here. */
+    ai: EtchAiApi;
     /** Persist everything (blocks, loops, styles, UI). */
     saveAsync(): Promise<void>;
     /**
@@ -1520,4 +1554,4 @@ declare function isEtchApiError(value: unknown): value is EtchApiError;
  */
 declare const ETCH_API_VERSION = "0.x";
 
-export { type ArrayComponentProperty, type BlockLoopBinding, type BlockPatch, type BooleanComponentProperty, type BooleanParam, type BridgeConnectOptions, type ClassComponentProperty, type ColorScheme, type ComponentPatch, type ComponentProperty, type ComponentPropertyBase, type ConditionComponentProperty, type ConnectOptions, type CopyObject, type CustomField, type CustomFieldAssignment, type CustomFieldGroup, type CustomFieldType, ETCH_API_VERSION, type Etch, EtchApiError, type EtchApiErrorCode, type EtchBlockCommon, type EtchBlockContext, type EtchBlockJson, type EtchBlockOptions, type EtchBlockScript, type EtchBlockType, type EtchBlockTypeName, type EtchBlocksApi, type EtchBridgeConnection, type EtchComponentBlockJson, type EtchComponentsApi, type EtchConditionBlockJson, type EtchDynamicElementBlockJson, type EtchDynamicImageBlockJson, type EtchElementBlockJson, type EtchFieldsApi, type EtchHistoryApi, type EtchHtmlAttributes, type EtchLoop, type EtchLoopBlockJson, type EtchLoopConfig, type EtchLoopObj, type EtchLoopsApi, type EtchNavigationApi, type EtchPassthroughBlockJson, type EtchPostContentBlockJson, type EtchRawHtmlBlockJson, type EtchSkillsApi, type EtchSlotContentBlockJson, type EtchSlotPlaceholderBlockJson, type EtchStylesApi, type EtchStylesheetsApi, type EtchSvgBlockJson, type EtchTextBlockJson, type EtchUiApi, type FindBlocksPredicate, type GroupComponentProperty, type GutenbergBlock, type LoopParamRef, type MetaQueryItem, type NavigationPlace, type NumberComponentProperty, type NumericParam, type ObjectComponentProperty, type PostCustomFieldGroupEntry, type PostCustomFieldValueEntry, type PostCustomFieldValueResponse, type PostCustomFieldValuesResponse, type PostSummary, type PublicBlockJson, type PublicComponentJson, type PublicComponentSummary, type RepeaterComponentProperty, type ResolvedCustomField, type SelectOptionsString, type SkillDetail, type SkillSummary, type StringComponentProperty, type StyleListFilter, type StylePatch, type StyleSelectorType, type StyleSummary, type StylesheetInput, type StylesheetPatch, type StylesheetSummary, type StylesheetType, type TaxQueryItem, type TemplateSummary, type WpQueryArgs, type WpTermsArgs, type WpUsersArgs, getEtch, isEtchApiError, isEtchAvailable };
+export { type ArrayComponentProperty, type BlockLoopBinding, type BlockPatch, type BooleanComponentProperty, type BooleanParam, type BridgeConnectOptions, type ClassComponentProperty, type ColorScheme, type ComponentPatch, type ComponentProperty, type ComponentPropertyBase, type ConditionComponentProperty, type ConnectOptions, type CopyObject, type CustomField, type CustomFieldAssignment, type CustomFieldGroup, type CustomFieldType, ETCH_API_VERSION, type Etch, type EtchAiApi, EtchApiError, type EtchApiErrorCode, type EtchBlockCommon, type EtchBlockContext, type EtchBlockJson, type EtchBlockOptions, type EtchBlockScript, type EtchBlockType, type EtchBlockTypeName, type EtchBlocksApi, type EtchBridgeConnection, type EtchComponentBlockJson, type EtchComponentsApi, type EtchConditionBlockJson, type EtchDynamicElementBlockJson, type EtchDynamicImageBlockJson, type EtchElementBlockJson, type EtchFieldsApi, type EtchHistoryApi, type EtchHtmlAttributes, type EtchLoop, type EtchLoopBlockJson, type EtchLoopConfig, type EtchLoopObj, type EtchLoopsApi, type EtchNavigationApi, type EtchPassthroughBlockJson, type EtchPostContentBlockJson, type EtchRawHtmlBlockJson, type EtchSkillsApi, type EtchSlotContentBlockJson, type EtchSlotPlaceholderBlockJson, type EtchStylesApi, type EtchStylesheetsApi, type EtchSvgBlockJson, type EtchTextBlockJson, type EtchUiApi, type ExternalAiState, type FindBlocksPredicate, type GroupComponentProperty, type GutenbergBlock, type LoopParamRef, type MetaQueryItem, type NavigationPlace, type NumberComponentProperty, type NumericParam, type ObjectComponentProperty, type PostCustomFieldGroupEntry, type PostCustomFieldValueEntry, type PostCustomFieldValueResponse, type PostCustomFieldValuesResponse, type PostSummary, type PublicBlockJson, type PublicComponentJson, type PublicComponentSummary, type RepeaterComponentProperty, type ResolvedCustomField, type SelectOptionsString, type SkillDetail, type SkillSummary, type StringComponentProperty, type StyleListFilter, type StylePatch, type StyleSelectorType, type StyleSummary, type StylesheetInput, type StylesheetPatch, type StylesheetSummary, type StylesheetType, type TaxQueryItem, type TemplateSummary, type WpQueryArgs, type WpTermsArgs, type WpUsersArgs, getEtch, isEtchApiError, isEtchAvailable };

package/dist/index.d.ts

@@ -1048,7 +1048,7 @@ interface EtchComponentsApi {
  * - `loop-manager` — the loop manager
  * - `asset-manager` — the asset (media) library
  */
-type NavigationPlace = 'builder' | 'templates' | 'style-manager' | 'content-hub' | 'loop-manager' | 'asset-manager';
+type NavigationPlace = 'builder' | 'templates' | 'style-manager' | 'content-hub' | 'loop-manager' | 'data-manager' | 'asset-manager';
 /** Lightweight post entry returned by `navigation.listPostsAsync()`. */
 interface PostSummary {
     /** Post id. */
@@ -1290,6 +1290,38 @@ interface EtchSkillsApi {
     getReference(name: string, file: string): string | undefined;
 }
 
+/**
+ * External AI agent presence (`etch.ai`).
+ *
+ * Lets a connected agent advertise that it is working in this tab and what
+ * phase it is in, driving the builder's presence overlay. Intended to be set
+ * from a bridge connection (see `connectAs`), where pushed scripts reach only
+ * `window.etch` — so this is the supported way to toggle the overlay.
+ */
+/**
+ * The phase an external agent reports.
+ *
+ * - `idle` — agent not present; the presence overlay is hidden.
+ * - `working` — agent is actively editing the canvas.
+ * - `waiting` — agent is waiting on the human (input, approval).
+ * - `thinking` — agent is reasoning before it acts.
+ */
+type ExternalAiState = 'idle' | 'working' | 'waiting' | 'thinking';
+/** Advertise external AI agent presence and phase to the builder. */
+interface EtchAiApi {
+    /** The agent's current presence phase (`idle` when not present). */
+    getState(): ExternalAiState;
+    /**
+     * Set the agent's presence phase. Any non-`idle` value shows the presence
+     * overlay; `idle` hides it.
+     *
+     * @throws `EtchApiError` (`INVALID_ARGUMENT`) for an unknown state.
+     */
+    setState(state: ExternalAiState): void;
+    /** Clear presence — shorthand for `setState('idle')`. */
+    hide(): void;
+}
+
 /**
  * Builder chrome controls (`etch.ui`) and undo/redo (`etch.history`).
  */
@@ -1425,6 +1457,8 @@ interface Etch {
     history: EtchHistoryApi;
     /** Bundled, read-only authoring skills (guides + reference subskills). */
     skills: EtchSkillsApi;
+    /** External AI agent presence: advertise that an agent is working here. */
+    ai: EtchAiApi;
     /** Persist everything (blocks, loops, styles, UI). */
     saveAsync(): Promise<void>;
     /**
@@ -1520,4 +1554,4 @@ declare function isEtchApiError(value: unknown): value is EtchApiError;
  */
 declare const ETCH_API_VERSION = "0.x";
 
-export { type ArrayComponentProperty, type BlockLoopBinding, type BlockPatch, type BooleanComponentProperty, type BooleanParam, type BridgeConnectOptions, type ClassComponentProperty, type ColorScheme, type ComponentPatch, type ComponentProperty, type ComponentPropertyBase, type ConditionComponentProperty, type ConnectOptions, type CopyObject, type CustomField, type CustomFieldAssignment, type CustomFieldGroup, type CustomFieldType, ETCH_API_VERSION, type Etch, EtchApiError, type EtchApiErrorCode, type EtchBlockCommon, type EtchBlockContext, type EtchBlockJson, type EtchBlockOptions, type EtchBlockScript, type EtchBlockType, type EtchBlockTypeName, type EtchBlocksApi, type EtchBridgeConnection, type EtchComponentBlockJson, type EtchComponentsApi, type EtchConditionBlockJson, type EtchDynamicElementBlockJson, type EtchDynamicImageBlockJson, type EtchElementBlockJson, type EtchFieldsApi, type EtchHistoryApi, type EtchHtmlAttributes, type EtchLoop, type EtchLoopBlockJson, type EtchLoopConfig, type EtchLoopObj, type EtchLoopsApi, type EtchNavigationApi, type EtchPassthroughBlockJson, type EtchPostContentBlockJson, type EtchRawHtmlBlockJson, type EtchSkillsApi, type EtchSlotContentBlockJson, type EtchSlotPlaceholderBlockJson, type EtchStylesApi, type EtchStylesheetsApi, type EtchSvgBlockJson, type EtchTextBlockJson, type EtchUiApi, type FindBlocksPredicate, type GroupComponentProperty, type GutenbergBlock, type LoopParamRef, type MetaQueryItem, type NavigationPlace, type NumberComponentProperty, type NumericParam, type ObjectComponentProperty, type PostCustomFieldGroupEntry, type PostCustomFieldValueEntry, type PostCustomFieldValueResponse, type PostCustomFieldValuesResponse, type PostSummary, type PublicBlockJson, type PublicComponentJson, type PublicComponentSummary, type RepeaterComponentProperty, type ResolvedCustomField, type SelectOptionsString, type SkillDetail, type SkillSummary, type StringComponentProperty, type StyleListFilter, type StylePatch, type StyleSelectorType, type StyleSummary, type StylesheetInput, type StylesheetPatch, type StylesheetSummary, type StylesheetType, type TaxQueryItem, type TemplateSummary, type WpQueryArgs, type WpTermsArgs, type WpUsersArgs, getEtch, isEtchApiError, isEtchAvailable };
+export { type ArrayComponentProperty, type BlockLoopBinding, type BlockPatch, type BooleanComponentProperty, type BooleanParam, type BridgeConnectOptions, type ClassComponentProperty, type ColorScheme, type ComponentPatch, type ComponentProperty, type ComponentPropertyBase, type ConditionComponentProperty, type ConnectOptions, type CopyObject, type CustomField, type CustomFieldAssignment, type CustomFieldGroup, type CustomFieldType, ETCH_API_VERSION, type Etch, type EtchAiApi, EtchApiError, type EtchApiErrorCode, type EtchBlockCommon, type EtchBlockContext, type EtchBlockJson, type EtchBlockOptions, type EtchBlockScript, type EtchBlockType, type EtchBlockTypeName, type EtchBlocksApi, type EtchBridgeConnection, type EtchComponentBlockJson, type EtchComponentsApi, type EtchConditionBlockJson, type EtchDynamicElementBlockJson, type EtchDynamicImageBlockJson, type EtchElementBlockJson, type EtchFieldsApi, type EtchHistoryApi, type EtchHtmlAttributes, type EtchLoop, type EtchLoopBlockJson, type EtchLoopConfig, type EtchLoopObj, type EtchLoopsApi, type EtchNavigationApi, type EtchPassthroughBlockJson, type EtchPostContentBlockJson, type EtchRawHtmlBlockJson, type EtchSkillsApi, type EtchSlotContentBlockJson, type EtchSlotPlaceholderBlockJson, type EtchStylesApi, type EtchStylesheetsApi, type EtchSvgBlockJson, type EtchTextBlockJson, type EtchUiApi, type ExternalAiState, type FindBlocksPredicate, type GroupComponentProperty, type GutenbergBlock, type LoopParamRef, type MetaQueryItem, type NavigationPlace, type NumberComponentProperty, type NumericParam, type ObjectComponentProperty, type PostCustomFieldGroupEntry, type PostCustomFieldValueEntry, type PostCustomFieldValueResponse, type PostCustomFieldValuesResponse, type PostSummary, type PublicBlockJson, type PublicComponentJson, type PublicComponentSummary, type RepeaterComponentProperty, type ResolvedCustomField, type SelectOptionsString, type SkillDetail, type SkillSummary, type StringComponentProperty, type StyleListFilter, type StylePatch, type StyleSelectorType, type StyleSummary, type StylesheetInput, type StylesheetPatch, type StylesheetSummary, type StylesheetType, type TaxQueryItem, type TemplateSummary, type WpQueryArgs, type WpTermsArgs, type WpUsersArgs, getEtch, isEtchApiError, isEtchAvailable };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@digital-gravy/etch-public-api",
-	"version": "0.8.0",
+	"version": "0.8.2",
 	"description": "MIT-licensed typed client and contract for the Etch builder scripting API (window.etch). Etch itself is a separate proprietary product governed by its own commercial terms.",
 	"license": "MIT",
 	"repository": {