@ai-gui/plugin-bigscreen 0.34.0

package/dist/index.d.cts

@@ -0,0 +1,205 @@
+import { AIGuiPlugin } from "@ai-gui/core";
+import { EChartsCoreOption } from "echarts/core";
+
+//#region src/types.d.ts
+/** The palette a screen is drawn in. `dark` is the big-screen look; `light` sits on a white page. */
+/** The palette a screen is drawn in. `dark` is the big-screen look; `light` sits on a white page. */
+type ScreenTheme = "dark" | "light";
+interface PanelBase {
+  title?: string;
+  /** How many of the screen's columns the panel takes. Default 4 of 12. */
+  span?: number;
+  /** Body height in CSS pixels. Default depends on the kind. */
+  height?: number;
+}
+/** One number, counted up from zero when it appears, with an optional change and sparkline. */
+interface KpiPanel extends PanelBase {
+  kind: "kpi";
+  value: number;
+  unit?: string;
+  prefix?: string;
+  /** Digits after the decimal point. Default 0. */
+  decimals?: number;
+  /** Change as a fraction: 0.12 is +12%. */
+  delta?: number;
+  /** Whether a positive delta is good. Default true. */
+  upIsGood?: boolean;
+  /** A short series drawn as a sparkline under the number. */
+  trend?: number[];
+  label?: string;
+}
+/** A dial or a ring showing how far `value` is along `max`. */
+interface GaugePanel extends PanelBase {
+  kind: "gauge";
+  value: number;
+  max?: number;
+  unit?: string;
+  style?: "dial" | "ring";
+  /** Fractions of `max` at which the colour turns amber, then red. */
+  thresholds?: [number, number];
+}
+/** Horizontal bars, longest first, growing in when they appear. */
+interface RankPanel extends PanelBase {
+  kind: "rank";
+  items: Array<{
+    name: string;
+    value: number;
+  }>;
+  unit?: string;
+  /** Show this many; the rest are dropped. Default 8. */
+  top?: number;
+}
+/** Any ECharts option, drawn on canvas with the screen's palette and entrance animation. */
+interface ChartPanel extends PanelBase {
+  kind: "chart";
+  option: Record<string, unknown>;
+}
+/** A 3D chart over the `data` points, slowly turning. */
+interface Chart3dPanel extends PanelBase {
+  kind: "chart3d";
+  type: "bar3D" | "scatter3D" | "surface" | "line3D";
+  /** Points as [x, y, z]; with category axes x and y are indexes into them. */
+  data: Array<[number, number, number]>;
+  xAxis?: string[];
+  yAxis?: string[];
+  rotate?: boolean;
+}
+/** A globe with arcs between places and points on it. */
+interface GlobePanel extends PanelBase {
+  kind: "globe";
+  arcs?: Array<{
+    from: [number, number];
+    to: [number, number];
+    label?: string;
+  }>;
+  points?: Array<{
+    coord: [number, number];
+    label?: string;
+    value?: number;
+  }>;
+  rotate?: boolean;
+}
+type Panel = KpiPanel | GaugePanel | RankPanel | ChartPanel | Chart3dPanel | GlobePanel;
+type PanelKind = Panel["kind"];
+interface ScreenDefinition {
+  title?: string;
+  subtitle?: string;
+  theme: ScreenTheme;
+  /** The accent colour, as a hex string. */
+  accent?: string;
+  /** Grid columns. Default 12. */
+  columns: number;
+  panels: Panel[];
+}
+interface BigscreenOptions {
+  /** Refuse a screen with more panels than this. Default 24. */
+  maxPanels?: number;
+  /** Refuse a fence larger than this, before parsing it. Default 64 KiB. */
+  maxSourceBytes?: number;
+  /** Host override: `false` draws everything at its final state, no count-ups, no rotation. Default true. */
+  animate?: boolean;
+  /** Host override for the palette; a screen's own `theme` wins when set in the fence. */
+  theme?: ScreenTheme;
+}
+interface BigscreenError {
+  code: "invalid-json" | "invalid-definition" | "too-large";
+  message: string;
+}
+type BigscreenResult<T> = {
+  ok: true;
+  value: T;
+} | {
+  ok: false;
+  error: BigscreenError;
+}; //#endregion
+//#region src/prompt.d.ts
+/**
+ * The model-facing rules for a data wall.
+ *
+ * The rule that must survive editing is "只用对话里已有的数字": a screen full of counting
+ * numbers looks like evidence, and a model that fills gaps with plausible figures produces a
+ * convincing lie. The examples show every panel kind once, because that is what a model copies,
+ * and the numbers in them are obviously placeholders.
+ *
+ * You rarely want this directly: `buildSystemPrompt({ registry, plugins, locale })` from
+ * `@ai-gui/core` collects the card specs and every enabled plugin's spec in one call, in the
+ * product's language. Reach for this only to inspect or override one plugin's rules.
+ */
+declare function bigscreenPromptSpec(locale?: string): string;
+
+//#endregion
+//#region src/parse.d.ts
+/** Validate one `bigscreen` fence, or explain why it cannot be shown. */
+declare function parseBigscreen(source: string, options?: {
+  maxPanels?: number;
+  maxSourceBytes?: number;
+  theme?: ScreenTheme;
+}): BigscreenResult<ScreenDefinition>;
+
+//#endregion
+//#region src/palette.d.ts
+interface Palette {
+  accent: string;
+  text: string;
+  muted: string;
+  good: string;
+  bad: string;
+  warn: string;
+  track: string;
+  /** The series colours charts cycle through. */
+  series: string[];
+  gridLine: string;
+}
+/**
+ * Two palettes, one per theme.
+ *
+ * The dark one is the data-wall look — deep navy, cyan accent, a little glow; the light one is
+ * the same screen on a white page. The accent can be overridden per screen, and the series
+ * colours start from it so a screen reads as one thing rather than a collage.
+ */
+declare function palette(definition: Pick<ScreenDefinition, "theme" | "accent">): Palette;
+/** `#rrggbb` with an alpha, for glows and fills. */
+declare function withAlpha(hex: string, alpha: number): string;
+
+//#endregion
+//#region src/options.d.ts
+/** Format a number for a label: thousands grouped, up to `decimals` places. */
+declare function formatNumber(value: number, decimals?: number): string;
+/** The colour a gauge shows at `fraction` of its range. */
+declare function gaugeColour(fraction: number, thresholds: [number, number] | undefined, c: Palette): string;
+declare function gaugeOption(panel: GaugePanel, c: Palette, animate: boolean): EChartsCoreOption;
+/**
+ * The screen's palette laid over whatever the model wrote.
+ *
+ * The model's option wins on anything it sets; this only fills in the colours, the font, the
+ * transparent background and the entrance animation a screen wants, so a plain `bar` series
+ * still looks like it belongs.
+ */
+declare function chartOption(panel: ChartPanel, c: Palette, animate: boolean): EChartsCoreOption;
+declare function chart3dOption(panel: Chart3dPanel, c: Palette, animate: boolean): EChartsCoreOption;
+/**
+ * A globe without a satellite photograph.
+ *
+ * ECharts' globe wants a texture, and the usual one is an image fetched from somewhere — which a
+ * page must not do on a model's say-so. So the texture is painted here: a deep sphere with a
+ * graticule, which is what a data wall's globe looks like anyway. Arcs get a moving trail.
+ */
+
+declare function globeOption(panel: GlobePanel, c: Palette, animate: boolean, texture: string | undefined): EChartsCoreOption;
+
+//#endregion
+//#region src/index.d.ts
+declare const bigscreenCss: string;
+/**
+ * A data wall: KPIs that count up, gauges that sweep, ranks that grow, charts that draw
+ * themselves, and 3D bars and globes that turn — laid out on a grid the model chooses.
+ *
+ * The screen is presentation, not evidence. Where the numbers must be the host's — a BI board
+ * over real queries — `@ai-gui/plugin-dashboard` is the block, and it refuses to let the model
+ * write a row. This one lets the model lay out the numbers it was given, which is what a
+ * summary, a demo or a briefing needs, and the prompt spec tells it never to invent them.
+ */
+declare function bigscreen(options?: BigscreenOptions): AIGuiPlugin;
+
+//#endregion
+export { BigscreenError, BigscreenOptions, BigscreenResult, Chart3dPanel, ChartPanel, GaugePanel, GlobePanel, KpiPanel, Panel, PanelKind, RankPanel, ScreenDefinition, ScreenTheme, bigscreen, bigscreenCss, bigscreenPromptSpec, chart3dOption, chartOption, formatNumber, gaugeColour, gaugeOption, globeOption, palette, parseBigscreen, withAlpha };

package/dist/index.d.ts

@@ -0,0 +1,205 @@
+import { AIGuiPlugin } from "@ai-gui/core";
+import { EChartsCoreOption } from "echarts/core";
+
+//#region src/types.d.ts
+/** The palette a screen is drawn in. `dark` is the big-screen look; `light` sits on a white page. */
+/** The palette a screen is drawn in. `dark` is the big-screen look; `light` sits on a white page. */
+type ScreenTheme = "dark" | "light";
+interface PanelBase {
+  title?: string;
+  /** How many of the screen's columns the panel takes. Default 4 of 12. */
+  span?: number;
+  /** Body height in CSS pixels. Default depends on the kind. */
+  height?: number;
+}
+/** One number, counted up from zero when it appears, with an optional change and sparkline. */
+interface KpiPanel extends PanelBase {
+  kind: "kpi";
+  value: number;
+  unit?: string;
+  prefix?: string;
+  /** Digits after the decimal point. Default 0. */
+  decimals?: number;
+  /** Change as a fraction: 0.12 is +12%. */
+  delta?: number;
+  /** Whether a positive delta is good. Default true. */
+  upIsGood?: boolean;
+  /** A short series drawn as a sparkline under the number. */
+  trend?: number[];
+  label?: string;
+}
+/** A dial or a ring showing how far `value` is along `max`. */
+interface GaugePanel extends PanelBase {
+  kind: "gauge";
+  value: number;
+  max?: number;
+  unit?: string;
+  style?: "dial" | "ring";
+  /** Fractions of `max` at which the colour turns amber, then red. */
+  thresholds?: [number, number];
+}
+/** Horizontal bars, longest first, growing in when they appear. */
+interface RankPanel extends PanelBase {
+  kind: "rank";
+  items: Array<{
+    name: string;
+    value: number;
+  }>;
+  unit?: string;
+  /** Show this many; the rest are dropped. Default 8. */
+  top?: number;
+}
+/** Any ECharts option, drawn on canvas with the screen's palette and entrance animation. */
+interface ChartPanel extends PanelBase {
+  kind: "chart";
+  option: Record<string, unknown>;
+}
+/** A 3D chart over the `data` points, slowly turning. */
+interface Chart3dPanel extends PanelBase {
+  kind: "chart3d";
+  type: "bar3D" | "scatter3D" | "surface" | "line3D";
+  /** Points as [x, y, z]; with category axes x and y are indexes into them. */
+  data: Array<[number, number, number]>;
+  xAxis?: string[];
+  yAxis?: string[];
+  rotate?: boolean;
+}
+/** A globe with arcs between places and points on it. */
+interface GlobePanel extends PanelBase {
+  kind: "globe";
+  arcs?: Array<{
+    from: [number, number];
+    to: [number, number];
+    label?: string;
+  }>;
+  points?: Array<{
+    coord: [number, number];
+    label?: string;
+    value?: number;
+  }>;
+  rotate?: boolean;
+}
+type Panel = KpiPanel | GaugePanel | RankPanel | ChartPanel | Chart3dPanel | GlobePanel;
+type PanelKind = Panel["kind"];
+interface ScreenDefinition {
+  title?: string;
+  subtitle?: string;
+  theme: ScreenTheme;
+  /** The accent colour, as a hex string. */
+  accent?: string;
+  /** Grid columns. Default 12. */
+  columns: number;
+  panels: Panel[];
+}
+interface BigscreenOptions {
+  /** Refuse a screen with more panels than this. Default 24. */
+  maxPanels?: number;
+  /** Refuse a fence larger than this, before parsing it. Default 64 KiB. */
+  maxSourceBytes?: number;
+  /** Host override: `false` draws everything at its final state, no count-ups, no rotation. Default true. */
+  animate?: boolean;
+  /** Host override for the palette; a screen's own `theme` wins when set in the fence. */
+  theme?: ScreenTheme;
+}
+interface BigscreenError {
+  code: "invalid-json" | "invalid-definition" | "too-large";
+  message: string;
+}
+type BigscreenResult<T> = {
+  ok: true;
+  value: T;
+} | {
+  ok: false;
+  error: BigscreenError;
+}; //#endregion
+//#region src/prompt.d.ts
+/**
+ * The model-facing rules for a data wall.
+ *
+ * The rule that must survive editing is "只用对话里已有的数字": a screen full of counting
+ * numbers looks like evidence, and a model that fills gaps with plausible figures produces a
+ * convincing lie. The examples show every panel kind once, because that is what a model copies,
+ * and the numbers in them are obviously placeholders.
+ *
+ * You rarely want this directly: `buildSystemPrompt({ registry, plugins, locale })` from
+ * `@ai-gui/core` collects the card specs and every enabled plugin's spec in one call, in the
+ * product's language. Reach for this only to inspect or override one plugin's rules.
+ */
+declare function bigscreenPromptSpec(locale?: string): string;
+
+//#endregion
+//#region src/parse.d.ts
+/** Validate one `bigscreen` fence, or explain why it cannot be shown. */
+declare function parseBigscreen(source: string, options?: {
+  maxPanels?: number;
+  maxSourceBytes?: number;
+  theme?: ScreenTheme;
+}): BigscreenResult<ScreenDefinition>;
+
+//#endregion
+//#region src/palette.d.ts
+interface Palette {
+  accent: string;
+  text: string;
+  muted: string;
+  good: string;
+  bad: string;
+  warn: string;
+  track: string;
+  /** The series colours charts cycle through. */
+  series: string[];
+  gridLine: string;
+}
+/**
+ * Two palettes, one per theme.
+ *
+ * The dark one is the data-wall look — deep navy, cyan accent, a little glow; the light one is
+ * the same screen on a white page. The accent can be overridden per screen, and the series
+ * colours start from it so a screen reads as one thing rather than a collage.
+ */
+declare function palette(definition: Pick<ScreenDefinition, "theme" | "accent">): Palette;
+/** `#rrggbb` with an alpha, for glows and fills. */
+declare function withAlpha(hex: string, alpha: number): string;
+
+//#endregion
+//#region src/options.d.ts
+/** Format a number for a label: thousands grouped, up to `decimals` places. */
+declare function formatNumber(value: number, decimals?: number): string;
+/** The colour a gauge shows at `fraction` of its range. */
+declare function gaugeColour(fraction: number, thresholds: [number, number] | undefined, c: Palette): string;
+declare function gaugeOption(panel: GaugePanel, c: Palette, animate: boolean): EChartsCoreOption;
+/**
+ * The screen's palette laid over whatever the model wrote.
+ *
+ * The model's option wins on anything it sets; this only fills in the colours, the font, the
+ * transparent background and the entrance animation a screen wants, so a plain `bar` series
+ * still looks like it belongs.
+ */
+declare function chartOption(panel: ChartPanel, c: Palette, animate: boolean): EChartsCoreOption;
+declare function chart3dOption(panel: Chart3dPanel, c: Palette, animate: boolean): EChartsCoreOption;
+/**
+ * A globe without a satellite photograph.
+ *
+ * ECharts' globe wants a texture, and the usual one is an image fetched from somewhere — which a
+ * page must not do on a model's say-so. So the texture is painted here: a deep sphere with a
+ * graticule, which is what a data wall's globe looks like anyway. Arcs get a moving trail.
+ */
+
+declare function globeOption(panel: GlobePanel, c: Palette, animate: boolean, texture: string | undefined): EChartsCoreOption;
+
+//#endregion
+//#region src/index.d.ts
+declare const bigscreenCss: string;
+/**
+ * A data wall: KPIs that count up, gauges that sweep, ranks that grow, charts that draw
+ * themselves, and 3D bars and globes that turn — laid out on a grid the model chooses.
+ *
+ * The screen is presentation, not evidence. Where the numbers must be the host's — a BI board
+ * over real queries — `@ai-gui/plugin-dashboard` is the block, and it refuses to let the model
+ * write a row. This one lets the model lay out the numbers it was given, which is what a
+ * summary, a demo or a briefing needs, and the prompt spec tells it never to invent them.
+ */
+declare function bigscreen(options?: BigscreenOptions): AIGuiPlugin;
+
+//#endregion
+export { BigscreenError, BigscreenOptions, BigscreenResult, Chart3dPanel, ChartPanel, GaugePanel, GlobePanel, KpiPanel, Panel, PanelKind, RankPanel, ScreenDefinition, ScreenTheme, bigscreen, bigscreenCss, bigscreenPromptSpec, chart3dOption, chartOption, formatNumber, gaugeColour, gaugeOption, globeOption, palette, parseBigscreen, withAlpha };