@nighthawk.hq/macro-sdk 0.3.0 → 0.4.0

package/lib/index.d.ts

@@ -8,6 +8,7 @@ export type { Setting, SettingMap, SettingGroup, RegionSetting, RatioSetting, Po
 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nighthawk.hq/macro-sdk",
-  "version": "0.3.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",