@navbytes/vee 0.3.0

package/README.md

@@ -0,0 +1,118 @@
+# Vee TypeScript SDK
+
+A tiny, zero-dependency TypeScript SDK for writing Vee plugins with typed
+builders instead of hand-formatting the xbar/SwiftBar text protocol. It mirrors
+the [Python](../python) and [Go](../go) SDKs — same builder shape, option names,
+encoding order, and quoting — and produces byte-identical output. Node runs the
+TypeScript directly (type-stripping), so there is no build step.
+
+## Requirements
+
+- Node 24+ (for native TypeScript execution). No dependencies.
+
+## Installing
+
+A Vee plugin is a single executable dropped in your plugins folder — no build
+step, no `node_modules`. The SDK therefore travels *with* the plugin as a
+sibling file rather than being resolved from a package manager:
+
+```sh
+vee sdk ts --out ~/path/to/your/plugins   # writes vee.ts there
+```
+
+```ts
+import { Menu } from "./vee.ts";
+```
+
+`vee new --lang ts --out DIR` does both at once — it scaffolds a plugin and
+writes `vee.ts` beside it, so the result runs immediately.
+
+**Or from npm**, if your plugin is part of a project that already has a
+`node_modules` — a bundled plugin, or one you build before dropping in:
+
+```sh
+npm install @navbytes/vee
+```
+
+```ts
+import { Menu } from "@navbytes/vee";
+```
+
+The package ships compiled JavaScript with type declarations, because Node
+refuses to strip types under `node_modules`. It has no dependencies, and it
+carries the same version as the app it was released with — the SDK and the
+parser that reads its output ship from one commit, so a matching pair is a
+guaranteed-compatible pair.
+
+The examples in this repository import `../vee.ts` because they sit next to the
+SDK here. Copying one out means running `vee sdk ts` beside it and changing that
+import to `./vee.ts`.
+
+## Layout
+
+```
+plugins/typescript/
+├─ vee.ts           # the SDK: Menu, Section, ItemOptions
+├─ examples/*.ts    # example plugins; each exports build() -> string
+├─ test/*.test.ts   # drift guard (node --test)
+└─ package.json     # npm test, npm run build:fixtures
+```
+
+Golden fixtures live one level up in [`../fixtures/`](../fixtures) and are shared
+by all three SDKs — see the [plugins README](../README.md).
+
+## Hello world
+
+Create `cpu.5s.ts` in your plugins folder:
+
+```ts
+#!/usr/bin/env node
+import { Menu } from "./vee.ts";
+
+const menu = new Menu();
+menu.title("CPU 12%", { color: "green", sfimage: "cpu" });
+
+const d = menu.dropdown;
+d.item("Top processes", { href: "https://example.com/procs" });
+d.separator();
+
+const details = d.submenu("Details");
+details.item("Load: 1.20");
+details.item("Cores: 8");
+
+d.item("Refresh", { refresh: true });
+
+menu.print();
+```
+
+Make it executable (`chmod +x cpu.5s.ts`) and drop it in your plugins folder.
+The `.5s` sets a 5-second refresh, exactly as with any other plugin.
+
+## API
+
+The three SDKs expose the same `Menu` / `Section` / options surface, method for
+method, and are checked against each other so they cannot drift. Rather than
+restate a third of that contract here, the full cross-language reference —
+every method, every option, and the TypeScript spelling of each — lives in one
+place:
+
+**[Plugin SDKs reference](https://vee.navbytes.io/guide/sdk/)**
+
+For the parameters themselves — what each one accepts, its default, and which
+chart it belongs to — see the [plugin authoring
+reference](https://vee.navbytes.io/guide/plugin-authoring/) and
+[Charts](https://vee.navbytes.io/guide/charts/), both generated from
+`docs/api/params.json`, the same record this SDK is verified against.
+
+## Tests
+
+```sh
+cd plugins/typescript
+npm test                 # fixture drift guard (node --test)
+npm run build:fixtures   # regenerate ../fixtures from the examples
+```
+
+The drift guard runs each example's `build()` and asserts the output matches its
+golden fixture in `../fixtures/`. Because those fixtures are shared with the
+Python and Go SDKs and parsed by the Swift `VeePluginFormat` tests, this keeps
+every SDK, the fixtures, and the parser in lockstep.

package/dist/vee.d.ts

@@ -0,0 +1,413 @@
+export type Color = string;
+export interface ItemOptions {
+    color?: Color;
+    size?: number;
+    font?: string;
+    length?: number;
+    /** Trim surrounding whitespace from the text. */
+    trim?: boolean;
+    /** Interpret ANSI colour escapes in the text. */
+    ansi?: boolean;
+    /** Expand `:emoji:` shortcodes in the text. */
+    emojize?: boolean;
+    href?: string;
+    /** Shell command to run on click; `params` become param1..N. */
+    shell?: string;
+    params?: string[];
+    terminal?: boolean;
+    refresh?: boolean;
+    /** Show this line in the dropdown only, never in the menu bar. */
+    dropdown?: boolean;
+    alternate?: boolean;
+    disabled?: boolean;
+    checked?: boolean;
+    key?: string;
+    tooltip?: string;
+    /** An image for the row: a base64 payload or a file path. */
+    image?: string;
+    /** Like `image`, but rendered as a template image (adapts to the theme). */
+    templateImage?: string;
+    /** SF Symbol name (SwiftBar/Vee extension). */
+    sfimage?: string;
+    /**
+     * SF Symbol colour(s) → `sfcolor=`. A list supplies one colour per layer of
+     * a multicolour symbol; Vee reads it as a comma-separated list, so keep
+     * commas out of colour names.
+     */
+    sfColor?: Color | Color[];
+    /** SF Symbol point size → `sfsize=`. */
+    sfSize?: number;
+    /** SF Symbol configuration string → `sfconfig=`. */
+    sfConfig?: string;
+    /** Render the text as inline Markdown. */
+    md?: boolean;
+    /** Trailing badge chip. */
+    badge?: string;
+    /** Render `:sf.symbol:` tokens in the text as inline SF Symbols. */
+    symbolize?: boolean;
+    /** Open this web URL in a web view on click → `webview=`. */
+    webview?: string;
+    /** Web view width in points → `webvieww=`. */
+    webviewW?: number;
+    /** Web view height in points → `webviewh=`. */
+    webviewH?: number;
+    /** Name of a macOS Shortcut to run on click → `shortcut=`. */
+    shortcut?: string;
+    /**
+     * Render as a native, non-interactive section header (`header=true`) — a
+     * real `NSMenuItem.sectionHeader`, not a disabled row dressed up as one.
+     */
+    header?: boolean;
+    /**
+     * Which edge this row's visual accessory anchors to → `accessory=`. Applies
+     * uniformly to `sparkline`, `progress`, and the `chart` shapes, since they
+     * share the same in-row geometry. Omitted, the accessory sits trailing.
+     */
+    accessory?: "leading" | "trailing";
+    /** Inline data series → `sparkline=1,2,3`. */
+    sparkline?: number[];
+    /**
+     * Sparkline width in points. `"full"` stretches the chart to the row's own
+     * width instead. Emitted as `accessoryw=`, which sizes whichever accessory a
+     * row carries; `progressW`, `chart.w` and `accessoryW` are the same knob
+     * reached from different option sets.
+     */
+    sparklineW?: number | "full";
+    /**
+     * Width in points for whichever accessory this row carries — gauge,
+     * sparkline, chart, or slider → `accessoryw=`. `"full"` stretches it to the
+     * row's own width. Use this to size a `slider`, which has no option of its
+     * own; for the others the per-accessory options are equivalent.
+     */
+    accessoryW?: number | "full";
+    /** Height in points for this row's accessory → `accessoryh=`. Ignored for a toggle or slider. */
+    accessoryH?: number;
+    /** Sparkline height in points, emitted as `accessoryh=`. */
+    sparklineH?: number;
+    /** Sparkline line colour → `sparklinecolor=`. Falls back to the row's `color`. */
+    sparklineColor?: Color;
+    /** On/off switch → `toggle=on` / `toggle=off`. */
+    toggle?: boolean;
+    /** Continuous control → `slider=min,max,value`. */
+    slider?: {
+        min: number;
+        max: number;
+        value: number;
+    };
+    /**
+     * Progress gauge. Pass a fraction directly → `progress=<fraction>`, or
+     * `{ value, max }` → `progress=<value>,<max>`, which the format accepts
+     * natively and Vee divides on parse. The two-argument form keeps the
+     * author's own numbers on the wire instead of a pre-divided float.
+     */
+    progress?: number | {
+        value: number;
+        max: number;
+    };
+    /** Progress track (background) colour → `progresstrackcolor=`. */
+    progressTrackColor?: Color;
+    /**
+     * @deprecated The pre-v2 spelling of `progressTrackColor`. Still accepted and
+     * still emitted as `progresstrackcolor=`; will be removed in the next major
+     * version.
+     */
+    trackColor?: Color;
+    /**
+     * Progress bar width in points, emitted as `accessoryw=`. `"full"` stretches the bar to
+     * the row's own width instead, the same knob `chart.w` takes.
+     */
+    progressW?: number | "full";
+    /** Progress bar height in points, emitted as `accessoryh=`. */
+    progressH?: number;
+    /**
+     * Categorical share chart → `pie=` / `donut=` / `stackedbar=`. All three
+     * shapes take the same data — one series of non-negative values read as
+     * shares of a whole — so switching `kind` needs no other change.
+     *
+     * `labels`/`colors` are positional against `values`. Vee reads both as
+     * comma-separated lists, so a label containing a comma would be read as two
+     * labels: keep commas out of segment names.
+     */
+    chart?: {
+        kind: "pie" | "donut" | "stackedbar";
+        values: number[];
+        labels?: string[];
+        colors?: Color[];
+        /**
+         * Inline size in points, emitted as `accessoryw=`/`accessoryh=`. A pie/donut is a circle, so
+         * either knob sizes both sides; a stacked bar takes them independently.
+         * Omitted, a chart takes its per-kind default (24pt circle, 110×12 bar).
+         * `w: "full"` stretches the chart to the row's own width instead — a
+         * stacked bar only, since a circle has no free width (Vee warns and falls
+         * back to points on `pie`/`donut`).
+         */
+        w?: number | "full";
+        h?: number;
+    };
+}
+/** A menu section at a given submenu depth (0 = top level). */
+export declare class Section {
+    private readonly lines;
+    private readonly depth;
+    constructor(lines: string[], depth: number);
+    private prefix;
+    item(text: string, options?: ItemOptions): this;
+    separator(): this;
+    /** Adds an item and returns a `Section` for its submenu. */
+    submenu(text: string, options?: ItemOptions): Section;
+}
+/** The top-level menu: title line(s) plus a dropdown. */
+export declare class Menu {
+    private readonly titles;
+    private readonly body;
+    title(text: string, options?: ItemOptions): this;
+    get dropdown(): Section;
+    toString(): string;
+    print(): void;
+}
+export type WidgetTemplate = "stat" | "gauge" | "trend" | "list" | "board";
+export type WidgetStatus = "ok" | "warning" | "error";
+export type WidgetActionKind = "refresh" | "href" | "shortcut";
+export interface WidgetCardItem {
+    label: string;
+    value?: string;
+    symbol?: string;
+    tint?: Color;
+}
+export interface WidgetCardAction {
+    kind: WidgetActionKind;
+    label: string;
+    /** The URL to open, for `kind: "href"`. Scheme-filtered by Vee on parse. */
+    url?: string;
+    /** The Shortcut name to run, for `kind: "shortcut"`. */
+    name?: string;
+}
+export interface WidgetCardOptions {
+    template?: WidgetTemplate;
+    title?: string;
+    /** SF Symbol name for the glyph. */
+    symbol?: string;
+    tint?: Color;
+    /** The headline value, already formatted (e.g. `"$18.2k"`). */
+    value?: string;
+    caption?: string;
+    detail?: string;
+    status?: WidgetStatus;
+    /** `0…1`; clamped by Vee if out of range. */
+    progress?: number;
+    trend?: number[];
+    /** Rows for the `list`/`board` templates. */
+    items?: WidgetCardItem[];
+    /** Up to two are rendered as buttons; the templates decide which. */
+    actions?: WidgetCardAction[];
+    /** Seconds — a hint for the next widget reload. */
+    refreshAfter?: number;
+    /** Seconds — when the tile should show a stale treatment. */
+    staleAfter?: number;
+    /**
+     * An optional composable **layout tree** — the escape hatch alongside the
+     * five preset templates, for layouts the presets can't express (two columns,
+     * a date rail, activity rings, a KPI grid). Build it with the node helpers
+     * (`VStack`/`HStack`/`Text`/`Image`/`Gauge`/…). When present, Vee renders the
+     * tree instead of `template`. See docs/design/widget-surface-contract.md.
+     */
+    layout?: WidgetNode;
+}
+/** A font token, or an explicit point size (clamped 8…96) when a token won't fit. */
+export interface NodeFont {
+    size?: "caption2" | "caption" | "footnote" | "subheadline" | "body" | "headline" | "title3" | "title2" | "title" | "largeTitle";
+    pointSize?: number;
+    weight?: "regular" | "medium" | "semibold" | "bold";
+    design?: "default" | "rounded" | "monospaced" | "serif";
+}
+/** Per-element modifiers. Only bounded, SwiftUI-cheap options are exposed. */
+export interface NodeStyle {
+    font?: NodeFont;
+    tint?: Color;
+    /** Multiline text alignment. */
+    align?: "leading" | "center" | "trailing";
+    /** Uniform padding in points (clamped 0…64). */
+    padding?: number;
+    /** Maximum text lines (clamped 1…20). */
+    lineLimit?: number;
+    /** Keep numeric columns from jittering. */
+    monospacedDigit?: boolean;
+    /** Let a headline shrink to fit rather than truncate (clamped 0.3…1). */
+    minScale?: number;
+    /** Grow to fill available width (the only, bounded, width control). */
+    fill?: boolean;
+}
+export type NodeType = "vstack" | "hstack" | "zstack" | "grid" | "text" | "image" | "gauge" | "sparkline" | "spacer" | "divider";
+export interface WidgetNode {
+    type: NodeType;
+    text?: string;
+    /** SF Symbol name, for an `image` node (v1 renders SF Symbols only). */
+    symbol?: string;
+    /** `0…1` fill, for a `gauge` node. */
+    value?: number;
+    /** Series, for a `sparkline` node. */
+    values?: number[];
+    /** `"linear"` (default) or `"circular"`, for a `gauge` node. */
+    gaugeStyle?: "linear" | "circular";
+    /** Cross-axis alignment, for a container. */
+    align?: string;
+    /** Inter-child spacing, for a container. */
+    spacing?: number;
+    /** Column count, for a `grid` (default 2; clamped 1…4). */
+    columns?: number;
+    /** Minimum length, for a `spacer`. */
+    minLength?: number;
+    /** Families this node renders in (`small`/`medium`/`large`); absent = all. */
+    families?: Array<"small" | "medium" | "large">;
+    style?: NodeStyle;
+    children?: WidgetNode[];
+}
+/**
+ * The widget-mode payload (see `WidgetCardOptions`). Call `.toString()`/
+ * `.print()` exactly once per `VEE_TARGET=widget` run with the richest data
+ * available — each native template (small/medium/large) takes what fits.
+ */
+export declare class WidgetCard {
+    private readonly options;
+    constructor(options?: WidgetCardOptions);
+    toString(): string;
+    print(): void;
+}
+/** Builds a widget card. Equivalent to `new WidgetCard(options)`. */
+export declare function widgetCard(options?: WidgetCardOptions): WidgetCard;
+type ContainerOpts = {
+    align?: string;
+    spacing?: number;
+    families?: WidgetNode["families"];
+    style?: NodeStyle;
+};
+type LeafOpts = {
+    families?: WidgetNode["families"];
+    style?: NodeStyle;
+};
+/**
+ * Builders for the layout tree. Namespaced (`Node.VStack(…)`) so they don't
+ * collide with the card-level template builders (`Stat`/`Gauge`/…) and stay
+ * clearly node-level. Each returns a `WidgetNode`; `widgetCard({ layout })`
+ * serializes it in the canonical key order the three SDKs share.
+ */
+export declare const Node: {
+    /** A vertical stack. */
+    VStack: (children: WidgetNode[], opts?: ContainerOpts) => WidgetNode;
+    /** A horizontal stack — side-by-side regions (two columns, a date rail, a row of cells). */
+    HStack: (children: WidgetNode[], opts?: ContainerOpts) => WidgetNode;
+    /** A depth stack — overlays and rings (e.g. concentric gauges). */
+    ZStack: (children: WidgetNode[], opts?: ContainerOpts) => WidgetNode;
+    /** A grid of `columns` (default 2, clamped 1…4) — KPI boards. */
+    Grid: (children: WidgetNode[], opts?: ContainerOpts & {
+        columns?: number;
+    }) => WidgetNode;
+    /** A text run. */
+    Text: (text: string, opts?: LeafOpts) => WidgetNode;
+    /** An SF Symbol glyph (v1 renders SF Symbols only). */
+    Image: (symbol: string, opts?: LeafOpts) => WidgetNode;
+    /** A gauge — `linear` (default) or `circular`. `value` is `0…1`. */
+    Gauge: (value: number, opts?: {
+        gaugeStyle?: "linear" | "circular";
+    } & LeafOpts) => WidgetNode;
+    /** A dependency-free line chart from `values`. */
+    Sparkline: (values: number[], opts?: LeafOpts) => WidgetNode;
+    /** Flexible empty space. */
+    Spacer: (opts?: {
+        minLength?: number;
+        families?: WidgetNode["families"];
+    }) => WidgetNode;
+    /** A hairline divider. */
+    Divider: (opts?: {
+        families?: WidgetNode["families"];
+    }) => WidgetNode;
+};
+type TemplatelessOptions = Omit<WidgetCardOptions, "template">;
+/** Glyph, big `value` in `tint`, `title`/`caption`. The default template. */
+export declare function Stat(options: TemplatelessOptions): WidgetCard;
+/** Stat + a native gauge from `progress`. */
+export declare function Gauge(options: TemplatelessOptions): WidgetCard;
+/** Stat + a sparkline from `trend`. */
+export declare function Trend(options: TemplatelessOptions): WidgetCard;
+/** `title` header + `items` as rows. */
+export declare function List(options: TemplatelessOptions): WidgetCard;
+/** A compact grid of `items` as stat cells (KPI board). */
+export declare function Board(options: TemplatelessOptions): WidgetCard;
+/** Options for a JSON menu item.
+ *
+ * The JSON protocol carries a subset of the text protocol's parameters, so this
+ * is a distinct type rather than `ItemOptions`: an option JSON cannot express
+ * is a compile error here, not a key that is silently dropped on the way out.
+ */
+export interface JSONItemOptions {
+    color?: Color;
+    size?: number;
+    href?: string;
+    shell?: string;
+    params?: string[];
+    terminal?: boolean;
+    refresh?: boolean;
+    sfimage?: string;
+    disabled?: boolean;
+    checked?: boolean;
+    tooltip?: string;
+    header?: boolean;
+    accessory?: "leading" | "trailing";
+    sparkline?: number[];
+    /** Sparkline width in points; `"full"` stretches it to the row's width. */
+    /** @deprecated Use `accessoryWidth`. */
+    sparklineWidth?: number | "full";
+    /** Width for whichever accessory this item carries, or `"full"`. */
+    accessoryWidth?: number | "full";
+    /** Height for whichever accessory this item carries. */
+    accessoryHeight?: number;
+    sparklineHeight?: number;
+    sparklineColor?: Color;
+    toggle?: boolean;
+    slider?: {
+        min: number;
+        max: number;
+        value: number;
+    };
+    /** A completion fraction, clamped to `0…1` by Vee. */
+    progress?: number;
+    progressTrackColor?: Color;
+    /** Progress bar width in points; `"full"` stretches it to the row's width. */
+    progressWidth?: number | "full";
+    progressHeight?: number;
+    chart?: {
+        kind: "pie" | "donut" | "stackedbar";
+        values: number[];
+        labels?: string[];
+        colors?: Color[];
+        w?: number | "full";
+        h?: number;
+    };
+    /** An alternate row, shown while ⌥ is held. */
+    alternate?: JSONItem;
+}
+/** One item in a JSON menu: `JSONItemOptions` plus the structural keys. */
+export interface JSONItem extends JSONItemOptions {
+    text?: string;
+    separator?: boolean;
+    submenu?: JSONItem[];
+}
+/** A JSON menu section at a given submenu depth. Mirrors `Section`. */
+export declare class JSONSection {
+    private readonly items;
+    constructor(items: JSONItem[]);
+    item(text: string, options?: JSONItemOptions): this;
+    separator(): this;
+    /** Adds an item and returns a `JSONSection` for its submenu. */
+    submenu(text: string, options?: JSONItemOptions): JSONSection;
+}
+/** The top-level JSON menu: title line(s) plus a dropdown. Mirrors `Menu`. */
+export declare class JSONMenu {
+    private readonly titles;
+    private readonly body;
+    title(text: string, options?: JSONItemOptions): this;
+    get dropdown(): JSONSection;
+    toString(): string;
+    print(): void;
+}
+export {};

package/dist/vee.js

@@ -0,0 +1,356 @@
+// Vee plugin SDK — typed builders that emit the xbar/SwiftBar text format Vee
+// parses. Zero dependencies; runs directly on Node (which strips the types).
+// Vee's parser (LineParser.splitTextAndParams/parseParams) reads `\|`, `\n`,
+// and `\\` as escapes — for a literal `|` (which would otherwise be read as
+// the text/params delimiter) and a literal newline (which would otherwise
+// split a plugin's single stdout line into two corrupted ones). Order matters:
+// backslashes must be escaped first, or the backslash `escapeText` inserts for
+// `|`/newline would itself get re-escaped.
+function escapeText(value) {
+    return value.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\n/g, "\\n");
+}
+// The characters that force a value through the quoted path. `\s` here is the
+// reference definition the Python and Go SDKs mirror explicitly — each
+// language's own "whitespace" class differs at the edges (Python's adds
+// U+001C–U+001F, Go's `unicode.IsSpace` omits U+FEFF), so the set is written
+// out there rather than inherited.
+const NEEDS_QUOTE = /[\s|\\]/;
+function quote(value) {
+    const escaped = escapeText(value);
+    // Backslash also forces quoting: an unquoted (bare) value is never
+    // unescaped by the parser, so anything containing an escape must go through
+    // the quoted path, which is.
+    //
+    // A leading quote character forces it too: the parser decides a value is
+    // quoted by looking at its first character, so emitting `"a"` bare would
+    // round-trip back as `a` with the quotes eaten. Values that merely *contain*
+    // a quote are safe bare — only the first position is read as a delimiter.
+    if (NEEDS_QUOTE.test(value) || value.startsWith('"') || value.startsWith("'")) {
+        return `"${escaped.replace(/"/g, '\\"')}"`;
+    }
+    return escaped;
+}
+function encode(options) {
+    if (!options)
+        return "";
+    const parts = [];
+    const push = (key, value) => {
+        if (value !== undefined && value !== null)
+            parts.push(`${key}=${quote(String(value))}`);
+    };
+    push("color", options.color);
+    push("size", options.size);
+    push("font", options.font);
+    push("length", options.length);
+    push("trim", options.trim);
+    push("ansi", options.ansi);
+    push("emojize", options.emojize);
+    push("href", options.href);
+    if (options.shell !== undefined) {
+        push("shell", options.shell);
+        (options.params ?? []).forEach((p, i) => push(`param${i + 1}`, p));
+    }
+    push("terminal", options.terminal);
+    push("refresh", options.refresh);
+    push("dropdown", options.dropdown);
+    push("alternate", options.alternate);
+    push("disabled", options.disabled);
+    push("checked", options.checked);
+    push("key", options.key);
+    push("tooltip", options.tooltip);
+    push("image", options.image);
+    push("templateimage", options.templateImage);
+    push("sfimage", options.sfimage);
+    if (options.sfColor !== undefined) {
+        push("sfcolor", Array.isArray(options.sfColor) ? options.sfColor.join(",") : options.sfColor);
+    }
+    push("sfsize", options.sfSize);
+    push("sfconfig", options.sfConfig);
+    push("md", options.md);
+    push("badge", options.badge);
+    push("symbolize", options.symbolize);
+    push("webview", options.webview);
+    push("webvieww", options.webviewW);
+    push("webviewh", options.webviewH);
+    push("shortcut", options.shortcut);
+    push("header", options.header);
+    push("accessory", options.accessory);
+    if (options.sparkline !== undefined)
+        push("sparkline", options.sparkline.map(String).join(","));
+    push("sparklinecolor", options.sparklineColor);
+    if (options.toggle !== undefined)
+        push("toggle", options.toggle ? "on" : "off");
+    if (options.slider !== undefined) {
+        const s = options.slider;
+        push("slider", `${s.min},${s.max},${s.value}`);
+    }
+    if (options.progress !== undefined) {
+        const p = options.progress;
+        push("progress", typeof p === "number" ? String(p) : `${p.value},${p.max}`);
+    }
+    push("progresstrackcolor", options.progressTrackColor ?? options.trackColor);
+    if (options.chart !== undefined) {
+        const c = options.chart;
+        push(c.kind, c.values.map(String).join(","));
+        if (c.labels !== undefined)
+            push("chartlabels", c.labels.join(","));
+        if (c.colors !== undefined)
+            push("chartcolors", c.colors.join(","));
+    }
+    // One wire parameter sizes whichever accessory the row carries, so the
+    // per-accessory options above all funnel here. They stay separate in the API
+    // because a typed builder already knows which accessory you are describing —
+    // the ambiguity `accessoryw=` solves for hand-written lines cannot arise.
+    push("accessoryw", options.accessoryW ?? options.sparklineW ?? options.progressW ?? options.chart?.w);
+    push("accessoryh", options.accessoryH ?? options.sparklineH ?? options.progressH ?? options.chart?.h);
+    return parts.length ? " | " + parts.join(" ") : "";
+}
+/** A menu section at a given submenu depth (0 = top level). */
+export class Section {
+    lines;
+    depth;
+    constructor(lines, depth) {
+        this.lines = lines;
+        this.depth = depth;
+    }
+    prefix() {
+        return "-".repeat(this.depth * 2);
+    }
+    item(text, options) {
+        this.lines.push(this.prefix() + escapeText(text) + encode(options));
+        return this;
+    }
+    separator() {
+        this.lines.push(this.prefix() + "---");
+        return this;
+    }
+    /** Adds an item and returns a `Section` for its submenu. */
+    submenu(text, options) {
+        this.item(text, options);
+        return new Section(this.lines, this.depth + 1);
+    }
+}
+/** The top-level menu: title line(s) plus a dropdown. */
+export class Menu {
+    titles = [];
+    body = [];
+    title(text, options) {
+        this.titles.push(escapeText(text) + encode(options));
+        return this;
+    }
+    get dropdown() {
+        return new Section(this.body, 0);
+    }
+    toString() {
+        const head = this.titles.join("\n");
+        return this.body.length ? `${head}\n---\n${this.body.join("\n")}` : head;
+    }
+    print() {
+        process.stdout.write(this.toString() + "\n");
+    }
+}
+/**
+ * The widget-mode payload (see `WidgetCardOptions`). Call `.toString()`/
+ * `.print()` exactly once per `VEE_TARGET=widget` run with the richest data
+ * available — each native template (small/medium/large) takes what fits.
+ */
+export class WidgetCard {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    toString() {
+        const o = this.options;
+        const payload = { vee_widget: 1 };
+        const push = (key, value) => {
+            if (value !== undefined)
+                payload[key] = value;
+        };
+        push("template", o.template);
+        push("title", o.title);
+        push("symbol", o.symbol);
+        push("tint", o.tint);
+        push("value", o.value);
+        push("caption", o.caption);
+        push("detail", o.detail);
+        push("status", o.status);
+        push("progress", o.progress);
+        push("trend", o.trend);
+        push("items", o.items);
+        push("actions", o.actions);
+        push("refresh_after", o.refreshAfter);
+        push("stale_after", o.staleAfter);
+        push("layout", o.layout ? orderNode(o.layout) : undefined);
+        return JSON.stringify(payload);
+    }
+    print() {
+        process.stdout.write(this.toString() + "\n");
+    }
+}
+/** Builds a widget card. Equivalent to `new WidgetCard(options)`. */
+export function widgetCard(options) {
+    return new WidgetCard(options);
+}
+// ── Layout node serialization + builders ─────────────────────────────────────
+/** Rebuilds a node with keys in the canonical order the three SDKs share, so
+ *  output is byte-identical regardless of how the node object was constructed.
+ *  `undefined` keys are dropped; `0`/`false` are kept. */
+function orderNode(n) {
+    const o = {};
+    const put = (k, v) => { if (v !== undefined)
+        o[k] = v; };
+    put("type", n.type);
+    put("text", n.text);
+    put("symbol", n.symbol);
+    put("value", n.value);
+    put("values", n.values);
+    put("gauge_style", n.gaugeStyle);
+    put("align", n.align);
+    put("spacing", n.spacing);
+    put("columns", n.columns);
+    put("min_length", n.minLength);
+    put("families", n.families);
+    put("style", n.style ? orderStyle(n.style) : undefined);
+    put("children", n.children ? n.children.map(orderNode) : undefined);
+    return o;
+}
+function orderStyle(s) {
+    const o = {};
+    const put = (k, v) => { if (v !== undefined)
+        o[k] = v; };
+    put("font", s.font ? orderFont(s.font) : undefined);
+    put("tint", s.tint);
+    put("align", s.align);
+    put("padding", s.padding);
+    put("line_limit", s.lineLimit);
+    put("monospaced_digit", s.monospacedDigit);
+    put("min_scale", s.minScale);
+    put("fill", s.fill);
+    return o;
+}
+function orderFont(f) {
+    const o = {};
+    const put = (k, v) => { if (v !== undefined)
+        o[k] = v; };
+    put("size", f.size);
+    put("point_size", f.pointSize);
+    put("weight", f.weight);
+    put("design", f.design);
+    return o;
+}
+/**
+ * Builders for the layout tree. Namespaced (`Node.VStack(…)`) so they don't
+ * collide with the card-level template builders (`Stat`/`Gauge`/…) and stay
+ * clearly node-level. Each returns a `WidgetNode`; `widgetCard({ layout })`
+ * serializes it in the canonical key order the three SDKs share.
+ */
+export const Node = {
+    /** A vertical stack. */
+    VStack: (children, opts = {}) => ({ type: "vstack", children, ...opts }),
+    /** A horizontal stack — side-by-side regions (two columns, a date rail, a row of cells). */
+    HStack: (children, opts = {}) => ({ type: "hstack", children, ...opts }),
+    /** A depth stack — overlays and rings (e.g. concentric gauges). */
+    ZStack: (children, opts = {}) => ({ type: "zstack", children, ...opts }),
+    /** A grid of `columns` (default 2, clamped 1…4) — KPI boards. */
+    Grid: (children, opts = {}) => ({ type: "grid", children, ...opts }),
+    /** A text run. */
+    Text: (text, opts = {}) => ({ type: "text", text, ...opts }),
+    /** An SF Symbol glyph (v1 renders SF Symbols only). */
+    Image: (symbol, opts = {}) => ({ type: "image", symbol, ...opts }),
+    /** A gauge — `linear` (default) or `circular`. `value` is `0…1`. */
+    Gauge: (value, opts = {}) => ({ type: "gauge", value, ...opts }),
+    /** A dependency-free line chart from `values`. */
+    Sparkline: (values, opts = {}) => ({ type: "sparkline", values, ...opts }),
+    /** Flexible empty space. */
+    Spacer: (opts = {}) => ({ type: "spacer", ...opts }),
+    /** A hairline divider. */
+    Divider: (opts = {}) => ({ type: "divider", ...opts }),
+};
+/** Glyph, big `value` in `tint`, `title`/`caption`. The default template. */
+export function Stat(options) {
+    return new WidgetCard({ ...options, template: "stat" });
+}
+/** Stat + a native gauge from `progress`. */
+export function Gauge(options) {
+    return new WidgetCard({ ...options, template: "gauge" });
+}
+/** Stat + a sparkline from `trend`. */
+export function Trend(options) {
+    return new WidgetCard({ ...options, template: "trend" });
+}
+/** `title` header + `items` as rows. */
+export function List(options) {
+    return new WidgetCard({ ...options, template: "list" });
+}
+/** A compact grid of `items` as stat cells (KPI board). */
+export function Board(options) {
+    return new WidgetCard({ ...options, template: "board" });
+}
+// The key order every SDK emits, so the three produce byte-identical JSON.
+const JSON_ITEM_KEYS = [
+    "text", "separator", "color", "size", "href", "shell", "params", "terminal",
+    "refresh", "sfimage", "disabled", "checked", "tooltip", "header", "accessory",
+    "sparkline", "sparklineWidth", "sparklineHeight", "sparklineColor",
+    "accessoryWidth", "accessoryHeight",
+    "toggle", "slider", "progress", "progressTrackColor", "progressWidth",
+    "progressHeight", "chart", "submenu", "alternate",
+];
+/** Rebuilds an item with keys in the shared canonical order, dropping absent
+ *  ones and recursing into `submenu`/`alternate`. */
+function orderJSONItem(item) {
+    const out = {};
+    for (const key of JSON_ITEM_KEYS) {
+        const value = item[key];
+        if (value === undefined)
+            continue;
+        if (key === "submenu")
+            out[key] = value.map(orderJSONItem);
+        else if (key === "alternate")
+            out[key] = orderJSONItem(value);
+        else
+            out[key] = value;
+    }
+    return out;
+}
+/** A JSON menu section at a given submenu depth. Mirrors `Section`. */
+export class JSONSection {
+    items;
+    constructor(items) {
+        this.items = items;
+    }
+    item(text, options) {
+        this.items.push({ text, ...options });
+        return this;
+    }
+    separator() {
+        this.items.push({ separator: true });
+        return this;
+    }
+    /** Adds an item and returns a `JSONSection` for its submenu. */
+    submenu(text, options) {
+        const submenu = [];
+        this.items.push({ text, ...options, submenu });
+        return new JSONSection(submenu);
+    }
+}
+/** The top-level JSON menu: title line(s) plus a dropdown. Mirrors `Menu`. */
+export class JSONMenu {
+    titles = [];
+    body = [];
+    title(text, options) {
+        this.titles.push({ text, ...options });
+        return this;
+    }
+    get dropdown() {
+        return new JSONSection(this.body);
+    }
+    toString() {
+        const payload = { vee: 1, title: this.titles.map(orderJSONItem) };
+        if (this.body.length)
+            payload.items = this.body.map(orderJSONItem);
+        return JSON.stringify(payload);
+    }
+    print() {
+        process.stdout.write(this.toString() + "\n");
+    }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@navbytes/vee",
+  "version": "0.3.0",
+  "type": "module",
+  "description": "Typed builders for authoring Vee plugins — the xbar/SwiftBar text protocol, the structured-JSON menu format, and widget cards.",
+  "keywords": [
+    "vee",
+    "xbar",
+    "swiftbar",
+    "menubar",
+    "macos",
+    "plugin"
+  ],
+  "license": "MIT",
+  "author": "Naveen Kumar",
+  "homepage": "https://vee.navbytes.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/navbytes/vee.git",
+    "directory": "plugins/typescript"
+  },
+  "bugs": "https://github.com/navbytes/vee/issues",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/vee.d.ts",
+      "default": "./dist/vee.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "npx -y -p typescript@5 tsc -p tsconfig.build.json",
+    "test": "node --test \"test/**/*.test.ts\"",
+    "check:dist": "node scripts/check-dist.mjs",
+    "build:fixtures": "for f in examples/*.ts; do node \"$f\" > \"../fixtures/$(basename \"${f%.ts}\").txt\"; done",
+    "prepublishOnly": "npm run build && npm run check:dist"
+  }
+}