WCP Portability Protocol

WCPP defines how WCP-based dashboard setups are bundled, transported, and reconstructed on a different machine. Where WCP handles runtime communication between widget and host, WCPP handles the packaging and distribution of those widget setups.

What problem WCPP solves

A WCP dashboard orchestration is a self-contained snapshot: pinned widgets, layout, theme references, and configuration. Moving that setup from one machine to another requires moving not just the layout but also the widget containers that power it, and the themes that style it — none of which are in the layout file itself.

WCPP solves this by defining a family of portable file formats that bundle all of these concerns together. A .wcpa application package, for example, includes the orchestration layout, a snapshot of its theme, and a widget inventory with the Docker image details needed to provision the containers on any WCPP-conformant machine.

Relationship to WCP

WCPP depends on WCP 2.0.0: it references the WCP container block, widget manifests (/widget/wcp), and the Bonjour service. WCP does not depend on WCPP — they are independent, complementary layers in the same ecosystem.

Both protocols are part of the broader WCP ecosystem, designed and maintained by Penrith Beacon as open standards for local-first dashboard widget communication and distribution.

The .wcp* Format Family

All four WCPP formats are ZIP archives. Each contains a manifest.json and a README.md at the archive root. Format-specific content varies.

Choosing the right format:

• Use .wcpo to share one or more orchestration layouts without themes.
• Use .wcpt to share a theme collection independently of any orchestration.
• Use .wcpx to distribute a complete WCP setup — any combination of applications, orchestrations, and themes bundled together. The recipient imports everything in one operation.
• Use .wcpa for distributing a complete, launchable application — layout, theme, and widget container details bundled in one file.

.wcpo — WCP Orchestration Package

A .wcpo file is a ZIP archive containing one or more orchestration snapshots. It is the base format for sharing dashboard layouts.

Archive structure

manifest.json fields

Notes

.wcpt — WCP Theme Package

A .wcpt file is a ZIP archive containing a named collection of themes. Themes are self-contained sets of CSS custom property values that define the visual appearance of a WCP dashboard.

Archive structure

manifest.json fields

docs index structure

When formatVersion is "1.1", the docs field in manifest.json is an object with a collection entry and a themes array. All paths use the wcp-theme- prefix convention:

// manifest.json — docs index (excerpt)
"docs": {
  "collection": {
    "md":   "docs/wcp-theme-collection-penrith-beacon-default-1a71e05b-424f-4dd2-9ba6-072fc4ada57d.md",
    "html": "docs/wcp-theme-collection-penrith-beacon-default-1a71e05b-424f-4dd2-9ba6-072fc4ada57d.html"
  },
  "themes": [
    {
      "uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "Penrith Beacon WCP Light",
      "md":   "docs/wcp-theme-penrith-beacon-wcp-light-b2c3d4e5-f6a7-8901-bcde-f12345678901.md",
      "html": "docs/wcp-theme-penrith-beacon-wcp-light-b2c3d4e5-f6a7-8901-bcde-f12345678901.html"
    }
    // ... one entry per theme
  ]
}

For single-theme .wcpt files, the docs field is a flat object (no collection key):

"docs": {
  "md":   "docs/wcp-theme-penrith-beacon-wcp-light-b2c3d4e5-f6a7-8901-bcde-f12345678901.md",
  "html": "docs/wcp-theme-penrith-beacon-wcp-light-b2c3d4e5-f6a7-8901-bcde-f12345678901.html"
}

themes.json schema

themes.json contains a JSON array of theme objects.

Example — Penrith Beacon WCP Light (all 81 tokens)

// themes.json (single theme object — Penrith Beacon WCP Light, canonical default)
{
  "id":          "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "uuid":        "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "name":        "Penrith Beacon WCP Light",
  "variant":     "light",
  "wcpVersion":  "2.2.1",
  "description": "The canonical default light theme for the Penrith Beacon® WCP Dashboard.",
  "conformance": "WCAG 2.2:AA",
  "collectionId":"1a71e05b-424f-4dd2-9ba6-072fc4ada57d",
  "author":      "Anthony Harrison",
  "authorEmail": "widgets@penrithbeacon.com",
  "authorUrl":   "https://harrisonofthenorth.com",
  "themeUrl":    "https://penrithbeacon.com",
  "vars": {
    // — Surfaces —
    "--wcp-color-bg":                    "#ffffff",
    "--wcp-color-surface":               "#f6f8fa",
    "--wcp-color-surface-raised":        "#eaeef2",
    "--wcp-color-surface-sunken":        "#ffffff",
    "--wcp-color-overlay":               "rgba(255,255,255,0.75)",
    // — Borders —
    "--wcp-color-border":                "#d0d7de",
    "--wcp-color-border-strong":         "rgba(31,35,40,0.25)",
    // — Text —
    "--wcp-color-text":                  "#1f2328",
    "--wcp-color-text-muted":            "#636c76",
    "--wcp-color-text-disabled":         "rgba(99,108,118,0.5)",
    "--wcp-color-text-inverse":          "#ffffff",
    "--wcp-color-link":                  "#0969da",
    // — Brand —
    "--wcp-color-primary":               "#8B6914",
    "--wcp-color-primary-dim":           "rgba(139,105,20,0.12)",
    "--wcp-color-primary-on":            "#ffffff",
    // — Status —
    "--wcp-color-success":               "#1a7f37",
    "--wcp-color-success-on":            "#ffffff",
    "--wcp-color-success-surface":       "rgba(26,127,55,0.12)",
    "--wcp-color-warning":               "#9a6700",
    "--wcp-color-warning-on":            "#ffffff",
    "--wcp-color-warning-surface":       "rgba(154,103,0,0.12)",
    "--wcp-color-danger":                "#cf222e",
    "--wcp-color-danger-on":             "#ffffff",
    "--wcp-color-danger-surface":        "rgba(207,34,46,0.12)",
    "--wcp-color-info":                  "#0969da",
    "--wcp-color-info-on":               "#ffffff",
    "--wcp-color-info-surface":          "rgba(9,105,218,0.12)",
    // — Typography —
    "--wcp-font-family":                 "-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif",
    "--wcp-font-mono":                   "ui-monospace,'Cascadia Code','Source Code Pro',Menlo,Consolas,monospace",
    "--wcp-font-size-xs":                "11px",
    "--wcp-font-size-sm":                "12px",
    "--wcp-font-size-md":                "14px",
    "--wcp-font-size-lg":                "16px",
    "--wcp-font-size-xl":                "20px",
    "--wcp-font-size-2xl":               "24px",
    "--wcp-font-size-3xl":               "32px",
    "--wcp-font-weight-normal":          "400",
    "--wcp-font-weight-medium":          "500",
    "--wcp-font-weight-semibold":        "600",
    "--wcp-font-weight-bold":            "700",
    "--wcp-line-height-tight":           "1.2",
    "--wcp-line-height-normal":          "1.5",
    "--wcp-line-height-relaxed":         "1.75",
    // — Spacing —
    "--wcp-space-1":                     "4px",
    "--wcp-space-2":                     "8px",
    "--wcp-space-3":                     "12px",
    "--wcp-space-4":                     "16px",
    "--wcp-space-5":                     "20px",
    "--wcp-space-6":                     "24px",
    "--wcp-space-7":                     "32px",
    "--wcp-space-8":                     "64px",
    // — Shape —
    "--wcp-radius-sm":                   "4px",
    "--wcp-radius-md":                   "8px",
    "--wcp-radius-lg":                   "12px",
    "--wcp-radius-xl":                   "16px",
    "--wcp-radius-round":                "9999px",
    // — Shadow —
    "--wcp-shadow-sm":                   "0 4px 8px rgba(0,0,0,.12)",
    "--wcp-shadow-md":                   "0 4px 12px rgba(0,0,0,.2)",
    "--wcp-shadow-lg":                   "0 8px 24px rgba(0,0,0,.25)",
    "--wcp-shadow-xl":                   "0 16px 40px rgba(0,0,0,.3)",
    // — Motion —
    "--wcp-motion-fast":                 "100ms",
    "--wcp-motion-normal":               "200ms",
    "--wcp-motion-slow":                 "350ms",
    "--wcp-easing-standard":             "ease",
    "--wcp-easing-out":                  "ease-out",
    "--wcp-easing-in":                   "ease-in",
    "--wcp-easing-spring":               "cubic-bezier(0.34,1.56,0.64,1)",
    // — Z-index —
    "--wcp-z-base":                      "0",
    "--wcp-z-raised":                    "10",
    "--wcp-z-dropdown":                  "1000",
    "--wcp-z-sticky":                    "1100",
    "--wcp-z-modal":                     "1200",
    "--wcp-z-toast":                     "1300",
    "--wcp-z-tooltip":                   "1400",
    // — Focus & Touch —
    "--wcp-focus-ring-width":            "2px",
    "--wcp-focus-ring-offset":           "2px",
    "--wcp-focus-ring-color":            "#8B6914",
    "--wcp-touch-target-min":            "44px",
    // — Widget —
    "--wcp-widget-bg":                   "#f6f8fa",
    "--wcp-widget-border":               "#d0d7de",
    "--wcp-widget-radius":               "8px",
    "--wcp-widget-padding":              "16px",
    "--wcp-widget-gap":                  "12px",
    "--wcp-widget-shadow":               "0 4px 8px rgba(0,0,0,.12)"
  }
}

.wcpx — WCP Distribution Envelope

A .wcpx file is a distribution bundle containing zero or more packages of each type: .wcpa application packages, .wcpo orchestration packages, and .wcpt theme packages. It is the intended format for distributing a complete WCP ecosystem setup in a single file — bundling live orchestrations, applications, and archived packages together.

All sub-packages are complete, valid archives in their own right and can be extracted and imported individually if needed.

Archive structure (formatVersion 2.0)

At least one sub-package must be present — an empty .wcpx is invalid. Any combination of sub-packages is valid: a bundle of only applications, only themes, or any mix.

manifest.json fields

contents field example

{
  "format":        "wcpx",
  "formatVersion": "2.0",
  "contents": [
    "applications/my-app-id.wcpa",
    "applications/another-app-id.wcpa",
    "orchestrations/live-export.wcpo",
    "themes/dark-collection.wcpt"
  ]
}

Import semantics

A conformant importer reads the contents array and processes each entry by its file extension — .wcpa, .wcpo, or .wcpt. All orchestrations and themes from all sub-packages are aggregated into a single conflict-resolution pass before any data is written. Widget inventories from both .wcpa and .wcpo sub-packages are combined to provide container provisioning information in the post-import checklist.

.wcpa — WCP Application Package

A .wcpa file is the richest WCPP format. It bundles a single orchestration as a distributable, launchable application — including its themes, a widget container inventory, and optionally an icon. It is the intended format for sharing complete WCP-based applications.

Archive structure

manifest.json fields

orchestration.json

The full orchestration snapshot, in the same format as a .wcpo orchestration entry. Conformant importers set application: true on the imported orchestration automatically — the flag does not need to be present in the file.

themes.json

Same schema as .wcpt themes.json — a JSON array of theme objects. Includes both explicitly exported themes and any adopted theme snapshot (see Adopted Theme Portability). Duplicate detection by id prevents the same theme appearing twice.

widgets.json

See Widget Inventory — this is the WCPP mechanism for container provisioning. The widgets.json file records Docker image information for every widget URL in the orchestration.

Widget Inventory (widgets.json)

widgets.json is present only in .wcpa files. It records Docker container information for every widget URL referenced in the orchestration, captured at export time by probing each widget's /widget/wcp endpoint.

On import, a WCPP-conformant host uses this inventory to identify which containers need to be provisioned on the receiving machine — and to show the user the exact docker pull commands needed to bring offline widgets online.

Schema

{
  "widgets": [
    {
      "url":         "http://localhost:3741",
      "name":        "WCP Radio",
      "version":     "1.0.0",
      "wcpVersion": "2.0.0",
      "components": ["radio"],
      "container": {
        "image":  "docker.io/penrithbeacon/wcp-widget-radio",
        "tag":    "latest",
        "source": { "type": "registry" }
      }
    }
  ]
}

widgets[] entry fields

Adopted Theme Portability

A theme reference (themeRefs) is a UUID pointer to a theme stored in the host dashboard's settings. This works locally, but breaks portability: if the referenced theme is deleted, or does not exist on the receiving machine, the orchestration loses its intended appearance.

WCPP solves this with the adopted theme snapshot. When a user adopts a theme for a specific orchestration, the full CSS vars object is stored directly on the orchestration as adoptedTheme:

// Inside orchestration.json
{
  "id": "my-orchestration",
  "name": "My App",
  "adoptedTheme": {
    "id":   "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "name": "Penrith Beacon WCP Light",
    "vars": {
      "--wcp-color-bg":      "#ffffff",
      "--wcp-color-surface": "#f6f8fa",
      "--wcp-color-primary": "#8B6914",
      "--wcp-color-text":    "#1f2328"
    }
  }
}

Host behaviour

• On import: if adoptedTheme.vars is present, apply those CSS custom properties when rendering the orchestration — even if the UUID does not exist in local theme settings.
• On .wcpa export: include the adopted theme in themes.json as a full theme entry alongside any other exported themes. Duplicate detection by id prevents double-inclusion.

Conformance Requirements

A WCPP-conformant host is a WCP dashboard that fully implements the import/export requirements of this specification.

A WCPP-conformant host MUST

1. 1Import all four formats — .wcpo, .wcpt, .wcpx, .wcpa
2. 2Detect conflicts on import — orchestration ID or theme UUID already exists on the host
3. 3Resolve conflicts per-item — the user chooses skip or replace before any data is written
4. 4Export all four formats
5. 5Set application: true on any orchestration imported from a .wcpa file
6. 6Apply adoptedTheme.vars when rendering an orchestration with an adopted theme snapshot
7. 7Generate fresh wcpInstanceId for all widget instruments on import — instance IDs are host-local and have no meaning across machines
8. 8Base64-encode HTML content (htmlBase64 field) on .wcpo export; decode on import

A WCPP-conformant host SHOULD

• Strip wcpInstanceId from all instruments at export time
• Probe widget URLs during .wcpa export to populate widgets.json container information
• Present docker pull commands to the user for offline widgets discovered during .wcpa import
• Require user confirmation before pulling any new Docker image (see Trust Model)

Docker Hub Distribution

WCPP uses full OCI image paths in the container.image field for unambiguous resolution across registries:

docker.io/penrithbeacon/wcp-widget-radio:latest
└──────── └────────────────────────────  └─────
registry  namespace/image               tag

• container.source.type: "registry" signals that the image is on Docker Hub or another OCI registry
• The registry hostname is the first component of the image path (docker.io for Docker Hub)
• The docker.io prefix is the conventional OCI path form for Docker Hub images

Official widget naming convention

All Penrith Beacon reference widgets follow the pattern:

docker.io/penrithbeacon/wcp-widget-{name}:{tag}

source.type values

Bonjour as Import Agent

Bonjour is a companion service to WCPP-conformant hosts. In the WCP runtime spec, Bonjour manages widget container lifecycle — starting, stopping, and health-checking containers that are already registered. In WCPP, Bonjour plays an additional role as an import agent for .wcpa packages.

Provisioning flow

1. 1User imports a .wcpa file into the host dashboard
2. 2Host parses widgets.json inventory from the package
3. 3For each widget with container.source.type: "registry": check whether a container is already running at the url
4. 4For offline widgets: prompt the user for confirmation, then execute docker pull {image}:{tag}, create and start the container
5. 5Host wires the imported orchestration to the provisioned containers
6. 6Host triggers a reload or navigation to show the new orchestration

In cases where Bonjour is not available, the host SHOULD still surface the docker pull commands to the user so they can provision the containers manually before launching the imported orchestration.

Trust Model

User confirmation

A WCPP-conformant host MUST require explicit user confirmation before pulling any Docker image from a registry for the first time (per image name). Automatic or silent pulls are not permitted.

Trust boundary

The container.image field in widgets.json is sourced from the widget's own /widget/wcp manifest at export time — it is not inserted by the exporting host. However, importers should treat all image names as untrusted input and surface them visibly to the user before any pull operation.

HTML content

Snippet instrument HTML and masthead ticker HTML are base64-encoded in all WCPP packages. This is a transport encoding for safe JSON serialisation — it is not a security boundary. Conformant hosts decode it on import. Hosts should apply their own content security policies to decoded HTML before rendering.

Future

Image signing and checksum verification are not yet specified in WCPP 1.0. These will be addressed in a future revision.

Versioning

WCPP versions independently of WCP. The WCPP version covers the overall specification. Individual format versions (formatVersion in each manifest.json) are incremented per-format when a breaking change is made to that format's schema.

WCPP specification versions

Format version history