whitemagic/openspec/changes/whitemagic-foundation/specs/high-level-api/spec.md

ADDED Requirements

Requirement: Remote pointer indexer

WhiteMagic SHALL expose a RemotePointer obtained by indexing the memory facade with an address, offering read/write/execute operations relative to that base address.

Scenario: read via indexer

• WHEN sharp[addr].Read<int>(offset) is called
• THEN it MUST read an int at addr + offset

Scenario: write via indexer

• WHEN sharp[addr].WriteString("text") is called
• THEN the string MUST be written starting at addr

Requirement: Module and function access

WhiteMagic SHALL expose modules and their exported functions by name, allowing a resolved function to be executed with a calling convention and arguments.

Scenario: resolve function by name

• WHEN sharp["user32"]["MessageBoxA"] is resolved
• THEN it MUST return a function bound to the export address of MessageBoxA in user32

Scenario: execute resolved function

• WHEN a resolved function is executed with a calling convention and arguments
• THEN it MUST invoke the target through the chosen execution strategy with those arguments

Requirement: PEB and TEB access

WhiteMagic SHALL expose managed reads of the target's Process Environment Block and a thread's Thread Environment Block.

Scenario: read PEB field

• WHEN a PEB field (e.g. being-debugged flag) is read
• THEN it MUST reflect the target's actual PEB value

Scenario: read TEB field

• WHEN a TEB field is read for a given thread
• THEN it MUST reflect that thread's actual TEB value

Requirement: Window mutation

WhiteMagic SHALL enumerate and mutate target windows — position, size, title, activation, and flashing.

Scenario: move and resize

• WHEN a window's X, Y, width, and height are set
• THEN the window MUST move and resize to those values

Scenario: query by class name

• WHEN windows are queried by class name
• THEN matching windows MUST be returned

Requirement: Keyboard and mouse simulation

WhiteMagic SHALL simulate keyboard and mouse input to a target window, including input delivered without activating the window where the mechanism allows.

Scenario: write text to a window

• WHEN text is written to a target window's keyboard interface
• THEN the window MUST receive the corresponding key input

Scenario: mouse click

• WHEN a click at a coordinate is issued to a window's mouse interface
• THEN the window MUST receive the corresponding mouse input

Requirement: Asynchronous execution wrappers

WhiteMagic SHALL provide Task-based asynchronous wrappers over its execution strategies.

Scenario: async execute returns a task

• WHEN an async execute is invoked
• THEN it MUST return a Task<T> that completes with the execution result