Press n or j to go to the next uncovered block, b, p or k for the previous block.
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 | 5x 23x 23x 26x 31x 31x 25x 31x 2x 1x 1x 1x 1x 31x 1x 1x 1x 1x 31x 2x 2x 2x 31x 2x 2x 3x 3x 2x 31x 2x 1x 1x 1x 1x 31x 2x 1x 1x 1x 1x 31x 2x 2x 1x 1x 1x 1x 31x 1x 1x 31x 31x 29x 24x 22x 22x 21x 21x 2x 2x 3x 3x 3x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 2x 2x 2x 2x 2x 2x 2x 2x 2x 2x 1x 1x 29x 29x 29x 23x 9x 9x 9x 5x 5x 5x 9x 9x 9x 9x 9x | import { useEffect } from "react";
import { SimulatorActionType, API_VERSION, SimulatorEventType } from "@/types/external-api";
import type { SimulatorMessage, SimulatorResponse, SimulatorEventMessage, SimulationStateEventData, ServerStatusEventData } from "@/types/external-api";
interface UseExternalApiParams {
/** Restrict inbound messages to this origin. Use "*" to allow all origins. */
allowedOrigin: string;
/** Called when a LOAD_CODE message is received. */
onLoadCode: (code: string) => void;
/** Called when a START_SIMULATION message is received. */
onStartSimulation: () => void;
/** Called when a STOP_SIMULATION message is received. */
onStopSimulation: () => void;
/** Called when a PAUSE_SIMULATION message is received. */
onPauseSimulation: () => void;
/** Called when a RESUME_SIMULATION message is received. */
onResumeSimulation: () => void;
/** Called when a SET_PIN_STATE message is received. */
onSetPinState: (pin: number, value: number) => void;
/** Returns the current value of a pin (used for GET_PIN_STATE responses). */
getPinState: (pin: number) => number;
/** Called when a SERIAL_INPUT message is received. */
onSerialInput: (data: string) => void;
/** Called when a SET_SIMULATION_TIMEOUT message is received. */
onSetSimulationTimeout: (timeout: number) => void;
/** Called when a SET_OUTPUT_TAB message is received. */
onSetOutputTab: (tab: "compiler" | "messages" | "registry" | "debug") => void;
/** Returns the current simulation state (used for GET_SIMULATION_STATE responses). */
getSimulationState: () => string;
/** Returns the current server status for GET_SERVER_STATUS responses. */
getServerStatus: () => ServerStatusEventData | null;
}
// Global storage for the allowed origin (set by useExternalApi hook)
const _allowedOriginRef = { value: "*" };
/**
* Sends a response message to the parent frame.
* Automatically includes the API version for backward compatibility negotiation.
*
* @param response - The response payload to send. May or may not include version already.
* @param targetOrigin - The target origin for the postMessage call.
* Pass the parent origin explicitly to prevent data leakage (S2819).
* Use `"*"` only when the caller intentionally allows any receiver.
*/
export function sendMessageToParent(
response: Partial<SimulatorResponse>,
targetOrigin: string,
): void {
const withVersion: SimulatorResponse = {
...response,
version: API_VERSION,
} as SimulatorResponse;
(globalThis.parent ?? globalThis).postMessage(withVersion, targetOrigin);
}
/**
* Sends an event message (emitted proactively by the simulator) to the parent frame.
* Automatically includes the API version.
*
* @param event - The event message to send (already includes version and type).
* @param targetOrigin - The target origin for the postMessage call.
*/
export function sendEventToParent(
event: SimulatorEventMessage,
targetOrigin: string,
): void {
(globalThis.parent ?? globalThis).postMessage(event, targetOrigin);
}
/**
* Hook that listens for inbound `window.postMessage` messages and
* dispatches them to the appropriate simulator callbacks.
*
* Security: messages from origins other than `allowedOrigin` are silently
* dropped (unless `allowedOrigin` is `"*"`).
*/
export function useExternalApi(params: UseExternalApiParams): void {
const {
allowedOrigin,
onLoadCode,
onStartSimulation,
onStopSimulation,
onPauseSimulation,
onResumeSimulation,
onSetPinState,
getPinState,
onSerialInput,
onSetSimulationTimeout,
onSetOutputTab,
getSimulationState,
getServerStatus,
} = params;
// Store the allowed origin globally for use by event-sending functions
useEffect(() => {
_allowedOriginRef.value = allowedOrigin;
}, [allowedOrigin]);
// ── Action handler dispatchers ──────────────────────────────────────────
const handleLoadCode = (payload: unknown): void => {
if (typeof (payload as { code?: unknown })?.code !== "string") {
sendMessageToParent({ type: SimulatorActionType.LOAD_CODE, success: false, error: "payload.code must be a string" }, allowedOrigin);
return;
}
onLoadCode((payload as { code: string }).code);
sendMessageToParent({ type: SimulatorActionType.LOAD_CODE, success: true }, allowedOrigin);
};
const handlePinState = (payload: unknown): void => {
const p = payload as { pin?: unknown; value?: unknown };
Iif (typeof p?.pin !== "number" || typeof p?.value !== "number") {
sendMessageToParent({ type: SimulatorActionType.SET_PIN_STATE, success: false, error: "payload.pin and payload.value must be numbers" }, allowedOrigin);
return;
}
onSetPinState(p.pin, p.value);
sendMessageToParent({ type: SimulatorActionType.SET_PIN_STATE, success: true }, allowedOrigin);
};
const handleGetPinState = (payload: unknown): void => {
Iif (typeof (payload as { pin?: unknown })?.pin !== "number") {
sendMessageToParent({ type: SimulatorActionType.GET_PIN_STATE, success: false, error: "payload.pin must be a number" }, allowedOrigin);
return;
}
const value = getPinState((payload as { pin: number }).pin);
sendMessageToParent({ type: SimulatorActionType.GET_PIN_STATE, success: true, data: value }, allowedOrigin);
};
const handleBatchSetPinState = (payload: unknown): void => {
Iif (!Array.isArray((payload as { pins?: unknown })?.pins)) {
sendMessageToParent({ type: SimulatorActionType.BATCH_SET_PIN_STATE, success: false, error: "payload.pins must be an array" }, allowedOrigin);
return;
}
for (const pinState of (payload as { pins: Array<{ pin?: unknown; value?: unknown }> }).pins) {
Eif (typeof pinState?.pin === "number" && typeof pinState?.value === "number") {
onSetPinState(pinState.pin, pinState.value);
}
}
sendMessageToParent({ type: SimulatorActionType.BATCH_SET_PIN_STATE, success: true }, allowedOrigin);
};
const handleSerialInput = (payload: unknown): void => {
if (typeof (payload as { data?: unknown })?.data !== "string") {
sendMessageToParent({ type: SimulatorActionType.SERIAL_INPUT, success: false, error: "payload.data must be a string" }, allowedOrigin);
return;
}
onSerialInput((payload as { data: string }).data);
sendMessageToParent({ type: SimulatorActionType.SERIAL_INPUT, success: true }, allowedOrigin);
};
const handleSetTimeout = (payload: unknown): void => {
if (typeof (payload as { timeout?: unknown })?.timeout !== "number" || (payload as { timeout: number }).timeout < 0) {
sendMessageToParent({ type: SimulatorActionType.SET_SIMULATION_TIMEOUT, success: false, error: "payload.timeout must be a non-negative number" }, allowedOrigin);
return;
}
onSetSimulationTimeout((payload as { timeout: number }).timeout / 1000);
sendMessageToParent({ type: SimulatorActionType.SET_SIMULATION_TIMEOUT, success: true }, allowedOrigin);
};
const handleSetOutputTab = (payload: unknown): void => {
const validTabs = ["compiler", "messages", "registry", "debug"];
if (typeof (payload as { tab?: unknown })?.tab !== "string" || !validTabs.includes((payload as { tab: string }).tab)) {
sendMessageToParent({ type: SimulatorActionType.SET_OUTPUT_TAB, success: false, error: `payload.tab must be one of: ${validTabs.join(", ")}` }, allowedOrigin);
return;
}
onSetOutputTab((payload as { tab: "compiler" | "messages" | "registry" | "debug" }).tab);
sendMessageToParent({ type: SimulatorActionType.SET_OUTPUT_TAB, success: true }, allowedOrigin);
};
const handleGetState = (): void => {
const state = getSimulationState();
sendMessageToParent({ type: SimulatorActionType.GET_SIMULATION_STATE, success: true, data: state }, allowedOrigin);
};
const handleGetServerStatus = (): void => {
const status = getServerStatus();
sendMessageToParent({ type: SimulatorActionType.GET_SERVER_STATUS, success: true, data: status }, allowedOrigin);
};
useEffect(() => {
const handleMessage = (event: MessageEvent): void => {
if (allowedOrigin !== "*" && event.origin !== allowedOrigin) return;
const msg = event.data;
if (typeof msg !== "object" || msg === null || typeof msg.type !== "string") return;
const message = msg as SimulatorMessage;
switch (message.type) {
case SimulatorActionType.LOAD_CODE:
handleLoadCode(message.payload);
break;
case SimulatorActionType.START_SIMULATION:
onStartSimulation();
sendMessageToParent({ type: SimulatorActionType.START_SIMULATION, success: true }, allowedOrigin);
break;
case SimulatorActionType.STOP_SIMULATION:
onStopSimulation();
sendMessageToParent({ type: SimulatorActionType.STOP_SIMULATION, success: true }, allowedOrigin);
break;
case SimulatorActionType.PAUSE_SIMULATION:
onPauseSimulation();
sendMessageToParent({ type: SimulatorActionType.PAUSE_SIMULATION, success: true }, allowedOrigin);
break;
case SimulatorActionType.RESUME_SIMULATION:
onResumeSimulation();
sendMessageToParent({ type: SimulatorActionType.RESUME_SIMULATION, success: true }, allowedOrigin);
break;
case SimulatorActionType.SET_PIN_STATE:
handlePinState(message.payload);
break;
case SimulatorActionType.GET_PIN_STATE:
handleGetPinState(message.payload);
break;
case SimulatorActionType.BATCH_SET_PIN_STATE:
handleBatchSetPinState(message.payload);
break;
case SimulatorActionType.SERIAL_INPUT:
handleSerialInput(message.payload);
break;
case SimulatorActionType.SET_SIMULATION_TIMEOUT:
handleSetTimeout(message.payload);
break;
case SimulatorActionType.SET_OUTPUT_TAB:
handleSetOutputTab(message.payload);
break;
case SimulatorActionType.GET_SIMULATION_STATE:
handleGetState();
break;
case SimulatorActionType.GET_SERVER_STATUS:
handleGetServerStatus();
break;
// default: silently ignore unknown actions
}
};
globalThis.addEventListener("message", handleMessage);
return () => {
globalThis.removeEventListener("message", handleMessage);
};
}, [
allowedOrigin, onLoadCode, onStartSimulation, onStopSimulation,
onPauseSimulation, onResumeSimulation, onSetPinState, getPinState,
onSerialInput, onSetSimulationTimeout, onSetOutputTab, getSimulationState, getServerStatus,
]);
}
/**
* Gets the currently configured allowed origin for external API communication.
* Defaults to "*" if useExternalApi has not been called yet.
* @internal Used by other hooks to send events with the correct origin.
*/
function getAllowedOrigin(): string {
return _allowedOriginRef.value;
}
/**
* Sends a SERIAL_OUTPUT_EVENT to the parent frame with serial data.
* Automatically uses the configured allowed origin and includes API version.
* Safely handles errors to prevent serial output from blocking the simulator.
* @param output - The serial output string to send.
*/
export function emitSerialOutput(output: string): void {
try {
const event: SimulatorEventMessage<typeof SimulatorEventType.SERIAL_OUTPUT_EVENT> = {
version: API_VERSION,
type: SimulatorEventType.SERIAL_OUTPUT_EVENT,
success: true,
data: output,
};
sendEventToParent(event, getAllowedOrigin());
} catch (error) {
// Silently ignore postMessage errors to prevent disrupting serial output
// This is expected when the simulator is not embedded in an iframe
if (typeof console !== "undefined" && console.debug) {
console.debug("[External API] Serial event send failed (expected when not in iframe):", error);
}
}
}
/**
* Sends a PIN_STATE_CHANGE_EVENT to the parent frame when a pin changes value.
* @param pin - Pin number (0-13 digital, 14-19 = A0-A5 analog)
* @param value - New pin value
*/
export function emitPinStateChange(pin: number, value: number): void {
try {
const event: SimulatorEventMessage<typeof SimulatorEventType.PIN_STATE_CHANGE_EVENT> = {
version: API_VERSION,
type: SimulatorEventType.PIN_STATE_CHANGE_EVENT,
success: true,
data: { pin, value },
};
sendEventToParent(event, getAllowedOrigin());
} catch {
// Silently ignore — postMessage errors are expected when not embedded
}
}
/**
* Sends a SIMULATION_STATE_EVENT to the parent frame when the simulation state changes.
* @param state - New simulation state
* @param message - Optional human-readable message
*/
export function emitSimulationStateEvent(
state: "IDLE" | "QUEUED_FOR_COMPILING" | "COMPILING" | "QUEUED_FOR_SIMULATION" | "RUNNING" | "PAUSED" | "ERROR",
message?: string,
): void {
try {
const data: SimulationStateEventData = { state };
if (message !== undefined) data.message = message;
const event: SimulatorEventMessage<typeof SimulatorEventType.SIMULATION_STATE_EVENT> = {
version: API_VERSION,
type: SimulatorEventType.SIMULATION_STATE_EVENT,
success: true,
data,
};
sendEventToParent(event, getAllowedOrigin());
} catch {
// Silently ignore — postMessage errors are expected when not embedded
}
}
/**
* Sends a SERVER_STATUS_EVENT to the parent frame with current pool / compile stats.
* Called periodically so test harnesses can measure queue times.
* @param data - Server status snapshot from use-backend-health
*/
export function emitServerStatusEvent(data: ServerStatusEventData): void {
try {
const event: SimulatorEventMessage<typeof SimulatorEventType.SERVER_STATUS_EVENT> = {
version: API_VERSION,
type: SimulatorEventType.SERVER_STATUS_EVENT,
success: true,
data,
};
sendEventToParent(event, getAllowedOrigin());
} catch {
// Silently ignore — postMessage errors are expected when not embedded
}
}
|