@nighthawk.hq/macro-sdk 0.1.0

package/build/index.js

@@ -0,0 +1,49 @@
+import { build } from 'esbuild';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const MANIFEST = JSON.parse(readFileSync(join(HERE, '..', 'runtime-manifest.json'), 'utf8'));
+const SPECIFIER = '@nighthawk.hq/macro-sdk';
+const MAX_BYTES = 256 * 1024;
+
+function externalSdkPlugin() {
+  const shim =
+    'const s = globalThis.__nhSdk;\n' +
+    "if (!s) throw new Error('Nighthawk SDK runtime not present in this realm');\n" +
+    MANIFEST.map((n) => `export const ${n} = s.${n};`).join('\n') +
+    '\n';
+  return {
+    name: 'nighthawk-sdk-external',
+    setup(b) {
+      b.onResolve({ filter: /^@nighthawk\.hq\/macro-sdk$/ }, () => ({
+        path: SPECIFIER,
+        namespace: 'nh-sdk',
+      }));
+      b.onLoad({ filter: /.*/, namespace: 'nh-sdk' }, () => ({ contents: shim, loader: 'js' }));
+    },
+  };
+}
+
+export async function buildMacro({ id, entry, outDir }) {
+  const outfile = join(outDir ?? 'dist', `${id}.js`);
+  await build({
+    entryPoints: [entry],
+    bundle: true,
+    format: 'iife',
+    target: 'es2022',
+    platform: 'neutral',
+    outfile,
+    plugins: [externalSdkPlugin()],
+    logLevel: 'info',
+  });
+  const bytes = readFileSync(outfile).length;
+  if (bytes > MAX_BYTES) {
+    throw new Error(
+      `macro "${id}" bundle is ${bytes}B (> ${MAX_BYTES}B) — the SDK may not be externalized`
+    );
+  }
+  console.log(`[macro:${id}] built → ${outfile} (${bytes}B)`);
+  return { outfile, bytes };
+}

package/lib/decorators.d.ts

@@ -0,0 +1,31 @@
+import type { MacroBase } from './macro-base';
+import type { Target } from './types';
+export type ActionOptions = {
+    id: string;
+    bindable?: boolean;
+    label?: string;
+    suggestedKey?: string;
+};
+type MacroOpts = {
+    id: string;
+    schemaVersion?: number;
+    target?: Target;
+    tickTimeoutMs?: number;
+};
+type AnyCtor = abstract new (...args: never[]) => MacroBase;
+export declare function Macro(opts: MacroOpts): <T extends AnyCtor>(value: T, context: ClassDecoratorContext) => T;
+export declare function OnStart(): (_method: unknown, context: ClassMethodDecoratorContext) => void;
+export declare function OnStop(): (_method: unknown, context: ClassMethodDecoratorContext) => void;
+export declare function OnTick(hz: number): (_method: unknown, context: ClassMethodDecoratorContext) => void;
+export declare function Action(action: string | ActionOptions): (_method: unknown, context: ClassMethodDecoratorContext) => void;
+export declare function Panel(meta: {
+    id: string;
+    title: string;
+}): (_method: unknown, context: ClassMethodDecoratorContext) => void;
+/**
+ * Marks a method that returns the macro's in-game overlay HUD layout — a compact
+ * view drawn over the game, separate from the tabbed @Panel views. A macro may
+ * declare several @Overlay methods; their widgets are concatenated into one HUD.
+ */
+export declare function Overlay(): (_method: unknown, context: ClassMethodDecoratorContext) => void;
+export {};

package/lib/geometry.d.ts

@@ -0,0 +1,21 @@
+export type Point = {
+    x: number;
+    y: number;
+};
+export type Region = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+export type RegionRatio = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+export type ColorRGB = {
+    r: number;
+    g: number;
+    b: number;
+};

package/lib/index.d.ts

@@ -0,0 +1,19 @@
+export { Macro, OnStart, OnStop, OnTick, Action, Panel, Overlay } from './decorators';
+export type { ActionOptions } from './decorators';
+export { MacroBase } from './macro-base';
+export { robloxTarget, processTarget } from './targets';
+export { region, ratio, point, color, number, string, boolean, select, pixelColor, findColor, defaultsOf, } from './settings';
+export type { Setting, SettingMap, RegionSetting, RatioSetting, PointSetting, ColorSetting, NumberSetting, StringSetting, BooleanSetting, SelectSetting, PixelColorSetting, PixelColorValue, FindColorSetting, FindColorValue, } from './settings';
+export { Group, Row, Stat, Chip, Divider, Button, Text, Meter, Image } from './widgets';
+export type { Widget, PanelDeclaration, WidgetTone, WidgetSize, WidgetAlign, WidgetWeight, } from './panel-types';
+export { Roblox, Instance } from './roblox/index';
+export type { RobloxOffsets } from './roblox/offsets';
+export type { UDim2, Vector3, TreeNode } from './roblox/instance';
+export { offsetsFromDump } from './roblox/offsets-dump';
+export type { RobloxOffsetDump } from './roblox/offsets-dump';
+export { Address } from './process/address';
+export { struct, f } from './process/struct';
+export type { StructSpec } from './process/struct';
+export type { ProcessAccess } from './process/process-access';
+export type { Point, Region, RegionRatio, ColorRGB } from './geometry';
+export type { ScriptCtx, Target, GameId, WindowTarget, ProcessTarget, PackageDeclaration, PixelReadout, MouseButton, } from './types';

package/lib/macro-base.d.ts

@@ -0,0 +1,23 @@
+import type { ProcessAccess } from './process/process-access';
+import type { ScriptCtx } from './types';
+declare const CTX: unique symbol;
+export declare abstract class MacroBase<State extends Record<string, unknown> = Record<string, unknown>> {
+    /** Set by the generated declaration before each lifecycle/tick/action call. */
+    private [CTX];
+    /** Initial state, published to the UI when the macro starts. */
+    initialState?: State;
+    /**
+     * @internal Bind the live ctx; returns the previous binding so callers can
+     * restore it (LIFO) — an action interleaving a suspended async tick must not
+     * clobber the tick's ctx.
+     */
+    __bind(ctx: ScriptCtx | undefined): ScriptCtx | undefined;
+    protected get ctx(): ScriptCtx;
+    protected get process(): ProcessAccess | undefined;
+    protected get input(): ScriptCtx['input'];
+    protected get log(): ScriptCtx['log'];
+    protected get settings(): Record<string, unknown>;
+    protected get state(): State;
+    protected setState(partial: Partial<State>): void;
+}
+export {};

package/lib/panel-types.d.ts

@@ -0,0 +1,61 @@
+export type WidgetTone = 'default' | 'ok' | 'warn' | 'err' | 'info';
+export type WidgetSize = 'sm' | 'md' | 'lg';
+export type WidgetAlign = 'start' | 'center' | 'end';
+export type WidgetWeight = 'normal' | 'medium' | 'bold';
+export type Widget = {
+    kind: 'stat';
+    label: string;
+    bind: string;
+    tone?: WidgetTone;
+    size?: WidgetSize;
+    align?: WidgetAlign;
+} | {
+    kind: 'meter';
+    label: string;
+    bind: string;
+    min: number;
+    max: number;
+    tone?: WidgetTone;
+    colorMode?: 'auto' | 'tone';
+} | {
+    kind: 'chip';
+    label: string;
+    bind: string;
+    tone?: WidgetTone;
+    size?: WidgetSize;
+} | {
+    kind: 'button';
+    label: string;
+    action: string;
+    payload?: unknown;
+    variant?: 'default' | 'outline' | 'destructive' | 'ghost';
+    size?: WidgetSize;
+} | {
+    kind: 'divider';
+} | {
+    kind: 'group';
+    title?: string;
+    children: Widget[];
+} | {
+    kind: 'row';
+    children: Widget[];
+    align?: WidgetAlign;
+    gap?: 'tight' | 'normal' | 'wide';
+} | {
+    kind: 'text';
+    value?: string;
+    bind?: string;
+    tone?: WidgetTone;
+    size?: WidgetSize;
+    align?: WidgetAlign;
+    weight?: WidgetWeight;
+    mono?: boolean;
+} | {
+    kind: 'image';
+    bind: string;
+};
+export type PanelDeclaration = {
+    id: string;
+    title: string;
+    layout: Widget[];
+};

package/lib/process/address.d.ts

@@ -0,0 +1,10 @@
+export declare class Address {
+    readonly value: bigint;
+    constructor(value: bigint | number);
+    add(offset: number | bigint): Address;
+    sub(offset: number | bigint): Address;
+    equals(other: Address): boolean;
+    isNull(): boolean;
+    toBigInt(): bigint;
+    toString(): string;
+}

package/lib/process/process-access.d.ts

@@ -0,0 +1,23 @@
+import type { Address } from './address';
+import type { StructSpec } from './struct';
+export interface ProcessAccess {
+    attached(): boolean;
+    moduleBase(name?: string): Address | null;
+    readBytes(addr: Address, size: number): Buffer | null;
+    readU8(addr: Address): number | null;
+    readI8(addr: Address): number | null;
+    readU16(addr: Address): number | null;
+    readI16(addr: Address): number | null;
+    readU32(addr: Address): number | null;
+    readI32(addr: Address): number | null;
+    readU64(addr: Address): bigint | null;
+    readI64(addr: Address): bigint | null;
+    readF32(addr: Address): number | null;
+    readF64(addr: Address): number | null;
+    readBool(addr: Address): boolean | null;
+    readPointer(addr: Address): Address | null;
+    readStruct<T>(addr: Address, spec: StructSpec<T>): T | null;
+    readString(addr: Address, len: number, encoding?: BufferEncoding): string | null;
+    readCString(addr: Address, maxLen?: number, encoding?: BufferEncoding): string | null;
+    walk(base: Address, offsets: readonly number[]): Address | null;
+}

package/lib/process/struct.d.ts

@@ -0,0 +1,29 @@
+export type StructSpec<T> = {
+    readonly size: number;
+    read(buf: Buffer, base?: number): T;
+};
+type FieldReader<T> = (buf: Buffer, off: number) => T;
+type Field<T> = {
+    offset: number;
+    size: number;
+    read: FieldReader<T>;
+};
+export declare const f: {
+    u8: (offset: number) => Field<number>;
+    i8: (offset: number) => Field<number>;
+    u16: (offset: number) => Field<number>;
+    i16: (offset: number) => Field<number>;
+    u32: (offset: number) => Field<number>;
+    i32: (offset: number) => Field<number>;
+    u64: (offset: number) => Field<bigint>;
+    i64: (offset: number) => Field<bigint>;
+    f32: (offset: number) => Field<number>;
+    f64: (offset: number) => Field<number>;
+    bool: (offset: number) => Field<boolean>;
+};
+type Shape = Record<string, Field<unknown>>;
+type Decoded<S extends Shape> = {
+    [K in keyof S]: S[K] extends Field<infer T> ? T : never;
+};
+export declare function struct<S extends Shape>(fields: S): StructSpec<Decoded<S>>;
+export {};

package/lib/roblox/index.d.ts

@@ -0,0 +1,32 @@
+import { Address } from '../process/address';
+import type { ProcessAccess } from '../process/process-access';
+import { Instance } from './instance';
+import type { RobloxOffsets } from './offsets';
+export declare class Roblox {
+    #private;
+    readonly process: ProcessAccess;
+    readonly offsets: RobloxOffsets;
+    private constructor();
+    static bind(process: ProcessAccess, offsets: RobloxOffsets): Roblox;
+    invalidateCache(): void;
+    /**
+     * Sanity-check the offsets against live memory: resolve the DataModel and
+     * confirm it plus the Workspace/Players services look right. Catches a stale
+     * offset table after a Roblox build bump, instead of silently reading garbage.
+     */
+    validate(): {
+        ok: boolean;
+        problems: string[];
+    };
+    dataModel(): Instance | null;
+    service(name: string): Instance | null;
+    workspace(): Instance | null;
+    players(): Instance | null;
+    localPlayer(): Instance | null;
+    playerGui(): Instance | null;
+    character(): Instance | null;
+    equippedTool(): Instance | null;
+}
+export { Instance, Address };
+export type { RobloxOffsets };
+export type { UDim2, Vector3, TreeNode } from './instance';

package/lib/roblox/instance.d.ts

@@ -0,0 +1,64 @@
+import { Address } from '../process/address';
+import type { ProcessAccess } from '../process/process-access';
+import type { RobloxOffsets } from './offsets';
+/** A Roblox UDim2 axis pair: `scale` (0..1 fraction of parent) + `offset` (px). */
+export type UDim2 = {
+    /** X scale, 0..1. */
+    sx: number;
+    /** X offset, px. */
+    ox: number;
+    /** Y scale, 0..1. */
+    sy: number;
+    /** Y offset, px. */
+    oy: number;
+};
+/** A 3D world position. */
+export type Vector3 = {
+    x: number;
+    y: number;
+    z: number;
+};
+/** A serializable snapshot of an instance subtree (see Instance.snapshot). */
+export type TreeNode = {
+    name: string;
+    className: string;
+    children: TreeNode[];
+};
+export declare class Instance {
+    #private;
+    readonly address: Address;
+    constructor(address: Address, proc: ProcessAccess, off: RobloxOffsets);
+    name(): string;
+    className(): string;
+    text(): string;
+    /** A *Value object's `.Value` string (StringValue, etc.) — read inline at +Value. */
+    value(): string;
+    readF32At(offset: number): number | null;
+    readF64At(offset: number): number | null;
+    readI32At(offset: number): number | null;
+    readU64At(offset: number): bigint | null;
+    readBoolAt(offset: number): boolean | null;
+    readPointerAt(offset: number): Address | null;
+    /** Read an inline Roblox std::string at this instance + offset. */
+    readStringAt(offset: number): string | null;
+    /** A BasePart's world position (BasePart → Primitive → Position). Null without spatial offsets. */
+    worldPosition(): Vector3 | null;
+    /** Structured snapshot of this subtree, `depth` levels of descendants deep. */
+    snapshot(depth?: number): TreeNode;
+    /** Pretty-printed `name : ClassName` tree, for exploring an unfamiliar game. */
+    tree(depth?: number): string;
+    parent(): Instance | null;
+    children(): Instance[];
+    findFirstChild(name: string): Instance | null;
+    findFirstChildOfClass(className: string): Instance | null;
+    /** Frame/TextLabel `.Visible`. Returns null if the read fails. */
+    visible(): boolean | null;
+    /** ScreenGui `.Enabled`. Returns null if the read fails. */
+    enabled(): boolean | null;
+    /** GuiObject `.Position` as a UDim2. Returns null if the read fails. */
+    position(): UDim2 | null;
+    /** GuiObject `.Size` as a UDim2. Returns null if the read fails. */
+    size(): UDim2 | null;
+    findFirstDescendant(name: string, maxDepth?: number): Instance | null;
+    walk(path: string): Instance | null;
+}

package/lib/roblox/offsets-dump.d.ts

@@ -0,0 +1,6 @@
+import type { RobloxOffsets } from './offsets';
+export type RobloxOffsetDump = {
+    'Roblox Version'?: string;
+    Offsets: Record<string, Record<string, number> | undefined>;
+};
+export declare function offsetsFromDump(dump: RobloxOffsetDump): RobloxOffsets;

package/lib/roblox/offsets.d.ts

@@ -0,0 +1,20 @@
+export type RobloxOffsets = {
+    FakeDataModelPointer: number;
+    FakeDataModelToDataModel: number;
+    Name: number;
+    Parent: number;
+    Children: number;
+    ClassDescriptor: number;
+    ClassDescriptorToClassName: number;
+    StringLength: number;
+    Value: number;
+    LocalPlayer: number;
+    TextLabelText: number;
+    FramePositionX: number;
+    FrameSizeX: number;
+    FrameVisible: number;
+    TextLabelVisible: number;
+    ScreenGuiEnabled: number;
+    Primitive?: number;
+    PrimitivePosition?: number;
+};

package/lib/settings.d.ts

@@ -0,0 +1,52 @@
+import type { Point, Region, RegionRatio } from './geometry';
+type Base<K extends string, T> = {
+    kind: K;
+    label: string;
+    description?: string;
+    default: T;
+};
+export type RegionSetting = Base<'region', Region>;
+export type RatioSetting = Base<'ratio', RegionRatio>;
+export type PointSetting = Base<'point', {
+    x: number;
+    y: number;
+}>;
+export type ColorSetting = Base<'color', string> & {
+    tolerance?: number;
+};
+export type NumberSetting = Base<'number', number> & {
+    min?: number;
+    max?: number;
+    step?: number;
+};
+export type StringSetting = Base<'string', string>;
+export type BooleanSetting = Base<'boolean', boolean>;
+export type SelectSetting<T extends string = string> = Base<'select', T> & {
+    options: readonly T[];
+};
+export type PixelColorValue = {
+    point: Point;
+    color: string;
+    tolerance?: number;
+};
+export type PixelColorSetting = Base<'pixelColor', PixelColorValue>;
+export type FindColorValue = {
+    rect: Region;
+    color: string;
+    tolerance?: number;
+};
+export type FindColorSetting = Base<'findColor', FindColorValue>;
+export type Setting = RegionSetting | RatioSetting | PointSetting | ColorSetting | NumberSetting | StringSetting | BooleanSetting | SelectSetting | PixelColorSetting | FindColorSetting;
+export type SettingMap = Record<string, Setting>;
+export declare const region: (s: Omit<RegionSetting, "kind">) => RegionSetting;
+export declare const ratio: (s: Omit<RatioSetting, "kind">) => RatioSetting;
+export declare const point: (s: Omit<PointSetting, "kind">) => PointSetting;
+export declare const color: (s: Omit<ColorSetting, "kind">) => ColorSetting;
+export declare const number: (s: Omit<NumberSetting, "kind">) => NumberSetting;
+export declare const string: (s: Omit<StringSetting, "kind">) => StringSetting;
+export declare const boolean: (s: Omit<BooleanSetting, "kind">) => BooleanSetting;
+export declare const select: <T extends string>(s: Omit<SelectSetting<T>, "kind">) => SelectSetting<T>;
+export declare const pixelColor: (s: Omit<PixelColorSetting, "kind">) => PixelColorSetting;
+export declare const findColor: (s: Omit<FindColorSetting, "kind">) => FindColorSetting;
+export declare function defaultsOf<M extends SettingMap>(map: M): Record<string, unknown>;
+export {};

package/lib/targets.d.ts

@@ -0,0 +1,9 @@
+import type { ProcessTarget } from './types';
+export declare function processTarget(opts: {
+    processName: string;
+    moduleName?: string;
+    expectedVersion?: string;
+}): ProcessTarget;
+export declare function robloxTarget(opts?: {
+    expectedVersion?: string;
+}): ProcessTarget;

package/lib/types.d.ts

@@ -0,0 +1,118 @@
+import type { ColorRGB, Point, Region } from './geometry';
+import type { PanelDeclaration, Widget } from './panel-types';
+import type { ProcessAccess } from './process/process-access';
+import type { RobloxOffsets } from './roblox/offsets';
+import type { SettingMap } from './settings';
+export type PixelReadout = ColorRGB & {
+    hex: string;
+};
+export type MouseButton = 'left' | 'right' | 'middle';
+export type ScriptCtx = {
+    settings: Record<string, unknown>;
+    state: {
+        get(): Record<string, unknown>;
+        set(partial: Record<string, unknown>): void;
+    };
+    signal: AbortSignal;
+    sleep(ms: number): Promise<void>;
+    /** Wall-clock time in milliseconds (host-mediated; equivalent to `Date.now()`). */
+    now(): number;
+    screen: {
+        captureRegion(name: string): Promise<Buffer>;
+        pixelAt(name: string): Promise<PixelReadout>;
+        pixelAtPoint(point: Point): Promise<PixelReadout>;
+        pixelAtRatio(rx: number, ry: number): Promise<PixelReadout>;
+        pixelMatches(settingName: string): Promise<boolean>;
+        pixelMatches(name: string, hex: string, tolerance?: number): Promise<boolean>;
+        pixelMatchesAt(point: Point, hex: string, tolerance?: number): Promise<boolean>;
+        findColor(settingName: string): Promise<Array<{
+            x: number;
+            y: number;
+            distance: number;
+        }>>;
+        findColor(regionName: string, hex: string, opts?: {
+            tolerance?: number;
+            limit?: number;
+            step?: number;
+        }): Promise<Array<{
+            x: number;
+            y: number;
+            distance: number;
+        }>>;
+    };
+    input: {
+        click(name: string, button?: MouseButton): Promise<void>;
+        clickAt(point: Point, button?: MouseButton): Promise<void>;
+        clickRatio(rx: number, ry: number, button?: MouseButton): Promise<void>;
+        move(name: string): Promise<void>;
+        moveAt(point: Point): Promise<void>;
+        mouseDown(button: MouseButton): Promise<void>;
+        mouseUp(button: MouseButton): Promise<void>;
+        tapKey(key: string): Promise<void>;
+        holdKey(key: string, ms: number): Promise<void>;
+        releaseAll(): Promise<void>;
+    };
+    color: {
+        distance(a: string | ColorRGB, b: string | ColorRGB): number;
+        matches(a: string | ColorRGB, b: string | ColorRGB, tolerance?: number): boolean;
+        hexToRgb(hex: string): ColorRGB;
+        rgbToHex(rgb: ColorRGB): string;
+    };
+    log: {
+        trace(msg: string, data?: unknown): void;
+        debug(msg: string, data?: unknown): void;
+        info(msg: string, data?: unknown): void;
+        warn(msg: string, data?: unknown): void;
+        error(msg: string, data?: unknown): void;
+        success(msg: string, data?: unknown): void;
+    };
+    invoke(actionName: string, payload?: unknown): Promise<unknown>;
+    process?: ProcessAccess;
+    /** Game memory offsets, fetched per game build and injected by the runtime. */
+    offsets: RobloxOffsets;
+};
+/** Identifies which game an offset set belongs to, so the runtime knows which
+ * table to fetch and inject as `ctx.offsets`. Roblox is the only game today. */
+export type GameId = 'roblox';
+export type WindowTarget = {
+    kind: 'window';
+    titlePattern: RegExp;
+    referenceSize: {
+        w: number;
+        h: number;
+    };
+};
+export type ProcessTarget = {
+    kind: 'process';
+    processName?: string;
+    moduleName?: string;
+    expectedVersion?: string;
+    game?: GameId;
+};
+export type Target = WindowTarget | ProcessTarget;
+export type PackageDeclaration = {
+    id: string;
+    schemaVersion: number;
+    target?: Target;
+    state?: Record<string, unknown>;
+    settings?: SettingMap;
+    macro?: {
+        onStart?: (ctx: ScriptCtx) => Promise<void> | void;
+        tick?: (ctx: ScriptCtx) => Promise<void> | void;
+        onStop?: (ctx: ScriptCtx) => Promise<void> | void;
+        pollMs?: number;
+        tickTimeoutMs?: number;
+    };
+    panels?: PanelDeclaration[];
+    /** Combined in-game overlay HUD layout (concatenation of all @Overlay methods). */
+    overlay?: Widget[];
+    actions?: Record<string, (ctx: ScriptCtx, payload?: unknown) => Promise<unknown> | unknown>;
+    actionMeta?: Record<string, {
+        label?: string;
+        bindable?: boolean;
+        suggestedKey?: string;
+    }>;
+    debug?: Record<string, (ctx: ScriptCtx) => unknown>;
+    migrations?: Record<number, (old: Record<string, unknown>) => Record<string, unknown>>;
+};
+export type { Region };

package/lib/widgets.d.ts

@@ -0,0 +1,41 @@
+import type { Widget, WidgetAlign, WidgetSize, WidgetTone, WidgetWeight } from './panel-types';
+type StatOpts = {
+    tone?: WidgetTone;
+    size?: WidgetSize;
+    align?: WidgetAlign;
+};
+export declare const Stat: (label: string, bind: string, opts?: StatOpts) => Widget;
+type ChipOpts = {
+    tone?: WidgetTone;
+    size?: WidgetSize;
+};
+export declare const Chip: (label: string, bind: string, opts?: ChipOpts) => Widget;
+type ButtonOpts = {
+    payload?: unknown;
+    variant?: 'default' | 'outline' | 'destructive' | 'ghost';
+    size?: WidgetSize;
+};
+export declare const Button: (label: string, action: string, opts?: ButtonOpts) => Widget;
+export declare const Divider: () => Widget;
+export declare const Group: (title: string, children: Widget[]) => Widget;
+type RowOpts = {
+    align?: WidgetAlign;
+    gap?: 'tight' | 'normal' | 'wide';
+};
+export declare const Row: (children: Widget[], opts?: RowOpts) => Widget;
+type TextOpts = {
+    bind?: string;
+    tone?: WidgetTone;
+    size?: WidgetSize;
+    align?: WidgetAlign;
+    weight?: WidgetWeight;
+    mono?: boolean;
+};
+export declare const Text: (value: string, opts?: TextOpts) => Widget;
+type MeterOpts = {
+    tone?: WidgetTone;
+    colorMode?: 'auto' | 'tone';
+};
+export declare const Meter: (label: string, bind: string, min: number, max: number, opts?: MeterOpts) => Widget;
+export declare const Image: (bind: string) => Widget;
+export {};

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@nighthawk.hq/macro-sdk",
+  "version": "0.1.0",
+  "description": "Nighthawk macro author SDK — types only. Runtime is provided by the host.",
+  "type": "module",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": { "types": "./lib/index.d.ts", "default": "./stub.js" },
+    "./build": "./build/index.js"
+  },
+  "files": ["lib/**/*.d.ts", "stub.js", "build/index.js", "runtime-manifest.json"],
+  "scripts": {
+    "test": "node --test test/shim.test.mjs"
+  },
+  "dependencies": {
+    "esbuild": "^0.24.0"
+  }
+}

package/runtime-manifest.json

@@ -0,0 +1,38 @@
+[
+  "Action",
+  "Address",
+  "Button",
+  "Chip",
+  "Divider",
+  "Group",
+  "Image",
+  "Instance",
+  "Macro",
+  "MacroBase",
+  "Meter",
+  "OnStart",
+  "OnStop",
+  "OnTick",
+  "Overlay",
+  "Panel",
+  "Roblox",
+  "Row",
+  "Stat",
+  "Text",
+  "boolean",
+  "color",
+  "defaultsOf",
+  "f",
+  "findColor",
+  "number",
+  "offsetsFromDump",
+  "pixelColor",
+  "point",
+  "processTarget",
+  "ratio",
+  "region",
+  "robloxTarget",
+  "select",
+  "string",
+  "struct"
+]

package/stub.js

@@ -0,0 +1,4 @@
+throw new Error(
+  'Nighthawk SDK runtime is provided by the host, not by this package. ' +
+    'Macros must be built with @nighthawk.hq/macro-sdk/build, which externalizes this import.'
+);