Components DSL

The Propal components DSL is a typed JSON grammar that produces valid TipTap editor content without exposing the raw editor JSON. Agents author sections by composing typed blocks; the server validates against Zod schemas, applies structural rules, and assembles the final document atomically.

Mental model

A proposal is a suite of sections. Each visual block of the document (intro, goals, pricing, testimonials…) is wrapped in a section. Anything outside a section uses page-level styling. Structural rules (enforced by Zod + a runtime validator with explicit error messages):

The root of any tree submitted via the DSL is a section or section[].
A section cannot contain another section — flat hierarchy at the root.
Inside a section, only blocks are allowed: paragraph, heading, columns, cards, mini_table, gallery, etc.
columns.cols must equal columns.length.
image / icon / video are placeholders — no src accepted.
embed is the only block that takes an external URL (with provider-host allowlist).
Card-grouped components (testimonial_cards, process_cards, …) always assemble to a columns block with one card per column. Proprietary card containers are never produced.

Schema discovery

Agents use two tools to learn the grammar at runtime:

list_propal_components

Returns the full catalog with descriptions, structural rules, limits, and a compact example per component.

get_propal_component_schema

Returns the detailed Zod-derived schema for a single component ({ component_type: 'section' | 'columns' | ... }).

The descriptions in those tools are the source of truth — this page mirrors them but the live tool always wins.

Layout

Component	Props	Notes
`section`	`theme?`, `section_style?`, `background_image?`, `badge?`, `badge_color?`, `title?`, `title_level?`, `description?`, `children: Block[]`	Root container. `theme` is legacy; prefer `section_style` + a proposal theme. See theming.
`columns`	`cols: '2'\|'3'\|'4'`, `column_widths?`, `columns: Block[][]`	One sub-tree per column. `columns.length` must equal `cols`.
`spacer`	`height?`	Vertical space.

Basic blocks

Component	Props
`paragraph`	`text`, `align?`
`heading`	`level: 1\|2\|3`, `text`, `align?`
`bullet_list`	`items: string[]`
`divider`	(no props — renders `horizontalRule`)
`badge`	`text`, `color`, `size`, `rounded`
`stars`	`count`, `color`
`profile`	`name`, `title` (avatar is a placeholder)

Media

Placeholders only — no external URLs:

Component	Maps to
`image`	`imageUpload` (`componentUpload: 'block'`)
`icon`	`imageUpload` (`componentUpload: 'icon'`)
`video`	`videoUpload`

The user uploads the actual asset in the editor after the agent has built the structure. With URL:

{
  type: 'embed',
  provider: 'youtube' | 'loom' | 'vimeo' | 'figma' | 'drive' | 'generic',
  src: string, // HTTPS, validated against the provider's host allowlist
  height?: string,
}

Allowed hosts:

Provider	Hosts
`youtube`	`youtube.com`, `youtu.be`
`loom`	`loom.com`
`vimeo`	`vimeo.com`, `player.vimeo.com`
`figma`	`figma.com`
`drive`	`drive.google.com`, `docs.google.com`
`generic`	any HTTPS URL

Business / rich blocks

Component	Props
`product_table`	(proprietary container preserved — see notes)
`mini_table`	`header_service?`, `header_duration?`, `rows: { service, duration }[]`
`gallery`	`cols`, `item_count` (placeholders)

Cards

For each card type the DSL exposes both a standalone form and a grouped form. Grouped cards always assemble to a columns block with one card per column — proprietary containers (testimonialsContainer, accordionContainer, etc.) are deprecated and never produced.

Standalone	Grouped	Items contain
`numbered_callout`	`numbered_callouts`	`{ number, title, description, color }`
`process_card`	`process_cards`	`{ number, title, description, color }`
`process_card_with_image`	(use `columns` + image)	adds an image placeholder
`stat_card`	`stat_cards`	`{ value, label }`
`testimonial_card`	`testimonial_cards`	`{ quote, name, title, stars, star_color }`
`team_card`	`team_cards`	`{ name, role, bio }`
`pricing_card`	`pricing_cards`	`{ name, description, price, features, button_text? }`
`case_study_card`	`case_study_cards`	`{ title, description, badges?, social_proof_, link_, orientation }`
`question`	`questions`	`{ question, answer, open? }`

Grouped cards take a cols prop matching the visual layout ('1'–'4').

Section theming

Three accepted forms for section.section_style, in order of preference:

'default' — “Page” : the section inherits page-level colors. No section ambience.
Named slot id (recommended) — e.g. 'soft', 'deep'. Resolved server-side via theme.section_styles[].id. Survives reordering of the theme’s slots.
Positional index — '1', '2', '3', … 1-indexed reference into the theme’s section_styles[] array. In stock themes: '1' = Default, '2' = Highlight, '3' = Contrast.

The legacy section.theme (white / gray / black / outlined) is inert when a custom theme is applied to the proposal — it only controls the legacy bodyTheme fallback on themeless proposals. Prefer section_style. See theming for the full picture.

Background image

{
  type: 'section',
  // ...
  background_image: {
    media_id: string,         // UUID of an asset uploaded via media_service
    overlay?: boolean,
    overlay_opacity?: number, // 0-100
    size?: 'cover' | 'contain' | 'auto' | 'custom',
    size_width?: string,      // when size === 'custom'
    size_height?: string,
    position_x?: string,      // CSS values (e.g. '50%', 'top')
    position_y?: string,
    repeat?: 'no-repeat' | 'repeat' | 'repeat-x' | 'repeat-y',
    attachment?: 'scroll' | 'fixed',
  },
}

media_id must reference an asset that already exists in the org’s media library. The server resolves the URL at assemble time.

Limits

Limit	Value
`MAX_SECTIONS` per append	10
`MAX_DEPTH` (columns nesting)	6
`MAX_NODES` per tree	200
`MAX_BLOCKS_PER_SECTION`	50
`MAX_BLOCKS_PER_COLUMN`	30
`MAX_COLUMNS`	4

These are exposed in the limits field of list_propal_components.

End-to-end example

Build a 2-section proposal with a hero and three numbered callouts:

{
  "tree": [
    {
      "type": "section",
      "section_style": "default",
      "badge": "Welcome",
      "title": "Q2 Redesign Proposal",
      "description": "A complete refresh of the marketing site.",
      "children": [
        { "type": "divider" },
        {
          "type": "paragraph",
          "text": "We've reviewed your current site and identified three priorities."
        }
      ]
    },
    {
      "type": "section",
      "section_style": "highlight",
      "title": "Goals",
      "children": [
        {
          "type": "numbered_callouts",
          "cols": "3",
          "items": [
            { "number": "01", "title": "Faster", "description": "Cut TTI by 50%.", "color": "blue" },
            { "number": "02", "title": "Cleaner", "description": "Refresh visuals.", "color": "green" },
            { "number": "03", "title": "Convert", "description": "Better CTA placement.", "color": "purple" }
          ]
        }
      ]
    }
  ]
}

Send via:

append_propal_component_tree_to_proposal
  proposal_id: "<uuid>"
  tree: <above>

The server validates the tree, resolves named refs (here "highlight" if a matching slot id exists), assembles the TipTap nodes, and atomically appends them with optimistic concurrency control.

Round-trip stability

Reading a proposal via get_proposal_tree returns the same DSL shape you wrote — assembler defaults are stripped on read so the round-trip is a fixed point. Caveats:

Node types not in the DSL come back as { type: 'unknown', tiptap_type, text_preview, child_count }.
Old proposals containing legacy *Container nodes are flattened to the grouped DSL form (testimonial_cards, questions, …) on read only — they are never written back in that form.
Headings with level > 3 come back as unknown (the DSL only supports 1-3).

Overview

Reference

Components DSL

Mental model

Schema discovery

list_propal_components

get_propal_component_schema

Layout

Basic blocks

Media

Business / rich blocks

Cards

Section theming

Background image

Limits

End-to-end example

Round-trip stability

​Mental model

​Schema discovery

list_propal_components

get_propal_component_schema

​Layout

​Basic blocks

​Media

​Business / rich blocks

​Cards

​Section theming

​Background image

​Limits

​End-to-end example

​Round-trip stability

Mental model

Schema discovery

Layout

Basic blocks

Media

Business / rich blocks

Cards

Section theming

Background image

Limits

End-to-end example

Round-trip stability