@ugames/bracket-protocol

TypeScript types for the UGames Bracket Protocol — the contract creator-built tournament bundles implement against, so any LUKSO-aware host (UGames, Common Ground, Universal Everything, third parties) can render them against any tournament state.

Spec doc (canonical, CC0): docs/conventions/bracket-protocol-v1.md

Status: v1.1 — additive; v1.0 hosts and bundles remain interoperable.

Install

npm install @ugames/bracket-protocol
# or
pnpm add @ugames/bracket-protocol

Quick start

A bracket bundle is a React component that implements the BracketProps contract:

import type { BracketProps } from "@ugames/bracket-protocol";
import React from "react";

export default function MyBracket({ tournament, canAdvance, advance }: BracketProps) {
  return (
    <div style={{ padding: 16, color: "#e5e5e5", fontFamily: "system-ui" }}>
      {tournament.matches.map((match) => (
        <button
          key={match.id}
          disabled={!canAdvance || !!match.winnerId}
          onClick={() => match.p1Id && advance(match.id, match.p1Id)}
        >
          Round {match.round}, Match {match.position}
        </button>
      ))}
    </div>
  );
}

Bundle the file as ESM, pin to IPFS, register as a templateType: "BRACKET" template through the UGames API, and any host conforming to the protocol will mount it in a sandboxed iframe and pass live tournament state in.

Sandbox guarantees

Hosts MUST render the bundle inside a sandboxed iframe. Bundles MUST follow these rules:

• Inline styles only. No Tailwind, no <link rel="stylesheet">, no global CSS.
• No window.* globals. Read everything from props.
• No 100vh / viewport-locked layouts. The host auto-grows the iframe to content height; locked dimensions clip.
• No direct fetch() to host APIs. Use the provided callbacks (advance, seed, join).
• Single React root. Default-export the component; the host owns the lifecycle.
• Default export takes BracketProps. Any other shape is treated as a zero-arg "demo mode" component with no scoring wired through.

Versioning

Per the spec, v1.x releases are additive only. Hosts ignore unknown fields; bundles ignore unknown capabilities. Adding a new write path (e.g., join in v1.1) is allowed; changing the signature of an existing one is not.

| Version | Adds | | ------- | ------------------------------------------------------------------------------------- | | 1.0 | Bundle format, render contract, tournament shape, advance + seed + refresh. | | 1.1 | + join(opts?) — sign in as the viewer's UP from inside the bundle. Optional. |

Types exported

• BracketProps — the prop contract
• Tournament, BracketMatch, BracketParticipant, BracketViewer, BracketMatchScore
• BracketFormat, TournamentStatus
• BracketJoinOptions, BracketJoinResult
• PROTOCOL_VERSION, SPEC_URL — string constants for runtime introspection

License

CC0 1.0 Universal — public domain. Implement, fork, copy, modify, redistribute. No attribution required.