@emyrk/chronicle-panel-sdk

TypeScript contracts and binary event-stream helpers for trusted Chronicle custom panels.

Install

pnpm add @emyrk/chronicle-panel-sdk

Host API

import type {
  ChroniclePanelPluginV1,
  ChroniclePanelSnapshotV1,
} from "@emyrk/chronicle-panel-sdk/v1";

The snapshot includes instance and encounter timing, log capabilities, players, units, current selections, Sync state, panel dimensions, and theme. When a log is associated with a guild, snapshot.instance.guild contains its id and name; the field is absent for logs without a guild.

Event streams and protobuf

import { decodeEncounterPayloads } from "@emyrk/chronicle-panel-sdk/v1/events";
import { DamageSchema } from "@emyrk/chronicle-panel-sdk/v1/protobuf";

decodeEncounterPayloads() decodes Chronicle's chronicle-event-stream-v1 framing and the generated protobuf schema exports decode individual events. The canonical protobuf source is published with the package under proto/chronicle.proto.

Custom panel bundles must remain self-contained. Bundle this package into the panel's entry or worker artifact rather than leaving npm imports for Chronicle to resolve at runtime.

Floating breakouts

Chronicle owns the floating shell, dragging, resizing, mobile presentation, and lifecycle. Panels render their content into an isolated ShadowRoot:

const breakout = api.breakouts.open({
  title: "Warlock damage",
  initialPosition: { x: 200, y: 120 },
  initialSize: { width: 420, height: 300 },
  onClose: () => {
    // Drop any plugin state associated with this breakout.
  },
});

breakout.root.append(content);
// Optional; Chronicle also closes it when the panel unmounts.
breakout.close();

A panel instance may open up to eight simultaneous breakouts. onClose runs exactly once after a breakout closes, whether it was closed by Chronicle's shell, the returned handle, closeAll(), or panel teardown. closeAll() only closes breakouts owned by that mounted panel instance.

Compatibility

• Host API: 1
• Manifest schema: 1
• Event framing: chronicle-event-stream-v1

Breaking changes to a versioned host or stream contract require a new versioned entry point. Additive protobuf fields remain wire-compatible.