@nighthawk.hq/macro-sdk 0.2.0 → 0.4.0

package/lib/index.d.ts

@@ -3,11 +3,12 @@ export { Macro, OnStart, OnStop, OnTick, Action, Panel, Overlay } from './decora
 export type { ActionOptions } from './decorators';
 export { MacroBase } from './macro-base';
 export { robloxTarget } 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 { region, ratio, point, color, number, string, boolean, select, pixelColor, findColor, group, defaultsOf, } from './settings';
+export type { Setting, SettingMap, SettingGroup, 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 { RobloxValidation } from './roblox/index';
 export type { RobloxOffsets } from './roblox/offsets';
 export type { UDim2, Vector3, TreeNode } from './roblox/instance';
 export { offsetsFromDump } from './roblox/offsets-dump';

package/lib/roblox/index.d.ts

@@ -2,6 +2,18 @@ import { Address } from '../process/address';
 import type { ProcessAccess } from '../process/process-access';
 import { Instance } from './instance';
 import type { RobloxOffsets } from './offsets';
+/**
+ * Result of {@link Roblox.validate}. A discriminated union so the caller gets a single,
+ * ready-to-surface, user-facing `reason` for the failure — no macro has to author its
+ * own wording — while `problems` carries the diagnostic detail for logs.
+ */
+export type RobloxValidation = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+    problems: string[];
+};
 export declare class Roblox {
     #private;
     readonly process: ProcessAccess;
@@ -10,14 +22,13 @@ export declare class Roblox {
     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.
+     * Check the live game state + offsets and, on failure, return the real user-facing
+     * `reason` for it — so a macro just surfaces `check.reason` instead of authoring its
+     * own wording. The three failure modes are distinct: not attached (Roblox closed),
+     * attached but no DataModel (at the menu / still loading), and a resolved DataModel
+     * whose shape is wrong (offsets stale after a Roblox build bump).
      */
-    validate(): {
-        ok: boolean;
-        problems: string[];
-    };
+    validate(): RobloxValidation;
     dataModel(): Instance | null;
     service(name: string): Instance | null;
     workspace(): Instance | null;

package/lib/settings.d.ts

@@ -1,9 +1,14 @@
 import type { Point, Region, RegionRatio } from './geometry';
+export type SettingGroup = {
+    label: string;
+    collapsed?: boolean;
+};
 type Base<K extends string, T> = {
     kind: K;
     label: string;
     description?: string;
     default: T;
+    group?: SettingGroup;
 };
 export type RegionSetting = Base<'region', Region>;
 export type RatioSetting = Base<'ratio', RegionRatio>;
@@ -48,5 +53,8 @@ export declare const boolean: (s: Omit<BooleanSetting, "kind">) => BooleanSettin
 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 group<M extends SettingMap>(label: string, settings: M, opts?: {
+    collapsed?: boolean;
+}): M;
 export declare function defaultsOf<M extends SettingMap>(map: M): Record<string, unknown>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nighthawk.hq/macro-sdk",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "packageManager": "pnpm@10.34.1",
   "description": "Nighthawk macro author SDK — types only. Runtime is provided by the host.",
   "type": "module",
@@ -10,10 +10,18 @@
   },
   "types": "./lib/index.d.ts",
   "exports": {
-    ".": { "types": "./lib/index.d.ts", "default": "./stub.js" },
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./stub.js"
+    },
     "./build": "./build/index.js"
   },
-  "files": ["lib/**/*.d.ts", "stub.js", "build/index.js", "runtime-manifest.json"],
+  "files": [
+    "lib/**/*.d.ts",
+    "stub.js",
+    "build/index.js",
+    "runtime-manifest.json"
+  ],
   "scripts": {
     "generate": "node scripts/generate.mjs",
     "test": "node --test test/shim.test.mjs"

package/runtime-manifest.json

@@ -27,6 +27,7 @@
     "defaultsOf",
     "f",
     "findColor",
+    "group",
     "number",
     "offsetsFromDump",
     "pixelColor",