CmdCal

Brand Packs

A brand pack bundles your organization's template file, extracted layouts, archetype mappings, and assets into a versioned unit that the render engine applies automatically during preflight and rendering.

What a Brand Pack Contains

ComponentDescription
Template fileA .pptx or .potx file that provides slide masters and layouts
Compiled tokensColor palette, font families, and spacing rules extracted from the template
LayoutsEach slide master layout with placeholder types, counts, and geometry
ArchetypesMappings from semantic slide types (e.g. title-body, kpi-grid) to specific template layouts, inferred from placeholder structure and naming
AssetsLogos, images, or other binary files associated with the brand pack

Creating a Brand Pack

Upload a template file to the brand pack API:

Terminal
curl -X POST https://api.paperjsx.com/api/v2/brand-packs \
  -H "Authorization: Bearer pj_live_YOUR_KEY" \
  -F "name=Acme Corp" \
  -F "file=@acme-template.pptx"

The server parses the template, extracts layouts and placeholder geometry, infers archetype mappings, and stores a compiled version. The response includes the brand pack ID and its first version.

Versioning

Each upload creates a new version of the brand pack. Versions are numbered sequentially. Key version fields:

  • version_number -- integer, starting at 1
  • status -- compilation state of the version
  • placeholder_coverage -- percentage of layouts with recognized placeholder types
  • missing_placeholder_count -- placeholders the engine could not classify
  • template_support_level -- how well the template maps to the V2 slide type set
  • certified -- whether this version has been manually verified

Only one version is active at a time (active_version_id on the brand pack record). Renders that reference a brandPackId without a specific brandPackVersionId use the active version.

Using Brand Packs in Renders

Pass brandPackId (and optionally brandPackVersionId) to preflight or render requests:

JSON
{
  "sourceSchema": "protocol_v2",
  "brandPackId": "bp_abc123",
  "document": {
    "version": "2.0",
    "title": "Branded Deck",
    "slides": [...]
  }
}

The engine resolves the brand pack, applies the template, maps semantic slide types to brand-specific layouts using archetype inference, and includes brand compliance findings in the quality report.

Archetype Inference

When a brand pack version is compiled, the engine analyzes each layout's placeholder families (title, body, chart, table, image) and geometry to infer which semantic slide types it can support. Inference sources include:

  • Keyword matching -- layout name contains terms like "comparison", "timeline", "chart"
  • Placeholder geometry -- grid-like arrangements suggest kpi-grid or tombstone-grid
  • Placeholder family counts -- a layout with title + body placeholders maps to title-body
  • Fallback -- layouts that do not match a specific type receive a generic mapping

Brand Compliance

When a brand pack is attached, the preflight quality report includes a brand_compliance section with findings about layout mismatches, missing placeholders, and archetype coverage gaps. These findings feed into the policyResult guardrail decision.

Next Steps