nativemason 0.0.0-stage → 0.2.0

package/dist/browser/accessibility.js

@@ -0,0 +1,93 @@
+import { BridgeFault, BrowserAccessibilitySamplesSchema } from '@nativemason/contracts';
+import { solidContrastRatio } from '../core/accessibility.js';
+/** Read-only, bounded browser evidence; native semantics are never inferred here. */
+export async function captureAccessibilityEvidence(page, cdp, snapshot) {
+    const samples = BrowserAccessibilitySamplesSchema.parse(await page.evaluate(() => {
+        const runtime = window.__RN_LAYOUT_BRIDGE__;
+        const focusable = Array.from(document.querySelectorAll('button,a[href],input,select,textarea,[tabindex],[contenteditable=true]')).filter(node => node.tabIndex >= 0 && !node.matches(':disabled') && !node.closest('[inert],[hidden]') && node.getClientRects().length > 0 && getComputedStyle(node).visibility === 'visible');
+        focusable.sort((a, b) => (a.tabIndex > 0 ? a.tabIndex : Infinity) - (b.tabIndex > 0 ? b.tabIndex : Infinity));
+        const rgba = (value) => {
+            const match = /^rgba?\(([^)]+)\)$/.exec(value);
+            if (!match || match[1].includes('%'))
+                return null;
+            const values = match[1].split(/[,\s/]+/).filter(Boolean).map(Number);
+            if (values.length !== 3 && values.length !== 4 || values.some(value => !Number.isFinite(value)))
+                return null;
+            return [...values.slice(0, 3), values[3] ?? 1];
+        };
+        return Object.fromEntries((runtime?.getDiagnosticTargets() ?? []).map(({ id, element }) => {
+            if (!(element instanceof HTMLElement))
+                return [id, { direction: 'unknown', focusOrder: null, foreground: null, background: null, requiredRatio: 4.5, contrastReason: 'Registered host is not an HTML element' }];
+            const style = getComputedStyle(element), textFill = style.getPropertyValue('-webkit-text-fill-color'), color = textFill ? rgba(textFill) : rgba(style.color);
+            let background = null, reason = element.closest(':disabled,[aria-disabled="true"]') ? 'Text belongs to an inactive control; contrast exemption cannot be evaluated as ordinary text' : null;
+            for (let current = element; current; current = current.parentElement) {
+                const computed = getComputedStyle(current);
+                if (Number(computed.opacity) !== 1 || computed.filter !== 'none' || computed.mixBlendMode !== 'normal' || (computed.backdropFilter && computed.backdropFilter !== 'none')) {
+                    reason ??= 'Opacity, blending, or filters prevent a proven solid-color contrast';
+                    break;
+                }
+                if (!background) {
+                    if (computed.backgroundImage !== 'none') {
+                        reason ??= 'An image or gradient background requires pixel evidence';
+                        break;
+                    }
+                    const value = rgba(computed.backgroundColor);
+                    if (!value) {
+                        reason ??= 'Unsupported background color space';
+                        break;
+                    }
+                    if (value[3] === 1)
+                        background = value.slice(0, 3);
+                    else if (value[3] !== 0) {
+                        reason ??= 'Translucent backgrounds require compositing evidence';
+                        break;
+                    }
+                }
+            }
+            if (textFill && !color)
+                reason ??= 'Unsupported text fill color space';
+            if (!color || color[3] !== 1)
+                reason ??= 'An opaque sRGB foreground was not established';
+            if (!background)
+                reason ??= 'No explicit opaque ancestor background was established';
+            if (parseFloat(style.getPropertyValue('-webkit-text-stroke-width')) > 0)
+                reason ??= 'Text stroke changes glyph contrast and requires pixel evidence';
+            if (style.textShadow !== 'none')
+                reason ??= 'Text shadow changes require pixel evidence';
+            if (element instanceof HTMLInputElement && element.value === '' && element.placeholder)
+                reason ??= 'Placeholder foreground evidence is unavailable';
+            const index = focusable.indexOf(element), large = parseFloat(style.fontSize) >= 24 || (parseFloat(style.fontSize) >= 18.6666667 && Number(style.fontWeight) >= 700);
+            return [id, { direction: style.direction === 'rtl' ? 'rtl' : 'ltr', focusOrder: index < 0 ? null : index, foreground: reason ? null : color.slice(0, 3), background: reason ? null : background, requiredRatio: large ? 3 : 4.5, contrastReason: reason }];
+        }));
+    }));
+    const names = new Map();
+    await cdp.send('Accessibility.enable');
+    const root = await cdp.send('Runtime.evaluate', { expression: 'Object.fromEntries(window.__RN_LAYOUT_BRIDGE__.getDiagnosticTargets().map(target=>[target.id,target.element]))', objectGroup: 'nativemason-accessibility' });
+    if (!root.result.objectId)
+        throw new BridgeFault('STALE_SNAPSHOT', 'Accessibility targets disappeared');
+    try {
+        const properties = await cdp.send('Runtime.getProperties', { objectId: root.result.objectId, ownProperties: true });
+        for (const property of properties.result) {
+            names.set(property.name, null);
+            if (!property.value?.objectId)
+                continue;
+            try {
+                const described = await cdp.send('DOM.describeNode', { objectId: property.value.objectId });
+                const tree = await cdp.send('Accessibility.getPartialAXTree', { backendNodeId: described.node.backendNodeId, fetchRelatives: false });
+                const node = tree.nodes.find(node => node.backendDOMNodeId === described.node.backendNodeId && !node.ignored);
+                names.set(property.name, typeof node?.name?.value === 'string' ? node.name.value : null);
+            }
+            catch { /* Missing AX evidence is explicit; never replace it with an inferred label. */ }
+        }
+    }
+    finally {
+        await cdp.send('Runtime.releaseObjectGroup', { objectGroup: 'nativemason-accessibility' }).catch(() => undefined);
+    }
+    return { ...snapshot, nodes: snapshot.nodes.map(node => {
+            const sample = samples[node.id];
+            if (!sample)
+                return node;
+            const contrast = sample.foreground && sample.background ? { status: 'measured', ratio: solidContrastRatio(sample.foreground, sample.background), requiredRatio: sample.requiredRatio } : { status: 'unavailable', reason: sample.contrastReason ?? 'Solid-style contrast is unavailable' };
+            return { ...node, accessibility: { ...node.accessibility, direction: sample.direction, directionSource: 'browser-computed', browser: { name: names.get(node.id) ?? null, focusOrder: sample.focusOrder, focusOrderSource: 'dom-sequential-estimate', contrast } } };
+        }) };
+}

package/dist/browser/index.d.ts

@@ -0,0 +1,16 @@
+import { type BrowserPort, type DeviceProfile } from '@nativemason/contracts';
+export interface BrowserBridgeOptions {
+    webUrl: string;
+    sessionId: string;
+    scenarioId: string;
+    profile: DeviceProfile;
+    timeoutMs?: number;
+}
+export interface BrowserBridge extends BrowserPort {
+    timings(): {
+        captureMs: number[];
+        trialMs: number[];
+    };
+}
+/** Owns one Chromium context. Runtime changes travel through React Native props, never CSS. */
+export declare function createBrowserBridge(options: BrowserBridgeOptions): Promise<BrowserBridge>;

package/dist/browser/index.js

@@ -0,0 +1,495 @@
+import { captureAccessibilityEvidence } from './accessibility.js';
+import { performance } from 'node:perf_hooks';
+import { chromium } from 'playwright';
+import { BridgeFault, DeviceProfileSchema, ErrorCodeSchema, SpatialSnapshotSchema, LayoutMutationSchema, ScenarioScriptSchema, } from '@nativemason/contracts';
+function applyProfileOverrides(base, overrides) {
+    if (!overrides)
+        return structuredClone(base);
+    if (overrides.fontScale !== undefined)
+        throw new BridgeFault('UNSUPPORTED_PROFILE', 'Chromium font-scale simulation is not supported until rendered text changes can be verified');
+    if (!overrides.orientation || overrides.orientation === base.orientation)
+        return structuredClone(base);
+    const { width, height } = base.window;
+    if (Math.abs(width - height) < 0.01)
+        throw new BridgeFault('UNSUPPORTED_PROFILE', 'Cannot infer the alternate viewport dimensions from a square profile');
+    const insets = overrides.orientation === 'landscape'
+        ? { top: base.insets.left, right: base.insets.top, bottom: base.insets.right, left: base.insets.bottom }
+        : { top: base.insets.right, right: base.insets.bottom, bottom: base.insets.left, left: base.insets.top };
+    const profile = { ...base, orientation: overrides.orientation, window: { width: height, height: width }, root: { x: 0, y: 0, width: height, height: width }, insets };
+    if (insets.left + insets.right >= profile.window.width || insets.top + insets.bottom >= profile.window.height) {
+        throw new BridgeFault('UNSUPPORTED_PROFILE', 'Rotated safe-area insets do not fit the requested orientation');
+    }
+    return profile;
+}
+// CDP models SafeAreaInsets as integer CSS pixels; captured geometry remains fractional.
+function emulatedInsets(profile) { return Object.fromEntries(Object.entries(profile.insets).map(([edge, value]) => [edge, Math.round(value)])); }
+function fault(error, fallback) {
+    if (error instanceof BridgeFault)
+        return error;
+    const message = error instanceof Error ? error.message : String(error);
+    const code = /timeout|timed out/i.test(message) ? 'TIMEOUT' : 'INTERNAL_ERROR';
+    return new BridgeFault(code, `${fallback}: ${message}`);
+}
+function validateSnapshot(value, options) {
+    const parsed = SpatialSnapshotSchema.safeParse(value);
+    if (!parsed.success)
+        throw new BridgeFault('INVALID_INPUT', 'Browser returned an invalid snapshot', parsed.error.flatten());
+    const snapshot = parsed.data;
+    if (snapshot.platform !== 'web' || snapshot.sessionId !== options.sessionId || snapshot.scenarioId !== options.scenarioId) {
+        throw new BridgeFault('STALE_SNAPSHOT', 'Browser snapshot belongs to another platform, session, or scenario');
+    }
+    if (JSON.stringify(snapshot.profile) !== JSON.stringify(options.profile)) {
+        // Parse both objects first to make field insertion order irrelevant.
+        if (JSON.stringify(DeviceProfileSchema.parse(snapshot.profile)) !== JSON.stringify(DeviceProfileSchema.parse(options.profile))) {
+            throw new BridgeFault('STALE_SNAPSHOT', 'Browser profile differs from the configured session profile');
+        }
+    }
+    const ids = snapshot.nodes.map(node => node.id);
+    if (new Set(ids).size !== ids.length)
+        throw new BridgeFault('DUPLICATE_ELEMENT', 'Browser snapshot contains duplicate element IDs');
+    const known = new Set(ids);
+    for (const node of snapshot.nodes) {
+        if (node.parentId !== null && !known.has(node.parentId)) {
+            throw new BridgeFault('MISSING_ELEMENT', `Missing instrumented parent ${node.parentId} for ${node.id}`);
+        }
+        if (node.source && snapshot.revisions[node.source.path] !== node.source.hash) {
+            throw new BridgeFault('STALE_SOURCE', `Source revision mismatch for ${node.id}`);
+        }
+    }
+    return snapshot;
+}
+function identity(snapshot) {
+    return JSON.stringify({
+        generation: snapshot.generation,
+        profile: snapshot.profile,
+        revisions: Object.entries(snapshot.revisions).sort(([a], [b]) => a.localeCompare(b)),
+        nodes: snapshot.nodes.map(node => ({ id: node.id, parentId: node.parentId, source: node.source, pressableState: node.pressableState })).sort((a, b) => a.id.localeCompare(b.id)),
+    });
+}
+function geometry(snapshot) {
+    return JSON.stringify(snapshot.nodes.map(node => ({ id: node.id, rect: node.rect })).sort((a, b) => a.id.localeCompare(b.id)));
+}
+async function waitForAssets(page, timeoutMs) {
+    await page.waitForFunction(() => {
+        const fontsReady = !document.fonts || document.fonts.status === 'loaded';
+        return fontsReady && Array.from(document.images).every(image => image.complete);
+    }, undefined, { timeout: timeoutMs });
+    const broken = await page.evaluate(() => Array.from(document.images).filter(image => image.currentSrc && image.naturalWidth === 0).map(image => image.currentSrc));
+    if (broken.length > 0)
+        throw new BridgeFault('INVALID_INPUT', 'One or more screen images failed to load', { images: broken });
+}
+async function collectDiagnostics(cdp) {
+    const root = await cdp.send('Runtime.evaluate', {
+        expression: 'Object.fromEntries(window.__RN_LAYOUT_BRIDGE__.getDiagnosticTargets().map(target => [target.id, target.element]))',
+        returnByValue: false, objectGroup: 'nativemason-diagnostics',
+    });
+    const objectId = root.result.objectId;
+    if (!objectId)
+        throw new BridgeFault('STALE_SNAPSHOT', 'Runtime did not expose registered DOM targets');
+    try {
+        const properties = await cdp.send('Runtime.getProperties', { objectId, ownProperties: true });
+        const nodes = {};
+        const warnings = [];
+        let domSnapshot;
+        try {
+            domSnapshot = await cdp.send('DOMSnapshot.captureSnapshot', { computedStyles: [], includePaintOrder: true, includeDOMRects: true });
+        }
+        catch { /* Paint order remains nullable. */ }
+        for (const property of properties.result) {
+            const elementObjectId = property.value?.objectId;
+            if (!property.name)
+                continue;
+            if (!elementObjectId) {
+                nodes[property.name] = { clipping: 'unknown', centerHitTest: 'unknown', scrollOverflow: { horizontal: false, vertical: false }, paintOrder: null, fonts: [], lineBoxCount: null };
+                warnings.push({ elementId: property.name, code: 'EVIDENCE_UNAVAILABLE', severity: 'uncertain', message: 'The registered host did not resolve to a DOM element' });
+                continue;
+            }
+            const requested = await cdp.send('DOM.requestNode', { objectId: elementObjectId });
+            if (!requested.nodeId) {
+                nodes[property.name] = { clipping: 'unknown', centerHitTest: 'unknown', scrollOverflow: { horizontal: false, vertical: false }, paintOrder: null, fonts: [], lineBoxCount: null };
+                warnings.push({ elementId: property.name, code: 'EVIDENCE_UNAVAILABLE', severity: 'uncertain', message: 'The registered host has no CDP DOM node' });
+                continue;
+            }
+            const described = await cdp.send('DOM.describeNode', { nodeId: requested.nodeId, depth: 0 });
+            const backendNodeId = described.node.backendNodeId;
+            const diagnostic = await cdp.send('Runtime.callFunctionOn', {
+                objectId: elementObjectId,
+                functionDeclaration: `function(){
+        const r=this.getBoundingClientRect(); const cx=r.left+r.width/2, cy=r.top+r.height/2;
+        let clipped=false, known=true, scrollX=false, scrollY=false;
+        for(let p=this;p&&p.nodeType===1;p=p.parentElement){
+          const s=getComputedStyle(p), pr=p.getBoundingClientRect();
+          if(s.overflowX==='hidden'||s.overflowX==='clip'||s.overflowX==='auto'||s.overflowX==='scroll'){
+            scrollX=scrollX||p.scrollWidth>p.clientWidth; if(p!==this&&(r.left<pr.left||r.right>pr.right))clipped=true;
+          }
+          if(s.overflowY==='hidden'||s.overflowY==='clip'||s.overflowY==='auto'||s.overflowY==='scroll'){
+            scrollY=scrollY||p.scrollHeight>p.clientHeight; if(p!==this&&(r.top<pr.top||r.bottom>pr.bottom))clipped=true;
+          }
+        }
+        const style=getComputedStyle(this); const requested=style.fontFamily.split(',').map(v=>v.trim().replace(/^['"]|['"]$/g,''));
+        let lines=null; if(this.childNodes.length){const range=document.createRange();range.selectNodeContents(this);const rects=[...range.getClientRects()];lines=new Set(rects.map(x=>Math.round(x.top*100)/100)).size;}
+        const failedFonts=[...document.fonts].filter(f=>f.status==='error').map(f=>f.family.replace(/^['"]|['"]$/g,''));
+        return {clipped,known,scrollX,scrollY,cx,cy,requested,lines,failedFonts};
+      }`, returnByValue: true,
+            });
+            const value = diagnostic.result?.value;
+            if (!value)
+                continue;
+            const clipping = value.known ? (value.clipped ? 'confirmed' : 'clear') : 'unknown';
+            let centerHitTest = 'unknown';
+            try {
+                const hit = await cdp.send('DOM.getNodeForLocation', { x: Math.round(value.cx), y: Math.round(value.cy), includeUserAgentShadowDOM: true, ignorePointerEventsNone: false });
+                const hitObject = await cdp.send('DOM.resolveNode', { backendNodeId: hit.backendNodeId, objectGroup: 'nativemason-diagnostics' });
+                if (hitObject.object.objectId) {
+                    const contains = await cdp.send('Runtime.callFunctionOn', {
+                        objectId: elementObjectId,
+                        functionDeclaration: `function(hit){const owns=(ancestor,node)=>{for(let current=node;current;current=current.parentNode||(current.getRootNode&&current.getRootNode().host)||null)if(current===ancestor)return true;return false;};return owns(this,hit)?'clear':owns(hit,this)?'unknown':'confirmed';}`,
+                        arguments: [{ objectId: hitObject.object.objectId }], returnByValue: true,
+                    });
+                    centerHitTest = contains.result.value;
+                }
+            }
+            catch {
+                centerHitTest = 'unknown';
+            }
+            let paintOrder = null;
+            if (domSnapshot) {
+                for (const doc of domSnapshot.documents) {
+                    const index = doc.nodes.backendNodeId?.indexOf(backendNodeId) ?? -1;
+                    const layoutIndex = doc.layout.nodeIndex.indexOf(index);
+                    if (layoutIndex >= 0)
+                        paintOrder = doc.layout.paintOrders?.[layoutIndex] ?? null;
+                }
+            }
+            let fonts = [];
+            try {
+                const platformFonts = await cdp.send('CSS.getPlatformFontsForNode', { nodeId: requested.nodeId });
+                fonts = platformFonts.fonts.map((font) => ({ family: font.familyName, glyphCount: font.glyphCount, isCustom: font.isCustomFont ?? null }));
+            }
+            catch { /* Font evidence can be unavailable for non-text hosts. */ }
+            const lineBoxCount = value.lines ?? null;
+            nodes[property.name] = { clipping, centerHitTest, scrollOverflow: { horizontal: value.scrollX, vertical: value.scrollY }, paintOrder, fonts, lineBoxCount };
+            if (clipping === 'confirmed')
+                warnings.push({ elementId: property.name, code: 'CLIPPED', severity: 'confirmed', message: 'The registered element is clipped by an ancestor' });
+            if (centerHitTest === 'confirmed')
+                warnings.push({ elementId: property.name, code: 'OCCLUDED', severity: 'confirmed', message: 'A different DOM node receives the center-point hit test' });
+            const genericFamilies = new Set(['arial', 'sans-serif', 'serif', 'monospace', 'system-ui', '-apple-system', 'blinkmacsystemfont', 'segoe ui', 'roboto', 'helvetica', 'noto sans']);
+            const customRequested = value.requested.some((family) => !genericFamilies.has(family.toLowerCase()));
+            if (customRequested && !fonts.some(font => value.requested.some((family) => font.family.toLowerCase() === family.toLowerCase()))) {
+                const failed = value.requested.some((family) => value.failedFonts.some((name) => name.toLowerCase() === family.toLowerCase()));
+                warnings.push({ elementId: property.name, code: 'FONT_LOAD_FAILED', severity: failed ? 'confirmed' : 'uncertain', message: failed ? 'The requested custom FontFace has an error status' : 'Chromium rendered glyphs with a family other than the first requested custom family' });
+            }
+            if (clipping === 'unknown' || centerHitTest === 'unknown')
+                warnings.push({ elementId: property.name, code: 'EVIDENCE_UNAVAILABLE', severity: 'uncertain', message: 'One or more browser diagnostics could not be established' });
+        }
+        return { nodes, warnings };
+    }
+    finally {
+        await cdp.send('Runtime.releaseObjectGroup', { objectGroup: 'nativemason-diagnostics' }).catch(() => undefined);
+    }
+}
+/** Owns one Chromium context. Runtime changes travel through React Native props, never CSS. */
+export async function createBrowserBridge(options) {
+    const profile = DeviceProfileSchema.parse(options.profile);
+    if (profile.fontScale !== 1)
+        throw new BridgeFault('UNSUPPORTED_PROFILE', 'Chromium font-scale simulation has no rendered-text proof');
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    let browser;
+    try {
+        browser = await chromium.launch({ headless: true });
+        const context = await browser.newContext({
+            viewport: { width: Math.round(profile.window.width), height: Math.round(profile.window.height) },
+            deviceScaleFactor: profile.pixelRatio,
+            reducedMotion: 'reduce',
+        });
+        const page = await context.newPage();
+        const cdp = await context.newCDPSession(page);
+        await cdp.send('DOM.enable');
+        await cdp.send('DOMSnapshot.enable');
+        await cdp.send('CSS.enable');
+        // Emulate the environment, so nested safe-area providers observe the same profile.
+        await cdp.send('Emulation.setSafeAreaInsetsOverride', { insets: emulatedInsets(profile) });
+        page.setDefaultTimeout(timeoutMs);
+        await page.goto(options.webUrl, { waitUntil: 'domcontentloaded', timeout: timeoutMs });
+        await cdp.send('DOM.getDocument', { depth: -1, pierce: true });
+        await page.waitForFunction(() => !!window.__RN_LAYOUT_BRIDGE__, undefined, { timeout: timeoutMs });
+        await page.evaluate(input => window.__RN_LAYOUT_BRIDGE__.configure(input), {
+            sessionId: options.sessionId,
+            scenarioId: options.scenarioId,
+            profile,
+        });
+        await waitForAssets(page, timeoutMs);
+        const captureMs = [];
+        const trialMs = [];
+        let closed = false;
+        let baseline;
+        let activeTrial = false;
+        let activeProfile = profile;
+        let navigation = 0;
+        let baselineNavigation = 0;
+        page.on('framenavigated', frame => { if (frame === page.mainFrame())
+            navigation++; });
+        async function callRuntime(operation, id, patch, mutations) {
+            let timer;
+            try {
+                const result = await Promise.race([
+                    page.evaluate(async (input) => {
+                        try {
+                            const runtime = window.__RN_LAYOUT_BRIDGE__;
+                            if (!runtime)
+                                return { ok: false, code: 'STALE_SNAPSHOT', message: 'Screen runtime is no longer mounted' };
+                            const value = input.operation === 'capture' ? await runtime.capture()
+                                : input.operation === 'resetTrial' ? await runtime.resetTrial()
+                                    : input.operation === 'applyTrialBatch' ? runtime.applyTrialBatch ? await runtime.applyTrialBatch(input.mutations) : input.mutations.length === 1 ? await runtime.applyTrial(input.mutations[0].elementId, input.mutations[0].patch) : (() => { throw new Error('Runtime does not support batch mutations; update its development bundle'); })()
+                                        : await runtime.applyTrial(input.id, input.patch);
+                            return { ok: true, value };
+                        }
+                        catch (error) {
+                            const failure = error;
+                            return { ok: false, code: failure?.code, message: String(failure?.message ?? error) };
+                        }
+                    }, { operation, id, patch, mutations }),
+                    new Promise((_resolve, reject) => {
+                        timer = setTimeout(() => reject(new BridgeFault('TIMEOUT', `Browser runtime ${operation} timed out`)), timeoutMs);
+                    }),
+                ]);
+                if (!result.ok) {
+                    const code = ErrorCodeSchema.safeParse(result.code);
+                    throw new BridgeFault(code.success ? code.data : 'INTERNAL_ERROR', result.message);
+                }
+                return result.value;
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+            }
+        }
+        function ensureOpen() {
+            if (closed || !browser.isConnected())
+                throw new BridgeFault('SESSION_NOT_FOUND', 'Browser session is closed');
+        }
+        async function readStable() {
+            ensureOpen();
+            const started = performance.now();
+            await waitForAssets(page, timeoutMs);
+            let previous;
+            while (performance.now() - started < timeoutMs) {
+                const raw = await callRuntime('capture');
+                const parsed = SpatialSnapshotSchema.parse(raw);
+                const snapshot = validateSnapshot({ ...parsed, webDiagnostics: await collectDiagnostics(cdp) }, { ...options, profile: activeProfile });
+                if (snapshot.status === 'stable' && previous?.status === 'stable' && identity(previous) === identity(snapshot) && geometry(previous) === geometry(snapshot))
+                    return snapshot;
+                previous = snapshot;
+                await page.evaluate(() => new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(() => resolve()))));
+            }
+            throw new BridgeFault('UNSTABLE_LAYOUT', 'Screen did not produce two matching stable layout captures');
+        }
+        async function setProfile(overrides) {
+            const nextProfile = applyProfileOverrides(profile, overrides);
+            const profileChanged = JSON.stringify(nextProfile) !== JSON.stringify(activeProfile);
+            if (!profileChanged)
+                return;
+            {
+                activeTrial = false;
+                baseline = undefined;
+                await callRuntime('resetTrial');
+                await cdp.send('Emulation.setSafeAreaInsetsOverride', { insets: emulatedInsets(nextProfile) });
+                await page.setViewportSize({ width: Math.round(nextProfile.window.width), height: Math.round(nextProfile.window.height) });
+                await cdp.send('Emulation.setDeviceMetricsOverride', { width: Math.round(nextProfile.window.width), height: Math.round(nextProfile.window.height), deviceScaleFactor: nextProfile.pixelRatio, mobile: true, screenOrientation: { type: nextProfile.orientation === 'landscape' ? 'landscapePrimary' : 'portraitPrimary', angle: nextProfile.orientation === 'landscape' ? 90 : 0 } });
+            }
+            activeProfile = nextProfile;
+            await page.evaluate(input => window.__RN_LAYOUT_BRIDGE__.configure(input), { sessionId: options.sessionId, scenarioId: options.scenarioId, profile: activeProfile });
+        }
+        async function trialBatch(mutations, overrides) {
+            const started = performance.now();
+            ensureOpen();
+            if (!mutations.length)
+                throw new BridgeFault('INVALID_INPUT', 'A trial needs at least one mutation');
+            const parsed = mutations.map(mutation => { const result = LayoutMutationSchema.safeParse(mutation); if (!result.success)
+                throw new BridgeFault('INVALID_INPUT', result.error.message); return result.data; });
+            if (new Set(parsed.map(m => m.elementId)).size !== parsed.length)
+                throw new BridgeFault('INVALID_INPUT', 'A batch must contain each element only once');
+            if (!baseline)
+                throw new BridgeFault('STALE_SNAPSHOT', 'Capture a baseline before trying a layout mutation');
+            try {
+                await setProfile(overrides);
+                if (!baseline)
+                    throw new BridgeFault('STALE_SNAPSHOT', 'Profile changed; capture a fresh profile-bound baseline');
+                const before = await readStable();
+                if (navigation !== baselineNavigation || identity(before) !== identity(baseline)) {
+                    throw new BridgeFault('STALE_SNAPSHOT', 'Source, profile, navigation, or mounted elements changed since the baseline');
+                }
+                for (const mutation of parsed)
+                    if (!before.nodes.some(node => node.id === mutation.elementId))
+                        throw new BridgeFault('MISSING_ELEMENT', `Unknown element ${mutation.elementId}`);
+                await callRuntime('resetTrial');
+                activeTrial = false;
+                const reset = await readStable();
+                if (identity(reset) !== identity(baseline) || geometry(reset) !== geometry(baseline)) {
+                    throw new BridgeFault('STALE_SNAPSHOT', 'Reset layout no longer matches the captured baseline');
+                }
+                await callRuntime('applyTrialBatch', undefined, undefined, parsed);
+                activeTrial = true;
+                const snapshot = await readStable();
+                if (identity(snapshot) !== identity(baseline))
+                    throw new BridgeFault('STALE_SNAPSHOT', 'The mounted screen changed while applying the trial');
+                return snapshot;
+            }
+            catch (error) {
+                // A failed candidate must never leave a partially applied trial behind.
+                await callRuntime('resetTrial').catch(() => undefined);
+                activeTrial = false;
+                throw fault(error, 'Could not trial browser layout');
+            }
+            finally {
+                trialMs.push(performance.now() - started);
+            }
+        }
+        return {
+            async capture(overrides) {
+                const started = performance.now();
+                try {
+                    await setProfile(overrides);
+                    const snapshot = await readStable();
+                    if (!activeTrial) {
+                        baseline = snapshot;
+                        baselineNavigation = navigation;
+                    }
+                    return snapshot;
+                }
+                catch (error) {
+                    throw fault(error, 'Could not capture browser layout');
+                }
+                finally {
+                    captureMs.push(performance.now() - started);
+                }
+            },
+            trial(elementId, patch, overrides) { return trialBatch([{ elementId, patch }], overrides); },
+            trialBatch,
+            async resetTrial() {
+                ensureOpen();
+                try {
+                    await callRuntime('resetTrial');
+                    activeTrial = false;
+                }
+                catch (error) {
+                    throw fault(error, 'Could not reset browser trial');
+                }
+            },
+            async runScenario(script) {
+                ensureOpen();
+                const parsed = ScenarioScriptSchema.parse(script);
+                if (parsed.scenarioId !== options.scenarioId)
+                    throw new BridgeFault('INVALID_INPUT', 'Scenario script must match the session scenario');
+                await callRuntime('resetTrial');
+                activeTrial = false;
+                baseline = undefined;
+                for (const action of [...parsed.reset, ...parsed.actions]) {
+                    if (action.type === 'navigate') {
+                        const url = new URL(action.url, options.webUrl);
+                        if (url.origin !== new URL(options.webUrl).origin)
+                            throw new BridgeFault('INVALID_INPUT', 'Scenario navigation must remain on the application origin');
+                        await page.goto(url.href, { waitUntil: 'domcontentloaded', timeout: timeoutMs });
+                        await page.waitForFunction(() => !!window.__RN_LAYOUT_BRIDGE__, undefined, { timeout: timeoutMs });
+                        await page.evaluate(input => window.__RN_LAYOUT_BRIDGE__.configure(input), { sessionId: options.sessionId, scenarioId: options.scenarioId, profile: activeProfile });
+                        continue;
+                    }
+                    if (action.type === 'hook') {
+                        await page.evaluate(async (input) => {
+                            const runtime = window.__RN_LAYOUT_BRIDGE__;
+                            if (runtime?.runHook) {
+                                await runtime.runHook(input.name, input.value);
+                                return;
+                            }
+                            const hooks = window.__NATIVEMASON_SCENARIO_HOOKS__;
+                            if (!hooks?.[input.name])
+                                throw new Error(`Unknown scenario hook ${input.name}`);
+                            await hooks[input.name](input.value);
+                        }, action);
+                        continue;
+                    }
+                    if (action.type === 'keyboard') {
+                        if (action.visible)
+                            throw new BridgeFault('UNSUPPORTED_PROFILE', 'Chromium cannot establish native software keyboard visibility');
+                        await page.keyboard.press('Escape');
+                        await page.evaluate(() => { const focused = document.activeElement; if (focused instanceof HTMLElement)
+                            focused.blur(); });
+                        continue;
+                    }
+                    if (action.type === 'wait') {
+                        await page.waitForFunction(id => {
+                            const target = window.__RN_LAYOUT_BRIDGE__?.getDiagnosticTargets().find(item => item.id === id)?.element;
+                            if (!(target instanceof Element))
+                                return false;
+                            const box = target.getBoundingClientRect();
+                            return box.width > 0 && box.height > 0 && getComputedStyle(target).visibility !== 'hidden';
+                        }, action.elementId, { timeout: action.timeoutMs });
+                        continue;
+                    }
+                    const handle = await page.evaluateHandle(id => { const target = window.__RN_LAYOUT_BRIDGE__?.getDiagnosticTargets().find(item => item.id === id)?.element; return target instanceof Element ? target : null; }, action.elementId);
+                    try {
+                        const element = handle.asElement();
+                        if (!element)
+                            throw new BridgeFault('MISSING_ELEMENT', `Scenario target ${action.elementId} is unavailable`);
+                        if (action.type === 'press') {
+                            if (action.phase === 'down') {
+                                await element.scrollIntoViewIfNeeded();
+                                const box = await element.boundingBox();
+                                if (!box)
+                                    throw new BridgeFault('MISSING_ELEMENT', 'Held pointer target has no box');
+                                await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2);
+                                await page.mouse.down();
+                            }
+                            else
+                                await page.mouse.up();
+                        }
+                        else if (action.type === 'tap')
+                            await element.click();
+                        else if (action.type === 'input') {
+                            if (action.mode === 'append') {
+                                await element.focus();
+                                await element.press('ControlOrMeta+End');
+                                await page.keyboard.insertText(action.text);
+                            }
+                            else
+                                await element.fill(action.text);
+                        }
+                        else if (action.type === 'swipe')
+                            await element.evaluate((node, direction) => { if (!(node instanceof Element))
+                                throw new Error('Swipe target is not an element'); node.scrollBy(direction === 'LEFT' ? node.clientWidth : direction === 'RIGHT' ? -node.clientWidth : 0, direction === 'UP' ? node.clientHeight : direction === 'DOWN' ? -node.clientHeight : 0); }, action.direction);
+                        else if (action.type === 'scroll')
+                            await element.evaluate((node, delta) => { if (!(node instanceof Element))
+                                throw new Error('Scroll target is not an element'); node.scrollBy(delta.x, delta.y); }, action);
+                    }
+                    finally {
+                        await handle.dispose();
+                    }
+                }
+                await readStable();
+            },
+            async captureAccessibility() {
+                const snapshot = await readStable(), evidence = await captureAccessibilityEvidence(page, cdp, snapshot), after = await readStable();
+                if (identity(snapshot) !== identity(after) || geometry(snapshot) !== geometry(after))
+                    throw new BridgeFault('STALE_SNAPSHOT', 'Layout changed during accessibility capture');
+                return SpatialSnapshotSchema.parse({ ...evidence, snapshotId: after.snapshotId });
+            },
+            async screenshot() {
+                ensureOpen();
+                await readStable();
+                return page.screenshot({ type: 'png', fullPage: false, animations: 'disabled', scale: 'device' });
+            },
+            async close() {
+                if (closed)
+                    return;
+                closed = true;
+                await cdp.detach().catch(() => undefined);
+                await browser.close();
+            },
+            timings() { return { captureMs: [...captureMs], trialMs: [...trialMs] }; },
+        };
+    }
+    catch (error) {
+        await browser?.close().catch(() => undefined);
+        throw fault(error, 'Could not open Chromium session');
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { BridgeApplication } from './application/index.js';
+import { createMcpServer } from './mcp/index.js';
+if (process.argv[2] === 'init') {
+    const { initialize } = await import('./init/index.js');
+    const root = process.argv.find((arg, index) => index > 2 && !arg.startsWith('--')) ?? process.cwd();
+    console.log(JSON.stringify(await initialize(root, process.argv.includes('--dry-run'), { textProbes: process.argv.includes('--text-probes') }), null, 2));
+    process.exit(0);
+}
+if (process.argv.includes('--help')) {
+    console.log('nativemason [init [project-root] [--dry-run]]\nWithout arguments, starts the MCP stdio server.');
+    process.exit(0);
+}
+const app = new BridgeApplication();
+const server = createMcpServer(app);
+let closing = false;
+async function close() { if (closing)
+    return; closing = true; await app.close(); await server.close(); }
+process.once('SIGINT', () => { void close().finally(() => process.exit(0)); });
+process.once('SIGTERM', () => { void close().finally(() => process.exit(0)); });
+process.stdin.once('end', () => { void close(); });
+await server.connect(new StdioServerTransport());

package/dist/core/accessibility.d.ts

@@ -0,0 +1,5 @@
+import type { AccessibilityFinding, SpatialSnapshot } from '@nativemason/contracts';
+/** WCAG relative luminance for previously validated opaque sRGB channels. */
+export declare function solidContrastRatio(foreground: readonly number[], background: readonly number[]): number;
+/** Bounded evidence checks; never infers native assistive-technology behavior. */
+export declare function inspectAccessibility(snapshot: SpatialSnapshot): AccessibilityFinding[];