First definition guide

This walkthrough builds a small definition that fires a labeled event on bullish bars — ready to Collect and attach a study.

Use it when you want Chartnaut to find “every time this setup appeared” in history. In the API the word flow means the same thing as Definition in the product UI.

What you need first

• What is a definition

• Willingness to open Code (or let the Definition authoring agent draft it)

Steps

1. Create a definition under Research → Definitions.

2. Paste the script below into Code.

3. Preview emits on a chart — each pin title is the label, not the event id.

4. Snapshot / version, then Collect a dataset.

Full script

meta({
  name: "Bull bar",
  kind: "flow",
  slug: "bull-bar",
  shortName: "BullBar",
});

events.declare({
  id: "bull_bar",
  intent: "Mark closes above open",
  payload: {
    range: { type: "number", description: "High minus low" },
  },
  paint: "pin",
  oncePer: { keys: ["session"], windowBars: 1 },
});

outputs.declare({
  id: "close_line",
  kind: "line",
  name: "Close",
  color: "#64b5f6",
});

export function onBar(ctx) {
  ctx.plot("close_line", ctx.close);

  if (ctx.close <= ctx.open) return;

  const range = ctx.high - ctx.low;
  ctx.emit(
    "bull_bar",
    { range },
    {
      label: `Bull · R=${range.toFixed(2)}`,
      subtitle: `close ${ctx.close.toFixed(2)}`,
      price: ctx.close,
      timeStart: ctx.time,
    }
  );
}

Rules that bite early

• Every ctx.emit needs a non-empty label. Missing labels are lint-warned and dropped at runtime.

• Do not put _displayLabel or _displaySubtitle in events.declare.payload — those are reserved.

• Use oncePer for dedupe. Do not hand-roll emit throttling with module state.

• kind: "flow" enables events for Collect.

Next

1. Emit and labels

2. Events and snapshots

3. Collect a dataset