gloomberb 0.11.2 → 0.12.0

package/src/cli/pane-functions/headless.ts

@@ -0,0 +1,423 @@
+import { apiClient } from "../../api-client";
+import type { MarketContext } from "../types";
+import type {
+  HeadlessBundleResult,
+  HeadlessBundleSection,
+  HeadlessPaneColumn,
+  HeadlessPaneContext,
+  HeadlessPaneDefinition,
+  HeadlessPaneEntry,
+  HeadlessPaneLoadArgs,
+  HeadlessPaneOptionValues,
+  HeadlessPaneResult,
+  HeadlessPaneRow,
+  HeadlessSeriesResult,
+  HeadlessSnapshotResult,
+} from "../../types/plugin";
+import { renderSection, renderTable } from "../../utils/cli-output";
+import type { PaneFunctionReport } from "./report";
+import type { ResolvedPaneFunction } from "./resolver";
+
+interface SerializableHeadlessColumn {
+  key: string;
+  header: string;
+  align?: "left" | "right" | "center";
+  width?: number;
+  description?: string;
+}
+
+export interface LoadedHeadlessPaneModel {
+  definition: HeadlessPaneDefinition;
+  args: HeadlessPaneLoadArgs;
+  result: HeadlessPaneResult;
+}
+
+function argumentName(definition: HeadlessPaneDefinition): string {
+  return definition.argument.placeholder
+    ?? (definition.argument.kind === "free-text" ? "text" : "symbol");
+}
+
+function requiredArgumentError(definition: HeadlessPaneDefinition, token: string): Error {
+  return new Error(`Usage: gloomberb fn ${token} <${argumentName(definition)}>`);
+}
+
+function normalizeSymbol(value: string): string {
+  return value.trim().replace(/^\$+/, "").toUpperCase();
+}
+
+function normalizeSymbolList(value: string): string[] {
+  const symbols: string[] = [];
+  const seen = new Set<string>();
+  for (const part of value.split(/[,\n]/)) {
+    const symbol = normalizeSymbol(part);
+    if (!symbol || seen.has(symbol)) continue;
+    seen.add(symbol);
+    symbols.push(symbol);
+  }
+  return symbols;
+}
+
+function validateSymbolCount(
+  definition: HeadlessPaneDefinition,
+  token: string,
+  symbols: string[],
+): void {
+  const minimum = definition.argument.minimum
+    ?? (definition.argument.optional ? 0 : 1);
+  const maximum = definition.argument.maximum;
+  if (symbols.length < minimum) {
+    if (minimum <= 1) throw requiredArgumentError(definition, token);
+    throw new Error(`${token} requires at least ${minimum} symbols.`);
+  }
+  if (maximum != null && symbols.length > maximum) {
+    throw new Error(`${token} accepts at most ${maximum} symbols.`);
+  }
+}
+
+export function buildHeadlessPaneLoadArgs(
+  definition: HeadlessPaneDefinition,
+  token: string,
+  rawArgument: string,
+  options: HeadlessPaneOptionValues,
+): HeadlessPaneLoadArgs {
+  const raw = rawArgument.trim();
+  switch (definition.argument.kind) {
+    case "none":
+      if (raw) throw new Error(`${token} does not accept an argument.`);
+      return { rawArgument: raw, argument: null, symbols: [], options };
+    case "free-text":
+      if (!raw && !definition.argument.optional) throw requiredArgumentError(definition, token);
+      return { rawArgument: raw, argument: raw || null, symbols: [], options };
+    case "ticker": {
+      const symbol = normalizeSymbol(raw);
+      const symbols = symbol ? [symbol] : [];
+      validateSymbolCount(definition, token, symbols);
+      return {
+        rawArgument: raw,
+        argument: symbol || null,
+        symbols,
+        options,
+      };
+    }
+    case "tickers":
+    case "symbol-list": {
+      const symbols = normalizeSymbolList(raw);
+      validateSymbolCount(definition, token, symbols);
+      return {
+        rawArgument: raw,
+        argument: symbols.length > 0 ? symbols : null,
+        symbols,
+        options,
+      };
+    }
+    default: {
+      const _exhaustive: never = definition.argument.kind;
+      return _exhaustive;
+    }
+  }
+}
+
+function throwIfAborted(signal: AbortSignal): void {
+  if (!signal.aborted) return;
+  throw signal.reason instanceof Error
+    ? signal.reason
+    : new Error("Headless pane load was aborted.");
+}
+
+export async function loadHeadlessPaneModel(
+  definition: HeadlessPaneDefinition,
+  args: HeadlessPaneLoadArgs,
+  context: HeadlessPaneContext,
+): Promise<HeadlessPaneResult> {
+  throwIfAborted(context.signal);
+  const result = await definition.load(args, context);
+  throwIfAborted(context.signal);
+  validateHeadlessResult(definition.shape, result);
+  return result;
+}
+
+/**
+ * Loads the same renderer-neutral model used by `fn`.
+ * A future screenshot payload can call this function instead of adding another fetch path.
+ */
+export async function loadResolvedHeadlessPaneModel(
+  resolved: ResolvedPaneFunction,
+  context: MarketContext,
+  rawArgument: string,
+  signal: AbortSignal = new AbortController().signal,
+): Promise<LoadedHeadlessPaneModel> {
+  const definition = resolved.headless;
+  if (!definition) throw new Error(`${resolved.token} has no headless pane model.`);
+  const args = buildHeadlessPaneLoadArgs(definition, resolved.token, rawArgument, resolved.options);
+  const headlessContext: HeadlessPaneContext = {
+    marketData: context.dataProvider,
+    apiClient,
+    config: context.config,
+    signal,
+  };
+  const result = await loadHeadlessPaneModel(definition, args, headlessContext);
+  return { definition, args, result };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
+function validateHeadlessResult(shape: HeadlessPaneDefinition["shape"], result: unknown): void {
+  if (!isRecord(result)) throw new Error(`Headless ${shape} loader returned an invalid result.`);
+  const valid = shape === "rows"
+    ? Array.isArray(result.rows)
+    : shape === "bundle"
+      ? Array.isArray(result.sections)
+      : shape === "series"
+        ? Array.isArray(result.series)
+        : Array.isArray(result.items) && result.asOf != null;
+  if (!valid) throw new Error(`Headless ${shape} loader returned an invalid result.`);
+}
+
+function serializableColumns(columns: HeadlessPaneColumn[]): SerializableHeadlessColumn[] {
+  return columns.map((column) => ({
+    key: column.key,
+    header: column.header,
+    ...(column.align ? { align: column.align } : {}),
+    ...(column.width != null ? { width: column.width } : {}),
+    ...(column.description ? { description: column.description } : {}),
+  }));
+}
+
+function inferColumns(rows: HeadlessPaneRow[]): HeadlessPaneColumn[] {
+  const keys = new Set<string>();
+  for (const row of rows) {
+    for (const key of Object.keys(row)) keys.add(key);
+  }
+  return [...keys].map((key) => ({ key, header: key }));
+}
+
+function columnsFor(
+  rows: HeadlessPaneRow[],
+  ownColumns: HeadlessPaneColumn[] | undefined,
+  fallbackColumns: HeadlessPaneColumn[] | undefined,
+): HeadlessPaneColumn[] {
+  return ownColumns ?? fallbackColumns ?? inferColumns(rows);
+}
+
+function serializeBundleSection(
+  section: HeadlessBundleSection,
+  fallbackColumns: HeadlessPaneColumn[] | undefined,
+): Record<string, unknown> {
+  if ("rows" in section && section.rows) {
+    const columns = columnsFor(section.rows, section.columns, fallbackColumns);
+    return {
+      title: section.title,
+      columns: serializableColumns(columns),
+      rows: section.rows,
+    };
+  }
+  return { title: section.title, entries: section.entries };
+}
+
+export function serializeHeadlessPaneResult(
+  definition: HeadlessPaneDefinition,
+  result: HeadlessPaneResult,
+): Record<string, unknown> {
+  const common = {
+    ...(result.errors ? { errors: result.errors } : {}),
+    ...(result.metadata ? { metadata: result.metadata } : {}),
+  };
+  switch (definition.shape) {
+    case "rows": {
+      const rowsResult = result as HeadlessPaneResult & { rows: HeadlessPaneRow[]; columns?: HeadlessPaneColumn[] };
+      const columns = columnsFor(rowsResult.rows, rowsResult.columns, definition.columns);
+      return { ...common, columns: serializableColumns(columns), rows: rowsResult.rows };
+    }
+    case "bundle": {
+      const bundle = result as HeadlessBundleResult;
+      return {
+        ...common,
+        sections: bundle.sections.map((section) => serializeBundleSection(section, definition.columns)),
+      };
+    }
+    case "series": {
+      const series = result as HeadlessSeriesResult;
+      return { ...common, series: series.series, ...(series.stats ? { stats: series.stats } : {}) };
+    }
+    case "snapshot": {
+      const snapshot = result as HeadlessSnapshotResult;
+      const columns = columnsFor(snapshot.items, undefined, definition.columns);
+      return {
+        ...common,
+        asOf: snapshot.asOf,
+        columns: serializableColumns(columns),
+        items: snapshot.items,
+      };
+    }
+    default: {
+      const _exhaustive: never = definition.shape;
+      return _exhaustive;
+    }
+  }
+}
+
+function displayValue(value: unknown): string {
+  if (value == null) return "-";
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "object") return JSON.stringify(value);
+  return String(value);
+}
+
+function renderRows(
+  rows: HeadlessPaneRow[],
+  ownColumns: HeadlessPaneColumn[] | undefined,
+  fallbackColumns: HeadlessPaneColumn[] | undefined,
+): string {
+  if (rows.length === 0) return "No data.";
+  const columns = columnsFor(rows, ownColumns, fallbackColumns);
+  return renderTable(
+    columns.map((column) => ({
+      header: column.header.toUpperCase(),
+      align: column.align,
+      width: column.width,
+    })),
+    rows.map((row) => columns.map((column) => {
+      const value = row[column.key];
+      return column.format ? column.format(value, row) : displayValue(value);
+    })),
+  );
+}
+
+function renderEntries(entries: HeadlessPaneEntry[]): string {
+  if (entries.length === 0) return "No data.";
+  return renderTable(
+    [{ header: "METRIC" }, { header: "VALUE" }],
+    entries.map((entry) => [entry.label, entry.formatted ?? displayValue(entry.value)]),
+  );
+}
+
+function renderBundle(
+  definition: HeadlessPaneDefinition,
+  result: HeadlessBundleResult,
+): string[] {
+  return result.sections.flatMap((section, index) => [
+    ...(index > 0 ? [""] : []),
+    renderSection(section.title),
+    "rows" in section && section.rows
+      ? renderRows(section.rows, section.columns, definition.columns)
+      : renderEntries(section.entries),
+  ]);
+}
+
+function renderSeries(result: HeadlessSeriesResult): string[] {
+  const rows = result.series.map((series) => {
+    const latest = [...series.points].reverse().find((point) => (
+      point.value != null || point.close != null
+    ));
+    return {
+      series: series.label,
+      latest: latest ? displayValue(latest.date) : "-",
+      value: latest?.value ?? latest?.close ?? null,
+      points: series.points.length,
+    };
+  });
+  const columns: HeadlessPaneColumn[] = [
+    { key: "series", header: "Series" },
+    { key: "latest", header: "Latest" },
+    { key: "value", header: "Value", align: "right" },
+    { key: "points", header: "Points", align: "right" },
+  ];
+  const lines = [renderRows(rows, columns, undefined)];
+  if (result.stats) {
+    const entries = Array.isArray(result.stats)
+      ? result.stats
+      : Object.entries(result.stats).map(([label, value]) => ({ label, value }));
+    lines.push("", renderSection("Statistics"), renderEntries(entries));
+  }
+  return lines;
+}
+
+function reportTitle(definition: HeadlessPaneDefinition, args: HeadlessPaneLoadArgs, fallback: string): string {
+  if (typeof definition.describe === "function") return definition.describe(args);
+  return definition.describe ?? fallback;
+}
+
+export function renderHeadlessPaneText(
+  definition: HeadlessPaneDefinition,
+  result: HeadlessPaneResult,
+  args: HeadlessPaneLoadArgs,
+  fallbackTitle: string,
+): string {
+  const lines = [reportTitle(definition, args, fallbackTitle), ""];
+  switch (definition.shape) {
+    case "rows": {
+      const rowsResult = result as HeadlessPaneResult & { rows: HeadlessPaneRow[]; columns?: HeadlessPaneColumn[] };
+      lines.push(renderRows(rowsResult.rows, rowsResult.columns, definition.columns));
+      break;
+    }
+    case "bundle":
+      lines.push(...renderBundle(definition, result as HeadlessBundleResult));
+      break;
+    case "series":
+      lines.push(...renderSeries(result as HeadlessSeriesResult));
+      break;
+    case "snapshot": {
+      const snapshot = result as HeadlessSnapshotResult;
+      lines.push(`As of: ${displayValue(snapshot.asOf)}`, "", renderRows(snapshot.items, undefined, definition.columns));
+      break;
+    }
+    default: {
+      const _exhaustive: never = definition.shape;
+      return _exhaustive;
+    }
+  }
+  if (result.errors?.length) lines.push("", `Errors: ${result.errors.join(" ")}`);
+  return lines.join("\n").trimEnd();
+}
+
+function resultRowCount(definition: HeadlessPaneDefinition, result: HeadlessPaneResult): number {
+  switch (definition.shape) {
+    case "rows":
+      return (result as { rows: HeadlessPaneRow[] }).rows.length;
+    case "bundle":
+      return (result as HeadlessBundleResult).sections.reduce((count, section) => (
+        count + ("rows" in section && section.rows ? section.rows.length : section.entries.length)
+      ), 0);
+    case "series":
+      return (result as HeadlessSeriesResult).series.reduce((count, series) => count + series.points.length, 0);
+    case "snapshot":
+      return (result as HeadlessSnapshotResult).items.length;
+    default: {
+      const _exhaustive: never = definition.shape;
+      return _exhaustive;
+    }
+  }
+}
+
+export async function buildHeadlessFunctionReport(
+  resolved: ResolvedPaneFunction,
+  context: MarketContext,
+  rawArgument: string,
+): Promise<PaneFunctionReport> {
+  const loaded = await loadResolvedHeadlessPaneModel(resolved, context, rawArgument);
+  const rowCount = resultRowCount(loaded.definition, loaded.result);
+  const unavailableSymbols = rowCount === 0 ? loaded.args.symbols : [];
+  const serialized = serializeHeadlessPaneResult(loaded.definition, loaded.result);
+  return {
+    data: {
+      kind: loaded.definition.shape,
+      target: resolved.token,
+      capabilityId: resolved.capability.id,
+      symbols: loaded.args.symbols,
+      options: resolved.options,
+      rowCount,
+      empty: rowCount === 0,
+      complete: unavailableSymbols.length === 0 && !loaded.result.errors?.length,
+      unavailableSymbols,
+      ...serialized,
+    },
+    text: renderHeadlessPaneText(
+      loaded.definition,
+      loaded.result,
+      loaded.args,
+      resolved.label,
+    ),
+  };
+}

package/src/cli/pane-functions/index.test.ts

@@ -208,6 +208,15 @@ describe("pane function CLI args", () => {
     });
   });
 
+  test("enables live DOM screenshots without claiming report support for unmapped panes", () => {
+    expect(capabilityFor("new-api-pane")).toMatchObject({
+      id: "unverified-pane",
+      botSafe: false,
+      reportReadiness: "unsupported",
+      screenshotReadiness: "live-dom",
+    });
+  });
+
   test("rejects financial statement options on a price comparison", () => {
     const capability = capabilityFor("comparison-chart-pane");
     expect(() => normalizeCapabilityOptions(capability, {

package/src/cli/pane-functions/index.ts

@@ -37,12 +37,13 @@ async function withPaneRuntime<T>(
     registry: PaneFunctionCatalog;
     resolved: ResolvedPaneFunction;
   }) => Promise<T>,
+  settings: { strictHeadlessOptions?: boolean } = {},
 ): Promise<T> {
   const parsed = parsePaneFunctionArgs(args);
   return withMarketData(ctx, async (context) => {
     const registry = await createPaneCatalog(context, ctx.plugins);
     try {
-      const resolved = await resolvePaneFunction(registry, context, parsed);
+      const resolved = await resolvePaneFunction(registry, context, parsed, settings);
       return await run({ parsed, context, registry, resolved });
     } finally {
       registry.destroy();
@@ -73,7 +74,7 @@ export async function runPaneFunction(args: string[], ctx: CliCommandContext) {
       ctx.printResult({ data: report.data }, {
         text: () => report.text,
       });
-    });
+    }, { strictHeadlessOptions: true });
   });
 }
 
@@ -98,6 +99,9 @@ export async function runPaneScreenshot(args: string[], ctx: CliCommandContext)
         outputPath,
         width: parsed.width,
         height: parsed.height,
+        theme: parsed.theme,
+        scale: parsed.scale,
+        watermark: parsed.watermark,
         options: parsed.options,
       });
       if (parsed.requireBotSafe && !result.usable) {

package/src/cli/pane-functions/options.ts

@@ -23,6 +23,12 @@ export interface ParsedPaneFunctionArgs {
   outputPath: string | null;
   width: number;
   height: number;
+  /** Theme id override for screenshots; null keeps the configured theme. */
+  theme: string | null;
+  /** Render scale: 1.5 renders two thirds as many cells at 1.5x size, so text reads larger at the same pixel size. */
+  scale: number;
+  /** Small label drawn in the pane title bar, e.g. a domain; null draws nothing. */
+  watermark: string | null;
   requireBotSafe: boolean;
 }
 
@@ -62,6 +68,9 @@ export function parsePaneFunctionArgs(args: string[]): ParsedPaneFunctionArgs {
   let outputPath: string | null = null;
   let width = DEFAULT_SHOT_WIDTH;
   let height = DEFAULT_SHOT_HEIGHT;
+  let theme: string | null = null;
+  let scale = 1;
+  let watermark: string | null = null;
   let requireBotSafe = false;
 
   for (let index = 0; index < args.length; index += 1) {
@@ -98,6 +107,12 @@ export function parsePaneFunctionArgs(args: string[]): ParsedPaneFunctionArgs {
       if (Number.isFinite(parsedHeight)) {
         height = Math.max(MIN_SHOT_HEIGHT, Math.min(MAX_SHOT_HEIGHT, Math.round(parsedHeight)));
       }
+    } else if (normalizedKey === "theme" && value !== true) {
+      theme = value.trim() || null;
+    } else if (normalizedKey === "scale" && value !== true) {
+      scale = parseScale(value);
+    } else if (normalizedKey === "watermark" && value !== true) {
+      watermark = value.trim() || null;
     } else if (normalizedKey === "arguments" && value !== true) {
       Object.assign(options, parseArgumentsOption(value));
     } else {
@@ -107,7 +122,7 @@ export function parsePaneFunctionArgs(args: string[]): ParsedPaneFunctionArgs {
 
   const target = positionals[0]?.trim() ?? "";
   const arg = positionals.slice(1).join(" ").trim();
-  return { target, arg, options, outputPath, width, height, requireBotSafe };
+  return { target, arg, options, outputPath, width, height, theme, scale, watermark, requireBotSafe };
 }
 
 export function parsePaneCatalogArgs(args: string[]): ParsedPaneCatalogArgs {
@@ -165,7 +180,17 @@ export function optionString(options: PaneOptionValues, key: string): string | u
   return value === true || value === undefined ? undefined : String(value);
 }
 
-const RESERVED_OPTION_KEYS = new Set(["output", "out", "o", "width", "height", "arguments", "state"]);
+const RESERVED_OPTION_KEYS = new Set([
+  "output", "out", "o", "width", "height", "theme", "scale", "watermark", "arguments", "state",
+]);
+
+function parseScale(value: string): number {
+  const parsed = Number.parseFloat(value);
+  if (!Number.isFinite(parsed) || parsed < 0.5 || parsed > 4) {
+    throw new Error(`--scale must be a number between 0.5 and 4, got "${value}".`);
+  }
+  return parsed;
+}
 
 export function optionSettings(options: Record<string, string | true>): Record<string, unknown> {
   const settings: Record<string, unknown> = {};

package/src/cli/pane-functions/report.ts

@@ -44,6 +44,7 @@ import {
   withShotPriceHistory,
 } from "./data";
 import type { ResolvedPaneFunction } from "./resolver";
+import { buildHeadlessFunctionReport } from "./headless";
 
 export interface PaneFunctionReportData {
   kind: string;
@@ -750,6 +751,9 @@ export async function buildFunctionReport(
   context: MarketContext,
   rawArg: string,
 ): Promise<PaneFunctionReport> {
+  if (resolved.headless) {
+    return buildHeadlessFunctionReport(resolved, context, rawArg);
+  }
   if (isFinancialAnalysisFunction(resolved)) {
     return buildFinancialStatementReport(resolved, context, rawArg);
   }

package/src/cli/pane-functions/resolver.ts

@@ -1,6 +1,11 @@
 import type { PaneInstanceConfig } from "../../types/config";
 import { CHART_COMPOSER_PANE_ID } from "../../types/config";
-import type { PaneDef, PaneTemplateCreateOptions, PaneTemplateDef } from "../../types/plugin";
+import type {
+  HeadlessPaneDefinition,
+  PaneDef,
+  PaneTemplateCreateOptions,
+  PaneTemplateDef,
+} from "../../types/plugin";
 import { applyChartComposerCapabilityOptions } from "../../plugins/builtin/chart-composer/cli-options";
 import { parseChartSpec } from "../../plugins/builtin/chart-composer/chart-spec";
 import { normalizeTickerInput } from "../../tickers/search";
@@ -20,6 +25,7 @@ import {
 } from "./options";
 import {
   capabilityPaneSettings,
+  getHeadlessPaneDefinition,
   getPaneFunctionCapability,
   normalizeCapabilityOptions,
   type NormalizedPaneFunctionOptions,
@@ -33,6 +39,7 @@ export interface ResolvedPaneFunction {
   shortcut?: string;
   pane: PaneDef;
   template?: PaneTemplateDef;
+  headless?: HeadlessPaneDefinition;
   instance: PaneInstanceConfig;
   createOptions: PaneTemplateCreateOptions | undefined;
   optionSettings: Record<string, unknown>;
@@ -41,16 +48,24 @@ export interface ResolvedPaneFunction {
 }
 
 async function buildPaneInstance(
-  resolved: Pick<ResolvedPaneFunction, "pane" | "template" | "createOptions" | "optionSettings" | "capability" | "options">,
+  resolved: Pick<ResolvedPaneFunction, "pane" | "template" | "headless" | "createOptions" | "optionSettings" | "capability" | "options">,
   context: MarketContext,
   target: string,
 ): Promise<PaneInstanceConfig> {
-  // A text argument is a phrase, not a symbol: uppercasing it and binding it as
-  // a ticker makes the pane look for a provider for "HIGH GROWTH SOFTWARE".
-  const argKind = resolved.template?.shortcut?.argKind;
+  // Free text is a phrase, not a symbol. Treating it as a ticker makes the
+  // pane look for a provider for values such as "HIGH GROWTH SOFTWARE".
+  const shortcutArgKind = resolved.template?.shortcut?.argKind;
+  const headlessArgKind = resolved.headless?.argument.kind;
+  const fallbackSymbol = headlessArgKind === "free-text" || headlessArgKind === "none"
+    ? null
+    : headlessArgKind === "tickers" || headlessArgKind === "symbol-list"
+      ? normalizeTickerInput(null, cleanTickerInput(target.split(/[,\n]/)[0] ?? ""))
+      : shortcutArgKind === "text"
+        ? null
+        : normalizeTickerInput(null, cleanTickerInput(target));
   const primarySymbol = resolved.createOptions?.symbol
     ?? resolved.createOptions?.symbols?.[0]
-    ?? (argKind === "text" ? null : normalizeTickerInput(null, cleanTickerInput(target)));
+    ?? fallbackSymbol;
   const templateContext = buildTemplateContext(context, primarySymbol ?? null);
   const spec = await resolved.template?.createInstance?.(templateContext, resolved.createOptions) ?? {};
   const instanceId = `${resolved.pane.id}:cli-${slugifyName(target || resolved.pane.id, "pane")}`;
@@ -83,6 +98,7 @@ export async function resolvePaneFunction(
   registry: PaneFunctionCatalog,
   context: MarketContext,
   args: ParsedPaneFunctionArgs,
+  resolutionSettings: { strictHeadlessOptions?: boolean } = {},
 ): Promise<ResolvedPaneFunction> {
   if (!args.target) {
     throw new Error("Usage: gloomberb fn <function-or-pane> [argument] [--key value]");
@@ -106,9 +122,10 @@ export async function resolvePaneFunction(
     throw new Error(`Template "${template?.id}" points at missing pane "${template?.paneId}".`);
   }
   const createOptions = buildCreateOptions(template, args.arg);
+  const headless = getHeadlessPaneDefinition(template, pane);
   const capability = getPaneFunctionCapability(template, pane);
   const normalizedOptions = normalizeCapabilityOptions(capability, args.options, {
-    strict: args.requireBotSafe,
+    strict: args.requireBotSafe || (!!headless && resolutionSettings.strictHeadlessOptions === true),
   });
   const settings = capability.botSafe
     ? {
@@ -126,13 +143,14 @@ export async function resolvePaneFunction(
     shortcut: template?.shortcut?.prefix,
     pane,
     template,
+    ...(headless ? { headless } : {}),
     instance: {} as PaneInstanceConfig,
     createOptions,
     optionSettings: settings,
     capability,
     options: normalizedOptions,
   };
-  resolved.instance = await buildPaneInstance(resolved, context, args.arg || pane.id);
+  resolved.instance = await buildPaneInstance(resolved, context, args.arg);
   return resolved;
 }