@pushwoosh/rpc-gateway-ai-assistant 0.1.136 → 0.1.137

package/data.js

@@ -8,7 +8,8 @@ export const data = {
             "DOCUMENT_BLOCK_TYPE_CARD",
             "DOCUMENT_BLOCK_TYPE_COLUMNS",
             "DOCUMENT_BLOCK_TYPE_CONTENT",
-            "DOCUMENT_BLOCK_TYPE_GROUP"
+            "DOCUMENT_BLOCK_TYPE_GROUP",
+            "DOCUMENT_BLOCK_TYPE_PLACEHOLDER"
         ]
     },
     "pushwoosh.aibuilder.v1.GroupDirection": {
@@ -461,6 +462,15 @@ export const data = {
             }
         }
     },
+    "pushwoosh.aibuilder.v1.Placeholder": {
+        "type": "I",
+        "fields": {
+            "prompt": {
+                "type": "string",
+                "optional": true
+            }
+        }
+    },
     "pushwoosh.aibuilder.v1.AiBuilderBlock": {
         "type": "I",
         "fields": {
@@ -479,6 +489,9 @@ export const data = {
             "group": {
                 "type": "pushwoosh.aibuilder.v1.AiBuilderGroup"
             },
+            "placeholder": {
+                "type": "pushwoosh.aibuilder.v1.Placeholder"
+            },
             "styles": {
                 "type": "pushwoosh.aibuilder.v1.BlockStyles",
                 "optional": true
@@ -493,7 +506,8 @@ export const data = {
                     "card",
                     "columns",
                     "content",
-                    "group"
+                    "group",
+                    "placeholder"
                 ]
             }
         }
@@ -636,7 +650,8 @@ export const data = {
             "AI_GEN_BLOCK_TYPE_HINT_CARD",
             "AI_GEN_BLOCK_TYPE_HINT_COLUMNS",
             "AI_GEN_BLOCK_TYPE_HINT_CONTENT",
-            "AI_GEN_BLOCK_TYPE_HINT_GROUP"
+            "AI_GEN_BLOCK_TYPE_HINT_GROUP",
+            "AI_GEN_BLOCK_TYPE_HINT_PLACEHOLDER"
         ]
     },
     "pushwoosh.aigen.v1.AiGenMode": {
@@ -705,10 +720,6 @@ export const data = {
                 "type": "string",
                 "array": true
             },
-            "afterPath": {
-                "type": "string",
-                "array": true
-            },
             "typeHint": {
                 "type": "pushwoosh.aigen.v1.AiGenBlockTypeHint"
             },
@@ -757,10 +768,6 @@ export const data = {
             "prompt": {
                 "type": "string"
             },
-            "afterPath": {
-                "type": "string",
-                "array": true
-            },
             "parentId": {
                 "type": "string"
             }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@pushwoosh/rpc-gateway-ai-assistant",
-    "version": "0.1.136",
+    "version": "0.1.137",
     "description": "AI Assistant api gateway HTTP API Types and Data",
     "main": "index.js",
     "module": "index.js",

package/pushwoosh_aibuilder_v1.d.ts

@@ -8,16 +8,39 @@ export type DocumentBlockType = 'DOCUMENT_BLOCK_TYPE_UNSPECIFIED' | 'DOCUMENT_BL
  * Structural stack container — a "group" block in the kind registry.
  * Wire-shape is AiBuilderBlock.group. Allowed in EMAIL and WEB_POPUP.
  */
- | 'DOCUMENT_BLOCK_TYPE_GROUP';
+ | 'DOCUMENT_BLOCK_TYPE_GROUP'
+/**
+ * Client-created empty slot meant to be materialised into a real
+ * block by the AI on a follow-up edit. Wire-shape is
+ * AiBuilderBlock.placeholder.
+ */
+ | 'DOCUMENT_BLOCK_TYPE_PLACEHOLDER';
 /**
  * GroupDirection picks which axis an AiBuilderGroup lays its children
- * along. The planner emits UNSPECIFIED (proto zero) on freshly
- * generated groups — clients should treat UNSPECIFIED and VERTICAL
- * identically as a vertical stack. HORIZONTAL is only ever set by the
- * client (post-generation) when it wants a side-by-side layout; the
- * backend preserves the client's choice across edits. The enum lives
- * at file scope so the same shape is shared between the document
- * model and the AiGen wire types.
+ * along.
+ *
+ * Wire contract:
+ * UNSPECIFIED — "inherit / use the document default" (currently
+ * rendered as a vertical stack). Render-time fallback
+ * only; NOT wire-equivalent to VERTICAL — downstream
+ * consumers that diff documents see them as different
+ * values.
+ * VERTICAL    — explicit vertical stack. Reserved for an "Explicit
+ * override" UX where the client wants to pin the value
+ * against a future default change. The backend never
+ * emits this on freshly generated groups; that case
+ * stays UNSPECIFIED.
+ * HORIZONTAL  — explicit side-by-side layout. Emitted only by the
+ * client (the LLM never picks a direction).
+ *
+ * Recommended client flow: send UNSPECIFIED for the default and switch
+ * to a concrete value only when the user explicitly chose a non-default
+ * direction; revert to UNSPECIFIED when the user resets it.
+ *
+ * Server contract: the backend preserves whatever value the client
+ * sent across edits — direction is in the client-managed set on
+ * AiBuilderGroup. The enum lives at file scope so the same shape is
+ * shared between the document model and the AiGen wire types.
  */
 export type GroupDirection = 'GROUP_DIRECTION_UNSPECIFIED' | 'GROUP_DIRECTION_VERTICAL' | 'GROUP_DIRECTION_HORIZONTAL';
 export type CardLayout = 'CARD_LAYOUT_UNSPECIFIED' | 'CARD_LAYOUT_RIGHT' | 'CARD_LAYOUT_LEFT' | 'CARD_LAYOUT_TOP' | 'CARD_LAYOUT_NO' | 'CARD_LAYOUT_BACKGROUND';
@@ -26,10 +49,22 @@ export type ButtonGroupAlign = 'BUTTON_GROUP_ALIGN_UNSPECIFIED' | 'BUTTON_GROUP_
  * GroupAlign controls alignment of an AiBuilderGroup's children along
  * the perpendicular axis (for direction=VERTICAL → horizontal
  * alignment of children; for direction=HORIZONTAL → vertical
- * alignment). UNSPECIFIED is the proto zero value and clients should
- * render it as START — same client-managed pattern as GroupDirection.
- * Named in start/center/end terms (not left/right) because the
- * concrete axis depends on direction.
+ * alignment). Named in start/center/end terms (not left/right)
+ * because the concrete axis depends on direction.
+ *
+ * Wire contract:
+ * UNSPECIFIED — "inherit / use the document default" (currently
+ * rendered as START). Render-time fallback only; NOT
+ * wire-equivalent to START.
+ * START       — explicit start alignment. Reserved for the same
+ * "Explicit override" UX as GroupDirection.VERTICAL.
+ * The backend never emits this on freshly generated
+ * groups; that case stays UNSPECIFIED.
+ * CENTER/END  — explicit center / end alignment.
+ *
+ * Recommended client flow: same as GroupDirection — UNSPECIFIED for the
+ * default, a concrete value only when the user explicitly chose one,
+ * back to UNSPECIFIED on reset.
  */
 export type GroupAlign = 'GROUP_ALIGN_UNSPECIFIED' | 'GROUP_ALIGN_START' | 'GROUP_ALIGN_CENTER' | 'GROUP_ALIGN_END';
 /**
@@ -261,13 +296,30 @@ export type AiBuilderColumn = {
  * this block's id; the group itself has no copy and no image slot.
  * Allowed in EMAIL and WEB_POPUP.
  *
- * direction / align / margin / padding / gap are client-managed: the
- * LLM never sees them, the backend preserves them across edits. On
- * freshly generated groups the backend emits proto-zero values
- * (direction = UNSPECIFIED, align = UNSPECIFIED, optional fields
- * unset); clients are expected to render UNSPECIFIED direction as a
- * vertical stack, UNSPECIFIED align as START, and set non-default
- * values themselves when needed.
+ * Wire contract:
+ * - All fields (direction, align, margin, padding, gap) are
+ * client-managed. The backend preserves whatever the client sent
+ * verbatim across edits and emits proto-zero / unset for them on
+ * freshly generated groups.
+ * - UNSPECIFIED enums and unset optionals mean "inherit / use the
+ * document default" — see GroupDirection / GroupAlign for the
+ * render-time fallback. UNSPECIFIED is NOT wire-equivalent to the
+ * concrete default value; downstream consumers that diff documents
+ * see them as different states.
+ * - The LLM never sees these fields and never sets them; they round-
+ * trip through the backend untouched.
+ *
+ * Recommended client flow:
+ * - Default rendering (vertical stack, START alignment, document
+ * defaults for margin/padding/gap): leave UNSPECIFIED / unset.
+ * Don't normalise to a concrete enum just because that's what the
+ * user currently sees.
+ * - Send a concrete enum (VERTICAL, START, HORIZONTAL, CENTER, END)
+ * only when the user explicitly chose a non-default value, or when
+ * the user wants to pin the value against a future default change.
+ * - On reset, write back UNSPECIFIED / unset rather than the concrete
+ * default — that way the document still diffs cleanly against a
+ * freshly generated group.
  */
 export type AiBuilderGroup = {
     direction: GroupDirection;
@@ -286,6 +338,23 @@ export type AiBuilderGroup = {
      */
     align: GroupAlign;
 };
+/**
+ * Placeholder is a client-created empty slot meant to be replaced by
+ * the AI on a follow-up edit. The frontend builder inserts a
+ * Placeholder when the user adds a new block to the canvas without
+ * yet describing what it should be; on the next AI-edit the model
+ * replaces it with a real block kind (card / columns / content /
+ * group). Carries no rendered content of its own.
+ */
+export type Placeholder = {
+    /**
+     * Optional user-supplied hint about what the slot should become,
+     * e.g. "CTA section with a button" or "product card". The AI uses
+     * it as an instruction on the next edit; empty string lets the
+     * model pick freely from surrounding context.
+     */
+    prompt?: string;
+};
 export type AiBuilderBlock_block_card = {
     type: 'card';
     data: AiBuilderCard;
@@ -302,7 +371,11 @@ export type AiBuilderBlock_block_group = {
     type: 'group';
     data: AiBuilderGroup;
 };
-export type AiBuilderBlock_block = AiBuilderBlock_block_card | AiBuilderBlock_block_columns | AiBuilderBlock_block_content | AiBuilderBlock_block_group;
+export type AiBuilderBlock_block_placeholder = {
+    type: 'placeholder';
+    data: Placeholder;
+};
+export type AiBuilderBlock_block = AiBuilderBlock_block_card | AiBuilderBlock_block_columns | AiBuilderBlock_block_content | AiBuilderBlock_block_group | AiBuilderBlock_block_placeholder;
 export type AiBuilderBlock = {
     id: string;
     styles?: BlockStyles;

package/pushwoosh_aigen_v1.d.ts

@@ -36,7 +36,15 @@ export type AiGenBlockTypeHint = 'AI_GEN_BLOCK_TYPE_HINT_UNSPECIFIED' | 'AI_GEN_
  * skipped — groups carry no copy, just children referenced via
  * parent_id. Allowed in EMAIL and WEB_POPUP.
  */
- | 'AI_GEN_BLOCK_TYPE_HINT_GROUP';
+ | 'AI_GEN_BLOCK_TYPE_HINT_GROUP'
+/**
+ * Client-created empty slot meant to be materialised into a real
+ * block by the AI on a follow-up edit. The block generator is
+ * skipped — the planner emits a `replace` for each placeholder it
+ * sees in <current_document> and the pipeline retargets the replace
+ * to a real content kind before invoking the block generator.
+ */
+ | 'AI_GEN_BLOCK_TYPE_HINT_PLACEHOLDER';
 /**
  * AiGenMode selects the document-domain profile the generation pipeline
  * runs under: which block kinds are allowed, which Meta fields are
@@ -101,6 +109,13 @@ export type AiGenRequest = {
  * single-entry structure_diff echoing these fields so the UI can match an
  * optimistically-rendered placeholder, followed by the block_delta and any
  * image_deltas for the new block.
+ *
+ * Positioning: the new block lands at the end of the target parent
+ * scope (end of the page when parent_id is empty, end of that
+ * container's children otherwise). Fine-grained positioning is the
+ * client's job: drop an empty `Placeholder` block on the canvas where
+ * you want it and ask the AI to materialise it on the next edit (see
+ * the placeholder flow in the document).
  */
 export type AiGenAddBlock = {
     /**
@@ -109,13 +124,6 @@ export type AiGenAddBlock = {
      * block_id must not collide with any existing block id in that page.
      */
     blockPath: string[];
-    /**
-     * Path of the block this one should be inserted after:
-     * `[page_id, existing_block_id]`. Must share `page_id` with
-     * `block_path`. Empty = insert at the beginning of the page referenced
-     * by `block_path[0]`.
-     */
-    afterPath: string[];
     /**
      * Optional. UNSPECIFIED = the block generator decides card vs columns
      * based on the prompt and surrounding blocks.
@@ -152,17 +160,26 @@ export type AiGenStructureAdd = {
     typeHint: AiGenBlockTypeHint;
     prompt: string;
     /**
-     * Path of the block this one should be inserted after. Empty → insert
-     * at the beginning of the page referenced by `block_path[0]`. May
-     * reference an existing block path or another add.block_path from the
-     * same diff (must share `page_id`).
-     */
-    afterPath: string[];
-    /**
-     * Id of the parent container block. Empty string = top-level. May
-     * reference an existing container or another add from the same diff.
-     * The new block becomes a child of that container (still a sibling in
-     * page.blocks; the tree is rebuilt by group-by-parent on the client).
+     * Id of the parent container block.
+     *
+     * Wire contract:
+     * - Empty string = top-level (the add lands at the end of the
+     * page).
+     * - Non-empty must resolve to a container block: either an
+     * existing one in `document`, or an add appearing earlier in
+     * AiGenStructureDiff.add. Back-references only — the parent
+     * must be either already in the document or appear before this
+     * entry in the same `add` list. Forward-references are rejected
+     * by the server (parent_id reset to empty with a warning in the
+     * logs).
+     * - The add lands at the end of its parent scope; fine-grained
+     * positioning is done by the client via placeholder slots
+     * before the edit (see Placeholder in ai_builder_document.proto).
+     *
+     * Recommended client flow: process AiGenStructureDiff.add entries
+     * left-to-right; each entry's parent_id is guaranteed resolvable
+     * against the entries the client has already processed plus the
+     * pre-edit document.
      */
     parentId: string;
 };
@@ -181,6 +198,13 @@ export type AiGenStructureReplace = {
 /**
  * Emitted once for edit (when the planner ran), before any block_delta.
  * Not emitted on the block_path bypass path.
+ *
+ * Wire contract: the `add` list is ordered. Each entry's parent_id may
+ * reference an earlier entry in the same list (back-reference); the
+ * server rejects forward-references on sanitisation. Clients should
+ * apply `add` entries left-to-right so a pending parent is in place
+ * before any of its children. `remove` and `replace` are commutative
+ * and may be applied in any order.
  */
 export type AiGenStructureDiff = {
     add: AiGenStructureAdd[];