nativemason 0.0.0-stage → 0.3.0

package/dist/native/index.js

@@ -0,0 +1,221 @@
+import { randomUUID, timingSafeEqual } from 'node:crypto';
+import { WebSocketServer, WebSocket } from 'ws';
+import { BridgeFault, NativeBindHostSchema, NativeClientMessageSchema } from '@nativemason/contracts';
+export async function createNativeBridge(options) {
+    const host = NativeBindHostSchema.safeParse(options.host ?? '127.0.0.1');
+    if (!host.success)
+        throw new BridgeFault('INVALID_INPUT', 'Native host must be a loopback or private LAN IPv4 interface address');
+    const server = new WebSocketServer({ host: host.data, port: options.port, maxPayload: 4 * 1024 * 1024 });
+    await new Promise((resolve, reject) => { server.once('listening', resolve); server.once('error', reject); });
+    let client;
+    let closed = false;
+    let connectedPlatform = "android";
+    let connectedTargetId;
+    let supportsActions = false;
+    let handshakeFailure;
+    const actions = new Map();
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const pending = new Map();
+    const waiters = new Set();
+    function failPending(error) {
+        for (const item of pending.values()) {
+            clearTimeout(item.timer);
+            item.reject(error);
+        }
+        pending.clear();
+        for (const item of actions.values()) {
+            clearTimeout(item.timer);
+            item.reject(error);
+        }
+        actions.clear();
+    }
+    server.on('connection', socket => {
+        let authenticated = false;
+        const helloTimeout = setTimeout(() => socket.close(1008, 'Handshake timeout'), timeoutMs);
+        socket.on('message', raw => {
+            let decoded;
+            try {
+                decoded = JSON.parse(raw.toString());
+            }
+            catch {
+                socket.close(1008, 'Invalid protocol message');
+                return;
+            }
+            const parsed = NativeClientMessageSchema.safeParse(decoded);
+            if (!parsed.success) {
+                if (typeof decoded === 'object' && decoded !== null && 'type' in decoded && decoded.type === 'hello')
+                    handshakeFailure = 'Native handshake schema or protocol version is incompatible; rebuild the development runtime';
+                // Only correlate validated-schema coherence failures after authentication
+                // to an already pending request. Other malformed traffic closes the peer.
+                const requestId = typeof decoded === 'object' && decoded !== null && 'requestId' in decoded && typeof decoded.requestId === 'string' ? decoded.requestId : undefined;
+                const staleSource = parsed.error.issues.some(issue => issue.code === 'custom' && issue.params?.bridgeCode === 'STALE_SOURCE');
+                const item = authenticated && client === socket && requestId ? pending.get(requestId) : undefined;
+                if (staleSource && item && requestId) {
+                    pending.delete(requestId);
+                    clearTimeout(item.timer);
+                    item.reject(new BridgeFault('STALE_SOURCE', 'Native snapshot contains inconsistent source metadata'));
+                    return;
+                }
+                socket.close(1008, 'Invalid protocol message');
+                return;
+            }
+            const message = parsed.data;
+            if (message.type === 'hello') {
+                if (message.protocolVersion === 1 && (options.platform === 'ios' || options.targetId)) {
+                    handshakeFailure = 'Protocol v2 required for selected native target';
+                    socket.close(1002, handshakeFailure);
+                    return;
+                }
+                if (message.protocolVersion === 2 && (!message.platform || !message.targetId || !message.capabilities)) {
+                    handshakeFailure = 'Protocol v2 target identity and capabilities required';
+                    socket.close(1002, handshakeFailure);
+                    return;
+                }
+                if ((options.platform && options.platform !== message.platform) || (options.targetId && options.targetId !== message.targetId)) {
+                    handshakeFailure = 'Native target mismatch';
+                    socket.close(1008, handshakeFailure);
+                    return;
+                }
+                const received = Buffer.from(message.token);
+                const expected = Buffer.from(options.token);
+                if (authenticated || received.length !== expected.length || !timingSafeEqual(received, expected) || message.scenarioId !== options.scenarioId) {
+                    socket.close(1008, 'Handshake rejected');
+                    return;
+                }
+                clearTimeout(helloTimeout);
+                authenticated = true;
+                handshakeFailure = undefined;
+                connectedPlatform = message.platform ?? 'android';
+                connectedTargetId = message.targetId;
+                supportsActions = message.capabilities?.scenarioActions ?? false;
+                if (client && client !== socket) {
+                    failPending(new BridgeFault('NATIVE_DISCONNECTED', 'Native runtime reconnected'));
+                    client.close(1000, 'Replaced by reconnect');
+                }
+                client = socket;
+                for (const waiter of waiters)
+                    waiter.resolve(socket);
+                waiters.clear();
+                return;
+            }
+            if (!authenticated || client !== socket) {
+                socket.close(1008, 'Authenticate first');
+                return;
+            }
+            const action = actions.get(message.requestId);
+            if (action) {
+                clearTimeout(action.timer);
+                actions.delete(message.requestId);
+                if (message.type === 'action_result')
+                    action.resolve();
+                else if (message.type === 'error')
+                    action.reject(new BridgeFault(message.error.code, message.error.message, message.error.details));
+                else
+                    action.reject(new BridgeFault('VERIFICATION_FAILED', 'Expected native action result'));
+                return;
+            }
+            if (message.type === 'action_result')
+                return;
+            const item = pending.get(message.requestId);
+            if (!item)
+                return;
+            pending.delete(message.requestId);
+            clearTimeout(item.timer);
+            if (message.type === 'error') {
+                item.reject(new BridgeFault(message.error.code, message.error.message, message.error.details));
+                return;
+            }
+            const snapshot = message.snapshot;
+            if (snapshot.platform !== connectedPlatform || snapshot.sessionId !== options.sessionId || snapshot.scenarioId !== options.scenarioId) {
+                item.reject(new BridgeFault('VERIFICATION_FAILED', 'Native snapshot identity mismatch'));
+                return;
+            }
+            if (options.targetId && (snapshot.nativeTarget?.targetId !== connectedTargetId || snapshot.nativeTarget?.platform !== connectedPlatform)) {
+                item.reject(new BridgeFault('VERIFICATION_FAILED', 'Native snapshot target mismatch'));
+                return;
+            }
+            if (snapshot.status !== 'stable') {
+                item.reject(new BridgeFault('UNSTABLE_LAYOUT', 'Native layout did not settle'));
+                return;
+            }
+            for (const [path, hash] of Object.entries(item.expected)) {
+                if (snapshot.revisions[path] !== hash) {
+                    item.reject(new BridgeFault('STALE_SOURCE', `Native source mismatch for ${path}`));
+                    return;
+                }
+            }
+            item.resolve(snapshot);
+        });
+        socket.on('error', () => { });
+        socket.on('close', () => {
+            clearTimeout(helloTimeout);
+            if (client === socket) {
+                client = undefined;
+                failPending(new BridgeFault('NATIVE_DISCONNECTED', 'Native runtime disconnected'));
+            }
+        });
+    });
+    async function connected() {
+        if (closed)
+            throw new BridgeFault('NATIVE_DISCONNECTED', 'Native bridge is closed');
+        if (client?.readyState === WebSocket.OPEN)
+            return client;
+        return new Promise((resolve, reject) => {
+            const waiter = { resolve: (socket) => { clearTimeout(timer); resolve(socket); }, reject: (error) => { clearTimeout(timer); reject(error); } };
+            const timer = setTimeout(() => { waiters.delete(waiter); reject(new BridgeFault('NATIVE_DISCONNECTED', handshakeFailure ?? 'No authenticated native runtime connected')); }, timeoutMs);
+            waiters.add(waiter);
+        });
+    }
+    return {
+        async runHook(name, value) {
+            const socket = await connected();
+            if (!supportsActions)
+                throw new BridgeFault('INVALID_INPUT', 'Native runtime does not support scenario actions');
+            const requestId = randomUUID();
+            return new Promise((resolve, reject) => {
+                const timer = setTimeout(() => { actions.delete(requestId); reject(new BridgeFault('TIMEOUT', 'Native action timed out')); }, timeoutMs);
+                actions.set(requestId, { resolve, reject, timer });
+                socket.send(JSON.stringify({ type: 'action', requestId, sessionId: options.sessionId, name, value }), error => {
+                    if (error) {
+                        clearTimeout(timer);
+                        actions.delete(requestId);
+                        reject(new BridgeFault('NATIVE_DISCONNECTED', error.message));
+                    }
+                });
+            });
+        },
+        async capture(expectedRevisions) {
+            const socket = await connected();
+            if (socket.readyState !== WebSocket.OPEN)
+                throw new BridgeFault('NATIVE_DISCONNECTED', 'Native runtime disconnected before capture');
+            const requestId = randomUUID();
+            return new Promise((resolve, reject) => {
+                const timer = setTimeout(() => { pending.delete(requestId); reject(new BridgeFault('TIMEOUT', 'Native capture timed out')); }, timeoutMs);
+                pending.set(requestId, { resolve, reject, timer, expected: expectedRevisions });
+                socket.send(JSON.stringify({ type: 'capture', requestId, sessionId: options.sessionId, expectedRevisions }), error => {
+                    if (error) {
+                        const item = pending.get(requestId);
+                        if (item) {
+                            clearTimeout(item.timer);
+                            pending.delete(requestId);
+                            reject(new BridgeFault('NATIVE_DISCONNECTED', error.message));
+                        }
+                    }
+                });
+            });
+        },
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            const error = new BridgeFault('NATIVE_DISCONNECTED', 'Native bridge closed');
+            failPending(error);
+            for (const waiter of waiters)
+                waiter.reject(error);
+            waiters.clear();
+            for (const socket of server.clients)
+                socket.terminate();
+            await new Promise((resolve, reject) => server.close(error => error ? reject(error) : resolve()));
+        },
+    };
+}

package/dist/overlay/index.d.ts

@@ -0,0 +1,3 @@
+import { type OverlayScene } from '@nativemason/contracts';
+/** Draws logical-coordinate scene geometry over an existing screenshot without touching page layout. */
+export declare function renderOverlay(png: Uint8Array, input: OverlayScene, pixelRatio?: number): Promise<Uint8Array>;

package/dist/overlay/index.js

@@ -0,0 +1,35 @@
+import sharp from 'sharp';
+import { BridgeFault, OverlaySceneSchema } from '@nativemason/contracts';
+function xml(value) {
+    return value.replace(/[&<>"']/g, char => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;' })[char]);
+}
+/** Draws logical-coordinate scene geometry over an existing screenshot without touching page layout. */
+export async function renderOverlay(png, input, pixelRatio) {
+    const parsed = OverlaySceneSchema.safeParse(input);
+    if (!parsed.success)
+        throw new BridgeFault('INVALID_INPUT', 'Invalid overlay scene', parsed.error.flatten());
+    const scene = parsed.data;
+    if (!Number.isFinite(scene.width) || !Number.isFinite(scene.height) || scene.width <= 0 || scene.height <= 0)
+        throw new BridgeFault('INVALID_INPUT', 'Overlay dimensions must be finite and positive');
+    if (scene.marks.some(mark => !Number.isInteger(mark.label) || mark.label < 1))
+        throw new BridgeFault('INVALID_INPUT', 'Overlay marks must have positive integer labels');
+    const image = sharp(png);
+    const metadata = await image.metadata();
+    if (!metadata.width || !metadata.height)
+        throw new BridgeFault('INVALID_INPUT', 'Screenshot has no dimensions');
+    const scaleX = metadata.width / scene.width;
+    const scaleY = metadata.height / scene.height;
+    if (pixelRatio !== undefined && (!Number.isFinite(pixelRatio) || pixelRatio <= 0 || Math.abs(scaleX - pixelRatio) > 1 / scene.width || Math.abs(scaleY - pixelRatio) > 1 / scene.height)) {
+        throw new BridgeFault('INVALID_INPUT', 'Screenshot dimensions do not match the requested pixel ratio');
+    }
+    if (Math.abs(scaleX - scaleY) > Math.max(1 / scene.width, 1 / scene.height))
+        throw new BridgeFault('INVALID_INPUT', 'Screenshot and overlay scene have different aspect ratios');
+    const targets = scene.targets.map(target => `<g><title>${xml(target.id)}</title><rect x="${target.rect.x}" y="${target.rect.y}" width="${target.rect.width}" height="${target.rect.height}" fill="#22c55e" fill-opacity="0.18" stroke="#16a34a" stroke-width="1" stroke-dasharray="4 3"/></g>`).join('');
+    const marks = scene.marks.map(mark => {
+        const x = Math.min(Math.max(mark.rect.x, 0), Math.max(0, scene.width - 28));
+        const y = Math.min(Math.max(mark.rect.y, 0), Math.max(0, scene.height - 20));
+        return `<g><title>${xml(mark.id)}</title><rect x="${mark.rect.x}" y="${mark.rect.y}" width="${mark.rect.width}" height="${mark.rect.height}" fill="none" stroke="#ef4444" stroke-width="1"/><rect x="${x}" y="${y}" width="28" height="20" rx="3" fill="#b91c1c"/><text x="${x + 14}" y="${y + 14}" font-family="sans-serif" font-size="12" text-anchor="middle" fill="white">${xml(String(mark.label))}</text></g>`;
+    }).join('');
+    const svg = Buffer.from(`<svg xmlns="http://www.w3.org/2000/svg" width="${metadata.width}" height="${metadata.height}" viewBox="0 0 ${scene.width} ${scene.height}">${targets}${marks}</svg>`);
+    return image.composite([{ input: svg }]).png().toBuffer();
+}

package/dist/scenario/index.d.ts

@@ -0,0 +1,5 @@
+import { type NativeScenarioOptions, type NativeProfilePort, type ScenarioPort } from '@nativemason/contracts';
+/** Native UI actions run against the explicitly selected application and device. */
+export declare function createNativeScenarioPort(options: NativeScenarioOptions): ScenarioPort;
+/** Journals device-wide settings before mutation and restores them even when the callback fails. */
+export declare function createNativeProfilePort(options: NativeScenarioOptions): NativeProfilePort;

package/dist/scenario/index.js

@@ -0,0 +1,318 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { mkdtemp, readFile, writeFile, unlink, rmdir, mkdir, open } from 'node:fs/promises';
+import { tmpdir, homedir } from 'node:os';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { Buffer } from 'node:buffer';
+import { BridgeFault, NativeScenarioFailureEvidenceSchema, ScenarioScriptSchema } from '@nativemason/contracts';
+const execute = promisify(execFile);
+const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+const regex = (value) => `^${value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}$`;
+const FAILURE_MESSAGE_LIMIT = 2048;
+const FAILURE_OUTPUT_LIMIT = 16384;
+function textOutput(value) {
+    if (typeof value === 'string')
+        return value;
+    return Buffer.isBuffer(value) ? value.toString('utf8') : '';
+}
+function scenarioFailureEvidence(error) {
+    const wrapper = error && typeof error === 'object' ? error : {};
+    const rawError = wrapper.reason ?? error;
+    const processError = (rawError && typeof rawError === 'object' ? rawError : new Error(String(rawError)));
+    const fullMessage = String(processError.message ?? (error instanceof Error ? error.message : error));
+    const rawStdout = textOutput(wrapper.stdout ?? processError.stdout);
+    const rawStderr = textOutput(wrapper.stderr ?? processError.stderr);
+    const rawCode = processError.exitCode ?? processError.code;
+    const exitCode = typeof rawCode === 'number' && Number.isInteger(rawCode) ? rawCode : typeof rawCode === 'string' && rawCode ? rawCode.slice(0, 64) : null;
+    const rawSignal = typeof processError.signal === 'string' ? processError.signal : null;
+    const signal = rawSignal?.slice(0, 64) ?? null;
+    return NativeScenarioFailureEvidenceSchema.parse({
+        driver: 'maestro', message: fullMessage.slice(0, FAILURE_MESSAGE_LIMIT), exitCode, signal,
+        terminated: processError.killed === true || signal !== null,
+        stdout: rawStdout.slice(-FAILURE_OUTPUT_LIMIT), stderr: rawStderr.slice(-FAILURE_OUTPUT_LIMIT),
+        outputTruncated: fullMessage.length > FAILURE_MESSAGE_LIMIT || rawStdout.length > FAILURE_OUTPUT_LIMIT || rawStderr.length > FAILURE_OUTPUT_LIMIT || String(rawCode ?? '').length > 64 || String(rawSignal ?? '').length > 64 || rawCode === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER',
+    });
+}
+function safeString(value) {
+    if (value.includes('${') || value.includes('\0'))
+        throw new BridgeFault('UNSUPPORTED_ACTION', 'Maestro interpolation and NUL characters are not accepted in scenario values');
+    return value;
+}
+function validateOptions(options) {
+    if (!/^[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z][A-Za-z0-9_]*)+$/.test(options.appId))
+        throw new BridgeFault('INVALID_INPUT', 'An explicit native application identifier is required');
+    if (!options.target.targetId || /[\0\r\n]/.test(options.target.targetId))
+        throw new BridgeFault('INVALID_INPUT', 'A native device identifier is required');
+    if (options.ssh && !/^[A-Za-z0-9_.-]+@[A-Za-z0-9_.-]+$/.test(options.ssh.destination))
+        throw new BridgeFault('INVALID_INPUT', 'SSH destination must be user@host');
+}
+function sshArgs(options) { return [...(options.ssh?.identityFile ? ['-i', options.ssh.identityFile] : []), '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10', options.ssh.destination]; }
+async function command(options, executable, args) {
+    const result = options.ssh ? await execute('ssh', [...sshArgs(options), [executable, ...args].map(quote).join(' ')], { timeout: options.timeoutMs ?? 30000, maxBuffer: 4 * 1024 * 1024 }) : await execute(executable, args, { timeout: options.timeoutMs ?? 30000, maxBuffer: 4 * 1024 * 1024 });
+    return result.stdout.trim();
+}
+async function maestro(options, commands) {
+    const flow = `appId: ${JSON.stringify(options.appId)}\n---\n${JSON.stringify(commands, null, 2)}\n`;
+    const directory = await mkdtemp(path.join(tmpdir(), 'nativemason-maestro-'));
+    const file = path.join(directory, 'flow.yaml');
+    try {
+        await writeFile(file, flow, { mode: 0o600 });
+        try {
+            if (options.ssh) {
+                // SSH stdin carries the generated flow; only validated, quoted command arguments enter its shell.
+                const program = `set -e; nm_flow_dir=$(mktemp -d); trap 'rm "$nm_flow_dir/flow.yaml"; rmdir "$nm_flow_dir"' EXIT; cat > "$nm_flow_dir/flow.yaml"; ${[options.maestroPath ?? 'maestro', '--device', options.adbSerial ?? options.target.targetId, 'test'].map(quote).join(' ')} "$nm_flow_dir/flow.yaml"`;
+                await new Promise((resolve, reject) => { const child = execFile('ssh', [...sshArgs(options), program], { timeout: options.timeoutMs ?? 120000, maxBuffer: 4 * 1024 * 1024 }, (error, stdout, stderr) => error ? reject({ reason: error, stdout, stderr }) : resolve()); child.stdin?.end(flow); });
+            }
+            else
+                await command({ ...options, timeoutMs: options.timeoutMs ?? 120000 }, options.maestroPath ?? 'maestro', ['--device', options.adbSerial ?? options.target.targetId, 'test', file]);
+        }
+        catch (error) {
+            const evidence = scenarioFailureEvidence(error);
+            const reason = evidence.message.slice(0, 256);
+            throw new BridgeFault('VERIFICATION_FAILED', reason ? `Native scenario command failed: ${reason}` : 'Native scenario command failed', evidence);
+        }
+    }
+    finally {
+        await unlink(file).catch(() => undefined);
+        await rmdir(directory).catch(() => undefined);
+    }
+}
+/** Native UI actions run against the explicitly selected application and device. */
+export function createNativeScenarioPort(options) {
+    validateOptions(options);
+    let closed = false;
+    return {
+        async run(script) {
+            if (closed)
+                throw new BridgeFault('SESSION_NOT_FOUND', 'Native scenario driver is closed');
+            const parsed = ScenarioScriptSchema.parse(script);
+            if (options.target.platform === 'ios' && options.target.kind === 'physical' && [...parsed.reset, ...parsed.actions].some(action => action.type !== 'hook'))
+                throw new BridgeFault('UNSUPPORTED_ACTION', 'Physical iOS supports registered app hooks; Maestro UI actions require an iOS simulator. Navigate manually before capture.');
+            // Reject unsupported static actions before executing earlier hooks or UI actions.
+            for (const action of [...parsed.reset, ...parsed.actions]) {
+                if (action.type === 'hook' && !options.runHook)
+                    throw new BridgeFault('UNSUPPORTED_ACTION', 'Native application hooks require an explicitly registered runtime hook transport');
+                if (action.type === 'press')
+                    throw new BridgeFault('UNSUPPORTED_ACTION', 'Held pointer phases are supported in Chromium only; native state requires an app scenario hook');
+                if (action.type === 'scroll')
+                    throw new BridgeFault('UNSUPPORTED_ACTION', 'Native exact scroll offsets are unavailable; use the explicit swipe action');
+                if (action.type === 'keyboard' && action.visible)
+                    throw new BridgeFault('UNSUPPORTED_ACTION', 'Show the native keyboard by tapping an input; visibility must be measured by the application');
+                if ('elementId' in action)
+                    safeString(action.elementId);
+                if (action.type === 'navigate')
+                    safeString(action.url);
+                if (action.type === 'input') {
+                    safeString(action.text);
+                    if (options.target.platform === 'android' && [...action.text].some(character => character.codePointAt(0) > 127))
+                        throw new BridgeFault('UNSUPPORTED_ACTION', 'Maestro inputText does not support Unicode on Android');
+                }
+                if (action.type === 'input' && action.mode === 'replace' && action.text === '')
+                    throw new BridgeFault('UNSUPPORTED_ACTION', 'Maestro cannot verify an empty native text value when the field may expose a placeholder or accessibility label');
+            }
+            const commands = [];
+            const flush = async () => { if (commands.length) {
+                await maestro(options, commands);
+                commands.length = 0;
+            } };
+            for (const action of [...parsed.reset, ...parsed.actions]) {
+                if (action.type === 'navigate') {
+                    commands.push({ openLink: safeString(action.url) });
+                    continue;
+                }
+                if (action.type === 'hook') {
+                    if (!options.runHook)
+                        throw new BridgeFault('UNSUPPORTED_ACTION', 'Native application hooks require an explicitly registered runtime hook transport');
+                    await flush();
+                    await options.runHook(action.name, action.value);
+                    continue;
+                }
+                if (action.type === 'keyboard') {
+                    if (action.visible)
+                        throw new BridgeFault('UNSUPPORTED_ACTION', 'Show the native keyboard by tapping an input; visibility must be measured by the application');
+                    commands.push('hideKeyboard');
+                    continue;
+                }
+                if (action.type === 'scroll')
+                    throw new BridgeFault('UNSUPPORTED_ACTION', 'Native exact scroll offsets are unavailable; use the explicit swipe action');
+                const selector = { id: regex(safeString(action.elementId)) };
+                if (action.type === 'tap')
+                    commands.push({ tapOn: selector });
+                if (action.type === 'swipe')
+                    commands.push({ swipe: { from: selector, direction: action.direction } });
+                if (action.type === 'wait')
+                    commands.push({ extendedWaitUntil: { visible: selector, timeout: action.timeoutMs } });
+                if (action.type === 'input') {
+                    safeString(action.text);
+                    commands.push({ tapOn: selector });
+                    if (action.mode === 'replace')
+                        commands.push({ copyTextFrom: selector }, { assertTrue: '${maestro.copiedText.length <= 100}' }, { eraseText: 100 });
+                    commands.push({ inputText: action.text });
+                    // Maestro may resolve copiedText from hint/accessibility text when the actual text is empty.
+                    if (action.mode === 'replace')
+                        commands.push({ copyTextFrom: selector }, { assertTrue: `\${maestro.copiedText === ${JSON.stringify(action.text)}}` });
+                }
+            }
+            await flush();
+        },
+        async close() { closed = true; },
+    };
+}
+const profileOperations = new Set();
+const iosSizes = { '1': 'large', '0.823': 'extra-small', '0.882': 'small', '0.941': 'medium', '1.118': 'extra-large', '1.235': 'extra-extra-large', '1.353': 'extra-extra-extra-large', '1.786': 'accessibility-medium', '2.143': 'accessibility-large', '2.643': 'accessibility-extra-large', '3.143': 'accessibility-extra-extra-large', '3.571': 'accessibility-extra-extra-extra-large' };
+/** Journals device-wide settings before mutation and restores them even when the callback fails. */
+export function createNativeProfilePort(options) {
+    validateOptions(options);
+    const directory = path.join(homedir(), '.cache', 'nativemason', 'native-settings');
+    const journal = path.join(directory, createHash('sha256').update(`${options.ssh?.destination ?? 'local'}:${options.target.platform}:${options.adbSerial ?? options.target.targetId}`).digest('hex') + '.json');
+    let active = false;
+    const adb = (args) => command(options, 'adb', ['-s', options.adbSerial ?? options.target.targetId, ...args]);
+    const settings = (operation, key, value) => adb(['shell', 'settings', operation, 'system', key, ...(value === undefined ? [] : [value])]);
+    async function waitForProfile(expected) {
+        if (!options.readProfile)
+            return;
+        const started = Date.now();
+        let lastError;
+        while (true) {
+            try {
+                const actual = await options.readProfile();
+                lastError = undefined;
+                if ((expected.fontScale === undefined || Math.abs(actual.fontScale - expected.fontScale) < 0.01) && (expected.orientation === undefined || actual.orientation === expected.orientation))
+                    return;
+            }
+            catch (error) {
+                if (!(error instanceof BridgeFault) || !['NATIVE_DISCONNECTED', 'TIMEOUT', 'UNSTABLE_LAYOUT', 'STALE_SOURCE', 'STALE_SNAPSHOT'].includes(error.code))
+                    throw error;
+                lastError = error;
+            }
+            if (Date.now() - started > (options.timeoutMs ?? 30000))
+                throw lastError ?? new BridgeFault('UNSUPPORTED_PROFILE', 'Native runtime did not report the requested font scale and orientation');
+            await new Promise(resolve => setTimeout(resolve, 100));
+        }
+    }
+    async function restore(saved) {
+        if (saved.platform === 'android') {
+            for (const [key, value] of [['font_scale', saved.fontScale], ['user_rotation', saved.rotation], ['accelerometer_rotation', saved.accelerometer]])
+                if (value !== undefined) {
+                    await settings(value === 'null' ? 'delete' : 'put', key, value === 'null' ? undefined : value);
+                    if (await settings('get', key) !== value)
+                        throw new BridgeFault('RECOVERY_CONFLICT', `Android did not restore ${key}`);
+                }
+        }
+        else {
+            if (saved.contentSize)
+                await command(options, 'xcrun', ['simctl', 'ui', options.target.targetId, 'content_size', saved.contentSize]);
+            if (saved.orientation)
+                await maestro(options, [{ setOrientation: saved.orientation === 'portrait' ? 'PORTRAIT' : 'LANDSCAPE_LEFT' }]);
+        }
+        await unlink(journal);
+    }
+    async function recover(owned = false) {
+        if (profileOperations.has(journal) && !owned)
+            throw new BridgeFault('RECOVERY_CONFLICT', 'Native profile operation is still active');
+        let saved;
+        try {
+            saved = JSON.parse(await readFile(journal, 'utf8'));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw new BridgeFault('RECOVERY_CONFLICT', 'Native settings journal is unreadable');
+        }
+        if (saved.platform !== options.target.platform || !Number.isInteger(saved.pid) || saved.pid <= 0 || [saved.fontScale, saved.rotation, saved.accelerometer].some(value => value !== undefined && value !== 'null' && !/^\d+(?:\.\d+)?$/.test(value)) || (saved.contentSize !== undefined && !Object.values(iosSizes).includes(saved.contentSize)) || (saved.orientation !== undefined && !['portrait', 'landscape'].includes(saved.orientation)))
+            throw new BridgeFault('RECOVERY_CONFLICT', 'Native settings journal is invalid');
+        let alive = false;
+        try {
+            process.kill(saved.pid, 0);
+            alive = true;
+        }
+        catch (error) {
+            if (error.code !== 'ESRCH')
+                alive = true;
+        }
+        if (saved.pid === process.pid && (owned || !profileOperations.has(journal)))
+            alive = false;
+        if (alive)
+            throw new BridgeFault('RECOVERY_CONFLICT', 'Another process owns pending native settings; close it before recovery');
+        await restore(saved);
+    }
+    return {
+        recover: () => recover(),
+        async withProfile(profile, work) {
+            if (options.target.platform === 'ios' && options.target.kind === 'physical') {
+                if (profile.fontScale !== undefined || profile.orientation !== undefined) {
+                    if (!options.readProfile)
+                        throw new BridgeFault('UNSUPPORTED_PROFILE', 'Physical iOS profile checks require runtime measurements');
+                    const actual = await options.readProfile();
+                    if ((profile.fontScale !== undefined && Math.abs(actual.fontScale - profile.fontScale) > 0.01) || (profile.orientation !== undefined && actual.orientation !== profile.orientation))
+                        throw new BridgeFault('UNSUPPORTED_PROFILE', 'Change font scale or orientation manually on the iOS device, then capture its measured profile');
+                }
+                return work();
+            }
+            if (active || profileOperations.has(journal))
+                throw new BridgeFault('RECOVERY_CONFLICT', 'Native profile operations must be serialized');
+            active = true;
+            profileOperations.add(journal);
+            let saved;
+            let journalOwned = false;
+            let originalProfile;
+            try {
+                await recover(true);
+                if (options.target.platform === 'ios' && options.target.kind !== 'simulator')
+                    throw new BridgeFault('UNSUPPORTED_PROFILE', 'iOS profile overrides require a simulator');
+                if (options.target.platform === 'ios' && profile.orientation !== undefined && !options.readProfile)
+                    throw new BridgeFault('UNSUPPORTED_PROFILE', 'iOS orientation changes require measured orientation capability');
+                if (options.readProfile)
+                    originalProfile = await options.readProfile();
+                const category = profile.fontScale === undefined ? undefined : iosSizes[String(profile.fontScale)];
+                if (options.target.platform === 'ios' && profile.fontScale !== undefined && !category)
+                    throw new BridgeFault('UNSUPPORTED_PROFILE', 'The requested iOS scale has no supported Dynamic Type category');
+                saved = options.target.platform === 'android' ? { pid: process.pid, platform: 'android', fontScale: await settings('get', 'font_scale'), rotation: await settings('get', 'user_rotation'), accelerometer: await settings('get', 'accelerometer_rotation') } : { pid: process.pid, platform: 'ios', contentSize: await command(options, 'xcrun', ['simctl', 'ui', options.target.targetId, 'content_size']), ...(profile.orientation !== undefined ? { orientation: (await options.readProfile()).orientation } : {}) };
+                await mkdir(directory, { recursive: true });
+                const handle = await open(journal, 'wx', 0o600);
+                journalOwned = true;
+                try {
+                    await handle.writeFile(JSON.stringify(saved));
+                    await handle.sync();
+                }
+                finally {
+                    await handle.close();
+                }
+                if (options.target.platform === 'android') {
+                    if (profile.fontScale !== undefined) {
+                        await settings('put', 'font_scale', String(profile.fontScale));
+                        const actual = Number(await settings('get', 'font_scale'));
+                        if (Math.abs(actual - profile.fontScale) > 0.001)
+                            throw new BridgeFault('UNSUPPORTED_PROFILE', 'Android did not accept the requested system font scale');
+                    }
+                    if (profile.orientation !== undefined) {
+                        await settings('put', 'accelerometer_rotation', '0');
+                        await settings('put', 'user_rotation', profile.orientation === 'landscape' ? '1' : '0');
+                    }
+                }
+                else {
+                    if (category)
+                        await command(options, 'xcrun', ['simctl', 'ui', options.target.targetId, 'content_size', category]);
+                    if (profile.orientation !== undefined)
+                        await maestro(options, [{ setOrientation: profile.orientation === 'portrait' ? 'PORTRAIT' : 'LANDSCAPE_LEFT' }]);
+                }
+                await waitForProfile(profile);
+                return await work();
+            }
+            finally {
+                try {
+                    if (saved && journalOwned) {
+                        await restore(saved);
+                        if (originalProfile)
+                            await waitForProfile(originalProfile);
+                    }
+                }
+                finally {
+                    active = false;
+                    profileOperations.delete(journal);
+                }
+            }
+        },
+    };
+}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "nativemason",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.3.0",
+  "type": "module",
+  "bin": {
+    "nativemason": "./bin/nativemason.js",
+    "rn-layout-bridge": "./bin/nativemason.js"
+  },
+  "exports": {
+    ".": "./dist/mcp/index.js",
+    "./babel": "./dist/instrumentation/index.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "@babel/core": "^7.28.5",
+    "@babel/types": "^7.28.5",
+    "@modelcontextprotocol/sdk": "^1.24.0",
+    "@nativemason/contracts": "0.3.0",
+    "diff": "^8.0.2",
+    "playwright": "^1.56.1",
+    "sharp": "^0.35.5",
+    "ts-morph": "^27.0.2",
+    "ws": "^8.18.3"
+  },
+  "license": "Apache-2.0",
+  "files": [
+    "dist",
+    "bin",
+    "LICENSE",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gauravsaini/nativemason.git",
+    "directory": "packages/bridge"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
 }