prism

README

Prism

Prism is a visualization library for .pulse files. It compiles declarative JSON specs into charts — server-side SVG / PNG / PDF via Go, and live in-browser via web components — using Vega-Lite-inspired vocabulary with snake_case naming and Pulse expression syntax.

Install

go install github.com/frankbardon/prism/cmd/prism@latest
prism version   # prism v0.2.0

First chart in 5 lines

prism init
cp .prism/examples/bar_basic.json my-chart.prism.json
prism plot my-chart.prism.json > chart.svg
open chart.svg

What ships in v0.1

• Six-stage pipeline — Spec → Validate → Plan → Compile → Encode → Render.
• 20+ marks — bar, line, area, point, rule, text, tick, rect, arc, pie, donut, histogram, heatmap, boxplot, violin, sankey, funnel, sparkline, image, path.
• Composition — layer, concat, hconcat, vconcat, facet, repeat. Cross-layer scale resolution (shared/independent).
• Multi-source — datasets block + hash join + parallel Source execution. Server-side + browser-side dataset registries.
• Selections — point + interval; client + server reactive modes.
• Themes — light, dark, print built-in. Sparse override via spec or custom theme.json.
• Renderers — SVG (Go), Canvas-via-JS (vendored ESM web component), PDF (gopdf with embedded fonts, paginated grids).
• Service surface — Twirp HTTP + MCP stdio. prism serve, prism mcp.
• CLI — validate, plan, execute, plot, scene, serve, mcp, inspect, examples, schema, init, errors lookup, static-bundle, version.

Documentation

The full manual is an mdBook under docs/, published to https://frankbardon.github.io/prism/. Build locally with make docs-serve.

• Getting started — install + first chart + editor setup.
• Gallery — 59 fixture specs with rendered SVGs.
• Concepts — spec, marks, encoding, composition, selections, themes, multi-source.
• Cookbook — multi-source join, faceting, custom themes, MCP agent integration.
• Migration from Vega-Lite.
• prism errors lookup CODE — fixup metadata for every PRISM_* code.

License

MIT — see LICENSE.

Contributing

See CONTRIBUTING.md for setup, conventions, and PR guidelines, and CLAUDE.md for the full set of conventions, contracts, and the Update Demand table. The .planning/ directory carries the design discussion, phase plans, and locked decisions; new features should land with a PHASE.md + PLAN.md following the existing pattern.

Documentation

Overview

Package prism is the public Go entry point for the Prism visualization library. The full pipeline lives in subpackages (spec, validate, plan, plan/build, encode, render, …); this root package exposes the two highest-level operations callers reach for:

• Compile — run the pipeline up to but not including the rasterising render stage. Returns a renderer-agnostic CompiledPlan describing what would be drawn. Typically 10-50× cheaper than a full Render (the encode + raster stages are the expensive ones).

• Render — full pipeline → byte stream (SVG today; PDF gated by build tag).

Both helpers accept either a parsed *spec.Spec or raw JSON bytes and surface diagnostics (PRISM_WARN_* warnings) alongside any hard-error envelope.

Index

• func ApplyPatch(s *spec.Spec, p Patch) (*spec.Spec, error)
• type CompileOptions
• type CompiledMark
• type CompiledPlan
  • func Compile(ctx context.Context, s *spec.Spec, opts CompileOptions) (*CompiledPlan, error)
  • func CompileJSON(ctx context.Context, specJSON []byte, opts CompileOptions) (*CompiledPlan, error)
• type CompiledScale
• type DataBinding
• type Diagnostic
• type LayoutInfo
• type Patch
  • func DiffSpecs(before, after *spec.Spec) (Patch, error)
• type PatchOp
• type Scene
  • func NewScene(ctx context.Context, s *spec.Spec, opts CompileOptions) (*Scene, error)
  • func (s *Scene) Apply(p Patch) error
  • func (s *Scene) ApplyAndRender(p Patch) (*CompiledPlan, error)
  • func (s *Scene) Plan() *CompiledPlan
  • func (s *Scene) Spec() *spec.Spec

Functions

func ApplyPatch

func ApplyPatch(s *spec.Spec, p Patch) (*spec.Spec, error)

ApplyPatch returns a new *spec.Spec with the patch's operations applied. The input spec is not mutated. On any operation failure (path miss, type mismatch, schema violation post-apply), the returned spec is nil and the error envelope carries PRISM_SPEC_PATCH_001 with the failing operation index in Details.

Types

type CompileOptions

type CompileOptions struct {
	Build  build.Options
	Exec   plan.ExecOpts
	Encode encode.EncodeOpts
}

CompileOptions controls the compile pipeline. Build, Exec, and Encode are passed through to the corresponding stages. When zero, sensible defaults are filled in (in-memory backend, single-worker executor, 800×600 layout).

type CompiledMark

type CompiledMark struct {
	SceneID       string         `json:"scene_id"`
	LayerID       string         `json:"layer_id"`
	MarkIndex     int            `json:"mark_index"`
	Type          scene.MarkType `json:"type"`
	InstanceCount int            `json:"instance_count"`
	Source        string         `json:"source,omitempty"`
}

CompiledMark summarises one layer's worth of marks. MarkIndex is the layer's index within its enclosing scene; InstanceCount is the number of individual mark geometries (one per data row in the general case).

type CompiledPlan

type CompiledPlan struct {
	Scene       *scene.SceneDoc `json:"scene"`
	Marks       []CompiledMark  `json:"marks"`
	Scales      []CompiledScale `json:"scales"`
	Data        []DataBinding   `json:"data"`
	Layout      LayoutInfo      `json:"layout"`
	Diagnostics []Diagnostic    `json:"diagnostics"`
}

CompiledPlan is the structured output of Compile: the same information the renderer would consume, exposed as a stable JSON shape. Callers can inspect the plan, diff two plans against each other, or hand it to a renderer separately via RenderPlan.

The Scene field carries the canonical IR; the flattened views (Marks, Scales, Data, Layout) summarise it for programmatic inspection so callers don't have to traverse the full tree.

func Compile

func Compile(ctx context.Context, s *spec.Spec, opts CompileOptions) (*CompiledPlan, error)

Compile runs Validate → Plan → Execute → Encode and returns a CompiledPlan. The result is renderer-agnostic; pass it to RenderPlan to produce pixel bytes. Typical cost is dominated by the executor (data I/O + aggregation); the marshalled CompiledPlan itself is light. Callers that want only the plan summary can discard CompiledPlan.Scene to drop the full IR.

func CompileJSON

func CompileJSON(ctx context.Context, specJSON []byte, opts CompileOptions) (*CompiledPlan, error)

CompileJSON decodes specJSON and delegates to Compile.

type CompiledScale

type CompiledScale struct {
	SceneID string          `json:"scene_id"`
	Channel scene.Channel   `json:"channel"`
	Type    scene.ScaleType `json:"type"`
	Domain  []any           `json:"domain"`
	Range   [2]float64      `json:"range"`
}

CompiledScale is the post-resolve scale descriptor for one channel. Domain values are typed `any` because categorical scales carry strings while quantitative scales carry numbers / times.

type DataBinding

type DataBinding struct {
	Name     string `json:"name"`
	Hash     string `json:"hash,omitempty"`
	Resolved bool   `json:"resolved"`
}

DataBinding is one dataset reference resolved during compile. Resolved is always true when present in the CompiledPlan (compile failed otherwise); the field is retained for forward-compatibility with the data-reference variant which can produce data-pending states.

type Diagnostic

type Diagnostic struct {
	Code    string `json:"code"`
	Message string `json:"message"`
	Path    string `json:"path,omitempty"`
}

Diagnostic mirrors a SceneDoc warning. Code is a PRISM_WARN_* (or any future PRISM_* code emitted during compile); Path is the layer / channel context when known.

type LayoutInfo

type LayoutInfo struct {
	Width  float64 `json:"width"`
	Height float64 `json:"height"`
	Rows   int     `json:"rows"`
	Cols   int     `json:"cols"`
}

LayoutInfo carries the resolved chart-frame dimensions and the composition grid shape (rows/cols).

type Patch

type Patch []PatchOp

Patch is an RFC 6902 JSON Patch — an ordered list of operations to transform one spec into another. Use ApplyPatch to apply a patch to a spec; DiffSpecs to compute one between two specs.

Atomic semantics: ApplyPatch either succeeds with every operation applied, or fails with no state change. A failing operation's index is returned in the error envelope.

func DiffSpecs

func DiffSpecs(before, after *spec.Spec) (Patch, error)

DiffSpecs returns a Patch that, when applied to before, produces after. The result is a sequence of `replace` / `add` / `remove` operations expressed against the JSON form of the specs — not necessarily the minimal patch, but a correct one. Useful for callers that want to think in full specs and transmit minimal updates.

type PatchOp

type PatchOp struct {
	Op    string `json:"op"`
	Path  string `json:"path"`
	Value any    `json:"value,omitempty"`
	From  string `json:"from,omitempty"`
}

PatchOp is one RFC 6902 operation.

Op:    "add" | "remove" | "replace" | "move" | "copy" | "test"
Path:  JSON Pointer (RFC 6901) targeting the value to operate on.
Value: required for add / replace / test.
From:  required for move / copy (the source pointer).

type Scene

type Scene struct {
	// contains filtered or unexported fields
}

Scene is a stateful wrapper around a Prism spec + its last CompiledPlan. Use it when the consumer wants to evolve a chart incrementally via patches: each Apply mutates the in-memory spec and re-compiles, exposing the new plan via Plan().

Scene is not safe for concurrent use; serialise Apply calls externally if multiple goroutines drive a single scene.

func NewScene

func NewScene(ctx context.Context, s *spec.Spec, opts CompileOptions) (*Scene, error)

NewScene compiles an initial spec and returns a Scene bound to it. The returned Scene can be patched via Apply / ApplyAndRender.

func (*Scene) Apply

func (s *Scene) Apply(p Patch) error

Apply transforms the scene's spec by the given RFC 6902 patch and re-compiles. The mutation is atomic: if any operation fails, or the resulting spec fails to decode / re-compile, the scene's state is unchanged and the error envelope explains why.

func (*Scene) ApplyAndRender

func (s *Scene) ApplyAndRender(p Patch) (*CompiledPlan, error)

ApplyAndRender applies the patch and returns the updated plan in one call. It is shorthand for Apply followed by Plan(). The "render" half of the name follows the upgrade-spec API; the returned object is the structured CompiledPlan — callers wanting pixels should hand it to a Renderer.

func (*Scene) Plan

func (s *Scene) Plan() *CompiledPlan

Plan returns the most recent CompiledPlan.

func (*Scene) Spec

func (s *Scene) Spec() *spec.Spec

Spec returns the scene's current *spec.Spec. The returned value is shared with the scene; callers should not mutate it directly — patches must travel through Apply / ApplyAndRender so the compiled plan stays in sync.